1171 files changed, 528571 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/411toppm.1 b/upstream/mageia-cauldron/man1/411toppm.1
new file mode 100644
index 00000000..ed1d5533
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/411toppm.1
@@ -0,0 +1,71 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "411toppm User Manual" 0 "03 March 2001" "netpbm documentation"
+
+.SH NAME
+411toppm - convert Sony Mavica .411 image to PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fB411toppm\fP
+[\fB-width \fP\fIwidth\fP]
+[\fB-height \fP\fIheight\fP]
+[\fI411file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+ \fB411toppm\fP reads a .411 file, such as from a Sony Mavic
+camera, and converts it to a PPM image as output.
+.PP
+Output is to Standard Output.
+.PP
+The originator of this program and decipherer of the .411 format,
+Steve Allen
+<\fIsla@alumni.caltech.edu\fP>,
+has this to say about the
+utility of this program: "There's so little image in a 64x48 thumbnail
+(especially when you have the full size JPG file) that the only point
+in doing this was to answer the implicit challenge posed by the manual
+stating that only the camera can use these files."
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fB411toppm\fP recognizes the following
+command line options:
+.PP
+All options may be abbreviated to the shortest unique prefix.
+
+
+.TP
+\fB-width\fP
+The width (number of columns) of the input image.  Default is 64.
+.TP
+\fB-height\fP
+The height (number of rows) of the input image.  Default is 48.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/411toppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/abc2abc.1 b/upstream/mageia-cauldron/man1/abc2abc.1
new file mode 100644
index 00000000..2d501102
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/abc2abc.1
@@ -0,0 +1,123 @@
+.TH ABC2ABC 1 "07 June 2011"
+.SH NAME
+abc2abc \- a simple abc checker/re-formatter/transposer
+.SH SYNOPSIS
+\fBabc2abc\fP \fIfile\fP [ \fB-s\fP ] [ \fB-n\fP ] [ \fB-b\fP ]
+[ \fB-r\fP ] [ \fB-e\fP ] [ \fB-t \fP\fIsemitones\fP ] [ \fB-nda\fP ]
+[ \fB-u\fP ] [ \fB-d\fP ] [ \fB-v\fP ] [ \fB-V\fP\fIvoice number\fP]
+[\fB-P\fP\fivoice number\fp] [\fB-nokeys\fP]
+[ \fB-nokeyf\fP] [ \fB-usekey\fP\fI(sharps/flats)\fP]
+[\fB-useclef\fP\fI(treble/clef)\fP] [ \fB-OCC\fP ]
+.SH "DESCRIPTION"
+.PP
+.B abc2abc
+is a simple abc checker/re-formatter/transposer.
+It will check whether the \fIfile\fP given on the command line
+obeys basic abc syntax.
+.PP
+If you want to check an abc tune,
+it is recommended that you use
+.B abc2midi
+with the \fB-c\fP option.
+This performs extra checks that
+.B abc2abc
+does not do.
+.PP
+The output of
+.B abc2abc
+goes to standard output.
+Use redirection to save it to a file.
+.SH OPTIONS
+.TP
+.B \-s
+Rework spacing in the file (which affects how notes are beamed together
+when the music is printed out). This option does not appear to be working
+correctly.
+.TP
+.BI \-n " X"
+Reformats the abc file with line breaks every \fIX\fP bars.
+.TP
+.B \-b
+Don't do bar checking.
+.TP
+.B \-r
+Don't do repeat checking.
+.TP
+.B \-e
+Don't report errors.
+.TP
+.BI \-t " n"
+Transpose tune by \fIn\fP semitones. This function will also
+work with K: none or one of \-nokeys or \-nokeyf.
+If a voice is assigned to channel 10 (drum channel) using a
+%%MIDI channel 10
+command, then this voice is never transposed.
+
+.TP
+.B \-nda
+Convert double accidentals in guitar chord to another chord though
+strictly not correct.
+.TP
+.B \-u
+Update notation; the older notation \fB+ +\fP for chords is replaced by 
+\fB[]\fP and \fBs s\fP for slurs is replaced by \fB()\fP.
+.TP
+.B \-OCC
+Accept the old notation for chord. Normally this is turned off,
+since it conflicts with abc draft standard version 2.0 for
+decorations (eg. +crescendo(+).
+.TP
+.B \-d
+Re-notate the tune with all note lengths doubled. The unit length specified by the L: field
+command is halved (e.g. L:1/8 to L:1/16).
+.TP
+.B \-v
+Re-notate the tune with all note lengths halved. The unit length specified by the L: field
+command is doubled (e.g. L:1/8 to L:1/4).
+.TP
+.B \-ver
+Prints version number and exits.
+.TP
+.BI \-V " X[,Y...]"
+For multivoiced abc files (i.e. contains V: field commands), only voices \fIX[,Y,...]\fP are copied.
+.TP
+.BI \-P " X,[,Y...]"
+For multivoiced abc files (i.e. contains V: field commands), all voices except \fIX[,Y...]\fP remain the same. Voices X,Y... are modified according the other runtime parameters. 
+.TP
+.BI \-X " n"
+For a file containing many tunes, the X: reference numbers are renumbered sequentially
+starting from number \fIn\fP.
+.TP
+.BI \-xref " n"
+Only the tune with X: n is processed.
+.TP
+.B \-nokeys
+No key signature will be assumed. Instead, sharps and naturals will
+be placed wherever they are needed.
+.TP
+.B \-nokeyf
+No key signature will be assumed. Instead, flats and naturals will
+be placed wherever they are needed.
+.TP
+.B \-usekey " sf
+This will force abc2abc to output the notes in the key signature
+keys[sf] where sf specifies the number of flats (\-negative) or 
+sharps (+positive) in the key signature. It is a number between
+\-5 and +5 inclusive.
+.TP
+.B \-useclef
+This works with only the -t (transpose) and provided the abc
+file does not already have a clef command in the K: field. It
+does not support voices.
+.PP
+* Normally abc2abc will convert the deprecated notation for
+decorations (eg. !ppp!) to the abc version 2.0 draft standard (eg. +ppp+).
+If you do not wish to change to this standard include the \-OCC flag.
+
+.SH "SEE ALSO"
+.IR abcmtex "(1), " abc2midi "(1), " midi2abc "(1), " mftext "(1)"
+.SH AUTHOR
+This manual page was written by Anselm Lingnau <lingnau@tm.informatik.uni-frankfurt.de> and is now supported by Seymour Shlien <fy733@ncf.ca>
+for the GNU/Linux system.
+.SH VERSION
+This man page describes abc2abc version 2.04 from January 22 2020.
diff --git a/upstream/mageia-cauldron/man1/abc2ly.1 b/upstream/mageia-cauldron/man1/abc2ly.1
new file mode 100644
index 00000000..36cc3427
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/abc2ly.1
@@ -0,0 +1,43 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH ABC2LY "1" "January 2024" "abc2ly (LilyPond) 2.24.3" "User Commands"
+.SH NAME
+abc2ly \- manual page for abc2ly (LilyPond) 2.24.3
+.SH SYNOPSIS
+.B abc2ly
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR
+.SH DESCRIPTION
+abc2ly converts ABC music files (see
+http://abcnotation.com/abc2mtex/abc.txt) to LilyPond input.
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to FILE
+.TP
+\fB\-s\fR, \fB\-\-strict\fR
+be strict about success
+.TP
+\fB\-b\fR, \fB\-\-beams\fR
+preserve ABC's notion of beams
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress progress messages
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH "SEE ALSO"
+The full documentation for
+.B abc2ly
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B abc2ly
+programs are properly installed at your site, the command
+.IP
+.B info abc2ly
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/abc2midi.1 b/upstream/mageia-cauldron/man1/abc2midi.1
new file mode 100644
index 00000000..f5488955
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/abc2midi.1
@@ -0,0 +1,568 @@
+.TH ABC2MIDI 1 "June 2017"
+.SH NAME
+\fBabc2midi\fP \- converts abc file to MIDI file(s)
+.SH SYNOPSIS
+abc2midi \fIinfile\fP [\fIrefnum\fP] [\-c] [\-v] [\-ver] [\-t] [\-n limit] [\-CS] [\-quiet] [\-silent] [\-Q tempo] [\-NFNP] [\-NFER] [\-NGRA] [\-NGUI] [\-STFW] [\-OCC] [\-NCOM] [\-HARP] [\-BF] [\-TT] [\-o outfile] \-CSM [filename]
+.SH DESCRIPTION
+ The default action is to write a MIDI file for each abc tune
+ with the filename <stem>N.mid, where <stem> is the filestem
+ of the abc file and N is the tune reference number. If the \-o
+ option is used, only one file is written. This is the tune
+ specified by the reference number or, if no reference number
+ is given, the first tune in the file.
+.SH OPTIONS
+.TP
+.B \fIrefnum\fP
+process the tune with reference number \fIrefnum\fP
+.TP
+.B -c
+selects checking only
+.TP
+.B -v n
+selects verbose option where n is the level (optional)
+.TP
+.B -ver
+prints version number and exits
+.TP
+.B -t
+selects filenames derived from tune titles
+.TP
+.B -CS
+use 2:1 instead of 3:1 for broken rhythms
+.TP
+.B -quiet
+Suppresses some common warnings.
+.TP
+.B -silent
+Suppresses other messages.
+.TP
+.B -n \fI X\fP
+limits the length of the file name stem to X characters
+.TP
+.B -Q \fI tempo\fP
+sets the default tempo in quarter notes per minute if it was not
+specified in the abc header.
+.TP
+.B -NFNP
+Ignore any dynamic indications !f! !ff! etc.
+.TP
+.B -NFER
+Ignore any fermata indications (eg H or !fermata!).
+.TP
+.B -NGRA
+Ignore any grace notes.
+.TP
+.B -NGUI
+Ignore any guitar chords enclosed in double quotes.
+.TP
+.B -STFW
+Place lyric text in separate MIDI tracks.
+.TP
+.B -NCOM
+Suppress some comments in the output MIDI file.
+.TP
+.B -OCC
+Accept old chord convention (eg +D2G2+ instead of [DG]2).
+.TP
+.B -BF
+BarFly mode: invokes a stress model if possible.
+.TP
+.B -HARP
+Roll ornaments=roll are generated for the harpist (same pitch)
+.TP
+.B -TT
+Changes the tuning from A = 440 Hz.
+.TP
+.B -o \fIoutfile\fP
+write output to \fIoutfile\fP
+.TP
+.B -CSM \fIinfile\fP
+load a set of custom stress modes from a file
+.SH FEATURES
+.PP
+* Broken rhythms (>, <), chords, n-tuples, slurring, ties, staccatto notes,
+repeats, in-tune tempo/length/time signature changes are all supported.
+.PP
+* R:hornpipe or r:hornpipe is recognized and note timings are adjusted to
+give a broken rhythm (ab is converted to a>b).
+.PP
+* Most errors in the abc input will generate a suitable error message in
+the output and the converter keeps going.
+.PP
+* Comments and text fields in the abc source are converted to text events
+in the MIDI output
+.PP
+* If guitar chords are present, they are used to generate an accompaniment
+in the MIDI output.
+.PP
+* If there are mis-matched repeat signs in the abc, the program attempts to
+fix them. However, it will not attempt this if a multi-part tune 
+description has been used or if multiple voices are in use.
+.PP
+* Karaoke MIDI files can be generated by using the w: field to include 
+lyrics.
+.PP
+* Nonnumeric voice id's, eg. V: soprano, as proposed for the new
+abc standard is accepted.
+.PP
+* Invisible rests specified by x are treated the same way as
+normal rests (z).
+.PP
+* Decorations may be indicated using either the deprecated
+notation (eg. !fermata!) or the standard version 2.0 notation
+(eg. +fermata+).
+.PP
+.SH LIMITATIONS
+* No field is inherited from above the X: field of the tune.
+
+
+.SH "ABC SYNTAX EXTENSIONS"
+* There are some extensions to the abc syntax of the form
+.PP
+%%MIDI channel n
+.PP
+These control channel and program selection, transposing and various
+other features of abc2midi.
+.PP
+Each of these should appear on a line by itself. All of them are allowed
+within the abc tune body. By using these in combination with the part
+notation, one can, for example, play a part transposed or in a different key.
+.PP
+The idea behind this syntax is that other programs will treat it as a
+comment and ignore it.
+.PP
+%%MIDI channel n
+.PP
+selects melody channel n (in the range 1-16).
+.PP
+%%MIDI program [c] n
+.PP
+selects program n (in the range 0-127) on channel c. If c is not given, the
+program is selected on the current melody channel. Most modern tone
+generators follow the General MIDI standard which defines the instrument
+type for each program number.
+.PP
+%%MIDI beat a b c n
+.PP
+controls the way note velocities are selected. The first note in a bar has
+velocity a. Other "strong" notes have velocity b and all the rest have velocity
+c. a, b and c must be in the range 0-127. The parameter n determines which
+notes are "strong". If the time signature is x/y, then each note is given
+a position number k = 0, 1, 2 .. x-1 within each bar. Note that the units for
+n are not the unit note length. If k is a multiple of n, then the note is
+"strong". The volume specifiers !ppp! to !fff! are equivalent to the
+following :
+.P
+!ppp! = %%MIDI beat 30 20 10 1
+.br
+!pp!  = %%MIDI beat 45 35 20 1
+.br
+!p!   = %%MIDI beat 60 50 35 1
+.br
+!mp!  = %%MIDI beat 75 65 50 1
+.br
+!mf!  = %%MIDI beat 90 80 65 1
+.br
+!f!   = %%MIDI beat 105 95 80 1
+.br
+!ff!  = %%MIDI beat 120 110 95 1
+.br
+!fff! = %%MIDI beat 127 125 110 1
+
+.PP
+%%MIDI beatmod n
+.PP
+Increments by n (or decrements if n is negative) the velocities a, b and
+c described above. The instructions !crescendo(! and !crescendo)!
+are equivalent to inserting a %%MIDI beatmod 15 wherever they
+occur. (Alternatively you can use !<(! and !<)!.) Similarly the
+instructions !diminuendo(! and !diminuendo)! are equivalent
+to %%MIDI beatmod \-15.
+
+.PP
+%%MIDI deltaloudness n
+.PP
+where n is a small positive number.  By default the crescendo and
+diminuendo instructions modify the beat variables a, b, and c by
+15 velocity units. This instruction allows you to set this default
+to value n.
+
+.PP
+%%MIDI nobeataccents
+.PP
+For instruments such as church organ that have no greatly emphasized beat notes,
+using this will force use of the 'b' velocity (see %%MIDI beat)
+for every note irrespective of position in the bar.  This allows dynamics
+(ff, f, etc) to be used in the normal way.
+.PP
+%%MIDI beataccents
+.PP
+Revert to emphasizing notes the the usual way. (default)
+
+.PP
+%%MIDI beatstring <string of f, m and p>
+.PP
+This provides an alternative way of specifying where the strong and weak
+stresses fall within a bar. 'f' means velocity a (normally strong), 'm'
+means velocity b (medium velocity) and 'p' means velocity c (soft velocity).
+For example, if the time signature is 7/8 with stresses on the first, fourth
+and sixth notes in the bar, we could use the following
+.PP
+%%MIDI beatstring fppmpmp
+.PP
+%%MIDI transpose n
+.PP
+transposes the output by the specified number of semitones. n may be
+positive or negative.
+.PP
+%%MIDI rtranspose n
+.PP
+Relative transpose by the specified number of semitones. i.e.
+%%MIDI transpose a followed by %%MIDI rtranspose b results in a
+transposition of a+b. %%MIDI transpose b will result in a transposition
+of b semitones, regardless of any previous transposition.
+.PP
+%%MIDI c n
+.PP
+specifies the MIDI pitch which corresponds to c. The default is 60. This
+number should normally be a multiple of 12.
+.PP
+%%MIDI grace a/b
+.PP
+sets the fraction of the next note that grace notes will take up. a
+must be between 1 and b-1. The grace notes may not sound natural
+in this approach, since the length of the individual grace notes
+vary with the complexity of the grace and the length of the
+following note. A different approach (which is now the default)
+assumes that the grace notes always have a fixed duration.
+To use the other approach you would specify,
+
+%%MIDI gracedivider b
+
+where b specifies how many parts to divide the unit length
+specified by the L: field command. For example if b = 4 and
+L: = 1/8, then every grace note would be 1/(8*4) or a 32nd
+note. Time would be stolen from the note to which the grace
+notes are applied. If that note is not long enough to handle
+the grace then the grace notes would be assigned 0 duration.
+
+
+
+.PP
+%%MIDI chordname name n1 n2 n3 n4 n5 n6
+.PP
+Defines how to play a guitar chord called "name". n1 is usually 0 and
+n2, n3 to n6 give the pitches of the other notes in semitones relative
+to the root note. There may be fewer than 6 notes in the chord, but not
+more.If "name" is already defined, this command re-defines it. Unlike
+most other commands, chordname definitions stay in effect from where they
+are defined to the end of the abc file. The following illustrates how
+m, 7, m7 and maj7 could be set up if they were not already defined.
+.PP
+%%MIDI chordname m 0 3 7
+.br
+%%MIDI chordname 7 0 4 7 10
+.br
+%%MIDI chordname m7 0 3 7 10
+.br
+%%MIDI chordname maj7 0 4 7 11
+.PP
+%%MIDI gchord string
+.PP
+sets up how guitar chords are generated. The string is a sequence made of
+of z's, c's  f's and b's for rests, chords, fundamental and fundamental
+plus chord notes respectively.  This specifies how each bar is to be played.
+An optional length is allowed to follow the z's, c's f's and b's  e.g. czf2zf3.
+If the abc contains guitar chords, then abc2midi automatically adds chords and
+fundamentals after encountering the first guitar chord. It keeps using that
+chord until a new chord is specified in the abc. Whenever the M: field is
+encountered in the abc, an appropriate default string is set :
+.P
+For 2/4 or 4/4 time default is equivalent to :
+%%MIDI gchord fzczfzcz
+.P
+For 3/4 time default is equivalent to :
+%%MIDI gchord fzczcz
+.P
+For 6/8 time default is equivalent to :
+%%MIDI gchord fzcfzc
+.P
+For 9/8 time default is equivalent to :
+%%MIDI gchord fzcfzcfzc
+.P
+
+The gchord command has been extended to allow you to play
+the individual notes comprising the guitar chord. This allows
+you to play broken chords or arpeggios. The new codes g,h,i,j,
+G,H,I,J reference the individual notes starting from the
+lowest note of the chord (not necessarily the root in the
+case of inversions). For example for the C major chord, g
+refers to C, h refers to E and i refers to G. For a gchord
+command such as,
+.P
+%%MIDI gchord ghih
+.P
+Abc2midi will arpeggiate the C major guitar chord to
+CEGE. The upper case letters G,H,I, and J refer to
+the same notes except they are transposed down one
+octave. Note for the first inversion of the C major
+chord (indicated by "C/E"), E would be the lowest
+note so g would reference the note E.
+.P
+Like other gchord codes, you may append a numeral indicating
+the duration of the note. The same rules apply as before.
+You can use any combination of the gchord codes,
+(fcbghijGHIJz).
+
+
+.PP
+%%MIDI chordprog n
+.PP
+Sets the MIDI instrument for the chords to be n. If the command
+includes the string octave=n where n is a number between \-2 and 2
+inclusive, then this will shift the pitch of the instrument by n
+octaves. For example %%MIDI chordprog 10 octave=1.)
+
+.PP
+%%MIDI bassprog n
+.PP
+Sets the MIDI instrument for the bass notes to be n. If the command
+includes the string octave=n where n is a number between \-2 and 2
+inclusive, then this will shift the pitch of the instrument by n
+octaves. For example %%MIDI bassprog 10 octave=\-1.)
+.PP
+%%MIDI chordvol n
+.PP
+Sets the volume (velocity) of the chord notes at n.
+.PP
+%%MIDI bassvol n
+.PP
+Sets the volume (velocity) of the bass notes at n. There is no corresponding
+melodyvol command since there are 3 velocity values for melody, set using the
+beat command.
+.PP
+%%MIDI gchordon
+.PP
+Turns on guitar chords (they are turned on by default at the start of a
+tune).
+.PP
+%%MIDI gchordoff
+.PP
+Turns off guitar chords.
+.PP
+%%MIDI droneon
+.PP
+Turns on a continuous drone (used in bagpipe music) consisting
+of two notes. By default the notes are A, and A,, played
+on a bassoon at a velocity of 80. This can be configured
+by the %%MIDI drone command described below.
+.PP
+%%MIDI droneoff
+.PP
+Turns off the continuous drone.
+.PP
+%%MIDI drone n1 n2 n3 n4 n5
+.PP
+Sets the drone parameters where n1 is the MIDI program, n2 and
+n3 specify the MIDI pitches of the two notes in the chord, and n4 
+and n5 specify the MIDI velocities of the two notes.
+If you do not set these parameters they are by default
+70 45 33 80 80. A value of zero or less indicates that
+the setting of this parameter should be left as it is.
+.PP
+%%MIDI drum string [drum programs] [drum velocities]
+.PP
+This sets up a drum pattern. The string determines when there is a drum beat
+and the drum program values determine what each drum strike sounds like.
+.PP
+e.g. %%MIDI drum d2zdd 35 38 38  100 50 50
+.PP
+The string may contain 'd' for a drum strike or 'z' for a rest. By default
+a voice starts with no drum pattern and '%%MIDI drumon' is 
+needed to enable the drumming. The drum pattern is repeated during
+each bar until '%%MIDI drumoff' is encountered. The %%MIDI drum 
+command may be used within a tune to change the drum pattern. 
+This command places the drum sounds on channel 10 and
+assumes your tone generator complies with the General Midi standard - if
+it does not, then you may hear tones instead of drum sounds.
+.PP
+In both the gchord and drum commands, the standard note length of
+a single note f,c,z or d is not set by the L: command. Instead it
+is adjusted so that the entire gchord string or drum string fits
+exactly into one bar. In other words the duration of each note
+is divided by the total duration of the string. This means that,
+for example, the drum string "dd" is equivalent to drum string "d4d4".
+You cannot currently specify fractions directly (eg. C3/2)
+as done in the body of the music, but it is still possible to express
+complex rhythms. For example, to indicate a rhythm such as
+(3ddd d/d/d/d, you would write the string "d4d4d4d3d3d3d3".
+.PP
+%%MIDI drumbars n
+.PP
+The %%MIDI drum line can sound quite monotonous if it is repeated
+each bar. To circumvent this problem a new MIDI command
+%%MIDI drumbars n
+where n is a small number will spread out the drum string over
+n consecutive bars. By default drumbars is set to 1 maintaining
+compatibility with existing abc files. You should take
+care that the drumstring is evenly divisible between the
+drumbar bars. Also the time signature should not change
+between bars in a drumbar unit. (Sample abc file in doc/CHANGES
+June 24 2008.)
+.PP
+%%MIDI gchordbars n
+.PP
+This command spreads the gchord string over n consecutive bars
+just like drumbars (above). (A sample is found in doc/CHANGES
+March 17 2009.)
+
+
+
+
+.PP
+With version 1.54 Dec 4 2004 of abc2midi, notes in chords
+(eg. [FAc]) are not played in the same instant but offsetted
+and shortened by 10 MIDI time units. Thus the first note
+in the chord (eg. F) is played for the full indicated time,
+the second note (eg. A) starts 10 MIDI units later and is shortened
+by the same amount and the third note starts another 10 MIDI
+units later and is shortened by another 10 units. This introduces
+an "expressivo" option and avoids the heavy attack. (This
+does not apply to gchords or multivoiced chords.) The amount
+of the delay and shortening may be configured by the MIDI command
+
+.PP
+%%MIDI chordattack n
+
+.PP
+where n is a small number. If n is zero, then abc2midi should
+behave as in earlier versions. The delay n is in MIDI time units
+where there are 480 units in a quarter note beat. The program
+may not run correctly if n is too large and there are short
+chords.
+
+.PP
+%%MIDI randomchordattack n
+.PP
+Like above except that the delay is a random variable uniformly
+distributed between 0 and n-1.
+
+.PP
+%%MIDI trim x/y
+.PP
+where x and y are two numbers. This command controls the articulation
+of notes and chords by placing silent gaps between the notes.  The length
+of these gaps is determined by x/y and the unit length specified by the L:
+command. These gaps are produced by shortening the notes by the same amount.
+If the note is already shorter than the specified gap, then the gap
+is set to half the length of the note.  The fraction x/y indicates
+a note duration in the same manner as specified in the abc file.
+The actual duration is based on the unit length specified by the
+L: field command. It is recommended that x/y be a fraction close
+to zero. Note trimming is disabled inside slurs as specified by
+parentheses. You can turn off all note trimming by setting x to 0,
+eg 0/1. By default, note trimming is turned off at the beginning
+of a tune or voice command.
+
+.PP
+%%MIDI expand x/y
+.PP
+where x and y are two numbers defining a fraction less than 1.
+This command controls the articulation of notes and chords in the
+reverse manner. The notes are lengthened by this fraction so they
+overlap the start of the next note.
+
+
+.PP
+%%MIDI drummap note midipitch
+.PP
+Please see abcguide.txt.
+.PP
+%%MIDI ptstress filename
+.PP
+This command loads file filename into abc2midi which contains
+the Phil Taylor stress parameters and puts abc2midi in the mode
+where it applies these stress parameters on every note. This
+model runs in opposition to the standard beat model, so the
+MIDI beat, beatstring, beatmod commands become ineffectual.
+This also means that the dynamic indications !f! !pp! etc.
+do not work any more.
+.PP
+There are two different implementations of the stress model.
+Model 1 modifies the note articulation and takes
+control of the MIDI trim parameters too. To revert back to
+the standard model, put the command %%MIDI beataccents.
+Model 2 modifies both the onset and ending of each note
+allowing a musical beat to expand or contract in time. However,
+the length of a musical measure should be preserved. Note
+if you using model 2, which the current default, you must
+include \-BF as one of the runtime parameters of abc2midi.
+.PP
+The model divides a bar into equal segments. For each segment,
+a loudness or MIDI velocity is specified and a duration multiplier
+is specified. If a note falls into a specific segment, it assumes
+the velocity of that segment and its duration is modified
+accordingly. If the note overlaps more than one segment, then
+the note assumes the average of those segment values.
+.PP
+The input file specifies the number of segments and the loudness
+and duration multipliers for each segment. The file has the
+following format. The first value is the number of segments and each line
+specifies the velocity and duration multiplier of the specific
+segment. The velocity is limited to 127 and the duration is a
+decimal number. The note durations is modified by varying the
+gap between notes, so it is not possible to extend a note. This
+preserves the regular tempo of the music. The program scales,
+the note duration indications by dividing it by the maximum
+value which here is 1.4.
+
+.PP
+%%MIDI stressmodel n
+.PP
+
+where n is either 1 or 2, selects the stress model implementation.
+
+.PP
+ other %%MIDI commands such as bendvelocity, bendstring,
+controlstring have been introduced recently and are described
+in the file abcguide.txt.
+
+
+
+.SH "COMPATIBILITY WITH DRAFT STANDARD 2.0"
+
+.PP
+The proposed standard introduces a new copyright field
+using the syntax
+
+.PP
+%%abc-copyright (c) Copyright John Smith 2003
+
+.PP
+Abc2midi now inserts this in the MIDI file in the form of a
+metatext copyright tag. Changes were made to the event_specific
+function in store.c to process the copyright information. It
+is also copied into the Karaoke track (if it is created) as
+as @T field.
+
+.PP
+
+
+.SH SEE ALSO
+abc2ps(1), midi2abc(1), yaps(1).
+.SH AUTHOR
+James Allwright <J.R.Allwright@westminster.ac.uk>
+.SH SUPPORTED
+ by Seymour Shlien <fy733@ncf.ca>
+.SH VERSION
+This man page describes abc2midi version 2.27  June 25 2006.
+.SH COPYRIGHT
+Copyright 1999 James Allwright
+.PP
+abc2midi is supplied "as is" without any warranty. It
+is free software and can be used, copied, modified and
+distributed without fee under the terms of the GNU General 
+Public License.
+.PP
+More complete documentation may be found in abcguide.txt
+which comes with the abcMIDI distribution.
diff --git a/upstream/mageia-cauldron/man1/abcmatch.1 b/upstream/mageia-cauldron/man1/abcmatch.1
new file mode 100644
index 00000000..ebff7806
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/abcmatch.1
@@ -0,0 +1,120 @@
+.TH ABCMATCH 1
+.SH NAME
+abcmatch \- Search for specific sequences of notes in an abc file composed of many tunes.
+.SH SYNOPSIS
+\fBabcmatch\fP \fiabc\ file\fP [\fB-c\fP] [\fB-v\fP] [\fB-r\fP] [\fB-con\fP]\
+    [\fB-fixed nn\fP] [\fB-qnt\fP] [\fB-lev\fP] [\fB-a\fP] [\fB-ign\fP]\
+    [\fB-br %d\fP] [\fB-tp abc reference file\fP] [\fB-ver\fP]\
+    [\fB-pitch_hist\fP] [\fB-wpitch_hist\fP] [\fB-length_hist\fP]\
+    [\fB-interval_hist\fP] [\fB-pitch_table\fP] [\fB-interval_table\fP]\
+ \fireference\ number\fP
+.SH "DESCRIPTION"
+.PP
+.B abcmatch
+is used to  search for specific sequences of notes in an  abc file
+composed of many tunes. For example, if you know a few bars of a tune,
+you can use this program to find the tune having this sequence and perhaps
+identify the tune.
+At a minimum, abcmatch requires two files. A template file called
+match.abc which contains the bars that you are searching for and a large
+file consisting of a hundred or more abc tunes. The program automatically
+loads up the match.abc file and then scans every tune in the large file
+.SH OPTIONS
+.TP
+.B -v and -c
+mainly used for debugging when the program does not do what was expected.
+.TP
+.B -ver
+prints version number and then exits
+.TP
+.B --norhythm
+Causes the matching algorithm to ignore the length of notes in a bar,
+thus E3/2F/D GA2 would match EFD G2A. The option ignores \-r parameter
+since it is now irrelevant.
+.TP
+.B -pitch_table
+Used to produce a interval weighted pitch histogram for each tune in
+the file. If this is saved in an external file, that file could be used
+as a database for finding tunes with similar pitch probability density
+functions (pdf).
+.TP
+.B -r
+Controls how the matching criterion handles small rhythm variations in
+the melody. The \-r option must be followed by a number which specifies
+the temporal resolution for the match. When the number is zero, this
+indicates that a perfect match should be performed, meaning that the
+lengths of each note in the bar must match exactly in order to be
+reported. For larger values a looser match will be performed as
+described below. Note lengths are converted into temporal units where
+a quarter note normally is assigned a value of 24. Therefore an eight
+note has a value of 12, a sixteenth has a value of 6, a half note has
+a value of 48 and etc. If you specify a temporal resolution of 12, then
+the pitch values of the notes only need to match at time units which
+are multiples of an eighth note. 
+.TP
+.B -fixed n
+Causes the program to disregard bar lines when does the matching. It
+allows matching of notes between tunes having different time signatures.
+n is a number which specifies the exact number of notes to match. For
+example if n is 4, the program could match
+|C E G E| .. with |C E|G E|
+Note the matcher still starts at a beginning of a given bar for both the
+tune and template.
+.TP
+.B -con
+Specifies contour matching. In this case, the program uses the key
+signature only to indicate accidentals. The pitch contour is computed
+from the pitch difference or interval between adjacent notes.
+.TP
+.B -qnt
+Uses the contour matching algorithm but also quantizes the intervals
+using the following table:
+
+unison and semitone    0
+minor 2nd to major 2nd 1
+minor 3rd to major 3rd 2
+any larger interval    3
+
+Negative numbers are descending intervals.
+.TP
+.B -tp file name, reference number
+Substitute any tune for the template match.abc. When using this
+feature, the entire tune is used as a template. Abcmatch does not match
+the template with itself, and only bars which match bars in other tunes
+are reported.
+.TP
+.B -br threshold
+Runs the program in a brief mode designed to identify groups of tunes
+sharing common bars. In this mode, the program counts the numbers of
+bars in the test tune which are also present in match.abc. If the
+number of common bars is larger or equal to the threshold then the
+program reports the tune and the number of common bars. 
+The program scans all the tunes in the abc file and returns a list of
+all the tunes which have more than a specific number of bars in common
+with the template, match.abc. In actual use, the program is run
+repeatedly by a script. For each tune in a abc file, it creates a
+template file called match.abc and then executes abcmatch. The outputs
+are displayed on the screen in a form easy to interpret. The user has
+no control of the matching criterion. The rhythm must match exactly
+and the notes are transposed to suit the key signature. In other words
+the \-r parameter is independent of what is specified in the parameter
+list.
+.TP
+.B -pitch_hist or -length_hist
+Runs the program in another mode. It produces a histogram of the
+distribution of the notes in the abc file.
+The pitch is indicated in midi units. Thus middle C is 60 and the
+pitches go up in semitone units. Following the pitch is a count
+of the number of times that note occurred.
+.TP
+.B -pitch_table or -interval_table
+Used to create a database for a collection of tunes in a file for
+future analysis.
+
+.SH "SEE ALSO"
+.PP
+.IR abc2abc "(1), " abc2midi "(1), " mftext "(1) ", midi2abc "(1) ", midicopy "(1) ", yaps "(1)"
+.SH AUTHOR
+This manual page was written by Ross Gammon based on abcmatch.txt by Seymour Shlien.
+.SH VERSION
+This man page describes abcmatch version 1.35 from January 15 2006.
diff --git a/upstream/mageia-cauldron/man1/addftinfo.1 b/upstream/mageia-cauldron/man1/addftinfo.1
new file mode 100644
index 00000000..d649ef31
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/addftinfo.1
@@ -0,0 +1,195 @@
+.TH ADDFTINFO 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+addftinfo \- add information to troff font files for use with groff
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.\" Characters
+.\" ====================================================================
+.
+.\" Ellipsis ...
+.ie t .ds EL \fS\N'188'\fP\"
+.el .ds EL \&.\|.\|.\&\"
+.\" called with \*(EL
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY addftinfo
+.OP \-asc\-height n
+.OP \-body\-depth n
+.OP \-body\-height n
+.OP \-cap\-height n
+.OP \-comma\-depth n
+.OP \-desc\-depth n
+.OP \-fig\-height n
+.OP \-x\-height n
+.I res
+.I unitwidth
+.I font
+.YS
+.
+.SY addftinfo
+.B \-\-help
+.YS
+.
+.SY addftinfo
+.B \-v
+.SY addftinfo
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B addftinfo
+reads a troff font file and adds some additional font-metric
+information that is used by the groff system.
+.
+The font file with the information added is written on the standard
+output.
+.
+The information added is guessed using some parametric information
+about the font and assumptions about the traditional troff names for
+characters.
+.
+The main information added is the heights and depths of characters.
+.
+The
+.I res
+and
+.I unitwidth
+arguments should be the same as the corresponding parameters in the
+DESC file;
+.I font
+is the name of the file describing the font;
+if
+.I font
+ends with
+.B I
+the font will be assumed to be italic.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.B \-v
+prints the version number.
+.
+.
+.LP
+All other options change one of the parameters that are used to derive
+the heights and depths.
+.
+Like the existing quantities in the font file, each
+.I value
+is in
+.RI inches/ res
+for a font whose point size is
+.IR unitwidth .
+.
+.I param-option
+must be one of:
+.
+.TP
+.B \-x\-height
+The height of lowercase letters without ascenders such as x.
+.
+.TP
+.B \-fig\-height
+The height of figures (digits).
+.
+.TP
+.B \-asc\-height
+The height of characters with ascenders, such as b, d or l.
+.
+.TP
+.B \-body\-height
+The height of characters such as parentheses.
+.
+.TP
+.B \-cap\-height
+The height of uppercase letters such as A.
+.
+.TP
+.B \-comma\-depth
+The depth of a comma.
+.
+.TP
+.B \-desc\-depth
+The depth of characters with descenders, such as p, q, or y.
+.
+.TP
+.B \-body\-depth
+The depth of characters such as parentheses.
+.
+.
+.LP
+.B addftinfo
+makes no attempt to use the specified parameters to guess the
+unspecified parameters.
+.
+If a parameter is not specified the default will be used.
+.
+The defaults are chosen to have the reasonable values for a Times
+font.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR groff_font (5),
+.BR groff (1),
+.BR groff_char (7)
+.
+.
+.P
+You can view a man page
+.IB name ( n )
+with
+.RS
+.EX
+.BI "man" " n name"
+.EE
+.RE
+in text mode and with
+.RS
+.EX
+.BI "groffer" " n name"
+.EE
+.RE
+in graphical mode (PDF, etc.).
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/addr2line.1 b/upstream/mageia-cauldron/man1/addr2line.1
new file mode 100644
index 00000000..7e3630f6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/addr2line.1
@@ -0,0 +1,353 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "ADDR2LINE 1"
+.TH ADDR2LINE 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+addr2line \- convert addresses or symbol+offset into file names and line numbers
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+addr2line [\fB\-a\fR|\fB\-\-addresses\fR]
+          [\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR]
+          [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]]
+          [\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR]
+          [\fB\-R\fR|\fB\-\-recurse\-limit\fR]
+          [\fB\-e\fR \fIfilename\fR|\fB\-\-exe=\fR\fIfilename\fR]
+          [\fB\-f\fR|\fB\-\-functions\fR] [\fB\-s\fR|\fB\-\-basename\fR]
+          [\fB\-i\fR|\fB\-\-inlines\fR]
+          [\fB\-p\fR|\fB\-\-pretty\-print\fR]
+          [\fB\-j\fR|\fB\-\-section=\fR\fIname\fR]
+          [\fB\-H\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR]
+          [addr addr ...]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBaddr2line\fR translates addresses or symbol+offset into file names and line numbers.
+Given an address or symbol+offset in an executable or an offset in a section of a relocatable
+object, it uses the debugging information to figure out which file name and
+line number are associated with it.
+.PP
+The executable or relocatable object to use is specified with the \fB\-e\fR
+option.  The default is the file \fIa.out\fR.  The section in the relocatable
+object to use is specified with the \fB\-j\fR option.
+.PP
+\&\fBaddr2line\fR has two modes of operation.
+.PP
+In the first, hexadecimal addresses or symbol+offset are specified on the command line,
+and \fBaddr2line\fR displays the file name and line number for each
+address.
+.PP
+In the second, \fBaddr2line\fR reads hexadecimal addresses or symbol+offset from
+standard input, and prints the file name and line number for each
+address on standard output.  In this mode, \fBaddr2line\fR may be used
+in a pipe to convert dynamically chosen addresses.
+.PP
+The format of the output is \fB\s-1FILENAME:LINENO\s0\fR.  By default
+each input address generates one line of output.
+.PP
+Two options can generate additional lines before each
+\&\fB\s-1FILENAME:LINENO\s0\fR line (in that order).
+.PP
+If the \fB\-a\fR option is used then a line with the input address
+is displayed.
+.PP
+If the \fB\-f\fR option is used, then a line with the
+\&\fB\s-1FUNCTIONNAME\s0\fR is displayed.  This is the name of the function
+containing the address.
+.PP
+One option can generate additional lines after the
+\&\fB\s-1FILENAME:LINENO\s0\fR line.
+.PP
+If the \fB\-i\fR option is used and the code at the given address is
+present there because of inlining by the compiler then additional
+lines are displayed afterwards.  One or two extra lines (if the
+\&\fB\-f\fR option is used) are displayed for each inlined function.
+.PP
+Alternatively if the \fB\-p\fR option is used then each input
+address generates a single, long, output line containing the address,
+the function name, the file name and the line number.  If the
+\&\fB\-i\fR option has also been used then any inlined functions will
+be displayed in the same manner, but on separate lines, and prefixed
+by the text \fB(inlined by)\fR.
+.PP
+If the file name or function name can not be determined,
+\&\fBaddr2line\fR will print two question marks in their place.  If the
+line number can not be determined, \fBaddr2line\fR will print 0.
+.PP
+When symbol+offset is used, +offset is optional, except when the symbol
+is ambigious with a hex number. The resolved symbols can be mangled
+or unmangled, except unmangled symbols with + are not allowed.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-addresses\fR" 4
+.IX Item "--addresses"
+.PD
+Display the address before the function name, file and line number
+information.  The address is printed with a \fB0x\fR prefix to easily
+identify it.
+.IP "\fB\-b\fR \fIbfdname\fR" 4
+.IX Item "-b bfdname"
+.PD 0
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+.PD
+Specify that the object-code format for the object files is
+\&\fIbfdname\fR.
+.IP "\fB\-C\fR" 4
+.IX Item "-C"
+.PD 0
+.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
+.IX Item "--demangle[=style]"
+.PD
+Decode (\fIdemangle\fR) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes \*(C+ function names readable.  Different compilers have different
+mangling styles. The optional demangling style argument can be used to
+choose an appropriate demangling style for your compiler.
+.IP "\fB\-e\fR \fIfilename\fR" 4
+.IX Item "-e filename"
+.PD 0
+.IP "\fB\-\-exe=\fR\fIfilename\fR" 4
+.IX Item "--exe=filename"
+.PD
+Specify the name of the executable for which addresses should be
+translated.  The default file is \fIa.out\fR.
+.IP "\fB\-f\fR" 4
+.IX Item "-f"
+.PD 0
+.IP "\fB\-\-functions\fR" 4
+.IX Item "--functions"
+.PD
+Display function names as well as file and line number information.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-basenames\fR" 4
+.IX Item "--basenames"
+.PD
+Display only the base of each file name.
+.IP "\fB\-i\fR" 4
+.IX Item "-i"
+.PD 0
+.IP "\fB\-\-inlines\fR" 4
+.IX Item "--inlines"
+.PD
+If the address belongs to a function that was inlined, the source
+information for all enclosing scopes back to the first non-inlined
+function will also be printed.  For example, if \f(CW\*(C`main\*(C'\fR inlines
+\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from
+\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR
+will also be printed.
+.IP "\fB\-j\fR" 4
+.IX Item "-j"
+.PD 0
+.IP "\fB\-\-section\fR" 4
+.IX Item "--section"
+.PD
+Read offsets relative to the specified section instead of absolute addresses.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-pretty\-print\fR" 4
+.IX Item "--pretty-print"
+.PD
+Make the output more human friendly: each location are printed on one line.
+If option \fB\-i\fR is specified, lines for all enclosing scopes are
+prefixed with \fB(inlined by)\fR.
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-R\fR" 4
+.IX Item "-R"
+.IP "\fB\-\-recurse\-limit\fR" 4
+.IX Item "--recurse-limit"
+.IP "\fB\-\-no\-recurse\-limit\fR" 4
+.IX Item "--no-recurse-limit"
+.IP "\fB\-\-recursion\-limit\fR" 4
+.IX Item "--recursion-limit"
+.IP "\fB\-\-no\-recursion\-limit\fR" 4
+.IX Item "--no-recursion-limit"
+.PD
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings.  Since the name mangling formats allow for
+an infinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault.  The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+.Sp
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names.  Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+.Sp
+The \fB\-r\fR option is a synonym for the
+\&\fB\-\-no\-recurse\-limit\fR option.  The \fB\-R\fR option is a
+synonym for the \fB\-\-recurse\-limit\fR option.
+.Sp
+Note this option is only effective if the \fB\-C\fR or
+\&\fB\-\-demangle\fR option has been enabled.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/alpine.1 b/upstream/mageia-cauldron/man1/alpine.1
new file mode 100644
index 00000000..794a238c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/alpine.1
@@ -0,0 +1,398 @@
+.TH alpine 1 "Version 2.26"
+.SH NAME
+alpine \- an Alternatively Licensed Program for Internet News and Email
+.SH SYNTAX 
+
+.B alpine
+[
+.I options
+] [
+.I address
+,
+.I address
+] 
+
+.B alpinef
+[
+.I options
+] [
+.I address
+,
+.I address
+]
+.SH DESCRIPTION
+
+Alpine is a screen-oriented message-handling tool.  In its default 
+configuration, Alpine offers an intentionally limited set of 
+functions geared toward the novice user, but it also has a large
+list of optional "power-user" and personal-preference features.
+.I alpinef 
+is a variant of Alpine that uses function keys rather than mnemonic 
+single-letter commands.
+Alpine's basic feature set includes:
+.IP
+View, Save, Export, Delete, Print, Reply and Forward messages.
+.IP
+Compose messages in a simple editor (Pico) with word-wrap and a spelling
+checker.  Messages may be postponed for later completion.
+.IP
+Full-screen selection and management of message folders.
+.IP
+Address book to keep a list of long or frequently-used addresses.
+Personal distribution lists may be defined.
+Addresses may be taken into the address book from
+incoming mail without retyping them. 
+.IP
+New mail checking and notification occurs automatically every 2.5 minutes
+and after certain commands, e.g. refresh-screen (Ctrl-L).
+.IP
+On-line, context-sensitive help screens.
+.PP
+Alpine supports MIME (Multipurpose Internet Mail Extensions), an Internet
+Standard for representing multipart and multimedia data in email.
+Alpine allows you to save MIME objects to files, and in some 
+cases, can also initiate the correct program for viewing the object.
+It uses the system's
+.I mailcap 
+configuration file to determine what program can process a particular MIME
+object type. 
+Alpine's message composer does not have integral multimedia capability, but
+any type of data file --including multimedia-- can be attached to a text
+message and sent using MIME's encoding rules.  This allows any group of
+individuals with MIME-capable mail software (e.g. Alpine, PC-Alpine, or many
+other programs) to exchange formatted documents, spread-sheets, image
+files, etc, via Internet email. 
+.PP
+Alpine uses the 
+.I c-client
+messaging API to access local and remote mail folders. This
+library provides a variety of low-level message-handling functions, 
+including drivers
+for a variety of different mail file formats, as well as routines
+to access remote mail and news servers, using IMAP (Internet Message
+Access Protocol) and NNTP (Network News Transport Protocol).  Outgoing mail
+is usually posted directly via SMTP 
+(Simple Mail Transfer Protocol).
+.SH OPTIONS
+.if n .ta 2.8i
+.if t .ta 2.1i
+
+The command line options/arguments are:
+.IP \fIaddress\fR 20
+Send mail to 
+.I address.
+This will cause Alpine to go directly into the message composer.
+.IP \fB-attach\ \fIfile\fR 20
+Send mail with the listed
+.I file
+as an attachment.
+.IP \fB-attachlist\ \fIfile-list\fR 20
+Send mail with the listed
+.I file-list
+as an attachments.
+.IP \fB-attach_and_delete\ \fIfile\fR 20
+Send mail with the listed
+.I file
+as an attachment, and remove the file
+after the message is sent.
+.IP \fB-aux\ \fIlocal_directory\fR 20
+PC-Alpine only. When using a remote configuration (-p <remote_config>) this tells
+PC-Alpine the local directory to use for storing auxiliary files, like debug
+files, address books, and signature files.
+.IP \fB-bail\fR 20
+Exit if the pinerc file does not exist. This might be useful if the config
+file is accessed using some remote filesystem protocol. If the remote mount
+is missing this will cause Alpine to quit instead of creating a new pinerc.
+.IP \fB-c\ \fIcontext-number\fR 20
+context-number is the number corresponding to the 
+folder-collection to which the
+.I -f
+command line argument should be applied.  By default the
+.I -f
+argument is applied to the first defined folder-collection.
+.IP \fB-conf\fR 20
+Produce a sample/fresh copy of the 
+system-wide configuration file,
+.I pine.conf,
+on the standard output. This is distinct from the per-user
+.I .pinerc
+file.
+.IP \fB-convert_sigs\ \fI-p\ pinerc\fR 20
+Convert signature files into literal signatures.
+.IP \fB-copy_abook\ <\fIlocal_abook\fR>\ <\fIremote_abook\fR> 20
+Copy the local address book file to a remote address book folder.
+.IP \fB-copy_pinerc\ <\fIlocal_pinerc\fR>\ <\fIremote_pinerc\fR> 20
+Copy the local pinerc file to a remote pinerc folder.
+.IP \fB-d\ \fIdebug-level\fR 20
+Output diagnostic info at
+.I debug-level
+(0-9) to the current
+.I .pine-debug[1-4]
+file.  A value of 0 turns debugging off and suppresses the
+.I .pine-debug
+file.
+.IP \fB-d\ \fIkey[=val]\fR 20
+Fine tuned output of diagnostic messages where "flush" causes
+debug file writing without buffering, "timestamp" appends
+each message with a timestamp, "imap=n" where n is between
+0 and 4 representing none to verbose IMAP telemetry reporting,
+"numfiles=n" where n is between 0 and 31 corresponding to the
+number of debug files to maintain, and "verbose=n" where n is
+between 0 and 9 indicating an inverse threshold for message
+output.
+.IP \fB-f\ \fIfolder\fR 20
+Open 
+.I folder 
+(in first defined folder collection, use 
+.I -c n
+to specify another collection) instead of INBOX.
+.IP \fB-F\ \fIfile\fR 20
+Open named text file and view with Alpine's browser.
+.IP \fB-h\fR 20
+Help: list valid command-line options.
+.IP \fB-i\fR 20
+Start up in the FOLDER INDEX screen.
+.IP \fB-I\ \fIkeystrokes\fR 20
+Initial (comma separated list of) keystrokes which Alpine should execute
+on startup.
+.IP \fB-install\fR 20
+For PC-Alpine only, this option causes PC-Alpine to prompt for some basic
+setup information, then exits.
+.IP \fB-k\fR 20
+Use function keys for commands. This is the same as running the command
+.IR alpinef .
+.IP \fB-n\ \fInumber\fR 20
+Start up with current message-number set to 
+.I number.
+.IP \fB-nowrite_password_cache\fR 20
+Read from a password cache if there is one, but
+never offer to write a password to the cache
+.IP \fB-o\fR 20
+Open first folder read-only.
+.IP \fB-p\ \fIconfig-file\fR 20
+Use 
+.I config-file
+as the personal configuration file instead of the default 
+.IR .pinerc .
+.IP \fB-P\ \fIconfig-file\fR 20
+Use 
+.I config-file
+as the configuration file instead of default
+system-wide configuration file 
+.IR pine.conf .
+.IP \fB-passfile\ \fI<fully-qualified-path>\fR 20
+When password file support is compiled in, use the file specified in
+.I <fully-qualified-path>
+instead of the default.
+.IP \fB-pinerc\ \fIfile\fR 20
+Output fresh pinerc configuration to 
+.I file, preserving the settings of variables that the user has made.
+Use \fIfile\fR set to ``-'' to make output go to standard out.
+.IP \fB-pwdcertdir\ \fI<fully-qualified-path>\fR 20
+When SMIME and password file support are compiled in, this variable sets 
+the directory to store your personal key and certificate to encrypt and 
+decrypt your password file.
+.IP \fB-r\fR 20
+Use restricted/demo mode.
+.I Alpine
+will only send mail to itself
+and functions like save and export are restricted.
+.IP \fB-registry\ \fIcmd\fR 20
+For PC-Alpine only, this option affects the values of 
+Alpine's registry entries.
+Possible values for \fIcmd\fR are set, clear, and dump.
+\fISet\fR will always reset Alpine's registry 
+entries according to its current settings.
+\fIClear\fR will clear the registry values.
+\fIClearsilent\fR will silently clear the registry values.
+\fIDump\fR will display the values of current registry settings.
+Note that the dump command is currently disabled.
+Without the -registry option, PC-Alpine will write values into
+the registry only if there currently aren't any values set.
+.IP \fB-smimedir\ \fI<fully-qualified-path>\fR
+If SMIME is compiled in, this argument sets the directory where the 
+public, private, and certificate authorities certificates and keys 
+are stored. If not set by the command line the default is 
+~/.alpine-smime
+.IP \fB-sort\ \fIorder\fR
+Sort the FOLDER INDEX display in one of the following orders: 
+.I arrival, date, subject, orderedsubj, thread, from, size, score, to, cc,
+or
+.I reverse. Arrival 
+order is the default. 
+The OrderedSubj choice simulates a threaded sort.
+Any sort may be reversed by adding 
+.I /reverse
+to it.
+.I Reverse
+by itself is the same as
+.IR arrival/reverse .
+.IP \fB-supported\fR 20
+Some options may or may not be supported depending on how Alpine
+was compiled.
+This is a way to determine which options are supported in the particular
+copy of Alpine you are using.
+.IP \fB-uninstall\fR 20
+For PC-Alpine only, this option causes PC-Alpine to remove references to
+Alpine in Windows settings.
+.IP \fB-url\ \fIurl\fR 20
+Open the given
+.I url.
+Cannot be used with 
+.I -f
+or
+.I -F
+options.
+.IP \fB-v\fR 20
+Version: Print version information.
+.IP \fB-version\fR 20
+Version: Print version information.
+.IP \fB-x\ \fIconfig\fR 20
+Use configuration exceptions in
+.I config.
+Exceptions are used to override your default pinerc
+settings for a particular platform, can be a local file or
+a remote folder.
+.IP \fB-xoauth2-server\ \fIServerName\fR 20
+Name of the service that XOAUTH2 authentication will be attempted.
+The only service supported as of this writing is Gmail. Note that
+all of the options -xoauth2-server, -xoauth2-client-id and 
+-xoauth2-client-secret must be used simultaneously. Example:
+-xoauth2-server Gmail.
+.IP \fB-xoauth2-client-id\ \fIClient-Id\fR 20
+String that identifies Alpine with the service provider that provides
+XOAUTH2 authentication. Note that
+all of the options -xoauth2-server, -xoauth2-client-id and 
+-xoauth2-client-secret must be used simultaneously.
+.IP \fB-xoauth2-client-secret\ \fIClient-Secret\fR 20
+Secret string that identifies the Alpine with 
+the service provider that provides XOAUTH2 authentication.
+Note that
+all of the options -xoauth2-server, -xoauth2-client-id and 
+-xoauth2-client-secret must be used simultaneously.
+.IP \fB-z\fR 20
+Enable ^Z and SIGTSTP so alpine may be suspended.
+.IP \fI-option\=\fIvalue\fR 20
+Assign 
+.I value
+to the config option 
+.I option
+e.g. -signature-file=sig1 or -feature-list=signature-at-bottom 
+(Note: feature-list values are additive) 
+.SH CONFIGURATION
+
+There are several levels of Alpine configuration.  Configuration values at 
+a given level over-ride corresponding values at lower levels.  In order of 
+increasing precedence:
+
+ o built-in defaults.
+.br
+ o system-wide 
+.I pine.conf 
+file.
+.br
+ o personal 
+.I .pinerc 
+file (may be set via built-in Setup/Config menu.)
+.br
+ o command-line options.
+.br
+ o system-wide 
+.I pine.conf.fixed 
+file.
+
+There is one exception to the rule that configuration values are replaced
+by the value of the same option in a higher-precedence file: the
+feature-list variable has values that are additive, but can be negated by
+prepending "no-" in front of an individual feature name. Unix Alpine also
+uses the following environment variables: 
+
+  TERM
+.br
+  DISPLAY     (determines if Alpine can display IMAGE attachments.)
+.br
+  SHELL       (if not set, default is /bin/sh )
+.br
+  MAILCAPS    (semicolon delimited list of path names to mailcap files)
+.SH FILES
+.if n .ta 2.8i
+.if t .ta 2.1i
+
+/usr/spool/mail/xxxx	Default folder for incoming mail.
+.br
+~/mail	Default directory for mail folders.
+.br
+~/.addressbook	Default address book file.
+.br
+~/.signature	File used for signature, appended to every message.
+.br
+~/.pine-debug[1-4]	Diagnostic log for debugging.
+.br
+~/.pinerc	Personal alpine config file.
+.br
+~/.pine-crash	Debug information useful to debug a crash.
+.br
+~/.newsrc	News subscription/state file.
+.br
+~/.mailcap	Personal mail capabilities file.
+.br
+~/.mime.types	Personal file extension to MIME type mapping
+.br
+/etc/mailcap	System-wide mail capabilities file.
+.br
+/etc/mime.types	System-wide file ext. to MIME type mapping
+.br
+/usr/local/lib/pine.info	Local pointer to system administrator.
+.br
+/usr/local/lib/pine.conf	System-wide configuration file.
+.br
+/usr/local/lib/pine.conf.fixed	 Non-overridable configuration file.
+.br
+~/.alpine-smime/ca	Directory that contains Certificate Authority files.
+.br
+~/.alpine-smime/private	Directory that contains private key(s).
+.br
+~/.alpine-smime/public	Directory that contains public key(s).
+.br
+/tmp/.\\usr\\spool\\mail\\xxxx	Per-folder mailbox lock files.
+.br
+~/.pine-interrupted-mail	Message which was interrupted.
+.br
+~/mail/postponed-msgs	For postponed messages (drafts)
+.br
+~/mail/sent-mail	Outgoing message archive (FCC).
+.br
+~/mail/saved-messages	Default destination for Saving messages.
+.SH "SEE ALSO"
+
+pico(1), binmail(1), aliases(5), mailaddr(7), sendmail(8), spell(1), imapd(8)
+
+.br
+Newsgroup:  comp.mail.pine
+
+.br
+Mailing List:
+.br
+Alpine-info, at https://www.washington.edu/alpine/alpine-info/
+
+.br
+Main Alpine distribution site:  
+.br
+http://repo.or.cz/alpine.git
+
+.br
+Alpine Technical Notes, included in the source distribution.
+
+.br
+C-Client messaging API library, included in the source distribution.
+.SH ACKNOWLEDGMENTS
+.na 
+.nf
+
+This software is the result of the contribution of many individuals 
+who have dedicated their time to support, improve and suggest ways 
+to improve Alpine through the years. This software would not be 
+possible without the support of the University of Washington in 
+Seattle, Washington. The Alpine community extends its most sincere 
+thanks to all contributors and invites everyone to join in and 
+contribute to this project.
diff --git a/upstream/mageia-cauldron/man1/anytopnm.1 b/upstream/mageia-cauldron/man1/anytopnm.1
new file mode 100644
index 00000000..e588de7a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/anytopnm.1
@@ -0,0 +1,100 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Anytopnm User Manual" 0 "15 November 2014" "netpbm documentation"
+
+.SH NAME
+anytopnm - convert an arbitrary type of image file to PBM, PGM, or PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBanytopnm\fP [\fIfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBanytopnm\fP converts the input image, which may be in any of
+about 100 graphics formats, to PBM, PGM, or PPM format, depending on
+that nature of the input image, and outputs it to Standard Output.
+.PP
+To determine the format of the input, \fBanytopnm\fP uses the
+\fBfile\fP program (possibly assisted by the magic numbers file
+fragment included with Netpbm). If that fails (very few image formats
+have magic numbers), \fBanytopnm\fP looks at the filename extension.
+If that fails, \fBanytopnm\fP punts.
+.PP
+The type of the output file depends on the input image.
+.PP
+\fBanytopnm\fP uses the converters for particular graphics formats
+that are in the Netpbm package, so it can't convert any format that
+you couldn't convert with some other Netpbm program.  What
+\fBanytopnm\fP adds is the ability to recognize the format and choose
+the appropriate Netpbm program to convert it.  For example, if you
+invoke \fBanytopnm\fP on a GIF file, \fBanytopnm\fP will recognize
+that it is a GIF file and therefore \fBgiftopnm\fP knows how to
+convert it to PNM, so \fBanytopnm\fP invokes \fBgiftopnm\fP.
+.PP
+\fBanytopnm\fP cannot recognize every possible input format, so you
+may still be able to convert an image with a specific Netpbm program when
+\fBanytopnm\fP fails to convert it.
+.PP
+If \fBfile\fP indicates that the input file is compressed (either
+via Unix compress, gzip, or bzip compression), \fBanytopnm\fP
+uncompresses it and proceeds as above with the uncompressed result.
+.PP
+If \fBfile\fP indicates that the input file is encoded by uuencode
+or btoa, \fBanytopnm\fP decodes it and proceeds as above with the
+decoded result.
+.PP
+If \fIfile\fP is \fB-\fP or not given, \fBanytopnm\fP takes its
+input from Standard Input.
+.PP
+Many image formats are capable of representing multiple images.  In
+most cases, \fBanytopnm\fP converts these to multi-image Netpbm images,
+but for some formats, \fBanytopnm\fP converts only the first image and
+ignores the rest.
+.PP
+In the case of a multi-image GIF input, \fBanytopnm\fP converts all the
+images starting with Netpbm 10.69 (December 2014), but only the first in
+earlier releases.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBanytopnm\fP.
+
+\fBanytopnm\fP does not recognize the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)  However, the \fB-version\fP option works.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBfile\fP man page
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/anytopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ar.1 b/upstream/mageia-cauldron/man1/ar.1
new file mode 100644
index 00000000..e662fcef
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ar.1
@@ -0,0 +1,538 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "AR 1"
+.TH AR 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+ar \- create, modify, and extract from archives
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from
+archives.  An \fIarchive\fR is a single file holding a collection of
+other files in a structure that makes it possible to retrieve
+the original individual files (called \fImembers\fR of the archive).
+.PP
+The original files' contents, mode (permissions), timestamp, owner, and
+group are preserved in the archive, and can be restored on
+extraction.
+.PP
+\&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any
+length; however, depending on how \fBar\fR is configured on your
+system, a limit on member-name length may be imposed for compatibility
+with archive formats maintained with other tools.  If it exists, the
+limit is often 15 characters (typical of formats related to a.out) or 16
+characters (typical of formats related to coff).
+.PP
+\&\fBar\fR is considered a binary utility because archives of this sort
+are most often used as \fIlibraries\fR holding commonly needed
+subroutines.  Since libraries often will depend on other libraries,
+\&\fBar\fR can also record the dependencies of a library when the
+\&\fB\-\-record\-libdeps\fR option is specified.
+.PP
+\&\fBar\fR creates an index to the symbols defined in relocatable
+object modules in the archive when you specify the modifier \fBs\fR.
+Once created, this index is updated in the archive whenever \fBar\fR
+makes a change to its contents (save for the \fBq\fR update operation).
+An archive with such an index speeds up linking to the library, and
+allows routines in the library to call each other without regard to
+their placement in the archive.
+.PP
+You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
+table.  If an archive lacks the table, another form of \fBar\fR called
+\&\fBranlib\fR can be used to add just the table.
+.PP
+\&\s-1GNU\s0 \fBar\fR can optionally create a \fIthin\fR archive,
+which contains a symbol index and references to the original copies
+of the member files of the archive.  This is useful for building
+libraries for use within a local build tree, where the relocatable
+objects are expected to remain available, and copying the contents of
+each object would only waste time and space.
+.PP
+An archive can either be \fIthin\fR or it can be normal.  It cannot
+be both at the same time.  Once an archive is created its format
+cannot be changed without first deleting it and then creating a new
+archive in its place.
+.PP
+Thin archives are also \fIflattened\fR, so that adding one thin
+archive to another thin archive does not nest it, as would happen with
+a normal archive.  Instead the elements of the first archive are added
+individually to the second archive.
+.PP
+The paths to the elements of the archive are stored relative to the
+archive itself.
+.PP
+\&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different
+facilities.  You can control its activity using command-line options,
+like the different varieties of \fBar\fR on Unix systems; or, if you
+specify the single command-line option \fB\-M\fR, you can control it
+with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R"
+program.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+\&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier
+flags \fImod\fR in any order, within the first command-line argument.
+.PP
+If you wish, you may begin the first command-line argument with a
+dash.
+.PP
+The \fIp\fR keyletter specifies what operation to execute; it may be
+any of the following, but you must specify only one of them:
+.IP "\fBd\fR" 4
+.IX Item "d"
+\&\fIDelete\fR modules from the archive.  Specify the names of modules to
+be deleted as \fImember\fR...; the archive is untouched if you
+specify no files to delete.
+.Sp
+If you specify the \fBv\fR modifier, \fBar\fR lists each module
+as it is deleted.
+.IP "\fBm\fR" 4
+.IX Item "m"
+Use this operation to \fImove\fR members in an archive.
+.Sp
+The ordering of members in an archive can make a difference in how
+programs are linked using the library, if a symbol is defined in more
+than one member.
+.Sp
+If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
+\&\fImember\fR arguments are moved to the \fIend\fR of the archive;
+you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
+specified place instead.
+.IP "\fBp\fR" 4
+.IX Item "p"
+\&\fIPrint\fR the specified members of the archive, to the standard
+output file.  If the \fBv\fR modifier is specified, show the member
+name before copying its contents to standard output.
+.Sp
+If you specify no \fImember\fR arguments, all the files in the archive are
+printed.
+.IP "\fBq\fR" 4
+.IX Item "q"
+\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
+\&\fIarchive\fR, without checking for replacement.
+.Sp
+The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
+operation; new members are always placed at the end of the archive.
+.Sp
+The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
+.Sp
+Since the point of this operation is speed, implementations of
+\&\fBar\fR have the option of not updating the archive's symbol
+table if one exists.  Too many different systems however assume that
+symbol tables are always up-to-date, so \s-1GNU\s0 \fBar\fR will
+rebuild the table even with a quick append.
+.Sp
+Note \- \s-1GNU\s0 \fBar\fR treats the command \fBqs\fR as a
+synonym for \fBr\fR \- replacing already existing files in the
+archive and appending new ones at the end.
+.IP "\fBr\fR" 4
+.IX Item "r"
+Insert the files \fImember\fR... into \fIarchive\fR (with
+\&\fIreplacement\fR). This operation differs from \fBq\fR in that any
+previously existing members are deleted if their names match those being
+added.
+.Sp
+If one of the files named in \fImember\fR... does not exist, \fBar\fR
+displays an error message, and leaves undisturbed any existing members
+of the archive matching that name.
+.Sp
+By default, new members are added at the end of the file; but you may
+use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
+placement relative to some existing member.
+.Sp
+The modifier \fBv\fR used with this operation elicits a line of
+output for each file inserted, along with one of the letters \fBa\fR or
+\&\fBr\fR to indicate whether the file was appended (no old member
+deleted) or replaced.
+.IP "\fBs\fR" 4
+.IX Item "s"
+Add an index to the archive, or update it if it already exists.  Note
+this command is an exception to the rule that there can only be one
+command letter, as it is possible to use it as either a command or a
+modifier.  In either case it does the same thing.
+.IP "\fBt\fR" 4
+.IX Item "t"
+Display a \fItable\fR listing the contents of \fIarchive\fR, or those
+of the files listed in \fImember\fR... that are present in the
+archive.  Normally only the member name is shown, but if the modifier
+\&\fBO\fR is specified, then the corresponding offset of the member is also
+displayed.  Finally, in order to see the modes (permissions), timestamp,
+owner, group, and size the \fBv\fR modifier should be included.
+.Sp
+If you do not specify a \fImember\fR, all files in the archive
+are listed.
+.Sp
+If there is more than one file with the same name (say, \fBfie\fR) in
+an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
+first instance; to see them all, you must ask for a complete
+listing\-\-\-in our example, \fBar t b.a\fR.
+.IP "\fBx\fR" 4
+.IX Item "x"
+\&\fIExtract\fR members (named \fImember\fR) from the archive.  You can
+use the \fBv\fR modifier with this operation, to request that
+\&\fBar\fR list each name as it extracts it.
+.Sp
+If you do not specify a \fImember\fR, all files in the archive
+are extracted.
+.Sp
+Files cannot be extracted from a thin archive, and there are
+restrictions on extracting from archives created with \fBP\fR: The
+paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any
+subdirectories in the paths must exist.  If it is desired to avoid
+these restrictions then used the \fB\-\-output\fR option to specify
+an output directory.
+.PP
+A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
+keyletter, to specify variations on an operation's behavior:
+.IP "\fBa\fR" 4
+.IX Item "a"
+Add new files \fIafter\fR an existing member of the
+archive.  If you use the modifier \fBa\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.
+.IP "\fBb\fR" 4
+.IX Item "b"
+Add new files \fIbefore\fR an existing member of the
+archive.  If you use the modifier \fBb\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.  (same as \fBi\fR).
+.IP "\fBc\fR" 4
+.IX Item "c"
+\&\fICreate\fR the archive.  The specified \fIarchive\fR is always
+created if it did not exist, when you request an update.  But a warning is
+issued unless you specify in advance that you expect to create it, by
+using this modifier.
+.IP "\fBD\fR" 4
+.IX Item "D"
+Operate in \fIdeterministic\fR mode.  When adding files and the archive
+index use zero for UIDs, GIDs, timestamps, and use consistent file modes
+for all files.  When this option is used, if \fBar\fR is used with
+identical options and identical input files, multiple runs will create
+identical output files regardless of the input files' owners, groups,
+file modes, or modification times.
+.Sp
+If \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
+It can be disabled with the \fBU\fR modifier, below.
+.IP "\fBf\fR" 4
+.IX Item "f"
+Truncate names in the archive.  \s-1GNU\s0 \fBar\fR will normally permit file
+names of any length.  This will cause it to create archives which are
+not compatible with the native \fBar\fR program on some systems.  If
+this is a concern, the \fBf\fR modifier may be used to truncate file
+names when putting them in the archive.
+.IP "\fBi\fR" 4
+.IX Item "i"
+Insert new files \fIbefore\fR an existing member of the
+archive.  If you use the modifier \fBi\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.  (same as \fBb\fR).
+.IP "\fBl\fR" 4
+.IX Item "l"
+Specify dependencies of this library.  The dependencies must immediately
+follow this option character, must use the same syntax as the linker
+command line, and must be specified within a single argument.  I.e., if
+multiple items are needed, they must be quoted to form a single command
+line argument.  For example \fBL \*(L"\-L/usr/local/lib \-lmydep1 \-lmydep2\*(R"\fR
+.IP "\fBN\fR" 4
+.IX Item "N"
+Uses the \fIcount\fR parameter.  This is used if there are multiple
+entries in the archive with the same name.  Extract or delete instance
+\&\fIcount\fR of the given name from the archive.
+.IP "\fBo\fR" 4
+.IX Item "o"
+Preserve the \fIoriginal\fR dates of members when extracting them.  If
+you do not specify this modifier, files extracted from the archive
+are stamped with the time of extraction.
+.IP "\fBO\fR" 4
+.IX Item "O"
+Display member offsets inside the archive. Use together with the \fBt\fR
+option.
+.IP "\fBP\fR" 4
+.IX Item "P"
+Use the full path name when matching or storing names in the archive.
+Archives created with full path names are not \s-1POSIX\s0 compliant, and
+thus may not work with tools other than up to date \s-1GNU\s0 tools.
+Modifying such archives with \s-1GNU\s0 \fBar\fR without using
+\&\fBP\fR will remove the full path names unless the archive is a
+thin archive.  Note that \fBP\fR may be useful when adding files to
+a thin archive since \fBr\fR without \fBP\fR ignores the path
+when choosing which element to replace.  Thus
+.Sp
+.Vb 1
+\&        ar rcST archive.a subdir/file1 subdir/file2 file1
+.Ve
+.Sp
+will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with
+\&\f(CW\*(C`file1\*(C'\fR from the current directory.  Adding \fBP\fR will
+prevent this replacement.
+.IP "\fBs\fR" 4
+.IX Item "s"
+Write an object-file index into the archive, or update an existing one,
+even if no other change is made to the archive.  You may use this modifier
+flag either with any operation, or alone.  Running \fBar s\fR on an
+archive is equivalent to running \fBranlib\fR on it.
+.IP "\fBS\fR" 4
+.IX Item "S"
+Do not generate an archive symbol table.  This can speed up building a
+large library in several steps.  The resulting archive can not be used
+with the linker.  In order to build a symbol table, you must omit the
+\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
+\&\fBranlib\fR on the archive.
+.IP "\fBT\fR" 4
+.IX Item "T"
+Deprecated alias for \fB\-\-thin\fR.  \fBT\fR is not recommended because in
+many ar implementations \fBT\fR has a different meaning, as specified by
+X/Open System Interface.
+.IP "\fBu\fR" 4
+.IX Item "u"
+Normally, \fBar r\fR... inserts all files
+listed into the archive.  If you would like to insert \fIonly\fR those
+of the files you list that are newer than existing members of the same
+names, use this modifier.  The \fBu\fR modifier is allowed only for the
+operation \fBr\fR (replace).  In particular, the combination \fBqu\fR is
+not allowed, since checking the timestamps would lose any speed
+advantage from the operation \fBq\fR.
+.IP "\fBU\fR" 4
+.IX Item "U"
+Do \fInot\fR operate in \fIdeterministic\fR mode.  This is the inverse
+of the \fBD\fR modifier, above: added files and the archive index will
+get their actual \s-1UID, GID,\s0 timestamp, and file mode values.
+.Sp
+This is the default unless \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR.
+.IP "\fBv\fR" 4
+.IX Item "v"
+This modifier requests the \fIverbose\fR version of an operation.  Many
+operations display additional information, such as filenames processed,
+when the modifier \fBv\fR is appended.
+.IP "\fBV\fR" 4
+.IX Item "V"
+This modifier shows the version number of \fBar\fR.
+.PP
+The \fBar\fR program also supports some command-line options which
+are neither modifiers nor actions, but which do change its behaviour
+in specific ways:
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Displays the list of command-line options supported by \fBar\fR
+and then exits.
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+Displays the version information of \fBar\fR and then exits.
+.IP "\fB\-X32_64\fR" 4
+.IX Item "-X32_64"
+\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
+compatibility with \s-1AIX.\s0  The behaviour produced by this option is the
+default for \s-1GNU\s0 \fBar\fR.  \fBar\fR does not support any
+of the other \fB\-X\fR options; in particular, it does not support
+\&\fB\-X32\fR which is the default for \s-1AIX\s0 \fBar\fR.
+.IP "\fB\-\-plugin\fR \fIname\fR" 4
+.IX Item "--plugin name"
+The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes
+\&\fBar\fR to load the plugin called \fIname\fR which adds support
+for more file formats, including object files with link-time
+optimization information.
+.Sp
+This option is only available if the toolchain has been built with
+plugin support enabled.
+.Sp
+If \fB\-\-plugin\fR is not provided, but plugin support has been
+enabled then \fBar\fR iterates over the files in
+\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
+plugin that claims the object in question is used.
+.Sp
+Please note that this plugin search directory is \fInot\fR the one
+used by \fBld\fR's \fB\-plugin\fR option.  In order to make
+\&\fBar\fR use the  linker plugin it must be copied into the
+\&\fI${libdir}/bfd\-plugins\fR directory.  For \s-1GCC\s0 based compilations
+the linker plugin is called \fIliblto_plugin.so.0.0.0\fR.  For Clang
+based compilations it is called \fILLVMgold.so\fR.  The \s-1GCC\s0 plugin
+is always backwards compatible with earlier versions, so it is
+sufficient to just copy the newest one.
+.IP "\fB\-\-target\fR \fItarget\fR" 4
+.IX Item "--target target"
+The optional command-line switch \fB\-\-target\fR \fIbfdname\fR
+specifies that the archive members are in an object code format
+different from your system's default format.  See
+.IP "\fB\-\-output\fR \fIdirname\fR" 4
+.IX Item "--output dirname"
+The \fB\-\-output\fR option can be used to specify a path to a
+directory into which archive members should be extracted.  If this
+option is not specified then the current directory will be used.
+.Sp
+Note \- although the presence of this option does imply a \fBx\fR 
+extraction operation that option must still be included on the command
+line.
+.IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4
+.IX Item "--record-libdeps libdeps"
+The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier,
+just handled in long form.
+.IP "\fB\-\-thin\fR" 4
+.IX Item "--thin"
+Make the specified \fIarchive\fR a \fIthin\fR archive.  If it already
+exists and is a regular archive, the existing members must be present
+in the same directory as \fIarchive\fR.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/arch.1 b/upstream/mageia-cauldron/man1/arch.1
new file mode 100644
index 00000000..fbb6fbd6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/arch.1
@@ -0,0 +1,36 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH ARCH "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+arch \- print machine hardware name (same as uname -m)
+.SH SYNOPSIS
+.B arch
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print machine architecture.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie and Karel Zak.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBuname\fP(1), \fBuname\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/arch>
+.br
+or available locally via: info \(aq(coreutils) arch invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/as.1 b/upstream/mageia-cauldron/man1/as.1
new file mode 100644
index 00000000..c7c2a85a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/as.1
@@ -0,0 +1,3038 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "AS 1"
+.TH AS 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+AS \- the portable GNU assembler.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+as [\fB\-a\fR[\fBcdghlns\fR][=\fIfile\fR]]
+ [\fB\-\-alternate\fR]
+ [\fB\-\-compress\-debug\-sections\fR] [\fB\-\-nocompress\-debug\-sections\fR]
+ [\fB\-D\fR]
+ [\fB\-\-dump\-config\fR]
+ [\fB\-\-debug\-prefix\-map\fR \fIold\fR=\fInew\fR]
+ [\fB\-\-defsym\fR \fIsym\fR=\fIval\fR]
+ [\fB\-\-elf\-stt\-common=[no|yes]\fR]
+ [\fB\-\-emulation\fR=\fIname\fR]
+ [\fB\-f\fR]
+ [\fB\-g\fR] [\fB\-\-gstabs\fR] [\fB\-\-gstabs+\fR]
+ [\fB\-\-gdwarf\-<N>\fR] [\fB\-\-gdwarf\-sections\fR]
+ [\fB\-\-gdwarf\-cie\-version\fR=\fI\s-1VERSION\s0\fR]
+ [\fB\-\-generate\-missing\-build\-notes=[no|yes]\fR]
+ [\fB\-\-gsframe\fR]
+ [\fB\-\-hash\-size\fR=\fIN\fR]
+ [\fB\-\-help\fR] [\fB\-\-target\-help\fR]
+ [\fB\-I\fR \fIdir\fR]
+ [\fB\-J\fR]
+ [\fB\-K\fR]
+ [\fB\-\-keep\-locals\fR]
+ [\fB\-L\fR]
+ [\fB\-\-listing\-lhs\-width\fR=\fI\s-1NUM\s0\fR]
+ [\fB\-\-listing\-lhs\-width2\fR=\fI\s-1NUM\s0\fR]
+ [\fB\-\-listing\-rhs\-width\fR=\fI\s-1NUM\s0\fR]
+ [\fB\-\-listing\-cont\-lines\fR=\fI\s-1NUM\s0\fR]
+ [\fB\-\-multibyte\-handling=[allow|warn|warn\-sym\-only]\fR]
+ [\fB\-\-no\-pad\-sections\fR]
+ [\fB\-o\fR \fIobjfile\fR] [\fB\-R\fR]
+ [\fB\-\-sectname\-subst\fR]
+ [\fB\-\-size\-check=[error|warning]\fR]
+ [\fB\-\-statistics\fR]
+ [\fB\-v\fR] [\fB\-version\fR] [\fB\-\-version\fR]
+ [\fB\-W\fR] [\fB\-\-warn\fR] [\fB\-\-fatal\-warnings\fR] [\fB\-w\fR] [\fB\-x\fR]
+ [\fB\-Z\fR] [\fB@\fR\fI\s-1FILE\s0\fR]
+ [\fItarget-options\fR]
+ [\fB\-\-\fR|\fIfiles\fR ...]
+.SH "TARGET"
+.IX Header "TARGET"
+\&\fITarget AArch64 options:\fR
+   [\fB\-EB\fR|\fB\-EL\fR]
+   [\fB\-mabi\fR=\fI\s-1ABI\s0\fR]
+.PP
+\&\fITarget Alpha options:\fR
+   [\fB\-m\fR\fIcpu\fR]
+   [\fB\-mdebug\fR | \fB\-no\-mdebug\fR]
+   [\fB\-replace\fR | \fB\-noreplace\fR]
+   [\fB\-relax\fR] [\fB\-g\fR] [\fB\-G\fR\fIsize\fR]
+   [\fB\-F\fR] [\fB\-32addr\fR]
+.PP
+\&\fITarget \s-1ARC\s0 options:\fR
+   [\fB\-mcpu=\fR\fIcpu\fR]
+   [\fB\-mA6\fR|\fB\-mARC600\fR|\fB\-mARC601\fR|\fB\-mA7\fR|\fB\-mARC700\fR|\fB\-mEM\fR|\fB\-mHS\fR]
+   [\fB\-mcode\-density\fR]
+   [\fB\-mrelax\fR]
+   [\fB\-EB\fR|\fB\-EL\fR]
+.PP
+\&\fITarget \s-1ARM\s0 options:\fR
+   [\fB\-mcpu\fR=\fIprocessor\fR[+\fIextension\fR...]]
+   [\fB\-march\fR=\fIarchitecture\fR[+\fIextension\fR...]]
+   [\fB\-mfpu\fR=\fIfloating-point-format\fR]
+   [\fB\-mfloat\-abi\fR=\fIabi\fR]
+   [\fB\-meabi\fR=\fIver\fR]
+   [\fB\-mthumb\fR]
+   [\fB\-EB\fR|\fB\-EL\fR]
+   [\fB\-mapcs\-32\fR|\fB\-mapcs\-26\fR|\fB\-mapcs\-float\fR|
+    \fB\-mapcs\-reentrant\fR]
+   [\fB\-mthumb\-interwork\fR] [\fB\-k\fR]
+.PP
+\&\fITarget Blackfin options:\fR
+   [\fB\-mcpu\fR=\fIprocessor\fR[\-\fIsirevision\fR]]
+   [\fB\-mfdpic\fR]
+   [\fB\-mno\-fdpic\fR]
+   [\fB\-mnopic\fR]
+.PP
+\&\fITarget \s-1BPF\s0 options:\fR
+   [\fB\-EL\fR] [\fB\-EB\fR]
+.PP
+\&\fITarget \s-1CRIS\s0 options:\fR
+   [\fB\-\-underscore\fR | \fB\-\-no\-underscore\fR]
+   [\fB\-\-pic\fR] [\fB\-N\fR]
+   [\fB\-\-emulation=criself\fR | \fB\-\-emulation=crisaout\fR]
+   [\fB\-\-march=v0_v10\fR | \fB\-\-march=v10\fR | \fB\-\-march=v32\fR | \fB\-\-march=common_v10_v32\fR]
+.PP
+\&\fITarget C\-SKY options:\fR
+   [\fB\-march=\fR\fIarch\fR] [\fB\-mcpu=\fR\fIcpu\fR]
+   [\fB\-EL\fR] [\fB\-mlittle\-endian\fR] [\fB\-EB\fR] [\fB\-mbig\-endian\fR]
+   [\fB\-fpic\fR] [\fB\-pic\fR]
+   [\fB\-mljump\fR] [\fB\-mno\-ljump\fR]
+   [\fB\-force2bsr\fR] [\fB\-mforce2bsr\fR] [\fB\-no\-force2bsr\fR] [\fB\-mno\-force2bsr\fR]
+   [\fB\-jsri2bsr\fR] [\fB\-mjsri2bsr\fR] [\fB\-no\-jsri2bsr\fR ] [\fB\-mno\-jsri2bsr\fR]
+   [\fB\-mnolrw\fR ] [\fB\-mno\-lrw\fR]
+   [\fB\-melrw\fR] [\fB\-mno\-elrw\fR]
+   [\fB\-mlaf\fR ] [\fB\-mliterals\-after\-func\fR]
+   [\fB\-mno\-laf\fR] [\fB\-mno\-literals\-after\-func\fR]
+   [\fB\-mlabr\fR] [\fB\-mliterals\-after\-br\fR]
+   [\fB\-mno\-labr\fR] [\fB\-mnoliterals\-after\-br\fR]
+   [\fB\-mistack\fR] [\fB\-mno\-istack\fR]
+   [\fB\-mhard\-float\fR] [\fB\-mmp\fR] [\fB\-mcp\fR] [\fB\-mcache\fR]
+   [\fB\-msecurity\fR] [\fB\-mtrust\fR]
+   [\fB\-mdsp\fR] [\fB\-medsp\fR] [\fB\-mvdsp\fR]
+.PP
+\&\fITarget D10V options:\fR
+   [\fB\-O\fR]
+.PP
+\&\fITarget D30V options:\fR
+   [\fB\-O\fR|\fB\-n\fR|\fB\-N\fR]
+.PP
+\&\fITarget \s-1EPIPHANY\s0 options:\fR
+   [\fB\-mepiphany\fR|\fB\-mepiphany16\fR]
+.PP
+\&\fITarget H8/300 options:\fR
+   [\-h\-tick\-hex]
+.PP
+\&\fITarget i386 options:\fR
+   [\fB\-\-32\fR|\fB\-\-x32\fR|\fB\-\-64\fR] [\fB\-n\fR]
+   [\fB\-march\fR=\fI\s-1CPU\s0\fR[+\fI\s-1EXTENSION\s0\fR...]] [\fB\-mtune\fR=\fI\s-1CPU\s0\fR]
+.PP
+\&\fITarget \s-1IA\-64\s0 options:\fR
+   [\fB\-mconstant\-gp\fR|\fB\-mauto\-pic\fR]
+   [\fB\-milp32\fR|\fB\-milp64\fR|\fB\-mlp64\fR|\fB\-mp64\fR]
+   [\fB\-mle\fR|\fBmbe\fR]
+   [\fB\-mtune=itanium1\fR|\fB\-mtune=itanium2\fR]
+   [\fB\-munwind\-check=warning\fR|\fB\-munwind\-check=error\fR]
+   [\fB\-mhint.b=ok\fR|\fB\-mhint.b=warning\fR|\fB\-mhint.b=error\fR]
+   [\fB\-x\fR|\fB\-xexplicit\fR] [\fB\-xauto\fR] [\fB\-xdebug\fR]
+.PP
+\&\fITarget \s-1IP2K\s0 options:\fR
+   [\fB\-mip2022\fR|\fB\-mip2022ext\fR]
+.PP
+\&\fITarget M32C options:\fR
+   [\fB\-m32c\fR|\fB\-m16c\fR] [\-relax] [\-h\-tick\-hex]
+.PP
+\&\fITarget M32R options:\fR
+   [\fB\-\-m32rx\fR|\fB\-\-[no\-]warn\-explicit\-parallel\-conflicts\fR|
+   \fB\-\-W[n]p\fR]
+.PP
+\&\fITarget M680X0 options:\fR
+   [\fB\-l\fR] [\fB\-m68000\fR|\fB\-m68010\fR|\fB\-m68020\fR|...]
+.PP
+\&\fITarget M68HC11 options:\fR
+   [\fB\-m68hc11\fR|\fB\-m68hc12\fR|\fB\-m68hcs12\fR|\fB\-mm9s12x\fR|\fB\-mm9s12xg\fR]
+   [\fB\-mshort\fR|\fB\-mlong\fR]
+   [\fB\-mshort\-double\fR|\fB\-mlong\-double\fR]
+   [\fB\-\-force\-long\-branches\fR] [\fB\-\-short\-branches\fR]
+   [\fB\-\-strict\-direct\-mode\fR] [\fB\-\-print\-insn\-syntax\fR]
+   [\fB\-\-print\-opcodes\fR] [\fB\-\-generate\-example\fR]
+.PP
+\&\fITarget \s-1MCORE\s0 options:\fR
+   [\fB\-jsri2bsr\fR] [\fB\-sifilter\fR] [\fB\-relax\fR]
+   [\fB\-mcpu=[210|340]\fR]
+.PP
+\&\fITarget Meta options:\fR
+   [\fB\-mcpu=\fR\fIcpu\fR] [\fB\-mfpu=\fR\fIcpu\fR] [\fB\-mdsp=\fR\fIcpu\fR]
+\&\fITarget \s-1MICROBLAZE\s0 options:\fR
+.PP
+\&\fITarget \s-1MIPS\s0 options:\fR
+   [\fB\-nocpp\fR] [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR[\fIoptimization level\fR]]
+   [\fB\-g\fR[\fIdebug level\fR]] [\fB\-G\fR \fInum\fR] [\fB\-KPIC\fR] [\fB\-call_shared\fR]
+   [\fB\-non_shared\fR] [\fB\-xgot\fR [\fB\-mvxworks\-pic\fR]
+   [\fB\-mabi\fR=\fI\s-1ABI\s0\fR] [\fB\-32\fR] [\fB\-n32\fR] [\fB\-64\fR] [\fB\-mfp32\fR] [\fB\-mgp32\fR]
+   [\fB\-mfp64\fR] [\fB\-mgp64\fR] [\fB\-mfpxx\fR]
+   [\fB\-modd\-spreg\fR] [\fB\-mno\-odd\-spreg\fR]
+   [\fB\-march\fR=\fI\s-1CPU\s0\fR] [\fB\-mtune\fR=\fI\s-1CPU\s0\fR] [\fB\-mips1\fR] [\fB\-mips2\fR]
+   [\fB\-mips3\fR] [\fB\-mips4\fR] [\fB\-mips5\fR] [\fB\-mips32\fR] [\fB\-mips32r2\fR]
+   [\fB\-mips32r3\fR] [\fB\-mips32r5\fR] [\fB\-mips32r6\fR] [\fB\-mips64\fR] [\fB\-mips64r2\fR]
+   [\fB\-mips64r3\fR] [\fB\-mips64r5\fR] [\fB\-mips64r6\fR]
+   [\fB\-construct\-floats\fR] [\fB\-no\-construct\-floats\fR]
+   [\fB\-mignore\-branch\-isa\fR] [\fB\-mno\-ignore\-branch\-isa\fR]
+   [\fB\-mnan=\fR\fIencoding\fR]
+   [\fB\-trap\fR] [\fB\-no\-break\fR] [\fB\-break\fR] [\fB\-no\-trap\fR]
+   [\fB\-mips16\fR] [\fB\-no\-mips16\fR]
+   [\fB\-mmips16e2\fR] [\fB\-mno\-mips16e2\fR]
+   [\fB\-mmicromips\fR] [\fB\-mno\-micromips\fR]
+   [\fB\-msmartmips\fR] [\fB\-mno\-smartmips\fR]
+   [\fB\-mips3d\fR] [\fB\-no\-mips3d\fR]
+   [\fB\-mdmx\fR] [\fB\-no\-mdmx\fR]
+   [\fB\-mdsp\fR] [\fB\-mno\-dsp\fR]
+   [\fB\-mdspr2\fR] [\fB\-mno\-dspr2\fR]
+   [\fB\-mdspr3\fR] [\fB\-mno\-dspr3\fR]
+   [\fB\-mmsa\fR] [\fB\-mno\-msa\fR]
+   [\fB\-mxpa\fR] [\fB\-mno\-xpa\fR]
+   [\fB\-mmt\fR] [\fB\-mno\-mt\fR]
+   [\fB\-mmcu\fR] [\fB\-mno\-mcu\fR]
+   [\fB\-mcrc\fR] [\fB\-mno\-crc\fR]
+   [\fB\-mginv\fR] [\fB\-mno\-ginv\fR]
+   [\fB\-mloongson\-mmi\fR] [\fB\-mno\-loongson\-mmi\fR]
+   [\fB\-mloongson\-cam\fR] [\fB\-mno\-loongson\-cam\fR]
+   [\fB\-mloongson\-ext\fR] [\fB\-mno\-loongson\-ext\fR]
+   [\fB\-mloongson\-ext2\fR] [\fB\-mno\-loongson\-ext2\fR]
+   [\fB\-minsn32\fR] [\fB\-mno\-insn32\fR]
+   [\fB\-mfix7000\fR] [\fB\-mno\-fix7000\fR]
+   [\fB\-mfix\-rm7000\fR] [\fB\-mno\-fix\-rm7000\fR]
+   [\fB\-mfix\-vr4120\fR] [\fB\-mno\-fix\-vr4120\fR]
+   [\fB\-mfix\-vr4130\fR] [\fB\-mno\-fix\-vr4130\fR]
+   [\fB\-mfix\-r5900\fR] [\fB\-mno\-fix\-r5900\fR]
+   [\fB\-mdebug\fR] [\fB\-no\-mdebug\fR]
+   [\fB\-mpdr\fR] [\fB\-mno\-pdr\fR]
+.PP
+\&\fITarget \s-1MMIX\s0 options:\fR
+   [\fB\-\-fixed\-special\-register\-names\fR] [\fB\-\-globalize\-symbols\fR]
+   [\fB\-\-gnu\-syntax\fR] [\fB\-\-relax\fR] [\fB\-\-no\-predefined\-symbols\fR]
+   [\fB\-\-no\-expand\fR] [\fB\-\-no\-merge\-gregs\fR] [\fB\-x\fR]
+   [\fB\-\-linker\-allocated\-gregs\fR]
+.PP
+\&\fITarget Nios \s-1II\s0 options:\fR
+   [\fB\-relax\-all\fR] [\fB\-relax\-section\fR] [\fB\-no\-relax\fR]
+   [\fB\-EB\fR] [\fB\-EL\fR]
+.PP
+\&\fITarget \s-1NDS32\s0 options:\fR
+    [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR] [\fB\-Os\fR] [\fB\-mcpu=\fR\fIcpu\fR]
+    [\fB\-misa=\fR\fIisa\fR] [\fB\-mabi=\fR\fIabi\fR] [\fB\-mall\-ext\fR]
+    [\fB\-m[no\-]16\-bit\fR]  [\fB\-m[no\-]perf\-ext\fR] [\fB\-m[no\-]perf2\-ext\fR]
+    [\fB\-m[no\-]string\-ext\fR] [\fB\-m[no\-]dsp\-ext\fR] [\fB\-m[no\-]mac\fR] [\fB\-m[no\-]div\fR]
+    [\fB\-m[no\-]audio\-isa\-ext\fR] [\fB\-m[no\-]fpu\-sp\-ext\fR] [\fB\-m[no\-]fpu\-dp\-ext\fR]
+    [\fB\-m[no\-]fpu\-fma\fR] [\fB\-mfpu\-freg=\fR\fI\s-1FREG\s0\fR] [\fB\-mreduced\-regs\fR]
+    [\fB\-mfull\-regs\fR] [\fB\-m[no\-]dx\-regs\fR] [\fB\-mpic\fR] [\fB\-mno\-relax\fR]
+    [\fB\-mb2bb\fR]
+.PP
+\&\fITarget \s-1PDP11\s0 options:\fR
+   [\fB\-mpic\fR|\fB\-mno\-pic\fR] [\fB\-mall\fR] [\fB\-mno\-extensions\fR]
+   [\fB\-m\fR\fIextension\fR|\fB\-mno\-\fR\fIextension\fR]
+   [\fB\-m\fR\fIcpu\fR] [\fB\-m\fR\fImachine\fR]
+.PP
+\&\fITarget picoJava options:\fR
+   [\fB\-mb\fR|\fB\-me\fR]
+.PP
+\&\fITarget PowerPC options:\fR
+   [\fB\-a32\fR|\fB\-a64\fR]
+   [\fB\-mpwrx\fR|\fB\-mpwr2\fR|\fB\-mpwr\fR|\fB\-m601\fR|\fB\-mppc\fR|\fB\-mppc32\fR|\fB\-m603\fR|\fB\-m604\fR|\fB\-m403\fR|\fB\-m405\fR|
+    \fB\-m440\fR|\fB\-m464\fR|\fB\-m476\fR|\fB\-m7400\fR|\fB\-m7410\fR|\fB\-m7450\fR|\fB\-m7455\fR|\fB\-m750cl\fR|\fB\-mgekko\fR|
+    \fB\-mbroadway\fR|\fB\-mppc64\fR|\fB\-m620\fR|\fB\-me500\fR|\fB\-e500x2\fR|\fB\-me500mc\fR|\fB\-me500mc64\fR|\fB\-me5500\fR|
+    \fB\-me6500\fR|\fB\-mppc64bridge\fR|\fB\-mbooke\fR|\fB\-mpower4\fR|\fB\-mpwr4\fR|\fB\-mpower5\fR|\fB\-mpwr5\fR|\fB\-mpwr5x\fR|
+    \fB\-mpower6\fR|\fB\-mpwr6\fR|\fB\-mpower7\fR|\fB\-mpwr7\fR|\fB\-mpower8\fR|\fB\-mpwr8\fR|\fB\-mpower9\fR|\fB\-mpwr9\fR\fB\-ma2\fR|
+    \fB\-mcell\fR|\fB\-mspe\fR|\fB\-mspe2\fR|\fB\-mtitan\fR|\fB\-me300\fR|\fB\-mcom\fR]
+   [\fB\-many\fR] [\fB\-maltivec\fR|\fB\-mvsx\fR|\fB\-mhtm\fR|\fB\-mvle\fR]
+   [\fB\-mregnames\fR|\fB\-mno\-regnames\fR]
+   [\fB\-mrelocatable\fR|\fB\-mrelocatable\-lib\fR|\fB\-K \s-1PIC\s0\fR] [\fB\-memb\fR]
+   [\fB\-mlittle\fR|\fB\-mlittle\-endian\fR|\fB\-le\fR|\fB\-mbig\fR|\fB\-mbig\-endian\fR|\fB\-be\fR]
+   [\fB\-msolaris\fR|\fB\-mno\-solaris\fR]
+   [\fB\-nops=\fR\fIcount\fR]
+.PP
+\&\fITarget \s-1PRU\s0 options:\fR
+   [\fB\-link\-relax\fR]
+   [\fB\-mnolink\-relax\fR]
+   [\fB\-mno\-warn\-regname\-label\fR]
+.PP
+\&\fITarget RISC-V options:\fR
+   [\fB\-fpic\fR|\fB\-fPIC\fR|\fB\-fno\-pic\fR]
+   [\fB\-march\fR=\fI\s-1ISA\s0\fR]
+   [\fB\-mabi\fR=\fI\s-1ABI\s0\fR]
+   [\fB\-mlittle\-endian\fR|\fB\-mbig\-endian\fR]
+.PP
+\&\fITarget \s-1RL78\s0 options:\fR
+   [\fB\-mg10\fR]
+   [\fB\-m32bit\-doubles\fR|\fB\-m64bit\-doubles\fR]
+.PP
+\&\fITarget \s-1RX\s0 options:\fR
+   [\fB\-mlittle\-endian\fR|\fB\-mbig\-endian\fR]
+   [\fB\-m32bit\-doubles\fR|\fB\-m64bit\-doubles\fR]
+   [\fB\-muse\-conventional\-section\-names\fR]
+   [\fB\-msmall\-data\-limit\fR]
+   [\fB\-mpid\fR]
+   [\fB\-mrelax\fR]
+   [\fB\-mint\-register=\fR\fInumber\fR]
+   [\fB\-mgcc\-abi\fR|\fB\-mrx\-abi\fR]
+.PP
+\&\fITarget s390 options:\fR
+   [\fB\-m31\fR|\fB\-m64\fR] [\fB\-mesa\fR|\fB\-mzarch\fR] [\fB\-march\fR=\fI\s-1CPU\s0\fR]
+   [\fB\-mregnames\fR|\fB\-mno\-regnames\fR]
+   [\fB\-mwarn\-areg\-zero\fR]
+.PP
+\&\fITarget \s-1SCORE\s0 options:\fR
+   [\fB\-EB\fR][\fB\-EL\fR][\fB\-FIXDD\fR][\fB\-NWARN\fR]
+   [\fB\-SCORE5\fR][\fB\-SCORE5U\fR][\fB\-SCORE7\fR][\fB\-SCORE3\fR]
+   [\fB\-march=score7\fR][\fB\-march=score3\fR]
+   [\fB\-USE_R1\fR][\fB\-KPIC\fR][\fB\-O0\fR][\fB\-G\fR \fInum\fR][\fB\-V\fR]
+.PP
+\&\fITarget \s-1SPARC\s0 options:\fR
+   [\fB\-Av6\fR|\fB\-Av7\fR|\fB\-Av8\fR|\fB\-Aleon\fR|\fB\-Asparclet\fR|\fB\-Asparclite\fR
+    \fB\-Av8plus\fR|\fB\-Av8plusa\fR|\fB\-Av8plusb\fR|\fB\-Av8plusc\fR|\fB\-Av8plusd\fR
+    \fB\-Av8plusv\fR|\fB\-Av8plusm\fR|\fB\-Av9\fR|\fB\-Av9a\fR|\fB\-Av9b\fR|\fB\-Av9c\fR
+    \fB\-Av9d\fR|\fB\-Av9e\fR|\fB\-Av9v\fR|\fB\-Av9m\fR|\fB\-Asparc\fR|\fB\-Asparcvis\fR
+    \fB\-Asparcvis2\fR|\fB\-Asparcfmaf\fR|\fB\-Asparcima\fR|\fB\-Asparcvis3\fR
+    \fB\-Asparcvisr\fR|\fB\-Asparc5\fR]
+   [\fB\-xarch=v8plus\fR|\fB\-xarch=v8plusa\fR]|\fB\-xarch=v8plusb\fR|\fB\-xarch=v8plusc\fR
+    \fB\-xarch=v8plusd\fR|\fB\-xarch=v8plusv\fR|\fB\-xarch=v8plusm\fR|\fB\-xarch=v9\fR
+    \fB\-xarch=v9a\fR|\fB\-xarch=v9b\fR|\fB\-xarch=v9c\fR|\fB\-xarch=v9d\fR|\fB\-xarch=v9e\fR
+    \fB\-xarch=v9v\fR|\fB\-xarch=v9m\fR|\fB\-xarch=sparc\fR|\fB\-xarch=sparcvis\fR
+    \fB\-xarch=sparcvis2\fR|\fB\-xarch=sparcfmaf\fR|\fB\-xarch=sparcima\fR
+    \fB\-xarch=sparcvis3\fR|\fB\-xarch=sparcvisr\fR|\fB\-xarch=sparc5\fR
+    \fB\-bump\fR]
+   [\fB\-32\fR|\fB\-64\fR]
+   [\fB\-\-enforce\-aligned\-data\fR][\fB\-\-dcti\-couples\-detect\fR]
+.PP
+\&\fITarget \s-1TIC54X\s0 options:\fR
+ [\fB\-mcpu=54[123589]\fR|\fB\-mcpu=54[56]lp\fR] [\fB\-mfar\-mode\fR|\fB\-mf\fR]
+ [\fB\-merrors\-to\-file\fR \fI<filename>\fR|\fB\-me\fR \fI<filename>\fR]
+.PP
+\&\fITarget \s-1TIC6X\s0 options:\fR
+   [\fB\-march=\fR\fIarch\fR] [\fB\-mbig\-endian\fR|\fB\-mlittle\-endian\fR]
+   [\fB\-mdsbt\fR|\fB\-mno\-dsbt\fR] [\fB\-mpid=no\fR|\fB\-mpid=near\fR|\fB\-mpid=far\fR]
+   [\fB\-mpic\fR|\fB\-mno\-pic\fR]
+.PP
+\&\fITarget TILE-Gx options:\fR
+   [\fB\-m32\fR|\fB\-m64\fR][\fB\-EB\fR][\fB\-EL\fR]
+.PP
+\&\fITarget Visium options:\fR
+   [\fB\-mtune=\fR\fIarch\fR]
+.PP
+\&\fITarget Xtensa options:\fR
+ [\fB\-\-[no\-]text\-section\-literals\fR] [\fB\-\-[no\-]auto\-litpools\fR]
+ [\fB\-\-[no\-]absolute\-literals\fR]
+ [\fB\-\-[no\-]target\-align\fR] [\fB\-\-[no\-]longcalls\fR]
+ [\fB\-\-[no\-]transform\fR]
+ [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR]
+ [\fB\-\-[no\-]trampolines\fR]
+ [\fB\-\-abi\-windowed\fR|\fB\-\-abi\-call0\fR]
+.PP
+\&\fITarget Z80 options:\fR
+  [\fB\-march=\fR\fI\s-1CPU\s0\fR\fI[\-EXT]\fR\fI[+EXT]\fR]
+  [\fB\-local\-prefix=\fR\fI\s-1PREFIX\s0\fR]
+  [\fB\-colonless\fR]
+  [\fB\-sdcc\fR]
+  [\fB\-fp\-s=\fR\fI\s-1FORMAT\s0\fR]
+  [\fB\-fp\-d=\fR\fI\s-1FORMAT\s0\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\s-1GNU\s0 \fBas\fR is really a family of assemblers.
+If you use (or have used) the \s-1GNU\s0 assembler on one architecture, you
+should find a fairly similar environment when you use it on another
+architecture.  Each version has much in common with the others,
+including object file formats, most assembler directives (often called
+\&\fIpseudo-ops\fR) and assembler syntax.
+.PP
+\&\fBas\fR is primarily intended to assemble the output of the
+\&\s-1GNU C\s0 compiler \f(CW\*(C`gcc\*(C'\fR for use by the linker
+\&\f(CW\*(C`ld\*(C'\fR.  Nevertheless, we've tried to make \fBas\fR
+assemble correctly everything that other assemblers for the same
+machine would assemble.
+Any exceptions are documented explicitly.
+This doesn't mean \fBas\fR always uses the same syntax as another
+assembler for the same architecture; for example, we know of several
+incompatible versions of 680x0 assembly language syntax.
+.PP
+Each time you run \fBas\fR it assembles exactly one source
+program.  The source program is made up of one or more files.
+(The standard input is also a file.)
+.PP
+You give \fBas\fR a command line that has zero or more input file
+names.  The input files are read (from left file name to right).  A
+command-line argument (in any position) that has no special meaning
+is taken to be an input file name.
+.PP
+If you give \fBas\fR no file names it attempts to read one input file
+from the \fBas\fR standard input, which is normally your terminal.  You
+may have to type \fBctl-D\fR to tell \fBas\fR there is no more program
+to assemble.
+.PP
+Use \fB\-\-\fR if you need to explicitly name the standard input file
+in your command line.
+.PP
+If the source is empty, \fBas\fR produces a small, empty object
+file.
+.PP
+\&\fBas\fR may write warnings and error messages to the standard error
+file (usually your terminal).  This should not happen when  a compiler
+runs \fBas\fR automatically.  Warnings report an assumption made so
+that \fBas\fR could keep assembling a flawed program; errors report a
+grave problem that stops the assembly.
+.PP
+If you are invoking \fBas\fR via the \s-1GNU C\s0 compiler,
+you can use the \fB\-Wa\fR option to pass arguments through to the assembler.
+The assembler arguments must be separated from each other (and the \fB\-Wa\fR)
+by commas.  For example:
+.PP
+.Vb 1
+\&        gcc \-c \-g \-O \-Wa,\-alh,\-L file.c
+.Ve
+.PP
+This passes two options to the assembler: \fB\-alh\fR (emit a listing to
+standard output with high-level and assembly source) and \fB\-L\fR (retain
+local symbols in the symbol table).
+.PP
+Usually you do not need to use this \fB\-Wa\fR mechanism, since many compiler
+command-line options are automatically passed to the assembler by the compiler.
+(You can call the \s-1GNU\s0 compiler driver with the \fB\-v\fR option to see
+precisely what options it passes to each compilation pass, including the
+assembler.)
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.IP "\fB\-a[cdghlmns]\fR" 4
+.IX Item "-a[cdghlmns]"
+Turn on listings, in any of a variety of ways:
+.RS 4
+.IP "\fB\-ac\fR" 4
+.IX Item "-ac"
+omit false conditionals
+.IP "\fB\-ad\fR" 4
+.IX Item "-ad"
+omit debugging directives
+.IP "\fB\-ag\fR" 4
+.IX Item "-ag"
+include general information, like as version and options passed
+.IP "\fB\-ah\fR" 4
+.IX Item "-ah"
+include high-level source
+.IP "\fB\-al\fR" 4
+.IX Item "-al"
+include assembly
+.IP "\fB\-am\fR" 4
+.IX Item "-am"
+include macro expansions
+.IP "\fB\-an\fR" 4
+.IX Item "-an"
+omit forms processing
+.IP "\fB\-as\fR" 4
+.IX Item "-as"
+include symbols
+.IP "\fB=file\fR" 4
+.IX Item "=file"
+set the name of the listing file
+.RE
+.RS 4
+.Sp
+You may combine these options; for example, use \fB\-aln\fR for assembly
+listing without forms processing.  The \fB=file\fR option, if used, must be
+the last one.  By itself, \fB\-a\fR defaults to \fB\-ahls\fR.
+.RE
+.IP "\fB\-\-alternate\fR" 4
+.IX Item "--alternate"
+Begin in alternate macro mode.
+.IP "\fB\-\-compress\-debug\-sections\fR" 4
+.IX Item "--compress-debug-sections"
+Compress \s-1DWARF\s0 debug sections using zlib with \s-1SHF_COMPRESSED\s0 from the
+\&\s-1ELF ABI.\s0  The resulting object file may not be compatible with older
+linkers and object file utilities.  Note if compression would make a
+given section \fIlarger\fR then it is not compressed.
+.IP "\fB\-\-compress\-debug\-sections=none\fR" 4
+.IX Item "--compress-debug-sections=none"
+.PD 0
+.IP "\fB\-\-compress\-debug\-sections=zlib\fR" 4
+.IX Item "--compress-debug-sections=zlib"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gnu\fR" 4
+.IX Item "--compress-debug-sections=zlib-gnu"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gabi\fR" 4
+.IX Item "--compress-debug-sections=zlib-gabi"
+.IP "\fB\-\-compress\-debug\-sections=zstd\fR" 4
+.IX Item "--compress-debug-sections=zstd"
+.PD
+These options control how \s-1DWARF\s0 debug sections are compressed.
+\&\fB\-\-compress\-debug\-sections=none\fR is equivalent to
+\&\fB\-\-nocompress\-debug\-sections\fR.
+\&\fB\-\-compress\-debug\-sections=zlib\fR and
+\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR are equivalent to
+\&\fB\-\-compress\-debug\-sections\fR.
+\&\fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses \s-1DWARF\s0 debug sections
+using the obsoleted zlib-gnu format.  The debug sections are renamed to begin
+with \fB.zdebug\fR.
+\&\fB\-\-compress\-debug\-sections=zstd\fR compresses \s-1DWARF\s0 debug
+sections using zstd.  Note \- if compression would actually make a section
+\&\fIlarger\fR, then it is not compressed nor renamed.
+.IP "\fB\-\-nocompress\-debug\-sections\fR" 4
+.IX Item "--nocompress-debug-sections"
+Do not compress \s-1DWARF\s0 debug sections.  This is usually the default for all
+targets except the x86/x86_64, but a configure time option can be used to
+override this.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+Enable denugging in target specific backends, if supported.  Otherwise ignored.
+Even if ignored, this option is accepted for script compatibility with calls to
+other assemblers.
+.IP "\fB\-\-debug\-prefix\-map\fR \fIold\fR\fB=\fR\fInew\fR" 4
+.IX Item "--debug-prefix-map old=new"
+When assembling files in directory \fI\fIold\fI\fR, record debugging
+information describing them as in \fI\fInew\fI\fR instead.
+.IP "\fB\-\-defsym\fR \fIsym\fR\fB=\fR\fIvalue\fR" 4
+.IX Item "--defsym sym=value"
+Define the symbol \fIsym\fR to be \fIvalue\fR before assembling the input file.
+\&\fIvalue\fR must be an integer constant.  As in C, a leading \fB0x\fR
+indicates a hexadecimal value, and a leading \fB0\fR indicates an octal
+value.  The value of the symbol can be overridden inside a source file via the
+use of a \f(CW\*(C`.set\*(C'\fR pseudo-op.
+.IP "\fB\-\-dump\-config\fR" 4
+.IX Item "--dump-config"
+Displays how the assembler is configured and then exits.
+.IP "\fB\-\-elf\-stt\-common=no\fR" 4
+.IX Item "--elf-stt-common=no"
+.PD 0
+.IP "\fB\-\-elf\-stt\-common=yes\fR" 4
+.IX Item "--elf-stt-common=yes"
+.PD
+These options control whether the \s-1ELF\s0 assembler should generate common
+symbols with the \f(CW\*(C`STT_COMMON\*(C'\fR type.  The default can be controlled
+by a configure option \fB\-\-enable\-elf\-stt\-common\fR.
+.IP "\fB\-\-emulation=\fR\fIname\fR" 4
+.IX Item "--emulation=name"
+If the assembler is configured to support multiple different target
+configurations then this option can be used to select the desired form.
+.IP "\fB\-f\fR" 4
+.IX Item "-f"
+\&\*(L"fast\*(R"\-\-\-skip whitespace and comment preprocessing (assume source is
+compiler output).
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-\-gen\-debug\fR" 4
+.IX Item "--gen-debug"
+.PD
+Generate debugging information for each assembler source line using whichever
+debug format is preferred by the target.  This currently means either \s-1STABS,
+ECOFF\s0 or \s-1DWARF2.\s0  When the debug format is \s-1DWARF\s0 then a \f(CW\*(C`.debug_info\*(C'\fR and
+\&\f(CW\*(C`.debug_line\*(C'\fR section is only emitted when the assembly file doesn't
+generate one itself.
+.IP "\fB\-\-gstabs\fR" 4
+.IX Item "--gstabs"
+Generate stabs debugging information for each assembler line.  This
+may help debugging assembler code, if the debugger can handle it.
+.IP "\fB\-\-gstabs+\fR" 4
+.IX Item "--gstabs+"
+Generate stabs debugging information for each assembler line, with \s-1GNU\s0
+extensions that probably only gdb can handle, and that could make other
+debuggers crash or refuse to read your program.  This
+may help debugging assembler code.  Currently the only \s-1GNU\s0 extension is
+the location of the current working directory at assembling time.
+.IP "\fB\-\-gdwarf\-2\fR" 4
+.IX Item "--gdwarf-2"
+Generate \s-1DWARF2\s0 debugging information for each assembler line.  This
+may help debugging assembler code, if the debugger can handle it.  Note\-\-\-this
+option is only supported by some targets, not all of them.
+.IP "\fB\-\-gdwarf\-3\fR" 4
+.IX Item "--gdwarf-3"
+This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it
+allows for the possibility of the generation of extra debug information as per
+version 3 of the \s-1DWARF\s0 specification.  Note \- enabling this option does not
+guarantee the generation of any extra information, the choice to do so is on a
+per target basis.
+.IP "\fB\-\-gdwarf\-4\fR" 4
+.IX Item "--gdwarf-4"
+This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it
+allows for the possibility of the generation of extra debug information as per
+version 4 of the \s-1DWARF\s0 specification.  Note \- enabling this option does not
+guarantee the generation of any extra information, the choice to do so is on a
+per target basis.
+.IP "\fB\-\-gdwarf\-5\fR" 4
+.IX Item "--gdwarf-5"
+This option is the same as the \fB\-\-gdwarf\-2\fR option, except that it
+allows for the possibility of the generation of extra debug information as per
+version 5 of the \s-1DWARF\s0 specification.  Note \- enabling this option does not
+guarantee the generation of any extra information, the choice to do so is on a
+per target basis.
+.IP "\fB\-\-gdwarf\-sections\fR" 4
+.IX Item "--gdwarf-sections"
+Instead of creating a .debug_line section, create a series of
+\&.debug_line.\fIfoo\fR sections where \fIfoo\fR is the name of the
+corresponding code section.  For example a code section called \fI.text.func\fR
+will have its dwarf line number information placed into a section called
+\&\fI.debug_line.text.func\fR.  If the code section is just called \fI.text\fR
+then debug line section will still be called just \fI.debug_line\fR without any
+suffix.
+.IP "\fB\-\-gdwarf\-cie\-version=\fR\fIversion\fR" 4
+.IX Item "--gdwarf-cie-version=version"
+Control which version of \s-1DWARF\s0 Common Information Entries (CIEs) are produced.
+When this flag is not specificed the default is version 1, though some targets
+can modify this default.  Other possible values for \fIversion\fR are 3 or 4.
+.IP "\fB\-\-generate\-missing\-build\-notes=yes\fR" 4
+.IX Item "--generate-missing-build-notes=yes"
+.PD 0
+.IP "\fB\-\-generate\-missing\-build\-notes=no\fR" 4
+.IX Item "--generate-missing-build-notes=no"
+.PD
+These options control whether the \s-1ELF\s0 assembler should generate \s-1GNU\s0 Build
+attribute notes if none are present in the input sources.
+The default can be controlled by the \fB\-\-enable\-generate\-build\-notes\fR
+configure option.
+.IP "\fB\-\-gsframe\fR" 4
+.IX Item "--gsframe"
+.PD 0
+.IP "\fB\-\-gsframe\fR" 4
+.IX Item "--gsframe"
+.PD
+Create \fI.sframe\fR section from \s-1CFI\s0 directives.
+.IP "\fB\-\-hash\-size\fR \fIN\fR" 4
+.IX Item "--hash-size N"
+Ignored.  Supported for command line compatibility with other assemblers.
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Print a summary of the command-line options and exit.
+.IP "\fB\-\-target\-help\fR" 4
+.IX Item "--target-help"
+Print a summary of all target specific options and exit.
+.IP "\fB\-I\fR \fIdir\fR" 4
+.IX Item "-I dir"
+Add directory \fIdir\fR to the search list for \f(CW\*(C`.include\*(C'\fR directives.
+.IP "\fB\-J\fR" 4
+.IX Item "-J"
+Don't warn about signed overflow.
+.IP "\fB\-K\fR" 4
+.IX Item "-K"
+Issue warnings when difference tables altered for long displacements.
+.IP "\fB\-L\fR" 4
+.IX Item "-L"
+.PD 0
+.IP "\fB\-\-keep\-locals\fR" 4
+.IX Item "--keep-locals"
+.PD
+Keep (in the symbol table) local symbols.  These symbols start with
+system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems
+or \fBL\fR for traditional a.out systems.
+.IP "\fB\-\-listing\-lhs\-width=\fR\fInumber\fR" 4
+.IX Item "--listing-lhs-width=number"
+Set the maximum width, in words, of the output data column for an assembler
+listing to \fInumber\fR.
+.IP "\fB\-\-listing\-lhs\-width2=\fR\fInumber\fR" 4
+.IX Item "--listing-lhs-width2=number"
+Set the maximum width, in words, of the output data column for continuation
+lines in an assembler listing to \fInumber\fR.
+.IP "\fB\-\-listing\-rhs\-width=\fR\fInumber\fR" 4
+.IX Item "--listing-rhs-width=number"
+Set the maximum width of an input source line, as displayed in a listing, to
+\&\fInumber\fR bytes.
+.IP "\fB\-\-listing\-cont\-lines=\fR\fInumber\fR" 4
+.IX Item "--listing-cont-lines=number"
+Set the maximum number of lines printed in a listing for a single line of input
+to \fInumber\fR + 1.
+.IP "\fB\-\-multibyte\-handling=allow\fR" 4
+.IX Item "--multibyte-handling=allow"
+.PD 0
+.IP "\fB\-\-multibyte\-handling=warn\fR" 4
+.IX Item "--multibyte-handling=warn"
+.IP "\fB\-\-multibyte\-handling=warn\-sym\-only\fR" 4
+.IX Item "--multibyte-handling=warn-sym-only"
+.IP "\fB\-\-multibyte\-handling=warn_sym_only\fR" 4
+.IX Item "--multibyte-handling=warn_sym_only"
+.PD
+Controls how the assembler handles multibyte characters in the input.  The
+default (which can be restored by using the \fBallow\fR argument) is to
+allow such characters without complaint.  Using the \fBwarn\fR argument will
+make the assembler generate a warning message whenever any multibyte character
+is encountered.  Using the \fBwarn-sym-only\fR argument will only cause a
+warning to be generated when a symbol is defined with a name that contains
+multibyte characters.  (References to undefined symbols will not generate a
+warning).
+.IP "\fB\-\-no\-pad\-sections\fR" 4
+.IX Item "--no-pad-sections"
+Stop the assembler for padding the ends of output sections to the alignment
+of that section.  The default is to pad the sections, but this can waste space
+which might be needed on targets which have tight memory constraints.
+.IP "\fB\-o\fR \fIobjfile\fR" 4
+.IX Item "-o objfile"
+Name the object-file output from \fBas\fR \fIobjfile\fR.
+.IP "\fB\-R\fR" 4
+.IX Item "-R"
+Fold the data section into the text section.
+.IP "\fB\-\-reduce\-memory\-overheads\fR" 4
+.IX Item "--reduce-memory-overheads"
+Ignored.  Supported for compatibility with tools that apss the same option to
+both the assembler and the linker.
+.IP "\fB\-\-sectname\-subst\fR" 4
+.IX Item "--sectname-subst"
+Honor substitution sequences in section names.
+.IP "\fB\-\-size\-check=error\fR" 4
+.IX Item "--size-check=error"
+.PD 0
+.IP "\fB\-\-size\-check=warning\fR" 4
+.IX Item "--size-check=warning"
+.PD
+Issue an error or warning for invalid \s-1ELF\s0 .size directive.
+.IP "\fB\-\-statistics\fR" 4
+.IX Item "--statistics"
+Print the maximum space (in bytes) and total time (in seconds) used by
+assembly.
+.IP "\fB\-\-strip\-local\-absolute\fR" 4
+.IX Item "--strip-local-absolute"
+Remove local absolute symbols from the outgoing symbol table.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+.PD
+Print the \fBas\fR version.
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+Print the \fBas\fR version and exit.
+.IP "\fB\-W\fR" 4
+.IX Item "-W"
+.PD 0
+.IP "\fB\-\-no\-warn\fR" 4
+.IX Item "--no-warn"
+.PD
+Suppress warning messages.
+.IP "\fB\-\-fatal\-warnings\fR" 4
+.IX Item "--fatal-warnings"
+Treat warnings as errors.
+.IP "\fB\-\-warn\fR" 4
+.IX Item "--warn"
+Don't suppress warning messages or treat them as errors.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+Ignored.
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+Ignored.
+.IP "\fB\-Z\fR" 4
+.IX Item "-Z"
+Generate an object file even after errors.
+.IP "\fB\-\- |\fR \fIfiles\fR \fB...\fR" 4
+.IX Item "-- | files ..."
+Standard input, or source files to assemble.
+.PP
+The following options are available when as is configured for the
+64\-bit mode of the \s-1ARM\s0 Architecture (AArch64).
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+This option specifies that the output generated by the assembler should
+be marked as being encoded for a big-endian processor.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+This option specifies that the output generated by the assembler should
+be marked as being encoded for a little-endian processor.
+.IP "\fB\-mabi=\fR\fIabi\fR" 4
+.IX Item "-mabi=abi"
+Specify which \s-1ABI\s0 the source code uses.  The recognized arguments
+are: \f(CW\*(C`ilp32\*(C'\fR and \f(CW\*(C`lp64\*(C'\fR, which decides the generated object
+file in \s-1ELF32\s0 and \s-1ELF64\s0 format respectively.  The default is \f(CW\*(C`lp64\*(C'\fR.
+.IP "\fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4
+.IX Item "-mcpu=processor[+extension...]"
+This option specifies the target processor.  The assembler will issue an error
+message if an attempt is made to assemble an instruction which will not execute
+on the target processor.  The following processor names are recognized:
+\&\f(CW\*(C`cortex\-a34\*(C'\fR,
+\&\f(CW\*(C`cortex\-a35\*(C'\fR,
+\&\f(CW\*(C`cortex\-a53\*(C'\fR,
+\&\f(CW\*(C`cortex\-a55\*(C'\fR,
+\&\f(CW\*(C`cortex\-a57\*(C'\fR,
+\&\f(CW\*(C`cortex\-a65\*(C'\fR,
+\&\f(CW\*(C`cortex\-a65ae\*(C'\fR,
+\&\f(CW\*(C`cortex\-a72\*(C'\fR,
+\&\f(CW\*(C`cortex\-a73\*(C'\fR,
+\&\f(CW\*(C`cortex\-a75\*(C'\fR,
+\&\f(CW\*(C`cortex\-a76\*(C'\fR,
+\&\f(CW\*(C`cortex\-a76ae\*(C'\fR,
+\&\f(CW\*(C`cortex\-a77\*(C'\fR,
+\&\f(CW\*(C`cortex\-a78\*(C'\fR,
+\&\f(CW\*(C`cortex\-a78ae\*(C'\fR,
+\&\f(CW\*(C`cortex\-a78c\*(C'\fR,
+\&\f(CW\*(C`cortex\-a510\*(C'\fR,
+\&\f(CW\*(C`cortex\-a710\*(C'\fR,
+\&\f(CW\*(C`ares\*(C'\fR,
+\&\f(CW\*(C`exynos\-m1\*(C'\fR,
+\&\f(CW\*(C`falkor\*(C'\fR,
+\&\f(CW\*(C`neoverse\-n1\*(C'\fR,
+\&\f(CW\*(C`neoverse\-n2\*(C'\fR,
+\&\f(CW\*(C`neoverse\-e1\*(C'\fR,
+\&\f(CW\*(C`neoverse\-v1\*(C'\fR,
+\&\f(CW\*(C`qdf24xx\*(C'\fR,
+\&\f(CW\*(C`saphira\*(C'\fR,
+\&\f(CW\*(C`thunderx\*(C'\fR,
+\&\f(CW\*(C`vulcan\*(C'\fR,
+\&\f(CW\*(C`xgene1\*(C'\fR
+\&\f(CW\*(C`xgene2\*(C'\fR,
+\&\f(CW\*(C`cortex\-r82\*(C'\fR,
+\&\f(CW\*(C`cortex\-x1\*(C'\fR,
+and
+\&\f(CW\*(C`cortex\-x2\*(C'\fR.
+The special name \f(CW\*(C`all\*(C'\fR may be used to allow the assembler to accept
+instructions valid for any supported processor, including all optional
+extensions.
+.Sp
+In addition to the basic instruction set, the assembler can be told to
+accept, or restrict, various extension mnemonics that extend the
+processor.
+.Sp
+If some implementations of a particular processor can have an
+extension, then then those extensions are automatically enabled.
+Consequently, you will not normally have to specify any additional
+extensions.
+.IP "\fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4
+.IX Item "-march=architecture[+extension...]"
+This option specifies the target architecture.  The assembler will
+issue an error message if an attempt is made to assemble an
+instruction which will not execute on the target architecture.  The
+following architecture names are recognized: \f(CW\*(C`armv8\-a\*(C'\fR,
+\&\f(CW\*(C`armv8.1\-a\*(C'\fR, \f(CW\*(C`armv8.2\-a\*(C'\fR, \f(CW\*(C`armv8.3\-a\*(C'\fR, \f(CW\*(C`armv8.4\-a\*(C'\fR
+\&\f(CW\*(C`armv8.5\-a\*(C'\fR, \f(CW\*(C`armv8.6\-a\*(C'\fR, \f(CW\*(C`armv8.7\-a\*(C'\fR, \f(CW\*(C`armv8.8\-a\*(C'\fR,
+\&\f(CW\*(C`armv8\-r\*(C'\fR, \f(CW\*(C`armv9\-a\*(C'\fR, \f(CW\*(C`armv9.1\-a\*(C'\fR, \f(CW\*(C`armv9.2\-a\*(C'\fR,
+and \f(CW\*(C`armv9.3\-a\*(C'\fR.
+.Sp
+If both \fB\-mcpu\fR and \fB\-march\fR are specified, the
+assembler will use the setting for \fB\-mcpu\fR.  If neither are
+specified, the assembler will default to \fB\-mcpu=all\fR.
+.Sp
+The architecture option can be extended with the same instruction set
+extension options as the \fB\-mcpu\fR option.  Unlike
+\&\fB\-mcpu\fR, extensions are not always enabled by default,
+.IP "\fB\-mverbose\-error\fR" 4
+.IX Item "-mverbose-error"
+This option enables verbose error messages for AArch64 gas.  This option
+is enabled by default.
+.IP "\fB\-mno\-verbose\-error\fR" 4
+.IX Item "-mno-verbose-error"
+This option disables verbose error messages in AArch64 gas.
+.PP
+The following options are available when as is configured for an Alpha
+processor.
+.IP "\fB\-m\fR\fIcpu\fR" 4
+.IX Item "-mcpu"
+This option specifies the target processor.  If an attempt is made to
+assemble an instruction which will not execute on the target processor,
+the assembler may either expand the instruction as a macro or issue an
+error message.  This option is equivalent to the \f(CW\*(C`.arch\*(C'\fR directive.
+.Sp
+The following processor names are recognized:
+\&\f(CW21064\fR,
+\&\f(CW\*(C`21064a\*(C'\fR,
+\&\f(CW21066\fR,
+\&\f(CW21068\fR,
+\&\f(CW21164\fR,
+\&\f(CW\*(C`21164a\*(C'\fR,
+\&\f(CW\*(C`21164pc\*(C'\fR,
+\&\f(CW21264\fR,
+\&\f(CW\*(C`21264a\*(C'\fR,
+\&\f(CW\*(C`21264b\*(C'\fR,
+\&\f(CW\*(C`ev4\*(C'\fR,
+\&\f(CW\*(C`ev5\*(C'\fR,
+\&\f(CW\*(C`lca45\*(C'\fR,
+\&\f(CW\*(C`ev5\*(C'\fR,
+\&\f(CW\*(C`ev56\*(C'\fR,
+\&\f(CW\*(C`pca56\*(C'\fR,
+\&\f(CW\*(C`ev6\*(C'\fR,
+\&\f(CW\*(C`ev67\*(C'\fR,
+\&\f(CW\*(C`ev68\*(C'\fR.
+The special name \f(CW\*(C`all\*(C'\fR may be used to allow the assembler to accept
+instructions valid for any Alpha processor.
+.Sp
+In order to support existing practice in \s-1OSF/1\s0 with respect to \f(CW\*(C`.arch\*(C'\fR,
+and existing practice within \fB\s-1MILO\s0\fR (the Linux \s-1ARC\s0 bootloader), the
+numbered processor names (e.g. 21064) enable the processor-specific PALcode
+instructions, while the \*(L"electro-vlasic\*(R" names (e.g. \f(CW\*(C`ev4\*(C'\fR) do not.
+.IP "\fB\-mdebug\fR" 4
+.IX Item "-mdebug"
+.PD 0
+.IP "\fB\-no\-mdebug\fR" 4
+.IX Item "-no-mdebug"
+.PD
+Enables or disables the generation of \f(CW\*(C`.mdebug\*(C'\fR encapsulation for
+stabs directives and procedure descriptors.  The default is to automatically
+enable \f(CW\*(C`.mdebug\*(C'\fR when the first stabs directive is seen.
+.IP "\fB\-relax\fR" 4
+.IX Item "-relax"
+This option forces all relocations to be put into the object file, instead
+of saving space and resolving some relocations at assembly time.  Note that
+this option does not propagate all symbol arithmetic into the object file,
+because not all symbol arithmetic can be represented.  However, the option
+can still be useful in specific applications.
+.IP "\fB\-replace\fR" 4
+.IX Item "-replace"
+.PD 0
+.IP "\fB\-noreplace\fR" 4
+.IX Item "-noreplace"
+.PD
+Enables or disables the optimization of procedure calls, both at assemblage
+and at link time.  These options are only available for \s-1VMS\s0 targets and
+\&\f(CW\*(C`\-replace\*(C'\fR is the default.  See section 1.4.1 of the OpenVMS Linker
+Utility Manual.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+This option is used when the compiler generates debug information.  When
+\&\fBgcc\fR is using \fBmips-tfile\fR to generate debug
+information for \s-1ECOFF,\s0 local labels must be passed through to the object
+file.  Otherwise this option has no effect.
+.IP "\fB\-G\fR\fIsize\fR" 4
+.IX Item "-Gsize"
+A local common symbol larger than \fIsize\fR is placed in \f(CW\*(C`.bss\*(C'\fR,
+while smaller symbols are placed in \f(CW\*(C`.sbss\*(C'\fR.
+.IP "\fB\-F\fR" 4
+.IX Item "-F"
+.PD 0
+.IP "\fB\-32addr\fR" 4
+.IX Item "-32addr"
+.PD
+These options are ignored for backward compatibility.
+.PP
+The following options are available when as is configured for an \s-1ARC\s0
+processor.
+.IP "\fB\-mcpu=\fR\fIcpu\fR" 4
+.IX Item "-mcpu=cpu"
+This option selects the core processor variant.
+.IP "\fB\-EB | \-EL\fR" 4
+.IX Item "-EB | -EL"
+Select either big-endian (\-EB) or little-endian (\-EL) output.
+.IP "\fB\-mcode\-density\fR" 4
+.IX Item "-mcode-density"
+Enable Code Density extension instructions.
+.PP
+The following options are available when as is configured for the \s-1ARM\s0
+processor family.
+.IP "\fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4
+.IX Item "-mcpu=processor[+extension...]"
+Specify which \s-1ARM\s0 processor variant is the target.
+.IP "\fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4
+.IX Item "-march=architecture[+extension...]"
+Specify which \s-1ARM\s0 architecture variant is used by the target.
+.IP "\fB\-mfpu=\fR\fIfloating-point-format\fR" 4
+.IX Item "-mfpu=floating-point-format"
+Select which Floating Point architecture is the target.
+.IP "\fB\-mfloat\-abi=\fR\fIabi\fR" 4
+.IX Item "-mfloat-abi=abi"
+Select which floating point \s-1ABI\s0 is in use.
+.IP "\fB\-mthumb\fR" 4
+.IX Item "-mthumb"
+Enable Thumb only instruction decoding.
+.IP "\fB\-mapcs\-32 | \-mapcs\-26 | \-mapcs\-float | \-mapcs\-reentrant\fR" 4
+.IX Item "-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant"
+Select which procedure calling convention is in use.
+.IP "\fB\-EB | \-EL\fR" 4
+.IX Item "-EB | -EL"
+Select either big-endian (\-EB) or little-endian (\-EL) output.
+.IP "\fB\-mthumb\-interwork\fR" 4
+.IX Item "-mthumb-interwork"
+Specify that the code has been generated with interworking between Thumb and
+\&\s-1ARM\s0 code in mind.
+.IP "\fB\-mccs\fR" 4
+.IX Item "-mccs"
+Turns on CodeComposer Studio assembly syntax compatibility mode.
+.IP "\fB\-k\fR" 4
+.IX Item "-k"
+Specify that \s-1PIC\s0 code has been generated.
+.PP
+The following options are available when as is configured for
+the Blackfin processor family.
+.IP "\fB\-mcpu=\fR\fIprocessor\fR[\fB\-\fR\fIsirevision\fR]" 4
+.IX Item "-mcpu=processor[-sirevision]"
+This option specifies the target processor.  The optional \fIsirevision\fR
+is not used in assembler.  It's here such that \s-1GCC\s0 can easily pass down its
+\&\f(CW\*(C`\-mcpu=\*(C'\fR option.  The assembler will issue an
+error message if an attempt is made to assemble an instruction which
+will not execute on the target processor.  The following processor names are
+recognized:
+\&\f(CW\*(C`bf504\*(C'\fR,
+\&\f(CW\*(C`bf506\*(C'\fR,
+\&\f(CW\*(C`bf512\*(C'\fR,
+\&\f(CW\*(C`bf514\*(C'\fR,
+\&\f(CW\*(C`bf516\*(C'\fR,
+\&\f(CW\*(C`bf518\*(C'\fR,
+\&\f(CW\*(C`bf522\*(C'\fR,
+\&\f(CW\*(C`bf523\*(C'\fR,
+\&\f(CW\*(C`bf524\*(C'\fR,
+\&\f(CW\*(C`bf525\*(C'\fR,
+\&\f(CW\*(C`bf526\*(C'\fR,
+\&\f(CW\*(C`bf527\*(C'\fR,
+\&\f(CW\*(C`bf531\*(C'\fR,
+\&\f(CW\*(C`bf532\*(C'\fR,
+\&\f(CW\*(C`bf533\*(C'\fR,
+\&\f(CW\*(C`bf534\*(C'\fR,
+\&\f(CW\*(C`bf535\*(C'\fR (not implemented yet),
+\&\f(CW\*(C`bf536\*(C'\fR,
+\&\f(CW\*(C`bf537\*(C'\fR,
+\&\f(CW\*(C`bf538\*(C'\fR,
+\&\f(CW\*(C`bf539\*(C'\fR,
+\&\f(CW\*(C`bf542\*(C'\fR,
+\&\f(CW\*(C`bf542m\*(C'\fR,
+\&\f(CW\*(C`bf544\*(C'\fR,
+\&\f(CW\*(C`bf544m\*(C'\fR,
+\&\f(CW\*(C`bf547\*(C'\fR,
+\&\f(CW\*(C`bf547m\*(C'\fR,
+\&\f(CW\*(C`bf548\*(C'\fR,
+\&\f(CW\*(C`bf548m\*(C'\fR,
+\&\f(CW\*(C`bf549\*(C'\fR,
+\&\f(CW\*(C`bf549m\*(C'\fR,
+\&\f(CW\*(C`bf561\*(C'\fR,
+and
+\&\f(CW\*(C`bf592\*(C'\fR.
+.IP "\fB\-mfdpic\fR" 4
+.IX Item "-mfdpic"
+Assemble for the \s-1FDPIC ABI.\s0
+.IP "\fB\-mno\-fdpic\fR" 4
+.IX Item "-mno-fdpic"
+.PD 0
+.IP "\fB\-mnopic\fR" 4
+.IX Item "-mnopic"
+.PD
+Disable \-mfdpic.
+.PP
+The following options are available when as is configured for
+the Linux kernel \s-1BPF\s0 processor family.
+.PP
+\&\f(CW@chapter\fR \s-1BPF\s0 Dependent Features
+.SS "Options"
+.IX Subsection "Options"
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+This option specifies that the assembler should emit big-endian eBPF.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+This option specifies that the assembler should emit little-endian
+eBPF.
+.PP
+Note that if no endianness option is specified in the command line,
+the host endianness is used.
+See the info pages for documentation of the CRIS-specific options.
+.PP
+The following options are available when as is configured for
+the C\-SKY processor family.
+.IP "\fB\-march=\fR\fIarchname\fR" 4
+.IX Item "-march=archname"
+Assemble for architecture \fIarchname\fR.  The \fB\-\-help\fR option
+lists valid values for \fIarchname\fR.
+.IP "\fB\-mcpu=\fR\fIcpuname\fR" 4
+.IX Item "-mcpu=cpuname"
+Assemble for architecture \fIcpuname\fR.  The \fB\-\-help\fR option
+lists valid values for \fIcpuname\fR.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+.PD 0
+.IP "\fB\-mlittle\-endian\fR" 4
+.IX Item "-mlittle-endian"
+.PD
+Generate little-endian output.
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+.PD 0
+.IP "\fB\-mbig\-endian\fR" 4
+.IX Item "-mbig-endian"
+.PD
+Generate big-endian output.
+.IP "\fB\-fpic\fR" 4
+.IX Item "-fpic"
+.PD 0
+.IP "\fB\-pic\fR" 4
+.IX Item "-pic"
+.PD
+Generate position-independent code.
+.IP "\fB\-mljump\fR" 4
+.IX Item "-mljump"
+.PD 0
+.IP "\fB\-mno\-ljump\fR" 4
+.IX Item "-mno-ljump"
+.PD
+Enable/disable transformation of the short branch instructions
+\&\f(CW\*(C`jbf\*(C'\fR, \f(CW\*(C`jbt\*(C'\fR, and \f(CW\*(C`jbr\*(C'\fR to \f(CW\*(C`jmpi\*(C'\fR.
+This option is for V2 processors only.
+It is ignored on \s-1CK801\s0 and \s-1CK802\s0 targets, which do not support the \f(CW\*(C`jmpi\*(C'\fR
+instruction, and is enabled by default for other processors.
+.IP "\fB\-mbranch\-stub\fR" 4
+.IX Item "-mbranch-stub"
+.PD 0
+.IP "\fB\-mno\-branch\-stub\fR" 4
+.IX Item "-mno-branch-stub"
+.PD
+Pass through \f(CW\*(C`R_CKCORE_PCREL_IMM26BY2\*(C'\fR relocations for \f(CW\*(C`bsr\*(C'\fR
+instructions to the linker.
+.Sp
+This option is only available for bare-metal C\-SKY V2 \s-1ELF\s0 targets,
+where it is enabled by default.  It cannot be used in code that will be
+dynamically linked against shared libraries.
+.IP "\fB\-force2bsr\fR" 4
+.IX Item "-force2bsr"
+.PD 0
+.IP "\fB\-mforce2bsr\fR" 4
+.IX Item "-mforce2bsr"
+.IP "\fB\-no\-force2bsr\fR" 4
+.IX Item "-no-force2bsr"
+.IP "\fB\-mno\-force2bsr\fR" 4
+.IX Item "-mno-force2bsr"
+.PD
+Enable/disable transformation of \f(CW\*(C`jbsr\*(C'\fR instructions to \f(CW\*(C`bsr\*(C'\fR.
+This option is always enabled (and \fB\-mno\-force2bsr\fR is ignored)
+for \s-1CK801/CK802\s0 targets.  It is also always enabled when
+\&\fB\-mbranch\-stub\fR is in effect.
+.IP "\fB\-jsri2bsr\fR" 4
+.IX Item "-jsri2bsr"
+.PD 0
+.IP "\fB\-mjsri2bsr\fR" 4
+.IX Item "-mjsri2bsr"
+.IP "\fB\-no\-jsri2bsr\fR" 4
+.IX Item "-no-jsri2bsr"
+.IP "\fB\-mno\-jsri2bsr\fR" 4
+.IX Item "-mno-jsri2bsr"
+.PD
+Enable/disable transformation of \f(CW\*(C`jsri\*(C'\fR instructions to \f(CW\*(C`bsr\*(C'\fR.
+This option is enabled by default.
+.IP "\fB\-mnolrw\fR" 4
+.IX Item "-mnolrw"
+.PD 0
+.IP "\fB\-mno\-lrw\fR" 4
+.IX Item "-mno-lrw"
+.PD
+Enable/disable transformation of \f(CW\*(C`lrw\*(C'\fR instructions into a
+\&\f(CW\*(C`movih\*(C'\fR/\f(CW\*(C`ori\*(C'\fR pair.
+.IP "\fB\-melrw\fR" 4
+.IX Item "-melrw"
+.PD 0
+.IP "\fB\-mno\-elrw\fR" 4
+.IX Item "-mno-elrw"
+.PD
+Enable/disable extended \f(CW\*(C`lrw\*(C'\fR instructions.
+This option is enabled by default for CK800\-series processors.
+.IP "\fB\-mlaf\fR" 4
+.IX Item "-mlaf"
+.PD 0
+.IP "\fB\-mliterals\-after\-func\fR" 4
+.IX Item "-mliterals-after-func"
+.IP "\fB\-mno\-laf\fR" 4
+.IX Item "-mno-laf"
+.IP "\fB\-mno\-literals\-after\-func\fR" 4
+.IX Item "-mno-literals-after-func"
+.PD
+Enable/disable placement of literal pools after each function.
+.IP "\fB\-mlabr\fR" 4
+.IX Item "-mlabr"
+.PD 0
+.IP "\fB\-mliterals\-after\-br\fR" 4
+.IX Item "-mliterals-after-br"
+.IP "\fB\-mno\-labr\fR" 4
+.IX Item "-mno-labr"
+.IP "\fB\-mnoliterals\-after\-br\fR" 4
+.IX Item "-mnoliterals-after-br"
+.PD
+Enable/disable placement of literal pools after unconditional branches.
+This option is enabled by default.
+.IP "\fB\-mistack\fR" 4
+.IX Item "-mistack"
+.PD 0
+.IP "\fB\-mno\-istack\fR" 4
+.IX Item "-mno-istack"
+.PD
+Enable/disable interrupt stack instructions.  This option is enabled by
+default on \s-1CK801, CK802,\s0 and \s-1CK802\s0 processors.
+.PP
+The following options explicitly enable certain optional instructions.
+These features are also enabled implicitly by using \f(CW\*(C`\-mcpu=\*(C'\fR to specify
+a processor that supports it.
+.IP "\fB\-mhard\-float\fR" 4
+.IX Item "-mhard-float"
+Enable hard float instructions.
+.IP "\fB\-mmp\fR" 4
+.IX Item "-mmp"
+Enable multiprocessor instructions.
+.IP "\fB\-mcp\fR" 4
+.IX Item "-mcp"
+Enable coprocessor instructions.
+.IP "\fB\-mcache\fR" 4
+.IX Item "-mcache"
+Enable cache prefetch instruction.
+.IP "\fB\-msecurity\fR" 4
+.IX Item "-msecurity"
+Enable C\-SKY security instructions.
+.IP "\fB\-mtrust\fR" 4
+.IX Item "-mtrust"
+Enable C\-SKY trust instructions.
+.IP "\fB\-mdsp\fR" 4
+.IX Item "-mdsp"
+Enable \s-1DSP\s0 instructions.
+.IP "\fB\-medsp\fR" 4
+.IX Item "-medsp"
+Enable enhanced \s-1DSP\s0 instructions.
+.IP "\fB\-mvdsp\fR" 4
+.IX Item "-mvdsp"
+Enable vector \s-1DSP\s0 instructions.
+.PP
+The following options are available when as is configured for
+an Epiphany processor.
+.IP "\fB\-mepiphany\fR" 4
+.IX Item "-mepiphany"
+Specifies that the both 32 and 16 bit instructions are allowed.  This is the
+default behavior.
+.IP "\fB\-mepiphany16\fR" 4
+.IX Item "-mepiphany16"
+Restricts the permitted instructions to just the 16 bit set.
+.PP
+The following options are available when as is configured for an H8/300
+processor.
+\&\f(CW@chapter\fR H8/300 Dependent Features
+.SS "Options"
+.IX Subsection "Options"
+The Renesas H8/300 version of \f(CW\*(C`as\*(C'\fR has one
+machine-dependent option:
+.IP "\fB\-h\-tick\-hex\fR" 4
+.IX Item "-h-tick-hex"
+Support H'00 style hex constants in addition to 0x00 style.
+.IP "\fB\-mach=\fR\fIname\fR" 4
+.IX Item "-mach=name"
+Sets the H8300 machine variant.  The following machine names
+are recognised:
+\&\f(CW\*(C`h8300h\*(C'\fR,
+\&\f(CW\*(C`h8300hn\*(C'\fR,
+\&\f(CW\*(C`h8300s\*(C'\fR,
+\&\f(CW\*(C`h8300sn\*(C'\fR,
+\&\f(CW\*(C`h8300sx\*(C'\fR and 
+\&\f(CW\*(C`h8300sxn\*(C'\fR.
+.PP
+The following options are available when as is configured for
+an i386 processor.
+.IP "\fB\-\-32 | \-\-x32 | \-\-64\fR" 4
+.IX Item "--32 | --x32 | --64"
+Select the word size, either 32 bits or 64 bits.  \fB\-\-32\fR
+implies Intel i386 architecture, while \fB\-\-x32\fR and \fB\-\-64\fR
+imply \s-1AMD\s0 x86\-64 architecture with 32\-bit or 64\-bit word-size
+respectively.
+.Sp
+These options are only available with the \s-1ELF\s0 object file format, and
+require that the necessary \s-1BFD\s0 support has been included (on a 32\-bit
+platform you have to add \-\-enable\-64\-bit\-bfd to configure enable 64\-bit
+usage and use x86\-64 as target platform).
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+By default, x86 \s-1GAS\s0 replaces multiple nop instructions used for
+alignment within code sections with multi-byte nop instructions such
+as leal 0(%esi,1),%esi.  This switch disables the optimization if a single
+byte nop (0x90) is explicitly specified as the fill byte for alignment.
+.IP "\fB\-\-divide\fR" 4
+.IX Item "--divide"
+On SVR4\-derived platforms, the character \fB/\fR is treated as a comment
+character, which means that it cannot be used in expressions.  The
+\&\fB\-\-divide\fR option turns \fB/\fR into a normal character.  This does
+not disable \fB/\fR at the beginning of a line starting a comment, or
+affect using \fB#\fR for starting a comment.
+.IP "\fB\-march=\fR\fI\s-1CPU\s0\fR\fB[+\fR\fI\s-1EXTENSION\s0\fR\fB...]\fR" 4
+.IX Item "-march=CPU[+EXTENSION...]"
+This option specifies the target processor.  The assembler will
+issue an error message if an attempt is made to assemble an instruction
+which will not execute on the target processor.  The following
+processor names are recognized:
+\&\f(CW\*(C`i8086\*(C'\fR,
+\&\f(CW\*(C`i186\*(C'\fR,
+\&\f(CW\*(C`i286\*(C'\fR,
+\&\f(CW\*(C`i386\*(C'\fR,
+\&\f(CW\*(C`i486\*(C'\fR,
+\&\f(CW\*(C`i586\*(C'\fR,
+\&\f(CW\*(C`i686\*(C'\fR,
+\&\f(CW\*(C`pentium\*(C'\fR,
+\&\f(CW\*(C`pentiumpro\*(C'\fR,
+\&\f(CW\*(C`pentiumii\*(C'\fR,
+\&\f(CW\*(C`pentiumiii\*(C'\fR,
+\&\f(CW\*(C`pentium4\*(C'\fR,
+\&\f(CW\*(C`prescott\*(C'\fR,
+\&\f(CW\*(C`nocona\*(C'\fR,
+\&\f(CW\*(C`core\*(C'\fR,
+\&\f(CW\*(C`core2\*(C'\fR,
+\&\f(CW\*(C`corei7\*(C'\fR,
+\&\f(CW\*(C`iamcu\*(C'\fR,
+\&\f(CW\*(C`k6\*(C'\fR,
+\&\f(CW\*(C`k6_2\*(C'\fR,
+\&\f(CW\*(C`athlon\*(C'\fR,
+\&\f(CW\*(C`opteron\*(C'\fR,
+\&\f(CW\*(C`k8\*(C'\fR,
+\&\f(CW\*(C`amdfam10\*(C'\fR,
+\&\f(CW\*(C`bdver1\*(C'\fR,
+\&\f(CW\*(C`bdver2\*(C'\fR,
+\&\f(CW\*(C`bdver3\*(C'\fR,
+\&\f(CW\*(C`bdver4\*(C'\fR,
+\&\f(CW\*(C`znver1\*(C'\fR,
+\&\f(CW\*(C`znver2\*(C'\fR,
+\&\f(CW\*(C`znver3\*(C'\fR,
+\&\f(CW\*(C`znver4\*(C'\fR,
+\&\f(CW\*(C`btver1\*(C'\fR,
+\&\f(CW\*(C`btver2\*(C'\fR,
+\&\f(CW\*(C`generic32\*(C'\fR and
+\&\f(CW\*(C`generic64\*(C'\fR.
+.Sp
+In addition to the basic instruction set, the assembler can be told to
+accept various extension mnemonics.  For example,
+\&\f(CW\*(C`\-march=i686+sse4+vmx\*(C'\fR extends \fIi686\fR with \fIsse4\fR and
+\&\fIvmx\fR.  The following extensions are currently supported:
+\&\f(CW8087\fR,
+\&\f(CW287\fR,
+\&\f(CW387\fR,
+\&\f(CW687\fR,
+\&\f(CW\*(C`cmov\*(C'\fR,
+\&\f(CW\*(C`fxsr\*(C'\fR,
+\&\f(CW\*(C`mmx\*(C'\fR,
+\&\f(CW\*(C`sse\*(C'\fR,
+\&\f(CW\*(C`sse2\*(C'\fR,
+\&\f(CW\*(C`sse3\*(C'\fR,
+\&\f(CW\*(C`sse4a\*(C'\fR,
+\&\f(CW\*(C`ssse3\*(C'\fR,
+\&\f(CW\*(C`sse4.1\*(C'\fR,
+\&\f(CW\*(C`sse4.2\*(C'\fR,
+\&\f(CW\*(C`sse4\*(C'\fR,
+\&\f(CW\*(C`avx\*(C'\fR,
+\&\f(CW\*(C`avx2\*(C'\fR,
+\&\f(CW\*(C`adx\*(C'\fR,
+\&\f(CW\*(C`rdseed\*(C'\fR,
+\&\f(CW\*(C`prfchw\*(C'\fR,
+\&\f(CW\*(C`smap\*(C'\fR,
+\&\f(CW\*(C`mpx\*(C'\fR,
+\&\f(CW\*(C`sha\*(C'\fR,
+\&\f(CW\*(C`rdpid\*(C'\fR,
+\&\f(CW\*(C`ptwrite\*(C'\fR,
+\&\f(CW\*(C`cet\*(C'\fR,
+\&\f(CW\*(C`gfni\*(C'\fR,
+\&\f(CW\*(C`vaes\*(C'\fR,
+\&\f(CW\*(C`vpclmulqdq\*(C'\fR,
+\&\f(CW\*(C`prefetchwt1\*(C'\fR,
+\&\f(CW\*(C`clflushopt\*(C'\fR,
+\&\f(CW\*(C`se1\*(C'\fR,
+\&\f(CW\*(C`clwb\*(C'\fR,
+\&\f(CW\*(C`movdiri\*(C'\fR,
+\&\f(CW\*(C`movdir64b\*(C'\fR,
+\&\f(CW\*(C`enqcmd\*(C'\fR,
+\&\f(CW\*(C`serialize\*(C'\fR,
+\&\f(CW\*(C`tsxldtrk\*(C'\fR,
+\&\f(CW\*(C`kl\*(C'\fR,
+\&\f(CW\*(C`widekl\*(C'\fR,
+\&\f(CW\*(C`hreset\*(C'\fR,
+\&\f(CW\*(C`avx512f\*(C'\fR,
+\&\f(CW\*(C`avx512cd\*(C'\fR,
+\&\f(CW\*(C`avx512er\*(C'\fR,
+\&\f(CW\*(C`avx512pf\*(C'\fR,
+\&\f(CW\*(C`avx512vl\*(C'\fR,
+\&\f(CW\*(C`avx512bw\*(C'\fR,
+\&\f(CW\*(C`avx512dq\*(C'\fR,
+\&\f(CW\*(C`avx512ifma\*(C'\fR,
+\&\f(CW\*(C`avx512vbmi\*(C'\fR,
+\&\f(CW\*(C`avx512_4fmaps\*(C'\fR,
+\&\f(CW\*(C`avx512_4vnniw\*(C'\fR,
+\&\f(CW\*(C`avx512_vpopcntdq\*(C'\fR,
+\&\f(CW\*(C`avx512_vbmi2\*(C'\fR,
+\&\f(CW\*(C`avx512_vnni\*(C'\fR,
+\&\f(CW\*(C`avx512_bitalg\*(C'\fR,
+\&\f(CW\*(C`avx512_vp2intersect\*(C'\fR,
+\&\f(CW\*(C`tdx\*(C'\fR,
+\&\f(CW\*(C`avx512_bf16\*(C'\fR,
+\&\f(CW\*(C`avx_vnni\*(C'\fR,
+\&\f(CW\*(C`avx512_fp16\*(C'\fR,
+\&\f(CW\*(C`prefetchi\*(C'\fR,
+\&\f(CW\*(C`avx_ifma\*(C'\fR,
+\&\f(CW\*(C`avx_vnni_int8\*(C'\fR,
+\&\f(CW\*(C`cmpccxadd\*(C'\fR,
+\&\f(CW\*(C`wrmsrns\*(C'\fR,
+\&\f(CW\*(C`msrlist\*(C'\fR,
+\&\f(CW\*(C`avx_ne_convert\*(C'\fR,
+\&\f(CW\*(C`rao_int\*(C'\fR,
+\&\f(CW\*(C`amx_int8\*(C'\fR,
+\&\f(CW\*(C`amx_bf16\*(C'\fR,
+\&\f(CW\*(C`amx_fp16\*(C'\fR,
+\&\f(CW\*(C`amx_tile\*(C'\fR,
+\&\f(CW\*(C`vmx\*(C'\fR,
+\&\f(CW\*(C`vmfunc\*(C'\fR,
+\&\f(CW\*(C`smx\*(C'\fR,
+\&\f(CW\*(C`xsave\*(C'\fR,
+\&\f(CW\*(C`xsaveopt\*(C'\fR,
+\&\f(CW\*(C`xsavec\*(C'\fR,
+\&\f(CW\*(C`xsaves\*(C'\fR,
+\&\f(CW\*(C`aes\*(C'\fR,
+\&\f(CW\*(C`pclmul\*(C'\fR,
+\&\f(CW\*(C`fsgsbase\*(C'\fR,
+\&\f(CW\*(C`rdrnd\*(C'\fR,
+\&\f(CW\*(C`f16c\*(C'\fR,
+\&\f(CW\*(C`bmi2\*(C'\fR,
+\&\f(CW\*(C`fma\*(C'\fR,
+\&\f(CW\*(C`movbe\*(C'\fR,
+\&\f(CW\*(C`ept\*(C'\fR,
+\&\f(CW\*(C`lzcnt\*(C'\fR,
+\&\f(CW\*(C`popcnt\*(C'\fR,
+\&\f(CW\*(C`hle\*(C'\fR,
+\&\f(CW\*(C`rtm\*(C'\fR,
+\&\f(CW\*(C`tsx\*(C'\fR,
+\&\f(CW\*(C`invpcid\*(C'\fR,
+\&\f(CW\*(C`clflush\*(C'\fR,
+\&\f(CW\*(C`mwaitx\*(C'\fR,
+\&\f(CW\*(C`clzero\*(C'\fR,
+\&\f(CW\*(C`wbnoinvd\*(C'\fR,
+\&\f(CW\*(C`pconfig\*(C'\fR,
+\&\f(CW\*(C`waitpkg\*(C'\fR,
+\&\f(CW\*(C`uintr\*(C'\fR,
+\&\f(CW\*(C`cldemote\*(C'\fR,
+\&\f(CW\*(C`rdpru\*(C'\fR,
+\&\f(CW\*(C`mcommit\*(C'\fR,
+\&\f(CW\*(C`sev_es\*(C'\fR,
+\&\f(CW\*(C`lwp\*(C'\fR,
+\&\f(CW\*(C`fma4\*(C'\fR,
+\&\f(CW\*(C`xop\*(C'\fR,
+\&\f(CW\*(C`cx16\*(C'\fR,
+\&\f(CW\*(C`syscall\*(C'\fR,
+\&\f(CW\*(C`rdtscp\*(C'\fR,
+\&\f(CW\*(C`3dnow\*(C'\fR,
+\&\f(CW\*(C`3dnowa\*(C'\fR,
+\&\f(CW\*(C`sse4a\*(C'\fR,
+\&\f(CW\*(C`sse5\*(C'\fR,
+\&\f(CW\*(C`snp\*(C'\fR,
+\&\f(CW\*(C`invlpgb\*(C'\fR,
+\&\f(CW\*(C`tlbsync\*(C'\fR,
+\&\f(CW\*(C`svme\*(C'\fR and
+\&\f(CW\*(C`padlock\*(C'\fR.
+Note that these extension mnemonics can be prefixed with \f(CW\*(C`no\*(C'\fR to revoke
+the respective (and any dependent) functionality.
+.Sp
+When the \f(CW\*(C`.arch\*(C'\fR directive is used with \fB\-march\fR, the
+\&\f(CW\*(C`.arch\*(C'\fR directive will take precedent.
+.IP "\fB\-mtune=\fR\fI\s-1CPU\s0\fR" 4
+.IX Item "-mtune=CPU"
+This option specifies a processor to optimize for. When used in
+conjunction with the \fB\-march\fR option, only instructions
+of the processor specified by the \fB\-march\fR option will be
+generated.
+.Sp
+Valid \fI\s-1CPU\s0\fR values are identical to the processor list of
+\&\fB\-march=\fR\fI\s-1CPU\s0\fR.
+.IP "\fB\-msse2avx\fR" 4
+.IX Item "-msse2avx"
+This option specifies that the assembler should encode \s-1SSE\s0 instructions
+with \s-1VEX\s0 prefix.
+.IP "\fB\-muse\-unaligned\-vector\-move\fR" 4
+.IX Item "-muse-unaligned-vector-move"
+This option specifies that the assembler should encode aligned vector
+move as unaligned vector move.
+.IP "\fB\-msse\-check=\fR\fInone\fR" 4
+.IX Item "-msse-check=none"
+.PD 0
+.IP "\fB\-msse\-check=\fR\fIwarning\fR" 4
+.IX Item "-msse-check=warning"
+.IP "\fB\-msse\-check=\fR\fIerror\fR" 4
+.IX Item "-msse-check=error"
+.PD
+These options control if the assembler should check \s-1SSE\s0 instructions.
+\&\fB\-msse\-check=\fR\fInone\fR will make the assembler not to check \s-1SSE\s0
+instructions,  which is the default.  \fB\-msse\-check=\fR\fIwarning\fR
+will make the assembler issue a warning for any \s-1SSE\s0 instruction.
+\&\fB\-msse\-check=\fR\fIerror\fR will make the assembler issue an error
+for any \s-1SSE\s0 instruction.
+.IP "\fB\-mavxscalar=\fR\fI128\fR" 4
+.IX Item "-mavxscalar=128"
+.PD 0
+.IP "\fB\-mavxscalar=\fR\fI256\fR" 4
+.IX Item "-mavxscalar=256"
+.PD
+These options control how the assembler should encode scalar \s-1AVX\s0
+instructions.  \fB\-mavxscalar=\fR\fI128\fR will encode scalar
+\&\s-1AVX\s0 instructions with 128bit vector length, which is the default.
+\&\fB\-mavxscalar=\fR\fI256\fR will encode scalar \s-1AVX\s0 instructions
+with 256bit vector length.
+.Sp
+\&\s-1WARNING:\s0 Don't use this for production code \- due to \s-1CPU\s0 errata the
+resulting code may not work on certain models.
+.IP "\fB\-mvexwig=\fR\fI0\fR" 4
+.IX Item "-mvexwig=0"
+.PD 0
+.IP "\fB\-mvexwig=\fR\fI1\fR" 4
+.IX Item "-mvexwig=1"
+.PD
+These options control how the assembler should encode \s-1VEX\s0.W\-ignored (\s-1WIG\s0)
+\&\s-1VEX\s0 instructions.  \fB\-mvexwig=\fR\fI0\fR will encode \s-1WIG VEX\s0
+instructions with vex.w = 0, which is the default.
+\&\fB\-mvexwig=\fR\fI1\fR will encode \s-1WIG EVEX\s0 instructions with
+vex.w = 1.
+.Sp
+\&\s-1WARNING:\s0 Don't use this for production code \- due to \s-1CPU\s0 errata the
+resulting code may not work on certain models.
+.IP "\fB\-mevexlig=\fR\fI128\fR" 4
+.IX Item "-mevexlig=128"
+.PD 0
+.IP "\fB\-mevexlig=\fR\fI256\fR" 4
+.IX Item "-mevexlig=256"
+.IP "\fB\-mevexlig=\fR\fI512\fR" 4
+.IX Item "-mevexlig=512"
+.PD
+These options control how the assembler should encode length-ignored
+(\s-1LIG\s0) \s-1EVEX\s0 instructions.  \fB\-mevexlig=\fR\fI128\fR will encode \s-1LIG
+EVEX\s0 instructions with 128bit vector length, which is the default.
+\&\fB\-mevexlig=\fR\fI256\fR and \fB\-mevexlig=\fR\fI512\fR will
+encode \s-1LIG EVEX\s0 instructions with 256bit and 512bit vector length,
+respectively.
+.IP "\fB\-mevexwig=\fR\fI0\fR" 4
+.IX Item "-mevexwig=0"
+.PD 0
+.IP "\fB\-mevexwig=\fR\fI1\fR" 4
+.IX Item "-mevexwig=1"
+.PD
+These options control how the assembler should encode w\-ignored (\s-1WIG\s0)
+\&\s-1EVEX\s0 instructions.  \fB\-mevexwig=\fR\fI0\fR will encode \s-1WIG
+EVEX\s0 instructions with evex.w = 0, which is the default.
+\&\fB\-mevexwig=\fR\fI1\fR will encode \s-1WIG EVEX\s0 instructions with
+evex.w = 1.
+.IP "\fB\-mmnemonic=\fR\fIatt\fR" 4
+.IX Item "-mmnemonic=att"
+.PD 0
+.IP "\fB\-mmnemonic=\fR\fIintel\fR" 4
+.IX Item "-mmnemonic=intel"
+.PD
+This option specifies instruction mnemonic for matching instructions.
+The \f(CW\*(C`.att_mnemonic\*(C'\fR and \f(CW\*(C`.intel_mnemonic\*(C'\fR directives will
+take precedent.
+.IP "\fB\-msyntax=\fR\fIatt\fR" 4
+.IX Item "-msyntax=att"
+.PD 0
+.IP "\fB\-msyntax=\fR\fIintel\fR" 4
+.IX Item "-msyntax=intel"
+.PD
+This option specifies instruction syntax when processing instructions.
+The \f(CW\*(C`.att_syntax\*(C'\fR and \f(CW\*(C`.intel_syntax\*(C'\fR directives will
+take precedent.
+.IP "\fB\-mnaked\-reg\fR" 4
+.IX Item "-mnaked-reg"
+This option specifies that registers don't require a \fB%\fR prefix.
+The \f(CW\*(C`.att_syntax\*(C'\fR and \f(CW\*(C`.intel_syntax\*(C'\fR directives will take precedent.
+.IP "\fB\-madd\-bnd\-prefix\fR" 4
+.IX Item "-madd-bnd-prefix"
+This option forces the assembler to add \s-1BND\s0 prefix to all branches, even
+if such prefix was not explicitly specified in the source code.
+.IP "\fB\-mno\-shared\fR" 4
+.IX Item "-mno-shared"
+On \s-1ELF\s0 target, the assembler normally optimizes out non-PLT relocations
+against defined non-weak global branch targets with default visibility.
+The \fB\-mshared\fR option tells the assembler to generate code which
+may go into a shared library where all non-weak global branch targets
+with default visibility can be preempted.  The resulting code is
+slightly bigger.  This option only affects the handling of branch
+instructions.
+.IP "\fB\-mbig\-obj\fR" 4
+.IX Item "-mbig-obj"
+On \s-1PE/COFF\s0 target this option forces the use of big object file
+format, which allows more than 32768 sections.
+.IP "\fB\-momit\-lock\-prefix=\fR\fIno\fR" 4
+.IX Item "-momit-lock-prefix=no"
+.PD 0
+.IP "\fB\-momit\-lock\-prefix=\fR\fIyes\fR" 4
+.IX Item "-momit-lock-prefix=yes"
+.PD
+These options control how the assembler should encode lock prefix.
+This option is intended as a workaround for processors, that fail on
+lock prefix. This option can only be safely used with single-core,
+single-thread computers
+\&\fB\-momit\-lock\-prefix=\fR\fIyes\fR will omit all lock prefixes.
+\&\fB\-momit\-lock\-prefix=\fR\fIno\fR will encode lock prefix as usual,
+which is the default.
+.IP "\fB\-mfence\-as\-lock\-add=\fR\fIno\fR" 4
+.IX Item "-mfence-as-lock-add=no"
+.PD 0
+.IP "\fB\-mfence\-as\-lock\-add=\fR\fIyes\fR" 4
+.IX Item "-mfence-as-lock-add=yes"
+.PD
+These options control how the assembler should encode lfence, mfence and
+sfence.
+\&\fB\-mfence\-as\-lock\-add=\fR\fIyes\fR will encode lfence, mfence and
+sfence as \fBlock addl \f(CB$0x0\fB, (%rsp)\fR in 64\-bit mode and
+\&\fBlock addl \f(CB$0x0\fB, (%esp)\fR in 32\-bit mode.
+\&\fB\-mfence\-as\-lock\-add=\fR\fIno\fR will encode lfence, mfence and
+sfence as usual, which is the default.
+.IP "\fB\-mrelax\-relocations=\fR\fIno\fR" 4
+.IX Item "-mrelax-relocations=no"
+.PD 0
+.IP "\fB\-mrelax\-relocations=\fR\fIyes\fR" 4
+.IX Item "-mrelax-relocations=yes"
+.PD
+These options control whether the assembler should generate relax
+relocations, R_386_GOT32X, in 32\-bit mode, or R_X86_64_GOTPCRELX and
+R_X86_64_REX_GOTPCRELX, in 64\-bit mode.
+\&\fB\-mrelax\-relocations=\fR\fIyes\fR will generate relax relocations.
+\&\fB\-mrelax\-relocations=\fR\fIno\fR will not generate relax
+relocations.  The default can be controlled by a configure option
+\&\fB\-\-enable\-x86\-relax\-relocations\fR.
+.IP "\fB\-malign\-branch\-boundary=\fR\fI\s-1NUM\s0\fR" 4
+.IX Item "-malign-branch-boundary=NUM"
+This option controls how the assembler should align branches with segment
+prefixes or \s-1NOP.\s0  \fI\s-1NUM\s0\fR must be a power of 2.  It should be 0 or
+no less than 16.  Branches will be aligned within \fI\s-1NUM\s0\fR byte
+boundary.  \fB\-malign\-branch\-boundary=0\fR, which is the default,
+doesn't align branches.
+.IP "\fB\-malign\-branch=\fR\fI\s-1TYPE\s0\fR\fB[+\fR\fI\s-1TYPE\s0\fR\fB...]\fR" 4
+.IX Item "-malign-branch=TYPE[+TYPE...]"
+This option specifies types of branches to align. \fI\s-1TYPE\s0\fR is
+combination of \fBjcc\fR, which aligns conditional jumps,
+\&\fBfused\fR, which aligns fused conditional jumps, \fBjmp\fR,
+which aligns unconditional jumps, \fBcall\fR which aligns calls,
+\&\fBret\fR, which aligns rets, \fBindirect\fR, which aligns indirect
+jumps and calls.  The default is \fB\-malign\-branch=jcc+fused+jmp\fR.
+.IP "\fB\-malign\-branch\-prefix\-size=\fR\fI\s-1NUM\s0\fR" 4
+.IX Item "-malign-branch-prefix-size=NUM"
+This option specifies the maximum number of prefixes on an instruction
+to align branches.  \fI\s-1NUM\s0\fR should be between 0 and 5.  The default
+\&\fI\s-1NUM\s0\fR is 5.
+.IP "\fB\-mbranches\-within\-32B\-boundaries\fR" 4
+.IX Item "-mbranches-within-32B-boundaries"
+This option aligns conditional jumps, fused conditional jumps and
+unconditional jumps within 32 byte boundary with up to 5 segment prefixes
+on an instruction.  It is equivalent to
+\&\fB\-malign\-branch\-boundary=32\fR
+\&\fB\-malign\-branch=jcc+fused+jmp\fR
+\&\fB\-malign\-branch\-prefix\-size=5\fR.
+The default doesn't align branches.
+.IP "\fB\-mlfence\-after\-load=\fR\fIno\fR" 4
+.IX Item "-mlfence-after-load=no"
+.PD 0
+.IP "\fB\-mlfence\-after\-load=\fR\fIyes\fR" 4
+.IX Item "-mlfence-after-load=yes"
+.PD
+These options control whether the assembler should generate lfence
+after load instructions.  \fB\-mlfence\-after\-load=\fR\fIyes\fR will
+generate lfence.  \fB\-mlfence\-after\-load=\fR\fIno\fR will not generate
+lfence, which is the default.
+.IP "\fB\-mlfence\-before\-indirect\-branch=\fR\fInone\fR" 4
+.IX Item "-mlfence-before-indirect-branch=none"
+.PD 0
+.IP "\fB\-mlfence\-before\-indirect\-branch=\fR\fIall\fR" 4
+.IX Item "-mlfence-before-indirect-branch=all"
+.IP "\fB\-mlfence\-before\-indirect\-branch=\fR\fIregister\fR" 4
+.IX Item "-mlfence-before-indirect-branch=register"
+.IP "\fB\-mlfence\-before\-indirect\-branch=\fR\fImemory\fR" 4
+.IX Item "-mlfence-before-indirect-branch=memory"
+.PD
+These options control whether the assembler should generate lfence
+before indirect near branch instructions.
+\&\fB\-mlfence\-before\-indirect\-branch=\fR\fIall\fR will generate lfence
+before indirect near branch via register and issue a warning before
+indirect near branch via memory.
+It also implicitly sets \fB\-mlfence\-before\-ret=\fR\fIshl\fR when
+there's no explicit \fB\-mlfence\-before\-ret=\fR.
+\&\fB\-mlfence\-before\-indirect\-branch=\fR\fIregister\fR will generate
+lfence before indirect near branch via register.
+\&\fB\-mlfence\-before\-indirect\-branch=\fR\fImemory\fR will issue a
+warning before indirect near branch via memory.
+\&\fB\-mlfence\-before\-indirect\-branch=\fR\fInone\fR will not generate
+lfence nor issue warning, which is the default.  Note that lfence won't
+be generated before indirect near branch via register with
+\&\fB\-mlfence\-after\-load=\fR\fIyes\fR since lfence will be generated
+after loading branch target register.
+.IP "\fB\-mlfence\-before\-ret=\fR\fInone\fR" 4
+.IX Item "-mlfence-before-ret=none"
+.PD 0
+.IP "\fB\-mlfence\-before\-ret=\fR\fIshl\fR" 4
+.IX Item "-mlfence-before-ret=shl"
+.IP "\fB\-mlfence\-before\-ret=\fR\fIor\fR" 4
+.IX Item "-mlfence-before-ret=or"
+.IP "\fB\-mlfence\-before\-ret=\fR\fIyes\fR" 4
+.IX Item "-mlfence-before-ret=yes"
+.IP "\fB\-mlfence\-before\-ret=\fR\fInot\fR" 4
+.IX Item "-mlfence-before-ret=not"
+.PD
+These options control whether the assembler should generate lfence
+before ret.  \fB\-mlfence\-before\-ret=\fR\fIor\fR will generate
+generate or instruction with lfence.
+\&\fB\-mlfence\-before\-ret=\fR\fIshl/yes\fR will generate shl instruction
+with lfence. \fB\-mlfence\-before\-ret=\fR\fInot\fR will generate not
+instruction with lfence. \fB\-mlfence\-before\-ret=\fR\fInone\fR will not
+generate lfence, which is the default.
+.IP "\fB\-mx86\-used\-note=\fR\fIno\fR" 4
+.IX Item "-mx86-used-note=no"
+.PD 0
+.IP "\fB\-mx86\-used\-note=\fR\fIyes\fR" 4
+.IX Item "-mx86-used-note=yes"
+.PD
+These options control whether the assembler should generate
+\&\s-1GNU_PROPERTY_X86_ISA_1_USED\s0 and \s-1GNU_PROPERTY_X86_FEATURE_2_USED
+GNU\s0 property notes.  The default can be controlled by the
+\&\fB\-\-enable\-x86\-used\-note\fR configure option.
+.IP "\fB\-mevexrcig=\fR\fIrne\fR" 4
+.IX Item "-mevexrcig=rne"
+.PD 0
+.IP "\fB\-mevexrcig=\fR\fIrd\fR" 4
+.IX Item "-mevexrcig=rd"
+.IP "\fB\-mevexrcig=\fR\fIru\fR" 4
+.IX Item "-mevexrcig=ru"
+.IP "\fB\-mevexrcig=\fR\fIrz\fR" 4
+.IX Item "-mevexrcig=rz"
+.PD
+These options control how the assembler should encode SAE-only
+\&\s-1EVEX\s0 instructions.  \fB\-mevexrcig=\fR\fIrne\fR will encode \s-1RC\s0 bits
+of \s-1EVEX\s0 instruction with 00, which is the default.
+\&\fB\-mevexrcig=\fR\fIrd\fR, \fB\-mevexrcig=\fR\fIru\fR
+and \fB\-mevexrcig=\fR\fIrz\fR will encode SAE-only \s-1EVEX\s0 instructions
+with 01, 10 and 11 \s-1RC\s0 bits, respectively.
+.IP "\fB\-mamd64\fR" 4
+.IX Item "-mamd64"
+.PD 0
+.IP "\fB\-mintel64\fR" 4
+.IX Item "-mintel64"
+.PD
+This option specifies that the assembler should accept only \s-1AMD64\s0 or
+Intel64 \s-1ISA\s0 in 64\-bit mode.  The default is to accept common, Intel64
+only and \s-1AMD64\s0 ISAs.
+.IP "\fB\-O0 | \-O | \-O1 | \-O2 | \-Os\fR" 4
+.IX Item "-O0 | -O | -O1 | -O2 | -Os"
+Optimize instruction encoding with smaller instruction size.  \fB\-O\fR
+and \fB\-O1\fR encode 64\-bit register load instructions with 64\-bit
+immediate as 32\-bit register load instructions with 31\-bit or 32\-bits
+immediates, encode 64\-bit register clearing instructions with 32\-bit
+register clearing instructions, encode 256\-bit/512\-bit \s-1VEX/EVEX\s0 vector
+register clearing instructions with 128\-bit \s-1VEX\s0 vector register
+clearing instructions, encode 128\-bit/256\-bit \s-1EVEX\s0 vector
+register load/store instructions with \s-1VEX\s0 vector register load/store
+instructions, and encode 128\-bit/256\-bit \s-1EVEX\s0 packed integer logical
+instructions with 128\-bit/256\-bit \s-1VEX\s0 packed integer logical.
+.Sp
+\&\fB\-O2\fR includes \fB\-O1\fR optimization plus encodes
+256\-bit/512\-bit \s-1EVEX\s0 vector register clearing instructions with 128\-bit
+\&\s-1EVEX\s0 vector register clearing instructions.  In 64\-bit mode \s-1VEX\s0 encoded
+instructions with commutative source operands will also have their
+source operands swapped if this allows using the 2\-byte \s-1VEX\s0 prefix form
+instead of the 3\-byte one.  Certain forms of \s-1AND\s0 as well as \s-1OR\s0 with the
+same (register) operand specified twice will also be changed to \s-1TEST.\s0
+.Sp
+\&\fB\-Os\fR includes \fB\-O2\fR optimization plus encodes 16\-bit, 32\-bit
+and 64\-bit register tests with immediate as 8\-bit register test with
+immediate.  \fB\-O0\fR turns off this optimization.
+.PP
+The following options are available when as is configured for the
+Ubicom \s-1IP2K\s0 series.
+.IP "\fB\-mip2022ext\fR" 4
+.IX Item "-mip2022ext"
+Specifies that the extended \s-1IP2022\s0 instructions are allowed.
+.IP "\fB\-mip2022\fR" 4
+.IX Item "-mip2022"
+Restores the default behaviour, which restricts the permitted instructions to
+just the basic \s-1IP2022\s0 ones.
+.PP
+The following options are available when as is configured for the
+Renesas M32C and M16C processors.
+.IP "\fB\-m32c\fR" 4
+.IX Item "-m32c"
+Assemble M32C instructions.
+.IP "\fB\-m16c\fR" 4
+.IX Item "-m16c"
+Assemble M16C instructions (the default).
+.IP "\fB\-relax\fR" 4
+.IX Item "-relax"
+Enable support for link-time relaxations.
+.IP "\fB\-h\-tick\-hex\fR" 4
+.IX Item "-h-tick-hex"
+Support H'00 style hex constants in addition to 0x00 style.
+.PP
+The following options are available when as is configured for the
+Renesas M32R (formerly Mitsubishi M32R) series.
+.IP "\fB\-\-m32rx\fR" 4
+.IX Item "--m32rx"
+Specify which processor in the M32R family is the target.  The default
+is normally the M32R, but this option changes it to the M32RX.
+.IP "\fB\-\-warn\-explicit\-parallel\-conflicts or \-\-Wp\fR" 4
+.IX Item "--warn-explicit-parallel-conflicts or --Wp"
+Produce warning messages when questionable parallel constructs are
+encountered.
+.IP "\fB\-\-no\-warn\-explicit\-parallel\-conflicts or \-\-Wnp\fR" 4
+.IX Item "--no-warn-explicit-parallel-conflicts or --Wnp"
+Do not produce warning messages when questionable parallel constructs are
+encountered.
+.PP
+The following options are available when as is configured for the
+Motorola 68000 series.
+.IP "\fB\-l\fR" 4
+.IX Item "-l"
+Shorten references to undefined symbols, to one word instead of two.
+.IP "\fB\-m68000 | \-m68008 | \-m68010 | \-m68020 | \-m68030\fR" 4
+.IX Item "-m68000 | -m68008 | -m68010 | -m68020 | -m68030"
+.PD 0
+.IP "\fB| \-m68040 | \-m68060 | \-m68302 | \-m68331 | \-m68332\fR" 4
+.IX Item "| -m68040 | -m68060 | -m68302 | -m68331 | -m68332"
+.IP "\fB| \-m68333 | \-m68340 | \-mcpu32 | \-m5200\fR" 4
+.IX Item "| -m68333 | -m68340 | -mcpu32 | -m5200"
+.PD
+Specify what processor in the 68000 family is the target.  The default
+is normally the 68020, but this can be changed at configuration time.
+.IP "\fB\-m68881 | \-m68882 | \-mno\-68881 | \-mno\-68882\fR" 4
+.IX Item "-m68881 | -m68882 | -mno-68881 | -mno-68882"
+The target machine does (or does not) have a floating-point coprocessor.
+The default is to assume a coprocessor for 68020, 68030, and cpu32.  Although
+the basic 68000 is not compatible with the 68881, a combination of the
+two can be specified, since it's possible to do emulation of the
+coprocessor instructions with the main processor.
+.IP "\fB\-m68851 | \-mno\-68851\fR" 4
+.IX Item "-m68851 | -mno-68851"
+The target machine does (or does not) have a memory-management
+unit coprocessor.  The default is to assume an \s-1MMU\s0 for 68020 and up.
+.PP
+The following options are available when as is configured for an
+Altera Nios \s-1II\s0 processor.
+.IP "\fB\-relax\-section\fR" 4
+.IX Item "-relax-section"
+Replace identified out-of-range branches with PC-relative \f(CW\*(C`jmp\*(C'\fR
+sequences when possible.  The generated code sequences are suitable
+for use in position-independent code, but there is a practical limit
+on the extended branch range because of the length of the sequences.
+This option is the default.
+.IP "\fB\-relax\-all\fR" 4
+.IX Item "-relax-all"
+Replace branch instructions not determinable to be in range
+and all call instructions with \f(CW\*(C`jmp\*(C'\fR and \f(CW\*(C`callr\*(C'\fR sequences
+(respectively).  This option generates absolute relocations against the
+target symbols and is not appropriate for position-independent code.
+.IP "\fB\-no\-relax\fR" 4
+.IX Item "-no-relax"
+Do not replace any branches or calls.
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+Generate big-endian output.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+Generate little-endian output.  This is the default.
+.IP "\fB\-march=\fR\fIarchitecture\fR" 4
+.IX Item "-march=architecture"
+This option specifies the target architecture.  The assembler issues
+an error message if an attempt is made to assemble an instruction which
+will not execute on the target architecture.  The following architecture
+names are recognized:
+\&\f(CW\*(C`r1\*(C'\fR,
+\&\f(CW\*(C`r2\*(C'\fR.  
+The default is \f(CW\*(C`r1\*(C'\fR.
+.PP
+The following options are available when as is configured for a
+\&\s-1PRU\s0 processor.
+.IP "\fB\-mlink\-relax\fR" 4
+.IX Item "-mlink-relax"
+Assume that \s-1LD\s0 would optimize \s-1LDI32\s0 instructions by checking the upper
+16 bits of the \fIexpression\fR. If they are all zeros, then \s-1LD\s0 would
+shorten the \s-1LDI32\s0 instruction to a single \s-1LDI.\s0 In such case \f(CW\*(C`as\*(C'\fR
+will output \s-1DIFF\s0 relocations for diff expressions.
+.IP "\fB\-mno\-link\-relax\fR" 4
+.IX Item "-mno-link-relax"
+Assume that \s-1LD\s0 would not optimize \s-1LDI32\s0 instructions. As a consequence,
+\&\s-1DIFF\s0 relocations will not be emitted.
+.IP "\fB\-mno\-warn\-regname\-label\fR" 4
+.IX Item "-mno-warn-regname-label"
+Do not warn if a label name matches a register name. Usually assembler
+programmers will want this warning to be emitted. C compilers may want
+to turn this off.
+.PP
+The following options are available when as is configured for
+a \s-1MIPS\s0 processor.
+.IP "\fB\-G\fR \fInum\fR" 4
+.IX Item "-G num"
+This option sets the largest size of an object that can be referenced
+implicitly with the \f(CW\*(C`gp\*(C'\fR register.  It is only accepted for targets that
+use \s-1ECOFF\s0 format, such as a DECstation running Ultrix.  The default value is 8.
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+Generate \*(L"big endian\*(R" format output.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+Generate \*(L"little endian\*(R" format output.
+.IP "\fB\-mips1\fR" 4
+.IX Item "-mips1"
+.PD 0
+.IP "\fB\-mips2\fR" 4
+.IX Item "-mips2"
+.IP "\fB\-mips3\fR" 4
+.IX Item "-mips3"
+.IP "\fB\-mips4\fR" 4
+.IX Item "-mips4"
+.IP "\fB\-mips5\fR" 4
+.IX Item "-mips5"
+.IP "\fB\-mips32\fR" 4
+.IX Item "-mips32"
+.IP "\fB\-mips32r2\fR" 4
+.IX Item "-mips32r2"
+.IP "\fB\-mips32r3\fR" 4
+.IX Item "-mips32r3"
+.IP "\fB\-mips32r5\fR" 4
+.IX Item "-mips32r5"
+.IP "\fB\-mips32r6\fR" 4
+.IX Item "-mips32r6"
+.IP "\fB\-mips64\fR" 4
+.IX Item "-mips64"
+.IP "\fB\-mips64r2\fR" 4
+.IX Item "-mips64r2"
+.IP "\fB\-mips64r3\fR" 4
+.IX Item "-mips64r3"
+.IP "\fB\-mips64r5\fR" 4
+.IX Item "-mips64r5"
+.IP "\fB\-mips64r6\fR" 4
+.IX Item "-mips64r6"
+.PD
+Generate code for a particular \s-1MIPS\s0 Instruction Set Architecture level.
+\&\fB\-mips1\fR is an alias for \fB\-march=r3000\fR, \fB\-mips2\fR is an
+alias for \fB\-march=r6000\fR, \fB\-mips3\fR is an alias for
+\&\fB\-march=r4000\fR and \fB\-mips4\fR is an alias for \fB\-march=r8000\fR.
+\&\fB\-mips5\fR, \fB\-mips32\fR, \fB\-mips32r2\fR, \fB\-mips32r3\fR,
+\&\fB\-mips32r5\fR, \fB\-mips32r6\fR, \fB\-mips64\fR, \fB\-mips64r2\fR,
+\&\fB\-mips64r3\fR, \fB\-mips64r5\fR, and \fB\-mips64r6\fR correspond to generic
+\&\s-1MIPS V, MIPS32, MIPS32\s0 Release 2, \s-1MIPS32\s0 Release 3, \s-1MIPS32\s0 Release 5, \s-1MIPS32\s0
+Release 6, \s-1MIPS64, MIPS64\s0 Release 2, \s-1MIPS64\s0 Release 3, \s-1MIPS64\s0 Release 5, and
+\&\s-1MIPS64\s0 Release 6 \s-1ISA\s0 processors, respectively.
+.IP "\fB\-march=\fR\fIcpu\fR" 4
+.IX Item "-march=cpu"
+Generate code for a particular \s-1MIPS CPU.\s0
+.IP "\fB\-mtune=\fR\fIcpu\fR" 4
+.IX Item "-mtune=cpu"
+Schedule and tune for a particular \s-1MIPS CPU.\s0
+.IP "\fB\-mfix7000\fR" 4
+.IX Item "-mfix7000"
+.PD 0
+.IP "\fB\-mno\-fix7000\fR" 4
+.IX Item "-mno-fix7000"
+.PD
+Cause nops to be inserted if the read of the destination register
+of an mfhi or mflo instruction occurs in the following two instructions.
+.IP "\fB\-mfix\-rm7000\fR" 4
+.IX Item "-mfix-rm7000"
+.PD 0
+.IP "\fB\-mno\-fix\-rm7000\fR" 4
+.IX Item "-mno-fix-rm7000"
+.PD
+Cause nops to be inserted if a dmult or dmultu instruction is
+followed by a load instruction.
+.IP "\fB\-mfix\-r5900\fR" 4
+.IX Item "-mfix-r5900"
+.PD 0
+.IP "\fB\-mno\-fix\-r5900\fR" 4
+.IX Item "-mno-fix-r5900"
+.PD
+Do not attempt to schedule the preceding instruction into the delay slot
+of a branch instruction placed at the end of a short loop of six
+instructions or fewer and always schedule a \f(CW\*(C`nop\*(C'\fR instruction there
+instead.  The short loop bug under certain conditions causes loops to
+execute only once or twice, due to a hardware bug in the R5900 chip.
+.IP "\fB\-mdebug\fR" 4
+.IX Item "-mdebug"
+.PD 0
+.IP "\fB\-no\-mdebug\fR" 4
+.IX Item "-no-mdebug"
+.PD
+Cause stabs-style debugging output to go into an ECOFF-style .mdebug
+section instead of the standard \s-1ELF\s0 .stabs sections.
+.IP "\fB\-mpdr\fR" 4
+.IX Item "-mpdr"
+.PD 0
+.IP "\fB\-mno\-pdr\fR" 4
+.IX Item "-mno-pdr"
+.PD
+Control generation of \f(CW\*(C`.pdr\*(C'\fR sections.
+.IP "\fB\-mgp32\fR" 4
+.IX Item "-mgp32"
+.PD 0
+.IP "\fB\-mfp32\fR" 4
+.IX Item "-mfp32"
+.PD
+The register sizes are normally inferred from the \s-1ISA\s0 and \s-1ABI,\s0 but these
+flags force a certain group of registers to be treated as 32 bits wide at
+all times.  \fB\-mgp32\fR controls the size of general-purpose registers
+and \fB\-mfp32\fR controls the size of floating-point registers.
+.IP "\fB\-mgp64\fR" 4
+.IX Item "-mgp64"
+.PD 0
+.IP "\fB\-mfp64\fR" 4
+.IX Item "-mfp64"
+.PD
+The register sizes are normally inferred from the \s-1ISA\s0 and \s-1ABI,\s0 but these
+flags force a certain group of registers to be treated as 64 bits wide at
+all times.  \fB\-mgp64\fR controls the size of general-purpose registers
+and \fB\-mfp64\fR controls the size of floating-point registers.
+.IP "\fB\-mfpxx\fR" 4
+.IX Item "-mfpxx"
+The register sizes are normally inferred from the \s-1ISA\s0 and \s-1ABI,\s0 but using
+this flag in combination with \fB\-mabi=32\fR enables an \s-1ABI\s0 variant
+which will operate correctly with floating-point registers which are
+32 or 64 bits wide.
+.IP "\fB\-modd\-spreg\fR" 4
+.IX Item "-modd-spreg"
+.PD 0
+.IP "\fB\-mno\-odd\-spreg\fR" 4
+.IX Item "-mno-odd-spreg"
+.PD
+Enable use of floating-point operations on odd-numbered single-precision
+registers when supported by the \s-1ISA.\s0  \fB\-mfpxx\fR implies
+\&\fB\-mno\-odd\-spreg\fR, otherwise the default is \fB\-modd\-spreg\fR.
+.IP "\fB\-mips16\fR" 4
+.IX Item "-mips16"
+.PD 0
+.IP "\fB\-no\-mips16\fR" 4
+.IX Item "-no-mips16"
+.PD
+Generate code for the \s-1MIPS 16\s0 processor.  This is equivalent to putting
+\&\f(CW\*(C`.module mips16\*(C'\fR at the start of the assembly file.  \fB\-no\-mips16\fR
+turns off this option.
+.IP "\fB\-mmips16e2\fR" 4
+.IX Item "-mmips16e2"
+.PD 0
+.IP "\fB\-mno\-mips16e2\fR" 4
+.IX Item "-mno-mips16e2"
+.PD
+Enable the use of MIPS16e2 instructions in \s-1MIPS16\s0 mode.  This is equivalent
+to putting \f(CW\*(C`.module mips16e2\*(C'\fR at the start of the assembly file.
+\&\fB\-mno\-mips16e2\fR turns off this option.
+.IP "\fB\-mmicromips\fR" 4
+.IX Item "-mmicromips"
+.PD 0
+.IP "\fB\-mno\-micromips\fR" 4
+.IX Item "-mno-micromips"
+.PD
+Generate code for the microMIPS processor.  This is equivalent to putting
+\&\f(CW\*(C`.module micromips\*(C'\fR at the start of the assembly file.
+\&\fB\-mno\-micromips\fR turns off this option.  This is equivalent to putting
+\&\f(CW\*(C`.module nomicromips\*(C'\fR at the start of the assembly file.
+.IP "\fB\-msmartmips\fR" 4
+.IX Item "-msmartmips"
+.PD 0
+.IP "\fB\-mno\-smartmips\fR" 4
+.IX Item "-mno-smartmips"
+.PD
+Enables the SmartMIPS extension to the \s-1MIPS32\s0 instruction set.  This is
+equivalent to putting \f(CW\*(C`.module smartmips\*(C'\fR at the start of the assembly
+file.  \fB\-mno\-smartmips\fR turns off this option.
+.IP "\fB\-mips3d\fR" 4
+.IX Item "-mips3d"
+.PD 0
+.IP "\fB\-no\-mips3d\fR" 4
+.IX Item "-no-mips3d"
+.PD
+Generate code for the \s-1MIPS\-3D\s0 Application Specific Extension.
+This tells the assembler to accept \s-1MIPS\-3D\s0 instructions.
+\&\fB\-no\-mips3d\fR turns off this option.
+.IP "\fB\-mdmx\fR" 4
+.IX Item "-mdmx"
+.PD 0
+.IP "\fB\-no\-mdmx\fR" 4
+.IX Item "-no-mdmx"
+.PD
+Generate code for the \s-1MDMX\s0 Application Specific Extension.
+This tells the assembler to accept \s-1MDMX\s0 instructions.
+\&\fB\-no\-mdmx\fR turns off this option.
+.IP "\fB\-mdsp\fR" 4
+.IX Item "-mdsp"
+.PD 0
+.IP "\fB\-mno\-dsp\fR" 4
+.IX Item "-mno-dsp"
+.PD
+Generate code for the \s-1DSP\s0 Release 1 Application Specific Extension.
+This tells the assembler to accept \s-1DSP\s0 Release 1 instructions.
+\&\fB\-mno\-dsp\fR turns off this option.
+.IP "\fB\-mdspr2\fR" 4
+.IX Item "-mdspr2"
+.PD 0
+.IP "\fB\-mno\-dspr2\fR" 4
+.IX Item "-mno-dspr2"
+.PD
+Generate code for the \s-1DSP\s0 Release 2 Application Specific Extension.
+This option implies \fB\-mdsp\fR.
+This tells the assembler to accept \s-1DSP\s0 Release 2 instructions.
+\&\fB\-mno\-dspr2\fR turns off this option.
+.IP "\fB\-mdspr3\fR" 4
+.IX Item "-mdspr3"
+.PD 0
+.IP "\fB\-mno\-dspr3\fR" 4
+.IX Item "-mno-dspr3"
+.PD
+Generate code for the \s-1DSP\s0 Release 3 Application Specific Extension.
+This option implies \fB\-mdsp\fR and \fB\-mdspr2\fR.
+This tells the assembler to accept \s-1DSP\s0 Release 3 instructions.
+\&\fB\-mno\-dspr3\fR turns off this option.
+.IP "\fB\-mmsa\fR" 4
+.IX Item "-mmsa"
+.PD 0
+.IP "\fB\-mno\-msa\fR" 4
+.IX Item "-mno-msa"
+.PD
+Generate code for the \s-1MIPS SIMD\s0 Architecture Extension.
+This tells the assembler to accept \s-1MSA\s0 instructions.
+\&\fB\-mno\-msa\fR turns off this option.
+.IP "\fB\-mxpa\fR" 4
+.IX Item "-mxpa"
+.PD 0
+.IP "\fB\-mno\-xpa\fR" 4
+.IX Item "-mno-xpa"
+.PD
+Generate code for the \s-1MIPS\s0 eXtended Physical Address (\s-1XPA\s0) Extension.
+This tells the assembler to accept \s-1XPA\s0 instructions.
+\&\fB\-mno\-xpa\fR turns off this option.
+.IP "\fB\-mmt\fR" 4
+.IX Item "-mmt"
+.PD 0
+.IP "\fB\-mno\-mt\fR" 4
+.IX Item "-mno-mt"
+.PD
+Generate code for the \s-1MT\s0 Application Specific Extension.
+This tells the assembler to accept \s-1MT\s0 instructions.
+\&\fB\-mno\-mt\fR turns off this option.
+.IP "\fB\-mmcu\fR" 4
+.IX Item "-mmcu"
+.PD 0
+.IP "\fB\-mno\-mcu\fR" 4
+.IX Item "-mno-mcu"
+.PD
+Generate code for the \s-1MCU\s0 Application Specific Extension.
+This tells the assembler to accept \s-1MCU\s0 instructions.
+\&\fB\-mno\-mcu\fR turns off this option.
+.IP "\fB\-mcrc\fR" 4
+.IX Item "-mcrc"
+.PD 0
+.IP "\fB\-mno\-crc\fR" 4
+.IX Item "-mno-crc"
+.PD
+Generate code for the \s-1MIPS\s0 cyclic redundancy check (\s-1CRC\s0) Application
+Specific Extension.  This tells the assembler to accept \s-1CRC\s0 instructions.
+\&\fB\-mno\-crc\fR turns off this option.
+.IP "\fB\-mginv\fR" 4
+.IX Item "-mginv"
+.PD 0
+.IP "\fB\-mno\-ginv\fR" 4
+.IX Item "-mno-ginv"
+.PD
+Generate code for the Global INValidate (\s-1GINV\s0) Application Specific
+Extension.  This tells the assembler to accept \s-1GINV\s0 instructions.
+\&\fB\-mno\-ginv\fR turns off this option.
+.IP "\fB\-mloongson\-mmi\fR" 4
+.IX Item "-mloongson-mmi"
+.PD 0
+.IP "\fB\-mno\-loongson\-mmi\fR" 4
+.IX Item "-mno-loongson-mmi"
+.PD
+Generate code for the Loongson MultiMedia extensions Instructions (\s-1MMI\s0)
+Application Specific Extension.  This tells the assembler to accept \s-1MMI\s0
+instructions.
+\&\fB\-mno\-loongson\-mmi\fR turns off this option.
+.IP "\fB\-mloongson\-cam\fR" 4
+.IX Item "-mloongson-cam"
+.PD 0
+.IP "\fB\-mno\-loongson\-cam\fR" 4
+.IX Item "-mno-loongson-cam"
+.PD
+Generate code for the Loongson Content Address Memory (\s-1CAM\s0) instructions.
+This tells the assembler to accept Loongson \s-1CAM\s0 instructions.
+\&\fB\-mno\-loongson\-cam\fR turns off this option.
+.IP "\fB\-mloongson\-ext\fR" 4
+.IX Item "-mloongson-ext"
+.PD 0
+.IP "\fB\-mno\-loongson\-ext\fR" 4
+.IX Item "-mno-loongson-ext"
+.PD
+Generate code for the Loongson EXTensions (\s-1EXT\s0) instructions.
+This tells the assembler to accept Loongson \s-1EXT\s0 instructions.
+\&\fB\-mno\-loongson\-ext\fR turns off this option.
+.IP "\fB\-mloongson\-ext2\fR" 4
+.IX Item "-mloongson-ext2"
+.PD 0
+.IP "\fB\-mno\-loongson\-ext2\fR" 4
+.IX Item "-mno-loongson-ext2"
+.PD
+Generate code for the Loongson EXTensions R2 (\s-1EXT2\s0) instructions.
+This option implies \fB\-mloongson\-ext\fR.
+This tells the assembler to accept Loongson \s-1EXT2\s0 instructions.
+\&\fB\-mno\-loongson\-ext2\fR turns off this option.
+.IP "\fB\-minsn32\fR" 4
+.IX Item "-minsn32"
+.PD 0
+.IP "\fB\-mno\-insn32\fR" 4
+.IX Item "-mno-insn32"
+.PD
+Only use 32\-bit instruction encodings when generating code for the
+microMIPS processor.  This option inhibits the use of any 16\-bit
+instructions.  This is equivalent to putting \f(CW\*(C`.set insn32\*(C'\fR at
+the start of the assembly file.  \fB\-mno\-insn32\fR turns off this
+option.  This is equivalent to putting \f(CW\*(C`.set noinsn32\*(C'\fR at the
+start of the assembly file.  By default \fB\-mno\-insn32\fR is
+selected, allowing all instructions to be used.
+.IP "\fB\-\-construct\-floats\fR" 4
+.IX Item "--construct-floats"
+.PD 0
+.IP "\fB\-\-no\-construct\-floats\fR" 4
+.IX Item "--no-construct-floats"
+.PD
+The \fB\-\-no\-construct\-floats\fR option disables the construction of
+double width floating point constants by loading the two halves of the
+value into the two single width floating point registers that make up
+the double width register.  By default \fB\-\-construct\-floats\fR is
+selected, allowing construction of these floating point constants.
+.IP "\fB\-\-relax\-branch\fR" 4
+.IX Item "--relax-branch"
+.PD 0
+.IP "\fB\-\-no\-relax\-branch\fR" 4
+.IX Item "--no-relax-branch"
+.PD
+The \fB\-\-relax\-branch\fR option enables the relaxation of out-of-range
+branches.  By default \fB\-\-no\-relax\-branch\fR is selected, causing any
+out-of-range branches to produce an error.
+.IP "\fB\-mignore\-branch\-isa\fR" 4
+.IX Item "-mignore-branch-isa"
+.PD 0
+.IP "\fB\-mno\-ignore\-branch\-isa\fR" 4
+.IX Item "-mno-ignore-branch-isa"
+.PD
+Ignore branch checks for invalid transitions between \s-1ISA\s0 modes.  The
+semantics of branches does not provide for an \s-1ISA\s0 mode switch, so in
+most cases the \s-1ISA\s0 mode a branch has been encoded for has to be the
+same as the \s-1ISA\s0 mode of the branch's target label.  Therefore \s-1GAS\s0 has
+checks implemented that verify in branch assembly that the two \s-1ISA\s0
+modes match.  \fB\-mignore\-branch\-isa\fR disables these checks.  By
+default \fB\-mno\-ignore\-branch\-isa\fR is selected, causing any invalid
+branch requiring a transition between \s-1ISA\s0 modes to produce an error.
+.IP "\fB\-mnan=\fR\fIencoding\fR" 4
+.IX Item "-mnan=encoding"
+Select between the \s-1IEEE 754\-2008\s0 (\fB\-mnan=2008\fR) or the legacy
+(\fB\-mnan=legacy\fR) NaN encoding format.  The latter is the default.
+.IP "\fB\-\-emulation=\fR\fIname\fR" 4
+.IX Item "--emulation=name"
+This option was formerly used to switch between \s-1ELF\s0 and \s-1ECOFF\s0 output
+on targets like \s-1IRIX 5\s0 that supported both.  \s-1MIPS ECOFF\s0 support was
+removed in \s-1GAS 2.24,\s0 so the option now serves little purpose.
+It is retained for backwards compatibility.
+.Sp
+The available configuration names are: \fBmipself\fR, \fBmipslelf\fR and
+\&\fBmipsbelf\fR.  Choosing \fBmipself\fR now has no effect, since the output
+is always \s-1ELF.\s0  \fBmipslelf\fR and \fBmipsbelf\fR select little\- and
+big-endian output respectively, but \fB\-EL\fR and \fB\-EB\fR are now the
+preferred options instead.
+.IP "\fB\-nocpp\fR" 4
+.IX Item "-nocpp"
+\&\fBas\fR ignores this option.  It is accepted for compatibility with
+the native tools.
+.IP "\fB\-\-trap\fR" 4
+.IX Item "--trap"
+.PD 0
+.IP "\fB\-\-no\-trap\fR" 4
+.IX Item "--no-trap"
+.IP "\fB\-\-break\fR" 4
+.IX Item "--break"
+.IP "\fB\-\-no\-break\fR" 4
+.IX Item "--no-break"
+.PD
+Control how to deal with multiplication overflow and division by zero.
+\&\fB\-\-trap\fR or \fB\-\-no\-break\fR (which are synonyms) take a trap exception
+(and only work for Instruction Set Architecture level 2 and higher);
+\&\fB\-\-break\fR or \fB\-\-no\-trap\fR (also synonyms, and the default) take a
+break exception.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+When this option is used, \fBas\fR will issue a warning every
+time it generates a nop instruction from a macro.
+.PP
+The following options are available when as is configured for a
+LoongArch processor.
+.IP "\fB\-fpic\fR" 4
+.IX Item "-fpic"
+.PD 0
+.IP "\fB\-fPIC\fR" 4
+.IX Item "-fPIC"
+.PD
+Generate position-independent code
+.IP "\fB\-fno\-pic\fR" 4
+.IX Item "-fno-pic"
+Don't generate position-independent code (default)
+.PP
+The following options are available when as is configured for a
+Meta processor.
+.ie n .IP """\-mcpu=metac11""" 4
+.el .IP "\f(CW\-mcpu=metac11\fR" 4
+.IX Item "-mcpu=metac11"
+Generate code for Meta 1.1.
+.ie n .IP """\-mcpu=metac12""" 4
+.el .IP "\f(CW\-mcpu=metac12\fR" 4
+.IX Item "-mcpu=metac12"
+Generate code for Meta 1.2.
+.ie n .IP """\-mcpu=metac21""" 4
+.el .IP "\f(CW\-mcpu=metac21\fR" 4
+.IX Item "-mcpu=metac21"
+Generate code for Meta 2.1.
+.ie n .IP """\-mfpu=metac21""" 4
+.el .IP "\f(CW\-mfpu=metac21\fR" 4
+.IX Item "-mfpu=metac21"
+Allow code to use \s-1FPU\s0 hardware of Meta 2.1.
+.PP
+See the info pages for documentation of the MMIX-specific options.
+.PP
+The following options are available when as is configured for a
+\&\s-1NDS32\s0 processor.
+.ie n .IP """\-O1""" 4
+.el .IP "\f(CW\-O1\fR" 4
+.IX Item "-O1"
+Optimize for performance.
+.ie n .IP """\-Os""" 4
+.el .IP "\f(CW\-Os\fR" 4
+.IX Item "-Os"
+Optimize for space.
+.ie n .IP """\-EL""" 4
+.el .IP "\f(CW\-EL\fR" 4
+.IX Item "-EL"
+Produce little endian data output.
+.ie n .IP """\-EB""" 4
+.el .IP "\f(CW\-EB\fR" 4
+.IX Item "-EB"
+Produce little endian data output.
+.ie n .IP """\-mpic""" 4
+.el .IP "\f(CW\-mpic\fR" 4
+.IX Item "-mpic"
+Generate \s-1PIC.\s0
+.ie n .IP """\-mno\-fp\-as\-gp\-relax""" 4
+.el .IP "\f(CW\-mno\-fp\-as\-gp\-relax\fR" 4
+.IX Item "-mno-fp-as-gp-relax"
+Suppress fp-as-gp relaxation for this file.
+.ie n .IP """\-mb2bb\-relax""" 4
+.el .IP "\f(CW\-mb2bb\-relax\fR" 4
+.IX Item "-mb2bb-relax"
+Back-to-back branch optimization.
+.ie n .IP """\-mno\-all\-relax""" 4
+.el .IP "\f(CW\-mno\-all\-relax\fR" 4
+.IX Item "-mno-all-relax"
+Suppress all relaxation for this file.
+.ie n .IP """\-march=<arch name>""" 4
+.el .IP "\f(CW\-march=<arch name>\fR" 4
+.IX Item "-march=<arch name>"
+Assemble for architecture <arch name> which could be v3, v3j, v3m, v3f,
+v3s, v2, v2j, v2f, v2s.
+.ie n .IP """\-mbaseline=<baseline>""" 4
+.el .IP "\f(CW\-mbaseline=<baseline>\fR" 4
+.IX Item "-mbaseline=<baseline>"
+Assemble for baseline <baseline> which could be v2, v3, v3m.
+.ie n .IP """\-mfpu\-freg=\fIFREG\fP""" 4
+.el .IP "\f(CW\-mfpu\-freg=\f(CIFREG\f(CW\fR" 4
+.IX Item "-mfpu-freg=FREG"
+Specify a \s-1FPU\s0 configuration.
+.RS 4
+.ie n .IP """0      8 SP /  4 DP registers""" 4
+.el .IP "\f(CW0      8 SP /  4 DP registers\fR" 4
+.IX Item "0 8 SP / 4 DP registers"
+.PD 0
+.ie n .IP """1     16 SP /  8 DP registers""" 4
+.el .IP "\f(CW1     16 SP /  8 DP registers\fR" 4
+.IX Item "1 16 SP / 8 DP registers"
+.ie n .IP """2     32 SP / 16 DP registers""" 4
+.el .IP "\f(CW2     32 SP / 16 DP registers\fR" 4
+.IX Item "2 32 SP / 16 DP registers"
+.ie n .IP """3     32 SP / 32 DP registers""" 4
+.el .IP "\f(CW3     32 SP / 32 DP registers\fR" 4
+.IX Item "3 32 SP / 32 DP registers"
+.RE
+.RS 4
+.RE
+.ie n .IP """\-mabi=\fIabi\fP""" 4
+.el .IP "\f(CW\-mabi=\f(CIabi\f(CW\fR" 4
+.IX Item "-mabi=abi"
+.PD
+Specify a abi version <abi> could be v1, v2, v2fp, v2fpp.
+.ie n .IP """\-m[no\-]mac""" 4
+.el .IP "\f(CW\-m[no\-]mac\fR" 4
+.IX Item "-m[no-]mac"
+Enable/Disable Multiply instructions support.
+.ie n .IP """\-m[no\-]div""" 4
+.el .IP "\f(CW\-m[no\-]div\fR" 4
+.IX Item "-m[no-]div"
+Enable/Disable Divide instructions support.
+.ie n .IP """\-m[no\-]16bit\-ext""" 4
+.el .IP "\f(CW\-m[no\-]16bit\-ext\fR" 4
+.IX Item "-m[no-]16bit-ext"
+Enable/Disable 16\-bit extension
+.ie n .IP """\-m[no\-]dx\-regs""" 4
+.el .IP "\f(CW\-m[no\-]dx\-regs\fR" 4
+.IX Item "-m[no-]dx-regs"
+Enable/Disable d0/d1 registers
+.ie n .IP """\-m[no\-]perf\-ext""" 4
+.el .IP "\f(CW\-m[no\-]perf\-ext\fR" 4
+.IX Item "-m[no-]perf-ext"
+Enable/Disable Performance extension
+.ie n .IP """\-m[no\-]perf2\-ext""" 4
+.el .IP "\f(CW\-m[no\-]perf2\-ext\fR" 4
+.IX Item "-m[no-]perf2-ext"
+Enable/Disable Performance extension 2
+.ie n .IP """\-m[no\-]string\-ext""" 4
+.el .IP "\f(CW\-m[no\-]string\-ext\fR" 4
+.IX Item "-m[no-]string-ext"
+Enable/Disable String extension
+.ie n .IP """\-m[no\-]reduced\-regs""" 4
+.el .IP "\f(CW\-m[no\-]reduced\-regs\fR" 4
+.IX Item "-m[no-]reduced-regs"
+Enable/Disable Reduced Register configuration (\s-1GPR16\s0) option
+.ie n .IP """\-m[no\-]audio\-isa\-ext""" 4
+.el .IP "\f(CW\-m[no\-]audio\-isa\-ext\fR" 4
+.IX Item "-m[no-]audio-isa-ext"
+Enable/Disable \s-1AUDIO ISA\s0 extension
+.ie n .IP """\-m[no\-]fpu\-sp\-ext""" 4
+.el .IP "\f(CW\-m[no\-]fpu\-sp\-ext\fR" 4
+.IX Item "-m[no-]fpu-sp-ext"
+Enable/Disable \s-1FPU SP\s0 extension
+.ie n .IP """\-m[no\-]fpu\-dp\-ext""" 4
+.el .IP "\f(CW\-m[no\-]fpu\-dp\-ext\fR" 4
+.IX Item "-m[no-]fpu-dp-ext"
+Enable/Disable \s-1FPU DP\s0 extension
+.ie n .IP """\-m[no\-]fpu\-fma""" 4
+.el .IP "\f(CW\-m[no\-]fpu\-fma\fR" 4
+.IX Item "-m[no-]fpu-fma"
+Enable/Disable \s-1FPU\s0 fused-multiply-add instructions
+.ie n .IP """\-mall\-ext""" 4
+.el .IP "\f(CW\-mall\-ext\fR" 4
+.IX Item "-mall-ext"
+Turn on all extensions and instructions support
+.PP
+The following options are available when as is configured for a
+PowerPC processor.
+.IP "\fB\-a32\fR" 4
+.IX Item "-a32"
+Generate \s-1ELF32\s0 or \s-1XCOFF32.\s0
+.IP "\fB\-a64\fR" 4
+.IX Item "-a64"
+Generate \s-1ELF64\s0 or \s-1XCOFF64.\s0
+.IP "\fB\-K \s-1PIC\s0\fR" 4
+.IX Item "-K PIC"
+Set \s-1EF_PPC_RELOCATABLE_LIB\s0 in \s-1ELF\s0 flags.
+.IP "\fB\-mpwrx | \-mpwr2\fR" 4
+.IX Item "-mpwrx | -mpwr2"
+Generate code for \s-1POWER/2\s0 (\s-1RIOS2\s0).
+.IP "\fB\-mpwr\fR" 4
+.IX Item "-mpwr"
+Generate code for \s-1POWER\s0 (\s-1RIOS1\s0)
+.IP "\fB\-m601\fR" 4
+.IX Item "-m601"
+Generate code for PowerPC 601.
+.IP "\fB\-mppc, \-mppc32, \-m603, \-m604\fR" 4
+.IX Item "-mppc, -mppc32, -m603, -m604"
+Generate code for PowerPC 603/604.
+.IP "\fB\-m403, \-m405\fR" 4
+.IX Item "-m403, -m405"
+Generate code for PowerPC 403/405.
+.IP "\fB\-m440\fR" 4
+.IX Item "-m440"
+Generate code for PowerPC 440.  BookE and some 405 instructions.
+.IP "\fB\-m464\fR" 4
+.IX Item "-m464"
+Generate code for PowerPC 464.
+.IP "\fB\-m476\fR" 4
+.IX Item "-m476"
+Generate code for PowerPC 476.
+.IP "\fB\-m7400, \-m7410, \-m7450, \-m7455\fR" 4
+.IX Item "-m7400, -m7410, -m7450, -m7455"
+Generate code for PowerPC 7400/7410/7450/7455.
+.IP "\fB\-m750cl, \-mgekko, \-mbroadway\fR" 4
+.IX Item "-m750cl, -mgekko, -mbroadway"
+Generate code for PowerPC 750CL/Gekko/Broadway.
+.IP "\fB\-m821, \-m850, \-m860\fR" 4
+.IX Item "-m821, -m850, -m860"
+Generate code for PowerPC 821/850/860.
+.IP "\fB\-mppc64, \-m620\fR" 4
+.IX Item "-mppc64, -m620"
+Generate code for PowerPC 620/625/630.
+.IP "\fB\-me200z2, \-me200z4\fR" 4
+.IX Item "-me200z2, -me200z4"
+Generate code for e200 variants, e200z2 with \s-1LSP,\s0 e200z4 with \s-1SPE.\s0
+.IP "\fB\-me300\fR" 4
+.IX Item "-me300"
+Generate code for PowerPC e300 family.
+.IP "\fB\-me500, \-me500x2\fR" 4
+.IX Item "-me500, -me500x2"
+Generate code for Motorola e500 core complex.
+.IP "\fB\-me500mc\fR" 4
+.IX Item "-me500mc"
+Generate code for Freescale e500mc core complex.
+.IP "\fB\-me500mc64\fR" 4
+.IX Item "-me500mc64"
+Generate code for Freescale e500mc64 core complex.
+.IP "\fB\-me5500\fR" 4
+.IX Item "-me5500"
+Generate code for Freescale e5500 core complex.
+.IP "\fB\-me6500\fR" 4
+.IX Item "-me6500"
+Generate code for Freescale e6500 core complex.
+.IP "\fB\-mlsp\fR" 4
+.IX Item "-mlsp"
+Enable \s-1LSP\s0 instructions.  (Disables \s-1SPE\s0 and \s-1SPE2.\s0)
+.IP "\fB\-mspe\fR" 4
+.IX Item "-mspe"
+Generate code for Motorola \s-1SPE\s0 instructions.  (Disables \s-1LSP.\s0)
+.IP "\fB\-mspe2\fR" 4
+.IX Item "-mspe2"
+Generate code for Freescale \s-1SPE2\s0 instructions.  (Disables \s-1LSP.\s0)
+.IP "\fB\-mtitan\fR" 4
+.IX Item "-mtitan"
+Generate code for AppliedMicro Titan core complex.
+.IP "\fB\-mppc64bridge\fR" 4
+.IX Item "-mppc64bridge"
+Generate code for PowerPC 64, including bridge insns.
+.IP "\fB\-mbooke\fR" 4
+.IX Item "-mbooke"
+Generate code for 32\-bit BookE.
+.IP "\fB\-ma2\fR" 4
+.IX Item "-ma2"
+Generate code for A2 architecture.
+.IP "\fB\-maltivec\fR" 4
+.IX Item "-maltivec"
+Generate code for processors with AltiVec instructions.
+.IP "\fB\-mvle\fR" 4
+.IX Item "-mvle"
+Generate code for Freescale PowerPC \s-1VLE\s0 instructions.
+.IP "\fB\-mvsx\fR" 4
+.IX Item "-mvsx"
+Generate code for processors with Vector-Scalar (\s-1VSX\s0) instructions.
+.IP "\fB\-mhtm\fR" 4
+.IX Item "-mhtm"
+Generate code for processors with Hardware Transactional Memory instructions.
+.IP "\fB\-mpower4, \-mpwr4\fR" 4
+.IX Item "-mpower4, -mpwr4"
+Generate code for Power4 architecture.
+.IP "\fB\-mpower5, \-mpwr5, \-mpwr5x\fR" 4
+.IX Item "-mpower5, -mpwr5, -mpwr5x"
+Generate code for Power5 architecture.
+.IP "\fB\-mpower6, \-mpwr6\fR" 4
+.IX Item "-mpower6, -mpwr6"
+Generate code for Power6 architecture.
+.IP "\fB\-mpower7, \-mpwr7\fR" 4
+.IX Item "-mpower7, -mpwr7"
+Generate code for Power7 architecture.
+.IP "\fB\-mpower8, \-mpwr8\fR" 4
+.IX Item "-mpower8, -mpwr8"
+Generate code for Power8 architecture.
+.IP "\fB\-mpower9, \-mpwr9\fR" 4
+.IX Item "-mpower9, -mpwr9"
+Generate code for Power9 architecture.
+.IP "\fB\-mpower10, \-mpwr10\fR" 4
+.IX Item "-mpower10, -mpwr10"
+Generate code for Power10 architecture.
+.IP "\fB\-mfuture\fR" 4
+.IX Item "-mfuture"
+Generate code for 'future' architecture.
+.IP "\fB\-mcell\fR" 4
+.IX Item "-mcell"
+.PD 0
+.IP "\fB\-mcell\fR" 4
+.IX Item "-mcell"
+.PD
+Generate code for Cell Broadband Engine architecture.
+.IP "\fB\-mcom\fR" 4
+.IX Item "-mcom"
+Generate code Power/PowerPC common instructions.
+.IP "\fB\-many\fR" 4
+.IX Item "-many"
+Generate code for any architecture (\s-1PWR/PWRX/PPC\s0).
+.IP "\fB\-mregnames\fR" 4
+.IX Item "-mregnames"
+Allow symbolic names for registers.
+.IP "\fB\-mno\-regnames\fR" 4
+.IX Item "-mno-regnames"
+Do not allow symbolic names for registers.
+.IP "\fB\-mrelocatable\fR" 4
+.IX Item "-mrelocatable"
+Support for \s-1GCC\s0's \-mrelocatable option.
+.IP "\fB\-mrelocatable\-lib\fR" 4
+.IX Item "-mrelocatable-lib"
+Support for \s-1GCC\s0's \-mrelocatable\-lib option.
+.IP "\fB\-memb\fR" 4
+.IX Item "-memb"
+Set \s-1PPC_EMB\s0 bit in \s-1ELF\s0 flags.
+.IP "\fB\-mlittle, \-mlittle\-endian, \-le\fR" 4
+.IX Item "-mlittle, -mlittle-endian, -le"
+Generate code for a little endian machine.
+.IP "\fB\-mbig, \-mbig\-endian, \-be\fR" 4
+.IX Item "-mbig, -mbig-endian, -be"
+Generate code for a big endian machine.
+.IP "\fB\-msolaris\fR" 4
+.IX Item "-msolaris"
+Generate code for Solaris.
+.IP "\fB\-mno\-solaris\fR" 4
+.IX Item "-mno-solaris"
+Do not generate code for Solaris.
+.IP "\fB\-nops=\fR\fIcount\fR" 4
+.IX Item "-nops=count"
+If an alignment directive inserts more than \fIcount\fR nops, put a
+branch at the beginning to skip execution of the nops.
+.PP
+The following options are available when as is configured for a
+RISC-V processor.
+.IP "\fB\-fpic\fR" 4
+.IX Item "-fpic"
+.PD 0
+.IP "\fB\-fPIC\fR" 4
+.IX Item "-fPIC"
+.PD
+Generate position-independent code
+.IP "\fB\-fno\-pic\fR" 4
+.IX Item "-fno-pic"
+Don't generate position-independent code (default)
+.IP "\fB\-march=ISA\fR" 4
+.IX Item "-march=ISA"
+Select the base isa, as specified by \s-1ISA.\s0  For example \-march=rv32ima.
+If this option and the architecture attributes aren't set, then assembler
+will check the default configure setting \-\-with\-arch=ISA.
+.IP "\fB\-misa\-spec=ISAspec\fR" 4
+.IX Item "-misa-spec=ISAspec"
+Select the default isa spec version.  If the version of \s-1ISA\s0 isn't set
+by \-march, then assembler helps to set the version according to
+the default chosen spec.  If this option isn't set, then assembler will
+check the default configure setting \-\-with\-isa\-spec=ISAspec.
+.IP "\fB\-mpriv\-spec=PRIVspec\fR" 4
+.IX Item "-mpriv-spec=PRIVspec"
+Select the privileged spec version.  We can decide whether the \s-1CSR\s0 is valid or
+not according to the chosen spec.  If this option and the privilege attributes
+aren't set, then assembler will check the default configure setting
+\&\-\-with\-priv\-spec=PRIVspec.
+.IP "\fB\-mabi=ABI\fR" 4
+.IX Item "-mabi=ABI"
+Selects the \s-1ABI,\s0 which is either \*(L"ilp32\*(R" or \*(L"lp64\*(R", optionally followed
+by \*(L"f\*(R", \*(L"d\*(R", or \*(L"q\*(R" to indicate single-precision, double-precision, or
+quad-precision floating-point calling convention, or none to indicate
+the soft-float calling convention.  Also, \*(L"ilp32\*(R" can optionally be followed
+by \*(L"e\*(R" to indicate the \s-1RVE ABI,\s0 which is always soft-float.
+.IP "\fB\-mrelax\fR" 4
+.IX Item "-mrelax"
+Take advantage of linker relaxations to reduce the number of instructions
+required to materialize symbol addresses. (default)
+.IP "\fB\-mno\-relax\fR" 4
+.IX Item "-mno-relax"
+Don't do linker relaxations.
+.IP "\fB\-march\-attr\fR" 4
+.IX Item "-march-attr"
+Generate the default contents for the riscv elf attribute section if the
+\&.attribute directives are not set.  This section is used to record the
+information that a linker or runtime loader needs to check compatibility.
+This information includes \s-1ISA\s0 string, stack alignment requirement, unaligned
+memory accesses, and the major, minor and revision version of privileged
+specification.
+.IP "\fB\-mno\-arch\-attr\fR" 4
+.IX Item "-mno-arch-attr"
+Don't generate the default riscv elf attribute section if the .attribute
+directives are not set.
+.IP "\fB\-mcsr\-check\fR" 4
+.IX Item "-mcsr-check"
+Enable the \s-1CSR\s0 checking for the ISA-dependent \s-1CRS\s0 and the read-only \s-1CSR.\s0
+The ISA-dependent \s-1CSR\s0 are only valid when the specific \s-1ISA\s0 is set.  The
+read-only \s-1CSR\s0 can not be written by the \s-1CSR\s0 instructions.
+.IP "\fB\-mno\-csr\-check\fR" 4
+.IX Item "-mno-csr-check"
+Don't do \s-1CSR\s0 checking.
+.IP "\fB\-mlittle\-endian\fR" 4
+.IX Item "-mlittle-endian"
+Generate code for a little endian machine.
+.IP "\fB\-mbig\-endian\fR" 4
+.IX Item "-mbig-endian"
+Generate code for a big endian machine.
+.PP
+See the info pages for documentation of the RX-specific options.
+.PP
+The following options are available when as is configured for the s390
+processor family.
+.IP "\fB\-m31\fR" 4
+.IX Item "-m31"
+.PD 0
+.IP "\fB\-m64\fR" 4
+.IX Item "-m64"
+.PD
+Select the word size, either 31/32 bits or 64 bits.
+.IP "\fB\-mesa\fR" 4
+.IX Item "-mesa"
+.PD 0
+.IP "\fB\-mzarch\fR" 4
+.IX Item "-mzarch"
+.PD
+Select the architecture mode, either the Enterprise System
+Architecture (esa) or the z/Architecture mode (zarch).
+.IP "\fB\-march=\fR\fIprocessor\fR" 4
+.IX Item "-march=processor"
+Specify which s390 processor variant is the target, \fBg5\fR (or
+\&\fBarch3\fR), \fBg6\fR, \fBz900\fR (or \fBarch5\fR), \fBz990\fR (or
+\&\fBarch6\fR), \fBz9\-109\fR, \fBz9\-ec\fR (or \fBarch7\fR), \fBz10\fR (or
+\&\fBarch8\fR), \fBz196\fR (or \fBarch9\fR), \fBzEC12\fR (or \fBarch10\fR),
+\&\fBz13\fR (or \fBarch11\fR), \fBz14\fR (or \fBarch12\fR), \fBz15\fR
+(or \fBarch13\fR), or \fBz16\fR (or \fBarch14\fR).
+.IP "\fB\-mregnames\fR" 4
+.IX Item "-mregnames"
+.PD 0
+.IP "\fB\-mno\-regnames\fR" 4
+.IX Item "-mno-regnames"
+.PD
+Allow or disallow symbolic names for registers.
+.IP "\fB\-mwarn\-areg\-zero\fR" 4
+.IX Item "-mwarn-areg-zero"
+Warn whenever the operand for a base or index register has been specified
+but evaluates to zero.
+.PP
+The following options are available when as is configured for a
+\&\s-1TMS320C6000\s0 processor.
+.IP "\fB\-march=\fR\fIarch\fR" 4
+.IX Item "-march=arch"
+Enable (only) instructions from architecture \fIarch\fR.  By default,
+all instructions are permitted.
+.Sp
+The following values of \fIarch\fR are accepted: \f(CW\*(C`c62x\*(C'\fR,
+\&\f(CW\*(C`c64x\*(C'\fR, \f(CW\*(C`c64x+\*(C'\fR, \f(CW\*(C`c67x\*(C'\fR, \f(CW\*(C`c67x+\*(C'\fR, \f(CW\*(C`c674x\*(C'\fR.
+.IP "\fB\-mdsbt\fR" 4
+.IX Item "-mdsbt"
+.PD 0
+.IP "\fB\-mno\-dsbt\fR" 4
+.IX Item "-mno-dsbt"
+.PD
+The \fB\-mdsbt\fR option causes the assembler to generate the
+\&\f(CW\*(C`Tag_ABI_DSBT\*(C'\fR attribute with a value of 1, indicating that the
+code is using \s-1DSBT\s0 addressing.  The \fB\-mno\-dsbt\fR option, the
+default, causes the tag to have a value of 0, indicating that the code
+does not use \s-1DSBT\s0 addressing.  The linker will emit a warning if
+objects of different type (\s-1DSBT\s0 and non-DSBT) are linked together.
+.IP "\fB\-mpid=no\fR" 4
+.IX Item "-mpid=no"
+.PD 0
+.IP "\fB\-mpid=near\fR" 4
+.IX Item "-mpid=near"
+.IP "\fB\-mpid=far\fR" 4
+.IX Item "-mpid=far"
+.PD
+The \fB\-mpid=\fR option causes the assembler to generate the
+\&\f(CW\*(C`Tag_ABI_PID\*(C'\fR attribute with a value indicating the form of data
+addressing used by the code.  \fB\-mpid=no\fR, the default,
+indicates position-dependent data addressing, \fB\-mpid=near\fR
+indicates position-independent addressing with \s-1GOT\s0 accesses using near
+\&\s-1DP\s0 addressing, and \fB\-mpid=far\fR indicates position-independent
+addressing with \s-1GOT\s0 accesses using far \s-1DP\s0 addressing.  The linker will
+emit a warning if objects built with different settings of this option
+are linked together.
+.IP "\fB\-mpic\fR" 4
+.IX Item "-mpic"
+.PD 0
+.IP "\fB\-mno\-pic\fR" 4
+.IX Item "-mno-pic"
+.PD
+The \fB\-mpic\fR option causes the assembler to generate the
+\&\f(CW\*(C`Tag_ABI_PIC\*(C'\fR attribute with a value of 1, indicating that the
+code is using position-independent code addressing,  The
+\&\f(CW\*(C`\-mno\-pic\*(C'\fR option, the default, causes the tag to have a value of
+0, indicating position-dependent code addressing.  The linker will
+emit a warning if objects of different type (position-dependent and
+position-independent) are linked together.
+.IP "\fB\-mbig\-endian\fR" 4
+.IX Item "-mbig-endian"
+.PD 0
+.IP "\fB\-mlittle\-endian\fR" 4
+.IX Item "-mlittle-endian"
+.PD
+Generate code for the specified endianness.  The default is
+little-endian.
+.PP
+The following options are available when as is configured for a TILE-Gx
+processor.
+.IP "\fB\-m32 | \-m64\fR" 4
+.IX Item "-m32 | -m64"
+Select the word size, either 32 bits or 64 bits.
+.IP "\fB\-EB | \-EL\fR" 4
+.IX Item "-EB | -EL"
+Select the endianness, either big-endian (\-EB) or little-endian (\-EL).
+.PP
+The following option is available when as is configured for a Visium
+processor.
+.IP "\fB\-mtune=\fR\fIarch\fR" 4
+.IX Item "-mtune=arch"
+This option specifies the target architecture.  If an attempt is made to
+assemble an instruction that will not execute on the target architecture,
+the assembler will issue an error message.
+.Sp
+The following names are recognized:
+\&\f(CW\*(C`mcm24\*(C'\fR
+\&\f(CW\*(C`mcm\*(C'\fR
+\&\f(CW\*(C`gr5\*(C'\fR
+\&\f(CW\*(C`gr6\*(C'\fR
+.PP
+The following options are available when as is configured for an
+Xtensa processor.
+.IP "\fB\-\-text\-section\-literals | \-\-no\-text\-section\-literals\fR" 4
+.IX Item "--text-section-literals | --no-text-section-literals"
+Control the treatment of literal pools.  The default is
+\&\fB\-\-no\-text\-section\-literals\fR, which places literals in
+separate sections in the output file.  This allows the literal pool to be
+placed in a data \s-1RAM/ROM.\s0  With \fB\-\-text\-section\-literals\fR, the
+literals are interspersed in the text section in order to keep them as
+close as possible to their references.  This may be necessary for large
+assembly files, where the literals would otherwise be out of range of the
+\&\f(CW\*(C`L32R\*(C'\fR instructions in the text section.  Literals are grouped into
+pools following \f(CW\*(C`.literal_position\*(C'\fR directives or preceding
+\&\f(CW\*(C`ENTRY\*(C'\fR instructions.  These options only affect literals referenced
+via PC-relative \f(CW\*(C`L32R\*(C'\fR instructions; literals for absolute mode
+\&\f(CW\*(C`L32R\*(C'\fR instructions are handled separately.
+.IP "\fB\-\-auto\-litpools | \-\-no\-auto\-litpools\fR" 4
+.IX Item "--auto-litpools | --no-auto-litpools"
+Control the treatment of literal pools.  The default is
+\&\fB\-\-no\-auto\-litpools\fR, which in the absence of
+\&\fB\-\-text\-section\-literals\fR places literals in separate sections
+in the output file.  This allows the literal pool to be placed in a data
+\&\s-1RAM/ROM.\s0  With \fB\-\-auto\-litpools\fR, the literals are interspersed
+in the text section in order to keep them as close as possible to their
+references, explicit \f(CW\*(C`.literal_position\*(C'\fR directives are not
+required.  This may be necessary for very large functions, where single
+literal pool at the beginning of the function may not be reachable by
+\&\f(CW\*(C`L32R\*(C'\fR instructions at the end.  These options only affect
+literals referenced via PC-relative \f(CW\*(C`L32R\*(C'\fR instructions; literals
+for absolute mode \f(CW\*(C`L32R\*(C'\fR instructions are handled separately.
+When used together with \fB\-\-text\-section\-literals\fR,
+\&\fB\-\-auto\-litpools\fR takes precedence.
+.IP "\fB\-\-absolute\-literals | \-\-no\-absolute\-literals\fR" 4
+.IX Item "--absolute-literals | --no-absolute-literals"
+Indicate to the assembler whether \f(CW\*(C`L32R\*(C'\fR instructions use absolute
+or PC-relative addressing.  If the processor includes the absolute
+addressing option, the default is to use absolute \f(CW\*(C`L32R\*(C'\fR
+relocations.  Otherwise, only the PC-relative \f(CW\*(C`L32R\*(C'\fR relocations
+can be used.
+.IP "\fB\-\-target\-align | \-\-no\-target\-align\fR" 4
+.IX Item "--target-align | --no-target-align"
+Enable or disable automatic alignment to reduce branch penalties at some
+expense in code size.    This optimization is enabled by default.  Note
+that the assembler will always align instructions like \f(CW\*(C`LOOP\*(C'\fR that
+have fixed alignment requirements.
+.IP "\fB\-\-longcalls | \-\-no\-longcalls\fR" 4
+.IX Item "--longcalls | --no-longcalls"
+Enable or disable transformation of call instructions to allow calls
+across a greater range of addresses.    This option should be used when call
+targets can potentially be out of range.  It may degrade both code size
+and performance, but the linker can generally optimize away the
+unnecessary overhead when a call ends up within range.  The default is
+\&\fB\-\-no\-longcalls\fR.
+.IP "\fB\-\-transform | \-\-no\-transform\fR" 4
+.IX Item "--transform | --no-transform"
+Enable or disable all assembler transformations of Xtensa instructions,
+including both relaxation and optimization.  The default is
+\&\fB\-\-transform\fR; \fB\-\-no\-transform\fR should only be used in the
+rare cases when the instructions must be exactly as specified in the
+assembly source.  Using \fB\-\-no\-transform\fR causes out of range
+instruction operands to be errors.
+.IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR" 4
+.IX Item "--rename-section oldname=newname"
+Rename the \fIoldname\fR section to \fInewname\fR.  This option can be used
+multiple times to rename multiple sections.
+.IP "\fB\-\-trampolines | \-\-no\-trampolines\fR" 4
+.IX Item "--trampolines | --no-trampolines"
+Enable or disable transformation of jump instructions to allow jumps
+across a greater range of addresses.    This option should be used when jump targets can
+potentially be out of range.  In the absence of such jumps this option
+does not affect code size or performance.  The default is
+\&\fB\-\-trampolines\fR.
+.IP "\fB\-\-abi\-windowed | \-\-abi\-call0\fR" 4
+.IX Item "--abi-windowed | --abi-call0"
+Choose \s-1ABI\s0 tag written to the \f(CW\*(C`.xtensa.info\*(C'\fR section.  \s-1ABI\s0 tag
+indicates \s-1ABI\s0 of the assembly code.  A warning is issued by the linker
+on an attempt to link object files with inconsistent \s-1ABI\s0 tags.
+Default \s-1ABI\s0 is chosen by the Xtensa core configuration.
+.PP
+The following options are available when as is configured for an
+Z80 processor.
+.PP
+\&\f(CW@chapter\fR Z80 Dependent Features
+.SS "Command-line Options"
+.IX Subsection "Command-line Options"
+.IP "\fB\-march=\fR\fI\s-1CPU\s0\fR\fB[\-\fR\fI\s-1EXT\s0\fR\fB...][+\fR\fI\s-1EXT\s0\fR\fB...]\fR" 4
+.IX Item "-march=CPU[-EXT...][+EXT...]"
+This option specifies the target processor. The assembler will issue
+an error message if an attempt is made to assemble an instruction which
+will not execute on the target processor. The following processor names
+are recognized:
+\&\f(CW\*(C`z80\*(C'\fR,
+\&\f(CW\*(C`z180\*(C'\fR,
+\&\f(CW\*(C`ez80\*(C'\fR,
+\&\f(CW\*(C`gbz80\*(C'\fR,
+\&\f(CW\*(C`z80n\*(C'\fR,
+\&\f(CW\*(C`r800\*(C'\fR.
+In addition to the basic instruction set, the assembler can be told to
+accept some extention mnemonics. For example,
+\&\f(CW\*(C`\-march=z180+sli+infc\*(C'\fR extends \fIz180\fR with \fI\s-1SLI\s0\fR instructions and
+\&\fI\s-1IN F,\s0(C)\fR. The following extentions are currently supported:
+\&\f(CW\*(C`full\*(C'\fR (all known instructions),
+\&\f(CW\*(C`adl\*(C'\fR (\s-1ADL CPU\s0 mode by default, eZ80 only),
+\&\f(CW\*(C`sli\*(C'\fR (instruction known as \fI\s-1SLI\s0\fR, \fI\s-1SLL\s0\fR or \fI\s-1SL1\s0\fR),
+\&\f(CW\*(C`xyhl\*(C'\fR (instructions with halves of index registers: \fI\s-1IXL\s0\fR, \fI\s-1IXH\s0\fR,
+\&\fI\s-1IYL\s0\fR, \fI\s-1IYH\s0\fR),
+\&\f(CW\*(C`xdcb\*(C'\fR (instructions like \fIRotOp (II+d),R\fR and \fIBitOp n,(II+d),R\fR),
+\&\f(CW\*(C`infc\*(C'\fR (instruction \fI\s-1IN F,\s0(C)\fR or \fI\s-1IN\s0 (C)\fR),
+\&\f(CW\*(C`outc0\*(C'\fR (instruction \fI\s-1OUT\s0 (C),0\fR).
+Note that rather than extending a basic instruction set, the extention
+mnemonics starting with \f(CW\*(C`\-\*(C'\fR revoke the respective functionality:
+\&\f(CW\*(C`\-march=z80\-full+xyhl\*(C'\fR first removes all default extentions and adds
+support for index registers halves only.
+.Sp
+If this option is not specified then \f(CW\*(C`\-march=z80+xyhl+infc\*(C'\fR is assumed.
+.IP "\fB\-local\-prefix=\fR\fIprefix\fR" 4
+.IX Item "-local-prefix=prefix"
+Mark all labels with specified prefix as local. But such label can be
+marked global explicitly in the code. This option do not change default
+local label prefix \f(CW\*(C`.L\*(C'\fR, it is just adds new one.
+.IP "\fB\-colonless\fR" 4
+.IX Item "-colonless"
+Accept colonless labels. All symbols at line begin are treated as labels.
+.IP "\fB\-sdcc\fR" 4
+.IX Item "-sdcc"
+Accept assembler code produced by \s-1SDCC.\s0
+.IP "\fB\-fp\-s=\fR\fI\s-1FORMAT\s0\fR" 4
+.IX Item "-fp-s=FORMAT"
+Single precision floating point numbers format. Default: ieee754 (32 bit).
+.IP "\fB\-fp\-d=\fR\fI\s-1FORMAT\s0\fR" 4
+.IX Item "-fp-d=FORMAT"
+Double precision floating point numbers format. Default: ieee754 (64 bit).
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBgcc\fR\|(1), \fBld\fR\|(1), and the Info entries for \fIbinutils\fR and \fIld\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/asciitopgm.1 b/upstream/mageia-cauldron/man1/asciitopgm.1
new file mode 100644
index 00000000..ff6adc8b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/asciitopgm.1
@@ -0,0 +1,102 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Asciitopgm User Manual" 0 "20 January 2011" "netpbm documentation"
+
+.SH NAME
+asciitopgm - convert ASCII graphics into a PGM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBasciitopgm\fP
+[\fB-d\fP \fIdivisor\fP] \fIheight\fP \fIwidth\fP [\fIasciifile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBasciitopgm\fP reads ASCII data as input and produces a PGM image
+with pixel values which are an approximation of the
+"brightness" of the ASCII characters, assuming
+black-on-white printing.  In other words, a capital M is very dark, a
+period is very light, and a space is white.
+.PP
+Obviously, \fBasciitopgm\fP assumes a certain font in assigning
+a brightness value to a character.
+.PP
+\fBasciitopgm\fP considers ASCII control characters to be all white.  For
+a lower case character, It assigns a special brightnesses which has nothing to
+do with what it looks like printed.
+\fBasciitopgm\fP takes the ASCII character code from the lower 7 bits
+of each input byte.  But it warns you if the most significant bit of
+any input byte is not zero.
+.PP
+The output image is \fIheight\fP pixels high by \fIwidth\fP pixels wide,
+truncating and padding with white on the right and bottom as necessary.
+.PP
+The \fIdivisor\fP value is an integer (decimal) by which the
+blackness of an input character is divided.  You can use this to
+adjust the brightness of the output: for example, if the image is too
+bright, increase the divisor.
+.PP
+In a sort of reminiscence of Fortran line printer carriage control,
+where a line starts with \fB+\fP (plus), \fBasciitopgm\fP combines it
+with the previous row of output instead of generating a new row.  This
+allows a larger range of gray values.  (In Fortran carriage control, the
+first character of every line sent to the printer tells how much to advance
+the paper, with \fB+\fP meaning not at all, so that the rest of the
+characters on the line overstrike the ones already on the paper.  What
+\fBasciitopgm\fP does is rather different in that \fBasciitopgm\fP does not
+reserve the first character of every line that way.  If the first character is
+anything but \fB+\fP, \fBasciitopgm\fP considers it just to be first
+character of the image.
+.PP
+If you're looking for something that creates an image of text,
+with that text specified in ASCII, that is something quite different.
+Use \fBpbmtext\fP for that.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBasciitopgm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-d\fP \fIdivisor\fP
+Specify the value by which the blackness of an input character is
+divided.  This is an integer value.  Default value is 1.  Larger
+values produce darker output images.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoascii" (1)\c
+\&,
+.BR "pbmtext" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Wilson H. Bent. Jr. (\fIwhb@usc.edu\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/asciitopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/at.1 b/upstream/mageia-cauldron/man1/at.1
new file mode 100644
index 00000000..6aeb5a65
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/at.1
@@ -0,0 +1,322 @@
+.TH AT 1 2009-11-14
+.SH NAME
+at, batch, atq, atrm \- queue, examine, or delete jobs for later execution
+.SH SYNOPSIS
+.B at
+.RB [ \-V ]
+.RB [ \-q
+.IR queue ]
+.RB [ \-f
+.IR file ]
+.RB [ \-u
+.IR username ]
+.RB [ \-mMlv ]
+.IR timespec " ...\&"
+.br
+.B at
+.RB [ \-V ]
+.RB [ \-q
+.IR queue ]
+.RB [ \-f
+.IR file ]
+.RB [ \-u
+.IR username ]
+.RB [ \-mMkv ]
+.RB [ \-t
+.IR time ]
+.br
+.B "at \-c"
+.I job
+[...\&]
+.br
+.B atq
+.RB [ \-V ]
+.RB [ \-q
+.IR queue ]
+.br
+.B at
+.RB [ \-rd ]
+.I job
+[...\&]
+.br
+.B atrm
+.RB [ \-V ]
+.I job
+[...\&]
+.br
+.B batch
+.br
+.B "at \-b"
+.SH DESCRIPTION
+.B at
+and
+.B batch
+read commands from standard input or a specified file which are to
+be executed at a later time, using the shell set by the user's environment
+variable
+.BR SHELL,
+the user's login shell, or ultimately
+.BR /bin/sh .
+.TP 8
+.B at
+executes commands at a specified time.
+.TP 8
+.B atq
+lists the user's pending jobs, unless the user is the superuser; in that
+case, everybody's jobs are listed.  The format of the output lines (one
+for each job) is: Job number, date, hour, queue, and username.
+.TP 8
+.B atrm
+deletes jobs, identified by their job number.
+.TP 8
+.B batch
+executes commands when system load levels permit; in other words, when the load average
+drops below 0.8, or the value specified in the invocation of
+.BR atd .
+.PP
+.B At
+allows fairly complex time
+specifications, extending the POSIX.2 standard.  It accepts times
+of the form
+.B HH:MM
+to run a job at a specific time of day.
+(If that time is already past, the next day is assumed.)
+You may also specify
+.B midnight,
+.B noon,
+or
+.B teatime
+(4pm)
+and you can have a time-of-day suffixed with
+.B AM
+or
+.B PM
+for running in the morning or the evening.
+You can also say what day the job will be run,
+by giving a date in the form
+.B month-name
+.B day
+with an optional
+.B year,
+or giving a date of the form
+.IR MMDD [ CC ] YY ,
+.IR MM / DD /[ CC ] YY ,
+.IR DD . MM .[ CC ] YY
+or
+.RI [ CC ] YY - MM - DD .
+The specification of a date
+.I must
+follow the specification of the time of day.
+You can also give times like
+.B now
+.B +
+.I count
+.I time-units,
+where the time-units can be
+.B minutes,
+.B hours,
+.B days,
+or
+.B weeks
+and you can tell
+.B at
+to run the job today by suffixing the time with
+.B today
+and to run the job tomorrow by suffixing the time with
+.B tomorrow.
+.PP
+For example, to run a job at 4pm three days from now, you would do
+.B at 4pm + 3 days,
+to run a job at 10:00am on July 31, you would do
+.B at 10am Jul 31
+and to run a job at 1am tomorrow, you would do
+.B at 1am tomorrow.
+.PP
+If you specify a job to absolutely run at a specific time and date in
+the past, the job will run as soon as possible.  For example, if it is
+8pm and you do a
+.B at 6pm today,
+it will run more likely at 8:05pm.
+.PP
+The definition of the time specification can be found in
+.IR /usr/share/doc/at/timespec .
+.PP
+For both
+.BR at " and " batch ,
+commands are read from standard input or the file specified
+with the
+.B \-f
+option and executed.
+The working directory, the environment (except for the variables
+.BR BASH_VERSINFO ,
+.BR DISPLAY ,
+.BR EUID ,
+.BR GROUPS ,
+.BR SHELLOPTS ,
+.BR TERM ,
+.BR UID ,
+and
+.BR _ )
+and the umask are retained from the time of invocation.
+
+As
+.B at
+is currently implemented as a setuid program, other environment variables (e.g.,
+.BR LD_LIBRARY_PATH " or " LD_PRELOAD )
+are also not exported.  This may change in the future.  As a workaround,
+set these variables explicitly in your job.
+
+An
+.BR "at " \-
+or
+.BR "batch "\-
+command invoked from a
+.BR su (1)
+shell will retain the current userid.
+The user will be mailed standard error and standard output from his
+commands, if any.
+Mail will be sent using the command
+.BR /usr/sbin/sendmail .
+If
+.B at
+is executed from a
+.BR su (1)
+shell, the owner of the login shell will receive the mail.
+.PP
+The superuser may use these commands in any case.
+For other users, permission to use at is determined by the files
+.I /etc/at.allow
+and
+.IR /etc/at.deny .
+See
+.BR at.allow (5)
+for details.
+.SH OPTIONS
+.TP 8
+.B \-V
+prints the version number to standard error and exit successfully.
+.TP 8
+.BI \-q " queue"
+uses the specified queue.
+A queue designation consists of a single letter; valid queue designations
+range from
+.B a
+to
+.B z
+and
+.B A
+to
+.BR Z .
+The
+.B a
+queue is the default for
+.B at
+and the
+.B b
+queue for
+.BR batch .
+Queues with higher letters run with increased niceness.  The special
+queue "=" is reserved for jobs which are currently running.
+.P
+If a job is submitted to a queue designated with an uppercase letter, the
+job is treated as if it were submitted to batch at the time of the job.
+Once the time is reached, the batch processing rules with respect to load
+average apply.
+If
+.B atq
+is given a specific queue, it will only show jobs pending in that queue.
+.TP 8
+.B \-m
+Send mail to the user when the job has completed even if there was no
+output.
+.TP 8
+.B \-M
+Never send mail to the user.
+.TP 8
+.BI \-u " username"
+Sends mail to 
+.I username
+rather than the current user.
+.TP 8
+.BI \-f " file"
+Reads the job from
+.I file
+rather than standard input.
+.TP 8
+.BI \-t " time"
+run the job at
+.IR time ,
+given in the format [[CC]YY]MMDDhhmm[.ss]
+.TP 8
+.B \-l
+Is an alias for
+.B atq.
+.TP
+.B \-r
+Is an alias for
+.B atrm.
+.TP
+.B \-d
+Is an alias for
+.B atrm.
+.TP
+.B \-b
+is an alias for
+.BR batch .
+.TP
+.B \-v
+Shows the time the job will be executed before reading the job.
+.P
+Times displayed will be in the format "Thu Feb 20 14:50:00 1997".
+.TP
+.B
+\-c
+cats the jobs listed on the command line to standard output.
+.SH FILES
+.I /var/spool/at
+.br
+.I /var/spool/at/spool
+.br
+.I /proc/loadavg
+.br
+.I /var/run/utmp
+.br
+.I /etc/at.allow
+.br
+.I /etc/at.deny
+.SH SEE ALSO
+.BR at.allow (5),
+.BR at.deny (5),
+.BR atd (8),
+.BR cron (1),
+.BR nice (1),
+.BR sh (1),
+.BR umask (2).
+.SH BUGS
+The correct operation of
+.B batch
+for Linux depends on the presence of a
+.IR proc -
+type directory mounted on
+.IR /proc .
+.PP
+If the file
+.I /var/run/utmp
+is not available or corrupted, or if the user is not logged on at the
+time
+.B at
+is invoked, the mail is sent to the userid found
+in the environment variable
+.BR LOGNAME .
+If that is undefined or empty, the current userid is assumed.
+.PP
+.B At
+and
+.B batch
+as presently implemented are not suitable when users are competing for
+resources.
+If this is the case for your site, you might want to consider another
+batch system, such as
+.BR nqs .
+.SH AUTHOR
+At was mostly written by Thomas Koenig.
diff --git a/upstream/mageia-cauldron/man1/atktopbm.1 b/upstream/mageia-cauldron/man1/atktopbm.1
new file mode 100644
index 00000000..eaa79655
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/atktopbm.1
@@ -0,0 +1,61 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Atktopbm User Manual" 0 "26 September 1991" "netpbm documentation"
+
+.SH NAME
+atktopbm - convert Andrew Toolkit raster object to PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBatktopbm\fP [\fIatkfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBatktopbm\fP reads an Andrew Toolkit raster object as input.
+and produces a PBM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBatktopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pbmtoatk" (1)\c
+\&
+.IP \(bu
+
+.BR "pbm" (1)\c
+\&
+
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Bill Janssen.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/atktopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/aumix.1 b/upstream/mageia-cauldron/man1/aumix.1
new file mode 100644
index 00000000..523f894b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/aumix.1
@@ -0,0 +1,341 @@
+.\" $Aumix: aumix/doc/aumix.1,v 1.7 2010/05/04 23:30:28 trevor Exp $
+.\" from mdoc.samples(7)
+.\"
+.\" The following requests are required for all man pages.
+.\"           .Dd Month day, year
+.\"           .Os OPERATING_SYSTEM [version/release]
+.\"           .Dt DOCUMENT_TITLE [section number] [volume]
+.\"           .Sh NAME
+.\"           .Nm name
+.\"           .Nd one line description of name
+.\"           .Sh SYNOPSIS
+.\"           .Sh DESCRIPTION
+.\" The following requests should be uncommented and
+.\" used where appropriate.  This next request is
+.\" for sections 2, 3 and 9 function return values only.
+.\" .Sh RETURN VALUES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\" .Sh ENVIRONMENT
+.\" .Sh FILES
+.\" .Sh EXAMPLES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\"     (command return values (to shell) and
+.\"       fprintf/stderr type diagnostics)
+.\" .Sh DIAGNOSTICS
+.\" The next request is for sections 2, 3 and 9 error
+.\" and signal handling only.
+.\" .Sh ERRORS
+.\" .Sh SEE ALSO
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.\" .Sh BUGS
+.\"
+.Dd July 13, 2000
+.Os
+.Dt AUMIX 1
+.Sh NAME
+.Nm aumix
+.Nd adjust audio mixer
+.Sh SYNOPSIS
+.Nm
+[\-<channel option>[[+|\-][<amount>]]|<level>|R[ecord]|P[lay]|q[uery]]
+[\-dhILqS] [\-f <rc file>][\-C <color scheme file>]
+.Sh DESCRIPTION
+This program adjusts the settings of an audio mixing device.
+It can be used from the command line, in scripts, or interactively
+with the keyboard or mouse.
+.Sh OPTIONS
+.Ss CHANNEL OPTIONS
+.Bl -tag -width Fl -compact
+.It Fl v
+main volume
+.It Fl b
+bass
+.It Fl c
+CD
+.It Fl i
+input gain
+.It Fl l
+line
+.It Fl m
+microphone
+.It Fl o
+output gain
+.It Fl p
+PC speaker
+.It Fl r
+record
+.It Fl s
+synthesizer
+.It Fl t
+treble
+.It Fl w
+PCM
+.It Fl W
+PCM 2
+.It Fl x
+mix monitor
+.It Fl 1
+line 1
+.It Fl 2
+line 2
+.It Fl 3
+line 3
+.El
+.Pp
+For each channel, 
+.Cm q
+queries, 
+.Cm +
+and
+.Cm \-
+increment and decrement by one, or an amount if one is specified.
+If no
+.Cm +
+or
+.Cm \-
+is given after the channel option, a number sets a specific level
+(monophonically).
+.Ss OTHER OPTIONS
+.Bl -tag -width Fl
+.It Fl C Ar color_scheme_file
+specify the name of a file containing a color scheme.
+This implies
+.Fl I .
+.It Fl d Ar device_file
+specify the name of the mixer device (default is
+.Pa /dev/mixer )
+.It Fl f Ar rc_file
+specify file for saving and loading settings
+.It Fl h
+display information on usage
+.It Fl I
+run
+.Nm
+interactively, using the full-screen ncurses-based interface.
+This is the default if no options are given, but must be specified
+in order to have
+.Nm
+go into interactive mode after doing things non-interactively.
+.It Fl L
+load settings from
+.Pa $HOME/.aumixrc ,
+or
+.Pa /etc/aumixrc
+if the former is inaccessible
+.It Fl q
+query all devices and print their settings
+.It Fl S
+save settings to
+.Pa $HOME/.aumixrc
+.El
+.Sh EXAMPLES
+The command
+.Bd -literal -offset indent
+aumix \-q \-v75 \-m 0 \-c R \-c+10 \-m q
+.Ed
+.Pp
+prints all settings, sets volume to 75%, sets microphone to 0, sets
+CD to record, increases the CD level by ten (both left and right),
+and prints the new settings for the microphone.
+.Pp
+The .aumixrc file containing:
+.Bd -literal -offset indent
+vol:60:60
+wait:5000
+vol:50:50
+.Ed
+.Pp
+sets the volume to 60%, waits five seconds, then reduces the volume to 50%.
+Note that "wait" lines will not be saved by aumix.  They must be added by hand.
+.Sh INTERACTIVE USE
+If no options are given on the command line, and
+.Nm
+is compiled with ncurses, it will run interactively.
+.Ss LAYOUT
+The left bank of controls is used for adjusting levels; the right
+bank is for adjusting balance.
+Mixing channels not supported by your hardware will not be shown.
+Mixing channels which are stereo-capable will have balance controls.
+.Ss KEYS
+The following keys control
+.Nm
+in interactive mode:
+.Bl -tag -width Fl
+.It page up, page down, up and down cursor
+select a new control.
+.It Tab, Enter, <, >, comma and period
+toggle between level and balance controls
+.It + , \- , \&[ , \&] , left and right cursor and digits
+adjust the setting of the current device.
+The
+.Li +
+and right cursor keys increase the level by 3%; the
+.Li \-
+and left cursor keys decrease it by the same amount.
+The
+.Li \&[
+key sets it to 0% and
+.Li \&]
+or
+.Li 0
+set it to 100%.
+The digits
+.Li 1
+to
+.Li 9
+set it to 10% through 90%.
+The same keys work analogously on the balance controls.
+.It Space
+toggles between record and play for controls which are capable of 
+this.
+.It |
+centers the balance of the current device.
+.It K or k
+show a description of the functions of keys
+.It L or l
+load settings from
+.Pa $HOME/.aumixrc ,
+falling back to
+.Pa /etc/aumixrc
+.It M or m
+mute or unmute
+.It O or o
+.Dq only :
+mute all channels but the current one
+.It S or s
+save settings to the rc file
+.It U or u
+undo any muting
+.It Q or q
+end the program
+.It ^L
+refresh screen
+.El
+.Pp
+^Z, ^D and ^C also have their normal function (the screen is refreshed when
+.Nm
+is brought to the foreground).
+.Ss MOUSE
+In interactive mode,
+.Nm
+can accept input from the mouse if
+.Xr gpm 8
+is running and
+.Nm
+is compiled with
+.Xr gpm 8
+support.
+If gpm is not running but gpm support is included, the message
+.Ql mouse off
+will appear at the top of the screen, and only keyboard input will be
+accepted.
+With
+.Xr gpm 8
+running, most functions can be performed through the mouse.
+The mouse is active whenever one of its buttons is held down.
+While active, it works in the following ways:
+.Bl -bullet -compact
+.It
+over a control track, it sets the control to match the position of
+the mouse cursor.
+.It
+over a record/play indicator, it toggles the record/play state.
+.It
+over the 
+.Ql Quit ,
+.Ql Load ,
+.Ql Save ,
+.Ql Keys ,
+.Ql Mute ,
+.Ql Only ,
+or
+.Ql Undo
+labels at the top of the screen, it causes those actions to take place.
+.El
+.Sh ENVIRONMENT
+The
+.Ev HOME
+variable is used.
+When
+.Nm
+is compiled with GTK+ support,
+.Ev DISPLAY
+is checked, and if set is used.
+.Ev LANG
+is used when
+.Nm
+the ncurses screen is displayed.
+.Sh FILES
+Saved settings for the mixer are kept in the
+.Pa /etc/aumixrc
+and
+.Pa $HOME/.aumixrc
+files, but can be kept anywhere if specified explicitly.
+Color schemes are normally kept in the directory given
+by
+.Ev DATADIR
+at compilation time, but are preferentially loaded
+from the current directory and can be kept anywhere so long as the
+path to them is specified.
+The format of these files is:
+.Bd -filled -offset indent
+.Ar item
+.Ar foreground
+.Ar background
+.Ed 
+.Pp
+where
+.Ar item
+is one of
+.Ql active ,
+.Ql axis ,
+.Ql handle ,
+.Ql hotkey ,
+.Ql menu ,
+.Ql play ,
+.Ql record ,
+or
+.Ql track
+and
+.Ar foreground
+and
+.Ar background
+are one of
+.Ql black ,
+.Ql red ,
+.Ql green ,
+.Ql yellow ,
+.Ql blue ,
+.Ql magenta ,
+.Ql cyan ,
+or
+.Ql white .
+The words should be separated by whitespace and can be upper-,
+lower-, or mixed-case.
+Lines not matching all these conditions are ignored.
+Some samples of color schemes are provided, named
+after the sort of terminal where they should be most suitable.
+.Pp
+If either foreground or background is given as
+.Ql \- ,
+then the default color for that is used.
+The defaults are a white foreground and black background.
+.Pp
+An xpm icon is provided.
+.Sh VERSION
+This page corresponds to version 2.9.1.
+.Sh BUGS
+Suspending with ^Z may make the terminal difficult to use.
+.Sh HOME PAGE
+.Bd -literal
+http://jpj.net/~trevor/aumix.html
+.Sh MAILING LISTS
+.Bd -literal
+https://gna.org/mail/?group=aumix
+.Sh SEE ALSO
+.Xr gpm 1 ,
+.Xr moused 8 ,
+.Xr sb 4 ,
+.Xr xaumix 1
diff --git a/upstream/mageia-cauldron/man1/autoconf.1 b/upstream/mageia-cauldron/man1/autoconf.1
new file mode 100644
index 00000000..c7ba1d7b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autoconf.1
@@ -0,0 +1,129 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTOCONF "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autoconf \- Generate configuration scripts
+.SH SYNOPSIS
+.B autoconf
+[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR]
+.SH DESCRIPTION
+Generate a configuration script from a TEMPLATE\-FILE if given, or
+\&'configure.ac' if present, or else 'configure.in'.  Output is sent
+to the standard output if TEMPLATE\-FILE is given, else into
+\&'configure'.
+.SS "Operation modes:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+consider all files obsolete
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE (stdout is the default)
+.TP
+\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR
+report the warnings falling in CATEGORY
+(comma\-separated list accepted)
+.SS "Warning categories are:"
+.TP
+cross
+cross compilation issues
+.TP
+gnu
+GNU coding standards (default in gnu and gnits modes)
+.TP
+obsolete
+obsolete features or constructions (default)
+.TP
+override
+user redefinitions of Automake rules or variables
+.TP
+portability
+portability issues (default in gnu and gnits modes)
+.TP
+portability\-recursive
+nested Make variables (default with \fB\-Wportability\fR)
+.TP
+extra\-portability
+extra portability issues related to obscure tools
+.TP
+syntax
+dubious syntactic constructs (default)
+.TP
+unsupported
+unsupported or incomplete features (default)
+.SS "-W also understands:"
+.TP
+all
+turn on all the warnings
+.TP
+none
+turn off all the warnings
+.TP
+no\-CATEGORY
+turn off warnings in CATEGORY
+.TP
+error
+treat all enabled warnings as errors
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.SS "Tracing:"
+.TP
+\fB\-t\fR, \fB\-\-trace\fR=\fI\,MACRO[\/\fR:FORMAT]
+report the list of calls to MACRO
+.TP
+\fB\-i\fR, \fB\-\-initialization\fR
+also trace Autoconf's initialization process
+.PP
+In tracing mode, no configuration script is created.  FORMAT defaults
+to '$f:$l:$n:$%'; see 'autom4te \fB\-\-help\fR' for information about FORMAT.
+.SH AUTHOR
+Written by David J. MacKenzie and Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/autoheader.1 b/upstream/mageia-cauldron/man1/autoheader.1
new file mode 100644
index 00000000..f416c436
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autoheader.1
@@ -0,0 +1,114 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTOHEADER "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autoheader \- Create a template header for configure
+.SH SYNOPSIS
+.B autoheader
+[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR]
+.SH DESCRIPTION
+Create a template file of C '#define' statements for 'configure' to
+use.  To this end, scan TEMPLATE\-FILE, or 'configure.ac' if present,
+or else 'configure.in'.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+consider all files obsolete
+.TP
+\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR
+report the warnings falling in CATEGORY
+(comma\-separated list accepted)
+.SS "Warning categories are:"
+.TP
+cross
+cross compilation issues
+.TP
+gnu
+GNU coding standards (default in gnu and gnits modes)
+.TP
+obsolete
+obsolete features or constructions (default)
+.TP
+override
+user redefinitions of Automake rules or variables
+.TP
+portability
+portability issues (default in gnu and gnits modes)
+.TP
+portability\-recursive
+nested Make variables (default with \fB\-Wportability\fR)
+.TP
+extra\-portability
+extra portability issues related to obscure tools
+.TP
+syntax
+dubious syntactic constructs (default)
+.TP
+unsupported
+unsupported or incomplete features (default)
+.SS "-W also understands:"
+.TP
+all
+turn on all the warnings
+.TP
+none
+turn off all the warnings
+.TP
+no\-CATEGORY
+turn off warnings in CATEGORY
+.TP
+error
+treat all enabled warnings as errors
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.SH AUTHOR
+Written by Roland McGrath and Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/autom4te.1 b/upstream/mageia-cauldron/man1/autom4te.1
new file mode 100644
index 00000000..2174ee8a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autom4te.1
@@ -0,0 +1,198 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTOM4TE "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autom4te \- Generate files and scripts thanks to M4
+.SH SYNOPSIS
+.B autom4te
+[\fI\,OPTION\/\fR]... [\fI\,FILES\/\fR]
+.SH DESCRIPTION
+Run GNU M4 on the FILES, avoiding useless runs.  Output the traces if tracing,
+the frozen file if freezing, otherwise the expansion of the FILES.
+.PP
+If some of the FILES are named 'FILE.m4f' they are considered to be M4
+frozen files of all the previous files (which are therefore not loaded).
+If 'FILE.m4f' is not found, then 'FILE.m4' will be used, together with
+all the previous files.
+.PP
+Some files may be optional, i.e., will only be processed if found in the
+include path, but then must end in '.m4?';  the question mark is not part
+of the actual file name.
+.SS "Operation modes:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE (defaults to '\-', stdout)
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+don't rely on cached values
+.TP
+\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR
+report the warnings falling in CATEGORY
+(comma\-separated list accepted)
+.TP
+\fB\-l\fR, \fB\-\-language\fR=\fI\,LANG\/\fR
+specify the set of M4 macros to use
+.TP
+\fB\-C\fR, \fB\-\-cache\fR=\fI\,DIRECTORY\/\fR
+preserve results for future runs in DIRECTORY
+.TP
+\fB\-\-no\-cache\fR
+disable the cache
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fI\,OCTAL\/\fR
+change the non trace output file mode (0666)
+.TP
+\fB\-M\fR, \fB\-\-melt\fR
+don't use M4 frozen files
+.SS "Languages include:"
+.TP
+\&'Autoconf'
+create Autoconf configure scripts
+.TP
+\&'Autotest'
+create Autotest test suites
+.TP
+\&'M4sh'
+create M4sh shell scripts
+.TP
+\&'M4sugar'
+create M4sugar output
+.SS "Warning categories are:"
+.TP
+cross
+cross compilation issues
+.TP
+gnu
+GNU coding standards (default in gnu and gnits modes)
+.TP
+obsolete
+obsolete features or constructions (default)
+.TP
+override
+user redefinitions of Automake rules or variables
+.TP
+portability
+portability issues (default in gnu and gnits modes)
+.TP
+portability\-recursive
+nested Make variables (default with \fB\-Wportability\fR)
+.TP
+extra\-portability
+extra portability issues related to obscure tools
+.TP
+syntax
+dubious syntactic constructs (default)
+.TP
+unsupported
+unsupported or incomplete features (default)
+.SS "-W also understands:"
+.TP
+all
+turn on all the warnings
+.TP
+none
+turn off all the warnings
+.TP
+no\-CATEGORY
+turn off warnings in CATEGORY
+.TP
+error
+treat all enabled warnings as errors
+.PP
+The environment variables 'M4' and 'WARNINGS' are honored.
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.SS "Tracing:"
+.TP
+\fB\-t\fR, \fB\-\-trace\fR=\fI\,MACRO[\/\fR:FORMAT]
+report the MACRO invocations
+.TP
+\fB\-p\fR, \fB\-\-preselect\fR=\fI\,MACRO\/\fR
+prepare to trace MACRO in a future run
+.SS "Freezing:"
+.TP
+\fB\-F\fR, \fB\-\-freeze\fR
+produce an M4 frozen state file for FILES
+.SS "FORMAT defaults to '$f:$l:$n:$%', and can use the following escapes:"
+.TP
+$$
+literal $
+.TP
+$f
+file where macro was called
+.TP
+$l
+line where macro was called
+.TP
+$d
+nesting depth of macro call
+.TP
+$n
+name of the macro
+.TP
+$NUM
+argument NUM, unquoted and with newlines
+.TP
+$SEP@
+all arguments, with newlines, quoted, and separated by SEP
+.TP
+$SEP*
+all arguments, with newlines, unquoted, and separated by SEP
+.TP
+$SEP%
+all arguments, without newlines, unquoted, and separated by SEP
+.PP
+SEP can be empty for the default (comma for @ and *, colon for %),
+a single character for that character, or {STRING} to use a string.
+.SH AUTHOR
+Written by Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/autopoint.1 b/upstream/mageia-cauldron/man1/autopoint.1
new file mode 100644
index 00000000..c179ea25
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autopoint.1
@@ -0,0 +1,47 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH AUTOPOINT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+autopoint \- copies standard gettext infrastructure
+.SH SYNOPSIS
+.B autopoint
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Copies standard gettext infrastructure files into a source package.
+.SH OPTIONS
+.TP
+\fB\-\-help\fR
+print this help and exit
+.TP
+\fB\-\-version\fR
+print version information and exit
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+force overwriting of files that already exist
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+print modifications but don't perform them
+.SH AUTHOR
+Written by Bruno Haible
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2002\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B autopoint
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B autopoint
+programs are properly installed at your site, the command
+.IP
+.B info autopoint
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/autoreconf.1 b/upstream/mageia-cauldron/man1/autoreconf.1
new file mode 100644
index 00000000..770cc98d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autoreconf.1
@@ -0,0 +1,137 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTORECONF "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autoreconf \- Update generated configuration files
+.SH SYNOPSIS
+.B autoreconf
+[\fI\,OPTION\/\fR]... [\fI\,DIRECTORY\/\fR]...
+.SH DESCRIPTION
+Run 'autoconf' and, when needed, 'aclocal', 'autoheader', 'automake',
+\&'autopoint' (formerly 'gettextize'), 'libtoolize', 'intltoolize', and
+\&'gtkdocize' to regenerate the GNU Build System files in specified
+DIRECTORIES and their subdirectories (defaulting to '.').
+.PP
+By default, it only remakes those files that are older than their
+sources.  If you install new versions of the GNU Build System,
+you can make 'autoreconf' remake all of the files by giving it the
+\&'\-\-force' option.
+.SS "Operation modes:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+consider all generated and standard files obsolete
+.TP
+\fB\-i\fR, \fB\-\-install\fR
+copy missing standard auxiliary files
+.TP
+\fB\-\-no\-recursive\fR
+don't rebuild sub\-packages
+.TP
+\fB\-s\fR, \fB\-\-symlink\fR
+with \fB\-i\fR, install symbolic links instead of copies
+.TP
+\fB\-m\fR, \fB\-\-make\fR
+when applicable, re\-run ./configure && make
+.TP
+\fB\-W\fR, \fB\-\-warnings\fR=\fI\,CATEGORY\/\fR
+report the warnings falling in CATEGORY
+(comma\-separated list accepted)
+.SS "Warning categories are:"
+.TP
+cross
+cross compilation issues
+.TP
+gnu
+GNU coding standards (default in gnu and gnits modes)
+.TP
+obsolete
+obsolete features or constructions (default)
+.TP
+override
+user redefinitions of Automake rules or variables
+.TP
+portability
+portability issues (default in gnu and gnits modes)
+.TP
+portability\-recursive
+nested Make variables (default with \fB\-Wportability\fR)
+.TP
+extra\-portability
+extra portability issues related to obscure tools
+.TP
+syntax
+dubious syntactic constructs (default)
+.TP
+unsupported
+unsupported or incomplete features (default)
+.SS "-W also understands:"
+.TP
+all
+turn on all the warnings
+.TP
+none
+turn off all the warnings
+.TP
+no\-CATEGORY
+turn off warnings in CATEGORY
+.TP
+error
+treat all enabled warnings as errors
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.PP
+The environment variables AUTOCONF, ACLOCAL, AUTOHEADER, AUTOM4TE,
+AUTOMAKE, AUTOPOINT, GTKDOCIZE, INTLTOOLIZE, LIBTOOLIZE, M4, MAKE,
+and WARNINGS are honored.
+.SH AUTHOR
+Written by David J. MacKenzie and Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/autoscan.1 b/upstream/mageia-cauldron/man1/autoscan.1
new file mode 100644
index 00000000..3ffc9d39
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autoscan.1
@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTOSCAN "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autoscan \- Generate a preliminary configure.ac
+.SH SYNOPSIS
+.B autoscan
+[\fI\,OPTION\/\fR]... [\fI\,SRCDIR\/\fR]
+.SH DESCRIPTION
+Examine source files in the directory tree rooted at SRCDIR, or the
+current directory if none is given.  Search the source files for
+common portability problems, check for incompleteness of
+\&'configure.ac', and create a file 'configure.scan' which is a
+preliminary 'configure.ac' for that package.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.SH AUTHOR
+Written by David J. MacKenzie and Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/autoupdate.1 b/upstream/mageia-cauldron/man1/autoupdate.1
new file mode 100644
index 00000000..3f5dffc1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/autoupdate.1
@@ -0,0 +1,70 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH AUTOUPDATE "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+autoupdate \- Update a configure.ac to a newer Autoconf
+.SH SYNOPSIS
+.B autoupdate
+[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE-FILE\/\fR]...
+.SH DESCRIPTION
+Update each TEMPLATE\-FILE if given, or 'configure.ac' if present,
+or else 'configure.in', to the syntax of the current version of
+Autoconf.  The original files are backed up.
+.SS "Operation modes:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely report processing
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+don't remove temporary files
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+consider all files obsolete
+.SS "Library directories:"
+.TP
+\fB\-B\fR, \fB\-\-prepend\-include\fR=\fI\,DIR\/\fR
+prepend directory DIR to search path
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append directory DIR to search path
+.SH AUTHOR
+Written by David J. MacKenzie and Akim Demaille.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/avstopam.1 b/upstream/mageia-cauldron/man1/avstopam.1
new file mode 100644
index 00000000..38604e4b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/avstopam.1
@@ -0,0 +1,63 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Avstopam User Manual" 0 "07 February 2010" "netpbm documentation"
+.PP
+
+.PP
+
+.SH NAME
+.PP
+avstopam - convert an AVS X image to a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBavstopam\fP
+[\fIavsfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBavstopam\fP reads a Stardent AVS X image as input and produces a Netpbm
+image as output.
+.PP
+\fIavsfile\fP is the input file, which defaults to Standard Input.
+Output is always on Standard Output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBavstopam\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright\ \(co 2010 Scott Pakin,
+\fIscott+pbm@pakin.org\fP
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pamtoavs" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/avstopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/b2sum.1 b/upstream/mageia-cauldron/man1/b2sum.1
new file mode 100644
index 00000000..dc2bfd44
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/b2sum.1
@@ -0,0 +1,84 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH B2SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+b2sum \- compute and check BLAKE2 message digest
+.SH SYNOPSIS
+.B b2sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check BLAKE2b (512\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-l\fR, \fB\-\-length\fR=\fI\,BITS\/\fR
+digest length in bits; must not exceed the max for
+the blake2 algorithm and must be a multiple of 8
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in RFC 7693.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH AUTHOR
+Written by Padraig Brady and Samuel Neves.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/b2sum>
+.br
+or available locally via: info \(aq(coreutils) b2sum invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/banner.1 b/upstream/mageia-cauldron/man1/banner.1
new file mode 100644
index 00000000..7235053a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/banner.1
@@ -0,0 +1,101 @@
+.\" vim: set ft=nroff .\"
+.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+.\" #
+.\" #              C E D A R
+.\" #          S O L U T I O N S       "Software done right."
+.\" #           S O F T W A R E
+.\" #
+.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+.\" #
+.\" # Author   : Kenneth J. Pronovici <pronovic@ieee.org>
+.\" # Project  : banner
+.\" # Purpose  : Manpage for the banner program
+.\" #
+.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+.TH banner "1" "Oct 2020" "Banner" "Kenneth J. Pronovici"
+.SH NAME
+banner \- prints a short string to the console in very large letters
+.SH SYNOPSIS
+.B banner
+\fIstring\fR
+.SH DESCRIPTION
+.PP
+This is a classic-style banner program similar to the one found in Solaris or
+AIX in the late 1990s.  It prints a short string to the console in very large
+letters.
+.PP
+Banners that do not fit in the terminal will be truncated.  If $COLUMNS is
+exported in the environment, it is taken to be the width of the terminal.  If
+$COLUMNS is not exported, and TIOCGWINSZ is available on the platform, then its
+idea of the terminal size is used.  Otherwise, a terminal width of 80
+characters is assumed.  
+.PP
+Usage is straightforward.  For instance, a single word is printed like this:
+.PP
+   > banner ken
+   
+   #    #  #######  #     #
+   #   #   #        ##    #
+   #  #    #        # #   #
+   ###     #####    #  #  #
+   #  #    #        #   # #
+   #   #   #        #    ##
+   #    #  #######  #     #
+.PP
+Multiple arguments are printed on separate lines:
+.PP
+   > banner one two  
+   
+   #######  #     #  #######  
+   #     #  ##    #  #        
+   #     #  # #   #  #        
+   #     #  #  #  #  #####    
+   #     #  #   # #  #        
+   #     #  #    ##  #        
+   #######  #     #  #######  
+      
+   
+   #######  #     #  #######  
+      #     #  #  #  #     #  
+      #     #  #  #  #     #  
+      #     #  #  #  #     #  
+      #     #  #  #  #     #  
+      #     #  #  #  #     #  
+      #      ## ##   ####### 
+.PP
+To get a single long line containing whitespace, you must quote the string:
+.PP
+   > banner "one two"
+   
+   #######  #     #  #######        #######  #     #  #######  
+   #     #  ##    #  #                 #     #  #  #  #     #  
+   #     #  # #   #  #                 #     #  #  #  #     #  
+   #     #  #  #  #  #####             #     #  #  #  #     #  
+   #     #  #   # #  #                 #     #  #  #  #     #  
+   #     #  #    ##  #                 #     #  #  #  #     #  
+   #######  #     #  #######           #      ## ##   #######  
+
+.SH COMPATIBILITY
+.PP
+From time to time, people assert that this program is buggy because it
+doesn't do something that some other banner implementation does.  The
+behavior of the program is based on what I saw on Solaris and AIX systems
+at the time I wrote it in the late 1990s.  I make no claims that the
+behavior is identical to that of any other contemporary system, especially
+any non-free system that I may or may not have access to. 
+.PP
+If you don't like the behavior, you can either submit a patch, or you can
+use an alternative program such as figlet.  I am always happy to accept
+patches, and I promise to integrate patches promptly if provided.  So far,
+no one who's complained has bothered to provide any patches, so the
+behavior remains the same.
+.SH BUGS
+Report bugs to <support@cedar\-solutions.com>.
+.SH AUTHOR
+Written by Kenneth J. Pronovici <pronovic@ieee.org>.
+.SH COPYRIGHT
+Copyright (c) 2000\-2004.2007,2013,2014 Kenneth J. Pronovici.
+.br
+This is free software; see the source for copying conditions.  There is
+NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE.
diff --git a/upstream/mageia-cauldron/man1/base32.1 b/upstream/mageia-cauldron/man1/base32.1
new file mode 100644
index 00000000..16116844
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/base32.1
@@ -0,0 +1,52 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH BASE32 "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+base32 \- base32 encode/decode data and print to standard output
+.SH SYNOPSIS
+.B base32
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Base32 encode or decode FILE, or standard input, to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-d\fR, \fB\-\-decode\fR
+decode data
+.TP
+\fB\-i\fR, \fB\-\-ignore\-garbage\fR
+when decoding, ignore non\-alphabet characters
+.TP
+\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR
+wrap encoded lines after COLS character (default 76).
+Use 0 to disable line wrapping
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The data are encoded as described for the base32 alphabet in RFC 4648.
+When decoding, the input may contain newlines in addition to the bytes of
+the formal base32 alphabet.  Use \fB\-\-ignore\-garbage\fR to attempt to recover
+from any other non\-alphabet bytes in the encoded stream.
+.SH AUTHOR
+Written by Simon Josefsson.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/base32>
+.br
+or available locally via: info \(aq(coreutils) base32 invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/base64.1 b/upstream/mageia-cauldron/man1/base64.1
new file mode 100644
index 00000000..c759baf5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/base64.1
@@ -0,0 +1,52 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH BASE64 "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+base64 \- base64 encode/decode data and print to standard output
+.SH SYNOPSIS
+.B base64
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Base64 encode or decode FILE, or standard input, to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-d\fR, \fB\-\-decode\fR
+decode data
+.TP
+\fB\-i\fR, \fB\-\-ignore\-garbage\fR
+when decoding, ignore non\-alphabet characters
+.TP
+\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR
+wrap encoded lines after COLS character (default 76).
+Use 0 to disable line wrapping
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The data are encoded as described for the base64 alphabet in RFC 4648.
+When decoding, the input may contain newlines in addition to the bytes of
+the formal base64 alphabet.  Use \fB\-\-ignore\-garbage\fR to attempt to recover
+from any other non\-alphabet bytes in the encoded stream.
+.SH AUTHOR
+Written by Simon Josefsson.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/base64>
+.br
+or available locally via: info \(aq(coreutils) base64 invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/basename.1 b/upstream/mageia-cauldron/man1/basename.1
new file mode 100644
index 00000000..91860a50
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/basename.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH BASENAME "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+basename \- strip directory and suffix from filenames
+.SH SYNOPSIS
+.B basename
+\fI\,NAME \/\fR[\fI\,SUFFIX\/\fR]
+.br
+.B basename
+\fI\,OPTION\/\fR... \fI\,NAME\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print NAME with any leading directory components removed.
+If specified, also remove a trailing SUFFIX.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-multiple\fR
+support multiple arguments and treat each as a NAME
+.TP
+\fB\-s\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+remove a trailing SUFFIX; implies \fB\-a\fR
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH EXAMPLES
+.TP
+basename /usr/bin/sort
+\-> "sort"
+.TP
+basename include/stdio.h .h
+\-> "stdio"
+.TP
+basename \-s .h include/stdio.h
+\-> "stdio"
+.TP
+basename \-a any/str1 any/str2
+\-> "str1" followed by "str2"
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBdirname\fP(1), \fBreadlink\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/basename>
+.br
+or available locally via: info \(aq(coreutils) basename invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/basenc.1 b/upstream/mageia-cauldron/man1/basenc.1
new file mode 100644
index 00000000..4322697c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/basenc.1
@@ -0,0 +1,106 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH BASENC "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+basenc \- Encode/decode data and print to standard output
+.SH SYNOPSIS
+.B basenc
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+basenc encode or decode FILE, or standard input, to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-base64\fR
+same as 'base64' program (RFC4648 section 4)
+.TP
+\fB\-\-base64url\fR
+file\- and url\-safe base64 (RFC4648 section 5)
+.TP
+\fB\-\-base32\fR
+same as 'base32' program (RFC4648 section 6)
+.TP
+\fB\-\-base32hex\fR
+extended hex alphabet base32 (RFC4648 section 7)
+.TP
+\fB\-\-base16\fR
+hex encoding (RFC4648 section 8)
+.TP
+\fB\-\-base2msbf\fR
+bit string with most significant bit (msb) first
+.TP
+\fB\-\-base2lsbf\fR
+bit string with least significant bit (lsb) first
+.TP
+\fB\-d\fR, \fB\-\-decode\fR
+decode data
+.TP
+\fB\-i\fR, \fB\-\-ignore\-garbage\fR
+when decoding, ignore non\-alphabet characters
+.TP
+\fB\-w\fR, \fB\-\-wrap\fR=\fI\,COLS\/\fR
+wrap encoded lines after COLS character (default 76).
+Use 0 to disable line wrapping
+.TP
+\fB\-\-z85\fR
+ascii85\-like encoding (ZeroMQ spec:32/Z85);
+when encoding, input length must be a multiple of 4;
+when decoding, input length must be a multiple of 5
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+When decoding, the input may contain newlines in addition to the bytes of
+the formal alphabet.  Use \fB\-\-ignore\-garbage\fR to attempt to recover
+from any other non\-alphabet bytes in the encoded stream.
+.SH "ENCODINGS EXAMPLES"
+.PP
+.nf
+.RS
+$ printf '\\376\\117\\202' | basenc \-\-base64
+/k+C
+
+$ printf '\\376\\117\\202' | basenc \-\-base64url
+_k-C
+
+$ printf '\\376\\117\\202' | basenc \-\-base32
+7ZHYE===
+
+$ printf '\\376\\117\\202' | basenc \-\-base32hex
+VP7O4===
+
+$ printf '\\376\\117\\202' | basenc \-\-base16
+FE4F82
+
+$ printf '\\376\\117\\202' | basenc \-\-base2lsbf
+011111111111001001000001
+
+$ printf '\\376\\117\\202' | basenc \-\-base2msbf
+111111100100111110000010
+
+$ printf '\\376\\117\\202\\000' | basenc \-\-z85
+@.FaC
+.RE
+.fi
+.SH AUTHOR
+Written by Simon Josefsson and Assaf Gordon.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/basenc>
+.br
+or available locally via: info \(aq(coreutils) basenc invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/bash.1 b/upstream/mageia-cauldron/man1/bash.1
new file mode 100644
index 00000000..55c56220
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bash.1
@@ -0,0 +1,11764 @@
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\"	Chet Ramey
+.\"	Case Western Reserve University
+.\"	chet.ramey@case.edu
+.\"
+.\"	Last Change: Mon Sep 19 11:13:21 EDT 2022
+.\"
+.\" bash_builtins, strip all but Built-Ins section
+.if \n(zZ=1 .ig zZ
+.if \n(zY=1 .ig zY
+.TH BASH 1 "2022 September 19" "GNU Bash 5.2"
+.\"
+.\" There's some problem with having a `@'
+.\" in a tagged paragraph with the BSD man macros.
+.\" It has to do with `@' appearing in the }1 macro.
+.\" This is a problem on 4.3 BSD and Ultrix, but Sun
+.\" appears to have fixed it.
+.\" If you're seeing the characters
+.\" `@u-3p' appearing before the lines reading
+.\" `possible-hostname-completions
+.\" and `complete-hostname' down in READLINE,
+.\" then uncomment this redefinition.
+.\"
+.\" .de }1
+.\" .ds ]X \&\\*(]B\\
+.\" .nr )E 0
+.\" .if !"\\$1"" .nr )I \\$1n
+.\" .}f
+.\" .ll \\n(LLu
+.\" .in \\n()Ru+\\n(INu+\\n()Iu
+.\" .ti \\n(INu
+.\" .ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X
+.\" .br\}
+.\" .el \\*(]X\h|\\n()Iu+\\n()Ru\c
+.\" .}f
+.\" ..
+.\"
+.\" File Name macro.  This used to be `.PN', for Path Name,
+.\" but Sun doesn't seem to like that very much.
+.\"
+.de FN
+\fI\|\\$1\|\fP
+..
+.SH NAME
+bash \- GNU Bourne-Again SHell
+.SH SYNOPSIS
+.B bash
+[options]
+[command_string | file]
+.SH COPYRIGHT
+.if n Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc.
+.if t Bash is Copyright \(co 1989-2022 by the Free Software Foundation, Inc.
+.SH DESCRIPTION
+.B Bash
+is an \fBsh\fR-compatible command language interpreter that
+executes commands read from the standard input or from a file.
+.B Bash
+also incorporates useful features from the \fIKorn\fP and \fIC\fP
+shells (\fBksh\fP and \fBcsh\fP).
+.PP
+.B Bash
+is intended to be a conformant implementation of the
+Shell and Utilities portion of the IEEE POSIX specification
+(IEEE Standard 1003.1).
+.B Bash
+can be configured to be POSIX-conformant by default.
+.SH OPTIONS
+All of the single-character shell options documented in the
+description of the \fBset\fR builtin command, including \fB\-o\fP,
+can be used as options when the shell is invoked.
+In addition, \fBbash\fR
+interprets the following options when it is invoked:
+.PP
+.PD 0
+.TP 10
+.B \-c
+If the
+.B \-c
+option is present, then commands are read from the first non-option argument
+.IR command_string .
+If there are arguments after the
+.IR command_string ,
+the first argument is assigned to
+.B $0
+and any remaining arguments are assigned to the positional parameters.
+The assignment to
+.B $0
+sets the name of the shell, which is used in warning and error messages.
+.TP
+.B \-i
+If the
+.B \-i
+option is present, the shell is
+.IR interactive .
+.TP
+.B \-l
+Make
+.B bash
+act as if it had been invoked as a login shell (see
+.SM
+.B INVOCATION
+below).
+.TP
+.B \-r
+If the
+.B \-r
+option is present, the shell becomes
+.I restricted
+(see
+.SM
+.B "RESTRICTED SHELL"
+below).
+.TP
+.B \-s
+If the
+.B \-s
+option is present, or if no arguments remain after option
+processing, then commands are read from the standard input.
+This option allows the positional parameters to be set
+when invoking an interactive shell or when reading input
+through a pipe.
+.TP
+.B \-D
+A list of all double-quoted strings preceded by \fB$\fP
+is printed on the standard output.
+These are the strings that
+are subject to language translation when the current locale
+is not \fBC\fP or \fBPOSIX\fP.
+This implies the \fB\-n\fP option; no commands will be executed.
+.TP
+.B [\-+]O [\fIshopt_option\fP]
+\fIshopt_option\fP is one of the shell options accepted by the
+\fBshopt\fP builtin (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option;
+\fB+O\fP unsets it.
+If \fIshopt_option\fP is not supplied, the names and values of the shell
+options accepted by \fBshopt\fP are printed on the standard output.
+If the invocation option is \fB+O\fP, the output is displayed in a format
+that may be reused as input.
+.TP
+.B \-\-
+A
+.B \-\-
+signals the end of options and disables further option processing.
+Any arguments after the
+.B \-\-
+are treated as filenames and arguments.  An argument of
+.B \-
+is equivalent to \fB\-\-\fP.
+.PD
+.PP
+.B Bash
+also interprets a number of multi-character options.
+These options must appear on the command line before the
+single-character options to be recognized.
+.PP
+.PD 0
+.TP
+.B \-\-debugger
+Arrange for the debugger profile to be executed before the shell
+starts.
+Turns on extended debugging mode (see the description of the
+.B extdebug
+option to the
+.B shopt
+builtin below).
+.TP
+.B \-\-dump\-po\-strings
+Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP
+\fBpo\fP (portable object) file format.
+.TP
+.B \-\-dump\-strings
+Equivalent to \fB\-D\fP.
+.TP
+.B \-\-help
+Display a usage message on standard output and exit successfully.
+.TP
+\fB\-\-init\-file\fP \fIfile\fP
+.PD 0
+.TP
+\fB\-\-rcfile\fP \fIfile\fP
+.PD
+Execute commands from
+.I file
+instead of the standard personal initialization file
+.I ~/.bashrc
+if the shell is interactive (see
+.SM
+.B INVOCATION
+below).
+.TP
+.B \-\-login
+Equivalent to \fB\-l\fP.
+.TP
+.B \-\-noediting
+Do not use the GNU
+.B readline
+library to read command lines when the shell is interactive.
+.TP
+.B \-\-noprofile
+Do not read either the system-wide startup file
+.FN /etc/profile
+or any of the personal initialization files
+.IR ~/.bash_profile ,
+.IR ~/.bash_login ,
+or
+.IR ~/.profile .
+By default,
+.B bash
+reads these files when it is invoked as a login shell (see
+.SM
+.B INVOCATION
+below).
+.TP
+.B \-\-norc
+Do not read and execute the personal initialization file
+.I ~/.bashrc
+if the shell is interactive.
+This option is on by default if the shell is invoked as
+.BR sh .
+.TP
+.B \-\-posix
+Change the behavior of \fBbash\fP where the default operation differs
+from the POSIX standard to match the standard (\fIposix mode\fP).
+See
+.SM
+.B "SEE ALSO"
+below for a reference to a document that details how posix mode affects
+bash's behavior.
+.TP
+.B \-\-restricted
+The shell becomes restricted (see
+.SM
+.B "RESTRICTED SHELL"
+below).
+.TP
+.B \-\-verbose
+Equivalent to \fB\-v\fP.
+.TP
+.B \-\-version
+Show version information for this instance of
+.B bash
+on the standard output and exit successfully.
+.PD
+.SH ARGUMENTS
+If arguments remain after option processing, and neither the
+.B \-c
+nor the
+.B \-s
+option has been supplied, the first argument is assumed to
+be the name of a file containing shell commands.
+If
+.B bash
+is invoked in this fashion,
+.B $0
+is set to the name of the file, and the positional parameters
+are set to the remaining arguments.
+.B Bash
+reads and executes commands from this file, then exits.
+\fBBash\fP's exit status is the exit status of the last command
+executed in the script.
+If no commands are executed, the exit status is 0.
+An attempt is first made to open the file in the current directory, and,
+if no file is found, then the shell searches the directories in
+.SM
+.B PATH
+for the script.
+.SH INVOCATION
+A \fIlogin shell\fP is one whose first character of argument zero is a
+.BR \- ,
+or one started with the
+.B \-\-login
+option.
+.PP
+An \fIinteractive\fP shell is one started without non-option arguments
+(unless \fB\-s\fP is specified)
+and without the
+.B \-c
+option,
+whose standard input and error are
+both connected to terminals (as determined by
+.IR isatty (3)),
+or one started with the
+.B \-i
+option.
+.SM
+.B PS1
+is set and
+.B $\-
+includes
+.B i
+if
+.B bash
+is interactive,
+allowing a shell script or a startup file to test this state.
+.PP
+The following paragraphs describe how
+.B bash
+executes its startup files.
+If any of the files exist but cannot be read,
+.B bash
+reports an error.
+Tildes are expanded in filenames as described below under
+.B "Tilde Expansion"
+in the
+.SM
+.B EXPANSION
+section.
+.PP
+When
+.B bash
+is invoked as an interactive login shell, or as a non-interactive shell
+with the \fB\-\-login\fP option, it first reads and
+executes commands from the file \fI/etc/profile\fP, if that
+file exists.
+After reading that file, it looks for \fI~/.bash_profile\fP,
+\fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads
+and executes commands from the first one that exists and is readable.
+The
+.B \-\-noprofile
+option may be used when the shell is started to inhibit this behavior.
+.PP
+When an interactive login shell exits,
+or a non-interactive login shell executes the \fBexit\fP builtin command,
+.B bash
+reads and executes commands from the file \fI~/.bash_logout\fP, if it
+exists.
+.PP
+When an interactive shell that is not a login shell is started,
+.B bash
+reads and executes commands from \fI~/.bashrc\fP, if that file exists.
+This may be inhibited by using the
+.B \-\-norc
+option.
+The \fB\-\-rcfile\fP \fIfile\fP option will force
+.B bash
+to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP.
+.PP
+When
+.B bash
+is started non-interactively, to run a shell script, for example, it
+looks for the variable
+.SM
+.B BASH_ENV
+in the environment, expands its value if it appears there, and uses the
+expanded value as the name of a file to read and execute.
+.B Bash
+behaves as if the following command were executed:
+.sp .5
+.RS
+.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
+.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
+.RE
+.sp .5
+but the value of the
+.SM
+.B PATH
+variable is not used to search for the filename.
+.PP
+If
+.B bash
+is invoked with the name
+.BR sh ,
+it tries to mimic the startup behavior of historical versions of
+.B sh
+as closely as possible,
+while conforming to the POSIX standard as well.
+When invoked as an interactive login shell, or a non-interactive
+shell with the \fB\-\-login\fP option, it first attempts to
+read and execute commands from
+.I /etc/profile
+and
+.IR ~/.profile ,
+in that order.
+The
+.B \-\-noprofile
+option may be used to inhibit this behavior.
+When invoked as an interactive shell with the name
+.BR sh ,
+.B bash
+looks for the variable
+.SM
+.BR ENV ,
+expands its value if it is defined, and uses the
+expanded value as the name of a file to read and execute.
+Since a shell invoked as
+.B sh
+does not attempt to read and execute commands from any other startup
+files, the
+.B \-\-rcfile
+option has no effect.
+A non-interactive shell invoked with the name
+.B sh
+does not attempt to read any other startup files.
+When invoked as
+.BR sh ,
+.B bash
+enters
+.I posix
+mode after the startup files are read.
+.PP
+When
+.B bash
+is started in
+.I posix
+mode, as with the
+.B \-\-posix
+command line option, it follows the POSIX standard for startup files.
+In this mode, interactive shells expand the
+.SM
+.B ENV
+variable and commands are read and executed from the file
+whose name is the expanded value.
+No other startup files are read.
+.PP
+.B Bash
+attempts to determine when it is being run with its standard input
+connected to a network connection, as when executed by
+the historical remote shell daemon, usually \fIrshd\fP,
+or the secure shell daemon \fIsshd\fP.
+If
+.B bash
+determines it is being run non-interactively in this fashion,
+it reads and executes commands from \fI~/.bashrc\fP,
+if that file exists and is readable.
+It will not do this if invoked as \fBsh\fP.
+The
+.B \-\-norc
+option may be used to inhibit this behavior, and the
+.B \-\-rcfile
+option may be used to force another file to be read, but neither
+\fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
+or allow them to be specified.
+.PP
+If the shell is started with the effective user (group) id not equal to the
+real user (group) id, and the \fB\-p\fP option is not supplied, no startup
+files are read, shell functions are not inherited from the environment, the
+.SM
+.BR SHELLOPTS ,
+.SM
+.BR BASHOPTS ,
+.SM
+.BR CDPATH ,
+and
+.SM
+.B GLOBIGNORE
+variables, if they appear in the environment, are ignored,
+and the effective user id is set to the real user id.
+If the \fB\-p\fP option is supplied at invocation, the startup behavior is
+the same, but the effective user id is not reset.
+.SH DEFINITIONS
+The following definitions are used throughout the rest of this
+document.
+.PD 0
+.TP
+.B blank
+A space or tab.
+.TP
+.B word
+A sequence of characters considered as a single unit by the shell.
+Also known as a
+.BR token .
+.TP
+.B name
+A
+.I word
+consisting only of alphanumeric characters and underscores, and
+beginning with an alphabetic character or an underscore.  Also
+referred to as an
+.BR identifier .
+.TP
+.B metacharacter
+A character that, when unquoted, separates words.  One of the following:
+.br
+.RS
+.PP
+.if t \fB|  &  ;  (  )  <  >  space  tab  newline\fP
+.if n \fB|  & ; ( ) < > space tab newline\fP
+.RE
+.TP
+.B control operator
+A \fItoken\fP that performs a control function.  It is one of the following
+symbols:
+.RS
+.PP
+.if t \fB||  &  &&  ;  ;;  ;&  ;;&  (  )  |  |&    <newline>\fP
+.if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
+.RE
+.PD
+.SH "RESERVED WORDS"
+\fIReserved words\fP are words that have a special meaning to the shell.
+The following words are recognized as reserved when unquoted and either
+the first word of a command (see
+.SM
+.B SHELL GRAMMAR
+below), the third word of a
+.B case
+or
+.B select
+command
+(only \fBin\fP is valid), or the third word of a
+.B for
+command (only \fBin\fP and \fBdo\fP are valid):
+.if t .RS
+.PP
+.B
+.if n ! case  coproc  do done elif else esac fi for function if in select then until while { } time [[ ]]
+.if t !    case    coproc    do    done    elif    else    esac    fi    for    function    if    in    select    then    until    while    {    }    time    [[    ]]
+.if t .RE
+.SH "SHELL GRAMMAR"
+This section describes the syntax of the various forms of shell commands.
+.SS Simple Commands
+A \fIsimple command\fP is a sequence of optional variable assignments
+followed by \fBblank\fP-separated words and redirections, and
+terminated by a \fIcontrol operator\fP.  The first word
+specifies the command to be executed, and is passed as argument zero.
+The remaining words are passed as arguments to the invoked command.
+.PP
+The return value of a \fIsimple command\fP is its exit status, or
+128+\fIn\^\fP if the command is terminated by signal
+.IR n .
+.SS Pipelines
+A \fIpipeline\fP is a sequence of one or more commands separated by
+one of the control operators
+.B |
+or \fB|&\fP.
+The format for a pipeline is:
+.RS
+.PP
+[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ]
+.RE
+.PP
+The standard output of
+.I command1
+is connected via a pipe to the standard input of
+.IR command2 .
+This connection is performed before any redirections specified by the
+.IR command1 (see
+.SM
+.B REDIRECTION
+below).
+If \fB|&\fP is used, \fIcommand1\fP's standard error, in addition to its
+standard output, is connected to
+\fIcommand2\fP's standard input through the pipe;
+it is shorthand for \fB2>&1 |\fP.
+This implicit redirection of the standard error to the standard output is
+performed after any redirections specified by \fIcommand1\fP.
+.PP
+The return status of a pipeline is the exit status of the last
+command, unless the \fBpipefail\fP option is enabled.
+If \fBpipefail\fP is enabled, the pipeline's return status is the
+value of the last (rightmost) command to exit with a non-zero status,
+or zero if all commands exit successfully.
+If the reserved word
+.B !
+precedes a pipeline, the exit status of that pipeline is the logical
+negation of the exit status as described above.
+The shell waits for all commands in the pipeline to
+terminate before returning a value.
+.PP
+If the
+.B time
+reserved word precedes a pipeline, the elapsed as well as user and
+system time consumed by its execution are reported when the pipeline
+terminates.
+The \fB\-p\fP option changes the output format to that specified by POSIX.
+When the shell is in \fIposix mode\fP, it does not recognize
+\fBtime\fP as a reserved word if the next token begins with a `-'.
+The
+.SM
+.B TIMEFORMAT
+variable may be set to a format string that specifies how the timing
+information should be displayed; see the description of
+.SM
+.B TIMEFORMAT
+under
+.B "Shell Variables"
+below.
+.PP
+When the shell is in \fIposix mode\fP, \fBtime\fP
+may be followed by a newline.  In this case, the shell displays the
+total user and system time consumed by the shell and its children.
+The
+.SM
+.B TIMEFORMAT
+variable may be used to specify the format of
+the time information.
+.PP
+Each command in a multi-command pipeline,
+where pipes are created,
+is executed in a \fIsubshell\fP, which is a
+separate process.
+See
+.SM
+\fBCOMMAND EXECUTION ENVIRONMENT\fP
+for a description of subshells and a subshell environment.
+If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
+(see the description of \fBshopt\fP below),
+the last element of a pipeline may be run by the shell process
+when job control is not active.
+.SS Lists
+A \fIlist\fP is a sequence of one or more pipelines separated by one
+of the operators
+.BR ; ,
+.BR & ,
+.BR && ,
+or
+.BR || ,
+and optionally terminated by one of
+.BR ; ,
+.BR & ,
+or
+.BR <newline> .
+.PP
+Of these list operators,
+.B &&
+and
+.B ||
+have equal precedence, followed by
+.B ;
+and
+.BR & ,
+which have equal precedence.
+.PP
+A sequence of one or more newlines may appear in a \fIlist\fP instead
+of a semicolon to delimit commands.
+.PP
+If a command is terminated by the control operator
+.BR & ,
+the shell executes the command in the \fIbackground\fP
+in a subshell.
+The shell does not wait for the command to
+finish, and the return status is 0.
+These are referred to as \fIasynchronous\fP commands.
+Commands separated by a
+.B ;
+are executed sequentially; the shell waits for each
+command to terminate in turn.  The return status is the
+exit status of the last command executed.
+.PP
+AND and OR lists are sequences of one or more pipelines separated by the
+\fB&&\fP and \fB||\fP control operators, respectively.
+AND and OR lists are executed with left associativity.
+An AND list has the form
+.RS
+.PP
+\fIcommand1\fP \fB&&\fP \fIcommand2\fP
+.RE
+.PP
+.I command2
+is executed if, and only if,
+.I command1
+returns an exit status of zero (success).
+.PP
+An OR list has the form
+.RS
+.PP
+\fIcommand1\fP \fB||\fP \fIcommand2\fP
+.RE
+.PP
+.I command2
+is executed if, and only if,
+.I command1
+returns a non-zero exit status.
+The return status of
+AND and OR lists is the exit status of the last command
+executed in the list.
+.SS Compound Commands
+A \fIcompound command\fP is one of the following.
+In most cases a \fIlist\fP in a command's description may be separated from
+the rest of the command by one or more newlines, and may be followed by a
+newline in place of a semicolon.
+.TP
+(\fIlist\fP)
+\fIlist\fP is executed in a subshell (see
+.SM
+\fBCOMMAND EXECUTION ENVIRONMENT\fP
+below for a description of a subshell environment).
+Variable assignments and builtin
+commands that affect the shell's environment do not remain in effect
+after the command completes.  The return status is the exit status of
+\fIlist\fP.
+.TP
+{ \fIlist\fP; }
+\fIlist\fP is simply executed in the current shell environment.
+\fIlist\fP must be terminated with a newline or semicolon.
+This is known as a \fIgroup command\fP.
+The return status is the exit status of
+\fIlist\fP.
+Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
+\fB}\fP are \fIreserved words\fP and must occur where a reserved
+word is permitted to be recognized.  Since they do not cause a word
+break, they must be separated from \fIlist\fP by whitespace or another
+shell metacharacter.
+.TP
+((\fIexpression\fP))
+The \fIexpression\fP is evaluated according to the rules described
+below under
+.SM
+.BR "ARITHMETIC EVALUATION" .
+If the value of the expression is non-zero, the return status is 0;
+otherwise the return status is 1.
+The \fIexpression\fP
+undergoes the same expansions
+as if it were within double quotes,
+but double quote characters in \fIexpression\fP are not treated specially
+and are removed.
+.TP
+\fB[[\fP \fIexpression\fP \fB]]\fP
+Return a status of 0 or 1 depending on the evaluation of
+the conditional expression \fIexpression\fP.
+Expressions are composed of the primaries described below under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" .
+The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting
+and pathname expansion.
+The shell performs tilde expansion, parameter and
+variable expansion, arithmetic expansion, command substitution, process
+substitution, and quote removal on those words
+(the expansions that would occur if the words were enclosed in double quotes).
+Conditional operators such as \fB\-f\fP must be unquoted to be recognized
+as primaries.
+.if t .sp 0.5
+.if n .sp 1
+When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
+lexicographically using the current locale.
+.if t .sp 0.5
+.if n .sp 1
+When the \fB==\fP and \fB!=\fP operators are used, the string to the
+right of the operator is considered a pattern and matched according
+to the rules described below under \fBPattern Matching\fP,
+as if the \fBextglob\fP shell option were enabled.
+The \fB=\fP operator is equivalent to \fB==\fP.
+If the
+.B nocasematch
+shell option is enabled, the match is performed without regard to the case
+of alphabetic characters.
+The return value is 0 if the string matches (\fB==\fP) or does not match
+(\fB!=\fP) the pattern, and 1 otherwise.
+Any part of the pattern may be quoted to force the quoted portion
+to be matched as a string.
+.if t .sp 0.5
+.if n .sp 1
+An additional binary operator, \fB=~\fP, is available, with the same
+precedence as \fB==\fP and \fB!=\fP.
+When it is used, the string to the right of the operator is considered
+a POSIX extended regular expression and matched accordingly
+(using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces
+usually described in \fIregex\fP(3)).
+The return value is 0 if the string matches
+the pattern, and 1 otherwise.
+If the regular expression is syntactically incorrect, the conditional
+expression's return value is 2.
+If the
+.B nocasematch
+shell option is enabled, the match is performed without regard to the case
+of alphabetic characters.
+If any part of the pattern is quoted, the quoted portion is matched literally.
+This means every character in the quoted portion matches itself,
+instead of having any special pattern matching meaning.
+If the pattern is stored in a shell variable, quoting the variable
+expansion forces the entire pattern to be matched literally.
+Treat bracket expressions in regular expressions carefully,
+since normal quoting and pattern characters lose their meanings
+between brackets.
+.if t .sp 0.5
+.if n .sp 1
+The pattern will match if it matches any part of the string.
+Anchor the pattern using the \fB^\fP and \fB$\fP regular expression
+operators to force it to match the entire string.
+The array variable
+.SM
+.B BASH_REMATCH
+records which parts of the string matched the pattern.
+The element of
+.SM
+.B BASH_REMATCH
+with index 0 contains the portion of
+the string matching the entire regular expression.
+Substrings matched by parenthesized subexpressions within the regular
+expression are saved in the remaining
+.SM
+.B BASH_REMATCH
+indices. The element of
+.SM
+.B BASH_REMATCH
+with index \fIn\fP is the portion of the
+string matching the \fIn\fPth parenthesized subexpression.
+Bash sets
+.SM
+.B BASH_REMATCH
+in the global scope; declaring it as a local variable will lead to
+unexpected results.
+.if t .sp 0.5
+.if n .sp 1
+Expressions may be combined using the following operators, listed
+in decreasing order of precedence:
+.if t .sp 0.5
+.if n .sp 1
+.RS
+.PD 0
+.TP
+.B ( \fIexpression\fP )
+Returns the value of \fIexpression\fP.
+This may be used to override the normal precedence of operators.
+.TP
+.B ! \fIexpression\fP
+True if
+.I expression
+is false.
+.TP
+\fIexpression1\fP \fB&&\fP \fIexpression2\fP
+True if both
+.I expression1
+and
+.I expression2
+are true.
+.TP
+\fIexpression1\fP \fB||\fP \fIexpression2\fP
+True if either
+.I expression1
+or
+.I expression2
+is true.
+.PD
+.LP
+The \fB&&\fP and \fB||\fP
+operators do not evaluate \fIexpression2\fP if the value of
+\fIexpression1\fP is sufficient to determine the return value of
+the entire conditional expression.
+.RE
+.TP
+\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
+The list of words following \fBin\fP is expanded, generating a list
+of items.
+The variable \fIname\fP is set to each element of this list
+in turn, and \fIlist\fP is executed each time.
+If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
+\fIlist\fP once for each positional parameter that is set (see
+.SM
+.B PARAMETERS
+below).
+The return status is the exit status of the last command that executes.
+If the expansion of the items following \fBin\fP results in an empty
+list, no commands are executed, and the return status is 0.
+.TP
+\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP
+First, the arithmetic expression \fIexpr1\fP is evaluated according
+to the rules described below under
+.SM
+.BR "ARITHMETIC EVALUATION" .
+The arithmetic expression \fIexpr2\fP is then evaluated repeatedly
+until it evaluates to zero.
+Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is
+executed and the arithmetic expression \fIexpr3\fP is evaluated.
+If any expression is omitted, it behaves as if it evaluates to 1.
+The return value is the exit status of the last command in \fIlist\fP
+that is executed, or false if any of the expressions is invalid.
+.TP
+\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
+The list of words following \fBin\fP is expanded, generating a list
+of items, and the set of expanded words is printed on the standard
+error, each preceded by a number.  If the \fBin\fP
+\fIword\fP is omitted, the positional parameters are printed (see
+.SM
+.B PARAMETERS
+below).
+.B select
+then displays the
+.SM
+.B PS3
+prompt and reads a line from the standard input.
+If the line consists of a number corresponding to one of
+the displayed words, then the value of
+.I name
+is set to that word.
+If the line is empty, the words and prompt are displayed again.
+If EOF is read, the \fBselect\fP command completes and returns 1.
+Any other value read causes
+.I name
+to be set to null.  The line read is saved in the variable
+.SM
+.BR REPLY .
+The
+.I list
+is executed after each selection until a
+.B break
+command is executed.
+The exit status of
+.B select
+is the exit status of the last command executed in
+.IR list ,
+or zero if no commands were executed.
+.TP
+\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
+... ) \fIlist\fP ;; ] ... \fBesac\fP
+A \fBcase\fP command first expands \fIword\fP, and tries to match
+it against each \fIpattern\fP in turn, using the matching rules
+described under
+.B Pattern Matching
+below.
+The \fIword\fP is expanded using tilde
+expansion, parameter and variable expansion, arithmetic expansion,
+command substitution, process substitution and quote removal.
+Each \fIpattern\fP examined is expanded using tilde
+expansion, parameter and variable expansion, arithmetic expansion,
+command substitution, process substitution, and quote removal.
+If the
+.B nocasematch
+shell option is enabled, the match is performed without regard to the case
+of alphabetic characters.
+When a match is found, the corresponding \fIlist\fP is executed.
+If the \fB;;\fP operator is used, no subsequent matches are attempted after
+the first pattern match.
+Using \fB;&\fP in place of \fB;;\fP causes execution to continue with
+the \fIlist\fP associated with the next set of patterns.
+Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next
+pattern list in the statement, if any, and execute any associated \fIlist\fP
+on a successful match,
+continuing the case statement execution as if the pattern list had not matched.
+The exit status is zero if no
+pattern matches.  Otherwise, it is the exit status of the
+last command executed in \fIlist\fP.
+.TP
+\fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
+[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
+[ \fBelse\fP \fIlist\fP; ] \fBfi\fP
+The
+.B if
+.I list
+is executed.  If its exit status is zero, the
+\fBthen\fP \fIlist\fP is executed.  Otherwise, each \fBelif\fP
+\fIlist\fP is executed in turn, and if its exit status is zero,
+the corresponding \fBthen\fP \fIlist\fP is executed and the
+command completes.  Otherwise, the \fBelse\fP \fIlist\fP is
+executed, if present.  The exit status is the exit status of the
+last command executed, or zero if no condition tested true.
+.TP
+\fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
+.PD 0
+.TP
+\fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
+.PD
+The \fBwhile\fP command continuously executes the list
+\fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
+an exit status of zero.  The \fBuntil\fP command is identical
+to the \fBwhile\fP command, except that the test is negated:
+.I list-2
+is executed as long as the last command in
+.I list-1
+returns a non-zero exit status.
+The exit status of the \fBwhile\fP and \fBuntil\fP commands
+is the exit status
+of the last command executed in \fIlist-2\fP, or zero if
+none was executed.
+.SS Coprocesses
+A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
+word.
+A coprocess is executed asynchronously in a subshell, as if the command
+had been terminated with the \fB&\fP control operator, with a two-way pipe
+established between the executing shell and the coprocess.
+.PP
+The syntax for a coprocess is:
+.RS
+.PP
+\fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP]
+.RE
+.PP
+This creates a coprocess named \fINAME\fP.
+\fIcommand\fP may be either a simple command or a compound
+command (see above).
+\fINAME\fP is a shell variable name.
+If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
+.PP
+The recommended form to use for a coprocess is
+.RS
+.PP
+\fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; }
+.RE
+.PP
+This form is recommended because simple commands result in the coprocess
+always being named \fBCOPROC\fP, and it is simpler to use and more complete
+than the other compound commands.
+.PP
+If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
+word following \fBcoproc\fP determines whether that word is interpreted
+as a variable name: it is interpreted as \fINAME\fP if it is not a
+reserved word that introduces a compound command.
+If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this
+is to avoid confusion between \fINAME\fP and the first word of the simple
+command.
+.PP
+When the coprocess is executed, the shell creates an array variable (see
+.B Arrays
+below) named \fINAME\fP in the context of the executing shell.
+The standard output of
+.I command
+is connected via a pipe to a file descriptor in the executing shell,
+and that file descriptor is assigned to \fINAME\fP[0].
+The standard input of
+.I command
+is connected via a pipe to a file descriptor in the executing shell,
+and that file descriptor is assigned to \fINAME\fP[1].
+This pipe is established before any redirections specified by the
+command (see
+.SM
+.B REDIRECTION
+below).
+The file descriptors can be utilized as arguments to shell commands
+and redirections using standard word expansions.
+Other than those created to execute command and process substitutions,
+the file descriptors are not available in subshells.
+.PP
+The process ID of the shell spawned to execute the coprocess is
+available as the value of the variable \fINAME\fP_PID.
+The \fBwait\fP
+builtin command may be used to wait for the coprocess to terminate.
+.PP
+Since the coprocess is created as an asynchronous command,
+the \fBcoproc\fP command always returns success.
+The return status of a coprocess is the exit status of \fIcommand\fP.
+.SS Shell Function Definitions
+A shell function is an object that is called like a simple command and
+executes a compound command with a new set of positional parameters.
+Shell functions are declared as follows:
+.TP
+\fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP]
+.PD 0
+.TP
+\fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
+.PD
+This defines a function named \fIfname\fP.
+The reserved word \fBfunction\fP is optional.
+If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
+The \fIbody\fP of the function is the compound command
+.I compound\-command
+(see \fBCompound Commands\fP above).
+That command is usually a \fIlist\fP of commands between { and }, but
+may be any command listed under \fBCompound Commands\fP above.
+If the \fBfunction\fP reserved word is used, but the
+parentheses are not supplied, the braces are recommended.
+\fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
+name of a simple command.
+When in \fIposix mode\fP, \fIfname\fP must be a valid shell \fIname\fP
+and may not be the name of one of the
+POSIX \fIspecial builtins\fP.
+In default mode, a function name can be any unquoted shell word that does
+not contain \fB$\fP.
+Any redirections (see
+.SM
+.B REDIRECTION
+below) specified when a function is defined are performed
+when the function is executed.
+The exit status of a function definition is zero unless a syntax error
+occurs or a readonly function with the same name already exists.
+When executed, the exit status of a function is the exit status of the
+last command executed in the body.  (See
+.SM
+.B FUNCTIONS
+below.)
+.SH COMMENTS
+In a non-interactive shell, or an interactive shell in which the
+.B interactive_comments
+option to the
+.B shopt
+builtin is enabled (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below), a word beginning with
+.B #
+causes that word and all remaining characters on that line to
+be ignored.  An interactive shell without the
+.B interactive_comments
+option enabled does not allow comments.  The
+.B interactive_comments
+option is on by default in interactive shells.
+.SH QUOTING
+\fIQuoting\fP is used to remove the special meaning of certain
+characters or words to the shell.  Quoting can be used to
+disable special treatment for special characters, to prevent
+reserved words from being recognized as such, and to prevent
+parameter expansion.
+.PP
+Each of the \fImetacharacters\fP listed above under
+.SM
+.B DEFINITIONS
+has special meaning to the shell and must be quoted if it is to
+represent itself.
+.PP
+When the command history expansion facilities are being used
+(see
+.SM
+.B HISTORY EXPANSION
+below), the
+\fIhistory expansion\fP character, usually \fB!\fP, must be quoted
+to prevent history expansion.
+.PP
+There are three quoting mechanisms: the
+.IR "escape character" ,
+single quotes, and double quotes.
+.PP
+A non-quoted backslash (\fB\e\fP) is the
+.IR "escape character" .
+It preserves the literal value of the next character that follows,
+with the exception of <newline>.  If a \fB\e\fP<newline> pair
+appears, and the backslash is not itself quoted, the \fB\e\fP<newline>
+is treated as a line continuation (that is, it is removed from the
+input stream and effectively ignored).
+.PP
+Enclosing characters in single quotes preserves the literal value
+of each character within the quotes.  A single quote may not occur
+between single quotes, even when preceded by a backslash.
+.PP
+Enclosing characters in double quotes preserves the literal value
+of all characters within the quotes, with the exception of
+.BR $ ,
+.BR \` ,
+.BR \e ,
+and, when history expansion is enabled,
+.BR ! .
+When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning
+within double quotes, even when history expansion is enabled.
+The characters
+.B $
+and
+.B \`
+retain their special meaning within double quotes.  The backslash
+retains its special meaning only when followed by one of the following
+characters:
+.BR $ ,
+.BR \` ,
+\^\fB"\fP\^,
+.BR \e ,
+or
+.BR <newline> .
+A double quote may be quoted within double quotes by preceding it with
+a backslash.
+If enabled, history expansion will be performed unless an
+.B !
+appearing in double quotes is escaped using a backslash.
+The backslash preceding the
+.B !
+is not removed.
+.PP
+The special parameters
+.B *
+and
+.B @
+have special meaning when in double
+quotes (see
+.SM
+.B PARAMETERS
+below).
+.PP
+Character sequences of the form \fB$\fP\(aq\fIstring\fP\(aq are treated
+as a special variant of single quotes.
+The sequence expands to \fIstring\fP, with backslash-escaped characters
+in \fIstring\fP replaced as specified by the ANSI C standard.
+Backslash escape sequences, if present, are decoded as follows:
+.RS
+.PD 0
+.TP
+.B \ea
+alert (bell)
+.TP
+.B \eb
+backspace
+.TP
+.B \ee
+.TP
+.B \eE
+an escape character
+.TP
+.B \ef
+form feed
+.TP
+.B \en
+new line
+.TP
+.B \er
+carriage return
+.TP
+.B \et
+horizontal tab
+.TP
+.B \ev
+vertical tab
+.TP
+.B \e\e
+backslash
+.TP
+.B \e\(aq
+single quote
+.TP
+.B \e\(dq
+double quote
+.TP
+.B \e?
+question mark
+.TP
+.B \e\fInnn\fP
+the eight-bit character whose value is the octal value \fInnn\fP
+(one to three octal digits)
+.TP
+.B \ex\fIHH\fP
+the eight-bit character whose value is the hexadecimal value \fIHH\fP
+(one or two hex digits)
+.TP
+.B \eu\fIHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHH\fP (one to four hex digits)
+.TP
+.B \eU\fIHHHHHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHHHHHH\fP (one to eight hex digits)
+.TP
+.B \ec\fIx\fP
+a control-\fIx\fP character
+.PD
+.RE
+.LP
+The expanded result is single-quoted, as if the dollar sign had
+not been present.
+.PP
+A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq)
+will cause the string to be translated according to the current locale.
+The \fIgettext\fP infrastructure performs the lookup and
+translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP,
+and \fBTEXTDOMAIN\fP shell variables.
+If the current locale is \fBC\fP or \fBPOSIX\fP,
+if there are no translations available,
+or if the string is not translated,
+the dollar sign is ignored.
+This is a form of double quoting, so the string remains double-quoted
+by default, whether or not it is translated and replaced.
+If the \fBnoexpand_translation\fP option is enabled
+using the \fBshopt\fP builtin,
+translated strings are single-quoted instead of double-quoted.
+See the description of
+.B shopt
+below under
+.SM
+.BR SHELL BUILTIN COMMANDS .
+.SH PARAMETERS
+A
+.I parameter
+is an entity that stores values.
+It can be a
+.IR name ,
+a number, or one of the special characters listed below under
+.BR "Special Parameters" .
+A
+.I variable
+is a parameter denoted by a
+.IR name .
+A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
+Attributes are assigned using the
+.B declare
+builtin command (see
+.B declare
+below in
+.SM
+.BR "SHELL BUILTIN COMMANDS" ).
+.PP
+A parameter is set if it has been assigned a value.  The null string is
+a valid value.  Once a variable is set, it may be unset only by using
+the
+.B unset
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.PP
+A
+.I variable
+may be assigned to by a statement of the form
+.RS
+.PP
+\fIname\fP=[\fIvalue\fP]
+.RE
+.PP
+If
+.I value
+is not given, the variable is assigned the null string.  All
+.I values
+undergo tilde expansion, parameter and variable expansion,
+command substitution, arithmetic expansion, and quote
+removal (see
+.SM
+.B EXPANSION
+below).  If the variable has its
+.B integer
+attribute set, then
+.I value
+is evaluated as an arithmetic expression even if the $((...)) expansion is
+not used (see
+.B "Arithmetic Expansion"
+below).
+Word splitting and pathname expansion are not performed.
+Assignment statements may also appear as arguments to the
+.BR alias ,
+.BR declare ,
+.BR typeset ,
+.BR export ,
+.BR readonly ,
+and
+.B local
+builtin commands (\fIdeclaration\fP commands).
+When in \fIposix mode\fP, these builtins may appear in a command after
+one or more instances of the \fBcommand\fP builtin and retain these
+assignment statement properties.
+.PP
+In the context where an assignment statement is assigning a value
+to a shell variable or array index, the += operator can be used to
+append to or add to the variable's previous value.
+This includes arguments to builtin commands such as \fBdeclare\fP that
+accept assignment statements (\fIdeclaration\fP commands).
+When += is applied to a variable for which the \fBinteger\fP attribute has been
+set, \fIvalue\fP is evaluated as an arithmetic expression and added to the
+variable's current value, which is also evaluated.
+When += is applied to an array variable using compound assignment (see
+.B Arrays
+below), the
+variable's value is not unset (as it is when using =), and new values are
+appended to the array beginning at one greater than the array's maximum index
+(for indexed arrays) or added as additional key\-value pairs in an
+associative array.
+When applied to a string-valued variable, \fIvalue\fP is expanded and
+appended to the variable's value.
+.PP
+A variable can be assigned the \fInameref\fP attribute using the
+\fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
+(see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
+to create a \fInameref\fP, or a reference to another variable.
+This allows variables to be manipulated indirectly.
+Whenever the nameref variable is referenced, assigned to, unset, or has
+its attributes modified (other than using or changing the \fInameref\fP
+attribute itself), the
+operation is actually performed on the variable specified by the nameref
+variable's value.
+A nameref is commonly used within shell functions to refer to a variable
+whose name is passed as an argument to the function.
+For instance, if a variable name is passed to a shell function as its first
+argument, running
+.sp .5
+.RS
+.if t \f(CWdeclare -n ref=$1\fP
+.if n declare -n ref=$1
+.RE
+.sp .5
+inside the function creates a nameref variable \fBref\fP whose value is
+the variable name passed as the first argument.
+References and assignments to \fBref\fP, and changes to its attributes,
+are treated as references, assignments, and attribute modifications
+to the variable whose name was passed as \fB$1\fP.
+If the control variable in a \fBfor\fP loop has the nameref attribute,
+the list of words can be a list of shell variables, and a name reference
+will be established for each word in the list, in turn, when the loop is
+executed.
+Array variables cannot be given the \fBnameref\fP attribute.
+However, nameref variables can reference array variables and subscripted
+array variables.
+Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
+Otherwise, if \fBunset\fP is executed with the name of a nameref variable
+as an argument, the variable referenced by the nameref variable will be unset.
+.SS Positional Parameters
+A
+.I positional parameter
+is a parameter denoted by one or more
+digits, other than the single digit 0.  Positional parameters are
+assigned from the shell's arguments when it is invoked,
+and may be reassigned using the
+.B set
+builtin command.  Positional parameters may not be assigned to
+with assignment statements.  The positional parameters are
+temporarily replaced when a shell function is executed (see
+.SM
+.B FUNCTIONS
+below).
+.PP
+When a positional parameter consisting of more than a single
+digit is expanded, it must be enclosed in braces (see
+.SM
+.B EXPANSION
+below).
+.SS Special Parameters
+The shell treats several parameters specially.  These parameters may
+only be referenced; assignment to them is not allowed.
+.PD 0
+.TP
+.B *
+Expands to the positional parameters, starting from one.
+When the expansion is not within double quotes, each positional parameter
+expands to a separate word.
+In contexts where it is performed, those words
+are subject to further word splitting and pathname expansion.
+When the expansion occurs within double quotes, it expands to a single word
+with the value of each parameter separated by the first character of the
+.SM
+.B IFS
+special variable.  That is, "\fB$*\fP" is equivalent
+to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
+.I c
+is the first character of the value of the
+.SM
+.B IFS
+variable.  If
+.SM
+.B IFS
+is unset, the parameters are separated by spaces.
+If
+.SM
+.B IFS
+is null, the parameters are joined without intervening separators.
+.TP
+.B @
+Expands to the positional parameters, starting from one.
+In contexts where word splitting is performed, this expands each
+positional parameter to a separate word; if not within double
+quotes, these words are subject to word splitting.
+In contexts where word splitting is not performed,
+this expands to a single word
+with each positional parameter separated by a space.
+When the
+expansion occurs within double quotes, each parameter expands to a
+separate word.  That is, "\fB$@\fP" is equivalent to
+"\fB$1\fP" "\fB$2\fP" ...
+If the double-quoted expansion occurs within a word, the expansion of
+the first parameter is joined with the beginning part of the original
+word, and the expansion of the last parameter is joined with the last
+part of the original word.
+When there are no positional parameters, "\fB$@\fP" and
+.B $@
+expand to nothing (i.e., they are removed).
+.TP
+.B #
+Expands to the number of positional parameters in decimal.
+.TP
+.B ?
+Expands to the exit status of the most recently executed foreground
+pipeline.
+.TP
+.B \-
+Expands to the current option flags as specified upon invocation,
+by the
+.B set
+builtin command, or those set by the shell itself
+(such as the
+.B \-i
+option).
+.TP
+.B $
+Expands to the process ID of the shell. In a subshell, it
+expands to the process ID of the current shell, not the
+subshell.
+.TP
+.B !
+Expands to the process ID of the job most recently placed into the
+background, whether executed as an asynchronous command or using
+the \fBbg\fP builtin (see
+.SM
+.B "JOB CONTROL"
+below).
+.TP
+.B 0
+Expands to the name of the shell or shell script.  This is set at
+shell initialization.  If
+.B bash
+is invoked with a file of commands,
+.B $0
+is set to the name of that file.  If
+.B bash
+is started with the
+.B \-c
+option, then
+.B $0
+is set to the first argument after the string to be
+executed, if one is present.  Otherwise, it is set
+to the filename used to invoke
+.BR bash ,
+as given by argument zero.
+.PD
+.SS Shell Variables
+The following variables are set by the shell:
+.PP
+.PD 0
+.TP
+.B _
+At shell startup, set to the pathname used to invoke the
+shell or shell script being executed as passed in the environment
+or argument list.
+Subsequently, expands to the last argument to the previous simple
+command executed in the foreground, after expansion.
+Also set to the full pathname used to invoke each command executed
+and placed in the environment exported to that command.
+When checking mail, this parameter holds the name of the mail file
+currently being checked.
+.TP
+.B BASH
+Expands to the full filename used to invoke this instance of
+.BR bash .
+.TP
+.B BASHOPTS
+A colon-separated list of enabled shell options.  Each word in
+the list is a valid argument for the
+.B \-s
+option to the
+.B shopt
+builtin command (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).  The options appearing in
+.SM
+.B BASHOPTS
+are those reported as
+.I on
+by \fBshopt\fP.
+If this variable is in the environment when
+.B bash
+starts up, each shell option in the list will be enabled before
+reading any startup files.
+This variable is read-only.
+.TP
+.B BASHPID
+Expands to the process ID of the current \fBbash\fP process.
+This differs from \fB$$\fP under certain circumstances, such as subshells
+that do not require \fBbash\fP to be re-initialized.
+Assignments to
+.SM
+.B BASHPID
+have no effect.
+If
+.B BASHPID
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_ALIASES
+An associative array variable whose members correspond to the internal
+list of aliases as maintained by the \fBalias\fP builtin.
+Elements added to this array appear in the alias list; however,
+unsetting array elements currently does not cause aliases to be removed
+from the alias list.
+If
+.B BASH_ALIASES
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_ARGC
+An array variable whose values are the number of parameters in each
+frame of the current \fBbash\fP execution call stack.
+The number of
+parameters to the current subroutine (shell function or script executed
+with \fB.\fP or \fBsource\fP) is at the top of the stack.
+When a subroutine is executed, the number of parameters passed is pushed onto
+.SM
+.BR BASH_ARGC .
+The shell sets
+.SM
+.B BASH_ARGC
+only when in extended debugging mode (see the description of the
+.B extdebug
+option to the
+.B shopt
+builtin below).
+Setting \fBextdebug\fP after the shell has started to execute a script,
+or referencing this variable when \fBextdebug\fP is not set,
+may result in inconsistent values.
+.TP
+.B BASH_ARGV
+An array variable containing all of the parameters in the current \fBbash\fP
+execution call stack.  The final parameter of the last subroutine call
+is at the top of the stack; the first parameter of the initial call is
+at the bottom.  When a subroutine is executed, the parameters supplied
+are pushed onto
+.SM
+.BR BASH_ARGV .
+The shell sets
+.SM
+.B BASH_ARGV
+only when in extended debugging mode
+(see the description of the
+.B extdebug
+option to the
+.B shopt
+builtin below).
+Setting \fBextdebug\fP after the shell has started to execute a script,
+or referencing this variable when \fBextdebug\fP is not set,
+may result in inconsistent values.
+.TP
+.B BASH_ARGV0
+When referenced, this variable expands to the name of the shell or shell
+script (identical to
+.BR $0 ;
+see the description of special parameter 0 above).
+Assignment to
+.B BASH_ARGV0
+causes the value assigned to also be assigned to \fB$0\fP.
+If
+.B BASH_ARGV0
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_CMDS
+An associative array variable whose members correspond to the internal
+hash table of commands as maintained by the \fBhash\fP builtin.
+Elements added to this array appear in the hash table; however,
+unsetting array elements currently does not cause command names to be removed
+from the hash table.
+If
+.B BASH_CMDS
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_COMMAND
+The command currently being executed or about to be executed, unless the
+shell is executing a command as the result of a trap,
+in which case it is the command executing at the time of the trap.
+If
+.B BASH_COMMAND
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_EXECUTION_STRING
+The command argument to the \fB\-c\fP invocation option.
+.TP
+.B BASH_LINENO
+An array variable whose members are the line numbers in source files
+where each corresponding member of
+.SM
+.B FUNCNAME
+was invoked.
+\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
+file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where
+\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called
+(or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another
+shell function).
+Use
+.SM
+.B LINENO
+to obtain the current line number.
+.TP
+.B BASH_LOADABLES_PATH
+A colon-separated list of directories in which the shell looks for
+dynamically loadable builtins specified by the
+.B enable
+command.
+.TP
+.B BASH_REMATCH
+An array variable whose members are assigned by the \fB=~\fP binary
+operator to the \fB[[\fP conditional command.
+The element with index 0 is the portion of the string
+matching the entire regular expression.
+The element with index \fIn\fP is the portion of the
+string matching the \fIn\fPth parenthesized subexpression.
+.TP
+.B BASH_SOURCE
+An array variable whose members are the source filenames
+where the corresponding shell function names in the
+.SM
+.B FUNCNAME
+array variable are defined.
+The shell function
+\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
+\fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
+\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
+.TP
+.B BASH_SUBSHELL
+Incremented by one within each subshell or subshell environment when
+the shell begins executing in that environment.
+The initial value is 0.
+If
+.B BASH_SUBSHELL
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B BASH_VERSINFO
+A readonly array variable whose members hold version information for
+this instance of
+.BR bash .
+The values assigned to the array members are as follows:
+.sp .5
+.RS
+.TP 24
+.B BASH_VERSINFO[\fR0\fP]
+The major version number (the \fIrelease\fP).
+.TP
+.B BASH_VERSINFO[\fR1\fP]
+The minor version number (the \fIversion\fP).
+.TP
+.B BASH_VERSINFO[\fR2\fP]
+The patch level.
+.TP
+.B BASH_VERSINFO[\fR3\fP]
+The build version.
+.TP
+.B BASH_VERSINFO[\fR4\fP]
+The release status (e.g., \fIbeta1\fP).
+.TP
+.B BASH_VERSINFO[\fR5\fP]
+The value of
+.SM
+.BR MACHTYPE .
+.RE
+.TP
+.B BASH_VERSION
+Expands to a string describing the version of this instance of
+.BR bash .
+.TP
+.B COMP_CWORD
+An index into \fB${COMP_WORDS}\fP of the word containing the current
+cursor position.
+This variable is available only in shell functions invoked by the
+programmable completion facilities (see \fBProgrammable Completion\fP
+below).
+.TP
+.B COMP_KEY
+The key (or final key of a key sequence) used to invoke the current
+completion function.
+.TP
+.B COMP_LINE
+The current command line.
+This variable is available only in shell functions and external
+commands invoked by the
+programmable completion facilities (see \fBProgrammable Completion\fP
+below).
+.TP
+.B COMP_POINT
+The index of the current cursor position relative to the beginning of
+the current command.
+If the current cursor position is at the end of the current command,
+the value of this variable is equal to \fB${#COMP_LINE}\fP.
+This variable is available only in shell functions and external
+commands invoked by the
+programmable completion facilities (see \fBProgrammable Completion\fP
+below).
+.TP
+.B COMP_TYPE
+Set to an integer value corresponding to the type of completion attempted
+that caused a completion function to be called:
+\fITAB\fP, for normal completion,
+\fI?\fP, for listing completions after successive tabs,
+\fI!\fP, for listing alternatives on partial word completion,
+\fI@\fP, to list completions if the word is not unmodified,
+or
+\fI%\fP, for menu completion.
+This variable is available only in shell functions and external
+commands invoked by the
+programmable completion facilities (see \fBProgrammable Completion\fP
+below).
+.TP
+.B COMP_WORDBREAKS
+The set of characters that the \fBreadline\fP library treats as word
+separators when performing word completion.
+If
+.SM
+.B COMP_WORDBREAKS
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B COMP_WORDS
+An array variable (see \fBArrays\fP below) consisting of the individual
+words in the current command line.
+The line is split into words as \fBreadline\fP would split it, using
+.SM
+.B COMP_WORDBREAKS
+as described above.
+This variable is available only in shell functions invoked by the
+programmable completion facilities (see \fBProgrammable Completion\fP
+below).
+.TP
+.B COPROC
+An array variable (see \fBArrays\fP below) created to hold the file descriptors
+for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
+above).
+.TP
+.B DIRSTACK
+An array variable (see
+.B Arrays
+below) containing the current contents of the directory stack.
+Directories appear in the stack in the order they are displayed by the
+.B dirs
+builtin.
+Assigning to members of this array variable may be used to modify
+directories already in the stack, but the
+.B pushd
+and
+.B popd
+builtins must be used to add and remove directories.
+Assignment to this variable will not change the current directory.
+If
+.SM
+.B DIRSTACK
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B EPOCHREALTIME
+Each time this parameter is referenced, it expands to the number of seconds
+since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value
+with micro-second granularity.
+Assignments to
+.SM
+.B EPOCHREALTIME
+are ignored.
+If
+.SM
+.B EPOCHREALTIME
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B EPOCHSECONDS
+Each time this parameter is referenced, it expands to the number of seconds
+since the Unix Epoch (see \fItime\fP\fR(3)\fP).
+Assignments to
+.SM
+.B EPOCHSECONDS
+are ignored.
+If
+.SM
+.B EPOCHSECONDS
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B EUID
+Expands to the effective user ID of the current user, initialized at
+shell startup.  This variable is readonly.
+.TP
+.B FUNCNAME
+An array variable containing the names of all shell functions
+currently in the execution call stack.
+The element with index 0 is the name of any currently-executing
+shell function.
+The bottom-most element (the one with the highest index) is
+.if t \f(CW"main"\fP.
+.if n "main".
+This variable exists only when a shell function is executing.
+Assignments to
+.SM
+.B FUNCNAME
+have no effect.
+If
+.SM
+.B FUNCNAME
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.if t .sp 0.5
+.if n .sp 1
+This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP.
+Each element of \fBFUNCNAME\fP has corresponding elements in
+\fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack.
+For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file
+\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number
+\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
+The \fBcaller\fP builtin displays the current call stack using this
+information.
+.TP
+.B GROUPS
+An array variable containing the list of groups of which the current
+user is a member.
+Assignments to
+.SM
+.B GROUPS
+have no effect.
+If
+.SM
+.B GROUPS
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B HISTCMD
+The history number, or index in the history list, of the current
+command.
+Assignments to
+.SM
+.B HISTCMD
+are ignored.
+If
+.SM
+.B HISTCMD
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B HOSTNAME
+Automatically set to the name of the current host.
+.TP
+.B HOSTTYPE
+Automatically set to a string that uniquely
+describes the type of machine on which
+.B bash
+is executing.
+The default is system-dependent.
+.TP
+.B LINENO
+Each time this parameter is referenced, the shell substitutes
+a decimal number representing the current sequential line number
+(starting with 1) within a script or function.  When not in a
+script or function, the value substituted is not guaranteed to
+be meaningful.
+If
+.SM
+.B LINENO
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B MACHTYPE
+Automatically set to a string that fully describes the system
+type on which
+.B bash
+is executing, in the standard GNU \fIcpu-company-system\fP format.
+The default is system-dependent.
+.TP
+.B MAPFILE
+An array variable (see \fBArrays\fP below) created to hold the text
+read by the \fBmapfile\fP builtin when no variable name is supplied.
+.TP
+.B OLDPWD
+The previous working directory as set by the
+.B cd
+command.
+.TP
+.B OPTARG
+The value of the last option argument processed by the
+.B getopts
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.TP
+.B OPTIND
+The index of the next argument to be processed by the
+.B getopts
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.TP
+.B OSTYPE
+Automatically set to a string that
+describes the operating system on which
+.B bash
+is executing.
+The default is system-dependent.
+.TP
+.B PIPESTATUS
+An array variable (see
+.B Arrays
+below) containing a list of exit status values from the processes
+in the most-recently-executed foreground pipeline (which may
+contain only a single command).
+.TP
+.B PPID
+The process ID of the shell's parent.  This variable is readonly.
+.TP
+.B PWD
+The current working directory as set by the
+.B cd
+command.
+.TP
+.B RANDOM
+Each time this parameter is referenced, it expands to a random integer
+between 0 and 32767.
+Assigning
+a value to
+.SM
+.BR RANDOM
+initializes (seeds) the sequence of random numbers.
+If
+.SM
+.B RANDOM
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B READLINE_ARGUMENT
+Any numeric argument given to a readline command that was defined using
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below)
+when it was invoked.
+.TP
+.B READLINE_LINE
+The contents of the
+.B readline
+line buffer, for use with
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+.TP
+.B READLINE_MARK
+The position of the mark (saved insertion point) in the
+.B readline
+line buffer, for use with
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+The characters between the insertion point and the mark are often
+called the \fIregion\fP.
+.TP
+.B READLINE_POINT
+The position of the insertion point in the
+.B readline
+line buffer, for use with
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+.TP
+.B REPLY
+Set to the line of input read by the
+.B read
+builtin command when no arguments are supplied.
+.TP
+.B SECONDS
+Each time this parameter is
+referenced, it expands to the number of seconds since shell invocation.
+If a value is assigned to
+.SM
+.BR SECONDS ,
+the value returned upon subsequent
+references is
+the number of seconds since the assignment plus the value assigned.
+The number of seconds at shell invocation and the current time are always
+determined by querying the system clock.
+If
+.SM
+.B SECONDS
+is unset, it loses its special properties, even if it is
+subsequently reset.
+.TP
+.B SHELLOPTS
+A colon-separated list of enabled shell options.  Each word in
+the list is a valid argument for the
+.B \-o
+option to the
+.B set
+builtin command (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).  The options appearing in
+.SM
+.B SHELLOPTS
+are those reported as
+.I on
+by \fBset \-o\fP.
+If this variable is in the environment when
+.B bash
+starts up, each shell option in the list will be enabled before
+reading any startup files.
+This variable is read-only.
+.TP
+.B SHLVL
+Incremented by one each time an instance of
+.B bash
+is started.
+.TP
+.B SRANDOM
+This variable expands to a 32-bit pseudo-random number each time it is
+referenced. The random number generator is not linear on systems that
+support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number
+has no relationship to the numbers preceding it.
+The random number generator cannot be seeded, so assignments to this
+variable have no effect.
+If
+.SM
+.B SRANDOM
+is unset, it loses its special properties,
+even if it is subsequently reset.
+.TP
+.B UID
+Expands to the user ID of the current user, initialized at shell startup.
+This variable is readonly.
+.PD
+.PP
+The following variables are used by the shell.  In some cases,
+.B bash
+assigns a default value to a variable; these cases are noted
+below.
+.PP
+.PD 0
+.TP
+.B BASH_COMPAT
+The value is used to set the shell's compatibility level.
+See
+.SM
+.B "SHELL COMPATIBILITY MODE"
+below for a description of the various compatibility
+levels and their effects.
+The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
+corresponding to the desired compatibility level.
+If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility
+level is set to the default for the current version.
+If \fBBASH_COMPAT\fP is set to a value that is not one of the valid
+compatibility levels, the shell prints an error message and sets the
+compatibility level to the default for the current version.
+The valid values correspond to the compatibility levels
+described below under
+.SM
+.BR "SHELL COMPATIBILITY MODE" .
+For example, 4.2 and 42 are valid values that correspond
+to the \fBcompat42\fP \fBshopt\fP option
+and set the compatibility level to 42.
+The current version is also a valid value.
+.TP
+.B BASH_ENV
+If this parameter is set when \fBbash\fP is executing a shell script,
+its value is interpreted as a filename containing commands to
+initialize the shell, as in
+.IR ~/.bashrc .
+The value of
+.SM
+.B BASH_ENV
+is subjected to parameter expansion, command substitution, and arithmetic
+expansion before being interpreted as a filename.
+.SM
+.B PATH
+is not used to search for the resultant filename.
+.TP
+.B BASH_XTRACEFD
+If set to an integer corresponding to a valid file descriptor, \fBbash\fP
+will write the trace output generated when
+.if t \f(CWset -x\fP
+.if n \fIset -x\fP
+is enabled to that file descriptor.
+The file descriptor is closed when
+.SM
+.B BASH_XTRACEFD
+is unset or assigned a new value.
+Unsetting
+.SM
+.B BASH_XTRACEFD
+or assigning it the empty string causes the
+trace output to be sent to the standard error.
+Note that setting
+.SM
+.B BASH_XTRACEFD
+to 2 (the standard error file
+descriptor) and then unsetting it will result in the standard error
+being closed.
+.TP
+.B CDPATH
+The search path for the
+.B cd
+command.
+This is a colon-separated list of directories in which the shell looks
+for destination directories specified by the
+.B cd
+command.
+A sample value is
+.if t \f(CW".:~:/usr"\fP.
+.if n ".:~:/usr".
+.TP
+.B CHILD_MAX
+Set the number of exited child status values for the shell to remember.
+Bash will not allow this value to be decreased below a POSIX-mandated
+minimum, and there is a maximum value (currently 8192) that this may
+not exceed.
+The minimum value is system-dependent.
+.TP
+.B COLUMNS
+Used by the \fBselect\fP compound command to determine the terminal width
+when printing selection lists.
+Automatically set if the
+.B checkwinsize
+option is enabled or in an interactive shell upon receipt of a
+.SM
+.BR SIGWINCH .
+.TP
+.B COMPREPLY
+An array variable from which \fBbash\fP reads the possible completions
+generated by a shell function invoked by the programmable completion
+facility (see \fBProgrammable Completion\fP below).
+Each array element contains one possible completion.
+.TP
+.B EMACS
+If \fBbash\fP finds this variable in the environment when the shell starts
+with value
+.if t \f(CWt\fP,
+.if n "t",
+it assumes that the shell is running in an Emacs shell buffer and disables
+line editing.
+.TP
+.B ENV
+Expanded and executed similarly to
+.SM
+.B BASH_ENV
+(see \fBINVOCATION\fP above)
+when an interactive shell is invoked in \fIposix mode\fP.
+.TP
+.B EXECIGNORE
+A colon-separated list of shell patterns (see \fBPattern Matching\fP)
+defining the list of filenames to be ignored by command search using
+\fBPATH\fP.
+Files whose full pathnames match one of these patterns are not considered
+executable files for the purposes of completion and command execution
+via \fBPATH\fP lookup.
+This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP
+commands.
+Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP.
+Use this variable to ignore shared library files that have the executable
+bit set, but are not executable files.
+The pattern matching honors the setting of the \fBextglob\fP shell
+option.
+.TP
+.B FCEDIT
+The default editor for the
+.B fc
+builtin command.
+.TP
+.B FIGNORE
+A colon-separated list of suffixes to ignore when performing
+filename completion (see
+.SM
+.B READLINE
+below).
+A filename whose suffix matches one of the entries in
+.SM
+.B FIGNORE
+is excluded from the list of matched filenames.
+A sample value is
+.if t \f(CW".o:~"\fP.
+.if n ".o:~".
+.TP
+.B FUNCNEST
+If set to a numeric value greater than 0, defines a maximum function
+nesting level.  Function invocations that exceed this nesting level
+will cause the current command to abort.
+.TP
+.B GLOBIGNORE
+A colon-separated list of patterns defining the set of file names to
+be ignored by pathname expansion.
+If a file name matched by a pathname expansion pattern also matches one
+of the patterns in
+.SM
+.BR GLOBIGNORE ,
+it is removed from the list of matches.
+.TP
+.B HISTCONTROL
+A colon-separated list of values controlling how commands are saved on
+the history list.
+If the list of values includes
+.IR ignorespace ,
+lines which begin with a
+.B space
+character are not saved in the history list.
+A value of
+.I ignoredups
+causes lines matching the previous history entry to not be saved.
+A value of
+.I ignoreboth
+is shorthand for \fIignorespace\fP and \fIignoredups\fP.
+A value of
+.I erasedups
+causes all previous lines matching the current line to be removed from
+the history list before that line is saved.
+Any value not in the above list is ignored.
+If
+.SM
+.B HISTCONTROL
+is unset, or does not include a valid value,
+all lines read by the shell parser are saved on the history list,
+subject to the value of
+.SM
+.BR HISTIGNORE .
+The second and subsequent lines of a multi-line compound command are
+not tested, and are added to the history regardless of the value of
+.SM
+.BR HISTCONTROL .
+.TP
+.B HISTFILE
+The name of the file in which command history is saved (see
+.SM
+.B HISTORY
+below).  The default value is \fI~/.bash_history\fP.  If unset, the
+command history is not saved when a shell exits.
+.TP
+.B HISTFILESIZE
+The maximum number of lines contained in the history file.  When this
+variable is assigned a value, the history file is truncated, if
+necessary,
+to contain no more than that number of lines by removing the oldest entries.
+The history file is also truncated to this size after
+writing it when a shell exits.
+If the value is 0, the history file is truncated to zero size.
+Non-numeric values and numeric values less than zero inhibit truncation.
+The shell sets the default value to the value of \fBHISTSIZE\fP
+after reading any startup files.
+.TP
+.B HISTIGNORE
+A colon-separated list of patterns used to decide which command lines
+should be saved on the history list.  Each pattern is anchored at the
+beginning of the line and must match the complete line (no implicit
+`\fB*\fP' is appended).  Each pattern is tested against the line
+after the checks specified by
+.SM
+.B HISTCONTROL
+are applied.
+In addition to the normal shell pattern matching characters, `\fB&\fP'
+matches the previous history line.  `\fB&\fP' may be escaped using a
+backslash; the backslash is removed before attempting a match.
+The second and subsequent lines of a multi-line compound command are
+not tested, and are added to the history regardless of the value of
+.SM
+.BR HISTIGNORE .
+The pattern matching honors the setting of the \fBextglob\fP shell
+option.
+.TP
+.B HISTSIZE
+The number of commands to remember in the command history (see
+.SM
+.B HISTORY
+below).
+If the value is 0, commands are not saved in the history list.
+Numeric values less than zero result in every command being saved
+on the history list (there is no limit).
+The shell sets the default value to 500 after reading any startup files.
+.TP
+.B HISTTIMEFORMAT
+If this variable is set and not null, its value is used as a format string
+for \fIstrftime\fP(3) to print the time stamp associated with each history
+entry displayed by the \fBhistory\fP builtin.
+If this variable is set, time stamps are written to the history file so
+they may be preserved across shell sessions.
+This uses the history comment character to distinguish timestamps from
+other history lines.
+.TP
+.B HOME
+The home directory of the current user; the default argument for the
+\fBcd\fP builtin command.
+The value of this variable is also used when performing tilde expansion.
+.TP
+.B HOSTFILE
+Contains the name of a file in the same format as
+.FN /etc/hosts
+that should be read when the shell needs to complete a
+hostname.
+The list of possible hostname completions may be changed while the
+shell is running;
+the next time hostname completion is attempted after the
+value is changed,
+.B bash
+adds the contents of the new file to the existing list.
+If
+.SM
+.B HOSTFILE
+is set, but has no value, or does not name a readable file,
+\fBbash\fP attempts to read
+.FN /etc/hosts
+to obtain the list of possible hostname completions.
+When
+.SM
+.B HOSTFILE
+is unset, the hostname list is cleared.
+.TP
+.B IFS
+The
+.I Internal Field Separator
+that is used
+for word splitting after expansion and to
+split lines into words with the
+.B read
+builtin command.  The default value is
+``<space><tab><newline>''.
+.TP
+.B IGNOREEOF
+Controls the
+action of an interactive shell on receipt of an
+.SM
+.B EOF
+character as the sole input.  If set, the value is the number of
+consecutive
+.SM
+.B EOF
+characters which must be
+typed as the first characters on an input line before
+.B bash
+exits.  If the variable exists but does not have a numeric value, or
+has no value, the default value is 10.  If it does not exist,
+.SM
+.B EOF
+signifies the end of input to the shell.
+.TP
+.B INPUTRC
+The filename for the
+.B readline
+startup file, overriding the default of
+.FN ~/.inputrc
+(see
+.SM
+.B READLINE
+below).
+.TP
+.B INSIDE_EMACS
+If this variable appears in the environment when the shell starts,
+\fBbash\fP assumes that it is running inside an Emacs shell buffer
+and may disable line editing, depending on the value of \fBTERM\fP.
+.TP
+.B LANG
+Used to determine the locale category for any category not specifically
+selected with a variable starting with \fBLC_\fP.
+.TP
+.B LC_ALL
+This variable overrides the value of
+.SM
+.B LANG
+and any other
+\fBLC_\fP variable specifying a locale category.
+.TP
+.B LC_COLLATE
+This variable determines the collation order used when sorting the
+results of pathname expansion, and determines the behavior of range
+expressions, equivalence classes, and collating sequences within
+pathname expansion and pattern matching.
+.TP
+.B LC_CTYPE
+This variable determines the interpretation of characters and the
+behavior of character classes within pathname expansion and pattern
+matching.
+.TP
+.B LC_MESSAGES
+This variable determines the locale used to translate double-quoted
+strings preceded by a \fB$\fP.
+.TP
+.B LC_NUMERIC
+This variable determines the locale category used for number formatting.
+.TP
+.B LC_TIME
+This variable determines the locale category used for data and time
+formatting.
+.TP
+.B LINES
+Used by the \fBselect\fP compound command to determine the column length
+for printing selection lists.
+Automatically set if the
+.B checkwinsize
+option is enabled or in an interactive shell upon receipt of a
+.SM
+.BR SIGWINCH .
+.TP
+.B MAIL
+If this parameter is set to a file or directory name and the
+.SM
+.B MAILPATH
+variable is not set,
+.B bash
+informs the user of the arrival of mail in the specified file or
+Maildir-format directory.
+.TP
+.B MAILCHECK
+Specifies how
+often (in seconds)
+.B bash
+checks for mail.  The default is 60 seconds.  When it is time to check
+for mail, the shell does so before displaying the primary prompt.
+If this variable is unset, or set to a value that is not a number
+greater than or equal to zero, the shell disables mail checking.
+.TP
+.B MAILPATH
+A colon-separated list of filenames to be checked for mail.
+The message to be printed when mail arrives in a particular file
+may be specified by separating the filename from the message with a `?'.
+When used in the text of the message, \fB$_\fP expands to the name of
+the current mailfile.
+Example:
+.RS
+.PP
+\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq
+.PP
+.B Bash
+can be configured to supply
+a default value for this variable (there is no value by default),
+but the location of the user
+mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
+.RE
+.TP
+.B OPTERR
+If set to the value 1,
+.B bash
+displays error messages generated by the
+.B getopts
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.SM
+.B OPTERR
+is initialized to 1 each time the shell is invoked or a shell
+script is executed.
+.TP
+.B PATH
+The search path for commands.  It
+is a colon-separated list of directories in which
+the shell looks for commands (see
+.SM
+.B COMMAND EXECUTION
+below).
+A zero-length (null) directory name in the value of
+.SM
+.B PATH
+indicates the current directory.
+A null directory name may appear as two adjacent colons, or as an initial
+or trailing colon.
+The default path is system-dependent,
+and is set by the administrator who installs
+.BR bash .
+A common value is
+.na
+.if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP.
+.if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
+.ad
+.TP
+.B POSIXLY_CORRECT
+If this variable is in the environment when \fBbash\fP starts, the shell
+enters \fIposix mode\fP before reading the startup files, as if the
+.B \-\-posix
+invocation option had been supplied.  If it is set while the shell is
+running, \fBbash\fP enables \fIposix mode\fP, as if the command
+.if t \f(CWset -o posix\fP
+.if n \fIset -o posix\fP
+had been executed.
+When the shell enters \fIposix mode\fP, it sets this variable if it was
+not already set.
+.TP
+.B PROMPT_COMMAND
+If this variable is set, and is an array,
+the value of each set element is executed as a command
+prior to issuing each primary prompt.
+If this is set but not an array variable, 
+its value is used as a command to execute instead.
+.TP
+.B PROMPT_DIRTRIM
+If set to a number greater than zero, the value is used as the number of
+trailing directory components to retain when expanding the \fB\ew\fP and
+\fB\eW\fP prompt string escapes (see
+.SM
+.B PROMPTING
+below).  Characters removed are replaced with an ellipsis.
+.TP
+.B PS0
+The value of this parameter is expanded (see
+.SM
+.B PROMPTING
+below) and displayed by interactive shells after reading a command
+and before the command is executed.
+.TP
+.B PS1
+The value of this parameter is expanded (see
+.SM
+.B PROMPTING
+below) and used as the primary prompt string.  The default value is
+``\fB\es\-\ev\e$ \fP''.
+.TP
+.B PS2
+The value of this parameter is expanded as with
+.SM
+.B PS1
+and used as the secondary prompt string.  The default is
+``\fB> \fP''.
+.TP
+.B PS3
+The value of this parameter is used as the prompt for the
+.B select
+command (see
+.SM
+.B SHELL GRAMMAR
+above).
+.TP
+.B PS4
+The value of this parameter is expanded as with
+.SM
+.B PS1
+and the value is printed before each command
+.B bash
+displays during an execution trace.  The first character of
+the expanded value of
+.SM
+.B PS4
+is replicated multiple times, as necessary, to indicate multiple
+levels of indirection.  The default is ``\fB+ \fP''.
+.TP
+.B SHELL
+This variable expands to the full pathname to the shell.
+If it is not set when the shell starts,
+.B bash
+assigns to it the full pathname of the current user's login shell.
+.TP
+.B TIMEFORMAT
+The value of this parameter is used as a format string specifying
+how the timing information for pipelines prefixed with the
+.B time
+reserved word should be displayed.
+The \fB%\fP character introduces an escape sequence that is
+expanded to a time value or other information.
+The escape sequences and their meanings are as follows; the
+braces denote optional portions.
+.sp .5
+.RS
+.PD 0
+.TP 10
+.B %%
+A literal \fB%\fP.
+.TP
+.B %[\fIp\fP][l]R
+The elapsed time in seconds.
+.TP
+.B %[\fIp\fP][l]U
+The number of CPU seconds spent in user mode.
+.TP
+.B %[\fIp\fP][l]S
+The number of CPU seconds spent in system mode.
+.TP
+.B %P
+The CPU percentage, computed as (%U + %S) / %R.
+.PD
+.RE
+.IP
+The optional \fIp\fP is a digit specifying the \fIprecision\fP,
+the number of fractional digits after a decimal point.
+A value of 0 causes no decimal point or fraction to be output.
+At most three places after the decimal point may be specified;
+values of \fIp\fP greater than 3 are changed to 3.
+If \fIp\fP is not specified, the value 3 is used.
+.IP
+The optional \fBl\fP specifies a longer format, including
+minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
+The value of \fIp\fP determines whether or not the fraction is
+included.
+.IP
+If this variable is not set, \fBbash\fP acts as if it had the
+value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP.
+If the value is null, no timing information is displayed.
+A trailing newline is added when the format string is displayed.
+.PD 0
+.TP
+.B TMOUT
+If set to a value greater than zero,
+.SM
+.B TMOUT
+is treated as the
+default timeout for the \fBread\fP builtin.
+The \fBselect\fP command terminates if input does not arrive
+after
+.SM
+.B TMOUT
+seconds when input is coming from a terminal.
+In an interactive shell, the value is interpreted as the
+number of seconds to wait for a line of input after issuing the
+primary prompt.
+.B Bash
+terminates after waiting for that number of seconds if a complete
+line of input does not arrive.
+.TP
+.B TMPDIR
+If set, \fBbash\fP uses its value as the name of a directory in which
+\fBbash\fP creates temporary files for the shell's use.
+.TP
+.B auto_resume
+This variable controls how the shell interacts with the user and
+job control.  If this variable is set, single word simple
+commands without redirections are treated as candidates for resumption
+of an existing stopped job.  There is no ambiguity allowed; if there is
+more than one job beginning with the string typed, the job most recently
+accessed is selected.  The
+.I name
+of a stopped job, in this context, is the command line used to
+start it.
+If set to the value
+.IR exact ,
+the string supplied must match the name of a stopped job exactly;
+if set to
+.IR substring ,
+the string supplied needs to match a substring of the name of a
+stopped job.  The
+.I substring
+value provides functionality analogous to the
+.B %?
+job identifier (see
+.SM
+.B JOB CONTROL
+below).  If set to any other value, the supplied string must
+be a prefix of a stopped job's name; this provides functionality
+analogous to the \fB%\fP\fIstring\fP job identifier.
+.TP
+.B histchars
+The two or three characters which control history expansion
+and tokenization (see
+.SM
+.B HISTORY EXPANSION
+below).  The first character is the \fIhistory expansion\fP character,
+the character which signals the start of a history
+expansion, normally `\fB!\fP'.
+The second character is the \fIquick substitution\fP
+character, which is used as shorthand for re-running the previous
+command entered, substituting one string for another in the command.
+The default is `\fB^\fP'.
+The optional third character is the character
+which indicates that the remainder of the line is a comment when found
+as the first character of a word, normally `\fB#\fP'.  The history
+comment character causes history substitution to be skipped for the
+remaining words on the line.  It does not necessarily cause the shell
+parser to treat the rest of the line as a comment.
+.PD
+.SS Arrays
+.B Bash
+provides one-dimensional indexed and associative array variables.
+Any variable may be used as an indexed array; the
+.B declare
+builtin will explicitly declare an array.
+There is no maximum
+limit on the size of an array, nor any requirement that members
+be indexed or assigned contiguously.
+Indexed arrays are referenced using integers (including arithmetic
+expressions) and are zero-based; associative arrays are referenced
+using arbitrary strings.
+Unless otherwise noted, indexed array indices must be non-negative integers.
+.PP
+An indexed array is created automatically if any variable is assigned to
+using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP.  The
+.I subscript
+is treated as an arithmetic expression that must evaluate to a number.
+To explicitly declare an indexed array, use
+.B declare \-a \fIname\fP
+(see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.B declare \-a \fIname\fP[\fIsubscript\fP]
+is also accepted; the \fIsubscript\fP is ignored.
+.PP
+Associative arrays are created using
+.BR "declare \-A \fIname\fP" .
+.PP
+Attributes may be
+specified for an array variable using the
+.B declare
+and
+.B readonly
+builtins.  Each attribute applies to all members of an array.
+.PP
+Arrays are assigned to using compound assignments of the form
+\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
+\fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
+Indexed array assignments do not require anything but \fIstring\fP.
+Each \fIvalue\fP in the list is expanded using all the shell expansions
+described below under
+.SM
+.BR EXPANSION .
+When assigning to indexed arrays, if the optional brackets and subscript
+are supplied, that index is assigned to;
+otherwise the index of the element assigned is the last index assigned
+to by the statement plus one.  Indexing starts at zero.
+.PP
+When assigning to an associative array, the words in a compound assignment
+may be either assignment statements, for which the subscript is required,
+or a list of words that is interpreted as a sequence of alternating keys
+and values:
+\fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP.
+These are treated identically to
+\fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP.
+The first word in the list determines how the remaining words
+are interpreted; all assignments in a list must be of the same type.
+When using key/value pairs, the keys may not be missing or empty;
+a final missing value is treated like the empty string.
+.PP
+This syntax is also accepted by the
+.B declare
+builtin.  Individual array elements may be assigned to using the
+\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
+When assigning to an indexed array, if
+.I name
+is subscripted by a negative number, that number is
+interpreted as relative to one greater than the maximum index of
+\fIname\fP, so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
+.PP
+The += operator will append to an array variable when assigning
+using the compound assignment syntax; see
+.SM
+.B PARAMETERS
+above.
+.PP
+Any element of an array may be referenced using
+${\fIname\fP[\fIsubscript\fP]}.  The braces are required to avoid
+conflicts with pathname expansion.  If
+\fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
+all members of \fIname\fP.  These subscripts differ only when the
+word appears within double quotes.  If the word is double-quoted,
+${\fIname\fP[*]} expands to a single
+word with the value of each array member separated by the first
+character of the
+.SM
+.B IFS
+special variable, and ${\fIname\fP[@]} expands each element of
+\fIname\fP to a separate word.  When there are no array members,
+${\fIname\fP[@]} expands to nothing.
+If the double-quoted expansion occurs within a word, the expansion of
+the first parameter is joined with the beginning part of the original
+word, and the expansion of the last parameter is joined with the last
+part of the original word.
+This is analogous to the expansion
+of the special parameters \fB*\fP and \fB@\fP (see
+.B Special Parameters
+above).  ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
+${\fIname\fP[\fIsubscript\fP]}.  If \fIsubscript\fP is \fB*\fP or
+\fB@\fP, the expansion is the number of elements in the array.
+If the
+.I subscript
+used to reference an element of an indexed array
+evaluates to a number less than zero, it is
+interpreted as relative to one greater than the maximum index of the array,
+so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
+.PP
+Referencing an array variable without a subscript is equivalent to
+referencing the array with a subscript of 0.
+Any reference to a variable using a valid subscript is legal, and
+.B bash
+will create an array if necessary.
+.PP
+An array variable is considered set if a subscript has been assigned a
+value.  The null string is a valid value.
+.PP
+It is possible to obtain the keys (indices) of an array as well as the values.
+${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
+expand to the indices assigned in array variable \fIname\fP.
+The treatment when in double quotes is similar to the expansion of the
+special parameters \fI@\fP and \fI*\fP within double quotes.
+.PP
+The
+.B unset
+builtin is used to destroy arrays.  \fBunset\fP \fIname\fP[\fIsubscript\fP]
+destroys the array element at index \fIsubscript\fP,
+for both indexed and associative arrays.
+Negative subscripts to indexed arrays are interpreted as described above.
+Unsetting the last element of an array variable does not unset the variable.
+\fBunset\fP \fIname\fP, where \fIname\fP is an array,
+removes the entire array.
+\fBunset\fP \fIname\fP[\fIsubscript\fP], where
+\fIsubscript\fP is \fB*\fP or \fB@\fP, behaves differently depending on
+whether \fIname\fP is an indexed or associative array.
+If \fIname\fP is an associative array, this unsets the element with
+subscript \fB*\fP or \fB@\fP.
+If \fIname\fP is an indexed array, unset removes all of the elements but
+does not remove the array itself.
+.PP
+When using a variable name with a subscript as an argument to a command,
+such as with \fBunset\fP, without using the word expansion syntax
+described above, the argument is subject to pathname expansion.
+If pathname expansion is not desired, the argument should be quoted.
+.PP
+The
+.BR declare ,
+.BR local ,
+and
+.B readonly
+builtins each accept a
+.B \-a
+option to specify an indexed array and a
+.B \-A
+option to specify an associative array.
+If both options are supplied,
+.B \-A
+takes precedence.
+The
+.B read
+builtin accepts a
+.B \-a
+option to assign a list of words read from the standard input
+to an array.  The
+.B set
+and
+.B declare
+builtins display array values in a way that allows them to be
+reused as assignments.
+.SH EXPANSION
+Expansion is performed on the command line after it has been split into
+words.  There are seven kinds of expansion performed:
+.IR "brace expansion" ,
+.IR "tilde expansion" ,
+.IR "parameter and variable expansion" ,
+.IR "command substitution" ,
+.IR "arithmetic expansion" ,
+.IR "word splitting" ,
+and
+.IR "pathname expansion" .
+.PP
+The order of expansions is:
+brace expansion;
+tilde expansion, parameter and variable expansion, arithmetic expansion,
+and command substitution (done in a left-to-right fashion);
+word splitting;
+and pathname expansion.
+.PP
+On systems that can support it, there is an additional expansion
+available: \fIprocess substitution\fP.
+This is performed at the
+same time as tilde, parameter, variable, and arithmetic expansion and
+command substitution.
+.PP
+After these expansions are performed, quote characters present in the
+original word are removed unless they have been quoted themselves
+(\fIquote removal\fP).
+.PP
+Only brace expansion, word splitting, and pathname expansion
+can increase the number of words of the expansion; other expansions
+expand a single word to a single word.
+The only exceptions to this are the expansions of
+"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP",
+and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
+as explained above (see
+.SM
+.BR PARAMETERS ).
+.SS Brace Expansion
+.I "Brace expansion"
+is a mechanism by which arbitrary strings
+may be generated.  This mechanism is similar to
+\fIpathname expansion\fP, but the filenames generated
+need not exist.  Patterns to be brace expanded take
+the form of an optional
+.IR preamble ,
+followed by either a series of comma-separated strings or
+a sequence expression between a pair of braces, followed by
+an optional
+.IR postscript .
+The preamble is prefixed to each string contained
+within the braces, and the postscript is then appended
+to each resulting string, expanding left to right.
+.PP
+Brace expansions may be nested.  The results of each expanded
+string are not sorted; left to right order is preserved.
+For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
+.PP
+A sequence expression takes the form
+\fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP,
+where \fIx\fP and \fIy\fP are either integers or single letters,
+and \fIincr\fP, an optional increment, is an integer.
+When integers are supplied, the expression expands to each number between
+\fIx\fP and \fIy\fP, inclusive.
+Supplied integers may be prefixed with \fI0\fP to force each term to have the
+same width.
+When either \fIx\fP or \fPy\fP begins with a zero, the shell
+attempts to force all generated terms to contain the same number of digits,
+zero-padding where necessary.
+When letters are supplied, the expression expands to each character
+lexicographically between \fIx\fP and \fIy\fP, inclusive,
+using the default C locale.
+Note that both \fIx\fP and \fIy\fP must be of the same type
+(integer or letter).
+When the increment is supplied, it is used as the difference between
+each term.  The default increment is 1 or \-1 as appropriate.
+.PP
+Brace expansion is performed before any other expansions,
+and any characters special to other expansions are preserved
+in the result.  It is strictly textual.
+.B Bash
+does not apply any syntactic interpretation to the context of the
+expansion or the text between the braces.
+.PP
+A correctly-formed brace expansion must contain unquoted opening
+and closing braces, and at least one unquoted comma or a valid
+sequence expression.
+Any incorrectly formed brace expansion is left unchanged.
+A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
+being considered part of a brace expression.
+To avoid conflicts with parameter expansion, the string \fB${\fP
+is not considered eligible for brace expansion, and inhibits brace
+expansion until the closing \fB}\fP.
+.PP
+This construct is typically used as shorthand when the common
+prefix of the strings to be generated is longer than in the
+above example:
+.RS
+.PP
+mkdir /usr/local/src/bash/{old,new,dist,bugs}
+.RE
+or
+.RS
+chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
+.RE
+.PP
+Brace expansion introduces a slight incompatibility with
+historical versions of
+.BR sh .
+.B sh
+does not treat opening or closing braces specially when they
+appear as part of a word, and preserves them in the output.
+.B Bash
+removes braces from words as a consequence of brace
+expansion.  For example, a word entered to
+.B sh
+as \fIfile{1,2}\fP
+appears identically in the output.  The same word is
+output as
+.I file1 file2
+after expansion by
+.BR bash .
+If strict compatibility with
+.B sh
+is desired, start
+.B bash
+with the
+.B +B
+option or disable brace expansion with the
+.B +B
+option to the
+.B set
+command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.SS Tilde Expansion
+If a word begins with an unquoted tilde character (`\fB~\fP'), all of
+the characters preceding the first unquoted slash (or all characters,
+if there is no unquoted slash) are considered a \fItilde-prefix\fP.
+If none of the characters in the tilde-prefix are quoted, the
+characters in the tilde-prefix following the tilde are treated as a
+possible \fIlogin name\fP.
+If this login name is the null string, the tilde is replaced with the
+value of the shell parameter
+.SM
+.BR HOME .
+If
+.SM
+.B HOME
+is unset, the home directory of the user executing the shell is
+substituted instead.
+Otherwise, the tilde-prefix is replaced with the home directory
+associated with the specified login name.
+.PP
+If the tilde-prefix is a `~+', the value of the shell variable
+.SM
+.B PWD
+replaces the tilde-prefix.
+If the tilde-prefix is a `~\-', the value of the shell variable
+.SM
+.BR OLDPWD ,
+if it is set, is substituted.
+If the characters following the tilde in the tilde-prefix consist
+of a number \fIN\fP, optionally prefixed
+by a `+' or a `\-', the tilde-prefix is replaced with the corresponding
+element from the directory stack, as it would be displayed by the
+.B dirs
+builtin invoked with the tilde-prefix as an argument.
+If the characters following the tilde in the tilde-prefix consist of a
+number without a leading `+' or `\-', `+' is assumed.
+.PP
+If the login name is invalid, or the tilde expansion fails, the word
+is unchanged.
+.PP
+Each variable assignment is checked for unquoted tilde-prefixes immediately
+following a
+.B :
+or the first
+.BR = .
+In these cases, tilde expansion is also performed.
+Consequently, one may use filenames with tildes in assignments to
+.SM
+.BR PATH ,
+.SM
+.BR MAILPATH ,
+and
+.SM
+.BR CDPATH ,
+and the shell assigns the expanded value.
+.PP
+Bash also performs tilde expansion on words satisfying the conditions of
+variable assignments (as described above under
+.SM
+.BR PARAMETERS )
+when they appear as arguments to simple commands.
+Bash does not do this, except for the \fIdeclaration\fP commands listed
+above, when in \fIposix mode\fP.
+.SS Parameter Expansion
+The `\fB$\fP' character introduces parameter expansion,
+command substitution, or arithmetic expansion.  The parameter name
+or symbol to be expanded may be enclosed in braces, which
+are optional but serve to protect the variable to be expanded from
+characters immediately following it which could be
+interpreted as part of the name.
+.PP
+When braces are used, the matching ending brace is the first `\fB}\fP'
+not escaped by a backslash or within a quoted string, and not within an
+embedded arithmetic expansion, command substitution, or parameter
+expansion.
+.PP
+.PD 0
+.TP
+${\fIparameter\fP}
+The value of \fIparameter\fP is substituted.  The braces are required
+when
+.I parameter
+is a positional parameter with more than one digit,
+or when
+.I parameter
+is followed by a character which is not to be
+interpreted as part of its name.
+The \fIparameter\fP is a shell parameter as described above
+\fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
+.PD
+.PP
+If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
+and \fIparameter\fP is not a \fInameref\fP,
+it introduces a level of indirection.
+\fBBash\fP uses the value formed by expanding the rest of
+\fIparameter\fP as the new \fIparameter\fP; this is then
+expanded and that value is used in the rest of the expansion, rather
+than the expansion of the original \fIparameter\fP.
+This is known as \fIindirect expansion\fP.
+The value is subject to tilde expansion,
+parameter expansion, command substitution, and arithmetic expansion.
+If \fIparameter\fP is a nameref, this expands to the name of the
+parameter referenced by \fIparameter\fP instead of performing the
+complete indirect expansion.
+The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
+${\fB!\fP\fIname\fP[\fI@\fP]} described below.
+The exclamation point must immediately follow the left brace in order to
+introduce indirection.
+.PP
+In each of the cases below, \fIword\fP is subject to tilde expansion,
+parameter expansion, command substitution, and arithmetic expansion.
+.PP
+When not performing substring expansion, using the forms documented below
+(e.g., \fB:-\fP),
+\fBbash\fP tests for a parameter that is unset or null.  Omitting the colon
+results in a test only for a parameter that is unset.
+.PP
+.PD 0
+.TP
+${\fIparameter\fP\fB:\-\fP\fIword\fP}
+\fBUse Default Values\fP.  If
+.I parameter
+is unset or null, the expansion of
+.I word
+is substituted.  Otherwise, the value of
+.I parameter
+is substituted.
+.TP
+${\fIparameter\fP\fB:=\fP\fIword\fP}
+\fBAssign Default Values\fP.
+If
+.I parameter
+is unset or null, the expansion of
+.I word
+is assigned to
+.IR parameter .
+The value of
+.I parameter
+is then substituted.  Positional parameters and special parameters may
+not be assigned to in this way.
+.TP
+${\fIparameter\fP\fB:?\fP\fIword\fP}
+\fBDisplay Error if Null or Unset\fP.
+If
+.I parameter
+is null or unset, the expansion of \fIword\fP (or a message to that effect
+if
+.I word
+is not present) is written to the standard error and the shell, if it
+is not interactive, exits.  Otherwise, the value of \fIparameter\fP is
+substituted.
+.TP
+${\fIparameter\fP\fB:+\fP\fIword\fP}
+\fBUse Alternate Value\fP.
+If
+.I parameter
+is null or unset, nothing is substituted, otherwise the expansion of
+.I word
+is substituted.
+.TP
+${\fIparameter\fP\fB:\fP\fIoffset\fP}
+.PD 0
+.TP
+${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
+.PD
+\fBSubstring Expansion\fP.
+Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
+starting at the character specified by \fIoffset\fP.
+If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by
+\fB@\fP or \fB*\fP, or an associative array name, the results differ as
+described below.
+If \fIlength\fP is omitted, expands to the substring of the value of
+\fIparameter\fP starting at the character specified by \fIoffset\fP
+and extending to the end of the value.
+\fIlength\fP and \fIoffset\fP are arithmetic expressions (see
+.SM
+.B
+ARITHMETIC EVALUATION
+below).
+.sp 1
+If \fIoffset\fP evaluates to a number less than zero, the value
+is used as an offset in characters
+from the end of the value of \fIparameter\fP.
+If \fIlength\fP evaluates to a number less than zero,
+it is interpreted as an offset in characters
+from the end of the value of \fIparameter\fP rather than
+a number of characters, and the expansion is the characters between
+\fIoffset\fP and that result.
+Note that a negative offset must be separated from the colon by at least
+one space to avoid being confused with the \fB:-\fP expansion.
+.sp 1
+If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP
+positional parameters beginning at \fIoffset\fP.
+A negative \fIoffset\fP is taken relative to one greater than the greatest
+positional parameter, so an offset of \-1 evaluates to the last positional
+parameter.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
+If \fIparameter\fP is an indexed array name subscripted by @ or *,
+the result is the \fIlength\fP
+members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
+A negative \fIoffset\fP is taken relative to one greater than the maximum
+index of the specified array.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
+Substring expansion applied to an associative array produces undefined
+results.
+.sp 1
+Substring indexing is zero-based unless the positional parameters
+are used, in which case the indexing starts at 1 by default.
+If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
+prefixed to the list.
+.TP
+${\fB!\fP\fIprefix\fP\fB*\fP}
+.PD 0
+.TP
+${\fB!\fP\fIprefix\fP\fB@\fP}
+.PD
+\fBNames matching prefix\fP.
+Expands to the names of variables whose names begin with \fIprefix\fP,
+separated by the first character of the
+.SM
+.B IFS
+special variable.
+When \fI@\fP is used and the expansion appears within double quotes, each
+variable name expands to a separate word.
+.TP
+${\fB!\fP\fIname\fP[\fI@\fP]}
+.PD 0
+.TP
+${\fB!\fP\fIname\fP[\fI*\fP]}
+.PD
+\fBList of array keys\fP.
+If \fIname\fP is an array variable, expands to the list of array indices
+(keys) assigned in \fIname\fP.
+If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
+otherwise.
+When \fI@\fP is used and the expansion appears within double quotes, each
+key expands to a separate word.
+.TP
+${\fB#\fP\fIparameter\fP}
+\fBParameter length\fP.
+The length in characters of the value of \fIparameter\fP is substituted.
+If
+.I parameter
+is
+.B *
+or
+.BR @ ,
+the value substituted is the number of positional parameters.
+If
+.I parameter
+is an array name subscripted by
+.B *
+or
+.BR @ ,
+the value substituted is the number of elements in the array.
+If
+.I parameter
+is an indexed array name subscripted by a negative number, that number is
+interpreted as relative to one greater than the maximum index of
+\fIparameter\fP, so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
+.TP
+${\fIparameter\fP\fB#\fP\fIword\fP}
+.PD 0
+.TP
+${\fIparameter\fP\fB##\fP\fIword\fP}
+.PD
+\fBRemove matching prefix pattern\fP.
+The
+.I word
+is expanded to produce a pattern just as in pathname
+expansion, and matched against the expanded value of
+.I parameter
+using the rules described under
+.B Pattern Matching
+below.
+If the pattern matches the beginning of
+the value of
+.IR parameter ,
+then the result of the expansion is the expanded value of
+.I parameter
+with the shortest matching pattern (the ``\fB#\fP'' case) or the
+longest matching pattern (the ``\fB##\fP'' case) deleted.
+If
+.I parameter
+is
+.B @
+or
+.BR * ,
+the pattern removal operation is applied to each positional
+parameter in turn, and the expansion is the resultant list.
+If
+.I parameter
+is an array variable subscripted with
+.B @
+or
+.BR * ,
+the pattern removal operation is applied to each member of the
+array in turn, and the expansion is the resultant list.
+.TP
+${\fIparameter\fP\fB%\fP\fIword\fP}
+.PD 0
+.TP
+${\fIparameter\fP\fB%%\fP\fIword\fP}
+.PD
+\fBRemove matching suffix pattern\fP.
+The \fIword\fP is expanded to produce a pattern just as in
+pathname expansion, and matched against the expanded value of
+.I parameter
+using the rules described under
+.B Pattern Matching
+below.
+If the pattern matches a trailing portion of the expanded value of
+.IR parameter ,
+then the result of the expansion is the expanded value of
+.I parameter
+with the shortest matching pattern (the ``\fB%\fP'' case) or the
+longest matching pattern (the ``\fB%%\fP'' case) deleted.
+If
+.I parameter
+is
+.B @
+or
+.BR * ,
+the pattern removal operation is applied to each positional
+parameter in turn, and the expansion is the resultant list.
+If
+.I parameter
+is an array variable subscripted with
+.B @
+or
+.BR * ,
+the pattern removal operation is applied to each member of the
+array in turn, and the expansion is the resultant list.
+.TP
+${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
+.PD 0
+.TP
+${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
+.TP
+${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP}
+.TP
+${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP}
+.PD
+\fBPattern substitution\fP.
+The \fIpattern\fP is expanded to produce a pattern just as in
+pathname expansion.
+\fIParameter\fP is expanded and the longest match of \fIpattern\fP
+against its value is replaced with \fIstring\fP.
+\fIstring\fP undergoes tilde expansion, parameter and variable expansion,
+arithmetic expansion, command and process substitution, and quote removal.
+The match is performed using the rules described under
+.B Pattern Matching
+below.
+In the first form above, only the first match is replaced.
+If there are two slashes separating \fIparameter\fP and \fIpattern\fP 
+(the second form above), all matches of \fIpattern\fP are
+replaced with \fIstring\fP.
+If \fIpattern\fP is preceded by \fB#\fP (the third form above),
+it must match at the beginning of the expanded value of \fIparameter\fP.
+If \fIpattern\fP is preceded by \fB%\fP (the fourth form above),
+it must match at the end of the expanded value of \fIparameter\fP.
+If the expansion of \fIstring\fP is null,
+matches of \fIpattern\fP are deleted.
+If \fIstring\fP is null,
+matches of \fIpattern\fP are deleted
+and the \fB/\fP following \fIpattern\fP may be omitted.
+.sp 1
+If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP,
+any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the
+matching portion of \fIpattern\fP.
+.sp 1
+Quoting any part of \fIstring\fP inhibits replacement in the
+expansion of the quoted portion, including replacement strings stored
+in shell variables.
+Backslash will escape \fB&\fP in \fIstring\fP; the backslash is removed
+in order to permit a literal \fB&\fP in the replacement string.
+Backslash can also be used to escape a backslash; \fB\e\e\fP results in
+a literal backslash in the replacement.
+Users should take care if \fIstring\fP is double-quoted to avoid
+unwanted interactions between the backslash and double-quoting, since
+backslash has special meaning within double quotes.
+Pattern substitution performs the check for unquoted \fB&\fP after
+expanding \fIstring\fP;
+shell programmers should quote any occurrences of \fB&\fP
+they want to be taken literally in the replacement
+and ensure any instances of \fB&\fP they want to be replaced are unquoted.
+.sp 1
+If the
+.B nocasematch
+shell option is enabled, the match is performed without regard to the case
+of alphabetic characters.
+If
+.I parameter
+is
+.B @
+or
+.BR * ,
+the substitution operation is applied to each positional
+parameter in turn, and the expansion is the resultant list.
+If
+.I parameter
+is an array variable subscripted with
+.B @
+or
+.BR * ,
+the substitution operation is applied to each member of the
+array in turn, and the expansion is the resultant list.
+.TP
+${\fIparameter\fP\fB^\fP\fIpattern\fP}
+.PD 0
+.TP
+${\fIparameter\fP\fB^^\fP\fIpattern\fP}
+.TP
+${\fIparameter\fP\fB,\fP\fIpattern\fP}
+.TP
+${\fIparameter\fP\fB,,\fP\fIpattern\fP}
+.PD
+\fBCase modification\fP.
+This expansion modifies the case of alphabetic characters in \fIparameter\fP.
+The \fIpattern\fP is expanded to produce a pattern just as in
+pathname expansion.
+Each character in the expanded value of \fIparameter\fP is tested against
+\fIpattern\fP, and, if it matches the pattern, its case is converted.
+The pattern should not attempt to match more than one character.
+The \fB^\fP operator converts lowercase letters matching \fIpattern\fP
+to uppercase; the \fB,\fP operator converts matching uppercase letters
+to lowercase.
+The \fB^^\fP and \fB,,\fP expansions convert each matched character in the
+expanded value; the \fB^\fP and \fB,\fP expansions match and convert only
+the first character in the expanded value.
+If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
+every character.
+If
+.I parameter
+is
+.B @
+or
+.BR * ,
+the case modification operation is applied to each positional
+parameter in turn, and the expansion is the resultant list.
+If
+.I parameter
+is an array variable subscripted with
+.B @
+or
+.BR * ,
+the case modification operation is applied to each member of the
+array in turn, and the expansion is the resultant list.
+.TP
+${\fIparameter\fP\fB@\fP\fIoperator\fP}
+\fBParameter transformation\fP.
+The expansion is either a transformation of the value of \fIparameter\fP
+or information about \fIparameter\fP itself, depending on the value of
+\fIoperator\fP.  Each \fIoperator\fP is a single letter:
+.sp 1
+.RS
+.PD 0
+.TP
+.B U
+The expansion is a string that is the value of \fIparameter\fP with lowercase
+alphabetic characters converted to uppercase.
+.TP
+.B u
+The expansion is a string that is the value of \fIparameter\fP with the first
+character converted to uppercase, if it is alphabetic.
+.TP
+.B L
+The expansion is a string that is the value of \fIparameter\fP with uppercase
+alphabetic characters converted to lowercase.
+.TP
+.B Q
+The expansion is a string that is the value of \fIparameter\fP quoted in a
+format that can be reused as input.
+.TP
+.B E
+The expansion is a string that is the value of \fIparameter\fP with backslash
+escape sequences expanded as with the \fB$\(aq...\(aq\fP quoting mechanism.
+.TP
+.B P
+The expansion is a string that is the result of expanding the value of
+\fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below).
+.TP
+.B A
+The expansion is a string in the form of
+an assignment statement or \fBdeclare\fP command that, if
+evaluated, will recreate \fIparameter\fP with its attributes and value.
+.TP
+.B K
+Produces a possibly-quoted version of the value of \fIparameter\fP,
+except that it prints the values of
+indexed and associative arrays as a sequence of quoted key-value pairs
+(see \fBArrays\fP above).
+.TP
+.B a
+The expansion is a string consisting of flag values representing
+\fIparameter\fP's attributes.
+.TP
+.B k
+Like the K transformation, but expands the keys and values of
+indexed and associative arrays to separate words after word splitting.
+.PD
+.PP
+If
+.I parameter
+is
+.B @
+or
+.BR * ,
+the operation is applied to each positional
+parameter in turn, and the expansion is the resultant list.
+If
+.I parameter
+is an array variable subscripted with
+.B @
+or
+.BR * ,
+the operation is applied to each member of the
+array in turn, and the expansion is the resultant list.
+.sp 1
+The result of the expansion is subject to word splitting and pathname
+expansion as described below.
+.RE
+.SS Command Substitution
+\fICommand substitution\fP allows the output of a command to replace
+the command name.  There are two forms:
+.RS
+.PP
+\fB$(\fP\fIcommand\fP\|\fB)\fP
+.RE
+or
+.RS
+\fB\`\fP\fIcommand\fP\fB\`\fP
+.RE
+.PP
+.B Bash
+performs the expansion by executing \fIcommand\fP in a subshell environment
+and replacing the command substitution with the standard output of the
+command, with any trailing newlines deleted.
+Embedded newlines are not deleted, but they may be removed during
+word splitting.
+The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
+the equivalent but faster \fB$(< \fIfile\fP)\fR.
+.PP
+When the old-style backquote form of substitution is used,
+backslash retains its literal meaning except when followed by
+.BR $ ,
+.BR \` ,
+or
+.BR \e .
+The first backquote not preceded by a backslash terminates the
+command substitution.
+When using the $(\^\fIcommand\fP\|) form, all characters between the
+parentheses make up the command; none are treated specially.
+.PP
+Command substitutions may be nested.  To nest when using the backquoted form,
+escape the inner backquotes with backslashes.
+.PP
+If the substitution appears within double quotes, word splitting and
+pathname expansion are not performed on the results.
+.SS Arithmetic Expansion
+Arithmetic expansion allows the evaluation of an arithmetic expression
+and the substitution of the result.  The format for arithmetic expansion is:
+.RS
+.PP
+\fB$((\fP\fIexpression\fP\fB))\fP
+.RE
+.PP
+The
+.I expression
+undergoes the same expansions
+as if it were within double quotes,
+but double quote characters in \fIexpression\fP are not treated specially
+and are removed.
+All tokens in the expression undergo parameter and variable expansion,
+command substitution, and quote removal.
+The result is treated as the arithmetic expression to be evaluated.
+Arithmetic expansions may be nested.
+.PP
+The evaluation is performed according to the rules listed below under
+.SM
+.BR "ARITHMETIC EVALUATION" .
+If
+.I expression
+is invalid,
+.B bash
+prints a message indicating failure and no substitution occurs.
+.SS Process Substitution
+\fIProcess substitution\fP allows a process's input or output to be
+referred to using a filename.
+It takes the form of
+\fB<(\fP\fIlist\^\fP\fB)\fP
+or
+\fB>(\fP\fIlist\^\fP\fB)\fP.
+The process \fIlist\fP is run asynchronously, and its input or output
+appears as a filename.
+This filename is
+passed as an argument to the current command as the result of the
+expansion.
+If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
+the file will provide input for \fIlist\fP.  If the
+\fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
+argument should be read to obtain the output of \fIlist\fP.
+Process substitution is supported on systems that support named
+pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
+.PP
+When available, process substitution is performed
+simultaneously with parameter and variable expansion,
+command substitution,
+and arithmetic expansion.
+.SS Word Splitting
+The shell scans the results of
+parameter expansion,
+command substitution,
+and
+arithmetic expansion
+that did not occur within double quotes for
+.IR "word splitting" .
+.PP
+The shell treats each character of
+.SM
+.B IFS
+as a delimiter, and splits the results of the other
+expansions into words using these characters as field terminators.
+If
+.SM
+.B IFS
+is unset, or its
+value is exactly
+.BR <space><tab><newline> ,
+the default, then
+sequences of
+.BR <space> ,
+.BR <tab> ,
+and
+.B <newline>
+at the beginning and end of the results of the previous
+expansions are ignored, and
+any sequence of
+.SM
+.B IFS
+characters not at the beginning or end serves to delimit words.
+If
+.SM
+.B IFS
+has a value other than the default, then sequences of
+the whitespace characters
+.BR space ,
+.BR tab ,
+and
+.B newline
+are ignored at the beginning and end of the
+word, as long as the whitespace character is in the
+value of
+.SM
+.B IFS
+(an
+.SM
+.B IFS
+whitespace character).
+Any character in
+.SM
+.B IFS
+that is not
+.SM
+.B IFS
+whitespace, along with any adjacent
+.SM
+.B IFS
+whitespace characters, delimits a field.
+A sequence of
+.SM
+.B IFS
+whitespace characters is also treated as a delimiter.
+If the value of
+.SM
+.B IFS
+is null, no word splitting occurs.
+.PP
+Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
+and passed to commands as empty strings.
+Unquoted implicit null arguments, resulting from the expansion of
+parameters that have no values, are removed.
+If a parameter with no value is expanded within double quotes, a
+null argument results and is retained
+and passed to a command as an empty string.
+When a quoted null argument appears as part of a word whose expansion is
+non-null, the null argument is removed.
+That is, the word
+\f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and
+null argument removal.
+.PP
+Note that if no expansion occurs, no splitting
+is performed.
+.SS Pathname Expansion
+After word splitting,
+unless the
+.B \-f
+option has been set,
+.B bash
+scans each word for the characters
+.BR * ,
+.BR ? ,
+and
+.BR [ .
+If one of these characters appears, and is not quoted, then the word is
+regarded as a
+.IR pattern ,
+and replaced with an alphabetically sorted list of
+filenames matching the pattern
+(see
+.SM
+.B "Pattern Matching"
+below).
+If no matching filenames are found,
+and the shell option
+.B nullglob
+is not enabled, the word is left unchanged.
+If the
+.B nullglob
+option is set, and no matches are found,
+the word is removed.
+If the
+.B failglob
+shell option is set, and no matches are found, an error message
+is printed and the command is not executed.
+If the shell option
+.B nocaseglob
+is enabled, the match is performed without regard to the case
+of alphabetic characters.
+When a pattern is used for pathname expansion,
+the character
+.B ``.''
+at the start of a name or immediately following a slash
+must be matched explicitly, unless the shell option
+.B dotglob
+is set.
+In order to match the filenames
+.B ``.''
+and
+.BR ``..'' ,
+the pattern must begin with ``.'' (for example, ``.?''),
+even if
+.B dotglob
+is set.
+If the
+.B globskipdots
+shell option is enabled, the filenames
+.B ``.''
+and
+.BR ``..''
+are never matched, even if the pattern begins with a
+.BR ``.'' .
+When not matching pathnames, the
+.B ``.''
+character is not treated specially.
+When matching a pathname, the slash character must always be
+matched explicitly by a slash in the pattern, but in other matching
+contexts it can be matched by a special pattern character as described
+below under
+.SM
+.BR "Pattern Matching" .
+See the description of
+.B shopt
+below under
+.SM
+.B SHELL BUILTIN COMMANDS
+for a description of the
+.BR nocaseglob ,
+.BR nullglob ,
+.BR globskipdots ,
+.BR failglob ,
+and
+.B dotglob
+shell options.
+.PP
+The
+.SM
+.B GLOBIGNORE
+shell variable may be used to restrict the set of file names matching a
+.IR pattern .
+If
+.SM
+.B GLOBIGNORE
+is set, each matching file name that also matches one of the patterns in
+.SM
+.B GLOBIGNORE
+is removed from the list of matches.
+If the \fBnocaseglob\fP option is set, the matching against the patterns in
+.SM
+.B GLOBIGNORE
+is performed without regard to case.
+The filenames
+.B ``.''
+and
+.B ``..''
+are always ignored when
+.SM
+.B GLOBIGNORE
+is set and not null.  However, setting
+.SM
+.B GLOBIGNORE
+to a non-null value has the effect of enabling the
+.B dotglob
+shell option, so all other filenames beginning with a
+.B ``.''
+will match.
+To get the old behavior of ignoring filenames beginning with a
+.BR ``.'' ,
+make
+.B ``.*''
+one of the patterns in
+.SM
+.BR GLOBIGNORE .
+The
+.B dotglob
+option is disabled when
+.SM
+.B GLOBIGNORE
+is unset.
+The pattern matching honors the setting of the \fBextglob\fP shell
+option.
+.PP
+\fBPattern Matching\fP
+.PP
+Any character that appears in a pattern, other than the special pattern
+characters described below, matches itself.  The NUL character may not
+occur in a pattern.  A backslash escapes the following character; the
+escaping backslash is discarded when matching.
+The special pattern characters must be quoted if
+they are to be matched literally.
+.PP
+The special pattern characters have the following meanings:
+.PP
+.PD 0
+.RS
+.TP
+.B *
+Matches any string, including the null string.
+When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
+a pathname expansion context, two adjacent \fB*\fPs used as a single
+pattern will match all files and zero or more directories and
+subdirectories.
+If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories
+and subdirectories.
+.TP
+.B ?
+Matches any single character.
+.TP
+.B [...]
+Matches any one of the enclosed characters.  A pair of characters
+separated by a hyphen denotes a
+\fIrange expression\fP;
+any character that falls between those two characters, inclusive,
+using the current locale's collating sequence and character set,
+is matched.  If the first character following the
+.B [
+is a
+.B !
+or a
+.B ^
+then any character not enclosed is matched.
+The sorting order of characters in range expressions,
+and the characters included in the range,
+are determined by
+the current locale and the values of the
+.SM
+.B LC_COLLATE
+or
+.SM
+.B LC_ALL
+shell variables, if set.
+To obtain the traditional interpretation of range expressions, where
+.B [a\-d]
+is equivalent to
+.BR [abcd] ,
+set value of the
+.B LC_ALL
+shell variable to
+.BR C ,
+or enable the
+.B globasciiranges
+shell option.
+A
+.B \-
+may be matched by including it as the first or last character
+in the set.
+A
+.B ]
+may be matched by including it as the first character
+in the set.
+.br
+.if t .sp 0.5
+.if n .sp 1
+Within
+.B [
+and
+.BR ] ,
+\fIcharacter classes\fP can be specified using the syntax
+\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
+following classes defined in the POSIX standard:
+.PP
+.RS
+.B
+.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
+.if t alnum   alpha   ascii   blank   cntrl   digit   graph   lower   print   punct   space   upper   word   xdigit
+.br
+A character class matches any character belonging to that class.
+The \fBword\fP character class matches letters, digits, and the character _.
+.br
+.if t .sp 0.5
+.if n .sp 1
+Within
+.B [
+and
+.BR ] ,
+an \fIequivalence class\fP can be specified using the syntax
+\fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
+same collation weight (as defined by the current locale) as
+the character \fIc\fP.
+.br
+.if t .sp 0.5
+.if n .sp 1
+Within
+.B [
+and
+.BR ] ,
+the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
+\fIsymbol\fP.
+.RE
+.RE
+.PD
+.PP
+If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
+builtin, the shell recognizes several extended pattern matching operators.
+In the following description, a \fIpattern-list\fP is a list of one
+or more patterns separated by a \fB|\fP.
+Composite patterns may be formed using one or more of the following
+sub-patterns:
+.sp 1
+.PD 0
+.RS
+.TP
+\fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
+Matches zero or one occurrence of the given patterns
+.TP
+\fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
+Matches zero or more occurrences of the given patterns
+.TP
+\fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
+Matches one or more occurrences of the given patterns
+.TP
+\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
+Matches one of the given patterns
+.TP
+\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
+Matches anything except one of the given patterns
+.RE
+.PD
+.PP
+The\fBextglob\fP option changes the behavior of the parser, since the
+parentheses are normally treated as operators with syntactic meaning.
+To ensure that extended matching patterns are parsed correctly, make sure
+that \fBextglob\fP is enabled before parsing constructs containing the
+patterns, including shell functions and command substitutions.
+.PP
+When matching filenames, the \fBdotglob\fP shell option determines
+the set of filenames that are tested:
+when \fBdotglob\fP is enabled, the set of filenames includes all files
+beginning with ``.'', but ``.'' and ``..'' must be matched by a
+pattern or sub-pattern that begins with a dot;
+when it is disabled, the set does not
+include any filenames beginning with ``.'' unless the pattern
+or sub-pattern begins with a ``.''.
+As above, ``.'' only has a special meaning when matching filenames.
+.PP
+Complicated extended pattern matching against long strings is slow,
+especially when the patterns contain alternations and the strings
+contain multiple matches.
+Using separate matches against shorter strings, or using arrays of
+strings instead of a single long string, may be faster.
+.SS Quote Removal
+After the preceding expansions, all unquoted occurrences of the
+characters
+.BR \e ,
+.BR \(aq ,
+and \^\f3"\fP\^ that did not result from one of the above
+expansions are removed.
+.SH REDIRECTION
+Before a command is executed, its input and output
+may be
+.I redirected
+using a special notation interpreted by the shell.
+\fIRedirection\fP allows commands' file handles to be
+duplicated, opened, closed,
+made to refer to different files,
+and can change the files the command reads from and writes to.
+Redirection may also be used to modify file handles in the
+current shell execution environment.
+The following redirection
+operators may precede or appear anywhere within a
+.I simple command
+or may follow a
+.IR command .
+Redirections are processed in the order they appear, from
+left to right.
+.PP
+Each redirection that may be preceded by a file descriptor number
+may instead be preceded by a word of the form {\fIvarname\fP}.
+In this case, for each redirection operator except
+>&- and <&-, the shell will allocate a file descriptor greater
+than or equal to 10 and assign it to \fIvarname\fP.
+If >&- or <&- is preceded
+by {\fIvarname\fP}, the value of \fIvarname\fP defines the file
+descriptor to close.
+If {\fIvarname\fP} is supplied, the redirection persists beyond
+the scope of the command, allowing the shell programmer to manage
+the file descriptor's lifetime manually.
+The \fBvarredir_close\fP shell option manages this behavior.
+.PP
+In the following descriptions, if the file descriptor number is
+omitted, and the first character of the redirection operator is
+.BR < ,
+the redirection refers to the standard input (file descriptor
+0).  If the first character of the redirection operator is
+.BR > ,
+the redirection refers to the standard output (file descriptor
+1).
+.PP
+The word following the redirection operator in the following
+descriptions, unless otherwise noted, is subjected to
+brace expansion, tilde expansion, parameter and variable expansion,
+command substitution, arithmetic expansion, quote removal,
+pathname expansion, and word splitting.
+If it expands to more than one word,
+.B bash
+reports an error.
+.PP
+Note that the order of redirections is significant.  For example,
+the command
+.RS
+.PP
+ls \fB>\fP dirlist 2\fB>&\fP1
+.RE
+.PP
+directs both standard output and standard error to the file
+.IR dirlist ,
+while the command
+.RS
+.PP
+ls 2\fB>&\fP1 \fB>\fP dirlist
+.RE
+.PP
+directs only the standard output to file
+.IR dirlist ,
+because the standard error was duplicated from the standard output
+before the standard output was redirected to
+.IR dirlist .
+.PP
+\fBBash\fP handles several filenames specially when they are used in
+redirections, as described in the following table.
+If the operating system on which \fBbash\fP is running provides these
+special files, bash will use them; otherwise it will emulate them
+internally with the behavior described below.
+.RS
+.PP
+.PD 0
+.TP
+.B /dev/fd/\fIfd\fP
+If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated.
+.TP
+.B /dev/stdin
+File descriptor 0 is duplicated.
+.TP
+.B /dev/stdout
+File descriptor 1 is duplicated.
+.TP
+.B /dev/stderr
+File descriptor 2 is duplicated.
+.TP
+.B /dev/tcp/\fIhost\fP/\fIport\fP
+If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
+is an integer port number or service name, \fBbash\fP attempts to open
+the corresponding TCP socket.
+.TP
+.B /dev/udp/\fIhost\fP/\fIport\fP
+If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
+is an integer port number or service name, \fBbash\fP attempts to open
+the corresponding UDP socket.
+.PD
+.RE
+.PP
+A failure to open or create a file causes the redirection to fail.
+.PP
+Redirections using file descriptors greater than 9 should be used with
+care, as they may conflict with file descriptors the shell uses
+internally.
+.SS Redirecting Input
+Redirection of input causes the file whose name results from
+the expansion of
+.I word
+to be opened for reading on file descriptor
+.IR n ,
+or the standard input (file descriptor 0) if
+.I n
+is not specified.
+.PP
+The general format for redirecting input is:
+.RS
+.PP
+[\fIn\fP]\fB<\fP\fIword\fP
+.RE
+.SS Redirecting Output
+Redirection of output causes the file whose name results from
+the expansion of
+.I word
+to be opened for writing on file descriptor
+.IR n ,
+or the standard output (file descriptor 1) if
+.I n
+is not specified.  If the file does not exist it is created;
+if it does exist it is truncated to zero size.
+.PP
+The general format for redirecting output is:
+.RS
+.PP
+[\fIn\fP]\fB>\fP\fIword\fP
+.RE
+.PP
+If the redirection operator is
+.BR > ,
+and the
+.B noclobber
+option to the
+.B set
+builtin has been enabled, the redirection will fail if the file
+whose name results from the expansion of \fIword\fP exists and is
+a regular file.
+If the redirection operator is
+.BR >| ,
+or the redirection operator is
+.B >
+and the
+.B noclobber
+option to the
+.B set
+builtin command is not enabled, the redirection is attempted even
+if the file named by \fIword\fP exists.
+.SS Appending Redirected Output
+Redirection of output in this fashion
+causes the file whose name results from
+the expansion of
+.I word
+to be opened for appending on file descriptor
+.IR n ,
+or the standard output (file descriptor 1) if
+.I n
+is not specified.  If the file does not exist it is created.
+.PP
+The general format for appending output is:
+.RS
+.PP
+[\fIn\fP]\fB>>\fP\fIword\fP
+.RE
+.SS Redirecting Standard Output and Standard Error
+This construct allows both the
+standard output (file descriptor 1) and
+the standard error output (file descriptor 2)
+to be redirected to the file whose name is the
+expansion of
+.IR word .
+.PP
+There are two formats for redirecting standard output and
+standard error:
+.RS
+.PP
+\fB&>\fP\fIword\fP
+.RE
+and
+.RS
+\fB>&\fP\fIword\fP
+.RE
+.PP
+Of the two forms, the first is preferred.
+This is semantically equivalent to
+.RS
+.PP
+\fB>\fP\fIword\fP 2\fB>&\fP1
+.RE
+.PP
+When using the second form, \fIword\fP may not expand to a number or
+\fB\-\fP.  If it does, other redirection operators apply
+(see \fBDuplicating File Descriptors\fP below) for compatibility
+reasons.
+.SS Appending Standard Output and Standard Error
+This construct allows both the
+standard output (file descriptor 1) and
+the standard error output (file descriptor 2)
+to be appended to the file whose name is the
+expansion of
+.IR word .
+.PP
+The format for appending standard output and standard error is:
+.RS
+.PP
+\fB&>>\fP\fIword\fP
+.RE
+.PP
+This is semantically equivalent to
+.RS
+.PP
+\fB>>\fP\fIword\fP 2\fB>&\fP1
+.RE
+.PP
+(see \fBDuplicating File Descriptors\fP below).
+.SS Here Documents
+This type of redirection instructs the shell to read input from the
+current source until a line containing only
+.I delimiter
+(with no trailing blanks)
+is seen.  All of
+the lines read up to that point are then used as the standard
+input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command.
+.PP
+The format of here-documents is:
+.RS
+.PP
+.nf
+[\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP
+        \fIhere-document\fP
+\fIdelimiter\fP
+.fi
+.RE
+.PP
+No parameter and variable expansion, command substitution,
+arithmetic expansion, or pathname expansion is performed on
+.IR word .
+If any part of
+.I word
+is quoted, the
+.I delimiter
+is the result of quote removal on
+.IR word ,
+and the lines in the here-document are not expanded.
+If \fIword\fP is unquoted,
+all lines of the here-document are subjected to
+parameter expansion, command substitution, and arithmetic expansion,
+the character sequence
+.B \e<newline>
+is ignored, and
+.B \e
+must be used to quote the characters
+.BR \e ,
+.BR $ ,
+and
+.BR \` .
+.PP
+If the redirection operator is
+.BR <<\- ,
+then all leading tab characters are stripped from input lines and the
+line containing
+.IR delimiter .
+This allows
+here-documents within shell scripts to be indented in a
+natural fashion.
+.SS "Here Strings"
+A variant of here documents, the format is:
+.RS
+.PP
+.nf
+[\fIn\fP]\fB<<<\fP\fIword\fP
+.fi
+.RE
+.PP
+The \fIword\fP undergoes
+tilde expansion, parameter and variable expansion,
+command substitution, arithmetic expansion, and quote removal.
+Pathname expansion and word splitting are not performed.
+The result is supplied as a single string, with a newline appended,
+to the command on its
+standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
+.SS "Duplicating File Descriptors"
+The redirection operator
+.RS
+.PP
+[\fIn\fP]\fB<&\fP\fIword\fP
+.RE
+.PP
+is used to duplicate input file descriptors.
+If
+.I word
+expands to one or more digits, the file descriptor denoted by
+.I n
+is made to be a copy of that file descriptor.
+If the digits in
+.I word
+do not specify a file descriptor open for input, a redirection error occurs.
+If
+.I word
+evaluates to
+.BR \- ,
+file descriptor
+.I n
+is closed.  If
+.I n
+is not specified, the standard input (file descriptor 0) is used.
+.PP
+The operator
+.RS
+.PP
+[\fIn\fP]\fB>&\fP\fIword\fP
+.RE
+.PP
+is used similarly to duplicate output file descriptors.  If
+.I n
+is not specified, the standard output (file descriptor 1) is used.
+If the digits in
+.I word
+do not specify a file descriptor open for output, a redirection error occurs.
+If
+.I word
+evaluates to
+.BR \- ,
+file descriptor
+.I n
+is closed.
+As a special case, if \fIn\fP is omitted, and \fIword\fP does not
+expand to one or more digits or \fB\-\fP, the standard output and standard
+error are redirected as described previously.
+.SS "Moving File Descriptors"
+The redirection operator
+.RS
+.PP
+[\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
+.RE
+.PP
+moves the file descriptor \fIdigit\fP to file descriptor
+.IR n ,
+or the standard input (file descriptor 0) if \fIn\fP is not specified.
+\fIdigit\fP is closed after being duplicated to \fIn\fP.
+.PP
+Similarly, the redirection operator
+.RS
+.PP
+[\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
+.RE
+.PP
+moves the file descriptor \fIdigit\fP to file descriptor
+.IR n ,
+or the standard output (file descriptor 1) if \fIn\fP is not specified.
+.SS "Opening File Descriptors for Reading and Writing"
+The redirection operator
+.RS
+.PP
+[\fIn\fP]\fB<>\fP\fIword\fP
+.RE
+.PP
+causes the file whose name is the expansion of
+.I word
+to be opened for both reading and writing on file descriptor
+.IR n ,
+or on file descriptor 0 if
+.I n
+is not specified.  If the file does not exist, it is created.
+.SH ALIASES
+\fIAliases\fP allow a string to be substituted for a word when it is used
+as the first word of a simple command.
+The shell maintains a list of aliases that may be set and unset with the
+.B alias
+and
+.B unalias
+builtin commands (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+The first word of each simple command, if unquoted,
+is checked to see if it has an
+alias.  If so, that word is replaced by the text of the alias.
+The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
+any of the shell \fImetacharacters\fP or quoting characters
+listed above may not appear in an alias name.
+The replacement text may contain any valid shell input,
+including shell metacharacters.
+The first word of the replacement text is tested
+for aliases, but a word that is identical to an alias being expanded
+is not expanded a second time.
+This means that one may alias
+.B ls
+to
+.BR "ls \-F" ,
+for instance, and
+.B bash
+does not try to recursively expand the replacement text.
+If the last character of the alias value is a
+.IR blank ,
+then the next command
+word following the alias is also checked for alias expansion.
+.PP
+Aliases are created and listed with the
+.B alias
+command, and removed with the
+.B unalias
+command.
+.PP
+There is no mechanism for using arguments in the replacement text.
+If arguments are needed, use a shell function (see
+.SM
+.B FUNCTIONS
+below).
+.PP
+Aliases are not expanded when the shell is not interactive, unless
+the
+.B expand_aliases
+shell option is set using
+.B shopt
+(see the description of
+.B shopt
+under
+.SM
+\fBSHELL BUILTIN COMMANDS\fP
+below).
+.PP
+The rules concerning the definition and use of aliases are
+somewhat confusing.
+.B Bash
+always reads at least one complete line of input,
+and all lines that make up a compound command,
+before executing any of the commands on that line or the compound command.
+Aliases are expanded when a
+command is read, not when it is executed.  Therefore, an
+alias definition appearing on the same line as another
+command does not take effect until the next line of input is read.
+The commands following the alias definition
+on that line are not affected by the new alias.
+This behavior is also an issue when functions are executed.
+Aliases are expanded when a function definition is read,
+not when the function is executed, because a function definition
+is itself a command.  As a consequence, aliases
+defined in a function are not available until after that
+function is executed.  To be safe, always put
+alias definitions on a separate line, and do not use
+.B alias
+in compound commands.
+.PP
+For almost every purpose, aliases are superseded by
+shell functions.
+.SH FUNCTIONS
+A shell function, defined as described above under
+.SM
+.BR "SHELL GRAMMAR" ,
+stores a series of commands for later execution.
+When the name of a shell function is used as a simple command name,
+the list of commands associated with that function name is executed.
+Functions are executed in the context of the
+current shell; no new process is created to interpret
+them (contrast this with the execution of a shell script).
+When a function is executed, the arguments to the
+function become the positional parameters
+during its execution.
+The special parameter
+.B #
+is updated to reflect the change.  Special parameter \fB0\fP
+is unchanged.
+The first element of the
+.SM
+.B FUNCNAME
+variable is set to the name of the function while the function
+is executing.
+.PP
+All other aspects of the shell execution
+environment are identical between a function and its caller
+with these exceptions: the
+.SM
+.B DEBUG
+and
+.B RETURN
+traps (see the description of the
+.B trap
+builtin under
+.SM
+.B SHELL BUILTIN COMMANDS
+below) are not inherited unless the function has been given the
+\fBtrace\fP attribute (see the description of the
+.SM
+.B declare
+builtin below) or the
+\fB\-o functrace\fP shell option has been enabled with
+the \fBset\fP builtin
+(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
+and the
+.SM
+.B ERR
+trap is not inherited unless the \fB\-o errtrace\fP shell option has
+been enabled.
+.PP
+Variables local to the function may be declared with the
+.B local
+builtin command (\fIlocal variables\fP).
+Ordinarily, variables and their values
+are shared between the function and its caller.
+If a variable is declared \fBlocal\fP, the variable's visible scope
+is restricted to that function and its children (including the functions
+it calls).
+.PP
+In the following description, the \fIcurrent scope\fP is a currently-
+executing function.
+Previous scopes consist of that function's caller and so on,
+back to the "global" scope, where the shell is not executing
+any shell function.
+Consequently, a local variable at the current scope is a variable
+declared using the \fBlocal\fP or \fBdeclare\fP builtins in the
+function that is currently executing.
+.PP
+Local variables "shadow" variables with the same name declared at
+previous scopes.
+For instance, a local variable declared in a function
+hides a global variable of the same name: references and assignments
+refer to the local variable, leaving the global variable unmodified.
+When the function returns, the global variable is once again visible.
+.PP
+The shell uses \fIdynamic scoping\fP to control a variable's visibility
+within functions.
+With dynamic scoping, visible variables and their values
+are a result of the sequence of function calls that caused execution
+to reach the current function.
+The value of a variable that a function sees depends
+on its value within its caller, if any, whether that caller is
+the "global" scope or another shell function.
+This is also the value that a local variable
+declaration "shadows", and the value that is restored when the function
+returns.
+.PP
+For example, if a variable \fIvar\fP is declared as local in function
+\fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP,
+references to \fIvar\fP made from within \fIfunc2\fP will resolve to the
+local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable
+named \fIvar\fP.
+.PP
+The \fBunset\fP builtin also acts using the same dynamic scope: if a
+variable is local to the current scope, \fBunset\fP will unset it;
+otherwise the unset will refer to the variable found in any calling scope
+as described above.
+If a variable at the current local scope is unset, it will remain so
+(appearing as unset)
+until it is reset in that scope or until the function returns.
+Once the function returns, any instance of the variable at a previous
+scope will become visible.
+If the unset acts on a variable at a previous scope, any instance of a
+variable with that name that had been shadowed will become visible
+(see below how the \fBlocalvar_unset\fP shell option changes this behavior).
+.PP
+The \fBFUNCNEST\fP variable, if set to a numeric value greater
+than 0, defines a maximum function nesting level.  Function
+invocations that exceed the limit cause the entire command to
+abort.
+.PP
+If the builtin command
+.B return
+is executed in a function, the function completes and
+execution resumes with the next command after the function
+call.
+Any command associated with the \fBRETURN\fP trap is executed
+before execution resumes.
+When a function completes, the values of the
+positional parameters and the special parameter
+.B #
+are restored to the values they had prior to the function's
+execution.
+.PP
+Function names and definitions may be listed with the
+.B \-f
+option to the
+.B declare
+or
+.B typeset
+builtin commands.  The
+.B \-F
+option to
+.B declare
+or
+.B typeset
+will list the function names only
+(and optionally the source file and line number, if the \fBextdebug\fP
+shell option is enabled).
+Functions may be exported so that child shell processes
+(those created when executing a separate shell invocation)
+automatically have them defined with the
+.B \-f
+option to the
+.B export
+builtin.
+A function definition may be deleted using the \fB\-f\fP option to
+the
+.B unset
+builtin.
+.PP
+Functions may be recursive.
+The \fBFUNCNEST\fP variable may be used to limit the depth of the
+function call stack and restrict the number of function invocations.
+By default, no limit is imposed on the number of recursive calls.
+.SH "ARITHMETIC EVALUATION"
+The shell allows arithmetic expressions to be evaluated, under
+certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin
+commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP).
+Evaluation is done in fixed-width integers with no check for overflow,
+though division by 0 is trapped and flagged as an error.
+The operators and their precedence, associativity, and values
+are the same as in the C language.
+The following list of operators is grouped into levels of
+equal-precedence operators.
+The levels are listed in order of decreasing precedence.
+.PP
+.PD 0
+.TP
+.B \fIid\fP++ \fIid\fP\-\-
+variable post-increment and post-decrement
+.TP
+.B \- +
+unary minus and plus
+.TP
+.B ++\fIid\fP \-\-\fIid\fP
+variable pre-increment and pre-decrement
+.TP
+.B ! ~
+logical and bitwise negation
+.TP
+.B **
+exponentiation
+.TP
+.B * / %
+multiplication, division, remainder
+.TP
+.B + \-
+addition, subtraction
+.TP
+.B << >>
+left and right bitwise shifts
+.TP
+.B <= >= < >
+comparison
+.TP
+.B == !=
+equality and inequality
+.TP
+.B &
+bitwise AND
+.TP
+.B ^
+bitwise exclusive OR
+.TP
+.B |
+bitwise OR
+.TP
+.B &&
+logical AND
+.TP
+.B ||
+logical OR
+.TP
+.B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
+conditional operator
+.TP
+.B = *= /= %= += \-= <<= >>= &= ^= |=
+assignment
+.TP
+.B \fIexpr1\fP , \fIexpr2\fP
+comma
+.PD
+.PP
+Shell variables are allowed as operands; parameter expansion is
+performed before the expression is evaluated.
+Within an expression, shell variables may also be referenced by name
+without using the parameter expansion syntax.
+A shell variable that is null or unset evaluates to 0 when referenced
+by name without using the parameter expansion syntax.
+The value of a variable is evaluated as an arithmetic expression
+when it is referenced, or when a variable which has been given the
+\fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value.
+A null value evaluates to 0.
+A shell variable need not have its \fIinteger\fP attribute
+turned on to be used in an expression.
+.PP
+Integer constants follow the C language definition, without suffixes or
+character constants.
+Constants with a leading 0 are interpreted as octal numbers.
+A leading 0x or 0X denotes hexadecimal.
+Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
+is a decimal number between 2 and 64 representing the arithmetic
+base, and \fIn\fP is a number in that base.
+If \fIbase#\fP is omitted, then base 10 is used.
+When specifying \fIn\fP,
+if a non-digit is required,
+the digits greater than 9 are represented by the lowercase letters,
+the uppercase letters, @, and _, in that order.
+If \fIbase\fP is less than or equal to 36, lowercase and uppercase
+letters may be used interchangeably to represent numbers between 10
+and 35.
+.PP
+Operators are evaluated in order of precedence.  Sub-expressions in
+parentheses are evaluated first and may override the precedence
+rules above.
+.SH "CONDITIONAL EXPRESSIONS"
+Conditional expressions are used by the \fB[[\fP compound command and
+the \fBtest\fP and \fB[\fP builtin commands to test file attributes
+and perform string and arithmetic comparisons.
+The \fBtest\fP and \fB[\fP commands determine their behavior based on
+the number of arguments; see the descriptions of those commands for any
+other command-specific actions.
+.PP
+Expressions are formed from the following unary or binary primaries.
+\fBBash\fP handles several filenames specially when they are used in
+expressions.
+If the operating system on which \fBbash\fP is running provides these
+special files, bash will use them; otherwise it will emulate them
+internally with this behavior:
+If any \fIfile\fP argument to one of the primaries is of the form
+\fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked.
+If the \fIfile\fP argument to one of the primaries is one of
+\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file
+descriptor 0, 1, or 2, respectively, is checked.
+.PP
+Unless otherwise specified, primaries that operate on files follow symbolic
+links and operate on the target of the link, rather than the link itself.
+.if t .sp 0.5
+.if n .sp 1
+When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
+lexicographically using the current locale.
+The \fBtest\fP command sorts using ASCII ordering.
+.sp 1
+.PD 0
+.TP
+.B \-a \fIfile\fP
+True if \fIfile\fP exists.
+.TP
+.B \-b \fIfile\fP
+True if \fIfile\fP exists and is a block special file.
+.TP
+.B \-c \fIfile\fP
+True if \fIfile\fP exists and is a character special file.
+.TP
+.B \-d \fIfile\fP
+True if \fIfile\fP exists and is a directory.
+.TP
+.B \-e \fIfile\fP
+True if \fIfile\fP exists.
+.TP
+.B \-f \fIfile\fP
+True if \fIfile\fP exists and is a regular file.
+.TP
+.B \-g \fIfile\fP
+True if \fIfile\fP exists and is set-group-id.
+.TP
+.B \-h \fIfile\fP
+True if \fIfile\fP exists and is a symbolic link.
+.TP
+.B \-k \fIfile\fP
+True if \fIfile\fP exists and its ``sticky'' bit is set.
+.TP
+.B \-p \fIfile\fP
+True if \fIfile\fP exists and is a named pipe (FIFO).
+.TP
+.B \-r \fIfile\fP
+True if \fIfile\fP exists and is readable.
+.TP
+.B \-s \fIfile\fP
+True if \fIfile\fP exists and has a size greater than zero.
+.TP
+.B \-t \fIfd\fP
+True if file descriptor
+.I fd
+is open and refers to a terminal.
+.TP
+.B \-u \fIfile\fP
+True if \fIfile\fP exists and its set-user-id bit is set.
+.TP
+.B \-w \fIfile\fP
+True if \fIfile\fP exists and is writable.
+.TP
+.B \-x \fIfile\fP
+True if \fIfile\fP exists and is executable.
+.TP
+.B \-G \fIfile\fP
+True if \fIfile\fP exists and is owned by the effective group id.
+.TP
+.B \-L \fIfile\fP
+True if \fIfile\fP exists and is a symbolic link.
+.TP
+.B \-N \fIfile\fP
+True if \fIfile\fP exists and has been modified since it was last read.
+.TP
+.B \-O \fIfile\fP
+True if \fIfile\fP exists and is owned by the effective user id.
+.TP
+.B \-S \fIfile\fP
+True if \fIfile\fP exists and is a socket.
+.TP
+\fIfile1\fP \fB\-ef\fP \fIfile2\fP
+True if \fIfile1\fP and \fIfile2\fP refer to the same device and
+inode numbers.
+.TP
+\fIfile1\fP \-\fBnt\fP \fIfile2\fP
+True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
+or if \fIfile1\fP exists and \fPfile2\fP does not.
+.TP
+\fIfile1\fP \-\fBot\fP \fIfile2\fP
+True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
+and \fIfile1\fP does not.
+.TP
+.B \-o \fIoptname\fP
+True if the shell option
+.I optname
+is enabled.
+See the list of options under the description of the
+.B \-o
+option to the
+.B set
+builtin below.
+.TP
+.B \-v \fIvarname\fP
+True if the shell variable
+.I varname
+is set (has been assigned a value).
+.TP
+.B \-R \fIvarname\fP
+True if the shell variable
+.I varname
+is set and is a name reference.
+.TP
+.B \-z \fIstring\fP
+True if the length of \fIstring\fP is zero.
+.TP
+\fIstring\fP
+.PD 0
+.TP
+.B \-n \fIstring\fP
+.PD
+True if the length of
+.I string
+is non-zero.
+.TP
+\fIstring1\fP \fB==\fP \fIstring2\fP
+.PD 0
+.TP
+\fIstring1\fP \fB=\fP \fIstring2\fP
+.PD
+True if the strings are equal.  \fB=\fP should be used
+with the \fBtest\fP command for POSIX conformance.
+When used with the \fB[[\fP command, this performs pattern matching as
+described above (\fBCompound Commands\fP).
+.TP
+\fIstring1\fP \fB!=\fP \fIstring2\fP
+True if the strings are not equal.
+.TP
+\fIstring1\fP \fB<\fP \fIstring2\fP
+True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
+.TP
+\fIstring1\fP \fB>\fP \fIstring2\fP
+True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
+.TP
+.I \fIarg1\fP \fBOP\fP \fIarg2\fP
+.SM
+.B OP
+is one of
+.BR \-eq ,
+.BR \-ne ,
+.BR \-lt ,
+.BR \-le ,
+.BR \-gt ,
+or
+.BR \-ge .
+These arithmetic binary operators return true if \fIarg1\fP
+is equal to, not equal to, less than, less than or equal to,
+greater than, or greater than or equal to \fIarg2\fP, respectively.
+.I Arg1
+and
+.I arg2
+may be positive or negative integers.
+When used with the \fB[[\fP command,
+.I Arg1
+and
+.I Arg2
+are evaluated as arithmetic expressions (see
+.SM
+.B "ARITHMETIC EVALUATION"
+above).
+.PD
+.SH "SIMPLE COMMAND EXPANSION"
+When a simple command is executed, the shell performs the following
+expansions, assignments, and redirections, from left to right, in
+the following order.
+.IP 1.
+The words that the parser has marked as variable assignments (those
+preceding the command name) and redirections are saved for later
+processing.
+.IP 2.
+The words that are not variable assignments or redirections are
+expanded.  If any words remain after expansion, the first word
+is taken to be the name of the command and the remaining words are
+the arguments.
+.IP 3.
+Redirections are performed as described above under
+.SM
+.BR REDIRECTION .
+.IP 4.
+The text after the \fB=\fP in each variable assignment undergoes tilde
+expansion, parameter expansion, command substitution, arithmetic expansion,
+and quote removal before being assigned to the variable.
+.PP
+If no command name results, the variable assignments affect the current
+shell environment.
+In the case of such a command (one that consists only of assignment
+statements and redirections), assignment statements are performed before
+redirections.
+Otherwise, the variables are added to the environment
+of the executed command and do not affect the current shell environment.
+If any of the assignments attempts to assign a value to a readonly variable,
+an error occurs, and the command exits with a non-zero status.
+.PP
+If no command name results, redirections are performed, but do not
+affect the current shell environment.  A redirection error causes the
+command to exit with a non-zero status.
+.PP
+If there is a command name left after expansion, execution proceeds as
+described below.  Otherwise, the command exits.  If one of the expansions
+contained a command substitution, the exit status of the command is
+the exit status of the last command substitution performed.  If there
+were no command substitutions, the command exits with a status of zero.
+.SH "COMMAND EXECUTION"
+After a command has been split into words, if it results in a
+simple command and an optional list of arguments, the following
+actions are taken.
+.PP
+If the command name contains no slashes, the shell attempts to
+locate it.  If there exists a shell function by that name, that
+function is invoked as described above in
+.SM
+.BR FUNCTIONS .
+If the name does not match a function, the shell searches for
+it in the list of shell builtins.  If a match is found, that
+builtin is invoked.
+.PP
+If the name is neither a shell function nor a builtin,
+and contains no slashes,
+.B bash
+searches each element of the
+.SM
+.B PATH
+for a directory containing an executable file by that name.
+.B Bash
+uses a hash table to remember the full pathnames of executable
+files (see
+.B hash
+under
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+A full search of the directories in
+.SM
+.B PATH
+is performed only if the command is not found in the hash table.
+If the search is unsuccessful, the shell searches for a defined shell
+function named \fBcommand_not_found_handle\fP.
+If that function exists, it is invoked in a separate execution environment
+with the original command and
+the original command's arguments as its arguments, and the function's
+exit status becomes the exit status of that subshell.
+If that function is not defined, the shell prints an error
+message and returns an exit status of 127.
+.PP
+If the search is successful, or if the command name contains
+one or more slashes, the shell executes the named program in a
+separate execution environment.
+Argument 0 is set to the name given, and the remaining arguments
+to the command are set to the arguments given, if any.
+.PP
+If this execution fails because the file is not in executable
+format, and the file is not a directory, it is assumed to be
+a \fIshell script\fP, a file
+containing shell commands, and the shell creates a
+new instance of itself
+to execute it.
+This subshell reinitializes itself, so
+that the effect is as if a new shell had been invoked
+to handle the script, with the exception that the locations of
+commands remembered by the parent (see
+.B hash
+below under
+.SM
+\fBSHELL BUILTIN COMMANDS\fP)
+are retained by the child.
+.PP
+If the program is a file beginning with
+.BR #! ,
+the remainder of the first line specifies an interpreter
+for the program.  The shell executes the
+specified interpreter on operating systems that do not
+handle this executable format themselves.  The arguments to the
+interpreter consist of a single optional argument following the
+interpreter name on the first line of the program, followed
+by the name of the program, followed by the command
+arguments, if any.
+.SH COMMAND EXECUTION ENVIRONMENT
+The shell has an \fIexecution environment\fP, which consists of the
+following:
+.IP \(bu
+open files inherited by the shell at invocation, as modified by
+redirections supplied to the \fBexec\fP builtin
+.IP \(bu
+the current working directory as set by \fBcd\fP, \fBpushd\fP, or
+\fBpopd\fP, or inherited by the shell at invocation
+.IP \(bu
+the file creation mode mask as set by \fBumask\fP or inherited from
+the shell's parent
+.IP \(bu
+current traps set by \fBtrap\fP
+.IP \(bu
+shell parameters that are set by variable assignment or with \fBset\fP
+or inherited from the shell's parent in the environment
+.IP \(bu
+shell functions defined during execution or inherited from the shell's
+parent in the environment
+.IP \(bu
+options enabled at invocation (either by default or with command-line
+arguments) or by \fBset\fP
+.IP \(bu
+options enabled by \fBshopt\fP
+.IP \(bu
+shell aliases defined with \fBalias\fP
+.IP \(bu
+various process IDs, including those of background jobs, the value
+of \fB$$\fP, and the value of
+.SM
+.B PPID
+.PP
+When a simple command other than a builtin or shell function
+is to be executed, it
+is invoked in a separate execution environment that consists of
+the following.
+Unless otherwise noted, the values are inherited from the shell.
+.if n .sp 1
+.IP \(bu
+the shell's open files, plus any modifications and additions specified
+by redirections to the command
+.IP \(bu
+the current working directory
+.IP \(bu
+the file creation mode mask
+.IP \(bu
+shell variables and functions marked for export, along with variables
+exported for the command, passed in the environment
+.IP \(bu
+traps caught by the shell are reset to the values inherited from the
+shell's parent, and traps ignored by the shell are ignored
+.PP
+A command invoked in this separate environment cannot affect the
+shell's execution environment.
+.PP
+A \fIsubshell\fP is a copy of the shell process.
+.PP
+Command substitution, commands grouped with parentheses,
+and asynchronous commands are invoked in a
+subshell environment that is a duplicate of the shell environment,
+except that traps caught by the shell are reset to the values
+that the shell inherited from its parent at invocation.  Builtin
+commands that are invoked as part of a pipeline are also executed in a
+subshell environment.  Changes made to the subshell environment
+cannot affect the shell's execution environment.
+.PP
+Subshells spawned to execute command substitutions inherit the value of
+the \fB\-e\fP option from the parent shell.  When not in \fIposix mode\fP,
+\fBbash\fP clears the \fB\-e\fP option in such subshells.
+.PP
+If a command is followed by a \fB&\fP and job control is not active, the
+default standard input for the command is the empty file \fI/dev/null\fP.
+Otherwise, the invoked command inherits the file descriptors of the calling
+shell as modified by redirections.
+.SH ENVIRONMENT
+When a program is invoked it is given an array of strings
+called the
+.IR environment .
+This is a list of
+\fIname\fP\-\fIvalue\fP pairs, of the form
+.IR "name\fR=\fPvalue" .
+.PP
+The shell provides several ways to manipulate the environment.
+On invocation, the shell scans its own environment and
+creates a parameter for each name found, automatically marking
+it for
+.I export
+to child processes.  Executed commands inherit the environment.
+The
+.B export
+and
+.B declare \-x
+commands allow parameters and functions to be added to and
+deleted from the environment.  If the value of a parameter
+in the environment is modified, the new value becomes part
+of the environment, replacing the old.  The environment
+inherited by any executed command consists of the shell's
+initial environment, whose values may be modified in the shell,
+less any pairs removed by the
+.B unset
+command, plus any additions via the
+.B export
+and
+.B declare \-x
+commands.
+.PP
+The environment for any
+.I simple command
+or function may be augmented temporarily by prefixing it with
+parameter assignments, as described above in
+.SM
+.BR PARAMETERS .
+These assignment statements affect only the environment seen
+by that command.
+.PP
+If the
+.B \-k
+option is set (see the
+.B set
+builtin command below), then
+.I all
+parameter assignments are placed in the environment for a command,
+not just those that precede the command name.
+.PP
+When
+.B bash
+invokes an external command, the variable
+.B _
+is set to the full filename of the command and passed to that
+command in its environment.
+.SH "EXIT STATUS"
+The exit status of an executed command is the value returned by the
+\fIwaitpid\fP system call or equivalent function.  Exit statuses
+fall between 0 and 255, though, as explained below, the shell may
+use values above 125 specially.  Exit statuses from shell builtins and
+compound commands are also limited to this range.  Under certain
+circumstances, the shell will use special values to indicate specific
+failure modes.
+.PP
+For the shell's purposes, a command which exits with a
+zero exit status has succeeded.  An exit status of zero
+indicates success.  A non-zero exit status indicates failure.
+When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
+the value of 128+\fIN\fP as the exit status.
+.PP
+If a command is not found, the child process created to
+execute it returns a status of 127.  If a command is found
+but is not executable, the return status is 126.
+.PP
+If a command fails because of an error during expansion or redirection,
+the exit status is greater than zero.
+.PP
+Shell builtin commands return a status of 0 (\fItrue\fP) if
+successful, and non-zero (\fIfalse\fP) if an error occurs
+while they execute.
+All builtins return an exit status of 2 to indicate incorrect usage,
+generally invalid options or missing arguments.
+.PP
+The exit status of the last command is available in the special
+parameter $?.
+.PP
+\fBBash\fP itself returns the exit status of the last command
+executed, unless a syntax error occurs, in which case it exits
+with a non-zero value.  See also the \fBexit\fP builtin
+command below.
+.SH SIGNALS
+When \fBbash\fP is interactive, in the absence of any traps, it ignores
+.SM
+.B SIGTERM
+(so that \fBkill 0\fP does not kill an interactive shell),
+and
+.SM
+.B SIGINT
+is caught and handled (so that the \fBwait\fP builtin is interruptible).
+In all cases, \fBbash\fP ignores
+.SM
+.BR SIGQUIT .
+If job control is in effect,
+.B bash
+ignores
+.SM
+.BR SIGTTIN ,
+.SM
+.BR SIGTTOU ,
+and
+.SM
+.BR SIGTSTP .
+.PP
+Non-builtin commands run by \fBbash\fP have signal handlers
+set to the values inherited by the shell from its parent.
+When job control is not in effect, asynchronous commands
+ignore
+.SM
+.B SIGINT
+and
+.SM
+.B SIGQUIT
+in addition to these inherited handlers.
+Commands run as a result of command substitution ignore the
+keyboard-generated job control signals
+.SM
+.BR SIGTTIN ,
+.SM
+.BR SIGTTOU ,
+and
+.SM
+.BR SIGTSTP .
+.PP
+The shell exits by default upon receipt of a
+.SM
+.BR SIGHUP .
+Before exiting, an interactive shell resends the
+.SM
+.B SIGHUP
+to all jobs, running or stopped.
+Stopped jobs are sent
+.SM
+.B SIGCONT
+to ensure that they receive the
+.SM
+.BR SIGHUP .
+To prevent the shell from
+sending the signal to a particular job, it should be removed from the
+jobs table with the
+.B disown
+builtin (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below) or marked
+to not receive
+.SM
+.B SIGHUP
+using
+.BR "disown \-h" .
+.PP
+If the
+.B huponexit
+shell option has been set with
+.BR shopt ,
+.B bash
+sends a
+.SM
+.B SIGHUP
+to all jobs when an interactive login shell exits.
+.PP
+If \fBbash\fP is waiting for a command to complete and receives a signal
+for which a trap has been set, the trap will not be executed until
+the command completes.
+When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
+builtin, the reception of a signal for which a trap has been set will
+cause the \fBwait\fP builtin to return immediately with an exit status
+greater than 128, immediately after which the trap is executed.
+.PP
+When job control is not enabled, and \fBbash\fP is waiting for a foreground
+command to complete, the shell receives keyboard-generated signals
+such as
+.SM
+.B SIGINT
+(usually generated by \fB^C\fP) that users commonly intend to send
+to that command.
+This happens because the shell and the command are in the
+same process group as the terminal, and \fB^C\fP sends
+.SM
+.B SIGINT
+to all processes in that process group.
+.PP
+When \fBbash\fP is running without job control enabled and receives 
+.SM
+.B SIGINT
+while waiting for a foreground command, it waits until that foreground
+command terminates and then decides what to do about the
+.SM
+.BR SIGINT :
+.IP 1.
+If the command terminates due to the
+.SM
+.BR SIGINT ,
+\fBbash\fP concludes
+that the user meant to end the entire script, and acts on the
+.SM
+.B SIGINT
+(e.g., by running a
+.SM
+.B SIGINT
+trap or exiting itself);
+.IP 2.
+If the command does not terminate due to
+.SM
+.BR SIGINT ,
+the program handled the
+.SM
+.B SIGINT
+itself and did not treat it as a fatal signal.
+In that case, \fBbash\fP does not treat
+.SM
+.B SIGINT
+as a fatal signal, either, instead assuming that the
+.SM
+.B SIGINT
+was used as part of the program's normal operation
+(e.g., emacs uses it to abort editing
+commands) or deliberately discarded.
+However, \fBbash\fP will run any
+trap set on
+.SM
+.BR SIGINT ,
+as it does with any other trapped signal it
+receives while it is waiting for the foreground command to
+complete, for compatibility.
+.SH "JOB CONTROL"
+.I Job control
+refers to the ability to selectively stop (\fIsuspend\fP)
+the execution of processes and continue (\fIresume\fP)
+their execution at a later point.  A user typically employs
+this facility via an interactive interface supplied jointly
+by the operating system kernel's terminal driver and
+.BR bash .
+.PP
+The shell associates a
+.I job
+with each pipeline.  It keeps a table of currently executing
+jobs, which may be listed with the
+.B jobs
+command.  When
+.B bash
+starts a job asynchronously (in the
+.IR background ),
+it prints a line that looks like:
+.RS
+.PP
+[1] 25647
+.RE
+.PP
+indicating that this job is job number 1 and that the process ID
+of the last process in the pipeline associated with this job is 25647.
+All of the processes in a single pipeline are members of the same job.
+.B Bash
+uses the
+.I job
+abstraction as the basis for job control.
+.PP
+To facilitate the implementation of the user interface to job
+control, the operating system maintains the notion of a \fIcurrent terminal
+process group ID\fP.  Members of this process group (processes whose
+process group ID is equal to the current terminal process group ID)
+receive keyboard-generated signals such as
+.SM
+.BR SIGINT .
+These processes are said to be in the
+.IR foreground .
+.I Background
+processes are those whose process group ID differs from the terminal's;
+such processes are immune to keyboard-generated signals.
+Only foreground processes are allowed to read from or, if the
+user so specifies with \f(CWstty tostop\fP, write to the
+terminal.
+Background processes which attempt to read from (write to when
+\f(CWstty tostop\fP is in effect) the
+terminal are sent a
+.SM
+.B SIGTTIN (SIGTTOU)
+signal by the kernel's terminal driver,
+which, unless caught, suspends the process.
+.PP
+If the operating system on which
+.B bash
+is running supports
+job control,
+.B bash
+contains facilities to use it.
+Typing the
+.I suspend
+character (typically
+.BR ^Z ,
+Control-Z) while a process is running
+causes that process to be stopped and returns control to
+.BR bash .
+Typing the
+.I "delayed suspend"
+character (typically
+.BR ^Y ,
+Control-Y) causes the process to be stopped when it
+attempts to read input from the terminal, and control to
+be returned to
+.BR bash .
+The user may then manipulate the state of this job, using the
+.B bg
+command to continue it in the background, the
+.B fg
+command to continue it in the foreground, or
+the
+.B kill
+command to kill it.  A \fB^Z\fP takes effect immediately,
+and has the additional side effect of causing pending output
+and typeahead to be discarded.
+.PP
+There are a number of ways to refer to a job in the shell.
+The character
+.B %
+introduces a job specification (\fIjobspec\fP).  Job number
+.I n
+may be referred to as
+.BR %n .
+A job may also be referred to using a prefix of the name used to
+start it, or using a substring that appears in its command line.
+For example,
+.B %ce
+refers to a stopped
+job whose command name begins with
+.BR ce .
+If a prefix matches more than one job,
+.B bash
+reports an error.  Using
+.BR %?ce ,
+on the other hand, refers to any job containing the string
+.B ce
+in its command line.  If the substring matches more than one job,
+.B bash
+reports an error.  The symbols
+.B %%
+and
+.B %+
+refer to the shell's notion of the
+.IR "current job" ,
+which is the last job stopped while it was in
+the foreground or started in the background.
+The
+.I "previous job"
+may be referenced using
+.BR %\- .
+If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used
+to refer to that job.
+In output pertaining to jobs (e.g., the output of the
+.B jobs
+command), the current job is always flagged with a
+.BR + ,
+and the previous job with a
+.BR \- .
+A single % (with no accompanying job specification) also refers to the
+current job.
+.PP
+Simply naming a job can be used to bring it into the
+foreground:
+.B %1
+is a synonym for
+\fB``fg %1''\fP,
+bringing job 1 from the background into the foreground.
+Similarly,
+.B ``%1 &''
+resumes job 1 in the background, equivalent to
+\fB``bg %1''\fP.
+.PP
+The shell learns immediately whenever a job changes state.
+Normally,
+.B bash
+waits until it is about to print a prompt before reporting
+changes in a job's status so as to not interrupt
+any other output.  If the
+.B \-b
+option to the
+.B set
+builtin command
+is enabled,
+.B bash
+reports such changes immediately.
+Any trap on
+.SM
+.B SIGCHLD
+is executed for each child that exits.
+.PP
+If an attempt to exit
+.B bash
+is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has
+been enabled using the \fBshopt\fP builtin, running), the shell prints a
+warning message, and, if the \fBcheckjobs\fP option is enabled, lists the
+jobs and their statuses.
+The
+.B jobs
+command may then be used to inspect their status.
+If a second attempt to exit is made without an intervening command,
+the shell does not print another warning, and any stopped
+jobs are terminated.
+.PP
+When the shell is waiting for a job or process using the \fBwait\fP
+builtin, and job control is enabled, \fBwait\fP will return when the
+job changes state. The \fB\-f\fP option causes \fBwait\fP to wait
+until the job or process terminates before returning.
+.SH PROMPTING
+When executing interactively,
+.B bash
+displays the primary prompt
+.SM
+.B PS1
+when it is ready to read a command, and the secondary prompt
+.SM
+.B PS2
+when it needs more input to complete a command.
+.B Bash
+displays
+.SM
+.B PS0
+after it reads a command but before executing it.
+.B Bash
+displays
+.SM
+.B PS4
+as described above
+before tracing each command when the \fB\-x\fP option is enabled.
+.B Bash
+allows these prompt strings to be customized by inserting a number of
+backslash-escaped special characters that are decoded as follows:
+.RS
+.PD 0
+.TP
+.B \ea
+an ASCII bell character (07)
+.TP
+.B \ed
+the date in "Weekday Month Date" format (e.g., "Tue May 26")
+.TP
+.B \eD{\fIformat\fP}
+the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted
+into the prompt string; an empty \fIformat\fP results in a locale-specific
+time representation.  The braces are required
+.TP
+.B \ee
+an ASCII escape character (033)
+.TP
+.B \eh
+the hostname up to the first `.'
+.TP
+.B \eH
+the hostname
+.TP
+.B \ej
+the number of jobs currently managed by the shell
+.TP
+.B \el
+the basename of the shell's terminal device name
+.TP
+.B \en
+newline
+.TP
+.B \er
+carriage return
+.TP
+.B \es
+the name of the shell, the basename of
+.B $0
+(the portion following the final slash)
+.TP
+.B \et
+the current time in 24-hour HH:MM:SS format
+.TP
+.B \eT
+the current time in 12-hour HH:MM:SS format
+.TP
+.B \e@
+the current time in 12-hour am/pm format
+.TP
+.B \eA
+the current time in 24-hour HH:MM format
+.TP
+.B \eu
+the username of the current user
+.TP
+.B \ev
+the version of \fBbash\fP (e.g., 2.00)
+.TP
+.B \eV
+the release of \fBbash\fP, version + patch level (e.g., 2.00.0)
+.TP
+.B \ew
+the value of the \fBPWD\fP shell variable (\fB$PWD\fP),
+with
+.SM
+.B $HOME
+abbreviated with a tilde
+(uses the value of the
+.SM
+.B PROMPT_DIRTRIM
+variable)
+.TP
+.B \eW
+the basename of \fB$PWD\fP,
+with
+.SM
+.B $HOME
+abbreviated with a tilde
+.TP
+.B \e!
+the history number of this command
+.TP
+.B \e#
+the command number of this command
+.TP
+.B \e$
+if the effective UID is 0, a
+.BR # ,
+otherwise a
+.B $
+.TP
+.B \e\fInnn\fP
+the character corresponding to the octal number \fInnn\fP
+.TP
+.B \e\e
+a backslash
+.TP
+.B \e[
+begin a sequence of non-printing characters, which could be used to
+embed a terminal control sequence into the prompt
+.TP
+.B \e]
+end a sequence of non-printing characters
+.PD
+.RE
+.PP
+The command number and the history number are usually different:
+the history number of a command is its position in the history
+list, which may include commands restored from the history file
+(see
+.SM
+.B HISTORY
+below), while the command number is the position in the sequence
+of commands executed during the current shell session.
+After the string is decoded, it is expanded via
+parameter expansion, command substitution, arithmetic
+expansion, and quote removal, subject to the value of the
+.B promptvars
+shell option (see the description of the
+.B shopt
+command under
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+This can have unwanted side effects if escaped portions of the string
+appear within command substitution or contain characters special to
+word expansion.
+.SH READLINE
+This is the library that handles reading input when using an interactive
+shell, unless the
+.B \-\-noediting
+option is given at shell invocation.
+Line editing is also used when using the \fB\-e\fP option to the
+\fBread\fP builtin.
+By default, the line editing commands are similar to those of Emacs.
+A vi-style line editing interface is also available.
+Line editing can be enabled at any time using the
+.B \-o emacs
+or
+.B \-o vi
+options to the
+.B set
+builtin (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+To turn off line editing after the shell is running, use the
+.B +o emacs
+or
+.B +o vi
+options to the
+.B set
+builtin.
+.SS "Readline Notation"
+In this section, the Emacs-style notation is used to denote
+keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
+means Control\-N.  Similarly,
+.I meta
+keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboards
+without a
+.I meta
+key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
+then the
+.I x
+key.  This makes ESC the \fImeta prefix\fP.
+The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
+or press the Escape key
+then hold the Control key while pressing the
+.I x
+key.)
+.PP
+Readline commands may be given numeric
+.IR arguments ,
+which normally act as a repeat count.
+Sometimes, however, it is the sign of the argument that is significant.
+Passing a negative argument to a command that acts in the forward
+direction (e.g., \fBkill\-line\fP) causes that command to act in a
+backward direction.
+Commands whose behavior with arguments deviates from this are noted
+below.
+.PP
+When a command is described as \fIkilling\fP text, the text
+deleted is saved for possible future retrieval
+(\fIyanking\fP).  The killed text is saved in a
+\fIkill ring\fP.  Consecutive kills cause the text to be
+accumulated into one unit, which can be yanked all at once.
+Commands which do not kill text separate the chunks of text
+on the kill ring.
+.SS "Readline Initialization"
+Readline is customized by putting commands in an initialization
+file (the \fIinputrc\fP file).
+The name of this file is taken from the value of the
+.SM
+.B INPUTRC
+variable.  If that variable is unset, the default is
+.IR ~/.inputrc .
+If that file  does not exist or cannot be read, the ultimate default is
+.IR /etc/inputrc .
+When a program which uses the readline library starts up, the
+initialization file is read, and the key bindings and variables
+are set.
+There are only a few basic constructs allowed in the
+readline initialization file.
+Blank lines are ignored.
+Lines beginning with a \fB#\fP are comments.
+Lines beginning with a \fB$\fP indicate conditional constructs.
+Other lines denote key bindings and variable settings.
+.PP
+The default key-bindings may be changed with an
+.I inputrc
+file.
+Other programs that use this library may add their own commands
+and bindings.
+.PP
+For example, placing
+.RS
+.PP
+M\-Control\-u: universal\-argument
+.RE
+or
+.RS
+C\-Meta\-u: universal\-argument
+.RE
+into the
+.I inputrc
+would make M\-C\-u execute the readline command
+.IR universal\-argument .
+.PP
+The following symbolic character names are recognized:
+.IR RUBOUT ,
+.IR DEL ,
+.IR ESC ,
+.IR LFD ,
+.IR NEWLINE ,
+.IR RET ,
+.IR RETURN ,
+.IR SPC ,
+.IR SPACE ,
+and
+.IR TAB .
+.PP
+In addition to command names, readline allows keys to be bound
+to a string that is inserted when the key is pressed (a \fImacro\fP).
+.SS "Readline Key Bindings"
+The syntax for controlling key bindings in the
+.I inputrc
+file is simple.  All that is required is the name of the
+command or the text of a macro and a key sequence to which
+it should be bound.  The name may be specified in one of two ways:
+as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
+prefixes, or as a key sequence.
+.PP
+When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
+.I keyname
+is the name of a key spelled out in English.  For example:
+.sp
+.RS
+Control-u: universal\-argument
+.br
+Meta-Rubout: backward-kill-word
+.br
+Control-o: "> output"
+.RE
+.LP
+In the above example,
+.I C\-u
+is bound to the function
+.BR universal\-argument ,
+.I M\-DEL
+is bound to the function
+.BR backward\-kill\-word ,
+and
+.I C\-o
+is bound to run the macro
+expressed on the right hand side (that is, to insert the text
+.if t \f(CW> output\fP
+.if n ``> output''
+into the line).
+.PP
+In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
+.B keyseq
+differs from
+.B keyname
+above in that strings denoting
+an entire key sequence may be specified by placing the sequence
+within double quotes.  Some GNU Emacs style key escapes can be
+used, as in the following example, but the symbolic character names
+are not recognized.
+.sp
+.RS
+"\eC\-u": universal\-argument
+.br
+"\eC\-x\eC\-r": re\-read\-init\-file
+.br
+"\ee[11~": "Function Key 1"
+.RE
+.PP
+In this example,
+.I C\-u
+is again bound to the function
+.BR universal\-argument .
+.I "C\-x C\-r"
+is bound to the function
+.BR re\-read\-init\-file ,
+and
+.I "ESC [ 1 1 ~"
+is bound to insert the text
+.if t \f(CWFunction Key 1\fP.
+.if n ``Function Key 1''.
+.PP
+The full set of GNU Emacs style escape sequences is
+.RS
+.PD 0
+.TP
+.B \eC\-
+control prefix
+.TP
+.B \eM\-
+meta prefix
+.TP
+.B \ee
+an escape character
+.TP
+.B \e\e
+backslash
+.TP
+.B \e"
+literal "
+.TP
+.B \e\(aq
+literal \(aq
+.RE
+.PD
+.PP
+In addition to the GNU Emacs style escape sequences, a second
+set of backslash escapes is available:
+.RS
+.PD 0
+.TP
+.B \ea
+alert (bell)
+.TP
+.B \eb
+backspace
+.TP
+.B \ed
+delete
+.TP
+.B \ef
+form feed
+.TP
+.B \en
+newline
+.TP
+.B \er
+carriage return
+.TP
+.B \et
+horizontal tab
+.TP
+.B \ev
+vertical tab
+.TP
+.B \e\fInnn\fP
+the eight-bit character whose value is the octal value \fInnn\fP
+(one to three digits)
+.TP
+.B \ex\fIHH\fP
+the eight-bit character whose value is the hexadecimal value \fIHH\fP
+(one or two hex digits)
+.RE
+.PD
+.PP
+When entering the text of a macro, single or double quotes must
+be used to indicate a macro definition.
+Unquoted text is assumed to be a function name.
+In the macro body, the backslash escapes described above are expanded.
+Backslash will quote any other character in the macro text,
+including " and \(aq.
+.PP
+.B Bash
+allows the current readline key bindings to be displayed or modified
+with the
+.B bind
+builtin command.  The editing mode may be switched during interactive
+use by using the
+.B \-o
+option to the
+.B set
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.SS "Readline Variables"
+Readline has variables that can be used to further customize its
+behavior.  A variable may be set in the
+.I inputrc
+file with a statement of the form
+.RS
+.PP
+\fBset\fP \fIvariable\-name\fP \fIvalue\fP
+.RE
+or using the \fBbind\fP builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).
+.PP
+Except where noted, readline variables can take the values
+.B On
+or
+.B Off
+(without regard to case).
+Unrecognized variable names are ignored.
+When a variable value is read, empty or null values, "on" (case-insensitive),
+and "1" are equivalent to \fBOn\fP.  All other values are equivalent to
+\fBOff\fP.
+The variables and their default values are:
+.PP
+.PD 0
+.TP
+.B active\-region\-start\-color   
+A string variable that controls the text color and background when displaying
+the text in the active region (see the description of
+\fBenable\-active\-region\fP below).
+This string must not take up any physical character positions on the display,
+so it should consist only of terminal escape sequences.
+It is output to the terminal before displaying the text in the active region.
+This variable is reset to the default value whenever the terminal type changes.
+The default value is the string that puts the terminal in standout mode,
+as obtained from the terminal's terminfo description.
+A sample value might be \f(CW"\ee[01;33m"\fP.
+.TP
+.B active\-region\-end\-color     
+A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP 
+and restores "normal" terminal display appearance after displaying text
+in the active region.
+This string must not take up any physical character positions on the display,
+so it should consist only of terminal escape sequences.
+It is output to the terminal after displaying the text in the active region.
+This variable is reset to the default value whenever the terminal type changes.
+The default value is the string that restores the terminal from standout mode,
+as obtained from the terminal's terminfo description.
+A sample value might be \f(CW"\ee[0m"\fP.
+.TP
+.B bell\-style (audible)
+Controls what happens when readline wants to ring the terminal bell.
+If set to \fBnone\fP, readline never rings the bell.  If set to
+\fBvisible\fP, readline uses a visible bell if one is available.
+If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
+.TP
+.B bind\-tty\-special\-chars (On)
+If set to \fBOn\fP, readline attempts to bind the control characters
+treated specially by the kernel's terminal driver to their readline
+equivalents.
+.TP
+.B blink\-matching\-paren (Off)
+If set to \fBOn\fP, readline attempts to briefly move the cursor to an
+opening parenthesis when a closing parenthesis is inserted.
+.TP
+.B colored\-completion\-prefix (Off)
+If set to \fBOn\fP, when listing completions, readline displays the
+common prefix of the set of possible completions using a different color.
+The color definitions are taken from the value of the \fBLS_COLORS\fP
+environment variable.
+If there is a color definition in \fB$LS_COLORS\fP for the custom suffix
+"readline-colored-completion-prefix", readline uses this color for
+the common prefix instead of its default.
+.TP
+.B colored\-stats (Off)
+If set to \fBOn\fP, readline displays possible completions using different
+colors to indicate their file type.
+The color definitions are taken from the value of the \fBLS_COLORS\fP
+environment variable.
+.TP
+.B comment\-begin (``#'')
+The string that is inserted when the readline
+.B insert\-comment
+command is executed.
+This command is bound to
+.B M\-#
+in emacs mode and to
+.B #
+in vi command mode.
+.TP
+.B completion\-display\-width (\-1)
+The number of screen columns used to display possible matches
+when performing completion.
+The value is ignored if it is less than 0 or greater than the terminal
+screen width.
+A value of 0 will cause matches to be displayed one per line.
+The default value is \-1.
+.TP
+.B completion\-ignore\-case (Off)
+If set to \fBOn\fP, readline performs filename matching and completion
+in a case\-insensitive fashion.
+.TP
+.B completion\-map\-case (Off)
+If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
+treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
+performing case\-insensitive filename matching and completion.
+.TP
+.B completion\-prefix\-display\-length (0)
+The length in characters of the common prefix of a list of possible
+completions that is displayed without modification.  When set to a
+value greater than zero, common prefixes longer than this value are
+replaced with an ellipsis when displaying possible completions.
+.TP
+.B completion\-query\-items (100)
+This determines when the user is queried about viewing
+the number of possible completions
+generated by the \fBpossible\-completions\fP command.
+It may be set to any integer value greater than or equal to zero.
+If the number of possible completions is greater than
+or equal to the value of this variable,
+readline will ask whether or not the user wishes to view them;
+otherwise they are simply listed on the terminal.
+A zero value means readline should never ask; negative values are
+treated as zero.
+.TP
+.B convert\-meta (On)
+If set to \fBOn\fP, readline will convert characters with the
+eighth bit set to an ASCII key sequence
+by stripping the eighth bit and prefixing an
+escape character (in effect, using escape as the \fImeta prefix\fP).
+The default is \fIOn\fP, but readline will set it to \fIOff\fP if the
+locale contains eight-bit characters.
+This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
+may change if the locale is changed.
+.TP
+.B disable\-completion (Off)
+If set to \fBOn\fP, readline will inhibit word completion.  Completion
+characters will be inserted into the line as if they had been
+mapped to \fBself-insert\fP.
+.TP
+.B echo\-control\-characters (On)
+When set to \fBOn\fP, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.
+.TP
+.B editing\-mode (emacs)
+Controls whether readline begins with a set of key bindings similar
+to \fIEmacs\fP or \fIvi\fP.
+.B editing\-mode
+can be set to either
+.B emacs
+or
+.BR vi .
+.TP
+.B emacs\-mode\-string (@)
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
+this string is displayed immediately before the last line of the primary
+prompt when emacs editing mode is active.  The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+.TP
+.B enable\-active\-region (On)
+The \fIpoint\fP is the current cursor position, and \fImark\fP refers  
+to a saved cursor position.   
+The text between the point and mark is referred to as the \fIregion\fP.  
+When this variable is set to \fIOn\fP, readline allows certain commands
+to designate the region as \fIactive\fP.  
+When the region is active, readline highlights the text in the region using
+the value of the \fBactive\-region\-start\-color\fP, which defaults to the
+string that enables
+the terminal's standout mode.
+The active region shows the text inserted by bracketed-paste and any
+matching text found by incremental and non-incremental history searches.
+.TP
+.B enable\-bracketed\-paste (On)
+When set to \fBOn\fP, readline configures the terminal to insert each
+paste into the editing buffer as a single string of characters, instead
+of treating each character as if it had been read from the keyboard.
+This prevents readline from executing any editing commands bound to key
+sequences appearing in the pasted text.
+.TP
+.B enable\-keypad (Off)
+When set to \fBOn\fP, readline will try to enable the application
+keypad when it is called.  Some systems need this to enable the
+arrow keys.
+.TP
+.B enable\-meta\-key (On)
+When set to \fBOn\fP, readline will try to enable any meta modifier
+key the terminal claims to support when it is called.  On many terminals,
+the meta key is used to send eight-bit characters.
+.TP
+.B expand\-tilde (Off)
+If set to \fBOn\fP, tilde expansion is performed when readline
+attempts word completion.
+.TP
+.B history\-preserve\-point (Off)
+If set to \fBOn\fP, the history code attempts to place point at the
+same location on each history line retrieved with \fBprevious-history\fP
+or \fBnext-history\fP.
+.TP
+.B history\-size (unset)
+Set the maximum number of history entries saved in the history list.
+If set to zero, any existing history entries are deleted and no new entries
+are saved.
+If set to a value less than zero, the number of history entries is not
+limited.
+By default, the number of history entries is set to the value of the
+\fBHISTSIZE\fP shell variable.
+If an attempt is made to set \fIhistory\-size\fP to a non-numeric value,
+the maximum number of history entries will be set to 500.
+.TP
+.B horizontal\-scroll\-mode (Off)
+When set to \fBOn\fP, makes readline use a single line for display,
+scrolling the input horizontally on a single screen line when it
+becomes longer than the screen width rather than wrapping to a new line.
+This setting is automatically enabled for terminals of height 1.
+.TP
+.B input\-meta (Off)
+If set to \fBOn\fP, readline will enable eight-bit input (that is,
+it will not strip the eighth bit from the characters it reads),
+regardless of what the terminal claims it can support.  The name
+.B meta\-flag
+is a synonym for this variable.
+The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
+locale contains eight-bit characters.
+This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
+may change if the locale is changed.
+.TP
+.B isearch\-terminators (``C\-[C\-J'')
+The string of characters that should terminate an incremental
+search without subsequently executing the character as a command.
+If this variable has not been given a value, the characters
+\fIESC\fP and \fIC\-J\fP will terminate an incremental search.
+.TP
+.B keymap (emacs)
+Set the current readline keymap.  The set of valid keymap names is
+\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
+vi\-command\fP, and
+.IR vi\-insert .
+\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
+equivalent to \fIemacs\-standard\fP.  The default value is
+.IR emacs ;
+the value of
+.B editing\-mode
+also affects the default keymap.
+.TP
+.B keyseq\-timeout (500)
+Specifies the duration \fIreadline\fP will wait for a character when reading an
+ambiguous key sequence (one that can form a complete key sequence using
+the input read so far, or can take additional input to complete a longer
+key sequence).
+If no input is received within the timeout, \fIreadline\fP will use the shorter
+but complete key sequence.
+The value is specified in milliseconds, so a value of 1000 means that
+\fIreadline\fP will wait one second for additional input.
+If this variable is set to a value less than or equal to zero, or to a
+non-numeric value, \fIreadline\fP will wait until another key is pressed to
+decide which key sequence to complete.
+.TP
+.B mark\-directories (On)
+If set to \fBOn\fP, completed directory names have a slash
+appended.
+.TP
+.B mark\-modified\-lines (Off)
+If set to \fBOn\fP, history lines that have been modified are displayed
+with a preceding asterisk (\fB*\fP).
+.TP
+.B mark\-symlinked\-directories (Off)
+If set to \fBOn\fP, completed names which are symbolic links to directories
+have a slash appended (subject to the value of
+\fBmark\-directories\fP).
+.TP
+.B match\-hidden\-files (On)
+This variable, when set to \fBOn\fP, causes readline to match files whose
+names begin with a `.' (hidden files) when performing filename
+completion.
+If set to \fBOff\fP, the leading `.' must be
+supplied by the user in the filename to be completed.
+.TP
+.B menu\-complete\-display\-prefix (Off)
+If set to \fBOn\fP, menu completion displays the common prefix of the
+list of possible completions (which may be empty) before cycling through
+the list.
+.TP
+.B output\-meta (Off)
+If set to \fBOn\fP, readline will display characters with the
+eighth bit set directly rather than as a meta-prefixed escape
+sequence.
+The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
+locale contains eight-bit characters.
+This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
+may change if the locale is changed.
+.TP
+.B page\-completions (On)
+If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
+to display a screenful of possible completions at a time.
+.TP
+.B print\-completions\-horizontally (Off)
+If set to \fBOn\fP, readline will display completions with matches
+sorted horizontally in alphabetical order, rather than down the screen.
+.TP
+.B revert\-all\-at\-newline (Off)
+If set to \fBOn\fP, readline will undo all changes to history lines
+before returning when \fBaccept\-line\fP is executed.  By default,
+history lines may be modified and retain individual undo lists across
+calls to \fBreadline\fP.
+.TP
+.B show\-all\-if\-ambiguous (Off)
+This alters the default behavior of the completion functions.  If
+set to
+.BR On ,
+words which have more than one possible completion cause the
+matches to be listed immediately instead of ringing the bell.
+.TP
+.B show\-all\-if\-unmodified (Off)
+This alters the default behavior of the completion functions in
+a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
+If set to
+.BR On ,
+words which have more than one possible completion without any
+possible partial completion (the possible completions don't share
+a common prefix) cause the matches to be listed immediately instead
+of ringing the bell.
+.TP
+.B show\-mode\-in\-prompt (Off)
+If set to \fBOn\fP, add a string to the beginning of the prompt
+indicating the editing mode: emacs, vi command, or vi insertion.
+The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
+.TP
+.B skip\-completed\-text (Off)
+If set to \fBOn\fP, this alters the default completion behavior when
+inserting a single match into the line.  It's only active when
+performing completion in the middle of a word.  If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+.TP
+.B vi\-cmd\-mode\-string ((cmd))
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
+this string is displayed immediately before the last line of the primary
+prompt when vi editing mode is active and in command mode.
+The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+.TP
+.B vi\-ins\-mode\-string ((ins))
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
+this string is displayed immediately before the last line of the primary
+prompt when vi editing mode is active and in insertion mode.
+The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+.TP
+.B visible\-stats (Off)
+If set to \fBOn\fP, a character denoting a file's type as reported
+by \fIstat\fP(2) is appended to the filename when listing possible
+completions.
+.PD
+.SS "Readline Conditional Constructs"
+Readline implements a facility similar in spirit to the conditional
+compilation features of the C preprocessor which allows key
+bindings and variable settings to be performed as the result
+of tests.  There are four parser directives used.
+.IP \fB$if\fP
+The
+.B $if
+construct allows bindings to be made based on the
+editing mode, the terminal being used, or the application using
+readline.  The text of the test, after any comparison operator,
+ extends to the end of the line;
+unless otherwise noted, no characters are required to isolate it.
+.RS
+.IP \fBmode\fP
+The \fBmode=\fP form of the \fB$if\fP directive is used to test
+whether readline is in emacs or vi mode.
+This may be used in conjunction
+with the \fBset keymap\fP command, for instance, to set bindings in
+the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
+readline is starting out in emacs mode.
+.IP \fBterm\fP
+The \fBterm=\fP form may be used to include terminal-specific
+key bindings, perhaps to bind the key sequences output by the
+terminal's function keys.  The word on the right side of the
+.B =
+is tested against both the full name of the terminal and the portion
+of the terminal name before the first \fB\-\fP.  This allows
+.I sun
+to match both
+.I sun
+and
+.IR sun\-cmd ,
+for instance.
+.IP \fBversion\fP
+The \fBversion\fP test may be used to perform comparisons against
+specific readline versions.
+The \fBversion\fP expands to the current readline version.
+The set of comparison operators includes
+.BR = ,
+(and
+.BR == ),
+.BR != ,
+.BR <= ,
+.BR >= ,
+.BR < ,
+and
+.BR > .
+The version number supplied on the right side of the operator consists
+of a major version number, an optional decimal point, and an optional
+minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
+is assumed to be \fB0\fP.
+The operator may be separated from the string \fBversion\fP
+and from the version number argument by whitespace.
+.IP \fBapplication\fP
+The \fBapplication\fP construct is used to include
+application-specific settings.  Each program using the readline
+library sets the \fIapplication name\fP, and an initialization
+file can test for a particular value.
+This could be used to bind key sequences to functions useful for
+a specific program.  For instance, the following command adds a
+key sequence that quotes the current or previous word in \fBbash\fP:
+.sp 1
+.RS
+.nf
+\fB$if\fP Bash
+# Quote the current or previous word
+"\eC\-xq": "\eeb\e"\eef\e""
+\fB$endif\fP
+.fi
+.RE
+.IP \fIvariable\fP
+The \fIvariable\fP construct provides simple equality tests for readline
+variables and values.
+The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
+The variable name must be separated from the comparison operator by
+whitespace; the operator may be separated from the value on the right hand
+side by whitespace.
+Both string and boolean variables may be tested. Boolean variables must be
+tested against the values \fIon\fP and \fIoff\fP.
+.RE
+.IP \fB$endif\fP
+This command, as seen in the previous example, terminates an
+\fB$if\fP command.
+.IP \fB$else\fP
+Commands in this branch of the \fB$if\fP directive are executed if
+the test fails.
+.IP \fB$include\fP
+This directive takes a single filename as an argument and reads commands
+and bindings from that file.  For example, the following directive
+would read \fI/etc/inputrc\fP:
+.sp 1
+.RS
+.nf
+\fB$include\fP \^ \fI/etc/inputrc\fP
+.fi
+.RE
+.SS Searching
+Readline provides commands for searching through the command history
+(see
+.SM
+.B HISTORY
+below) for lines containing a specified string.
+There are two search modes:
+.I incremental
+and
+.IR non-incremental .
+.PP
+Incremental searches begin before the user has finished typing the
+search string.
+As each character of the search string is typed, readline displays
+the next entry from the history matching the string typed so far.
+An incremental search requires only as many characters as needed to
+find the desired history entry.
+The characters present in the value of the \fBisearch-terminators\fP
+variable are used to terminate an incremental search.
+If that variable has not been assigned a value the Escape and
+Control-J characters will terminate an incremental search.
+Control-G will abort an incremental search and restore the original
+line.
+When the search is terminated, the history entry containing the
+search string becomes the current line.
+.PP
+To find other matching entries in the history list, type Control-S or
+Control-R as appropriate.
+This will search backward or forward in the history for the next
+entry matching the search string typed so far.
+Any other key sequence bound to a readline command will terminate
+the search and execute that command.
+For instance, a \fInewline\fP will terminate the search and accept
+the line, thereby executing the command from the history list.
+.PP
+Readline remembers the last incremental search string.  If two
+Control-Rs are typed without any intervening characters defining a
+new search string, any remembered search string is used.
+.PP
+Non-incremental searches read the entire search string before starting
+to search for matching history lines.  The search string may be
+typed by the user or be part of the contents of the current line.
+.SS "Readline Command Names"
+The following is a list of the names of the commands and the default
+key sequences to which they are bound.
+Command names without an accompanying key sequence are unbound by default.
+In the following descriptions, \fIpoint\fP refers to the current cursor
+position, and \fImark\fP refers to a cursor position saved by the
+\fBset\-mark\fP command.
+The text between the point and mark is referred to as the \fIregion\fP.
+.SS Commands for Moving
+.PD 0
+.TP
+.B beginning\-of\-line (C\-a)
+Move to the start of the current line.
+.TP
+.B end\-of\-line (C\-e)
+Move to the end of the line.
+.TP
+.B forward\-char (C\-f)
+Move forward a character.
+.TP
+.B backward\-char (C\-b)
+Move back a character.
+.TP
+.B forward\-word (M\-f)
+Move forward to the end of the next word.  Words are composed of
+alphanumeric characters (letters and digits).
+.TP
+.B backward\-word (M\-b)
+Move back to the start of the current or previous word.
+Words are composed of alphanumeric characters (letters and digits).
+.TP
+.B shell\-forward\-word
+Move forward to the end of the next word.
+Words are delimited by non-quoted shell metacharacters.
+.TP
+.B shell\-backward\-word
+Move back to the start of the current or previous word.
+Words are delimited by non-quoted shell metacharacters.
+.TP
+.B previous\-screen\-line
+Attempt to move point to the same physical screen column on the previous
+physical screen line. This will not have the desired effect if the current
+readline line does not take up more than one physical line or if point is not
+greater than the length of the prompt plus the screen width.
+.TP
+.B next\-screen\-line
+Attempt to move point to the same physical screen column on the next
+physical screen line. This will not have the desired effect if the current
+readline line does not take up more than one physical line or if the length
+of the current readline line is not greater than the length of the prompt
+plus the screen width.
+.TP
+.B clear\-display (M\-C\-l)
+Clear the screen and, if possible, the terminal's scrollback buffer,
+then redraw the current line,
+leaving the current line at the top of the screen.
+.TP
+.B clear\-screen (C\-l)
+Clear the screen,
+then redraw the current line,
+leaving the current line at the top of the screen.
+With an argument, refresh the current line without clearing the
+screen.
+.TP
+.B redraw\-current\-line
+Refresh the current line.
+.PD
+.SS Commands for Manipulating the History
+.PD 0
+.TP
+.B accept\-line (Newline, Return)
+Accept the line regardless of where the cursor is.  If this line is
+non-empty, add it to the history list according to the state of the
+.SM
+.B HISTCONTROL
+variable.  If the line is a modified history
+line, then restore the history line to its original state.
+.TP
+.B previous\-history (C\-p)
+Fetch the previous command from the history list, moving back in
+the list.
+.TP
+.B next\-history (C\-n)
+Fetch the next command from the history list, moving forward in the
+list.
+.TP
+.B beginning\-of\-history (M\-<)
+Move to the first line in the history.
+.TP
+.B end\-of\-history (M\->)
+Move to the end of the input history, i.e., the line currently being
+entered.
+.TP
+.B operate\-and\-get\-next (C\-o)
+Accept the current line for execution and fetch the next line
+relative to the current line from the history for editing.
+A numeric argument, if supplied, specifies the history entry to use instead
+of the current line.
+.TP
+.B
+fetch\-history
+With a numeric argument, fetch that entry from the history list
+and make it the current line.
+Without an argument, move back to the first entry in the history list.
+.TP
+.B reverse\-search\-history (C\-r)
+Search backward starting at the current line and moving `up' through
+the history as necessary.  This is an incremental search.
+.TP
+.B forward\-search\-history (C\-s)
+Search forward starting at the current line and moving `down' through
+the history as necessary.  This is an incremental search.
+.TP
+.B non\-incremental\-reverse\-search\-history (M\-p)
+Search backward through the history starting at the current line
+using a non-incremental search for a string supplied by the user.
+.TP
+.B non\-incremental\-forward\-search\-history (M\-n)
+Search forward through the history using a non-incremental search for
+a string supplied by the user.
+.TP
+.B history\-search\-forward
+Search forward through the history for the string of characters
+between the start of the current line and the point.
+This is a non-incremental search.
+.TP
+.B history\-search\-backward
+Search backward through the history for the string of characters
+between the start of the current line and the point.
+This is a non-incremental search.
+.TP
+.B history\-substring\-search\-backward
+Search backward through the history for the string of characters
+between the start of the current line and the current cursor
+position (the \fIpoint\fP).
+The search string may match anywhere in a history line.
+This is a non-incremental search.
+.TP
+.B history\-substring\-search\-forward
+Search forward through the history for the string of characters
+between the start of the current line and the point.
+The search string may match anywhere in a history line.
+This is a non-incremental search.
+.TP
+.B yank\-nth\-arg (M\-C\-y)
+Insert the first argument to the previous command (usually
+the second word on the previous line) at point.
+With an argument
+.IR n ,
+insert the \fIn\fPth word from the previous command (the words
+in the previous command begin with word 0).  A negative argument
+inserts the \fIn\fPth word from the end of the previous command.
+Once the argument \fIn\fP is computed, the argument is extracted
+as if the "!\fIn\fP" history expansion had been specified.
+.TP
+.B
+yank\-last\-arg (M\-.\^, M\-_\^)
+Insert the last argument to the previous command (the last word of
+the previous history entry).
+With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
+Successive calls to \fByank\-last\-arg\fP move back through the history
+list, inserting the last word (or the word specified by the argument to
+the first call) of each line in turn.
+Any numeric argument supplied to these successive calls determines
+the direction to move through the history.  A negative argument switches
+the direction through the history (back or forward).
+The history expansion facilities are used to extract the last word,
+as if the "!$" history expansion had been specified.
+.TP
+.B shell\-expand\-line (M\-C\-e)
+Expand the line as the shell does.  This
+performs alias and history expansion as well as all of the shell
+word expansions.  See
+.SM
+.B HISTORY EXPANSION
+below for a description of history expansion.
+.TP
+.B history\-expand\-line (M\-^)
+Perform history expansion on the current line.
+See
+.SM
+.B HISTORY EXPANSION
+below for a description of history expansion.
+.TP
+.B magic\-space
+Perform history expansion on the current line and insert a space.
+See
+.SM
+.B HISTORY EXPANSION
+below for a description of history expansion.
+.TP
+.B alias\-expand\-line
+Perform alias expansion on the current line.
+See
+.SM
+.B ALIASES
+above for a description of alias expansion.
+.TP
+.B history\-and\-alias\-expand\-line
+Perform history and alias expansion on the current line.
+.TP
+.B insert\-last\-argument (M\-.\^, M\-_\^)
+A synonym for \fByank\-last\-arg\fP.
+.TP
+.B edit\-and\-execute\-command (C\-x C\-e)
+Invoke an editor on the current command line, and execute the result as shell
+commands.
+\fBBash\fP attempts to invoke
+.SM
+.BR $VISUAL ,
+.SM
+.BR $EDITOR ,
+and \fIemacs\fP as the editor, in that order.
+.PD
+.SS Commands for Changing Text
+.PD 0
+.TP
+.B \fIend\-of\-file\fP (usually C\-d)
+The character indicating end-of-file as set, for example, by
+.if t \f(CWstty\fP.
+.if n ``stty''.
+If this character is read when there are no characters
+on the line, and point is at the beginning of the line, readline
+interprets it as the end of input and returns
+.SM
+.BR EOF .
+.TP
+.B delete\-char (C\-d)
+Delete the character at point.
+If this function is bound to the
+same character as the tty \fBEOF\fP character, as \fBC\-d\fP
+commonly is, see above for the effects.
+.TP
+.B backward\-delete\-char (Rubout)
+Delete the character behind the cursor.  When given a numeric argument,
+save the deleted text on the kill ring.
+.TP
+.B forward\-backward\-delete\-char
+Delete the character under the cursor, unless the cursor is at the
+end of the line, in which case the character behind the cursor is
+deleted.
+.TP
+.B quoted\-insert (C\-q, C\-v)
+Add the next character typed to the line verbatim.  This is
+how to insert characters like \fBC\-q\fP, for example.
+.TP
+.B tab\-insert (C\-v TAB)
+Insert a tab character.
+.TP
+.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
+Insert the character typed.
+.TP
+.B transpose\-chars (C\-t)
+Drag the character before point forward over the character at point,
+moving point forward as well.
+If point is at the end of the line, then this transposes
+the two characters before point.
+Negative arguments have no effect.
+.TP
+.B transpose\-words (M\-t)
+Drag the word before point past the word after point,
+moving point over that word as well.
+If point is at the end of the line, this transposes
+the last two words on the line.
+.TP
+.B upcase\-word (M\-u)
+Uppercase the current (or following) word.  With a negative argument,
+uppercase the previous word, but do not move point.
+.TP
+.B downcase\-word (M\-l)
+Lowercase the current (or following) word.  With a negative argument,
+lowercase the previous word, but do not move point.
+.TP
+.B capitalize\-word (M\-c)
+Capitalize the current (or following) word.  With a negative argument,
+capitalize the previous word, but do not move point.
+.TP
+.B overwrite\-mode
+Toggle overwrite mode.  With an explicit positive numeric argument,
+switches to overwrite mode.  With an explicit non-positive numeric
+argument, switches to insert mode.  This command affects only
+\fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
+Each call to \fIreadline()\fP starts in insert mode.
+In overwrite mode, characters bound to \fBself\-insert\fP replace
+the text at point rather than pushing the text to the right.
+Characters bound to \fBbackward\-delete\-char\fP replace the character
+before point with a space.  By default, this command is unbound.
+.PD
+.SS Killing and Yanking
+.PD 0
+.TP
+.B kill\-line (C\-k)
+Kill the text from point to the end of the line.
+.TP
+.B backward\-kill\-line (C\-x Rubout)
+Kill backward to the beginning of the line.
+.TP
+.B unix\-line\-discard (C\-u)
+Kill backward from point to the beginning of the line.
+The killed text is saved on the kill-ring.
+.\" There is no real difference between this and backward-kill-line
+.TP
+.B kill\-whole\-line
+Kill all characters on the current line, no matter where point is.
+.TP
+.B kill\-word (M\-d)
+Kill from point to the end of the current word, or if between
+words, to the end of the next word.
+Word boundaries are the same as those used by \fBforward\-word\fP.
+.TP
+.B backward\-kill\-word (M\-Rubout)
+Kill the word behind point.
+Word boundaries are the same as those used by \fBbackward\-word\fP.
+.TP
+.B shell\-kill\-word
+Kill from point to the end of the current word, or if between
+words, to the end of the next word.
+Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
+.TP
+.B shell\-backward\-kill\-word
+Kill the word behind point.
+Word boundaries are the same as those used by \fBshell\-backward\-word\fP.
+.TP
+.B unix\-word\-rubout (C\-w)
+Kill the word behind point, using white space as a word boundary.
+The killed text is saved on the kill-ring.
+.TP
+.B unix\-filename\-rubout
+Kill the word behind point, using white space and the slash character
+as the word boundaries.
+The killed text is saved on the kill-ring.
+.TP
+.B delete\-horizontal\-space (M\-\e)
+Delete all spaces and tabs around point.
+.TP
+.B kill\-region
+Kill the text in the current region.
+.TP
+.B copy\-region\-as\-kill
+Copy the text in the region to the kill buffer.
+.TP
+.B copy\-backward\-word
+Copy the word before point to the kill buffer.
+The word boundaries are the same as \fBbackward\-word\fP.
+.TP
+.B copy\-forward\-word
+Copy the word following point to the kill buffer.
+The word boundaries are the same as \fBforward\-word\fP.
+.TP
+.B yank (C\-y)
+Yank the top of the kill ring into the buffer at point.
+.TP
+.B yank\-pop (M\-y)
+Rotate the kill ring, and yank the new top.  Only works following
+.B yank
+or
+.BR yank\-pop .
+.PD
+.SS Numeric Arguments
+.PD 0
+.TP
+.B digit\-argument (M\-0, M\-1, ..., M\-\-)
+Add this digit to the argument already accumulating, or start a new
+argument.  M\-\- starts a negative argument.
+.TP
+.B universal\-argument
+This is another way to specify an argument.
+If this command is followed by one or more digits, optionally with a
+leading minus sign, those digits define the argument.
+If the command is followed by digits, executing
+.B universal\-argument
+again ends the numeric argument, but is otherwise ignored.
+As a special case, if this command is immediately followed by a
+character that is neither a digit nor minus sign, the argument count
+for the next command is multiplied by four.
+The argument count is initially one, so executing this function the
+first time makes the argument count four, a second time makes the
+argument count sixteen, and so on.
+.PD
+.SS Completing
+.PD 0
+.TP
+.B complete (TAB)
+Attempt to perform completion on the text before point.
+.B Bash
+attempts completion treating the text as a variable (if the
+text begins with \fB$\fP), username (if the text begins with
+\fB~\fP), hostname (if the text begins with \fB@\fP), or
+command (including aliases and functions) in turn.  If none
+of these produces a match, filename completion is attempted.
+.TP
+.B possible\-completions (M\-?)
+List the possible completions of the text before point.
+.TP
+.B insert\-completions (M\-*)
+Insert all completions of the text before point
+that would have been generated by
+\fBpossible\-completions\fP.
+.TP
+.B menu\-complete
+Similar to \fBcomplete\fP, but replaces the word to be completed
+with a single match from the list of possible completions.
+Repeated execution of \fBmenu\-complete\fP steps through the list
+of possible completions, inserting each match in turn.
+At the end of the list of completions, the bell is rung
+(subject to the setting of \fBbell\-style\fP)
+and the original text is restored.
+An argument of \fIn\fP moves \fIn\fP positions forward in the list
+of matches; a negative argument may be used to move backward
+through the list.
+This command is intended to be bound to \fBTAB\fP, but is unbound
+by default.
+.TP
+.B menu\-complete\-backward
+Identical to \fBmenu\-complete\fP, but moves backward through the list
+of possible completions, as if \fBmenu\-complete\fP had been given a
+negative argument.  This command is unbound by default.
+.TP
+.B delete\-char\-or\-list
+Deletes the character under the cursor if not at the beginning or
+end of the line (like \fBdelete\-char\fP).
+If at the end of the line, behaves identically to
+\fBpossible\-completions\fP.
+This command is unbound by default.
+.TP
+.B complete\-filename (M\-/)
+Attempt filename completion on the text before point.
+.TP
+.B possible\-filename\-completions (C\-x /)
+List the possible completions of the text before point,
+treating it as a filename.
+.TP
+.B complete\-username (M\-~)
+Attempt completion on the text before point, treating
+it as a username.
+.TP
+.B possible\-username\-completions (C\-x ~)
+List the possible completions of the text before point,
+treating it as a username.
+.TP
+.B complete\-variable (M\-$)
+Attempt completion on the text before point, treating
+it as a shell variable.
+.TP
+.B possible\-variable\-completions (C\-x $)
+List the possible completions of the text before point,
+treating it as a shell variable.
+.TP
+.B complete\-hostname (M\-@)
+Attempt completion on the text before point, treating
+it as a hostname.
+.TP
+.B possible\-hostname\-completions (C\-x @)
+List the possible completions of the text before point,
+treating it as a hostname.
+.TP
+.B complete\-command (M\-!)
+Attempt completion on the text before point, treating
+it as a command name.  Command completion attempts to
+match the text against aliases, reserved words, shell
+functions, shell builtins, and finally executable filenames,
+in that order.
+.TP
+.B possible\-command\-completions (C\-x !)
+List the possible completions of the text before point,
+treating it as a command name.
+.TP
+.B dynamic\-complete\-history (M\-TAB)
+Attempt completion on the text before point, comparing
+the text against lines from the history list for possible
+completion matches.
+.TP
+.B dabbrev\-expand
+Attempt menu completion on the text before point, comparing
+the text against lines from the history list for possible
+completion matches.
+.TP
+.B complete\-into\-braces (M\-{)
+Perform filename completion and insert the list of possible completions
+enclosed within braces so the list is available to the shell (see
+.B Brace Expansion
+above).
+.PD
+.SS Keyboard Macros
+.PD 0
+.TP
+.B start\-kbd\-macro (C\-x (\^)
+Begin saving the characters typed into the current keyboard macro.
+.TP
+.B end\-kbd\-macro (C\-x )\^)
+Stop saving the characters typed into the current keyboard macro
+and store the definition.
+.TP
+.B call\-last\-kbd\-macro (C\-x e)
+Re-execute the last keyboard macro defined, by making the characters
+in the macro appear as if typed at the keyboard.
+.TP
+.B print\-last\-kbd\-macro ()
+Print the last keyboard macro defined in a format suitable for the
+\fIinputrc\fP file.
+.PD
+.SS Miscellaneous
+.PD 0
+.TP
+.B re\-read\-init\-file (C\-x C\-r)
+Read in the contents of the \fIinputrc\fP file, and incorporate
+any bindings or variable assignments found there.
+.TP
+.B abort (C\-g)
+Abort the current editing command and
+ring the terminal's bell (subject to the setting of
+.BR bell\-style ).
+.TP
+.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...)
+If the metafied character \fIx\fP is uppercase, run the command
+that is bound to the corresponding metafied lowercase character.
+The behavior is undefined if \fIx\fP is already lowercase.
+.TP
+.B prefix\-meta (ESC)
+Metafy the next character typed.
+.SM
+.B ESC
+.B f
+is equivalent to
+.BR Meta\-f .
+.TP
+.B undo (C\-_, C\-x C\-u)
+Incremental undo, separately remembered for each line.
+.TP
+.B revert\-line (M\-r)
+Undo all changes made to this line.  This is like executing the
+.B undo
+command enough times to return the line to its initial state.
+.TP
+.B tilde\-expand (M\-&)
+Perform tilde expansion on the current word.
+.TP
+.B set\-mark (C\-@, M\-<space>)
+Set the mark to the point.  If a
+numeric argument is supplied, the mark is set to that position.
+.TP
+.B exchange\-point\-and\-mark (C\-x C\-x)
+Swap the point with the mark.  The current cursor position is set to
+the saved position, and the old cursor position is saved as the mark.
+.TP
+.B character\-search (C\-])
+A character is read and point is moved to the next occurrence of that
+character.  A negative argument searches for previous occurrences.
+.TP
+.B character\-search\-backward (M\-C\-])
+A character is read and point is moved to the previous occurrence of that
+character.  A negative argument searches for subsequent occurrences.
+.TP
+.B skip\-csi\-sequence
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End.  Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC\-[.  If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer.  This is unbound by default,
+but usually bound to ESC\-[.
+.TP
+.B insert\-comment (M\-#)
+Without a numeric argument, the value of the readline
+.B comment\-begin
+variable is inserted at the beginning of the current line.
+If a numeric argument is supplied, this command acts as a toggle: if
+the characters at the beginning of the line do not match the value
+of \fBcomment\-begin\fP, the value is inserted, otherwise
+the characters in \fBcomment\-begin\fP are deleted from the beginning of
+the line.
+In either case, the line is accepted as if a newline had been typed.
+The default value of
+\fBcomment\-begin\fP causes this command to make the current line
+a shell comment.
+If a numeric argument causes the comment character to be removed, the line
+will be executed by the shell.
+.TP
+.B spell\-correct\-word (C\-x s)
+Perform spelling correction on the current word, treating it as a directory
+or filename, in the same way as the \fBcdspell\fP shell option.
+Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
+.TP
+.B glob\-complete\-word (M\-g)
+The word before point is treated as a pattern for pathname expansion,
+with an asterisk implicitly appended.  This pattern is used to
+generate a list of matching filenames for possible completions.
+.TP
+.B glob\-expand\-word (C\-x *)
+The word before point is treated as a pattern for pathname expansion,
+and the list of matching filenames is inserted, replacing the word.
+If a numeric argument is supplied, an asterisk is appended before
+pathname expansion.
+.TP
+.B glob\-list\-expansions (C\-x g)
+The list of expansions that would have been generated by
+.B glob\-expand\-word
+is displayed, and the line is redrawn.
+If a numeric argument is supplied, an asterisk is appended before
+pathname expansion.
+.TP
+.B dump\-functions
+Print all of the functions and their key bindings to the
+readline output stream.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B dump\-variables
+Print all of the settable readline variables and their values to the
+readline output stream.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B dump\-macros
+Print all of the readline key sequences bound to macros and the
+strings they output.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B display\-shell\-version (C\-x C\-v)
+Display version information about the current instance of
+.BR bash .
+.PD
+.SS Programmable Completion
+When word completion is attempted for an argument to a command for
+which a completion specification (a \fIcompspec\fP) has been defined
+using the \fBcomplete\fP builtin (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below), the programmable completion facilities are invoked.
+.PP
+First, the command name is identified.
+If the command word is the empty string (completion attempted at the
+beginning of an empty line), any compspec defined with
+the \fB\-E\fP option to \fBcomplete\fP is used.
+If a compspec has been defined for that command, the
+compspec is used to generate the list of possible completions for the word.
+If the command word is a full pathname, a compspec for the full
+pathname is searched for first.
+If no compspec is found for the full pathname, an attempt is made to
+find a compspec for the portion following the final slash.
+If those searches do not result in a compspec, any compspec defined with
+the \fB\-D\fP option to \fBcomplete\fP is used as the default.
+If there is no default compspec, \fBbash\fP attempts alias expansion
+on the command word as a final resort, and attempts to find a compspec
+for the command word from any successful expansion.
+.PP
+Once a compspec has been found, it is used to generate the list of
+matching words.
+If a compspec is not found, the default \fBbash\fP completion as
+described above under \fBCompleting\fP is performed.
+.PP
+First, the actions specified by the compspec are used.
+Only matches which are prefixed by the word being completed are
+returned.
+When the
+.B \-f
+or
+.B \-d
+option is used for filename or directory name completion, the shell
+variable
+.SM
+.B FIGNORE
+is used to filter the matches.
+.PP
+Any completions specified by a pathname expansion pattern to the
+\fB\-G\fP option are generated next.
+The words generated by the pattern need not match the word
+being completed.
+The
+.SM
+.B GLOBIGNORE
+shell variable is not used to filter the matches, but the
+.SM
+.B FIGNORE
+variable is used.
+.PP
+Next, the string specified as the argument to the \fB\-W\fP option
+is considered.
+The string is first split using the characters in the
+.SM
+.B IFS
+special variable as delimiters.
+Shell quoting is honored.
+Each word is then expanded using
+brace expansion, tilde expansion, parameter and variable expansion,
+command substitution, and arithmetic expansion,
+as described above under
+.SM
+.BR EXPANSION .
+The results are split using the rules described above under
+\fBWord Splitting\fP.
+The results of the expansion are prefix-matched against the word being
+completed, and the matching words become the possible completions.
+.PP
+After these matches have been generated, any shell function or command
+specified with the \fB\-F\fP and \fB\-C\fP options is invoked.
+When the command or function is invoked, the
+.SM
+.BR COMP_LINE ,
+.SM
+.BR COMP_POINT ,
+.SM
+.BR COMP_KEY ,
+and
+.SM
+.B COMP_TYPE
+variables are assigned values as described above under
+\fBShell Variables\fP.
+If a shell function is being invoked, the
+.SM
+.B COMP_WORDS
+and
+.SM
+.B COMP_CWORD
+variables are also set.
+When the function or command is invoked,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
+No filtering of the generated completions against the word being completed
+is performed; the function or command has complete freedom in generating
+the matches.
+.PP
+Any function specified with \fB\-F\fP is invoked first.
+The function may use any of the shell facilities, including the
+\fBcompgen\fP builtin described below, to generate the matches.
+It must put the possible completions in the
+.SM
+.B COMPREPLY
+array variable, one per array element.
+.PP
+Next, any command specified with the \fB\-C\fP option is invoked
+in an environment equivalent to command substitution.
+It should print a list of completions, one per line, to the
+standard output.
+Backslash may be used to escape a newline, if necessary.
+.PP
+After all of the possible completions are generated, any filter
+specified with the \fB\-X\fP option is applied to the list.
+The filter is a pattern as used for pathname expansion; a \fB&\fP
+in the pattern is replaced with the text of the word being completed.
+A literal \fB&\fP may be escaped with a backslash; the backslash
+is removed before attempting a match.
+Any completion that matches the pattern will be removed from the list.
+A leading \fB!\fP negates the pattern; in this case any completion
+not matching the pattern will be removed.
+If the
+.B nocasematch
+shell option is enabled, the match is performed without regard to the case
+of alphabetic characters.
+.PP
+Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP
+options are added to each member of the completion list, and the result is
+returned to the readline completion code as the list of possible
+completions.
+.PP
+If the previously-applied actions do not generate any matches, and the
+\fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
+compspec was defined, directory name completion is attempted.
+.PP
+If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
+compspec was defined, directory name completion is attempted and any
+matches are added to the results of the other actions.
+.PP
+By default, if a compspec is found, whatever it generates is returned
+to the completion code as the full set of possible completions.
+The default \fBbash\fP completions are not attempted, and the readline
+default of filename completion is disabled.
+If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
+the compspec was defined, the \fBbash\fP default completions are attempted
+if the compspec generates no matches.
+If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the
+compspec was defined, readline's default completion will be performed
+if the compspec (and, if attempted, the default \fBbash\fP completions)
+generate no matches.
+.PP
+When a compspec indicates that directory name completion is desired,
+the programmable completion functions force readline to append a slash
+to completed names which are symbolic links to directories, subject to
+the value of the \fBmark\-directories\fP readline variable, regardless
+of the setting of the \fBmark-symlinked\-directories\fP readline variable.
+.PP
+There is some support for dynamically modifying completions.  This is
+most useful when used in combination with a default completion specified
+with \fBcomplete \-D\fP.
+It's possible for shell functions executed as completion
+handlers to indicate that completion should be retried by returning an
+exit status of 124.  If a shell function returns 124, and changes
+the compspec associated with the command on which completion is being
+attempted (supplied as the first argument when the function is executed),
+programmable completion restarts from the beginning, with an
+attempt to find a new compspec for that command.  This allows a set of
+completions to be built dynamically as completion is attempted, rather than
+being loaded all at once.
+.PP
+For instance, assuming that there is a library of compspecs, each kept in a
+file corresponding to the name of the command, the following default
+completion function would load completions dynamically:
+.PP
+\f(CW_completion_loader()
+.br
+{
+.br
+	. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
+.br
+}
+.br
+complete -D -F _completion_loader -o bashdefault -o default
+.br
+\fP
+.SH HISTORY
+When the
+.B \-o history
+option to the
+.B set
+builtin is enabled, the shell provides access to the
+\fIcommand history\fP,
+the list of commands previously typed.
+The value of the
+.SM
+.B HISTSIZE
+variable is used as the
+number of commands to save in a history list.
+The text of the last
+.SM
+.B HISTSIZE
+commands (default 500) is saved.  The shell
+stores each command in the history list prior to parameter and
+variable expansion (see
+.SM
+.B EXPANSION
+above) but after history expansion is performed, subject to the
+values of the shell variables
+.SM
+.B HISTIGNORE
+and
+.SM
+.BR HISTCONTROL .
+.PP
+On startup, the history is initialized from the file named by
+the variable
+.SM
+.B HISTFILE
+(default \fI~/.bash_history\fP).
+The file named by the value of
+.SM
+.B HISTFILE
+is truncated, if necessary, to contain no more than
+the number of lines specified by the value of
+.SM
+.BR HISTFILESIZE .
+If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value,
+or a numeric value less than zero, the history file is not truncated.
+When the history file is read,
+lines beginning with the history comment character followed immediately
+by a digit are interpreted as timestamps for the following history line.
+These timestamps are optionally displayed depending on the value of the
+.SM
+.B HISTTIMEFORMAT
+variable.
+When a shell with history enabled exits, the last
+.SM
+.B $HISTSIZE
+lines are copied from the history list to
+.SM
+.BR $HISTFILE .
+If the
+.B histappend
+shell option is enabled
+(see the description of
+.B shopt
+under
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below), the lines are appended to the history file,
+otherwise the history file is overwritten.
+If
+.SM
+.B HISTFILE
+is unset, or if the history file is unwritable, the history is
+not saved.
+If the
+.SM
+.B HISTTIMEFORMAT
+variable is set, time stamps are written to the history file, marked
+with the history comment character, so
+they may be preserved across shell sessions.
+This uses the history comment character to distinguish timestamps from
+other history lines.
+After saving the history, the history file is truncated
+to contain no more than
+.SM
+.B HISTFILESIZE
+lines.  If
+.SM
+.B HISTFILESIZE
+is unset, or set to null, a non-numeric value,
+or a numeric value less than zero, the history file is not truncated.
+.PP
+The builtin command
+.B fc
+(see
+.SM
+.B SHELL BUILTIN COMMANDS
+below) may be used to list or edit and re-execute a portion of
+the history list.
+The
+.B history
+builtin may be used to display or modify the history list and
+manipulate the history file.
+When using command-line editing, search commands
+are available in each editing mode that provide access to the
+history list.
+.PP
+The shell allows control over which commands are saved on the history
+list.  The
+.SM
+.B HISTCONTROL
+and
+.SM
+.B HISTIGNORE
+variables may be set to cause the shell to save only a subset of the
+commands entered.
+The
+.B cmdhist
+shell option, if enabled, causes the shell to attempt to save each
+line of a multi-line command in the same history entry, adding
+semicolons where necessary to preserve syntactic correctness.
+The
+.B lithist
+shell option causes the shell to save the command with embedded newlines
+instead of semicolons.  See the description of the
+.B shopt
+builtin below under
+.SM
+.B "SHELL BUILTIN COMMANDS"
+for information on setting and unsetting shell options.
+.SH "HISTORY EXPANSION"
+The shell supports a history expansion feature that
+is similar to the history expansion in
+.BR csh .
+This section describes what syntax features are available.  This
+feature is enabled by default for interactive shells, and can be
+disabled using the
+.B +H
+option to the
+.B set
+builtin command (see
+.SM
+.B SHELL BUILTIN COMMANDS
+below).  Non-interactive shells do not perform history expansion
+by default.
+.PP
+History expansions introduce words from the history list into
+the input stream, making it easy to repeat commands, insert the
+arguments to a previous command into the current input line, or
+fix errors in previous commands quickly.
+.PP
+History expansion is performed immediately after a complete line
+is read, before the shell breaks it into words, and is performed
+on each line individually without taking quoting on previous lines into
+account.
+It takes place in two parts.
+The first is to determine which line from the history list
+to use during substitution.
+The second is to select portions of that line for inclusion into
+the current one.
+The line selected from the history is the \fIevent\fP,
+and the portions of that line that are acted upon are \fIwords\fP.
+Various \fImodifiers\fP are available to manipulate the selected words.
+The line is broken into words in the same fashion as when reading input,
+so that several \fImetacharacter\fP-separated words surrounded by
+quotes are considered one word.
+History expansions are introduced by the appearance of the
+history expansion character, which is \^\fB!\fP\^ by default.
+Only backslash (\^\fB\e\fP\^) and single quotes can quote
+the history expansion character, but the history expansion character is
+also treated as quoted if it immediately precedes the closing double quote
+in a double-quoted string.
+.PP
+Several characters inhibit history expansion if found immediately
+following the history expansion character, even if it is unquoted:
+space, tab, newline, carriage return, and \fB=\fP.
+If the \fBextglob\fP shell option is enabled, \fB(\fP will also
+inhibit expansion.
+.PP
+Several shell options settable with the
+.B shopt
+builtin may be used to tailor the behavior of history expansion.
+If the
+.B histverify
+shell option is enabled (see the description of the
+.B shopt
+builtin below), and
+.B readline
+is being used, history substitutions are not immediately passed to
+the shell parser.
+Instead, the expanded line is reloaded into the
+.B readline
+editing buffer for further modification.
+If
+.B readline
+is being used, and the
+.B histreedit
+shell option is enabled, a failed history substitution will be reloaded
+into the
+.B readline
+editing buffer for correction.
+The
+.B \-p
+option to the
+.B history
+builtin command may be used to see what a history expansion will
+do before using it.
+The
+.B \-s
+option to the
+.B history
+builtin may be used to add commands to the end of the history list
+without actually executing them, so that they are available for
+subsequent recall.
+.PP
+The shell allows control of the various characters used by the
+history expansion mechanism (see the description of
+.B histchars
+above under
+.BR "Shell Variables" ).
+The shell uses
+the history comment character to mark history timestamps when
+writing the history file.
+.SS Event Designators
+An event designator is a reference to a command line entry in the
+history list.
+Unless the reference is absolute, events are relative to the current
+position in the history list.
+.PP
+.PD 0
+.TP
+.B !
+Start a history substitution, except when followed by a
+.BR blank ,
+newline, carriage return, =
+or ( (when the \fBextglob\fP shell option is enabled using
+the \fBshopt\fP builtin).
+.TP
+.B !\fIn\fR
+Refer to command line
+.IR n .
+.TP
+.B !\-\fIn\fR
+Refer to the current command minus
+.IR n .
+.TP
+.B !!
+Refer to the previous command.  This is a synonym for `!\-1'.
+.TP
+.B !\fIstring\fR
+Refer to the most recent command preceding the current position in the
+history list starting with
+.IR string .
+.TP
+.B !?\fIstring\fR\fB[?]\fR
+Refer to the most recent command preceding the current position in the
+history list containing
+.IR string .
+The trailing \fB?\fP may be omitted if
+.I string
+is followed immediately by a newline.
+If \fIstring\fP is missing, the string from the most recent search is used;
+it is an error if there is no previous search string.
+.TP
+.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
+Quick substitution.  Repeat the previous command, replacing
+.I string1
+with
+.IR string2 .
+Equivalent to
+``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u''
+(see \fBModifiers\fP below).
+.TP
+.B !#
+The entire command line typed so far.
+.PD
+.SS Word Designators
+Word designators are used to select desired words from the event.
+A
+.B :
+separates the event specification from the word designator.
+It may be omitted if the word designator begins with a
+.BR ^ ,
+.BR $ ,
+.BR * ,
+.BR \- ,
+or
+.BR % .
+Words are numbered from the beginning of the line,
+with the first word being denoted by 0 (zero).
+Words are inserted into the current line separated by single spaces.
+.PP
+.PD 0
+.TP
+.B 0 (zero)
+The zeroth word.  For the shell, this is the command
+word.
+.TP
+.I n
+The \fIn\fRth word.
+.TP
+.B ^
+The first argument.  That is, word 1.
+.TP
+.B $
+The last word.  This is usually the last argument, but will expand to the
+zeroth word if there is only one word in the line.
+.TP
+.B %
+The first word matched by the most recent `?\fIstring\fR?' search,
+if the search string begins with a character that is part of a word.
+.TP
+.I x\fB\-\fPy
+A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
+.TP
+.B *
+All of the words but the zeroth.  This is a synonym
+for `\fI1\-$\fP'.  It is not an error to use
+.B *
+if there is just one
+word in the event; the empty string is returned in that case.
+.TP
+.B x*
+Abbreviates \fIx\-$\fP.
+.TP
+.B x\-
+Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
+If \fBx\fP is missing, it defaults to 0.
+.PD
+.PP
+If a word designator is supplied without an event specification, the
+previous command is used as the event.
+.SS Modifiers
+After the optional word designator, there may appear a sequence of
+one or more of the following modifiers, each preceded by a `:'.
+These modify, or edit, the word or words selected from the history event.
+.PP
+.PD 0
+.TP
+.B h
+Remove a trailing filename component, leaving only the head.
+.TP
+.B t
+Remove all leading filename components, leaving the tail.
+.TP
+.B r
+Remove a trailing suffix of the form \fI.xxx\fP, leaving the
+basename.
+.TP
+.B e
+Remove all but the trailing suffix.
+.TP
+.B p
+Print the new command but do not execute it.
+.TP
+.B q
+Quote the substituted words, escaping further substitutions.
+.TP
+.B x
+Quote the substituted words as with
+.BR q ,
+but break into words at
+.B blanks
+and newlines.
+The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one
+supplied is used.
+.TP
+.B s/\fIold\fP/\fInew\fP/
+Substitute
+.I new
+for the first occurrence of
+.I old
+in the event line.
+Any character may be used as the delimiter in place of /.
+The final delimiter is optional if it is the last character of the
+event line.
+The delimiter may be quoted in
+.I old
+and
+.I new
+with a single backslash.  If & appears in
+.IR new ,
+it is replaced by
+.IR old .
+A single backslash will quote the &.
+If
+.I old
+is null, it is set to the last
+.I old
+substituted, or, if no previous history substitutions took place,
+the last
+.I string
+in a
+.B !?\fIstring\fR\fB[?]\fR
+search.
+If
+.I new
+is null, each matching
+.I old
+is deleted.
+.TP
+.B &
+Repeat the previous substitution.
+.TP
+.B g
+Cause changes to be applied over the entire event line.  This is
+used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
+or `\fB:&\fP'.  If used with
+`\fB:s\fP', any delimiter can be used
+in place of /, and the final delimiter is optional
+if it is the last character of the event line.
+An \fBa\fP may be used as a synonym for \fBg\fP.
+.TP
+.B G
+Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
+in the event line.
+.PD
+.SH "SHELL BUILTIN COMMANDS"
+.\" start of bash_builtins
+.zZ
+.PP
+Unless otherwise noted, each builtin command documented in this
+section as accepting options preceded by
+.B \-
+accepts
+.B \-\-
+to signify the end of the options.
+The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
+do not accept options and do not treat \fB\-\-\fP specially.
+The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
+\fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
+and \fBshift\fP builtins accept and process arguments beginning with
+\fB\-\fP without requiring \fB\-\-\fP.
+Other builtins that accept arguments but are not specified as accepting
+options interpret arguments beginning with \fB\-\fP as invalid options and
+require \fB\-\-\fP to prevent this interpretation.
+.sp .5
+.PD 0
+.TP
+\fB:\fP [\fIarguments\fP]
+.PD
+No effect; the command does nothing beyond expanding
+.I arguments
+and performing any specified
+redirections.
+The return status is zero.
+.TP
+\fB .\| \fP \fIfilename\fP [\fIarguments\fP]
+.PD 0
+.TP
+\fBsource\fP \fIfilename\fP [\fIarguments\fP]
+.PD
+Read and execute commands from
+.I filename
+in the current
+shell environment and return the exit status of the last command
+executed from
+.IR filename .
+If
+.I filename
+does not contain a slash, filenames in
+.SM
+.B PATH
+are used to find the directory containing
+.IR filename ,
+but \fIfilename\fP does not need to be executable.
+The file searched for in
+.SM
+.B PATH
+need not be executable.
+When \fBbash\fP is not in \fIposix mode\fP, it searches
+the current directory if no file is found in
+.SM
+.BR PATH .
+If the
+.B sourcepath
+option to the
+.B shopt
+builtin command is turned off, the
+.SM
+.B PATH
+is not searched.
+If any \fIarguments\fP are supplied, they become the positional
+parameters when \fIfilename\fP is executed.  Otherwise the positional
+parameters are unchanged.
+If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
+\fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
+restored around the call to \fB.\fP, and \fB.\fP unsets the
+\fBDEBUG\fP trap while it executes.
+If \fB\-T\fP is not set, and the sourced file changes
+the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes.
+The return status is the status of the last command exited within
+the script (0 if no commands are executed), and false if
+.I filename
+is not found or cannot be read.
+.TP
+\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+\fBAlias\fP with no arguments or with the
+.B \-p
+option prints the list of aliases in the form
+\fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
+When arguments are supplied, an alias is defined for
+each \fIname\fP whose \fIvalue\fP is given.
+A trailing space in \fIvalue\fP causes the next word to be
+checked for alias substitution when the alias is expanded.
+For each \fIname\fP in the argument list for which no \fIvalue\fP
+is supplied, the name and value of the alias is printed.
+\fBAlias\fP returns true unless a \fIname\fP is given for which
+no alias has been defined.
+.TP
+\fBbg\fP [\fIjobspec\fP ...]
+Resume each suspended job \fIjobspec\fP in the background, as if it
+had been started with
+.BR & .
+If
+.I jobspec
+is not present, the shell's notion of the \fIcurrent job\fP is used.
+.B bg
+.I jobspec
+returns 0 unless run when job control is disabled or, when run with
+job control enabled, any specified \fIjobspec\fP was not found
+or was started without job control.
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
+.PD 0
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
+.TP
+\fBbind\fP \fIreadline-command-line\fP
+.PD
+Display current
+.B readline
+key and function bindings, bind a key sequence to a
+.B readline
+function or macro, or set a
+.B readline
+variable.
+Each non-option argument is a command as it would appear in a
+.B readline
+initialization file such as
+.IR .inputrc ,
+but each binding or command must be passed as a separate argument;
+e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-m \fIkeymap\fP
+Use
+.I keymap
+as the keymap to be affected by the subsequent bindings.
+Acceptable
+.I keymap
+names are
+\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
+vi\-move, vi\-command\fP, and
+.IR vi\-insert .
+\fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also
+a synonym); \fIemacs\fP is
+equivalent to \fIemacs\-standard\fP.
+.TP
+.B \-l
+List the names of all \fBreadline\fP functions.
+.TP
+.B \-p
+Display \fBreadline\fP function names and bindings in such a way
+that they can be re-read.
+.TP
+.B \-P
+List current \fBreadline\fP function names and bindings.
+.TP
+.B \-s
+Display \fBreadline\fP key sequences bound to macros and the strings
+they output in such a way that they can be re-read.
+.TP
+.B \-S
+Display \fBreadline\fP key sequences bound to macros and the strings
+they output.
+.TP
+.B \-v
+Display \fBreadline\fP variable names and values in such a way that they
+can be re-read.
+.TP
+.B \-V
+List current \fBreadline\fP variable names and values.
+.TP
+.B \-f \fIfilename\fP
+Read key bindings from \fIfilename\fP.
+.TP
+.B \-q \fIfunction\fP
+Query about which keys invoke the named \fIfunction\fP.
+.TP
+.B \-u \fIfunction\fP
+Unbind all keys bound to the named \fIfunction\fP.
+.TP
+.B \-r \fIkeyseq\fP
+Remove any current binding for \fIkeyseq\fP.
+.TP
+.B \-x \fIkeyseq\fP:\fIshell\-command\fP
+Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
+entered.
+When \fIshell\-command\fP is executed, the shell sets the
+.SM
+.B READLINE_LINE
+variable to the contents of the \fBreadline\fP line buffer and the
+.SM
+.B READLINE_POINT
+and
+.SM
+.B READLINE_MARK
+variables to the current location of the insertion point and the saved
+insertion point (the mark), respectively.
+The shell assigns any numeric argument the user supplied to the     
+.SM
+.B READLINE_ARGUMENT
+variable.
+If there was no argument, that variable is not set.
+If the executed command changes the value of any of
+.SM
+.BR READLINE_LINE ,
+.SM
+.BR READLINE_POINT ,
+or
+.SM
+.BR READLINE_MARK ,
+those new values will be reflected in the editing state.
+.TP
+.B \-X
+List all key sequences bound to shell commands and the associated commands
+in a format that can be reused as input.
+.PD
+.PP
+The return value is 0 unless an unrecognized option is given or an
+error occurred.
+.RE
+.TP
+\fBbreak\fP [\fIn\fP]
+Exit from within a
+.BR for ,
+.BR while ,
+.BR until ,
+or
+.B select
+loop.  If \fIn\fP is specified, break \fIn\fP levels.
+.I n
+must be \(>= 1.  If
+.I n
+is greater than the number of enclosing loops, all enclosing loops
+are exited.
+The return value is 0 unless \fIn\fP is not greater than or equal to 1.
+.TP
+\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
+Execute the specified shell builtin, passing it
+.IR arguments ,
+and return its exit status.
+This is useful when defining a
+function whose name is the same as a shell builtin,
+retaining the functionality of the builtin within the function.
+The \fBcd\fP builtin is commonly redefined this way.
+The return status is false if
+.I shell\-builtin
+is not a shell builtin command.
+.TP
+\fBcaller\fP [\fIexpr\fP]
+Returns the context of any active subroutine call (a shell function or
+a script executed with the \fB.\fP or \fBsource\fP builtins).
+Without \fIexpr\fP, \fBcaller\fP displays the line number and source
+filename of the current subroutine call.
+If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
+displays the line number, subroutine name, and source file corresponding
+to that position in the current execution call stack.  This extra
+information may be used, for example, to print a stack trace.  The
+current frame is frame 0.
+The return value is 0 unless the shell is not executing a subroutine
+call or \fIexpr\fP does not correspond to a valid position in the
+call stack.
+.TP
+\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP]
+Change the current directory to \fIdir\fP.
+if \fIdir\fP is not supplied, the value of the
+.SM
+.B HOME
+shell variable is the default.
+The variable
+.SM
+.B CDPATH
+defines the search path for the directory containing
+.IR dir :
+each directory name in
+.SM
+.B CDPATH
+is searched for \fIdir\fP.
+Alternative directory names in
+.SM
+.B CDPATH
+are separated by a colon (:).  A null directory name in
+.SM
+.B CDPATH
+is the same as the current directory, i.e., ``\fB.\fP''.  If
+.I dir
+begins with a slash (/),
+then
+.SM
+.B CDPATH
+is not used.  The
+.B \-P
+option causes \fBcd\fP to use the physical directory structure
+by resolving symbolic links while traversing \fIdir\fP and
+before processing instances of \fI..\fP in \fIdir\fP (see also the
+.B \-P
+option to the
+.B set
+builtin command); the
+.B \-L
+option forces symbolic links to be followed by resolving the link
+after processing instances of \fI..\fP in \fIdir\fP.
+If \fI..\fP appears in \fIdir\fP, it is processed by removing the
+immediately previous pathname component from \fIdir\fP, back to a slash
+or the beginning of \fIdir\fP.
+If the
+.B \-e
+option is supplied with
+.BR \-P ,
+and the current working directory cannot be successfully determined
+after a successful directory change, \fBcd\fP will return an unsuccessful
+status.
+On systems that support it, the \fB\-@\fP option presents the extended
+attributes associated with a file as a directory.
+An argument of
+.B \-
+is converted to
+.SM
+.B $OLDPWD
+before the directory change is attempted.
+If a non-empty directory name from
+.SM
+.B CDPATH
+is used, or if
+\fB\-\fP is the first argument, and the directory change is
+successful, the absolute pathname of the new working directory is
+written to the standard output.
+If the directory change is successful, \fBcd\fP sets the value of the
+\fBPWD\fP environment variable to the new directory name, and sets the
+\fBOLDPWD\fP environment variable to the value of the current working
+directory before the change.
+The return value is true if the directory was successfully changed;
+false otherwise.
+.TP
+\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
+Run
+.I command
+with
+.I args
+suppressing the normal shell function lookup.
+Only builtin commands or commands found in the
+.SM
+.B PATH
+are executed.  If the
+.B \-p
+option is given, the search for
+.I command
+is performed using a default value for
+.SM
+.B PATH
+that is guaranteed to find all of the standard utilities.
+If either the
+.B \-V
+or
+.B \-v
+option is supplied, a description of
+.I command
+is printed.  The
+.B \-v
+option causes a single word indicating the command or filename
+used to invoke
+.I command
+to be displayed; the
+.B \-V
+option produces a more verbose description.
+If the
+.B \-V
+or
+.B \-v
+option is supplied, the exit status is 0 if
+.I command
+was found, and 1 if not.  If neither option is supplied and
+an error occurred or
+.I command
+cannot be found, the exit status is 127.  Otherwise, the exit status of the
+.B command
+builtin is the exit status of
+.IR command .
+.TP
+\fBcompgen\fP [\fIoption\fP] [\fIword\fP]
+Generate possible completion matches for \fIword\fP according to
+the \fIoption\fPs, which may be any option accepted by the
+.B complete
+builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write
+the matches to the standard output.
+When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
+set by the programmable completion facilities, while available, will not
+have useful values.
+.sp 1
+The matches will be generated in the same way as if the programmable
+completion code had generated them directly from a completion specification
+with the same flags.
+If \fIword\fP is specified, only those completions matching \fIword\fP
+will be displayed.
+.sp 1
+The return value is true unless an invalid option is supplied, or no
+matches were generated.
+.TP
+\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP]
+.br
+[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
+.PD 0
+.TP
+\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...]
+.PD
+Specify how arguments to each \fIname\fP should be completed.
+If the \fB\-p\fP option is supplied, or if no options are supplied,
+existing completion specifications are printed in a way that allows
+them to be reused as input.
+The \fB\-r\fP option removes a completion specification for
+each \fIname\fP, or, if no \fIname\fPs are supplied, all
+completion specifications.
+The \fB\-D\fP option indicates that other supplied options and actions should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The \fB\-E\fP option indicates that other supplied options and actions should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
+The \fB\-I\fP option indicates that other supplied options and actions should
+apply to completion on the initial non-assignment word on the line, or after
+a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
+name completion.
+If multiple options are supplied, the \fB\-D\fP option takes precedence
+over \fB\-E\fP, and both take precedence over \fB\-I\fP.
+If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
+\fIname\fP arguments are ignored; these completions only apply to the case
+specified by the option.
+.sp 1
+The process of applying these completion specifications when word completion
+is attempted is described
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above under \fBProgrammable Completion\fP.
+.sp 1
+Other options, if specified, have the following meanings.
+The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
+(and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
+should be quoted to protect them from expansion before the
+.B complete
+builtin is invoked.
+.RS
+.PD 0
+.TP 8
+\fB\-o\fP \fIcomp-option\fP
+The \fIcomp-option\fP controls several aspects of the compspec's behavior
+beyond the simple generation of completions.
+\fIcomp-option\fP may be one of:
+.RS
+.TP 8
+.B bashdefault
+Perform the rest of the default \fBbash\fP completions if the compspec
+generates no matches.
+.TP 8
+.B default
+Use readline's default filename completion if the compspec generates
+no matches.
+.TP 8
+.B dirnames
+Perform directory name completion if the compspec generates no matches.
+.TP 8
+.B filenames
+Tell readline that the compspec generates filenames, so it can perform any
+filename\-specific processing (like adding a slash to directory names,
+quoting special characters, or suppressing trailing spaces).
+Intended to be used with shell functions.
+.TP 8
+.B noquote
+Tell readline not to quote the completed words if they are filenames
+(quoting filenames is the default).
+.TP 8
+.B nosort
+Tell readline not to sort the list of possible completions alphabetically.
+.TP 8
+.B nospace
+Tell readline not to append a space (the default) to words completed at
+the end of the line.
+.TP 8
+.B plusdirs
+After any matches defined by the compspec are generated,
+directory name completion is attempted and any
+matches are added to the results of the other actions.
+.RE
+.TP 8
+\fB\-A\fP \fIaction\fP
+The \fIaction\fP may be one of the following to generate a list of possible
+completions:
+.RS
+.TP 8
+.B alias
+Alias names.  May also be specified as \fB\-a\fP.
+.TP 8
+.B arrayvar
+Array variable names.
+.TP 8
+.B binding
+\fBReadline\fP key binding names.
+.TP 8
+.B builtin
+Names of shell builtin commands.  May also be specified as \fB\-b\fP.
+.TP 8
+.B command
+Command names.  May also be specified as \fB\-c\fP.
+.TP 8
+.B directory
+Directory names.  May also be specified as \fB\-d\fP.
+.TP 8
+.B disabled
+Names of disabled shell builtins.
+.TP 8
+.B enabled
+Names of enabled shell builtins.
+.TP 8
+.B export
+Names of exported shell variables.  May also be specified as \fB\-e\fP.
+.TP 8
+.B file
+File names.  May also be specified as \fB\-f\fP.
+.TP 8
+.B function
+Names of shell functions.
+.TP 8
+.B group
+Group names.  May also be specified as \fB\-g\fP.
+.TP 8
+.B helptopic
+Help topics as accepted by the \fBhelp\fP builtin.
+.TP 8
+.B hostname
+Hostnames, as taken from the file specified by the
+.SM
+.B HOSTFILE
+shell variable.
+.TP 8
+.B job
+Job names, if job control is active.  May also be specified as \fB\-j\fP.
+.TP 8
+.B keyword
+Shell reserved words.  May also be specified as \fB\-k\fP.
+.TP 8
+.B running
+Names of running jobs, if job control is active.
+.TP 8
+.B service
+Service names.  May also be specified as \fB\-s\fP.
+.TP 8
+.B setopt
+Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
+.TP 8
+.B shopt
+Shell option names as accepted by the \fBshopt\fP builtin.
+.TP 8
+.B signal
+Signal names.
+.TP 8
+.B stopped
+Names of stopped jobs, if job control is active.
+.TP 8
+.B user
+User names.  May also be specified as \fB\-u\fP.
+.TP 8
+.B variable
+Names of all shell variables.  May also be specified as \fB\-v\fP.
+.RE
+.TP 8
+\fB\-C\fP \fIcommand\fP
+\fIcommand\fP is executed in a subshell environment, and its output is
+used as the possible completions.
+Arguments are passed as with the \fB\-F\fP option.
+.TP 8
+\fB\-F\fP \fIfunction\fP
+The shell function \fIfunction\fP is executed in the current shell
+environment.
+When the function is executed,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
+When it finishes, the possible completions are retrieved from the value
+of the
+.SM
+.B COMPREPLY
+array variable.
+.TP 8
+\fB\-G\fP \fIglobpat\fP
+The pathname expansion pattern \fIglobpat\fP is expanded to generate
+the possible completions.
+.TP 8
+\fB\-P\fP \fIprefix\fP
+\fIprefix\fP is added at the beginning of each possible completion
+after all other options have been applied.
+.TP 8
+\fB\-S\fP \fIsuffix\fP
+\fIsuffix\fP is appended to each possible completion
+after all other options have been applied.
+.TP 8
+\fB\-W\fP \fIwordlist\fP
+The \fIwordlist\fP is split using the characters in the
+.SM
+.B IFS
+special variable as delimiters, and each resultant word is expanded.
+Shell quoting is honored within \fIwordlist\fP,
+in order to provide a
+mechanism for the words to contain shell metacharacters or characters
+in the value of
+.SM
+.BR IFS .
+The possible completions are the members of the resultant list which
+match the word being completed.
+.TP 8
+\fB\-X\fP \fIfilterpat\fP
+\fIfilterpat\fP is a pattern as used for pathname expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+\fIfilterpat\fP is removed from the list.
+A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
+case, any completion not matching \fIfilterpat\fP is removed.
+.PD
+.PP
+The return value is true unless an invalid option is supplied, an option
+other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP
+argument, an attempt is made to remove a completion specification for
+a \fIname\fP for which no specification exists, or
+an error occurs adding a completion specification.
+.RE
+.TP
+\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
+Modify completion options for each \fIname\fP according to the
+\fIoption\fPs, or for the
+currently-executing completion if no \fIname\fPs are supplied.
+If no \fIoption\fPs are given, display the completion options for each
+\fIname\fP or the current completion.
+The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
+builtin described above.
+The \fB\-D\fP option indicates that other supplied options should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The \fB\-E\fP option indicates that other supplied options should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
+The \fB\-I\fP option indicates that other supplied options should
+apply to completion on the initial non-assignment word on the line,
+or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually
+command name completion.
+.sp 1
+The return value is true unless an invalid option is supplied, an attempt
+is made to modify the options for a \fIname\fP for which no completion
+specification exists, or an output error occurs.
+.TP
+\fBcontinue\fP [\fIn\fP]
+Resume the next iteration of the enclosing
+.BR for ,
+.BR while ,
+.BR until ,
+or
+.B select
+loop.
+If
+.I n
+is specified, resume at the \fIn\fPth enclosing loop.
+.I n
+must be \(>= 1.  If
+.I n
+is greater than the number of enclosing loops, the last enclosing loop
+(the ``top-level'' loop) is resumed.
+The return value is 0 unless \fIn\fP is not greater than or equal to 1.
+.TP
+\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+.PD 0
+.TP
+\fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+.PD
+Declare variables and/or give them attributes.
+If no \fIname\fPs are given then display the values of variables.
+The
+.B \-p
+option will display the attributes and values of each
+.IR name .
+When
+.B \-p
+is used with \fIname\fP arguments, additional options,
+other than \fB\-f\fP and \fB\-F\fP, are ignored.
+When
+.B \-p
+is supplied without \fIname\fP arguments, it will display the attributes
+and values of all variables having the attributes specified by the
+additional options.
+If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display
+the attributes and values of all shell variables.  The \fB\-f\fP option
+will restrict the display to shell functions.
+The
+.B \-F
+option inhibits the display of function definitions; only the
+function name and attributes are printed.
+If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
+the source file name and line number where each \fIname\fP
+is defined are displayed as well.  The
+.B \-F
+option implies
+.BR \-f .
+The
+.B \-g
+option forces variables to be created or modified at the global scope,
+even when \fBdeclare\fP is executed in a shell function.
+It is ignored in all other cases.
+The
+.B \-I
+option causes local variables to inherit the attributes
+(except the \fInameref\fP attribute) 
+and value of any existing variable with the same
+\fIname\fP at a surrounding scope.
+If there is no existing variable, the local variable is initially unset.
+The following options can
+be used to restrict output to variables with the specified attribute or
+to give variables attributes:
+.RS
+.PD 0
+.TP
+.B \-a
+Each \fIname\fP is an indexed array variable (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B \-A
+Each \fIname\fP is an associative array variable (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B \-f
+Use function names only.
+.TP
+.B \-i
+The variable is treated as an integer; arithmetic evaluation (see
+.SM
+.B "ARITHMETIC EVALUATION"
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+is performed when the variable is assigned a value.
+.TP
+.B \-l
+When the variable is assigned a value, all upper-case characters are
+converted to lower-case.
+The upper-case attribute is disabled.
+.TP
+.B \-n
+Give each \fIname\fP the \fInameref\fP attribute, making
+it a name reference to another variable.
+That other variable is defined by the value of \fIname\fP.
+All references, assignments, and attribute modifications
+to \fIname\fP, except those using or changing the
+\fB\-n\fP attribute itself, are performed on the variable referenced by
+\fIname\fP's value.
+The nameref attribute cannot be applied to array variables.
+.TP
+.B \-r
+Make \fIname\fPs readonly.  These names cannot then be assigned values
+by subsequent assignment statements or unset.
+.TP
+.B \-t
+Give each \fIname\fP the \fItrace\fP attribute.
+Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
+the calling shell.
+The trace attribute has no special meaning for variables.
+.TP
+.B \-u
+When the variable is assigned a value, all lower-case characters are
+converted to upper-case.
+The lower-case attribute is disabled.
+.TP
+.B \-x
+Mark \fIname\fPs for export to subsequent commands via the environment.
+.PD
+.PP
+Using `+' instead of `\-'
+turns off the attribute instead,
+with the exceptions that \fB+a\fP and \fB+A\fP
+may not be used to destroy array variables and \fB+r\fP will not
+remove the readonly attribute.
+When used in a function,
+.B declare
+and
+.B typeset
+make each
+\fIname\fP local, as with the
+.B local
+command,
+unless the \fB\-g\fP option is supplied.
+If a variable name is followed by =\fIvalue\fP, the value of
+the variable is set to \fIvalue\fP.
+When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
+create array variables, additional attributes do not take effect until
+subsequent assignments.
+The return value is 0 unless an invalid option is encountered,
+an attempt is made to define a function using
+.if n ``\-f foo=bar'',
+.if t \f(CW\-f foo=bar\fP,
+an attempt is made to assign a value to a readonly variable,
+an attempt is made to assign a value to an array variable without
+using the compound assignment syntax (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+one of the \fInames\fP is not a valid shell variable name,
+an attempt is made to turn off readonly status for a readonly variable,
+an attempt is made to turn off array status for an array variable,
+or an attempt is made to display a non-existent function with \fB\-f\fP.
+.RE
+.TP
+.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
+Without options, displays the list of currently remembered directories.
+The default display is on a single line with directory names separated
+by spaces.
+Directories are added to the list with the
+.B pushd
+command; the
+.B popd
+command removes entries from the list.
+The current directory is always the first directory in the stack.
+.RS
+.PD 0
+.TP
+.B \-c
+Clears the directory stack by deleting all of the entries.
+.TP
+.B \-l
+Produces a listing using full pathnames;
+the default listing format uses a tilde to denote the home directory.
+.TP
+.B \-p
+Print the directory stack with one entry per line.
+.TP
+.B \-v
+Print the directory stack with one entry per line,
+prefixing each entry with its index in the stack.
+.TP
+\fB+\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the left of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
+.TP
+\fB\-\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the right of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
+.PD
+.PP
+The return value is 0 unless an
+invalid option is supplied or \fIn\fP indexes beyond the end
+of the directory stack.
+.RE
+.TP
+\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ]
+Without options, remove each
+.I jobspec
+from the table of active jobs.
+If
+.I jobspec
+is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option
+is supplied, the \fIcurrent job\fP is used.
+If the \fB\-h\fP option is given, each
+.I jobspec
+is not removed from the table, but is marked so that
+.SM
+.B SIGHUP
+is not sent to the job if the shell receives a
+.SM
+.BR SIGHUP .
+If no
+.I jobspec
+is supplied, the
+.B \-a
+option means to remove or mark all jobs; the
+.B \-r
+option without a
+.I jobspec
+argument restricts operation to running jobs.
+The return value is 0 unless a
+.I jobspec
+does not specify a valid job.
+.TP
+\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
+Output the \fIarg\fPs, separated by spaces, followed by a newline.
+The return status is 0 unless a write error occurs.
+If \fB\-n\fP is specified, the trailing newline is
+suppressed.  If the \fB\-e\fP option is given, interpretation of
+the following backslash-escaped characters is enabled.  The
+.B \-E
+option disables the interpretation of these escape characters,
+even on systems where they are interpreted by default.
+The \fBxpg_echo\fP shell option may be used to
+dynamically determine whether or not \fBecho\fP expands these
+escape characters by default.
+.B echo
+does not interpret \fB\-\-\fP to mean the end of options.
+.B echo
+interprets the following escape sequences:
+.RS
+.PD 0
+.TP
+.B \ea
+alert (bell)
+.TP
+.B \eb
+backspace
+.TP
+.B \ec
+suppress further output
+.TP
+.B \ee
+.TP
+.B \eE
+an escape character
+.TP
+.B \ef
+form feed
+.TP
+.B \en
+new line
+.TP
+.B \er
+carriage return
+.TP
+.B \et
+horizontal tab
+.TP
+.B \ev
+vertical tab
+.TP
+.B \e\e
+backslash
+.TP
+.B \e0\fInnn\fP
+the eight-bit character whose value is the octal value \fInnn\fP
+(zero to three octal digits)
+.TP
+.B \ex\fIHH\fP
+the eight-bit character whose value is the hexadecimal value \fIHH\fP
+(one or two hex digits)
+.TP
+.B \eu\fIHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHH\fP (one to four hex digits)
+.TP
+.B \eU\fIHHHHHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHHHHHH\fP (one to eight hex digits)
+.PD
+.RE
+.TP
+\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
+Enable and disable builtin shell commands.
+Disabling a builtin allows a disk command which has the same name
+as a shell builtin to be executed without specifying a full pathname,
+even though the shell normally searches for builtins before disk commands.
+If \fB\-n\fP is used, each \fIname\fP
+is disabled; otherwise,
+\fInames\fP are enabled.  For example, to use the
+.B test
+binary found via the
+.SM
+.B PATH
+instead of the shell builtin version, run
+.if t \f(CWenable -n test\fP.
+.if n ``enable -n test''.
+The
+.B \-f
+option means to load the new builtin command
+.I name
+from shared object
+.IR filename ,
+on systems that support dynamic loading.
+Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
+colon-separated list of directories in which to search for \fIfilename\fP.
+The default is system-dependent.
+The
+.B \-d
+option will delete a builtin previously loaded with
+.BR \-f .
+If no \fIname\fP arguments are given, or if the
+.B \-p
+option is supplied, a list of shell builtins is printed.
+With no other option arguments, the list consists of all enabled
+shell builtins.
+If \fB\-n\fP is supplied, only disabled builtins are printed.
+If \fB\-a\fP is supplied, the list printed includes all builtins, with an
+indication of whether or not each is enabled.
+If \fB\-s\fP is supplied, the output is restricted to the POSIX
+\fIspecial\fP builtins.
+If no options are supplied and a \fIname\fP is not a shell builtin,
+\fBenable\fP will attempt to load \fIname\fP from a shared object named
+\fIname\fP, as if the command were
+.if t \f(CWenable \-f\fP \fIname name\fP .
+.if n ``enable -f \fIname name\fP .
+The return value is 0 unless a
+.I name
+is not a shell builtin or there is an error loading a new builtin
+from a shared object.
+.TP
+\fBeval\fP [\fIarg\fP ...]
+The \fIarg\fPs are read and concatenated together into a single
+command.  This command is then read and executed by the shell, and
+its exit status is returned as the value of
+.BR eval .
+If there are no
+.IR args ,
+or only null arguments,
+.B eval
+returns 0.
+.TP
+\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
+If
+.I command
+is specified, it replaces the shell.
+No new process is created.  The
+.I arguments
+become the arguments to \fIcommand\fP.
+If the
+.B \-l
+option is supplied,
+the shell places a dash at the beginning of the zeroth argument passed to
+.IR command .
+This is what
+.IR login (1)
+does.  The
+.B \-c
+option causes
+.I command
+to be executed with an empty environment.  If
+.B \-a
+is supplied, the shell passes
+.I name
+as the zeroth argument to the executed command.
+If
+.I command
+cannot be executed for some reason, a non-interactive shell exits,
+unless the
+.B execfail
+shell option
+is enabled.  In that case, it returns failure.
+An interactive shell returns failure if the file cannot be executed.
+A subshell exits unconditionally if \fBexec\fP fails.
+If
+.I command
+is not specified, any redirections take effect in the current shell,
+and the return status is 0.  If there is a redirection error, the
+return status is 1.
+.TP
+\fBexit\fP [\fIn\fP]
+Cause the shell to exit
+with a status of \fIn\fP.  If
+.I n
+is omitted, the exit status
+is that of the last command executed.
+A trap on
+.SM
+.B EXIT
+is executed before the shell terminates.
+.TP
+\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
+.PD 0
+.TP
+.B export \-p
+.PD
+The supplied
+.I names
+are marked for automatic export to the environment of
+subsequently executed commands.  If the
+.B \-f
+option is given, the
+.I names
+refer to functions.
+If no
+.I names
+are given, or if the
+.B \-p
+option is supplied, a list
+of names of all exported variables is printed.
+The
+.B \-n
+option causes the export property to be removed from each
+\fIname\fP.
+If a variable name is followed by =\fIword\fP, the value of
+the variable is set to \fIword\fP.
+.B export
+returns an exit status of 0 unless an invalid option is
+encountered,
+one of the \fInames\fP is not a valid shell variable name, or
+.B \-f
+is supplied with a
+.I name
+that is not a function.
+.TP
+\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
+.PD 0
+.TP
+\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
+.PD
+The first form selects a range of commands from
+.I first
+to
+.I last
+from the history list and displays or edits and re-executes them.
+.I First
+and
+.I last
+may be specified as a string (to locate the last command beginning
+with that string) or as a number (an index into the history list,
+where a negative number is used as an offset from the current
+command number).
+When listing, a \fIfirst\fP or \fIlast\fP of
+0 is equivalent to \-1 and \-0 is equivalent to the current
+command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1
+and \-0 is invalid.
+If
+.I last
+is not specified, it is set to
+the current command for listing (so that
+.if n ``fc \-l \-10''
+.if t \f(CWfc \-l \-10\fP
+prints the last 10 commands) and to
+.I first
+otherwise.
+If
+.I first
+is not specified, it is set to the previous
+command for editing and \-16 for listing.
+.sp 1
+The
+.B \-n
+option suppresses
+the command numbers when listing.  The
+.B \-r
+option reverses the order of
+the commands.  If the
+.B \-l
+option is given,
+the commands are listed on
+standard output.  Otherwise, the editor given by
+.I ename
+is invoked
+on a file containing those commands.  If
+.I ename
+is not given, the
+value of the
+.SM
+.B FCEDIT
+variable is used, and
+the value of
+.SM
+.B EDITOR
+if
+.SM
+.B FCEDIT
+is not set.  If neither variable is set,
+.FN vi
+is used.  When editing is complete, the edited commands are
+echoed and executed.
+.sp 1
+In the second form, \fIcommand\fP is re-executed after each instance
+of \fIpat\fP is replaced by \fIrep\fP.
+\fICommand\fP is interpreted the same as \fIfirst\fP above.
+A useful alias to use with this is
+.if n ``r="fc -s"'',
+.if t \f(CWr='fc \-s'\fP,
+so that typing
+.if n ``r cc''
+.if t \f(CWr cc\fP
+runs the last command beginning with
+.if n ``cc''
+.if t \f(CWcc\fP
+and typing
+.if n ``r''
+.if t \f(CWr\fP
+re-executes the last command.
+.sp 1
+If the first form is used, the return value is 0 unless an invalid
+option is encountered or
+.I first
+or
+.I last
+specify history lines out of range.
+If the
+.B \-e
+option is supplied, the return value is the value of the last
+command executed or failure if an error occurs with the temporary
+file of commands.  If the second form is used, the return status
+is that of the command re-executed, unless
+.I cmd
+does not specify a valid history line, in which case
+.B fc
+returns failure.
+.TP
+\fBfg\fP [\fIjobspec\fP]
+Resume
+.I jobspec
+in the foreground, and make it the current job.
+If
+.I jobspec
+is not present, the shell's notion of the \fIcurrent job\fP is used.
+The return value is that of the command placed into the foreground,
+or failure if run when job control is disabled or, when run with
+job control enabled, if
+.I jobspec
+does not specify a valid job or
+.I jobspec
+specifies a job that was started without job control.
+.TP
+\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP]
+.B getopts
+is used by shell procedures to parse positional parameters.
+.I optstring
+contains the option characters to be recognized; if a character
+is followed by a colon, the option is expected to have an
+argument, which should be separated from it by white space.
+The colon and question mark characters may not be used as
+option characters.
+Each time it is invoked,
+.B getopts
+places the next option in the shell variable
+.IR name ,
+initializing
+.I name
+if it does not exist,
+and the index of the next argument to be processed into the
+variable
+.SM
+.BR OPTIND .
+.SM
+.B OPTIND
+is initialized to 1 each time the shell or a shell script
+is invoked.  When an option requires an argument,
+.B getopts
+places that argument into the variable
+.SM
+.BR OPTARG .
+The shell does not reset
+.SM
+.B OPTIND
+automatically; it must be manually reset between multiple
+calls to
+.B getopts
+within the same shell invocation if a new set of parameters
+is to be used.
+.sp 1
+When the end of options is encountered, \fBgetopts\fP exits with a
+return value greater than zero.
+.SM
+.B OPTIND
+is set to the index of the first non-option argument,
+and \fIname\fP is set to ?.
+.sp 1
+.B getopts
+normally parses the positional parameters, but if more arguments are
+supplied as
+.I arg
+values,
+.B getopts
+parses those instead.
+.sp 1
+.B getopts
+can report errors in two ways.  If the first character of
+.I optstring
+is a colon,
+.I silent
+error reporting is used.  In normal operation, diagnostic messages
+are printed when invalid options or missing option arguments are
+encountered.
+If the variable
+.SM
+.B OPTERR
+is set to 0, no error messages will be displayed, even if the first
+character of
+.I optstring
+is not a colon.
+.sp 1
+If an invalid option is seen,
+.B getopts
+places ? into
+.I name
+and, if not silent,
+prints an error message and unsets
+.SM
+.BR OPTARG .
+If
+.B getopts
+is silent,
+the option character found is placed in
+.SM
+.B OPTARG
+and no diagnostic message is printed.
+.sp 1
+If a required argument is not found, and
+.B getopts
+is not silent,
+a question mark (\^\fB?\fP\^) is placed in
+.IR name ,
+.SM
+.B OPTARG
+is unset, and a diagnostic message is printed.
+If
+.B getopts
+is silent, then a colon (\^\fB:\fP\^) is placed in
+.I name
+and
+.SM
+.B OPTARG
+is set to the option character found.
+.sp 1
+.B getopts
+returns true if an option, specified or unspecified, is found.
+It returns false if the end of options is encountered or an
+error occurs.
+.TP
+\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
+Each time \fBhash\fP is invoked,
+the full pathname of the command
+.I name
+is determined by searching
+the directories in
+.B $PATH
+and remembered.  Any previously-remembered pathname is discarded.
+If the
+.B \-p
+option is supplied, no path search is performed, and
+.I filename
+is used as the full filename of the command.
+The
+.B \-r
+option causes the shell to forget all
+remembered locations.
+The
+.B \-d
+option causes the shell to forget the remembered location of each \fIname\fP.
+If the
+.B \-t
+option is supplied, the full pathname to which each \fIname\fP corresponds
+is printed.  If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
+the \fIname\fP is printed before the hashed full pathname.
+The
+.B \-l
+option causes output to be displayed in a format that may be reused as input.
+If no arguments are given, or if only \fB\-l\fP is supplied,
+information about remembered commands is printed.
+The return status is true unless a
+.I name
+is not found or an invalid option is supplied.
+.TP
+\fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
+Display helpful information about builtin commands.  If
+.I pattern
+is specified,
+.B help
+gives detailed help on all commands matching
+.IR pattern ;
+otherwise help for all the builtins and shell control structures
+is printed.
+.RS
+.PD 0
+.TP
+.B \-d
+Display a short description of each \fIpattern\fP
+.TP
+.B \-m
+Display the description of each \fIpattern\fP in a manpage-like format
+.TP
+.B \-s
+Display only a short usage synopsis for each \fIpattern\fP
+.PD
+.PP
+The return status is 0 unless no command matches
+.IR pattern .
+.RE
+.TP
+\fBhistory [\fIn\fP]
+.PD 0
+.TP
+\fBhistory\fP \fB\-c\fP
+.TP
+\fBhistory \-d\fP \fIoffset\fP
+.TP
+\fBhistory \-d\fP \fIstart\fP\-\fIend\fP
+.TP
+\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
+.TP
+\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
+.TP
+\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
+.PD
+With no options, display the command
+history list with line numbers.  Lines listed
+with a
+.B *
+have been modified.  An argument of
+.I n
+lists only the last
+.I n
+lines.
+If the shell variable
+.SM
+.B HISTTIMEFORMAT
+is set and not null,
+it is used as a format string for \fIstrftime\fP(3) to display
+the time stamp associated with each displayed history entry.
+No intervening blank is printed between the formatted time stamp
+and the history line.
+If \fIfilename\fP is supplied, it is used as the
+name of the history file; if not, the value of
+.SM
+.B HISTFILE
+is used.  Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-c
+Clear the history list by deleting all the entries.
+.TP
+\fB\-d\fP \fIoffset\fP
+Delete the history entry at position \fIoffset\fP.
+If \fIoffset\fP is negative, it is interpreted as relative to one greater
+than the last history position, so negative indices count back from the
+end of the history, and an index of \-1 refers to the current
+\fBhistory -d\fP command.
+.TP
+\fB\-d\fP \fIstart\fP\-\fIend\fP
+Delete the range of history entries between positions \fIstart\fP and
+\fIend\fP, inclusive.
+Positive and negative values for \fIstart\fP and \fIend\fP
+are interpreted as described above.
+.TP
+.B \-a
+Append the ``new'' history lines to the history file.
+These are history lines entered since the beginning of the current
+\fBbash\fP session, but not already appended to the history file.
+.TP
+.B \-n
+Read the history lines not already read from the history
+file into the current history list.  These are lines
+appended to the history file since the beginning of the
+current \fBbash\fP session.
+.TP
+.B \-r
+Read the contents of the history file
+and append them to the current history list.
+.TP
+.B \-w
+Write the current history list to the history file, overwriting the
+history file's contents.
+.TP
+.B \-p
+Perform history substitution on the following \fIargs\fP and display
+the result on the standard output.
+Does not store the results in the history list.
+Each \fIarg\fP must be quoted to disable normal history expansion.
+.TP
+.B \-s
+Store the
+.I args
+in the history list as a single entry.  The last command in the
+history list is removed before the
+.I args
+are added.
+.PD
+.PP
+If the
+.SM
+.B HISTTIMEFORMAT
+variable is set, the time stamp information
+associated with each history entry is written to the history file,
+marked with the history comment character.
+When the history file is read, lines beginning with the history
+comment character followed immediately by a digit are interpreted
+as timestamps for the following history entry.
+The return value is 0 unless an invalid option is encountered, an
+error occurs while reading or writing the history file, an invalid
+\fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
+history expansion supplied as an argument to \fB\-p\fP fails.
+.RE
+.TP
+\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
+.PD 0
+.TP
+\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
+.PD
+The first form lists the active jobs.  The options have the following
+meanings:
+.RS
+.PD 0
+.TP
+.B \-l
+List process IDs
+in addition to the normal information.
+.TP
+.B \-n
+Display information only about jobs that have changed status since
+the user was last notified of their status.
+.TP
+.B \-p
+List only the process ID of the job's process group
+leader.
+.TP
+.B \-r
+Display only running jobs.
+.TP
+.B \-s
+Display only stopped jobs.
+.PD
+.PP
+If
+.I jobspec
+is given, output is restricted to information about that job.
+The return status is 0 unless an invalid option is encountered
+or an invalid
+.I jobspec
+is supplied.
+.PP
+If the
+.B \-x
+option is supplied,
+.B jobs
+replaces any
+.I jobspec
+found in
+.I command
+or
+.I args
+with the corresponding process group ID, and executes
+.I command
+passing it
+.IR args ,
+returning its exit status.
+.RE
+.TP
+\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
+.PD 0
+.TP
+\fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
+.PD
+Send the signal named by
+.I sigspec
+or
+.I signum
+to the processes named by
+.I pid
+or
+.IR jobspec .
+.I sigspec
+is either a case-insensitive signal name such as
+.SM
+.B SIGKILL
+(with or without the
+.SM
+.B SIG
+prefix) or a signal number;
+.I signum
+is a signal number.
+If
+.I sigspec
+is not present, then
+.SM
+.B SIGTERM
+is assumed.
+An argument of
+.B \-l
+lists the signal names.
+If any arguments are supplied when
+.B \-l
+is given, the names of the signals corresponding to the arguments are
+listed, and the return status is 0.
+The \fIexit_status\fP argument to
+.B \-l
+is a number specifying either a signal number or the exit status of
+a process terminated by a signal.
+The
+.B \-L
+option is equivalent to \fB\-l\fP.
+.B kill
+returns true if at least one signal was successfully sent, or false
+if an error occurs or an invalid option is encountered.
+.TP
+\fBlet\fP \fIarg\fP [\fIarg\fP ...]
+Each
+.I arg
+is an arithmetic expression to be evaluated (see
+.SM
+.B "ARITHMETIC EVALUATION"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+If the last
+.I arg
+evaluates to 0,
+.B let
+returns 1; 0 is returned otherwise.
+.TP
+\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ]
+For each argument, a local variable named
+.I name
+is created, and assigned
+.IR value .
+The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
+When
+.B local
+is used within a function, it causes the variable
+.I name
+to have a visible scope restricted to that function and its children.
+If \fIname\fP is \-, the set of shell options is made local to the function
+in which \fBlocal\fP is invoked: shell options changed using the
+\fBset\fP builtin inside the function are restored to their original values
+when the function returns.
+The restore is effected as if a series of \fBset\fP commands were executed
+to restore the values that were in place before the function.
+With no operands,
+.B local
+writes a list of local variables to the standard output.  It is
+an error to use
+.B local
+when not within a function.  The return status is 0 unless
+.B local
+is used outside a function, an invalid
+.I name
+is supplied, or
+\fIname\fP is a readonly variable.
+.TP
+.B logout
+Exit a login shell.
+.TP
+\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
+.PD 0
+.TP
+\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
+.PD
+Read lines from the standard input into the indexed array variable
+.IR array ,
+or from file descriptor
+.I fd
+if the
+.B \-u
+option is supplied.
+The variable
+.SM
+.B MAPFILE
+is the default \fIarray\fP.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-d
+The first character of \fIdelim\fP is used to terminate each input line,
+rather than newline.
+If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
+when it reads a NUL character.
+.TP
+.B \-n
+Copy at most
+.I count
+lines.  If \fIcount\fP is 0, all lines are copied.
+.TP
+.B \-O
+Begin assigning to
+.I array
+at index
+.IR origin .
+The default index is 0.
+.TP
+.B \-s
+Discard the first \fIcount\fP lines read.
+.TP
+.B \-t
+Remove a trailing \fIdelim\fP (default newline) from each line read.
+.TP
+.B \-u
+Read lines from file descriptor \fIfd\fP instead of the standard input.
+.TP
+.B \-C
+Evaluate
+.I callback
+each time \fIquantum\fP lines are read.  The \fB\-c\fP option specifies
+.IR quantum .
+.TP
+.B \-c
+Specify the number of lines read between each call to
+.IR callback .
+.PD
+.PP
+If
+.B \-C
+is specified without
+.BR \-c ,
+the default quantum is 5000.
+When \fIcallback\fP is evaluated, it is supplied the index of the next
+array element to be assigned and the line to be assigned to that element
+as additional arguments.
+\fIcallback\fP is evaluated after the line is read but before the
+array element is assigned.
+.PP
+If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
+before assigning to it.
+.PP
+\fBmapfile\fP returns successfully unless an invalid option or option
+argument is supplied, \fIarray\fP is invalid or unassignable, or if
+\fIarray\fP is not an indexed array.
+.RE
+.TP
+\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
+Removes entries from the directory stack.
+The elements are numbered from 0 starting at the first directory
+listed by \fBdirs\fP.
+With no arguments, \fBpopd\fP
+removes the top directory from the stack, and
+changes to the new top directory.
+Arguments, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-n
+Suppresses the normal change of directory when removing directories
+from the stack, so that only the stack is manipulated.
+.TP
+\fB+\fP\fIn\fP
+Removes the \fIn\fPth entry counting from the left of the list
+shown by
+.BR dirs ,
+starting with zero, from the stack.
+For example:
+.if n ``popd +0''
+.if t \f(CWpopd +0\fP
+removes the first directory,
+.if n ``popd +1''
+.if t \f(CWpopd +1\fP
+the second.
+.TP
+\fB\-\fP\fIn\fP
+Removes the \fIn\fPth entry counting from the right of the list
+shown by
+.BR dirs ,
+starting with zero.  For example:
+.if n ``popd -0''
+.if t \f(CWpopd -0\fP
+removes the last directory,
+.if n ``popd -1''
+.if t \f(CWpopd -1\fP
+the next to last.
+.PD
+.PP
+If the top element of the directory stack is modified, and
+the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
+builtin to change to the directory at the top of the stack.
+If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
+.PP
+Otherwise,
+.B popd
+returns false if an invalid option is encountered, the directory stack
+is empty, or a non-existent directory stack entry is specified.
+.PP
+If the
+.B popd
+command is successful,
+bash runs
+.B dirs
+to show the final contents of the directory stack,
+and the return status is 0.
+.RE
+.TP
+\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
+Write the formatted \fIarguments\fP to the standard output under the
+control of the \fIformat\fP.
+The \fB\-v\fP option causes the output to be assigned to the variable
+\fIvar\fP rather than being printed to the standard output.
+.sp 1
+The \fIformat\fP is a character string which contains three types of objects:
+plain characters, which are simply copied to standard output, character
+escape sequences, which are converted and copied to the standard output, and
+format specifications, each of which causes printing of the next successive
+\fIargument\fP.
+In addition to the standard \fIprintf\fP(1) format specifications,
+\fBprintf\fP interprets the following extensions:
+.RS
+.PD 0
+.TP
+.B %b
+causes
+\fBprintf\fP to expand backslash escape sequences in the corresponding
+\fIargument\fP
+in the same way as \fBecho \-e\fP.
+.TP
+.B %q
+causes \fBprintf\fP to output the corresponding
+\fIargument\fP in a format that can be reused as shell input.
+.TP
+.B %Q
+like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
+before quoting it.
+.TP
+.B %(\fIdatefmt\fP)T
+causes \fBprintf\fP to output the date-time string resulting from using
+\fIdatefmt\fP as a format string for \fIstrftime\fP(3).
+The corresponding \fIargument\fP is an integer representing the number of
+seconds since the epoch.
+Two special argument values may be used: \-1 represents the current
+time, and \-2 represents the time the shell was invoked.
+If no argument is specified, conversion behaves as if \-1 had been given.
+This is an exception to the usual \fBprintf\fP behavior.
+.PD
+.PP
+The %b, %q, and %T directives all use the field width and precision
+arguments from the format specification and write that many bytes from
+(or use that wide a field for) the expanded argument, which usually
+contains more characters than the original.
+.PP
+Arguments to non-string format specifiers are treated as C constants,
+except that a leading plus or minus sign is allowed, and if the leading
+character is a single or double quote, the value is the ASCII value of
+the following character.
+.PP
+The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
+If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
+extra format specifications behave as if a zero value or null string, as
+appropriate, had been supplied.
+The return value is zero on success, non-zero on failure.
+.RE
+.TP
+\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
+.PD 0
+.TP
+\fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
+.PD
+Adds a directory to the top of the directory stack, or rotates
+the stack, making the new top of the stack the current working
+directory.
+With no arguments, \fBpushd\fP exchanges the top two elements of
+the directory stack.
+Arguments, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-n
+Suppresses the normal change of directory when rotating or
+adding directories to the stack, so that only the stack is manipulated.
+.TP
+\fB+\fP\fIn\fP
+Rotates the stack so that the \fIn\fPth directory
+(counting from the left of the list shown by
+.BR dirs ,
+starting with zero)
+is at the top.
+.TP
+\fB\-\fP\fIn\fP
+Rotates the stack so that the \fIn\fPth directory
+(counting from the right of the list shown by
+.BR dirs ,
+starting with zero) is at the top.
+.TP
+.I dir
+Adds
+.I dir
+to the directory stack at the top
+.PD
+.PP
+After the stack has been modified, if the \fB\-n\fP option was not
+supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
+directory at the top of the stack.
+If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
+.PP
+Otherwise, if no arguments are supplied,
+.B pushd
+returns 0 unless the directory stack is empty.
+When rotating the directory stack,
+.B pushd
+returns 0 unless the directory stack is empty or
+a non-existent directory stack element is specified.
+.PP
+If the
+.B pushd
+command is successful,
+bash runs
+.B dirs
+to show the final contents of the directory stack.
+.RE
+.TP
+\fBpwd\fP [\fB\-LP\fP]
+Print the absolute pathname of the current working directory.
+The pathname printed contains no symbolic links if the
+.B \-P
+option is supplied or the
+.B \-o physical
+option to the
+.B set
+builtin command is enabled.
+If the
+.B \-L
+option is used, the pathname printed may contain symbolic links.
+The return status is 0 unless an error occurs while
+reading the name of the current directory or an
+invalid option is supplied.
+.TP
+\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
+One line is read from the standard input, or from the file descriptor
+\fIfd\fP supplied as an argument to the \fB\-u\fP option,
+split into words as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under \fBWord Splitting\fP,
+and the first word
+is assigned to the first
+.IR name ,
+the second word to the second
+.IR name ,
+and so on.
+If there are more words than names, the remaining words and their
+intervening delimiters are assigned to the last
+.IR name .
+If there are fewer words read from the input stream than names,
+the remaining names are assigned empty values.
+The characters in
+.SM
+.B IFS
+are used to split the line into words using the same rules the shell
+uses for expansion (described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under \fBWord Splitting\fP).
+The backslash character (\fB\e\fP) may be used to remove any special
+meaning for the next character read and for line continuation.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-a \fIaname\fP
+The words are assigned to sequential indices
+of the array variable
+.IR aname ,
+starting at 0.
+.I aname
+is unset before any new values are assigned.
+Other \fIname\fP arguments are ignored.
+.TP
+.B \-d \fIdelim\fP
+The first character of \fIdelim\fP is used to terminate the input line,
+rather than newline.
+If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
+when it reads a NUL character.
+.TP
+.B \-e
+If the standard input
+is coming from a terminal,
+.B readline
+(see
+.SM
+.B READLINE
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+is used to obtain the line.
+Readline uses the current (or default, if line editing was not previously
+active) editing settings, but uses readline's default filename completion.
+.TP
+.B \-i \fItext\fP
+If
+.B readline
+is being used to read the line, \fItext\fP is placed into the editing
+buffer before editing begins.
+.TP
+.B \-n \fInchars\fP
+\fBread\fP returns after reading \fInchars\fP characters rather than
+waiting for a complete line of input, but honors a delimiter if fewer
+than \fInchars\fP characters are read before the delimiter.
+.TP
+.B \-N \fInchars\fP
+\fBread\fP returns after reading exactly \fInchars\fP characters rather
+than waiting for a complete line of input, unless EOF is encountered or
+\fBread\fP times out.
+Delimiter characters encountered in the input are
+not treated specially and do not cause \fBread\fP to return until
+\fInchars\fP characters are read.
+The result is not split on the characters in \fBIFS\fP; the intent is
+that the variable is assigned exactly the characters read
+(with the exception of backslash; see the \fB\-r\fP option below).
+.TP
+.B \-p \fIprompt\fP
+Display \fIprompt\fP on standard error, without a
+trailing newline, before attempting to read any input.  The prompt
+is displayed only if input is coming from a terminal.
+.TP
+.B \-r
+Backslash does not act as an escape character.
+The backslash is considered to be part of the line.
+In particular, a backslash-newline pair may not then be used as a line
+continuation.
+.TP
+.B \-s
+Silent mode.  If input is coming from a terminal, characters are
+not echoed.
+.TP
+.B \-t \fItimeout\fP
+Cause \fBread\fP to time out and return failure if a complete line of
+input (or a specified number of characters)
+is not read within \fItimeout\fP seconds.
+\fItimeout\fP may be a decimal number with a fractional portion following
+the decimal point.
+This option is only effective if \fBread\fP is reading input from a
+terminal, pipe, or other special file; it has no effect when reading
+from regular files.
+If \fBread\fP times out, \fBread\fP saves any partial input read into
+the specified variable \fIname\fP.
+If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
+read any data.
+The exit status is 0 if input is available on the specified file descriptor,
+or the read will return EOF,
+non-zero otherwise.
+The exit status is greater than 128 if the timeout is exceeded.
+.TP
+.B \-u \fIfd\fP
+Read input from file descriptor \fIfd\fP.
+.PD
+.PP
+If no
+.I names
+are supplied, the line read,
+without the ending delimiter but otherwise unmodified,
+is assigned to the variable
+.SM
+.BR REPLY .
+The exit status is zero, unless end-of-file is encountered, \fBread\fP
+times out (in which case the status is greater than 128),
+a variable assignment error (such as assigning to a readonly variable) occurs,
+or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
+.RE
+.TP
+\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]
+.PD
+The given
+\fInames\fP are marked readonly; the values of these
+.I names
+may not be changed by subsequent assignment.
+If the
+.B \-f
+option is supplied, the functions corresponding to the
+\fInames\fP are so
+marked.
+The
+.B \-a
+option restricts the variables to indexed arrays; the
+.B \-A
+option restricts the variables to associative arrays.
+If both options are supplied,
+.B \-A
+takes precedence.
+If no
+.I name
+arguments are given, or if the
+.B \-p
+option is supplied, a list of all readonly names is printed.
+The other options may be used to restrict the output to a subset of
+the set of readonly names.
+The
+.B \-p
+option causes output to be displayed in a format that
+may be reused as input.
+If a variable name is followed by =\fIword\fP, the value of
+the variable is set to \fIword\fP.
+The return status is 0 unless an invalid option is encountered,
+one of the
+.I names
+is not a valid shell variable name, or
+.B \-f
+is supplied with a
+.I name
+that is not a function.
+.TP
+\fBreturn\fP [\fIn\fP]
+Causes a function to stop executing and return the value specified by
+.I n
+to its caller.
+If
+.I n
+is omitted, the return status is that of the last command
+executed in the function body.
+If \fBreturn\fP is executed by a trap handler, the last command used to
+determine the status is the last command executed before the trap handler.
+If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
+used to determine the status is the last command executed by the trap
+handler before \fBreturn\fP was invoked.
+If
+.B return
+is used outside a function,
+but during execution of a script by the
+.B .
+(\fBsource\fP) command, it causes the shell to stop executing
+that script and return either
+.I n
+or the exit status of the last command executed within the
+script as the exit status of the script.
+If \fIn\fP is supplied, the return value is its least significant
+8 bits.
+The return status is non-zero if
+.B return
+is supplied a non-numeric argument, or
+is used outside a
+function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
+Any command associated with the \fBRETURN\fP trap is executed
+before execution resumes after the function or script.
+.TP
+\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
+.PD 0
+.TP
+\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
+.PD
+Without options, display the name and value of each shell variable
+in a format that can be reused as input
+for setting or resetting the currently-set variables.
+Read-only variables cannot be reset.
+In \fIposix mode\fP, only shell variables are listed.
+The output is sorted according to the current locale.
+When options are specified, they set or unset shell attributes.
+Any arguments remaining after option processing are treated
+as values for the positional parameters and are assigned, in order, to
+.BR $1 ,
+.BR $2 ,
+.B ...
+.BR $\fIn\fP .
+Options, if specified, have the following meanings:
+.RS
+.PD 0
+.TP 8
+.B \-a
+Each variable or function that is created or modified is given the
+export attribute and marked for export to the environment of
+subsequent commands.
+.TP 8
+.B \-b
+Report the status of terminated background jobs
+immediately, rather than before the next primary prompt.  This is
+effective only when job control is enabled.
+.TP 8
+.B \-e
+Exit immediately if a
+\fIpipeline\fP (which may consist of a single \fIsimple command\fP),
+a \fIlist\fP,
+or a \fIcompound command\fP
+(see
+.SM
+.B SHELL GRAMMAR
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+exits with a non-zero status.
+The shell does not exit if the
+command that fails is part of the command list immediately following a
+.B while
+or
+.B until
+keyword,
+part of the test following the
+.B if
+or
+.B elif
+reserved words, part of any command executed in a
+.B &&
+or
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
+any command in a pipeline but the last,
+or if the command's return value is
+being inverted with
+.BR ! .
+If a compound command other than a subshell
+returns a non-zero status because a command failed
+while \fB\-e\fP was being ignored, the shell does not exit.
+A trap on \fBERR\fP, if set, is executed before the shell exits.
+This option applies to the shell environment and each subshell environment
+separately (see
+.SM
+.B "COMMAND EXECUTION ENVIRONMENT"
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+and may cause
+subshells to exit before executing all the commands in the subshell.
+.if t .sp 0.5
+.if n .sp 1
+If a compound command or shell function executes in a context
+where \fB\-e\fP is being ignored,
+none of the commands executed within the compound command or function body
+will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
+and a command returns a failure status.
+If a compound command or shell function sets \fB\-e\fP while executing in
+a context where \fB\-e\fP is ignored, that setting will not have any
+effect until the compound command or the command containing the function
+call completes.
+.TP 8
+.B \-f
+Disable pathname expansion.
+.TP 8
+.B \-h
+Remember the location of commands as they are looked up for execution.
+This is enabled by default.
+.TP 8
+.B \-k
+All arguments in the form of assignment statements
+are placed in the environment for a command, not just
+those that precede the command name.
+.TP 8
+.B \-m
+Monitor mode.  Job control is enabled.  This option is on
+by default for interactive shells on systems that support
+it (see
+.SM
+.B JOB CONTROL
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+All processes run in a separate process group.
+When a background job completes, the shell prints a line
+containing its exit status.
+.TP 8
+.B \-n
+Read commands but do not execute them.
+This may be used to check a shell script for syntax errors.
+This is ignored by interactive shells.
+.TP 8
+.B \-o \fIoption\-name\fP
+The \fIoption\-name\fP can be one of the following:
+.RS
+.TP 8
+.B allexport
+Same as
+.BR \-a .
+.TP 8
+.B braceexpand
+Same as
+.BR \-B .
+.TP 8
+.B emacs
+Use an emacs-style command line editing interface.  This is enabled
+by default when the shell is interactive, unless the shell is started
+with the
+.B \-\-noediting
+option.
+This also affects the editing interface used for \fBread \-e\fP.
+.TP 8
+.B errexit
+Same as
+.BR \-e .
+.TP 8
+.B errtrace
+Same as
+.BR \-E .
+.TP 8
+.B functrace
+Same as
+.BR \-T .
+.TP 8
+.B hashall
+Same as
+.BR \-h .
+.TP 8
+.B histexpand
+Same as
+.BR \-H .
+.TP 8
+.B history
+Enable command history, as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR HISTORY .
+This option is on by default in interactive shells.
+.TP 8
+.B ignoreeof
+The effect is as if the shell command
+.if t \f(CWIGNOREEOF=10\fP
+.if n ``IGNOREEOF=10''
+had been executed
+(see
+.B Shell Variables
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP 8
+.B keyword
+Same as
+.BR \-k .
+.TP 8
+.B monitor
+Same as
+.BR \-m .
+.TP 8
+.B noclobber
+Same as
+.BR \-C .
+.TP 8
+.B noexec
+Same as
+.BR \-n .
+.TP 8
+.B noglob
+Same as
+.BR \-f .
+.TP 8
+.B nolog
+Currently ignored.
+.TP 8
+.B notify
+Same as
+.BR \-b .
+.TP 8
+.B nounset
+Same as
+.BR \-u .
+.TP 8
+.B onecmd
+Same as
+.BR \-t .
+.TP 8
+.B physical
+Same as
+.BR \-P .
+.TP 8
+.B pipefail
+If set, the return value of a pipeline is the value of the last
+(rightmost) command to exit with a non-zero status, or zero if all
+commands in the pipeline exit successfully.
+This option is disabled by default.
+.TP 8
+.B posix
+Change the behavior of
+.B bash
+where the default operation differs
+from the POSIX standard to match the standard (\fIposix mode\fP).
+See
+.SM
+.B "SEE ALSO"
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el below
+for a reference to a document that details how posix mode affects
+bash's behavior.
+.TP 8
+.B privileged
+Same as
+.BR \-p .
+.TP 8
+.B verbose
+Same as
+.BR \-v .
+.TP 8
+.B vi
+Use a vi-style command line editing interface.
+This also affects the editing interface used for \fBread \-e\fP.
+.TP 8
+.B xtrace
+Same as
+.BR \-x .
+.sp .5
+.PP
+If
+.B \-o
+is supplied with no \fIoption\-name\fP, the values of the current options are
+printed.
+If
+.B +o
+is supplied with no \fIoption\-name\fP, a series of
+.B set
+commands to recreate the current option settings is displayed on
+the standard output.
+.RE
+.TP 8
+.B \-p
+Turn on
+.I privileged
+mode.  In this mode, the
+.SM
+.B $ENV
+and
+.SM
+.B $BASH_ENV
+files are not processed, shell functions are not inherited from the
+environment, and the
+.SM
+.BR SHELLOPTS ,
+.SM
+.BR BASHOPTS ,
+.SM
+.BR CDPATH ,
+and
+.SM
+.B GLOBIGNORE
+variables, if they appear in the environment, are ignored.
+If the shell is started with the effective user (group) id not equal to the
+real user (group) id, and the \fB\-p\fP option is not supplied, these actions
+are taken and the effective user id is set to the real user id.
+If the \fB\-p\fP option is supplied at startup, the effective user id is
+not reset.
+Turning this option off causes the effective user
+and group ids to be set to the real user and group ids.
+.TP 8
+.B \-r
+Enable restricted shell mode.
+This option cannot be unset once it has been set.
+.TP 8
+.B \-t
+Exit after reading and executing one command.
+.TP 8
+.B \-u
+Treat unset variables and parameters other than the special
+parameters "@" and "*",
+or array variables subscripted with "@" or "*",
+as an error when performing
+parameter expansion.  If expansion is attempted on an
+unset variable or parameter, the shell prints an error message, and,
+if not interactive, exits with a non-zero status.
+.TP 8
+.B \-v
+Print shell input lines as they are read.
+.TP 8
+.B \-x
+After expanding each \fIsimple command\fP,
+\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
+arithmetic \fBfor\fP command, display the expanded value of
+.SM
+.BR PS4 ,
+followed by the command and its expanded arguments
+or associated word list.
+.TP 8
+.B \-B
+The shell performs brace expansion (see
+.B Brace Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This is on by default.
+.TP 8
+.B \-C
+If set,
+.B bash
+does not overwrite an existing file with the
+.BR > ,
+.BR >& ,
+and
+.B <>
+redirection operators.  This may be overridden when
+creating output files by using the redirection operator
+.B >|
+instead of
+.BR > .
+.TP 8
+.B \-E
+If set, any trap on \fBERR\fP is inherited by shell functions, command
+substitutions, and commands executed in a subshell environment.
+The \fBERR\fP trap is normally not inherited in such cases.
+.TP 8
+.B \-H
+Enable
+.B !
+style history substitution.  This option is on by
+default when the shell is interactive.
+.TP 8
+.B \-P
+If set, the shell does not resolve symbolic links when executing
+commands such as
+.B cd
+that change the current working directory.  It uses the
+physical directory structure instead.  By default,
+.B bash
+follows the logical chain of directories when performing commands
+which change the current directory.
+.TP 8
+.B \-T
+If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
+functions, command substitutions, and commands executed in a
+subshell environment.
+The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
+in such cases.
+.TP 8
+.B \-\-
+If no arguments follow this option, then the positional parameters are
+unset.  Otherwise, the positional parameters are set to the
+\fIarg\fPs, even if some of them begin with a
+.BR \- .
+.TP 8
+.B \-
+Signal the end of options, cause all remaining \fIarg\fPs to be
+assigned to the positional parameters.  The
+.B \-x
+and
+.B \-v
+options are turned off.
+If there are no \fIarg\fPs,
+the positional parameters remain unchanged.
+.PD
+.PP
+The options are off by default unless otherwise noted.
+Using + rather than \- causes these options to be turned off.
+The options can also be specified as arguments to an invocation of
+the shell.
+The current set of options may be found in
+.BR $\- .
+The return status is always true unless an invalid option is encountered.
+.RE
+.TP
+\fBshift\fP [\fIn\fP]
+The positional parameters from \fIn\fP+1 ... are renamed to
+.B $1
+.B ....
+Parameters represented by the numbers \fB$#\fP
+down to \fB$#\fP\-\fIn\fP+1 are unset.
+.I n
+must be a non-negative number less than or equal to \fB$#\fP.
+If
+.I n
+is 0, no parameters are changed.
+If
+.I n
+is not given, it is assumed to be 1.
+If
+.I n
+is greater than \fB$#\fP, the positional parameters are not changed.
+The return status is greater than zero if
+.I n
+is greater than
+.B $#
+or less than zero; otherwise 0.
+.TP
+\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
+Toggle the values of settings controlling optional shell behavior.
+The settings can be either those listed below, or, if the
+.B \-o
+option is used, those available with the
+.B \-o
+option to the \fBset\fP builtin command.
+With no options, or with the
+.B \-p
+option, a list of all settable options is displayed, with
+an indication of whether or not each is set;
+if \fIoptnames\fP are supplied, the output is restricted to those options.
+The \fB\-p\fP option causes output to be displayed in a form that
+may be reused as input.
+Other options have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-s
+Enable (set) each \fIoptname\fP.
+.TP
+.B \-u
+Disable (unset) each \fIoptname\fP.
+.TP
+.B \-q
+Suppresses normal output (quiet mode); the return status indicates
+whether the \fIoptname\fP is set or unset.
+If multiple \fIoptname\fP arguments are given with
+.BR \-q ,
+the return status is zero if all \fIoptnames\fP are enabled; non-zero
+otherwise.
+.TP
+.B \-o
+Restricts the values of \fIoptname\fP to be those defined for the
+.B \-o
+option to the
+.B set
+builtin.
+.PD
+.PP
+If either
+.B \-s
+or
+.B \-u
+is used with no \fIoptname\fP arguments,
+.B shopt
+shows only those options which are set or unset, respectively.
+Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
+by default.
+.PP
+The return status when listing options is zero if all \fIoptnames\fP
+are enabled, non-zero otherwise.  When setting or unsetting options,
+the return status is zero unless an \fIoptname\fP is not a valid shell
+option.
+.PP
+The list of \fBshopt\fP options is:
+.if t .sp .5v
+.if n .sp 1v
+.PD 0
+.TP 8
+.B assoc_expand_once
+If set, the shell suppresses multiple evaluation of associative array
+subscripts during arithmetic expression evaluation, while executing
+builtins that can perform variable assignments,
+and while executing builtins that perform array dereferencing.
+.TP 8
+.B autocd
+If set, a command name that is the name of a directory is executed as if
+it were the argument to the \fBcd\fP command.
+This option is only used by interactive shells.
+.TP 8
+.B cdable_vars
+If set, an argument to the
+.B cd
+builtin command that
+is not a directory is assumed to be the name of a variable whose
+value is the directory to change to.
+.TP 8
+.B cdspell
+If set, minor errors in the spelling of a directory component in a
+.B cd
+command will be corrected.
+The errors checked for are transposed characters,
+a missing character, and one character too many.
+If a correction is found, the corrected filename is printed,
+and the command proceeds.
+This option is only used by interactive shells.
+.TP 8
+.B checkhash
+If set, \fBbash\fP checks that a command found in the hash
+table exists before trying to execute it.  If a hashed command no
+longer exists, a normal path search is performed.
+.TP 8
+.B checkjobs
+If set, \fBbash\fP lists the status of any stopped and running jobs before
+exiting an interactive shell.  If any jobs are running, this causes
+the exit to be deferred until a second exit is attempted without an
+intervening command (see
+.SM
+.B "JOB CONTROL"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+The shell always postpones exiting if any jobs are stopped.
+.TP 8
+.B checkwinsize
+If set, \fBbash\fP checks the window size after each external (non-builtin)
+command and, if necessary, updates the values of
+.SM
+.B LINES
+and
+.SM
+.BR COLUMNS .
+This option is enabled by default.
+.TP 8
+.B cmdhist
+If set,
+.B bash
+attempts to save all lines of a multiple-line
+command in the same history entry.  This allows
+easy re-editing of multi-line commands.
+This option is enabled by default, but only has an effect if command
+history is enabled, as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR HISTORY .
+.PD 0
+.TP 8
+.B compat31
+.TP 8
+.B compat32
+.TP 8
+.B compat40
+.TP 8
+.B compat41
+.TP 8
+.B compat42
+.TP 8
+.B compat43
+.TP 8
+.B compat44
+.TP 8
+.B compat50
+.PD
+These control aspects of the shell's compatibility mode
+(see
+.SM
+.B "SHELL COMPATIBILITY MODE"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el below).
+.TP 8
+.B complete_fullquote
+If set,
+.B bash
+quotes all shell metacharacters in filenames and directory names when
+performing completion.
+If not set,
+.B bash
+removes metacharacters such as the dollar sign from the set of
+characters that will be quoted in completed filenames
+when these metacharacters appear in shell variable references in words to be
+completed.
+This means that dollar signs in variable names that expand to directories
+will not be quoted;
+however, any dollar signs appearing in filenames will not be quoted, either.
+This is active only when bash is using backslashes to quote completed
+filenames.
+This variable is set by default, which is the default bash behavior in
+versions through 4.2.
+.TP 8
+.B direxpand
+If set,
+.B bash
+replaces directory names with the results of word expansion when performing
+filename completion.  This changes the contents of the readline editing
+buffer.
+If not set,
+.B bash
+attempts to preserve what the user typed.
+.TP 8
+.B dirspell
+If set,
+.B bash
+attempts spelling correction on directory names during word completion
+if the directory name initially supplied does not exist.
+.TP 8
+.B dotglob
+If set,
+.B bash
+includes filenames beginning with a `.' in the results of pathname
+expansion.
+The filenames
+.B ``.''
+and
+.B ``..''
+must always be matched explicitly, even if
+.B dotglob
+is set.
+.TP 8
+.B execfail
+If set, a non-interactive shell will not exit if
+it cannot execute the file specified as an argument to the
+.B exec
+builtin command.  An interactive shell does not exit if
+.B exec
+fails.
+.TP 8
+.B expand_aliases
+If set, aliases are expanded as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR ALIASES .
+This option is enabled by default for interactive shells.
+.TP 8
+.B extdebug
+If set at shell invocation,
+or in a shell startup file,
+arrange to execute the debugger profile
+before the shell starts, identical to the \fB\-\-debugger\fP option.
+If set after invocation, behavior intended for use by debuggers is enabled:
+.RS
+.TP
+.B 1.
+The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
+file name and line number corresponding to each function name supplied
+as an argument.
+.TP
+.B 2.
+If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
+next command is skipped and not executed.
+.TP
+.B 3.
+If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
+shell is executing in a subroutine (a shell function or a shell script
+executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
+a call to \fBreturn\fP.
+.TP
+.B 4.
+.SM
+.B BASH_ARGC
+and
+.SM
+.B BASH_ARGV
+are updated as described in their descriptions
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B 5.
+Function tracing is enabled: command substitution, shell functions, and
+subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
+\fBDEBUG\fP and \fBRETURN\fP traps.
+.TP
+.B 6.
+Error tracing is enabled: command substitution, shell functions, and
+subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
+\fBERR\fP trap.
+.RE
+.TP 8
+.B extglob
+If set, the extended pattern matching features described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+\fBPathname Expansion\fP are enabled.
+.TP 8
+.B extquote
+If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
+performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
+enclosed in double quotes.  This option is enabled by default.
+.TP 8
+.B failglob
+If set, patterns which fail to match filenames during pathname expansion
+result in an expansion error.
+.TP 8
+.B force_fignore
+If set, the suffixes specified by the
+.SM
+.B FIGNORE
+shell variable
+cause words to be ignored when performing word completion even if
+the ignored words are the only possible completions.
+See
+.SM
+\fBSHELL VARIABLES\fP
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+for a description of
+.SM
+.BR FIGNORE .
+This option is enabled by default.
+.TP 8
+.B globasciiranges
+If set, range expressions used in pattern matching bracket expressions (see
+.SM
+.B Pattern Matching
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+behave as if in the traditional C locale when performing
+comparisons.  That is, the current locale's collating sequence
+is not taken into account, so
+.B b
+will not collate between
+.B A
+and
+.BR B ,
+and upper-case and lower-case ASCII characters will collate together.
+.TP 8
+.B globskipdots
+If set, pathname expansion will never match the filenames
+.B ``.''
+and
+.BR ``..'' ,
+even if the pattern begins with a
+.BR ``.'' .
+This option is enabled by default.
+.TP 8
+.B globstar
+If set, the pattern \fB**\fP used in a pathname expansion context will
+match all files and zero or more directories and subdirectories.
+If the pattern is followed by a \fB/\fP, only directories and
+subdirectories match.
+.TP 8
+.B gnu_errfmt
+If set, shell error messages are written in the standard GNU error
+message format.
+.TP 8
+.B histappend
+If set, the history list is appended to the file named by the value
+of the
+.SM
+.B HISTFILE
+variable when the shell exits, rather than overwriting the file.
+.TP 8
+.B histreedit
+If set, and
+.B readline
+is being used, a user is given the opportunity to re-edit a
+failed history substitution.
+.TP 8
+.B histverify
+If set, and
+.B readline
+is being used, the results of history substitution are not immediately
+passed to the shell parser.  Instead, the resulting line is loaded into
+the \fBreadline\fP editing buffer, allowing further modification.
+.TP 8
+.B hostcomplete
+If set, and
+.B readline
+is being used, \fBbash\fP will attempt to perform hostname completion when a
+word containing a \fB@\fP is being completed (see
+.B Completing
+under
+.SM
+.B READLINE
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This is enabled by default.
+.TP 8
+.B huponexit
+If set, \fBbash\fP will send
+.SM
+.B SIGHUP
+to all jobs when an interactive login shell exits.
+.TP 8
+.B inherit_errexit
+If set, command substitution inherits the value of the \fBerrexit\fP option,
+instead of unsetting it in the subshell environment.
+This option is enabled when \fIposix mode\fP is enabled.
+.TP 8
+.B interactive_comments
+If set, allow a word beginning with
+.B #
+to cause that word and all remaining characters on that
+line to be ignored in an interactive shell (see
+.SM
+.B COMMENTS
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This option is enabled by default.
+.TP 8
+.B lastpipe
+If set, and job control is not active, the shell runs the last command of
+a pipeline not executed in the background in the current shell environment.
+.TP 8
+.B lithist
+If set, and the
+.B cmdhist
+option is enabled, multi-line commands are saved to the history with
+embedded newlines rather than using semicolon separators where possible.
+.TP 8
+.B localvar_inherit
+If set, local variables inherit the value and attributes of a variable of
+the same name that exists at a previous scope before any new value is
+assigned.  The nameref attribute is not inherited.
+.TP 8
+.B localvar_unset
+If set, calling \fBunset\fP on local variables in previous function scopes
+marks them so subsequent lookups find them unset until that function
+returns. This is identical to the behavior of unsetting local variables
+at the current function scope.
+.TP 8
+.B login_shell
+The shell sets this option if it is started as a login shell (see
+.SM
+.B "INVOCATION"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+The value may not be changed.
+.TP 8
+.B mailwarn
+If set, and a file that \fBbash\fP is checking for mail has been
+accessed since the last time it was checked, the message ``The mail in
+\fImailfile\fP has been read'' is displayed.
+.TP 8
+.B no_empty_cmd_completion
+If set, and
+.B readline
+is being used,
+.B bash
+will not attempt to search the
+.SM
+.B PATH
+for possible completions when
+completion is attempted on an empty line.
+.TP 8
+.B nocaseglob
+If set,
+.B bash
+matches filenames in a case\-insensitive fashion when performing pathname
+expansion (see
+.B Pathname Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP 8
+.B nocasematch
+If set,
+.B bash
+matches patterns in a case\-insensitive fashion when performing matching
+while executing \fBcase\fP or \fB[[\fP conditional commands,
+when performing pattern substitution word expansions,
+or when filtering possible completions as part of programmable completion.
+.TP 8
+.B noexpand_translation
+If set,
+.B bash
+encloses the translated results of $"..." quoting in single quotes
+instead of double quotes.
+If the string is not translated, this has no effect.
+.TP 8
+.B nullglob
+If set,
+.B bash
+allows patterns which match no
+files (see
+.B Pathname Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+to expand to a null string, rather than themselves.
+.TP 8
+.B patsub_replacement
+If set, \fBbash\fP
+expands occurrences of \fB&\fP in the replacement string of pattern
+substitution to the text matched by the pattern, as described
+under \fBParameter Expansion\fP
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+This option is enabled by default.
+.TP 8
+.B progcomp
+If set, the programmable completion facilities (see
+\fBProgrammable Completion\fP
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+are enabled.
+This option is enabled by default.
+.TP 8
+.B progcomp_alias
+If set, and programmable completion is enabled, \fBbash\fP treats a command
+name that doesn't have any completions as a possible alias and attempts
+alias expansion. If it has an alias, \fBbash\fP attempts programmable
+completion using the command word resulting from the expanded alias.
+.TP 8
+.B promptvars
+If set, prompt strings undergo
+parameter expansion, command substitution, arithmetic
+expansion, and quote removal after being expanded as described in
+.SM
+.B PROMPTING
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+This option is enabled by default.
+.TP 8
+.B restricted_shell
+The shell sets this option if it is started in restricted mode
+(see
+.SM
+.B "RESTRICTED SHELL"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el below).
+The value may not be changed.
+This is not reset when the startup files are executed, allowing
+the startup files to discover whether or not a shell is restricted.
+.TP 8
+.B shift_verbose
+If set, the
+.B shift
+builtin prints an error message when the shift count exceeds the
+number of positional parameters.
+.TP 8
+.B sourcepath
+If set, the
+\fB.\fP (\fBsource\fP) builtin uses the value of
+.SM
+.B PATH
+to find the directory containing the file supplied as an argument.
+This option is enabled by default.
+.TP 8
+.B varredir_close
+If set, the shell automatically closes file descriptors assigned using the
+\fI{varname}\fP redirection syntax (see
+.SM
+.B REDIRECTION
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+instead of leaving them open when the command completes.
+.TP 8
+.B xpg_echo
+If set, the \fBecho\fP builtin expands backslash-escape sequences
+by default.
+.RE
+.PD
+.TP
+\fBsuspend\fP [\fB\-f\fP]
+Suspend the execution of this shell until it receives a
+.SM
+.B SIGCONT
+signal.  A login shell,
+or a shell without job control enabled,
+cannot be suspended; the
+.B \-f
+option can be used to override this and force the suspension.
+The return status is 0 unless the shell is a login shell
+or job control is not enabled
+and
+.B \-f
+is not supplied.
+.TP
+\fBtest\fP \fIexpr\fP
+.PD 0
+.TP
+\fB[\fP \fIexpr\fP \fB]\fP
+Return a status of 0 (true) or 1 (false) depending on
+the evaluation of the conditional expression
+.IR expr .
+Each operator and operand must be a separate argument.
+Expressions are composed of the primaries described 
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" .
+\fBtest\fP does not accept any options, nor does it accept and ignore
+an argument of \fB\-\-\fP as signifying the end of options.
+.if t .sp 0.5
+.if n .sp 1
+Expressions may be combined using the following operators, listed
+in decreasing order of precedence.
+The evaluation depends on the number of arguments; see below.
+Operator precedence is used when there are five or more arguments.
+.RS
+.PD 0
+.TP
+.B ! \fIexpr\fP
+True if
+.I expr
+is false.
+.TP
+.B ( \fIexpr\fP )
+Returns the value of \fIexpr\fP.
+This may be used to override the normal precedence of operators.
+.TP
+\fIexpr1\fP \-\fBa\fP \fIexpr2\fP
+True if both
+.I expr1
+and
+.I expr2
+are true.
+.TP
+\fIexpr1\fP \-\fBo\fP \fIexpr2\fP
+True if either
+.I expr1
+or
+.I expr2
+is true.
+.PD
+.PP
+\fBtest\fP and \fB[\fP evaluate conditional
+expressions using a set of rules based on the number of arguments.
+.if t .sp 0.5
+.if n .sp 1
+.PD 0
+.TP
+0 arguments
+The expression is false.
+.TP
+1 argument
+The expression is true if and only if the argument is not null.
+.TP
+2 arguments
+If the first argument is \fB!\fP, the expression is true if and
+only if the second argument is null.
+If the first argument is one of the unary conditional operators listed
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" ,
+the expression is true if the unary test is true.
+If the first argument is not a valid unary conditional operator, the expression
+is false.
+.TP
+3 arguments
+The following conditions are applied in the order listed.
+If the second argument is one of the binary conditional operators listed
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" ,
+the result of the expression is the result of the binary test using
+the first and third arguments as operands.
+The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
+when there are three arguments.
+If the first argument is \fB!\fP, the value is the negation of
+the two-argument test using the second and third arguments.
+If the first argument is exactly \fB(\fP and the third argument is
+exactly \fB)\fP, the result is the one-argument test of the second
+argument.
+Otherwise, the expression is false.
+.TP
+4 arguments
+The following conditions are applied in the order listed.
+If the first argument is \fB!\fP, the result is the negation of
+the three-argument expression composed of the remaining arguments.
+the two-argument test using the second and third arguments.
+If the first argument is exactly \fB(\fP and the fourth argument is
+exactly \fB)\fP, the result is the two-argument test of the second
+and third arguments.
+Otherwise, the expression is parsed and evaluated according to
+precedence using the rules listed above.
+.TP
+5 or more arguments
+The expression is parsed and evaluated according to precedence
+using the rules listed above.
+.if t .sp 0.5
+.if n .sp 1
+.LP
+When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators
+sort lexicographically using ASCII ordering.
+.RE
+.PD
+.TP
+.B times
+Print the accumulated user and system times for the shell and
+for processes run from the shell.  The return status is 0.
+.TP
+\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...]
+The command
+.I arg
+is to be read and executed when the shell receives
+signal(s)
+.IR sigspec .
+If
+.I arg
+is absent (and there is a single \fIsigspec\fP) or
+.BR \- ,
+each specified signal is
+reset to its original disposition (the value it had
+upon entrance to the shell).
+If
+.I arg
+is the null string the signal specified by each
+.I sigspec
+is ignored by the shell and by the commands it invokes.
+If
+.I arg
+is not present and
+.B \-p
+has been supplied, then the trap commands associated with each
+.I sigspec
+are displayed.
+If no arguments are supplied or if only
+.B \-p
+is given,
+.B trap
+prints the list of commands associated with each signal.
+The
+.B \-l
+option causes the shell to print a list of signal names and
+their corresponding numbers.
+Each
+.I sigspec
+is either
+a signal name defined in <\fIsignal.h\fP>, or a signal number.
+Signal names are case insensitive and the
+.SM
+.B SIG
+prefix is optional.
+.if t .sp 0.5
+.if n .sp 1
+If a
+.I sigspec
+is
+.SM
+.B EXIT
+(0) the command
+.I arg
+is executed on exit from the shell.
+If a
+.I sigspec
+is
+.SM
+.BR DEBUG ,
+the command
+.I arg
+is executed before every \fIsimple command\fP, \fIfor\fP command,
+\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP
+command, and before the first command executes in a shell function (see
+.SM
+.B SHELL GRAMMAR
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+Refer to the description of the \fBextdebug\fP option to the
+\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
+If a
+.I sigspec
+is
+.SM
+.BR RETURN ,
+the command
+.I arg
+is executed each time a shell function or a script executed with
+the \fB.\fP or \fBsource\fP builtins finishes executing.
+.if t .sp 0.5
+.if n .sp 1
+If a
+.I sigspec
+is
+.SM
+.BR ERR ,
+the command
+.I arg
+is executed whenever
+a pipeline (which may consist of a single simple
+command), a list, or a compound command returns a
+non\-zero exit status,
+subject to the following conditions.
+The
+.SM
+.B ERR
+trap is not executed if the failed
+command is part of the command list immediately following a
+.B while
+or
+.B until
+keyword,
+part of the test in an
+.I if
+statement, part of a command executed in a
+.B &&
+or
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
+any command in a pipeline but the last,
+or if the command's return value is
+being inverted using
+.BR ! .
+These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
+.if t .sp 0.5
+.if n .sp 1
+Signals ignored upon entry to the shell cannot be trapped or reset.
+Trapped signals that are not being ignored are reset to their original
+values in a subshell or subshell environment when one is created.
+The return status is false if any
+.I sigspec
+is invalid; otherwise
+.B trap
+returns true.
+.TP
+\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...]
+With no options,
+indicate how each
+.I name
+would be interpreted if used as a command name.
+If the
+.B \-t
+option is used,
+.B type
+prints a string which is one of
+.IR alias ,
+.IR keyword ,
+.IR function ,
+.IR builtin ,
+or
+.I file
+if
+.I name
+is an alias, shell reserved word, function, builtin, or disk file,
+respectively.
+If the
+.I name
+is not found, then nothing is printed, and an exit status of false
+is returned.
+If the
+.B \-p
+option is used,
+.B type
+either returns the name of the disk file
+that would be executed if
+.I name
+were specified as a command name,
+or nothing if
+.if t \f(CWtype -t name\fP
+.if n ``type -t name''
+would not return
+.IR file .
+The
+.B \-P
+option forces a
+.SM
+.B PATH
+search for each \fIname\fP, even if
+.if t \f(CWtype -t name\fP
+.if n ``type -t name''
+would not return
+.IR file .
+If a command is hashed,
+.B \-p
+and
+.B \-P
+print the hashed value, which is not necessarily the file that appears
+first in
+.SM
+.BR PATH .
+If the
+.B \-a
+option is used,
+.B type
+prints all of the places that contain
+an executable named
+.IR name .
+This includes aliases and functions,
+if and only if the
+.B \-p
+option is not also used.
+The table of hashed commands is not consulted
+when using
+.BR \-a .
+The
+.B \-f
+option suppresses shell function lookup, as with the \fBcommand\fP builtin.
+.B type
+returns true if all of the arguments are found, false if
+any are not found.
+.TP
+\fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
+.PD 0
+.TP
+\fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
+.PD
+Provides control over the resources available to the shell and to
+processes started by it, on systems that allow such control.
+The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
+set for the given resource.
+A hard limit cannot be increased by a non-root user once it is set;
+a soft limit may be increased up to the value of the hard limit.
+If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
+limits are set.
+The value of
+.I limit
+can be a number in the unit specified for the resource
+or one of the special values
+.BR hard ,
+.BR soft ,
+or
+.BR unlimited ,
+which stand for the current hard limit, the current soft limit, and
+no limit, respectively.
+If
+.I limit
+is omitted, the current value of the soft limit of the resource is
+printed, unless the \fB\-H\fP option is given.  When more than one
+resource is specified, the limit name and unit, if appropriate,
+are printed before the value.
+Other options are interpreted as follows:
+.RS
+.PD 0
+.TP
+.B \-a
+All current limits are reported; no limits are set
+.TP
+.B \-b
+The maximum socket buffer size
+.TP
+.B \-c
+The maximum size of core files created
+.TP
+.B \-d
+The maximum size of a process's data segment
+.TP
+.B \-e
+The maximum scheduling priority ("nice")
+.TP
+.B \-f
+The maximum size of files written by the shell and its children
+.TP
+.B \-i
+The maximum number of pending signals
+.TP
+.B \-k
+The maximum number of kqueues that may be allocated
+.TP
+.B \-l
+The maximum size that may be locked into memory
+.TP
+.B \-m
+The maximum resident set size (many systems do not honor this limit)
+.TP
+.B \-n
+The maximum number of open file descriptors (most systems do not
+allow this value to be set)
+.TP
+.B \-p
+The pipe size in 512-byte blocks (this may not be set)
+.TP
+.B \-q
+The maximum number of bytes in POSIX message queues
+.TP
+.B \-r
+The maximum real-time scheduling priority
+.TP
+.B \-s
+The maximum stack size
+.TP
+.B \-t
+The maximum amount of cpu time in seconds
+.TP
+.B \-u
+The maximum number of processes available to a single user
+.TP
+.B \-v
+The maximum amount of virtual memory available to the shell and, on
+some systems, to its children
+.TP
+.B \-x
+The maximum number of file locks
+.TP
+.B \-P
+The maximum number of pseudoterminals
+.TP
+.B \-R
+The maximum time a real-time process can run before blocking, in microseconds
+.TP
+.B \-T
+The maximum number of threads
+.PD
+.PP
+If
+.I limit
+is given, and the
+.B \-a
+option is not used,
+\fIlimit\fP is the new value of the specified resource.
+If no option is given, then
+.B \-f
+is assumed.  Values are in 1024-byte increments, except for
+.BR \-t ,
+which is in seconds;
+.BR \-R ,
+which is in microseconds;
+.BR \-p ,
+which is in units of 512-byte blocks;
+.BR \-P ,
+.BR \-T ,
+.BR \-b ,
+.BR \-k ,
+.BR \-n ,
+and
+.BR \-u ,
+which are unscaled values;
+and, when in posix mode,
+.B \-c
+and
+.BR \-f ,
+which are in 512-byte increments.
+The return status is 0 unless an invalid option or argument is supplied,
+or an error occurs while setting a new limit.
+.RE
+.TP
+\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
+The user file-creation mask is set to
+.IR mode .
+If
+.I mode
+begins with a digit, it
+is interpreted as an octal number; otherwise
+it is interpreted as a symbolic mode mask similar
+to that accepted by
+.IR chmod (1).
+If
+.I mode
+is omitted, the current value of the mask is printed.
+The
+.B \-S
+option causes the mask to be printed in symbolic form; the
+default output is an octal number.
+If the
+.B \-p
+option is supplied, and
+.I mode
+is omitted, the output is in a form that may be reused as input.
+The return status is 0 if the mode was successfully changed or if
+no \fImode\fP argument was supplied, and false otherwise.
+.TP
+\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
+Remove each \fIname\fP from the list of defined aliases.  If
+.B \-a
+is supplied, all alias definitions are removed.  The return
+value is true unless a supplied
+.I name
+is not a defined alias.
+.TP
+\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...]
+For each
+.IR name ,
+remove the corresponding variable or function.
+If the
+.B \-v
+option is given, each
+.I name
+refers to a shell variable, and that variable is removed.
+Read-only variables may not be unset.
+If
+.B \-f
+is specified, each
+.I name
+refers to a shell function, and the function definition
+is removed.
+If the
+.B \-n
+option is supplied, and \fIname\fP is a variable with the \fInameref\fP
+attribute, \fIname\fP will be unset rather than the variable it
+references.
+\fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
+If no options are supplied, each \fIname\fP refers to a variable; if
+there is no variable by that name, a function with that name, if any, is
+unset.
+Each unset variable or function is removed from the environment
+passed to subsequent commands.
+If any of
+.SM
+.BR BASH_ALIASES ,
+.SM
+.BR BASH_ARGV0 ,
+.SM
+.BR BASH_CMDS ,
+.SM
+.BR BASH_COMMAND ,
+.SM
+.BR BASH_SUBSHELL ,
+.SM
+.BR BASHPID ,
+.SM
+.BR COMP_WORDBREAKS ,
+.SM
+.BR DIRSTACK ,
+.SM
+.BR EPOCHREALTIME ,
+.SM
+.BR EPOCHSECONDS ,
+.SM
+.BR FUNCNAME ,
+.SM
+.BR GROUPS ,
+.SM
+.BR HISTCMD ,
+.SM
+.BR LINENO ,
+.SM
+.BR RANDOM ,
+.SM
+.BR SECONDS ,
+or
+.SM
+.B SRANDOM
+are unset, they lose their special properties, even if they are
+subsequently reset.  The exit status is true unless a
+.I name
+is readonly or may not be unset.
+.TP
+\fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP]
+Wait for each specified child process and return its termination status.
+Each
+.I id
+may be a process
+ID or a job specification; if a job spec is given, all processes
+in that job's pipeline are waited for.  If
+.I id
+is not given,
+\fBwait\fP waits for all running background jobs and
+the last-executed process substitution, if its process id is the same as
+\fB$!\fP,
+and the return status is zero.
+If the \fB\-n\fP option is supplied,
+\fBwait\fP waits for a single job
+from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job,
+to complete and returns its exit status.
+If none of the supplied arguments is a child of the shell, or if no arguments
+are supplied and the shell has no unwaited-for children, the exit status
+is 127.
+If the \fB\-p\fP option is supplied, the process or job identifier of the job
+for which the exit status is returned is assigned to the variable
+\fIvarname\fP named by the option argument.
+The variable will be unset initially, before any assignment.
+This is useful only when the \fB\-n\fP option is supplied.
+Supplying the \fB\-f\fP option, when job control is enabled,
+forces \fBwait\fP to wait for \fIid\fP to terminate before returning
+its status, instead of returning when it changes status.
+If
+.I id
+specifies a non-existent process or job, the return status is 127.
+If \fBwait\fP is interrupted by a signal, the return status will be greater
+than 128, as described under
+.B SIGNALS
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+Otherwise, the return status is the exit status of the last
+process or job waited for.
+.SH "SHELL COMPATIBILITY MODE"
+Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
+specified as a set of options to the shopt builtin (
+.BR compat31 ,
+.BR compat32 ,
+.BR compat40 ,
+.BR compat41 ,
+and so on).
+There is only one current
+compatibility level -- each option is mutually exclusive.
+The compatibility level is intended to allow users to select behavior
+from previous versions that is incompatible with newer versions
+while they migrate scripts to use current features and
+behavior. It's intended to be a temporary solution.
+.PP
+This section does not mention behavior that is standard for a particular
+version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp
+matching operator quotes special regexp characters in the word, which is
+default behavior in bash-3.2 and subsequent versions). 
+.PP
+If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
+compatibility levels up to and including the current compatibility level.
+The idea is that each compatibility level controls behavior that changed
+in that version of \fBbash\fP,
+but that behavior may have been present in earlier versions.
+For instance, the change to use locale-based comparisons with the \fB[[\fP
+command came in bash-4.1, and earlier versions used ASCII-based comparisons,
+so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
+That granularity may not be sufficient for
+all uses, and as a result users should employ compatibility levels carefully.
+Read the documentation for a particular feature to find out the
+current behavior.
+.PP
+Bash-4.3 introduced a new shell variable:
+.SM
+.BR BASH_COMPAT .
+The value assigned
+to this variable (a decimal version number like 4.2, or an integer
+corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
+compatibility level.
+.PP
+Starting with bash-4.4, Bash has begun deprecating older compatibility
+levels.
+Eventually, the options will be removed in favor of
+.SM
+.BR BASH_COMPAT .
+.PP
+Bash-5.0 is the final version for which there will be an individual shopt
+option for the previous version. Users should use
+.SM
+.B BASH_COMPAT
+on bash-5.0 and later versions.
+.PP
+The following table describes the behavior changes controlled by each
+compatibility level setting.
+The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
+compatibility level
+to \fINN\fP using one of the following mechanisms.
+For versions prior to bash-5.0, the compatibility level may be set using
+the corresponding \fBcompat\fP\fINN\fP shopt option.
+For bash-4.3 and later versions, the
+.SM
+.B BASH_COMPAT
+variable is preferred,
+and it is required for bash-5.1 and later versions.
+.TP
+\fBcompat31\fP
+.PD 0
+.RS
+.IP \(bu
+quoting the rhs of the \fB[[\fP command's regexp matching operator (=~)
+has no special effect
+.RE
+.PD
+.TP
+\fBcompat32\fP
+.PD 0
+.RS
+.IP \(bu
+interrupting a command list such as "a ; b ; c" causes the execution
+of the next command in the list (in bash-4.0 and later versions,
+the shell acts as if it received the interrupt, so
+interrupting one command in a list aborts the execution of the
+entire list)
+.RE
+.PD
+.TP
+\fBcompat40\fP
+.PD 0
+.RS
+.IP \(bu
+the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
+consider the current locale when comparing strings; they use ASCII
+ordering.
+Bash versions prior to bash-4.1 use ASCII collation and
+.IR strcmp (3);
+bash-4.1 and later use the current locale's collation sequence and
+.IR strcoll (3).
+.RE
+.PD
+.TP
+\fBcompat41\fP
+.PD 0
+.RS
+.IP \(bu
+in \fIposix\fP mode, \fBtime\fP may be followed by options and still be
+recognized as a reserved word (this is POSIX interpretation 267)
+.IP \(bu
+in \fIposix\fP mode, the parser requires that an even number of single
+quotes occur in the \fIword\fP portion of a double-quoted
+parameter expansion and treats them specially, so that characters within
+the single quotes are considered quoted
+(this is POSIX interpretation 221)
+.RE
+.PD
+.TP
+\fBcompat42\fP
+.PD 0
+.RS
+.IP \(bu
+the replacement string in double-quoted pattern substitution does not
+undergo quote removal, as it does in versions after bash-4.2
+.IP \(bu
+in posix mode, single quotes are considered special when expanding
+the \fIword\fP portion of a double-quoted parameter expansion
+and can be used to quote a closing brace or other special character
+(this is part of POSIX interpretation 221);
+in later versions, single quotes
+are not special within double-quoted word expansions
+.RE
+.PD
+.TP
+\fBcompat43\fP
+.PD 0
+.RS
+.IP \(bu
+the shell does not print a warning message if an attempt is made to
+use a quoted compound assignment as an argument to declare
+(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is
+deprecated
+.IP \(bu
+word expansion errors are considered non-fatal errors that cause the
+current command to fail, even in posix mode
+(the default behavior is to make them fatal errors that cause the shell
+to exit)
+.IP \(bu
+when executing a shell function, the loop state (while/until/etc.)
+is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
+or continue loops in the calling context. Bash-4.4 and later reset
+the loop state to prevent this
+.RE
+.PD
+.TP
+\fBcompat44\fP
+.PD 0
+.RS
+.IP \(bu
+the shell sets up the values used by
+.SM
+.B BASH_ARGV
+and
+.SM
+.B BASH_ARGC
+so they can expand to the shell's positional parameters even if extended
+debugging mode is not enabled
+.IP \(bu
+a subshell inherits loops from its parent context, so \fBbreak\fP
+or \fBcontinue\fP will cause the subshell to exit.
+Bash-5.0 and later reset the loop state to prevent the exit
+.IP \(bu
+variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
+that set attributes continue to affect variables with the same
+name in the calling environment even if the shell is not in posix
+mode
+.RE
+.PD
+.TP
+\fBcompat50\fP
+.PD 0
+.RS
+.IP \(bu
+Bash-5.1 changed the way
+.SM
+.B $RANDOM
+is generated to introduce slightly
+more randomness. If the shell compatibility level is set to 50 or
+lower, it reverts to the method from bash-5.0 and previous versions,
+so seeding the random number generator by assigning a value to
+.SM
+.B RANDOM
+will produce the same sequence as in bash-5.0
+.IP \(bu
+If the command hash table is empty, bash versions prior to bash-5.1
+printed an informational message to that effect, even when producing
+output that can be reused as input. Bash-5.1 suppresses that message
+when the \fB\-l\fP option is supplied.
+.RE
+.PD
+.TP
+\fBcompat51\fP
+.PD 0
+.RS
+.IP \(bu
+The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
+and \fB*\fP differently depending on whether the array is indexed or
+associative, and differently than in previous versions.
+.RE
+.PD
+.\" bash_builtins
+.if \n(zZ=1 .ig zZ
+.SH "RESTRICTED SHELL"
+.\" rbash.1
+.zY
+.PP
+If
+.B bash
+is started with the name
+.BR rbash ,
+or the
+.B \-r
+option is supplied at invocation,
+the shell becomes restricted.
+A restricted shell is used to
+set up an environment more controlled than the standard shell.
+It behaves identically to
+.B bash
+with the exception that the following are disallowed or not performed:
+.IP \(bu
+changing directories with \fBcd\fP
+.IP \(bu
+setting or unsetting the values of
+.SM
+.BR SHELL ,
+.SM
+.BR PATH ,
+.SM
+.BR HISTFILE ,
+.SM
+.BR ENV ,
+or
+.SM
+.B BASH_ENV
+.IP \(bu
+specifying command names containing
+.B /
+.IP \(bu
+specifying a filename containing a
+.B /
+as an argument to the
+.B .
+builtin command
+.IP \(bu
+specifying a filename containing a slash as an argument to the
+.B history
+builtin command
+.IP \(bu
+specifying a filename containing a slash as an argument to the
+.B \-p
+option to the
+.B hash
+builtin command
+.IP \(bu
+importing function definitions from the shell environment at startup
+.IP \(bu
+parsing the value of
+.SM
+.B SHELLOPTS
+from the shell environment at startup
+.IP \(bu
+redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
+.IP \(bu
+using the
+.B exec
+builtin command to replace the shell with another command
+.IP \(bu
+adding or deleting builtin commands with the
+.B \-f
+and
+.B \-d
+options to the
+.B enable
+builtin command
+.IP \(bu
+using the \fBenable\fP builtin command to enable disabled shell builtins
+.IP \(bu
+specifying the
+.B \-p
+option to the
+.B command
+builtin command
+.IP \(bu
+turning off restricted mode with
+\fBset +r\fP or \fBshopt -u restricted_shell\fP.
+.PP
+These restrictions are enforced after any startup files are read.
+.PP
+.ie \n(zY=1 When a command that is found to be a shell script is executed,
+.el \{ When a command that is found to be a shell script is executed
+(see
+.SM
+.B "COMMAND EXECUTION"
+above),
+\}
+.B rbash
+turns off any restrictions in the shell spawned to execute the
+script.
+.\" end of rbash.1
+.if \n(zY=1 .ig zY
+.SH "SEE ALSO"
+.PD 0
+.TP
+\fIBash Reference Manual\fP, Brian Fox and Chet Ramey
+.TP
+\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
+.TP
+\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
+.TP
+\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE --
+http://pubs.opengroup.org/onlinepubs/9699919799/
+.TP
+http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
+.TP
+\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
+.TP
+\fIemacs\fP(1), \fIvi\fP(1)
+.TP
+\fIreadline\fP(3)
+.PD
+.SH FILES
+.PD 0
+.TP
+.FN /bin/bash
+The \fBbash\fP executable
+.TP
+.FN /etc/profile
+The systemwide initialization file, executed for login shells
+.TP
+.FN ~/.bash_profile
+The personal initialization file, executed for login shells
+.TP
+.FN ~/.bashrc
+The individual per-interactive-shell startup file
+.TP
+.FN ~/.bash_logout
+The individual login shell cleanup file, executed when a login shell exits
+.TP
+.FN ~/.bash_history
+The default value of \fBHISTFILE\fP, the file in which bash saves the
+command history
+.TP
+.FN ~/.inputrc
+Individual \fIreadline\fP initialization file
+.PD
+.SH AUTHORS
+Brian Fox, Free Software Foundation
+.br
+bfox@gnu.org
+.PP
+Chet Ramey, Case Western Reserve University
+.br
+chet.ramey@case.edu
+.SH BUG REPORTS
+If you find a bug in
+.B bash,
+you should report it.  But first, you should
+make sure that it really is a bug, and that it appears in the latest
+version of
+.BR bash .
+The latest version is always available from
+\fIftp://ftp.gnu.org/pub/gnu/bash/\fP and
+\fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP.
+.PP
+Once you have determined that a bug actually exists, use the
+.I bashbug
+command to submit a bug report.
+If you have a fix, you are encouraged to mail that as well!
+Suggestions and `philosophical' bug reports may be mailed
+to \fIbug-bash@gnu.org\fP or posted to the Usenet
+newsgroup
+.BR gnu.bash.bug .
+.PP
+ALL bug reports should include:
+.PP
+.PD 0
+.TP 20
+The version number of \fBbash\fR
+.TP
+The hardware and operating system
+.TP
+The compiler used to compile
+.TP
+A description of the bug behaviour
+.TP
+A short script or `recipe' which exercises the bug
+.PD
+.PP
+.I bashbug
+inserts the first three items automatically into the template
+it provides for filing a bug report.
+.PP
+Comments and bug reports concerning
+this manual page should be directed to
+.IR chet.ramey@case.edu .
+.SH BUGS
+It's too big and too slow.
+.PP
+There are some subtle differences between
+.B bash
+and traditional versions of
+.BR sh ,
+mostly because of the
+.SM
+.B POSIX
+specification.
+.PP
+Aliases are confusing in some uses.
+.PP
+Shell builtin commands and functions are not stoppable/restartable.
+.PP
+Compound commands and command sequences of the form `a ; b ; c'
+are not handled gracefully when process suspension is attempted.
+When a process is stopped, the shell immediately executes the next
+command in the sequence.
+It suffices to place the sequence of commands between
+parentheses to force it into a subshell, which may be stopped as
+a unit.
+.PP
+Array variables may not (yet) be exported.
+.PP
+There may be only one active coprocess at a time.
+.zZ
+.zY
diff --git a/upstream/mageia-cauldron/man1/bashbug.1 b/upstream/mageia-cauldron/man1/bashbug.1
new file mode 100644
index 00000000..abcaf482
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bashbug.1
@@ -0,0 +1,67 @@
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\"     Chet Ramey
+.\"     Case Western Reserve University
+.\"     chet@po.cwru.edu
+.\"
+.\"     Last Change: Sun Aug  2 15:39:07 EDT 2020
+.\"
+.TH BASHBUG 1 "2020 August 1" "GNU Bash 5.1"
+.SH NAME
+bashbug \- report a bug in bash
+.SH SYNOPSIS
+\fBbashbug\fP [\fI--version\fP] [\fI--help\fP] [\fIemail-address\fP]
+.SH DESCRIPTION
+.B bashbug
+is a shell script to help the user compose and mail bug reports
+concerning bash in a standard format.
+.B bashbug
+invokes the editor specified by the environment variable
+.SM
+.B EDITOR
+on a temporary copy of the bug report format outline. The user must
+fill in the appropriate fields and exit the editor.
+.B bashbug
+then mails the completed report to \fIbug-bash@gnu.org\fP, or
+\fIemail-address\fP.  If the report cannot be mailed, it is saved in the
+file \fIdead.bashbug\fP in the invoking user's home directory.
+.PP
+The bug report format outline consists of several sections.  The first
+section provides information about the machine, operating system, the
+bash version, and the compilation environment.  The second section
+should be filled in with a description of the bug.  The third section
+should be a description of how to reproduce the bug.  The optional
+fourth section is for a proposed fix.  Fixes are encouraged.
+.SH ENVIRONMENT
+.B bashbug
+will utilize the following environment variables if they exist:
+.TP
+.B EDITOR
+Specifies the preferred editor. If
+.SM
+.B EDITOR
+is not set,
+.B bashbug
+attempts to locate a number of alternative editors, including
+.BR emacs .
+If
+.B bashbug
+cannot locate any of the alternative editors, it attempts to execute \fBvi\fP.
+.TP
+.B HOME
+Directory in which the failed bug report is saved if the mail fails.
+.TP
+.B TMPDIR
+Directory in which to create temporary files and directories.
+.SH "SEE ALSO"
+.TP
+\fIbash\fP(1)
+.SH AUTHORS
+Brian Fox, Free Software Foundation
+.br
+bfox@gnu.org
+.PP
+Chet Ramey, Case Western Reserve University
+.br
+chet@po.cwru.edu
diff --git a/upstream/mageia-cauldron/man1/bc.1 b/upstream/mageia-cauldron/man1/bc.1
new file mode 100644
index 00000000..eeda08be
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bc.1
@@ -0,0 +1,823 @@
+.\"
+.\" bc.1 - the *roff document processor source for the bc manual
+.\"
+.\" This file is part of GNU bc.
+.\" Copyright (C) 1991-1994, 1997, 2000, 2003, 2006, 2017 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 2 of the License , or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; see the file COPYING.  If not, write to:
+.\"   The Free Software Foundation, Inc.
+.\"   51 Franklin Street, Fifth Floor
+.\"   Boston, MA 02110-1301  USA
+.\"
+.\" You may contact the author by:
+.\" e-mail: philnelson@acm.org
+.\" us-mail: Philip A. Nelson
+.\" Computer Science Department, 9062
+.\" Western Washington University
+.\" Bellingham, WA 98226-9062
+.\"
+.\"
+.TH bc 1 "2006-06-11" "GNU Project"
+.SH NAME
+bc - An arbitrary precision calculator language
+.SH SYNTAX
+\fBbc\fR [ \fB-hlwsqv\fR ] [long-options] [ \fI file ...\fR ]
+.SH DESCRIPTION
+\fBbc\fR is a language that supports arbitrary precision numbers
+with interactive execution of statements.  There are some similarities
+in the syntax to the C programming language. 
+A standard math library is available by command line option.
+If requested, the math library is defined before processing any files.
+\fBbc\fR starts by processing code from all the files listed
+on the command line in the order listed.  After all files have been
+processed, \fBbc\fR reads from the standard input.  All code is
+executed as it is read.  (If a file contains a command to halt the
+processor, \fBbc\fR will never read from the standard input.)
+.PP
+This version of \fBbc\fR contains several extensions beyond
+traditional \fBbc\fR implementations and the POSIX draft standard.
+Command line options can cause these extensions to print a warning 
+or to be rejected.  This 
+document describes the language accepted by this processor.
+Extensions will be identified as such.
+.SS OPTIONS
+.IP "-h, --help"
+Print the usage and exit.
+.IP "-i, --interactive"
+Force interactive mode.
+.IP "-l, --mathlib"
+Define the standard math library.
+.IP "-w, --warn"
+Give warnings for extensions to POSIX \fBbc\fR.
+.IP "-s, --standard"
+Process exactly the POSIX \fBbc\fR language.
+.IP "-q, --quiet"
+Do not print the normal GNU bc welcome.
+.IP "-v, --version"
+Print the version number and copyright and quit.
+.SS NUMBERS
+The most basic element in \fBbc\fR is the number.  Numbers are
+arbitrary precision numbers.  This precision is both in the integer
+part and the fractional part.  All numbers are represented internally
+in decimal and all computation is done in decimal.  (This version
+truncates results from divide and multiply operations.)  There are two
+attributes of numbers, the length and the scale.  The length is the
+total number of decimal digits used by \fBbc\fR to represent a number
+and the scale is the total number of decimal digits after the decimal
+point.  For example:
+.nf
+.RS
+ .000001 has a length of 6 and scale of 6.
+ 1935.000 has a length of 7 and a scale of 3.
+.RE
+.fi
+.SS VARIABLES
+Numbers are stored in two types of variables, simple variables and
+arrays.  Both simple variables and array variables are named.  Names
+begin with a letter followed by any number of letters, digits and
+underscores.  All letters must be lower case.  (Full alpha-numeric
+names are an extension. In POSIX \fBbc\fR all names are a single
+lower case letter.)  The type of variable is clear by the context
+because all array variable names will be followed by brackets ([]).
+.PP
+There are four special variables, \fBscale, ibase, obase,\fR and
+\fBlast\fR.  \fBscale\fR defines how some operations use digits after the
+decimal point.  The default value of \fBscale\fR is 0. \fBibase\fR
+and \fBobase\fR define the conversion base for input and output
+numbers.  The default for both input and output is base 10.
+\fBlast\fR (an extension) is a variable that has the value of the last
+printed number.  These will be discussed in further detail where
+appropriate.  All of these variables may have values assigned to them
+as well as used in expressions.
+.SS COMMENTS
+Comments in \fBbc\fR start with the characters \fB/*\fR and end with
+the characters \fB*/\fR.  Comments may start anywhere and appear as a
+single space in the input.  (This causes comments to delimit other
+input items.  For example, a comment can not be found in the middle of
+a variable name.)  Comments include any newlines (end of line) between
+the start and the end of the comment.
+.PP
+To support the use of scripts for \fBbc\fR, a single line comment has been
+added as an extension.  A single line comment starts at a \fB#\fR
+character and continues to the next end of the line.  The end of line
+character is not part of the comment and is processed normally.
+.SS EXPRESSIONS
+The numbers are manipulated by expressions and statements.  Since
+the language was designed to be interactive, statements and expressions
+are executed as soon as possible.  There is no "main" program.  Instead,
+code is executed as it is encountered.  (Functions, discussed in
+detail later, are defined when encountered.)
+.PP
+A simple expression is just a constant. \fBbc\fR converts constants
+into internal decimal numbers using the current input base, specified
+by the variable \fBibase\fR. (There is an exception in functions.)
+The legal values of \fBibase\fR are 2 through 36. (Bases greater than
+16 are an extension.) Assigning a value outside this range to
+\fBibase\fR will result in a value of 2 or 36.  Input numbers may
+contain the characters 0-9 and A-Z. (Note: They must be capitals.
+Lower case letters are variable names.)  Single digit numbers always
+have the value of the digit regardless of the value of
+\fBibase\fR. (i.e. A = 10.)  For multi-digit numbers, \fBbc\fR changes
+all input digits greater or equal to ibase to the value of
+\fBibase\fR-1.  This makes the number \fBZZZ\fR always be the largest
+3 digit number of the input base.
+.PP
+Full expressions are similar to many other high level languages.
+Since there is only one kind of number, there are no rules for mixing
+types.  Instead, there are rules on the scale of expressions.  Every
+expression has a scale.  This is derived from the scale of original
+numbers, the operation performed and in many cases, the value of the
+variable \fBscale\fR. Legal values of the variable \fBscale\fR are
+0 to the maximum number representable by a C integer.
+.PP
+In the following descriptions of legal expressions, "expr" refers to a
+complete expression and "var" refers to a simple or an array variable.
+A simple variable is just a
+.RS
+\fIname\fR
+.RE
+and an array variable is specified as
+.RS
+\fIname\fR[\fIexpr\fR]
+.RE
+Unless specifically
+mentioned the scale of the result is the maximum scale of the
+expressions involved.
+.IP "- expr"
+The result is the negation of the expression.
+.IP "++ var"
+The variable is incremented by one and the new value is the result of
+the expression.
+.IP "-- var"
+The variable
+is decremented by one and the new value is the result of the
+expression.
+.IP "var ++"
+ The result of the expression is the value of
+the variable and then the variable is incremented by one.
+.IP "var --"
+The result of the expression is the value of the variable and then
+the variable is decremented by one.
+.IP "expr + expr"
+The result of the expression is the sum of the two expressions.
+.IP "expr - expr"
+The result of the expression is the difference of the two expressions.
+.IP "expr * expr"
+The result of the expression is the product of the two expressions.
+.IP "expr / expr"
+The result of the expression is the quotient of the two expressions.
+The scale of the result is the value of the variable \fBscale\fR.
+.IP "expr % expr"
+The result of the expression is the "remainder" and it is computed in the
+following way.  To compute a%b, first a/b is computed to \fBscale\fR
+digits.  That result is used to compute a-(a/b)*b to the scale of the
+maximum of \fBscale\fR+scale(b) and scale(a).  If \fBscale\fR is set
+to zero and both expressions are integers this expression is the
+integer remainder function.
+.IP "expr ^ expr"
+The result of the expression is the value of the first raised to the
+second. The second expression must be an integer.  (If the second
+expression is not an integer, a warning is generated and the
+expression is truncated to get an integer value.)  The scale of the
+result is \fBscale\fR if the exponent is negative.  If the exponent
+is positive the scale of the result is the minimum of the scale of the
+first expression times the value of the exponent and the maximum of
+\fBscale\fR and the scale of the first expression.  (e.g. scale(a^b)
+= min(scale(a)*b, max( \fBscale,\fR scale(a))).)  It should be noted
+that expr^0 will always return the value of 1.
+.IP "( expr )"
+This alters the standard precedence to force the evaluation of the
+expression.
+.IP "var = expr"
+The variable is assigned the value of the expression.
+.IP "var <op>= expr"
+This is equivalent to "var = var <op> expr" with the exception that
+the "var" part is evaluated only once.  This can make a difference if
+"var" is an array.
+.PP
+Relational expressions are a special kind of expression
+that always evaluate to 0 or 1, 0 if the relation is false and 1 if
+the relation is true.  These may appear in any legal expression.
+(POSIX bc requires that relational expressions are used only in if,
+while, and for statements and that only one relational test may be
+done in them.)  The relational operators are
+.IP "expr1 < expr2"
+The result is 1 if expr1 is strictly less than expr2.
+.IP "expr1 <= expr2"
+The result is 1 if expr1 is less than or equal to expr2.
+.IP "expr1 > expr2"
+The result is 1 if expr1 is strictly greater than expr2.
+.IP "expr1 >= expr2"
+The result is 1 if expr1 is greater than or equal to expr2.
+.IP "expr1 == expr2"
+The result is 1 if expr1 is equal to expr2.
+.IP "expr1 != expr2"
+The result is 1 if expr1 is not equal to expr2.
+.PP
+Boolean operations are also legal.  (POSIX \fBbc\fR does NOT have
+boolean operations). The result of all boolean operations are 0 and 1
+(for false and true) as in relational expressions.  The boolean
+operators are:
+.IP "!expr"
+The result is 1 if expr is 0.
+.IP "expr && expr"
+The result is 1 if both expressions are non-zero.
+.IP "expr || expr"
+The result is 1 if either expression is non-zero.
+.PP
+The expression precedence is as follows: (lowest to highest)
+.nf
+.RS
+|| operator, left associative
+&& operator, left associative
+! operator, nonassociative
+Relational operators, left associative
+Assignment operator, right associative
++ and - operators, left associative
+*, / and % operators, left associative
+^ operator, right associative
+unary - operator, nonassociative
+++ and -- operators, nonassociative
+.RE
+.fi
+.PP
+This precedence was chosen so that POSIX compliant \fBbc\fR programs
+will run correctly. This will cause the use of the relational and
+logical operators to have some unusual behavior when used with
+assignment expressions.  Consider the expression:
+.RS
+a = 3 < 5
+.RE
+.PP
+Most C programmers would assume this would assign the result of "3 <
+5" (the value 1) to the variable "a".  What this does in \fBbc\fR is
+assign the value 3 to the variable "a" and then compare 3 to 5.  It is
+best to use parenthesis when using relational and logical operators
+with the assignment operators.
+.PP
+There are a few more special expressions that are provided in \fBbc\fR.
+These have to do with user defined functions and standard
+functions.  They all appear as "\fIname\fB(\fIparameters\fB)\fR".
+See the section on functions for user defined functions.  The standard
+functions are:
+.IP "length ( expression )"
+The value of the length function is the number of significant digits in the
+expression.
+.IP "read ( )"
+The read function (an extension) will read a number from the standard
+input, regardless of where the function occurs.   Beware, this can
+cause problems with the mixing of data and program in the standard input.
+The best use for this function is in a previously written program that
+needs input from the user, but never allows program code to be input
+from the user.  The value of the read function is the number read from
+the standard input using the current value of the variable 
+\fBibase\fR for the conversion base.
+.IP "scale ( expression )"
+The value of the scale function is the number of digits after the decimal
+point in the expression.
+.IP "sqrt ( expression )"
+The value of the sqrt function is the square root of the expression.  If
+the expression is negative, a run time error is generated.
+.SS STATEMENTS
+Statements (as in most algebraic languages) provide the sequencing of
+expression evaluation.  In \fBbc\fR statements are executed "as soon
+as possible."  Execution happens when a newline in encountered and
+there is one or more complete statements.  Due to this immediate
+execution, newlines are very important in \fBbc\fR. In fact, both a
+semicolon and a newline are used as statement separators.  An
+improperly placed newline will cause a syntax error.  Because newlines
+are statement separators, it is possible to hide a newline by using
+the backslash character.  The sequence "\e<nl>", where <nl> is the
+newline appears to \fBbc\fR as whitespace instead of a newline.  A
+statement list is a series of statements separated by semicolons and
+newlines.  The following is a list of \fBbc\fR statements and what
+they do: (Things enclosed in brackets ([]) are optional parts of the
+statement.)
+.IP "expression"
+This statement does one of two things.  If the expression starts with
+"<variable> <assignment> ...", it is considered to be an assignment
+statement.  If the expression is not an assignment statement, the
+expression is evaluated and printed to the output.  After the number
+is printed, a newline is printed.  For example, "a=1" is an assignment
+statement and "(a=1)" is an expression that has an embedded
+assignment.  All numbers that are printed are printed in the base
+specified by the variable \fBobase\fR. The legal values for \fB
+obase\fR are 2 through BC_BASE_MAX.  (See the section LIMITS.)  For
+bases 2 through 16, the usual method of writing numbers is used.  For
+bases greater than 16, \fBbc\fR uses a multi-character digit method
+of printing the numbers where each higher base digit is printed as a
+base 10 number.  The multi-character digits are separated by spaces.
+Each digit contains the number of characters required to represent the
+base ten value of "obase-1".  Since numbers are of arbitrary
+precision, some numbers may not be printable on a single output line.
+These long numbers will be split across lines using the "\e" as the
+last character on a line.  The maximum number of characters printed
+per line is 70.  Due to the interactive nature of \fBbc\fR, printing
+a number causes the side effect of assigning the printed value to the
+special variable \fBlast\fR. This allows the user to recover the
+last value printed without having to retype the expression that
+printed the number.  Assigning to \fBlast\fR is legal and will
+overwrite the last printed value with the assigned value.  The newly
+assigned value will remain until the next number is printed or another
+value is assigned to \fBlast\fR.  (Some installations may allow the 
+use of a single period (.) which is not part of a number as a short
+hand notation for for \fBlast\fR.)
+.IP "string"
+The string is printed to the output.  Strings start with a double quote
+character and contain all characters until the next double quote character.
+All characters are take literally, including any newline.  No newline
+character is printed after the string.
+.IP "\fBprint\fR list"
+The print statement (an extension) provides another method of output.
+The "list" is a list of strings and expressions separated by commas.
+Each string or expression is printed in the order of the list.  No
+terminating newline is printed.  Expressions are evaluated and their
+value is printed and assigned to the variable \fBlast\fR. Strings
+in the print statement are printed to the output and may contain
+special characters.  Special characters start with the backslash
+character (\e).  The special characters recognized by \fBbc\fR are
+"a" (alert or bell), "b" (backspace), "f" (form feed), "n" (newline),
+"r" (carriage return), "q" (double quote), "t" (tab), and "\e" (backslash).
+Any other character following the backslash will be ignored.  
+.IP "{ statement_list }"
+This is the compound statement.  It allows multiple statements to be
+grouped together for execution.
+.IP "\fBif\fR ( expression ) statement1 [\fBelse\fR statement2]"
+The if statement evaluates the expression and executes statement1 or
+statement2 depending on the value of the expression.  If the expression
+is non-zero, statement1 is executed.  If statement2 is present and
+the value of the expression is 0, then statement2 is executed.  (The
+else clause is an extension.)
+.IP "\fBwhile\fR ( expression ) statement"
+The while statement will execute the statement while the expression
+is non-zero.  It evaluates the expression before each execution of
+the statement.   Termination of the loop is caused by a zero
+expression value or the execution of a break statement.
+.IP "\fBfor\fR ( [expression1] ; [expression2] ; [expression3] ) statement"
+The for statement controls repeated execution of the statement.  
+Expression1 is evaluated before the loop.  Expression2 is evaluated
+before each execution of the statement.  If it is non-zero, the statement
+is evaluated.  If it is zero, the loop is terminated.  After each
+execution of the statement, expression3 is evaluated before the reevaluation
+of expression2.  If expression1 or expression3 are missing, nothing is
+evaluated at the point they would be evaluated.
+If expression2 is missing, it is the same as substituting
+the value 1 for expression2.  (The optional expressions are an
+extension. POSIX \fBbc\fR requires all three expressions.)
+The following is equivalent code for the for statement:
+.nf
+.RS
+expression1;
+while (expression2) {
+   statement;
+   expression3;
+}
+.RE
+.fi
+.IP "\fBbreak\fR"
+This statement causes a forced exit of the most recent enclosing while
+statement or for statement.
+.IP "\fBcontinue\fR"
+The continue statement (an extension)  causes the most recent enclosing
+for statement to start the next iteration.
+.IP "\fBhalt\fR"
+The halt statement (an extension) is an executed statement that causes
+the \fBbc\fR processor to quit only when it is executed.  For example,
+"if (0 == 1) halt" will not cause \fBbc\fR to terminate because the halt is
+not executed.
+.IP "\fBreturn\fR"
+Return the value 0 from a function.  (See the section on functions.)
+.IP "\fBreturn\fR ( expression )"
+Return the value of the expression from a function.  (See the section on 
+functions.)  As an extension, the parenthesis are not required.
+.SS PSEUDO STATEMENTS
+These statements are not statements in the traditional sense.  They are
+not executed statements.  Their function is performed at "compile" time.
+.IP "\fBlimits\fR"
+Print the local limits enforced by the local version of \fBbc\fR.  This
+is an extension.
+.IP "\fBquit\fR"
+When the quit statement is read, the \fBbc\fR processor
+is terminated, regardless of where the quit statement is found.  For
+example, "if (0 == 1) quit" will cause \fBbc\fR to terminate.
+.IP "\fBwarranty\fR"
+Print a longer warranty notice.  This is an extension.
+.SS FUNCTIONS
+Functions provide a method of defining a computation that can be executed
+later.  Functions in 
+.B bc
+always compute a value and return it to the caller.  Function definitions
+are "dynamic" in the sense that a function is undefined until a definition
+is encountered in the input.  That definition is then used until another
+definition function for the same name is encountered.  The new definition
+then replaces the older definition.  A function is defined as follows:
+.nf
+.RS
+\fBdefine \fIname \fB( \fIparameters \fB) { \fInewline
+\fI    auto_list   statement_list \fB}\fR
+.RE
+.fi
+A function call is just an expression of the form
+"\fIname\fB(\fIparameters\fB)\fR".
+.PP
+Parameters are numbers or arrays (an extension).  In the function definition,
+zero or more parameters are defined by listing their names separated by
+commas.  All parameters are call by value parameters.  
+Arrays are specified in the parameter definition by
+the notation "\fIname\fB[]\fR".   In the function call, actual parameters
+are full expressions for number parameters.  The same notation is used
+for passing arrays as for defining array parameters.  The named array is
+passed by value to the function.  Since function definitions are dynamic,
+parameter numbers and types are checked when a function is called.  Any
+mismatch in number or types of parameters will cause a runtime error.
+A runtime error will also occur for the call to an undefined function.
+.PP
+The \fIauto_list\fR is an optional list of variables that are for
+"local" use.  The syntax of the auto list (if present) is "\fBauto
+\fIname\fR, ... ;".  (The semicolon is optional.)  Each \fIname\fR is
+the name of an auto variable.  Arrays may be specified by using the
+same notation as used in parameters.  These variables have their
+values pushed onto a stack at the start of the function.  The
+variables are then initialized to zero and used throughout the
+execution of the function.  At function exit, these variables are
+popped so that the original value (at the time of the function call)
+of these variables are restored.  The parameters are really auto
+variables that are initialized to a value provided in the function
+call.  Auto variables are different than traditional local variables
+because if function A calls function B, B may access function
+A's auto variables by just using the same name, unless function B has
+called them auto variables.  Due to the fact that auto variables and
+parameters are pushed onto a stack, \fBbc\fR supports recursive functions.
+.PP
+The function body is a list of \fBbc\fR statements.  Again, statements
+are separated by semicolons or newlines.  Return statements cause the
+termination of a function and the return of a value.  There are two
+versions of the return statement.  The first form, "\fBreturn\fR", returns
+the value 0 to the calling expression.  The second form, 
+"\fBreturn ( \fIexpression \fB)\fR", computes the value of the expression
+and returns that value to the calling expression.  There is an implied
+"\fBreturn (0)\fR" at the end of every function.  This allows a function
+to terminate and return 0 without an explicit return statement.
+.PP
+Functions also change the usage of the variable \fBibase\fR.  All
+constants in the function body will be converted using the value of
+\fBibase\fR at the time of the function call.  Changes of \fBibase\fR
+will be ignored during the execution of the function except for the
+standard function \fBread\fR, which will always use the current value
+of \fBibase\fR for conversion of numbers.
+.PP
+Several extensions have been added to functions.  First, the format of
+the definition has been slightly relaxed.  The standard requires the
+opening brace be on the same line as the \fBdefine\fR keyword and all
+other parts must be on following lines.  This version of \fBbc\fR will
+allow any number of newlines before and after the opening brace of the
+function.  For example, the following definitions are legal.
+.nf
+.RS
+\f(CW
+define d (n) { return (2*n); }
+define d (n)
+  { return (2*n); }
+\fR
+.RE
+.fi
+.PP
+Functions may be defined as \fBvoid\fR.  A void
+funtion returns no value and thus may not be used in any place that needs
+a value.  A void function does not produce any output when called by itself
+on an input line.  The key word \fBvoid\fR is placed between the key word
+\fBdefine\fR and the function name.  For example, consider the following
+session.
+.nf
+.RS
+\f(CW
+define py (y) { print "--->", y, "<---", "\en"; }
+define void px (x) { print "--->", x, "<---", "\en"; }
+py(1)
+--->1<---
+0
+px(1)
+--->1<---
+\fR
+.RE
+.fi
+Since \fBpy\fR is not a void function, the call of \fBpy(1)\fR prints
+the desired output and then prints a second line that is the value of
+the function.  Since the value of a function that is not given an
+explicit return statement is zero, the zero is printed.  For \fBpx(1)\fR,
+no zero is printed because the function is a void function.
+.PP
+Also, call by variable for arrays was added.  To declare
+a call by variable array, the declaration of the array parameter in the
+function definition looks like "\fI*name\fB[]\fR".  The call to the
+function remains the same as call by value arrays. 
+.SS MATH LIBRARY
+If \fBbc\fR is invoked with the \fB-l\fR option, a math library is preloaded
+and the default scale is set to 20.   The math functions will calculate their
+results to the scale set at the time of their call.  
+The math library defines the following functions:
+.IP "s (\fIx\fR)"
+The sine of x, x is in radians.
+.IP "c (\fIx\fR)"
+The cosine of x, x is in radians.
+.IP "a (\fIx\fR)"
+The arctangent of x, arctangent returns radians.
+.IP "l (\fIx\fR)"
+The natural logarithm of x.
+.IP "e (\fIx\fR)"
+The exponential function of raising e to the value x.
+.IP "j (\fIn,x\fR)"
+The Bessel function of integer order n of x.
+.SS EXAMPLES
+In /bin/sh,  the following will assign the value of "pi" to the shell
+variable \fBpi\fR.
+.RS
+\f(CW
+pi=$(echo "scale=10; 4*a(1)" | bc -l)
+\fR
+.RE
+.PP
+The following is the definition of the exponential function used in the
+math library.  This function is written in POSIX \fBbc\fR.
+.nf
+.RS
+\f(CW
+scale = 20
+
+/* Uses the fact that e^x = (e^(x/2))^2
+   When x is small enough, we use the series:
+     e^x = 1 + x + x^2/2! + x^3/3! + ...
+*/
+
+define e(x) {
+  auto  a, d, e, f, i, m, v, z
+
+  /* Check the sign of x. */
+  if (x<0) {
+    m = 1
+    x = -x
+  } 
+
+  /* Precondition x. */
+  z = scale;
+  scale = 4 + z + .44*x;
+  while (x > 1) {
+    f += 1;
+    x /= 2;
+  }
+
+  /* Initialize the variables. */
+  v = 1+x
+  a = x
+  d = 1
+
+  for (i=2; 1; i++) {
+    e = (a *= x) / (d *= i)
+    if (e == 0) {
+      if (f>0) while (f--)  v = v*v;
+      scale = z
+      if (m) return (1/v);
+      return (v/1);
+    }
+    v += e
+  }
+}
+\fR
+.RE
+.fi
+.PP
+The following is code that uses the extended features of \fBbc\fR to
+implement a simple program for calculating checkbook balances.  This
+program is best kept in a file so that it can be used many times 
+without having to retype it at every use.
+.nf
+.RS
+\f(CW
+scale=2
+print "\enCheck book program!\en"
+print "  Remember, deposits are negative transactions.\en"
+print "  Exit by a 0 transaction.\en\en"
+
+print "Initial balance? "; bal = read()
+bal /= 1
+print "\en"
+while (1) {
+  "current balance = "; bal
+  "transaction? "; trans = read()
+  if (trans == 0) break;
+  bal -= trans
+  bal /= 1
+}
+quit
+\fR
+.RE
+.fi
+.PP
+The following is the definition of the recursive factorial function.
+.nf
+.RS
+\f(CW
+define f (x) {
+  if (x <= 1) return (1);
+  return (f(x-1) * x);
+}
+\fR
+.RE
+.fi
+.SS READLINE AND LIBEDIT OPTIONS
+GNU \fBbc\fR can be compiled (via a configure option) to use the GNU
+\fBreadline\fR input editor library or the BSD \fBlibedit\fR library.
+This allows the user to do editing of lines before sending them
+to \fBbc\fR.  It also allows for a history of previous lines typed.
+When this option is selected, \fBbc\fR has one more special variable.
+This special variable, \fBhistory\fR is the number of lines of history
+retained.  For \fBreadline\fR, a value of -1 means that an unlimited
+number of history lines are retained.  Setting the value of
+\fBhistory\fR to a positive number restricts the number of history
+lines to the number given.  The value of 0 disables the history
+feature.  The default value is 100. For more information, read the
+user manuals for the GNU \fBreadline\fR, \fBhistory\fR and BSD \fBlibedit\fR
+libraries.  One can not enable both \fBreadline\fR and \fBlibedit\fR
+at the same time.
+.SS DIFFERENCES
+This version of 
+.B bc
+was implemented from the POSIX P1003.2/D11 draft and contains
+several differences and extensions relative to the draft and
+traditional implementations.
+It is not implemented in the traditional way using
+.I dc(1).
+This version is a single process which parses and runs a byte code
+translation of the program.  There is an "undocumented" option (-c)
+that causes the program to output the byte code to
+the standard output instead of running it.  It was mainly used for
+debugging the parser and preparing the math library.
+.PP
+A major source of differences is
+extensions, where a feature is extended to add more functionality and
+additions, where new features are added. 
+The following is the list of differences and extensions.
+.IP "LANG environment"
+This version does not conform to the POSIX standard in the processing
+of the LANG environment variable and all environment variables starting
+with LC_.
+.IP "names"
+Traditional and POSIX
+.B bc
+have single letter names for functions, variables and arrays.  They have
+been extended to be multi-character names that start with a letter and
+may contain letters, numbers and the underscore character.
+.IP "Strings"
+Strings are not allowed to contain NUL characters.  POSIX says all characters
+must be included in strings.
+.IP "last"
+POSIX \fBbc\fR does not have a \fBlast\fR variable.  Some implementations
+of \fBbc\fR use the period (.) in a similar way.  
+.IP "comparisons"
+POSIX \fBbc\fR allows comparisons only in the if statement, the while
+statement, and the second expression of the for statement.  Also, only
+one relational operation is allowed in each of those statements.
+.IP "if statement, else clause"
+POSIX \fBbc\fR does not have an else clause.
+.IP "for statement"
+POSIX \fBbc\fR requires all expressions to be present in the for statement.
+.IP "&&, ||, !"
+POSIX \fBbc\fR does not have the logical operators.
+.IP "read function"
+POSIX \fBbc\fR does not have a read function.
+.IP "print statement"
+POSIX \fBbc\fR does not have a print statement .
+.IP "continue statement"
+POSIX \fBbc\fR does not have a continue statement.
+.IP "return statement"
+POSIX \fBbc\fR requires parentheses around the return expression.
+.IP "array parameters"
+POSIX \fBbc\fR does not (currently) support array parameters in full.
+The POSIX grammar allows for arrays in function definitions, but does
+not provide a method to specify an array as an actual parameter.  (This
+is most likely an oversight in the grammar.)  Traditional implementations
+of \fBbc\fR have only call by value array parameters.
+.IP "function format"
+POSIX \fBbc\fR requires the opening brace on the same line as the 
+\fBdefine\fR key word and the \fBauto\fR statement on the next line.
+.IP "=+, =-, =*, =/, =%, =^"
+POSIX \fBbc\fR does not require these "old style" assignment operators to
+be defined.  This version may allow these "old style" assignments.  Use
+the limits statement to see if the installed version supports them.  If
+it does support the "old style" assignment operators, the statement
+"a =- 1" will decrement \fBa\fR by 1 instead of setting \fBa\fR to the
+value -1.
+.IP "spaces in numbers"
+Other implementations of \fBbc\fR allow spaces in numbers.  For example,
+"x=1 3" would assign the value 13 to the variable x.  The same statement
+would cause a syntax error in this version of \fBbc\fR.
+.IP "errors and execution"
+This implementation varies from other implementations in terms of what
+code will be executed when syntax and other errors are found in the
+program.  If a syntax error is found in a function definition, error
+recovery tries to find the beginning of a statement and continue to
+parse the function.  Once a syntax error is found in the function, the
+function will not be callable and becomes undefined.
+Syntax errors in the interactive execution code will invalidate the
+current execution block.  The execution block is terminated by an
+end of line that appears after a complete sequence of statements.
+For example, 
+.nf
+.RS
+a = 1
+b = 2
+.RE
+.fi
+has two execution blocks and
+.nf
+.RS
+{ a = 1
+  b = 2 }
+.RE
+.fi
+has one execution block.  Any runtime error will terminate the execution
+of the current execution block.  A runtime warning will not terminate the
+current execution block.
+.IP "Interrupts"
+During an interactive session, the SIGINT signal (usually generated by
+the control-C character from the terminal) will cause execution of the
+current execution block to be interrupted.  It will display a "runtime"
+error indicating which function was interrupted.  After all runtime
+structures have been cleaned up, a message will be printed to notify the
+user that \fBbc\fR is ready for more input.  All previously defined functions
+remain defined and the value of all non-auto variables are the value at
+the point of interruption.  All auto variables and function parameters
+are removed during the
+clean up process.  During a non-interactive
+session, the SIGINT signal will terminate the entire run of \fBbc\fR.
+.SS LIMITS
+The following are the limits currently in place for this 
+.B bc
+processor.  Some of them may have been changed by an installation.
+Use the limits statement to see the actual values.
+.IP "BC_BASE_MAX"
+The maximum output base is currently set at 999.  The maximum input base
+is 16.
+.IP "BC_DIM_MAX"
+This is currently an arbitrary limit of 65535 as distributed.  Your
+installation may be different.
+.IP "BC_SCALE_MAX"
+The number of digits after the decimal point is limited to INT_MAX digits.
+Also, the number of digits before the decimal point is limited to INT_MAX
+digits.
+.IP "BC_STRING_MAX"
+The limit on the number of characters in a string is INT_MAX characters.
+.IP "exponent"
+The value of the exponent in the raise operation (^) is limited to LONG_MAX.
+.IP "variable names"
+The current limit on the number of unique names is 32767 for each of
+simple variables, arrays and functions.
+.SH ENVIRONMENT VARIABLES
+The following environment variables are processed by \fBbc\fR:
+.IP "POSIXLY_CORRECT"
+This is the same as the \fB-s\fR option.
+.IP "BC_ENV_ARGS"
+This is another mechanism to get arguments to \fBbc\fR.  The
+format is the same as the command line arguments.  These arguments
+are processed first, so any files listed in the environment arguments
+are processed before any command line argument files.  This allows
+the user to set up "standard" options and files to be processed
+at every invocation of \fBbc\fR.  The files in the environment
+variables would typically contain function definitions for functions
+the user wants defined every time \fBbc\fR is run.
+.IP "BC_LINE_LENGTH"
+This should be an integer specifying the number of characters in an
+output line for numbers. This includes the backslash and newline characters
+for long numbers.  As an extension, the value of zero disables the 
+multi-line feature.  Any other value of this variable that is less than
+3 sets the line length to 70.
+.SH DIAGNOSTICS
+If any file on the command line can not be opened, \fBbc\fR will report
+that the file is unavailable and terminate.  Also, there are compile
+and run time diagnostics that should be self-explanatory.
+.SH BUGS
+Error recovery is not very good yet.
+.PP
+Email bug reports to
+.BR bug-bc@gnu.org .
+Be sure to include the word ``bc'' somewhere in the ``Subject:'' field.
+.SH AUTHOR
+.nf
+Philip A. Nelson
+philnelson@acm.org
+.fi
+.SH ACKNOWLEDGEMENTS
+The author would like to thank Steve Sommars (Steve.Sommars@att.com) for
+his extensive help in testing the implementation.  Many great suggestions
+were given.  This is a much better product due to his involvement.
diff --git a/upstream/mageia-cauldron/man1/bioradtopgm.1 b/upstream/mageia-cauldron/man1/bioradtopgm.1
new file mode 100644
index 00000000..7f24e015
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bioradtopgm.1
@@ -0,0 +1,66 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Bioradtopbm User Manual" 0 "28 June 1993" "netpbm documentation"
+
+.SH NAME
+bioradtopgm - convert a Biorad confocal file into a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBbioradtopgm\fP
+[\fB-image#\fP]
+[\fIimagedata\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBbioradtopgm\fP reads a Biorad confocal file as input and
+produces a PGM image as output.  If the resulting image is upside
+down, run it through \fBpamflip -tb\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBbioradtopgm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-image#\fP
+A Biorad image file may contain more than one image. With this option,
+you can specify which image to extract (only one at a time). The first
+image in the file has number zero. If no
+image number is supplied, only information about the image size and
+the number of images in the input is printed out. No output is produced.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamflip" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1993 by Oliver Trepte
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/bioradtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/bison.1 b/upstream/mageia-cauldron/man1/bison.1
new file mode 100644
index 00000000..de34f222
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bison.1
@@ -0,0 +1,288 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH BISON "1" "February 2023" "GNU Bison 3.8.2" "User Commands"
+.SH NAME
+bison \- GNU Project parser generator (yacc replacement)
+.SH SYNOPSIS
+.B bison
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR
+.SH DESCRIPTION
+.I Bison
+is a parser generator in the style of
+.IR yacc (1).
+It should be upwardly compatible with input files designed
+for
+.IR yacc .
+.PP
+Input files should follow the
+.I yacc
+convention of ending in
+.BR .y .
+Unlike
+.IR yacc ,
+the generated files do not have fixed names, but instead use the prefix
+of the input file.
+Moreover, if you need to put
+.I C++
+code in the input file, you can end his name by a C++-like extension
+(.ypp or .y++), then bison will follow your extension to name the
+output file (.cpp or .c++).
+For instance, a grammar description file named
+.B parse.yxx
+would produce the generated parser in a file named
+.BR parse.tab.cxx ,
+instead of
+.IR yacc 's
+.B y.tab.c
+or old
+.I Bison
+version's
+.BR parse.tab.c .
+.PP
+This description of the options that can be given to
+.I bison
+is adapted from the node
+.B Invocation
+in the
+.B bison.texi
+manual, which should be taken as authoritative.
+.PP
+.I Bison
+supports both traditional single-letter options and mnemonic long
+option names.  Long option names are indicated with
+.B \-\-
+instead of
+.BR \- .
+Abbreviations for option names are allowed as long as they
+are unique.  When a long option takes an argument, like
+.BR \-\-file-prefix ,
+connect the option name and the argument with
+.BR = .
+.PP
+Generate a deterministic LR or generalized LR (GLR) parser employing
+LALR(1), IELR(1), or canonical LR(1) parser tables.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+The same is true for optional arguments.
+.SS "Operation Modes:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-\-print\-localedir\fR
+output directory containing locale\-dependent data
+and exit
+.TP
+\fB\-\-print\-datadir\fR
+output directory containing skeletons and XSLT
+and exit
+.TP
+\fB\-u\fR, \fB\-\-update\fR
+apply fixes to the source grammar file and exit
+.TP
+\fB\-f\fR, \fB\-\-feature\fR[=\fI\,FEATURES\/\fR]
+activate miscellaneous features
+.SS "FEATURES is a list of comma separated words that can include:"
+.TP
+caret, diagnostics\-show\-caret
+show errors with carets
+.TP
+fixit, diagnostics\-parseable\-fixits
+show machine\-readable fixes
+.TP
+syntax\-only
+do not generate any file
+.TP
+all
+all of the above
+.TP
+none
+disable all of the above
+.SS "Diagnostics:"
+.TP
+\fB\-W\fR, \fB\-\-warnings\fR[=\fI\,CATEGORY\/\fR]
+report the warnings falling in CATEGORY
+.TP
+\fB\-\-color\fR[=\fI\,WHEN\/\fR]
+whether to colorize the diagnostics
+.TP
+\fB\-\-style\fR=\fI\,FILE\/\fR
+specify the CSS FILE for colorizer diagnostics
+.SS "Warning categories include:"
+.TP
+conflicts\-sr
+S/R conflicts (enabled by default)
+.TP
+conflicts\-rr
+R/R conflicts (enabled by default)
+.TP
+counterexamples, cex
+generate conflict counterexamples
+.TP
+dangling\-alias
+string aliases not attached to a symbol
+.TP
+deprecated
+obsolete constructs
+.TP
+empty\-rule
+empty rules without %empty
+.TP
+midrule\-values
+unset or unused midrule values
+.TP
+precedence
+useless precedence and associativity
+.TP
+yacc
+incompatibilities with POSIX Yacc
+.TP
+other
+all other warnings (enabled by default)
+.TP
+all
+all the warnings except 'counterexamples', 'dangling\-alias' and 'yacc'
+.TP
+no\-CATEGORY
+turn off warnings in CATEGORY
+.TP
+none
+turn off all the warnings
+.TP
+error[=CATEGORY]
+treat warnings as errors
+.SS "WHEN can be one of the following:"
+.TP
+always, yes
+colorize the output
+.TP
+never, no
+don't colorize the output
+.TP
+auto, tty
+colorize if the output device is a tty
+.SS "Tuning the Parser:"
+.TP
+\fB\-L\fR, \fB\-\-language\fR=\fI\,LANGUAGE\/\fR
+specify the output programming language
+.TP
+\fB\-S\fR, \fB\-\-skeleton\fR=\fI\,FILE\/\fR
+specify the skeleton to use
+.TP
+\fB\-t\fR, \fB\-\-debug\fR
+instrument the parser for tracing
+same as '\-Dparse.trace'
+.TP
+\fB\-\-locations\fR
+enable location support
+.TP
+\fB\-D\fR, \fB\-\-define=NAME\fR[=\fI\,VALUE\/\fR]
+similar to '%define NAME VALUE'
+.TP
+\fB\-F\fR, \fB\-\-force\-define=NAME\fR[=\fI\,VALUE\/\fR]
+override '%define NAME VALUE'
+.TP
+\fB\-p\fR, \fB\-\-name\-prefix\fR=\fI\,PREFIX\/\fR
+prepend PREFIX to the external symbols
+deprecated by '\-Dapi.prefix={PREFIX}'
+.TP
+\fB\-l\fR, \fB\-\-no\-lines\fR
+don't generate '#line' directives
+.TP
+\fB\-k\fR, \fB\-\-token\-table\fR
+include a table of token names
+.TP
+\fB\-y\fR, \fB\-\-yacc\fR
+emulate POSIX Yacc
+.SS "Output Files:"
+.TP
+\fB\-H\fR, \fB\-\-header\fR=\fI\,[FILE]\/\fR
+also produce a header file
+.TP
+\fB\-d\fR
+likewise but cannot specify FILE (for POSIX Yacc)
+.TP
+\fB\-r\fR, \fB\-\-report\fR=\fI\,THINGS\/\fR
+also produce details on the automaton
+.TP
+\fB\-\-report\-file\fR=\fI\,FILE\/\fR
+write report to FILE
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+same as '\-\-report=state'
+.TP
+\fB\-b\fR, \fB\-\-file\-prefix\fR=\fI\,PREFIX\/\fR
+specify a PREFIX for output files
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+leave output to FILE
+.TP
+\fB\-g\fR, \fB\-\-graph\fR[=\fI\,FILE\/\fR]
+also output a graph of the automaton
+.TP
+\fB\-\-html\fR[=\fI\,FILE\/\fR]
+also output an HTML report of the automaton
+.TP
+\fB\-x\fR, \fB\-\-xml\fR[=\fI\,FILE\/\fR]
+also output an XML report of the automaton
+.TP
+\fB\-M\fR, \fB\-\-file\-prefix\-map\fR=\fI\,OLD=NEW\/\fR replace prefix OLD with NEW when writing file paths
+in output files
+.SS "THINGS is a list of comma separated words that can include:"
+.TP
+states
+describe the states
+.TP
+itemsets
+complete the core item sets with their closure
+.TP
+lookaheads
+explicitly associate lookahead tokens to items
+.TP
+solved
+describe shift/reduce conflicts solving
+.TP
+counterexamples, cex
+generate conflict counterexamples
+.TP
+all
+include all the above information
+.TP
+none
+disable the report
+.SH AUTHOR
+Written by Robert Corbett and Richard Stallman.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-bison@gnu.org>.
+.br
+GNU Bison home page: <https://www.gnu.org/software/bison/>.
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>.
+.PP
+.br
+Report translation bugs to <https://translationproject.org/team/>.
+.br
+For complete documentation, run: info bison.
+.SH COPYRIGHT
+Copyright \(co 2021 Free Software Foundation, Inc.
+.br
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.BR lex (1),
+.BR flex (1),
+.BR yacc (1).
+.PP
+The full documentation for
+.B bison
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B bison
+programs are properly installed at your site, the command
+.IP
+.B info bison
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/bmptopnm.1 b/upstream/mageia-cauldron/man1/bmptopnm.1
new file mode 100644
index 00000000..bd8777cb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bmptopnm.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Bmptopnm User Manual" 0 "05 December 2018" "netpbm documentation"
+
+.SH NAME
+bmptopnm - convert a BMP file into a PBM, PGM, or PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBbmptopnm\fP
+
+[\fB-verbose\fP]
+
+[\fIbmpfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBbmptopnm\fP reads a Microsoft Windows or OS/2 BMP file as
+input.  and produces a PBM, PGM, or PNM image as output.  If the input
+is colormapped and contains only black and white, the output is PBM.
+If the input is colormapped and contains only black white and gray,
+the output is PGM.  Otherwise, the output is PPM.
+.PP
+\fBbmptopnm\fP understands BMP files compressed with run length
+encoding (RLE4/RLE8), but not if that encoding includes a "delta"
+(which is rare).  \fBbmptopnm\fP recognizes the delta and issues an
+error message.
+.PP
+Before Netpbm 10.75 (June 2016), \fBbmptopnm\fP could not convert
+Version 4 or Version 5 Windows BMP images.
+.PP
+\fBbmptopnm\fP cannot convert BMP files compressed with JPEG or PNG
+encoding.  It recognizes the compression and issues an error message.  Before
+Netpbm 10.32 (February 2006), \fBbmptopnm\fP couldn't convert RLE8 BMP files
+either, and before Netpbm 10.85 (December 2018), it couldn't convert RLE4
+(between 10.32 and 10.85, it would act like it recognized the format, but
+produce garbage output).
+.PP
+Before Netpbm 10.18 (September 2003), this program could not convert
+BMP images with the BI_BITFIELDS format ("compression type").  It would
+recognize the format and issue an error message.
+.PP
+\fBbmptopnm\fP cannot convert OS/2 BMP files with 16 bits per
+pixel (only because the author did not have a complete specification
+for them).  It recognizes the format and issues an error message.
+Before Netpbm 10.16 (June 2003), it also could not convert Windows BMP
+files with 16 bits per pixel.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBbmptopnm\fP recognizes the following
+command line option:
+
+
+
+.TP
+\fB-verbose\fP
+Report contents of the BMP header to the standard error.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtobmp" (1)\c
+\&,
+.BR "ppmtowinicon" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992 by David W. Sanderson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/bmptopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/bmptoppm.1 b/upstream/mageia-cauldron/man1/bmptoppm.1
new file mode 100644
index 00000000..cb49f7aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bmptoppm.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Bmptoppm User Manual" 0 "March 2002" "netpbm documentation"
+
+.SH NAME
+
+bmptoppm - replaced by bmptopnm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBbmptoppm\fP was replaced in Netpbm 9.25 (March 2002) by
+.BR "bmptopnm" (1)\c
+\&.
+.PP
+\fBbmptopnm\fP is backward compatible with \fBbmptoppm\fP except that
+it generates PBM and PGM output when it is more appropriate than PPM.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/bmptoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/bootctl.1 b/upstream/mageia-cauldron/man1/bootctl.1
new file mode 100644
index 00000000..945a1a98
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bootctl.1
@@ -0,0 +1,682 @@
+'\" t
+.TH "BOOTCTL" "1" "" "systemd 255" "bootctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+bootctl \- Control EFI firmware boot settings and manage boot loader
+.SH "SYNOPSIS"
+.HP \w'\fBbootctl\fR\ 'u
+\fBbootctl\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+\fBbootctl\fR
+can check the EFI firmware and boot loader status, list and manage available boot loaders and boot loader entries, and install, update, or remove the
+\fBsystemd-boot\fR(7)
+boot loader on the current system\&.
+.SH "GENERIC EFI FIRMWARE/BOOT LOADER COMMANDS"
+.PP
+These commands are available on any EFI system, regardless of the boot loader used\&.
+.PP
+\fBstatus\fR
+.RS 4
+Shows brief information about the system firmware, the boot loader that was used to boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware\*(Aqs list of boot loaders and the current default boot loader entry\&. If no command is specified, this is the implied default\&.
+.sp
+See the example below for details of the output\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBreboot\-to\-firmware\fR [\fIBOOL\fR]
+.RS 4
+Query or set the "Reboot\-Into\-Firmware\-Setup" flag of the EFI firmware\&. Takes a boolean argument which controls whether to show the firmware setup on next system reboot\&. If the argument is omitted shows the current status of the flag, or whether the flag is supported\&. This controls the same flag as
+\fBsystemctl reboot \-\-firmware\-setup\fR, but is more low\-level and allows setting the flag independently from actually requesting a reboot\&.
+.sp
+Hint: use
+\fBsystemctl reboot \-\-firmware\-setup\fR
+to reboot into firmware setup once\&. See
+\fBsystemctl\fR(1)
+for details\&.
+.sp
+Added in version 251\&.
+.RE
+.SH "BOOT LOADER SPECIFICATION COMMANDS"
+.PP
+These commands are available for all boot loaders that implement the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, such as
+\fBsystemd\-boot\fR\&.
+.PP
+\fBlist\fR
+.RS 4
+Shows all available boot loader entries implementing the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, as well as any other entries discovered or automatically generated by a boot loader implementing the
+\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2\&. JSON output may be requested with
+\fB\-\-json=\fR\&.
+.sp
+See the example below for details of the output\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBunlink\fR \fIID\fR
+.RS 4
+Removes a boot loader entry including the files it refers to\&. Takes a single boot loader entry ID string or a glob pattern as argument\&. Referenced files such as kernel or initrd are only removed if no other entry refers to them\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fBcleanup\fR
+.RS 4
+Removes files from the ESP and XBOOTLDR partitions that belong to the entry token but are not referenced in any boot loader entries\&.
+.sp
+Added in version 253\&.
+.RE
+.SH "BOOT LOADER INTERFACE COMMANDS"
+.PP
+These commands are available for all boot loaders that implement the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
+and the
+\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2, such as
+\fBsystemd\-boot\fR\&.
+.PP
+\fBset\-default\fR \fIID\fR, \fBset\-oneshot\fR \fIID\fR
+.RS 4
+Sets the default boot loader entry\&. Takes a single boot loader entry ID string or a glob pattern as argument\&. The
+\fBset\-oneshot\fR
+command will set the default entry only for the next boot, the
+\fBset\-default\fR
+will set it persistently for all future boots\&.
+.sp
+\fBbootctl list\fR
+can be used to list available boot loader entries and their IDs\&.
+.sp
+In addition, the boot loader entry ID may be specified as one of:
+\fB@default\fR,
+\fB@oneshot\fR
+or
+\fB@current\fR, which correspond to the current default boot loader entry for all future boots, the current default boot loader entry for the next boot, and the currently booted boot loader entry\&. These special IDs are resolved to the current values of the EFI variables
+\fILoaderEntryDefault\fR,
+\fILoaderEntryOneShot\fR
+and
+\fILoaderEntrySelected\fR, see
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
+for details\&. These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot loader entry for all future boots, but may be used for other operations too\&.
+.sp
+If set to
+\fB@saved\fR
+the chosen entry will be saved as an EFI variable on every boot and automatically selected the next time the boot loader starts\&.
+.sp
+When an empty string ("") is specified as the ID, then the corresponding EFI variable will be unset\&.
+.sp
+Hint: use
+\fBsystemctl reboot \-\-boot\-loader\-entry=\fR\fB\fIID\fR\fR
+to reboot into a specific boot entry and
+\fBsystemctl reboot \-\-boot\-loader\-menu=\fR\fB\fItimeout\fR\fR
+to reboot into the boot loader menu once\&. See
+\fBsystemctl\fR(1)
+for details\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fBset\-timeout\fR \fITIMEOUT\fR, \fBset\-timeout\-oneshot\fR \fITIMEOUT\fR
+.RS 4
+Sets the boot loader menu timeout in seconds\&. The
+\fBset\-timeout\-oneshot\fR
+command will set the timeout only for the next boot\&. See
+\fBsystemd.time\fR(7)
+for details about the syntax of time spans\&.
+.sp
+If this is set to
+\fBmenu\-disabled\fR
+or
+\fBmenu\-hidden\fR
+or
+\fB0\fR, no menu is shown and the default entry will be booted immediately, while setting this to
+\fBmenu\-force\fR
+disables the timeout while always showing the menu\&. When an empty string ("") is specified the bootloader will revert to its default menu timeout\&.
+.sp
+Added in version 250\&.
+.RE
+.SH "SYSTEMD\-BOOT COMMANDS"
+.PP
+These commands manage the
+\fBsystemd\-boot\fR
+EFI boot loader, and do not work in conjunction with other boot loaders\&.
+.PP
+\fBinstall\fR
+.RS 4
+Installs
+\fBsystemd\-boot\fR
+into the EFI system partition\&. A copy of
+\fBsystemd\-boot\fR
+will be stored as the EFI default/fallback loader at
+\fIESP\fR/EFI/BOOT/BOOT*\&.EFI\&. The boot loader is then added to the top of the firmware\*(Aqs boot loader list\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBupdate\fR
+.RS 4
+Updates all installed versions of
+\fBsystemd-boot\fR(7), if the available version is newer than the version installed in the EFI system partition\&. This also includes the EFI default/fallback loader at
+\fIESP\fR/EFI/BOOT/BOOT*\&.EFI\&. The boot loader is then added to end of the firmware\*(Aqs boot loader list if missing\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBremove\fR
+.RS 4
+Removes all installed versions of
+\fBsystemd\-boot\fR
+from the EFI system partition and the firmware\*(Aqs boot loader list\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBis\-installed\fR
+.RS 4
+Checks whether
+\fBsystemd\-boot\fR
+is installed in the ESP\&. Note that a single ESP might host multiple boot loaders; this hence checks whether
+\fBsystemd\-boot\fR
+is one (of possibly many) installed boot loaders \(em and neither whether it is the default nor whether it is registered in any EFI variables\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fBrandom\-seed\fR
+.RS 4
+Generates a random seed and stores it in the EFI System Partition (ESP), for use by the
+\fBsystemd\-boot\fR
+boot loader\&. If a random seed already exists in the ESP it is refreshed\&. Also generates a random \*(Aqsystem token\*(Aq and stores it persistently as an EFI variable, if one has not been set before\&. If the boot loader finds the random seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the OS and a new seed to store in the ESP from the combination of both\&. The random seed passed to the OS is credited to the kernel\*(Aqs entropy pool by the system manager during early boot, and permits userspace to boot up with an entropy pool fully initialized very early on\&. Also see
+\fBsystemd-boot-random-seed.service\fR(8)\&.
+.sp
+See
+\m[blue]\fBRandom Seeds\fR\m[]\&\s-2\u[3]\d\s+2
+for further information\&.
+.sp
+Added in version 243\&.
+.RE
+.SH "KERNEL IMAGE COMMANDS"
+.PP
+\fBkernel\-identify\fR \fIkernel\fR
+.RS 4
+Takes a kernel image as argument\&. Checks what kind of kernel the image is\&. Returns one of
+"uki",
+"pe", and
+"unknown"\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fBkernel\-inspect\fR \fIkernel\fR
+.RS 4
+Takes a kernel image as argument\&. Prints details about the image\&.
+.sp
+Added in version 253\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-esp\-path=\fR
+.RS 4
+Path to the EFI System Partition (ESP)\&. If not specified,
+/efi/,
+/boot/, and
+/boot/efi/
+are checked in turn\&. It is recommended to mount the ESP to
+/efi/, if possible\&.
+.RE
+.PP
+\fB\-\-boot\-path=\fR
+.RS 4
+Path to the Extended Boot Loader partition, as defined in the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. If not specified,
+/boot/
+is checked\&. It is recommended to mount the Extended Boot Loader partition to
+/boot/, if possible\&.
+.RE
+.PP
+\fB\-\-root=\fR\fB\fIroot\fR\fR
+.RS 4
+Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
+\fIroot\fR
+path, including config search paths\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIimage\fR\fR
+.RS 4
+Takes a path to a disk image file or block device node\&. If specified, all operations are applied to file system in the indicated disk image\&. This option is similar to
+\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[4]\d\s+2\&. For further information on supported disk images, see
+\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-install\-source=\fR
+.RS 4
+When installing binaries with
+\fB\-\-root=\fR
+or
+\fB\-\-image=\fR, selects where to source them from\&. Takes one of
+"auto"
+(the default),
+"image"
+or
+"host"\&. With
+"auto"
+binaries will be picked from the specified directory or image, and if not found they will be picked from the host\&. With
+"image"
+or
+"host"
+no fallback search will be performed if the binaries are not found in the selected source\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-print\-esp\-path\fR
+.RS 4
+This option modifies the behaviour of
+\fBstatus\fR\&. Only prints the path to the EFI System Partition (ESP) to standard output and exits\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-print\-boot\-path\fR
+.RS 4
+This option modifies the behaviour of
+\fBstatus\fR\&. Only prints the path to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard output and exit\&. This command is useful to determine where to place boot loader entries, as they are preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise\&.
+.sp
+Boot Loader Specification Type #1 entries should generally be placed in the directory
+"$(bootctl \-x)/loader/entries/"\&. Existence of that directory may also be used as indication that boot loader entry support is available on the system\&. Similarly, Boot Loader Specification Type #2 entries should be placed in the directory
+"$(bootctl \-x)/EFI/Linux/"\&.
+.sp
+Note that this option (similarly to the
+\fB\-\-print\-boot\-path\fR
+option mentioned above), is available independently from the boot loader used, i\&.e\&. also without
+\fBsystemd\-boot\fR
+being installed\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-print\-root\-device\fR
+.RS 4
+Print the path to the block device node backing the root file system of the local OS\&. This prints a path such as
+/dev/nvme0n1p5\&. If the root file system is backed by dm\-crypt/LUKS or dm\-verity the underlying block device is returned\&. If the root file system is backed by multiple block devices (as supported by btrfs) the operation will fail\&. If the switch is specified twice (i\&.e\&.
+\fB\-RR\fR) and the discovered block device is a partition device the "whole" block device it belongs to is determined and printed (e\&.g\&.
+/dev/nvme0n1)\&. If the root file system is
+"tmpfs"
+(or a similar in\-memory file system), the block device backing
+/usr/
+is returned if applicable\&. If the root file system is a network file system (e\&.g\&. NFS, CIFS) the operation will fail\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-no\-variables\fR
+.RS 4
+Do not touch the firmware\*(Aqs boot loader list stored in EFI variables\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-graceful\fR
+.RS 4
+Ignore failure when the EFI System Partition cannot be found, when EFI variables cannot be written, or a different or newer boot loader is already installed\&. Currently only applies to
+\fBis\-installed\fR,
+\fBupdate\fR, and
+\fBrandom\-seed\fR
+verbs\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppress printing of the results of various commands and also the hints about ESP being unavailable\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-make\-entry\-directory=yes|no\fR
+.RS 4
+Controls creation and deletion of the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
+Type #1 entry directory on the file system containing resources such as kernel and initrd images during
+\fBinstall\fR
+and
+\fBremove\fR, respectively\&. The directory is named after the entry token, as specified with
+\fB\-\-entry\-token=\fR
+parameter described below, and is placed immediately below the
+\fI$BOOT\fR
+root directory (i\&.e\&. beneath the file system returned by the
+\fB\-\-print\-boot\-path\fR
+option, see above)\&. Defaults to
+"no"\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-entry\-token=\fR
+.RS 4
+Controls how to name and identify boot loader entries for this OS installation\&. Accepted during
+\fBinstall\fR, and takes one of
+"auto",
+"machine\-id",
+"os\-id",
+"os\-image\-id"
+or an arbitrary string prefixed by
+"literal:"
+as argument\&.
+.sp
+If set to
+\fBmachine\-id\fR
+the entries are named after the machine ID of the running system (e\&.g\&.
+"b0e793a9baf14b5fa13ecbe84ff637ac")\&. See
+\fBmachine-id\fR(5)
+for details about the machine ID concept and file\&.
+.sp
+If set to
+\fBos\-id\fR
+the entries are named after the OS ID of the running system, i\&.e\&. the
+\fIID=\fR
+field of
+\fBos-release\fR(5)
+(e\&.g\&.
+"fedora")\&. Similarly, if set to
+\fBos\-image\-id\fR
+the entries are named after the OS image ID of the running system, i\&.e\&. the
+\fIIMAGE_ID=\fR
+field of
+os\-release
+(e\&.g\&.
+"vendorx\-cashier\-system")\&.
+.sp
+If set to
+\fBauto\fR
+(the default), the
+/etc/kernel/entry\-token
+file will be read if it exists, and the stored value used\&. Otherwise if the local machine ID is initialized it is used\&. Otherwise
+\fIIMAGE_ID=\fR
+from
+os\-release
+will be used, if set\&. Otherwise,
+\fIID=\fR
+from
+os\-release
+will be used, if set\&.
+.sp
+Unless set to
+"machine\-id", or when
+\fB\-\-make\-entry\-directory=yes\fR
+is used the selected token string is written to a file
+/etc/kernel/entry\-token, to ensure it will be used for future entries\&. This file is also read by
+\fBkernel-install\fR(8), in order to identify under which name to generate boot loader entries for newly installed kernels, or to determine the entry names for removing old ones\&.
+.sp
+Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option\&. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted)
+\fI$BOOT\fR
+partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-all\-architectures\fR
+.RS 4
+Install binaries for all supported EFI architectures (this implies
+\fB\-\-no\-variables\fR)\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-efi\-boot\-option\-description=\fR
+.RS 4
+Description of the entry added to the firmware\*(Aqs boot option list\&. Defaults to
+"Linux Boot Manager"\&.
+.sp
+Using the default entry name
+"Linux Boot Manager"
+is generally preferable as only one bootloader installed to a single ESP partition should be used to boot any number of OS installations found on the various disks installed in the system\&. Specifically distributions should not use this flag to install a branded entry in the boot option list\&. However in situations with multiple disks, each with their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in the firmware\*(Aqs boot option menu\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-dry\-run\fR
+.RS 4
+Dry run for
+\fBunlink\fR
+and
+\fBcleanup\fR\&.
+.sp
+In dry run mode, the unlink and cleanup operations only print the files that would get deleted without actually deleting them\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "SIGNED \&.EFI FILES"
+.PP
+\fBbootctl\fR
+\fBinstall\fR
+and
+\fBupdate\fR
+will look for a
+\fBsystemd\-boot\fR
+file ending with the
+"\&.efi\&.signed"
+suffix first, and copy that instead of the normal
+"\&.efi"
+file\&. This allows distributions or end\-users to provide signed images for UEFI SecureBoot\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+\fBbootctl \-\-print\-root\-device\fR
+returns exit status 80 in case the root file system is not backed by single block device, and other non\-zero exit statuses on other errors\&.
+.SH "ENVIRONMENT"
+.PP
+If
+\fI$SYSTEMD_RELAX_ESP_CHECKS=1\fR
+is set the validation checks for the ESP are relaxed, and the path specified with
+\fB\-\-esp\-path=\fR
+may refer to any kind of file system on any kind of partition\&.
+.PP
+Similarly,
+\fI$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1\fR
+turns off some validation checks for the Extended Boot Loader partition\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Output from status and list\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBbootctl status\fR
+System:
+     Firmware: UEFI 2\&.40 (\fIfirmware\-version\fR)  � firmware vendor and version
+  Secure Boot: disabled (setup)              � Secure Boot status
+ TPM2 Support: yes
+ Boot into FW: supported                     � does the firmware support booting into itself
+
+Current Boot Loader:                         � details about sd\-boot or another boot loader
+      Product: systemd\-boot \fIversion\fR            implementing the \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2
+     Features: ✓ Boot counting
+               ✓ Menu timeout control
+               ✓ One\-shot menu timeout control
+               ✓ Default entry control
+               ✓ One\-shot entry control
+               ✓ Support for XBOOTLDR partition
+               ✓ Support for passing random seed to OS
+               ✓ Load drop\-in drivers
+               ✓ Boot loader sets ESP information
+               ✓ Menu can be disabled
+          ESP: /dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000
+         File: └─/EFI/systemd/systemd\-bootx64\&.efi
+
+Random Seed:                                 � random seed used for entropy in early boot
+ Passed to OS: yes
+ System Token: set
+       Exists: yes
+
+Available Boot Loaders on ESP:
+          ESP: /boot/efi (/dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000)
+         File: └─/EFI/systemd/systemd\-bootx64\&.efi (systemd\-boot 251
+         File: └─/EFI/BOOT/BOOTX64\&.EFI (systemd\-boot 251
+
+Boot Loaders Listed in EFI Variables:
+        Title: Linux Boot Manager
+           ID: 0x0001
+       Status: active, boot\-order
+    Partition: /dev/disk/by\-partuuid/\&...
+         File: └─/EFI/systemd/systemd\-bootx64\&.efi
+
+        Title: Fedora
+           ID: 0x0000
+       Status: active, boot\-order
+    Partition: /dev/disk/by\-partuuid/\&...
+         File: └─/EFI/fedora/shimx64\&.efi
+
+        Title: Linux\-Firmware\-Updater
+           ID: 0x0002
+       Status: active, boot\-order
+    Partition: /dev/disk/by\-partuuid/\&...
+         File: └─/EFI/fedora/fwupdx64\&.efi
+
+Boot Loader Entries:
+        $BOOT: /boot/efi (/dev/disk/by\-partuuid/01234567\-89ab\-cdef\-dead\-beef00000000)
+
+Default Boot Loader Entry:
+         type: Boot Loader Specification Type #1 (\&.conf)
+        title: Fedora Linux 36 (Workstation Edition)
+           id: \&...
+       source: /boot/efi/loader/entries/\fIentry\-token\fR\-\fIkernel\-version\fR\&.conf
+      version: \fIkernel\-version\fR
+   machine\-id: \&...
+        linux: /\fIentry\-token\fR/\fIkernel\-version\fR/linux
+       initrd: /\fIentry\-token\fR/\fIkernel\-version\fR/initrd
+      options: root=\&...
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBbootctl list\fR
+Boot Loader Entries:
+         type: Boot Loader Specification Type #1 (\&.conf)
+        title: Fedora Linux 36 (Workstation Edition) (default) (selected)
+           id: \&...
+       source: /boot/efi/loader/entries/\fIentry\-token\fR\-\fIkernel\-version\fR\&.conf
+      version: \fIkernel\-version\fR
+   machine\-id: \&...
+        linux: /\fIentry\-token\fR/\fIkernel\-version\fR/linux
+       initrd: /\fIentry\-token\fR/\fIkernel\-version\fR/initrd
+      options: root=\&...
+
+         type: Boot Loader Specification Type #2 (\&.efi)
+        title: Fedora Linux 35 (Workstation Edition)
+           id: \&...
+       source: /boot/efi/EFI/Linux/fedora\-\fIkernel\-version\fR\&.efi
+      version: \fIkernel\-version\fR
+   machine\-id: \&...
+        linux: /EFI/Linux/fedora\-\fIkernel\-version\fR\&.efi
+      options: root=\&...
+
+         type: Automatic
+        title: Reboot Into Firmware Interface
+           id: auto\-reboot\-to\-firmware\-setup
+       source: /sys/firmware/efi/efivars/LoaderEntries\-4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4f
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+In the listing,
+"(default)"
+specifies the entry that will be used by default, and
+"(selected)"
+specifies the entry that was selected the last time (i\&.e\&. is currently running)\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd-boot\fR(7),
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2,
+\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2,
+\fBsystemd-boot-random-seed.service\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Boot Loader Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/boot_loader_specification
+.RE
+.IP " 2." 4
+Boot Loader Interface
+.RS 4
+\%https://systemd.io/BOOT_LOADER_INTERFACE
+.RE
+.IP " 3." 4
+Random Seeds
+.RS 4
+\%https://systemd.io/RANDOM_SEEDS
+.RE
+.IP " 4." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
diff --git a/upstream/mageia-cauldron/man1/brushtopbm.1 b/upstream/mageia-cauldron/man1/brushtopbm.1
new file mode 100644
index 00000000..64096a81
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/brushtopbm.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Brushtopbm User Manual" 0 "28 August 1988" "netpbm documentation"
+
+.SH NAME
+brushtopbm - convert a doodle brush file into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBbrushtopbm\fP
+[\fIbrushfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBbrushtopbm\fP reads a Xerox doodle brush file as input.  and
+produces a portable bitmap as output.
+.PP
+Note that there is currently no pbmtobrush tool.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBbrushtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/brushtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/builtins.1 b/upstream/mageia-cauldron/man1/builtins.1
new file mode 100644
index 00000000..00dc28b0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/builtins.1
@@ -0,0 +1,3909 @@
+.lf 1 ./builtins.1
+.\" This is a hack to force bash builtins into the whatis database
+.\" and to get the list of builtins to come up with the man command.
+.\"
+.\" File Name macro.  This used to be `.PN', for Path Name,
+.\" but Sun doesn't seem to like that very much.
+.\"
+.de FN
+\fI\|\\$1\|\fP
+..
+.TH BASH_BUILTINS 1 "2021 November 22" "GNU Bash 5.2"
+.SH NAME
+:, ., [, alias, bg, bind, break, builtin, caller,
+cd, command, compgen, complete, compopt,
+continue, declare, dirs, disown, echo, enable, eval, exec, exit,
+export, false, fc, fg, getopts, hash, help, history, jobs, kill,
+let, local, logout, mapfile, popd, printf, pushd, pwd, read,
+readarray, readonly, return, set,
+shift, shopt, source, suspend, test, times, trap, true, type, typeset,
+ulimit, umask, unalias, unset, wait \- bash built-in commands, see \fBbash\fR(1)
+.SH BASH BUILTIN COMMANDS
+.nr zZ 1
+.lf 1 ./bash.1
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\"	Chet Ramey
+.\"	Case Western Reserve University
+.\"	chet.ramey@case.edu
+.\"
+.\"	Last Change: Mon Sep 19 11:13:21 EDT 2022
+.\"
+.\" bash_builtins, strip all but Built-Ins section
+.PP
+Unless otherwise noted, each builtin command documented in this
+section as accepting options preceded by
+.B \-
+accepts
+.B \-\-
+to signify the end of the options.
+The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
+do not accept options and do not treat \fB\-\-\fP specially.
+The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
+\fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
+and \fBshift\fP builtins accept and process arguments beginning with
+\fB\-\fP without requiring \fB\-\-\fP.
+Other builtins that accept arguments but are not specified as accepting
+options interpret arguments beginning with \fB\-\fP as invalid options and
+require \fB\-\-\fP to prevent this interpretation.
+.sp .5
+.PD 0
+.TP
+\fB:\fP [\fIarguments\fP]
+.PD
+No effect; the command does nothing beyond expanding
+.I arguments
+and performing any specified
+redirections.
+The return status is zero.
+.TP
+\fB .\| \fP \fIfilename\fP [\fIarguments\fP]
+.PD 0
+.TP
+\fBsource\fP \fIfilename\fP [\fIarguments\fP]
+.PD
+Read and execute commands from
+.I filename
+in the current
+shell environment and return the exit status of the last command
+executed from
+.IR filename .
+If
+.I filename
+does not contain a slash, filenames in
+.SM
+.B PATH
+are used to find the directory containing
+.IR filename ,
+but \fIfilename\fP does not need to be executable.
+The file searched for in
+.SM
+.B PATH
+need not be executable.
+When \fBbash\fP is not in \fIposix mode\fP, it searches
+the current directory if no file is found in
+.SM
+.BR PATH .
+If the
+.B sourcepath
+option to the
+.B shopt
+builtin command is turned off, the
+.SM
+.B PATH
+is not searched.
+If any \fIarguments\fP are supplied, they become the positional
+parameters when \fIfilename\fP is executed.  Otherwise the positional
+parameters are unchanged.
+If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
+\fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
+restored around the call to \fB.\fP, and \fB.\fP unsets the
+\fBDEBUG\fP trap while it executes.
+If \fB\-T\fP is not set, and the sourced file changes
+the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes.
+The return status is the status of the last command exited within
+the script (0 if no commands are executed), and false if
+.I filename
+is not found or cannot be read.
+.TP
+\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+\fBAlias\fP with no arguments or with the
+.B \-p
+option prints the list of aliases in the form
+\fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
+When arguments are supplied, an alias is defined for
+each \fIname\fP whose \fIvalue\fP is given.
+A trailing space in \fIvalue\fP causes the next word to be
+checked for alias substitution when the alias is expanded.
+For each \fIname\fP in the argument list for which no \fIvalue\fP
+is supplied, the name and value of the alias is printed.
+\fBAlias\fP returns true unless a \fIname\fP is given for which
+no alias has been defined.
+.TP
+\fBbg\fP [\fIjobspec\fP ...]
+Resume each suspended job \fIjobspec\fP in the background, as if it
+had been started with
+.BR & .
+If
+.I jobspec
+is not present, the shell's notion of the \fIcurrent job\fP is used.
+.B bg
+.I jobspec
+returns 0 unless run when job control is disabled or, when run with
+job control enabled, any specified \fIjobspec\fP was not found
+or was started without job control.
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
+.PD 0
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
+.TP
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
+.TP
+\fBbind\fP \fIreadline-command-line\fP
+.PD
+Display current
+.B readline
+key and function bindings, bind a key sequence to a
+.B readline
+function or macro, or set a
+.B readline
+variable.
+Each non-option argument is a command as it would appear in a
+.B readline
+initialization file such as
+.IR .inputrc ,
+but each binding or command must be passed as a separate argument;
+e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-m \fIkeymap\fP
+Use
+.I keymap
+as the keymap to be affected by the subsequent bindings.
+Acceptable
+.I keymap
+names are
+\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
+vi\-move, vi\-command\fP, and
+.IR vi\-insert .
+\fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also
+a synonym); \fIemacs\fP is
+equivalent to \fIemacs\-standard\fP.
+.TP
+.B \-l
+List the names of all \fBreadline\fP functions.
+.TP
+.B \-p
+Display \fBreadline\fP function names and bindings in such a way
+that they can be re-read.
+.TP
+.B \-P
+List current \fBreadline\fP function names and bindings.
+.TP
+.B \-s
+Display \fBreadline\fP key sequences bound to macros and the strings
+they output in such a way that they can be re-read.
+.TP
+.B \-S
+Display \fBreadline\fP key sequences bound to macros and the strings
+they output.
+.TP
+.B \-v
+Display \fBreadline\fP variable names and values in such a way that they
+can be re-read.
+.TP
+.B \-V
+List current \fBreadline\fP variable names and values.
+.TP
+.B \-f \fIfilename\fP
+Read key bindings from \fIfilename\fP.
+.TP
+.B \-q \fIfunction\fP
+Query about which keys invoke the named \fIfunction\fP.
+.TP
+.B \-u \fIfunction\fP
+Unbind all keys bound to the named \fIfunction\fP.
+.TP
+.B \-r \fIkeyseq\fP
+Remove any current binding for \fIkeyseq\fP.
+.TP
+.B \-x \fIkeyseq\fP:\fIshell\-command\fP
+Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
+entered.
+When \fIshell\-command\fP is executed, the shell sets the
+.SM
+.B READLINE_LINE
+variable to the contents of the \fBreadline\fP line buffer and the
+.SM
+.B READLINE_POINT
+and
+.SM
+.B READLINE_MARK
+variables to the current location of the insertion point and the saved
+insertion point (the mark), respectively.
+The shell assigns any numeric argument the user supplied to the     
+.SM
+.B READLINE_ARGUMENT
+variable.
+If there was no argument, that variable is not set.
+If the executed command changes the value of any of
+.SM
+.BR READLINE_LINE ,
+.SM
+.BR READLINE_POINT ,
+or
+.SM
+.BR READLINE_MARK ,
+those new values will be reflected in the editing state.
+.TP
+.B \-X
+List all key sequences bound to shell commands and the associated commands
+in a format that can be reused as input.
+.PD
+.PP
+The return value is 0 unless an unrecognized option is given or an
+error occurred.
+.RE
+.TP
+\fBbreak\fP [\fIn\fP]
+Exit from within a
+.BR for ,
+.BR while ,
+.BR until ,
+or
+.B select
+loop.  If \fIn\fP is specified, break \fIn\fP levels.
+.I n
+must be \(>= 1.  If
+.I n
+is greater than the number of enclosing loops, all enclosing loops
+are exited.
+The return value is 0 unless \fIn\fP is not greater than or equal to 1.
+.TP
+\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
+Execute the specified shell builtin, passing it
+.IR arguments ,
+and return its exit status.
+This is useful when defining a
+function whose name is the same as a shell builtin,
+retaining the functionality of the builtin within the function.
+The \fBcd\fP builtin is commonly redefined this way.
+The return status is false if
+.I shell\-builtin
+is not a shell builtin command.
+.TP
+\fBcaller\fP [\fIexpr\fP]
+Returns the context of any active subroutine call (a shell function or
+a script executed with the \fB.\fP or \fBsource\fP builtins).
+Without \fIexpr\fP, \fBcaller\fP displays the line number and source
+filename of the current subroutine call.
+If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
+displays the line number, subroutine name, and source file corresponding
+to that position in the current execution call stack.  This extra
+information may be used, for example, to print a stack trace.  The
+current frame is frame 0.
+The return value is 0 unless the shell is not executing a subroutine
+call or \fIexpr\fP does not correspond to a valid position in the
+call stack.
+.TP
+\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP]
+Change the current directory to \fIdir\fP.
+if \fIdir\fP is not supplied, the value of the
+.SM
+.B HOME
+shell variable is the default.
+The variable
+.SM
+.B CDPATH
+defines the search path for the directory containing
+.IR dir :
+each directory name in
+.SM
+.B CDPATH
+is searched for \fIdir\fP.
+Alternative directory names in
+.SM
+.B CDPATH
+are separated by a colon (:).  A null directory name in
+.SM
+.B CDPATH
+is the same as the current directory, i.e., ``\fB.\fP''.  If
+.I dir
+begins with a slash (/),
+then
+.SM
+.B CDPATH
+is not used.  The
+.B \-P
+option causes \fBcd\fP to use the physical directory structure
+by resolving symbolic links while traversing \fIdir\fP and
+before processing instances of \fI..\fP in \fIdir\fP (see also the
+.B \-P
+option to the
+.B set
+builtin command); the
+.B \-L
+option forces symbolic links to be followed by resolving the link
+after processing instances of \fI..\fP in \fIdir\fP.
+If \fI..\fP appears in \fIdir\fP, it is processed by removing the
+immediately previous pathname component from \fIdir\fP, back to a slash
+or the beginning of \fIdir\fP.
+If the
+.B \-e
+option is supplied with
+.BR \-P ,
+and the current working directory cannot be successfully determined
+after a successful directory change, \fBcd\fP will return an unsuccessful
+status.
+On systems that support it, the \fB\-@\fP option presents the extended
+attributes associated with a file as a directory.
+An argument of
+.B \-
+is converted to
+.SM
+.B $OLDPWD
+before the directory change is attempted.
+If a non-empty directory name from
+.SM
+.B CDPATH
+is used, or if
+\fB\-\fP is the first argument, and the directory change is
+successful, the absolute pathname of the new working directory is
+written to the standard output.
+If the directory change is successful, \fBcd\fP sets the value of the
+\fBPWD\fP environment variable to the new directory name, and sets the
+\fBOLDPWD\fP environment variable to the value of the current working
+directory before the change.
+The return value is true if the directory was successfully changed;
+false otherwise.
+.TP
+\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
+Run
+.I command
+with
+.I args
+suppressing the normal shell function lookup.
+Only builtin commands or commands found in the
+.SM
+.B PATH
+are executed.  If the
+.B \-p
+option is given, the search for
+.I command
+is performed using a default value for
+.SM
+.B PATH
+that is guaranteed to find all of the standard utilities.
+If either the
+.B \-V
+or
+.B \-v
+option is supplied, a description of
+.I command
+is printed.  The
+.B \-v
+option causes a single word indicating the command or filename
+used to invoke
+.I command
+to be displayed; the
+.B \-V
+option produces a more verbose description.
+If the
+.B \-V
+or
+.B \-v
+option is supplied, the exit status is 0 if
+.I command
+was found, and 1 if not.  If neither option is supplied and
+an error occurred or
+.I command
+cannot be found, the exit status is 127.  Otherwise, the exit status of the
+.B command
+builtin is the exit status of
+.IR command .
+.TP
+\fBcompgen\fP [\fIoption\fP] [\fIword\fP]
+Generate possible completion matches for \fIword\fP according to
+the \fIoption\fPs, which may be any option accepted by the
+.B complete
+builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write
+the matches to the standard output.
+When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
+set by the programmable completion facilities, while available, will not
+have useful values.
+.sp 1
+The matches will be generated in the same way as if the programmable
+completion code had generated them directly from a completion specification
+with the same flags.
+If \fIword\fP is specified, only those completions matching \fIword\fP
+will be displayed.
+.sp 1
+The return value is true unless an invalid option is supplied, or no
+matches were generated.
+.TP
+\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP]
+.br
+[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
+.PD 0
+.TP
+\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...]
+.PD
+Specify how arguments to each \fIname\fP should be completed.
+If the \fB\-p\fP option is supplied, or if no options are supplied,
+existing completion specifications are printed in a way that allows
+them to be reused as input.
+The \fB\-r\fP option removes a completion specification for
+each \fIname\fP, or, if no \fIname\fPs are supplied, all
+completion specifications.
+The \fB\-D\fP option indicates that other supplied options and actions should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The \fB\-E\fP option indicates that other supplied options and actions should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
+The \fB\-I\fP option indicates that other supplied options and actions should
+apply to completion on the initial non-assignment word on the line, or after
+a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
+name completion.
+If multiple options are supplied, the \fB\-D\fP option takes precedence
+over \fB\-E\fP, and both take precedence over \fB\-I\fP.
+If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
+\fIname\fP arguments are ignored; these completions only apply to the case
+specified by the option.
+.sp 1
+The process of applying these completion specifications when word completion
+is attempted is described
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above under \fBProgrammable Completion\fP.
+.sp 1
+Other options, if specified, have the following meanings.
+The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
+(and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
+should be quoted to protect them from expansion before the
+.B complete
+builtin is invoked.
+.RS
+.PD 0
+.TP 8
+\fB\-o\fP \fIcomp-option\fP
+The \fIcomp-option\fP controls several aspects of the compspec's behavior
+beyond the simple generation of completions.
+\fIcomp-option\fP may be one of:
+.RS
+.TP 8
+.B bashdefault
+Perform the rest of the default \fBbash\fP completions if the compspec
+generates no matches.
+.TP 8
+.B default
+Use readline's default filename completion if the compspec generates
+no matches.
+.TP 8
+.B dirnames
+Perform directory name completion if the compspec generates no matches.
+.TP 8
+.B filenames
+Tell readline that the compspec generates filenames, so it can perform any
+filename\-specific processing (like adding a slash to directory names,
+quoting special characters, or suppressing trailing spaces).
+Intended to be used with shell functions.
+.TP 8
+.B noquote
+Tell readline not to quote the completed words if they are filenames
+(quoting filenames is the default).
+.TP 8
+.B nosort
+Tell readline not to sort the list of possible completions alphabetically.
+.TP 8
+.B nospace
+Tell readline not to append a space (the default) to words completed at
+the end of the line.
+.TP 8
+.B plusdirs
+After any matches defined by the compspec are generated,
+directory name completion is attempted and any
+matches are added to the results of the other actions.
+.RE
+.TP 8
+\fB\-A\fP \fIaction\fP
+The \fIaction\fP may be one of the following to generate a list of possible
+completions:
+.RS
+.TP 8
+.B alias
+Alias names.  May also be specified as \fB\-a\fP.
+.TP 8
+.B arrayvar
+Array variable names.
+.TP 8
+.B binding
+\fBReadline\fP key binding names.
+.TP 8
+.B builtin
+Names of shell builtin commands.  May also be specified as \fB\-b\fP.
+.TP 8
+.B command
+Command names.  May also be specified as \fB\-c\fP.
+.TP 8
+.B directory
+Directory names.  May also be specified as \fB\-d\fP.
+.TP 8
+.B disabled
+Names of disabled shell builtins.
+.TP 8
+.B enabled
+Names of enabled shell builtins.
+.TP 8
+.B export
+Names of exported shell variables.  May also be specified as \fB\-e\fP.
+.TP 8
+.B file
+File names.  May also be specified as \fB\-f\fP.
+.TP 8
+.B function
+Names of shell functions.
+.TP 8
+.B group
+Group names.  May also be specified as \fB\-g\fP.
+.TP 8
+.B helptopic
+Help topics as accepted by the \fBhelp\fP builtin.
+.TP 8
+.B hostname
+Hostnames, as taken from the file specified by the
+.SM
+.B HOSTFILE
+shell variable.
+.TP 8
+.B job
+Job names, if job control is active.  May also be specified as \fB\-j\fP.
+.TP 8
+.B keyword
+Shell reserved words.  May also be specified as \fB\-k\fP.
+.TP 8
+.B running
+Names of running jobs, if job control is active.
+.TP 8
+.B service
+Service names.  May also be specified as \fB\-s\fP.
+.TP 8
+.B setopt
+Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
+.TP 8
+.B shopt
+Shell option names as accepted by the \fBshopt\fP builtin.
+.TP 8
+.B signal
+Signal names.
+.TP 8
+.B stopped
+Names of stopped jobs, if job control is active.
+.TP 8
+.B user
+User names.  May also be specified as \fB\-u\fP.
+.TP 8
+.B variable
+Names of all shell variables.  May also be specified as \fB\-v\fP.
+.RE
+.TP 8
+\fB\-C\fP \fIcommand\fP
+\fIcommand\fP is executed in a subshell environment, and its output is
+used as the possible completions.
+Arguments are passed as with the \fB\-F\fP option.
+.TP 8
+\fB\-F\fP \fIfunction\fP
+The shell function \fIfunction\fP is executed in the current shell
+environment.
+When the function is executed,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
+When it finishes, the possible completions are retrieved from the value
+of the
+.SM
+.B COMPREPLY
+array variable.
+.TP 8
+\fB\-G\fP \fIglobpat\fP
+The pathname expansion pattern \fIglobpat\fP is expanded to generate
+the possible completions.
+.TP 8
+\fB\-P\fP \fIprefix\fP
+\fIprefix\fP is added at the beginning of each possible completion
+after all other options have been applied.
+.TP 8
+\fB\-S\fP \fIsuffix\fP
+\fIsuffix\fP is appended to each possible completion
+after all other options have been applied.
+.TP 8
+\fB\-W\fP \fIwordlist\fP
+The \fIwordlist\fP is split using the characters in the
+.SM
+.B IFS
+special variable as delimiters, and each resultant word is expanded.
+Shell quoting is honored within \fIwordlist\fP,
+in order to provide a
+mechanism for the words to contain shell metacharacters or characters
+in the value of
+.SM
+.BR IFS .
+The possible completions are the members of the resultant list which
+match the word being completed.
+.TP 8
+\fB\-X\fP \fIfilterpat\fP
+\fIfilterpat\fP is a pattern as used for pathname expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+\fIfilterpat\fP is removed from the list.
+A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
+case, any completion not matching \fIfilterpat\fP is removed.
+.PD
+.PP
+The return value is true unless an invalid option is supplied, an option
+other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP
+argument, an attempt is made to remove a completion specification for
+a \fIname\fP for which no specification exists, or
+an error occurs adding a completion specification.
+.RE
+.TP
+\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
+Modify completion options for each \fIname\fP according to the
+\fIoption\fPs, or for the
+currently-executing completion if no \fIname\fPs are supplied.
+If no \fIoption\fPs are given, display the completion options for each
+\fIname\fP or the current completion.
+The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
+builtin described above.
+The \fB\-D\fP option indicates that other supplied options should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The \fB\-E\fP option indicates that other supplied options should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
+The \fB\-I\fP option indicates that other supplied options should
+apply to completion on the initial non-assignment word on the line,
+or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually
+command name completion.
+.sp 1
+The return value is true unless an invalid option is supplied, an attempt
+is made to modify the options for a \fIname\fP for which no completion
+specification exists, or an output error occurs.
+.TP
+\fBcontinue\fP [\fIn\fP]
+Resume the next iteration of the enclosing
+.BR for ,
+.BR while ,
+.BR until ,
+or
+.B select
+loop.
+If
+.I n
+is specified, resume at the \fIn\fPth enclosing loop.
+.I n
+must be \(>= 1.  If
+.I n
+is greater than the number of enclosing loops, the last enclosing loop
+(the ``top-level'' loop) is resumed.
+The return value is 0 unless \fIn\fP is not greater than or equal to 1.
+.TP
+\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+.PD 0
+.TP
+\fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+.PD
+Declare variables and/or give them attributes.
+If no \fIname\fPs are given then display the values of variables.
+The
+.B \-p
+option will display the attributes and values of each
+.IR name .
+When
+.B \-p
+is used with \fIname\fP arguments, additional options,
+other than \fB\-f\fP and \fB\-F\fP, are ignored.
+When
+.B \-p
+is supplied without \fIname\fP arguments, it will display the attributes
+and values of all variables having the attributes specified by the
+additional options.
+If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display
+the attributes and values of all shell variables.  The \fB\-f\fP option
+will restrict the display to shell functions.
+The
+.B \-F
+option inhibits the display of function definitions; only the
+function name and attributes are printed.
+If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
+the source file name and line number where each \fIname\fP
+is defined are displayed as well.  The
+.B \-F
+option implies
+.BR \-f .
+The
+.B \-g
+option forces variables to be created or modified at the global scope,
+even when \fBdeclare\fP is executed in a shell function.
+It is ignored in all other cases.
+The
+.B \-I
+option causes local variables to inherit the attributes
+(except the \fInameref\fP attribute) 
+and value of any existing variable with the same
+\fIname\fP at a surrounding scope.
+If there is no existing variable, the local variable is initially unset.
+The following options can
+be used to restrict output to variables with the specified attribute or
+to give variables attributes:
+.RS
+.PD 0
+.TP
+.B \-a
+Each \fIname\fP is an indexed array variable (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B \-A
+Each \fIname\fP is an associative array variable (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B \-f
+Use function names only.
+.TP
+.B \-i
+The variable is treated as an integer; arithmetic evaluation (see
+.SM
+.B "ARITHMETIC EVALUATION"
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+is performed when the variable is assigned a value.
+.TP
+.B \-l
+When the variable is assigned a value, all upper-case characters are
+converted to lower-case.
+The upper-case attribute is disabled.
+.TP
+.B \-n
+Give each \fIname\fP the \fInameref\fP attribute, making
+it a name reference to another variable.
+That other variable is defined by the value of \fIname\fP.
+All references, assignments, and attribute modifications
+to \fIname\fP, except those using or changing the
+\fB\-n\fP attribute itself, are performed on the variable referenced by
+\fIname\fP's value.
+The nameref attribute cannot be applied to array variables.
+.TP
+.B \-r
+Make \fIname\fPs readonly.  These names cannot then be assigned values
+by subsequent assignment statements or unset.
+.TP
+.B \-t
+Give each \fIname\fP the \fItrace\fP attribute.
+Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
+the calling shell.
+The trace attribute has no special meaning for variables.
+.TP
+.B \-u
+When the variable is assigned a value, all lower-case characters are
+converted to upper-case.
+The lower-case attribute is disabled.
+.TP
+.B \-x
+Mark \fIname\fPs for export to subsequent commands via the environment.
+.PD
+.PP
+Using `+' instead of `\-'
+turns off the attribute instead,
+with the exceptions that \fB+a\fP and \fB+A\fP
+may not be used to destroy array variables and \fB+r\fP will not
+remove the readonly attribute.
+When used in a function,
+.B declare
+and
+.B typeset
+make each
+\fIname\fP local, as with the
+.B local
+command,
+unless the \fB\-g\fP option is supplied.
+If a variable name is followed by =\fIvalue\fP, the value of
+the variable is set to \fIvalue\fP.
+When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
+create array variables, additional attributes do not take effect until
+subsequent assignments.
+The return value is 0 unless an invalid option is encountered,
+an attempt is made to define a function using
+.if n ``\-f foo=bar'',
+.if t \f(CW\-f foo=bar\fP,
+an attempt is made to assign a value to a readonly variable,
+an attempt is made to assign a value to an array variable without
+using the compound assignment syntax (see
+.B Arrays
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+one of the \fInames\fP is not a valid shell variable name,
+an attempt is made to turn off readonly status for a readonly variable,
+an attempt is made to turn off array status for an array variable,
+or an attempt is made to display a non-existent function with \fB\-f\fP.
+.RE
+.TP
+.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
+Without options, displays the list of currently remembered directories.
+The default display is on a single line with directory names separated
+by spaces.
+Directories are added to the list with the
+.B pushd
+command; the
+.B popd
+command removes entries from the list.
+The current directory is always the first directory in the stack.
+.RS
+.PD 0
+.TP
+.B \-c
+Clears the directory stack by deleting all of the entries.
+.TP
+.B \-l
+Produces a listing using full pathnames;
+the default listing format uses a tilde to denote the home directory.
+.TP
+.B \-p
+Print the directory stack with one entry per line.
+.TP
+.B \-v
+Print the directory stack with one entry per line,
+prefixing each entry with its index in the stack.
+.TP
+\fB+\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the left of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
+.TP
+\fB\-\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the right of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
+.PD
+.PP
+The return value is 0 unless an
+invalid option is supplied or \fIn\fP indexes beyond the end
+of the directory stack.
+.RE
+.TP
+\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ]
+Without options, remove each
+.I jobspec
+from the table of active jobs.
+If
+.I jobspec
+is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option
+is supplied, the \fIcurrent job\fP is used.
+If the \fB\-h\fP option is given, each
+.I jobspec
+is not removed from the table, but is marked so that
+.SM
+.B SIGHUP
+is not sent to the job if the shell receives a
+.SM
+.BR SIGHUP .
+If no
+.I jobspec
+is supplied, the
+.B \-a
+option means to remove or mark all jobs; the
+.B \-r
+option without a
+.I jobspec
+argument restricts operation to running jobs.
+The return value is 0 unless a
+.I jobspec
+does not specify a valid job.
+.TP
+\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
+Output the \fIarg\fPs, separated by spaces, followed by a newline.
+The return status is 0 unless a write error occurs.
+If \fB\-n\fP is specified, the trailing newline is
+suppressed.  If the \fB\-e\fP option is given, interpretation of
+the following backslash-escaped characters is enabled.  The
+.B \-E
+option disables the interpretation of these escape characters,
+even on systems where they are interpreted by default.
+The \fBxpg_echo\fP shell option may be used to
+dynamically determine whether or not \fBecho\fP expands these
+escape characters by default.
+.B echo
+does not interpret \fB\-\-\fP to mean the end of options.
+.B echo
+interprets the following escape sequences:
+.RS
+.PD 0
+.TP
+.B \ea
+alert (bell)
+.TP
+.B \eb
+backspace
+.TP
+.B \ec
+suppress further output
+.TP
+.B \ee
+.TP
+.B \eE
+an escape character
+.TP
+.B \ef
+form feed
+.TP
+.B \en
+new line
+.TP
+.B \er
+carriage return
+.TP
+.B \et
+horizontal tab
+.TP
+.B \ev
+vertical tab
+.TP
+.B \e\e
+backslash
+.TP
+.B \e0\fInnn\fP
+the eight-bit character whose value is the octal value \fInnn\fP
+(zero to three octal digits)
+.TP
+.B \ex\fIHH\fP
+the eight-bit character whose value is the hexadecimal value \fIHH\fP
+(one or two hex digits)
+.TP
+.B \eu\fIHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHH\fP (one to four hex digits)
+.TP
+.B \eU\fIHHHHHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHHHHHH\fP (one to eight hex digits)
+.PD
+.RE
+.TP
+\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
+Enable and disable builtin shell commands.
+Disabling a builtin allows a disk command which has the same name
+as a shell builtin to be executed without specifying a full pathname,
+even though the shell normally searches for builtins before disk commands.
+If \fB\-n\fP is used, each \fIname\fP
+is disabled; otherwise,
+\fInames\fP are enabled.  For example, to use the
+.B test
+binary found via the
+.SM
+.B PATH
+instead of the shell builtin version, run
+.if t \f(CWenable -n test\fP.
+.if n ``enable -n test''.
+The
+.B \-f
+option means to load the new builtin command
+.I name
+from shared object
+.IR filename ,
+on systems that support dynamic loading.
+Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
+colon-separated list of directories in which to search for \fIfilename\fP.
+The default is system-dependent.
+The
+.B \-d
+option will delete a builtin previously loaded with
+.BR \-f .
+If no \fIname\fP arguments are given, or if the
+.B \-p
+option is supplied, a list of shell builtins is printed.
+With no other option arguments, the list consists of all enabled
+shell builtins.
+If \fB\-n\fP is supplied, only disabled builtins are printed.
+If \fB\-a\fP is supplied, the list printed includes all builtins, with an
+indication of whether or not each is enabled.
+If \fB\-s\fP is supplied, the output is restricted to the POSIX
+\fIspecial\fP builtins.
+If no options are supplied and a \fIname\fP is not a shell builtin,
+\fBenable\fP will attempt to load \fIname\fP from a shared object named
+\fIname\fP, as if the command were
+.if t \f(CWenable \-f\fP \fIname name\fP .
+.if n ``enable -f \fIname name\fP .
+The return value is 0 unless a
+.I name
+is not a shell builtin or there is an error loading a new builtin
+from a shared object.
+.TP
+\fBeval\fP [\fIarg\fP ...]
+The \fIarg\fPs are read and concatenated together into a single
+command.  This command is then read and executed by the shell, and
+its exit status is returned as the value of
+.BR eval .
+If there are no
+.IR args ,
+or only null arguments,
+.B eval
+returns 0.
+.TP
+\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
+If
+.I command
+is specified, it replaces the shell.
+No new process is created.  The
+.I arguments
+become the arguments to \fIcommand\fP.
+If the
+.B \-l
+option is supplied,
+the shell places a dash at the beginning of the zeroth argument passed to
+.IR command .
+This is what
+.IR login (1)
+does.  The
+.B \-c
+option causes
+.I command
+to be executed with an empty environment.  If
+.B \-a
+is supplied, the shell passes
+.I name
+as the zeroth argument to the executed command.
+If
+.I command
+cannot be executed for some reason, a non-interactive shell exits,
+unless the
+.B execfail
+shell option
+is enabled.  In that case, it returns failure.
+An interactive shell returns failure if the file cannot be executed.
+A subshell exits unconditionally if \fBexec\fP fails.
+If
+.I command
+is not specified, any redirections take effect in the current shell,
+and the return status is 0.  If there is a redirection error, the
+return status is 1.
+.TP
+\fBexit\fP [\fIn\fP]
+Cause the shell to exit
+with a status of \fIn\fP.  If
+.I n
+is omitted, the exit status
+is that of the last command executed.
+A trap on
+.SM
+.B EXIT
+is executed before the shell terminates.
+.TP
+\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
+.PD 0
+.TP
+.B export \-p
+.PD
+The supplied
+.I names
+are marked for automatic export to the environment of
+subsequently executed commands.  If the
+.B \-f
+option is given, the
+.I names
+refer to functions.
+If no
+.I names
+are given, or if the
+.B \-p
+option is supplied, a list
+of names of all exported variables is printed.
+The
+.B \-n
+option causes the export property to be removed from each
+\fIname\fP.
+If a variable name is followed by =\fIword\fP, the value of
+the variable is set to \fIword\fP.
+.B export
+returns an exit status of 0 unless an invalid option is
+encountered,
+one of the \fInames\fP is not a valid shell variable name, or
+.B \-f
+is supplied with a
+.I name
+that is not a function.
+.TP
+\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
+.PD 0
+.TP
+\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
+.PD
+The first form selects a range of commands from
+.I first
+to
+.I last
+from the history list and displays or edits and re-executes them.
+.I First
+and
+.I last
+may be specified as a string (to locate the last command beginning
+with that string) or as a number (an index into the history list,
+where a negative number is used as an offset from the current
+command number).
+When listing, a \fIfirst\fP or \fIlast\fP of
+0 is equivalent to \-1 and \-0 is equivalent to the current
+command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1
+and \-0 is invalid.
+If
+.I last
+is not specified, it is set to
+the current command for listing (so that
+.if n ``fc \-l \-10''
+.if t \f(CWfc \-l \-10\fP
+prints the last 10 commands) and to
+.I first
+otherwise.
+If
+.I first
+is not specified, it is set to the previous
+command for editing and \-16 for listing.
+.sp 1
+The
+.B \-n
+option suppresses
+the command numbers when listing.  The
+.B \-r
+option reverses the order of
+the commands.  If the
+.B \-l
+option is given,
+the commands are listed on
+standard output.  Otherwise, the editor given by
+.I ename
+is invoked
+on a file containing those commands.  If
+.I ename
+is not given, the
+value of the
+.SM
+.B FCEDIT
+variable is used, and
+the value of
+.SM
+.B EDITOR
+if
+.SM
+.B FCEDIT
+is not set.  If neither variable is set,
+.FN vi
+is used.  When editing is complete, the edited commands are
+echoed and executed.
+.sp 1
+In the second form, \fIcommand\fP is re-executed after each instance
+of \fIpat\fP is replaced by \fIrep\fP.
+\fICommand\fP is interpreted the same as \fIfirst\fP above.
+A useful alias to use with this is
+.if n ``r="fc -s"'',
+.if t \f(CWr='fc \-s'\fP,
+so that typing
+.if n ``r cc''
+.if t \f(CWr cc\fP
+runs the last command beginning with
+.if n ``cc''
+.if t \f(CWcc\fP
+and typing
+.if n ``r''
+.if t \f(CWr\fP
+re-executes the last command.
+.sp 1
+If the first form is used, the return value is 0 unless an invalid
+option is encountered or
+.I first
+or
+.I last
+specify history lines out of range.
+If the
+.B \-e
+option is supplied, the return value is the value of the last
+command executed or failure if an error occurs with the temporary
+file of commands.  If the second form is used, the return status
+is that of the command re-executed, unless
+.I cmd
+does not specify a valid history line, in which case
+.B fc
+returns failure.
+.TP
+\fBfg\fP [\fIjobspec\fP]
+Resume
+.I jobspec
+in the foreground, and make it the current job.
+If
+.I jobspec
+is not present, the shell's notion of the \fIcurrent job\fP is used.
+The return value is that of the command placed into the foreground,
+or failure if run when job control is disabled or, when run with
+job control enabled, if
+.I jobspec
+does not specify a valid job or
+.I jobspec
+specifies a job that was started without job control.
+.TP
+\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP]
+.B getopts
+is used by shell procedures to parse positional parameters.
+.I optstring
+contains the option characters to be recognized; if a character
+is followed by a colon, the option is expected to have an
+argument, which should be separated from it by white space.
+The colon and question mark characters may not be used as
+option characters.
+Each time it is invoked,
+.B getopts
+places the next option in the shell variable
+.IR name ,
+initializing
+.I name
+if it does not exist,
+and the index of the next argument to be processed into the
+variable
+.SM
+.BR OPTIND .
+.SM
+.B OPTIND
+is initialized to 1 each time the shell or a shell script
+is invoked.  When an option requires an argument,
+.B getopts
+places that argument into the variable
+.SM
+.BR OPTARG .
+The shell does not reset
+.SM
+.B OPTIND
+automatically; it must be manually reset between multiple
+calls to
+.B getopts
+within the same shell invocation if a new set of parameters
+is to be used.
+.sp 1
+When the end of options is encountered, \fBgetopts\fP exits with a
+return value greater than zero.
+.SM
+.B OPTIND
+is set to the index of the first non-option argument,
+and \fIname\fP is set to ?.
+.sp 1
+.B getopts
+normally parses the positional parameters, but if more arguments are
+supplied as
+.I arg
+values,
+.B getopts
+parses those instead.
+.sp 1
+.B getopts
+can report errors in two ways.  If the first character of
+.I optstring
+is a colon,
+.I silent
+error reporting is used.  In normal operation, diagnostic messages
+are printed when invalid options or missing option arguments are
+encountered.
+If the variable
+.SM
+.B OPTERR
+is set to 0, no error messages will be displayed, even if the first
+character of
+.I optstring
+is not a colon.
+.sp 1
+If an invalid option is seen,
+.B getopts
+places ? into
+.I name
+and, if not silent,
+prints an error message and unsets
+.SM
+.BR OPTARG .
+If
+.B getopts
+is silent,
+the option character found is placed in
+.SM
+.B OPTARG
+and no diagnostic message is printed.
+.sp 1
+If a required argument is not found, and
+.B getopts
+is not silent,
+a question mark (\^\fB?\fP\^) is placed in
+.IR name ,
+.SM
+.B OPTARG
+is unset, and a diagnostic message is printed.
+If
+.B getopts
+is silent, then a colon (\^\fB:\fP\^) is placed in
+.I name
+and
+.SM
+.B OPTARG
+is set to the option character found.
+.sp 1
+.B getopts
+returns true if an option, specified or unspecified, is found.
+It returns false if the end of options is encountered or an
+error occurs.
+.TP
+\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
+Each time \fBhash\fP is invoked,
+the full pathname of the command
+.I name
+is determined by searching
+the directories in
+.B $PATH
+and remembered.  Any previously-remembered pathname is discarded.
+If the
+.B \-p
+option is supplied, no path search is performed, and
+.I filename
+is used as the full filename of the command.
+The
+.B \-r
+option causes the shell to forget all
+remembered locations.
+The
+.B \-d
+option causes the shell to forget the remembered location of each \fIname\fP.
+If the
+.B \-t
+option is supplied, the full pathname to which each \fIname\fP corresponds
+is printed.  If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
+the \fIname\fP is printed before the hashed full pathname.
+The
+.B \-l
+option causes output to be displayed in a format that may be reused as input.
+If no arguments are given, or if only \fB\-l\fP is supplied,
+information about remembered commands is printed.
+The return status is true unless a
+.I name
+is not found or an invalid option is supplied.
+.TP
+\fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
+Display helpful information about builtin commands.  If
+.I pattern
+is specified,
+.B help
+gives detailed help on all commands matching
+.IR pattern ;
+otherwise help for all the builtins and shell control structures
+is printed.
+.RS
+.PD 0
+.TP
+.B \-d
+Display a short description of each \fIpattern\fP
+.TP
+.B \-m
+Display the description of each \fIpattern\fP in a manpage-like format
+.TP
+.B \-s
+Display only a short usage synopsis for each \fIpattern\fP
+.PD
+.PP
+The return status is 0 unless no command matches
+.IR pattern .
+.RE
+.TP
+\fBhistory [\fIn\fP]
+.PD 0
+.TP
+\fBhistory\fP \fB\-c\fP
+.TP
+\fBhistory \-d\fP \fIoffset\fP
+.TP
+\fBhistory \-d\fP \fIstart\fP\-\fIend\fP
+.TP
+\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
+.TP
+\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
+.TP
+\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
+.PD
+With no options, display the command
+history list with line numbers.  Lines listed
+with a
+.B *
+have been modified.  An argument of
+.I n
+lists only the last
+.I n
+lines.
+If the shell variable
+.SM
+.B HISTTIMEFORMAT
+is set and not null,
+it is used as a format string for \fIstrftime\fP(3) to display
+the time stamp associated with each displayed history entry.
+No intervening blank is printed between the formatted time stamp
+and the history line.
+If \fIfilename\fP is supplied, it is used as the
+name of the history file; if not, the value of
+.SM
+.B HISTFILE
+is used.  Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-c
+Clear the history list by deleting all the entries.
+.TP
+\fB\-d\fP \fIoffset\fP
+Delete the history entry at position \fIoffset\fP.
+If \fIoffset\fP is negative, it is interpreted as relative to one greater
+than the last history position, so negative indices count back from the
+end of the history, and an index of \-1 refers to the current
+\fBhistory -d\fP command.
+.TP
+\fB\-d\fP \fIstart\fP\-\fIend\fP
+Delete the range of history entries between positions \fIstart\fP and
+\fIend\fP, inclusive.
+Positive and negative values for \fIstart\fP and \fIend\fP
+are interpreted as described above.
+.TP
+.B \-a
+Append the ``new'' history lines to the history file.
+These are history lines entered since the beginning of the current
+\fBbash\fP session, but not already appended to the history file.
+.TP
+.B \-n
+Read the history lines not already read from the history
+file into the current history list.  These are lines
+appended to the history file since the beginning of the
+current \fBbash\fP session.
+.TP
+.B \-r
+Read the contents of the history file
+and append them to the current history list.
+.TP
+.B \-w
+Write the current history list to the history file, overwriting the
+history file's contents.
+.TP
+.B \-p
+Perform history substitution on the following \fIargs\fP and display
+the result on the standard output.
+Does not store the results in the history list.
+Each \fIarg\fP must be quoted to disable normal history expansion.
+.TP
+.B \-s
+Store the
+.I args
+in the history list as a single entry.  The last command in the
+history list is removed before the
+.I args
+are added.
+.PD
+.PP
+If the
+.SM
+.B HISTTIMEFORMAT
+variable is set, the time stamp information
+associated with each history entry is written to the history file,
+marked with the history comment character.
+When the history file is read, lines beginning with the history
+comment character followed immediately by a digit are interpreted
+as timestamps for the following history entry.
+The return value is 0 unless an invalid option is encountered, an
+error occurs while reading or writing the history file, an invalid
+\fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
+history expansion supplied as an argument to \fB\-p\fP fails.
+.RE
+.TP
+\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
+.PD 0
+.TP
+\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
+.PD
+The first form lists the active jobs.  The options have the following
+meanings:
+.RS
+.PD 0
+.TP
+.B \-l
+List process IDs
+in addition to the normal information.
+.TP
+.B \-n
+Display information only about jobs that have changed status since
+the user was last notified of their status.
+.TP
+.B \-p
+List only the process ID of the job's process group
+leader.
+.TP
+.B \-r
+Display only running jobs.
+.TP
+.B \-s
+Display only stopped jobs.
+.PD
+.PP
+If
+.I jobspec
+is given, output is restricted to information about that job.
+The return status is 0 unless an invalid option is encountered
+or an invalid
+.I jobspec
+is supplied.
+.PP
+If the
+.B \-x
+option is supplied,
+.B jobs
+replaces any
+.I jobspec
+found in
+.I command
+or
+.I args
+with the corresponding process group ID, and executes
+.I command
+passing it
+.IR args ,
+returning its exit status.
+.RE
+.TP
+\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
+.PD 0
+.TP
+\fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
+.PD
+Send the signal named by
+.I sigspec
+or
+.I signum
+to the processes named by
+.I pid
+or
+.IR jobspec .
+.I sigspec
+is either a case-insensitive signal name such as
+.SM
+.B SIGKILL
+(with or without the
+.SM
+.B SIG
+prefix) or a signal number;
+.I signum
+is a signal number.
+If
+.I sigspec
+is not present, then
+.SM
+.B SIGTERM
+is assumed.
+An argument of
+.B \-l
+lists the signal names.
+If any arguments are supplied when
+.B \-l
+is given, the names of the signals corresponding to the arguments are
+listed, and the return status is 0.
+The \fIexit_status\fP argument to
+.B \-l
+is a number specifying either a signal number or the exit status of
+a process terminated by a signal.
+The
+.B \-L
+option is equivalent to \fB\-l\fP.
+.B kill
+returns true if at least one signal was successfully sent, or false
+if an error occurs or an invalid option is encountered.
+.TP
+\fBlet\fP \fIarg\fP [\fIarg\fP ...]
+Each
+.I arg
+is an arithmetic expression to be evaluated (see
+.SM
+.B "ARITHMETIC EVALUATION"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+If the last
+.I arg
+evaluates to 0,
+.B let
+returns 1; 0 is returned otherwise.
+.TP
+\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ]
+For each argument, a local variable named
+.I name
+is created, and assigned
+.IR value .
+The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
+When
+.B local
+is used within a function, it causes the variable
+.I name
+to have a visible scope restricted to that function and its children.
+If \fIname\fP is \-, the set of shell options is made local to the function
+in which \fBlocal\fP is invoked: shell options changed using the
+\fBset\fP builtin inside the function are restored to their original values
+when the function returns.
+The restore is effected as if a series of \fBset\fP commands were executed
+to restore the values that were in place before the function.
+With no operands,
+.B local
+writes a list of local variables to the standard output.  It is
+an error to use
+.B local
+when not within a function.  The return status is 0 unless
+.B local
+is used outside a function, an invalid
+.I name
+is supplied, or
+\fIname\fP is a readonly variable.
+.TP
+.B logout
+Exit a login shell.
+.TP
+\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
+.PD 0
+.TP
+\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
+.PD
+Read lines from the standard input into the indexed array variable
+.IR array ,
+or from file descriptor
+.I fd
+if the
+.B \-u
+option is supplied.
+The variable
+.SM
+.B MAPFILE
+is the default \fIarray\fP.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-d
+The first character of \fIdelim\fP is used to terminate each input line,
+rather than newline.
+If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
+when it reads a NUL character.
+.TP
+.B \-n
+Copy at most
+.I count
+lines.  If \fIcount\fP is 0, all lines are copied.
+.TP
+.B \-O
+Begin assigning to
+.I array
+at index
+.IR origin .
+The default index is 0.
+.TP
+.B \-s
+Discard the first \fIcount\fP lines read.
+.TP
+.B \-t
+Remove a trailing \fIdelim\fP (default newline) from each line read.
+.TP
+.B \-u
+Read lines from file descriptor \fIfd\fP instead of the standard input.
+.TP
+.B \-C
+Evaluate
+.I callback
+each time \fIquantum\fP lines are read.  The \fB\-c\fP option specifies
+.IR quantum .
+.TP
+.B \-c
+Specify the number of lines read between each call to
+.IR callback .
+.PD
+.PP
+If
+.B \-C
+is specified without
+.BR \-c ,
+the default quantum is 5000.
+When \fIcallback\fP is evaluated, it is supplied the index of the next
+array element to be assigned and the line to be assigned to that element
+as additional arguments.
+\fIcallback\fP is evaluated after the line is read but before the
+array element is assigned.
+.PP
+If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
+before assigning to it.
+.PP
+\fBmapfile\fP returns successfully unless an invalid option or option
+argument is supplied, \fIarray\fP is invalid or unassignable, or if
+\fIarray\fP is not an indexed array.
+.RE
+.TP
+\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
+Removes entries from the directory stack.
+The elements are numbered from 0 starting at the first directory
+listed by \fBdirs\fP.
+With no arguments, \fBpopd\fP
+removes the top directory from the stack, and
+changes to the new top directory.
+Arguments, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-n
+Suppresses the normal change of directory when removing directories
+from the stack, so that only the stack is manipulated.
+.TP
+\fB+\fP\fIn\fP
+Removes the \fIn\fPth entry counting from the left of the list
+shown by
+.BR dirs ,
+starting with zero, from the stack.
+For example:
+.if n ``popd +0''
+.if t \f(CWpopd +0\fP
+removes the first directory,
+.if n ``popd +1''
+.if t \f(CWpopd +1\fP
+the second.
+.TP
+\fB\-\fP\fIn\fP
+Removes the \fIn\fPth entry counting from the right of the list
+shown by
+.BR dirs ,
+starting with zero.  For example:
+.if n ``popd -0''
+.if t \f(CWpopd -0\fP
+removes the last directory,
+.if n ``popd -1''
+.if t \f(CWpopd -1\fP
+the next to last.
+.PD
+.PP
+If the top element of the directory stack is modified, and
+the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
+builtin to change to the directory at the top of the stack.
+If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
+.PP
+Otherwise,
+.B popd
+returns false if an invalid option is encountered, the directory stack
+is empty, or a non-existent directory stack entry is specified.
+.PP
+If the
+.B popd
+command is successful,
+bash runs
+.B dirs
+to show the final contents of the directory stack,
+and the return status is 0.
+.RE
+.TP
+\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
+Write the formatted \fIarguments\fP to the standard output under the
+control of the \fIformat\fP.
+The \fB\-v\fP option causes the output to be assigned to the variable
+\fIvar\fP rather than being printed to the standard output.
+.sp 1
+The \fIformat\fP is a character string which contains three types of objects:
+plain characters, which are simply copied to standard output, character
+escape sequences, which are converted and copied to the standard output, and
+format specifications, each of which causes printing of the next successive
+\fIargument\fP.
+In addition to the standard \fIprintf\fP(1) format specifications,
+\fBprintf\fP interprets the following extensions:
+.RS
+.PD 0
+.TP
+.B %b
+causes
+\fBprintf\fP to expand backslash escape sequences in the corresponding
+\fIargument\fP
+in the same way as \fBecho \-e\fP.
+.TP
+.B %q
+causes \fBprintf\fP to output the corresponding
+\fIargument\fP in a format that can be reused as shell input.
+.TP
+.B %Q
+like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
+before quoting it.
+.TP
+.B %(\fIdatefmt\fP)T
+causes \fBprintf\fP to output the date-time string resulting from using
+\fIdatefmt\fP as a format string for \fIstrftime\fP(3).
+The corresponding \fIargument\fP is an integer representing the number of
+seconds since the epoch.
+Two special argument values may be used: \-1 represents the current
+time, and \-2 represents the time the shell was invoked.
+If no argument is specified, conversion behaves as if \-1 had been given.
+This is an exception to the usual \fBprintf\fP behavior.
+.PD
+.PP
+The %b, %q, and %T directives all use the field width and precision
+arguments from the format specification and write that many bytes from
+(or use that wide a field for) the expanded argument, which usually
+contains more characters than the original.
+.PP
+Arguments to non-string format specifiers are treated as C constants,
+except that a leading plus or minus sign is allowed, and if the leading
+character is a single or double quote, the value is the ASCII value of
+the following character.
+.PP
+The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
+If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
+extra format specifications behave as if a zero value or null string, as
+appropriate, had been supplied.
+The return value is zero on success, non-zero on failure.
+.RE
+.TP
+\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
+.PD 0
+.TP
+\fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
+.PD
+Adds a directory to the top of the directory stack, or rotates
+the stack, making the new top of the stack the current working
+directory.
+With no arguments, \fBpushd\fP exchanges the top two elements of
+the directory stack.
+Arguments, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-n
+Suppresses the normal change of directory when rotating or
+adding directories to the stack, so that only the stack is manipulated.
+.TP
+\fB+\fP\fIn\fP
+Rotates the stack so that the \fIn\fPth directory
+(counting from the left of the list shown by
+.BR dirs ,
+starting with zero)
+is at the top.
+.TP
+\fB\-\fP\fIn\fP
+Rotates the stack so that the \fIn\fPth directory
+(counting from the right of the list shown by
+.BR dirs ,
+starting with zero) is at the top.
+.TP
+.I dir
+Adds
+.I dir
+to the directory stack at the top
+.PD
+.PP
+After the stack has been modified, if the \fB\-n\fP option was not
+supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
+directory at the top of the stack.
+If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
+.PP
+Otherwise, if no arguments are supplied,
+.B pushd
+returns 0 unless the directory stack is empty.
+When rotating the directory stack,
+.B pushd
+returns 0 unless the directory stack is empty or
+a non-existent directory stack element is specified.
+.PP
+If the
+.B pushd
+command is successful,
+bash runs
+.B dirs
+to show the final contents of the directory stack.
+.RE
+.TP
+\fBpwd\fP [\fB\-LP\fP]
+Print the absolute pathname of the current working directory.
+The pathname printed contains no symbolic links if the
+.B \-P
+option is supplied or the
+.B \-o physical
+option to the
+.B set
+builtin command is enabled.
+If the
+.B \-L
+option is used, the pathname printed may contain symbolic links.
+The return status is 0 unless an error occurs while
+reading the name of the current directory or an
+invalid option is supplied.
+.TP
+\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
+One line is read from the standard input, or from the file descriptor
+\fIfd\fP supplied as an argument to the \fB\-u\fP option,
+split into words as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under \fBWord Splitting\fP,
+and the first word
+is assigned to the first
+.IR name ,
+the second word to the second
+.IR name ,
+and so on.
+If there are more words than names, the remaining words and their
+intervening delimiters are assigned to the last
+.IR name .
+If there are fewer words read from the input stream than names,
+the remaining names are assigned empty values.
+The characters in
+.SM
+.B IFS
+are used to split the line into words using the same rules the shell
+uses for expansion (described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under \fBWord Splitting\fP).
+The backslash character (\fB\e\fP) may be used to remove any special
+meaning for the next character read and for line continuation.
+Options, if supplied, have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-a \fIaname\fP
+The words are assigned to sequential indices
+of the array variable
+.IR aname ,
+starting at 0.
+.I aname
+is unset before any new values are assigned.
+Other \fIname\fP arguments are ignored.
+.TP
+.B \-d \fIdelim\fP
+The first character of \fIdelim\fP is used to terminate the input line,
+rather than newline.
+If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
+when it reads a NUL character.
+.TP
+.B \-e
+If the standard input
+is coming from a terminal,
+.B readline
+(see
+.SM
+.B READLINE
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+is used to obtain the line.
+Readline uses the current (or default, if line editing was not previously
+active) editing settings, but uses readline's default filename completion.
+.TP
+.B \-i \fItext\fP
+If
+.B readline
+is being used to read the line, \fItext\fP is placed into the editing
+buffer before editing begins.
+.TP
+.B \-n \fInchars\fP
+\fBread\fP returns after reading \fInchars\fP characters rather than
+waiting for a complete line of input, but honors a delimiter if fewer
+than \fInchars\fP characters are read before the delimiter.
+.TP
+.B \-N \fInchars\fP
+\fBread\fP returns after reading exactly \fInchars\fP characters rather
+than waiting for a complete line of input, unless EOF is encountered or
+\fBread\fP times out.
+Delimiter characters encountered in the input are
+not treated specially and do not cause \fBread\fP to return until
+\fInchars\fP characters are read.
+The result is not split on the characters in \fBIFS\fP; the intent is
+that the variable is assigned exactly the characters read
+(with the exception of backslash; see the \fB\-r\fP option below).
+.TP
+.B \-p \fIprompt\fP
+Display \fIprompt\fP on standard error, without a
+trailing newline, before attempting to read any input.  The prompt
+is displayed only if input is coming from a terminal.
+.TP
+.B \-r
+Backslash does not act as an escape character.
+The backslash is considered to be part of the line.
+In particular, a backslash-newline pair may not then be used as a line
+continuation.
+.TP
+.B \-s
+Silent mode.  If input is coming from a terminal, characters are
+not echoed.
+.TP
+.B \-t \fItimeout\fP
+Cause \fBread\fP to time out and return failure if a complete line of
+input (or a specified number of characters)
+is not read within \fItimeout\fP seconds.
+\fItimeout\fP may be a decimal number with a fractional portion following
+the decimal point.
+This option is only effective if \fBread\fP is reading input from a
+terminal, pipe, or other special file; it has no effect when reading
+from regular files.
+If \fBread\fP times out, \fBread\fP saves any partial input read into
+the specified variable \fIname\fP.
+If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
+read any data.
+The exit status is 0 if input is available on the specified file descriptor,
+or the read will return EOF,
+non-zero otherwise.
+The exit status is greater than 128 if the timeout is exceeded.
+.TP
+.B \-u \fIfd\fP
+Read input from file descriptor \fIfd\fP.
+.PD
+.PP
+If no
+.I names
+are supplied, the line read,
+without the ending delimiter but otherwise unmodified,
+is assigned to the variable
+.SM
+.BR REPLY .
+The exit status is zero, unless end-of-file is encountered, \fBread\fP
+times out (in which case the status is greater than 128),
+a variable assignment error (such as assigning to a readonly variable) occurs,
+or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
+.RE
+.TP
+\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]
+.PD
+The given
+\fInames\fP are marked readonly; the values of these
+.I names
+may not be changed by subsequent assignment.
+If the
+.B \-f
+option is supplied, the functions corresponding to the
+\fInames\fP are so
+marked.
+The
+.B \-a
+option restricts the variables to indexed arrays; the
+.B \-A
+option restricts the variables to associative arrays.
+If both options are supplied,
+.B \-A
+takes precedence.
+If no
+.I name
+arguments are given, or if the
+.B \-p
+option is supplied, a list of all readonly names is printed.
+The other options may be used to restrict the output to a subset of
+the set of readonly names.
+The
+.B \-p
+option causes output to be displayed in a format that
+may be reused as input.
+If a variable name is followed by =\fIword\fP, the value of
+the variable is set to \fIword\fP.
+The return status is 0 unless an invalid option is encountered,
+one of the
+.I names
+is not a valid shell variable name, or
+.B \-f
+is supplied with a
+.I name
+that is not a function.
+.TP
+\fBreturn\fP [\fIn\fP]
+Causes a function to stop executing and return the value specified by
+.I n
+to its caller.
+If
+.I n
+is omitted, the return status is that of the last command
+executed in the function body.
+If \fBreturn\fP is executed by a trap handler, the last command used to
+determine the status is the last command executed before the trap handler.
+If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
+used to determine the status is the last command executed by the trap
+handler before \fBreturn\fP was invoked.
+If
+.B return
+is used outside a function,
+but during execution of a script by the
+.B .
+(\fBsource\fP) command, it causes the shell to stop executing
+that script and return either
+.I n
+or the exit status of the last command executed within the
+script as the exit status of the script.
+If \fIn\fP is supplied, the return value is its least significant
+8 bits.
+The return status is non-zero if
+.B return
+is supplied a non-numeric argument, or
+is used outside a
+function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
+Any command associated with the \fBRETURN\fP trap is executed
+before execution resumes after the function or script.
+.TP
+\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
+.PD 0
+.TP
+\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
+.PD
+Without options, display the name and value of each shell variable
+in a format that can be reused as input
+for setting or resetting the currently-set variables.
+Read-only variables cannot be reset.
+In \fIposix mode\fP, only shell variables are listed.
+The output is sorted according to the current locale.
+When options are specified, they set or unset shell attributes.
+Any arguments remaining after option processing are treated
+as values for the positional parameters and are assigned, in order, to
+.BR $1 ,
+.BR $2 ,
+.B ...
+.BR $\fIn\fP .
+Options, if specified, have the following meanings:
+.RS
+.PD 0
+.TP 8
+.B \-a
+Each variable or function that is created or modified is given the
+export attribute and marked for export to the environment of
+subsequent commands.
+.TP 8
+.B \-b
+Report the status of terminated background jobs
+immediately, rather than before the next primary prompt.  This is
+effective only when job control is enabled.
+.TP 8
+.B \-e
+Exit immediately if a
+\fIpipeline\fP (which may consist of a single \fIsimple command\fP),
+a \fIlist\fP,
+or a \fIcompound command\fP
+(see
+.SM
+.B SHELL GRAMMAR
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+exits with a non-zero status.
+The shell does not exit if the
+command that fails is part of the command list immediately following a
+.B while
+or
+.B until
+keyword,
+part of the test following the
+.B if
+or
+.B elif
+reserved words, part of any command executed in a
+.B &&
+or
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
+any command in a pipeline but the last,
+or if the command's return value is
+being inverted with
+.BR ! .
+If a compound command other than a subshell
+returns a non-zero status because a command failed
+while \fB\-e\fP was being ignored, the shell does not exit.
+A trap on \fBERR\fP, if set, is executed before the shell exits.
+This option applies to the shell environment and each subshell environment
+separately (see
+.SM
+.B "COMMAND EXECUTION ENVIRONMENT"
+.ie \n(zZ=1 in \fIbash(1)\fP),
+.el above),
+and may cause
+subshells to exit before executing all the commands in the subshell.
+.if t .sp 0.5
+.if n .sp 1
+If a compound command or shell function executes in a context
+where \fB\-e\fP is being ignored,
+none of the commands executed within the compound command or function body
+will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
+and a command returns a failure status.
+If a compound command or shell function sets \fB\-e\fP while executing in
+a context where \fB\-e\fP is ignored, that setting will not have any
+effect until the compound command or the command containing the function
+call completes.
+.TP 8
+.B \-f
+Disable pathname expansion.
+.TP 8
+.B \-h
+Remember the location of commands as they are looked up for execution.
+This is enabled by default.
+.TP 8
+.B \-k
+All arguments in the form of assignment statements
+are placed in the environment for a command, not just
+those that precede the command name.
+.TP 8
+.B \-m
+Monitor mode.  Job control is enabled.  This option is on
+by default for interactive shells on systems that support
+it (see
+.SM
+.B JOB CONTROL
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+All processes run in a separate process group.
+When a background job completes, the shell prints a line
+containing its exit status.
+.TP 8
+.B \-n
+Read commands but do not execute them.
+This may be used to check a shell script for syntax errors.
+This is ignored by interactive shells.
+.TP 8
+.B \-o \fIoption\-name\fP
+The \fIoption\-name\fP can be one of the following:
+.RS
+.TP 8
+.B allexport
+Same as
+.BR \-a .
+.TP 8
+.B braceexpand
+Same as
+.BR \-B .
+.TP 8
+.B emacs
+Use an emacs-style command line editing interface.  This is enabled
+by default when the shell is interactive, unless the shell is started
+with the
+.B \-\-noediting
+option.
+This also affects the editing interface used for \fBread \-e\fP.
+.TP 8
+.B errexit
+Same as
+.BR \-e .
+.TP 8
+.B errtrace
+Same as
+.BR \-E .
+.TP 8
+.B functrace
+Same as
+.BR \-T .
+.TP 8
+.B hashall
+Same as
+.BR \-h .
+.TP 8
+.B histexpand
+Same as
+.BR \-H .
+.TP 8
+.B history
+Enable command history, as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR HISTORY .
+This option is on by default in interactive shells.
+.TP 8
+.B ignoreeof
+The effect is as if the shell command
+.if t \f(CWIGNOREEOF=10\fP
+.if n ``IGNOREEOF=10''
+had been executed
+(see
+.B Shell Variables
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP 8
+.B keyword
+Same as
+.BR \-k .
+.TP 8
+.B monitor
+Same as
+.BR \-m .
+.TP 8
+.B noclobber
+Same as
+.BR \-C .
+.TP 8
+.B noexec
+Same as
+.BR \-n .
+.TP 8
+.B noglob
+Same as
+.BR \-f .
+.TP 8
+.B nolog
+Currently ignored.
+.TP 8
+.B notify
+Same as
+.BR \-b .
+.TP 8
+.B nounset
+Same as
+.BR \-u .
+.TP 8
+.B onecmd
+Same as
+.BR \-t .
+.TP 8
+.B physical
+Same as
+.BR \-P .
+.TP 8
+.B pipefail
+If set, the return value of a pipeline is the value of the last
+(rightmost) command to exit with a non-zero status, or zero if all
+commands in the pipeline exit successfully.
+This option is disabled by default.
+.TP 8
+.B posix
+Change the behavior of
+.B bash
+where the default operation differs
+from the POSIX standard to match the standard (\fIposix mode\fP).
+See
+.SM
+.B "SEE ALSO"
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el below
+for a reference to a document that details how posix mode affects
+bash's behavior.
+.TP 8
+.B privileged
+Same as
+.BR \-p .
+.TP 8
+.B verbose
+Same as
+.BR \-v .
+.TP 8
+.B vi
+Use a vi-style command line editing interface.
+This also affects the editing interface used for \fBread \-e\fP.
+.TP 8
+.B xtrace
+Same as
+.BR \-x .
+.sp .5
+.PP
+If
+.B \-o
+is supplied with no \fIoption\-name\fP, the values of the current options are
+printed.
+If
+.B +o
+is supplied with no \fIoption\-name\fP, a series of
+.B set
+commands to recreate the current option settings is displayed on
+the standard output.
+.RE
+.TP 8
+.B \-p
+Turn on
+.I privileged
+mode.  In this mode, the
+.SM
+.B $ENV
+and
+.SM
+.B $BASH_ENV
+files are not processed, shell functions are not inherited from the
+environment, and the
+.SM
+.BR SHELLOPTS ,
+.SM
+.BR BASHOPTS ,
+.SM
+.BR CDPATH ,
+and
+.SM
+.B GLOBIGNORE
+variables, if they appear in the environment, are ignored.
+If the shell is started with the effective user (group) id not equal to the
+real user (group) id, and the \fB\-p\fP option is not supplied, these actions
+are taken and the effective user id is set to the real user id.
+If the \fB\-p\fP option is supplied at startup, the effective user id is
+not reset.
+Turning this option off causes the effective user
+and group ids to be set to the real user and group ids.
+.TP 8
+.B \-r
+Enable restricted shell mode.
+This option cannot be unset once it has been set.
+.TP 8
+.B \-t
+Exit after reading and executing one command.
+.TP 8
+.B \-u
+Treat unset variables and parameters other than the special
+parameters "@" and "*",
+or array variables subscripted with "@" or "*",
+as an error when performing
+parameter expansion.  If expansion is attempted on an
+unset variable or parameter, the shell prints an error message, and,
+if not interactive, exits with a non-zero status.
+.TP 8
+.B \-v
+Print shell input lines as they are read.
+.TP 8
+.B \-x
+After expanding each \fIsimple command\fP,
+\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
+arithmetic \fBfor\fP command, display the expanded value of
+.SM
+.BR PS4 ,
+followed by the command and its expanded arguments
+or associated word list.
+.TP 8
+.B \-B
+The shell performs brace expansion (see
+.B Brace Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This is on by default.
+.TP 8
+.B \-C
+If set,
+.B bash
+does not overwrite an existing file with the
+.BR > ,
+.BR >& ,
+and
+.B <>
+redirection operators.  This may be overridden when
+creating output files by using the redirection operator
+.B >|
+instead of
+.BR > .
+.TP 8
+.B \-E
+If set, any trap on \fBERR\fP is inherited by shell functions, command
+substitutions, and commands executed in a subshell environment.
+The \fBERR\fP trap is normally not inherited in such cases.
+.TP 8
+.B \-H
+Enable
+.B !
+style history substitution.  This option is on by
+default when the shell is interactive.
+.TP 8
+.B \-P
+If set, the shell does not resolve symbolic links when executing
+commands such as
+.B cd
+that change the current working directory.  It uses the
+physical directory structure instead.  By default,
+.B bash
+follows the logical chain of directories when performing commands
+which change the current directory.
+.TP 8
+.B \-T
+If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
+functions, command substitutions, and commands executed in a
+subshell environment.
+The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
+in such cases.
+.TP 8
+.B \-\-
+If no arguments follow this option, then the positional parameters are
+unset.  Otherwise, the positional parameters are set to the
+\fIarg\fPs, even if some of them begin with a
+.BR \- .
+.TP 8
+.B \-
+Signal the end of options, cause all remaining \fIarg\fPs to be
+assigned to the positional parameters.  The
+.B \-x
+and
+.B \-v
+options are turned off.
+If there are no \fIarg\fPs,
+the positional parameters remain unchanged.
+.PD
+.PP
+The options are off by default unless otherwise noted.
+Using + rather than \- causes these options to be turned off.
+The options can also be specified as arguments to an invocation of
+the shell.
+The current set of options may be found in
+.BR $\- .
+The return status is always true unless an invalid option is encountered.
+.RE
+.TP
+\fBshift\fP [\fIn\fP]
+The positional parameters from \fIn\fP+1 ... are renamed to
+.B $1
+.B ....
+Parameters represented by the numbers \fB$#\fP
+down to \fB$#\fP\-\fIn\fP+1 are unset.
+.I n
+must be a non-negative number less than or equal to \fB$#\fP.
+If
+.I n
+is 0, no parameters are changed.
+If
+.I n
+is not given, it is assumed to be 1.
+If
+.I n
+is greater than \fB$#\fP, the positional parameters are not changed.
+The return status is greater than zero if
+.I n
+is greater than
+.B $#
+or less than zero; otherwise 0.
+.TP
+\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
+Toggle the values of settings controlling optional shell behavior.
+The settings can be either those listed below, or, if the
+.B \-o
+option is used, those available with the
+.B \-o
+option to the \fBset\fP builtin command.
+With no options, or with the
+.B \-p
+option, a list of all settable options is displayed, with
+an indication of whether or not each is set;
+if \fIoptnames\fP are supplied, the output is restricted to those options.
+The \fB\-p\fP option causes output to be displayed in a form that
+may be reused as input.
+Other options have the following meanings:
+.RS
+.PD 0
+.TP
+.B \-s
+Enable (set) each \fIoptname\fP.
+.TP
+.B \-u
+Disable (unset) each \fIoptname\fP.
+.TP
+.B \-q
+Suppresses normal output (quiet mode); the return status indicates
+whether the \fIoptname\fP is set or unset.
+If multiple \fIoptname\fP arguments are given with
+.BR \-q ,
+the return status is zero if all \fIoptnames\fP are enabled; non-zero
+otherwise.
+.TP
+.B \-o
+Restricts the values of \fIoptname\fP to be those defined for the
+.B \-o
+option to the
+.B set
+builtin.
+.PD
+.PP
+If either
+.B \-s
+or
+.B \-u
+is used with no \fIoptname\fP arguments,
+.B shopt
+shows only those options which are set or unset, respectively.
+Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
+by default.
+.PP
+The return status when listing options is zero if all \fIoptnames\fP
+are enabled, non-zero otherwise.  When setting or unsetting options,
+the return status is zero unless an \fIoptname\fP is not a valid shell
+option.
+.PP
+The list of \fBshopt\fP options is:
+.if t .sp .5v
+.if n .sp 1v
+.PD 0
+.TP 8
+.B assoc_expand_once
+If set, the shell suppresses multiple evaluation of associative array
+subscripts during arithmetic expression evaluation, while executing
+builtins that can perform variable assignments,
+and while executing builtins that perform array dereferencing.
+.TP 8
+.B autocd
+If set, a command name that is the name of a directory is executed as if
+it were the argument to the \fBcd\fP command.
+This option is only used by interactive shells.
+.TP 8
+.B cdable_vars
+If set, an argument to the
+.B cd
+builtin command that
+is not a directory is assumed to be the name of a variable whose
+value is the directory to change to.
+.TP 8
+.B cdspell
+If set, minor errors in the spelling of a directory component in a
+.B cd
+command will be corrected.
+The errors checked for are transposed characters,
+a missing character, and one character too many.
+If a correction is found, the corrected filename is printed,
+and the command proceeds.
+This option is only used by interactive shells.
+.TP 8
+.B checkhash
+If set, \fBbash\fP checks that a command found in the hash
+table exists before trying to execute it.  If a hashed command no
+longer exists, a normal path search is performed.
+.TP 8
+.B checkjobs
+If set, \fBbash\fP lists the status of any stopped and running jobs before
+exiting an interactive shell.  If any jobs are running, this causes
+the exit to be deferred until a second exit is attempted without an
+intervening command (see
+.SM
+.B "JOB CONTROL"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+The shell always postpones exiting if any jobs are stopped.
+.TP 8
+.B checkwinsize
+If set, \fBbash\fP checks the window size after each external (non-builtin)
+command and, if necessary, updates the values of
+.SM
+.B LINES
+and
+.SM
+.BR COLUMNS .
+This option is enabled by default.
+.TP 8
+.B cmdhist
+If set,
+.B bash
+attempts to save all lines of a multiple-line
+command in the same history entry.  This allows
+easy re-editing of multi-line commands.
+This option is enabled by default, but only has an effect if command
+history is enabled, as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR HISTORY .
+.PD 0
+.TP 8
+.B compat31
+.TP 8
+.B compat32
+.TP 8
+.B compat40
+.TP 8
+.B compat41
+.TP 8
+.B compat42
+.TP 8
+.B compat43
+.TP 8
+.B compat44
+.TP 8
+.B compat50
+.PD
+These control aspects of the shell's compatibility mode
+(see
+.SM
+.B "SHELL COMPATIBILITY MODE"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el below).
+.TP 8
+.B complete_fullquote
+If set,
+.B bash
+quotes all shell metacharacters in filenames and directory names when
+performing completion.
+If not set,
+.B bash
+removes metacharacters such as the dollar sign from the set of
+characters that will be quoted in completed filenames
+when these metacharacters appear in shell variable references in words to be
+completed.
+This means that dollar signs in variable names that expand to directories
+will not be quoted;
+however, any dollar signs appearing in filenames will not be quoted, either.
+This is active only when bash is using backslashes to quote completed
+filenames.
+This variable is set by default, which is the default bash behavior in
+versions through 4.2.
+.TP 8
+.B direxpand
+If set,
+.B bash
+replaces directory names with the results of word expansion when performing
+filename completion.  This changes the contents of the readline editing
+buffer.
+If not set,
+.B bash
+attempts to preserve what the user typed.
+.TP 8
+.B dirspell
+If set,
+.B bash
+attempts spelling correction on directory names during word completion
+if the directory name initially supplied does not exist.
+.TP 8
+.B dotglob
+If set,
+.B bash
+includes filenames beginning with a `.' in the results of pathname
+expansion.
+The filenames
+.B ``.''
+and
+.B ``..''
+must always be matched explicitly, even if
+.B dotglob
+is set.
+.TP 8
+.B execfail
+If set, a non-interactive shell will not exit if
+it cannot execute the file specified as an argument to the
+.B exec
+builtin command.  An interactive shell does not exit if
+.B exec
+fails.
+.TP 8
+.B expand_aliases
+If set, aliases are expanded as described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR ALIASES .
+This option is enabled by default for interactive shells.
+.TP 8
+.B extdebug
+If set at shell invocation,
+or in a shell startup file,
+arrange to execute the debugger profile
+before the shell starts, identical to the \fB\-\-debugger\fP option.
+If set after invocation, behavior intended for use by debuggers is enabled:
+.RS
+.TP
+.B 1.
+The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
+file name and line number corresponding to each function name supplied
+as an argument.
+.TP
+.B 2.
+If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
+next command is skipped and not executed.
+.TP
+.B 3.
+If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
+shell is executing in a subroutine (a shell function or a shell script
+executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
+a call to \fBreturn\fP.
+.TP
+.B 4.
+.SM
+.B BASH_ARGC
+and
+.SM
+.B BASH_ARGV
+are updated as described in their descriptions
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP
+.B 5.
+Function tracing is enabled: command substitution, shell functions, and
+subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
+\fBDEBUG\fP and \fBRETURN\fP traps.
+.TP
+.B 6.
+Error tracing is enabled: command substitution, shell functions, and
+subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
+\fBERR\fP trap.
+.RE
+.TP 8
+.B extglob
+If set, the extended pattern matching features described
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+\fBPathname Expansion\fP are enabled.
+.TP 8
+.B extquote
+If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
+performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
+enclosed in double quotes.  This option is enabled by default.
+.TP 8
+.B failglob
+If set, patterns which fail to match filenames during pathname expansion
+result in an expansion error.
+.TP 8
+.B force_fignore
+If set, the suffixes specified by the
+.SM
+.B FIGNORE
+shell variable
+cause words to be ignored when performing word completion even if
+the ignored words are the only possible completions.
+See
+.SM
+\fBSHELL VARIABLES\fP
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+for a description of
+.SM
+.BR FIGNORE .
+This option is enabled by default.
+.TP 8
+.B globasciiranges
+If set, range expressions used in pattern matching bracket expressions (see
+.SM
+.B Pattern Matching
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+behave as if in the traditional C locale when performing
+comparisons.  That is, the current locale's collating sequence
+is not taken into account, so
+.B b
+will not collate between
+.B A
+and
+.BR B ,
+and upper-case and lower-case ASCII characters will collate together.
+.TP 8
+.B globskipdots
+If set, pathname expansion will never match the filenames
+.B ``.''
+and
+.BR ``..'' ,
+even if the pattern begins with a
+.BR ``.'' .
+This option is enabled by default.
+.TP 8
+.B globstar
+If set, the pattern \fB**\fP used in a pathname expansion context will
+match all files and zero or more directories and subdirectories.
+If the pattern is followed by a \fB/\fP, only directories and
+subdirectories match.
+.TP 8
+.B gnu_errfmt
+If set, shell error messages are written in the standard GNU error
+message format.
+.TP 8
+.B histappend
+If set, the history list is appended to the file named by the value
+of the
+.SM
+.B HISTFILE
+variable when the shell exits, rather than overwriting the file.
+.TP 8
+.B histreedit
+If set, and
+.B readline
+is being used, a user is given the opportunity to re-edit a
+failed history substitution.
+.TP 8
+.B histverify
+If set, and
+.B readline
+is being used, the results of history substitution are not immediately
+passed to the shell parser.  Instead, the resulting line is loaded into
+the \fBreadline\fP editing buffer, allowing further modification.
+.TP 8
+.B hostcomplete
+If set, and
+.B readline
+is being used, \fBbash\fP will attempt to perform hostname completion when a
+word containing a \fB@\fP is being completed (see
+.B Completing
+under
+.SM
+.B READLINE
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This is enabled by default.
+.TP 8
+.B huponexit
+If set, \fBbash\fP will send
+.SM
+.B SIGHUP
+to all jobs when an interactive login shell exits.
+.TP 8
+.B inherit_errexit
+If set, command substitution inherits the value of the \fBerrexit\fP option,
+instead of unsetting it in the subshell environment.
+This option is enabled when \fIposix mode\fP is enabled.
+.TP 8
+.B interactive_comments
+If set, allow a word beginning with
+.B #
+to cause that word and all remaining characters on that
+line to be ignored in an interactive shell (see
+.SM
+.B COMMENTS
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+This option is enabled by default.
+.TP 8
+.B lastpipe
+If set, and job control is not active, the shell runs the last command of
+a pipeline not executed in the background in the current shell environment.
+.TP 8
+.B lithist
+If set, and the
+.B cmdhist
+option is enabled, multi-line commands are saved to the history with
+embedded newlines rather than using semicolon separators where possible.
+.TP 8
+.B localvar_inherit
+If set, local variables inherit the value and attributes of a variable of
+the same name that exists at a previous scope before any new value is
+assigned.  The nameref attribute is not inherited.
+.TP 8
+.B localvar_unset
+If set, calling \fBunset\fP on local variables in previous function scopes
+marks them so subsequent lookups find them unset until that function
+returns. This is identical to the behavior of unsetting local variables
+at the current function scope.
+.TP 8
+.B login_shell
+The shell sets this option if it is started as a login shell (see
+.SM
+.B "INVOCATION"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+The value may not be changed.
+.TP 8
+.B mailwarn
+If set, and a file that \fBbash\fP is checking for mail has been
+accessed since the last time it was checked, the message ``The mail in
+\fImailfile\fP has been read'' is displayed.
+.TP 8
+.B no_empty_cmd_completion
+If set, and
+.B readline
+is being used,
+.B bash
+will not attempt to search the
+.SM
+.B PATH
+for possible completions when
+completion is attempted on an empty line.
+.TP 8
+.B nocaseglob
+If set,
+.B bash
+matches filenames in a case\-insensitive fashion when performing pathname
+expansion (see
+.B Pathname Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+.TP 8
+.B nocasematch
+If set,
+.B bash
+matches patterns in a case\-insensitive fashion when performing matching
+while executing \fBcase\fP or \fB[[\fP conditional commands,
+when performing pattern substitution word expansions,
+or when filtering possible completions as part of programmable completion.
+.TP 8
+.B noexpand_translation
+If set,
+.B bash
+encloses the translated results of $"..." quoting in single quotes
+instead of double quotes.
+If the string is not translated, this has no effect.
+.TP 8
+.B nullglob
+If set,
+.B bash
+allows patterns which match no
+files (see
+.B Pathname Expansion
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+to expand to a null string, rather than themselves.
+.TP 8
+.B patsub_replacement
+If set, \fBbash\fP
+expands occurrences of \fB&\fP in the replacement string of pattern
+substitution to the text matched by the pattern, as described
+under \fBParameter Expansion\fP
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+This option is enabled by default.
+.TP 8
+.B progcomp
+If set, the programmable completion facilities (see
+\fBProgrammable Completion\fP
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+are enabled.
+This option is enabled by default.
+.TP 8
+.B progcomp_alias
+If set, and programmable completion is enabled, \fBbash\fP treats a command
+name that doesn't have any completions as a possible alias and attempts
+alias expansion. If it has an alias, \fBbash\fP attempts programmable
+completion using the command word resulting from the expanded alias.
+.TP 8
+.B promptvars
+If set, prompt strings undergo
+parameter expansion, command substitution, arithmetic
+expansion, and quote removal after being expanded as described in
+.SM
+.B PROMPTING
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+This option is enabled by default.
+.TP 8
+.B restricted_shell
+The shell sets this option if it is started in restricted mode
+(see
+.SM
+.B "RESTRICTED SHELL"
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el below).
+The value may not be changed.
+This is not reset when the startup files are executed, allowing
+the startup files to discover whether or not a shell is restricted.
+.TP 8
+.B shift_verbose
+If set, the
+.B shift
+builtin prints an error message when the shift count exceeds the
+number of positional parameters.
+.TP 8
+.B sourcepath
+If set, the
+\fB.\fP (\fBsource\fP) builtin uses the value of
+.SM
+.B PATH
+to find the directory containing the file supplied as an argument.
+This option is enabled by default.
+.TP 8
+.B varredir_close
+If set, the shell automatically closes file descriptors assigned using the
+\fI{varname}\fP redirection syntax (see
+.SM
+.B REDIRECTION
+.ie \n(zZ=1 in \fIbash(1)\fP)
+.el above)
+instead of leaving them open when the command completes.
+.TP 8
+.B xpg_echo
+If set, the \fBecho\fP builtin expands backslash-escape sequences
+by default.
+.RE
+.PD
+.TP
+\fBsuspend\fP [\fB\-f\fP]
+Suspend the execution of this shell until it receives a
+.SM
+.B SIGCONT
+signal.  A login shell,
+or a shell without job control enabled,
+cannot be suspended; the
+.B \-f
+option can be used to override this and force the suspension.
+The return status is 0 unless the shell is a login shell
+or job control is not enabled
+and
+.B \-f
+is not supplied.
+.TP
+\fBtest\fP \fIexpr\fP
+.PD 0
+.TP
+\fB[\fP \fIexpr\fP \fB]\fP
+Return a status of 0 (true) or 1 (false) depending on
+the evaluation of the conditional expression
+.IR expr .
+Each operator and operand must be a separate argument.
+Expressions are composed of the primaries described 
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" .
+\fBtest\fP does not accept any options, nor does it accept and ignore
+an argument of \fB\-\-\fP as signifying the end of options.
+.if t .sp 0.5
+.if n .sp 1
+Expressions may be combined using the following operators, listed
+in decreasing order of precedence.
+The evaluation depends on the number of arguments; see below.
+Operator precedence is used when there are five or more arguments.
+.RS
+.PD 0
+.TP
+.B ! \fIexpr\fP
+True if
+.I expr
+is false.
+.TP
+.B ( \fIexpr\fP )
+Returns the value of \fIexpr\fP.
+This may be used to override the normal precedence of operators.
+.TP
+\fIexpr1\fP \-\fBa\fP \fIexpr2\fP
+True if both
+.I expr1
+and
+.I expr2
+are true.
+.TP
+\fIexpr1\fP \-\fBo\fP \fIexpr2\fP
+True if either
+.I expr1
+or
+.I expr2
+is true.
+.PD
+.PP
+\fBtest\fP and \fB[\fP evaluate conditional
+expressions using a set of rules based on the number of arguments.
+.if t .sp 0.5
+.if n .sp 1
+.PD 0
+.TP
+0 arguments
+The expression is false.
+.TP
+1 argument
+The expression is true if and only if the argument is not null.
+.TP
+2 arguments
+If the first argument is \fB!\fP, the expression is true if and
+only if the second argument is null.
+If the first argument is one of the unary conditional operators listed
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" ,
+the expression is true if the unary test is true.
+If the first argument is not a valid unary conditional operator, the expression
+is false.
+.TP
+3 arguments
+The following conditions are applied in the order listed.
+If the second argument is one of the binary conditional operators listed
+.ie \n(zZ=1 in \fIbash(1)\fP
+.el above
+under
+.SM
+.BR "CONDITIONAL EXPRESSIONS" ,
+the result of the expression is the result of the binary test using
+the first and third arguments as operands.
+The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
+when there are three arguments.
+If the first argument is \fB!\fP, the value is the negation of
+the two-argument test using the second and third arguments.
+If the first argument is exactly \fB(\fP and the third argument is
+exactly \fB)\fP, the result is the one-argument test of the second
+argument.
+Otherwise, the expression is false.
+.TP
+4 arguments
+The following conditions are applied in the order listed.
+If the first argument is \fB!\fP, the result is the negation of
+the three-argument expression composed of the remaining arguments.
+the two-argument test using the second and third arguments.
+If the first argument is exactly \fB(\fP and the fourth argument is
+exactly \fB)\fP, the result is the two-argument test of the second
+and third arguments.
+Otherwise, the expression is parsed and evaluated according to
+precedence using the rules listed above.
+.TP
+5 or more arguments
+The expression is parsed and evaluated according to precedence
+using the rules listed above.
+.if t .sp 0.5
+.if n .sp 1
+.LP
+When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators
+sort lexicographically using ASCII ordering.
+.RE
+.PD
+.TP
+.B times
+Print the accumulated user and system times for the shell and
+for processes run from the shell.  The return status is 0.
+.TP
+\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...]
+The command
+.I arg
+is to be read and executed when the shell receives
+signal(s)
+.IR sigspec .
+If
+.I arg
+is absent (and there is a single \fIsigspec\fP) or
+.BR \- ,
+each specified signal is
+reset to its original disposition (the value it had
+upon entrance to the shell).
+If
+.I arg
+is the null string the signal specified by each
+.I sigspec
+is ignored by the shell and by the commands it invokes.
+If
+.I arg
+is not present and
+.B \-p
+has been supplied, then the trap commands associated with each
+.I sigspec
+are displayed.
+If no arguments are supplied or if only
+.B \-p
+is given,
+.B trap
+prints the list of commands associated with each signal.
+The
+.B \-l
+option causes the shell to print a list of signal names and
+their corresponding numbers.
+Each
+.I sigspec
+is either
+a signal name defined in <\fIsignal.h\fP>, or a signal number.
+Signal names are case insensitive and the
+.SM
+.B SIG
+prefix is optional.
+.if t .sp 0.5
+.if n .sp 1
+If a
+.I sigspec
+is
+.SM
+.B EXIT
+(0) the command
+.I arg
+is executed on exit from the shell.
+If a
+.I sigspec
+is
+.SM
+.BR DEBUG ,
+the command
+.I arg
+is executed before every \fIsimple command\fP, \fIfor\fP command,
+\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP
+command, and before the first command executes in a shell function (see
+.SM
+.B SHELL GRAMMAR
+.ie \n(zZ=1 in \fIbash(1)\fP).
+.el above).
+Refer to the description of the \fBextdebug\fP option to the
+\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
+If a
+.I sigspec
+is
+.SM
+.BR RETURN ,
+the command
+.I arg
+is executed each time a shell function or a script executed with
+the \fB.\fP or \fBsource\fP builtins finishes executing.
+.if t .sp 0.5
+.if n .sp 1
+If a
+.I sigspec
+is
+.SM
+.BR ERR ,
+the command
+.I arg
+is executed whenever
+a pipeline (which may consist of a single simple
+command), a list, or a compound command returns a
+non\-zero exit status,
+subject to the following conditions.
+The
+.SM
+.B ERR
+trap is not executed if the failed
+command is part of the command list immediately following a
+.B while
+or
+.B until
+keyword,
+part of the test in an
+.I if
+statement, part of a command executed in a
+.B &&
+or
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
+any command in a pipeline but the last,
+or if the command's return value is
+being inverted using
+.BR ! .
+These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
+.if t .sp 0.5
+.if n .sp 1
+Signals ignored upon entry to the shell cannot be trapped or reset.
+Trapped signals that are not being ignored are reset to their original
+values in a subshell or subshell environment when one is created.
+The return status is false if any
+.I sigspec
+is invalid; otherwise
+.B trap
+returns true.
+.TP
+\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...]
+With no options,
+indicate how each
+.I name
+would be interpreted if used as a command name.
+If the
+.B \-t
+option is used,
+.B type
+prints a string which is one of
+.IR alias ,
+.IR keyword ,
+.IR function ,
+.IR builtin ,
+or
+.I file
+if
+.I name
+is an alias, shell reserved word, function, builtin, or disk file,
+respectively.
+If the
+.I name
+is not found, then nothing is printed, and an exit status of false
+is returned.
+If the
+.B \-p
+option is used,
+.B type
+either returns the name of the disk file
+that would be executed if
+.I name
+were specified as a command name,
+or nothing if
+.if t \f(CWtype -t name\fP
+.if n ``type -t name''
+would not return
+.IR file .
+The
+.B \-P
+option forces a
+.SM
+.B PATH
+search for each \fIname\fP, even if
+.if t \f(CWtype -t name\fP
+.if n ``type -t name''
+would not return
+.IR file .
+If a command is hashed,
+.B \-p
+and
+.B \-P
+print the hashed value, which is not necessarily the file that appears
+first in
+.SM
+.BR PATH .
+If the
+.B \-a
+option is used,
+.B type
+prints all of the places that contain
+an executable named
+.IR name .
+This includes aliases and functions,
+if and only if the
+.B \-p
+option is not also used.
+The table of hashed commands is not consulted
+when using
+.BR \-a .
+The
+.B \-f
+option suppresses shell function lookup, as with the \fBcommand\fP builtin.
+.B type
+returns true if all of the arguments are found, false if
+any are not found.
+.TP
+\fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
+.PD 0
+.TP
+\fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
+.PD
+Provides control over the resources available to the shell and to
+processes started by it, on systems that allow such control.
+The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
+set for the given resource.
+A hard limit cannot be increased by a non-root user once it is set;
+a soft limit may be increased up to the value of the hard limit.
+If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
+limits are set.
+The value of
+.I limit
+can be a number in the unit specified for the resource
+or one of the special values
+.BR hard ,
+.BR soft ,
+or
+.BR unlimited ,
+which stand for the current hard limit, the current soft limit, and
+no limit, respectively.
+If
+.I limit
+is omitted, the current value of the soft limit of the resource is
+printed, unless the \fB\-H\fP option is given.  When more than one
+resource is specified, the limit name and unit, if appropriate,
+are printed before the value.
+Other options are interpreted as follows:
+.RS
+.PD 0
+.TP
+.B \-a
+All current limits are reported; no limits are set
+.TP
+.B \-b
+The maximum socket buffer size
+.TP
+.B \-c
+The maximum size of core files created
+.TP
+.B \-d
+The maximum size of a process's data segment
+.TP
+.B \-e
+The maximum scheduling priority ("nice")
+.TP
+.B \-f
+The maximum size of files written by the shell and its children
+.TP
+.B \-i
+The maximum number of pending signals
+.TP
+.B \-k
+The maximum number of kqueues that may be allocated
+.TP
+.B \-l
+The maximum size that may be locked into memory
+.TP
+.B \-m
+The maximum resident set size (many systems do not honor this limit)
+.TP
+.B \-n
+The maximum number of open file descriptors (most systems do not
+allow this value to be set)
+.TP
+.B \-p
+The pipe size in 512-byte blocks (this may not be set)
+.TP
+.B \-q
+The maximum number of bytes in POSIX message queues
+.TP
+.B \-r
+The maximum real-time scheduling priority
+.TP
+.B \-s
+The maximum stack size
+.TP
+.B \-t
+The maximum amount of cpu time in seconds
+.TP
+.B \-u
+The maximum number of processes available to a single user
+.TP
+.B \-v
+The maximum amount of virtual memory available to the shell and, on
+some systems, to its children
+.TP
+.B \-x
+The maximum number of file locks
+.TP
+.B \-P
+The maximum number of pseudoterminals
+.TP
+.B \-R
+The maximum time a real-time process can run before blocking, in microseconds
+.TP
+.B \-T
+The maximum number of threads
+.PD
+.PP
+If
+.I limit
+is given, and the
+.B \-a
+option is not used,
+\fIlimit\fP is the new value of the specified resource.
+If no option is given, then
+.B \-f
+is assumed.  Values are in 1024-byte increments, except for
+.BR \-t ,
+which is in seconds;
+.BR \-R ,
+which is in microseconds;
+.BR \-p ,
+which is in units of 512-byte blocks;
+.BR \-P ,
+.BR \-T ,
+.BR \-b ,
+.BR \-k ,
+.BR \-n ,
+and
+.BR \-u ,
+which are unscaled values;
+and, when in posix mode,
+.B \-c
+and
+.BR \-f ,
+which are in 512-byte increments.
+The return status is 0 unless an invalid option or argument is supplied,
+or an error occurs while setting a new limit.
+.RE
+.TP
+\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
+The user file-creation mask is set to
+.IR mode .
+If
+.I mode
+begins with a digit, it
+is interpreted as an octal number; otherwise
+it is interpreted as a symbolic mode mask similar
+to that accepted by
+.IR chmod (1).
+If
+.I mode
+is omitted, the current value of the mask is printed.
+The
+.B \-S
+option causes the mask to be printed in symbolic form; the
+default output is an octal number.
+If the
+.B \-p
+option is supplied, and
+.I mode
+is omitted, the output is in a form that may be reused as input.
+The return status is 0 if the mode was successfully changed or if
+no \fImode\fP argument was supplied, and false otherwise.
+.TP
+\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
+Remove each \fIname\fP from the list of defined aliases.  If
+.B \-a
+is supplied, all alias definitions are removed.  The return
+value is true unless a supplied
+.I name
+is not a defined alias.
+.TP
+\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...]
+For each
+.IR name ,
+remove the corresponding variable or function.
+If the
+.B \-v
+option is given, each
+.I name
+refers to a shell variable, and that variable is removed.
+Read-only variables may not be unset.
+If
+.B \-f
+is specified, each
+.I name
+refers to a shell function, and the function definition
+is removed.
+If the
+.B \-n
+option is supplied, and \fIname\fP is a variable with the \fInameref\fP
+attribute, \fIname\fP will be unset rather than the variable it
+references.
+\fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
+If no options are supplied, each \fIname\fP refers to a variable; if
+there is no variable by that name, a function with that name, if any, is
+unset.
+Each unset variable or function is removed from the environment
+passed to subsequent commands.
+If any of
+.SM
+.BR BASH_ALIASES ,
+.SM
+.BR BASH_ARGV0 ,
+.SM
+.BR BASH_CMDS ,
+.SM
+.BR BASH_COMMAND ,
+.SM
+.BR BASH_SUBSHELL ,
+.SM
+.BR BASHPID ,
+.SM
+.BR COMP_WORDBREAKS ,
+.SM
+.BR DIRSTACK ,
+.SM
+.BR EPOCHREALTIME ,
+.SM
+.BR EPOCHSECONDS ,
+.SM
+.BR FUNCNAME ,
+.SM
+.BR GROUPS ,
+.SM
+.BR HISTCMD ,
+.SM
+.BR LINENO ,
+.SM
+.BR RANDOM ,
+.SM
+.BR SECONDS ,
+or
+.SM
+.B SRANDOM
+are unset, they lose their special properties, even if they are
+subsequently reset.  The exit status is true unless a
+.I name
+is readonly or may not be unset.
+.TP
+\fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP]
+Wait for each specified child process and return its termination status.
+Each
+.I id
+may be a process
+ID or a job specification; if a job spec is given, all processes
+in that job's pipeline are waited for.  If
+.I id
+is not given,
+\fBwait\fP waits for all running background jobs and
+the last-executed process substitution, if its process id is the same as
+\fB$!\fP,
+and the return status is zero.
+If the \fB\-n\fP option is supplied,
+\fBwait\fP waits for a single job
+from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job,
+to complete and returns its exit status.
+If none of the supplied arguments is a child of the shell, or if no arguments
+are supplied and the shell has no unwaited-for children, the exit status
+is 127.
+If the \fB\-p\fP option is supplied, the process or job identifier of the job
+for which the exit status is returned is assigned to the variable
+\fIvarname\fP named by the option argument.
+The variable will be unset initially, before any assignment.
+This is useful only when the \fB\-n\fP option is supplied.
+Supplying the \fB\-f\fP option, when job control is enabled,
+forces \fBwait\fP to wait for \fIid\fP to terminate before returning
+its status, instead of returning when it changes status.
+If
+.I id
+specifies a non-existent process or job, the return status is 127.
+If \fBwait\fP is interrupted by a signal, the return status will be greater
+than 128, as described under
+.B SIGNALS
+.ie \n(zZ=1 in \fIbash(1)\fP.
+.el above.
+Otherwise, the return status is the exit status of the last
+process or job waited for.
+.SH "SHELL COMPATIBILITY MODE"
+Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
+specified as a set of options to the shopt builtin (
+.BR compat31 ,
+.BR compat32 ,
+.BR compat40 ,
+.BR compat41 ,
+and so on).
+There is only one current
+compatibility level -- each option is mutually exclusive.
+The compatibility level is intended to allow users to select behavior
+from previous versions that is incompatible with newer versions
+while they migrate scripts to use current features and
+behavior. It's intended to be a temporary solution.
+.PP
+This section does not mention behavior that is standard for a particular
+version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp
+matching operator quotes special regexp characters in the word, which is
+default behavior in bash-3.2 and subsequent versions). 
+.PP
+If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
+compatibility levels up to and including the current compatibility level.
+The idea is that each compatibility level controls behavior that changed
+in that version of \fBbash\fP,
+but that behavior may have been present in earlier versions.
+For instance, the change to use locale-based comparisons with the \fB[[\fP
+command came in bash-4.1, and earlier versions used ASCII-based comparisons,
+so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
+That granularity may not be sufficient for
+all uses, and as a result users should employ compatibility levels carefully.
+Read the documentation for a particular feature to find out the
+current behavior.
+.PP
+Bash-4.3 introduced a new shell variable:
+.SM
+.BR BASH_COMPAT .
+The value assigned
+to this variable (a decimal version number like 4.2, or an integer
+corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
+compatibility level.
+.PP
+Starting with bash-4.4, Bash has begun deprecating older compatibility
+levels.
+Eventually, the options will be removed in favor of
+.SM
+.BR BASH_COMPAT .
+.PP
+Bash-5.0 is the final version for which there will be an individual shopt
+option for the previous version. Users should use
+.SM
+.B BASH_COMPAT
+on bash-5.0 and later versions.
+.PP
+The following table describes the behavior changes controlled by each
+compatibility level setting.
+The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
+compatibility level
+to \fINN\fP using one of the following mechanisms.
+For versions prior to bash-5.0, the compatibility level may be set using
+the corresponding \fBcompat\fP\fINN\fP shopt option.
+For bash-4.3 and later versions, the
+.SM
+.B BASH_COMPAT
+variable is preferred,
+and it is required for bash-5.1 and later versions.
+.TP
+\fBcompat31\fP
+.PD 0
+.RS
+.IP \(bu
+quoting the rhs of the \fB[[\fP command's regexp matching operator (=~)
+has no special effect
+.RE
+.PD
+.TP
+\fBcompat32\fP
+.PD 0
+.RS
+.IP \(bu
+interrupting a command list such as "a ; b ; c" causes the execution
+of the next command in the list (in bash-4.0 and later versions,
+the shell acts as if it received the interrupt, so
+interrupting one command in a list aborts the execution of the
+entire list)
+.RE
+.PD
+.TP
+\fBcompat40\fP
+.PD 0
+.RS
+.IP \(bu
+the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
+consider the current locale when comparing strings; they use ASCII
+ordering.
+Bash versions prior to bash-4.1 use ASCII collation and
+.IR strcmp (3);
+bash-4.1 and later use the current locale's collation sequence and
+.IR strcoll (3).
+.RE
+.PD
+.TP
+\fBcompat41\fP
+.PD 0
+.RS
+.IP \(bu
+in \fIposix\fP mode, \fBtime\fP may be followed by options and still be
+recognized as a reserved word (this is POSIX interpretation 267)
+.IP \(bu
+in \fIposix\fP mode, the parser requires that an even number of single
+quotes occur in the \fIword\fP portion of a double-quoted
+parameter expansion and treats them specially, so that characters within
+the single quotes are considered quoted
+(this is POSIX interpretation 221)
+.RE
+.PD
+.TP
+\fBcompat42\fP
+.PD 0
+.RS
+.IP \(bu
+the replacement string in double-quoted pattern substitution does not
+undergo quote removal, as it does in versions after bash-4.2
+.IP \(bu
+in posix mode, single quotes are considered special when expanding
+the \fIword\fP portion of a double-quoted parameter expansion
+and can be used to quote a closing brace or other special character
+(this is part of POSIX interpretation 221);
+in later versions, single quotes
+are not special within double-quoted word expansions
+.RE
+.PD
+.TP
+\fBcompat43\fP
+.PD 0
+.RS
+.IP \(bu
+the shell does not print a warning message if an attempt is made to
+use a quoted compound assignment as an argument to declare
+(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is
+deprecated
+.IP \(bu
+word expansion errors are considered non-fatal errors that cause the
+current command to fail, even in posix mode
+(the default behavior is to make them fatal errors that cause the shell
+to exit)
+.IP \(bu
+when executing a shell function, the loop state (while/until/etc.)
+is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
+or continue loops in the calling context. Bash-4.4 and later reset
+the loop state to prevent this
+.RE
+.PD
+.TP
+\fBcompat44\fP
+.PD 0
+.RS
+.IP \(bu
+the shell sets up the values used by
+.SM
+.B BASH_ARGV
+and
+.SM
+.B BASH_ARGC
+so they can expand to the shell's positional parameters even if extended
+debugging mode is not enabled
+.IP \(bu
+a subshell inherits loops from its parent context, so \fBbreak\fP
+or \fBcontinue\fP will cause the subshell to exit.
+Bash-5.0 and later reset the loop state to prevent the exit
+.IP \(bu
+variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
+that set attributes continue to affect variables with the same
+name in the calling environment even if the shell is not in posix
+mode
+.RE
+.PD
+.TP
+\fBcompat50\fP
+.PD 0
+.RS
+.IP \(bu
+Bash-5.1 changed the way
+.SM
+.B $RANDOM
+is generated to introduce slightly
+more randomness. If the shell compatibility level is set to 50 or
+lower, it reverts to the method from bash-5.0 and previous versions,
+so seeding the random number generator by assigning a value to
+.SM
+.B RANDOM
+will produce the same sequence as in bash-5.0
+.IP \(bu
+If the command hash table is empty, bash versions prior to bash-5.1
+printed an informational message to that effect, even when producing
+output that can be reused as input. Bash-5.1 suppresses that message
+when the \fB\-l\fP option is supplied.
+.RE
+.PD
+.TP
+\fBcompat51\fP
+.PD 0
+.RS
+.IP \(bu
+The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
+and \fB*\fP differently depending on whether the array is indexed or
+associative, and differently than in previous versions.
+.RE
+.PD
+.\" bash_builtins
+.zY
+.lf 23 ./builtins.1
+.SH SEE ALSO
+bash(1), sh(1)
diff --git a/upstream/mageia-cauldron/man1/busctl.1 b/upstream/mageia-cauldron/man1/busctl.1
new file mode 100644
index 00000000..ed53281e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/busctl.1
@@ -0,0 +1,583 @@
+'\" t
+.TH "BUSCTL" "1" "" "systemd 255" "busctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+busctl \- Introspect the bus
+.SH "SYNOPSIS"
+.HP \w'\fBbusctl\fR\ 'u
+\fBbusctl\fR [OPTIONS...] [COMMAND] [\fINAME\fR...]
+.SH "DESCRIPTION"
+.PP
+\fBbusctl\fR
+may be used to introspect and monitor the D\-Bus bus\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR
+.RS 4
+Show all peers on the bus, by their service names\&. By default, shows both unique and well\-known names, but this may be changed with the
+\fB\-\-unique\fR
+and
+\fB\-\-acquired\fR
+switches\&. This is the default operation if no command is specified\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBstatus\fR [\fISERVICE\fR]
+.RS 4
+Show process information and credentials of a bus service (if one is specified by its unique or well\-known name), a process (if one is specified by its numeric PID), or the owner of the bus (if no parameter is specified)\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBmonitor\fR [\fISERVICE\fR...]
+.RS 4
+Dump messages being exchanged\&. If
+\fISERVICE\fR
+is specified, show messages to or from this peer, identified by its well\-known or unique name\&. Otherwise, show all messages on the bus\&. Use
+Ctrl+C
+to terminate the dump\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBcapture\fR [\fISERVICE\fR...]
+.RS 4
+Similar to
+\fBmonitor\fR
+but writes the output in pcapng format (for details, see
+\m[blue]\fBPCAP Next Generation (pcapng) Capture File Format\fR\m[]\&\s-2\u[1]\d\s+2)\&. Make sure to redirect standard output to a file or pipe\&. Tools like
+\fBwireshark\fR(1)
+may be used to dissect and view the resulting files\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBtree\fR [\fISERVICE\fR...]
+.RS 4
+Shows an object tree of one or more services\&. If
+\fISERVICE\fR
+is specified, show object tree of the specified services only\&. Otherwise, show all object trees of all services on the bus that acquired at least one well\-known name\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBintrospect\fR \fISERVICE\fR \fIOBJECT\fR [\fIINTERFACE\fR]
+.RS 4
+Show interfaces, methods, properties and signals of the specified object (identified by its path) on the specified service\&. If the interface argument is passed, the output is limited to members of the specified interface\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBcall\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIMETHOD\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]]
+.RS 4
+Invoke a method and show the response\&. Takes a service name, object path, interface name and method name\&. If parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To suppress output of the returned data, use the
+\fB\-\-quiet\fR
+option\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBemit\fR \fIOBJECT\fR \fIINTERFACE\fR \fISIGNAL\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]]
+.RS 4
+Emit a signal\&. Takes an object path, interface name and method name\&. If parameters shall be passed, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To specify the destination of the signal, use the
+\fB\-\-destination=\fR
+option\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fBget\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR...
+.RS 4
+Retrieve the current value of one or more object properties\&. Takes a service name, object path, interface name and property name\&. Multiple properties may be specified at once, in which case their values will be shown one after the other, separated by newlines\&. The output is, by default, in terse format\&. Use
+\fB\-\-verbose\fR
+for a more elaborate output format\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBset\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR \fISIGNATURE\fR \fIARGUMENT\fR...
+.RS 4
+Set the current value of an object property\&. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBhelp\fR
+.RS 4
+Show command syntax help\&.
+.sp
+Added in version 209\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-address=\fR\fB\fIADDRESS\fR\fR
+.RS 4
+Connect to the bus specified by
+\fIADDRESS\fR
+instead of using suitable defaults for either the system or user bus (see
+\fB\-\-system\fR
+and
+\fB\-\-user\fR
+options)\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-show\-machine\fR
+.RS 4
+When showing the list of peers, show a column containing the names of containers they belong to\&. See
+\fBsystemd-machined.service\fR(8)\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-unique\fR
+.RS 4
+When showing the list of peers, show only "unique" names (of the form
+":\fInumber\fR\&.\fInumber\fR")\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-acquired\fR
+.RS 4
+The opposite of
+\fB\-\-unique\fR
+\(em only "well\-known" names will be shown\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-activatable\fR
+.RS 4
+When showing the list of peers, show only peers which have actually not been activated yet, but may be started automatically if accessed\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-match=\fR\fB\fIMATCH\fR\fR
+.RS 4
+When showing messages being exchanged, show only the subset matching
+\fIMATCH\fR\&. See
+\fBsd_bus_add_match\fR(3)\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-size=\fR
+.RS 4
+When used with the
+\fBcapture\fR
+command, specifies the maximum bus message size to capture ("snaplen")\&. Defaults to 4096 bytes\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-list\fR
+.RS 4
+When used with the
+\fBtree\fR
+command, shows a flat list of object paths instead of a tree\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+When used with the
+\fBcall\fR
+command, suppresses display of the response message payload\&. Note that even if this option is specified, errors returned will still be printed and the tool will indicate success or failure with the process exit code\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-verbose\fR
+.RS 4
+When used with the
+\fBcall\fR
+or
+\fBget\-property\fR
+command, shows output in a more verbose format\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-xml\-interface\fR
+.RS 4
+When used with the
+\fBintrospect\fR
+call, dump the XML description received from the D\-Bus
+\fBorg\&.freedesktop\&.DBus\&.Introspectable\&.Introspect\fR
+call instead of the normal output\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+When used with the
+\fBcall\fR
+or
+\fBget\-property\fR
+command, shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks) or
+"pretty"
+(for a pretty version of the same, with indentation and line breaks)\&. Note that transformation from D\-Bus marshalling to JSON is done in a loss\-less way, which means type information is embedded into the JSON object tree\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-j\fR
+.RS 4
+Equivalent to
+\fB\-\-json=pretty\fR
+when invoked interactively from a terminal\&. Otherwise equivalent to
+\fB\-\-json=short\fR, in particular when the output is piped to some other program\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-\-expect\-reply=\fR\fIBOOL\fR
+.RS 4
+When used with the
+\fBcall\fR
+command, specifies whether
+\fBbusctl\fR
+shall wait for completion of the method call, output the returned method response data, and return success or failure via the process exit code\&. If this is set to
+"no", the method call will be issued but no response is expected, the tool terminates immediately, and thus no response can be shown, and no success or failure is returned via the exit code\&. To only suppress output of the reply message payload, use
+\fB\-\-quiet\fR
+above\&. Defaults to
+"yes"\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-auto\-start=\fR\fIBOOL\fR
+.RS 4
+When used with the
+\fBcall\fR
+or
+\fBemit\fR
+command, specifies whether the method call should implicitly activate the called service, should it not be running yet but is configured to be auto\-started\&. Defaults to
+"yes"\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-allow\-interactive\-authorization=\fR\fIBOOL\fR
+.RS 4
+When used with the
+\fBcall\fR
+command, specifies whether the services may enforce interactive authorization while executing the operation, if the security policy is configured for this\&. Defaults to
+"yes"\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-timeout=\fR\fISECS\fR
+.RS 4
+When used with the
+\fBcall\fR
+command, specifies the maximum time to wait for method call completion\&. If no time unit is specified, assumes seconds\&. The usual other units are understood, too (ms, us, s, min, h, d, w, month, y)\&. Note that this timeout does not apply if
+\fB\-\-expect\-reply=no\fR
+is used, as the tool does not wait for any reply message then\&. When not specified or when set to 0, the default of
+"25s"
+is assumed\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-augment\-creds=\fR\fIBOOL\fR
+.RS 4
+Controls whether credential data reported by
+\fBlist\fR
+or
+\fBstatus\fR
+shall be augmented with data from
+/proc/\&. When this is turned on, the data shown is possibly inconsistent, as the data read from
+/proc/
+might be more recent than the rest of the credential information\&. Defaults to
+"yes"\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-watch\-bind=\fR\fIBOOL\fR
+.RS 4
+Controls whether to wait for the specified
+\fBAF_UNIX\fR
+bus socket to appear in the file system before connecting to it\&. Defaults to off\&. When enabled, the tool will watch the file system until the socket is created and then connect to it\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-\-destination=\fR\fISERVICE\fR
+.RS 4
+Takes a service name\&. When used with the
+\fBemit\fR
+command, a signal is emitted to the specified service\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-user\fR
+.RS 4
+Talk to the service manager of the calling user, rather than the service manager of the system\&.
+.RE
+.PP
+\fB\-\-system\fR
+.RS 4
+Talk to the service manager of the system\&. This is the implied default\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize the output in
+\fBlist\fR
+command\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "PARAMETER FORMATTING"
+.PP
+The
+\fBcall\fR
+and
+\fBset\-property\fR
+commands take a signature string followed by a list of parameters formatted as string (for details on D\-Bus signature strings, see the
+\m[blue]\fBType system chapter of the D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2)\&. For simple types, each parameter following the signature should simply be the parameter\*(Aqs value formatted as string\&. Positive boolean values may be formatted as
+"true",
+"yes",
+"on", or
+"1"; negative boolean values may be specified as
+"false",
+"no",
+"off", or
+"0"\&. For arrays, a numeric argument for the number of entries followed by the entries shall be specified\&. For variants, the signature of the contents shall be specified, followed by the contents\&. For dictionaries and structs, the contents of them shall be directly specified\&.
+.PP
+For example,
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+s jawoll
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+is the formatting of a single string
+"jawoll"\&.
+.PP
+.if n \{\
+.RS 4
+.\}
+.nf
+as 3 hello world foobar
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+is the formatting of a string array with three entries,
+"hello",
+"world"
+and
+"foobar"\&.
+.PP
+.if n \{\
+.RS 4
+.\}
+.nf
+a{sv} 3 One s Eins Two u 2 Yes b true
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+is the formatting of a dictionary array that maps strings to variants, consisting of three entries\&. The string
+"One"
+is assigned the string
+"Eins"\&. The string
+"Two"
+is assigned the 32\-bit unsigned integer 2\&. The string
+"Yes"
+is assigned a positive boolean\&.
+.PP
+Note that the
+\fBcall\fR,
+\fBget\-property\fR,
+\fBintrospect\fR
+commands will also generate output in this format for the returned data\&. Since this format is sometimes too terse to be easily understood, the
+\fBcall\fR
+and
+\fBget\-property\fR
+commands may generate a more verbose, multi\-line output when passed the
+\fB\-\-verbose\fR
+option\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Write and Read a Property\fR
+.PP
+The following two commands first write a property and then read it back\&. The property is found on the
+"/org/freedesktop/systemd1"
+object of the
+"org\&.freedesktop\&.systemd1"
+service\&. The name of the property is
+"LogLevel"
+on the
+"org\&.freedesktop\&.systemd1\&.Manager"
+interface\&. The property contains a single string:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# busctl set\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel s debug
+# busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel
+s "debug"
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Terse and Verbose Output\fR
+.PP
+The following two commands read a property that contains an array of strings, and first show it in terse format, followed by verbose format:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment
+as 2 "LANG=en_US\&.UTF\-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
+$ busctl get\-property \-\-verbose org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment
+ARRAY "s" {
+        STRING "LANG=en_US\&.UTF\-8";
+        STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
+};
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&3.\ \&Invoking a Method\fR
+.PP
+The following command invokes the
+"StartUnit"
+method on the
+"org\&.freedesktop\&.systemd1\&.Manager"
+interface of the
+"/org/freedesktop/systemd1"
+object of the
+"org\&.freedesktop\&.systemd1"
+service, and passes it two strings
+"cups\&.service"
+and
+"replace"\&. As a result of the method call, a single object path parameter is received and shown:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# busctl call org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager StartUnit ss "cups\&.service" "replace"
+o "/org/freedesktop/systemd1/job/42684"
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBdbus-daemon\fR(1),
+\m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[3]\d\s+2,
+\fBsd-bus\fR(3),
+\fBvarlinkctl\fR(1),
+\fBsystemd\fR(1),
+\fBmachinectl\fR(1),
+\fBwireshark\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+PCAP Next Generation (pcapng) Capture File Format
+.RS 4
+\%https://github.com/pcapng/pcapng/
+.RE
+.IP " 2." 4
+Type system chapter of the D-Bus specification
+.RS 4
+\%https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
+.RE
+.IP " 3." 4
+D-Bus
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/dbus
+.RE
diff --git a/upstream/mageia-cauldron/man1/bzdiff.1 b/upstream/mageia-cauldron/man1/bzdiff.1
new file mode 100644
index 00000000..adb7a8e7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bzdiff.1
@@ -0,0 +1,47 @@
+\"Shamelessly copied from zmore.1 by Philippe Troin <phil@fifi.org>
+\"for Debian GNU/Linux
+.TH BZDIFF 1
+.SH NAME
+bzcmp, bzdiff \- compare bzip2 compressed files
+.SH SYNOPSIS
+.B bzcmp
+[ cmp_options ] file1
+[ file2 ]
+.br
+.B bzdiff
+[ diff_options ] file1
+[ file2 ]
+.SH DESCRIPTION
+.I  Bzcmp
+and 
+.I bzdiff
+are used to invoke the
+.I cmp
+or the
+.I diff
+program on bzip2 compressed files.  All options specified are passed
+directly to
+.I cmp
+or
+.IR diff "."
+If only 1 file is specified, then the files compared are
+.I file1
+and an uncompressed
+.IR file1 ".bz2."
+If two files are specified, then they are uncompressed if necessary and fed to
+.I cmp
+or
+.IR diff "."
+The exit status from 
+.I cmp
+or
+.I diff
+is preserved.
+.SH "SEE ALSO"
+cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)
+.SH BUGS
+Messages from the
+.I cmp
+or
+.I diff
+programs refer to temporary filenames instead of those specified.
diff --git a/upstream/mageia-cauldron/man1/bzgrep.1 b/upstream/mageia-cauldron/man1/bzgrep.1
new file mode 100644
index 00000000..c99e3be3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bzgrep.1
@@ -0,0 +1,56 @@
+\"Shamelessly copied from zmore.1 by Philippe Troin <phil@fifi.org>
+\"for Debian GNU/Linux
+.TH BZGREP 1
+.SH NAME
+bzgrep, bzfgrep, bzegrep \- search possibly bzip2 compressed files for a regular expression
+.SH SYNOPSIS
+.B bzgrep
+[ grep options ]
+.BI  [\ -e\ ] " pattern"
+.IR filename ".\|.\|."
+.br
+.B bzegrep
+[ grep -E options ]
+.BI  [\ -e\ ] " pattern"
+.IR filename ".\|.\|."
+.br
+.B bzfgrep
+[ grep -F options ]
+.BI  [\ -e\ ] " pattern"
+.IR filename ".\|.\|."
+.SH DESCRIPTION
+.IR  Bzgrep
+is used to invoke the
+.I grep
+on bzip2-compressed files. All options specified are passed directly to
+.I grep.
+If no file is specified, then the standard input is decompressed
+if necessary and fed to grep.
+Otherwise the given files are uncompressed if necessary and fed to
+.I grep.
+.PP
+If
+.I bzgrep
+is invoked as
+.I bzegrep
+or
+.I bzfgrep
+then
+.I grep -E
+or
+.I grep -F
+is used instead of
+.I grep.
+If the GREP environment variable is set,
+.I bzgrep
+uses it as the
+.I grep
+program to be invoked. For example:
+
+    for sh:  GREP="grep -F" bzgrep string files
+    for csh: (setenv GREP "grep -F"; bzgrep string files)
+.SH AUTHOR
+Charles Levert (charles@comm.polymtl.ca). Adapted to bzip2 by Philippe
+Troin <phil@fifi.org> for Debian GNU/Linux.
+.SH "SEE ALSO"
+grep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)
diff --git a/upstream/mageia-cauldron/man1/bzip2.1 b/upstream/mageia-cauldron/man1/bzip2.1
new file mode 100644
index 00000000..0cbcdab0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bzip2.1
@@ -0,0 +1,454 @@
+.PU
+.TH bzip2 1
+.SH NAME
+bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8
+.br
+bzcat \- decompresses files to stdout
+.br
+bzip2recover \- recovers data from damaged bzip2 files
+
+.SH SYNOPSIS
+.ll +8
+.B bzip2
+.RB [ " \-cdfkqstvzVL123456789 " ]
+[
+.I "filenames \&..."
+]
+.ll -8
+.br
+.B bunzip2
+.RB [ " \-fkvsVL " ]
+[ 
+.I "filenames \&..."
+]
+.br
+.B bzcat
+.RB [ " \-s " ]
+[ 
+.I "filenames \&..."
+]
+.br
+.B bzip2recover
+.I "filename"
+
+.SH DESCRIPTION
+.I bzip2
+compresses files using the Burrows-Wheeler block sorting
+text compression algorithm, and Huffman coding.  Compression is
+generally considerably better than that achieved by more conventional
+LZ77/LZ78-based compressors, and approaches the performance of the PPM
+family of statistical compressors.
+
+The command-line options are deliberately very similar to 
+those of 
+.I GNU gzip, 
+but they are not identical.
+
+.I bzip2
+expects a list of file names to accompany the
+command-line flags.  Each file is replaced by a compressed version of
+itself, with the name "original_name.bz2".  
+Each compressed file
+has the same modification date, permissions, and, when possible,
+ownership as the corresponding original, so that these properties can
+be correctly restored at decompression time.  File name handling is
+naive in the sense that there is no mechanism for preserving original
+file names, permissions, ownerships or dates in filesystems which lack
+these concepts, or have serious file name length restrictions, such as
+MS-DOS.
+
+.I bzip2
+and
+.I bunzip2
+will by default not overwrite existing
+files.  If you want this to happen, specify the \-f flag.
+
+If no file names are specified,
+.I bzip2
+compresses from standard
+input to standard output.  In this case,
+.I bzip2
+will decline to
+write compressed output to a terminal, as this would be entirely
+incomprehensible and therefore pointless.
+
+.I bunzip2
+(or
+.I bzip2 \-d) 
+decompresses all
+specified files.  Files which were not created by 
+.I bzip2
+will be detected and ignored, and a warning issued.  
+.I bzip2
+attempts to guess the filename for the decompressed file 
+from that of the compressed file as follows:
+
+       filename.bz2    becomes   filename
+       filename.bz     becomes   filename
+       filename.tbz2   becomes   filename.tar
+       filename.tbz    becomes   filename.tar
+       anyothername    becomes   anyothername.out
+
+If the file does not end in one of the recognised endings, 
+.I .bz2, 
+.I .bz, 
+.I .tbz2
+or
+.I .tbz, 
+.I bzip2 
+complains that it cannot
+guess the name of the original file, and uses the original name
+with
+.I .out
+appended.
+
+As with compression, supplying no
+filenames causes decompression from 
+standard input to standard output.
+
+.I bunzip2 
+will correctly decompress a file which is the
+concatenation of two or more compressed files.  The result is the
+concatenation of the corresponding uncompressed files.  Integrity
+testing (\-t) 
+of concatenated 
+compressed files is also supported.
+
+You can also compress or decompress files to the standard output by
+giving the \-c flag.  Multiple files may be compressed and
+decompressed like this.  The resulting outputs are fed sequentially to
+stdout.  Compression of multiple files 
+in this manner generates a stream
+containing multiple compressed file representations.  Such a stream
+can be decompressed correctly only by
+.I bzip2 
+version 0.9.0 or
+later.  Earlier versions of
+.I bzip2
+will stop after decompressing
+the first file in the stream.
+
+.I bzcat
+(or
+.I bzip2 -dc) 
+decompresses all specified files to
+the standard output.
+
+.I bzip2
+will read arguments from the environment variables
+.I BZIP2
+and
+.I BZIP,
+in that order, and will process them
+before any arguments read from the command line.  This gives a 
+convenient way to supply default arguments.
+
+Compression is always performed, even if the compressed 
+file is slightly
+larger than the original.  Files of less than about one hundred bytes
+tend to get larger, since the compression mechanism has a constant
+overhead in the region of 50 bytes.  Random data (including the output
+of most file compressors) is coded at about 8.05 bits per byte, giving
+an expansion of around 0.5%.
+
+As a self-check for your protection, 
+.I 
+bzip2
+uses 32-bit CRCs to
+make sure that the decompressed version of a file is identical to the
+original.  This guards against corruption of the compressed data, and
+against undetected bugs in
+.I bzip2
+(hopefully very unlikely).  The
+chances of data corruption going undetected is microscopic, about one
+chance in four billion for each file processed.  Be aware, though, that
+the check occurs upon decompression, so it can only tell you that
+something is wrong.  It can't help you 
+recover the original uncompressed
+data.  You can use 
+.I bzip2recover
+to try to recover data from
+damaged files.
+
+Return values: 0 for a normal exit, 1 for environmental problems (file
+not found, invalid flags, I/O errors, &c), 2 to indicate a corrupt
+compressed file, 3 for an internal consistency error (eg, bug) which
+caused
+.I bzip2
+to panic.
+
+.SH OPTIONS
+.TP
+.B \-c --stdout
+Compress or decompress to standard output.
+.TP
+.B \-d --decompress
+Force decompression.  
+.I bzip2, 
+.I bunzip2 
+and
+.I bzcat 
+are
+really the same program, and the decision about what actions to take is
+done on the basis of which name is used.  This flag overrides that
+mechanism, and forces 
+.I bzip2
+to decompress.
+.TP
+.B \-z --compress
+The complement to \-d: forces compression, regardless of the
+invocation name.
+.TP
+.B \-t --test
+Check integrity of the specified file(s), but don't decompress them.
+This really performs a trial decompression and throws away the result.
+.TP
+.B \-f --force
+Force overwrite of output files.  Normally,
+.I bzip2 
+will not overwrite
+existing output files.  Also forces 
+.I bzip2 
+to break hard links
+to files, which it otherwise wouldn't do.
+
+bzip2 normally declines to decompress files which don't have the
+correct magic header bytes.  If forced (-f), however, it will pass
+such files through unmodified.  This is how GNU gzip behaves.
+.TP
+.B \-k --keep
+Keep (don't delete) input files during compression
+or decompression.
+.TP
+.B \-s --small
+Reduce memory usage, for compression, decompression and testing.  Files
+are decompressed and tested using a modified algorithm which only
+requires 2.5 bytes per block byte.  This means any file can be
+decompressed in 2300k of memory, albeit at about half the normal speed.
+
+During compression, \-s selects a block size of 200k, which limits
+memory use to around the same figure, at the expense of your compression
+ratio.  In short, if your machine is low on memory (8 megabytes or
+less), use \-s for everything.  See MEMORY MANAGEMENT below.
+.TP
+.B \-q --quiet
+Suppress non-essential warning messages.  Messages pertaining to
+I/O errors and other critical events will not be suppressed.
+.TP
+.B \-v --verbose
+Verbose mode -- show the compression ratio for each file processed.
+Further \-v's increase the verbosity level, spewing out lots of
+information which is primarily of interest for diagnostic purposes.
+.TP
+.B \-L --license -V --version
+Display the software version, license terms and conditions.
+.TP
+.B \-1 (or \-\-fast) to \-9 (or \-\-best)
+Set the block size to 100 k, 200 k ..  900 k when compressing.  Has no
+effect when decompressing.  See MEMORY MANAGEMENT below.
+The \-\-fast and \-\-best aliases are primarily for GNU gzip 
+compatibility.  In particular, \-\-fast doesn't make things
+significantly faster.  
+And \-\-best merely selects the default behaviour.
+.TP
+.B \--
+Treats all subsequent arguments as file names, even if they start
+with a dash.  This is so you can handle files with names beginning
+with a dash, for example: bzip2 \-- \-myfilename.
+.TP
+.B \--repetitive-fast --repetitive-best
+These flags are redundant in versions 0.9.5 and above.  They provided
+some coarse control over the behaviour of the sorting algorithm in
+earlier versions, which was sometimes useful.  0.9.5 and above have an
+improved algorithm which renders these flags irrelevant.
+
+.SH MEMORY MANAGEMENT
+.I bzip2 
+compresses large files in blocks.  The block size affects
+both the compression ratio achieved, and the amount of memory needed for
+compression and decompression.  The flags \-1 through \-9
+specify the block size to be 100,000 bytes through 900,000 bytes (the
+default) respectively.  At decompression time, the block size used for
+compression is read from the header of the compressed file, and
+.I bunzip2
+then allocates itself just enough memory to decompress
+the file.  Since block sizes are stored in compressed files, it follows
+that the flags \-1 to \-9 are irrelevant to and so ignored
+during decompression.
+
+Compression and decompression requirements, 
+in bytes, can be estimated as:
+
+       Compression:   400k + ( 8 x block size )
+
+       Decompression: 100k + ( 4 x block size ), or
+                      100k + ( 2.5 x block size )
+
+Larger block sizes give rapidly diminishing marginal returns.  Most of
+the compression comes from the first two or three hundred k of block
+size, a fact worth bearing in mind when using
+.I bzip2
+on small machines.
+It is also important to appreciate that the decompression memory
+requirement is set at compression time by the choice of block size.
+
+For files compressed with the default 900k block size,
+.I bunzip2
+will require about 3700 kbytes to decompress.  To support decompression
+of any file on a 4 megabyte machine, 
+.I bunzip2
+has an option to
+decompress using approximately half this amount of memory, about 2300
+kbytes.  Decompression speed is also halved, so you should use this
+option only where necessary.  The relevant flag is -s.
+
+In general, try and use the largest block size memory constraints allow,
+since that maximises the compression achieved.  Compression and
+decompression speed are virtually unaffected by block size.
+
+Another significant point applies to files which fit in a single block
+-- that means most files you'd encounter using a large block size.  The
+amount of real memory touched is proportional to the size of the file,
+since the file is smaller than a block.  For example, compressing a file
+20,000 bytes long with the flag -9 will cause the compressor to
+allocate around 7600k of memory, but only touch 400k + 20000 * 8 = 560
+kbytes of it.  Similarly, the decompressor will allocate 3700k but only
+touch 100k + 20000 * 4 = 180 kbytes.
+
+Here is a table which summarises the maximum memory usage for different
+block sizes.  Also recorded is the total compressed size for 14 files of
+the Calgary Text Compression Corpus totalling 3,141,622 bytes.  This
+column gives some feel for how compression varies with block size.
+These figures tend to understate the advantage of larger block sizes for
+larger files, since the Corpus is dominated by smaller files.
+
+           Compress   Decompress   Decompress   Corpus
+    Flag     usage      usage       -s usage     Size
+
+     -1      1200k       500k         350k      914704
+     -2      2000k       900k         600k      877703
+     -3      2800k      1300k         850k      860338
+     -4      3600k      1700k        1100k      846899
+     -5      4400k      2100k        1350k      845160
+     -6      5200k      2500k        1600k      838626
+     -7      6100k      2900k        1850k      834096
+     -8      6800k      3300k        2100k      828642
+     -9      7600k      3700k        2350k      828642
+
+.SH RECOVERING DATA FROM DAMAGED FILES
+.I bzip2
+compresses files in blocks, usually 900kbytes long.  Each
+block is handled independently.  If a media or transmission error causes
+a multi-block .bz2
+file to become damaged, it may be possible to
+recover data from the undamaged blocks in the file.
+
+The compressed representation of each block is delimited by a 48-bit
+pattern, which makes it possible to find the block boundaries with
+reasonable certainty.  Each block also carries its own 32-bit CRC, so
+damaged blocks can be distinguished from undamaged ones.
+
+.I bzip2recover
+is a simple program whose purpose is to search for
+blocks in .bz2 files, and write each block out into its own .bz2 
+file.  You can then use
+.I bzip2 
+\-t
+to test the
+integrity of the resulting files, and decompress those which are
+undamaged.
+
+.I bzip2recover
+takes a single argument, the name of the damaged file, 
+and writes a number of files "rec00001file.bz2",
+"rec00002file.bz2", etc, containing the  extracted  blocks.
+The  output  filenames  are  designed  so  that the use of
+wildcards in subsequent processing -- for example,  
+"bzip2 -dc  rec*file.bz2 > recovered_data" -- processes the files in
+the correct order.
+
+.I bzip2recover
+should be of most use dealing with large .bz2
+files,  as  these will contain many blocks.  It is clearly
+futile to use it on damaged single-block  files,  since  a
+damaged  block  cannot  be recovered.  If you wish to minimise 
+any potential data loss through media  or  transmission errors, 
+you might consider compressing with a smaller
+block size.
+
+.SH PERFORMANCE NOTES
+The sorting phase of compression gathers together similar strings in the
+file.  Because of this, files containing very long runs of repeated
+symbols, like "aabaabaabaab ..."  (repeated several hundred times) may
+compress more slowly than normal.  Versions 0.9.5 and above fare much
+better than previous versions in this respect.  The ratio between
+worst-case and average-case compression time is in the region of 10:1.
+For previous versions, this figure was more like 100:1.  You can use the
+\-vvvv option to monitor progress in great detail, if you want.
+
+Decompression speed is unaffected by these phenomena.
+
+.I bzip2
+usually allocates several megabytes of memory to operate
+in, and then charges all over it in a fairly random fashion.  This means
+that performance, both for compressing and decompressing, is largely
+determined by the speed at which your machine can service cache misses.
+Because of this, small changes to the code to reduce the miss rate have
+been observed to give disproportionately large performance improvements.
+I imagine 
+.I bzip2
+will perform best on machines with very large caches.
+
+.SH CAVEATS
+I/O error messages are not as helpful as they could be.
+.I bzip2
+tries hard to detect I/O errors and exit cleanly, but the details of
+what the problem is sometimes seem rather misleading.
+
+This manual page pertains to version 1.0.8 of
+.I bzip2.  
+Compressed data created by this version is entirely forwards and
+backwards compatible with the previous public releases, versions
+0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 1.0.2 and above, but with the following
+exception: 0.9.0 and above can correctly decompress multiple
+concatenated compressed files.  0.1pl2 cannot do this; it will stop
+after decompressing just the first file in the stream.
+
+.I bzip2recover
+versions prior to 1.0.2 used 32-bit integers to represent
+bit positions in compressed files, so they could not handle compressed
+files more than 512 megabytes long.  Versions 1.0.2 and above use
+64-bit ints on some platforms which support them (GNU supported
+targets, and Windows).  To establish whether or not bzip2recover was
+built with such a limitation, run it without arguments.  In any event
+you can build yourself an unlimited version if you can recompile it
+with MaybeUInt64 set to be an unsigned 64-bit integer.
+
+
+
+.SH AUTHOR
+Julian Seward, jseward@acm.org.
+
+https://sourceware.org/bzip2/
+
+The ideas embodied in
+.I bzip2
+are due to (at least) the following
+people: Michael Burrows and David Wheeler (for the block sorting
+transformation), David Wheeler (again, for the Huffman coder), Peter
+Fenwick (for the structured coding model in the original
+.I bzip,
+and many refinements), and Alistair Moffat, Radford Neal and Ian Witten
+(for the arithmetic coder in the original
+.I bzip).  
+I am much
+indebted for their help, support and advice.  See the manual in the
+source distribution for pointers to sources of documentation.  Christian
+von Roques encouraged me to look for faster sorting algorithms, so as to
+speed up compression.  Bela Lubkin encouraged me to improve the
+worst-case compression performance.  
+Donna Robinson XMLised the documentation.
+The bz* scripts are derived from those of GNU gzip.
+Many people sent patches, helped
+with portability problems, lent machines, gave advice and were generally
+helpful.
diff --git a/upstream/mageia-cauldron/man1/bzme.1 b/upstream/mageia-cauldron/man1/bzme.1
new file mode 100644
index 00000000..cdf06eaf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bzme.1
@@ -0,0 +1,146 @@
+.PU
+.TH bzip2 1
+.SH NAME
+bzme \- recompress gziped, ziped, ... files into bzip2
+
+.SH SYNOPSIS
+.ll +8
+.B bzmz
+.RB [ " \-fh " ]
+[
+.I "filenames \&..."
+]
+
+.SH DESCRIPTION
+.I bzme
+recompresses files using the Burrows-Wheeler block sorting text compression
+algorithm, and Huffman coding.  Compression is generally considerably better
+than that achieved by more conventional LZ77/LZ78-based compressors,
+and approaches the performance of the PPM family of statistical compressors.
+
+.I bzme
+expects a list of file names to accompany the command-line flags.
+Each file is replaced by a recompressed version of itself, with the name
+as described in 
+.B "NEW NAMES"
+section.
+
+.I bzme
+won't overwrite by default existing files.  If you want this to happen, specify
+the \-f flag.
+
+.SH "NEW NAMES"
+.I bzip2
+attempts to guess the filename for the decompressed file 
+from that of the compressed file as follows:
+
+       filename.tgz    becomes   filename.tar.bz2
+       filename.tar.gz becomes   filename.tar.bz2
+       filename.zip    becomes   filename.tar.bz2
+       filename.z      becomes   filename.bz2
+       filename.Z      becomes   filename.bz2
+       filename.gz     becomes   filename.bz2
+
+If the file does not end in one of the recognised endings, \fI.tgz\fP, 
+
+or \fI.zip\fP,
+.I bzme 
+complains that it cannot guess if the name of the recompressed file (ie it
+doesn't detect the original name to be a file compressed in a known format)
+
+.SH OPTIONS
+.TP
+.B \-f
+Force overwrite of output files, even if
+.I -k
+is used.  Normally,
+.I bzip2 
+will not overwrite existing output files.
+
+.TP
+.B \-k
+Keep (don't delete) input files during compression
+or decompression.
+.".TP
+.".B \-q --quiet
+."Suppress non-essential warning messages.  Messages pertaining to
+."I/O errors and other critical events will not be suppressed.
+.".TP
+.".B \-v --verbose
+."Verbose mode -- dysplay space gain (default)
+.".TP
+.".B \-L --license -V --version
+."Display the software version, license terms and conditions.
+
+.SH SECURITY
+.I bzme
+will keep source file if there's an error while decompressing source file
+or recompressing new file (or
+.I -k
+option is used of course).
+
+.I bzme
+won't overwite the target file, even if
+.I -k
+option is used, if the source file doesn't exists.
+
+As a self-check for your protection, 
+.I bzip2
+uses 32-bit CRCs to make sure that the decompressed version of a file is
+identical to the original.
+.BR
+This offers a better protection against corruption
+of the compressed data than offered by gzip.
+
+.SH SPACE GAIN
+Compression is only performed if the compressed file is smaller than the
+original: the original file is only removed if the newly compressed file
+is smaller, else the new recompressed file is deleted.
+
+Text (aka non binary) files're quite nearly always better compressed
+by bzip2 rather than gzip.
+
+.SH MEMORY VS SPACE TRADEOFF
+There're two things :
+.TP
+.B Consumed CPU time
+The needed cpu time is reduced by decompressing only one time.
+Files to recompress were compressed through compress or gzip, used to be
+decompressed by gunzip -t in order to check that the original file was ok.
+This resulted in passing two times the data in the decompression process
+(one to check integrity, one to recompress).
+temporary space usage will be zero since bzme will use a pipe
+rather than a temporary file as it does in the early ages.
+Source error're detected through bash PIPESTATUS feature.
+.TP
+.B Occupied space
+While recompressing files, if they were compressed through compress or gzip,
+temporary space usage will be zero since bzme will use a pipe
+rather than a temporary file as it did in the early ages.
+Source error're detected through bash PIPESTATUS feature.
+Zip files're still fully decompressed on disk.
+
+As for the recompressed file and original file, only the smallest file
+is kept.
+
+.SH RETURN VALUES
+0 for a normal exit.
+1 will be returned if an unknown option is passed.
+
+.SH BUGS
+Bash getopt (which is used to analyse options) isn't gnu style aware, ie cmd
+opt1 file1 file2 opt2 will result in ignoring opt2 option.
+
+Solaris/SunOs du doesn't supports gnu option, and thus, bzme won't
+work on those OSes unless GNU fileutils got installed.
+.BR
+I had once a day patched bzme to use right options for solaris but i had
+lost my changes.
+.LP
+So solaris remains unsupported.
+
+.SH "SEE ALSO"
+bzip2(1), bunzip2(1)
+
+.SH AUTHOR
+Thierry Vignaud <tvignaud@mandrakesoft.com>, 1999-2002
diff --git a/upstream/mageia-cauldron/man1/bzmore.1 b/upstream/mageia-cauldron/man1/bzmore.1
new file mode 100644
index 00000000..b437d3b0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/bzmore.1
@@ -0,0 +1,152 @@
+.\"Shamelessly copied from zmore.1 by Philippe Troin <phil@fifi.org>
+.\"for Debian GNU/Linux
+.TH BZMORE 1
+.SH NAME
+bzmore, bzless \- file perusal filter for crt viewing of bzip2 compressed text
+.SH SYNOPSIS
+.B bzmore
+[ name ...  ]
+.br
+.B bzless
+[ name ...  ]
+.SH NOTE
+In the following description,
+.I bzless
+and
+.I less
+can be used interchangeably with
+.I bzmore
+and
+.I more.
+.SH DESCRIPTION
+.I  Bzmore
+is a filter which allows examination of compressed or plain text files
+one screenful at a time on a soft-copy terminal.
+.I bzmore
+works on files compressed with
+.I bzip2
+and also on uncompressed files.
+If a file does not exist,
+.I bzmore
+looks for a file of the same name with the addition of a .bz2 suffix.
+.PP
+.I Bzmore
+normally pauses after each screenful, printing --More--
+at the bottom of the screen.
+If the user then types a carriage return, one more line is displayed.
+If the user hits a space,
+another screenful is displayed.  Other possibilities are enumerated later.
+.PP
+.I Bzmore
+looks in the file
+.I /etc/termcap
+to determine terminal characteristics,
+and to determine the default window size.
+On a terminal capable of displaying 24 lines,
+the default window size is 22 lines.
+Other sequences which may be typed when
+.I bzmore
+pauses, and their effects, are as follows (\fIi\fP is an optional integer
+argument, defaulting to 1) :
+.PP
+.IP \fIi\|\fP<space>
+display
+.I i
+more lines, (or another screenful if no argument is given)
+.PP
+.IP ^D
+display 11 more lines (a ``scroll'').
+If
+.I i
+is given, then the scroll size is set to \fIi\|\fP.
+.PP
+.IP d
+same as ^D (control-D)
+.PP
+.IP \fIi\|\fPz
+same as typing a space except that \fIi\|\fP, if present, becomes the new
+window size.  Note that the window size reverts back to the default at the
+end of the current file.
+.PP
+.IP \fIi\|\fPs
+skip \fIi\|\fP lines and print a screenful of lines
+.PP
+.IP \fIi\|\fPf
+skip \fIi\fP screenfuls and print a screenful of lines
+.PP
+.IP "q or Q"
+quit reading the current file; go on to the next (if any)
+.PP
+.IP "e or q"
+When the prompt --More--(Next file: 
+.IR file )
+is printed, this command causes bzmore to exit.
+.PP
+.IP s
+When the prompt --More--(Next file: 
+.IR file )
+is printed, this command causes bzmore to skip the next file and continue.
+.PP 
+.IP =
+Display the current line number.
+.PP
+.IP \fIi\|\fP/expr
+search for the \fIi\|\fP-th occurrence of the regular expression \fIexpr.\fP
+If the pattern is not found,
+.I bzmore
+goes on to the next file (if any).
+Otherwise, a screenful is displayed, starting two lines before the place
+where the expression was found.
+The user's erase and kill characters may be used to edit the regular
+expression.
+Erasing back past the first column cancels the search command.
+.PP
+.IP \fIi\|\fPn
+search for the \fIi\|\fP-th occurrence of the last regular expression entered.
+.PP
+.IP !command
+invoke a shell with \fIcommand\|\fP. 
+The character `!' in "command" are replaced with the
+previous shell command.  The sequence "\\!" is replaced by "!".
+.PP
+.IP ":q or :Q"
+quit reading the current file; go on to the next (if any)
+(same as q or Q).
+.PP
+.IP .
+(dot) repeat the previous command.
+.PP
+The commands take effect immediately, i.e., it is not necessary to
+type a carriage return.
+Up to the time when the command character itself is given,
+the user may hit the line kill character to cancel the numerical
+argument being formed.
+In addition, the user may hit the erase character to redisplay the
+--More-- message.
+.PP
+At any time when output is being sent to the terminal, the user can
+hit the quit key (normally control\-\\).
+.I Bzmore
+will stop sending output, and will display the usual --More--
+prompt.
+The user may then enter one of the above commands in the normal manner.
+Unfortunately, some output is lost when this is done, due to the
+fact that any characters waiting in the terminal's output queue
+are flushed when the quit signal occurs.
+.PP
+The terminal is set to
+.I noecho
+mode by this program so that the output can be continuous.
+What you type will thus not show on your terminal, except for the / and !
+commands.
+.PP
+If the standard output is not a teletype, then
+.I bzmore
+acts just like
+.I bzcat,
+except that a header is printed before each file.
+.SH FILES
+.DT
+/etc/termcap		Terminal data base
+.SH "SEE ALSO"
+more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)
diff --git a/upstream/mageia-cauldron/man1/c++filt.1 b/upstream/mageia-cauldron/man1/c++filt.1
new file mode 100644
index 00000000..da380c54
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/c++filt.1
@@ -0,0 +1,376 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "C++FILT 1"
+.TH C++FILT 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+c++filt \- demangle C++ and Java symbols
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+c++filt [\fB\-_\fR|\fB\-\-strip\-underscore\fR]
+        [\fB\-n\fR|\fB\-\-no\-strip\-underscore\fR]
+        [\fB\-p\fR|\fB\-\-no\-params\fR]
+        [\fB\-t\fR|\fB\-\-types\fR]
+        [\fB\-i\fR|\fB\-\-no\-verbose\fR]
+        [\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR]
+        [\fB\-R\fR|\fB\-\-recurse\-limit\fR]
+        [\fB\-s\fR \fIformat\fR|\fB\-\-format=\fR\fIformat\fR]
+        [\fB\-\-help\fR]  [\fB\-\-version\fR]  [\fIsymbol\fR...]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \*(C+ and Java languages provide function overloading, which means
+that you can write many functions with the same name, providing that
+each function takes parameters of different types.  In order to be
+able to distinguish these similarly named functions \*(C+ and Java
+encode them into a low-level assembler name which uniquely identifies
+each different version.  This process is known as \fImangling\fR. The
+\&\fBc++filt\fR
+[1]
+program does the inverse mapping: it decodes (\fIdemangles\fR) low-level
+names into user-level names so that they can be read.
+.PP
+Every alphanumeric word (consisting of letters, digits, underscores,
+dollars, or periods) seen in the input is a potential mangled name.
+If the name decodes into a \*(C+ name, the \*(C+ name replaces the
+low-level name in the output, otherwise the original word is output.
+In this way you can pass an entire assembler source file, containing
+mangled names, through \fBc++filt\fR and see the same source file
+containing demangled names.
+.PP
+You can also use \fBc++filt\fR to decipher individual symbols by
+passing them on the command line:
+.PP
+.Vb 1
+\&        c++filt <symbol>
+.Ve
+.PP
+If no \fIsymbol\fR arguments are given, \fBc++filt\fR reads symbol
+names from the standard input instead.  All the results are printed on
+the standard output.  The difference between reading names from the
+command line versus reading names from the standard input is that
+command-line arguments are expected to be just mangled names and no
+checking is performed to separate them from surrounding text.  Thus
+for example:
+.PP
+.Vb 1
+\&        c++filt \-n _Z1fv
+.Ve
+.PP
+will work and demangle the name to \*(L"f()\*(R" whereas:
+.PP
+.Vb 1
+\&        c++filt \-n _Z1fv,
+.Ve
+.PP
+will not work.  (Note the extra comma at the end of the mangled
+name which makes it invalid).  This command however will work:
+.PP
+.Vb 1
+\&        echo _Z1fv, | c++filt \-n
+.Ve
+.PP
+and will display \*(L"f(),\*(R", i.e., the demangled name followed by a
+trailing comma.  This behaviour is because when the names are read
+from the standard input it is expected that they might be part of an
+assembler source file where there might be extra, extraneous
+characters trailing after a mangled name.  For example:
+.PP
+.Vb 1
+\&            .type   _Z1fv, @function
+.Ve
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-_\fR" 4
+.IX Item "-_"
+.PD 0
+.IP "\fB\-\-strip\-underscore\fR" 4
+.IX Item "--strip-underscore"
+.PD
+On some systems, both the C and \*(C+ compilers put an underscore in front
+of every name.  For example, the C name \f(CW\*(C`foo\*(C'\fR gets the low-level
+name \f(CW\*(C`_foo\*(C'\fR.  This option removes the initial underscore.  Whether
+\&\fBc++filt\fR removes the underscore by default is target dependent.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-\-no\-strip\-underscore\fR" 4
+.IX Item "--no-strip-underscore"
+.PD
+Do not remove the initial underscore.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-no\-params\fR" 4
+.IX Item "--no-params"
+.PD
+When demangling the name of a function, do not display the types of
+the function's parameters.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.IP "\fB\-\-types\fR" 4
+.IX Item "--types"
+.PD
+Attempt to demangle types as well as function names.  This is disabled
+by default since mangled types are normally only used internally in
+the compiler, and they can be confused with non-mangled names.  For example,
+a function called \*(L"a\*(R" treated as a mangled type name would be
+demangled to \*(L"signed char\*(R".
+.IP "\fB\-i\fR" 4
+.IX Item "-i"
+.PD 0
+.IP "\fB\-\-no\-verbose\fR" 4
+.IX Item "--no-verbose"
+.PD
+Do not include implementation details (if any) in the demangled
+output.
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-R\fR" 4
+.IX Item "-R"
+.IP "\fB\-\-recurse\-limit\fR" 4
+.IX Item "--recurse-limit"
+.IP "\fB\-\-no\-recurse\-limit\fR" 4
+.IX Item "--no-recurse-limit"
+.IP "\fB\-\-recursion\-limit\fR" 4
+.IX Item "--recursion-limit"
+.IP "\fB\-\-no\-recursion\-limit\fR" 4
+.IX Item "--no-recursion-limit"
+.PD
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings.  Since the name mangling formats allow for
+an infinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault.  The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+.Sp
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names.  Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+.Sp
+The \fB\-r\fR option is a synonym for the
+\&\fB\-\-no\-recurse\-limit\fR option.  The \fB\-R\fR option is a
+synonym for the \fB\-\-recurse\-limit\fR option.
+.IP "\fB\-s\fR \fIformat\fR" 4
+.IX Item "-s format"
+.PD 0
+.IP "\fB\-\-format=\fR\fIformat\fR" 4
+.IX Item "--format=format"
+.PD
+\&\fBc++filt\fR can decode various methods of mangling, used by
+different compilers.  The argument to this option selects which
+method it uses:
+.RS 4
+.ie n .IP """auto""" 4
+.el .IP "\f(CWauto\fR" 4
+.IX Item "auto"
+Automatic selection based on executable (the default method)
+.ie n .IP """gnu""" 4
+.el .IP "\f(CWgnu\fR" 4
+.IX Item "gnu"
+the one used by the \s-1GNU \*(C+\s0 compiler (g++)
+.ie n .IP """lucid""" 4
+.el .IP "\f(CWlucid\fR" 4
+.IX Item "lucid"
+the one used by the Lucid compiler (lcc)
+.ie n .IP """arm""" 4
+.el .IP "\f(CWarm\fR" 4
+.IX Item "arm"
+the one specified by the \*(C+ Annotated Reference Manual
+.ie n .IP """hp""" 4
+.el .IP "\f(CWhp\fR" 4
+.IX Item "hp"
+the one used by the \s-1HP\s0 compiler (aCC)
+.ie n .IP """edg""" 4
+.el .IP "\f(CWedg\fR" 4
+.IX Item "edg"
+the one used by the \s-1EDG\s0 compiler
+.ie n .IP """gnu\-v3""" 4
+.el .IP "\f(CWgnu\-v3\fR" 4
+.IX Item "gnu-v3"
+the one used by the \s-1GNU \*(C+\s0 compiler (g++) with the V3 \s-1ABI.\s0
+.ie n .IP """java""" 4
+.el .IP "\f(CWjava\fR" 4
+.IX Item "java"
+the one used by the \s-1GNU\s0 Java compiler (gcj)
+.ie n .IP """gnat""" 4
+.el .IP "\f(CWgnat\fR" 4
+.IX Item "gnat"
+the one used by the \s-1GNU\s0 Ada compiler (\s-1GNAT\s0).
+.RE
+.RS 4
+.RE
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Print a summary of the options to \fBc++filt\fR and exit.
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+Print the version number of \fBc++filt\fR and exit.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "FOOTNOTES"
+.IX Header "FOOTNOTES"
+.IP "1." 4
+MS-DOS does not allow \f(CW\*(C`+\*(C'\fR characters in file names, so on
+MS-DOS this program is named \fB\s-1CXXFILT\s0\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/cameratopam.1 b/upstream/mageia-cauldron/man1/cameratopam.1
new file mode 100644
index 00000000..ce9fdde5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cameratopam.1
@@ -0,0 +1,192 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Cameratopam User Manual" 0 "12 April 2005" "netpbm documentation"
+
+.SH NAME
+cameratopam - convert raw camera image to PAM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBcameratopam\fP
+
+[\fIinput_file_name\fP]
+
+[\fB-identify_only\fP]
+[\fB-quick_interpolate\fP]
+[\fB-half_size\fP]
+[\fB-four_color_rgb\fP]
+[\fB-document_mode\fP]
+[\fB-balance_auto\fP]
+[\fB-balance_camera\fP]
+[\fB-red_scale=\fP\fIfloat\fP]
+[\fB-blue_scale=\fP\fIfloat\fP]
+[\fB-bright=\fP\fIfraction\fP]
+[\fB-no_clip_color\fP]
+[\fB-rgb\fP]
+[\fB-use_secondary\fP]
+[\fB-linear\fP]
+[\fB-verbose\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and
+its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBcameratopam\fP converts from any of dozens of raw camera image
+formats to PAM.  
+.PP
+Digital still cameras often can produce images in a special raw
+format in addition to something more standard such as TIFF or JFIF
+(JPEG).  Software supplied with the camera allows you to manipulate
+the image using information which is lost when the camera converts to
+the common format.  A particular camera model often has a unique raw
+format.
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBcameratopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-identify_only\fP
+Report to Standard Error the format of the input image but don't
+generate an output image.  Program fails if it cannot recognize the
+format.
+
+.TP
+\fB-verbose\fP
+Report to Standard Error details of the processing.
+
+.TP
+\fB-quick_interpolate\fP
+Use simple bilinear interpolation for quick results.  The default
+is to use a slow, high-quality adaptive algorithm.
+
+.TP
+\fB-half_size\fP
+Half-size the output image.  Instead of interpolating, reduce
+each 2x2 block of sensors to one pixel.  Much faster than
+\fB-quick_interpolate\fP.
+
+.TP
+\fB-four_color_rgb\fP
+Interpolate RGB as four colors.  This causes a slight loss of
+detail, so use this only if you see false 2x2 mesh patterns in blue
+sky.
+
+.TP
+\fB-document_mode\fP
+Show the raw data as a grayscale image with no interpolation.
+This is good for photographing black and white documents.
+
+.TP
+\fB-balance_auto\fP
+Automatic color balance.  The default is to use a fixed
+color balance based on a white card photographed in sunlight.
+
+.TP
+\fB-balance_camera\fP
+Use the color balance specified by the camera.  If
+\fBcameratopam\fP can't find this, it prints a warning and reverts to
+the default.
+
+.TP
+\fB-red_scale=\fP\fIfloat\fP
+.TP
+\fB-blue_scale\fP\fIfloat\fP
+Further adjust the color balance by multiplying the red and blue
+channels by these values.  Both default to 1.0.
+
+.TP
+\fB-bright=\fP\fIfloat\fP
+Change the output brightness.  Default is 1.0.
+
+.TP
+\fB-no_clip_color\fP
+By default, \fBcameratoapm\fP clips all colors to prevent pink
+hues in the highlights.  Combine this option with
+\fB-bright=0.25\fP to leave the image data completely unclipped.
+
+.TP
+\fB-rgb\fP
+Write raw camera colors to the output file.  By default,
+\fBcameratoapm\fP converts to sRGB colorspace.
+
+.TP
+\fB-use_secondary\fP
+For cameras based on the Fuji Super CCD SR, this option causes
+\fBcameratopam\fP to use the secondary sensors, in effect
+underexposing the image by four stops to reveal detail in the
+highlights.  \fBcameratopam\fP silently ignores this option for all
+other cameras.
+
+.TP
+\fB-linear\fP
+This option causes \fBcameratopam\fP to generate a variation on
+PAM that has "linear" color samples.  In true PAM, each
+sample in the image raster is gamma-corrected; i.e. it is essentially
+proportional to brightness.  With the \fBlinear\fP option,
+\fBcameratopam\fP generates an image in which the samples are instead
+proportional to light intensity.
+.sp
+Without \fB-linear\fP, the image maxval is 255, so the image
+contains one byte per sample.  With \fB-linear\fP, the maxval is
+65535, so the image contains two bytes per sample.
+.sp
+Without \fB-linear\fP, \fBcameratopam\fP uses a 99th percentile
+white point.  With \fB-linear\fP, it doesn't.  I don't know what that
+means.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "411toppm" (1)\c
+\&, 
+.BR "pamflip" (1)\c
+\&, 
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBcameratopam\fP was new in Netpbm 10.28 (June 2005).
+.PP
+It was derived from the program 
+.UR https://dechifro.org/dcraw/
+\fBdcraw\fP by Dave Coffin
+.UE
+\&, by Bryan Henderson in April 2005.  Bryan replaced the part
+that generates the Netpbm output image and removed the Adobe Photoshop
+output function.  Bryan changed the command syntax and made other
+small changes to make the program consistent with Netpbm.  He also
+split the source code into manageable pieces (\fBdcraw\fP had a
+single 5000 line source file).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/cameratopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/captoinfo.1m b/upstream/mageia-cauldron/man1/captoinfo.1m
new file mode 100644
index 00000000..7bec27d3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/captoinfo.1m
@@ -0,0 +1,234 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 1998-2010,2016 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: captoinfo.1m,v 1.58 2023/12/23 16:28:31 tom Exp $
+.TH captoinfo 1M 2023-12-23 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.SH NAME
+\fB\%captoinfo\fP \-
+convert a \fItermcap\fP description into a \fI\%term\%info\fP description
+.SH SYNOPSIS
+.B captoinfo
+.RI [ tic-option ]
+.RI [ file
+\&.\|.\|.]
+.P
+.B "captoinfo \-V"
+.SH DESCRIPTION
+\fB\%captoinfo\fP translates terminal descriptions.
+It looks in each given text \fIfile\fP for \fI\%termcap\fP entries and,
+for each one found,
+writes an equivalent \fI\%\%term\%info\fP description to the standard
+output stream.
+\fI\%termcap\fP \fBtc\fP capabilities translate to \fI\%\%term\%info\fP
+\*(``\fBuse\fP\*('' capabilities.
+.PP
+If no \fIfile\fPs are specified,
+\fB\%captoinfo\fP interprets the content of the environment variable
+\fI\%TERMCAP\fP as a file name,
+and extracts only the entry for the terminal named in the environment
+variable \fITERM\fP from it.
+If the environment variable \fI\%TERMCAP\fP is not set,
+\fB\%captoinfo\fP reads
+.I \%/etc/termcap.
+.PP
+This utility is implemented as a link to \fB\%tic\fP(1M),
+with the latter's
+.B \-I
+option implied.
+You can use other \fB\%tic\fP options such as
+.BR \-1 ,
+.BR \-f ,
+.BR \-v ,
+.BR \-w ,
+and
+.BR \-x .
+The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
+.SS "Translations from Nonstandard Capabilities"
+\fB\%captoinfo\fP translates some obsolete,
+nonstandard capabilities into standard
+(SVr4/XSI Curses)
+\fI\%\%term\%info\fP capabilities.
+It issues a diagnostic to the standard error stream for each,
+inviting the user to check that it has not mistakenly translated an
+unknown or mistyped capability name.
+.PP
+.TS
+center;
+Cb S
+Cb Cb Cb Cb
+Cb Cb C  Lb.
+Name
+Obsolete	Standard	Origin	\f(BIterminfo\fP capability
+_
+BO	mr	AT&T	enter_reverse_mode
+CI	vi	AT&T	cursor_invisible
+CV	ve	AT&T	cursor_normal
+DS	mh	AT&T	enter_dim_mode
+EE	me	AT&T	exit_attribute_mode
+FE	LF	AT&T	label_on
+FL	LO	AT&T	label_off
+XS	mk	AT&T	enter_secure_mode
+EN	@7	XENIX	key_end
+GE	ae	XENIX	exit_alt_charset_mode
+GS	as	XENIX	enter_alt_charset_mode
+HM	kh	XENIX	key_home
+LD	kL	XENIX	key_dl
+PD	kN	XENIX	key_npage
+PN	po	XENIX	prtr_off
+PS	pf	XENIX	prtr_on
+PU	kP	XENIX	key_ppage
+RT	@8	XENIX	kent
+UP	ku	XENIX	kcuu1
+KA	k;	Tektronix	key_f10
+KB	F1	Tektronix	key_f11
+KC	F2	Tektronix	key_f12
+KD	F3	Tektronix	key_f13
+KE	F4	Tektronix	key_f14
+KF	F5	Tektronix	key_f15
+BC	Sb	Tektronix	set_background
+FC	Sf	Tektronix	set_foreground
+HS	mh	IRIX	enter_dim_mode
+.TE
+.PP
+XENIX \fI\%termcap\fP had a set of extension capabilities,
+corresponding to box drawing characters of CCSID
+(\*(``code page\*('') 437,
+as follows.
+.PP
+.TS
+center;
+cb cb
+cb l .
+\f(BItermcap\fP Name	Graphic
+_
+G2	upper left corner
+G3	lower left corner
+G1	upper right corner
+G4	lower right corner
+GR	tee pointing right
+GL	tee pointing left
+GU	tee pointing up
+GD	tee pointing down
+GH	horizontal line
+GV	vertical line
+GC	intersection
+G6	double upper left corner
+G7	double lower left corner
+G5	double upper right corner
+G8	double lower right corner
+Gr	double tee pointing right
+Gr	double tee pointing left
+Gu	double tee pointing up
+Gd	double tee pointing down
+Gh	double horizontal line
+Gv	double vertical line
+Gc	double intersection
+.\" TODO: There are about 40 box drawing code points in CCSID 437;
+.\" were there no XENIX capabilities for the mixed single- and double-
+.\" line intersections?
+.\"
+.\" TODO: GG doesn't seem to fit with the others; explain it.
+GG	ACS magic cookie count
+.TE
+.PP
+\fB\%captoinfo\fP composes single-line capabilities into an \fBacsc\fP
+string,
+and discards \fBGG\fP and double-line capabilities with a warning
+diagnostic.
+.PP
+IBM's AIX has a \fI\%\%term\%info\fP facility descended from SVr1
+\fI\%\%term\%info\fP,
+but which is incompatible with the SVr4 format.
+\fB\%captoinfo\fP translates the following AIX extensions.
+.PP
+.TS
+center;
+cb cb
+l  l .
+IBM	XSI
+_
+ksel	kslt
+kbtab	kcbt
+font0	s0ds
+font1	s1ds
+font2	s2ds
+font3	s3ds
+.TE
+.PP
+Additionally,
+this program translates the AIX \fBbox1\fP capability to an \fBacsc\fP
+string.
+.PP
+The HP-UX \fI\%\%term\%info\fP library supports two nonstandard
+\fI\%\%term\%info\fP capabilities,
+\fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock).
+\fB\%captoinfo\fP discards these with a warning message.
+.SH FILES
+.TP
+.I /etc/termcap
+default \fI\%termcap\fP terminal capability database
+.SH PORTABILITY
+X/Open Curses,
+Issue 7 (2009) describes \fBtic\fP briefly,
+but omits this program.
+.PP
+SVr4 systems provide \fB\%captoinfo\fP as a separate application from
+\fBtic\fP.
+Its
+.B \-v
+option does not accept a trace level argument
+.I n;
+repeat
+.B \-v
+.I n
+times instead.
+.PP
+NetBSD does not provide this application.
+.SH AUTHORS
+Eric S. Raymond <esr@snark.thyrsus.com>
+and
+.br
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%infocmp\fP(1M),
+\fB\%tic\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/cat.1 b/upstream/mageia-cauldron/man1/cat.1
new file mode 100644
index 00000000..df6e07d9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cat.1
@@ -0,0 +1,75 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CAT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+cat \- concatenate files and print on the standard output
+.SH SYNOPSIS
+.B cat
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Concatenate FILE(s) to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-A\fR, \fB\-\-show\-all\fR
+equivalent to \fB\-vET\fR
+.TP
+\fB\-b\fR, \fB\-\-number\-nonblank\fR
+number nonempty output lines, overrides \fB\-n\fR
+.TP
+\fB\-e\fR
+equivalent to \fB\-vE\fR
+.TP
+\fB\-E\fR, \fB\-\-show\-ends\fR
+display $ at end of each line
+.TP
+\fB\-n\fR, \fB\-\-number\fR
+number all output lines
+.TP
+\fB\-s\fR, \fB\-\-squeeze\-blank\fR
+suppress repeated empty output lines
+.TP
+\fB\-t\fR
+equivalent to \fB\-vT\fR
+.TP
+\fB\-T\fR, \fB\-\-show\-tabs\fR
+display TAB characters as ^I
+.TP
+\fB\-u\fR
+(ignored)
+.TP
+\fB\-v\fR, \fB\-\-show\-nonprinting\fR
+use ^ and M\- notation, except for LFD and TAB
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH EXAMPLES
+.TP
+cat f \- g
+Output f's contents, then standard input, then g's contents.
+.TP
+cat
+Copy standard input to standard output.
+.SH AUTHOR
+Written by Torbjorn Granlund and Richard M. Stallman.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBtac\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/cat>
+.br
+or available locally via: info \(aq(coreutils) cat invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chattr.1 b/upstream/mageia-cauldron/man1/chattr.1
new file mode 100644
index 00000000..1ba1bf18
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chattr.1
@@ -0,0 +1,299 @@
+.\" -*- nroff -*-
+.TH CHATTR 1 "February 2023" "E2fsprogs version 1.47.0"
+.SH NAME
+chattr \- change file attributes on a Linux file system
+.SH SYNOPSIS
+.B chattr
+[
+.B \-RVf
+]
+[
+.B \-v
+.I version
+]
+[
+.B \-p
+.I project
+]
+[
+.I mode
+]
+.I files...
+.SH DESCRIPTION
+.B chattr
+changes the file attributes on a Linux file system.
+.PP
+The format of a symbolic
+.I mode
+is
+.BR +-= [ aAcCdDeFijmPsStTux ].
+.PP
+The operator
+.RB ' + '
+causes the selected attributes to be added to the
+existing attributes of the files;
+.RB ' - '
+causes them to be removed; and
+.RB ' = '
+causes them to be the only attributes that the files have.
+.PP
+The letters
+.RB ' aAcCdDeFijmPsStTux '
+select the new attributes for the files:
+append only
+.RB ( a ),
+no atime updates
+.RB ( A ),
+compressed
+.RB ( c ),
+no copy on write
+.RB ( C ),
+no dump
+.RB ( d ),
+synchronous directory updates
+.RB ( D ),
+extent format
+.RB ( e ),
+case-insensitive directory lookups
+.RB ( F ),
+immutable
+.RB ( i ),
+data journaling
+.RB ( j ),
+don't compress
+.RB ( m ),
+project hierarchy
+.RB ( P ),
+secure deletion
+.RB ( s ),
+synchronous updates
+.RB ( S ),
+no tail-merging
+.RB ( t ),
+top of directory hierarchy
+.RB ( T ),
+undeletable
+.RB ( u ),
+and direct access for files
+.RB ( x ).
+.PP
+The following attributes are read-only, and may be listed by
+.BR lsattr (1)
+but not modified by chattr:
+encrypted
+.RB ( E ),
+indexed directory
+.RB ( I ),
+inline data
+.RB ( N ),
+and verity
+.RB ( V ).
+.PP
+Not all flags are supported or utilized by all file systems; refer to
+file system-specific man pages such as
+.BR btrfs (5),
+.BR ext4 (5),
+.BR mkfs.f2fs (8),
+and
+.BR xfs (5)
+for more file system-specific details.
+.SH OPTIONS
+.TP
+.B \-R
+Recursively change attributes of directories and their contents.
+.TP
+.B \-V
+Be verbose with chattr's output and print the program version.
+.TP
+.B \-f
+Suppress most error messages.
+.TP
+.BI \-v " version"
+Set the file's version/generation number.
+.TP
+.BI \-p " project"
+Set the file's project number.
+.SH ATTRIBUTES
+.TP
+.B a
+A file with the 'a' attribute set can only be opened in append mode for
+writing.  Only the superuser or a process possessing the
+CAP_LINUX_IMMUTABLE capability can set or clear this attribute.
+.TP
+.B A
+When a file with the 'A' attribute set is accessed, its atime record is
+not modified.  This avoids a certain amount of disk I/O for laptop
+systems.
+.TP
+.B c
+A file with the 'c' attribute set is automatically compressed on the disk
+by the kernel.  A read from this file returns uncompressed data.  A write to
+this file compresses data before storing them on the disk.  Note: please
+make sure to read the bugs and limitations section at the end of this
+document.  (Note: For btrfs, If the 'c' flag is set, then the 'C' flag
+cannot be set. Also conflicts with btrfs mount option 'nodatasum')
+.TP
+.B C
+A file with the 'C' attribute set will not be subject to copy-on-write
+updates.  This flag is only supported on file systems which perform
+copy-on-write.  (Note: For btrfs, the 'C' flag should be
+set on new or empty files.  If it is set on a file which already has
+data blocks, it is undefined when the blocks assigned to the file will
+be fully stable.  If the 'C' flag is set on a directory, it will have no
+effect on the directory, but new files created in that directory will
+have the No_COW attribute set. If the 'C' flag is set, then the 'c' flag
+cannot be set.)
+.TP
+.B d
+A file with the 'd' attribute set is not a candidate for backup when the
+.BR dump (8)
+program is run.
+.TP
+.B D
+When a directory with the 'D' attribute set is modified,
+the changes are written synchronously to the disk; this is equivalent to
+the 'dirsync' mount option applied to a subset of the files.
+.TP
+.B e
+The 'e' attribute indicates that the file is using extents for mapping
+the blocks on disk.  It may not be removed using
+.BR chattr (1).
+.TP
+.B E
+A file, directory, or symlink with the 'E' attribute set is encrypted by the
+file system.  This attribute may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B F
+A directory with the 'F' attribute set indicates that all the path
+lookups inside that directory are made in a case-insensitive fashion.
+This attribute can only be changed in empty directories on file systems
+with the casefold feature enabled.
+.TP
+.B i
+A file with the 'i' attribute cannot be modified: it cannot be deleted or
+renamed, no link can be created to this file, most of the file's
+metadata can not be modified, and the file can not be opened in write mode.
+Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
+capability can set or clear this attribute.
+.TP
+.B I
+The 'I' attribute is used by the htree code to indicate that a directory
+is being indexed using hashed trees.  It may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B j
+A file with the 'j' attribute has all of its data written to the ext3 or
+ext4 journal before being written to the file itself, if the file system
+is mounted with the "data=ordered" or "data=writeback" options and the
+file system has a journal.  When the file system is mounted with the
+"data=journal" option all file data is already journalled and this
+attribute has no effect.  Only the superuser or a process possessing the
+CAP_SYS_RESOURCE capability can set or clear this attribute.
+.TP
+.B m
+A file with the 'm' attribute is excluded from compression on file
+systems that support per-file compression.
+.TP
+.B N
+A file with the 'N' attribute set indicates that the file has data
+stored inline, within the inode itself. It may not be set or cleared
+using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B P
+A directory with the 'P' attribute set will enforce a hierarchical
+structure for project id's.  This means that files and directories created
+in the directory will inherit the project id of the directory, rename
+operations are constrained so when a file or directory is moved into
+another directory, that the project ids must match.  In addition, a
+hard link to file can only be created when the project id for the file
+and the destination directory match.
+.TP
+.B s
+When a file with the 's' attribute set is deleted, its blocks are zeroed
+and written back to the disk.  Note: please make sure to read the bugs
+and limitations section at the end of this document.
+.TP
+.B S
+When a file with the 'S' attribute set is modified,
+the changes are written synchronously to the disk; this is equivalent to
+the 'sync' mount option applied to a subset of the files.
+.TP
+.B t
+A file with the 't' attribute will not have a partial block fragment at
+the end of the file merged with other files (for those file systems which
+support tail-merging).  This is necessary for applications such as LILO
+which read the file system directly, and which don't understand tail-merged
+files.  Note: As of this writing, the ext2, ext3, and ext4 file systems do
+not support tail-merging.
+.TP
+.B T
+A directory with the 'T' attribute will be deemed to be the top of
+directory hierarchies for the purposes of the Orlov block allocator.
+This is a hint to the block allocator used by ext3 and ext4 that the
+subdirectories under this directory are not related, and thus should be
+spread apart for allocation purposes.   For example it is a very good
+idea to set the 'T' attribute on the /home directory, so that /home/john
+and /home/mary are placed into separate block groups.  For directories
+where this attribute is not set, the Orlov block allocator will try to
+group subdirectories closer together where possible.
+.TP
+.B u
+When a file with the 'u' attribute set is deleted, its contents are
+saved.  This allows the user to ask for its undeletion.  Note: please
+make sure to read the bugs and limitations section at the end of this
+document.
+.TP
+.B x
+A file with the 'x' requests the use of direct access (dax) mode, if the
+kernel supports DAX.  This can be overridden by the 'dax=never' mount
+option.  For more information see the kernel documentation for dax:
+<https://www.kernel.org/doc/html/latest/filesystems/dax.html>.
+.IP
+If the attribute is set on an existing directory, it will be inherited
+by all files and subdirectories that are subsequently created in the
+directory.  If an existing directory has contained some files and
+subdirectories, modifying the attribute on the parent directory doesn't
+change the attributes on these files and subdirectories.
+.TP
+.B V
+A file with the 'V' attribute set has fs-verity enabled.  It cannot be
+written to, and the file system will automatically verify all data read
+from it against a cryptographic hash that covers the entire file's
+contents, e.g. via a Merkle tree.  This makes it possible to efficiently
+authenticate the file.  This attribute may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.PP
+.SH AUTHOR
+.B chattr
+was written by Remy Card <Remy.Card@linux.org>.  It is currently being
+maintained by Theodore Ts'o <tytso@alum.mit.edu>.
+.SH BUGS AND LIMITATIONS
+The 'c', 's',  and 'u' attributes are not honored
+by the ext2, ext3, and ext4 file systems as implemented in the current
+mainline Linux kernels.
+Setting 'a' and 'i' attributes will not affect the ability to write
+to already existing file descriptors.
+.PP
+The 'j' option is only useful for ext3 and ext4 file systems.
+.PP
+The 'D' option is only useful on Linux kernel 2.5.19 and later.
+.SH AVAILABILITY
+.B chattr
+is part of the e2fsprogs package and is available from
+http://e2fsprogs.sourceforge.net.
+.SH SEE ALSO
+.BR lsattr (1),
+.BR btrfs (5),
+.BR ext4 (5),
+.BR mkfs.f2fs (8),
+.BR xfs (5).
diff --git a/upstream/mageia-cauldron/man1/chcon.1 b/upstream/mageia-cauldron/man1/chcon.1
new file mode 100644
index 00000000..e81af735
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chcon.1
@@ -0,0 +1,92 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CHCON "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+chcon \- change file security context
+.SH SYNOPSIS
+.B chcon
+[\fI\,OPTION\/\fR]... \fI\,CONTEXT FILE\/\fR...
+.br
+.B chcon
+[\fI\,OPTION\/\fR]... [\fI\,-u USER\/\fR] [\fI\,-r ROLE\/\fR] [\fI\,-l RANGE\/\fR] [\fI\,-t TYPE\/\fR] \fI\,FILE\/\fR...
+.br
+.B chcon
+[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Change the SELinux security context of each FILE to CONTEXT.
+With \fB\-\-reference\fR, change the security context of each FILE to that of RFILE.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-dereference\fR
+affect the referent of each symbolic link (this is
+the default), rather than the symbolic link itself
+.TP
+\fB\-h\fR, \fB\-\-no\-dereference\fR
+affect symbolic links instead of any referenced file
+.TP
+\fB\-u\fR, \fB\-\-user\fR=\fI\,USER\/\fR
+set user USER in the target security context
+.TP
+\fB\-r\fR, \fB\-\-role\fR=\fI\,ROLE\/\fR
+set role ROLE in the target security context
+.TP
+\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR
+set type TYPE in the target security context
+.TP
+\fB\-l\fR, \fB\-\-range\fR=\fI\,RANGE\/\fR
+set range RANGE in the target security context
+.TP
+\fB\-\-no\-preserve\-root\fR
+do not treat '/' specially (the default)
+.TP
+\fB\-\-preserve\-root\fR
+fail to operate recursively on '/'
+.TP
+\fB\-\-reference\fR=\fI\,RFILE\/\fR
+use RFILE's security context rather than specifying
+a CONTEXT value
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+operate on files and directories recursively
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+output a diagnostic for every file processed
+.PP
+The following options modify how a hierarchy is traversed when the \fB\-R\fR
+option is also specified.  If more than one is specified, only the final
+one takes effect.
+.TP
+\fB\-H\fR
+if a command line argument is a symbolic link
+to a directory, traverse it
+.TP
+\fB\-L\fR
+traverse every symbolic link to a directory
+encountered
+.TP
+\fB\-P\fR
+do not traverse any symbolic links (default)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Russell Coker and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/chcon>
+.br
+or available locally via: info \(aq(coreutils) chcon invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chgrp.1 b/upstream/mageia-cauldron/man1/chgrp.1
new file mode 100644
index 00000000..318b0c91
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chgrp.1
@@ -0,0 +1,93 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CHGRP "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+chgrp \- change group ownership
+.SH SYNOPSIS
+.B chgrp
+[\fI\,OPTION\/\fR]... \fI\,GROUP FILE\/\fR...
+.br
+.B chgrp
+[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Change the group of each FILE to GROUP.
+With \fB\-\-reference\fR, change the group of each FILE to that of RFILE.
+.TP
+\fB\-c\fR, \fB\-\-changes\fR
+like verbose but report only when a change is made
+.TP
+\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR
+suppress most error messages
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+output a diagnostic for every file processed
+.TP
+\fB\-\-dereference\fR
+affect the referent of each symbolic link (this is
+the default), rather than the symbolic link itself
+.TP
+\fB\-h\fR, \fB\-\-no\-dereference\fR
+affect symbolic links instead of any referenced file
+(useful only on systems that can change the
+ownership of a symlink)
+.TP
+\fB\-\-no\-preserve\-root\fR
+do not treat '/' specially (the default)
+.TP
+\fB\-\-preserve\-root\fR
+fail to operate recursively on '/'
+.TP
+\fB\-\-reference\fR=\fI\,RFILE\/\fR
+use RFILE's group rather than specifying a
+GROUP value
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+operate on files and directories recursively
+.PP
+The following options modify how a hierarchy is traversed when the \fB\-R\fR
+option is also specified.  If more than one is specified, only the final
+one takes effect.
+.TP
+\fB\-H\fR
+if a command line argument is a symbolic link
+to a directory, traverse it
+.TP
+\fB\-L\fR
+traverse every symbolic link to a directory
+encountered
+.TP
+\fB\-P\fR
+do not traverse any symbolic links (default)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH EXAMPLES
+.TP
+chgrp staff /u
+Change the group of /u to "staff".
+.TP
+chgrp \-hR staff /u
+Change the group of /u and subfiles to "staff".
+.SH AUTHOR
+Written by David MacKenzie and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBchown\fP(1), \fBchown\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/chgrp>
+.br
+or available locally via: info \(aq(coreutils) chgrp invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chmod.1 b/upstream/mageia-cauldron/man1/chmod.1
new file mode 100644
index 00000000..54a606c1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chmod.1
@@ -0,0 +1,173 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CHMOD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+chmod \- change file mode bits
+.SH SYNOPSIS
+.B chmod
+[\fI\,OPTION\/\fR]... \fI\,MODE\/\fR[\fI\,,MODE\/\fR]... \fI\,FILE\/\fR...
+.br
+.B chmod
+[\fI\,OPTION\/\fR]... \fI\,OCTAL-MODE FILE\/\fR...
+.br
+.B chmod
+[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR...
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR chmod .
+.B chmod
+changes the file mode bits of each given file according to
+.IR mode ,
+which can be either a symbolic representation of changes to make, or
+an octal number representing the bit pattern for the new mode bits.
+.PP
+The format of a symbolic mode is [\c
+\fBugoa\fP.\|.\|.][[\fB-+=\fP][\fIperms\fP.\|.\|.].\|.\|.],
+where
+.I "perms"
+is either zero or more letters from the set
+\fBrwxXst\fP, or a single letter from the set \fBugo\fP.
+Multiple symbolic
+modes can be given, separated by commas.
+.PP
+A combination of the letters \fBugoa\fP controls which users' access
+to the file will be changed: the user who owns it (\fBu\fP), other
+users in the file's group (\fBg\fP), other users not in the file's
+group (\fBo\fP), or all users (\fBa\fP).  If none of these are given,
+the effect is as if (\fBa\fP) were
+given, but bits that are set in the umask are not affected.
+.PP
+The operator \fB+\fP causes the selected file mode bits to be added to
+the existing file mode bits of each file; \fB-\fP causes them to be
+removed; and \fB=\fP causes them to be added and causes unmentioned
+bits to be removed except that a directory's unmentioned set user and
+group ID bits are not affected.
+.PP
+The letters \fBrwxXst\fP select file mode bits for the affected users:
+read (\fBr\fP), write (\fBw\fP), execute (or search for directories)
+(\fBx\fP), execute/search only if the file is a directory or already
+has execute permission for some user (\fBX\fP), set user or group ID
+on execution (\fBs\fP), restricted deletion flag or sticky bit
+(\fBt\fP).  Instead of one or more of these letters, you can specify
+exactly one of the letters \fBugo\fP: the permissions granted to the
+user who owns the file (\fBu\fP), the permissions granted to other
+users who are members of the file's group (\fBg\fP),
+and the permissions granted to users that are in neither of the two preceding
+categories (\fBo\fP).
+.PP
+A numeric mode is from one to four octal digits (0\-7), derived by
+adding up the bits with values 4, 2, and 1.  Omitted digits are
+assumed to be leading zeros.
+The first digit selects the set user ID (4) and set group ID (2) and
+restricted deletion or sticky (1) attributes.  The second digit
+selects permissions for the user who owns the file: read (4), write (2),
+and execute (1); the third selects permissions for other users in the
+file's group, with the same values; and the fourth for other users not
+in the file's group, with the same values.
+.PP
+.B chmod
+never changes the permissions of symbolic links; the
+.B chmod
+system call cannot change their permissions.  This is not a problem
+since the permissions of symbolic links are never used.
+However, for each symbolic link listed on the command line,
+.B chmod
+changes the permissions of the pointed-to file.
+In contrast,
+.B chmod
+ignores symbolic links encountered during recursive directory
+traversals.
+.SH "SETUID AND SETGID BITS"
+.B chmod
+clears the set-group-ID bit of a
+regular file if the file's group ID does not match the user's
+effective group ID or one of the user's supplementary group IDs,
+unless the user has appropriate privileges.  Additional restrictions
+may cause the set-user-ID and set-group-ID bits of
+.I MODE
+or
+.I RFILE
+to be ignored.  This behavior depends on the policy and
+functionality of the underlying
+.B chmod
+system call.  When in
+doubt, check the underlying system behavior.
+.PP
+For directories
+.B chmod
+preserves set-user-ID and set-group-ID bits unless you
+explicitly specify otherwise.  You can set or clear the bits with
+symbolic modes like
+.B u+s
+and
+.BR g\-s .
+To clear these bits for directories with a numeric mode requires
+an additional leading zero like
+.BR 00755 ,
+leading minus like
+.BR \-6000 ,
+or leading equals like
+.BR =755 .
+.SH "RESTRICTED DELETION FLAG OR STICKY BIT"
+The restricted deletion flag or sticky bit is a single bit, whose
+interpretation depends on the file type.  For directories, it prevents
+unprivileged users from removing or renaming a file in the directory
+unless they own the file or the directory; this is called the
+.I "restricted deletion flag"
+for the directory, and is commonly found on world-writable directories
+like \fB/tmp\fP.  For regular files on some older systems, the bit
+saves the program's text image on the swap device so it will load more
+quickly when run; this is called the
+.IR "sticky bit" .
+.SH OPTIONS
+.PP
+Change the mode of each FILE to MODE.
+With \fB\-\-reference\fR, change the mode of each FILE to that of RFILE.
+.TP
+\fB\-c\fR, \fB\-\-changes\fR
+like verbose but report only when a change is made
+.TP
+\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR
+suppress most error messages
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+output a diagnostic for every file processed
+.TP
+\fB\-\-no\-preserve\-root\fR
+do not treat '/' specially (the default)
+.TP
+\fB\-\-preserve\-root\fR
+fail to operate recursively on '/'
+.TP
+\fB\-\-reference\fR=\fI\,RFILE\/\fR
+use RFILE's mode instead of MODE values
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+change files and directories recursively
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Each MODE is of the form '[ugoa]*([\-+=]([rwxXst]*|[ugo]))+|[\-+=][0\-7]+'.
+.SH AUTHOR
+Written by David MacKenzie and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBchmod\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/chmod>
+.br
+or available locally via: info \(aq(coreutils) chmod invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chown.1 b/upstream/mageia-cauldron/man1/chown.1
new file mode 100644
index 00000000..5b15d87d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chown.1
@@ -0,0 +1,125 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CHOWN "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+chown \- change file owner and group
+.SH SYNOPSIS
+.B chown
+[\fI\,OPTION\/\fR]... [\fI\,OWNER\/\fR][\fI\,:\/\fR[\fI\,GROUP\/\fR]] \fI\,FILE\/\fR...
+.br
+.B chown
+[\fI\,OPTION\/\fR]... \fI\,--reference=RFILE FILE\/\fR...
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR chown .
+.B chown
+changes the user and/or group ownership of each given file.  If
+only an owner (a user name or numeric user ID) is given, that user is made the
+owner of each given file, and the files' group is not changed.  If the
+owner is followed by a colon and a group name (or numeric group ID),
+with no spaces between them, the group ownership of the files is
+changed as well.  If a colon but no group name follows the user name,
+that user is made the owner of the files and the group of the files is
+changed to that user's login group.  If the colon and group are given,
+but the owner is omitted, only the group of the files is changed;
+in this case,
+.B chown
+performs the same function as
+.BR chgrp .
+If only a colon is given, or if the entire operand is empty, neither the
+owner nor the group is changed.
+.SH OPTIONS
+.PP
+Change the owner and/or group of each FILE to OWNER and/or GROUP.
+With \fB\-\-reference\fR, change the owner and group of each FILE to those of RFILE.
+.TP
+\fB\-c\fR, \fB\-\-changes\fR
+like verbose but report only when a change is made
+.TP
+\fB\-f\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR
+suppress most error messages
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+output a diagnostic for every file processed
+.TP
+\fB\-\-dereference\fR
+affect the referent of each symbolic link (this is
+the default), rather than the symbolic link itself
+.TP
+\fB\-h\fR, \fB\-\-no\-dereference\fR
+affect symbolic links instead of any referenced file
+(useful only on systems that can change the
+ownership of a symlink)
+.TP
+\fB\-\-from\fR=\fI\,CURRENT_OWNER\/\fR:CURRENT_GROUP
+change the owner and/or group of each file only if
+its current owner and/or group match those specified
+here.  Either may be omitted, in which case a match
+is not required for the omitted attribute
+.TP
+\fB\-\-no\-preserve\-root\fR
+do not treat '/' specially (the default)
+.TP
+\fB\-\-preserve\-root\fR
+fail to operate recursively on '/'
+.TP
+\fB\-\-reference\fR=\fI\,RFILE\/\fR
+use RFILE's owner and group rather than
+specifying OWNER:GROUP values
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+operate on files and directories recursively
+.PP
+The following options modify how a hierarchy is traversed when the \fB\-R\fR
+option is also specified.  If more than one is specified, only the final
+one takes effect.
+.TP
+\fB\-H\fR
+if a command line argument is a symbolic link
+to a directory, traverse it
+.TP
+\fB\-L\fR
+traverse every symbolic link to a directory
+encountered
+.TP
+\fB\-P\fR
+do not traverse any symbolic links (default)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Owner is unchanged if missing.  Group is unchanged if missing, but changed
+to login group if implied by a ':' following a symbolic OWNER.
+OWNER and GROUP may be numeric as well as symbolic.
+.SH EXAMPLES
+.TP
+chown root /u
+Change the owner of /u to "root".
+.TP
+chown root:staff /u
+Likewise, but also change its group to "staff".
+.TP
+chown \-hR root /u
+Change the owner of /u and subfiles to "root".
+.SH AUTHOR
+Written by David MacKenzie and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBchown\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/chown>
+.br
+or available locally via: info \(aq(coreutils) chown invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chroot.1 b/upstream/mageia-cauldron/man1/chroot.1
new file mode 100644
index 00000000..707992f6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chroot.1
@@ -0,0 +1,50 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CHROOT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+chroot \- run command or interactive shell with special root directory
+.SH SYNOPSIS
+.B chroot
+[\fI\,OPTION\/\fR] \fI\,NEWROOT \/\fR[\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...]
+.br
+.B chroot
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Run COMMAND with root directory set to NEWROOT.
+.TP
+\fB\-\-groups\fR=\fI\,G_LIST\/\fR
+specify supplementary groups as g1,g2,..,gN
+.TP
+\fB\-\-userspec\fR=\fI\,USER\/\fR:GROUP
+specify user and group (ID or name) to use
+.TP
+\fB\-\-skip\-chdir\fR
+do not change working directory to '/'
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If no command is given, run '"$SHELL" \fB\-i\fR' (default: '/bin/sh \fB\-i\fR').
+.SH AUTHOR
+Written by Roland McGrath.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBchroot\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/chroot>
+.br
+or available locally via: info \(aq(coreutils) chroot invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/chvt.1 b/upstream/mageia-cauldron/man1/chvt.1
new file mode 100644
index 00000000..d015b05c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/chvt.1
@@ -0,0 +1,31 @@
+.\" @(#)chvt.1 1.0 970126 aeb
+.TH CHVT 1 "26 January 1997" "kbd"
+.SH NAME
+chvt \- change foreground virtual terminal
+.SH SYNOPSIS
+.B chvt
+[\fI\,option\/\fR...]
+.I N
+.SH DESCRIPTION
+The command
+.B chvt
+.I N
+makes
+.I /dev/ttyN
+the foreground terminal.
+(The corresponding screen is created if it did not exist yet.
+To get rid of unused VTs,
+use
+.BR deallocvt (1).)
+The key combination
+.RI (Ctrl-)LeftAlt-F N
+(with
+.I N
+in the range 1-12) usually has a similar effect.
+.SH OPTIONS
+.TP
+.I "\-V, \-\-version"
+print program version and exit.
+.TP
+.I "\-h, \-\-help"
+show this text and exit.
diff --git a/upstream/mageia-cauldron/man1/ci.1 b/upstream/mageia-cauldron/man1/ci.1
new file mode 100644
index 00000000..dc3e95f1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ci.1
@@ -0,0 +1,944 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH CI 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+ci \- check in RCS revisions
+.SH SYNOPSIS
+.B ci
+.RI [ options ] " file " .\|.\|.
+.SH DESCRIPTION
+.B ci
+stores new revisions into \*os.
+Each file name matching an \*r suffix
+is taken to be an \*o.
+All others
+are assumed to be working files containing new revisions.
+.B ci
+deposits the contents of each working file
+into the corresponding \*o.
+If only a working file is given,
+.B ci
+tries to find the corresponding \*o in an \*r subdirectory
+and then in the working file's directory.
+For more details, see
+.SM "FILE NAMING"
+below.
+.PP
+For
+.B ci
+to work, the caller's login must be on the access list,
+except if the access list is empty or the caller is the superuser or the
+owner of the file.
+To append a new revision to an existing branch, the tip revision on
+that branch must be locked by the caller.  Otherwise, only a
+new branch can be created.  This restriction is not enforced
+for the owner of the file if non-strict locking is used
+(see
+.BR rcs (1)).
+A lock held by someone else can be broken with the
+.B rcs
+command.
+.PP
+Unless the
+.B \-f
+option is given,
+.B ci
+checks whether the revision to be deposited differs from the preceding one.
+If not, instead of creating a new revision
+.B ci
+reverts to the preceding one.
+To revert, ordinary
+.B ci
+removes the working file and any lock;
+.B "ci\ \-l"
+keeps and
+.B "ci\ \-u"
+removes any lock, and then they both generate a new working file much as if
+.B "co\ \-l"
+or
+.B "co\ \-u"
+had been applied to the preceding revision.
+When reverting, any
+.B \-n
+and
+.B \-s
+options apply to the preceding revision.
+.PP
+For each revision deposited,
+.B ci
+prompts for a log message.
+The log message should summarize the change and must be terminated by
+end-of-file or by a line containing
+.BR \&. "\ by"
+itself.
+If several files are checked in
+.B ci
+asks whether to reuse the
+previous log message.
+If the standard input is not a terminal,
+.B ci
+suppresses the prompt
+and uses the same log message for all files.
+See also
+.BR \-m .
+.PP
+If the \*o does not exist,
+.B ci
+creates it and
+deposits the contents of the working file as the initial revision
+(default number:
+.BR 1.1 ).
+The access list is initialized to empty.
+Instead of the log message,
+.B ci
+requests descriptive text (see
+.B \-t
+below).
+.PP
+The number
+.I rev
+of the deposited revision can be given by any of the options
+.BR \-f ,
+.BR \-i ,
+.BR \-I ,
+.BR \-j ,
+.BR \-k ,
+.BR \-l ,
+.BR \-M ,
+.BR \-q ,
+.BR \-r ,
+or
+.BR \-u .
+.I rev
+can be symbolic, numeric, or mixed.
+Symbolic names in
+.I rev
+must already be defined;
+see the
+.B \-n
+and
+.B \-N
+options for assigning names during checkin.
+If
+.I rev
+is
+.BR $ ,
+.B ci
+determines the revision number from keyword values in the working file.
+.PP
+If
+.I rev
+begins with a period,
+then the default branch (normally the trunk) is prepended to it.
+If
+.I rev
+is a branch number followed by a period,
+then the latest revision on that branch is used.
+.PP
+If
+.I rev
+is a revision number, it must be higher than the latest
+one on the branch to which
+.I rev
+belongs, or must start a new branch.
+.PP
+If
+.I rev
+is a branch rather than a revision number,
+the new revision is appended to that branch.  The level number is obtained
+by incrementing the tip revision number of that branch.
+If
+.I rev
+indicates a non-existing branch,
+that branch is created with the initial revision numbered
+.IB rev .1\f1.\fP
+.br
+.ne 8
+.PP
+If
+.I rev
+is omitted,
+.B ci
+tries to derive the new revision number from
+the caller's last lock.  If the caller has locked the tip revision of a branch,
+the new revision is appended to that branch.
+The new revision number is obtained
+by incrementing the tip revision number.
+If the caller locked a non-tip revision, a new branch is started at
+that revision by incrementing the highest branch number at that revision.
+The default initial branch and level numbers are
+.BR 1 .
+.PP
+If
+.I rev
+is omitted and the caller has no lock, but owns
+the file and locking
+is not set to
+.IR strict ,
+then the revision is appended to the
+default branch (normally the trunk; see the
+.B \-b
+option of
+.BR rcs (1)).
+.PP
+Exception: On the trunk, revisions can be appended to the end, but
+not inserted.
+.SH OPTIONS
+.TP
+.BI \-r rev
+Check in revision
+.IR rev .
+.TP
+.BR \-r
+The bare
+.B \-r
+option (without any revision) has an unusual meaning in
+.BR ci .
+With other \*r commands, a bare
+.B \-r
+option specifies the most recent revision on the default branch,
+but with
+.BR ci ,
+a bare
+.B \-r
+option reestablishes the default behavior of releasing a lock and
+removing the working file, and is used to override any default
+.B \-l
+or
+.B \-u
+options established by shell aliases or scripts.
+.TP
+.BR \-l [\f2rev\fP]
+works like
+.BR \-r ,
+except it performs an additional
+.B "co\ \-l"
+for the
+deposited revision.  Thus, the deposited revision is immediately
+checked out again and locked.
+This is useful for saving a revision although one wants to continue
+editing it after the checkin.
+.TP
+.BR \-u [\f2rev\fP]
+works like
+.BR \-l ,
+except that the deposited revision is not locked.
+This lets one read the working file
+immediately after checkin.
+.RS
+.PP
+The
+.BR \-l ,
+bare
+.BR \-r ,
+and
+.B \-u
+options are mutually exclusive and silently override each other.
+For example,
+.B "ci\ \-u\ \-r"
+is equivalent to
+.B "ci\ \-r"
+because bare
+.B \-r
+overrides
+.BR \-u .
+.RE
+.TP
+.BR \-f [\f2rev\fP]
+forces a deposit; the new revision is deposited even it is not different
+from the preceding one.
+.TP
+.BR \-k [\f2rev\fP]
+searches the working file for keyword values to determine its revision number,
+creation date, state, and author (see
+.BR co (1)),
+and assigns these
+values to the deposited revision, rather than computing them locally.
+It also generates a default login message noting the login of the caller
+and the actual checkin date.
+This option is useful for software distribution.  A revision that is sent to
+several sites should be checked in with the
+.B \-k
+option at these sites to
+preserve the original number, date, author, and state.
+The extracted keyword values and the default log message can be overridden
+with the options
+.BR \-d ,
+.BR \-m ,
+.BR \-s ,
+.BR \-w ,
+and any option that carries a revision number.
+.TP
+.BR \-q [\f2rev\fP]
+quiet mode; diagnostic output is not printed.
+A revision that is not different from the preceding one is not deposited,
+unless
+.B \-f
+is given.
+.TP
+.BR \-i [\f2rev\fP]
+initial checkin; report an error if the \*o already exists.
+This avoids race conditions in certain applications.
+.TP
+.BR \-j [\f2rev\fP]
+just checkin and do not initialize;
+report an error if the \*o does not already exist.
+.TP
+.BR \-I [\f2rev\fP]
+interactive mode;
+the user is prompted and questioned
+even if the standard input is not a terminal.
+.TP
+.BR \-d "[\f2date\fP]"
+uses
+.I date
+for the checkin date and time.
+The
+.I date
+is specified in free format as explained in
+.BR co (1).
+This is useful for lying about the checkin date, and for
+.B \-k
+if no date is available.
+If
+.I date
+is empty, the working file's time of last modification is used.
+.TP
+.BR \-M [\f2rev\fP]
+Set the modification time on any new working file
+to be the date of the retrieved revision.
+For example,
+.BI "ci\ \-d\ \-M\ \-u" "\ f"
+does not alter
+.IR f 's
+modification time, even if
+.IR f 's
+contents change due to keyword substitution.
+Use this option with care; it can confuse
+.BR make (1).
+.TP
+.BR \-m [\fP\f2msg\fP]
+uses the string
+.I msg
+as the log message for all revisions checked in.
+If
+.I msg
+is omitted, it defaults to "*** empty log message ***".
+By convention, log messages that start with
+.B #
+are comments and are ignored by programs like GNU Emacs's
+.B vc
+package.
+Also, log messages that start with
+.BI { clumpname }
+(followed by white space) are meant to be clumped together if possible,
+even if they are associated with different files; the
+.BI { clumpname }
+label is used only for clumping,
+and is not considered to be part of the log message itself.
+.TP
+.BI \-n "name"
+assigns the symbolic name
+.I name
+to the number of the checked-in revision.
+.B ci
+prints an error message if
+.I name
+is already assigned to another
+number.
+.TP
+.BI \-N "name"
+same as
+.BR \-n ,
+except that it overrides a previous assignment of
+.IR name .
+.TP
+.BI \-s "state"
+sets the state of the checked-in revision to the identifier
+.IR state .
+The default state is
+.BR Exp .
+.TP
+.BI \-t file
+writes descriptive text from the contents of the named
+.I file
+into the \*o,
+deleting the existing text.
+The
+.I file
+cannot begin with
+.BR \- .
+.TP
+.BI \-t\- string
+Write descriptive text from the
+.I string
+into the \*o, deleting the existing text.
+.RS
+.PP
+The
+.B \-t
+option, in both its forms, has effect only during an initial checkin;
+it is silently ignored otherwise.
+.PP
+During the initial checkin, if
+.B \-t
+is not given,
+.B ci
+obtains the text from standard input,
+terminated by end-of-file or by a line containing
+.BR \&. "\ by"
+itself.
+The user is prompted for the text if interaction is possible; see
+.BR \-I .
+.PP
+For backward compatibility with older versions of \*r, a bare
+.B \-t
+option is ignored.
+.RE
+.TP
+.B \-T
+Set the \*o's modification time to the new revision's time
+if the former precedes the latter and there is a new revision;
+preserve the \*o's modification time otherwise.
+If you have locked a revision,
+.B ci
+usually updates the \*o's modification time to the current time,
+because the lock is stored in the \*o
+and removing the lock requires changing the \*o.
+This can create an \*o newer than the working file in one of two ways:
+first,
+.B "ci\ \-M"
+can create a working file with a date before the current time;
+second, when reverting to the previous revision
+the \*o can change while the working file remains unchanged.
+These two cases can cause excessive recompilation caused by a
+.BR make (1)
+dependency of the working file on the \*o.
+The
+.B \-T
+option inhibits this recompilation by lying about the \*o's date.
+Use this option with care; it can suppress recompilation even when
+a checkin of one working file should affect
+another working file associated with the same \*o.
+For example, suppose the \*o's time is 01:00,
+the (changed) working file's time is 02:00,
+some other copy of the working file has a time of 03:00,
+and the current time is 04:00.
+Then
+.B "ci\ \-d\ \-T"
+sets the \*o's time to 02:00 instead of the usual 04:00;
+this causes
+.BR make (1)
+to think (incorrectly) that the other copy is newer than the \*o.
+.TP
+.BI \-w "login"
+uses
+.I login
+for the author field of the deposited revision.
+Useful for lying about the author, and for
+.B \-k
+if no author is available.
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.IR n .
+See
+.BR co (1)
+for details.
+.TP
+.BI \-x "suffixes"
+specifies the suffixes for \*os.
+A nonempty suffix matches any file name ending in the suffix.
+An empty suffix matches any file name of the form
+.BI RCS/ frag
+or
+.IB frag1 /RCS/ frag2.
+The
+.B \-x
+option can specify a list of suffixes
+separated by
+.BR / .
+For example,
+.B \-x,v/
+specifies two suffixes:
+.B ,v
+and the empty suffix.
+If two or more suffixes are specified,
+they are tried in order when looking for an \*o;
+the first one that works is used for that file.
+If no \*o is found but an \*o can be created,
+the suffixes are tried in order
+to determine the new \*o's name.
+The default for
+.IR suffixes
+is installation-dependent; normally it is
+.B ,v/
+for hosts like Unix that permit commas in file names,
+and is empty (i.e. just the empty suffix) for other hosts.
+.TP
+.BI \-z zone
+specifies the date output format in keyword substitution,
+and specifies the default time zone for
+.I date
+in the
+.BI \-d date
+option.
+The
+.I zone
+should be empty, a numeric \*u offset, or the special string
+.B LT
+for local time.
+The default is an empty
+.IR zone ,
+which uses the traditional \*r format of \*u without any time zone indication
+and with slashes separating the parts of the date;
+otherwise, times are output in \*i 8601 format with time zone indication.
+For example, if local time is January 11, 1990, 8pm Pacific Standard Time,
+eight hours west of \*u,
+then the time is output as follows:
+.RS
+.LP
+.RS
+.nf
+.ta \w'\f3\-z+05:30\fP  'u +\w'\f31990-01-11 09:30:00+05:30\fP  'u
+.ne 4
+\f2option\fP	\f2time output\fP
+\f3\-z\fP	\f31990/01/12 04:00:00\fP	\f2(default)\fP
+\f3\-zLT\fP	\f31990-01-11 20:00:00\-08\fP
+\f3\-z+05:30\fP	\f31990-01-12 09:30:00+05:30\fP
+.ta 4n +4n +4n +4n
+.fi
+.RE
+.LP
+The
+.B \-z
+option does not affect dates stored in \*os,
+which are always \*u.
+.SH "FILE NAMING"
+Pairs of \*os and working files can be specified in three ways
+(see also the
+example section).
+.PP
+1) Both the \*o and the working file are given.
+The \*o name is of the form
+.IB frag1 / workfileX
+and the working file name is of the form
+.IB frag2 / workfile
+where
+.IB frag1 /
+and
+.IB frag2 /
+are (possibly different or empty) file names,
+.I workfile
+is a file name, and
+.I X
+is an \*r suffix.
+If
+.I X
+is empty,
+.IB frag1 /
+must start with
+.B RCS/
+or must contain
+.BR /RCS/ .
+.PP
+2) Only the \*o is given.
+Then the working file is created in the current
+directory and its name is derived from the \*o name
+by removing
+.IB frag1 /
+and the suffix
+.IR X .
+.PP
+3) Only the working file is given.
+Then
+.B ci
+considers each \*r suffix
+.I X
+in turn, looking for an \*o of the form
+.IB frag2 /RCS/ workfileX
+or (if the former is not found and
+.I X
+is nonempty)
+.IB frag2 / workfileX.
+.PP
+If the \*o is specified without a file name in 1) and 2),
+.B ci
+looks for the \*o first in the directory
+.B ./RCS
+and then in the current
+directory.
+.PP
+.B ci
+reports an error if an attempt to open an \*o fails for an unusual reason,
+even if the \*o's name is just one of several possibilities.
+For example, to suppress use of \*r commands in a directory
+.IR d ,
+create a regular file named
+.IB d /RCS
+so that casual attempts to use \*r commands in
+.I d
+fail because
+.IB d /RCS
+is not a directory.
+.SH EXAMPLES
+Suppose
+.B ,v
+is an \*r suffix and the current directory contains a subdirectory
+.B RCS
+with an \*o
+.BR io.c,v .
+Then each of the following commands check in a copy of
+.B io.c
+into
+.B RCS/io.c,v
+as the latest revision, removing
+.BR io.c .
+.LP
+.RS
+.nf
+.ft 3
+ci  io.c;    ci  RCS/io.c,v;   ci  io.c,v;
+ci  io.c  RCS/io.c,v;    ci  io.c  io.c,v;
+ci  RCS/io.c,v  io.c;    ci  io.c,v  io.c;
+.ft
+.fi
+.RE
+.PP
+Suppose instead that the empty suffix
+is an \*r suffix and the current directory contains a subdirectory
+.B RCS
+with an \*o
+.BR io.c .
+The each of the following commands checks in a new revision.
+.LP
+.RS
+.nf
+.ft 3
+ci  io.c;    ci  RCS/io.c;
+ci  io.c  RCS/io.c;
+ci  RCS/io.c  io.c;
+.ft
+.fi
+.RE
+.SH "FILE MODES"
+An \*o created by
+.B ci
+inherits the read and execute permissions
+from the working file.  If the \*o exists already,
+.B ci
+preserves its read and execute permissions.
+.B ci
+always turns off all write permissions of \*os.
+.SH FILES
+Temporary files are created in the directory containing
+the working file, and also in the temporary directory (see
+.B \s-1TMPDIR\s0
+under
+.BR \s-1ENVIRONMENT\s0 ).
+A semaphore file or files are created in the directory containing the \*o.
+With a nonempty suffix, the semaphore names begin with
+the first character of the suffix; therefore, do not specify an suffix
+whose first character could be that of a working file name.
+With an empty suffix, the semaphore names end with
+.B _
+so working file names should not end in
+.BR _ .
+.PP
+.B ci
+never changes an \*o or working file.
+Normally,
+.B ci
+unlinks the file and creates a new one;
+but instead of breaking a chain of one or more symbolic links to an \*o,
+it unlinks the destination file instead.
+Therefore,
+.B ci
+breaks any hard or symbolic links to any working file it changes;
+and hard links to \*os are ineffective,
+but symbolic links to \*os are preserved.
+.PP
+The effective user must be able to
+search and write the directory containing the \*o.
+Normally, the real user must be able to
+read the \*r and working files
+and to search and write the directory containing the working file;
+however, some older hosts
+cannot easily switch between real and effective users,
+so on these hosts the effective user is used for all accesses.
+The effective user is the same as the real user
+unless your copies of
+.B ci
+and
+.B co
+have setuid privileges.
+As described in the next section,
+these privileges yield extra security if
+the effective user owns all \*os and directories,
+and if only the effective user can write \*r directories.
+.PP
+Users can control access to \*os by setting the permissions
+of the directory containing the files; only users with write access
+to the directory can use \*r commands to change its \*os.
+For example, in hosts that allow a user to belong to several groups,
+one can make a group's \*r directories writable to that group only.
+This approach suffices for informal projects,
+but it means that any group member can arbitrarily change the group's \*os,
+and can even remove them entirely.
+Hence more formal projects sometimes distinguish between an \*r administrator,
+who can change the \*os at will, and other project members,
+who can check in new revisions but cannot otherwise change the \*os.
+.SH "SETUID USE"
+To prevent anybody but their \*r administrator from deleting revisions,
+a set of users can employ setuid privileges as follows.
+.nr n \w'\(bu'+2n-1/1n
+.ds n \nn
+.if \n(.g .if r an-tag-sep .ds n \w'\(bu'u+\n[an-tag-sep]u
+.IP \(bu \*n
+Check that the host supports \*r setuid use.
+Consult a trustworthy expert if there are any doubts.
+It is best if the
+.B seteuid
+system call works as described in Posix 1003.1a Draft 5,
+because \*r can switch back and forth easily
+between real and effective users, even if the real user is
+.BR root .
+If not, the second best is if the
+.B setuid
+system call supports saved setuid
+(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
+this fails only if the real or effective user is
+.BR root .
+If \*r detects any failure in setuid, it quits immediately.
+.IP \(bu \nn
+Choose a user
+.I A
+to serve as \*r administrator for the set of users.
+Only
+.I A
+can invoke the
+.B rcs
+command on the users' \*os.
+.I A
+should not be
+.B root
+or any other user with special powers.
+Mutually suspicious sets of users should use different administrators.
+.IP \(bu \nn
+Choose a file name
+.I B
+to be a directory of files to be executed by the users.
+.IP \(bu \nn
+Have
+.I A
+set up
+.I B
+to contain copies of
+.B ci
+and
+.B co
+that are setuid to
+.I A
+by copying the commands from their standard installation directory
+.I D
+as follows:
+.LP
+.RS
+.nf
+.ne 3
+\f3mkdir\fP  \f2B\fP
+\f3cp\fP  \f2D\fP\^\f3/c[io]\fP  \f2B\fP
+\f3chmod  go\-w,u+s\fP  \f2B\fP\f3/c[io]\fP
+.fi
+.RE
+.IP \(bu \nn
+Have each user prepend
+.I B
+to their command search path as follows:
+.LP
+.RS
+.nf
+.ne 2
+\f3PATH=\fP\f2B\fP\f3:$PATH;  export  PATH\fP  # ordinary shell
+\f3set  path=(\fP\f2B\fP  \f3$path)\fP  # C shell
+.fi
+.RE
+.IP \(bu \nn
+Have
+.I A
+create each \*r directory
+.I R
+with write access only to
+.I A
+as follows:
+.LP
+.RS
+.nf
+.ne 2
+\f3mkdir\fP  \f2R\fP
+\f3chmod  go\-w\fP  \f2R\fP
+.fi
+.RE
+.IP \(bu \nn
+If you want to let only certain users read the \*os,
+put the users into a group
+.IR G ,
+and have
+.I A
+further protect the \*r directory as follows:
+.LP
+.RS
+.nf
+.ne 2
+\f3chgrp\fP  \f2G  R\fP
+\f3chmod  g\-w,o\-rwx\fP  \f2R\fP
+.fi
+.RE
+.IP \(bu \nn
+Have
+.I A
+copy old \*os (if any) into
+.IR R ,
+to ensure that
+.I A
+owns them.
+.IP \(bu \nn
+An \*o's access list limits who can check in and lock revisions.
+The default access list is empty,
+which grants checkin access to anyone who can read the \*o.
+If you want limit checkin access,
+have
+.I A
+invoke
+.B "rcs\ \-a"
+on the file; see
+.BR rcs (1).
+In particular,
+.BI "rcs\ \-e\ \-a" A
+limits access to just
+.IR A .
+.IP \(bu \nn
+Have
+.I A
+initialize any new \*os with
+.B "rcs\ \-i"
+before initial checkin, adding the
+.B \-a
+option if you want to limit checkin access.
+.IP \(bu \nn
+Give setuid privileges only to
+.BR ci ,
+.BR co ,
+and
+.BR rcsclean ;
+do not give them to
+.B rcs
+or to any other command.
+.IP \(bu \nn
+Do not use other setuid commands to invoke \*r commands;
+setuid is trickier than you think!
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+For each revision,
+.B ci
+prints the \*o, the working file, and the number
+of both the deposited and the preceding revision.
+The exit status is zero if and only if all operations were successful.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR co (1),
+.BR emacs (1),
+.BR ident (1),
+.BR make (1),
+.BR rcs (1),
+.BR rcsclean (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rlog (1),
+.BR setuid (2),
+.BR rcsfile (5).
+.PP
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
diff --git a/upstream/mageia-cauldron/man1/cifsiostat.1 b/upstream/mageia-cauldron/man1/cifsiostat.1
new file mode 100644
index 00000000..08c71fee
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cifsiostat.1
@@ -0,0 +1,152 @@
+.\" cifsiostat manual page - (C) 2020 Sebastien Godard (sysstat <at> orange.fr)
+.TH CIFSIOSTAT 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+cifsiostat \- Report CIFS statistics.
+
+.SH SYNOPSIS
+.ie 'yes'no' \{
+.B cifsiostat [ -h ] [ -k | -m ] [ -t ] [ -V ] [ --debuginfo ] [ --dec={ 0 | 1 | 2 } ] [ --human ] [ --pretty ] [
+.IB "interval " "[ " "count " "] ]"
+.\}
+.el \{
+.B cifsiostat [ -h ] [ -k | -m ] [ -t ] [ -V ] [ --dec={ 0 | 1 | 2 } ] [ --human ] [ --pretty ] [
+.IB "interval " "[ " "count " "] ]"
+.\}
+
+.SH DESCRIPTION
+The
+.B cifsiostat
+command displays statistics about read and write operations
+on CIFS filesystems.
+.PP
+.RI "The " "interval"
+parameter specifies the amount of time in seconds between
+each report. The first report contains statistics for the time since
+system startup (boot). Each subsequent report contains statistics
+collected during the interval since the previous report.
+A report consists of a CIFS header row followed by
+a line of statistics for each CIFS filesystem that is mounted.
+.RI "The " "count " "parameter can be specified in conjunction with the " "interval "
+.RI "parameter. If the " "count " "parameter is specified, the value of " "count "
+.RI "determines the number of reports generated at " "interval " "seconds apart. If the " "interval "
+.RI "parameter is specified without the " "count " "parameter, the "
+.BR "cifsiostat " "command generates reports continuously."
+
+.SH REPORT
+The CIFS report provides statistics for each mounted CIFS filesystem.
+The report shows the following fields:
+
+.IP Filesystem:
+This columns shows the mount point of the CIFS filesystem.
+.IP "rB/s (rkB/s, rMB/s)"
+Indicate the average number of bytes (kilobytes, megabytes) read per second.
+.IP "wB/s (wkB/s, wMB/s)"
+Indicate the average number of bytes (kilobytes, megabytes) written per second.
+.IP rop/s
+Indicate the number of 'read' operations that were issued to the filesystem
+per second.
+.IP wop/s
+Indicate the number of 'write' operations that were issued to the filesystem
+per second.
+.IP fo/s
+Indicate the number of open files per second.
+.IP fc/s
+Indicate the number of closed files per second.
+.IP fd/s
+Indicate the number of deleted files per second.
+
+.SH OPTIONS
+.if 'yes'no' \{
+.TP
+.B --debuginfo
+Print debug output to stderr.
+.\}
+.TP
+.B --dec={ 0 | 1 | 2 }
+Specify the number of decimal places to use (0 to 2, default value is 2).
+.TP
+.B -h
+This option is equivalent to specifying
+.BR "--human --pretty" "."
+.TP
+.B --human
+Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
+The units displayed with this option supersede any other default units (e.g.
+kilobytes, sectors...) associated with the metrics.
+.TP
+.B -k
+Display statistics in kilobytes per second.
+.TP
+.B -m
+Display statistics in megabytes per second.
+.TP
+.B --pretty
+Make the CIFS report easier to read by a human.
+.TP
+.B -t
+Print the time for each report displayed. The timestamp format may depend
+on the value of the
+.BR "S_TIME_FORMAT " "environment variable (see below)."
+.TP
+.B -V
+Print version number then exit.
+
+.SH ENVIRONMENT
+.RB "The " "cifsiostat " "command takes into account the following environment variables: "
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.BR "never" ", " "always " "or " "auto " "(the latter is equivalent to the default settings)."
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "I=32;22:N=34;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B I=
+SGR substring for filesystem names.
+.TP
+.B N=
+SGR substring for non-zero statistics values.
+.TP
+.B Z=
+SGR substring for zero values.
+.RE
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.B ISO
+then the current locale will be ignored when printing the date in the report
+header. The
+.B cifsiostat
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+.RB "The timestamp displayed with option " "-t " "will also be compliant with ISO 8601 format."
+
+.SH BUG
+.IR "/proc " "filesystem must be mounted for"
+.BR "cifsiostat " "to work."
+.PP
+.RB "Although " "cifsiostat"
+speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
+A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
+
+.SH FILE
+.IR "/proc/fs/cifs/Stats " "contains CIFS statistics."
+
+.SH AUTHORS
+Written by Ivana Varekova (varekova <at> redhat.com)
+.br
+Maintained by Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "iostat" "(1),"
+.BR "tapestat" "(1), " "nfsiostat" "(1)"
+
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/cistopbm.1 b/upstream/mageia-cauldron/man1/cistopbm.1
new file mode 100644
index 00000000..2bd444b4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cistopbm.1
@@ -0,0 +1,71 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Cistopbm User Manual" 0 "13 August 2020" "netpbm documentation"
+
+.SH NAME
+cistopbm - convert Compuserve RLE image to PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBcistopbm\fP 
+[\fB-i\fP]
+[\fIcisfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBcistopbm\fP reads a Compuserve RLE file as input.
+and produces a PBM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBcistopbm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-i\fP
+Inverse: Reverse the mapping of foreground/background to black/white.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtocis" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.UR https://web.archive.org/web/20140721001738/staticweb.rasip.fer.hr/research/compress/algorithms_run-length_coding.htm
+CompuServe RLE file format
+.UE
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBcistopbm\fP was new in Netpbm 10.48 (September 2009).
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2009 John Elliot <jce@seasip.demon.co.uk>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/cistopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/cksum.1 b/upstream/mageia-cauldron/man1/cksum.1
new file mode 100644
index 00000000..bd8059a7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cksum.1
@@ -0,0 +1,114 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CKSUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+cksum \- compute and verify file checksums
+.SH SYNOPSIS
+.B cksum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or verify checksums.
+By default use the 32 bit CRC algorithm.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-algorithm\fR=\fI\,TYPE\/\fR
+select the digest type to use.  See DIGEST below.
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-l\fR, \fB\-\-length\fR=\fI\,BITS\/\fR
+digest length in bits; must not exceed the max for
+the blake2 algorithm and must be a multiple of 8
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum (the default)
+.TP
+\fB\-\-untagged\fR
+create a reversed style checksum, without digest type
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-debug\fR
+indicate which implementation used
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SS "DIGEST determines the digest algorithm and default output format:"
+.TP
+sysv
+(equivalent to sum \fB\-s\fR)
+.TP
+bsd
+(equivalent to sum \fB\-r\fR)
+.TP
+crc
+(equivalent to cksum)
+.TP
+md5
+(equivalent to md5sum)
+.TP
+sha1
+(equivalent to sha1sum)
+.TP
+sha224
+(equivalent to sha224sum)
+.TP
+sha256
+(equivalent to sha256sum)
+.TP
+sha384
+(equivalent to sha384sum)
+.TP
+sha512
+(equivalent to sha512sum)
+.TP
+blake2b
+(equivalent to b2sum)
+.TP
+sm3
+(only available through cksum)
+.PP
+When checking, the input should be a former output of this program,
+or equivalent standalone program.
+.SH AUTHOR
+Written by Padraig Brady and Q. Frank Xia.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/cksum>
+.br
+or available locally via: info \(aq(coreutils) cksum invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/clear.1 b/upstream/mageia-cauldron/man1/clear.1
new file mode 100644
index 00000000..c034b0ea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/clear.1
@@ -0,0 +1,186 @@
+.\"***************************************************************************
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: clear.1,v 1.46 2023/12/16 20:32:22 tom Exp $
+.TH clear 1 2023-12-16 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds '  \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.ie t .ds '  \(aq
+.el   .ds '  '
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.
+.SH NAME
+\fB\%clear\fP \-
+clear the terminal screen
+.SH SYNOPSIS
+.B clear
+.RB [ \-x ]
+.RB [ \-T\ \c
+.IR terminal-type ]
+.PP
+.B "clear \-V"
+.SH DESCRIPTION
+\fB\%clear\fP clears your terminal's screen and its scrollback buffer,
+if any.
+\fB\%clear\fP retrieves the terminal type from the environment
+variable \fITERM\fP,
+then consults the \fIterminfo\fP terminal capability database entry for
+that type to determine how to perform these actions.
+.PP
+The capabilities to clear the screen and scrollback buffer are named
+\*(``clear\*('' and \*(``E3\*('', respectively.
+The latter is a \fIuser-defined capability\fP,
+applying an extension mechanism introduced in \fI\%ncurses\fP 5.0
+(1999).
+.SH OPTIONS
+\fB\%clear\fP recognizes the following options.
+.TP 9 \" "-T type" + 2n
+.B \-T \fItype\fP
+produces instructions suitable for the terminal \fItype\fP.
+Normally,
+this option is unnecessary,
+because the terminal type is inferred from the environment variable
+\fITERM\fP.
+If this option is specified,
+\fB\%clear\fP ignores the environment variables \fILINES\fP and
+\fI\%COLUMNS\fP as well.
+.TP
+.B \-V
+reports the version of \fI\%ncurses\fP associated with this program and
+exits with a successful status.
+.TP
+.B \-x
+prevents \fB\%clear\fP from attempting to clear the scrollback buffer.
+.SH PORTABILITY
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008) nor X/Open Curses Issue 7 documents \fB\%clear\fP.
+.PP
+The latter documents \fBtput\fP,
+which could be used to replace this utility either via a shell script or
+by an alias
+(such as a symbolic link)
+to run \fB\%tput\fP as \fB\%clear\fP.
+.SH HISTORY
+A \fBclear\fP command using the \fItermcap\fP database and library
+appeared in 2BSD (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c
+Eighth Edition Unix (1985) later included it.
+.PP
+The commercial Unix arm of AT&T adapted a different BSD program
+(\fBtset\fP) to make a new command,
+\fBtput\fP,
+and replaced the \fBclear\fP program with a shell script that called
+\*(``\fBtput clear\fP\*(''.
+.PP
+.RS 4
+.EX
+/usr/bin/tput ${1:+\-T$1} clear 2> /dev/null
+exit
+.EE
+.RE
+.PP
+In 1989, when Keith Bostic revised the BSD \fBtput\fP command
+to make it similar to AT&T's \fBtput\fP,
+he added a \fBclear\fP shell script as well.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\
+.\"   tput/clear.sh
+.PP
+.RS 4
+.EX
+exec tput clear
+.EE
+.RE
+.PP
+The remainder of the script in each case is a copyright notice.
+.PP
+In 1995,
+\fI\%ncurses\fP's \fBclear\fP began by adapting BSD's original
+\fBclear\fP command to use \fIterminfo\fP.
+The \fBE3\fP extension came later.
+.bP
+In June 1999, \fIxterm\fP provided an extension to the standard control
+sequence for clearing the screen.
+Rather than clearing just the visible part of the screen using
+.RS 8
+.PP
+.EX
+printf \*'\e033[2J\*'
+.EE
+.RE
+.IP
+one could clear the scrollback buffer as well by using
+.RS 8
+.PP
+.EX
+printf \*'\e033[\fB3\fPJ\*'
+.EE
+.RE
+.IP
+instead.
+\*(``XTerm Control Sequences\fP\*('' documents this feature as
+originating with \fIxterm\fP.
+.bP
+A few other terminal emulators adopted it,
+such as PuTTY in 2006.
+.bP
+In April 2011, a Red Hat developer submitted a patch to the Linux
+kernel, modifying its console driver to do the same thing.
+Documentation of this change,
+appearing in Linux 3.0,
+did not mention \fIxterm\fP,
+although that program was cited in the Red Hat bug report (#683733)
+motivating the feature.
+.bP
+Subsequently,
+more terminal developers adopted the feature.
+The next relevant step was to change the \fI\%ncurses\fP \fBclear\fP
+program in 2013 to incorporate this extension.
+.bP
+In 2013,
+the \fBE3\fP capability was not exercised by
+\*(``\fB\%tput clear\fP\*(''.
+That oversight was addressed in 2016 by reorganizing \fB\%tput\fP to
+share its logic with \fB\%clear\fP and \fB\%tset\fP.
+.SH SEE ALSO
+\fB\%tput\fP(1),
+\fB\%xterm\fP(1),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/cmp.1 b/upstream/mageia-cauldron/man1/cmp.1
new file mode 100644
index 00000000..a9ea06a6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cmp.1
@@ -0,0 +1,76 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.4.
+.TH CMP "1" "May 2023" "diffutils 3.10" "User Commands"
+.SH NAME
+cmp \- compare two files byte by byte
+.SH SYNOPSIS
+.B cmp
+[\fIOPTION\fR]... \fIFILE1 \fR[\fIFILE2 \fR[\fISKIP1 \fR[\fISKIP2\fR]]]
+.SH DESCRIPTION
+Compare two files byte by byte.
+.PP
+The optional SKIP1 and SKIP2 specify the number of bytes to skip
+at the beginning of each file (zero by default).
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-print\-bytes\fR
+print differing bytes
+.TP
+\fB\-i\fR, \fB\-\-ignore\-initial\fR=\fISKIP\fR
+skip first SKIP bytes of both inputs
+.TP
+\fB\-i\fR, \fB\-\-ignore\-initial\fR=\fISKIP1\fR:SKIP2
+skip first SKIP1 bytes of FILE1 and
+first SKIP2 bytes of FILE2
+.TP
+\fB\-l\fR, \fB\-\-verbose\fR
+output byte numbers and differing byte values
+.TP
+\fB\-n\fR, \fB\-\-bytes\fR=\fILIMIT\fR
+compare at most LIMIT bytes
+.TP
+\fB\-s\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+suppress all normal output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+output version information and exit
+.PP
+SKIP values may be followed by the following multiplicative suffixes:
+kB 1000, K 1024, MB 1,000,000, M 1,048,576,
+GB 1,000,000,000, G 1,073,741,824, and so on for T, P, E, Z, Y.
+.PP
+If a FILE is '\-' or missing, read standard input.
+Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
+.SH AUTHOR
+Written by Torbjorn Granlund and David MacKenzie.
+.SH "REPORTING BUGS"
+Report bugs to: bug\-diffutils@gnu.org
+.br
+GNU diffutils home page: <https://www.gnu.org/software/diffutils/>
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR diff (1),
+.BR diff3 (1),
+.BR sdiff (1)
+.PP
+The full documentation for
+.B cmp
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B cmp
+programs are properly installed at your site, the command
+.IP
+.B info cmp
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/cmuwmtopbm.1 b/upstream/mageia-cauldron/man1/cmuwmtopbm.1
new file mode 100644
index 00000000..0ccc16f7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cmuwmtopbm.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Cmuwmtopbm User Manual" 0 "15 April 1989" "netpbm documentation"
+
+.SH NAME
+cmuwmtopbm - convert a CMU window manager bitmap into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBcmuwmtopbm\fP
+[\fIcmuwmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBcmuwmtopbm\fP reads a CMU window manager bitmap as input.  and
+produces a PBM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBcmuwmtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtocmuwm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/cmuwmtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/co.1 b/upstream/mageia-cauldron/man1/co.1
new file mode 100644
index 00000000..82ee5143
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/co.1
@@ -0,0 +1,805 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH CO 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+co \- check out RCS revisions
+.SH SYNOPSIS
+.B co
+.RI [ options ] " file " .\|.\|.
+.SH DESCRIPTION
+.B co
+retrieves a revision from each \*o and stores it into
+the corresponding working file.
+.PP
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+Names are paired as explained in
+.BR ci (1).
+.PP
+Revisions of an \*o can be checked out locked or unlocked.  Locking a
+revision prevents overlapping updates.  A revision checked out for reading or
+processing (e.g., compiling) need not be locked.  A revision checked out
+for editing and later checkin must normally be locked.  Checkout with locking
+fails if the revision to be checked out is currently locked by another user.
+(A lock can be broken with
+.BR rcs "(1).)\ \&"
+Checkout with locking also requires the caller to be on the access list of
+the \*o, unless he is the owner of the
+file or the superuser, or the access list is empty.
+Checkout without locking is not subject to accesslist restrictions, and is
+not affected by the presence of locks.
+.PP
+A revision is selected by options for revision or branch number,
+checkin date/time, author, or state.
+When the selection options
+are applied in combination,
+.B co
+retrieves the latest revision
+that satisfies all of them.
+If none of the selection options
+is specified,
+.B co
+retrieves the latest revision
+on the default branch (normally the trunk, see the
+.B \-b
+option of
+.BR rcs (1)).
+A revision or branch number can be attached
+to any of the options
+.BR \-f ,
+.BR \-I ,
+.BR \-l ,
+.BR \-M ,
+.BR \-p ,
+.BR \-q ,
+.BR \-r ,
+or
+.BR \-u .
+The options
+.B \-d
+(date),
+.B \-s
+(state), and
+.B \-w
+(author)
+retrieve from a single branch, the
+.I selected
+branch,
+which is either specified by one of
+.BR \-f ,
+\&.\|.\|.,
+.BR \-u ,
+or the default branch.
+.PP
+A
+.B co
+command applied to an \*o
+with no revisions creates a zero-length working file.
+.B co
+always performs keyword substitution (see below).
+.SH OPTIONS
+.TP
+.BR \-r [\f2rev\fP]
+retrieves the latest revision whose number is less than or equal to
+.IR rev .
+If
+.I rev
+indicates a branch rather than a revision,
+the latest revision on that branch is retrieved.
+If
+.I rev
+is omitted, the latest revision on the default branch
+(see the
+.B \-b
+option of
+.BR rcs (1))
+is retrieved.
+If
+.I rev
+is
+.BR $ ,
+.B co
+determines the revision number from keyword values in the working file.
+Otherwise, a revision is composed of one or more numeric or symbolic fields
+separated by periods.
+If
+.I rev
+begins with a period,
+then the default branch (normally the trunk) is prepended to it.
+If
+.I rev
+is a branch number followed by a period,
+then the latest revision on that branch is used.
+The numeric equivalent of a symbolic field
+is specified with the
+.B \-n
+option of the commands
+.BR ci (1)
+and
+.BR rcs (1).
+.TP
+.BR \-l [\f2rev\fP]
+same as
+.BR \-r ,
+except that it also locks the retrieved revision for
+the caller.
+.TP
+.BR \-u [\f2rev\fP]
+same as
+.BR \-r ,
+except that it unlocks the retrieved revision if it was
+locked by the caller.  If
+.I rev
+is omitted,
+.B \-u
+retrieves the revision locked by the caller, if there is one; otherwise,
+it retrieves the latest revision on the default branch.
+.TP
+.BR \-f [\f2rev\fP]
+forces the overwriting of the working file;
+useful in connection with
+.BR \-q .
+See also
+.SM "FILE MODES"
+below.
+.TP
+.B \-kkv
+Generate keyword strings using the default form, e.g.\&
+.B "$\&Revision: \*(Rv $"
+for the
+.B Revision
+keyword.
+A locker's name is inserted in the value of the
+.BR Header ,
+.BR Id ,
+and
+.B Locker
+keyword strings
+only as a file is being locked,
+i.e. by
+.B "ci\ \-l"
+and
+.BR "co\ \-l".
+This is the default.
+.TP
+.B \-kkvl
+Like
+.BR \-kkv ,
+except that a locker's name is always inserted
+if the given revision is currently locked.
+.TP
+.B \-kk
+Generate only keyword names in keyword strings; omit their values.
+See
+.SM "KEYWORD SUBSTITUTION"
+below.
+For example, for the
+.B Revision
+keyword, generate the string
+.B $\&Revision$
+instead of
+.BR "$\&Revision: \*(Rv $" .
+This option is useful to ignore differences due to keyword substitution
+when comparing different revisions of a file.
+Log messages are inserted after
+.B $\&Log$
+keywords even if
+.B \-kk
+is specified,
+since this tends to be more useful when merging changes.
+.TP
+.B \-ko
+Generate the old keyword string,
+present in the working file just before it was checked in.
+For example, for the
+.B Revision
+keyword, generate the string
+.B "$\&Revision: 1.1 $"
+instead of
+.B "$\&Revision: \*(Rv $"
+if that is how the string appeared when the file was checked in.
+This can be useful for file formats
+that cannot tolerate any changes to substrings
+that happen to take the form of keyword strings.
+.TP
+.B \-kb
+Generate a binary image of the old keyword string.
+This acts like
+.BR \-ko ,
+except it performs all working file input and output in binary mode.
+This makes little difference on Posix and Unix hosts,
+but on DOS-like hosts one should use
+.B "rcs\ \-i\ \-kb"
+to initialize an \*o intended to be used for binary files.
+Also, on all hosts,
+.BR rcsmerge (1)
+normally refuses to merge files when
+.B \-kb
+is in effect.
+.TP
+.B \-kv
+Generate only keyword values for keyword strings.
+For example, for the
+.B Revision
+keyword, generate the string
+.B \*(Rv
+instead of
+.BR "$\&Revision: \*(Rv $" .
+This can help generate files in programming languages where it is hard to
+strip keyword delimiters like
+.B "$\&Revision:\ $"
+from a string.
+However, further keyword substitution cannot be performed once the
+keyword names are removed, so this option should be used with care.
+Because of this danger of losing keywords,
+this option cannot be combined with
+.BR \-l ,
+and the owner write permission of the working file is turned off;
+to edit the file later, check it out again without
+.BR \-kv .
+.TP
+.BR \-p [\f2rev\fP]
+prints the retrieved revision on the standard output rather than storing it
+in the working file.
+This option is useful when
+.B co
+is part of a pipe.
+.TP
+.BR \-q [\f2rev\fP]
+quiet mode; diagnostics are not printed.
+.TP
+.BR \-I [\f2rev\fP]
+interactive mode;
+the user is prompted and questioned
+even if the standard input is not a terminal.
+.TP
+.BI \-d date
+retrieves the latest revision on the selected branch whose checkin date/time is
+less than or equal to
+.IR date .
+The date and time can be given in free format.
+The time zone
+.B LT
+stands for local time;
+other common time zone names are understood.
+For example, the following
+.IR date s
+are equivalent
+if local time is January 11, 1990, 8pm Pacific Standard Time,
+eight hours west of Coordinated Universal Time (\*u):
+.RS
+.LP
+.RS
+.nf
+.ta \w'\f3Thu, 11 Jan 1990 20:00:00 \-0800\fP  'u
+.ne 10
+\f38:00 pm lt\fP
+\f34:00 AM, Jan. 12, 1990\fP	default is \*u
+\f31990-01-12 04:00:00+00\fP	\*i 8601 (\*u)
+\f31990-01-11 20:00:00\-08\fP	\*i 8601 (local time)
+\f31990/01/12 04:00:00\fP	traditional \*r format
+\f3Thu Jan 11 20:00:00 1990 LT\fP	output of \f3ctime\fP(3) + \f3LT\fP
+\f3Thu Jan 11 20:00:00 PST 1990\fP	output of \f3date\fP(1)
+\f3Fri Jan 12 04:00:00 GMT 1990\fP
+\f3Thu, 11 Jan 1990 20:00:00 \-0800\fP	Internet RFC 822
+\f312-January-1990, 04:00 WET\fP
+.ta 4n +4n +4n +4n
+.fi
+.RE
+.LP
+Most fields in the date and time can be defaulted.
+The default time zone is normally \*u, but this can be overridden by the
+.B \-z
+option.
+The other defaults are determined in the order year, month, day,
+hour, minute, and second (most to least significant).  At least one of these
+fields must be provided.  For omitted fields that are of higher significance
+than the highest provided field, the time zone's current values are assumed.
+For all other omitted fields,
+the lowest possible values are assumed.
+For example, without
+.BR \-z ,
+the date
+.B "20, 10:30"
+defaults to
+10:30:00 \*u of the 20th of the \*u time zone's current month and year.
+The date/time must be quoted if it contains spaces.
+.RE
+.TP
+.BR \-M [\f2rev\fP]
+Set the modification time on the new working file
+to be the date of the retrieved revision.
+Use this option with care; it can confuse
+.BR make (1).
+.TP
+.BI \-s state
+retrieves the latest revision on the selected branch whose state is set to
+.IR state .
+.TP
+.BI \-S
+Enable
+.I self-same
+mode.
+In this mode, the owner of a lock is unimportant, just that it exists.
+Effectively, this means the user cannot check out the same revision twice.
+.TP
+.B \-T
+Preserve the modification time on the \*o
+even if the \*o changes because a lock is added or removed.
+This option can suppress extensive recompilation caused by a
+.BR make (1)
+dependency of some other copy of the working file on the \*o.
+Use this option with care; it can suppress recompilation even when it is needed,
+i.e. when the change of lock
+would mean a change to keyword strings in the other working file.
+.TP
+.BR \-w [\f2login\fP]
+retrieves the latest revision on the selected branch which was checked in
+by the user with login name
+.IR login .
+If the argument
+.I login
+is
+omitted, the caller's login is assumed.
+.TP
+.BI \-j joinlist
+generates a new revision which is the join of the revisions on
+.IR joinlist .
+This option is largely obsoleted by
+.BR rcsmerge (1)
+but is retained for backwards compatibility.
+.RS
+.PP
+The
+.I joinlist
+is a comma-separated list of pairs of the form
+.IB rev2 : rev3,
+where
+.I rev2
+and
+.I rev3
+are (symbolic or numeric)
+revision numbers.
+For the initial such pair,
+.I rev1
+denotes the revision selected
+by the above options
+.BR \-f ,
+\&.\|.\|.,
+.BR \-w .
+For all other pairs,
+.I rev1
+denotes the revision generated by the previous pair.
+(Thus, the output
+of one join becomes the input to the next.)
+.PP
+For each pair,
+.B co
+joins revisions
+.I rev1
+and
+.I rev3
+with respect to
+.IR rev2 .
+This means that all changes that transform
+.I rev2
+into
+.I rev1
+are applied to a copy of
+.IR rev3 .
+This is particularly useful if
+.I rev1
+and
+.I rev3
+are the ends of two branches that have
+.I rev2
+as a common ancestor.  If
+.IR rev1 < rev2 < rev3
+on the same branch,
+joining generates a new revision which is like
+.I rev3,
+but with all changes that lead from
+.I rev1
+to
+.I rev2
+undone.
+If changes from
+.I rev2
+to
+.I rev1
+overlap with changes from
+.I rev2
+to
+.I rev3,
+.B co
+reports overlaps as described in
+.BR merge (1).
+.PP
+For the initial pair,
+.I rev2
+can be omitted.  The default is the common
+ancestor.
+If any of the arguments indicate branches, the latest revisions
+on those branches are assumed.
+The options
+.B \-l
+and
+.B \-u
+lock or unlock
+.IR rev1 .
+.RE
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.I n,
+where
+.I n
+can be
+.BR 3 ,
+.BR 4 ,
+or
+.BR 5 .
+This can be useful when interchanging \*os with others who are
+running older versions of \*r.
+To see which version of \*r your correspondents are running, have them invoke
+.BR "rcs \-V" ;
+this works with newer versions of \*r.
+If it doesn't work, have them invoke
+.B rlog
+on an \*o;
+if none of the first few lines of output contain the string
+.B branch:
+it is version 3;
+if the dates' years have just two digits, it is version 4;
+otherwise, it is version 5.
+An \*o generated while emulating version 3 loses its default branch.
+An \*r revision generated while emulating version 4 or earlier has
+a time stamp that is off by up to 13 hours.
+A revision extracted while emulating version 4 or earlier contains
+abbreviated dates of the form
+.IB yy / mm / dd
+and can also contain different white space and line prefixes
+in the substitution for
+.BR $\&Log$ .
+.TP
+.BI \-x "suffixes"
+Use
+.I suffixes
+to characterize \*os.
+See
+.BR ci (1)
+for details.
+.TP
+.BI \-z zone
+specifies the date output format in keyword substitution,
+and specifies the default time zone for
+.I date
+in the
+.BI \-d date
+option.
+The
+.I zone
+should be empty, a numeric \*u offset, or the special string
+.B LT
+for local time.
+The default is an empty
+.IR zone ,
+which uses the traditional \*r format of \*u without any time zone indication
+and with slashes separating the parts of the date;
+otherwise, times are output in \*i 8601 format with time zone indication.
+For example, if local time is January 11, 1990, 8pm Pacific Standard Time,
+eight hours west of \*u,
+then the time is output as follows:
+.RS
+.LP
+.RS
+.nf
+.ta \w'\f3\-z+05:30\fP  'u +\w'\f31990-01-11 09:30:00+05:30\fP  'u
+.ne 4
+\f2option\fP	\f2time output\fP
+\f3\-z\fP	\f31990/01/12 04:00:00\fP	\f2(default)\fP
+\f3\-zLT\fP	\f31990-01-11 20:00:00\-08\fP
+\f3\-z+05:30\fP	\f31990-01-12 09:30:00+05:30\fP
+.ta 4n +4n +4n +4n
+.fi
+.RE
+.LP
+The
+.B \-z
+option does not affect dates stored in \*os,
+which are always \*u.
+.RE
+.SH "KEYWORD SUBSTITUTION"
+Strings of the form
+.BI $ keyword $
+and
+.BI $ keyword : .\|.\|. $
+embedded in
+the text are replaced
+with strings of the form
+.BI $ keyword : value $
+where
+.I keyword
+and
+.I value
+are pairs listed below.
+Keywords can be embedded in literal strings
+or comments to identify a revision.
+.PP
+Initially, the user enters strings of the form
+.BI $ keyword $ .
+On checkout,
+.B co
+replaces these strings with strings of the form
+.BI $ keyword : value $ .
+If a revision containing strings of the latter form
+is checked back in, the value fields will be replaced during the next
+checkout.
+Thus, the keyword values are automatically updated on checkout.
+This automatic substitution can be modified by the
+.B \-k
+options.
+.PP
+Keywords and their corresponding values:
+.TP
+.B $\&Author$
+The login name of the user who checked in the revision.
+.TP
+.B $\&Date$
+The date and time the revision was checked in.
+With
+.BI \-z zone
+a numeric time zone offset is appended; otherwise, the date is \*u.
+.TP
+.B $\&Header$
+A standard header containing the full \*o name, the
+revision number, the date and time, the author, the state,
+and the locker (if locked).
+With
+.BI \-z zone
+a numeric time zone offset is appended to the date; otherwise, the date is \*u.
+.TP
+.B $\&Id$
+Same as
+.BR $\&Header$ ,
+except that the \*o name is without the directory components.
+.TP
+.B $\&Locker$
+The login name of the user who locked the revision (empty if not locked).
+.TP
+.B $\&Log$
+The log message supplied during checkin, preceded by a header
+containing the \*o name, the revision number, the author, and the date
+and time.
+With
+.BI \-z zone
+a numeric time zone offset is appended; otherwise, the date is \*u.
+Existing log messages are
+.I not
+replaced.
+Instead, the new log message is inserted after
+.BR $\&Log: .\|.\|. $ .
+This is useful for
+accumulating a complete change log in a source file.
+.RS
+.LP
+Each inserted line is prefixed by the string that prefixes the
+.B $\&Log$
+line.  For example, if the
+.B $\&Log$
+line is
+.RB \*(lq "//\ $\&Log: tan.cc\ $" \*(rq,
+\*r prefixes each line of the log with
+.RB \*(lq "//\ " \*(rq.
+This is useful for languages with comments that go to the end of the line.
+The convention for other languages is to use a
+.RB \*(lq " \(** " \(rq
+prefix inside a multiline comment.
+For example, the initial log comment of a C program
+conventionally is of the following form:
+.RS
+.LP
+.nf
+.ft 3
+.ne 3
+/\(**
+.in +\w'/'u
+\(** $\&Log$
+\(**/
+.in
+.ft
+.fi
+.RE
+.LP
+For backwards compatibility with older versions of \*r, if the log prefix is
+.B /\(**
+or
+.B (\(**
+surrounded by optional white space, inserted log lines contain a space
+instead of
+.B /
+or
+.BR ( ;
+however, this usage is obsolescent and should not be relied on.
+.RE
+.TP
+.B $\&Name$
+The symbolic name used to check out the revision, if any.
+For example,
+.B "co\ \-rJoe"
+generates
+.BR "$\&Name:\ Joe\ $" .
+Plain
+.B co
+generates just
+.BR "$\&Name:\ \ $" .
+.TP
+.B $\&RCSfile$
+The \*o name without directory components.
+.TP
+.B $\&Revision$
+The revision number assigned to the revision.
+.TP
+.B $\&Source$
+The full \*o name.
+.TP
+.B $\&State$
+The state assigned to the revision with the
+.B \-s
+option of
+.BR rcs (1)
+or
+.BR ci (1).
+.PP
+The following characters in keyword values are represented by escape sequences
+to keep keyword strings well-formed.
+.LP
+.RS
+.nf
+.ne 6
+.ta \w'newline  'u
+\f2char	escape sequence\fP
+tab	\f3\et\fP
+newline	\f3\en\fP
+space	\f3\e040
+$	\e044
+\e	\e\e\fP
+.fi
+.RE
+.SH "FILE MODES"
+The working file inherits the read and execute permissions from the \*r
+file.  In addition, the owner write permission is turned on, unless
+.B \-kv
+is set or the file
+is checked out unlocked and locking is set to strict (see
+.BR rcs (1)).
+.PP
+If a file with the name of the working file exists already and has write
+permission,
+.B co
+aborts the checkout,
+asking beforehand if possible.
+If the existing working file is
+not writable or
+.B \-f
+is given, the working file is deleted without asking.
+.SH FILES
+.B co
+accesses files much as
+.BR ci (1)
+does, except that it does not need to read the working file
+unless a revision number of
+.B $
+is specified.
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+The \*o name, the working file name,
+and the revision number retrieved are
+written to the diagnostic output.
+The exit status is zero if and only if all operations were successful.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR ctime (3),
+.BR date (1),
+.BR ident (1),
+.BR make (1),
+.BR rcs (1),
+.BR rcsclean (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rlog (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
+.SH LIMITS
+Links to the \*r and working files are not preserved.
+.PP
+There is no way to selectively suppress the expansion of keywords, except
+by writing them differently.  In nroff and troff, this is done by embedding the
+null-character
+.B \e&
+into the keyword.
+.br
diff --git a/upstream/mageia-cauldron/man1/comm.1 b/upstream/mageia-cauldron/man1/comm.1
new file mode 100644
index 00000000..964c5c84
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/comm.1
@@ -0,0 +1,76 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH COMM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+comm \- compare two sorted files line by line
+.SH SYNOPSIS
+.B comm
+[\fI\,OPTION\/\fR]... \fI\,FILE1 FILE2\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Compare sorted files FILE1 and FILE2 line by line.
+.PP
+When FILE1 or FILE2 (not both) is \-, read standard input.
+.PP
+With no options, produce three\-column output.  Column one contains
+lines unique to FILE1, column two contains lines unique to FILE2,
+and column three contains lines common to both files.
+.TP
+\fB\-1\fR
+suppress column 1 (lines unique to FILE1)
+.TP
+\fB\-2\fR
+suppress column 2 (lines unique to FILE2)
+.TP
+\fB\-3\fR
+suppress column 3 (lines that appear in both files)
+.TP
+\fB\-\-check\-order\fR
+check that the input is correctly sorted, even
+if all input lines are pairable
+.TP
+\fB\-\-nocheck\-order\fR
+do not check that the input is correctly sorted
+.TP
+\fB\-\-output\-delimiter\fR=\fI\,STR\/\fR
+separate columns with STR
+.TP
+\fB\-\-total\fR
+output a summary
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Note, comparisons honor the rules specified by 'LC_COLLATE'.
+.SH EXAMPLES
+.TP
+comm \-12 file1 file2
+Print only lines present in both file1 and file2.
+.TP
+comm \-3 file1 file2
+Print lines in file1 not in file2, and vice versa.
+.SH AUTHOR
+Written by Richard M. Stallman and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBjoin\fP(1), \fBuniq\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/comm>
+.br
+or available locally via: info \(aq(coreutils) comm invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/compress.1 b/upstream/mageia-cauldron/man1/compress.1
new file mode 100644
index 00000000..79de6ef6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/compress.1
@@ -0,0 +1,294 @@
+.TH COMPRESS 1 local
+.SH NAME
+compress, uncompress, zcat \- compress and expand data
+.SH SYNOPSIS
+.ll +8
+.B compress
+[
+.B \-f
+] [
+.B \-v
+] [
+.B \-c
+] [
+.B \-V
+] [
+.B \-r
+] [
+.B \-b
+.I bits
+] [
+.B \-\-
+] [
+.I "name \&..."
+]
+.ll -8
+.br
+.B uncompress
+[
+.B \-f
+] [
+.B \-v
+] [
+.B \-c
+] [
+.B \-V
+] [
+.B \-\-
+] [
+.I "name \&..."
+]
+.br
+.B zcat
+[
+.B \-V
+] [
+.B \-\-
+] [
+.I "name \&..."
+]
+.SH DESCRIPTION
+.I Compress
+reduces the size of the named files using adaptive Lempel\-Ziv coding.
+Whenever possible,
+each file is replaced by one with the extension
+.B "\&.Z,"
+while keeping the same ownership modes, access and modification times.
+If no files are specified, the standard input is compressed to the
+standard output.
+.I Compress
+will only attempt to compress regular files.
+In particular, it will ignore symbolic links. If a file has multiple
+hard links,
+.I compress
+will refuse to compress it unless the
+.B \-f
+flag is given.
+.PP
+If
+.B \-f
+is not given and
+.I compress
+is run in the foreground,
+the user is prompted as to whether an existing file should be overwritten.
+.PP
+Compressed files can be restored to their original form using
+.I uncompress
+or
+.I zcat.
+.PP
+.I uncompress
+takes a list of files on its command line and replaces each
+file whose name ends with
+.B "\&.Z"
+and which begins with the correct magic number with an uncompressed
+file without the 
+.B "\&.Z."
+The uncompressed file will have the mode, ownership and
+timestamps of the compressed file.
+.PP
+The
+.B \-c
+option makes
+.I compress/uncompress
+write to the standard output; no files are changed.
+.PP
+.I zcat
+is identical to
+.I uncompress
+.B \-c.
+.I zcat
+uncompresses either a list of files on the command line or its
+standard input and writes the uncompressed data on standard output.
+.I zcat
+will uncompress files that have the correct magic number whether
+they have a
+.B "\&.Z"
+suffix or not.
+.PP
+If the
+.B \-r
+flag is specified, 
+.I compress
+will operate recursively. If any of the file names specified on the command
+line are directories, 
+.I compress
+will descend into the directory and compress all the files it finds there.
+.PP
+The
+.B \-V
+flag tells each of these programs to print its version and patchlevel,
+along with any preprocessor flags specified during compilation, on
+stderr before doing any compression or uncompression.
+.PP
+.I Compress
+uses the modified Lempel\-Ziv algorithm popularized in
+"A Technique for High Performance Data Compression",
+Terry A. Welch,
+.I "IEEE Computer,"
+vol. 17, no. 6 (June 1984), pp. 8\-19.
+Common substrings in the file are first replaced by 9\-bit codes 257 and up.
+When code 512 is reached, the algorithm switches to 10\-bit codes and
+continues to use more bits until the
+limit specified by the
+.B \-b
+flag is reached (default 16).
+.I Bits
+must be between 9 and 16.  The default can be changed in the source to allow
+.I compress
+to be run on a smaller machine.
+.PP
+After the
+.I bits
+limit is attained,
+.I compress
+periodically checks the compression ratio.  If it is increasing,
+.I compress
+continues to use the existing code dictionary.  However,
+if the compression ratio decreases,
+.I compress
+discards the table of substrings and rebuilds it from scratch.  This allows
+the algorithm to adapt to the next "block" of the file.
+.PP
+Note that the
+.B \-b
+flag is omitted for
+.I uncompress,
+since the 
+.I bits
+parameter specified during compression
+is encoded within the output, along with
+a magic number to ensure that neither decompression of random data nor
+recompression of compressed data is attempted. 
+.PP
+.ne 8
+The amount of compression obtained depends on the size of the
+input, the number of
+.I bits
+per code, and the distribution of common substrings.
+Typically, text such as source code or English
+is reduced by 50\-60%.
+Compression is generally much better than that achieved by
+Huffman coding (as used in
+.IR pack ),
+or adaptive Huffman coding
+.RI ( compact ),
+and takes less time to compute.
+.PP
+Under the
+.B \-v
+option,
+a message is printed yielding the percentage of
+reduction for each file compressed.
+.PP
+.B \-\-
+may be used to halt option parsing and force all remaining arguments to be
+treated as paths.
+.SH "DIAGNOSTICS"
+Exit status is normally 0;
+if the last file is larger after (attempted) compression, the status is 2;
+if an error occurs, exit status is 1.
+.PP
+Usage: compress [\-dfvcVr] [\-b maxbits] [file ...]
+.in +8
+Invalid options were specified on the command line.
+.in -8
+Missing maxbits
+.in +8
+Maxbits must follow
+.BR \-b \.
+.in -8
+.IR file :
+not in compressed format
+.in +8
+The file specified to
+.I uncompress
+has not been compressed.
+.in -8
+.IR file :
+compressed with 
+.I xx
+bits, can only handle 
+.I yy
+bits
+.in +8
+.I File
+was compressed by a program that could deal with
+more 
+.I bits
+than the compress code on this machine.
+Recompress the file with smaller
+.IR bits \.
+.in -8
+.IR file :
+already has .Z suffix \-\- no change
+.in +8
+The file is assumed to be already compressed.
+Rename the file and try again.
+.in -8
+.IR file :
+filename too long to tack on .Z
+.in +8
+The file cannot be compressed because its name is longer than
+12 characters.
+Rename and try again.
+This message does not occur on BSD systems.
+.in -8
+.I file
+already exists; do you wish to overwrite (y or n)?
+.in +8
+Respond "y" if you want the output file to be replaced; "n" if not.
+.in -8
+uncompress: corrupt input
+.in +8
+A SIGSEGV violation was detected which usually means that the input file has
+been corrupted.
+.in -8
+Compression: 
+.I "xx.xx%"
+.in +8
+Percentage of the input saved by compression.
+(Relevant only for
+.BR \-v \.)
+.in -8
+\-\- not a regular file or directory: ignored
+.in +8
+When the input file is not a regular file or directory,
+(e.g. a symbolic link, socket, FIFO, device file), it is
+left unaltered.
+.in -8
+\-\- has
+.I xx 
+other links: unchanged
+.in +8
+The input file has links; it is left unchanged.  See
+.IR ln "(1)"
+for more information. Use the
+.B \-f
+flag to force compression of multiply\-linked files.
+.in -8
+\-\- file unchanged
+.in +8
+No savings is achieved by
+compression.  The input remains virgin.
+.in -8
+.SH "BUGS"
+Although compressed files are compatible between machines with large memory,
+.BR \-b \12
+should be used for file transfer to architectures with 
+a small process data space (64KB or less, as exhibited by the DEC PDP
+series, the Intel 80286, etc.)
+.PP
+Invoking compress with a 
+.BR \-r
+flag will occasionally cause it to produce spurious error warnings of the form
+.PP
+.in 8
+"<filename>.Z already has .Z suffix \- ignored"
+.in -8
+.PP
+These warnings can be ignored. See the comments in compress42.c:compdir()
+in the source distribution for an explanation.
+.SH "SEE ALSO"
+.BR pack (1),
+.BR compact (1)
diff --git a/upstream/mageia-cauldron/man1/consoletype.1 b/upstream/mageia-cauldron/man1/consoletype.1
new file mode 100644
index 00000000..ebd1d88c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/consoletype.1
@@ -0,0 +1,44 @@
+.TH CONSOLETYPE 1 "Red Hat, Inc" "RH" \" -*- nroff -*-
+.SH NAME
+\fBconsoletype
+\- print type of the console connected to standard input
+.SH SYNOPSIS
+\fBconsoletype [\fIstdout\fR] [\fIfg\fR]
+.SH DESCRIPTION
+\fBconsoletype
+prints the type of console connected to standard input, and checks
+whether the console connected to standard input is the current
+foreground virtual console. With no arguments, it prints
+\fIvt\fR
+if console is a virtual terminal (/dev/tty* or /dev/console device if not on
+a serial console),
+\fIserial\fR
+if standard input is a serial console (/dev/console or /dev/ttyS*) and
+\fIpty\fR
+if standard input is a pseudo terminal.
+.SH RETURN VALUE
+\fBconsoletype
+when passed no arguments returns 
+.TP
+\fI0
+if on virtual terminal
+.TP
+\fI1
+if on serial console
+.TP
+\fI2
+if on a pseudo terminal.
+.TP
+When passed the \fIstdout\fR argument, \fBconsoletype\fR returns
+.TP
+\fI0
+in all cases, and prints the console type to stdout.
+.TP
+When passed the \fIfg\fR argument, \fBconsoletype\fR returns
+.TP
+\fI0
+if the console connected to standard input is the current virtual
+terminal
+.TP
+\fI1
+otherwise.
diff --git a/upstream/mageia-cauldron/man1/convert-ly.1 b/upstream/mageia-cauldron/man1/convert-ly.1
new file mode 100644
index 00000000..285029f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/convert-ly.1
@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH CONVERT-LY "1" "January 2024" "convert-ly 2.24.3" "User Commands"
+.SH NAME
+convert-ly \- manual page for convert-ly 2.24.3
+.SH SYNOPSIS
+.B convert-ly
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR
+.SH DESCRIPTION
+Update LilyPond input to newer version.  By default, update from the
+version taken from the \eversion command, to the current LilyPond version.
+If FILE is `\-', read from standard input.
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-f\fR, \fB\-\-from\fR=\fI\,VERSION\/\fR
+start from VERSION [default: \eversion found in file]
+.TP
+\fB\-e\fR, \fB\-\-edit\fR
+edit in place
+.TP
+\fB\-l\fR, \fB\-\-loglevel\fR=\fI\,LOGLEVEL\/\fR
+Print log messages according to LOGLEVEL (NONE, ERROR,
+WARNING, PROGRESS (default), DEBUG)
+.TP
+\fB\-n\fR, \fB\-\-no\-version\fR
+do not add \eversion command if missing
+.TP
+\fB\-c\fR, \fB\-\-current\-version\fR
+force updating \eversion number to 2.24.3
+.TP
+\fB\-d\fR, \fB\-\-diff\-version\-update\fR
+only update \eversion number if file is modified
+.TP
+\fB\-s\fR, \fB\-\-show\-rules\fR
+show rules [default: \fB\-f\fR 0, \fB\-t\fR 2.24.3]
+.TP
+\fB\-t\fR, \fB\-\-to\fR=\fI\,VERSION\/\fR
+convert to VERSION [default: 2.24.3]
+.TP
+\fB\-b\fR, \fB\-\-backup\-numbered\fR
+make a numbered backup [default: filename.ext~]
+.TP
+\fB\-w\fR, \fB\-\-warranty\fR
+show warranty and copyright
+.SH EXAMPLES
+.IP
+\f(CW$ convert-ly -e old.ly\fR
+.br
+\f(CW$ convert-ly --from=2.3.28 --to=2.5.21 foobar.ly > foobar-new.ly\fR
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH "SEE ALSO"
+The full documentation for
+.B convert-ly
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B convert-ly
+programs are properly installed at your site, the command
+.IP
+.B info convert-ly
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/coredumpctl.1 b/upstream/mageia-cauldron/man1/coredumpctl.1
new file mode 100644
index 00000000..fc6d03da
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/coredumpctl.1
@@ -0,0 +1,467 @@
+'\" t
+.TH "COREDUMPCTL" "1" "" "systemd 255" "coredumpctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+coredumpctl \- Retrieve and process saved core dumps and metadata
+.SH "SYNOPSIS"
+.HP \w'\fBcoredumpctl\fR\ 'u
+\fBcoredumpctl\fR [OPTIONS...] {COMMAND} [PID|COMM|EXE|MATCH...]
+.SH "DESCRIPTION"
+.PP
+\fBcoredumpctl\fR
+is a tool that can be used to retrieve and process core dumps and metadata which were saved by
+\fBsystemd-coredump\fR(8)\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR
+.RS 4
+List core dumps captured in the journal matching specified characteristics\&. If no command is specified, this is the implied default\&.
+.sp
+The output is designed to be human readable and contains a table with the following columns:
+.PP
+TIME
+.RS 4
+The timestamp of the crash, as reported by the kernel\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+PID
+.RS 4
+The identifier of the process that crashed\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+UID, GID
+.RS 4
+The user and group identifiers of the process that crashed\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+SIGNAL
+.RS 4
+The signal that caused the process to crash, when applicable\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+COREFILE
+.RS 4
+Information whether the coredump was stored, and whether it is still accessible:
+"none"
+means the core was not stored,
+"\-"
+means that it was not available (for example because the process was not terminated by a signal),
+"present"
+means that the core file is accessible by the current user,
+"journal"
+means that the core was stored in the
+"journal",
+"truncated"
+is the same as one of the previous two, but the core was too large and was not stored in its entirety,
+"error"
+means that the core file cannot be accessed, most likely because of insufficient permissions, and
+"missing"
+means that the core was stored in a file, but this file has since been removed\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+EXE
+.RS 4
+The full path to the executable\&. For backtraces of scripts this is the name of the interpreter\&.
+.sp
+Added in version 233\&.
+.RE
+.sp
+It\*(Aqs worth noting that different restrictions apply to data saved in the journal and core dump files saved in
+/var/lib/systemd/coredump, see overview in
+\fBsystemd-coredump\fR(8)\&. Thus it may very well happen that a particular core dump is still listed in the journal while its corresponding core dump file has already been removed\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fBinfo\fR
+.RS 4
+Show detailed information about the last core dump or core dumps matching specified characteristics captured in the journal\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fBdump\fR
+.RS 4
+Extract the last core dump matching specified characteristics\&. The core dump will be written on standard output, unless an output file is specified with
+\fB\-\-output=\fR\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fBdebug\fR
+.RS 4
+Invoke a debugger on the last core dump matching specified characteristics\&. By default,
+\fBgdb\fR(1)
+will be used\&. This may be changed using the
+\fB\-\-debugger=\fR
+option or the
+\fI$SYSTEMD_DEBUGGER\fR
+environment variable\&. Use the
+\fB\-\-debugger\-arguments=\fR
+option to pass extra command line arguments to the debugger\&.
+.sp
+Added in version 239\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.PP
+\fB\-1\fR
+.RS 4
+Show information of the most recent core dump only, instead of listing all known core dumps\&. Equivalent to
+\fB\-\-reverse \-n 1\fR\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fB\-n\fR \fIINT\fR
+.RS 4
+Show at most the specified number of entries\&. The specified parameter must be an integer greater or equal to 1\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-S\fR, \fB\-\-since\fR
+.RS 4
+Only print entries which are since the specified date\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-U\fR, \fB\-\-until\fR
+.RS 4
+Only print entries which are until the specified date\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-reverse\fR
+.RS 4
+Reverse output so that the newest entries are displayed first\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-F\fR \fIFIELD\fR, \fB\-\-field=\fR\fIFIELD\fR
+.RS 4
+Print all possible data values the specified field takes in matching core dump entries of the journal\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fB\-o\fR \fIFILE\fR, \fB\-\-output=\fR\fIFILE\fR
+.RS 4
+Write the core to
+\fBFILE\fR\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fB\-\-debugger=\fR\fIDEBUGGER\fR
+.RS 4
+Use the given debugger for the
+\fBdebug\fR
+command\&. If not given and
+\fI$SYSTEMD_DEBUGGER\fR
+is unset, then
+\fBgdb\fR(1)
+will be used\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-A\fR \fIARGS\fR, \fB\-\-debugger\-arguments=\fR\fIARGS\fR
+.RS 4
+Pass the given
+\fIARGS\fR
+as extra command line arguments to the debugger\&. Quote as appropriate when
+\fIARGS\fR
+contain whitespace\&. (See Examples\&.)
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-file=\fR\fB\fIGLOB\fR\fR
+.RS 4
+Takes a file glob as an argument\&. If specified, coredumpctl will operate on the specified journal files matching
+\fIGLOB\fR
+instead of the default runtime and system journal paths\&. May be specified multiple times, in which case files will be suitably interleaved\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-D\fR \fIDIR\fR, \fB\-\-directory=\fR\fIDIR\fR
+.RS 4
+Use the journal files in the specified
+\fBDIR\fR\&.
+.sp
+Added in version 225\&.
+.RE
+.PP
+\fB\-\-root=\fR\fB\fIROOT\fR\fR
+.RS 4
+Use root directory
+\fBROOT\fR
+when searching for coredumps\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIimage\fR\fR
+.RS 4
+Takes a path to a disk image file or block device node\&. If specified, all operations are applied to file system in the indicated disk image\&. This option is similar to
+\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
+\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppresses informational messages about lack of access to journal files and possible in\-flight coredumps\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-\-all\fR
+.RS 4
+Look at all available journal files in
+/var/log/journal/
+(excluding journal namespaces) instead of only local ones\&.
+.sp
+Added in version 250\&.
+.RE
+.SH "MATCHING"
+.PP
+A match can be:
+.PP
+\fIPID\fR
+.RS 4
+Process ID of the process that dumped core\&. An integer\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fICOMM\fR
+.RS 4
+Name of the executable (matches
+\fBCOREDUMP_COMM=\fR)\&. Must not contain slashes\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fIEXE\fR
+.RS 4
+Path to the executable (matches
+\fBCOREDUMP_EXE=\fR)\&. Must contain at least one slash\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fIMATCH\fR
+.RS 4
+General journalctl match filter, must contain an equals sign ("=")\&. See
+\fBjournalctl\fR(1)\&.
+.sp
+Added in version 215\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned; otherwise, a non\-zero failure code is returned\&. Not finding any matching core dumps is treated as failure\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_DEBUGGER\fR
+.RS 4
+Use the given debugger for the
+\fBdebug\fR
+command\&. See the
+\fB\-\-debugger=\fR
+option\&.
+.sp
+Added in version 239\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&List all the core dumps of a program\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ coredumpctl list /usr/lib64/firefox/firefox
+TIME       PID  UID  GID SIG     COREFILE EXE                         SIZE
+Tue \&...   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox     \-
+Wed \&... 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox     \-
+Fri \&... 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28\&.7M
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The journal has three entries pertaining to
+/usr/lib64/firefox/firefox, and only the last entry still has an available core file (in external storage on disk)\&.
+.PP
+Note that
+coredumpctl
+needs access to the journal files to retrieve the relevant entries from the journal\&. Thus, an unprivileged user will normally only see information about crashing programs of this user\&.
+.PP
+\fBExample\ \&2.\ \&Invoke gdb on the last core dump\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ coredumpctl debug
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&3.\ \&Use gdb to display full register info from the last core dump\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ coredumpctl debug \-\-debugger\-arguments="\-batch \-ex \*(Aqinfo all\-registers\*(Aq"
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&4.\ \&Show information about a core dump matched by PID\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ coredumpctl info 6654
+           PID: 6654 (bash)
+           UID: 1000 (user)
+           GID: 1000 (user)
+        Signal: 11 (SEGV)
+     Timestamp: Mon 2021\-01\-01 00:00:01 CET (20s ago)
+  Command Line: bash \-c $\*(Aqkill \-SEGV $$\*(Aq
+    Executable: /usr/bin/bash
+ Control Group: /user\&.slice/user\-1000\&.slice/\&...
+          Unit: user@1000\&.service
+     User Unit: vte\-spawn\-\&...\&.scope
+         Slice: user\-1000\&.slice
+     Owner UID: 1000 (user)
+       Boot ID: \&...
+    Machine ID: \&...
+      Hostname: \&...
+       Storage: /var/lib/systemd/coredump/core\&.bash\&.1000\&.\&...\&.zst (present)
+  Size on Disk: 51\&.7K
+       Message: Process 130414 (bash) of user 1000 dumped core\&.
+
+                Stack trace of thread 130414:
+                #0  0x00007f398142358b kill (libc\&.so\&.6 + 0x3d58b)
+                #1  0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
+                #2  0x0000558c2c79dc59 execute_builtin\&.lto_priv\&.0 (bash + 0x51c59)
+                #3  0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
+                #4  0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
+                #5  0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
+                #6  0x0000558c2c85415c run_one_command\&.isra\&.0 (bash + 0x10815c)
+                #7  0x0000558c2c77d040 main (bash + 0x31040)
+                #8  0x00007f398140db75 __libc_start_main (libc\&.so\&.6 + 0x27b75)
+                #9  0x0000558c2c77dd1e _start (bash + 0x31d1e)
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&5.\ \&Extract the last core dump of /usr/bin/bar to a file named bar\&.coredump\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ coredumpctl \-o bar\&.coredump dump /usr/bin/bar
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd-coredump\fR(8),
+\fBcoredump.conf\fR(5),
+\fBsystemd-journald.service\fR(8),
+\fBgdb\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
diff --git a/upstream/mageia-cauldron/man1/corelist.1 b/upstream/mageia-cauldron/man1/corelist.1
new file mode 100644
index 00000000..710dd408
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/corelist.1
@@ -0,0 +1,252 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "CORELIST 1"
+.TH CORELIST 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+corelist \- a commandline frontend to Module::CoreList
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+See Module::CoreList for one.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 9
+\&   corelist \-v
+\&   corelist [\-a|\-d] <ModuleName> | /<ModuleRegex>/ [<ModuleVersion>] ...
+\&   corelist [\-v <PerlVersion>] [ <ModuleName> | /<ModuleRegex>/ ] ...
+\&   corelist [\-r <PerlVersion>] ...
+\&   corelist \-\-utils [\-d] <UtilityName> [<UtilityName>] ...
+\&   corelist \-\-utils \-v <PerlVersion>
+\&   corelist \-\-feature <FeatureName> [<FeatureName>] ...
+\&   corelist \-\-diff PerlVersion PerlVersion
+\&   corelist \-\-upstream <ModuleName>
+.Ve
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \-a 4
+.IX Item "-a"
+lists all versions of the given module (or the matching modules, in case you
+used a module regexp) in the perls Module::CoreList knows about.
+.Sp
+.Vb 1
+\&    corelist \-a Unicode
+\&
+\&    Unicode was first released with perl v5.6.2
+\&      v5.6.2     3.0.1
+\&      v5.8.0     3.2.0
+\&      v5.8.1     4.0.0
+\&      v5.8.2     4.0.0
+\&      v5.8.3     4.0.0
+\&      v5.8.4     4.0.1
+\&      v5.8.5     4.0.1
+\&      v5.8.6     4.0.1
+\&      v5.8.7     4.1.0
+\&      v5.8.8     4.1.0
+\&      v5.8.9     5.1.0
+\&      v5.9.0     4.0.0
+\&      v5.9.1     4.0.0
+\&      v5.9.2     4.0.1
+\&      v5.9.3     4.1.0
+\&      v5.9.4     4.1.0
+\&      v5.9.5     5.0.0
+\&      v5.10.0    5.0.0
+\&      v5.10.1    5.1.0
+\&      v5.11.0    5.1.0
+\&      v5.11.1    5.1.0
+\&      v5.11.2    5.1.0
+\&      v5.11.3    5.2.0
+\&      v5.11.4    5.2.0
+\&      v5.11.5    5.2.0
+\&      v5.12.0    5.2.0
+\&      v5.12.1    5.2.0
+\&      v5.12.2    5.2.0
+\&      v5.12.3    5.2.0
+\&      v5.12.4    5.2.0
+\&      v5.13.0    5.2.0
+\&      v5.13.1    5.2.0
+\&      v5.13.2    5.2.0
+\&      v5.13.3    5.2.0
+\&      v5.13.4    5.2.0
+\&      v5.13.5    5.2.0
+\&      v5.13.6    5.2.0
+\&      v5.13.7    6.0.0
+\&      v5.13.8    6.0.0
+\&      v5.13.9    6.0.0
+\&      v5.13.10   6.0.0
+\&      v5.13.11   6.0.0
+\&      v5.14.0    6.0.0
+\&      v5.14.1    6.0.0
+\&      v5.15.0    6.0.0
+.Ve
+.IP \-d 4
+.IX Item "-d"
+finds the first perl version where a module has been released by
+date, and not by version number (as is the default).
+.IP \-\-diff 4
+.IX Item "--diff"
+Given two versions of perl, this prints a human-readable table of all module
+changes between the two.  The output format may change in the future, and is
+meant for \fIhumans\fR, not programs.  For programs, use the Module::CoreList
+API.
+.IP "\-? or \-help" 4
+.IX Item "-? or -help"
+help! help! help! to see more help, try \-\-man.
+.IP \-man 4
+.IX Item "-man"
+all of the help
+.IP \-v 4
+.IX Item "-v"
+lists all of the perl release versions we got the CoreList for.
+.Sp
+If you pass a version argument (value of \f(CW$]\fR, like \f(CW5.00503\fR or \f(CW5.008008\fR),
+you get a list of all the modules and their respective versions.
+(If you have the \f(CW\*(C`version\*(C'\fR module, you can also use new-style version numbers,
+like \f(CW5.8.8\fR.)
+.Sp
+In module filtering context, it can be used as Perl version filter.
+.IP \-r 4
+.IX Item "-r"
+lists all of the perl releases and when they were released
+.Sp
+If you pass a perl version you get the release date for that version only.
+.IP \-\-utils 4
+.IX Item "--utils"
+lists the first version of perl each named utility program was released with
+.Sp
+May be used with \-d to modify the first release criteria.
+.Sp
+If used with \-v <version> then all utilities released with that version of perl
+are listed, and any utility programs named on the command line are ignored.
+.IP "\-\-feature, \-f" 4
+.IX Item "--feature, -f"
+lists the first version bundle of each named feature given
+.IP "\-\-upstream, \-u" 4
+.IX Item "--upstream, -u"
+Shows if the given module is primarily maintained in perl core or on CPAN
+and bug tracker URL.
+.PP
+As a special case, if you specify the module name \f(CW\*(C`Unicode\*(C'\fR, you'll get
+the version number of the Unicode Character Database bundled with the
+requested perl versions.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 1
+\&    $ corelist File::Spec
+\&
+\&    File::Spec was first released with perl 5.005
+\&
+\&    $ corelist File::Spec 0.83
+\&
+\&    File::Spec 0.83 was released with perl 5.007003
+\&
+\&    $ corelist File::Spec 0.89
+\&
+\&    File::Spec 0.89 was not in CORE (or so I think)
+\&
+\&    $ corelist File::Spec::Aliens
+\&
+\&    File::Spec::Aliens  was not in CORE (or so I think)
+\&
+\&    $ corelist /IPC::Open/
+\&
+\&    IPC::Open2 was first released with perl 5
+\&
+\&    IPC::Open3 was first released with perl 5
+\&
+\&    $ corelist /MANIFEST/i
+\&
+\&    ExtUtils::Manifest was first released with perl 5.001
+\&
+\&    $ corelist /Template/
+\&
+\&    /Template/  has no match in CORE (or so I think)
+\&
+\&    $ corelist \-v 5.8.8 B
+\&
+\&    B                        1.09_01
+\&
+\&    $ corelist \-v 5.8.8 /^B::/
+\&
+\&    B::Asmdata               1.01
+\&    B::Assembler             0.07
+\&    B::Bblock                1.02_01
+\&    B::Bytecode              1.01_01
+\&    B::C                     1.04_01
+\&    B::CC                    1.00_01
+\&    B::Concise               0.66
+\&    B::Debug                 1.02_01
+\&    B::Deparse               0.71
+\&    B::Disassembler          1.05
+\&    B::Lint                  1.03
+\&    B::O                     1.00
+\&    B::Showlex               1.02
+\&    B::Stackobj              1.00
+\&    B::Stash                 1.00
+\&    B::Terse                 1.03_01
+\&    B::Xref                  1.01
+.Ve
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2002\-2007 by D.H. aka PodMaster
+.PP
+Currently maintained by the perl 5 porters <perl5\-porters@perl.org>.
+.PP
+This program is distributed under the same terms as perl itself.
+See http://perl.org/ or http://cpan.org/ for more info on that.
diff --git a/upstream/mageia-cauldron/man1/cp.1 b/upstream/mageia-cauldron/man1/cp.1
new file mode 100644
index 00000000..a4fc879e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cp.1
@@ -0,0 +1,178 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CP "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+cp \- copy files and directories
+.SH SYNOPSIS
+.B cp
+[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,SOURCE DEST\/\fR
+.br
+.B cp
+[\fI\,OPTION\/\fR]... \fI\,SOURCE\/\fR... \fI\,DIRECTORY\/\fR
+.br
+.B cp
+[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY SOURCE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-archive\fR
+same as \fB\-dR\fR \fB\-\-preserve\fR=\fI\,all\/\fR
+.TP
+\fB\-\-attributes\-only\fR
+don't copy the file data, just the attributes
+.TP
+\fB\-\-backup\fR[=\fI\,CONTROL\/\fR]
+make a backup of each existing destination file
+.TP
+\fB\-b\fR
+like \fB\-\-backup\fR but does not accept an argument
+.TP
+\fB\-\-copy\-contents\fR
+copy contents of special files when recursive
+.TP
+\fB\-d\fR
+same as \fB\-\-no\-dereference\fR \fB\-\-preserve\fR=\fI\,links\/\fR
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+if an existing destination file cannot be
+opened, remove it and try again (this option
+is ignored when the \fB\-n\fR option is also used)
+.TP
+\fB\-i\fR, \fB\-\-interactive\fR
+prompt before overwrite (overrides a previous \fB\-n\fR
+option)
+.TP
+\fB\-H\fR
+follow command\-line symbolic links in SOURCE
+.TP
+\fB\-l\fR, \fB\-\-link\fR
+hard link files instead of copying
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+always follow symbolic links in SOURCE
+.TP
+\fB\-n\fR, \fB\-\-no\-clobber\fR
+do not overwrite an existing file (overrides
+a previous \fB\-i\fR option)
+.TP
+\fB\-P\fR, \fB\-\-no\-dereference\fR
+never follow symbolic links in SOURCE
+.TP
+\fB\-p\fR
+same as \fB\-\-preserve\fR=\fI\,mode\/\fR,ownership,timestamps
+.TP
+\fB\-\-preserve\fR[=\fI\,ATTR_LIST\/\fR]
+preserve the specified attributes (default:
+mode,ownership,timestamps), if possible
+additional attributes: context, links, xattr,
+all
+.TP
+\fB\-\-no\-preserve\fR=\fI\,ATTR_LIST\/\fR
+don't preserve the specified attributes
+.TP
+\fB\-\-parents\fR
+use full source file name under DIRECTORY
+.TP
+\fB\-R\fR, \fB\-r\fR, \fB\-\-recursive\fR
+copy directories recursively
+.TP
+\fB\-\-reflink\fR[=\fI\,WHEN\/\fR]
+control clone/CoW copies. See below
+.TP
+\fB\-\-remove\-destination\fR
+remove each existing destination file before
+attempting to open it (contrast with \fB\-\-force\fR)
+.TP
+\fB\-\-sparse\fR=\fI\,WHEN\/\fR
+control creation of sparse files. See below
+.TP
+\fB\-\-strip\-trailing\-slashes\fR
+remove any trailing slashes from each SOURCE
+argument
+.TP
+\fB\-s\fR, \fB\-\-symbolic\-link\fR
+make symbolic links instead of copying
+.TP
+\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+override the usual backup suffix
+.TP
+\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR
+copy all SOURCE arguments into DIRECTORY
+.TP
+\fB\-T\fR, \fB\-\-no\-target\-directory\fR
+treat DEST as a normal file
+.TP
+\fB\-u\fR, \fB\-\-update\fR
+copy only when the SOURCE file is newer
+than the destination file or when the
+destination file is missing
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+explain what is being done
+.TP
+\fB\-x\fR, \fB\-\-one\-file\-system\fR
+stay on this file system
+.TP
+\fB\-Z\fR
+set SELinux security context of destination
+file to default type
+.TP
+\fB\-\-context\fR[=\fI\,CTX\/\fR]
+like \fB\-Z\fR, or if CTX is specified then set the
+SELinux or SMACK security context to CTX
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+By default, sparse SOURCE files are detected by a crude heuristic and the
+corresponding DEST file is made sparse as well.  That is the behavior
+selected by \fB\-\-sparse\fR=\fI\,auto\/\fR.  Specify \fB\-\-sparse\fR=\fI\,always\/\fR to create a sparse DEST
+file whenever the SOURCE file contains a long enough sequence of zero bytes.
+Use \fB\-\-sparse\fR=\fI\,never\/\fR to inhibit creation of sparse files.
+.PP
+When \fB\-\-reflink\fR[=\fI\,always\/\fR] is specified, perform a lightweight copy, where the
+data blocks are copied only when modified.  If this is not possible the copy
+fails, or if \fB\-\-reflink\fR=\fI\,auto\/\fR is specified, fall back to a standard copy.
+Use \fB\-\-reflink\fR=\fI\,never\/\fR to ensure a standard copy is performed.
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX.
+The version control method may be selected via the \fB\-\-backup\fR option or through
+the VERSION_CONTROL environment variable.  Here are the values:
+.TP
+none, off
+never make backups (even if \fB\-\-backup\fR is given)
+.TP
+numbered, t
+make numbered backups
+.TP
+existing, nil
+numbered if numbered backups exist, simple otherwise
+.TP
+simple, never
+always make simple backups
+.PP
+As a special case, cp makes a backup of SOURCE when the force and backup
+options are given and SOURCE and DEST are the same name for an existing,
+regular file.
+.SH AUTHOR
+Written by Torbjorn Granlund, David MacKenzie, and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/cp>
+.br
+or available locally via: info \(aq(coreutils) cp invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/cpan.1 b/upstream/mageia-cauldron/man1/cpan.1
new file mode 100644
index 00000000..45dbf68b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cpan.1
@@ -0,0 +1,340 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "CPAN 1"
+.TH CPAN 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+cpan \- easily interact with CPAN from the command line
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&        # with arguments and no switches, installs specified modules
+\&        cpan module_name [ module_name ... ]
+\&
+\&        # with switches, installs modules with extra behavior
+\&        cpan [\-cfFimtTw] module_name [ module_name ... ]
+\&
+\&        # use local::lib
+\&        cpan \-I module_name [ module_name ... ]
+\&
+\&        # one time mirror override for faster mirrors
+\&        cpan \-p ...
+\&
+\&        # with just the dot, install from the distribution in the
+\&        # current directory
+\&        cpan .
+\&
+\&        # without arguments, starts CPAN.pm shell
+\&        cpan
+\&
+\&        # without arguments, but some switches
+\&        cpan [\-ahpruvACDLOPX]
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This script provides a command interface (not a shell) to CPAN. At the
+moment it uses CPAN.pm to do the work, but it is not a one-shot command
+runner for CPAN.pm.
+.SS Options
+.IX Subsection "Options"
+.IP \-a 4
+.IX Item "-a"
+Creates a CPAN.pm autobundle with CPAN::Shell\->autobundle.
+.IP "\-A module [ module ... ]" 4
+.IX Item "-A module [ module ... ]"
+Shows the primary maintainers for the specified modules.
+.IP "\-c module" 4
+.IX Item "-c module"
+Runs a `make clean` in the specified module's directories.
+.IP "\-C module [ module ... ]" 4
+.IX Item "-C module [ module ... ]"
+Show the \fIChanges\fR files for the specified modules
+.IP "\-D module [ module ... ]" 4
+.IX Item "-D module [ module ... ]"
+Show the module details. This prints one line for each out-of-date module
+(meaning, modules locally installed but have newer versions on CPAN).
+Each line has three columns: module name, local version, and CPAN
+version.
+.IP \-f 4
+.IX Item "-f"
+Force the specified action, when it normally would have failed. Use this
+to install a module even if its tests fail. When you use this option,
+\&\-i is not optional for installing a module when you need to force it:
+.Sp
+.Vb 1
+\&        % cpan \-f \-i Module::Foo
+.Ve
+.IP \-F 4
+.IX Item "-F"
+Turn off CPAN.pm's attempts to lock anything. You should be careful with
+this since you might end up with multiple scripts trying to muck in the
+same directory. This isn't so much of a concern if you're loading a special
+config with \f(CW\*(C`\-j\*(C'\fR, and that config sets up its own work directories.
+.IP "\-g module [ module ... ]" 4
+.IX Item "-g module [ module ... ]"
+Downloads to the current directory the latest distribution of the module.
+.IP "\-G module [ module ... ]" 4
+.IX Item "-G module [ module ... ]"
+UNIMPLEMENTED
+.Sp
+Download to the current directory the latest distribution of the
+modules, unpack each distribution, and create a git repository for each
+distribution.
+.Sp
+If you want this feature, check out Yanick Champoux's \f(CW\*(C`Git::CPAN::Patch\*(C'\fR
+distribution.
+.IP \-h 4
+.IX Item "-h"
+Print a help message and exit. When you specify \f(CW\*(C`\-h\*(C'\fR, it ignores all
+of the other options and arguments.
+.IP "\-i module [ module ... ]" 4
+.IX Item "-i module [ module ... ]"
+Install the specified modules. With no other switches, this switch
+is implied.
+.IP \-I 4
+.IX Item "-I"
+Load \f(CW\*(C`local::lib\*(C'\fR (think like \f(CW\*(C`\-I\*(C'\fR for loading lib paths). Too bad
+\&\f(CW\*(C`\-l\*(C'\fR was already taken.
+.IP "\-j Config.pm" 4
+.IX Item "-j Config.pm"
+Load the file that has the CPAN configuration data. This should have the
+same format as the standard \fICPAN/Config.pm\fR file, which defines
+\&\f(CW$CPAN::Config\fR as an anonymous hash.
+.IP \-J 4
+.IX Item "-J"
+Dump the configuration in the same format that CPAN.pm uses. This is useful
+for checking the configuration as well as using the dump as a starting point
+for a new, custom configuration.
+.IP \-l 4
+.IX Item "-l"
+List all installed modules with their versions
+.IP "\-L author [ author ... ]" 4
+.IX Item "-L author [ author ... ]"
+List the modules by the specified authors.
+.IP \-m 4
+.IX Item "-m"
+Make the specified modules.
+.IP "\-M mirror1,mirror2,..." 4
+.IX Item "-M mirror1,mirror2,..."
+A comma-separated list of mirrors to use for just this run. The \f(CW\*(C`\-P\*(C'\fR
+option can find them for you automatically.
+.IP \-n 4
+.IX Item "-n"
+Do a dry run, but don't actually install anything. (unimplemented)
+.IP \-O 4
+.IX Item "-O"
+Show the out-of-date modules.
+.IP \-p 4
+.IX Item "-p"
+Ping the configured mirrors and print a report
+.IP \-P 4
+.IX Item "-P"
+Find the best mirrors you could be using and use them for the current
+session.
+.IP \-r 4
+.IX Item "-r"
+Recompiles dynamically loaded modules with CPAN::Shell\->recompile.
+.IP \-s 4
+.IX Item "-s"
+Drop in the CPAN.pm shell. This command does this automatically if you don't
+specify any arguments.
+.IP "\-t module [ module ... ]" 4
+.IX Item "-t module [ module ... ]"
+Run a `make test` on the specified modules.
+.IP \-T 4
+.IX Item "-T"
+Do not test modules. Simply install them.
+.IP \-u 4
+.IX Item "-u"
+Upgrade all installed modules. Blindly doing this can really break things,
+so keep a backup.
+.IP \-v 4
+.IX Item "-v"
+Print the script version and CPAN.pm version then exit.
+.IP \-V 4
+.IX Item "-V"
+Print detailed information about the cpan client.
+.IP \-w 4
+.IX Item "-w"
+UNIMPLEMENTED
+.Sp
+Turn on cpan warnings. This checks various things, like directory permissions,
+and tells you about problems you might have.
+.IP "\-x module [ module ... ]" 4
+.IX Item "-x module [ module ... ]"
+Find close matches to the named modules that you think you might have
+mistyped. This requires the optional installation of Text::Levenshtein or
+Text::Levenshtein::Damerau.
+.IP \-X 4
+.IX Item "-X"
+Dump all the namespaces to standard output.
+.SS Examples
+.IX Subsection "Examples"
+.Vb 2
+\&        # print a help message
+\&        cpan \-h
+\&
+\&        # print the version numbers
+\&        cpan \-v
+\&
+\&        # create an autobundle
+\&        cpan \-a
+\&
+\&        # recompile modules
+\&        cpan \-r
+\&
+\&        # upgrade all installed modules
+\&        cpan \-u
+\&
+\&        # install modules ( sole \-i is optional )
+\&        cpan \-i Netscape::Booksmarks Business::ISBN
+\&
+\&        # force install modules ( must use \-i )
+\&        cpan \-fi CGI::Minimal URI
+\&
+\&        # install modules but without testing them
+\&        cpan \-Ti CGI::Minimal URI
+.Ve
+.SS "Environment variables"
+.IX Subsection "Environment variables"
+There are several components in CPAN.pm that use environment variables.
+The build tools, ExtUtils::MakeMaker and Module::Build use some,
+while others matter to the levels above them. Some of these are specified
+by the Perl Toolchain Gang:
+.PP
+Lancaster Consensus: <https://github.com/Perl\-Toolchain\-Gang/toolchain\-site/blob/master/lancaster\-consensus.md>
+.PP
+Oslo Consensus: <https://github.com/Perl\-Toolchain\-Gang/toolchain\-site/blob/master/oslo\-consensus.md>
+.IP NONINTERACTIVE_TESTING 4
+.IX Item "NONINTERACTIVE_TESTING"
+Assume no one is paying attention and skips prompts for distributions
+that do that correctly. \f(CWcpan(1)\fR sets this to \f(CW1\fR unless it already
+has a value (even if that value is false).
+.IP PERL_MM_USE_DEFAULT 4
+.IX Item "PERL_MM_USE_DEFAULT"
+Use the default answer for a prompted questions. \f(CWcpan(1)\fR sets this
+to \f(CW1\fR unless it already has a value (even if that value is false).
+.IP CPAN_OPTS 4
+.IX Item "CPAN_OPTS"
+As with \f(CW\*(C`PERL5OPT\*(C'\fR, a string of additional \f(CWcpan(1)\fR options to
+add to those you specify on the command line.
+.IP CPANSCRIPT_LOGLEVEL 4
+.IX Item "CPANSCRIPT_LOGLEVEL"
+The log level to use, with either the embedded, minimal logger or
+Log::Log4perl if it is installed. Possible values are the same as
+the \f(CW\*(C`Log::Log4perl\*(C'\fR levels: \f(CW\*(C`TRACE\*(C'\fR, \f(CW\*(C`DEBUG\*(C'\fR, \f(CW\*(C`INFO\*(C'\fR, \f(CW\*(C`WARN\*(C'\fR,
+\&\f(CW\*(C`ERROR\*(C'\fR, and \f(CW\*(C`FATAL\*(C'\fR. The default is \f(CW\*(C`INFO\*(C'\fR.
+.IP GIT_COMMAND 4
+.IX Item "GIT_COMMAND"
+The path to the \f(CW\*(C`git\*(C'\fR binary to use for the Git features. The default
+is \f(CW\*(C`/usr/local/bin/git\*(C'\fR.
+.SH "EXIT VALUES"
+.IX Header "EXIT VALUES"
+The script exits with zero if it thinks that everything worked, or a
+positive number if it thinks that something failed. Note, however, that
+in some cases it has to divine a failure by the output of things it does
+not control. For now, the exit codes are vague:
+.PP
+.Vb 1
+\&        1       An unknown error
+\&
+\&        2       The was an external problem
+\&
+\&        4       There was an internal problem with the script
+\&
+\&        8       A module failed to install
+.Ve
+.SH "TO DO"
+.IX Header "TO DO"
+* one shot configuration values from the command line
+.SH BUGS
+.IX Header "BUGS"
+* none noted
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Most behaviour, including environment variables and configuration,
+comes directly from CPAN.pm.
+.SH "SOURCE AVAILABILITY"
+.IX Header "SOURCE AVAILABILITY"
+This code is in Github in the CPAN.pm repository:
+.PP
+.Vb 1
+\&        https://github.com/andk/cpanpm
+.Ve
+.PP
+The source used to be tracked separately in another GitHub repo,
+but the canonical source is now in the above repo.
+.SH CREDITS
+.IX Header "CREDITS"
+Japheth Cleaver added the bits to allow a forced install (\-f).
+.PP
+Jim Brandt suggest and provided the initial implementation for the
+up-to-date and Changes features.
+.PP
+Adam Kennedy pointed out that \fBexit()\fR causes problems on Windows
+where this script ends up with a .bat extension
+.SH AUTHOR
+.IX Header "AUTHOR"
+brian d foy, \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2001\-2015, brian d foy, All Rights Reserved.
+.PP
+You may redistribute this under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/cpio.1 b/upstream/mageia-cauldron/man1/cpio.1
new file mode 100644
index 00000000..59b35ae5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cpio.1
@@ -0,0 +1,361 @@
+.\" This file is part of GNU cpio. -*- nroff -*-
+.\" Copyright 2014-2023 Free Software Foundation, Inc.
+.\"
+.\" GNU cpio 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.
+.\"
+.\" GNU cpio is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with GNU cpio.  If not, see <http://www.gnu.org/licenses/>.
+.TH CPIO 1 "April 29, 2023" "CPIO" "GNU CPIO"
+.SH NAME
+cpio \- copy files to and from archives
+.SH SYNOPSIS
+.B cpio
+{\fB\-o\fR|\fB\-\-create\fR} [\fB\-0acvABLV\fR] [\fB\-C\fR \fIBYTES\fR]
+[\fB\-H\fR \fIFORMAT\fR] [\fB\-M\fR \fIMESSAGE\fR]
+[\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-format=\fIFORMAT\fR] [\fB\-\-message=\fIMESSAGE\fR]
+[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR] [\fB\-\-verbose\fR]
+[\fB\-\-dot\fR] [\fB\-\-append\fR]
+[\fB\-\-block\-size=\fIblocks\fR] [\fB\-\-dereference\fR]
+[\fB\-\-io\-size=\fIBYTES\fR] [\fB\-\-quiet\fR]
+[\fB\-\-force\-local\fR] [\fB\-\-rsh\-command=\fICOMMAND\fR]
+\fB<\fR \fIname-list\fR [\fB>\fR \fIarchive\fR]
+
+.B cpio
+{\fB\-i\fR|\fB\-\-extract\fR} [\fB\-bcdfmnrtsuvBSV\fR] [\fB\-C\fR \fIBYTES\fR]
+[\fB\-E\fR \fIFILE\fR] [\fB\-H\fR \fIFORMAT\fR]
+[\fB\-M\fR \fIMESSAGE\fR] [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-make\-directories\fR] [\fB\-\-nonmatching\fR]
+[\fB\-\-preserve\-modification\-time\fR] [\fB\-\-numeric\-uid\-gid\fR]
+[\fB\-\-rename\fR] [\fB\-\-list\fR] [\fB\-\-swap\-bytes\fR]
+[\fB\-\-swap\fR] [\fB\-\-dot\fR] [\fB\-\-unconditional\fR]
+[\fB\-\-verbose\fR] [\fB\-\-block\-size=\fIBLOCKS\fR]
+[\fB\-\-swap\-halfwords\fR] [\fB\-\-io\-size=\fIBYTES\fR]
+[\fB\-\-pattern\-file=\fIFILE\fR] [\fB\-\-format=\fIFORMAT\fR]
+[\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-message=\fIMESSAGE\fR]
+[\fB\-\-force\-local\fR] [\fB\-\-no\-absolute\-filenames\fR] [\fB\-\-sparse\fR]
+[\fB\-\-only\-verify\-crc\fR] [\fB\-\-to\-stdout\fR] [\fB\-\-quiet\fR]
+[\fB\-\-rsh\-command=\fICOMMAND\fR]
+[\fIpattern\fR...] [\fB<\fR \fIarchive\fR]
+
+.B cpio
+{\fB\-p\fR|\fB\-\-pass\-through\fR} [\fB\-0adlmuvLV\fR]
+[\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR]
+[\fB\-\-make\-directories\fR] [\fB\-\-link\fR] [\fB\-\-quiet\fR]
+[\fB\-\-preserve\-modification\-time] [\fB\-\-unconditional\fR]
+[\fB\-\-verbose\fR] [\fB\-\-dot\fR] [\fB\-\-dereference\fR]
+[\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-sparse\fR]
+\fIdestination-directory\fR \fB<\fR \fIname-list\fR
+
+.B cpio
+{\fB\-?\fR|\fB\-\-help\fR|\fB\-\-usage\fR|\fB\-\-version\fR}
+.SH NOTE
+This manpage is a short description of GNU \fBcpio\fR.  For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBGNU Cpio Manual\fR available in texinfo format.  If the \fBinfo\fR
+reader and the cpio documentation are properly installed on your
+system, the command
+.PP
+.RS +4
+.B info cpio
+.RE
+.PP
+should give you access to the complete manual.
+.PP
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org/software/cpio/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBGNU Cpio Manual\fR, the later shall be considered the authoritative
+source.
+.SH DESCRIPTION
+GNU \fBcpio\fR copies files between archives and directories.  It
+supports the following archive formats: old binary cpio, old portable
+cpio, SVR4 cpio with and without checksum, HP cpio, and various tar
+formats.
+.PP
+The operation mode is requested by one of the following options:
+.TP
+.BR \-o ", " \-\-create
+Copy-out.  Read a list of file names from the standard input and
+create on the standard output (unless overridden by the \fB\-\-file\fR
+option) an archive containing these files.
+.TP
+.BR \-i ", " \-\-extract
+Copy-in.  Read the archive from standard input (or from the file
+supplied with the \fB\-\-file\fR option) and extract files from it, or
+(if the \fB\-t\fR option is given) list its contents to the standard
+output.  If one or more \fIpattern\fRs are supplied, read or list only
+files matching these patterns.  The \fB\-t\fR option alone implies
+\fB\-i\fR.
+.TP
+.BR \-p ", " \-\-pass\-through
+Pass-through.  Read a list of file names from the standard input and
+copy them to the specified directory.
+.TP
+.BR \-? ", " \-\-help
+Give a short help summary and exit.
+.TP
+.B \-\-usage
+Print a short usage message and exit.
+.TP
+.B \-\-version
+Print program version and exit.
+.SH OPTIONS
+.SS Operation modifiers valid in any mode
+.TP
+\fB\-\-block\-size=\fIBLOCK-SIZE\fR
+Set the I/O block size to \fIBLOCK-SIZE\fR * 512 bytes.
+.TP
+.B \-B
+Set the I/O block size to 5120 bytes.
+.TP
+.B \-c
+Use the old portable (ASCII) archive format.  This is the same as
+\fB\-H odc\fR.
+.TP
+\fB\-C\fR, \fB\-\-io\-size=\fINUMBER\fR
+Set the I/O block size to the given \fINUMBER\fR of bytes.
+.TP
+\fB\-D\fR, \fB\-\-directory=\fIDIR\fR
+Change to directory \fIDIR\fR.
+.TP
+.B \-\-force\-local
+Archive file is local, even if its name contains colons.
+.TP
+\fB\-H\fR, \fB\-\-format=\fIFORMAT\fR
+Use given archive \fBFORMAT\fR.  Valid formats are (the number in
+parentheses gives maximum size for individual archive member):
+.RS
+.TP
+.B bin
+The obsolete binary format.  (2147483647 bytes)
+.TP
+.B odc
+The old (POSIX.1) portable format. (8589934591 bytes)
+.TP
+.B newc
+The new (SVR4) portable format, which supports file systems
+having more than 65536 inodes. (4294967295 bytes)
+.TP
+.B crc
+The new (SVR4) portable format with a checksum added.
+.TP
+.B tar
+The old tar format. (8589934591 bytes)
+.TP
+.B ustar
+The POSIX.1 tar format.  Also recognizes GNU tar archives,
+which are similar but not identical. (8589934591 bytes)
+.TP
+.B hpbin
+The obsolete binary format used by HPUX's cpio (which stores
+device files differently).
+.TP
+.B hpodc
+The portable format used by HPUX's cpio (which stores device
+files differently).
+.RE
+.TP
+\fB\-R\fR, \fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]
+In copy-in and copy-pass mode, set the ownership of all files created
+to the specified \fIUSER\fR and/or \fIGROUP\fR.  In copy-out mode,
+store the supplied owner information in the archive.
+
+\fIUSER\fR and \fIGROUP\fR are first looked up in the system user and
+group databases.  If not found, \fBcpio\fR checks if they consist of
+decimal digits only and, if so, treats them as numeric UID and GID,
+correspondingly.
+
+To avoid the lookup and ensure that arguments are treated as numeric
+values, prefix them with a plus sign, e.g.: \fB-R +0:+0\fR.
+.TP
+.B \-\-quiet
+Do not print the number of blocks copied at the end of the run.
+.TP
+.BI \-\-rsh\-command= COMMAND
+Use remote \fICOMMAND\fR instead of \fBrsh\fR.
+.TP
+.BR \-v ", " \-\-verbose
+Verbosely list the files processed.
+.TP
+.BR \-V ", " \-\-dot
+Print a "\fB.\fR" for each file processed.
+.TP
+\fB\-W\fR, \fB\-\-warning=\fIFLAG\fR
+Controls what warnings are displayed.  The \fIFLAG\fR is one of
+.BR none ,
+to disable all warnings,
+.BR all
+to enable them,
+.BR truncate ,
+to enable warnings about field truncation, and
+.BR no\-truncate ,
+to disable them.
+
+Multiple \fB\-W\fR options accumulate.
+.SS Operation modifiers valid in copy-in and copy-out modes
+.TP
+\fB\-F\fR, \fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-FILE\fR
+Use this \fIARCHIVE-FILE\fR instead of standard input (in copy-in
+mode) or standard output (in copy-out mode).  Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+.TP
+\fB\-M\fR, \fB\-\-message=\fISTRING\fR
+Print \fISTRING\fR when the end of a volume of the backup media is reached.
+.SS Operation modifiers valid only in copy-in mode
+.TP
+.BR \-b ", " \-\-swap
+Swap both halfwords of words and bytes of halfwords in the data.
+Equivalent to \fB\-sS\fR.
+.TP
+.BR \-f ", " \-\-nonmatching
+Only copy files that do not match any of the given patterns.
+.TP
+.BR \-n ", " \-\-numeric\-uid\-gid
+In the verbose table of contents listing, show numeric UID and GID.
+.\" FIXME: special meaning when storing tar files.
+.TP
+.BR \-r ", " \-\-rename
+Interactively rename files.
+.TP
+.BR \-s ", " \-\-swap\-bytes
+Swap the bytes of each halfword in the files.
+.TP
+.BR \-S ", " \-\-swap\-halfwords
+Swap the halfwords of each word (4 bytes) in the files.
+.TP
+.B \-\-to\-stdout
+Extract files to standard output.
+.TP
+\fB\-E\fR, \fB\-\-pattern\-file=\fIFILE\fR
+Read additional patterns specifying filenames to extract or list from
+\fIFILE\fR.
+.TP
+.B \-\-only\-verify\-crc
+When reading a CRC format archive, only verify the CRC's of each file
+in the archive, without actually extracting the files.
+.SS Operation modifiers valid only in copy-out mode
+.TP
+.BR \-A ", " \-\-append
+Append to an existing archive.
+.TP
+.BR \-\-device\-independent ", " \-\-reproducible
+Create reproducible archives.  This is equivalent to
+.BR "\-\-ignore\-devno \-\-ignore\-dirnlink \-\-renumber\-inodes" .
+.TP
+.B \-\-ignore\-devno
+Store 0 in the device number field of each archive member, instead of
+the actual device number.
+.TP
+.B \-\-ignore\-dirnlink
+Store 2 in the
+.I nlink
+field of each directory archive member,
+instead of the actual number of links.
+.TP
+\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
+Use \fIARCHIVE-NAME\fR instead of standard output. Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+
+The output archive name can be specified either using this option, or
+using \fB\-F\fR (\fB\-\-file\fR), but not both.
+.TP
+.B \-\-renumber\-inodes
+Renumber inodes when storing them in the archive.
+.SS Operation modifiers valid only in copy-pass mode
+.TP
+.BR \-l ", " \-\-link
+Link files instead of copying them, when possible.
+.SS Operation modifiers valid in copy-in and copy-out modes
+.TP
+.B \-\-absolute\-filenames
+Do not strip file system prefix components from the file names.  This
+is the default.
+.TP
+.B \-\-no\-absolute\-filenames
+Create all files relative to the current directory.
+.SS Operation modifiers valid in copy-out and copy-pass modes
+.TP
+.BR \-0 ", " \-\-null
+Filenames in the list are delimited by null characters instead of
+newlines.
+.TP
+.BR \-a ", " \-\-reset\-access\-time
+Reset the access times of files after reading them.
+.TP
+\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
+Use \fIARCHIVE-NAME\fR instead of standard input. Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+
+The input archive name can be specified either using this option, or
+using \fB\-F\fR (\fB\-\-file\fR), but not both.
+.TP
+.BR \-L ", " \-\-dereference
+Dereference symbolic links (copy the files that they point to instead
+of copying the links).
+.SS Operation modifiers valid in copy-in and copy-pass modes
+.TP
+.BR \-d ", " \-\-make\-directories
+Create leading directories where needed.
+.TP
+.BR \-m ", " \-\-preserve\-modification\-time
+Retain previous file modification times when creating files.
+.TP
+.B \-\-no\-preserve\-owner
+Do not change the ownership of the files.
+.TP
+.B \-\-sparse
+Write files with large blocks of zeros as sparse files.
+.TP
+.BR \-u ", " \-\-unconditional
+Replace all files unconditionally.
+.SH "RETURN VALUE"
+GNU \fBcpio\fR exits with code \fB0\fR if it was able to successfully
+complete the requested operation.  On errors, it exits with code \fB2\fR.
+.SH "SEE ALSO"
+.BR tar (1),
+.BR rmt (8),
+.BR mt (1).
+.SH "BUG REPORTS"
+Report bugs to <bug\-cpio@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2014--2023 Free Software Foundation, Inc.
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/upstream/mageia-cauldron/man1/cronnext.1 b/upstream/mageia-cauldron/man1/cronnext.1
new file mode 100644
index 00000000..deacf7cc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cronnext.1
@@ -0,0 +1,86 @@
+.TH CRONNEXT 1 "2017-06-11" "cronie" "User Commands"
+.SH NAME
+cronnext \- time of next job cron will execute
+.SH SYNOPSIS
+.TP 9
+.B cronnext
+[\fB-i \fIusers\fR] [\fB-e \fIusers\fR] [\fB-s\fR]
+[\fB-a\fR]
+[\fB-t \fItime\fR] [\fB-q \fItime\fR] [\fB-j \fIcommand\fR]
+[\fB-l\fR] [\fB-c\fR] [\fB-f\fR] [\fB-h\fR] [\fB-V\fR]
+[file]...
+.SH DESCRIPTION
+Determine the time cron will execute the next job.  Without arguments, it
+prints that time considering all crontabs, in number of seconds since the
+Epoch, rounded to the minute. This number can be converted into other formats
+using
+.BR date (1),
+like
+.B date --date @43243254
+
+The file arguments are optional. If provided,
+.I cronnext
+uses them as crontabs instead of the ones installed in the system.
+.SH OPTIONS
+.TP
+.BI "\-i " user,user,user,...
+Consider only the crontabs of the specified users.  Use
+.B *system*
+for the system crontab.
+.TP
+.BI "\-e " user,user,user,...
+Do not consider the crontabs of the specified users.
+.TP
+.B \-s
+Do not consider the system crontab, usually the
+.I /etc/crontab
+file.  The system crontab usually contains the hourly, daily, weekly and
+montly crontabs, which might be better dealt with
+.BR anacron (8).
+.TP
+.BI \-a
+Use the crontabs installed in the system in addition to the ones passed as
+file arguments. This is implicit if no file is passed.
+.TP
+.BI "\-t " time
+Determine the next job from this time, instead of now.  The time is
+expressed in number of seconds since the Epoch, as obtained for example by
+.BR "date +%s --date \(dqnow + 2 hours\(dq" ,
+and is internally rounded to the minute.
+.TP
+.BI "\-q " time
+Do not check jobs over this time, expressed in the same way as in option
+.BR -t .
+.TP
+.BI "\-j " command
+Only look for jobs that contain \fIcommand\fP as a substring.
+.TP
+.B \-l
+Print the whole entries of the jobs that are the next to be executed by cron.
+The default is to only print their next time of execution.
+.TP
+.B \-c
+Print every entry in every crontab with the next time it is executed.
+.TP
+.B \-f
+Print all jobs that are executed in the given interval. Requires option
+\fB-q\fR.
+.TP
+.B \-h
+Print usage output and exit.
+.TP
+.B \-V
+Print version and exit.
+.SH AUTHOR
+.MT sgerwk@aol.com
+Marco Migliori
+.ME
+.SH SEE ALSO
+.BR cron (8),
+.BR cron (1),
+.BR crontab (5),
+.BR crontab (1),
+.BR anacron (8),
+.BR anacrontab (5),
+.BR atq (1),
+.BR date (1)
diff --git a/upstream/mageia-cauldron/man1/crontab.1 b/upstream/mageia-cauldron/man1/crontab.1
new file mode 100644
index 00000000..d080ceff
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/crontab.1
@@ -0,0 +1,251 @@
+.\"/* Copyright 1988,1990,1993 by Paul Vixie
+.\" * All rights reserved
+.\" */
+.\"
+.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" Modified 2010/09/12 by Colin Dean, Durham University IT Service,
+.\" to add clustering support.
+.\"
+.\" $Id: crontab.1,v 1.7 2004/01/23 19:03:32 vixie Exp $
+.\"
+.TH CRONTAB 1 "2019-10-29" "cronie" "User Commands"
+.SH NAME
+crontab \- maintains crontab files for individual users
+.SH SYNOPSIS
+.B crontab
+.RB [ -u
+.IR user ]
+.RI < "file"
+.RB | \ - >
+.br
+.B crontab
+.RB [ -T ]
+.RI < "file"
+.RB | \ - >
+.br
+.B crontab
+.RB [ -u
+.IR user ]
+.RB < -l " | " -r " | " -e >\ [ -i ]
+.RB [ -s ]
+.br
+.B crontab
+.BR -n \ [
+.IR "hostname " ]
+.br
+.B crontab
+.BR -c
+.br
+.B crontab
+.BR -V
+.SH DESCRIPTION
+.I Crontab
+is the program used to install a crontab table
+.IR file ,
+remove or list the existing tables used to serve the
+.BR cron (8)
+daemon.  Each user can have their own crontab, and though these are files
+in
+.IR /var/spool/ ,
+they are not intended to be edited directly.  For SELinux in MLS mode,
+you can define more crontabs for each range.  For more information, see
+.BR selinux (8).
+.PP
+In this version of
+.IR Cron
+it is possible to use a network-mounted shared
+.I /var/spool/cron
+across a cluster of hosts and specify that only one of the hosts should
+run the crontab jobs in the particular directory at any one time.  You
+may also use
+.BR crontab
+from any of these hosts to edit the same shared set of crontab files, and
+to set and query which host should run the crontab jobs.
+.PP
+Scheduling cron jobs with
+.BR crontab
+can be allowed or disallowed for different users.  For this purpose, use the
+.I cron.allow
+and
+.I cron.deny
+files.  If the
+.I cron.allow
+file exists, a user must be listed in it to be allowed to use
+.BR crontab .
+If the
+.I cron.allow
+file does not exist but the
+.I cron.deny
+file does exist, then a user must
+.I not
+be listed in the
+.I cron.deny
+file in order to use
+.BR crontab.
+If neither of these files exist, then only the super user is allowed to use
+.BR crontab .
+.PP
+Another way to restrict the scheduling of cron jobs beyond
+.BR crontab
+is to use PAM authentication in
+.I /etc/security/access.conf
+to set up users, which are allowed or disallowed to use
+.BR crontab
+or modify system cron jobs in the
+.IR /etc/cron.d/
+directory.
+.PP
+The temporary directory can be set in an environment variable.  If it is
+not set by the user, the
+.I /tmp
+directory is used.
+.PP
+When listing a crontab on a terminal the output will be colorized unless
+an environment variable
+.I NO_COLOR
+is set.
+.PP
+.SH "OPTIONS"
+.TP
+.B "\-u"
+Specifies the name of the user whose crontab is to be modified.  If this
+option is not used,
+.BR crontab
+examines "your" crontab, i.e., the crontab of the person executing the
+command. If no crontab exists for a particular user, it is created for
+them the first time the
+.B crontab -u
+command is used under their username.
+.TP
+.B "\-T"
+Test the crontab file syntax without installing it. 
+Once an issue is found, the validation is interrupted, so this will not return all the existing issues at the same execution.
+.TP
+.B "\-l"
+Displays the current crontab on standard output.
+.TP
+.B "\-r"
+Removes the current crontab.
+.TP
+.B "\-e"
+Edits the current crontab using the editor specified by the
+.I VISUAL
+or
+.I EDITOR
+environment variables.  After you exit from the editor, the modified
+crontab will be installed automatically.
+.TP
+.B "\-i"
+This option modifies the
+.B "\-r"
+option to prompt the user for a 'y/Y' response before actually removing
+the crontab.
+.TP
+.B "\-s"
+Appends the current SELinux security context string as an MLS_LEVEL
+setting to the crontab file before editing / replacement occurs - see the
+documentation of MLS_LEVEL in
+.BR crontab (5).
+.TP
+.B "\-n"
+This option is relevant only if
+.BR cron (8)
+was started with the
+.B \-c
+option, to enable clustering support.  It is used to set the host in the
+cluster which should run the jobs specified in the crontab files in the
+.I /var/spool/cron
+directory.  If a hostname is supplied, the host whose hostname returned
+by
+.BR gethostname (2)
+matches the supplied hostname, will be selected to run the selected cron jobs subsequently.  If there
+is no host in the cluster matching the supplied hostname, or you explicitly specify
+an empty hostname, then the selected jobs will not be run at all.  If the hostname
+is omitted, the name of the local host returned by
+.BR gethostname (2)
+is used.  Using this option has no effect on the
+.I /etc/crontab
+file and the files in the
+.I /etc/cron.d
+directory, which are always run, and considered host-specific.  For more
+information on clustering support, see
+.BR cron (8).
+.TP
+.B "\-c"
+This option is only relevant if
+.BR cron (8)
+was started with the
+.B \-c
+option, to enable clustering support.  It is used to query which host in
+the cluster is currently set to run the jobs specified in the crontab
+files in the directory
+.I /var/spool/cron
+, as set using the
+.B \-n
+option.
+.TP
+.B "\-V"
+Print version and exit.
+.SH CAVEATS
+The files
+.I cron.allow
+and
+.I cron.deny
+cannot be used to restrict the execution of cron jobs; they only restrict the
+use of
+.BR crontab .
+In particular, restricting access to
+.BR crontab
+has no effect on an existing
+.I crontab
+of a user. Its jobs will continue to be executed until the crontab is removed.
+.PP
+The files
+.I cron.allow
+and
+.I cron.deny
+must be readable by the user invoking
+.BR crontab .
+If this is not the case, then they are treated as non-existent.
+.SH "SEE ALSO"
+.BR crontab (5),
+.BR cron (8)
+.SH FILES
+.nf
+/etc/cron.allow
+/etc/cron.deny
+.fi
+.SH STANDARDS
+The
+.I crontab
+command conforms to IEEE Std1003.2-1992 (``POSIX'') with one exception:
+For replacing the current crontab with data from standard input the
+.B \-
+has to be specified on the command line if the standard input is a TTY.
+This new command syntax differs from previous versions of Vixie Cron,
+as well as from the classic SVR3 syntax.
+.SH DIAGNOSTICS
+An informative usage message appears if you run a crontab with a faulty
+command defined in it.
+.SH AUTHOR
+.MT vixie@isc.org
+Paul Vixie
+.ME
+.br
+.MT colin@colin-dean.org
+Colin Dean
+.ME
diff --git a/upstream/mageia-cauldron/man1/csplit.1 b/upstream/mageia-cauldron/man1/csplit.1
new file mode 100644
index 00000000..3132f193
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/csplit.1
@@ -0,0 +1,77 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CSPLIT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+csplit \- split a file into sections determined by context lines
+.SH SYNOPSIS
+.B csplit
+[\fI\,OPTION\/\fR]... \fI\,FILE PATTERN\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output pieces of FILE separated by PATTERN(s) to files 'xx00', 'xx01', ...,
+and output byte counts of each piece to standard output.
+.PP
+Read standard input if FILE is \-
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-suffix\-format\fR=\fI\,FORMAT\/\fR
+use sprintf FORMAT instead of %02d
+.TP
+\fB\-f\fR, \fB\-\-prefix\fR=\fI\,PREFIX\/\fR
+use PREFIX instead of 'xx'
+.TP
+\fB\-k\fR, \fB\-\-keep\-files\fR
+do not remove output files on errors
+.TP
+\fB\-\-suppress\-matched\fR
+suppress the lines matching PATTERN
+.TP
+\fB\-n\fR, \fB\-\-digits\fR=\fI\,DIGITS\/\fR
+use specified number of digits instead of 2
+.TP
+\fB\-s\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+do not print counts of output file sizes
+.TP
+\fB\-z\fR, \fB\-\-elide\-empty\-files\fR
+remove empty output files
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SS "Each PATTERN may be:"
+.TP
+INTEGER
+copy up to but not including specified line number
+.TP
+/REGEXP/[OFFSET]
+copy up to but not including a matching line
+.TP
+%REGEXP%[OFFSET]
+skip to, but not including a matching line
+.TP
+{INTEGER}
+repeat the previous pattern specified number of times
+.TP
+{*}
+repeat the previous pattern as many times as possible
+.PP
+A line OFFSET is an integer optionally preceded by '+' or '\-'
+.SH AUTHOR
+Written by Stuart Kemp and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/csplit>
+.br
+or available locally via: info \(aq(coreutils) csplit invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/cu.1 b/upstream/mageia-cauldron/man1/cu.1
new file mode 100644
index 00000000..67e0f066
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cu.1
@@ -0,0 +1,304 @@
+''' $Id: cu.1,v 1.10 2002/03/05 22:13:33 ian Rel $
+.TH cu 1 "Taylor UUCP 1.07"
+.SH NAME
+cu \- Call up another system
+.SH SYNOPSIS
+.B cu
+[ options ] [ system | phone | "dir" ]
+.SH DESCRIPTION
+The
+.I cu
+command is used to call up another system and act as a dial in
+terminal.  It can also do simple file transfers with no error
+checking.
+
+.I cu
+takes a single argument, besides the options.  If the argument is the
+string "dir" cu will make a direct connection to the port.  This may
+only be used by users with write access to the port, as it permits
+reprogramming the modem.
+
+Otherwise, if the argument begins with a digit, it is taken to be a
+phone number to call.  Otherwise, it is taken to be the name of a
+system to call.  The
+.B \-z
+or
+.B \-\-system
+option may be used to name a system beginning with a digit, and the
+.B \-c
+or
+.B \-\-phone
+option may be used to name a phone number that does not begin with a
+digit.
+
+.I cu
+locates a port to use in the UUCP configuration files.  If a simple
+system name is given, it will select a port appropriate for that
+system.  The
+.B \-p, \-\-port, \-l, \-\-line, \-s
+and
+.B \-\-speed
+options may be used to control the port selection.
+
+When a connection is made to the remote system,
+.I cu
+forks into two processes.  One reads from the port and writes to the
+terminal, while the other reads from the terminal and writes to the
+port.
+
+.I cu
+provides several commands that may be used during the conversation.
+The commands all begin with an escape character, initially
+.B ~
+(tilde).  The escape character is only recognized at the beginning of
+a line.  To send an escape character to the remote system at the start
+of a line, it must be entered twice.  All commands are either a single
+character or a word beginning with
+.B %
+(percent sign).
+
+.I cu
+recognizes the following commands:
+
+.TP 5
+.B ~.
+Terminate the conversation.
+.TP 5
+.B ~! command
+Run command in a shell.  If command is empty, starts up a shell.
+.TP 5
+.B ~$ command
+Run command, sending the standard output to the remote system.
+.TP 5
+.B ~| command
+Run command, taking the standard input from the remote system.
+.TP 5
+.B ~+ command
+Run command, taking the standard input from the remote system and
+sending the standard output to the remote system.
+.TP 5
+.B ~#, ~%break
+Send a break signal, if possible.
+.TP 5
+.B ~c directory, ~%cd directory
+Change the local directory.
+.TP 5
+.B ~> file
+Send a file to the remote system.  This just dumps the file over the
+communication line.  It is assumed that the remote system is expecting
+it.
+.TP 5
+.B ~<
+Receive a file from the remote system.  This prompts for the local
+file name and for the remote command to execute to begin the file
+transfer.  It continues accepting data until the contents of the
+.B eofread
+variable are seen.
+.TP 5
+.B ~p from to, ~%put from to
+Send a file to a remote Unix system.  This runs the appropriate
+commands on the remote system.
+.TP 5
+.B ~t from to, ~%take from to
+Retrieve a file from a remote Unix system.  This runs the appropriate
+commands on the remote system.
+.TP 5
+.B ~s variable value
+Set a
+.I cu
+variable to the given value.  If value is not given, the variable is
+set to
+.B true.
+.TP 5
+.B ~! variable
+Set a
+.I cu
+variable to
+.B false.
+.TP 5
+.B ~z
+Suspend the cu session.  This is only supported on some systems.  On
+systems for which ^Z may be used to suspend a job, 
+.B ~^Z
+will also suspend the session.
+.TP 5
+.B ~%nostop
+Turn off XON/XOFF handling.
+.TP 5
+.B ~%stop
+Turn on XON/XOFF handling.
+.TP 5
+.B ~v
+List all the variables and their values.
+.TP 5
+.B ~?
+List all commands.
+
+.I cu
+also supports several variables.  They may be listed with the
+.B ~v
+command, and set with the
+.B ~s
+or
+.B ~!
+commands.
+
+.TP 5
+.B escape
+The escape character.  Initially
+.B ~
+(tilde).
+.TP 5
+.B delay
+If this variable is true,
+.I cu
+will delay for a second after recognizing the escape character before
+printing the name of the local system.  The default is true.
+.TP 5
+.B eol
+The list of characters which are considered to finish a line.  The
+escape character is only recognized after one of these is seen.  The
+default is carriage return, ^U, ^C, ^O, ^D, ^S, ^Q, ^R.
+.TP 5
+.B binary
+Whether to transfer binary data when sending a file.  If this is
+false, then newlines in the file being sent are converted to carriage
+returns.  The default is false.
+.TP 5
+.B binary-prefix
+A string used before sending a binary character in a file transfer, if
+the
+.B binary
+variable is true.  The default is ^V.
+.TP 5
+.B echo-check
+Whether to check file transfers by examining what the remote system
+echoes back.  This probably doesn't work very well.  The default is
+false.
+.TP 5
+.B echonl
+The character to look for after sending each line in a file.  The
+default is carriage return.
+.TP 5
+.B timeout
+The timeout to use, in seconds, when looking for a character, either
+when doing echo checking or when looking for the
+.B echonl
+character.  The default is 30.
+.TP 5
+.B kill
+The character to use delete a line if the echo check fails.  The
+default is ^U.
+.TP 5
+.B resend
+The number of times to resend a line if the echo check continues to
+fail.  The default is 10.
+.TP 5
+.B eofwrite
+The string to write after sending a file with the
+.B ~>
+command.  The default is ^D.
+.TP 5
+.B eofread
+The string to look for when receiving a file with the
+.B ~<
+command.  The default is $, which is intended to be a typical shell
+prompt.
+.TP 5
+.B verbose
+Whether to print accumulated information during a file transfer.  The
+default is true.
+.SH OPTIONS
+The following options may be given to
+.I cu.
+.TP 5
+.B \-e, \-\-parity=even
+Use even parity.
+.TP 5
+.B \-o, \-\-parity=odd
+Use odd parity.
+.TP 5
+.B \-\-parity=none
+Use no parity.  No parity is also used if both
+.B \-e
+and
+.B \-o
+are given.
+.TP 5
+.B \-h, \-\-halfduplex
+Echo characters locally (half-duplex mode).
+.TP 5
+.B \-\-nostop
+Turn off XON/XOFF handling (it is on by default).
+.TP 5
+.B \-E char, \-\-escape char
+Set the escape character.  Initially
+.B ~
+(tilde).  To eliminate the escape character, use
+.B -E ''.
+.TP 5
+.B \-z system, \-\-system system
+The system to call.
+.TP 5
+.B \-c phone-number, \-\-phone phone-number
+The phone number to call.
+.TP 5
+.B \-p port, \-\-port port
+Name the port to use.
+.TP 5
+.B \-a port
+Equivalent to
+.B \-\-port port.
+.TP 5
+.B \-l line, \-\-line line
+Name the line to use by giving a device name.  This may be used to
+dial out on ports that are not listed in the UUCP configuration files.
+Write access to the device is required.
+.TP 5
+.B \-s speed, \-\-speed speed
+The speed (baud rate) to use.
+.TP 5
+.B \-#
+Where # is a number, equivalent to
+.B \-\-speed #.
+.TP 5
+.B \-n, \-\-prompt
+Prompt for the phone number to use.
+.TP 5
+.B \-d
+Enter debugging mode.  Equivalent to
+.B \-\-debug all.
+.TP 5
+.B \-x type, \-\-debug type
+Turn on particular debugging types.  The following types are
+recognized: abnormal, chat, handshake, uucp-proto, proto, port,
+config, spooldir, execute, incoming, outgoing.  Only abnormal, chat,
+handshake, port, config, incoming and outgoing are meaningful for
+.I cu.
+
+Multiple types may be given, separated by commas, and the
+.B \-\-debug
+option may appear multiple times.  A number may also be given, which
+will turn on that many types from the foregoing list; for example,
+.B \-\-debug 2
+is equivalent to
+.B \-\-debug abnormal,chat.
+.B \-\-debug all
+may be used to turn on all debugging options.
+.TP 5
+.B \-I file, \-\-config file
+Set configuration file to use.  This option may not be available,
+depending upon how
+.I cu
+was compiled.
+.TP 5
+.B \-v, \-\-version
+Report version information and exit.
+.TP 5
+.B \-\-help
+Print a help message and exit.
+.SH BUGS
+This program does not work very well.
+.SH AUTHOR
+Ian Lance Taylor
+<ian@airs.com>
diff --git a/upstream/mageia-cauldron/man1/cut.1 b/upstream/mageia-cauldron/man1/cut.1
new file mode 100644
index 00000000..9c680ff6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/cut.1
@@ -0,0 +1,85 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH CUT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+cut \- remove sections from each line of files
+.SH SYNOPSIS
+.B cut
+\fI\,OPTION\/\fR... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print selected parts of lines from each FILE to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-bytes\fR=\fI\,LIST\/\fR
+select only these bytes
+.TP
+\fB\-c\fR, \fB\-\-characters\fR=\fI\,LIST\/\fR
+select only these characters
+.TP
+\fB\-d\fR, \fB\-\-delimiter\fR=\fI\,DELIM\/\fR
+use DELIM instead of TAB for field delimiter
+.TP
+\fB\-f\fR, \fB\-\-fields\fR=\fI\,LIST\/\fR
+select only these fields;  also print any line
+that contains no delimiter character, unless
+the \fB\-s\fR option is specified
+.TP
+\fB\-n\fR
+with \fB\-b\fR: don't split multibyte characters
+.TP
+\fB\-\-complement\fR
+complement the set of selected bytes, characters
+or fields
+.TP
+\fB\-s\fR, \fB\-\-only\-delimited\fR
+do not print lines not containing delimiters
+.TP
+\fB\-\-output\-delimiter\fR=\fI\,STRING\/\fR
+use STRING as the output delimiter
+the default is to use the input delimiter
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Use one, and only one of \fB\-b\fR, \fB\-c\fR or \fB\-f\fR.  Each LIST is made up of one
+range, or many ranges separated by commas.  Selected input is written
+in the same order that it is read, and is written exactly once.
+Each range is one of:
+.TP
+N
+N'th byte, character or field, counted from 1
+.TP
+N\-
+from N'th byte, character or field, to end of line
+.TP
+N\-M
+from N'th to M'th (included) byte, character or field
+.TP
+\fB\-M\fR
+from first to M'th (included) byte, character or field
+.SH AUTHOR
+Written by David M. Ihnat, David MacKenzie, and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/cut>
+.br
+or available locally via: info \(aq(coreutils) cut invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/date.1 b/upstream/mageia-cauldron/man1/date.1
new file mode 100644
index 00000000..6f0cd0e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/date.1
@@ -0,0 +1,271 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DATE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+date \- print or set the system date and time
+.SH SYNOPSIS
+.B date
+[\fI\,OPTION\/\fR]... [\fI\,+FORMAT\/\fR]
+.br
+.B date
+[\fI\,-u|--utc|--universal\/\fR] [\fI\,MMDDhhmm\/\fR[[\fI\,CC\/\fR]\fI\,YY\/\fR][\fI\,.ss\/\fR]]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Display date and time in the given FORMAT.
+With \fB\-s\fR, or with [MMDDhhmm[[CC]YY][.ss]], set the date and time.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-d\fR, \fB\-\-date\fR=\fI\,STRING\/\fR
+display time described by STRING, not 'now'
+.TP
+\fB\-\-debug\fR
+annotate the parsed date,
+and warn about questionable usage to stderr
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fI\,DATEFILE\/\fR
+like \fB\-\-date\fR; once for each line of DATEFILE
+.TP
+\fB\-I[FMT]\fR, \fB\-\-iso\-8601\fR[=\fI\,FMT\/\fR]
+output date/time in ISO 8601 format.
+FMT='date' for date only (the default),
+\&'hours', 'minutes', 'seconds', or 'ns'
+for date and time to the indicated precision.
+Example: 2006\-08\-14T02:34:56\-06:00
+.TP
+\fB\-\-resolution\fR
+output the available resolution of timestamps
+Example: 0.000000001
+.TP
+\fB\-R\fR, \fB\-\-rfc\-email\fR
+output date and time in RFC 5322 format.
+Example: Mon, 14 Aug 2006 02:34:56 \fB\-0600\fR
+.TP
+\fB\-\-rfc\-3339\fR=\fI\,FMT\/\fR
+output date/time in RFC 3339 format.
+FMT='date', 'seconds', or 'ns'
+for date and time to the indicated precision.
+Example: 2006\-08\-14 02:34:56\-06:00
+.TP
+\fB\-r\fR, \fB\-\-reference\fR=\fI\,FILE\/\fR
+display the last modification time of FILE
+.TP
+\fB\-s\fR, \fB\-\-set\fR=\fI\,STRING\/\fR
+set time described by STRING
+.TP
+\fB\-u\fR, \fB\-\-utc\fR, \fB\-\-universal\fR
+print or set Coordinated Universal Time (UTC)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+FORMAT controls the output.  Interpreted sequences are:
+.TP
+%%
+a literal %
+.TP
+%a
+locale's abbreviated weekday name (e.g., Sun)
+.TP
+%A
+locale's full weekday name (e.g., Sunday)
+.TP
+%b
+locale's abbreviated month name (e.g., Jan)
+.TP
+%B
+locale's full month name (e.g., January)
+.TP
+%c
+locale's date and time (e.g., Thu Mar  3 23:05:25 2005)
+.TP
+%C
+century; like %Y, except omit last two digits (e.g., 20)
+.TP
+%d
+day of month (e.g., 01)
+.TP
+%D
+date; same as %m/%d/%y
+.TP
+%e
+day of month, space padded; same as %_d
+.TP
+%F
+full date; like %+4Y\-%m\-%d
+.TP
+%g
+last two digits of year of ISO week number (see %G)
+.TP
+%G
+year of ISO week number (see %V); normally useful only with %V
+.TP
+%h
+same as %b
+.TP
+%H
+hour (00..23)
+.TP
+%I
+hour (01..12)
+.TP
+%j
+day of year (001..366)
+.TP
+%k
+hour, space padded ( 0..23); same as %_H
+.TP
+%l
+hour, space padded ( 1..12); same as %_I
+.TP
+%m
+month (01..12)
+.TP
+%M
+minute (00..59)
+.TP
+%n
+a newline
+.TP
+%N
+nanoseconds (000000000..999999999)
+.TP
+%p
+locale's equivalent of either AM or PM; blank if not known
+.TP
+%P
+like %p, but lower case
+.TP
+%q
+quarter of year (1..4)
+.TP
+%r
+locale's 12\-hour clock time (e.g., 11:11:04 PM)
+.TP
+%R
+24\-hour hour and minute; same as %H:%M
+.TP
+%s
+seconds since the Epoch (1970\-01\-01 00:00 UTC)
+.TP
+%S
+second (00..60)
+.TP
+%t
+a tab
+.TP
+%T
+time; same as %H:%M:%S
+.TP
+%u
+day of week (1..7); 1 is Monday
+.TP
+%U
+week number of year, with Sunday as first day of week (00..53)
+.TP
+%V
+ISO week number, with Monday as first day of week (01..53)
+.TP
+%w
+day of week (0..6); 0 is Sunday
+.TP
+%W
+week number of year, with Monday as first day of week (00..53)
+.TP
+%x
+locale's date representation (e.g., 12/31/99)
+.TP
+%X
+locale's time representation (e.g., 23:13:48)
+.TP
+%y
+last two digits of year (00..99)
+.TP
+%Y
+year
+.TP
+%z
++hhmm numeric time zone (e.g., \fB\-0400\fR)
+.TP
+%:z
++hh:mm numeric time zone (e.g., \fB\-04\fR:00)
+.TP
+%::z
++hh:mm:ss numeric time zone (e.g., \fB\-04\fR:00:00)
+.TP
+%:::z
+numeric time zone with : to necessary precision (e.g., \fB\-04\fR, +05:30)
+.TP
+%Z
+alphabetic time zone abbreviation (e.g., EDT)
+.PP
+By default, date pads numeric fields with zeroes.
+The following optional flags may follow '%':
+.TP
+\-
+(hyphen) do not pad the field
+.TP
+_
+(underscore) pad with spaces
+.TP
+0
+(zero) pad with zeros
+.TP
++
+pad with zeros, and put '+' before future years with >4 digits
+.TP
+^
+use upper case if possible
+.TP
+#
+use opposite case if possible
+.PP
+After any flags comes an optional field width, as a decimal number;
+then an optional modifier, which is either
+E to use the locale's alternate representations if available, or
+O to use the locale's alternate numeric symbols if available.
+.SH EXAMPLES
+Convert seconds since the Epoch (1970\-01\-01 UTC) to a date
+.IP
+\f(CW$ date --date='@2147483647'\fR
+.PP
+Show the time on the west coast of the US (use \fBtzselect\fP(1) to find TZ)
+.IP
+\f(CW$ TZ='America/Los_Angeles' date\fR
+.PP
+Show the local time for 9AM next Friday on the west coast of the US
+.IP
+\f(CW$ date --date='TZ="America/Los_Angeles" 09:00 next Fri'\fR
+.SH "DATE STRING"
+.\" NOTE: keep this paragraph in sync with the one in touch.x
+The --date=STRING is a mostly free format human readable date string
+such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or
+even "next Thursday".  A date string may contain items indicating
+calendar date, time of day, time zone, day of week, relative time,
+relative date, and numbers.  An empty string indicates the beginning
+of the day.  The date string format is more complex than is easily
+documented here but is fully described in the info documentation.
+.SH ENVIRONMENT
+.TP
+TZ
+Specifies the timezone, unless overridden by command line parameters.
+If neither is specified, the setting from /etc/localtime is used.
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/date>
+.br
+or available locally via: info \(aq(coreutils) date invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/dc.1 b/upstream/mageia-cauldron/man1/dc.1
new file mode 100644
index 00000000..1c666493
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dc.1
@@ -0,0 +1,520 @@
+.\"
+.\" dc.1 - the *roff document processor source for the dc manual
+.\"
+.\" This file is part of GNU dc.
+.\" Copyright (C) 1994, 1997, 1998, 2000, 2001, 2005, 2006, 2008, 2013, 2016
+.\" Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to copy, distribute and/or modify this document
+.\" under the terms of the GNU Free Documentation License, Version 1.2 or
+.\" any later version published by the Free Software Foundation; with no
+.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+.\" Texts.
+.\"
+.TH dc 1 "2008-05-22" "GNU Project"
+.ds dc \fIdc\fP
+.ds Dc \fIdc\fP
+.SH NAME
+dc \- an arbitrary precision calculator
+.SH SYNOPSIS
+dc [-V] [--version] [-h] [--help]
+   [-e scriptexpression] [--expression=scriptexpression]
+   [-f scriptfile] [--file=scriptfile]
+   [file ...]
+.SH DESCRIPTION
+.PP
+\*(Dc is a reverse-polish desk calculator which supports
+unlimited precision arithmetic.
+It also allows you to define and call macros.
+Normally \*(dc reads from the standard input;
+if any command arguments are given to it, they are filenames,
+and \*(dc reads and executes the contents of the files before reading
+from standard input.
+All normal output is to standard output;
+all error output is to standard error.
+.PP
+A reverse-polish calculator stores numbers on a stack.
+Entering a number pushes it on the stack.
+Arithmetic operations pop arguments off the stack and push the results.
+.PP
+To enter a number in
+.IR dc ,
+type the digits
+(using upper case letters
+.I A
+through
+.I F
+as "digits" when working
+with input bases greater than ten),
+with an optional decimal point.
+Exponential notation is not supported.
+To enter a negative number,
+begin the number with ``_''.
+``-'' cannot be used for this,
+as it is a binary operator for subtraction instead.
+To enter two numbers in succession,
+separate them with spaces or newlines.
+These have no meaning as commands.
+.SH OPTIONS
+\*(Dc may be invoked with the following command-line options:
+.TP
+.B -V
+.TP
+.B --version
+Print out the version of \*(dc that is being run and a copyright notice,
+then exit.
+.TP
+.B -h
+.TP
+.B --help
+Print a usage message briefly summarizing these command-line options
+and the bug-reporting address,
+then exit.
+.TP
+.B -e \fIscript\fP
+.TP
+.BI --expression= script
+Add the commands in
+.I script
+to the set of commands to be run while processing the input.
+.TP
+.B -f \fIscript-file\fP
+.TP
+.BI --file= script-file
+Add the commands contained in the file
+.I script-file
+to the set of commands to be run while processing the input.
+.PP
+If any command-line parameters remain after processing the above,
+these parameters are interpreted as the names of input files to
+be processed.
+A file name of
+.B -
+refers to the standard input stream.
+The standard input will processed if no script files or
+expressions are specified.
+.PD
+.SH
+Printing Commands
+.TP
+.B p
+Prints the value on the top of the stack,
+without altering the stack.
+A newline is printed after the value.
+.TP
+.B n
+Prints the value on the top of the stack, popping it off,
+and does not print a newline after.
+.TP
+.B P
+Pops off the value on top of the stack.
+If it it a string, it is simply printed without a trailing newline.
+Otherwise it is a number, and the integer portion of its absolute
+value is printed out as a "base (UCHAR_MAX+1)" byte stream.
+Assuming that (UCHAR_MAX+1) is 256
+(as it is on most machines with 8-bit bytes),
+the sequence \fBKSK0k1/_1Ss [ls*]Sxd0>x
+[256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx]
+dsxxsx0sqLqsxLxLK+k\fP
+could also accomplish this function.
+(Much of the complexity of the above native-dc code is due
+to the ~ computing the characters backwards,
+and the desire to ensure that all registers wind up back
+in their original states.)
+.TP
+.B f
+Prints the entire contents of the stack
+.ig
+and the contents of all of the registers,
+..
+without altering anything.
+This is a good command to use if you are lost or want
+to figure out what the effect of some command has been.
+.PD
+.SH
+Arithmetic
+.TP
+.B +
+Pops two values off the stack, adds them,
+and pushes the result.
+The precision of the result is determined only
+by the values of the arguments,
+and is enough to be exact.
+.TP
+.B -
+Pops two values,
+subtracts the first one popped from the second one popped,
+and pushes the result.
+.TP
+.B *
+Pops two values, multiplies them, and pushes the result.
+The number of fraction digits in the result depends on
+the current precision value and the number of fraction
+digits in the two arguments.
+.TP
+.B /
+Pops two values,
+divides the second one popped from the first one popped,
+and pushes the result.
+The number of fraction digits is specified by the precision value.
+.TP
+.B %
+Pops two values,
+computes the remainder of the division that the
+.B /
+command would do,
+and pushes that.
+The value computed is the same as that computed by
+the sequence \fBSd dld/ Ld*-\fP .
+.TP
+.B ~
+Pops two values,
+divides the second one popped from the first one popped.
+The quotient is pushed first, and the remainder is pushed next.
+The number of fraction digits used in the division
+is specified by the precision value.
+(The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish
+this function, with slightly different error checking.)
+.TP
+.B ^
+Pops two values and exponentiates,
+using the first value popped as the exponent
+and the second popped as the base.
+The fraction part of the exponent is ignored.
+The precision value specifies the number of fraction
+digits in the result.
+.TP
+.B |
+Pops three values and computes a modular exponentiation.
+The first value popped is used as the reduction modulus;
+this value must be a non-zero number,
+and should be an integer.
+The second popped is used as the exponent;
+this value must be a non-negative number,
+and any fractional part of this exponent will be ignored.
+The third value popped is the base which gets exponentiated,
+which should be an integer.
+For small integers this is like the sequence \fBSm^Lm%\fP,
+but, unlike \fB^\fP, this command will work with arbitrarily large exponents.
+.TP
+.B v
+Pops one value,
+computes its square root,
+and pushes that.
+The maximum of the precision value and the precision of the argument
+is used to determine the number of fraction digits in the result.
+.PP
+Most arithmetic operations are affected by the ``precision value'',
+which you can set with the
+.B k
+command.
+The default precision value is zero,
+which means that all arithmetic except for
+addition and subtraction produces integer results.
+.SH
+Stack Control
+.TP
+.B c
+Clears the stack, rendering it empty.
+.TP
+.B d
+Duplicates the value on the top of the stack,
+pushing another copy of it.
+Thus, ``4d*p'' computes 4 squared and prints it.
+.TP
+.B r
+Reverses the order of (swaps) the top two values on the stack.
+(This can also be accomplished with the sequence \fBSaSbLaLb\fP.)
+.TP
+.B R
+Pops the top-of-stack as an integer
+.IR n .
+Cyclically rotates the top
+.I n
+items on the updated stack.
+If
+.I n
+is positive, then the rotation direction will make the topmost
+element the second-from top;
+if
+.I n
+is negative, then the rotation will make the topmost element the
+.IR n -th
+element from the top.
+If the stack depth is less than
+.IR n ,
+then the entire stack is rotated (in the appropriate direction),
+without any error being reported.
+.SH
+Registers
+.PP
+\*(Dc provides at least 256 memory registers,
+each named by a single character.
+You can store a number or a string in a register and retrieve it later.
+.TP
+.BI s r
+Pop the value off the top of the stack and store
+it into register
+.IR r .
+.TP
+.BI l r
+Copy the value in register
+.I r
+and push it onto the stack.
+The value 0 is retrieved if the register is uninitialized.
+This does not alter the contents of
+.IR r .
+.PP
+Each register also contains its own stack.
+The current register value is the top of the register's stack.
+.TP
+.BI S r
+Pop the value off the top of the (main) stack and
+push it onto the stack of register
+.IR r .
+The previous value of the register becomes inaccessible.
+.TP
+.BI L r
+Pop the value off the top of register
+.IR r 's
+stack and push it onto the main stack.
+The previous value
+in register
+.IR r 's
+stack, if any,
+is now accessible via the
+.BI l r
+command.
+.ig
+.PP
+The
+.B f
+command prints a list of all registers that have contents stored in them,
+together with their contents.
+Only the current contents of each register
+(the top of its stack)
+is printed.
+..
+.SH
+Parameters
+.PP
+\*(Dc has three parameters that control its operation:
+the precision, the input radix, and the output radix.
+The precision specifies the number
+of fraction digits to keep in the result of most arithmetic operations.
+The input radix controls the interpretation of numbers typed in;
+all numbers typed in use this radix.
+The output radix is used for printing numbers.
+.PP
+The input and output radices are separate parameters;
+you can make them unequal,
+which can be useful or confusing.
+The input radix must be between 2 and 16 inclusive.
+The output radix must be at least 2.
+The precision must be zero or greater.
+The precision is always measured in decimal digits,
+regardless of the current input or output radix.
+.TP
+.B i
+Pops the value off the top of the stack
+and uses it to set the input radix.
+.TP
+.B o
+Pops the value off the top of the stack
+and uses it to set the output radix.
+.TP
+.B k
+Pops the value off the top of the stack
+and uses it to set the precision.
+.TP
+.B I
+Pushes the current input radix on the stack.
+.TP
+.B O
+Pushes the current output radix on the stack.
+.TP
+.B K
+Pushes the current precision on the stack.
+.SH
+Strings
+.PP
+\*(Dc has a limited ability to operate on strings
+as well as on numbers;
+the only things you can do with strings are
+print them and execute them as macros
+(which means that the contents of the string are processed as
+\*(dc commands).
+All registers and the stack can hold strings,
+and \*(dc always knows whether any given object is a string or a number.
+Some commands such as arithmetic operations demand numbers
+as arguments and print errors if given strings.
+Other commands can accept either a number or a string;
+for example, the
+.B p
+command can accept either and prints the object
+according to its type.
+.TP
+.BI [ characters ]
+Makes a string containing
+.I characters
+(contained between balanced
+.B [
+and
+.B ]
+characters),
+and pushes it on the stack.
+For example,
+.B [foo]P
+prints the characters
+.B foo
+(with no newline).
+.TP
+.B a
+The top-of-stack is popped.
+If it was a number, then the low-order byte of this number
+is converted into a string and pushed onto the stack.
+Otherwise the top-of-stack was a string,
+and the first character of that string is pushed back.
+.TP
+.B x
+Pops a value off the stack and executes it as a macro.
+Normally it should be a string;
+if it is a number,
+it is simply pushed back onto the stack.
+For example,
+.B [1p]x
+executes the macro
+.B 1p
+which pushes
+.B 1
+on the stack and prints
+.B 1
+on a separate line.
+.PP
+Macros are most often stored in registers;
+.B [1p]sa
+stores a macro to print
+.B 1
+into register
+.BR a ,
+and
+.B lax
+invokes this macro.
+.TP
+.BI > r
+Pops two values off the stack and compares them
+assuming they are numbers,
+executing the contents of register
+.I r
+as a macro if the original top-of-stack
+is greater.
+Thus,
+.B 1 2>a
+will invoke register
+.BR a 's
+contents and
+.B 2 1>a
+will not.
+.TP
+.BI !> r
+Similar but invokes the macro if the original top-of-stack is
+not greater than (less than or equal to) what was the second-to-top.
+.TP
+.BI < r
+Similar but invokes the macro if the original top-of-stack is less.
+.TP
+.BI !< r
+Similar but invokes the macro if the original top-of-stack is
+not less than (greater than or equal to) what was the second-to-top.
+.TP
+.BI = r
+Similar but invokes the macro if the two numbers popped are equal.
+.TP
+.BI != r
+Similar but invokes the macro if the two numbers popped are not equal.
+.ig
+This can also be validly used to compare two strings for equality.
+..
+.TP
+.B ?
+Reads a line from the terminal and executes it.
+This command allows a macro to request input from the user.
+.TP
+.B q
+exits from a macro and also from the macro which invoked it.
+If called from the top level,
+or from a macro which was called directly from the top level,
+the
+.B q
+command will cause \*(dc to exit.
+.TP
+.B Q
+Pops a value off the stack and uses it as a count
+of levels of macro execution to be exited.
+Thus,
+.B 3Q
+exits three levels.
+The
+.B Q
+command will never cause \*(dc to exit.
+.SH
+Status Inquiry
+.TP
+.B Z
+Pops a value off the stack,
+calculates the number of decimal digits it has
+(or number of characters, if it is a string)
+and pushes that number.
+The digit count for a number does
+.I not
+include any leading zeros,
+even if those appear to the right of the radix point.
+.TP
+.B X
+Pops a value off the stack,
+calculates the number of fraction digits it has,
+and pushes that number.
+For a string,
+the value pushed is
+.\" -1.
+0.
+.TP
+.B z
+Pushes the current stack depth:
+the number of objects on the stack before the execution of the
+.B z
+command.
+.SH
+Miscellaneous
+.TP
+.B !
+Will run the rest of the line as a system command.
+Note that parsing of the !<, !=, and !> commands take precedence,
+so if you want to run a command starting with <, =, or > you will
+need to add a space after the !.
+.TP
+.B #
+Will interpret the rest of the line as a comment.
+.TP
+.BI : r
+Will pop the top two values off of the stack.
+The old second-to-top value will be stored in the array
+.IR r ,
+indexed by the old top-of-stack value.
+.TP
+.BI ; r
+Pops the top-of-stack and uses it as an index into
+the array
+.IR r .
+The selected value is then pushed onto the stack.
+.P
+Note that each stacked instance of a register has its own
+array associated with it.
+Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1,
+because the 2 was stored in an instance of 0:a that
+was later popped.
+.SH
+BUGS
+.PP
+Email bug reports to
+.BR bug-dc@gnu.org .
diff --git a/upstream/mageia-cauldron/man1/dd.1 b/upstream/mageia-cauldron/man1/dd.1
new file mode 100644
index 00000000..1934a9da
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dd.1
@@ -0,0 +1,176 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+dd \- convert and copy a file
+.SH SYNOPSIS
+.B dd
+[\fI\,OPERAND\/\fR]...
+.br
+.B dd
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Copy a file, converting and formatting according to the operands.
+.TP
+bs=BYTES
+read and write up to BYTES bytes at a time (default: 512);
+overrides ibs and obs
+.TP
+cbs=BYTES
+convert BYTES bytes at a time
+.TP
+conv=CONVS
+convert the file as per the comma separated symbol list
+.TP
+count=N
+copy only N input blocks
+.TP
+ibs=BYTES
+read up to BYTES bytes at a time (default: 512)
+.TP
+if=FILE
+read from FILE instead of stdin
+.TP
+iflag=FLAGS
+read as per the comma separated symbol list
+.TP
+obs=BYTES
+write BYTES bytes at a time (default: 512)
+.TP
+of=FILE
+write to FILE instead of stdout
+.TP
+oflag=FLAGS
+write as per the comma separated symbol list
+.TP
+seek=N
+(or oseek=N) skip N obs\-sized output blocks
+.TP
+skip=N
+(or iseek=N) skip N ibs\-sized input blocks
+.TP
+status=LEVEL
+The LEVEL of information to print to stderr;
+\&'none' suppresses everything but error messages,
+\&'noxfer' suppresses the final transfer statistics,
+\&'progress' shows periodic transfer statistics
+.PP
+N and BYTES may be followed by the following multiplicative suffixes:
+c=1, w=2, b=512, kB=1000, K=1024, MB=1000*1000, M=1024*1024, xM=M,
+GB=1000*1000*1000, G=1024*1024*1024, and so on for T, P, E, Z, Y.
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+If N ends in 'B', it counts bytes not blocks.
+.PP
+Each CONV symbol may be:
+.TP
+ascii
+from EBCDIC to ASCII
+.TP
+ebcdic
+from ASCII to EBCDIC
+.TP
+ibm
+from ASCII to alternate EBCDIC
+.TP
+block
+pad newline\-terminated records with spaces to cbs\-size
+.TP
+unblock
+replace trailing spaces in cbs\-size records with newline
+.TP
+lcase
+change upper case to lower case
+.TP
+ucase
+change lower case to upper case
+.TP
+sparse
+try to seek rather than write all\-NUL output blocks
+.TP
+swab
+swap every pair of input bytes
+.TP
+sync
+pad every input block with NULs to ibs\-size; when used
+with block or unblock, pad with spaces rather than NULs
+.TP
+excl
+fail if the output file already exists
+.TP
+nocreat
+do not create the output file
+.TP
+notrunc
+do not truncate the output file
+.TP
+noerror
+continue after read errors
+.TP
+fdatasync
+physically write output file data before finishing
+.TP
+fsync
+likewise, but also write metadata
+.PP
+Each FLAG symbol may be:
+.TP
+append
+append mode (makes sense only for output; conv=notrunc suggested)
+.TP
+direct
+use direct I/O for data
+.TP
+directory
+fail unless a directory
+.TP
+dsync
+use synchronized I/O for data
+.TP
+sync
+likewise, but also for metadata
+.TP
+fullblock
+accumulate full blocks of input (iflag only)
+.TP
+nonblock
+use non\-blocking I/O
+.TP
+noatime
+do not update access time
+.TP
+nocache
+Request to drop cache.  See also oflag=sync
+.TP
+noctty
+do not assign controlling terminal from file
+.TP
+nofollow
+do not follow symlinks
+.PP
+Sending a USR1 signal to a running 'dd' process makes it
+print I/O statistics to standard error and then resume copying.
+.PP
+Options are:
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Paul Rubin, David MacKenzie, and Stuart Kemp.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/dd>
+.br
+or available locally via: info \(aq(coreutils) dd invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/ddbugtopbm.1 b/upstream/mageia-cauldron/man1/ddbugtopbm.1
new file mode 100644
index 00000000..5bf76bb7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ddbugtopbm.1
@@ -0,0 +1,117 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ddbugtopbm User Manual" 0 "21 August 2002" "netpbm documentation"
+
+.SH NAME
+ddbugtopbm - convert Diddle or DiddleBug sketches to PBM files
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBddbugtopbm\fP
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+\fBddbugtopbm </path/to/palm/backup/dir/DiddleBugDB.pdb\fP
+
+\fBddbugtopbm </path/to/palm/backup/dir/DiddleDB.pdb\fP
+
+\fBddbugtopbm </path/to/palm/backup/dir/DiddleIDB.pdb\fP
+
+.fi
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBddbugtopbm\fP converts all sketches present in a database used
+by the PalmOS programs \fBDiddle\fP or \fBDiddleBug\fP into
+appropriately-named PBM files.  The backup copy of DiddleBug's
+database you should use as this program's input is usually called
+\fBDiddleBugDB.pdb\fP.  Or if you use the original Diddle, it has two
+separate DBs - \fBDiddleDB.pdb\fP, containing unnamed `scratch'
+sketches, and \fBDiddleIDB.pdb\fP, containing the saved (and named)
+sketches which are listed by its `index' option.  You can feed this
+program any of these three on standard input.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBddbugtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN using
+.SH USING THE PROGRAM
+.PP
+I recommend you \fInot\fP run \fBddbugtopbm\fP from your Palm
+backup directory, i.e. don't run it from the directory the DB will
+normally be in.  Instead, run it from some other directory (perhaps you
+could make a directory purely to hold the PBM files, just to keep
+things simple) and use an absolute or relative path to the DB.
+.PP
+The filenames used for the output PBMs are based on the names given
+to each sketch; if you have an unnamed sketch, it's given a name along
+the lines of \fBsketch-0123.pbm\fP.
+.PP
+While the named sketches will overwrite any existing PBM file with
+the same name, the unnamed ones won't - they'll just try using another
+filename.  (I think this is probably the right approach, as you can't
+really tell the unnamed sketches apart.)
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The DiddleBug DB reader is only known to work with DBs from
+DiddleBug version 2.50. But it should probably work on later versions,
+and I think it'll work on DBs from version 2.15 as well.
+.PP
+It might fall over if fed an empty database, and doesn't do much
+(if any) checking of the input.
+
+
+.UN author
+.SH AUTHOR
+
+Russell Marks (\fIrus@svgalib.org\fP).
+.PP
+Mitch Blevins's decompression code is directly from DiddleBug
+itself, which like ddbugtopbm is distributed under the terms of the
+GNU GPL.
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "palmtopnm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.PP
+Jens-Chr. Heyer's `didcon' script does something similar.
+
+.UN history
+.SH HISTORY
+.PP
+\fBddbugtopbm\fP was new in Netpbm 10.18 (August 2003).  It was written
+and independently distributed in August 2002.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ddbugtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/deallocvt.1 b/upstream/mageia-cauldron/man1/deallocvt.1
new file mode 100644
index 00000000..00135d99
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/deallocvt.1
@@ -0,0 +1,35 @@
+.\" @(#)deallocvt.1 1.0 970317 aeb
+.TH DEALLOCVT 1 "17 Mar 1997" "kbd"
+.SH NAME
+deallocvt \- deallocate unused virtual consoles
+.SH SYNOPSIS
+.B deallocvt
+[\fI\,option\/\fR...]
+.RI [ N " ...]"
+.SH DESCRIPTION
+.LP
+The command
+.B deallocvt
+deallocates kernel memory and data structures
+for all unused virtual consoles.
+If one or more arguments
+.IR N " ..."
+are given, only the corresponding consoles
+.I /dev/ttyN
+are deallocated.
+
+A virtual console is unused if it is not the foreground console,
+and no process has it open for reading or writing, and no text
+has been selected on its screen.
+.SH OPTIONS
+.TP
+.I "\-V, \-\-version"
+print program version and exit.
+.TP
+.I "\-h, \-\-help"
+show this text and exit.
+.SH "SEE ALSO"
+.BR chvt (1),
+.BR openvt (1)
+
+
diff --git a/upstream/mageia-cauldron/man1/df.1 b/upstream/mageia-cauldron/man1/df.1
new file mode 100644
index 00000000..c0c73363
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/df.1
@@ -0,0 +1,120 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DF "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+df \- report file system space usage
+.SH SYNOPSIS
+.B df
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR df .
+.B df
+displays the amount of space available on the file system
+containing each file name argument.  If no file name is given, the
+space available on all currently mounted file systems is shown.
+Space is shown in 1K blocks by default, unless the environment
+variable POSIXLY_CORRECT is set, in which case 512-byte blocks are
+used.
+.PP
+If an argument is the absolute file name of a device node containing a
+mounted file system,
+.B df
+shows the space available on that file system rather than on the
+file system containing the device node.  This version of
+.B df
+cannot show the space available on unmounted file systems, because on
+most kinds of systems doing so requires very nonportable intimate
+knowledge of file system structures.
+.SH OPTIONS
+.PP
+Show information about the file system on which each FILE resides,
+or all file systems by default.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+include pseudo, duplicate, inaccessible file systems
+.TP
+\fB\-B\fR, \fB\-\-block\-size\fR=\fI\,SIZE\/\fR
+scale sizes by SIZE before printing them; e.g.,
+\&'\-BM' prints sizes in units of 1,048,576 bytes;
+see SIZE format below
+.TP
+\fB\-h\fR, \fB\-\-human\-readable\fR
+print sizes in powers of 1024 (e.g., 1023M)
+.TP
+\fB\-H\fR, \fB\-\-si\fR
+print sizes in powers of 1000 (e.g., 1.1G)
+.TP
+\fB\-i\fR, \fB\-\-inodes\fR
+list inode information instead of block usage
+.TP
+\fB\-k\fR
+like \fB\-\-block\-size\fR=\fI\,1K\/\fR
+.TP
+\fB\-l\fR, \fB\-\-local\fR
+limit listing to local file systems
+.TP
+\fB\-\-no\-sync\fR
+do not invoke sync before getting usage info (default)
+.TP
+\fB\-\-output\fR[=\fI\,FIELD_LIST\/\fR]
+use the output format defined by FIELD_LIST,
+or print all fields if FIELD_LIST is omitted.
+.TP
+\fB\-P\fR, \fB\-\-portability\fR
+use the POSIX output format
+.TP
+\fB\-\-sync\fR
+invoke sync before getting usage info
+.TP
+\fB\-\-total\fR
+elide all entries insignificant to available space,
+and produce a grand total
+.TP
+\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR
+limit listing to file systems of type TYPE
+.TP
+\fB\-T\fR, \fB\-\-print\-type\fR
+print file system type
+.TP
+\fB\-x\fR, \fB\-\-exclude\-type\fR=\fI\,TYPE\/\fR
+limit listing to file systems not of type TYPE
+.TP
+\fB\-v\fR
+(ignored)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Display values are in units of the first available SIZE from \fB\-\-block\-size\fR,
+and the DF_BLOCK_SIZE, BLOCK_SIZE and BLOCKSIZE environment variables.
+Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set).
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+FIELD_LIST is a comma\-separated list of columns to be included.  Valid
+field names are: 'source', 'fstype', 'itotal', 'iused', 'iavail', 'ipcent',
+\&'size', 'used', 'avail', 'pcent', 'file' and 'target' (see info page).
+.SH AUTHOR
+Written by Torbjorn Granlund, David MacKenzie, and Paul Eggert.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/df>
+.br
+or available locally via: info \(aq(coreutils) df invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/diff.1 b/upstream/mageia-cauldron/man1/diff.1
new file mode 100644
index 00000000..c32cbd86
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/diff.1
@@ -0,0 +1,270 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.4.
+.TH DIFF "1" "May 2023" "diffutils 3.10" "User Commands"
+.SH NAME
+diff \- compare files line by line
+.SH SYNOPSIS
+.B diff
+[\fIOPTION\fR]... \fIFILES\fR
+.SH DESCRIPTION
+Compare FILES line by line.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-normal\fR
+output a normal diff (the default)
+.TP
+\fB\-q\fR, \fB\-\-brief\fR
+report only when files differ
+.TP
+\fB\-s\fR, \fB\-\-report\-identical\-files\fR
+report when two files are the same
+.TP
+\fB\-c\fR, \fB\-C\fR NUM, \fB\-\-context\fR[=\fINUM\fR]
+output NUM (default 3) lines of copied context
+.TP
+\fB\-u\fR, \fB\-U\fR NUM, \fB\-\-unified\fR[=\fINUM\fR]
+output NUM (default 3) lines of unified context
+.TP
+\fB\-e\fR, \fB\-\-ed\fR
+output an ed script
+.TP
+\fB\-n\fR, \fB\-\-rcs\fR
+output an RCS format diff
+.TP
+\fB\-y\fR, \fB\-\-side\-by\-side\fR
+output in two columns
+.TP
+\fB\-W\fR, \fB\-\-width\fR=\fINUM\fR
+output at most NUM (default 130) print columns
+.TP
+\fB\-\-left\-column\fR
+output only the left column of common lines
+.TP
+\fB\-\-suppress\-common\-lines\fR
+do not output common lines
+.TP
+\fB\-p\fR, \fB\-\-show\-c\-function\fR
+show which C function each change is in
+.TP
+\fB\-F\fR, \fB\-\-show\-function\-line\fR=\fIRE\fR
+show the most recent line matching RE
+.TP
+\fB\-\-label\fR LABEL
+use LABEL instead of file name and timestamp
+(can be repeated)
+.TP
+\fB\-t\fR, \fB\-\-expand\-tabs\fR
+expand tabs to spaces in output
+.TP
+\fB\-T\fR, \fB\-\-initial\-tab\fR
+make tabs line up by prepending a tab
+.TP
+\fB\-\-tabsize\fR=\fINUM\fR
+tab stops every NUM (default 8) print columns
+.TP
+\fB\-\-suppress\-blank\-empty\fR
+suppress space or tab before empty output lines
+.TP
+\fB\-l\fR, \fB\-\-paginate\fR
+pass output through 'pr' to paginate it
+.TP
+\fB\-r\fR, \fB\-\-recursive\fR
+recursively compare any subdirectories found
+.TP
+\fB\-\-no\-dereference\fR
+don't follow symbolic links
+.TP
+\fB\-N\fR, \fB\-\-new\-file\fR
+treat absent files as empty
+.TP
+\fB\-\-unidirectional\-new\-file\fR
+treat absent first files as empty
+.TP
+\fB\-\-ignore\-file\-name\-case\fR
+ignore case when comparing file names
+.TP
+\fB\-\-no\-ignore\-file\-name\-case\fR
+consider case when comparing file names
+.TP
+\fB\-x\fR, \fB\-\-exclude\fR=\fIPAT\fR
+exclude files that match PAT
+.TP
+\fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
+exclude files that match any pattern in FILE
+.TP
+\fB\-S\fR, \fB\-\-starting\-file\fR=\fIFILE\fR
+start with FILE when comparing directories
+.TP
+\fB\-\-from\-file\fR=\fIFILE1\fR
+compare FILE1 to all operands;
+FILE1 can be a directory
+.TP
+\fB\-\-to\-file\fR=\fIFILE2\fR
+compare all operands to FILE2;
+FILE2 can be a directory
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+ignore case differences in file contents
+.TP
+\fB\-E\fR, \fB\-\-ignore\-tab\-expansion\fR
+ignore changes due to tab expansion
+.TP
+\fB\-Z\fR, \fB\-\-ignore\-trailing\-space\fR
+ignore white space at line end
+.TP
+\fB\-b\fR, \fB\-\-ignore\-space\-change\fR
+ignore changes in the amount of white space
+.TP
+\fB\-w\fR, \fB\-\-ignore\-all\-space\fR
+ignore all white space
+.TP
+\fB\-B\fR, \fB\-\-ignore\-blank\-lines\fR
+ignore changes where lines are all blank
+.TP
+\fB\-I\fR, \fB\-\-ignore\-matching\-lines\fR=\fIRE\fR
+ignore changes where all lines match RE
+.TP
+\fB\-a\fR, \fB\-\-text\fR
+treat all files as text
+.TP
+\fB\-\-strip\-trailing\-cr\fR
+strip trailing carriage return on input
+.TP
+\fB\-D\fR, \fB\-\-ifdef\fR=\fINAME\fR
+output merged file with '#ifdef NAME' diffs
+.TP
+\fB\-\-GTYPE\-group\-format\fR=\fIGFMT\fR
+format GTYPE input groups with GFMT
+.TP
+\fB\-\-line\-format\fR=\fILFMT\fR
+format all input lines with LFMT
+.TP
+\fB\-\-LTYPE\-line\-format\fR=\fILFMT\fR
+format LTYPE input lines with LFMT
+.IP
+These format options provide fine\-grained control over the output
+.IP
+of diff, generalizing \fB\-D\fR/\-\-ifdef.
+.TP
+LTYPE is 'old', 'new', or 'unchanged'.
+GTYPE is LTYPE or 'changed'.
+.IP
+GFMT (only) may contain:
+.TP
+%<
+lines from FILE1
+.TP
+%>
+lines from FILE2
+.TP
+%=
+lines common to FILE1 and FILE2
+.TP
+%[\-][WIDTH][.[PREC]]{doxX}LETTER
+printf\-style spec for LETTER
+.IP
+LETTERs are as follows for new group, lower case for old group:
+.TP
+F
+first line number
+.TP
+L
+last line number
+.TP
+N
+number of lines = L\-F+1
+.TP
+E
+F\-1
+.TP
+M
+L+1
+.TP
+%(A=B?T:E)
+if A equals B then T else E
+.IP
+LFMT (only) may contain:
+.TP
+%L
+contents of line
+.TP
+%l
+contents of line, excluding any trailing newline
+.TP
+%[\-][WIDTH][.[PREC]]{doxX}n
+printf\-style spec for input line number
+.IP
+Both GFMT and LFMT may contain:
+.TP
+%%
+%
+.TP
+%c'C'
+the single character C
+.TP
+%c'\eOOO'
+the character with octal code OOO
+.TP
+C
+the character C (other characters represent themselves)
+.TP
+\fB\-d\fR, \fB\-\-minimal\fR
+try hard to find a smaller set of changes
+.TP
+\fB\-\-horizon\-lines\fR=\fINUM\fR
+keep NUM lines of the common prefix and suffix
+.TP
+\fB\-\-speed\-large\-files\fR
+assume large files and many scattered small changes
+.TP
+\fB\-\-color\fR[=\fIWHEN\fR]
+color output; WHEN is 'never', 'always', or 'auto';
+plain \fB\-\-color\fR means \fB\-\-color=\fR'auto'
+.TP
+\fB\-\-palette\fR=\fIPALETTE\fR
+the colors to use when \fB\-\-color\fR is active; PALETTE is
+a colon\-separated list of terminfo capabilities
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+output version information and exit
+.PP
+FILES are 'FILE1 FILE2' or 'DIR1 DIR2' or 'DIR FILE' or 'FILE DIR'.
+If \fB\-\-from\-file\fR or \fB\-\-to\-file\fR is given, there are no restrictions on FILE(s).
+If a FILE is '\-', read standard input.
+Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
+.SH AUTHOR
+Written by Paul Eggert, Mike Haertel, David Hayes,
+Richard Stallman, and Len Tower.
+.SH "REPORTING BUGS"
+Report bugs to: bug\-diffutils@gnu.org
+.br
+GNU diffutils home page: <https://www.gnu.org/software/diffutils/>
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR wdiff (1),
+.BR cmp (1),
+.BR diff3 (1),
+.BR sdiff (1),
+.BR patch (1)
+.PP
+The full documentation for
+.B diff
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B diff
+programs are properly installed at your site, the command
+.IP
+.B info diff
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/diff3.1 b/upstream/mageia-cauldron/man1/diff3.1
new file mode 100644
index 00000000..9bd8342a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/diff3.1
@@ -0,0 +1,102 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.4.
+.TH DIFF3 "1" "May 2023" "diffutils 3.10" "User Commands"
+.SH NAME
+diff3 \- compare three files line by line
+.SH SYNOPSIS
+.B diff3
+[\fIOPTION\fR]... \fIMYFILE OLDFILE YOURFILE\fR
+.SH DESCRIPTION
+Compare three files line by line.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-A\fR, \fB\-\-show\-all\fR
+output all changes, bracketing conflicts
+.TP
+\fB\-e\fR, \fB\-\-ed\fR
+output ed script incorporating changes
+from OLDFILE to YOURFILE into MYFILE
+.TP
+\fB\-E\fR, \fB\-\-show\-overlap\fR
+like \fB\-e\fR, but bracket conflicts
+.TP
+\fB\-3\fR, \fB\-\-easy\-only\fR
+like \fB\-e\fR, but incorporate only nonoverlapping changes
+.TP
+\fB\-x\fR, \fB\-\-overlap\-only\fR
+like \fB\-e\fR, but incorporate only overlapping changes
+.TP
+\fB\-X\fR
+like \fB\-x\fR, but bracket conflicts
+.TP
+\fB\-i\fR
+append 'w' and 'q' commands to ed scripts
+.TP
+\fB\-m\fR, \fB\-\-merge\fR
+output actual merged file, according to
+\fB\-A\fR if no other options are given
+.TP
+\fB\-a\fR, \fB\-\-text\fR
+treat all files as text
+.TP
+\fB\-\-strip\-trailing\-cr\fR
+strip trailing carriage return on input
+.TP
+\fB\-T\fR, \fB\-\-initial\-tab\fR
+make tabs line up by prepending a tab
+.TP
+\fB\-\-diff\-program\fR=\fIPROGRAM\fR
+use PROGRAM to compare files
+.TP
+\fB\-L\fR, \fB\-\-label\fR=\fILABEL\fR
+use LABEL instead of file name
+(can be repeated up to three times)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+output version information and exit
+.PP
+The default output format is a somewhat human\-readable representation of
+the changes.
+.PP
+The \fB\-e\fR, \fB\-E\fR, \fB\-x\fR, \fB\-X\fR (and corresponding long) options cause an ed script
+to be output instead of the default.
+.PP
+Finally, the \fB\-m\fR (\fB\-\-merge\fR) option causes diff3 to do the merge internally
+and output the actual merged file.  For unusual input, this is more
+robust than using ed.
+.PP
+If a FILE is '\-', read standard input.
+Exit status is 0 if successful, 1 if conflicts, 2 if trouble.
+.SH AUTHOR
+Written by Randy Smith.
+.SH "REPORTING BUGS"
+Report bugs to: bug\-diffutils@gnu.org
+.br
+GNU diffutils home page: <https://www.gnu.org/software/diffutils/>
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR cmp (1),
+.BR diff (1),
+.BR sdiff (1)
+.PP
+The full documentation for
+.B diff3
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B diff3
+programs are properly installed at your site, the command
+.IP
+.B info diff3
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/dir.1 b/upstream/mageia-cauldron/man1/dir.1
new file mode 100644
index 00000000..808e072f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dir.1
@@ -0,0 +1,264 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DIR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+dir \- list directory contents
+.SH SYNOPSIS
+.B dir
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+List information about the FILEs (the current directory by default).
+Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with .
+.TP
+\fB\-A\fR, \fB\-\-almost\-all\fR
+do not list implied . and ..
+.TP
+\fB\-\-author\fR
+with \fB\-l\fR, print the author of each file
+.TP
+\fB\-b\fR, \fB\-\-escape\fR
+print C\-style escapes for nongraphic characters
+.TP
+\fB\-\-block\-size\fR=\fI\,SIZE\/\fR
+with \fB\-l\fR, scale sizes by SIZE when printing them;
+e.g., '\-\-block\-size=M'; see SIZE format below
+.TP
+\fB\-B\fR, \fB\-\-ignore\-backups\fR
+do not list implied entries ending with ~
+.TP
+\fB\-c\fR
+with \fB\-lt\fR: sort by, and show, ctime (time of last
+modification of file status information);
+with \fB\-l\fR: show ctime and sort by name;
+otherwise: sort by ctime, newest first
+.TP
+\fB\-C\fR
+list entries by columns
+.TP
+\fB\-\-color\fR[=\fI\,WHEN\/\fR]
+color the output WHEN; more info below
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+list directories themselves, not their contents
+.TP
+\fB\-D\fR, \fB\-\-dired\fR
+generate output designed for Emacs' dired mode
+.TP
+\fB\-f\fR
+list all entries in directory order
+.TP
+\fB\-F\fR, \fB\-\-classify\fR[=\fI\,WHEN\/\fR]
+append indicator (one of */=>@|) to entries WHEN
+.TP
+\fB\-\-file\-type\fR
+likewise, except do not append '*'
+.TP
+\fB\-\-format\fR=\fI\,WORD\/\fR
+across \fB\-x\fR, commas \fB\-m\fR, horizontal \fB\-x\fR, long \fB\-l\fR,
+single\-column \fB\-1\fR, verbose \fB\-l\fR, vertical \fB\-C\fR
+.TP
+\fB\-\-full\-time\fR
+like \fB\-l\fR \fB\-\-time\-style\fR=\fI\,full\-iso\/\fR
+.TP
+\fB\-g\fR
+like \fB\-l\fR, but do not list owner
+.TP
+\fB\-\-group\-directories\-first\fR
+group directories before files;
+can be augmented with a \fB\-\-sort\fR option, but any
+use of \fB\-\-sort\fR=\fI\,none\/\fR (\fB\-U\fR) disables grouping
+.TP
+\fB\-G\fR, \fB\-\-no\-group\fR
+in a long listing, don't print group names
+.TP
+\fB\-h\fR, \fB\-\-human\-readable\fR
+with \fB\-l\fR and \fB\-s\fR, print sizes like 1K 234M 2G etc.
+.TP
+\fB\-\-si\fR
+likewise, but use powers of 1000 not 1024
+.TP
+\fB\-H\fR, \fB\-\-dereference\-command\-line\fR
+follow symbolic links listed on the command line
+.TP
+\fB\-\-dereference\-command\-line\-symlink\-to\-dir\fR
+follow each command line symbolic link
+that points to a directory
+.TP
+\fB\-\-hide\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+(overridden by \fB\-a\fR or \fB\-A\fR)
+.TP
+\fB\-\-hyperlink\fR[=\fI\,WHEN\/\fR]
+hyperlink file names WHEN
+.TP
+\fB\-\-indicator\-style\fR=\fI\,WORD\/\fR
+append indicator with style WORD to entry names:
+none (default), slash (\fB\-p\fR),
+file\-type (\fB\-\-file\-type\fR), classify (\fB\-F\fR)
+.TP
+\fB\-i\fR, \fB\-\-inode\fR
+print the index number of each file
+.TP
+\fB\-I\fR, \fB\-\-ignore\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+.TP
+\fB\-k\fR, \fB\-\-kibibytes\fR
+default to 1024\-byte blocks for file system usage;
+used only with \fB\-s\fR and per directory totals
+.TP
+\fB\-l\fR
+use a long listing format
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+when showing file information for a symbolic
+link, show information for the file the link
+references rather than for the link itself
+.TP
+\fB\-m\fR
+fill width with a comma separated list of entries
+.TP
+\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR
+like \fB\-l\fR, but list numeric user and group IDs
+.TP
+\fB\-N\fR, \fB\-\-literal\fR
+print entry names without quoting
+.TP
+\fB\-o\fR
+like \fB\-l\fR, but do not list group information
+.TP
+\fB\-p\fR, \fB\-\-indicator\-style\fR=\fI\,slash\/\fR
+append / indicator to directories
+.TP
+\fB\-q\fR, \fB\-\-hide\-control\-chars\fR
+print ? instead of nongraphic characters
+.TP
+\fB\-\-show\-control\-chars\fR
+show nongraphic characters as\-is (the default,
+unless program is 'ls' and output is a terminal)
+.TP
+\fB\-Q\fR, \fB\-\-quote\-name\fR
+enclose entry names in double quotes
+.TP
+\fB\-\-quoting\-style\fR=\fI\,WORD\/\fR
+use quoting style WORD for entry names:
+literal, locale, shell, shell\-always,
+shell\-escape, shell\-escape\-always, c, escape
+(overrides QUOTING_STYLE environment variable)
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse order while sorting
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+list subdirectories recursively
+.TP
+\fB\-s\fR, \fB\-\-size\fR
+print the allocated size of each file, in blocks
+.TP
+\fB\-S\fR
+sort by file size, largest first
+.TP
+\fB\-\-sort\fR=\fI\,WORD\/\fR
+sort by WORD instead of name: none (\fB\-U\fR), size (\fB\-S\fR),
+time (\fB\-t\fR), version (\fB\-v\fR), extension (\fB\-X\fR), width
+.TP
+\fB\-\-time\fR=\fI\,WORD\/\fR
+change the default of using modification times;
+access time (\fB\-u\fR): atime, access, use;
+change time (\fB\-c\fR): ctime, status;
+birth time: birth, creation;
+.IP
+with \fB\-l\fR, WORD determines which time to show;
+with \fB\-\-sort\fR=\fI\,time\/\fR, sort by WORD (newest first)
+.TP
+\fB\-\-time\-style\fR=\fI\,TIME_STYLE\/\fR
+time/date format with \fB\-l\fR; see TIME_STYLE below
+.TP
+\fB\-t\fR
+sort by time, newest first; see \fB\-\-time\fR
+.TP
+\fB\-T\fR, \fB\-\-tabsize\fR=\fI\,COLS\/\fR
+assume tab stops at each COLS instead of 8
+.TP
+\fB\-u\fR
+with \fB\-lt\fR: sort by, and show, access time;
+with \fB\-l\fR: show access time and sort by name;
+otherwise: sort by access time, newest first
+.TP
+\fB\-U\fR
+do not sort; list entries in directory order
+.TP
+\fB\-v\fR
+natural sort of (version) numbers within text
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,COLS\/\fR
+set output width to COLS.  0 means no limit
+.TP
+\fB\-x\fR
+list entries by lines instead of by columns
+.TP
+\fB\-X\fR
+sort alphabetically by entry extension
+.TP
+\fB\-Z\fR, \fB\-\-context\fR
+print any security context of each file
+.TP
+\fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-1\fR
+list one file per line
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+The TIME_STYLE argument can be full\-iso, long\-iso, iso, locale, or +FORMAT.
+FORMAT is interpreted like in \fBdate\fP(1).  If FORMAT is FORMAT1<newline>FORMAT2,
+then FORMAT1 applies to non\-recent files and FORMAT2 to recent files.
+TIME_STYLE prefixed with 'posix\-' takes effect only outside the POSIX locale.
+Also the TIME_STYLE environment variable sets the default style to use.
+.PP
+The WHEN argument defaults to 'always' and can also be 'auto' or 'never'.
+.PP
+Using color to distinguish file types is disabled both by default and
+with \fB\-\-color\fR=\fI\,never\/\fR.  With \fB\-\-color\fR=\fI\,auto\/\fR, ls emits color codes only when
+standard output is connected to a terminal.  The LS_COLORS environment
+variable can change the settings.  Use the \fBdircolors\fP(1) command to set it.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if minor problems (e.g., cannot access subdirectory),
+.TP
+2
+if serious trouble (e.g., cannot access command\-line argument).
+.SH AUTHOR
+Written by Richard M. Stallman and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/dir>
+.br
+or available locally via: info \(aq(coreutils) dir invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/dircolors.1 b/upstream/mageia-cauldron/man1/dircolors.1
new file mode 100644
index 00000000..24546e1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dircolors.1
@@ -0,0 +1,50 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DIRCOLORS "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+dircolors \- color setup for ls
+.SH SYNOPSIS
+.B dircolors
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output commands to set the LS_COLORS environment variable.
+.SS "Determine format of output:"
+.TP
+\fB\-b\fR, \fB\-\-sh\fR, \fB\-\-bourne\-shell\fR
+output Bourne shell code to set LS_COLORS
+.TP
+\fB\-c\fR, \fB\-\-csh\fR, \fB\-\-c\-shell\fR
+output C shell code to set LS_COLORS
+.TP
+\fB\-p\fR, \fB\-\-print\-database\fR
+output defaults
+.TP
+\fB\-\-print\-ls\-colors\fR
+output fully escaped colors for display
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If FILE is specified, read it to determine which colors to use for which
+file types and extensions.  Otherwise, a precompiled database is used.
+For details on the format of these files, run 'dircolors \fB\-\-print\-database\fR'.
+.SH AUTHOR
+Written by H. Peter Anvin.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/dircolors>
+.br
+or available locally via: info \(aq(coreutils) dircolors invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/dirname.1 b/upstream/mageia-cauldron/man1/dirname.1
new file mode 100644
index 00000000..8e1de98a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dirname.1
@@ -0,0 +1,50 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DIRNAME "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+dirname \- strip last component from file name
+.SH SYNOPSIS
+.B dirname
+[\fI\,OPTION\/\fR] \fI\,NAME\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output each NAME with its last non\-slash component and trailing slashes
+removed; if NAME contains no /'s, output '.' (meaning the current directory).
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH EXAMPLES
+.TP
+dirname /usr/bin/
+\-> "/usr"
+.TP
+dirname dir1/str dir2/str
+\-> "dir1" followed by "dir2"
+.TP
+dirname stdio.h
+\-> "."
+.SH AUTHOR
+Written by David MacKenzie and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBbasename\fP(1), \fBreadlink\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/dirname>
+.br
+or available locally via: info \(aq(coreutils) dirname invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/du.1 b/upstream/mageia-cauldron/man1/du.1
new file mode 100644
index 00000000..8c28ba26
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/du.1
@@ -0,0 +1,163 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH DU "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+du \- estimate file space usage
+.SH SYNOPSIS
+.B du
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.br
+.B du
+[\fI\,OPTION\/\fR]... \fI\,--files0-from=F\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Summarize device usage of the set of FILEs, recursively for directories.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-0\fR, \fB\-\-null\fR
+end each output line with NUL, not newline
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+write counts for all files, not just directories
+.TP
+\fB\-\-apparent\-size\fR
+print apparent sizes rather than device usage; although
+the apparent size is usually smaller, it may be
+larger due to holes in ('sparse') files, internal
+fragmentation, indirect blocks, and the like
+.TP
+\fB\-B\fR, \fB\-\-block\-size\fR=\fI\,SIZE\/\fR
+scale sizes by SIZE before printing them; e.g.,
+\&'\-BM' prints sizes in units of 1,048,576 bytes;
+see SIZE format below
+.TP
+\fB\-b\fR, \fB\-\-bytes\fR
+equivalent to '\-\-apparent\-size \fB\-\-block\-size\fR=\fI\,1\/\fR'
+.TP
+\fB\-c\fR, \fB\-\-total\fR
+produce a grand total
+.TP
+\fB\-D\fR, \fB\-\-dereference\-args\fR
+dereference only symlinks that are listed on the
+command line
+.TP
+\fB\-d\fR, \fB\-\-max\-depth\fR=\fI\,N\/\fR
+print the total for a directory (or file, with \fB\-\-all\fR)
+only if it is N or fewer levels below the command
+line argument;  \fB\-\-max\-depth\fR=\fI\,0\/\fR is the same as
+\fB\-\-summarize\fR
+.TP
+\fB\-\-files0\-from\fR=\fI\,F\/\fR
+summarize device usage of the
+NUL\-terminated file names specified in file F;
+if F is \-, then read names from standard input
+.TP
+\fB\-H\fR
+equivalent to \fB\-\-dereference\-args\fR (\fB\-D\fR)
+.TP
+\fB\-h\fR, \fB\-\-human\-readable\fR
+print sizes in human readable format (e.g., 1K 234M 2G)
+.TP
+\fB\-\-inodes\fR
+list inode usage information instead of block usage
+.TP
+\fB\-k\fR
+like \fB\-\-block\-size\fR=\fI\,1K\/\fR
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+dereference all symbolic links
+.TP
+\fB\-l\fR, \fB\-\-count\-links\fR
+count sizes many times if hard linked
+.TP
+\fB\-m\fR
+like \fB\-\-block\-size\fR=\fI\,1M\/\fR
+.TP
+\fB\-P\fR, \fB\-\-no\-dereference\fR
+don't follow any symbolic links (this is the default)
+.TP
+\fB\-S\fR, \fB\-\-separate\-dirs\fR
+for directories do not include size of subdirectories
+.TP
+\fB\-\-si\fR
+like \fB\-h\fR, but use powers of 1000 not 1024
+.TP
+\fB\-s\fR, \fB\-\-summarize\fR
+display only a total for each argument
+.TP
+\fB\-t\fR, \fB\-\-threshold\fR=\fI\,SIZE\/\fR
+exclude entries smaller than SIZE if positive,
+or entries greater than SIZE if negative
+.TP
+\fB\-\-time\fR
+show time of the last modification of any file in the
+directory, or any of its subdirectories
+.TP
+\fB\-\-time\fR=\fI\,WORD\/\fR
+show time as WORD instead of modification time:
+atime, access, use, ctime or status
+.TP
+\fB\-\-time\-style\fR=\fI\,STYLE\/\fR
+show times using STYLE, which can be:
+full\-iso, long\-iso, iso, or +FORMAT;
+FORMAT is interpreted like in 'date'
+.TP
+\fB\-X\fR, \fB\-\-exclude\-from\fR=\fI\,FILE\/\fR
+exclude files that match any pattern in FILE
+.TP
+\fB\-\-exclude\fR=\fI\,PATTERN\/\fR
+exclude files that match PATTERN
+.TP
+\fB\-x\fR, \fB\-\-one\-file\-system\fR
+skip directories on different file systems
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Display values are in units of the first available SIZE from \fB\-\-block\-size\fR,
+and the DU_BLOCK_SIZE, BLOCK_SIZE and BLOCKSIZE environment variables.
+Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set).
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.SH PATTERNS
+PATTERN is a shell pattern (not a regular expression).  The pattern
+.B ?\&
+matches any one character, whereas
+.B *
+matches any string (composed of zero, one or multiple characters).  For
+example,
+.B *.o
+will match any files whose names end in
+.BR .o .
+Therefore, the command
+.IP
+.B du \-\-exclude=\(aq*.o\(aq
+.PP
+will skip all files and subdirectories ending in
+.B .o
+(including the file
+.B .o
+itself).
+.SH AUTHOR
+Written by Torbjorn Granlund, David MacKenzie, Paul Eggert,
+and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/du>
+.br
+or available locally via: info \(aq(coreutils) du invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/dumpkeys.1 b/upstream/mageia-cauldron/man1/dumpkeys.1
new file mode 100644
index 00000000..8a8f77b8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dumpkeys.1
@@ -0,0 +1,251 @@
+.\" @(#)loadkeys.1 1.0 93/09/1 RK
+.TH DUMPKEYS 1 "1 Sep 1993" "kbd"
+.SH NAME
+dumpkeys \- dump keyboard translation tables
+.SH SYNOPSIS
+.B dumpkeys
+[OPTIONS]
+.SH DESCRIPTION
+.IX "dumpkeys command" "" "\fLdumpkeys\fR command"
+.LP
+.B dumpkeys
+writes, to the standard output, the current contents of the keyboard
+driver's translation tables, in the format specified by
+.BR keymaps (5).
+.LP
+Using the various options, the format of the output can be controlled
+and also other information from the kernel and the programs
+.BR dumpkeys (1)
+and
+.BR loadkeys (1)
+can be obtained.
+.SH OPTIONS
+.TP
+.B \-h \-\-help
+Prints the program's version number and a short usage message to the
+program's standard error output and exits.
+.TP
+.B \-i \-\-short-info
+Prints some characteristics of the kernel's keyboard driver. The items
+shown are:
+.LP
+.RS
+Keycode range supported by the kernel
+.LP
+.RS
+This tells what values can be used after the
+.B keycode
+keyword in keytable files. See
+.BR keymaps (5)
+for more information and the syntax of these files.
+.RE
+.LP
+Number of actions bindable to a key
+.LP
+.RS
+This tells how many different actions a single key can output using
+various modifier keys. If the value is 16 for example, you can define up
+to 16 different actions to a key combined with modifiers. When the value
+is 16, the kernel probably knows about four modifier keys, which you can
+press in different combinations with the key to access all the bound
+actions.
+.RE
+.LP
+Ranges of action codes supported by the kernel
+.LP
+.RS
+This item contains a list of action code ranges in hexadecimal notation.
+These are the values that can be used in the right hand side of a key
+definition, ie. the
+.IR vv 's
+in a line
+.LP
+.RS
+.B keycode
+.I xx
+=
+.I vv vv vv vv
+.RE
+.LP
+(see
+.BR keymaps (5)
+for more information about the format of key definition lines).
+.BR dumpkeys (1)
+and
+.BR loadkeys (1)
+support a symbolic notation, which is preferable to the numeric one, as
+the action codes may vary from kernel to kernel while the symbolic names
+usually remain the same. However, the list of action code ranges can be
+used to determine, if the kernel actually supports all the symbols
+.BR loadkeys (1)
+knows, or are there maybe some actions supported by the kernel that
+have no symbolic name in your
+.BR loadkeys (1)
+program. To see this, you compare the range list with the action symbol
+list, see option
+.B --long-info
+below.
+.RE
+.LP
+Number of function keys supported by kernel
+.LP
+.RS
+This tells the number of action codes that can be used to output
+strings of characters. These action codes are traditionally bound to
+the various function and editing keys of the keyboard and are defined
+to send standard escape sequences. However, you can redefine these to
+send common command lines, email addresses or whatever you like.
+Especially if the number of this item is greater than the number of
+function and editing keys in your keyboard, you may have some "spare"
+action codes that you can bind to AltGr-letter combinations, for example,
+to send some useful strings. See
+.BR loadkeys (1)
+for more details.
+.RE
+.LP
+Function strings
+.LP
+.RS
+You can see you current function key definitions with the command
+.LP
+.RS
+.B dumpkeys --funcs-only
+.RE
+.LP
+.RE
+.RE
+.LP
+.TP
+.B \-l \-s \-\-long-info
+This option instructs
+.B dumpkeys
+to print a long information listing. The output is the same as with the
+.B --short-info
+appended with the list of action symbols supported by
+.BR loadkeys (1)
+and
+.BR dumpkeys (1),
+along with the symbols' numeric values.
+.LP
+.TP
+.B \-n \-\-numeric
+This option causes
+.B dumpkeys
+to by-pass the conversion of action code values to symbolic notation and
+to print the in hexadecimal format instead.
+.LP
+.TP
+.B \-f \-\-full-table
+This makes
+.B dumpkeys
+skip all the short-hand heuristics (see
+.BR keymaps (5))
+and output the key bindings in the canonical form. First a keymaps
+line describing the currently defined modifier combinations
+is printed. Then for each key a row with a column for each
+modifier combination is printed. For
+example, if the current keymap in use uses seven modifiers,
+every row will have seven action code columns. This format
+can be useful for example to programs that post-process the
+output of
+.BR dumpkeys .
+.LP
+.TP
+.BI \-S shape " " " " \-\-shape= shape
+Available shapes:
+.LP
+.RS
+.B 2
+default output.
+.RE
+.LP
+.RS
+.B 4
+one line for each keycode.
+.RE
+.LP
+.RS
+.B 8
+one line for each (modifier,keycode) pair.
+.RE
+.LP
+.RS
+.B 16
+one line for each keycode until 1st hole.
+.RE
+.LP
+.TP
+.B \-1 \-\-separate-lines
+This forces
+.B dumpkeys
+to write one line per (modifier,keycode) pair. It prefixes the word
+.I plain
+for plain keycodes.
+.LP
+.TP
+.B \-t \-\-funcs-only
+When this option is given,
+.B dumpkeys
+prints only the function key string definitions. Normally
+.B dumpkeys
+prints both the key bindings and the string definitions.
+.LP
+.TP
+.B \-k \-\-keys-only
+When this option is given,
+.B dumpkeys
+prints only the key bindings. Normally
+.B dumpkeys
+prints both the key bindings and the string definitions.
+.LP
+.TP
+.B \-d \-\-compose-only
+When this option is given,
+.B dumpkeys
+prints only the compose key combinations.
+This option is available only if your kernel has compose key support.
+.LP
+.TP
+.BI \-c charset " " " " \-\-charset= charset
+This instructs
+.B dumpkeys
+to interpret character code values according to the specified character
+set. This affects only the translation of character code values to
+symbolic names. Valid values for
+.I charset
+currently are
+.BR iso-8859-X ,
+Where X is a digit in 1-9.  If no
+.I charset
+is specified,
+.B iso-8859-1
+is used as a default.
+This option produces an output line `charset "iso-8859-X"', telling
+loadkeys how to interpret the keymap. (For example, "division" is
+0xf7 in iso-8859-1 but 0xba in iso-8859-8.)
+.LP
+.TP
+.BI \-C dev " " " " \-\-console= dev
+The affected console device can be specified using the
+.I -C
+(or
+.I --console
+) option. This option supports exactly one device name.
+.LP
+.TP
+.B \-v \-\-verbose
+Turn on verbose output.
+.LP
+.TP
+.B \-V \-\-version
+Prints version number and exits.
+.LP
+.SH FILES
+.TP
+.I /usr/lib/kbd/keymaps
+The recommended directory for keytable files.
+.LP
+.SH "SEE ALSO"
+.BR loadkeys (1),
+.BR keymaps (5)
+
diff --git a/upstream/mageia-cauldron/man1/dvipdf.1 b/upstream/mageia-cauldron/man1/dvipdf.1
new file mode 100644
index 00000000..d915638d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/dvipdf.1
@@ -0,0 +1,28 @@
+.TH DVIPDF 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+dvipdf \- Convert TeX DVI file to PDF using ghostscript and dvips
+.SH SYNOPSIS
+\fBdvipdf\fR [ \fIoptions\fR ] \fIinput.dvi\fR [ \fIoutput.pdf\fR ] ...
+.SH DESCRIPTION
+This script invokes
+.BR dvips (1)
+with the
+.B -q
+option, and pipes its output into
+.BR gs (1)
+with the following options:
+
+.ce
+.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite
+
+as well as 
+.B -sOutputFile
+and any options from the command-line.
+.SH SEE ALSO
+gs(1), dvips(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/echo.1 b/upstream/mageia-cauldron/man1/echo.1
new file mode 100644
index 00000000..d7949d76
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/echo.1
@@ -0,0 +1,93 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH ECHO "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+echo \- display a line of text
+.SH SYNOPSIS
+.B echo
+[\fI\,SHORT-OPTION\/\fR]... [\fI\,STRING\/\fR]...
+.br
+.B echo
+\fI\,LONG-OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Echo the STRING(s) to standard output.
+.TP
+\fB\-n\fR
+do not output the trailing newline
+.TP
+\fB\-e\fR
+enable interpretation of backslash escapes
+.TP
+\fB\-E\fR
+disable interpretation of backslash escapes (default)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If \fB\-e\fR is in effect, the following sequences are recognized:
+.TP
+\e\e
+backslash
+.TP
+\ea
+alert (BEL)
+.TP
+\eb
+backspace
+.TP
+\ec
+produce no further output
+.TP
+\ee
+escape
+.TP
+\ef
+form feed
+.TP
+\en
+new line
+.TP
+\er
+carriage return
+.TP
+\et
+horizontal tab
+.TP
+\ev
+vertical tab
+.TP
+\e0NNN
+byte with octal value NNN (1 to 3 digits)
+.TP
+\exHH
+byte with hexadecimal value HH (1 to 2 digits)
+.PP
+NOTE: your shell may have its own version of echo, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.PP
+NOTE: \fBprintf\fP(1) is a preferred alternative,
+which does not have issues outputting option\-like strings.
+.SH AUTHOR
+Written by Brian Fox and Chet Ramey.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBprintf\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/echo>
+.br
+or available locally via: info \(aq(coreutils) echo invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/ed.1 b/upstream/mageia-cauldron/man1/ed.1
new file mode 100644
index 00000000..3a84bdfb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ed.1
@@ -0,0 +1,83 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.2.
+.TH ED "1" "January 2023" "GNU ed 1.19" "User Commands"
+.SH NAME
+ed \- line-oriented text editor
+.SH SYNOPSIS
+.B ed
+[\fI\,options\/\fR] [\fI\,file\/\fR]
+.SH DESCRIPTION
+GNU ed is a line\-oriented text editor. It is used to create, display,
+modify and otherwise manipulate text files, both interactively and via
+shell scripts. A restricted version of ed, red, can only edit files in
+the current directory and cannot execute shell commands. Ed is the
+\&'standard' text editor in the sense that it is the original editor for
+Unix, and thus widely available. For most purposes, however, it is
+superseded by full\-screen editors such as GNU Emacs or GNU Moe.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-E\fR, \fB\-\-extended\-regexp\fR
+use extended regular expressions
+.TP
+\fB\-G\fR, \fB\-\-traditional\fR
+run in compatibility mode
+.TP
+\fB\-l\fR, \fB\-\-loose\-exit\-status\fR
+exit with 0 status even if a command fails
+.TP
+\fB\-p\fR, \fB\-\-prompt\fR=\fI\,STRING\/\fR
+use STRING as an interactive prompt
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+suppress diagnostics written to stderr
+.TP
+\fB\-r\fR, \fB\-\-restricted\fR
+run in restricted mode
+.TP
+\fB\-s\fR, \fB\-\-script\fR
+suppress byte counts and '!' prompt
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+be verbose; equivalent to the 'H' command
+.TP
+\fB\-\-strip\-trailing\-cr\fR
+strip carriage returns at end of text lines
+.PP
+Start edit by reading in 'file' if given.
+If 'file' begins with a '!', read output of shell command.
+.PP
+Exit status: 0 for a normal exit, 1 for environmental problems
+(file not found, invalid command line options, I/O errors, etc), 2 to
+indicate a corrupt or invalid input file, 3 for an internal consistency
+error (e.g., bug) which caused ed to panic.
+.SH "REPORTING BUGS"
+Report bugs to bug\-ed@gnu.org
+.br
+Ed home page: http://www.gnu.org/software/ed/ed.html
+.br
+General help using GNU software: http://www.gnu.org/gethelp
+.SH COPYRIGHT
+Copyright \(co 1994 Andrew L. Moore.
+.br
+Copyright \(co 2023 Antonio Diaz Diaz.
+License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B ed
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B ed
+programs are properly installed at your site, the command
+.IP
+.B info ed
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/elfedit.1 b/upstream/mageia-cauldron/man1/elfedit.1
new file mode 100644
index 00000000..33e62e3e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/elfedit.1
@@ -0,0 +1,273 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "ELFEDIT 1"
+.TH ELFEDIT 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+elfedit \- update ELF header and program property of ELF files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+elfedit [\fB\-\-input\-mach=\fR\fImachine\fR]
+        [\fB\-\-input\-type=\fR\fItype\fR]
+        [\fB\-\-input\-osabi=\fR\fIosabi\fR]
+        [\fB\-\-input\-abiversion=\fR\fIversion\fR]
+        \fB\-\-output\-mach=\fR\fImachine\fR
+        \fB\-\-output\-type=\fR\fItype\fR
+        \fB\-\-output\-osabi=\fR\fIosabi\fR
+        \fB\-\-output\-abiversion=\fR\fIversion\fR
+        \fB\-\-enable\-x86\-feature=\fR\fIfeature\fR
+        \fB\-\-disable\-x86\-feature=\fR\fIfeature\fR
+        [\fB\-v\fR|\fB\-\-version\fR]
+        [\fB\-h\fR|\fB\-\-help\fR]
+        \fIelffile\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBelfedit\fR updates the \s-1ELF\s0 header and program property of \s-1ELF\s0
+files which have the matching \s-1ELF\s0 machine and file types.  The options
+control how and which fields in the \s-1ELF\s0 header and program property
+should be updated.
+.PP
+\&\fIelffile\fR... are the \s-1ELF\s0 files to be updated.  32\-bit and
+64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The long and short forms of options, shown here as alternatives, are
+equivalent. At least one of the \fB\-\-output\-mach\fR,
+\&\fB\-\-output\-type\fR, \fB\-\-output\-osabi\fR,
+\&\fB\-\-output\-abiversion\fR,
+\&\fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR
+options must be given.
+.IP "\fB\-\-input\-mach=\fR\fImachine\fR" 4
+.IX Item "--input-mach=machine"
+Set the matching input \s-1ELF\s0 machine type to \fImachine\fR.  If
+\&\fB\-\-input\-mach\fR isn't specified, it will match any \s-1ELF\s0
+machine types.
+.Sp
+The supported \s-1ELF\s0 machine types are, \fIi386\fR, \fI\s-1IAMCU\s0\fR, \fIL1OM\fR,
+\&\fIK1OM\fR and \fIx86\-64\fR.
+.IP "\fB\-\-output\-mach=\fR\fImachine\fR" 4
+.IX Item "--output-mach=machine"
+Change the \s-1ELF\s0 machine type in the \s-1ELF\s0 header to \fImachine\fR.  The
+supported \s-1ELF\s0 machine types are the same as \fB\-\-input\-mach\fR.
+.IP "\fB\-\-input\-type=\fR\fItype\fR" 4
+.IX Item "--input-type=type"
+Set the matching input \s-1ELF\s0 file type to \fItype\fR.  If
+\&\fB\-\-input\-type\fR isn't specified, it will match any \s-1ELF\s0 file types.
+.Sp
+The supported \s-1ELF\s0 file types are, \fIrel\fR, \fIexec\fR and \fIdyn\fR.
+.IP "\fB\-\-output\-type=\fR\fItype\fR" 4
+.IX Item "--output-type=type"
+Change the \s-1ELF\s0 file type in the \s-1ELF\s0 header to \fItype\fR.  The
+supported \s-1ELF\s0 types are the same as \fB\-\-input\-type\fR.
+.IP "\fB\-\-input\-osabi=\fR\fIosabi\fR" 4
+.IX Item "--input-osabi=osabi"
+Set the matching input \s-1ELF\s0 file \s-1OSABI\s0 to \fIosabi\fR.  If
+\&\fB\-\-input\-osabi\fR isn't specified, it will match any \s-1ELF\s0 OSABIs.
+.Sp
+The supported \s-1ELF\s0 OSABIs are, \fInone\fR, \fI\s-1HPUX\s0\fR, \fINetBSD\fR,
+\&\fI\s-1GNU\s0\fR, \fILinux\fR (alias for \fI\s-1GNU\s0\fR),
+\&\fISolaris\fR, \fI\s-1AIX\s0\fR, \fIIrix\fR,
+\&\fIFreeBSD\fR, \fI\s-1TRU64\s0\fR, \fIModesto\fR, \fIOpenBSD\fR, \fIOpenVMS\fR,
+\&\fI\s-1NSK\s0\fR, \fI\s-1AROS\s0\fR and \fIFenixOS\fR.
+.IP "\fB\-\-output\-osabi=\fR\fIosabi\fR" 4
+.IX Item "--output-osabi=osabi"
+Change the \s-1ELF OSABI\s0 in the \s-1ELF\s0 header to \fIosabi\fR.  The
+supported \s-1ELF OSABI\s0 are the same as \fB\-\-input\-osabi\fR.
+.IP "\fB\-\-input\-abiversion=\fR\fIversion\fR" 4
+.IX Item "--input-abiversion=version"
+Set the matching input \s-1ELF\s0 file \s-1ABIVERSION\s0 to \fIversion\fR.
+\&\fIversion\fR must be between 0 and 255.  If \fB\-\-input\-abiversion\fR
+isn't specified, it will match any \s-1ELF\s0 ABIVERSIONs.
+.IP "\fB\-\-output\-abiversion=\fR\fIversion\fR" 4
+.IX Item "--output-abiversion=version"
+Change the \s-1ELF ABIVERSION\s0 in the \s-1ELF\s0 header to \fIversion\fR.
+\&\fIversion\fR must be between 0 and 255.
+.IP "\fB\-\-enable\-x86\-feature=\fR\fIfeature\fR" 4
+.IX Item "--enable-x86-feature=feature"
+Set the \fIfeature\fR bit in program property in \fIexec\fR or \fIdyn\fR
+\&\s-1ELF\s0 files with machine types of \fIi386\fR or \fIx86\-64\fR.  The
+supported features are, \fIibt\fR, \fIshstk\fR, \fIlam_u48\fR and
+\&\fIlam_u57\fR.
+.IP "\fB\-\-disable\-x86\-feature=\fR\fIfeature\fR" 4
+.IX Item "--disable-x86-feature=feature"
+Clear the \fIfeature\fR bit in program property in \fIexec\fR or
+\&\fIdyn\fR \s-1ELF\s0 files with machine types of \fIi386\fR or \fIx86\-64\fR.
+The supported features are the same as \fB\-\-enable\-x86\-feature\fR.
+.Sp
+Note: \fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR
+are available only on hosts with \fBmmap\fR support.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Display the version number of \fBelfedit\fR.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Display the command-line options understood by \fBelfedit\fR.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/enc2xs.1 b/upstream/mageia-cauldron/man1/enc2xs.1
new file mode 100644
index 00000000..8bac403c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/enc2xs.1
@@ -0,0 +1,351 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ENC2XS 1"
+.TH ENC2XS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+enc2xs \-\- Perl Encode Module Generator
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\&  enc2xs \-[options]
+\&  enc2xs \-M ModName mapfiles...
+\&  enc2xs \-C
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fIenc2xs\fR builds a Perl extension for use by Encode from either
+Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
+Besides being used internally during the build process of the Encode
+module, you can use \fIenc2xs\fR to add your own encoding to perl.
+No knowledge of XS is necessary.
+.SH "Quick Guide"
+.IX Header "Quick Guide"
+If you want to know as little about Perl as possible but need to
+add a new encoding, just read this chapter and forget the rest.
+.IP 0. 4
+.IX Item "0."
+Have a .ucm file ready.  You can get it from somewhere or you can write
+your own from scratch or you can grab one from the Encode distribution
+and customize it.  For the UCM format, see the next Chapter.  In the
+example below, I'll call my theoretical encoding myascii, defined
+in \fImy.ucm\fR.  \f(CW\*(C`$\*(C'\fR is a shell prompt.
+.Sp
+.Vb 2
+\&  $ ls \-F
+\&  my.ucm
+.Ve
+.IP 1. 4
+.IX Item "1."
+Issue a command as follows;
+.Sp
+.Vb 5
+\&  $ enc2xs \-M My my.ucm
+\&  generating Makefile.PL
+\&  generating My.pm
+\&  generating README
+\&  generating Changes
+.Ve
+.Sp
+Now take a look at your current directory.  It should look like this.
+.Sp
+.Vb 2
+\&  $ ls \-F
+\&  Makefile.PL   My.pm         my.ucm        t/
+.Ve
+.Sp
+The following files were created.
+.Sp
+.Vb 3
+\&  Makefile.PL \- MakeMaker script
+\&  My.pm       \- Encode submodule
+\&  t/My.t      \- test file
+.Ve
+.RS 4
+.IP 1.1. 4
+.IX Item "1.1."
+If you want *.ucm installed together with the modules, do as follows;
+.Sp
+.Vb 3
+\&  $ mkdir Encode
+\&  $ mv *.ucm Encode
+\&  $ enc2xs \-M My Encode/*ucm
+.Ve
+.RE
+.RS 4
+.RE
+.IP 2. 4
+.IX Item "2."
+Edit the files generated.  You don't have to if you have no time AND no
+intention to give it to someone else.  But it is a good idea to edit
+the pod and to add more tests.
+.IP 3. 4
+.IX Item "3."
+Now issue a command all Perl Mongers love:
+.Sp
+.Vb 2
+\&  $ perl Makefile.PL
+\&  Writing Makefile for Encode::My
+.Ve
+.IP 4. 4
+.IX Item "4."
+Now all you have to do is make.
+.Sp
+.Vb 12
+\&  $ make
+\&  cp My.pm blib/lib/Encode/My.pm
+\&  /usr/local/bin/perl /usr/local/bin/enc2xs \-Q \-O \e
+\&    \-o encode_t.c \-f encode_t.fnm
+\&  Reading myascii (myascii)
+\&  Writing compiled form
+\&  128 bytes in string tables
+\&  384 bytes (75%) saved spotting duplicates
+\&  1 bytes (0.775%) saved using substrings
+\&  ....
+\&  chmod 644 blib/arch/auto/Encode/My/My.bs
+\&  $
+.Ve
+.Sp
+The time it takes varies depending on how fast your machine is and
+how large your encoding is.  Unless you are working on something big
+like euc-tw, it won't take too long.
+.IP 5. 4
+.IX Item "5."
+You can "make install" already but you should test first.
+.Sp
+.Vb 8
+\&  $ make test
+\&  PERL_DL_NONLAZY=1 /usr/local/bin/perl \-Iblib/arch \-Iblib/lib \e
+\&    \-e \*(Aquse Test::Harness  qw(&runtests $verbose); \e
+\&    $verbose=0; runtests @ARGV;\*(Aq t/*.t
+\&  t/My....ok
+\&  All tests successful.
+\&  Files=1, Tests=2,  0 wallclock secs
+\&   ( 0.09 cusr + 0.01 csys = 0.09 CPU)
+.Ve
+.IP 6. 4
+.IX Item "6."
+If you are content with the test result, just "make install"
+.IP 7. 4
+.IX Item "7."
+If you want to add your encoding to Encode's demand-loading list
+(so you don't have to "use Encode::YourEncoding"), run
+.Sp
+.Vb 1
+\&  enc2xs \-C
+.Ve
+.Sp
+to update Encode::ConfigLocal, a module that controls local settings.
+After that, "use Encode;" is enough to load your encodings on demand.
+.SH "The Unicode Character Map"
+.IX Header "The Unicode Character Map"
+Encode uses the Unicode Character Map (UCM) format for source character
+mappings.  This format is used by IBM's ICU package and was adopted
+by Nick Ing-Simmons for use with the Encode module.  Since UCM is
+more flexible than Tcl's Encoding Map and far more user-friendly,
+this is the recommended format for Encode now.
+.PP
+A UCM file looks like this.
+.PP
+.Vb 10
+\&  #
+\&  # Comments
+\&  #
+\&  <code_set_name> "US\-ascii" # Required
+\&  <code_set_alias> "ascii"   # Optional
+\&  <mb_cur_min> 1             # Required; usually 1
+\&  <mb_cur_max> 1             # Max. # of bytes/char
+\&  <subchar> \ex3F             # Substitution char
+\&  #
+\&  CHARMAP
+\&  <U0000> \ex00 |0 # <control>
+\&  <U0001> \ex01 |0 # <control>
+\&  <U0002> \ex02 |0 # <control>
+\&  ....
+\&  <U007C> \ex7C |0 # VERTICAL LINE
+\&  <U007D> \ex7D |0 # RIGHT CURLY BRACKET
+\&  <U007E> \ex7E |0 # TILDE
+\&  <U007F> \ex7F |0 # <control>
+\&  END CHARMAP
+.Ve
+.IP \(bu 4
+Anything that follows \f(CW\*(C`#\*(C'\fR is treated as a comment.
+.IP \(bu 4
+The header section continues until a line containing the word
+CHARMAP. This section has a form of \fI<keyword> value\fR, one
+pair per line.  Strings used as values must be quoted. Barewords are
+treated as numbers.  \fI\exXX\fR represents a byte.
+.Sp
+Most of the keywords are self-explanatory. \fIsubchar\fR means
+substitution character, not subcharacter.  When you decode a Unicode
+sequence to this encoding but no matching character is found, the byte
+sequence defined here will be used.  For most cases, the value here is
+\&\ex3F; in ASCII, this is a question mark.
+.IP \(bu 4
+CHARMAP starts the character map section.  Each line has a form as
+follows:
+.Sp
+.Vb 5
+\&  <UXXXX> \exXX.. |0 # comment
+\&    ^     ^      ^
+\&    |     |      +\- Fallback flag
+\&    |     +\-\-\-\-\-\-\-\- Encoded byte sequence
+\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\- Unicode Character ID in hex
+.Ve
+.Sp
+The format is roughly the same as a header section except for the
+fallback flag: | followed by 0..3.   The meaning of the possible
+values is as follows:
+.RS 4
+.IP |0 4
+.IX Item "|0"
+Round trip safe.  A character decoded to Unicode encodes back to the
+same byte sequence.  Most characters have this flag.
+.IP |1 4
+.IX Item "|1"
+Fallback for unicode \-> encoding.  When seen, enc2xs adds this
+character for the encode map only.
+.IP |2 4
+.IX Item "|2"
+Skip sub-char mapping should there be no code point.
+.IP |3 4
+.IX Item "|3"
+Fallback for encoding \-> unicode.  When seen, enc2xs adds this
+character for the decode map only.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+And finally, END OF CHARMAP ends the section.
+.PP
+When you are manually creating a UCM file, you should copy ascii.ucm
+or an existing encoding which is close to yours, rather than write
+your own from scratch.
+.PP
+When you do so, make sure you leave at least \fBU0000\fR to \fBU0020\fR as
+is, unless your environment is EBCDIC.
+.PP
+\&\fBCAVEAT\fR: not all features in UCM are implemented.  For example,
+icu:state is not used.  Because of that, you need to write a perl
+module if you want to support algorithmical encodings, notably
+the ISO\-2022 series.  Such modules include Encode::JP::2022_JP,
+Encode::KR::2022_KR, and Encode::TW::HZ.
+.SS "Coping with duplicate mappings"
+.IX Subsection "Coping with duplicate mappings"
+When you create a map, you SHOULD make your mappings round-trip safe.
+That is, \f(CWencode(\*(Aqyour\-encoding\*(Aq, decode(\*(Aqyour\-encoding\*(Aq, $data)) eq
+$data\fR stands for all characters that are marked as \f(CW\*(C`|0\*(C'\fR.  Here is
+how to make sure:
+.IP \(bu 4
+Sort your map in Unicode order.
+.IP \(bu 4
+When you have a duplicate entry, mark either one with '|1' or '|3'.
+.IP \(bu 4
+And make sure the '|1' or '|3' entry FOLLOWS the '|0' entry.
+.PP
+Here is an example from big5\-eten.
+.PP
+.Vb 2
+\&  <U2550> \exF9\exF9 |0
+\&  <U2550> \exA2\exA4 |3
+.Ve
+.PP
+Internally Encoding \-> Unicode and Unicode \-> Encoding Map looks like
+this;
+.PP
+.Vb 4
+\&  E to U               U to E
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  \exF9\exF9 => U2550    U2550 => \exF9\exF9
+\&  \exA2\exA4 => U2550
+.Ve
+.PP
+So it is round-trip safe for \exF9\exF9.  But if the line above is upside
+down, here is what happens.
+.PP
+.Vb 4
+\&  E to U               U to E
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  \exA2\exA4 => U2550    U2550 => \exF9\exF9
+\&  (\exF9\exF9 => U2550 is now overwritten!)
+.Ve
+.PP
+The Encode package comes with \fIucmlint\fR, a crude but sufficient
+utility to check the integrity of a UCM file.  Check under the
+Encode/bin directory for this.
+.PP
+When in doubt, you can use \fIucmsort\fR, yet another utility under
+Encode/bin directory.
+.SH Bookmarks
+.IX Header "Bookmarks"
+.IP \(bu 4
+ICU Home Page 
+<http://www.icu\-project.org/>
+.IP \(bu 4
+ICU Character Mapping Tables
+<http://site.icu\-project.org/charts/charset>
+.IP \(bu 4
+ICU:Conversion Data
+<http://www.icu\-project.org/userguide/conversion\-data.html>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode,
+perlmod,
+perlpod
diff --git a/upstream/mageia-cauldron/man1/encguess.1 b/upstream/mageia-cauldron/man1/encguess.1
new file mode 100644
index 00000000..81a14c5a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/encguess.1
@@ -0,0 +1,133 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ENCGUESS 1"
+.TH ENCGUESS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+encguess \- guess character encodings of files
+.SH VERSION
+.IX Header "VERSION"
+\&\f(CW$Id:\fR encguess,v 0.3 2020/12/02 01:28:17 dankogai Exp $
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  encguess [switches] filename...
+.Ve
+.SS SWITCHES
+.IX Subsection "SWITCHES"
+.IP \-h 2
+.IX Item "-h"
+show this message and exit.
+.IP \-s 2
+.IX Item "-s"
+specify a list of "suspect encoding types" to test, 
+separated by either \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`,\*(C'\fR
+.IP \-S 2
+.IX Item "-S"
+output a list of all acceptable encoding types that can be used with
+the \-s param
+.IP \-u 2
+.IX Item "-u"
+suppress display of unidentified types
+.SS EXAMPLES:
+.IX Subsection "EXAMPLES:"
+.IP \(bu 2
+Guess encoding of a file named \f(CW\*(C`test.txt\*(C'\fR, using only the default
+suspect types.
+.Sp
+.Vb 1
+\&   encguess test.txt
+.Ve
+.IP \(bu 2
+Guess the encoding type of a file named \f(CW\*(C`test.txt\*(C'\fR, using the suspect
+types \f(CW\*(C`euc\-jp,shiftjis,7bit\-jis\*(C'\fR.
+.Sp
+.Vb 2
+\&   encguess \-s euc\-jp,shiftjis,7bit\-jis test.txt
+\&   encguess \-s euc\-jp:shiftjis:7bit\-jis test.txt
+.Ve
+.IP \(bu 2
+Guess the encoding type of several files, do not display results for
+unidentified files.
+.Sp
+.Vb 1
+\&   encguess \-us euc\-jp,shiftjis,7bit\-jis test*.txt
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The encoding identification is done by checking one encoding type at a
+time until all but the right type are eliminated. The set of encoding
+types to try is defined by the \-s parameter and defaults to ascii,
+utf8 and UTF\-16/32 with BOM. This can be overridden by passing one or
+more encoding types via the \-s parameter. If you need to pass in
+multiple suspect encoding types, use a quoted string with the a space
+separating each value.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode::Guess, Encode::Detect
+.SH "LICENSE AND COPYRIGHT"
+.IX Header "LICENSE AND COPYRIGHT"
+Copyright 2015 Michael LaGrasta and Dan Kogai.
+.PP
+This program is free software; you can redistribute it and/or modify it
+under the terms of the the Artistic License (2.0). You may obtain a
+copy of the full license at:
+.PP
+<http://www.perlfoundation.org/artistic_license_2_0>
diff --git a/upstream/mageia-cauldron/man1/env.1 b/upstream/mageia-cauldron/man1/env.1
new file mode 100644
index 00000000..c0c0a6df
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/env.1
@@ -0,0 +1,129 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH ENV "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+env \- run a program in a modified environment
+.SH SYNOPSIS
+.B env
+[\fI\,OPTION\/\fR]... [\fI\,-\/\fR] [\fI\,NAME=VALUE\/\fR]... [\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Set each NAME to VALUE in the environment and run COMMAND.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-i\fR, \fB\-\-ignore\-environment\fR
+start with an empty environment
+.TP
+\fB\-0\fR, \fB\-\-null\fR
+end each output line with NUL, not newline
+.TP
+\fB\-u\fR, \fB\-\-unset\fR=\fI\,NAME\/\fR
+remove variable from the environment
+.TP
+\fB\-C\fR, \fB\-\-chdir\fR=\fI\,DIR\/\fR
+change working directory to DIR
+.TP
+\fB\-S\fR, \fB\-\-split\-string\fR=\fI\,S\/\fR
+process and split S into separate arguments;
+used to pass multiple arguments on shebang lines
+.TP
+\fB\-\-block\-signal\fR[=\fI\,SIG\/\fR]
+block delivery of SIG signal(s) to COMMAND
+.TP
+\fB\-\-default\-signal\fR[=\fI\,SIG\/\fR]
+reset handling of SIG signal(s) to the default
+.TP
+\fB\-\-ignore\-signal\fR[=\fI\,SIG\/\fR]
+set handling of SIG signal(s) to do nothing
+.TP
+\fB\-\-list\-signal\-handling\fR
+list non default signal handling to stderr
+.TP
+\fB\-v\fR, \fB\-\-debug\fR
+print verbose information for each processing step
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+A mere \- implies \fB\-i\fR.  If no COMMAND, print the resulting environment.
+.PP
+SIG may be a signal name like 'PIPE', or a signal number like '13'.
+Without SIG, all known signals are included.  Multiple signals can be
+comma\-separated.
+.SH OPTIONS
+.SS "\-S/\-\-split\-string usage in scripts"
+The
+.B \-S
+option allows specifying multiple parameters in a script.
+Running a script named
+.B 1.pl
+containing the following first line:
+.PP
+.RS
+.nf
+#!/usr/bin/env \-S perl \-w \-T
+\&...
+.fi
+.RE
+.PP
+Will execute
+.B "perl \-w \-T 1.pl".
+.PP
+Without the
+.B '\-S'
+parameter the script will likely fail with:
+.PP
+.RS
+.nf
+/usr/bin/env: 'perl \-w \-T': No such file or directory
+.fi
+.RE
+.PP
+See the full documentation for more details.
+.PP
+.SS "\-\-default-signal[=SIG]" usage
+This option allows setting a signal handler to its default
+action, which is not possible using the traditional shell
+trap command.  The following example ensures that seq
+will be terminated by SIGPIPE no matter how this signal
+is being handled in the process invoking the command.
+
+.PP
+.RS
+.nf
+sh \-c 'env \-\-default-signal=PIPE seq inf | head \-n1'
+.fi
+.RE
+.PP
+.SH NOTES
+POSIX's \fBexec\fP(3p) pages says:
+.RS
+"many existing applications wrongly assume that they start with certain
+signals set to the default action and/or unblocked.... Therefore, it is best
+not to block or ignore signals across execs without explicit reason to do so,
+and especially not to block signals across execs of arbitrary (not closely
+cooperating) programs."
+.RE
+.SH AUTHOR
+Written by Richard Mlynarik, David MacKenzie, and Assaf Gordon.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBsigaction\fP(2), \fBsigprocmask\fP(2), \fBsignal\fP(7)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/env>
+.br
+or available locally via: info \(aq(coreutils) env invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/envsubst.1 b/upstream/mageia-cauldron/man1/envsubst.1
new file mode 100644
index 00000000..0d5ae21b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/envsubst.1
@@ -0,0 +1,55 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH ENVSUBST "1" "October 2022" "GNU gettext-runtime 0.21.1" "User Commands"
+.SH NAME
+envsubst \- substitutes environment variables in shell format strings
+.SH SYNOPSIS
+.B envsubst
+[\fI\,OPTION\/\fR] [\fI\,SHELL-FORMAT\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Substitutes the values of environment variables.
+.SS "Operation mode:"
+.TP
+\fB\-v\fR, \fB\-\-variables\fR
+output the variables occurring in SHELL\-FORMAT
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.PP
+In normal operation mode, standard input is copied to standard output,
+with references to environment variables of the form $VARIABLE or ${VARIABLE}
+being replaced with the corresponding values.  If a SHELL\-FORMAT is given,
+only those environment variables that are referenced in SHELL\-FORMAT are
+substituted; otherwise all environment variables references occurring in
+standard input are substituted.
+.PP
+When \fB\-\-variables\fR is used, standard input is ignored, and the output consists
+of the environment variables that are referenced in SHELL\-FORMAT, one per line.
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2003\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B envsubst
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B envsubst
+programs are properly installed at your site, the command
+.IP
+.B info envsubst
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/epsffit.1 b/upstream/mageia-cauldron/man1/epsffit.1
new file mode 100644
index 00000000..685d8c20
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/epsffit.1
@@ -0,0 +1,63 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH EPSFFIT "1" "October 2021" "epsffit 2.07" "User Commands"
+.SH NAME
+epsffit - fit an Encapsulated PostScript file to a given bounding box
+.SH SYNOPSIS
+.B epsffit
+[\fI\,OPTION\/\fR...] \fI\,LLX LLY URX URY \/\fR[\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Fit an Encapsulated PostScript file to a given bounding box.
+.TP
+\fB\-c\fR, \fB\-\-center\fR
+center the image in the given bounding box
+.TP
+\fB\-r\fR, \fB\-\-rotate\fR
+rotate the image by 90 degrees counter\-clockwise
+.TP
+\fB\-a\fR, \fB\-\-aspect\fR
+adjust the aspect ratio to fit the bounding box
+.TP
+\fB\-m\fR, \fB\-\-maximize\fR
+rotate the image to fill more of the page if possible
+.TP
+\fB\-s\fR, \fB\-\-showpage\fR
+append a \fI\,/showpage\/\fP to the file to force printing
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+(LLX, LLY) are the coordinates of the lower left corner of the box, and
+(URX, URY) the upper right.
+.PP
+If OUTFILE is not specified, writes to standard output.
+If INFILE is not specified, reads from standard input.
+.PP
+See
+.BR psutils (1)
+for the available units.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2016.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/eqn.1 b/upstream/mageia-cauldron/man1/eqn.1
new file mode 100644
index 00000000..62cc6024
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/eqn.1
@@ -0,0 +1,1375 @@
+'\" t
+.TH EQN 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+eqn \- format equations for troff or MathML
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr eqn_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.ie \n(.V<\n(.v \
+.  ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el \
+.  ds tx TeX
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY eqn
+.OP \-rvCNR
+.OP \-d xy
+.OP \-T name
+.OP \-M dir
+.OP \-f F
+.OP \-s n
+.OP \-p n
+.OP \-m n
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This manual page describes the GNU version of
+.BR eqn ,
+which is part of the groff document formatting system.
+.
+.B eqn
+compiles descriptions of equations embedded within
+.B troff
+input files into commands that are understood by
+.BR troff .
+.
+Normally, it should be invoked using the
+.B \-e
+option of
+.BR groff .
+.
+The syntax is quite compatible with Unix eqn.
+.
+The output of GNU
+.B eqn
+cannot be processed with Unix troff;
+it must be processed with GNU troff.
+.
+If no files are given on the command line, the standard input is read.
+.
+A filename of
+.B \-
+causes the standard input to be read.
+.
+.
+.LP
+.B eqn
+searches for the file
+.I eqnrc
+in the directories given with the
+.B \-M
+option first, then in
+.IR /usr/\:lib64/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+and finally in the standard macro directory
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
+.
+If it exists,
+.B eqn
+processes it before the other input files.
+.
+The
+.B \-R
+option prevents this.
+.
+.
+.LP
+GNU
+.B eqn
+does not provide the functionality of neqn:
+it does not support low-resolution, typewriter-like devices
+(although it may work adequately for very simple input).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.BI \-d xy
+Specify delimiters
+.I x
+and\~\c
+.I y
+for the left and right end, respectively, of in-line equations.
+.
+Any
+.B delim
+statements in the source file overrides this.
+.
+.TP
+.B \-C
+Recognize
+.B .EQ
+and
+.B .EN
+even when followed by a character other than space or newline.
+.
+Also, the statement
+.RB \[oq] "delim on" \[cq]
+is not handled specially.
+.
+.TP
+.B \-N
+Don't allow newlines within delimiters.
+.
+This option allows
+.B eqn
+to recover better from missing closing delimiters.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.B \-r
+Only one size reduction.
+.
+.TP
+.BI \-m n
+The minimum point-size is\~\c
+.IR n .
+.
+.B eqn
+does not reduce the size of subscripts or superscripts to
+a smaller size than\~\c
+.IR n .
+.
+.TP
+.BI \-T name
+The output is for device
+.IR name .
+.
+Normally, the only effect of this is to define a macro
+.I name
+with a value of\~\c
+.BR 1 ;
+.I eqnrc
+uses this to provide definitions appropriate for the output device.
+.
+However, if the specified device is \[lq]MathML\[rq], the output is
+MathML markup rather than troff commands, and
+.I eqnrc
+is not loaded at all.
+.
+The default output device is
+.BR ps .
+.
+.TP
+.BI \-M dir
+Search
+.I dir
+for
+.I eqnrc
+before the default directories.
+.
+.TP
+.B \-R
+Don't load
+.IR eqnrc .
+.
+.TP
+.BI \-f F
+This is equivalent to a
+.BI gfont\  F
+command.
+.
+.TP
+.BI \-s n
+This is equivalent to a
+.BI gsize\  n
+command.
+.
+This option is deprecated.
+.B eqn
+normally sets equations at whatever the current point size
+is when the equation is encountered.
+.
+.TP
+.BI \-p n
+This says that subscripts and superscripts should be
+.IR n \~points
+smaller than the surrounding text.
+.
+This option is deprecated.
+.
+Normally
+.B eqn
+sets subscripts and superscripts at 70% of the size of the surrounding
+text.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+Only the differences between GNU
+.B eqn
+and Unix eqn are described here.
+.
+.
+.LP
+GNU
+.B eqn
+emits Presentation MathML output when invoked with the
+.B "-T\~MathML"
+option.
+.
+.
+.LP
+GNU eqn sets the input token
+.B \&"..."
+as three periods or low dots, rather than the three centered dots of
+classic eqn.  To get three centered dots, write
+.B "cdots"
+or
+.BR "cdot cdot cdot".
+.
+.
+.LP
+Most of the new features of the GNU
+.B eqn
+input language are based on \*(tx.
+.
+There are some references to the differences between \*(tx and GNU
+.B eqn
+below;
+these may safely be ignored if you do not know \*(tx.
+.
+.
+.\" ====================================================================
+.SS Controlling delimiters
+.\" ====================================================================
+.
+If not in compatibility mode,
+.B eqn
+recognizes
+.
+.RS
+.LP
+.B delim on
+.RE
+.
+.LP
+to restore the delimiters which have been previously disabled
+with a call to
+.RB \[oq] "delim off" \[cq].
+.
+If delimiters haven't been specified, the call has no effect.
+.
+.
+.\" ====================================================================
+.SS Automatic spacing
+.\" ====================================================================
+.
+.B eqn
+gives each component of an equation a type, and adjusts the spacing
+between components using that type.
+.
+Possible types are described in the table below.
+.
+.
+.TS
+lB l.
+ordinary	T{
+an ordinary character such as \[oq]1\[cq] or
+.RI \[oq] x \[cq]
+T}
+operator	T{
+a large operator such as
+.ds Su \[oq]\s+5\(*S\s0\[cq]
+.if \n(.g .if !c\(*S .ds Su the summation operator
+\*(Su
+T}
+binary	a binary operator such as \[oq]\[pl]\[cq]
+relation	a relation such as \[oq]=\[cq]
+opening	a opening bracket such as \[oq](\[cq]
+closing	a closing bracket such as \[oq])\[cq]
+punctuation	a punctuation character such as \[oq],\[cq]
+inner	a subformula contained within brackets
+suppress	a type that suppresses automatic spacing adjustment
+.TE
+.
+.
+.LP
+Components of an equation
+get a type in one of two ways.
+.
+.TP
+.BI type\  t\ e
+This yields an equation component that contains\~\c
+.I e
+but that has type\~\c
+.IR t ,
+where
+.I t
+is one of the types mentioned above.
+.
+For example,
+.B times
+is defined as
+.
+.RS
+.IP
+.B
+type "binary" \e(mu
+.RE
+.
+.IP
+The name of the type doesn't have to be quoted, but quoting protects
+from macro expansion.
+.
+.TP
+.BI chartype\  t\ text
+Unquoted groups of characters are split up into individual characters,
+and the type of each character is looked up;
+this changes the type that is stored for each character;
+it says that the characters in
+.I text
+from now on have type\~\c
+.IR t .
+For example,
+.
+.RS
+.IP
+.B
+chartype "punctuation" .,;:
+.RE
+.
+.IP
+would make the characters \[oq].,;:\[cq] have type punctuation
+whenever they subsequently appeared in an equation.
+.
+The type\~\c
+.I t
+can also be
+.B letter
+or
+.BR digit ;
+in these cases
+.B chartype
+changes the font type of the characters.
+.
+See subsection \[lq]Fonts\[rq] below.
+.
+.
+.\" ====================================================================
+.SS New primitives
+.\" ====================================================================
+.
+.TP
+.BI big\  e
+Enlarges the expression it modifies; intended to have semantics like
+CSS \[oq]large\[cq].
+.
+In troff output, the point size is increased by\~5; in MathML output,
+the expression uses
+.
+.RS
+.IP
+.EX
+<mstyle \%mathsize='big'>
+.EE
+.RE
+.
+.TP
+.IB e1\  smallover\  e2
+This is similar to
+.BR over ;
+.B smallover
+reduces the size of
+.I e1
+and
+.IR e2 ;
+it also puts less vertical space between
+.I e1
+or
+.I e2
+and the fraction bar.
+.
+The
+.B over
+primitive corresponds to the \*(tx
+.B \eover
+primitive in display styles;
+.B smallover
+corresponds to
+.B \eover
+in non-display styles.
+.
+.TP
+.BI vcenter\  e
+This vertically centers
+.I e
+about the math axis.
+.
+The math axis is the vertical position about which characters such as
+\[oq]\[pl]\[cq] and \[oq]\[mi]\[cq] are centered; also it is the
+vertical position used for the bar of fractions.
+.
+For example,
+.B sum
+is defined as
+.
+.RS
+.IP
+.B
+{ type "operator" vcenter size +5 \e(*S }
+.RE
+.
+.IP
+(Note that vcenter is silently ignored when generating MathML.)
+.
+.TP
+.IB e1\  accent\  e2
+This sets
+.I e2
+as an accent over
+.IR e1 .
+.I e2
+is assumed to be at the correct height for a lowercase letter;
+.I e2
+is moved down according to whether
+.I e1
+is taller or shorter than a lowercase letter.
+.
+For example,
+.B hat
+is defined as
+.
+.RS
+.IP
+.B
+accent { "^" }
+.RE
+.
+.IP
+.BR dotdot ,
+.BR dot ,
+.BR tilde ,
+.BR vec ,
+and
+.B dyad
+are also defined using the
+.B accent
+primitive.
+.
+.TP
+.IB e1\  uaccent\  e2
+This sets
+.I e2
+as an accent under
+.IR e1 .
+.I e2
+is assumed to be at the correct height for a character without a descender;
+.I e2
+is moved down if
+.I e1
+has a descender.
+.
+.B utilde
+is pre-defined using
+.B uaccent
+as a tilde accent below the baseline.
+.
+.TP
+.BI split\ \[dq] text \[dq]
+This has the same effect as simply
+.
+.RS
+.IP
+.I text
+.RE
+.
+.IP
+but
+.I text
+is not subject to macro expansion because it is quoted;
+.I text
+is split up and the spacing between individual characters is adjusted.
+.
+.TP
+.BI nosplit\  text
+This has the same effect as
+.
+.RS
+.IP
+.BI \[dq] text \[dq]
+.RE
+.
+.IP
+but because
+.I text
+is not quoted it is subject to macro expansion;
+.I text
+is not split up
+and the spacing between individual characters is not adjusted.
+.
+.TP
+.IB e\  opprime
+This is a variant of
+.B prime
+that acts as an operator on\~\c
+.IR e .
+.
+It produces a different result from
+.B prime
+in a case such as
+.BR A\ opprime\ sub\ 1 :
+with
+.B opprime
+the\~\c
+.B 1
+is tucked under the prime as a subscript to the\~\c
+.B A
+(as is conventional in mathematical typesetting),
+whereas with
+.B prime
+the\~\c
+.B 1
+is a subscript to the prime character.
+.
+The precedence of
+.B opprime
+is the same as that of
+.B bar
+and
+.BR under ,
+which is higher than that of everything except
+.B accent
+and
+.BR uaccent .
+.
+In unquoted text a\~\c
+.B \[aq]
+that is not the first character is treated like
+.BR opprime .
+.
+.TP
+.BI special\  text\ e
+This constructs a new object from\~\c
+.I e
+using a
+.BR troff (1)
+macro named
+.IR text .
+.
+When the macro is called,
+the string
+.B 0s
+contains the output for\~\c
+.IR e ,
+and the number registers
+.BR 0w ,
+.BR 0h ,
+.BR 0d ,
+.BR 0skern ,
+and
+.B 0skew
+contain the width, height, depth, subscript kern, and skew of\~\c
+.IR e .
+.
+(The
+.I "subscript kern"
+of an object says how much a subscript on that object should be tucked in;
+the
+.I skew
+of an object says how far to the right of the center of the object an
+accent over the object should be placed.)
+.
+The macro must modify
+.B 0s
+so that it outputs the desired result with its origin at the current
+point, and increase the current horizontal position by the width
+of the object.
+.
+The number registers must also be modified so that they correspond to the
+result.
+.
+.IP
+For example, suppose you wanted a construct that \[oq]cancels\[cq] an
+expression by drawing a diagonal line through it.
+.
+.RS
+.IP
+.ft B
+.if t .ne 6+\n(.Vu
+.br
+\&.EQ
+.br
+define cancel 'special Ca'
+.br
+\&.EN
+.br
+\&.de Ca
+.br
+\&.\ \ ds 0s \e
+.br
+\eZ'\e\e*(0s'\e
+.br
+\ev'\e\en(0du'\e
+.br
+\eD'l \e\en(0wu -\e\en(0hu-\e\en(0du'\e
+.br
+\ev'\e\en(0hu'
+.br
+\&..
+.ft
+.RE
+.
+.IP
+Then you could cancel an expression\~\c
+.I e
+with
+.BI \%cancel\ {\  e\  }
+.
+.IP
+Here's a more complicated construct that draws a box round an
+expression:
+.
+.RS
+.IP
+.ft B
+.if t .ne 11+\n(.Vu
+\&.EQ
+.br
+define box 'special Bx'
+.br
+\&.EN
+.br
+\&.de Bx
+.br
+\&.\ \ ds 0s \e
+.br
+\eZ'\eh'1n'\e\e*(0s'\e
+.br
+\eZ'\e
+.br
+\ev'\e\en(0du+1n'\e
+.br
+\eD'l \e\en(0wu+2n 0'\e
+.br
+\eD'l 0 -\e\en(0hu-\e\en(0du-2n'\e
+.br
+\eD'l -\e\en(0wu-2n 0'\e
+.br
+\eD'l 0 \e\en(0hu+\e\en(0du+2n'\e
+.br
+\&'\e
+.br
+\eh'\e\en(0wu+2n'
+.br
+\&.\ \ nr 0w +2n
+.br
+\&.\ \ nr 0d +1n
+.br
+\&.\ \ nr 0h +1n
+.br
+\&..
+.ft
+.RE
+.
+.TP
+.BI space\  n
+A positive value of the integer\~\c
+.I n
+(in hundredths of an em) sets the vertical spacing before the
+equation, a negative value sets the spacing after the equation,
+replacing the default values.
+.
+This primitive provides an interface to
+.BR groff 's
+.B \ex
+escape (but with opposite sign).
+.
+.IP
+This keyword has no effect if the equation is part of a
+.B pic
+picture.
+.
+.
+.\" ====================================================================
+.SS Extended primitives
+.\" ====================================================================
+.
+.TP
+.BI col\  n\  {\  .\|.\|.\  }
+.TQ
+.BI ccol\  n\  {\  .\|.\|.\  }
+.TQ
+.BI lcol\  n\  {\  .\|.\|.\  }
+.TQ
+.BI rcol\  n\  {\  .\|.\|.\  }
+.TQ
+.BI pile\  n\  {\  .\|.\|.\  }
+.TQ
+.BI cpile\  n\  {\  .\|.\|.\  }
+.TQ
+.BI lpile\  n\  {\  .\|.\|.\  }
+.TQ
+.BI rpile\  n\  {\  .\|.\|.\  }
+The integer value\~\c
+.I n
+(in hundredths of an em) increases the vertical spacing between rows,
+using
+.BR groff 's
+.B \ex
+escape (the value has no effect in MathML mode).
+Negative values are possible but have no effect.
+If there is more than a single value given in a matrix, the biggest one
+is used.
+.
+.
+.\" ====================================================================
+.SS Customization
+.\" ====================================================================
+.
+When
+.B eqn
+is generating troff markup, the appearance of equations is controlled
+by a large number of parameters.
+.
+They have no effect when generating MathML mode, which pushes
+typesetting and fine motions downstream to a MathML rendering engine.
+.
+These parameters can be set using the
+.B set
+command.
+.
+.TP
+.BI set\  p\ n
+This sets parameter\~\c
+.I p
+to value\~\c
+.IR n ;
+.IR n \~is
+an integer.
+.
+For example,
+.
+.RS
+.IP
+.B
+set x_height 45
+.RE
+.
+.IP
+says that
+.B eqn
+should assume an x\~height of 0.45\~ems.
+.
+.
+.RS
+.LP
+Possible parameters are as follows.
+.
+Values are in units of hundredths of an em unless otherwise stated.
+.
+These descriptions are intended to be expository rather than
+definitive.
+.
+.TP
+.B minimum_size
+.B eqn
+doesn't set anything at a smaller point-size than this.
+.
+The value is in points.
+.
+.TP
+.B fat_offset
+The
+.B fat
+primitive emboldens an equation by overprinting two copies of the
+equation horizontally offset by this amount.
+.
+This parameter is not used in MathML mode; instead, fat text uses
+.
+.RS
+.IP
+.EX
+<mstyle mathvariant='double-struck'>
+.EE
+.RE
+.
+.TP
+.B over_hang
+A fraction bar is longer by twice this amount than
+the maximum of the widths of the numerator and denominator;
+in other words, it overhangs the numerator and
+denominator by at least this amount.
+.
+.TP
+.B accent_width
+When
+.B bar
+or
+.B under
+is applied to a single character,
+the line is this long.
+.
+Normally,
+.B bar
+or
+.B under
+produces a line whose length is the width of the object to which it applies;
+in the case of a single character,
+this tends to produce a line that looks too long.
+.
+.TP
+.B delimiter_factor
+Extensible delimiters produced with the
+.B left
+and
+.B right
+primitives have a combined height and depth of at least this many
+thousandths of twice the maximum amount by which the sub-equation that
+the delimiters enclose extends away from the axis.
+.
+.TP
+.B delimiter_shortfall
+Extensible delimiters produced with the
+.B left
+and
+.B right
+primitives have a combined height and depth not less than the
+difference of twice the maximum amount by which the sub-equation that
+the delimiters enclose extends away from the axis and this amount.
+.
+.TP
+.B null_delimiter_space
+This much horizontal space is inserted on each side of a fraction.
+.
+.TP
+.B script_space
+The width of subscripts and superscripts is increased by this amount.
+.
+.TP
+.B thin_space
+This amount of space is automatically inserted after punctuation
+characters.
+.
+.TP
+.B medium_space
+This amount of space is automatically inserted on either side of
+binary operators.
+.
+.TP
+.B thick_space
+This amount of space is automatically inserted on either side of
+relations.
+.
+.TP
+.B x_height
+The height of lowercase letters without ascenders such as \[oq]x\[cq].
+.
+.TP
+.B axis_height
+The height above the baseline of the center of characters such as
+\[oq]\[pl]\[cq] and \[oq]\[mi]\[cq].
+.
+It is important that this value is correct for the font
+you are using.
+.
+.TP
+.B default_rule_thickness
+This should set to the thickness of the
+.B \e(ru
+character, or the thickness of horizontal lines produced with the
+.B \eD
+escape sequence.
+.
+.TP
+.B num1
+The
+.B over
+command shifts up the numerator by at least this amount.
+.
+.TP
+.B num2
+The
+.B smallover
+command shifts up the numerator by at least this amount.
+.
+.TP
+.B denom1
+The
+.B over
+command shifts down the denominator by at least this amount.
+.
+.TP
+.B denom2
+The
+.B smallover
+command shifts down the denominator by at least this amount.
+.
+.TP
+.B sup1
+Normally superscripts are shifted up by at least this amount.
+.
+.TP
+.B sup2
+Superscripts within superscripts or upper limits
+or numerators of
+.B smallover
+fractions are shifted up by at least this amount.
+.
+This is usually less than sup1.
+.
+.TP
+.B sup3
+Superscripts within denominators or square roots
+or subscripts or lower limits are shifted up by at least
+this amount.
+.
+This is usually less than sup2.
+.
+.TP
+.B sub1
+Subscripts are normally shifted down by at least this amount.
+.
+.TP
+.B sub2
+When there is both a subscript and a superscript, the subscript is
+shifted down by at least this amount.
+.
+.TP
+.B sup_drop
+The baseline of a superscript is no more than this much amount below
+the top of the object on which the superscript is set.
+.
+.TP
+.B sub_drop
+The baseline of a subscript is at least this much below the bottom of
+the object on which the subscript is set.
+.
+.TP
+.B big_op_spacing1
+The baseline of an upper limit is at least this much above the top of
+the object on which the limit is set.
+.
+.TP
+.B big_op_spacing2
+The baseline of a lower limit is at least this much below the bottom
+of the object on which the limit is set.
+.
+.TP
+.B big_op_spacing3
+The bottom of an upper limit is at least this much above the top of
+the object on which the limit is set.
+.
+.TP
+.B big_op_spacing4
+The top of a lower limit is at least this much below the bottom of the
+object on which the limit is set.
+.
+.TP
+.B big_op_spacing5
+This much vertical space is added above and below limits.
+.
+.TP
+.B baseline_sep
+The baselines of the rows in a pile or matrix are normally this far
+apart.
+.
+In most cases this should be equal to the sum of
+.B num1
+and
+.BR denom1 .
+.
+.TP
+.B shift_down
+The midpoint between the top baseline and the bottom baseline in a
+matrix or pile is shifted down by this much from the axis.
+.
+In most cases this should be equal to
+.BR axis_height .
+.
+.TP
+.B column_sep
+This much space is added between columns in a matrix.
+.
+.TP
+.B matrix_side_sep
+This much space is added at each side of a matrix.
+.
+.TP
+.B draw_lines
+If this is non-zero, lines are drawn using the
+.B \eD
+escape sequence, rather than with the
+.B \el
+escape sequence and the
+.B \e(ru
+character.
+.
+.TP
+.B body_height
+The amount by which the height of the equation exceeds this is added
+as extra space before the line containing the equation (using
+.BR \ex ).
+.
+The default value is 85.
+.
+.TP
+.B body_depth
+The amount by which the depth of the equation exceeds this is added as
+extra space after the line containing the equation (using
+.BR \ex ).
+.
+The default value is 35.
+.
+.TP
+.B nroff
+If this is non-zero,
+then
+.B ndefine
+behaves like
+.B define
+and
+.B tdefine
+is ignored, otherwise
+.B tdefine
+behaves like
+.B define
+and
+.B ndefine
+is ignored.
+.
+The default value is\~0 (This is typically changed to\~1 by the
+.I eqnrc
+file for the
+.BR ascii ,
+.BR latin1 ,
+.BR utf8 ,
+and
+.B cp1047
+devices.)
+.
+.
+.LP
+A more precise description of the role of many of these
+parameters can be found in Appendix\~H of
+.IR "The \*(txbook" .
+.RE
+.
+.
+.\" ====================================================================
+.SS Macros
+.\" ====================================================================
+.
+Macros can take arguments.
+.
+In a macro body,
+.BI $ n
+where
+.I n
+is between 1 and\~9, is replaced by the
+.IR n th
+argument if the macro is called with arguments;
+if there are fewer than
+.IR n \~arguments,
+it is replaced by nothing.
+.
+A word containing a left parenthesis where the part of the word
+before the left parenthesis has been defined using the
+.B define
+command is recognized as a macro call with arguments; characters
+following the left parenthesis up to a matching right parenthesis are
+treated as comma-separated arguments; commas inside nested parentheses
+do not terminate an argument.
+.
+.TP
+.BI sdefine\  name\ X\ anything\ X
+This is like the
+.B define
+command, but
+.I name
+is not recognized if called with arguments.
+.
+.TP
+.BI include\ \[dq] file \[dq]
+.TQ
+.BI copy\ \[dq] file \[dq]
+Include the contents of
+.I file
+.RB ( include
+and
+.B copy
+are synonyms).
+.
+Lines of
+.I file
+beginning with
+.B .EQ
+or
+.B .EN
+are ignored.
+.
+.TP
+.BI ifdef\  name\ X\ anything\ X
+If
+.I name
+has been defined by
+.B define
+(or has been automatically defined because
+.I name
+is the output device) process
+.IR anything ;
+otherwise ignore
+.IR anything .
+.
+.I X
+can be any character not appearing in
+.IR anything .
+.
+.TP
+.BI undef\  name
+Remove definition of
+.IR name ,
+making it undefined.
+.
+.
+.LP
+Besides the macros mentioned above, the following definitions are available:
+.BR Alpha ,
+.BR Beta ,
+\&.\|.\|.,
+.B Omega
+(this is the same as
+.BR ALPHA ,
+.BR BETA ,
+\&.\|.\|.,
+.BR OMEGA ),
+.B ldots
+(three dots on the base line), and
+.BR dollar .
+.
+.
+.\" ====================================================================
+.SS Fonts
+.\" ====================================================================
+.
+.B eqn
+normally uses at least two fonts to set an equation:
+an italic font for letters,
+and a roman font for everything else.
+.
+The existing
+.B gfont
+command
+changes the font that is used as the italic font.
+.
+By default this is\~\c
+.BR I .
+The font that is used as the roman font can be changed using the new
+.B grfont
+command.
+.
+.TP
+.BI grfont\  f
+Set the roman font to\~\c
+.IR f .
+.
+.
+.LP
+The
+.B italic
+primitive uses the current italic font set by
+.BR gfont ;
+the
+.B roman
+primitive uses the current roman font set by
+.BR grfont .
+.
+There is also a new
+.B gbfont
+command, which changes the font used by the
+.B bold
+primitive.
+.
+If you only use the
+.BR roman ,
+.B italic
+and
+.B bold
+primitives to changes fonts within an equation, you can change all the
+fonts used by your equations just by using
+.BR gfont ,
+.B grfont
+and
+.B gbfont
+commands.
+.
+.
+.LP
+You can control which characters are treated as letters
+(and therefore set in italics) by using the
+.B chartype
+command described above.
+.
+A type of
+.B letter
+causes a character to be set in italic type.
+.
+A type of
+.B digit
+causes a character to be set in roman type.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/eqnrc
+Initialization file.
+.
+.
+.\" ====================================================================
+.SH MATHML MODE LIMITATIONS
+.\" ====================================================================
+.
+MathML is designed on the assumption that it cannot know the exact
+physical characteristics of the media and devices on which it will
+be rendered.
+.
+It does not support fine control of motions and sizes to the same
+degree troff does.
+.
+Thus:
+.
+.IP *
+.B eqn
+parameters have no effect on the generated MathML.
+.
+.IP *
+The
+.BR special ,
+.BR up ,
+.BR down ,
+.BR fwd ,
+and
+.B back
+operations cannot be implemented, and yield a MathML
+\[oq]<merror>\[cq] message instead.
+.
+.IP *
+The
+.B vcenter
+keyword is silently ignored, as centering on the math axis is the
+MathML default.
+.
+.IP *
+Characters that
+.B eqn
+over troff sets extra large \(en notably the integral sign \(en may
+appear too small and need to have their \[oq]<mstyle>\[cq] wrappers
+adjusted by hand.
+.
+.
+.LP
+As in its troff mode,
+.B eqn
+in MathML mode leaves the
+.B .EQ
+and
+.B .EN
+delimiters in place for displayed equations, but emits no explicit
+delimiters around inline equations.
+.
+They can, however, be recognized as strings that begin with
+\[oq]<math>\[cq] and end with \[oq]</math>\[cq] and do not cross line
+boundaries.
+.
+.
+.LP
+See section \[lq]Bugs\[rq] below for translation limits specific to
+.BR eqn .
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+Inline equations are set at the point size that is current at the
+beginning of the input line.
+.
+.
+.LP
+In MathML mode, the
+.B mark
+and
+.B lineup
+features don't work.
+.
+These could, in theory, be implemented with \[oq]<maligngroup>\[cq]
+elements.
+.
+.
+.LP
+In MathML mode, each digit of a numeric literal gets a separate
+\[oq]<mn>\:</mn>\[cq] pair, and decimal points are tagged with
+\[oq]<mo>\:</mo>\[cq].
+.
+This is allowed by the specification, but inefficient.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR groff (1),
+.BR troff (1),
+.BR pic (1),
+.BR groff_font (5),
+.I The\ \*[tx]book
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[eqn_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" tab-width: 12
+.\" End:
+.\" vim: set filetype=groff tabstop=12:
diff --git a/upstream/mageia-cauldron/man1/escp2topbm.1 b/upstream/mageia-cauldron/man1/escp2topbm.1
new file mode 100644
index 00000000..926edaf7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/escp2topbm.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Escp2topbm User Manual" 0 "14 July 2015" "netpbm documentation"
+
+.SH NAME
+
+escp2topbm - convert an ESC/P2 printer file to a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBescp2topbm\fP
+[\fIprintfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBescp2topbm\fP reads an ESC/P2 printer control stream as input.
+It produces a PBM image as output.
+.PP
+\fBescp2topbm\fP filters the raster graphic content from an Epson
+ESC/P2 printer control stream and writes the image it would print as a
+standard (raw) PBM image.
+.PP
+The input is from the file named by the \fIprintfile\fP argument, or
+from Standard Input if you don't specify \fIprintfile\fP.  The output is
+to Standard Output.
+.PP
+\fBescp2topbm\fP understands compression modes 0 (uncompressed)
+and 1 (RLE compressed) in the Epson input stream.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBescp2topbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+.PP
+Before Netpbm 10.72 (September 2015), the Netpbm common option
+\fB-plain\fP has no effect on \fBescp2topbm\fP .
+
+.UN hints
+.SH HINTS
+.PP
+As \fBescp2topbm\fP is a simple program, created mainly to test
+\fBpbmtoescp2\fP, there are some restrictions:
+
+
+.IP \(bu
+\fBescp2topbm\fP looks only at "ESC." sequences and ignores
+all data outside these Escape sequences.
+
+.IP \(bu
+\fBescp2topbm\fP assumes that only one raster graphic is in the
+printer stream.  If this isn't true, the result is garbage.
+
+.IP \(bu
+\fBescp2topbm\fP assumes that all "ESC."  sequences use the same
+width value.  If this isn't true, the result is garbage.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoescp2" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2003 by Ulrich Walcher 
+(\fIu.walcher@gmx.de\fP).
+
+.UN history
+.SH HISTORY
+.PP
+\fBescp2topbm\fP was added to Netpbm in Release 10.18 (August 2003);
+it was created around the same time.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/escp2topbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/etf2ly.1 b/upstream/mageia-cauldron/man1/etf2ly.1
new file mode 100644
index 00000000..83b70943
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/etf2ly.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH ETF2LY "1" "January 2024" "etf2ly (LilyPond) 2.24.3" "User Commands"
+.SH NAME
+etf2ly \- manual page for etf2ly (LilyPond) 2.24.3
+.SH SYNOPSIS
+.B etf2ly
+[\fI\,OPTION\/\fR]... \fI\,ETF-FILE\/\fR
+.SH DESCRIPTION
+Enigma Transport Format is a format used by Coda Music Technology's
+Finale product.  etf2ly converts a subset of ETF to a ready\-to\-use LilyPond file.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to FILE
+.TP
+\fB\-w\fR, \fB\-\-warranty\fR
+show warranty and copyright
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH "SEE ALSO"
+The full documentation for
+.B etf2ly
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B etf2ly
+programs are properly installed at your site, the command
+.IP
+.B info etf2ly
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/exif.1 b/upstream/mageia-cauldron/man1/exif.1
new file mode 100644
index 00000000..9029211a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/exif.1
@@ -0,0 +1,237 @@
+.\" Copyright © 2002-2012 by Thomas Pircher (tehpeh at gmx dot net),
+.\" Dan Fandrich et. al.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" License.
+.\"
+.TH exif 1 "2012-07-13" "exif 0.6.21.1" "command line front-end to libexif"
+.SH "NAME"
+exif \- shows EXIF information in JPEG files
+.SH "SYNOPSIS"
+.BI "exif [ " "OPTION" " ] [ " "file..." " ]"
+.SH DESCRIPTION
+.B "exif"
+is a small command-line utility to show and change EXIF information in JPEG
+files.
+.PP
+Most digital cameras produce EXIF files, which are JPEG files with extra tags
+that contain information about the image. The
+.B "exif"
+command-line utility allows you to read EXIF information from and write EXIF
+information to those files.
+.B "exif"
+internally uses the
+.B "libexif"
+library.
+.PP
+Each input file given on the command line is acted upon in turn, using 
+all the options given. Execution will be aborted immediately if one
+file is not readable or does not contain EXIF tags.
+.PP
+As EXIF tags are read, any unknown ones are discarded and known ones are
+automatically converted into the correct format, if they aren't already.
+Corrupted MakerNote tags are also removed, but no format changes are made.
+.SH "OPTIONS"
+.TP
+.BI "\-v, \-\-version"
+Display the
+.B exif
+version number.
+.TP
+.BI "\-i, \-\-ids"
+Show ID numbers instead of tag names.
+.TP
+.BI "\-t, \-\-tag=" "TAG"
+Select only this
+.IR "TAG" .
+.I "TAG"
+is the tag title, the short tag name, or the tag number
+(hexadecimal numbers are prefixed with 0x), from the IFD specified
+with \-\-ifd.  The tag title is dependent on the current locale, whereas
+name and number are locale-independent.
+.TP
+.BI "\-\-ifd=" "IFD"
+Select a tag or tags from this
+.IR "IFD" .
+Valid IFDs are "0", "1", "EXIF", "GPS", and "Interoperability".
+Defaults to "0".
+.TP
+.BI "\-l, \-\-list\-tags"
+List all known EXIF tags and IFDs.  A JPEG image must be provided, and
+those tags which appear in the file are shown with an asterisk in the
+corresponding position in the list.
+.TP
+.BI "\-|, \-\-show\-mnote"
+Show the contents of the MakerNote tag.  The contents of this tag are nonstandard
+(and often undocumented) and may therefore not be recognized, or if they are
+recognized they may not necessarily be interpreted correctly.
+.TP
+.BI "\-\-remove"
+Remove the tag or (if no tag is specified) the entire IFD.
+.TP
+.BI "\-s, \-\-show\-description"
+Show description of tag.  The \-\-tag option must also be given.
+.TP
+.BI "\-e, \-\-extract\-thumbnail"
+Extract the thumbnail, writing the thumbnail image to the file specified
+with \-\-output.
+.TP
+.BI "\-r, \-\-remove\-thumbnail"
+Remove the thumbnail from the image, writing the new image to the file specified
+with \-\-output.
+.TP
+.BI "-n, \-\-insert\-thumbnail=" "FILE"
+Insert
+.I "FILE"
+as thumbnail.  No attempt is made to ensure that the contents of
+.I "FILE"
+are in a valid thumbnail format.
+.TP
+.BI "\-\-no-fixup"
+Do not attempt to fix EXIF specification violations when reading tags.
+When used in conjunction with \-\-create-exif, this option inhibits the
+creation of the mandatory tags.
+.B exif
+will otherwise remove illegal or unknown tags, add some mandatory tags using
+default values, and change the data type of some tags to match that required
+by the specification.
+.TP
+.BI "\-o, \-\-output=" "FILE"
+Write output image to
+.IR "FILE" .
+If this option is not given and an image file must be written, the
+name used is the same as the input file with the suffix ".modified.jpeg".
+.TP
+.BI "\-\-set\-value=" "VALUE"
+Set the data for the tag specified with \-\-tag and \-\-ifd to
+.IR "VALUE" .
+Compound values consisting of multiple components are separated with
+spaces.
+.TP
+.BI "\-c, \-\-create-exif"
+Create EXIF data if it does not exist. Mandatory tags are created with
+default values unless the \-\-no-fixup option is given.
+This option can be used instead of specifying an input file name in most
+cases, to operate on the default values of the mandatory set of EXIF tags.
+In this case, the \-\-output option has no effect and no file is written.
+.TP
+.BI "\-m, \-\-machine\-readable"
+Produce output in a machine-readable (tab-delimited) format.
+The \-\-xml-output and \-\-machine\-readable options are mutually exclusive.
+.TP
+.BI "\-w, \-\-width=" "N"
+Set the maximum width of the output to N characters (default 80). This does
+not apply to some output formats (e.g. XML).
+.TP
+.BI "\-x, \-\-xml-output"
+Produce output in an XML format (when possible).
+The \-\-xml-output and \-\-machine\-readable options are mutually exclusive.
+Note that the XML schema changes with the locale, and it sometimes produces
+invalid XML. This option is not recommended.
+.TP
+.BI "\-d, \-\-debug"
+Show debugging messages. Also, when processing a file that contains corrupted
+data, this option causes
+.B exif
+to attempt to continue processing. Normally,
+corrupted data causes an abort.
+.SS "Help options"
+.TP
+.BI "\-?, \-\-help"
+Show help message.
+.TP
+.BI "\-\-usage"
+Display brief usage message.
+.SH "EXAMPLES"
+Display all recognized EXIF tags in an image and the tag contents, with bad
+tags fixed:
+.LP
+.RS
+exif image.jpg
+.RE
+.LP
+Display a table listing all known EXIF tags and whether each one exists in the
+given image:
+.LP
+.RS
+exif \-\-list-tags \-\-no-fixup image.jpg
+.RE
+.LP
+Display details on all XResolution tags found in the given image:
+.LP
+.RS
+exif \-\-tag=XResolution \-\-no-fixup image.jpg
+.RE
+.LP
+Display the raw contents of the "Model" tag in the given image (with a newline
+character appended):
+.LP
+.RS
+exif \-\-ifd=0 \-\-tag=Model \-\-machine-readable image.jpg
+.RE
+.LP
+Extract the thumbnail into the file thumbnail.jpg:
+.LP
+.RS
+exif \-\-extract-thumbnail \-\-output=thumbnail.jpg image.jpg
+.RE
+.LP
+Display a list of the numeric values of only the EXIF tags in the thumbnail IFD
+(IFD 1) and the tag values:
+.LP
+.RS
+exif \-\-ids \-\-ifd=1 \-\-no-fixup image.jpg
+.RE
+.LP
+Display the meaning of tag 0x9209 in the "EXIF" IFD according to the EXIF
+specification:
+.LP
+.RS
+exif \-\-show-description \-\-ifd=EXIF \-\-tag=0x9209
+.RE
+.LP
+Add an Orientation tag with value "Bottom-left" (4) to an existing image,
+leaving the existing tags untouched:
+.LP
+.RS
+exif \-\-output=new.jpg \-\-ifd=0 \-\-tag=0x0112 \-\-set-value=4 \-\-no-fixup image.jpg
+.RE
+.LP
+Add a YCbCr Sub-Sampling tag with value 2,1 (a.k.a YCbCr 4:2:2) to an
+existing image and fix the existing tags, if necessary:
+.LP
+.RS
+exif \-\-output=new.jpg \-\-tag=YCbCrSubSampling \-\-ifd=0 \-\-set-value='2 1' image.jpg
+.RE
+.LP
+Remove the "User Comment" tag from an image:
+.LP
+.RS
+exif \-\-output=new.jpg \-\-remove \-\-tag="User Comment" \-\-ifd=EXIF image.jpg
+.RE
+.LP
+Display a table with all known EXIF tags, highlighting mandatory ones:
+.LP
+.RS
+exif \-cl
+.RE
+.LP
+.SH "AUTHOR"
+.B exif
+was written by Lutz Mueller <lutz@users.sourceforge.net>
+and numerous contributors.
+This man page is Copyright \(co 2002-2012 Thomas Pircher,
+Dan Fandrich and others.
+.SH "SEE ALSO"
+.UR "https://libexif.github.io/"
+.BR "https://libexif.github.io/"
diff --git a/upstream/mageia-cauldron/man1/expand.1 b/upstream/mageia-cauldron/man1/expand.1
new file mode 100644
index 00000000..572f00a1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/expand.1
@@ -0,0 +1,54 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH EXPAND "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+expand \- convert tabs to spaces
+.SH SYNOPSIS
+.B expand
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Convert tabs in each FILE to spaces, writing to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-i\fR, \fB\-\-initial\fR
+do not convert tabs after non blanks
+.TP
+\fB\-t\fR, \fB\-\-tabs\fR=\fI\,N\/\fR
+have tabs N characters apart, not 8
+.TP
+\fB\-t\fR, \fB\-\-tabs\fR=\fI\,LIST\/\fR
+use comma separated list of tab positions.
+The last specified position can be prefixed with '/'
+to specify a tab size to use after the last
+explicitly specified tab stop.  Also a prefix of '+'
+can be used to align remaining tab stops relative to
+the last specified tab stop instead of the first column
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBunexpand\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/expand>
+.br
+or available locally via: info \(aq(coreutils) expand invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/expr.1 b/upstream/mageia-cauldron/man1/expr.1
new file mode 100644
index 00000000..54cd84fe
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/expr.1
@@ -0,0 +1,107 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH EXPR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+expr \- evaluate expressions
+.SH SYNOPSIS
+.B expr
+\fI\,EXPRESSION\/\fR
+.br
+.B expr
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Print the value of EXPRESSION to standard output.  A blank line below
+separates increasing precedence groups.  EXPRESSION may be:
+.TP
+ARG1 | ARG2
+ARG1 if it is neither null nor 0, otherwise ARG2
+.TP
+ARG1 & ARG2
+ARG1 if neither argument is null or 0, otherwise 0
+.TP
+ARG1 < ARG2
+ARG1 is less than ARG2
+.TP
+ARG1 <= ARG2
+ARG1 is less than or equal to ARG2
+.TP
+ARG1 = ARG2
+ARG1 is equal to ARG2
+.TP
+ARG1 != ARG2
+ARG1 is unequal to ARG2
+.TP
+ARG1 >= ARG2
+ARG1 is greater than or equal to ARG2
+.TP
+ARG1 > ARG2
+ARG1 is greater than ARG2
+.TP
+ARG1 + ARG2
+arithmetic sum of ARG1 and ARG2
+.TP
+ARG1 \- ARG2
+arithmetic difference of ARG1 and ARG2
+.TP
+ARG1 * ARG2
+arithmetic product of ARG1 and ARG2
+.TP
+ARG1 / ARG2
+arithmetic quotient of ARG1 divided by ARG2
+.TP
+ARG1 % ARG2
+arithmetic remainder of ARG1 divided by ARG2
+.TP
+STRING : REGEXP
+anchored pattern match of REGEXP in STRING
+.TP
+match STRING REGEXP
+same as STRING : REGEXP
+.TP
+substr STRING POS LENGTH
+substring of STRING, POS counted from 1
+.TP
+index STRING CHARS
+index in STRING where any CHARS is found, or 0
+.TP
+length STRING
+length of STRING
+.TP
++ TOKEN
+interpret TOKEN as a string, even if it is a
+.IP
+keyword like 'match' or an operator like '/'
+.TP
+( EXPRESSION )
+value of EXPRESSION
+.PP
+Beware that many operators need to be escaped or quoted for shells.
+Comparisons are arithmetic if both ARGs are numbers, else lexicographical.
+Pattern matches return the string matched between \e( and \e) or null; if
+\e( and \e) are not used, they return the number of characters matched or 0.
+.PP
+Exit status is 0 if EXPRESSION is neither null nor 0, 1 if EXPRESSION is null
+or 0, 2 if EXPRESSION is syntactically invalid, and 3 if an error occurred.
+.SH AUTHOR
+Written by Mike Parker, James Youngman, and Paul Eggert.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/expr>
+.br
+or available locally via: info \(aq(coreutils) expr invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/extractres.1 b/upstream/mageia-cauldron/man1/extractres.1
new file mode 100644
index 00000000..9ae7499e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/extractres.1
@@ -0,0 +1,70 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH EXTRACTRES "1" "October 2021" "extractres 2.07" "User Commands"
+.SH NAME
+extractres - extract resources from a PostScript document
+.SH SYNOPSIS
+.B extractres
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Extract resources from a PostScript document.
+.TP
+\fB\-m\fR, \fB\-\-merge\fR
+merge resources of the same name into one file
+(needed e.g. for fonts output in multiple blocks)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+.B Extractres
+extracts resources (fonts, procsets, patterns, files, etc) appearing in a
+PostScript document, and puts appropriate
+.B %%IncludeResource
+comments in the document prologue.
+The extracted resources are written to files with the same name as the
+resource, and an appropriate extension.
+The pipeline
+.sp
+.RS
+extractres file.ps | includeres >out.ps
+.RE
+.sp
+will move all resources appearing in a document to the document prologue,
+removing redundant copies.
+The output file can then be put through page re-arrangement filters such as
+.B psnup
+or 
+.B pstops
+safely.
+
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH BUGS
+.B extractres
+does not alter the
+.B %%DocumentSuppliedResources
+comments.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2012\-2019.
+.br
+Copyright \(co Angus J. C. Duggan 1991\-1997.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/eyuvtoppm.1 b/upstream/mageia-cauldron/man1/eyuvtoppm.1
new file mode 100644
index 00000000..0e400b86
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/eyuvtoppm.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Eyuvtoppm User Manual" 0 "22 April 2001" "netpbm documentation"
+
+.SH NAME
+eyuvtoppm - convert a Berkeley YUV file to a PPM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBeyuvtoppm\fP
+[\fB--width\fP
+\fIwidth\fP]
+[\fB--height\fP
+\fIheight\fP]
+[\fIeyuvfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBeyuvtoppm\fP reads a Berkeley Encoder YUV (not the same as
+Abekas YUV) file as input and produces a PPM image on Standard Output.
+.PP
+With no filename argument takes input from Standard Input.
+Otherwise, \fIeyuvfile \fP is the file specification of the input
+file.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBeyuvtoppm\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB--width\fP \fIwidth\fP
+Width of the image, in pixels.  Must be an even number.
+
+.TP
+\fB--height\fP \fIheight\fP
+Height of the image, in pixels.  Must be an even number.
+
+
+.PP
+These options are mandatory.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoeyuv" (1)\c
+\&,
+.BR "yuvtoppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/eyuvtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/factor.1 b/upstream/mageia-cauldron/man1/factor.1
new file mode 100644
index 00000000..0b4d9aa3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/factor.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH FACTOR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+factor \- factor numbers
+.SH SYNOPSIS
+.B factor
+[\fI\,NUMBER\/\fR]...
+.br
+.B factor
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the prime factors of each specified integer NUMBER.  If none
+are specified on the command line, read them from standard input.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Paul Rubin, Torbjorn Granlund, and Niels Moller.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/factor>
+.br
+or available locally via: info \(aq(coreutils) factor invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/false.1 b/upstream/mageia-cauldron/man1/false.1
new file mode 100644
index 00000000..bbfd51fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/false.1
@@ -0,0 +1,40 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH FALSE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+false \- do nothing, unsuccessfully
+.SH SYNOPSIS
+.B false
+[\fI\,ignored command line arguments\/\fR]
+.br
+.B false
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Exit with a status code indicating failure.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NOTE: your shell may have its own version of false, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/false>
+.br
+or available locally via: info \(aq(coreutils) false invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/faxformat.1 b/upstream/mageia-cauldron/man1/faxformat.1
new file mode 100644
index 00000000..3749d8d7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/faxformat.1
@@ -0,0 +1,105 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Fax Formats" 1 "03 December 2008" "netpbm documentation"
+
+.SH SYNOPSIS
+.PP
+This page, part of the
+.BR "Netpbm user's guide" (1)\c
+\&,
+describes FAX formats in relation to Netpbm facilities.
+
+.SH DESCRIPTION
+.PP
+The ITU (formerly CCITT) publishes standards for operation of fax machines
+(the idea is to provide a way to be sure that a fax machine is able to receive
+a fax sent by another).  These standards incidentally specify graphics file
+formats -- a protocol for representing a visual image in sequences of bits.
+.PP
+The two relevant standards are called Group 3 (G3) and Group 4 (G4) (Groups
+1 and 2 are analog standards no longer in use).  Virtually every fax machine
+in existence conforms at least generally to at least one of these standards.
+.PP
+The standard for Group 3 fax is defined in ITU Recommendation T.4.  In the
+U.S., that is implemented by EIA standards EIA-465 and EIA-466.  These
+standards cover more than the file format as well, including how to transmit
+bits over a telephone line and procedures for handling document transmissions.
+.PP
+G3 faxes are 204 dots per inch (dpi) horizontally and 98 dpi (196
+dpi optionally, in fine-detail mode) vertically.
+.PP
+The standards specify three file formats (also called coding methods and
+compression schemes -- remember the standard doesn't mention computer files;
+it talks about the format of a stream of bits travelling over a telephone
+line):
+
+
+
+.TP
+MH
+This compresses in one dimension: it compresses individual raster lines
+but makes no attempt to compress redundancy between lines.
+.sp
+One dimensional compression is traditionally the best a fax machine could
+handle because G3 neither assumes error free transmission not retransmits when
+errors occur, and receiving fax machines traditionally could not afford to
+buffer much of a page.  It's important that when there is an error in a raster
+line, its impact not spread to many lines after it.
+.sp
+All Group 3 and Group 4 fax machines must be able to send and receive MH.
+.sp
+MH is sometimes called "G3," but that is a poor name because
+while the Group 3 standard does specify MH, it has always specified other
+formats too.
+.sp
+MH is sometimes called "T4" based on the name of the
+document that specifies it, ITU T.4.  But this is a poor name because
+T.4 also specifies MR.
+
+
+.TP
+MR
+This compresses in two dimensions, horizontally and vertically.
+.sp
+MR has always been part of the Group 3 standard, but is optional
+(a Group 3 fax machine may or may not be able to send and receive it).
+
+.TP
+MMR
+This is a more advanced format than the others.  It is even more
+two-dimensional than MR.  It is optional in the Group 3 standard, and didn't
+even exist in earlier versions of it.  It was developed specifically for the
+Group 4 standard, but then added to an extended Group 3 standard as well.
+.sp
+MMR is sometimes called Group 4, but that is a poor name because of
+the fact that it is also part of the current Group 3 standard.
+.sp
+MMR is sometimes called "T6" based on the name of the document
+ that specifies it, ITU T.6.
+
+
+.PP
+\fBg3topbm\fP converts the MH format to PBM.  \fBpbmtog3\fP converts
+PBM to MH.
+.PP
+There is no Netpbm program to convert to or from other fax formats.
+
+.SH TIFF
+.PP
+The TIFF format is flexible enough to allow lots of different coding
+methods, within it.  There are TIFF subformats for MH, MR, and MMR, among
+others.  These are particularly useful when you receive a fax as a TIFF file.
+.PP
+\fBtifftopnm\fP recognizes and can convert from any of these.
+.PP
+\fBpamtotiff\fP can convert to any of these; you use command options
+to choose which.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/faxformat.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/fgconsole.1 b/upstream/mageia-cauldron/man1/fgconsole.1
new file mode 100644
index 00000000..12965a57
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fgconsole.1
@@ -0,0 +1,50 @@
+.TH FGCONSOLE 1 "14 February 2002" "kbd"
+
+.SH NAME
+fgconsole \- print the number of the active VT.
+
+.SH SYNOPSIS
+.B fgconsole
+[
+.B \-h \-\-help
+|
+.B \-V \-\-version
+|
+.B \-n \-\-next-available
+]
+.SH DESCRIPTION
+If the active Virtual Terminal is
+.IR /dev/ttyN ,
+then prints
+.I N
+on standard output.
+
+If the console is a serial console, then
+"serial"
+is printed instead.
+.TP
+.I \-h \-\-help
+Prints short usage message and exits.
+.TP
+.I \-V \-\-version
+Prints version number and exits.
+.TP
+.I \-\-next\-available
+Will show the next unallocated virtual terminal. Normally 6 virtual
+terminals are allocated, with number 7 used for X; this will return
+"8" in this case.
+
+.SH NOTES
+Under
+.IR devfs ,
+the consoles are in
+.IR /dev/vc/N .
+.I devfsd
+may maintain symlinks for compatibility.
+.SH "SEE ALSO"
+.BR chvt (1).
+.\" .SH "AUTHORS"
+.\" Andries Brouwer
+.\" .br
+.\" Manpage by Alastair McKinstry <mckinstry@computer.org>
+
diff --git a/upstream/mageia-cauldron/man1/fiascotopnm.1 b/upstream/mageia-cauldron/man1/fiascotopnm.1
new file mode 100644
index 00000000..e57945c6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fiascotopnm.1
@@ -0,0 +1,231 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Fiascotopnm User Manual" 0 "12 July 2000" "netpbm documentation"
+
+.SH NAME
+fiascotopnm - Convert compressed FIASCO image to PGM, or PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBfiascotopnm \fP
+[\fIoption\fP]...
+[\fIfilename\fP]...
+.PP
+All option names may be abbreviated; for example, --output may be
+written --outp or --ou. For all options an one letter short option
+is provided. Mandatory or optional arguments to long options are
+mandatory or optional for short options, too. Both short and long
+options are case sensitive.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBfiascotopnm\fP decompresses the named FIASCO files, or the
+Standard Input if no file is named, and writes the images as PGM, or
+PPM files, depending on whether the FIASCO image is black and white or
+color.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBfiascotopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-o\fP[\fIname\fP], \fB--output=\fP[\fIname\fP]
+ Write decompressed image to the file \fIname\fP.ppm (if PPM) or
+\fIname\fP.pgm (if PGM).  If \fIname\fP is \fB-\fP, then produce
+the image file on the standard output. The optional argument
+\fIname\fP can be omitted, then the input filename is used as
+basename with the suffix .ppm or .pgm. In case of video streams, the
+frames are stored in the files \fIname\fP.\fBN\fP.ppm where \fBN\fP
+is the frame number (of the form 00..0 - 99..9); output on the
+standard output is not possible with video streams.
+.sp
+ If \fIname\fP is a relative path and the environment variable
+\fBFIASCO_IMAGES\fP is a (colon-separated) list of directories, then
+the output file(s) are written to the first (writable) directory of
+this list. Otherwise, the current directory is used to store the
+output file(s).
+
+.TP
+\fB-r\fP, \fB--fast\fP
+Decompress images in the 4:2:0 format; i.e., each chroma channel is
+decompressed to an image of halved width and height. Use this option
+on slow machines when the desired frame rate is not achieved; the
+output quality is only slightly decreased. 
+
+.TP
+\fB-d\fP, \fB--double\fP
+Double the size of the X11 window both in width and height; no pixel
+interpolation is used, each pixel is just replaced by four identical
+pixels.
+
+.TP
+\fB-p\fP, \fB--panel\fP
+Show a panel with play, stop, pause, record and exit buttons to
+control the display of videos. When pressing the record button, all
+frames are decompressed and stored in memory. The other buttons work
+in the usual way.
+
+.TP
+\fB-m\fP \fIN\fP, \fB--magnify=\fP\fIN\fP
+Set magnification of the decompressed image. Positive values enlarge
+and negative values reduce the image width and height by a factor of
+2^|\fIN\fP|.
+
+.TP
+\fB-s\fP \fIN\fP, \fB--smoothing=\fP\fIN\fP
+Smooth decompressed image(s) along the partitioning borders by the
+given amount \fIN\fP. \fIN\fP is 1 (minimum) to 100 (maximum); default
+is 70. When \fIN\fP=0, then the smoothing amount specified in the
+FIASCO file is used (defined by the FIASCO coder).
+
+.TP
+\fB-F\fP \fIN\fP, \fB--framerate=\fP\fIN\fP
+Set number of frames per second to \fIN\fP. When using this option,
+the frame rate specified in the FIASCO file is overridden.
+
+.TP
+\fB--verbose=\fP\fIN\fP
+Set verbose of \fBfiascotopnm\fP to \fIN\fP.
+
+.TP
+\fB-v\fP, \fB--version\fP
+Print \fBfiascotopnm\fP version number, then exit.
+
+.TP
+\fB-f\fP \fIname\fP, \fB--config=\fP\fIname\fP
+Load parameter file \fIname\fP to initialize the options of
+\fBfiascotopnm\fP.  See file \fBsystem.fiascorc\fP for an example of
+the syntax. Options of \fBfiascotopnm \fP are set by any of the
+following methods (in the specified order):
+
+
+.IP \(bu
+Global ressource file \fB/etc/system.fiascorc\fP
+
+.IP \(bu
+$HOME\fB/.fiascorc\fP
+
+.IP \(bu
+command line
+
+.IP \(bu
+--config=\fIname\fP
+
+
+.TP
+\fB-h\fP, \fB--help\fP
+Print help, then exit.
+
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+fiascotopnm foo.wfa >foo.ppm
+
+.fi
+.PP
+Decompress the FIASCO file "foo.wfa" and store it as
+"foo.ppm".
+
+.nf
+fiascotopnm -o foo1.wfa foo2.wfa
+
+.fi
+.PP
+Decompress the FIASCO files "foo1.wfa" and
+"foo2.wfa" and write the frames to the image files
+"foo1.wfa.ppm" and "foo2.wfa.ppm".
+
+.nf
+fiascotopnm -oimage foo1.wfa
+
+.fi
+.PP
+Decompress the FIASCO file "foo1.wfa" and write all 15
+frames to the image files "image.00.ppm", ... ,
+"image.14.ppm".
+
+.nf
+fiascotopnm --fast --magnify=-1 --double video.wfa >stream.ppm
+
+.fi
+.PP
+Decompress the FIASCO file "video.wfa".  The
+decompression speed is as fast as possible: the image is decompressed
+(in 4:2:0 format) at a quarter of its original size; then the image is
+enlarged again by pixel doubling.
+
+.UN files
+.SH FILES
+
+
+.TP
+\fB/etc/system.fiascorc\fP
+The systemwide initialization file.
+
+.TP
+$HOME\fB/.fiascorc\fP
+The personal initialization file.
+
+
+
+.UN environment
+.SH ENVIRONMENT
+
+
+.TP
+\fBFIASCO_IMAGES\fP
+Save path for image files. Default is "./".
+
+.TP
+\fBFIASCO_DATA\fP
+Search path for FIASCO files. Default is "./".
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtofiasco" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.PP
+Ullrich Hafner, Juergen Albert, Stefan Frank, and Michael Unger.
+\fBWeighted Finite Automata for Video Compression\fP, IEEE Journal on
+Selected Areas In Communications, January 1998
+Ullrich Hafner. \fBLow Bit-Rate Image and Video Coding with Weighted
+Finite Automata\fP, Ph.D. thesis, Mensch & Buch Verlag, ISBN
+3-89820-002-7, October 1999.
+
+.UN author
+.SH AUTHOR
+
+Ullrich Hafner <\fIhafner@bigfoot.de\fP>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/fiascotopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/file.1 b/upstream/mageia-cauldron/man1/file.1
new file mode 100644
index 00000000..be19360e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/file.1
@@ -0,0 +1,740 @@
+.\" $File: file.man,v 1.147 2022/10/31 13:22:26 christos Exp $
+.Dd October 26, 2022
+.Dt FILE 1
+.Os
+.Sh NAME
+.Nm file
+.Nd determine file type
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Op Fl bcdEhiklLNnprsSvzZ0
+.Op Fl Fl apple
+.Op Fl Fl exclude-quiet
+.Op Fl Fl extension
+.Op Fl Fl mime-encoding
+.Op Fl Fl mime-type
+.Op Fl e Ar testname
+.Op Fl F Ar separator
+.Op Fl f Ar namefile
+.Op Fl m Ar magicfiles
+.Op Fl P Ar name=value
+.Ar
+.Ek
+.Nm
+.Fl C
+.Op Fl m Ar magicfiles
+.Nm
+.Op Fl Fl help
+.Sh DESCRIPTION
+This manual page documents version 5.44 of the
+.Nm
+command.
+.Pp
+.Nm
+tests each argument in an attempt to classify it.
+There are three sets of tests, performed in this order:
+filesystem tests, magic tests, and language tests.
+The
+.Em first
+test that succeeds causes the file type to be printed.
+.Pp
+The type printed will usually contain one of the words
+.Em text
+(the file contains only
+printing characters and a few common control
+characters and is probably safe to read on an
+.Dv ASCII
+terminal),
+.Em executable
+(the file contains the result of compiling a program
+in a form understandable to some
+.Tn UNIX
+kernel or another),
+or
+.Em data
+meaning anything else (data is usually
+.Dq binary
+or non-printable).
+Exceptions are well-known file formats (core files, tar archives)
+that are known to contain binary data.
+When modifying magic files or the program itself, make sure to
+.Em preserve these keywords .
+Users depend on knowing that all the readable files in a directory
+have the word
+.Dq text
+printed.
+Don't do as Berkeley did and change
+.Dq shell commands text
+to
+.Dq shell script .
+.Pp
+The filesystem tests are based on examining the return from a
+.Xr stat 2
+system call.
+The program checks to see if the file is empty,
+or if it's some sort of special file.
+Any known file types appropriate to the system you are running on
+(sockets, symbolic links, or named pipes (FIFOs) on those systems that
+implement them)
+are intuited if they are defined in the system header file
+.In sys/stat.h .
+.Pp
+The magic tests are used to check for files with data in
+particular fixed formats.
+The canonical example of this is a binary executable (compiled program)
+.Dv a.out
+file, whose format is defined in
+.In elf.h ,
+.In a.out.h
+and possibly
+.In exec.h
+in the standard include directory.
+These files have a
+.Dq magic number
+stored in a particular place
+near the beginning of the file that tells the
+.Tn UNIX
+operating system
+that the file is a binary executable, and which of several types thereof.
+The concept of a
+.Dq magic number
+has been applied by extension to data files.
+Any file with some invariant identifier at a small fixed
+offset into the file can usually be described in this way.
+The information identifying these files is read from the compiled
+magic file
+.Pa /usr/share/misc/magic.mgc ,
+or the files in the directory
+.Pa /usr/share/misc/magic
+if the compiled file does not exist.
+In addition, if
+.Pa $HOME/.magic.mgc
+or
+.Pa $HOME/.magic
+exists, it will be used in preference to the system magic files.
+.Pp
+If a file does not match any of the entries in the magic file,
+it is examined to see if it seems to be a text file.
+ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets
+(such as those used on Macintosh and IBM PC systems),
+UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC
+character sets can be distinguished by the different
+ranges and sequences of bytes that constitute printable text
+in each set.
+If a file passes any of these tests, its character set is reported.
+ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified
+as
+.Dq text
+because they will be mostly readable on nearly any terminal;
+UTF-16 and EBCDIC are only
+.Dq character data
+because, while
+they contain text, it is text that will require translation
+before it can be read.
+In addition,
+.Nm
+will attempt to determine other characteristics of text-type files.
+If the lines of a file are terminated by CR, CRLF, or NEL, instead
+of the Unix-standard LF, this will be reported.
+Files that contain embedded escape sequences or overstriking
+will also be identified.
+.Pp
+Once
+.Nm
+has determined the character set used in a text-type file,
+it will
+attempt to determine in what language the file is written.
+The language tests look for particular strings (cf.
+.In names.h )
+that can appear anywhere in the first few blocks of a file.
+For example, the keyword
+.Em .br
+indicates that the file is most likely a
+.Xr troff 1
+input file, just as the keyword
+.Em struct
+indicates a C program.
+These tests are less reliable than the previous
+two groups, so they are performed last.
+The language test routines also test for some miscellany
+(such as
+.Xr tar 1
+archives, JSON files).
+.Pp
+Any file that cannot be identified as having been written
+in any of the character sets listed above is simply said to be
+.Dq data .
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl Fl apple
+Causes the
+.Nm
+command to output the file type and creator code as
+used by older MacOS versions.
+The code consists of eight letters,
+the first describing the file type, the latter the creator.
+This option works properly only for file formats that have the
+apple-style output defined.
+.It Fl b , Fl Fl brief
+Do not prepend filenames to output lines (brief mode).
+.It Fl C , Fl Fl compile
+Write a
+.Pa magic.mgc
+output file that contains a pre-parsed version of the magic file or directory.
+.It Fl c , Fl Fl checking-printout
+Cause a checking printout of the parsed form of the magic file.
+This is usually used in conjunction with the
+.Fl m
+option to debug a new magic file before installing it.
+.It Fl d
+Prints internal debugging information to stderr.
+.It Fl E
+On filesystem errors (file not found etc), instead of handling the error
+as regular output as POSIX mandates and keep going, issue an error message
+and exit.
+.It Fl e , Fl Fl exclude Ar testname
+Exclude the test named in
+.Ar testname
+from the list of tests made to determine the file type.
+Valid test names are:
+.Bl -tag -width compress
+.It apptype
+.Dv EMX
+application type (only on EMX).
+.It ascii
+Various types of text files (this test will try to guess the text
+encoding, irrespective of the setting of the
+.Sq encoding
+option).
+.It encoding
+Different text encodings for soft magic tests.
+.It tokens
+Ignored for backwards compatibility.
+.It cdf
+Prints details of Compound Document Files.
+.It compress
+Checks for, and looks inside, compressed files.
+.It csv
+Checks Comma Separated Value files.
+.It elf
+Prints ELF file details, provided soft magic tests are enabled and the
+elf magic is found.
+.It json
+Examines JSON (RFC-7159) files by parsing them for compliance.
+.It soft
+Consults magic files.
+.It tar
+Examines tar files by verifying the checksum of the 512 byte tar header.
+Excluding this test can provide more detailed content description by using
+the soft magic method.
+.It text
+A synonym for
+.Sq ascii .
+.El
+.It Fl Fl exclude-quiet
+Like
+.Fl Fl exclude
+but ignore tests that
+.Nm
+does not know about.
+This is intended for compatibility with older versions of
+.Nm .
+.It Fl Fl extension
+Print a slash-separated list of valid extensions for the file type found.
+.It Fl F , Fl Fl separator Ar separator
+Use the specified string as the separator between the filename and the
+file result returned.
+Defaults to
+.Sq \&: .
+.It Fl f , Fl Fl files-from Ar namefile
+Read the names of the files to be examined from
+.Ar namefile
+(one per line)
+before the argument list.
+Either
+.Ar namefile
+or at least one filename argument must be present;
+to test the standard input, use
+.Sq -
+as a filename argument.
+Please note that
+.Ar namefile
+is unwrapped and the enclosed filenames are processed when this option is
+encountered and before any further options processing is done.
+This allows one to process multiple lists of files with different command line
+arguments on the same
+.Nm
+invocation.
+Thus if you want to set the delimiter, you need to do it before you specify
+the list of files, like:
+.Dq Fl F Ar @ Fl f Ar namefile ,
+instead of:
+.Dq Fl f Ar namefile Fl F Ar @ .
+.It Fl h , Fl Fl no-dereference
+This option causes symlinks not to be followed
+(on systems that support symbolic links).
+This is the default if the environment variable
+.Dv POSIXLY_CORRECT
+is not defined.
+.It Fl i , Fl Fl mime
+Causes the
+.Nm
+command to output mime type strings rather than the more
+traditional human readable ones.
+Thus it may say
+.Sq text/plain; charset=us-ascii
+rather than
+.Dq ASCII text .
+.It Fl Fl mime-type , Fl Fl mime-encoding
+Like
+.Fl i ,
+but print only the specified element(s).
+.It Fl k , Fl Fl keep-going
+Don't stop at the first match, keep going.
+Subsequent matches will be
+have the string
+.Sq "\[rs]012\- "
+prepended.
+(If you want a newline, see the
+.Fl r
+option.)
+The magic pattern with the highest strength (see the
+.Fl l
+option) comes first.
+.It Fl l , Fl Fl list
+Shows a list of patterns and their strength sorted descending by
+.Xr magic 4
+strength
+which is used for the matching (see also the
+.Fl k
+option).
+.It Fl L , Fl Fl dereference
+This option causes symlinks to be followed, as the like-named option in
+.Xr ls 1
+(on systems that support symbolic links).
+This is the default if the environment variable
+.Ev POSIXLY_CORRECT
+is defined.
+.It Fl m , Fl Fl magic-file Ar magicfiles
+Specify an alternate list of files and directories containing magic.
+This can be a single item, or a colon-separated list.
+If a compiled magic file is found alongside a file or directory,
+it will be used instead.
+.It Fl N , Fl Fl no-pad
+Don't pad filenames so that they align in the output.
+.It Fl n , Fl Fl no-buffer
+Force stdout to be flushed after checking each file.
+This is only useful if checking a list of files.
+It is intended to be used by programs that want filetype output from a pipe.
+.It Fl p , Fl Fl preserve-date
+On systems that support
+.Xr utime 3
+or
+.Xr utimes 2 ,
+attempt to preserve the access time of files analyzed, to pretend that
+.Nm
+never read them.
+.It Fl P , Fl Fl parameter Ar name=value
+Set various parameter limits.
+.Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
+.It Sy "Name" Ta Sy "Default" Ta Sy "Explanation"
+.It Li bytes Ta 1048576 Ta max number of bytes to read from file
+.It Li elf_notes Ta 256 Ta max ELF notes processed
+.It Li elf_phnum Ta 2048 Ta max ELF program sections processed
+.It Li elf_shnum Ta 32768 Ta max ELF sections processed
+.It Li encoding Ta 65536 Ta max number of bytes to scan for encoding evaluation
+.It Li indir Ta 50 Ta recursion limit for indirect magic
+.It Li name Ta 50 Ta use count limit for name/use magic
+.It Li regex Ta 8192 Ta length limit for regex searches
+.El
+.It Fl r , Fl Fl raw
+Don't translate unprintable characters to \eooo.
+Normally
+.Nm
+translates unprintable characters to their octal representation.
+.It Fl s , Fl Fl special-files
+Normally,
+.Nm
+only attempts to read and determine the type of argument files which
+.Xr stat 2
+reports are ordinary files.
+This prevents problems, because reading special files may have peculiar
+consequences.
+Specifying the
+.Fl s
+option causes
+.Nm
+to also read argument files which are block or character special files.
+This is useful for determining the filesystem types of the data in raw
+disk partitions, which are block special files.
+This option also causes
+.Nm
+to disregard the file size as reported by
+.Xr stat 2
+since on some systems it reports a zero size for raw disk partitions.
+.It Fl S , Fl Fl no-sandbox
+On systems where libseccomp
+.Pa ( https://github.com/seccomp/libseccomp )
+is available, the
+.Fl S
+option disables sandboxing which is enabled by default.
+This option is needed for
+.Nm
+to execute external decompressing programs,
+i.e. when the
+.Fl z
+option is specified and the built-in decompressors are not available.
+On systems where sandboxing is not available, this option has no effect.
+.It Fl v , Fl Fl version
+Print the version of the program and exit.
+.It Fl z , Fl Fl uncompress
+Try to look inside compressed files.
+.It Fl Z , Fl Fl uncompress-noreport
+Try to look inside compressed files, but report information about the contents
+only not the compression.
+.It Fl 0 , Fl Fl print0
+Output a null character
+.Sq \e0
+after the end of the filename.
+Nice to
+.Xr cut 1
+the output.
+This does not affect the separator, which is still printed.
+.Pp
+If this option is repeated more than once, then
+.Nm
+prints just the filename followed by a NUL followed by the description
+(or ERROR: text) followed by a second NUL for each entry.
+.It Fl -help
+Print a help message and exit.
+.El
+.Sh ENVIRONMENT
+The environment variable
+.Ev MAGIC
+can be used to set the default magic file name.
+If that variable is set, then
+.Nm
+will not attempt to open
+.Pa $HOME/.magic .
+.Nm
+adds
+.Dq Pa .mgc
+to the value of this variable as appropriate.
+The environment variable
+.Ev POSIXLY_CORRECT
+controls (on systems that support symbolic links), whether
+.Nm
+will attempt to follow symlinks or not.
+If set, then
+.Nm
+follows symlink, otherwise it does not.
+This is also controlled by the
+.Fl L
+and
+.Fl h
+options.
+.Sh FILES
+.Bl -tag -width /usr/share/misc/magic.mgc -compact
+.It Pa /usr/share/misc/magic.mgc
+Default compiled list of magic.
+.It Pa /usr/share/misc/magic
+Directory containing default magic files.
+.El
+.Sh EXIT STATUS
+.Nm
+will exit with
+.Dv 0
+if the operation was successful or
+.Dv >0
+if an error was encountered.
+The following errors cause diagnostic messages, but don't affect the program
+exit code (as POSIX requires), unless
+.Fl E
+is specified:
+.Bl -bullet -compact -offset indent
+.It
+A file cannot be found
+.It
+There is no permission to read a file
+.It
+The file type cannot be determined
+.El
+.Sh EXAMPLES
+.Bd -literal -offset indent
+$ file file.c file /dev/{wd0a,hda}
+file.c:	  C program text
+file:	  ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV),
+	  dynamically linked (uses shared libs), stripped
+/dev/wd0a: block special (0/0)
+/dev/hda: block special (3/0)
+
+$ file -s /dev/wd0{b,d}
+/dev/wd0b: data
+/dev/wd0d: x86 boot sector
+
+$ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10}
+/dev/hda:   x86 boot sector
+/dev/hda1:  Linux/i386 ext2 filesystem
+/dev/hda2:  x86 boot sector
+/dev/hda3:  x86 boot sector, extended partition table
+/dev/hda4:  Linux/i386 ext2 filesystem
+/dev/hda5:  Linux/i386 swap file
+/dev/hda6:  Linux/i386 swap file
+/dev/hda7:  Linux/i386 swap file
+/dev/hda8:  Linux/i386 swap file
+/dev/hda9:  empty
+/dev/hda10: empty
+
+$ file -i file.c file /dev/{wd0a,hda}
+file.c:	     text/x-c
+file:	     application/x-executable
+/dev/hda:    application/x-not-regular-file
+/dev/wd0a:   application/x-not-regular-file
+
+.Ed
+.Sh SEE ALSO
+.Xr hexdump 1 ,
+.Xr od 1 ,
+.Xr strings 1 ,
+.Xr magic 4
+.Sh STANDARDS CONFORMANCE
+This program is believed to exceed the System V Interface Definition
+of FILE(CMD), as near as one can determine from the vague language
+contained therein.
+Its behavior is mostly compatible with the System V program of the same name.
+This version knows more magic, however, so it will produce
+different (albeit more accurate) output in many cases.
+.\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html
+.Pp
+The one significant difference
+between this version and System V
+is that this version treats any white space
+as a delimiter, so that spaces in pattern strings must be escaped.
+For example,
+.Bd -literal -offset indent
+\*[Gt]10	string	language impress\	(imPRESS data)
+.Ed
+.Pp
+in an existing magic file would have to be changed to
+.Bd -literal -offset indent
+\*[Gt]10	string	language\e impress	(imPRESS data)
+.Ed
+.Pp
+In addition, in this version, if a pattern string contains a backslash,
+it must be escaped.
+For example
+.Bd -literal -offset indent
+0	string		\ebegindata	Andrew Toolkit document
+.Ed
+.Pp
+in an existing magic file would have to be changed to
+.Bd -literal -offset indent
+0	string		\e\ebegindata	Andrew Toolkit document
+.Ed
+.Pp
+SunOS releases 3.2 and later from Sun Microsystems include a
+.Nm
+command derived from the System V one, but with some extensions.
+This version differs from Sun's only in minor ways.
+It includes the extension of the
+.Sq \*[Am]
+operator, used as,
+for example,
+.Bd -literal -offset indent
+\*[Gt]16	long\*[Am]0x7fffffff	\*[Gt]0		not stripped
+.Ed
+.Sh SECURITY
+On systems where libseccomp
+.Pa ( https://github.com/seccomp/libseccomp )
+is available,
+.Nm
+is enforces limiting system calls to only the ones necessary for the
+operation of the program.
+This enforcement does not provide any security benefit when
+.Nm
+is asked to decompress input files running external programs with
+the
+.Fl z
+option.
+To enable execution of external decompressors, one needs to disable
+sandboxing using the
+.Fl S
+option.
+.Sh MAGIC DIRECTORY
+The magic file entries have been collected from various sources,
+mainly USENET, and contributed by various authors.
+Christos Zoulas (address below) will collect additional
+or corrected magic file entries.
+A consolidation of magic file entries
+will be distributed periodically.
+.Pp
+The order of entries in the magic file is significant.
+Depending on what system you are using, the order that
+they are put together may be incorrect.
+If your old
+.Nm
+command uses a magic file,
+keep the old magic file around for comparison purposes
+(rename it to
+.Pa /usr/share/misc/magic.orig ) .
+.Sh HISTORY
+There has been a
+.Nm
+command in every
+.Dv UNIX since at least Research Version 4
+(man page dated November, 1973).
+The System V version introduced one significant major change:
+the external list of magic types.
+This slowed the program down slightly but made it a lot more flexible.
+.Pp
+This program, based on the System V version,
+was written by Ian Darwin
+.Aq ian@darwinsys.com
+without looking at anybody else's source code.
+.Pp
+John Gilmore revised the code extensively, making it better than
+the first version.
+Geoff Collyer found several inadequacies
+and provided some magic file entries.
+Contributions of the
+.Sq \*[Am]
+operator by Rob McMahon,
+.Aq cudcv@warwick.ac.uk ,
+1989.
+.Pp
+Guy Harris,
+.Aq guy@netapp.com ,
+made many changes from 1993 to the present.
+.Pp
+Primary development and maintenance from 1990 to the present by
+Christos Zoulas
+.Aq christos@astron.com .
+.Pp
+Altered by Chris Lowth
+.Aq chris@lowth.com ,
+2000: handle the
+.Fl i
+option to output mime type strings, using an alternative
+magic file and internal logic.
+.Pp
+Altered by Eric Fischer
+.Aq enf@pobox.com ,
+July, 2000,
+to identify character codes and attempt to identify the languages
+of non-ASCII files.
+.Pp
+Altered by Reuben Thomas
+.Aq rrt@sc3d.org ,
+2007-2011, to improve MIME support, merge MIME and non-MIME magic,
+support directories as well as files of magic, apply many bug fixes,
+update and fix a lot of magic, improve the build system, improve the
+documentation, and rewrite the Python bindings in pure Python.
+.Pp
+The list of contributors to the
+.Sq magic
+directory (magic files)
+is too long to include here.
+You know who you are; thank you.
+Many contributors are listed in the source files.
+.Sh LEGAL NOTICE
+Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999.
+Covered by the standard Berkeley Software Distribution copyright; see the file
+COPYING in the source distribution.
+.Pp
+The files
+.Pa tar.h
+and
+.Pa is_tar.c
+were written by John Gilmore from his public-domain
+.Xr tar 1
+program, and are not covered by the above license.
+.Sh BUGS
+Please report bugs and send patches to the bug tracker at
+.Pa https://bugs.astron.com/
+or the mailing list at
+.Aq file@astron.com
+(visit
+.Pa https://mailman.astron.com/mailman/listinfo/file
+first to subscribe).
+.Sh TODO
+Fix output so that tests for MIME and APPLE flags are not needed all
+over the place, and actual output is only done in one place.
+This needs a design.
+Suggestion: push possible outputs on to a list, then pick the
+last-pushed (most specific, one hopes) value at the end, or
+use a default if the list is empty.
+This should not slow down evaluation.
+.Pp
+The handling of
+.Dv MAGIC_CONTINUE
+and printing \e012- between entries is clumsy and complicated; refactor
+and centralize.
+.Pp
+Some of the encoding logic is hard-coded in encoding.c and can be moved
+to the magic files if we had a !:charset annotation.
+.Pp
+Continue to squash all magic bugs.
+See Debian BTS for a good source.
+.Pp
+Store arbitrarily long strings, for example for %s patterns, so that
+they can be printed out.
+Fixes Debian bug #271672.
+This can be done by allocating strings in a string pool, storing the
+string pool at the end of the magic file and converting all the string
+pointers to relative offsets from the string pool.
+.Pp
+Add syntax for relative offsets after current level (Debian bug #466037).
+.Pp
+Make file -ki work, i.e. give multiple MIME types.
+.Pp
+Add a zip library so we can peek inside Office2007 documents to
+print more details about their contents.
+.Pp
+Add an option to print URLs for the sources of the file descriptions.
+.Pp
+Combine script searches and add a way to map executable names to MIME
+types (e.g. have a magic value for !:mime which causes the resulting
+string to be looked up in a table).
+This would avoid adding the same magic repeatedly for each new
+hash-bang interpreter.
+.Pp
+When a file descriptor is available, we can skip and adjust the buffer
+instead of the hacky buffer management we do now.
+.Pp
+Fix
+.Dq name
+and
+.Dq use
+to check for consistency at compile time (duplicate
+.Dq name ,
+.Dq use
+pointing to undefined
+.Dq name
+).
+Make
+.Dq name
+/
+.Dq use
+more efficient by keeping a sorted list of names.
+Special-case ^ to flip endianness in the parser so that it does not
+have to be escaped, and document it.
+.Pp
+If the offsets specified internally in the file exceed the buffer size
+(
+.Dv HOWMANY
+variable in file.h), then we don't seek to that offset, but we give up.
+It would be better if buffer managements was done when the file descriptor
+is available so we can seek around the file.
+One must be careful though because this has performance and thus security
+considerations, because one can slow down things by repeatedly seeking.
+.Pp
+There is support now for keeping separate buffers and having offsets from
+the end of the file, but the internal buffer management still needs an
+overhaul.
+.Sh AVAILABILITY
+You can obtain the original author's latest version by anonymous FTP
+on
+.Pa ftp.astron.com
+in the directory
+.Pa /pub/file/file-X.YZ.tar.gz .
diff --git a/upstream/mageia-cauldron/man1/find.1 b/upstream/mageia-cauldron/man1/find.1
new file mode 100644
index 00000000..478f7162
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/find.1
@@ -0,0 +1,2777 @@
+'\" t
+.TH FIND 1 \" -*- nroff -*-
+.SH NAME
+find \- search for files in a directory hierarchy
+.SH SYNOPSIS
+.B find
+[\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [starting-point...\&] [expression]
+.
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR find .
+GNU
+.B find
+searches the directory tree rooted at each given starting-point by
+evaluating the given expression from left to right, according to the
+rules of precedence (see section OPERATORS), until the outcome is
+known (the left hand side is false for \fIand\fR operations, true for
+.IR or ),
+at which point
+.B find
+moves on to the next file name.  If no starting-point is specified,
+`.\&' is assumed.
+.PP
+If you are using
+.B find
+in an environment where security is important (for example if you are
+using it to search directories that are writable by other users), you
+should read the `Security Considerations' chapter of the findutils
+documentation, which is called \fBFinding Files\fP and comes with
+findutils.
+That document also includes a lot more detail
+and discussion than this manual page, so you may find it a more useful
+source of information.
+.
+.SH OPTIONS
+The
+.BR \-H ,
+.B \-L
+and
+.B \-P
+options control the treatment of symbolic
+links.  Command-line arguments following these are taken to be names
+of files or directories to be examined, up to the first argument that
+begins with `\-', or the argument `(' or `!'.  That argument and any
+following arguments are taken to be the expression describing what is
+to be searched for.  If no paths are given, the current directory is
+used.  If no expression is given, the expression
+.B \-print
+is used
+(but you should probably consider using
+.B \-print0
+instead, anyway).
+.PP
+This manual page talks about `options' within the expression list.
+These options control the behaviour of
+.B find
+but are specified immediately after the last path name.  The five
+`real' options
+.BR \-H ,
+.BR \-L ,
+.BR \-P ,
+.B  \-D
+and
+.B  \-O
+must appear before
+the first path name, if at all.  A double dash
+.B \-\-
+could theoretically be used to signal that any remaining arguments
+are not options, but this does not really work due to the way
+.B find
+determines the end of the following path arguments: it does that by reading
+until an expression argument comes (which also starts with a `-').
+Now, if a path argument would start with a `-', then
+.B find
+would treat it as expression argument instead.
+Thus, to ensure that all start points are taken as such, and especially to
+prevent that wildcard patterns expanded by the calling shell are not mistakenly
+treated as expression arguments, it is generally safer to prefix wildcards or
+dubious path names with either `./' or to use absolute path names starting
+with '/'.
+Alternatively, it is generally safe though non-portable to use the GNU option
+.B \-files0\-from
+to pass arbitrary starting points to
+.BR find .
+
+.IP \-P
+Never follow symbolic links.  This is the default behaviour.  When
+.B find
+examines or prints information about files, and the file is a symbolic
+link, the information used shall be taken from the properties of the
+symbolic link itself.
+
+.IP \-L
+Follow symbolic links.  When
+.B find
+examines or prints information about files, the information used shall
+be taken from the properties of the file to which the link points, not
+from the link itself (unless it is a broken symbolic link or
+.B find
+is unable to examine the file to which the link points).  Use of this
+option implies
+.BR \-noleaf .
+If you later use the
+.B \-P
+option,
+.B \-noleaf
+will still be in effect.  If
+.B \-L
+is in effect and
+.B find
+discovers a symbolic link to a subdirectory during its search,
+the subdirectory pointed to by the symbolic link will be searched.
+.IP
+When the
+.B \-L
+option is in effect, the
+.B \-type
+predicate will always
+match against the type of the file that a symbolic link points to
+rather than the link itself (unless the symbolic link is broken).
+Actions that can cause symbolic links to become broken while
+.B find
+is executing (for example
+.BR \-delete )
+can give rise to confusing behaviour.
+Using
+.B \-L
+causes the
+.B \-lname
+and
+.B \-ilname
+predicates always to return
+false.
+
+.IP \-H
+Do not follow symbolic links, except while processing the command
+line arguments.  When
+.B find
+examines or prints information about files, the information used
+shall be taken from the properties of the symbolic link itself.
+The only exception to this behaviour is when a file specified on the
+command line is a symbolic link,
+and the link can be resolved.
+For that situation, the information used is taken from whatever the
+link points to
+(that is, the link is followed).
+The information about the link itself is used as a fallback if the
+file pointed to by the symbolic link cannot be examined.
+If
+.B \-H
+is in effect and one of the
+paths specified on the command line is a symbolic link to a directory,
+the contents of that directory will be examined (though of course
+.B \-maxdepth\ 0
+would prevent this).
+.P
+If more than one of
+.BR \-H ,
+.B \-L
+and
+.B \-P
+is specified, each overrides the
+others; the last one appearing on the command line takes effect.
+Since it is the default, the
+.B \-P
+option should be considered to be in
+effect unless either
+.B \-H
+or
+.B \-L
+is specified.
+
+GNU
+.B find
+frequently stats files during the processing of the command line
+itself, before any searching has begun.  These options also affect how
+those arguments are processed.  Specifically, there are a number of
+tests that compare files listed on the command line against a file we
+are currently considering.  In each case, the file specified on the
+command line will have been examined and some of its properties will
+have been saved.  If the named file is in fact a symbolic link, and
+the
+.B \-P
+option is in effect (or if neither
+.B \-H
+nor
+.B \-L
+were specified), the information used for the comparison will be taken from
+the properties of the symbolic link.  Otherwise, it will be taken from
+the properties of the file the link points to.  If
+.B find
+cannot follow the link (for example because it has insufficient
+privileges or the link points to a nonexistent file) the properties of
+the link itself will be used.
+.P
+When the
+.B \-H
+or
+.B \-L
+options are in effect, any symbolic links listed as the argument of
+.B \-newer
+will be dereferenced, and the timestamp
+will be taken from the file to which the symbolic link points.  The
+same consideration applies to
+.BR \-newerXY ,
+.B \-anewer
+and
+.BR \-cnewer .
+
+The
+.B \-follow
+option has a similar effect to
+.BR \-L ,
+though it takes
+effect at the point where it appears (that is, if
+.B \-L
+is not used but
+.B \-follow
+is, any symbolic links appearing after
+.B \-follow
+on the
+command line will be dereferenced, and those before it will not).
+
+.IP "\-D debugopts"
+Print diagnostic information; this can be helpful to diagnose problems
+with why
+.B find
+is not doing what you want.  The list of debug options should be comma
+separated.  Compatibility of the debug options is not guaranteed
+between releases of findutils.  For a complete list of valid debug
+options, see the output of
+.BR "find \-D\ help" .
+Valid debug options include
+.RS
+.IP exec
+Show diagnostic information relating to \-exec, \-execdir, \-ok and \-okdir
+.IP opt
+Prints diagnostic information relating to the optimisation of the
+expression tree; see the \-O option.
+.IP rates
+Prints a summary indicating how often each predicate succeeded or
+failed.
+.IP search
+Navigate the directory tree verbosely.
+.IP stat
+Print messages as files are examined with the
+.B stat
+and
+.B lstat
+system calls.  The
+.B find
+program tries to minimise such calls.
+.IP tree
+Show the expression tree in its original and optimised form.
+.IP all
+Enable all of the other debug options (but
+.BR help ).
+.IP help
+Explain the debugging options.
+.RE
+.IP \-Olevel
+Enables query optimisation.
+The
+.B find
+program reorders tests to speed up execution while preserving the
+overall effect; that is, predicates with side effects are not
+reordered relative to each other.  The optimisations performed at each
+optimisation level are as follows.
+.RS
+.IP 0
+Equivalent to optimisation level 1.
+.IP 1
+This is the default optimisation level and corresponds to the
+traditional behaviour.  Expressions are reordered so that tests based
+only on the names of files (for example
+.B \-name
+and
+.BR \-regex )
+are performed first.
+.IP 2
+Any
+.B \-type
+or
+.B \-xtype
+tests are performed after any tests based only on the names of files,
+but before any tests that require information from the inode.  On many
+modern versions of Unix, file types are returned by
+.B readdir()
+and so these predicates are faster to evaluate than predicates which
+need to stat the file first.
+If you use the
+.B "\-fstype\ \fIFOO\fR"
+predicate and specify a filesystem type
+.I FOO
+which is not known (that is, present in `/etc/mtab') at the time
+.B find
+starts, that predicate is equivalent to
+.BR \-false .
+.IP 3
+At this optimisation level, the full cost-based query optimiser is
+enabled.  The order of tests is modified so that cheap (i.e.\& fast)
+tests are performed first and more expensive ones are performed later,
+if necessary.  Within each cost band, predicates are evaluated earlier
+or later according to whether they are likely to succeed or not.  For
+.BR \-o ,
+predicates which are likely to succeed are evaluated earlier, and for
+.BR \-a ,
+predicates which are likely to fail are evaluated earlier.
+.RE
+.IP
+The cost-based optimiser has a fixed idea of how likely any given test
+is to succeed.  In some cases the probability takes account of the
+specific nature of the test (for example,
+.B \-type\ f
+is assumed to be more likely to succeed than
+.BR "\-type\ c" ).
+The cost-based optimiser is currently being evaluated.
+If it does not actually improve the performance of
+.BR find ,
+it will be removed again.  Conversely, optimisations that prove to be
+reliable, robust and effective may be enabled at lower optimisation
+levels over time.  However, the default behaviour (i.e.\& optimisation
+level 1) will not be changed in the 4.3.x release series.  The
+findutils test suite runs all the tests on
+.B find
+at each optimisation level and ensures that the result is the same.
+.
+.SH EXPRESSION
+The part of the command line after the list of starting points is the
+.IR expression .
+This is a kind of query specification describing how we match files
+and what we do with the files that were matched.
+An expression is composed of a sequence of things:
+
+.IP Tests
+Tests return a true or false value, usually on the basis of some
+property of a file we are considering.  The
+.B \-empty
+test for example is true only when the current file is empty.
+
+.IP Actions
+Actions have side effects (such as printing something on the standard
+output) and return either true or false, usually based on whether or
+not they are successful.  The
+.B \-print
+action for example prints the name of the current file on the standard
+output.
+
+.IP "Global options"
+Global options affect the operation of tests and actions specified on
+any part of the command line.  Global options always return true.  The
+.B \-depth
+option for example makes
+.B find
+traverse the file system in a depth-first order.
+
+.IP "Positional options"
+Positional options affect only tests or actions which follow them.
+Positional options always return true.  The
+.B \-regextype
+option for example is positional, specifying the regular expression
+dialect for regular expressions occurring later on the command line.
+
+.IP Operators
+Operators join together the other items within the expression.  They
+include for example
+.B \-o
+(meaning logical OR) and
+.B \-a
+(meaning logical AND).  Where an operator is missing,
+.B \-a
+is assumed.
+
+.P
+The
+.B \-print
+action is performed on all files for which the whole expression is
+true, unless it contains an action other than
+.B \-prune
+or
+.BR \-quit .
+Actions which inhibit the default
+.B \-print
+are
+.BR \-delete ,
+.BR \-exec ,
+.BR \-execdir ,
+.BR \-ok ,
+.BR \-okdir ,
+.BR \-fls ,
+.BR \-fprint ,
+.BR \-fprintf ,
+.BR \-ls ,
+.B \-print
+and
+.BR \-printf .
+
+
+The
+.B \-delete
+action also acts like an option (since it implies
+.BR \-depth ).
+
+.SS POSITIONAL OPTIONS
+Positional options always return true.  They affect only tests occurring
+later on the command line.
+
+.IP \-daystart
+Measure times (for
+.BR \-amin ,
+.BR \-atime ,
+.BR \-cmin ,
+.BR \-ctime ,
+.BR \-mmin ,
+and
+.BR \-mtime )
+from the beginning of today rather than from 24 hours ago.  This
+option only affects tests which appear later on the command line.
+
+.IP \-follow
+Deprecated; use the
+.B \-L
+option instead.  Dereference symbolic links.
+Implies
+.BR \-noleaf .
+The
+.B \-follow
+option affects only those tests which
+appear after it on the command line.  Unless the
+.B \-H
+or
+.B \-L
+option has
+been specified, the position of the
+.B \-follow
+option changes the behaviour of the
+.B \-newer
+predicate; any files listed as the argument
+of
+.B \-newer
+will be dereferenced if they are symbolic links.  The same
+consideration applies to
+.BR \-newerXY ,
+.B \-anewer
+and
+.BR \-cnewer .
+Similarly, the
+.B \-type
+predicate will always match against the type of the file
+that a symbolic link points to rather than the link itself.  Using
+.B \-follow
+causes the
+.B \-lname and
+.B \-ilname
+predicates always to return false.
+
+.IP "\-regextype \fItype\fR"
+Changes the regular expression syntax understood by
+.B \-regex
+and
+.B \-iregex
+tests which occur later on the command line.  To see which regular
+expression types are known, use
+.BR "\-regextype\ help" .
+The Texinfo documentation (see
+.B SEE
+.BR ALSO )
+explains the meaning of and
+differences between the various types of regular expression.
+
+.IP "\-warn, \-nowarn"
+Turn warning messages on or off.  These warnings apply only to the
+command line usage, not to any conditions that
+.B find
+might encounter when it searches directories.  The default behaviour
+corresponds to
+.B \-warn
+if standard input is a tty, and to
+.B \-nowarn
+otherwise.  If a warning message relating to command-line usage is
+produced, the exit status of
+.B find
+is not affected.  If the
+.B POSIXLY_CORRECT
+environment variable is set, and
+.B \-warn
+is also used, it is not specified which, if any, warnings will be active.
+
+.SS GLOBAL OPTIONS
+Global options always return true.
+Global options take effect even for tests which occur earlier on the
+command line.  To prevent confusion, global options should specified
+on the command-line after the list of start points, just before the
+first test, positional option or action.
+If you specify a global option in some other place,
+.B find
+will issue a warning message explaining that this can be confusing.
+
+The global options occur after the list of start points, and so are
+not the same kind of option as
+.BR \-L ,
+for example.
+
+.IP \-d
+A synonym for \-depth, for compatibility with FreeBSD, NetBSD, \
+MacOS X and OpenBSD.
+
+.IP \-depth
+Process each directory's contents before the directory itself.  The
+\-delete action also implies
+.BR \-depth .
+
+.IP "\-files0\-from \fIfile\fR"
+Read the starting points from \fIfile\fR instead of getting them on the
+command line.
+In contrast to the known limitations of passing starting points via arguments
+on the command line, namely the limitation of the amount of file names,
+and the inherent ambiguity of file names clashing with option names,
+using this option allows to safely pass an arbitrary number of starting points
+to \fBfind\fR.
+
+Using this option and passing starting points on the command line is mutually
+exclusive, and is therefore not allowed at the same time.
+
+The \fIfile\fR argument is mandatory.
+One can use
+.B \-files0\-from\ \-
+to read the list of starting points from the \fIstandard input\fR stream,
+and e.g. from a pipe.
+In this case, the actions
+.B \-ok
+and
+.B \-okdir
+are not allowed, because they would obviously interfere with reading from
+\fIstandard input\fR in order to get a user confirmation.
+
+The starting points in \fIfile\fR have to be separated by ASCII NUL characters.
+Two consecutive NUL characters, i.e., a starting point with a Zero-length
+file name is not allowed and will lead to an error diagnostic followed by
+a non-Zero exit code later.
+
+In the case the given \fIfile\fR is empty, \fBfind\fR does not process any
+starting point and therefore will exit immediately after parsing the program
+arguments.
+This is unlike the standard invocation where \fBfind\fR assumes the current
+directory as starting point if no path argument is passed.
+
+The processing of the starting points is otherwise as usual, e.g.
+.B find
+will recurse into subdirectories unless otherwise prevented.
+To process only the starting points, one can additionally pass
+.BR \-maxdepth\ 0 .
+
+Further notes:
+if a file is listed more than once in the input file, it is unspecified
+whether it is visited more than once.
+If the \fIfile\fR is mutated during the operation of
+.BR find ,
+the result is unspecified as well.
+Finally, the seek position within the named \fIfile\fR at the time
+.B find
+exits, be it with
+.B \-quit
+or in any other way, is also unspecified.
+By "unspecified" here is meant that it may or may not work or do any specific
+thing, and that the behavior may change from platform to platform, or from
+.B findutils
+release to release.
+
+.IP "\-help, \-\-help"
+Print a summary of the command-line usage of
+.B find
+and exit.
+
+.IP \-ignore_readdir_race
+Normally, \fBfind\fR will emit an error message when it fails to stat a file.
+If you give this option and a file is deleted between the time \fBfind\fR
+reads the name of the file from the directory and the time it tries to stat
+the file, no error message will be issued.
+This also applies to files or directories whose names are given on the
+command line.
+This option takes effect at the time the command line is read,
+which means that you cannot search one part of the filesystem with
+this option on and part of it with this option off
+(if you need to do that, you will need to issue two \fBfind\fR commands
+instead, one with the option and one without it).
+
+Furthermore,
+.B find
+with the
+.B \-ignore_readdir_race
+option will ignore errors of the
+.B \-delete
+action in the case the file has disappeared since the parent directory was read:
+it will not output an error diagnostic, and the return code of the
+.B \-delete
+action will be true.
+
+.IP "\-maxdepth \fIlevels\fR"
+Descend at most \fIlevels\fR (a non-negative integer) levels of
+directories below the starting-points.  Using
+.B \-maxdepth\ 0
+means only apply the tests and actions to the starting-points themselves.
+
+.IP "\-mindepth \fIlevels\fR"
+Do not apply any tests or actions at levels less than \fIlevels\fR (a
+non-negative integer).  Using
+.B \-mindepth\ 1
+means process all files except the starting-points.
+
+.IP \-mount
+Don't descend directories on other filesystems.  An alternate name for
+.BR \-xdev ,
+for compatibility with some other versions of
+.BR find .
+
+.IP \-noignore_readdir_race
+Turns off the effect of
+.BR \-ignore_readdir_race .
+
+.IP "\-noleaf"
+Do not optimize by assuming that directories contain 2 fewer
+subdirectories than their hard link count.  This option is needed when
+searching filesystems that do not follow the Unix directory-link
+convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
+points.  Each directory on a normal Unix filesystem has at least 2
+hard links: its name and its `.\&' entry.  Additionally, its
+subdirectories (if any) each have a `..\&' entry linked to that
+directory.  When
+.B find
+is examining a directory, after it has statted 2 fewer subdirectories
+than the directory's link count, it knows that the rest of the entries
+in the directory are non-directories (`leaf' files in the directory
+tree).  If only the files' names need to be examined, there is no need
+to stat them; this gives a significant increase in search speed.
+
+.IP "\-version, \-\-version"
+Print the \fBfind\fR version number and exit.
+
+.IP \-xautofs
+Don't descend directories on autofs filesystems.
+
+.IP \-xdev
+Don't descend directories on other filesystems.
+
+.SS TESTS
+Some tests, for example
+.B \-newerXY
+and
+.BR \-samefile ,
+allow comparison between the file currently being examined and some
+reference file specified on the command line.  When these tests are
+used, the interpretation of the reference file is determined by the
+options
+.BR \-H ,
+.B \-L
+and
+.B \-P
+and any previous
+.BR \-follow ,
+but the reference file is only examined once, at the time the command
+line is parsed.  If the reference file cannot be examined (for
+example, the
+.BR stat (2)
+system call fails for it), an error message is issued, and
+.B find
+exits with a nonzero status.
+.P
+A numeric argument \fIn\fR can be specified to tests (like
+.BR \-amin ,
+.BR \-mtime ,
+.BR \-gid ,
+.BR \-inum ,
+.BR \-links ,
+.BR \-size ,
+.BR \-uid
+and
+.BR \-used )
+as
+.IP \fI+n\fP
+for greater than
+.IR n ,
+.IP \fI\-n\fP
+for less than
+.IR n ,
+.IP \fIn\fP
+for exactly
+.IR n .
+.
+.P
+Supported tests:
+
+.IP "\-amin \fIn\fR"
+File was last accessed less than, more than or exactly \fIn\fR minutes ago.
+
+.IP "\-anewer \fIreference\fR"
+Time of the last access of the current file is more recent than that
+of the last data modification of the \fIreference\fR file.
+If \fIreference\fR is a symbolic link and the
+.B \-H
+option or the
+.B \-L
+option is in effect, then the time of the last data modification of the file
+it points to is always used.
+
+.IP "\-atime \fIn\fR"
+File was last accessed less than, more than or exactly
+.IR n *24
+hours ago.
+When find figures out how many 24-hour periods ago the file
+was last accessed, any fractional part is ignored, so to match
+.BR "\-atime\ +1" ,
+a file has to have been accessed at least
+.I two
+days ago.
+
+.IP "\-cmin \fIn\fR"
+File's status was last changed less than, more than or exactly \fIn\fR minutes
+ago.
+
+.IP "\-cnewer \fIreference\fR"
+Time of the last status change of the current file is more recent than that
+of the last data modification of the \fIreference\fR file.
+If \fIreference\fR is a symbolic link and the
+.B \-H
+option or the
+.B \-L
+option is in effect, then the time of the last data modification of the file
+it points to is always used.
+
+.IP "\-ctime \fIn\fR"
+File's status was last changed less than, more than or exactly
+.IR n *24
+hours ago.
+See the comments for
+.B \-atime
+to understand how rounding affects the interpretation of file status
+change times.
+
+.IP \-empty
+File is empty and is either a regular file or a directory.
+
+.IP \-executable
+Matches files which are executable and directories which are
+searchable (in a file name resolution sense) by the current user.
+This takes into account access control lists and other permissions
+artefacts which the
+.B \-perm
+test ignores.  This test makes use of the
+.BR access (2)
+system call, and so can be fooled by NFS servers which do UID
+mapping (or root-squashing), since many systems implement
+.BR access (2)
+in the client's kernel and so cannot make use of the UID mapping
+information held on the server.  Because this test is based only on
+the result of the
+.BR access (2)
+system call, there is no guarantee that a file for which this test
+succeeds can actually be executed.
+
+.IP \-false
+Always false.
+
+.IP "\-fstype \fItype\fR"
+File is on a filesystem of type
+.IR type .
+The valid filesystem types vary among different versions of Unix;
+an incomplete list of
+filesystem types that are accepted on some version of Unix or another
+is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K.  You can use
+.B \-printf
+with the %F directive to see the types of your filesystems.
+
+.IP "\-gid \fIn\fR"
+File's numeric group ID is less than, more than or exactly
+.IR n .
+
+.IP "\-group \fIgname\fR"
+File belongs to group \fIgname\fR (numeric group ID allowed).
+
+.IP "\-ilname \fIpattern\fR"
+Like
+.BR \-lname ,
+but the match is case insensitive.
+If the
+.B \-L
+option or the
+.B \-follow
+option is in effect, this test returns false unless the symbolic link
+is broken.
+
+
+.IP "\-iname \fIpattern\fR"
+Like
+.BR \-name ,
+but the match is case insensitive.  For example, the
+patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo',
+`fOo', etc.
+The pattern `*foo*` will also match a file called '.foobar'.
+
+.IP "\-inum \fIn\fR"
+File has inode number smaller than, greater than or exactly
+.IR n .
+It is normally easier to use the
+.B \-samefile
+test instead.
+
+.IP "\-ipath \fIpattern\fR"
+Like
+.BR \-path .
+but the match is case insensitive.
+
+.IP "\-iregex \fIpattern\fR"
+Like
+.BR \-regex ,
+but the match is case insensitive.
+
+.IP "\-iwholename \fIpattern\fR"
+See \-ipath.  This alternative is less portable than
+.BR \-ipath .
+
+.IP "\-links \fIn\fR"
+File has less than, more than or exactly \fIn\fR hard links.
+
+.IP "\-lname \fIpattern\fR"
+File is a symbolic link whose contents match shell pattern
+.IR pattern .
+The metacharacters do not treat `/' or `.\&' specially.
+If the
+.B \-L
+option or the
+.B \-follow
+option is in effect, this test returns false unless the symbolic link
+is broken.
+
+.IP "\-mmin \fIn\fR"
+File's data was last modified less than, more than or exactly \fIn\fR minutes
+ago.
+
+.IP "\-mtime \fIn\fR"
+File's data was last modified less than, more than or exactly
+.IR n *24
+hours ago.
+See the comments for
+.B \-atime
+to understand how rounding affects the interpretation of file
+modification times.
+
+.IP "\-name \fIpattern\fR"
+Base of file name (the path with the leading directories removed)
+matches shell pattern
+.IR pattern .
+Because the leading directories are removed,
+the file names considered for a match with
+.B \-name
+will never include a slash, so `\-name a/b' will never match anything
+(you probably need to use
+.B \-path
+instead).
+A warning is issued if you try to do this,
+unless the environment variable
+.B POSIXLY_CORRECT
+is set.
+The metacharacters (`*', `?',
+and `[]') match a `.\&' at the start of the base name (this is a change
+in findutils-4.2.2; see section STANDARDS CONFORMANCE below).  To ignore a
+directory and the files under it, use
+.B \-prune
+rather than checking every file in the tree;
+see an example in the description of that action.
+Braces are not recognised as being
+special, despite the fact that some shells including Bash imbue braces
+with a special meaning in shell patterns.  The filename matching is
+performed with the use of the
+.BR fnmatch (3)
+library function.
+Don't forget to enclose the pattern in quotes in order to protect it
+from expansion by the shell.
+
+.IP "\-newer \fIreference\fR"
+Time of the last data modification of the current file is more recent than that
+of the last data modification of the \fIreference\fR file.
+If \fIreference\fR is a symbolic link and the
+.B \-H
+option or the
+.B \-L
+option is in effect, then the time of the last data modification of the file
+it points to is always used.
+
+.IP "\-newerXY \fIreference\fR"
+Succeeds if timestamp \fIX\fR of the file being considered is newer
+than timestamp \fIY\fR of the file
+.IR reference .
+The letters \fIX\fR and \fIY\fR can be any of the following letters:
+
+.TS
+ll
+ll
+ll
+ll
+llw(2i).
+a	The access time of the file \fIreference\fR
+B	The birth time of the file \fIreference\fR
+c	The inode status change time of \fIreference\fR
+m	The modification time of the file \fIreference\fR
+t	\fIreference\fR is interpreted directly as a time
+.TE
+
+Some combinations are invalid; for example, it is invalid for
+.I X
+to be
+.IR t .
+Some combinations are not implemented on all systems; for example
+.I B
+is not supported on all systems.  If an invalid or unsupported
+combination of
+.I XY
+is specified, a fatal error results.  Time specifications are
+interpreted as for the argument to the
+.B \-d
+option of GNU
+.BR date .
+If you try to use the birth time of a reference file, and the birth
+time cannot be determined, a fatal error message results.  If you
+specify a test which refers to the birth time of files being examined,
+this test will fail for any files where the birth time is unknown.
+
+.IP \-nogroup
+No group corresponds to file's numeric group ID.
+
+.IP \-nouser
+No user corresponds to file's numeric user ID.
+
+.IP "\-path \fIpattern\fR"
+File name matches shell pattern
+.IR pattern .
+The metacharacters do not treat `/' or `.\&' specially;
+so, for example,
+.in +4m
+.nf
+find . \-path \(dq./sr*sc\(dq
+.fi
+.in
+will print an entry for a directory called
+.I ./src/misc
+(if one exists).  To ignore a whole directory tree, use
+.B \-prune
+rather than
+checking every file in the tree.
+Note that the pattern match test applies to the whole file name,
+starting from one of the start points named on the command line.  It
+would only make sense to use an absolute path name here if the
+relevant start point is also an absolute path.  This means that this
+command will never match anything:
+.br
+.in +4m
+.nf
+find bar \-path /foo/bar/myfile \-print
+.fi
+.in
+Find compares the
+.B \-path
+argument with the concatenation of a directory name and the base name
+of the file it's examining.  Since the concatenation will never end
+with a slash,
+.B \-path
+arguments ending in a slash will match nothing (except perhaps a start
+point specified on the command line).
+The predicate
+.B \-path
+is also supported by HP-UX
+.B find
+and is part of the POSIX 2008 standard.
+
+.IP "\-perm \fImode\fR"
+File's permission bits are exactly \fImode\fR (octal or symbolic).
+Since an exact match is required, if you want to use this form for
+symbolic modes, you may have to specify a rather complex mode string.
+For example `\-perm g=w' will only match files which have mode 0020
+(that is, ones for which group write permission is the only permission
+set).  It is more likely that you will want to use the `/' or `\-'
+forms, for example `\-perm \-g=w', which matches any file with group
+write permission.  See the
+.B EXAMPLES
+section for some illustrative examples.
+
+.IP "\-perm \-\fImode\fR"
+All of the permission bits \fImode\fR are set for the file.
+Symbolic modes are accepted in this form, and this is usually the way
+in which you would want to use them.  You must specify `u', `g' or `o' if
+you use a symbolic mode.
+See the
+.B EXAMPLES
+section for some illustrative examples.
+
+.IP "\-perm /\fImode\fR"
+Any of the permission bits \fImode\fR are set for the file.  Symbolic
+modes are accepted in this form.  You must specify `u', `g' or `o' if
+you use a symbolic mode.  See the
+.B EXAMPLES
+section for some illustrative examples.  If no permission bits in
+.I mode
+are set, this test matches any file (the idea here is to be consistent
+with the behaviour of
+.BR "\-perm\ \-000" ).
+
+.IP "\-perm +\fImode\fR"
+This is no longer supported (and has been deprecated since 2005).  Use
+.B "\-perm /\fImode\fR"
+instead.
+
+.IP \-readable
+Matches files which are readable by the current user.  This takes into
+account access control lists and other permissions artefacts which the
+.B \-perm
+test ignores.  This test makes use of the
+.BR access (2)
+system call, and so can be fooled by NFS servers which do UID
+mapping (or root-squashing), since many systems implement
+.BR access (2)
+in the client's kernel and so cannot make use of the UID mapping
+information held on the server.
+
+.IP "\-regex \fIpattern\fR"
+File name matches regular expression
+.IR pattern .
+This is a match on the whole path, not a search.
+For example, to match a file named
+.IR ./fubar3,
+you can use the regular expression `.*bar.\&' or `.*b.*3',
+but not `f.*r3'.
+The regular expressions understood by
+.B find
+are by default Emacs Regular Expressions (except that `.' matches
+newline), but this can be changed with the
+.B \-regextype
+option.
+
+.IP "\-samefile \fIname\fR"
+File refers to the same inode as
+.IR name .
+When
+.B \-L
+is in effect, this can include symbolic links.
+
+.IP "\-size \fIn\fR[cwbkMG]"
+File uses less than, more than or exactly \fIn\fP units of space, rounding up.
+The following suffixes can be used:
+.RS
+.IP `b'
+for 512-byte blocks (this is the default if no suffix is used)
+.IP `c'
+for bytes
+.IP `w'
+for two-byte words
+.IP `k'
+for kibibytes (KiB, units of 1024 bytes)
+.IP `M'
+for mebibytes (MiB, units of 1024 * 1024 = 1\|048\|576 bytes)
+.IP `G'
+for gibibytes (GiB, units of 1024 * 1024 * 1024 = 1\|073\|741\|824 bytes)
+.RE
+.IP
+The size is simply the st_size member of the struct stat populated by
+the lstat (or stat) system call, rounded up as shown above.
+In other words, it's consistent with the result you get for
+.BR "ls\ \-l" .
+Bear in
+mind that the `%k' and `%b' format specifiers of
+.B \-printf
+handle sparse files
+differently.  The `b' suffix always denotes 512-byte blocks and never
+1024-byte blocks, which is different to the behaviour of
+.BR \-ls .
+.IP
+The + and - prefixes signify greater than and less than, as usual;
+i.e., an exact size of \fIn\fR units does not match.
+Bear in mind that the size is rounded up to the next unit.
+Therefore
+.B \-size\ \-1M
+is not equivalent to
+.BR "\-size\ \-1\|048\|576c" .
+The former only matches empty files, the latter matches files from 0 to
+1,048,575 bytes.
+.IP \-true
+Always true.
+
+.IP "\-type \fIc\fR"
+File is of type
+.IR c :
+.RS
+.IP b
+block (buffered) special
+.IP c
+character (unbuffered) special
+.IP d
+directory
+.IP p
+named pipe (FIFO)
+.IP f
+regular file
+.IP l
+symbolic link; this is never true if the
+.B \-L
+option or the
+.B \-follow
+option is in effect, unless the symbolic link is broken.  If you want
+to search for symbolic links when
+.B \-L
+is in effect, use
+.BR \-xtype .
+.IP s
+socket
+.IP D
+door (Solaris)
+.RE
+.IP
+To search for more than one type at once, you can supply the combined list of
+type letters separated by a comma `,' (GNU extension).
+.IP "\-uid \fIn\fR"
+File's numeric user ID is less than, more than or exactly
+.IR n .
+
+.IP "\-used \fIn\fR"
+File was last accessed less than, more than or exactly \fIn\fR days after its
+status was last changed.
+
+.IP "\-user \fIuname\fR"
+File is owned by user \fIuname\fR (numeric user ID allowed).
+
+.IP "\-wholename \fIpattern\fR"
+See \-path.  This alternative is less portable than
+.BR \-path .
+
+.IP "\-writable"
+Matches files which are writable by the current user.  This takes into
+account access control lists and other permissions artefacts which the
+.B \-perm
+test ignores.  This test makes use of the
+.BR access (2)
+system call, and so can be fooled by NFS servers which do UID
+mapping (or root-squashing), since many systems implement
+.BR access (2)
+in the client's kernel and so cannot make use of the UID mapping
+information held on the server.
+
+.IP "\-xtype \fIc\fR"
+The same as
+.B \-type
+unless the file is a symbolic link.  For symbolic
+links: if the
+.B \-H
+or
+.B \-P
+option was specified, true if the file is a
+link to a file of type
+.IR c ;
+if the
+.B \-L
+option has been given, true
+if \fIc\fR is `l'.  In other words, for symbolic links,
+.B \-xtype
+checks the type of the file that
+.B \-type
+does not check.
+.IP "\-context \fIpattern\fR"
+(SELinux only) Security context of the file matches glob
+.IR pattern .
+
+.SS ACTIONS
+.IP "\-delete\fR"
+Delete files or directories; true if removal succeeded.
+If the removal failed, an error message is issued and
+.BR find 's
+exit status will be nonzero (when it eventually exits).
+
+.BR Warning :
+Don't forget that
+.B find
+evaluates the command line as an
+expression, so putting
+.B \-delete
+first will make
+.B find
+try to delete everything below the starting points you specified.
+
+The use of the
+.B \-delete
+action on the command line automatically turns on the
+.B \-depth
+option.
+As in turn
+.B \-depth
+makes
+.B \-prune
+ineffective, the
+.B \-delete
+action cannot usefully be combined with
+.BR \-prune .
+
+Often, the user might want to test a find command line with
+.B \-print
+prior to adding
+.B \-delete
+for the actual removal run.
+To avoid surprising results, it is usually best to remember to use
+.B \-depth
+explicitly during those earlier test runs.
+
+The
+.B \-delete
+action will fail to remove a directory unless it is empty.
+
+Together with the
+.B \-ignore_readdir_race
+option,
+.B find
+will ignore errors of the
+.B \-delete
+action in the case the file has disappeared since the parent directory was
+read: it will not output an error diagnostic, not change the exit code to
+nonzero, and the return code of the
+.B \-delete
+action will be true.
+
+
+.IP "\-exec \fIcommand\fR ;"
+Execute
+.IR command ;
+true if 0 status is returned.  All following
+arguments to
+.B find
+are taken to be arguments to the command until an argument consisting
+of `;' is encountered.  The string `{}' is replaced by the current
+file name being processed everywhere it occurs in the arguments to the
+command, not just in arguments where it is alone, as in some versions
+of
+.BR find .
+Both of these constructions might need to be escaped (with a `\e') or
+quoted to protect them from expansion by the shell.  See the
+.B EXAMPLES
+section for examples of the use of the
+.B \-exec
+option.  The specified
+command is run once for each matched file.
+The command is executed in the starting directory.
+There are unavoidable security problems surrounding use of the
+.B \-exec
+action;
+you should use the
+.B \-execdir
+option instead.
+
+.IP "\-exec \fIcommand\fR {} +"
+This variant of the
+.B \-exec
+action runs the specified command on the
+selected files, but the command line is built by appending each
+selected file name at the end; the total number of invocations of the
+command will be much less than the number of matched files.  The
+command line is built in much the same way that
+.B xargs
+builds its command lines.  Only one instance of `{}' is allowed within
+the command, and it must appear at the end, immediately before the `+';
+it needs to be escaped (with a `\e') or quoted to protect it from
+interpretation by the shell.
+The command is executed in the starting directory.  If any invocation
+with the `+' form returns a non-zero value as exit status, then
+.B find
+returns a non-zero exit status.  If
+.B find
+encounters an error, this can sometimes cause an
+immediate exit, so some pending commands may not be run
+at all.  For this reason
+.B \-exec\ \fImy-command\fP\ ...\ {}\ +\ \-quit
+may not result in
+.I my-command
+actually being run.  This variant of
+.B \-exec
+always returns true.
+
+.IP "\-execdir \fIcommand\fR ;"
+.IP "\-execdir \fIcommand\fR {} +"
+Like
+.BR \-exec ,
+but the specified command is run from the subdirectory
+containing the matched file, which is not normally the directory in
+which you started
+.BR find .
+As with \-exec, the {} should be quoted if find is being invoked from
+a shell.
+This a much more secure method for invoking commands, as it avoids
+race conditions during resolution of the paths to the matched files.
+As with the
+.B \-exec
+action, the `+' form of
+.B \-execdir
+will build a
+command line to process more than one matched file, but any given
+invocation of
+.I command
+will only list files that exist in the same subdirectory.  If you use
+this option, you must ensure that your
+.B PATH
+environment variable does not reference `.';
+otherwise, an attacker can run any commands they like by leaving an
+appropriately-named file in a directory in which you will run
+.BR \-execdir .
+The same applies to having entries in
+.B PATH
+which are empty or which are not absolute directory names.  If
+any invocation with the `+' form returns a non-zero value as exit status,
+then
+.B find
+returns a non-zero exit status.  If
+.B find
+encounters an error, this can sometimes cause an
+immediate exit, so some pending commands may not be run
+at all.
+The result of the action depends on whether the
+.B +
+or the
+.B ;
+variant is being used;
+.B \-execdir\ \fIcommand\fP\ {}\ +
+always returns true, while
+.B \-execdir\ \fIcommand\fP\ {}\ ;
+returns true only if
+.I command
+returns 0.
+
+
+.IP "\-fls \fIfile\fR"
+True; like
+.B \-ls
+but write to \fIfile\fR like
+.BR \-fprint .
+The output file is always created, even if the predicate is never
+matched.
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP "\-fprint \fIfile\fR"
+True; print the full file name into file
+.IR file .
+If \fIfile\fR
+does not exist when \fBfind\fR is run, it is created; if it does
+exist, it is truncated.  The file names
+.I /dev/stdout
+and
+.I /dev/stderr
+are handled specially; they refer to the standard
+output and standard error output, respectively.
+The output file is always created, even if the predicate is never matched.
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP "\-fprint0 \fIfile\fR"
+True; like
+.B \-print0
+but write to \fIfile\fR like
+.BR \-fprint .
+The output file is always created, even if the predicate is never matched.
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP "\-fprintf \fIfile\fR \fIformat\fR"
+True; like
+.B \-printf
+but write to \fIfile\fR like
+.BR \-fprint .
+The output file is always created, even if the predicate is never matched.
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP \-ls
+True; list current file in
+.B ls \-dils
+format on standard output.
+The block counts are of 1\ KB blocks, unless the environment variable
+.B POSIXLY_CORRECT
+is set, in which case 512-byte blocks are used.
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP "\-ok \fIcommand\fR ;"
+Like
+.B \-exec
+but ask the user first.  If the user agrees, run the command.  Otherwise
+just return false.  If the command is run, its standard input is redirected
+from
+.IR /dev/null .
+This action may not be specified together with the
+.B \-files0\-from
+option.
+
+.IP
+The response to the prompt is matched against a pair of regular
+expressions to determine if it is an affirmative or negative
+response.  This regular expression is obtained from the system if the
+.B POSIXLY_CORRECT
+environment variable is set, or otherwise from
+.BR find 's
+message translations.  If the system has no suitable
+definition,
+.BR find 's
+own definition will be used.
+In either case, the interpretation of the regular expression itself
+will be affected by the environment variables
+.B LC_CTYPE
+(character classes) and
+.B LC_COLLATE
+(character ranges and equivalence classes).
+
+
+
+.IP "\-okdir \fIcommand\fR ;"
+Like
+.B \-execdir
+but ask the user first in the same way as for
+.BR \-ok .
+If the user does not agree, just return false.
+If the command is run, its standard input is redirected from
+.IR /dev/null .
+This action may not be specified together with the
+.B \-files0\-from
+option.
+
+
+.IP \-print
+True; print the full file name on the standard output, followed by a
+newline.
+If you are piping the output of
+.B find
+into another program and there is the faintest possibility that the files
+which you are searching for might contain a newline, then you should
+seriously consider using the
+.B \-print0
+option instead of
+.BR \-print .
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+.IP \-print0
+True; print the full file name on the standard output, followed by a
+null character (instead of the newline character that
+.B \-print
+uses).
+This allows file names that contain newlines or other types of white
+space to be correctly interpreted by programs that process the
+\fBfind\fR output.  This option corresponds to the
+.B \-0
+option of
+.BR xargs .
+
+.IP "\-printf \fIformat\fR"
+True; print \fIformat\fR on the standard output, interpreting `\e'
+escapes and `%' directives.  Field widths and precisions can be
+specified as with the
+.BR printf (3)
+C function.  Please note that many of
+the fields are printed as %s rather than %d, and this may mean that
+flags don't work as you might expect.  This also means that the `\-'
+flag does work (it forces fields to be left-aligned).  Unlike
+.BR \-print ,
+.B \-printf
+does not add a newline at the end of the string.  The escapes
+and directives are:
+.RS
+.IP \ea
+Alarm bell.
+.IP \eb
+Backspace.
+.IP \ec
+Stop printing from this format immediately and flush the output.
+.IP \ef
+Form feed.
+.IP \en
+Newline.
+.IP \er
+Carriage return.
+.IP \et
+Horizontal tab.
+.IP \ev
+Vertical tab.
+.IP \e0
+ASCII NUL.
+.IP \e\e
+A literal backslash (`\e').
+.IP \eNNN
+The character whose ASCII code is NNN (octal).
+.PP
+A `\e' character followed by any other character is treated as an
+ordinary character, so they both are printed.
+.IP %%
+A literal percent sign.
+.IP %a
+File's last access time in the format returned by the C
+.BR ctime (3)
+function.
+.IP %A\fIk\fP
+File's last access time in the format specified by
+.IR k ,
+which is either `@' or a directive for the C
+.BR strftime (3)
+function.
+The following shows an incomplete list of possible values for \fIk\fR.
+Please refer to the documentation of
+.BR strftime (3)
+for the full list.
+Some of the conversion specification characters might not be available on all systems,
+due to differences in the implementation of the
+.BR strftime (3)
+library function.
+.RS
+.IP @
+seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part.
+.PP
+Time fields:
+.IP H
+hour (00..23)
+.IP I
+hour (01..12)
+.IP k
+hour ( 0..23)
+.IP l
+hour ( 1..12)
+.IP M
+minute (00..59)
+.IP p
+locale's AM or PM
+.IP r
+time, 12-hour (hh:mm:ss [AP]M)
+.IP S
+Second (00.00 \&..\& 61.00).  There is a fractional part.
+.IP T
+time, 24-hour (hh:mm:ss.xxxxxxxxxx)
+.IP +
+Date and time, separated by `+', for example
+`2004\-04\-28+22:22:05.0'.  This is a GNU extension.  The time is
+given in the current timezone (which may be affected by setting the
+.B TZ
+environment variable).  The seconds field includes a fractional part.
+.IP X
+locale's time representation (H:M:S).  The seconds field includes a
+fractional part.
+.IP Z
+time zone (e.g., EDT), or nothing if no time zone is determinable
+.PP
+Date fields:
+.IP a
+locale's abbreviated weekday name (Sun..Sat)
+.IP A
+locale's full weekday name, variable length (Sunday..Saturday)
+.IP b
+locale's abbreviated month name (Jan..Dec)
+.IP B
+locale's full month name, variable length (January..December)
+.IP c
+locale's date and time (Sat Nov 04 12:02:33 EST 1989).  The format is
+the same as for
+.BR ctime (3)
+and so to preserve compatibility with that format, there is no fractional part
+in the seconds field.
+.IP d
+day of month (01..31)
+.IP D
+date (mm/dd/yy)
+.IP F
+date (yyyy-mm-dd)
+.IP h
+same as b
+.IP j
+day of year (001..366)
+.IP m
+month (01..12)
+.IP U
+week number of year with Sunday as first day of week (00..53)
+.IP w
+day of week (0..6)
+.IP W
+week number of year with Monday as first day of week (00..53)
+.IP x
+locale's date representation (mm/dd/yy)
+.IP y
+last two digits of year (00..99)
+.IP Y
+year (1970...\&)
+.RE
+.IP %b
+The amount of disk space used for this file in 512-byte blocks.  Since disk
+space is allocated in multiples of the filesystem block size this is usually
+greater than %s/512, but it can also be smaller if the file is a sparse file.
+
+.IP %B\fIk\fP
+File's birth time, i.e., its creation time, in the format specified by
+.IR k ,
+which is the same as for %A.
+This directive produces an empty string if the underlying operating system or
+filesystem does not support birth times.
+
+.IP %c
+File's last status change time in the format returned by the C
+.BR ctime (3)
+function.
+.IP %C\fIk\fP
+File's last status change time in the format specified by
+.IR k ,
+which is the same as for %A.
+.IP %d
+File's depth in the directory tree; 0 means the file is a starting-point.
+.IP %D
+The device number on which the file exists (the st_dev field of struct
+stat), in decimal.
+.IP %f
+Print the basename; the file's name with any leading directories
+removed (only the last element).  For
+.BR / ,
+the result is `/'.
+See the
+.B EXAMPLES
+section for an example.
+
+.IP %F
+Type of the filesystem the file is on; this value can be used for
+\-fstype.
+.IP %g
+File's group name, or numeric group ID if the group has no name.
+.IP %G
+File's numeric group ID.
+.IP %h
+Dirname; the Leading directories of the file's name (all but the last
+element).  If the file name contains no slashes (since it is in the
+current directory) the %h specifier expands to `.'.  For files which
+are themselves directories and contain a slash (including
+.BR / ),
+%h expands to the empty string.  See the
+.B EXAMPLES
+section for an example.
+.IP %H
+Starting-point under which file was found.
+.IP %i
+File's inode number (in decimal).
+.IP %k
+The amount of disk space used for this file in 1\ KB blocks.
+Since disk space is allocated in multiples of the filesystem block
+size this is usually greater than %s/1024,
+but it can also be smaller if the file is a sparse file.
+.IP %l
+Object of symbolic link (empty string if file is not a symbolic link).
+.IP %m
+File's permission bits (in octal).  This option uses the `traditional'
+numbers which most Unix implementations use, but if your particular
+implementation uses an unusual ordering of octal permissions bits, you
+will see a difference between the actual value of the file's mode and
+the output of %m.
+Normally you will want to have a leading zero on this number,
+and to do this, you should use the
+.B #
+flag (as in, for example, `%#m').
+.IP %M
+File's permissions (in symbolic form, as for
+.BR ls ).
+This directive is supported in findutils 4.2.5 and later.
+.IP %n
+Number of hard links to file.
+.IP %p
+File's name.
+.IP %P
+File's name with the name of the starting-point under which
+it was found removed.
+.IP %s
+File's size in bytes.
+.IP %S
+File's sparseness.  This is calculated as (BLOCKSIZE*st_blocks /
+st_size).  The exact value you will get for an ordinary file of a
+certain length is system-dependent.  However, normally sparse files
+will have values less than 1.0, and files which use indirect blocks
+may have a value which is greater than 1.0.  In general the number of
+blocks used by a file is file system dependent.
+The value used for BLOCKSIZE is system-dependent, but is usually 512
+bytes.
+If the file size is zero, the value printed is undefined.
+On systems which lack support for st_blocks,
+a file's sparseness is assumed to be 1.0.
+.IP %t
+File's last modification time in the format returned by the C
+.BR ctime (3)
+function.
+.IP %T\fIk\fP
+File's last modification time in the format specified by
+.IR k ,
+which is the same as for %A.
+.IP %u
+File's user name, or numeric user ID if the user has no name.
+.IP %U
+File's numeric user ID.
+.IP %y
+File's type (like in
+.BR "ls \-l" ),
+U=unknown type (shouldn't happen)
+.IP %Y
+File's type (like %y), plus follow symbolic links: `L'=loop, `N'=nonexistent,
+`?' for any other error when determining the type of the target of a symbolic
+link.
+.IP %Z
+(SELinux only) file's security context.
+.IP "%{ %[ %("
+Reserved for future use.
+.PP
+A `%' character followed by any other character is discarded, but the
+other character is printed (don't rely on this, as further format
+characters may be introduced).  A `%' at the end of the format
+argument causes undefined behaviour since there is no following
+character.  In some locales, it may hide your door keys, while in
+others it may remove the final page from the novel you are reading.
+
+The %m and %d directives support the
+.BR # ,
+.B 0
+and
+.B +
+flags, but the other directives do not, even if they
+print numbers.  Numeric directives that do not support these flags
+include
+.BR G ,
+.BR U ,
+.BR b ,
+.BR D ,
+.B  k
+and
+.BR n .
+The `\-' format flag is supported and changes the alignment of a field
+from right-justified (which is the default) to left-justified.
+.PP
+See the
+.B UNUSUAL FILENAMES
+section for information about how unusual characters in filenames are handled.
+
+
+.RE
+.IP \-prune
+True; if the file is a directory, do not descend into it.  If
+.B \-depth
+is given, then
+.B \-prune
+has no effect.  Because
+.B \-delete
+implies
+.BR \-depth ,
+you cannot usefully use
+.B \-prune
+and
+.B \-delete
+together.
+For example, to skip the directory
+.I src/emacs
+and all files and directories under it, and print the names of the other files
+found, do something like this:
+.in +4m
+.nf
+find . \-path ./src/emacs \-prune \-o \-print
+.fi
+.in
+
+
+.IP "\-quit"
+Exit immediately (with return value zero if no errors have occurred).
+This is different to
+.B \-prune
+because
+.B \-prune
+only applies to the contents of pruned directories, while
+.B \-quit
+simply makes
+.B find
+stop immediately.  No child processes will be left
+running.  Any command lines which have been built by
+.B \-exec\ ...\ +
+or
+.B \-execdir\ ...\ +
+are invoked before the program is
+exited.  After
+.B \-quit
+is executed, no more files specified on the command line will be
+processed.  For example,
+.RB ` "find\ \fI/tmp/foo\fP\ \fI/tmp/bar\fP\ \-print\ \-quit" `
+will print only `/tmp/foo`.
+.br
+One common use of
+.B \-quit
+is to stop searching the file system once we have
+found what we want.  For example, if we want to find just a single
+file we can do this:
+.in +4m
+.nf
+find / -name needle -print -quit
+.fi
+.in
+
+.SS OPERATORS
+Listed in order of decreasing precedence:
+
+.IP "( \fIexpr\fR )"
+Force precedence.  Since parentheses are special to the shell, you
+will normally need to quote them.  Many of the examples in this manual
+page use backslashes for this purpose: `\e(...\e)' instead of `(...)'.
+
+.IP "! \fIexpr\fR"
+True if \fIexpr\fR is false.  This character will also usually need
+protection from interpretation by the shell.
+
+.IP "\-not \fIexpr\fR"
+Same as !\&
+.IR expr ,
+but not POSIX compliant.
+
+.IP "\fIexpr1 expr2\fR"
+Two expressions in a row are taken to be joined with an
+implied
+.BR \-a ;
+\fIexpr2\fR is not evaluated if \fIexpr1\fR is false.
+
+.IP "\fIexpr1\fR \-a \fIexpr2\fR"
+Same as
+.IR "expr1 expr2" .
+
+.IP "\fIexpr1\fR \-and \fIexpr2\fR"
+Same as
+.IR "expr1 expr2" ,
+but not POSIX compliant.
+
+.IP "\fIexpr1\fR \-o \fIexpr2\fR"
+Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true.
+
+.IP "\fIexpr1\fR \-or \fIexpr2\fR"
+Same as \fIexpr1\fR
+.B \-o
+.IR expr2 ,
+but not POSIX compliant.
+
+.IP "\fIexpr1\fR , \fIexpr2\fR"
+List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated.  The
+value of \fIexpr1\fR is discarded; the value of the list is the value
+of
+.IR expr2 .
+The comma operator can be useful for searching for
+several different types of thing, but traversing the filesystem
+hierarchy only once.  The
+.B \-fprintf
+action can be used to list the various matched items into several
+different output files.
+.P
+Please note that
+.B \-a
+when specified implicitly (for example by two tests appearing without
+an explicit operator between them) or explicitly has higher precedence
+than
+.BR \-o .
+This means that
+.B find . \-name afile \-o \-name bfile \-print
+will never print
+.IR afile .
+.
+.SH UNUSUAL FILENAMES
+Many of the actions of
+.B find
+result in the printing of data which is under the control of other
+users.  This includes file names, sizes, modification times and so
+forth.  File names are a potential problem since they can contain any
+character except `\e0' and `/'.  Unusual characters in file names can
+do unexpected and often undesirable things to your terminal (for
+example, changing the settings of your function keys on some
+terminals).  Unusual characters are handled differently by various
+actions, as described below.
+
+.IP "\-print0, \-fprint0"
+Always print the exact filename, unchanged, even if the output is
+going to a terminal.
+
+.IP "\-ls, \-fls"
+Unusual characters are always escaped.  White space, backslash, and
+double quote characters are printed using C-style escaping (for
+example `\ef', `\e\(dq').  Other unusual characters are printed using an
+octal escape.  Other printable characters (for
+.B \-ls
+and
+.B \-fls
+these are the characters between octal 041 and 0176) are printed as-is.
+
+.IP "\-printf, \-fprintf"
+If the output is not going to a terminal, it is printed as-is.
+Otherwise, the result depends on which directive is in use.  The
+directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are
+not under control of files' owners, and so are printed as-is.  The
+directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have
+values which are under the control of files' owners but which cannot
+be used to send arbitrary data to the terminal, and so these are
+printed as-is.  The directives %f, %h, %l, %p and %P are quoted.  This
+quoting is performed in the same way as for GNU
+.BR ls .
+This is not the same quoting mechanism as the one used for
+.B \-ls
+and
+.BR \-fls .
+If you are able to decide what format to use for the output of
+.B find
+then it is normally better to use `\e0' as a terminator
+than to use newline, as file names can contain white space and newline
+characters.  The setting of the
+.B LC_CTYPE
+environment variable is used to determine which characters need to be quoted.
+
+.IP "\-print, \-fprint"
+Quoting is handled in the same way as for
+.B \-printf
+and
+.BR \-fprintf .
+If you are using
+.B find
+in a script or in a situation where the matched files might have
+arbitrary names, you should consider using
+.B \-print0
+instead of
+.BR \-print .
+.P
+The
+.B \-ok
+and
+.B \-okdir
+actions print the current filename as-is.  This may change in a future release.
+.
+.SH "STANDARDS CONFORMANCE"
+For closest compliance to the POSIX standard, you should set the
+.B POSIXLY_CORRECT
+environment variable.
+The following options are specified in the POSIX standard
+(IEEE Std 1003.1-2008, 2016 Edition):
+
+.IP \fB\-H\fR
+This option is supported.
+
+.IP \fB\-L\fR
+This option is supported.
+
+.IP \fB\-name\fR
+This option is supported, but POSIX conformance depends on the
+POSIX conformance of the system's
+.BR fnmatch (3)
+library function.  As of findutils-4.2.2, shell metacharacters
+(`*', `?' or `[]' for example) match a leading `.', because
+IEEE PASC interpretation 126 requires this.
+This is a change from previous versions of findutils.
+
+.IP \fB\-type\fR
+Supported.
+POSIX specifies `b', `c', `d', `l', `p', `f' and `s'.
+GNU find also supports `D', representing a Door, where the OS provides these.
+Furthermore, GNU find allows multiple types to be specified at once in a
+comma-separated list.
+
+.IP \fB\-ok\fR
+Supported.
+Interpretation of the response is according to the `yes' and `no'
+patterns selected by setting the
+.B LC_MESSAGES
+environment variable.
+When the
+.B POSIXLY_CORRECT
+environment variable is set, these patterns are taken system's definition
+of a positive (yes) or negative (no) response.
+See the system's documentation for
+.BR nl_langinfo (3),
+in particular YESEXPR and NOEXPR.
+When
+.B POSIXLY_CORRECT
+is not set, the patterns are instead taken from
+.BR find 's
+own message catalogue.
+
+.IP \fB\-newer\fR
+Supported.  If the file specified is a symbolic link, it is always
+dereferenced.  This is a change from previous behaviour, which used to
+take the relevant time from the symbolic link; see the HISTORY section
+below.
+
+.IP \fB\-perm\fR
+Supported.  If the
+.B POSIXLY_CORRECT
+environment variable is not set,
+some mode arguments (for example +a+x) which are not valid in POSIX
+are supported for backward-compatibility.
+
+.IP "Other primaries"
+The primaries
+.BR \-atime ,
+.BR \-ctime ,
+.BR \-depth ,
+.BR \-exec ,
+.BR \-group ,
+.BR \-links ,
+.BR \-mtime ,
+.BR \-nogroup ,
+.BR \-nouser ,
+.BR \-ok ,
+.BR \-path ,
+.BR \-print ,
+.BR \-prune ,
+.BR \-size ,
+.B \-user
+and
+.B \-xdev
+are all supported.
+
+.P
+The POSIX standard specifies parentheses `(', `)', negation `!' and the
+logical AND/OR operators
+.B \-a
+and
+.BR \-o .
+.P
+All other options, predicates, expressions and so forth are extensions
+beyond the POSIX standard.  Many of these extensions are not unique to
+GNU find, however.
+.P
+The POSIX standard requires that
+.B find
+detects loops:
+.IP
+The
+.B find
+utility shall detect infinite loops; that is, entering a
+previously visited directory that is an ancestor of the last file
+encountered.  When it detects an infinite loop, find shall write a
+diagnostic message to standard error and shall either recover its
+position in the hierarchy or terminate.
+.P
+GNU
+.B find
+complies with these requirements.  The link count of
+directories which contain entries which are hard links to an ancestor
+will often be lower than they otherwise should be.  This can mean that
+GNU find will sometimes optimise away the visiting of a subdirectory
+which is actually a link to an ancestor.  Since
+.B find
+does not actually enter such a subdirectory, it is allowed to avoid
+emitting a diagnostic message.  Although this behaviour may be
+somewhat confusing, it is unlikely that anybody actually depends on
+this behaviour.  If the leaf optimisation has been turned off with
+.BR \-noleaf ,
+the directory entry will always be examined and the diagnostic message
+will be issued where it is appropriate.  Symbolic links cannot be used
+to create filesystem cycles as such, but if the
+.B \-L
+option or the
+.B \-follow
+option is in use, a diagnostic message is issued when
+.B find
+encounters a loop of symbolic links.  As with loops containing hard
+links, the leaf optimisation will often mean that
+.B find
+knows that it doesn't need to call
+.I stat()
+or
+.I chdir()
+on the symbolic link, so this diagnostic is frequently not necessary.
+.P
+The
+.B \-d
+option is supported for compatibility with various BSD systems,
+but you should use the POSIX-compliant option
+.B \-depth
+instead.
+.P
+The
+.B POSIXLY_CORRECT
+environment variable does not affect the behaviour of the
+.B \-regex
+or
+.B \-iregex
+tests because those tests aren't specified in the POSIX standard.
+.
+.SH "ENVIRONMENT VARIABLES"
+
+.IP LANG
+Provides a default value for the internationalization variables that
+are unset or null.
+
+.IP LC_ALL
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+
+.IP LC_COLLATE
+The POSIX standard specifies that this variable affects the pattern
+matching to be used for the
+.B \-name
+option.
+GNU find uses the
+.BR fnmatch (3)
+library function, and so support for
+.B LC_COLLATE
+depends on the system library.
+This variable also affects the interpretation of the response to
+.BR \-ok ;
+while the
+.B LC_MESSAGES
+variable selects the actual pattern used to interpret the response to
+.BR \-ok ,
+the interpretation of any bracket expressions in the pattern will be
+affected by
+.BR LC_COLLATE .
+
+.IP LC_CTYPE
+This variable affects the treatment of character classes used in
+regular expressions and also with
+the
+.B \-name
+test, if the system's
+.BR fnmatch (3)
+library function supports this.  This variable also affects the
+interpretation of any character classes in the regular expressions
+used to interpret the response to the prompt issued by
+.BR \-ok .
+The
+.B LC_CTYPE
+environment variable will also affect which characters are considered
+to be unprintable when filenames are printed;
+see the section UNUSUAL FILENAMES.
+
+.IP LC_MESSAGES
+Determines the locale to be used for internationalised messages.  If the
+.B POSIXLY_CORRECT
+environment variable is set, this also determines the interpretation of
+the response to the prompt made by the
+.B \-ok
+action.
+
+.IP NLSPATH
+Determines the location of the internationalisation message catalogues.
+
+.IP PATH
+Affects the directories which are searched to find the executables
+invoked by
+.BR \-exec ,
+.BR \-execdir ,
+.B \-ok
+and
+.BR \-okdir .
+
+.IP POSIXLY_CORRECT
+Determines the block size used by
+.B \-ls
+and
+.BR \-fls .
+If
+.B POSIXLY_CORRECT
+is set, blocks are units of 512 bytes.  Otherwise they are units of 1024 bytes.
+.IP
+Setting this variable also turns off
+warning messages (that is, implies
+.BR \-nowarn )
+by default, because POSIX requires that apart from
+the output for
+.BR \-ok ,
+all messages printed on stderr are diagnostics and must result in a
+non-zero exit status.
+.IP
+When
+.B POSIXLY_CORRECT
+is not set,
+.B "\-perm \fI+zzz\fR"
+is treated just like
+.B "\-perm \fI/zzz\fR"
+if
+\fI+zzz\fR is not a valid symbolic mode.  When
+.B POSIXLY_CORRECT
+is set, such
+constructs are treated as an error.
+.IP
+When
+.B POSIXLY_CORRECT
+is set, the response to the prompt made by the
+.B \-ok
+action is interpreted according to the system's message catalogue, as
+opposed to according to
+.BR find 's
+own message translations.
+
+.IP TZ
+Affects the time zone used for some of the time-related format
+directives of
+.B \-printf
+and
+.BR \-fprintf .
+.
+.SH "EXAMPLES"
+.\" A bulleted \[bu] list of examples.
+.SS Simple `find|xargs` approach
+.IP \[bu]
+Find files named
+.I core
+in or below the directory
+.I /tmp
+and delete them.
+.nf
+\&
+.in +4m
+.B $ find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
+.in
+\&
+.fi
+Note that this will work incorrectly if there are
+any filenames containing newlines, single or double quotes, or spaces.
+.
+.SS Safer `find -print0 | xargs -0` approach
+.IP \[bu]
+Find files named \fIcore\fP in or below the directory \fI/tmp\fP
+and delete them, processing filenames in such a way that file or
+directory names containing single or double quotes, spaces or newlines
+are correctly handled.
+.nf
+\&
+.in +4m
+.B $ find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
+.in
+\&
+.fi
+The
+.B \-name
+test comes before the
+.B \-type
+test in order to avoid having to call
+.BR stat (2)
+on every file.
+.PP
+Note that there is still a race between the time
+.B find
+traverses the hierarchy printing the matching filenames, and the time the
+process executed by
+.B xargs
+works with that file.
+.
+.SS Processing arbitrary starting points
+.IP \[bu]
+Given that another program \fIproggy\fR pre-filters and creates a huge
+NUL-separated list of files, process those as starting points, and find
+all regular, empty files among them:
+.nf
+\&
+.in +4m
+.B $ proggy | find \-files0\-from \- \-maxdepth 0 \-type f \-empty
+.in
+\&
+.fi
+The use of
+.B `\-files0\-from\ \-`
+means to read the names of the starting points from \fIstandard input\fR,
+i.e., from the pipe; and
+.B \-maxdepth\ 0
+ensures that only explicitly those entries are examined without recursing
+into directories (in the case one of the starting points is one).
+.
+.SS
+Executing a command for each file
+.IP \[bu]
+Run
+.I file
+on every file in or below the current directory.
+.nf
+\&
+.in +4m
+.B $ find . \-type f \-exec file \(aq{}\(aq \e;
+.in
+\&
+.fi
+Notice that the braces are enclosed in single quote marks to protect them
+from interpretation as shell script punctuation.  The semicolon is
+similarly protected by the use of a backslash, though single quotes
+could have been used in that case also.
+.PP
+In many cases, one might prefer the
+.B `\-exec\ \&...\&\ +`
+or better the
+.B `\-execdir\ \&...\&\ +`
+syntax for performance and security reasons.
+.
+.SS Traversing the filesystem just once - for 2 different actions
+.IP \[bu]
+Traverse the filesystem just once, listing set-user-ID files and
+directories into
+.I /root/suid.txt
+and large files into
+.IR /root/big.txt .
+.nf
+\&
+.in +4m
+.B $ find / \e
+.in +4m
+.B \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e
+.br
+.B \e( \-size +100M \-fprintf /root/big.txt  \(aq%\-10s %p\en\(aq \e)
+.in -4m
+.in -4m
+\&
+.fi
+This example uses the line-continuation character \(aq\e\(aq on the first two
+lines to instruct the shell to continue reading the command on the next line.
+.
+.SS
+Searching files by age
+.IP \[bu]
+Search for files in your home directory which have been modified in
+the last twenty-four hours.
+.nf
+\&
+.in +4m
+.B $ find $HOME  \-mtime 0
+.in
+\&
+.fi
+This command works this way because the
+time since each file was last modified is divided by 24 hours and any
+remainder is discarded.  That means that to match
+.B \-mtime
+.BR 0 ,
+a file will have to have a modification in the past which is less than
+24 hours ago.
+.
+.SS
+Searching files by permissions
+.IP \[bu]
+Search for files which are executable but not readable.
+.nf
+\&
+.in +4m
+.B $ find /sbin /usr/sbin \-executable \e! \-readable \-print
+.in
+\&
+.fi
+.
+.IP \[bu]
+Search for files which have read and write permission for their owner,
+and group, but which other users can read but not write to.
+.nf
+\&
+.in +4m
+.B $ find . \-perm 664
+.in
+\&
+.fi
+Files which meet these criteria but have other permissions bits set
+(for example if someone can execute the file) will not be matched.
+.
+.IP \[bu]
+Search for files which have read and write permission for their owner
+and group, and which other users can read, without regard to the
+presence of any extra permission bits (for example the executable
+bit).
+.nf
+\&
+.in +4m
+.B $ find . \-perm \-664
+.in
+\&
+.fi
+This will match a file which has mode
+.IR 0777 ,
+for example.
+.
+.IP \[bu]
+Search for files which are writable by somebody (their owner, or
+their group, or anybody else).
+.nf
+\&
+.in +4m
+.B $ find . \-perm /222
+.in
+\&
+.fi
+.
+.IP \[bu]
+Search for files which are writable by either their owner or their group.
+.nf
+\&
+.in +4m
+.B $ find . \-perm /220
+.B $ find . \-perm /u+w,g+w
+.B $ find . \-perm /u=w,g=w
+.in
+\&
+.fi
+All three of these commands do the same thing, but the first one uses
+the octal representation of the file mode, and the other two use the
+symbolic form.
+The files don't have to be writable by both the owner and group to be matched;
+either will do.
+.
+.IP \[bu]
+Search for files which are writable by both their owner and their group.
+.nf
+\&
+.in +4m
+.B $ find . \-perm \-220
+.B $ find . \-perm \-g+w,u+w
+.in
+\&
+.fi
+Both these commands do the same thing.
+.
+.IP \[bu]
+A more elaborate search on permissions.
+.nf
+\&
+.in +4m
+.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111
+.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x
+.in
+\&
+.fi
+These two commands both search for files that are readable for everybody
+.RB ( "\-perm \-444"
+or
+.BR "\-perm \-a+r" ),
+have at least one write bit
+set
+.RB ( "\-perm /222"
+or
+.BR "\-perm /a+w" )
+but are not executable for anybody
+.RB ( "! \-perm /111"
+or
+.B ! \-perm /a+x
+respectively).
+.
+.SS
+Pruning - omitting files and subdirectories
+.IP \[bu]
+Copy the contents of
+.I /source-dir
+to
+.IR /dest-dir ,
+but omit files and directories named
+.I .snapshot
+(and anything in them).  It also omits files or directories whose name ends in
+`\(ti', but not their contents.
+.nf
+\&
+.in +4m
+.B $ cd /source-dir
+.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e
+.br
+.in +4m
+.B | cpio \-pmd0  /dest-dir
+.in -4m
+.in -4m
+\&
+.fi
+The construct
+.B \-prune\ \-o\ \e(\ \&...\&\ \-print0\ \e)
+is quite common.  The idea here is that the expression before
+.B \-prune
+matches things which are to be pruned.  However, the
+.B \-prune
+action itself returns true, so the following
+.B \-o
+ensures that the right hand side is evaluated only for those
+directories which didn't get pruned (the contents of the pruned
+directories are not even visited, so their contents are irrelevant).
+The expression on the right hand side of the
+.B \-o
+is in parentheses only for clarity.  It emphasises that the
+.B \-print0
+action takes place only for things that didn't have
+.B \-prune
+applied to them.  Because the default `and' condition between tests
+binds more tightly than
+.BR \-o ,
+this is the default anyway, but the parentheses help to show
+what is going on.
+.
+.IP \[bu]
+Given the following directory of projects and their associated SCM
+administrative directories, perform an efficient search for the
+projects' roots:
+.nf
+\&
+.in +4m
+.B $ find repo/ \e
+.in +4m
+.B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e
+.B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e
+.B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e
+.B \e) \-print \-prune
+.in -4m
+.in -4m
+\&
+.fi
+Sample output:
+.nf
+\&
+.in +4m
+.B repo/project1/CVS
+.B repo/gnu/project2/.svn
+.B repo/gnu/project3/.svn
+.B repo/gnu/project3/src/.svn
+.B repo/project4/.git
+.in
+\&
+.fi
+In this example,
+.B \-prune
+prevents unnecessary descent into directories that have already been
+discovered (for example we do not search
+.I project3/src
+because we already found
+.IR project3/.svn ),
+but ensures sibling directories
+.RI ( project2
+and
+.IR project3 )
+are found.
+.
+.SS
+Other useful examples
+.IP \[bu]
+Search for several file types.
+.nf
+\&
+.in +4m
+.B $ find /tmp \-type f,d,l
+.in
+\&
+.fi
+Search for files, directories, and symbolic links in the directory
+.I /tmp
+passing these types as a comma-separated list (GNU extension),
+which is otherwise equivalent to the longer, yet more portable:
+.nf
+\&
+.in +4m
+.B $ find /tmp \e( \-type f \-o \-type d \-o \-type l \e)
+.in
+\&
+.fi
+.
+.IP \[bu]
+Search for files with the particular name
+.I needle
+and stop immediately when we find the first one.
+.nf
+\&
+.in +4m
+.B $ find / -name needle -print -quit
+.in
+\&
+.fi
+.
+.IP \[bu]
+Demonstrate the interpretation of the
+.B %f
+and
+.B %h
+format directives of the
+.B \-printf
+action for some corner-cases.
+Here is an example including some output.
+.nf
+\&
+.in +4m
+.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
+.B [.][.]
+.B [.][..]
+.B [][/]
+.B [][tmp]
+.B [/tmp][TRACE]
+.B [.][compile]
+.B [compile/64/tests][find]
+.in
+\&
+.fi
+.
+.SH EXIT STATUS
+.B find
+exits with status 0 if all files are processed successfully, greater
+than 0 if errors occur.
+This is deliberately a very broad description,
+but if the return value is non-zero,
+you should not rely on the correctness of the results of
+.BR find .
+
+When some error occurs,
+.B find
+may stop immediately, without completing all the actions specified.
+For example, some starting points may not have been examined or some
+pending program invocations for
+.B \-exec\ \&...\&\ {}\ +
+or
+.B "\-execdir\ \&...\&\ {}\ +
+may not have been performed.
+.
+.SH "HISTORY"
+As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
+example) used in filename patterns match a leading `.', because
+IEEE POSIX interpretation 126 requires this.
+.P
+As of findutils-4.3.3,
+.B \-perm\ /000
+now matches all files instead of none.
+.P
+Nanosecond-resolution
+timestamps were implemented in findutils-4.3.3.
+.P
+As of findutils-4.3.11, the
+.B \-delete
+action sets
+.BR find 's
+exit status to a nonzero value when it fails.
+However,
+.B find
+will not exit immediately.  Previously,
+.BR find 's
+exit status was unaffected by the failure of
+.BR \-delete .
+.TS
+l l l .
+Feature	Added in	Also occurs in
+\-files0\-from	4.9.0
+\-newerXY	4.3.3	BSD
+\-D	4.3.1
+\-O	4.3.1
+\-readable	4.3.0
+\-writable	4.3.0
+\-executable	4.3.0
+\-regextype	4.2.24
+\-exec ... +	4.2.12	POSIX
+\-execdir	4.2.12	BSD
+\-okdir	4.2.12
+\-samefile	4.2.11
+\-H	4.2.5	POSIX
+\-L	4.2.5	POSIX
+\-P	4.2.5	BSD
+\-delete	4.2.3
+\-quit	4.2.3
+\-d	4.2.3	BSD
+\-wholename	4.2.0
+\-iwholename	4.2.0
+\-ignore_readdir_race	4.2.0
+\-fls	4.0
+\-ilname	3.8
+\-iname	3.8
+\-ipath	3.8
+\-iregex	3.8
+.TE
+.P
+The syntax
+\.B \-perm +MODE
+was removed in findutils-4.5.12, in favour of
+\.B \-perm
+.BR /MODE .
+The
+.B +MODE
+syntax had been deprecated since findutils-4.2.21
+which was released in 2005.
+.
+.SH "NON-BUGS"
+.SS Operator precedence surprises
+The command
+.B find . \-name afile \-o \-name bfile \-print
+will never print
+.I afile
+because this is actually equivalent to
+.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" .
+Remember that the precedence of
+.B \-a
+is higher than that of
+.B \-o
+and when there is no operator specified between tests,
+.B \-a
+is assumed.
+.SS \(lqpaths must precede expression\(rq error message
+.nf
+.B $ find . \-name *.c \-print
+find: paths must precede expression
+find: possible unquoted pattern after predicate `-name'?
+.fi
+.P
+This happens when the shell could expand the pattern
+.I *.c
+to more than one file name existing in the current directory,
+and passing the resulting file names in the command line to
+.B find
+like this:
+.nf
+.
+.B find . \-name frcode.c locate.c word_io.c \-print
+.
+.fi
+That command is of course not going to work, because the
+.B \-name
+predicate allows exactly only one pattern as argument.  Instead of doing things
+this way, you should enclose the pattern in quotes or escape the wildcard, thus
+allowing
+.B find
+to use the pattern with the wildcard during the search for file name matching
+instead of file names expanded by the parent shell:
+.nf
+.B $ find . \-name \(aq*.c\(aq \-print
+.B $ find . \-name \e*.c \-print
+.fi
+.
+.SH "BUGS"
+There are security problems inherent in the behaviour that the POSIX
+standard specifies for
+.BR find ,
+which therefore cannot be fixed.  For example, the
+.B \-exec
+action is
+inherently insecure, and
+.B \-execdir
+should be used instead.
+.
+.P
+The environment variable
+.B LC_COLLATE
+has no effect on the
+.B \-ok
+action.
+.
+.SH "REPORTING BUGS"
+GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.PP
+Report any other issue via the form at the GNU Savannah bug tracker:
+.RS
+<https://savannah.gnu.org/bugs/?group=findutils>
+.RE
+General topics about the GNU findutils package are discussed at the
+.I bug\-findutils
+mailing list:
+.RS
+<https://lists.gnu.org/mailman/listinfo/bug-findutils>
+.RE
+.
+.SH COPYRIGHT
+Copyright \(co 1990-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.
+.SH "SEE ALSO"
+.BR chmod (1),
+.BR locate (1),
+.BR ls (1),
+.BR updatedb (1),
+.BR xargs (1),
+.BR lstat (2),
+.BR stat (2),
+.BR ctime (3)
+.BR fnmatch (3),
+.BR printf (3),
+.BR strftime (3),
+.BR locatedb (5),
+.BR regex (7)
+.PP
+Full documentation <https://www.gnu.org/software/findutils/find>
+.br
+or available locally via:
+.B info find
diff --git a/upstream/mageia-cauldron/man1/finger.1 b/upstream/mageia-cauldron/man1/finger.1
new file mode 100644
index 00000000..91fed19b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/finger.1
@@ -0,0 +1,194 @@
+.\" Copyright (c) 1989, 1990 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	from: @(#)finger.1	6.14 (Berkeley) 7/27/91
+.\"	$Id: finger.1,v 1.1.1.1 2000/11/03 19:18:15 mk Exp $
+.\"
+.Dd August 15, 1999
+.Dt FINGER 1
+.Os "Linux NetKit (0.17)"
+.Sh NAME
+.Nm finger
+.Nd user information lookup program
+.Sh SYNOPSIS
+.Nm finger
+.Op Fl lmsp
+.Op Ar user ...
+.Op Ar user@host ...
+.Sh DESCRIPTION
+The
+.Nm finger
+displays information about the system users.
+.Pp
+Options are:
+.Bl -tag -width flag
+.It Fl s
+.Nm Finger
+displays the user's login name, real name, terminal name and write
+status (as a ``*'' after the terminal name if write permission is
+denied), idle time, login time, office location and office phone
+number.
+.Pp
+Login time is displayed as month, day, hours and minutes, unless
+more than six months ago, in which case the year is displayed rather
+than the hours and minutes.
+.Pp
+Unknown devices as well as nonexistent idle and login times are
+displayed as single asterisks.
+.Pp
+.It Fl l
+Produces a multi-line format displaying all of the information
+described for the
+.Fl s
+option as well as the user's home directory, home phone number, login
+shell, mail status, and the contents of the files
+.Dq Pa .plan ,
+.Dq Pa .project ,
+.Dq Pa .pgpkey
+and
+.Dq Pa .forward
+from the user's home directory.
+.Pp
+Phone numbers specified as eleven digits are printed as ``+N-NNN-NNN-NNNN''.
+Numbers specified as ten or seven digits are printed as the appropriate
+subset of that string.
+Numbers specified as five digits are printed as ``xN-NNNN''.
+Numbers specified as four digits are printed as ``xNNNN''.
+.Pp
+If write permission is denied to the device, the phrase ``(messages off)''
+is appended to the line containing the device name.
+One entry per user is displayed with the
+.Fl l
+option; if a user is logged on multiple times, terminal information
+is repeated once per login.
+.Pp
+Mail status is shown as ``No Mail.'' if there is no mail at all,
+``Mail last read DDD MMM ## HH:MM YYYY (TZ)'' if the person has looked
+at their mailbox since new mail arriving, or ``New mail received ...'',
+``  Unread since ...'' if they have new mail.
+.Pp
+.It Fl p
+Prevents
+the
+.Fl l
+option of
+.Nm finger
+from displaying the contents of the
+.Dq Pa .plan ,
+.Dq Pa .project
+and
+.Dq Pa .pgpkey
+files.
+.It Fl m
+Prevent matching of
+.Ar user
+names.
+.Ar User
+is usually a login name; however, matching will also be done on the
+users' real names, unless the
+.Fl m
+option is supplied.
+All name matching performed by
+.Nm finger
+is case insensitive.
+.El
+.Pp
+If no options are specified,
+.Nm finger
+defaults to the
+.Fl l
+style output if operands are provided, otherwise to the
+.Fl s
+style.
+Note that some fields may be missing, in either format, if information
+is not available for them.
+.Pp
+If no arguments are specified,
+.Nm finger
+will print an entry for each user currently logged into the system.
+.Pp
+.Nm Finger
+may be used to look up users on a remote machine.
+The format is to specify a
+.Ar user
+as
+.Dq Li user@host ,
+or
+.Dq Li @host ,
+where the default output
+format for the former is the
+.Fl l
+style, and the default output format for the latter is the
+.Fl s
+style.
+The
+.Fl l
+option is the only option that may be passed to a remote machine.
+.Pp
+If standard output is a socket, 
+.Nm finger
+will emit a carriage return (^M) before every linefeed (^J). This is
+for processing remote finger requests when invoked by
+.Xr fingerd 8 .
+.Sh FILES
+.Bl -tag -width mmmmmmmmmmmmmmm
+.It Pa ~/.nofinger
+If finger finds this file in a user's home directory, it will, for
+finger requests originating outside the local host, firmly deny the
+existence of that user.  For this to work, the finger program, as
+started by
+.Xr fingerd 8 ,
+must be able to see the
+.Pa .nofinger
+file. This generally means that the home directory containing the file
+must have the other-users-execute bit set (o+x). See
+.Xr chmod 1 .
+If you use this feature for privacy, please test it with ``finger
+@localhost'' before relying on it, just in case.
+.It ~/.plan
+.It ~/.project
+.It ~/.pgpkey
+These files are printed as part of a long-format request. The
+.Pa .project
+file is limited to one line; the
+.Pa .plan
+file may be arbitrarily long.
+.El
+.Sh SEE ALSO
+.Xr chfn 1 ,
+.Xr passwd 1 ,
+.Xr w 1 ,
+.Xr who 1
+.Sh HISTORY
+The
+.Nm finger
+command appeared in
+.Bx 3.0 .
diff --git a/upstream/mageia-cauldron/man1/fitstopnm.1 b/upstream/mageia-cauldron/man1/fitstopnm.1
new file mode 100644
index 00000000..c0f44dd7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fitstopnm.1
@@ -0,0 +1,157 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Fitstopnm User Manual" 0 "02 August 2015" "netpbm documentation"
+
+.SH NAME
+fitstopnm - convert a FITS file into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBfitstopnm\fP
+[\fB-image=\fP\fIN\fP]
+[\fB-scanmax\fP]
+[\fB-printmax\fP]
+[\fB-min=\fP\fIf\fP]
+[\fB-max=\fP\fIf\fP]
+[\fB-omaxval=\fP\fIN\fP
+[\fIFITSfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBfitstopnm\fP reads a FITS (Flexible Image Transport System) file as
+input and produces a PPM image if the FITS file consists of 3 image planes
+(NAXIS = 3 and NAXIS3 = 3), or a PGM image if the FITS file consists of 2
+image planes (NAXIS = 2), or if you specify the \fB-image\fP option.
+.PP
+Note that the PPM image is highly unlikely to be a true PPM image, as it is
+not normal for a FITS image to use the third axis as R, G, and B components of
+the pixels.  The most common interpretation when there are 3 axes is that the
+third one is time.  So the image is instead a pseudo-PPM in which the three
+sample values of a pixel represent something other than color components, for
+example gray levels at three instants (this variation on PPM is common in
+programs such as \fBfitstopnm\fP that predate the PAM format).
+.PP
+If you work with FITS images with 3 axes, you should probably always use
+the \fB-image\fP option to avoid getting an unwanted pseudo-PPM image.
+.PP
+The program tells you what kind of PNM image it is writing.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBfitstopnm\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-image=\fP\fIN\fP
+This is for FITS files with three axes.  This option says that the third
+axis is for multiple images, and the option value \fIN\fP tells which one you
+want.
+
+.TP
+\fB-omaxval=\fP\fIN\fP
+.sp
+This is the maxval that the output PNM image is to have.
+.sp
+By default, the maxval is the least possible to retain all the
+precision of the FITS input.  That means the difference between the
+highest and lowest sample value in the input.  If the values range
+from -5 to 100, for example, the default maxval would be 106 and each
+PNM sample value would correspond to one FITS sample value.
+.sp
+For a FITS input with floating point sample values, the precision is
+essentially unlimited, so this is not possible.  In that case, the default
+maxval is simply 255.
+.sp
+This option was new in Netpbm 10.39 (June 2007).  Before that, the
+output maxval is always the default.
+
+.TP
+\fB-min=\fP\fIfloat\fP
+.TP
+\fB-max=\fP\fIfloat\fP
+.sp
+You can use these options to override the min and max values as
+read from the FITS header or the image data if the header has no
+DATAMIN and DATAMAX keywords.
+
+.TP
+\fB-scanmax\fP
+Use this option to force the program to scan the data even when the
+header has DATAMIN and DATAMAX.
+
+.TP
+\fB-printmax\fP
+With this option, the program just prints the min and max values
+and quits without doing its normal job.
+.sp
+This is for use in shell programs.  Example:
+
+.nf
+\f(CW
+    eval 'fitstopnm -printmax $filename | \e
+    awk {min = $1; max = $2} \e
+          END {print "min=" min; " max=" max}'
+\fP
+
+.fi
+
+
+
+.UN notes
+.SH NOTES
+
+.UN pixelorder
+.SS Pixel Order
+.PP
+You may need to pass the output of \fBfitstopnm\fP through \fBpamflip
+-topbottom\fP.  See 
+.UR pamtofits.html#pixelorder
+\fBpamtofits\fP
+.UE
+\&
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtofits" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer, with modifications by Daniel
+Briggs (\fIdbriggs@nrao.edu\fP) and
+Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/fitstopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/flex.1 b/upstream/mageia-cauldron/man1/flex.1
new file mode 100644
index 00000000..5ec683c4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/flex.1
@@ -0,0 +1,163 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH FLEX "1" "March 2022" "The Flex Project" "Programming"
+.SH NAME
+flex \- the fast lexical analyser generator
+.SH SYNOPSIS
+.B flex
+[\fI\,OPTIONS\/\fR] [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+Generates programs that perform pattern\-matching on text.
+.SS "Table Compression:"
+.TP
+\fB\-Ca\fR, \fB\-\-align\fR
+trade off larger tables for better memory alignment
+.TP
+\fB\-Ce\fR, \fB\-\-ecs\fR
+construct equivalence classes
+.TP
+\fB\-Cf\fR
+do not compress tables; use \fB\-f\fR representation
+.TP
+\fB\-CF\fR
+do not compress tables; use \fB\-F\fR representation
+.TP
+\fB\-Cm\fR, \fB\-\-meta\-ecs\fR
+construct meta\-equivalence classes
+.TP
+\fB\-Cr\fR, \fB\-\-read\fR
+use read() instead of stdio for scanner input
+.TP
+\fB\-f\fR, \fB\-\-full\fR
+generate fast, large scanner. Same as \fB\-Cfr\fR
+.TP
+\fB\-F\fR, \fB\-\-fast\fR
+use alternate table representation. Same as \fB\-CFr\fR
+.TP
+\fB\-Cem\fR
+default compression (same as \fB\-\-ecs\fR \fB\-\-meta\-ecs\fR)
+.SS "Debugging:"
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+enable debug mode in scanner
+.TP
+\fB\-b\fR, \fB\-\-backup\fR
+write backing\-up information to lex.backup
+.TP
+\fB\-p\fR, \fB\-\-perf\-report\fR
+write performance report to stderr
+.TP
+\fB\-s\fR, \fB\-\-nodefault\fR
+suppress default rule to ECHO unmatched text
+.TP
+\fB\-T\fR, \fB\-\-trace\fR
+flex should run in trace mode
+.TP
+\fB\-w\fR, \fB\-\-nowarn\fR
+do not generate warnings
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+write summary of scanner statistics to stdout
+.TP
+\fB\-\-hex\fR
+use hexadecimal numbers instead of octal in debug outputs
+.SH FILES
+.TP
+\fB\-o\fR, \fB\-\-outfile\fR=\fI\,FILE\/\fR
+specify output filename
+.TP
+\fB\-S\fR, \fB\-\-skel\fR=\fI\,FILE\/\fR
+specify skeleton file
+.TP
+\fB\-t\fR, \fB\-\-stdout\fR
+write scanner on stdout instead of lex.yy.c
+.TP
+\fB\-\-yyclass\fR=\fI\,NAME\/\fR
+name of C++ class
+.TP
+\fB\-\-header\-file\fR=\fI\,FILE\/\fR
+create a C header file in addition to the scanner
+.HP
+\fB\-\-tables\-file\fR[=\fI\,FILE\/\fR] write tables to FILE
+.SS "Scanner behavior:"
+.TP
+\fB\-7\fR, \fB\-\-7bit\fR
+generate 7\-bit scanner
+.TP
+\fB\-8\fR, \fB\-\-8bit\fR
+generate 8\-bit scanner
+.TP
+\fB\-B\fR, \fB\-\-batch\fR
+generate batch scanner (opposite of \fB\-I\fR)
+.TP
+\fB\-i\fR, \fB\-\-case\-insensitive\fR
+ignore case in patterns
+.TP
+\fB\-l\fR, \fB\-\-lex\-compat\fR
+maximal compatibility with original lex
+.TP
+\fB\-X\fR, \fB\-\-posix\-compat\fR
+maximal compatibility with POSIX lex
+.TP
+\fB\-I\fR, \fB\-\-interactive\fR
+generate interactive scanner (opposite of \fB\-B\fR)
+.TP
+\fB\-\-yylineno\fR
+track line count in yylineno
+.SS "Generated code:"
+.TP
+\-+,  \fB\-\-c\fR++
+generate C++ scanner class
+.TP
+\fB\-Dmacro\fR[=\fI\,defn\/\fR]
+#define macro defn  (default defn is '1')
+.TP
+\fB\-L\fR,  \fB\-\-noline\fR
+suppress #line directives in scanner
+.TP
+\fB\-P\fR,  \fB\-\-prefix\fR=\fI\,STRING\/\fR
+use STRING as prefix instead of "yy"
+.TP
+\fB\-R\fR,  \fB\-\-reentrant\fR
+generate a reentrant C scanner
+.TP
+\fB\-\-bison\-bridge\fR
+scanner for bison pure parser.
+.TP
+\fB\-\-bison\-locations\fR
+include yylloc support.
+.TP
+\fB\-\-stdinit\fR
+initialize yyin/yyout to stdin/stdout
+.TP
+\fB\-\-nounistd\fR
+do not include <unistd.h>
+.TP
+\fB\-\-noFUNCTION\fR
+do not generate a particular FUNCTION
+.SS "Miscellaneous:"
+.TP
+\fB\-c\fR
+do\-nothing POSIX option
+.TP
+\fB\-n\fR
+do\-nothing POSIX option
+.HP
+\-?
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+produce this help message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+report flex version
+.SH "SEE ALSO"
+The full documentation for
+.B flex
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B flex
+programs are properly installed at your site, the command
+.IP
+.B info flex
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/floppyd.1 b/upstream/mageia-cauldron/man1/floppyd.1
new file mode 100644
index 00000000..700136da
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/floppyd.1
@@ -0,0 +1,255 @@
+'\" t
+.TH floppyd 1 "21Mar23" mtools-4.0.43
+.SH Name
+floppyd - floppy daemon for remote access to floppy drive
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+\&\fR\&\f(CWFloppyd\fR is used as a server to grant access to the floppy drive
+to clients running on a remote machine, just as an X server grants
+access to the display to remote clients.  It has the following syntax:
+.PP
+\&\fR\&\f(CWfloppyd\fR [\fR\&\f(CW-d\fR] [\fR\&\f(CW-l\fR] [\fR\&\f(CW-s\fR \fIport\fR] [\fR\&\f(CW-r\fR
+\&\fIuser\fR] [\fR\&\f(CW-b\fR \fIipaddr\fR] [\fR\&\f(CW-x\fR \fIdisplay\fR] \fIdevicenames\fR
+.PP
+\&\fR\&\f(CWfloppyd\fR is always associated with an X server.  It runs on the
+same machine as its X server, and listens on port 5703 and above.
+.PP
+.SH Authentication
+.PP
+\&\fR\&\f(CWfloppyd\fR authenticates remote clients using the \fR\&\f(CWXauthority\fR
+protocol. Xhost authentication is not supported. Each floppyd is
+associated with an X server.  When a remote client attempts to connect
+to floppyd, it sends floppyd the X authority record corresponding to
+floppyd's X server.  Floppyd in turn then tries to open up a connection
+to the X server in order to verify the authenticity of the xauth record.
+If the connection to the X server succeeds, the client is granted
+access.
+\&\fR\&\f(CWDISPLAY\fR.
+.PP
+\&\fBCaution\fR: In order to make authentication work correctly, the
+local host should \fBnot\fR be listed in the \fR\&\f(CWxhost\fR list of
+allowed hosts.
+ Indeed, hosts listed in \fR\&\f(CWxhost\fR do not need a correct
+\&\fR\&\f(CWXauthority\fR cookie to connect to the X server. As \fR\&\f(CWfloppyd\fR
+runs on the same host as the X server, all its probe connection would
+succeed even for clients who supplied a bad cookie.  This means that
+your floppy drive would be open to the world, i.e. a huge security hole.
+ If your X server does not allow you to remove \fR\&\f(CWlocalhost:0\fR and
+\&\fR\&\f(CW:0\fR from the \fR\&\f(CWxhost\fR list, you can prevent floppyd from
+probing those display names with the \fR\&\f(CW-l\fR option.
+.PP
+.SH Command\ line\ options
+.TP
+\&\fR\&\f(CWd\fR\ 
+Daemon mode. Floppyd runs its own server loop.  Do not supply this if
+you start floppyd from \fR\&\f(CWinetd.conf\fR
+.TP
+\&\fR\&\f(CWs\ \ \fIport\fR\&\f(CW\fR\ 
+Port number for daemon mode.  Default is 5703 + \fIdisplaynumber\fR.
+This flag implies daemon mode.  For example, for display
+\&\fR\&\f(CWhitchhiker:5\fR, the port would be 5708.
+.TP
+\&\fR\&\f(CWb\ \ \fIipaddr\fR\&\f(CW\fR\ 
+Bind address (for multi homed hosts). This flag implies daemon mode
+.TP
+\&\fR\&\f(CWr\ \fIuser\fR\&\f(CW\fR\ 
+Run the server under as the given user
+.TP
+\&\fR\&\f(CWx\ \fIdisplay\fR\&\f(CW\fR\ 
+X display to use for authentication. By default, this is taken from the
+\&\fR\&\f(CWDISPLAY\fR variable. If neither the \fR\&\f(CWx\fR attribute is present
+nor \fR\&\f(CWDISPLAY\fR is set, floppyd uses \fR\&\f(CW:0.0\fR.
+.PP
+\&\fIdevicenames\fR is a list of device nodes to be opened.  Default
+is \fR\&\f(CW/dev/fd0\fR. Multiple devices are only supported on mtools
+versions newer than 3.9.11.
+.PP
+.SH Connecting\ to\ floppyd
+.PP
+ In order to use floppyd, add the flag \fR\&\f(CWremote\fR to the device
+description in your \fR\&\f(CW\(if~/.mtoolsrc\(is\fR file.  If the flag \fR\&\f(CWremote\fR
+is given, the \fR\&\f(CWfile\fR parameter of the device description is taken
+to be a remote address.  It's format is the following:
+\&\fIhostname\fR\fR\&\f(CW:\fR\fIdisplaynumber\fR[\fR\&\f(CW/\fR[\fIbaseport\fR][\fR\&\f(CW/\fR\fIdrive\fR]]. When
+using this entry, mtools connects to port
+\&\fIbaseport\fR+\fIdisplaynumber\fR at \fIhostname\fR. By default
+\&\fIbaseport\fR is 5703. The drive parameter is to distinguish among
+multiple drives associated with a single display (only mtools versions
+more recent than 3.9.11)
+.PP
+.SH Examples:
+.PP
+ The following starts a floppy daemon giving access to \fR\&\f(CW\(if/dev/fd0\(is\fR,
+listening on the default port 5703, tied to the default X servers:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+floppyd -d /dev/fd0
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ Each of the following starts a floppy daemon giving access to
+\&\fR\&\f(CW\(if/dev/fd1\(is\fR, tied to the :1 local X servers, and listening on port
+5704. We assume that the local host is named \fR\&\f(CWhitchhiker\fR.
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+floppyd -d /dev/fd0
+floppyd -d -x :1 -p 5704 /dev/fd0 
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ If you want to start floppyd by \fR\&\f(CWinetd\fR instead of running it as a 
+daemon, insert the following lines into \fR\&\f(CW\(if/etc/services\(is\fR:
+ 
+.nf
+.ft 3
+.in +0.3i
+# floppy daemon
+floppyd-0    5703/tcp    # floppy daemon for X server :0
+floppyd-1    5704/tcp    # floppy daemon for X server :1
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ And insert the following into \fR\&\f(CW\(if/etc/inetd.conf\(is\fR (assuming that you
+have defined a user named floppy in your \fR\&\f(CW\(if/etc/passwd\(is\fR):
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+# floppy daemon
+floppyd-0 stream  tcp  wait  floppy  /usr/sbin/floppyd floppyd /dev/fd0 
+floppyd-1 stream  tcp  wait  floppy  /usr/sbin/floppyd floppyd -x :1 /dev/fd0 
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ Note that you need to supply the X display names for the second
+floppyd.  This is because the port is opened by inetd.conf, and hence
+floppyd cannot know its number to interfere the display number.
+.PP
+On the client side, insert the following into your \fR\&\f(CW\(if~/.mtoolsrc\(is\fR
+to define a drive letter accessing floppy drive in your X terminal:
+ 
+.nf
+.ft 3
+.in +0.3i
+drive x: file="$DISPLAY" remote
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+If your X terminal has more than one drive, you may access the
+additional drives as follows:
+ 
+.nf
+.ft 3
+.in +0.3i
+drive y: file="$DISPLAY//1" remote
+drive z: file="$DISPLAY//2" remote
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/floppyd_installtest.1 b/upstream/mageia-cauldron/man1/floppyd_installtest.1
new file mode 100644
index 00000000..6cdf73ea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/floppyd_installtest.1
@@ -0,0 +1,94 @@
+'\" t
+.TH floppyd_installtest 1 "21Mar23" mtools-4.0.43
+.SH Name
+floppyd_installtest - tests whether floppyd is installed and running
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+\&\fR\&\f(CWFloppyd_installtest\fR is used to check for the presence of a running
+floppyd daemon. This is useful, if you have a small front-end script to
+mtools, which decides whether to use floppyd or not.
+.PP
+\&\fR\&\f(CWfloppyd_installtest\fR [\fR\&\f(CW-f\fR]  Connect-String
+.PP
+If the \fR\&\f(CW-f\fR option is specified, \fR\&\f(CWfloppyd_installtest\fR does a
+full X-Cookie authentication and complains if this does not work.
+.PP
+The connect-String has the format described in the floppyd-section:
+\&\fIhostname\fR\fR\&\f(CW:\fR\fIdisplaynumber\fR[\fR\&\f(CW/\fR\fIbaseport\fR]
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/fmt.1 b/upstream/mageia-cauldron/man1/fmt.1
new file mode 100644
index 00000000..1bfa6a62
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fmt.1
@@ -0,0 +1,60 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH FMT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+fmt \- simple optimal text formatter
+.SH SYNOPSIS
+.B fmt
+[\fI\,-WIDTH\/\fR] [\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Reformat each paragraph in the FILE(s), writing to standard output.
+The option \fB\-WIDTH\fR is an abbreviated form of \fB\-\-width\fR=\fI\,DIGITS\/\fR.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-c\fR, \fB\-\-crown\-margin\fR
+preserve indentation of first two lines
+.TP
+\fB\-p\fR, \fB\-\-prefix\fR=\fI\,STRING\/\fR
+reformat only lines beginning with STRING,
+reattaching the prefix to reformatted lines
+.TP
+\fB\-s\fR, \fB\-\-split\-only\fR
+split long lines, but do not refill
+.TP
+\fB\-t\fR, \fB\-\-tagged\-paragraph\fR
+indentation of first line different from second
+.TP
+\fB\-u\fR, \fB\-\-uniform\-spacing\fR
+one space between words, two after sentences
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,WIDTH\/\fR
+maximum line width (default of 75 columns)
+.TP
+\fB\-g\fR, \fB\-\-goal\fR=\fI\,WIDTH\/\fR
+goal width (default of 93% of width)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Ross Paterson.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/fmt>
+.br
+or available locally via: info \(aq(coreutils) fmt invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/fold.1 b/upstream/mageia-cauldron/man1/fold.1
new file mode 100644
index 00000000..8cb1760f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fold.1
@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH FOLD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+fold \- wrap each input line to fit in specified width
+.SH SYNOPSIS
+.B fold
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Wrap input lines in each FILE, writing to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-bytes\fR
+count bytes rather than columns
+.TP
+\fB\-c\fR, \fB\-\-characters\fR
+count characters rather than columns
+.TP
+\fB\-s\fR, \fB\-\-spaces\fR
+break at spaces
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,WIDTH\/\fR
+use WIDTH columns instead of 80
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/fold>
+.br
+or available locally via: info \(aq(coreutils) fold invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/formail.1 b/upstream/mageia-cauldron/man1/formail.1
new file mode 100644
index 00000000..92c861ec
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/formail.1
@@ -0,0 +1,558 @@
+.\"if n .pl +(135i-\n(.pu)
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.Id $Id$
+.TH FORMAIL 1 \*(Dt BuGless
+.rn SH Sh
+.de SH
+.br
+.ne 11
+.Sh "\\$1"
+..
+.rn SS Ss
+.de SS
+.br
+.ne 10
+.Ss "\\$1"
+..
+.rn TP Tp
+.de TP
+.br
+.ne 9
+.Tp \\$1
+..
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.SH NAME
+formail \- mail (re)formatter
+.SH SYNOPSIS
+.na
+.B formail
+.RI [ "\fB\+\fPskip" ]
+.RI [ "\fB\-\fPtotal" ]
+.RB [ \-bczfrktedqBY ]
+.RB [ \-p
+.IR prefix ]
+.if n .ti +0.5i
+.RB [ \-D
+.IR "maxlen idcache" ]
+.if n .ti +0.5i
+.RB [ \-l
+.IR folder ]
+.if n .ti +0.5i
+.RB [ \-x
+.IR headerfield ]
+.RB [ \-X
+.IR headerfield ]
+.if n .ti +0.5i
+.RB [ \-a
+.IR headerfield ]
+.RB [ \-A
+.IR headerfield ]
+.if n .ti +0.5i
+.RB [ \-i
+.IR headerfield ]
+.RB [ \-I
+.IR headerfield ]
+.if n .ti +0.5i
+.RB [ \-u
+.IR headerfield ]
+.RB [ \-U
+.IR headerfield ]
+.if n .ti +0.5i
+.RB [ \-R
+.I oldfield
+.IR newfield ]
+.if n .ti +0.5i
+.RB [ \-n
+.RI [ maxprocs
+]]
+.RB [ \-m
+.IR minfields ]
+.RB [ \-s
+.RI [ command
+.RI [ arg
+\&.\|.\|.\|]]]
+.br
+.B formail
+.B \-v
+.ad
+.SH DESCRIPTION
+.B formail
+is a filter that can be used to force mail into mailbox format, perform
+`From ' escaping, generate auto-replying headers, do simple
+header munging/extracting or split up a
+mailbox/digest/articles file.  The mail/mailbox/article contents will be
+expected on stdin.
+.PP
+If formail is supposed to determine the sender of the mail, but is unable
+to find any, it will substitute `foo@bar'.
+.PP
+If formail is started without any command line options, it will force any
+mail coming from stdin into mailbox format and will escape
+.B all
+bogus `From ' lines with a `>'.
+.SH OPTIONS
+.TP 0.5i
+.B \-v
+Formail will print its version number and exit.
+.TP
+.B \-b
+Don't escape any bogus mailbox headers (i.e., lines starting with `From ').
+.TP
+.I "\fB\-p\fP prefix"
+Define a different quotation prefix.  If unspecified it defaults to `>'.
+.TP
+.B \-Y
+Assume traditional Berkeley mailbox format, ignoring any
+.B Content-Length:
+fields.
+.TP
+.B \-c
+Concatenate continued fields in the header.  Might be convenient when
+postprocessing mail with standard (line oriented) text utilities.
+.TP
+.B \-z
+Ensure a whitespace exists between field name and content.
+Zap fields which contain only a single whitespace character.
+Zap leading and trailing whitespace on fields extracted with
+.BR \-x .
+.TP
+.B \-f
+Force formail to simply pass along any non-mailbox format (i.e., don't
+generate a `From ' line as the first line).
+.TP
+.B \-r
+Generate an auto-reply header.  This will normally throw away all the existing
+fields (except X-Loop:) in the original message, fields you wish to preserve
+need to be named using the
+.B \-i
+option.  If you use this option in conjunction with
+.BR \-k ,
+you can prevent the body from being `escaped' by also specifying
+.BR \-b .
+.TP
+.B \-k
+When generating the auto-reply header or when extracting fields, keep
+the body as well.
+.TP
+.B \-t
+Trust the sender to have used a valid return address in his header.  This
+causes formail to select the
+.I header sender
+instead of the
+.I envelope sender
+for the reply.  This option should be used when generating auto-reply
+headers from news articles or when the sender of the message is
+expecting a reply.
+.TP
+.B \-s
+The input will be split up into separate mail messages, and piped into
+a program one by one (a new program is started for every part).
+.B \-s
+has to be the last option specified, the first argument following it is
+expected to be the name of a program, any other arguments will be
+passed along to it.  If you omit the program, then formail will simply
+concatenate the split mails on stdout again.  See
+.BR FILENO .
+.TP
+.I "\fB\-n\fP [maxprocs]"
+Tell formail not to wait for every program to finish before starting
+the next (causes splits to be processed in parallel).
+.I Maxprocs
+optionally specifies an upper limit on the number of concurrently
+running processes.
+.TP
+.B \-e
+Do not require empty lines to be preceding the header of a new message
+(i.e.,  the messages could start on every line).
+.TP
+.B \-d
+Tell formail that the messages it is supposed to split need not be in
+strict mailbox format (i.e., allows you to split digests/articles or
+non-standard mailbox formats).  This disables recognition of the
+.B Content-Length:
+field.
+.TP
+.B \-l folder
+Generate a log summary in the same style as procmail.  This includes
+the entire "From " line, the Subject: header field, the folder, and
+the size of the message in bytes.  The mailstat command can be used
+to summarize logs in this format.
+.TP
+.B \-B
+Makes formail assume that it is splitting up a BABYL rmail file.
+.TP
+.I "\fB\-m\fP minfields"
+Allows you to specify the number of consecutive headerfields formail
+needs to find before it decides it found the start of a new message, it
+defaults to 2.
+.TP
+.B \-q
+Tells formail to (still detect but) be quiet about write errors,
+duplicate messages and mismatched
+.B Content-Length:
+fields.  This option is on by default, to make it display the messages
+use
+.BR \-q\- .
+.TP
+.I "\fB\-D\fP maxlen idcache"
+Formail will detect if the Message-ID of the current message has
+already been seen using an
+.I idcache
+file of approximately
+.I maxlen
+size.  If not splitting, it will return success if a duplicate has been
+found.  If splitting, it will not output duplicate messages.  If used
+in conjunction with
+.BR \-r ,
+formail will look at the
+.I mail address
+of the envelope sender
+.I instead
+at the Message-ID.
+.TP
+.I "\fB\-x\fP headerfield"
+Extract the contents of this
+.I headerfield
+from the header.  Line continuations will be left intact; if you
+want the value on a single line then you'll also need the
+.B \-c
+option.
+.TP
+.I "\fB\-X\fP headerfield"
+Same as
+.BR \-x ,
+but also preserves/includes the field name.
+.TP
+.I "\fB\-a\fP headerfield"
+Append a custom
+.I headerfield
+onto the header; but only if a similar field does not exist yet.  If
+you specify either one of the field names
+.B Message-ID:
+or
+.B Resent-Message-ID:
+with no field contents, then formail will generate a unique message-ID
+for you.
+.TP
+.I "\fB\-A\fP headerfield"
+Append a custom
+.I headerfield
+onto the header in any case.
+.TP
+.I "\fB\-i\fP headerfield"
+Same as
+.BR \-A ,
+except that any existing similar fields are renamed by prepending an
+``Old-'' prefix.  If
+.I headerfield
+consists only of a field-name, it will not be appended.
+.TP
+.I "\fB\-I\fP headerfield"
+Same as
+.BR \-i ,
+except that any existing similar fields are simply removed.  If
+.I headerfield
+consists only of a field-name, it effectively deletes the field.
+.TP
+.I "\fB\-u\fP headerfield"
+Make the first occurrence of this field unique, and thus delete all
+subsequent occurrences of it.
+.TP
+.I "\fB\-U\fP headerfield"
+Make the last occurrence of this field unique, and thus delete all
+preceding occurrences of it.
+.TP
+.I "\fB\-R\fP oldfield newfield"
+Renames all occurrences of the fieldname
+.I oldfield
+into
+.IR newfield .
+.TP
+.I "\fB\+\fPskip"
+Skip the first
+.I skip
+messages while splitting.
+.TP
+.I "\fB\-\fPtotal"
+Output at most
+.I total
+messages while splitting.
+.SH NOTES
+When renaming, removing, or extracting fields, partial fieldnames may
+be used to specify all fields that start with the specified value.
+.PP
+By default, when generating an auto-reply header formail selects the
+envelope sender from the input message.  This is correct for vacation
+messages and other automatic replies regarding the routing or delivery
+of the original message.  If the sender is expecting a reply or the
+reply is being generated in response to the contents of the original
+message then the \-t option should be used.
+.PP
+.BR RFC822 ,
+the original standard governing the format of Internet mail
+messages, did not specify whether Resent header fields (those that
+begin with `Resent\-', such as `Resent\-From:') should be considered
+when generating a reply.  Since then, the recommended usage of the
+Resent headers has evolved to consider them as purely informational and
+not for use when generating a reply.  This has been codified in
+.BR RFC2822 ,
+the new Internet Message Format standard, which states in part:
+.IP
+Resent fields are used to identify a message as having been
+reintroduced into the transport system by a user.  The purpose of
+using resent fields is to have the message appear to the final
+recipient as if it were sent directly by the original sender, with
+all of the original fields remaining the same.\|\|.\|.\|.\|\|They
+MUST NOT be used in the normal processing of replies or other such
+automatic actions on messages.
+.PP
+While formail now
+ignores Resent headers when generating header replies, versions of
+formail prior to 3.14 gave such headers a high precedence.  If the old
+behavior is needed for established applications it can be specified by
+calling formail with the option `-a Resent-' in addition
+to the \-r and \-t options.  This usage is deprecated
+and should not be used in new applications.
+.SH ENVIRONMENT
+.TP .5i
+.B FILENO
+While splitting, formail assigns the message number currently being output to
+this variable.  By presetting FILENO, you can change the initial message
+number being used and the width of the zero-padded output.  If FILENO is
+unset it will default to 000.  If FILENO is non-empty and
+does not contain a number, FILENO generation is disabled.
+.SH EXAMPLES
+To split up a digest one usually uses:
+.RS
+formail +1 \-ds >>the_mailbox_of_your_choice
+.RE
+or
+.RS
+formail +1 \-ds procmail
+.RE
+.PP
+To remove all Received: fields from the header:
+.RS
+formail \-I Received:
+.RE
+.PP
+To remove all fields except From: and Subject: from the header:
+.RS
+formail \-k \-X From: \-X Subject:
+.RE
+.PP
+To supersede the Reply-To: field in a header you could use:
+.RS
+formail \-i "Reply-To: foo@bar"
+.RE
+.PP
+To convert a non-standard mailbox file into a standard mailbox file you can
+use:
+.RS
+formail \-ds <old_mailbox >>new_mailbox
+.RE
+.PP
+Or, if you have a very tolerant mailer:
+.RS
+formail \-a Date: \-ds <old_mailbox >>new_mailbox
+.RE
+.PP
+To extract the header from a message:
+.RS
+formail \-X ""
+.RE
+or
+.RS
+sed \-e '/^$/ q'
+.RE
+.PP
+To extract the body from a message:
+.RS
+formail \-I ""
+.RE
+or
+.RS
+sed \-e '1,/^$/ d'
+.RE
+.SH "SEE ALSO"
+.na
+.nh
+.BR mail (1),
+.BR sendmail (8),
+.BR procmail (1),
+.BR sed (1),
+.BR sh (1),
+.BR RFC822 ,
+.BR RFC2822 ,
+.B RFC1123
+.hy
+.ad
+.SH DIAGNOSTICS
+.TP 2.3i
+Can't fork
+Too many processes on this machine.
+.TP
+Content-Length: field exceeds actual length by nnn bytes
+The Content-Length: field in the header specified a length that was longer
+than the actual body.  This causes this message to absorb a number of
+subsequent messages following it in the same mailbox.
+.TP
+Couldn't write to stdout
+The program that formail was trying to pipe into didn't accept all the data
+formail sent to it; this diagnostic can be suppressed by the
+.B \-q
+option.
+.TP
+Duplicate key found: x
+The Message-ID or sender x in this message was found in the idcache; this
+diagnostic can be suppressed by the
+.B \-q
+option.
+.TP
+Failed to execute "x"
+Program not in path, or not executable.
+.TP
+File table full
+Too many open files on this machine.
+.TP
+Invalid field-name: "x"
+The specified field-name "x" contains control characters, or cannot be a
+partial field-name for this option.
+.SH WARNINGS
+You can save yourself and others a lot of grief if you try to avoid using
+this autoreply feature on mails coming through mailinglists.  Depending
+on the format of the incoming mail (which in turn depends on both the
+original sender's mail agent and the mailinglist setup) formail could
+decide to generate an autoreply header that replies to the list.
+.PP
+In the tradition of UN*X utilities, formail will do exactly what
+you ask it to, even if it results in a
+.RB non- RFC822
+compliant message.  In particular, formail will let you generate
+header fields whose name ends in a space instead of a colon.  While
+this is correct for the leading `From ' line, that line is not a
+header field so much as the message separator for the mbox mailbox
+format.  Multiple occurrences of such a line or any other colonless
+header field will be considered by many mail programs, including
+formail itself, as the beginning of a new message.  Others will
+consider the message to be corrupt.  Because of this, you should
+not use the
+.B \-i
+option with the `From ' line as the resulting renamed line,
+`Old-From ', will probably not do what you want it to.  If
+you want to save the original `From ' line, rename it with the
+.B \-R
+option to a legal header field such as `X-From_:'.
+.SH BUGS
+When formail has to generate a leading `From ' line it normally will contain
+the current date.  If formail is given the option `\-a Date:',
+it will use the date from the `Date:' field in the header (if present).
+However, since formail copies it verbatim, the format will differ from that
+expected by most mail readers.
+.PP
+If formail is instructed to delete or rename the leading `From ' line, it
+will not automatically regenerate it as usual.  To force formail to regenerate
+it in this case, include \fB\-a 'From '\fP.
+.PP
+If formail is not called as the first program in a pipe and it is told to
+split up the input in several messages, then formail will not terminate until
+the program it receives the input from closes its output or terminates itself.
+.PP
+If formail is instructed to generate an autoreply mail, it will
+.B never
+put more than one address in the `To:' field.
+.SH MISCELLANEOUS
+Formail is eight-bit clean.
+.PP
+When formail has to determine the sender's address, every
+.B RFC822
+conforming
+mail address is allowed.  Formail will always strip down the address to
+its minimal form (deleting excessive comments and whitespace).
+.PP
+The regular expression that is used to find `real' postmarks is:
+.RS
+"\en\enFrom [\et ]*[^\et\en ]+[\et ]+[^\en\et ]"
+.RE
+.PP
+If a
+.B Content-Length:
+field is found in a header, formail will copy the number of specified bytes in
+the body verbatim before resuming the regular scanning for message boundaries
+(except when splitting digests or Berkeley mailbox format is assumed).
+.PP
+Any header lines immediately following the leading `From ' line
+that start with `>From ' are considered to be a continuation
+of the `From ' line.  If instructed to rename the `From ' line,
+formail will change each leading `>' into a space, thereby
+transforming those lines into normal
+.B RFC822
+continuations.
+.SH NOTES
+Calling up formail with the \-h or \-? options will cause
+it to display a command-line help page.
+.Sh SOURCE
+This program is part of the
+.I procmail mail-processing-package
+(v3.24) available at http://www.procmail.org/ or
+ftp.procmail.org in
+.BR pub/procmail/ .
+.Sh MAILINGLIST
+There exists a mailinglist for questions relating to any program in the
+procmail package:
+.RS
+<procmail-users@procmail.org>
+.RS
+for submitting questions/answers.
+.RE
+<procmail-users-request@procmail.org>
+.RS
+for subscription requests.
+.RE
+.PP
+.RE
+If you would like to stay informed about new versions and official patches send
+a subscription request to
+.RS
+procmail-announce-request@procmail.org
+.RE
+(this is a readonly list).
+.SH AUTHORS
+Stephen R. van den Berg
+.RS
+<srb@cuci.nl>
+.RE
+.\".if n .pl -(\n(.tu-1i)
+.rm SH
+.rn Sh SH
+.rm SS
+.rn Ss SS
+.rm TP
+.rn Tp TP
+.rm RS
+.rn Rs RS
+.rm RE
+.rn Re RE
diff --git a/upstream/mageia-cauldron/man1/fstopgm.1 b/upstream/mageia-cauldron/man1/fstopgm.1
new file mode 100644
index 00000000..7316b3b2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fstopgm.1
@@ -0,0 +1,98 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Fstopgm User Manual" 0 "06 April 89" "netpbm documentation"
+
+.SH NAME
+fstopgm - convert a Usenix FaceSaver(tm) file into a PGM image
+
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBfstopgm\fP
+[\fIfsfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBfstopgm\fP reads a Usenix FaceSaver(tm) file as input and
+produces a PGM image as output.
+.PP
+FaceSaver(tm) files sometimes have rectangular pixels.  While
+\fBfstopgm\fP won't re-scale them into square pixels for you, it will
+give you the precise \fBpamscale\fP command that will do the job.
+Because of this, reading a FaceSaver(tm) image is a two-step process.
+First you do:
+
+.nf
+  fstopgm > /dev/null
+
+.fi
+
+This will tell you whether you need to use \fBpamscale.\fP
+
+Then use one of the following pipelines:
+.nf
+  fstopgm | pnmnorm
+  fstopgm | pamscale -whatever | pnmnorm
+
+.fi
+
+To go to PBM, you want something more like one of these:
+.nf
+  fstopgm | pamenlarge 3 | pnmnorm | pamditherbw
+  fstopgm | pamenlarge 3 | pamscale <whatever> | pnmnorm | pamditherbw
+
+.fi
+
+You want to enlarge when going to a bitmap because otherwise you lose
+information; but enlarging by more than 3 does not look good.
+.PP
+FaceSaver is a registered trademark of Metron Computerware Ltd. of
+Oakland, CA.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBfstopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtofs" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pnmnorm" (1)\c
+\&,
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamditherbw" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/fstopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/funzip.1 b/upstream/mageia-cauldron/man1/funzip.1
new file mode 100644
index 00000000..30206e4b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/funzip.1
@@ -0,0 +1,127 @@
+.\"  Copyright (c) 1990-2009 Info-ZIP.  All rights reserved.
+.\"
+.\"  See the accompanying file LICENSE, version 2009-Jan-02 or later
+.\"  (the contents of which are also included in unzip.h) for terms of use.
+.\"  If, for some reason, all these files are missing, the Info-ZIP license
+.\"  also may be found at:  ftp://ftp.info-zip.org/pub/infozip/license.html
+.\"
+.\" funzip.1 by Greg Roelofs and others.
+.\"
+.\" =========================================================================
+.\" define .EX/.EE (for multiline user-command examples; normal Courier font)
+.de EX
+.in +4n
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.fi
+.in -4n
+..
+.\" =========================================================================
+.TH FUNZIP 1L "20 April 2009 (v3.95)" "Info-ZIP"
+.SH NAME
+funzip \- filter for extracting from a ZIP archive in a pipe
+.PD
+.SH SYNOPSIS
+\fBfunzip\fP [\fB\-password\fP] [\fIinput[.zip|.gz]\fP]
+.\" =========================================================================
+.SH ARGUMENTS
+.IP [\fI\-password\fP]
+Optional password to be used if ZIP archive is encrypted.  Decryption
+may not be supported at some sites.  See DESCRIPTION for more details.
+.IP [\fIinput[.zip|.gz]\fP]
+Optional input archive file specification. See DESCRIPTION for details.
+.PD
+.\" =========================================================================
+.SH DESCRIPTION
+.I funzip
+without a file argument acts as a filter; that is, it assumes that a
+ZIP archive (or a \fIgzip\fP'd(1) file) is being piped into
+standard input, and it extracts the first member from the archive to stdout.
+When stdin comes from a tty device,
+.I funzip
+assumes that this cannot be a stream of (binary) compressed data and
+shows a short help text, instead.
+If there is a file argument, then input is read from the specified file
+instead of from stdin.
+.PP
+A password for encrypted zip files can be specified
+on the command line (preceding the file name, if any) by prefixing the
+password with a dash.  Note that this constitutes a security risk on many
+systems; currently running processes are often visible via simple commands
+(e.g., \fIps\fP(1) under Unix), and command-line histories can be read.
+If the first entry of the zip file is encrypted and
+no password is specified on the command line, then the user is prompted for
+a password and the password is not echoed on the console.
+.PP
+Given the limitation on single-member extraction, \fIfunzip\fP is most
+useful in conjunction with a secondary archiver program such as \fItar\fP(1).
+The following section includes an example illustrating this usage in the
+case of disk backups to tape.
+.PD
+.\" =========================================================================
+.SH EXAMPLES
+To use \fIfunzip\fP to extract the first member file of the archive test.zip
+and to pipe it into \fImore\fP(1):
+.PP
+.EX
+funzip test.zip | more
+.EE
+.PP
+To use \fIfunzip\fP to test the first member file of test.zip (any errors
+will be reported on standard error):
+.PP
+.EX
+funzip test.zip > /dev/null
+.EE
+.PP
+To use \fIzip\fP and \fIfunzip\fP in place of \fIcompress\fP(1) and
+\fIzcat\fP(1) (or \fIgzip\fP(1L) and \fIgzcat\fP(1L)) for tape backups:
+.PP
+.EX
+tar cf \- . | zip \-7 | dd of=/dev/nrst0 obs=8k
+dd if=/dev/nrst0 ibs=8k | funzip | tar xf \-
+.EE
+.PP
+(where, for example, nrst0 is a SCSI tape drive).
+.PD
+.\" =========================================================================
+.SH BUGS
+When piping an encrypted file into \fImore\fP and allowing \fIfunzip\fP
+to prompt for password, the terminal may sometimes be reset to a non-echo
+mode.  This is apparently due to a race condition between the two programs;
+\fIfunzip\fP changes the terminal mode to non-echo before \fImore\fP reads
+its state, and \fImore\fP then ``restores'' the terminal to this mode before
+exiting.  To recover, run \fIfunzip\fP on the same file but redirect to
+/dev/null rather than piping into more; after prompting again for the
+password, \fIfunzip\fP will reset the terminal properly.
+.PP
+There is presently no way to extract any member but the first from a ZIP
+archive.  This would be useful in the case where a ZIP archive is included
+within another archive.  In the case where the first member is a directory,
+\fIfunzip\fP simply creates the directory and exits.
+.PP
+The functionality of \fIfunzip\fP should be incorporated into \fIunzip\fP
+itself (future release).
+.PD
+.\" =========================================================================
+.SH "SEE ALSO"
+\fIgzip\fP(1L), \fIunzip\fP(1L), \fIunzipsfx\fP(1L), \fIzip\fP(1L),
+\fIzipcloak\fP(1L), \fIzipinfo\fP(1L), \fIzipnote\fP(1L), \fIzipsplit\fP(1L)
+.PD
+.\" =========================================================================
+.SH URL
+The Info-ZIP home page is currently at
+.EX
+\fChttp://www.info-zip.org/pub/infozip/\fR
+.EE
+or
+.EX
+\fCftp://ftp.info-zip.org/pub/infozip/\fR .
+.EE
+.PD
+.\" =========================================================================
+.SH AUTHOR
+Mark Adler (Info-ZIP)
diff --git a/upstream/mageia-cauldron/man1/fuse2fs.1 b/upstream/mageia-cauldron/man1/fuse2fs.1
new file mode 100644
index 00000000..6b1f2136
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/fuse2fs.1
@@ -0,0 +1,79 @@
+.\" -*- nroff -*-
+.\" Copyright 1993, 1994, 1995 by Theodore Ts'o.  All Rights Reserved.
+.\" This file may be copied under the terms of the GNU Public License.
+.\"
+.TH FUSE2FS 1 "February 2023" "E2fsprogs version 1.47.0"
+.SH NAME
+fuse2fs \- FUSE file system client for ext2/ext3/ext4 file systems
+.SH SYNOPSIS
+.B fuse2fs
+[
+.B device/image
+]
+[
+.B mountpoint
+]
+[
+.I options
+]
+.SH DESCRIPTION
+.B fuse2fs
+is a FUSE file system client that supports reading and writing from
+devices or image files containing ext2, ext3, and ext4 file systems.
+.SH OPTIONS
+.SS "general options:"
+.TP
+\fB\-o\fR opt,[opt...]
+mount options
+.TP
+\fB\-h\fR   \fB\-\-help\fR
+print help
+.TP
+\fB\-V\fR   \fB\-\-version\fR
+print version
+.SS "fuse2fs options:"
+.TP
+\fB-o\fR ro
+read-only mount
+.TP
+\fB-o\fR errors=panic
+dump core on error
+.TP
+\fB-o\fR minixdf
+minix-style df
+.TP
+\fB-o\fR fakeroot
+pretend to be root for permission checks
+.TP
+\fB-o\fR no_default_opts
+do not include default fuse options
+.TP
+\fB-o\fR norecovery
+do not replay the journal and mount the file system read-only
+.TP
+\fB-o\fR fuse2fs_debug
+enable fuse2fs debugging
+.SS "FUSE options:"
+.TP
+\fB-d -o\fR debug
+enable debug output (implies -f)
+.TP
+\fB-f\fR
+foreground operation
+.TP
+\fB-s\fR
+disable multi-threaded operation
+.P
+For other FUSE options please see
+.BR mount.fuse (8)
+or see the output of
+.I fuse2fs \-\-helpfull
+.SH AVAILABILITY
+.B fuse2fs
+is part of the e2fsprogs package and is available from
+http://e2fsprogs.sourceforge.net.
+.SH SEE ALSO
+.BR ext4 (5)
+.BR e2fsck (8),
+.BR mount.fuse (8)
+
diff --git a/upstream/mageia-cauldron/man1/g3topbm.1 b/upstream/mageia-cauldron/man1/g3topbm.1
new file mode 100644
index 00000000..e13eae9b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/g3topbm.1
@@ -0,0 +1,154 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "G3topbm User Manual" 0 "03 December 2008" "netpbm documentation"
+
+.SH NAME
+g3topbm - convert a Group 3 fax file into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBg3topbm\fP
+[\fB-kludge\fP]
+[\fB-reversebits\fP]
+[\fB-stretch\fP]
+[\fB-width=\fP\fIpixels\fP | paper_size={A3|A4|A5|A6|B4}]
+[\fB-stop_error\fP]
+[\fIg3file\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBg3topbm\fP reads a Group 3 fax file with MH (Modified Huffman)
+compression as input and produces a PBM image as output.
+.PP
+\fBg3topbm\fP tolerates various deviations from the standard,
+so as to recover some of the image if there was a transmission error.
+One thing it tolerates is lines of varying length.  The standard requires
+all the lines to be the same length; \fBg3topbm\fP makes the output
+image as wide as the longest line in the input and pads the others on
+the right.  It warns you when it does this.
+.PP
+You can use the \fBstop_error\fP option to make \fBg3topbm\fP
+insist on valid input.
+.PP
+There is no Netpbm program that understands the other G3 fax
+compression methods: MR (Modified Read) and MMR (Modified Modified Read).
+.PP
+Note that the Group 3 fax file format does not include any kind of a
+signature so that \fBg3topbm\fP might verify it's actually looking at a G3
+file or that the compression method is MH.  The program will interpret any
+sequence of bytes you give it as if it is G3 and, while typically issuing a
+lot of error messages about the file not conforming to the G3 MH format, will
+produce output (unless you use
+\fB-stoperror\fP).  In particular, if you feed \fBg3topbm\fP an MR or MMR
+file, it will not tell you of your mistake.
+.PP
+There are subformats of TIFF that use the Group 3 fax encodings
+inside.  See \fBtifftopnm\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBg3topbm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-kludge\fP
+Tells \fBg3topbm\fP to ignore the first few lines of the file;
+sometimes fax files have some junk at the beginning.
+
+.TP
+\fB-reversebits\fP
+Tells \fBg3topbm\fP to interpret bits least-significant first,
+instead of the default most-significant first.  Apparently some fax
+modems do it one way and others do it the other way.  If you get a
+whole bunch of "bad code word" messages, try using this
+option.
+
+.TP
+\fB-stretch\fP
+This option tells \fBg3topbm\fP to stretch the image vertically by
+duplicating each row.  This is for the low-quality transmission mode.
+
+.TP
+\fB-width=\fP\fIpixels\fP
+This option tells \fBg3topbm\fP that the image is supposed to be
+\fIpixels\fP pixels wide.  If any line in it is not that size, \fBg3topbm\fP
+issues a warning or fails, depending on whether you specify
+\fB-stop_error\fP.
+.sp
+You cannot specify both \fB-width\fP and \fB-paper_size\fP.
+.sp
+This option was new in Netpbm 10.33 (March 2006).
+
+.TP
+\fB-paper_size=\fP{\fBA3\fP,\fBA4\fP,\fBA5\fP,\fBA6\fP,\fBB4\fP}
+This option tells \fBg3topbm\fP for what size paper this image is
+supposed to be formatted.  \fBg3topbm\fP uses the width of the paper
+the same way as with the \fB-width\fP option.  \fBg3topbm\fP
+does not use the height of the paper for anything.
+.sp
+You cannot specify both \fB-width\fP and \fB-paper_size\fP.
+.sp
+This option was new in Netpbm 10.33 (March 2006).
+
+.TP
+\fB-stop_error\fP
+This option tells \fBg3topbm\fP to fail when it finds a problem
+in the input.  "Fail" means it terminates with a nonzero
+status code with the contents of the output file undefined.
+.sp
+If you don't specify this option, \fBg3topbm\fP does its best to
+work around input errors and salvage as much of the image as possible
+in the output image.  It first tries to resynchronize to a later line
+by searching for the next End Of Line marker, skipping any lines or
+partial lines in between.  It saves the beginning of the line in which
+it encountered the problem.  If the input file ends prematurely,
+\fBg3topbm\fP produces output containing the lines up to where it
+encountered the problem.
+.sp
+\fBg3topbm\fP issues warning messages when it continues in spite of
+input errors.
+.sp
+This option was new in Netpbm 10.24 (August 2004).  Before that,
+\fBg3topbm\fP always failed when it encountered premature EOF and
+never failed when it encountered other problems.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtog3" (1)\c
+\&,
+.BR "tifftopnm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "fax formats" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/g3topbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/gamma4scanimage.1 b/upstream/mageia-cauldron/man1/gamma4scanimage.1
new file mode 100644
index 00000000..2efe6783
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gamma4scanimage.1
@@ -0,0 +1,82 @@
+.TH gamma4scanimage 1 "10 Jul 2008" "" "SANE Scanner Access Now Easy"
+.IX gamma4scanimage
+.SH NAME
+gamma4scanimage \- create a gamma table for scanimage
+.SH SYNOPSIS
+.B gamma4scanimage
+.I gamma
+.RI [ shadow
+.RI [ highlight
+.RI [ maxin
+.RI [ maxout ]]]]
+
+.SH DESCRIPTION
+The tool
+.B gamma4scanimage
+creates a gamma table in the format expected by scanimage. You can define a
+.BR gamma,
+a
+.BR shadow
+and a
+.BR highlight
+value. You also can specify the size
+.RB ( maxin )
+and maximum output value
+.RB ( maxout )
+of the gamma table.
+.PP
+.BR gamma
+is a floating point value, neutral value being 1.0. If the value is larger than
+1.0 then the image is brighter.
+.PP
+.BR shadow
+defines the minimum input value that is necessary to create an output value
+larger than zero.  shadow has to be in the range
+.RB "[0.." "maxin" "]."
+Its default value is 0.
+.PP
+.BR highlight
+defines the maximum input value that produces an output value smaller than
+maxout.  highlight must be in the range
+.RB "[0.." "maxin" "]"
+and
+larger than shadow. Its default value is the same as
+.B maxin
+(16383 if not set).
+.PP
+.B maxin
+defines the size of the gamma table. The size depends on the scanner/backend.
+If the scanner uses 8 bit gamma input then
+.B maxin
+must be set to 255, 1023 for 10
+bits, 4095 for 12 bits, and 16383 for 14 bits. The default is 16383.  To find
+out what value
+.B maxin
+has to be, call
+.BR scanimage (1)
+with a very large gamma table
+[0]0-[99999]255 and
+.BR scanimage (1)
+will print an error message with the needed gamma table size.
+.PP
+.B maxout
+defines the maximum output value. Take a look at the output of
+.I scanimage \-h
+to find out what
+.B maxout
+must be. The default value is 255.
+.PP
+.SH EXAMPLE
+scanimage \-\-custom\-gamma=yes \-\-gamma\-table
+`gamma4scanimage 1.8 0 11500 16383 255`
+>image.pnm
+
+.SH SEE ALSO
+.BR sane (7),
+.BR scanimage (1)
+
+.SH AUTHOR
+Oliver Rauch
+
+.SH EMAIL-CONTACT
+.I Oliver.Rauch@Rauch-Domain.DE
diff --git a/upstream/mageia-cauldron/man1/gawk.1 b/upstream/mageia-cauldron/man1/gawk.1
new file mode 100644
index 00000000..8bdda3b0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gawk.1
@@ -0,0 +1,2513 @@
+.ds PX \s-1POSIX\s+1
+.ds UX \s-1UNIX\s+1
+.ds GN \s-1GNU\s+1
+.ds AK \s-1AWK\s+1
+.ds EP \fIGAWK: Effective AWK Programming\fP
+.if !\n(.g \{\
+.	if !\w|\*(lq| \{\
+.		ds lq ``
+.		if \w'\(lq' .ds lq "\(lq
+.	\}
+.	if !\w|\*(rq| \{\
+.		ds rq ''
+.		if \w'\(rq' .ds rq "\(rq
+.	\}
+.\}
+.TH GAWK 1 "Nov 02 2023" "Free Software Foundation" "Utility Commands"
+.SH NAME
+gawk \- pattern scanning and processing language
+.SH SYNOPSIS
+.B gawk
+[ \*(PX or \*(GN style options ]
+.B \-f
+.I program-file
+[
+.B \-\^\-
+] file .\|.\|.
+.br
+.B gawk
+[ \*(PX or \*(GN style options ]
+[
+.B \-\^\-
+]
+.I program-text
+file .\|.\|.
+.SH DESCRIPTION
+.I Gawk
+is the \*(GN Project's implementation of the \*(AK programming language.
+It conforms to the definition of the language in
+the \*(PX 1003.1 standard.
+This version in turn is based on the description in
+.IR "The AWK Programming Language" ,
+by Aho, Kernighan, and Weinberger.
+.I Gawk
+provides the additional features found in the current version
+of Brian Kernighan's
+.I awk
+and numerous \*(GN-specific extensions.
+.PP
+The command line consists of options to
+.I gawk
+itself, the \*(AK program text (if not supplied via the
+.B \-f
+or
+.B \-\^\-include
+options), and values to be made
+available in the
+.B ARGC
+and
+.B ARGV
+pre-defined \*(AK variables.
+.SH PREFACE
+This manual page is intentionally as terse as possible.
+Full details are provided in \*(EP, and you should look
+there for the full story on any specific feature.
+Where possible, links to the online version of the manual
+are provided.
+.SH OPTION FORMAT
+.I Gawk
+options may be either traditional \*(PX-style one letter options,
+or \*(GN-style long options.  \*(PX options start with a single \*(lq\-\*(rq,
+while long options start with \*(lq\-\^\-\*(rq.
+Long options are provided for both \*(GN-specific features and
+for \*(PX-mandated features.
+.PP
+.IR Gawk -specific
+options are typically used in long-option form.
+Arguments to long options are either joined with the option
+by an
+.B =
+sign, with no intervening spaces, or they may be provided in the
+next command line argument.
+Long options may be abbreviated, as long as the abbreviation
+remains unique.
+.PP
+Additionally, every long option has a corresponding short
+option, so that the option's functionality may be used from
+within
+.B #!
+executable scripts.
+.SH OPTIONS
+.I Gawk
+accepts the following options.
+Standard options are listed first, followed by options for
+.I gawk
+extensions, listed alphabetically by short option.
+.TP
+.BI \-f " program-file\fR,\fP " \-\^\-file " program-file"
+Read the \*(AK program source from the file
+.IR program-file ,
+instead of from the first command line argument.
+Multiple
+.B \-f
+options may be used.
+Files read with
+.B \-f
+are treated as if they begin with an implicit \fB@namespace "awk"\fR statement.
+.TP
+.BI \-F " fs\fR, \fP" \-\^\-field-separator " fs"
+Use
+.I fs
+for the input field separator (the value of the
+.B FS
+predefined
+variable).
+.TP
+\fB\-v\fI var\fB\^=\^\fIval\fR, \fB\-\^\-assign \fIvar\fB\^=\^\fIval\fR
+Assign the value
+.I val
+to the variable
+.IR var ,
+before execution of the program begins.
+Such variable values are available to the
+.B BEGIN
+rule of an \*(AK program.
+.TP
+.BR \-b ", " \-\^\-characters\-as\-bytes
+Treat all input data as single-byte characters.
+The
+.B \-\^\-posix
+option overrides this one.
+.TP
+.BR \-c ", " \-\^\-traditional
+Run in
+.I compatibility
+mode.  In compatibility mode,
+.I gawk
+behaves identically to Brian Kernighan's
+.IR awk ;
+none of the \*(GN-specific extensions are recognized.
+.TP
+.BR \-C ", " \-\^\-copyright
+Print the short version of the \*(GN copyright information message on
+the standard output and exit successfully.
+.TP
+\fB\-d\fR[\fIfile\fR], \fB\-\^\-dump-variables\fR[\fB=\fIfile\fR]
+Print a sorted list of global variables, their types and final values to
+.IR file .
+The default file is
+.B awkvars.out
+in the current directory.
+.TP
+\fB\-D\fR[\fIfile\fR], \fB\-\^\-debug\fR[\fB=\fIfile\fR]
+Enable debugging of \*(AK programs.
+By default, the debugger reads commands interactively from the keyboard
+(standard input).
+The optional
+.I file
+argument specifies a file with a list
+of commands for the debugger to execute non-interactively.
+.sp .5
+In this mode of execution,
+.I gawk
+loads the
+AWK source code and then prompts for debugging commands.
+.I Gawk
+can only debug AWK program source provided with the
+.B \-f
+and
+.B \-\^\-include
+options.
+The debugger is documented in \*(EP; see
+.IR https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger .
+.TP
+.BI \-e " program-text\fR, \fP" \-\^\-source " program-text"
+Use
+.I program-text
+as \*(AK program source code.
+Each argument supplied via
+.B \-e
+is treated as if it begins with an implicit \fB@namespace "awk"\fR statement.
+.TP
+\fB\-E \fIfile\fR, \fB\-\^\-exec \fIfile\fR
+Similar to
+.BR \-f ,
+however, this option is the last one processed.
+This should be used with
+.B #!
+scripts, particularly for CGI applications, to avoid
+passing in options or source code (!) on the command line
+from a URL.
+This option disables command-line variable assignments.
+.TP
+.BR \-g ", " \-\^\-gen\-pot
+Scan and parse the \*(AK program, and generate a \*(GN
+.B \&.pot
+(Portable Object Template)
+format file on standard output with entries for all localizable
+strings in the program.  The program itself is not executed.
+.TP
+.BR \-h ", " \-\^\-help
+Print a relatively short summary of the available options on
+the standard output.
+Per the
+.IR "GNU Coding Standards" ,
+these options cause an immediate, successful exit.
+.TP
+\fB\-i \fIinclude-file\fR, \fB\-\^\-include \fIinclude-file\fR
+Load an awk source library.
+This searches for the library using the
+.B AWKPATH
+environment variable.  If the initial search fails, another attempt will
+be made after appending the
+.B \&.awk
+suffix.  The file will be loaded only
+once (i.e., duplicates are eliminated), and the code does not constitute
+the main program source.
+Files read with
+.B \-\^\-include
+are treated as if they begin with an implicit \fB@namespace "awk"\fR statement.
+.TP
+.BR \-I ", " \-\^\-trace
+Print the internal byte code names as they are executed when running
+the program. The trace is printed to standard error. Each ``op code''
+is preceded by a
+.B +
+sign in the output.
+.TP
+\fB\-k\fR, \fB\-\^\-csv\fR
+Enable CSV special processing.
+See
+.BR "Comma Separated Values" ,
+below, for more detail.
+.TP
+.BI \-l " lib\fR, " \-\^\-load " lib"
+Load a
+.I gawk
+extension from the shared library
+.IR lib .
+This searches for the library using the
+.B AWKLIBPATH
+environment variable.  If the initial search fails, another attempt will
+be made after appending the default shared library suffix for the platform.
+The library initialization routine is expected to be named
+.BR dl_load() .
+.TP
+\fB\-L \fR[\fIvalue\fR], \fB\-\^\-lint\fR[\fB=\fIvalue\fR]
+Provide warnings about constructs that are
+dubious or non-portable to other \*(AK implementations.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options
+for the list of possible values for
+.IR value .
+.TP
+.BR \-M ", " \-\^\-bignum
+Force arbitrary precision arithmetic on numbers. This option has
+no effect if
+.I gawk
+is not compiled to use the GNU MPFR and GMP libraries.
+(In such a case,
+.I gawk
+issues a warning.)
+.sp
+.B NOTE:
+This feature is
+.IR "on parole" .
+The primary
+.I gawk
+maintainer is no longer supporting it, although there is
+a member of the development team who is. If this situation
+changes, the feature
+will be removed from
+.IR gawk .
+.ig
+Set
+.B GAWK_NO_MPFR_WARN
+in the environment to silence the warning.
+..
+.TP
+.BR \-n ", " \-\^\-non\-decimal\-data
+Recognize octal and hexadecimal values in input data.
+.I "Use this option with great caution!"
+.TP
+.BR \-N ", " \-\^\-use\-lc\-numeric
+Force
+.I gawk
+to use the locale's decimal point character when parsing input data.
+.ig
+.\" This option is left undocumented, on purpose.
+.TP
+.BR "\-W nostalgia" ", " \-\^\-nostalgia
+Provide a moment of nostalgia for long time
+.I awk
+users.
+..
+.TP
+\fB\-o\fR[\fIfile\fR], \fB\-\^\-pretty-print\fR[\fB=\fIfile\fR]
+Output a pretty printed version of the program to
+.IR file .
+The default file is
+.B awkprof.out
+in the current directory.
+This option implies
+.BR \-\^\-no\-optimize .
+.TP
+.BR \-O ", " \-\^\-optimize
+Enable
+.IR gawk 's
+default optimizations upon the internal representation of the program.
+This option is on by default.
+.TP
+\fB\-p\fR[\fIprof-file\fR], \fB\-\^\-profile\fR[\fB=\fIprof-file\fR]
+Start a profiling session, and send the profiling data to
+.IR prof-file .
+The default is
+.B awkprof.out
+in the current directory.
+The profile contains execution counts of each statement in the program
+in the left margin and function call counts for each user-defined function.
+.I Gawk
+runs more slowly in this mode.
+This option implies
+.BR \-\^\-no\-optimize .
+.TP
+.BR \-P ", " \-\^\-posix
+This turns on
+.I compatibility
+mode, and disables a number of common extensions.
+.TP
+.BR \-r ", " \-\^\-re\-interval
+Enable the use of
+.I "interval expressions"
+in regular expression matching.
+Interval expressions
+are enabled by default, but this option remains for backwards compatibility.
+.TP
+.BR \-s ", " \-\^\-no\-optimize
+Disable
+.IR gawk 's
+default optimizations upon the internal representation of the program.
+.TP
+.BR \-S ", " \-\^\-sandbox
+Run
+.I gawk
+in sandbox mode, disabling the
+.B system()
+function, input redirection with
+.BR getline ,
+output redirection with
+.BR print " and " printf ,
+and loading dynamic extensions.
+Command execution (through pipelines) is also disabled.
+.TP
+.BR \-t ", " \-\^\-lint\-old
+Provide warnings about constructs that are
+not portable to the original version of \*(UX
+.IR awk .
+.TP
+.BR \-V ", " \-\^\-version
+Print version information for this particular copy of
+.I gawk
+on the standard output.
+This is useful when reporting bugs.
+Per the
+.IR "GNU Coding Standards" ,
+these options cause an immediate, successful exit.
+.TP
+.B \-\^\-
+Signal the end of options. This is useful to allow further arguments to the
+\*(AK program itself to start with a \*(lq\-\*(rq.
+.PP
+In compatibility mode,
+any other options are flagged as invalid, but are otherwise ignored.
+In normal operation, as long as program text has been supplied, unknown
+options are passed on to the \*(AK program in the
+.B ARGV
+array for processing.
+.PP
+For \*(PX compatibility, the
+.B \-W
+option may be used, followed by the name of a long option.
+.SH AWK PROGRAM EXECUTION
+An \*(AK program consists of a sequence of
+optional directives,
+pattern-action statements,
+and optional function definitions.
+.RS
+.PP
+\fB@include "\fIfilename\^\fB"
+.br
+\fB@load "\fIfilename\^\fB"
+.br
+\fB@namespace "\fIname\^\fB"
+.br
+\fIpattern\fB	{ \fIaction statements\fB }\fR
+.br
+\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR
+.RE
+.PP
+.I Gawk
+first reads the program source from the
+.IR program-file (s)
+if specified,
+from arguments to
+.BR \-\^\-source ,
+or from the first non-option argument on the command line.
+The
+.B \-f
+and
+.B \-\^\-source
+options may be used multiple times on the command line.
+.I Gawk
+reads the program text as if all the
+.IR program-file s
+and command line source texts
+had been concatenated together.
+.PP
+In addition, lines beginning with
+.B @include
+may be used to include other source files into your program.
+This is equivalent
+to using the
+.B \-\^\-include
+option.
+.PP
+Lines beginning with
+.B @load
+may be used to load extension functions into your program.  This is equivalent
+to using the
+.B \-\^\-load
+option.
+.PP
+The environment variable
+.B AWKPATH
+specifies a search path to use when finding source files named with
+the
+.B \-f
+and
+.B \-\^\-include
+options.  If this variable does not exist, the default path is
+\fB".:/usr/local/share/awk"\fR.
+(The actual directory may vary, depending upon how
+.I gawk
+was built and installed.)
+If a file name given to the
+.B \-f
+option contains a \*(lq/\*(rq character, no path search is performed.
+.PP
+The environment variable
+.B AWKLIBPATH
+specifies a search path to use when finding source files named with
+the
+.B \-\^\-load
+option.  If this variable does not exist, the default path is
+\fB"/usr/local/lib/gawk"\fR.
+(The actual directory may vary, depending upon how
+.I gawk
+was built and installed.)
+.PP
+.I Gawk
+executes \*(AK programs in the following order.
+First,
+all variable assignments specified via the
+.B \-v
+option are performed.
+Next,
+.I gawk
+compiles the program into an internal form.
+Then,
+.I gawk
+executes the code in the
+.B BEGIN
+rule(s) (if any),
+and then proceeds to read
+each file named in the
+.B ARGV
+array (up to
+.BR ARGV[ARGC\-1] ).
+If there are no files named on the command line,
+.I gawk
+reads the standard input.
+.PP
+If a filename on the command line has the form
+.IB var = val
+it is treated as a variable assignment.  The variable
+.I var
+will be assigned the value
+.IR val .
+(This happens after any
+.B BEGIN
+rule(s) have been run.)
+.PP
+If the value of a particular element of
+.B ARGV
+is empty (\fB""\fR),
+.I gawk
+skips over it.
+.PP
+For each input file,
+if a
+.B BEGINFILE
+rule exists,
+.I gawk
+executes the associated code
+before processing the contents of the file. Similarly,
+.I gawk
+executes
+the code associated with
+.B ENDFILE
+rules
+after processing the file.
+.PP
+For each record in the input,
+.I gawk
+tests to see if it matches any
+.I pattern
+in the \*(AK program.
+For each pattern that the record matches,
+.I gawk
+executes the associated
+.IR action .
+The patterns are tested in the order they occur in the program.
+.PP
+Finally, after all the input is exhausted,
+.I gawk
+executes the code in the
+.B END
+rule(s) (if any).
+.SS Command Line Directories
+According to POSIX, files named on the
+.I awk
+command line must be
+text files.  The behavior is ``undefined'' if they are not.  Most versions
+of
+.I awk
+treat a directory on the command line as a fatal error.
+.PP
+For
+.IR gawk ,
+a directory on the command line
+produces a warning, but is otherwise skipped.  If either of the
+.B \-\^\-posix
+or
+.B \-\^\-traditional
+options is given, then
+.I gawk
+reverts to
+treating directories on the command line as a fatal error.
+.SH VARIABLES, RECORDS AND FIELDS
+\*(AK variables are dynamic; they come into existence when they are
+first used.  Their values are either floating-point numbers or strings,
+or both,
+depending upon how they are used.
+Additionally,
+.I gawk
+allows variables to have regular-expression type.
+\*(AK also has one dimensional
+arrays; arrays with multiple dimensions may be simulated.
+However,
+.I gawk
+provides true arrays of arrays.
+Several pre-defined variables are set as a program
+runs; these are described as needed and summarized below.
+.SS Records
+Normally, records are separated by newline characters.  You can control how
+records are separated by assigning values to the built-in variable
+.BR RS .
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Records.html
+for the details.
+.SS Fields
+As each input record is read,
+.I gawk
+splits the record into
+.IR fields ,
+using the value of the
+.B FS
+variable as the field separator.
+Additionally,
+.B FIELDWIDTHS
+and
+.B FPAT
+may be used to control input field splitting.
+See the details, starting at
+.IR https://www.gnu.org/software/gawk/manual/html_node/Fields.html .
+.PP
+Each field in the input record may be referenced by its position:
+.BR $1 ,
+.BR $2 ,
+and so on.
+.B $0
+is the whole record,
+including leading and trailing whitespace.
+.PP
+The variable
+.B NF
+is set to the total number of fields in the input record.
+.PP
+References to non-existent fields (i.e., fields after
+.BR $NF )
+produce the null string.  However, assigning to a non-existent field
+(e.g.,
+.BR "$(NF+2) = 5" )
+increases the value of
+.BR NF ,
+creates any intervening fields with the null string as their values, and
+causes the value of
+.B $0
+to be recomputed, with the fields being separated by the value of
+.BR OFS .
+References to negative numbered fields cause a fatal error.
+Decrementing
+.B NF
+causes the values of fields past the new value to be lost, and the value of
+.B $0
+to be recomputed, with the fields being separated by the value of
+.BR OFS .
+.PP
+Assigning a value to an existing field
+causes the whole record to be rebuilt when
+.B $0
+is referenced.
+Similarly, assigning a value to
+.B $0
+causes the record to be resplit, creating new
+values for the fields.
+.SS Comma Separated Values
+When invoked with ether the
+.B \-k
+or the
+.B \-\^\-csv
+option,
+.I gawk
+does not use regular record determination and field splitting
+as described above.
+Instead, records are terminated by unquoted newlines, and
+fields are separated by commas.
+Double-quotes may be used to enclose fields containing
+commas, newlines, or doubled double-quotes.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
+for more details.
+.SS Built-in Variables
+.IR Gawk\^ "'s"
+built-in variables are listed below.
+This list is purposely terse. For details, see
+.IR https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables .
+.TP "\w'\fBFIELDWIDTHS\fR'u+1n"
+.B ARGC
+The number of command line arguments.
+.TP
+.B ARGIND
+The index in
+.B ARGV
+of the current file being processed.
+.TP
+.B ARGV
+Array of command line arguments.  The array is indexed from
+0 to
+.B ARGC
+\- 1.
+.TP
+.B BINMODE
+On non-POSIX systems, specifies use of \*(lqbinary\*(rq mode for all file I/O.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html
+for the details.
+.TP
+.B CONVFMT
+The conversion format for numbers, \fB"%.6g"\fR, by default.
+.TP
+.B ENVIRON
+An array containing the values of the current environment.
+The array is indexed by the environment variables, each element being
+the value of that variable.
+.TP
+.B ERRNO
+If a system error occurs either doing a redirection for
+.BR getline ,
+during a read for
+.BR getline ,
+or during a
+.BR close() ,
+then
+.B ERRNO
+is set to
+a string describing the error.
+The value is subject to translation in non-English locales.
+.TP
+.B FIELDWIDTHS
+A whitespace-separated list of field widths.  When set,
+.I gawk
+parses the input into fields of fixed width, instead of using the
+value of the
+.B FS
+variable as the field separator.
+Each field width may optionally be preceded by a colon-separated
+value specifying the number of characters to skip before the field starts.
+.TP
+.B FILENAME
+The name of the current input file.
+If no files are specified on the command line, the value of
+.B FILENAME
+is \*(lq\-\*(rq.
+However,
+.B FILENAME
+is undefined inside the
+.B BEGIN
+rule
+(unless set by
+.BR getline ).
+.TP
+.B FNR
+The input record number in the current input file.
+.TP
+.B FPAT
+A regular expression describing the contents of the
+fields in a record.
+When set,
+.I gawk
+parses the input into fields, where the fields match the
+regular expression, instead of using the
+value of
+.B FS
+as the field separator.
+.TP
+.B FS
+The input field separator, a space by default.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html
+for the details.
+.TP
+.B FUNCTAB
+An array whose indices and corresponding values
+are the names of all the user-defined
+or extension functions in the program.
+.BR NOTE :
+You may not use the
+.B delete
+statement with the
+.B FUNCTAB
+array.
+.TP
+.B IGNORECASE
+Controls the case-sensitivity of all regular expression
+and string operations.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html
+for details.
+.TP
+.B LINT
+Provides dynamic control of the
+.B \-\^\-lint
+option from within an \*(AK program.
+.TP
+.B NF
+The number of fields in the current input record.
+.TP
+.B NR
+The total number of input records seen so far.
+.TP
+.B OFMT
+The output format for numbers, \fB"%.6g"\fR, by default.
+.TP
+.B OFS
+The output field separator, a space by default.
+.TP
+.B ORS
+The output record separator, by default a newline.
+.TP
+.B PREC
+The working precision of arbitrary precision floating-point
+numbers, 53 by default.
+.TP
+.B PROCINFO
+The elements of this array provide access to information about the
+running \*(AK program.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset
+for the details.
+.TP
+.B ROUNDMODE
+The rounding mode to use for arbitrary precision arithmetic on
+numbers, by default \fB"N"\fR (IEEE-754 roundTiesToEven mode).
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode
+for the details.
+.TP
+.B RS
+The input record separator, by default a newline.
+.TP
+.B RT
+The record terminator.
+.I Gawk
+sets
+.B RT
+to the input text that matched the character or regular expression
+specified by
+.BR RS .
+.TP
+.B RSTART
+The index of the first character matched by
+.BR match() ;
+0 if no match.
+.TP
+.B RLENGTH
+The length of the string matched by
+.BR match() ;
+\-1 if no match.
+.TP
+.B SUBSEP
+The string used to separate multiple subscripts in array
+elements, by default \fB"\e034"\fR.
+.TP
+.B SYMTAB
+An array whose indices are the names of all currently defined
+global variables and arrays in the program.
+You may not use the
+.B delete
+statement with the
+.B SYMTAB
+array, nor assign to elements with an index that is
+not a variable name.
+.TP
+.B TEXTDOMAIN
+The text domain of the \*(AK program; used to find the localized
+translations for the program's strings.
+.SS Arrays
+Arrays are subscripted with an expression between square brackets
+.RB ( [ " and " ] ).
+If the expression is an expression list
+.RI ( expr ", " expr " .\|.\|.)"
+then the array subscript is a string consisting of the
+concatenation of the (string) value of each expression,
+separated by the value of the
+.B SUBSEP
+variable.
+This facility is used to simulate multiply dimensioned
+arrays.  For example:
+.PP
+.RS
+.ft B
+i = "A";\^ j = "B";\^ k = "C"
+.br
+x[i, j, k] = "hello, world\en"
+.ft R
+.RE
+.PP
+assigns the string \fB"hello,\ world\en"\fR to the element of the array
+.B x
+which is indexed by the string \fB"A\e034B\e034C"\fR.  All arrays in \*(AK
+are associative, i.e., indexed by string values.
+.PP
+The special operator
+.B in
+may be used to test if an array has an index consisting of a particular
+value:
+.PP
+.RS
+.ft B
+.nf
+if (val in array)
+	print array[val]
+.fi
+.ft
+.RE
+.PP
+If the array has multiple subscripts, use
+.BR "(i, j) in array" .
+.PP
+The
+.B in
+construct may also be used in a
+.B for
+loop to iterate over all the elements of an array.
+However, the
+.B "(i, j) in array"
+construct only works in tests, not in
+.B for
+loops.
+.PP
+An element may be deleted from an array using the
+.B delete
+statement.
+The
+.B delete
+statement may also be used to delete the entire contents of an array,
+just by specifying the array name without a subscript.
+.PP
+.I gawk
+supports true multidimensional arrays. It does not require that
+such arrays be ``rectangular'' as in C or C++.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Arrays
+for details.
+.SS Namespaces
+.I Gawk
+provides a simple
+.I namespace
+facility to help work around the fact that all variables in
+AWK are global.
+.PP
+A
+.I "qualified name"
+consists of a two simple identifiers joined by a double colon
+.RB ( :: ).
+The left-hand identifier represents the namespace and the right-hand
+identifier is the variable within it.
+All simple (non-qualified) names are considered to be in the
+``current'' namespace; the default namespace is
+.BR awk .
+However, simple identifiers consisting solely of uppercase
+letters are forced into the
+.B awk
+namespace, even if the current namespace is different.
+.PP
+You change the current namespace with an
+\fB@namespace "\fIname\^\fB"\fR
+directive.
+.PP
+The standard predefined builtin function names may not be used as
+namespace names.  The names of additional functions provided by
+.I gawk
+may be used as namespace names or as simple identifiers in other
+namespaces.
+For more details, see
+.IR https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces .
+.SS Variable Typing And Conversion
+Variables and fields
+may be (floating point) numbers, or strings, or both.
+They may also be regular expressions. How the
+value of a variable is interpreted depends upon its context.  If used in
+a numeric expression, it will be treated as a number; if used as a string
+it will be treated as a string.
+.PP
+To force a variable to be treated as a number, add zero to it; to force it
+to be treated as a string, concatenate it with the null string.
+.PP
+Uninitialized variables have the numeric value zero and the string value ""
+(the null, or empty, string).
+.PP
+When a string must be converted to a number, the conversion is accomplished
+using
+.IR strtod (3).
+A number is converted to a string by using the value of
+.B CONVFMT
+as a format string for
+.IR sprintf (3),
+with the numeric value of the variable as the argument.
+However, even though all numbers in \*(AK are floating-point,
+integral values are
+.I always
+converted as integers.
+.PP
+.I Gawk
+performs comparisons as follows:
+If two variables are numeric, they are compared numerically.
+If one value is numeric and the other has a string value that is a
+\*(lqnumeric string,\*(rq then comparisons are also done numerically.
+Otherwise, the numeric value is converted to a string and a string
+comparison is performed.
+Two strings are compared, of course, as strings.
+.PP
+Note that string constants, such as \fB"57"\fP, are
+.I not
+numeric strings, they are string constants.
+The idea of \*(lqnumeric string\*(rq
+only applies to fields,
+.B getline
+input,
+.BR FILENAME ,
+.B ARGV
+elements,
+.B ENVIRON
+elements and the elements of an array created by
+.B split()
+or
+.B patsplit()
+that are numeric strings.
+The basic idea is that
+.IR "user input" ,
+and only user input, that looks numeric,
+should be treated that way.
+.SS Octal and Hexadecimal Constants
+You may use C-style octal and hexadecimal constants in your AWK
+program source code.
+For example, the octal value
+.B 011
+is equal to decimal
+.BR 9 ,
+and the hexadecimal value
+.B 0x11
+is equal to decimal 17.
+.SS String Constants
+String constants in \*(AK are sequences of characters enclosed
+between double quotes (like \fB"value"\fR).  Within strings, certain
+.I "escape sequences"
+are recognized, as in C.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences
+for the details.
+.SS Regexp Constants
+A regular expression constant is a sequence of characters enclosed
+between forward slashes (like
+.BR /value/ ).
+.PP
+The escape sequences described in the manual may also be used inside
+constant regular expressions
+(e.g.,
+.B "/[\ \et\ef\en\er\ev]/"
+matches whitespace characters).
+.PP
+.I Gawk
+provides
+.I "strongly typed"
+regular expression constants. These are written with a leading
+.B @
+symbol (like so:
+.BR @/value/ ).
+Such constants may be assigned to scalars (variables, array elements)
+and passed to user-defined functions. Variables that have been so
+assigned have regular expression type.
+.SH PATTERNS AND ACTIONS
+\*(AK is a line-oriented language.  The pattern comes first, and then the
+action.  Action statements are enclosed in
+.B {
+and
+.BR } .
+Either the pattern may be missing, or the action may be missing, but,
+of course, not both.  If the pattern is missing, the action
+executes for every single record of input.
+A missing action is equivalent to
+.RS
+.PP
+.B "{ print }"
+.RE
+.PP
+which prints the entire record.
+.PP
+Comments begin with the
+.B #
+character, and continue until the
+end of the line.
+Empty lines may be used to separate statements.
+Normally, a statement ends with a newline, however, this is not the
+case for lines ending in
+a comma,
+.BR { ,
+.BR ? ,
+.BR : ,
+.BR && ,
+or
+.BR || .
+Lines ending in
+.B do
+or
+.B else
+also have their statements automatically continued on the following line.
+In other cases, a line can be continued by ending it with a \*(lq\e\*(rq,
+in which case the newline is ignored.  However, a \*(lq\e\*(rq after a
+.B #
+is not special.
+.PP
+Multiple statements may
+be put on one line by separating them with a \*(lq;\*(rq.
+This applies to both the statements within the action part of a
+pattern-action pair (the usual case),
+and to the pattern-action statements themselves.
+.SS Patterns
+\*(AK patterns may be one of the following:
+.PP
+.RS
+.nf
+.B BEGIN
+.B END
+.B BEGINFILE
+.B ENDFILE
+.BI / "regular expression" /
+.I "relational expression"
+.IB pattern " && " pattern
+.IB pattern " || " pattern
+.IB pattern " ? " pattern " : " pattern
+.BI ( pattern )
+.BI ! " pattern"
+.IB pattern1 ", " pattern2
+.fi
+.RE
+.PP
+.B BEGIN
+and
+.B END
+are two special kinds of patterns which are not tested against
+the input.
+The action parts of all
+.B BEGIN
+patterns are merged as if all the statements had
+been written in a single
+.B BEGIN
+rule.  They are executed before any
+of the input is read.  Similarly, all the
+.B END
+rules are merged,
+and executed when all the input is exhausted (or when an
+.B exit
+statement is executed).
+.B BEGIN
+and
+.B END
+patterns cannot be combined with other patterns in pattern expressions.
+.B BEGIN
+and
+.B END
+patterns cannot have missing action parts.
+.PP
+.B BEGINFILE
+and
+.B ENDFILE
+are additional special patterns whose actions are executed
+before reading the first record of each command-line input file
+and after reading the last record of each file.
+Inside the
+.B BEGINFILE
+rule, the value of
+.B ERRNO
+is the empty string if the file was opened successfully.
+Otherwise, there is some problem with the file and the code should
+use
+.B nextfile
+to skip it. If that is not done,
+.I gawk
+produces its usual fatal error for files that cannot be opened.
+.PP
+For
+.BI / "regular expression" /
+patterns, the associated statement is executed for each input record that matches
+the regular expression.
+Regular expressions are essentially the same as those in
+.IR egrep (1).
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Regexp.html
+for the details on regular expressions.
+.PP
+A
+.I "relational expression"
+may use any of the operators defined below in the section on actions.
+These generally test whether certain fields match certain regular expressions.
+.PP
+The
+.BR && ,
+.BR || ,
+and
+.B !
+operators are logical AND, logical OR, and logical NOT, respectively, as in C.
+They do short-circuit evaluation, also as in C, and are used for combining
+more primitive pattern expressions.  As in most languages, parentheses
+may be used to change the order of evaluation.
+.PP
+The
+.B ?\^:
+operator is like the same operator in C.  If the first pattern is true
+then the pattern used for testing is the second pattern, otherwise it is
+the third.  Only one of the second and third patterns is evaluated.
+.PP
+The
+.IB pattern1 ", " pattern2
+form of an expression is called a
+.IR "range pattern" .
+It matches all input records starting with a record that matches
+.IR pattern1 ,
+and continuing until a record that matches
+.IR pattern2 ,
+inclusive.  It does not combine with any other sort of pattern expression.
+.SS Actions
+Action statements are enclosed in braces,
+.B {
+and
+.BR } .
+Action statements consist of the usual assignment, conditional, and looping
+statements found in most languages.  The operators, control statements,
+and input/output statements
+available are patterned after those in C.
+.SS Operators
+The operators in \*(AK, in order of decreasing precedence, are:
+.TP "\w'\fB*= /= %= ^=\fR'u+1n"
+.BR ( \&.\|.\|. )
+Grouping
+.TP
+.B $
+Field reference.
+.TP
+.B "++ \-\^\-"
+Increment and decrement, both prefix and postfix.
+.TP
+.B ^
+Exponentiation.
+.TP
+.B "+ \- !"
+Unary plus, unary minus, and logical negation.
+.TP
+.B "* / %"
+Multiplication, division, and modulus.
+.TP
+.B "+ \-"
+Addition and subtraction.
+.TP
+.I space
+String concatenation.
+.TP
+.B "|   |&"
+Piped I/O for
+.BR getline ,
+.BR print ,
+and
+.BR printf .
+.TP
+.B "< > <= >= == !="
+The regular relational operators.
+.TP
+.B "~ !~"
+Regular expression match, negated match.
+.TP
+.B in
+Array membership.
+.TP
+.B &&
+Logical AND.
+.TP
+.B ||
+Logical OR.
+.TP
+.B ?:
+The C conditional expression.  This has the form
+.IB expr1 " ? " expr2 " : " expr3\/\fR.
+If
+.I expr1
+is true, the value of the expression is
+.IR expr2 ,
+otherwise it is
+.IR expr3 .
+Only one of
+.I expr2
+and
+.I expr3
+is evaluated.
+.TP
+.B "= += \-= *= /= %= ^="
+Assignment.  Both absolute assignment
+.BI ( var " = " value )
+and operator-assignment (the other forms) are supported.
+.SS Control Statements
+The control statements are
+as follows:
+.PP
+.RS
+.nf
+\fBif (\fIcondition\fB) \fIstatement\fR [ \fBelse\fI statement \fR]
+\fBwhile (\fIcondition\fB) \fIstatement\fR
+\fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR
+\fBfor (\fIexpr1\fB; \fIexpr2\fB; \fIexpr3\fB) \fIstatement\fR
+\fBfor (\fIvar \fBin\fI array\fB) \fIstatement\fR
+\fBbreak\fR
+\fBcontinue\fR
+\fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR
+\fBdelete \fIarray\^\fR
+\fBexit\fR [ \fIexpression\fR ]
+\fB{ \fIstatements \fB}\fR
+\fBswitch (\fIexpression\fB) {
+\fBcase \fIvalue\fB|\fIregex\fB : \fIstatement
+\&.\^.\^.
+\fR[ \fBdefault: \fIstatement \fR]
+\fB}\fR
+.fi
+.RE
+.SS "I/O Statements"
+The input/output statements are as follows:
+.TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n"
+\fBclose(\fIfile \fR[\fB, \fIhow\fR]\fB)\fR
+Close an open file, pipe or coprocess.
+The optional
+.I how
+should only be used when closing one end of a
+two-way pipe to a coprocess.
+It must be a string value, either
+\fB"to"\fR or \fB"from"\fR.
+.TP
+.B getline
+Set
+.B $0
+from the next input record; set
+.BR NF ,
+.BR NR ,
+.BR FNR ,
+.BR RT .
+.TP
+.BI "getline <" file
+Set
+.B $0
+from the next record of
+.IR file ;
+set
+.BR NF ,
+.BR RT .
+.TP
+.BI getline " var"
+Set
+.I var
+from the next input record; set
+.BR NR ,
+.BR FNR ,
+.BR RT .
+.TP
+.BI getline " var" " <" file
+Set
+.I var
+from the next record of
+.IR file ;
+set
+.BR RT .
+.TP
+\fIcommand\fB | getline \fR[\fIvar\fR]
+Run
+.IR command ,
+piping the output either into
+.B $0
+or
+.IR var ,
+as above, and
+.BR RT .
+.TP
+\fIcommand\fB |& getline \fR[\fIvar\fR]
+Run
+.I command
+as a coprocess
+piping the output either into
+.B $0
+or
+.IR var ,
+as above, and
+.BR RT .
+.RI "(The " command
+can also be a socket.  See the subsection
+.BR "Special File Names" ,
+below.)
+.TP
+\&\fBfflush(\fR[\fIfile\^\fR]\fB)\fR
+Flush any buffers associated with the open output file or pipe
+.IR file .
+If
+.I file
+is missing or if it
+is the null string,
+then flush all open output files and pipes.
+.TP
+.B next
+Stop processing the current input record.
+Read the next input record
+and start processing over with the first pattern in the
+\*(AK program.
+Upon reaching the end of the input data,
+execute any
+.B END
+rule(s).
+.TP
+.B nextfile
+Stop processing the current input file.  The next input record read
+comes from the next input file.
+Update
+.B FILENAME
+and
+.BR ARGIND ,
+reset
+.B FNR
+to 1, and start processing over with the first pattern in the
+\*(AK program.
+Upon reaching the end of the input data,
+execute any
+.B ENDFILE
+and
+.B END
+rule(s).
+.TP
+.B print
+Print the current record.
+The output record is terminated with the value of
+.BR ORS .
+.TP
+.BI print " expr-list"
+Print expressions.
+Each expression is separated by the value of
+.BR OFS .
+The output record is terminated with the value of
+.BR ORS .
+.TP
+.BI print " expr-list" " >" file
+Print expressions on
+.IR file .
+Each expression is separated by the value of
+.BR OFS .
+The output record is terminated with the value of
+.BR ORS .
+.TP
+.BI printf " fmt, expr-list"
+Format and print.
+.TP
+.BI printf " fmt, expr-list" " >" file
+Format and print on
+.IR file .
+.TP
+.BI system( cmd-line )
+Execute the command
+.IR cmd-line ,
+and return the exit status.
+(This may not be available on non-\*(PX systems.)
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions
+for the full details on the exit status.
+.PP
+Additional output redirections are allowed for
+.B print
+and
+.BR printf .
+.TP
+.BI "print .\|.\|.\& >>" " file"
+Append output to the
+.IR file .
+.TP
+.BI "print .\|.\|.\& |" " command"
+Write on a pipe.
+.TP
+.BI "print .\|.\|.\& |&" " command"
+Send data to a coprocess or socket.
+(See also the subsection
+.BR "Special File Names" ,
+below.)
+.PP
+The
+.B getline
+command returns 1 on success, zero on end of file, and \-1 on an error.
+If the
+.IR errno (3)
+value indicates that the I/O operation may be retried,
+and \fBPROCINFO["\fIinput\^\fP", "RETRY"]\fR
+is set, then \-2 is returned instead of \-1, and further calls to
+.B getline
+may be attempted.
+Upon an error,
+.B ERRNO
+is set to a string describing the problem.
+.PP
+.BR NOTE :
+Failure in opening a two-way socket results in a non-fatal error being
+returned to the calling function. If using a pipe, coprocess, or socket to
+.BR getline ,
+or from
+.B print
+or
+.B printf
+within a loop, you
+.I must
+use
+.B close()
+to create new instances of the command or socket.
+\*(AK does not automatically close pipes, sockets, or coprocesses when
+they return EOF.
+.PP
+The \*(AK versions of the
+.B printf
+statement and
+.B sprintf()
+function
+are similar to those of C. For details, see
+.IR https://www.gnu.org/software/gawk/manual/html_node/Printf.html .
+.SS Special File Names
+When doing I/O redirection from either
+.B print
+or
+.B printf
+into a file,
+or via
+.B getline
+from a file,
+.I gawk
+recognizes certain special filenames internally.  These filenames
+allow access to open file descriptors inherited from
+.IR gawk\^ "'s"
+parent process (usually the shell).
+These file names may also be used on the command line to name data files.
+The filenames are:
+.TP "\w'\fB/dev/stdout\fR'u+1n"
+.B \-
+The standard input.
+.TP
+.B /dev/stdin
+The standard input.
+.TP
+.B /dev/stdout
+The standard output.
+.TP
+.B /dev/stderr
+The standard error output.
+.TP
+.BI /dev/fd/\^ n
+The file associated with the open file descriptor
+.IR n .
+.PP
+The following special filenames may be used with the
+.B |&
+coprocess operator for creating TCP/IP network connections:
+.TP
+.PD 0
+.BI /inet/tcp/ lport / rhost / rport
+.TP
+.PD 0
+.BI /inet4/tcp/ lport / rhost / rport
+.TP
+.PD
+.BI /inet6/tcp/ lport / rhost / rport
+Files for a TCP/IP connection on local port
+.I lport
+to
+remote host
+.I rhost
+on remote port
+.IR rport .
+Use a port of
+.B 0
+to have the system pick a port.
+Use
+.B /inet4
+to force an IPv4 connection,
+and
+.B /inet6
+to force an IPv6 connection.
+Plain
+.B /inet
+uses the system default (most likely IPv4).
+Usable only with the
+.B |&
+two-way I/O operator.
+.TP
+.PD 0
+.BI /inet/udp/ lport / rhost / rport
+.TP
+.PD 0
+.BI /inet4/udp/ lport / rhost / rport
+.TP
+.PD
+.BI /inet6/udp/ lport / rhost / rport
+Similar, but use UDP/IP instead of TCP/IP.
+.SS Numeric Functions
+\*(AK has the following built-in arithmetic functions:
+.TP "\w'\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR'u+1n"
+.BI atan2( y , " x" )
+Return the arctangent of
+.I y/x
+in radians.
+.TP
+.BI cos( expr )
+Return the cosine of
+.IR expr ,
+which is in radians.
+.TP
+.BI exp( expr )
+The exponential function.
+.TP
+.BI int( expr )
+Truncate to integer.
+.ig
+.TP
+.BI intdiv( num ", " denom ", " result )
+Truncate
+.I num
+and
+.I denom
+to integers. Return the quotient of
+.I num
+divided by
+.I denom
+in \fIresult\fB["quotient"]\fR
+and the remainder in
+\fIresult\fB["remainder"]\fR.
+This is a
+.I gawk
+extension, primarily of value when working with
+arbitrarily large integers.
+..
+.TP
+.BI log( expr )
+The natural logarithm function.
+.TP
+.B rand()
+Return a random number
+.IR N ,
+between zero and one,
+such that 0 \(<= \fIN\fP < 1.
+.TP
+.BI sin( expr )
+Return the sine of
+.IR expr ,
+which is in radians.
+.TP
+.BI sqrt( expr )
+Return the square root of
+.IR expr .
+.TP
+\&\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR
+Use
+.I expr
+as the new seed for the random number generator.  If no
+.I expr
+is provided, use the time of day.
+Return the previous seed for the random
+number generator.
+.SS String Functions
+.I Gawk
+has the following built-in string functions; details are provided in
+.IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions .
+.TP "\w'\fBsprintf(\fIfmt\^\fB, \fIexpr-list\^\fB)\fR'u+1n"
+\fBasort(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
+Return the number of elements in the source
+array
+.IR s .
+Sort
+the contents of
+.I s
+using
+.IR gawk\^ "'s"
+normal rules for
+comparing values, and replace the indices of the
+sorted values
+.I s
+with sequential
+integers starting with 1. If the optional
+destination array
+.I d
+is specified,
+first duplicate
+.I s
+into
+.IR d ,
+and then sort
+.IR d ,
+leaving the indices of the
+source array
+.I s
+unchanged. The optional string
+.I how
+controls the direction and the comparison mode.
+Valid values for
+.I how
+are
+described in
+.IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions .
+.IR s " and " d
+are allowed to be the same array; this only makes sense when
+supplying the third argument as well.
+.TP
+\fBasorti(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
+Return the number of elements in the source
+array
+.IR s .
+The behavior is the same as that of
+.BR asort() ,
+except that the array
+.I indices
+are used for sorting, not the array values.
+When done, the array is indexed numerically, and
+the values are those of the original indices.
+The original values are lost; thus provide
+a second array if you wish to preserve the original.
+The purpose of the optional string
+.I how
+is the same as for
+.BR asort() .
+Here too,
+.IR s " and " d
+are allowed to be the same array; this only makes sense when
+supplying the third argument as well.
+.TP
+\fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR
+Search the target string
+.I t
+for matches of the regular expression
+.IR r .
+If
+.I h
+is a string beginning with
+.B g
+or
+.BR G ,
+then replace all matches of
+.I r
+with
+.IR s .
+Otherwise,
+.I h
+is a number indicating which match of
+.I r
+to replace.
+If
+.I t
+is not supplied, use
+.B $0
+instead.
+Within the replacement text
+.IR s ,
+the sequence
+.BI \e n\fR,
+where
+.I n
+is a digit from 1 to 9, may be used to indicate just the text that
+matched the
+.IR n 'th
+parenthesized subexpression.  The sequence
+.B \e0
+represents the entire matched text, as does the character
+.BR & .
+Unlike
+.B sub()
+and
+.BR gsub() ,
+the modified string is returned as the result of the function,
+and the original target string is
+.I not
+changed.
+.TP
+\fBgsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
+For each substring matching the regular expression
+.I r
+in the string
+.IR t ,
+substitute the string
+.IR s ,
+and return the number of substitutions.
+If
+.I t
+is not supplied, use
+.BR $0 .
+An
+.B &
+in the replacement text is replaced with the text that was actually matched.
+Use
+.B \e&
+to get a literal
+.BR & .
+(This must be typed as \fB"\e\e&"\fP; see
+.I https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details
+for a fuller discussion of the rules for ampersands
+and backslashes in the replacement text of
+.BR sub() ,
+.BR gsub() ,
+and
+.BR gensub() .)
+.TP
+.BI index( s , " t" )
+Return the index of the string
+.I t
+in the string
+.IR s ,
+or zero if
+.I t
+is not present.
+(This implies that character indices start at one.)
+.TP
+\fBlength(\fR[\fIs\fR]\fB)
+Return the length of the string
+.IR s ,
+or the length of
+.B $0
+if
+.I s
+is not supplied.
+With an array argument,
+.B length()
+returns the number of elements in the array.
+.TP
+\fBmatch(\fIs\fB, \fIr \fR[\fB, \fIa\fR]\fB)\fR
+Return the position in
+.I s
+where the regular expression
+.I r
+occurs, or zero if
+.I r
+is not present, and set the values of
+.B RSTART
+and
+.BR RLENGTH .
+Note that the argument order is the same as for the
+.B ~
+operator:
+.IB str " ~"
+.IR re .
+.ft R
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
+for a description of how the array
+.I a
+is filled if it is provided.
+.TP
+\fBpatsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR
+Split the string
+.I s
+into the array
+.I a
+and the separators array
+.I seps
+on the regular expression
+.IR r ,
+and return the number of fields.
+Element values are the portions of
+.I s
+that matched
+.IR r .
+The value of
+.BI seps[ i ]
+is the possibly null separator that appeared after
+.BI a[ i ]\fR.
+The value of
+.B seps[0]
+is the possibly null leading separator.
+If
+.I r
+is omitted,
+.B FPAT
+is used instead.
+The arrays
+.I a
+and
+.I seps
+are cleared first.
+Splitting behaves identically to field splitting with
+.BR FPAT .
+.TP
+\fBsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR
+Split the string
+.I s
+into the array
+.I a
+and the separators array
+.I seps
+on the regular expression
+.IR r ,
+and return the number of fields.  If
+.I r
+is omitted,
+.B FS
+is used instead.
+The arrays
+.I a
+and
+.I seps
+are cleared first.
+.BI seps[ i ]
+is the field separator matched by
+.I r
+between
+.BI a[ i ]
+and
+.BI a[ i +1]\fR.
+Splitting behaves identically to field splitting.
+.TP
+.BI sprintf( fmt\^ , " expr-list\^" )
+Print
+.I expr-list
+according to
+.IR fmt ,
+and return the resulting string.
+.TP
+.BI strtonum( str )
+Examine
+.IR str ,
+and return its numeric value.
+If
+.I str
+begins
+with a leading
+.BR 0 ,
+treat it
+as an octal number.
+If
+.I str
+begins
+with a leading
+.B 0x
+or
+.BR 0X ,
+treat it
+as a hexadecimal number.
+Otherwise, assume it is a decimal number.
+.TP
+\fBsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
+Just like
+.BR gsub() ,
+but replace only the first matching substring.
+Return either zero or one.
+.TP
+\fBsubstr(\fIs\fB, \fIi \fR[\fB, \fIn\fR]\fB)\fR
+Return the at most
+.IR n -character
+substring of
+.I s
+starting at
+.IR i .
+If
+.I n
+is omitted, use the rest of
+.IR s .
+.TP
+.BI tolower( str )
+Return a copy of the string
+.IR str ,
+with all the uppercase characters in
+.I str
+translated to their corresponding lowercase counterparts.
+Non-alphabetic characters are left unchanged.
+.TP
+.BI toupper( str )
+Return a copy of the string
+.IR str ,
+with all the lowercase characters in
+.I str
+translated to their corresponding uppercase counterparts.
+Non-alphabetic characters are left unchanged.
+.PP
+.I Gawk
+is multibyte aware.  This means that
+.BR index() ,
+.BR length() ,
+.B substr()
+and
+.B match()
+all work in terms of characters, not bytes.
+.SS Time Functions
+.I Gawk
+provides the following functions for obtaining time stamps and
+formatting them. Details are provided in
+.IR https://www.gnu.org/software/gawk/manual/html_node/Time-Functions .
+.TP "\w'\fBsystime()\fR'u+1n"
+\fBmktime(\fIdatespec\fR [\fB, \fIutc-flag\fR]\fB)\fR
+Turn
+.I datespec
+into a time stamp of the same form as returned by
+.BR systime() ,
+and return the result.
+If
+.I utc-flag
+is present and is non-zero or non-null, the time is assumed to be in
+the UTC time zone; otherwise, the
+time is assumed to be in the local time zone.
+If
+.I datespec
+does not contain enough elements or if the resulting time
+is out of range,
+.B mktime()
+returns \-1.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions
+for the details of
+.IR datespec .
+.TP
+\fBstrftime(\fR[\fIformat \fR[\fB, \fItimestamp\fR[\fB, \fIutc-flag\fR]]]\fB)\fR
+Format
+.I timestamp
+according to the specification in
+.IR format .
+If
+.I utc-flag
+is present and is non-zero or non-null, the result
+is in UTC, otherwise the result is in local time.
+The
+.I timestamp
+should be of the same form as returned by
+.BR systime() .
+If
+.I timestamp
+is missing, the current time of day is used.
+If
+.I format
+is missing, a default format equivalent to the output of
+.IR date (1)
+is used.
+The default format is available in
+.BR PROCINFO["strftime"] .
+See the specification for the
+.B strftime()
+function in ISO C for the format conversions that are
+guaranteed to be available.
+.TP
+.B systime()
+Return the current time of day as the number of seconds since the Epoch
+(1970-01-01 00:00:00 UTC on \*(PX systems).
+.SS Bit Manipulations Functions
+.I Gawk
+supplies the following bit manipulation functions.
+They work by converting double-precision floating point
+values to
+.B uintmax_t
+integers, doing the operation, and then converting the
+result back to floating point.
+Passing negative operands to any of these functions causes
+a fatal error.
+.PP
+The functions are:
+.TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n"
+\fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise AND of the values provided in the argument list.
+There must be at least two.
+.TP
+\fBcompl(\fIval\fB)\fR
+Return the bitwise complement of
+.IR val .
+.TP
+\fBlshift(\fIval\fB, \fIcount\fB)\fR
+Return the value of
+.IR val ,
+shifted left by
+.I count
+bits.
+.TP
+\fBor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise OR of the values provided in the argument list.
+There must be at least two.
+.TP
+\fBrshift(\fIval\fB, \fIcount\fB)\fR
+Return the value of
+.IR val ,
+shifted right by
+.I count
+bits.
+.TP
+\fBxor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise XOR of the values provided in the argument list.
+There must be at least two.
+.SS Type Functions
+The following functions provide type related information about
+their arguments.
+.TP \w'\fBisarray(\fIx\fB)\fR'u+1n
+\fBisarray(\fIx\fB)\fR
+Return true if
+.I x
+is an array, false otherwise.
+.TP
+\fBtypeof(\fIx\fB)\fR
+Return a string indicating the type of
+.IR x .
+The string will be one of
+\fB"array"\fP,
+\fB"number"\fP,
+\fB"regexp"\fP,
+\fB"string"\fP,
+\fB"strnum"\fP,
+\fB"unassigned"\fP,
+or
+\fB"undefined"\fP.
+.SS Internationalization Functions
+The following functions may be used from within your AWK program for
+translating strings at run-time.
+For full details, see
+.IR https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions .
+.TP
+\fBbindtextdomain(\fIdirectory \fR[\fB, \fIdomain\fR]\fB)\fR
+Specify the directory where
+.I gawk
+looks for the
+.B \&.gmo
+files, in case they
+will not or cannot be placed in the ``standard'' locations.
+It returns the directory where
+.I domain
+is ``bound.''
+.sp .5
+The default
+.I domain
+is the value of
+.BR TEXTDOMAIN .
+If
+.I directory
+is the null string (\fB""\fR), then
+.B bindtextdomain()
+returns the current binding for the
+given
+.IR domain .
+.TP
+\fBdcgettext(\fIstring \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR
+Return the translation of
+.I string
+in text domain
+.I domain
+for locale category
+.IR category .
+The default value for
+.I domain
+is the current value of
+.BR TEXTDOMAIN .
+The default value for
+.I category
+is \fB"LC_MESSAGES"\fR.
+.TP
+\fBdcngettext(\fIstring1\fB, \fIstring2\fB, \fInumber \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR
+Return the plural form used for
+.I number
+of the translation of
+.I string1
+and
+.I string2
+in
+text domain
+.I domain
+for locale category
+.IR category .
+The default value for
+.I domain
+is the current value of
+.BR TEXTDOMAIN .
+The default value for
+.I category
+is \fB"LC_MESSAGES"\fR.
+.SS Boolean Valued Functions
+You can create special Boolean-typed values; see the manual for how
+they work and why they exist.
+.TP
+.BI mkbool( expression\^ )
+Based on the boolean value of
+.I expression
+return either a true value or a false value.
+True values have numeric value one.
+False values have numeric value zero.
+.SH USER-DEFINED FUNCTIONS
+Functions in \*(AK are defined as follows:
+.PP
+.RS
+\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR
+.RE
+.PP
+Functions execute when they are called from within expressions
+in either patterns or actions.  Actual parameters supplied in the function
+call are used to instantiate the formal parameters declared in the function.
+Arrays are passed by reference, other variables are passed by value.
+.PP
+Local variables are declared as extra parameters
+in the parameter list.  The convention is to separate local variables from
+real parameters by extra spaces in the parameter list.  For example:
+.PP
+.RS
+.ft B
+.nf
+function  f(p, q,     a, b)	# a and b are local
+{
+	\&.\|.\|.
+}
+
+/abc/	{ .\|.\|.\& ; f(1, 2) ; .\|.\|.\& }
+.fi
+.ft R
+.RE
+.PP
+The left parenthesis in a function call is required
+to immediately follow the function name,
+without any intervening whitespace.
+This restriction does not apply to the built-in functions listed above.
+.PP
+Functions may call each other and may be recursive.
+Function parameters used as local variables are initialized
+to the null string and the number zero upon function invocation.
+.PP
+Use
+.BI return " expr"
+to return a value from a function.  The return value is undefined if no
+value is provided, or if the function returns by \*(lqfalling off\*(rq the
+end.
+.PP
+Functions may be called indirectly. To do this, assign
+the name of the function to be called, as a string, to a variable.
+Then use the variable as if it were the name of a function, prefixed with an
+.B @
+sign, like so:
+.RS
+.ft B
+.nf
+function myfunc()
+{
+	print "myfunc called"
+	\&.\|.\|.
+}
+
+{	.\|.\|.
+	the_func = "myfunc"
+	@the_func()	# call through the_func to myfunc
+	.\|.\|.
+}
+.fi
+.ft R
+.RE
+.PP
+If
+.B \-\^\-lint
+has been provided,
+.I gawk
+warns about calls to undefined functions at parse time,
+instead of at run time.
+Calling an undefined function at run time is a fatal error.
+.SH DYNAMICALLY LOADING NEW FUNCTIONS
+You can dynamically add new functions written in C or C++ to the running
+.I gawk
+interpreter with the
+.B @load
+statement.
+The full details are beyond the scope of this manual page;
+see
+.IR https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions .
+.SH SIGNALS
+The
+.I gawk
+profiler accepts two signals.
+.B SIGUSR1
+causes it to dump a profile and function call stack to the
+profile file, which is either
+.BR awkprof.out ,
+or whatever file was named with the
+.B \-\^\-profile
+option.  It then continues to run.
+.B SIGHUP
+causes
+.I gawk
+to dump the profile and function call stack and then exit.
+.SH INTERNATIONALIZATION
+String constants are sequences of characters enclosed in double
+quotes.  In non-English speaking environments, it is possible to mark
+strings in the \*(AK program as requiring translation to the local
+natural language. Such strings are marked in the \*(AK program with
+a leading underscore (\*(lq_\*(rq).  For example,
+.sp
+.RS
+.ft B
+gawk 'BEGIN { print "hello, world" }'
+.RE
+.sp
+.ft R
+always prints
+.BR "hello, world" .
+But,
+.sp
+.RS
+.ft B
+gawk 'BEGIN { print _"hello, world" }'
+.RE
+.sp
+.ft R
+might print
+.B "bonjour, monde"
+in France.
+See
+.I https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization
+for the steps involved in producing and running a localizable
+\*(AK program.
+.SH GNU EXTENSIONS
+.I Gawk
+has a too-large number of extensions to \*(PX
+.IR awk .
+They are described in
+.IR https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html .
+All the extensions
+can be disabled by
+invoking
+.I gawk
+with the
+.B \-\^\-traditional
+or
+.B \-\^\-posix
+options.
+.SH ENVIRONMENT VARIABLES
+The
+.B AWKPATH
+environment variable can be used to provide a list of directories that
+.I gawk
+searches when looking for files named via the
+.BR \-f ,
+.BR \-\^\-file ,
+.B \-i
+and
+.B \-\^\-include
+options, and the
+.B @include
+directive.  If the initial search fails, the path is searched again after
+appending
+.B \&.awk
+to the filename.
+.PP
+The
+.B AWKLIBPATH
+environment variable can be used to provide a list of directories that
+.I gawk
+searches when looking for files named via the
+.B \-l
+and
+.B \-\^\-load
+options.
+.PP
+The
+.B GAWK_PERSIST_FILE
+environment variable, if present, specifies a file to use as
+the backing store for persistent memory.
+.IR "This is an experimental feature" .
+See \*(EP for the details.
+.PP
+The
+.B GAWK_READ_TIMEOUT
+environment variable can be used to specify a timeout
+in milliseconds for reading input from a terminal, pipe
+or two-way communication including sockets.
+.PP
+For connection to a remote host via socket,
+.B GAWK_SOCK_RETRIES
+controls the number of retries, and
+.B GAWK_MSEC_SLEEP
+the interval between retries.
+The interval is in milliseconds. On systems that do not support
+.IR usleep (3),
+the value is rounded up to an integral number of seconds.
+.PP
+If
+.B POSIXLY_CORRECT
+exists in the environment, then
+.I gawk
+behaves exactly as if
+.B \-\^\-posix
+had been specified on the command line.
+If
+.B \-\^\-lint
+has been specified,
+.I gawk
+issues a warning message to this effect.
+.ig
+.PP
+Set
+.B GAWK_NO_MPFR_WARN
+in the environment to silence the warning about MPFR mode
+being deprecated.
+..
+.SH EXIT STATUS
+If the
+.B exit
+statement is used with a value,
+then
+.I gawk
+exits with
+the numeric value given to it.
+.PP
+Otherwise, if there were no problems during execution,
+.I gawk
+exits with the value of the C constant
+.BR EXIT_SUCCESS .
+This is usually zero.
+.PP
+If an error occurs,
+.I gawk
+exits with the value of
+the C constant
+.BR EXIT_FAILURE .
+This is usually one.
+.PP
+If
+.I gawk
+exits because of a fatal error, the exit
+status is 2.  On non-POSIX systems, this value may be mapped to
+.BR EXIT_FAILURE .
+.SH VERSION INFORMATION
+This man page documents
+.IR gawk ,
+version 5.3.
+.SH AUTHORS
+The original version of \*(UX
+.I awk
+was designed and implemented by Alfred Aho,
+Peter Weinberger, and Brian Kernighan of Bell Laboratories.
+Ozan Yigit is the the current maintainer.
+Brian Kernighan occasionally dabbles in its development.
+.PP
+Paul Rubin and Jay Fenlason,
+of the Free Software Foundation, wrote
+.IR gawk ,
+to be compatible with the original version of
+.I awk
+distributed in Seventh Edition \*(UX.
+John Woods contributed a number of bug fixes.
+David Trueman, with contributions
+from Arnold Robbins, made
+.I gawk
+compatible with the new version of \*(UX
+.IR awk .
+Arnold Robbins is the current maintainer.
+.PP
+See \*(EP for a full list of the contributors to
+.I gawk
+and its documentation.
+.PP
+See the
+.B README
+file in the
+.I gawk
+distribution for up-to-date information about maintainers
+and which ports are currently supported.
+.SH BUG REPORTS
+If you find a bug in
+.IR gawk ,
+please use the
+.IR gawkbug (1)
+program to report it.
+.PP
+Full instructions for reporting a bug are provided in
+.IR https://www.gnu.org/software/gawk/manual/html_node/Bugs.html .
+.I Please
+carefully read and follow the instructions given there.
+This will make bug reporting and resolution much easier for everyone involved.
+Really.
+.SH BUGS
+The
+.B \-F
+option is not necessary given the command line variable assignment feature;
+it remains only for backwards compatibility.
+.PP
+This manual page is too long;
+.I gawk
+has too many features.
+.SH SEE ALSO
+.IR egrep (1),
+.IR sed (1),
+.IR gawkbug (1),
+.IR printf (3),
+and
+.IR strftime (3).
+.PP
+.IR "The AWK Programming Language" ,
+Alfred V.\& Aho, Brian W.\& Kernighan, Peter J.\& Weinberger,
+Addison-Wesley, 1988.  ISBN 0-201-07981-X.
+.PP
+\*(EP,
+Edition 5.2, shipped with the
+.I gawk
+source.
+The current version of this document is available online at
+.IR https://www.gnu.org/software/gawk/manual .
+.PP
+The GNU
+.B gettext
+documentation, available online at
+.IR https://www.gnu.org/software/gettext .
+.SH EXAMPLES
+.nf
+Print and sort the login names of all users:
+
+.ft B
+	BEGIN	{ FS = ":" }
+		{ print $1 | "sort" }
+
+.ft R
+Count lines in a file:
+
+.ft B
+		{ nlines++ }
+	END	{ print nlines }
+
+.ft R
+Precede each line by its number in the file:
+
+.ft B
+	{ print FNR, $0 }
+
+.ft R
+Concatenate and line number (a variation on a theme):
+
+.ft B
+	{ print NR, $0 }
+
+.ft R
+Run an external command for particular lines of data:
+
+.ft B
+	tail \-f access_log |
+	awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }'
+.ft R
+.fi
+.ig
+.SH ACKNOWLEDGEMENTS
+Brian Kernighan
+provided valuable assistance during testing and debugging.
+We thank him.
+..
+.SH COPYING PERMISSIONS
+Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009,
+2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
+2020, 2021, 2022, 2023
+Free Software Foundation, Inc.
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual page provided the copyright notice and this permission
+notice are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual page).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual page under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual page into another language, under the above conditions for
+modified versions, except that this permission notice may be stated in
+a translation approved by the Foundation.
diff --git a/upstream/mageia-cauldron/man1/gawkbug.1 b/upstream/mageia-cauldron/man1/gawkbug.1
new file mode 100644
index 00000000..35524769
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gawkbug.1
@@ -0,0 +1,73 @@
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\"     Arnold Robbins
+.\"     bug-gawk@gnu.org
+.\"
+.TH GAWKBUG 1 "2023 October 18" "GNU Awk 5.3"
+.SH NAME
+gawkbug \- report a bug in gawk
+.SH SYNOPSIS
+\fBgawkbug\fP [\fI\-\^\-version\fP] [\fI\-\^\-help\fP] [\fIemail-address\fP]
+.SH DESCRIPTION
+.B gawkbug
+is a shell script to help the user compose and mail bug reports
+concerning
+.B gawk
+in a standard format.
+.B gawkbug
+invokes the editor specified by the environment variable
+.SM
+.B EDITOR
+on a temporary copy of the bug report format outline. The user must
+fill in the appropriate fields and exit the editor.
+.B gawkbug
+then mails the completed report to \fIbug-gawk@gnu.org\fP, or
+\fIemail-address\fP.  If the report cannot be mailed, it is saved in the
+file \fIdead.gawkbug\fP in the invoking user's home directory.
+.PP
+The bug report format outline consists of several sections.  The first
+section provides information about the machine, operating system, the
+.B gawk
+version, and the compilation environment.  The second section
+should be filled in with a description of the bug.  The third section
+should be a description of how to reproduce the bug.  The optional
+fourth section is for a proposed fix.  Fixes are encouraged.
+.SH ENVIRONMENT
+.B gawkbug
+will utilize the following environment variables if they exist:
+.TP
+.B EDITOR
+Specifies the preferred editor. If
+.SM
+.B EDITOR
+is not set,
+.B gawkbug
+attempts to locate a number of alternative editors, including
+.BR vim ,
+and if it must,
+.BR emacs .
+If
+.B gawkbug
+cannot locate any of the alternative editors, it attempts to execute \fBvi\fP.
+.TP
+.B HOME
+Directory in which the failed bug report is saved if the mail fails.
+.TP
+.B TMPDIR
+Directory in which to create temporary files and directories.
+.SH "SEE ALSO"
+.TP
+\fIgawk\fP(1)
+.SH AUTHORS
+Brian Fox, Free Software Foundation
+.br
+bfox@gnu.org
+.PP
+Chet Ramey, Case Western Reserve University
+.br
+chet@po.cwru.edu
+.PP
+Arnold Robbins
+.br
+bug-gawk@gnu.org
diff --git a/upstream/mageia-cauldron/man1/gcore.1 b/upstream/mageia-cauldron/man1/gcore.1
new file mode 100644
index 00000000..fb97e50c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gcore.1
@@ -0,0 +1,118 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "GCORE 1"
+.TH GCORE 1 2023-12-29 "gdb-13.2-6.mga10 (Mageia release 10)" "GNU Development Tools"
+.\" 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
+gcore \- Generate a core file of a running program
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+gcore [\-a] [\-o \fIprefix\fR] \fIpid1\fR [\fIpid2\fR...\fIpidN\fR]
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Generate core dumps of one or more running programs with process IDs
+\&\fIpid1\fR, \fIpid2\fR, etc.  A core file produced by \fBgcore\fR
+is equivalent to one produced by the kernel when the process crashes
+(and when \f(CW\*(C`ulimit \-c\*(C'\fR was used to set up an appropriate core dump
+limit).  However, unlike after a crash, after \fBgcore\fR finishes
+its job the program remains running without any change.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \fB\-a\fR 4
+.IX Item "-a"
+Dump all memory mappings.  The actual effect of this option depends on
+the Operating System.  On GNU/Linux, it will disable
+\&\f(CW\*(C`use\-coredump\-filter\*(C'\fR and
+enable \f(CW\*(C`dump\-excluded\-mappings\*(C'\fR.
+.IP "\fB\-o\fR \fIprefix\fR" 4
+.IX Item "-o prefix"
+The optional argument \fIprefix\fR specifies the prefix to be used
+when composing the file names of the core dumps.  The file name is
+composed as \fIprefix.pid\fR, where \fIpid\fR is the
+process ID of the running program being analyzed by \fBgcore\fR.
+If not specified, \fIprefix\fR defaults to \fIgcore\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The full documentation for GDB is maintained as a Texinfo manual.
+If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB's Texinfo
+documentation are properly installed at your site, the command
+.PP
+.Vb 1
+\&        info gdb
+.Ve
+.PP
+should give you access to the complete manual.
+.PP
+\&\fIUsing GDB: A Guide to the GNU Source-Level Debugger\fR,
+Richard M. Stallman and Roland H. Pesch, July 1991.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 1988\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "Free Software" and "Free Software Needs
+Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
+and with the Back-Cover Texts as in (a) below.
+.PP
+(a) The FSF's Back-Cover Text is: "You are free to copy and modify
+this GNU Manual.  Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom."
diff --git a/upstream/mageia-cauldron/man1/gdiffmk.1 b/upstream/mageia-cauldron/man1/gdiffmk.1
new file mode 100644
index 00000000..97826128
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gdiffmk.1
@@ -0,0 +1,260 @@
+.TH GDIFFMK 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+gdiffmk \- mark differences between groff/nroff/troff files
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 2004-2018 Free Software Foundation, Inc.
+.\"
+.\" This file is part of gdiffmk, which is part of groff, the GNU roff
+.\" type-setting system.
+.\"
+.\" 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.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see
+.\" <http://www.gnu.org/licenses/>.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY gdiffmk
+.OP \-a addmark
+.OP \-c changemark
+.OP \-d deletemark
+.RB [ \-D
+.RB [ \-B ]
+.RB [ \-M
+.IR "mark1 mark2" ]]
+.OP \-x diffcmd
+.OP \-\-
+.I file1
+.I file2
+.RI [ output ]
+.YS
+.
+.SY gdiffmk
+.B \-\-help
+.YS
+.
+.SY gdiffmk
+.B \-\-version
+.YS
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B gdiffmk
+compares two
+.BR groff (1),
+.BR nroff (1),
+or
+.BR troff (1)
+documents,
+.I file1
+and
+.IR file2 ,
+and creates an output which is
+.I file2
+with added \[lq]margin character\[rq] (.mc) commands that indicate the
+differences.
+.
+.
+.LP
+If the
+.I output
+filename is present,
+the output is written there.
+.
+If it is
+.B \-
+or absent the output is written to the standard output.
+.
+.
+.LP
+If the
+.I file1
+or
+.I file2
+argument is
+.B \-
+the standard input is read for that input.
+.
+Clearly both cannot be
+.BR \- .
+.
+.
+.LP
+Note that the output is not necessarily compatible with all macro packages
+and all preprocessors.
+.
+See section \(lqBugs\(rq below.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.TP
+.BI \-a addmark
+Use the
+.I addmark
+for source lines not in
+.I file1
+but present in
+.IR file2 .
+.
+Default:
+.BR + .
+.
+.TP
+.B \-B
+By default, the deleted texts marked by the
+.B \-D
+option end
+with an added troff break command,
+.BR .br ,
+to ensure that the deletions are marked properly.
+.
+This is the only way to guarantee that deletions and small
+changes get flagged.
+.
+This option directs the program not to insert these breaks; it makes
+no sense to use it without
+.BR \-D .
+.
+.TP
+.BI \-c changemark
+Use the
+.I changemark
+for changed source lines.
+.
+Default:
+.BR | .
+.
+.TP
+.BI \-d deletemark
+Use the
+.I deletemark
+for deleted source lines.
+.
+Default:
+.BR * .
+.
+.TP
+.B \-D
+Show the deleted portions from changed and deleted text.
+.
+Default delimiting marks:
+.BR "[[" " \&.\|.\|.\& " "]]" .
+.
+.TP
+.BI \-M "mark1 mark2"
+Change the delimiting marks for the
+.B \-D
+option.
+.
+It makes no sense to use this option without
+.BR \-D .
+.
+.TP
+.BI \-x diffcmd
+Use the
+.I diffcmd
+command to perform the comparison of
+.I file1
+and
+.IR file2 .
+.
+In particular,
+.I diffcmd
+should accept the GNU
+.B diff
+.BI \-D name
+option.
+.
+Default:
+.BR diff (1).
+.
+.TP
+.B \-\-
+All the following arguments are treated as file names,
+even if they begin with
+.BR \- .
+.
+.TP
+.B \-\-help
+Print a usage message on standard error output and exit.
+.
+.TP
+.B \-\-version
+Print version information on the standard output and exit.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+The output is not necessarily compatible with all macro packages
+and all preprocessors.
+.
+A workaround that is often successful against preprocessor problems is
+to run
+.B gdiffmk
+on the output of all the preprocessors instead of the input source.
+.
+.
+.LP
+.B gdiffmk
+relies on the
+.BI \-D name
+option of GNU
+.BR diff (1)
+to make a merged \[lq]#ifdef\[rq] output format.
+.
+It hasn't been tested whether other versions of
+.BR diff (1)
+do support this option.
+.
+See also the
+.BI \-x diffcmd
+option.
+.
+.
+.\" ====================================================================
+.SH AUTHORS
+.\" ====================================================================
+.B gdiffmk
+was written and is maintained by
+.MT MBianchi@\:Foveal.com
+Mike Bianchi
+.ME .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR groff (1),
+.BR nroff (1),
+.BR gtroff (1),
+.BR diff (1)
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/gemtopbm.1 b/upstream/mageia-cauldron/man1/gemtopbm.1
new file mode 100644
index 00000000..08b60fe1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gemtopbm.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Gemtopbm User Manual" 0 "May 2000" "netpbm documentation"
+
+.SH NAME
+
+gemtopbm - replaced by gemtopnm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBgemtopbm\fP was replaced in Netpbm 9.1 (May 2000) by 
+.BR "gemtopnm" (1)\c
+\&.
+.PP
+\fBgemtopnm\fP is backward compatible with \fBgemtopbm\fP, but
+works on color images as well.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/gemtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/gemtopnm.1 b/upstream/mageia-cauldron/man1/gemtopnm.1
new file mode 100644
index 00000000..e3d8c3d1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gemtopnm.1
@@ -0,0 +1,67 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Gemtopnm User Manual" 0 "30 April 2000" "netpbm documentation"
+
+.SH NAME
+gemtopnm - convert a GEM .img file into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBgemtopnm\fP
+[\fB-d\fP]
+[\fIgemfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBgemtopnm\fP reads a GEM .img file, either the one plane
+(black/white) or four plane (16 color) varieety, as input and produces
+a PBM or PPM file as output, depending on whether the input is one or
+four plane.
+.PP
+The input file is \fIgemfile\fP if you specify that argument, or
+Standard Input otherwise.  Output is to Standard Output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBgemtopnm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-d\fP
+Produce output describing the contents of the .img file.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtogem" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1988 Diomidis D. Spinellis (\fIdds@cc.ic.ac.uk\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/gemtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/genhostid.1 b/upstream/mageia-cauldron/man1/genhostid.1
new file mode 100644
index 00000000..436d9537
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/genhostid.1
@@ -0,0 +1,12 @@
+.TH GENHOSTID 1
+.SH NAME
+genhostid \- generate and set a hostid for the current host
+.SH SYNOPSIS
+.B genhostid
+
+.SH DESCRIPTION
+\fBgenhostid\fR generates a random hostid and stores it in /etc/hostid,
+if /etc/hostid does not already exist.
+
+.SH "SEE ALSO"
+hostid(1), gethostid(2), sethostid(2)
diff --git a/upstream/mageia-cauldron/man1/gettext.1 b/upstream/mageia-cauldron/man1/gettext.1
new file mode 100644
index 00000000..005c1eff
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gettext.1
@@ -0,0 +1,74 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH GETTEXT "1" "October 2022" "GNU gettext-runtime 0.21.1" "User Commands"
+.SH NAME
+gettext \- translate message
+.SH SYNOPSIS
+.B gettext
+[\fI\,OPTION\/\fR] [[\fI\,TEXTDOMAIN\/\fR] \fI\,MSGID\/\fR]
+.br
+.B gettext
+[\fI\,OPTION\/\fR] \fI\,-s \/\fR[\fI\,MSGID\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+The \fBgettext\fP program translates a natural language message into the
+user's language, by looking up the translation in a message catalog.
+.PP
+Display native language translation of a textual message.
+.TP
+\fB\-d\fR, \fB\-\-domain\fR=\fI\,TEXTDOMAIN\/\fR
+retrieve translated messages from TEXTDOMAIN
+.TP
+\fB\-c\fR, \fB\-\-context\fR=\fI\,CONTEXT\/\fR
+specify context for MSGID
+.TP
+\fB\-e\fR
+enable expansion of some escape sequences
+.TP
+\fB\-n\fR
+suppress trailing newline
+.TP
+\fB\-E\fR
+(ignored for compatibility)
+.TP
+[TEXTDOMAIN] MSGID
+retrieve translated message corresponding
+to MSGID from TEXTDOMAIN
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+display version information and exit
+.PP
+If the TEXTDOMAIN parameter is not given, the domain is determined from the
+environment variable TEXTDOMAIN.  If the message catalog is not found in the
+regular directory, another location can be specified with the environment
+variable TEXTDOMAINDIR.
+When used with the \fB\-s\fR option the program behaves like the 'echo' command.
+But it does not simply copy its arguments to stdout.  Instead those messages
+found in the selected catalog are translated.
+Standard search directory: /usr/share/locale
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B gettext
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B gettext
+programs are properly installed at your site, the command
+.IP
+.B info gettext
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/gettextize.1 b/upstream/mageia-cauldron/man1/gettextize.1
new file mode 100644
index 00000000..ca63ea81
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gettextize.1
@@ -0,0 +1,56 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH GETTEXTIZE "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+gettextize \- install or upgrade gettext infrastructure
+.SH SYNOPSIS
+.B gettextize
+[\fI\,OPTION\/\fR]... [\fI\,package-dir\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Prepares a source package to use gettext.
+.SH OPTIONS
+.TP
+\fB\-\-help\fR
+print this help and exit
+.TP
+\fB\-\-version\fR
+print version information and exit
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+force writing of new files even if old exist
+.TP
+\fB\-\-po\-dir\fR=\fI\,DIR\/\fR
+specify directory with PO files
+.TP
+\fB\-\-no\-changelog\fR
+don't update or create ChangeLog files
+.TP
+\fB\-\-symlink\fR
+make symbolic links instead of copying files
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+print modifications but don't perform them
+.SH AUTHOR
+Written by Ulrich Drepper
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B gettextize
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B gettextize
+programs are properly installed at your site, the command
+.IP
+.B info gettextize
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/giftopnm.1 b/upstream/mageia-cauldron/man1/giftopnm.1
new file mode 100644
index 00000000..36df904c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/giftopnm.1
@@ -0,0 +1,235 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Giftopnm User Manual" 0 "13 September 2012" "netpbm documentation"
+
+.SH NAME
+giftopnm - convert a GIF file into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBgiftopnm\fP
+[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fB-verbose\fP]
+[\fB-comments\fP]
+[\fB-image=\fP{\fIN\fP,\fBall\fP}]
+[\fB-repair\fP]
+[\fB-quitearly\fP]
+[\fIGIFfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This is a graphics format converter from the GIF format to the PNM 
+(i.e. PBM, PGM, or PPM) format.
+.PP
+If the image contains only black and maximally bright white, the
+output is PBM.  If the image contains more than those two colors, but
+only grays, the output is PGM.  If the image contains other colors,
+the output is PPM.
+.PP
+ A GIF image contains rectangular pixels.  They all have the same
+aspect ratio, but may not be square (it's actually quite unusual for
+them not to be square, but it could happen).  The pixels of a Netpbm
+image are always square.  Because of the engineering complexity to do
+otherwise, \fBgiftopnm\fP converts a GIF image to a Netpbm image
+pixel-for-pixel.  This means if the GIF pixels are not square, the
+Netpbm output image has the wrong aspect ratio.  In this case,
+\fBgiftopnm\fP issues an informational message telling you to run
+\fBpamscale\fP to correct the output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBgiftopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB--alphaout=\fP\fIalpha-filename\fP
+\fBgiftopnm \fP creates a PBM file containing the transparency
+information from the input image.  This transparency image is the same
+dimensions as the input image, and each pixel of the transparency image tells
+whether the corresponding pixel of the input image is transparent.  Black
+means transparent; white means opaque.  If you don't
+specify \fB--alphaout\fP, \fBgiftopnm\fP does not generate a transparency
+file, and if the input image has a transparency channel, \fBgiftopnm\fP simply
+discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBgiftopnm\fP writes the
+transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.  
+
+.TP
+\fB-verbose\fP
+Produce verbose output about the GIF file input.
+
+.TP
+\fB-comments\fP
+With this option, \fBgiftopnm\fP issues messages showing the GIF comments
+(A GIF89 stream can contain comments in comment extensions).
+.sp
+By default, \fBgiftopnm\fP ignores comment extensions.
+
+
+.TP
+\fB-image=\fP{\fIN\fP,\fBall\fP}
+This option identifies which image from the GIF stream you want.  
+You can select either one image or all the images.  Select all the 
+images with \fBall\fP.  Select one image by specifying its sequence
+number in the stream: \fB1\fP, \fB2\fP, \fB3\fP, etc.
+.sp
+The default is just Image 1.
+.sp
+A GIF stream normally contains only one image, so you don't need
+this option.  But some streams, including animated GIFs, have multiple
+images.
+.sp
+When you select multiple GIF images, the output is a PNM stream with
+multiple images.
+.sp
+If you specify a single image, \fBgiftopnm\fP must read and
+partially validate the images before that in the stream.  It may or may
+not do the same for the images after it; see \fB-quitearly\fP.
+.sp
+The \fBall\fP value was added in Netpbm 10.16 (June 2003).  Earlier
+\fBgiftopnm\fP can extract only one image.
+
+.TP
+\fB-repair\fP
+This option makes \fBgiftopnm\fP try to salvage what it can from an
+invalid GIF input.
+.sp
+In particular, when \fBgiftopnm\fP detects that the GIF input is
+invalid so that it is impossible to determine what the pixels are
+intended to be, it produces a single arbitrary color for all further
+pixels in the image.  \fBgiftopnm\fP processes the image from top to
+bottom, left to right, so this means the bottommost pixels will be
+this padding.
+.sp
+\fBgiftopnm\fP issues warning messages when it salvages an image
+in this way.
+.sp
+Without this option, \fBgiftopnm\fP fails when it detects invalid
+GIF input.  Any output it produces is arbitrary, and typically is not
+a valid PNM image.
+.sp
+It is fairly common for an image to be corrupted such that is
+started off as a valid GIF, but had the end of the file cut off.  An
+interrupted network transfer tends to do this.  In this case,
+\fBgiftopnm\fP's salvage operation will produce a valid PNM image of
+the proper dimensions, but with a single arbitrary color for the pixels
+that were left out of the file.
+.sp
+This option was new in Netpbm 10.38 (March 2007).  From 10.32 through
+10.37, \fBgiftopnm\fP always fails if it detects invalid GIF input.
+Before 10.32, it succeeds in the case of a truncated image, and replaces
+the missing pixels with arbitrary colors, not necessarily all the same
+(The pre-10.32 behavior wasn't actually intended by the design).
+
+
+.TP
+\fB-quitearly\fP
+This option makes \fBgiftopnm\fP stop reading its input file as soon
+as it has converted and output the images from the input that you requested.
+By default, \fBgiftopnm\fP reads until the end of the GIF stream, ignoring
+any data after the images you requested.
+.sp
+Two reasons \fInot\fP to use this option:
+
+.IP \(bu
+The input file is a pipe and the process that is filling that pipe
+expects the pipe to take the entire stream and will fail or get stuck
+if it doesn't.
+
+.IP \(bu
+You want to validate the entire GIF stream.
+
+
+.sp
+Two reasons to use this option:
+
+
+.IP \(bu
+It saves the time and other resources to read the end of the stream.
+.IP \(bu
+There are errors in the end of the stream that make \fBgiftopnm\fP fail.
+
+.sp
+This option has no effect if you also specify \fB-image=all\fP
+.sp
+This option was new in Netpbm 10.35 (August 2006).  Before that, 
+\fBgiftopnm\fP always reads the entire stream.
+     
+
+
+.UN restrictions
+.SH RESTRICTIONS
+.PP
+This does not correctly handle the Plain Text Extension of the
+GIF89 standard, since I did not have any example input files
+containing them.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtogif" (1)\c
+\&,
+.BR "ppmcolormask" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.UR http://www.lcdf.org/gifsicle
+http://www.lcdf.org/gifsicle
+.UE
+\&,
+.BR "ppm" (1)\c
+\&.
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (c) 1993 by David Koblas (\fIkoblas@netcom.com\fP)
+
+.UN license
+.SH LICENSE
+.PP
+As a historical note, for a long time if you used \fBgiftopnm\fP,
+you were using a patent on the LZW compression method which was owned
+by Unisys, and in all probability you did not have a license from
+Unisys to do so.  Unisys typically asked $5000 for a license for
+trivial use of the patent.  Unisys never enforced the patent against
+trivial users, and made statements that it is much less concerned
+about people using the patent for decompression (which is what
+\fBgiftopnm\fP does than for compression.  The patent expired in
+2003.
+.PP
+Rumor has it that IBM also owns a patent covering \fBgiftopnm\fP.
+.PP
+A replacement for the GIF format that has never required any patent
+license to use is the PNG format.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/giftopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/gnumeric.1 b/upstream/mageia-cauldron/man1/gnumeric.1
new file mode 100644
index 00000000..05cfaa29
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gnumeric.1
@@ -0,0 +1,199 @@
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH GNUMERIC 1 "2009-02-08" gnumeric "GNOME"
+.SH NAME
+gnumeric \- a GNOME spreadsheet application.
+
+.SH SYNOPSIS
+\fBgnumeric\fR [\fIOPTIONS\fR] [\fIfiles\fR \fI...\fR ]
+
+.SH DESCRIPTION
+\fBGnumeric\fR is a powerful spreadsheet program created by the GNOME
+project. \fBGnumeric\fR intends to compete with commercial
+spreadsheets by becoming fully compatible with Microsoft Excel(TM) and
+through the support of most popular spreadsheet file formats such as
+Excel(TM), Lotus 1-2-3(TM), Applix(TM), Sylk(TM), XBase(TM),
+Oleo(TM) and OpenOffice.org formats.
+
+\fBGnumeric\fR supports advanced calculations using statistical,
+financial and database access functions. Plotting data is supported
+through an incomplete but powerful plotting system. A plugin system
+extends \fBgnumeric\fR , for instance enabling the export of data to
+the LaTeX \\longtable format. Plugins can be used to define custom
+functionality. A rudimentary scripting API for the Python language
+exists and will be extended in the near future. Since \fBgnumeric\fR
+is \fBfree\fR software, \fBgnumeric\fR can also be extended directly
+at the source code level by any competent programmer.
+
+The program can be started from the command line as \fBgnumeric\fR or
+from one of the menus provided by the underlying platform. When started
+on the command line, \fBgnumeric\fR may be followed by the options listed
+below and possibly the names of files in various spreadsheet formats
+which will then be opened immediately. For instance, the command:
+
+    gnumeric myfile.gnumeric
+
+will launch \fBgnumeric\fR and open the file called
+"myfile.gnumeric". The default \fBgnumeric\fR file format is in
+extensible markup language (XML) which subsequently has been
+compressed with \fBgzip\fR.
+
+.SH USER OPTIONS
+This program follows the usual GNU command line syntax, with single
+letter options starting with a single dash (`-') and longer options
+starting with two dashes (`--').
+
+.SS "Help options"
+.B \-?, \-\-help
+Show help message.
+.TP
+.B \-\-usage
+Displays a brief usage message.
+
+.SS "Gnumeric options"
+.TP
+.B \-v, \-\-version
+Displays the version number of the installed instance of
+\fBgnumeric\fR.
+.TP
+.B \-\-no-splash
+Start \fBgnumeric\fR without showing the splash screen.  The splash 
+screen is normally shown if loading files takes too long.
+
+.SS "Options for window placement"
+.TP
+\fB\-g, \-\-geometry=WIDTHxHEIGHT+XOFF+YOFF 
+Set the size and position of the first window. All units are in
+pixels. The X offset is from the left hand side of the screen, the Y
+offset is from the top of the screen. For example, \-g=800x600+20+30
+will open a gnumeric window 800 pixels wide by 600 pixels high, with
+the left edge of gnumeric 20 pixels from the left of the screen and
+the top edge of gnumeric 30 pixels from the top of the screen.
+.TP
+.B \fB\-\-display=\fR\fIDISPLAY\fR
+X display to use, where DISPLAY has the form
+machinename:Xdisplay.Screen. Note that the machine displaying gnumeric
+must have granted the machine running gnumeric the right to display
+(see xhost).
+
+.TP 
+.B \fB\-\-screen=\fR\fISCREEN\fR
+X screen to use, a more compact form of the functionality described
+above.
+
+
+
+
+.SH ADVANCED OPTIONS
+
+.SS "GNOME options"
+.TP
+.B \-\-disable-sound
+Disable sound server usage.
+.TP
+.B \-\-enable-sound
+Enable sound server usage.
+.TP
+\fB\-\-espeaker=\fR\fIHOSTNAME:PORT\fR
+Host:port on which the sound server to use is running.
+.TP
+.B \-\-disable-crash-dialog
+Disable the bug submission dialog which appears if Gnumeric crashes.
+
+.SS "GTK options"
+.TP
+\fB\-\-gdk-debug=\fR\fIFLAGS\fR
+Gdk debugging flags to set.
+.TP
+\fB\-\-gdk-no-debug=\fR\fIFLAGS\fR
+Gdk debugging flags to unset.
+.TP
+.B \-\-sync
+Make X calls synchronous.
+.TP
+\fB\-\-name=\fR\fINAME\fR
+Program name as used by the window manager.
+.TP
+\fB\-\-class=\fR\fICLASS\fR
+Program class as used by the window manager.
+.TP
+\fB\-\-gxid_host=\fR\fIHOST\fR
+The host on which to contact the gxid daemon. This overrides the GXID_HOST environment variable. This option is only available if GTK+ has been configured with \-\-gdk-target=x11.
+.TP
+\fB\-\-gxid_port=\fR\fIPORT\fR
+The port for the connection to gxid. This overrides the GXID_PORT environment variable. This option is only available if GTK+ has been configured with \-\-gdk-target=x11.
+.TP
+\fB\-\-gtk-debug=\fR\fIFLAGS\fR
+Gtk+ debugging flags to set.
+.TP
+\fB\-\-gtk-no-debug=\fR\fIFLAGS\fR
+Gtk+ debugging flags to unset.
+.TP
+\fB\-\-g-fatal-warnings\fR
+Make all warnings fatal.
+.TP
+\fB\-\-gtk-module=\fR\fIMODULE\fR
+Load an additional Gtk module.
+
+.SS "Session management options"
+.TP
+\fB\-\-sm-client-id=\fR\fIID\fR
+Specify session management ID.
+.TP
+\fB\-\-sm-config-prefix=\fR\fIPREFIX\fR
+Specify prefix of saved configuration.
+.TP
+.B \-\-sm-disable
+Disable connection to session manager.
+
+
+.SH VERSION
+This manual page describes \fBgnumeric\fR version 1.8.
+
+.SH BUGS
+For the list of known \fBgnumeric\fR bugs, or to report new ones
+please visit \fIhttp://bugzilla.gnome.org\fR.
+
+.SH "SEE ALSO"
+\fBssconvert\fR(1),
+\fBssindex\fR(1),
+\fBssdiff\fR(1)
+\fBssgrep\fR(1)
+.PP
+.B The Gnumeric Manual
+Available through the \fBHelp\fR menu or 
+.URL "http://www.gnome.org/projects/gnumeric/doc/gnumeric.shtml" online .
+.PP
+.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" .
+.PP
+.URL "http://www.gnome.org/" "The GNOME project page" .
+
+.SH LICENSE
+
+\fBGnumeric\fR is licensed under the terms of the General Public
+License (GPL), version 2 or 3. For information on this license look at the
+source code that came with the software or see the 
+.URL "http://www.gnu.org/" "GNU project page" .
+
+.SH COPYRIGHT
+
+The copyright on the \fBgnumeric\fR software and source code is held
+by the individual authors as is documented in the source code.
+
+
+.SH AUTHORS
+.SS "Gnumeric"
+Jody Goldberg <jody@gnome.org>
+.br
+Miguel de Icaza <miguel@gnome.org>
+.br
+Morten Welinder <terra@gnome.org>
+.br
+
+-- and many others.  For a more complete list, see the About dialog.
+.SS "This manual page"
+Jan Schaumann <jschauma@netmeister.org>
+.br
+Adrian Custer <acuster@gnome.org>
diff --git a/upstream/mageia-cauldron/man1/gouldtoppm.1 b/upstream/mageia-cauldron/man1/gouldtoppm.1
new file mode 100644
index 00000000..db7bc896
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gouldtoppm.1
@@ -0,0 +1,52 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Gouldtoppm User Manual" 0 "20 May 1990" "netpbm documentation"
+
+.SH NAME
+gouldtoppm - convert Gould scanner file into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBgouldtoppm\fP
+[\fIgouldfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBgouldtoppm\fP reads a file produced by the Gould scanner as
+input and produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBgouldtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright(C) 1990 by Stephen Paul Lesniewski
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/gouldtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/gpm-root.1 b/upstream/mageia-cauldron/man1/gpm-root.1
new file mode 100644
index 00000000..6df6f2fa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gpm-root.1
@@ -0,0 +1,230 @@
+.TH GPM-ROOT 1 "February 1995"
+.UC 4
+.SH NAME
+gpm-root \- a default handler for gpm, used to draw menus on
+the root window
+.SH SYNOPSIS
+.B gpm-root
+[
+.I options
+]
+.br
+.SH DESCRIPTION
+
+.LP
+The program gpm-root is designed to handle Control-Mouse events to
+draw menus on the background of the current tty. The actual menus
+are described by a configuration file in the user's home directory.
+
+.LP
+Please note that gpm-root needs to run with Linux 1.1.73 or
+newer, because previous kernels lack some screen handling capabilities
+required by the program.
+
+.LP
+The program uses the files /dev/vcs* to draw to the console screen.
+These are available only from kernel 1.1.81 onward. If you miss those
+device nodes, you should create them using create_vcs in the
+distribution directory. The tool won't run with kernels older than 1.1.81,
+because they lacked a full screen dump/restore capability.
+
+.LP
+Available command line options are the following:
+.TP
+-m \fBnumber\fP
+Choose the modifier to use (by default: control). The modifier
+can be provided either as a number or as a symbolic string.
+Allowed strings are shift, anyAlt, leftAlt,
+rightAlt, control.
+.TP
+-u
+Deny using user-specific configuration files. With this
+option on, only /etc/gpm-root.conf will be used as a source
+of configuration information. This option
+is intended for those system administrators who fear security could
+be broken by this daemon. Things should be sufficiently secure, but
+if you find a hole please tell me about it.
+.TP
+-D
+Do not automatically enter background operation when started,
+and log messages to the standard error stream, not the syslog
+mechanism.  This is useful for debugging; in previous releases
+it was done with a compile-time option.
+.TP
+-V \fBverbosity increment\fP
+Raise the maximum level of messages that will be logged.  Thus a
+positive argument has the effect of making the program more
+verbose.  One can also give a negative argument to hush the
+program; however, note that due to \fBgetopt(3)\fP rules a negative
+argument must follow the option with no space betwixt (that is,
+-V-1 but not -V -1).  Program Arguments,,,libc.
+The argument is optional and its default value is 1.
+
+.LP
+Each time a menu is drawn, the configuration file is reparsed if it has
+changed. This allows modification of personal setup without reinvoking
+the daemon.
+
+.LP
+The actual configuration file is better introduced by looking at your
+/etc/gpm-root.conf.
+.fi
+
+.LP
+The syntax for the file won't be described here, being it quite apparent
+from the example above. Blanks and newlines are unused in parsing the
+file, and the layout of the file is free. Comments are allowed in the
+file: any hash mark (#) found at the beginning of the line or
+after white space makes the parser discard anything up to the next
+line. To insert quotes (") in strings precede them with a backslash.
+
+.LP
+Note that recursive menus are allowed, to any level of recursion.
+
+.LP
+Keywords belong to three groups: the button keyword, the cfg
+keywords and the action keywords. They are all described in the table
+below:
+.TP
+button \fBnumber\fP \fBmenu\fP
+The button keyword is used to introduce a menu. It is
+followed by the number of the relevant button (1=left,
+2=middle, 3=right), an open brace, a menu and a closed brace.
+A menu is made up of cfg statements, followed by
+action statements. Cfg statements can come in any order,
+while the order of action statements tells the actual order
+in which actions will appear on the screen, top to bottom.
+
+.LP
+The following statements belong to the cfg set.
+.TP
+name \fBstring\fP
+If the name keyword is present, the specified
+\fBstring\fP will be used as the name for the current menu.
+.TP
+background \fBcolor\fP
+This statements is used to specify the
+background color to be used in the current menu. The \fBcolor\fP
+can be specified with one of the eight canonical strings black,
+red, cyan etc. The background defaults to black.
+.TP
+foreground \fBcolor\fP
+This statements is used to specify the
+foreground color for menu items. Its value defaults to white.
+An optional bright keyword can appear before the actual color.
+.TP
+border \fBcolor\fP
+border is used to specify the
+border color for the menu. Its value defaults to white.
+An optional bright keyword can appear before the actual color.
+.TP
+head \fBcolor\fP
+head is used to specify the
+foreground color for the title of the menu. Its value defaults
+to white.
+An optional bright keyword can appear before the actual color.
+
+.LP
+The following statements belong to the action set.
+.TP
+\fBstring\fP f.fgcmd \fBcmdstring\fP
+When the mouse button is
+released above the corresponding menu item, the \fBcmdstring\fP is
+pasted in the keyboard queue of the current console. This is
+not yet implemented.
+.TP
+\fBstring\fP f.bgcmd \fBcmdstring\fP
+When the mouse button is released above the
+corresponding menu item, a shell (/bin/sh) is forked to
+execute the specified command, with stdin
+connected to /dev/null, and stdout, stderr connected
+to the active console.
+.TP
+\fBstring\fP f.jptty \fBttynumber\fP
+When the mouse button is
+released above the corresponding menu item, the console is
+switched to the one specified. The \fBttynumber\fP must be specified
+as a string. Any tty can be reached this way, even those which are
+not accessible via the keyboard.
+.TP
+\fBstring\fP f.mktty \fBttynumber\fP
+When the mouse button is
+released above the corresponding menu item, an unused console is
+selected, and /sbin/mingetty is executed in it. The current console
+is switched to the newly opened console. I use this command to save
+kernel memory by opening a single console through /etc/inittab
+and requesting the others only when i need to login.
+.TP
+\fBstring\fP \fBWhole-menu\fP
+A menu can directly follow the label string.
+When the mouse pointer leaves the menu frame at the level of \fBstring\fP,
+a second menu is posted on screen.
+.TP
+\fBstring\fP f.lock
+When the mouse button is
+released above the corresponding menu item, the keyboard and the
+screen are locked, and only the locking user or the superuser
+can unlock them. This is not yet implemented.
+.TP
+\fBstring\fP f.load
+The current loadavg when the menu is posted is concatenated to \fBstring\fP
+to build the actual message displayed on screen. Nothing happens at
+button release.
+.TP
+\fBstring\fP f.free
+The free memory and swap when the menu is posted is concatenated
+to \fBstring\fP
+to build the actual message displayed on screen. Nothing happens at
+button release.
+.TP
+\fBstring\fP f.time
+The current time is formatted with \fBstrftime(3)\fP, according to
+\fBstring\fP. The resulting string is
+the actual message displayed on screen. Nothing happens at
+button release.
+.TP
+\fBstring\fP f.pipe \fBcmdline\fP
+When the mouse pointer leaves the menu frame at the level of \fBstring\fP,
+a message box is posted on screen showing the last ten lines
+of the output of \fBcmdline\fP. \fBcmdline\fP is executed
+by /bin/sh. This is not yet implemented.
+
+
+.TP
+\fBstring\fP f.nop
+This does nothing, it only displays \fBstring\fP on the menu.
+
+.LP
+The HOME, LOGNAME and USER environment variables are setup
+to the values for the invoking user before spawning an external
+process (f.bgcmd, f.pipe). The current directory is always /.
+
+.LP
+.SH BUGS
+
+.LP
+Known bugs have been fixed. In particular, if you invoke gpm-root
+right after gpm, it will delay a few seconds before trying to connect
+to the daemon.
+
+.LP
+.SH AUTHOR
+Alessandro Rubini <rubini@linux.it>
+
+.LP
+.SH FILES
+.nf
+/dev/gpmctl     The socket used to connect to gpm.
+/etc/gpm-root.conf  The default configuration file.
+$(HOME)/.gpm-root   The user configuration file.
+/dev/vcs*           Virtual Console Screens
+.fi
+
+.LP
+.SH SEE ALSO
+.nf
+\fB gpm(8) \fP
+
+.fi
+The info file about `gpm', which gives more complete information and
+explains how to write a gpm client.
diff --git a/upstream/mageia-cauldron/man1/gprof.1 b/upstream/mageia-cauldron/man1/gprof.1
new file mode 100644
index 00000000..98733055
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gprof.1
@@ -0,0 +1,776 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "GPROF 1"
+.TH GPROF 1 "2023-01-14" "binutils-2.40.00" "GNU"
+.\" 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"
+gprof \- display call graph profile data
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ABCeEfFJnNOpPqQRStZ][\fIname\fR] ]
+ [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ]
+ [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ]
+ [ \-\-[no\-]annotated\-source[=\fIname\fR] ]
+ [ \-\-[no\-]exec\-counts[=\fIname\fR] ]
+ [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ]
+ [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ]
+ [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ]
+ [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ]
+ [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ]
+ [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-inline\-file\-names ]
+ [ \-\-min\-count=\fIn\fR ] [ \-\-no\-static ] [ \-\-print\-path ]
+ [ \-\-separate\-files ] [ \-\-static\-call\-graph ] [ \-\-sum ]
+ [ \-\-table\-length=\fIlen\fR ] [ \-\-traditional ] [ \-\-version ]
+ [ \-\-width=\fIn\fR ] [ \-\-ignore\-non\-functions ]
+ [ \-\-demangle[=\fI\s-1STYLE\s0\fR] ] [ \-\-no\-demangle ]
+ [\-\-external\-symbol\-table=name]
+ [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77
+programs.  The effect of called routines is incorporated in the profile
+of each caller.  The profile data is taken from the call graph profile file
+(\fIgmon.out\fR default) which is created by programs
+that are compiled with the \fB\-pg\fR option of
+\&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR.
+The \fB\-pg\fR option also links in versions of the library routines
+that are compiled for profiling.  \f(CW\*(C`Gprof\*(C'\fR reads the given object
+file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between
+its symbol table and the call graph profile from \fIgmon.out\fR.
+If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR
+output shows the sum of the profile information in the given profile files.
+.PP
+\&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine.
+Next, these times are propagated along the edges of the call graph.
+Cycles are discovered, and calls into a cycle are made to share the time
+of the cycle.
+.PP
+Several forms of output are available from the analysis.
+.PP
+The \fIflat profile\fR shows how much time your program spent in each function,
+and how many times that function was called.  If you simply want to know
+which functions burn most of the cycles, it is stated concisely here.
+.PP
+The \fIcall graph\fR shows, for each function, which functions called it, which
+other functions it called, and how many times.  There is also an estimate
+of how much time was spent in the subroutines of each function.  This can
+suggest places where you might try to eliminate function calls that use a
+lot of time.
+.PP
+The \fIannotated source\fR listing is a copy of the program's
+source code, labeled with the number of times each line of the
+program was executed.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+These options specify which of several output formats
+\&\f(CW\*(C`gprof\*(C'\fR should produce.
+.PP
+Many of these options take an optional \fIsymspec\fR to specify
+functions to be included or excluded.  These options can be
+specified multiple times, with different symspecs, to include
+or exclude sets of symbols.
+.PP
+Specifying any of these options overrides the default (\fB\-p \-q\fR),
+which prints a flat profile and call graph analysis
+for all functions.
+.ie n .IP """\-A[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-A[symspec]"
+.PD 0
+.ie n .IP """\-\-annotated\-source[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--annotated-source[=symspec]"
+.PD
+The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code.
+If \fIsymspec\fR is specified, print output only for matching symbols.
+.ie n .IP """\-b""" 4
+.el .IP "\f(CW\-b\fR" 4
+.IX Item "-b"
+.PD 0
+.ie n .IP """\-\-brief""" 4
+.el .IP "\f(CW\-\-brief\fR" 4
+.IX Item "--brief"
+.PD
+If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the
+verbose blurbs that try to explain the meaning of all of the fields in
+the tables.  This is useful if you intend to print out the output, or
+are tired of seeing the blurbs.
+.ie n .IP """\-B""" 4
+.el .IP "\f(CW\-B\fR" 4
+.IX Item "-B"
+The \fB\-B\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.
+.ie n .IP """\-C[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-C[symspec]"
+.PD 0
+.ie n .IP """\-\-exec\-counts[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--exec-counts[=symspec]"
+.PD
+The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to
+print a tally of functions and the number of times each was called.
+If \fIsymspec\fR is specified, print tally only for matching symbols.
+.Sp
+If the profile data file contains basic-block count records, specifying
+the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block
+execution counts to be tallied and displayed.
+.ie n .IP """\-i""" 4
+.el .IP "\f(CW\-i\fR" 4
+.IX Item "-i"
+.PD 0
+.ie n .IP """\-\-file\-info""" 4
+.el .IP "\f(CW\-\-file\-info\fR" 4
+.IX Item "--file-info"
+.PD
+The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information
+about the profile data file(s) and then exit.  The number of histogram,
+call graph, and basic-block count records is displayed.
+.ie n .IP """\-I \fIdirs\fP""" 4
+.el .IP "\f(CW\-I \f(CIdirs\f(CW\fR" 4
+.IX Item "-I dirs"
+.PD 0
+.ie n .IP """\-\-directory\-path=\fIdirs\fP""" 4
+.el .IP "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4
+.IX Item "--directory-path=dirs"
+.PD
+The \fB\-I\fR option specifies a list of search directories in
+which to find source files.  Environment variable \fI\s-1GPROF_PATH\s0\fR
+can also be used to convey this information.
+Used mostly for annotated source output.
+.ie n .IP """\-J[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-J[symspec]"
+.PD 0
+.ie n .IP """\-\-no\-annotated\-source[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--no-annotated-source[=symspec]"
+.PD
+The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
+print annotated source code.
+If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source,
+but excludes matching symbols.
+.ie n .IP """\-L""" 4
+.el .IP "\f(CW\-L\fR" 4
+.IX Item "-L"
+.PD 0
+.ie n .IP """\-\-print\-path""" 4
+.el .IP "\f(CW\-\-print\-path\fR" 4
+.IX Item "--print-path"
+.PD
+Normally, source filenames are printed with the path
+component suppressed.  The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR
+to print the full pathname of
+source filenames, which is determined
+from symbolic debugging information in the image file
+and is relative to the directory in which the compiler
+was invoked.
+.ie n .IP """\-p[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-p[symspec]"
+.PD 0
+.ie n .IP """\-\-flat\-profile[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--flat-profile[=symspec]"
+.PD
+The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile.
+If \fIsymspec\fR is specified, print flat profile only for matching symbols.
+.ie n .IP """\-P[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-P[symspec]"
+.PD 0
+.ie n .IP """\-\-no\-flat\-profile[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--no-flat-profile[=symspec]"
+.PD
+The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile.
+If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile,
+but excludes matching symbols.
+.ie n .IP """\-q[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-q[symspec]"
+.PD 0
+.ie n .IP """\-\-graph[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--graph[=symspec]"
+.PD
+The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.
+If \fIsymspec\fR is specified, print call graph only for matching symbols
+and their children.
+.ie n .IP """\-Q[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-Q[symspec]"
+.PD 0
+.ie n .IP """\-\-no\-graph[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--no-graph[=symspec]"
+.PD
+The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the
+call graph.
+If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph,
+but excludes matching symbols.
+.ie n .IP """\-t""" 4
+.el .IP "\f(CW\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.ie n .IP """\-\-table\-length=\fInum\fP""" 4
+.el .IP "\f(CW\-\-table\-length=\f(CInum\f(CW\fR" 4
+.IX Item "--table-length=num"
+.PD
+The \fB\-t\fR option causes the \fInum\fR most active source lines in
+each source file to be listed when source annotation is enabled.  The
+default is 10.
+.ie n .IP """\-y""" 4
+.el .IP "\f(CW\-y\fR" 4
+.IX Item "-y"
+.PD 0
+.ie n .IP """\-\-separate\-files""" 4
+.el .IP "\f(CW\-\-separate\-files\fR" 4
+.IX Item "--separate-files"
+.PD
+This option affects annotated source output only.
+Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files
+to standard-output.  If this option is specified,
+annotated source for a file named \fIpath/\fIfilename\fI\fR
+is generated in the file \fI\fIfilename\fI\-ann\fR.  If the underlying
+file system would truncate \fI\fIfilename\fI\-ann\fR so that it
+overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates
+annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the
+original file name has an extension, that extension is \fIreplaced\fR
+with \fI.ann\fR).
+.ie n .IP """\-Z[\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4
+.IX Item "-Z[symspec]"
+.PD 0
+.ie n .IP """\-\-no\-exec\-counts[=\fIsymspec\fP]""" 4
+.el .IP "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
+.IX Item "--no-exec-counts[=symspec]"
+.PD
+The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
+print a tally of functions and the number of times each was called.
+If \fIsymspec\fR is specified, print tally, but exclude matching symbols.
+.ie n .IP """\-r""" 4
+.el .IP "\f(CW\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.ie n .IP """\-\-function\-ordering""" 4
+.el .IP "\f(CW\-\-function\-ordering\fR" 4
+.IX Item "--function-ordering"
+.PD
+The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
+suggested function ordering for the program based on profiling data.
+This option suggests an ordering which may improve paging, tlb and
+cache behavior for the program on systems which support arbitrary
+ordering of functions in an executable.
+.Sp
+The exact details of how to force the linker to place functions
+in a particular order is system dependent and out of the scope of this
+manual.
+.ie n .IP """\-R \fImap_file\fP""" 4
+.el .IP "\f(CW\-R \f(CImap_file\f(CW\fR" 4
+.IX Item "-R map_file"
+.PD 0
+.ie n .IP """\-\-file\-ordering \fImap_file\fP""" 4
+.el .IP "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4
+.IX Item "--file-ordering map_file"
+.PD
+The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
+suggested .o link line ordering for the program based on profiling data.
+This option suggests an ordering which may improve paging, tlb and
+cache behavior for the program on systems which do not support arbitrary
+ordering of functions in an executable.
+.Sp
+Use of the \fB\-a\fR argument is highly recommended with this option.
+.Sp
+The \fImap_file\fR argument is a pathname to a file which provides
+function name to object file mappings.  The format of the file is similar to
+the output of the program \f(CW\*(C`nm\*(C'\fR.
+.Sp
+.Vb 8
+\&        c\-parse.o:00000000 T yyparse
+\&        c\-parse.o:00000004 C yyerrflag
+\&        c\-lang.o:00000000 T maybe_objc_method_name
+\&        c\-lang.o:00000000 T print_lang_statistics
+\&        c\-lang.o:00000000 T recognize_objc_keyword
+\&        c\-decl.o:00000000 T print_lang_identifier
+\&        c\-decl.o:00000000 T print_lang_type
+\&        ...
+.Ve
+.Sp
+To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like
+\&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR.
+.ie n .IP """\-T""" 4
+.el .IP "\f(CW\-T\fR" 4
+.IX Item "-T"
+.PD 0
+.ie n .IP """\-\-traditional""" 4
+.el .IP "\f(CW\-\-traditional\fR" 4
+.IX Item "--traditional"
+.PD
+The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in
+\&\*(L"traditional\*(R" \s-1BSD\s0 style.
+.ie n .IP """\-w \fIwidth\fP""" 4
+.el .IP "\f(CW\-w \f(CIwidth\f(CW\fR" 4
+.IX Item "-w width"
+.PD 0
+.ie n .IP """\-\-width=\fIwidth\fP""" 4
+.el .IP "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4
+.IX Item "--width=width"
+.PD
+Sets width of output lines to \fIwidth\fR.
+Currently only used when printing the function index at the bottom
+of the call graph.
+.ie n .IP """\-x""" 4
+.el .IP "\f(CW\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.ie n .IP """\-\-all\-lines""" 4
+.el .IP "\f(CW\-\-all\-lines\fR" 4
+.IX Item "--all-lines"
+.PD
+This option affects annotated source output only.
+By default, only the lines at the beginning of a basic-block
+are annotated.  If this option is specified, every line in
+a basic-block is annotated by repeating the annotation for the
+first line.  This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR.
+.ie n .IP """\-\-demangle[=\fIstyle\fP]""" 4
+.el .IP "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4
+.IX Item "--demangle[=style]"
+.PD 0
+.ie n .IP """\-\-no\-demangle""" 4
+.el .IP "\f(CW\-\-no\-demangle\fR" 4
+.IX Item "--no-demangle"
+.PD
+These options control whether \*(C+ symbol names should be demangled when
+printing output.  The default is to demangle symbols.  The
+\&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different
+compilers have different mangling styles.  The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler.
+.SS "Analysis Options"
+.IX Subsection "Analysis Options"
+.ie n .IP """\-a""" 4
+.el .IP "\f(CW\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.ie n .IP """\-\-no\-static""" 4
+.el .IP "\f(CW\-\-no\-static\fR" 4
+.IX Item "--no-static"
+.PD
+The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of
+statically declared (private) functions.  (These are functions whose
+names are not listed as global, and which are not visible outside the
+file/function/block where they were defined.)  Time spent in these
+functions, calls to/from them, etc., will all be attributed to the
+function that was loaded directly before it in the executable file.
+This option affects both the flat profile and the call graph.
+.ie n .IP """\-c""" 4
+.el .IP "\f(CW\-c\fR" 4
+.IX Item "-c"
+.PD 0
+.ie n .IP """\-\-static\-call\-graph""" 4
+.el .IP "\f(CW\-\-static\-call\-graph\fR" 4
+.IX Item "--static-call-graph"
+.PD
+The \fB\-c\fR option causes the call graph of the program to be
+augmented by a heuristic which examines the text space of the object
+file and identifies function calls in the binary machine code.
+Since normal call graph records are only generated when functions are
+entered, this option identifies children that could have been called,
+but never were.  Calls to functions that were not compiled with
+profiling enabled are also identified, but only if symbol table
+entries are present for them.
+Calls to dynamic library routines are typically \fInot\fR found
+by this option.
+Parents or children identified via this heuristic
+are indicated in the call graph with call counts of \fB0\fR.
+.ie n .IP """\-D""" 4
+.el .IP "\f(CW\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.ie n .IP """\-\-ignore\-non\-functions""" 4
+.el .IP "\f(CW\-\-ignore\-non\-functions\fR" 4
+.IX Item "--ignore-non-functions"
+.PD
+The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which
+are not known to be functions.  This option will give more accurate
+profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for
+example).
+.ie n .IP """\-k \fIfrom\fP/\fIto\fP""" 4
+.el .IP "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4
+.IX Item "-k from/to"
+The \fB\-k\fR option allows you to delete from the call graph any arcs from
+symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR.
+.ie n .IP """\-l""" 4
+.el .IP "\f(CW\-l\fR" 4
+.IX Item "-l"
+.PD 0
+.ie n .IP """\-\-line""" 4
+.el .IP "\f(CW\-\-line\fR" 4
+.IX Item "--line"
+.PD
+The \fB\-l\fR option enables line-by-line profiling, which causes
+histogram hits to be charged to individual source code lines,
+instead of functions.  This feature only works with programs compiled
+by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler.  Newer versions of
+\&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead.
+.Sp
+If the program was compiled with basic-block counting enabled,
+this option will also identify how many times each line of
+code was executed.
+While line-by-line profiling can help isolate where in a large function
+a program is spending its time, it also significantly increases
+the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical
+inaccuracies.
+.ie n .IP """\-\-inline\-file\-names""" 4
+.el .IP "\f(CW\-\-inline\-file\-names\fR" 4
+.IX Item "--inline-file-names"
+This option causes \f(CW\*(C`gprof\*(C'\fR to print the source file after each
+symbol in both the flat profile and the call graph. The full path to the
+file is printed if used with the \fB\-L\fR option.
+.ie n .IP """\-m \fInum\fP""" 4
+.el .IP "\f(CW\-m \f(CInum\f(CW\fR" 4
+.IX Item "-m num"
+.PD 0
+.ie n .IP """\-\-min\-count=\fInum\fP""" 4
+.el .IP "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4
+.IX Item "--min-count=num"
+.PD
+This option affects execution count output only.
+Symbols that are executed less than \fInum\fR times are suppressed.
+.ie n .IP """\-n\fIsymspec\fP""" 4
+.el .IP "\f(CW\-n\f(CIsymspec\f(CW\fR" 4
+.IX Item "-nsymspec"
+.PD 0
+.ie n .IP """\-\-time=\fIsymspec\fP""" 4
+.el .IP "\f(CW\-\-time=\f(CIsymspec\f(CW\fR" 4
+.IX Item "--time=symspec"
+.PD
+The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
+to only propagate times for symbols matching \fIsymspec\fR.
+.ie n .IP """\-N\fIsymspec\fP""" 4
+.el .IP "\f(CW\-N\f(CIsymspec\f(CW\fR" 4
+.IX Item "-Nsymspec"
+.PD 0
+.ie n .IP """\-\-no\-time=\fIsymspec\fP""" 4
+.el .IP "\f(CW\-\-no\-time=\f(CIsymspec\f(CW\fR" 4
+.IX Item "--no-time=symspec"
+.PD
+The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
+not to propagate times for symbols matching \fIsymspec\fR.
+.ie n .IP """\-S\fIfilename\fP""" 4
+.el .IP "\f(CW\-S\f(CIfilename\f(CW\fR" 4
+.IX Item "-Sfilename"
+.PD 0
+.ie n .IP """\-\-external\-symbol\-table=\fIfilename\fP""" 4
+.el .IP "\f(CW\-\-external\-symbol\-table=\f(CIfilename\f(CW\fR" 4
+.IX Item "--external-symbol-table=filename"
+.PD
+The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table
+file, such as \fI/proc/kallsyms\fR, rather than read the symbol table
+from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful
+for profiling kernel modules.
+.ie n .IP """\-z""" 4
+.el .IP "\f(CW\-z\fR" 4
+.IX Item "-z"
+.PD 0
+.ie n .IP """\-\-display\-unused\-functions""" 4
+.el .IP "\f(CW\-\-display\-unused\-functions\fR" 4
+.IX Item "--display-unused-functions"
+.PD
+If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all
+functions in the flat profile, even those that were never called, and
+that had no time spent in them.  This is useful in conjunction with the
+\&\fB\-c\fR option for discovering which routines were never called.
+.SS "Miscellaneous Options"
+.IX Subsection "Miscellaneous Options"
+.ie n .IP """\-d[\fInum\fP]""" 4
+.el .IP "\f(CW\-d[\f(CInum\f(CW]\fR" 4
+.IX Item "-d[num]"
+.PD 0
+.ie n .IP """\-\-debug[=\fInum\fP]""" 4
+.el .IP "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4
+.IX Item "--debug[=num]"
+.PD
+The \fB\-d\fR \fInum\fR option specifies debugging options.
+If \fInum\fR is not specified, enable all debugging.
+.ie n .IP """\-h""" 4
+.el .IP "\f(CW\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.ie n .IP """\-\-help""" 4
+.el .IP "\f(CW\-\-help\fR" 4
+.IX Item "--help"
+.PD
+The \fB\-h\fR option prints command line usage.
+.ie n .IP """\-O\fIname\fP""" 4
+.el .IP "\f(CW\-O\f(CIname\f(CW\fR" 4
+.IX Item "-Oname"
+.PD 0
+.ie n .IP """\-\-file\-format=\fIname\fP""" 4
+.el .IP "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4
+.IX Item "--file-format=name"
+.PD
+Selects the format of the profile data files.  Recognized formats are
+\&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and
+\&\fBprof\fR (not yet supported).
+.ie n .IP """\-s""" 4
+.el .IP "\f(CW\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.ie n .IP """\-\-sum""" 4
+.el .IP "\f(CW\-\-sum\fR" 4
+.IX Item "--sum"
+.PD
+The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information
+in the profile data files it read in, and write out a profile data
+file called \fIgmon.sum\fR, which contains all the information from
+the profile data files that \f(CW\*(C`gprof\*(C'\fR read in.  The file \fIgmon.sum\fR
+may be one of the specified input files; the effect of this is to
+merge the data in the other input files into \fIgmon.sum\fR.
+.Sp
+Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the
+cumulative data in the file \fIgmon.sum\fR.
+.ie n .IP """\-v""" 4
+.el .IP "\f(CW\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.ie n .IP """\-\-version""" 4
+.el .IP "\f(CW\-\-version\fR" 4
+.IX Item "--version"
+.PD
+The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version
+number, and then exit.
+.SS "Deprecated Options"
+.IX Subsection "Deprecated Options"
+These options have been replaced with newer versions that use symspecs.
+.ie n .IP """\-e \fIfunction_name\fP""" 4
+.el .IP "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4
+.IX Item "-e function_name"
+The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print
+information about the function \fIfunction_name\fR (and its
+children...) in the call graph.  The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as \fB[not printed]\fR.  More than one \fB\-e\fR option may be
+given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR
+option.
+.ie n .IP """\-E \fIfunction_name\fP""" 4
+.el .IP "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4
+.IX Item "-E function_name"
+The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but
+time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph.  More than one \fB\-E\fR option may be given; only one
+\&\fIfunction_name\fR may be indicated with each \fB\-E\fR option.
+.ie n .IP """\-f \fIfunction_name\fP""" 4
+.el .IP "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4
+.IX Item "-f function_name"
+The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the
+call graph to the function \fIfunction_name\fR and its children (and
+their children...).  More than one \fB\-f\fR option may be given;
+only one \fIfunction_name\fR may be indicated with each \fB\-f\fR
+option.
+.ie n .IP """\-F \fIfunction_name\fP""" 4
+.el .IP "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4
+.IX Item "-F function_name"
+The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but
+only time spent in the function and its children (and their
+children...) will be used to determine total-time and
+percentages-of-time for the call graph.  More than one \fB\-F\fR option
+may be given; only one \fIfunction_name\fR may be indicated with each
+\&\fB\-F\fR option.  The \fB\-F\fR option overrides the \fB\-E\fR option.
+.SH "FILES"
+.IX Header "FILES"
+.ie n .IP """\fIa.out\fP""" 4
+.el .IP "\f(CW\f(CIa.out\f(CW\fR" 4
+.IX Item "a.out"
+the namelist and text space.
+.ie n .IP """\fIgmon.out\fP""" 4
+.el .IP "\f(CW\f(CIgmon.out\f(CW\fR" 4
+.IX Item "gmon.out"
+dynamic call graph and profile.
+.ie n .IP """\fIgmon.sum\fP""" 4
+.el .IP "\f(CW\f(CIgmon.sum\f(CW\fR" 4
+.IX Item "gmon.sum"
+summarized dynamic call graph and profile.
+.SH "BUGS"
+.IX Header "BUGS"
+The granularity of the sampling is shown, but remains
+statistical at best.
+We assume that the time for each execution of a function
+can be expressed by the total time for the function divided
+by the number of times the function is called.
+Thus the time propagated along the call graph arcs to the function's
+parents is directly proportional to the number of times that
+arc is traversed.
+.PP
+Parents that are not themselves profiled will have the time of
+their profiled children propagated to them, but they will appear
+to be spontaneously invoked in the call graph listing, and will
+not have their time propagated further.
+Similarly, signal catchers, even though profiled, will appear
+to be spontaneous (although for more obscure reasons).
+Any profiled children of signal catchers should have their times
+propagated properly, unless the signal catcher was invoked during
+the execution of the profiling routine, in which case all is lost.
+.PP
+The profiled program must call \f(CW\*(C`exit\*(C'\fR(2)
+or return normally for the profiling information to be saved
+in the \fIgmon.out\fR file.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBmonitor\fR\|(3), \fBprofil\fR\|(2), \fBcc\fR\|(1), \fBprof\fR\|(1), and the Info entry for \fIgprof\fR.
+.PP
+\&\*(L"An Execution Profiler for Modular Programs\*(R",
+by S. Graham, P. Kessler, M. McKusick;
+Software \- Practice and Experience,
+Vol. 13, pp. 671\-685, 1983.
+.PP
+\&\*(L"gprof: A Call Graph Execution Profiler\*(R",
+by S. Graham, P. Kessler, M. McKusick;
+Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction,
+\&\s-1SIGPLAN\s0 Notices, Vol. 17, No  6, pp. 120\-126, June 1982.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1988\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/grep.1 b/upstream/mageia-cauldron/man1/grep.1
new file mode 100644
index 00000000..7758ed1e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grep.1
@@ -0,0 +1,1358 @@
+.\" GNU grep man page
+.de dT
+.ds Dt \\$2
+..
+.dT Time-stamp: "2019-12-29"
+.\" Update the above date whenever a change to either this file or
+.\" grep.c's 'usage' function results in a nontrivial change to the man page.
+.\" In Emacs, you can update the date by running 'M-x time-stamp'
+.\" after you make a change that you decide is nontrivial.
+.\" It is no big deal to forget to update the date.
+.
+.TH GREP 1 \*(Dt "GNU grep 3.11" "User Commands"
+.
+.if !\w|\*(lq| \{\
+.\" groff an-old.tmac does not seem to be in use, so define lq and rq.
+.	ie \n(.g \{\
+.		ds lq \(lq\"
+.		ds rq \(rq\"
+.	\}
+.	el \{\
+.		ds lq ``
+.		ds rq ''
+.	\}
+.\}
+.
+.if !\w|\*(la| \{\
+.\" groff an-ext.tmac does not seem to be in use, so define the parts of
+.\" it that are used below.  For a copy of groff an-ext.tmac, please see:
+.\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac
+.\" --- Start of lines taken from groff an-ext.tmac
+.
+.\" Check whether we are using grohtml.
+.nr mH 0
+.if \n(.g \
+.  if '\*(.T'html' \
+.    nr mH 1
+.
+.
+.\" Map mono-width fonts to standard fonts for groff's TTY device.
+.if n \{\
+.  do ftr CR R
+.  do ftr CI I
+.  do ftr CB B
+.\}
+.
+.\" groff has glyph entities for angle brackets.
+.ie \n(.g \{\
+.  ds la \(la\"
+.  ds ra \(ra\"
+.\}
+.el \{\
+.  ds la <\"
+.  ds ra >\"
+.  \" groff's man macros control hyphenation with this register.
+.  nr HY 1
+.\}
+.
+.\" Start URL.
+.de UR
+.  ds m1 \\$1\"
+.  nh
+.  if \\n(mH \{\
+.    \" Start diversion in a new environment.
+.    do ev URL-div
+.    do di URL-div
+.  \}
+..
+.
+.
+.\" End URL.
+.de UE
+.  ie \\n(mH \{\
+.    br
+.    di
+.    ev
+.
+.    \" Has there been one or more input lines for the link text?
+.    ie \\n(dn \{\
+.      do HTML-NS "<a href=""\\*(m1"">"
+.      \" Yes, strip off final newline of diversion and emit it.
+.      do chop URL-div
+.      do URL-div
+\c
+.      do HTML-NS </a>
+.    \}
+.    el \
+.      do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
+\&\\$*\"
+.  \}
+.  el \
+\\*(la\\*(m1\\*(ra\\$*\"
+.
+.  hy \\n(HY
+..
+.
+.
+.\" Start email address.
+.de MT
+.  ds m1 \\$1\"
+.  nh
+.  if \\n(mH \{\
+.    \" Start diversion in a new environment.
+.    do ev URL-div
+.    do di URL-div
+.  \}
+..
+.
+.
+.\" End email address.
+.de ME
+.  ie \\n(mH \{\
+.    br
+.    di
+.    ev
+.
+.    \" Has there been one or more input lines for the link text?
+.    ie \\n(dn \{\
+.      do HTML-NS "<a href=""mailto:\\*(m1"">"
+.      \" Yes, strip off final newline of diversion and emit it.
+.      do chop URL-div
+.      do URL-div
+\c
+.      do HTML-NS </a>
+.    \}
+.    el \
+.      do HTML-NS "<a href=""mailto:\\*(m1"">\\*(m1</a>"
+\&\\$*\"
+.  \}
+.  el \
+\\*(la\\*(m1\\*(ra\\$*\"
+.
+.  hy \\n(HY
+..
+.\" --- End of lines taken from groff an-ext.tmac
+.\}
+.
+.hy 0
+.
+.SH NAME
+grep \- print lines that match patterns
+.
+.SH SYNOPSIS
+.B grep
+.RI [ OPTION .\|.\|.]\&
+.I PATTERNS
+.RI [ FILE .\|.\|.]
+.br
+.B grep
+.RI [ OPTION .\|.\|.]\&
+.B \-e
+.I PATTERNS
+\&.\|.\|.\&
+.RI [ FILE .\|.\|.]
+.br
+.B grep
+.RI [ OPTION .\|.\|.]\&
+.B \-f
+.I PATTERN_FILE
+\&.\|.\|.\&
+.RI [ FILE .\|.\|.]
+.
+.SH DESCRIPTION
+.B grep
+searches for
+.I PATTERNS
+in each
+.IR FILE .
+.I PATTERNS
+is one or more patterns separated by newline characters, and
+.B grep
+prints each line that matches a pattern.
+Typically
+.I PATTERNS
+should be quoted when
+.B grep
+is used in a shell command.
+.PP
+A
+.I FILE
+of
+.RB "\*(lq" \- "\*(rq"
+stands for standard input.
+If no
+.I FILE
+is given, recursive searches examine the working directory,
+and nonrecursive searches read standard input.
+.
+.SH OPTIONS
+.SS "Generic Program Information"
+.TP
+.B \-\^\-help
+Output a usage message and exit.
+.TP
+.BR \-V ", " \-\^\-version
+Output the version number of
+.B grep
+and exit.
+.SS "Pattern Syntax"
+.TP
+.BR \-E ", " \-\^\-extended\-regexp
+Interpret
+.I PATTERNS
+as extended regular expressions (EREs, see below).
+.TP
+.BR \-F ", " \-\^\-fixed\-strings
+Interpret
+.I PATTERNS
+as fixed strings, not regular expressions.
+.TP
+.BR \-G ", " \-\^\-basic\-regexp
+Interpret
+.I PATTERNS
+as basic regular expressions (BREs, see below).
+This is the default.
+.TP
+.BR \-P ", " \-\^\-perl\-regexp
+Interpret
+.I PATTERNS
+as Perl-compatible regular expressions (PCREs).
+This option is experimental when combined with the
+.B \-z
+.RB ( \-\^\-null\-data )
+option, and
+.B "grep \-P"
+may warn of unimplemented features.
+.SS "Matching Control"
+.TP
+.BI \-e " PATTERNS" "\fR,\fP \-\^\-regexp=" PATTERNS
+Use
+.I PATTERNS
+as the patterns.
+If this option is used multiple times or is combined with the
+.B \-f
+.RB ( \-\^\-file )
+option, search for all patterns given.
+This option can be used to protect a pattern beginning with \*(lq\-\*(rq.
+.TP
+.BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
+Obtain patterns from
+.IR FILE ,
+one per line.
+If this option is used multiple times or is combined with the
+.B \-e
+.RB ( \-\^\-regexp )
+option, search for all patterns given.
+The empty file contains zero patterns, and therefore matches nothing.
+If
+.IR FILE
+is
+.B \-
+, read patterns from standard input.
+.TP
+.BR \-i ", " \-\^\-ignore\-case
+Ignore case distinctions in patterns and input data,
+so that characters that differ only in case
+match each other.
+.TP
+.B \-\^\-no\-ignore\-case
+Do not ignore case distinctions in patterns and input data.
+This is the default.
+This option is useful for passing to shell scripts that already use
+.BR \-i ,
+to cancel its effects because the two options override each other.
+.TP
+.BR \-v ", " \-\^\-invert\-match
+Invert the sense of matching, to select non-matching lines.
+.TP
+.BR \-w ", " \-\^\-word\-regexp
+Select only those lines containing matches that form whole words.
+The test is that the matching substring must either be at the
+beginning of the line, or preceded by a non-word constituent
+character.
+Similarly, it must be either at the end of the line
+or followed by a non-word constituent character.
+Word-constituent characters are letters, digits, and the underscore.
+This option has no effect if
+.B \-x
+is also specified.
+.TP
+.BR \-x ", " \-\^\-line\-regexp
+Select only those matches that exactly match the whole line.
+For a regular expression pattern, this is like parenthesizing the
+pattern and then surrounding it with
+.B ^
+and
+.BR $ .
+.SS "General Output Control"
+.TP
+.BR \-c ", " \-\^\-count
+Suppress normal output; instead print a count of
+matching lines for each input file.
+With the
+.BR \-v ", " \-\^\-invert\-match
+option (see above), count non-matching lines.
+.TP
+.BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
+Surround the matched (non-empty) strings, matching lines, context lines,
+file names, line numbers, byte offsets, and separators (for fields and
+groups of context lines) with escape sequences to display them in color
+on the terminal.
+The colors are defined by the environment variable
+.BR GREP_COLORS .
+.I WHEN
+is
+.BR never ", " always ", or " auto .
+.TP
+.BR \-L ", " \-\^\-files\-without\-match
+Suppress normal output; instead print the name
+of each input file from which no output would
+normally have been printed.
+.TP
+.BR \-l ", " \-\^\-files\-with\-matches
+Suppress normal output; instead print
+the name of each input file from which output
+would normally have been printed.
+Scanning each input file stops upon first match.
+.TP
+.BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM
+Stop reading a file after
+.I NUM
+matching lines.
+If
+.I NUM
+is zero,
+.B grep
+stops right away without reading input.
+A
+.I NUM
+of \-1 is treated as infinity and
+.B grep
+does not stop; this is the default.
+If the input is standard input from a regular file,
+and
+.I NUM
+matching lines are output,
+.B grep
+ensures that the standard input is positioned to just after the last
+matching line before exiting, regardless of the presence of trailing
+context lines.
+This enables a calling process to resume a search.
+When
+.B grep
+stops after
+.I NUM
+matching lines, it outputs any trailing context lines.
+When the
+.B \-c
+or
+.B \-\^\-count
+option is also used,
+.B grep
+does not output a count greater than
+.IR NUM .
+When the
+.B \-v
+or
+.B \-\^\-invert\-match
+option is also used,
+.B grep
+stops after outputting
+.I NUM
+non-matching lines.
+.TP
+.BR \-o ", " \-\^\-only\-matching
+Print only the matched (non-empty) parts of a matching line,
+with each such part on a separate output line.
+.TP
+.BR \-q ", " \-\^\-quiet ", " \-\^\-silent
+Quiet; do not write anything to standard output.
+Exit immediately with zero status if any match is found,
+even if an error was detected.
+Also see the
+.B \-s
+or
+.B \-\^\-no\-messages
+option.
+.TP
+.BR \-s ", " \-\^\-no\-messages
+Suppress error messages about nonexistent or unreadable files.
+.SS "Output Line Prefix Control"
+.TP
+.BR \-b ", " \-\^\-byte\-offset
+Print the 0-based byte offset within the input file
+before each line of output.
+If
+.B \-o
+.RB ( \-\^\-only\-matching )
+is specified,
+print the offset of the matching part itself.
+.TP
+.BR \-H ", " \-\^\-with\-filename
+Print the file name for each match.
+This is the default when there is more than one file to search.
+This is a GNU extension.
+.TP
+.BR \-h ", " \-\^\-no\-filename
+Suppress the prefixing of file names on output.
+This is the default when there is only one file
+(or only standard input) to search.
+.TP
+.BI \-\^\-label= LABEL
+Display input actually coming from standard input as input coming from file
+.IR LABEL .
+This can be useful for commands that transform a file's contents
+before searching,
+e.g.,
+.BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H 'some pattern'" .
+See also the
+.B \-H
+option.
+.TP
+.BR \-n ", " \-\^\-line\-number
+Prefix each line of output with the 1-based line number
+within its input file.
+.TP
+.BR \-T ", " \-\^\-initial\-tab
+Make sure that the first character of actual line content lies on a
+tab stop, so that the alignment of tabs looks normal.
+This is useful with options that prefix their output to the actual content:
+.BR \-H , \-n ,
+and
+.BR \-b .
+In order to improve the probability that lines
+from a single file will all start at the same column,
+this also causes the line number and byte offset (if present)
+to be printed in a minimum size field width.
+.TP
+.BR \-Z ", " \-\^\-null
+Output a zero byte (the ASCII
+.B NUL
+character) instead of the character that normally follows a file name.
+For example,
+.B "grep \-lZ"
+outputs a zero byte after each file name instead of the usual newline.
+This option makes the output unambiguous, even in the presence of file
+names containing unusual characters like newlines.
+This option can be used with commands like
+.BR "find \-print0" ,
+.BR "perl \-0" ,
+.BR "sort \-z" ,
+and
+.B "xargs \-0"
+to process arbitrary file names,
+even those that contain newline characters.
+.SS "Context Line Control"
+.TP
+.BI \-A " NUM" "\fR,\fP \-\^\-after\-context=" NUM
+Print
+.I NUM
+lines of trailing context after matching lines.
+Places a line containing a group separator
+.RB ( \-\^\- )
+between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only\-matching
+option, this has no effect and a warning is given.
+.TP
+.BI \-B " NUM" "\fR,\fP \-\^\-before\-context=" NUM
+Print
+.I NUM
+lines of leading context before matching lines.
+Places a line containing a group separator
+.RB ( \-\^\- )
+between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only\-matching
+option, this has no effect and a warning is given.
+.TP
+.BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM
+Print
+.I NUM
+lines of output context.
+Places a line containing a group separator
+.RB ( \-\^\- )
+between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only\-matching
+option, this has no effect and a warning is given.
+.TP
+.BI \-\^\-group\-separator= SEP
+When
+.BR \-A ,
+.BR \-B ,
+or
+.B \-C
+are in use, print
+.I SEP
+instead of
+.B \-\^\-
+between groups of lines.
+.TP
+.B \-\^\-no\-group\-separator
+When
+.BR \-A ,
+.BR \-B ,
+or
+.B \-C
+are in use, do not print a separator between groups of lines.
+.SS "File and Directory Selection"
+.TP
+.BR \-a ", " \-\^\-text
+Process a binary file as if it were text; this is equivalent to the
+.B \-\^\-binary\-files=text
+option.
+.TP
+.BI \-\^\-binary\-files= TYPE
+If a file's data or metadata
+indicate that the file contains binary data,
+assume that the file is of type
+.IR TYPE .
+Non-text bytes indicate binary data; these are either output bytes that are
+improperly encoded for the current locale, or null input bytes when the
+.B \-z
+option is not given.
+.IP
+By default,
+.I TYPE
+is
+.BR binary ,
+and
+.B grep
+suppresses output after null input binary data is discovered,
+and suppresses output lines that contain improperly encoded data.
+When some output is suppressed,
+.B grep
+follows any output
+with a message to standard error saying that a binary file matches.
+.IP
+If
+.I TYPE
+is
+.BR without\-match ,
+when
+.B grep
+discovers null input binary data it assumes that the rest of the file
+does not match; this is equivalent to the
+.B \-I
+option.
+.IP
+If
+.I TYPE
+is
+.BR text ,
+.B grep
+processes a binary file as if it were text; this is equivalent to the
+.B \-a
+option.
+.IP
+When
+.I type
+is
+.BR binary ,
+.B grep
+may treat non-text bytes as line terminators even without the
+.B \-z
+option.  This means choosing
+.B binary
+versus
+.B text
+can affect whether a pattern matches a file.  For
+example, when
+.I type
+is
+.B binary
+the pattern
+.B q$ might
+match
+.B q
+immediately followed by a null byte, even though this
+is not matched when
+.I type
+is
+.BR text .
+Conversely, when
+.I type
+is
+.B binary
+the pattern
+.B .\&
+(period) might not match a null byte.
+.IP
+.I Warning:
+The
+.B \-a
+option might output binary garbage,
+which can have nasty side effects if the output is a terminal and if the
+terminal driver interprets some of it as commands.
+On the other hand, when reading files whose text encodings are
+unknown, it can be helpful to use
+.B \-a
+or to set
+.B LC_ALL='C'
+in the environment, in order to find more matches even if the matches
+are unsafe for direct display.
+.TP
+.BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
+If an input file is a device, FIFO or socket, use
+.I ACTION
+to process it.
+By default,
+.I ACTION
+is
+.BR read ,
+which means that devices are read just as if they were ordinary files.
+If
+.I ACTION
+is
+.BR skip ,
+devices are silently skipped.
+.TP
+.BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
+If an input file is a directory, use
+.I ACTION
+to process it.
+By default,
+.I ACTION
+is
+.BR read ,
+i.e., read directories just as if they were ordinary files.
+If
+.I ACTION
+is
+.BR skip ,
+silently skip directories.
+If
+.I ACTION
+is
+.BR recurse ,
+read all files under each directory, recursively,
+following symbolic links only if they are on the command line.
+This is equivalent to the
+.B \-r
+option.
+.TP
+.BI \-\^\-exclude= GLOB
+Skip any command-line file with a name suffix that matches the pattern
+.IR GLOB ,
+using wildcard matching; a name suffix is either the whole
+name, or a trailing part that starts with a non-slash character
+immediately after a slash
+.RB ( / )
+in the name.
+When searching recursively, skip any subfile whose base name matches
+.IR GLOB ;
+the base name is the part after the last slash.
+A pattern can use
+.BR * ,
+.BR ? ,
+and
+.BR [ .\|.\|. ]\&
+as wildcards, and
+.B \e
+to quote a wildcard or backslash character literally.
+.TP
+.BI \-\^\-exclude\-from= FILE
+Skip files whose base name matches any of the file-name globs read from
+.I FILE
+(using wildcard matching as described under
+.BR \-\^\-exclude ).
+.TP
+.BI \-\^\-exclude\-dir= GLOB
+Skip any command-line directory with a name suffix that matches the
+pattern
+.IR GLOB .
+When searching recursively, skip any subdirectory
+whose base name matches
+.IR GLOB .
+Ignore any redundant trailing slashes in
+.IR GLOB .
+.TP
+.BR \-I
+Process a binary file as if it did not contain matching data; this is
+equivalent to the
+.B \-\^\-binary\-files=without\-match
+option.
+.TP
+.BI \-\^\-include= GLOB
+Search only files whose base name matches
+.I GLOB
+(using wildcard matching as described under
+.BR \-\^\-exclude ).
+If contradictory
+.B \-\^\-include
+and
+.B \-\^\-exclude
+options are given, the last matching one wins.
+If no
+.B \-\^\-include
+or
+.B \-\^\-exclude
+options match, a file is included unless the first such option is
+.BR \-\^\-include .
+.TP
+.BR \-r ", " \-\^\-recursive
+Read all files under each directory, recursively,
+following symbolic links only if they are on the command line.
+Note that if no file operand is given,
+.B grep
+searches the working directory.
+This is equivalent to the
+.B "\-d recurse"
+option.
+.TP
+.BR \-R ", " \-\^\-dereference\-recursive
+Read all files under each directory, recursively.
+Follow all symbolic links, unlike
+.BR \-r .
+.SS "Other Options"
+.TP
+.B \-\^\-line\-buffered
+Use line buffering on output.
+This can cause a performance penalty.
+.TP
+.BR \-U ", " \-\^\-binary
+Treat the file(s) as binary.
+By default, under MS-DOS and MS-Windows,
+.B grep
+guesses whether a file is text or binary as described for the
+.B \-\^\-binary\-files
+option.
+If
+.B grep
+decides the file is a text file, it strips the CR characters from the
+original file contents (to make regular expressions with
+.B ^
+and
+.B $
+work correctly).
+Specifying
+.B \-U
+overrules this guesswork, causing all files to be read and passed to the
+matching mechanism verbatim; if the file is a text file with CR/LF
+pairs at the end of each line, this will cause some regular
+expressions to fail.
+This option has no effect on platforms
+other than MS-DOS and MS-Windows.
+.TP
+.BR \-z ", " \-\^\-null\-data
+Treat input and output data as sequences of lines, each terminated by
+a zero byte (the ASCII NUL character) instead of a newline.
+Like the
+.B \-Z
+or
+.B \-\^\-null
+option, this option can be used with commands like
+.B sort -z
+to process arbitrary file names.
+.
+.SH "REGULAR EXPRESSIONS"
+A regular expression is a pattern that describes a set of strings.
+Regular expressions are constructed analogously to arithmetic
+expressions, by using various operators to combine smaller expressions.
+.PP
+.B grep
+understands three different versions of regular expression syntax:
+\*(lqbasic\*(rq (BRE), \*(lqextended\*(rq (ERE) and \*(lqperl\*(rq (PCRE).
+In GNU
+.BR grep ,
+basic and extended regular expressions are merely different notations
+for the same pattern-matching functionality.
+In other implementations, basic regular expressions are ordinarily
+less powerful than extended, though occasionally it is the other way around.
+The following description applies to extended regular expressions;
+differences for basic regular expressions are summarized afterwards.
+Perl-compatible regular expressions have different functionality, and are
+documented in
+.BR pcre2syntax (3)
+and
+.BR pcre2pattern (3),
+but work only if PCRE support is enabled.
+.PP
+The fundamental building blocks are the regular expressions
+that match a single character.
+Most characters, including all letters and digits,
+are regular expressions that match themselves.
+Any meta-character with special meaning
+may be quoted by preceding it with a backslash.
+.PP
+The period
+.B .\&
+matches any single character.
+It is unspecified whether it matches an encoding error.
+.SS "Character Classes and Bracket Expressions"
+A
+.I "bracket expression"
+is a list of characters enclosed by
+.B [
+and
+.BR ] .
+It matches any single
+character in that list.
+If the first character of the list
+is the caret
+.B ^
+then it matches any character
+.I not
+in the list; it is unspecified whether it matches an encoding error.
+For example, the regular expression
+.B [0123456789]
+matches any single digit.
+.PP
+Within a bracket expression, a
+.I "range expression"
+consists of two characters separated by a hyphen.
+It matches any single character that sorts between the two characters,
+inclusive, using the locale's collating sequence and character set.
+For example, in the default C locale,
+.B [a\-d]
+is equivalent to
+.BR [abcd] .
+Many locales sort characters in dictionary order, and in these locales
+.B [a\-d]
+is typically not equivalent to
+.BR [abcd] ;
+it might be equivalent to
+.BR [aBbCcDd] ,
+for example.
+To obtain the traditional interpretation of bracket expressions,
+you can use the C locale by setting the
+.B LC_ALL
+environment variable to the value
+.BR C .
+.PP
+Finally, certain named classes of characters are predefined within
+bracket expressions, as follows.
+Their names are self explanatory, and they are
+.BR [:alnum:] ,
+.BR [:alpha:] ,
+.BR [:blank:] ,
+.BR [:cntrl:] ,
+.BR [:digit:] ,
+.BR [:graph:] ,
+.BR [:lower:] ,
+.BR [:print:] ,
+.BR [:punct:] ,
+.BR [:space:] ,
+.BR [:upper:] ,
+and
+.BR [:xdigit:] .
+For example,
+.B [[:alnum:]]
+means the character class of numbers and
+letters in the current locale.
+In the C locale and ASCII
+character set encoding, this is the same as
+.BR [0\-9A\-Za\-z] .
+(Note that the brackets in these class names are part of the symbolic
+names, and must be included in addition to the brackets delimiting
+the bracket expression.)
+Most meta-characters lose their special meaning inside bracket expressions.
+To include a literal
+.B ]
+place it first in the list.
+Similarly, to include a literal
+.B ^
+place it anywhere but first.
+Finally, to include a literal
+.B \-
+place it last.
+.SS Anchoring
+The caret
+.B ^
+and the dollar sign
+.B $
+are meta-characters that respectively match the empty string at the
+beginning and end of a line.
+.SS "The Backslash Character and Special Expressions"
+The symbols
+.B \e<
+and
+.B \e>
+respectively match the empty string at the beginning and end of a word.
+The symbol
+.B \eb
+matches the empty string at the edge of a word,
+and
+.B \eB
+matches the empty string provided it's
+.I not
+at the edge of a word.
+The symbol
+.B \ew
+is a synonym for
+.B [_[:alnum:]]
+and
+.B \eW
+is a synonym for
+.BR [^_[:alnum:]] .
+.SS Repetition
+A regular expression may be followed by one of several repetition operators:
+.PD 0
+.TP
+.B ?
+The preceding item is optional and matched at most once.
+.TP
+.B *
+The preceding item will be matched zero or more times.
+.TP
+.B +
+The preceding item will be matched one or more times.
+.TP
+.BI { n }
+The preceding item is matched exactly
+.I n
+times.
+.TP
+.BI { n ,}
+The preceding item is matched
+.I n
+or more times.
+.TP
+.BI {, m }
+The preceding item is matched at most
+.I m
+times.
+This is a GNU extension.
+.TP
+.BI { n , m }
+The preceding item is matched at least
+.I n
+times, but not more than
+.I m
+times.
+.PD
+.SS Concatenation
+Two regular expressions may be concatenated; the resulting
+regular expression matches any string formed by concatenating
+two substrings that respectively match the concatenated
+expressions.
+.SS Alternation
+Two regular expressions may be joined by the infix operator
+.BR | ;
+the resulting regular expression matches any string matching
+either alternate expression.
+.SS Precedence
+Repetition takes precedence over concatenation, which in turn
+takes precedence over alternation.
+A whole expression may be enclosed in parentheses
+to override these precedence rules and form a subexpression.
+.SS "Back-references and Subexpressions"
+The back-reference
+.BI \e n\c
+\&, where
+.I n
+is a single digit, matches the substring
+previously matched by the
+.IR n th
+parenthesized subexpression of the regular expression.
+.SS "Basic vs Extended Regular Expressions"
+In basic regular expressions the meta-characters
+.BR ? ,
+.BR + ,
+.BR { ,
+.BR | ,
+.BR ( ,
+and
+.BR )
+lose their special meaning; instead use the backslashed
+versions
+.BR \e? ,
+.BR \e+ ,
+.BR \e{ ,
+.BR \e| ,
+.BR \e( ,
+and
+.BR \e) .
+.
+.SH "EXIT STATUS"
+Normally the exit status is 0 if a line is selected, 1 if no lines
+were selected, and 2 if an error occurred.  However, if the
+.B \-q
+or
+.B \-\^\-quiet
+or
+.B \-\^\-silent
+is used and a line is selected, the exit status is 0 even if an error
+occurred.
+.
+.SH ENVIRONMENT
+The behavior of
+.B grep
+is affected by the following environment variables.
+.PP
+The locale for category
+.BI LC_ foo
+is specified by examining the three environment variables
+.BR LC_ALL ,
+.BR LC_\fIfoo\fP ,
+.BR LANG ,
+in that order.
+The first of these variables that is set specifies the locale.
+For example, if
+.B LC_ALL
+is not set, but
+.B LC_MESSAGES
+is set to
+.BR pt_BR ,
+then the Brazilian Portuguese locale is used for the
+.B LC_MESSAGES
+category.
+The C locale is used if none of these environment variables are set,
+if the locale catalog is not installed, or if
+.B grep
+was not compiled with national language support (NLS).
+The shell command
+.B "locale \-a"
+lists locales that are currently available.
+.TP
+.B GREP_COLORS
+Controls how the
+.B \-\^\-color
+option highlights output.
+Its value is a colon-separated list of capabilities
+that defaults to
+.B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
+with the
+.B rv
+and
+.B ne
+boolean capabilities omitted (i.e., false).
+Supported capabilities are as follows.
+.RS
+.TP
+.B sl=
+SGR substring for whole selected lines
+(i.e.,
+matching lines when the
+.B \-v
+command-line option is omitted,
+or non-matching lines when
+.B \-v
+is specified).
+If however the boolean
+.B rv
+capability
+and the
+.B \-v
+command-line option are both specified,
+it applies to context matching lines instead.
+The default is empty (i.e., the terminal's default color pair).
+.TP
+.B cx=
+SGR substring for whole context lines
+(i.e.,
+non-matching lines when the
+.B \-v
+command-line option is omitted,
+or matching lines when
+.B \-v
+is specified).
+If however the boolean
+.B rv
+capability
+and the
+.B \-v
+command-line option are both specified,
+it applies to selected non-matching lines instead.
+The default is empty (i.e., the terminal's default color pair).
+.TP
+.B rv
+Boolean value that reverses (swaps) the meanings of
+the
+.B sl=
+and
+.B cx=
+capabilities
+when the
+.B \-v
+command-line option is specified.
+The default is false (i.e., the capability is omitted).
+.TP
+.B mt=01;31
+SGR substring for matching non-empty text in any matching line
+(i.e.,
+a selected line when the
+.B \-v
+command-line option is omitted,
+or a context line when
+.B \-v
+is specified).
+Setting this is equivalent to setting both
+.B ms=
+and
+.B mc=
+at once to the same value.
+The default is a bold red text foreground over the current line background.
+.TP
+.B ms=01;31
+SGR substring for matching non-empty text in a selected line.
+(This is only used when the
+.B \-v
+command-line option is omitted.)
+The effect of the
+.B sl=
+(or
+.B cx=
+if
+.BR rv )
+capability remains active when this kicks in.
+The default is a bold red text foreground over the current line background.
+.TP
+.B mc=01;31
+SGR substring for matching non-empty text in a context line.
+(This is only used when the
+.B \-v
+command-line option is specified.)
+The effect of the
+.B cx=
+(or
+.B sl=
+if
+.BR rv )
+capability remains active when this kicks in.
+The default is a bold red text foreground over the current line background.
+.TP
+.B fn=35
+SGR substring for file names prefixing any content line.
+The default is a magenta text foreground over the terminal's default background.
+.TP
+.B ln=32
+SGR substring for line numbers prefixing any content line.
+The default is a green text foreground over the terminal's default background.
+.TP
+.B bn=32
+SGR substring for byte offsets prefixing any content line.
+The default is a green text foreground over the terminal's default background.
+.TP
+.B se=36
+SGR substring for separators that are inserted
+between selected line fields
+.RB ( : ),
+between context line fields,
+.RB ( \- ),
+and between groups of adjacent lines when nonzero context is specified
+.RB ( \-\^\- ).
+The default is a cyan text foreground over the terminal's default background.
+.TP
+.B ne
+Boolean value that prevents clearing to the end of line
+using Erase in Line (EL) to Right
+.RB ( \e33[K )
+each time a colorized item ends.
+This is needed on terminals on which EL is not supported.
+It is otherwise useful on terminals
+for which the
+.B back_color_erase
+.RB ( bce )
+boolean terminfo capability does not apply,
+when the chosen highlight colors do not affect the background,
+or when EL is too slow or causes too much flicker.
+The default is false (i.e., the capability is omitted).
+.PP
+Note that boolean capabilities have no
+.BR = .\|.\|.\&
+part.
+They are omitted (i.e., false) by default and become true when specified.
+.PP
+See the Select Graphic Rendition (SGR) section
+in the documentation of the text terminal that is used
+for permitted values and their meaning as character attributes.
+These substring values are integers in decimal representation
+and can be concatenated with semicolons.
+.B grep
+takes care of assembling the result
+into a complete SGR sequence
+.RB ( \e33[ .\|.\|. m ).
+Common values to concatenate include
+.B 1
+for bold,
+.B 4
+for underline,
+.B 5
+for blink,
+.B 7
+for inverse,
+.B 39
+for default foreground color,
+.B 30
+to
+.B 37
+for foreground colors,
+.B 90
+to
+.B 97
+for 16-color mode foreground colors,
+.B 38;5;0
+to
+.B 38;5;255
+for 88-color and 256-color modes foreground colors,
+.B 49
+for default background color,
+.B 40
+to
+.B 47
+for background colors,
+.B 100
+to
+.B 107
+for 16-color mode background colors, and
+.B 48;5;0
+to
+.B 48;5;255
+for 88-color and 256-color modes background colors.
+.RE
+.TP
+\fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
+These variables specify the locale for the
+.B LC_COLLATE
+category,
+which determines the collating sequence
+used to interpret range expressions like
+.BR [a\-z] .
+.TP
+\fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
+These variables specify the locale for the
+.B LC_CTYPE
+category,
+which determines the type of characters,
+e.g., which characters are whitespace.
+This category also determines the character encoding, that is, whether
+text is encoded in UTF-8, ASCII, or some other encoding.  In the C or
+POSIX locale, all characters are encoded as a single byte and every
+byte is a valid character.
+.TP
+\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
+These variables specify the locale for the
+.B LC_MESSAGES
+category,
+which determines the language that
+.B grep
+uses for messages.
+The default C locale uses American English messages.
+.TP
+.B POSIXLY_CORRECT
+If set,
+.B grep
+behaves as POSIX requires; otherwise,
+.B grep
+behaves more like other GNU programs.
+POSIX requires that options that follow file names must be
+treated as file names; by default, such options are permuted to the
+front of the operand list and are treated as options.
+Also, POSIX requires that unrecognized options be diagnosed as
+\*(lqillegal\*(rq, but since they are not really against the law the default
+is to diagnose them as \*(lqinvalid\*(rq.
+.
+.SH NOTES
+This man page is maintained only fitfully;
+the full documentation is often more up-to-date.
+.
+.SH COPYRIGHT
+Copyright 1998-2000, 2002, 2005-2023 Free Software Foundation, Inc.
+.PP
+This is free software;
+see the source for copying conditions.
+There is NO warranty;
+not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.
+.SH BUGS
+.SS "Reporting Bugs"
+Email bug reports to
+.MT bug-grep@gnu.org
+the bug-reporting address
+.ME .
+An
+.UR https://lists.gnu.org/mailman/listinfo/bug-grep
+email archive
+.UE
+and a
+.UR https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep
+bug tracker
+.UE
+are available.
+.SS "Known Bugs"
+Large repetition counts in the
+.BI { n , m }
+construct may cause
+.B grep
+to use lots of memory.
+In addition,
+certain other obscure regular expressions require exponential time
+and space, and may cause
+.B grep
+to run out of memory.
+.PP
+Back-references are very slow, and may require exponential time.
+.
+.SH EXAMPLE
+The following example outputs the location and contents of any line
+containing \*(lqf\*(rq and ending in \*(lq.c\*(rq,
+within all files in the current directory whose names
+contain \*(lqg\*(rq and end in \*(lq.h\*(rq.
+The
+.B \-n
+option outputs line numbers, the
+.B \-\-
+argument treats expansions of \*(lq*g*.h\*(rq starting with \*(lq\-\*(rq
+as file names not options,
+and the empty file /dev/null causes file names to be output
+even if only one file name happens to be of the form \*(lq*g*.h\*(rq.
+.PP
+.in +2n
+.EX
+$ \fBgrep\fP \-n \-\- 'f.*\e.c$' *g*.h /dev/null
+argmatch.h:1:/* definitions and prototypes for argmatch.c
+.EE
+.in
+.PP
+The only line that matches is line 1 of argmatch.h.
+Note that the regular expression syntax used in the pattern differs
+from the globbing syntax that the shell uses to match file names.
+.
+.SH "SEE ALSO"
+.SS "Regular Manual Pages"
+.BR awk (1),
+.BR cmp (1),
+.BR diff (1),
+.BR find (1),
+.BR perl (1),
+.BR sed (1),
+.BR sort (1),
+.BR xargs (1),
+.BR read (2),
+.BR pcre2 (3),
+.BR pcre2syntax (3),
+.BR pcre2pattern (3),
+.BR terminfo (5),
+.BR glob (7),
+.BR regex (7)
+.SS "Full Documentation"
+A
+.UR https://www.gnu.org/software/grep/manual/
+complete manual
+.UE
+is available.
+If the
+.B info
+and
+.B grep
+programs are properly installed at your site, the command
+.IP
+.B info grep
+.PP
+should give you access to the complete manual.
+.
+.\" Work around problems with some troff -man implementations.
+.br
+.
+.\" Format for Emacs-maintained Dt string defined at this file's start.
+.\" Local variables:
+.\" time-stamp-format: "%:y-%02m-%02d"
+.\" End:
diff --git a/upstream/mageia-cauldron/man1/grn.1 b/upstream/mageia-cauldron/man1/grn.1
new file mode 100644
index 00000000..51aa97c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grn.1
@@ -0,0 +1,783 @@
+'\" t
+.TH GRN 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grn \- groff preprocessor for gremlin files
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 2000-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr grn_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grn
+.OP \-Cv
+.OP \-T dev
+.OP \-M dir
+.OP \-F dir
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I grn
+is a preprocessor for including
+.I gremlin
+pictures in
+.I groff
+input.
+.
+.I grn
+writes to standard output, processing only input lines between two
+that start with
+.B .GS
+and
+.BR .GE .
+.
+Those lines must contain
+.I grn
+commands (see below).
+.
+These commands request a
+.I gremlin
+file, and the picture in that file is converted and placed in the
+.I troff
+input stream.
+.
+The
+.B .GS
+request may be followed by a C, L, or R to center, left, or right
+justify the whole
+.I gremlin
+picture (default justification is center).
+.
+If no
+.I file
+is mentioned, the standard input is read.
+.
+At the end of the picture, the position on the page is the bottom of the
+.I gremlin
+picture.
+.
+If the
+.I grn
+entry is ended with
+.B .GF
+instead of
+.BR .GE ,
+the position is left at the top of the picture.
+.
+.
+.PP
+Please note that currently only the \-me macro package has support for
+.BR .GS ,
+.BR .GE ,
+and
+.BR .GF .
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.BI \-T dev
+Prepare output for printer
+.IR dev .
+The default device is
+.BR ps .
+See
+.BR groff (1)
+for acceptable devices.
+.
+.TP
+.BI \-M dir
+Prepend
+.I dir
+to the default search path for
+.I gremlin
+files.
+.
+The default path is (in that order) the current directory, the home
+directory,
+.IR /usr/\:lib64/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+and
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
+.
+.TP
+.BI \-F dir
+Search
+.I dir
+for subdirectories
+.IR dev name
+.RI ( name
+is the name of the device) for the
+.I DESC
+file before the default font directories
+.IR /usr/\:share/\:groff/\:site\-font ,
+.IR /usr/\:share/\:groff/\:1.22.4/\:font ,
+and
+.IR /usr/\:lib/\:font .
+.
+.TP
+.B \-C
+Recognize
+.B .GS
+and
+.B .GE
+(and
+.BR .GF )
+even when followed by a character other than space or newline.
+.\".TP
+.\".B \-s
+.\"This switch causes the picture to be traversed twice:
+.\"The first time, only the interiors of filled polygons (as borderless
+.\"polygons) are printed.
+.\"The second time, the outline is printed as a series of line segments.
+.\"This way, postprocessors that overwrite rather than merge picture elements
+.\"(such as PostScript) can still have text and graphics on a shaded
+.\"background.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.\" ====================================================================
+.SH "GRN COMMANDS"
+.\" ====================================================================
+.
+Each input line between
+.B .GS
+and
+.B .GE
+may have one
+.I grn
+command.
+.
+Commands consist of one or two strings separated by white space, the first
+string being the command and the second its operand.
+Commands may be upper or lower case and abbreviated down to one character.
+.
+.
+.PP
+Commands that affect a picture's environment (those listed before
+.BR default ,
+see below) are only in effect for the current picture:
+.
+The environment is reinitialized to the defaults at the start of the next
+picture.
+.
+The commands are as follows:
+.TP
+.BI 1\  N
+.TQ
+.BI 2\  N
+.TQ
+.BI 3\  N
+.TQ
+.BI 4\  N
+.
+Set
+.IR gremlin 's
+text size number 1 (2, 3, or 4) to
+.I N
+points.
+.
+The default is 12 (16, 24, and 36, respectively).
+.
+.TP
+.BI roman\  f
+.TQ
+.BI italics\  f
+.TQ
+.BI bold\  f
+.TQ
+.BI special\  f
+Set the roman (italics, bold, or special) font to
+.IR troff 's
+font
+.I f
+(either a name or number).
+.
+The default is R (I, B, and S, respectively).
+.
+.TP
+.BI l\  f
+.TQ
+.BI stipple\  f
+Set the stipple font to
+.IR troff 's
+stipple font
+.I f
+(name or number).
+.
+The command
+.B stipple
+may be abbreviated down as far as \[oq]st\[cq] (to avoid confusion
+with
+.BR special ).
+.
+There is
+.I no
+default for stipples (unless one is set by the default command), and
+it is invalid to include a
+.I gremlin
+picture with polygons without specifying a
+stipple font.
+.
+.TP
+.BI x\  N
+.TQ
+.BI scale\  N
+Magnify the picture (in addition to any default magnification) by
+.IR N ,
+a floating point number larger than zero.
+.
+The command
+.B scale
+may be abbreviated down to \[oq]sc\[cq].
+.
+.TP
+.BI narrow\  N
+.TQ
+.BI medium\  N
+.TQ
+.BI thick\  N
+.
+Set the thickness of
+.IR gremlin 's
+narrow (medium and thick, respectively) lines to
+.I N
+times 0.15pt (this value can be changed at compile time).
+.
+The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt
+(0.45pt and 0.75pt, respectively).
+.
+A thickness value of zero selects the smallest available line thickness.
+.
+Negative values cause the line thickness to be proportional to the
+current point size.
+.
+.TP
+.BI pointscale\  <off/on>
+Scale text to match the picture.
+.
+Gremlin text is usually printed in the point size specified with the
+commands
+.BR 1 ,
+.BR 2 ,
+.BR 3 ,
+.RB or\~ 4 ,
+regardless of any scaling factors in the picture.
+.
+Setting
+.B pointscale
+will cause the point sizes to scale with the picture (within
+.IR troff 's
+limitations, of course).
+.
+An operand of anything but
+.I off
+will turn text scaling on.
+.
+.TP
+.B default
+Reset the picture environment defaults to the settings in the current
+picture.
+.
+This is meant to be used as a global parameter setting mechanism at
+the beginning of the
+.I troff
+input file, but can be used at any time to reset the
+default settings.
+.
+.TP
+.BI width\  N
+Forces the picture to be
+.I N
+inches wide.
+.
+This overrides any scaling factors present in the same picture.
+.RB \[oq] width
+.IR 0 \[cq]
+is ignored.
+.
+.TP
+.BI height\  N
+Forces picture to be
+.I N
+inches high, overriding other scaling factors.
+.
+If both \[oq]width\[cq] and \[oq]height\[cq] are specified the tighter
+constraint will determine the scale of the picture.
+.B Height
+and
+.B width
+commands are not saved with a
+.B default
+command.
+.
+They will, however, affect point size scaling if that option is set.
+.
+.TP
+.BI file\  name
+Get picture from
+.I gremlin
+file
+.I name
+located the current directory (or in the library directory; see the
+.B \-M
+option above).
+.
+If two
+.B file
+commands are given, the second one overrides the first.
+.
+If
+.I name
+doesn't exist, an error message is reported and processing
+continues from the
+.B .GE
+line.
+.
+.
+.\" ====================================================================
+.SH "NOTES ABOUT GROFF"
+.\" ====================================================================
+.
+Since
+.I grn
+is a preprocessor, it doesn't know about current indents, point
+sizes, margins, number registers, etc.  Consequently, no
+.I troff
+input can be placed between the
+.B .GS
+and
+.B .GE
+requests.
+.
+However,
+.I gremlin
+text is now processed by
+.IR troff ,
+so anything valid in a single line of
+.I troff
+input is valid in a line of
+.I gremlin
+text (barring \[oq].\[cq] directives at the beginning of a line).
+.
+Thus, it is possible to have equations within a
+.I gremlin
+figure by including in the
+.I gremlin
+file
+.I eqn
+expressions enclosed by previously defined delimiters (e.g.\&
+.IR $$ ).
+.
+.
+.PP
+When using
+.I grn
+along with other preprocessors, it is best to run
+.I tbl
+before
+.IR grn ,
+.IR pic ,
+and/or
+.I ideal
+to avoid overworking
+.IR tbl .
+.
+.I Eqn
+should always be run last.
+.
+.
+.PP
+A picture is considered an entity, but that doesn't stop
+.I troff
+from trying to break it up if it falls off the end of a page.
+.
+Placing the picture between \[oq]keeps\[cq] in \-me macros will ensure
+proper placement.
+.
+.
+.PP
+.I grn
+uses
+.IR troff 's
+number registers
+.B g1
+through
+.B g9
+and sets registers
+.B g1
+and
+.B g2
+to the width and height of the
+.I gremlin
+figure (in device units) before entering the
+.B .GS
+request (this is for those who want to rewrite these macros).
+.
+.
+.\" ====================================================================
+.SH "GREMLIN FILE FORMAT"
+.\" ====================================================================
+.
+There exist two distinct
+.I gremlin
+file formats, the original format from the
+.I AED
+graphic terminal version, and the
+.I SUN
+or
+.I X11
+version.
+.
+An extension to the
+.IR SUN / X11
+version allowing reference points with negative coordinates is
+.B not
+compatible with the
+.I AED
+version.
+.
+As long as a
+.I gremlin
+file does not contain negative coordinates, either format will be read
+correctly by either version of
+.I gremlin
+or
+.IR grn .
+.
+The other difference from
+.IR SUN / X11
+format is the use of names for picture objects (e.g., POLYGON, CURVE)
+instead of numbers.
+.
+Files representing the same picture are shown in Table 1 in each format.
+.sp
+.TS
+center, tab(@);
+l lw(0.1i) l.
+sungremlinfile@@gremlinfile
+0 240.00 128.00@@0 240.00 128.00
+CENTCENT@@2
+240.00 128.00@@240.00 128.00
+185.00 120.00@@185.00 120.00
+240.00 120.00@@240.00 120.00
+296.00 120.00@@296.00 120.00
+*@@\-1.00 \-1.00
+2 3@@2 3
+10 A Triangle@@10 A Triangle
+POLYGON@@6
+224.00 416.00@@224.00 416.00
+96.00 160.00@@96.00 160.00
+384.00 160.00@@384.00 160.00
+*@@\-1.00 \-1.00
+5 1@@5 1
+0@@0
+\-1@@\-1
+.T&
+css.
+.sp
+Table 1.  File examples
+.TE
+.sp
+.IP \(bu
+The first line of each
+.I gremlin
+file contains either the string
+.B gremlinfile
+.RI ( AED
+version) or
+.B sungremlinfile
+.RI ( SUN / X11 )
+.IP \(bu
+The second line of the file contains an orientation, and
+.B x
+and
+.B y
+values for a positioning point, separated by spaces.
+The orientation, either
+.B 0
+or
+.BR 1 ,
+is ignored by the
+.IR SUN / X11
+version.
+.
+.B 0
+means that
+.I gremlin
+will display things in horizontal format (drawing area wider than it is
+tall, with menu across top).
+.
+.B 1
+means that
+.I gremlin
+will display things in vertical format (drawing area taller than it is
+wide, with menu on left side).
+.
+.B x
+and
+.B y
+are floating point values giving a positioning point to be used when
+this file is read into another file.
+.
+The stuff on this line really isn't all that important; a value of
+\[lq]1 0.00 0.00\[rq] is suggested.
+.
+.IP \(bu
+The rest of the file consists of zero or more element specifications.
+.
+After the last element specification is a line containing the string
+\[lq]\-1\[rq].
+.
+.IP \(bu
+Lines longer than 127 characters are chopped to this limit.
+.
+.
+.\" ====================================================================
+.SH "ELEMENT SPECIFICATIONS"
+.\" ====================================================================
+.
+.IP \(bu
+The first line of each element contains a single decimal number giving
+the type of the element
+.RI ( AED
+version) or its ASCII name
+.RI ( SUN / X11
+version).
+.
+See Table 2.
+.sp
+.TS
+center, tab(@);
+css
+ccc
+nll.
+\fIgremlin\fP File Format \(mi Object Type Specification
+.sp
+\fIAED\fP Number@\fISUN\/\fP/\,\fIX11\fP Name@Description
+0@BOTLEFT@bottom-left-justified text
+1@BOTRIGHT@bottom-right-justified text
+2@CENTCENT@center-justified text
+3@VECTOR@vector
+4@ARC@arc
+5@CURVE@curve
+6@POLYGON@polygon
+7@BSPLINE@b-spline
+8@BEZIER@B\['e]zier
+10@TOPLEFT@top-left-justified text
+11@TOPCENT@top-center-justified text
+12@TOPRIGHT@top-right-justified text
+13@CENTLEFT@left-center-justified text
+14@CENTRIGHT@right-center-justified text
+15@BOTCENT@bottom-center-justified text
+.T&
+css.
+.sp
+Table 2.
+Type Specifications in \fIgremlin\fP Files
+.TE
+.sp
+.IP \(bu
+After the object type comes a variable number of lines, each specifying a
+point used to display the element.
+Each line contains an x-coordinate and a y-coordinate in floating point
+format, separated by spaces.
+The list of points is terminated by a line containing the string \[lq]\-1.0
+\-1.0\[rq]
+.RI ( AED
+version) or a single asterisk, \[lq]*\[rq]
+.RI ( SUN / X11
+version).
+.
+.IP \(bu
+After the points comes a line containing two decimal values, giving the
+brush and size for the element.
+.
+The brush determines the style in which things are drawn.
+.
+For vectors, arcs, and curves there are six valid brush values:
+.sp
+.TS
+center, tab(@);
+ncw(0.1i)l.
+1 \(mi@@thin dotted lines
+2 \(mi@@thin dot-dashed lines
+3 \(mi@@thick solid lines
+4 \(mi@@thin dashed lines
+5 \(mi@@thin solid lines
+6 \(mi@@medium solid lines
+.TE
+.sp
+For polygons, one more value, 0, is valid.
+It specifies a polygon with an invisible border.
+For text, the brush selects a font as follows:
+.sp
+.TS
+center, tab(@);
+ncw(0.1i)l.
+1 \(mi@@roman (R font in groff)
+2 \(mi@@italics (I font in groff)
+3 \(mi@@bold (B font in groff)
+4 \(mi@@special (S font in groff)
+.TE
+.sp
+If you're using
+.I grn
+to run your pictures through
+.IR groff ,
+the font is really just a starting font:
+.
+The text string can contain formatting sequences like
+\[lq]\efI\[rq]
+or
+\[lq]\ed\[rq]
+which may change the font (as well as do many other things).
+.
+For text, the size field is a decimal value between 1 and 4.
+.
+It selects the size of the font in which the text will be drawn.
+.
+For polygons, this size field is interpreted as a stipple number to
+fill the polygon with.
+.
+The number is used to index into a stipple font at print time.
+.
+.IP \(bu
+The last line of each element contains a decimal number and a string of
+characters, separated by a single space.
+.
+The number is a count of the number of characters in the string.
+.
+This information is only used for text elements, and contains the text
+string.
+.
+There can be spaces inside the text.
+.
+For arcs, curves, and vectors, this line of the element contains the
+string \[lq]0\[rq].
+.
+.
+.\" ====================================================================
+.SH "NOTES ON COORDINATES"
+.\" ====================================================================
+.
+.I gremlin
+was designed for
+.IR AED s,
+and its coordinates reflect the
+.I AED
+coordinate space.
+.
+For vertical pictures, x-values range 116 to 511, and y-values from 0
+to 483.
+.
+For horizontal pictures, x-values range from 0 to 511 and y-values
+range from 0 to 367.
+.
+Although you needn't absolutely stick to this range, you'll
+get best results if you at least stay in this vicinity.
+.
+Also, point lists are terminated by a point of (\-1, \-1), so you
+shouldn't ever use negative coordinates.
+.
+.I gremlin
+writes out coordinates using format \[lq]%f1.2\[rq]; it's probably
+a good idea to use the same format if you want to modify the
+.I grn
+code.
+.
+.
+.\" ====================================================================
+.SH "NOTES ON SUN/X11 COORDINATES"
+.\" ====================================================================
+.
+There is no longer a restriction on the range of coordinates used to
+create objects in the
+.IR SUN / X11
+version of
+.IR gremlin .
+.
+However, files with negative coordinates
+.B will
+cause problems if displayed on the
+.IR AED .
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name /DESC
+Device description file for device
+.IR name .
+.
+.
+.\" ====================================================================
+.SH AUTHORS
+.\" ====================================================================
+David Slattengren and Barry Roitblat wrote the original Berkeley
+.IR grn .
+.
+Daniel Senderowicz and Werner Lemberg modified it for
+.IR groff .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR gremlin (1),
+.BR groff (1),
+.BR pic (1),
+.BR ideal (1)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[grn_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grodvi.1 b/upstream/mageia-cauldron/man1/grodvi.1
new file mode 100644
index 00000000..e5c0db4a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grodvi.1
@@ -0,0 +1,476 @@
+.TH GRODVI 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grodvi \- convert groff output to TeX DVI format
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr grodvi_C \n[.C]
+.cp 0
+.
+.
+.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el .ds tx TeX
+.
+.de FT
+.  if '\\*(.T'dvi' .ft \\$1
+..
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grodvi
+.OP \-dl
+.OP \-F dir
+.OP \-p papersize
+.OP \-w n
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY grodvi
+.B \-\-help
+.YS
+.
+.SY grodvi
+.B \-v
+.SY grodvi
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B grodvi
+is a driver for
+.B groff
+that produces \*(tx DVI format.
+.
+Normally it should be run by
+.BR groff\ \-Tdvi .
+.
+This will run
+.BR troff\ \-Tdvi ;
+it will also input the macros in
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/\:dvi.tmac .
+.
+.LP
+The DVI file generated by
+.B grodvi
+can be printed by any correctly-written DVI driver.
+.
+The troff drawing primitives are implemented
+using the tpic version\~2 specials.
+.
+If the driver does not support these, the
+.B \[rs]D
+commands will not produce any output.
+.
+.LP
+There is an additional drawing command available:
+.
+.TP
+.BI \[rs]D'R\  dh\ dv '
+Draw a rule (solid black rectangle), with one corner
+at the current position, and the diagonally opposite corner
+at the current position
+.RI +( dh , dv ).
+.
+Afterwards the current position will be at the opposite corner.
+.
+This produces a rule in the DVI file and so can be printed even with a
+driver that does not support the tpic specials unlike the other
+.B \[rs]D
+commands.
+.
+.LP
+The groff command
+.BI \[rs]X' anything '
+is translated into the same command in the DVI file as would be
+produced by
+.BI \[rs]special{ anything }
+in \*(tx;
+.I anything
+may not contain a newline.
+.
+.LP
+For inclusion of EPS image files,
+.B \-Tdvi
+loads
+.I pspic.tmac
+automatically, providing the
+.B PSPIC
+macro.
+.
+Please check
+.BR groff_tmac (5)
+for a detailed description.
+.
+.LP
+Font files for
+.B grodvi
+can be created from tfm files using
+.BR tfmtodit (1).
+.
+The font description file should contain the following
+additional commands:
+.
+.TP
+.BI internalname\   name
+The name of the tfm file (without the
+.I .tfm
+extension) is
+.IR name .
+.
+.TP
+.BI checksum\  n
+The checksum in the tfm file is
+.IR n .
+.
+.TP
+.BI designsize\  n
+The designsize in the tfm file is
+.IR n .
+.
+.LP
+These are automatically generated by
+.B tfmtodit.
+.
+.LP
+The default color for
+.B \[rs]m
+and
+.B \[rs]M
+is black.
+.
+Currently, the drawing color for
+.B \[rs]D
+commands is always black, and fill color values are translated to gray.
+.
+.LP
+In
+.B troff
+the
+.B \[rs]N
+escape sequence can be used to access characters by their position
+in the corresponding tfm file;
+all characters in the tfm file can be accessed this way.
+.
+.LP
+By design, the DVI format doesn't care about physical dimensions of the
+output medium.
+.
+Instead,
+.B grodvi
+emits the equivalent to \*[tx]'s
+.BI \[rs]special{papersize= width , length }
+on the first page;
+.B dvips
+(and possibly other DVI drivers) then sets the page size accordingly.
+.
+If either the page width or length is not positive, no papersize special
+is output.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-d
+Do not use tpic specials to implement drawing commands.
+.
+Horizontal and vertical lines will be implemented by rules.
+.
+Other drawing commands will be ignored.
+.
+.TP
+.BI \-F dir
+Prepend directory
+.RI dir /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device, usually
+.BR dvi .
+.
+.TP
+.B \-l
+Specify landscape orientation.
+.
+.TP
+.BI \-p papersize
+Specify paper dimensions.
+.
+This overrides the
+.BR papersize ,
+.BR paperlength ,
+and
+.B paperwidth
+commands in the
+.I DESC
+file; it accepts the same arguments as the
+.B papersize
+command (see
+.BR groff_font (5)
+for details).
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.BI \-w n
+Set the default line thickness to
+.I n
+thousandths of an em.
+.
+If this option isn't specified, the line thickness defaults to
+0.04\~em.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+There are styles called
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+mounted at font positions 1 to\ 4.
+The fonts are grouped into families
+.B T
+and
+.B H
+having members in each of these styles:
+.
+.RS
+.TP
+.B TR
+.FT TR
+CM Roman (cmr10)
+.FT
+.
+.TQ
+.B TI
+.FT TI
+CM Text Italic (cmti10)
+.FT
+.
+.TQ
+.B TB
+.FT TB
+CM Bold Extended Roman (cmbx10)
+.FT
+.
+.TQ
+.B TBI
+.FT TBI
+CM Bold Extended Text Italic (cmbxti10)
+.FT
+.
+.TQ
+.B HR
+.FT HR
+CM Sans Serif (cmss10)
+.FT
+.
+.TQ
+.B HI
+.FT HI
+CM Slanted Sans Serif (cmssi10)
+.FT
+.
+.TQ
+.B HB
+.FT HB
+CM Sans Serif Bold Extended (cmssbx10)
+.FT
+.
+.TQ
+.B HBI
+.FT HBI
+CM Slanted Sans Serif Bold Extended (cmssbxo10)
+.FT
+.RE
+.
+.LP
+There are also the following fonts which are not members of a family:
+.
+.RS
+.TP
+.B CW
+CM Typewriter Text (cmtt10)
+.FT CW
+.FT
+.
+.TQ
+.B CWI
+CM Italic Typewriter Text (cmitt10)
+.FT CWI
+.FT
+.RE
+.
+.LP
+Special fonts are
+.B MI
+(cmmi10),
+.B S
+(cmsy10),
+.B EX
+(cmex10),
+.B SC
+(cmtex10, only for
+.BR CW ),
+and, perhaps surprisingly,
+.BR TR ,
+.BR TI ,
+and
+.BR CW ,
+due to the different font encodings of text fonts.
+.
+For italic fonts,
+.B CWI
+is used instead of
+.BR CW .
+.
+.LP
+Finally, the symbol fonts of the American Mathematical Society are available
+as special fonts
+.B SA
+(msam10) and
+.B SB
+(msbm10).
+.
+These two fonts are not mounted by default.
+.
+.LP
+Using the option
+.B \-mec
+(which loads the file
+.IR ec.tmac )
+provides the EC and TC fonts.
+.
+The design of the EC family is very similar to that of the CM fonts;
+additionally, they give a much better coverage of groff symbols.
+.
+Note that
+.I ec.tmac
+must be called before any language-specific files; it doesn't take
+care of hcode values.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devdvi/DESC
+Device description file.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devdvi/ F
+Font description file for font
+.IR F .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/dvi.tmac
+Macros for use with
+.BR grodvi .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/ec.tmac
+Macros to switch to EC fonts.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+Dvi files produced by
+.B grodvi
+use a different resolution (57816 units per inch) from those produced by
+\*(tx.
+.
+Incorrectly written drivers which assume the resolution used by \*(tx,
+rather than using the resolution specified in the DVI file will not
+work with
+.BR grodvi .
+.
+.LP
+When using the
+.B \-d
+option with boxed tables,
+vertical and horizontal lines can sometimes protrude by one pixel.
+.
+This is a consequence of the way \*(tx requires that the heights
+and widths of rules be rounded.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR tfmtodit (1),
+.BR groff (1),
+.BR troff (1),
+.BR groff_out (5),
+.BR groff_font (5),
+.BR groff_char (7),
+.BR groff_tmac (5)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[grodvi_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/groff.1 b/upstream/mageia-cauldron/man1/groff.1
new file mode 100644
index 00000000..95c01591
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/groff.1
@@ -0,0 +1,2055 @@
+.TH GROFF 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+groff \- front-end for the groff document formatting system
+.
+.\" groff.man -> groff.1
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr groff_1_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" This file is part of groff, the GNU roff type-setting system.
+.\"
+.\" Permission is granted to copy, distribute and/or modify this
+.\" document under the terms of the GNU Free Documentation License,
+.\" Version 1.3 or any later version published by the Free Software
+.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
+.\" and with no Back-Cover Texts.
+.\"
+.\" A copy of the Free Documentation License is included as a file
+.\" called FDL in the main directory of the groff source package.
+.
+.
+.\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.\" ====================================================================
+.\" 'char or string'
+.de Quoted
+.  ft CR
+\[oq]\\$*\[cq]
+.  ft
+..
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY groff
+.OP \-abcegijklpstzCEGNRSUVXZ
+.OP \-d cs
+.OP \-D arg
+.OP \-f fam
+.OP \-F dir
+.OP \-I dir
+.OP \-K arg
+.OP \-L arg
+.OP \-m name
+.OP \-M dir
+.OP \-n num
+.OP \-o list
+.OP \-P arg
+.OP \-r cn
+.OP \-T dev
+.OP \-w name
+.OP \-W name
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY groff
+.B \-h
+.SY groff
+.B \-\-help
+.YS
+.
+.SY groff
+.B \-v
+.RI [ option
+\&.\|.\|.\&]
+.SY groff
+.B \-\-version
+.RI [ option
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This document describes the
+.B groff
+program, the main front-end for the
+.I groff
+document formatting system.
+.
+The
+.I groff
+program and macro suite is the implementation of a
+.BR roff (7)
+system within the free software collection
+.UR http://\:www.gnu.org
+GNU
+.UE .
+.
+The
+.I groff
+system has all features of the classical
+.IR roff ,
+but adds many extensions.
+.
+.
+.P
+The
+.B groff
+program allows control of the whole
+.I groff
+system by command-line options.
+.
+This is a great simplification in comparison to the classical case (which
+uses pipes only).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+The command line is parsed according to the usual \f[CR]GNU\f[]
+convention.
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+Options can be grouped behind a single \[oq]\-\[cq] (minus character).
+.
+A filename of
+.B \-
+(minus character) denotes the standard input.
+.
+.
+.P
+As
+.B groff
+is a wrapper program for
+.B troff
+both programs share a set of options.
+.
+But the
+.B groff
+program has some additional, native options and gives a new meaning to
+some
+.B troff
+options.
+.
+On the other hand, not all
+.B troff
+options can be fed into
+.BR groff .
+.
+.
+.\" ====================================================================
+.SS Native groff Options
+.\" ====================================================================
+.
+The following options either do not exist for
+.B troff
+or are differently interpreted by
+.BR groff .
+.
+.
+.TP
+.BI \-D\  arg
+Set default input encoding used by
+.B preconv
+to
+.IR arg .
+.
+Implies
+.BR \-k .
+.
+.
+.TP
+.B \-e
+Preprocess with
+.BR eqn .
+.
+.
+.TP
+.B \-g
+Preprocess with
+.BR grn .
+.
+.
+.TP
+.B \-G
+Preprocess with
+.BR grap .
+.
+Implies
+.BR \-p .
+.
+.
+.TP
+.B \-h
+.TQ
+.B \-\-help
+Print a help message.
+.
+.
+.TP
+.BI \-I\  dir
+This option may be used to specify a directory to search for
+files (both those on the command line and those named in
+.B .psbb
+and
+.B .so
+requests, and
+.B \eX'ps: import'
+,
+.B \eX'ps: file'
+and
+.B \eX'pdf: pdfpic'
+escapes).
+.
+The current directory is always searched first.
+.
+This option may be specified more than once;
+the directories are searched in the order specified.
+.
+No directory search is performed for files specified using an absolute path.
+.
+This option implies the
+.B \-s
+option.
+.
+.
+.TP
+.B \-j
+Preprocess with
+.BR chem .
+.
+Implies
+.BR \-p .
+.
+.
+.TP
+.B \-k
+Preprocess with
+.BR preconv .
+.
+This is run before any other preprocessor.
+.
+Please refer to
+.BR preconv 's
+manual page for its behaviour if no
+.B \-K
+(or
+.BR \-D )
+option is specified.
+.
+.
+.TP
+.BI \-K\  arg
+Set input encoding used by
+.B preconv
+to
+.IR arg .
+.
+Implies
+.BR \-k .
+.
+.
+.TP
+.B \-l
+Send the output to a spooler program for printing.
+.
+The command that should be used for this is specified by the
+.B print
+command in the device description file, see
+.BR \%groff_font (5).
+.
+If this command is not present, the output is piped into the
+.BR lpr (1)
+program by default.
+.
+See options
+.B \-L
+and
+.BR \-X .
+.
+.
+.TP
+.BI \-L\  arg
+Pass
+.I arg
+to the spooler program.
+.
+Several arguments should be passed with a separate
+\-L
+option each.
+.
+Note that
+.B groff
+does not prepend
+\[oq]\-\[cq]
+(a minus sign) to
+.I arg
+before passing it to the spooler program.
+.
+.
+.TP
+.B \-N
+Don't allow newlines within
+.I eqn
+delimiters.
+.
+This is the same as the
+.B \-N
+option in
+.BR eqn .
+.
+.
+.TP
+.B \-p
+Preprocess with
+.BR pic .
+.
+.
+.TP
+.BI \-P\  \-option
+.TQ
+.BI \-P\  \-option \ \-P\  arg
+Pass
+.I \-option
+or
+.I "\-option\~arg"
+to the postprocessor.
+.
+The option must be specified with the necessary preceding minus
+sign(s)
+.Quoted \-
+or
+.Quoted \-\-
+because
+.B groff
+does not prepend any dashes before passing it to the postprocessor.
+.
+For example, to pass a title to the
+.B \%gxditview
+postprocessor, the shell command
+.
+.RS
+.IP
+.EX
+groff \-X \-P \-title \-P 'groff it' \f[I]foo\f[]
+.EE
+.RE
+.
+.IP
+is equivalent to
+.
+.RS
+.IP
+.EX
+groff \-X \-Z \f[I]foo\f[] | \
+gxditview \-title 'groff it' \-
+.EE
+.RE
+.
+.
+.TP
+.B \-R
+Preprocess with
+.BR refer .
+.
+No mechanism is provided for passing arguments to
+.B refer
+because most
+.B refer
+options have equivalent language elements that can be specified within
+the document.
+.
+See
+.BR \%refer (1)
+for more details.
+.
+.
+.TP
+.B \-s
+Preprocess with
+.BR soelim .
+.
+.
+.TP
+.B \-S
+Safer mode.
+.
+Pass the
+.B \-S
+option to
+.B pic
+and disable the following
+.B troff
+requests:
+.BR .open ,
+.BR .opena ,
+.BR .pso ,
+.BR .sy ,
+and
+.BR .pi .
+.
+For security reasons, safer mode is enabled by default.
+.
+.
+.TP
+.B \-t
+Preprocess with
+.BR tbl .
+.
+.
+.TP
+.BI \-T\  dev
+Set output device to
+.IR dev .
+.
+For this device,
+.B troff
+generates the
+.I intermediate
+.IR output ;
+see
+.BR \%groff_out (5).
+.
+Then
+.B groff
+calls a postprocessor to convert
+.BR troff 's
+.I intermediate output
+to its final format.
+.
+Real devices in
+.B groff
+are
+.
+.RS
+.RS
+.TP
+dvi
+TeX DVI format (postprocessor is
+.BR grodvi ).
+.
+.TP
+html
+.TQ
+xhtml
+HTML and XHTML output (preprocessors are
+.B soelim
+and
+.BR \%pre-grohtml ,
+postprocessor is
+.BR \%post-grohtml ).
+.
+.TP
+lbp
+Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers;
+postprocessor is
+.BR grolbp ).
+.
+.TP
+lj4
+HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor
+is
+.BR grolj4 ).
+.
+.TP
+ps
+PostScript output (postprocessor is
+.BR grops ).
+.
+.TP
+pdf
+Portable Document Format (PDF) output (postprocessor is
+.BR gropdf ).
+.RE
+.RE
+.
+.
+.IP
+For the following TTY output devices (postprocessor is always
+.BR grotty ),
+.B \-T
+selects the output encoding:
+.
+.RS
+.RS
+.TP
+ascii
+7bit \f[CR]ASCII\f[].
+.
+.TP
+cp1047
+\%Latin-1 character set for EBCDIC hosts.
+.
+.TP
+latin1
+ISO \%8859-1.
+.
+.TP
+utf8
+Unicode character set in \%UTF-8 encoding.
+.
+This mode has the most useful fonts for TTY mode, so it is the best
+mode for TTY output.
+.RE
+.RE
+.
+.
+.IP
+The following arguments select
+.B \%gxditview
+as the \[oq]postprocessor\[cq] (it is rather a viewing program):
+.
+.RS
+.RS
+.TP
+X75
+75\|dpi resolution, 10\|pt document base font.
+.TP
+X75\-12
+75\|dpi resolution, 12\|pt document base font.
+.TP
+X100
+100\|dpi resolution, 10\|pt document base font.
+.TP
+X100\-12
+100\|dpi resolution, 12\|pt document base font.
+.RE
+.RE
+.
+.IP
+The default device is
+.BR ps .
+.
+.
+.TP
+.B \-U
+Unsafe mode.
+.
+Reverts to the (old) unsafe behaviour; see option
+.BR \-S .
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Output version information of
+.B groff
+and of all programs that are run by it; that is, the given command line
+is parsed in the usual way, passing
+.B \-v
+to all subprograms.
+.
+.
+.TP
+.B \-V
+Output the pipeline that would be run by
+.B groff
+(as a wrapper program) on the standard output, but do not execute it.
+.
+If given more than once,
+the commands are both printed on the standard error and run.
+.
+.
+.TP
+.B \-X
+Use
+.B \%gxditview
+instead of using the usual postprocessor to (pre)view a document.
+.
+The printing spooler behavior as outlined with options
+.B \-l
+and
+.B \-L
+is carried over to
+.BR \%gxditview (1)
+by determining an argument for the
+.B \-printCommand
+option of
+.BR \%gxditview (1).
+.
+This sets the default
+.B Print
+action and the corresponding menu entry to that value.
+.
+.B \-X
+only produces good results with
+.BR \-Tps ,
+.BR \-TX75 ,
+.BR \-TX75\-12 ,
+.BR \-TX100 ,
+and
+.BR \-TX100\-12 .
+.
+The default resolution for previewing
+.B \-Tps
+output is 75\|dpi; this can be changed by passing the
+.B \-resolution
+option to
+.BR \%gxditview ,
+for example
+.
+.RS
+.IP
+.EX
+groff \-X \-P\-resolution \-P100 \-man foo.1
+.EE
+.RE
+.
+.
+.TP
+.B \-z
+Suppress output generated by
+.BR troff .
+.
+Only error messages are printed.
+.
+.
+.TP
+.B \-Z
+Do not automatically postprocess
+.I groff intermediate output
+in the usual manner.
+.
+This will cause the
+.B troff
+.I output
+to appear on standard output,
+replacing the usual postprocessor output; see
+.BR \%groff_out (5).
+.
+.
+.\" ====================================================================
+.SS Transparent Options
+.\" ====================================================================
+.
+The following options are transparently handed over to the formatter
+program
+.B troff
+that is called by
+.B groff
+subsequently.
+.
+These options are described in more detail in
+.BR troff (1).
+.
+.TP
+.B \-a
+\f[CR]ASCII\f[] approximation of output.
+.
+.TP
+.B \-b
+Backtrace on error or warning.
+.
+.TP
+.B \-c
+Disable color output.
+.
+Please consult the
+.BR \%grotty (1)
+man page for more details.
+.
+.TP
+.B \-C
+Enable compatibility mode.
+.
+.TP
+.BI \-d\  cs
+.TQ
+.BI \-d\  name = s
+Define string.
+.
+.TP
+.B \-E
+Disable
+.B troff
+error messages.
+.
+.TP
+.BI \-f\  fam
+Set default font family.
+.
+.TP
+.BI \-F\  dir
+Set path for device
+.I DESC
+files.
+.
+.TP
+.B \-i
+Process standard input after the specified input files.
+.
+.TP
+.BI \-m\  name
+Include macro file
+.RI name .tmac
+(or
+.IR tmac. name);
+see also
+.BR \%groff_tmac (5).
+.
+.TP
+.BI \-M\  dir
+Path for macro files.
+.
+.TP
+.BI \-n\  num
+Number the first page
+.IR num .
+.
+.TP
+.BI \-o\  list
+Output only pages in
+.IR list .
+.
+.TP
+.BI \-r\  cn
+.TQ
+.BI \-r\  name = n
+Set number register.
+.
+.TP
+.BI \-w\  name
+Enable warning
+.IR name .
+.
+See
+.BR troff (1)
+for names.
+.
+.TP
+.BI \-W\  name
+disable warning
+.IR name .
+.
+See
+.BR troff (1)
+for names.
+.
+.
+.\" ====================================================================
+.SH "USING GROFF"
+.\" ====================================================================
+.
+The
+.I groff system
+implements the infrastructure of classical roff; see
+.BR roff (7)
+for a survey on how a
+.I roff
+system works in general.
+.
+Due to the front-end programs available within the
+.I groff
+system, using
+.I groff
+is much easier than
+.IR "classical roff" .
+.
+This section gives an overview of the parts that constitute the
+.I groff
+system.
+.
+It complements
+.BR roff (7)
+with
+.IR groff -specific
+features.
+.
+This section can be regarded as a guide to the documentation around
+the
+.I groff
+system.
+.
+.
+.\" ====================================================================
+.SS Paper Size
+.\" ====================================================================
+.
+The
+.I virtual
+paper size used by
+.B troff
+to format the input is controlled globally with the requests
+.BR .po ,
+.BR .pl ,
+and
+.BR .ll .
+.
+See
+.BR groff_tmac (5)
+for the \[oq]papersize\[cq] macro package which provides a convenient
+interface.
+.
+.
+.P
+The
+.I physical
+paper size, giving the actual dimensions of the paper sheets, is
+controlled by output devices like
+.B grops
+with the command-line options
+.B \-p
+and
+.BR \-l .
+.
+See
+.BR groff_font (5)
+and the man pages of the output devices for more details.
+.
+.B groff
+uses the command-line option
+.B \-P
+to pass options to output devices; for example, the following selects
+A4 paper in landscape orientation for the PS device:
+.
+.IP
+.EX
+groff \-Tps \-P\-pa4 \-P\-l ...
+.EE
+.
+.
+.\" ====================================================================
+.SS Front-ends
+.\" ====================================================================
+.
+The
+.B groff
+program is a wrapper around the
+.BR troff (1)
+program.
+.
+It allows one to specify the preprocessors by command-line options and
+automatically runs the postprocessor that is appropriate for the
+selected device.
+.
+Doing so, the sometimes tedious piping mechanism of classical
+.BR roff (7)
+can be avoided.
+.
+.
+.P
+The
+.BR grog (1)
+program can be used for guessing the correct
+.I groff
+command line to format a file.
+.
+.
+.P
+The
+.BR \%groffer (1)
+program is an all-around viewer for
+.I groff
+files and man pages.
+.
+.
+.\" ====================================================================
+.SS Preprocessors
+.\" ====================================================================
+.
+The
+.I groff
+preprocessors are reimplementations of the classical preprocessors
+with moderate extensions.
+.
+The standard preprocessors distributed with the
+.I groff
+package are
+.
+.TP
+.BR eqn (1)
+for mathematical formulae,
+.
+.TP
+.BR grn (1)
+for including
+.BR gremlin (1)
+pictures,
+.
+.TP
+.BR pic (1)
+for drawing diagrams,
+.
+.TP
+.BR chem (1)
+for chemical structure diagrams,
+.
+.TP
+.BR \%refer (1)
+for bibliographic references,
+.
+.TP
+.BR \%soelim (1)
+for including macro files from standard locations,
+.
+.P
+and
+.
+.TP
+.BR tbl (1)
+for tables.
+.
+.P
+A new preprocessor not available in classical
+.I troff
+is
+.BR \%preconv (1)
+which converts various input encodings to something
+.B groff
+can understand.
+.
+It is always run first before any other preprocessor.
+.
+.P
+Besides these, there are some internal preprocessors that are
+automatically run with some devices.
+.
+These aren't visible to the user.
+.
+.
+.\" ====================================================================
+.SS "Macro Packages"
+.\" ====================================================================
+.
+Macro packages can be included by option
+.BR \-m .
+.
+The
+.I groff
+system implements and extends all classical macro packages in a
+compatible way and adds some packages of its own.
+.
+Actually, the following macro packages come with
+.IR groff :
+.
+.TP
+.B man
+The traditional man page format; see
+.BR \%groff_man (7).
+It can be specified on the command line as
+.B \-man
+or
+.BR \-m\~man .
+.
+.TP
+.B mandoc
+The general package for man pages; it automatically recognizes
+whether the documents uses the
+.I man
+or the
+.I mdoc
+format and branches to the corresponding macro package.
+.
+It can be specified on the command line as
+.B \%\-mandoc
+or
+.BR \-m\~\%mandoc .
+.
+.TP
+.B mdoc
+The \f[CR]BSD\f[]-style man page format; see
+.BR \%groff_mdoc (7).
+.
+It can be specified on the command line as
+.B \-mdoc
+or
+.BR \-m\~mdoc .
+.
+.TP
+.B me
+The classical
+.I me
+document format; see
+.BR \%groff_me (7).
+.
+It can be specified on the command line as
+.B \-me
+or
+.BR \-m\~me .
+.
+.TP
+.B mm
+The classical
+.I mm
+document format; see
+.BR \%groff_mm (7).
+.
+It can be specified on the command line as
+.B \-mm
+or
+.BR \-m\~mm .
+.
+.TP
+.B ms
+The classical
+.I ms
+document format; see
+.BR \%groff_ms (7).
+It can be specified on the command line as
+.B \-ms
+or
+.BR \-m\~ms .
+.
+.TP
+.B www
+HTML-like macros for inclusion in arbitrary
+.I groff
+documents; see
+.BR \%groff_www (7).
+.
+.P
+Details on the naming of macro files and their placement can be found
+in
+.BR \%groff_tmac (5);
+this man page also documents some other, minor auxiliary macro packages
+not mentioned here.
+.
+.
+.\" ====================================================================
+.SS "Programming Language"
+.\" ====================================================================
+.
+General concepts common to all
+.I roff
+programming languages are described in
+.BR roff (7).
+.
+.
+.P
+The
+.I groff
+extensions to the classical
+.I troff
+language are documented in
+.BR \%groff_diff (7).
+.
+.
+.P
+An overview of language features,
+including all supported escapes and requests,
+can be found in
+.BR groff (7).
+.
+.
+.\" ====================================================================
+.SS Formatters
+.\" ====================================================================
+.
+The central
+.I roff
+formatter within the
+.I groff
+system is
+.BR troff (1).
+.
+It provides the features of both the classical
+.I troff
+and
+.IR nroff ,
+as well as the
+.I groff
+extensions.
+.
+The command-line option
+.B \-C
+switches
+.B troff
+into
+.I "compatibility mode"
+which tries to emulate classical
+.I roff
+as much as possible.
+.
+.
+.P
+There is a shell script
+.BR nroff (1)
+that emulates the behavior of classical
+.BR nroff .
+.
+It tries to automatically select the proper output encoding, according to
+the current locale.
+.
+.
+.P
+The formatter program generates
+.IR "intermediate output" ;
+see
+.BR \%groff_out (7).
+.
+.
+.\" ====================================================================
+.SS Devices
+.\" ====================================================================
+.
+In
+.IR roff ,
+the output targets are called
+.IR devices .
+A device can be a piece of hardware, e.g., a printer, or a software
+file format.
+.
+A device is specified by the option
+.BR \-T .
+.
+The
+.I groff
+devices are as follows.
+.
+.TP
+.B ascii
+Text output using the
+.BR ascii (7)
+character set.
+.
+.TP
+.B cp1047
+Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix).
+.
+.TP
+.B dvi
+TeX DVI format.
+.
+.TP
+.B html
+HTML output.
+.
+.TP
+.B latin1
+Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see
+.BR \%iso_8859_1 (7).
+.
+.TP
+.B lbp
+Output for Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser
+printers).
+.
+.TP
+.B lj4
+HP LaserJet4-compatible (or other PCL5-compatible) printers.
+.
+.TP
+.B ps
+PostScript output; suitable for printers and previewers like
+.BR gv (1).
+.
+.TP
+.B pdf
+PDF files; suitable for viewing with tools such as
+.BR evince (1)
+and
+.BR okular (1).
+.
+.TP
+.B utf8
+Text output using the Unicode (ISO 10646) character set with \%UTF-8
+encoding; see
+.BR unicode (7).
+.
+.TP
+.B xhtml
+XHTML output.
+.
+.TP
+.B X75
+75dpi X Window System output suitable for the previewers
+.BR \%xditview (1x)
+and
+.BR \%gxditview (1).
+.
+A variant for a 12\|pt document base font is
+.BR \%X75-12 .
+.
+.TP
+.B X100
+100dpi X Window System output suitable for the previewers
+.BR \%xditview (1x)
+and
+.BR \%gxditview (1).
+.
+A variant for a 12\|pt document base font is
+.BR \%X100-12 .
+.
+.
+.P
+The postprocessor to be used for a device is specified by the
+.B postpro
+command in the device description file; see
+.BR \%groff_font (5).
+.
+This can be overridden with the
+.B \-X
+option.
+.
+.P
+The default device is
+.BR ps .
+.
+.
+.\" ====================================================================
+.SS Postprocessors
+.\" ====================================================================
+.
+.I groff
+provides 3\~hardware postprocessors:
+.
+.TP
+.BR \%grolbp (1)
+for some Canon printers,
+.
+.TP
+.BR \%grolj4 (1)
+for printers compatible to the HP LaserJet\~4 and PCL5,
+.
+.TP
+.BR \%grotty (1)
+for text output using various encodings, e.g., on text-oriented
+terminals or line printers.
+.
+.
+.P
+Today, most printing or drawing hardware is handled by the operating
+system, by device drivers, or by software interfaces, usually
+accepting PostScript.
+.
+Consequently, there isn't an urgent need for more hardware device
+postprocessors.
+.
+.
+.P
+The
+.I groff
+software devices for conversion into other document file formats are
+.
+.TP
+.BR \%grodvi (1)
+for the DVI format,
+.
+.TP
+.BR \%grohtml (1)
+for HTML and XHTML formats,
+.
+.TP
+.BR grops (1)
+for PostScript.
+.
+.TP
+.BR gropdf (1)
+for PDF.
+.
+.
+.P
+Combined with the many existing free conversion tools this should
+be sufficient to convert a
+.I troff
+document into virtually any existing data format.
+.
+.
+.\" ====================================================================
+.SS Utilities
+.\" ====================================================================
+.
+The following utility programs around
+.I groff
+are available.
+.
+.TP
+.BR \%addftinfo (1)
+Add information to
+.I troff
+font description files for use with
+.IR groff .
+.
+.TP
+.BR \%afmtodit (1)
+Create font description files for PostScript device.
+.
+.TP
+.BR \%eqn2graph (1)
+Convert an
+.B eqn
+image into a cropped image.
+.
+.TP
+.BR \%gdiffmk (1)
+Mark differences between
+.IR groff ,
+.IR nroff ,
+or
+.I troff
+files.
+.
+.TP
+.BR \%grap2graph (1)
+Convert a
+.B grap
+diagram into a cropped bitmap image.
+.
+.TP
+.BR \%groffer (1)
+General viewer program for
+.I groff
+files and man pages.
+.
+.TP
+.BR \%gxditview (1)
+The
+.I groff
+X viewer, the \f[CR]GNU\f[] version of
+.BR xditview .
+.
+.TP
+.BR \%hpftodit (1)
+Create font description files for lj4 device.
+.
+.TP
+.BR \%indxbib (1)
+Make inverted index for bibliographic databases.
+.
+.TP
+.BR lkbib (1)
+Search bibliographic databases.
+.
+.TP
+.BR \%lookbib (1)
+Interactively search bibliographic databases.
+.
+.TP
+.BR \%pdfroff (1)
+Create PDF documents using
+.BR groff .
+.
+.TP
+.BR \%pfbtops (1)
+Translate a PostScript font in \&.pfb format to \f[CR]ASCII\f[].
+.
+.TP
+.BR \%pic2graph (1)
+Convert a
+.B pic
+diagram into a cropped image.
+.
+.TP
+.BR \%tfmtodit (1)
+Create font description files for TeX DVI device.
+.
+.TP
+.BR \%xditview (1x)
+.I roff
+viewer historically distributed with the X Window System.
+.\" Nowadays (2017) it's its own module as X.Org does not do monolithic
+.\" releases anymore (since 2012).  Development on "app/xditview" is
+.\" close to moribund, though.
+.
+.TP
+.BR \%xtotroff (1)
+Convert X font metrics into \f[CR]GNU\f[]
+.I troff
+font metrics.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+Normally, the path separator in the following environment variables is
+the colon; this may vary depending on the operating system.
+.
+For example, DOS and Windows use a semicolon instead.
+.
+.
+.TP
+.I GROFF_BIN_PATH
+This search path, followed by
+.IR PATH ,
+is used for commands that are executed by
+.BR groff .
+.
+If it is not set then the directory where the
+.I groff
+binaries were installed is prepended to
+.IR PATH .
+.
+.
+.TP
+.I GROFF_COMMAND_PREFIX
+When there is a need to run different
+.I roff
+implementations at the same time
+.I groff
+provides the facility to prepend a prefix to most of its programs that
+could provoke name clashings at run time (default is to have none).
+.
+Historically, this prefix was the character
+.BR g ,
+but it can be anything.
+.
+For example,
+.B gtroff
+stood for
+.IR groff 's
+.BR troff ,
+.B gtbl
+for the
+.I groff
+version of
+.BR tbl .
+.
+By setting
+.I \%GROFF_COMMAND_PREFIX
+to different values, the different
+.I roff
+installations can be addressed.
+.
+More exactly, if it is set to prefix
+.I xxx
+then
+.B groff
+as a wrapper program internally calls
+.IB xxx troff
+instead of
+.BR troff .
+.
+This also applies to the preprocessors
+.BR eqn ,
+.BR grn ,
+.BR pic ,
+.BR \%refer ,
+.BR tbl ,
+.BR \%soelim ,
+and to the utilities
+.B \%indxbib
+and
+.BR \%lookbib .
+.
+This feature does not apply to any programs different from the ones
+above (most notably
+.B groff
+itself) since they are unique to the
+.I groff
+package.
+.
+.
+.TP
+.I GROFF_ENCODING
+The value of this environment value is passed to the
+.B preconv
+preprocessor to select the encoding of input files.
+.
+Setting this option implies
+.BR groff 's
+command-line option
+.B \-k
+(this is,
+.B groff
+actually always calls
+.BR preconv ).
+.
+If set without a value,
+.B groff
+calls
+.B preconv
+without arguments.
+.
+An explicit
+.B \-K
+command-line option overrides the value of
+.IR \%GROFF_ENCODING .
+.
+See
+.BR preconv (1)
+for details.
+.
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.TP
+.I GROFF_TMAC_PATH
+A list of directories in which to search for macro files in addition
+to the default directories.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_tmac (5)
+for more details.
+.
+.
+.TP
+.I GROFF_TMPDIR
+The directory in which temporary files are created.
+.
+If this is not set but the environment variable
+.I \%TMPDIR
+instead, temporary files are created in the directory
+.IR \%TMPDIR .
+.
+On MS-DOS and Windows platforms, the environment variables
+.I TMP
+and
+.I TEMP
+(in that order) are searched also, after
+.I \%GROFF_TMPDIR
+and
+.IR \%TMPDIR .
+.
+Otherwise, temporary files are created in
+.IR /tmp .
+.
+The
+.BR \%refer (1),
+.BR \%groffer (1),
+.BR \%grohtml (1),
+and
+.BR grops (1)
+commands use temporary files.
+.
+.
+.TP
+.I GROFF_TYPESETTER
+Preset the default device.
+.
+If this is not set the
+.B ps
+device is used as default.
+.
+This device name is overwritten by the option
+.BR \-T .
+.
+.
+.\" ====================================================================
+.SH EXAMPLES
+.\" ====================================================================
+.
+The following example illustrates the power of the
+.B groff
+program as a wrapper around
+.BR troff .
+.
+.
+.P
+To process a
+.I roff
+file using the preprocessors
+.B tbl
+and
+.B pic
+and the
+.B me
+macro set, classical
+.I troff
+had to be called by
+.
+.IP
+.EX
+pic foo.me | tbl | troff \-me \-Tlatin1 | grotty
+.EE
+.
+.
+.P
+Using
+.BR groff ,
+this pipe can be shortened to the equivalent command
+.
+.IP
+.EX
+groff \-p \-t \-me \-T latin1 foo.me
+.EE
+.
+.
+.P
+An even easier way to call this is to use
+.BR grog (1)
+to guess the preprocessor and macro options and execute the generated
+command (by using backquotes to specify shell command substitution)
+.
+.IP
+.EX
+\[ga]grog \-Tlatin1 foo.me\[ga]
+.EE
+.
+.
+.P
+The simplest way is to view the contents in an automated way by
+calling
+.
+.IP
+.EX
+groffer foo.me
+.EE
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+On \f[CR]EBCDIC\f[] hosts (e.g., \f[CR]OS/390 Unix\f[]), output
+devices
+.B ascii
+and
+.B latin1
+aren't available.
+.
+Similarly, output for \f[CR]EBCDIC\f[] code page
+.B cp1047
+is not available on \f[CR]ASCII\f[] based operating systems.
+.
+.
+.\" ====================================================================
+.SH "INSTALLATION DIRECTORIES"
+.\" ====================================================================
+.
+.I groff
+installs files in varying locations depending on its compile-time
+configuration.
+.
+On this installation, the following locations are used.
+.
+.
+.TP
+.I /usr/\:lib64/\:X11/\:app\-defaults/\:
+Application defaults directory for
+.IR gxditview (1).
+.
+.
+.TP
+.I /usr/\:bin
+Directory containing
+.IR groff 's
+executable commands.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:eign
+List of common words for
+.IR indxbib (1).
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4
+Directory for data files.
+.
+.
+.TP
+.I /usr/\:dict/\:papers/\:Ind
+Default index for
+.IR lkbib (1)
+and
+.IR refer (1).
+.
+.
+.TP
+.I /usr/\:share/\:doc/\:groff\-1.22.4
+Documentation directory.
+.
+.
+.TP
+.I /usr/\:share/\:doc/\:groff\-1.22.4/\:examples
+Example directory.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font
+Font directory.
+.
+.
+.TP
+.I /usr/\:share/\:doc/\:groff\-1.22.4/\:html
+HTML documentation directory.
+.
+.
+.TP
+.I /usr/\:lib/\:font
+Legacy font directory.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:site\-font
+Local font directory.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:site\-tmac
+Local macro package
+.RI ( tmac
+file) directory.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac
+Macro package
+.RI ( tmac
+file) directory.
+.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:oldfont
+Font directory for compatibility with old versions of
+.IR groff ;
+see
+.IR grops (1).
+.
+.
+.TP
+.I /usr/\:share/\:doc/\:groff\-1.22.4/\:pdf
+PDF documentation directory.
+.
+.
+.TP
+.I /usr/\:lib64/\:groff/\:site\-tmac
+System macro package
+.RI ( tmac
+file) directory.
+.
+.
+.\" ====================================================================
+.SS "groff Macro Directory"
+.\" ====================================================================
+.
+This contains all information related to macro packages.
+.
+Note that more than a single directory is searched for those files
+as documented in
+.BR \%groff_tmac (5).
+.
+For the
+.I groff
+installation corresponding to this document, it is located at
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
+.
+The following files contained in the
+.I groff macro directory
+have a special meaning:
+.
+.
+.TP
+.I troffrc
+Initialization file for
+.IR troff .
+.
+This is interpreted by
+.B troff
+before reading the macro sets and any input.
+.
+.
+.TP
+.I troffrc\-end
+Final startup file for
+.IR troff .
+.
+It is parsed after all macro sets have been read.
+.
+.
+.TP
+.RI name .tmac
+.TQ
+.IR tmac. name
+Macro file for macro package
+.IR name .
+.
+.
+.\" ====================================================================
+.SS "groff Font Directory"
+.\" ====================================================================
+.
+This contains all information related to output devices.
+.
+Note that more than a single directory is searched for those files; see
+.BR troff (1).
+.
+For the
+.I groff
+installation corresponding to this document, it is located at
+.IR /usr/\:share/\:groff/\:1.22.4/\:font .
+.
+The following files contained in the
+.I "groff font directory"
+have a special meaning:
+.
+.
+.TP
+.IR dev name /DESC
+Device description file for device
+.IR name ,
+see
+.BR \%groff_font (5).
+.
+.
+.TP
+.IR dev name / F
+Font file for font
+.I F
+of device
+.IR name .
+.
+.
+.\" ====================================================================
+.SH AVAILABILITY
+.\" ====================================================================
+.
+Information on how to get
+.I groff
+and related information is available at the
+.UR http://\:www.gnu.org/\:software/\:groff
+groff page of the GNU website
+.UE .
+.
+.
+.P
+Three
+.I groff
+mailing lists are available:
+.
+.
+.IP
+.MT bug\-groff@\:gnu.org
+bug tracker activity (read-only)
+.ME ;
+.
+.
+.IP
+.MT groff@\:gnu.org
+general discussion
+.ME ;
+and
+.
+.
+.IP
+.MT groff\-commit@\:gnu.org
+commit activity (read-only)
+.ME ,
+which reports changes to
+.IR groff 's
+source code repository by its developers.
+.
+.
+.P
+Details on repository access and much more can be found in the file
+.I README
+at the top directory of the
+.I groff
+source package.
+.
+.
+.P
+A free implementation of the
+.B grap
+preprocessor, written by
+.MT faber@\:lunabase.org
+Ted Faber
+.ME ,
+can be found at the
+.UR http://\:www.lunabase.org/\:\|\[ti]faber/\:Vault/\:software/\:grap/
+grap website
+.UE .
+.
+This is the only
+.I grap
+supported by
+.IR groff .
+.
+.
+.\" ====================================================================
+.SH AUTHORS
+.\" ====================================================================
+.
+.B groff
+was written by
+.MT jjc@\:jclark.com
+James Clark
+.ME .
+.
+This document was rewritten, enhanced, and put under the FDL license in
+2002 by
+.MT groff\-bernd.warken\-72@\:web.de
+Bernd Warken
+.ME .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \[lq]info groff\[rq].
+.
+.
+.P
+Due to its complex structure, the
+.I groff
+system has many man pages.
+.
+They can be read with
+.BR man (1)
+or
+.BR \%groffer (1).
+.
+.P
+But there are special sections of
+.IR "man pages" .
+.
+.I groff
+has man pages in sections
+.BR 1 , " 5" , and " 7" .
+.
+When there are several
+.I man pages
+with the same name in the same
+.I man
+section, the one with the lowest section is should as first.
+.
+The other man pages can be shown anyway by adding the section number
+as argument before the man page name.
+.
+Reading the man page about the
+.I groff
+language is done by one of
+.RS
+.nf
+.nh
+.EX
+.B man 7 groff
+.B groffer 7 groff
+.EE
+.hy
+.fi
+.RE
+.
+.ad l
+.TP
+Introduction, history and further readings:
+.BR roff (7).
+.
+.TP
+Viewer for groff files:
+.BR \%groffer (1),
+.BR \%gxditview (1),
+.BR \%xditview (1x).
+.
+.TP
+Wrapper programs for formatters:
+.BR \%groff (1),
+.BR \%grog (1).
+.
+.TP
+Roff preprocessors:
+.BR \%eqn (1),
+.BR \%grn (1),
+.BR \%pic (1),
+.BR \%chem (1),
+.BR \%preconv (1),
+.BR \%refer (1),
+.BR \%soelim (1),
+.BR \%tbl (1),
+.BR grap (1).
+.
+.TP
+Roff language with the groff extensions:
+.BR \%groff (7),
+.BR \%groff_char (7),
+.BR \%groff_diff (7),
+.BR \%groff_font (5).
+.
+.TP
+Roff formatter programs:
+.BR \%nroff (1),
+.BR \%troff (1),
+.BR ditroff (7).
+.
+.TP
+The intermediate output language:
+.BR \%groff_out (7).
+.
+.TP
+Postprocessors for the output devices:
+.BR \%grodvi (1),
+.BR \%grohtml (1),
+.BR \%grolbp (1),
+.BR \%grolj4 (1),
+.BR \%lj4_font (5),
+.BR \%grops (1),
+.BR \%gropdf (1),
+.BR \%grotty (1).
+.
+.TP
+Groff macro packages and macro-specific utilities:
+.BR \%groff_tmac (5),
+.BR \%groff_man (7),
+.BR \%groff_mdoc (7),
+.BR \%groff_me (7),
+.BR \%groff_mm (7),
+.BR \%groff_mmse (7),
+.BR \%groff_mom (7),
+.BR \%groff_ms (7),
+.BR \%groff_www (7),
+.BR \%groff_trace (7),
+.BR \%mmroff (7).
+.
+.TP
+The following utilities are available:
+.BR \%addftinfo (1),
+.BR \%afmtodit (1),
+.BR \%eqn2graph (1),
+.BR \%gdiffmk (1),
+.BR \%grap2graph (1),
+.BR \%groffer (1),
+.BR \%gxditview (1),
+.BR \%hpftodit (1),
+.BR \%indxbib (1),
+.BR \%lkbib (1),
+.BR \%lookbib (1),
+.BR \%pdfroff (1),
+.BR \%pfbtops (1),
+.BR \%pic2graph (1),
+.BR \%tfmtodit (1),
+.BR \%xtotroff (1).
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[groff_1_C]
+.
+.
+.\" ====================================================================
+.\" Emacs setup
+.\" ====================================================================
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grohtml.1 b/upstream/mageia-cauldron/man1/grohtml.1
new file mode 100644
index 00000000..f86fe3fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grohtml.1
@@ -0,0 +1,446 @@
+.TH GROHTML 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grohtml \- HTML driver for groff
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1999-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grohtml
+.OP \-bhlnprVy
+.OP \-a aa-text-bits
+.OP \-D dir
+.OP \-F dir
+.OP \-g aa-graphic-bits
+.OP \-i resolution
+.OP \-I image-stem
+.OP \-j filename
+.OP \-o image-vertical-offset
+.OP \-s size
+.OP \-S level
+.OP \-x html-dialect
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY grohtml
+.B \-\-help
+.YS
+.
+.SY grohtml
+.B \-v
+.SY grohtml
+.B \-\-version
+.YS
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+The
+.B grohtml
+front end (which consists of a preprocessor,
+.BR pre-grohtml ,
+and a device driver,
+.BR post-grohtml )
+translates the output of GNU
+.B troff
+to HTML.
+.
+Users should always invoke
+.B grohtml
+via the groff command with a
+.B \-Thtml
+option.
+.
+If no files are given,
+.B grohtml
+will read the standard input.
+.
+A filename of
+.B \-
+will also cause
+.B grohtml
+to read the standard input.
+.
+Html output is written to the standard output.
+.
+When
+.B grohtml
+is run by
+.B groff
+options can be passed to
+.B grohtml
+using
+.BR groff 's
+.B \-P
+option.
+.
+.
+.PP
+.B grohtml
+invokes
+.B groff
+twice.
+In the first pass, pictures, equations, and tables are rendered
+using the
+.B ps
+device, and in the second pass HTML output is generated by the
+.B html
+device.
+.
+.
+.PP
+.B grohtml
+always writes output in \%UTF-8 encoding and has built-in entities for
+all non-composite unicode characters.
+.
+In spite of this, groff may issue warnings about unknown special
+characters if they can't be found during the first pass.
+.
+Such warnings can be safely ignored unless the special characters
+appear inside a table or equation.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.TP
+.BI \-a aa-text-bits
+Number of bits of antialiasing information to be used by
+.I text
+when generating PNG images.
+.
+The default is\~4 but valid values are 0, 1, 2, and\~4.
+.
+Note your version of
+.B gs
+needs to support the
+.B \%\-dTextAlphaBits
+and
+.B \%\-dGraphicAlphaBits
+options in order to exploit antialiasing.
+.
+A value of\~0 stops
+.B grohtml
+from issuing antialiasing commands to
+.BR gs .
+.
+.TP
+.B \-b
+Initialize the background color to white.
+.
+.TP
+.BI \-D dir
+Inform
+.B grohtml
+to place all image files into directory
+.IR dir .
+.
+.TP
+.B \-e
+This option should not be directly invoked by the user as it is an
+internal option utilized by
+.B groff
+when
+.B \-Thtml
+or
+.B \-Txhtml
+is specified.
+It is used by the
+.B grohtml
+preprocessor to determine whether
+.B eqn
+should attempt to produce MathML (if
+.B \-Txhtml
+is specified).
+.
+.TP
+.BI \-F dir
+Prepend directory
+.RI dir /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device, usually
+.BR html .
+.
+.TP
+.BI \-g aa-graphic-bits
+Number of bits of antialiasing information to be used by
+.I graphics
+when generating PNG images.
+.
+The default is\~4 but valid values are 0, 1, 2, and\~4.
+.
+Note your version of
+.B gs
+needs to support the
+.B \%\-dTextAlphaBits
+and
+.B \%\-dGraphicAlphaBits
+options in order to exploit antialiasing.
+.
+A value of\~0 stops
+.B grohtml
+from issuing antialiasing commands to
+.BR gs .
+.
+.TP
+.B \-h
+Generate section and number headings by using
+.BR <B> .\|.\|. </B>
+and increasing the font size, rather than using the
+.BI <H n >\c
+\&.\|.\|.\c
+.BI </H n >
+tags.
+.
+.TP
+.BI \-i resolution
+Select the resolution for all images.
+.
+By default this is 100 pixels per inch.
+.
+Example:
+.B \-i200
+indicates 200 pixels per inch.
+.
+.TP
+.BI \-I stem
+Determine the image stem name.
+.
+If omitted grohtml uses
+.BI \%grohtml- XXX
+.RI ( XXX
+is the process ID).
+.
+.TP
+.BI \-j filename
+Inform
+.B grohtml
+to split the HTML output into multiple files.
+.
+The
+.I filename
+is the stem and specified section headings (default is level one)
+start a new file, named
+.IR filename-n.html .
+.
+.TP
+.B \-l
+Turn off the production of automatic section links at the top of the
+document.
+.
+.TP
+.B \-n
+Generate simple heading anchors whenever a section/number heading is
+found.
+.
+Without the option the anchor value is the textual heading.
+.
+This can cause problems when a heading contains a \(oq?\(cqa on older
+versions of some browsers (Netscape).
+.
+This flag is automatically turned on if a heading contains an image.
+.
+.TP
+.BI \-o vertical-offset
+Specify the vertical offset of images in points.
+.
+.TP
+.B \-p
+Display page rendering progress to stderr.
+.B grohtml
+only displays a page number when an image is required.
+.
+.TP
+.B \-r
+Turn off the automatic header and footer line (HTML rule).
+.
+.TP
+.B \-s size
+Set the base point size of the source file.
+.
+Thereafter when this point size is used in the source it will
+correspond to the HTML base size.
+.
+Every increase of two points in the source will yield a
+.B <big>
+tag, and conversely when a decrease of two points is seen a
+.B <small>
+tag is emitted.
+.
+.TP
+.BI \-S level
+When splitting HTML output,
+split at the heading level (or higher) defined by
+.IR level .
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.B \-V
+Create an XHTML or HTML validator button at the bottom of each page of
+the document.
+.
+.TP
+.BI \-x dialect
+Select HTML dialect.
+.
+Currently,
+.I dialect
+should be either the digit\~\c
+.B 4
+or the letter\~\c
+.B x
+which indicates whether
+.B grohtml
+should generate HTML\~4 or XHTML, respectively.
+.
+This option should not be directly invoked by the user as it is
+an internal option utilized by
+.B groff
+when
+.B \-Thtml
+or
+.B \-Txhtml
+is specified.
+.
+.TP
+.B \-y
+Produce a right-justified groff signature at the end of the document.
+.
+This is only generated if the
+.B \-V
+flag is also specified.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+There are styles called
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+mounted at font positions 1 to\~4.
+.
+.
+.\" ====================================================================
+.SH DEPENDENCIES
+.\" ====================================================================
+.
+.B grohtml
+is dependent upon the PNG utilities
+.RB ( \%pnmcut ,
+.BR \%pnmcrop ,
+.BR \%pnmtopng )
+and GhostScript
+.RB ( gs ).
+.
+.B \%pnmtopng
+(version 2.37.6 or greater)
+and
+.B \%pnmcut
+from the netpbm package (version 9.16 or greater) will work also.
+.
+It is also dependent upon
+.B \%psselect
+from the
+.B PSUtils
+package.
+.
+Images are generated whenever a table, picture, equation or line is
+encountered.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.B grohtml
+uses temporary files.
+.
+See the
+.BR groff (1)
+man page for details where such files are created.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp (expressed as seconds since the Unix epoch) to use as the
+creation timestamp in place of the current time.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+.B Grohtml
+has been completely redesigned and rewritten.
+.
+It is still beta code.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR afmtodit (1),
+.BR groff (1),
+.BR troff (1),
+.BR psbb (1),
+.BR groff_out (5),
+.BR groff_font (5),
+.BR groff_char (7)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grolbp.1 b/upstream/mageia-cauldron/man1/grolbp.1
new file mode 100644
index 00000000..cc25de7e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grolbp.1
@@ -0,0 +1,456 @@
+'\" t
+.TH GROLBP 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grolbp \- groff driver for Canon CAPSL printers (LBP-4 and LBP-8 \
+series laser printers)
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr grolbp_C \n[.C]
+.cp 0
+.
+.
+.\" Modified by Francisco Andrés Verdú <pandres@dragonet.es> for the
+.\" grolbp program.
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1994-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grolbp
+.OP \-l
+.OP \-c num-copies
+.OP \-F font-directory
+.OP \-o orientation
+.OP \-p paper-size
+.OP \-w width
+.RI [ file
+\&.\|.\|.\&]
+.SY grolbp
+[\c
+.BI \-\-copies= num-copies\c
+] [\c
+.BI \-\-fontdir= font-directory\c
+] [\c
+.B \-\-landscape\c
+] [\c
+.BI \-\-linewidth= width\c
+] [\c
+.BI \-\-orientation= orientation\c
+] [\c
+.BI \-\-papersize= paper-size\c
+]
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY grolbp
+.B \-h
+.SY grolbp
+.B \-\-help
+.YS
+.
+.SY grolbp
+.B \-v
+.SY grolbp
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B grolbp
+is a driver for
+.B groff
+that produces output in CAPSL and VDM format suitable for Canon LBP-4
+and LBP-8 printers.
+.
+.
+.LP
+For compatibility with
+.BR grolj4 (1)
+there is an additional drawing command available:
+.
+.TP
+.BI \eD'R\  dh\ dv '
+Draw a rule
+(i.e., a solid black rectangle),
+with one corner at the current position,
+and the diagonally opposite corner at the current
+position
+.RI +( dh , dv ).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Note that there can be whitespace between a one-letter option and its
+argument;
+on the other hand, there must be whitespace and/or an equal sign
+(\(oq=\(cq) between a long-name option and its argument.
+.
+.
+.TP
+.BI \-c " num-copies"
+.TQ
+.BI \-\-copies= num-copies
+Print
+.I num-copies
+copies of each page.
+.
+.
+.TP
+.BI \-F " font-directory"
+.TQ
+.BI \-\-fontdir= font-directory
+Prepend directory
+.RI font-directory /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device, usually
+.BR lbp .
+.
+.
+.TP
+.B \-h
+.TQ
+.B \-\-help
+Print a short help text.
+.
+.
+.TP
+.B \-l
+.TQ
+.B \-\-landscape
+Print the document with a landscape orientation.
+.
+.
+.TP
+.BI \-o " orientation"
+.TQ
+.BI \-\-orientation= orientation
+Print the document with
+.I orientation
+orientation, which must be \(oqportrait\(cq or \(oqlandscape\(cq.
+.
+.
+.TP
+.BI \-p " paper-size"
+.TQ
+.BI \-\-papersize= paper-size
+Set the paper size to
+.IR paper-size ,
+which must be a valid paper size description as indicated in section
+\[lq]Paper Sizes\[rq], below.
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Print the version number.
+.
+.
+.TP
+.BI \-w " width"
+.TQ
+.BI \-\-linewidth= width
+Set the default line thickness to
+.I width
+thousandths of an em.
+.
+If this option isn't specified, the line thickness defaults to 0.04\~em.
+.
+.
+.\" ====================================================================
+.SH TYPEFACES
+.\" ====================================================================
+.
+The driver supports the Dutch, Swiss and Swiss-Narrow scalable
+typefaces, each one in the Regular, Bold, Italic and Bold-Italic styles.
+.
+Additionally, the Courier and Elite monospaced typefaces at the sizes 8
+and 12 points (for Courier) resp.\& 8 and 10 points (for Elite) are
+supported, each one in the Regular, Bold and Italic styles.
+.
+.
+.PP
+The following chart summarizes the font names you can use to access
+these fonts:
+.
+.
+.PP
+.TS
+tab(|) allbox center;
+c c c c c
+ab c c c c
+.
+Typeface | Regular | Bold | Italic | Bold-Italic
+Dutch | TR | TB | TI | TBI
+Swiss | HR | HB | HI | HBI
+Swiss Narrow | HNR | HNB | HNI | HNBI
+Courier | CR | CB | CI |
+Elite | ER | EB | EI |
+.TE
+.
+.
+.\" ====================================================================
+.SH PAPER SIZES
+.\" ====================================================================
+.
+The paper size can be set in the
+.I DESC
+file or with command-line options to
+.BR grolbp .
+If the paper size is specified both ways, the command-line options take
+precedence over the contents of the
+.I DESC
+file (this applies to the page orientation too).
+.
+.
+.PP
+See
+.BR groff_font (5)
+how to set the paper dimensions in the
+.I DESC
+file.
+.
+.
+.PP
+To set the paper size in the command line, add
+.sp 1
+.in +2m
+.BI \-p \ paper-size
+.in -2m
+.sp 1
+or
+.sp 1
+.in +2m
+.BI \-\-papersize= paper-size
+.in -2m
+.sp 1
+to the other
+.B grolbp
+options, where
+.I paper-size
+is in the same format as in the
+.I DESC
+file.
+.
+.
+.PP
+If no paper size is specified in the
+.I DESC
+file or the command line, a default size of A4 is used.
+.
+.
+.\" ====================================================================
+.SH PAGE ORIENTATION
+.\" ====================================================================
+.
+As with the page size, the orientation of the printed page
+.RB ( portrait
+or
+.BR landscape )
+can be set in the
+.I DESC
+file or with command-line options.
+.
+It is also case insensitive.
+.
+.
+.PP
+To set the orientation in the
+.I DESC
+file, insert a line with the following content:
+.sp 1
+.in +2m
+.B orientation
+.RB [ portrait | landscape ]
+.in -2m
+.sp 1
+.
+Only the first valid orientation command in the
+.I DESC
+file is used.
+.
+.
+.PP
+To set the page orientation with command-line options you can use the
+.B \-o
+or
+.B \-\-orientation
+option with the same parameters
+.RB ( portrait
+or
+.BR landscape )
+as in the
+.I DESC
+file.
+Or you can use the
+.B \-l
+option to force the pages to be printed in landscape.
+.
+.
+.\" ====================================================================
+.SH FONT FILE FORMAT
+.\" ====================================================================
+.
+In addition to the usual commands described in
+.BR groff_font (5),
+.B grolbp
+provides the command
+.I lbpname
+which sets the font name sent to the printer when requesting this font.
+.
+The syntax of this command is:
+.sp 1
+.in +2m
+.B lbpname
+.I printer_font_name
+.in -2m
+.
+.IP \(bu
+For bitmapped fonts,
+.I printer_font_name
+has the form
+.sp 1
+.in +2m
+.RI N\(la base_fontname \(ra\(la font_style \(ra
+.in -2m
+.sp 1
+.I base_fontname
+is the font name as it appears in the printers font listings without the
+first letter, up to (but not including) the font size.
+.I font_style
+can be one of the letters
+.BR R ,
+.BR I ,
+or
+.BR B ,
+indicating the font styles Roman, Italic and Bold respectively.
+.
+.IP
+For instance, if the printer's
+.I font listing A
+shows font \(oqNelite12I.ISO_USA\(cq, the corresponding entry in the
+font description file is
+.sp 1
+.in +2m
+.B lbpname NeliteI
+.in -2m
+.
+.IP
+Note that you may need to modify
+.B grolbp
+to add support for new bitmapped fonts, since the available font names
+and font sizes of bitmapped fonts (as documented above) are hard-coded
+into the program.
+.
+.IP \(bu
+For scalable fonts,
+.I printer_font_name
+is identical to the font name as it appears in the printer's
+.IR "font listing A" .
+.
+.IP
+For instance, to select the \(oqSwiss\(cq font in bold style, which
+appears in the printer's
+.I font listing A
+as \(oqSwiss-Bold\(cq, the required
+.B lbpname
+command line is
+.sp 1
+.in +2m
+.B lbpname Swiss-Bold
+.in -2m
+.sp 1
+.
+.PP
+The argument of
+.B lbpname
+is case sensitive.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devlbp/DESC
+Device description file.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devlbp/ F
+Font description file for font
+.IR F .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/lbp.tmac
+Macros for use with
+.BR grolbp .
+.
+.
+.\" ====================================================================
+.SH SEE ALSO
+.\" ====================================================================
+.
+.BR groff (1),
+.BR troff (1),
+.BR groff_out (5),
+.BR groff_font (5),
+.BR groff_char (7)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[grolbp_C]
+.
+.
+.\"
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grolj4.1 b/upstream/mageia-cauldron/man1/grolj4.1
new file mode 100644
index 00000000..90ddf5b1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grolj4.1
@@ -0,0 +1,232 @@
+.TH GROLJ4 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grolj4 \- groff driver for HP LaserJet 4 family
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1994-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grolj4
+.OP \-l
+.OP \-c num-copies
+.RB [ \-d
+.RI [ n ]]
+.OP \-F font-directory
+.OP \-p paper-size
+.OP \-w line-width
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY grolj4
+.B \-\-help
+.YS
+.
+.SY grolj4
+.B \-v
+.SY grolj4
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B grolj4
+is a driver for
+.B groff
+that produces output in PCL5 format suitable for an HP LaserJet 4
+printer.
+.
+.
+.LP
+There is an additional drawing command available:
+.
+.TP
+.BI \eD'R\  dh\ dv '
+Draw a rule (solid black rectangle), with one corner at the current
+position, and the diagonally opposite corner at the current position
+.RI +( dh , dv ).
+.
+Afterwards the current position will be at the opposite corner.
+.
+This generates a PCL fill rectangle command, and so will work on
+printers that do not support HPGL/2 unlike the other
+.B \eD
+commands.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.BI \-c " num-copies"
+Print
+.I num-copies
+copies of each page.
+.
+.
+.TP
+.B \-l
+Print the document with a landscape orientation.
+.
+.
+.TP
+.B \-d\c
+.RI " [" n ]
+Use duplex mode
+.IR n :
+1\ is long-side binding; 2\ is short-side binding;
+default is\ 1.
+.
+.
+.TP
+.BI \-p " paper-size"
+Set the paper size to
+.IR paper-size ,
+which must be one of
+letter, legal, executive, a4, com10, monarch, c5, b5, dl.
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Print the version number.
+.
+.
+.TP
+.BI \-w " line-width"
+Set the default line thickness to
+.I line-width
+thousandths of an em.
+.
+If this option isn't specified, the line thickness defaults to
+0.04\~em.
+.
+.
+.TP
+.BI \-F " font-directory"
+Prepend directory
+.IR font-directory /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device, usually
+.BR lj4 .
+.
+.
+.LP
+The following four commands are available additionally in the
+font description files:
+.
+.
+.TP
+.BI pclweight \ N
+The integer value
+.I N
+must be in the range \-7 to +7; default is\~0.
+.
+.
+.TP
+.BI pclstyle \ N
+The integer value
+.I N
+must be in the range 0 to 32767; default is\~0.
+.
+.
+.TP
+.BI pclproportional \ N
+A boolean flag which can be either 0 or\~1; default is\~0.
+.
+.
+.TP
+.BI pcltypeface \ N
+The integer value
+.I N
+must be in the range 0 to 65535; default is\~0.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devlj4/DESC
+Device description file.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devlj4/ F
+Font description file for font
+.IR F .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/lj4.tmac
+Macros for use with
+.BR grolj4 .
+.
+.
+.SH BUGS
+Small dots.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR lj4_font (5),
+.BR groff (1),
+.BR troff (1),
+.BR groff_out (5),
+.BR groff_font (5),
+.BR groff_char (7)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grops.1 b/upstream/mageia-cauldron/man1/grops.1
new file mode 100644
index 00000000..44caf40b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grops.1
@@ -0,0 +1,1509 @@
+.TH GROPS 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grops \- PostScript driver for groff
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr grops_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.de FT
+.  if '\\*(.T'ps' .ft \\$1
+.  if '\\*(.T'pdf' .ft \\$1
+..
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grops
+.OP \-glmv
+.OP \-b n
+.OP \-c n
+.OP \-F dir
+.OP \-I dir
+.OP \-p papersize
+.OP \-P prologue
+.OP \-w n
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B grops
+translates the output of GNU
+.B troff
+to PostScript.
+.
+Normally
+.B grops
+should be invoked by using the groff command with a
+.B \-Tps
+option.
+.
+.if 'ps'ps' (Actually, this is the default for groff.)
+.
+If no files are given,
+.B grops
+reads the standard input.
+.
+A filename of
+.B \-
+also causes
+.B grops
+to read the standard input.
+.
+PostScript output is written to the standard output.
+.
+When
+.B grops
+is run by
+.B groff
+options can be passed to
+.B grops
+using
+.BR groff 's
+.B \-P
+option.
+.
+.
+.LP
+Note that
+.B grops
+doesn't produce a valid document structure (conforming to the
+Document Structuring Convention) if called with multiple file
+arguments.
+.
+To print such concatenated output it is necessary to deactivate DSC
+handling in the printing program or previewer.
+.
+See section \[lq]Font Installation\[rq] below for a guide how to install
+fonts for
+.BR grops .
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.BI \-b n
+Provide workarounds for older printers, broken spoolers, and previewers.
+.
+Normally
+.B grops
+produces output at PostScript LanguageLevel\~2 that conforms to the
+Document Structuring Conventions version 3.0.
+.
+Some older printers, spoolers, and previewers can't handle such
+output.
+.
+The value of\~\c
+.I n
+controls what
+.B grops
+does to make its output acceptable to such programs.
+.
+A value of\~0 causes grops not to employ any workarounds.
+.
+.IP
+Add\~1 if no
+.B %%Begin\%Document\%Setup
+and
+.B %%End\%Document\%Setup
+comments should be generated;
+this is needed for early versions of TranScript that get confused by
+anything between the
+.B %%End\%Prolog
+comment and the first
+.B %%Page
+comment.
+.
+.IP
+Add\~2 if lines in included files beginning with
+.B %!\&
+should be stripped out; this is needed for Sun's pageview
+previewer.
+.
+.IP
+Add\~4 if
+.BR %%Page ,
+.B %%Trailer
+and
+.B %%End\%Prolog
+comments should be
+stripped out of included files; this is needed for spoolers that
+don't understand the
+.B %%Begin\%Document
+and
+.B %%End\%Document
+comments.
+.
+.IP
+Add\~8 if the first line of the PostScript output should be
+.B %!PS-Adobe-2.0
+rather than
+.BR %!PS-Adobe-3.0 ;
+this is needed when using Sun's Newsprint with a printer that
+requires page reversal.
+.
+.IP
+Add\~16 if no media size information should be included in the
+document (this is, neither use
+.B %%Document\%Media
+nor the
+.B setpagedevice
+PostScript command).
+.
+This was the behaviour of groff version 1.18.1 and earlier; it is
+needed for older printers which don't understand PostScript
+LanguageLevel\~2.
+.
+It is also necessary if the output is further processed to get an
+encapsulated PS (EPS) file \[en] see below.
+.
+.IP
+The default value can be specified by a
+.
+.RS
+.IP
+.BI broken\  n
+.
+.LP
+command in the
+.I DESC
+file.
+.
+Otherwise the default value is\~0.
+.RE
+.
+.TP
+.BI \-c n
+Print
+.I n
+copies of each page.
+.
+.TP
+.BI \-F dir
+Prepend directory
+.RI dir /dev name
+to the search path for prologue, font, and device description files;
+.I name
+is the name of the device, usually
+.BR ps .
+.
+.TP
+.B \-g
+Guess the page length.
+.
+This generates PostScript code that guesses the page length.
+.
+The guess is correct only if the imageable area is vertically
+centered on the page.
+.
+This option allows you to generate documents that can be printed
+both on letter (8.5\[mu]11) paper and on A4 paper without change.
+.
+.TP
+.BI \-I dir
+This option may be used to add a directory to the search path for
+files on the command line and files named in
+.B \[rs]X'ps: import'
+and
+.B \[rs]X'ps: file'
+escapes.
+.
+The search path is initialized with the current directory.
+.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+.
+If you want to make the current directory be read before other directories,
+add
+.B \-I.\&
+at the appropriate place.
+.
+.IP
+No directory search is performed for files with an absolute file name.
+.
+.TP
+.B \-l
+Print the document in landscape format.
+.
+.TP
+.B \-m
+Turn manual feed on for the document.
+.
+.TP
+.BI \-p paper-size
+Set physical dimension of output medium.
+.
+This overrides the
+.BR papersize ,
+.BR paperlength ,
+and
+.B paperwidth
+commands in the
+.I DESC
+file; it accepts the same arguments as the
+.B papersize
+command.
+.
+See
+.B groff_font (5)
+for details.
+.
+.TP
+.BI \-P prologue-file
+Use the file
+.I prologue-file
+(in the font path) as the prologue instead of the default prologue file
+.BR prologue .
+.
+This option overrides the environment variable
+.I GROPS_PROLOGUE.
+.
+.TP
+.BI \-w n
+Lines should be drawn using a thickness of
+.IR n \~\c
+thousandths of an em.
+.
+If this option is not given, the line thickness defaults to 0.04\~em.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+The input to
+.B grops
+must be in the format output by
+.BR troff (1).
+.
+This is described in
+.BR groff_out (5).
+.
+.LP
+In addition, the device and font description files for the device used
+must meet certain requirements:
+.
+The resolution must be an integer multiple of\~72 times the
+.BR sizescale .
+.
+The
+.B ps
+device uses a resolution of 72000 and a sizescale of 1000.
+.
+.
+.LP
+The device description file must contain a valid paper size; see
+.BR groff_font (5)
+for more information.
+.
+.
+.LP
+Each font description file must contain a command
+.IP
+.BI internalname\  psname
+.LP
+which says that the PostScript name of the font is
+.IR psname .
+.
+It may also contain a command
+.IP
+.BI encoding\  enc_file
+.LP
+which says that
+the PostScript font should be reencoded using the encoding described in
+.IR enc_file ;
+this file should consist of a sequence of lines of the form:
+.IP
+.I
+pschar code
+.LP
+where
+.I pschar
+is the PostScript name of the character,
+and
+.I code
+is its position in the encoding expressed as a decimal integer; valid
+values are in the range 0 to\~255.
+.
+Lines starting with
+.B #
+and blank lines are ignored.
+.
+The code for each character given in the font file must correspond
+to the code for the character in encoding file, or to the code in the default
+encoding for the font if the PostScript font is not to be reencoded.
+.
+This code can be used with the
+.B \[rs]N
+escape sequence in
+.B troff
+to select the character,
+even if the character does not have a groff name.
+.
+Every character in the font file must exist in the PostScript font, and
+the widths given in the font file must match the widths used
+in the PostScript font.
+.
+.B grops
+assumes that a character with a groff name of
+.B space
+is blank (makes no marks on the page);
+it can make use of such a character to generate more efficient and
+compact PostScript output.
+.
+.
+.LP
+Note that
+.B grops
+is able to display all glyphs in a PostScript font, not only 256.
+.I enc_file
+(or the default encoding if no encoding file specified) just defines the
+order of glyphs for the first 256 characters; all other glyphs are
+accessed with additional encoding vectors which
+.B grops
+produces on the fly.
+.
+.
+.LP
+.B grops
+can automatically include the downloadable fonts necessary
+to print the document.
+.
+Such fonts must be in PFA format.
+.
+Use
+.BR \%pfbtops (1)
+to convert a Type\~1 font in PFB format.
+.
+Any downloadable fonts which should, when required, be included by
+.B grops
+must be listed in the file
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devps/download ;
+this should consist of lines of the form
+.
+.IP
+.I
+font filename
+.
+.
+.LP
+where
+.I font
+is the PostScript name of the font,
+and
+.I filename
+is the name of the file containing the font;
+lines beginning with
+.B #
+and blank lines are ignored;
+fields may be separated by tabs or spaces;
+.I filename
+is searched for using the same mechanism that is used
+for groff font metric files.
+.
+The
+.I download
+file itself is also searched for using this mechanism;
+currently, only the first found file in the font path is used.
+.
+.
+.LP
+If the file containing a downloadable font or imported document
+conforms to the Adobe Document Structuring Conventions,
+then
+.B grops
+interprets any comments in the files sufficiently to ensure that its
+own output is conforming.
+.
+It also supplies any needed font resources that are listed in the
+.I download
+file
+as well as any needed file resources.
+.
+It is also able to handle inter-resource dependencies.
+.
+For example, suppose that you have a downloadable font called
+Garamond, and also a downloadable font called Garamond-Outline which
+depends on Garamond (typically it would be defined to copy
+Garamond's font dictionary, and change the PaintType), then it is
+necessary for Garamond to appear before Garamond-Outline in the
+PostScript document.
+.
+.B grops
+handles this automatically provided that the downloadable font file
+for Garamond-Outline indicates its dependence on Garamond by means of
+the Document Structuring Conventions, for example by beginning with
+the following lines
+.
+.IP
+.B
+%!PS-Adobe-3.0 Resource-Font
+.br
+.B
+%%DocumentNeededResources: font Garamond
+.br
+.B
+%%EndComments
+.br
+.B
+%%IncludeResource: font Garamond
+.
+.
+.LP
+In this case both Garamond and Garamond-Outline would need to be listed
+in the
+.I download
+file.
+.
+A downloadable font should not include its own name in a
+.B %%Document\%Supplied\%Resources
+comment.
+.
+.
+.LP
+.B grops
+does not interpret
+.B %%Document\%Fonts
+comments.
+.
+The
+.BR %%Document\%Needed\%Resources ,
+.BR %%Document\%Supplied\%Resources ,
+.BR %%Include\%Resource ,
+.BR %%Begin\%Resource ,
+and
+.B %%End\%Resource
+comments
+(or possibly the old
+.BR %%Document\%Needed\%Fonts ,
+.BR %%Document\%Supplied\%Fonts ,
+.BR %%Include\%Font ,
+.BR %%Begin\%Font ,
+and
+.B %%End\%Font
+comments)
+should be used.
+.
+.
+.LP
+In the default setup
+there are styles called
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+mounted at font positions 1 to\~4.
+.
+The fonts are grouped into families
+.BR A ,
+.BR BM ,
+.BR C ,
+.BR H ,
+.BR HN ,
+.BR N ,
+.BR P ,
+and\~\c
+.B T
+having members in each of these styles:
+.
+.RS
+.TP
+.B AR
+.FT AR
+AvantGarde-Book
+.FT
+.
+.TQ
+.B AI
+.FT AI
+AvantGarde-BookOblique
+.FT
+.
+.TQ
+.B AB
+.FT AB
+AvantGarde-Demi
+.FT
+.
+.TQ
+.B ABI
+.FT ABI
+AvantGarde-DemiOblique
+.FT
+.
+.TQ
+.B BMR
+.FT BMR
+Bookman-Light
+.FT
+.
+.TQ
+.B BMI
+.FT BMI
+Bookman-LightItalic
+.FT
+.
+.TQ
+.B BMB
+.FT BMB
+Bookman-Demi
+.FT
+.
+.TQ
+.B BMBI
+.FT BMBI
+Bookman-DemiItalic
+.FT
+.
+.TQ
+.B CR
+.FT CR
+Courier
+.FT
+.
+.TQ
+.B CI
+.FT CI
+Courier-Oblique
+.FT
+.
+.TQ
+.B CB
+.FT CB
+Courier-Bold
+.FT
+.
+.TQ
+.B CBI
+.FT CBI
+Courier-BoldOblique
+.FT
+.
+.TQ
+.B HR
+.FT HR
+Helvetica
+.FT
+.
+.TQ
+.B HI
+.FT HI
+Helvetica-Oblique
+.FT
+.
+.TQ
+.B HB
+.FT HB
+Helvetica-Bold
+.FT
+.
+.TQ
+.B HBI
+.FT HBI
+Helvetica-BoldOblique
+.FT
+.
+.TQ
+.B HNR
+.FT HNR
+Helvetica-Narrow
+.FT
+.
+.TQ
+.B HNI
+.FT HNI
+Helvetica-Narrow-Oblique
+.FT
+.
+.TQ
+.B HNB
+.FT HNB
+Helvetica-Narrow-Bold
+.FT
+.
+.TQ
+.B HNBI
+.FT HNBI
+Helvetica-Narrow-BoldOblique
+.FT
+.
+.TQ
+.B NR
+.FT NR
+NewCenturySchlbk-Roman
+.FT
+.
+.TQ
+.B NI
+.FT NI
+NewCenturySchlbk-Italic
+.FT
+.
+.TQ
+.B NB
+.FT NB
+NewCenturySchlbk-Bold
+.FT
+.
+.TQ
+.B NBI
+.FT NBI
+NewCenturySchlbk-BoldItalic
+.FT
+.
+.TQ
+.B PR
+.FT PR
+Palatino-Roman
+.FT
+.
+.TQ
+.B PI
+.FT PI
+Palatino-Italic
+.FT
+.
+.TQ
+.B PB
+.FT PB
+Palatino-Bold
+.FT
+.
+.TQ
+.B PBI
+.FT PBI
+Palatino-BoldItalic
+.FT
+.
+.TQ
+.B TR
+.FT TR
+Times-Roman
+.FT
+.
+.TQ
+.B TI
+.FT TI
+Times-Italic
+.FT
+.
+.TQ
+.B TB
+.FT TB
+Times-Bold
+.FT
+.
+.TQ
+.B TBI
+.FT TBI
+Times-BoldItalic
+.FT
+.RE
+.
+.
+.LP
+There is also the following font which is not a member of a family:
+.
+.RS
+.TP
+.B ZCMI
+.FT ZCMI
+ZapfChancery-MediumItalic
+.FT
+.RE
+.
+.
+.LP
+There are also some special fonts called
+.B S
+for the PS Symbol font, and
+.BR SS ,
+containing slanted lowercase Greek letters taken from PS Symbol.
+.
+Zapf Dingbats is available as
+.BR ZD ,
+and a reversed version of ZapfDingbats (with symbols pointing in the opposite
+direction) is available as
+.BR ZDR ;
+most characters in these fonts are unnamed and must be accessed using
+.BR \[rs]N .
+.
+.
+.LP
+The default color for
+.B \[rs]m
+and
+.B \[rs]M
+is black; for colors defined in the \[oq]rgb\[cq] color space
+.B setrgbcolor
+is used, for \[oq]cmy\[cq] and \[oq]cmyk\[cq]
+.BR setcmykcolor ,
+and for \[oq]gray\[cq]
+.BR setgray .
+.
+Note that
+.B setcmykcolor
+is a PostScript LanguageLevel\~2 command and thus not available on some
+older printers.
+.
+.
+.LP
+.B grops
+understands various X\~commands produced using the
+.B \[rs]X
+escape sequence;
+.B grops
+only interprets commands that begin with a
+.B ps:
+tag.
+.
+.TP
+.BI \[rs]X'ps:\ exec\  code '
+This executes the arbitrary PostScript commands in
+.IR code .
+.
+The PostScript currentpoint is set to the position of the
+.B \[rs]X
+command before executing
+.IR code .
+.
+The origin is at the top left corner of the page,
+and y\~coordinates increase down the page.
+.
+A procedure\~\c
+.B u
+is defined that converts groff units to the coordinate system in
+effect (provided the user doesn't change the scale).
+.
+For example,
+.
+.RS
+.IP
+.B
+\&.nr x 1i
+.br
+.B
+\[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
+.br
+.RE
+.
+.IP
+draws a horizontal line one inch long.
+.
+.I code
+may make changes to the graphics state,
+but any changes persist only to the end of the page.
+.
+A dictionary containing the definitions specified by the
+.B def
+and
+.B mdef
+is on top of the dictionary stack.
+.
+If your code adds definitions to this dictionary,
+you should allocate space for them using
+.BI \[rs]X'ps\ mdef \ n '\fR.
+.
+Any definitions persist only until the end of the page.
+.
+If you use the
+.B \[rs]Y
+escape sequence with an argument that names a macro,
+.I code
+can extend over multiple lines.
+.
+For example,
+.
+.RS
+.IP
+.nf
+.ft B
+\&.nr x 1i
+\&.de y
+\&ps: exec
+\&\[rs]nx u 0 rlineto
+\&stroke
+\&..
+\&\[rs]Yy
+.ft R
+.fi
+.
+.LP
+is another way to draw a horizontal line one inch long.
+.
+Note the single backslash before \[oq]nx\[cq] \[en] the only reason to
+use a number register while defining the macro \[oq]y\[cq] is to
+convert a user-specified dimension \[oq]1i\[cq] to internal groff
+units which are in turn converted to PS units with the
+.B u
+procedure.
+.
+.
+.LP
+.B grops
+wraps user-specified PostScript code into a dictionary, nothing more.
+.
+In particular, it doesn't start and end the inserted code with
+.B save
+and
+.BR restore ,
+respectively.
+.
+This must be supplied by the user, if necessary.
+.
+.RE
+.
+.TP
+.BI \[rs]X'ps:\ file\  name '
+This is the same as the
+.B exec
+command except that the PostScript code is read from file
+.IR name .
+.
+.TP
+.BI \[rs]X'ps:\ def\  code '
+Place a PostScript definition contained in
+.I code
+in the prologue.
+.
+There should be at most one definition per
+.B \[rs]X
+command.
+.
+Long definitions can be split over several
+.B \[rs]X
+commands;
+all the
+.I code
+arguments are simply joined together separated by newlines.
+.
+The definitions are placed in a dictionary which is automatically
+pushed on the dictionary stack when an
+.B exec
+command is executed.
+.
+If you use the
+.B \[rs]Y
+escape sequence with an argument that names a macro,
+.I code
+can extend over multiple lines.
+.
+.TP
+.BI \[rs]X'ps:\ mdef\  n\ code  '
+Like
+.BR def ,
+except that
+.I code
+may contain up to
+.IR n \~\c
+definitions.
+.
+.B grops
+needs to know how many definitions
+.I code
+contains
+so that it can create an appropriately sized PostScript dictionary
+to contain them.
+.
+.TP
+.BI \[rs]X'ps:\ import\  file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
+Import a PostScript graphic from
+.IR file .
+.
+The arguments
+.IR llx ,
+.IR lly ,
+.IR urx ,
+and
+.I ury
+give the bounding box of the graphic in the default PostScript
+coordinate system; they should all be integers;
+.I llx
+and
+.I lly
+are the x and y\~coordinates of the lower left
+corner of the graphic;
+.I urx
+and
+.I ury
+are the x and y\~coordinates of the upper right corner of the graphic;
+.I width
+and
+.I height
+are integers that give the desired width and height in groff
+units of the graphic.
+.
+.IP
+The graphic is scaled so that it has this width and height
+and translated so that the lower left corner of the graphic is
+located at the position associated with
+.B \[rs]X
+command.
+.
+If the height argument is omitted it is scaled uniformly in the
+x and y\~directions so that it has the specified width.
+.
+.IP
+Note that the contents of the
+.B \[rs]X
+command are not interpreted by
+.BR troff ;
+so vertical space for the graphic is not automatically added,
+and the
+.I width
+and
+.I height
+arguments are not allowed to have attached scaling indicators.
+.
+.IP
+If the PostScript file complies with the Adobe Document Structuring
+Conventions and contains a
+.B %%Bounding\%Box
+comment, then the bounding box can be automatically
+extracted from within groff by using the
+.B psbb
+request.
+.
+.IP
+See
+.BR groff_tmac (5)
+for a description of the
+.B PSPIC
+macro which provides a convenient high-level interface for inclusion of
+PostScript graphics.
+.
+.TP
+.B \[rs]X'ps:\ invis'
+.TQ
+.B \[rs]X'ps:\ endinvis'
+No output is generated for text and drawing commands
+that are bracketed with these
+.B \[rs]X
+commands.
+.
+These commands are intended for use when output from
+.B troff
+is previewed before being processed with
+.BR grops ;
+if the previewer is unable to display certain characters
+or other constructs, then other substitute characters or constructs
+can be used for previewing by bracketing them with these
+.B \[rs]X
+commands.
+.
+.
+.RS
+.LP
+For example,
+.B \%gxditview
+is not able to display a proper
+.B \[rs](em
+character because the standard X11 fonts do not provide it;
+this problem can be overcome by executing the following
+request
+.
+.IP
+.ft B
+.nf
+\&.char \[rs](em \[rs]X'ps: invis'\[rs]
+\[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
+\[rs]X'ps: endinvis'\[rs](em
+.ft
+.fi
+.
+.
+.LP
+In this case,
+.B \%gxditview
+is unable to display the
+.B \[rs](em
+character and draws the line,
+whereas
+.B grops
+prints the
+.B \[rs](em
+character
+and ignores the line (this code is already in file
+.B Xps.tmac
+which is loaded if a document intended for
+.B grops
+is previewed with
+.BR \%gxditview ).
+.RE
+.
+.
+.LP
+If a PostScript procedure
+.B BPhook
+has been defined via a
+.RB \[oq] ps:\ def \[cq]
+or
+.RB \[oq] ps:\ mdef \[cq]
+device command, it is executed at the beginning of every page (before
+anything is drawn or written by groff).
+.
+For example, to underlay the page contents with the word
+\[oq]DRAFT\[cq] in light gray, you might use
+.RS
+.LP
+.nf
+.ft B
+\&.de XX
+ps: def
+/BPhook
+{ gsave .9 setgray clippath pathbbox exch 2 copy
+  .5 mul exch .5 mul translate atan rotate pop pop
+  /NewCenturySchlbk-Roman findfont 200 scalefont setfont
+  (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
+  grestore }
+def
+\&..
+\&.devicem XX
+.ft R
+.fi
+.RE
+.LP
+Or, to cause lines and polygons to be drawn with square linecaps
+and mitered linejoins instead of the round linecaps and linejoins
+normally used by
+.BR grops ,
+use
+.RS
+.LP
+.nf
+.ft B
+\&.de XX
+ps: def
+/BPhook { 2 setlinecap 0 setlinejoin } def
+\&..
+\&.devicem XX
+.ft R
+.fi
+.RE
+.LP
+(square linecaps, as opposed to butt linecaps (0 setlinecap),
+give true corners in boxed tables even though the lines are
+drawn unconnected).
+.
+.
+.\" ====================================================================
+.SS Encapsulated PostScript
+.\" ====================================================================
+.
+.B grops
+itself doesn't emit bounding box information.
+.
+With the help of Ghostscript the following simple script,
+.BR groff2eps ,
+produces an encapsulated PS file.
+.
+.
+.RS
+.LP
+.nf
+.ft B
+#! /bin/sh
+groff \-P\-b16 $1 > $1.ps
+gs \-dNOPAUSE \-sDEVICE=bbox \-\- $1.ps 2> $1.bbox
+sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs]
+    \-e "/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/" $1.ps > $1.eps
+rm $1.ps $1.bbox
+.ft R
+.fi
+.RE
+.
+.
+.LP
+Just say
+.
+.IP
+.B
+groff2eps foo
+.
+.LP
+to convert file
+.B foo
+to
+.BR foo.eps .
+.
+.
+.\" ====================================================================
+.SS TrueType and other font formats
+.\" ====================================================================
+.
+TrueType fonts can be used with
+.B grops
+if converted first to
+.B "Type\~42"
+format, a special PostScript wrapper equivalent to the PFA format
+mentioned in
+.BR \%pfbtops (1).
+.
+There are several different methods to generate a type42 wrapper and
+most of them involve the use of a PostScript interpreter such as
+Ghostscript \[en] see
+.BR gs (1).
+.
+.
+.LP
+Yet, the easiest method involves the use of the application
+.BR ttftot42 (1).
+.
+This program uses
+.BR freetype (3)
+(version 1.3.1) to generate type42
+font wrappers and well-formed AFM files that can be fed to
+the
+.BR \%afmtodit (1)
+script to create appropriate metric files.
+.
+The resulting font wrappers should be added to the
+.I download
+file.
+.B ttftot42
+source code can be downloaded from
+.UR ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
+ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
+.UE .
+.
+.
+.LP
+Another solution for creating type42 wrappers is to use FontForge,
+available from
+.UR http://\:fontforge.sf.net
+http://\:fontforge.sf.net
+.UE .
+This font editor can convert most outline font formats.
+.
+.
+.\" ====================================================================
+.SH "FONT INSTALLATION"
+.\" ====================================================================
+.
+This section gives a summary of the above explanations; it can serve
+as a step-by-step font installation guide for
+.BR grops .
+.
+.ds BU \[bu]\ \ \"
+.de LI
+.IP "" 4
+\h'-\w'\*[BU]'u'\*[BU]\c
+..
+.LI
+Convert your font to something groff understands.
+.
+This is either a PostScript Type\~1 font in PFA format or a PostScript
+Type\~42 font, together with an AFM file.
+.
+.IP
+The very first characters in a PFA file look like this:
+.
+.RS
+.IP
+.B %!PS-AdobeFont-1.0:
+.RE
+.
+.IP
+A PFB file has this also in the first line, but the string is
+preceded with some binary bytes.
+.
+.IP
+The very first characters in a Type\~42 font file look like this:
+.
+.RS
+.IP
+.B %!PS-TrueTypeFont
+.RE
+.
+.IP
+This is a wrapper format for TrueType fonts.
+.
+Old PS printers might not support it (this is, they don't have a
+built-in TrueType font interpreter).
+.
+.IP
+If your font is in PFB format (such fonts normally have
+.I .pfb
+as the file extension), you might use groff's
+.BR \%pfbtops (1)
+program to convert it to PFA.
+.
+For TrueType fonts, try
+.B ttftot42
+or
+.BR fontforge .
+For all other font formats use
+.B fontforge
+which can convert most outline font formats.
+.
+.LI
+Convert the AFM file to a groff font description file with the
+.BR \%afmtodit (1)
+program.
+.
+An example call is
+.
+.RS
+.IP
+afmtodit Foo-Bar-Bold.afm textmap FBB
+.RE
+.
+.IP
+which converts the metric file
+.I Foo-Bar-Bold.afm
+to the groff
+font
+.IR FBB .
+.
+If you have a font family which comes with normal, bold, italic,
+and bold italic faces, it is recommended to use the letters
+.BR R ,
+.BR B ,
+.BR I ,
+and
+.BR BI ,
+respectively, as postfixes in the groff font names to make groff's
+\[oq].fam\[cq] request work.
+.
+An example is groff's built-in Times-Roman font: The font family
+name is
+.BR T ,
+and the groff font names are
+.BR TR ,
+.BR TB ,
+.BR TI ,
+and
+.BR TBI .
+.
+.LI
+Install both the groff font description files and the fonts in a
+.I devps
+subdirectory of the font path which groff finds.
+.
+See section \[lq]Environment\[rq] in
+.BR troff (1)
+for the actual value of the font path.
+.
+Note that groff doesn't use the AFM files (but it is a good idea
+to store them anyway).
+.
+.LI
+Register all fonts which must be downloaded to the printer in the
+.I devps/download
+file.
+.
+Only the first occurrence of this file in the font path is read.
+.
+This means that you should copy the default
+.I download
+file to the first directory in your font path and add your fonts there.
+.
+To continue the above example we assume that the PS font name for
+.I Foo-Bar-Bold.pfa
+is \[oq]XY-Foo-Bar-Bold\[cq] (the PS font name is stored in the
+.B internalname
+field in the
+.I FBB
+file),
+thus the following line should be added to
+.IR download .
+.
+.RS
+.IP
+.B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
+.
+.RE
+.
+.
+.\" ====================================================================
+.SH OLD FONTS
+.\" ====================================================================
+.
+groff versions 1.19.2 and earlier contain a slightly different set of
+the 35 Adobe core fonts; the difference is mainly the lack of the
+\[oq]Euro\[cq] glyph and a reduced set of kerning pairs.
+.
+For backwards compatibility, these old fonts are installed also in the
+.
+.IP
+.I /usr/\:share/\:groff/\:1.22.4/\:oldfont/devps
+.
+.LP
+directory.
+.
+.
+.LP
+To use them, make sure that
+.B grops
+finds the fonts before the default system fonts (with the same names):
+Either add command-line option
+.B \-F
+to
+.B grops
+.
+.IP
+.B groff \-Tps \-P\-F \-P/usr/\:share/\:groff/\:1.22.4/\:oldfont .\|.\|.
+.
+.LP
+or add the directory to groff's font path environment variable
+.
+.IP
+.B GROFF_FONT_PATH=/usr/\:share/\:groff/\:1.22.4/\:oldfont
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROPS_PROLOGUE
+If this is set to
+.IR foo ,
+then
+.B grops
+uses the file
+.I foo
+(in the font path) instead of the default prologue file
+.BR prologue .
+.
+The option
+.B \-P
+overrides this environment variable.
+.
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp (expressed as seconds since the Unix epoch) to use as the
+creation timestamp in place of the current time.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devps/DESC
+Device description file.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devps/ F
+Font description file for font
+.IR F .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devps/download
+List of downloadable fonts.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devps/text.enc
+Encoding used for text fonts.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/ps.tmac
+Macros for use with
+.BR grops ;
+automatically loaded by
+.B troffrc
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/pspic.tmac
+Definition of
+.B PSPIC
+macro,
+automatically loaded by
+.IR ps.tmac .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/psold.tmac
+Macros to disable use of characters not present in older
+PostScript printers (e.g., \[oq]eth\[cq] or \[oq]thorn\[cq]).
+.
+.TP
+.IR /tmp/grops XXXXXX
+Temporary file.
+See
+.BR groff (1)
+for details on the location of temporary files.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR \%afmtodit (1),
+.BR groff (1),
+.BR troff (1),
+.BR \%pfbtops (1),
+.BR \%groff_out (5),
+.BR \%groff_font (5),
+.BR \%groff_char (7),
+.BR \%groff_tmac (5)
+.
+.
+.LP
+.UR http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf
+PostScript Language Document Structuring Conventions Specification
+.UE
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[grops_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/grotty.1 b/upstream/mageia-cauldron/man1/grotty.1
new file mode 100644
index 00000000..a1755eb1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grotty.1
@@ -0,0 +1,542 @@
+.TH GROTTY 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+grotty \- groff driver for typewriter-like devices
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr grotty_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY grotty
+.OP \-bBcdfhioruUv
+.OP \-F dir
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B grotty
+translates the output of GNU
+.B troff
+into a form suitable for typewriter-like devices.
+.
+Normally
+.B grotty
+should be invoked by using the
+.B groff
+command with a
+.BR \-Tascii ,
+.B \-Tlatin1
+or
+.B \-Tutf8
+option on ASCII based systems, and with
+.B \-Tcp1047
+and
+.B \-Tutf8
+on EBCDIC based hosts.
+.
+If no files are given,
+.B grotty
+reads the standard input.
+.
+A filename of
+.B \-
+also causes
+.B grotty
+to read the standard input.
+.
+Output is written to the standard output.
+.
+.
+.LP
+By default,
+.B grotty
+emits SGR escape sequences (from ISO 6429, also called ANSI color
+escapes) to change text attributes (bold, italic, colors).
+.
+This makes it possible to have eight different background and
+foreground colors; additionally, bold and italic attributes can be
+used \f[BI]at the same time\f[] (by using the BI font).
+.
+.
+.LP
+The following colors are defined in
+.BR tty.tmac :
+black, white, red, green, blue, yellow, magenta, cyan.
+.
+Unknown colors are mapped to the default color (which is dependent on
+the settings of the terminal; in most cases, this is black for the
+foreground and white for the background).
+.
+.
+.LP
+Use the
+.B \-c
+switch to revert to the old behaviour, printing a bold character
+.I c
+with the sequence
+.RI \[lq] c
+BACKSPACE
+.IR c \[rq]
+and an italic character
+.I c
+by the sequence
+.RB \[lq] _
+BACKSPACE
+.IR c \[rq].
+.
+At the same time, color output is disabled.
+.
+The same effect can be achieved by setting either the
+.I GROFF_NO_SGR
+environment variable or using the \[oq]sgr\[cq] X command (see below).
+.
+.
+.LP
+For SGR support, it is necessary to use the
+.B \-R
+option of
+.BR less (1)
+to disable the interpretation of
+.BR grotty 's
+old output format.
+.
+Consequently, all programs which use
+.B less
+as the pager program have to pass this option to it.
+.
+For
+.BR man (1)
+in particular, either add
+.B \-R
+to the
+.I PAGER
+environment variable, e.g.\&
+.
+.RS
+.LP
+.B PAGER="/usr/bin/less \-R"
+.br
+.B export PAGER
+.RE
+.LP
+.
+or use the
+.B \-P
+option of
+.B man
+to set the pager executable and its options, or modify the
+configuration file of
+.B man
+in a similar fashion.
+.
+Note that with some
+.BR man (1)
+versions, you have to use the
+.I \%MANPAGER
+environment variable instead.
+.
+.
+.LP
+.BR grotty 's
+old output format can be displayed on a terminal
+by piping through
+.BR ul (1).
+Pagers such as
+.BR more (1)
+or
+.BR less (1)
+are also able to display these sequences.
+Use either
+.B \-B
+or
+.B \-U
+when piping into
+.BR less (1);
+use
+.B \-b
+when piping into
+.BR more (1).
+There is no need to filter the output through
+.BR col (1)
+since
+.B grotty
+never outputs reverse line feeds.
+.
+.
+.LP
+The font description file may contain a command
+.
+.IP
+.BI internalname\  n
+.LP
+.
+where
+.I n
+is a decimal integer.
+.
+If the 01 bit in
+.I n
+is set,
+then the font is treated as an italic font;
+if the 02 bit is set,
+then it is treated as a bold font.
+.
+The code field in the font description field gives the code which is
+used to output the character.
+.
+This code can also be used in the
+.B \[rs]N
+escape sequence in
+.BR troff .
+.
+.
+.LP
+If the
+.I DESC
+file contains the keyword
+.BR unicode ,
+.B grotty
+emits Unicode characters in UTF-8 encoding.
+.
+Otherwise, it emits characters in a single-byte encoding depending on
+the data in the font description files.
+.
+See the
+.BR groff_font (5)
+man page for more details.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-b
+Suppress the use of overstriking for bold characters.
+.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-B
+Use only overstriking for bold-italic characters.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-c
+Use
+.BR grotty 's
+old output format (see above).
+This also disables color output.
+.
+.TP
+.B \-d
+Ignore all
+.B \[rs]D
+commands.
+.
+Without this
+.B grotty
+renders
+.B \[rs]D'l\|.\|.\|.\&'
+commands that have at least one zero argument
+(and so are either horizontal or vertical)
+using
+.BR \- ,
+.BR | ,
+and
+.B +
+characters.
+.
+In a similar way,
+.B grotty
+handles
+.B \[rs]D'p\|.\|.\|.\&'
+commands which consist entirely of horizontal and vertical lines.
+.
+.
+.TP
+.B \-f
+Use form feeds in the output.
+.
+A form feed is output at the end of each page that has no output on
+its last line.
+.
+.TP
+.BI \-F dir
+Prepend directory
+.RI dir /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device, usually
+.BR ascii ,
+.BR latin1 ,
+.BR utf8 ,
+or
+.BR cp1047 .
+.
+.TP
+.B \-h
+Use horizontal tabs in the output.
+.
+Tabs are assumed to be set every 8 columns.
+.
+.TP
+.B \-i
+Use escape sequences to set the italic text attribute instead of the
+underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
+.
+Note that most terminals (including xterm) don't support this.
+.
+Ignored if
+.B \-c
+is active.
+.
+.TP
+.B \-o
+Suppress overstriking (other than for bold or underlined characters in
+case the old output format has been activated with
+.BR \-c ).
+.
+.TP
+.B \-r
+Use escape sequences to set the reverse text attribute instead of the
+underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
+.
+Ignored if
+.B \-c
+is active.
+.
+.TP
+.B \-u
+Suppress the use of underlining for italic characters.
+.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-U
+Use only underlining for bold-italic characters.
+.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+.B grotty
+understands a single X command produced using the
+.B \[rs]X
+escape sequence.
+.
+.TP
+.BI \[rs]X'tty:\ sgr\  n '
+.
+If
+.I n
+is non-zero or missing, enable SGR output (this is the default),
+otherwise use the old drawing scheme for bold and underline.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_NO_SGR
+If set, the old drawing scheme for bold and underline (using the
+backspace character) is active.
+.
+Colors are disabled.
+.
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to search for the
+.IR dev name
+directory in addition to the default ones.
+.
+See
+.BR troff (1)
+and
+.BR \%groff_font (5)
+for more details.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devascii/DESC
+Device description file for the
+.B ascii
+device.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devascii/ F
+Font description file for font
+.I F
+of the
+.B ascii
+device.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devlatin1/DESC
+Device description file for the
+.B latin1
+device.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devlatin1/ F
+Font description file for font
+.I F
+of the
+.B latin1
+device.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devutf8/DESC
+Device description file for the
+.B utf8
+device.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devutf8/ F
+Font description file for font
+.I F
+of the
+.B utf8
+device.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devcp1047/DESC
+Device description file for the
+.B cp1047
+device.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devcp1047/ F
+Font description file for font
+.I F
+of the
+.B cp1047
+device.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/tty.tmac
+Macros for use with
+.BR grotty .
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/tty\-char.tmac
+Additional character definitions for use with
+.BR grotty .
+.
+.LP
+Note that on EBCDIC hosts, only files for the
+.B cp1047
+device is installed.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+.B grotty
+is intended only for simple documents.
+.
+.
+.LP
+There is no support for fractional horizontal or vertical motions.
+.
+.
+.LP
+There is no support for
+.B \[rs]D
+commands other than horizontal and vertical lines.
+.
+.
+.LP
+Characters above the first line (i.e.\& with a vertical position
+of\~0) cannot be printed.
+.
+.
+.LP
+Color handling differs from
+.BR grops (1).
+.B \[rs]M
+doesn't set the fill color for closed graphic objects (which
+.B grotty
+doesn't support anyway) but changes the background color of the
+character cell, affecting all subsequent operations.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR groff (1),
+.BR troff (1),
+.BR groff_out (5),
+.BR groff_font (5),
+.BR groff_char (7),
+.BR ul (1),
+.BR more (1),
+.BR man (1),
+.BR less (1)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[grotty_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/groups.1 b/upstream/mageia-cauldron/man1/groups.1
new file mode 100644
index 00000000..2a5c73ba
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/groups.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH GROUPS "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+groups \- print the groups a user is in
+.SH SYNOPSIS
+.B groups
+[\fI\,OPTION\/\fR]... [\fI\,USERNAME\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print group memberships for each USERNAME or, if no USERNAME is specified, for
+the current process (which may differ if the groups database has changed).
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie and James Youngman.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBgetent\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/groups>
+.br
+or available locally via: info \(aq(coreutils) groups invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/grub2-editenv.1 b/upstream/mageia-cauldron/man1/grub2-editenv.1
new file mode 100644
index 00000000..a115f0f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-editenv.1
@@ -0,0 +1,62 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-EDITENV "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-editenv \- edit GRUB environment block
+.SH SYNOPSIS
+.B grub-editenv
+[\fI\,OPTION\/\fR...] \fI\,FILENAME COMMAND\/\fR
+.SH DESCRIPTION
+Tool to edit environment block.
+.IP
+Commands:
+.TP
+create
+Create a blank environment block file.
+.TP
+incr [NAME ...]
+Increase value of integer variables.
+.TP
+list
+List the current variables.
+.TP
+set [NAME=VALUE ...]
+Set variables.
+.TP
+unset [NAME ...]
+Delete variables.
+.IP
+Options:
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+If FILENAME is `\-', the default value \fI\,/boot/grub2/grubenv\/\fP is used.
+.PP
+There is no `delete' command; if you want to delete the whole environment
+block, use `rm /boot/grub2/grubenv'.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-reboot (8),
+.BR grub-set-default (8)
+.PP
+The full documentation for
+.B grub-editenv
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-editenv
+programs are properly installed at your site, the command
+.IP
+.B info grub-editenv
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-emu.1 b/upstream/mageia-cauldron/man1/grub2-emu.1
new file mode 100644
index 00000000..e0c4626d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-emu.1
@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-EMU "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-emu \- GRUB emulator
+.SH SYNOPSIS
+.B grub-emu
+[\fI\,OPTION\/\fR...]
+.SH DESCRIPTION
+GRUB emulator.
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+use GRUB files in the directory DIR
+[default=/boot/grub2]
+.TP
+\fB\-H\fR, \fB\-\-hold\fR[=\fI\,SECS\/\fR]
+wait until a debugger will attach
+.TP
+\fB\-\-memdisk\fR=\fI\,FILE\/\fR
+use FILE as memdisk
+.TP
+\fB\-m\fR, \fB\-\-device\-map\fR=\fI\,FILE\/\fR
+use FILE as the device map
+[default=/boot/grub2/device.map]
+.TP
+\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR
+Set root device.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-W\fR, \fB\-\-switch\-root\fR
+use switch\-root to only switch root filesystem
+without restarting the kernel.
+.TP
+\fB\-X\fR, \fB\-\-kexec\fR
+use kexec to boot Linux kernels via systemctl
+(pass twice to enable dangerous fallback to
+non\-systemctl).
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+If you are trying to install GRUB, then you should use
+.BR grub-install (8)
+rather than this program.
+.PP
+The full documentation for
+.B grub-emu
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-emu
+programs are properly installed at your site, the command
+.IP
+.B info grub-emu
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-file.1 b/upstream/mageia-cauldron/man1/grub2-file.1
new file mode 100644
index 00000000..6c00b6eb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-file.1
@@ -0,0 +1,118 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-FILE "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-file \- check file type
+.SH SYNOPSIS
+.B file
+\fI\,OPTIONS FILE\/\fR
+.SH DESCRIPTION
+Check if FILE is of specified type.
+.TP
+\fB\-\-is\-i386\-xen\-pae\-domu\fR
+Check if FILE can be booted as i386 PAE Xen unprivileged guest kernel
+.TP
+\fB\-\-is\-x86_64\-xen\-domu\fR
+Check if FILE can be booted as x86_64 Xen unprivileged guest kernel
+.TP
+\fB\-\-is\-x86\-xen\-dom0\fR
+Check if FILE can be used as Xen x86 privileged guest kernel
+.TP
+\fB\-\-is\-x86\-multiboot\fR
+Check if FILE can be used as x86 multiboot kernel
+.HP
+\fB\-\-is\-x86\-multiboot2\fR Check if FILE can be used as x86 multiboot2 kernel
+.TP
+\fB\-\-is\-arm\-linux\fR
+Check if FILE is ARM Linux
+.TP
+\fB\-\-is\-arm64\-linux\fR
+Check if FILE is ARM64 Linux
+.TP
+\fB\-\-is\-ia64\-linux\fR
+Check if FILE is IA64 Linux
+.TP
+\fB\-\-is\-mips\-linux\fR
+Check if FILE is MIPS Linux
+.TP
+\fB\-\-is\-mipsel\-linux\fR
+Check if FILE is MIPSEL Linux
+.TP
+\fB\-\-is\-sparc64\-linux\fR
+Check if FILE is SPARC64 Linux
+.TP
+\fB\-\-is\-powerpc\-linux\fR
+Check if FILE is POWERPC Linux
+.TP
+\fB\-\-is\-x86\-linux\fR
+Check if FILE is x86 Linux
+.TP
+\fB\-\-is\-x86\-linux32\fR
+Check if FILE is x86 Linux supporting 32\-bit protocol
+.TP
+\fB\-\-is\-x86\-kfreebsd\fR
+Check if FILE is x86 kFreeBSD
+.TP
+\fB\-\-is\-i386\-kfreebsd\fR
+Check if FILE is i386 kFreeBSD
+.TP
+\fB\-\-is\-x86_64\-kfreebsd\fR
+Check if FILE is x86_64 kFreeBSD
+.TP
+\fB\-\-is\-x86\-knetbsd\fR
+Check if FILE is x86 kNetBSD
+.TP
+\fB\-\-is\-i386\-knetbsd\fR
+Check if FILE is i386 kNetBSD
+.HP
+\fB\-\-is\-x86_64\-knetbsd\fR Check if FILE is x86_64 kNetBSD
+.TP
+\fB\-\-is\-i386\-efi\fR
+Check if FILE is i386 EFI file
+.TP
+\fB\-\-is\-x86_64\-efi\fR
+Check if FILE is x86_64 EFI file
+.TP
+\fB\-\-is\-ia64\-efi\fR
+Check if FILE is IA64 EFI file
+.TP
+\fB\-\-is\-arm64\-efi\fR
+Check if FILE is ARM64 EFI file
+.TP
+\fB\-\-is\-arm\-efi\fR
+Check if FILE is ARM EFI file
+.TP
+\fB\-\-is\-riscv32\-efi\fR
+Check if FILE is RISC\-V 32bit EFI file
+.TP
+\fB\-\-is\-riscv64\-efi\fR
+Check if FILE is RISC\-V 64bit EFI file
+.TP
+\fB\-\-is\-hibernated\-hiberfil\fR
+Check if FILE is hiberfil.sys in hibernated state
+.TP
+\fB\-\-is\-x86_64\-xnu\fR
+Check if FILE is x86_64 XNU (Mac OS X kernel)
+.TP
+\fB\-\-is\-i386\-xnu\fR
+Check if FILE is i386 XNU (Mac OS X kernel)
+.TP
+\fB\-\-is\-xnu\-hibr\fR
+Check if FILE is XNU (Mac OS X kernel) hibernated image
+.TP
+\fB\-\-is\-x86\-bios\-bootsector\fR
+Check if FILE is BIOS bootsector
+.PP
+\fB\-h\fR, \fB\-\-help\fR              Display this help and exit.
+\fB\-u\fR, \fB\-\-usage\fR             Display the usage of this command and exit.
+.SH "SEE ALSO"
+The full documentation for
+.B grub-file
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-file
+programs are properly installed at your site, the command
+.IP
+.B info grub-file
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-fstest.1 b/upstream/mageia-cauldron/man1/grub2-fstest.1
new file mode 100644
index 00000000..03d5fe2f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-fstest.1
@@ -0,0 +1,88 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-FSTEST "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-fstest \- debug tool for GRUB filesystem drivers
+.SH SYNOPSIS
+.B grub-fstest
+[\fI\,OPTION\/\fR...] \fI\,IMAGE_PATH COMMANDS\/\fR
+.SH DESCRIPTION
+Debug tool for filesystem driver.
+.IP
+Commands:
+.TP
+blocklist FILE
+Display blocklist of FILE.
+.TP
+cat FILE
+Copy FILE to standard output.
+.TP
+cmp FILE LOCAL
+Compare FILE with local file LOCAL.
+.TP
+cp FILE LOCAL
+Copy FILE to local file LOCAL.
+.TP
+crc FILE
+Get crc32 checksum of FILE.
+.TP
+hex FILE
+Show contents of FILE in hex.
+.TP
+ls PATH
+List files in PATH.
+.TP
+xnu_uuid DEVICE
+Compute XNU UUID of the device.
+.TP
+\fB\-c\fR, \fB\-\-diskcount\fR=\fI\,NUM\/\fR
+Specify the number of input files.
+.TP
+\fB\-C\fR, \fB\-\-crypto\fR
+Mount crypto devices.
+.TP
+\fB\-d\fR, \fB\-\-debug\fR=\fI\,STRING\/\fR
+Set debug environment variable.
+.TP
+\fB\-K\fR, \fB\-\-zfs\-key\fR=\fI\,FILE\/\fR|prompt
+Load zfs crypto key.
+.TP
+\fB\-n\fR, \fB\-\-length\fR=\fI\,NUM\/\fR
+Handle N bytes in output file.
+.TP
+\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR
+Set root device.
+.TP
+\fB\-s\fR, \fB\-\-skip\fR=\fI\,NUM\/\fR
+Skip N bytes from output file.
+.TP
+\fB\-u\fR, \fB\-\-uncompress\fR
+Uncompress data.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "SEE ALSO"
+.BR grub-probe (8)
+.PP
+The full documentation for
+.B grub-fstest
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-fstest
+programs are properly installed at your site, the command
+.IP
+.B info grub-fstest
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-glue-efi.1 b/upstream/mageia-cauldron/man1/grub2-glue-efi.1
new file mode 100644
index 00000000..f2b20afb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-glue-efi.1
@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-GLUE-EFI "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-glue-efi \- generate a fat binary for EFI
+.SH SYNOPSIS
+.B grub-glue-efi
+[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR]
+.SH DESCRIPTION
+grub-glue-efi processes ia32 and amd64 EFI images and glues them according to Apple format.
+.PP
+Glue 32\-bit and 64\-bit binary into Apple universal one.
+.TP
+\fB\-3\fR, \fB\-\-input32\fR=\fI\,FILE\/\fR
+set input filename for 32\-bit part.
+.TP
+\fB\-6\fR, \fB\-\-input64\fR=\fI\,FILE\/\fR
+set input filename for 64\-bit part.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+set output filename. Default is STDOUT
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+The full documentation for
+.B grub-glue-efi
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-glue-efi
+programs are properly installed at your site, the command
+.IP
+.B info grub-glue-efi
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-kbdcomp.1 b/upstream/mageia-cauldron/man1/grub2-kbdcomp.1
new file mode 100644
index 00000000..a8e057c5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-kbdcomp.1
@@ -0,0 +1,42 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-KBDCOMP "1" "September 2023" "grub-kbdcomp ()" "User Commands"
+.SH NAME
+grub-kbdcomp \- generate a GRUB keyboard layout file
+.SH SYNOPSIS
+.B grub-kbdcomp
+\fI\,-o OUTPUT CKBMAP_ARGUMENTS\/\fR...
+.SH DESCRIPTION
+grub-kbdcomp processes a X keyboard layout description in
+.BR keymaps (5)
+format into a format that can be used by GRUB's
+.B keymap
+command.
+.PP
+Make GRUB keyboard layout file.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this message and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version information and exit
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE [required]
+.PP
+grub\-kbdcomp generates a keyboard layout for GRUB using ckbcomp
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mklayout (8)
+.PP
+The full documentation for
+.B grub-kbdcomp
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-kbdcomp
+programs are properly installed at your site, the command
+.IP
+.B info grub-kbdcomp
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-menulst2cfg.1 b/upstream/mageia-cauldron/man1/grub2-menulst2cfg.1
new file mode 100644
index 00000000..25bf13fb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-menulst2cfg.1
@@ -0,0 +1,23 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MENULST2CFG "1" "September 2023" "Usage: grub-menulst2cfg [INFILE [OUTFILE]]" "User Commands"
+.SH NAME
+grub-menulst2cfg \- transform legacy menu.lst into grub.cfg
+.SH SYNOPSIS
+.B grub-menulst2cfg
+[\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+
+.SH "SEE ALSO"
+.BR grub-mkconfig (8)
+.PP
+The full documentation for
+.B grub-menulst2cfg
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-menulst2cfg
+programs are properly installed at your site, the command
+.IP
+.B info grub-menulst2cfg
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkfont.1 b/upstream/mageia-cauldron/man1/grub2-mkfont.1
new file mode 100644
index 00000000..9658c930
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkfont.1
@@ -0,0 +1,73 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKFONT "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkfont \- make GRUB font files
+.SH SYNOPSIS
+.B grub-mkfont
+[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR] \fI\,FONT_FILES\/\fR
+.SH DESCRIPTION
+Convert common font file formats into PF2
+.TP
+\fB\-a\fR, \fB\-\-force\-autohint\fR
+force autohint
+.TP
+\fB\-b\fR, \fB\-\-bold\fR
+convert to bold font
+.TP
+\fB\-c\fR, \fB\-\-asce\fR=\fI\,NUM\/\fR
+set font ascent
+.TP
+\fB\-d\fR, \fB\-\-desc\fR=\fI\,NUM\/\fR
+set font descent
+.TP
+\fB\-i\fR, \fB\-\-index\fR=\fI\,NUM\/\fR
+select face index
+.TP
+\fB\-\-no\-bitmap\fR
+ignore bitmap strikes when loading
+.TP
+\fB\-\-no\-hinting\fR
+disable hinting
+.TP
+\fB\-n\fR, \fB\-\-name\fR=\fI\,NAME\/\fR
+set font family name
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE [required]
+.TP
+\fB\-r\fR, \fB\-\-range\fR=\fI\,FROM\-TO[\/\fR,FROM\-TO]
+set font range
+.TP
+\fB\-s\fR, \fB\-\-size\fR=\fI\,SIZE\/\fR
+set font size
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkconfig (8)
+.PP
+The full documentation for
+.B grub-mkfont
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkfont
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkfont
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkimage.1 b/upstream/mageia-cauldron/man1/grub2-mkimage.1
new file mode 100644
index 00000000..e4d938c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkimage.1
@@ -0,0 +1,106 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKIMAGE "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkimage \- make a bootable image of GRUB
+.SH SYNOPSIS
+.B grub-mkimage
+[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR]... [\fI\,MODULES\/\fR]
+.SH DESCRIPTION
+Make a bootable image of GRUB.
+.TP
+\fB\-c\fR, \fB\-\-config\fR=\fI\,FILE\/\fR
+embed FILE as an early config
+.TP
+\fB\-C\fR, \fB\-\-compression=\fR(xz|none|auto)
+choose the compression to use for core image
+.TP
+\fB\-\-disable\-shim\-lock\fR
+disable shim_lock verifier
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+use images and modules under DIR
+[default=/usr/lib/grub/<platform>]
+.TP
+\fB\-D\fR, \fB\-\-dtb\fR=\fI\,FILE\/\fR
+embed FILE as a device tree (DTB)
+.TP
+\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR
+embed FILE as public key for PGP signature
+checking
+.TP
+\fB\-m\fR,                              \fB\-\-memdisk\fR=\fI\,FILE\/\fR
+embed FILE as a memdisk image
+.PP
+Implies `\-p (memdisk)/boot/grub' and overrides
+.TP
+any prefix supplied previously, but the prefix
+itself can be overridden by later options
+.TP
+\fB\-n\fR, \fB\-\-note\fR
+add NOTE segment for CHRP IEEE1275
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+output a generated image to FILE [default=stdout]
+.TP
+\fB\-O\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR
+generate an image in FORMAT
+available formats: i386\-coreboot, i386\-multiboot,
+i386\-pc, i386\-xen_pvh, i386\-pc\-pxe,
+i386\-pc\-eltorito, i386\-efi, i386\-ieee1275,
+i386\-qemu, x86_64\-efi, i386\-xen, x86_64\-xen,
+mipsel\-yeeloong\-flash, mipsel\-fuloong2f\-flash,
+mipsel\-loongson\-elf, powerpc\-ieee1275,
+sparc64\-ieee1275\-raw, sparc64\-ieee1275\-cdcore,
+sparc64\-ieee1275\-aout, ia64\-efi, mips\-arc,
+mipsel\-arc, mipsel\-qemu_mips\-elf,
+mips\-qemu_mips\-flash, mipsel\-qemu_mips\-flash,
+mips\-qemu_mips\-elf, arm\-uboot,
+arm\-coreboot\-vexpress, arm\-coreboot\-veyron,
+arm\-efi, arm64\-efi, riscv32\-efi, riscv64\-efi
+.TP
+\fB\-p\fR, \fB\-\-prefix\fR=\fI\,DIR\/\fR
+set prefix directory
+.TP
+\fB\-s\fR, \fB\-\-sbat\fR=\fI\,FILE\/\fR
+SBAT metadata
+.TP
+\fB\-S\fR, \fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR
+Add a note segment reserving SIZE bytes for an
+appended signature
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-x\fR, \fB\-\-x509\fR=\fI\,FILE\/\fR
+embed FILE as an x509 certificate for appended
+signature checking
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-install (8),
+.BR grub-mkrescue (1),
+.BR grub-mknetdir (8)
+.PP
+The full documentation for
+.B grub-mkimage
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkimage
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkimage
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mklayout.1 b/upstream/mageia-cauldron/man1/grub2-mklayout.1
new file mode 100644
index 00000000..11eda88c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mklayout.1
@@ -0,0 +1,52 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKLAYOUT "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mklayout \- generate a GRUB keyboard layout file
+.SH SYNOPSIS
+.B grub-mklayout
+[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR]
+.SH DESCRIPTION
+grub-mklayout processes a keyboard layout description in
+.BR keymaps (5)
+format into a format that can be used by GRUB's
+.B keymap
+command.
+.PP
+Generate GRUB keyboard layout from Linux console one.
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,FILE\/\fR
+set input filename. Default is STDIN
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+set output filename. Default is STDOUT
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkconfig (8)
+.PP
+The full documentation for
+.B grub-mklayout
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mklayout
+programs are properly installed at your site, the command
+.IP
+.B info grub-mklayout
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mknetdir.1 b/upstream/mageia-cauldron/man1/grub2-mknetdir.1
new file mode 100644
index 00000000..786558ad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mknetdir.1
@@ -0,0 +1,100 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKNETDIR "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mknetdir \- prepare a GRUB netboot directory.
+.SH SYNOPSIS
+.B grub-mknetdir
+[\fI\,OPTION\/\fR...]
+.SH DESCRIPTION
+Prepares
+GRUB network boot images at net_directory/subdir assuming net_directory being
+TFTP root.
+.TP
+\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR
+Add a note segment reserving SIZE bytes for an
+appended signature
+.TP
+\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo
+compress GRUB files [optional]
+.TP
+\fB\-\-disable\-shim\-lock\fR
+disable shim_lock verifier
+.TP
+\fB\-\-dtb\fR=\fI\,FILE\/\fR
+embed a specific DTB
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+use images and modules under DIR
+[default=/usr/lib/grub/<platform>]
+.TP
+\fB\-\-fonts\fR=\fI\,FONTS\/\fR
+install FONTS [default=unicode]
+.TP
+\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR
+install only MODULES and their dependencies
+[default=all]
+.TP
+\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR
+embed FILE as public key for signature checking
+.TP
+\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR
+[default=/usr/share/locale]
+.TP
+\fB\-\-locales\fR=\fI\,LOCALES\/\fR
+install only LOCALES [default=all]
+.TP
+\fB\-\-modules\fR=\fI\,MODULES\/\fR
+pre\-load specified modules MODULES
+.TP
+\fB\-\-sbat\fR=\fI\,FILE\/\fR
+SBAT metadata
+.TP
+\fB\-\-themes\fR=\fI\,THEMES\/\fR
+install THEMES [default=starfield]
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR
+embed FILE as an x509 certificate for signature
+checking
+.TP
+\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto
+choose the compression to use for core image
+.TP
+\fB\-\-net\-directory\fR=\fI\,DIR\/\fR
+root directory of TFTP server
+.TP
+\fB\-\-subdir\fR=\fI\,DIR\/\fR
+relative subdirectory on network server
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.PP
+Prepares GRUB network boot images at net_directory/subdir assuming
+net_directory being TFTP root.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkimage (1)
+.PP
+The full documentation for
+.B grub-mknetdir
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mknetdir
+programs are properly installed at your site, the command
+.IP
+.B info grub-mknetdir
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkpasswd-pbkdf2.1 b/upstream/mageia-cauldron/man1/grub2-mkpasswd-pbkdf2.1
new file mode 100644
index 00000000..a9b39901
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkpasswd-pbkdf2.1
@@ -0,0 +1,46 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKPASSWD-PBKDF2 "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkpasswd-pbkdf2 \- generate hashed password for GRUB
+.SH SYNOPSIS
+.B grub-mkpasswd-pbkdf2
+[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR]
+.SH DESCRIPTION
+Generate PBKDF2 password hash.
+.TP
+\fB\-c\fR, \fB\-\-iteration\-count\fR=\fI\,NUM\/\fR
+Number of PBKDF2 iterations
+.TP
+\fB\-l\fR, \fB\-\-buflen\fR=\fI\,NUM\/\fR
+Length of generated hash
+.TP
+\fB\-s\fR, \fB\-\-salt\fR=\fI\,NUM\/\fR
+Length of salt
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkconfig (8)
+.PP
+The full documentation for
+.B grub-mkpasswd-pbkdf2
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkpasswd-pbkdf2
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkpasswd-pbkdf2
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkrelpath.1 b/upstream/mageia-cauldron/man1/grub2-mkrelpath.1
new file mode 100644
index 00000000..7f525807
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkrelpath.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKRELPATH "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkrelpath \- make a system path relative to its root
+.SH SYNOPSIS
+.B grub-mkrelpath
+[\fI\,OPTION\/\fR...] \fI\,PATH\/\fR
+.SH DESCRIPTION
+Transform a system filename into GRUB one.
+.TP
+\fB\-r\fR, \fB\-\-relative\fR
+use relative path on btrfs
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-probe (8)
+.PP
+The full documentation for
+.B grub-mkrelpath
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkrelpath
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkrelpath
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkrescue.1 b/upstream/mageia-cauldron/man1/grub2-mkrescue.1
new file mode 100644
index 00000000..19113b1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkrescue.1
@@ -0,0 +1,131 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKRESCUE "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkrescue \- make a GRUB rescue image
+.SH SYNOPSIS
+.B grub-mkrescue
+[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR] \fI\,SOURCE\/\fR...
+.SH DESCRIPTION
+Make GRUB CD\-ROM, disk, pendrive and floppy bootable image.
+.TP
+\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR
+Add a note segment reserving SIZE bytes for an
+appended signature
+.TP
+\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo
+compress GRUB files [optional]
+.TP
+\fB\-\-disable\-shim\-lock\fR
+disable shim_lock verifier
+.TP
+\fB\-\-dtb\fR=\fI\,FILE\/\fR
+embed a specific DTB
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+use images and modules under DIR
+[default=/usr/lib/grub/<platform>]
+.TP
+\fB\-\-fonts\fR=\fI\,FONTS\/\fR
+install FONTS [default=unicode]
+.TP
+\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR
+install only MODULES and their dependencies
+[default=all]
+.TP
+\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR
+embed FILE as public key for signature checking
+.TP
+\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR
+[default=/usr/share/locale]
+.TP
+\fB\-\-locales\fR=\fI\,LOCALES\/\fR
+install only LOCALES [default=all]
+.TP
+\fB\-\-modules\fR=\fI\,MODULES\/\fR
+pre\-load specified modules MODULES
+.TP
+\fB\-\-sbat\fR=\fI\,FILE\/\fR
+SBAT metadata
+.TP
+\fB\-\-themes\fR=\fI\,THEMES\/\fR
+install THEMES [default=starfield]
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR
+embed FILE as an x509 certificate for signature
+checking
+.TP
+\fB\-\-arcs\-boot\fR
+enable ARCS (big\-endian mips machines, mostly
+SGI) boot. Disables HFS+, APM, sparc64 and boot
+as disk image for i386\-pc
+.TP
+\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto
+choose the compression to use for core image
+.TP
+\fB\-\-label\-bgcolor\fR=\fI\,COLOR\/\fR
+use COLOR for label background
+.TP
+\fB\-\-label\-color\fR=\fI\,COLOR\/\fR
+use COLOR for label
+.TP
+\fB\-\-label\-font\fR=\fI\,FILE\/\fR
+use FILE as font for label
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE [required]
+.TP
+\fB\-\-product\-name\fR=\fI\,STRING\/\fR
+use STRING as product name
+.TP
+\fB\-\-product\-version\fR=\fI\,STRING\/\fR
+use STRING as product version
+.TP
+\fB\-\-rom\-directory\fR=\fI\,DIR\/\fR
+save ROM images in DIR [optional]
+.TP
+\fB\-\-sparc\-boot\fR
+enable sparc boot. Disables HFS+, APM, ARCS and
+boot as disk image for i386\-pc
+.TP
+\fB\-\-xorriso\fR=\fI\,FILE\/\fR
+use FILE as xorriso [optional]
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.PP
+Generates a bootable CD/USB/floppy image.  Arguments other than options to
+this program are passed to xorriso, and indicate source files, source
+directories, or any of the mkisofs options listed by the output of `xorriso
+\fB\-as\fR mkisofs \fB\-help\fR'.
+.PP
+Option \fB\-\-\fR switches to native xorriso command mode.
+.PP
+Mail xorriso support requests to <bug\-xorriso@gnu.org>.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkimage (1)
+.PP
+The full documentation for
+.B grub-mkrescue
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkrescue
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkrescue
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mkstandalone.1 b/upstream/mageia-cauldron/man1/grub2-mkstandalone.1
new file mode 100644
index 00000000..7f4cfaa1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mkstandalone.1
@@ -0,0 +1,110 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MKSTANDALONE "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mkstandalone \- make a memdisk-based GRUB image
+.SH SYNOPSIS
+.B grub-mkstandalone
+[\fI\,OPTION\/\fR...] [\fI\,OPTION\/\fR] \fI\,SOURCE\/\fR...
+.SH DESCRIPTION
+Generate a standalone image (containing all modules) in the selected format
+.TP
+\fB\-\-appended\-signature\-size\fR=\fI\,SIZE\/\fR
+Add a note segment reserving SIZE bytes for an
+appended signature
+.TP
+\fB\-\-compress\fR=\fI\,no\/\fR|xz|gz|lzo
+compress GRUB files [optional]
+.TP
+\fB\-\-disable\-shim\-lock\fR
+disable shim_lock verifier
+.TP
+\fB\-\-dtb\fR=\fI\,FILE\/\fR
+embed a specific DTB
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+use images and modules under DIR
+[default=/usr/lib/grub/<platform>]
+.TP
+\fB\-\-fonts\fR=\fI\,FONTS\/\fR
+install FONTS [default=unicode]
+.TP
+\fB\-\-install\-modules\fR=\fI\,MODULES\/\fR
+install only MODULES and their dependencies
+[default=all]
+.TP
+\fB\-k\fR, \fB\-\-pubkey\fR=\fI\,FILE\/\fR
+embed FILE as public key for signature checking
+.TP
+\fB\-\-locale\-directory\fR=\fI\,DIR\/\fR use translations under DIR
+[default=/usr/share/locale]
+.TP
+\fB\-\-locales\fR=\fI\,LOCALES\/\fR
+install only LOCALES [default=all]
+.TP
+\fB\-\-modules\fR=\fI\,MODULES\/\fR
+pre\-load specified modules MODULES
+.TP
+\fB\-\-sbat\fR=\fI\,FILE\/\fR
+SBAT metadata
+.TP
+\fB\-\-themes\fR=\fI\,THEMES\/\fR
+install THEMES [default=starfield]
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\fB\-x\fR, \fB\-\-x509key\fR=\fI\,FILE\/\fR
+embed FILE as an x509 certificate for signature
+checking
+.TP
+\fB\-\-core\-compress\fR=\fI\,xz\/\fR|none|auto
+choose the compression to use for core image
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+save output in FILE [required]
+.TP
+\fB\-O\fR, \fB\-\-format\fR=\fI\,FILE\/\fR
+generate an image in FORMAT
+available formats: i386\-coreboot, i386\-multiboot,
+i386\-pc, i386\-xen_pvh, i386\-pc\-pxe,
+i386\-pc\-eltorito, i386\-efi, i386\-ieee1275,
+i386\-qemu, x86_64\-efi, i386\-xen, x86_64\-xen,
+mipsel\-yeeloong\-flash, mipsel\-fuloong2f\-flash,
+mipsel\-loongson\-elf, powerpc\-ieee1275,
+sparc64\-ieee1275\-raw, sparc64\-ieee1275\-cdcore,
+sparc64\-ieee1275\-aout, ia64\-efi, mips\-arc,
+mipsel\-arc, mipsel\-qemu_mips\-elf,
+mips\-qemu_mips\-flash, mipsel\-qemu_mips\-flash,
+mips\-qemu_mips\-elf, arm\-uboot,
+arm\-coreboot\-vexpress, arm\-coreboot\-veyron,
+arm\-efi, arm64\-efi, riscv32\-efi, riscv64\-efi
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.PP
+Graft point syntax (E.g. \fI\,/boot/grub/grub\/\fP.cfg=./grub.cfg) is accepted
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkimage (1)
+.PP
+The full documentation for
+.B grub-mkstandalone
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mkstandalone
+programs are properly installed at your site, the command
+.IP
+.B info grub-mkstandalone
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-mount.1 b/upstream/mageia-cauldron/man1/grub2-mount.1
new file mode 100644
index 00000000..eafbe264
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-mount.1
@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-MOUNT "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-mount \- export GRUB filesystem with FUSE
+.SH SYNOPSIS
+.B grub-mount
+[\fI\,OPTION\/\fR...] \fI\,IMAGE1 \/\fR[\fI\,IMAGE2 \/\fR...] \fI\,MOUNTPOINT\/\fR
+.SH DESCRIPTION
+Debug tool for filesystem driver.
+.TP
+\fB\-C\fR, \fB\-\-crypto\fR
+Mount crypto devices.
+.TP
+\fB\-d\fR, \fB\-\-debug\fR=\fI\,STRING\/\fR
+Set debug environment variable.
+.TP
+\fB\-K\fR, \fB\-\-zfs\-key\fR=\fI\,FILE\/\fR|prompt
+Load zfs crypto key.
+.TP
+\fB\-r\fR, \fB\-\-root\fR=\fI\,DEVICE_NAME\/\fR
+Set root device.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "SEE ALSO"
+The full documentation for
+.B grub-mount
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-mount
+programs are properly installed at your site, the command
+.IP
+.B info grub-mount
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-render-label.1 b/upstream/mageia-cauldron/man1/grub2-render-label.1
new file mode 100644
index 00000000..0f2107ab
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-render-label.1
@@ -0,0 +1,56 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-RENDER-LABEL "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-render-label \- generate a .disk_label for Apple Macs.
+.SH SYNOPSIS
+.B grub-render-label
+[\fI\,OPTION\/\fR...] [\fI\,OPTIONS\/\fR]
+.SH DESCRIPTION
+Render Apple .disk_label.
+.TP
+\fB\-b\fR, \fB\-\-bgcolor\fR=\fI\,COLOR\/\fR
+use COLOR for background
+.TP
+\fB\-c\fR, \fB\-\-color\fR=\fI\,COLOR\/\fR
+use COLOR for text
+.TP
+\fB\-f\fR, \fB\-\-font\fR=\fI\,FILE\/\fR
+use FILE as font (PF2).
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,FILE\/\fR
+read text from FILE.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+set output filename. Default is STDOUT
+.TP
+\fB\-t\fR, \fB\-\-text\fR=\fI\,STRING\/\fR
+set the label to render
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+The full documentation for
+.B grub-render-label
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-render-label
+programs are properly installed at your site, the command
+.IP
+.B info grub-render-label
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-script-check.1 b/upstream/mageia-cauldron/man1/grub2-script-check.1
new file mode 100644
index 00000000..fac9eadc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-script-check.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-SCRIPT-CHECK "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-script-check \- check grub.cfg for syntax errors
+.SH SYNOPSIS
+.B grub-script-check
+[\fI\,OPTION\/\fR...] [\fI\,PATH\/\fR]
+.SH DESCRIPTION
+Checks GRUB script configuration file for syntax errors.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-mkconfig (8)
+.PP
+The full documentation for
+.B grub-script-check
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-script-check
+programs are properly installed at your site, the command
+.IP
+.B info grub-script-check
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-set-bootflag.1 b/upstream/mageia-cauldron/man1/grub2-set-bootflag.1
new file mode 100644
index 00000000..6f25cdaf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-set-bootflag.1
@@ -0,0 +1,23 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-SET-BOOTFLAG "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-set-bootflag \- set a bootflag in the GRUB environment block
+.SH SYNOPSIS
+.B 'grub-set-bootflag
+\fI\,<bootflag>', where <bootflag> is one of:\/\fR
+.SH DESCRIPTION
+.IP
+boot_success
+menu_show_once
+.SH "SEE ALSO"
+The full documentation for
+.B grub-set-bootflag
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-set-bootflag
+programs are properly installed at your site, the command
+.IP
+.B info grub-set-bootflag
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/grub2-syslinux2cfg.1 b/upstream/mageia-cauldron/man1/grub2-syslinux2cfg.1
new file mode 100644
index 00000000..33b2e826
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/grub2-syslinux2cfg.1
@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH GRUB-SYSLINUX2CFG "1" "September 2023" "GRUB 2.06" "User Commands"
+.SH NAME
+grub-syslinux2cfg \- transform syslinux config into grub.cfg
+.SH SYNOPSIS
+.B grub-syslinux2cfg
+[\fI\,OPTION\/\fR...] \fI\,FILE\/\fR
+.SH DESCRIPTION
+Transform syslinux config into GRUB one.
+.TP
+\fB\-c\fR, \fB\-\-cwd\fR=\fI\,DIR\/\fR
+current directory of syslinux [default is parent
+directory of input file].
+.TP
+\fB\-i\fR, \fB\-\-isolinux\fR
+assume input is an isolinux configuration file.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to FILE [default=stdout].
+.TP
+\fB\-p\fR, \fB\-\-pxelinux\fR
+assume input is a pxelinux configuration file.
+.TP
+\fB\-r\fR, \fB\-\-root\fR=\fI\,DIR\/\fR
+root directory of the syslinux disk [default=/].
+.TP
+\fB\-s\fR, \fB\-\-syslinux\fR
+assume input is a syslinux configuration file.
+.TP
+\fB\-t\fR, \fB\-\-target\-root\fR=\fI\,DIR\/\fR
+root directory as it will be seen on runtime
+[default=/].
+.TP
+\fB\-T\fR, \fB\-\-target\-cwd\fR=\fI\,DIR\/\fR
+current directory of syslinux as it will be seen
+on runtime  [default is parent directory of input
+file].
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print verbose messages.
+.TP
+\-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.SH "REPORTING BUGS"
+Report bugs to <bug\-grub@gnu.org>.
+.SH "SEE ALSO"
+.BR grub-menulst2cfg (8)
+.PP
+The full documentation for
+.B grub-syslinux2cfg
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B grub-syslinux2cfg
+programs are properly installed at your site, the command
+.IP
+.B info grub-syslinux2cfg
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/gs.1 b/upstream/mageia-cauldron/man1/gs.1
new file mode 100644
index 00000000..c3897406
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gs.1
@@ -0,0 +1,431 @@
+.TH GS 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+gs \- Ghostscript (PostScript and PDF language interpreter and previewer)
+.SH SYNOPSIS
+\fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR
+.br
+\fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR
+.br
+\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR
+.br
+\fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+.SH DESCRIPTION
+The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR)
+command invokes \fBGhostscript\fR, an interpreter of Adobe Systems'
+\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages.
+\fBgs\fR reads "files" in sequence and executes them as Ghostscript
+programs. After doing this, it reads further input from the standard input
+stream (normally the keyboard), interpreting each line separately and
+output to an output device (may be a file or an X11 window preview,
+see below). The
+interpreter exits gracefully when it encounters the "quit" command (either
+in a file or from the keyboard), at end-of-file, or at an interrupt signal
+(such as Control-C at the keyboard).
+.PP
+The interpreter recognizes many option switches, some of which are described
+below. Please see the usage documentation for complete information. Switches
+may appear anywhere in the command line and apply to all files thereafter.
+Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a
+message which shows several useful switches, all the devices known to
+that executable, and the search path for fonts; on Unix it also shows the
+location of detailed documentation.
+.PP
+Ghostscript may be built to use many different output devices.  To see
+which devices your executable includes, run "\fBgs -h\fR".
+.PP
+Unless you
+specify a particular device, Ghostscript normally opens the first one of
+those and directs output to it.
+.PP
+If built with X11 support, often
+the default device is an X11 window (previewer), else ghostscript will
+typically
+use the bbox device and print on stdout the dimension of the postscript file.
+.PP
+So if the first one in the list is the one
+you want to use, just issue the command
+.PP
+.nf
+	gs myfile.ps
+.fi
+.PP
+You can also check the set of available devices from within Ghostscript:
+invoke Ghostscript and type
+.PP
+.nf
+	devicenames ==
+.fi
+.PP
+but the first device on the resulting list may not be the default device
+you determine with "\fBgs -h\fR".  To specify "AbcXyz" as the
+initial output device, include the switch
+.PP
+.nf
+	\-sDEVICE=AbcXyz
+.fi
+.PP
+For example, for output to an Epson printer you might use the command
+.PP
+.nf
+	gs \-sDEVICE=epson myfile.ps
+.fi
+.PP
+The "\-sDEVICE=" switch must precede the first mention of a file to print,
+and only the switch's first use has any effect.
+.PP
+Finally, you can specify a default device in the environment variable
+\fBGS_DEVICE\fR.  The order of precedence for these alternatives from
+highest to lowest (Ghostscript uses the device defined highest in the list)
+is:
+.PP
+Some devices can support different resolutions (densities).  To specify
+the resolution on such a printer, use the "\-r" switch:
+.PP
+.nf
+	gs \-sDEVICE=<device> \-r<xres>x<yres>
+.fi
+.PP
+For example, on a 9-pin Epson-compatible printer, you get the
+lowest-density (fastest) mode with
+.PP
+.nf
+	gs \-sDEVICE=epson \-r60x72
+.fi
+.PP
+and the highest-density (best output quality) mode with
+.PP
+.nf
+	gs \-sDEVICE=epson \-r240x72.
+.fi
+.PP
+If you select a printer as the output device, Ghostscript also allows you
+to choose where Ghostscript sends the output \-\- on Unix systems, usually
+to a temporary file.  To send the output to a file "foo.xyz",
+use the switch
+.PP
+.nf
+	\-sOutputFile=foo.xyz
+.fi
+.PP
+You might want to print each page separately.  To do this, send the output
+to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
+switch with "%d" in a filename template:
+.PP
+.nf
+	\-sOutputFile=foo%d.xyz
+.fi
+.PP
+Each resulting file receives one page of output, and the files are numbered
+in sequence.  "%d" is a printf format specification; you can also use a
+variant like "%02d".
+.PP
+On Unix and MS Windows systems you can also send output to a pipe.  For example, to
+pipe output to the "\fBlpr\fR" command (which, on many Unix systems,
+directs it to a printer), use the option
+.PP
+.nf
+	\-sOutputFile=%pipe%lpr
+.fi
+.PP
+Note that the '%' characters need to be doubled on MS Windows to avoid 
+mangling by the command interpreter.
+.PP
+You can also send output to standard output:
+.PP
+.nf
+	\-sOutputFile=\-
+.fi
+or
+.nf
+	\-sOutputFile=%stdout%
+.fi
+.PP
+In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript
+from writing messages to standard output.
+.PP
+To select a specific paper size, use the command line switch
+.PP
+.nf
+	-sPAPERSIZE=<paper_size>
+.fi
+.PP
+for instance
+.PP
+.nf
+	-sPAPERSIZE=a4
+.fi
+or
+.nf
+	-sPAPERSIZE=legal
+.fi
+.PP
+Most ISO and US paper sizes are recognized. See the usage documentation for
+a full list, or the definitions in the initialization file "gs_statd.ps".
+.PP
+Ghostscript can do many things other than print or view PostScript and
+PDF files.  For example, if you want to know the bounding box of a
+PostScript (or EPS) file, Ghostscript provides a special "device" that
+just prints out this information.
+.PP
+For example, using one of the example files distributed with Ghostscript,
+.PP
+.nf
+	gs \-sDEVICE=bbox golfer.ps
+.fi
+.PP
+prints out
+.PP
+.nf
+	%%BoundingBox: 0 25 583 732
+	%%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445
+.fi
+.SH OPTIONS
+.TP
+.BI \-\- " filename arg1 ..."
+Takes the next argument as a file name as usual, but takes all remaining
+arguments (even if they have the syntactic form of switches) and defines
+the name "ARGUMENTS" in "userdict" (not "systemdict") as an
+array of those strings, \fBbefore\fR running the file.  When Ghostscript
+finishes executing the file, it exits back to the shell.
+.TP
+.BI \-D name = token
+.TQ
+.BI \-d name = token
+Define a name in "systemdict" with the given definition.  The token must be
+exactly one token (as defined by the "token" operator) and may contain no
+whitespace.
+.TP
+.BI \-D name
+.TQ
+.BI \-d name
+Define a name in "systemdict" with value=null.
+.TP
+.BI \-S name = string
+.TQ
+.BI \-s name = string
+Define a name in "systemdict" with a given string as value.  This is
+different from \fB\-d\fR.  For example, \fB\-dname=35\fR is equivalent to the
+program fragment
+.br
+	/name 35 def
+.br
+whereas \fB\-sname=35\fR is equivalent to
+.br
+	/name (35) def
+.TP
+.B \-P
+Makes Ghostscript to look first in the current directory for library files.
+By default, Ghostscript no longer looks in the current directory,
+unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
+See also the \fBINITIALIZATION FILES\fR section below, and bundled 
+\fBUse.htm\fR for detailed discussion on search paths and how Ghostcript finds files.
+.TP
+.B \-q
+Quiet startup: suppress normal startup messages, and also do the
+equivalent of \fB\-dQUIET\fR.
+.TP
+.BI \-g number1 x number2
+Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and
+\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR.  This is for the benefit of devices
+(such as X11 windows) that require (or allow) width and height to be
+specified.
+.TP
+.BI \-r number
+.TQ
+.BI \-r number1 x number2
+Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and
+\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR.  This is for the benefit of
+devices such as printers that support multiple X and Y resolutions.  If
+only one number is given, it is used for both X and Y resolutions.
+.TP
+.BI \-I directories
+Adds the designated list of directories at the head of the
+search path for library files.
+.TP
+.B \-
+This is not really a switch, but indicates to Ghostscript that standard
+input is coming from a file or a pipe and not interactively from the
+command line.  Ghostscript reads from standard input until it reaches
+end-of-file, executing it like any other file, and then continues with
+processing the command line.  When the command line has been entirely
+processed, Ghostscript exits rather than going into its interactive mode.
+.PP
+Note that the normal initialization file "gs_init.ps" makes "systemdict"
+read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR,
+\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be
+superseded by definitions in "userdict" or other dictionaries.)
+.SH "SPECIAL NAMES"
+.TP
+.B \-dNOCACHE
+Disables character caching.  Useful only for debugging.
+.TP
+.B \-dNOBIND
+Disables the "bind" operator.  Useful only for debugging.
+.TP
+.B \-dNODISPLAY
+Suppresses the normal initialization of the output device.
+This may be useful when debugging.
+.TP
+.B \-dNOPAUSE
+Disables the prompt and pause at the end of each page.  This may be
+desirable for applications where another program is driving Ghostscript.
+.TP
+.B \-dNOPLATFONTS
+Disables the use of fonts supplied by the underlying platform (for instance
+X Windows). This may be needed if the platform fonts look undesirably
+different from the scalable fonts.
+.TP
+.B \-dSAFER
+Restricts file operations the job can perform. Now the default mode of operation.
+.TP
+.B \-dWRITESYSTEMDICT
+Leaves "systemdict" writable.  This is necessary when running special
+utility programs, but is strongly discouraged as it bypasses normal Postscript
+security measures.
+.TP
+.BI \-sDEVICE= device
+Selects an alternate initial output device, as described above.
+.TP
+.BI \-sOutputFile= filename
+Selects an alternate output file (or pipe) for the initial output
+device, as described above.
+.SH "SAFER MODE"
+.PP
+The
+.B \-dSAFER
+option restricts file system accesses to those files and directories
+allowed by the relevant environment variables (such as GS_LIB) or
+by the command line parameters (see https://ghostscript.com/doc/current/Use.htm
+for details).
+.PP
+SAFER mode is now the default mode of operation. Thus when running programs that
+need to open files or set restricted parameters
+you should pass the
+.B \-dNOSAFER
+command line option or its synonym
+.BR \-dDELAYSAFER .
+.PP
+Running with NOSAFER/DELAYSAFER (as the same suggests) loosens the security
+and is thus recommended ONLY for debugging or in VERY controlled workflows,
+and strongly NOT recommended in any other circumstances.
+.SH FILES
+.PP
+The locations of many Ghostscript run-time files are compiled into the
+executable when it is built.  On Unix these are typically based in
+\fB/usr/local\fR, but this may be different on your system.  Under DOS they
+are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if
+you install Ghostscript with \fBGSview\fR.  Run "\fBgs -h\fR" to find the
+location of Ghostscript documentation on your system, from which you can
+get more details.
+.TP
+.B /usr/local/share/ghostscript/#.##/*
+Startup files, utilities, and basic font definitions
+.TP
+.B /usr/local/share/ghostscript/fonts/*
+More font definitions
+.TP
+.B /usr/local/share/ghostscript/#.##/examples/*
+Ghostscript demonstration files
+.TP
+.B /usr/local/share/ghostscript/#.##/doc/*
+Diverse document files
+.SH "INITIALIZATION FILES"
+When looking for the initialization files "gs_*.ps", the files related to
+fonts, or the file for the "run" operator, Ghostscript first tries to open
+the file with the name as given, using the current working directory if no
+directory is specified.  If this fails, and the file name doesn't specify
+an explicit directory or drive (for instance, doesn't contain "/" on Unix
+systems or "\\" on MS Windows systems), Ghostscript tries directories in this
+order:
+.TP 4
+1.
+the directories specified by the \fB\-I\fR switches in the command
+line (see below), if any;
+.TP
+2.
+the directories specified by the \fBGS_LIB\fR environment variable,
+if any;
+.TP
+3.
+the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the
+Ghostscript makefile when the executable was built.  When \fBgs\fR is built
+on Unix, \fBGS_LIB_DEFAULT\fR is usually
+"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts"
+where "#.##" represents the Ghostscript version number.
+.PP
+Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)
+may be either a single directory or a list of directories separated by
+":".
+.SH ENVIRONMENT
+.TP
+.B GS_OPTIONS
+String of options to be processed before the command line options
+.TP
+.B GS_DEVICE
+Used to specify an output device
+.TP
+.B GS_FONTPATH
+Path names used to search for fonts
+.TP
+.B GS_LIB
+Path names for initialization files and fonts
+.TP
+.B  TEMP
+Where temporary files are made
+.SH X RESOURCES
+Ghostscript, or more properly the X11 display device, looks for the 
+following resources under the program name "Ghostscript":
+.TP
+.B borderWidth
+The border width in pixels (default = 1).
+.TP
+.B borderColor
+The name of the border color (default = black).
+.TP
+.B geometry
+The window size and placement, WxH+X+Y (default is NULL).
+.TP
+.B xResolution
+The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR
+and \fBWidthMMOfScreen\fR).
+.TP
+.B yResolution
+The number of y pixels per inch (default is computed from
+\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR).
+.TP
+.B useBackingPixmap
+Determines whether backing store is to be used for saving display window
+(default = true).
+.PP
+See the usage document for a more complete list of resources.  To set these
+resources on Unix, put them in a file such as "~/.Xresources" in the
+following form:
+.PP
+.nf
+	Ghostscript*geometry:	 612x792\-0+0
+	Ghostscript*xResolution: 72
+	Ghostscript*yResolution: 72
+.fi
+.PP
+Then merge these resources into the X server's resource database:
+.PP
+.nf
+	% xrdb \-merge ~/.Xresources
+.fi
+.SH SEE ALSO
+The various Ghostscript document files (above), especially \fBUse.htm\fR.
+.SH BUGS
+See http://bugs.ghostscript.com/ and the Usenet news group 
+comp.lang.postscript.
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the primary maintainers
+of Ghostscript.
+Russell J. Lang, gsview at ghostgum.com.au, is the author of 
+most of the MS Windows code in Ghostscript.
diff --git a/upstream/mageia-cauldron/man1/gslp.1 b/upstream/mageia-cauldron/man1/gslp.1
new file mode 100644
index 00000000..9794045c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gslp.1
@@ -0,0 +1,99 @@
+.TH GSLP 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+gslp \- Format and print text using ghostscript
+.br
+gsbj \- Format and print text for BubbleJet printer using ghostscript
+.br
+gsdj \- Format and print text for DeskJet printer using ghostscript
+.br
+gsdj500 \- Format and print text for DeskJet 500 BubbleJet using ghostscript
+.br
+gslj \- Format and print text for LaserJet printer using ghostscript
+.SH SYNOPSIS
+.na
+\fBgslp\fB 
+\-12BclqRr \-b<header> \-f<font> \-F<hfont> \-L<lines> \-p<outfile>
+\-T<n>
+\-\-add\-to\-space\ <units>
+\-\-add\-to\-width\ <units>
+\-\-columns\ <n>
+\-\-detect
+\-\-first\-page\ <n>
+\-\-kern\ <file.afm>
+\-\-last\-page\ <n>
+\-\-(heading|footing)\-(left|center|right)\ <string>
+\-\-margin\-(top|bottom|left|right)\ <inches>
+\-\-no\-eject\-(file|formfeed)
+\-\-spacing\ <n>
+[gs\ options] [files]
+.ad
+.br
+\fBgsbj\fR [options] [files]
+.br
+\fBgsdj\fR [options] [files]
+.br
+\fBgsdj500\fR [options] [files]
+.br
+\fBgslj\fR [options] [files]
+.SH DESCRIPTION
+This utility provides functionality approximately equivalent to the Unix
+.BR enscript (1)
+program.  It prints plain text files using a single font.
+It currently handles tabs and formfeeds, but not backspaces.
+It will line-wrap when using fixed-pitch fonts.
+It will also do kerning and width adjustment.
+.PP
+The default device (\-sDEVICE=) and resolution (\-r) are as follows:
+.nf
+.na
+      gslp      epson      180
+      gsbj      bj10e      180
+      gsdj      deskjet    300
+      gsdj500   djet500    300
+      gslj      laserjet   300
+.ad
+.fi
+By default the current date is formatted as the center header.
+.SH OPTIONS
+.IP "Standard switches implemented:"
+-12BclqRr -b<header> -f<font> -F<hfont> -L<lines> -p<outfile>
+.IP "Sun switches implemented:"
+-T<n>	set tab width
+.IP "Switches ignored:"
+-GghKkmow -# -C -d -J -n -P -S -s -t -v
+.IP "Switches added:"
+.RS
+.IP "--add-to-space <units>"
+add the given number of 1/72" units to the width of each
+space (may be negative)
+.IP "--add-to-width <units>"
+add the given number of 1/72" units to the width of each
+character (may be negative)
+.IP "--columns <n>"
+print in <n> columns
+.IP "--detect"
+treat the file as PostScript if it starts with %!
+.IP "--first-page <n>"
+start printing at page <n>
+.IP "--kern <file.afm>"
+kern using information from the given .AFM file
+.IP "--last-page <n>"
+stop printing after page <n>
+.IP "--(heading|footing)-(left|center|right) <string>"
+set the heading/footing fields; use -B first to clear
+.IP "--margin-(top|bottom|left|right) <inches>"
+set a margin
+.IP "--no-eject-(file|formfeed)"
+end-of-file/FF only starts a new column, not a new sheet
+.IP "--spacing <n>"
+use double (n=2), triple (n=3), etc. spacing
+.RE
+Also, the string %# in a heading or footing is replaced with the page #.
+.SH SEE ALSO
+gs(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/gsnd.1 b/upstream/mageia-cauldron/man1/gsnd.1
new file mode 100644
index 00000000..2711357c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gsnd.1
@@ -0,0 +1,19 @@
+.TH GSND 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+gsnd \- Run ghostscript (PostScript and PDF engine) without display
+.SH SYNOPSIS
+\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ...
+.SH DESCRIPTION
+This script simply invokes
+.BR gs (1)
+with the
+.B -NODISPLAY
+flag, followed by any other arguments from the command-line.
+.SH SEE ALSO
+gs(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/gstack.1 b/upstream/mageia-cauldron/man1/gstack.1
new file mode 100644
index 00000000..1f4e406b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gstack.1
@@ -0,0 +1,48 @@
+.\"
+.\" gstack manual page.
+.\" Copyright (c) 1999 Ross Thompson
+.\" Copyright (c) 2001, 2002, 2004, 2008 Red Hat, Inc.
+.\"
+.\" Original author: Ross Thompson <ross@whatsis.com>
+.\"
+.\" 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 2, or (at your option)
+.\" any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; see the file COPYING.  If not, write to
+.\" the Free Software Foundation, 59 Temple Place - Suite 330,
+.\" Boston, MA 02111-1307, USA.
+.\"
+.TH GSTACK 1 "Feb 15 2008" "Red Hat Linux" "Linux Programmer's Manual"
+
+.SH NAME
+gstack \- print a stack trace of a running process
+
+.SH SYNOPSIS
+.B gstack
+pid
+
+.SH DESCRIPTION
+
+\f3gstack\f1 attaches to the active process named by the \f3pid\f1 on
+the command line, and prints out an execution stack trace.  If ELF
+symbols exist in the binary (usually the case unless you have run
+strip(1)), then symbolic addresses are printed as well.
+
+If the process is part of a thread group, then \f3gstack\f1 will print
+out a stack trace for each of the threads in the group.
+
+.SH SEE ALSO
+nm(1), ptrace(2), gdb(1)
+
+.SH AUTHORS
+Ross Thompson <ross@whatsis.com>
+
+Red Hat, Inc. <http://bugzilla.redhat.com/bugzilla>
diff --git a/upstream/mageia-cauldron/man1/gzexe.1 b/upstream/mageia-cauldron/man1/gzexe.1
new file mode 100644
index 00000000..04e3a732
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gzexe.1
@@ -0,0 +1,57 @@
+.TH GZEXE 1
+.SH NAME
+gzexe \- compress executable files in place
+.SH SYNOPSIS
+.B gzexe
+.I "name .\|.\|."
+.SH DESCRIPTION
+The
+.B gzexe
+utility allows you to compress executables in place and have them
+automatically uncompress and execute when you run them (at a penalty
+in performance).  For example if you execute ``gzexe /usr/bin/gdb'' it
+will create the following two files:
+.nf
+.br
+    -rwxr-xr-x  1 root root 1026675 Jun  7 13:53 /usr/bin/gdb
+    -rwxr-xr-x  1 root root 2304524 May 30 13:02 /usr/bin/gdb~
+.fi
+/usr/bin/gdb~ is the original file and /usr/bin/gdb is the self-uncompressing
+executable file.  You can remove /usr/bin/gdb~ once you are sure that
+/usr/bin/gdb works properly.
+.PP
+This utility is most useful on systems with very small disks.
+.SH OPTIONS
+.TP
+.B \-d
+Decompress the given executables instead of compressing them.
+.SH "SEE ALSO"
+.BR gzip (1),
+.BR znew (1),
+.BR zmore (1),
+.BR zcmp (1),
+.BR zforce (1)
+.SH CAVEATS
+The compressed executable is a shell script.  This may create some
+security holes.  In particular, the compressed executable relies
+on the PATH environment variable to find
+.B gzip
+and some standard utilities
+.RB ( basename ,
+.BR chmod ,
+.BR ln ,
+.BR mkdir ,
+.BR mktemp ,
+.BR rm ,
+.BR sleep ,
+and
+.BR tail ).
+.SH "BUGS"
+The
+.B gzexe
+command
+attempts to retain the original file attributes on the compressed executable,
+but you may have to fix them manually in some cases, using
+.B chmod
+or
+.BR chown .
diff --git a/upstream/mageia-cauldron/man1/gzip.1 b/upstream/mageia-cauldron/man1/gzip.1
new file mode 100644
index 00000000..657ad0d6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/gzip.1
@@ -0,0 +1,577 @@
+.TH GZIP 1 local
+.SH NAME
+gzip, gunzip, zcat \- compress or expand files
+.SH SYNOPSIS
+.ll +8
+.B gzip
+.RB [ " \-acdfhklLnNrtvV19 " ]
+.RB [ \-S\ suffix ]
+[
+.I "name \&..."
+]
+.ll -8
+.br
+.B gunzip
+.RB [ " \-acfhklLnNrtvV " ]
+.RB [ \-S\ suffix ]
+[
+.I "name \&..."
+]
+.br
+.B zcat
+.RB [ " \-fhLV " ]
+[
+.I "name \&..."
+]
+.SH DESCRIPTION
+The
+.B gzip
+command
+reduces the size of the named files using Lempel-Ziv coding (LZ77).
+Whenever possible,
+each file is replaced by one with the extension
+.BR "\&.gz" ,
+while keeping the same ownership modes, access and modification times.
+(The default extension is
+.B "z"
+for MSDOS, OS/2 FAT, Windows NT FAT and Atari.)
+If no files are specified, or if a file name is "\-",
+the standard input is compressed to the standard output.
+The
+.B gzip
+command
+will only attempt to compress regular files.
+In particular, it will ignore symbolic links.
+.PP
+If the compressed file name is too long for its file system,
+.B gzip
+truncates it.
+The
+.B gzip
+command
+attempts to truncate only the parts of the file name longer than 3 characters.
+(A part is delimited by dots.) If the name consists of small parts only,
+the longest parts are truncated.
+For example, if file names are limited to 14 characters,
+gzip.msdos.exe is compressed to gzi.msd.exe.gz.
+Names are not truncated on systems which do not have a limit on file name
+length.
+.PP
+By default,
+.B gzip
+keeps the original file name and timestamp in the compressed file.
+These are used when decompressing the file with the
+.B \-N
+option.
+This is useful when the compressed file name was truncated or
+when the timestamp was not preserved after a file transfer.
+.PP
+Compressed files can be restored to their original form using
+.B "gzip \-d"
+or
+.B gunzip
+or
+.BR zcat .
+If the original name saved in the compressed file is not suitable for its
+file system, a new name is constructed from the original one to make it valid.
+.PP
+.B gunzip
+takes a list of files on its command line and replaces each
+file whose name ends with .gz, \-gz, .z, \-z, or _z (ignoring case)
+and which begins with the correct magic number with an uncompressed
+file without the original extension.
+.B gunzip
+also recognizes the special extensions
+.B "\&.tgz"
+and
+.B "\&.taz"
+as shorthands for
+.B "\&.tar.gz"
+and
+.B "\&.tar.Z"
+respectively.
+When compressing,
+.B gzip
+uses the
+.B "\&.tgz"
+extension if necessary instead of truncating a file with a
+.B "\&.tar"
+extension.
+.PP
+.B gunzip
+can currently decompress files created by
+.BR gzip ,
+.BR zip ,
+.BR compress ,
+.B "compress \-H"
+or
+.BR pack .
+The detection of the input format is automatic.
+When using the first two formats,
+.B gunzip
+checks a 32 bit CRC.
+For
+.B pack
+and
+.B gunzip
+checks the uncompressed length.
+The standard
+.B compress
+format was not designed to allow consistency checks.
+However
+.B gunzip
+is sometimes able to detect a bad .Z file.
+If you get an error when uncompressing a .Z file,
+do not assume that the .Z file is
+correct simply because the standard
+.B uncompress
+does not complain.
+This generally means that the standard
+.B uncompress
+does not check its input, and happily generates garbage output.
+The SCO compress \-H format (lzh compression method) does not include a CRC
+but also allows some consistency checks.
+.PP
+Files created by
+.B zip
+can be uncompressed by gzip only if they have a single member compressed
+with the 'deflation' method.
+This feature is only intended to help
+conversion of tar.zip files to the tar.gz format.
+To extract a
+.B zip
+file with a single member, use a command like
+.RB ' "gunzip <foo.zip" '
+or
+.RB ' "gunzip \-S .zip foo.zip" '.
+To extract zip files
+with several members, use
+.B unzip
+instead of
+.BR gunzip .
+.PP
+The
+.B zcat
+command
+is identical to
+.B gunzip
+.BR \-c .
+(On some systems,
+.B zcat
+may be installed as
+.B gzcat
+to preserve the original link to
+.BR compress .)
+.B zcat
+uncompresses either a list of files on the command line or its
+standard input and writes the uncompressed data on standard output.
+.B zcat
+will uncompress files that have the correct magic number whether
+they have a
+.B "\&.gz"
+suffix or not.
+.PP
+The
+.B gzip
+command
+uses the Lempel-Ziv algorithm used in
+.B zip
+and PKZIP.
+The amount of compression obtained depends on the size of the
+input and the distribution of common substrings.
+Typically, text such as source code or English
+is reduced by 60\(en70%.
+Compression is generally much better than that achieved by
+LZW (as used in
+.BR compress ),
+Huffman coding (as used in
+.BR pack ),
+or adaptive Huffman coding
+.RB ( compact ).
+.PP
+Compression is always performed, even if the compressed file is
+slightly larger than the original.
+The worst case expansion is
+a few bytes for the gzip file header, plus 5 bytes per 32\ KiB block,
+or an expansion ratio of 0.015% for large files.
+The actual number of used disk blocks almost never increases.
+.PP
+.B gzip
+normally preserves the mode and modification timestamp
+of a file when compressing or decompressing.
+If you have appropriate privileges,
+it also preserves the file's owner and group.
+.SH OPTIONS
+.TP
+.B \-a \-\-ascii
+Ascii text mode: convert end-of-lines using local conventions.
+This option is supported only on some non-Unix systems.
+For MSDOS, CR LF is converted to LF when compressing,
+and LF is converted to CR LF when decompressing.
+.TP
+.B \-c \-\-stdout \-\-to-stdout
+Write output on standard output; keep original files unchanged.
+If there are several input files, the output consists of a sequence of
+independently compressed members.
+To obtain better compression,
+concatenate all input files before compressing them.
+.TP
+.B \-d \-\-decompress \-\-uncompress
+Decompress.
+.TP
+.B \-f \-\-force
+Force compression or decompression even if the file has multiple links
+or the corresponding file already exists, or if the compressed data
+is read from or written to a terminal.
+If the input data is not in a format recognized by
+.BR gzip ,
+and if the option \-\-stdout is also given, copy the input data without change
+to the standard output: let
+.B zcat
+behave as
+.BR cat .
+If
+.B \-f
+is not given,
+and when not running in the background,
+.B gzip
+prompts to verify whether an existing file should be overwritten.
+.TP
+.B \-h \-\-help
+Display a help screen and quit.
+.TP
+.B \-k \-\-keep
+Keep (don't delete) input files during compression or decompression.
+.TP
+.B \-l \-\-list
+For each compressed file, list the following fields:
+
+    compressed size: size of the compressed file
+    uncompressed size: size of the uncompressed file
+    ratio: compression ratio (0.0% if unknown)
+    uncompressed_name: name of the uncompressed file
+
+The uncompressed size is given as \-1 for files not in gzip format,
+such as compressed .Z files.
+To get the uncompressed size for such a file, you can use:
+
+    zcat file.Z | wc \-c
+
+In combination with the \-\-verbose option, the following fields are also
+displayed:
+
+    method: compression method
+    crc: the 32-bit CRC of the uncompressed data
+    date & time: timestamp for the uncompressed file
+
+The compression methods currently supported are deflate, compress, lzh
+(SCO compress \-H) and pack.
+The crc is given as ffffffff for a file not in gzip format.
+
+With \-\-name, the uncompressed name,  date and time  are
+those stored within the compress file if present.
+
+With \-\-verbose, the size totals and compression ratio for all files
+is also displayed, unless some sizes are unknown.
+With \-\-quiet, the title and totals lines are not displayed.
+.TP
+.B \-L \-\-license
+Display the
+.B gzip
+license and quit.
+.TP
+.B \-n \-\-no-name
+When compressing, do not save the original file name and timestamp by default.
+(The original name is always saved if the name had to be truncated.)
+When decompressing, do not restore the original file name
+if present (remove only the
+.B gzip
+suffix from the compressed file name) and do not restore the original
+timestamp if present (copy it from the compressed file).
+This option is the default when decompressing.
+.TP
+.B \-N \-\-name
+When compressing, always save the original file name, and save
+the seconds part of the original modification timestamp if the
+original is a regular file and its timestamp is at least 1 (1970-01-01
+00:00:01 UTC) and is less than 2**32 (2106-02-07 06:28:16 UTC,
+assuming leap seconds are not counted); this
+is the default.
+When decompressing, restore from the saved file name and
+timestamp if present.
+This option is useful on systems which have a limit on file name
+length or when the timestamp has been lost after a file transfer.
+.TP
+.B \-q \-\-quiet
+Suppress all warnings.
+.TP
+.B \-r \-\-recursive
+Travel the directory structure recursively.
+If any of the file names specified on the command line are directories,
+.B gzip
+will descend into the directory and compress all the files it finds there
+(or decompress them in the case of
+.B gunzip
+).
+.TP
+.B \-S .suf   \-\-suffix .suf
+When compressing, use suffix .suf instead of .gz.
+Any non-empty suffix can be given, but suffixes
+other than .z and .gz should be avoided to avoid confusion when files
+are transferred to other systems.
+
+When decompressing, add .suf to the beginning of the list of
+suffixes to try, when deriving an output file name from an input file name.
+.TP
+.B \-\-synchronous
+Use synchronous output.
+With this option,
+.B gzip
+is less likely to lose data during a system crash, but it can be
+considerably slower.
+.TP
+.B \-t \-\-test
+Test.
+Check the compressed file integrity then quit.
+.TP
+.B \-v \-\-verbose
+Verbose.
+Display the name and percentage reduction for each file compressed
+or decompressed.
+.TP
+.B \-V \-\-version
+Version.
+Display the version number and compilation options then quit.
+.TP
+.B \-# \-\-fast \-\-best
+Regulate the speed of compression using the specified digit
+.BR # ,
+where
+.B \-1
+or
+.B \-\-fast
+indicates the fastest compression method (less compression)
+and
+.B \-9
+or
+.B \-\-best
+indicates the slowest compression method (best compression).
+The default compression level is
+.B \-6
+(that is, biased towards high compression at expense of speed).
+.TP
+.B \-\-rsyncable
+When you synchronize a compressed file between two computers,
+this option allows rsync to transfer only files that were changed in
+the archive instead of the entire archive.
+Normally, after a change is made to any file in the archive,
+the compression algorithm can generate a new version of the archive
+that does not match the previous version of the archive.
+In this case, rsync transfers the entire new version of the archive to
+the remote computer.
+With this option, rsync can transfer only the changed files as well as
+a small amount of metadata that is required to update the archive
+structure in the area that was changed.
+.SH "ADVANCED USAGE"
+Multiple compressed files can be concatenated.
+In this case,
+.B gunzip
+will extract all members at once.
+For example:
+
+      gzip \-c file1  > foo.gz
+      gzip \-c file2 >> foo.gz
+
+Then
+
+      gunzip \-c foo
+
+is equivalent to
+
+      cat file1 file2
+
+In case of damage to one member of a .gz file, other members can
+still be recovered (if the damaged member is removed).
+However, you can get better compression by compressing all members at once:
+
+      cat file1 file2 | gzip > foo.gz
+
+compresses better than
+
+      gzip \-c file1 file2 > foo.gz
+
+If you want to recompress concatenated files to get better compression, do:
+
+      gzip \-cd old.gz | gzip > new.gz
+
+If a compressed file consists of several members, the uncompressed
+size and CRC reported by the \-\-list option applies to the last member only.
+If you need the uncompressed size for all members, you can use:
+
+      gzip \-cd file.gz | wc \-c
+
+If you wish to create a single archive file with multiple members so
+that members can later be extracted independently, use an archiver
+such as tar or zip.
+GNU tar supports the \-z option to invoke gzip transparently.
+gzip is designed as a complement to tar, not as a replacement.
+.SH "ENVIRONMENT"
+The obsolescent environment variable
+.B GZIP
+can hold a set of default options for
+.BR gzip .
+These options are interpreted first and can be overwritten by explicit
+command line parameters.
+As this can cause problems when using scripts,
+this feature is supported only for options that are
+reasonably likely to not cause too much harm, and
+.B gzip
+warns if it is used.
+This feature will be removed in a future release of
+.BR gzip .
+.PP
+You can use an alias or script instead.
+For example, if
+.B gzip
+is in the directory
+.B /usr/bin
+you can prepend
+.B $HOME/bin
+to your
+.B PATH
+and create an executable script
+.B $HOME/bin/gzip
+containing the following:
+
+      #! /bin/sh
+      export PATH=/usr/bin
+      exec gzip \-9 "$@"
+.SH "SEE ALSO"
+.BR znew (1),
+.BR zcmp (1),
+.BR zmore (1),
+.BR zforce (1),
+.BR gzexe (1),
+.BR zip (1),
+.BR unzip (1),
+.BR compress (1)
+.PP
+The
+.B gzip
+file format is specified in P. Deutsch, \s-1GZIP\s0 file format
+specification version 4.3,
+.BR <https://www.ietf.org/rfc/rfc1952.txt> ,
+Internet RFC 1952 (May 1996).
+The
+.B zip
+deflation format is specified in P. Deutsch, \s-1DEFLATE\s0 Compressed
+Data Format Specification version 1.3,
+.BR <https://www.ietf.org/rfc/rfc1951.txt> ,
+Internet RFC 1951 (May 1996).
+.SH "DIAGNOSTICS"
+Exit status is normally 0;
+if an error occurs, exit status is 1.
+If a warning occurs, exit status is 2.
+.TP
+Usage: gzip [\-cdfhklLnNrtvV19] [\-S suffix] [file ...]
+Invalid options were specified on the command line.
+.TP
+\fIfile\fP\^: not in gzip format
+The file specified to
+.B gunzip
+has not been compressed.
+.TP
+\fIfile\fP\^: Corrupt input.
+Use zcat to recover some data.
+The compressed file has been damaged.
+The data up to the point of failure can be recovered using
+
+      zcat \fIfile\fP > recover
+.TP
+\fIfile\fP\^: compressed with \fIxx\fP bits, can only handle \fIyy\fP bits
+.B File
+was compressed (using LZW) by a program that could deal with
+more
+bits
+than the decompress code on this machine.
+Recompress the file with gzip, which compresses better and uses
+less memory.
+.TP
+\fIfile\fP\^: already has .gz suffix \-\- unchanged
+The file is assumed to be already compressed.
+Rename the file and try again.
+.TP
+\fIfile\fP already exists; do you wish to overwrite (y or n)?
+Respond "y" if you want the output file to be replaced; "n" if not.
+.TP
+gunzip: corrupt input
+A SIGSEGV violation was detected which usually means that the input file has
+been corrupted.
+.TP
+\fIxx.x%\fP Percentage of the input saved by compression.
+(Relevant only for
+.B \-v
+and
+.BR \-l \.)
+.TP
+\-\- not a regular file or directory: ignored
+When the input file is not a regular file or directory,
+(e.g., a symbolic link, socket, FIFO, device file), it is
+left unaltered.
+.TP
+\-\- has \fIxx\fP other links: unchanged
+The input file has links; it is left unchanged.
+See
+.BR ln "(1)"
+for more information.
+Use the
+.B \-f
+flag to force compression of multiply-linked files.
+.SH CAVEATS
+When writing compressed data to a tape, it is generally necessary to
+pad the output with zeroes up to a block boundary.
+When the data is read and the whole block is passed to
+.B gunzip
+for decompression,
+.B gunzip
+detects that there is extra trailing garbage after the compressed data
+and emits a warning by default.
+You can use the \-\-quiet option to suppress the warning.
+.SH BUGS
+In some rare cases, the \-\-best option gives worse compression than
+the default compression level (\-6).
+On some highly redundant files,
+.B compress
+compresses better than
+.BR gzip .
+.SH "REPORTING BUGS"
+Report bugs to: bug\-gzip@gnu.org
+.br
+GNU gzip home page: <https://www.gnu.org/software/gzip/>
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>
+.SH "COPYRIGHT NOTICE"
+Copyright \(co 1998\(en1999, 2001\(en2002, 2012, 2015\(en2023
+Free Software Foundation, Inc.
+.br
+Copyright \(co 1992, 1993 Jean-loup Gailly
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.
diff --git a/upstream/mageia-cauldron/man1/h2ph.1 b/upstream/mageia-cauldron/man1/h2ph.1
new file mode 100644
index 00000000..8de56770
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/h2ph.1
@@ -0,0 +1,193 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "H2PH 1"
+.TH H2PH 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+h2ph \- convert .h C header files to .ph Perl header files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBh2ph [\-d destination directory] [\-r | \-a] [\-l] [\-h] [\-e] [\-D] [\-Q]
+[headerfiles]\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fIh2ph\fR
+converts any C header files specified to the corresponding Perl header file
+format.
+It is most easily run while in /usr/include:
+.PP
+.Vb 1
+\&        cd /usr/include; h2ph * sys/*
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&        cd /usr/include; h2ph * sys/* arpa/* netinet/*
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&        cd /usr/include; h2ph \-r \-l .
+.Ve
+.PP
+The output files are placed in the hierarchy rooted at Perl's
+architecture dependent library directory.  You can specify a different
+hierarchy with a \fB\-d\fR switch.
+.PP
+If run with no arguments, filters standard input to standard output.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP "\-d destination_dir" 4
+.IX Item "-d destination_dir"
+Put the resulting \fB.ph\fR files beneath \fBdestination_dir\fR, instead of
+beneath the default Perl library location (\f(CW$Config{\*(Aqinstallsitearch\*(Aq}\fR).
+.IP \-r 4
+.IX Item "-r"
+Run recursively; if any of \fBheaderfiles\fR are directories, then run \fIh2ph\fR
+on all files in those directories (and their subdirectories, etc.).  \fB\-r\fR
+and \fB\-a\fR are mutually exclusive.
+.IP \-a 4
+.IX Item "-a"
+Run automagically; convert \fBheaderfiles\fR, as well as any \fB.h\fR files
+which they include.  This option will search for \fB.h\fR files in all
+directories which your C compiler ordinarily uses.  \fB\-a\fR and \fB\-r\fR are
+mutually exclusive.
+.IP \-l 4
+.IX Item "-l"
+Symbolic links will be replicated in the destination directory.  If \fB\-l\fR
+is not specified, then links are skipped over.
+.IP \-h 4
+.IX Item "-h"
+Put 'hints' in the .ph files which will help in locating problems with
+\&\fIh2ph\fR.  In those cases when you \fBrequire\fR a \fB.ph\fR file containing syntax
+errors, instead of the cryptic
+.Sp
+.Vb 1
+\&        [ some error condition ] at (eval mmm) line nnn
+.Ve
+.Sp
+you will see the slightly more helpful
+.Sp
+.Vb 1
+\&        [ some error condition ] at filename.ph line nnn
+.Ve
+.Sp
+However, the \fB.ph\fR files almost double in size when built using \fB\-h\fR.
+.IP \-e 4
+.IX Item "-e"
+If an error is encountered during conversion, output file will be removed and
+a warning emitted instead of terminating the conversion immediately.
+.IP \-D 4
+.IX Item "-D"
+Include the code from the \fB.h\fR file as a comment in the \fB.ph\fR file.
+This is primarily used for debugging \fIh2ph\fR.
+.IP \-Q 4
+.IX Item "-Q"
+\&'Quiet' mode; don't print out the names of the files being converted.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+No environment variables are used.
+.SH FILES
+.IX Header "FILES"
+.Vb 2
+\& /usr/include/*.h
+\& /usr/include/sys/*.h
+.Ve
+.PP
+etc.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1)
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+The usual warnings if it can't read or write the files involved.
+.SH BUGS
+.IX Header "BUGS"
+Doesn't construct the \f(CW%sizeof\fR array for you.
+.PP
+It doesn't handle all C constructs, but it does attempt to isolate
+definitions inside evals so that you can get at the definitions
+that it can translate.
+.PP
+It's only intended as a rough tool.
+You may need to dicker with the files produced.
+.PP
+You have to run this program by hand; it's not run as part of the Perl
+installation.
+.PP
+Doesn't handle complicated expressions built piecemeal, a la:
+.PP
+.Vb 7
+\&    enum {
+\&        FIRST_VALUE,
+\&        SECOND_VALUE,
+\&    #ifdef ABC
+\&        THIRD_VALUE
+\&    #endif
+\&    };
+.Ve
+.PP
+Doesn't necessarily locate all of your C compiler's internally-defined
+symbols.
diff --git a/upstream/mageia-cauldron/man1/h2xs.1 b/upstream/mageia-cauldron/man1/h2xs.1
new file mode 100644
index 00000000..aebd24b0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/h2xs.1
@@ -0,0 +1,482 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "H2XS 1"
+.TH H2XS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+h2xs \- convert .h C header files to Perl extensions
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBh2xs\fR [\fBOPTIONS\fR ...] [headerfile ... [extra_libraries]]
+.PP
+\&\fBh2xs\fR \fB\-h\fR|\fB\-?\fR|\fB\-\-help\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fIh2xs\fR builds a Perl extension from C header files.  The extension
+will include functions which can be used to retrieve the value of any
+#define statement which was in the C header files.
+.PP
+The \fImodule_name\fR will be used for the name of the extension.  If
+module_name is not supplied then the name of the first header file
+will be used, with the first character capitalized.
+.PP
+If the extension might need extra libraries, they should be included
+here.  The extension Makefile.PL will take care of checking whether
+the libraries actually exist and how they should be loaded.  The extra
+libraries should be specified in the form \-lm \-lposix, etc, just as on
+the cc command line.  By default, the Makefile.PL will search through
+the library path determined by Configure.  That path can be augmented
+by including arguments of the form \fB\-L/another/library/path\fR in the
+extra-libraries argument.
+.PP
+In spite of its name, \fIh2xs\fR may also be used to create a skeleton pure
+Perl module. See the \fB\-X\fR option.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP "\fB\-A\fR, \fB\-\-omit\-autoload\fR" 5
+.IX Item "-A, --omit-autoload"
+Omit all autoload facilities.  This is the same as \fB\-c\fR but also
+removes the \f(CW\*(C`use\ AutoLoader\*(C'\fR statement from the .pm file.
+.IP "\fB\-B\fR, \fB\-\-beta\-version\fR" 5
+.IX Item "-B, --beta-version"
+Use an alpha/beta style version number.  Causes version number to
+be "0.00_01" unless \fB\-v\fR is specified.
+.IP "\fB\-C\fR, \fB\-\-omit\-changes\fR" 5
+.IX Item "-C, --omit-changes"
+Omits creation of the \fIChanges\fR file, and adds a HISTORY section to
+the POD template.
+.IP "\fB\-F\fR, \fB\-\-cpp\-flags\fR=\fIaddflags\fR" 5
+.IX Item "-F, --cpp-flags=addflags"
+Additional flags to specify to C preprocessor when scanning header for
+function declarations.  Writes these options in the generated \fIMakefile.PL\fR
+too.
+.IP "\fB\-M\fR, \fB\-\-func\-mask\fR=\fIregular expression\fR" 5
+.IX Item "-M, --func-mask=regular expression"
+selects functions/macros to process.
+.IP "\fB\-O\fR, \fB\-\-overwrite\-ok\fR" 5
+.IX Item "-O, --overwrite-ok"
+Allows a pre-existing extension directory to be overwritten.
+.IP "\fB\-P\fR, \fB\-\-omit\-pod\fR" 5
+.IX Item "-P, --omit-pod"
+Omit the autogenerated stub POD section.
+.IP "\fB\-X\fR, \fB\-\-omit\-XS\fR" 5
+.IX Item "-X, --omit-XS"
+Omit the XS portion. Used to generate a skeleton pure Perl module.
+\&\f(CW\*(C`\-c\*(C'\fR and \f(CW\*(C`\-f\*(C'\fR are implicitly enabled.
+.IP "\fB\-a\fR, \fB\-\-gen\-accessors\fR" 5
+.IX Item "-a, --gen-accessors"
+Generate an accessor method for each element of structs and unions. The
+generated methods are named after the element name; will return the current
+value of the element if called without additional arguments; and will set
+the element to the supplied value (and return the new value) if called with
+an additional argument. Embedded structures and unions are returned as a
+pointer rather than the complete structure, to facilitate chained calls.
+.Sp
+These methods all apply to the Ptr type for the structure; additionally
+two methods are constructed for the structure type itself, \f(CW\*(C`_to_ptr\*(C'\fR
+which returns a Ptr type pointing to the same structure, and a \f(CW\*(C`new\*(C'\fR
+method to construct and return a new structure, initialised to zeroes.
+.IP "\fB\-b\fR, \fB\-\-compat\-version\fR=\fIversion\fR" 5
+.IX Item "-b, --compat-version=version"
+Generates a .pm file which is backwards compatible with the specified
+perl version.
+.Sp
+For versions < 5.6.0, the changes are.
+    \- no use of 'our' (uses 'use vars' instead)
+    \- no 'use warnings'
+.Sp
+Specifying a compatibility version higher than the version of perl you
+are using to run h2xs will have no effect.  If unspecified h2xs will default
+to compatibility with the version of perl you are using to run h2xs.
+.IP "\fB\-c\fR, \fB\-\-omit\-constant\fR" 5
+.IX Item "-c, --omit-constant"
+Omit \f(CWconstant()\fR from the .xs file and corresponding specialised
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR from the .pm file.
+.IP "\fB\-d\fR, \fB\-\-debugging\fR" 5
+.IX Item "-d, --debugging"
+Turn on debugging messages.
+.IP "\fB\-e\fR, \fB\-\-omit\-enums\fR=[\fIregular expression\fR]" 5
+.IX Item "-e, --omit-enums=[regular expression]"
+If \fIregular expression\fR is not given, skip all constants that are defined in
+a C enumeration. Otherwise skip only those constants that are defined in an
+enum whose name matches \fIregular expression\fR.
+.Sp
+Since \fIregular expression\fR is optional, make sure that this switch is followed
+by at least one other switch if you omit \fIregular expression\fR and have some
+pending arguments such as header-file names. This is ok:
+.Sp
+.Vb 1
+\&    h2xs \-e \-n Module::Foo foo.h
+.Ve
+.Sp
+This is not ok:
+.Sp
+.Vb 1
+\&    h2xs \-n Module::Foo \-e foo.h
+.Ve
+.Sp
+In the latter, foo.h is taken as \fIregular expression\fR.
+.IP "\fB\-f\fR, \fB\-\-force\fR" 5
+.IX Item "-f, --force"
+Allows an extension to be created for a header even if that header is
+not found in standard include directories.
+.IP "\fB\-g\fR, \fB\-\-global\fR" 5
+.IX Item "-g, --global"
+Include code for safely storing static data in the .xs file.
+Extensions that do no make use of static data can ignore this option.
+.IP "\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR" 5
+.IX Item "-h, -?, --help"
+Print the usage, help and version for this h2xs and exit.
+.IP "\fB\-k\fR, \fB\-\-omit\-const\-func\fR" 5
+.IX Item "-k, --omit-const-func"
+For function arguments declared as \f(CW\*(C`const\*(C'\fR, omit the const attribute in the
+generated XS code.
+.IP "\fB\-m\fR, \fB\-\-gen\-tied\-var\fR" 5
+.IX Item "-m, --gen-tied-var"
+\&\fBExperimental\fR: for each variable declared in the header file(s), declare
+a perl variable of the same name magically tied to the C variable.
+.IP "\fB\-n\fR, \fB\-\-name\fR=\fImodule_name\fR" 5
+.IX Item "-n, --name=module_name"
+Specifies a name to be used for the extension, e.g., \-n\ RPC::DCE
+.IP "\fB\-o\fR, \fB\-\-opaque\-re\fR=\fIregular expression\fR" 5
+.IX Item "-o, --opaque-re=regular expression"
+Use "opaque" data type for the C types matched by the regular
+expression, even if these types are \f(CW\*(C`typedef\*(C'\fR\-equivalent to types
+from typemaps.  Should not be used without \fB\-x\fR.
+.Sp
+This may be useful since, say, types which are \f(CW\*(C`typedef\*(C'\fR\-equivalent
+to integers may represent OS-related handles, and one may want to work
+with these handles in OO-way, as in \f(CW\*(C`$handle\->do_something()\*(C'\fR.
+Use \f(CW\*(C`\-o .\*(C'\fR if you want to handle all the \f(CW\*(C`typedef\*(C'\fRed types as opaque
+types.
+.Sp
+The type-to-match is whitewashed (except for commas, which have no
+whitespace before them, and multiple \f(CW\*(C`*\*(C'\fR which have no whitespace
+between them).
+.IP "\fB\-p\fR, \fB\-\-remove\-prefix\fR=\fIprefix\fR" 5
+.IX Item "-p, --remove-prefix=prefix"
+Specify a prefix which should be removed from the Perl function names,
+e.g., \-p\ sec_rgy_ This sets up the XS \fBPREFIX\fR keyword and removes
+the prefix from functions that are autoloaded via the \f(CWconstant()\fR
+mechanism.
+.IP "\fB\-s\fR, \fB\-\-const\-subs\fR=\fIsub1,sub2\fR" 5
+.IX Item "-s, --const-subs=sub1,sub2"
+Create a perl subroutine for the specified macros rather than autoload
+with the \fBconstant()\fR subroutine.  These macros are assumed to have a
+return type of \fBchar *\fR, e.g.,
+\&\-s\ sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
+.IP "\fB\-t\fR, \fB\-\-default\-type\fR=\fItype\fR" 5
+.IX Item "-t, --default-type=type"
+Specify the internal type that the \fBconstant()\fR mechanism uses for macros.
+The default is IV (signed integer).  Currently all macros found during the
+header scanning process will be assumed to have this type.  Future versions
+of \f(CW\*(C`h2xs\*(C'\fR may gain the ability to make educated guesses.
+.IP \fB\-\-use\-new\-tests\fR 5
+.IX Item "--use-new-tests"
+When \fB\-\-compat\-version\fR (\fB\-b\fR) is present the generated tests will use
+\&\f(CW\*(C`Test::More\*(C'\fR rather than \f(CW\*(C`Test\*(C'\fR which is the default for versions before
+5.6.2.  \f(CW\*(C`Test::More\*(C'\fR will be added to PREREQ_PM in the generated
+\&\f(CW\*(C`Makefile.PL\*(C'\fR.
+.IP \fB\-\-use\-old\-tests\fR 5
+.IX Item "--use-old-tests"
+Will force the generation of test code that uses the older \f(CW\*(C`Test\*(C'\fR module.
+.IP \fB\-\-skip\-exporter\fR 5
+.IX Item "--skip-exporter"
+Do not use \f(CW\*(C`Exporter\*(C'\fR and/or export any symbol.
+.IP \fB\-\-skip\-ppport\fR 5
+.IX Item "--skip-ppport"
+Do not use \f(CW\*(C`Devel::PPPort\*(C'\fR: no portability to older version.
+.IP \fB\-\-skip\-autoloader\fR 5
+.IX Item "--skip-autoloader"
+Do not use the module \f(CW\*(C`AutoLoader\*(C'\fR; but keep the \fBconstant()\fR function
+and \f(CW\*(C`sub AUTOLOAD\*(C'\fR for constants.
+.IP \fB\-\-skip\-strict\fR 5
+.IX Item "--skip-strict"
+Do not use the pragma \f(CW\*(C`strict\*(C'\fR.
+.IP \fB\-\-skip\-warnings\fR 5
+.IX Item "--skip-warnings"
+Do not use the pragma \f(CW\*(C`warnings\*(C'\fR.
+.IP "\fB\-v\fR, \fB\-\-version\fR=\fIversion\fR" 5
+.IX Item "-v, --version=version"
+Specify a version number for this extension.  This version number is added
+to the templates.  The default is 0.01, or 0.00_01 if \f(CW\*(C`\-B\*(C'\fR is specified.
+The version specified should be numeric.
+.IP "\fB\-x\fR, \fB\-\-autogen\-xsubs\fR" 5
+.IX Item "-x, --autogen-xsubs"
+Automatically generate XSUBs basing on function declarations in the
+header file.  The package \f(CW\*(C`C::Scan\*(C'\fR should be installed. If this
+option is specified, the name of the header file may look like
+\&\f(CW\*(C`NAME1,NAME2\*(C'\fR. In this case NAME1 is used instead of the specified
+string, but XSUBs are emitted only for the declarations included from
+file NAME2.
+.Sp
+Note that some types of arguments/return\-values for functions may
+result in XSUB\-declarations/typemap\-entries which need
+hand-editing. Such may be objects which cannot be converted from/to a
+pointer (like \f(CW\*(C`long long\*(C'\fR), pointers to functions, or arrays.  See
+also the section on "LIMITATIONS of \fB\-x\fR".
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 2
+\&    # Default behavior, extension is Rusers
+\&    h2xs rpcsvc/rusers
+\&
+\&    # Same, but extension is RUSERS
+\&    h2xs \-n RUSERS rpcsvc/rusers
+\&
+\&    # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
+\&    h2xs rpcsvc::rusers
+\&
+\&    # Extension is ONC::RPC.  Still finds <rpcsvc/rusers.h>
+\&    h2xs \-n ONC::RPC rpcsvc/rusers
+\&
+\&    # Without constant() or AUTOLOAD
+\&    h2xs \-c rpcsvc/rusers
+\&
+\&    # Creates templates for an extension named RPC
+\&    h2xs \-cfn RPC
+\&
+\&    # Extension is ONC::RPC.
+\&    h2xs \-cfn ONC::RPC
+\&
+\&    # Extension is a pure Perl module with no XS code.
+\&    h2xs \-X My::Module
+\&
+\&    # Extension is Lib::Foo which works at least with Perl5.005_03.
+\&    # Constants are created for all #defines and enums h2xs can find
+\&    # in foo.h.
+\&    h2xs \-b 5.5.3 \-n Lib::Foo foo.h
+\&
+\&    # Extension is Lib::Foo which works at least with Perl5.005_03.
+\&    # Constants are created for all #defines but only for enums
+\&    # whose names do not start with \*(Aqbar_\*(Aq.
+\&    h2xs \-b 5.5.3 \-e \*(Aq^bar_\*(Aq \-n Lib::Foo foo.h
+\&
+\&    # Makefile.PL will look for library \-lrpc in
+\&    # additional directory /opt/net/lib
+\&    h2xs rpcsvc/rusers \-L/opt/net/lib \-lrpc
+\&
+\&    # Extension is DCE::rgynbase
+\&    # prefix "sec_rgy_" is dropped from perl function names
+\&    h2xs \-n DCE::rgynbase \-p sec_rgy_ dce/rgynbase
+\&
+\&    # Extension is DCE::rgynbase
+\&    # prefix "sec_rgy_" is dropped from perl function names
+\&    # subroutines are created for sec_rgy_wildcard_name and
+\&    # sec_rgy_wildcard_sid
+\&    h2xs \-n DCE::rgynbase \-p sec_rgy_ \e
+\&    \-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase
+\&
+\&    # Make XS without defines in perl.h, but with function declarations
+\&    # visible from perl.h. Name of the extension is perl1.
+\&    # When scanning perl.h, define \-DEXT=extern \-DdEXT= \-DINIT(x)=
+\&    # Extra backslashes below because the string is passed to shell.
+\&    # Note that a directory with perl header files would
+\&    #  be added automatically to include path.
+\&    h2xs \-xAn perl1 \-F "\-DEXT=extern \-DdEXT= \-DINIT\e(x\e)=" perl.h
+\&
+\&    # Same with function declaration in proto.h as visible from perl.h.
+\&    h2xs \-xAn perl2 perl.h,proto.h
+\&
+\&    # Same but select only functions which match /^av_/
+\&    h2xs \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h
+\&
+\&    # Same but treat SV* etc as "opaque" types
+\&    h2xs \-o \*(Aq^[S]V \e*$\*(Aq \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h
+.Ve
+.SS "Extension based on \fI.h\fP and \fI.c\fP files"
+.IX Subsection "Extension based on .h and .c files"
+Suppose that you have some C files implementing some functionality,
+and the corresponding header files.  How to create an extension which
+makes this functionality accessible in Perl?  The example below
+assumes that the header files are \fIinterface_simple.h\fR and
+\&\fIinterface_hairy.h\fR, and you want the perl module be named as
+\&\f(CW\*(C`Ext::Ension\*(C'\fR.  If you need some preprocessor directives and/or
+linking with external libraries, see the flags \f(CW\*(C`\-F\*(C'\fR, \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR
+in "OPTIONS".
+.IP "Find the directory name" 4
+.IX Item "Find the directory name"
+Start with a dummy run of h2xs:
+.Sp
+.Vb 1
+\&  h2xs \-Afn Ext::Ension
+.Ve
+.Sp
+The only purpose of this step is to create the needed directories, and
+let you know the names of these directories.  From the output you can
+see that the directory for the extension is \fIExt/Ension\fR.
+.IP "Copy C files" 4
+.IX Item "Copy C files"
+Copy your header files and C files to this directory \fIExt/Ension\fR.
+.IP "Create the extension" 4
+.IX Item "Create the extension"
+Run h2xs, overwriting older autogenerated files:
+.Sp
+.Vb 1
+\&  h2xs \-Oxan Ext::Ension interface_simple.h interface_hairy.h
+.Ve
+.Sp
+h2xs looks for header files \fIafter\fR changing to the extension
+directory, so it will find your header files OK.
+.IP "Archive and test" 4
+.IX Item "Archive and test"
+As usual, run
+.Sp
+.Vb 5
+\&  cd Ext/Ension
+\&  perl Makefile.PL
+\&  make dist
+\&  make
+\&  make test
+.Ve
+.IP Hints 4
+.IX Item "Hints"
+It is important to do \f(CW\*(C`make dist\*(C'\fR as early as possible.  This way you
+can easily \fBmerge\fR\|(1) your changes to autogenerated files if you decide
+to edit your \f(CW\*(C`.h\*(C'\fR files and rerun h2xs.
+.Sp
+Do not forget to edit the documentation in the generated \fI.pm\fR file.
+.Sp
+Consider the autogenerated files as skeletons only, you may invent
+better interfaces than what h2xs could guess.
+.Sp
+Consider this section as a guideline only, some other options of h2xs
+may better suit your needs.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+No environment variables are used.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall and others
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perl, perlxstut, ExtUtils::MakeMaker, and AutoLoader.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+The usual warnings if it cannot read or write the files involved.
+.SH "LIMITATIONS of \fB\-x\fP"
+.IX Header "LIMITATIONS of -x"
+\&\fIh2xs\fR would not distinguish whether an argument to a C function
+which is of the form, say, \f(CW\*(C`int *\*(C'\fR, is an input, output, or
+input/output parameter.  In particular, argument declarations of the
+form
+.PP
+.Vb 3
+\&    int
+\&    foo(n)
+\&        int *n
+.Ve
+.PP
+should be better rewritten as
+.PP
+.Vb 3
+\&    int
+\&    foo(n)
+\&        int &n
+.Ve
+.PP
+if \f(CW\*(C`n\*(C'\fR is an input parameter.
+.PP
+Additionally, \fIh2xs\fR has no facilities to intuit that a function
+.PP
+.Vb 4
+\&   int
+\&   foo(addr,l)
+\&        char *addr
+\&        int   l
+.Ve
+.PP
+takes a pair of address and length of data at this address, so it is better
+to rewrite this function as
+.PP
+.Vb 11
+\&    int
+\&    foo(sv)
+\&            SV *addr
+\&        PREINIT:
+\&            STRLEN len;
+\&            char *s;
+\&        CODE:
+\&            s = SvPV(sv,len);
+\&            RETVAL = foo(s, len);
+\&        OUTPUT:
+\&            RETVAL
+.Ve
+.PP
+or alternately
+.PP
+.Vb 5
+\&    static int
+\&    my_foo(SV *sv)
+\&    {
+\&        STRLEN len;
+\&        char *s = SvPV(sv,len);
+\&
+\&        return foo(s, len);
+\&    }
+\&
+\&    MODULE = foo        PACKAGE = foo   PREFIX = my_
+\&
+\&    int
+\&    foo(sv)
+\&        SV *sv
+.Ve
+.PP
+See perlxs and perlxstut for additional details.
diff --git a/upstream/mageia-cauldron/man1/hdifftopam.1 b/upstream/mageia-cauldron/man1/hdifftopam.1
new file mode 100644
index 00000000..df6f94f8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hdifftopam.1
@@ -0,0 +1,72 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Hdifftopam User Manual" 0 "15 April 2002" "netpbm documentation"
+
+.SH NAME
+hdifftopam - convert horizontal difference image to original PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBhdifftopam\fP[\fIpamfile\fP]
+[\fB-pnm\fP]
+[\fB-verbose\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may
+use white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBhdifftopam\fP undoes what \fBpamtohdiff\fP does.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBhdifftopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-pnm\fP
+     This option tells \fBhdifftopam\fP to create a PNM image (i.e. PGM or
+     PPM).  Without it, \fBhdifftopam\fP creates a PAM image (with a
+     tuple type of "unhdiff").  If the PAM does not have the proper depth
+     to be a PGM or PPM (i.e. 1 or 3) and you specify \fB-pnm\fP,
+     \fBhdifftopam\fP fails.
+
+
+.TP
+\fB-verbose\fP
+     Print output image width, height, depth and maxval to standard error.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtohdiff" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Bryan Henderson
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/hdifftopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/head.1 b/upstream/mageia-cauldron/man1/head.1
new file mode 100644
index 00000000..4ba94d82
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/head.1
@@ -0,0 +1,65 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH HEAD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+head \- output the first part of files
+.SH SYNOPSIS
+.B head
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the first 10 lines of each FILE to standard output.
+With more than one FILE, precede each with a header giving the file name.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\-]NUM\/\fR
+print the first NUM bytes of each file;
+with the leading '\-', print all but the last
+NUM bytes of each file
+.TP
+\fB\-n\fR, \fB\-\-lines\fR=\fI\,[\-]NUM\/\fR
+print the first NUM lines instead of the first 10;
+with the leading '\-', print all but the last
+NUM lines of each file
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+never print headers giving file names
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+always print headers giving file names
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NUM may have a multiplier suffix:
+b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,
+GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.SH AUTHOR
+Written by David MacKenzie and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBtail\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/head>
+.br
+or available locally via: info \(aq(coreutils) head invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/hipstopgm.1 b/upstream/mageia-cauldron/man1/hipstopgm.1
new file mode 100644
index 00000000..d650eab8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hipstopgm.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Hipstopgm User Manual" 0 "24 August 89" "netpbm documentation"
+
+.SH NAME
+hipstopgm - convert a HIPS file into a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBhipstopgm\fP
+[\fIhipsfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBhipstopgm\fP reads a HIPS file as input and produces a PGM
+image as output.
+.PP
+If the HIPS file contains more than one frame in sequence,
+\fBhipstopgm\fP will concatenate all the frames vertically.
+.PP
+HIPS is a format developed at the Human Information Processing
+Laboratory, NYU.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBhipstopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/hipstopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/homectl.1 b/upstream/mageia-cauldron/man1/homectl.1
new file mode 100644
index 00000000..db58c946
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/homectl.1
@@ -0,0 +1,1371 @@
+'\" t
+.TH "HOMECTL" "1" "" "systemd 255" "homectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+homectl \- Create, remove, change or inspect home directories
+.SH "SYNOPSIS"
+.HP \w'\fBhomectl\fR\ 'u
+\fBhomectl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBhomectl\fR
+may be used to create, remove, change or inspect a user\*(Aqs home directory\&. It\*(Aqs primarily a command interfacing with
+\fBsystemd-homed.service\fR(8)
+which manages home directories of users\&.
+.PP
+Home directories managed by
+systemd\-homed\&.service
+are self\-contained, and thus include the user\*(Aqs full metadata record in the home\*(Aqs data storage itself, making them easy to migrate between machines\&. In particular, a home directory describes a matching user record, and every user record managed by
+systemd\-homed\&.service
+also implies existence and encapsulation of a home directory\&. The user account and home directory become the same concept\&.
+.PP
+The following backing storage mechanisms are supported:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+An individual LUKS2 encrypted loopback file for a user, stored in
+/home/*\&.home\&. At login the file system contained in this files is mounted, after the LUKS2 encrypted volume has been attached\&. The user\*(Aqs password is identical to the encryption passphrase of the LUKS2 volume\&. Access to data without preceding user authentication is thus not possible, even for the system administrator\&. This storage mechanism provides the strongest data security and is thus recommended\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Similar, but the LUKS2 encrypted file system is located on regular block device, such as a USB storage stick\&. In this mode home directories and all data they include are nicely migratable between machines, simply by plugging the USB stick into different systems at different times\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+An encrypted directory using
+"fscrypt"
+on file systems that support it (at the moment this is primarily
+"ext4"), located in
+/home/*\&.homedir\&. This mechanism also provides encryption, but substantially weaker than LUKS2, as most file system metadata is unprotected\&. Moreover it currently does not support changing user passwords once the home directory has been created\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A
+"btrfs"
+subvolume for each user, also located in
+/home/*\&.homedir\&. This provides no encryption, but good quota support\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A regular directory for each user, also located in
+/home/*\&.homedir\&. This provides no encryption, but is a suitable fallback available on all machines, even where LUKS2,
+"fscrypt"
+or
+"btrfs"
+support is not available\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+An individual Windows file share (CIFS) for each user\&.
+.RE
+.PP
+Note that
+systemd\-homed\&.service
+and
+\fBhomectl\fR
+will not manage "classic" UNIX user accounts as created with
+\fBuseradd\fR(8)
+or similar tools\&. In particular, this functionality is not suitable for managing system users (i\&.e\&. users with a UID below 1000) but is exclusive to regular ("human") users\&.
+.PP
+Note that users/home directories managed via
+\fBsystemd\-homed\&.service\fR
+do not show up in
+/etc/passwd
+and similar files, they are synthesized via glibc NSS during runtime\&. They are thus resolvable and may be enumerated via the
+\fBgetent\fR(1)
+tool\&.
+.PP
+This tool interfaces directly with
+systemd\-homed\&.service, and may execute specific commands on the home directories it manages\&. Since every home directory managed that way also defines a JSON user and group record these home directories may also be inspected and enumerated via
+\fBuserdbctl\fR(1)\&.
+.PP
+Home directories managed by
+systemd\-homed\&.service
+are usually in one of two states, or in a transition state between them: when
+"active"
+they are unlocked and mounted, and thus accessible to the system and its programs; when
+"inactive"
+they are not mounted and thus not accessible\&. Activation happens automatically at login of the user and usually can only complete after a password (or other authentication token) has been supplied\&. Deactivation happens after the user fully logged out\&. A home directory remains active as long as the user is logged in at least once, i\&.e\&. has at least one login session\&. When the user logs in a second time simultaneously the home directory remains active\&. It is deactivated only after the last of the user\*(Aqs sessions ends\&.
+.SH "OPTIONS"
+.PP
+The following general options are understood (further options that control the various properties of user records managed by
+systemd\-homed\&.service
+are documented further down):
+.PP
+\fB\-\-identity=\fR\fIFILE\fR
+.RS 4
+Read the user\*(Aqs JSON record from the specified file\&. If passed as
+"\-"
+read the user record from standard input\&. The supplied JSON object must follow the structure documented in
+\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2\&. This option may be used in conjunction with the
+\fBcreate\fR
+and
+\fBupdate\fR
+commands (see below), where it allows configuring the user record in JSON as\-is, instead of setting the individual user record properties (see below)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIFORMAT\fR, \fB\-j\fR
+.RS 4
+Controls whether to output the user record in JSON format, if the
+\fBinspect\fR
+command (see below) is used\&. Takes one of
+"pretty",
+"short"
+or
+"off"\&. If
+"pretty"
+human\-friendly whitespace and newlines are inserted in the output to make the JSON data more readable\&. If
+"short"
+all superfluous whitespace is suppressed\&. If
+"off"
+(the default) the user information is not shown in JSON format but in a friendly human readable formatting instead\&. The
+\fB\-j\fR
+option picks
+"pretty"
+when run interactively and
+"short"
+otherwise\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-export\-format=\fR\fIFORMAT\fR, \fB\-E\fR, \fB\-EE\fR
+.RS 4
+When used with the
+\fBinspect\fR
+verb in JSON mode (see above) may be used to suppress certain aspects of the JSON user record on output\&. Specifically, if
+"stripped"
+format is used the binding and runtime fields of the record are removed\&. If
+"minimal"
+format is used the cryptographic signature is removed too\&. If
+"full"
+format is used the full JSON record is shown (this is the default)\&. This option is useful for copying an existing user record to a different system in order to create a similar user there with the same settings\&. Specifically:
+\fBhomectl inspect \-EE | ssh root@othersystem homectl create \-i\-\fR
+may be used as simple command line for replicating a user on another host\&.
+\fB\-E\fR
+is equivalent to
+\fB\-j \-\-export\-format=stripped\fR,
+\fB\-EE\fR
+to
+\fB\-j \-\-export\-format=minimal\fR\&. Note that when replicating user accounts user records acquired in
+"stripped"
+mode will retain the original cryptographic signatures and thus may only be modified when the private key to update them is available on the destination machine\&. When replicating users in
+"minimal"
+mode, the signature is removed during the replication and thus the record will be implicitly signed with the key of the destination machine and may be updated there without any private key replication\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "USER RECORD PROPERTIES"
+.PP
+The following options control various properties of the user records/home directories that
+systemd\-homed\&.service
+manages\&. These switches may be used in conjunction with the
+\fBcreate\fR
+and
+\fBupdate\fR
+commands for configuring various aspects of the home directory and the user account:
+.PP
+\fB\-\-real\-name=\fR\fINAME\fR, \fB\-c\fR \fINAME\fR
+.RS 4
+The real name for the user\&. This corresponds with the GECOS field on classic UNIX NSS records\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-realm=\fR\fIREALM\fR
+.RS 4
+The realm for the user\&. The realm associates a user with a specific organization or installation, and allows distinguishing users of the same name defined in different contexts\&. The realm can be any string that also qualifies as valid DNS domain name, and it is recommended to use the organization\*(Aqs or installation\*(Aqs domain name for this purpose, but this is not enforced nor required\&. On each system only a single user of the same name may exist, and if a user with the same name and realm is seen it is assumed to refer to the same user while a user with the same name but different realm is considered a different user\&. Note that this means that two users sharing the same name but with distinct realms are not allowed on the same system\&. Assigning a realm to a user is optional\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-email\-address=\fR\fIEMAIL\fR
+.RS 4
+Takes an electronic mail address to associate with the user\&. On log\-in the
+\fI$EMAIL\fR
+environment variable is initialized from this value\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-location=\fR\fITEXT\fR
+.RS 4
+Takes location specification for this user\&. This is free\-form text, which might or might not be usable by geo\-location applications\&. Example:
+\fB\-\-location="Berlin, Germany"\fR
+or
+\fB\-\-location="Basement, Room 3a"\fR
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-icon\-name=\fR\fIICON\fR
+.RS 4
+Takes an icon name to associate with the user, following the scheme defined by the
+\m[blue]\fBIcon Naming Specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-home\-dir=\fR\fIPATH\fR, \fB\-d\fR\fIPATH\fR
+.RS 4
+Takes a path to use as home directory for the user\&. Note that this is the directory the user\*(Aqs home directory is mounted to while the user is logged in\&. This is not where the user\*(Aqs data is actually stored, see
+\fB\-\-image\-path=\fR
+for that\&. If not specified defaults to
+/home/$USER\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-uid=\fR\fIUID\fR
+.RS 4
+Takes a preferred numeric UNIX UID to assign this user\&. If a user is to be created with the specified UID and it is already taken by a different user on the local system then creation of the home directory is refused\&. Note though, if after creating the home directory it is used on a different system and the configured UID is taken by another user there, then
+\fBsystemd\-homed\fR
+may assign the user a different UID on that system\&. The specified UID must be outside of the system user range\&. It is recommended to use the 60001\&...60513 UID range for this purpose\&. If not specified, the UID is automatically picked\&. If the home directory is found to be owned by a different UID when logging in, the home directory and everything underneath it will have its ownership changed automatically before login completes\&.
+.sp
+Note that changing this option for existing home directories generally has no effect on home directories that already have been registered locally (have a local
+\fIbinding\fR), as the UID used for an account on the local system is determined when the home directory is first activated on it, and then remains in effect until the home directory is removed\&.
+.sp
+Note that users managed by
+\fBsystemd\-homed\fR
+always have a matching group associated with the same name as well as a GID matching the UID of the user\&. Thus, configuring the GID separately is not permitted\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-member\-of=\fR\fIGROUP\fR, \fB\-G\fR \fIGROUP\fR
+.RS 4
+Takes a comma\-separated list of auxiliary UNIX groups this user shall belong to\&. Example:
+\fB\-\-member\-of=wheel\fR
+to provide the user with administrator privileges\&. Note that
+\fBsystemd\-homed\fR
+does not manage any groups besides a group matching the user in name and numeric UID/GID\&. Thus any groups listed here must be registered independently, for example with
+\fBgroupadd\fR(8)\&. Any non\-existent groups are ignored\&. This option may be used more than once, in which case all specified group lists are combined\&. If the user is currently a member of a group which is not listed, the user will be removed from the group\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-capability\-bounding\-set=\fR\fICAPABILITIES\fR, \fB\-\-capability\-ambient\-set=\fR\fICAPABILITIES\fR
+.RS 4
+These options take a space separated list of process capabilities (e\&.g\&.
+\fBCAP_WAKE_ALARM\fR,
+\fBCAP_BLOCK_SUSPEND\fR, \&...) that shall be set in the capability bounding and ambient sets for all the user\*(Aqs sessions\&. See
+\fBcapabilities\fR(7)
+for details on the capabilities concept\&. These options may be used more than once, in which case the specified lists are combined\&. If the parameter begins with a
+"~"
+character the effect is inverted: the specified capability is dropped from the specific set\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-skel=\fR\fIPATH\fR
+.RS 4
+Takes a file system path to a directory\&. Specifies the skeleton directory to initialize the home directory with\&. All files and directories in the specified path are copied into any newly create home directory\&. If not specified defaults to
+/etc/skel/\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-shell=\fR\fISHELL\fR
+.RS 4
+Takes a file system path\&. Specifies the shell binary to execute on terminal logins\&. If not specified defaults to
+/bin/bash\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-setenv=\fR\fIVARIABLE\fR[=\fIVALUE\fR]
+.RS 4
+Takes an environment variable assignment to set for all user processes\&. May be used multiple times to set multiple environment variables\&. When
+"="
+and
+\fIVALUE\fR
+are omitted, the value of the variable with the same name in the program environment will be used\&.
+.sp
+Note that a number of other settings also result in environment variables to be set for the user, including
+\fB\-\-email=\fR,
+\fB\-\-timezone=\fR
+and
+\fB\-\-language=\fR\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-timezone=\fR\fITIMEZONE\fR
+.RS 4
+Takes a time zone location name that sets the timezone for the specified user\&. When the user logs in the
+\fI$TZ\fR
+environment variable is initialized from this setting\&. Example:
+\fB\-\-timezone=Europe/Amsterdam\fR
+will result in the environment variable
+"TZ=:Europe/Amsterdam"\&. (":"
+is used intentionally as part of the timezone specification, see
+\fBtzset\fR(3)\&.)
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-language=\fR\fILANG\fR
+.RS 4
+Takes a specifier indicating the preferred language of the user\&. The
+\fI$LANG\fR
+environment variable is initialized from this value on login, and thus a value suitable for this environment variable is accepted here, for example
+\fB\-\-language=de_DE\&.UTF8\fR\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-ssh\-authorized\-keys=\fR\fIKEYS\fR
+.RS 4
+Either takes a SSH authorized key line to associate with the user record or a
+"@"
+character followed by a path to a file to read one or more such lines from\&. SSH keys configured this way are made available to SSH to permit access to this home directory and user record\&. This option may be used more than once to configure multiple SSH keys\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-pkcs11\-token\-uri=\fR\fIURI\fR
+.RS 4
+Takes an RFC 7512 PKCS#11 URI referencing a security token (e\&.g\&. YubiKey or PIV smartcard) that shall be able to unlock the user account\&. The security token URI should reference a security token with exactly one pair of X\&.509 certificate and private key\&. A random secret key is then generated, encrypted with the public key of the X\&.509 certificate, and stored as part of the user record\&. At login time it is decrypted with the PKCS#11 module and then used to unlock the account and associated resources\&. See below for an example how to set up authentication with a security token\&.
+.sp
+Instead of a valid PKCS#11 URI, the special strings
+"list"
+and
+"auto"
+may be specified\&. If
+"list"
+is passed, a brief table of suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs\&. If
+"auto"
+is passed, a suitable PKCS#11 hardware token is automatically selected (this operation will fail if there isn\*(Aqt exactly one suitable token discovered)\&. The latter is a useful shortcut for the most common case where a single PKCS#11 hardware token is plugged in\&.
+.sp
+Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the
+"hmac\-secret"
+extension (for example: the YubiKey 5 series), as supported with the
+\fB\-\-fido2\-device=\fR
+option below\&. Both mechanisms are similarly powerful, though FIDO2 is the more modern technology\&. PKCS#11/PIV tokens have the benefit of being recognizable before authentication and hence can be used for implying the user identity to use for logging in, which FIDO2 does not allow\&. PKCS#11/PIV devices generally require initialization (i\&.e\&. storing a private/public key pair on them, see example below) before they can be used; FIDO2 security tokens generally do not required that, and work out of the box\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-fido2\-credential\-algorithm=\fR\fISTRING\fR
+.RS 4
+Specify COSE algorithm used in credential generation\&. The default value is
+"es256"\&. Supported values are
+"es256",
+"rs256"
+and
+"eddsa"\&.
+.sp
+"es256"
+denotes ECDSA over NIST P\-256 with SHA\-256\&.
+"rs256"
+denotes 2048\-bit RSA with PKCS#1\&.5 padding and SHA\-256\&.
+"eddsa"
+denotes EDDSA over Curve25519 with SHA\-512\&.
+.sp
+Note that your authenticator may not support some algorithms\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-fido2\-device=\fR\fIPATH\fR
+.RS 4
+Takes a path to a Linux
+"hidraw"
+device (e\&.g\&.
+/dev/hidraw1), referring to a FIDO2 security token implementing the
+"hmac\-secret"
+extension that shall be able to unlock the user account\&. A random salt value is generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the salt using an internal secret key\&. The result is then used as the key to unlock the user account\&. The random salt is included in the user record, so that whenever authentication is needed it can be passed to the FIDO2 token again\&.
+.sp
+Instead of a valid path to a FIDO2
+"hidraw"
+device the special strings
+"list"
+and
+"auto"
+may be specified\&. If
+"list"
+is passed, a brief table of suitable discovered FIDO2 devices is shown\&. If
+"auto"
+is passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered\&. The latter is a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in\&.
+.sp
+Note that FIDO2 devices suitable for this option must implement the
+"hmac\-secret"
+extension\&. Most current devices (such as the YubiKey 5 series) do\&. If the extension is not implemented the device cannot be used for unlocking home directories\&.
+.sp
+The FIDO2 device may be subsequently removed by setting the device path to an empty string (e\&.g\&.
+\fBhomectl update $USER \-\-fido2\-device=""\fR)\&.
+.sp
+Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be used with either
+\fB\-\-fido2\-device=\fR
+or
+\fB\-\-pkcs11\-token\-uri=\fR), for a discussion see above\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-client\-pin=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require the user to enter a PIN when unlocking the account (the FIDO2
+"clientPin"
+feature)\&. Defaults to
+"yes"\&. (Note: this setting is without effect if the security token does not support the
+"clientPin"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-user\-presence=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require the user to verify presence (tap the token, the FIDO2
+"up"
+feature) when unlocking the account\&. Defaults to
+"yes"\&. (Note: this setting is without effect if the security token does not support the
+"up"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-user\-verification=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require user verification when unlocking the account (the FIDO2
+"uv"
+feature)\&. Defaults to
+"no"\&. (Note: this setting is without effect if the security token does not support the
+"uv"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-recovery\-key=\fR\fIBOOL\fR
+.RS 4
+Accepts a boolean argument\&. If enabled a recovery key is configured for the account\&. A recovery key is a computer generated access key that may be used to regain access to an account if the password has been forgotten or the authentication token lost\&. The key is generated and shown on screen, and should be printed or otherwise transferred to a secure location\&. A recovery key may be entered instead of a regular password to unlock the account\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-locked=\fR\fIBOOLEAN\fR
+.RS 4
+Takes a boolean argument\&. Specifies whether this user account shall be locked\&. If true logins into this account are prohibited, if false (the default) they are permitted (of course, only if authorization otherwise succeeds)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-not\-before=\fR\fITIMESTAMP\fR, \fB\-\-not\-after=\fR\fITIMESTAMP\fR
+.RS 4
+These options take a timestamp string, in the format documented in
+\fBsystemd.time\fR(7)
+and configures points in time before and after logins into this account are not permitted\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-rate\-limit\-interval=\fR\fISECS\fR, \fB\-\-rate\-limit\-burst=\fR\fINUMBER\fR
+.RS 4
+Configures a rate limit on authentication attempts for this user\&. If the user attempts to authenticate more often than the specified number, on a specific system, within the specified time interval authentication is refused until the time interval passes\&. Defaults to 10 times per 1min\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-password\-hint=\fR\fITEXT\fR
+.RS 4
+Takes a password hint to store alongside the user record\&. This string is stored accessible only to privileged users and the user itself and may not be queried by other users\&. Example:
+\fB\-\-password\-hint="My first pet\*(Aqs name"\fR\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-enforce\-password\-policy=\fR\fIBOOL\fR, \fB\-P\fR
+.RS 4
+Takes a boolean argument\&. Configures whether to enforce the system\*(Aqs password policy for this user, regarding quality and strength of selected passwords\&. Defaults to on\&.
+\fB\-P\fR
+is short for
+\fB\-\-\-enforce\-password\-policy=no\fR\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-password\-change\-now=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean argument\&. If true the user is asked to change their password on next login\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-password\-change\-min=\fR\fITIME\fR, \fB\-\-password\-change\-max=\fR\fITIME\fR, \fB\-\-password\-change\-warn=\fR\fITIME\fR, \fB\-\-password\-change\-inactive=\fR\fITIME\fR
+.RS 4
+Each of these options takes a time span specification as argument (in the syntax documented in
+\fBsystemd.time\fR(7)) and configures various aspects of the user\*(Aqs password expiration policy\&. Specifically,
+\fB\-\-password\-change\-min=\fR
+configures how much time has to pass after changing the password of the user until the password may be changed again\&. If the user tries to change their password before this time passes the attempt is refused\&.
+\fB\-\-password\-change\-max=\fR
+configures how soon after it has been changed the password expires and needs to be changed again\&. After this time passes logging in may only proceed after the password is changed\&.
+\fB\-\-password\-change\-warn=\fR
+specifies how much earlier than then the time configured with
+\fB\-\-password\-change\-max=\fR
+the user is warned at login to change their password as it will expire soon\&. Finally
+\fB\-\-password\-change\-inactive=\fR
+configures the time which has to pass after the password as expired until the user is not permitted to log in or change the password anymore\&. Note that these options only apply to password authentication, and do not apply to other forms of authentication, for example PKCS#11\-based security token authentication\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-disk\-size=\fR\fIBYTES\fR
+.RS 4
+Either takes a size in bytes as argument (possibly using the usual K, M, G, \&... suffixes for 1024 base values), a percentage value, or the special strings
+"min"
+or
+"max", and configures the disk space to assign to the user\&. If a percentage value is specified (i\&.e\&. the argument suffixed with
+"%") it is taken relative to the available disk space of the backing file system\&. If specified as
+"min"
+assigns the minimal disk space permitted by the constraints of the backing file system and other limits, when specified as
+"max"
+assigns the maximum disk space available\&. If the LUKS2 backend is used this configures the size of the loopback file and file system contained therein\&. For the other storage backends configures disk quota using the filesystem\*(Aqs native quota logic, if available\&. If not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for the others\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-access\-mode=\fR\fIMODE\fR
+.RS 4
+Takes a UNIX file access mode written in octal\&. Configures the access mode of the home directory itself\&. Note that this is only used when the directory is first created, and the user may change this any time afterwards\&. Example:
+\fB\-\-access\-mode=0700\fR
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-umask=\fR\fIMASK\fR
+.RS 4
+Takes the access mode mask (in octal syntax) to apply to newly created files and directories of the user ("umask")\&. If set this controls the initial umask set for all login sessions of the user, possibly overriding the system\*(Aqs defaults\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-nice=\fR\fINICE\fR
+.RS 4
+Takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login time\&. Takes a numeric value in the range \-20 (highest priority) to 19 (lowest priority)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-rlimit=\fR\fILIMIT\fR=\fIVALUE\fR[:\fIVALUE\fR]
+.RS 4
+Allows configuration of resource limits for processes of this user, see
+\fBgetrlimit\fR(2)
+for details\&. Takes a resource limit name (e\&.g\&.
+"LIMIT_NOFILE") followed by an equal sign, followed by a numeric limit\&. Optionally, separated by colon a second numeric limit may be specified\&. If two are specified this refers to the soft and hard limits, respectively\&. If only one limit is specified the setting sets both limits in one\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-tasks\-max=\fR\fITASKS\fR
+.RS 4
+Takes a non\-zero unsigned integer as argument\&. Configures the maximum number of tasks (i\&.e\&. threads, where each process is at least one thread) the user may have at any given time\&. This limit applies to all tasks forked off the user\*(Aqs sessions, even if they change user identity via
+\fBsu\fR(1)
+or a similar tool\&. Use
+\fB\-\-rlimit=LIMIT_NPROC=\fR
+to place a limit on the tasks actually running under the UID of the user, thus excluding any child processes that might have changed user identity\&. This controls the
+\fITasksMax=\fR
+setting of the per\-user systemd slice unit
+user\-$UID\&.slice\&. See
+\fBsystemd.resource-control\fR(5)
+for further details\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-memory\-high=\fR\fIBYTES\fR, \fB\-\-memory\-max=\fR\fIBYTES\fR
+.RS 4
+Set a limit on the memory a user may take up on a system at any given time in bytes (the usual K, M, G, \&... suffixes are supported, to the base of 1024)\&. This includes all memory used by the user itself and all processes they forked off that changed user credentials\&. This controls the
+\fIMemoryHigh=\fR
+and
+\fIMemoryMax=\fR
+settings of the per\-user systemd slice unit
+user\-$UID\&.slice\&. See
+\fBsystemd.resource-control\fR(5)
+for further details\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-cpu\-weight=\fR\fIWEIGHT\fR, \fB\-\-io\-weight=\fR\fIWEIGHT\fR
+.RS 4
+Set CPU and IO scheduling weights of the processes of the user, including those of processes forked off by the user that changed user credentials\&. Takes a numeric value in the range 1\&...10000\&. This controls the
+\fICPUWeight=\fR
+and
+\fIIOWeight=\fR
+settings of the per\-user systemd slice unit
+user\-$UID\&.slice\&. See
+\fBsystemd.resource-control\fR(5)
+for further details\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-storage=\fR\fISTORAGE\fR
+.RS 4
+Selects the storage mechanism to use for this home directory\&. Takes one of
+"luks",
+"fscrypt",
+"directory",
+"subvolume",
+"cifs"\&. For details about these mechanisms, see above\&. If a new home directory is created and the storage type is not specifically specified,
+\fBhomed.conf\fR(5)
+defines which default storage to use\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-image\-path=\fR\fIPATH\fR
+.RS 4
+Takes a file system path\&. Configures where to place the user\*(Aqs home directory\&. When LUKS2 storage is used refers to the path to the loopback file, otherwise to the path to the home directory (which may be in
+/home/
+or any other accessible filesystem)\&. When unspecified defaults to
+/home/$USER\&.home
+when LUKS storage is used and
+/home/$USER\&.homedir
+for the other storage mechanisms\&. Not defined for the
+"cifs"
+storage mechanism\&. To use LUKS2 storage on a regular block device (for example a USB stick) pass the path to the block device here\&. Specifying the path to a directory here when using LUKS2 storage is not allowed\&. Similar, specifying the path to a regular file or device node is not allowed if any of the other storage backends are used\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-drop\-caches=\fR\fIBOOL\fR
+.RS 4
+Automatically flush OS file system caches on logout\&. This is useful in combination with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and directories in memory (and accessible) after logout\&. This option is also supported on other backends, but should not bring any benefit there\&. Defaults to off, except if the selected storage backend is fscrypt, where it defaults to on\&. Note that flushing OS caches will negatively influence performance of the OS shortly after logout\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-fs\-type=\fR\fITYPE\fR
+.RS 4
+When LUKS2 storage is used configures the file system type to use inside the home directory LUKS2 container\&. One of
+"btrfs",
+"ext4",
+"xfs"\&. If not specified
+\fBhomed.conf\fR(5)
+defines which default file system type to use\&. Note that
+"xfs"
+is not recommended as its support for file system resizing is too limited\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-luks\-discard=\fR\fIBOOL\fR
+.RS 4
+When LUKS2 storage is used configures whether to enable the
+"discard"
+feature of the file system\&. If enabled the file system on top of the LUKS2 volume will report empty block information to LUKS2 and the loopback file below, ensuring that empty space in the home directory is returned to the backing file system below the LUKS2 volume, resulting in a "sparse" loopback file\&. This option mostly defaults to off, since this permits over\-committing home directories which results in I/O errors if the underlying file system runs full while the upper file system wants to allocate a block\&. Such I/O errors are generally not handled well by file systems nor applications\&. When LUKS2 storage is used on top of regular block devices (instead of on top a loopback file) the discard logic defaults to on\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-luks\-offline\-discard=\fR\fIBOOL\fR
+.RS 4
+Similar to
+\fB\-\-luks\-discard=\fR, controls the trimming of the file system\&. However, while
+\fB\-\-luks\-discard=\fR
+controls what happens when the home directory is active,
+\fB\-\-luks\-offline\-discard=\fR
+controls what happens when it becomes inactive, i\&.e\&. whether to trim/allocate the storage when deactivating the home directory\&. This option defaults to on, to ensure disk space is minimized while a user is not logged in\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-luks\-extra\-mount\-options=\fR\fIOPTIONS\fR
+.RS 4
+Takes a string containing additional mount options to use when mounting the LUKS volume\&. If specified, this string will be appended to the default, built\-in mount options\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-luks\-cipher=\fR\fICIPHER\fR, \fB\-\-luks\-cipher\-mode=\fR\fIMODE\fR, \fB\-\-luks\-volume\-key\-size=\fR\fIBYTES\fR, \fB\-\-luks\-pbkdf\-type=\fR\fITYPE\fR, \fB\-\-luks\-pbkdf\-hash\-algorithm=\fR\fIALGORITHM\fR, \fB\-\-luks\-pbkdf\-force\-iterations=\fR\fIITERATIONS\fR, \fB\-\-luks\-pbkdf\-time\-cost=\fR\fISECONDS\fR, \fB\-\-luks\-pbkdf\-memory\-cost=\fR\fIBYTES\fR, \fB\-\-luks\-pbkdf\-parallel\-threads=\fR\fITHREADS\fR, \fB\-\-luks\-sector\-size=\fR\fIBYTES\fR
+.RS 4
+Configures various cryptographic parameters for the LUKS2 storage mechanism\&. See
+\fBcryptsetup\fR(8)
+for details on the specific attributes\&.
+.sp
+Note that
+\fBhomectl\fR
+uses bytes for key size, like
+/proc/crypto, but
+\fBcryptsetup\fR(8)
+uses bits\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-auto\-resize\-mode=\fR
+.RS 4
+Configures whether to automatically grow and/or shrink the backing file system on login and logout\&. Takes one of the strings
+"off",
+"grow",
+"shrink\-and\-grow"\&. Only applies to the LUKS2 backend currently, and if the btrfs file system is used inside it (since only then online growing/shrinking of the file system is supported)\&. Defaults to
+"shrink\-and\-grow", if LUKS2/btrfs is used, otherwise is off\&. If set to
+"off"
+no automatic shrinking/growing during login or logout is done\&. If set to
+"grow"
+the home area is grown to the size configured via
+\fB\-\-disk\-size=\fR
+should it currently be smaller\&. If it already matches the configured size or is larger no operation is executed\&. If set to
+"shrink\-and\-grow"
+the home area is also resized during logout to the minimal size the used disk space and file system constraints permit\&. This mode thus ensures that while a home area is activated it is sized to the configured size, but while deactivated it is compacted taking up only the minimal space possible\&. Note that if the system is powered off abnormally or if the user otherwise not logged out cleanly the shrinking operation will not take place, and the user has to re\-login/logout again before it is executed again\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-rebalance\-weight=\fR
+.RS 4
+Configures the weight parameter for the free disk space rebalancing logic\&. Only applies to the LUKS2 backend (since for the LUKS2 backend disk space is allocated from a per\-user loopback file system instead of immediately from a common pool like the other backends do it)\&. In regular intervals free disk space in the active home areas and their backing storage is redistributed among them, taking the weight value configured here into account\&. Expects an integer in the range 1\&...10000, or the special string
+"off"\&. If not specified defaults to 100\&. The weight is used to scale free space made available to the home areas: a home area with a weight of 200 will get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half of that\&. The backing file system will be assigned space for a weight of 20\&. If set to
+"off"
+no automatic free space distribution is done for this home area\&. Note that resizing the home area explicitly (with
+\fBhomectl resize\fR
+see below) will implicitly turn off the automatic rebalancing\&. To reenable the automatic rebalancing use
+\fB\-\-rebalance\-weight=\fR
+with an empty parameter\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-nosuid=\fR\fIBOOL\fR, \fB\-\-nodev=\fR\fIBOOL\fR, \fB\-\-noexec=\fR\fIBOOL\fR
+.RS 4
+Configures the
+"nosuid",
+"nodev"
+and
+"noexec"
+mount options for the home directories\&. By default
+"nodev"
+and
+"nosuid"
+are on, while
+"noexec"
+is off\&. For details about these mount options see
+\fBmount\fR(8)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-cifs\-domain=\fR\fIDOMAIN\fR, \fB\-\-cifs\-user\-name=\fR\fIUSER\fR, \fB\-\-cifs\-service=\fR\fISERVICE\fR, \fB\-\-cifs\-extra\-mount\-options=\fR\fIOPTIONS\fR
+.RS 4
+Configures the Windows File Sharing (CIFS) domain and user to associate with the home directory/user account, as well as the file share ("service") to mount as directory\&. The latter is used when
+"cifs"
+storage is selected\&. The file share should be specified in format
+"//\fIhost\fR/\fIshare\fR/\fIdirectory/\&...\fR"\&. The directory part is optional \(em if not specified the home directory will be placed in the top\-level directory of the share\&. The
+\fB\-\-cifs\-extra\-mount\-options=\fR
+setting allows specifying additional mount options when mounting the share, see
+\fBmount.cifs\fR(8)
+for details\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-stop\-delay=\fR\fISECS\fR
+.RS 4
+Configures the time the per\-user service manager shall continue to run after the all sessions of the user ended\&. The default is configured in
+\fBlogind.conf\fR(5)
+(for home directories of LUKS2 storage located on removable media this defaults to 0 though)\&. A longer time makes sure quick, repetitive logins are more efficient as the user\*(Aqs service manager doesn\*(Aqt have to be started every time\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-kill\-processes=\fR\fIBOOL\fR
+.RS 4
+Configures whether to kill all processes of the user on logout\&. The default is configured in
+\fBlogind.conf\fR(5)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-auto\-login=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean argument\&. Configures whether the graphical UI of the system should automatically log this user in if possible\&. Defaults to off\&. If less or more than one user is marked this way automatic login is disabled\&.
+.sp
+Added in version 245\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR
+.RS 4
+List all home directories (along with brief details) currently managed by
+systemd\-homed\&.service\&. This command is also executed if none is specified on the command line\&. (Note that the list of users shown by this command does not include users managed by other subsystems, such as system users or any traditional users listed in
+/etc/passwd\&.)
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBactivate\fR \fIUSER\fR [\fIUSER\&...\fR]
+.RS 4
+Activate one or more home directories\&. The home directories of each listed user will be activated and made available under their mount points (typically in
+/home/$USER)\&. Note that any home activated this way stays active indefinitely, until it is explicitly deactivated again (with
+\fBdeactivate\fR, see below), or the user logs in and out again and it thus is deactivated due to the automatic deactivation\-on\-logout logic\&.
+.sp
+Activation of a home directory involves various operations that depend on the selected storage mechanism\&. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file system, mounting the file system, and potentially changing the ownership of all included files to the correct UID/GID\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBdeactivate\fR \fIUSER\fR [\fIUSER\&...\fR]
+.RS 4
+Deactivate one or more home directories\&. This undoes the effect of
+\fBactivate\fR\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBinspect\fR \fIUSER\fR [\fIUSER\&...\fR]
+.RS 4
+Show various details about the specified home directories\&. This shows various information about the home directory and its user account, including runtime data such as current state, disk use and similar\&. Combine with
+\fB\-\-json=\fR
+to show the detailed JSON user record instead, possibly combined with
+\fB\-\-export\-format=\fR
+to suppress certain aspects of the output\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBauthenticate\fR \fIUSER\fR [\fIUSER\&...\fR]
+.RS 4
+Validate authentication credentials of a home directory\&. This queries the caller for a password (or similar) and checks that it correctly unlocks the home directory\&. This leaves the home directory in the state it is in, i\&.e\&. it leaves the home directory in inactive state if it was inactive before, and in active state if it was active before\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBcreate\fR \fIUSER\fR, \fBcreate\fR \fB\-\-identity=\fR\fIPATH\fR [\fIUSER\fR]
+.RS 4
+Create a new home directory/user account of the specified name\&. Use the various user record property options (as documented above) to control various aspects of the home directory and its user accounts\&.
+.sp
+The specified user name should follow the strict syntax described on
+\m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[3]\d\s+2\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBremove\fR \fIUSER\fR
+.RS 4
+Remove a home directory/user account\&. This will remove both the home directory\*(Aqs user record and the home directory itself, and thus delete all files and directories owned by the user\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBupdate\fR \fIUSER\fR, \fBupdate\fR \fB\-\-identity=\fR\fIPATH\fR [\fIUSER\fR]
+.RS 4
+Update a home directory/user account\&. Use the various user record property options (as documented above) to make changes to the account, or alternatively provide a full, updated JSON user record via the
+\fB\-\-identity=\fR
+option\&.
+.sp
+Note that changes to user records not signed by a cryptographic private key available locally are not permitted, unless
+\fB\-\-identity=\fR
+is used with a user record that is already correctly signed by a recognized private key\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBpasswd\fR \fIUSER\fR
+.RS 4
+Change the password of the specified home directory/user account\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBresize\fR \fIUSER\fR \fIBYTES\fR
+.RS 4
+Change the disk space assigned to the specified home directory\&. If the LUKS2 storage mechanism is used this will automatically resize the loopback file and the file system contained within\&. Note that if
+"ext4"
+is used inside of the LUKS2 volume, it is necessary to deactivate the home directory before shrinking it (i\&.e the user has to log out)\&. Growing can be done while the home directory is active\&. If
+"xfs"
+is used inside of the LUKS2 volume the home directory may not be shrunk whatsoever\&. On all three of
+"ext4",
+"xfs"
+and
+"btrfs"
+the home directory may be grown while the user is logged in, and on the latter also shrunk while the user is logged in\&. If the
+"subvolume",
+"directory",
+"fscrypt"
+storage mechanisms are used, resizing will change file system quota\&. The size parameter may make use of the usual suffixes B, K, M, G, T (to the base of 1024)\&. The special strings
+"min"
+and
+"max"
+may be specified in place of a numeric size value, for minimizing or maximizing disk space assigned to the home area, taking constraints of the file system, disk usage inside the home area and on the backing storage into account\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBlock\fR \fIUSER\fR
+.RS 4
+Temporarily suspend access to the user\*(Aqs home directory and remove any associated cryptographic keys from memory\&. Any attempts to access the user\*(Aqs home directory will stall until the home directory is unlocked again (i\&.e\&. re\-authenticated)\&. This functionality is primarily intended to be used during system suspend to make sure the user\*(Aqs data cannot be accessed until the user re\-authenticates on resume\&. This operation is only defined for home directories that use the LUKS2 storage mechanism\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBunlock\fR \fIUSER\fR
+.RS 4
+Resume access to the user\*(Aqs home directory again, undoing the effect of
+\fBlock\fR
+above\&. This requires authentication of the user, as the cryptographic keys required for access to the home directory need to be reacquired\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBlock\-all\fR
+.RS 4
+Execute the
+\fBlock\fR
+command on all suitable home directories at once\&. This operation is generally executed on system suspend (i\&.e\&. by
+\fBsystemctl suspend\fR
+and related commands), to ensure all active user\*(Aqs cryptographic keys for accessing their home directories are removed from memory\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBdeactivate\-all\fR
+.RS 4
+Execute the
+\fBdeactivate\fR
+command on all active home directories at once\&. This operation is generally executed on system shut down (i\&.e\&. by
+\fBsystemctl poweroff\fR
+and related commands), to ensure all active user\*(Aqs home directories are fully deactivated before
+/home/
+and related file systems are unmounted\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fBwith\fR \fIUSER\fR \fICOMMAND\&...\fR
+.RS 4
+Activate the specified user\*(Aqs home directory, run the specified command (under the caller\*(Aqs identity, not the specified user\*(Aqs) and deactivate the home directory afterwards again (unless the user is logged in otherwise)\&. This command is useful for running privileged backup scripts and such, but requires authentication with the user\*(Aqs credentials in order to be able to unlock the user\*(Aqs home directory\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBrebalance\fR
+.RS 4
+Rebalance free disk space between active home areas and the backing storage\&. See
+\fB\-\-rebalance\-weight=\fR
+above\&. This executes no operation unless there\*(Aqs at least one active LUKS2 home area that has disk space rebalancing enabled\&. This operation is synchronous: it will only complete once disk space is rebalanced according to the rebalancing weights\&. Note that rebalancing also takes place automatically in the background in regular intervals\&. Use this command to synchronously ensure disk space is properly redistributed before initiating an operation requiring large amounts of disk space\&.
+.sp
+Added in version 250\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.PP
+When a command is invoked with
+\fBwith\fR, the exit status of the child is propagated\&. Effectively,
+\fBhomectl\fR
+will exit without error if the command is successfully invoked
+\fIand\fR
+finishes successfully\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Create a user "waldo" in the administrator group "wheel", and assign 500 MiB disk space to them\&.\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+homectl create waldo \-\-real\-name="Waldo McWaldo" \-G wheel \-\-disk\-size=500M
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Create a user "wally" on a USB stick, and assign a maximum of 500 concurrent tasks to them\&.\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+homectl create wally \-\-real\-name="Wally McWally" \-\-image\-path=/dev/disk/by\-id/usb\-SanDisk_Ultra_Fit_476fff954b2b5c44\-0:0 \-\-tasks\-max=500
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&3.\ \&Change nice level of user "odlaw" to +5 and make sure the environment variable \fI$SOME\fR is set to the string "THING" for them on login\&.\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+homectl update odlaw \-\-nice=5 \-\-setenv=SOME=THING
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&4.\ \&Set up authentication with a YubiKey security token using PKCS#11/PIV:\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# Clear the Yubikey from any old keys (careful!)
+ykman piv reset
+
+# Generate a new private/public key pair on the device, store the public key in \*(Aqpubkey\&.pem\*(Aq\&.
+ykman piv generate\-key \-a RSA2048 9d pubkey\&.pem
+
+# Create a self\-signed certificate from this public key, and store it on the device\&.
+ykman piv generate\-certificate \-\-subject "Knobelei" 9d pubkey\&.pem
+
+# We don\*(Aqt need the public key on disk anymore
+rm pubkey\&.pem
+
+# Allow the security token to unlock the account of user \*(Aqlafcadio\*(Aq\&.
+homectl update lafcadio \-\-pkcs11\-token\-uri=auto
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&5.\ \&Set up authentication with a FIDO2 security token:\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# Allow a FIDO2 security token to unlock the account of user \*(Aqnihilbaxter\*(Aq\&.
+homectl update nihilbaxter \-\-fido2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-homed.service\fR(8),
+\fBhomed.conf\fR(5),
+\fBuserdbctl\fR(1),
+\fBuseradd\fR(8),
+\fBcryptsetup\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+JSON User Records
+.RS 4
+\%https://systemd.io/USER_RECORD
+.RE
+.IP " 2." 4
+Icon Naming Specification
+.RS 4
+\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
+.RE
+.IP " 3." 4
+User/Group Name Syntax
+.RS 4
+\%https://systemd.io/USER_NAMES
+.RE
diff --git a/upstream/mageia-cauldron/man1/hostid.1 b/upstream/mageia-cauldron/man1/hostid.1
new file mode 100644
index 00000000..57f4a7de
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hostid.1
@@ -0,0 +1,36 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH HOSTID "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+hostid \- print the numeric identifier for the current host
+.SH SYNOPSIS
+.B hostid
+[\fI\,OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the numeric identifier (in hexadecimal) for the current host.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBgethostid\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/hostid>
+.br
+or available locally via: info \(aq(coreutils) hostid invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/hostname.1 b/upstream/mageia-cauldron/man1/hostname.1
new file mode 100644
index 00000000..5f6aa5ec
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hostname.1
@@ -0,0 +1,280 @@
+.TH HOSTNAME 1 "2009-09-16" "net-tools" "Linux Programmer's Manual"
+
+.SH NAME
+hostname \- show or set the system's host name
+.br
+domainname \- show or set the system's NIS/YP domain name
+.br
+ypdomainname \- show or set the system's NIS/YP domain name
+.br
+nisdomainname \- show or set the system's NIS/YP domain name
+.br
+dnsdomainname \- show the system's DNS domain name
+.br
+
+.SH SYNOPSIS
+.B hostname
+.RB [ \-a|\-\-alias ]
+.RB [ \-d|\-\-domain ]
+.RB [ \-f|\-\-fqdn|\-\-long ]
+.RB [ \-A|\-\-all-fqdns ]
+.RB [ \-i|\-\-ip-address ]
+.RB [ \-I|\-\-all-ip-addresses ]
+.RB [ \-s|\-\-short ]
+.RB [ \-y|\-\-yp|\-\-nis ]
+.br
+.B hostname
+.RB [ \-b|\-\-boot ]
+.RB [ \-F|\-\-file\ filename ]
+.RB [ hostname ]
+.br
+.B hostname
+.RB [ \-h|\-\-help ]
+.RB [ \-V|\-\-version ]
+.PP
+.B domainname
+.RB [ nisdomain ]
+.RB [ \-F\ file ]
+.br
+.B ypdomainname
+.RB [ nisdomain ]
+.RB [ \-F\ file ]
+.br
+.B nisdomainname
+.RB [ nisdomain ]
+.RB [ \-F\ file ]
+.PP
+.B dnsdomainname
+
+.SH DESCRIPTION
+.B Hostname
+is used to display the system's DNS name, and to display or set its hostname or
+NIS domain name.
+
+.SS "GET NAME"
+When called without any arguments, the program displays the current
+names:
+.LP
+.B hostname
+will print the name of the system as returned by the
+.BR gethostname (2)
+function.
+.LP
+.B domainname
+will print the NIS domainname of the system.
+.B domainname
+uses the
+.BR gethostname (2)
+function, while
+.B ypdomainname
+and
+.B nisdomainname
+use the
+.BR getdomainname (2).
+.LP
+.B dnsdomainname
+will print the domain part of the FQDN (Fully Qualified Domain Name). The
+complete FQDN of the system is returned with
+.B hostname \-\-fqdn
+(but see the warnings in section
+.B THE FQDN
+below).
+
+.LP
+The function 
+.BR gethostname(2)
+is used to get the hostname.  When the 
+.BR "hostname \-a, \-d, \-f or \-i" 
+is called will 
+.BR gethostbyname(3)
+be called.  The difference in 
+.BR gethostname(2)
+and
+.BR gethostbyname(3)
+is that
+.BR gethostbyname(3)
+is network aware, so it consults 
+.IR /etc/nsswitch.conf
+and
+.IR /etc/host.conf
+to decide whether to read information in
+.IR /etc/hostname
+or
+.IR /etc/hosts
+
+.SS "SET NAME"
+When called with one argument or with the
+.B \-\-file
+option, the commands set the host name or the NIS/YP domain name.
+.B hostname
+uses the
+.BR sethostname (2)
+function, while all of the three
+.BR domainname ,
+.B ypdomainname
+and
+.B nisdomainname
+use
+.BR setdomainname (2).
+Note, that this is effective only until the next reboot.
+Edit /etc/hostname for permanent change.
+.LP
+Note, that only the super-user can change the names.
+.LP
+It is not possible to set the FQDN or the DNS domain name with the
+.B dnsdomainname
+command (see
+.B THE FQDN
+below).
+.LP
+The host name is usually set once at system startup
+(normally by reading the contents of a file which contains
+the host name, e.g.
+.IR /etc/hostname ).
+
+.SS THE FQDN
+The FQDN (Fully Qualified Domain Name) of the system is the name that the
+.BR resolver (3)
+returns for the host name, such as,
+.IR ursula.example.com .
+It is usually the hostname followed by the DNS domain name (the part
+after the first dot).  You can check the FQDN using
+.B hostname \-\-fqdn
+or the domain name using
+.BR "dnsdomainname" .
+.LP
+You cannot change the FQDN with
+.B hostname
+or
+.BR dnsdomainname .
+.LP
+The recommended method of setting the FQDN is to make the hostname be
+an alias for the fully qualified name using
+.IR /etc/hosts ,
+DNS, or NIS. For example, if the hostname was "ursula", one might have a line in
+.I /etc/hosts
+which reads
+.LP
+.RS
+127.0.1.1    ursula.example.com ursula
+.RE
+.LP
+Technically: The FQDN is the name
+.BR getaddrinfo (3)
+returns for the host name returned by
+.BR gethostname (2).
+The DNS domain name is the part after the first dot.
+.LP
+Therefore it depends on the configuration of the resolver (usually in
+.IR /etc/host.conf )
+how you can change it. Usually the hosts file is parsed before DNS or
+NIS, so it is most common to change the FQDN in
+.IR /etc/hosts .
+.LP
+If a machine has multiple network interfaces/addresses or is used in a
+mobile environment, then it may either have multiple FQDNs/domain names
+or none at all. Therefore avoid using
+.BR "hostname \-\-fqdn" ,
+.B hostname \-\-domain
+and
+.BR "dnsdomainname" .
+.B hostname \-\-ip-address
+is subject to the same limitations so it should be avoided as well.
+
+.SH OPTIONS
+.TP
+.I "\-a, \-\-alias"
+Display the alias name of the host (if used). This option is deprecated
+and should not be used anymore.
+.TP
+.I "\-A, \-\-all-fqdns"
+Displays all FQDNs of the machine. This option enumerates all configured
+network addresses on all configured network interfaces, and translates
+them to DNS domain names. Addresses that cannot be translated (i.e. because
+they do not have an appropriate reverse IP entry) are skipped. Note that
+different addresses may resolve to the same name, therefore the output may
+contain duplicate entries. Do not make any assumptions about the order of the
+output.
+.TP
+.I "\-b, \-\-boot"
+Always set a hostname; this allows the file specified by \fI\-F\fR to be
+non-existent or empty, in which case the default hostname \fIlocalhost\fR
+will be used if none is yet set.
+.TP
+.I "\-d, \-\-domain"
+Display the name of the DNS domain.  Don't use the command
+.B domainname
+to get the DNS domain name because it will show the NIS domain name and
+not the DNS domain name. Use
+.B dnsdomainname
+instead. See the warnings in section
+.B THE FQDN
+above, and avoid using this option.
+.TP
+.I "\-f, \-\-fqdn, \-\-long"
+Display the FQDN (Fully Qualified Domain Name). A FQDN consists of a
+short host name and the DNS domain name. Unless you are using bind or NIS
+for host lookups you can change the FQDN and the DNS domain name (which is
+part of the FQDN) in the \fI/etc/hosts\fR file. See the warnings in section
+.B THE FQDN
+above und use
+.B hostname \-\-all-fqdns
+instead wherever possible.
+.TP
+.I "\-F, \-\-file filename"
+Read the host name from the specified file. Comments (lines starting with
+a `#') are ignored.
+.TP
+.I "\-i, \-\-ip-address"
+Display the network address(es) of the host name. Note that this works only
+if the host name can be resolved. Avoid using this option; use
+.B hostname \-\-all-ip-addresses
+instead.
+.TP
+.I "\-I, \-\-all-ip-addresses"
+Display all network addresses of the host. This option enumerates all
+configured addresses on all network interfaces. The loopback interface and IPv6
+link-local addresses are omitted. Contrary to option \fI\-i\fR, this option
+does not depend on name resolution. Do not make any assumptions about the
+order of the output.
+.TP
+.I "\-s, \-\-short"
+Display the short host name. This is the host name cut at the first dot.
+.TP
+.I "\-V, \-\-version"
+Print version information on standard output and exit successfully.
+.TP
+.I "\-y, \-\-yp, \-\-nis"
+Display the NIS domain name. If a parameter is given (or
+.B \-\-file name
+) then root can also set a new NIS domain.
+.TP
+.I "\-h, \-\-help"
+Print a usage message and exit.
+.SH NOTES
+The address families
+.B hostname
+tries when looking up the FQDN, aliases and network addresses of the
+host are determined by the configuration of your resolver.
+For instance, on GNU Libc systems, the resolver can be instructed to
+try IPv6 lookups first by using the
+.B inet6
+option in
+.BR /etc/resolv.conf .
+.SH FILES
+.B /etc/hostname
+Historically this file was supposed to only contain the hostname and not the
+full canonical FQDN. Nowadays most software is able to cope with a full FQDN
+here. This file is read at boot time by the system initialization scripts to
+set the hostname.
+.LP
+.B /etc/hosts
+Usually, this is where one sets the domain name by aliasing the host name to
+the FQDN.
+.SH AUTHORS
+Peter Tobias, <tobias@et-inf.fho-emden.de>
+.br
+Bernd Eckenfels, <net-tools@lina.inka.de> (NIS and manpage).
+.br
+Michael Meskes, <meskes@debian.org>
+.br
diff --git a/upstream/mageia-cauldron/man1/hostnamectl.1 b/upstream/mageia-cauldron/man1/hostnamectl.1
new file mode 100644
index 00000000..bba45a7e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hostnamectl.1
@@ -0,0 +1,217 @@
+'\" t
+.TH "HOSTNAMECTL" "1" "" "systemd 255" "hostnamectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+hostnamectl \- Control the system hostname
+.SH "SYNOPSIS"
+.HP \w'\fBhostnamectl\fR\ 'u
+\fBhostnamectl\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+\fBhostnamectl\fR
+may be used to query and change the system hostname and related settings\&.
+.PP
+\fBsystemd-hostnamed.service\fR(8)
+and this tool distinguish three different hostnames: the high\-level "pretty" hostname which might include all kinds of special characters (e\&.g\&. "Lennart\*(Aqs Laptop"), the "static" hostname which is the user\-configured hostname (e\&.g\&. "lennarts\-laptop"), and the transient hostname which is a fallback value received from network configuration (e\&.g\&. "node12345678")\&. If a static hostname is set to a valid value, then the transient hostname is not used\&.
+.PP
+Note that the pretty hostname has little restrictions on the characters and length used, while the static and transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at maximum (the latter being a Linux limitation)\&.
+.PP
+Use
+\fBsystemd-firstboot\fR(1)
+to initialize the system hostname for mounted (but not booted) system images\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBstatus\fR
+.RS 4
+Show system hostname and related information\&. If no command is specified, this is the implied default\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBhostname\fR [\fINAME\fR]
+.RS 4
+If no argument is given, print the system hostname\&. If an optional argument
+\fINAME\fR
+is provided then the command changes the system hostname to
+\fINAME\fR\&. By default, this will alter the pretty, the static, and the transient hostname alike; however, if one or more of
+\fB\-\-static\fR,
+\fB\-\-transient\fR,
+\fB\-\-pretty\fR
+are used, only the selected hostnames are changed\&. If the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be simplified in regards to the character set used before the latter are updated\&. This is done by removing special characters and spaces\&. This ensures that the pretty and the static hostname are always closely related while still following the validity rules of the specific name\&. This simplification of the hostname string is not done if only the transient and/or static hostnames are set, and the pretty hostname is left untouched\&.
+.sp
+The static and transient hostnames must each be either a single DNS label (a string composed of 7\-bit ASCII lower\-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN\&. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fBicon\-name\fR [\fINAME\fR]
+.RS 4
+If no argument is given, print the icon name of the system\&. If an optional argument
+\fINAME\fR
+is provided then the command changes the icon name to
+\fINAME\fR\&. The icon name is used by some graphical applications to visualize this host\&. The icon name should follow the
+\m[blue]\fBIcon Naming Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fBchassis\fR [\fITYPE\fR]
+.RS 4
+If no argument is given, print the chassis type\&. If an optional argument
+\fITYPE\fR
+is provided then the command changes the chassis type to
+\fITYPE\fR\&. The chassis type is used by some graphical applications to visualize the host or alter user interaction\&. Currently, the following chassis types are defined:
+"desktop",
+"laptop",
+"convertible",
+"server",
+"tablet",
+"handset",
+"watch",
+"embedded", as well as the special chassis types
+"vm"
+and
+"container"
+for virtualized systems that lack an immediate physical chassis\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fBdeployment\fR [\fIENVIRONMENT\fR]
+.RS 4
+If no argument is given, print the deployment environment\&. If an optional argument
+\fIENVIRONMENT\fR
+is provided then the command changes the deployment environment to
+\fIENVIRONMENT\fR\&. Argument
+\fIENVIRONMENT\fR
+must be a single word without any control characters\&. One of the following is suggested:
+"development",
+"integration",
+"staging",
+"production"\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fBlocation\fR [\fILOCATION\fR]
+.RS 4
+If no argument is given, print the location string for the system\&. If an optional argument
+\fILOCATION\fR
+is provided then the command changes the location string for the system to
+\fILOCATION\fR\&. Argument
+\fILOCATION\fR
+should be a human\-friendly, free\-form string describing the physical location of the system, if it is known and applicable\&. This may be as generic as
+"Berlin, Germany"
+or as specific as
+"Left Rack, 2nd Shelf"\&.
+.sp
+Added in version 249\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-static\fR, \fB\-\-transient\fR, \fB\-\-pretty\fR
+.RS 4
+If
+\fBstatus\fR
+is invoked (or no explicit command is given) and one of these switches is specified,
+\fBhostnamectl\fR
+will print out just this selected hostname\&.
+.sp
+If used with
+\fBhostname\fR, only the selected hostnames will be updated\&. When more than one of these switches are specified, all the specified hostnames will be updated\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBhostname\fR(1),
+\fBhostname\fR(5),
+\fBmachine-info\fR(5),
+\fBsystemctl\fR(1),
+\fBsystemd-hostnamed.service\fR(8),
+\fBsystemd-firstboot\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Icon Naming Specification
+.RS 4
+\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
+.RE
diff --git a/upstream/mageia-cauldron/man1/hpftodit.1 b/upstream/mageia-cauldron/man1/hpftodit.1
new file mode 100644
index 00000000..01559605
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/hpftodit.1
@@ -0,0 +1,428 @@
+.TH HPFTODIT 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+hpftodit \- create font description files for use with groff \-Tlj4
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr hpftodit_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1994-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY hpftodit
+.OP \-aqs
+.OP \-i n
+.I tfm-file
+.I map-file
+.I output-font
+.YS
+.
+.SY hpftodit
+.B \-d
+.I tfm-file
+.RI [ map-file ]
+.YS
+.
+.SY hpftodit
+.B \-\-help
+.YS
+.
+.SY hpftodit
+.B \-v
+.SY hpftodit
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B hpftodit
+creates a font file for use with a Hewlett-Packard LaserJet\~\%4-series
+(or newer) printer with
+.BR "groff \-Tlj4" ,
+using data from an HP tagged font metric (TFM) file.
+.
+.I tfm-file
+is the name of the TFM file for the font;
+Intellifont and TrueType TFM files are supported,
+but symbol set TFM files are not.
+.
+.I map-file
+is a file giving the
+.I groff
+names for characters in the font;
+this file should consist of a sequence of lines of the form:
+.RS
+.EX
+.IR "m u c1 c2 " "\&.\|.\|.\& [#" " comment" "]"
+.EE
+.RE
+where
+.I m
+is a decimal integer giving the MSL (Master Symbol List) number of the
+character,
+.I u
+is a hexadecimal integer giving the Unicode value of the character,
+and
+.IR c1 ,
+.IR c2 ", .\|.\|."
+are the
+.I groff
+names of the character
+(see
+.BR groff_char (7)
+for a list).
+.
+The values can be separated by any whitespace;
+the Unicode value must use uppercase digits A\^\[en]\^F,
+and must be without a leading
+.RB \[oq] 0x \[cq],
+.RB \[oq] u \[cq],
+or
+.RB \[oq] U+ \[cq].
+Unicode values corresponding to composite glyphs are decomposed;
+e.g.,
+.RB \[oq] u00C0 \[cq]
+becomes
+.RB \[oq] u0041_0300 \[cq].
+.
+The name for a glyph without a
+.I groff
+name may be given as
+.BI u XXXX
+if the glyph corresponds to a Unicode value,
+or as an unnamed glyph
+.RB \[oq] \-\-\- \[cq].
+.
+If the given Unicode value is in the Private Use Area
+(0xE000\^\[en]\^0xF8FF),
+the glyph is included as an unnamed glyph.
+.
+Refer to
+.BR groff_diff (1)
+for additional information about unnamed glyphs and how to access them.
+.
+.
+.LP
+Blank lines and lines beginning with
+.RB \[oq] # \[cq]
+are ignored.
+.
+A
+.RB \[oq] # \[cq]
+following one or more
+.I groff
+names begins a comment.
+.
+Because
+.RB \[oq] # \[cq]
+is a valid
+.I groff
+name,
+it must appear first in a list of
+.I groff
+names if a comment is included,
+e.g.,
+.
+.RS
+.EX
+.B
+3   0023   #   # number sign
+.EE
+.RE
+.
+or
+.
+.RS
+.EX
+.B
+3   0023   # sh   # number sign
+.EE
+.RE
+.
+rather than
+.
+.RS
+.EX
+.B
+3   0023   sh #   # number sign
+.EE
+.RE
+.
+which will treat the first
+.RB \[oq] # \[cq]
+as the beginning of the comment.
+.
+.
+.LP
+The
+.I groff
+font file is written to the specified
+.IR output-font ;
+if this operand is
+.RB \[oq] \- \[cq],
+the font file is written to the standard output.
+.
+.
+.LP
+The
+.B \-s
+option should be given if the font is special
+(a font is \[lq]special\[rq] if
+.I groff
+should search it whenever a character is not found in the current font).
+.
+If the font is special,
+it should be listed in the
+.B fonts
+command in the DESC file;
+if it is not special,
+there is no need to list it,
+since
+.I groff
+can automatically mount it when it's first used.
+.
+.
+.LP
+If the
+.B \-i
+option is used,
+.B hpftodit
+automatically will generate an italic correction,
+a left italic correction and a subscript correction
+for each character
+(the significance of these parameters is explained in
+.BR groff_font (5)).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.TP
+.B \-a
+Include characters in the TFM file that are not included in
+.IR map-file .
+.
+A glyph with corresponding Unicode value is given the name
+.RI u XXXX ;
+a glyph without a Unicode value is included as an unnamed glyph
+\[oq]\-\^\-\^\-\[cq].
+.
+A glyph with a Unicode value in the Private Use Area
+(0xE000\^\[en]\^0xF8FF) also is included as an unnamed glyph.
+.
+.
+.IP
+This option provides a simple means of adding Unicode-named and
+unnamed glyphs to a font without including them in the map file,
+but it affords little control over which glyphs are placed in a regular
+font and which are placed in a special font.
+.
+The presence or absence of the
+.B \-s
+option has some effect on which glyphs are included:
+without the
+.B \-s
+option,
+only the \[lq]text\[rq] symbol sets are searched for matching glyphs;
+with the
+.B \-s
+option,
+only the \[lq]mathematical\[rq] symbol sets are searched.
+.
+Nonetheless,
+restricting the symbol sets searched isn't very selective\[em]many
+glyphs are placed in both regular and special fonts.
+.
+Normally,
+the
+.B \-a
+option should be used only as a last resort.
+.
+.
+.TP
+.B \-d
+Dump information about the TFM file to the standard output;
+this option can be useful for ensuring that a TFM file is a proper match
+for a font,
+and that the contents of the TFM file are suitable.
+.
+The information includes the values of important TFM tags,
+and a listing (by MSL number for Intellifont TFM files or by Unicode
+value for TrueType TFM files) of the glyphs included in the TFM file.
+.
+The unit of measure \[oq]DU\[cq] for some tags indicates design units;
+there are 8782\~design units per em for Intellifont fonts,
+and 2048\~design units per em for TrueType fonts.
+.
+Note that the accessibility of a glyph depends on its inclusion in a
+symbol set;
+some TFM files list many glyphs but only a few symbol sets.
+.
+.IP
+The glyph listing includes the glyph index within the TFM file,
+the MSL or Unicode value,
+and the symbol set and character code that will be used to print the
+glyph.
+.
+If
+.I map-file
+is given,
+.I groff
+names are given for matching glyphs.
+.
+If only the glyph index and MSL or Unicode value are given,
+the glyph does not appear in any supported symbol set and cannot be
+printed.
+.
+.IP
+With the
+.B \-d
+option,
+.I map-file
+is optional,
+and
+.I output-font
+is ignored if given.
+.
+.TP
+.B \-q
+Suppress warnings about characters in the map file that were not found
+in the TFM file.
+.
+Warnings never are given for unnamed glyphs or by glyphs named by their
+Unicode values.
+.
+This option is useful when sending the output of
+.B hpftodit
+to the standard output.
+.
+.TP
+.B \-v
+Print the
+.B hpftodit
+version number and exit.
+.
+.TP
+.B \-s
+The font is special.
+.
+This option adds the
+.B special
+command to the font file,
+and affects the order in which HP symbol sets are searched for each
+glyph.
+.
+Without the
+.B \-s
+option,
+the \[lq]text\[rq] sets are searched before the \[lq]mathematical\[rq]
+symbol sets.
+With the
+.B \-s
+option,
+the search order is reversed.
+.
+.TP
+.BI \-i n
+Generate an italic correction for each character so that the character's
+width plus the character's italic correction is equal to
+.I n
+thousandths of an em plus the amount by which the right edge of the
+character's bounding is to the right of the character's origin.
+.
+If this would result in a negative italic correction,
+use a zero italic correction instead.
+.
+.IP
+Also generate a subscript correction equal to the product of the tangent
+of the slant of the font and four fifths of the x-height of the font.
+.
+If this would result in a subscript correction greater than the italic
+correction,
+use a subscript correction equal to the italic correction instead.
+.
+.IP
+Also generate a left italic correction for each character equal to
+.I n
+thousandths of an em plus the amount by which the left edge of the
+character's bounding box is to the left of the character's origin.
+.
+The left italic correction may be negative.
+.
+.IP
+This option normally is needed only with italic or oblique fonts;
+a value of 50 (0.05\~em) usually is a reasonable choice.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/\:devlj4/\:DESC
+device description file
+.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/\:devlj4/\: F
+Font description file for font
+.I F
+.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/\:devlj4/\:generate/\: * .map
+symbol mapping files
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR groff (1),
+.BR groff_diff (1),
+.BR grolj4 (1),
+.BR groff_font (5),
+.BR lj4_font (5)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[hpftodit_C]
+.
+.
+.\" ====================================================================
+.\" Editor settings
+.\" ====================================================================
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 72
+.\" End:
+.\" vim: set filetype=groff textwidth=72:
diff --git a/upstream/mageia-cauldron/man1/iceauth.1 b/upstream/mageia-cauldron/man1/iceauth.1
new file mode 100644
index 00000000..95ed2edc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/iceauth.1
@@ -0,0 +1,126 @@
+.\" Copyright 1994, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included in
+.\" all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+.\" THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+.\" SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall not
+.\" be used in advertising or otherwise to promote the sale, use or other
+.\" dealing in this Software without prior written authorization from the
+.\" The Open Group.
+.\"
+.TH ICEAUTH 1 "iceauth 1.0.9" "X Version 11"
+.SH NAME
+iceauth \- ICE authority file utility
+.SH SYNOPSIS
+.B iceauth
+[ \fB\-f\fP \fIauthfile\fP ] [ \fB\-vqibuV\fP ] [ \fIcommand arg ...\fP ]
+.SH DESCRIPTION
+.PP
+The \fIiceauth\fP program is used to edit and display the authorization
+information used in connecting with ICE.  This program is usually
+used to extract authorization records from one machine and merge them in on
+another (as is the case when using remote logins or granting access to
+other users).  Commands (described below) may be entered interactively,
+on the \fIiceauth\fP command line, or in scripts.
+.SH OPTIONS
+.PP
+\fB\-f\fP \fIauthfile\fP  Name of the authority file to use. Will default to
+             the file currently in use by the session.
+.PP
+\fB\-v\fP           Turns on extra messages (verbose mode)
+.PP
+\fB\-q\fP           Turns off extra messages (quiet mode)
+.PP
+\fB\-i\fP           Ignore the locks on the authority file
+.PP
+\fB\-b\fP           Break the locks on the authority file
+.PP
+\fB\-u\fP           Print basic usage instructions
+.PP
+\fB\-V\fP           Print version and exit
+.PP
+.SH USAGE
+.PP
+When \fIiceauth\fP is run it will allow the following set of commands
+to be entered interactively or in scripts.
+.PP
+\fB?\fP
+.PP
+List available commands.
+.PP
+\fBhelp\fP
+.PP
+Print help information. You may supply a command name to \fIhelp\fP to
+get specific information about it.
+.PP
+\fBinfo\fP
+.PP
+Print information about the entries in the authority file.
+.PP
+\fBlist\fP
+.PP
+List (print) entries in the authority file. You may specify optional
+modifiers as below to specify which entries are listed.
+.PP
+\fIlist\fP [ \fIprotocol_name\fP ] [ \fIprotocol_data\fP ] [
+\fInetid\fP ] [ \fIauthname\fP ]
+.PP
+\fBadd\fP
+.PP
+Add an entry to the authority file. This must be in the format
+.PP
+\fIadd\fP \fIprotocol_name\fP \fIprotocol_data\fP \fInetid\fP \fIauthname\fP \fIauthdata\fP
+.PP
+\fBremove\fP
+.PP
+Remove entries from the authority file.
+.PP
+\fIremove\fP [ \fIprotocol_name\fP ] [ \fIprotocol_data\fP ] [
+\fInetid\fP ] [ \fIauthname\fP ]
+.PP
+\fBextract\fP
+.PP
+Extract entries from the authority file in to a destination file. You
+must supply the path to the destination to this command as in the
+following format. Optional specifiers allow you to narrow which
+entries are extracted.
+.PP
+\fIextract\fP \fIfilename\fP [ \fIprotocol_name\fP ] [ \fIprotocol_data\fP ]
+[ \fInetid\fP ] [ \fIauthname\fP ]
+.PP
+\fBmerge\fP
+.PP
+Merge entries from other files in to the authority file selected by the program. You may supply any number of file paths to this command as follows:
+.PP
+\fImerge\fP \fIfilename1\fP [ \fIfilename2\fP ] [ \fIfilename3\fP ] ...
+.PP
+\fBexit\fP
+.PP
+Save changes and exit the program.
+.PP
+\fBquit\fP
+.PP
+Abort changes and exit the program without saving.
+.PP
+\fBsource\fP
+.PP
+Read and execute commands from a file.
+.PP
+\fIsource\fP \fIfilename\fP
+.PP
+.SH AUTHOR
+Ralph Mor, X Consortium
diff --git a/upstream/mageia-cauldron/man1/icehelp.1 b/upstream/mageia-cauldron/man1/icehelp.1
new file mode 100644
index 00000000..f545c9d3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icehelp.1
@@ -0,0 +1,149 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEHELP 1"
+.TH ICEHELP 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icehelp \- a very simple HTML browser
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicehelp\fR [\fIOPTIONS\fR] \fIFILENAME\fR
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicehelp\fR is a very simple HTML browser, which is used by \fBicewm\fR\|(1)
+to display the IceWM Manual and the manpages.
+.PP
+The document can be navigated by cursor keys, navigation keys and
+a scrollbar. To find text, hit \f(CW\*(C`Ctrl+F\*(C'\fR for a search window.
+Hit the \f(CW\*(C`F3\*(C'\fR function key to repeat a search.
+.PP
+The top right corner shows a button, which opens a menu. This menu
+can also be opened by a right mouse button click.
+.SS ARGUMENTS
+.IX Subsection "ARGUMENTS"
+.IP \fIFILENAME\fR 4
+.IX Item "FILENAME"
+Specifies the file to browse.  It can also be the URL of a website.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.SS "SPECIFIC OPTIONS"
+.IX Subsection "SPECIFIC OPTIONS"
+.IP \fB\-B\fR 4
+.IX Item "-B"
+Display the IceWM icewmbg manpage.
+.IP "\fB\-b\fR, \fB\-\-bugs\fR" 4
+.IX Item "-b, --bugs"
+Display the IceWM bug reports (primitively).
+.IP "\fB\-f\fR, \fB\-\-faq\fR" 4
+.IX Item "-f, --faq"
+Display the IceWM FAQ and Howto.
+.IP \fB\-g\fR 4
+.IX Item "-g"
+Display the IceWM Github website.
+.IP "\fB\-i\fR, \fB\-\-icewm\fR" 4
+.IX Item "-i, --icewm"
+Display the IceWM icewm manpage.
+.IP "\fB\-m\fR, \fB\-\-manual\fR" 4
+.IX Item "-m, --manual"
+Display the IceWM Manual (default).
+.IP \fB\-s\fR 4
+.IX Item "-s"
+Display the IceWM icesound manpage.
+.IP "\fB\-t\fR, \fB\-\-theme\fR" 4
+.IX Item "-t, --theme"
+Display the IceWM themes Howto.
+.IP "\fB\-w\fR, \fB\-\-website\fR" 4
+.IX Item "-w, --website"
+Display the IceWM website.
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
+.IX Item "-d, --display=DISPLAY"
+Use \fIDISPLAY\fR to connect to the X server.
+If this option is missing then \fIDISPLAY\fR
+is read from the environment variable \f(CW\*(C`DISPLAY\*(C'\fR.
+.IP \fB\-\-sync\fR 4
+.IX Item "--sync"
+Use a slower synchronous mode communication with \fIX11\fR server.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions to \fIstdout\fR for the program and exit.
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icesh.1 b/upstream/mageia-cauldron/man1/icesh.1
new file mode 100644
index 00000000..82867c66
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icesh.1
@@ -0,0 +1,952 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICESH 1"
+.TH ICESH 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icesh \- control window properties and the IceWM window manager
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+.IP "\fBicesh\fR \fIOPTIONS|ACTIONS\fR+" 4
+.IX Item "icesh OPTIONS|ACTIONS+"
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicesh\fR provides two types of commands:
+.IP "1. Commands to directly interact with icewm:" 4
+.IX Item "1. Commands to directly interact with icewm:"
+These are listed in the section "MANAGER ACTIONS" below.
+They are easy to use, because they don't require to select one
+or more windows. For example, \f(CW\*(C`icesh restart\*(C'\fR will restart
+icewm and \f(CW\*(C`icesh clients\*(C'\fR lists the applications that
+are managed by icewm.
+.IP "2. Commands that operate on a selection of windows:" 4
+.IX Item "2. Commands that operate on a selection of windows:"
+See the section \f(CW\*(C`WINDOW ACTIONS\*(C'\fR below. For example, \f(CW\*(C`icesh close\*(C'\fR
+is a request to close a window, but which window? Now icesh
+will turn the mouse pointer into a crosshair. Click on a window
+and a close request will be sent to that application.
+.Sp
+The power of icesh lies in its ability to programmatically
+select one or more windows and operate on that selection.
+This can be used in scripts and in \fBicewm\-keys\fR\|(5)
+to define your own window management hotkeys.  For example, to
+immediately close all xterm windows do \f(CW\*(C`icesh \-c xterm close\*(C'\fR.
+.Sp
+There are a dozen \f(CW\*(C`SELECT OPTIONS\*(C'\fR to select windows.  They start
+with a '\-' or a '+'.  The '\-' starts a new selection, while the '+'
+adds more windows to an existing selection.
+.Sp
+This selection of windows can be reduced by \f(CW\*(C`FILTER OPTIONS\*(C'\fR.
+These remove unwanted windows from the current selection.
+Multiple filter options can be given. For example,
+\&\f(CW\*(C`icesh \-c xterm \-W this close\*(C'\fR will close only those xterms
+that are shown on the current workspace. The xterms on other
+workspaces are filtered out by the \f(CW\*(C`\-W this\*(C'\fR filter option.
+.PP
+There is no limit to the number of commands, selections, filters
+and actions that you can give to a single icesh command.
+They are processed and evaluated one by one from left to right.
+This makes icesh a small declarative programming language.
+Have a look at some examples near the end of this document.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+\&\fBicesh\fR recognizes the following options:
+.SS "SELECT OPTIONS"
+.IX Subsection "SELECT OPTIONS"
+Select options specify the window or windows to which subsequent
+actions apply. If none is given, but an action does require a window,
+then a selection crosshair is shown to select the desired window
+interactively. The manager actions do not require window options.
+.PP
+The following options \fIselect\fR one or more client windows.
+If needed, they can be repeated for successive actions.
+.IP "\fB\-a\fR, \fB\-all\fR" 4
+.IX Item "-a, -all"
+Selects all client windows of the window manager.
+.IP "\fB\-f\fR, \fB\-focus\fR, \fB+f\fR, \fB+focus\fR" 4
+.IX Item "-f, -focus, +f, +focus"
+Selects the application window that is currently focused.
+The option with minus sign replaces the existing selection with
+the focused window. With a plus sign the focused window is added to
+an existing selection.
+.IP "\fB+g\fR, \fB+group\fR" 4
+.IX Item "+g, +group"
+Extend the current selection with client windows that
+belong to the same application window group.
+.IP "\fB\-r\fR, \fB\-root\fR, \fB+r\fR, \fB+root\fR" 4
+.IX Item "-r, -root, +r, +root"
+Selects the root window.
+The option with minus sign replaces the existing selection with
+the root window. With a plus sign the root window is added to
+an existing selection.
+.IP "\fB\-s\fR, \fB\-shown\fR" 4
+.IX Item "-s, -shown"
+Selects all client windows that are on the current workspace.
+.IP "\fB\-t\fR, \fB\-top\fR" 4
+.IX Item "-t, -top"
+Selects all toplevel windows from the display unconditionally.
+This includes windows that have never been mapped and windows
+with the override redirect bit set to evade management.
+.IP "\fB\-w\fR, \fB\-window\fR, \fB+w\fR, \fB+window\fR \fIWINDOW_ID\fR" 4
+.IX Item "-w, -window, +w, +window WINDOW_ID"
+Specifies the identifier of the window, \fIWINDOW_ID\fR, for which the
+action applies.  Special identifiers are \fBroot\fR for the root window
+and \fBfocus\fR for the currently focused window.
+The option with minus sign replaces the existing selection.
+With a plus sign the window is added to an existing selection.
+.IP "\fB\-x\fR, \fB\-xembed\fR" 4
+.IX Item "-x, -xembed"
+Selects all windows that are embedded using the \fIXEMBED\fR protocol.
+.IP "\fB+c\fR, \fB+class\fR \fICLASS\fR" 4
+.IX Item "+c, +class CLASS"
+Extend the current selection with client windows that have a
+\&\fIWM_CLASS\fR property equal to \fICLASS\fR. This is the resource
+instance and class name.  If \fICLASS\fR contains a period, only
+windows with exactly the same \fIWM_CLASS\fR property are matched.
+If there is no period, windows of the same class and windows
+of the same instance are selected.
+.IP "\fB+C\fR, \fB+Class\fR" 4
+.IX Item "+C, +Class"
+Extend the current selection with client windows that
+have a \fIWM_CLASS\fR property \fIsimilar\fR to the already
+selected set of windows.
+.IP "\fB\-D\fR, \fB\-Dockapps\fR" 4
+.IX Item "-D, -Dockapps"
+Selects all Dockapp applications that are managed by icewm.
+.IP "\fB+P\fR, \fB+Pid\fR" 4
+.IX Item "+P, +Pid"
+Extend the current selection with client windows that have
+the same process identifier as one of the selected windows.
+.IP \fB\-T\fR 4
+.IX Item "-T"
+Selects the IceWM taskbar.
+.SS "FILTER OPTIONS"
+.IX Subsection "FILTER OPTIONS"
+The following options \fIfilter\fR the currently selected set of windows.
+If no previous \fIselect\fR option was given then a \fB\-all\fR option is
+implicitly assumed to filter all client windows.
+.IP "\fB\-c\fR, \fB\-class\fR \fICLASS\fR" 4
+.IX Item "-c, -class CLASS"
+Filters the set of windows on their \fIWM_CLASS\fR property.  This is
+the resource instance and class name. If \fICLASS\fR contains a period,
+only windows with exactly the same \fIWM_CLASS\fR property are matched.
+If there is no period, windows of the same class and windows of the
+same instance (aka. \fI\-name\fR) are selected.
+.IP "\fB\-l\fR, \fB\-last\fR" 4
+.IX Item "-l, -last"
+Filter clients and keep only the most recent client.
+.IP "\fB\-m\fR, \fB\-machine\fR \fIHOST\fR" 4
+.IX Item "-m, -machine HOST"
+Filters clients by host name. Clients with a WM_CLIENT_MACHINE property
+equal to \fIHOST\fR are selected.
+.IP "\fB\-n\fR, \fB\-name\fR \fINAME\fR" 4
+.IX Item "-n, -name NAME"
+Filters clients by _NET_WM_NAME or WM_NAME.
+\&\fINAME\fR matches any part of the property value.
+To match at the beginning use a \f(CW\*(C`^\*(C'\fR prefix.
+To match at the end use a \f(CW\*(C`$\*(C'\fR suffix.
+.IP "\fB\-p\fR, \fB\-pid\fR \fIPID\fR" 4
+.IX Item "-p, -pid PID"
+Filters clients by process ID. Clients with a _NET_WM_PID property equal
+to \fIPID\fR are selected.
+.IP "\fB\-u\fR, \fB\-unmapped\fR" 4
+.IX Item "-u, -unmapped"
+Filter clients and keep those that are currently not viewable.
+These are hidden, minimized, rolled-up, or on another workspace.
+.IP "\fB\-v\fR, \fB\-viewable\fR" 4
+.IX Item "-v, -viewable"
+Filter clients and keep only those that are currently viewable.
+These clients are mapped on the current workspace.
+.IP "\fB\-G\fR, \fB\-Gravity\fR \fIGRAVITY\fR" 4
+.IX Item "-G, -Gravity GRAVITY"
+Filters clients by the window gravity field of the WM_NORMAL_HINTS
+property.  Clients with a gravity equal to \fIGRAVITY\fR are selected.
+If \fIGRAVITY\fR starts with an exclamation mark then the filtering is
+inverted.
+.IP "\fB\-L\fR, \fB\-Layer\fR \fILAYER\fR" 4
+.IX Item "-L, -Layer LAYER"
+Filters clients by \fIGNOME window layer\fR, which can either be a layer
+name or a layer number. See EXPRESSIONS below. If \fILAYER\fR starts with
+an exclamation mark then the filtering is inverted.
+.IP "\fB\-N\fR, \fB\-Netstate\fR \fISTATE\fR" 4
+.IX Item "-N, -Netstate STATE"
+Filters clients by \fIEWMH window state\fR. Clients that have at
+least an EWMH window state of \fISTATE\fR are selected.  This state
+refers to details like \fBMINIZED\fR or \fBMAXIMIZED\fR. See EXPRESSIONS
+below. If \fISTATE\fR starts with an exclamation mark then the filtering
+is inverted.  A question mark \f(CW\*(C`?\*(C'\fR filters clients with any bit set
+in \fISTATE\fR.
+.IP "\fB\-P\fR, \fB\-Property\fR \fIPROP[=value]\fR" 4
+.IX Item "-P, -Property PROP[=value]"
+Filters clients by property. Clients that have a property \fIPROP\fR
+are selected. If the optional \fIvalue\fR is given, the match succeeds
+only if \fIPROP\fR is a string, window, cardinal, or atom, with a value
+equal to \fIvalue\fR.  The filtering is inverted if \fIPROP\fR starts with
+an exclamation mark.
+.IP "\fB\-R\fR, \fB\-Role\fR \fIROLE\fR" 4
+.IX Item "-R, -Role ROLE"
+Filters clients by WM_WINDOW_ROLE. Clients that have a WM_WINDOW_ROLE
+property value equal to \fIROLE\fR are selected.  The filtering is inverted
+if \fIROLE\fR starts with an exclamation mark.
+.IP "\fB\-W\fR, \fB\-Workspace\fR \fIWORKSPACE\fR" 4
+.IX Item "-W, -Workspace WORKSPACE"
+Filter clients by workspace. Workspace \fIWORKSPACE\fR is either a
+workspace name, or a workspace number counting from zero, or the word
+\&\f(CW\*(C`this\*(C'\fR for the current workspace, or the word \f(CW\*(C`All\*(C'\fR for all workspaces.
+If \fIWORKSPACE\fR starts with an exclamation mark then the filtering is
+inverted.
+.IP "\fB\-X\fR, \fB\-Xinerama\fR \fIMONITOR\fR" 4
+.IX Item "-X, -Xinerama MONITOR"
+Limit clients by \fIRandR\fR/\fIXinerama\fR monitor. Only operate on
+clients that are displayed on \fIMONITOR\fR, where \fIMONITOR\fR can
+be \f(CW\*(C`All\*(C'\fR for all monitors, \f(CW\*(C`this\*(C'\fR for the monitor where the
+active window is displayed, or a monitor number starting from zero.
+See the output of \f(CW\*(C`randr\*(C'\fR or \f(CW\*(C`xinerama\*(C'\fR below.
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+The following options are identical for every IceWM command.
+.IP "\fB\-d\fR, \fB\-display\fR \fIDISPLAY\fR" 4
+.IX Item "-d, -display DISPLAY"
+Specifies the X11 DISPLAY.  If unspecified, defaults to \fR\f(CB$DISPLAY\fR\fB\fR.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions to \fIstdout\fR for the program and exit.
+.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
+.IX Item "-q, --quiet"
+Don't complain if no matching windows could be found.
+.SS ACTIONS
+.IX Subsection "ACTIONS"
+\&\fBicesh\fR expects one or more action arguments.  There are two kinds of
+actions: \fIwindow actions\fR and \fImanager actions\fR. The first operates on
+the selected windows. The second directly interacts with the \fBicewm\fR
+window manager.
+.SS "WINDOW ACTIONS"
+.IX Subsection "WINDOW ACTIONS"
+The following actions affect the selected window or windows.
+.IP \fBactivate\fR 4
+.IX Item "activate"
+Activate the window, aka. \fIto focus\fR.
+.IP \fBclose\fR 4
+.IX Item "close"
+Send a close request to the client that created the window.
+.IP \fBkill\fR 4
+.IX Item "kill"
+Force an immediate close down of the client that created the window.
+.IP \fBid\fR 4
+.IX Item "id"
+Print window identifiers for the selected windows.
+.IP \fBpid\fR 4
+.IX Item "pid"
+Print process identifiers for the selected windows.
+.IP \fBlist\fR 4
+.IX Item "list"
+Show window details, like geometry and names.
+.IP \fBlower\fR 4
+.IX Item "lower"
+Lower the window.
+.IP \fBraise\fR 4
+.IX Item "raise"
+Raise the window.
+.IP \fBabove\fR 4
+.IX Item "above"
+Stack the window above others.
+.IP \fBbelow\fR 4
+.IX Item "below"
+Stack the window below others.
+.IP \fBrollup\fR 4
+.IX Item "rollup"
+Rollup the specified window.
+.IP \fBfullscreen\fR 4
+.IX Item "fullscreen"
+Set the window to fullscreen.
+.IP \fBmaximize\fR 4
+.IX Item "maximize"
+Maximize the window.
+.IP \fBhorizontal\fR 4
+.IX Item "horizontal"
+Maximize the window only horizontally.
+.IP \fBvertical\fR 4
+.IX Item "vertical"
+Maximize the window only vertically.
+.IP \fBminimize\fR 4
+.IX Item "minimize"
+Minimize the window.
+.IP \fBrestore\fR 4
+.IX Item "restore"
+Restore the window to normal.
+.IP \fBhide\fR 4
+.IX Item "hide"
+Hide the window.
+.IP \fBunhide\fR 4
+.IX Item "unhide"
+Reveal the window.
+.IP \fBskip\fR 4
+.IX Item "skip"
+Don't show the window on the taskbar.
+.IP \fBunskip\fR 4
+.IX Item "unskip"
+Do show the window on the taskbar.
+.IP \fBsticky\fR 4
+.IX Item "sticky"
+Show the window on all workspaces.
+.IP \fBunsticky\fR 4
+.IX Item "unsticky"
+Show the window on just one workspace.
+.IP \fBurgent\fR 4
+.IX Item "urgent"
+Set the urgent flag to flash the task button.
+.IP "\fBresize\fR \fIWIDTH\fR \fIHEIGHT\fR" 4
+.IX Item "resize WIDTH HEIGHT"
+Resize window to \fIWIDTH\fR by \fIHEIGHT\fR window units.  For text based
+applications like terminals, a window unit is the size of a single
+character cell.
+.IP "\fBsizeto\fR \fIWIDTH\fR \fIHEIGHT\fR" 4
+.IX Item "sizeto WIDTH HEIGHT"
+Resize window to \fIWIDTH\fR by \fIHEIGHT\fR pixels. If \fIWIDTH\fR or \fIHEIGHT\fR
+ends with a percent sign \f(CW\*(C`%\*(C'\fR, then they refer to a percentage of the
+desktop work area. For instance, \f(CW\*(C`sizeto 50% 100%\*(C'\fR resizes to half
+the desktop width and whatever height is available above or below the
+taskbar.
+.IP "\fBsizeby\fR \fIWIDTH\fR \fIHEIGHT\fR" 4
+.IX Item "sizeby WIDTH HEIGHT"
+Resize window by \fIWIDTH\fR by \fIHEIGHT\fR pixels. If \fIWIDTH\fR or \fIHEIGHT\fR
+ends with a percent sign \f(CW\*(C`%\*(C'\fR, then they refer to a percentage of the
+current window size. For instance, \f(CW\*(C`sizeby 50% 200\*(C'\fR increases the width
+by 50% and increases the height by 200 pixels.
+.IP "\fBmove\fR \fIX\fR \fIY\fR" 4
+.IX Item "move X Y"
+Move the selected window or windows to the screen position \fIX\fR \fIY\fR.
+To specify \fIX\fR or \fIY\fR values relative to the right side or bottom side
+precede the value with an extra minus sign, like in \f(CW\*(C`move \-+10 \-\-20\*(C'\fR.
+.IP "\fBmoveby\fR \fIX\fR \fIY\fR" 4
+.IX Item "moveby X Y"
+Displace window by \fIX\fR \fIY\fR pixels.
+.IP \fBcenter\fR 4
+.IX Item "center"
+Position the window in the center of the desktop work area.
+.IP \fBleft\fR 4
+.IX Item "left"
+Position the window against the left side of the desktop work area.
+.IP \fBright\fR 4
+.IX Item "right"
+Position the window against the right side of the desktop work area.
+.IP \fBtop\fR 4
+.IX Item "top"
+Position the window against the top side of the desktop work area.
+.IP \fBbottom\fR 4
+.IX Item "bottom"
+Position the window against the bottom side of the desktop work area.
+.IP "\fBsetIconTitle\fR \fITITLE\fR" 4
+.IX Item "setIconTitle TITLE"
+Set the icon title to \fITITLE\fR.
+.IP \fBgetIconTitle\fR 4
+.IX Item "getIconTitle"
+Print the icon title.
+.IP "\fBsetWindowTitle\fR \fITITLE\fR" 4
+.IX Item "setWindowTitle TITLE"
+Set the window title to \fITITLE\fR.
+.IP \fBgetWindowTitle\fR 4
+.IX Item "getWindowTitle"
+Print the window title.
+.IP "\fBsetGeometry\fR \fIGEOMETRY\fR" 4
+.IX Item "setGeometry GEOMETRY"
+Set the window geometry to \fIGEOMETRY\fR.  This geometry should be
+specified in a format that can be parsed by \fBXParseGeometry\fR\|(3).
+Negative offsets are with respect to the bottom or right side of
+the screen.  Use \f(CW\*(C`+\-\*(C'\fR for a truly negative position.
+.IP \fBgetGeometry\fR 4
+.IX Item "getGeometry"
+Print the window geometry.
+.IP "\fBsetClass\fR \fICLASS\fR" 4
+.IX Item "setClass CLASS"
+Set the resource name and class to \fICLASS\fR, which should be a resource
+name and a resource class connected by a dot. To preserve either the
+existing name or class, use a percentage sign for that part.
+.IP \fBgetClass\fR 4
+.IX Item "getClass"
+Print the resource name and class.
+.IP "\fBnetState\fR \fI[STATE]\fR" 4
+.IX Item "netState [STATE]"
+If \fISTATE\fR is omitted then it shows the \fIEWMH window state\fR.
+If \fISTATE\fR starts with a \f(CW\*(C`+\*(C'\fR then flags in \fISTATE\fR are appended to
+the existing \fIEWMH window state\fR.  If \fISTATE\fR starts with a \f(CW\*(C`\-\*(C'\fR
+then flags in \fISTATE\fR are removed from the existing \fIEWMH window
+state\fR.  If \fISTATE\fR starts with a \f(CW\*(C`^\*(C'\fR then flags in \fISTATE\fR are
+toggled with respect to the existing \fIEWMH window state\fR.
+If \fISTATE\fR starts with a \f(CW\*(C`=\*(C'\fR then the \fIEWMH window state\fR
+is set to \fISTATE\fR. See EXPRESSIONS below. A list of \fIEWMH flags\fR
+can be found in the output of \f(CW\*(C`icesh symbols\*(C'\fR.
+.IP "\fBsetLayer\fR \fILAYER\fR" 4
+.IX Item "setLayer LAYER"
+Move the specified window to another \fIwindow layer\fR.
+See EXPRESSIONS below for a list of \fILAYER\fR symbols.
+.IP \fBgetLayer\fR 4
+.IX Item "getLayer"
+Print the \fIwindow layer\fR for the specified window.
+.IP "\fBsetWorkspace\fR \fIWORKSPACE\fR" 4
+.IX Item "setWorkspace WORKSPACE"
+Move the specified window to another workspace.  Select the root
+window to change the current workspace. If \fIWORKSPACE\fR is \f(CW\*(C`All\*(C'\fR
+then the specified window becomes visible on all workspaces.
+Specify \f(CW\*(C`this\*(C'\fR for the current workspace, \f(CW\*(C`next\*(C'\fR for the subsequent
+workspace or \f(CW\*(C`prev\*(C'\fR for the preceding workspace.
+.IP \fBgetWorkspace\fR 4
+.IX Item "getWorkspace"
+Print the workspace for the specified window.
+.IP "\fBopacity\fR [\fIOPACITY\fR]" 4
+.IX Item "opacity [OPACITY]"
+Print the window opacity if \fIOPACITY\fR is not given,
+otherwise set the window opacity to \fIOPACITY\fR.
+.IP "\fBsetTrayOption\fR \fITRAYOPTION\fR" 4
+.IX Item "setTrayOption TRAYOPTION"
+Set the \fIIceWM tray option\fR for the specified window to \fITRAYOPTION\fR.
+See \fIIceWM tray options\fR, below, for \fITRAYOPTION\fR symbols.
+.IP \fBgetTrayOption\fR 4
+.IX Item "getTrayOption"
+Print the \fIIceWM tray option\fR for the specified window.
+.IP "\fBsetNormalGravity\fR \fIGRAVITY\fR" 4
+.IX Item "setNormalGravity GRAVITY"
+Set the window gravity field in the WM_NORMAL_HINTS property for the
+specified window to \fIGRAVITY\fR.  See below for \fIGRAVITY\fR symbols.
+.IP \fBgetNormalGravity\fR 4
+.IX Item "getNormalGravity"
+Print the window gravity from the WM_NORMAL_HINTS property for the
+specified window.
+.IP "\fBsetWindowGravity\fR \fIGRAVITY\fR" 4
+.IX Item "setWindowGravity GRAVITY"
+Set the window gravity for the specified window to \fIGRAVITY\fR.
+See below for \fIGRAVITY\fR symbols.
+.IP \fBgetWindowGravity\fR 4
+.IX Item "getWindowGravity"
+Print the window gravity for the specified window.
+.IP "\fBsetBitGravity\fR \fIGRAVITY\fR" 4
+.IX Item "setBitGravity GRAVITY"
+Set the bit gravity> for the specified window to \fIGRAVITY\fR.
+See below for \fIGRAVITY\fR symbols.
+.IP \fBgetBitGravity\fR 4
+.IX Item "getBitGravity"
+Print the bit gravity for the specified window.
+.IP "\fBmotif\fR [\fBfuncs\fR \fIFUNCTIONS\fR | \fBdecor\fR \fIDECORATIONS\fR | \fBremove\fR]" 4
+.IX Item "motif [funcs FUNCTIONS | decor DECORATIONS | remove]"
+Query, set or modify the \f(CW\*(C`_MOTIF_WM_HINTS\*(C'\fR property for the specified
+window.  Without arguments \fBmotif\fR will show the current value, but
+only if the window has such a property. The property can be removed or
+reset with the \fBremove\fR argument. With \fBfuncs\fR and \fBdecor\fR individual
+fields of this property can be enabled or disabled. If \fIFUNCTIONS\fR or
+\&\fIDECORATIONS\fR starts with a minus or plus sign then the existing value
+is modified, otherwise it is set to the new value. Note that if \f(CW\*(C`All\*(C'\fR
+is set, other set fields are disabled and cleared fields are enabled.
+.IP \fBborderless\fR 4
+.IX Item "borderless"
+Hide the frame borders and title.
+.IP \fBbordered\fR 4
+.IX Item "bordered"
+Show the frame borders and title.
+.IP \fBdenormal\fR 4
+.IX Item "denormal"
+Remove the WM_NORMAL_HINTS property, if it exists.  This lifts
+font-size restrictions on resizing, especially for terminals.
+.IP "\fBprop\fR \fIPROPERTY\fR" 4
+.IX Item "prop PROPERTY"
+Print the value of property \fIPROPERTY\fR, if it is present.
+.IP \fBproperties\fR 4
+.IX Item "properties"
+Print all properties and their values.
+.IP \fBframe\fR 4
+.IX Item "frame"
+Print the identifier of the window frame.
+.IP \fBextents\fR 4
+.IX Item "extents"
+Print the window identifier and the frame border sizes: left, right,
+top and bottom.
+.IP \fBfocusmodel\fR 4
+.IX Item "focusmodel"
+Print the ICCCM focus model as advertised by the client window.
+This is either Locally, Passive, Globally or NoInput.
+.IP "\fBoverride\fR [\fI0|1\fR]" 4
+.IX Item "override [0|1]"
+Print the override redirect status for the window, or if either 0 or 1
+is given, then disable or enable the override redirect status.
+.IP "\fBtabto\fR \fIlabel\fR" 4
+.IX Item "tabto label"
+Move the windows as tabs to a frame that has \f(CW\*(C`frame\*(C'\fR label \fIlabel\fR.
+Such a frame is created if needed.
+.IP \fBuntab\fR 4
+.IX Item "untab"
+Move each window to its own frame, if it is currently tabbed.
+.IP "\fBloadicon\fR \fIimage.pam\fR" 4
+.IX Item "loadicon image.pam"
+Load an icon from file, which must be in the PAM image format,
+with dimensions at most 256, a depth of 4, and type \fIRGB_ALPHA\fR.
+.IP "\fBsaveicon\fR \fIfile000.pam\fR" 4
+.IX Item "saveicon file000.pam"
+Save an icon to a new file in the PAM image format. Digits are
+increased to generate a unique new filename for each window.
+.IP "\fBclick\fR \fIwindow-x\fR \fIwindow-y\fR \fIbutton\fR" 4
+.IX Item "click window-x window-y button"
+Send a button press and release event at position (\fIwindow-x\fR,
+\&\fIwindow-y\fR). A negative position is relative to the bottom right
+corner. The mouse pointer is warped to the position before sending
+the events. The button number should be between 1 and 5 inclusive.
+.IP "\fBmonitors\fR \fItop\fR \fIbottom\fR \fIleft\fR \fIright\fR" 4
+.IX Item "monitors top bottom left right"
+This sets the monitors to use for fullscreen.
+Top, bottom, left, and right are indices of the \fIicesh xinerama\fR command.
+.IP \fBspy\fR 4
+.IX Item "spy"
+Observe the selected windows and report any changes. This includes
+focus, visibility, position, size and all window properties.
+To monitor all of the protocol request messages that client applications
+may send to icewm, also spy on the root window.
+.IP \fBstacking\fR 4
+.IX Item "stacking"
+Sort the list of windows from topmost to bottom-most.
+.IP \fBreverse\fR 4
+.IX Item "reverse"
+Reverse the order of the list of windows.
+.SS "MANAGER ACTIONS"
+.IX Subsection "MANAGER ACTIONS"
+The following actions control the IceWM window manager and therefore
+do not require a window \fIselect\fR or \fIfilter\fR option:
+.IP \fBlistWorkspaces\fR 4
+.IX Item "listWorkspaces"
+List the names of all workspaces.
+.IP \fBcurrent\fR 4
+.IX Item "current"
+Show the number and name of the current workspace.
+.IP "\fBgoto\fR \fIWORKSPACE\fR" 4
+.IX Item "goto WORKSPACE"
+Change the current workspace to \fIWORKSPACE\fR. Specify \f(CW\*(C`next\*(C'\fR for the
+subsequent workspace or \f(CW\*(C`prev\*(C'\fR for the preceding workspace.
+.IP "\fBworkspaces\fR [\fICOUNT\fR]" 4
+.IX Item "workspaces [COUNT]"
+Print the number of workspaces if \fICOUNT\fR is not given,
+otherwise set the number of workspaces to \fICOUNT\fR.
+.IP "\fBsetWorkspaceName\fR \fIINDEX\fR \fINAME\fR" 4
+.IX Item "setWorkspaceName INDEX NAME"
+Change the name of the workspace \fIINDEX\fR to \fINAME\fR, where \fIINDEX\fR is
+a workspace number starting from zero.
+.IP "\fBsetWorkspaceNames\fR \fINAME\fR [\fINAME\fR]*" 4
+.IX Item "setWorkspaceNames NAME [NAME]*"
+Change the workspace names to the list of \fINAME\fRs.
+.IP "\fBaddWorkspace\fR \fINAME\fR" 4
+.IX Item "addWorkspace NAME"
+Create a new workspace with name \fINAME\fR.
+.IP "\fBdesktop\fR [\fISHOWING\fR]" 4
+.IX Item "desktop [SHOWING]"
+If \fISHOWING\fR is \f(CW1\fR then set \f(CW\*(C`showing the desktop\*(C'\fR mode.
+If \fISHOWING\fR is \f(CW0\fR then turn off \f(CW\*(C`showing the desktop\*(C'\fR.
+Print the current mode if \fISHOWING\fR is not given.
+.IP \fBworkarea\fR 4
+.IX Item "workarea"
+Print the dimensions of the work area for the current workspace.
+This is the desktop, but minus space occupied by dock and panel windows.
+.IP \fBrandr\fR 4
+.IX Item "randr"
+Summarize the \fIRandR\fR configuration.
+.IP \fBxinerama\fR 4
+.IX Item "xinerama"
+Summarize the \fIXinerama\fR configuration.
+.IP \fBcheck\fR 4
+.IX Item "check"
+Print information about the current window manager, like name,
+version, class, locale, command, host name and pid.
+.IP \fBclients\fR 4
+.IX Item "clients"
+List all managed client windows, their titles and geometries.
+.IP \fBshown\fR 4
+.IX Item "shown"
+List all mapped client windows for the current desktop,
+their titles and geometries.
+.IP \fBwindows\fR 4
+.IX Item "windows"
+List all toplevel windows, their titles and geometries.
+.IP \fBsystray\fR 4
+.IX Item "systray"
+List applications that are managed by the IceWM system tray.
+.IP \fBxembed\fR 4
+.IX Item "xembed"
+List application windows that are embedded using the \fIXEMBED\fR protocol.
+This is another way to discover system tray applications.
+.IP \fBlogout\fR 4
+.IX Item "logout"
+Let icewm execute the \f(CW\*(C`LogoutCommand\*(C'\fR.
+.IP \fBreboot\fR 4
+.IX Item "reboot"
+Let icewm execute the \f(CW\*(C`RebootCommand\*(C'\fR.
+.IP \fBshutdown\fR 4
+.IX Item "shutdown"
+Let icewm execute the \f(CW\*(C`ShutdownCommand\*(C'\fR.
+.IP \fBcancel\fR 4
+.IX Item "cancel"
+Let icewm cancel the logout/reboot/shutdown.
+.IP \fBabout\fR 4
+.IX Item "about"
+Let icewm show the about window.
+.IP \fBwindowlist\fR 4
+.IX Item "windowlist"
+Let icewm show the window list window.
+.IP \fBrestart\fR 4
+.IX Item "restart"
+Let icewm restart itself.
+.IP \fBsuspend\fR 4
+.IX Item "suspend"
+Let icewm execute the \f(CW\*(C`SuspendCommand\*(C'\fR.
+.IP \fBhibernate\fR 4
+.IX Item "hibernate"
+Let icewm execute the \f(CW\*(C`HibernateCommand\*(C'\fR.
+.IP \fBwinoptions\fR 4
+.IX Item "winoptions"
+Let icewm reload the \f(CW\*(C`winoptions\*(C'\fR.
+.IP \fBkeys\fR 4
+.IX Item "keys"
+Let icewm reload the \f(CW\*(C`keys\*(C'\fR file.
+.IP \fBrefresh\fR 4
+.IX Item "refresh"
+Let icewm refresh the desktop background.
+.IP \fBguievents\fR 4
+.IX Item "guievents"
+Monitor the \fBICEWM_GUI_EVENT\fR property and report all changes.
+Hit \f(CW\*(C`Ctrl+C\*(C'\fR to abort this and continue with the next command.
+.IP "\fBdelay\fR [\fItime\fR]" 4
+.IX Item "delay [time]"
+Stop execution for \fItime\fR or 0.1 seconds.
+.IP "\fBrunonce\fR \fIprogram\fR [\fIarguments...\fR]" 4
+.IX Item "runonce program [arguments...]"
+This action is meant to be used together with the \fB\-class\fR option.
+Only if no window is matched by \fIWM_CLASS\fR then
+\&\fIprogram\fR [\fIarguments...\fR] is executed.
+.IP "\fBloop\fR [\fIcount\fR]" 4
+.IX Item "loop [count]"
+Loop back to the beginning of the command and repeat. The optional
+\&\fIcount\fR limits the number of repetitions.
+.IP \fBpick\fR 4
+.IX Item "pick"
+Choose a window by a mouse button click.
+.IP \fBsync\fR 4
+.IX Item "sync"
+Synchronize with the IceWM window manager. That is, wait for icewm to
+process all previous actions.
+.IP \fBsymbols\fR 4
+.IX Item "symbols"
+List all named symbols.
+.SS CONDITIONALS
+.IX Subsection "CONDITIONALS"
+Icesh supports \f(CW\*(C`if\-then\-else\*(C'\fR expressions. The full syntax is:
+.PP
+.Vb 9
+\&    if selection
+\&    then
+\&        actions
+\&    elif selection
+\&    then
+\&        actions
+\&    else
+\&        actions
+\&    end
+.Ve
+.PP
+Where \f(CW\*(C`selection\*(C'\fR is a sequence of selection and filtering options,
+which evaluates to \fBtrue\fR when it is non-empty. That is, if one or more
+windows fulfilled the condition. If it is empty, then its \f(CW\*(C`actions\*(C'\fR
+clause is ignored and the subsequent \f(CW\*(C`elif\*(C'\fR or \f(CW\*(C`else\*(C'\fR clause is tried
+or taken. Each clause is optional.
+.PP
+Whenever a selection condition evaluates to \fBfalse\fR, the window selection
+that existed before the \f(CW\*(C`if\*(C'\fR clause is immediately restored.  This also
+happens after an \f(CW\*(C`end\*(C'\fR clause.
+.SS EXPRESSIONS
+.IX Subsection "EXPRESSIONS"
+Some of the window actions require one or two \fIEXPRESSION\fR arguments.
+.ie n .IP "\fBEXPRESSION\fR ::= \fISYMBOL\fR | \fIEXPRESSION\fR { ""+"" | ""|"" } \fISYMBOL\fR" 4
+.el .IP "\fBEXPRESSION\fR ::= \fISYMBOL\fR | \fIEXPRESSION\fR { \f(CW+\fR | \f(CW|\fR } \fISYMBOL\fR" 4
+.IX Item "EXPRESSION ::= SYMBOL | EXPRESSION { + | | } SYMBOL"
+.PP
+Each \fISYMBOL\fR may be from one of the following applicable domains:
+.IP "\fIWindow layer\fR" 4
+.IX Item "Window layer"
+Named symbols of the domain \fIWindow layer\fR (numeric range: 0\-15):
+.Sp
+.Vb 9
+\&    Desktop                (0)
+\&    Below                  (2)
+\&    Normal                 (4)
+\&    OnTop                  (6)
+\&    Dock                   (8)
+\&    AboveDock             (10)
+\&    Menu                  (12)
+\&    Fullscreen            (14)
+\&    AboveAll              (15)
+.Ve
+.Sp
+These symbols are used with the \fILAYER\fR argument to the \f(CW\*(C`setLayer\*(C'\fR
+action.
+.IP "\fIIceWM tray option\fR" 4
+.IX Item "IceWM tray option"
+Named symbols of the domain \fIIceWM tray option\fR (numeric range: 0\-2):
+.Sp
+.Vb 3
+\&    Ignore                 (0)
+\&    Minimized              (1)
+\&    Exclusive              (2)
+.Ve
+.Sp
+These symbols are used with the \fITRAYOPTION\fR argument to the
+\&\f(CW\*(C`setTrayOption\*(C'\fR action.
+.IP "\fIGravity symbols\fR" 4
+.IX Item "Gravity symbols"
+Named symbols for window and bit gravity (numeric range: 0\-10):
+.Sp
+.Vb 11
+\&    ForgetGravity         (0)
+\&    NorthWestGravity      (1)
+\&    NorthGravity          (2)
+\&    NorthEastGravity      (3)
+\&    WestGravity           (4)
+\&    CenterGravity         (5)
+\&    EastGravity           (6)
+\&    SouthWestGravity      (7)
+\&    SouthGravity          (8)
+\&    SouthEastGravity      (9)
+\&    StaticGravity         (10)
+.Ve
+.IP "\fIMotif functions\fR" 4
+.IX Item "Motif functions"
+.Vb 6
+\&    All                  (1)
+\&    Resize               (2)
+\&    Move                 (4)
+\&    Minimize             (8)
+\&    Maximize             (16)
+\&    Close                (32)
+.Ve
+.IP "\fIMotif decorations\fR" 4
+.IX Item "Motif decorations"
+.Vb 7
+\&    All                  (1)
+\&    Border               (2)
+\&    Resize               (4)
+\&    Title                (8)
+\&    Menu                 (16)
+\&    Minimize             (32)
+\&    Maximize             (64)
+.Ve
+.IP "\fIEWMH window state symbols\fR" 4
+.IX Item "EWMH window state symbols"
+Named symbols of the domain \fIEWMH state\fR (numeric range:
+0\-8191):
+.Sp
+.Vb 10
+\&    ABOVE                 (1)
+\&    BELOW                 (2)
+\&    DEMANDS_ATTENTION     (4)
+\&    FOCUSED               (8)
+\&    FULLSCREEN            (16)
+\&    HIDDEN                (32)
+\&    MAXIMIZED_HORZ        (64)
+\&    MAXIMIZED_VERT        (128)
+\&    MODAL                 (256)
+\&    SHADED                (512)
+\&    SKIP_PAGER            (1024)
+\&    SKIP_TASKBAR          (2048)
+\&    STICKY                (4096)
+.Ve
+.SS EXAMPLES
+.IX Subsection "EXAMPLES"
+List all workspace names:
+.PP
+.Vb 1
+\&    icesh listWorkspaces
+.Ve
+.PP
+Example output:
+.PP
+.Vb 4
+\&    workspace #0: \`main\*(Aq
+\&    workspace #1: \`web\*(Aq
+\&    workspace #2: \`doc\*(Aq
+\&    workspace #3: \`dev\*(Aq
+.Ve
+.PP
+Close terminal work and activate terminal fun.
+.PP
+.Vb 1
+\&    icesh \-c work.XTerm close \-a \-c fun.XTerm activate
+.Ve
+.PP
+Print opacity for all xterms.
+.PP
+.Vb 1
+\&    icesh \-c XTerm opacity
+.Ve
+.PP
+Change opacity for all xterms.
+.PP
+.Vb 1
+\&    icesh \-c XTerm opacity 84
+.Ve
+.PP
+Move all windows on workspace "Top" to the current workspace.
+.PP
+.Vb 1
+\&    icesh \-W "Top" setWorkspace "this"
+.Ve
+.PP
+Restore all hidden clients, minimize all clients on the current
+workspace and activate Firefox.
+.PP
+.Vb 1
+\&    icesh \-N HIDDEN restore \-a \-W "this" minimize \-a \-c Firefox activate
+.Ve
+.PP
+Resize the focused window to occupy the right half of the desktop area.
+.PP
+.Vb 1
+\&    icesh \-f sizeto 49% 100% top right raise
+.Ve
+.PP
+Toggle the frame border of the focused window.
+.PP
+.Vb 2
+\&    if icesh \-f motif | grep \-q \*(Aqdecor:$\*(Aq; then \e
+\&        icesh \-f motif decor All; else icesh \-f motif decor ""; fi
+.Ve
+.PP
+Here is a different solution using conditionals.
+.PP
+.Vb 1
+\&    icesh \-f if \-P _NET_FRAME_EXTENTS=0 then bordered else borderless
+.Ve
+.PP
+Here is a conditional to either toggle the visibility of a roxterm
+that has a WM_ROLE value of \f(CW\*(C`special\*(C'\fR or start it with \fBrunonce\fR.
+.PP
+.Vb 4
+\&    icesh if \-c roxterm.Roxterm \-R special then \e
+\&        if \-v then hide \e
+\&        elif \-u then setWorkspace this activate end \e
+\&        else runonce roxterm \-\-role=special
+.Ve
+.PP
+Collect all urxvt terminals from the fourth workspace in a single frame
+on the current workspace.
+.PP
+.Vb 1
+\&    icesh \-W 3 \-c urxvt tabto myfunnyname
+.Ve
+.PP
+Use the loop construct conditionally to wait for a certain window to
+appear.
+.PP
+.Vb 1
+\&    icesh \-t if \-n Tooltip then list else delay 0.05 loop end
+.Ve
+.SS ENVIRONMENT
+.IX Subsection "ENVIRONMENT"
+.IP \fBDISPLAY\fR 4
+.IX Item "DISPLAY"
+The default display.
+.SS "EXIT STATUS"
+.IX Subsection "EXIT STATUS"
+.IP \fB0\fR 4
+.IX Item "0"
+The last action completed successfully.
+.IP \fB1\fR 4
+.IX Item "1"
+The last action completed unsuccessfully, or no window met the condition.
+.IP \fB2\fR 4
+.IX Item "2"
+A conditional has invalid syntax.
+.IP \fB3\fR 4
+.IX Item "3"
+The display could not be opened.
+.IP \fB4\fR 4
+.IX Item "4"
+The X server reports an error while processing a request.
+.SS COMPLIANCE
+.IX Subsection "COMPLIANCE"
+\&\fBicesh\fR is largely compliant with the EWMH and ICCCM specifications.
+Some commands, like manager actions, are specific to IceWM.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+\&\fBicewm\fR\|(1), \fBwmctrl\fR\|(1), \fBxdotool\fR\|(1), \fBxprop\fR\|(1),
+\&\fBxwininfo\fR\|(1), \fBXParseGeometry\fR\|(3).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewm-menu-fdo.1 b/upstream/mageia-cauldron/man1/icewm-menu-fdo.1
new file mode 100644
index 00000000..afd2b271
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewm-menu-fdo.1
@@ -0,0 +1,190 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWM-MENU-FDO 1"
+.TH ICEWM-MENU-FDO 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewm\-menu\-fdo \- menu generator for .desktop files
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewm-menu-fdo\fR [\fIOPTIONS\fR] [\fIFILENAME\fR]
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewm-menu-fdo\fR generates a menu for the \fBIceWM\fR window manager
+from XDG menu descriptors (aka FreeDesktop.Org \fI.desktop\fR files).
+By including this in the \fBicewm\-menu\fR\|(1), the system applications
+become available in the icewm start menu.
+.SS ARGUMENTS
+.IX Subsection "ARGUMENTS"
+.IP [\fIFILENAME\fR] 4
+.IX Item "[FILENAME]"
+The optional \fIFILENAME\fR argument is the location of a \fI.desktop\fR file.
+When given, \fBicewm-menu-fdo\fR launches the application using the \f(CW\*(C`Exec\*(C'\fR
+line from the desktop file.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.IP "\fB\-g\fR, \fB\-\-generic\fR" 4
+.IX Item "-g, --generic"
+Include the generic name in parentheses in the title of \fBprog\fR entries.
+.IP \fB\-\-seps\fR 4
+.IX Item "--seps"
+Print a leading and a trailing separator.
+.IP \fB\-\-sep\-before\fR 4
+.IX Item "--sep-before"
+Print a leading separator.
+.IP \fB\-\-sep\-after\fR 4
+.IX Item "--sep-after"
+Print a trailing separator.
+.IP \fB\-\-no\-sep\-others\fR 4
+.IX Item "--no-sep-others"
+Don't print the \f(CW\*(C`Other\*(C'\fR category last.
+.IP \fB\-\-no\-sub\-cats\fR 4
+.IX Item "--no-sub-cats"
+Don't nest subcategories in submenus.
+.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
+.IX Item "-o, --output=FILE"
+Write the output to \fIFILE\fR.
+.IP "\fB\-t\fR, \fB\-\-terminal=NAME\fR" 4
+.IX Item "-t, --terminal=NAME"
+Use \fINAME\fR to start a terminal emulator that supports the '\-e' option.
+.IP \fB\-\-flat\fR 4
+.IX Item "--flat"
+Display apps from all categories in one level with the title containing
+the category information as prefix.
+.IP "\fB\-F sep\fR, \fB\-\-flat\-sep=sep\fR" 4
+.IX Item "-F sep, --flat-sep=sep"
+When used with \f(CW\*(C`\-\-flat\*(C'\fR, the specified character sequence is used as
+separator between the section titles.
+.IP "\fB\-m filter\fR, \fB\-\-match=filter\fR" 4
+.IX Item "-m filter, --match=filter"
+Specifies a filter to show only apps that contain this as substring
+within their title.
+.IP "\fB\-M filter\fR, \fB\-\-imatch=filter\fR" 4
+.IX Item "-M filter, --imatch=filter"
+Like \f(CW\*(C`\-\-match\*(C'\fR but applied with any letter case.
+.IP \fB\-\-match\-sec\fR 4
+.IX Item "--match-sec"
+Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to both, apps and
+section titles.
+.IP \fB\-\-match\-osec\fR 4
+.IX Item "--match-osec"
+Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to only to section titles.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions to \fIstdout\fR for the program and exit.
+.SS USAGE
+.IX Subsection "USAGE"
+This utility is not normally used directly. It is used as the
+executable in a \fBmenuprog\fR entry in a \fBicewm\-menu\fR\|(5).
+.SS EXAMPLES
+.IX Subsection "EXAMPLES"
+The following line in a \fBicewm\-menu\fR\|(5) file will dynamically generate
+a comprehensive set of menus for easy access to \fI.desktop\fR files.
+.PP
+.Vb 1
+\&    menuprog "Desktop Apps" folder icewm\-menu\-fdo
+.Ve
+.SS ENVIRONMENT
+.IX Subsection "ENVIRONMENT"
+\&\fBXDG_DATA_HOME\fR or \fBXDG_DATA_DIRS\fR are considered as suggested by XDG
+Base Directory Specification.
+.PP
+\&\fBTERMINAL\fR may define a terminal emulator that supports the '\-e' option.
+.SS "CONFORMING TO"
+.IX Subsection "CONFORMING TO"
+\&\fBicewm-menu-fdo\fR complies roughly to the XDG \fI.desktop\fR file and menu
+specification, see "Desktop Entry Specification", Version 1.2alpha,
+2015\-03\-06 and "Desktop Menu Specification", Version 1.1\-draft, 31
+March 2011.
+.SS CAVEATS
+.IX Subsection "CAVEATS"
+The \fBicewm-menu-fdo\fR program is only built when the \fBicewm\fR\|(1) package
+is configured with the \fB\-\-enable\-menus\-fdo\fR option, which requires the
+\&\fBglib2\-dev\fR package dependency.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+"Desktop Entry Specification",
+"Desktop Menu Specification",
+\&\fBicewm\fR\|(1),
+\&\fBicewm\-menu\fR\|(5),
+\&\fBicewm\-preferences\fR\|(5),
+\&\fBicewm\-programs\fR\|(5).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Eduard Bloch <mailto:edi@gmx.de>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewm-menu-xrandr.1 b/upstream/mageia-cauldron/man1/icewm-menu-xrandr.1
new file mode 100644
index 00000000..98fdce2b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewm-menu-xrandr.1
@@ -0,0 +1,141 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWM-MENU-XRANDR 1"
+.TH ICEWM-MENU-XRANDR 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewm\-menu\-xrandr \- IceWM menu provider for multi\-monitor setup shortcuts
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewm-menu-xrandr\fR
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewm-menu-xrandr\fR is a helper to manage multi-screen configurations
+in a semi-automated way. It is a regular icewm menu generator that
+detects the available xrandr screens (i.e. connected monitors) and
+creates menu entries that call the xrandr command to setup this
+configuration.
+.PP
+Optionally, the contents of the generated configurations can be accessed
+on-the-fly through a "quick-switch" style menu which pops up upon
+pressing Super-P key binding (or a manually configured key, see
+\&\fBicewm\-keys\fR\|(5) for the configuration of \fBswitchkey\fR directive).
+.PP
+The tool does not examine the exact monitor resolutions, refresh rates
+or screen orientation. For this matters it uses auto selected mode by
+default. However, it is possible to replace the custom option selection
+for each output using \fIxrandr\fR options in a custom configuration file
+(see \fICONFIGURATION\fR below). Also tuning specific options like
+\&\-\-brightness and \-\-gamma is possible there.
+.PP
+The displayed name of the monitors is constructed using the output name
+and the monitor information from its EDID data. Either from its "Display
+Name" field or from the "Unspecified ASCII text" fields (concatenated).
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.IP \fB\-\-max\fR 4
+.IX Item "--max"
+Obsolete and ineffective option. Used to select the \fIxrandr\fR mode with the
+highest detected refresh rate. However, the maximum rate might cause
+problems, therefore the explicit configuration in the \fIINI file\fR should be
+used now, see \fICONFIGURATION\fR.
+.IP "\fB\-\-auto\-number [ init value ]\fR" 4
+.IX Item "--auto-number [ init value ]"
+Adding a auto-incremented numbered prefix to each display name,
+optionally started at the specified value. This mostly useful for menu
+creation.
+.IP "\fB\-\-xrandr command\fR" 4
+.IX Item "--xrandr command"
+Replacement for \fIxrandr\fR command that should deliver equivalent data
+and accept the same options as \fIxrandr\fR.
+.IP "\fB\-\-activate combo-name\fR" 4
+.IX Item "--activate combo-name"
+A shortcut to run the activation command of the specified combo, just
+like \fIIceWM\fR would run the commmand when selected from the menu or
+quick-switch dialog. The \fIcombo-name\fR parameter needs to match the
+displayed name exactly.
+.SS CONFIGURATION
+.IX Subsection "CONFIGURATION"
+Optionally, a local configuration can specify command line options to
+\&\fIxrandr\fR calls, and further commands to run after mode switching.
+.PP
+Refer to configuration examples (\fIxrandr_menu\fR) in \fIicewm\fR
+documentation or its contrib folder for the syntax and rules of that
+file. It can be placed into \fR\f(CI$HOME\fR\fI/.config/icewm\fR or into
+\&\fI\fR\f(CI$HOME\fR\fI/.icewm\fR or wherever \fI\fR\f(CI$XDG_CONFIG_HOME\fR\fI/.config/icewm\fR might
+resolve to.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+\&\fBicewm\fR\|(1),
+\&\fBxrandr\fR\|(1).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Eduard Bloch <mailto:edi@gmx.de>.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBicewm-menu-xrandr\fR is licensed under the Simplified BSD License.
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution.
diff --git a/upstream/mageia-cauldron/man1/icewm-session.1 b/upstream/mageia-cauldron/man1/icewm-session.1
new file mode 100644
index 00000000..45cd5759
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewm-session.1
@@ -0,0 +1,185 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWM-SESSION 1"
+.TH ICEWM-SESSION 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewm\-session \- X.Org session manager provider with IceWM
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewm-session\fR [\fIOPTIONS\fR]
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+icewm-session is an implementation of a X.Org session manager and can be
+run from a X11 session setup. It runs \fBicewm\fR as default window manager
+and controls the life cycle of related support applications.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.SS "SPECIFIC OPTIONS"
+.IX Subsection "SPECIFIC OPTIONS"
+.IP "\fB\-c\fR, \fB\-\-config=FILE\fR" 4
+.IX Item "-c, --config=FILE"
+Let IceWM load preferences from \fIFILE\fR.
+.IP "\fB\-t\fR, \fB\-\-theme=FILE\fR" 4
+.IX Item "-t, --theme=FILE"
+Let IceWM load the theme \fIFILE\fR.
+.IP "\fB\-i\fR, \fB\-\-icewm=FILE\fR" 4
+.IX Item "-i, --icewm=FILE"
+Use \fIFILE\fR as the IceWM window manager.
+.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
+.IX Item "-o, --output=FILE"
+Redirect all output to \fIFILE\fR.
+A leading tilde or environment variable is expanded.
+.IP "\fB\-a\fR, \fB\-\-alpha\fR" 4
+.IX Item "-a, --alpha"
+Use a 32\-bit visual for translucency.
+.IP "\fB\-b\fR, \fB\-\-nobg\fR" 4
+.IX Item "-b, --nobg"
+Do not start icewmbg.
+.IP "\fB\-n\fR, \fB\-\-notray\fR" 4
+.IX Item "-n, --notray"
+Do not start icewmtray.
+This is only applicable if IceWM was explicitly configured
+to use an external icewmtray process.
+.IP "\fB\-s\fR, \fB\-\-sound\fR" 4
+.IX Item "-s, --sound"
+Also start icesound.
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
+.IX Item "-d, --display=DISPLAY"
+Use \fIDISPLAY\fR to connect to the X server.
+If this option is missing then \fIDISPLAY\fR
+is read from the environment variable \f(CW\*(C`DISPLAY\*(C'\fR.
+.IP \fB\-\-sync\fR 4
+.IX Item "--sync"
+Use a slower synchronous mode communication with the \fIX11\fR server.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Give a list of all supported options and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions and exit.
+.SS "DEBUGGING OPTIONS"
+.IX Subsection "DEBUGGING OPTIONS"
+.IP "\fB\-v\fR, \fB\-\-\-valgrind\fR" 4
+.IX Item "-v, ---valgrind"
+Let \f(CW\*(C`/usr/bin/valgrind\*(C'\fR run icewm.
+Thoroughly examines the execution of icewm.
+.IP "\fB\-g\fR, \fB\-\-\-catchsegv\fR" 4
+.IX Item "-g, ---catchsegv"
+Let \f(CW\*(C`/usr/bin/catchsegv\*(C'\fR run icewm.
+Gives a backtrace if icewm segfaults.
+.SS USAGE
+.IX Subsection "USAGE"
+On startup icewm-session executes the following steps.
+From the file \fIenv\fR in the configuration directory
+it loads additional environment variables, if that file exists.
+Then it will start \fIicewmbg\fR to manage root background colors and images.
+It may also start \fIicesound\fR, if this was enabled at configuration time.
+Then \fIicewm\fR is started.
+.PP
+If there exists an executable script \fIstartup\fR in the configuration
+directory, it will be executed. It may contain commands to initialize X11
+settings with \fIxset\fR, load keyboard configuration, start a compositing
+manager like \fIcompton\fR and load system tray applications.
+.PP
+When icewm exits, icewm-session will execute a \fIshutdown\fR script,
+if it exists in the configuration directory.
+When this finishes, icewm-session will terminate icewm, icewmbg
+and icesound. Finally, icewm-session will exit.
+.PP
+If the icewm process crashes then icewm-session will attempt to restart
+it. If two such crashes occur in a short period, then icewm-session will
+attempt to popup a dialog using either \fIyad\fR, \fIxmessage\fR, \fIkdialog\fR
+or \fIzenity\fR.  This dialog presents a choice between restarting icewm,
+starting a terminal, or abort execution of icewm-session.
+.SS ENVIRONMENT
+.IX Subsection "ENVIRONMENT"
+.IP \fBICEWM_OPTIONS\fR 4
+.IX Item "ICEWM_OPTIONS"
+A space separated list of options that will be added to the command
+line invocation of \fIicewm\fR. This can be set in the \fIenv\fR file.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+\&\fBicewm\fR\|(1),
+\&\fBicewm\-env\fR\|(5),
+\&\fBicewm\-shutdown\fR\|(5),
+\&\fBicewm\-startup\fR\|(5),
+\&\fBicewmbg\fR\|(1).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewm-set-gnomewm.1 b/upstream/mageia-cauldron/man1/icewm-set-gnomewm.1
new file mode 100644
index 00000000..3b22c268
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewm-set-gnomewm.1
@@ -0,0 +1,97 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWM-SET-GNOMEWM 1"
+.TH ICEWM-SET-GNOMEWM 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewm\-set\-gnomewm \- modify GNOME settings to use IceWM
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewm-set-gnomewm\fR [\fIOPTIONS\fR]
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewm-set-gnomewm\fR is a helper script that instruments GNOME to
+replace its own WM with icewm.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewm.1 b/upstream/mageia-cauldron/man1/icewm.1
new file mode 100644
index 00000000..5d04293e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewm.1
@@ -0,0 +1,1418 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWM 1"
+.TH ICEWM 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewm \- lightweight X11 window manager
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewm\fR [\fIOPTIONS\fR]
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewm\fR is a window manager for the X11 window system.
+It aims to be small, fast and familiar to new users.
+.PP
+\&\fBicewm\fR is called a re-parenting window manager,
+because it draws small frames around application windows.
+By dragging this frame with the mouse, windows are resized or moved.
+.PP
+Because windows may overlap, \fBicewm\fR is also a stacking window manager.
+Many windows may exist, some hidden behind others.
+.PP
+\&\fBicewm\fR supports a configurable number of virtual desktops.  These are
+called workspaces. Related windows are grouped on a dedicated workspace.
+By switching between workspaces, the user can attend to different tasks,
+while keeping oversight.  This is supported by a task bar and a pager.
+.PP
+The installation comes with several themes. Choose a theme via a menu.
+.PP
+\&\fBicewm\fR is compliant with the ICCCM and EWMH window manager specifications.
+.SS PROGRAMS
+.IX Subsection "PROGRAMS"
+The \fBicewm\fR package includes several programs:
+.IP \fBicewm\fR\|(1) 4
+.IX Item "icewm"
+The actual window manager. It positions application windows on screen
+and decorates them with borders. It gives input focus to the current
+active application. \fBicewm\fR supports different focus modes, which are
+explained below. It draws a small task bar at the bottom of the screen,
+that gives easy access to programs, to virtual desktops, to active
+applications, and to a small set of monitoring applets.
+.IP \fBicewmbg\fR\|(1) 4
+.IX Item "icewmbg"
+The background setting application. It can assign plain background color
+or images in different formats to the X background.  Each workspace can
+have its own background.  It supports semitransparency. Semitransparent
+background image and colour can be configured. When the background image
+has changed then \fBicewmbg\fR\|(1) can be notified to update the background.
+Multi-head monitor setups are fully supported.  See the \fBicewmbg\fR\|(1).
+.IP \fBicewm\-session\fR\|(1) 4
+.IX Item "icewm-session"
+\&\fBicewm\-session\fR\|(1) is the preferred program to start the IceWM system.
+It first loads additional environment variables from the optional
+\&\fIenv\fR file. Then it starts \fBicewmbg\fR\|(1) and \fBicewm\fR. It also runs
+the \fIstartup\fR script and implements basic session management.
+On termination the \fIshutdown\fR script will be run first, then
+\&\fBicewm\-session\fR\|(1) will terminate \fBicewm\fR and \fBicewmbg\fR\|(1).
+\&\fBicewm\-session\fR\|(1) will also start the optional \fBicesound\fR\|(1)
+if you give it the \fB\-\-sound\fR option.  See \fBicewm\-session\fR\|(1).
+.IP \fBicesh\fR\|(1) 4
+.IX Item "icesh"
+A powerful tool to control window properties and to interact with the
+window manager. It is typically used in shell scripts. See \fBicesh\fR\|(1).
+.IP \fBicehelp\fR\|(1) 4
+.IX Item "icehelp"
+A small document browser that is used by \fBicewm\fR to display the
+\&'IceWM manual' and some man pages.
+.IP \fBicewmhint\fR\|(1) 4
+.IX Item "icewmhint"
+A utility for passing IceWM-specific window options to \fBicewm\fR.
+The options are used to configure the first application that is started
+subsequently.  See \fBicewmhint\fR\|(1).
+.IP \fBicesound\fR\|(1) 4
+.IX Item "icesound"
+Plays audio files on GUI events that are raised by \fBicewm\fR.
+It supports ALSA, AO and OSS.  See the \fBicesound\fR\|(1) man page.
+.IP \fBicewm\-menu\-fdo\fR\|(1) 4
+.IX Item "icewm-menu-fdo"
+Generate an \fBicewm\fR menu with executable desktop applications
+according to XDG specifications. See the \fBicewm\-menu\-fdo\fR\|(1) man page.
+.IP \fBicewm\-set\-gnomewm\fR\|(1) 4
+.IX Item "icewm-set-gnomewm"
+Configures GNOME to start IceWM instead of its own WM.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.SS "COMMON OPTIONS"
+.IX Subsection "COMMON OPTIONS"
+Each of the IceWM executables supports the following options:
+.IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4
+.IX Item "-c, --config=FILE"
+Use \fIFILE\fR as the source of configuration options.  By default \fBicewm\fR
+looks for a file named \fIpreferences\fR.  This is a readable text file
+that can be modified with the help of a text editor.
+.IP "\fB\-t\fR, \fB\-\-theme\fR=\fINAME\fR" 4
+.IX Item "-t, --theme=NAME"
+Use \fINAME\fR as the name of the \fBicewm\fR theme to use.  A theme defines
+the look and feel of \fBicewm\fR, like colors, fonts and buttons.
+.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
+.IX Item "-d, --display=DISPLAY"
+Connect to the X11 server on \fIDISPLAY\fR.  By default
+the environment variable \f(CW\*(C`DISPLAY\*(C'\fR is used.
+.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
+.IX Item "-o, --output=FILE"
+Redirect all output to \fIFILE\fR.
+A leading tilde or environment variable is expanded.
+.IP \fB\-\-sync\fR 4
+.IX Item "--sync"
+This option specifies to use a slower synchronous communication mode
+with the X11 server.  This is irrelevant for normal use.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Gives a complete list of all the available command-line options with
+some very brief explanation.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Shows the software release version for this program.
+.SS "ICEWM OPTIONS"
+.IX Subsection "ICEWM OPTIONS"
+The \fBicewm\fR program supports some additional options:
+.IP "\fB\-a\fR, \fB\-\-alpha\fR" 4
+.IX Item "-a, --alpha"
+Use a 32\-bit visual for translucency. This can also be set in
+the preferences file as \f(CW\*(C`Alpha=1\*(C'\fR.
+.IP \fB\-\-replace\fR 4
+.IX Item "--replace"
+Instructs \fBicewm\fR to replace an existing window manager.  Provided that
+the window manager being replaced is ICCCM 2.0 compliant, once it
+notices that it is to be replaced it will cease operations and typically
+stop execution.  This allows \fBicewm\fR to establish itself as the only
+active window manager.
+.IP "\fB\-r\fR, \fB\-\-restart\fR" 4
+.IX Item "-r, --restart"
+Tell \fBicewm\fR to restart itself. This reloads the configuration from
+file. If no window manager is active, then it starts one.
+.IP "\fB\-s\fR, \fB\-\-splash\fR=\fIIMAGE\fR" 4
+.IX Item "-s, --splash=IMAGE"
+Briefly show \fIIMAGE\fR on startup in the center of the screen.
+This can also be set in the preferences file as Splash=\f(CW\*(C`image.jpg\*(C'\fR.
+.IP \fB\-\-configured\fR 4
+.IX Item "--configured"
+Shows a list of configuration options that were enabled when \fBicewm\fR
+was compiled from source code.  This can be helpful if one suspects some
+functionality may be missing.
+.IP \fB\-\-directories\fR 4
+.IX Item "--directories"
+Gives a list of directories where \fBicewm\fR will look for configuration
+data.  This list is printed in the actual order in which \fBicewm\fR uses
+it to search for configuration files.
+.IP "\fB\-l\fR, \fB\-\-list\-themes\fR" 4
+.IX Item "-l, --list-themes"
+\&\fBicewm\fR will search all the configuration directories for theme files
+and print a list of all found themes.
+.IP "\fB\-p\fR, \fB\-\-postpreferences\fR" 4
+.IX Item "-p, --postpreferences"
+This gives a long list of all the internal \fBicewm\fR options with their
+actual values after \fBicewm\fR has processed all of the configuration and
+theme files. In some advanced scenarios this can be helpful to inspect
+which configuration was chosen or whether option formatting was correct.
+.IP \fB\-\-rewrite\-preferences\fR 4
+.IX Item "--rewrite-preferences"
+Overwrite an existing preferences file with an icewm default preferences,
+but preserve all modifications insofar they deviate from the defaults.
+.IP \fB\-\-extensions\fR 4
+.IX Item "--extensions"
+Give a list of the current X extensions, their versions and status.
+.IP \fB\-\-trace\fR=\fIconf\fR,\fIfont\fR,\fIicon\fR,\fIprog\fR,\fIsystray\fR 4
+.IX Item "--trace=conf,font,icon,prog,systray"
+Enable tracing of the paths that are used to load configuration,
+fonts, icons, executed programs, and/or system tray applets.
+.SS USAGE
+.IX Subsection "USAGE"
+.SS TASKBAR
+.IX Subsection "TASKBAR"
+On startup \fBicewm\fR launches the task bar at the bottom of the screen.
+The task bar consists from left to right  of the following components:
+.PP
+The \fIMenu\fR button in the lower left corner gives access to the \fBicewm\fR
+root menu. This menu has sub-menus to start applications, to control
+\&\fBicewm\fR settings, and the \fBicewm\fR \fILogout\fR menu.
+.PP
+The \fIShow Desktop\fR button unmaps all application windows to fully
+uncover the desktop.
+.PP
+The \fIWindow List Menu\fR button gives access to a menu with a list of
+active windows for the current workspace and a list of workspaces
+with sub-menus for their active application windows.
+.PP
+The \fIToolbar\fR is a list of icons for applications that are defined in
+the toolbar configuration file.
+.PP
+The \fIWorkspace Pane\fR shows one button for each workspace.  The current
+workspace is indicated by a pressed button.  Clicking another workspace
+switches to that workspace.  Press left mouse, then the Shift key, then
+release the left mouse, takes the current window to that workspace.
+Press left, then Alt, then release left, moves only the focused window
+to other workspace, without changing the current workspace.
+.PP
+The workspaces are defined in the \fIpreferences\fR file.  To change a name
+for only this session, double click, edit the name and hit Enter.
+When \f(CW\*(C`PagerShowPreview\*(C'\fR is turned on, a small graphical window summary
+for each workspace is shown. They support drag-and-drop: dragging a
+Firefox tab to a workspace button changes the current workspace.
+Then releasing it moves that tab to a new window in that workspace.
+.PP
+The \fITask Pane\fR consists of a list of wide buttons for each application
+that is running on the current workspace, or all workspaces if
+\&\f(CW\*(C`TaskBarShowAllWindows=1\*(C'\fR.  Each task button shows the
+application icon and the application title.  The active application is
+indicated by a pressed button.  This is the application that has input
+focus.  Pressing another button activates that application: it is
+brought to the foreground and receives input focus.  Other mouse
+controlled activities on the window buttons are: dragging window buttons
+with the left mouse button to rearrange the order, closing the application
+window with \f(CW\*(C`Alt\*(C'\fR + middle button, lowering the application window with
+\&\f(CW\*(C`Ctrl\*(C'\fR + middle button, or bringing the application window to the current
+workspace with \f(CW\*(C`Shift\*(C'\fR + middle button if \f(CW\*(C`TaskBarShowAllWindows=1\*(C'\fR.
+.PP
+If there are not many application buttons then a stretch of plain task
+bar is visible.  Clicking on it with the right mouse button gives the
+task bar menu.  Even with a full task pane, this menu can be usually
+accessed by right-clicking the bottom right corner of the taskbar.
+.PP
+The \fITray Applet\fR shows system tray objects.
+.PP
+The \fIAPM Applet\fR shows battery power status.
+.PP
+The \fINet Applet\fR shows network activity.  Network devices to monitor
+are given by the \f(CW\*(C`NetworkStatusDevice\*(C'\fR option.
+.PP
+The \fIMemory Applet\fR monitors memory usage.
+.PP
+The \fICPU Applet\fR monitors processor utilization.
+.PP
+The \fIMailbox Applet\fR monitors mailbox status changes.
+See the section MAILBOX MONITORING below.
+.PP
+The \fIClock Applet\fR shows the current time and date.  It is configured
+by the \f(CW\*(C`TimeFormat\*(C'\fR option.
+.PP
+The \fITask Bar Collapse\fR button collapses the task bar and hides it.
+.PP
+Not all \fBicewm\fR applets may show up on the task bar.  They must have
+been enabled during configuration of the \fBicewm\fR software.  Their
+appearance is also controlled by options in the \fIpreferences\fR file.
+.SS "INPUT FOCUS"
+.IX Subsection "INPUT FOCUS"
+Of all visible windows only one can be the active window.  This is the
+window that has input focus.  It is the primary receiver of keyboard
+and mouse events and hence one can interact with the application that
+created that window.  A primary task of a window manager is to allow the
+user to switch input focus between different windows.  The primary means
+to do this is the mouse pointer.  By moving the mouse pointer over the
+screen to another window, and perhaps also by clicking on a window,
+input focus can be directed.
+.PP
+The \f(CW\*(C`FocusMode\*(C'\fR option controls the way \fBicewm\fR gives input focus to
+applications.  It is initialized by the \fIfocus_mode\fR configuration
+file.  The focus mode is set via the \fIFocus\fR menu.  \fBicewm\fR supports
+six focus models:
+.IP "\fB1. Click-to-focus\fR" 4
+.IX Item "1. Click-to-focus"
+The default focus mode.  In this mode changing input focus requires to
+click a window with the left mouse button. The window is raised if
+needed.  When an application requests focus its task pane button
+flashes.  This gives the option to honor this request or to ignore it.
+When a new application window appears it automatically receives focus.
+Also when a hidden application raises to the front it receives focus.
+.IP "\fB2. Sloppy-mouse-focus\fR" 4
+.IX Item "2. Sloppy-mouse-focus"
+Sets input focus merely by moving the mouse pointer over a window.  It
+is called sloppy, because if the mouse then leaves the window and moves
+to the desktop background the input focus remains with the last active
+window.  When a window receives focus it is raised.  When an application
+requests focus its task pane button flashes.  A new application or an
+application that raises to the front automatically receives focus.
+.IP "\fB3. Explicit-focus\fR" 4
+.IX Item "3. Explicit-focus"
+Focus is even more user-controlled than \fBClick-to-focus\fR.  When a
+window receives focus it is not raised by default, unless the frame
+border is clicked.  No flashing occurs when an application requests
+focus.  When a new application window appears it does not receive focus.
+Only by explicit clicking on a window is focus directed.
+.IP "\fB4. Strict-mouse-focus\fR" 4
+.IX Item "4. Strict-mouse-focus"
+Like \fBSloppy\fR but focus remains with the last window. New applications
+don't receive focus and are mapped behind other windows.  When an
+application raises to the front it still does not get focus.
+.IP "\fB5. Quiet-sloppy-focus\fR" 4
+.IX Item "5. Quiet-sloppy-focus"
+Like \fBSloppy\fR but no disturbing flashing occurs on the task bar when an
+application requests focus.
+.IP "\fB6. Custom-mode\fR" 4
+.IX Item "6. Custom-mode"
+A focus mode that is defined by the following ten options:
+\&\f(CW\*(C`ClickToFocus\*(C'\fR,
+\&\f(CW\*(C`FocusOnAppRaise\*(C'\fR,
+\&\f(CW\*(C`RequestFocusOnAppRaise\*(C'\fR,
+\&\f(CW\*(C`RaiseOnFocus\*(C'\fR,
+\&\f(CW\*(C`RaiseOnClickClient\*(C'\fR,
+\&\f(CW\*(C`FocusChangesWorkspace\*(C'\fR,
+\&\f(CW\*(C`FocusOnMap\*(C'\fR,
+\&\f(CW\*(C`FocusOnMapTransient\*(C'\fR,
+\&\f(CW\*(C`FocusOnMapTransientActive\*(C'\fR,
+\&\f(CW\*(C`MapInactiveOnTop\*(C'\fR.
+.Sp
+All non-Custom focus modes override these ten options.
+.PP
+Apart from the mouse, \fBicewm\fR supports changing input focus in two
+ways by keyboard.  By pressing \f(CW\*(C`Alt+Esc\*(C'\fR or \f(CW\*(C`Alt+Shift+Esc\*(C'\fR,
+input focus is immediately changed to the next or previous window,
+which will be raised to make it fully visible. The other method
+involves the quick switch.
+.SS "QUICK SWITCH"
+.IX Subsection "QUICK SWITCH"
+The \fBQuickSwitch\fR is a means to quickly and interactively change
+the input focus to another window.  It is activated by pressing the
+\&\f(CW\*(C`Alt+Tab\*(C'\fR or \f(CW\*(C`Alt+Shift+Tab\*(C'\fR key combination.  A window pops up
+in the centre of the screen with a list of windows to choose from.
+A narrow band indicates a selection: the candidate window that will
+be activated to receive input focus when the Alt key is released.
+.PP
+The selection can be changed by repeatedly pressing the Tab key, while
+keeping the Alt key down. If a Shift key is also down, the direction of
+traversal is reversed. Or use the scroll wheel of the mouse.  Or use
+one of the digit keys to select the corresponding window from the list.
+Arrow keys are also supported, as well as the Home and End key.
+.PP
+To make a selected window the active window, just release the Alt key,
+or hit the Return key, or click on it.  To cancel the QuickSwitch,
+press Escape or click outside of the QuickSwitch window.
+.PP
+A selected window can be closed by Delete, \f(CW\*(C`Alt+F4\*(C'\fR, or the middle
+mouse button.  While the QuickSwitch window is up, one can still change
+workspace with the usual workspace hotkeys.
+.PP
+The QuickSwitch has two distinct modes: vertical and horizontal.
+The window list can include all windows or be limited to the current
+workspace. There is an option to raise the selected candidate.
+See the many preferences available for the QuickSwitch.
+.SS "WINDOW PLACEMENT"
+.IX Subsection "WINDOW PLACEMENT"
+A second important task of a window manager is to place new windows on
+the screen.  By default \fBicewm\fR chooses a placement with minimal
+overlap, but this is determined by the \f(CW\*(C`SmartPlacement\*(C'\fR option in the
+\&\fIpreferences\fR file.  If \f(CW\*(C`SmartPlacement\*(C'\fR is turned off then windows
+are placed in sequence from left to right and top to bottom.  One can
+also turn on \f(CW\*(C`ManualPlacement\*(C'\fR.  Then new windows appear initially in
+the top left corner and the mouse cursor changes into a fist.  By moving
+the fist cursor to a suitable location and clicking the new window will
+appear at the mouse click location.
+.SS "WINDOW LAYERS"
+.IX Subsection "WINDOW LAYERS"
+Windows can overlap.  Which window appears on top is determined by three
+features.  Newer windows appear over older windows.  By clicking on a
+window it is raised to the top.  But both are overruled by the window
+layer.  Windows can be placed in different layers via the \fILayers\fR
+menu.  Click with the right mouse button on the window frame and select
+\&\fILayer\fR.  From there choose one of seven window layers.  These are
+ordered from higher to lower.  Windows in higher layers appear over
+windows in lower layers.
+.SS "TABBED WINDOWS"
+.IX Subsection "TABBED WINDOWS"
+A window frame may contain multiple client windows. Only one client can
+be visible, while the others are hidden. This is called tabbing.  This
+can be helpful to reduce the number of visible windows. To create a tab,
+drag the title bar with the middle mouse button, while holding down a
+shift key, onto the title bar of another frame. The two title bars will
+start to flash to indicate that they can merge. Release the mouse button
+to merge the client of the upper window to the lower frame.  Now the
+lower frame will have multiple clients, called tabs. The title bar will
+show a vertical bar with triple dots to indicate this.
+To change the current tab either:
+.IP \(bu 4
+Click on the triple dots next to the vertical bar.
+.IP \(bu 4
+Use \f(CW\*(C`KeyWinNext=Alt+F6\*(C'\fR to select the next tab.
+.IP \(bu 4
+Use \f(CW\*(C`KeyWinPrev=Alt+Shift+F6\*(C'\fR for the previous tab.
+.IP \(bu 4
+Use the QuickSwitch.
+.IP \(bu 4
+Use the window list window.
+.IP \(bu 4
+Use a submenu in the window menu.
+.PP
+To change the mouse binding for creating tabs, modify
+\&\fBMouseWinTabbing\fR=\f(CW\*(C`Shift+Pointer_Button2\*(C'\fR.  Another
+useful setting is \fBMouseWinTabbing\fR=\f(CW\*(C`Pointer_Button1\*(C'\fR.
+.PP
+\&\f(CW\*(C`Alt+F4\*(C'\fR closes all tabs. To close just the active tab add to \f(CW\*(C`keys\*(C'\fR:
+.PP
+.Vb 1
+\&    key "Ctrl+Shift+F4"     icesh \-f close
+.Ve
+.PP
+To move the active tab to its own window frame by key, add to \f(CW\*(C`keys\*(C'\fR:
+.PP
+.Vb 1
+\&    key "Alt+u"             icesh \-f untab
+.Ve
+.PP
+To open all chrome windows in the same frame add this to \f(CW\*(C`winoptions\*(C'\fR:
+.PP
+.Vb 1
+\&    google\-chrome.frame:    chrome
+.Ve
+.SS WORKSPACES
+.IX Subsection "WORKSPACES"
+\&\fBicewm\fR supports multiple virtual desktops called workspaces.  A
+workspace is like a screen where a subset of all application windows are
+mapped.  Thanks to multiple workspaces we can more easily manage a
+large number of applications.  The number of workspaces and their names
+are configurable in the \fIpreferences\fR file through the
+\&\f(CW\*(C`WorkspaceNames\*(C'\fR option.  By default four workspaces are created
+with the names 1, 2, 3 and 4 thus:
+.PP
+.Vb 1
+\& WorkspaceNames=" 1 ", " 2 ", " 3 ", " 4 "
+.Ve
+.PP
+This syntax is typical for \fBicewm\fR options that receive multiple
+values.  It is a list of comma-separated values each of which can be
+quoted.
+.PP
+The workspaces are visible on the toolbar.  One can switch to a
+different workspace by pressing the workspace button in the toolbar,
+but after becoming familiar with the 'keyboard shortcuts' below one will
+want to use a hotkey to choose a workspace.  If the \f(CW\*(C`EdgeSwitch\*(C'\fR
+options is enabled in the \fIpreferences\fR file (with sub-options
+\&\f(CW\*(C`HorizontalEdgeSwitch\*(C'\fR and \f(CW\*(C`VerticalEdgeSwitch\*(C'\fR) then one can move to
+the next or previous workspace by moving the mouse to the edge of the
+screen.  The \f(CW\*(C`ContinuousEdgeSwitch\*(C'\fR option enables continuous movement
+to subsequent workspaces.  The \f(CW\*(C`EdgeSwitchDelay\*(C'\fR option says how long
+to wait before a change of workspace occurs.
+.PP
+To move an application window to a different workspace one can use a
+keyboard shortcut.  Another option is to select the \fIMove To\fR submenu
+in the window menu of the window frame.
+.SS "DRAG AND DROP"
+.IX Subsection "DRAG AND DROP"
+The task bar supports drag and drop operations. When a drag
+is in progress, the destination window can be activated by
+hovering the drag icon over the task button for that window.
+Alternatively, the current workspace can be changed by
+hovering the drag icon over the desired workspace button.
+When edge switching is enabled, the current workspace can
+also be changed by bringing the drag icon to the screen edge.
+.SS "ADDRESS BAR"
+.IX Subsection "ADDRESS BAR"
+If \fBEnableAddressBar\fR=1 then \fBKeySysAddressBar\fR=\f(CW\*(C`Alt+Ctrl+Space\*(C'\fR
+activates the address bar in the task bar.
+If \fBShowAddressBar\fR=1 it is always shown. This is a command-line in
+the task bar where a shell command can be typed.
+Pressing \f(CW\*(C`Enter\*(C'\fR will execute the command.
+\&\fBAddressBarCommand\fR=\f(CW\*(C`/bin/sh\*(C'\fR will be used to execute the command.
+On \f(CW\*(C`Control+Enter\*(C'\fR the command is executed in a terminal
+as given by \fBTerminalCommand\fR.
+The address bar maintains a history that is navigable by the \fIUp\fR
+and \fIDown\fR keys.
+It supports command completion using \f(CW\*(C`Tab\*(C'\fR or \f(CW\*(C`Ctrl+I\*(C'\fR.
+A rich set of editing operations is supported,
+including cut\-/copy\-/paste\-operations.
+.SS "WINDOW LIST"
+.IX Subsection "WINDOW LIST"
+The window list window shows a list of all workspaces. For each
+workspace it shows the window titles of the windows that are mapped
+on it. The bottom entry reads \f(CW\*(C`All Workspaces\*(C'\fR. It holds the sticky
+windows. These windows are mapped in all workspaces.
+.PP
+The window list window is normally hidden. Choose one of the following
+four methods to make it visible:
+.IP \(bu 4
+Select the bottom window list menu entry.
+.IP \(bu 4
+Press the \f(CW\*(C`KeySysWindowList=Ctrl+Alt+Esc\*(C'\fR key.
+.IP \(bu 4
+Press the right Windows key if \f(CW\*(C`Win95Keys=1\*(C'\fR
+.IP \(bu 4
+Press the \f(CW\*(C`DesktopWinListButton=2\*(C'\fR mouse button in the root window.
+.IP \(bu 4
+Press the middle mouse button in a workspace button on the task bar.
+.PP
+A single-click on a window entry selects it. A group of windows can
+be selected by \f(CW\*(C`Shift+Pointer_Button1\*(C'\fR or by dragging with the left
+mouse button. Use \f(CW\*(C`Ctrl+Pointer_Button1\*(C'\fR to individually select
+windows in a multi-selection. A right mouse click over a selection
+will popup the system menu for this selection.  To close the selected
+windows, press \f(CW\*(C`Delete\*(C'\fR. Press \f(CW\*(C`Shift+Delete\*(C'\fR to forcefully kill them.
+Right mouse click below the sticky windows for a menu with window
+arranging actions.
+.PP
+Double-click on a workspace to switch to it.  Double-click on a window
+to activate it.  Or navigate by arrow keys and press Enter.
+The space bar toggles a selection of a window. \f(CW\*(C`Ctrl+a\*(C'\fR and \f(CW\*(C`Ctrl+/\*(C'\fR
+will select the entire list of windows. \f(CW\*(C`Ctrl+\e\e\*(C'\fR deselects everything.
+Press the first letter of a window title to navigate to it and select
+it. If titles of multiple windows start with the same letter then
+repeatedly pressing the first letter cycles over those windows.
+\&\f(CW\*(C`Home\*(C'\fR selects the first entry and \f(CW\*(C`End\*(C'\fR the last. \f(CW\*(C`PageUp\*(C'\fR and
+\&\f(CW\*(C`PageDown\*(C'\fR move up or down by ten entries. Combine this with the
+\&\f(CW\*(C`Shift\*(C'\fR key to extend a selection over the range of motion.
+.SS "SYSTEM DIALOG"
+.IX Subsection "SYSTEM DIALOG"
+The system dialog offers quick access to a set of general controls.
+It can lock the screen, suspend the system, logout or cancel a pending
+logout, reboot the system, shutdown the system, show the window list,
+restart icewm, show the about dialog, reload the winoptions file or
+the keys file. It is activated by \fBKeySysDialog\fR=\f(CW\*(C`Ctrl+Alt+Del\*(C'\fR.
+To cancel it, hit the Escape key.
+.SS "MAILBOX MONITORING"
+.IX Subsection "MAILBOX MONITORING"
+The task bar can show one or more icons to reflect the status of a
+mailbox. The mailbox can be a local file or a remote POP or IMAP
+account. For this a couple of options must be set. First,
+\&\fITaskBarShowMailboxStatus\fR must be enabled, which it is by default.
+Then the location of the mailbox must be set.  Icewm first looks for
+\&\fIMailBoxPath\fR in preferences. If this is unset, it looks at the
+environment variables \f(CW\*(C`MAILPATH\*(C'\fR and \f(CW\*(C`MAIL\*(C'\fR.  \fIMailBoxPath\fR may
+contain a space-separated list of mailboxes, while \f(CW\*(C`MAILPATH\*(C'\fR may
+contain a colon-separated list of mailboxes.  If a mailbox starts
+with a slash \f(CW\*(C`/\*(C'\fR, then it is a local file, otherwise a URL.
+These are six examples of possible mailboxes:
+.PP
+.Vb 6
+\&    file:///var/spool/mail/captnmark
+\&    file:///home/captnmark/Maildir/
+\&    pop3://markus:%2f%40%3a@maol.ch/
+\&    pop3s://markus:password@pop.gmail.com/
+\&    imap://mathias@localhost/INBOX.Maillisten.icewm\-user
+\&    imaps://mathias:password@imap.gmail.com/INBOX
+.Ve
+.PP
+The POP3S and IMAPS schemes use \f(CW\*(C`openssl\*(C'\fR for TLS/SSL encryption.
+Note that for IceWM to access Gmail you must first configure
+your Gmail account to enable POP3 or IMAP access.
+Make sure you have secure file permissions on your IceWM
+preferences file and the directory that contains it.
+.PP
+Reserved characters in the password, like \fIslash\fR, \fIat\fR and \fIcolon\fR
+can be specified using escape sequences with a hexadecimal encoding
+like \f(CW%2f\fR for the slash or \f(CW%40\fR for the at sign.
+For example, to hex-encode \f(CW\*(C`!p@a%s&s~\*(C'\fR use this Perl snippet:
+.PP
+.Vb 2
+\&    perl \-e \*(Aqforeach(split("", $ARGV[0])) { printf "%%%02x", ord($_); };
+\&    print "\en";\*(Aq \*(Aq!p@a%s&s~\*(Aq
+.Ve
+.PP
+Which will print:
+.PP
+.Vb 1
+\&    %21%40%23%24%25%5e%26%2a%7e
+.Ve
+.PP
+This is the hex-encoded password. However, it is unwise to store a
+password in your preferences. Consider a wallet extension for IceWM.
+.PP
+IceWM will check a mailbox periodically. The period in seconds can
+be set by the \fIMailCheckDelay\fR option, which is 30 seconds by default.
+.PP
+Whenever new mail arrives, the mailbox icon will be highlighted.
+The color will indicate if the mail has been read or not. Hovering
+the mouse over the mailbox icon will show a tooltip with more details.
+A command can be also be run on new mail. Set the \fINewMailCommand\fR
+option. Its environment will have these variables set by IceWM:
+.IP ICEWM_MAILBOX 4
+.IX Item "ICEWM_MAILBOX"
+The mailbox index number of \fIMailBoxPath\fR starting from 1.
+.IP ICEWM_COUNT 4
+.IX Item "ICEWM_COUNT"
+The total number of messages in this mailbox.
+.IP ICEWM_UNREAD 4
+.IX Item "ICEWM_UNREAD"
+The number of unread messages in this mailbox.
+.SS "KEYBOARD LAYOUT SWITCHING"
+.IX Subsection "KEYBOARD LAYOUT SWITCHING"
+To control keyboard layouts on the task bar, define in \fIpreferences\fR
+the option \fBKeyboardLayouts\fR to a comma-separated list of your
+preferred keyboard layouts. For example:
+.PP
+.Vb 1
+\& KeyboardLayouts="de","fr","jp"
+.Ve
+.PP
+A keyboard layout can simply be a name. Usually this is a two-letter
+country code. See the directory \fI/usr/share/X11/xkb/symbols\fR for
+a list of available keyboard layouts for your system.  If it is
+enclosed in double quotes, it can also be a space-separated list of
+command-line arguments to an invocation of the \f(CW\*(C`setxkbmap\*(C'\fR program.
+.PP
+The first layout is the default. It will be installed when icewm starts.
+The task bar will show the current keyboard layout. If an icon can
+be found for the first two letters of the layout, then that icon
+will be shown. Otherwise the first two letters of the name of the
+layout will be shown.
+.PP
+Click on the current keyboard layout to cycle through all the
+available keyboard layouts, or use the \fBKeySysKeyboardNext\fR key.
+Click with the right mouse button to open a menu of all available
+keyboard layouts.
+.PP
+It is also possible to configure a default keyboard layout for
+each program individually in the \fBicewm\-winoptions\fR\|(5) file.
+Whenever such a program receives input focus, icewm will install
+this configured keyboard layout automatically. The keyboard status
+on the task bar will be updated to reflect this.
+.PP
+Please note that for keyboard layout switching to work, the
+\&\f(CW\*(C`setxkbmap\*(C'\fR program must be installed. To see your current
+keyboard layout settings, do \f(CW\*(C`setxkbmap \-query\*(C'\fR.
+.SS "KEYBOARD SHORTCUTS"
+.IX Subsection "KEYBOARD SHORTCUTS"
+\&\fBicewm\fR supports a large number of hotkeys to activate some behaviour
+with a single key combination.  These are all configurable in the
+\&\fIpreferences\fR file.  Here we give their preferences name, followed by
+their default value in double quotes, and a short descriptions of their
+effect.
+.PP
+Note that all use one or more key modifiers. Icewm supports the
+following modifiers: Alt, AltGr, Ctrl, Hyper, Meta, Shift, Super.
+Setting \fBModSuperIsCtrlAlt=1\fR makes the Super modifier an alias
+for Ctrl+Alt.
+.ie n .IP "\fBKeyWinRaise\fR=""Alt+F1""" 4
+.el .IP \fBKeyWinRaise\fR=\f(CWAlt+F1\fR 4
+.IX Item "KeyWinRaise=Alt+F1"
+Raises the window that currently has input focus.
+.ie n .IP "\fBKeyWinOccupyAll\fR=""Alt+F2""" 4
+.el .IP \fBKeyWinOccupyAll\fR=\f(CWAlt+F2\fR 4
+.IX Item "KeyWinOccupyAll=Alt+F2"
+Makes the active window occupy all workspaces.
+.ie n .IP "\fBKeyWinLower\fR=""Alt+F3""" 4
+.el .IP \fBKeyWinLower\fR=\f(CWAlt+F3\fR 4
+.IX Item "KeyWinLower=Alt+F3"
+Lowers the window that currently has input focus.
+.ie n .IP "\fBKeyWinClose\fR=""Alt+F4""" 4
+.el .IP \fBKeyWinClose\fR=\f(CWAlt+F4\fR 4
+.IX Item "KeyWinClose=Alt+F4"
+Closes the active window.
+.ie n .IP "\fBKeyWinRestore\fR=""Alt+F5""" 4
+.el .IP \fBKeyWinRestore\fR=\f(CWAlt+F5\fR 4
+.IX Item "KeyWinRestore=Alt+F5"
+Restores the active window to its visible state.
+.ie n .IP "\fBKeyWinNext\fR=""Alt+F6""" 4
+.el .IP \fBKeyWinNext\fR=\f(CWAlt+F6\fR 4
+.IX Item "KeyWinNext=Alt+F6"
+Switches focus to the next window.
+.ie n .IP "\fBKeyWinPrev\fR=""Alt+Shift+F6""" 4
+.el .IP \fBKeyWinPrev\fR=\f(CWAlt+Shift+F6\fR 4
+.IX Item "KeyWinPrev=Alt+Shift+F6"
+Switches focus to the previous window.
+.ie n .IP "\fBKeyWinMove\fR=""Alt+F7""" 4
+.el .IP \fBKeyWinMove\fR=\f(CWAlt+F7\fR 4
+.IX Item "KeyWinMove=Alt+F7"
+Starts movement of the active window.
+.ie n .IP "\fBKeyWinSize\fR=""Alt+F8""" 4
+.el .IP \fBKeyWinSize\fR=\f(CWAlt+F8\fR 4
+.IX Item "KeyWinSize=Alt+F8"
+Starts resizing of the active window.
+.ie n .IP "\fBKeyWinMinimize\fR=""Alt+F9""" 4
+.el .IP \fBKeyWinMinimize\fR=\f(CWAlt+F9\fR 4
+.IX Item "KeyWinMinimize=Alt+F9"
+Iconifies the active window.
+.ie n .IP "\fBKeyWinMaximize\fR=""Alt+F10""" 4
+.el .IP \fBKeyWinMaximize\fR=\f(CWAlt+F10\fR 4
+.IX Item "KeyWinMaximize=Alt+F10"
+Maximizes the active window with borders.
+.ie n .IP "\fBKeyWinMaximizeVert\fR=""Alt+Shift+F10""" 4
+.el .IP \fBKeyWinMaximizeVert\fR=\f(CWAlt+Shift+F10\fR 4
+.IX Item "KeyWinMaximizeVert=Alt+Shift+F10"
+Maximizes the active window vertically.
+.ie n .IP "\fBKeyWinMaximizeHoriz\fR=""undefined""" 4
+.el .IP \fBKeyWinMaximizeHoriz\fR=\f(CWundefined\fR 4
+.IX Item "KeyWinMaximizeHoriz=undefined"
+Maximizes the active window horizontally.
+.ie n .IP "\fBKeyWinFullscreen\fR=""Alt+F11""" 4
+.el .IP \fBKeyWinFullscreen\fR=\f(CWAlt+F11\fR 4
+.IX Item "KeyWinFullscreen=Alt+F11"
+Maximizes the active window without borders.
+.ie n .IP "\fBKeyWinRollup\fR=""Alt+F12""" 4
+.el .IP \fBKeyWinRollup\fR=\f(CWAlt+F12\fR 4
+.IX Item "KeyWinRollup=Alt+F12"
+Rolls up the active window.
+.ie n .IP "\fBKeyWinHide\fR=""Alt+Shift+F12""" 4
+.el .IP \fBKeyWinHide\fR=\f(CWAlt+Shift+F12\fR 4
+.IX Item "KeyWinHide=Alt+Shift+F12"
+Hides the active window.
+.ie n .IP "\fBKeyWinMenu\fR=""Alt+Space""" 4
+.el .IP \fBKeyWinMenu\fR=\f(CWAlt+Space\fR 4
+.IX Item "KeyWinMenu=Alt+Space"
+Posts the window menu.
+.ie n .IP "\fBKeyWinArrangeNW\fR=""Ctrl+Alt+KP_7""" 4
+.el .IP \fBKeyWinArrangeNW\fR=\f(CWCtrl+Alt+KP_7\fR 4
+.IX Item "KeyWinArrangeNW=Ctrl+Alt+KP_7"
+Moves the active window to the top left corner of the screen.
+.ie n .IP "\fBKeyWinArrangeN\fR=""Ctrl+Alt+KP_8""" 4
+.el .IP \fBKeyWinArrangeN\fR=\f(CWCtrl+Alt+KP_8\fR 4
+.IX Item "KeyWinArrangeN=Ctrl+Alt+KP_8"
+Moves the active window to the top middle of the screen.
+.ie n .IP "\fBKeyWinArrangeNE\fR=""Ctrl+Alt+KP_9""" 4
+.el .IP \fBKeyWinArrangeNE\fR=\f(CWCtrl+Alt+KP_9\fR 4
+.IX Item "KeyWinArrangeNE=Ctrl+Alt+KP_9"
+Moves the active window to the top right of the screen.
+.ie n .IP "\fBKeyWinArrangeE\fR=""Ctrl+Alt+KP_6""" 4
+.el .IP \fBKeyWinArrangeE\fR=\f(CWCtrl+Alt+KP_6\fR 4
+.IX Item "KeyWinArrangeE=Ctrl+Alt+KP_6"
+Moves the active window to the middle right of the screen.
+.ie n .IP "\fBKeyWinArrangeSE\fR=""Ctrl+Alt+KP_3""" 4
+.el .IP \fBKeyWinArrangeSE\fR=\f(CWCtrl+Alt+KP_3\fR 4
+.IX Item "KeyWinArrangeSE=Ctrl+Alt+KP_3"
+Moves the active window to the bottom right of the screen.
+.ie n .IP "\fBKeyWinArrangeS\fR=""Ctrl+Alt+KP_2""" 4
+.el .IP \fBKeyWinArrangeS\fR=\f(CWCtrl+Alt+KP_2\fR 4
+.IX Item "KeyWinArrangeS=Ctrl+Alt+KP_2"
+Moves the active window to the bottom middle of the screen.
+.ie n .IP "\fBKeyWinArrangeSW\fR=""Ctrl+Alt+KP_1""" 4
+.el .IP \fBKeyWinArrangeSW\fR=\f(CWCtrl+Alt+KP_1\fR 4
+.IX Item "KeyWinArrangeSW=Ctrl+Alt+KP_1"
+Moves the active window to the bottom left of the screen.
+.ie n .IP "\fBKeyWinArrangeW\fR=""Ctrl+Alt+KP_4""" 4
+.el .IP \fBKeyWinArrangeW\fR=\f(CWCtrl+Alt+KP_4\fR 4
+.IX Item "KeyWinArrangeW=Ctrl+Alt+KP_4"
+Moves the active window to the middle left of the screen.
+.ie n .IP "\fBKeyWinArrangeC\fR=""Ctrl+Alt+KP_5""" 4
+.el .IP \fBKeyWinArrangeC\fR=\f(CWCtrl+Alt+KP_5\fR 4
+.IX Item "KeyWinArrangeC=Ctrl+Alt+KP_5"
+Moves the active window to the center of the screen.
+.IP "\fBKeyWinTileLeft\fR=""""" 4
+.IX Item "KeyWinTileLeft="""""
+Let the active window occupy the left half of the screen.
+.IP "\fBKeyWinTileRight\fR=""""" 4
+.IX Item "KeyWinTileRight="""""
+Let the active window occupy the right half of the screen.
+.IP "\fBKeyWinTileTop\fR=""""" 4
+.IX Item "KeyWinTileTop="""""
+Let the active window occupy the top half of the screen.
+.IP "\fBKeyWinTileBottom\fR=""""" 4
+.IX Item "KeyWinTileBottom="""""
+Let the active window occupy the bottom half of the screen.
+.IP "\fBKeyWinTileTopLeft\fR=""""" 4
+.IX Item "KeyWinTileTopLeft="""""
+Let the active window occupy the top left quarter of the screen.
+.IP "\fBKeyWinTileTopRight\fR=""""" 4
+.IX Item "KeyWinTileTopRight="""""
+Let the active window occupy the top right quarter of the screen.
+.IP "\fBKeyWinTileBottomLeft\fR=""""" 4
+.IX Item "KeyWinTileBottomLeft="""""
+Let the active window occupy the bottom left quarter of the screen.
+.IP "\fBKeyWinTileBottomRight\fR=""""" 4
+.IX Item "KeyWinTileBottomRight="""""
+Let the active window occupy the bottom right quarter of the screen.
+.IP "\fBKeyWinTileCenter\fR=""""" 4
+.IX Item "KeyWinTileCenter="""""
+Let the active window occupy the center quarter of the screen.
+.ie n .IP "\fBKeyWinSmartPlace\fR=""Ctrl+Alt+Shift+KP_5""" 4
+.el .IP \fBKeyWinSmartPlace\fR=\f(CWCtrl+Alt+Shift+KP_5\fR 4
+.IX Item "KeyWinSmartPlace=Ctrl+Alt+Shift+KP_5"
+Smart place the active window.
+.ie n .IP "\fBKeySysWinMenu\fR=""Shift+Esc""" 4
+.el .IP \fBKeySysWinMenu\fR=\f(CWShift+Esc\fR 4
+.IX Item "KeySysWinMenu=Shift+Esc"
+Posts the system window menu.
+.ie n .IP "\fBKeySysWinNext\fR=""Alt+Esc""" 4
+.el .IP \fBKeySysWinNext\fR=\f(CWAlt+Esc\fR 4
+.IX Item "KeySysWinNext=Alt+Esc"
+Give focus to the next window and raise it.
+.ie n .IP "\fBKeySysWinPrev\fR=""Alt+Shift+Esc""" 4
+.el .IP \fBKeySysWinPrev\fR=\f(CWAlt+Shift+Esc\fR 4
+.IX Item "KeySysWinPrev=Alt+Shift+Esc"
+Give focus to the previous window and raise it.
+.ie n .IP "\fBKeySysDialog\fR=""Ctrl+Alt+Del""" 4
+.el .IP \fBKeySysDialog\fR=\f(CWCtrl+Alt+Del\fR 4
+.IX Item "KeySysDialog=Ctrl+Alt+Del"
+Opens the IceWM system dialog in the center of the screen.
+.ie n .IP "\fBKeySysMenu\fR=""Ctrl+Esc""" 4
+.el .IP \fBKeySysMenu\fR=\f(CWCtrl+Esc\fR 4
+.IX Item "KeySysMenu=Ctrl+Esc"
+Activates the IceWM root menu in the lower left corner.
+.ie n .IP "\fBKeySysWindowList\fR=""Alt+Ctrl+Esc""" 4
+.el .IP \fBKeySysWindowList\fR=\f(CWAlt+Ctrl+Esc\fR 4
+.IX Item "KeySysWindowList=Alt+Ctrl+Esc"
+Opens the IceWM system window list in the center of the screen.
+.ie n .IP "\fBKeySysAddressBar\fR=""Alt+Ctrl+Space""" 4
+.el .IP \fBKeySysAddressBar\fR=\f(CWAlt+Ctrl+Space\fR 4
+.IX Item "KeySysAddressBar=Alt+Ctrl+Space"
+Opens the address bar in the task bar where a command can be typed.
+.ie n .IP "\fBKeySysWorkspacePrev\fR=""Alt+Ctrl+Left""" 4
+.el .IP \fBKeySysWorkspacePrev\fR=\f(CWAlt+Ctrl+Left\fR 4
+.IX Item "KeySysWorkspacePrev=Alt+Ctrl+Left"
+Goes one workspace to the left.
+.ie n .IP "\fBKeySysWorkspaceNext\fR=""Alt+Ctrl+Right""" 4
+.el .IP \fBKeySysWorkspaceNext\fR=\f(CWAlt+Ctrl+Right\fR 4
+.IX Item "KeySysWorkspaceNext=Alt+Ctrl+Right"
+Goes one workspace to the right.
+.ie n .IP "\fBKeySysWorkspaceLast\fR=""Alt+Ctrl+Down""" 4
+.el .IP \fBKeySysWorkspaceLast\fR=\f(CWAlt+Ctrl+Down\fR 4
+.IX Item "KeySysWorkspaceLast=Alt+Ctrl+Down"
+Goes to the previous workspace.
+.ie n .IP "\fBKeySysWorkspacePrevTakeWin\fR=""Alt+Ctrl+Shift+Left""" 4
+.el .IP \fBKeySysWorkspacePrevTakeWin\fR=\f(CWAlt+Ctrl+Shift+Left\fR 4
+.IX Item "KeySysWorkspacePrevTakeWin=Alt+Ctrl+Shift+Left"
+Takes the active window one workspace to the left.
+.ie n .IP "\fBKeySysWorkspaceNextTakeWin\fR=""Alt+Ctrl+Shift+Right""" 4
+.el .IP \fBKeySysWorkspaceNextTakeWin\fR=\f(CWAlt+Ctrl+Shift+Right\fR 4
+.IX Item "KeySysWorkspaceNextTakeWin=Alt+Ctrl+Shift+Right"
+Takes the active window one workspace to the right.
+.ie n .IP "\fBKeySysWorkspaceLastTakeWin\fR=""Alt+Ctrl+Shift+Down""" 4
+.el .IP \fBKeySysWorkspaceLastTakeWin\fR=\f(CWAlt+Ctrl+Shift+Down\fR 4
+.IX Item "KeySysWorkspaceLastTakeWin=Alt+Ctrl+Shift+Down"
+Takes the active window to the previous workspace.
+.ie n .IP "\fBKeySysWorkspace1\fR=""Alt+Ctrl+1""" 4
+.el .IP \fBKeySysWorkspace1\fR=\f(CWAlt+Ctrl+1\fR 4
+.IX Item "KeySysWorkspace1=Alt+Ctrl+1"
+Goes to workspace 1.
+.ie n .IP "\fBKeySysWorkspace2\fR=""Alt+Ctrl+2""" 4
+.el .IP \fBKeySysWorkspace2\fR=\f(CWAlt+Ctrl+2\fR 4
+.IX Item "KeySysWorkspace2=Alt+Ctrl+2"
+Goes to workspace 2.
+.ie n .IP "\fBKeySysWorkspace3\fR=""Alt+Ctrl+3""" 4
+.el .IP \fBKeySysWorkspace3\fR=\f(CWAlt+Ctrl+3\fR 4
+.IX Item "KeySysWorkspace3=Alt+Ctrl+3"
+Goes to workspace 3.
+.ie n .IP "\fBKeySysWorkspace4\fR=""Alt+Ctrl+4""" 4
+.el .IP \fBKeySysWorkspace4\fR=\f(CWAlt+Ctrl+4\fR 4
+.IX Item "KeySysWorkspace4=Alt+Ctrl+4"
+Goes to workspace 4.
+.ie n .IP "\fBKeySysWorkspace5\fR=""Alt+Ctrl+5""" 4
+.el .IP \fBKeySysWorkspace5\fR=\f(CWAlt+Ctrl+5\fR 4
+.IX Item "KeySysWorkspace5=Alt+Ctrl+5"
+Goes to workspace 5.
+.ie n .IP "\fBKeySysWorkspace6\fR=""Alt+Ctrl+6""" 4
+.el .IP \fBKeySysWorkspace6\fR=\f(CWAlt+Ctrl+6\fR 4
+.IX Item "KeySysWorkspace6=Alt+Ctrl+6"
+Goes to workspace 6.
+.ie n .IP "\fBKeySysWorkspace7\fR=""Alt+Ctrl+7""" 4
+.el .IP \fBKeySysWorkspace7\fR=\f(CWAlt+Ctrl+7\fR 4
+.IX Item "KeySysWorkspace7=Alt+Ctrl+7"
+Goes to workspace 7.
+.ie n .IP "\fBKeySysWorkspace8\fR=""Alt+Ctrl+8""" 4
+.el .IP \fBKeySysWorkspace8\fR=\f(CWAlt+Ctrl+8\fR 4
+.IX Item "KeySysWorkspace8=Alt+Ctrl+8"
+Goes to workspace 8.
+.ie n .IP "\fBKeySysWorkspace9\fR=""Alt+Ctrl+9""" 4
+.el .IP \fBKeySysWorkspace9\fR=\f(CWAlt+Ctrl+9\fR 4
+.IX Item "KeySysWorkspace9=Alt+Ctrl+9"
+Goes to workspace 9.
+.ie n .IP "\fBKeySysWorkspace10\fR=""Alt+Ctrl+0""" 4
+.el .IP \fBKeySysWorkspace10\fR=\f(CWAlt+Ctrl+0\fR 4
+.IX Item "KeySysWorkspace10=Alt+Ctrl+0"
+Goes to workspace 10.
+.ie n .IP "\fBKeySysWorkspace11\fR=""Alt+Ctrl+minus""" 4
+.el .IP \fBKeySysWorkspace11\fR=\f(CWAlt+Ctrl+minus\fR 4
+.IX Item "KeySysWorkspace11=Alt+Ctrl+minus"
+Goes to workspace 11.
+.ie n .IP "\fBKeySysWorkspace12\fR=""Alt+Ctrl+equal""" 4
+.el .IP \fBKeySysWorkspace12\fR=\f(CWAlt+Ctrl+equal\fR 4
+.IX Item "KeySysWorkspace12=Alt+Ctrl+equal"
+Goes to workspace 12.
+.ie n .IP "\fBKeySysWorkspace1TakeWin\fR=""Alt+Ctrl+Shift+1""" 4
+.el .IP \fBKeySysWorkspace1TakeWin\fR=\f(CWAlt+Ctrl+Shift+1\fR 4
+.IX Item "KeySysWorkspace1TakeWin=Alt+Ctrl+Shift+1"
+Takes the active window to workspace 1.
+.ie n .IP "\fBKeySysWorkspace2TakeWin\fR=""Alt+Ctrl+Shift+2""" 4
+.el .IP \fBKeySysWorkspace2TakeWin\fR=\f(CWAlt+Ctrl+Shift+2\fR 4
+.IX Item "KeySysWorkspace2TakeWin=Alt+Ctrl+Shift+2"
+Takes the active window to workspace 2.
+.ie n .IP "\fBKeySysWorkspace3TakeWin\fR=""Alt+Ctrl+Shift+3""" 4
+.el .IP \fBKeySysWorkspace3TakeWin\fR=\f(CWAlt+Ctrl+Shift+3\fR 4
+.IX Item "KeySysWorkspace3TakeWin=Alt+Ctrl+Shift+3"
+Takes the active window to workspace 3.
+.ie n .IP "\fBKeySysWorkspace4TakeWin\fR=""Alt+Ctrl+Shift+4""" 4
+.el .IP \fBKeySysWorkspace4TakeWin\fR=\f(CWAlt+Ctrl+Shift+4\fR 4
+.IX Item "KeySysWorkspace4TakeWin=Alt+Ctrl+Shift+4"
+Takes the active window to workspace 4.
+.ie n .IP "\fBKeySysWorkspace5TakeWin\fR=""Alt+Ctrl+Shift+5""" 4
+.el .IP \fBKeySysWorkspace5TakeWin\fR=\f(CWAlt+Ctrl+Shift+5\fR 4
+.IX Item "KeySysWorkspace5TakeWin=Alt+Ctrl+Shift+5"
+Takes the active window to workspace 5.
+.ie n .IP "\fBKeySysWorkspace6TakeWin\fR=""Alt+Ctrl+Shift+6""" 4
+.el .IP \fBKeySysWorkspace6TakeWin\fR=\f(CWAlt+Ctrl+Shift+6\fR 4
+.IX Item "KeySysWorkspace6TakeWin=Alt+Ctrl+Shift+6"
+Takes the active window to workspace 6.
+.ie n .IP "\fBKeySysWorkspace7TakeWin\fR=""Alt+Ctrl+Shift+7""" 4
+.el .IP \fBKeySysWorkspace7TakeWin\fR=\f(CWAlt+Ctrl+Shift+7\fR 4
+.IX Item "KeySysWorkspace7TakeWin=Alt+Ctrl+Shift+7"
+Takes the active window to workspace 7.
+.ie n .IP "\fBKeySysWorkspace8TakeWin\fR=""Alt+Ctrl+Shift+8""" 4
+.el .IP \fBKeySysWorkspace8TakeWin\fR=\f(CWAlt+Ctrl+Shift+8\fR 4
+.IX Item "KeySysWorkspace8TakeWin=Alt+Ctrl+Shift+8"
+Takes the active window to workspace 8.
+.ie n .IP "\fBKeySysWorkspace9TakeWin\fR=""Alt+Ctrl+Shift+9""" 4
+.el .IP \fBKeySysWorkspace9TakeWin\fR=\f(CWAlt+Ctrl+Shift+9\fR 4
+.IX Item "KeySysWorkspace9TakeWin=Alt+Ctrl+Shift+9"
+Takes the active window to workspace 9.
+.ie n .IP "\fBKeySysWorkspace10TakeWin\fR=""Alt+Ctrl+Shift+0""" 4
+.el .IP \fBKeySysWorkspace10TakeWin\fR=\f(CWAlt+Ctrl+Shift+0\fR 4
+.IX Item "KeySysWorkspace10TakeWin=Alt+Ctrl+Shift+0"
+Takes the active window to workspace 10.
+.ie n .IP "\fBKeySysWorkspace11TakeWin\fR=""Alt+Ctrl+Shift+minus""" 4
+.el .IP \fBKeySysWorkspace11TakeWin\fR=\f(CWAlt+Ctrl+Shift+minus\fR 4
+.IX Item "KeySysWorkspace11TakeWin=Alt+Ctrl+Shift+minus"
+Takes the active window to workspace 11.
+.ie n .IP "\fBKeySysWorkspace12TakeWin\fR=""Alt+Ctrl+Shift+equal""" 4
+.el .IP \fBKeySysWorkspace12TakeWin\fR=\f(CWAlt+Ctrl+Shift+equal\fR 4
+.IX Item "KeySysWorkspace12TakeWin=Alt+Ctrl+Shift+equal"
+Takes the active window to workspace 12.
+.ie n .IP "\fBKeySysTileVertical\fR=""Alt+Shift+F2""" 4
+.el .IP \fBKeySysTileVertical\fR=\f(CWAlt+Shift+F2\fR 4
+.IX Item "KeySysTileVertical=Alt+Shift+F2"
+Tiles all windows from left to right maximized vertically.
+.ie n .IP "\fBKeySysTileHorizontal\fR=""Alt+Shift+F3""" 4
+.el .IP \fBKeySysTileHorizontal\fR=\f(CWAlt+Shift+F3\fR 4
+.IX Item "KeySysTileHorizontal=Alt+Shift+F3"
+Tiles all windows from top to bottom maximized horizontally.
+.ie n .IP "\fBKeySysCascade\fR=""Alt+Shift+F4""" 4
+.el .IP \fBKeySysCascade\fR=\f(CWAlt+Shift+F4\fR 4
+.IX Item "KeySysCascade=Alt+Shift+F4"
+Makes a horizontal cascade of all windows which are maximized vertically.
+.ie n .IP "\fBKeySysArrange\fR=""Alt+Shift+F5""" 4
+.el .IP \fBKeySysArrange\fR=\f(CWAlt+Shift+F5\fR 4
+.IX Item "KeySysArrange=Alt+Shift+F5"
+Rearranges the windows.
+.ie n .IP "\fBKeySysUndoArrange\fR=""Alt+Shift+F7""" 4
+.el .IP \fBKeySysUndoArrange\fR=\f(CWAlt+Shift+F7\fR 4
+.IX Item "KeySysUndoArrange=Alt+Shift+F7"
+Undoes arrangement.
+.ie n .IP "\fBKeySysArrangeIcons\fR=""Alt+Shift+F8""" 4
+.el .IP \fBKeySysArrangeIcons\fR=\f(CWAlt+Shift+F8\fR 4
+.IX Item "KeySysArrangeIcons=Alt+Shift+F8"
+Rearranges icons.
+.ie n .IP "\fBKeySysMinimizeAll\fR=""Alt+Shift+F9""" 4
+.el .IP \fBKeySysMinimizeAll\fR=\f(CWAlt+Shift+F9\fR 4
+.IX Item "KeySysMinimizeAll=Alt+Shift+F9"
+Minimizes all windows.
+.ie n .IP "\fBKeySysHideAll\fR=""Alt+Shift+F11""" 4
+.el .IP \fBKeySysHideAll\fR=\f(CWAlt+Shift+F11\fR 4
+.IX Item "KeySysHideAll=Alt+Shift+F11"
+Hides all windows.
+.ie n .IP "\fBKeySysShowDesktop\fR=""Alt+Ctrl+d""" 4
+.el .IP \fBKeySysShowDesktop\fR=\f(CWAlt+Ctrl+d\fR 4
+.IX Item "KeySysShowDesktop=Alt+Ctrl+d"
+Unmaps all windows to show the desktop.
+.ie n .IP "\fBKeySysCollapseTaskBar\fR=""Alt+Ctrl+h""" 4
+.el .IP \fBKeySysCollapseTaskBar\fR=\f(CWAlt+Ctrl+h\fR 4
+.IX Item "KeySysCollapseTaskBar=Alt+Ctrl+h"
+Hides the task bar.
+.ie n .IP "\fBKeyTaskBarSwitchNext\fR=""undefined""" 4
+.el .IP \fBKeyTaskBarSwitchNext\fR=\f(CWundefined\fR 4
+.IX Item "KeyTaskBarSwitchNext=undefined"
+Switches to the next window in the task bar.
+.ie n .IP "\fBKeyTaskBarSwitchPrev\fR=""undefined""" 4
+.el .IP \fBKeyTaskBarSwitchPrev\fR=\f(CWundefined\fR 4
+.IX Item "KeyTaskBarSwitchPrev=undefined"
+Switches to the previous window in the task bar.
+.ie n .IP "\fBKeyTaskBarMoveNext\fR=""undefined""" 4
+.el .IP \fBKeyTaskBarMoveNext\fR=\f(CWundefined\fR 4
+.IX Item "KeyTaskBarMoveNext=undefined"
+Moves the task bar button of the current window
+right.
+.ie n .IP "\fBKeyTaskBarMovePrev\fR=""undefined""" 4
+.el .IP \fBKeyTaskBarMovePrev\fR=\f(CWundefined\fR 4
+.IX Item "KeyTaskBarMovePrev=undefined"
+Moves the task bar button of the current window
+left.
+.ie n .IP "\fBKeySysWinListMenu\fR=""undefined""" 4
+.el .IP \fBKeySysWinListMenu\fR=\f(CWundefined\fR 4
+.IX Item "KeySysWinListMenu=undefined"
+Shows the window list menu.
+.ie n .IP "\fBKeySysKeyboardNext\fR=""undefined""" 4
+.el .IP \fBKeySysKeyboardNext\fR=\f(CWundefined\fR 4
+.IX Item "KeySysKeyboardNext=undefined"
+Switch to the next keyboard layout in the KeyboardLayouts list.
+.ie n .IP "\fBKeySysSwitchNext\fR=""Alt+Tab""" 4
+.el .IP \fBKeySysSwitchNext\fR=\f(CWAlt+Tab\fR 4
+.IX Item "KeySysSwitchNext=Alt+Tab"
+Opens the \f(CW\*(C`QuickSwitch\*(C'\fR popup (see "INPUT FOCUS")
+and/or moves the selector in the \f(CW\*(C`QuickSwitch\*(C'\fR popup.
+.ie n .IP "\fBKeySysSwitchLast\fR=""Alt+Shift+Tab""" 4
+.el .IP \fBKeySysSwitchLast\fR=\f(CWAlt+Shift+Tab\fR 4
+.IX Item "KeySysSwitchLast=Alt+Shift+Tab"
+Works like \f(CW\*(C`KeySysSwitchNext\*(C'\fR but moving in the
+opposite direction.
+.ie n .IP "\fBKeySysSwitchClass\fR=""Alt+grave""" 4
+.el .IP \fBKeySysSwitchClass\fR=\f(CWAlt+grave\fR 4
+.IX Item "KeySysSwitchClass=Alt+grave"
+Is like \f(CW\*(C`KeySysSwitchNext\*(C'\fR but only for windows
+with the same WM_CLASS property as the currently focused window.
+.SS "MOUSE BINDINGS"
+.IX Subsection "MOUSE BINDINGS"
+You can control windows by a modified mouse button press:
+.ie n .IP "\fBMouseWinMove\fR=""Alt+Pointer_Button1""" 4
+.el .IP \fBMouseWinMove\fR=\f(CWAlt+Pointer_Button1\fR 4
+.IX Item "MouseWinMove=Alt+Pointer_Button1"
+Moves the window under the mouse over the screen.
+.ie n .IP "\fBMouseWinSize\fR=""Alt+Pointer_Button3""" 4
+.el .IP \fBMouseWinSize\fR=\f(CWAlt+Pointer_Button3\fR 4
+.IX Item "MouseWinSize=Alt+Pointer_Button3"
+Resizes the window.  Keep the key and button pressed.
+To enlarge the window move the mouse button away from the center.  To
+shrink it move towards the centre.
+.ie n .IP "\fBMouseWinRaise\fR=""Ctrl+Alt+Pointer_Button1""" 4
+.el .IP \fBMouseWinRaise\fR=\f(CWCtrl+Alt+Pointer_Button1\fR 4
+.IX Item "MouseWinRaise=Ctrl+Alt+Pointer_Button1"
+Raises the window under the mouse.
+.ie n .IP "\fBMouseWinLower\fR=""Ctrl+Alt+Pointer_Button1""" 4
+.el .IP \fBMouseWinLower\fR=\f(CWCtrl+Alt+Pointer_Button1\fR 4
+.IX Item "MouseWinLower=Ctrl+Alt+Pointer_Button1"
+Lowers the window under the mouse.
+If this is equal to \f(CW\*(C`MouseWinRaise\*(C'\fR and the window can be raised
+then \f(CW\*(C`MouseWinRaise\*(C'\fR takes preference over \f(CW\*(C`MouseWinLower\*(C'\fR.
+.IP "\fBMouseWinTabbing\fR=""Shift+Pointer_Button2""" 4
+.IX Item "MouseWinTabbing=""Shift+Pointer_Button2"""
+Mouse binding to create tabs.
+Drag the title bar with this button over another title bar.
+When they start to flash, release the button to merge the frame tabs.
+.PP
+The title frame of a window also listens for mouse clicks.  Left double
+clicking maximizes the window (\f(CW\*(C`TitleBarMaximizeButton=1\*(C'\fR). Press
+Shift to only maximize vertically. Press Alt+Shift for horizontally.
+Middle double clicking rolls up the window (\f(CW\*(C`TitleBarRollupButton=2\*(C'\fR).
+Also press Shift to maximize horizontally. If \fBTitleBarRollupButton\fR
+is either 4 or 5 then the scroll wheel controls rolling up or down.
+Pressing a mouse button and moving it will move the window.
+\&\f(CW\*(C`Alt+Pointer_Button1\*(C'\fR lowers the window.
+.PP
+When the mouse is on the window frame then a left click raises the
+window.  Dragging with the left button down resizes the window.
+Clicking the right button pops up the context menu.  Dragging with the
+right button moves the window.
+.PP
+Clicking on the desktop activates a menu.  The middle button shows the
+window list (\f(CW\*(C`DesktopWinListButton=2\*(C'\fR).  The right button shows the
+root menu (\f(CW\*(C`DesktopMenuButton=3\*(C'\fR). If you press \f(CW\*(C`Ctrl+Alt\*(C'\fR then
+the mouse wheel will focus all applications in turn.
+.SS SIGNALS
+.IX Subsection "SIGNALS"
+\&\fBicewm\fR supports the following signals:
+.IP \fBSIGHUP\fR 4
+.IX Item "SIGHUP"
+\&\fBicewm\fR will restart itself. It is a way to reload the configuration.
+.IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4
+.IX Item "SIGINT, SIGTERM"
+\&\fBicewm\fR will cease to manage application windows and terminate.
+.IP \fBSIGQUIT\fR 4
+.IX Item "SIGQUIT"
+\&\fBicewm\fR will initiate the logout procedure.  If a \f(CW\*(C`LogoutCommand\*(C'\fR
+preferences option was configured it will be executed.
+.IP \fBSIGUSR2\fR 4
+.IX Item "SIGUSR2"
+Toggle the logging of X11 events, if \f(CW\*(C`logevents\*(C'\fR was configured.
+.SS "ENVIRONMENT VARIABLES"
+.IX Subsection "ENVIRONMENT VARIABLES"
+.IP \fBICEWM_PRIVCFG\fR 4
+.IX Item "ICEWM_PRIVCFG"
+The directory for user private configuration files.  When this
+environment variable is not specified, the default directory is
+\&\fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm\fR when that directory exists, otherwise the
+default value is \fI\fR\f(CI$HOME\fR\fI/.icewm\fR.
+.IP \fBDISPLAY\fR 4
+.IX Item "DISPLAY"
+The name of the X11 server.  See \fBXorg\fR\|(1) or \fBXserver\fR\|(1).  This
+value can be overridden by the \fB\-\-display\fR option.
+.IP "\fBMAILPATH\fR, \fBMAIL\fR" 4
+.IX Item "MAILPATH, MAIL"
+Gives the location of your mailbox.  If the schema is omitted the local
+"file" schema is assumed.  This is used by the mailbox applet in the
+task bar to show the status of your mailbox.  If the \f(CW\*(C`MailBoxPath\*(C'\fR
+option in the \fIpreferences\fR file is set, then that one takes
+precedence.
+.SS FILES
+.IX Subsection "FILES"
+.SS "CONFIGURATION DIRECTORIES"
+.IX Subsection "CONFIGURATION DIRECTORIES"
+\&\fBicewm\fR looks for configuration files in the following directories, in
+the given order, until it finds one:
+.ie n .IP \fR\fI$ICEWM_PRIVCFG\fR\fI/\fR 4
+.el .IP \fR\f(CI$ICEWM_PRIVCFG\fR\fI/\fR 4
+.IX Item "$ICEWM_PRIVCFG/"
+Contains user-specific configurations.  When \fBICEWM_PRIVCFG\fR is
+specified, this directory takes precedence over
+\&\fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm\fR and \fI\fR\f(CI$HOME\fR\fI/.icewm\fR.
+.ie n .IP \fR\fI$XDG_CONFIG_HOME\fR\fI/icewm/\fR 4
+.el .IP \fR\f(CI$XDG_CONFIG_HOME\fR\fI/icewm/\fR 4
+.IX Item "$XDG_CONFIG_HOME/icewm/"
+Contains user-specific configurations.  When this directory exists it
+take precedence over \fR\f(CI$HOME\fR\fI/.icewm\fR.
+.ie n .IP \fR\fI$HOME\fR\fI/.icewm/\fR 4
+.el .IP \fR\f(CI$HOME\fR\fI/.icewm/\fR 4
+.IX Item "$HOME/.icewm/"
+Contains user-specific configurations.  This is the historical default
+directory.
+.IP \fI/etc/icewm/\fR 4
+.IX Item "/etc/icewm/"
+Contains system-wide customized defaults.  Please note that your local
+installation may have been configured to use a different system
+location.  The output of \f(CW\*(C`icewm \-\-directories\*(C'\fR will show this location.
+.IP \fI/usr/share/icewm/\fR 4
+.IX Item "/usr/share/icewm/"
+Default local installation settings.
+.SS "CONFIGURATION FILES"
+.IX Subsection "CONFIGURATION FILES"
+.IP \fIenv\fR 4
+.IX Item "env"
+\&\fBicewm\-session\fR\|(1) loads additional environment variables from the file
+\&\fIenv\fR.  Each line is subjected to POSIX shell expansion by
+\&\fBwordexp\fR\|(3).  Comment lines starting by a hash-sign (\f(CW\*(C`#\*(C'\fR) are ignored.
+\&\fBicewm\-session\fR\|(1) will load those expanded lines that contain a name,
+followed by an equals sign, followed by the value (which may be empty).
+.Sp
+See \fBicewm\-env\fR\|(5).
+.IP \fIfocus_mode\fR 4
+.IX Item "focus_mode"
+Defines the initial value for \f(CW\*(C`FocusMode\*(C'\fR.  Its default value is
+\&\f(CW\*(C`FocusMode=1\*(C'\fR (Click-to-focus).  This can be changed via the menu.
+\&\fBicewm\fR will save the Focus menu choice in this file.
+.Sp
+See \fBicewm\-focus_mode\fR\|(5).
+.IP \fIkeys\fR 4
+.IX Item "keys"
+Global keybindings to launch applications, which need not be window
+manager related.  Each non-empty line starts with the word \f(CW\*(C`key\*(C'\fR.
+After one or more spaces follows a double-quoted string of the bound X11
+key combination like \f(CW\*(C`Alt+Ctrl+Shift+X\*(C'\fR.  Then after at least one space
+follows a shell command-line that will be executed by \fBicewm\fR whenever
+this key combination is pressed.  For example, the following line
+creates a hotkey to reload the \fBicewm\fR configuration:
+.Sp
+.Vb 1
+\& key "Ctrl+Shift+r"      icesh restart
+.Ve
+.Sp
+See \fBicewm\-keys\fR\|(5).
+.IP \fImenu\fR 4
+.IX Item "menu"
+A menu of applications; usually customized by the user.  \fBicewm\fR
+provides the \fBicewm\-menu\-fdo\fR\|(1) program to generate a default menu.
+Similar programs are \fBxdg_menu\fR\|(1), \fBmmaker\fR\|(1) (MenuMaker),
+\&\fBxde\-menu\fR\|(1), \fBxdgmenumaker\fR\|(1).
+.Sp
+See \fBicewm\-menu\fR\|(5).
+.IP \fIpreferences\fR 4
+.IX Item "preferences"
+Contains general settings like paths, colors and fonts, but also options
+to control the \fBicewm\fR focus behaviour and the applets that are
+started in the task bar.  The \fBicewm\fR installation will provide a
+default \fIpreferences\fR file, which can be copied to the \fBicewm\fR user
+configuration directory and modified.
+.Sp
+See \fBicewm\-preferences\fR\|(5).
+.IP \fIprefoverride\fR 4
+.IX Item "prefoverride"
+Settings which override the settings from a theme.  Some of the \fBicewm\fR
+configuration options from the preferences file that control the
+look-and-feel may be overridden by the theme, if the theme designer
+thinks this is desirable.  However, this \fIprefoverride\fR file will again
+override this for a few specific options of your choosing.  It is safe
+to leave this file empty initially.
+.Sp
+See \fBicewm\-prefoverride\fR\|(5).
+.IP \fIprograms\fR 4
+.IX Item "programs"
+An automatically generated menu of applications.  This could be used by
+\&\fBwmconfig\fR\|(1), menu or similar programs to give easy access to all the
+desktop applications that are installed on the system.
+.Sp
+See \fBicewm\-programs\fR\|(5).
+.IP \fItheme\fR 4
+.IX Item "theme"
+This file contains the name of the default theme.  On startup \fBicewm\fR
+reads this file to obtain the theme name, unless \fBicewm\fR was started
+with the \fB\-\-theme\fR option.  Whenever a different theme is selected from
+the \fBicewm\fR Menu then the theme file is overwritten with the name of
+the selected theme.  This theme file contains the keyword \f(CW\*(C`Theme\*(C'\fR,
+followed by an equals sign, followed by a double-quoted string with the
+theme name.  The theme name is the name of the theme directory, followed
+by a slash, followed by the theme file.  Usually the theme file is just
+\&\fIdefault.theme\fR, but a theme may have alternatives.  Alternatives are
+small tweaks of a theme.  These are specified in their own \fI.theme\fR
+file, which replaces \fIdefault.theme\fR.  If no theme file exists then
+\&\fBicewm\fR will use the default setting of
+\&\f(CW\*(C`Theme="default/default.theme"\*(C'\fR.
+.Sp
+See \fBicewm\-theme\fR\|(5).
+.IP \fItoolbar\fR 4
+.IX Item "toolbar"
+Contains names of quick to launch applications with icons for the task
+bar.  Each non-empty non-comment line starts with the keyword \fBprog\fR.
+After one or more spaces follows a name, which is displayed in a tool
+tip whenever the mouse cursor hovers over the toolbar icon.  This name
+may be a double quoted string.  Then follows the bare name of the icon
+to use without extensions.  This icon will be shown in the toolbar.  The
+last component is a shell command-line that will be executed whenever
+the user presses the icon in the toolbar.  For example, the following
+line in toolbar will create a button with tool tip \f(CW\*(C`Mozilla Firefox\*(C'\fR
+with the \fIfirefox\fR icon that launches \fBfirefox\fR\|(1) when clicked:
+.Sp
+.Vb 1
+\& prog  "Mozilla Firefox"  firefox  /usr/bin/firefox \-\-private\-window
+.Ve
+.Sp
+See \fBicewm\-toolbar\fR\|(5).
+.IP \fIwinoptions\fR 4
+.IX Item "winoptions"
+Contains settings to control window appearance and behaviour that are
+specific to applications or groups of applications.  Options can control
+the border, whether it appears on the task bar, the window list, the
+system tray and the workspaces.  Also its layer, geometry, whether it
+can be moved, resized and closed.
+.Sp
+See \fBicewm\-winoptions\fR\|(5).
+.IP \fIstartup\fR 4
+.IX Item "startup"
+Contains commands to be executed on \fBicewm\fR startup.  This is an
+executable script with commands to tweak X11 settings and launch some
+applications that need to be active whenever \fBicewm\fR is started.
+It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR starts.
+.Sp
+See \fBicewm\-startup\fR\|(5).
+.IP \fIshutdown\fR 4
+.IX Item "shutdown"
+Contains commands to be executed on \fBicewm\fR shutdown.  This is an
+executable script with commands to be executed in the last stage of
+\&\fBicewm\fR termination.  Typically they may undo some of the effects of
+the \fIstartup\fR script.  It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR
+terminates.
+.Sp
+See \fBicewm\-shutdown\fR\|(5).
+.SS "CONFIGURATION SUBDIRECTORIES"
+.IX Subsection "CONFIGURATION SUBDIRECTORIES"
+.IP \fIcursors\fR 4
+.IX Item "cursors"
+May contain cursor icons in the XPM image format. These overrule cursors
+provided by a theme. There are 3 direction cursors: \fIleft.xpm\fR,
+\&\fIright.xpm\fR, \fImove.xpm\fR, 8 resize cursors: \fIsizeR.xpm\fR, \fIsizeTR.xpm\fR,
+\&\fIsizeT.xpm\fR, \fIsizeTL.xpm\fR, \fIsizeL.xpm\fR, \fIsizeBL.xpm\fR, \fIsizeB.xpm\fR,
+\&\fIsizeBR.xpm\fR, and 4 scroll cursors: \fIscrollL.xpm\fR, \fIscrollR.xpm\fR,
+\&\fIscrollU.xpm\fR, and \fIscrollD.xpm\fR.
+By default an XPM header defines four dimensions: width, height, colors
+and chars-per-pixel. For cursors this must be extended to six. The last
+two are the \fIx\-hotspot\fR and the \fIy\-hotspot\fR. These define which point
+in the XPM image is the sensitive point for the mouse pointer.
+.IP \fIicons\fR 4
+.IX Item "icons"
+Contains icons that are used to identify applications.  Usually these
+files are in the XPM format, but the PNG and SVG image formats are also
+supported.  The names of icon files may follow a specific naming
+pattern, like \fIapp_32x32.xpm\fR.  They start with a base name, usually
+this is just a single word.  Then follows an underscore, followed by a
+size specification in the format \f(CW\*(C`SIZExSIZE\*(C'\fR.  This is followed by a
+dot and the file extension, where the extension denotes the icon image
+format.  Common sizes are 16, 32 and 48 for small, large and huge icons.
+This depends on the respective \f(CW\*(C`IconSize\*(C'\fR preferences options.
+.IP \fIledclock\fR 4
+.IX Item "ledclock"
+Pictures of digits for the LED clock which is displayed in the
+bottom-right corner of the task bar.  These can be seen when the
+\&\f(CW\*(C`TaskBarShowClock\*(C'\fR and \f(CW\*(C`TaskBarClockLeds\*(C'\fR options are both set to 1.
+.IP \fImailbox\fR 4
+.IX Item "mailbox"
+Icons that are used to display different states of the mailbox applet
+in the task bar.  There are five states and each has its own icon:
+\&\fImail.xpm\fR, \fInewmail.xpm\fR, \fIunreadmail.xpm\fR, \fInomail.xpm\fR,
+\&\fIerrmail.xpm\fR.
+.IP \fIsounds\fR 4
+.IX Item "sounds"
+Audio files that are played by \fBicesound\fR\|(1) on GUI events.  These
+are: \fIstartup.wav\fR, \fIshutdown.wav\fR, \fIrestart.wav\fR, \fIlaunchApp.wav\fR,
+\&\fIworkspaceChange.wav\fR, \fIwindowOpen.wav\fR, \fIwindowClose.wav\fR,
+\&\fIdialogOpen.wav\fR, \fIdialogClose.wav\fR, \fIwindowMax.wav\fR,
+\&\fIwindowRestore.wav\fR, \fIwindowMin.wav\fR, \fIwindowHide.wav\fR,
+\&\fIwindowRollup.wav\fR, \fIwindowMoved.wav\fR, \fIwindowSized.wav\fR,
+\&\fIwindowLower.wav\fR.
+.IP \fItaskbar\fR 4
+.IX Item "taskbar"
+Pictures to customize the look of the task bar.  These include:
+\&\fItaskbarbg.xpm\fR, \fItaskbuttonactive.xpm\fR, \fItaskbuttonbg.xpm\fR,
+\&\fItaskbuttonminimized.xpm\fR, \fItoolbuttonbg.xpm\fR,
+\&\fIworkspacebuttonactive.xpm\fR, \fIworkspacebuttonbg.xpm\fR.
+.IP \fIthemes\fR 4
+.IX Item "themes"
+A directory to store themes.  Each theme is stored in its own
+sub-directory in the \fIthemes\fR directory. A theme contains at least a
+\&\fIdefault.theme\fR file, and optionally theme alternatives which are
+additional files that have a \fI.theme\fR file name extension and that
+contain tweaks of the \fIdefault.theme\fR file.
+How to create a theme is explained in the
+IceWM Theme Creation Howto.
+.IP \fIworkspace\fR 4
+.IX Item "workspace"
+If \f(CW\*(C`PagerShowPreview\*(C'\fR is disabled, icewm looks in the \f(CW\*(C`workspace\*(C'\fR
+directory for images to draw on a workspace button. The image filename
+should have the name of the workspace. The image extension is optional.
+.SS OPACITY
+.IX Subsection "OPACITY"
+IceWM supports window opacity and transparency in connection with an
+external compositor like \fBcompton\fR\|(1) or \fBpicom\fR\|(1).
+If a client window sets the \f(CW\*(C`_NET_WM_WINDOW_OPACITY\*(C'\fR property on
+its window, then \fBicewm\fR will copy this to the outer frame window,
+where the compositor will read it and adjust the opacity accordingly.
+.PP
+The opacity can also be set in the \fBicewm\-winoptions\fR\|(5) file.
+\&\fBicesh\fR\|(1) can control the opacity level of running applications.
+.PP
+The _NET_WM_WINDOW_TYPE properties that \fBicewm\fR sets on its windows
+are \fIDIALOG\fR, \fINOTIFICATION\fR, \fIPOPUP_MENU\fR and \fITOOLTIP\fR. The output
+of \f(CW\*(C`icesh windows\*(C'\fR shows their WM_CLASS values. These can be helpful
+to configure compton.
+.SS EXAMPLES
+.IX Subsection "EXAMPLES"
+Examples of the above configuration files can be found in the default
+installation path or in the system-wide defaults.  See the output of
+\&\f(CW\*(C`icewm \-\-directories\*(C'\fR for their locations.
+.SS "CONFORMING TO"
+.IX Subsection "CONFORMING TO"
+ICCCM 2.0: partial.  NetWM/EWMH: extensive.
+See the file \fICOMPLIANCE\fR in the distribution for full details.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+\&\fBicehelp\fR\|(1),
+\&\fBicesh\fR\|(1),
+\&\fBicesound\fR\|(1),
+\&\fBicewm\-env\fR\|(5),
+\&\fBicewm\-focus_mode\fR\|(5),
+\&\fBicewm\-keys\fR\|(5),
+\&\fBicewm\-menu\fR\|(5),
+\&\fBicewm\-menu\-fdo\fR\|(1),
+\&\fBicewm\-menu\-xrandr\fR\|(1),
+\&\fBicewm\-preferences\fR\|(5),
+\&\fBicewm\-prefoverride\fR\|(5),
+\&\fBicewm\-programs\fR\|(5),
+\&\fBicewm\-session\fR\|(1),
+\&\fBicewm\-set\-gnomewm\fR\|(1),
+\&\fBicewm\-shutdown\fR\|(5),
+\&\fBicewm\-startup\fR\|(5),
+\&\fBicewm\-theme\fR\|(5),
+\&\fBicewm\-toolbar\fR\|(5),
+\&\fBicewm\-winoptions\fR\|(5),
+\&\fBicewmbg\fR\|(1),
+\&\fBicewmhint\fR\|(1),
+\&\fBsetxkbmap\fR\|(1),
+\&\fBXorg\fR\|(1),
+\&\fBXserver\fR\|(1),
+\&\fBxinit\fR\|(1),
+\&\fBxprop\fR\|(1),
+\&\fBxwininfo\fR\|(1),
+\&\fBwmctrl\fR\|(1).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewmbg.1 b/upstream/mageia-cauldron/man1/icewmbg.1
new file mode 100644
index 00000000..124faf45
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewmbg.1
@@ -0,0 +1,298 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWMBG 1"
+.TH ICEWMBG 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+.Vb 1
+\& icewmbg \- a background settings manager for the IceWM window manager
+.Ve
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewmbg\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewmbg\fR can assign a colour or image to the \fIX11\fR desktop background.
+Common image formats are supported.  Each \fBicewm\fR\|(1) workspace can have
+its own background.
+.PP
+When the background image changes, \fBicewmbg\fR can be notified to
+update the background.  When switching workspaces, it checks the image
+file modification time.  If the file has changed, it reloads the
+image from file.
+.PP
+\&\fBicewmbg\fR supports semitransparency.  Semitransparent background
+images and colours can be configured.
+.PP
+It uses RandR or Xinerama to support backgrounds on all connected
+monitors.  When monitors appear/disappear, or change their resolution,
+\&\fBicewmbg\fR will adjust.  It supports an option for one large background
+over all monitors.
+.PP
+It will update the \f(CW\*(C`_ICEWMBG_IMAGE\*(C'\fR property of the root window to the
+path of the background image whenever it changes the desktop background.
+.PP
+\&\fBicewmbg\fR is started automatically by \fBicewm\-session\fR\|(1).
+If there is just a single background for all workspaces, icewmbg may
+conclude that it can safely exit after setting the desktop background,
+to free its system memory.  If the screen size changes, icewm will then
+attempt to restart icewmbg, preferably via icewm-session.
+.SS ARGUMENTS
+.IX Subsection "ARGUMENTS"
+.SS "SPECIFIC OPTIONS"
+.IX Subsection "SPECIFIC OPTIONS"
+Where multiple values can be given for images
+or colours, they are separated by comma's.
+Each such value may be enclosed in double quotes.
+If \fIFILE\fR is a directory, all images
+from that directory are used in sorted order.
+If the value starts with an exclamation mark, as in \fI!FILE\fR,
+the images from the directory \fIFILE\fR are permuted randomly.
+Image file names or directory names may have \fBglob\fR\|(7) wildcards,
+or they may start with a tilde or environment variable.
+.IP "\fB\-f\fR, \fB\-\-fork\fR" 4
+.IX Item "-f, --fork"
+Fork into the background and detach from the terminal.
+.IP "\fB\-p\fR, \fB\-\-replace\fR" 4
+.IX Item "-p, --replace"
+Replace an existing \fBicewmbg\fR. If there is a running \fBicewmbg\fR,
+it is instructed to quit.  The new \fBicewmbg\fR will take over.
+.IP "\fB\-q\fR, \fB\-\-quit\fR" 4
+.IX Item "-q, --quit"
+Tell the running \fBicewmbg\fR to quit. This option is used by
+\&\fBicewm\-session\fR\|(1) when \fBicewm\fR\|(1) exits.
+.IP "\fB\-r\fR, \fB\-\-restart\fR" 4
+.IX Item "-r, --restart"
+Tell the running \fBicewmbg\fR to restart itself.  This is useful when
+settings in have changed. If no icewmbg is active, it starts one.
+.IP "\fB\-u\fR, \fB\-\-shuffle\fR" 4
+.IX Item "-u, --shuffle"
+Shuffle the list of background images randomly.
+This option may be given again whenever the running
+\&\fBicewmbg\fR should reshuffle its list of background images.
+.IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4
+.IX Item "-c, --config=FILE"
+Load preferences from \fIFILE\fR.
+.IP "\fB\-t\fR, \fB\-\-theme\fR=\fITHEME\fR" 4
+.IX Item "-t, --theme=THEME"
+Use the theme named \fITHEME\fR.
+.IP "\fB\-i\fR, \fB\-\-image\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
+.IX Item "-i, --image=FILE[,FILE]*"
+Load background images from each \fIFILE\fR.
+This overrules the \f(CW\*(C`DesktopBackgroundImage\*(C'\fR preference.
+When more than one image is given, they are assigned
+to each workspace in the given order.
+.IP "\fB\-k\fR, \fB\-\-color\fR=\fICOLOR\fR[,\fICOLOR\fR]*" 4
+.IX Item "-k, --color=COLOR[,COLOR]*"
+Use background colours from each \fICOLOR\fR.
+This overrules the \f(CW\*(C`DesktopBackgroundColor\*(C'\fR preference.
+.IP "\fB\-s\fR, \fB\-\-semis\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
+.IX Item "-s, --semis=FILE[,FILE]*"
+Load transparency images from each \fIFILE\fR.
+This overrules the \f(CW\*(C`DesktopTransparencyImage\*(C'\fR preference.
+.IP "\fB\-x\fR, \fB\-\-trans\fR=\fINAME\fR[,\fINAME\fR]" 4
+.IX Item "-x, --trans=NAME[,NAME]"
+Use transparency colours for each \fINAME\fR.
+This overrules the \f(CW\*(C`DesktopTransparencyColor\*(C'\fR preference.
+.IP "\fB\-e\fR, \fB\-\-center\fR={\fI0\fR|\fI1\fR}" 4
+.IX Item "-e, --center={0|1}"
+Disable/Enable centring background.
+This overrules the \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR preference.
+.IP "\fB\-a\fR, \fB\-\-scaled\fR={\fI0\fR|\fI1\fR}" 4
+.IX Item "-a, --scaled={0|1}"
+Disable/Enable scaling background.
+This overrules the \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR preference.
+.IP "\fB\-m\fR, \fB\-\-multi\fR={\fI0\fR|\fI1\fR}" 4
+.IX Item "-m, --multi={0|1}"
+Disable or enable a single background over all monitors.
+This overrules the \f(CW\*(C`DesktopBackgroundMultihead\*(C'\fR preference.
+.IP "\fB\-y\fR, \fB\-\-cycle\fR=\fISECONDS\fR" 4
+.IX Item "-y, --cycle=SECONDS"
+Cycle over the list of background images every \fISECONDS\fR.
+This overrules the \f(CW\*(C`CycleBackgroundsPeriod\*(C'\fR preference.
+.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
+.IX Item "-o, --output=FILE"
+Redirect all output to \fIFILE\fR.
+A leading tilde or environment variable is expanded.
+.IP \fB\-\-postpreferences\fR 4
+.IX Item "--postpreferences"
+Print a list of all preference values that \fBicewmbg\fR will use.
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
+.IX Item "-d, --display=DISPLAY"
+Use \fIDISPLAY\fR to connect to the X server.
+Otherwise use DISPLAY from the environment.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions to \fIstdout\fR for the program and exit.
+.IP \fB\-\-sync\fR 4
+.IX Item "--sync"
+Use a slow synchronous mode to communicate with the \fIX11\fR server.
+.IP \fB\-\-verbose\fR 4
+.IX Item "--verbose"
+Report on some of the activities.
+.SS FILES
+.IX Subsection "FILES"
+Additional arguments, which either are a path or which have an image
+extension, are assumed to be background image files or directories.
+.SS PREFERENCES
+.IX Subsection "PREFERENCES"
+By default \fBicewmbg\fR loads settings from the \fBicewm\fR\|(1)
+preferences file. See \fBicewm\-preferences\fR\|(5) for details.
+The settings read are:
+.PP
+.Vb 10
+\&  DesktopBackgroundCenter    \- Display desktop background centered
+\&  DesktopBackgroundScaled    \- Display desktop background scaled
+\&  DesktopBackgroundColor     \- Desktop background color(s)
+\&  DesktopBackgroundImage     \- Desktop background image(s)
+\&  ShuffleBackgroundImages    \- Shuffle the list of background images
+\&  SupportSemitransparency    \- Support for semitransparent terminals
+\&  DesktopTransparencyColor   \- Semitransparency background color(s)
+\&  DesktopTransparencyImage   \- Semitransparency background image(s)
+\&  DesktopBackgroundMultihead \- One background over all monitors
+\&  CycleBackgroundsPeriod     \- Seconds between cycling over backgrounds
+.Ve
+.PP
+If these settings are set in the \fIpreferences\fR file, they can
+be overridden by the theme in the theme defaults file.
+To enforce a certain setting, set it in the \fIprefoverride\fR file instead.
+See \fBicewm\-prefoverride\fR\|(5).
+.SS WORKSPACES
+.IX Subsection "WORKSPACES"
+Each workspace can have a unique image. Specify multiple images to
+\&\fBDesktopBackgroundImage\fR separated by comma's.  Or give at least one
+directory with images. The images are assigned to each workspace in
+the order given. When icewm changes workspace, the running icewmbg
+will adapt the desktop background to the assigned image.
+.PP
+If you specify more images then there are workspaces, then
+\&\fBCycleBackgroundsPeriod\fR can set a period. When the period expires,
+icewmbg will switch to the next set of images. If you give less images
+than there are workspaces, then icewmbg will reuse previous images
+for the remaining workspaces.
+.SS "IMAGE SCALING"
+.IX Subsection "IMAGE SCALING"
+Often a background image has a different width or height than the screen.
+The image can then be replicated (tiled), centered or scaled. This is
+controlled by \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR and \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR.
+What happens for their combination is given by the following table:
+.PP
+.Vb 4
+\&  center:0 scaled:0 = The background is replicated in both directions.
+\&  center:1 scaled:0 = The background is centered, but not scaled.
+\&  center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
+\&  center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
+.Ve
+.SS EXAMPLES
+.IX Subsection "EXAMPLES"
+.Vb 1
+\&    # For four unique desktop backgrounds for four workspaces do:
+\&
+\&    icewmbg \-f \-p \-i image0,image1,image2,image3
+\&
+\&    # Or create a directory with the four images and do:
+\&
+\&    icewmbg \-f \-p \-i /path/to/directory
+\&
+\&    # The images should have proper image filename extensions.
+.Ve
+.SS SIGNALS
+.IX Subsection "SIGNALS"
+\&\fBicewmbg\fR supports the following signals:
+.IP \fBSIGHUP\fR 4
+.IX Item "SIGHUP"
+\&\fBicewmbg\fR will restart itself.
+.IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4
+.IX Item "SIGINT, SIGTERM"
+\&\fBicewmbg\fR will terminate.
+.IP \fBSIGUSR1\fR 4
+.IX Item "SIGUSR1"
+\&\fBicewmbg\fR will reshuffle the list of background images and
+update the backgrounds of all workspaces.
+.SS "SEE ALSO"
+.IX Subsection "SEE ALSO"
+\&\fBicewm\fR\|(1),
+\&\fBicewm\-preferences\fR\|(5),
+\&\fBicewm\-prefoverride\fR\|(5),
+\&\fBwmsetbg\fR\|(1),
+\&\fBxsetbg\fR\|(1),
+\&\fBxwallpaper\fR\|(1).
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icewmhint.1 b/upstream/mageia-cauldron/man1/icewmhint.1
new file mode 100644
index 00000000..0ca36bd3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icewmhint.1
@@ -0,0 +1,281 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ICEWMHINT 1"
+.TH ICEWMHINT 1 2023-12-28 "icewm 3.4.5" "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SS NAME
+.IX Subsection "NAME"
+icewmhint \- set IceWM hints by window class and instance
+.SS SYNOPSIS
+.IX Subsection "SYNOPSIS"
+\&\fBicewmhint\fR \fICLASS\fR\fB.\fR\fIINSTANCE\fR \fIOPTION\fR \fIVALUE\fR ...
+.SS DESCRIPTION
+.IX Subsection "DESCRIPTION"
+\&\fBicewmhint\fR is a utility for passing IceWM hints to \fBicewm\fR\|(1).
+\&\fBicewm\fR uses these hints for the first \fIX11 client\fR which is
+subsequently started. They take precedence over hints from
+the \fBicewm\-winoptions\fR\|(1) file.
+.PP
+A hint is a triplet consisting of a \fIclass.instance\fR, an
+\&\fIIceWM winoption\fR and its value. Multiple hints can be given per
+invocation of \fBicewmhint\fR.
+.PP
+The hints are communicated over the \f(CW\*(C`_ICEWM_WINOPTHINT\*(C'\fR property on
+the root window.  \fBicewmhint\fR appends hints to this property, while
+\&\fBicewm\fR removes the property after reading it.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+\&\fBicewmhint\fR recognizes the following options:
+.SS "COMMAND OPTIONS"
+.IX Subsection "COMMAND OPTIONS"
+Only one command option can be specified per invocation.  If no command
+option is specified, argument parsing and processing is performed.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Print a brief usage statement to \fIstdout\fR and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+.IX Item "-V, --version"
+Print the program version to \fIstdout\fR and exit.
+.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
+.IX Item "-C, --copying"
+Print copying permissions to \fIstdout\fR for the program and exit.
+.SS "GENERAL OPTIONS"
+.IX Subsection "GENERAL OPTIONS"
+.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
+.IX Item "-d, --display=DISPLAY"
+Specifies the X11 DISPLAY. If unspecified, defaults to \fR\f(CB$DISPLAY\fR\fB\fR.
+.SS ARGUMENTS
+.IX Subsection "ARGUMENTS"
+The following three arguments are required for each hint.
+.IP \fICLASS\fR\fB.\fR\fIINSTANCE\fR 4
+.IX Item "CLASS.INSTANCE"
+Specifies the ICCCM 2.0 \fBWM_CLASS\fR property in terms of resource class
+and resource name separated by a period (\f(CW\*(C`.\*(C'\fR).  For example:
+\&\f(CW\*(C`XTerm.xterm\*(C'\fR. Just the resource class or resource name without a dot
+is also acceptable, like \f(CW\*(C`XTerm\*(C'\fR or \f(CW\*(C`xterm\*(C'\fR.
+.IP \fIOPTION\fR 4
+.IX Item "OPTION"
+Specifies the \fIOPTION\fR to affect.
+.IP \fIVALUE\fR 4
+.IX Item "VALUE"
+Gives the \fIVALUE\fR for the option.
+.PP
+Multiple hints can be given.
+.SS "GENERAL OPTION ARGUMENTS"
+.IX Subsection "GENERAL OPTION ARGUMENTS"
+.IP "\fBicon\fR \fINAME\fR" 4
+.IX Item "icon NAME"
+Specifies the icon name for windows of \fICLASS\fR\fB.\fR\fIINSTANCE\fR.
+\&\fINAME\fR should be the name of the icon.  \fBicewm\fR\|(1) will use its
+usual method to locate the icon.  The default is the name provided
+by window manager hints.
+.IP "\fBworkspace\fR \fIWORKSPACE\fR" 4
+.IX Item "workspace WORKSPACE"
+Specifies the workspace on which a window of \fICLASS\fR\fB.\fR\fIINSTANCE\fR
+will be initially placed.  The default is the current workspace.
+\&\fIWORKSPACE\fR should be a workspace number counting from 0.
+.IP "\fBgeometry\fR \fIGEOMETRY\fR" 4
+.IX Item "geometry GEOMETRY"
+Specifies the initial geometry for windows of the given
+\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR.  \fIGEOMETRY\fR must be a geometry that can be
+parsed by \fBXParseGeometry\fR\|(3).  The default is the geometry provided by
+window manager hints.
+.IP "\fBorder\fR \fINUMBER\fR" 4
+.IX Item "order NUMBER"
+The sorting order of task buttons and tray icons. The default value is
+zero. Increasing positive values go farther right, while decreasing
+negative values go farther left. The order option applies to the task
+pane, the tray pane and the system tray.
+.IP "\fBopacity\fR \fINUMBER\fR" 4
+.IX Item "opacity NUMBER"
+Set the _NET_WM_WINDOW_OPACITY property if \fINUMBER\fR is a value between
+1 and 100. \fINUMBER\fR is interpreted as percentage of maximum opaqueness.
+.IP "\fBlayer\fR {\fILAYER\fR|\fINUMBER\fR}" 4
+.IX Item "layer {LAYER|NUMBER}"
+This command option specifies the layer to be associated with a
+\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR.  The default is the \f(CW\*(C`Normal\*(C'\fR layer.  \fIVALUE\fR
+is either a layer number or a symbolic layer name.  Symbolic
+layer names are:
+.Sp
+.Vb 9
+\&    Desktop     (0)  Desktop window.
+\&    Below       (2)  Below the default layer.
+\&    Normal      (4)  Default layer for windows.
+\&    OnTop       (6)  Above the default layer.
+\&    Dock        (8)  Docked windows at edge of screen.
+\&    AboveDock  (10)  Windows above the dock.
+\&    Menu       (12)  The layer for menu\*(Aqs.
+\&    Fullscreen (14)  When fullscreen and focused.
+\&    AboveAll   (15)  Always above anything.
+.Ve
+.IP "\fBtray\fR {\fBIgnore\fR|\fBMinimized\fR|\fBExclusive\fR|\fINUMBER\fR}" 4
+.IX Item "tray {Ignore|Minimized|Exclusive|NUMBER}"
+Specifies the tray handling to be applied to windows with
+\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR.  This option is specific to \fBicewm\fR\|(1) and
+sets the \f(CW\*(C`_ICEWM_TRAY\*(C'\fR property associated with the window.
+The default is \f(CW\*(C`Ignore\*(C'\fR.  \fIVALUE\fR can be an option number
+or a symbolic name as follows:
+.Sp
+.Vb 3
+\&    Ignore     (0)  only in task list.
+\&    Minimized  (1)  icon in tray, task list unminimized.
+\&    Exclusive  (2)  only in tray, not in task list.
+.Ve
+.IP "\fBframe\fR \fIlabel\fR (default: none)" 4
+.IX Item "frame label (default: none)"
+All windows with the same frame label become tabs in a single frame.
+.SS "FUNCTION OPTION ARGUMENTS"
+.IX Subsection "FUNCTION OPTION ARGUMENTS"
+Specifies which functions are disabled or enabled (0/1) for windows with
+\&\fICLASS\fR\fB.\fR\fIINSTANCE\fR.  All functions have a default value of enabled
+(1) unless overridden by the application.  The Motif-like functions are
+as follows:
+.PP
+.Vb 7
+\&    fClose     can be closed:        (default: 1).
+\&    fHide      can be hidden:        (default: 1).
+\&    fMaximize  can be maximized:     (default: 1).
+\&    fMinimize  can be minimized:     (default: 1).
+\&    fMove      can be moved:         (default: 1).
+\&    fResize    can be resized:       (default: 1).
+\&    fRollup    can be shaded:        (default: 1).
+.Ve
+.SS "DECOR OPTION ARGUMENTS"
+.IX Subsection "DECOR OPTION ARGUMENTS"
+Specifies which decorations are disabled or enabled (0/1) for windows
+with \fICLASS\fR\fB.\fR\fIINSTANCE\fR.  All decor options have a default value
+of enabled (1) unless overridden by the application. The Motif-like
+decorations are as follows:
+.PP
+.Vb 10
+\&    dBorder    has border:           (default: 1).
+\&    dClose     has close button:     (default: 1).
+\&    dDepth     has depth button:     (default: 1).
+\&    dHide      has hide button:      (default: 1).
+\&    dMaximize  has maximize button:  (default: 1).
+\&    dMinimize  has minimize button:  (default: 1).
+\&    dResize    has resize grips:     (default: 1).
+\&    dRollup    has shade button:     (default: 1).
+\&    dSysMenu   has window menu:      (default: 1).
+\&    dTitleBar  has title bar:        (default: 1).
+.Ve
+.SS "FEATURE OPTION ARGUMENTS"
+.IX Subsection "FEATURE OPTION ARGUMENTS"
+Specifies which advanced features to be enabled/disabled (1/0) for
+windows with \fICLASS\fR\fB.\fR\fIINSTANCE\fR.  All advanced features have a
+default value of disabled (0) unless overridden by the application.  The
+advanced features are as follows:
+.PP
+.Vb 10
+\&    allWorkspaces             on all workspaces.
+\&    appTakesFocus             let application take focus.
+\&    doNotCover                limits workspace if sticky.
+\&    doNotFocus                do not focus.
+\&    doNotManage               do not manage.
+\&    forcedClose               no close dialog.
+\&    fullKeys                  provided more keys.
+\&    ignoreNoFocusHint         focus even no\-input.
+\&    ignorePagerPreview        do not show in pager preview.
+\&    ignorePositionHint        place automatically.
+\&    ignoreQuickSwitch         not on quick switch.
+\&    ignoreTaskBar             not on task bar.
+\&    ignoreUrgentHint          ignore urgent hints.
+\&    ignoreWinList             not on window list.
+\&    ignoreActivationMessages  only user can focus window.
+\&    ignoreOverrideRedirect    ignore the override redirect flag.
+\&    noFocusOnAppRaise         no focus on raise.
+\&    noFocusOnMap              do not focus when mapped.
+\&    noIgnoreTaskBar           on task bar.
+\&    startClose                close the window immediately.
+\&    startFullscreen           start full screen.
+\&    startMaximized            start maximized.
+\&    startMaximizedHorz        start maximized horizontal.
+\&    startMaximizedVert        start maximized vertical.
+\&    startMinimized            start minimized.
+.Ve
+.SS EXAMPLE
+.IX Subsection "EXAMPLE"
+.Vb 2
+\&    # Here is how to preload an invisible background process of chromium
+\&    # on the fourth workspace which is only visible on the Window List.
+\&
+\&    icewmhint Chromium\-browser startMinimized 1 \e
+\&              Chromium\-browser workspace 3 \e
+\&              Chromium\-browser ignorePagerPreview 1 \e
+\&              Chromium\-browser ignorePositionHint 1 \e
+\&              Chromium\-browser ignoreTaskBar 1 \e
+\&              Chromium\-browser ignoreQuickSwitch 1 \e
+\&              Chromium\-browser ignoreUrgentHint 1 \e
+\&              Chromium\-browser noFocusOnAppRaise 1
+\&    chromium
+.Ve
+.SS BUGS
+.IX Subsection "BUGS"
+Please report bugs at <https://github.com/bbidulock/icewm/issues>.
+.SS AUTHOR
+.IX Subsection "AUTHOR"
+Brian Bidulock <mailto:bidulock@openss7.org>.
+.PP
+See \fB\-\-copying\fR for full copyright notice and copying permissions.
+.SS LICENSE
+.IX Subsection "LICENSE"
+\&\fBIceWM\fR is licensed under the GNU Library General Public License.
+See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
+to display copying permissions.
diff --git a/upstream/mageia-cauldron/man1/icontopbm.1 b/upstream/mageia-cauldron/man1/icontopbm.1
new file mode 100644
index 00000000..419f86cc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/icontopbm.1
@@ -0,0 +1,48 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Icontopbm User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+
+icontopbm - replaced by sunicontopnm
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBicontopbm\fP
+[\fIiconfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBicontopbm\fP was obsoleted by
+.BR "\fBsunicontopnm\fP" (1)\c
+\&, introduced with Netpbm 10.53
+(December 2010).  \fBsunicontopnm\fP is backward compatible with
+\fBicontopbm\fP, plus adds additional functions, including the
+ability to convert a Depth=8 Sun icon, producing a PGM image.
+.PP
+Starting in Release 10.53, \fBicontopbm\fP is just an alias for
+\fBsunicontopnm\fP.
+.PP
+The point of the name change is that there are many kinds of icons in the
+world besides Sun icons, and in 2010, the Sun variety isn't even common.
+.PP
+In releases before 10.53, you can use the \fBsunicontopnm\fP documentation
+for \fBicontopbm\fP, as long as you recognize that any change the
+\fBsunicontopnm\fP manual says happened in or after Netpbm 10.53 doesn't
+apply to \fBicontopbm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/icontopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/id.1 b/upstream/mageia-cauldron/man1/id.1
new file mode 100644
index 00000000..54dd8bd4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/id.1
@@ -0,0 +1,62 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH ID "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+id \- print real and effective user and group IDs
+.SH SYNOPSIS
+.B id
+[\fI\,OPTION\/\fR]... [\fI\,USER\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print user and group information for each specified USER,
+or (when USER omitted) for the current process.
+.TP
+\fB\-a\fR
+ignore, for compatibility with other versions
+.TP
+\fB\-Z\fR, \fB\-\-context\fR
+print only the security context of the process
+.TP
+\fB\-g\fR, \fB\-\-group\fR
+print only the effective group ID
+.TP
+\fB\-G\fR, \fB\-\-groups\fR
+print all group IDs
+.TP
+\fB\-n\fR, \fB\-\-name\fR
+print a name instead of a number, for \fB\-ugG\fR
+.TP
+\fB\-r\fR, \fB\-\-real\fR
+print the real ID instead of the effective ID, with \fB\-ugG\fR
+.TP
+\fB\-u\fR, \fB\-\-user\fR
+print only the effective user ID
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+delimit entries with NUL characters, not whitespace;
+.IP
+not permitted in default format
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Without any OPTION, print some useful set of identified information.
+.SH AUTHOR
+Written by Arnold Robbins and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/id>
+.br
+or available locally via: info \(aq(coreutils) id invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/ident.1 b/upstream/mageia-cauldron/man1/ident.1
new file mode 100644
index 00000000..bb1aa53b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ident.1
@@ -0,0 +1,224 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.ds iD 5.4 1993/11/09 17:40:15 eggert Exp
+.if n .ds - \%--
+.if t .ds - \(em
+.TH IDENT 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+ident \- identify RCS keyword strings in files
+.SH SYNOPSIS
+.B ident
+[
+.B \-q
+] [
+.B \-V
+] [
+.I file
+\&.\|.\|. ]
+.SH DESCRIPTION
+.B ident
+searches for all instances of the pattern
+.BI $ keyword : "\ text\ " $
+in the named files or, if no files are named, the standard input.
+.PP
+These patterns are normally inserted automatically by the \*r command
+.BR co (1),
+but can also be inserted manually.
+The option
+.B \-q
+suppresses
+the warning given if there are no patterns in a file.
+The option
+.B \-V
+prints \*r's version number.
+.PP
+.B ident
+works on text files as well as object files and dumps.
+For example, if the C program in
+.B f.c
+contains
+.IP
+.ft 3
+#include <stdio.h>
+.br
+static char const rcsid[] =
+.br
+  \&"$\&Id: f.c,v \*(iD $\&";
+.br
+int main() { return printf(\&"%s\en\&", rcsid) == EOF; }
+.ft P
+.LP
+and
+.B f.c
+is compiled into
+.BR f.o ,
+then the command
+.IP
+.B "ident  f.c  f.o"
+.LP
+will output
+.nf
+.IP
+.ft 3
+f.c:
+    $\&Id: f.c,v \*(iD $
+f.o:
+    $\&Id: f.c,v \*(iD $
+.ft
+.fi
+.PP
+If a C program defines a string like
+.B rcsid
+above but does not use it,
+.BR lint (1)
+may complain, and some C compilers will optimize away the string.
+The most reliable solution is to have the program use the
+.B rcsid
+string, as shown in the example above.
+.PP
+.B ident
+finds all instances of the
+.BI $ keyword : "\ text\ " $
+pattern, even if
+.I keyword
+is not actually an \*r-supported keyword.
+This gives you information about nonstandard keywords like
+.BR $\&XConsortium$ .
+.PP
+The pattern normally requires a colon and a space immediately
+after the keyword and a space immediately before the terminating
+.BR $ ,
+but for Subversion 1.2 (and later) compatibility,
+.B ident
+will also recognize the pattern
+.BI $ keyword :: "\ text\ " $
+(i.e., two colons and a space)
+and the pattern
+.BI $ keyword :: "\ text\ #" $
+(likewise, with a hash before the terminating
+.BR $ ).
+These are the fixed-width keyword syntax.
+To summarize, the three recognized patterns are:
+.IP
+.BI $ keyword : "\ text\ " $
+.br
+.BI $ keyword :: "\ text\ " $
+.br
+.BI $ keyword :: "\ text\ #" $
+.br
+.SH KEYWORDS
+Here is the list of keywords currently maintained by
+.BR co (1).
+All times are given in Coordinated Universal Time (\*u,
+sometimes called \&\s-1GMT\s0) by default, but if the files
+were checked out with
+.BR co 's
+.BI \-z zone
+option, times are given with a numeric time zone indication appended.
+.TP
+.B $\&Author$
+The login name of the user who checked in the revision.
+.TP
+.B $\&Date$
+The date and time the revision was checked in.
+.TP
+.B $\&Header$
+A standard header containing the full \*o name, the
+revision number, the date and time, the author, the state,
+and the locker (if locked).
+.TP
+.B $\&Id$
+Same as
+.BR $\&Header$ ,
+except that the \*o name is without directory components.
+.TP
+.B $\&Locker$
+The login name of the user who locked the revision (empty if not locked).
+.TP
+.B $\&Log$
+The log message supplied during checkin.
+For
+.BR ident 's
+purposes, this is equivalent to
+.BR $\&RCSfile$ .
+.TP
+.B $\&Name$
+The symbolic name used to check out the revision, if any.
+.TP
+.B $\&RCSfile$
+The \*o name without directory components.
+.TP
+.B $\&Revision$
+The revision number assigned to the revision.
+.TP
+.B $\&Source$
+The full \*o name.
+.TP
+.B $\&State$
+The state assigned to the revision with the
+.B \-s
+option of
+.BR rcs (1)
+or
+.BR ci (1).
+.PP
+.BR co (1)
+represents the following characters in keyword values by escape sequences
+to keep keyword strings well-formed.
+.LP
+.RS
+.nf
+.ne 6
+.ta \w'newline  'u
+\f2char	escape sequence\fP
+tab	\f3\et\fP
+newline	\f3\en\fP
+space	\f3\e040
+$	\e044
+\e	\e\e\fP
+.fi
+.RE
+.ds EY 1990, 1992, 1993
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR co (1),
+.BR rcs (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rlog (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
diff --git a/upstream/mageia-cauldron/man1/ifnames.1 b/upstream/mageia-cauldron/man1/ifnames.1
new file mode 100644
index 00000000..21d7ed49
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ifnames.1
@@ -0,0 +1,55 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH IFNAMES "1" "December 2023" "GNU Autoconf 2.72" "User Commands"
+.SH NAME
+ifnames \- Extract CPP conditionals from a set of files
+.SH SYNOPSIS
+.B ifnames
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+Scan all of the C source FILES (or the standard input, if none are
+given) and write to the standard output a sorted list of all the
+identifiers that appear in those files in '#if', '#elif', '#ifdef', or
+\&'#ifndef' directives.  Print each identifier on a line, followed by a
+space\-separated list of the files in which that identifier occurs.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this help, then exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number, then exit
+.SH AUTHOR
+Written by David J. MacKenzie and Paul Eggert.
+.SH "REPORTING BUGS"
+Report bugs to
+.MT bug-autoconf@gnu.org
+.ME ,
+or via Savannah:
+.UR https://savannah.gnu.org/support/?group=autoconf
+.UE .
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+/Autoconf: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR autoconf (1),
+.BR automake (1),
+.BR autoreconf (1),
+.BR autoupdate (1),
+.BR autoheader (1),
+.BR autoscan (1),
+.BR config.guess (1),
+.BR config.sub (1),
+.BR ifnames (1),
+.BR libtool (1).
+
+The full documentation for Autoconf is maintained as a Texinfo manual.
+To read the manual locally, use the command
+.IP
+.B info autoconf
+.PP
+You can also consult the Web version of the manual at
+.UR https://gnu.org/software/autoconf/manual/
+.UE .
diff --git a/upstream/mageia-cauldron/man1/ilbmtoppm.1 b/upstream/mageia-cauldron/man1/ilbmtoppm.1
new file mode 100644
index 00000000..ac8d4f83
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ilbmtoppm.1
@@ -0,0 +1,160 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ilbmtoppm User Manual" 0 "12 November 2014" "netpbm documentation"
+
+.SH NAME
+ilbmtoppm - convert an ILBM file into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBilbmtoppm\fP
+[\fB-ignore\fP<chunkID>\fB]\fP
+[
+\fB-isham\fP | \fB-isnotham\fP |
+\fB-isehb\fP | \fB-isnotehb\fP |
+\fB-isdeep\fP | \fB-isnotdeep\fP
+]
+[\fB-cmaponly\fP]
+[\fB-adjustcolors\fP]
+[\fB-transparent \fP\fIcolor\fP]
+[\fB-maskfile\fP \fIfilename\fP
+[\fB-verbose\fP]
+[\fIILBMfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBilbmtoppm\fP reads an IFF ILBM file as input and produces a PPM
+image as output.  \fBilbmtoppm\fP can handle the following ILBM types:
+
+
+.IP \(bu
+Normal ILBMs with 1-16 planes.
+.IP \(bu
+Amiga Extra_Halfbrite (EHB)
+.IP \(bu
+Amiga HAM with 3-16 planes.
+.IP \(bu
+24 bit.
+.IP \(bu
+Multiplatte (normal or HAM) pictures.
+.IP \(bu
+Color map (BMHD + CMAP chunk only, nPlanes = 0).
+.IP \(bu
+Unofficial direct color.  1-16 planes for each color component.
+
+.PP
+\fBilbmtoppm\fP uses these ILBM chunks: BMHD, CMAP, CAMG (only HAM
+& EHB flags used), PCHG, BODY unofficial DCOL chunk to identify
+direct color ILBM.  It ignores these chunks: GRAB, DEST, SPRT, CRNG,
+CCRT, CLUT, DPPV, DRNG, EPSF.  It ignores, but displays in verbose
+mode, these: NAME, AUTH, (c), ANNO, DPI.  It skips chunks whose type
+it doesn't recognize.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBilbmtoppm\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-transparent \fP\fIcolor\fP
+This is the color that should "show through" in places where
+the image is transparent.
+.sp
+\fIcolor\fP is like the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+.TP
+\fB-verbose\fP
+Give some information about the ILBM file.
+
+.TP
+\fB-ignore\fP \fIchunkID\fP
+Skip a chunk.  \fIchunkID\fP is the 4-letter IFF chunk identifier
+of the chunk to be skipped.
+
+.TP
+\fB-isham\fP | \fB-isehb\fP
+Treat the input file as a HAM or Extra_Halfbrite picture, even if
+these flags are not set in the CAMG chunk (or if there is no CAMG
+chunk).
+
+.TP
+\fB-maskfile\fP \fIfilename\fP
+This names a file for \fBilbmtoppm\fP to create with the image's
+transparency mask.  The mask file is a PBM image which maps to the input image
+with white pixels representing transparent pixels in the image and black
+pixels representing opaque pixels.
+.sp
+If you don't specfy this, or the image does not contain transparency
+information, \fBilbmtoppm\fP does not create a mask file.
+
+.TP
+\fB-cmaponly\fP
+With this option, \fBilbmtoppm\fP generates a PPM of the ILBM's \fIcolor
+map\fP, not the image itself.
+.sp
+\fBilbmtoppm\fP does the same thing even without \fB-cmaponly\fP if the
+ILBM is a pure color map stream (it has a bitmap header with an \fInplanes\fP
+value of zero or has no BODY chunk.
+
+.TP
+\fB-adjustcolors\fP
+If all colors in the CMAP have a value of less then 16, ilbmtoppm
+assumes a 4-bit colormap and gives a warning.  With this option the
+colormap is scaled to 8 bits.
+
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The multipalette PCHG BigLineChanges and Huffman decompression code
+is untested.
+
+.UN references
+.SH REFERENCES
+
+Amiga ROM Kernel Reference Manual - Devices (3rd Ed.)
+Addison Wesley, ISBN 0-201-56775-X
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoilbm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Modified October 1993 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ilbmtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/imgtoppm.1 b/upstream/mageia-cauldron/man1/imgtoppm.1
new file mode 100644
index 00000000..92d0d280
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/imgtoppm.1
@@ -0,0 +1,55 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Imgtoppm User Manual" 0 "05 September 1989" "netpbm documentation"
+
+.SH NAME
+imgtoppm - convert an Img-whatnot file into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBimgtoppm\fP
+[\fIimgfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBimgtoppm\fPreads an Img-whatnot file as input and produces a
+PPM image as output.  The Img-whatnot toolkit is available for FTP on
+venera.isi.edu, along with numerous images in this format.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBimgtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Based on a simple conversion program posted to comp.graphics by Ed Falk.
+.PP
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/imgtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/includeres.1 b/upstream/mageia-cauldron/man1/includeres.1
new file mode 100644
index 00000000..2c8031cf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/includeres.1
@@ -0,0 +1,65 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH INCLUDERES "1" "October 2021" "includeres 2.07" "User Commands"
+.SH NAME
+includeres - include resources in a PostScript document
+.SH SYNOPSIS
+.B includeres
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Include resources in a PostScript document.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+.B Includeres
+includes resources (fonts, procsets, patterns, files, etc.) in place of
+.B %%IncludeResource
+comments in a PostScript document.
+The resources are searched for under the resource name, and with an
+appropriate extension.
+The pipeline
+.sp
+.RS
+extractres file.ps | includeres >out.ps
+.RE
+.sp
+will move all resources appearing in a document to the document prologue,
+removing redundant copies.
+The output file can then be put through page re-arrangement filters such as
+.B psnup
+or 
+.B pstops
+safely.
+
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH BUGS
+.B includeres
+does not alter the
+.B %%DocumentNeededResources
+comments.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2012\-2019.
+.br
+Copyright \(co Angus J. C. Duggan 1991\-1997.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/indent.1 b/upstream/mageia-cauldron/man1/indent.1
new file mode 100644
index 00000000..c5307b67
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/indent.1
@@ -0,0 +1,2185 @@
+.TH INDENT 1
+.SH "NAME"
+indent \- changes the appearance of a C program by inserting or deleting whitespace.  
+.SH "SYNOPSIS"
+.B "indent "
+[options] [input\-files]
+.sp
+.B "indent "
+[options] [single\-input\-file] [\-o output\-file]
+.sp
+.B "indent "
+\-\-version
+.SH "DESCRIPTION"
+This man page is generated from the file \fIindent.texinfo\fR.
+This is Edition  of "The \fBindent\fR Manual",
+for Indent Version , last updated .
+
+The \fBindent\fR program
+can be used to make code easier to read.  It can also convert from one
+style of writing C to another.  
+
+.B indent\fR understands a substantial amount about the syntax of C,
+but it also attempts to cope with incomplete and misformed syntax.
+
+In version 1.2 and more recent versions, the GNU style of indenting is
+the default.
+.SH "OPTIONS"
+
+.TP 4
+.B -as\fR, \fB--align-with-spaces\fR
+If using tabs for indentation, use spaces for alignment.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -bad\fR, \fB--blank-lines-after-declarations\fR
+Force blank lines after the declarations.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -bap\fR, \fB--blank-lines-after-procedures\fR
+Force blank lines after procedure bodies.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -bbb\fR, \fB--blank-lines-before-block-comments\fR
+Force blank lines before block comments.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -bbo\fR, \fB--break-before-boolean-operator\fR
+Prefer to break long lines before boolean operators.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -bc\fR, \fB--blank-lines-after-commas\fR
+Force newline after comma in declaration.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -bl\fR, \fB--braces-after-if-line\fR
+Put braces on line after \fBif\fR, etc.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -blf\fR, \fB--braces-after-func-def-line\fR
+Put braces on line following function definition line.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -bli\fIn\fB\fR, \fB--brace-indent\fIn\fB\fR
+Indent braces \fIn\fR spaces.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -bls\fR, \fB--braces-after-struct-decl-line\fR
+Put braces on the line after \fBstruct\fR declaration lines.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -br\fR, \fB--braces-on-if-line\fR
+Put braces on line with \fBif\fR, etc.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -brf\fR, \fB--braces-on-func-def-line\fR
+Put braces on function definition line.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -brs\fR, \fB--braces-on-struct-decl-line\fR
+Put braces on \fBstruct\fR declaration line.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -bs\fR, \fB--Bill-Shannon\fR, \fB--blank-before-sizeof\fR
+Put a space between \fBsizeof\fR and its argument.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -c\fIn\fB\fR, \fB--comment-indentation\fIn\fB\fR
+Put comments to the right of code in column \fIn\fR.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -cbi\fIn\fB\fR, \fB--case-brace-indentation\fIn\fB\fR
+Indent braces after a case label N spaces.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -cd\fIn\fB\fR, \fB--declaration-comment-column\fIn\fB\fR
+Put comments to the right of the declarations in column \fIn\fR.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -cdb\fR, \fB--comment-delimiters-on-blank-lines\fR
+Put comment delimiters on blank lines.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -cdw\fR, \fB--cuddle-do-while\fR
+Cuddle while of \fBdo {} while;\fR and preceding \(oq}\(cq.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -ce\fR, \fB--cuddle-else\fR
+Cuddle else and preceding \(oq}\(cq.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -ci\fIn\fB\fR, \fB--continuation-indentation\fIn\fB\fR
+Continuation indent of \fIn\fR spaces.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -cli\fIn\fB\fR, \fB--case-indentation\fIn\fB\fR
+Case label indent of \fIn\fR spaces.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -cp\fIn\fB\fR, \fB--else-endif-column\fIn\fB\fR
+Put comments to the right of \fB#else\fR and \fB
+#endif\fR statements in column \fIn\fR.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -cs\fR, \fB--space-after-cast\fR
+Put a space after a cast operator.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -d\fIn\fB\fR, \fB--line-comments-indentation\fIn\fB\fR
+Set indentation of comments not to the right 
+of code to \fIn\fR spaces.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -bfda\fR, \fB--break-function-decl-args\fR
+Break the line before all arguments in a declaration.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -bfde\fR, \fB--break-function-decl-args-end\fR
+Break the line after the last argument in a declaration.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -dj\fR, \fB--left-justify-declarations\fR
+If -cd 0 is used then comments after declarations are left justified
+behind the declaration.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -di\fIn\fB\fR, \fB--declaration-indentation\fIn\fB\fR
+Put variables in column \fIn\fR.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -fc1\fR, \fB--format-first-column-comments\fR
+Format comments in the first column.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -fca\fR, \fB--format-all-comments\fR
+Do not disable all formatting of comments.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -fnc\fR, \fB--fix-nested-comments\fR
+Fix nested comments.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -gnu\fR, \fB--gnu-style\fR
+Use GNU coding style.  This is the default.
+.br
+See \fB\ COMMON\ STYLES\fR.
+.TP
+.B -gts\fR, \fB--gettext-strings\fR
+Treat gettext \fB_("...")\fR and \fBN_("...")\fR as strings rather than as functions.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -hnl\fR, \fB--honour-newlines\fR
+Prefer to break long lines at the position of newlines in the input.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -i\fIn\fB\fR, \fB--indent-level\fIn\fB\fR
+Set indentation level to \fIn\fR spaces.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -il\fIn\fB\fR, \fB--indent-label\fIn\fB\fR
+Set offset for labels to column \fIn\fR.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -ip\fIn\fB\fR, \fB--parameter-indentation\fIn\fB\fR
+Indent parameter types in old-style function 
+definitions by \fIn\fR spaces.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -kr\fR, \fB--k-and-r-style\fR
+Use Kernighan & Ritchie coding style.
+.br
+See \fB\ COMMON\ STYLES\fR.
+.TP
+.B -l\fIn\fB\fR, \fB--line-length\fIn\fB\fR
+Set maximum line length for non-comment lines to \fIn\fR.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -lc\fIn\fB\fR, \fB--comment-line-length\fIn\fB\fR
+Set maximum line length for comment formatting to \fIn\fR.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -linux\fR, \fB--linux-style\fR
+Use Linux coding style.
+.br
+See \fB\ COMMON\ STYLES\fR.
+.TP
+.B -lp\fR, \fB--continue-at-parentheses\fR
+Line up continued lines at parentheses.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -lps\fR, \fB--leave-preprocessor-space\fR
+Leave space between \(oq#\(cq and preprocessor directive.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -nlps\fR, \fB--remove-preprocessor-space\fR
+Remove space between \(oq#\(cq and preprocessor directive.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -nbad\fR, \fB--no-blank-lines-after-declarations\fR
+Do not force blank lines after declarations.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -nbap\fR, \fB--no-blank-lines-after-procedures\fR
+Do not force blank lines after procedure bodies.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -nbbo\fR, \fB--break-after-boolean-operator\fR
+Do not prefer to break long lines before boolean operators.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -nbc\fR, \fB--no-blank-lines-after-commas\fR
+Do not force newlines after commas in declarations.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -nbfda\fR, \fB--dont-break-function-decl-args\fR
+Don\(cqt put each argument in a function declaration on a separate line.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -ncdb\fR, \fB--no-comment-delimiters-on-blank-lines\fR
+Do not put comment delimiters on blank lines.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -ncdw\fR, \fB--dont-cuddle-do-while\fR
+Do not cuddle \fB}\fR and the \fBwhile\fR of a \fBdo {} while;\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -nce\fR, \fB--dont-cuddle-else\fR
+Do not cuddle \fB}\fR and \fBelse\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -ncs\fR, \fB--no-space-after-casts\fR
+Do not put a space after cast operators.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -ndj\fIn\fB\fR, \fB--dont-left-justify-declarations\fR
+Comments after declarations are treated the same as 
+comments after other statements.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -nfc1\fR, \fB--dont-format-first-column-comments\fR
+Do not format comments in the first column as normal.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -nfca\fR, \fB--dont-format-comments\fR
+Do not format any comments.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -ngts\fR, \fB--no-gettext-strings\fR
+Treat gettext \fB_("...")\fR and \fBN_("...")\fR as normal functions.  This is the default.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -nhnl\fR, \fB--ignore-newlines\fR
+Do not prefer to break long lines at the position of newlines in the input.
+.br
+See \fB\ BREAKING\ LONG\ LINES\fR.
+.TP
+.B -nip\fR, \fB--no-parameter-indentation\fR
+Zero width indentation for parameters.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -nlp\fR, \fB--dont-line-up-parentheses\fR
+Do not line up parentheses.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -npcs\fR, \fB--no-space-after-function-call-names\fR
+Do not put space after the function in function calls.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -nprs\fR, \fB--no-space-after-parentheses\fR
+Do not put a space after every \(cq(\(cq and before every \(cq)\(cq.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -npsl\fR, \fB--dont-break-procedure-type\fR
+Put the type of a procedure on the same line as its name.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -nsaf\fR, \fB--no-space-after-for\fR
+Do not put a space after every \fBfor\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -nsai\fR, \fB--no-space-after-if\fR
+Do not put a space after every \fBif\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -nsaw\fR, \fB--no-space-after-while\fR
+Do not put a space after every \fBwhile\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -nsc\fR, \fB--dont-star-comments\fR
+Do not put the \(oq*\(cq character at the left of comments.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -nsob\fR, \fB--leave-optional-blank-lines\fR
+Do not swallow optional blank lines.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -nss\fR, \fB--dont-space-special-semicolon\fR
+Do not force a space before the semicolon after certain statements.
+Disables \(oq-ss\(cq.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -ntac\fR, \fB--dont-tab-align-comments\fR
+Do not pad comments out to the nearest tabstop.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -nut\fR, \fB--no-tabs\fR
+Use spaces instead of tabs.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -nv\fR, \fB--no-verbosity\fR
+Disable verbose mode.
+.br
+See \fB\ MISCELLANEOUS\ OPTIONS\fR.
+.TP
+.B -orig\fR, \fB--original\fR
+Use the original Berkeley coding style.
+.br
+See \fB\ COMMON\ STYLES\fR.
+.TP
+.B -npro\fR, \fB--ignore-profile\fR
+Do not read \(oq.indent.pro\(cq files.
+.br
+See \fB\ INVOKING\ INDENT\fR.
+.TP
+.B -pal\fR, \fB--pointer-align-left\fR
+Put asterisks in pointer declarations on the left of spaces, next to
+types: \(oq\(oqchar* p\(cq\(cq.
+.TP
+.B -par\fR, \fB--pointer-align-right\fR
+Put asterisks in pointer declarations on the right of spaces, next to
+variable names: \(oq\(oqchar *p\(cq\(cq. This is the default behavior.
+.TP
+.B -pcs\fR, \fB--space-after-procedure-calls\fR
+Insert a space between the name of the 
+procedure being called and the \(oq(\(cq.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -pi\fIn\fB\fR, \fB--paren-indentation\fIn\fB\fR
+Specify the extra indentation per open parentheses \(cq(\(cq when a
+statement is broken.See \fB\ STATEMENTS\fR.
+.TP
+.B -pmt\fR, \fB--preserve-mtime\fR
+Preserve access and modification times on output files.See \fB\ MISCELLANEOUS\ OPTIONS\fR.
+.TP
+.B -ppi\fIn\fB\fR, \fB--preprocessor-indentation\fIn\fB\fR
+Specify the indentation for preprocessor conditional statements.See \fB\ INDENTATION\fR.
+.TP
+.B -prs\fR, \fB--space-after-parentheses\fR
+Put a space after every \(cq(\(cq and before every \(cq)\(cq.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -psl\fR, \fB--procnames-start-lines\fR
+Put the type of a procedure on the line before its name.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -saf\fR, \fB--space-after-for\fR
+Put a space after each \fBfor\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -sai\fR, \fB--space-after-if\fR
+Put a space after each \fBif\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -sar\fR, \fB--spaces-around-initializers\fR
+Put a space after the \(oq{\(cq and before the \(oq}\(cq in initializers.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -saw\fR, \fB--space-after-while\fR
+Put a space after each \fBwhile\fR.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -sbi\fIn\fB\fR, \fB--struct-brace-indentation\fIn\fB\fR
+Indent braces of a struct, union or enum N spaces.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -sc\fR, \fB--start-left-side-of-comments\fR
+Put the \(oq*\(cq character at the left of comments.
+.br
+See \fB\ COMMENTS\fR.
+.TP
+.B -slc\fR, \fB--single-line-conditionals\fR
+Allow for unbraced conditionals (\fBif\fR, \fBelse\fR, etc.) to have
+their inner statement on the same line.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -sob\fR, \fB--swallow-optional-blank-lines\fR
+Swallow optional blank lines.
+.br
+See \fB\ BLANK\ LINES\fR.
+.TP
+.B -ss\fR, \fB--space-special-semicolon\fR
+On one-line \fBfor\fR and \fBwhile\fR statements, 
+force a blank before the semicolon.
+.br
+See \fB\ STATEMENTS\fR.
+.TP
+.B -st\fR, \fB--standard-output\fR
+Write to standard output.
+.br
+See \fB\ INVOKING\ INDENT\fR.
+.TP
+.B -T\fR
+Tell \fBindent\fR the name of typenames.
+.br
+See \fB\ DECLARATIONS\fR.
+.TP
+.B -ts\fIn\fB\fR, \fB--tab-size\fIn\fB\fR
+Set tab size to \fIn\fR spaces.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -ut\fR, \fB--use-tabs\fR
+Use tabs. This is the default.
+.br
+See \fB\ INDENTATION\fR.
+.TP
+.B -v\fR, \fB--verbose\fR
+Enable verbose mode.
+.br
+See \fB\ MISCELLANEOUS\ OPTIONS\fR.
+.TP
+.B -version\fR
+Output the version number of \fBindent\fR.
+.br
+See \fB\ MISCELLANEOUS\ OPTIONS\fR.
+
+.SH "INVOKING INDENT"
+
+As of version 1.3, the format of the \fBindent\fR command is:
+
+.in +5
+.nf
+.na
+
+indent [\fIoptions\fR] [\fIinput-files\fR]
+
+indent [\fIoptions\fR] [\fIsingle-input-file\fR] [-o \fIoutput-file\fR]
+
+.in -5
+.ad
+.fi
+
+This format is different from earlier versions and other versions of
+.B indent\fR.
+
+In the first form, one or more input files are specified.  \fBindent\fR
+makes a backup copy of each file, and the original file is replaced with
+its indented version.  See \fBBACKUP\ FILES\fR, for an explanation of how
+backups are made.
+
+In the second form, only one input file is specified.  In this case, or
+when the standard input is used, you may specify an output file after
+the \(oq-o\(cq option.
+
+To cause \fBindent\fR to write to standard output, use the \(oq-st\(cq
+option.  This is only allowed when there is only one input file, or when
+the standard input is used.
+
+If no input files are named, the standard input is read for input.
+Also, if a filename named \(oq-\(cq is specified, then the standard input
+is read.
+
+As an example, each of the following commands will input the program
+\(oqslithy_toves.c\(cq and write its indented text to
+\(oqslithy_toves.out\(cq:
+
+.in +5
+.nf
+.na
+
+indent slithy_toves.c -o slithy_toves.out
+
+indent -st slithy_toves.c > slithy_toves.out
+
+cat slithy_toves.c | indent -o slithy_toves.out
+
+.in -5
+.ad
+.fi
+
+Most other options to \fBindent\fR control how programs are formatted.
+As of version 1.2, \fBindent\fR also recognizes a long name for each
+option name.  Long options are prefixed by either \(oq--\(cq or
+\(oq+\(cq.
+[ \(oq+\(cq is being superseded by \(oq--\(cq to
+maintain consistency with the POSIX standard.]
+ In most of this document,
+the traditional, short names are used for the sake of brevity.
+See \fBOPTION\ SUMMARY\fR, for a list of options, including both long and
+short names.
+
+Here is another example:
+
+.in +5
+.nf
+.na
+indent -br test/metabolism.c -l85
+.in -5
+.ad
+.fi
+
+This will indent the program \(oqtest/metabolism.c\(cq using the
+\(oq-br\(cq and \(oq-l85\(cq options, write the output back to
+\(oqtest/metabolism.c\(cq, and write the original contents of
+\(oqtest/metabolism.c\(cq to a backup file in the directory \(oqtest\(cq.
+
+Equivalent invocations using long option names for this example would
+be:
+
+.in +5
+.nf
+.na
+
+indent --braces-on-if-line --line-length185 test/metabolism.c
+
+indent +braces-on-if-line +line-length185 test/metabolism.c
+
+.in -5
+.ad
+.fi
+
+If you find that you often use \fBindent\fR with the same options, you
+may put those options into a file named \(oq.indent.pro\(cq.
+.B indent\fR will look for a profile file in three places. First it will check
+the environment variable \fBINDENT_PROFILE\fR. If that exists its value 
+is expected to name the file that is to be used. If the environment variable does 
+not exist, indent looks for \(oq.indent.pro\(cq in the current directory
+ and use that if found.  Finally \fBindent\fR will search
+your home directory for \(oq.indent.pro\(cq and use that file if it is
+found.  This behaviour is different from that of other versions of
+.B indent\fR, which load both files if they both exist.
+
+The format of \(oq.indent.pro\(cq is simply a list of options, just as
+they would appear on the command line, separated by white space (tabs,
+spaces, and newlines).  Options in \(oq.indent.pro\(cq may be surrounded by C
+or C++ comments, in which case they are ignored.
+
+Command line switches are handled \fIafter\fR processing
+\(oq .indent.pro\(cq.  Options specified later override arguments
+specified earlier, with one exception: Explicitly specified options
+always override background options (See \fBCOMMON\ STYLES\fR).  You can
+prevent \fBindent\fR from reading an \(oq.indent.pro\(cq file by
+specifying the \(oq-npro\(cq option.
+
+.SH "BACKUP FILES"
+
+As of version 1.3, GNU \fBindent\fR makes GNU-style backup files, the
+same way GNU Emacs does.  This means that either \fIsimple\fR or
+.I numbered\fR backup filenames may be made.
+
+Simple backup file names are generated by appending a suffix to the
+original file name.  The default for this suffix is the
+one-character string \(oq~\(cq (tilde).  Thus, the backup file for
+\(oqpython.c\(cq would be \(oqpython.c~\(cq.
+
+Instead of the default, you may specify any string as a suffix by
+setting the environment variable \fBSIMPLE_BACKUP_SUFFIX\fR to
+your preferred suffix.
+
+Numbered backup versions of a file \(oqmomeraths.c\(cq look like
+\(oqmomeraths.c.~23~\(cq, where 23 is the version of this particular
+backup.  When making a numbered backup of the file \(oqsrc/momeraths.c\(cq,
+the backup file will be named \(oqsrc/momeraths.c.~\fIV\fR~\(cq, where
+.I V\fR is one greater than the highest version currently existing in
+the directory \(oqsrc\(cq.  The environment variable \fBVERSION_WIDTH\fR
+controls the number of digits, using left zero padding when necessary.
+For instance, setting this variable to "2" will lead to the backup
+file being named \(oqmomeraths.c.~04~\(cq.
+
+The type of backup file made is controlled by the value of the
+environment variable \fBVERSION_CONTROL\fR.  If it is the string
+\(oqsimple\(cq, then only simple backups will be made.  If its value is
+the string \(oqnumbered\(cq, then numbered backups will be made.  If its
+value is \(oqnumbered-existing\(cq, then numbered backups will be made if
+there \fIalready exist\fR numbered backups for the file being indented;
+otherwise, a simple backup is made.  If \fBVERSION_CONTROL\fR is not
+set, then \fBindent\fR assumes the behaviour of
+\(oqnumbered-existing\(cq.
+
+Other versions of \fBindent\fR use the suffix \(oq.BAK\(cq in naming
+backup files.  This behaviour can be emulated by setting
+.B SIMPLE_BACKUP_SUFFIX\fR to \(oq.BAK\(cq.
+
+Note also that other versions of \fBindent\fR make backups in the
+current directory, rather than in the directory of the source file as
+GNU \fBindent\fR now does.
+
+.SH "COMMON STYLES"
+
+There are several common styles of C code, including the GNU style, the
+Kernighan & Ritchie style, and the original Berkeley style.  A style may
+be selected with a single \fIbackground\fR option, which specifies a set
+of values for all other options.  However, explicitly specified options
+always override options implied by a background option.
+
+As of version 1.2, the default style of GNU \fBindent\fR is the GNU
+style.  Thus, it is no longer necessary to specify the option
+\(oq-gnu\(cq to obtain this format, although doing so will not cause an
+error.  Option settings which correspond to the GNU style are:
+
+.in +5
+.nf
+.na
+-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -nprs -psl -saf -sai
+-saw -nsc -nsob
+.in -5
+.ad
+.fi
+
+The GNU coding style is that preferred by the GNU project.  It is the
+style that the GNU Emacs C mode encourages and which is used in the C
+portions of GNU Emacs.  (People interested in writing programs for
+Project GNU should get a copy of "The GNU Coding Standards", which
+also covers semantic and portability issues such as memory usage, the
+size of integers, etc.)
+
+The Kernighan & Ritchie style is used throughout their well-known book
+"The C Programming Language".  It is enabled with the \(oq-kr\(cq
+option.  The Kernighan & Ritchie style corresponds to the following set
+of options:
+
+.in +5
+.nf
+.na
+-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0
+-cp33 -cs -d0 -di1 -nfc1 -nfca -hnl -i4 -ip0 -l75 -lp -npcs
+-nprs -npsl -saf -sai -saw -nsc -nsob -nss -par
+.in -5
+.ad
+.fi
+
+Kernighan & Ritchie style does not put comments to the right of code in
+the same column at all times (nor does it use only one space to the
+right of the code), so for this style \fBindent\fR has arbitrarily
+chosen column 33.
+
+The style of the original Berkeley \fBindent\fR may be obtained by
+specifying \(oq-orig\(cq (or by specifying \(oq--original\(cq, using the
+long option name).  This style is equivalent to the following settings:
+
+.in +5
+.nf
+.na
+-nbad -nbap -bbo -bc -br -brs -c33 -cd33 -cdb -ce -ci4 -cli0
+-cp33 -di16 -fc1 -fca -hnl -i4 -ip4 -l75 -lp -npcs -nprs -psl
+-saf -sai -saw -sc -nsob -nss -ts8
+.in -5
+.ad
+.fi
+
+The Linux style is used in the linux kernel code and drivers. Code 
+generally has to follow the Linux coding style to be accepted. 
+This style is equivalent to the following settings:
+
+.in +5
+.nf
+.na
+-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 
+-cli0 -d0 -di1 -nfc1 -i8 -ip0 -l80 -lp -npcs -nprs -npsl -sai
+-saf -saw -ncs -nsc -sob -nfca -cp33 -ss -ts8 -il1
+.in -5
+.ad
+.fi
+
+.SH "BLANK LINES"
+
+Various programming styles use blank lines in different places.
+.B indent\fR has a number of options to insert or delete blank lines in
+specific places.
+
+The \(oq-bad\(cq option causes \fBindent\fR to force a blank line after
+every block of declarations.  The \(oq-nbad\(cq option causes
+.B indent\fR not to force such blank lines.
+
+The \(oq-bap\(cq option forces a blank line after every procedure body.
+The \(oq-nbap\(cq option forces no such blank line.
+
+The \(oq-bbb\(cq option forces a blank line before every boxed comment
+(See \fBCOMMENTS\fR.)
+The \(oq-nbbb\(cq option does not force such blank lines.
+
+The \(oq-sob\(cq option causes \fBindent\fR to swallow optional blank
+lines (that is, any optional blank lines present in the input will be
+removed from the output).  If the \(oq-nsob\(cq is specified, any blank
+lines present in the input file will be copied to the output file.
+
+
+.SH "--blank-lines-after-declarations"
+
+The \(oq-bad\(cq option forces a blank line after every block of
+declarations.  The \(oq-nbad\(cq option does not add any such blank
+lines.
+
+For example, given the input
+.in +5
+.nf
+.na
+char *foo;
+char *bar;
+/* This separates blocks of declarations.  */
+int baz;
+.in -5
+.ad
+.fi
+
+.B indent -bad\fR produces
+
+.in +5
+.nf
+.na
+char *foo;
+char *bar;
+
+/* This separates blocks of declarations.  */
+int baz;
+.in -5
+.ad
+.fi
+
+and \fBindent -nbad\fR produces
+
+.in +5
+.nf
+.na
+char *foo;
+char *bar;
+/* This separates blocks of declarations.  */
+int baz;
+.in -5
+.ad
+.fi
+
+.SH "--blank-lines-after-procedures"
+
+The \(oq-bap\(cq option forces a blank line after every procedure body.
+
+For example, given the input
+
+.in +5
+.nf
+.na
+int
+foo ()
+{
+  puts("Hi");
+}
+/* The procedure bar is even less interesting.  */
+char *
+bar ()
+{
+  puts("Hello");
+}
+.in -5
+.ad
+.fi
+
+.B indent -bap\fR produces
+
+.in +5
+.nf
+.na
+int
+foo ()
+{
+  puts ("Hi");
+}
+
+/* The procedure bar is even less interesting.  */
+char *
+bar ()
+{
+  puts ("Hello");
+}
+.in -5
+.ad
+.fi
+
+and \fBindent -nbap\fR produces
+
+.in +5
+.nf
+.na
+int
+foo ()
+{
+  puts ("Hi");
+}
+/* The procedure bar is even less interesting.  */
+char *
+bar ()
+{
+  puts ("Hello");
+}
+.in -5
+.ad
+.fi
+
+No blank line will be added after the procedure \fBfoo\fR.
+
+.SH "COMMENTS"
+
+.B indent\fR formats both C and C++ comments. C comments are begun with
+\(oq/*\(cq, terminated with \(oq*/\(cq and may contain newline characters.
+C++ comments begin with the delimiter \(oq//\(cq and end at the newline.
+
+.B indent\fR handles comments differently depending upon their context.
+.B indent\fR attempts to distinguish between comments which follow
+statements, comments which follow declarations, comments following
+preprocessor directives, and comments which are not preceded by code of
+any sort, i.e., they begin the text of the line (although not
+necessarily in column 1).
+
+.B indent\fR further distinguishes between comments found outside of
+procedures and aggregates, and those found within them.  In particular,
+comments beginning a line found within a procedure will be indented to
+the column at which code is currently indented.  The exception to this 
+is a comment beginning in the leftmost column;  such a comment is output
+at that column.
+
+.B indent\fR attempts to leave \fIboxed comments\fR unmodified.  The
+general idea of such a comment is that it is enclosed in a rectangle or
+\(oq\(oqbox\(cq\(cq of stars or dashes to visually set it apart.  More precisely,
+boxed comments are defined as those in which the initial \(oq/*\(cq is
+followed immediately by the character \(oq*\(cq, \(oq=\(cq, \(oq_\(cq, or
+\(oq-\(cq, or those in which the beginning comment delimiter (\(oq/*\(cq)
+is on a line by itself, and the following line begins with a \(oq*\(cq in
+the same column as the star of the opening delimiter.
+
+Examples of boxed comments are:
+
+.in +5
+.nf
+.na
+/**********************
+ * Comment in a box!! *
+ **********************/
+
+       /*
+        * A different kind of scent,
+        * for a different kind of comment.
+        */
+.in -5
+.ad
+.fi
+
+.B indent\fR attempts to leave boxed comments exactly as they are found
+in the source file.  Thus the indentation of the comment is unchanged,
+and its length is not checked in any way.  The only alteration made is
+that an embedded tab character may be converted into the appropriate
+number of spaces.
+
+If the \(oq-bbb\(cq option is specified, all such boxed comments will be
+preceded by a blank line, unless such a comment is preceded by code.
+
+Comments which are not boxed comments may be formatted, which means that
+the line is broken to fit within a right margin and left-filled with
+whitespace.  Single newlines are equivalent to a space, but blank lines
+(two or more newlines in a row) are taken to mean a paragraph break.
+Formatting of comments which begin after the first column is enabled
+with the \(oq-fca\(cq option.  To format those beginning in column one,
+specify \(oq-fc1\(cq.  Such formatting is disabled by default.
+
+The right margin for formatting defaults to 78, but may be changed with
+the \(oq-lc\(cq option.  If the margin specified does not allow the
+comment to be printed, the margin will be automatically extended for the
+duration of that comment.  The margin is not respected if the comment is
+not being formatted.
+
+If the \(oq-fnc\(cq option is specified, all comments with \(oq/*\(cq
+embedded will have that character sequence replaced by a space followed
+by the character \(oq*\(cq thus eliminating nesting.
+
+If the comment begins a line (i.e., there is no program text to its
+left), it will be indented to the column it was found in unless the
+comment is within a block of code.  In that case, such a comment will be
+aligned with the indented code of that block (unless the comment began
+in the first column).  This alignment may be affected by the \(oq-d\(cq
+option, which specifies an amount by which such comments are moved to
+the \fIleft\fR, or unindented.  For example, \(oq-d2\(cq places comments
+two spaces to the left of code.  By default, comments are aligned with
+code, unless they begin in the first column, in which case they are left
+there by default --- to get them aligned with the code, specify \(oq-fc1\(cq.
+
+Comments to the right of code will appear by default in column 33.
+This may be changed with one of three options.  \(oq-c\(cq will specify
+the column for comments following code, \(oq-cd\(cq specifies the
+column for comments following declarations, and \(oq-cp\(cq specifies
+the column for comments following preprocessor directives \fB#else\fR
+and \fB#endif\fR. \(oq-dj\(cq together with \(oq-cd0\(cq can be used
+to suppress alignment of comments to the right of declarations, causing the 
+comment to follow one tabstop from the end of the declaration. Normally \(oq-cd0\(cq
+causes \(oq-c\(cq to become effective.
+
+If the code to the left of the comment exceeds the beginning column,
+the comment column will be extended to the next tabstop column past
+the end of the code, unless the \(oq-ntac\(cq option is specified.
+In the case of preprocessor directives,comments are extended to to one
+space past the end of the directive.  This extension lasts only for
+the output of that particular comment.
+
+The \(oq-cdb\(cq option places the comment delimiters on blank lines.
+Thus, a single line comment like \fB/* Loving hug */\fR can be
+transformed into:
+
+.in +5
+.nf
+.na
+/*
+   Loving hug
+ */
+.in -5
+.ad
+.fi
+
+Stars can be placed at the beginning of multi-line comments with the
+\(oq-sc\(cq option.  Thus, the single-line comment above can be
+transformed (with \(oq-cdb -sc\(cq) into:
+
+.in +5
+.nf
+.na
+/*
+ * Loving hug
+ */
+.in -5
+.ad
+.fi
+
+.SH "STATEMENTS"
+
+The \(oq-br\(cq or \(oq-bl\(cq option specifies how to format braces.
+
+The \(oq-br\(cq option formats statement braces like this:
+
+.in +5
+.nf
+.na
+if (x > 0) {
+  x--;
+}
+.in -5
+.ad
+.fi
+
+The \(oq-bl\(cq option formats them like this:
+
+.in +5
+.nf
+.na
+if (x > 0)
+  {
+    x--;
+  }
+.in -5
+.ad
+.fi
+
+If you use the \(oq-bl\(cq option, you may also want to specify the
+\(oq-bli\(cq option.  This option specifies the number of spaces by
+which braces are indented.  \(oq-bli2\(cq, the default, gives the
+result shown above.  \(oq-bli0\(cq results in the following:
+
+.in +5
+.nf
+.na
+if (x > 0)
+{
+  x--;
+}
+.in -5
+.ad
+.fi
+
+If you are using the \(oq-br\(cq option, you probably want to also use
+the \(oq-ce\(cq option.  This causes the \fBelse\fR in an if-then-else
+construct to cuddle up to the immediately preceding \(oq}\(cq.  For
+example, with \(oq-br -ce\(cq you get the following:
+
+.in +5
+.nf
+.na
+if (x > 0) {
+  x--;
+} else {
+  fprintf (stderr, "...something wrong?\\n");
+}
+.in -5
+.ad
+.fi
+
+With \(oq-br -nce\(cq that code would appear as
+
+.in +5
+.nf
+.na
+if (x > 0) {
+  x--;
+}
+else {
+  fprintf (stderr, "...something wrong?\\n");
+}
+.in -5
+.ad
+.fi
+
+An exception to the behavior occurs when there is a comment between the 
+right brace and the subsequent else statement.  While the \(oq-br\(cq 
+option will cause a left brace to jump over the comment, the else does 
+not jump over the comment to cuddle because it has a strong likelihood 
+of changing the meaning of the comment.
+
+The \(oq-cdw\(cq option causes the \fBwhile\fR in a do-while
+loop to cuddle up to the immediately preceding \(oq}\(cq.  For
+example, with \(oq-cdw\(cq you get the following:
+
+.in +5
+.nf
+.na
+do {
+  x--;
+} while (x);
+.in -5
+.ad
+.fi
+
+With \(oq-ncdw\(cq that code would appear as
+
+.in +5
+.nf
+.na
+do {
+  x--;
+}
+while (x);
+.in -5
+.ad
+.fi
+
+The \(oq-slc\(cq option allows for an unbraced conditional and its inner
+statement to appear on the same line. For example:
+
+.in +5
+.nf
+.na
+if (x) x--;
+else x++;
+.in -5
+.ad
+.fi
+
+Without \(oq-slc\(cq that code would appear as
+
+.in +5
+.nf
+.na
+if (x)
+  x--;
+else
+  x++;
+.in -5
+.ad
+.fi
+
+The \(oq-cli\(cq option specifies the number of spaces that case labels
+should be indented to the right of the containing \fBswitch\fR
+statement.
+
+The default gives code like:
+
+.in +5
+.nf
+.na
+switch (i)
+  {
+  case 0:
+    break;
+  case 1:
+    {
+      ++i;
+    }
+  default:
+    break;
+  }
+.in -5
+.ad
+.fi
+
+Using the \(oq-cli2\(cq that would become:
+
+.in +5
+.nf
+.na
+switch (i)
+  {
+    case 0:
+      break;
+    case 1:
+      {
+        ++i;
+      }
+    default:
+      break;
+  }
+.in -5
+.ad
+.fi
+
+The indentation of the braces below a case statement can be
+controlled with the \(oq-cbi\fIn\fR\(cq option.  For example,
+using \(oq-cli2 -cbi0\(cq results in:
+
+.in +5
+.nf
+.na
+switch (i)
+  {
+    case 0:
+      break;
+    case 1:
+    {
+      ++i;
+    }
+    default:
+      break;
+  }
+.in -5
+.ad
+.fi
+
+If a semicolon is on the same line as a \fBfor\fR or \fBwhile\fR
+statement, the \(oq-ss\(cq option will cause a space to be placed before
+the semicolon.  This emphasizes the semicolon, making it clear that the
+body of the \fBfor\fR or \fBwhile\fR statement is an empty statement.
+\(oq-nss\(cq disables this feature.
+
+The \(oq-pcs\(cq option causes a space to be placed between the name of
+the procedure being called and the \(oq(\(cq (for example, \fBputs\ ("Hi");\fR.  The \(oq-npcs\(cq option would give \fBputs("Hi");\fR).
+
+
+If the \(oq-cs\(cq option is specified, \fBindent\fR puts a space between
+a cast operator and the object to be cast. The \(oq-ncs\(cq ensures that there 
+is no space between the cast operator and the object. Remember that \fBindent\fR
+only knows about the standard C data types and so cannot recognise user-defined types
+in casts. Thus \fB(mytype)thing\fR is not treated as a cast.
+
+The \(oq-bs\(cq option ensures that there is a space between the
+keyword \fBsizeof\fR and its argument.  In some versions, this is
+known as the \(oqBill_Shannon\(cq option.
+
+The \(oq-saf\(cq option forces a space between a \fBfor\fR
+and the following parenthesis.  This is the default.
+
+The \(oq-sai\(cq option forces a space between a \fBif\fR
+and the following parenthesis.  This is the default.
+
+The \(oq-saw\(cq option forces a space between a \fBwhile\fR
+and the following parenthesis.  This is the default.
+
+The \(oq-prs\(cq option causes all parentheses to be separated with
+a space from whatever is between them.  For example, using \(oq-prs\(cq
+results in code like:
+
+.in +5
+.nf
+.na
+  while ( ( e_code - s_code ) < ( dec_ind - 1 ) )
+    {
+      set_buf_break ( bb_dec_ind );
+      *e_code++ = \(cq \(cq;
+    }
+.in -5
+.ad
+.fi
+
+.SH "DECLARATIONS"
+
+By default \fBindent\fR will line up identifiers, in the column
+specified by the \(oq-di\(cq option.  For example, \(oq-di16\(cq makes
+things look like:
+
+.in +5
+.nf
+.na
+int             foo;
+char           *bar;
+.in -5
+.ad
+.fi
+
+Using a small value (such as one or two) for the \(oq-di\(cq option can
+be used to cause the identifiers to be placed in the first available
+position; for example:
+
+.in +5
+.nf
+.na
+int foo;
+char *bar;
+.in -5
+.ad
+.fi
+
+The value given to the \(oq-di\(cq option will still affect variables
+which are put on separate lines from their types, for example
+\(oq-di2\(cq will lead to:
+
+.in +5
+.nf
+.na
+int
+  foo;
+.in -5
+.ad
+.fi
+
+If the \(oq-bc\(cq option is specified, a newline is forced after each
+comma in a declaration.  For example,
+
+.in +5
+.nf
+.na
+int a,
+  b,
+  c;
+.in -5
+.ad
+.fi
+
+With the \(oq-nbc\(cq option this would look like
+
+.in +5
+.nf
+.na
+int a, b, c;
+.in -5
+.ad
+.fi
+
+The \(oq-bfda\(cq option causes a newline to be forced after the comma
+separating the arguments of a function declaration.  The arguments will
+appear at one indention level deeper than the function declaration.  This 
+is particularly helpful for functions with long argument lists. 
+The option \(oq-bfde\(cq causes a newline to be forced before the closing 
+bracket of the function declaration. For both options the \(cqn\(cq setting is the default:
+-nbfda and -nbfde.
+
+
+For 
+example,
+
+.in +5
+.nf
+.na
+void foo (int arg1, char arg2, int *arg3, long arg4, char arg5);
+.in -5
+.ad
+.fi
+With the \(oq-bfda\(cq option this would look like
+
+.in +5
+.nf
+.na
+void foo (
+    int arg1,
+    char arg2,
+    int *arg3,
+    long arg4,
+    char arg5);
+.in -5
+.ad
+.fi
+
+With, in addition, the \(oq-bfde\(cq option this would look like
+
+.in +5
+.nf
+.na
+void foo (
+    int arg1,
+    char arg2,
+    int *arg3,
+    long arg4,
+    char arg5
+    );
+.in -5
+.ad
+.fi
+
+The \(oq-psl\(cq option causes the type of a procedure being defined to
+be placed on the line before the name of the procedure.  This style is
+required for the \fBetags\fR program to work correctly, as well as some
+of the \fBc-mode\fR functions of Emacs.
+
+You must use the \(oq-T\(cq
+option to tell \fBindent\fR the name of all the typenames in your
+program that are defined by \fBtypedef\fR.  \(oq-T\(cq can be specified
+more than once, and all names specified are used.  For example, if your
+program contains
+
+.in +5
+.nf
+.na
+typedef unsigned long CODE_ADDR;
+typedef enum {red, blue, green} COLOR;
+.in -5
+.ad
+.fi
+
+you would use the options \(oq-T CODE_ADDR -T COLOR\(cq.
+
+
+The \(oq-brs\(cq or \(oq-bls\(cq option specifies how to format braces
+in struct declarations.  The \(oq-brs\(cq option formats braces like
+this:
+
+.in +5
+.nf
+.na
+struct foo {
+  int x;
+};
+.in -5
+.ad
+.fi
+
+The \(oq-bls\(cq option formats them like this:
+
+.in +5
+.nf
+.na
+struct foo
+{
+  int x;
+};
+.in -5
+.ad
+.fi
+
+
+Similarly to the structure brace \(oq-brs\(cq and \(oq-bls\(cq options,
+ the function brace options \(oq-brf\(cq or \(oq-blf\(cq specify how to format the braces
+in function definitions.  The \(oq-brf\(cq option formats braces like
+this:
+
+.in +5
+.nf
+.na
+int one(void) {
+  return 1;
+};
+.in -5
+.ad
+.fi
+
+The \(oq-blf\(cq option formats them like this:
+
+.in +5
+.nf
+.na
+int one(void)
+{
+  return 1;
+};
+.in -5
+.ad
+.fi
+
+
+The \(oq-sar\(cq option affects how \fBindent\fR will render initializer
+lists. Without \(oq-sar\(cq they are formatted like this:
+
+.in +5
+.nf
+.na
+int a[] = {1, 2, 3, 4};
+
+struct s {
+  const char *name;
+  int x;
+} a[] = {
+  {"name", 0},
+  {"a", 1}
+};
+.in -5
+.ad
+.fi
+
+With \(oq-sar\(cq they are formatted like this, with spaces inside the
+braces:
+
+.in +5
+.nf
+.na
+int a[] = { 1, 2, 3, 4 };
+
+struct s {
+  const char *name;
+  int x;
+} a[] = {
+  { "name", 0 },
+  { "a", 1 }
+};
+.in -5
+.ad
+.fi
+
+.SH "INDENTATION"
+
+The most basic, and most controversial issues with regard to code
+formatting is precisely how indentation should be acoomplished.
+Fortunately, \fBindent\fR supports several different styles of
+identation.  The default is to use tabs for indentation, which is
+specified by the \(oq-ut\(cq option. Assuming the default tab size of
+8, the code would look like this:
+
+.in +5
+.nf
+.na
+int a(int b)
+{
+        return b;
+|------|
+ 1 tab
+}
+.in -5
+.ad
+.fi
+
+For those that prefer spaces to tabs, \(oqindent\(cq provides the
+\(oq-nut\(cq option. The same code would look like this:
+
+.in +5
+.nf
+.na
+int a(int b)
+{
+        return b;
+|------|
+8 spaces
+}
+.in -5
+.ad
+.fi
+
+Another issue in the formatting of code is how far each line should be
+indented from the left margin.  When the beginning of a statement such
+as \fBif\fR or \fBfor\fR is encountered, the indentation level is
+increased by the value specified by the \(oq-i\(cq option.  For example,
+use \(oq-i8\(cq to specify an eight character indentation for each
+level.  When a statement is broken across two lines, the second line is
+indented by a number of additional spaces specified by the \(oq-ci\(cq
+option.  \(oq-ci\(cq defaults to 0.  However, if the \(oq-lp\(cq option is
+specified, and a line has a left parenthesis which is not closed on that
+line, then continuation lines will be lined up to start at the character
+position just after the left parenthesis.  This processing also applies
+to \(oq[\(cq and applies to \(oq{\(cq when it occurs in initialization
+lists.  For example, a piece of continued code might look like this with
+\(oq-nlp -ci3\(cq in effect:
+
+.in +5
+.nf
+.na
+  p1 = first_procedure (second_procedure (p2, p3),
+     third_procedure (p4, p5));
+.in -5
+.ad
+.fi
+
+With \(oq-lp\(cq in effect the code looks somewhat clearer:
+
+.in +5
+.nf
+.na
+  p1 = first_procedure (second_procedure (p2, p3),
+                        third_procedure (p4, p5));
+.in -5
+.ad
+.fi
+
+When a statement is broken in between two or more paren pairs (...),
+each extra pair causes the indentation level extra indentation:
+
+.in +5
+.nf
+.na
+if ((((i < 2 &&
+        k > 0) || p == 0) &&
+    q == 1) ||
+  n = 0)
+.in -5
+.ad
+.fi
+
+The option \(oq-ip\fIN\fR\(cq can be used to set the extra offset per paren.
+For instance, \(oq-ip0\(cq would format the above as:
+
+.in +5
+.nf
+.na
+if ((((i < 2 &&
+  k > 0) || p == 0) &&
+  q == 1) ||
+  n = 0)
+.in -5
+.ad
+.fi
+
+.B indent\fR assumes that tabs are placed at regular intervals of both
+input and output character streams.  These intervals are by default 8
+columns wide, but (as of version 1.2) may be changed by the \(oq-ts\(cq
+option.  Tabs are treated as the equivalent number of spaces.
+
+By default, \fBindent\fR will use tabs to indent as far as possible,
+and then pad with spaces until the desired position is reached. However,
+with the \(oq-as\(cq option, spaces will be used for alignment beyond
+the current indentation level. By default, assuming \(oq-lp\(cq is
+enabled, the code would be indented like so (\(oqt\(cq represents tabs,
+\(oqs\(cq represents spaces):
+
+.in +5
+.nf
+.na
+unsigned long really_long_proc_name(unsigned long x, unsigned long y,
+                                    int a)
+|------||-------||------||-------|__
+   t        t       t       t     ss
+{
+        p1 = first_procedure (second_procedure (p2, p3),
+                              third_procedure (p4, p5));
+|------||------||------|_____
+   t       t       t    sssss
+}
+.in -5
+.ad
+.fi
+
+This is fine, if you assume that whoever is reading the code will honor
+your assumption of 8-space tabs. If the reader was using 4-space tabs,
+it would look like this:
+
+.in +5
+.nf
+.na
+unsigned long really_long_proc_name(unsigned long x, unsigned long y,
+                      int a)
+|---||---||---||---|__
+  t    t    t    t  ss
+{
+        p1 = first_procedure (second_procedure (p2, p3),
+                     third_procedure (p4, p5));
+|---||---||---|______
+  t    t    t  ssssss
+}
+.in -5
+.ad
+.fi
+
+The \(oq-as\(cq option fixes this so that the code will appear consistent
+regardless of what tab size the user users to read the code. This looks
+like:
+
+.in +5
+.nf
+.na
+unsigned long really_long_proc_name(unsigned long x, unsigned long y,
+                                    int a)
+____________________________________
+ssssssssssssssssssssssssssssssssssss
+{
+        p1 = first_procedure (second_procedure (p2, p3),
+                              third_procedure (p4, p5));
+|------|______________________
+   t    ssssssssssssssssssssss
+}
+.in -5
+.ad
+.fi
+
+The indentation of type declarations in old-style function definitions
+is controlled by the \(oq-ip\(cq parameter.  This is a numeric parameter
+specifying how many spaces to indent type declarations.  For example,
+the default \(oq-ip5\(cq makes definitions look like this:
+
+.in +5
+.nf
+.na
+char *
+create_world (x, y, scale)
+     int x;
+     int y;
+     float scale;
+{
+  . . .
+}
+.in -5
+.ad
+.fi
+
+For compatibility with other versions of indent, the option \(oq-nip\(cq
+is provided, which is equivalent to \(oq-ip0\(cq.
+
+ANSI C allows white space to be placed on preprocessor command lines
+between the character \(oq#\(cq and the command name.  By default,
+.B indent\fR removes this space, but specifying the \(oq-lps\(cq option
+directs \fBindent\fR to leave this space unmodified. The option \(oq-ppi\(cq 
+overrides  \(oq-nlps\(cq and  \(oq-lps\(cq.
+
+This option can be used to request that preprocessor conditional statements can
+be indented by to given number of spaces, for example with the option \(oq-ppi 3\(cq
+
+.in +5
+.nf
+.na
+#if X
+#if Y
+#define Z 1
+#else
+#define Z 0
+#endif
+#endif
+.in -5
+.ad
+.fi
+becomes
+.in +5
+.nf
+.na
+#if X
+#   if Y
+#      define Z 1
+#   else
+#      define Z 0
+#   endif
+#endif
+.in -5
+.ad
+.fi
+
+This option sets the offset at which a label (except case labels)
+will be positioned. If it is set to zero or a positive number, this indicates how 
+far from the left margin to indent a label.  If it is set to a negative number, 
+this indicates how far back from the current indent level to place the label.  
+The default setting is -2 which matches the behaviour of earlier versions of indent.
+Note that this parameter does not affect the placing of case labels; see the
+\(oq-cli\(cq parameter for that. For example with the option \(oq-il 1\(cq
+
+.in +5
+.nf
+.na
+group
+function()
+{
+    if (do_stuff1() == ERROR)
+        goto cleanup1;
+
+    if (do_stuff2() == ERROR)
+        goto cleanup2;
+
+    return SUCCESS;
+
+  cleanup2:
+    do_cleanup2();
+
+  cleanup1:
+    do_cleanup1();
+
+    return ERROR;
+}
+.in -5
+.ad
+.fi
+becomes
+.in +5
+.nf
+.na
+group
+function()
+{
+    if (do_stuff1() == ERROR)
+        goto cleanup1;
+
+    if (do_stuff2() == ERROR)
+        goto cleanup2;
+
+    return SUCCESS;
+
+ cleanup2:
+    do_cleanup2();
+
+ cleanup1:
+    do_cleanup1();
+
+    return ERROR;
+}
+.in -5
+.ad
+.fi
+
+.SH "BREAKING LONG LINES"
+
+With the option \(oq-l\fIn\fR\(cq, or \(oq--line-length\fIn\fR\(cq, it is
+possible to specify the maximum length of a line of C code, not including
+possible comments that follow it.
+
+When lines become longer than the specified line length, GNU \fBindent\fR
+tries to break the line at a logical place.  This is new as of version 2.1
+however and not very intelligent or flexible yet.
+
+Currently there are three options that allow one to interfere with the
+algorithm that determines where to break a line.
+
+The \(oq-bbo\(cq option causes GNU \fBindent\fR to prefer to break
+long lines before the boolean operators \fB&&\fR and \fB||\fR.  The
+\(oq-nbbo\(cq option causes GNU \fBindent\fR not have that
+preference.  For example, the default option \(oq-bbo\(cq (together
+with \(oq--line-length60\(cq and \(oq--ignore-newlines\(cq) makes code
+look like this:
+
+.in +5
+.nf
+.na
+  if (mask
+      && ((mask[0] == \(cq\\0\(cq)
+          || (mask[1] == \(cq\\0\(cq
+              && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq)))))
+.in -5
+.ad
+.fi
+
+Using the option \(oq-nbbo\(cq will make it look like this:
+
+.in +5
+.nf
+.na
+  if (mask &&
+      ((mask[0] == \(cq\\0\(cq) ||
+       (mask[1] == \(cq\\0\(cq &&
+        ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq)))))
+.in -5
+.ad
+.fi
+
+The default \(oq-hnl\(cq, however, honours newlines in the input file by
+giving them the highest possible priority to break lines at.  For example,
+when the input file looks like this:
+
+.in +5
+.nf
+.na
+  if (mask
+      && ((mask[0] == \(cq\\0\(cq)
+      || (mask[1] == \(cq\\0\(cq && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq)))))
+.in -5
+.ad
+.fi
+
+then using the option \(oq-hnl\(cq, or \(oq--honour-newlines\(cq,
+together with the previously mentioned \(oq-nbbo\(cq and
+\(oq--line-length60\(cq, will cause the output not to be what is given
+in the last example but instead will prefer to break at the positions
+where the code was broken in the input file:
+
+.in +5
+.nf
+.na
+  if (mask
+      && ((mask[0] == \(cq\\0\(cq)
+          || (mask[1] == \(cq\\0\(cq &&
+              ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq)))))
+.in -5
+.ad
+.fi
+
+The idea behind this option is that lines which are too long, but are already
+broken up, will not be touched by GNU \fBindent\fR.  Really messy code
+should be run through \fBindent\fR at least once using the
+\(oq--ignore-newlines\(cq option though.
+
+The \(oq-gts\(cq option affects how the gettext standard macros \fB_()\fR and \fBN_()\fR
+are treated.  The default behavior (or the use of \(oq-ngts\(cq) causes indent to 
+treat them as it does other functions, so that a long string is broken like the following
+example.
+
+.in +5
+.nf
+.na
+  if (mask)
+    {
+      warning (_
+               ("This is a long string that stays together."));
+    }
+.in -5
+.ad
+.fi
+
+With the \(oq-gts\(cq option, the underscore is treated as a part of the string, keeping
+it tied to the string, and respecting the fact that gettext is unobtrusively providing
+a localized string.  This only works if \fB_("\fR is together as a unit at the beginning
+of the string and \fB")\fR is together as a unit at the end.
+
+.in +5
+.nf
+.na
+  if (mask)
+    {
+      warning 
+        (_("This is a long string that stays together."));
+    }
+.in -5
+.ad
+.fi
+
+.SH "DISABLING FORMATTING"
+
+Formatting of C code may be disabled for portions of a program by
+embedding special \fIcontrol comments\fR in the program.  To turn off
+formatting for a section of a program, place the disabling control
+comment \fB/* *INDENT-OFF* */\fR on a line by itself just before that
+section.  Program text scanned after this control comment is output
+precisely as input with no modifications until the corresponding
+enabling comment is scanned on a line by itself.  The enabling control
+comment is \fB/* *INDENT-ON* */\fR, and any text following the comment
+on the line is also output unformatted.  Formatting begins again with
+the input line following the enabling control comment.
+
+More precisely, \fBindent\fR does not attempt to verify the closing
+delimiter (\fB*/\fR) for these C comments, and any whitespace on the
+line is totally transparent.
+
+These control comments also function in their C++ formats, namely
+.B // *INDENT-OFF*\fR and \fB// *INDENT-ON*\fR.
+
+It should be noted that the internal state of \fBindent\fR remains
+unchanged over the course of the unformatted section.  Thus, for
+example, turning off formatting in the middle of a function and
+continuing it after the end of the function may lead to bizarre
+results.  It is therefore wise to be somewhat modular in selecting code
+to be left unformatted.
+
+As a historical note, some earlier versions of \fBindent\fR produced
+error messages beginning with \fB*INDENT**\fR.  These versions of
+.B indent\fR were written to ignore any input text lines which began
+with such error messages.  I have removed this incestuous feature from
+GNU \fBindent\fR.
+
+.SH "MISCELLANEOUS OPTIONS"
+
+To find out what version of \fBindent\fR you have, use the command
+.B indent -version\fR.  This will report the version number of
+.B indent\fR, without doing any of the normal processing.
+
+The \(oq-v\(cq option can be used to turn on verbose mode.  When in
+verbose mode, \fBindent\fR reports when it splits one line of input
+into two more more lines of output, and gives some size statistics at
+completion. 
+
+The \(oq-pmt\(cq option causes \fBindent\fR to preserve the access
+and modification times on the output files.  Using this option
+has the advantage that running indent on all source and header
+files in a project won\(cqt cause \fBmake\fR to rebuild all targets.
+This option is only available on Operating Systems that have the
+POSIX \fButime(2)\fR function.
+
+.SH "BUGS"
+
+Please report any bugs to bug-indent@gnu.org.
+
+When \fBindent\fR is run twice on a file, with the same profile,
+it should \fInever\fR change that file the second time.  With the
+current design of \fBindent\fR, this can not be guaranteed,
+and it has not been extensively tested.
+
+.B indent\fR does not understand C.  In some cases this leads to
+the inability to join lines.  The result is that running a file
+through \fBindent\fR is \fIirreversible\fR, even if the used input
+file was the result of running \fBindent\fR with a given profile
+(\(oq.indent.pro\(cq).
+
+While an attempt was made to get \fBindent\fR working for C++, it
+will not do a good job on any C++ source except the very simplest.
+
+.B indent\fR does not look at the given \(oq--line-length\(cq option
+when writing comments to the output file.  This results often in comments
+being put far to the right.  In order to prohibit \fBindent\fR from
+joining a broken line that has a comment at the end, make sure that the
+comments start on the first line of the break.
+
+.B indent\fR does not count lines and comments (see the \(oq-v\(cq
+option) when \fBindent\fR is turned off with 
+.B /* *INDENT-OFF* */\fR.
+
+Comments of the form \fB/*UPPERCASE*/\fR are not treated as comment but as an
+identifier, causing them to be joined with the next line. This renders
+comments of this type useless, unless they are embedded in the code to
+begin with.
+
+.SH "COPYRIGHT"
+
+The following copyright notice applies to the \fBindent\fR program.
+The copyright and copying permissions for this manual appear near the
+beginning of \(oqindent.texinfo\(cq and \(oqindent.info\(cq, and near the
+end of \(oqindent.1\(cq.
+
+.nf
+.na
+Copyright (c) 2015 Tim Hentenaar.
+Copyright (c) 2001 David Ingamells.
+Copyright (c) 1999 Carlo Wood.
+Copyright (c) 1995, 1996 Joseph Arceneaux.
+Copyright (c) 1989, 1992, 1993, 1994, 1995, 1996, 2014 Free Software Foundation
+Copyright (c) 1985 Sun Microsystems, Inc.
+Copyright (c) 1980 The Regents of the University of California.
+Copyright (c) 1976 Board of Trustees of the University of Illinois.
+All rights reserved.
+
+Redistribution and use in source and binary forms are permitted
+provided that the above copyright notice and this paragraph are
+duplicated in all such forms and that any documentation,
+advertising materials, and other materials related to such
+distribution and use acknowledge that the software was developed
+by the University of California, Berkeley, the University of Illinois,
+Urbana, and Sun Microsystems, Inc.  The name of either University
+or Sun Microsystems may not be used to endorse or promote products
+derived from this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED \(oq\(oqAS IS\(cq\(cq AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.
+.ad
+.fi
+
+.SH "Options\(cq Cross Key"
+
+Here is a list of options alphabetized by long option, to help you find
+the corresponding short option.
+
+
+.in +5
+.nf
+.na
+--align-with-spaces                             -as
+--blank-lines-after-commas                      -bc             
+--blank-lines-after-declarations                -bad            
+--blank-lines-after-procedures                  -bap            
+--blank-lines-before-block-comments             -bbb            
+--braces-after-if-line                          -bl             
+--braces-after-func-def-line                    -blf
+--brace-indent                                  -bli
+--braces-after-struct-decl-line                 -bls
+--braces-on-if-line                             -br             
+--braces-on-func-def-line                       -brf
+--braces-on-struct-decl-line                    -brs
+--break-after-boolean-operator                  -nbbo
+--break-before-boolean-operator                 -bbo
+--break-function-decl-args                      -bfda
+--break-function-decl-args-end                  -bfde
+--case-indentation                              -cli\fIn\fR     
+--case-brace-indentation                        -cbi\fIn\fR
+--comment-delimiters-on-blank-lines             -cdb            
+--comment-indentation                           -c\fIn\fR       
+--continuation-indentation                      -ci\fIn\fR      
+--continue-at-parentheses                       -lp             
+--cuddle-do-while                               -cdw
+--cuddle-else                                   -ce             
+--declaration-comment-column                    -cd\fIn\fR      
+--declaration-indentation                       -di\fIn\fR      
+--dont-break-function-decl-args                 -nbfda
+--dont-break-function-decl-args-end             -nbfde
+--dont-break-procedure-type                     -npsl           
+--dont-cuddle-do-while                          -ncdw
+--dont-cuddle-else                              -nce            
+--dont-format-comments                          -nfca           
+--dont-format-first-column-comments             -nfc1           
+--dont-line-up-parentheses                      -nlp            
+--dont-left-justify-declarations                -ndj  
+--dont-space-special-semicolon                  -nss
+--dont-star-comments                            -nsc            
+--dont-tab-align-comments                       -ntac
+--else-endif-column                             -cp\fIn\fR
+--format-all-comments                           -fca            
+--format-first-column-comments                  -fc1            
+--gnu-style                                     -gnu            
+--honour-newlines                               -hnl
+--ignore-newlines                               -nhnl
+--ignore-profile                                -npro           
+--indent-label                                  -il\fIn\fR       
+--indent-level                                  -i\fIn\fR       
+--k-and-r-style                                 -kr             
+--leave-optional-blank-lines                    -nsob           
+--leave-preprocessor-space                      -lps
+--left-justify-declarations                     -dj 
+--line-comments-indentation                     -d\fIn\fR       
+--line-length                                   -l\fIn\fR       
+--linux-style                                   -linux             
+--no-blank-lines-after-commas                   -nbc            
+--no-blank-lines-after-declarations             -nbad           
+--no-blank-lines-after-procedures               -nbap           
+--no-blank-lines-before-block-comments          -nbbb           
+--no-comment-delimiters-on-blank-lines          -ncdb           
+--no-space-after-casts                          -ncs            
+--no-parameter-indentation                      -nip            
+--no-space-after-for				-nsaf
+--no-space-after-function-call-names            -npcs           
+--no-space-after-if				-nsai
+--no-space-after-parentheses                    -nprs
+--no-space-after-while				-nsaw
+--no-tabs                                       -nut
+--no-verbosity                                  -nv             
+--original                                      -orig
+--parameter-indentation                         -ip\fIn\fR      
+--paren-indentation                             -pi\fIn\fR
+--preserve-mtime				-pmt
+--preprocessor-indentation                      -ppi\fIn\fR
+--procnames-start-lines                         -psl            
+--remove-preprocessor-space                     -nlps
+--single-line-conditionals                      -slc
+--space-after-cast                              -cs             
+--space-after-for				-saf
+--space-after-if				-sai
+--space-after-parentheses                       -prs
+--space-after-procedure-calls                   -pcs            
+--space-after-while				-saw
+--space-special-semicolon                       -ss             
+--spaces-around-initializers                    -sar
+--standard-output                               -st             
+--start-left-side-of-comments                   -sc             
+--struct-brace-indentation                      -sbi\fIn\fR
+--swallow-optional-blank-lines                  -sob            
+--tab-size                                      -ts\fIn\fR      
+--use-tabs                                      -ut
+--verbose                                       -v              
+.in -5
+.ad
+.fi
+
+.SH "RETURN VALUE"
+.IP \(bu 2
+0 means no errors or warnings were found during a successful invocation of
+the program.
+.br
+.IP \(bu 2
+2 is returned if errors occur during formatting which do not prevent completion
+of the formatting, but which appear to be  manifested by incorrect code (i.e. code
+which wouldn't compile).
+.br
+.IP \(bu 2
+3 is returned if formatting of a file is halted because of an error with the file
+which prevents completion of formatting. If more than one input file was specified,
+indent continues to the next file.
+.br
+.IP \(bu 2
+4 is returned if a serious internal problem occurs and the entire indent process
+is terminated, even if all specified files have not been processed.
+.br
+.IP \(bu 2
+64 is returned if an invocation problem (like an incorrect option) prevents
+any formatting to occur.
+.SH FILES
+.br
+.nf
+.\" set tabstop to longest possible filename, plus a wee bit
+.ta \w'$HOME/.indent.pro   'u
+\fI$HOME/.indent.pro\fR	holds default options for indent.
+.SH "AUTHORS"
+.br
+Tim Hentenaar
+.br
+Carlo Wood
+.br
+Joseph Arceneaux
+.br
+Jim Kingdon
+.br
+David Ingamells
+.SH "HISTORY"
+Derived from the UCB program "indent".
+.SH "COPYING"
+Copyright (C) 1989, 1992, 1993, 1994, 1995, 1996, 2014, 2015 Free Software Foundation, Inc.
+Copyright (C) 1995, 1996 Joseph Arceneaux.
+Copyright (C) 1999 Carlo Wood.
+Copyright (C) 2001 David Ingamells.
+Copyright (C) 2013 �ukasz Stelmach.
+Copyright (C) 2015 Tim Hentenaar.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+
diff --git a/upstream/mageia-cauldron/man1/indxbib.1 b/upstream/mageia-cauldron/man1/indxbib.1
new file mode 100644
index 00000000..d1e593c5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/indxbib.1
@@ -0,0 +1,276 @@
+.TH INDXBIB 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+indxbib \- make inverted index for bibliographic databases
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY indxbib
+.OP \-w
+.OP \-c file
+.OP \-d dir
+.OP \-f file
+.OP \-h n
+.OP \-i string
+.OP \-k n
+.OP \-l n
+.OP \-n n
+.OP \-o file
+.OP \-t n
+.RI [ filename
+\&.\|.\|.\&]
+.YS
+.
+.SY indxbib
+.B \-\-help
+.YS
+.
+.SY indxbib
+.B \-v
+.SY indxbib
+.B \-\-version
+.YS
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B indxbib
+makes an inverted index for the bibliographic databases in
+.IR filename \|.\|.\|.
+for use with
+.BR refer (1),
+.BR lookbib (1),
+and
+.BR lkbib (1).
+.
+The index will be named
+.RI filename .i ;
+the index is written to a temporary file which is then renamed to
+this.
+.
+If no filenames are given on the command line because the
+.B \-f
+option has been used, and no
+.B \-o
+option is given, the index will be named
+.IR Ind.i .
+.
+.
+.LP
+Bibliographic databases are divided into records by blank lines.
+Within a record, each fields starts with a
+.B %
+character at the beginning of a line.
+.
+Fields have a one letter name which follows the
+.B %
+character.
+.
+.
+.LP
+The values set by the
+.BR \-c ,
+.BR \-n ,
+.BR \-l ,
+and
+.B \-t
+options are stored in the index;
+when the index is searched, keys will be discarded and truncated in a
+manner appropriate to these options;
+the original keys will be used for verifying that any record
+found using the index actually contains the keys.
+.
+This means that a user of an index need not know whether these
+options were used in the creation of the index,
+provided that not all the keys to be searched for
+would have been discarded during indexing
+and that the user supplies at least the part of each key
+that would have remained after being truncated during indexing.
+.
+The value set by the
+.B \-i
+option is also stored in the index
+and will be used in verifying records found using the index.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.B \-w
+Index whole files.
+.
+Each file is a separate record.
+.
+.TP
+.BI \-c file
+Read the list of common words from
+.I file
+instead of
+.IR /usr/\:share/\:groff/\:1.22.4/\:eign .
+.
+.TP
+.BI \-d dir
+Use
+.I dir
+as the pathname of the current working directory to store in the index,
+instead of the path printed by
+.BR pwd (1).
+.
+Usually
+.I dir
+will be a symbolic link that points to the directory printed by
+.BR pwd (1).
+.
+.TP
+.BI \-f file
+Read the files to be indexed from
+.IR file .
+.
+If
+.I file
+is
+.BR \- ,
+files will be read from the standard input.
+The
+.B \-f
+option can be given at most once.
+.
+.TP
+.BI \-i string
+Don't index the contents of fields whose names are in
+.IR string .
+.
+Initially
+.I string
+is
+.BR XYZ .
+.
+.TP
+.BI \-h n
+Use the first prime greater than or equal to
+.I n
+for the size of the hash table.
+.
+Larger values of
+.I n
+will usually make searching faster,
+but will make the index larger
+and
+.B indxbib
+use more memory.
+.
+Initially
+.I n
+is 997.
+.
+.TP
+.BI \-k n
+Use at most
+.I n
+keys per input record.
+.
+Initially
+.I n
+is 100.
+.
+.TP
+.BI \-l n
+Discard keys that are shorter than
+.IR n .
+.
+Initially
+.I n
+is 3.
+.
+.TP
+.BI \-n n
+Discard the
+.I n
+most common words.
+.
+Initially
+.I n
+is 100.
+.
+.TP
+.BI \-o basename
+The index should be named
+.RI basename .i .
+.
+.TP
+.BI \-t n
+Truncate keys to
+.IR n .
+.
+Initially
+.I n
+is 6.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.RI filename .i
+Index.
+.
+.TP
+.I Ind.i
+Default index name.
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:eign
+List of common words.
+.
+.TP
+.IR indxbib XXXXXX
+Temporary file.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR refer (1),
+.BR lkbib (1),
+.BR lookbib (1)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/info.1 b/upstream/mageia-cauldron/man1/info.1
new file mode 100644
index 00000000..3801a1fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/info.1
@@ -0,0 +1,101 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH INFO "1" "October 2023" "GNU texinfo 7.1" "User Commands"
+.SH NAME
+info \- read Info documents
+.SH SYNOPSIS
+.B info
+[\fI\,OPTION\/\fR]... [\fI\,MENU-ITEM\/\fR...]
+.SH DESCRIPTION
+Read documentation in Info format.
+.SS "Frequently-used options:"
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+use all matching manuals
+.TP
+\fB\-k\fR, \fB\-\-apropos\fR=\fI\,STRING\/\fR
+look up STRING in all indices of all manuals
+.TP
+\fB\-d\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
+add DIR to INFOPATH
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fI\,MANUAL\/\fR
+specify Info manual to visit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-index\-search\fR=\fI\,STRING\/\fR
+go to node pointed by index entry STRING
+.TP
+\fB\-n\fR, \fB\-\-node\fR=\fI\,NODENAME\/\fR
+specify nodes in first visited Info file
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+output selected nodes to FILE
+.TP
+\fB\-\-subnodes\fR
+recursively output menu items
+.TP
+\fB\-v\fR, \fB\-\-variable\fR VAR=VALUE
+assign VALUE to Info variable VAR
+.TP
+\fB\-\-version\fR
+display version information and exit
+.TP
+\fB\-w\fR, \fB\-\-where\fR, \fB\-\-location\fR
+print physical location of Info file
+.PP
+The first non\-option argument, if present, is the menu entry to start from;
+it is searched for in all 'dir' files along INFOPATH.
+If it is not present, info merges all 'dir' files and shows the result.
+Any remaining arguments are treated as the names of menu
+items relative to the initial node visited.
+.PP
+For a summary of key bindings, type H within Info.
+.SH EXAMPLES
+.TP
+info
+show top\-level dir menu
+.TP
+info info\-stnd
+show the manual for this Info program
+.TP
+info emacs
+start at emacs node from top\-level dir
+.TP
+info emacs buffers
+select buffers menu entry in emacs manual
+.TP
+info emacs \-n Files
+start at Files node within emacs manual
+.TP
+info '(emacs)Files'
+alternative way to start at Files node
+.TP
+info \-\-subnodes \-o out.txt emacs
+dump entire emacs manual to out.txt
+.TP
+info \-f ./foo.info
+show file ./foo.info, not searching dir
+.SH "REPORTING BUGS"
+Email bug reports to bug\-texinfo@gnu.org,
+general questions and discussion to help\-texinfo@gnu.org.
+.br
+Texinfo home page: http://www.gnu.org/software/texinfo/
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B info
+is maintained as a Texinfo manual.  If the
+.B info
+program is properly installed at your site, the command
+.IP
+.B info info
+.PP
+should give you access to the complete manual.
+(Or, if you have Emacs, M-x info will lead to the manual.)
diff --git a/upstream/mageia-cauldron/man1/infocmp.1m b/upstream/mageia-cauldron/man1/infocmp.1m
new file mode 100644
index 00000000..b18a5a67
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/infocmp.1m
@@ -0,0 +1,667 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2017,2018 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: infocmp.1m,v 1.107 2024/01/13 22:05:39 tom Exp $
+.TH infocmp 1M 2024-01-13 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds '  \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.ie t .ds '  \(aq
+.el   .ds '  '
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.
+.ds d /usr/share/terminfo
+.SH NAME
+\fBinfocmp\fP \-
+compare or print out \fIterminfo\fP descriptions
+.SH SYNOPSIS
+\fBinfocmp\fP [\fB\-\
+1\
+c\
+C\
+d\
+D\
+e\
+E\
+F\
+g\
+G\
+i\
+I\
+K\
+l\
+L\
+n\
+p\
+q\
+r\
+t\
+T\
+u\
+U\
+V\
+W\
+x\
+\fP]
+      [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fBsubset\fR]
+      [\fB\-w\fP\ \fIwidth\fP] [\fB\-A\fP\ \fIdirectory\fP] [\fB\-B\fP\ \fIdirectory\fP]
+      [\fIterminal-type\fP ...]
+.SH DESCRIPTION
+\fBinfocmp\fP can be used to compare a binary \fBterminfo\fP entry with other
+terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the
+\fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the
+binary file (\fBterm\fP) in a variety of formats.
+In all cases, the Boolean
+fields will be printed first, followed by the numeric fields, followed by the
+string fields.
+.SS "Default Options"
+If no options are specified and zero or one \fIterminal-types\fP are
+specified,
+the
+\fB\-I\fP option will be assumed.
+If more than one \fIterminal-type\fP is specified,
+the \fB\-d\fP option will be assumed.
+.SS "Comparison Options [\-d] [\-c] [\-n]"
+\fBinfocmp\fP compares the \fBterminfo\fP description of the first terminal
+\fIterminal-type\fP with each of the descriptions given by the entries
+for the other terminal's \fIterminal-types\fP.
+If a capability is defined for only one of the
+terminals, the value returned depends on the type of the capability:
+.bP
+\fBF\fP for missing Boolean variables
+.bP
+\fBNULL\fP for missing integer or string variables
+.PP
+Use the \fB\-q\fP option to show the distinction between
+\fIabsent\fP and \fIcancelled\fP capabilities.
+.PP
+These options produce a list which you can use to compare two
+or more terminal descriptions:
+.TP 5
+\fB\-d\fP
+produces a list of each capability that is \fIdifferent\fP
+between two entries.
+Each item in the list shows \*(``:\*('' after the capability name,
+followed by the capability values, separated by a comma.
+.TP
+\fB\-c\fP
+produces a list of each capability that is \fIcommon\fP between
+two or more entries.
+Missing capabilities are ignored.
+Each item in the list shows \*(``=\*('' after the capability name,
+followed by the capability value.
+.IP
+The \fB\-u\fP option provides a related output,
+showing the first terminal description rewritten to use the second
+as a building block via the \*(``use=\*('' clause.
+.TP
+\fB\-n\fP
+produces a list of each capability that is in \fInone\fP of the given entries.
+Each item in the list shows \*(``!\*('' before the capability name.
+.IP
+Normally only the conventional capabilities are shown.
+Use the \fB\-x\fP option to add the BSD-compatibility
+capabilities (names prefixed with \*(``OT\*('').
+.IP
+If no \fIterminal-types\fP are given,
+\fBinfocmp\fP uses the environment variable \fITERM\fP
+for each of the \fIterminal-types\fP.
+.SS "Source Listing Options [\-I] [\-L] [\-C] [\-r]"
+The \fB\-I\fP, \fB\-L\fP, and \fB\-C\fP options will produce
+a source listing for each terminal named.
+.PP
+.TS
+center;
+Lb L.
+\-I	use \fIterminfo\fP capability codes
+\-L	use \*(``long\*('' capability names
+\-C	use \fItermcap\fP capability codes
+\-r	with \fB\-C\fP, include nonstandard capabilities
+\-K	with \fB\-C\fP, improve BSD compatibility
+.TE
+.PP
+If no \fIterminal-types\fP are given,
+the environment variable \fITERM\fP will be used for the terminal name.
+.PP
+The source produced by the \fB\-C\fP option may be used directly as a
+\fBtermcap\fP entry, but not all parameterized strings can be changed to
+the \fBtermcap\fP format.
+\fBinfocmp\fP will attempt to convert most of the
+parameterized information, and anything not converted will be plainly marked in
+the output and commented out.
+These should be edited by hand.
+.PP
+For best results when converting to \fBtermcap\fP format,
+you should use both \fB\-C\fP and \fB\-r\fP.
+Normally a termcap description is limited to 1023 bytes.
+\fBinfocmp\fP trims away less essential parts to make it fit.
+If you are converting to one of the (rare) termcap implementations
+which accept an unlimited size of termcap,
+you may want to add the \fB\-T\fP option.
+More often however, you must help the termcap implementation,
+and trim excess whitespace (use the \fB\-0\fP option for that).
+.PP
+All padding information for strings will be collected together and placed
+at the beginning of the string where \fBtermcap\fP expects it.
+Mandatory
+padding (padding information with a trailing \*(``/\*('') will become optional.
+.PP
+All \fBtermcap\fP variables no longer supported by \fBterminfo\fP, but which
+are derivable from other \fBterminfo\fP variables, will be output.
+Not all
+\fBterminfo\fP capabilities will be translated; only those variables which were
+part of \fBtermcap\fP will normally be output.
+Specifying the \fB\-r\fP option
+will take off this restriction, allowing all capabilities to be output in
+\fItermcap\fP form.
+Normally you would use both the \fB\-C\fP and \fB\-r\fP options.
+The actual format used incorporates some improvements for escaped characters
+from terminfo format.
+For a stricter BSD-compatible translation, use the \fB\-K\fP option
+rather than \fB\-C\fP.
+.PP
+Note that because padding is collected to the beginning of the capability, not
+all capabilities are output.
+Mandatory padding is not supported.
+Because
+\fBtermcap\fP strings are not as flexible, it is not always possible to convert
+a \fBterminfo\fP string capability into an equivalent \fBtermcap\fP format.
+A subsequent conversion of the \fBtermcap\fP file
+back into \fBterminfo\fP format
+will not necessarily reproduce the original \fBterminfo\fP source.
+.PP
+Some common \fBterminfo\fP parameter sequences, their \fBtermcap\fP
+equivalents, and some terminal types which commonly have such sequences, are:
+.PP
+.TS
+center;
+Lf(BI) Lf(BI) L
+Lb     Lb     L.
+terminfo	termcap	Terminal Types
+_
+.\" ansi-m cup (adm3a has other stuff in between, more like concept)
+%p1%c	%.	ansi\-m
+.\" ansi cub, vt100 cub
+%p1%d	%d	ansi, vt100
+.\" vt52 cup (via vt52-basic)
+%p1%\*' \*'%+%c	%+x	vt52
+.\" ansi cup, vt100 cup
+%i	%iq	ansi, vt100
+.\" annarbor4080 cup
+%p1%?%\*'x\*'%>%t%p1%\*'y\*'%+%;	%>xy	annarbor4080
+.\" hpgeneric cup
+%p2\fR\|.\|.\|.\|\fP%p1	%r	hpgeneric
+.TE
+.SS "Use= Option [\-u]"
+The \fB\-u\fP option produces a \fBterminfo\fP source description of the first
+terminal \fIterminal-type\fP which is relative to the sum of the
+descriptions given by the entries for the other \fIterminal-types\fP.
+It does this by
+analyzing the differences between the first \fIterminal-types\fP and the
+other \fIterminal-types\fP and producing a description with \fBuse=\fP
+fields for the other terminals.
+In this manner, it is possible to retrofit generic terminfo
+entries into a terminal's description.
+Or, if two similar terminals exist, but
+were coded at different times or by different people so that each description
+is a full description, using \fBinfocmp\fP
+will show what can be done to change
+one description to be relative to the other.
+.PP
+A capability will be printed with an at-sign (@) if it no longer exists in the
+first \fIterminal-type\fP,
+but one of the other \fIterminal-type\fP entries contains a value for
+it.
+A capability's value will be printed if the value in the first
+\fIterminal-type\fP is not found in any of the other \fIterminal-type\fP
+entries,
+or if the first of the other \fIterminal-type\fP entries that has this
+capability gives a different value for the capability than that in the
+first \fIterminal-type\fP.
+.PP
+The order of the other \fIterminal-type\fP entries is significant.
+Since the
+terminfo compiler \fBtic\fP does a left-to-right scan of the capabilities,
+specifying two \fBuse=\fP entries that contain differing entries for the same
+capabilities will produce different results depending on the order that the
+entries are given in.
+\fBinfocmp\fP will flag any such inconsistencies between
+the other \fIterminal-type\fP entries as they are found.
+.PP
+Alternatively, specifying a capability \fIafter\fP a \fBuse=\fP entry that
+contains that capability will cause the second specification to be ignored.
+Using \fBinfocmp\fP to recreate a description can be a useful check to make
+sure that everything was specified correctly in the original source
+description.
+.PP
+Another error that does not cause incorrect compiled files, but will slow down
+the compilation time, is specifying extra \fBuse=\fP fields that are
+superfluous.
+\fBinfocmp\fP will flag any other \fIterminal-type use=\fP fields that
+were not needed.
+.SS "Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]"
+Like other \fI\%ncurses\fP utilities,
+\fBinfocmp\fP looks for the terminal descriptions in several places.
+You can use the \fI\%TERMINFO\fP and \fI\%TERMINFO_DIRS\fP environment
+variables to override the compiled-in default list of places to search.
+See \fBcurses\fP(3X), as well as
+the \fIFetching Compiled Descriptions\fP section in \fBterminfo\fR(5).
+.PP
+You can also use the options \fB\-A\fP
+and \fB\-B\fP to override the list of places to search
+when comparing terminal descriptions:
+.bP
+The \fB\-A\fP option sets the location for the first \fIterminal-type\fP
+.bP
+The \fB\-B\fP option sets the location for the other
+\fIterminal-types\fP.
+.PP
+Using these options, it is possible to
+compare descriptions for a terminal with the same name located in two different
+databases.
+For instance,
+you can use this feature for comparing descriptions for the same terminal
+created by different people.
+.SS "Other Options"
+.TP 5
+\fB\-0\fP
+causes the fields to be printed on one line, without wrapping.
+.TP 5
+\fB\-1\fP
+causes the fields to be printed out one to a line.
+Otherwise,
+the fields will be printed several to a line to a maximum width
+of 60 characters.
+.TP
+\fB\-a\fP
+tells \fBinfocmp\fP to retain commented-out capabilities
+rather than discarding them.
+Capabilities are commented by prefixing them with a period.
+.TP
+\fB\-D\fP
+tells \fBinfocmp\fP to print the database locations that it knows about,
+and exit.
+.TP 5
+\fB\-E\fP
+Dump the capabilities of the given terminal as tables, needed in
+the C initializer for a
+TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
+This option is useful for preparing versions of the curses library hardwired
+for a given terminal type.
+The tables are all declared static, and are named according to the type
+and the name of the corresponding terminal entry.
+.sp
+Before \fI\%ncurses\fP 5.0,
+the split between the \fB\-e\fP and \fB\-E\fP options was not needed;
+but support for extended names required making the arrays of terminal
+capabilities separate from the TERMTYPE structure.
+.TP 5
+\fB\-e\fP
+Dump the capabilities of the given terminal as a C initializer for a
+TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
+This option is useful for preparing versions of the curses library hardwired
+for a given terminal type.
+.TP 5
+\fB\-F\fP
+compare terminfo files.
+This assumes that two following arguments are filenames.
+The files are searched for pairwise matches between
+entries, with two entries considered to match if any of their names do.
+The report printed to standard output lists entries with no matches in
+the other file, and entries with more than one match.
+For entries
+with exactly one match it includes a difference report.
+Normally,
+to reduce the volume of the report, use references are
+not resolved before looking for differences, but resolution can be forced
+by also specifying \fB\-r\fP.
+.TP 5
+\fB\-f\fP
+Display complex terminfo strings which contain if/then/else/endif expressions
+indented for readability.
+.TP 5
+\fB\-G\fP
+Display constant literals in decimal form
+rather than their character equivalents.
+.TP 5
+\fB\-g\fP
+Display constant character literals in quoted form
+rather than their decimal equivalents.
+.TP 5
+\fB\-i\fP
+Analyze the initialization (\fBis1\fP, \fBis2\fP, \fBis3\fP), and reset
+(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP), strings in the entry,
+as well as those used for starting/stopping cursor-positioning mode
+(\fBsmcup\fP, \fBrmcup\fP) as well as starting/stopping keymap mode
+(\fBsmkx\fP, \fBrmkx\fP).
+.IP
+For each string, the
+code tries to analyze it into actions in terms of the other capabilities in the
+entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series
+private modes (the set of recognized special sequences has been selected for
+completeness over the existing terminfo database).
+Each report line consists
+of the capability name, followed by a colon and space, followed by a printable
+expansion of the capability string with sections matching recognized actions
+translated into {}-bracketed descriptions.
+.IP
+Here is a list of the DEC/ANSI
+special sequences recognized:
+.PP
+.TS
+center;
+L L.
+Action	Meaning
+_
+RIS	full reset
+SC	save cursor
+RC	restore cursor
+LL	home-down
+RSR	reset scroll region
+_
+DECSTR	soft reset (VT320)
+S7C1T	7-bit controls (VT220)
+_
+ISO DEC G0	enable DEC graphics for G0
+ISO UK G0	enable UK chars for G0
+ISO US G0	enable US chars for G0
+ISO DEC G1	enable DEC graphics for G1
+ISO UK G1	enable UK chars for G1
+ISO US G1	enable US chars for G1
+_
+DECPAM	application keypad mode
+DECPNM	normal keypad mode
+DECANSI	enter ANSI mode
+_
+ECMA[+\-]AM	keyboard action mode
+ECMA[+\-]IRM	insert replace mode
+ECMA[+\-]SRM	send receive mode
+ECMA[+\-]LNM	linefeed mode
+_
+DEC[+\-]CKM	application cursor keys
+DEC[+\-]ANM	set VT52 mode
+DEC[+\-]COLM	132-column mode
+DEC[+\-]SCLM	smooth scroll
+DEC[+\-]SCNM	reverse video mode
+DEC[+\-]OM	origin mode
+DEC[+\-]AWM	wraparound mode
+DEC[+\-]ARM	auto-repeat mode
+.TE
+.sp
+It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
+Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
+REVERSE.
+All but NORMAL may be prefixed with
+.RS
+.bP
+\*(``+\*('' (turn on) or
+.bP
+\*(``\-\*('' (turn off).
+.RE
+.IP
+An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
+.TP 5
+\fB\-l\fP
+Set output format to terminfo.
+.TP 5
+\fB\-p\fP
+Ignore padding specifications when comparing strings.
+.TP 5
+\fB\-Q\fP \fIn\fP
+Rather than show source in terminfo (text) format,
+print the compiled (binary) format in hexadecimal or base64 form,
+depending on the option's value:
+.RS 8
+.TP 3
+1
+hexadecimal
+.TP 3
+2
+base64
+.TP 3
+3
+hexadecimal and base64
+.RE
+.IP
+For example, this prints the compiled terminfo value as a string
+which could be assigned to the \fI\%TERMINFO\fP environment variable:
+.PP
+.RS 9
+.EX
+infocmp \-0 \-q \-Q2
+.EE
+.RE
+.TP 5
+\fB\-q\fP
+This makes the output a little shorter:
+.RS
+.bP
+Make the comparison listing shorter by omitting subheadings, and using
+\*(``\-\*('' for absent capabilities, \*(``@\*(''
+for canceled rather than \*(``NULL\*(''.
+.bP
+However, show differences between absent and cancelled capabilities.
+.bP
+Omit the \*(``Reconstructed from\*('' comment for source listings.
+.RE
+.TP 5
+\fB\-R\fIsubset\fR
+Restrict output to a given subset.
+This option is for use with archaic
+versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
+the full set of SVR4/XSI Curses terminfo; and variants such as AIX
+that have their own extensions incompatible with SVr4/XSI.
+.RS
+.bP
+Available terminfo
+subsets are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', and \*(``AIX\*('';
+see \fBterminfo\fP(5) for details.
+.bP
+You can also choose the subset \*(``BSD\*('' which selects only capabilities
+with termcap equivalents recognized by 4.4BSD.
+.bP
+If you select any other value for \fB\-R\fP,
+it is the same as no subset, i.e., all capabilities are used.
+.RE
+.IP
+A few options override the subset selected with \fB\-R\fP,
+if they are processed later in the command parameters:
+.RS
+.TP 5
+\fB\-C\fP
+sets the \*(``BSD\*('' subset as a side-effect.
+.TP 5
+\fB\-I\fP
+sets the subset to all capabilities.
+.TP 5
+\fB\-r\fP
+sets the subset to all capabilities.
+.RE
+.TP
+\fB\-s \fI[d|i|l|c]\fR
+The \fB\-s\fP option sorts the fields within each type according to the argument
+below:
+.br
+.RS 5
+.TP 5
+\fBd\fP
+leave fields in the order that they are stored in the \fIterminfo\fP database.
+.TP 5
+\fBi\fP
+sort by \fIterminfo\fP name.
+.TP 5
+\fBl\fP
+sort by the long C variable name.
+.TP 5
+\fBc\fP
+sort by the \fItermcap\fP name.
+.RE
+.IP
+If the \fB\-s\fP option is not given, the fields printed out will be
+sorted alphabetically by the \fBterminfo\fP name within each type,
+except in the case of the \fB\-C\fP or the \fB\-L\fP options, which cause the
+sorting to be done by the \fBtermcap\fP name or the long C variable
+name, respectively.
+.TP 5
+\fB\-T\fP
+eliminates size-restrictions on the generated text.
+This is mainly useful for testing and analysis, since the compiled
+descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
+.TP
+\fB\-t\fP
+tells \fBtic\fP to discard commented-out capabilities.
+Normally when translating from terminfo to termcap,
+untranslatable capabilities are commented-out.
+.TP 5
+\fB\-U\fP
+tells \fBinfocmp\fP to not post-process the data
+after parsing the source file.
+This feature helps when comparing the actual contents of two source files,
+since it excludes the inferences that \fBinfocmp\fP makes to fill in missing
+data.
+.TP 5
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
+.TP 5
+\fB\-v\fP \fIn\fP
+prints out tracing information on standard error as the program runs.
+.IP
+The optional parameter \fIn\fP is a number from 1 to 10, inclusive,
+indicating the desired level of detail of information.
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
+.TP
+\fB\-W\fP
+By itself, the \fB\-w\fP option will not force long strings to be wrapped.
+Use the \fB\-W\fP option to do this.
+.TP 5
+\fB\-w\fP \fIwidth\fP
+changes the output to \fIwidth\fP characters.
+.TP
+\fB\-x\fP
+print information for user-defined capabilities (see \fBuser_caps\fP(5).
+These are extensions to the terminfo repertoire which can be loaded
+using the \fB\-x\fP option of \fBtic\fP.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH EXTENSIONS
+The
+\fB\-0\fP,
+\fB\-1\fP,
+\fB\-E\fP,
+\fB\-F\fP,
+\fB\-G\fP,
+\fB\-Q\fP,
+\fB\-R\fP,
+\fB\-T\fP,
+\fB\-V\fP,
+\fB\-a\fP,
+\fB\-e\fP,
+\fB\-f\fP,
+\fB\-g\fP,
+\fB\-i\fP,
+\fB\-l\fP,
+\fB\-p\fP,
+\fB\-q\fP and
+\fB\-t\fP
+options are not supported in SVr4 curses.
+.PP
+SVr4 infocmp does not distinguish between absent and cancelled capabilities.
+Also, it shows missing integer capabilities as \fB\-1\fP
+(the internal value used to represent missing integers).
+This implementation shows those as \*(``NULL\*('',
+for consistency with missing strings.
+.PP
+The \fB\-r\fP option's notion of \*(``termcap\*('' capabilities
+is System V Release 4's.
+Actual BSD curses versions will have a more restricted set.
+To see only the
+4.4BSD set, use \fB\-r\fP \fB\-RBSD\fP.
+.SH PORTABILITY
+X/Open Curses, Issue 7 (2009) provides a description of \fBinfocmp\fP.
+It does not mention the options used for converting to termcap format.
+.SH HISTORY
+Although System V Release 2 provided a terminfo library,
+it had no documented tool for decompiling the terminal descriptions.
+Tony Hansen (AT&T) wrote the first \fBinfocmp\fP in early 1984,
+for System V Release 3.
+.PP
+Eric Raymond used the AT&T documentation in 1995 to provide an equivalent
+\fBinfocmp\fP for \fI\%ncurses\fP.
+In addition, he added a few new features such as:
+.bP
+the \fB\-e\fP option, to support \fIfallback\fP
+(compiled-in) terminal descriptions
+.bP
+the \fB\-i\fP option, to help with analysis
+.PP
+Later, Thomas Dickey added the \fB\-x\fP (user-defined capabilities)
+option, and the \fB\-E\fP option to support fallback entries with
+user-defined capabilities.
+.PP
+For a complete list, see the \fIEXTENSIONS\fP section.
+.PP
+In 2010, Roy Marples provided an \fBinfocmp\fP program for NetBSD.
+It is less capable than the SVr4 or \fI\%ncurses\fP versions
+(e.g., it lacks the sorting options documented in X/Open),
+but does include the \fB\-x\fP option adapted from \fI\%ncurses\fP.
+.SH BUGS
+The \fB\-F\fP option of \fB\%infocmp\fP(1M) should be a
+\fB\%toe\fP(1M) mode.
+.SH AUTHORS
+Eric S. Raymond <esr@snark.thyrsus.com>
+and
+.br
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%captoinfo\fP(1M),
+\fB\%infotocap\fP(1M),
+\fB\%tic\fP(1M),
+\fB\%toe\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
+.PP
+https://invisible\-island.net/ncurses/tctest.html
diff --git a/upstream/mageia-cauldron/man1/infotocap.1m b/upstream/mageia-cauldron/man1/infotocap.1m
new file mode 100644
index 00000000..fd3f1d44
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/infotocap.1m
@@ -0,0 +1,97 @@
+.\"***************************************************************************
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 1999-2010,2016 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: infotocap.1m,v 1.39 2023/12/10 14:12:43 tom Exp $
+.TH infotocap 1M 2023-12-10 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.ds d /usr/share/terminfo
+.SH NAME
+\fB\%infotocap\fP \-
+convert a \fI\%terminfo\fR description into a \fI\%termcap\fR description
+.SH SYNOPSIS
+.B infotocap
+.RI [ tic-option ]
+.I file
+\&.\|.\|.
+.P
+.B "infotocap \-V"
+.SH DESCRIPTION
+\fB\%infotocap\fP translates terminal descriptions.
+It looks in each given text \fIfile\fP for \fI\%terminfo\fP entries and,
+For each one found,
+it writes an analogous \fI\%termcap\fP description to the standard
+output stream.
+\fI\%terminfo\fP \*(``\fBuse\fP\*('' capabilities translate to
+\fI\%termcap\fP \fBtc\fP capabilities.
+Because \fI\%termcap\fP is a less expressive format than
+\fI\%terminfo\fP,
+some capabilities cannot be translated.
+.PP
+This utility is implemented as a link to \fB\%tic\fP(1M),
+with the latter's
+.B \-C
+option implied.
+You can use other \fB\%tic\fP options such as
+.BR \-1 ,
+.BR \-f ,
+.BR \-v ,
+.BR \-w ,
+and
+.BR \-x .
+The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH PORTABILITY
+None of X/Open Curses,
+Issue 7 (2009),
+SVr4,
+or NetBSD document this application.
+.SH AUTHORS
+Eric S. Raymond <esr@snark.thyrsus.com>
+and
+.br
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%infocmp\fP(1M),
+\fB\%tic\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/infotopam.1 b/upstream/mageia-cauldron/man1/infotopam.1
new file mode 100644
index 00000000..00a6bc46
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/infotopam.1
@@ -0,0 +1,247 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Infotopam User Manual" 0 "07 April 2004" "netpbm documentation"
+
+.SH NAME
+infotopam - convert Amiga .info icons to PAM
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBinfotopam\fP
+[\fB-forcecolor\fP]
+[\fB-numcolors\fP \fInumcolors\fP]
+[\fB-selected\fP]
+[\fIindex color\fP ...]
+[\fIfilename\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white space in
+place of the equals sign to separate an option name from its value.
+
+.UN examples
+.SH EXAMPLES
+.PP
+By default, \fBinfotopam\fP converts the first icon in a .info file:
+
+.nf
+    infotopam amiga.info > amiga.first.pam
+
+.fi
+.PP
+Use the \fI-selected\fP option to convert the second icon in a .info
+file.  Here \fBinfotopam\fP reads from Standard Input:
+
+.nf
+    infotopam -selected < amiga.info > amiga.second.pam
+
+.fi
+.PP
+Use the \fI-forcecolor\fP option to force color conversion for a 1
+bit-plane .info file:
+
+.nf
+    infotopam -forcecolor bw.info > bw.pam
+
+.fi
+.PP
+Use \fI-numcolors\fP to override colors for indexes 0 and 3.  Notice the
+two ways to specify the color:
+
+.nf
+    infotopam -numcolors 2 0 green 3 #FF0000 icon.info > icon.pam
+
+.fi
+.PP
+Since Amiga monitors do not use square pixels, some icons may appear
+squished.  Filtering the output through \fBpamscale\fP can fix this:
+
+.nf
+     infotopam squish.info | pamtopnm | pamscale -yscale 1.7 > normal.pnm
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBinfotopam\fP converts an Amiga .info (icon) file to a PAM image.
+\fBinfotopam\fP reads a .info file from \fIfilename\fP, or from Standard
+Input if you do not specify a file name, and writes the converted PAM image to
+Standard Output.
+.PP
+\fBinfotopam\fP currently handles 1 and 2 bit-plane icons.  If the .info
+icon only has 1 bit-plane, \fBinfotopam\fP generates a bitmap
+(black&white) PAM image; otherwise it generates a color PAM image.  You
+can force \fBinfotopam\fP to convert 1 bit-plane images to color PAM images by
+using the \fI-forcecolor\fP option.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBinfotopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-forcecolor\fP
+
+  
+.sp
+Forces \fBinfotopam\fP to convert 1 bit-plane icons to color PAM
+  images instead of bitmap PAM images.  \fBinfotopam\fP uses the index 2
+  color for black and the index 1 color for white (more on this
+  below).
+
+.TP
+\fB-numcolors\fP \fInumcolors\fP
+
+  
+.sp
+Tells \fBinfotopam\fP how many colors to override.  Pixels in the
+  Amiga .info files are assigned an index value rather than a specific color.
+  The standard colors for a 2 bit-plane icon are:
+
+.nf
+    Index 0:  Blue   (00, 55, AA)
+    Index 1:  White  (FF, FF, FF)
+    Index 2:  Black  (00, 00, 20)
+    Index 3:  Orange (FF, 8A, 00)
+
+.fi
+.sp
+To override the colors, first specify how many colors to override using
+  \fI-numcolors\fP, then specify an (\fIindex color\fP) pair for each color
+  you want to override, where \fIindex\fP is a value from 0 to 3 and
+  \fIcolor\fP the new color for that index.  Specify \fIcolor\fP as
+  described for the 
+.UR libnetpbm_image.html#colorname
+\fBpnm_parsecolor()\fP   argument
+.UE
+\&.
+
+.TP
+\fB-selected\fP
+
+  
+Tells \fBinfotopam\fP to convert the selected (second) icon instead of
+  the normal (first) icon.  Each Amiga .info icon file contains two icon
+  images.  The first image is the normal, unselected icon, and the second
+  image is the selected icon.  By default \fBinfotopam\fP converts the first
+  icon.  You can tell \fBinfotopam\fP to convert the second icon by using the
+  \fI-selected\fP option.
+
+
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pam" (1)\c
+\&
+.BR "pamtopnm" (1)\c
+\&
+.BR "pamscale" (1)\c
+\&
+
+
+.UN notes
+.SH NOTES
+.PP
+Thanks to the following people on comp.sys.amiga.programmer for tips
+and pointers on decoding the info file format:
+
+
+.IP \(bu
+Ben Hutchings
+.IP \(bu
+Thomas Richter
+.IP \(bu
+Kjetil Svalastog Matheussen
+.IP \(bu
+Anders Melchiorsen
+.IP \(bu
+Dirk Stoecker
+.IP \(bu
+Ronald V.D.
+
+.PP
+The format of the Amiga .info file is as follows:
+
+.nf
+    DiskObject header            78 bytes
+    Optional DrawerData header   56 bytes
+    First icon header            20 bytes
+    First icon data              Varies
+    Second icon header           20 bytes
+    Second icon data             Varies  
+
+.fi
+.PP
+The DiskObject header contains, among other things, the magic number
+(0xE310), the object width and height (inside the embedded Gadget header),
+and the version.
+.PP
+Each icon header contains the icon width and height, which can be smaller
+than the object width and height, and the number of bit-planes.
+.PP
+The icon data has the following format:
+
+.RS
+    
+.PP
+\fIBIT-PLANE\fP planes, each with \fIHEIGHT\fP rows of (\fIWIDTH\fP
+    +15) / 16 * 2 bytes length.
+.RE
+.PP
+So if you have a 9x3x2 icon, the icon data will look like this:
+
+.nf
+    aaaa aaaa a000 0000
+    aaaa aaaa a000 0000
+    aaaa aaaa a000 0000
+    bbbb bbbb b000 0000
+    bbbb bbbb b000 0000
+    bbbb bbbb b000 0000
+
+.fi
+.PP
+where \fIa\fP is a bit for the first bit-plane, \fIb\fP is a bit for the
+second bit-plane, and \fI0\fP is padding.  Thanks again to Ben Hutchings for
+his very helpful post!
+
+.UN history
+.SH HISTORY
+.PP
+\fBinfotopam\fP was new in Netpbm 10.22 (April 2004).
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBinfotopam\fP currently only handles 1 and 2 bit-plane icons.
+.PP
+There is no \fBpamtoinfo\fP command, since the .info files contain a lot
+more than just icon data, and mapping the colors would be difficult.
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2000, 2004 by Richard Griswold.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/infotopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/install.1 b/upstream/mageia-cauldron/man1/install.1
new file mode 100644
index 00000000..dd9cf20f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/install.1
@@ -0,0 +1,132 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH INSTALL "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+install \- copy files and set attributes
+.SH SYNOPSIS
+.B install
+[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,SOURCE DEST\/\fR
+.br
+.B install
+[\fI\,OPTION\/\fR]... \fI\,SOURCE\/\fR... \fI\,DIRECTORY\/\fR
+.br
+.B install
+[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY SOURCE\/\fR...
+.br
+.B install
+[\fI\,OPTION\/\fR]... \fI\,-d DIRECTORY\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+This install program copies files (often just compiled) into destination
+locations you choose.  If you want to download and install a ready\-to\-use
+package on a GNU/Linux system, you should instead be using a package manager
+like \fByum\fP(1) or \fBapt\-get\fP(1).
+.PP
+In the first three forms, copy SOURCE to DEST or multiple SOURCE(s) to
+the existing DIRECTORY, while setting permission modes and owner/group.
+In the 4th form, create all components of the given DIRECTORY(ies).
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-backup\fR[=\fI\,CONTROL\/\fR]
+make a backup of each existing destination file
+.TP
+\fB\-b\fR
+like \fB\-\-backup\fR but does not accept an argument
+.TP
+\fB\-c\fR
+(ignored)
+.TP
+\fB\-C\fR, \fB\-\-compare\fR
+compare content of source and destination files, and
+if no change to content, ownership, and permissions,
+do not modify the destination at all
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+treat all arguments as directory names; create all
+components of the specified directories
+.TP
+\fB\-D\fR
+create all leading components of DEST except the last,
+or all components of \fB\-\-target\-directory\fR,
+then copy SOURCE to DEST
+.TP
+\fB\-g\fR, \fB\-\-group\fR=\fI\,GROUP\/\fR
+set group ownership, instead of process' current group
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fI\,MODE\/\fR
+set permission mode (as in chmod), instead of rwxr\-xr\-x
+.TP
+\fB\-o\fR, \fB\-\-owner\fR=\fI\,OWNER\/\fR
+set ownership (super\-user only)
+.TP
+\fB\-p\fR, \fB\-\-preserve\-timestamps\fR
+apply access/modification times of SOURCE files
+to corresponding destination files
+.TP
+\fB\-s\fR, \fB\-\-strip\fR
+strip symbol tables
+.TP
+\fB\-\-strip\-program\fR=\fI\,PROGRAM\/\fR
+program used to strip binaries
+.TP
+\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+override the usual backup suffix
+.TP
+\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR
+copy all SOURCE arguments into DIRECTORY
+.TP
+\fB\-T\fR, \fB\-\-no\-target\-directory\fR
+treat DEST as a normal file
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print the name of each directory as it is created
+.TP
+\fB\-\-preserve\-context\fR
+preserve SELinux security context
+.TP
+\fB\-Z\fR
+set SELinux security context of destination
+file and each created directory to default type
+.TP
+\fB\-\-context\fR[=\fI\,CTX\/\fR]
+like \fB\-Z\fR, or if CTX is specified then set the
+SELinux or SMACK security context to CTX
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX.
+The version control method may be selected via the \fB\-\-backup\fR option or through
+the VERSION_CONTROL environment variable.  Here are the values:
+.TP
+none, off
+never make backups (even if \fB\-\-backup\fR is given)
+.TP
+numbered, t
+make numbered backups
+.TP
+existing, nil
+numbered if numbered backups exist, simple otherwise
+.TP
+simple, never
+always make simple backups
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/install>
+.br
+or available locally via: info \(aq(coreutils) install invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/instmodsh.1 b/upstream/mageia-cauldron/man1/instmodsh.1
new file mode 100644
index 00000000..d16e79f2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/instmodsh.1
@@ -0,0 +1,76 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "INSTMODSH 1"
+.TH INSTMODSH 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+instmodsh \- A shell to examine installed modules
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    instmodsh
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A little interface to ExtUtils::Installed to examine installed modules,
+validate your packlists and even create a tarball from an installed module.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+ExtUtils::Installed
diff --git a/upstream/mageia-cauldron/man1/intro.1 b/upstream/mageia-cauldron/man1/intro.1
new file mode 100644
index 00000000..38dd27ed
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/intro.1
@@ -0,0 +1,305 @@
+.\" Copyright (c) 2002 Andries Brouwer <aeb@cwi.nl>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH intro 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+intro \- introduction to user commands
+.SH DESCRIPTION
+Section 1 of the manual describes user commands and tools,
+for example, file manipulation tools, shells, compilers,
+web browsers, file and image viewers and editors, and so on.
+.SH NOTES
+Linux is a flavor of UNIX, and as a first approximation
+all user commands under UNIX work precisely the same under
+Linux (and FreeBSD and lots of other UNIX-like systems).
+.P
+Under Linux, there are GUIs (graphical user interfaces), where you
+can point and click and drag, and hopefully get work done without
+first reading lots of documentation.
+The traditional UNIX environment
+is a CLI (command line interface), where you type commands to
+tell the computer what to do.
+That is faster and more powerful,
+but requires finding out what the commands are.
+Below a bare minimum, to get started.
+.SS Login
+In order to start working, you probably first have to open a session by
+giving your username and password.
+The program
+.BR login (1)
+now starts a
+.I shell
+(command interpreter) for you.
+In case of a graphical login, you get a screen with menus or icons
+and a mouse click will start a shell in a window.
+See also
+.BR xterm (1).
+.SS The shell
+One types commands to the
+.IR shell ,
+the command interpreter.
+It is not built-in, but is just a program
+and you can change your shell.
+Everybody has their own favorite one.
+The standard one is called
+.IR sh .
+See also
+.BR ash (1),
+.BR bash (1),
+.BR chsh (1),
+.BR csh (1),
+.BR dash (1),
+.BR ksh (1),
+.BR zsh (1).
+.P
+A session might go like:
+.P
+.in +4n
+.EX
+.RB "knuth login: " aeb
+.RB "Password: " ********
+.RB "$ " date
+Tue Aug  6 23:50:44 CEST 2002
+.RB "$ " cal
+     August 2002
+Su Mo Tu We Th Fr Sa
+             1  2  3
+ 4  5  6  7  8  9 10
+11 12 13 14 15 16 17
+18 19 20 21 22 23 24
+25 26 27 28 29 30 31
+\&
+.RB "$ " ls
+bin  tel
+.RB "$ " "ls \-l"
+total 2
+drwxrwxr\-x   2 aeb       1024 Aug  6 23:51 bin
+\-rw\-rw\-r\-\-   1 aeb         37 Aug  6 23:52 tel
+.RB "$ " "cat tel"
+maja    0501\-1136285
+peter   0136\-7399214
+.RB "$ " "cp tel tel2"
+.RB "$ " "ls \-l"
+total 3
+drwxr\-xr\-x   2 aeb       1024 Aug  6 23:51 bin
+\-rw\-r\-\-r\-\-   1 aeb         37 Aug  6 23:52 tel
+\-rw\-r\-\-r\-\-   1 aeb         37 Aug  6 23:53 tel2
+.RB "$ " "mv tel tel1"
+.RB "$ " "ls \-l"
+total 3
+drwxr\-xr\-x   2 aeb       1024 Aug  6 23:51 bin
+\-rw\-r\-\-r\-\-   1 aeb         37 Aug  6 23:52 tel1
+\-rw\-r\-\-r\-\-   1 aeb         37 Aug  6 23:53 tel2
+.RB "$ " "diff tel1 tel2"
+.RB "$ " "rm tel1"
+.RB "$ " "grep maja tel2"
+maja    0501\-1136285
+$
+.EE
+.in
+.P
+Here typing Control-D ended the session.
+.P
+The
+.B $
+here was the command prompt\[em]it is the shell's way of indicating
+that it is ready for the next command.
+The prompt can be customized
+in lots of ways, and one might include stuff like username,
+machine name, current directory, time, and so on.
+An assignment PS1="What next, master? "
+would change the prompt as indicated.
+.P
+We see that there are commands
+.I date
+(that gives date and time), and
+.I cal
+(that gives a calendar).
+.P
+The command
+.I ls
+lists the contents of the current directory\[em]it tells you what
+files you have.
+With a
+.I \-l
+option it gives a long listing,
+that includes the owner and size and date of the file, and the
+permissions people have for reading and/or changing the file.
+For example, the file "tel" here is 37 bytes long, owned by aeb
+and the owner can read and write it, others can only read it.
+Owner and permissions can be changed by the commands
+.I chown
+and
+.IR chmod .
+.P
+The command
+.I cat
+will show the contents of a file.
+(The name is from "concatenate and print": all files given as
+parameters are concatenated and sent to "standard output"
+(see
+.BR stdout (3)),
+here
+the terminal screen.)
+.P
+The command
+.I cp
+(from "copy") will copy a file.
+.P
+The command
+.I mv
+(from "move"), on the other hand, only renames it.
+.P
+The command
+.I diff
+lists the differences between two files.
+Here there was no output because there were no differences.
+.P
+The command
+.I rm
+(from "remove") deletes the file, and be careful! it is gone.
+No wastepaper basket or anything.
+Deleted means lost.
+.P
+The command
+.I grep
+(from "g/re/p") finds occurrences of a string in one or more files.
+Here it finds Maja's telephone number.
+.SS Pathnames and the current directory
+Files live in a large tree, the file hierarchy.
+Each has a
+.I "pathname"
+describing the path from the root of the tree (which is called
+.IR / )
+to the file.
+For example, such a full pathname might be
+.IR /home/aeb/tel .
+Always using full pathnames would be inconvenient, and the name
+of a file in the current directory may be abbreviated by giving
+only the last component.
+That is why
+.I /home/aeb/tel
+can be abbreviated
+to
+.I tel
+when the current directory is
+.IR /home/aeb .
+.P
+The command
+.I pwd
+prints the current directory.
+.P
+The command
+.I cd
+changes the current directory.
+.P
+Try alternatively
+.I cd
+and
+.I pwd
+commands and explore
+.I cd
+usage: "cd", "cd .", "cd ..", "cd /", and "cd \[ti]".
+.SS Directories
+The command
+.I mkdir
+makes a new directory.
+.P
+The command
+.I rmdir
+removes a directory if it is empty, and complains otherwise.
+.P
+The command
+.I find
+(with a rather baroque syntax) will find files with given name
+or other properties.
+For example, "find . \-name tel" would find
+the file
+.I tel
+starting in the present directory (which is called
+.IR . ).
+And "find / \-name tel" would do the same, but starting at the root
+of the tree.
+Large searches on a multi-GB disk will be time-consuming,
+and it may be better to use
+.BR locate (1).
+.SS Disks and filesystems
+The command
+.I mount
+will attach the filesystem found on some disk (or floppy, or CDROM or so)
+to the big filesystem hierarchy.
+And
+.I umount
+detaches it again.
+The command
+.I df
+will tell you how much of your disk is still free.
+.SS Processes
+On a UNIX system many user and system processes run simultaneously.
+The one you are talking to runs in the
+.IR foreground ,
+the others in the
+.IR background .
+The command
+.I ps
+will show you which processes are active and what numbers these
+processes have.
+The command
+.I kill
+allows you to get rid of them.
+Without option this is a friendly
+request: please go away.
+And "kill \-9" followed by the number
+of the process is an immediate kill.
+Foreground processes can often be killed by typing Control-C.
+.SS Getting information
+There are thousands of commands, each with many options.
+Traditionally commands are documented on
+.IR "man pages" ,
+(like this one), so that the command "man kill" will document
+the use of the command "kill" (and "man man" document the command "man").
+The program
+.I man
+sends the text through some
+.IR pager ,
+usually
+.IR less .
+Hit the space bar to get the next page, hit q to quit.
+.P
+In documentation it is customary to refer to man pages
+by giving the name and section number, as in
+.BR man (1).
+Man pages are terse, and allow you to find quickly some forgotten
+detail.
+For newcomers an introductory text with more examples
+and explanations is useful.
+.P
+A lot of GNU/FSF software is provided with info files.
+Type "info info"
+for an introduction on the use of the program
+.IR info .
+.P
+Special topics are often treated in HOWTOs.
+Look in
+.I /usr/share/doc/howto/en
+and use a browser if you find HTML files there.
+.\"
+.\" Actual examples? Separate section for each of cat, cp, ...?
+.\" gzip, bzip2, tar, rpm
+.SH SEE ALSO
+.BR ash (1),
+.BR bash (1),
+.BR chsh (1),
+.BR csh (1),
+.BR dash (1),
+.BR ksh (1),
+.BR locate (1),
+.BR login (1),
+.BR man (1),
+.BR xterm (1),
+.BR zsh (1),
+.BR wait (2),
+.BR stdout (3),
+.BR man\-pages (7),
+.BR standards (7)
diff --git a/upstream/mageia-cauldron/man1/iostat.1 b/upstream/mageia-cauldron/man1/iostat.1
new file mode 100644
index 00000000..8272c92a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/iostat.1
@@ -0,0 +1,477 @@
+.\" iostat manual page - (C) 1998-2020 Sebastien Godard (sysstat <at> orange.fr)
+.TH IOSTAT 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+iostat \- Report Central Processing Unit (CPU) statistics and input/output
+statistics for devices and partitions.
+
+.SH SYNOPSIS
+.ie 'yes'no' \{
+.B iostat [ -c ] [ -d ] [ -h ] [ -k | -m ] [ -N ] [ -s ] [ -t ] [ -V ] [ -x ] [ -y ] [ -z ]
+.BI "[ --compact ] [ --dec={ 0 | 1 | 2 } ] [ { -f | +f } " "directory" " ] [ -j { ID | LABEL | PATH | UUID | ... } ] "
+.BI "[ -o JSON ] [ [ -H ] -g " "group_name " "] [ --human ] [ --pretty ] [ -p [ " "device" "[,...] | ALL ] ] ["
+.IB "device " "[...] | ALL ] [ --debuginfo ] [ " "interval " "[ " "count " "] ] "
+.\}
+.el \{
+.B iostat [ -c ] [ -d ] [ -h ] [ -k | -m ] [ -N ] [ -s ] [ -t ] [ -V ] [ -x ] [ -y ] [ -z ]
+.BI "[ --compact ] [ --dec={ 0 | 1 | 2 } ] [ { -f | +f } " "directory" " ] [ -j { ID | LABEL | PATH | UUID | ... } ] "
+.BI "[ -o JSON ] [ [ -H ] -g " "group_name " "] [ --human ] [ --pretty ] [ -p [ " "device" "[,...] | ALL ] ] ["
+.IB "device " "[...] | ALL ] [ " "interval " "[ " "count " "] ]"
+.\}
+
+.SH DESCRIPTION
+.RB "The " "iostat"
+command is used for monitoring system input/output device
+loading by observing the time the devices are active in relation
+to their average transfer rates. The
+.B iostat
+command generates reports
+that can be used to change system configuration to better balance
+the input/output load between physical disks.
+.PP
+The first report generated by the
+.B iostat
+command provides statistics
+concerning the time since the system was booted, unless the
+.B -y
+option is used (in this case, this first report is omitted).
+Each subsequent report
+covers the time since the previous report. All statistics are reported
+each time the
+.B iostat
+command is run. The report consists of a
+CPU header row followed by a row of
+CPU statistics. On
+multiprocessor systems, CPU statistics are calculated system-wide
+as averages among all processors. A device header row is displayed
+followed by a line of statistics for each device that is configured.
+.PP
+The
+.I interval
+parameter specifies the amount of time in seconds between
+each report. The
+.IR "count " "parameter can be specified in conjunction with the " "interval"
+.RI "parameter. If the " "count " "parameter is specified, the value of " "count"
+.RI "determines the number of reports generated at " "interval " "seconds apart. If the"
+.IR "interval " "parameter is specified without the " "count " "parameter, the"
+.B iostat
+command generates reports continuously.
+
+.SH REPORTS
+The
+.B iostat
+command generates two types of reports, the CPU
+Utilization report and the Device Utilization report.
+
+.IP "CPU Utilization Report"
+The first report generated by the
+.B iostat
+command is the CPU Utilization Report. For multiprocessor systems, the CPU values are
+global averages among all processors.
+The report has the following format:
+.RS
+.IP %user
+Show the percentage of CPU utilization that occurred while
+executing at the user level (application).
+.IP %nice
+Show the percentage of CPU utilization that occurred while
+executing at the user level with nice priority.
+.IP %system
+Show the percentage of CPU utilization that occurred while
+executing at the system level (kernel).
+.IP %iowait
+Show the percentage of time that the CPU or CPUs were idle during which
+the system had an outstanding disk I/O request.
+.IP %steal
+Show the percentage of time spent in involuntary wait by the virtual CPU
+or CPUs while the hypervisor was servicing another virtual processor.
+.IP %idle
+Show the percentage of time that the CPU or CPUs were idle and the system
+did not have an outstanding disk I/O request.
+.RE
+.PP
+.IP "Device Utilization Report"
+The second report generated by the
+.B iostat
+command is the Device Utilization Report.
+The device report provides statistics on a per physical device
+or partition basis. Block devices and partitions for which statistics are
+to be displayed may be entered on the command line.
+If no device nor partition is entered, then statistics are displayed
+for every device used by the system, and
+providing that the kernel maintains statistics for it.
+If the
+.B ALL
+keyword is given on the command line, then statistics are
+displayed for every device defined by the system, including those
+that have never been used.
+Transfer rates are shown in 1K blocks by default, unless the environment
+variable
+.B POSIXLY_CORRECT
+is set, in which case 512-byte blocks are used.
+The report may show the following fields, depending on the flags used (e.g.
+.BR "-x" ", " "-s " "and " "-k " "or " "-m" "):"
+.RS
+.IP Device:
+This column gives the device (or partition) name as listed in the
+.IR "/dev " "directory."
+.IP tps
+Indicate the number of transfers per second that were issued
+to the device. A transfer is an I/O request to the
+device. Multiple logical requests can be combined into a single I/O
+request to the device. A transfer is of indeterminate size.
+.IP "Blk_read/s (kB_read/s, MB_read/s)"
+Indicate the amount of data read from the device expressed in a number of
+blocks (kilobytes, megabytes) per second. Blocks are equivalent to sectors
+and therefore have a size of 512 bytes.
+.IP "Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s)"
+Indicate the amount of data written to the device expressed in a number of
+blocks (kilobytes, megabytes) per second.
+.IP "Blk_dscd/s (kB_dscd/s, MB_dscd/s)"
+Indicate the amount of data discarded for the device expressed in a number of
+blocks (kilobytes, megabytes) per second.
+.IP "Blk_w+d/s (kB_w+d/s, MB_w+d/s)"
+Indicate the amount of data written to or discarded for the device expressed
+in a number of blocks (kilobytes, megabytes) per second.
+.IP "Blk_read (kB_read, MB_read)"
+The total number of blocks (kilobytes, megabytes) read.
+.IP "Blk_wrtn (kB_wrtn, MB_wrtn)"
+The total number of blocks (kilobytes, megabytes) written.
+.IP "Blk_dscd (kB_dscd, MB_dscd)"
+The total number of blocks (kilobytes, megabytes) discarded.
+.IP "Blk_w+d (kB_w+d, MB_w+d)"
+The total number of blocks (kilobytes, megabytes) written or discarded.
+.IP r/s
+The number (after merges) of read requests completed per second for the device.
+.IP w/s
+The number (after merges) of write requests completed per second for the device.
+.IP d/s
+The number (after merges) of discard requests completed per second for the device.
+.IP f/s
+The number (after merges) of flush requests completed per second for the device.
+This counts flush requests executed by disks. Flush requests are not tracked for partitions.
+Before being merged, flush operations are counted as writes.
+.IP "sec/s (kB/s, MB/s)"
+The number of sectors (kilobytes, megabytes) read from, written to or
+discarded for the device per second.
+.IP "rsec/s (rkB/s, rMB/s)"
+The number of sectors (kilobytes, megabytes) read from the device per second.
+.IP "wsec/s (wkB/s, wMB/s)"
+The number of sectors (kilobytes, megabytes) written to the device per second.
+.IP "dsec/s (dkB/s, dMB/s)"
+The number of sectors (kilobytes, megabytes) discarded for the device per second.
+.IP rqm/s
+The number of I/O requests merged per second that were queued to the device.
+.IP rrqm/s
+The number of read requests merged per second that were queued to the device.
+.IP wrqm/s
+The number of write requests merged per second that were queued to the device.
+.IP drqm/s
+The number of discard requests merged per second that were queued to the device.
+.IP %rrqm
+The percentage of read requests merged together before being sent to the device.
+.IP %wrqm
+The percentage of write requests merged together before being sent to the device.
+.IP %drqm
+The percentage of discard requests merged together before being sent to the device.
+.IP areq-sz
+The average size (in kilobytes) of the I/O requests that were issued to the device.
+.br
+Note: In previous versions, this field was known as avgrq-sz and was expressed in sectors.
+.IP rareq-sz
+The average size (in kilobytes) of the read requests that were issued to the device.
+.IP wareq-sz
+The average size (in kilobytes) of the write requests that were issued to the device.
+.IP dareq-sz
+The average size (in kilobytes) of the discard requests that were issued to the device.
+.IP await
+The average time (in milliseconds) for I/O requests issued to the device
+to be served. This includes the time spent by the requests in queue and
+the time spent servicing them.
+.IP r_await
+The average time (in milliseconds) for read requests issued to the device
+to be served. This includes the time spent by the requests in queue and
+the time spent servicing them.
+.IP w_await
+The average time (in milliseconds) for write requests issued to the device
+to be served. This includes the time spent by the requests in queue and
+the time spent servicing them.
+.IP d_await
+The average time (in milliseconds) for discard requests issued to the device
+to be served. This includes the time spent by the requests in queue and
+the time spent servicing them.
+.IP f_await
+The average time (in milliseconds) for flush requests issued to the device
+to be served.
+The block layer combines flush requests and executes at most one at a time.
+Thus flush operations could be twice as long: Wait for current flush request,
+then execute it, then wait for the next one.
+.IP aqu-sz
+The average queue length of the requests that were issued to the device.
+.br
+Note: In previous versions, this field was known as avgqu-sz.
+.IP %util
+Percentage of elapsed time during which I/O requests were issued to the device
+(bandwidth utilization for the device). Device saturation occurs when this
+value is close to 100% for devices serving requests serially.
+But for devices serving requests in parallel, such as RAID arrays and
+modern SSDs, this number does not reflect their performance limits.
+.RE
+
+.SH OPTIONS
+.TP
+.B -c
+Display the CPU utilization report.
+.TP
+.B --compact
+Don't break the Device Utilization Report into sub-reports so that all the metrics get displayed
+on a single line.
+.TP
+.B -d
+Display the device utilization report.
+.if 'yes'no' \{
+.TP
+.B --debuginfo
+Print debug output to stderr.
+.\}
+.TP
+.B --dec={ 0 | 1 | 2 }
+Specify the number of decimal places to use (0 to 2, default value is 2).
+.TP
+.BI "-f " "directory"
+.RE
+.BI "+f " "directory"
+.RS
+Specify an alternative directory for
+.B iostat
+to read devices statistics. Option
+.BR "-f " "tells " "iostat " "to use only the files located in the alternative directory, "
+whereas option
+.B +f
+tells it to use both the standard kernel files and the files located in the alternative directory
+to read device statistics.
+
+.IR "directory" " is a directory containing files with statistics for devices managed in userspace."
+It may contain:
+
+- a "diskstats" file whose format is compliant with that located in "/proc",
+.br
+- statistics for individual devices contained in files whose format is compliant with that of files located in
+"/sys".
+
+In particular, the following files located in
+.I "directory"
+.RB "may be used by " "iostat" ":"
+
+.IR "directory" "/block/" "device" "/stat"
+.br
+.IR "directory" "/block/" "device" "/" "partition" "/stat"
+
+.IR "partition" " files must have an entry in " "directory" "/dev/block/ directory, e.g.:"
+
+.IR "directory" "/dev/block/" "major" ":" "minor" " --> ../../block/" "device" "/" "partition"
+.RE
+.TP
+.BI "-g " "group_name " "{ " "device " "[...] | ALL }"
+Display statistics for a group of devices.
+The
+.B iostat
+command reports statistics for each individual device in the list
+then a line of global statistics for the group displayed as
+.I group_name
+and made up of all the devices in the list. The
+.B ALL
+keyword means that all the block devices defined by the system shall be
+included in the group.
+.TP
+.B -H
+This option must be used with option
+.B -g
+and indicates that only global
+statistics for the group are to be displayed, and not statistics for
+individual devices in the group.
+.TP
+.B -h
+This option is equivalent to specifying
+.BR "--human --pretty" "."
+.TP
+.B --human
+Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
+The units displayed with this option supersede any other default units (e.g.
+kilobytes, sectors...) associated with the metrics.
+.TP
+.BI "-j { ID | LABEL | PATH | UUID | ... } [ " "device " "[...] | ALL ]"
+Display persistent device names. Keywords
+.BR "ID" ", " "LABEL" ", "
+etc. specify the type of the persistent name. These keywords are not limited,
+only prerequisite is that directory with required persistent names is present in
+.IR "/dev/disk" "."
+Optionally, multiple devices can be specified in the chosen persistent name type.
+Because persistent device names are usually long, option
+.B --pretty
+is implicitly set with this option.
+.TP
+.B -k
+Display statistics in kilobytes per second.
+.TP
+.B -m
+Display statistics in megabytes per second.
+.TP
+.B -N
+Display the registered device mapper names for any device mapper devices.
+Useful for viewing LVM2 statistics.
+.TP
+.B -o JSON
+Display the statistics in JSON (JavaScript Object Notation) format.
+JSON output field order is undefined, and new fields may be added
+in the future.
+.TP
+.BI "-p [ { " "device" "[,...] | ALL } ]"
+Display statistics for
+block devices and all their partitions that are used by the system.
+If a device name is entered on the command line, then statistics for it
+and all its partitions are displayed. Last, the
+.B ALL
+keyword indicates that statistics have to be displayed for all the block
+devices and partitions defined by the system, including those that have
+never been used. If option
+.B -j
+is defined before this option, devices entered on the command line can be
+specified with the chosen persistent name type.
+.TP
+.B --pretty
+Make the Device Utilization Report easier to read by a human.
+The device name will be printed on the right side. The report may also be broken
+into sub-reports if there are many metrics to display (use
+.B --compact
+option to prevent this).
+.TP
+.B -s
+Display a short (narrow) version of the report that should fit in 80
+characters wide screens.
+.TP
+.B -t
+Print the time for each report displayed. The timestamp format may depend
+on the value of the
+.BR "S_TIME_FORMAT " "environment variable (see below)."
+.TP
+.B -V
+Print version number then exit.
+.TP
+.B -x
+Display extended statistics.
+.TP
+.B -y
+Omit first report with statistics since system boot, if displaying
+multiple records at given interval.
+.TP
+.B -z
+Tell
+.B iostat
+to omit output for any devices for which there was no activity
+during the sample period.
+
+.SH ENVIRONMENT
+The
+.B iostat
+command takes into account the following environment variables:
+.TP
+.B POSIXLY_CORRECT
+When this variable is set, transfer rates are shown in 512-byte blocks instead
+of the default 1K blocks.
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.IR "never" ", " "always " "or " "auto"
+(the latter is equivalent to the default settings).
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B I=
+SGR (Select Graphic Rendition) substring for device names.
+.TP
+.B N=
+SGR substring for non-zero statistics values.
+.TP
+.BR "W=" " (or " "M=" ")"
+SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
+metric's meaning).
+.TP
+.BR "X=" " (or " "H=" ")"
+SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
+metric's meaning).
+.TP
+.B Z=
+SGR substring for zero values.
+.RE
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.B ISO
+then the current locale will be ignored when printing the date in the report
+header. The
+.B iostat
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+The timestamp displayed with option
+.B -t
+will also be compliant with ISO 8601 format.
+
+.SH EXAMPLES
+.TP
+.B iostat
+Display a single history since boot report for all CPU and Devices.
+.TP
+.B iostat -d 2
+Display a continuous device report at two second intervals.
+.TP
+.B iostat -d 2 6
+Display six reports at two second intervals for all devices.
+.TP
+.B iostat -x sda sdb 2 6
+Display six reports of extended statistics at two second intervals for devices
+sda and sdb.
+.TP
+.B iostat -p sda 2 6
+Display six reports at two second intervals for device sda and all its
+partitions (sda1, etc.)
+
+.SH BUGS
+.IR "/proc " "filesystem must be mounted for"
+.BR "iostat " "to work."
+.PP
+Kernels older than 2.6.x are no longer supported.
+.PP
+.RB "Although " "iostat"
+speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
+A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
+
+.SH FILES
+.IR "/proc/stat " "contains system statistics."
+.br
+.IR "/proc/uptime " "contains system uptime."
+.br
+.IR "/proc/diskstats " "contains disks statistics."
+.br
+.IR "/sys " "contains statistics for block devices."
+.br
+.IR "/proc/self/mountstats " "contains statistics for network filesystems."
+.br
+.IR "/dev/disk " "contains persistent device names."
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "tapestat" "(1), " "nfsiostat" "(1),"
+.BR "cifsiostat" "(1)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/iptables-xml.1 b/upstream/mageia-cauldron/man1/iptables-xml.1
new file mode 100644
index 00000000..e5a8aa3e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/iptables-xml.1
@@ -0,0 +1,87 @@
+.TH IPTABLES-XML 1 "" "iptables 1.8.9" "iptables 1.8.9"
+.\"
+.\" Man page written by Sam Liddicott <azez@ufomechanic.net>
+.\" It is based on the iptables-save man page.
+.\"
+.\"	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 2 of the License, or
+.\"	(at your option) any later version.
+.\"
+.\"	This program is distributed in the hope that it will be useful,
+.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"	GNU General Public License for more details.
+.\"
+.\"	You should have received a copy of the GNU General Public License
+.\"	along with this program; if not, write to the Free Software
+.\"	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+.\"
+.\"
+.SH NAME
+iptables-xml \(em Convert iptables-save format to XML
+.SH SYNOPSIS
+\fBiptables\-xml\fP [\fB\-c\fP] [\fB\-v\fP]
+.SH DESCRIPTION
+.PP
+.B iptables-xml
+is used to convert the output of iptables-save into an easily manipulatable
+XML format to STDOUT.  Use I/O-redirection provided by your shell to write to 
+a file.
+.TP
+\fB\-c\fR, \fB\-\-combine\fR
+combine consecutive rules with the same matches but different targets. iptables
+does not currently support more than one target per match, so this simulates 
+that by collecting the targets from consecutive iptables rules into one action
+tag, but only when the rule matches are identical. Terminating actions like
+RETURN, DROP, ACCEPT and QUEUE are not combined with subsequent targets.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Output xml comments containing the iptables line from which the XML is derived
+
+.PP
+iptables-xml does a mechanistic conversion to a very expressive xml
+format; the only semantic considerations are for \-g and \-j targets in
+order to discriminate between <call> <goto> and <nane-of-target> as it
+helps xml processing scripts if they can tell the difference between a
+target like SNAT and another chain.
+
+Some sample output is:
+
+<iptables-rules>
+  <table name="mangle">
+    <chain name="PREROUTING" policy="ACCEPT" packet-count="63436"
+byte-count="7137573">
+      <rule>
+       <conditions>
+        <match>
+          <p>tcp</p>
+        </match>
+        <tcp>
+          <sport>8443</sport>
+        </tcp>
+       </conditions>
+       <actions>
+        <call>
+          <check_ip/>
+        </call>
+        <ACCEPT/>
+       </actions>
+      </rule>
+    </chain>
+  </table>
+</iptables-rules>
+
+.PP
+Conversion from XML to iptables-save format may be done using the 
+iptables.xslt script and xsltproc, or a custom program using
+libxsltproc or similar; in this fashion:
+
+xsltproc iptables.xslt my-iptables.xml | iptables-restore
+
+.SH BUGS
+None known as of iptables-1.3.7 release
+.SH AUTHOR
+Sam Liddicott <azez@ufomechanic.net>
+.SH SEE ALSO
+\fBiptables\-save\fP(8), \fBiptables\-restore\fP(8), \fBiptables\fP(8)
diff --git a/upstream/mageia-cauldron/man1/isodebug.1 b/upstream/mageia-cauldron/man1/isodebug.1
new file mode 100644
index 00000000..58f0d9d3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/isodebug.1
@@ -0,0 +1,108 @@
+.\" @(#)isodebug.8	1.1 06/02/08 Copyr 2006 J. Schilling
+.\" Manual page for isodebug
+.\" Modified for cdrkit distribution by E.Bloch
+.\"
+.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
+.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
+.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
+.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
+.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
+.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U
+.if t .ds s \\(*b
+.if t .ds S SS
+.if n .ds a ae
+.if n .ds o oe
+.if n .ds u ue
+.if n .ds s sz
+.TH ISODEBUG 1 "06/02/08" "J\*org Schilling" "Schily\'s USER COMMANDS"
+.SH NAME
+isodebug \- print genisoimage debug info from ISO-9660 image
+.SH SYNOPSIS
+.B
+isodebug
+[
+.I options
+]
+[
+.I file
+]
+.SH DESCRIPTION
+.B Isodebug
+reads the debug info written by 
+.BR genisoimage (8)
+from within a ISO-9660 file system image and prints them.
+. \" .SH RETURNS
+. \" .SH ERRORS
+.SH OPTIONS
+.TP
+.B \-help
+Prints a short summary of the 
+.B isodebug
+options and exists.
+.TP
+.B \-version
+Prints the 
+.B isodebug
+version number string and exists.
+.TP
+.BI \-i " filename
+Filename to read ISO-9660 image from.
+.TP
+.BI dev= target
+SCSI target to use as CD/DVD-Recorder.
+See
+.BR wodim (1)
+for more information on now to use this option.
+.SH FILES
+.SH "SEE ALSO"
+.BR wodim (1),
+.BR genisoimage (1).
+.SH AUTHOR
+.nf
+J\*org Schilling
+Seestr. 110
+D-13353 Berlin
+Germany
+.fi
+.PP
+
+
+.SH AUTHOR
+.nf
+J\*org Schilling
+Seestr. 110
+D-13353 Berlin
+Germany
+.fi
+
+.PP
+This manpage describes the program implementation of
+.B
+isodebug
+as shipped by the cdrkit distribution. See
+.B
+http://alioth.debian.org/projects/debburn/
+for details. It is a spinoff from the original program distributed in the
+cdrtools package [1]. However, the cdrtools developers are not
+involved in the development of this spinoff and therefore shall not be made
+responsible for any problem caused by it. Do not try to get support for this
+program by contacting the original author(s).
+.PP
+If you have support questions, send them to
+.PP
+.B
+debburn-devel@lists.alioth.debian.org
+.br
+.PP
+If you have definitely found a bug, send a mail to this list or to
+.PP
+.B
+submit@bugs.debian.org
+.br
+.PP
+writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body.
+.PP
+.br
+[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de
+
+
diff --git a/upstream/mageia-cauldron/man1/isoinfo.1 b/upstream/mageia-cauldron/man1/isoinfo.1
new file mode 100644
index 00000000..1a00540a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/isoinfo.1
@@ -0,0 +1,365 @@
+.\"
+.\" @(#)isoinfo.8	1.7 04/06/01 joerg
+.\" 
+.\" Modified for cdrkit in 12/2006
+.\"
+.\" -*- nroff -*-
+.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
+.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
+.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
+.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
+.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
+.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U
+.if t .ds s \\(*b
+.if t .ds S SS
+.if n .ds a ae
+.if n .ds o oe
+.if n .ds u ue
+.if n .ds s sz
+.TH ISOINFO 1 "04/06/01" "Version 2.0"
+.SH NAME
+devdump, isoinfo, isovfy, isodump \- Utility programs for dumping and verifying iso9660
+images.
+.SH SYNOPSIS
+.B devdump 
+.I isoimage
+.PP
+.B isodump 
+.I isoimage
+.PP
+.B isoinfo
+[
+.B \-d
+]
+[
+.B \-h
+]
+[
+.B \-R
+]
+[
+.B \-J
+]
+[
+.B \-j
+.I charset
+]
+[
+.B \-f
+]
+[
+.B \-l
+]
+[
+.B \-p
+]
+[
+.B \-T
+.I sector
+]
+[
+.B \-N
+.I sector
+]
+[
+.B \-i
+.I isoimage
+]
+[
+.B \-x
+.I path
+]
+.PP
+.B isovfy 
+.I isoimage
+.SH DESCRIPTION
+.B devdump
+is a crude utility to interactively display the contents of device or
+filesystem images.
+The initial screen is a display of the first 256 bytes of the first 2048 byte
+sector.
+The commands are the same as with 
+.BR isodump .
+.PP
+.B isodump
+is a crude utility to interactively display the contents of iso9660 images
+in order to verify directory integrity.
+The initial screen is a display of the first part of the root directory,
+and the prompt shows you the extent number and offset in the extent.
+.RS
+.PP
+You can use the 'a' and 'b'
+commands to move backwards and forwards within the image. The 'g' command
+allows you to goto an arbitrary extent, and the 'f' command specifies
+a search string to be used. The '+' command searches forward for the next
+instance of the search string, and the 'q' command exits
+.B devdump
+or
+.BR isodump .
+.RE
+.PP
+.B isoinfo
+is a utility to perform directory like listings of iso9660 images.
+.PP
+.B isovfy
+is a utility to verify the integrity of an iso9660 image. Most of the tests
+in
+.B isovfy
+were added after bugs were discovered in early versions of
+.B genisoimage.
+It isn't all that clear how useful this is anymore, but it doesn't hurt to
+have this around.
+
+.SH OPTIONS
+The options common to all programs are
+.BR \-help , \-h , \-version ,
+.BI i =name, dev =name.
+The
+.B isoinfo
+program has additional command line options. The options are:
+.TP
+.B \-help
+.TP
+.B \-h
+print a summary of all options.
+.TP
+.B \-d
+Print information from the primary volume descriptor (PVD) of the iso9660
+image. This includes information about Rock Ridge, Joliet extensions
+and Eltorito boot information
+if present.
+.TP
+.B \-f
+generate output as if a 'find . -print' command had been run on the iso9660
+image. You should not use the
+.B -l
+image with the
+.B -f
+option.
+.TP
+.B \-i iso_image
+Specifies the path of the iso9660 image that we wish to examine.
+The options
+.B \-i
+and 
+.BI dev= target
+are mutual exclusive.
+.TP
+.BI dev= target
+Sets the SCSI target for the drive, see notes above.
+A typical device specification is
+.BI dev= 6,0
+\&.
+If a filename must be provided together with the numerical target 
+specification, the filename is implementation specific.
+The correct filename in this case can be found in the system specific
+manuals of the target operating system.
+On a 
+.I FreeBSD
+system without 
+.I CAM
+support, you need to use the control device (e.g.
+.IR /dev/rcd0.ctl ).
+A correct device specification in this case may be
+.BI dev= /dev/rcd0.ctl:@
+\&.
+.sp
+On Linux, drives connected to a parallel port adapter are mapped
+to a virtual SCSI bus. Different adapters are mapped to different
+targets on this virtual SCSI bus.
+.sp
+If no 
+.I dev
+option is present, the program
+will try to get the device from the 
+.B CDR_DEVICE
+environment.
+.sp
+If the argument to the
+.B dev=
+option does not contain the characters ',', '/', '@' or ':',
+it is interpreted as an label name that may be found in the file
+/etc/wodim.conf (see FILES section).
+.sp
+The options
+.B \-i
+and 
+.BI dev= target
+are mutual exclusive.
+.TP
+.B \-l
+generate output as if a 'ls -lR' command had been run on the iso9660 image.
+You should not use the
+.B -f
+image with the
+.B -l
+option.
+.TP
+.B \-N sector
+Quick hack to help examine single session disc files that are to be written to
+a multi-session disc. The sector number specified is the sector number at
+which the iso9660 image should be written when send to the cd-writer. Not
+used for the first session on the disc.
+.TP
+.B \-p
+Print path table information.
+.TP
+.B \-R
+Extract information from Rock Ridge extensions (if present) for permissions,
+file names and ownerships.
+.TP
+.B \-J
+Extract information from Joliet extensions (if present) for file names.
+.TP
+.B \-j charset
+Convert Joliet file names (if present) to the supplied charset. See
+.BR genisoimage (8)
+for details.
+.TP
+.B \-T sector
+Quick hack to help examine multi-session images that have already been burned
+to a multi-session disc. The sector number specified is the sector number for
+the start of the session we wish to display.
+.TP
+.B \-x pathname
+Extract specified file to stdout.
+.SH AUTHOR
+The author of the original sources (1993 .\|.\|. 1998) is
+Eric Youngdale <ericy@gnu.ai.mit.edu> or <eric@andante.jic.com> is to blame
+for these shoddy hacks.
+J\*org Schilling wrote the SCSI transport library and its adaptation layer to
+the programs and newer parts (starting from 1999) of the utilities, this makes
+them
+Copyright (C) 1999-2004 J\*org Schilling.
+Patches to improve general usability would be gladly accepted.
+.PP
+This manpage describes the program implementation of
+.B
+isoinfo
+as shipped by the cdrkit distribution. See
+.B
+http://alioth.debian.org/projects/debburn/
+for details. It is a spinoff from the original program distributed in the
+cdrtools package [1]. However, the cdrtools
+developers are not involved in the development of this spinoff and therefore
+shall not be made responsible for any problem caused by it. Do not try to get
+support for this program by contacting the original author(s).
+.PP
+If you have support questions, send them to
+.PP
+.B
+debburn-devel@lists.alioth.debian.org
+.br
+.PP
+If you have definitely found a bug, send a mail to this list or to
+.PP
+.B
+submit@bugs.debian.org
+.br
+.PP
+writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body.
+.SH BUGS
+The user interface really sucks.
+.SH FUTURE IMPROVEMENTS
+These utilities are really quick hacks, which are very useful for debugging
+problems in genisoimage or in an iso9660 filesystem. In the long run, it would
+be nice to have a daemon that would NFS export a iso9660 image.
+.PP
+The isoinfo program is probably the program that is of the most use to
+the general user.
+.SH AVAILABILITY
+These utilities come with the 
+.B cdrkit
+package, and the primary download site
+is http://debburn.alioth.debian.org/ and FTP mirrors of distributions.
+Despite the name, the software is not beta.
+
+.SH ENVIRONMENT
+.TP
+.B CDR_DEVICE
+This may either hold a device identifier that is suitable to the open
+call of the SCSI transport library or a label in the file /etc/wodim.conf.
+.TP
+.B RSH
+If the 
+.B RSH
+environment is present, the remote connection will not be created via
+.BR rcmd (3)
+but by calling the program pointed to by
+.BR RSH .
+Use e.g. 
+.BR RSH= /usr/bin/ssh
+to create a secure shell connection.
+.sp
+Note that this forces the program
+to create a pipe to the 
+.B rsh(1)
+program and disallows the program
+to directly access the network socket to the remote server.
+This makes it impossible to set up performance parameters and slows down
+the connection compared to a 
+.B root
+initiated
+.B rcmd(3)
+connection.
+.TP
+.B RSCSI
+If the 
+.B RSCSI
+environment is present, the remote SCSI server will not be the program
+.B /opt/schily/sbin/rscsi
+but the program pointed to by
+.BR RSCSI .
+Note that the remote SCSI server program name will be ignored if you log in
+using an account that has been created with a remote SCSI server program as
+login shell.
+
+.SH FILES
+.TP
+/etc/wodim.conf
+Default values can be set for the following options in /etc/wodim.conf.
+.RS
+.TP
+CDR_DEVICE
+This may either hold a device identifier that is suitable to the open
+call of the SCSI transport library or a label in the file /etc/wodim.conf
+that allows to identify a specific drive on the system.
+.TP
+Any other label
+is an identifier for a specific drive on the system.
+Such an identifier may not contain the characters ',', '/', '@' or ':'.
+.sp
+Each line that follows a label contains a TAB separated list of items.
+Currently, four items are recognized: the SCSI ID of the drive, the
+default speed that should be used for this drive, the default FIFO size
+that should be used for this drive and drive specific options. The values for 
+.I speed
+and
+.I fifosize
+may be set to -1 to tell the program to use the global defaults.
+The value for driveropts may be set to "" if no driveropts are used.
+A typical line may look this way:
+.sp
+teac1= 0,5,0	4	8m	""
+.sp
+yamaha= 1,6,0	-1	-1	burnfree
+.sp
+This tells the program
+that a drive named
+.I teac1
+is at scsibus 0, target 5, lun 0 and should be used with speed 4 and
+a FIFO size of 8 MB.
+A second drive may be found at scsibus 1, target 6, lun 0 and uses the
+default speed and the default FIFO size.
+.RE
+.SH SEE ALSO
+.BR genisoimage (1),
+.BR wodim (1),
+.BR readcd (1),
+.BR ssh (1).
+.RE
+.SH SOURCES
+.PP
+.br
+[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de
+
diff --git a/upstream/mageia-cauldron/man1/jed.1 b/upstream/mageia-cauldron/man1/jed.1
new file mode 100644
index 00000000..051ebe92
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/jed.1
@@ -0,0 +1,517 @@
+.\" ==================================================================
+.\" Jed programmers editor, this manpage was writen by 
+.\" "Boris D. Beletsky" <borik@isracom.co.il> copyright(c) 1996
+.\" This manpage may be freely distrebuted as part of GNU Debian Linux
+.\" ==================================================================
+.TH JED 1 "OCT 1996" Debian "User Manuals"
+.SH NAME
+Jed \- programmers editor
+.SH SYNOPSIS
+.B jed \-\-version
+.br
+.B jed\-script \-\-version
+.br
+.B xjed \-\-version
+.sp
+.B jed [\-\-secure] [\-\-batch|\-\-script|\-\-help] [options]
+.I file
+.B ...
+.br
+.B jed\-script [\-\-secure]
+.I script file
+.B [script options] ...
+.br
+.B xjed [\-\-secure] [X options] [\-\-batch|\-\-script|\-\-help] [options]
+.I file
+.B ...
+.SH DESCRIPTION
+.B Jed - programmers editor
+.LP
+Features:
+.LP
+Color syntax 
+.I highlighting. 
+Emulation of 
+.B Emacs,
+.B EDT,
+.B Wordstar, 
+and Brief editors. 
+Extensible in a language resembling C. Completely customizable.
+Editing TeX files with AUC-TeX style editing (BiBTeX support too).
+Folding support, and much more...
+.LP
+For complete documentation, see GNU info files, this manual only
+provides brief tutorial.
+.SH OPTIONS
+.SS major options
+.LP
+.I \-\-version
+.RS
+prints the version and compiletime variables.
+.RE
+.I \-\-help
+.RS
+prints usage information.
+.RE
+.I \-\-secure
+.RS
+runs Jed in secure mode, e.g. you can't run any external commands with
+.I system()
+or
+.I run_shell_cmd().
+.RE
+.I \-\-batch
+.RS
+run Jed in batch mode.
+This is a non-interactive mode.
+.RE
+.I \-\-script
+.RS
+this is a mode like
+.I \-\-batch
+but jed does not eval the startup files. It behaves like
+.I slsh.
+You must give the file that should be evaluated as second argument. It's
+the same as calling
+.B jed\-script.
+.SS minor options
+.LP
+.I \-n             
+.RS
+do not load 
+.I .jedrc 
+file.
+.RE
+.I \-a 'file'
+.RS
+load
+.I file
+as user configuration file instead of .jedrc.
+.RE
+.I + 'n'
+.RS
+goto line
+.I n
+in buffer (notice that in order to this option to take effect, if must
+appear before the file name in the command line, like 'jed +3 file')
+.RE
+.I \-g 'n'
+.RS
+goto line 
+.I n 
+in buffer (notice that in order to this option to take effect, if must
+appear after the file name in the command line, like 'jed file \-g 3')
+.RE
+.I \-l 'file'      
+.RS
+load 
+.I file 
+as S\-Lang code.
+.RE
+.I \-f 'function' 
+.RS
+execute S\-Lang function named
+.I function
+.RE
+.I \-s 'string'
+.RS
+search forward for 
+.I string
+.RE
+.I \-2             
+.RS
+split window
+.RE
+.I \-i 'file'
+.RS
+insert 
+.I file 
+into current buffer.
+.RE
+.LP
+.SS X options
+.B xjed
+accapts the common options like
+.I \-display, \-name, \-fn and \-geometry.
+Additionaly it accepts
+.LP
+.I \-facesize SIZE, \-fs SIZE
+.RS
+if build with XRENDERFONT support, selects the font size
+.I SIZE.
+Use it with the option
+.I \-fn
+to select a scalable font.
+.RE
+.I \-foreground COLOR, \-fg COLOR
+.RS
+sets the foreground color.
+.RE
+.I \-background COLOR, \-bg COLOR
+.RS
+sets the background color.
+.RE
+.I \-fgMouse COLOR, \-mfg COLOR
+.RS
+sets the foreground color of the mouse pointer.
+.RE
+.I \-bgMouse COLOR, \-mbg COLOR
+.RS
+sets the background color of the mouse pointer.
+.RE
+.I \-Iconic, \-ic
+.RS
+start iconified.
+.RE
+.I \-title NAME
+.RS
+sets the window title to
+.I NAME.
+.RE
+.LP
+For more options look at
+.B xterm.c.
+.SH CONFIGURATION
+.RS
+.I Emulating Other Editors
+.RE
+.LP
+JED's ability to create new functions using the 
+.I S\-Lang 
+programming language as well as allowing the user to choose key bindings,
+makes the emulation of other editors possible. Currently, JED provides
+reasonable emulation of the
+.I Emacs, EDT, and Wordstar
+editors.
+.LP
+.RS
+.I Emacs Emulation
+.RE
+.LP
+.I Emacs Emulation
+is provided by the S\-Lang code in
+.I emacs.sl.
+The
+basic functionality of Emacs is emulated; most Emacs users
+should have no problem with JED.  To enable Emacs emulation in JED, make sure
+that the line:
+.LP
+.RS
+.I () = evalfile ("emacs"); 
+.RE
+.LP
+is in your
+.I jed.rc
+(.jedrc) startup file.  JED is distributed
+with this line already present in the default jed.rc file.
+.LP
+.RS
+.I EDT Emulation
+.RE
+.LP
+For
+.I EDT
+emulation,
+.I edt.sl
+must be loaded.  This is accomplished by
+ensuring that the line:
+.LP
+.RS
+.I () = evalfile ("edt");
+.RE
+.LP
+is in present in the jed.rc (.jedrc) Startup File.
+.LP
+.RS
+.I Wordstar Emulation
+.RE
+.LP
+wordstar.sl contains the S\-Lang code for JED's Wordstar
+emulation. Adding the line
+.LP
+.RS
+.I () = evalfile ("wordstar");
+.RE
+.LP
+to your jed.rc (.jedrc) startup file will enable JED's
+Wordstar emulation.
+.SH RUN TIME
+.LP
+.RS
+.I Status line and Windows
+.RE
+.LP
+.I JED 
+supports multiple windows.  Each window may contain the same
+buffer or
+different buffers.  A status line is displayed immediately below
+each
+window.  The status line contains information such as the JED
+version
+number, the buffer name,
+.I mode,
+etc.  Please beware of the
+following indicators:
+.LP
+.I **
+.RS
+buffer has been modified since last save.
+.RE
+.I %%
+.RS
+buffer is read only.
+.RE
+.I m
+.RS
+Mark set indicator.  This means a region is being defined.
+.RE
+.I d
+.RS
+File changed on disk indicator.  This indicates that the
+file associated with the buffer is newer than the
+buffer itself.
+.RE
+.I s
+.RS
+spot pushed indicator.
+.RE
+.I +
+.RS
+Undo is enabled for the buffer.
+.RE
+.I [Narrow]
+.RS
+Buffer is narrowed to a region of LINES.
+.RE
+.I [Macro]
+.RS
+A macro is being defined.
+.RE
+.LP
+.RS
+.I Mini-Buffer.
+.RE
+.LP
+The
+.I Mini-Buffer
+consists of a single line located at the bottom of the
+screen. Much of the dialog between the user and JED takes place in this
+buffer.  For example, when you search for a string, JED will prompt you
+for the string in the Mini-Buffer.
+.LP
+The
+.I Mini-Buffer 
+also provides a direct link to the S\-Lang interpreter.
+To access the interpreter, press
+.I Ctrl-X Esc
+and the
+.I S\-Lang>
+prompt will appear in the Mini-Buffer.  Enter any valid S\-Lang expression for
+evaluation by the interpreter.
+.LP
+It is possible to recall data previously entered into the
+.I Mini-Buffer
+by using the up and down arrow keys.  This makes it possible to use and edit
+previous expressions in a convenient and efficient manner.
+.LP
+.RS
+.I Basic Editing
+.RE
+.LP
+.I Editing with JED
+is pretty easy - most keys simply insert themselves.
+Movement around the buffer is usually done using the
+.I arrow keys or page up and page down keys.
+If
+.I edt.sl
+is loaded, the keypads on
+VTxxx
+terminals function as well.  Here, only the
+highlights are
+touched upon
+(cut/paste operations are not considered `highlights').
+In the following, any character prefixed by the
+.I ^
+character denotes a
+Control character. On keyboards without an explicit Escape key,
+.I "Ctrl-["
+will most likely generate and Escape character.
+.LP
+A
+.I prefix argument
+to a command may be generated by first hitting the
+.I Esc
+key, then entering the number followed by pressing the desired
+key.  Normally, the prefix argument is used simply for
+repetition.  For
+example,
+to move to the right 40 characters, one would press
+.I "Esc 4 0"
+followed immediately by the right arrow key.
+This illustrates the use of the repeat argument for repetition.
+However, the
+prefix argument may be used in other ways as well.  For example,
+to begin
+defining a region, one would press the
+.I "Ctrl-@"
+key.  This sets the mark and begins highlighting.
+Pressing the
+.I "Ctrl-@"
+key with a prefix
+argument will abort the act of defining the region and to pop the
+mark.
+
+The following list of useful keybindings assumes that
+.I emacs.sl
+has been loaded.
+.LP
+.I Ctrl-L
+.RS
+Redraw screen.
+.RE
+.I Ctrl-_
+.RS
+Undo  (Control-underscore, also Ctrl-X u').
+.RE
+.I Esc q
+.RS
+Reformat paragraph (wrap mode).  Used with a prefix
+argument. will justify the paragraph as well.
+.RE
+.I Esc n
+.RS
+narrow paragraph
+(wrap mode).  Used with a prefix
+argument will justify the paragraph as well.
+.RE
+.I Esc ;
+.RS
+Make Language comment (Fortran
+and C)
+.RE
+.I Esc \\\\
+.RS
+Trim whitespace around point
+.RE
+.I Esc !
+.RS
+Execute shell command
+.RE
+.I Esc $
+.RS
+Ispell word 
+.RE
+.I Ctrl-X ?
+.RS
+Show line/column information.
+.RE
+.I `
+.RS
+quoted_insert --- insert
+next char as is (backquote key)
+.RE
+.I Esc s
+.RS
+Center line.
+.RE
+.I Esc u
+.RS
+Upcase word.
+.RE
+.I Esc d
+.RS
+Downcase word.
+.RE
+.I Esc c
+.RS
+Capitalize word.
+.RE
+.I Esc x
+.RS
+Get M-x minibuffer prompt with command
+completion
+.RE
+.I Ctrl-X Ctrl-B
+.RS
+pop up a list of buffers
+.RE
+.I Ctrl-X Ctrl-C
+.RS
+exit JED
+.RE
+.I Ctrl-X 0
+.RS
+Delete
+Current Window
+.RE
+.I Ctrl-X 1
+.RS
+One Window.
+.RE
+.I Ctrl-X 2
+.RS
+Split Window.
+.RE
+.RS
+.I Ctrl-X o
+.RE
+.RS
+Other window.
+.RE
+.I Ctrl-X b
+.RS
+switch to buffer
+.RE
+.I Ctrl-X k
+.RS
+kill buffer
+.RE
+.I Ctrl-X s
+.RS
+save some buffers
+.RE
+.I Ctrl-X Esc
+.RS
+Get "S\-Lang>" prompt for interface to the S\-Lang
+interpreter.
+.RE
+.I Esc .
+.RS
+Find tag
+.RE
+.I Ctrl-@
+.RS
+Set Mark (Begin defining a region).  Used with a
+prefix argument aborts the act
+of defining the region and
+pops the Mark.
+.RE
+.RE
+.\"---------------------------------------------------------
+.SH FILES
+.I JED_ROOT/lib/*.sl
+.RS
+these are the default runtime jed slang files
+.RE
+.I JED_ROOT/lib/site.sl
+.RS
+This is the default startup file.
+.RE
+.I /etc/jed.rc
+.RS
+The system wide configuration file.
+.RE
+.I ~/.jedrc
+.RS
+Per user configuration file.
+.SH AUTHOR
+.I "John E. Davis" <davis@space.mit.edu>
+.RS
+Jed's Author
+.RE
+
+
+--- This document was
+.I translated
+to nroff
+by "Boris D. Beletsky" <borik@isracom.co.il>
diff --git a/upstream/mageia-cauldron/man1/joe.1 b/upstream/mageia-cauldron/man1/joe.1
new file mode 100644
index 00000000..2f334656
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/joe.1
@@ -0,0 +1,6002 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "JOE" "" "March 2016" "" ""
+.
+.SH "NAME"
+\fBJOE\fR \- Joe\'s Own Editor
+.
+.SH "Syntax"
+\fBjoe [global\-options] [ [local\-options] filename ]\.\.\.\fR
+.
+.br
+\fBjstar [global\-options] [ [local\-options] filename ]\.\.\.\fR
+.
+.br
+\fBjmacs [global\-options] [ [local\-options] filename ]\.\.\.\fR
+.
+.br
+\fBrjoe [global\-options] [ [local\-options] filename ]\.\.\.\fR
+.
+.br
+\fBjpico [global\-options] [ [local\-options] filename ]\.\.\.\fR
+.
+.SH "Description"
+JOE is a powerful console screen editor\. It has a "mode\-less" user interface which is similar to many user\-friendly PC editors\. Users of Micro\-Pro\'s WordStar or Borland\'s "Turbo" languages will feel at home\. JOE is a full featured UNIX screen\-editor though, and has many features for editing programs and text\.
+.
+.P
+JOE also emulates several other editors\. JSTAR is a close imitation of WordStar with many "JOE" extensions\. JPICO is a close imitation of the Pine mailing system\'s PICO editor, but with many extensions and improvements\. JMACS is a GNU\-EMACS imitation\. RJOE is a restricted version of JOE, which allows you to edit only the files specified on the command line\.
+.
+.P
+Although JOE is actually five different editors, it still requires only one executable, but one with five different names\. The name of the editor with an "rc" appended gives the name of JOE\'s initialization file, which determines the personality of the editor\.
+.
+.P
+JOE is free software; you can distribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation\. JOE is available over the Internet from \fIhttp://www\.sourceforge\.net/projects/joe\-editor\fR\.
+.
+.SH "Usage"
+To start the editor, type \fBjoe\fR followed by zero or more names of files you want to edit\. Each file name may be preceded by a local option setting (see the local options table which follows)\. Other global options, which apply to the editor as a whole, may also be placed on the command line (see the global options table which follows)\. If you are editing a new file, you can either give the name of the new file when you invoke the editor, or in the editor when you save the new file\. A modified syntax for file names is provided to allow you to edit program output, standard input/output, or sections of files or devices\. See the section \fIFilenames\fR below for details\.
+.
+.P
+Once you are in the editor, you can type in text and use special control\-character sequences to perform other editing tasks\. To find out what the control\-character sequences are, read the rest of this man page or type \fB^K H\fR for help in the editor\.
+.
+.P
+Now for some obscure computer\-lore:
+.
+.P
+The \fB^\fR means that you hold down the \fBControl\fR key while pressing the following key (the same way the \fBShift\fR key works for uppercase letters)\. A number of control\-key sequences are duplicated on other keys, so that you don\'t need to press the control key: \fBEsc\fR will work in place of \fB^[\fR, \fBDel\fR will work in place of \fB^?\fR, \fBBackspace\fR will work in place of \fB^H\fR, \fBTab\fR will work in place of \fB^I\fR, \fBReturn\fR or \fBEnter\fR will work in place of \fB^M\fR and \fBLinefeed\fR will work in place of \fB^J\fR\. Some keyboards may give you trouble with some control keys\. \fB^\fR_, \fB^^\fR and \fB^@\fR can usually be entered without pressing shift (i\.e\., try \fB^\-\fR, \fB^6\fR and \fB^2\fR)\. Other keyboards may reassign these to other keys\. Try: \fB^\.\fR, \fB^,\fR and \fB^/\fR\. \fB^Space\fR can usually be used in place of \fB^@\fR\. \fB^\e\fR and \fB^]\fR are interpreted by many communication programs, including telnet and kermit\. Usually you just hit the key twice to get it to pass through the communication program\.
+.
+.P
+On some keyboards, holding the \fBAlt\fR key down while pressing another key is the same as typing \fBEsc\fR before typing the other key\.
+.
+.P
+Once you have typed \fB^K H\fR, the first help window appears at the top of the screen\. You can continue to enter and edit text while the help window is on\. To page through other topics, hit \fBEsc ,\fR and \fBEsc \.\fR (that is, \fBEsc ,\fR and \fBEsc \.\fR)\. Use \fB^K H\fR to dismiss the help window\.
+.
+.P
+You can customize the keyboard layout, the help screens and a number of behavior defaults by copying JOE\'s initialization file (usually \fB/etc/joe/joerc\fR) to \fB\.joerc\fR in your home directory and then by modifying it\. See the section \fIjoerc\fR below\.
+.
+.P
+To have JOE used as your default editor for e\-mail and News, you need to set the \fBEDITOR\fR and \fBVISUAL\fR environment variables in your shell initialization file (\fB\.cshrc\fR or \fB\.profile\fR) to refer to JOE (JOE usually resides as \fB/usr/bin/joe\fR)\.
+.
+.P
+There are a number of other obscure invocation parameters which may have to be set, particularly if your terminal screen is not updating as you think it should\. See the section \fIEnvironment variables\fR below\.
+.
+.P
+ \fI\fR
+.
+.SH "Command Line Options"
+These options can also be specified in the joerc file\. Local options can be set depending on the file\-name extension\. Programs (\.c, \.h or \.p extension) usually have autoindent enabled\. Wordwrap is enabled on other files, but rc files have it disabled\.
+.
+.P
+An option is enabled when it\'s given like this:
+.
+.IP "" 4
+.
+.nf
+
+\-wordwrap
+.
+.fi
+.
+.IP "" 0
+.
+.P
+An option is disabled when it\'s given like this:
+.
+.IP "" 4
+.
+.nf
+
+\-\-wordwrap
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Some options take arguments\. Arguments are given like this:
+.
+.IP "" 4
+.
+.nf
+
+\-lmargin 5
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The following global options may be specified on the command line:
+.
+.IP "\(bu" 4
+asis
+.
+.br
+Characters with codes above 127 will be sent to the terminal as\-is, instead of as inverse of the corresponding character below 128\. If this does not work, check your terminal server\. This option has no effect if UTF\-8 encoding is used\.
+.
+.br
+
+.
+.IP "\(bu" 4
+assume_256color
+.
+.br
+Assume ANSI\-like terminal emulator supports 256 colors even if termcap entry says it doesn\'t\.
+.
+.br
+
+.
+.IP "\(bu" 4
+assume_color
+.
+.br
+Assume ANSI\-like terminal emulator supports color even if termcap entry says it doesn\'t\.
+.
+.br
+
+.
+.IP "\(bu" 4
+text_color \fBcolor\fR
+.
+.br
+Set color for text\.
+.
+.br
+
+.
+.IP "\(bu" 4
+status_color \fBcolor\fR
+.
+.br
+Set color for status bar\.
+.
+.br
+
+.
+.IP "\(bu" 4
+help_color \fBcolor\fR
+.
+.br
+Set color for help\.
+.
+.br
+
+.
+.IP "\(bu" 4
+menu_color \fBcolor\fR
+.
+.br
+Set color for menus\.
+.
+.br
+
+.
+.IP "\(bu" 4
+prompt_color \fBcolor\fR
+.
+.br
+Set color for prompts\.
+.
+.br
+
+.
+.IP "\(bu" 4
+msg_color \fBcolor\fR
+.
+.br
+Set color for messages\.
+.
+.br
+
+.
+.IP "\(bu" 4
+autoswap
+.
+.br
+Automatically swap \fB^K B\fR with \fB^K K\fR if necessary to mark a legal block during block copy/move commands\.
+.
+.br
+
+.
+.IP "\(bu" 4
+backpath path
+.
+.br
+Sets path to a directory where all backup files are to be stored\. If this is unset (the default) backup files are stored in the directory containing the file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+baud nnn
+.
+.br
+Set the baud rate for the purposes of terminal screen optimization (overrides value reported by stty)\. JOE inserts delays for baud rates below 19200, which bypasses tty buffering so that typeahead will interrupt the screen output\. Scrolling commands will not be used for 38400 baud and above\. This is useful for X\-terms and other console ttys which really aren\'t going over a serial line\.
+.
+.br
+
+.
+.IP "\(bu" 4
+beep
+.
+.br
+Enable beeps when edit commands return errors, for example when the cursor goes past extremes\.
+.
+.br
+
+.
+.IP "\(bu" 4
+break_links
+.
+.br
+When enabled, JOE first deletes the file before writing it in order to break hard\-links and symbolic\-links\.
+.
+.br
+
+.
+.IP "\(bu" 4
+break_hardlinks
+.
+.br
+When enabled, and the file is not a symbolic links, JOE first deletes the file before writing it in order to break hard\-links\.
+.
+.br
+
+.
+.IP "\(bu" 4
+brpaste
+.
+.br
+When JOE starts, send command to the terminal emulator that enables "bracketed paste mode" (but only if the terminal seems to have the ANSI command set)\. In this mode, text pasted into the window is bracketed with ESC [ 2 0 0 ~ and ESC [ 2 0 1 ~\.
+.
+.br
+
+.
+.IP "\(bu" 4
+columns nnn
+.
+.br
+Set number of columns in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\.
+.
+.br
+
+.
+.IP "\(bu" 4
+csmode
+.
+.br
+Enable continued search mode: Successive \fB^K F\fRs repeat the current search instead of prompting for a new one\.
+.
+.br
+
+.
+.IP "\(bu" 4
+dopadding
+.
+.br
+Enable JOE to send padding NULs to the terminal (for very old terminals)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+exask
+.
+.br
+When set, \fB^K X\fR prompts for a new name before saving the file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+floatmouse
+.
+.br
+When set, mouse clicks can position the cursor beyond the ends of lines\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_crlf
+.
+.br
+When set, JOE tries to guess the file format MS\-DOS or UNIX\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_indent
+.
+.br
+When set, JOE tries to guess the indentation character and indentation step based on the contents of the file\. The algorithm is to find the greatest common factor of the three most common indentations found in the file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_non_utf8
+.
+.br
+When set, enable guessing of non\-UTF\-8 files in UTF\-8 locales\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_utf8
+.
+.br
+When set, enable guessing of UTF\-8 files in non\-UTF\-8 locales\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_utf16
+.
+.br
+When set, enable guessing of UTF\-16 files\. If a UTF\-16BE or UTF\-16LE file is detected, it is converted to UTF\-8 during load, and converted back to UTF\-16 during save\.
+.
+.br
+
+.
+.IP "\(bu" 4
+helpon
+.
+.br
+When set, start off with the on\-line help enabled\.
+.
+.br
+
+.
+.IP "\(bu" 4
+help_is_utf8
+.
+.br
+When set, the help text in the joerc file is assumed to be UTF\-8\.
+.
+.br
+
+.
+.IP "\(bu" 4
+icase
+.
+.br
+Search is case insensitive by default when set\.
+.
+.br
+
+.
+.IP "\(bu" 4
+joe_state
+.
+.br
+Enable reading and writing of ~/\.joe_state file
+.
+.br
+
+.
+.IP "\(bu" 4
+joexterm
+.
+.br
+Set this if xterm was configured with \-\-paste64 option for better mouse support\.
+.
+.br
+
+.
+.IP "\(bu" 4
+keepup
+.
+.br
+The column number on the status line is updated constantly when this is set, otherwise it is updated only once a second\.
+.
+.br
+
+.
+.IP "\(bu" 4
+language \fBlanguage\fR
+.
+.br
+Sets language for aspell\.
+.
+.br
+
+.
+.IP "\(bu" 4
+lightoff
+.
+.br
+Automatically turn off \fB^K B\fR \fB^K K\fR highlighting after a block operation\.
+.
+.br
+
+.
+.IP "\(bu" 4
+lines nnn
+.
+.br
+Set number of lines in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\.
+.
+.br
+
+.
+.IP "\(bu" 4
+marking
+.
+.br
+Enable marking mode: highlights between \fB^K B\fR and cursor\.
+.
+.br
+
+.
+.IP "\(bu" 4
+menu_above
+.
+.br
+Put menus above prompt instead of below them\.
+.
+.br
+
+.
+.IP "\(bu" 4
+menu_explorer
+.
+.br
+Stay in menu when a directory is selected (otherwise the directory is added to the path and the cursor jumps back to the prompt)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+menu_jump
+.
+.br
+Jump into the file selection menu when \fBTab\fR \fBTab\fR is hit\.
+.
+.br
+
+.
+.IP "\(bu" 4
+mid
+.
+.br
+If this option is set and the cursor moves off the window, the window will be scrolled so that the cursor is in the center\. This option is forced on slow terminals which don\'t have scrolling commands\.
+.
+.br
+
+.
+.IP "\(bu" 4
+left nn
+.
+.br
+This sets the number of columns the screen scrolls to the left when cursor moves past the left edge or when the crawll command is issued\. If nn is negative, then it\'s the fraction of the screen to scroll\. For example, \-2 means scroll 1/2 the screen\.
+.
+.br
+
+.
+.IP "\(bu" 4
+right nn
+.
+.br
+This sets the number of columns the screen scrolls to the right when cursor moves past the right edge or when the crawlr command is issued\. If nn is negative, then it\'s the fraction of the screen to scroll\. For example, \-3 means scroll 1/3 the screen\.
+.
+.br
+
+.
+.IP "\(bu" 4
+mouse
+.
+.br
+Enable xterm mouse support\.
+.
+.br
+
+.
+.IP "\(bu" 4
+nobackups
+.
+.br
+Disable backup files\.
+.
+.br
+
+.
+.IP "\(bu" 4
+nocurdir
+.
+.br
+Disable current\-directory prefix in prompts\.
+.
+.br
+
+.
+.IP "\(bu" 4
+noexmsg
+.
+.br
+Disable exiting message ("File not changed so no update needed")
+.
+.br
+
+.
+.IP "\(bu" 4
+nolinefeeds
+.
+.br
+Disable sending linefeeds to preserve screen history in terminal emulator\'s scroll\-back buffer (only relevant when notite mode is enabled)\.
+.
+.br
+.
+.br
+
+.
+.IP "\(bu" 4
+nolocks
+.
+.br
+Disable EMACS compatible file locks\.
+.
+.br
+
+.
+.IP "\(bu" 4
+nomodcheck
+.
+.br
+Disable periodic file modification check\.
+.
+.br
+
+.
+.IP "\(bu" 4
+nonotice
+.
+.br
+This option prevents the copyright notice from being displayed when the editor starts\.
+.
+.br
+
+.
+.IP "\(bu" 4
+nosta
+.
+.br
+This option eliminates the top\-most status line\. It\'s nice for when you only want to see your text on the screen or if you\'re using a vt52\.
+.
+.br
+
+.
+.IP "\(bu" 4
+notagsmenu
+.
+.br
+Disable selection menu for tags search with multiple results\.
+.
+.br
+
+.
+.IP "\(bu" 4
+notite
+.
+.br
+Disable ti and te termcap sequences which are usually set up to save and restore the terminal screen contents when JOE starts and exits\.
+.
+.br
+
+.
+.IP "\(bu" 4
+pastehack
+.
+.br
+If keyboard input comes in as one block assume it\'s a mouse paste and disable autoindent and wordwrap\.
+.
+.br
+
+.
+.IP "\(bu" 4
+noxon
+.
+.br
+Disable \fB^S\fR and \fB^Q\fR flow control, possibly allowing \fB^S\fR and \fB^Q\fR to be used as editor keys\.
+.
+.br
+
+.
+.IP "\(bu" 4
+orphan
+.
+.br
+Orphan extra files given on the command line instead of creating windows for them (the files are loaded, but you need to use switch\-buffer commands to access them)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+pg nnn
+.
+.br
+Set number of lines to keep during Page Up and Page Down (use \-1 for 1/2 window size)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+regex
+.
+.br
+Use standard regular expression syntax by default, instead of the JOE syntax (where special characters have their meaning only when preceded with backslash)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+restore
+.
+.br
+Set to have cursor positions restored to last positions of previously edited files\.
+.
+.br
+
+.
+.IP "\(bu" 4
+rtbutton
+.
+.br
+Swap left and right mouse buttons\.
+.
+.br
+
+.
+.IP "\(bu" 4
+search_prompting
+.
+.br
+Show previous search string in search command (like in PICO)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+skiptop nnn
+.
+.br
+When set to N, the first N lines of the terminal screen are not used by JOE and are instead left with their original contents\. This is useful for programs which call JOE to leave a message for the user\.
+.
+.br
+
+.
+.IP "\(bu" 4
+square
+.
+.br
+Enable rectangular block mode\.
+.
+.br
+
+.
+.IP "\(bu" 4
+transpose
+.
+.br
+Transpose rows with columns in all menus\.
+.
+.br
+
+.IP "\(bu" 4
+title
+.
+.br
+Display context (titles) in status line.  When enabled this shows the first line of the function that the cursor is in on the status line\.  The syntax file context.jsf identifies which lines are title lines\.
+.
+.br
+
+.
+.IP "\(bu" 4
+type
+.
+.br
+Select file type, overriding the automatically determined type\. The file types are defined in the \fBftyperc\fR file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+undo_keep nnn
+.
+.br
+Sets number of undo records to keep (0 means infinite)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+usetabs
+.
+.br
+Set to allow rectangular block operations to use tabs\.
+.
+.br
+
+.
+.IP "\(bu" 4
+wrap
+.
+.br
+Enable search to wrap to beginning of file\.
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+The following local options may be specified on the command line:
+.
+.IP "\(bu" 4
++nnn
+.
+.br
+The cursor starts on the specified line\.
+.
+.br
+
+.
+.IP "\(bu" 4
+autoindent
+.
+.br
+Enable auto\-indent mode\. When you hit \fBEnter\fR on an indented line, the indentation is duplicated onto the new line\.
+.
+.br
+
+.
+.IP "\(bu" 4
+c_comment
+.
+.br
+Enable \fB^G\fR skipping of C\-style comments /\fI\.\.\.\fR/
+.
+.br
+
+.
+.IP "\(bu" 4
+cpara \fBcharacters\fR
+.
+.br
+Sets list of characters which can indent paragraphs\.
+.
+.br
+
+.
+.IP "\(bu" 4
+cnotpara \fBcharacters\fR
+.
+.br
+Sets list of characters which begin lines which are definitely not part of paragraphs\.
+.
+.br
+
+.
+.IP "\(bu" 4
+cpp_comment
+.
+.br
+Enable \fB^G\fR skipping of C++\-style comments // \.\.\.
+.
+.br
+
+.
+.IP "\(bu" 4
+crlf
+.
+.br
+JOE uses CR\-LF as the end of line sequence instead of just LF\. This is for editing MS\-DOS or VMS files\.
+.
+.br
+
+.
+.IP "\(bu" 4
+encoding \fBencoding\fR
+.
+.br
+Set file encoding (like utf\-8 or 8859\-1)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+flowed
+.
+.br
+Set to force an extra space after each line of a paragraph but the last\.
+.
+.br
+
+.
+.IP "\(bu" 4
+force
+.
+.br
+When set, a final newline is appended to the file if there isn\'t one when the file is saved\.
+.
+.br
+
+.
+.IP "\(bu" 4
+french
+.
+.br
+When set, only one space is inserted after periods in paragraph reformats instead of two\.
+.
+.br
+
+.
+.IP "\(bu" 4
+hex
+.
+.br
+Enable hex\-dump mode\.
+.
+.br
+
+.
+.IP "\(bu" 4
+highlight
+.
+.br
+Enable syntax highlighting\.
+.
+.br
+
+.
+.IP "\(bu" 4
+highlighter_context
+.
+.br
+Enable use of syntax file to identify comments and strings which should be skipped over during \fB^G\fR matching\.
+.
+.br
+
+.
+.IP "\(bu" 4
+indentc nnn
+.
+.br
+Sets the indentation character for shift left and shift right (\fB^K ,\fR and \fB^K \.\fR)\. Use 32 for \fBSpace\fR, 9 for \fBTab\fR\.
+.
+.br
+
+.
+.IP "\(bu" 4
+indentfirst
+.
+.br
+When set, the smart home key jumps to the indentation point first, otherwise it jumps to column 1 first\.
+.
+.br
+
+.
+.IP "\(bu" 4
+istep nnn
+.
+.br
+Sets indentation step\.
+.
+.br
+
+.
+.IP "\(bu" 4
+linums
+.
+.br
+Enable line number display\.
+.
+.br
+
+.
+.IP "\(bu" 4
+lmargin
+.
+.br
+Set left margin\.
+.
+.br
+
+.
+.IP "\(bu" 4
+lmsg
+.
+.br
+Define left\-side status bar message\.
+.
+.br
+
+.
+.IP "\(bu" 4
+overwrite
+.
+.br
+Enable overtype mode\. Typing overwrites existing characters instead of inserting before them\.
+.
+.br
+
+.
+.IP "\(bu" 4
+picture
+.
+.br
+Enable "picture" mode\- allows cursor to go past ends of lines\.
+.
+.br
+
+.
+.IP "\(bu" 4
+pound_comment
+.
+.br
+\fB^G\fR ignores # \.\.\. comments\.
+.
+.br
+
+.
+.IP "\(bu" 4
+purify
+.
+.br
+Fix indentation if necessary before shifting or smart backspace\. For example, if indentation uses a mix of tabs and spaces, and indentc is space, then indentation will be converted to all spaces before the shifting operation\.
+.
+.br
+
+.
+.IP "\(bu" 4
+rdonly
+.
+.br
+Set read\-only mode\.
+.
+.br
+
+.
+.IP "\(bu" 4
+rmargin nnn
+.
+.br
+Set right margin\.
+.
+.br
+
+.
+.IP "\(bu" 4
+rmsg \fBstring\fR
+.
+.br
+Define right\-side status bar message\.
+.
+.br
+
+.
+.IP "\(bu" 4
+semi_comment
+.
+.br
+\fB^G\fR ignores ; \.\.\. comments\.
+.
+.br
+
+.
+.IP "\(bu" 4
+single_quoted
+.
+.br
+\fB^G\fR ignores \'\.\.\.\'
+.
+.br
+
+.
+.IP "\(bu" 4
+smartbacks
+.
+.br
+Enable smart backspace and tab\. When this mode is set backspace and tab indent or unindent based on the values of the istep and indentc options\.
+.
+.br
+
+.
+.IP "\(bu" 4
+smarthome
+.
+.br
+Home key first moves cursor to beginning of line, then if hit again, to the first non\-blank character\.
+.
+.br
+
+.
+.IP "\(bu" 4
+smsg \fBstring\fR
+.
+.br
+Define status command format when cursor is on a character\.
+.
+.br
+
+.
+.IP "\(bu" 4
+spaces
+.
+.br
+Insert spaces when \fBTab\fR key is hit\.
+.
+.br
+
+.
+.IP "\(bu" 4
+syntax \fBsyntax\fR
+.
+.br
+Set syntax for syntax highlighting\.
+.
+.br
+
+.
+.IP "\(bu" 4
+tab nnn
+.
+.br
+Set tab stop width\.
+.
+.br
+
+.
+.IP "\(bu" 4
+text_delimiters \fBword delimiter list\fR
+.
+.br
+Give list of word delimiters which \fB^G\fR will step through\.
+.
+.IP "" 0
+.
+.P
+For example, "begin=end:if=elif=else=endif" means that \fB^G\fR will jump between the matching if, elif, else and endif\.
+.
+.IP "\(bu" 4
+vhdl_comment
+.
+.br
+\fB^G\fR ignores \-\- \.\.\. comments
+.
+.br
+
+.
+.IP "\(bu" 4
+wordwrap
+.
+.br
+JOE wraps the previous word when you type past the right margin\.
+.
+.br
+
+.
+.IP "\(bu" 4
+zmsg \fBstring\fR
+.
+.br
+Define status command format when cursor is at end of file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+xmsg \fBstring\fR
+.
+.br
+Define startup message (usually the copyright notice)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+aborthint \fBstring\fR
+.
+.br
+Give the key sequence to show in prompts for abort (usually ^C)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+helphint \fBstring\fR
+.
+.br
+Give the key sequence to show in prompts for help (usually ^K H)\.
+.
+.br
+
+.
+.IP "" 0
+.
+.SS "Colors and attributes"
+Combine attributes and up to one foreground color and one background color to create arguments for color options like text_color\. For example: bold+bg_green+blue
+.
+.IP "\(bu" 4
+Attributes: bold, inverse, blink, dim, underline, and italic
+.
+.IP "\(bu" 4
+Foreground colors: white, cyan, magenta, blue, yellow, green, red, or black
+.
+.IP "\(bu" 4
+Background colors: bg_white, bg_cyan, bg_magenta, bg_blue, bg_yellow, bg_green, bg_red or bg_black
+.
+.IP "" 0
+.
+.P
+With a 16 color or 256 color terminal emulator (export TERM=xterm\-16color), these brighter than normal colors become available:
+.
+.IP "\(bu" 4
+Foreground: WHITE, CYAN, MAGENTA, BLUE, YELLOW, GREEN, RED or BLACK
+.
+.IP "\(bu" 4
+Background: bg_WHITE, bg_CYAN, bg_MAGENTA, bg_BLUE, bg_YELLOW, bg_GREEN, bg_RED or bg_BLACK
+.
+.IP "" 0
+.
+.P
+With a 256 color terminal emulator (export TERM=xterm\-256color), these become available:
+.
+.IP "\(bu" 4
+fg_RGB and bg_RGB, where R, G and B rand from 0 \- 5\. So: fg_500 is bright red\.
+.
+.IP "\(bu" 4
+fg_NN and bg_NN give shades of grey, where the intensity, NN, ranges from 0 \- 23\.
+.
+.IP "" 0
+.
+.SS "Status line definition strings"
+\-lmsg defines the left\-justified string and \-rmsg defines the right\-justified string\. The first character of \-rmsg is the background fill character\.
+.
+.P
+\-smsg defines the status command (\fB^K Space\fR)\. \-zmsg defines it when the cursor is at the end of the file\. The last character of smsg or zmsg is the fill character\.
+.
+.P
+The following escape sequences can be used in these strings:
+.
+.IP "" 4
+.
+.nf
+
+%t  12 hour time
+%u  24 hour time
+%T  O for overtype mode, I for insert mode
+%W  W if wordwrap is enabled
+%I  A if autoindent is enabled
+%X  Rectangle mode indicator
+%n  File name
+%m  \'(Modified)\' if file has been changed
+%*  \'*\' if file has been changed
+%R  Read\-only indicator
+%r  Row (line) number
+%c  Column number
+%o  Byte offset into file
+%O  Byte offset into file in hex
+%a  Ascii value of character under cursor
+%A  Ascii value of character under cursor in hex
+%w  Width of character under cursor
+%p  Percent of file cursor is at
+%l  No\. lines in file
+%k  Entered prefix keys
+%S  \'*SHELL*\' if there is a shell running in window
+%M  Macro recording message
+%y  Syntax
+%e  Encoding
+%x  Context (first non\-indented line going backwards)
+%dd day
+%dm month
+%dY year
+%Ename%  value of environment variable
+%Tname%  value of option (ON or OFF for Boolean options)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+These formatting escape sequences may also be given:
+.
+.IP "" 4
+.
+.nf
+
+\ei  Inverse
+\eu  Underline
+\eb  Bold
+\ed  Dim
+\ef  Blink
+\el  Italic
+.
+.fi
+.
+.IP "" 0
+.
+.P
+.
+.br
+.
+.SH "Basic Editing"
+When you type characters into the editor, they are normally inserted into the file being edited (or appended to the file if the cursor is at the end of the file)\. This is the normal operating mode of the editor\. If you want to replace some existing text, you have to delete the old text before or after you type in the replacement text\. The \fBBackspace\fR key can be used for deleting text: move the cursor to right after the text you want to delete and hit \fBBackspace\fR a number of times\.
+.
+.P
+Hit the \fBEnter\fR or \fBReturn\fR key to insert a line\-break\. For example, if the cursor was in the middle of a line and you hit \fBEnter\fR, the line would be split into two lines with the cursor appearing at the beginning of the second line\. Hit \fBBackspace\fR at the beginning of a line to eliminate a line\-break\.
+.
+.P
+Use the arrow keys to move around the file\. If your keyboard doesn\'t have arrow keys (or if they don\'t work for some reason), use \fB^F\fR to move forwards (right), \fB^B\fR to move backwards (left), \fB^P\fR to move to the previous line (up), and \fB^N\fR to move to the next line (down)\. The right and left arrow keys simply move forwards or backwards one character at a time through the text: if you\'re at the beginning of a line and you press left\-arrow, you will end up at the end of the previous line\. The up and down arrow keys move forwards and backwards by enough characters so that the cursor appears in the same column that it was in on the original line\.
+.
+.P
+If you want to indent the text you enter, you can use the \fBTab\fR key\. This inserts a special control character which makes the characters which follow it begin at the next tab stop\. Tab stops normally occur every 8 columns, but this can be changed with the \fB^T D\fR command\. PASCAL and C programmers often set tab stops on every 4 columns\.
+.
+.P
+If for some reason your terminal screen gets messed up (for example, if you receive a mail notice from biff), you can have the editor refresh the screen by hitting \fB^R\fR\.
+.
+.P
+There are many other keys for deleting text and moving around the file\. For example, hit \fB^D\fR to delete the character the cursor is on instead of deleting backwards like \fBBackspace\fR\. \fB^D\fR will also delete a line\-break if the cursor is at the end of a line\. Type \fB^Y\fR to delete the entire line the cursor is on or \fB^J\fR to delete just from the cursor to the end of the line\.
+.
+.P
+Hit \fB^A\fR to move the cursor to the beginning of the line it\'s on\. Hit \fB^E\fR to move the cursor to the end of the line\. Hit \fB^U\fR or \fB^V\fR for scrolling the cursor up or down 1/2 a screen\'s worth\.
+.
+.br
+"Scrolling" means that the text on the screen moves, but the cursor stays at the same place relative to the screen\. Hit \fB^K U\fR or \fB^K V\fR to move the cursor to the beginning or the end of the file\. Look at the help screens in the editor to find even more delete and movement commands\.
+.
+.P
+If you make a mistake, you can hit \fB^_\fR to "undo" it\. On most keyboards you hit just \fB^\-\fR to get \fB^_\fR, but on some you might have to hold both the \fBShift\fR and \fBControl\fR keys down at the same time to get it\. If you "undo" too much, you can "redo" the changes back into existence by hitting \fB^^\fR (type this with just \fB^6\fR on most keyboards)\.
+.
+.SS "Cursor position history"
+If you were editing in one place within the file, and you then temporarily had to look or edit some other place within the file, you can get back to the original place by hitting \fB^K \-\fR\. This command actually returns you to the last place you made a change in the file\. You can step through a history of places with \fB^K \-\fR and \fB^K =\fR, in the same way you can step through the history of changes with the "undo" and "redo" commands\.
+.
+.SS "Save and exit"
+When you are done editing the file, hit \fB^K X\fR to exit the editor\. You will be prompted for a file name if you hadn\'t already named the file you were editing\.
+.
+.P
+When you edit a file, you actually edit only a copy of the file\. So if you decide that you don\'t want the changes you made to a file during a particular edit session, you can hit \fB^C\fR to exit the editor without saving them\.
+.
+.P
+If you edit a file and save the changes, a backup copy of that file is created in the current directory, with a \fB~\fR appended to the name, which contains the original version of the file\.
+.
+.SS "File operations"
+You can hit \fB^K D\fR to save the current file (possibly under a different name from what the file was called originally)\. After the file is saved, you can hit \fB^K E\fR to edit a different file\.
+.
+.P
+If you want to save only a selected section of the file, see the section on \fIBlocks\fR below\.
+.
+.P
+If you want to include another file in the file you\'re editing, use \fB^K R\fR to insert it\.
+.
+.P
+ \fI\fR
+.
+.SS "Filenames"
+Wherever JOE expects you to enter a file name, whether on the command line or in prompts within the editor, you may also type:
+.
+.IP "\(bu" 4
+!command
+.
+.IP "" 0
+.
+.P
+To read or write data to or from a shell command\. For example, use \fBjoe \'!ls\'\fR to get a copy of your directory listing to edit or from within the editor use \fB^K D !mail jhallen@world\.std\.com\fR to send the file being edited to me\.
+.
+.IP "\(bu" 4
+>>filename
+.
+.IP "" 0
+.
+.P
+Use this to have JOE append the edited text to the end of the file "filename\."
+.
+.IP "\(bu" 4
+filename,START,SIZE
+.
+.IP "" 0
+.
+.P
+Use this to access a fixed section of a file or device\. \fBSTART\fR and \fBSIZE\fR may be entered in decimal (ex\.: 123) octal (ex\.: 0777) or hexadecimal (ex\.: 0xFF)\. For example, use \fBjoe /dev/fd0,508,2\fR to edit bytes 508 and 509 of the first floppy drive in Linux\.
+.
+.IP "\(bu" 4
+\-
+.
+.IP "" 0
+.
+.P
+Use this to get input from the standard input or to write output to the standard output\. For example, you can put JOE in a pipe of commands: \fBquota \-v | joe | mail root\fR, if you want to complain about your low quota\.
+.
+.SS "Using JOE in a shell script"
+JOE used to use /dev/tty to access the terminal\. This caused a problem with idle\-session killers (they would kill JOE because the real tty device was not being accessed for a long time), so now JOE only uses /dev/tty if you need to pipe a file into JOE, as in:
+.
+.IP "" 4
+.
+.nf
+
+echo "hi" | joe
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If you want to use JOE in a shell script which has its stdin/stdout redirected, but you do not need to pipe to it, you should simply redirect JOE\'s stdin/stdout to /dev/tty:
+.
+.IP "" 4
+.
+.nf
+
+joe filename  </dev/tty >/dev/tty
+.
+.fi
+.
+.IP "" 0
+.
+.P
+.
+.br
+.
+.br
+.
+.SS "Word wrap and formatting"
+If you type past the right edge of the screen in a C or PASCAL language file, the screen will scroll to the right to follow the cursor\. If you type past the right edge of the screen in a normal file (one whose name doesn\'t end in \.c, \.h or \.p), JOE will automatically wrap the last word onto the next line so that you don\'t have to hit \fBEnter\fR\. This is called word\-wrap mode\. Word\-wrap can be turned on or off with the \fB^T W\fR command\. JOE\'s initialization file is usually set up so that this mode is automatically turned on for all non\-program files\. See the section below on the \fIjoerc\fR file to change this and other defaults\.
+.
+.P
+Aside for Word\-wrap mode, JOE does not automatically keep paragraphs formatted like some word\-processors\. Instead, if you need a paragraph to be reformatted, hit \fB^K J\fR\. This command "fills in" the paragraph that the cursor is in, fitting as many words in a line as is possible\. A paragraph, in this case, is a block of text separated above and below by a blank line\.
+.
+.P
+The margins which JOE uses for paragraph formatting and word\-wrap can be set with the \fB^T L\fR and \fB^T R\fR commands\. If the left margin is set to a value other than 1, then when you start typing at the beginning of a line, the cursor will immediately jump to the left margin\.
+.
+.P
+There are a number of options which control the paragraph reformatter and word wrapper:
+.
+.IP "\(bu" 4
+The \fBcpara\fR option provides a list of characters which can indent a paragraph\. For example, in e\-mail quoted matter is indicated by \fB>\fR at the beginnings of line, so this character should be in the cpara list\.
+.
+.IP "\(bu" 4
+The \fBcnotpara\fR option provides a list of characters which, if they are the first non\-whitespace character of a line, indicate that the line is not to be included as part of a paragraph for formatting\. For example, lines beginning with \'\.\' in nroff can not be paragraph lines\.
+.
+.IP "\(bu" 4
+Autoindent mode affects the formatter\. If autoindent is disabled, only the first line will be indented\. If autoindent is enabled, the entire paragraph is indented\.
+.
+.IP "\(bu" 4
+\fBfrench\fR determines how many spaces are inserted after periods\.
+.
+.IP "\(bu" 4
+When \fBflowed\fR is enabled, a space is inserted after each but the last line of the paragraph\. This indicates that the lines belong together as a single paragraph in some programs\.
+.
+.IP "\(bu" 4
+When \fBovertype\fR is enabled, the word wrapper will not insert lines\.
+.
+.IP "" 0
+.
+.SS "Centering"
+If you want to center a line within the margins, use the \fB^K A\fR command\.
+.
+.SS "Spell checker"
+Hit \fBEsc N\fR to check the spelling of the word the cursor is on using the aspell program (or ispell program if you modify the joerc file)\. Hit \fBEsc L\fR to check the highlighted block or the entire file if no block is highlighted\.
+.
+.P
+JOE passes the language and character encoding to the spell checker\. To change the language, hit \fB^T V\fR\. For example, use en_US for English\.
+.
+.SS "Overtype mode"
+Sometimes it\'s tiresome to have to delete old text before or after you insert new text\. This happens, for example, when you are changing a table and you want to maintain the column position of the right side of the table\.
+.
+.br
+When this occurs, you can put the editor in overtype mode with \fB^T T\fR\.
+.
+.br
+When the editor is in this mode, the characters you type in replace existing characters, in the way an idealized typewriter would\. Also, \fBBackspace\fR simply moves left instead of deleting the character to the left, when it\'s not at the end or beginning of a line\. Overtype mode is not the natural way of dealing with text electronically, so you should go back to insert\-mode as soon as possible by typing \fB^T T\fR again\.
+.
+.P
+If you need to insert while you\'re in overtype mode, hit \fB^@\fR\. This inserts a single \fBSpace\fR into the text\.
+.
+.SS "Control and Meta characters"
+Each character is represented by a number\. For example, the number for \'A\' is 65 and the number for \'1\' is 49\. All of the characters which you normally see have numbers in the range of 32 \- 126 (this particular arbitrary assignment between characters and numbers is called the ASCII character set)\. The numbers outside of this range, from 0 to 255, aren\'t usually displayed, but sometimes have other special meanings\. The number 10, for example, is used for the line\-breaks\. You can enter these special, non\-displayed \fBcontrol characters\fR by first hitting \fB^Q\fR and then hitting a character in the range \fB@ A B C \.\.\. X Y Z [ ^ ] \e _\fR to get the number 0 \- 31, and ? to get 127\. For example, if you hit \fB^Q J\fR, you\'ll insert a line\-break character, or if you hit \fB^Q I\fR, you\'ll insert a \fBTab\fR character (which does the same thing the \fBTab\fR key does)\. A useful control character to enter is 12 (\fB^Q L\fR), which causes most printers to advance to the top of the page\. You\'ll notice that JOE displays this character as an underlined L\. You can enter the characters above 127, the \fBmeta characters\fR, by first hitting \fB^\e\fR\. This adds 128 to the next (possibly control) character entered\. JOE displays characters above 128 in inverse\-video\. Some foreign languages, which have more letters than English, use the meta characters for the rest of their alphabet\. You have to put the editor in \fBasis\fR mode to have these passed untranslated to the terminal\.
+.
+.P
+\fBNote:\fR JOE now normally passes all 8\-bits to the terminal unless the locale is set to C or POSIX\. If the locale is C or POSIX, then the \fBasis\fR flag determines if \fBmeta characters\fR are shown in inverse video or passed directly to the terminal\.
+.
+.P
+\fBNote:\fR In older version of JOE, you had to use \fBEsc \'\fR to enter control characters\.
+.
+.SH "Character sets and UTF\-8"
+JOE natively handles two classes of character sets: UTF\-8 and byte coded (like ISO\-8859\-1)\. For these character sets, the file is loaded as\-is into memory, and is exactly preserved during save, even if it contains UTF\-8 coding errors\.
+.
+.P
+It can not yet natively handle other major classes such as UTF\-16 or GB2312\. There are other restrictions: character sets must use LF (0x0A) or CR\-LF (0x0D \- 0x0A) as line terminators, space must be 0x20 and tab must be 0x09\. Basically, the files must be UNIX or MS\-DOS compatible text files\.
+.
+.P
+This means EBCDIC will not work properly (but you would need to handle fixed record length lines anyway) and character sets which use CR terminated lines (MACs) will not yet work\.
+.
+.P
+JOE now supports UTF\-16 (both big endian and little endian)\. It supports UTF\-16 by converting to UTF\-8 during load, and converting back to UTF\-16 during save\.
+.
+.P
+The terminal and the file can have different encodings\. JOE will translate between the two\. Currently, one of the two must be UTF\-8 for translation to work\.
+.
+.P
+The character set for the terminal and the default character set assumed for files is determined by the \'LC_ALL\' environment variable (and if that\'s not set, LC_CTYPE and LANG are also checked)\.
+.
+.P
+For example, if LC_ALL is set to:
+.
+.IP "" 4
+.
+.nf
+
+de_DE
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Then the character set will be ISO\-8859\-1\.
+.
+.P
+If LC_ALL is set to:
+.
+.IP "" 4
+.
+.nf
+
+de_DE\.UTF\-8
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The character set will be UTF\-8\.
+.
+.P
+Hit \fB^T E\fR to change the coding for the file\. Hit \fBTab\fR \fBTab\fR at this prompt to get a list of available codings\. There are a number of built\-in character sets, plus you can install character sets in the ~/\.joe/charmaps and /usr/share/joe/charmaps directories\.
+.
+.P
+Check: /usr/share/i18n/charmaps for example character set files\. Only byte oriented character sets will work\. Also, the file should not be gzipped (all of the charmap files in /usr/share/i18n/charmaps on my computer were compressed)\. The parser is very bad, so basically the file has to look exactly like the example one in /usr/share/joe/charmaps\.
+.
+.P
+You can hit \fB^K Space\fR to see the current character set\.
+.
+.P
+You can hit \fB^Q x\fR to enter a Unicode character if the file coding is UTF\-8\.
+.
+.SH "Prompts"
+Most prompts record a history of the responses you give them\. You can hit up and down arrow to step through these histories\.
+.
+.P
+Prompts are actually single line windows with no status line, so you can use any editing command that you normally use on text within the prompts\. The prompt history is actually just other lines of the same "prompt file"\. Thus you can can search backwards though the prompt history with the normal \fB^K F\fR command if you want\.
+.
+.P
+Since prompts are windows, you can also switch out of them with \fB^K P\fR and \fB^K N\fR\.
+.
+.SS "Completion and selection menus"
+You can hit \fBTab\fR in just about any prompt to request JOE to complete the word you are typing\. If JOE beeps, there are either no completions or many\. As with the "bash" shell, hit \fBTab\fR twice to bring up a list of all the possibilities\. This list is actually a menu, but by default, the cursor does not jump into it since it is usually easier to just type in your selection\. You can, however, jump into the menu window with \fB^K P\fR (move to previous window) and use the arrow keys and <Enter> to make your selection\. Also in a menu, you can hit the first letter of any of the items to make the cursor jump directly to it\. The \fB^T\fR option menu works like this\.
+.
+.P
+If the menu is too large to fit in the window, you can hit Page Up and Page Down to scroll it (even if you have not jumped into it)\.
+.
+.P
+\fBTab\fR completion works in the search and replace prompts as well\. In this case, JOE tries to complete the word based on the contents of the buffer\. If you need search for the \fBTab\fR character itself, you can enter it with \fB^Q Tab\fR\.
+.
+.P
+Also, you can hit \fBEsc Enter\fR in a text window to request JOE to complete the word you are typing\. As with the search prompt, JOE tries to complete the word based on the contents of the buffer\. It will bring up a menu of possibilities if you hit \fBEsc Enter\fR twice\.
+.
+.SH "Where am I?"
+Hit \fB^K Space\fR to have JOE report the line number, column number, and byte number on the last line of the screen\. The number associated with the character the cursor is on (its ASCII code) is also shown\. You can have the line number and/or column number always displayed on the status line by placing the appropriate escape sequences in the status line setup strings\. Edit the joerc file for details\.
+.
+.SH "What if I hit <strong>^K</strong> by accident?"
+Hit the space bar\. This runs an innocuous command (it shows the line number on the status bar)\.
+.
+.SH "Temporarily suspending the editor"
+If you need to temporarily stop the editor and go back to the shell, hit \fB^K Z\fR\. You might want to do this to stop whatever you\'re editing and answer an e\-mail message or read this man page, for example\. You have to type \fBfg\fR or \fBexit\fR (you\'ll be told which when you hit \fB^K Z\fR) to return to the editor\.
+.
+.SH "Searching for text"
+Hit \fB^K F\fR to have the editor search forwards or backwards for a text fragment (\fBstring\fR) for you\. You will be prompted for the text to search for\. After you hit \fBEnter\fR, you are prompted to enter options\.
+.
+.br
+You can just hit \fBEnter\fR again to have the editor immediately search forwards for the text, or you can enter one or more of these options:
+.
+.IP "\(bu" 4
+\fBb\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Search backwards instead of forwards\.
+.
+.IP "\(bu" 4
+\fBi\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Treat uppercase and lower case letters as the same when searching\. Normally uppercase and lowercase letters are considered to be different\.
+.
+.IP "\(bu" 4
+\fBnnn\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+(where \fBnnn\fR is a number) If you enter a number, JOE searches for the Nth occurrence of the text\. This is useful for going to specific places in files structured in some regular manner\.
+.
+.IP "\(bu" 4
+\fBr\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Replace text\. If you enter the \fBr\fR option, then you will be further prompted for replacement text\. Each time the editor finds the search text, you will be prompted as to whether you want to replace the found search text with the replacement text\. You hit: \fBy\fR to replace the text and then find the next occurrence, \fBn\fR to not replace this text, but to then find the next occurrence, \fBr\fR to replace all of the remaining occurrences of the search text in the remainder of the file without asking for confirmation (subject to the \fBnnn\fR option above), or \fB^C\fR to stop searching and replacing\.
+.
+.P
+You can also hit \fBB\fR or \fBBackspace\fR to back up to the previously found text (if it had been replaced, the replacement is undone)\.
+.
+.IP "\(bu" 4
+\fBa\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+The search covers all loaded buffers\. So to replace all instances of "foo" with "bar" in all \.c files in the current directory:
+.
+.IP "" 4
+.
+.nf
+
+joe *\.c
+   ^K F
+       foo <Enter>
+       ra <Enter>
+       bar <Enter>
+.
+.fi
+.
+.IP "" 0
+.
+.IP "\(bu" 4
+\fBe\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+The search covers all files in the grep or make error list\. You can use a UNIX command to generate a list of files and search and replace through the list\. So to replace all instances of "foo" with "bar" in all \.c files which begin with f\. You can also use "ls" and "find" instead of grep to create the file list\.
+.
+.IP "" 4
+.
+.nf
+
+Esc G
+  grep \-n foo f*\.c <Enter>
+^K F
+       foo <Enter>
+   re <Enter>
+   bar <Enter>
+.
+.fi
+.
+.IP "" 0
+.
+.IP "\(bu" 4
+\fBx\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+JOE will use the standard syntax for regular expressions if this option is given\. In the standard syntax, these characters have their special meanings directly, and do not have to be escaped with backslash: \., *, +, ?, {, }, (, ), |, ^, $ and [\.
+.
+.IP "\(bu" 4
+\fBy\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+JOE will use the JOE syntax for regular expressions instead of the standard syntax\. This overrides the "\-regex" option\.
+.
+.IP "\(bu" 4
+\fBv\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+JOE will send debug information about the regular expression to the startup log\. The log can be viewed with the showlog command\.
+.
+.P
+You can hit \fB^L\fR to repeat the previous search\.
+.
+.P
+You can hit \fB^K H\fR at the search and replace options prompt to bring up a list of all search and replace options\.
+.
+.SS "Regular Expressions"
+A number of special character sequences may be entered as search text:
+.
+.IP "\(bu" 4
+\fB\e*\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This finds zero or more of the item to the left\. For example, if you give \fBAB\e*C\fR as the search text, JOE will try to find an A followed by any number of Bs, and then a C\.
+.
+.IP "\(bu" 4
+\fB\e+\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This finds one or more of the item to the left\. For example, if you give \fBAB\e+C\fR as the search text, JOE will try to find an A followed by one or more Bs, and then a C\.
+.
+.IP "\(bu" 4
+\fB\e?\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This indicates that the item to the left is optional\. For example, if you give \fBAB\e?C\fR as the search text, JOE will find AC or ABC\.
+.
+.IP "\(bu" 4
+\fB\e{min,max}\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This indicates that JOE should try to find a string with a specific number of occurrences of the item to the left\. For example, \fBAX\e{2,5}B\fR will match these strings: AXXB, AXXXB, AXXXXB, and AXXXXXB\. Min can be left out to indicate 0 occurrences\. Max (and the comma) can be left out to indicate any number of occurrences\.
+.
+.IP "\(bu" 4
+\fB\e\.\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This finds exactly one character\. For example, if you give \fBA\e\.B\fR as the search text, JOE will find AXB, but not AB or AXXB\.
+.
+.IP "\(bu" 4
+\fB\e!\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This works like \fB\.\fR, but matches a balanced C\-language expression\. For example, if you search for \fBmalloc(\e!\e*)\fR, then JOE will find all function calls to \fBmalloc\fR, even if there was a \fB)\fR within the parenthesis\.
+.
+.IP "\(bu" 4
+\fB\e|\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This finds the item on the left or the item on the right\. For example, if you give \fBA\e|B\fR as the search text, JOE will try to find either an A or a B\.
+.
+.IP "\(bu" 4
+\fB\e( \e)\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Use these to group characters together\. For example, if you search for \fB\e(foo\e)\e+\fR, then JOE will find strings like "foo", and "foofoofoo"\.
+.
+.IP "\(bu" 4
+\fB^ \e$\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+These match the beginnings and endings of lines\. For example, if you give \fB^test\e$\fR, then JOE with find \fBtest\fR on a line by itself\.
+.
+.IP "\(bu" 4
+\fB\e\fI\e\e\fR\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+These match the beginnings and endings of words\. For example, if you give \fB\e\fIis\e\e\fR\fR, then JOE will find the word "is" but will not find the "is" in "this"\.
+.
+.IP "\(bu" 4
+\fB\e[\.\.\.]\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches any single character which appears within the brackets\. For example, if \fB\e[Tt]his\fR is entered as the search string, then JOE finds both \fBThis\fR and \fBthis\fR\. Ranges of characters can be entered within the brackets\. For example, \fB\e[A\-Z]\fR finds any uppercase letter\. If the first character given in the brackets is \fB^\fR, then JOE tries to find any character not given in the the brackets\. To include \fB\-\fR itself, include it as the last or first character (possibly after \fB^\fR)\.
+.
+.IP "\(bu" 4
+\fB\e\e\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Matches a single \e\.
+.
+.IP "\(bu" 4
+\fB\en\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This finds the special end\-of\-line or line\-break character\.
+.
+.P
+A number of special character sequences may also be given in the replacement string:
+.
+.IP "\(bu" 4
+\fB\e&\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This gets replaced by the text which matched the search string\. For example, if the search string was \fB\e\fI\e*\e\e\fR\fR, which matches words, and you give \fB"\e&"\fR, then JOE will put quote marks around words\.
+.
+.IP "\(bu" 4
+\fB\e1 \- \e9\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+These get replaced with the text which matched the Nth grouping; the text within the Nth set of \e( \e)\.
+.
+.IP "\(bu" 4
+\fB\el, \eu\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Convert the next character of the replacement text to lowercase or uppercase\.
+.
+.IP "\(bu" 4
+\fB\eL, \eU\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Convert all following replacement text to lowercase or uppercase\. Conversion stops when \eE is encountered\.
+.
+.IP "\(bu" 4
+\fB\e\e\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Use this if you need to put a \fB\e\fR in the replacement string\.
+.
+.IP "\(bu" 4
+\fB\en\fR
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Use this if you need to put a line\-break in the replacement string\.
+.
+.P
+Some examples:
+.
+.P
+Suppose you have a list of addresses, each on a separate line, which starts with "Address:" and has each element separated by commas\. Like so:
+.
+.P
+Address: S\. Holmes, 221b Baker St\., London, England
+.
+.P
+If you wanted to rearrange the list, to get the country first, then the city, then the person\'s name, and then the address, you could do this:
+.
+.P
+Type \fB^K F\fR to start the search, and type:
+.
+.P
+\fBAddress:\e(\e\.\e*\e),\e(\e\.\e*\e),\e(\e\.\e*\e),\e(\e\.\e*\e)\e$\fR
+.
+.P
+to match "Address:", the four comma\-separated elements, and then the end of the line\. When asked for options, you would type \fBr\fR to replace the string, and then type:
+.
+.P
+\fBAddress:\e4,\e3,\e1,\e2\fR
+.
+.P
+To shuffle the information the way you want it\. After hitting return, the search would begin, and the sample line would be changed to:
+.
+.P
+Address: England, London, S\. Holmes, 221b Baker St\.
+.
+.P
+ \fI\fR
+.
+.SS "Escape sequences"
+JOE understands the following escape sequences withing search and replacement strings:
+.
+.IP "\(bu" 4
+\ex{10ffff}
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches a specific Unicode code point given in hexadecimal\.
+.
+.IP "\(bu" 4
+\exFF
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches a specific character specified in hexadecimal\.
+.
+.IP "\(bu" 4
+\e377
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches a specific character specified in octal\.
+.
+.IP "\(bu" 4
+\ep{Ll}
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches any character in the named Unicode category or block\.
+.
+.P
+The block names, such as "Latin\-1 Supplement" or "Arabic" can be found here:
+.
+.P
+Unicode Blocks \fIftp://ftp\.unicode\.org/Public/8\.0\.0/ucd/Blocks\.txt\fR
+.
+.P
+The category names such as "Ll" can be found here:
+.
+.P
+Unicode Categories \fIftp://ftp\.unicode\.org/Public/5\.1\.0/ucd/UCD\.html#General_Category_Values\fR
+.
+.P
+Note that a single letter matches all of the category names which start with that letter\. For example, \ep{N} (any number) include \ep{Nd} (decimal digit), \ep{Nl} (letter number) and \ep{No} (other number)\.
+.
+.IP "\(bu" 4
+\ed
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches any Unicode digit\. This is the same as \ep{Nd}\.
+.
+.IP "\(bu" 4
+\eD
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches anything except for a Unicode digit\. This is the same as \e[^\ep{Nd}]\.
+.
+.IP "\(bu" 4
+\ew
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches any word character\. This is the same as \e[^\ep{C}\ep{P}\ep{Z}]\.
+.
+.IP "\(bu" 4
+\eW
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches anything except for a word character\. This is the same as \e[\ep{C}\ep{P}\ep{Z}]\.
+.
+.IP "\(bu" 4
+\es
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches any space character\. This is the same as \e[\et\er\ef\en\ep{Z}]\.
+.
+.IP "\(bu" 4
+\eS
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches anything except for a spacing character\. This is the same as \e[^\et\er\ef\en\ep{Z}]\.
+.
+.IP "\(bu" 4
+\ei
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches an identifier start character\. This is the same as \e[\ep{L}\ep{Pc}\ep{Nl}]\.
+.
+.IP "\(bu" 4
+\eI
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches anything except for an identifier start character\. This is the same as \e[^\ep{L}\ep{Pc}\ep{Nl}]\.
+.
+.IP "\(bu" 4
+\ec
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches an identifier continuation character\. This is the same as \e[\ei\ep{Mn}\ep{Mc}\ep{Nd}\ex{200c}\ex{200d}]\.
+.
+.IP "\(bu" 4
+\eC
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+This matches anything except for an identifier continuation character\. This is the same as \e[^\ei\ep{Mn}\ep{Mc}\ep{Nd}\ex{200c}\ex{200d}]\.
+.
+.IP "\(bu" 4
+\et Tab
+.
+.IP "\(bu" 4
+\en Newline
+.
+.IP "\(bu" 4
+\er Carriage return
+.
+.IP "\(bu" 4
+\eb Backspace
+.
+.IP "\(bu" 4
+\ea Alert
+.
+.IP "\(bu" 4
+\ef Formfeed
+.
+.IP "\(bu" 4
+\ee Escape
+.
+.IP "\(bu" 4
+\e\e Backslash
+.
+.IP "" 0
+.
+.SH "Incremental search"
+Use \fBEsc S\fR to start an increment search forwards, or \fBEsc R\fR to start an incremental search backwards\. As you type the search string, the cursor will jump to the first text that matches the regular expression you have entered so far\.
+.
+.P
+Hit \fBEsc S\fR or \fBEsc R\fR again to find the next occurrence of the text or to switch the direction of the search\.
+.
+.P
+\fB^S\fR, \fB^\e\fR and \fB^L\fR have the same effect as \fBEsc S\fR\. \fB^R\fR has the same effect as \fBEsc R\fR\. These keys are to support JMACS\.
+.
+.P
+Hit \fBBackspace\fR to undo the last incremental search action\. The last action could be a repeat of a previous search or the entering of a new character\.
+.
+.P
+Use \fB^Q\fR to insert control characters into the search text\. Previously, ` could also be used for this\.
+.
+.P
+Hit any other key to exit the increment search\.
+.
+.SH "Goto matching delimiter"
+Hit \fB^G\fR to jump between matching delimiters\. This works on both character delimiters (like \'(\' and \')\') and word delimiters for languages like Pascal and Verilog which use "begin" and "end" to delimit blocks\. It also works for matching start and end tags in XML\. If a word is not known, \fB^G\fR starts a search with the word moved into the search prompt\.
+.
+.P
+For \fB^G\fR to work on word delimiters, the cursor must be positioned on the first letter of the word\. So in XML, if the cursor is on the < in <foo>, it will jump to the >\. But if it is one the \'f\', it will jump to the matching </foo>\. Likewise, in C, \fB^G\fR will jump between #if, #else and #endif, but you need to position the cursor on the letter, not the \'#\'\.
+.
+.P
+\fB^G\fR is smart enough to skip delimiters found in quoted or commented\-out matter\. You need to tell JOE how your language indicates this: see the \fBftyperc\fR file for examples of how this is done\.
+.
+.P
+The are a number of options which control the behavior of \fB^G\fR\. These options control which kinds of comments \fB^G\fR can skip over:
+.
+.IP "\(bu" 4
+c_comment
+.
+.IP "\(bu" 4
+cpp_comment
+.
+.IP "\(bu" 4
+pount_comment
+.
+.IP "\(bu" 4
+semi_comment
+.
+.IP "\(bu" 4
+vhdl_comment
+.
+.IP "" 0
+.
+.P
+These options determine which kinds of strings \fB^G\fR can skip over:
+.
+.IP "\(bu" 4
+single_quoted
+.
+.IP "\(bu" 4
+double_quoted
+.
+.IP "" 0
+.
+.P
+This option allows an annotated syntax file to determine which text can be counted as comments or strings which can be skipped over by \fB^G\fR:
+.
+.IP "\(bu" 4
+highlighter_context
+.
+.IP "" 0
+.
+.P
+This option enables the use of syntax files to identify comments and strings which should be skipped over during \fB^G\fR matching\. The syntax file states should be annotated with the \fBstring\fR and \fBcomment\fR keywords for this to work\.
+.
+.IP "\(bu" 4
+text_delimiters
+.
+.IP "" 0
+.
+.P
+This option provides a list of word delimiters to match\. For example, "begin=end:if=elif=else=endif" means that \fB^G\fR will jump between the matching if, elif, else and endif\. It will also jump between begin and end\.
+.
+.P
+\fB^G\fR has a built\-in table for matching character delimiters\- it knows that \fB(\fR goes with \fB)\fR\.
+.
+.P
+\fB^G\fR has a built\-in parser to handle start/end tag matching for XML\.
+.
+.P
+ \fI\fR
+.
+.SH "Regions"
+If you want to move, copy, save or delete a specific section of text, you can do it with highlighted blocks\. First, move the cursor to the start of the section of text you want to work on, and press \fB^K B\fR\. Then move the cursor to the character just after the end of the text you want to affect and press \fB^K K\fR\. The text between the \fB^K B\fR and \fB^K K\fR should become highlighted\. Now you can move your cursor to someplace else in your document and press \fB^K M\fR to move the highlighted text there\.
+.
+.br
+You can press \fB^K C\fR to make a copy of the highlighted text and insert it to where the cursor is positioned\. \fB^K Y\fR to deletes the highlighted text\. \fB^K W\fR, writes the highlighted text to a file\.
+.
+.P
+A very useful command is \fB^K /\fR, which filters a block of text through a UNIX command\. For example, if you select a list of words with \fB^K B\fR and \fB^K K\fR, and then type \fB^K / sort\fR, the list of words will be sorted\. Another useful UNIX command for \fB^K /\fR, is \fBtr\fR\. If you type \fB^K / tr a\-z A\-Z\fR, then all of the letters in the highlighted block will be converted to uppercase\.
+.
+.SS "How do I deselect a highlighted region?"
+After you are finished with some region operations, you can just leave the highlighting on if you don\'t mind it (but don\'t accidentally hit \fB^K Y\fR)\. If it really bothers you, however, just hit \fB^K B ^K K\fR, to turn the highlighting off\.
+.
+.P
+Beginning with JOE 4\.2, you can hit \fB^C\fR to cancel the region selection\.
+.
+.SS "New ways of selecting regions"
+The classic way is to hit \fB^K B\fR at the beginning and \fB^K K\fR at the end\. These set pointers called markb and markk\. Once these are set you can jump to markb with \fBEsc B\fR and jump to markk with \fBEsc K\fR\.
+.
+.P
+New way: hit Ctrl\-\fBRight Arrow\fR to start selecting rightward\. Each time you hit Ctrl\-\fBRight Arrow\fR, the block is extended one more to the right\. This uses a simple macro: "begin_marking,rtarw,toggle_marking"\.
+.
+.P
+Unfortunately, there is no standard way to get the keysequence given by the terminal emulator when you hit Ctrl\-\fBRight Arrow\fR\. Instead you have to determine this sequence yourself and enter it directly in the joerc file\. Some examples are given for Xterm and gnome\-terminal\. Hit \fB^Q\fR Ctrl\-\fBRight Arrow\fR within JOE to have the sequence shown on your screen\. Note that Putty uses \fBEsc Esc [ C\fR which will not appear with \fB^Q Right Arrow\fR (also \fBEsc Esc\fR is the set bookmark command, so you need to unbind it to do this in Putty)\.
+.
+.P
+Also you can hit Ctrl\-\fBDelete\fR to cut and Ctrl\-\fBInsert\fR to paste if the sequence for these keys are known\.
+.
+.P
+The mouse can also be used to select text if mouse support is enabled in JOE\.
+.
+.SH "Indenting program blocks"
+Auto\-indent mode is toggled with the \fB^T I\fR command\. The \fBjoerc\fR file is normally set up so that files with names ending with \.p, \.c or \.h have auto\-indent mode enabled\. When auto\-indent mode is enabled and you hit \fBEnter\fR, the cursor will be placed in the same column that the first non\-whitespace character was on in the original line\.
+.
+.P
+You can use the \fB^K ,\fR and \fB^K \.\fR commands to shift a block of text to the left or right\. If no highlighting is set when you give these commands, the program block (as indicated by indentation) that the cursor is located in will be selected, and will be moved by subsequent \fB^K ,\fR and \fB^K \.\fR commands\.
+.
+.P
+The number of columns these commands shift by and the character used for shifting can be set through the istep and indentc options\. These options are available in the \fB^T\fR menu\. Also, \fB^T =\fR can be used to quickly select from a number of common values for indentation step and character\.
+.
+.P
+JOE has a number of additional options related to indenting programs:
+.
+.IP "\(bu" 4
+smartbacks
+.
+.br
+Enable smart backspace and tab\. When this mode is set \fBBackspace\fR and \fBTab\fR indent or unindent based on the values of the istep and indentc options\.
+.
+.br
+
+.
+.IP "\(bu" 4
+smarthome
+.
+.br
+The \fBHome\fR and \fB^A\fR keys first move the cursor to the beginning of the line, then if hit again, to the first non\-blank character\.
+.
+.br
+
+.
+.IP "\(bu" 4
+indentfirst
+.
+.br
+Smart home goes to first non\-blank character first, instead of going to the beginning of the line first\.
+.
+.br
+
+.
+.IP "\(bu" 4
+purify
+.
+.br
+Fix indentation if necessary before shifting or smart backspace\. For example, if indentation uses a mix of tabs and spaces, and indentc is space, then indentation will be converted to all spaces before the shifting operation\.
+.
+.br
+
+.
+.IP "\(bu" 4
+guess_indent
+.
+.br
+When set, JOE tries to guess the indentation character and indentation step based on the contents of the file\. The algorithm is to find the greatest common factor of the three most common indentations found in the file\.
+.
+.br
+
+.
+.IP "" 0
+.
+.SH "Rectangle mode"
+Type \fB^T X\fR to have \fB^K B\fR and \fB^K K\fR select rectangular blocks instead of stream\-of\-text blocks\. This is also known as columnar mode\. This mode is useful for moving, copying, deleting or saving columns of text\. You can also filter columns of text with the \fB^K /\fR command\- if you want to sort a column, for example\. The insert file command, \fB^K R\fR is also affected\.
+.
+.P
+When rectangle mode is selected, overtype mode is also useful (\fB^T T\fR)\. When overtype mode is selected, rectangles will replace existing text instead of getting inserted before it\. Also the delete block command (\fB^K Y\fR) will clear the selected rectangle with \fBSpaces\fR and \fBTabs\fR instead of deleting it\. Overtype mode is especially useful for the filter block command (\fB^K /\fR), since it will maintain the original width of the selected column\.
+.
+.SH "Picture mode"
+Use \fB^T P\fR to enter or exit picture mode\. Picture mode helps with ASCII drawings\.
+.
+.P
+Picture mode controls how JOE handles the case where the cursor is past the ends of lines\. This happens when you use the up or down arrow keys to move the cursor from the end of a long line to a short line\.
+.
+.P
+If you attempt to type a character in this case:
+.
+.P
+If picture mode is off, the cursor will jump to the end of the line and insert it there\.
+.
+.P
+If picture mode is on, the line is filled with spaces so that the character can be inserted at the cursor position\.
+.
+.SH "Windows"
+You can edit more than one file at the same time or edit two or more different places of the same file\. To do this, hit \fB^K O\fR, to split the screen into two windows\. Use \fB^K P\fR or \fB^K N\fR to move the cursor into the top window or the lower window\. Use \fB^K E\fR to edit a new file in one of the windows\. A window will go away when you save the file with \fB^K X\fR or abort the file with \fB^C\fR\. If you abort a file which exists in two windows, one of the window goes away, not the file\.
+.
+.P
+You can hit \fB^K O\fR within a window to create even more windows\. If you have too many windows on the screen, but you don\'t want to eliminate them, you can hit \fB^K I\fR\. This will show only the window the cursor is in, or if there was only one window on the screen to begin with, try to fit all hidden windows on the screen\. If there are more windows than can fit on the screen, you can hit \fB^K N\fR on the bottom\-most window or \fB^K P\fR on the top\-most window to get to them\.
+.
+.P
+If you gave more than one file name to JOE on the command line, each file will be placed in a different window\.
+.
+.P
+You can change the height of the windows with the \fB^K G\fR and \fB^K T\fR commands\.
+.
+.SS "Windowing system model"
+JOE has an unusual model for its windowing system\. Basically you have a ring of windows, but only a section of this ring may fit on the screen\. The windows not on the screen still exist, they are just scrolled off\. When you hit \fB^K N\fR on the bottom window of the screen, it scrolls further windows from the ring onto the screen, possibly letting the top window scroll out of view\.
+.
+.P
+Native JOE tries to keep each loaded buffer in a window, so users can find all of the buffers by scrolling through the windows\. The \fBexplode\fR command (\fB^K I\fR) either expands all windows to the size of the screen so that only one window can fit on the screen, or shrinks them all as much as possible to fit many on the screen\.
+.
+.P
+On the other hand, JOE supports "orphan" buffers\- files loaded into the editor, but which are not in a window\. \fB^C\fR normally closes a window and discards the buffer that was in it\. If you hit \fB^C\fR on the last remaining window, it will normally exit the editor\. However, if there are orphan buffers, \fB^C\fR will instead load them into this final window to give you a chance to explicitly discard them\. If the \fBorphan\fR option is given on the command line, as in \fBjoe \-orphan *\.c\fR, then JOE only loads the first file into a window and leaves all the rest as orphans\.
+.
+.P
+\fBorphan\fR also controls whether the edit command \fB^K E\fR creates a new window for a newly loaded file, or reuses the current window (orphaning its previous occupant)\.
+.
+.P
+The \fBbufed\fR command prompts for a name of a buffer to switch into a window\. Its completion list will show all buffers, including orphans and buffers which appear in other windows\. \fBEsc V\fR and \fBEsc U\fR (\fBnbuf\fR and \fBpbuf\fR commands) allow you to cycle through all buffers within a single window\.
+.
+.P
+Windows maintain a stack of occupants to support the pop\-up shell window feature\. When a pop\-up window is dismissed, the previous buffer is returned to the window\.
+.
+.SH "Scratch buffers"
+Scratch buffers are buffers which JOE does not worry about trying to preserve\. JOE will not ask to save modified scratch buffers\. Pop\-up shell windows, the startup log and compile and grep message windows are scratch buffers\. You can create your own scratch buffer with the \fBscratch\fR command\.
+.
+.P
+The following commands load scratch buffers:
+.
+.IP "\(bu" 4
+\fBshowlog\fR Show startup log
+.
+.IP "\(bu" 4
+\fBmwind\fR Show message window (compile / grep messages from \fBEsc C\fR and \fBEsc G\fR commands)\.
+.
+.IP "" 0
+.
+.SH "Keyboard macros"
+Macros allow you to record a series of keystrokes and replay them with the press of two keys\. This is useful to automate repetitive tasks\. To start a macro recording, hit \fB^K [\fR followed by a number from 0 to 9\. The status line will display (Macro n recording\.\.\.)\. Now, type in the series of keystrokes that you want to be able to repeat\. The commands you type will have their usual effects\. Hit \fB^K ]\fR to stop recording the macro\. Hit \fB^K\fR followed by the number you recorded the macro in to execute one iteration of the key\-strokes\.
+.
+.P
+For example, if you want to put "**" in front of a number of lines, you can type:
+.
+.P
+\fB^K [ 0 ^A **\fR\fIdown arrow\e\fR \fB^K ]\fR
+.
+.P
+Which starts the macro recording, moves the cursor to the beginning of the line, inserts "**", moves the cursor down one line, and then ends the recording\. Since we included the key\-strokes needed to position the cursor on the next line, we can repeatedly use this macro without having to move the cursor ourselves, something you should always keep in mind when recording a macro\.
+.
+.SS "Keyboard macro subroutines"
+If you find that the macro you are recording itself has a repeated set of key\-strokes in it, you can record a macro within the macro, as long as you use a different macro number\. Also you can execute previously recorded macros from within new macros\.
+.
+.SS "Query suspend"
+If your macro includes a prompt for user input, and you want the user to fill in the prompt every time the macro is executed, hit \fB^K ?\fR at the point in the macro recording where the user action is required\. Keyboard input will not be recorded at this point\. When the user completes the prompt, macro recording will continue\.
+.
+.P
+When the macro is executed, the macro player will pause at the point where \fB^K ?\fR was entered to allow user input\. When the user completes the prompt, the player continues with the rest of the macro\.
+.
+.SS "Repeat"
+You can use the repeat command, \fB^K \e\fR, to repeat a macro, or any other edit command or even a normal character, a specified number of times\. Hit \fB^K \e\fR, type in the number of times you want the command repeated and press \fBEnter\fR\. The next edit command you now give will be repeated that many times\. For example, to delete the next 20 lines of text, type:
+.
+.P
+\fB^K \e 20\fR\fIreturn\fR\fB^Y\fR
+.
+.SH "Macros and commands"
+A macro is a comma separated list of commands\. When the macro is executed, each command is executed until either the end of the list is reached, or one of the commands fails (non\-zero return value from the command)\. Failed commands beep if you have beeps enabled (\fB^T B\fR)\.
+.
+.P
+Hit \fBEsc D\fR to insert the current set of keyboard macros as text into the current buffer\. For example, the "**" insert macro above looks like this:
+.
+.IP "" 4
+.
+.nf
+
+home,"**",dnarw ^K 0    Macro 0
+.
+.fi
+.
+.IP "" 0
+.
+.P
+You could insert this into your \.joerc file and change the key sequence (the \fBK 0\fR) to something more permanent\.
+.
+.SS "Define your own"
+You can bind macros to key sequences or define your own named macros in the joerc file\. For example, this will define a macro called \fBfoo\fR:
+.
+.IP "" 4
+.
+.nf
+
+:def foo eof,bol
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\fBfoo\fR will position the cursor at the beginning of the last line of the file\. \fBeof\fR jumps to the end of the file\. \fBbol\fR jumps to the beginning of a line\. Once a macro has been named this way it will show up in the completion list of the \fBEsc X\fR command prompt\.
+.
+.SS "Command prompt"
+You can execute a macro directly by typing it into the command prompt\. Hit \fBEsc X\fR to bring up the command prompt\. Hit \fBTab\fR at this prompt for a completion list of all available commands\.
+.
+.P
+Here is a \fIcomplete list of commands\fR\.
+.
+.SS "Macro don\'t stop modifier"
+Sometimes, you expect commands to sometimes fail, but want the rest of the commands in the list to be executed anyway\. To mark a command which is allowed to fail, postfix it with \'!\'\. For example, here a macro which hits down page in the window above:
+.
+.IP "" 4
+.
+.nf
+
+prevw,pgdn!,nextw
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If prevw fails, the macro is aborted as usual\. Even if pgdn fails (already at end of buffer), nextw will be executed so that the cursor is returned to the original window\.
+.
+.SS "Macro repeat argument modifiers"
+Repeat arguments can be specified with \fB^K \e\fR\. When a command is executed with a repeat argument, it is repeatedly executed the specified number of times\. If the repeat argument is negative, an opposite command (if one exists) is executed instead\. For example, if you repeat "rtarw" \-3 times, "ltarw" will be repeated 3 times\. If a negative argument is given for a command which does not have an opposite, the repeat argument is ignored\.
+.
+.P
+Normally, if a repeat argument is specified for a macro, the macro is simply repeated the given number of times\. If a negative argument is given, the argument is ignored\.
+.
+.P
+Sometimes you want to allow negative arguments for macros and have their behavior modified\. To do this, postfix each command within the macro which should be switched to its opposite for negative arguments with \'\-\'\. For example, here is the page down other window macro:
+.
+.IP "" 4
+.
+.nf
+
+prevw,pgdn\-!,nextw
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Now if you execute this with an argument of \-2, it will be repeated twice, but pgup will be executed instead of pgdn\. (note that several postfix modifiers can be placed after each command)\.
+.
+.P
+Sometimes when a repeat argument is given to macro, you want only one of the commands in the list to be repeated, not the entire macro\. This can be indicated as follows:
+.
+.IP "" 4
+.
+.nf
+
+prevw,pgdn#!,nextw
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If this is executed with an argument of 2, prevw is executed once, pgdn is executed twice, and nextw is executed once\.
+.
+.P
+Finally, even more complex semantics can be expressed with the "if" command:
+.
+.IP "" 4
+.
+.nf
+
+if~,"arg<0",then,
+    ltarw,
+else,
+    rtarw,
+endif
+.
+.fi
+.
+.IP "" 0
+.
+.P
+When the macro is executed, the "arg" math variable is set to the given repeat argument\. The "argset" variable is set to true if the user set an argument, even if it\'s 1\. If no argument was given, argset is false\.
+.
+.P
+If any command in the list is postfixed with ~ (if above), the macro is not repeated, even if there is an argument\. \'arg\' is still set to the given repeat count, however\.
+.
+.SS "\'psh\'/\'query\' interaction"
+The \'psh\' command saves the \fB^K B\fR and \fB^K K\fR positions on a stack\. When the macro completes, (or when the \'pop\' command is called) the positions are restored\.
+.
+.P
+The \'query\' command suspends macro execution until the current dialog is complete\. It also suspends the automatic \'pop\' which happens at the end of a macro\- so if the macro ends in a dialog you often want to call \'query\' to prevent the \fB^K B\fR \fB^K K\fR positions from being restored too early\.
+.
+.SH "Tags search"
+If you are editing a large C program with many source files, you can use the \fBctags\fR program to generate a \fBtags\fR file\. This file contains a list of program symbols and the files and positions where the symbols are defined\.
+.
+.P
+First, create the tags file with the "ctags" program\. For example:
+.
+.IP "" 4
+.
+.nf
+
+ctags *\.c *\.h
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This will create a file called "tags" in the current directory\.
+.
+.P
+JOE looks for the "tags" file in the current directory\. If there is none, it will try to open the file specified by the TAGS environment variable\.
+.
+.P
+Paths in the tags file are always relative to location of the tags file itself\.
+.
+.P
+The tags file contains a list of identifier definition locations in one of these formats:
+.
+.IP "" 4
+.
+.nf
+
+identifier filename /search\-expression/[;comments]
+
+identifier filename ?search\-expression?[;comments]
+
+identifier filename line\-number[;comments]
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Some versions of ctags include class\-names in the identifiers:
+.
+.IP "" 4
+.
+.nf
+
+class::member
+.
+.fi
+.
+.IP "" 0
+.
+.P
+In this case, JOE will match on any of these strings:
+.
+.IP "" 4
+.
+.nf
+
+member
+::member
+class::member
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Some versions of ctags include a filename in the identifier:
+.
+.IP "" 4
+.
+.nf
+
+filename:identifier
+.
+.fi
+.
+.IP "" 0
+.
+.P
+In this case JOE will only find the identifier if the buffer name matches the filename\.
+.
+.P
+The search\-expression is a vi regular expression, but JOE only supports the following special characters:
+.
+.IP "" 4
+.
+.nf
+
+^ at the beginning means expression starts at beginning of line
+
+$ at the end means expression ends at end of line
+
+\ex quote x (suppress meaning of /, ?, ^ or $)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Type \fB^K ;\fR to bring up a tags search prompt\. If the cursor had been on an identifier, the prompt is pre\-loaded with it\. Tab completion works in this prompt (it uses the tags file to find completions)\.
+.
+.P
+When you hit \fBEnter\fR, the tags search commences:
+.
+.P
+If there is one and only one match, JOE will jump directly to the definition\.
+.
+.P
+If there are multiple matches, then the behavior is controlled by the notagsmenu option\. If notagsmenu is enabled JOE jumps to the first definition\. If you hit \fB^K ;\fR again before hitting any other keys, JOE jumps to the next definition, and so on\. The "tagjump" command also performs this function\.
+.
+.P
+If notagsmenu is disabled, JOE brings up a menu of all the matches\. You select the one you want and JOE jumps to it\. If you hit \fB^K ;\fR again before hitting any other keys, the same menu re\-appears with the cursor left in the original location\.
+.
+.P
+You can hit \fB^K \-\fR to move the cursor back to the original location before the tags search (often \fB^C\fR will work as well)\.
+.
+.P
+Since \fB^K ;\fR loads the definition file into the current window, you probably want to split the window first with \fB^K O\fR, to have both the original file and the definition file loaded\.
+.
+.SH "Calculator"
+JOE has a built\-in calculator which can be invoked with \fBEsc M\fR\.
+.
+.SS "Math functions"
+sin, cos, tan, exp, sqrt, cbrt, ln, log, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, int, floor, ceil, abs, erf, erfc, j0, j1, y0, y1
+.
+.SS "Variables"
+.
+.IP "\(bu" 4
+e
+.
+.br
+Set to \'e\'
+.
+.br
+
+.
+.IP "\(bu" 4
+pi
+.
+.br
+Set to \'pi\'
+.
+.br
+
+.
+.IP "\(bu" 4
+top
+.
+.br
+Set to line number of top window line
+.
+.br
+
+.
+.IP "\(bu" 4
+lines
+.
+.br
+Set to number of lines in file
+.
+.br
+
+.
+.IP "\(bu" 4
+line
+.
+.br
+Set to current line number
+.
+.br
+
+.
+.IP "\(bu" 4
+col
+.
+.br
+Set to current column number
+.
+.br
+
+.
+.IP "\(bu" 4
+byte
+.
+.br
+Set to current byte number
+.
+.br
+
+.
+.IP "\(bu" 4
+size
+.
+.br
+Set to buffer size
+.
+.br
+
+.
+.IP "\(bu" 4
+height
+.
+.br
+Set to window height
+.
+.br
+
+.
+.IP "\(bu" 4
+width
+.
+.br
+Set to window width
+.
+.br
+
+.
+.IP "\(bu" 4
+char
+.
+.br
+Set to ASCII val of character under cursor
+.
+.br
+
+.
+.IP "\(bu" 4
+markv
+.
+.br
+True if there is a valid block set (^KB \.\.\. ^KK)
+.
+.br
+
+.
+.IP "\(bu" 4
+rdonly
+.
+.br
+True if file is read\-only
+.
+.br
+
+.
+.IP "\(bu" 4
+arg
+.
+.br
+Current repeat argument
+.
+.br
+
+.
+.IP "\(bu" 4
+argset
+.
+.br
+True if a repeat argument was given
+.
+.br
+
+.
+.IP "\(bu" 4
+is_shell
+.
+.br
+True if executed in an active shell window
+.
+.br
+
+.
+.IP "\(bu" 4
+no_windows
+.
+.br
+No\. buffer windows on the screen
+.
+.br
+
+.
+.IP "\(bu" 4
+ans
+.
+.br
+Result of previous expression
+.
+.br
+
+.
+.IP "" 0
+.
+.SS "Commands"
+.
+.IP "\(bu" 4
+hex
+.
+.br
+Hex display mode
+.
+.br
+
+.
+.IP "\(bu" 4
+dec
+.
+.br
+Decimal display mode
+.
+.br
+
+.
+.IP "\(bu" 4
+ins
+.
+.br
+Insert \'ans\' into buffer
+.
+.br
+
+.
+.IP "\(bu" 4
+sum
+.
+.br
+Sum of numbers in block
+.
+.br
+
+.
+.IP "\(bu" 4
+cnt
+.
+.br
+Count numbers in block
+.
+.br
+
+.
+.IP "\(bu" 4
+avg
+.
+.br
+Average value of numbers in block
+.
+.br
+
+.
+.IP "\(bu" 4
+dev
+.
+.br
+Standard deviation of numbers in block
+.
+.br
+
+.
+.IP "\(bu" 4
+eval
+.
+.br
+Evaluate math expressions in block (or whole file if no block set)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+joe(\.\.\.)
+.
+.br
+Execute a JOE macro (argument in same format as joerc file macros)\. Return value of JOE macro is returned (for macro success, return true (non\-zero))\.
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+For example:
+.
+.IP "" 4
+.
+.nf
+
+joe(sys,"[ 1 == 1 ]",rtn)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+([ 1 == 1 ]) is a shell command\. "[" is a synonym for the "test" UNIX command\.
+.
+.P
+Returns true\.
+.
+.P
+Remember: argument for JOE macro command "if" is a math expression\. So for example, the macro:
+.
+.IP "" 4
+.
+.nf
+
+if,"joe(sys,\e"[ 1 == 1 ]\e",rtn)",then,"TRUE",endif
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Types TRUE into the buffer\.
+.
+.SS "Operators:"
+.
+.IP "\(bu" 4
+!x
+.
+.br
+Logical not of x\.
+.
+.br
+
+.
+.IP "\(bu" 4
+x
+.
+.br
+Raise x to power of y\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a*b
+.
+.br
+Multiply\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a/b
+.
+.br
+Divide\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a%b
+.
+.br
+Modulus\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a+b
+.
+.br
+Add\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a\-b
+.
+.br
+Subtract\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a<b
+.
+.br
+True if a is less than b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a<=b
+.
+.br
+True if a is less than or equal to b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a>b
+.
+.br
+True if a is greater than b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a>=b
+.
+.br
+True if a is greater than or equal to b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a==b
+.
+.br
+True if a equals b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a!=b
+.
+.br
+True if a does not equal b\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a&&b
+.
+.br
+True if both a and b are true\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a||b
+.
+.br
+True if ether a or b are true\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a?b:c
+.
+.br
+If a is true return b, otherwise return c\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a=b
+.
+.br
+Assign b to a\.
+.
+.br
+
+.
+.IP "\(bu" 4
+a:b
+.
+.br
+Execute a, then execute b\.
+.
+.br
+
+.
+.IP "" 0
+.
+.TP
+&&, || and ? : work as in C and sh as far as side effects: if the
+.
+.TP
+left side of && is false, the right side is not evaluated\.
+is expression separator\.
+.
+.SH "Shell windows"
+Hit \fB^K \'\fR to run a command shell in one of JOE\'s windows\. When the cursor is at the end of a shell window (use \fB^K V\fR if it\'s not), whatever you type is passed to the shell instead of the buffer\. Any output from the shell or from commands executed in the shell is appended to the shell window (the cursor will follow this output if it\'s at the end of the shell window)\. This command is useful for recording the results of shell commands\- for example the output of \fBmake\fR, the result of \fBgrep\fRping a set of files for a string, or directory listings from \fBFTP\fR sessions\. Besides typeable characters, the keys \fB^C\fR, \fBBackspace\fR, \fBDel\fR, \fBReturn\fR and \fB^D\fR are passed to the shell\. Type the shell \fBexit\fR command to stop recording shell output\. If you press \fB^C\fR in a shell window, when the cursor is not at the end of the window, the shell is \fBkill\fRed\.
+.
+.P
+If you use Bash, you can hit: \fB^Q Up Arrow\fR and \fB^Q Down Arrow\fR to scroll through Bash\'s history buffer\. Other keys work as well: try \fB^Q ^A\fR to go to beginning of line or \fB^Q ^E\fR to go to end of line\. Unfortunately JOE only emulates a dumb terminal, so you have to use a lot of imagination to do any editing beyond hitting backspace\.
+.
+.P
+In general, any character quoted with \fB^Q\fR is sent to the shell\.
+.
+.P
+Also sent to the shell: \fBTab\fR, \fBBackspace\fR, \fBEnter\fR, \fB^C\fR and \fB^D\fR\.
+.
+.P
+ \fI\fR
+.
+.SH "Pop\-up shell windows"
+Hit F1 \- F4 to open and switch between shell windows\.
+.
+.P
+Pop\-up shell windows use a full terminal emulator so that when you type "man ls" it\'s formatted correctly (it works well enough so that some interactive programs can be used)\. Even so, the shell window is still an edit buffer\.
+.
+.P
+The old shell window (with no terminal emulation) still exists: use \fB^K \'\fR to invoke it as usual\. This is useful to see control sequences emitted by a program\.
+.
+.P
+More of the keys get passed to the running program in pop\-up shell windows compared with the older one\. There is a :vtshell section of the joerc file to control which ones\. In particular arrow keys and Ctrl\-C are passed to the program\. It means you can easily step through bash history with the arrow keys, or abort programs the normal way with Ctrl\-C\.
+.
+.P
+On the other hand, loss of Ctrl\-C means it\'s less obvious how to close the window\. One way is to move the cursor off of the shell data entry point (with Ctrl\-P), and then hit Ctrl\-C\. Another is to hit \fB^K Q\fR\. Finally, you can type \'pop\' at the command prompt\.
+.
+.P
+If you need to pass a key to the shell that JOE normally uses, quote it\. For example, if you invoke "emacs \-nw" in the shell window, you can exit it with:
+.
+.IP "" 4
+.
+.nf
+
+^Q ^X ^C
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To quickly position the cursor back to the point where data is entered into the shell, hit \fB^K V\fR\.
+.
+.P
+When you open a shell window, a JOE\-specific startup\-script is sourced\. It\'s located in /etc/joe/shell\.sh (also /etc/joe/shell\.csh)\. It contains some aliases which allow you to control JOE with fake shell commands\. I have these commands so far:
+.
+.IP "\(bu" 4
+clear
+.
+.br
+erase shell window (delete buffer contents)
+.
+.br
+
+.
+.IP "\(bu" 4
+joe file
+.
+.br
+edit a file in JOE
+.
+.br
+
+.
+.IP "\(bu" 4
+math 1+2
+.
+.br
+evaluate equation using JOE\'s calculator
+.
+.br
+
+.
+.IP "\(bu" 4
+cd xyz
+.
+.br
+change directory, keep JOE up to date
+.
+.br
+
+.
+.IP "\(bu" 4
+markb
+.
+.br
+same as ^KB
+.
+.br
+
+.
+.IP "\(bu" 4
+markk
+.
+.br
+same as ^KK
+.
+.br
+
+.
+.IP "\(bu" 4
+mark command
+.
+.br
+execute shell command, mark it\'s output
+.
+.br
+
+.
+.IP "\(bu" 4
+parse command
+.
+.br
+execute shell command, parse it\'s output for file names and line numbers (for find or grep)
+.
+.br
+
+.
+.IP "\(bu" 4
+parser comman
+.
+.br
+execute shell command, parse it\'s output for errors (for gcc)
+.
+.br
+
+.
+.IP "\(bu" 4
+release
+.
+.br
+release parsed errors
+.
+.br
+
+.
+.IP "\(bu" 4
+pop
+.
+.br
+dismiss shell window (same as ^K Q)
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+These work by emitting an escape sequence recognized by the terminal emulator: \fBEsc { joe_macro }\fR\. When this is received, the macro is executed\. For security, only macros defined in the joerc file which begin with "shell_" can be executed this way\.
+.
+.SS "Use cases"
+Pop\-up shell windows have a number of nice use cases:
+.
+.IP "\(bu" 4
+Use it to browse manual pages
+.
+.IP
+Hit F1 and type "man fopen"\. Use \'b\' (\'u\') and space to control \fImore\fR (or \fIless\fR) while viewing the manual\. You can leave the manual on the screen in one window while editing in another window\.
+.
+.IP "\(bu" 4
+Use it to switch directories
+.
+.IP
+Hit F1 and navigate to the directory while using \fIcd\fR\. Once you are in the right place, hit \fB^K E\fR to load a file (or type "edit file" from the shell)\.
+.
+.IP "\(bu" 4
+Use it in conjunction with the error parser to find files
+.
+.IP
+Hit F1 and navigate to a directory\. Use grep or find (or both) to generate a list of files):
+.
+.IP "" 0
+.
+.IP "" 4
+.
+.nf
+
+        parse grep \-n FIXME *\.c
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Or:
+.
+.IP "" 4
+.
+.nf
+
+        markb; find \. | xargs grep \-n FIXME; markk; parse
+.
+.fi
+.
+.IP "" 0
+.
+.P
+(Note that you can\'t say this:
+.
+.IP "" 4
+.
+.nf
+
+        parse find \. | xargs grep \-n FIXME
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\&\.\.\.the issue is that only the words to the left of the pipe symbol are passed as arguments to the parse command)\.
+.
+.P
+Now use \fB^P\fR to position the cursor on one of the lines of the list\. Hit \fBEsc Space\fR to have JOE edit the file and jump to the specified line (also you can use \fBEsc \-\fR and \fBEsc =\fR to step through the list)\.
+.
+.IP "\(bu" 4
+Use it in conjunction with search and replace to edit many files
+.
+.IP
+Once JOE has a list of files (from above), use search and replace with the \'e\' option to visit all of them:
+.
+.IP "" 0
+.
+.IP "" 4
+.
+.nf
+
+        ^K F
+           Find: <text>
+           Options: re
+           Replace: <replacement text>
+.
+.fi
+.
+.IP "" 0
+.
+.IP "\(bu" 4
+Build your project
+.
+.IP "" 0
+.
+.P
+Easily capture errors from a build with:
+.
+.IP "" 4
+.
+.nf
+
+        parserr make
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Hit \fBEsc =\fR and \fBEsc \-\fR to step through the errors\.
+.
+.SS "How it works\.\."
+.
+.IP "\(bu" 4
+There is a new mode "ansi"\. (\fBEsc X\fR mode ansi)\. When this mode is enabled, the screen updater hides escape sequences which are in the buffer\. Otherwise you get a big mess from the sequences surrounding colored output from \'ls\'\.
+.
+.IP "\(bu" 4
+There is a new built\-in syntax: "ansi"\. (\fB^T Y\fR ansi)\. This syntax parses the ANSI color control sequences so that text gets colored\.
+.
+.IP "\(bu" 4
+There is a terminal emulator to interpret control sequences from the shell program\. It emulates a terminal by modifying the contents of an edit buffer\.
+.
+.IP "\(bu" 4
+When the edit window is resized we tell the shell by issuing the TIOCSSIZE or TIOCSWINSZ ioctl\. This way, the program running in the shell knows the window size\.
+.
+.IP "" 0
+.
+.SH "Compiler and grep/find parsers"
+JOE has two parsers which can be used to generate the error list (list of file names / line numbers)\.
+.
+.P
+The "parserr" command parses the entire buffer, or if the block is set, just the highighted block for compiler error messages\. The messages should be in this format:
+.
+.IP "" 4
+.
+.nf
+
+<junk> file\.name <junk> line\-number <junk> : <junk>
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The file name needs to be made of numbers, letters, \'/\', \'\.\' and \'\-\'\. It must have at leat one \'\.\' in it\. There needs to be a colon somewhere after the line number\. Lines not in this format are ignored\.
+.
+.P
+The "gparse\' command parses the entire buffer, or if the block is set, just the highlighted block for a list of filenames or filenames with line numbers from "grep \-n", "find" and similar programs\.
+.
+.IP "" 4
+.
+.nf
+
+filename
+
+filename:<junk>
+
+filename:line\-number:<junk>
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Once JOE has the error list, there are a number of things you can do with it:
+.
+.IP "\(bu" 4
+Visit the files/locations in the list with \fBEsc \-\fR and \fBEsc =\fR
+.
+.IP "\(bu" 4
+Search and replace across all files in the list by using the \'e\' search and replace option\.
+.
+.IP "\(bu" 4
+Clear the list by using the "release" command\.
+.
+.IP "" 0
+.
+.P
+Also, you can use \fBEsc Space\fR (\'jump\' command) to parse the line the cursor is on and jump to the parsed filename and line number\. \'jump\' uses the grep/find parser unless \'parserr\' had been previously issued in the buffer\.
+.
+.SS "Grep\-find"
+Hit \fBEsc G\fR to bring up the prompt\. Enter a command which results in file names with line numbers, for example: \'grep \-n fred *\.c\'\. This will list all instances of \'fred\' in the *\.c files\. You need the \'\-n\' to get the line numbers\.
+.
+.P
+Now you can hit \fBEsc Space\fR on one of the lines to jump to the selected file\. Also, you can use \fBEsc =\fR and \fBEsc \-\fR to step through each line\.
+.
+.SS "Compile"
+Hit \fBEsc C\fR to save all modified files and then bring up the compile prompt\. Enter the command you want to use for the compiler (typically "make \-w")\. The compiler will run in a shell window\. When it\'s complete, the results are parsed\.
+.
+.P
+The \'\-w\' flag should be given to "make" so that it prints messages whenever it changes directories\. The message are in this format:
+.
+.IP "" 4
+.
+.nf
+
+make[1]: Entering directory `/home/jhallen/joe\-editor\-mercurial/joe\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If there are any errors or warnings from the compiler you can hit \fBEsc Space\fR on one of the lines to jump to the selected file\. Also, you can use \fBEsc =\fR and \fBEsc \-\fR to step through each line\.
+.
+.SH "Syntax highlighting"
+To enable highlight use \fB^T H\fR\.
+.
+.P
+To select the syntax, use \fB^T Y\fR\. You can hit \fBTab\fR \fBTab\fR at the prompt for a completion list\.
+.
+.P
+JOE tries to determine the syntax to use based on the name and contents of the file\. The configuration file /etc/joe/ftyperc contains the definitions\.
+.
+.P
+Each syntax is defined by a file located /usr/share/joe/syntax/\.
+.
+.SH "How JOE syntax highlighting works"
+\fIfrom c\.jsf \fIhttp://joe\-editor\.hg\.sourceforge\.net/hgweb/joe\-editor/joe\-editor/file/tip/syntax/c\.jsf\.in\fR, slightly modified\fR
+.
+.P
+A deterministic state machine that performs lexical analysis of the target language is provided in a syntax file\. (This is the "assembly language" of syntax highlighting\. A separate program could in principal be used to convert a regular expression NFA syntax into this format)\.
+.
+.P
+Each state begins with:
+.
+.IP "" 4
+.
+.nf
+
+:<name> <color\-name> <context>
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\fIname\e\fR is the state\'s name\.
+.
+.P
+\fIcolor\-name\e\fR is the color used for characters eaten by the state (really a symbol for a user definable color)\.
+.
+.P
+\fIcontext\e\fR tells JOE if the current character is part of a comment or a string\. This allows JOE to skip over comments and strings when matching characters such as parentheses\. To use this feature, the highlighter_context option must be applied to the files highlighted by the corresponding syntax\. To apply the option, add it to ftyperc for those file entries\.
+.
+.P
+The valid contexts are:
+.
+.IP "\(bu" 4
+comment This character is part of a comment\. Example: /* comment */
+.
+.IP "\(bu" 4
+string This character is part of a string\. Examples: "string" \'c\' \'string\'
+.
+.IP "" 0
+.
+.P
+The comment and string delimiters themselves should be marked with the appropriate context\. The context is considered to be part of the color, so the recolor=\-N and recolormark options apply the context to previous characters\.
+.
+.P
+The first state defined is the initial state\.
+.
+.P
+Within a state, define transitions (jumps) to other states\. Each jump has the form:
+.
+.IP "" 4
+.
+.nf
+
+    <character\-list> <target\-state\-name> [<option>s]
+.
+.fi
+.
+.IP "" 0
+.
+.P
+There are three ways to specify \fIcharacter\-list\e\fRs, either \fB*\fR for any character not otherwise specified, \fB%\fR or \fB&\fR to match the character in the delimiter match buffer (\fB%\fR matches the saved character exactly, while \fB&\fR matches the opposite character, for example ( will match ) when \fB&\fR is used) or a literal list of characters within quotes (ranges and escape sequences allowed: see \fIEscape Sequences\fR)\. When the next character matches any in the list, a jump to the target\-state is taken and the character is eaten (we advance to the next character of the file to be colored)\.
+.
+.P
+The * transition should be the first transition specified in the state\.
+.
+.P
+There are several options:
+.
+.IP "\(bu" 4
+\fBnoeat\fR \- Do not eat the character, instead feed it to the next state (this tends to make the states smaller, but be careful: you can make infinite loops)\. \'noeat\' implies \'recolor=\-1\'\.
+.
+.IP "\(bu" 4
+\fBrecolor=\-N\fR \- Recolor the past N characters with the color of the target\-state\. For example once /* is recognized as the start of C comment, you want to color the /* with the C comment color with recolor=\-2\.
+.
+.IP "\(bu" 4
+\fBmark\fR \- Mark beginning of a region with current position\.
+.
+.IP "\(bu" 4
+\fBmarkend\fR \- Mark end of region\.
+.
+.IP "\(bu" 4
+\fBrecolormark\fR \- Recolor all of the characters in the marked region with the color of the target\-state\. If markend is not given, all of the characters up to the current position are recolored\. Note that the marked region can not cross line boundaries and must be on the same line as recolormark\.
+.
+.IP "\(bu" 4
+\fBbuffer\fR \- Start copying characters to a string buffer, beginning with this one (it\'s OK to not terminate buffering with a matching \'strings\', \'istrings\' or \'hold\' option\- the buffer is limited to leading 23 characters)\.
+.
+.IP "\(bu" 4
+\fBsave_c\fR \- Save character in delimiter match buffer\.
+.
+.IP "\(bu" 4
+\fBsave_s\fR \- Copy string buffer to delimiter match buffer\.
+.
+.IP "\(bu" 4
+\fBstrings\fR \- A list of strings follows\. If the buffer matches any of the given strings, a jump to the target\-state in the string list is taken instead of the normal jump\.
+.
+.IP "\(bu" 4
+\fBistrings\fR \- Same as strings, but case is ignored\. Note: strings and istrings should be the last option on the line\. They cause any options which follow them to be ignored\.
+.
+.IP "\(bu" 4
+\fBhold\fR \- Stop buffering string\- a future \'strings\' or \'istrings\' will look at contents of buffer at this point\. Useful for distinguishing commands and function calls in some languages \'write 7\' is a command \'write (\' is a function call\- hold lets us stop at the space and delay the string lookup until the ( or 7\.
+.
+.IP "" 0
+.
+.P
+The format of the string list is:
+.
+.IP "" 4
+.
+.nf
+
+    "string"   <target\-state> [<options>s]
+    "string"   <target\-state> [<options>s]
+    "&"        <target\-state> [<options>s]   # matches contents of delimiter match buffer
+    done
+.
+.fi
+.
+.IP "" 0
+.
+.P
+(all of the options above are allowed except "strings", "istrings" and "noeat"\. noeat is always implied after a matched string)\.
+.
+.P
+Weirdness: only states have colors, not transitions\. This means that you sometimes have to make dummy states with
+.
+.IP "" 4
+.
+.nf
+
+    *    <next\-state>    noeat
+.
+.fi
+.
+.IP "" 0
+.
+.P
+just to get a color specification\.
+.
+.P
+Delimiter match buffer is for perl and shell: a regex in perl can be s<\.\.>(\.\.\.) and in shell you can say: <<EOS \.\.\.\.\.\.\. EOS\. The idea is that you capture the first delimiter into the match buffer (the < or first "EOS") and then match it to the second one with "&" in a string or character list\.
+.
+.SS "Subroutines"
+Highlighter state machines can now make subroutine calls\. This works by template instantiation: the called state machine is included in your current state machine, but is modified so that the return address points to the called\. There is still no run\-time stack (the state is represented as a single integer plus the saved delimiter string)\.
+.
+.P
+Recursion is allowed, but is self limited to 5 levels\.
+.
+.P
+\fBNote:\fR this recursion limit is obsolete\. Subroutines now do use a stack so the call\-depth is limitless\.
+.
+.P
+To call a subroutine, use the \'call\' option:
+.
+.IP "" 4
+.
+.nf
+
+    "\e""    fred    call=string(dquote)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The subroutine called \'string\' is called and the jump to \'fred\' is ignored\. The \'dquote\' option is passed to the subroutine\.
+.
+.P
+If you use recolor along with call, the color used is that of the first state of the subroutine\.
+.
+.P
+The subroutine itself returns to the caller like this:
+.
+.IP "" 4
+.
+.nf
+
+    "\e""    whatever    return
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If we\'re in a subroutine, it returns to the target state of the call ("fred" in the above example)\. If we\'re not in a subroutine, it jumps to "whatever"\.
+.
+.P
+If you use recolor along with return, the color used is from the returned state ("fred" in the example above)\.
+.
+.P
+There are several ways of delimiting subroutines which show up in how it is called\. Here are the options:
+.
+.IP "\(bu" 4
+\fBcall=string()\fR \- A file called string\.jsf is the subroutine\. The entire file is the subroutine\. The starting point is the first state in the file\.
+.
+.IP "\(bu" 4
+\fBcall=library\.string()\fR \- A file called library\.jsf has the subroutine\. The subroutine within the file is called string\.
+.
+.IP "\(bu" 4
+\fBcall=\.string()\fR \- There is a subroutine called string in the current file\.
+.
+.IP "" 0
+.
+.P
+When a subroutine is within a file, but is not the whole file, it is delimited as follows:
+.
+.IP "" 4
+.
+.nf
+
+\&\.subr string
+
+\. \. \. states for string subroutine \. \. \.
+
+\.end
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Option flags can be passed to subroutines which control preprocessor\-like directives\. For example:
+.
+.IP "" 4
+.
+.nf
+
+\&\.ifdef dquote
+    "\e""    idle    return
+\.endif
+\.ifdef squote
+    "\'"     idle    return
+\.endif
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\&\.else is also available\. \.ifdefs can be nested\.
+.
+.P
+ \fI\fR
+.
+.SH "The joerc file"
+\fB^T\fR options, the help screens and the key\-sequence to editor command bindings are all defined in JOE\'s initialization file\. If you make a copy of this file (which normally resides in \fB/etc/joe/joerc\fR) to \fB$HOME/\.joerc\fR, you can customize these setting to your liking\. The syntax of the initialization file should be fairly obvious and there are further instructions in it\.
+.
+.P
+The \fBjoerc\fR file has a directive to include another file (:include)\. This facility is used to include a file called \fBftyperc\fR (usually located in \fB/etc/joe/ftyperc\fR)\. \fBftyperc\fR has the file type table which determines which local options (including syntax for the highlighter) are applied to each file type\.
+.
+.SS "Initialization file loading sequence"
+If the path for an initialization file begins with \'/\' (you can specify this with the include directive), JOE only tries to load it from the absolute path\. Otherwise, JOE tries to load initialization files (the joerc file and any files included in it, typically ftyperc) from three places:
+.
+.IP "\(bu" 4
+"$HOME/\.joerc" \- The user\'s personalized joerc file\.
+.
+.IP "\(bu" 4
+"/etc/joe/joerc" \- The system\'s joerc file\. The exact path is fixed during the build, and is determined by the \-\-sysconfdir configure script option\.
+.
+.IP "\(bu" 4
+"*joerc" \- Built\-in file This means JOE searches for the file in a table of files linked in with the JOE binary (they are in the builtins\.c file)\. A built\-in joerc file is provided so that the editor will run in cases where system\'s joerc is inaccessible\.
+.
+.IP "" 0
+.
+.P
+If the system\'s joerc file is newer than the user\'s joerc file, JOE will print a warning in the startup log\. Previous versions of JOE would prompt the user for this case\- the idea was that JOE may be unusable with an out of date initialization file\.
+.
+.SS "joerc file sections"
+The \fBjoerc\fR file is broken up into a number of sections:
+.
+.IP "\(bu" 4
+Global options Options which are not file specific, like \fBnoxon\fR\.
+.
+.IP "\(bu" 4
+File name and content dependent options Options which depend on the file type, such as \fBautoindent\fR\. The \fBftyperc\fR file is included in this section\.
+.
+.IP "\(bu" 4
+\fB^T\fR menu system definition Use :defmenu to define a named menu of macros\. The \fBmenu\fR command brings up a specific named menu\. \fB^T\fR is a macro which brings up the root menu: \fBmenu,"root",rtn\fR\.
+.
+.IP "\(bu" 4
+Help screen contents Each help screen is named\. The name is used to implement context dependent help\.
+.
+.IP "\(bu" 4
+Key bindings Key binding tables are defined\. You can define as many as you like (you can switch to a specific one with the \fBkeymap\fR command), but the following must be provided:
+.
+.IP "\(bu" 4
+\fBmain\fR Editing windows
+.
+.IP "\(bu" 4
+\fBprompt\fR Prompt windows
+.
+.IP "\(bu" 4
+\fBquery\fR Single\-character query prompts
+.
+.IP "\(bu" 4
+\fBquerya\fR Single\-character query for quote
+.
+.IP "\(bu" 4
+\fBquerysr\fR Single\-character query for search and replace
+.
+.IP "\(bu" 4
+\fBshell\fR Shell windows
+.
+.IP "\(bu" 4
+\fBvtshell\fR Terminal emulator shell windows
+.
+.IP "" 0
+
+.
+.IP "" 0
+.
+.P
+Key binding tables can inherit bindings from already defined tables\. This allows you to group common key bindings into a single table which is inherited by the others\.
+.
+.SS "Mode command"
+Many options can be controlled with the \fB^T\fR menu\. This menu is defined in the joerc file\. Each option in the \fB^T\fR menu just executes a macro\. Usually the macro is the mode command\. You can execute the mode command directly with:
+.
+.IP "" 4
+.
+.nf
+
+Esc X mode <enter>
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Hit \fBTab\fR \fBTab\fR for a completion list of all options\.
+.
+.SS "Menu command"
+This command calls up a named menu of macros which was defined in the \fBjoerc\fR file\.
+.
+.IP "" 4
+.
+.nf
+
+Esc X menu <enter>
+.
+.fi
+.
+.IP "" 0
+.
+.P
+As usual, hit \fBTab\fR \fBTab\fR at the prompt for a completion list of the menus which exist\.
+.
+.P
+\fB^T\fR is bound to the simple macro \fBmenu,"root",rtn\fR\- it brings up the root of the options menu system\.
+.
+.SH "Xterm Mouse support"
+There are two levels of mouse support\. The \-mouse option enables the first level, which will work with any stock Xterm\. If \-joexterm is also set, mouse support is enhanced, but you need a recent version of XTerm, and it needs to be \./configured with the \-\-enable\-paste64 option\.
+.
+.P
+When \-mouse is set, you can:
+.
+.IP "\(bu" 4
+Left\-click in a text window to set the cursor position\. Left\-click in a different window to move the cursor to a different window\.
+.
+.IP "\(bu" 4
+Select text with the mouse\. Left\-click and drag to select some text\- it will be as if you had used \fB^K B\fR and \fB^K K\fR to mark it\. Left\-click (but don\'t drag) to position the cursor somewhere else\. Middle click to copy the selected text to the cursor\- it will be as if you had hit \fB^K C\fR\. If you drag past the edge of the text window, the window will auto\-scroll to select more text\. Unfortunately, Xterm does not send any codes when the cursor is outside of the Xterm frame itself, so this only works if the mouse is still contained within the Xterm frame\. I\'ve sent a patch to the Xterm maintainer to improve this, but he has not taken it yet\.
+.
+.IP "\(bu" 4
+Resize windows with the mouse: click and hold on a status line dividing two windows to move it\.
+.
+.IP "\(bu" 4
+Select menu entries (such as any completion menu or the \fB^T\fR options menu): click on the menu item to position the cursor on it\. Double\-click on a menu item to select it (same as hitting return with cursor on it)\.
+.
+.IP "\(bu" 4
+If your mouse has a wheel, turning the wheel will scroll the window with the cursor\.
+.
+.IP "" 0
+.
+.P
+Unfortunately, when \-mouse is selected, cut and paste between X windows does not work as it normally does in a shell window (left\-click and drag to select, middle click to paste)\. Instead, you have to hold the shift key down to do this: shift\-left\-click and drag to select, and shift\-middle click to paste\. Note that pasting text into JOE this way has problems: any ` characters will get messed up because ` means quote the following control character\. Also if auto\-indent is enabled, pasted text will not be indented properly\.
+.
+.P
+\fBNote:\fR these problems with pasting have been resolved in recent versions of JOE\.
+.
+.IP "\(bu" 4
+JOE enables "bracketed paste" mode in Xterm so that pasted text is bracketed with an escape sequence\. This sequence causes JOE to disable the autoindent, wordwrap and spaces modes for the paste, and restores them when the paste is complete\.
+.
+.IP "\(bu" 4
+Even if the terminal emulator does not have this bracketed paste mode, JOE detects pasted text by timing: If text arrives all at once (all in the same buffer), the text is assumed to be pasted text and autoindent and wordwrap are temporarily disabled\.
+.
+.IP "" 0
+.
+.P
+When \-joexterm is set (and you have \./configured Xterm with \-\-enable\-paste64):
+.
+.IP "\(bu" 4
+Cut & paste are properly integrated with X\. Text selected with left\-click\-drag is available for pasting into other X windows (even if the selected text is larger than the text window)\. Text selected in other X windows can be pasted into JOE with middle\-click\. There are no problems pasting text containing ` or with auto\-indent\.
+.
+.IP "" 0
+.
+.P
+\-\-enable\-paste64 allows an application program to communicate Base\-64 encoded selection data to and from the Xterm\. The program has full control over what is in the selection data and when it is received or sent\.
+.
+.SH "Color Xterm support"
+JOE can make use of monochrome Xterm, 8\-color Xterm, 16\-color Xterm, 88\-color Xterm and 256\-color Xterm\. The number of colors which Xterm supports is determined by which "configure" script options are set before the Xterm source code is compiled\. The termcap or terminfo entry must support how your Xterm is configured\. On my Slackware Linux distribution, you have to set the TERM environment variable to one of these:
+.
+.IP "\(bu" 4
+xterm
+.
+.IP "\(bu" 4
+xterm\-color
+.
+.IP "\(bu" 4
+xterm\-16color
+.
+.IP "\(bu" 4
+xterm\-88color
+.
+.IP "\(bu" 4
+xterm\-256color
+.
+.IP "" 0
+.
+.P
+If the termcap/terminfo entry is missing, you can add the "\-assume_256color" option to the joerc file\. Note that this was broken for terminfo in versions of JOE below 3\.4\.
+.
+.P
+When it is working, the command: "joe \-assume_256color \-text_color bg_222" should have a gray background\.
+.
+.SH "Hex edit mode"
+When this mode is selected (either put \-hex on the command line, or look for "Hex edit mode" after hitting \fB^T\fR), the buffer is displayed as a hex dump, but all of the editing commands operate the same way\. It is most useful to select overtype mode in conjunction with hex dump (hit \fB^T T\fR)\. Then typing will not insert\.
+.
+.IP "\(bu" 4
+To enter the hex byte 0xF8 type \fB^Q x F 8\fR
+.
+.IP "\(bu" 4
+You can use \fB^K C\fR to copy a block as usual\. If overtype mode is selected, the block will overwrite the destination data without changing the size of the file\. Otherwise it inserts\.
+.
+.IP "\(bu" 4
+Hit \fBEsc X byte <Enter>\fR, to jump to a particular byte offset\. Hex values can be entered into this prompt like this: 0x2000\.
+.
+.IP "\(bu" 4
+Search, incremental search, and search & replace all operate as usual\.
+.
+.IP "" 0
+.
+.P
+ \fI\fR
+.
+.SH "Environment variables"
+For JOE to operate correctly, a number of other environment settings must be correct\. The throughput (baud rate) of the connection between the computer and your terminal must be set correctly for JOE to update the screen smoothly and allow typeahead to defer the screen update\. Use the \fBstty nnn\fR command to set this\. You want to set it as close as possible to actual throughput of the connection\. For example, if you are connected via a 1200 baud modem, you want to use this value for \fBstty\fR\. If you are connected via 14\.4k modem, but the terminal server you are connected to connects to the computer a 9600 baud, you want to set your speed as 9600 baud\. The special baud rate of 38400 or \fBextb\fR is used to indicate that you have a very\-high speed connection, such as a memory mapped console or an X\-window terminal emulator\. If you can\'t use \fBstty\fR to set the actual throughput (perhaps because of a modem communicating with the computer at a different rate than it\'s communicating over the phone line), you can put a numeric value in the \fBBAUD\fR environment variable instead (use \fBsetenv BAUD 9600\fR for csh or \fBBAUD=9600; export BAUD\fR for sh)\.
+.
+.P
+The \fBTERM\fR environment variable must be set to the type of terminal you\'re using\. If the size (number of lines/columns) of your terminal is different from what is reported in the TERMCAP or TERMINFO entry, you can set this with the \fBstty rows nn cols nn\fR command, or by setting the \fBLINES\fR and \fBCOLUMNS\fR environment variables\. The terminal size is variable on modern systems and is determined by an ioctl, so these parameters often have no effect\.
+.
+.P
+JOE normally expects that flow control between the computer and your terminal to use \fB^S\fR/\fB^Q\fR handshaking (i\.e\., if the computer is sending characters too fast for your terminal, your terminal sends \fB^S\fR to stop the output and \fB^Q\fR to restart it)\. If the flow control uses out\-of\-band or hardware handshaking or if your terminal is fast enough to always keep up with the computer output and you wish to map \fB^S\fR/\fB^Q\fR to edit commands, you can set the environment variable \fBNOXON\fR to have JOE attempt to turn off \fB^S\fR/\fB^Q\fR handshaking\. If the connection between the computer and your terminal uses no handshaking and your terminal is not fast enough to keep up with the output of the computer, you can set the environment variable \fBDOPADDING\fR to have \fBJOE\fR slow down the output by interspersing PAD characters between the terminal screen update sequences\.
+.
+.P
+Here is a complete list of the environment variables:
+.
+.IP "\(bu" 4
+BAUD
+.
+.br
+Tell JOE the baud rate of the terminal (overrides value reported by stty)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+COLUMNS
+.
+.br
+Set number of columns in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\.
+.
+.br
+
+.
+.IP "\(bu" 4
+DOPADDING
+.
+.br
+Enable JOE to send padding NULs to the terminal when set (for very old terminals)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+HOME
+.
+.br
+Used to get path to home directory for ~ expansion and also to find ~/\.joerc file ~/\.joe directory\.
+.
+.br
+
+.
+.IP "\(bu" 4
+HOSTNAME
+.
+.br
+Used to get hostname to put in EMACS compatible locks\.
+.
+.br
+
+.
+.IP "\(bu" 4
+JOETERM
+.
+.br
+Gives terminal type: JOE will use this instead of TERM if it\'s set\.
+.
+.br
+
+.
+.IP "\(bu" 4
+LANG
+.
+.br
+Sets locale (like en_US\.utf\-8)\. JOE uses the first of these which is set: LC_ALL, LC_CTYPE, LANG\.
+.
+.br
+
+.
+.IP "\(bu" 4
+LC_ALL
+.
+.br
+Sets locale (like en_US\.utf\-8)\. JOE uses the first of these which is set: LC_ALL, LC_CTYPE, LANG\.
+.
+.br
+
+.
+.IP "\(bu" 4
+LC_CTYPE
+.
+.br
+Sets locale (like en_US\.utf\-8)\. JOE uses the first of these which is set: LC_ALL, LC_CTYPE, LANG\.
+.
+.br
+
+.
+.IP "\(bu" 4
+LINES
+.
+.br
+Set number of lines in terminal emulator (in case termcap entry is wrong)\. This is only useful on old system which don\'t have the "get window size" ioctl\.
+.
+.br
+
+.
+.IP "\(bu" 4
+NOXON
+.
+.br
+Disable \fB^S\fR and \fB^Q\fR flow control, possibly allowing \fB^S\fR and \fB^Q\fR to be used as editor keys\.
+.
+.br
+
+.
+.IP "\(bu" 4
+SHELL
+.
+.br
+Path to shell (like /bin/sh)\. This is used in several places: If you are on a system with no job control, this shell is invoked when you hit \fB^K Z\fR\. Also this is the shell which is run in shell windows\. If SHELL is not set (Cygwin) or if it\'s set to /bin/sh, JOE invokes the first of these which exists: /bin/bash, /usr/bin/bash, /bin/sh\.
+.
+.br
+
+.
+.IP "\(bu" 4
+SIMPLE_BACKUP_SUFFIX
+.
+.br
+If this is set, it is appended to the file name instead of ~ to create the backup file name\.
+.
+.br
+
+.
+.IP "\(bu" 4
+TAGS
+.
+.br
+If set to a path to a file, JOE tries to use this as the "tags" file if there is no "tags" file in the current directory\.
+.
+.br
+
+.
+.IP "\(bu" 4
+TEMP
+.
+.br
+If set, gives path to directory to open swapfile instead of /tmp
+.
+.br
+
+.
+.IP "\(bu" 4
+TERMCAP
+.
+.br
+Used by JOE\'s built\-in termcap file parser (not used for terminfo)\. A termcap entry can be placed directly in this variable (which will be used if it matches TERM), or if it begins with /, it gives a list of paths to termcap files to search\.
+.
+.br
+
+.
+.IP "\(bu" 4
+TERMPATH
+.
+.br
+Gives list of paths to termcap files to search when TERMCAP has a termcap entry (otherwise it\'s ignored)\. The default list of paths to termcap files (when TERMCAP and TERMPATH do not have it) is: "~/\.termcap /etc/joe/termcap /etc/termcap"
+.
+.br
+
+.
+.IP "\(bu" 4
+TERM
+.
+.br
+Gives terminal type, like "vt100" or "xterm"\.
+.
+.br
+
+.
+.IP "\(bu" 4
+USER
+.
+.br
+Used to get user name for EMACS compatible file locks\.
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+ \fI\fR
+.
+.SH "JOE commands grouped by function"
+These commands can be entered at the \fBEsc X\fR prompt\.
+.
+.SS "Background programs"
+.
+.IP "\(bu" 4
+bknd
+.
+.br
+Run a shell in a window
+.
+.br
+
+.
+.IP "\(bu" 4
+vtbknd
+.
+.br
+Run a shell in a terminal emulator window
+.
+.br
+
+.
+.IP "\(bu" 4
+killproc
+.
+.br
+Kill program in current window
+.
+.br
+
+.
+.IP "\(bu" 4
+run
+.
+.br
+Run a UNIX command in a window
+.
+.br
+
+.
+.IP "\(bu" 4
+sys
+.
+.br
+Run a UNIX command and return to editor when done (I/O does not go through editor, but we get the command\'s return status)\.
+.
+.IP "" 0
+.
+.SS "Blocks"
+.
+.IP "\(bu" 4
+blkcpy
+.
+.br
+Copy marked block to cursor
+.
+.br
+
+.
+.IP "\(bu" 4
+blkdel
+.
+.br
+Delete marked block
+.
+.br
+
+.
+.IP "\(bu" 4
+blkmove
+.
+.br
+Move marked block to cursor
+.
+.br
+
+.
+.IP "\(bu" 4
+blksave
+.
+.br
+Save marked block into a file
+.
+.br
+
+.
+.IP "\(bu" 4
+copy
+.
+.br
+Copy block to kill\-ring
+.
+.br
+
+.
+.IP "\(bu" 4
+drop
+.
+.br
+Set markb\. If it was already set, eliminate Ait\.
+.
+.br
+
+.
+.IP "\(bu" 4
+dropon
+.
+.br
+Set markb\. If it was already set, eliminate it\. Turn on marking mode\.
+.
+.br
+
+.
+.IP "\(bu" 4
+toggle_marking
+.
+.br
+If we\'re in a block: clear markb and markk\. If marking is off: set markb and turn on marking\. If marking is on: set markk (swap if necessary with markb) and turn marking off\.
+.
+.br
+
+.
+.IP "\(bu" 4
+begin_marking
+.
+.br
+If we\'re on an edge of a block: set markb to other edge and turn on marking mode\. Otherwise set markb to cursor and turn on marking mode\.
+.
+.br
+
+.
+.IP "\(bu" 4
+select
+.
+.br
+Set markb\. If it was already set, do nothing\.
+.
+.br
+
+.
+.IP "\(bu" 4
+filt
+.
+.br
+Filter block or file through a UNIX command
+.
+.br
+
+.
+.IP "\(bu" 4
+markb
+.
+.br
+Set beginning of block mark
+.
+.br
+
+.
+.IP "\(bu" 4
+markk
+.
+.br
+Set end of block mark
+.
+.br
+
+.
+.IP "\(bu" 4
+markl
+.
+.br
+Mark current line
+.
+.br
+
+.
+.IP "\(bu" 4
+nmark
+.
+.br
+Eliminate markb and markk
+.
+.br
+
+.
+.IP "\(bu" 4
+picokill
+.
+.br
+Delete line or block
+.
+.br
+
+.
+.IP "\(bu" 4
+pop
+.
+.br
+Restore markb and markk values from stack
+.
+.br
+
+.
+.IP "\(bu" 4
+psh
+.
+.br
+Push markb and markk values onto a stack
+.
+.br
+
+.
+.IP "\(bu" 4
+swap
+.
+.br
+Switch cursor with markb
+.
+.br
+
+.
+.IP "\(bu" 4
+tomarkb
+.
+.br
+Move cursor to markb
+.
+.br
+
+.
+.IP "\(bu" 4
+tomarkbk
+.
+.br
+Move cursor to markb or markk
+.
+.br
+
+.
+.IP "\(bu" 4
+tomarkk
+.
+.br
+Move cursor to markk
+.
+.br
+
+.
+.IP "\(bu" 4
+yank
+.
+.br
+Insert top of kill ring
+.
+.br
+
+.
+.IP "\(bu" 4
+yankpop
+.
+.br
+Scroll through kill ring
+.
+.br
+
+.
+.IP "\(bu" 4
+yapp
+.
+.br
+Append next kill to top of kill ring
+.
+.br
+
+.
+.IP "\(bu" 4
+upper
+.
+.br
+Convert everything in block to uppercase
+.
+.br
+
+.
+.IP "\(bu" 4
+lower
+.
+.br
+Convert everything in block to lowercase
+.
+.IP "" 0
+.
+.SS "Buffers"
+.
+.IP "\(bu" 4
+bufed
+.
+.br
+Buffer menu
+.
+.br
+
+.
+.IP "\(bu" 4
+edit
+.
+.br
+Load file into window: asks to reload if buffer exists
+.
+.br
+
+.
+.IP "\(bu" 4
+switch
+.
+.br
+Load file into window: always uses buffer if it exists
+.
+.br
+
+.
+.IP "\(bu" 4
+scratch
+.
+.br
+Push a scratch buffer into current window
+.
+.br
+
+.
+.IP "\(bu" 4
+popabort
+.
+.br
+Abort and pop window from stack (do nothing if stack empty)
+.
+.br
+
+.
+.IP "\(bu" 4
+nbuf
+.
+.br
+Load next buffer into current window
+.
+.br
+
+.
+.IP "\(bu" 4
+pbuf
+.
+.br
+Load previous buffer into current window
+.
+.br
+
+.
+.IP "\(bu" 4
+reload
+.
+.br
+Re\-read file into buffer (revert)
+.
+.br
+
+.
+.IP "\(bu" 4
+reloadall
+.
+.br
+Re\-read all unmodified buffers
+.
+.IP "" 0
+.
+.SS "Cursor Motion"
+.
+.IP "\(bu" 4
+bof
+.
+.br
+Move cursor to beginning of file
+.
+.br
+
+.
+.IP "\(bu" 4
+bol
+.
+.br
+Move cursor to beginning of line (always)
+.
+.br
+
+.
+.IP "\(bu" 4
+bop
+.
+.br
+Move to beginning of a paragraph
+.
+.br
+
+.
+.IP "\(bu" 4
+bos
+.
+.br
+Move to beginning of screen
+.
+.br
+
+.
+.IP "\(bu" 4
+bkwdc
+.
+.br
+Search backwards for a character
+.
+.br
+
+.
+.IP "\(bu" 4
+byte
+.
+.br
+Move cursor to specific byte offset into the file\.
+.
+.br
+
+.
+.IP "\(bu" 4
+col
+.
+.br
+Move cursor to specific column number\.
+.
+.br
+
+.
+.IP "\(bu" 4
+dnarw
+.
+.br
+Move cursor down one line
+.
+.br
+
+.
+.IP "\(bu" 4
+eof
+.
+.br
+Move cursor to end of file
+.
+.br
+
+.
+.IP "\(bu" 4
+eol
+.
+.br
+Move cursor to end of line
+.
+.br
+
+.
+.IP "\(bu" 4
+eop
+.
+.br
+Move cursor to end of paragraph
+.
+.br
+
+.
+.IP "\(bu" 4
+fwrdc
+.
+.br
+Search forward for matching character
+.
+.br
+
+.
+.IP "\(bu" 4
+gomark
+.
+.br
+Move cursor to a bookmark
+.
+.br
+
+.
+.IP "\(bu" 4
+home
+.
+.br
+Move cursor to beginning of line
+.
+.br
+
+.
+.IP "\(bu" 4
+line
+.
+.br
+Move cursor to specified line
+.
+.br
+
+.
+.IP "\(bu" 4
+ltarw
+.
+.br
+Move cursor left
+.
+.br
+
+.
+.IP "\(bu" 4
+nedge
+.
+.br
+Move cursor to next edge
+.
+.br
+
+.
+.IP "\(bu" 4
+nextpos
+.
+.br
+Move cursor to next position in cursor position history
+.
+.br
+
+.
+.IP "\(bu" 4
+nextword
+.
+.br
+Move cursor to end of next word
+.
+.br
+
+.
+.IP "\(bu" 4
+pedge
+.
+.br
+Move cursor to previous edge
+.
+.br
+
+.
+.IP "\(bu" 4
+prevpos
+.
+.br
+Move cursor to previous position in cursor position history
+.
+.br
+
+.
+.IP "\(bu" 4
+prevword
+.
+.br
+Move cursor to beginning of previous word
+.
+.br
+
+.
+.IP "\(bu" 4
+rtarw
+.
+.br
+Move cursor right
+.
+.br
+
+.
+.IP "\(bu" 4
+setmark
+.
+.br
+Set a bookmark
+.
+.br
+
+.
+.IP "\(bu" 4
+tomatch
+.
+.br
+Move cursor to matching delimiter
+.
+.br
+
+.
+.IP "\(bu" 4
+tos
+.
+.br
+Move cursor to top of screen
+.
+.br
+
+.
+.IP "\(bu" 4
+uparw
+.
+.br
+Move cursor up
+.
+.IP "" 0
+.
+.SS "Deletion"
+.
+.IP "\(bu" 4
+backs
+.
+.br
+Backspace
+.
+.br
+
+.
+.IP "\(bu" 4
+backw
+.
+.br
+Backspace a word
+.
+.br
+
+.
+.IP "\(bu" 4
+delbol
+.
+.br
+Delete to beginning of line
+.
+.br
+
+.
+.IP "\(bu" 4
+delch
+.
+.br
+Delete character under cursor
+.
+.br
+
+.
+.IP "\(bu" 4
+deleol
+.
+.br
+Delete to end of line
+.
+.br
+
+.
+.IP "\(bu" 4
+dellin
+.
+.br
+Delete entire line
+.
+.br
+
+.
+.IP "\(bu" 4
+delw
+.
+.br
+Delete word to right
+.
+.IP "" 0
+.
+.SS "Error parsing"
+.
+.IP "\(bu" 4
+nxterr
+.
+.br
+Goto next parsed error
+.
+.br
+
+.
+.IP "\(bu" 4
+parserr
+.
+.br
+Parse errors in current file
+.
+.br
+
+.
+.IP "\(bu" 4
+gparse
+.
+.br
+Parse grep list in current file
+.
+.br
+
+.
+.IP "\(bu" 4
+jump
+.
+.br
+Parse current line and jump to it
+.
+.br
+
+.
+.IP "\(bu" 4
+prverr
+.
+.br
+Go to previous parsed error
+.
+.br
+
+.
+.IP "\(bu" 4
+showerr
+.
+.br
+Show current message
+.
+.br
+
+.
+.IP "\(bu" 4
+grep
+.
+.br
+Execute grep command, parse when done
+.
+.br
+
+.
+.IP "\(bu" 4
+build
+.
+.br
+Execute build command, parse when done
+.
+.br
+
+.
+.IP "\(bu" 4
+release
+.
+.br
+Release error/grep records
+.
+.IP "" 0
+.
+.SS "Exit"
+.
+.IP "\(bu" 4
+cancel
+.
+.br
+Like abort, but doesn\'t return failure: useful in macros to escape out of a prompt\.
+.
+.br
+
+.
+.IP "\(bu" 4
+abort
+.
+.br
+Abort current buffer/window\. Prompt if it is changed\.
+.
+.br
+
+.
+.IP "\(bu" 4
+abortbuf
+.
+.br
+Like above, but just fail if it would have to prompt because it\'s the last window on a modified buffer\.
+.
+.br
+
+.
+.IP "\(bu" 4
+ask
+.
+.br
+Prompt to save current file: user says yes return, user says no: run \'abort\'\. Use in a macro: "ask,query,exsave"
+.
+.br
+
+.
+.IP "\(bu" 4
+exsave
+.
+.br
+Save file and exit
+.
+.br
+
+.
+.IP "\(bu" 4
+lose
+.
+.br
+EMACS kill buffer\. The buffer is deleted\- any windows with it get a replacement scratch buffer\.
+.
+.br
+
+.
+.IP "\(bu" 4
+querysave
+.
+.br
+Prompt to save each modified buffer\. Use in a macro: "querysave,query,killjoe"
+.
+.br
+
+.
+.IP "\(bu" 4
+killjoe
+.
+.br
+Exit JOE immediately without checking for modified buffers
+.
+.IP "" 0
+.
+.SS "Files"
+.
+.IP "\(bu" 4
+cd
+.
+.br
+Set directory prefix
+.
+.br
+
+.
+.IP "\(bu" 4
+save
+.
+.br
+Save file
+.
+.br
+
+.
+.IP "\(bu" 4
+savenow
+.
+.br
+Save immediately, unless file name is not known
+.
+.br
+
+.
+.IP "\(bu" 4
+insf
+.
+.br
+Insert a file
+.
+.IP "" 0
+.
+.SS "Formatting"
+.
+.IP "\(bu" 4
+center
+.
+.br
+Center line
+.
+.br
+
+.
+.IP "\(bu" 4
+fmtblk
+.
+.br
+Format all paragraphs in a block
+.
+.br
+
+.
+.IP "\(bu" 4
+format
+.
+.br
+Format current paragraph
+.
+.br
+
+.
+.IP "\(bu" 4
+lindent
+.
+.br
+Indent to the left
+.
+.br
+
+.
+.IP "\(bu" 4
+rindent
+.
+.br
+Indent to the right
+.
+.IP "" 0
+.
+.SS "Help"
+.
+.IP "\(bu" 4
+help
+.
+.br
+Turn help on or off
+.
+.br
+
+.
+.IP "\(bu" 4
+hnext
+.
+.br
+Switch to next help screen
+.
+.br
+
+.
+.IP "\(bu" 4
+hprev
+.
+.br
+Switch to previous help screen
+.
+.IP "" 0
+.
+.SS "Inserting"
+.
+.IP "\(bu" 4
+ctrl
+.
+.br
+Type next key
+.
+.br
+
+.
+.IP "\(bu" 4
+finish
+.
+.br
+Complete word in text window
+.
+.br
+
+.
+.IP "\(bu" 4
+insc
+.
+.br
+Insert a space
+.
+.br
+
+.
+.IP "\(bu" 4
+open
+.
+.br
+Insert newline
+.
+.br
+
+.
+.IP "\(bu" 4
+quote
+.
+.br
+Insert a control character
+.
+.br
+
+.
+.IP "\(bu" 4
+quote8
+.
+.br
+Insert a meta character
+.
+.br
+
+.
+.IP "\(bu" 4
+rtn
+.
+.br
+\fBReturn\fR / \fBEnter\fR key
+.
+.br
+
+.
+.IP "\(bu" 4
+type
+.
+.br
+Insert typed character
+.
+.br
+
+.
+.IP "\(bu" 4
+secure_type
+.
+.br
+Insert typed character, but only allowed in prompt windows (not allowed in shell windows)
+.
+.IP "" 0
+.
+.SS "Macros"
+.
+.IP "\(bu" 4
+macros
+.
+.br
+Insert keyboard macros into current file
+.
+.br
+
+.
+.IP "\(bu" 4
+play
+.
+.br
+Execute a macro
+.
+.br
+
+.
+.IP "\(bu" 4
+query
+.
+.br
+Suspend macro recording for user query
+.
+.br
+
+.
+.IP "\(bu" 4
+record
+.
+.br
+Record a macro
+.
+.br
+
+.
+.IP "\(bu" 4
+stop
+.
+.br
+Stop recording macro
+.
+.IP "" 0
+.
+.SS "Menu"
+.
+.IP "\(bu" 4
+backsmenu
+.
+.br
+Undo in file completion menu
+.
+.br
+
+.
+.IP "\(bu" 4
+bofmenu
+.
+.br
+Move to beginning of menu
+.
+.br
+
+.
+.IP "\(bu" 4
+bolmenu
+.
+.br
+Move to beginning of line in a menu
+.
+.br
+
+.
+.IP "\(bu" 4
+dnarwmenu
+.
+.br
+Move down one line in a menu
+.
+.br
+
+.
+.IP "\(bu" 4
+eolmenu
+.
+.br
+Move cursor to end of line in a menu
+.
+.br
+
+.
+.IP "\(bu" 4
+eofmenu
+.
+.br
+Move cursor to end of menu
+.
+.br
+
+.
+.IP "\(bu" 4
+ltarwmenu
+.
+.br
+Move cursor left in a menu
+.
+.br
+
+.
+.IP "\(bu" 4
+rtarwmenu
+.
+.br
+Move cursor right in menu
+.
+.br
+
+.
+.IP "\(bu" 4
+uparwmenu
+.
+.br
+Move cursor up in menu
+.
+.br
+
+.
+.IP "\(bu" 4
+dnslidemenu
+.
+.br
+Scroll menu down one line
+.
+.br
+
+.
+.IP "\(bu" 4
+upslidemenu
+.
+.br
+Scroll menu up one line
+.
+.br
+
+.
+.IP "\(bu" 4
+pgupmenu
+.
+.br
+Scroll menu up
+.
+.br
+
+.
+.IP "\(bu" 4
+pgdnmenu
+.
+.br
+Scroll menu down
+.
+.br
+
+.
+.IP "\(bu" 4
+tabmenu
+.
+.br
+Tab through menu
+.
+.IP "" 0
+.
+.SS "Misc"
+.
+.IP "\(bu" 4
+beep
+.
+.br
+Beep
+.
+.br
+
+.
+.IP "\(bu" 4
+execmd
+.
+.br
+Execute a JOE command
+.
+.br
+
+.
+.IP "\(bu" 4
+debug_joe
+.
+.br
+Insert debug information into buffer
+.
+.br
+
+.
+.IP "\(bu" 4
+math
+.
+.br
+Calculator
+.
+.br
+
+.
+.IP "\(bu" 4
+maths
+.
+.br
+Secure Calculator (no way to run joe() macros)
+.
+.br
+
+.
+.IP "\(bu" 4
+mode
+.
+.br
+Mode prompt
+.
+.br
+
+.
+.IP "\(bu" 4
+menu
+.
+.br
+Menu prompt
+.
+.br
+
+.
+.IP "\(bu" 4
+msg
+.
+.br
+Display a message
+.
+.br
+
+.
+.IP "\(bu" 4
+notmod
+.
+.br
+Clear the modified flag
+.
+.br
+
+.
+.IP "\(bu" 4
+retype
+.
+.br
+Refresh screen
+.
+.br
+
+.
+.IP "\(bu" 4
+shell
+.
+.br
+Suspend process or execute a sub\-shell
+.
+.br
+
+.
+.IP "\(bu" 4
+stat
+.
+.br
+Display cursor position
+.
+.br
+
+.
+.IP "\(bu" 4
+tag
+.
+.br
+Tags file search
+.
+.br
+
+.
+.IP "\(bu" 4
+tagjump
+.
+.br
+Jump to next tags file search match (only if notagsmenu is set)
+.
+.br
+
+.
+.IP "\(bu" 4
+timer
+.
+.br
+Execute a macro periodically
+.
+.br
+
+.
+.IP "\(bu" 4
+txt
+.
+.br
+Insert text\. If first character is `, then text is assumed to be a format string (that is, the string used to define the status line for the rmsg and lmsg options) and is formatted before the insertion\.
+.
+.br
+
+.
+.IP "\(bu" 4
+name
+.
+.br
+Insert current file name
+.
+.br
+
+.
+.IP "\(bu" 4
+language
+.
+.br
+Insert current language
+.
+.br
+
+.
+.IP "\(bu" 4
+charset
+.
+.br
+Insert current character set
+.
+.br
+
+.
+.IP "\(bu" 4
+keymap
+.
+.br
+Switch to another keymap
+.
+.IP "" 0
+.
+.SS "Prompts"
+.
+.IP "\(bu" 4
+complete
+.
+.br
+Complete a file\-name in a prompt
+.
+.br
+
+.
+.IP "\(bu" 4
+if
+.
+.br
+Only run following cmds if expr is true (non\-zero)
+.
+.br
+
+.
+.IP "\(bu" 4
+then
+.
+.br
+Same as rtn but only works in prompt windows
+.
+.br
+
+.
+.IP "\(bu" 4
+elsif
+.
+.br
+Try a new condition
+.
+.br
+
+.
+.IP "\(bu" 4
+else
+.
+.br
+Toggle truth flag
+.
+.br
+
+.
+.IP "\(bu" 4
+endif
+.
+.br
+Start running cmds again
+.
+.br
+
+.
+.IP "" 0
+.
+.P
+Here is an example \'if\' macro:
+.
+.P
+if,"char==65",then,"it\'s an A",else,"it\'s not an A",endif __^[ q__
+.
+.P
+When you hit __^[ q__, if the character under the cursor is an \'A\': "it\'s a A" is inserted into the buffer, otherwise "it\'s not an A" is inserted\.
+.
+.P
+"if" creates a math prompt (like __Esc M__)\. "then" is like "rtn"\- it hits the return key for this prompt\.
+.
+.P
+Within the math prompt, the following variables are available:
+.
+.IP "\(bu" 4
+char
+.
+.br
+ASCII value of character under cursor
+.
+.br
+
+.
+.IP "\(bu" 4
+width
+.
+.br
+Width of screen
+.
+.br
+
+.
+.IP "\(bu" 4
+height
+.
+.br
+Height of screen
+.
+.br
+
+.
+.IP "\(bu" 4
+byte
+.
+.br
+byte number
+.
+.br
+
+.
+.IP "\(bu" 4
+col
+.
+.br
+column number
+.
+.br
+
+.
+.IP "\(bu" 4
+line
+.
+.br
+line number
+.
+.br
+
+.
+.IP "\(bu" 4
+lines
+.
+.br
+no\. lines in file
+.
+.br
+
+.
+.IP "\(bu" 4
+top
+.
+.br
+line number of top line of window
+.
+.IP "" 0
+.
+.SS "Repeat"
+.
+.IP "\(bu" 4
+arg
+.
+.br
+Prompt for repeat argument
+.
+.br
+
+.
+.IP "\(bu" 4
+uarg
+.
+.br
+Universal argument
+.
+.IP "" 0
+.
+.SS "Scrolling"
+.
+.IP "\(bu" 4
+crawll
+.
+.br
+Pan screen left
+.
+.br
+
+.
+.IP "\(bu" 4
+crawlr
+.
+.br
+Pan screen right
+.
+.br
+
+.
+.IP "\(bu" 4
+dnslide
+.
+.br
+Scroll screen down 1 line
+.
+.br
+
+.
+.IP "\(bu" 4
+pgdn
+.
+.br
+Scroll screen down
+.
+.br
+
+.
+.IP "\(bu" 4
+pgup
+.
+.br
+Scroll screen up
+.
+.br
+
+.
+.IP "\(bu" 4
+upslide
+.
+.br
+Scroll up one line
+.
+.IP "" 0
+.
+.SS "Search and replace"
+.
+.IP "\(bu" 4
+ffirst
+.
+.br
+Find text
+.
+.br
+
+.
+.IP "\(bu" 4
+fnext
+.
+.br
+Repeat previous search
+.
+.br
+
+.
+.IP "\(bu" 4
+isrch
+.
+.br
+Incremental search forward
+.
+.br
+
+.
+.IP "\(bu" 4
+qrepl
+.
+.br
+Search and replace
+.
+.br
+
+.
+.IP "\(bu" 4
+rfirst
+.
+.br
+Search backwards for text
+.
+.br
+
+.
+.IP "\(bu" 4
+rsrch
+.
+.br
+Reverse incremental search
+.
+.IP "" 0
+.
+.SS "Windows"
+.
+.IP "\(bu" 4
+explode
+.
+.br
+Display one window or display all windows
+.
+.br
+
+.
+.IP "\(bu" 4
+dupw
+.
+.br
+Duplicate current window
+.
+.br
+
+.
+.IP "\(bu" 4
+groww
+.
+.br
+Increase size of window
+.
+.br
+
+.
+.IP "\(bu" 4
+nextw
+.
+.br
+Move cursor to next window
+.
+.br
+
+.
+.IP "\(bu" 4
+prevw
+.
+.br
+Go to previous window
+.
+.br
+
+.
+.IP "\(bu" 4
+shrinkw
+.
+.br
+Shrink window
+.
+.br
+
+.
+.IP "\(bu" 4
+splitw
+.
+.br
+Split window into two
+.
+.br
+
+.
+.IP "\(bu" 4
+tw0
+.
+.br
+Eliminate this window
+.
+.br
+
+.
+.IP "\(bu" 4
+tw1
+.
+.br
+Show only one window
+.
+.br
+
+.
+.IP "\(bu" 4
+mwind
+.
+.br
+Get error messages window on the screen and put cursor in it\.
+.
+.br
+
+.
+.IP "\(bu" 4
+showlog
+.
+.br
+Get startup log scratch buffer into window\.
+.
+.br
+
+.
+.IP "\(bu" 4
+mfit
+.
+.br
+Fit two windows on the screen: make current window 6 lines, and give rest of space to window above\. The window above is either the existing previous window, a newly created one if there wasn\'t one\.
+.
+.IP "" 0
+.
+.SS "Undo"
+.
+.IP "\(bu" 4
+redo
+.
+.br
+Re\-execute the latest undone change
+.
+.br
+
+.
+.IP "\(bu" 4
+undo
+.
+.br
+Undo last change
+.
+.IP "" 0
+.
+.SS "Mouse"
+.
+.IP "\(bu" 4
+tomouse
+.
+.br
+Move the cursor to where the mouse was clicked/dragged
+.
+.br
+
+.
+.IP "\(bu" 4
+defmdown
+.
+.br
+Default single\-click handler, usually bound to MDOWN\.  Positions cursor to mouse and begins a region\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defmup
+.
+.br
+Default single\-click release handler, usually bound to MUP\.  Completes selection of a region\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defmdrag
+.
+.br
+Default single\-click drag handler, usually bound to MDRAG\.  Selects a region of text a character at a time\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm2down
+.
+.br
+Default double\-click handler, usually bound to M2DOWN\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm2up
+.
+.br
+Default double\-click release handler, usually bound to M2UP\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm2drag
+.
+.br
+Default double\-click drag handler, usually bound to M2DRAG\.  Selects a region of text a word at a time\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm3down
+.
+.br
+Default triple\-click handler, usually bound to M3DOWN\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm3up
+.
+.br
+Default triple\-click release handler, usually bound to M3UP\.
+.
+.br
+
+.
+.IP "\(bu" 4
+defm3drag
+.
+.br
+Default triple\-click drag handler, usually bound to M3DRAG\.  Selects a region of text a line at a time\.
+.
+.br
+
+.IP "\(bu" 4
+defmiddledown
+.
+.br
+Default middle click handler, usually bound to MIDDLEDOWN.  This inserts text\.
+.
+.br
+
+.IP "\(bu" 4
+defmiddleup
+.
+.br
+Default middle click release handler, usually bound to MIDDLEUP\.
+.
+.br
+
+.
+.IP "\(bu" 4
+xtmouse
+.
+.br
+Handle xterm mouse events, usually bound to Esc [ M\.  It parses the rest of the sequence and generates fake "keys" that can be bound to macros in the joerc file\.  It uses a timer to detect double-click and triple-click\.  The keys are: MUP, MDOWN, MDRAG, M2UP, M2DOWN, M2DRAG, M3UP, M3DOWN, M3DRAG, MWUP and MWDOWN\.
+.
+.br
+
+.
+.IP "\(bu" 4
+extmouse
+.
+.br
+Handle extended xterm mouse events, usually bound to Esc [ <.
+.
+.br
+
+.
+.IP "\(bu" 4
+paste
+.
+.br
+Insert base64 encoded text (for XTerm \-\-enable\-base64 option)\.
+.
+.br
+
+.
+.IP "\(bu" 4
+brpaste
+.
+.br
+Disable autoindent, wordwrap and spaces\. The idea is to bind this to \fBEsc [ 2 0 0 ~\fR so that when the terminal emulator sends a mouse paste, the text is inserted as\-is\.
+.
+.br
+
+.
+.IP "\(bu" 4
+brpaste_done
+.
+.br
+Restore autoindent, wordwrap and spaces modes to their original values before brpaste\. The idea is to bind this to \fBEsc [ 2 0 1 ~\fR so that these modes are restored after a mouse paste\.
+.
+.br
+
+.
+.IP "" 0
+
diff --git a/upstream/mageia-cauldron/man1/join.1 b/upstream/mageia-cauldron/man1/join.1
new file mode 100644
index 00000000..0bc283b7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/join.1
@@ -0,0 +1,97 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH JOIN "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+join \- join lines of two files on a common field
+.SH SYNOPSIS
+.B join
+[\fI\,OPTION\/\fR]... \fI\,FILE1 FILE2\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+For each pair of input lines with identical join fields, write a line to
+standard output.  The default join field is the first, delimited by blanks.
+.PP
+When FILE1 or FILE2 (not both) is \-, read standard input.
+.TP
+\fB\-a\fR FILENUM
+also print unpairable lines from file FILENUM, where
+FILENUM is 1 or 2, corresponding to FILE1 or FILE2
+.TP
+\fB\-e\fR STRING
+replace missing (empty) input fields with STRING;
+I.e., missing fields specified with '\-12jo' options
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+ignore differences in case when comparing fields
+.TP
+\fB\-j\fR FIELD
+equivalent to '\-1 FIELD \fB\-2\fR FIELD'
+.TP
+\fB\-o\fR FORMAT
+obey FORMAT while constructing output line
+.TP
+\fB\-t\fR CHAR
+use CHAR as input and output field separator
+.TP
+\fB\-v\fR FILENUM
+like \fB\-a\fR FILENUM, but suppress joined output lines
+.TP
+\fB\-1\fR FIELD
+join on this FIELD of file 1
+.TP
+\fB\-2\fR FIELD
+join on this FIELD of file 2
+.TP
+\fB\-\-check\-order\fR
+check that the input is correctly sorted, even
+if all input lines are pairable
+.TP
+\fB\-\-nocheck\-order\fR
+do not check that the input is correctly sorted
+.TP
+\fB\-\-header\fR
+treat the first line in each file as field headers,
+print them without trying to pair them
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Unless \fB\-t\fR CHAR is given, leading blanks separate fields and are ignored,
+else fields are separated by CHAR.  Any FIELD is a field number counted
+from 1.  FORMAT is one or more comma or blank separated specifications,
+each being 'FILENUM.FIELD' or '0'.  Default FORMAT outputs the join field,
+the remaining fields from FILE1, the remaining fields from FILE2, all
+separated by CHAR.  If FORMAT is the keyword 'auto', then the first
+line of each file determines the number of fields output for each line.
+.PP
+Important: FILE1 and FILE2 must be sorted on the join fields.
+E.g., use "sort \fB\-k\fR 1b,1" if 'join' has no options,
+or use "join \fB\-t\fR ''" if 'sort' has no options.
+Note, comparisons honor the rules specified by 'LC_COLLATE'.
+If the input is not sorted and some lines cannot be joined, a
+warning message will be given.
+.SH AUTHOR
+Written by Mike Haertel.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcomm\fP(1), \fBuniq\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/join>
+.br
+or available locally via: info \(aq(coreutils) join invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/journalctl.1 b/upstream/mageia-cauldron/man1/journalctl.1
new file mode 100644
index 00000000..16dd0e82
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/journalctl.1
@@ -0,0 +1,1374 @@
+'\" t
+.TH "JOURNALCTL" "1" "" "systemd 255" "journalctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+journalctl \- Print log entries from the systemd journal
+.SH "SYNOPSIS"
+.HP \w'\fBjournalctl\fR\ 'u
+\fBjournalctl\fR [OPTIONS...] [MATCHES...]
+.SH "DESCRIPTION"
+.PP
+\fBjournalctl\fR
+is used to print the log entries stored in the journal by
+\fBsystemd-journald.service\fR(8)
+and
+\fBsystemd-journal-remote.service\fR(8)\&.
+.PP
+If called without parameters, it will show the contents of the journal accessible to the calling user, starting with the oldest entry collected\&.
+.PP
+If one or more match arguments are passed, the output is filtered accordingly\&. A match is in the format
+"FIELD=VALUE", e\&.g\&.
+"_SYSTEMD_UNIT=httpd\&.service", referring to the components of a structured journal entry\&. See
+\fBsystemd.journal-fields\fR(7)
+for a list of well\-known fields\&. If multiple matches are specified matching different fields, the log entries are filtered by both, i\&.e\&. the resulting output will show only entries matching all the specified matches of this kind\&. If two matches apply to the same field, then they are automatically matched as alternatives, i\&.e\&. the resulting output will show entries matching any of the specified matches for the same field\&. Finally, the character
+"+"
+may appear as a separate word between other terms on the command line\&. This causes all matches before and after to be combined in a disjunction (i\&.e\&. logical OR)\&.
+.PP
+It is also possible to filter the entries by specifying an absolute file path as an argument\&. The file path may be a file or a symbolic link and the file must exist at the time of the query\&. If a file path refers to an executable binary, an
+"_EXE="
+match for the canonicalized binary path is added to the query\&. If a file path refers to an executable script, a
+"_COMM="
+match for the script name is added to the query\&. If a file path refers to a device node,
+"_KERNEL_DEVICE="
+matches for the kernel name of the device and for each of its ancestor devices is added to the query\&. Symbolic links are dereferenced, kernel names are synthesized, and parent devices are identified from the environment at the time of the query\&. In general, a device node is the best proxy for an actual device, as log entries do not usually contain fields that identify an actual device\&. For the resulting log entries to be correct for the actual device, the relevant parts of the environment at the time the entry was logged, in particular the actual device corresponding to the device node, must have been the same as those at the time of the query\&. Because device nodes generally change their corresponding devices across reboots, specifying a device node path causes the resulting entries to be restricted to those from the current boot\&.
+.PP
+Additional constraints may be added using options
+\fB\-\-boot\fR,
+\fB\-\-unit=\fR, etc\&., to further limit what entries will be shown (logical AND)\&.
+.PP
+Output is interleaved from all accessible journal files, whether they are rotated or currently being written, and regardless of whether they belong to the system itself or are accessible user journals\&. The
+\fB\-\-header\fR
+option can be used to identify which files
+\fIare\fR
+being shown\&.
+.PP
+The set of journal files which will be used can be modified using the
+\fB\-\-user\fR,
+\fB\-\-system\fR,
+\fB\-\-directory\fR, and
+\fB\-\-file\fR
+options, see below\&.
+.PP
+All users are granted access to their private per\-user journals\&. However, by default, only root and users who are members of a few special groups are granted access to the system journal and the journals of other users\&. Members of the groups
+"systemd\-journal",
+"adm", and
+"wheel"
+can read all journal files\&. Note that the two latter groups traditionally have additional privileges specified by the distribution\&. Members of the
+"wheel"
+group can often perform administrative tasks\&.
+.PP
+The output is paged through
+\fBless\fR
+by default, and long lines are "truncated" to screen width\&. The hidden part can be viewed by using the left\-arrow and right\-arrow keys\&. Paging can be disabled; see the
+\fB\-\-no\-pager\fR
+option and the "Environment" section below\&.
+.PP
+When outputting to a tty, lines are colored according to priority: lines of level ERROR and higher are colored red; lines of level WARNING are colored yellow; lines of level NOTICE are highlighted; lines of level INFO are displayed normally; lines of level DEBUG are colored grey\&.
+.PP
+To write entries
+\fIto\fR
+the journal, a few methods may be used\&. In general, output from systemd units is automatically connected to the journal, see
+\fBsystemd-journald.service\fR(8)\&. In addition,
+\fBsystemd-cat\fR(1)
+may be used to send messages to the journal directly\&.
+.SH "SOURCE OPTIONS"
+.PP
+The following options control where to read journal records from:
+.PP
+\fB\-\-system\fR, \fB\-\-user\fR
+.RS 4
+Show messages from system services and the kernel (with
+\fB\-\-system\fR)\&. Show messages from service of current user (with
+\fB\-\-user\fR)\&. If neither is specified, show all messages that the user can see\&.
+.sp
+The
+\fB\-\-user\fR
+option affects how
+\fB\-\-unit=\fR
+arguments are treated\&. See
+\fB\-\-unit=\fR\&.
+.sp
+Note that
+\fB\-\-user\fR
+only works if persistent logging is enabled, via the
+\fIStorage=\fR
+setting in
+\fBjournald.conf\fR(5)\&.
+.sp
+Added in version 205\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Show messages from a running, local container\&. Specify a container name to connect to\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-m\fR, \fB\-\-merge\fR
+.RS 4
+Show entries interleaved from all available journals, including remote ones\&.
+.sp
+Added in version 190\&.
+.RE
+.PP
+\fB\-D \fR\fB\fIDIR\fR\fR, \fB\-\-directory=\fR\fB\fIDIR\fR\fR
+.RS 4
+Takes a directory path as argument\&. If specified, journalctl will operate on the specified journal directory
+\fIDIR\fR
+instead of the default runtime and system journal paths\&.
+.sp
+Added in version 187\&.
+.RE
+.PP
+\fB\-\-file=\fR\fB\fIGLOB\fR\fR
+.RS 4
+Takes a file glob as an argument\&. If specified, journalctl will operate on the specified journal files matching
+\fIGLOB\fR
+instead of the default runtime and system journal paths\&. May be specified multiple times, in which case files will be suitably interleaved\&.
+.sp
+Added in version 205\&.
+.RE
+.PP
+\fB\-\-root=\fR\fB\fIROOT\fR\fR
+.RS 4
+Takes a directory path as an argument\&. If specified,
+\fBjournalctl\fR
+will operate on journal directories and catalog file hierarchy underneath the specified directory instead of the root directory (e\&.g\&.
+\fB\-\-update\-catalog\fR
+will create
+\fIROOT\fR/var/lib/systemd/catalog/database, and journal files under
+\fIROOT\fR/run/journal/
+or
+\fIROOT\fR/var/log/journal/
+will be displayed)\&.
+.sp
+Added in version 201\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIIMAGE\fR\fR
+.RS 4
+Takes a path to a disk image file or block device node\&. If specified,
+\fBjournalctl\fR
+will operate on the file system in the indicated disk image\&. This option is similar to
+\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices, thus providing an easy way to extract log data from disk images\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
+\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-namespace=\fR\fB\fINAMESPACE\fR\fR
+.RS 4
+Takes a journal namespace identifier string as argument\&. If not specified the data collected by the default namespace is shown\&. If specified shows the log data of the specified namespace instead\&. If the namespace is specified as
+"*"
+data from all namespaces is shown, interleaved\&. If the namespace identifier is prefixed with
+"+"
+data from the specified namespace and the default namespace is shown, interleaved, but no other\&. For details about journal namespaces see
+\fBsystemd-journald.service\fR(8)\&.
+.sp
+Added in version 245\&.
+.RE
+.SH "FILTERING OPTIONS"
+.PP
+The following options control how to filter journal records:
+.PP
+\fB\-S\fR, \fB\-\-since=\fR, \fB\-U\fR, \fB\-\-until=\fR
+.RS 4
+Start showing entries on or newer than the specified date, or on or older than the specified date, respectively\&. Date specifications should be of the format
+"2012\-10\-30 18:17:16"\&. If the time part is omitted,
+"00:00:00"
+is assumed\&. If only the seconds component is omitted,
+":00"
+is assumed\&. If the date component is omitted, the current day is assumed\&. Alternatively the strings
+"yesterday",
+"today",
+"tomorrow"
+are understood, which refer to 00:00:00 of the day before the current day, the current day, or the day after the current day, respectively\&.
+"now"
+refers to the current time\&. Finally, relative times may be specified, prefixed with
+"\-"
+or
+"+", referring to times before or after the current time, respectively\&. For complete time and date specification, see
+\fBsystemd.time\fR(7)\&. Note that
+\fB\-\-output=short\-full\fR
+prints timestamps that follow precisely this format\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-cursor=\fR
+.RS 4
+Start showing entries from the location in the journal specified by the passed cursor\&.
+.sp
+Added in version 193\&.
+.RE
+.PP
+\fB\-\-after\-cursor=\fR
+.RS 4
+Start showing entries from the location in the journal
+\fIafter\fR
+the location specified by the passed cursor\&. The cursor is shown when the
+\fB\-\-show\-cursor\fR
+option is used\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-cursor\-file=\fR\fB\fIFILE\fR\fR
+.RS 4
+If
+\fIFILE\fR
+exists and contains a cursor, start showing entries
+\fIafter\fR
+this location\&. Otherwise show entries according to the other given options\&. At the end, write the cursor of the last entry to
+\fIFILE\fR\&. Use this option to continually read the journal by sequentially calling
+\fBjournalctl\fR\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-b \fR\fB[[\fIID\fR][\fI\(+-offset\fR]|\fBall\fR]\fR, \fB\-\-boot\fR\fB[=[\fIID\fR][\fI\(+-offset\fR]|\fBall\fR]\fR
+.RS 4
+Show messages from a specific boot\&. This will add a match for
+"_BOOT_ID="\&.
+.sp
+The argument may be empty, in which case logs for the current boot will be shown\&.
+.sp
+If the boot ID is omitted, a positive
+\fIoffset\fR
+will look up the boots starting from the beginning of the journal, and an equal\-or\-less\-than zero
+\fIoffset\fR
+will look up boots starting from the end of the journal\&. Thus,
+\fB1\fR
+means the first boot found in the journal in chronological order,
+\fB2\fR
+the second and so on; while
+\fB\-0\fR
+is the last boot,
+\fB\-1\fR
+the boot before last, and so on\&. An empty
+\fIoffset\fR
+is equivalent to specifying
+\fB\-0\fR, except when the current boot is not the last boot (e\&.g\&. because
+\fB\-\-directory\fR
+was specified to look at logs from a different machine)\&.
+.sp
+If the 32\-character
+\fIID\fR
+is specified, it may optionally be followed by
+\fIoffset\fR
+which identifies the boot relative to the one given by boot
+\fIID\fR\&. Negative values mean earlier boots and positive values mean later boots\&. If
+\fIoffset\fR
+is not specified, a value of zero is assumed, and the logs for the boot given by
+\fIID\fR
+are shown\&.
+.sp
+The special argument
+\fBall\fR
+can be used to negate the effect of an earlier use of
+\fB\-b\fR\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-\-unit=\fR\fB\fIUNIT\fR\fR\fB|\fR\fB\fIPATTERN\fR\fR
+.RS 4
+Show messages for the specified systemd unit
+\fIUNIT\fR
+(such as a service unit), or for any of the units matched by
+\fIPATTERN\fR\&. If a pattern is specified, a list of unit names found in the journal is compared with the specified pattern and all that match are used\&. For each unit name, a match is added for messages from the unit ("_SYSTEMD_UNIT=\fIUNIT\fR"), along with additional matches for messages from systemd and messages about coredumps for the specified unit\&. A match is also added for
+"_SYSTEMD_SLICE=\fIUNIT\fR", such that if the provided
+\fIUNIT\fR
+is a
+\fBsystemd.slice\fR(5)
+unit, all logs of children of the slice will be shown\&.
+.sp
+With
+\fB\-\-user\fR, all
+\fB\-\-unit=\fR
+arguments will be converted to match user messages as if specified with
+\fB\-\-user\-unit=\fR\&.
+.sp
+This parameter can be specified multiple times\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-user\-unit=\fR
+.RS 4
+Show messages for the specified user session unit\&. This will add a match for messages from the unit ("_SYSTEMD_USER_UNIT="
+and
+"_UID=") and additional matches for messages from session systemd and messages about coredumps for the specified unit\&. A match is also added for
+"_SYSTEMD_USER_SLICE=\fIUNIT\fR", such that if the provided
+\fIUNIT\fR
+is a
+\fBsystemd.slice\fR(5)
+unit, all logs of children of the unit will be shown\&.
+.sp
+This parameter can be specified multiple times\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-t\fR, \fB\-\-identifier=\fR\fB\fISYSLOG_IDENTIFIER\fR\fR
+.RS 4
+Show messages for the specified syslog identifier
+\fISYSLOG_IDENTIFIER\fR\&.
+.sp
+This parameter can be specified multiple times\&.
+.sp
+Added in version 217\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-priority=\fR
+.RS 4
+Filter output by message priorities or priority ranges\&. Takes either a single numeric or textual log level (i\&.e\&. between 0/"emerg"
+and 7/"debug"), or a range of numeric/text log levels in the form FROM\&.\&.TO\&. The log levels are the usual syslog log levels as documented in
+\fBsyslog\fR(3), i\&.e\&.
+"emerg"\ \&(0),
+"alert"\ \&(1),
+"crit"\ \&(2),
+"err"\ \&(3),
+"warning"\ \&(4),
+"notice"\ \&(5),
+"info"\ \&(6),
+"debug"\ \&(7)\&. If a single log level is specified, all messages with this log level or a lower (hence more important) log level are shown\&. If a range is specified, all messages within the range are shown, including both the start and the end value of the range\&. This will add
+"PRIORITY="
+matches for the specified priorities\&.
+.sp
+Added in version 188\&.
+.RE
+.PP
+\fB\-\-facility=\fR
+.RS 4
+Filter output by syslog facility\&. Takes a comma\-separated list of numbers or facility names\&. The names are the usual syslog facilities as documented in
+\fBsyslog\fR(3)\&.
+\fB\-\-facility=help\fR
+may be used to display a list of known facility names and exit\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-g\fR, \fB\-\-grep=\fR
+.RS 4
+Filter output to entries where the
+\fIMESSAGE=\fR
+field matches the specified regular expression\&. PERL\-compatible regular expressions are used, see
+\fBpcre2pattern\fR(3)
+for a detailed description of the syntax\&.
+.sp
+If the pattern is all lowercase, matching is case insensitive\&. Otherwise, matching is case sensitive\&. This can be overridden with the
+\fB\-\-case\-sensitive\fR
+option, see below\&.
+.sp
+When used with
+\fB\-\-lines=\fR
+(not prefixed with
+"+"),
+\fB\-\-reverse\fR
+is implied\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-\-case\-sensitive\fR\fB[=BOOLEAN]\fR
+.RS 4
+Make pattern matching case sensitive or case insensitive\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-k\fR, \fB\-\-dmesg\fR
+.RS 4
+Show only kernel messages\&. This implies
+\fB\-b\fR
+and adds the match
+"_TRANSPORT=kernel"\&.
+.sp
+Added in version 205\&.
+.RE
+.SH "OUTPUT OPTIONS"
+.PP
+The following options control how journal records are printed:
+.PP
+\fB\-o\fR, \fB\-\-output=\fR
+.RS 4
+Controls the formatting of the journal entries that are shown\&. Takes one of the following options:
+.PP
+\fBshort\fR
+.RS 4
+is the default and generates an output that is mostly identical to the formatting of classic syslog files, showing one line per journal entry\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBshort\-full\fR
+.RS 4
+is very similar, but shows timestamps in the format the
+\fB\-\-since=\fR
+and
+\fB\-\-until=\fR
+options accept\&. Unlike the timestamp information shown in
+\fBshort\fR
+output mode this mode includes weekday, year and timezone information in the output, and is locale\-independent\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fBshort\-iso\fR
+.RS 4
+is very similar, but shows timestamps in the
+\m[blue]\fBRFC 3339\fR\m[]\&\s-2\u[2]\d\s+2
+profile of ISO 8601\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBshort\-iso\-precise\fR
+.RS 4
+as for
+\fBshort\-iso\fR
+but includes full microsecond precision\&.
+.sp
+Added in version 234\&.
+.RE
+.PP
+\fBshort\-precise\fR
+.RS 4
+is very similar, but shows classic syslog timestamps with full microsecond precision\&.
+.sp
+Added in version 207\&.
+.RE
+.PP
+\fBshort\-monotonic\fR
+.RS 4
+is very similar, but shows monotonic timestamps instead of wallclock timestamps\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBshort\-delta\fR
+.RS 4
+as for
+\fBshort\-monotonic\fR
+but includes the time difference to the previous entry\&. Maybe unreliable time differences are marked by a
+"*"\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fBshort\-unix\fR
+.RS 4
+is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock timestamps ("UNIX time")\&. The time is shown with microsecond accuracy\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fBverbose\fR
+.RS 4
+shows the full\-structured entry items with all fields\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBexport\fR
+.RS 4
+serializes the journal into a binary (but mostly text\-based) stream suitable for backups and network transfer (see
+\m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2
+for more information)\&. To import the binary stream back into native journald format use
+\fBsystemd-journal-remote\fR(8)\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBjson\fR
+.RS 4
+formats entries as JSON objects, separated by newline characters (see
+\m[blue]\fBJournal JSON Format\fR\m[]\&\s-2\u[4]\d\s+2
+for more information)\&. Field values are generally encoded as JSON strings, with three exceptions:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+Fields larger than 4096 bytes are encoded as
+\fBnull\fR
+values\&. (This may be turned off by passing
+\fB\-\-all\fR, but be aware that this may allocate overly long JSON objects\&.)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+Journal entries permit non\-unique fields within the same log entry\&. JSON does not allow non\-unique fields within objects\&. Due to this, if a non\-unique field is encountered a JSON array is used as field value, listing all field values as elements\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+Fields containing non\-printable or non\-UTF8 bytes are encoded as arrays containing the raw bytes individually formatted as unsigned numbers\&.
+.RE
+.sp
+Note that this encoding is reversible (with the exception of the size limit)\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBjson\-pretty\fR
+.RS 4
+formats entries as JSON data structures, but formats them in multiple lines in order to make them more readable by humans\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBjson\-sse\fR
+.RS 4
+formats entries as JSON data structures, but wraps them in a format suitable for
+\m[blue]\fBServer\-Sent Events\fR\m[]\&\s-2\u[5]\d\s+2\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBjson\-seq\fR
+.RS 4
+formats entries as JSON data structures, but prefixes them with an ASCII Record Separator character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in accordance with
+\m[blue]\fBJavaScript Object Notation (JSON) Text Sequences\fR\m[]\&\s-2\u[6]\d\s+2
+("application/json\-seq")\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fBcat\fR
+.RS 4
+generates a very terse output, only showing the actual message of each journal entry with no metadata, not even a timestamp\&. If combined with the
+\fB\-\-output\-fields=\fR
+option will output the listed fields for each log record, instead of the message\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBwith\-unit\fR
+.RS 4
+similar to
+\fBshort\-full\fR, but prefixes the unit and user unit names instead of the traditional syslog identifier\&. Useful when using templated instances, as it will include the arguments in the unit names\&.
+.sp
+Added in version 239\&.
+.RE
+.RE
+.PP
+\fB\-\-truncate\-newline\fR
+.RS 4
+Truncate each log message at the first newline character on output, so that only the first line of each message is displayed\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-output\-fields=\fR
+.RS 4
+A comma separated list of the fields which should be included in the output\&. This has an effect only for the output modes which would normally show all fields (\fBverbose\fR,
+\fBexport\fR,
+\fBjson\fR,
+\fBjson\-pretty\fR,
+\fBjson\-sse\fR
+and
+\fBjson\-seq\fR), as well as on
+\fBcat\fR\&. For the former, the
+"__CURSOR",
+"__REALTIME_TIMESTAMP",
+"__MONOTONIC_TIMESTAMP", and
+"_BOOT_ID"
+fields are always printed\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-lines=\fR
+.RS 4
+Show the most recent journal events and limit the number of events shown\&. The argument is a positive integer or
+"all"
+to disable the limit\&. Additionally, if the number is prefixed with
+"+", the oldest journal events are used instead\&. The default value is 10 if no argument is given\&.
+.sp
+If
+\fB\-\-follow\fR
+is used, this option is implied\&. When not prefixed with
+"+"
+and used with
+\fB\-\-grep=\fR,
+\fB\-\-reverse\fR
+is implied\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-reverse\fR
+.RS 4
+Reverse output so that the newest entries are displayed first\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-\-show\-cursor\fR
+.RS 4
+The cursor is shown after the last entry after two dashes:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\-\- cursor: s=0639\&...
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The format of the cursor is private and subject to change\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-utc\fR
+.RS 4
+Express time in Coordinated Universal Time (UTC)\&.
+.sp
+Added in version 217\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-catalog\fR
+.RS 4
+Augment log lines with explanation texts from the message catalog\&. This will add explanatory help texts to log messages in the output where this is available\&. These short help texts will explain the context of an error or log event, possible solutions, as well as pointers to support forums, developer documentation, and any other relevant manuals\&. Note that help texts are not available for all messages, but only for selected ones\&. For more information on the message catalog, please refer to the
+\m[blue]\fBMessage Catalog Developer Documentation\fR\m[]\&\s-2\u[7]\d\s+2\&.
+.sp
+Note: when attaching
+\fBjournalctl\fR
+output to bug reports, please do
+\fInot\fR
+use
+\fB\-x\fR\&.
+.sp
+Added in version 196\&.
+.RE
+.PP
+\fB\-\-no\-hostname\fR
+.RS 4
+Don\*(Aqt show the hostname field of log messages originating from the local host\&. This switch has an effect only on the
+\fBshort\fR
+family of output modes (see above)\&.
+.sp
+Note: this option does not remove occurrences of the hostname from log entries themselves, so it does not prevent the hostname from being visible in the logs\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-no\-full\fR, \fB\-\-full\fR, \fB\-l\fR
+.RS 4
+Ellipsize fields when they do not fit in available columns\&. The default is to show full fields, allowing them to wrap or be truncated by the pager, if one is used\&.
+.sp
+The old options
+\fB\-l\fR/\fB\-\-full\fR
+are not useful anymore, except to undo
+\fB\-\-no\-full\fR\&.
+.sp
+Added in version 196\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-all\fR
+.RS 4
+Show all fields in full, even if they include unprintable characters or are very long\&. By default, fields with unprintable characters are abbreviated as "blob data"\&. (Note that the pager may escape unprintable characters again\&.)
+.RE
+.PP
+\fB\-f\fR, \fB\-\-follow\fR
+.RS 4
+Show only the most recent journal entries, and continuously print new entries as they are appended to the journal\&.
+.RE
+.PP
+\fB\-\-no\-tail\fR
+.RS 4
+Show all stored output lines, even in follow mode\&. Undoes the effect of
+\fB\-\-lines=\fR\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppresses all informational messages (i\&.e\&. "\-\- Journal begins at \&...", "\-\- Reboot \-\-"), any warning messages regarding inaccessible system journals when run as a normal user\&.
+.RE
+.SH "PAGER CONTROL OPTIONS"
+.PP
+The following options control page support:
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-e\fR, \fB\-\-pager\-end\fR
+.RS 4
+Immediately jump to the end of the journal inside the implied pager tool\&. This implies
+\fB\-n1000\fR
+to guarantee that the pager will not buffer logs of unbounded size\&. This may be overridden with an explicit
+\fB\-n\fR
+with some other numeric value, while
+\fB\-nall\fR
+will disable this cap\&. Note that this option is only supported for the
+\fBless\fR(1)
+pager\&.
+.sp
+Added in version 198\&.
+.RE
+.SH "FORWARD SECURE SEALING (FSS) OPTIONS"
+.PP
+The following options may be used together with the
+\fB\-\-setup\-keys\fR
+command described below:
+.PP
+\fB\-\-interval=\fR
+.RS 4
+Specifies the change interval for the sealing key when generating an FSS key pair with
+\fB\-\-setup\-keys\fR\&. Shorter intervals increase CPU consumption but shorten the time range of undetectable journal alterations\&. Defaults to 15min\&.
+.sp
+Added in version 189\&.
+.RE
+.PP
+\fB\-\-verify\-key=\fR
+.RS 4
+Specifies the FSS verification key to use for the
+\fB\-\-verify\fR
+operation\&.
+.sp
+Added in version 189\&.
+.RE
+.PP
+\fB\-\-force\fR
+.RS 4
+When
+\fB\-\-setup\-keys\fR
+is passed and Forward Secure Sealing (FSS) has already been configured, recreate FSS keys\&.
+.sp
+Added in version 206\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood\&. If none is specified the default is to display journal records\&.
+.PP
+\fB\-N\fR, \fB\-\-fields\fR
+.RS 4
+Print all field names currently used in all entries of the journal\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fB\-F\fR, \fB\-\-field=\fR
+.RS 4
+Print all possible data values the specified field can take in all entries of the journal\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-list\-boots\fR
+.RS 4
+Show a tabular list of boot numbers (relative to the current boot), their IDs, and the timestamps of the first and last message pertaining to the boot\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-disk\-usage\fR
+.RS 4
+Shows the current disk usage of all journal files\&. This shows the sum of the disk usage of all archived and active journal files\&.
+.sp
+Added in version 190\&.
+.RE
+.PP
+\fB\-\-vacuum\-size=\fR, \fB\-\-vacuum\-time=\fR, \fB\-\-vacuum\-files=\fR
+.RS 4
+\fB\-\-vacuum\-size=\fR
+removes the oldest archived journal files until the disk space they use falls below the specified size\&. Accepts the usual
+"K",
+"M",
+"G"
+and
+"T"
+suffixes (to the base of 1024)\&.
+.sp
+\fB\-\-vacuum\-time=\fR
+removes archived journal files older than the specified timespan\&. Accepts the usual
+"s"
+(default),
+"m",
+"h",
+"days",
+"weeks",
+"months", and
+"years"
+suffixes, see
+\fBsystemd.time\fR(7)
+for details\&.
+.sp
+\fB\-\-vacuum\-files=\fR
+leaves only the specified number of separate journal files\&.
+.sp
+Note that running
+\fB\-\-vacuum\-size=\fR
+has only an indirect effect on the output shown by
+\fB\-\-disk\-usage\fR, as the latter includes active journal files, while the vacuuming operation only operates on archived journal files\&. Similarly,
+\fB\-\-vacuum\-files=\fR
+might not actually reduce the number of journal files to below the specified number, as it will not remove active journal files\&.
+.sp
+\fB\-\-vacuum\-size=\fR,
+\fB\-\-vacuum\-time=\fR
+and
+\fB\-\-vacuum\-files=\fR
+may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit on the archived journal files\&. Specifying any of these three parameters as zero is equivalent to not enforcing the specific limit, and is thus redundant\&.
+.sp
+These three switches may also be combined with
+\fB\-\-rotate\fR
+into one command\&. If so, all active files are rotated first, and the requested vacuuming operation is executed right after\&. The rotation has the effect that all currently active files are archived (and potentially new, empty journal files opened as replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so far into account\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-verify\fR
+.RS 4
+Check the journal file for internal consistency\&. If the file has been generated with FSS enabled and the FSS verification key has been specified with
+\fB\-\-verify\-key=\fR, authenticity of the journal file is verified\&.
+.sp
+Added in version 189\&.
+.RE
+.PP
+\fB\-\-sync\fR
+.RS 4
+Asks the journal daemon to write all yet unwritten journal data to the backing file system and synchronize all journals\&. This call does not return until the synchronization operation is complete\&. This command guarantees that any log messages written before its invocation are safely stored on disk at the time it returns\&.
+.sp
+Added in version 228\&.
+.RE
+.PP
+\fB\-\-relinquish\-var\fR
+.RS 4
+Asks the journal daemon for the reverse operation to
+\fB\-\-flush\fR: if requested the daemon will write further log data to
+/run/log/journal/
+and stops writing to
+/var/log/journal/\&. A subsequent call to
+\fB\-\-flush\fR
+causes the log output to switch back to
+/var/log/journal/, see above\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fB\-\-smart\-relinquish\-var\fR
+.RS 4
+Similar to
+\fB\-\-relinquish\-var\fR, but executes no operation if the root file system and
+/var/log/journal/
+reside on the same mount point\&. This operation is used during system shutdown in order to make the journal daemon stop writing data to
+/var/log/journal/
+in case that directory is located on a mount point that needs to be unmounted\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fB\-\-flush\fR
+.RS 4
+Asks the journal daemon to flush any log data stored in
+/run/log/journal/
+into
+/var/log/journal/, if persistent storage is enabled\&. This call does not return until the operation is complete\&. Note that this call is idempotent: the data is only flushed from
+/run/log/journal/
+into
+/var/log/journal/
+once during system runtime (but see
+\fB\-\-relinquish\-var\fR
+below), and this command exits cleanly without executing any operation if this has already happened\&. This command effectively guarantees that all data is flushed to
+/var/log/journal/
+at the time it returns\&.
+.sp
+Added in version 217\&.
+.RE
+.PP
+\fB\-\-rotate\fR
+.RS 4
+Asks the journal daemon to rotate journal files\&. This call does not return until the rotation operation is complete\&. Journal file rotation has the effect that all currently active journal files are marked as archived and renamed, so that they are never written to in future\&. New (empty) journal files are then created in their place\&. This operation may be combined with
+\fB\-\-vacuum\-size=\fR,
+\fB\-\-vacuum\-time=\fR
+and
+\fB\-\-vacuum\-file=\fR
+into a single command, see above\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-header\fR
+.RS 4
+Instead of showing journal contents, show internal header information of the journal fields accessed\&.
+.sp
+This option is particularly useful when trying to identify out\-of\-order journal entries, as happens for example when the machine is booted with the wrong system time\&.
+.sp
+Added in version 187\&.
+.RE
+.PP
+\fB\-\-list\-catalog \fR\fB[\fI128\-bit\-ID\&...\fR]\fR
+.RS 4
+List the contents of the message catalog as a table of message IDs, plus their short description strings\&.
+.sp
+If any
+\fI128\-bit\-ID\fRs are specified, only those entries are shown\&.
+.sp
+Added in version 196\&.
+.RE
+.PP
+\fB\-\-dump\-catalog \fR\fB[\fI128\-bit\-ID\&...\fR]\fR
+.RS 4
+Show the contents of the message catalog, with entries separated by a line consisting of two dashes and the ID (the format is the same as
+\&.catalog
+files)\&.
+.sp
+If any
+\fI128\-bit\-ID\fRs are specified, only those entries are shown\&.
+.sp
+Added in version 199\&.
+.RE
+.PP
+\fB\-\-update\-catalog\fR
+.RS 4
+Update the message catalog index\&. This command needs to be executed each time new catalog files are installed, removed, or updated to rebuild the binary catalog index\&.
+.sp
+Added in version 196\&.
+.RE
+.PP
+\fB\-\-setup\-keys\fR
+.RS 4
+Instead of showing journal contents, generate a new key pair for Forward Secure Sealing (FSS)\&. This will generate a sealing key and a verification key\&. The sealing key is stored in the journal data directory and shall remain on the host\&. The verification key should be stored externally\&. Refer to the
+\fBSeal=\fR
+option in
+\fBjournald.conf\fR(5)
+for information on Forward Secure Sealing and for a link to a refereed scholarly paper detailing the cryptographic theory it is based on\&.
+.sp
+Added in version 189\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned; otherwise, a non\-zero failure code is returned\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+Without arguments, all collected logs are shown unfiltered:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+With one match specified, all entries with a field matching the expression are shown:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl _SYSTEMD_UNIT=avahi\-daemon\&.service
+journalctl _SYSTEMD_CGROUP=/user\&.slice/user\-42\&.slice/session\-c1\&.scope
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+If two different fields are matched, only entries matching both expressions at the same time are shown:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl _SYSTEMD_UNIT=avahi\-daemon\&.service _PID=28097
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+If two matches refer to the same field, all entries matching either expression are shown:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl _SYSTEMD_UNIT=avahi\-daemon\&.service _SYSTEMD_UNIT=dbus\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+If the separator
+"+"
+is used, two expressions may be combined in a logical OR\&. The following will show all messages from the Avahi service process with the PID 28097 plus all messages from the D\-Bus service (from any of its processes):
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl _SYSTEMD_UNIT=avahi\-daemon\&.service _PID=28097 + _SYSTEMD_UNIT=dbus\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To show all fields emitted
+\fIby\fR
+a unit and
+\fIabout\fR
+the unit, option
+\fB\-u\fR/\fB\-\-unit=\fR
+should be used\&.
+\fBjournalctl \-u \fR\fB\fIname\fR\fR
+expands to a complex filter similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+_SYSTEMD_UNIT=\fIname\fR\&.service
+  + UNIT=\fIname\fR\&.service _PID=1
+  + OBJECT_SYSTEMD_UNIT=\fIname\fR\&.service _UID=0
+  + COREDUMP_UNIT=\fIname\fR\&.service _UID=0 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+(see
+\fBsystemd.journal-fields\fR(7)
+for an explanation of those patterns)\&.
+.PP
+Show all logs generated by the D\-Bus executable:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl /usr/bin/dbus\-daemon
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Show all kernel logs from previous boot:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl \-k \-b \-1
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Show a live log display from a system service
+apache\&.service:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+journalctl \-f \-u apache
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-cat\fR(1),
+\fBsystemd-journald.service\fR(8),
+\fBsystemctl\fR(1),
+\fBcoredumpctl\fR(1),
+\fBsystemd.journal-fields\fR(7),
+\fBjournald.conf\fR(5),
+\fBsystemd.time\fR(7),
+\fBsystemd-journal-remote.service\fR(8),
+\fBsystemd-journal-upload.service\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
+.IP " 2." 4
+RFC 3339
+.RS 4
+\%https://tools.ietf.org/html/rfc3339
+.RE
+.IP " 3." 4
+Journal Export Format
+.RS 4
+\%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
+.RE
+.IP " 4." 4
+Journal JSON Format
+.RS 4
+\%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format
+.RE
+.IP " 5." 4
+Server-Sent Events
+.RS 4
+\%https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events
+.RE
+.IP " 6." 4
+JavaScript Object Notation (JSON) Text Sequences
+.RS 4
+\%https://tools.ietf.org/html/rfc7464
+.RE
+.IP " 7." 4
+Message Catalog Developer Documentation
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/systemd/catalog
+.RE
diff --git a/upstream/mageia-cauldron/man1/jpeg2ktopam.1 b/upstream/mageia-cauldron/man1/jpeg2ktopam.1
new file mode 100644
index 00000000..6e2fe401
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/jpeg2ktopam.1
@@ -0,0 +1,164 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Jpeg2ktopam User Manual" 0 "08 October 2009" "netpbm documentation"
+
+.SH NAME
+jpeg2ktopam - convert JPEG-2000 code stream to PAM/PNM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBjpeg2ktopam\fP
+[\fB-verbose\fP]
+[\fB-debuglevel=\fP\fInumber\fP]
+\fIfilename\fP
+
+.SH OPTION USAGE
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBjpeg2ktopam\fP converts the named JPEG-2000 file (JP2 or JPC),
+or Standard Input if no file is named, to a PBM, PGM, PPM, or PAM
+file on Standard Output.
+.PP
+The JPEG-2000 specification specifies two different formats: JP2 and
+JPEG-2000 code stream (JPC).  JP2 represents a visual image quite
+specifically, whereas JPC is a more or less arbitrary array of codes.  A JP2
+image contains a JPC stream and metadata describing how that stream represents
+a visual image.  \fBjpeg2ktopam\fP converts both.
+.PP
+If the color space identified in the image is grayscale
+(JAS_IMAGE_CS_GRAY), \fBjpeg2ktopam\fP generates a PGM image, unless the
+image contains only one bit per pixel, in which case \fBjpeg2ktopam\fP
+generates PBM.  If the color space is RGB (JAS_IMAGE_CS_RGB),
+\fBjpeg2ktopam\fP generates a PPM image.  If the input image is anything
+else, \fBjpeg2ktopam\fP generates a PAM image with no tuple type identified.
+.PP
+In the PGM and PPM cases, \fBjpeg2ktopam\fP assumes the intensity
+values in the input image have the same meaning as for PGM and PPM.
+One thing that implies is the ITU-R Recommendation BT.709 color space,
+which means the assumption is false for JP2 input.  JP2 input uses
+SRGB color encoding.  So if you use \fBjpeg2ktopam\fP to convert a
+JP2 image to PPM, it changes the visual image (slightly) -- the colors
+in the output are not the same as in the input.
+.PP
+In the PAM image, the output samples are numerically identical to
+the input samples.  If the input samples are signed, they are
+represented in two's complement form in the output (because PAM
+samples are always unsigned).  The PAM plane numbers are identical to
+the JPC component numbers.
+.PP
+A JPEG-2000 image has a "precision," which is the number of bits used for
+each code (in Netpbm lingo, "sample").  Actually, each component has a
+separate precision.  The maxval of a PGM, PPM, or PAM output is the
+largest number you can represent in the JPEG-2000 precision of the JPEG-2000
+component with the greatest precision.  The samples in all components are
+scaled to that maxval.  So if the red component has a precision of 4 bits
+and the green component has a precision of 6 bits, the maxval is 63 and
+the red component codes from the JPEG-2000 image are multiplied by 63/15 to
+generate the output samples.
+.PP
+\fBjpeg2ktopam\fP interprets the JPEG-2000 input with the 
+.UR http://www.ece.uvic.ca/~mdadams/jasper/
+Jasper JPEG-2000 library
+.UE
+\&.  See documentation of the library for details on what
+\fBjpeg2ktopam\fP handles.  Note that the Jasper library contains
+facilities for writing PNM images, but \fBjpeg2ktopam\fP does not use
+those.  It uses the Netpbm library instead.  Note that the makers of
+the Jasper library write it "JasPer," but Netpbm documentation follows
+standard American English typography rules, which don't allow that
+kind of capitalization.
+.PP
+Use \fBpamtojpeg2k\fP to convert in the other direction.
+.PP
+The program \fBjasper\fP, which is packaged with the Jasper 
+JPEG-2000 library, also converts between JPEG-2000 and PNM formats.
+Because it's packaged with the library, it may exploit it better, 
+especially recently added features.  However, since it does not use the
+Netpbm library to read and write the Netpbm formats, it doesn't do as
+good a job on that side.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBjpeg2ktopam\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-verbose\fP
+This option causes \fBjpeg2ktopam\fP to issue informational
+messages about the conversion process.
+
+.TP
+\fB-debuglevel\fP=\fInumber\fP
+This option controls debug messages from the Jasper library.  
+\fBjpeg2ktopam\fP passes \fInumber\fP as the debug level to the Jasper
+JPEG-2000 decoder.
+
+
+     
+.UN examples
+.SH EXAMPLES
+
+.nf
+  jpeg2ktopam myimg.jpc >myimg.ppm
+
+.fi
+
+.UN jpeg2000
+.SH ABOUT JPEG-2000
+.PP
+See
+.BR "the \fBpamtojpeg2k\fP manual" (1)\c
+\&
+for general information on JPEG-2000 compression and the
+JPEG-2000 formats.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtojpeg2k" (1)\c
+\&,
+.BR "jpegtopnm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBjpeg2ktopam\fP was added to Netpbm in Release 10.12 (November 2002).
+.PP
+Before Netpbm 10.49 (December 2009), \fBjpeg2ktopam\fP could not convert
+a JP2 file -- only JPC.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/jpeg2ktopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/jpegtopnm.1 b/upstream/mageia-cauldron/man1/jpegtopnm.1
new file mode 100644
index 00000000..9233f708
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/jpegtopnm.1
@@ -0,0 +1,371 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Jpegtopnm User Manual" 0 "13 October 2002" "netpbm documentation"
+
+.SH NAME
+jpegtopnm - convert JPEG/JFIF file to PPM or PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBjpegtopnm\fP
+[\fB-dct\fP {\fBint\fP|\fBfast\fP|\fBfloat\fP}]
+[\fB-nosmooth\fP]
+[\fB-maxmemory\fP \fIN\fP]
+[{\fB-adobe\fP|\fB-notadobe\fP}]
+[\fB-comments\fP]
+[\fB-dumpexif\fP]
+[\fB-exif=\fP\fIfilespec\fP]
+[\fB-multiple\fP]
+[\fB-repair\fP]
+[\fB-verbose\fP]
+[\fB-tracelevel\fP \fIN\fP]
+[\fIfilename\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBjpegtopnm\fP converts JFIF images to PPM or PGM images.
+.PP
+By default, \fBjpegtopnm\fP expects the input stream to contain one
+JFIF image and produces one PGM or PPM image as output.  It fails if the
+input stream is empty.
+.PP
+But with the \fB-multiple\fP option, \fBjpegtopnm\fP reads JFIF
+images sequentially from the input stream and writes one PPM or PGM image
+to the output stream for each JFIF input.  If the input stream is empty,
+so is the output.
+.PP
+The input stream is the \fIfilename\fP you specify or, if you
+don't specify \fIfilename\fP, Standard Input.  The output stream is
+Standard Output.
+.PP
+If a JFIF input image is of the grayscale variety, \fBjpegtopnm\fP
+generates a PGM image.  Otherwise, it generates a PPM image.
+.PP
+Before Netpbm 10.11 (October 2002), \fBjpegtopnm\fP did not have
+the multiple image stream capability.  From 10.11 through 10.22,
+Netpbm always behaved as if you specified \fB-multiple\fP.  Starting
+with Netpbm 10.23 (July 2004), Netpbm's default behavior went back to
+the pre-10.11 behavior and the new \fB-multiple\fP option selected
+the 10.12 behavior.  The reason for the reversion was that there were
+discovered in the world files that contain JFIF images followed by
+something other than another JFIF image.  The producers of these files
+expect them to work with any JFIF interpreter because most JFIF
+interpreters just stop reading the file after the first JFIF image.
+.PP
+\fBjpegtopnm\fP uses the Independent JPEG Group's JPEG library to
+interpret the input file.  See \fB
+.UR http://www.ijg.org
+http://www.ijg.org
+.UE
+\& \fP
+for information on the library.
+.PP
+"JFIF" is the correct name for the image format commonly
+known as "JPEG." Strictly speaking, JPEG is a method of
+compression.  The image format using JPEG compression that is by far
+the most common is JFIF.  There is also a subformat of TIFF that uses
+JPEG compression.
+.PP
+EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
+file that contains an EXIF header as an APP1 marker).
+\fBjpegtopnm\fP handles EXIF.
+.PP
+JFIF files can have either 8 bits per sample or 12 bits per sample.
+The 8 bit variety is by far the most common.  There are two versions
+of the IJG JPEG library.  One reads only 8 bit files and the other
+reads only 12 bit files.  You must link the appropriate one of these
+libraries with \fBjpegtopnm\fP.  Ordinarily, this means the library
+is in your shared library search path when you run \fBjpegtopnm\fP.
+.PP
+\fBjpegtopnm\fP generates output with either one byte or two bytes
+per sample depending on whether the JFIF input has either 8 bits or 12
+bits per sample.  You can use \fBpamdepth\fP to reduce a
+two-byte-per-sample file to a one-byte-per-sample file if you need to.
+.PP
+If the JFIF file uses the CMYK or YCCK color space, the input does
+not actually contain enough information to know what color each pixel
+is.  To know what color a pixel is, one would have to know the
+properties of the inks to which the color space refers.
+\fBjpegtopnm\fP interprets the colors using the common transformation
+which assumes all the inks are simply subtractive and linear.
+.PP
+See the
+.BR "\fBjpegtopnm\fP manual" (1)\c
+\&
+for information on how images lose quality when you convert to and
+from JFIF.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBjpegtopnm\fP recognizes the following
+command line options:
+.PP
+The options are only for advanced users.
+
+
+.TP
+\fB-dct int\fP
+Use integer DCT method (default).
+
+.TP
+\fB-dct fast\fP
+Use fast integer DCT (less accurate).
+
+.TP
+\fB-dct float\fP
+Use floating-point DCT method.
+The float method is very slightly more accurate than the int method, but is
+much slower unless your machine has very fast floating-point hardware.  Also
+note that results of the floating-point method may vary slightly across
+machines, while the integer methods should give the same results everywhere.
+The fast integer method is much less accurate than the other two.
+
+.TP
+\fB-nosmooth\fP
+Use a faster, lower-quality upsampling routine.
+.TP
+\fB-maxmemory\fP\fI N\fP
+Set limit on the amount of memory \fBjpegtopnm\fP uses in
+processing large images.  Value is in thousands of bytes, or millions
+of bytes if "M" is suffixed to the number.  For example,
+\fB-maxmemory 4m\fP selects 4000000 bytes.  If \fBjpegtopnm\fP needs
+more space, it uses temporary files.
+
+.TP
+\fB-adobe\fP
+.TP
+\fB-notadobe\fP
+There are two variations on the CMYK (and likewise YCCK) color space that
+may be used in the JFIF input.  In the normal one, a zero value for a color
+components indicates absence of ink.  In the other, a zero value means the
+maximum ink coverage.  The latter is used by Adobe Photoshop when it creates
+a bare JFIF output file (but not when it creates JFIF output as part of
+Encapsulated Postscript output).
+.sp
+These options tell \fBjpegtopnm\fP which version of the CMYK or
+YCCK color space the image uses.  If you specify neither,
+\fBjpegtopnm\fP tries to figure it out on its own.  In the present
+version, it doesn't try very hard at all: It just assumes the
+Photoshop version, since Photoshop and its emulators seem to be the
+main source of CMYK and YCCK images.  But with experience of use,
+future versions might be more sophisticated.
+.sp
+If the JFIF image does not indicate that it is CMYK or YCCK, these
+options have no effect.
+.sp
+If you don't use the right one of these options, the symptom is
+output that looks like a negative.
+
+.TP
+\fB-dumpexif\fP
+Print the interpreted contents of any Exif header in the input
+file to the Standard Error file.  Similar to the program \fBjhead\fP
+(not part of the Netpbm package).
+.sp
+This option was added in Netpbm 9.19 (September 2001).
+     
+.TP
+\fB-exif=\fP\fIfilespec\fP
+Extract the contents of the EXIF header from the input image and
+write it to the file \fIfilespec\fP.  \fIfilespec\fP=\fB-\fP means
+write it to Standard Output.  When you write the EXIF header to
+Standard Output, \fBjpegtopnm\fP does not output the converted image
+(which is what normally would go to Standard Output) at all.
+.sp
+\fBjpegtopnm\fP writes the contents of the EXIF header
+byte-for-byte, starting with the two byte length field (which length
+includes those two bytes).
+.sp
+You can use this file as input to \fBpnmtojpeg\fP to insert an
+identical EXIF header into a new JFIF image.
+.sp
+If there is no EXIF header, \fBjpegtopnm\fP writes two bytes of
+binary zero and nothing else.
+.sp
+An EXIF header takes the form of a JFIF APP1 marker.  Only the
+first such marker within the JFIF header counts.
+.sp
+This option was added in Netpbm 9.19 (September 2001).
+
+.TP
+\fB-multiple\fP
+Read multiple JFIF images sequentially from the input stream.
+See 
+.UR #description
+Description section
+.UE
+\& for details.
+.sp
+This option was new in Netpbm 10.23 (July 2004).
+
+.TP
+\fB-repair\fP
+If the JFIF input is invalid, try to salvage whatever information is
+there and produce a valid PNM image as output.
+.sp
+Without this option, some invalid input causes \fBjpegtopnm\fP
+to fail, and what output it produces is undefined.  With \fB-repair\fP
+such invalid input causes \fBjpegtopnm\fP to succeed instead.
+.sp
+But note that there are some forms of invalid input that always cause
+\fBjpegtopnm\fP to fail and others that always cause it to salvage image
+information and succeed.
+.sp
+One particular case where \fB-repair\fP makes a difference is the
+common case that the file is truncated somewhere after the JFIF
+header.  Without \fB-repair\fP, that always causes a failure; with
+\fB-repair\fP it always causes success.  Because the image
+information is laid out generally top to bottom in the JFIF stream,
+the image \fBjpegtopnm\fP produces in this case has the proper image
+contents at the top, but the bottom is padded with gray.
+.sp
+This option was new in Netpbm 10.38.0 (March 2007).  Before that,
+\fBjpegtopnm\fP always fails in the cases in question.
+
+
+.TP
+\fB-comments\fP
+Print any comments in the input file to the Standard Error file.
+
+.TP
+\fB-verbose\fP
+Print details about the conversion to the Standard Error file.
+
+.TP
+\fB-tracelevel\fP\fI n\fP
+Turn on the JPEG library's trace messages to the Standard Error
+file.  A higher value of \fIn\fP gets more trace information.
+\fB-verbose\fP implies a trace level of at least 1.
+
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+This example converts the color JFIF file foo.jpg to a PPM file
+named foo.ppm:
+
+.nf
+    jpegtopnm foo.jpg >foo.ppm
+
+.fi
+
+.UN hints
+.SH HINTS
+
+You can use \fBpnmquant\fP to color quantize the result, i.e. to
+reduce the number of distinct colors in the image.  In fact, you may
+have to if you want to convert the PPM file to certain other formats.
+\fBppmdither\fP Does a more sophisticated quantization.
+.PP
+Use \fBpamscale\fP to change the dimensions of the resulting
+image.
+.PP
+Use \fBppmtopgm \fP to convert a color JFIF file to a grayscale
+PGM file.
+.PP
+You can easily use these converters together.  E.g.:
+
+.nf
+    jpegtopnm foo.jpg | ppmtopgm | pamscale .25 >foo.pgm
+
+.fi
+.PP
+\fB-dct fast\fP and/or \fB-nosmooth\fP gain speed at a small
+sacrifice in quality.
+.PP
+If you are fortunate enough to have very fast floating point
+hardware, \fB-dct float\fP may be even faster than \fB-dct fast\fP.
+But on most machines \fB-dct float\fP is slower than \fB-dct int\fP;
+in this case it is not worth using, because its theoretical accuracy
+advantage is too small to be significant in practice.
+.PP
+Another program, \fBdjpeg\fP, is similar.  \fBdjpeg\fP is
+maintained by the Independent JPEG Group and packaged with the JPEG
+library which \fBjpegtopnm\fP uses for all its JPEG work.  Because of
+that, you may expect it to exploit more current JPEG features.  Also,
+since you have to have the library to run \fBjpegtopnm\fP, but not
+vice versa, \fBcjpeg\fP may be more commonly available.
+.PP
+On the other hand, \fBdjpeg\fP does not use the NetPBM libraries
+to generate its output, as all the NetPBM tools such as
+\fBjpegtopnm\fP do.  This means it is less likely to be consistent
+with all the other programs that deal with the NetPBM formats.  Also,
+the command syntax of \fBjpegtopnm\fP is consistent with that of the
+other Netpbm tools, unlike \fBdjpeg\fP.
+
+.UN environment
+.SH ENVIRONMENT
+
+
+.TP
+\fBJPEGMEM\fP
+If this environment variable is set, its value is the default
+memory limit.  The value is specified as described for the
+\fB-maxmemory\fP option.  An explicit \fB-maxmemory \fP option
+overrides any \fBJPEGMEM\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pnmtojpeg" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.PP
+\fBdjpeg\fP man page,
+\fBcjpeg\fP man page,
+\fBjpegtran\fP man page,
+\fBrdjpgcom\fP man page,
+\fBwrjpgcom\fP man page,
+\fBjhead\fP man page
+.PP
+Wallace, Gregory K.  "The JPEG Still Picture Compression
+Standard", Communications of the ACM, April 1991 (vol. 34,
+no. 4), pp. 30-44.
+
+.UN author
+.SH AUTHOR
+.PP
+\fBjpegtopnm\fP and this manual were derived in large part from
+\fBdjpeg\fP, by the Independent JPEG Group.  The program is otherwise
+by Bryan Henderson on March 19, 2000.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/jpegtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/json_pp.1 b/upstream/mageia-cauldron/man1/json_pp.1
new file mode 100644
index 00000000..a2b51e57
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/json_pp.1
@@ -0,0 +1,167 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "JSON_PP 1"
+.TH JSON_PP 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+json_pp \- JSON::PP command utility
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    json_pp [\-v] [\-f from_format] [\-t to_format] [\-json_opt options_to_json1[,options_to_json2[,...]]]
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+json_pp converts between some input and output formats (one of them is JSON).
+This program was copied from json_xs and modified.
+.PP
+The default input format is json and the default output format is json with pretty option.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.SS \-f
+.IX Subsection "-f"
+.Vb 1
+\&    \-f from_format
+.Ve
+.PP
+Reads a data in the given format from STDIN.
+.PP
+Format types:
+.IP json 4
+.IX Item "json"
+as JSON
+.IP eval 4
+.IX Item "eval"
+as Perl code
+.SS \-t
+.IX Subsection "-t"
+Writes a data in the given format to STDOUT.
+.IP null 4
+.IX Item "null"
+no action.
+.IP json 4
+.IX Item "json"
+as JSON
+.IP dumper 4
+.IX Item "dumper"
+as Data::Dumper
+.SS \-json_opt
+.IX Subsection "-json_opt"
+options to JSON::PP
+.PP
+Acceptable options are:
+.PP
+.Vb 2
+\&    ascii latin1 utf8 pretty indent space_before space_after relaxed canonical allow_nonref
+\&    allow_singlequote allow_barekey allow_bignum loose escape_slash indent_length
+.Ve
+.PP
+Multiple options must be separated by commas:
+.PP
+.Vb 1
+\&    Right: \-json_opt pretty,canonical
+\&
+\&    Wrong: \-json_opt pretty \-json_opt canonical
+.Ve
+.SS \-v
+.IX Subsection "-v"
+Verbose option, but currently no action in fact.
+.SS \-V
+.IX Subsection "-V"
+Prints version and exits.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 2
+\&    $ perl \-e\*(Aqprint q|{"foo":"��","bar":1234567890000000000000000}|\*(Aq |\e
+\&       json_pp \-f json \-t dumper \-json_opt pretty,utf8,allow_bignum
+\&    
+\&    $VAR1 = {
+\&              \*(Aqbar\*(Aq => bless( {
+\&                                \*(Aqvalue\*(Aq => [
+\&                                             \*(Aq0000000\*(Aq,
+\&                                             \*(Aq0000000\*(Aq,
+\&                                             \*(Aq5678900\*(Aq,
+\&                                             \*(Aq1234\*(Aq
+\&                                           ],
+\&                                \*(Aqsign\*(Aq => \*(Aq+\*(Aq
+\&                              }, \*(AqMath::BigInt\*(Aq ),
+\&              \*(Aqfoo\*(Aq => "\ex{3042}\ex{3044}"
+\&            };
+\&
+\&    $ perl \-e\*(Aqprint q|{"foo":"��","bar":1234567890000000000000000}|\*(Aq |\e
+\&       json_pp \-f json \-t dumper \-json_opt pretty
+\&    
+\&    $VAR1 = {
+\&              \*(Aqbar\*(Aq => \*(Aq1234567890000000000000000\*(Aq,
+\&              \*(Aqfoo\*(Aq => "\ex{e3}\ex{81}\ex{82}\ex{e3}\ex{81}\ex{84}"
+\&            };
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+JSON::PP, json_xs
+.SH AUTHOR
+.IX Header "AUTHOR"
+Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2010 by Makamaka Hannyaharamitu
+.PP
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/kbd_mode.1 b/upstream/mageia-cauldron/man1/kbd_mode.1
new file mode 100644
index 00000000..fc0da12a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/kbd_mode.1
@@ -0,0 +1,51 @@
+.\" @(#)kbd_mode.1 1.0 940406 aeb
+.TH KBD_MODE 1 "6 Apr 1994" "kbd"
+.SH NAME
+kbd_mode \- report or set the keyboard mode
+.SH SYNOPSIS
+.B kbd_mode
+[
+.I -a | -u | -k | -s 
+] [
+.I -f
+] [
+.I -C CONSOLE
+]
+.SH DESCRIPTION
+.IX "kbd_mode command" "" "\fLkbd_mode\fR command"  
+.LP
+Without argument,
+.B kbd_mode
+prints the current keyboard mode (RAW, MEDIUMRAW or XLATE).
+With argument, it sets the keyboard mode as indicated:
+.LP
+\-s: scancode mode (RAW),
+.LP
+\-k: keycode mode (MEDIUMRAW),
+.LP
+\-a: ASCII mode (XLATE),
+.LP
+\-u: UTF-8 mode (UNICODE).
+.LP
+Of course the "\-a" is only traditional, and the code used can be any
+8-bit character set.  With "\-u" a 16-bit character set is expected,
+and these chars are transmitted to the kernel as 1, 2, or 3 bytes
+(following the UTF-8 coding).
+In these latter two modes the key mapping defined by
+.BR loadkeys (1)
+is used.
+
+kbd_mode operates on the console specified by the "\-C" option; if there
+is none, the console associated with stdin is used.
+
+Warning: changing the keyboard mode, other than between ASCII and
+Unicode, will probably make your keyboard unusable. Set the "\-f" option
+to force such changes.
+This command is only meant for use (say via remote login)
+when some program left your keyboard in the wrong state.
+Note that in some obsolete versions of this program the "\-u"
+option was a synonym for "\-s" and older versions of this program may
+not recognize the "\-f" option.
+.SH "SEE ALSO"
+.BR loadkeys (1)
+
diff --git a/upstream/mageia-cauldron/man1/kbdinfo.1 b/upstream/mageia-cauldron/man1/kbdinfo.1
new file mode 100644
index 00000000..a4cf48e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/kbdinfo.1
@@ -0,0 +1,91 @@
+.TH KBDINFO "1" "June 2019" "kbd"
+.SH NAME
+kbdinfo \- read information about keyboard state
+.SH SYNOPSIS
+.B kbdinfo
+[\fI\,options\/\fR] \fI\,getmode \/\fR[\fI\,text|graphics\/\fR]
+.br
+.B kbdinfo
+[\fI\,options\/\fR] \fI\,gkbmode \/\fR[\fI\,raw|xlate|mediumraw|unicode\/\fR]
+.br
+.B kbdinfo
+[\fI\,options\/\fR] \fI\,gkbmeta \/\fR[\fI\,metabit|escprefix\/\fR]
+.br
+.B kbdinfo
+[\fI\,options\/\fR] \fI\,gkbled  \/\fR[\fI\,scrolllock|numlock|capslock\/\fR]
+.SH DESCRIPTION
+The utility allows you to read and check various parameters of the keyboard and
+virtual console.
+.TP 9
+.B getmode
+Get or check virtual console mode.
+.TP 9
+.B gkbmode
+Gets current keyboard mode.
+.LP
+.RS
+.TP 12
+.B raw
+Raw (scancode) mode. These are the raw codes generated by the keyboard.
+.TP 12
+.B mediumraw
+Medium raw (scancode) mode. This is extended medium raw mode, with keys above
+127 encoded as 0, high 7 bits, low 7 bits, with the 0 bearing the 'up' flag if
+needed. 0 is reserved, so this shouldn't interfere with anything else. The two
+bytes after 0 will always have the up flag set not to interfere with older
+applications. This allows for 16384 different keycodes, which should be enough.
+.TP 12
+.B xlate
+Translate keycodes using keymap. These are the codes generated via the current
+keysym mapping.
+.TP 12
+.B unicode
+Unicode mode.
+.RE
+.LP
+.TP 9
+.B gkbmeta
+Gets meta key handling mode.
+.LP
+.RS
+.TP 12
+.B escprefix
+Specifies if pressing the meta (alt) key generates an ESC (\\033) prefix followed by the keysym.
+.TP 12
+.B metabit
+The keysym marked with the high bit set.
+.RE
+.LP
+
+.TP 9
+.B gkbled
+Get keyboard flags CapsLock, NumLock, ScrollLock (not lights).
+.LP
+.RS
+.TP 12
+.B scrolllock
+The scroll lock is down.
+.TP 12
+.B numlock
+The num lock is down.
+.TP 12
+.B capslock
+The caps lock is down.
+.RE
+.LP
+.SH OPTIONS
+.TP
+\fB\-C\fR, \fB\-\-console\fR=\fI\,DEV\/\fR
+the console device to be used;
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number;
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this usage message.
+.SH AUTHORS
+Written by Alexey Gladkov.
+.SH "SEE ALSO"
+.BR kbdrate (1),
+.BR setleds (1),
+.BR kbd_mode (1)
diff --git a/upstream/mageia-cauldron/man1/ld.1 b/upstream/mageia-cauldron/man1/ld.1
new file mode 100644
index 00000000..16629fd0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ld.1
@@ -0,0 +1,3466 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "LD 1"
+.TH LD 1 "2023-01-14" "binutils-2.40.00" "GNU Development Tools"
+.\" 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"
+ld \- The GNU linker
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+ld [\fBoptions\fR] \fIobjfile\fR ...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBld\fR combines a number of object and archive files, relocates
+their data and ties up symbol references. Usually the last step in
+compiling a program is to run \fBld\fR.
+.PP
+\&\fBld\fR accepts Linker Command Language files written in
+a superset of \s-1AT&T\s0's Link Editor Command Language syntax,
+to provide explicit and total control over the linking process.
+.PP
+This man page does not describe the command language; see the
+\&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command
+language and on other aspects of the \s-1GNU\s0 linker.
+.PP
+This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries
+to operate on object files. This allows \fBld\fR to read, combine, and
+write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
+\&\f(CW\*(C`a.out\*(C'\fR.  Different formats may be linked together to produce any
+available kind of object file.
+.PP
+Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other
+linkers in providing diagnostic information.  Many linkers abandon
+execution immediately upon encountering an error; whenever possible,
+\&\fBld\fR continues executing, allowing you to identify other errors
+(or, in some cases, to get an output file in spite of the error).
+.PP
+The \s-1GNU\s0 linker \fBld\fR is meant to cover a broad range of situations,
+and to be as compatible as possible with other linkers.  As a result,
+you have many choices to control its behavior.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The linker supports a plethora of command-line options, but in actual
+practice few of them are used in any particular context.
+For instance, a frequent use of \fBld\fR is to link standard Unix
+object files on a standard, supported Unix system.  On such a system, to
+link a file \f(CW\*(C`hello.o\*(C'\fR:
+.PP
+.Vb 1
+\&        ld \-o <output> /lib/crt0.o hello.o \-lc
+.Ve
+.PP
+This tells \fBld\fR to produce a file called \fIoutput\fR as the
+result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and
+the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search
+directories.  (See the discussion of the \fB\-l\fR option below.)
+.PP
+Some of the command-line options to \fBld\fR may be specified at any
+point in the command line.  However, options which refer to files, such
+as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at
+which the option appears in the command line, relative to the object
+files and other file options.  Repeating non-file options with a
+different argument will either have no further effect, or override prior
+occurrences (those further to the left on the command line) of that
+option.  Options which may be meaningfully specified more than once are
+noted in the descriptions below.
+.PP
+Non-option arguments are object files or archives which are to be linked
+together.  They may follow, precede, or be mixed in with command-line
+options, except that an object file argument may not be placed between
+an option and its argument.
+.PP
+Usually the linker is invoked with at least one object file, but you can
+specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,
+and the script command language.  If \fIno\fR binary input files at all
+are specified, the linker does not produce any output, and issues the
+message \fBNo input files\fR.
+.PP
+If the linker cannot recognize the format of an object file, it will
+assume that it is a linker script.  A script specified in this way
+augments the main linker script used for the link (either the default
+linker script or the one specified by using \fB\-T\fR).  This feature
+permits the linker to link against a file which appears to be an object
+or an archive, but actually merely defines some symbol values, or uses
+\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects.  Specifying a
+script in this way merely augments the main linker script, with the
+extra commands placed after the main script; use the \fB\-T\fR option
+to replace the default linker script entirely, but note the effect of
+the \f(CW\*(C`INSERT\*(C'\fR command.
+.PP
+For options whose names are a single letter,
+option arguments must either follow the option letter without intervening
+whitespace, or be given as separate arguments immediately following the
+option that requires them.
+.PP
+For options whose names are multiple letters, either one dash or two can
+precede the option name; for example, \fB\-trace\-symbol\fR and
+\&\fB\-\-trace\-symbol\fR are equivalent.  Note\-\-\-there is one exception to
+this rule.  Multiple letter options that start with a lower case 'o' can
+only be preceded by two dashes.  This is to reduce confusion with the
+\&\fB\-o\fR option.  So for example \fB\-omagic\fR sets the output file
+name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the \s-1NMAGIC\s0 flag on the
+output.
+.PP
+Arguments to multiple-letter options must either be separated from the
+option name by an equals sign, or be given as separate arguments
+immediately following the option that requires them.  For example,
+\&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent.
+Unique abbreviations of the names of multiple-letter options are
+accepted.
+.PP
+Note\-\-\-if the linker is being invoked indirectly, via a compiler driver
+(e.g. \fBgcc\fR) then all the linker command-line options should be
+prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular
+compiler driver) like this:
+.PP
+.Vb 1
+\&          gcc \-Wl,\-\-start\-group foo.o bar.o \-Wl,\-\-end\-group
+.Ve
+.PP
+This is important, because otherwise the compiler driver program may
+silently drop the linker options, resulting in a bad link.  Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument acts as
+a separator, and causes the driver to pass only the option to the linker
+and the argument to the compiler.  In this case, it is simplest to use
+the joined forms of both single\- and multiple-letter options, such as:
+.PP
+.Vb 1
+\&          gcc foo.o bar.o \-Wl,\-eENTRY \-Wl,\-Map=a.map
+.Ve
+.PP
+Here is a table of the generic command-line switches accepted by the \s-1GNU\s0
+linker:
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.IP "\fB\-a\fR \fIkeyword\fR" 4
+.IX Item "-a keyword"
+This option is supported for \s-1HP/UX\s0 compatibility.  The \fIkeyword\fR
+argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
+\&\fBdefault\fR.  \fB\-aarchive\fR is functionally equivalent to
+\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
+to \fB\-Bdynamic\fR.  This option may be used any number of times.
+.IP "\fB\-\-audit\fR \fI\s-1AUDITLIB\s0\fR" 4
+.IX Item "--audit AUDITLIB"
+Adds \fI\s-1AUDITLIB\s0\fR to the \f(CW\*(C`DT_AUDIT\*(C'\fR entry of the dynamic section.
+\&\fI\s-1AUDITLIB\s0\fR is not checked for existence, nor will it use the \s-1DT_SONAME\s0
+specified in the library.  If specified multiple times \f(CW\*(C`DT_AUDIT\*(C'\fR
+will contain a colon separated list of audit interfaces to use. If the linker
+finds an object with an audit entry while searching for shared libraries,
+it will add a corresponding \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry in the output file.
+This option is only meaningful on \s-1ELF\s0 platforms supporting the rtld-audit
+interface.
+.IP "\fB\-b\fR \fIinput-format\fR" 4
+.IX Item "-b input-format"
+.PD 0
+.IP "\fB\-\-format=\fR\fIinput-format\fR" 4
+.IX Item "--format=input-format"
+.PD
+\&\fBld\fR may be configured to support more than one kind of object
+file.  If your \fBld\fR is configured this way, you can use the
+\&\fB\-b\fR option to specify the binary format for input object files
+that follow this option on the command line.  Even when \fBld\fR is
+configured to support alternative object formats, you don't usually need
+to specify this, as \fBld\fR should be configured to expect as a
+default input format the most usual format on each machine.
+\&\fIinput-format\fR is a text string, the name of a particular format
+supported by the \s-1BFD\s0 libraries.  (You can list the available binary
+formats with \fBobjdump \-i\fR.)
+.Sp
+You may want to use this option if you are linking files with an unusual
+binary format.  You can also use \fB\-b\fR to switch formats explicitly (when
+linking object files of different formats), by including
+\&\fB\-b\fR \fIinput-format\fR before each group of object files in a
+particular format.
+.Sp
+The default format is taken from the environment variable
+\&\f(CW\*(C`GNUTARGET\*(C'\fR.
+.Sp
+You can also define the input format from a script, using the command
+\&\f(CW\*(C`TARGET\*(C'\fR;
+.IP "\fB\-c\fR \fIMRI-commandfile\fR" 4
+.IX Item "-c MRI-commandfile"
+.PD 0
+.IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4
+.IX Item "--mri-script=MRI-commandfile"
+.PD
+For compatibility with linkers produced by \s-1MRI,\s0 \fBld\fR accepts script
+files written in an alternate, restricted command language, described in
+the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
+Introduce \s-1MRI\s0 script files with
+the option \fB\-c\fR; use the \fB\-T\fR option to run linker
+scripts written in the general-purpose \fBld\fR scripting language.
+If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories
+specified by any \fB\-L\fR options.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-dc\fR" 4
+.IX Item "-dc"
+.IP "\fB\-dp\fR" 4
+.IX Item "-dp"
+.PD
+These three options are equivalent; multiple forms are supported for
+compatibility with other linkers.  They assign space to common symbols
+even if a relocatable output file is specified (with \fB\-r\fR).  The
+script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
+.IP "\fB\-\-depaudit\fR \fI\s-1AUDITLIB\s0\fR" 4
+.IX Item "--depaudit AUDITLIB"
+.PD 0
+.IP "\fB\-P\fR \fI\s-1AUDITLIB\s0\fR" 4
+.IX Item "-P AUDITLIB"
+.PD
+Adds \fI\s-1AUDITLIB\s0\fR to the \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry of the dynamic section.
+\&\fI\s-1AUDITLIB\s0\fR is not checked for existence, nor will it use the \s-1DT_SONAME\s0
+specified in the library.  If specified multiple times \f(CW\*(C`DT_DEPAUDIT\*(C'\fR
+will contain a colon separated list of audit interfaces to use.  This
+option is only meaningful on \s-1ELF\s0 platforms supporting the rtld-audit interface.
+The \-P option is provided for Solaris compatibility.
+.IP "\fB\-\-enable\-non\-contiguous\-regions\fR" 4
+.IX Item "--enable-non-contiguous-regions"
+This option avoids generating an error if an input section does not
+fit a matching output section. The linker tries to allocate the input
+section to subseque nt matching output sections, and generates an
+error only if no output section is large enough.  This is useful when
+several non-contiguous memory regions are available and the input
+section does not require a particular one.  The order in which input
+sections are evaluated does not change, for instance:
+.Sp
+.Vb 10
+\&          MEMORY {
+\&            MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14
+\&            MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40
+\&            MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40
+\&          }
+\&          SECTIONS {
+\&            mem1 : { *(.data.*); } > MEM1
+\&            mem2 : { *(.data.*); } > MEM2
+\&            mem3 : { *(.data.*); } > MEM2
+\&          }
+\&        
+\&          with input sections:
+\&          .data.1: size 8
+\&          .data.2: size 0x10
+\&          .data.3: size 4
+\&        
+\&          results in .data.1 affected to mem1, and .data.2 and .data.3
+\&          affected to mem2, even though .data.3 would fit in mem3.
+.Ve
+.Sp
+This option is incompatible with \s-1INSERT\s0 statements because it changes
+the way input sections are mapped to output sections.
+.IP "\fB\-\-enable\-non\-contiguous\-regions\-warnings\fR" 4
+.IX Item "--enable-non-contiguous-regions-warnings"
+This option enables warnings when
+\&\f(CW\*(C`\-\-enable\-non\-contiguous\-regions\*(C'\fR allows possibly unexpected
+matches in sections mapping, potentially leading to silently
+discarding a section instead of failing because it does not fit any
+output region.
+.IP "\fB\-e\fR \fIentry\fR" 4
+.IX Item "-e entry"
+.PD 0
+.IP "\fB\-\-entry=\fR\fIentry\fR" 4
+.IX Item "--entry=entry"
+.PD
+Use \fIentry\fR as the explicit symbol for beginning execution of your
+program, rather than the default entry point.  If there is no symbol
+named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
+and use that as the entry address (the number will be interpreted in
+base 10; you may use a leading \fB0x\fR for base 16, or a leading
+\&\fB0\fR for base 8).
+.IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
+.IX Item "--exclude-libs lib,lib,..."
+Specifies a list of archive libraries from which symbols should not be automatically
+exported.  The library names may be delimited by commas or colons.  Specifying
+\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
+automatic export.  This option is available only for the i386 \s-1PE\s0 targeted
+port of the linker and for \s-1ELF\s0 targeted ports.  For i386 \s-1PE,\s0 symbols
+explicitly listed in a .def file are still exported, regardless of this
+option.  For \s-1ELF\s0 targeted ports, symbols affected by this option will
+be treated as hidden.
+.IP "\fB\-\-exclude\-modules\-for\-implib\fR \fImodule\fR\fB,\fR\fImodule\fR\fB,...\fR" 4
+.IX Item "--exclude-modules-for-implib module,module,..."
+Specifies a list of object files or archive members, from which symbols
+should not be automatically exported, but which should be copied wholesale
+into the import library being generated during the link.  The module names
+may be delimited by commas or colons, and must match exactly the filenames
+used by \fBld\fR to open the files; for archive members, this is simply
+the member name, but for object files the name listed must include and
+match precisely any path used to specify the input file on the linker's
+command-line.  This option is available only for the i386 \s-1PE\s0 targeted port
+of the linker.  Symbols explicitly listed in a .def file are still exported,
+regardless of this option.
+.IP "\fB\-E\fR" 4
+.IX Item "-E"
+.PD 0
+.IP "\fB\-\-export\-dynamic\fR" 4
+.IX Item "--export-dynamic"
+.IP "\fB\-\-no\-export\-dynamic\fR" 4
+.IX Item "--no-export-dynamic"
+.PD
+When creating a dynamically linked executable, using the \fB\-E\fR
+option or the \fB\-\-export\-dynamic\fR option causes the linker to add
+all symbols to the dynamic symbol table.  The dynamic symbol table is the
+set of symbols which are visible from dynamic objects at run time.
+.Sp
+If you do not use either of these options (or use the
+\&\fB\-\-no\-export\-dynamic\fR option to restore the default behavior), the
+dynamic symbol table will normally contain only those symbols which are
+referenced by some dynamic object mentioned in the link.
+.Sp
+If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
+back to the symbols defined by the program, rather than some other
+dynamic object, then you will probably need to use this option when
+linking the program itself.
+.Sp
+You can also use the dynamic list to control what symbols should
+be added to the dynamic symbol table if the output format supports it.
+See the description of \fB\-\-dynamic\-list\fR.
+.Sp
+Note that this option is specific to \s-1ELF\s0 targeted ports.  \s-1PE\s0 targets
+support a similar function to export all symbols from a \s-1DLL\s0 or \s-1EXE\s0; see
+the description of \fB\-\-export\-all\-symbols\fR below.
+.IP "\fB\-\-export\-dynamic\-symbol=\fR\fIglob\fR" 4
+.IX Item "--export-dynamic-symbol=glob"
+When creating a dynamically linked executable, symbols matching
+\&\fIglob\fR will be added to the dynamic symbol table. When creating a
+shared library, references to symbols matching \fIglob\fR will not be
+bound to the definitions within the shared library. This option is a
+no-op when creating a shared library and \fB\-Bsymbolic\fR or
+\&\fB\-\-dynamic\-list\fR are not specified. This option is only meaningful
+on \s-1ELF\s0 platforms which support shared libraries.
+.IP "\fB\-\-export\-dynamic\-symbol\-list=\fR\fIfile\fR" 4
+.IX Item "--export-dynamic-symbol-list=file"
+Specify a \fB\-\-export\-dynamic\-symbol\fR for each pattern in the file.
+The format of the file is the same as the version node without
+scope and node name.  See \fB\s-1VERSION\s0\fR for more information.
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+Link big-endian objects.  This affects the default output format.
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+Link little-endian objects.  This affects the default output format.
+.IP "\fB\-f\fR \fIname\fR" 4
+.IX Item "-f name"
+.PD 0
+.IP "\fB\-\-auxiliary=\fR\fIname\fR" 4
+.IX Item "--auxiliary=name"
+.PD
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field
+to the specified name.  This tells the dynamic linker that the symbol
+table of the shared object should be used as an auxiliary filter on the
+symbol table of the shared object \fIname\fR.
+.Sp
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field.  If
+the dynamic linker resolves any symbols from the filter object, it will
+first check whether there is a definition in the shared object
+\&\fIname\fR.  If there is one, it will be used instead of the definition
+in the filter object.  The shared object \fIname\fR need not exist.
+Thus the shared object \fIname\fR may be used to provide an alternative
+implementation of certain functions, perhaps for debugging or for
+machine-specific performance.
+.Sp
+This option may be specified more than once.  The \s-1DT_AUXILIARY\s0 entries
+will be created in the order in which they appear on the command line.
+.IP "\fB\-F\fR \fIname\fR" 4
+.IX Item "-F name"
+.PD 0
+.IP "\fB\-\-filter=\fR\fIname\fR" 4
+.IX Item "--filter=name"
+.PD
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to
+the specified name.  This tells the dynamic linker that the symbol table
+of the shared object which is being created should be used as a filter
+on the symbol table of the shared object \fIname\fR.
+.Sp
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field.  The
+dynamic linker will resolve symbols according to the symbol table of the
+filter object as usual, but it will actually link to the definitions
+found in the shared object \fIname\fR.  Thus the filter object can be
+used to select a subset of the symbols provided by the object
+\&\fIname\fR.
+.Sp
+Some older linkers used the \fB\-F\fR option throughout a compilation
+toolchain for specifying object-file format for both input and output
+object files.
+The \s-1GNU\s0 linker uses other mechanisms for this purpose: the
+\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the
+\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
+environment variable.
+The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
+creating an \s-1ELF\s0 shared object.
+.IP "\fB\-fini=\fR\fIname\fR" 4
+.IX Item "-fini=name"
+When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
+executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
+address of the function.  By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
+the function to call.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+Ignored.  Provided for compatibility with other tools.
+.IP "\fB\-G\fR \fIvalue\fR" 4
+.IX Item "-G value"
+.PD 0
+.IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
+.IX Item "--gpsize=value"
+.PD
+Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
+\&\fIsize\fR.  This is only meaningful for object file formats such as
+\&\s-1MIPS ELF\s0 that support putting large and small objects into different
+sections.  This is ignored for other object file formats.
+.IP "\fB\-h\fR \fIname\fR" 4
+.IX Item "-h name"
+.PD 0
+.IP "\fB\-soname=\fR\fIname\fR" 4
+.IX Item "-soname=name"
+.PD
+When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
+the specified name.  When an executable is linked with a shared object
+which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
+linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
+field rather than using the file name given to the linker.
+.IP "\fB\-i\fR" 4
+.IX Item "-i"
+Perform an incremental link (same as option \fB\-r\fR).
+.IP "\fB\-init=\fR\fIname\fR" 4
+.IX Item "-init=name"
+When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
+executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
+of the function.  By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
+function to call.
+.IP "\fB\-l\fR \fInamespec\fR" 4
+.IX Item "-l namespec"
+.PD 0
+.IP "\fB\-\-library=\fR\fInamespec\fR" 4
+.IX Item "--library=namespec"
+.PD
+Add the archive or object file specified by \fInamespec\fR to the
+list of files to link.  This option may be used any number of times.
+If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR
+will search the library path for a file called \fIfilename\fR, otherwise it
+will search the library path for a file called \fIlib\fInamespec\fI.a\fR.
+.Sp
+On systems which support shared libraries, \fBld\fR may also search for
+files other than \fIlib\fInamespec\fI.a\fR.  Specifically, on \s-1ELF\s0
+and SunOS systems, \fBld\fR will search a directory for a library
+called \fIlib\fInamespec\fI.so\fR before searching for one called
+\&\fIlib\fInamespec\fI.a\fR.  (By convention, a \f(CW\*(C`.so\*(C'\fR extension
+indicates a shared library.)  Note that this behavior does not apply
+to \fI:\fIfilename\fI\fR, which always specifies a file called
+\&\fIfilename\fR.
+.Sp
+The linker will search an archive only once, at the location where it is
+specified on the command line.  If the archive defines a symbol which
+was undefined in some object which appeared before the archive on the
+command line, the linker will include the appropriate file(s) from the
+archive.  However, an undefined symbol in an object appearing later on
+the command line will not cause the linker to search the archive again.
+.Sp
+See the \fB\-(\fR option for a way to force the linker to search
+archives multiple times.
+.Sp
+You may list the same archive multiple times on the command line.
+.Sp
+This type of archive searching is standard for Unix linkers.  However,
+if you are using \fBld\fR on \s-1AIX,\s0 note that it is different from the
+behaviour of the \s-1AIX\s0 linker.
+.IP "\fB\-L\fR \fIsearchdir\fR" 4
+.IX Item "-L searchdir"
+.PD 0
+.IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
+.IX Item "--library-path=searchdir"
+.PD
+Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search
+for archive libraries and \fBld\fR control scripts.  You may use this
+option any number of times.  The directories are searched in the order
+in which they are specified on the command line.  Directories specified
+on the command line are searched before the default directories.  All
+\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
+order in which the options appear.  \fB\-L\fR options do not affect
+how \fBld\fR searches for a linker script unless \fB\-T\fR
+option is specified.
+.Sp
+If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR or \f(CW$SYSROOT\fR, then this
+prefix will be replaced by the \fIsysroot prefix\fR, controlled by the
+\&\fB\-\-sysroot\fR option, or specified when the linker is configured.
+.Sp
+The default set of paths searched (without being specified with
+\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in
+some cases also on how it was configured.
+.Sp
+The paths can also be specified in a link script with the
+\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command.  Directories specified this way are searched
+at the point in which the linker script appears in the command line.
+.IP "\fB\-m\fR \fIemulation\fR" 4
+.IX Item "-m emulation"
+Emulate the \fIemulation\fR linker.  You can list the available
+emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.
+.Sp
+If the \fB\-m\fR option is not used, the emulation is taken from the
+\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
+.Sp
+Otherwise, the default emulation depends upon how the linker was
+configured.
+.IP "\fB\-M\fR" 4
+.IX Item "-M"
+.PD 0
+.IP "\fB\-\-print\-map\fR" 4
+.IX Item "--print-map"
+.PD
+Print a link map to the standard output.  A link map provides
+information about the link, including the following:
+.RS 4
+.IP "\(bu" 4
+Where object files are mapped into memory.
+.IP "\(bu" 4
+How common symbols are allocated.
+.IP "\(bu" 4
+All archive members included in the link, with a mention of the symbol
+which caused the archive member to be brought in.
+.IP "\(bu" 4
+The values assigned to symbols.
+.Sp
+Note \- symbols whose values are computed by an expression which
+involves a reference to a previous value of the same symbol may not
+have correct result displayed in the link map.  This is because the
+linker discards intermediate results and only retains the final value
+of an expression.  Under such circumstances the linker will display
+the final value enclosed by square brackets.  Thus for example a
+linker script containing:
+.Sp
+.Vb 3
+\&           foo = 1
+\&           foo = foo * 4
+\&           foo = foo + 8
+.Ve
+.Sp
+will produce the following output in the link map if the \fB\-M\fR
+option is used:
+.Sp
+.Vb 3
+\&           0x00000001                foo = 0x1
+\&           [0x0000000c]                foo = (foo * 0x4)
+\&           [0x0000000c]                foo = (foo + 0x8)
+.Ve
+.Sp
+See \fBExpressions\fR for more information about expressions in linker
+scripts.
+.IP "\(bu" 4
+How \s-1GNU\s0 properties are merged.
+.Sp
+When the linker merges input .note.gnu.property sections into one output
+\&.note.gnu.property section, some properties are removed or updated.
+These actions are reported in the link map.  For example:
+.Sp
+.Vb 1
+\&        Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
+.Ve
+.Sp
+This indicates that property 0xc0000002 is removed from output when
+merging properties in  \fIfoo.o\fR, whose property 0xc0000002 value
+is 0x1, and \fIbar.o\fR, which doesn't have property 0xc0000002.
+.Sp
+.Vb 1
+\&        Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
+.Ve
+.Sp
+This indicates that property 0xc0010001 value is updated to 0x1 in output
+when merging properties in  \fIfoo.o\fR, whose 0xc0010001 property value
+is 0x1, and \fIbar.o\fR, whose 0xc0010001 property value is 0x1.
+.RE
+.RS 4
+.RE
+.IP "\fB\-\-print\-map\-discarded\fR" 4
+.IX Item "--print-map-discarded"
+.PD 0
+.IP "\fB\-\-no\-print\-map\-discarded\fR" 4
+.IX Item "--no-print-map-discarded"
+.PD
+Print (or do not print) the list of discarded and garbage collected sections
+in the link map.  Enabled by default.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-\-nmagic\fR" 4
+.IX Item "--nmagic"
+.PD
+Turn off page alignment of sections, and disable linking against shared
+libraries.  If the output format supports Unix style magic numbers,
+mark the output as \f(CW\*(C`NMAGIC\*(C'\fR.
+.IP "\fB\-N\fR" 4
+.IX Item "-N"
+.PD 0
+.IP "\fB\-\-omagic\fR" 4
+.IX Item "--omagic"
+.PD
+Set the text and data sections to be readable and writable.  Also, do
+not page-align the data segment, and disable linking against shared
+libraries.  If the output format supports Unix style magic numbers,
+mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section
+is allowed for PE-COFF targets, it does not conform to the format
+specification published by Microsoft.
+.IP "\fB\-\-no\-omagic\fR" 4
+.IX Item "--no-omagic"
+This option negates most of the effects of the \fB\-N\fR option.  It
+sets the text section to be read-only, and forces the data segment to
+be page-aligned.  Note \- this option does not enable linking against
+shared libraries.  Use \fB\-Bdynamic\fR for this.
+.IP "\fB\-o\fR \fIoutput\fR" 4
+.IX Item "-o output"
+.PD 0
+.IP "\fB\-\-output=\fR\fIoutput\fR" 4
+.IX Item "--output=output"
+.PD
+Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this
+option is not specified, the name \fIa.out\fR is used by default.  The
+script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
+.IP "\fB\-\-dependency\-file=\fR\fIdepfile\fR" 4
+.IX Item "--dependency-file=depfile"
+Write a \fIdependency file\fR to \fIdepfile\fR.  This file contains a rule
+suitable for \f(CW\*(C`make\*(C'\fR describing the output file and all the input files
+that were read to produce it.  The output is similar to the compiler's
+output with \fB\-M \-MP\fR.  Note that there is no option like the compiler's \fB\-MM\fR,
+to exclude \*(L"system files\*(R" (which is not a well-specified concept in the
+linker, unlike \*(L"system headers\*(R" in the compiler).  So the output from
+\&\fB\-\-dependency\-file\fR is always specific to the exact state of the
+installation where it was produced, and should not be copied into
+distributed makefiles without careful editing.
+.IP "\fB\-O\fR \fIlevel\fR" 4
+.IX Item "-O level"
+If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes
+the output.  This might take significantly longer and therefore probably
+should only be enabled for the final binary.  At the moment this
+option only affects \s-1ELF\s0 shared library generation.  Future releases of
+the linker may make more use of this option.  Also currently there is
+no difference in the linker's behaviour for different non-zero values
+of this option.  Again this may change with future releases.
+.IP "\fB\-plugin\fR \fIname\fR" 4
+.IX Item "-plugin name"
+Involve a plugin in the linking process.  The \fIname\fR parameter is
+the absolute filename of the plugin.  Usually this parameter is
+automatically added by the complier, when using link time
+optimization, but users can also add their own plugins if they so
+wish.
+.Sp
+Note that the location of the compiler originated plugins is different
+from the place where the \fBar\fR, \fBnm\fR and
+\&\fBranlib\fR programs search for their plugins.  In order for
+those commands to make use of a compiler based plugin it must first be
+copied into the \fI${libdir}/bfd\-plugins\fR directory.  All gcc
+based linker plugins are backward compatible, so it is sufficient to
+just copy in the newest one.
+.IP "\fB\-\-push\-state\fR" 4
+.IX Item "--push-state"
+The \fB\-\-push\-state\fR allows one to preserve the current state of the
+flags which govern the input file handling so that they can all be
+restored with one corresponding \fB\-\-pop\-state\fR option.
+.Sp
+The option which are covered are: \fB\-Bdynamic\fR, \fB\-Bstatic\fR,
+\&\fB\-dn\fR, \fB\-dy\fR, \fB\-call_shared\fR, \fB\-non_shared\fR,
+\&\fB\-static\fR, \fB\-N\fR, \fB\-n\fR, \fB\-\-whole\-archive\fR,
+\&\fB\-\-no\-whole\-archive\fR, \fB\-r\fR, \fB\-Ur\fR,
+\&\fB\-\-copy\-dt\-needed\-entries\fR, \fB\-\-no\-copy\-dt\-needed\-entries\fR,
+\&\fB\-\-as\-needed\fR, \fB\-\-no\-as\-needed\fR, and \fB\-a\fR.
+.Sp
+One target for this option are specifications for \fIpkg-config\fR.  When
+used with the \fB\-\-libs\fR option all possibly needed libraries are
+listed and then possibly linked with all the time.  It is better to return
+something as follows:
+.Sp
+.Vb 1
+\&        \-Wl,\-\-push\-state,\-\-as\-needed \-libone \-libtwo \-Wl,\-\-pop\-state
+.Ve
+.IP "\fB\-\-pop\-state\fR" 4
+.IX Item "--pop-state"
+Undoes the effect of \-\-push\-state, restores the previous values of the
+flags governing input file handling.
+.IP "\fB\-q\fR" 4
+.IX Item "-q"
+.PD 0
+.IP "\fB\-\-emit\-relocs\fR" 4
+.IX Item "--emit-relocs"
+.PD
+Leave relocation sections and contents in fully linked executables.
+Post link analysis and optimization tools may need this information in
+order to perform correct modifications of executables.  This results
+in larger executables.
+.Sp
+This option is currently only supported on \s-1ELF\s0 platforms.
+.IP "\fB\-\-force\-dynamic\fR" 4
+.IX Item "--force-dynamic"
+Force the output file to have dynamic sections.  This option is specific
+to VxWorks targets.
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-\-relocatable\fR" 4
+.IX Item "--relocatable"
+.PD
+Generate relocatable output\-\-\-i.e., generate an output file that can in
+turn serve as input to \fBld\fR.  This is often called \fIpartial
+linking\fR.  As a side effect, in environments that support standard Unix
+magic numbers, this option also sets the output file's magic number to
+\&\f(CW\*(C`OMAGIC\*(C'\fR.
+If this option is not specified, an absolute file is produced.  When
+linking \*(C+ programs, this option \fIwill not\fR resolve references to
+constructors; to do that, use \fB\-Ur\fR.
+.Sp
+When an input file does not have the same format as the output file,
+partial linking is only supported if that input file does not contain any
+relocations.  Different output formats can have further restrictions; for
+example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking
+with input files in other formats at all.
+.Sp
+This option does the same thing as \fB\-i\fR.
+.IP "\fB\-R\fR \fIfilename\fR" 4
+.IX Item "-R filename"
+.PD 0
+.IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--just-symbols=filename"
+.PD
+Read symbol names and their addresses from \fIfilename\fR, but do not
+relocate it or include it in the output.  This allows your output file
+to refer symbolically to absolute locations of memory defined in other
+programs.  You may use this option more than once.
+.Sp
+For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \fB\-rpath\fR option.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-strip\-all\fR" 4
+.IX Item "--strip-all"
+.PD
+Omit all symbol information from the output file.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-strip\-debug\fR" 4
+.IX Item "--strip-debug"
+.PD
+Omit debugger symbol information (but not all symbols) from the output file.
+.IP "\fB\-\-strip\-discarded\fR" 4
+.IX Item "--strip-discarded"
+.PD 0
+.IP "\fB\-\-no\-strip\-discarded\fR" 4
+.IX Item "--no-strip-discarded"
+.PD
+Omit (or do not omit) global symbols defined in discarded sections.
+Enabled by default.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.IP "\fB\-\-trace\fR" 4
+.IX Item "--trace"
+.PD
+Print the names of the input files as \fBld\fR processes them.  If
+\&\fB\-t\fR is given twice then members within archives are also printed.
+\&\fB\-t\fR output is useful to generate a list of all the object files
+and scripts involved in linking, for example, when packaging files for
+a linker bug report.
+.IP "\fB\-T\fR \fIscriptfile\fR" 4
+.IX Item "-T scriptfile"
+.PD 0
+.IP "\fB\-\-script=\fR\fIscriptfile\fR" 4
+.IX Item "--script=scriptfile"
+.PD
+Use \fIscriptfile\fR as the linker script.  This script replaces
+\&\fBld\fR's default linker script (rather than adding to it), so
+\&\fIcommandfile\fR must specify everything necessary to describe the
+output file.    If \fIscriptfile\fR does not exist in
+the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories
+specified by any preceding \fB\-L\fR options.  Multiple \fB\-T\fR
+options accumulate.
+.IP "\fB\-dT\fR \fIscriptfile\fR" 4
+.IX Item "-dT scriptfile"
+.PD 0
+.IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4
+.IX Item "--default-script=scriptfile"
+.PD
+Use \fIscriptfile\fR as the default linker script.
+.Sp
+This option is similar to the \fB\-\-script\fR option except that
+processing of the script is delayed until after the rest of the
+command line has been processed.  This allows options placed after the
+\&\fB\-\-default\-script\fR option on the command line to affect the
+behaviour of the linker script, which can be important when the linker
+command line cannot be directly controlled by the user.  (eg because
+the command line is being constructed by another tool, such as
+\&\fBgcc\fR).
+.IP "\fB\-u\fR \fIsymbol\fR" 4
+.IX Item "-u symbol"
+.PD 0
+.IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4
+.IX Item "--undefined=symbol"
+.PD
+Force \fIsymbol\fR to be entered in the output file as an undefined
+symbol.  Doing this may, for example, trigger linking of additional
+modules from standard libraries.  \fB\-u\fR may be repeated with
+different option arguments to enter additional undefined symbols.  This
+option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command.
+.Sp
+If this option is being used to force additional modules to be pulled
+into the link, and if it is an error for the symbol to remain
+undefined, then the option \fB\-\-require\-defined\fR should be used
+instead.
+.IP "\fB\-\-require\-defined=\fR\fIsymbol\fR" 4
+.IX Item "--require-defined=symbol"
+Require that \fIsymbol\fR is defined in the output file.  This option
+is the same as option \fB\-\-undefined\fR except that if \fIsymbol\fR
+is not defined in the output file then the linker will issue an error
+and exit.  The same effect can be achieved in a linker script by using
+\&\f(CW\*(C`EXTERN\*(C'\fR, \f(CW\*(C`ASSERT\*(C'\fR and \f(CW\*(C`DEFINED\*(C'\fR together.  This option
+can be used multiple times to require additional symbols.
+.IP "\fB\-Ur\fR" 4
+.IX Item "-Ur"
+For anything other than \*(C+ programs, this option is equivalent to
+\&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in
+turn serve as input to \fBld\fR.  When linking \*(C+ programs, \fB\-Ur\fR
+\&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.
+It does not work to use \fB\-Ur\fR on files that were themselves linked
+with \fB\-Ur\fR; once the constructor table has been built, it cannot
+be added to.  Use \fB\-Ur\fR only for the last partial link, and
+\&\fB\-r\fR for the others.
+.IP "\fB\-\-orphan\-handling=\fR\fI\s-1MODE\s0\fR" 4
+.IX Item "--orphan-handling=MODE"
+Control how orphan sections are handled.  An orphan section is one not
+specifically mentioned in a linker script.
+.Sp
+\&\fI\s-1MODE\s0\fR can have any of the following values:
+.RS 4
+.ie n .IP """place""" 4
+.el .IP "\f(CWplace\fR" 4
+.IX Item "place"
+Orphan sections are placed into a suitable output section following
+the strategy described in \fBOrphan Sections\fR.  The option
+\&\fB\-\-unique\fR also affects how sections are placed.
+.ie n .IP """discard""" 4
+.el .IP "\f(CWdiscard\fR" 4
+.IX Item "discard"
+All orphan sections are discarded, by placing them in the
+\&\fB/DISCARD/\fR section.
+.ie n .IP """warn""" 4
+.el .IP "\f(CWwarn\fR" 4
+.IX Item "warn"
+The linker will place the orphan section as for \f(CW\*(C`place\*(C'\fR and also
+issue a warning.
+.ie n .IP """error""" 4
+.el .IP "\f(CWerror\fR" 4
+.IX Item "error"
+The linker will exit with an error if any orphan section is found.
+.RE
+.RS 4
+.Sp
+The default if \fB\-\-orphan\-handling\fR is not given is \f(CW\*(C`place\*(C'\fR.
+.RE
+.IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4
+.IX Item "--unique[=SECTION]"
+Creates a separate output section for every input section matching
+\&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is
+missing, for every orphan input section.  An orphan section is one not
+specifically mentioned in a linker script.  You may use this option
+multiple times on the command line;  It prevents the normal merging of
+input sections with the same name, overriding output section assignments
+in a linker script.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD
+Display the version number for \fBld\fR.  The \fB\-V\fR option also
+lists the supported emulations.
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.IP "\fB\-\-discard\-all\fR" 4
+.IX Item "--discard-all"
+.PD
+Delete all local symbols.
+.IP "\fB\-X\fR" 4
+.IX Item "-X"
+.PD 0
+.IP "\fB\-\-discard\-locals\fR" 4
+.IX Item "--discard-locals"
+.PD
+Delete all temporary local symbols.  (These symbols start with
+system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems
+or \fBL\fR for traditional a.out systems.)
+.IP "\fB\-y\fR \fIsymbol\fR" 4
+.IX Item "-y symbol"
+.PD 0
+.IP "\fB\-\-trace\-symbol=\fR\fIsymbol\fR" 4
+.IX Item "--trace-symbol=symbol"
+.PD
+Print the name of each linked file in which \fIsymbol\fR appears.  This
+option may be given any number of times.  On many systems it is necessary
+to prepend an underscore.
+.Sp
+This option is useful when you have an undefined symbol in your link but
+don't know where the reference is coming from.
+.IP "\fB\-Y\fR \fIpath\fR" 4
+.IX Item "-Y path"
+Add \fIpath\fR to the default library search path.  This option exists
+for Solaris compatibility.
+.IP "\fB\-z\fR \fIkeyword\fR" 4
+.IX Item "-z keyword"
+The recognized keywords are:
+.RS 4
+.IP "\fBcall\-nop=prefix\-addr\fR" 4
+.IX Item "call-nop=prefix-addr"
+.PD 0
+.IP "\fBcall\-nop=suffix\-nop\fR" 4
+.IX Item "call-nop=suffix-nop"
+.IP "\fBcall\-nop=prefix\-\fR\fIbyte\fR" 4
+.IX Item "call-nop=prefix-byte"
+.IP "\fBcall\-nop=suffix\-\fR\fIbyte\fR" 4
+.IX Item "call-nop=suffix-byte"
+.PD
+Specify the 1\-byte \f(CW\*(C`NOP\*(C'\fR padding when transforming indirect call
+to a locally defined function, foo, via its \s-1GOT\s0 slot.
+\&\fBcall\-nop=prefix\-addr\fR generates \f(CW\*(C`0x67 call foo\*(C'\fR.
+\&\fBcall\-nop=suffix\-nop\fR generates \f(CW\*(C`call foo 0x90\*(C'\fR.
+\&\fBcall\-nop=prefix\-\fR\fIbyte\fR generates \f(CW\*(C`\f(CIbyte\f(CW call foo\*(C'\fR.
+\&\fBcall\-nop=suffix\-\fR\fIbyte\fR generates \f(CW\*(C`call foo \f(CIbyte\f(CW\*(C'\fR.
+Supported for i386 and x86_64.
+.IP "\fBcet\-report=none\fR" 4
+.IX Item "cet-report=none"
+.PD 0
+.IP "\fBcet\-report=warning\fR" 4
+.IX Item "cet-report=warning"
+.IP "\fBcet\-report=error\fR" 4
+.IX Item "cet-report=error"
+.PD
+Specify how to report the missing \s-1GNU_PROPERTY_X86_FEATURE_1_IBT\s0 and
+\&\s-1GNU_PROPERTY_X86_FEATURE_1_SHSTK\s0 properties in input .note.gnu.property
+section.  \fBcet\-report=none\fR, which is the default, will make the
+linker not report missing properties in input files.
+\&\fBcet\-report=warning\fR will make the linker issue a warning for
+missing properties in input files.  \fBcet\-report=error\fR will make
+the linker issue an error for missing properties in input files.
+Note that \fBibt\fR will turn off the missing
+\&\s-1GNU_PROPERTY_X86_FEATURE_1_IBT\s0 property report and \fBshstk\fR will
+turn off the missing \s-1GNU_PROPERTY_X86_FEATURE_1_SHSTK\s0 property report.
+Supported for Linux/i386 and Linux/x86_64.
+.IP "\fBcombreloc\fR" 4
+.IX Item "combreloc"
+.PD 0
+.IP "\fBnocombreloc\fR" 4
+.IX Item "nocombreloc"
+.PD
+Combine multiple dynamic relocation sections and sort to improve
+dynamic symbol lookup caching.  Do not do this if \fBnocombreloc\fR.
+.IP "\fBcommon\fR" 4
+.IX Item "common"
+.PD 0
+.IP "\fBnocommon\fR" 4
+.IX Item "nocommon"
+.PD
+Generate common symbols with \s-1STT_COMMON\s0 type during a relocatable
+link.  Use \s-1STT_OBJECT\s0 type if \fBnocommon\fR.
+.IP "\fBcommon\-page\-size=\fR\fIvalue\fR" 4
+.IX Item "common-page-size=value"
+Set the page size most commonly used to \fIvalue\fR.  Memory image
+layout will be optimized to minimize memory pages if the system is
+using pages of this size.
+.IP "\fBdefs\fR" 4
+.IX Item "defs"
+Report unresolved symbol references from regular object files.  This
+is done even if the linker is creating a non-symbolic shared library.
+This option is the inverse of \fB\-z undefs\fR.
+.IP "\fBdynamic-undefined-weak\fR" 4
+.IX Item "dynamic-undefined-weak"
+.PD 0
+.IP "\fBnodynamic-undefined-weak\fR" 4
+.IX Item "nodynamic-undefined-weak"
+.PD
+Make undefined weak symbols dynamic when building a dynamic object,
+if they are referenced from a regular object file and not forced local
+by symbol visibility or versioning.  Do not make them dynamic if
+\&\fBnodynamic-undefined-weak\fR.  If neither option is given, a target
+may default to either option being in force, or make some other
+selection of undefined weak symbols dynamic.  Not all targets support
+these options.
+.IP "\fBexecstack\fR" 4
+.IX Item "execstack"
+Marks the object as requiring executable stack.
+.IP "\fBglobal\fR" 4
+.IX Item "global"
+This option is only meaningful when building a shared object.  It makes
+the symbols defined by this shared object available for symbol resolution
+of subsequently loaded libraries.
+.IP "\fBglobalaudit\fR" 4
+.IX Item "globalaudit"
+This option is only meaningful when building a dynamic executable.
+This option marks the executable as requiring global auditing by
+setting the \f(CW\*(C`DF_1_GLOBAUDIT\*(C'\fR bit in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR dynamic
+tag.  Global auditing requires that any auditing library defined via
+the \fB\-\-depaudit\fR or \fB\-P\fR command-line options be run for
+all dynamic objects loaded by the application.
+.IP "\fBibtplt\fR" 4
+.IX Item "ibtplt"
+Generate Intel Indirect Branch Tracking (\s-1IBT\s0) enabled \s-1PLT\s0 entries.
+Supported for Linux/i386 and Linux/x86_64.
+.IP "\fBibt\fR" 4
+.IX Item "ibt"
+Generate \s-1GNU_PROPERTY_X86_FEATURE_1_IBT\s0 in .note.gnu.property section
+to indicate compatibility with \s-1IBT.\s0  This also implies \fBibtplt\fR.
+Supported for Linux/i386 and Linux/x86_64.
+.IP "\fBindirect-extern-access\fR" 4
+.IX Item "indirect-extern-access"
+.PD 0
+.IP "\fBnoindirect-extern-access\fR" 4
+.IX Item "noindirect-extern-access"
+.PD
+Generate \s-1GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS\s0 in
+\&.note.gnu.property section to indicate that object file requires
+canonical function pointers and cannot be used with copy relocation.
+This option also implies \fBnoextern-protected-data\fR and
+\&\fBnocopyreloc\fR.  Supported for i386 and x86\-64.
+.Sp
+\&\fBnoindirect-extern-access\fR removes
+\&\s-1GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS\s0 from .note.gnu.property
+section.
+.IP "\fBinitfirst\fR" 4
+.IX Item "initfirst"
+This option is only meaningful when building a shared object.
+It marks the object so that its runtime initialization will occur
+before the runtime initialization of any other objects brought into
+the process at the same time.  Similarly the runtime finalization of
+the object will occur after the runtime finalization of any other
+objects.
+.IP "\fBinterpose\fR" 4
+.IX Item "interpose"
+Specify that the dynamic loader should modify its symbol search order
+so that symbols in this shared library interpose all other shared
+libraries not so marked.
+.IP "\fBunique\fR" 4
+.IX Item "unique"
+.PD 0
+.IP "\fBnounique\fR" 4
+.IX Item "nounique"
+.PD
+When generating a shared library or other dynamically loadable \s-1ELF\s0
+object mark it as one that should (by default) only ever be loaded once,
+and only in the main namespace (when using \f(CW\*(C`dlmopen\*(C'\fR). This is
+primarily used to mark fundamental libraries such as libc, libpthread et
+al which do not usually function correctly unless they are the sole instances
+of themselves. This behaviour can be overridden by the \f(CW\*(C`dlmopen\*(C'\fR caller
+and does not apply to certain loading mechanisms (such as audit libraries).
+.IP "\fBlam\-u48\fR" 4
+.IX Item "lam-u48"
+Generate \s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U48\s0 in .note.gnu.property section
+to indicate compatibility with Intel \s-1LAM_U48.\s0  Supported for Linux/x86_64.
+.IP "\fBlam\-u57\fR" 4
+.IX Item "lam-u57"
+Generate \s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U57\s0 in .note.gnu.property section
+to indicate compatibility with Intel \s-1LAM_U57.\s0  Supported for Linux/x86_64.
+.IP "\fBlam\-u48\-report=none\fR" 4
+.IX Item "lam-u48-report=none"
+.PD 0
+.IP "\fBlam\-u48\-report=warning\fR" 4
+.IX Item "lam-u48-report=warning"
+.IP "\fBlam\-u48\-report=error\fR" 4
+.IX Item "lam-u48-report=error"
+.PD
+Specify how to report the missing \s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U48\s0
+property in input .note.gnu.property section.
+\&\fBlam\-u48\-report=none\fR, which is the default, will make the
+linker not report missing properties in input files.
+\&\fBlam\-u48\-report=warning\fR will make the linker issue a warning for
+missing properties in input files.  \fBlam\-u48\-report=error\fR will
+make the linker issue an error for missing properties in input files.
+Supported for Linux/x86_64.
+.IP "\fBlam\-u57\-report=none\fR" 4
+.IX Item "lam-u57-report=none"
+.PD 0
+.IP "\fBlam\-u57\-report=warning\fR" 4
+.IX Item "lam-u57-report=warning"
+.IP "\fBlam\-u57\-report=error\fR" 4
+.IX Item "lam-u57-report=error"
+.PD
+Specify how to report the missing \s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U57\s0
+property in input .note.gnu.property section.
+\&\fBlam\-u57\-report=none\fR, which is the default, will make the
+linker not report missing properties in input files.
+\&\fBlam\-u57\-report=warning\fR will make the linker issue a warning for
+missing properties in input files.  \fBlam\-u57\-report=error\fR will
+make the linker issue an error for missing properties in input files.
+Supported for Linux/x86_64.
+.IP "\fBlam\-report=none\fR" 4
+.IX Item "lam-report=none"
+.PD 0
+.IP "\fBlam\-report=warning\fR" 4
+.IX Item "lam-report=warning"
+.IP "\fBlam\-report=error\fR" 4
+.IX Item "lam-report=error"
+.PD
+Specify how to report the missing \s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U48\s0 and
+\&\s-1GNU_PROPERTY_X86_FEATURE_1_LAM_U57\s0 properties in input .note.gnu.property
+section.  \fBlam\-report=none\fR, which is the default, will make the
+linker not report missing properties in input files.
+\&\fBlam\-report=warning\fR will make the linker issue a warning for
+missing properties in input files.  \fBlam\-report=error\fR will make
+the linker issue an error for missing properties in input files.
+Supported for Linux/x86_64.
+.IP "\fBlazy\fR" 4
+.IX Item "lazy"
+When generating an executable or shared library, mark it to tell the
+dynamic linker to defer function call resolution to the point when
+the function is called (lazy binding), rather than at load time.
+Lazy binding is the default.
+.IP "\fBloadfltr\fR" 4
+.IX Item "loadfltr"
+Specify that the object's filters be processed immediately at runtime.
+.IP "\fBmax\-page\-size=\fR\fIvalue\fR" 4
+.IX Item "max-page-size=value"
+Set the maximum memory page size supported to \fIvalue\fR.
+.IP "\fBmuldefs\fR" 4
+.IX Item "muldefs"
+Allow multiple definitions.
+.IP "\fBnocopyreloc\fR" 4
+.IX Item "nocopyreloc"
+Disable linker generated .dynbss variables used in place of variables
+defined in shared libraries.  May result in dynamic text relocations.
+.IP "\fBnodefaultlib\fR" 4
+.IX Item "nodefaultlib"
+Specify that the dynamic loader search for dependencies of this object
+should ignore any default library search paths.
+.IP "\fBnodelete\fR" 4
+.IX Item "nodelete"
+Specify that the object shouldn't be unloaded at runtime.
+.IP "\fBnodlopen\fR" 4
+.IX Item "nodlopen"
+Specify that the object is not available to \f(CW\*(C`dlopen\*(C'\fR.
+.IP "\fBnodump\fR" 4
+.IX Item "nodump"
+Specify that the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR.
+.IP "\fBnoexecstack\fR" 4
+.IX Item "noexecstack"
+Marks the object as not requiring executable stack.
+.IP "\fBnoextern-protected-data\fR" 4
+.IX Item "noextern-protected-data"
+Don't treat protected data symbols as external when building a shared
+library.  This option overrides the linker backend default.  It can be
+used to work around incorrect relocations against protected data symbols
+generated by compiler.  Updates on protected data symbols by another
+module aren't visible to the resulting shared library.  Supported for
+i386 and x86\-64.
+.IP "\fBnoreloc-overflow\fR" 4
+.IX Item "noreloc-overflow"
+Disable relocation overflow check.  This can be used to disable
+relocation overflow check if there will be no dynamic relocation
+overflow at run-time.  Supported for x86_64.
+.IP "\fBnow\fR" 4
+.IX Item "now"
+When generating an executable or shared library, mark it to tell the
+dynamic linker to resolve all symbols when the program is started, or
+when the shared library is loaded by dlopen, instead of deferring
+function call resolution to the point when the function is first
+called.
+.IP "\fBorigin\fR" 4
+.IX Item "origin"
+Specify that the object requires \fB\f(CB$ORIGIN\fB\fR handling in paths.
+.IP "\fBpack-relative-relocs\fR" 4
+.IX Item "pack-relative-relocs"
+.PD 0
+.IP "\fBnopack-relative-relocs\fR" 4
+.IX Item "nopack-relative-relocs"
+.PD
+Generate compact relative relocation in position-independent executable
+and shared library.  It adds \f(CW\*(C`DT_RELR\*(C'\fR, \f(CW\*(C`DT_RELRSZ\*(C'\fR and
+\&\f(CW\*(C`DT_RELRENT\*(C'\fR entries to the dynamic section.  It is ignored when
+building position-dependent executable and relocatable output.
+\&\fBnopack-relative-relocs\fR is the default, which disables compact
+relative relocation.  When linked against the \s-1GNU C\s0 Library, a
+\&\s-1GLIBC_ABI_DT_RELR\s0 symbol version dependency on the shared C Library is
+added to the output.  Supported for i386 and x86\-64.
+.IP "\fBrelro\fR" 4
+.IX Item "relro"
+.PD 0
+.IP "\fBnorelro\fR" 4
+.IX Item "norelro"
+.PD
+Create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object.  This
+specifies a memory segment that should be made read-only after
+relocation, if supported.  Specifying \fBcommon-page-size\fR smaller
+than the system page size will render this protection ineffective.
+Don't create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment if \fBnorelro\fR.
+.IP "\fBreport-relative-reloc\fR" 4
+.IX Item "report-relative-reloc"
+Report dynamic relative relocations generated by linker.  Supported for
+Linux/i386 and Linux/x86_64.
+.IP "\fBseparate-code\fR" 4
+.IX Item "separate-code"
+.PD 0
+.IP "\fBnoseparate-code\fR" 4
+.IX Item "noseparate-code"
+.PD
+Create separate code \f(CW\*(C`PT_LOAD\*(C'\fR segment header in the object.  This
+specifies a memory segment that should contain only instructions and must
+be in wholly disjoint pages from any other data.  Don't create separate
+code \f(CW\*(C`PT_LOAD\*(C'\fR segment if \fBnoseparate-code\fR is used.
+.IP "\fBshstk\fR" 4
+.IX Item "shstk"
+Generate \s-1GNU_PROPERTY_X86_FEATURE_1_SHSTK\s0 in .note.gnu.property section
+to indicate compatibility with Intel Shadow Stack.  Supported for
+Linux/i386 and Linux/x86_64.
+.IP "\fBstack\-size=\fR\fIvalue\fR" 4
+.IX Item "stack-size=value"
+Specify a stack size for an \s-1ELF\s0 \f(CW\*(C`PT_GNU_STACK\*(C'\fR segment.
+Specifying zero will override any default non-zero sized
+\&\f(CW\*(C`PT_GNU_STACK\*(C'\fR segment creation.
+.IP "\fBstart-stop-gc\fR" 4
+.IX Item "start-stop-gc"
+.PD 0
+.IP "\fBnostart-stop-gc\fR" 4
+.IX Item "nostart-stop-gc"
+.PD
+When \fB\-\-gc\-sections\fR is in effect, a reference from a retained
+section to \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR causes all
+input sections named \f(CW\*(C`SECNAME\*(C'\fR to also be retained, if
+\&\f(CW\*(C`SECNAME\*(C'\fR is representable as a C identifier and either
+\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR is synthesized by the
+linker.  \fB\-z start-stop-gc\fR disables this effect, allowing
+sections to be garbage collected as if the special synthesized symbols
+were not defined.  \fB\-z start-stop-gc\fR has no effect on a
+definition of \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR in an
+object file or linker script.  Such a definition will prevent the
+linker providing a synthesized \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or
+\&\f(CW\*(C`_\|_stop_SECNAME\*(C'\fR respectively, and therefore the special
+treatment by garbage collection for those references.
+.IP "\fBstart\-stop\-visibility=\fR\fIvalue\fR" 4
+.IX Item "start-stop-visibility=value"
+Specify the \s-1ELF\s0 symbol visibility for synthesized
+\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR and \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR symbols.  \fIvalue\fR must be exactly \fBdefault\fR,
+\&\fBinternal\fR, \fBhidden\fR, or \fBprotected\fR.  If no \fB\-z
+start-stop-visibility\fR option is given, \fBprotected\fR is used for
+compatibility with historical practice.  However, it's highly
+recommended to use \fB\-z start\-stop\-visibility=hidden\fR in new
+programs and shared libraries so that these symbols are not exported
+between shared objects, which is not usually what's intended.
+.IP "\fBtext\fR" 4
+.IX Item "text"
+.PD 0
+.IP "\fBnotext\fR" 4
+.IX Item "notext"
+.IP "\fBtextoff\fR" 4
+.IX Item "textoff"
+.PD
+Report an error if \s-1DT_TEXTREL\s0 is set, i.e., if the position-independent
+or shared object has dynamic relocations in read-only sections.  Don't
+report an error if \fBnotext\fR or \fBtextoff\fR.
+.IP "\fBundefs\fR" 4
+.IX Item "undefs"
+Do not report unresolved symbol references from regular object files,
+either when creating an executable, or when creating a shared library.
+This option is the inverse of \fB\-z defs\fR.
+.IP "\fBunique-symbol\fR" 4
+.IX Item "unique-symbol"
+.PD 0
+.IP "\fBnounique-symbol\fR" 4
+.IX Item "nounique-symbol"
+.PD
+Avoid duplicated local symbol names in the symbol string table.  Append
+".\f(CW\*(C`number\*(C'\fR" to duplicated local symbol names if \fBunique-symbol\fR
+is used.  \fBnounique-symbol\fR is the default.
+.IP "\fBx86\-64\-baseline\fR" 4
+.IX Item "x86-64-baseline"
+.PD 0
+.IP "\fBx86\-64\-v2\fR" 4
+.IX Item "x86-64-v2"
+.IP "\fBx86\-64\-v3\fR" 4
+.IX Item "x86-64-v3"
+.IP "\fBx86\-64\-v4\fR" 4
+.IX Item "x86-64-v4"
+.PD
+Specify the x86\-64 \s-1ISA\s0 level needed in .note.gnu.property section.
+\&\fBx86\-64\-baseline\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_BASELINE\*(C'\fR.
+\&\fBx86\-64\-v2\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V2\*(C'\fR.
+\&\fBx86\-64\-v3\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V3\*(C'\fR.
+\&\fBx86\-64\-v4\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V4\*(C'\fR.
+Supported for Linux/i386 and Linux/x86_64.
+.RE
+.RS 4
+.Sp
+Other keywords are ignored for Solaris compatibility.
+.RE
+.IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4
+.IX Item "-( archives -)"
+.PD 0
+.IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4
+.IX Item "--start-group archives --end-group"
+.PD
+The \fIarchives\fR should be a list of archive files.  They may be
+either explicit file names, or \fB\-l\fR options.
+.Sp
+The specified archives are searched repeatedly until no new undefined
+references are created.  Normally, an archive is searched only once in
+the order that it is specified on the command line.  If a symbol in that
+archive is needed to resolve an undefined symbol referred to by an
+object in an archive that appears later on the command line, the linker
+would not be able to resolve that reference.  By grouping the archives,
+they will all be searched repeatedly until all possible references are
+resolved.
+.Sp
+Using this option has a significant performance cost.  It is best to use
+it only when there are unavoidable circular references between two or
+more archives.
+.IP "\fB\-\-accept\-unknown\-input\-arch\fR" 4
+.IX Item "--accept-unknown-input-arch"
+.PD 0
+.IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4
+.IX Item "--no-accept-unknown-input-arch"
+.PD
+Tells the linker to accept input files whose architecture cannot be
+recognised.  The assumption is that the user knows what they are doing
+and deliberately wants to link in these unknown input files.  This was
+the default behaviour of the linker, before release 2.14.  The default
+behaviour from release 2.14 onwards is to reject such input files, and
+so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to
+restore the old behaviour.
+.IP "\fB\-\-as\-needed\fR" 4
+.IX Item "--as-needed"
+.PD 0
+.IP "\fB\-\-no\-as\-needed\fR" 4
+.IX Item "--no-as-needed"
+.PD
+This option affects \s-1ELF DT_NEEDED\s0 tags for dynamic libraries mentioned
+on the command line after the \fB\-\-as\-needed\fR option.  Normally
+the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned
+on the command line, regardless of whether the library is actually
+needed or not.  \fB\-\-as\-needed\fR causes a \s-1DT_NEEDED\s0 tag to only be
+emitted for a library that \fIat that point in the link\fR satisfies a
+non-weak undefined symbol reference from a regular object file or, if
+the library is not found in the \s-1DT_NEEDED\s0 lists of other needed libraries, a
+non-weak undefined symbol reference from another needed dynamic library.
+Object files or libraries appearing on the command line \fIafter\fR
+the library in question do not affect whether the library is seen as
+needed.  This is similar to the rules for extraction of object files
+from archives.  \fB\-\-no\-as\-needed\fR restores the default behaviour.
+.Sp
+Note: On Linux based systems the \fB\-\-as\-needed\fR option also has
+an affect on the behaviour of the \fB\-\-rpath\fR and
+\&\fB\-\-rpath\-link\fR options.  See the description of
+\&\fB\-\-rpath\-link\fR for more details.
+.IP "\fB\-\-add\-needed\fR" 4
+.IX Item "--add-needed"
+.PD 0
+.IP "\fB\-\-no\-add\-needed\fR" 4
+.IX Item "--no-add-needed"
+.PD
+These two options have been deprecated because of the similarity of
+their names to the \fB\-\-as\-needed\fR and \fB\-\-no\-as\-needed\fR
+options.  They have been replaced by \fB\-\-copy\-dt\-needed\-entries\fR
+and \fB\-\-no\-copy\-dt\-needed\-entries\fR.
+.IP "\fB\-assert\fR \fIkeyword\fR" 4
+.IX Item "-assert keyword"
+This option is ignored for SunOS compatibility.
+.IP "\fB\-Bdynamic\fR" 4
+.IX Item "-Bdynamic"
+.PD 0
+.IP "\fB\-dy\fR" 4
+.IX Item "-dy"
+.IP "\fB\-call_shared\fR" 4
+.IX Item "-call_shared"
+.PD
+Link against dynamic libraries.  This is only meaningful on platforms
+for which shared libraries are supported.  This option is normally the
+default on such platforms.  The different variants of this option are
+for compatibility with various systems.  You may use this option
+multiple times on the command line: it affects library searching for
+\&\fB\-l\fR options which follow it.
+.IP "\fB\-Bgroup\fR" 4
+.IX Item "-Bgroup"
+Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic
+section.  This causes the runtime linker to handle lookups in this
+object and its dependencies to be performed only inside the group.
+\&\fB\-\-unresolved\-symbols=report\-all\fR is implied.  This option is
+only meaningful on \s-1ELF\s0 platforms which support shared libraries.
+.IP "\fB\-Bstatic\fR" 4
+.IX Item "-Bstatic"
+.PD 0
+.IP "\fB\-dn\fR" 4
+.IX Item "-dn"
+.IP "\fB\-non_shared\fR" 4
+.IX Item "-non_shared"
+.IP "\fB\-static\fR" 4
+.IX Item "-static"
+.PD
+Do not link against shared libraries.  This is only meaningful on
+platforms for which shared libraries are supported.  The different
+variants of this option are for compatibility with various systems.  You
+may use this option multiple times on the command line: it affects
+library searching for \fB\-l\fR options which follow it.  This
+option also implies \fB\-\-unresolved\-symbols=report\-all\fR.  This
+option can be used with \fB\-shared\fR.  Doing so means that a
+shared library is being created but that all of the library's external
+references must be resolved by pulling in entries from static
+libraries.
+.IP "\fB\-Bsymbolic\fR" 4
+.IX Item "-Bsymbolic"
+When creating a shared library, bind references to global symbols to the
+definition within the shared library, if any.  Normally, it is possible
+for a program linked against a shared library to override the definition
+within the shared library.  This option is only meaningful on \s-1ELF\s0
+platforms which support shared libraries.
+.IP "\fB\-Bsymbolic\-functions\fR" 4
+.IX Item "-Bsymbolic-functions"
+When creating a shared library, bind references to global function
+symbols to the definition within the shared library, if any.
+This option is only meaningful on \s-1ELF\s0 platforms which support shared
+libraries.
+.IP "\fB\-Bno\-symbolic\fR" 4
+.IX Item "-Bno-symbolic"
+This option can cancel previously specified \fB\-Bsymbolic\fR and
+\&\fB\-Bsymbolic\-functions\fR.
+.IP "\fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR" 4
+.IX Item "--dynamic-list=dynamic-list-file"
+Specify the name of a dynamic list file to the linker.  This is
+typically used when creating shared libraries to specify a list of
+global symbols whose references shouldn't be bound to the definition
+within the shared library, or creating dynamically linked executables
+to specify a list of symbols which should be added to the symbol table
+in the executable.  This option is only meaningful on \s-1ELF\s0 platforms
+which support shared libraries.
+.Sp
+The format of the dynamic list is the same as the version node without
+scope and node name.  See \fB\s-1VERSION\s0\fR for more information.
+.IP "\fB\-\-dynamic\-list\-data\fR" 4
+.IX Item "--dynamic-list-data"
+Include all global data symbols to the dynamic list.
+.IP "\fB\-\-dynamic\-list\-cpp\-new\fR" 4
+.IX Item "--dynamic-list-cpp-new"
+Provide the builtin dynamic list for \*(C+ operator new and delete.  It
+is mainly useful for building shared libstdc++.
+.IP "\fB\-\-dynamic\-list\-cpp\-typeinfo\fR" 4
+.IX Item "--dynamic-list-cpp-typeinfo"
+Provide the builtin dynamic list for \*(C+ runtime type identification.
+.IP "\fB\-\-check\-sections\fR" 4
+.IX Item "--check-sections"
+.PD 0
+.IP "\fB\-\-no\-check\-sections\fR" 4
+.IX Item "--no-check-sections"
+.PD
+Asks the linker \fInot\fR to check section addresses after they have
+been assigned to see if there are any overlaps.  Normally the linker will
+perform this check, and if it finds any overlaps it will produce
+suitable error messages.  The linker does know about, and does make
+allowances for sections in overlays.  The default behaviour can be
+restored by using the command-line switch \fB\-\-check\-sections\fR.
+Section overlap is not usually checked for relocatable links.  You can
+force checking in that case by using the \fB\-\-check\-sections\fR
+option.
+.IP "\fB\-\-copy\-dt\-needed\-entries\fR" 4
+.IX Item "--copy-dt-needed-entries"
+.PD 0
+.IP "\fB\-\-no\-copy\-dt\-needed\-entries\fR" 4
+.IX Item "--no-copy-dt-needed-entries"
+.PD
+This option affects the treatment of dynamic libraries referred to
+by \s-1DT_NEEDED\s0 tags \fIinside\fR \s-1ELF\s0 dynamic libraries mentioned on the
+command line.  Normally the linker won't add a \s-1DT_NEEDED\s0 tag to the
+output binary for each library mentioned in a \s-1DT_NEEDED\s0 tag in an
+input dynamic library.  With \fB\-\-copy\-dt\-needed\-entries\fR
+specified on the command line however any dynamic libraries that
+follow it will have their \s-1DT_NEEDED\s0 entries added.  The default
+behaviour can be restored with \fB\-\-no\-copy\-dt\-needed\-entries\fR.
+.Sp
+This option also has an effect on the resolution of symbols in dynamic
+libraries.  With \fB\-\-copy\-dt\-needed\-entries\fR dynamic libraries
+mentioned on the command line will be recursively searched, following
+their \s-1DT_NEEDED\s0 tags to other libraries, in order to resolve symbols
+required by the output binary.  With the default setting however
+the searching of dynamic libraries that follow it will stop with the
+dynamic library itself.  No \s-1DT_NEEDED\s0 links will be traversed to resolve
+symbols.
+.IP "\fB\-\-cref\fR" 4
+.IX Item "--cref"
+Output a cross reference table.  If a linker map file is being
+generated, the cross reference table is printed to the map file.
+Otherwise, it is printed on the standard output.
+.Sp
+The format of the table is intentionally simple, so that it may be
+easily processed by a script if necessary.  The symbols are printed out,
+sorted by name.  For each symbol, a list of file names is given.  If the
+symbol is defined, the first file listed is the location of the
+definition.  If the symbol is defined as a common value then any files
+where this happens appear next.  Finally any files that reference the
+symbol are listed.
+.IP "\fB\-\-ctf\-variables\fR" 4
+.IX Item "--ctf-variables"
+.PD 0
+.IP "\fB\-\-no\-ctf\-variables\fR" 4
+.IX Item "--no-ctf-variables"
+.PD
+The \s-1CTF\s0 debuginfo format supports a section which encodes the names and
+types of variables found in the program which do not appear in any symbol
+table. These variables clearly cannot be looked up by address by
+conventional debuggers, so the space used for their types and names is
+usually wasted: the types are usually small but the names are often not.
+\&\fB\-\-ctf\-variables\fR causes the generation of such a section.
+The default behaviour can be restored with \fB\-\-no\-ctf\-variables\fR.
+.IP "\fB\-\-ctf\-share\-types=\fR\fImethod\fR" 4
+.IX Item "--ctf-share-types=method"
+Adjust the method used to share types between translation units in \s-1CTF.\s0
+.RS 4
+.IP "\fBshare-unconflicted\fR" 4
+.IX Item "share-unconflicted"
+Put all types that do not have ambiguous definitions into the shared dictionary,
+where debuggers can easily access them, even if they only occur in one
+translation unit.  This is the default.
+.IP "\fBshare-duplicated\fR" 4
+.IX Item "share-duplicated"
+Put only types that occur in multiple translation units into the shared
+dictionary: types with only one definition go into per-translation-unit
+dictionaries.  Types with ambiguous definitions in multiple translation units
+always go into per-translation-unit dictionaries.  This tends to make the \s-1CTF\s0
+larger, but may reduce the amount of \s-1CTF\s0 in the shared dictionary.  For very
+large projects this may speed up opening the \s-1CTF\s0 and save memory in the \s-1CTF\s0
+consumer at runtime.
+.RE
+.RS 4
+.RE
+.IP "\fB\-\-no\-define\-common\fR" 4
+.IX Item "--no-define-common"
+This option inhibits the assignment of addresses to common symbols.
+The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect.
+.Sp
+The \fB\-\-no\-define\-common\fR option allows decoupling
+the decision to assign addresses to Common symbols from the choice
+of the output file type; otherwise a non-Relocatable output type
+forces assigning addresses to Common symbols.
+Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced
+from a shared library to be assigned addresses only in the main program.
+This eliminates the unused duplicate space in the shared library,
+and also prevents any possible confusion over resolving to the wrong
+duplicate when there are many dynamic modules with specialized search
+paths for runtime symbol resolution.
+.IP "\fB\-\-force\-group\-allocation\fR" 4
+.IX Item "--force-group-allocation"
+This option causes the linker to place section group members like
+normal input sections, and to delete the section groups.  This is the
+default behaviour for a final link but this option can be used to
+change the behaviour of a relocatable link (\fB\-r\fR).  The script
+command \f(CW\*(C`FORCE_GROUP_ALLOCATION\*(C'\fR has the same
+effect.
+.IP "\fB\-\-defsym=\fR\fIsymbol\fR\fB=\fR\fIexpression\fR" 4
+.IX Item "--defsym=symbol=expression"
+Create a global symbol in the output file, containing the absolute
+address given by \fIexpression\fR.  You may use this option as many
+times as necessary to define multiple symbols in the command line.  A
+limited form of arithmetic is supported for the \fIexpression\fR in this
+context: you may give a hexadecimal constant or the name of an existing
+symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal
+constants or symbols.  If you need more elaborate expressions, consider
+using the linker command language from a script.
+\&\fINote:\fR there should be no white space between \fIsymbol\fR, the
+equals sign ("\fB=\fR"), and \fIexpression\fR.
+.Sp
+The linker processes \fB\-\-defsym\fR arguments and \fB\-T\fR arguments
+in order, placing \fB\-\-defsym\fR before \fB\-T\fR will define the
+symbol before the linker script from \fB\-T\fR is processed, while
+placing \fB\-\-defsym\fR after \fB\-T\fR will define the symbol after
+the linker script has been processed.  This difference has
+consequences for expressions within the linker script that use the
+\&\fB\-\-defsym\fR symbols, which order is correct will depend on what
+you are trying to achieve.
+.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
+.IX Item "--demangle[=style]"
+.PD 0
+.IP "\fB\-\-no\-demangle\fR" 4
+.IX Item "--no-demangle"
+.PD
+These options control whether to demangle symbol names in error messages
+and other output.  When the linker is told to demangle, it tries to
+present symbol names in a readable fashion: it strips leading
+underscores if they are used by the object file format, and converts \*(C+
+mangled symbol names into user readable names.  Different compilers have
+different mangling styles.  The optional demangling style argument can be used
+to choose an appropriate demangling style for your compiler.  The linker will
+demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR
+is set.  These options may be used to override the default.
+.IP "\fB\-I\fR\fIfile\fR" 4
+.IX Item "-Ifile"
+.PD 0
+.IP "\fB\-\-dynamic\-linker=\fR\fIfile\fR" 4
+.IX Item "--dynamic-linker=file"
+.PD
+Set the name of the dynamic linker.  This is only meaningful when
+generating dynamically linked \s-1ELF\s0 executables.  The default dynamic
+linker is normally correct; don't use this unless you know what you are
+doing.
+.IP "\fB\-\-no\-dynamic\-linker\fR" 4
+.IX Item "--no-dynamic-linker"
+When producing an executable file, omit the request for a dynamic
+linker to be used at load-time.  This is only meaningful for \s-1ELF\s0
+executables that contain dynamic relocations, and usually requires
+entry point code that is capable of processing these relocations.
+.IP "\fB\-\-embedded\-relocs\fR" 4
+.IX Item "--embedded-relocs"
+This option is similar to the \fB\-\-emit\-relocs\fR option except
+that the relocs are stored in a target-specific section.  This option
+is only supported by the \fB\s-1BFIN\s0\fR, \fB\s-1CR16\s0\fR and \fIM68K\fR
+targets.
+.IP "\fB\-\-disable\-multiple\-abs\-defs\fR" 4
+.IX Item "--disable-multiple-abs-defs"
+Do not allow multiple definitions with symbols included
+in filename invoked by \-R or \-\-just\-symbols
+.IP "\fB\-\-fatal\-warnings\fR" 4
+.IX Item "--fatal-warnings"
+.PD 0
+.IP "\fB\-\-no\-fatal\-warnings\fR" 4
+.IX Item "--no-fatal-warnings"
+.PD
+Treat all warnings as errors.  The default behaviour can be restored
+with the option \fB\-\-no\-fatal\-warnings\fR.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+.PD 0
+.IP "\fB\-\-no\-warnings\fR" 4
+.IX Item "--no-warnings"
+.PD
+Do not display any warning or error messages.  This overrides
+\&\fB\-\-fatal\-warnings\fR if it has been enabled.  This option can be
+used when it is known that the output binary will not work, but there
+is still a need to create it.
+.IP "\fB\-\-force\-exe\-suffix\fR" 4
+.IX Item "--force-exe-suffix"
+Make sure that an output file has a .exe suffix.
+.Sp
+If a successfully built fully linked output file does not have a
+\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy
+the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This
+option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless
+it ends in a \f(CW\*(C`.exe\*(C'\fR suffix.
+.IP "\fB\-\-gc\-sections\fR" 4
+.IX Item "--gc-sections"
+.PD 0
+.IP "\fB\-\-no\-gc\-sections\fR" 4
+.IX Item "--no-gc-sections"
+.PD
+Enable garbage collection of unused input sections.  It is ignored on
+targets that do not support this option.  The default behaviour (of not
+performing this garbage collection) can be restored by specifying
+\&\fB\-\-no\-gc\-sections\fR on the command line.  Note that garbage
+collection for \s-1COFF\s0 and \s-1PE\s0 format targets is supported, but the
+implementation is currently considered to be experimental.
+.Sp
+\&\fB\-\-gc\-sections\fR decides which input sections are used by
+examining symbols and relocations.  The section containing the entry
+symbol and all sections containing symbols undefined on the
+command-line will be kept, as will sections containing symbols
+referenced by dynamic objects.  Note that when building shared
+libraries, the linker must assume that any visible symbol is
+referenced.  Once this initial set of sections has been determined,
+the linker recursively marks as used any section referenced by their
+relocations.  See \fB\-\-entry\fR, \fB\-\-undefined\fR, and
+\&\fB\-\-gc\-keep\-exported\fR.
+.Sp
+This option can be set when doing a partial link (enabled with option
+\&\fB\-r\fR).  In this case the root of symbols kept must be explicitly
+specified either by one of the options \fB\-\-entry\fR,
+\&\fB\-\-undefined\fR, or \fB\-\-gc\-keep\-exported\fR or by a \f(CW\*(C`ENTRY\*(C'\fR
+command in the linker script.
+.Sp
+As a \s-1GNU\s0 extension, \s-1ELF\s0 input sections marked with the
+\&\f(CW\*(C`SHF_GNU_RETAIN\*(C'\fR flag will not be garbage collected.
+.IP "\fB\-\-print\-gc\-sections\fR" 4
+.IX Item "--print-gc-sections"
+.PD 0
+.IP "\fB\-\-no\-print\-gc\-sections\fR" 4
+.IX Item "--no-print-gc-sections"
+.PD
+List all sections removed by garbage collection.  The listing is
+printed on stderr.  This option is only effective if garbage
+collection has been enabled via the \fB\-\-gc\-sections\fR) option.  The
+default behaviour (of not listing the sections that are removed) can
+be restored by specifying \fB\-\-no\-print\-gc\-sections\fR on the command
+line.
+.IP "\fB\-\-gc\-keep\-exported\fR" 4
+.IX Item "--gc-keep-exported"
+When \fB\-\-gc\-sections\fR is enabled, this option prevents garbage
+collection of unused input sections that contain global symbols having
+default or protected visibility.  This option is intended to be used for
+executables where unreferenced sections would otherwise be garbage
+collected regardless of the external visibility of contained symbols.
+Note that this option has no effect when linking shared objects since
+it is already the default behaviour.  This option is only supported for
+\&\s-1ELF\s0 format targets.
+.IP "\fB\-\-print\-output\-format\fR" 4
+.IX Item "--print-output-format"
+Print the name of the default output format (perhaps influenced by
+other command-line options).  This is the string that would appear
+in an \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR linker script command.
+.IP "\fB\-\-print\-memory\-usage\fR" 4
+.IX Item "--print-memory-usage"
+Print used size, total size and used size of memory regions created with
+the \fB\s-1MEMORY\s0\fR command.  This is useful on embedded targets to have a
+quick view of amount of free memory.  The format of the output has one
+headline and one line per region.  It is both human readable and easily
+parsable by tools.  Here is an example of an output:
+.Sp
+.Vb 3
+\&        Memory region         Used Size  Region Size  %age Used
+\&                     ROM:        256 KB         1 MB     25.00%
+\&                     RAM:          32 B         2 GB      0.00%
+.Ve
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Print a summary of the command-line options on the standard output and exit.
+.IP "\fB\-\-target\-help\fR" 4
+.IX Item "--target-help"
+Print a summary of all target-specific options on the standard output and exit.
+.IP "\fB\-Map=\fR\fImapfile\fR" 4
+.IX Item "-Map=mapfile"
+Print a link map to the file \fImapfile\fR.  See the description of the
+\&\fB\-M\fR option, above.  If \fImapfile\fR is just the character
+\&\f(CW\*(C`\-\*(C'\fR then the map will be written to stdout.
+.Sp
+Specifying a directory as \fImapfile\fR causes the linker map to be
+written as a file inside the directory.  Normally name of the file
+inside the directory is computed as the basename of the \fIoutput\fR
+file with \f(CW\*(C`.map\*(C'\fR appended.   If however the special character
+\&\f(CW\*(C`%\*(C'\fR is used then this will be replaced by the full path of the
+output file.  Additionally if there are any characters after the
+\&\fI%\fR symbol then \f(CW\*(C`.map\*(C'\fR will no longer be appended.
+.Sp
+.Vb 10
+\&         \-o foo.exe \-Map=bar                  [Creates ./bar]
+\&         \-o ../dir/foo.exe \-Map=bar           [Creates ./bar]
+\&         \-o foo.exe \-Map=../dir               [Creates ../dir/foo.exe.map]
+\&         \-o ../dir2/foo.exe \-Map=../dir       [Creates ../dir/foo.exe.map]
+\&         \-o foo.exe \-Map=%                    [Creates ./foo.exe.map]
+\&         \-o ../dir/foo.exe \-Map=%             [Creates ../dir/foo.exe.map]
+\&         \-o foo.exe \-Map=%.bar                [Creates ./foo.exe.bar]
+\&         \-o ../dir/foo.exe \-Map=%.bar         [Creates ../dir/foo.exe.bar]
+\&         \-o ../dir2/foo.exe \-Map=../dir/%     [Creates ../dir/../dir2/foo.exe.map]
+\&         \-o ../dir2/foo.exe \-Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar]
+.Ve
+.Sp
+It is an error to specify more than one \f(CW\*(C`%\*(C'\fR character.
+.Sp
+If the map file already exists then it will be overwritten by this
+operation.
+.IP "\fB\-\-no\-keep\-memory\fR" 4
+.IX Item "--no-keep-memory"
+\&\fBld\fR normally optimizes for speed over memory usage by caching the
+symbol tables of input files in memory.  This option tells \fBld\fR to
+instead optimize for memory usage, by rereading the symbol tables as
+necessary.  This may be required if \fBld\fR runs out of memory space
+while linking a large executable.
+.IP "\fB\-\-no\-undefined\fR" 4
+.IX Item "--no-undefined"
+.PD 0
+.IP "\fB\-z defs\fR" 4
+.IX Item "-z defs"
+.PD
+Report unresolved symbol references from regular object files.  This
+is done even if the linker is creating a non-symbolic shared library.
+The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the
+behaviour for reporting unresolved references found in shared
+libraries being linked in.
+.Sp
+The effects of this option can be reverted by using \f(CW\*(C`\-z undefs\*(C'\fR.
+.IP "\fB\-\-allow\-multiple\-definition\fR" 4
+.IX Item "--allow-multiple-definition"
+.PD 0
+.IP "\fB\-z muldefs\fR" 4
+.IX Item "-z muldefs"
+.PD
+Normally when a symbol is defined multiple times, the linker will
+report a fatal error. These options allow multiple definitions and the
+first definition will be used.
+.IP "\fB\-\-allow\-shlib\-undefined\fR" 4
+.IX Item "--allow-shlib-undefined"
+.PD 0
+.IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4
+.IX Item "--no-allow-shlib-undefined"
+.PD
+Allows or disallows undefined symbols in shared libraries.
+This switch is similar to \fB\-\-no\-undefined\fR except that it
+determines the behaviour when the undefined symbols are in a
+shared library rather than a regular object file.  It does not affect
+how undefined symbols in regular object files are handled.
+.Sp
+The default behaviour is to report errors for any undefined symbols
+referenced in shared libraries if the linker is being used to create
+an executable, but to allow them if the linker is being used to create
+a shared library.
+.Sp
+The reasons for allowing undefined symbol references in shared
+libraries specified at link time are that:
+.RS 4
+.IP "\(bu" 4
+A shared library specified at link time may not be the same as the one
+that is available at load time, so the symbol might actually be
+resolvable at load time.
+.IP "\(bu" 4
+There are some operating systems, eg BeOS and \s-1HPPA,\s0 where undefined
+symbols in shared libraries are normal.
+.Sp
+The BeOS kernel for example patches shared libraries at load time to
+select whichever function is most appropriate for the current
+architecture.  This is used, for example, to dynamically select an
+appropriate memset function.
+.RE
+.RS 4
+.RE
+.IP "\fB\-\-error\-handling\-script=\fR\fIscriptname\fR" 4
+.IX Item "--error-handling-script=scriptname"
+If this option is provided then the linker will invoke
+\&\fIscriptname\fR whenever an error is encountered.  Currently however
+only two kinds of error are supported: missing symbols and missing
+libraries.  Two arguments will be passed to script: the keyword
+\&\*(L"undefined-symbol\*(R" or `missing\-lib" and the \fIname\fR of the
+undefined symbol or missing library.  The intention is that the script
+will provide suggestions to the user as to where the symbol or library
+might be found.  After the script has finished then the normal linker
+error message will be displayed.
+.Sp
+The availability of this option is controlled by a configure time
+switch, so it may not be present in specific implementations.
+.IP "\fB\-\-no\-undefined\-version\fR" 4
+.IX Item "--no-undefined-version"
+Normally when a symbol has an undefined version, the linker will ignore
+it. This option disallows symbols with undefined version and a fatal error
+will be issued instead.
+.IP "\fB\-\-default\-symver\fR" 4
+.IX Item "--default-symver"
+Create and use a default symbol version (the soname) for unversioned
+exported symbols.
+.IP "\fB\-\-default\-imported\-symver\fR" 4
+.IX Item "--default-imported-symver"
+Create and use a default symbol version (the soname) for unversioned
+imported symbols.
+.IP "\fB\-\-no\-warn\-mismatch\fR" 4
+.IX Item "--no-warn-mismatch"
+Normally \fBld\fR will give an error if you try to link together input
+files that are mismatched for some reason, perhaps because they have
+been compiled for different processors or for different endiannesses.
+This option tells \fBld\fR that it should silently permit such possible
+errors.  This option should only be used with care, in cases when you
+have taken some special action that ensures that the linker errors are
+inappropriate.
+.IP "\fB\-\-no\-warn\-search\-mismatch\fR" 4
+.IX Item "--no-warn-search-mismatch"
+Normally \fBld\fR will give a warning if it finds an incompatible
+library during a library search.  This option silences the warning.
+.IP "\fB\-\-no\-whole\-archive\fR" 4
+.IX Item "--no-whole-archive"
+Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent
+archive files.
+.IP "\fB\-\-noinhibit\-exec\fR" 4
+.IX Item "--noinhibit-exec"
+Retain the executable output file whenever it is still usable.
+Normally, the linker will not produce an output file if it encounters
+errors during the link process; it exits without writing an output file
+when it issues any error whatsoever.
+.IP "\fB\-nostdlib\fR" 4
+.IX Item "-nostdlib"
+Only search library directories explicitly specified on the
+command line.  Library directories specified in linker scripts
+(including linker scripts specified on the command line) are ignored.
+.IP "\fB\-\-oformat=\fR\fIoutput-format\fR" 4
+.IX Item "--oformat=output-format"
+\&\fBld\fR may be configured to support more than one kind of object
+file.  If your \fBld\fR is configured this way, you can use the
+\&\fB\-\-oformat\fR option to specify the binary format for the output
+object file.  Even when \fBld\fR is configured to support alternative
+object formats, you don't usually need to specify this, as \fBld\fR
+should be configured to produce as a default output format the most
+usual format on each machine.  \fIoutput-format\fR is a text string, the
+name of a particular format supported by the \s-1BFD\s0 libraries.  (You can
+list the available binary formats with \fBobjdump \-i\fR.)  The script
+command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but
+this option overrides it.
+.IP "\fB\-\-out\-implib\fR \fIfile\fR" 4
+.IX Item "--out-implib file"
+Create an import library in \fIfile\fR corresponding to the executable
+the linker is generating (eg. a \s-1DLL\s0 or \s-1ELF\s0 program).  This import
+library (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR for DLLs)
+may be used to link clients against the generated executable; this
+behaviour makes it possible to skip a separate import library creation
+step (eg. \f(CW\*(C`dlltool\*(C'\fR for DLLs).  This option is only available for
+the i386 \s-1PE\s0 and \s-1ELF\s0 targetted ports of the linker.
+.IP "\fB\-pie\fR" 4
+.IX Item "-pie"
+.PD 0
+.IP "\fB\-\-pic\-executable\fR" 4
+.IX Item "--pic-executable"
+.PD
+Create a position independent executable.  This is currently only supported on
+\&\s-1ELF\s0 platforms.  Position independent executables are similar to shared
+libraries in that they are relocated by the dynamic linker to the virtual
+address the \s-1OS\s0 chooses for them (which can vary between invocations).  Like
+normal dynamically linked executables they can be executed and symbols
+defined in the executable cannot be overridden by shared libraries.
+.IP "\fB\-no\-pie\fR" 4
+.IX Item "-no-pie"
+Create a position dependent executable.  This is the default.
+.IP "\fB\-qmagic\fR" 4
+.IX Item "-qmagic"
+This option is ignored for Linux compatibility.
+.IP "\fB\-Qy\fR" 4
+.IX Item "-Qy"
+This option is ignored for \s-1SVR4\s0 compatibility.
+.IP "\fB\-\-relax\fR" 4
+.IX Item "--relax"
+.PD 0
+.IP "\fB\-\-no\-relax\fR" 4
+.IX Item "--no-relax"
+.PD
+An option with machine dependent effects.
+This option is only supported on a few targets.
+.Sp
+On some platforms the \fB\-\-relax\fR option performs target specific,
+global optimizations that become possible when the linker resolves
+addressing in the program, such as relaxing address modes,
+synthesizing new instructions, selecting shorter version of current
+instructions, and combining constant values.
+.Sp
+On some platforms these link time global optimizations may make symbolic
+debugging of the resulting executable impossible.
+This is known to be the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0
+family of processors.
+.Sp
+On platforms where the feature is supported, the option
+\&\fB\-\-no\-relax\fR will disable it.
+.Sp
+On platforms where the feature is not supported, both \fB\-\-relax\fR
+and \fB\-\-no\-relax\fR are accepted, but ignored.
+.IP "\fB\-\-retain\-symbols\-file=\fR\fIfilename\fR" 4
+.IX Item "--retain-symbols-file=filename"
+Retain \fIonly\fR the symbols listed in the file \fIfilename\fR,
+discarding all others.  \fIfilename\fR is simply a flat file, with one
+symbol name per line.  This option is especially useful in environments
+(such as VxWorks)
+where a large global symbol table is accumulated gradually, to conserve
+run-time memory.
+.Sp
+\&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols,
+or symbols needed for relocations.
+.Sp
+You may only specify \fB\-\-retain\-symbols\-file\fR once in the command
+line.  It overrides \fB\-s\fR and \fB\-S\fR.
+.IP "\fB\-rpath=\fR\fIdir\fR" 4
+.IX Item "-rpath=dir"
+Add a directory to the runtime library search path.  This is used when
+linking an \s-1ELF\s0 executable with shared objects.  All \fB\-rpath\fR
+arguments are concatenated and passed to the runtime linker, which uses
+them to locate shared objects at runtime.
+.Sp
+The \fB\-rpath\fR option is also used when locating shared objects which
+are needed by shared objects explicitly included in the link; see the
+description of the \fB\-rpath\-link\fR option.  Searching \fB\-rpath\fR
+in this way is only supported by native linkers and cross linkers which
+have been configured with the \fB\-\-with\-sysroot\fR option.
+.Sp
+If \fB\-rpath\fR is not used when linking an \s-1ELF\s0 executable, the
+contents of the environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it
+is defined.
+.Sp
+The \fB\-rpath\fR option may also be used on SunOS.  By default, on
+SunOS, the linker will form a runtime search path out of all the
+\&\fB\-L\fR options it is given.  If a \fB\-rpath\fR option is used, the
+runtime search path will be formed exclusively using the \fB\-rpath\fR
+options, ignoring the \fB\-L\fR options.  This can be useful when using
+gcc, which adds many \fB\-L\fR options which may be on \s-1NFS\s0 mounted
+file systems.
+.Sp
+For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
+followed by a directory name, rather than a file name, it is treated as
+the \fB\-rpath\fR option.
+.IP "\fB\-rpath\-link=\fR\fIdir\fR" 4
+.IX Item "-rpath-link=dir"
+When using \s-1ELF\s0 or SunOS, one shared library may require another.  This
+happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one
+of the input files.
+.Sp
+When the linker encounters such a dependency when doing a non-shared,
+non-relocatable link, it will automatically try to locate the required
+shared library and include it in the link, if it is not included
+explicitly.  In such a case, the \fB\-rpath\-link\fR option
+specifies the first set of directories to search.  The
+\&\fB\-rpath\-link\fR option may specify a sequence of directory names
+either by specifying a list of names separated by colons, or by
+appearing multiple times.
+.Sp
+The tokens \fI\f(CI$ORIGIN\fI\fR and \fI\f(CI$LIB\fI\fR can appear in these search
+directories.  They will be replaced by the full path to the directory
+containing the program or shared object in the case of \fI\f(CI$ORIGIN\fI\fR
+and either \fBlib\fR \- for 32\-bit binaries \- or \fBlib64\fR \- for
+64\-bit binaries \- in the case of \fI\f(CI$LIB\fI\fR.
+.Sp
+The alternative form of these tokens \- \fI${\s-1ORIGIN\s0}\fR and
+\&\fI${\s-1LIB\s0}\fR can also be used.  The token \fI\f(CI$PLATFORM\fI\fR is not
+supported.
+.Sp
+This option should be used with caution as it overrides the search path
+that may have been hard compiled into a shared library. In such a case it
+is possible to use unintentionally a different search path than the
+runtime linker would do.
+.Sp
+The linker uses the following search paths to locate required shared
+libraries:
+.RS 4
+.IP "1." 4
+Any directories specified by \fB\-rpath\-link\fR options.
+.IP "2." 4
+Any directories specified by \fB\-rpath\fR options.  The difference
+between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories
+specified by \fB\-rpath\fR options are included in the executable and
+used at runtime, whereas the \fB\-rpath\-link\fR option is only effective
+at link time. Searching \fB\-rpath\fR in this way is only supported
+by native linkers and cross linkers which have been configured with
+the \fB\-\-with\-sysroot\fR option.
+.IP "3." 4
+On an \s-1ELF\s0 system, for native linkers, if the \fB\-rpath\fR and
+\&\fB\-rpath\-link\fR options were not used, search the contents of the
+environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR.
+.IP "4." 4
+On SunOS, if the \fB\-rpath\fR option was not used, search any
+directories specified using \fB\-L\fR options.
+.IP "5." 4
+For a native linker, search the contents of the environment
+variable \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR.
+.IP "6." 4
+For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or
+\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared
+libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if
+\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist.
+.IP "7." 4
+For a linker for a Linux system, if the file \fI/etc/ld.so.conf\fR
+exists, the list of directories found in that file.  Note: the path
+to this file is prefixed with the \f(CW\*(C`sysroot\*(C'\fR value, if that is
+defined, and then any \f(CW\*(C`prefix\*(C'\fR string if the linker was
+configured with the \fB\-\-prefix=<path>\fR option.
+.IP "8." 4
+For a native linker on a FreeBSD system, any directories specified by
+the \f(CW\*(C`_PATH_ELF_HINTS\*(C'\fR macro defined in the \fIelf\-hints.h\fR
+header file.
+.IP "9." 4
+Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a
+linker script given on the command line, including scripts specified
+by \fB\-T\fR (but not \fB\-dT\fR).
+.IP "10." 4
+The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
+.IP "11." 4
+Any directories specified by a plugin \s-1LDPT_SET_EXTRA_LIBRARY_PATH.\s0
+.IP "12." 4
+Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a default
+linker script.
+.RE
+.RS 4
+.Sp
+Note however on Linux based systems there is an additional caveat:  If
+the \fB\-\-as\-needed\fR option is active \fIand\fR a shared library
+is located which would normally satisfy the search \fIand\fR this
+library does not have \s-1DT_NEEDED\s0 tag for \fIlibc.so\fR
+\&\fIand\fR there is a shared library later on in the set of search
+directories which also satisfies the search \fIand\fR
+this second shared library does have a \s-1DT_NEEDED\s0 tag for
+\&\fIlibc.so\fR \fIthen\fR the second library will be selected instead
+of the first.
+.Sp
+If the required shared library is not found, the linker will issue a
+warning and continue with the link.
+.RE
+.IP "\fB\-shared\fR" 4
+.IX Item "-shared"
+.PD 0
+.IP "\fB\-Bshareable\fR" 4
+.IX Item "-Bshareable"
+.PD
+Create a shared library.  This is currently only supported on \s-1ELF, XCOFF\s0
+and SunOS platforms.  On SunOS, the linker will automatically create a
+shared library if the \fB\-e\fR option is not used and there are
+undefined symbols in the link.
+.IP "\fB\-\-sort\-common\fR" 4
+.IX Item "--sort-common"
+.PD 0
+.IP "\fB\-\-sort\-common=ascending\fR" 4
+.IX Item "--sort-common=ascending"
+.IP "\fB\-\-sort\-common=descending\fR" 4
+.IX Item "--sort-common=descending"
+.PD
+This option tells \fBld\fR to sort the common symbols by alignment in
+ascending or descending order when it places them in the appropriate output
+sections.  The symbol alignments considered are sixteen-byte or larger,
+eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
+between symbols due to alignment constraints.  If no sorting order is
+specified, then descending order is assumed.
+.IP "\fB\-\-sort\-section=name\fR" 4
+.IX Item "--sort-section=name"
+This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section
+patterns in the linker script.
+.IP "\fB\-\-sort\-section=alignment\fR" 4
+.IX Item "--sort-section=alignment"
+This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section
+patterns in the linker script.
+.IP "\fB\-\-spare\-dynamic\-tags=\fR\fIcount\fR" 4
+.IX Item "--spare-dynamic-tags=count"
+This option specifies the number of empty slots to leave in the
+\&.dynamic section of \s-1ELF\s0 shared objects.  Empty slots may be needed by
+post processing tools, such as the prelinker.  The default is 5.
+.IP "\fB\-\-split\-by\-file[=\fR\fIsize\fR\fB]\fR" 4
+.IX Item "--split-by-file[=size]"
+Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for
+each input file when \fIsize\fR is reached.  \fIsize\fR defaults to a
+size of 1 if not given.
+.IP "\fB\-\-split\-by\-reloc[=\fR\fIcount\fR\fB]\fR" 4
+.IX Item "--split-by-reloc[=count]"
+Tries to creates extra sections in the output file so that no single
+output section in the file contains more than \fIcount\fR relocations.
+This is useful when generating huge relocatable files for downloading into
+certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0
+cannot represent more than 65535 relocations in a single section.  Note
+that this will fail to work with object file formats which do not
+support arbitrary sections.  The linker will not split up individual
+input sections for redistribution, so if a single input section contains
+more than \fIcount\fR relocations one output section will contain that
+many relocations.  \fIcount\fR defaults to a value of 32768.
+.IP "\fB\-\-stats\fR" 4
+.IX Item "--stats"
+Compute and display statistics about the operation of the linker, such
+as execution time and memory usage.
+.IP "\fB\-\-sysroot=\fR\fIdirectory\fR" 4
+.IX Item "--sysroot=directory"
+Use \fIdirectory\fR as the location of the sysroot, overriding the
+configure-time default.  This option is only supported by linkers
+that were configured using \fB\-\-with\-sysroot\fR.
+.IP "\fB\-\-task\-link\fR" 4
+.IX Item "--task-link"
+This is used by \s-1COFF/PE\s0 based targets to create a task-linked object
+file where all of the global symbols have been converted to statics.
+.IP "\fB\-\-traditional\-format\fR" 4
+.IX Item "--traditional-format"
+For some targets, the output of \fBld\fR is different in some ways from
+the output of some existing linker.  This switch requests \fBld\fR to
+use the traditional format instead.
+.Sp
+For example, on SunOS, \fBld\fR combines duplicate entries in the
+symbol string table.  This can reduce the size of an output file with
+full debugging information by over 30 percent.  Unfortunately, the SunOS
+\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no
+trouble).  The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not
+combine duplicate entries.
+.IP "\fB\-\-section\-start=\fR\fIsectionname\fR\fB=\fR\fIorg\fR" 4
+.IX Item "--section-start=sectionname=org"
+Locate a section in the output file at the absolute
+address given by \fIorg\fR.  You may use this option as many
+times as necessary to locate multiple sections in the command
+line.
+\&\fIorg\fR must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+\&\fB0x\fR usually associated with hexadecimal values.  \fINote:\fR there
+should be no white space between \fIsectionname\fR, the equals
+sign ("\fB=\fR"), and \fIorg\fR.
+.IP "\fB\-Tbss=\fR\fIorg\fR" 4
+.IX Item "-Tbss=org"
+.PD 0
+.IP "\fB\-Tdata=\fR\fIorg\fR" 4
+.IX Item "-Tdata=org"
+.IP "\fB\-Ttext=\fR\fIorg\fR" 4
+.IX Item "-Ttext=org"
+.PD
+Same as \fB\-\-section\-start\fR, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or
+\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR.
+.IP "\fB\-Ttext\-segment=\fR\fIorg\fR" 4
+.IX Item "-Ttext-segment=org"
+When creating an \s-1ELF\s0 executable, it will set the address of the first
+byte of the text segment.
+.IP "\fB\-Trodata\-segment=\fR\fIorg\fR" 4
+.IX Item "-Trodata-segment=org"
+When creating an \s-1ELF\s0 executable or shared object for a target where
+the read-only data is in its own segment separate from the executable
+text, it will set the address of the first byte of the read-only data segment.
+.IP "\fB\-Tldata\-segment=\fR\fIorg\fR" 4
+.IX Item "-Tldata-segment=org"
+When creating an \s-1ELF\s0 executable or shared object for x86\-64 medium memory
+model, it will set the address of the first byte of the ldata segment.
+.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4
+.IX Item "--unresolved-symbols=method"
+Determine how to handle unresolved symbols.  There are four possible
+values for \fBmethod\fR:
+.RS 4
+.IP "\fBignore-all\fR" 4
+.IX Item "ignore-all"
+Do not report any unresolved symbols.
+.IP "\fBreport-all\fR" 4
+.IX Item "report-all"
+Report all unresolved symbols.  This is the default.
+.IP "\fBignore-in-object-files\fR" 4
+.IX Item "ignore-in-object-files"
+Report unresolved symbols that are contained in shared libraries, but
+ignore them if they come from regular object files.
+.IP "\fBignore-in-shared-libs\fR" 4
+.IX Item "ignore-in-shared-libs"
+Report unresolved symbols that come from regular object files, but
+ignore them if they come from shared libraries.  This can be useful
+when creating a dynamic binary and it is known that all the shared
+libraries that it should be referencing are included on the linker's
+command line.
+.RE
+.RS 4
+.Sp
+The behaviour for shared libraries on their own can also be controlled
+by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option.
+.Sp
+Normally the linker will generate an error message for each reported
+unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR
+can change this to a warning.
+.RE
+.IP "\fB\-\-dll\-verbose\fR" 4
+.IX Item "--dll-verbose"
+.PD 0
+.IP "\fB\-\-verbose[=\fR\fI\s-1NUMBER\s0\fR\fB]\fR" 4
+.IX Item "--verbose[=NUMBER]"
+.PD
+Display the version number for \fBld\fR and list the linker emulations
+supported.  Display which input files can and cannot be opened.  Display
+the linker script being used by the linker. If the optional \fI\s-1NUMBER\s0\fR
+argument > 1, plugin symbol status will also be displayed.
+.IP "\fB\-\-version\-script=\fR\fIversion-scriptfile\fR" 4
+.IX Item "--version-script=version-scriptfile"
+Specify the name of a version script to the linker.  This is typically
+used when creating shared libraries to specify additional information
+about the version hierarchy for the library being created.  This option
+is only fully supported on \s-1ELF\s0 platforms which support shared libraries;
+see \fB\s-1VERSION\s0\fR.  It is partially supported on \s-1PE\s0 platforms, which can
+use version scripts to filter symbol visibility in auto-export mode: any
+symbols marked \fBlocal\fR in the version script will not be exported.
+.IP "\fB\-\-warn\-common\fR" 4
+.IX Item "--warn-common"
+Warn when a common symbol is combined with another common symbol or with
+a symbol definition.  Unix linkers allow this somewhat sloppy practice,
+but linkers on some other operating systems do not.  This option allows
+you to find potential problems from combining global symbols.
+Unfortunately, some C libraries use this practice, so you may get some
+warnings about symbols in the libraries as well as in your programs.
+.Sp
+There are three kinds of global symbols, illustrated here by C examples:
+.RS 4
+.IP "\fBint i = 1;\fR" 4
+.IX Item "int i = 1;"
+A definition, which goes in the initialized data section of the output
+file.
+.IP "\fBextern int i;\fR" 4
+.IX Item "extern int i;"
+An undefined reference, which does not allocate space.
+There must be either a definition or a common symbol for the
+variable somewhere.
+.IP "\fBint i;\fR" 4
+.IX Item "int i;"
+A common symbol.  If there are only (one or more) common symbols for a
+variable, it goes in the uninitialized data area of the output file.
+The linker merges multiple common symbols for the same variable into a
+single symbol.  If they are of different sizes, it picks the largest
+size.  The linker turns a common symbol into a declaration, if there is
+a definition of the same variable.
+.RE
+.RS 4
+.Sp
+The \fB\-\-warn\-common\fR option can produce five kinds of warnings.
+Each warning consists of a pair of lines: the first describes the symbol
+just encountered, and the second describes the previous symbol
+encountered with the same name.  One or both of the two symbols will be
+a common symbol.
+.IP "1." 4
+Turning a common symbol into a reference, because there is already a
+definition for the symbol.
+.Sp
+.Vb 3
+\&        <file>(<section>): warning: common of \`<symbol>\*(Aq
+\&           overridden by definition
+\&        <file>(<section>): warning: defined here
+.Ve
+.IP "2." 4
+Turning a common symbol into a reference, because a later definition for
+the symbol is encountered.  This is the same as the previous case,
+except that the symbols are encountered in a different order.
+.Sp
+.Vb 3
+\&        <file>(<section>): warning: definition of \`<symbol>\*(Aq
+\&           overriding common
+\&        <file>(<section>): warning: common is here
+.Ve
+.IP "3." 4
+Merging a common symbol with a previous same-sized common symbol.
+.Sp
+.Vb 3
+\&        <file>(<section>): warning: multiple common
+\&           of \`<symbol>\*(Aq
+\&        <file>(<section>): warning: previous common is here
+.Ve
+.IP "4." 4
+Merging a common symbol with a previous larger common symbol.
+.Sp
+.Vb 3
+\&        <file>(<section>): warning: common of \`<symbol>\*(Aq
+\&           overridden by larger common
+\&        <file>(<section>): warning: larger common is here
+.Ve
+.IP "5." 4
+Merging a common symbol with a previous smaller common symbol.  This is
+the same as the previous case, except that the symbols are
+encountered in a different order.
+.Sp
+.Vb 3
+\&        <file>(<section>): warning: common of \`<symbol>\*(Aq
+\&           overriding smaller common
+\&        <file>(<section>): warning: smaller common is here
+.Ve
+.RE
+.RS 4
+.RE
+.IP "\fB\-\-warn\-constructors\fR" 4
+.IX Item "--warn-constructors"
+Warn if any global constructors are used.  This is only useful for a few
+object file formats.  For formats like \s-1COFF\s0 or \s-1ELF,\s0 the linker can not
+detect the use of global constructors.
+.IP "\fB\-\-warn\-execstack\fR" 4
+.IX Item "--warn-execstack"
+.PD 0
+.IP "\fB\-\-no\-warn\-execstack\fR" 4
+.IX Item "--no-warn-execstack"
+.PD
+On \s-1ELF\s0 platforms this option controls how the linker generates warning
+messages when it creates an output file with an executable stack.  By
+default the linker will not warn if the \fB\-z execstack\fR command
+line option has been used, but this behaviour can be overridden by the
+\&\fB\-\-warn\-execstack\fR option.
+.Sp
+On the other hand the linker will normally warn if the stack is made
+executable because one or more of the input files need an execuable
+stack and neither of the \fB\-z execstack\fR or \fB\-z
+noexecstack\fR command line options have been specified.  This warning
+can be disabled via the \fB\-\-no\-warn\-execstack\fR option.
+.Sp
+Note: \s-1ELF\s0 format input files specify that they need an executable
+stack by having a \fI.note.GNU\-stack\fR section with the executable
+bit set in its section flags.  They can specify that they do not need
+an executable stack by having that section, but without the executable
+flag bit set.  If an input file does not have a \fI.note.GNU\-stack\fR
+section present then the default behaviour is target specific.  For
+some targets, then absence of such a section implies that an
+executable stack \fIis\fR required.  This is often a problem for hand
+crafted assembler files.
+.IP "\fB\-\-warn\-multiple\-gp\fR" 4
+.IX Item "--warn-multiple-gp"
+Warn if multiple global pointer values are required in the output file.
+This is only meaningful for certain processors, such as the Alpha.
+Specifically, some processors put large-valued constants in a special
+section.  A special register (the global pointer) points into the middle
+of this section, so that constants can be loaded efficiently via a
+base-register relative addressing mode.  Since the offset in
+base-register relative mode is fixed and relatively small (e.g., 16
+bits), this limits the maximum size of the constant pool.  Thus, in
+large programs, it is often necessary to use multiple global pointer
+values in order to be able to address all possible constants.  This
+option causes a warning to be issued whenever this case occurs.
+.IP "\fB\-\-warn\-once\fR" 4
+.IX Item "--warn-once"
+Only warn once for each undefined symbol, rather than once per module
+which refers to it.
+.IP "\fB\-\-warn\-rwx\-segments\fR" 4
+.IX Item "--warn-rwx-segments"
+.PD 0
+.IP "\fB\-\-no\-warn\-rwx\-segments\fR" 4
+.IX Item "--no-warn-rwx-segments"
+.PD
+Warn if the linker creates a loadable, non-zero sized segment that has
+all three of the read, write and execute permission flags set.  Such a
+segment represents a potential security vulnerability.  In addition
+warnings will be generated if a thread local storage segment is
+created with the execute permission flag set, regardless of whether or
+not it has the read and/or write flags set.
+.Sp
+These warnings are enabled by default.  They can be disabled via the
+\&\fB\-\-no\-warn\-rwx\-segments\fR option and re-enabled via the
+\&\fB\-\-warn\-rwx\-segments\fR option.
+.IP "\fB\-\-warn\-section\-align\fR" 4
+.IX Item "--warn-section-align"
+Warn if the address of an output section is changed because of
+alignment.  Typically, the alignment will be set by an input section.
+The address will only be changed if it not explicitly specified; that
+is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for
+the section.
+.IP "\fB\-\-warn\-textrel\fR" 4
+.IX Item "--warn-textrel"
+Warn if the linker adds \s-1DT_TEXTREL\s0 to a position-independent executable
+or shared object.
+.IP "\fB\-\-warn\-alternate\-em\fR" 4
+.IX Item "--warn-alternate-em"
+Warn if an object has alternate \s-1ELF\s0 machine code.
+.IP "\fB\-\-warn\-unresolved\-symbols\fR" 4
+.IX Item "--warn-unresolved-symbols"
+If the linker is going to report an unresolved symbol (see the option
+\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error.
+This option makes it generate a warning instead.
+.IP "\fB\-\-error\-unresolved\-symbols\fR" 4
+.IX Item "--error-unresolved-symbols"
+This restores the linker's default behaviour of generating errors when
+it is reporting unresolved symbols.
+.IP "\fB\-\-whole\-archive\fR" 4
+.IX Item "--whole-archive"
+For each archive mentioned on the command line after the
+\&\fB\-\-whole\-archive\fR option, include every object file in the archive
+in the link, rather than searching the archive for the required object
+files.  This is normally used to turn an archive file into a shared
+library, forcing every object to be included in the resulting shared
+library.  This option may be used more than once.
+.Sp
+Two notes when using this option from gcc: First, gcc doesn't know
+about this option, so you have to use \fB\-Wl,\-whole\-archive\fR.
+Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your
+list of archives, because gcc will add its own list of archives to
+your link and you may not want this flag to affect those as well.
+.IP "\fB\-\-wrap=\fR\fIsymbol\fR" 4
+.IX Item "--wrap=symbol"
+Use a wrapper function for \fIsymbol\fR.  Any undefined reference to
+\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  Any
+undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to
+\&\fIsymbol\fR.
+.Sp
+This can be used to provide a wrapper for a system function.  The
+wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  If it
+wishes to call the system function, it should call
+\&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR.
+.Sp
+Here is a trivial example:
+.Sp
+.Vb 6
+\&        void *
+\&        _\|_wrap_malloc (size_t c)
+\&        {
+\&          printf ("malloc called with %zu\en", c);
+\&          return _\|_real_malloc (c);
+\&        }
+.Ve
+.Sp
+If you link other code with this file using \fB\-\-wrap malloc\fR, then
+all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR
+instead.  The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will
+call the real \f(CW\*(C`malloc\*(C'\fR function.
+.Sp
+You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that
+links without the \fB\-\-wrap\fR option will succeed.  If you do this,
+you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same
+file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the
+call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR.
+.Sp
+Only undefined references are replaced by the linker.  So, translation unit
+internal references to \fIsymbol\fR are not resolved to
+\&\f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  In the next example, the call to \f(CW\*(C`f\*(C'\fR in
+\&\f(CW\*(C`g\*(C'\fR is not resolved to \f(CW\*(C`_\|_wrap_f\*(C'\fR.
+.Sp
+.Vb 5
+\&        int
+\&        f (void)
+\&        {
+\&          return 123;
+\&        }
+\&        
+\&        int
+\&        g (void)
+\&        {
+\&          return f();
+\&        }
+.Ve
+.IP "\fB\-\-eh\-frame\-hdr\fR" 4
+.IX Item "--eh-frame-hdr"
+.PD 0
+.IP "\fB\-\-no\-eh\-frame\-hdr\fR" 4
+.IX Item "--no-eh-frame-hdr"
+.PD
+Request (\fB\-\-eh\-frame\-hdr\fR) or suppress
+(\fB\-\-no\-eh\-frame\-hdr\fR) the creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR
+section and \s-1ELF\s0 \f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header.
+.IP "\fB\-\-no\-ld\-generated\-unwind\-info\fR" 4
+.IX Item "--no-ld-generated-unwind-info"
+Request creation of \f(CW\*(C`.eh_frame\*(C'\fR unwind info for linker
+generated code sections like \s-1PLT.\s0  This option is on by default
+if linker generated unwind info is supported.  This option also
+controls the generation of \f(CW\*(C`.sframe\*(C'\fR unwind info for linker
+generated code sections like \s-1PLT.\s0
+.IP "\fB\-\-enable\-new\-dtags\fR" 4
+.IX Item "--enable-new-dtags"
+.PD 0
+.IP "\fB\-\-disable\-new\-dtags\fR" 4
+.IX Item "--disable-new-dtags"
+.PD
+This linker can create the new dynamic tags in \s-1ELF.\s0 But the older \s-1ELF\s0
+systems may not understand them. If you specify
+\&\fB\-\-enable\-new\-dtags\fR, the new dynamic tags will be created as needed
+and older dynamic tags will be omitted.
+If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be
+created. By default, the new dynamic tags are not created. Note that
+those options are only available for \s-1ELF\s0 systems.
+.IP "\fB\-\-hash\-size=\fR\fInumber\fR" 4
+.IX Item "--hash-size=number"
+Set the default size of the linker's hash tables to a prime number
+close to \fInumber\fR.  Increasing this value can reduce the length of
+time it takes the linker to perform its tasks, at the expense of
+increasing the linker's memory requirements.  Similarly reducing this
+value can reduce the memory requirements at the expense of speed.
+.IP "\fB\-\-hash\-style=\fR\fIstyle\fR" 4
+.IX Item "--hash-style=style"
+Set the type of linker's hash table(s).  \fIstyle\fR can be either
+\&\f(CW\*(C`sysv\*(C'\fR for classic \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for
+new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both
+the classic \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR and new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR
+hash tables.  The default depends upon how the linker was configured,
+but for most Linux based systems it will be \f(CW\*(C`both\*(C'\fR.
+.IP "\fB\-\-compress\-debug\-sections=none\fR" 4
+.IX Item "--compress-debug-sections=none"
+.PD 0
+.IP "\fB\-\-compress\-debug\-sections=zlib\fR" 4
+.IX Item "--compress-debug-sections=zlib"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gnu\fR" 4
+.IX Item "--compress-debug-sections=zlib-gnu"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gabi\fR" 4
+.IX Item "--compress-debug-sections=zlib-gabi"
+.IP "\fB\-\-compress\-debug\-sections=zstd\fR" 4
+.IX Item "--compress-debug-sections=zstd"
+.PD
+On \s-1ELF\s0 platforms, these options control how \s-1DWARF\s0 debug sections are
+compressed using zlib.
+.Sp
+\&\fB\-\-compress\-debug\-sections=none\fR doesn't compress \s-1DWARF\s0 debug
+sections.  \fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses
+\&\s-1DWARF\s0 debug sections and renames them to begin with \fB.zdebug\fR
+instead of \fB.debug\fR.  \fB\-\-compress\-debug\-sections=zlib\-gabi\fR
+also compresses \s-1DWARF\s0 debug sections, but rather than renaming them it
+sets the \s-1SHF_COMPRESSED\s0 flag in the sections' headers.
+.Sp
+The \fB\-\-compress\-debug\-sections=zlib\fR option is an alias for
+\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR.
+.Sp
+\&\fB\-\-compress\-debug\-sections=zstd\fR compresses \s-1DWARF\s0 debug sections using
+zstd.
+.Sp
+Note that this option overrides any compression in input debug
+sections, so if a binary is linked with \fB\-\-compress\-debug\-sections=none\fR
+for example, then any compressed debug sections in input files will be
+uncompressed before they are copied into the output binary.
+.Sp
+The default compression behaviour varies depending upon the target
+involved and the configure options used to build the toolchain.  The
+default can be determined by examining the output from the linker's
+\&\fB\-\-help\fR option.
+.IP "\fB\-\-reduce\-memory\-overheads\fR" 4
+.IX Item "--reduce-memory-overheads"
+This option reduces memory requirements at ld runtime, at the expense of
+linking speed.  This was introduced to select the old O(n^2) algorithm
+for link map file generation, rather than the new O(n) algorithm which uses
+about 40% more memory for symbol storage.
+.Sp
+Another effect of the switch is to set the default hash table size to
+1021, which again saves memory at the cost of lengthening the linker's
+run time.  This is not done however if the \fB\-\-hash\-size\fR switch
+has been used.
+.Sp
+The \fB\-\-reduce\-memory\-overheads\fR switch may be also be used to
+enable other tradeoffs in future versions of the linker.
+.IP "\fB\-\-max\-cache\-size=\fR\fIsize\fR" 4
+.IX Item "--max-cache-size=size"
+\&\fBld\fR normally caches the relocation information and symbol tables
+of input files in memory with the unlimited size.  This option sets the
+maximum cache size to \fIsize\fR.
+.IP "\fB\-\-build\-id\fR" 4
+.IX Item "--build-id"
+.PD 0
+.IP "\fB\-\-build\-id=\fR\fIstyle\fR" 4
+.IX Item "--build-id=style"
+.PD
+Request the creation of a \f(CW\*(C`.note.gnu.build\-id\*(C'\fR \s-1ELF\s0 note section
+or a \f(CW\*(C`.buildid\*(C'\fR \s-1COFF\s0 section.  The contents of the note are
+unique bits identifying this linked file.  \fIstyle\fR can be
+\&\f(CW\*(C`uuid\*(C'\fR to use 128 random bits, \f(CW\*(C`sha1\*(C'\fR to use a 160\-bit
+\&\s-1SHA1\s0 hash on the normative parts of the output contents,
+\&\f(CW\*(C`md5\*(C'\fR to use a 128\-bit \s-1MD5\s0 hash on the normative parts of
+the output contents, or \f(CW\*(C`0x\f(CIhexstring\f(CW\*(C'\fR to use a chosen bit
+string specified as an even number of hexadecimal digits (\f(CW\*(C`\-\*(C'\fR and
+\&\f(CW\*(C`:\*(C'\fR characters between digit pairs are ignored).  If \fIstyle\fR
+is omitted, \f(CW\*(C`sha1\*(C'\fR is used.
+.Sp
+The \f(CW\*(C`md5\*(C'\fR and \f(CW\*(C`sha1\*(C'\fR styles produces an identifier
+that is always the same in an identical output file, but will be
+unique among all nonidentical output files.  It is not intended
+to be compared as a checksum for the file's contents.  A linked
+file may be changed later by other tools, but the build \s-1ID\s0 bit
+string identifying the original linked file does not change.
+.Sp
+Passing \f(CW\*(C`none\*(C'\fR for \fIstyle\fR disables the setting from any
+\&\f(CW\*(C`\-\-build\-id\*(C'\fR options earlier on the command line.
+.IP "\fB\-\-package\-metadata=\fR\fI\s-1JSON\s0\fR" 4
+.IX Item "--package-metadata=JSON"
+Request the creation of a \f(CW\*(C`.note.package\*(C'\fR \s-1ELF\s0 note section.  The
+contents of the note are in \s-1JSON\s0 format, as per the package metadata
+specification.  For more information see:
+https://systemd.io/ELF_PACKAGE_METADATA/
+If the \s-1JSON\s0 argument is missing/empty then this will disable the
+creation of the metadata note, if one had been enabled by an earlier
+occurrence of the \-\-package\-metdata option.
+If the linker has been built with libjansson, then the \s-1JSON\s0 string
+will be validated.
+.PP
+The i386 \s-1PE\s0 linker supports the \fB\-shared\fR option, which causes
+the output to be a dynamically linked library (\s-1DLL\s0) instead of a
+normal executable.  You should name the output \f(CW\*(C`*.dll\*(C'\fR when you
+use this option.  In addition, the linker fully supports the standard
+\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line
+like an object file (in fact, it should precede archives it exports
+symbols from, to ensure that they get linked in, just like a normal
+object file).
+.PP
+In addition to the options common to all targets, the i386 \s-1PE\s0 linker
+support additional command-line options that are specific to the i386
+\&\s-1PE\s0 target.  Options that take values may be separated from their
+values by either a space or an equals sign.
+.IP "\fB\-\-add\-stdcall\-alias\fR" 4
+.IX Item "--add-stdcall-alias"
+If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
+as-is and also with the suffix stripped.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-base\-file\fR \fIfile\fR" 4
+.IX Item "--base-file file"
+Use \fIfile\fR as the name of a file in which to save the base
+addresses of all the relocations needed for generating DLLs with
+\&\fIdlltool\fR.
+[This is an i386 \s-1PE\s0 specific option]
+.IP "\fB\-\-dll\fR" 4
+.IX Item "--dll"
+Create a \s-1DLL\s0 instead of a regular executable.  You may also use
+\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
+file.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-long\-section\-names\fR" 4
+.IX Item "--enable-long-section-names"
+.PD 0
+.IP "\fB\-\-disable\-long\-section\-names\fR" 4
+.IX Item "--disable-long-section-names"
+.PD
+The \s-1PE\s0 variants of the \s-1COFF\s0 object format add an extension that permits
+the use of section names longer than eight characters, the normal limit
+for \s-1COFF.\s0  By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the \s-1COFF\s0 string table required
+to support the longer names.  As a \s-1GNU\s0 extension, it is possible to
+allow their use in executable images as well, or to (probably pointlessly!)
+disallow it in object files, by using these two options.  Executable images
+generated with these long section names are slightly non-standard, carrying
+as they do a string table, and may generate confusing output when examined
+with non-GNU PE-aware tools, such as file viewers and dumpers.  However,
+\&\s-1GDB\s0 relies on the use of \s-1PE\s0 long section names to find Dwarf\-2 debug
+information sections in an executable image at runtime, and so if neither
+option is specified on the command-line, \fBld\fR will enable long
+section names, overriding the default and technically correct behaviour,
+when it finds the presence of debug information while linking an executable
+image and not stripping symbols.
+[This option is valid for all \s-1PE\s0 targeted ports of the linker]
+.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4
+.IX Item "--enable-stdcall-fixup"
+.PD 0
+.IP "\fB\-\-disable\-stdcall\-fixup\fR" 4
+.IX Item "--disable-stdcall-fixup"
+.PD
+If the link finds a symbol that it cannot resolve, it will attempt to
+do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs
+only in the format of the symbol name (cdecl vs stdcall) and will
+resolve that symbol by linking to the match.  For example, the
+undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function
+\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked
+to the function \f(CW\*(C`_bar\*(C'\fR.  When the linker does this, it prints a
+warning, since it normally should have failed to link, but sometimes
+import libraries generated from third-party dlls may need this feature
+to be usable.  If you specify \fB\-\-enable\-stdcall\-fixup\fR, this
+feature is fully enabled and warnings are not printed.  If you specify
+\&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such
+mismatches are considered to be errors.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-leading\-underscore\fR" 4
+.IX Item "--leading-underscore"
+.PD 0
+.IP "\fB\-\-no\-leading\-underscore\fR" 4
+.IX Item "--no-leading-underscore"
+.PD
+For most targets default symbol-prefix is an underscore and is defined
+in target's description. By this option it is possible to
+disable/enable the default underscore symbol-prefix.
+.IP "\fB\-\-export\-all\-symbols\fR" 4
+.IX Item "--export-all-symbols"
+If given, all global symbols in the objects used to build a \s-1DLL\s0 will
+be exported by the \s-1DLL.\s0  Note that this is the default if there
+otherwise wouldn't be any exported symbols.  When symbols are
+explicitly exported via \s-1DEF\s0 files or implicitly exported via function
+attributes, the default is to not export anything else unless this
+option is given.  Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR,
+\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and
+\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically
+exported.  Also, symbols imported from other DLLs will not be
+re-exported, nor will symbols specifying the \s-1DLL\s0's internal layout
+such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with
+\&\f(CW\*(C`_iname\*(C'\fR.  In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR,
+\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported.
+Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will
+not be exported, to help with \*(C+ DLLs.  Finally, there is an
+extensive list of cygwin-private symbols that are not exported
+(obviously, this applies on when building DLLs for cygwin targets).
+These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR,
+\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR,
+\&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR,
+\&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR,
+\&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4
+.IX Item "--exclude-symbols symbol,symbol,..."
+Specifies a list of symbols which should not be automatically
+exported.  The symbol names may be delimited by commas or colons.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-exclude\-all\-symbols\fR" 4
+.IX Item "--exclude-all-symbols"
+Specifies no symbols should be automatically exported.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-file\-alignment\fR" 4
+.IX Item "--file-alignment"
+Specify the file alignment.  Sections in the file will always begin at
+file offsets which are multiples of this number.  This defaults to
+512.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-heap\fR \fIreserve\fR" 4
+.IX Item "--heap reserve"
+.PD 0
+.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
+.IX Item "--heap reserve,commit"
+.PD
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as heap for this program.  The default is 1MB reserved, 4K
+committed.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
+.IX Item "--image-base value"
+Use \fIvalue\fR as the base address of your program or dll.  This is
+the lowest memory location that will be used when your program or dll
+is loaded.  To reduce the need to relocate and improve performance of
+your dlls, each should have a unique base address and not overlap any
+other dlls.  The default is 0x400000 for executables, and 0x10000000
+for dlls.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-kill\-at\fR" 4
+.IX Item "--kill-at"
+If given, the stdcall suffixes (@\fInn\fR) will be stripped from
+symbols before they are exported.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-large\-address\-aware\fR" 4
+.IX Item "--large-address-aware"
+If given, the appropriate bit in the \*(L"Characteristics\*(R" field of the \s-1COFF\s0
+header is set to indicate that this executable supports virtual addresses
+greater than 2 gigabytes.  This should be used in conjunction with the /3GB
+or /USERVA=\fIvalue\fR megabytes switch in the \*(L"[operating systems]\*(R"
+section of the \s-1BOOT.INI.\s0  Otherwise, this bit has no effect.
+[This option is specific to \s-1PE\s0 targeted ports of the linker]
+.IP "\fB\-\-disable\-large\-address\-aware\fR" 4
+.IX Item "--disable-large-address-aware"
+Reverts the effect of a previous \fB\-\-large\-address\-aware\fR option.
+This is useful if \fB\-\-large\-address\-aware\fR is always set by the compiler
+driver (e.g. Cygwin gcc) and the executable does not support virtual
+addresses greater than 2 gigabytes.
+[This option is specific to \s-1PE\s0 targeted ports of the linker]
+.IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4
+.IX Item "--major-image-version value"
+Sets the major number of the \*(L"image version\*(R".  Defaults to 1.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4
+.IX Item "--major-os-version value"
+Sets the major number of the \*(L"os version\*(R".  Defaults to 4.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4
+.IX Item "--major-subsystem-version value"
+Sets the major number of the \*(L"subsystem version\*(R".  Defaults to 4.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4
+.IX Item "--minor-image-version value"
+Sets the minor number of the \*(L"image version\*(R".  Defaults to 0.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4
+.IX Item "--minor-os-version value"
+Sets the minor number of the \*(L"os version\*(R".  Defaults to 0.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4
+.IX Item "--minor-subsystem-version value"
+Sets the minor number of the \*(L"subsystem version\*(R".  Defaults to 0.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-output\-def\fR \fIfile\fR" 4
+.IX Item "--output-def file"
+The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0
+file corresponding to the \s-1DLL\s0 the linker is generating.  This \s-1DEF\s0 file
+(which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import
+library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to
+automatically or implicitly exported symbols.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-auto\-image\-base\fR" 4
+.IX Item "--enable-auto-image-base"
+.PD 0
+.IP "\fB\-\-enable\-auto\-image\-base=\fR\fIvalue\fR" 4
+.IX Item "--enable-auto-image-base=value"
+.PD
+Automatically choose the image base for DLLs, optionally starting with base
+\&\fIvalue\fR, unless one is specified using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument.
+By using a hash generated from the dllname to create unique image bases
+for each \s-1DLL,\s0 in-memory collisions and relocations which can delay program
+execution are avoided.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-disable\-auto\-image\-base\fR" 4
+.IX Item "--disable-auto-image-base"
+Do not automatically generate a unique image base.  If there is no
+user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform
+default.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4
+.IX Item "--dll-search-prefix string"
+When linking dynamically to a dll without an import library,
+search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to
+\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction
+between DLLs built for the various \*(L"subplatforms\*(R": native, cygwin,
+uwin, pw, etc.  For instance, cygwin DLLs typically use
+\&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-auto\-import\fR" 4
+.IX Item "--enable-auto-import"
+Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for
+\&\s-1DATA\s0 imports from DLLs, thus making it possible to bypass the dllimport
+mechanism on the user side and to reference unmangled symbol names.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.Sp
+The following remarks pertain to the original implementation of the
+feature and are obsolete nowadays for Cygwin and MinGW targets.
+.Sp
+Note: Use of the 'auto\-import' extension will cause the text section
+of the image file to be made writable. This does not conform to the
+PE-COFF format specification published by Microsoft.
+.Sp
+Note \- use of the 'auto\-import' extension will also cause read only
+data which would normally be placed into the .rdata section to be
+placed into the .data section instead.  This is in order to work
+around a problem with consts that is described here:
+http://www.cygwin.com/ml/cygwin/2004\-09/msg01101.html
+.Sp
+Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may
+see this message:
+.Sp
+"variable '<var>' can't be auto-imported. Please read the
+documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details."
+.Sp
+This message occurs when some (sub)expression accesses an address
+ultimately given by the sum of two constants (Win32 import tables only
+allow one).  Instances where this may occur include accesses to member
+fields of struct variables imported from a \s-1DLL,\s0 as well as using a
+constant index into an array variable imported from a \s-1DLL.\s0  Any
+multiword variable (arrays, structs, long long, etc) may trigger
+this error condition.  However, regardless of the exact data type
+of the offending exported variable, ld will always detect it, issue
+the warning, and exit.
+.Sp
+There are several ways to address this difficulty, regardless of the
+data type of the exported variable:
+.Sp
+One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task
+of adjusting references in your client code for runtime environment, so
+this method works only when runtime environment supports this feature.
+.Sp
+A second solution is to force one of the 'constants' to be a variable \*(--
+that is, unknown and un-optimizable at compile time.  For arrays,
+there are two possibilities: a) make the indexee (the array's address)
+a variable, or b) make the 'constant' index a variable.  Thus:
+.Sp
+.Vb 3
+\&        extern type extern_array[];
+\&        extern_array[1] \-\->
+\&           { volatile type *t=extern_array; t[1] }
+.Ve
+.Sp
+or
+.Sp
+.Vb 3
+\&        extern type extern_array[];
+\&        extern_array[1] \-\->
+\&           { volatile int t=1; extern_array[t] }
+.Ve
+.Sp
+For structs (and most other multiword data types) the only option
+is to make the struct itself (or the long long, or the ...) variable:
+.Sp
+.Vb 3
+\&        extern struct s extern_struct;
+\&        extern_struct.field \-\->
+\&           { volatile struct s *t=&extern_struct; t\->field }
+.Ve
+.Sp
+or
+.Sp
+.Vb 3
+\&        extern long long extern_ll;
+\&        extern_ll \-\->
+\&          { volatile long long * local_ll=&extern_ll; *local_ll }
+.Ve
+.Sp
+A third method of dealing with this difficulty is to abandon
+\&'auto\-import' for the offending symbol and mark it with
+\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR.  However, in practice that
+requires using compile-time #defines to indicate whether you are
+building a \s-1DLL,\s0 building client code that will link to the \s-1DLL,\s0 or
+merely building/linking to a static library.   In making the choice
+between the various methods of resolving the 'direct address with
+constant offset' problem, you should consider typical real-world usage:
+.Sp
+Original:
+.Sp
+.Vb 7
+\&        \-\-foo.h
+\&        extern int arr[];
+\&        \-\-foo.c
+\&        #include "foo.h"
+\&        void main(int argc, char **argv){
+\&          printf("%d\en",arr[1]);
+\&        }
+.Ve
+.Sp
+Solution 1:
+.Sp
+.Vb 9
+\&        \-\-foo.h
+\&        extern int arr[];
+\&        \-\-foo.c
+\&        #include "foo.h"
+\&        void main(int argc, char **argv){
+\&          /* This workaround is for win32 and cygwin; do not "optimize" */
+\&          volatile int *parr = arr;
+\&          printf("%d\en",parr[1]);
+\&        }
+.Ve
+.Sp
+Solution 2:
+.Sp
+.Vb 10
+\&        \-\-foo.h
+\&        /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */
+\&        #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e
+\&          !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
+\&        #define FOO_IMPORT _\|_declspec(dllimport)
+\&        #else
+\&        #define FOO_IMPORT
+\&        #endif
+\&        extern FOO_IMPORT int arr[];
+\&        \-\-foo.c
+\&        #include "foo.h"
+\&        void main(int argc, char **argv){
+\&          printf("%d\en",arr[1]);
+\&        }
+.Ve
+.Sp
+A fourth way to avoid this problem is to re-code your
+library to use a functional interface rather than a data interface
+for the offending variables (e.g. \fBset_foo()\fR and \fBget_foo()\fR accessor
+functions).
+.IP "\fB\-\-disable\-auto\-import\fR" 4
+.IX Item "--disable-auto-import"
+Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to
+\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4
+.IX Item "--enable-runtime-pseudo-reloc"
+If your code contains expressions described in \-\-enable\-auto\-import section,
+that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create
+a vector of 'runtime pseudo relocations' which can be used by runtime
+environment to adjust references to such data in your client code.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4
+.IX Item "--disable-runtime-pseudo-reloc"
+Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from DLLs.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4
+.IX Item "--enable-extra-pe-debug"
+Show additional debug info related to auto-import symbol thunking.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-section\-alignment\fR" 4
+.IX Item "--section-alignment"
+Sets the section alignment.  Sections in memory will always begin at
+addresses which are a multiple of this number.  Defaults to 0x1000.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-stack\fR \fIreserve\fR" 4
+.IX Item "--stack reserve"
+.PD 0
+.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
+.IX Item "--stack reserve,commit"
+.PD
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as stack for this program.  The default is 2MB reserved, 4K
+committed.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4
+.IX Item "--subsystem which"
+.PD 0
+.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4
+.IX Item "--subsystem which:major"
+.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4
+.IX Item "--subsystem which:major.minor"
+.PD
+Specifies the subsystem under which your program will execute.  The
+legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
+\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR.  You may optionally set
+the subsystem version also.  Numeric values are also accepted for
+\&\fIwhich\fR.
+[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.Sp
+The following options set flags in the \f(CW\*(C`DllCharacteristics\*(C'\fR field
+of the \s-1PE\s0 file header:
+[These options are specific to \s-1PE\s0 targeted ports of the linker]
+.IP "\fB\-\-high\-entropy\-va\fR" 4
+.IX Item "--high-entropy-va"
+.PD 0
+.IP "\fB\-\-disable\-high\-entropy\-va\fR" 4
+.IX Item "--disable-high-entropy-va"
+.PD
+Image is compatible with 64\-bit address space layout randomization
+(\s-1ASLR\s0).  This option is enabled by default for 64\-bit \s-1PE\s0 images.
+.Sp
+This option also implies \fB\-\-dynamicbase\fR and
+\&\fB\-\-enable\-reloc\-section\fR.
+.IP "\fB\-\-dynamicbase\fR" 4
+.IX Item "--dynamicbase"
+.PD 0
+.IP "\fB\-\-disable\-dynamicbase\fR" 4
+.IX Item "--disable-dynamicbase"
+.PD
+The image base address may be relocated using address space layout
+randomization (\s-1ASLR\s0).  This feature was introduced with \s-1MS\s0 Windows
+Vista for i386 \s-1PE\s0 targets.  This option is enabled by default but
+can be disabled via the \fB\-\-disable\-dynamicbase\fR option.
+This option also implies \fB\-\-enable\-reloc\-section\fR.
+.IP "\fB\-\-forceinteg\fR" 4
+.IX Item "--forceinteg"
+.PD 0
+.IP "\fB\-\-disable\-forceinteg\fR" 4
+.IX Item "--disable-forceinteg"
+.PD
+Code integrity checks are enforced.  This option is disabled by
+default.
+.IP "\fB\-\-nxcompat\fR" 4
+.IX Item "--nxcompat"
+.PD 0
+.IP "\fB\-\-disable\-nxcompat\fR" 4
+.IX Item "--disable-nxcompat"
+.PD
+The image is compatible with the Data Execution Prevention.
+This feature was introduced with \s-1MS\s0 Windows \s-1XP SP2\s0 for i386 \s-1PE\s0
+targets.  The option is enabled by default.
+.IP "\fB\-\-no\-isolation\fR" 4
+.IX Item "--no-isolation"
+.PD 0
+.IP "\fB\-\-disable\-no\-isolation\fR" 4
+.IX Item "--disable-no-isolation"
+.PD
+Although the image understands isolation, do not isolate the image.
+This option is disabled by default.
+.IP "\fB\-\-no\-seh\fR" 4
+.IX Item "--no-seh"
+.PD 0
+.IP "\fB\-\-disable\-no\-seh\fR" 4
+.IX Item "--disable-no-seh"
+.PD
+The image does not use \s-1SEH.\s0 No \s-1SE\s0 handler may be called from
+this image.  This option is disabled by default.
+.IP "\fB\-\-no\-bind\fR" 4
+.IX Item "--no-bind"
+.PD 0
+.IP "\fB\-\-disable\-no\-bind\fR" 4
+.IX Item "--disable-no-bind"
+.PD
+Do not bind this image.  This option is disabled by default.
+.IP "\fB\-\-wdmdriver\fR" 4
+.IX Item "--wdmdriver"
+.PD 0
+.IP "\fB\-\-disable\-wdmdriver\fR" 4
+.IX Item "--disable-wdmdriver"
+.PD
+The driver uses the \s-1MS\s0 Windows Driver Model.  This option is disabled
+by default.
+.IP "\fB\-\-tsaware\fR" 4
+.IX Item "--tsaware"
+.PD 0
+.IP "\fB\-\-disable\-tsaware\fR" 4
+.IX Item "--disable-tsaware"
+.PD
+The image is Terminal Server aware.  This option is disabled by
+default.
+.IP "\fB\-\-insert\-timestamp\fR" 4
+.IX Item "--insert-timestamp"
+.PD 0
+.IP "\fB\-\-no\-insert\-timestamp\fR" 4
+.IX Item "--no-insert-timestamp"
+.PD
+Insert a real timestamp into the image.  This is the default behaviour
+as it matches legacy code and it means that the image will work with
+other, proprietary tools.  The problem with this default is that it
+will result in slightly different images being produced each time the
+same sources are linked.  The option \fB\-\-no\-insert\-timestamp\fR
+can be used to insert a zero value for the timestamp, this ensuring
+that binaries produced from identical sources will compare
+identically.
+.IP "\fB\-\-enable\-reloc\-section\fR" 4
+.IX Item "--enable-reloc-section"
+.PD 0
+.IP "\fB\-\-disable\-reloc\-section\fR" 4
+.IX Item "--disable-reloc-section"
+.PD
+Create the base relocation table, which is necessary if the image
+is loaded at a different image base than specified in the \s-1PE\s0 header.
+This option is enabled by default.
+.PP
+The C6X uClinux target uses a binary format called \s-1DSBT\s0 to support shared
+libraries.  Each shared library in the system needs to have a unique index;
+all executables use an index of 0.
+.IP "\fB\-\-dsbt\-size\fR \fIsize\fR" 4
+.IX Item "--dsbt-size size"
+This option sets the number of entries in the \s-1DSBT\s0 of the current executable
+or shared library to \fIsize\fR.  The default is to create a table with 64
+entries.
+.IP "\fB\-\-dsbt\-index\fR \fIindex\fR" 4
+.IX Item "--dsbt-index index"
+This option sets the \s-1DSBT\s0 index of the current executable or shared library
+to \fIindex\fR.  The default is 0, which is appropriate for generating
+executables.  If a shared library is generated with a \s-1DSBT\s0 index of 0, the
+\&\f(CW\*(C`R_C6000_DSBT_INDEX\*(C'\fR relocs are copied into the output file.
+.Sp
+The \fB\-\-no\-merge\-exidx\-entries\fR switch disables the merging of adjacent
+exidx entries in frame unwind info.
+.IP "\fB\-\-branch\-stub\fR" 4
+.IX Item "--branch-stub"
+This option enables linker branch relaxation by inserting branch stub
+sections when needed to extend the range of branches.  This option is
+usually not required since C\-SKY supports branch and call instructions that
+can access the full memory range and branch relaxation is normally handled by
+the compiler or assembler.
+.IP "\fB\-\-stub\-group\-size=\fR\fIN\fR" 4
+.IX Item "--stub-group-size=N"
+This option allows finer control of linker branch stub creation.
+It sets the maximum size of a group of input sections that can
+be handled by one stub section.  A negative value of \fIN\fR locates
+stub sections after their branches, while a positive value allows stub
+sections to appear either before or after the branches.  Values of
+\&\fB1\fR or \fB\-1\fR indicate that the
+linker should choose suitable defaults.
+.PP
+The 68HC11 and 68HC12 linkers support specific options to control the
+memory bank switching mapping and trampoline code generation.
+.IP "\fB\-\-no\-trampoline\fR" 4
+.IX Item "--no-trampoline"
+This option disables the generation of trampoline. By default a trampoline
+is generated for each far function which is called using a \f(CW\*(C`jsr\*(C'\fR
+instruction (this happens when a pointer to a far function is taken).
+.IP "\fB\-\-bank\-window\fR \fIname\fR" 4
+.IX Item "--bank-window name"
+This option indicates to the linker the name of the memory region in
+the \fB\s-1MEMORY\s0\fR specification that describes the memory bank window.
+The definition of such region is then used by the linker to compute
+paging and addresses within the memory window.
+.PP
+The following options are supported to control handling of \s-1GOT\s0 generation
+when linking for 68K targets.
+.IP "\fB\-\-got=\fR\fItype\fR" 4
+.IX Item "--got=type"
+This option tells the linker which \s-1GOT\s0 generation scheme to use.
+\&\fItype\fR should be one of \fBsingle\fR, \fBnegative\fR,
+\&\fBmultigot\fR or \fBtarget\fR.  For more information refer to the
+Info entry for \fIld\fR.
+.PP
+The following options are supported to control microMIPS instruction
+generation and branch relocation checks for \s-1ISA\s0 mode transitions when
+linking for \s-1MIPS\s0 targets.
+.IP "\fB\-\-insn32\fR" 4
+.IX Item "--insn32"
+.PD 0
+.IP "\fB\-\-no\-insn32\fR" 4
+.IX Item "--no-insn32"
+.PD
+These options control the choice of microMIPS instructions used in code
+generated by the linker, such as that in the \s-1PLT\s0 or lazy binding stubs,
+or in relaxation.  If \fB\-\-insn32\fR is used, then the linker only uses
+32\-bit instruction encodings.  By default or if \fB\-\-no\-insn32\fR is
+used, all instruction encodings are used, including 16\-bit ones where
+possible.
+.IP "\fB\-\-ignore\-branch\-isa\fR" 4
+.IX Item "--ignore-branch-isa"
+.PD 0
+.IP "\fB\-\-no\-ignore\-branch\-isa\fR" 4
+.IX Item "--no-ignore-branch-isa"
+.PD
+These options control branch relocation checks for invalid \s-1ISA\s0 mode
+transitions.  If \fB\-\-ignore\-branch\-isa\fR is used, then the linker
+accepts any branch relocations and any \s-1ISA\s0 mode transition required
+is lost in relocation calculation, except for some cases of \f(CW\*(C`BAL\*(C'\fR
+instructions which meet relaxation conditions and are converted to
+equivalent \f(CW\*(C`JALX\*(C'\fR instructions as the associated relocation is
+calculated.  By default or if \fB\-\-no\-ignore\-branch\-isa\fR is used
+a check is made causing the loss of an \s-1ISA\s0 mode transition to produce
+an error.
+.IP "\fB\-\-compact\-branches\fR" 4
+.IX Item "--compact-branches"
+.PD 0
+.IP "\fB\-\-no\-compact\-branches\fR" 4
+.IX Item "--no-compact-branches"
+.PD
+These options control the generation of compact instructions by the linker
+in the \s-1PLT\s0 entries for \s-1MIPS R6.\s0
+.PP
+For the pdp11\-aout target, three variants of the output format can be
+produced as selected by the following options.  The default variant
+for pdp11\-aout is the \fB\-\-omagic\fR option, whereas for other
+targets \fB\-\-nmagic\fR is the default.  The \fB\-\-imagic\fR option is
+defined only for the pdp11\-aout target, while the others are described
+here as they apply to the pdp11\-aout target.
+.IP "\fB\-N\fR" 4
+.IX Item "-N"
+.PD 0
+.IP "\fB\-\-omagic\fR" 4
+.IX Item "--omagic"
+.PD
+Mark the output as \f(CW\*(C`OMAGIC\*(C'\fR (0407) in the \fIa.out\fR header to
+indicate that the text segment is not to be write-protected and
+shared.  Since the text and data sections are both readable and
+writable, the data section is allocated immediately contiguous after
+the text segment.  This is the oldest format for \s-1PDP11\s0 executable
+programs and is the default for \fBld\fR on \s-1PDP11\s0 Unix systems
+from the beginning through 2.11BSD.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-\-nmagic\fR" 4
+.IX Item "--nmagic"
+.PD
+Mark the output as \f(CW\*(C`NMAGIC\*(C'\fR (0410) in the \fIa.out\fR header to
+indicate that when the output file is executed, the text portion will
+be read-only and shareable among all processes executing the same
+file.  This involves moving the data areas up to the first possible 8K
+byte page boundary following the end of the text.  This option creates
+a \fIpure executable\fR format.
+.IP "\fB\-z\fR" 4
+.IX Item "-z"
+.PD 0
+.IP "\fB\-\-imagic\fR" 4
+.IX Item "--imagic"
+.PD
+Mark the output as \f(CW\*(C`IMAGIC\*(C'\fR (0411) in the \fIa.out\fR header to
+indicate that when the output file is executed, the program text and
+data areas will be loaded into separate address spaces using the split
+instruction and data space feature of the memory management unit in
+larger models of the \s-1PDP11.\s0  This doubles the address space available
+to the program.  The text segment is again pure, write-protected, and
+shareable.  The only difference in the output format between this
+option and the others, besides the magic number, is that both the text
+and data sections start at location 0.  The \fB\-z\fR option selected
+this format in 2.11BSD.  This option creates a \fIseparate
+executable\fR format.
+.IP "\fB\-\-no\-omagic\fR" 4
+.IX Item "--no-omagic"
+Equivalent to \fB\-\-nmagic\fR for pdp11\-aout.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+You can change the behaviour of \fBld\fR with the environment variables
+\&\f(CW\*(C`GNUTARGET\*(C'\fR,
+\&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR.
+.PP
+\&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't
+use \fB\-b\fR (or its synonym \fB\-\-format\fR).  Its value should be one
+of the \s-1BFD\s0 names for an input format.  If there is no
+\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format
+of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0
+attempts to discover the input format by examining binary input files;
+this method often succeeds, but there are potential ambiguities, since
+there is no method of ensuring that the magic number used to specify
+object-file formats is unique.  However, the configuration procedure for
+\&\s-1BFD\s0 on each system places the conventional format for that system first
+in the search-list, so ambiguities are resolved in favor of convention.
+.PP
+\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the
+\&\fB\-m\fR option.  The emulation can affect various aspects of linker
+behaviour, particularly the default linker script.  You can list the
+available emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.  If
+the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment
+variable is not defined, the default emulation depends upon how the
+linker was configured.
+.PP
+Normally, the linker will default to demangling symbols.  However, if
+\&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will
+default to not demangling symbols.  This environment variable is used in
+a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program.  The default
+may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR
+options.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBar\fR\|(1), \fBnm\fR\|(1), \fBobjcopy\fR\|(1), \fBobjdump\fR\|(1), \fBreadelf\fR\|(1) and
+the Info entries for \fIbinutils\fR and
+\&\fIld\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/leaftoppm.1 b/upstream/mageia-cauldron/man1/leaftoppm.1
new file mode 100644
index 00000000..68289a64
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/leaftoppm.1
@@ -0,0 +1,55 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Leaftoppm User Manual" 0 "01 June 2000" "netpbm documentation"
+
+.SH NAME
+leaftoppm - convert Interleaf image format to PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBleaftoppm\fP
+[\fIleaffile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBleaftoppm\fP reads a PPM image as input and generates an
+Interleaf image file as output.
+.PP
+Interleaf is a now-defunct (actually purchased ca. 2000 by
+BroadVision) technical publishing software company.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBleaftoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+The program is copyright (C) 1994 by Bill O'Donnell.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/leaftoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/less.1 b/upstream/mageia-cauldron/man1/less.1
new file mode 100644
index 00000000..2b887320
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/less.1
@@ -0,0 +1,2335 @@
+'\" t
+.TH LESS 1 "Version 643: 12 Feb 2024"
+.SH NAME
+less \- opposite of more
+.SH SYNOPSIS
+.B "less \-?"
+.br
+.B "less \-\-help"
+.br
+.B "less \-V"
+.br
+.B "less \-\-version"
+.br
+.B "less [\-[+]aABcCdeEfFgGiIJKLmMnNqQrRsSuUVwWX\(ti]"
+.br
+.B "     [\-b \fIspace\/\fP] [\-h \fIlines\/\fP] [\-j \fIline\/\fP] [\-k \fIkeyfile\/\fP]"
+.br
+.B "     [\-{oO} \fIlogfile\/\fP] [\-p \fIpattern\/\fP] [\-P \fIprompt\/\fP] [\-t \fItag\/\fP]"
+.br
+.B "     [\-T \fItagsfile\/\fP] [\-x \fItab\/\fP,...] [\-y \fIlines\/\fP] [\-[z] \fIlines\/\fP]"
+.br
+.B "     [\-# \fIshift\/\fP] [+[+]\fIcmd\/\fP] [\-\-] [\fIfilename\/\fP]..."
+.br
+(See the OPTIONS section for alternate option syntax with long option names.)
+.
+.SH DESCRIPTION
+.B Less
+is a program similar to
+.BR more (1),
+but which allows backward movement
+in the file as well as forward movement.
+Also,
+.B less
+does not have to read the entire input file before starting,
+so with large input files it starts up faster than text editors like
+.BR vi (1).
+.B Less
+uses termcap (or terminfo on some systems),
+so it can run on a variety of terminals.
+There is even limited support for hardcopy terminals.
+(On a hardcopy terminal, lines which should be printed at the top
+of the screen are prefixed with a caret.)
+.PP
+Commands are based on both
+.B more
+and
+.BR vi .
+Commands may be preceded by a decimal number,
+called N in the descriptions below.
+The number is used by some commands, as indicated.
+.
+.SH COMMANDS
+In the following descriptions, \(haX means control-X.
+ESC stands for the ESCAPE key; for example ESC-v means the
+two character sequence "ESCAPE", then "v".
+.IP "h or H"
+Help: display a summary of these commands.
+If you forget all the other commands, remember this one.
+.IP "SPACE or \(haV or f or \(haF"
+Scroll forward N lines, default one window (see option \-z below).
+If N is more than the screen size, only the final screenful is displayed.
+Warning: some systems use \(haV as a special literalization character.
+.IP "z"
+Like SPACE, but if N is specified, it becomes the new window size.
+.IP "ESC-SPACE"
+Like SPACE, but scrolls a full screenful, even if it reaches
+end-of-file in the process.
+.IP "ENTER or RETURN or \(haN or e or \(haE or j or \(haJ"
+Scroll forward N lines, default 1.
+The entire N lines are displayed, even if N is more than the screen size.
+.IP "d or \(haD"
+Scroll forward N lines, default one half of the screen size.
+If N is specified, it becomes the new default for
+subsequent d and u commands.
+.IP "b or \(haB or ESC-v"
+Scroll backward N lines, default one window (see option \-z below).
+If N is more than the screen size, only the final screenful is displayed.
+.IP "w"
+Like ESC-v, but if N is specified, it becomes the new window size.
+.IP "y or \(haY or \(haP or k or \(haK"
+Scroll backward N lines, default 1.
+The entire N lines are displayed, even if N is more than the screen size.
+Warning: some systems use \(haY as a special job control character.
+.IP "u or \(haU"
+Scroll backward N lines, default one half of the screen size.
+If N is specified, it becomes the new default for
+subsequent d and u commands.
+.IP "J"
+Like j, but continues to scroll beyond the end of the file.
+.IP "K or Y"
+Like k, but continues to scroll beyond the beginning of the file.
+.IP "ESC-) or RIGHTARROW"
+Scroll horizontally right N characters, default half the screen width
+(see the \-# option).
+If a number N is specified, it becomes the default for future RIGHTARROW
+and LEFTARROW commands.
+While the text is scrolled, it acts as though the \-S option
+(chop lines) were in effect.
+.IP "ESC-( or LEFTARROW"
+Scroll horizontally left N characters, default half the screen width
+(see the \-# option).
+If a number N is specified, it becomes the default for future RIGHTARROW
+and LEFTARROW commands.
+.IP "ESC-} or \(haRIGHTARROW"
+Scroll horizontally right to show the end of the longest displayed line.
+.IP "ESC-{ or \(haLEFTARROW"
+Scroll horizontally left back to the first column.
+.IP "r or \(haR or \(haL"
+Repaint the screen.
+.IP R
+Repaint the screen, discarding any buffered input.
+That is, reload the current file.
+Useful if the file is changing while it is being viewed.
+.IP "F"
+Scroll forward, and keep trying to read when the
+end of file is reached.
+Normally this command would be used when already at the end of the file.
+It is a way to monitor the tail of a file which is growing
+while it is being viewed.
+(The behavior is similar to the "tail \-f" command.)
+To stop waiting for more data, enter the interrupt character (usually \(haC).
+On systems which support
+.BR poll (2)
+you can also use \(haX or the character specified by the \-\-intr option.
+If the input is a pipe and the \-\-exit-follow-on-close option is in effect,
+.B less
+will automatically stop waiting for data when the input side 
+of the pipe is closed.
+.IP "ESC-F"
+Like F, but as soon as a line is found which matches
+the last search pattern, the terminal bell is rung
+and forward scrolling stops.
+.IP "g or < or ESC-<"
+Go to line N in the file, default 1 (beginning of file).
+(Warning: this may be slow if N is large.)
+.IP "G or > or ESC->"
+Go to line N in the file, default the end of the file.
+(Warning: this may be slow if N is large,
+or if N is not specified and
+standard input, rather than a file, is being read.)
+.IP "ESC-G"
+Same as G, except if no number N is specified and the input is standard input,
+goes to the last line which is currently buffered.
+.IP "p or %"
+Go to a position N percent into the file.
+N should be between 0 and 100, and may contain a decimal point.
+.IP "P"
+Go to the line containing byte offset N in the file.
+.IP "{"
+If a left curly bracket appears in the top line displayed
+on the screen,
+the { command will go to the matching right curly bracket.
+The matching right curly bracket is positioned on the bottom
+line of the screen.
+If there is more than one left curly bracket on the top line,
+a number N may be used to specify the N-th bracket on the line.
+.IP "}"
+If a right curly bracket appears in the bottom line displayed
+on the screen,
+the } command will go to the matching left curly bracket.
+The matching left curly bracket is positioned on the top
+line of the screen.
+If there is more than one right curly bracket on the bottom line,
+a number N may be used to specify the N-th bracket on the line.
+.IP "("
+Like {, but applies to parentheses rather than curly brackets.
+.IP ")"
+Like }, but applies to parentheses rather than curly brackets.
+.IP "["
+Like {, but applies to square brackets rather than curly brackets.
+.IP "]"
+Like }, but applies to square brackets rather than curly brackets.
+.IP "ESC-\(haF"
+Followed by two characters,
+acts like {, but uses the two characters as open and close brackets,
+respectively.
+For example, "ESC \(haF < >" could be used to
+go forward to the > which matches the < in the top displayed line.
+.IP "ESC-\(haB"
+Followed by two characters,
+acts like }, but uses the two characters as open and close brackets,
+respectively.
+For example, "ESC \(haB < >" could be used to
+go backward to the < which matches the > in the bottom displayed line.
+.IP m
+Followed by any lowercase or uppercase letter,
+marks the first displayed line with that letter.
+If the status column is enabled via the \-J option,
+the status column shows the marked line.
+.IP M
+Acts like m, except the last displayed line is marked
+rather than the first displayed line.
+.IP "\(aq"
+(Single quote.)
+Followed by any lowercase or uppercase letter, returns to the position which
+was previously marked with that letter.
+Followed by another single quote, returns to the position at
+which the last "large" movement command was executed.
+Followed by a \(ha or $, jumps to the beginning or end of the
+file respectively.
+Marks are preserved when a new file is examined,
+so the \(aq command can be used to switch between input files.
+.IP "\(haX\(haX"
+Same as single quote.
+.IP "ESC-m"
+Followed by any lowercase or uppercase letter,
+clears the mark identified by that letter.
+.IP /pattern
+Search forward in the file for the N-th line containing the pattern.
+N defaults to 1.
+The pattern is a regular expression, as recognized by
+the regular expression library supplied by your system.
+By default, searching is case-sensitive (uppercase and lowercase 
+are considered different); the \-i option can be used to change this.
+The search starts at the first line displayed
+(but see the \-a and \-j options, which change this).
+.sp
+Certain characters are special
+if entered at the beginning of the pattern;
+they modify the type of search rather than become part of the pattern:
+.RS
+.IP "\(haN or !"
+Search for lines which do NOT match the pattern.
+.IP "\(haE or *"
+Search multiple files.
+That is, if the search reaches the END of the current file
+without finding a match,
+the search continues in the next file in the command line list.
+.IP "\(haF or @"
+Begin the search at the first line of the FIRST file
+in the command line list,
+regardless of what is currently displayed on the screen
+or the settings of the \-a or \-j options.
+.IP "\(haK"
+Highlight any text which matches the pattern on the current screen,
+but don't move to the first match (KEEP current position).
+.IP "\(haR"
+Don't interpret regular expression metacharacters;
+that is, do a simple textual comparison.
+.IP "\(haS"
+Followed by a digit N between 1 and 5.
+Only text which has a non-empty match for the N-th parenthesized SUB-PATTERN 
+will be considered to match the pattern.
+(Supported only if
+.B less 
+is built with one of the regular expression libraries
+.BR posix ", " pcre ", or " pcre2 ".)"
+Multiple \(haS modifiers can be specified,
+to match more than one sub-pattern.
+.IP "\(haW"
+WRAP around the current file.
+That is, if the search reaches the end of the current file
+without finding a match, the search continues from the first line of the
+current file up to the line where it started.
+If the \(haW modifier is set, the \(haE modifier is ignored.
+.RE
+.IP ?pattern
+Search backward in the file for the N-th line containing the pattern.
+The search starts at the last line displayed
+(but see the \-a and \-j options, which change this).
+.sp
+Certain characters are special as in the / command:
+.RS
+.IP "\(haN or !"
+Search for lines which do NOT match the pattern.
+.IP "\(haE or *"
+Search multiple files.
+That is, if the search reaches the beginning of the current file
+without finding a match,
+the search continues in the previous file in the command line list.
+.IP "\(haF or @"
+Begin the search at the last line of the last file
+in the command line list,
+regardless of what is currently displayed on the screen
+or the settings of the \-a or \-j options.
+.IP "\(haK"
+As in forward searches.
+.IP "\(haR"
+As in forward searches.
+.IP "\(haS"
+As in forward searches.
+.IP "\(haW"
+WRAP around the current file.
+That is, if the search reaches the beginning of the current file
+without finding a match, the search continues from the last line of the
+current file up to the line where it started.
+.RE
+.IP "ESC-/pattern"
+Same as "/*".
+.IP "ESC-?pattern"
+Same as "?*".
+.IP n
+Repeat previous search, for N-th line containing the last pattern.
+If the previous search was modified by \(haN, the search is made for the
+N-th line NOT containing the pattern.
+If the previous search was modified by \(haE, the search continues
+in the next (or previous) file if not satisfied in the current file.
+If the previous search was modified by \(haR, the search is done
+without using regular expressions.
+There is no effect if the previous search was modified by \(haF or \(haK.
+.IP N
+Repeat previous search, but in the reverse direction.
+.IP "ESC-n"
+Repeat previous search, but crossing file boundaries.
+The effect is as if the previous search were modified by *.
+.IP "ESC-N"
+Repeat previous search, but in the reverse direction
+and crossing file boundaries.
+.IP "ESC-u"
+Undo search highlighting.
+Turn off highlighting of strings matching the current search pattern.
+If highlighting is already off because of a previous ESC-u command,
+turn highlighting back on.
+Any search command will also turn highlighting back on.
+(Highlighting can also be disabled by toggling the \-G option;
+in that case search commands do not turn highlighting back on.)
+.IP "ESC-U"
+Like ESC-u but also clears the saved search pattern.
+If the status column is enabled via the \-J option,
+this clears all search matches marked in the status column.
+.IP "&pattern"
+Display only lines which match the pattern;
+lines which do not match the pattern are not displayed.
+If pattern is empty (if you type & immediately followed by ENTER),
+any filtering is turned off, and all lines are displayed.
+While filtering is in effect, an ampersand is displayed at the
+beginning of the prompt,
+as a reminder that some lines in the file may be hidden.
+Multiple & commands may be entered, in which case only lines
+which match all of the patterns will be displayed.
+.sp
+Certain characters are special as in the / command:
+.RS
+.IP "\(haN or !"
+Display only lines which do NOT match the pattern.
+.IP "\(haR"
+Don't interpret regular expression metacharacters;
+that is, do a simple textual comparison.
+.RE
+.IP ":e [filename]"
+Examine a new file.
+If the filename is missing, the "current" file (see the :n and :p commands
+below) from the list of files in the command line is re-examined.
+A percent sign (%) in the filename is replaced by the name of the
+current file.
+A pound sign (#) is replaced by the name of the previously examined file.
+However, two consecutive percent signs are simply
+replaced with a single percent sign.
+This allows you to enter a filename that contains a percent sign
+in the name.
+Similarly, two consecutive pound signs are replaced with a single pound sign.
+The filename is inserted into the command line list of files
+so that it can be seen by subsequent :n and :p commands.
+If the filename consists of several files, they are all inserted into
+the list of files and the first one is examined.
+If the filename contains one or more spaces,
+the entire filename should be enclosed in double quotes
+(also see the \-" option).
+.IP "\(haX\(haV or E"
+Same as :e.
+Warning: some systems use \(haV as a special literalization character.
+On such systems, you may not be able to use \(haV.
+.IP ":n"
+Examine the next file (from the list of files given in the command line).
+If a number N is specified, the N-th next file is examined.
+.IP ":p"
+Examine the previous file in the command line list.
+If a number N is specified, the N-th previous file is examined.
+.IP ":x"
+Examine the first file in the command line list.
+If a number N is specified, the N-th file in the list is examined.
+.IP ":d"
+Remove the current file from the list of files.
+.IP "t"
+Go to the next tag, if there were more than one matches for the current tag.
+See the \-t option for more details about tags.
+.IP "T"
+Go to the previous tag, if there were more than one matches for the current tag.
+.IP "= or \(haG or :f"
+Prints some information about the file being viewed,
+including its name
+and the line number and byte offset of the bottom line being displayed.
+If possible, it also prints the length of the file,
+the number of lines in the file
+and the percent of the file above the last displayed line.
+.IP \-
+Followed by one of the command line option letters (see OPTIONS below),
+this will change the setting of that option
+and print a message describing the new setting.
+If a \(haP (CONTROL-P) is entered immediately after the dash,
+the setting of the option is changed but no message is printed.
+If the option letter has a numeric value (such as \-b or \-h),
+or a string value (such as \-P or \-t),
+a new value may be entered after the option letter.
+If no new value is entered, a message describing
+the current setting is printed and nothing is changed.
+.IP \-\-
+Like the \- command, but takes a long option name (see OPTIONS below)
+rather than a single option letter.
+You must press ENTER or RETURN after typing the option name.
+A \(haP immediately after the second dash suppresses printing of a
+message describing the new setting, as in the \- command.
+.IP \-+
+Followed by one of the command line option letters
+this will reset the option to its default setting
+and print a message describing the new setting.
+(The "\-+\fIX\fP" command does the same thing
+as "\-+\fIX\fP" on the command line.)
+This does not work for string-valued options.
+.IP \-\-+
+Like the \-+ command, but takes a long option name
+rather than a single option letter.
+.IP \-!
+Followed by one of the command line option letters,
+this will reset the option to the "opposite" of its default setting
+and print a message describing the new setting.
+This does not work for numeric or string-valued options.
+.IP \-\-!
+Like the \-!\& command, but takes a long option name
+rather than a single option letter.
+.IP _
+(Underscore.)
+Followed by one of the command line option letters,
+this will print a message describing the current setting of that option.
+The setting of the option is not changed.
+.IP __
+(Double underscore.)
+Like the _ (underscore) command, but takes a long option name
+rather than a single option letter.
+You must press ENTER or RETURN after typing the option name.
+.IP +cmd
+Causes the specified cmd to be executed each time a new file is examined.
+For example, +G causes
+.B less
+to initially display each file starting at the end
+rather than the beginning.
+.IP V
+Prints the version number of
+.B less
+being run.
+.IP "q or Q or :q or :Q or ZZ"
+Exits
+.BR less .
+.PP
+The following
+six
+commands may or may not be valid, depending on your particular installation.
+.
+.IP v
+Invokes an editor to edit the current file being viewed.
+The editor is taken from the environment variable VISUAL if defined,
+or EDITOR if VISUAL is not defined,
+or defaults to "vi" if neither VISUAL nor EDITOR is defined.
+See also the discussion of LESSEDIT under the section on PROMPTS below.
+.IP "! shell-command"
+Invokes a shell to run the shell-command given.
+A percent sign (%) in the command is replaced by the name of the
+current file.
+A pound sign (#) is replaced by the name of the previously examined file.
+"!!" repeats the last shell command.
+"!" with no shell command simply invokes a shell.
+On Unix systems, the shell is taken from the environment variable SHELL,
+or defaults to "sh".
+On MS-DOS and OS/2 systems, the shell is the normal command processor.
+.IP "# shell-command"
+Similar to the "!" command, 
+except that the command is expanded in the same way as prompt strings.
+For example, the name of the current file would be given as "%f".
+.IP "| <m> shell-command"
+<m> represents any mark letter.
+Pipes a section of the input file to the given shell command.
+The section of the file to be piped is between the position marked by
+the letter and the current screen.
+The entire current screen is included, regardless of whether the
+marked position is before or after the current screen.
+<m> may also be \(ha or $ to indicate beginning or end of file respectively.
+If <m> is \&.\& or newline, the current screen is piped.
+.IP "s filename"
+Save the input to a file.
+This works only if the input is a pipe, not an ordinary file.
+.IP "\(haX"
+When the "Waiting for data" message is displayed,
+such as while in the F command, pressing \(haX
+will stop
+.B less
+from waiting and return to a prompt.
+This may cause
+.B less
+to think that the file ends at the current position,
+so it may be necessary to use the R or F command to see more data.
+The \-\-intr option can be used to specify a different character
+to use instead of \(haX.
+This command works only on systems that support the
+.BR poll (2)
+function.
+On systems without
+.BR poll (2),
+the interrupt character (usually \(haC) can be used instead.
+.
+.SH OPTIONS
+Command line options are described below.
+Most options may be changed while
+.B less
+is running, via the "\-" command.
+.PP
+Some options may be given in one of two forms:
+either a dash followed by a single letter,
+or two dashes followed by a long option name.
+A long option name may be abbreviated as long as
+the abbreviation is unambiguous.
+For example, \-\-quit-at-eof may be abbreviated \-\-quit, but not
+\-\-qui, since both \-\-quit-at-eof and \-\-quiet begin with \-\-qui.
+Some long option names are in uppercase, such as \-\-QUIT-AT-EOF, as
+distinct from \-\-quit-at-eof.
+Such option names need only have their first letter capitalized;
+the remainder of the name may be in either case.
+For example, \-\-Quit-at-eof is equivalent to \-\-QUIT-AT-EOF.
+.PP
+Options are also taken from the environment variable "LESS".
+For example,
+to avoid typing "less \-options \&...\&" each time
+.B less
+is invoked, you might tell
+.BR csh :
+.sp
+setenv LESS "\-options"
+.sp
+or if you use
+.BR sh :
+.sp
+LESS="\-options"; export LESS
+.sp
+On MS-DOS, you don't need the quotes, but you should replace any
+percent signs in the options string by double percent signs.
+.sp
+The environment variable is parsed before the command line,
+so command line options override the LESS environment variable.
+If an option appears in the LESS variable, it can be reset
+to its default value on the command line by beginning the command
+line option with "\-+".
+.sp
+Some options like \-k or \-D require a string to follow the option letter.
+The string for that option is considered to end when a dollar sign ($) is found.
+For example, you can set two \-D options like this:
+.sp
+LESS="Dn9.1$Ds4.1"
+.sp
+If the \-\-use-backslash option appears earlier in the options, then
+a dollar sign or backslash may be included literally in an option string
+by preceding it with a backslash.
+If the \-\-use-backslash option is not in effect, then backslashes are
+not treated specially, and there is no way to include a dollar sign
+in the option string.
+.IP "\-? or \-\-help"
+This option displays a summary of the commands accepted by
+.B less
+(the same as the h command).
+(Depending on how your shell interprets the question mark,
+it may be necessary to quote the question mark, thus: "\-\e?".)
+.IP "\-a or \-\-search-skip-screen"
+By default, forward searches start at the top of the displayed screen
+and backwards searches start at the bottom of the displayed screen
+(except for repeated searches invoked by the n or N commands,
+which start after or before the "target" line respectively;
+see the \-j option for more about the target line).
+The \-a option causes forward searches to instead start at
+the bottom of the screen
+and backward searches to start at the top of the screen,
+thus skipping all lines displayed on the screen.
+.IP "\-A or \-\-SEARCH-SKIP-SCREEN"
+Causes all forward searches (not just non-repeated searches)
+to start just after the target line, and all backward searches
+to start just before the target line.
+Thus, forward searches will skip part of the displayed screen
+(from the first line up to and including the target line).
+Similarly backwards searches will skip the displayed screen
+from the last line up to and including the target line.
+This was the default behavior in less versions prior to 441.
+.IP "\-b\fIn\fP or \-\-buffers=\fIn\fP"
+Specifies the amount of buffer space
+.B less
+will use for each file, in units of kilobytes (1024 bytes).
+By default 64\ KB of buffer space is used for each file
+(unless the file is a pipe; see the \-B option).
+The \-b option specifies instead that \fIn\fP kilobytes of
+buffer space should be used for each file.
+If \fIn\fP is \-1, buffer space is unlimited; that is,
+the entire file can be read into memory.
+.IP "\-B or \-\-auto-buffers"
+By default, when data is read from a pipe,
+buffers are allocated automatically as needed.
+If a large amount of data is read from the pipe, this can cause
+a large amount of memory to be allocated.
+The \-B option disables this automatic allocation of buffers for pipes,
+so that only 64\ KB
+(or the amount of space specified by the \-b option)
+is used for the pipe.
+Warning: use of \-B can result in erroneous display, since only the
+most recently viewed part of the piped data is kept in memory;
+any earlier data is lost.
+Lost characters are displayed as question marks.
+.IP "\-c or \-\-clear-screen"
+Causes full screen repaints to be painted from the top line down.
+By default,
+full screen repaints are done by scrolling from the bottom of the screen.
+.IP "\-C or \-\-CLEAR-SCREEN"
+Same as \-c, for compatibility with older versions of
+.BR less .
+.IP "\-d or \-\-dumb"
+The \-d option suppresses the error message
+normally displayed if the terminal is dumb;
+that is, lacks some important capability,
+such as the ability to clear the screen or scroll backward.
+The \-d option does not otherwise change the behavior of
+.B less
+on a dumb terminal.
+.IP "\-D\fBx\fP\fIcolor\fP or \-\-color=\fBx\fP\fIcolor\fP"
+Changes the color of different parts of the displayed text.
+\fBx\fP is a single character which selects the type of text 
+whose color is being set:
+.RS
+.IP "B"
+Binary characters.
+.IP "C"
+Control characters.
+.IP "E"
+Errors and informational messages.
+.IP "H"
+Header lines and columns, set via the \-\-header option.
+.IP "M"
+Mark letters in the status column.
+.IP "N"
+Line numbers enabled via the \-N option.
+.IP "P"
+Prompts.
+.IP "R"
+The rscroll character.
+.IP "S"
+Search results.
+.IP "1-5"
+The text in a search result which matches
+the first through fifth parenthesized sub-pattern.
+Sub-pattern coloring works only if
+.B less 
+is built with one of the regular expression libraries
+.BR posix ", " pcre ", or " pcre2 .
+.IP "W"
+The highlight enabled via the \-w option.
+.IP "d"
+Bold text.
+.IP "k"
+Blinking text.
+.IP "s"
+Standout text.
+.IP "u"
+Underlined text.
+.RE
+ 
+.RS
+The uppercase letters and digits can be used only when the \-\-use-color option is enabled.
+When text color is specified by both an uppercase letter and a lowercase letter,
+the uppercase letter takes precedence. 
+For example, error messages are normally displayed as standout text.
+So if both "s" and "E" are given a color, the "E" color applies
+to error messages, and the "s" color applies to other standout text.
+The "d" and "u" letters refer to bold and underline text formed by 
+overstriking with backspaces (see the \-U option), 
+not to text using ANSI escape sequences with the \-R option.
+.PP
+A lowercase letter may be followed by a + to indicate that
+the normal format change and the specified color should both be used.
+For example, \-Dug displays underlined text as green without underlining;
+the green color has replaced the usual underline formatting.
+But \-Du+g displays underlined text as both green and in underlined format.
+.PP
+\fIcolor\fP is either a 4-bit color string or an 8-bit color string:
+.PP
+A 4-bit color string is zero, one or two characters, where 
+the first character specifies the foreground color and 
+the second specifies the background color as follows:
+.IP "b"
+Blue
+.IP "c"
+Cyan
+.IP "g"
+Green
+.IP "k"
+Black
+.IP "m"
+Magenta
+.IP "r"
+Red
+.IP "w"
+White
+.IP "y"
+Yellow
+.PP
+The corresponding uppercase letter denotes a brighter shade of the color.
+For example, \-DNGk displays line numbers as bright green text on a black 
+background, and \-DEbR displays error messages as blue text on a 
+bright red background.
+If either character is a "-" or is omitted, the corresponding color 
+is set to that of normal text.
+.PP
+An 8-bit color string is one or two decimal integers separated by a dot,
+where the first integer specifies the foreground color and 
+the second specifies the background color.
+Each integer is a value between 0 and 255 inclusive which selects
+a "CSI 38;5" color value (see
+.br
+.nh
+https://en.wikipedia.org/wiki/ANSI_escape_code#SGR)
+.hy
+If either integer is a "-" or is omitted,
+the corresponding color is set to that of normal text.
+On MS-DOS versions of 
+.BR less ,
+8-bit color is not supported; instead, decimal values are interpreted as 4-bit
+CHAR_INFO.Attributes values
+(see 
+.br
+.nh
+https://docs.microsoft.com/en-us/windows/console/char-info-str).
+.hy
+.PP
+On MS-DOS only, the \-Da option may be used to specify strict parsing of 
+ANSI color (SGR) sequences when the \-R option is used.
+Without this option, sequences that change text attributes 
+(bold, underline, etc.) may clear the text color.
+.RE
+.IP "\-e or \-\-quit-at-eof"
+Causes
+.B less
+to automatically exit
+the second time it reaches end-of-file.
+By default, the only way to exit
+.B less
+is via the "q" command.
+.IP "\-E or \-\-QUIT-AT-EOF"
+Causes
+.B less
+to automatically exit the first time it reaches end-of-file.
+.IP "\-f or \-\-force"
+Forces non-regular files to be opened.
+(A non-regular file is a directory or a device special file.)
+Also suppresses the warning message when a binary file is opened.
+By default,
+.B less
+will refuse to open non-regular files.
+Note that some operating systems will not allow directories
+to be read, even if \-f is set.
+.IP "\-F or \-\-quit-if-one-screen"
+Causes
+.B less
+to automatically exit
+if the entire file can be displayed on the first screen.
+.IP "\-g or \-\-hilite-search"
+Normally,
+.B less
+will highlight ALL strings which match the last search command.
+The \-g option changes this behavior to highlight only the particular string
+which was found by the last search command.
+This can cause
+.B less
+to run somewhat faster than the default.
+.IP "\-G or \-\-HILITE-SEARCH"
+The \-G option suppresses all highlighting of strings found by search commands.
+.IP "\-h\fIn\fP or \-\-max-back-scroll=\fIn\fP"
+Specifies a maximum number of lines to scroll backward.
+If it is necessary to scroll backward more than \fIn\fP lines,
+the screen is repainted in a forward direction instead.
+(If the terminal does not have the ability to scroll
+backward, \-h0 is implied.)
+.IP "\-i or \-\-ignore-case"
+Causes searches to ignore case; that is,
+uppercase and lowercase are considered identical.
+This option is ignored if any uppercase letters
+appear in the search pattern;
+in other words,
+if a pattern contains uppercase letters, then that search does not ignore case.
+.IP "\-I or \-\-IGNORE-CASE"
+Like \-i, but searches ignore case even if
+the pattern contains uppercase letters.
+.IP "\-j\fIn\fP or \-\-jump-target=\fIn\fP"
+Specifies a line on the screen where the "target" line
+is to be positioned.
+The target line is the line specified by any command to
+search for a pattern, jump to a line number,
+jump to a file percentage or jump to a tag.
+The screen line may be specified by a number: the top line on the screen
+is 1, the next is 2, and so on.
+The number may be negative to specify a line relative to the bottom
+of the screen: the bottom line on the screen is \-1, the second
+to the bottom is \-2, and so on.
+Alternately, the screen line may be specified as a fraction of the height
+of the screen, starting with a decimal point: \&.5 is in the middle of the
+screen, \&.3 is three tenths down from the first line, and so on.
+If the line is specified as a fraction, the actual line number
+is recalculated if the terminal window is resized.
+If any form of the \-j option is used,
+repeated forward searches (invoked with "n" or "N")
+begin at the line immediately after the target line,
+and repeated backward searches begin at the target line,
+unless changed by \-a or \-A.
+For example, if "\-j4" is used, the target line is the
+fourth line on the screen, so forward searches begin at the fifth line
+on the screen.
+However nonrepeated searches (invoked with "/" or "?")
+always begin at the start or end of the current screen respectively.
+.IP "\-J or \-\-status-column"
+Displays a status column at the left edge of the screen.
+The character displayed in the status column may be one of:
+.RS
+.IP ">"
+The line is chopped with the \-S option, and 
+the text that is chopped off beyond the right edge of the screen
+contains a match for the current search.
+.IP "<"
+The line is horizontally shifted, and
+the text that is shifted beyond the left side of the screen
+contains a match for the current search.
+.IP "="
+The line is both chopped and shifted,
+and there are matches beyond both sides of the screen.
+.IP "*"
+There are matches in the visible part of the line
+but none to the right or left of it.
+.IP "a-z, A-Z"
+The line has been marked with the corresponding letter via the m command.
+.RE
+.IP "\-k\fIfilename\fP or \-\-lesskey-file=\fIfilename\fP"
+Causes
+.B less
+to open and interpret the named file as a
+.BR lesskey (1)
+binary file.
+Multiple \-k options may be specified.
+If the LESSKEY or LESSKEY_SYSTEM environment variable is set, or
+if a lesskey file is found in a standard place (see KEY BINDINGS),
+it is also used as a
+.B lesskey
+file.
+.IP "\-\-lesskey-src=\fIfilename\fP"
+Causes
+.B less
+to open and interpret the named file as a 
+.BR lesskey (1)
+source file. 
+If the LESSKEYIN or LESSKEYIN_SYSTEM environment variable is set, or
+if a lesskey source file is found in a standard place (see KEY BINDINGS),
+it is also used as a
+.I "lesskey source"
+file.
+Prior to version 582, the
+.B lesskey
+program needed to be run to convert a 
+.I "lesskey source"
+file to a 
+.I "lesskey binary"
+file for
+.B less
+to use.
+Newer versions of
+.B less
+read the
+.I "lesskey source"
+file directly and ignore the binary file if the source file exists.
+.IP "\-K or \-\-quit-on-intr"
+Causes
+.B less
+to exit immediately (with status 2)
+when an interrupt character (usually \(haC) is typed.
+Normally, an interrupt character causes
+.B less
+to stop whatever it is doing and return to its command prompt.
+Note that use of this option makes it impossible to return to the
+command prompt from the "F" command.
+.IP "\-L or \-\-no-lessopen"
+Ignore the LESSOPEN environment variable
+(see the INPUT PREPROCESSOR section below).
+This option can be set from within
+.BR less ,
+but it will apply only to files opened subsequently, not to the
+file which is currently open.
+.IP "\-m or \-\-long-prompt"
+Causes
+.B less
+to prompt verbosely (like 
+.BR more (1)),
+with the percent into the file.
+By default,
+.B less
+prompts with a colon.
+.IP "\-M or \-\-LONG-PROMPT"
+Causes
+.B less
+to prompt even more verbosely than
+.BR more (1).
+.IP "\-n or \-\-line-numbers"
+Suppresses line numbers.
+The default (to use line numbers) may cause
+.B less
+to run more slowly in some cases, especially with a very large input file.
+Suppressing line numbers with the \-n option will avoid this problem.
+Using line numbers means: the line number will be displayed in the verbose
+prompt and in the = command,
+and the v command will pass the current line number to the editor
+(see also the discussion of LESSEDIT in PROMPTS below).
+.IP "\-N or \-\-LINE-NUMBERS"
+Causes a line number to be displayed at the beginning of
+each line in the display.
+.IP "\-o\fIfilename\fP or \-\-log-file=\fIfilename\fP"
+Causes
+.B less
+to copy its input to the named file as it is being viewed.
+This applies only when the input file is a pipe,
+not an ordinary file.
+If the file already exists,
+.B less
+will ask for confirmation before overwriting it.
+.IP "\-O\fIfilename\fP or \-\-LOG-FILE=\fIfilename\fP"
+The \-O option is like \-o, but it will overwrite an existing
+file without asking for confirmation.
+.sp
+If no log file has been specified,
+the \-o and \-O options can be used from within
+.B less
+to specify a log file.
+Without a file name, they will simply report the name of the log file.
+The "s" command is equivalent to specifying \-o from within
+.BR less .
+.IP "\-p\fIpattern\fP or \-\-pattern=\fIpattern\fP"
+The \-p option on the command line is equivalent to
+specifying +/\fIpattern\fP;
+that is, it tells
+.B less
+to start at the first occurrence of \fIpattern\fP in the file.
+.IP "\-P\fIprompt\fP or \-\-prompt=\fIprompt\fP"
+Provides a way to tailor the three prompt
+styles to your own preference.
+This option would normally be put in the LESS environment
+variable, rather than being typed in with each
+.B less
+command.
+Such an option must either be the last option in the LESS variable,
+or be terminated by a dollar sign.
+ \-Ps followed by a string changes the default (short) prompt
+to that string.
+ \-Pm changes the medium (\-m) prompt.
+ \-PM changes the long (\-M) prompt.
+ \-Ph changes the prompt for the help screen.
+ \-P= changes the message printed by the = command.
+ \-Pw changes the message printed while waiting for data (in the "F" command).
+.sp 1
+All prompt strings consist of a sequence of
+letters and special escape sequences.
+See the section on PROMPTS for more details.
+.IP "\-q or \-\-quiet or \-\-silent"
+Causes moderately "quiet" operation:
+the terminal bell is not rung
+if an attempt is made to scroll past the end of the file
+or before the beginning of the file.
+If the terminal has a "visual bell", it is used instead.
+The bell will be rung on certain other errors,
+such as typing an invalid character.
+The default is to ring the terminal bell in all such cases.
+.IP "\-Q or \-\-QUIET or \-\-SILENT"
+Causes totally "quiet" operation:
+the terminal bell is never rung.
+If the terminal has a "visual bell", it is used in all cases
+where the terminal bell would have been rung.
+.IP "\-r or \-\-raw-control-chars"
+Causes "raw" control characters to be displayed.
+The default is to display control characters using the caret notation;
+for example, a control-A (octal 001) is displayed as "\(haA"
+(with some exceptions as described under the \-U option).
+Warning: when the \-r option is used,
+.B less
+cannot keep track of the actual appearance of the screen
+(since this depends on how the screen responds to
+each type of control character).
+Thus, various display problems may result,
+such as long lines being split in the wrong place.
+.sp
+USE OF THE \-r OPTION IS NOT RECOMMENDED.
+.IP "\-R or \-\-RAW-CONTROL-CHARS"
+Like \-r, but only ANSI "color" escape sequences and OSC 8 hyperlink
+sequences are output in "raw" form.
+Unlike \-r, the screen appearance is maintained correctly,
+provided that there are no escape sequences in the file 
+other than these types of escape sequences.
+Color escape sequences are only supported when the color
+is changed within one line, not across lines. 
+In other words, the beginning of each line is assumed to be
+normal (non-colored), regardless of any escape sequences in previous lines.
+For the purpose of keeping track of screen appearance,
+these escape sequences are assumed to not move the cursor.
+.sp
+OSC 8 hyperlinks are sequences of the form:
+.sp
+	ESC ] 8 ; \&...\& \\7
+.sp
+The terminating sequence may be either a BEL character (\\7) 
+or the two-character sequence "ESC \\".
+.sp
+ANSI color escape sequences are sequences of the form:
+.sp
+	ESC [ \&...\& m
+.sp
+where the "...\&" is zero or more color specification characters.
+You can make
+.B less
+think that characters other than "m" can end ANSI color escape sequences
+by setting the environment variable LESSANSIENDCHARS to the list of
+characters which can end a color escape sequence.
+And you can make
+.B less
+think that characters other than the standard ones may appear between
+the ESC and the m by setting the environment variable LESSANSIMIDCHARS
+to the list of characters which can appear.
+.IP "\-s or \-\-squeeze-blank-lines"
+Causes consecutive blank lines to be squeezed into a single blank line.
+This is useful when viewing
+.B nroff
+output.
+.IP "\-S or \-\-chop-long-lines"
+Causes lines longer than the screen width to be
+chopped (truncated) rather than wrapped.
+That is, the portion of a long line that does not fit in
+the screen width is not displayed until you press RIGHT-ARROW.
+The default is to wrap long lines; that is, display the remainder
+on the next line.
+See also the \-\-wordwrap option.
+.IP "\-t\fItag\fP or \-\-tag=\fItag\fP"
+The \-t option, followed immediately by a TAG,
+will edit the file containing that tag.
+For this to work, tag information must be available;
+for example, there may be a file in the current directory called "tags",
+which was previously built by
+.BR ctags (1)
+or an equivalent command.
+If the environment variable LESSGLOBALTAGS is set, it is taken to be
+the name of a command compatible with
+.BR global (1),
+and that command is executed to find the tag.
+(See 
+.nh
+http://www.gnu.org/software/global/global.html).
+.hy
+The \-t option may also be specified from within
+.B less
+(using the \- command) as a way of examining a new file.
+The command ":t" is equivalent to specifying \-t from within
+.BR less .
+.IP "\-T\fItagsfile\fP or \-\-tag-file=\fItagsfile\fP"
+Specifies a tags file to be used instead of "tags".
+.IP "\-u or \-\-underline-special"
+Causes backspaces and carriage returns to be treated as printable characters;
+that is, they are sent to the terminal when they appear in the input.
+.IP "\-U or \-\-UNDERLINE-SPECIAL"
+Causes backspaces, tabs, carriage returns and "formatting characters"
+(as defined by Unicode) to be treated as control characters;
+that is, they are handled as specified by the \-r option.
+.sp
+By default, if neither \-u nor \-U is given,
+backspaces which appear adjacent to an underscore character
+are treated specially:
+the underlined text is displayed
+using the terminal's hardware underlining capability.
+Also, backspaces which appear between two identical characters
+are treated specially:
+the overstruck text is printed
+using the terminal's hardware boldface capability.
+Other backspaces are deleted, along with the preceding character.
+Carriage returns immediately followed by a newline are deleted.
+Other carriage returns are handled as specified by the \-r option.
+Unicode formatting characters, such as the Byte Order Mark,
+are sent to the terminal.
+Text which is overstruck or underlined can be searched for
+if neither \-u nor \-U is in effect.
+.sp
+See also the \-\-proc-backspace, \-\-proc-tab,
+and \-\-proc-return options.
+.IP "\-V or \-\-version"
+Displays the version number of
+.BR less .
+.IP "\-w or \-\-hilite-unread"
+Temporarily highlights the first "new" line after a forward movement
+of a full page.
+The first "new" line is the line immediately following the line previously
+at the bottom of the screen.
+Also highlights the target line after a g or p command.
+The highlight is removed at the next command which causes movement.
+If the \-\-status-line option is in effect, the entire line
+(the width of the screen) is highlighted.
+Otherwise, only the text in the line is highlighted,
+unless the \-J option is in effect,
+in which case only the status column is highlighted.
+.IP "\-W or \-\-HILITE-UNREAD"
+Like \-w, but temporarily highlights the first new line after any
+forward movement command larger than one line.
+.IP "\-x\fIn\fP,...\& or \-\-tabs=\fIn\fP,..."
+Sets tab stops.
+If only one \fIn\fP is specified, tab stops are set at multiples of \fIn\fP.
+If multiple values separated by commas are specified, tab stops
+are set at those positions, and then continue with the same spacing as the
+last two.
+For example, "-x9,17" will set tabs at positions 9, 17, 25, 33, etc.
+The default for \fIn\fP is 8.
+.IP "\-X or \-\-no-init"
+Disables sending the termcap initialization and deinitialization strings
+to the terminal.
+This is sometimes desirable if the deinitialization string does
+something unnecessary, like clearing the screen.
+.IP "\-y\fIn\fP or \-\-max-forw-scroll=\fIn\fP"
+Specifies a maximum number of lines to scroll forward.
+If it is necessary to scroll forward more than \fIn\fP lines,
+the screen is repainted instead.
+The \-c or \-C option may be used to repaint from the top of
+the screen if desired.
+By default, any forward movement causes scrolling.
+.IP "\-z\fIn\fP or \-\-window=\fIn\fP or \-\fIn\fP"
+Changes the default scrolling window size to \fIn\fP lines.
+The default is one screenful.
+The z and w commands can also be used to change the window size.
+The "z" may be omitted for compatibility with some versions of
+.BR more (1).
+If the number
+.I n
+is negative, it indicates
+.I n
+lines less than the current screen size.
+For example, if the screen is 24 lines, \fI\-z\-4\fP sets the
+scrolling window to 20 lines.  If the screen is resized to 40 lines,
+the scrolling window automatically changes to 36 lines.
+.IP "\-\(dq\fIcc\fP\ or\ \-\-quotes=\fIcc\fP"
+Changes the filename quoting character.
+This may be necessary if you are trying to name a file
+which contains both spaces and quote characters.
+Followed by a single character, this changes the quote character to that
+character.
+Filenames containing a space should then be surrounded by that character
+rather than by double quotes.
+Followed by two characters, changes the open quote to the first character,
+and the close quote to the second character.
+Filenames containing a space should then be preceded by the open quote
+character and followed by the close quote character.
+Note that even after the quote characters are changed, this option
+remains \-" (a dash followed by a double quote).
+.IP "\-\(ti or \-\-tilde"
+Normally lines after end of file are displayed as a single tilde (\(ti).
+This option causes lines after end of file to be displayed as blank lines.
+.IP "\-# or \-\-shift"
+Specifies the default number of positions to scroll horizontally
+in the RIGHTARROW and LEFTARROW commands.
+If the number specified is zero, it sets the default number of
+positions to one half of the screen width.
+Alternately, the number may be specified as a fraction of the width
+of the screen, starting with a decimal point: \&.5 is half of the
+screen width, \&.3 is three tenths of the screen width, and so on.
+If the number is specified as a fraction, the actual number of
+scroll positions is recalculated if the terminal window is resized.
+.IP "\-\-exit-follow-on-close"
+When using the "F" command on a pipe,
+.B less
+will automatically stop waiting for more data when the input side of the 
+pipe is closed.
+.IP "\-\-file-size"
+If \-\-file-size is specified,
+.B less
+will determine the size of the file 
+immediately after opening the file.
+Then the "=" command will display the number of lines in the file.
+Normally this is not done, because it can be slow if the input file 
+is non-seekable (such as a pipe) and is large.
+.IP "\-\-follow-name"
+Normally, if the input file is renamed while an F command is executing,
+.B less
+will continue to display the contents of the original file despite
+its name change.
+If \-\-follow-name is specified, during an F command
+.B less
+will periodically attempt to reopen the file by name.
+If the reopen succeeds and the file is a different file from the original
+(which means that a new file has been created
+with the same name as the original (now renamed) file),
+.B less
+will display the contents of that new file.
+.IP "\-\-header=\fIN[,M]\fP"
+Sets the number of header lines and columns displayed on the screen.
+The value may be of the form "N,M" where N and M are integers,
+to set the header lines to N and the header columns to M,
+or it may be a single integer "N" which sets the header lines to N 
+and the header columns to zero,
+or it may be ",M" which sets the header columns to M and the 
+header lines to zero.
+When N is nonzero, the first N lines at the top
+of the screen are replaced with the first N lines of the file,
+regardless of what part of the file are being viewed.
+When M is nonzero, the characters displayed at the 
+beginning of each line are replaced with the first M characters of the line,
+even if the rest of the line is scrolled horizontally.
+If either N or M is zero, 
+.B less
+stops displaying header lines or columns, respectively.
+(Note that it may be necessary to change the setting of the \-j option
+to ensure that the target line is not obscured by the header line(s).)
+.IP "\-\-incsearch"
+Subsequent search commands will be "incremental"; that is,
+.B less
+will advance to the next line containing the search pattern 
+as each character of the pattern is typed in.
+.IP "\-\-intr=\fIc\fP"
+Use the character \fIc\fP instead of \(haX to interrupt a read
+when the "Waiting for data" message is displayed.
+\fIc\fP must be an ASCII character; that is, one with a value 
+between 1 and 127 inclusive.
+A caret followed by a single character can be used 
+to specify a control character.
+.IP "\-\-line-num-width=\fIn\fP"
+Sets the minimum width of the line number field when the \-N option is in effect 
+to \fIn\fP characters.
+The default is 7.
+.IP "\-\-modelines=\fIn\fP"
+.RS
+Before displaying a file,
+.B less 
+will read the first \fIn\fP lines to try to find a vim-compatible 
+.IR modeline . 
+If \fIn\fP is zero,
+.B less
+does not try to find modelines.
+By using a modeline, the file itself can specify the tab stops 
+that should be used when viewing it.
+.PP
+A modeline contains, anywhere in the line, 
+a program name ("vi", "vim", "ex", or "less"),
+followed by a colon,
+possibly followed by the word "set",
+and finally followed by zero or more option settings.
+If the word "set" is used,
+option settings are separated by spaces, and end at the first colon.
+If the word "set" is not used, 
+option settings may be separated by either spaces or colons.
+The word "set" is required if the program name is "less"
+but optional if any of the other three names are used.
+If any option setting is of the form "tabstop=\fIn\fP" or "ts=\fIn\fP",
+then tab stops are automatically set as if \-\-tabs=\fIn\fP had been given.
+See the \-\-tabs description for acceptable values of \fIn\fP.
+.RE
+.IP "\-\-mouse"
+Enables mouse input:
+scrolling the mouse wheel down moves forward in the file,
+scrolling the mouse wheel up moves backwards in the file,
+and clicking the mouse sets the "#" mark to the line
+where the mouse is clicked.
+The number of lines to scroll when the wheel is moved
+can be set by the \-\-wheel-lines option.
+Mouse input works only on terminals which support X11 mouse reporting,
+and on the Windows version of
+.BR less .
+.IP "\-\-MOUSE"
+Like \-\-mouse, except the direction scrolled
+on mouse wheel movement is reversed.
+.IP "\-\-no-keypad"
+Disables sending the keypad initialization and deinitialization strings
+to the terminal.
+This is sometimes useful if the keypad strings make the numeric
+keypad behave in an undesirable manner.
+.IP "\-\-no-histdups"
+This option changes the behavior so that if a search string or
+file name is typed in, and the same string is already in the history list,
+the existing copy is removed from the history list before the new one is added.
+Thus, a given string will appear only once in the history list.
+Normally, a string may appear multiple times.
+.IP "\-\-no-number-headers"
+Header lines (defined via the \-\-header option) are not assigned line numbers.
+Line number 1 is assigned to the first line after any header lines.
+.IP "\-\-no-search-headers"
+Searches do not include header lines or header columns.
+.IP "\-\-no-vbell"
+Disables the terminal's visual bell.
+.IP "\-\-proc-backspace"
+If set, backspaces are handled as if neither the \-u option 
+nor the \-U option were set.
+That is, a backspace adjacent to an underscore causes text to be
+displayed in underline mode, and a backspace between identical
+characters cause text to be displayed in boldface mode.
+This option overrides the \-u and \-U options, so that display of
+backspaces can be controlled separate from tabs and carriage returns.
+If not set, backspace display is controlled by the \-u and \-U options.
+.IP "\-\-PROC-BACKSPACE"
+If set, backspaces are handled as if the \-U option were set;
+that is backspaces are treated as control characters.
+.IP "\-\-proc-return"
+If set, carriage returns are handled as if neither the \-u option 
+nor the \-U option were set.
+That is, a carriage return immediately before a newline is deleted.
+This option overrides the \-u and \-U options, so that display of
+carriage returns can be controlled separate from that of backspaces and tabs.
+If not set, carriage return display is controlled by the \-u and \-U options.
+.IP "\-\-PROC-RETURN"
+If set, carriage returns are handled as if the \-U option were set;
+that is carriage returns are treated as control characters.
+.IP "\-\-proc-tab"
+If set, tabs are handled as if the \-U option were not set.
+That is, tabs are expanded to spaces.
+This option overrides the \-U option, so that display of
+tabs can be controlled separate from that of backspaces and carriage returns.
+If not set, tab display is controlled by the \-U options.
+.IP "\-\-PROC-TAB"
+If set, tabs are handled as if the \-U option were set;
+that is tabs are treated as control characters.
+.IP "\-\-redraw-on-quit"
+When quitting, after sending the terminal deinitialization string,
+redraws the entire last screen.
+On terminals whose terminal deinitialization string causes the
+terminal to switch from an alternate screen, 
+this makes the last screenful of the current file remain visible after
+.B less
+has quit.
+.IP "\-\-rscroll=\fIc\fP"
+This option changes the character used to mark truncated lines.
+It may begin with a two-character attribute indicator like LESSBINFMT does.
+If there is no attribute indicator, standout is used.
+If set to "\-", truncated lines are not marked.
+.IP "\-\-save-marks"
+Save marks in the history file, so marks are retained
+across different invocations of
+.BR less .
+.IP "\-\-search-options=\fI...\fP"
+Sets default search modifiers. 
+The value is a string of one or more of the characters
+E, F, K, N, R or W.
+Setting any of these has the same effect as typing that
+control character at the beginning of every search pattern.
+For example, setting \-\-search-options=W is the same as
+typing \(haW at the beginning of every pattern.
+The value may also contain a digit between 1 and 5,
+which has the same effect as typing \(haS followed by that digit
+at the beginning of every search pattern.
+The value "-" disables all default search modifiers.
+.IP "\-\-show-preproc-errors"
+If a preprocessor produces data, 
+then exits with a non-zero exit code,
+.B less
+will display a warning.
+.IP "\-\-status-col-width=\fIn\fP"
+Sets the width of the status column when the \-J option is in effect.
+The default is 2 characters.
+.IP "\-\-status-line"
+If a line is marked, the entire line (rather than just the status column)
+is highlighted.
+Also lines highlighted due to the \-w option will have
+the entire line highlighted.
+If \-\-use-color is set, the line is colored rather than highlighted.
+.IP "\-\-use-backslash"
+This option changes the interpretations of options which follow this one.
+After the \-\-use-backslash option, any backslash in an option string is
+removed and the following character is taken literally.
+This allows a dollar sign to be included in option strings.
+.IP "\-\-use-color"
+Enables colored text in various places.
+The \-D option can be used to change the colors.
+Colored text works only if the terminal supports 
+ANSI color escape sequences (as defined in ECMA-48 SGR;
+see 
+.br
+.nh
+https://www.ecma-international.org/publications-and-standards/standards/ecma-48).
+.hy
+.IP "\-\-wheel-lines=\fIn\fP"
+Set the number of lines to scroll when the mouse wheel is scrolled
+and the \-\-mouse or \-\-MOUSE option is in effect.
+The default is 1 line.
+.IP "\-\-wordwrap"
+When the \-S option is not in use,
+wrap each line at a space or tab if possible,
+so that a word is not split between two lines.
+The default is to wrap at any character.
+.IP \-\-
+A command line argument of "\-\-" marks the end of option arguments.
+Any arguments following this are interpreted as filenames.
+This can be useful when viewing a file whose name begins with a "\-" or "+".
+.IP +
+If a command line option begins with \fB+\fP,
+the remainder of that option is taken to be an initial command to
+.BR less .
+For example, +G tells
+.B less
+to start at the end of the file rather than the beginning,
+and +/xyz tells it to start at the first occurrence of "xyz" in the file.
+As a special case, +<number> acts like +<number>g;
+that is, it starts the display at the specified line number
+(however, see the caveat under the "g" command above).
+If the option starts with ++, the initial command applies to
+every file being viewed, not just the first one.
+The + command described previously
+may also be used to set (or change) an initial command for every file.
+.
+.SH "LINE EDITING"
+When entering a command line at the bottom of the screen
+(for example, a filename for the :e command,
+or the pattern for a search command),
+certain keys can be used to manipulate the command line.
+Most commands have an alternate form in [ brackets ] which can be used if
+a key does not exist on a particular keyboard.
+(Note that the forms beginning with ESC do not work
+in some MS-DOS and Windows systems because ESC is the line erase character.)
+Any of these special keys may be entered literally by preceding
+it with the "literal" character, either \(haV or \(haA.
+A backslash itself may also be entered literally by entering two backslashes.
+.IP "LEFTARROW [ ESC-h ]"
+Move the cursor one space to the left.
+.IP "RIGHTARROW [ ESC-l ]"
+Move the cursor one space to the right.
+.IP "\(haLEFTARROW [ ESC-b or ESC-LEFTARROW ]"
+(That is, CONTROL and LEFTARROW simultaneously.)
+Move the cursor one word to the left.
+.IP "\(haRIGHTARROW [ ESC-w or ESC-RIGHTARROW ]"
+(That is, CONTROL and RIGHTARROW simultaneously.)
+Move the cursor one word to the right.
+.IP "HOME [ ESC-0 ]"
+Move the cursor to the beginning of the line.
+.IP "END [ ESC-$ ]"
+Move the cursor to the end of the line.
+.IP "BACKSPACE"
+Delete the character to the left of the cursor,
+or cancel the command if the command line is empty.
+.IP "DELETE or [ ESC-x ]"
+Delete the character under the cursor.
+.IP "\(haBACKSPACE [ ESC-BACKSPACE ]"
+(That is, CONTROL and BACKSPACE simultaneously.)
+Delete the word to the left of the cursor.
+.IP "\(haDELETE [ ESC-X or ESC-DELETE ]"
+(That is, CONTROL and DELETE simultaneously.)
+Delete the word under the cursor.
+.IP "UPARROW [ ESC-k ]"
+Retrieve the previous command line.
+If you first enter some text and then press UPARROW,
+it will retrieve the previous command which begins with that text.
+.IP "DOWNARROW [ ESC-j ]"
+Retrieve the next command line.
+If you first enter some text and then press DOWNARROW,
+it will retrieve the next command which begins with that text.
+.IP "TAB"
+Complete the partial filename to the left of the cursor.
+If it matches more than one filename, the first match
+is entered into the command line.
+Repeated TABs will cycle thru the other matching filenames.
+If the completed filename is a directory, a "/" is appended to the filename.
+(On MS-DOS systems, a "\e" is appended.)
+The environment variable LESSSEPARATOR can be used to specify a
+different character to append to a directory name.
+.IP "BACKTAB [ ESC-TAB ]"
+Like, TAB, but cycles in the reverse direction thru the matching filenames.
+.IP "\(haL"
+Complete the partial filename to the left of the cursor.
+If it matches more than one filename, all matches are entered into
+the command line (if they fit).
+.IP "\(haU (Unix and OS/2) or ESC (MS-DOS)"
+Delete the entire command line,
+or cancel the command if the command line is empty.
+If you have changed your line-kill character in Unix to something
+other than \(haU, that character is used instead of \(haU.
+.IP "\(haG"
+Delete the entire command line and return to the main prompt.
+.
+.SH "KEY BINDINGS"
+You may define your own
+.B less
+commands by creating a lesskey source file.
+This file specifies a set of command keys and an action
+associated with each key.
+You may also change the line-editing keys (see LINE EDITING),
+and set environment variables used by
+.BR less .
+See the
+.BR lesskey (1)
+manual page for details about the file format.
+.PP
+If the environment variable LESSKEYIN is set,
+.B less
+uses that as the name of the lesskey source file.
+Otherwise,
+.B less
+looks in a standard place for the lesskey source file:
+On Unix systems,
+.B less
+looks for a lesskey file called "$XDG_CONFIG_HOME/lesskey" or "$HOME/.config/lesskey" or "$HOME/.lesskey".
+On MS-DOS and Windows systems,
+.B less
+looks for a lesskey file called "$HOME/_lesskey", and if it is not found there,
+then looks for a lesskey file called "_lesskey" in any directory specified
+in the PATH environment variable.
+On OS/2 systems,
+.B less
+looks for a lesskey file called "$HOME/lesskey.ini", and if it is not found,
+then looks for a lesskey file called "lesskey.ini" in any directory specified
+in the INIT environment variable, and if it not found there,
+then looks for a lesskey file called "lesskey.ini" in any directory specified
+in the PATH environment variable.
+.PP
+A system-wide lesskey source file may also be set up to provide key bindings.
+If a key is defined in both a local lesskey file and in the
+system-wide file, key bindings in the local file take precedence over
+those in the system-wide file.
+If the environment variable LESSKEYIN_SYSTEM is set,
+.B less
+uses that as the name of the system-wide lesskey file.
+Otherwise,
+.B less
+looks in a standard place for the system-wide lesskey file:
+On Unix systems, the system-wide lesskey file is /usr/local/etc/syslesskey.
+(However, if
+.B less
+was built with a different sysconf directory than /usr/local/etc,
+that directory is where the sysless file is found.)
+On MS-DOS and Windows systems, the system-wide lesskey file is c:\e_syslesskey.
+On OS/2 systems, the system-wide lesskey file is c:\esyslesskey.ini.
+.PP
+Previous versions of
+.B less
+(before v582) used lesskey files with a binary format, produced by the
+.B lesskey
+program. It is no longer necessary to use the
+.B lesskey
+program.
+.
+.SH "INPUT PREPROCESSOR"
+You may define an "input preprocessor" for
+.BR less .
+Before
+.B less
+opens a file, it first gives your input preprocessor a chance to modify the
+way the contents of the file are displayed.
+An input preprocessor is simply an executable program (or shell script),
+which writes the contents of the file to a different file,
+called the replacement file.
+The contents of the replacement file are then displayed
+in place of the contents of the original file.
+However, it will appear to the user as if the original file is opened;
+that is,
+.B less
+will display the original filename as the name of the current file.
+.PP
+An input preprocessor receives one command line argument, the original filename,
+as entered by the user.
+It should create the replacement file, and when finished,
+print the name of the replacement file to its standard output.
+If the input preprocessor does not output a replacement filename,
+.B less
+uses the original file, as normal.
+The input preprocessor is not called when viewing standard input.
+To set up an input preprocessor, set the LESSOPEN environment variable
+to a command line which will invoke your input preprocessor.
+This command line should include one occurrence of the string "%s",
+which will be replaced by the filename
+when the input preprocessor command is invoked.
+.PP
+When
+.B less
+closes a file opened in such a way, it will call another program,
+called the input postprocessor,
+which may perform any desired clean-up action (such as deleting the
+replacement file created by LESSOPEN).
+This program receives two command line arguments, the original filename
+as entered by the user, and the name of the replacement file.
+To set up an input postprocessor, set the LESSCLOSE environment variable
+to a command line which will invoke your input postprocessor.
+It may include two occurrences of the string "%s";
+the first is replaced with the original name of the file and
+the second with the name of the replacement file,
+which was output by LESSOPEN.
+.PP
+For example, on many Unix systems, these two scripts will allow you
+to keep files in compressed format, but still let
+.B less
+view them directly:
+.PP
+lessopen.sh:
+.br
+	#! /bin/sh
+.br
+	case "$1" in
+.br
+	*.Z)	TEMPFILE=$(mktemp)
+.br
+		uncompress \-c $1  >$TEMPFILE  2>/dev/null
+.br
+		if [ \-s $TEMPFILE ]; then
+.br
+			echo $TEMPFILE
+.br
+		else
+.br
+			rm \-f $TEMPFILE
+.br
+		fi
+.br
+		;;
+.br
+	esac
+.PP
+lessclose.sh:
+.br
+	#! /bin/sh
+.br
+	rm $2
+.PP
+To use these scripts, put them both where they can be executed and
+set LESSOPEN="lessopen.sh\ %s", and
+LESSCLOSE="lessclose.sh\ %s\ %s".
+More complex LESSOPEN and LESSCLOSE scripts may be written
+to accept other types of compressed files, and so on.
+.PP
+It is also possible to set up an input preprocessor to
+pipe the file data directly to
+.BR less ,
+rather than putting the data into a replacement file.
+This avoids the need to decompress the entire file before
+starting to view it.
+An input preprocessor that works this way is called an input pipe.
+An input pipe, instead of writing the name of a replacement file on
+its standard output,
+writes the entire contents of the replacement file on its standard output.
+If the input pipe does not write any characters on its standard output,
+then there is no replacement file and
+.B less
+uses the original file, as normal.
+To use an input pipe,
+make the first character in the LESSOPEN environment variable a
+vertical bar (|) to signify that the input preprocessor is an input pipe.
+As with non-pipe input preprocessors, the command string must contain one
+occurrence of %s, which is replaced with the filename of the input file.
+.PP
+For example, on many Unix systems, this script will work like the
+previous example scripts:
+.PP
+lesspipe.sh:
+.br
+	#! /bin/sh
+.br
+	case "$1" in
+.br
+	*.Z)	uncompress \-c $1  2>/dev/null
+.br
+		;;
+.br
+	*)	exit 1
+.br
+		;;
+.br
+	esac
+.br
+	exit $?
+.br
+.PP
+To use this script, put it where it can be executed and set
+LESSOPEN="|lesspipe.sh %s".
+.PP
+Note that a preprocessor cannot output an empty file, since that
+is interpreted as meaning there is no replacement, and
+the original file is used.
+To avoid this, if LESSOPEN starts with two vertical bars,
+the exit status of the script determines the behavior when the output is empty.
+If the output is empty and the exit status is zero, 
+the empty output is considered to be replacement text.
+If the output is empty and the exit status is nonzero, 
+the original file is used.
+For compatibility with previous versions of
+.BR less ,
+if LESSOPEN starts with only one vertical bar, the exit status
+of the preprocessor is ignored.
+.PP
+When an input pipe is used, a LESSCLOSE postprocessor can be used,
+but it is usually not necessary since there is no replacement file
+to clean up.
+In this case, the replacement file name passed to the LESSCLOSE
+postprocessor is "\-".
+.PP
+For compatibility with previous versions of
+.BR less ,
+the input preprocessor or pipe is not used if
+.B less
+is viewing standard input.
+However, if the first character of LESSOPEN is a dash (\-),
+the input preprocessor is used on standard input as well as other files.
+In this case, the dash is not considered to be part of
+the preprocessor command.
+If standard input is being viewed, the input preprocessor is passed
+a file name consisting of a single dash.
+Similarly, if the first two characters of LESSOPEN are vertical bar and dash
+(|\-) or two vertical bars and a dash (||\-),
+the input pipe is used on standard input as well as other files.
+Again, in this case the dash is not considered to be part of
+the input pipe command.
+.
+.SH "NATIONAL CHARACTER SETS"
+There are three types of characters in the input file:
+.IP "normal characters"
+can be displayed directly to the screen.
+.IP "control characters"
+should not be displayed directly, but are expected to be found
+in ordinary text files (such as backspace and tab).
+.IP "binary characters"
+should not be displayed directly and are not expected to be found
+in text files.
+.PP
+A "character set" is simply a description of which characters are to
+be considered normal, control, and binary.
+The LESSCHARSET environment variable may be used to select a character set.
+Possible values for LESSCHARSET are:
+.IP ascii
+BS, TAB, NL, CR, and formfeed are control characters,
+all chars with values between 32 and 126 are normal,
+and all others are binary.
+.IP iso8859
+Selects an ISO 8859 character set.
+This is the same as ASCII, except characters between 160 and 255 are
+treated as normal characters.
+.IP latin1
+Same as iso8859.
+.IP latin9
+Same as iso8859.
+.IP dos
+Selects a character set appropriate for MS-DOS.
+.IP ebcdic
+Selects an EBCDIC character set.
+.IP IBM-1047
+Selects an EBCDIC character set used by OS/390 Unix Services.
+This is the EBCDIC analogue of latin1.  You get similar results
+by setting either LESSCHARSET=IBM-1047 or LC_CTYPE=en_US
+in your environment.
+.IP koi8-r
+Selects a Russian character set.
+.IP next
+Selects a character set appropriate for NeXT computers.
+.IP utf-8
+Selects the UTF-8 encoding of the ISO 10646 character set.
+UTF-8 is special in that it supports multi-byte characters in the input file.
+It is the only character set that supports multi-byte characters.
+.IP windows
+Selects a character set appropriate for Microsoft Windows (cp 1251).
+.PP
+In rare cases, it may be desired to tailor
+.B less
+to use a character set other than the ones definable by LESSCHARSET.
+In this case, the environment variable LESSCHARDEF can be used
+to define a character set.
+It should be set to a string where each character in the string represents
+one character in the character set.
+The character ".\&" is used for a normal character, "c" for control,
+and "b" for binary.
+A decimal number may be used for repetition.
+For example, "bccc4b.\&" would mean character 0 is binary,
+1, 2 and 3 are control, 4, 5, 6 and 7 are binary, and 8 is normal.
+All characters after the last are taken to be the same as the last,
+so characters 9 through 255 would be normal.
+(This is an example, and does not necessarily
+represent any real character set.)
+.PP
+This table shows the value of LESSCHARDEF which is equivalent
+to each of the possible values for LESSCHARSET:
+.
+.RS 5m
+.TS
+l l.
+ascii	8bcccbcc18b95.b
+dos	8bcccbcc12bc5b95.b.
+ebcdic	5bc6bcc7bcc41b.9b7.9b5.b..8b6.10b6.b9.7b
+	9.8b8.17b3.3b9.7b9.8b8.6b10.b.b.b.
+IBM-1047	4cbcbc3b9cbccbccbb4c6bcc5b3cbbc4bc4bccbc
+	191.b
+iso8859	8bcccbcc18b95.33b.
+koi8-r	8bcccbcc18b95.b128.
+latin1	8bcccbcc18b95.33b.
+next	8bcccbcc18b95.bb125.bb
+.TE
+.RE
+.PP
+If neither LESSCHARSET nor LESSCHARDEF is set,
+but any of the strings "UTF-8", "UTF8", "utf-8" or "utf8"
+is found in the LC_ALL, LC_CTYPE or LANG
+environment variables, then the default character set is utf-8.
+.PP
+If that string is not found, but your system supports the
+.B setlocale
+interface,
+.B less
+will use setlocale to determine the character set.
+setlocale is controlled by setting the LANG or LC_CTYPE environment
+variables.
+.PP
+Finally, if the
+.I setlocale
+interface is also not available, the default character set is latin1.
+.PP
+Control and binary characters are displayed in standout (reverse video).
+Each such character is displayed in caret notation if possible
+(e.g.\& \(haA for control-A).  Caret notation is used only if
+inverting the 0100 bit results in a normal printable character.
+Otherwise, the character is displayed as a hex number in angle brackets.
+This format can be changed by
+setting the LESSBINFMT environment variable.
+LESSBINFMT may begin with a "*" and one character to select
+the display attribute:
+"*k" is blinking, "*d" is bold, "*u" is underlined, "*s" is standout,
+and "*n" is normal.
+If LESSBINFMT does not begin with a "*", normal attribute is assumed.
+The remainder of LESSBINFMT is a string which may include one
+printf-style escape sequence (a % followed by x, X, o, d, etc.).
+For example, if LESSBINFMT is "*u[%x]", binary characters
+are displayed in underlined hexadecimal surrounded by brackets.
+The default if no LESSBINFMT is specified is "*s<%02X>".
+Warning: the result of expanding the character via LESSBINFMT must
+be less than 31 characters.
+.PP
+When the character set is utf-8, the LESSUTFBINFMT environment variable
+acts similarly to LESSBINFMT but it applies to Unicode code points
+that were successfully decoded but are unsuitable for display (e.g.,
+unassigned code points).
+Its default value is "<U+%04lX>".
+Note that LESSUTFBINFMT and LESSBINFMT share their display attribute
+setting ("*x") so specifying one will affect both;
+LESSUTFBINFMT is read after LESSBINFMT so its setting, if any,
+will have priority.
+Problematic octets in a UTF-8 file (octets of a truncated sequence,
+octets of a complete but non-shortest form sequence, invalid octets,
+and stray trailing octets)
+are displayed individually using LESSBINFMT so as to facilitate diagnostic
+of how the UTF-8 file is ill-formed.
+.PP
+When the character set is utf-8, in rare cases it may be desirable to
+override the Unicode definition of the type of certain characters.
+For example, characters in a Private Use Area are normally treated as control
+characters, but if you are using a custom font with printable characters
+in that range, it may be desirable to tell
+.B less
+to treat such characters as printable.
+This can be done by setting the LESSUTFCHARDEF environment variable
+to a comma-separated list of 
+.I "character type"
+definitions.
+Each character type definition consists of either one hexadecimal codepoint
+or a pair of codepoints separated by a dash,
+followed by a colon and a type character.
+Each hexadecimal codepoint may optionally be preceded by a "U" or "U+".
+If a pair of codepoints is given, the type is set for
+all characters inclusively between the two values.
+If there are multiple comma-separated codepoint values,
+they must be in ascending numerical order.
+The type character may be one of:
+.RS
+.IP "p"
+A normal printable character.
+.IP "w"
+A wide (2-space) printable character.
+.IP "b"
+A binary (non-printable) character.
+.IP "c"
+A composing (zero width) character.
+.RE
+.PP
+For example, setting LESSUTFCHARDEF to
+.nf
+.sp
+	E000-F8FF:p,F0000-FFFFD:p,100000-10FFFD:p
+.sp
+.fi
+would make all Private Use Area characters be treated as printable.
+.SH "PROMPTS"
+The \-P option allows you to tailor the prompt to your preference.
+The string given to the \-P option replaces the specified prompt string.
+Certain characters in the string are interpreted specially.
+The prompt mechanism is rather complicated to provide flexibility,
+but the ordinary user need not understand the details of constructing
+personalized prompt strings.
+.sp
+A percent sign followed by a single character is expanded
+according to what the following character is.
+(References to the input file size below refer to the preprocessed size,
+if an input preprocessor is being used.)
+.IP "%b\fIX\fP"
+Replaced by the byte offset into the current input file.
+The b is followed by a single character (shown as \fIX\fP above)
+which specifies the line whose byte offset is to be used.
+If the character is a "t", the byte offset of the top line in the
+display is used,
+an "m" means use the middle line,
+a "b" means use the bottom line,
+a "B" means use the line just after the bottom line,
+and a "j" means use the "target" line, as specified by the \-j option.
+.IP "%B"
+Replaced by the size of the current input file.
+.IP "%c"
+Replaced by the column number of the text appearing in the first
+column of the screen.
+.IP "%d\fIX\fP"
+Replaced by the page number of a line in the input file.
+The line to be used is determined by the \fIX\fP, as with the %b option.
+.IP "%D"
+Replaced by the number of pages in the input file,
+or equivalently, the page number of the last line in the input file.
+.IP "%E"
+Replaced by the name of the editor (from the VISUAL environment variable,
+or the EDITOR environment variable if VISUAL is not defined).
+See the discussion of the LESSEDIT feature below.
+.IP "%f"
+Replaced by the name of the current input file.
+.IP "%F"
+Replaced by the last component of the name of the current input file.
+.IP "%g"
+Replaced by the shell-escaped name of the current input file.
+This is useful when the expanded string will be used in a shell command,
+such as in LESSEDIT.
+.IP "%i"
+Replaced by the index of the current file in the list of
+input files.
+.IP "%l\fIX\fP"
+Replaced by the line number of a line in the input file.
+The line to be used is determined by the \fIX\fP, as with the %b option.
+.IP "%L"
+Replaced by the line number of the last line in the input file.
+.IP "%m"
+Replaced by the total number of input files.
+.IP "%p\fIX\fP"
+Replaced by the percent into the current input file, based on byte offsets.
+The line used is determined by the \fIX\fP as with the %b option.
+.IP "%P\fIX\fP"
+Replaced by the percent into the current input file, based on line numbers.
+The line used is determined by the \fIX\fP as with the %b option.
+.IP "%s"
+Same as %B.
+.IP "%t"
+Causes any trailing spaces to be removed.
+Usually used at the end of the string, but may appear anywhere.
+.IP "%T"
+Normally expands to the word "file".
+However if viewing files via a tags list using the \-t option,
+it expands to the word "tag".
+.IP "%x"
+Replaced by the name of the next input file in the list.
+.PP
+If any item is unknown (for example, the file size if input
+is a pipe), a question mark is printed instead.
+.PP
+The format of the prompt string can be changed
+depending on certain conditions.
+A question mark followed by a single character acts like an "IF":
+depending on the following character, a condition is evaluated.
+If the condition is true, any characters following the question mark
+and condition character, up to a period, are included in the prompt.
+If the condition is false, such characters are not included.
+A colon appearing between the question mark and the
+period can be used to establish an "ELSE": any characters between
+the colon and the period are included in the string if and only if
+the IF condition is false.
+Condition characters (which follow a question mark) may be:
+.IP "?a"
+True if any characters have been included in the prompt so far.
+.IP "?b\fIX\fP"
+True if the byte offset of the specified line is known.
+.IP "?B"
+True if the size of current input file is known.
+.IP "?c"
+True if the text is horizontally shifted (%c is not zero).
+.IP "?d\fIX\fP"
+True if the page number of the specified line is known.
+.IP "?e"
+True if at end-of-file.
+.IP "?f"
+True if there is an input filename
+(that is, if input is not a pipe).
+.IP "?l\fIX\fP"
+True if the line number of the specified line is known.
+.IP "?L"
+True if the line number of the last line in the file is known.
+.IP "?m"
+True if there is more than one input file.
+.IP "?n"
+True if this is the first prompt in a new input file.
+.IP "?p\fIX\fP"
+True if the percent into the current input file, based on byte offsets,
+of the specified line is known.
+.IP "?P\fIX\fP"
+True if the percent into the current input file, based on line numbers,
+of the specified line is known.
+.IP "?s"
+Same as "?B".
+.IP "?x"
+True if there is a next input file
+(that is, if the current input file is not the last one).
+.PP
+Any characters other than the special ones
+(question mark, colon, period, percent, and backslash)
+become literally part of the prompt.
+Any of the special characters may be included in the prompt literally
+by preceding it with a backslash.
+.PP
+Some examples:
+.sp
+?f%f:Standard input.
+.sp
+This prompt prints the filename, if known;
+otherwise the string "Standard input".
+.sp
+?f%f \&.?ltLine %lt:?pt%pt\e%:?btByte %bt:-...
+.sp
+This prompt would print the filename, if known.
+The filename is followed by the line number, if known,
+otherwise the percent if known, otherwise the byte offset if known.
+Otherwise, a dash is printed.
+Notice how each question mark has a matching period,
+and how the % after the %pt
+is included literally by escaping it with a backslash.
+.sp
+?n?f%f\ .?m(%T %i of %m)\ ..?e(END)\ ?x-\ Next\e:\ %x..%t";
+.sp
+This prints the filename if this is the first prompt in a file,
+followed by the "file N of N" message if there is more
+than one input file.
+Then, if we are at end-of-file, the string "(END)" is printed
+followed by the name of the next file, if there is one.
+Finally, any trailing spaces are truncated.
+This is the default prompt.
+For reference, here are the defaults for
+the other two prompts (\-m and \-M respectively).
+Each is broken into two lines here for readability only.
+.nf
+.sp
+?n?f%f\ .?m(%T\ %i\ of\ %m)\ ..?e(END)\ ?x-\ Next\e:\ %x.:
+	?pB%pB\e%:byte\ %bB?s/%s...%t
+.sp
+?f%f\ .?n?m(%T\ %i\ of\ %m)\ ..?ltlines\ %lt-%lb?L/%L.\ :
+	byte\ %bB?s/%s.\ .?e(END)\ ?x-\ Next\e:\ %x.:?pB%pB\e%..%t
+.sp
+.fi
+And here is the default message produced by the = command:
+.nf
+.sp
+?f%f\ .?m(%T\ %i\ of\ %m)\ .?ltlines\ %lt-%lb?L/%L.\ .
+	byte\ %bB?s/%s.\ ?e(END)\ :?pB%pB\e%..%t
+.fi
+.PP
+The prompt expansion features are also used for another purpose:
+if an environment variable LESSEDIT is defined, it is used
+as the command to be executed when the v command is invoked.
+The LESSEDIT string is expanded in the same way as the prompt strings.
+The default value for LESSEDIT is:
+.nf
+.sp
+	%E\ ?lm+%lm.\ %g
+.sp
+.fi
+Note that this expands to the editor name, followed by a + and the
+line number, followed by the shell-escaped file name.
+If your editor does not accept the "+linenumber" syntax, or has other
+differences in invocation syntax, the LESSEDIT variable can be
+changed to modify this default.
+.
+.SH SECURITY
+When the environment variable LESSSECURE is set to 1,
+.B less
+runs in a "secure" mode.
+This means these features are disabled:
+.RS
+.IP "!"
+the shell command
+.IP "#"
+the pshell command
+.IP "|"
+the pipe command
+.IP ":e"
+the examine command.
+.IP "v"
+the editing command
+.IP "s  \-o"
+log files
+.IP "\-k"
+use of lesskey files
+.IP "\-t"
+use of tags files
+.IP
+metacharacters in filenames, such as *
+.IP
+filename completion (TAB, \(haL)
+.IP
+history file
+.RE
+.PP
+Less can also be compiled to be permanently in "secure" mode.
+.
+.SH "COMPATIBILITY WITH MORE"
+If the environment variable LESS_IS_MORE is set to 1,
+or if the program is invoked via a file link named "more",
+.B less
+behaves (mostly) in conformance with the POSIX 
+.BR more (1)
+command specification.
+In this mode, less behaves differently in these ways:
+.PP
+The \-e option works differently.
+If the \-e option is not set,
+.B less
+behaves as if the \-e option were set.
+If the \-e option is set,
+.B less
+behaves as if the \-E option were set.
+.PP
+The \-m option works differently.
+If the \-m option is not set, the medium prompt is used,
+and it is prefixed with the string "\-\-More\-\-".
+If the \-m option is set, the short prompt is used.
+.PP
+The \-n option acts like the \-z option.
+The normal behavior of the \-n option is unavailable in this mode.
+.PP
+The parameter to the \-p option is taken to be a
+.B less
+command rather than a search pattern.
+.PP
+The LESS environment variable is ignored,
+and the MORE environment variable is used in its place.
+.
+.SH "ENVIRONMENT VARIABLES"
+Environment variables may be specified either in the system environment
+as usual, or in a
+.BR lesskey (1)
+file.
+If environment variables are defined in more than one place,
+variables defined in a local lesskey file take precedence over
+variables defined in the system environment, which take precedence
+over variables defined in the system-wide lesskey file.
+.IP COLUMNS
+Sets the number of columns on the screen.
+Takes precedence over the number of columns specified by the TERM variable.
+(But if you have a windowing system which supports TIOCGWINSZ or WIOCGETD,
+the window system's idea of the screen size takes precedence over the
+LINES and COLUMNS environment variables.)
+.IP EDITOR
+The name of the editor (used for the v command).
+.IP HOME
+Name of the user's home directory
+(used to find a lesskey file on Unix and OS/2 systems).
+.IP "HOMEDRIVE, HOMEPATH"
+Concatenation of the HOMEDRIVE and HOMEPATH environment variables is
+the name of the user's home directory if the HOME variable is not set
+(only in the Windows version).
+.IP INIT
+Name of the user's init directory (used to find a lesskey file on OS/2 systems).
+.IP LANG
+Language for determining the character set.
+.IP LC_CTYPE
+Language for determining the character set.
+.IP LESS
+Options which are passed to
+.B less
+automatically.
+.IP LESSANSIENDCHARS
+Characters which may end an ANSI color escape sequence
+(default "m").
+.IP LESSANSIMIDCHARS
+Characters which may appear between the ESC character and the
+end character in an ANSI color escape sequence
+(default "0123456789:;[?!"\(aq#%()*+\ ".
+.IP LESSBINFMT
+Format for displaying non-printable, non-control characters.
+.IP LESSCHARDEF
+Defines a character set.
+.IP LESSCHARSET
+Selects a predefined character set.
+.IP LESSCLOSE
+Command line to invoke the (optional) input-postprocessor.
+.IP LESSECHO
+Name of the lessecho program (default "lessecho").
+The lessecho program is needed to expand metacharacters, such as * and ?,
+in filenames on Unix systems.
+.IP LESSEDIT
+Editor prototype string (used for the v command).
+See discussion under PROMPTS.
+.IP LESSGLOBALTAGS
+Name of the command used by the \-t option to find global tags.
+Normally should be set to "global" if your system has the
+.BR global (1)
+command.  If not set, global tags are not used.
+.IP LESSHISTFILE
+Name of the history file used to remember search commands and
+shell commands between invocations of
+.BR less .
+If set to "\-" or "/dev/null", a history file is not used.
+The default depends on the operating system, but is usually:
+.RS
+.IP "Linux and Unix"
+"$XDG_STATE_HOME/lesshst" or "$HOME/.local/state/lesshst" or
+"$XDG_DATA_HOME/lesshst" or "$HOME/.lesshst".
+.IP "Windows and MS-DOS"
+"$HOME/_lesshst".
+.IP "OS/2"
+"$HOME/lesshst.ini" or "$INIT/lesshst.ini".
+.RE
+.IP LESSHISTSIZE
+The maximum number of commands to save in the history file.
+The default is 100.
+.IP LESSKEYIN
+Name of the default
+.I "lesskey source"
+file.
+.IP LESSKEY
+Name of the default
+.I "lesskey binary"
+file. (Not used if "$LESSKEYIN" exists.)
+.IP LESSKEYIN_SYSTEM
+Name of the default system-wide
+.I "lesskey source"
+file.
+.IP LESSKEY_SYSTEM
+Name of the default system-wide
+.I "lesskey binary"
+file. (Not used if "$LESSKEYIN_SYSTEM" exists.)
+.IP LESSMETACHARS
+List of characters which are considered "metacharacters" by the shell.
+.IP LESSMETAESCAPE
+Prefix which less will add before each metacharacter in a
+command sent to the shell.
+If LESSMETAESCAPE is an empty string, commands containing
+metacharacters will not be passed to the shell.
+.IP LESSOPEN
+Command line to invoke the (optional) input-preprocessor.
+.IP LESSSECURE
+Runs less in "secure" mode.
+See discussion under SECURITY.
+.IP LESSSEPARATOR
+String to be appended to a directory name in filename completion.
+.IP LESSUTFBINFMT
+Format for displaying non-printable Unicode code points.
+.IP LESSUTFCHARDEF 
+Overrides the type of specified Unicode characters.
+.IP LESS_COLUMNS
+Sets the number of columns on the screen.
+Unlike COLUMNS, takes precedence over the system's idea of the screen size,
+so it can be used to make
+.B less
+use less than the full screen width.
+If set to a negative number, sets the number of columns used to
+this much less than the actual screen width.
+.IP LESS_LINES
+Sets the number of lines on the screen.
+Unlike LINES, takes precedence over the system's idea of the screen size,
+so it can be used to make
+.B less
+use less than the full screen height.
+If set to a negative number, sets the number of lines used to
+this much less than the actual screen height.
+When set,
+.B less
+repaints the entire screen on every movement command,
+so scrolling may be slower.
+.IP LESS_DATA_DELAY
+Duration (in milliseconds) after starting to read data from the input,
+after which the "Waiting for data" message will be displayed.
+The default is 4000 (4 seconds).
+.IP LESS_IS_MORE
+Emulate the
+.BR more (1)
+command.
+.IP LESS_TERMCAP_xx
+Where "xx" is any two characters, overrides the definition 
+of the termcap "xx" capability for the terminal.
+.IP LINES
+Sets the number of lines on the screen.
+Takes precedence over the number of lines specified by the TERM variable.
+(But if you have a windowing system which supports TIOCGWINSZ or WIOCGETD,
+the window system's idea of the screen size takes precedence over the
+LINES and COLUMNS environment variables.)
+.IP MORE
+Options which are passed to
+.B less
+automatically when running in
+.BR more "-compatible mode."
+.IP PATH
+User's search path (used to find a lesskey file
+on MS-DOS and OS/2 systems).
+.IP SHELL
+The shell used to execute the !\& command, as well as to expand filenames.
+.IP TERM
+The type of terminal on which
+.B less
+is being run.
+.IP VISUAL
+The name of the editor (used for the v command).
+.IP XDG_CONFIG_HOME
+Possible location of the 
+.B lesskey
+file; see the KEY BINDINGS section.
+.IP XDG_DATA_HOME
+Possible location of the history file; see the description of the LESSHISTFILE environment variable.
+.IP XDG_STATE_HOME
+Possible location of the history file; see the description of the LESSHISTFILE environment variable.
+.
+.SH "SEE ALSO"
+.BR lesskey (1),
+.BR lessecho (1)
+.
+.SH COPYRIGHT
+Copyright (C) 1984-2023  Mark Nudelman
+.PP
+less is part of the GNU project and is free software.
+You can redistribute it and/or modify it
+under the terms of either
+(1) the GNU General Public License as published by
+the Free Software Foundation; or (2) the Less License.
+See the file README in the less distribution for more details
+regarding redistribution.
+You should have received a copy of the GNU General Public License
+along with the source for less; see the file COPYING.
+If not, write to the Free Software Foundation, 59 Temple Place,
+Suite 330, Boston, MA  02111-1307, USA.
+You should also have received a copy of the Less License;
+see the file LICENSE.
+.PP
+less is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+.
+.SH AUTHOR
+.
+Mark Nudelman
+.br
+Report bugs at https://github.com/gwsw/less/issues.
+.br
+For more information, see the less homepage at
+.br
+https://greenwoodsoftware.com/less
diff --git a/upstream/mageia-cauldron/man1/lessecho.1 b/upstream/mageia-cauldron/man1/lessecho.1
new file mode 100644
index 00000000..2b6b35bb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lessecho.1
@@ -0,0 +1,52 @@
+.TH LESSECHO 1 "Version 643: 12 Feb 2024"
+.SH NAME
+lessecho \- expand metacharacters
+.SH SYNOPSIS
+.B lessecho
+.I "[-ox] [-cx] [-pn] [-dn] [-mx] [-nn] [-ex] [-a] file ..."
+.SH "DESCRIPTION"
+.B lessecho
+is a program that simply echos its arguments on standard output.
+But any metacharacter in the output is preceded by an "escape"
+character, which by default is a backslash.
+.SH OPTIONS
+A summary of options is included below.
+.TP
+.B \-e\fIx\fP
+Specifies "\fIx\fP", rather than backslash, to be the escape char for metachars.
+If \fIx\fP is "-", no escape char is used and arguments containing metachars
+are surrounded by quotes instead.
+.TP
+.B \-o\fIx\fP
+Specifies "\fIx\fP", rather than double-quote, to be the open quote character,
+which is used if the \-e- option is specified.
+.TP
+.B \-c\fIx\fP
+Specifies "\fIx\fP" to be the close quote character.
+.TP
+.B \-p\fIn\fP
+Specifies "\fIn\fP" to be the open quote character, as an integer.
+.TP
+.B \-d\fIn\fP
+Specifies "\fIn\fP" to be the close quote character, as an integer.
+.TP
+.B \-m\fIx\fP
+Specifies "\fIx\fP" to be a metachar.
+By default, no characters are considered metachars.
+.TP
+.B \-n\fIn\fP
+Specifies "\fIn\fP" to be a metachar, as an integer.
+.TP
+.B \-f\fIn\fP
+Specifies "\fIn\fP" to be the escape char for metachars, as an integer.
+.TP
+.B \-a
+Specifies that all arguments are to be quoted.
+The default is that only arguments containing metacharacters are quoted.
+.SH "SEE ALSO"
+.BR less (1)
+.SH AUTHOR
+This manual page was written by Thomas Schoepf <schoepf@debian.org>,
+for the Debian GNU/Linux system (but may be used by others).
+.PP
+Report bugs at https://github.com/gwsw/less/issues.
diff --git a/upstream/mageia-cauldron/man1/lesskey.1 b/upstream/mageia-cauldron/man1/lesskey.1
new file mode 100644
index 00000000..21905b2d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lesskey.1
@@ -0,0 +1,458 @@
+'\" t
+.TH LESSKEY 1 "Version 643: 12 Feb 2024"
+.SH NAME
+lesskey \- customize key bindings for less
+.SH "SYNOPSIS (deprecated)"
+.B "lesskey [\-o output] [\-\-] [input]"
+.br
+.B "lesskey [\-\-output=output] [\-\-] [input]"
+.br
+.B "lesskey \-V"
+.br
+.B "lesskey \-\-version"
+.SH SCOPE
+This document describes the format of the 
+.B lesskey
+source file, which is used by
+.B less
+version 582 and later.
+In previous versions of 
+.BR less ,
+a separate program called
+.B lesskey
+was used to compile the 
+.B lesskey 
+source file into a format understood by
+.BR less .
+This compilation step is no longer required and the
+.B lesskey
+program is therefore deprecated, although the file format remains supported by
+.B less
+itself.
+.PP
+.SH DESCRIPTION
+A
+.B lesskey
+file specifies a set of key bindings and environment variables
+to be used by subsequent invocations of
+.BR less .
+.SH FILE FORMAT
+The input file consists of one or more
+.IR sections .
+Each section starts with a line that identifies the type of section.
+Possible sections are:
+.IP #command
+Customizes command key bindings.
+.IP #line-edit
+Customizes line-editing key bindings.
+.IP #env
+Defines environment variables.
+.PP
+Blank lines and lines which start with a hash mark (#) are ignored,
+except as noted below.
+.
+.SH "COMMAND SECTION"
+The command section begins with the line
+.sp
+#command
+.sp
+If the command section is the first section in the file,
+this line may be omitted.
+The command section consists of lines of the form:
+.sp
+	\fIstring\fP <whitespace> \fIaction\fP [extra-string] <newline>
+.sp
+Whitespace is any sequence of one or more spaces and/or tabs.
+The \fIstring\fP is the command key(s) which invoke the action.
+The \fIstring\fP may be a single command key, or a sequence of up to 15 keys.
+The \fIaction\fP is the name of the less action, from the list below.
+The characters in the \fIstring\fP may appear literally, or be
+prefixed by a caret to indicate a control key.
+A backslash followed by one to three octal digits may be used to
+specify a character by its octal value.
+A backslash followed by certain characters specifies input
+characters as follows:
+.RS 5m
+.TS
+l l l.
+\eb	BACKSPACE	(0x08)
+\ee	ESCAPE	(0x1B)
+\en	NEWLINE	(0x0A)
+\er	RETURN	(0x0D)
+\et	TAB	(0x09)
+.TE
+.sp
+\ek followed by a single character represents the char(s) produced when one of these keys is pressed:
+.TS
+l l.
+\ekb	BACKSPACE (the BACKSPACE key)
+\ekB	ctrl-BACKSPACE
+\ekd	DOWN ARROW
+\ekD	PAGE DOWN
+\eke	END
+\ekh	HOME
+\eki	INSERT
+\ekl	LEFT ARROW
+\ekL	ctrl-LEFT ARROW
+\ekr	RIGHT ARROW
+\ekR	ctrl-RIGHT ARROW
+\ekt	BACKTAB
+\eku	UP ARROW
+\ekU	PAGE UP
+\ekx	DELETE
+\ekX	ctrl-DELETE
+\ek1	F1
+.TE
+
+.PP
+A backslash followed by any other character indicates that character is
+to be taken literally.
+Characters which must be preceded by backslash include
+caret, space, tab, hash mark and the backslash itself.
+.PP
+An action may be followed by an "extra" string.
+When such a command is entered while running
+.BR less ,
+the action is performed, and then the extra
+string is parsed, just as if it were typed in to
+.BR less .
+This feature can be used in certain cases to extend
+the functionality of a command.
+For example, see the "{" and ":t" commands in the example below.
+The extra string has a special meaning for the "quit" action:
+when
+.B less
+quits, the first character of the extra string is used as its exit status.
+.
+.SH EXAMPLE
+The following input file describes the set of
+default command keys used by 
+.BR less .
+Documentation on each command can be found in the
+.less
+man page, under the key sequence which invokes the command.
+.sp
+.RS 5m
+.TS
+l l.
+#command
+\er	forw-line
+\en	forw-line
+e	forw-line
+j	forw-line
+\ekd	forw-line
+^E	forw-line
+^N	forw-line
+k	back-line
+y	back-line
+^Y	back-line
+^K	back-line
+^P	back-line
+J	forw-line-force
+K	back-line-force
+Y	back-line-force
+d	forw-scroll
+^D	forw-scroll
+u	back-scroll
+^U	back-scroll
+\e40	forw-screen
+f	forw-screen
+^F	forw-screen
+^V	forw-screen
+\ekD	forw-screen
+b	back-screen
+^B	back-screen
+\eev	back-screen
+\ekU	back-screen
+z	forw-window
+w	back-window
+\ee\e40	forw-screen-force
+F	forw-forever
+\eeF	forw-until-hilite
+R	repaint-flush
+r	repaint
+^R	repaint
+^L	repaint
+\eeu	undo-hilite
+\eeU	clear-search
+g	goto-line
+\ekh	goto-line
+<	goto-line
+\ee<	goto-line
+p	percent
+%	percent
+\ee[	left-scroll
+\ee]	right-scroll
+\ee(	left-scroll
+\ee)	right-scroll
+\ekl	left-scroll
+\ekr	right-scroll
+\ee{	no-scroll
+\ee}	end-scroll
+{	forw-bracket {}
+}	back-bracket {}
+(	forw-bracket ()
+)	back-bracket ()
+[	forw-bracket []
+]	back-bracket []
+\ee^F	forw-bracket
+\ee^B	back-bracket
+G	goto-end
+\ee>	goto-end
+>	goto-end
+\eke	goto-end
+\eeG	goto-end-buffered
+\&=	status
+^G	status
+:f	status
+/	forw-search
+?	back-search
+\ee/	forw-search *
+\ee?	back-search *
+n	repeat-search
+\een	repeat-search-all
+N	reverse-search
+\eeN	reverse-search-all
+&	filter
+m	set-mark
+M	set-mark-bottom
+\eem	clear-mark
+'	goto-mark
+^X^X	goto-mark
+E	examine
+:e	examine
+^X^V	examine
+:n	next-file
+:p	prev-file
+t	next-tag
+T	prev-tag
+:x	index-file
+:d	remove-file
+-	toggle-option
+:t	toggle-option t
+s	toggle-option o
+	## Use a long option name by starting the 
+	## extra string with ONE dash; eg:
+	##   s toggle-option -log-file\en
+\&_	display-option
+|	pipe
+v	visual
+!	shell
+#	pshell
++	firstcmd
+H	help
+h	help
+V	version
+0	digit
+1	digit
+2	digit
+3	digit
+4	digit
+5	digit
+6	digit
+7	digit
+8	digit
+9	digit
+q	quit
+Q	quit
+:q	quit
+:Q	quit
+ZZ	quit
+.TE
+.RE
+.sp
+.SH PRECEDENCE
+Commands specified by
+.B lesskey
+take precedence over the default commands.
+A default command key may be disabled by including it in the
+input file with the action "invalid".
+Alternatively, a key may be defined
+to do nothing by using the action "noaction".
+"noaction" is similar to "invalid", but
+.B less
+will give an error beep for an "invalid" command,
+but not for a "noaction" command.
+In addition, ALL default commands may be disabled by
+adding this control line to the input file:
+.sp
+#stop
+.sp
+This will cause all default commands to be ignored.
+The #stop line should be the last line in that section of the file.
+.PP
+Be aware that #stop can be dangerous.
+Since all default commands are disabled,
+you must provide sufficient commands before the #stop line
+to enable all necessary actions.
+For example, failure to provide a "quit" command can lead to frustration.
+.
+.SH "LINE EDITING SECTION"
+The line-editing section begins with the line:
+.sp
+#line-edit
+.sp
+This section specifies new key bindings for the line editing commands,
+in a manner similar to the way key bindings for
+ordinary commands are specified in the #command section.
+The line-editing section consists of a list of keys and actions,
+one per line as in the example below.
+.
+.SH EXAMPLE
+The following input file describes the set of
+default line-editing keys used by
+.BR less :
+.sp
+.RS 5m
+.TS
+l l.
+#line-edit
+\et	forw-complete
+\e17	back-complete
+\ee\et	back-complete
+^L	expand
+^V	literal
+^A	literal
+\eel	right
+\ekr	right
+\eeh	left
+\ekl	left
+\eeb	word-left
+\ee\ekl	word-left
+\eew	word-right
+\ee\ekr	word-right
+\eei	insert
+\eex	delete
+\ekx	delete
+\eeX	word-delete
+\eekx	word-delete
+\ee\eb	word-backspace
+\ee0	home
+\ekh	home
+\ee$	end
+\eke	end
+\eek	up
+\eku	up
+\eej	down
+^G	abort
+.TE
+.RE
+.sp
+.
+.SH "LESS ENVIRONMENT VARIABLES"
+The environment variable section begins with the line
+.sp
+#env
+.sp
+Following this line is a list of environment variable assignments.
+Each line consists of an environment variable name, an equals sign (=)
+and the value to be assigned to the environment variable.
+White space before and after the equals sign is ignored.
+Variables assigned in this way are visible only to
+.BR less .
+If a variable is specified in the system environment and also in a
+lesskey file, the value in the lesskey file takes precedence.
+.
+.sp
+If the variable name is followed by += rather than =,
+the string is appended to the variable's existing value.
+This currently works only if any += lines immediately follow
+the same variable's original definition (with an = line),
+without any intervening definitions of other variables.
+It can append only to a variable defined earlier in the file;
+it cannot append to a variable in the system environment.
+The string is appended literally, without any extra whitespace added,
+so if whitespace is desired,
+it should be appended to the end of the preceding line.
+(It cannot be added to the beginning of the += string because space after
+the equals sign is ignored, as noted above.)
+.
+.SH CONDITIONAL CONFIGURATION
+If a line begins with #version followed by a relational operator and a version number,
+the remainder of the line is parsed if and only if the running version of
+.B less
+(or
+.BR lesskey )
+matches the operator.
+This can be helpful if a lesskey file is used by different versions of
+.BR less .
+.sp
+For example, suppose that a new command named 'sideways-search' is added in 
+.B less
+version 777.
+Then the following line would assign the command to the Q key, but only in versions of
+.B less
+which support it. The line would be ignored by versions earlier than 777.
+.sp
+.nf
+	#version >= 777  Q sideways-search
+.fi
+.sp
+These six operators are supported:
+.RS 5m
+.TS
+l l.
+ >	Greater than
+ <	Less than
+ >=	Greater than or equal to
+ <=	Less than or equal to
+ =	Equal to
+ !=	Not equal to
+.TE
+.RE
+.sp
+The #version feature is not supported in
+.B less
+and
+.B lesskey
+before version 594.
+In those older versions, all #version lines are ignored.
+.
+.SH EXAMPLE
+The following input file sets the \-i and \-S options when
+.less
+is run and, on version 595 and higher, adds a \-\-color option.
+.sp
+.nf
+	#env
+	## (Note that there must be a space at the end of the next line,
+	##  to separate the --color option from the -S option.)
+	LESS = \-i\ \-S\ 
+	#version\ >=\ 595\ \ LESS\ +=\ \-\-color=Hkc
+.fi
+.
+.SH "SEE ALSO"
+.BR less (1)
+.
+.SH WARNINGS
+On MS-DOS and OS/2 systems, certain keys send a sequence of characters
+which start with a NUL character (0).
+This NUL character should be represented as \e340 in a lesskey file.
+.
+.SH COPYRIGHT
+Copyright (C) 1984-2023  Mark Nudelman
+.PP
+less is part of the GNU project and is free software.
+You can redistribute it and/or modify it
+under the terms of either
+(1) the GNU General Public License as published by
+the Free Software Foundation; or (2) the Less License.
+See the file README in the less distribution for more details
+regarding redistribution.
+You should have received a copy of the GNU General Public License
+along with the source for less; see the file COPYING.
+If not, write to the Free Software Foundation, 59 Temple Place,
+Suite 330, Boston, MA  02111-1307, USA.
+You should also have received a copy of the Less License;
+see the file LICENSE.
+.PP
+less is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+.
+.SH AUTHOR
+.
+Mark Nudelman
+.br
+Report bugs at https://github.com/gwsw/less/issues.
diff --git a/upstream/mageia-cauldron/man1/lesspipe.1 b/upstream/mageia-cauldron/man1/lesspipe.1
new file mode 100644
index 00000000..99097ca1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lesspipe.1
@@ -0,0 +1,221 @@
+.TH LESSPIPE.SH "1" "June 2023" "lesspipe.sh" "User Commands"
+.SH NAME
+lesspipe.sh \- a filter for less
+.SH SYNOPSIS
+.B lesspipe.sh
+[\fIFILE[s]\fR]...
+.SH DESCRIPTION
+.PP
+The aim of \fBlesspipe.sh\fP is to enhance the output of \fBless\fP. The choice
+of the rules to be applied to modify the output are based on the file contents.
+The file extension is respected only as a last resort.
+Usually \fBlesspipe.sh\fP is called as an input filter to \fBless\fP.
+.PP
+With the help of that filter \fBless\fP
+will display the uncompressed contents of compressed (\fIgzip, bzip2,
+compress, zstd, lz4, lzip, xz, lzma or brotli\fP) files. For files
+containing archives and directories, a table of contents will be displayed
+(\fItar, ar, zip, i7-zip, rar, jar, rpm, deb ms-cabinet and iso formats\fP).
+Many other files will be reformatted for display. It includes
+\fIpdf, dvi, markdown, Office (MS and Openoffice)\fP suites formats,
+\fINetCDF, matlab, device tree blob, html\fP and \fImedia (image, audio and
+video)\fP formats. This does require helper programs being installed.
+.PP
+The filter can also be applied recursively to extract and display
+files in archives on the fly. This works to a depth of 6 where applying a
+decompression algorithm counts as a separate level.
+.PP
+If the file utility reports text with an encoding different from the one
+used in the terminal then the text will be transformed using \fIiconv\fP into
+the default encoding. This does assume the \fIfile\fP command gets the file
+encoding right, which can be wrong in some situations. An appended colon
+to the file name does suppress the conversion.
+.PP
+When using the programs \fBgit\fP, \fBvim\fP or \fBmutt\fP they can be
+enabled to read non-text files by using lesspipe.sh. That is described in
+the Wiki at \fIhttps://github.com/wofr06/lesspipe/wiki\fP.
+.SH FILTER ACTIVATION
+The filter is called from \fBless\fP provided the environment variable
+\fBLESSOPEN\fP is set properly. For ksh like shells (\fIbash, zsh\fP)
+the command
+.RS
+.I LESSOPEN="|lesspipe.sh %s"; export LESSOPEN
+.RE
+does activate the filter for less. Use the fully qualified path, if
+\fBlesspipe.sh\fP is not in the search path. The command to set \fBLESSOPEN\fP
+can also be displayed by calling \fBlesspipe.sh\fP without arguments.
+This can even be used to set \fBLESSOPEN\fP directly:
+.RS
+.I eval `lesspipe.sh`
+(bash) or
+.RE
+.RS
+.I lesspipe.sh|source /dev/stdin
+(zsh)
+.RE
+Having set the environment variable as described above, \fBless\fP
+will then display textual information for a wide range of file formats.
+.PP
+The filter is normally not called if input is piped to less as in
+.RS
+.I cat somefile | less
+.RE
+As described in the man page of less, the filtering in a pipe can however
+be forced by starting \fBLESSOPEN\fP with the characters \fI|-\fP.
+.PP
+\fBLESSOPEN\fP starting with the two characters \fI||\fP to handle empty files
+and command errors is implemented only partly, usually on failures of
+commands within \fBlesspipe.sh\fP the error messages get displayed.
+.PP
+The now obsolete variable \fBLESS_ADVANCED_PREPROCESSOR\fP
+was used to decide, whether \fIhtml\fP, \fIxml\fP and \fIperl pod\fP  should
+be shown as pure text or not. This has been changed, these formats are now
+always interpreted, unless a colon is appended to the file name. If the
+correct file type (\fIhtml\fP, \fIxml\fP, \fIpod\fP) follows, the output can
+get colorized (see below).
+.PP
+.RS
+Example: \fIless index.html:html\fP
+.RE
+.PP
+To suppress informal messages in the first line of the filter output the
+ENV variable \fBLESSQUIET\fP can be set to a nonempty value.
+.PP
+To disengage the filter temporarily a colon can be appended to the file name.
+If the file name contains a colon, then an equal sign should be used instead.
+.SH OUTPUT COLORIZATION
+The filter is able to do syntax highlighting for a wide variety of
+file types. If installed, \fIbat\fP/\fIbatcat\fP is used for
+coloring the output. If not, \fIpygmentize\fP, \fIsource-highlight\fP,
+\fIvimcolor\fP and \fIcode2color\fP are tried in turn.
+For bat/batcat the theme is set to \fIansi\fP and the style is set to
+\fIplain\fP which comes closer to the unfiltered output of \fBless\fP.
+These settings can be changed in \fI~/.config/bat/config\fP or by the
+environment variables \fBBAT_STYLE\fP and \fBBAT_THEME\fP.
+.PP
+Among the colorizers
+a preferred one can be forced for coloring by setting the ENV variable
+\fBLESSCOLORIZER\fP to the name of the colorizer. For \fIpygmentize\fP and
+\fIbat\fP/\fIbatcat\fP restricted option settings are allowed as follows:
+.RS
+.I LESSCOLORIZER='pygmentize -O style=foo'
+.RE
+.RS
+.I LESSCOLORIZER='bat --style=foo --theme=bar'
+.RE
+Syntax highlighting is activated, if the environment variable \fBLESS\fP
+exists and contains the option \fI-R\fP
+or less is called with this option. This guarantees that escape sequences
+get converted into colors and do not garble the display. Using the option
+\fI-r\fP is not recommended, as the screen layout may be wrong, if long
+lines are in the output.
+.PP
+Syntax highlighting can be switched off by
+appending a colon after the file name, if the output was colorful. If the
+wrong language was chosen for syntax highlighting, then another one can be
+forced by appending a colon and a suffix to the file name.
+.PP
+In a pipe that method cannot be used. As a way out a last argument can be added
+that gets inspected by \fBlesspipe.sh\fP.
+A single colon (disengage filter) or :extension (force language) is possible as e.g with
+.RS
+.I command that generates c code | less - :c
+.RE
+.PP
+When the conditions for syntax highlighting are met directory listings and
+listings of tar file contents get colorized as well.
+.PP
+As \fBless\fP is used as a default browser in other programs the choice of the
+colorizer can affect the output of those programs.
+For \fIman\fP, \fIgit\fP, and \fIperldoc\fP) lesspipe.sh does no filtering.
+.SH WATCHING GROWING FILES
+As soon as \fBlesspipe.sh\fP
+calls a program to convert the input the ability to watch growing files
+(using the F command within less) is lost. This is usually wanted for log
+files like syslog. To temporarily disengage \fBlesspipe.sh\fP
+a colon as the last argument for \fBless\fP needs to be added as e.g in
+.RS
+.I less /var/log/syslog :
+.RE
+or \fBless\fP
+can be called with the +F argument, which is equivalent to F within the pager:
+.RS
+.I less +F /var/log/syslog
+.RE
+Appending a colon to the file name does not work, as then the filter has to be engaged to at least remove that colon and use cat for the original file.
+On the other hand non growing log files can be colorized using \fBccze\fP.
+Its recognition as a log file is difficult if not ending in \fI.log\fP
+but can be forced appending \fB:.log\fP to the file name as e.g in
+.RS
+.I less /var/log/syslog:.log
+.RE
+.SH ADVANCED USAGE
+This version of \fBlesspipe.sh\fP
+allows you to view individual files contained in a file archive, which itself
+may even be contained in another archive.
+.PP
+The notation for viewing files in multifile archives is
+.RS
+.B less
+\fIarchive_file\fP:\fIcontained_file\fP
+.RE
+or even
+.RS
+.B less
+\fIsuper_archive\fP:\fIarchive_file\fP:\fIcontained_file\fP
+.RE
+To display the last file in the chain raw format, a colon (\fI:\fP) has to be
+appended to the file name. If it does contain a colon, then the alternate
+separator character equal sign (\fI=\fP) has to be used.
+.PP
+Again, this method of extracting and displaying files does not work if
+\fBless\fP is called in an output pipe and \fBLESSOPEN\fP starts with the
+\fB|-\fP characters. As already for syntax highlighting the solution is to use
+a second argument that starts with a colon. Then the above command would
+be written as
+.RS
+\fBcat \fIsuper_archive\fP | \fBless\fP - :\fIarchive\fP:\fIcontained_file\fP
+.RE
+.PP
+.SH COMPLETING MECHANISM FOR ARCHIVE CONTENTS
+With the provided \fIlesscomplete\fP (for \fBzsh\fP and \fBbash\fP),
+\fI_less\fP (for \fBzsh\fP) and \fIless_completion\fP (for \fBbash\fP) files
+a tab completion for files in archives can be accomplished.
+Entering a colon (:) or an equal sign (=) after an archive
+file name and then pressing the tab key triggers the completion mechanism.
+This also works in chained archives. The files \fIlesscomplete\fP and
+\fIless_completion\fP have to be in one of the directories listed in
+\fB$PATH\fP and the function \fI_less\fP for \fBzsh\fP in a directory
+listed by \fI$fpath\fP. The less_completion script has to
+be sourced within a bash initialization script, e.g. in \fI~/.bashrc\fP. New
+directories such as \fI~/scripts\fP and \fI~/.fpath\fP can be added using the
+commands
+.RS
+\fBPATH\fP=\fI~/scripts:$PATH\fP and
+\fBfpath\fP=\fI(~/.fpath $fpath)\fP
+.RE
+.SH USER DEFINED FILTERING
+The lesspipe.sh filtering can be replaced or enhanced  by a user defined
+program. Such a program has to be called either \fB.lessfilter\fP (and be
+placed in the users home directory), or \fBlessfilter\fP (and be accessible
+from a directory mentioned in \fB$PATH\fP).
+It has to be executable and has to end with an exit code 0, if the filtering
+was done within that script. Otherwise, a nonzero exit code means the filtering
+is left to lesspipe.sh.
+.PP
+This mechanism can be used to add filtering for new formats or e.g. inhibit
+filtering for certain file types.
+.SH AUTHOR
+Wolfgang Friebel
+.SH "REPORTING BUGS"
+Report bugs to <wp.friebel AT gmail DOT com>.
+.SH COPYRIGHT
+Copyright \(co 2005-2023 Wolfgang Friebel
+.br
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+less(1)
+.PP
+A description of \fBlesspipe.sh\fP
+is also contained in the file README contained in the source code package
diff --git a/upstream/mageia-cauldron/man1/libnetcfg.1 b/upstream/mageia-cauldron/man1/libnetcfg.1
new file mode 100644
index 00000000..bdb4cf1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/libnetcfg.1
@@ -0,0 +1,116 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "LIBNETCFG 1"
+.TH LIBNETCFG 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+libnetcfg \- configure libnet
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The libnetcfg utility can be used to configure the libnet.
+Starting from perl 5.8 libnet is part of the standard Perl
+distribution, but the libnetcfg can be used for any libnet
+installation.
+.SH USAGE
+.IX Header "USAGE"
+Without arguments libnetcfg displays the current configuration.
+.PP
+.Vb 10
+\&    $ libnetcfg
+\&    # old config ./libnet.cfg
+\&    daytime_hosts        ntp1.none.such
+\&    ftp_int_passive      0
+\&    ftp_testhost         ftp.funet.fi
+\&    inet_domain          none.such
+\&    nntp_hosts           nntp.none.such
+\&    ph_hosts             
+\&    pop3_hosts           pop.none.such
+\&    smtp_hosts           smtp.none.such
+\&    snpp_hosts           
+\&    test_exist           1
+\&    test_hosts           1
+\&    time_hosts           ntp.none.such
+\&    # libnetcfg \-h for help
+\&    $
+.Ve
+.PP
+It tells where the old configuration file was found (if found).
+.PP
+The \f(CW\*(C`\-h\*(C'\fR option will show a usage message.
+.PP
+To change the configuration you will need to use either the \f(CW\*(C`\-c\*(C'\fR or
+the \f(CW\*(C`\-d\*(C'\fR options.
+.PP
+The default name of the old configuration file is by default
+"libnet.cfg", unless otherwise specified using the \-i option,
+\&\f(CW\*(C`\-i oldfile\*(C'\fR, and it is searched first from the current directory,
+and then from your module path.
+.PP
+The default name of the new configuration file is "libnet.cfg", and by
+default it is written to the current directory, unless otherwise
+specified using the \-o option, \f(CW\*(C`\-o newfile\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Net::Config, libnetFAQ
+.SH AUTHORS
+.IX Header "AUTHORS"
+Graham Barr, the original Configure script of libnet.
+.PP
+Jarkko Hietaniemi, conversion into libnetcfg for inclusion into Perl 5.8.
diff --git a/upstream/mageia-cauldron/man1/lilymidi.1 b/upstream/mageia-cauldron/man1/lilymidi.1
new file mode 100644
index 00000000..6aaba675
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lilymidi.1
@@ -0,0 +1,39 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH LILYMIDI "1" "January 2024" "lilymidi 2.24.3" "User Commands"
+.SH NAME
+lilymidi \- manual page for lilymidi 2.24.3
+.SH SYNOPSIS
+.B lilymidi
+[\fI\,options\/\fR] \fI\,FILE\/\fR
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+show program's version number and exit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-\-filter\-tracks\fR=\fI\,REGEXP\/\fR
+display only tracks numbers, of those track names
+matching REGEXP
+.TP
+\fB\-\-prefix\-tracks\fR=\fI\,PREFIX\/\fR
+prefix filtered track numbers with PREFIX
+.TP
+\fB\-\-dump\fR
+just dump parsed contents of the MIDI file
+.TP
+\fB\-\-pretty\fR
+dump parsed contents of the MIDI file in humanreadable form (implies \fB\-\-dump\fR)
+.SH "SEE ALSO"
+The full documentation for
+.B lilymidi
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B lilymidi
+programs are properly installed at your site, the command
+.IP
+.B info lilymidi
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/lilypond-book.1 b/upstream/mageia-cauldron/man1/lilypond-book.1
new file mode 100644
index 00000000..dcc65cd5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lilypond-book.1
@@ -0,0 +1,106 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH LILYPOND-BOOK "1" "January 2024" "lilypond-book 2.24.3" "User Commands"
+.SH NAME
+lilypond-book \- manual page for lilypond-book 2.24.3
+.SH SYNOPSIS
+.B lilypond-book
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR
+.SH DESCRIPTION
+Process LilyPond snippets in hybrid HTML, LaTeX, texinfo or DocBook document.
+.SH OPTIONS
+.TP
+\fB\-F\fR, \fB\-\-filter\fR=\fI\,FILTER\/\fR
+pipe snippets through FILTER [default: `convert\-ly \fB\-n\fR
+\-']
+.TP
+\fB\-f\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR
+use output format FORMAT (texi [default], texi\-html,
+latex, html, docbook)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+add DIR to include path
+.TP
+\fB\-\-info\-images\-dir\fR=\fI\,DIR\/\fR
+format Texinfo output so that Info will look for
+images of music in DIR
+.TP
+\fB\-\-left\-padding\fR=\fI\,PAD\/\fR
+pad left side of music to align music in spite of
+uneven bar numbers (in mm) [default: 3.0]
+.TP
+\fB\-\-lily\-loglevel\fR=\fI\,LOGLEVEL\/\fR
+print lilypond log messages according to LOGLEVEL
+[default: none]
+.TP
+\fB\-\-lily\-output\-dir\fR=\fI\,DIR\/\fR
+write lily\-XXX files to DIR, link into \fB\-\-output\fR dir
+.TP
+\fB\-l\fR, \fB\-\-loglevel\fR=\fI\,LOGLEVEL\/\fR
+print log messages according to LOGLEVEL (NONE, ERROR,
+WARNING, PROGRESS [default], DEBUG)
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,DIR\/\fR
+write output to DIR
+.TP
+\fB\-P\fR, \fB\-\-process\fR=\fI\,COMMAND\/\fR
+process ly_files using COMMAND FILE...
+.TP
+\fB\-\-redirect\-lilypond\-output\fR
+redirect the lilypond output
+.TP
+\fB\-s\fR, \fB\-\-safe\fR
+removed; using this option results in an error
+.TP
+\fB\-\-skip\-lily\-check\fR
+do not fail if no lilypond output is found
+.TP
+\fB\-\-skip\-png\-check\fR
+do not fail if no PNG images are found for EPS files
+.TP
+\fB\-\-use\-source\-file\-names\fR
+write snippet output files with the same base name as
+their source file
+.TP
+\fB\-V\fR, \fB\-\-verbose\fR
+be verbose
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-w\fR, \fB\-\-warranty\fR
+show warranty and copyright
+.SS "Options only for the latex and texinfo backends:"
+.TP
+\fB\-\-latex\-program\fR=\fI\,PROG\/\fR
+run executable PROG instead of latex or, in case \fB\-\-pdf\fR
+option is set, instead of pdflatex
+.TP
+\fB\-\-texinfo\-program\fR=\fI\,PROG\/\fR
+run executable PROG instead of texi2pdf
+.TP
+\fB\-\-pdf\fR
+create PDF files for use with pdftex
+.SH EXAMPLES
+.IP
+\f(CW$ lilypond-book --filter="tr '[a-z]' '[A-Z]'" BOOK\fR
+.br
+\f(CW$ lilypond-book -F "convert-ly --no-version --from=2.0.0 -" BOOK\fR
+.br
+\f(CW$ lilypond-book --process='lilypond -I include' BOOK\fR
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH "SEE ALSO"
+The full documentation for
+.B lilypond-book
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B lilypond-book
+programs are properly installed at your site, the command
+.IP
+.B info lilypond-book
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/lilypond-invoke-editor.1 b/upstream/mageia-cauldron/man1/lilypond-invoke-editor.1
new file mode 100644
index 00000000..06be765f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lilypond-invoke-editor.1
@@ -0,0 +1,30 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH LILYPOND-INVOKE-EDITOR "1" "January 2024" "lilypond-invoke-editor (GNU LilyPond 2.24.3)" "User Commands"
+.SH NAME
+lilypond-invoke-editor \- manual page for lilypond-invoke-editor (GNU LilyPond 2.24.3)
+.SH SYNOPSIS
+.B lilypond-invoke-editor
+\fI\,textedit://FILE:LINE:CHAR:COLUMN\/\fR
+.SH DESCRIPTION
+lilypond\-invoke\-editor (GNU LilyPond 2.24.3)
+.PP
+Visit a file and position the cursor.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+show version
+.SH "SEE ALSO"
+The full documentation for
+.B lilypond-invoke-editor
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B lilypond-invoke-editor
+programs are properly installed at your site, the command
+.IP
+.B info lilypond-invoke-editor
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/lilypond.1 b/upstream/mageia-cauldron/man1/lilypond.1
new file mode 100644
index 00000000..fe0e4389
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lilypond.1
@@ -0,0 +1,115 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH LILYPOND "1" "January 2024" "LilyPond 2.24.3 (running Guile 2.2)" "User Commands"
+.SH NAME
+LilyPond \- manual page for LilyPond 2.24.3 (running Guile 2.2)
+.SH SYNOPSIS
+.B lilypond
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+Typeset music and/or produce MIDI from FILE.
+.PP
+LilyPond produces beautiful music notation.
+For more information, see https://lilypond.org
+.SH OPTIONS
+.TP
+\fB\-f\fR, \fB\-\-formats\fR=\fI\,FORMATs\/\fR
+dump FORMAT,...  Also as separate options:
+.TP
+\fB\-\-pdf\fR
+generate PDF files (default)
+.TP
+\fB\-\-svg\fR
+generate SVG files
+.TP
+\fB\-\-png\fR
+generate PNG files
+.TP
+\fB\-\-ps\fR
+generate PostScript files
+.TP
+\fB\-E\fR, \fB\-\-eps\fR
+generate Encapsulated PostScript files
+.TP
+\fB\-O\fR, \fB\-\-pspdfopt\fR=\fI\,KEY\/\fR
+set ps/pdf optimization to KEY, which is either
+\&'size' (default), 'TeX', or 'TeX\-GS'
+.TP
+\fB\-d\fR, \fB\-\-define\-default=SYM\fR[=\fI\,VAL\/\fR]
+set Scheme option SYM to VAL (default: '#t')
+.TP
+\fB\-d\fR, \fB\-\-define\-default\fR=\fI\,no\-SYM\/\fR
+set Scheme option SYM to '#f'
+.TP
+\fB\-d\fR, \fB\-\-define\-default\fR=\fI\,help\/\fR
+show help for Scheme options
+.TP
+\fB\-e\fR, \fB\-\-evaluate\fR=\fI\,EXPR\/\fR
+evaluate scheme code
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-H\fR, \fB\-\-header\fR=\fI\,FIELD\/\fR
+dump \eheader field FIELD to file
+named BASENAME.FIELD
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fI\,DIR\/\fR
+append DIR to search path
+.TP
+\fB\-i\fR, \fB\-\-init\fR=\fI\,FILE\/\fR
+use FILE as init file
+.TP
+\fB\-j\fR, \fB\-\-jail\fR=\fI\,USER\/\fR,GROUP,JAIL,DIR
+chroot to JAIL, become USER:GROUP
+and cd into DIR
+.TP
+\fB\-l\fR, \fB\-\-loglevel\fR=\fI\,LOGLEVEL\/\fR
+print log messages according to LOGLEVEL,
+which is either NONE, ERROR, WARNING,
+BASIC, PROGRESS, INFO (default), or DEBUG
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to FILE (suffix will be added)
+or to FOLDER, in which case the file name
+will be taken from the input file.
+.TP
+\fB\-\-relocate\fR
+(ignored)
+.TP
+\fB\-s\fR, \fB\-\-silent\fR
+no progress, only error messages
+(equivalent to \fB\-\-loglevel\fR=\fI\,ERROR\/\fR)
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-V\fR, \fB\-\-verbose\fR
+be verbose (equivalent to \fB\-\-loglevel\fR=\fI\,DEBUG\/\fR)
+.TP
+\fB\-w\fR, \fB\-\-warranty\fR
+show warranty and copyright
+.PP
+You found a bug? Please read https://lilypond.org/bug\-reports.html
+.SH COPYRIGHT
+Copyright \(co 1996\-\-2023 by
+.IP
+Han\-Wen Nienhuys <hanwen@xs4all.nl>
+Jan Nieuwenhuizen <janneke@gnu.org>
+and others.
+.PP
+This program is free software.  It is covered by the GNU General Public
+License and you are welcome to change it and/or distribute copies of it
+under certain conditions.  Invoke as `lilypond \fB\-\-warranty\fR' for more
+information.
+.SH "SEE ALSO"
+The full documentation for
+.B LilyPond
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B LilyPond
+programs are properly installed at your site, the command
+.IP
+.B info LilyPond
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/lilysong.1 b/upstream/mageia-cauldron/man1/lilysong.1
new file mode 100644
index 00000000..7d206fd6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lilysong.1
@@ -0,0 +1,40 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH LILYSONG "1" "January 2024" "lilysong 2.24.3" "User Commands"
+.SH NAME
+lilysong \- manual page for lilysong 2.24.3
+.SH SYNOPSIS
+.B lilysong
+[\fI\,-p PLAY-PROGRAM\/\fR] \fI\,FILE.xml \/\fR[\fI\,LANGUAGE-CODE-OR-VOICE \/\fR[\fI\,SPEEDUP\/\fR]]
+.SH DESCRIPTION
+.IP
+lilysong FILE.ly [LANGUAGE\-CODE\-OR\-VOICE]
+lilysong \fB\-\-list\-voices\fR
+lilysong \fB\-\-list\-languages\fR
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+show program's version number and exit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-\-list\-voices\fR
+list available Festival voices
+.TP
+\fB\-\-list\-languages\fR
+list available Festival languages
+.TP
+\fB\-p\fR PROGRAM, \fB\-\-play\-program\fR=\fI\,PROGRAM\/\fR
+use PROGRAM to play song immediately
+.SH "SEE ALSO"
+The full documentation for
+.B lilysong
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B lilysong
+programs are properly installed at your site, the command
+.IP
+.B info lilysong
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/link.1 b/upstream/mageia-cauldron/man1/link.1
new file mode 100644
index 00000000..c2a111e8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/link.1
@@ -0,0 +1,39 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH LINK "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+link \- call the link function to create a link to a file
+.SH SYNOPSIS
+.B link
+\fI\,FILE1 FILE2\/\fR
+.br
+.B link
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Call the link function to create a link named FILE2 to an existing FILE1.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Michael Stone.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBlink\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/link>
+.br
+or available locally via: info \(aq(coreutils) link invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/linuxdoc.1 b/upstream/mageia-cauldron/man1/linuxdoc.1
new file mode 100644
index 00000000..af47b664
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/linuxdoc.1
@@ -0,0 +1,388 @@
+.\" Process this file with
+.\" groff -man -Tascii linuxdoc.1
+.\"
+.TH LINUXDOC 1 "27 Jul 2000"
+.SH NAME
+linuxdoc \- LinuxDoc DTD SGML converter to other output format
+.SH SYNOPSIS
+.B linuxdoc
+.I \fB\--backend=\fP\fIformat\fP
+.br
+.I \fB\--papersize=\fP\fIsize\fP
+.I \fB\--language=\fP\fIlang\fP
+.I \fB\--charset=\fP\fIchar\fP
+.I \fB\--style=\fP\fIfile\fP
+.I \fB\--debug\fP
+.I \fB\--define\fP\ \fIattribute=value\fP
+.I \fB\--include\fP\ \fIentity\fP
+.B "[backend-options...]"
+.I file(.sgml)\fP
+.PP
+or (Old, obsoleted usage)
+.br
+.B sgmlxxxx [generic-options...] [backend-options...] \ \ \fIfile(.sgml)\fP
+.SH DESCRIPTION
+The
+.B linuxdoc
+suite is a collection of text formatters which understands a LinuxDoc DTD
+SGML source file. Each formatter (or "back-end") renders the source file
+into a variety of output formats, including HTML, TeX, DVI, PostScript,
+plain text, and
+.BR groff (1)
+source in manual-page format. The linuxdoc suite is provided for backward
+compatibility, because there are still many useful documents written in
+LinuxDoc DTD sgml source.
+.LP
+The markup language(s) accepted by these formatters is described in the
+.IR Linuxdoc-Tools " User's " Guide .
+They are variants of an SGML document type definition originally
+designed by Matt Welsh for Linux documentation.
+.SH GENERIC-OPTIONS
+Most command-line options are accepted by all back-ends.  Some
+back-ends have additional specific options to control rendering to
+their particular output format.  Here are the common options:
+.IP "--backend=\fIformat\fR, -B
+Set the backend for specified format. Default is none of the actual
+format, but just output the usage of this suites.
+Available formats are: html, info, latex, lyx, rtf, txt, check.
+.IP "--papersize=\fIsize\fR, -p
+Set the paper size.  Default is ``a4'' (European 297x210mm paper).
+You may also specify ``letter'' size.
+.IP "--language=\fIlang\fR, -l"
+Specify the language of the document (this may change which style
+files are used for formatting by a back end).  The default language is
+English. Run an LinuxDoc-tools command without arguments to see the list
+of valid language codes.
+.IP "--charset=\fIchars\fR, -c"
+Specify the output character encoding.  Defaults to ``ascii''
+selecting the ASCII set; you may specify "latin" to specify the
+ISO 8859-1 (Latin-1) character set.
+Also, ``nippon'' and ``euc-kr'' is required to handle the euc-jp and
+euc-kr encoded sgml file.
+``utf-8'' is also accepted, although it is only partially supported.
+.IP "--style=\fIfile\fR, -S"
+Include an auxiliary DTD (Document Type Definition) from /usr/share/linuxdoc-tools/dtd.
+.IP "--tabsize=\fIn\fR, -t"
+Set the tab spacing assumed for generating the output document.  The
+default tab spacing is 8.
+.IP "--debug, -d"
+Don't delete intermediate files (such as .TeX files generated on the
+way to a .dvi, or .man files deleted on the way to plain text).
+.IP "--define, -D"
+Pass attribute/value pairs to be matched against "if" and "unless"
+conditionals.  See the User's Guide for extended discussion of this
+feature.
+This conditionalization are handled by sgmlpre command.
+See sgmlpre(1) as well as the User's Guide.
+.IP "--include, -i"
+Pass a \-i option to
+.BR nsgmls (1).
+This may be used for conditional inclusion.  See the
+.BR nsgmls (1)
+manual page for details.
+.IP "--pass, -P"
+Pass an option string to the back end.  The exact semantics of this
+option are dependent on the back end and should be explained in the
+individual manual pages for each.
+.IP file
+The SGML source file, named either
+.I file
+or
+.IR file.sgml .
+.LP
+Running a back-end with no arguments will cause it to list all its
+options (Error message about "no filenames given" can be ignored
+safely in this case).  The available back ends include (names in
+brackets are old & obsoleted form):
+.IP linuxdoc\ \-B\ html\ (sgml2html)
+translate to HTML
+.IP linuxdoc\ \-B\ info\ (sgml2info)
+translate to GNU info
+.IP linuxdoc\ \-B\ lyx\ (sgml2lyx)
+translate to Lyx macros
+.IP linuxdoc\ \-B\ latex\ (sgml2latex)
+translate to LaTeX 2e
+.IP linuxdoc\ \-B\ rtf\ (sgml2rtf)
+translate to Microsoft Rich Text Format
+.IP linuxdoc\ \-B\ txt\ (sgml2txt)
+translate to plain text or Unix manual-page markup
+.LP
+There is also a tool
+.BR linuxdoc -B check
+ (sgmlcheck)
+available for checking the Linuxdoc DTD SGML syntax of document sources
+without actually generating a translated version.
+.SH BACKEND-DRIVERS
+Here are the description for each backend drivers:
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B html \fP (sgml2html)
+converts a LinuxDoc DTD SGML source file to HTML output.
+Output will appear in the top level file
+.I file.html
+and
+.I file-n.html
+for each section (default action, but can be changed by option),
+where
+.I file
+is the name of the SGML source file and
+.I n
+is the section name.
+.LP
+The attribute/value pair "output=html" is set for conditionals.
+.LP
+.B linuxdoc -B html
+accepts the following options:
+.B [--split
+.I 0|1|2
+.B ] [--dosnames] [--imagebuttons]
+.B [--toc
+.I 0|1|2
+.B ]
+.LP
+The meanings of them are:
+.IP "--split, -s"
+What level to split source documents.  0 = don't split, 1 = split by
+major sections, 2 = split by subsections.
+.IP "--toc, -T"
+What level to generate toc.
+  0 = don't generate toc at all,
+  1 = includes major sections(/chapters/parts),
+  2 = includes subsections.
+.IP "--dosnames, -h"
+Use ".htm" rather than ".html" as the extension of
+.IP "--imagebuttons, -I"
+Use the "next", "previous", and "contents" arrow image icons included
+in /usr/share/linuxdoc-tools as navigation buttons.
+.IP "--footer, -F"
+Use the specified file as the footer in each resulted html file.
+Default footer is just plain
+
+.nh
+.nf
+.ad l
+ </BODY>\\n </HTML>\\n
+.hy
+.fi
+.IP "--header, -H"
+Use the specified file as the top part of the header in each resulted
+html file. Note this is not the full part of the header.
+(i.e. the title and the links (next,previous,contents) in the default
+header are retained. Default is
+
+.nh
+.nf
+.ad l
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\\n
+ <HTML>\\n <HEAD>\\n
+.hy
+.fi
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B info \fP (sgml2info)
+converts a LinuxDoc DTD SGML source file to GNU info format.
+Output will appear in
+.I file.info
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=info" is set for conditionals.
+.LP
+.B linuxdoc -B info
+has not backend specific options.
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B latex \fP (sgml2latex)
+converts a LinuxDoc DTD SGML source file to LaTeX output, using the
+.BR nsgmls (1)
+or
+.BR onsgmls (1)
+parser, and the
+.BR sgmlsasp (1)
+translator.  Using the LaTeX output, and the
+.BR latex (1)
+text formatter, you can then create DVI output, and PostScript output
+using the
+.BR dvips (1)
+converter. Output will appear in
+.I file.tex
+for LaTeX output,
+.I file.dvi
+for DVI output, or
+.I file.ps
+for PostScript output,
+where
+.I file
+is the name of the SGML source file.
+.LP
+Using  the LaTeX output, and the
+.BR pdflatex (1)
+text formatter, you can then create a nice PDF output, suitable for
+viewing with PDF viewers as
+.BR xpdf (1),
+.BR acroread (1)
+or
+.BR ghostview (1).
+.LP
+The attribute/value pair "output=latex2e" is set for conditionals.
+.LP
+.B linuxdoc -B latex
+accepts following backend specific options:
+.BI [--output= tex | dvi | ps | pdf]
+.B [--bibtex] [--makeindex]
+.BI [--pagenumber= n ]
+.B --quick
+.BI [--latex= latex | hlatexp | platex | jlatex]
+.BI [--dvips= dvips | dvi2ps]
+.BI [--verbosity=n]
+.LP
+The meanings of them are:
+.IP "--output=\fIfmt\fR, -o"
+Specify the desired output format.  The specifier
+.I fmt
+may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
+.PP
+Note: This version does not overwrite/remove the intermediate
+files: tex file for dvi output, or tex/dvi files for ps output.
+This is different behavior from the original SGML-Tools 1.0.9,
+so you are warned here.
+.IP "--bibtex, -b"
+Process the generated TeX with
+.BR bibtex (1).
+.IP "--makeindex, -m"
+Generate a TeX index file suitable for processing with
+.BR makeindex (1)
+from and <idx> and <cdx> tags present in the SGML source.
+.IP "--pagenumber, -n"
+Set the starting page number in the output DVI or PS file.
+.IP "--quick, -q"
+Do only one pass of LaTeX formatting.  This is often not sufficient
+to produce final output (because of references, etc.) but is useful
+for spotting TeX errors and justification problems.
+.IP "--pass, -P"
+The argument of the pass option is inserted just after the LaTeX
+preamble generated by the document-type tag.
+Specify the desired output format.  The specifier
+.I fmt
+may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
+.IP "--latex=\fIalternate_latex_command\fR, -x"
+This option is currently for Korean and Japanese.
+The
+.I alternate_latex_command
+can be ``latex'' (default), ``hlatexp'' (for Korean), ``platex''
+or ``jlatex'' (for Japanese).
+This option can be used to render Korean document using HLaTeXp,
+or to render Japanese document using pLaTeX/jLaTeX.
+If not, HLaTeX should be installed to render Korean document.
+On the other hand, Japanese document can be rendered with jLaTeX
+ (which is the default when ``\-c nippon'' is specified), so if you
+already have jLaTeX, you may not need to install the pLaTeX.
+.IP "--dvips=\fIalternate_dvips_command\fR, -s"
+This option is currently for Japanese.
+The
+.I alternate_dvips_command
+can be ``dvips'' or ``dvi2ps''.  If you don't know this, then
+you may not need this.
+.IP "--verbosity, -V"
+Set verbosity. '0' (default) will show info about LaTeX run only
+in case of errors. '1' will always show info for last run. '2'
+will show info for all runs.
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B lyx \fP (sgml2lyx)
+converts a LinuxDoc DTD SGML source file to LyX output.
+Output will appear in
+.I file.lyx
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=lyx" is set for conditionals.
+.LP
+.B linuxdoc -B lyx
+has not backend specific options.
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B rtf \fP (sgml2rtf)
+converts a LinuxDoc DTD SGML source file to RTF, the Rich Text Tormat
+used by the Microsoft Windows help system. Output will appear in the top
+level file
+.I file.rtf
+and
+.I file-n.rtf
+for each section, where
+.I file
+is the name of the SGML source file.  The RTF output is tailored for
+compilation by the Windows Help Compiler (hc31.exe).
+.LP
+The attribute/value pair "output=rtf" is set for conditionals.
+.LP
+.B linuxdoc -B rtf
+accepts
+.B [--twosplit]
+as a backend specific option.
+Following is the meaning of this option:
+.IP "--twosplit, -2"
+Splits files both at n. sections and n.m. subsections
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B txt \fP (sgml2txt)
+converts a LinuxDoc DTD SGML source file to ASCII, ISO-8859-1, or EUC-JP
+output. Output will appear in
+.I file.txt
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=txt" is set for conditionals.
+.LP
+.B linuxdoc -B txt
+accepts following backend-options:
+.B [--manpage] [--filter] [--blanks=\fIn\fB]
+.LP
+The meaning of these options are:
+.IP "--manpage, -m"
+Outputs a groff source file, suitable for formatting with
+.B groff -man
+for man pages
+.IP "--filter, -f"
+Remove backspace-overstrikes from the intermediate form generated by
+\fBgroff\fR(1).
+.IP "--pass, -P"
+The argument of the pass option is added to the command-line options
+handed to
+.BR groff (1).
+.IP "--blanks=\fIn\fR, -b"
+Set the limit of continuous blank lines for generating the output
+document.  The default limit is 3. if 0 (zero) is specified,
+the result have many continuous blank lines.
+.LP
+ ****************************************************
+.LP
+.B linuxdoc -B check \fP (sgmlcheck)
+runs an SGML parse on the specified document source.  Any errors are
+reported to standard output.  No formatted version of the source is
+produced.
+.LP
+Note that
+.B linuxdoc -B check
+preprocesses the LinuxDoc DTD SGML source, doing the conditionalization
+described by any <#if></#if> and <#unless></#unless> tags.
+Document sources containing these tags will confuse a standalone SGML parser.
+.B linuxdoc -B check
+has no backend-specific options.
+ ****************************************************
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+Maybe some are left.  Feel free to send your report to the current maintainer.
+.SH MAINTAINER
+This had been maintained by Cees de Groot <cg@cdegroot.com> in SGML-Tools (v1).
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
diff --git a/upstream/mageia-cauldron/man1/lispmtopgm.1 b/upstream/mageia-cauldron/man1/lispmtopgm.1
new file mode 100644
index 00000000..d4cdb7b3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lispmtopgm.1
@@ -0,0 +1,75 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Lispmtopgm User Manual" 0 "06 March 1990" "netpbm documentation"
+
+.SH NAME
+lispmtopgm - convert a Lisp Machine bitmap file to PGM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBlispmtopgm\fP
+[\fIlispmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBlistpmfile\fP reads a Lisp Machine bitmap as input and
+produces a PGM image as output.
+.PP
+This is the file format written by the tv:write-bit-array-file
+function on TI Explorer and Symbolics lisp machines.
+.PP
+Multi-plane bitmaps on lisp machines are color; but the Lispm image
+file format does not include a color map, so we must treat it as a
+monochrome instead and produce PGM.  This is unfortunate.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBlispmtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtolispm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN limitations
+.SH LIMITATIONS
+
+The Lispm bitmap file format is a bit quirky;  Usually the image in the file
+has its width rounded up to the next higher multiple of 32, but not always.
+If the width is not a multiple of 32, we don't deal with it properly, but 
+because of the Lispm microcode, such arrays are probably not image data 
+anyway.
+.PP
+Also, the Lispm code for saving bitmaps has a bug, in that if you
+are writing a bitmap which is not mod32 across, the file may be up to
+7 bits too short!  They round down instead of up, and we don't handle
+this bug gracefully.
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/lispmtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/list_audio_tracks.1 b/upstream/mageia-cauldron/man1/list_audio_tracks.1
new file mode 100644
index 00000000..b4a1dd0c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/list_audio_tracks.1
@@ -0,0 +1,54 @@
+.TH "LIST_AUDIO_TRACKS" "1" "Tue Feb 15 13:03:51 MST 2005" "" "list_audio_tracks"
+
+.PP
+.SH "NAME"
+list_audio_tracks is an alias for icedax.
+.PP
+.SH "SYNOPSIS"
+.PP
+\fBlist_audio-tracks\fP
+.PP
+.SH "DESCRIPTION"
+.PP
+\fBlist_audio_tracks\fP equals to the invocation of icedax, so all the
+arguments for the latter can be used.
+.PP
+.SH SEE ALSO
+icedax(1)
+.PP 
+.SH "AUTHOR" 
+.PP 
+\fBicedax\fP was written by Heiko Eissfeldt and others.
+.PP 
+This manpage describes the program implementation of
+.B
+list_audio_tracks
+as shipped by the cdrkit distribution. See
+.B
+http://alioth.debian.org/projects/debburn/
+for details. It is a spinoff from the original program called cdda2wav
+distributed by the cdrtools project. However, the cdrtools developers are not
+involved in the development of this spinoff and therefore shall not be made
+responsible for any problem caused by it. Do not try to get support for this
+program by contacting the original authors.
+.PP
+If you have support questions, send them to
+.PP
+.B
+debburn-devel@lists.alioth.debian.org
+.br
+.PP
+If you have definitely found a bug, send a mail to this list or to
+.PP
+.B
+submit@bugs.debian.org
+.br
+.PP
+writing at least a short description into the Subject and "Package: cdrkit" into the first line of the mail body.
+.PP
+This manual page was written by Oleksandr Moskalenko
+<malex@tagancha\&.org>, for
+the Debian GNU/Linux system\&.  It may be used by other distributions
+without contacting the author\&.  Any mistakes or omissions in the
+manual page are my fault; inquiries about or corrections to this
+manual page should be directed to me (and not to the primary author)\&.
diff --git a/upstream/mageia-cauldron/man1/lkbib.1 b/upstream/mageia-cauldron/man1/lkbib.1
new file mode 100644
index 00000000..1bce667e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lkbib.1
@@ -0,0 +1,166 @@
+.TH LKBIB 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+lkbib \- search bibliographic databases
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY lkbib
+.OP \-n
+.OP \-i fields
+.OP \-p filename
+.OP \-t n
+.I key
+\&.\|.\|.\&
+.YS
+.
+.SY lkbib
+.B \-\-help
+.YS
+.
+.SY lkbib
+.B \-v
+.SY lkbib
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I lkbib
+searches bibliographic databases for references that contain the keys
+.I key
+\&.\|.\|.\& and prints any references found on the standard output.
+.
+.I lkbib
+will search any databases given by
+.B \-p
+options, and then a default database.
+.
+The default database is taken from the
+.I \%REFER
+environment variable if it is set,
+otherwise it is
+.IR /usr/\:dict/\:papers/\:Ind .
+.
+For each database
+.I filename
+to be searched,
+if an index
+.RI filename .i
+created by
+.IR indxbib (1)
+exists, then it will be searched instead;
+each index can cover multiple databases.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-\-help
+Display a usage message and exit.
+.
+.
+.TP
+.BI \-i string
+When searching files for which no index exists,
+ignore the contents of fields whose names are in
+.IR string .
+.
+.
+.TP
+.BI \-p filename
+Search
+.IR filename .
+.
+Multiple
+.B \-p
+options can be used.
+.
+.
+.TP
+.BI \-t n
+Only require the first
+.I n
+characters of keys to be given.
+.
+Initially
+.I n
+is\~6.
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I REFER
+Default database.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:dict/\:papers/\:Ind
+Default database to be used if the
+.I \%REFER
+environment variable is not set.
+.
+.
+.TP
+.RI filename .i
+Index files.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.IR refer (1),
+.IR lookbib (1),
+.IR indxbib (1)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/ln.1 b/upstream/mageia-cauldron/man1/ln.1
new file mode 100644
index 00000000..a8b90c7d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ln.1
@@ -0,0 +1,119 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH LN "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+ln \- make links between files
+.SH SYNOPSIS
+.B ln
+[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,TARGET LINK_NAME\/\fR
+.br
+.B ln
+[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR
+.br
+.B ln
+[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR... \fI\,DIRECTORY\/\fR
+.br
+.B ln
+[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY TARGET\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+In the 1st form, create a link to TARGET with the name LINK_NAME.
+In the 2nd form, create a link to TARGET in the current directory.
+In the 3rd and 4th forms, create links to each TARGET in DIRECTORY.
+Create hard links by default, symbolic links with \fB\-\-symbolic\fR.
+By default, each destination (name of new link) should not already exist.
+When creating hard links, each TARGET must exist.  Symbolic links
+can hold arbitrary text; if later resolved, a relative link is
+interpreted in relation to its parent directory.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-backup\fR[=\fI\,CONTROL\/\fR]
+make a backup of each existing destination file
+.TP
+\fB\-b\fR
+like \fB\-\-backup\fR but does not accept an argument
+.TP
+\fB\-d\fR, \fB\-F\fR, \fB\-\-directory\fR
+allow the superuser to attempt to hard link
+directories (note: will probably fail due to
+system restrictions, even for the superuser)
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+remove existing destination files
+.TP
+\fB\-i\fR, \fB\-\-interactive\fR
+prompt whether to remove destinations
+.TP
+\fB\-L\fR, \fB\-\-logical\fR
+dereference TARGETs that are symbolic links
+.TP
+\fB\-n\fR, \fB\-\-no\-dereference\fR
+treat LINK_NAME as a normal file if
+it is a symbolic link to a directory
+.TP
+\fB\-P\fR, \fB\-\-physical\fR
+make hard links directly to symbolic links
+.TP
+\fB\-r\fR, \fB\-\-relative\fR
+with \fB\-s\fR, create links relative to link location
+.TP
+\fB\-s\fR, \fB\-\-symbolic\fR
+make symbolic links instead of hard links
+.TP
+\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+override the usual backup suffix
+.TP
+\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR
+specify the DIRECTORY in which to create
+the links
+.TP
+\fB\-T\fR, \fB\-\-no\-target\-directory\fR
+treat LINK_NAME as a normal file always
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print name of each linked file
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX.
+The version control method may be selected via the \fB\-\-backup\fR option or through
+the VERSION_CONTROL environment variable.  Here are the values:
+.TP
+none, off
+never make backups (even if \fB\-\-backup\fR is given)
+.TP
+numbered, t
+make numbered backups
+.TP
+existing, nil
+numbered if numbered backups exist, simple otherwise
+.TP
+simple, never
+always make simple backups
+.PP
+Using \fB\-s\fR ignores \fB\-L\fR and \fB\-P\fR.  Otherwise, the last option specified controls
+behavior when a TARGET is a symbolic link, defaulting to \fB\-P\fR.
+.SH AUTHOR
+Written by Mike Parker and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBlink\fP(2), \fBsymlink\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/ln>
+.br
+or available locally via: info \(aq(coreutils) ln invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/loadkeys.1 b/upstream/mageia-cauldron/man1/loadkeys.1
new file mode 100644
index 00000000..369ddcb9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/loadkeys.1
@@ -0,0 +1,212 @@
+.\" @(#)loadkeys.1
+.TH LOADKEYS 1 "6 Feb 1994" "kbd"
+.SH NAME
+loadkeys \- load keyboard translation tables
+.SH SYNOPSIS
+.B loadkeys
+[\fI\,OPTION\/\fR]... \fI\,FILENAME\/\fR...
+.br
+.B loadkeys
+.I --default
+.br
+.B loadkeys
+.I --mktable
+.br
+.B loadkeys
+.I --bkeymap
+.br
+.B loadkeys
+.I --parse
+.LP
+.SH DESCRIPTION
+.IX "loadkeys command" "" "\fLloadkeys\fR command"
+.LP
+The program
+.B loadkeys
+reads the file or files specified by
+.IR FILENAME... .
+Its main purpose is to load the kernel keymap for the console.
+You can specify console device by the
+.I -C
+(or
+.I --console
+) option.
+.SH "RESET TO DEFAULT"
+If the
+.I -d
+(or
+.I --default
+) option is given,
+.B loadkeys
+loads a default keymap, probably the file
+.I defkeymap.map
+either in
+.I /usr/lib/kbd/keymaps
+or in
+.IR /usr/src/linux/drivers/char .
+(Probably the former was user-defined, while the latter
+is a qwerty keyboard map for PCs - maybe not what was desired.)
+Sometimes, with a strange keymap loaded (with the minus on
+some obscure unknown modifier combination) it is easier to
+type `loadkeys defkeymap'.
+.SH "LOAD KERNEL KEYMAP"
+The main function of
+.B loadkeys
+is to load or modify the keyboard driver's translation tables.
+When specifying the file names, standard input can be denoted
+by dash (-). If no file is specified, the data is read from
+the standard input.
+.LP
+For many countries and keyboard types appropriate keymaps
+are available already, and a command like `loadkeys uk' might
+do what you want. On the other hand, it is easy to construct
+one's own keymap. The user has to tell what symbols belong
+to each key. She can find the keycode for a key by use of
+.BR showkey (1),
+while the keymap format is given in
+.BR keymaps (5)
+and can also be seen from the output of
+.BR dumpkeys (1).
+.SH "LOAD KERNEL ACCENT TABLE"
+If the input file does not contain any compose key definitions,
+the kernel accent table is left unchanged, unless the
+.I -c
+(or
+.I --clearcompose
+) option is given, in which case the kernel accent table is emptied.
+If the input file does contain compose key definitions, then all
+old definitions are removed, and replaced by the specified new entries.
+The kernel accent table is a sequence of (by default 68) entries
+describing how dead diacritical signs and compose keys behave.
+For example, a line
+.LP
+.RS
+compose ',' 'c' to ccedilla
+.RE
+.LP
+means that <ComposeKey><,><c> must be combined to <ccedilla>.
+The current content of this table can be see
+using `dumpkeys \-\-compose\-only'.
+.SH "LOAD KERNEL STRING TABLE"
+The option
+.I -s
+(or
+.I --clearstrings
+) clears the kernel string table. If this option is not given,
+.B loadkeys
+will only add or replace strings, not remove them.
+(Thus, the option \-s is required to reach a well-defined state.)
+The kernel string table is a sequence of strings
+with names like F31. One can make function key F5 (on
+an ordinary PC keyboard) produce the text `Hello!',
+and Shift+F5 `Goodbye!' using lines
+.LP
+.RS
+keycode 63 = F70 F71
+.br
+string F70 = "Hello!"
+.br
+string F71 = "Goodbye!"
+.RE
+.LP
+in the keymap.
+The default bindings for the function keys are certain
+escape sequences mostly inspired by the VT100 terminal.
+.SH "CREATE KERNEL SOURCE TABLE"
+If the
+.I -m
+(or
+.I --mktable
+) option is given
+.B loadkeys
+prints to the standard output a file that may be used as
+.I /usr/src/linux\%/drivers\%/char\%/defkeymap.c,
+specifying the default key bindings for a kernel
+(and does not modify the current keymap).
+.SH "CREATE BINARY KEYMAP"
+If the
+.I -b
+(or
+.I --bkeymap
+) option is given
+.B loadkeys
+prints to the standard output a file that may be used as a binary
+keymap as expected by Busybox
+.B loadkmap
+command (and does not modify the current keymap).
+.SH "UNICODE MODE"
+.B loadkeys
+automatically detects whether the console is in Unicode or
+ASCII (XLATE) mode.  When a keymap is loaded, literal
+keysyms (such as
+.BR section )
+are resolved accordingly; numerical keysyms are converted to
+fit the current console mode, regardless of the way they are
+specified (decimal, octal, hexadecimal or Unicode).
+.LP
+The
+.I -u
+(or
+.IR --unicode )
+switch forces
+.B loadkeys
+to convert all keymaps to Unicode.  If the keyboard is in a
+non-Unicode mode, such as XLATE,
+.B loadkeys
+will change it to Unicode for the time of its execution.  A
+warning message will be printed in this case.
+.LP
+It is recommended to run
+.BR kbd_mode (1)
+before
+.B loadkeys
+instead of using the
+.I -u
+option.
+.SH "OTHER OPTIONS"
+.TP
+.B \-a \-\-ascii
+Force conversion to ASCII.
+.TP
+.B \-h \-\-help
+.B loadkeys
+prints its version number and a short usage message to the programs
+standard error output and exits.
+.TP
+.B \-p \-\-parse
+.B loadkeys
+searches and parses keymap without action.
+.TP
+.B \-q \-\-quiet
+.B loadkeys
+suppresses all normal output.
+.TP
+.B \-V \-\-version
+.B loadkeys
+prints version number and exits.
+.SH WARNING
+Note that anyone having read access to
+.B /dev/console
+can run
+.B loadkeys
+and thus change the keyboard layout, possibly making it unusable. Note
+that the keyboard translation table is common for all the virtual
+consoles, so any changes to the keyboard bindings affect all the virtual
+consoles simultaneously.
+.LP
+Note that because the changes affect all the virtual consoles, they also
+outlive your session. This means that even at the login prompt the key
+bindings may not be what the user expects.
+.SH FILES
+.TP
+.I /usr/lib/kbd/keymaps
+default directory for keymaps.
+.LP
+.TP
+.I /usr/src/linux/drivers/char/defkeymap.map
+default kernel keymap.
+.LP
+.SH "SEE ALSO"
+.BR dumpkeys (1),
+.BR keymaps (5)
+
diff --git a/upstream/mageia-cauldron/man1/localectl.1 b/upstream/mageia-cauldron/man1/localectl.1
new file mode 100644
index 00000000..f4bdf58c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/localectl.1
@@ -0,0 +1,404 @@
+'\" t
+.TH "LOCALECTL" "1" "" "systemd 255" "localectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+localectl \- Control the system locale and keyboard layout settings
+.SH "SYNOPSIS"
+.HP \w'\fBlocalectl\fR\ 'u
+\fBlocalectl\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+\fBlocalectl\fR
+may be used to query and change the system locale and keyboard layout settings\&. It communicates with
+\fBsystemd-localed\fR(8)
+to modify files such as
+/etc/locale\&.conf
+and
+/etc/vconsole\&.conf\&.
+.PP
+The system locale controls the language settings of system services and of the UI before the user logs in, such as the display manager, as well as the default for users after login\&.
+.PP
+The keyboard settings control the keyboard layout used on the text console and of the graphical UI before the user logs in, such as the display manager, as well as the default for users after login\&.
+.PP
+Note that the changes performed using this tool might require the initrd to be rebuilt to take effect during early system boot\&. The initrd is not rebuilt automatically by
+localectl, this task has to be performed manually, usually using a tool like
+\fBdracut\fR(8)\&.
+.PP
+Note that
+\fBsystemd-firstboot\fR(1)
+may be used to initialize the system locale for mounted (but not booted) system images\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBstatus\fR
+.RS 4
+Show current settings of the system locale and keyboard mapping\&. If no command is specified, this is the implied default\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-locale LOCALE\fR, \fBset\-locale VARIABLE=LOCALE\&...\fR
+.RS 4
+Set the system locale\&. This takes one locale such as
+"en_US\&.UTF\-8", or takes one or more locale assignments such as
+"LANG=de_DE\&.utf8",
+"LC_MESSAGES=en_GB\&.utf8", and so on\&. If one locale without variable name is provided, then
+"LANG="
+locale variable will be set\&. See
+\fBlocale\fR(7)
+for details on the available settings and their meanings\&. Use
+\fBlist\-locales\fR
+for a list of available locales (see below)\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBlist\-locales\fR
+.RS 4
+List available locales useful for configuration with
+\fBset\-locale\fR\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-keymap MAP [TOGGLEMAP]\fR
+.RS 4
+Set the system keyboard mapping for the console and X11\&. This takes a mapping name (such as "de" or "us"), and possibly a second one to define a toggle keyboard mapping\&. Unless
+\fB\-\-no\-convert\fR
+is passed, the selected setting is also applied as the default system keyboard mapping of X11, after converting it to the closest matching X11 keyboard mapping\&. Use
+\fBlist\-keymaps\fR
+for a list of available keyboard mappings (see below)\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBlist\-keymaps\fR
+.RS 4
+List available keyboard mappings for the console, useful for configuration with
+\fBset\-keymap\fR\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-x11\-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]\fR
+.RS 4
+Set the system default keyboard mapping for X11 and the virtual console\&. This takes a keyboard mapping name (such as
+"de"
+or
+"us"), and possibly a model, variant, and options, see
+\fBkbd\fR(4)
+for details\&. Unless
+\fB\-\-no\-convert\fR
+is passed, the selected setting is also applied as the system console keyboard mapping, after converting it to the closest matching console keyboard mapping\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBlist\-x11\-keymap\-models\fR, \fBlist\-x11\-keymap\-layouts\fR, \fBlist\-x11\-keymap\-variants [LAYOUT]\fR, \fBlist\-x11\-keymap\-options\fR
+.RS 4
+List available X11 keymap models, layouts, variants and options, useful for configuration with
+\fBset\-keymap\fR\&. The command
+\fBlist\-x11\-keymap\-variants\fR
+optionally takes a layout parameter to limit the output to the variants suitable for the specific layout\&.
+.sp
+Added in version 201\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-no\-convert\fR
+.RS 4
+If
+\fBset\-keymap\fR
+or
+\fBset\-x11\-keymap\fR
+is invoked and this option is passed, then the keymap will not be converted from the console to X11, or X11 to console, respectively\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBlocale\fR(7),
+\fBlocale.conf\fR(5),
+\fBvconsole.conf\fR(5),
+\fBloadkeys\fR(1),
+\fBkbd\fR(4),
+\m[blue]\fBThe XKB Configuration Guide\fR\m[]\&\s-2\u[1]\d\s+2,
+\fBsystemctl\fR(1),
+\fBsystemd-localed.service\fR(8),
+\fBsystemd-firstboot\fR(1),
+\fBdracut\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+The XKB Configuration Guide
+.RS 4
+\%http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html
+.RE
diff --git a/upstream/mageia-cauldron/man1/lockfile.1 b/upstream/mageia-cauldron/man1/lockfile.1
new file mode 100644
index 00000000..1ae5ddc3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lockfile.1
@@ -0,0 +1,285 @@
+.\"if n .pl +(135i-\n(.pu)
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.Id $Id$
+.TH LOCKFILE 1 \*(Dt BuGless
+.rn SH Sh
+.de SH
+.br
+.ne 11
+.Sh "\\$1"
+..
+.rn SS Ss
+.de SS
+.br
+.ne 10
+.Ss "\\$1"
+..
+.rn TP Tp
+.de TP
+.br
+.ne 9
+.Tp \\$1
+..
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.na
+.SH NAME
+lockfile \- conditional semaphore-file creator
+.SH SYNOPSIS
+.B lockfile
+.I "\fB\-\fPsleeptime"
+|
+.I "\fB\-r \fPretries"
+|
+.if n .ti +0.5i
+.I "\fB\-l \fPlocktimeout"
+|
+.I "\fB\-s \fPsuspend"
+|
+.B "\-!"
+|
+.B "\-ml"
+|
+.B "\-mu"
+|
+.I filename
+\&.\|.\|.
+.ad
+.SH DESCRIPTION
+.B lockfile
+can be used to create one or more
+.I semaphore
+.IR files .
+If lockfile can't create all the specified files (in the specified order),
+it waits
+.I sleeptime
+(defaults to 8) seconds and retries the last file that didn't
+succeed.  You can specify the number of
+.I retries
+to do until failure is returned.
+If the number of
+.I retries
+is \-1 (default, i.e.,
+.BR \-r\-1 )
+lockfile will retry forever.
+.PP
+If the number of
+.I retries
+expires before all files have been created, lockfile returns failure and
+removes all the files it created up till that point.
+.PP
+Using lockfile as the condition of a loop in a shell script can be done
+easily by using the
+.B \-!
+flag to invert the exit status.  To prevent infinite loops, failures
+for any reason other than the lockfile already existing are not
+inverted to success but rather are still returned as failures.
+.PP
+All flags can be specified anywhere on the command line, they will be
+processed when encountered.  The command line is simply parsed from
+left to right.
+.PP
+All files created by lockfile will be read-only, and therefore
+will have to be removed with
+.B rm
+.BR \-f .
+.PP
+If you specify a
+.I locktimeout
+then a lockfile will be removed by force after locktimeout seconds have
+passed since the lockfile was last modified/created (most likely by some
+other program that unexpectedly died a long time ago, and hence could not clean
+up any leftover lockfiles).  Lockfile is clock skew immune.  After a lockfile
+has been removed by force, a suspension of
+.I suspend
+seconds (defaults to 16) is taken into account, in order to prevent
+the inadvertent immediate removal of any newly created lockfile by another
+program (compare
+.BR SUSPEND
+in
+.BR procmail (1)).
+.SS "Mailbox locks"
+If the permissions on the system mail spool directory allow it, or if lockfile
+is suitably setgid, it will be able to lock and unlock your system mailbox by
+using the options
+.B "\-ml"
+and
+.B "\-mu"
+respectively.
+.SH EXAMPLES
+Suppose you want to make sure that access to the file "important" is
+serialised, i.e., no more than one program or shell script should be allowed
+to access it.  For simplicity's sake, let's suppose that it is a shell
+script.  In this case you could solve it like this:
+.RS
+\&.\|.\|.
+lockfile important.lock
+\&.\|.\|.
+access_"important"_to_your_hearts_content
+\&.\|.\|.
+rm \-f important.lock
+\&.\|.\|.
+.RE
+Now if all the scripts that access "important" follow this guideline, you
+will be assured that at most one script will be executing between the
+`lockfile' and the `rm' commands.
+.SH ENVIRONMENT
+.TP 2.3i
+.B LOGNAME
+used as a hint to determine the invoker's loginname
+.SH FILES
+.TP 2.3i
+.B /etc/passwd
+to verify and/or correct the invoker's loginname (and to find out his HOME
+directory, if needed)
+.TP
+.B /var/spool/mail/$LOGNAME.lock
+lockfile for the system mailbox, the environment variables present in here
+will not be taken from the environment, but will be determined by looking
+in /etc/passwd
+.SH "SEE ALSO"
+.na
+.nh
+.BR rm (1),
+.BR mail (1),
+.BR sendmail (8),
+.BR procmail (1)
+.hy
+.ad
+.SH DIAGNOSTICS
+.TP 2.3i
+Filename too long, .\|.\|.
+Use shorter filenames.
+.TP
+Forced unlock denied on "x"
+No write permission in the directory where lockfile "x" resides, or more than
+one lockfile trying to force a lock at exactly the same time.
+.TP
+Forcing lock on "x"
+Lockfile "x" is going to be removed by force because of a timeout
+(compare
+.BR LOCKTIMEOUT
+in
+.BR procmail (1)).
+.TP
+Out of memory, .\|.\|.
+The system is out of swap space.
+.TP
+Signal received, .\|.\|.
+Lockfile will remove anything it created till now and terminate.
+.TP
+Sorry, .\|.\|.
+The
+.I retries
+limit has been reached.
+.TP
+Truncating "x" and retrying lock
+"x" does not seem to be a valid filename.
+.TP
+Try praying, .\|.\|.
+Missing subdirectories or insufficient privileges.
+.SH BUGS
+Definitely less than one.
+.SH WARNINGS
+The behavior of the
+.B \-!
+flag, while useful, is not necessarily intuitive or consistent.  When
+testing lockfile's return value, shell script writers should consider
+carefully whether they want to use the
+.B \-!
+flag, simply reverse the test, or do a switch on the exact exitcode.
+In general, the
+.B \-!
+flag should only be used when lockfile is the conditional of a loop.
+.SH MISCELLANEOUS
+Lockfile is NFS-resistant and eight-bit clean.
+.SH NOTES
+Calling up lockfile with the \-h or \-? options will cause
+it to display a command-line help page.  Calling it up with the \-v
+option will cause it to display its version information.
+.PP
+Multiple
+.B \-!
+flags will toggle the return status.
+.PP
+Since flags can occur anywhere on the command line, any filename starting
+with a '-' has to be preceded by './'.
+.PP
+The number of
+.I retries
+will not be reset when any following file is being created (i.e., they are
+simply used up).  It can, however, be reset by specifying
+.RI \-r newretries
+after every file on the command line.
+.PP
+Although files with any name can be used as lockfiles, it is common practice
+to use the extension `.lock' to lock mailfolders (it is appended to the
+mailfolder name).  In case one does not want to have to worry about too long
+filenames and does not have to conform to any other lockfilename convention,
+then an excellent way to generate a lockfilename corresponding to some already
+existing file is by taking the prefix `lock.' and appending the i-node number
+of the file which is to be locked.
+.Sh SOURCE
+This program is part of the
+.I procmail mail-processing-package
+(v3.24) available at http://www.procmail.org/ or
+ftp.procmail.org in
+.BR pub/procmail/ .
+.Sh MAILINGLIST
+There exists a mailinglist for questions relating to any program in the
+procmail package:
+.RS
+<procmail-users@procmail.org>
+.RS
+for submitting questions/answers.
+.RE
+<procmail-users-request@procmail.org>
+.RS
+for subscription requests.
+.RE
+.PP
+.RE
+If you would like to stay informed about new versions and official patches send
+a subscription request to
+.RS
+procmail-announce-request@procmail.org
+.RE
+(this is a readonly list).
+.SH AUTHORS
+Stephen R. van den Berg
+.RS
+<srb@cuci.nl>
+.RE
+.\".if n .pl -(\n(.tu-1i)
+.rm SH
+.rn Sh SH
+.rm SS
+.rn Ss SS
+.rm TP
+.rn Tp TP
+.rm RS
+.rn Rs RS
+.rm RE
+.rn Re RE
diff --git a/upstream/mageia-cauldron/man1/loginctl.1 b/upstream/mageia-cauldron/man1/loginctl.1
new file mode 100644
index 00000000..1670c1ba
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/loginctl.1
@@ -0,0 +1,587 @@
+'\" t
+.TH "LOGINCTL" "1" "" "systemd 255" "loginctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+loginctl \- Control the systemd login manager
+.SH "SYNOPSIS"
+.HP \w'\fBloginctl\fR\ 'u
+\fBloginctl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBloginctl\fR
+may be used to introspect and control the state of the
+\fBsystemd\fR(1)
+login manager
+\fBsystemd-logind.service\fR(8)\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.SS "Session Commands"
+.PP
+\fBlist\-sessions\fR
+.RS 4
+List current sessions\&.
+.RE
+.PP
+\fBsession\-status\fR [\fIID\fR\&...]
+.RS 4
+Show terse runtime status information about one or more sessions, followed by the most recent log data from the journal\&. Takes one or more session identifiers as parameters\&. If no session identifiers are passed, the status of the caller\*(Aqs session is shown\&. This function is intended to generate human\-readable output\&. If you are looking for computer\-parsable output, use
+\fBshow\-session\fR
+instead\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBshow\-session\fR [\fIID\fR\&...]
+.RS 4
+Show properties of one or more sessions or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a session ID is specified, properties of the session are shown\&. Specially, if the given ID is
+"self", the session to which the
+\fBloginctl\fR
+process belongs is used\&. If
+"auto", the current session is used as with
+"self"
+if exists, and falls back to the current user\*(Aqs graphical session\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBsession\-status\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBactivate\fR [\fIID\fR]
+.RS 4
+Activate a session\&. This brings a session into the foreground if another session is currently in the foreground on the respective seat\&. Takes a session identifier as argument\&. If no argument is specified, the session of the caller is put into foreground\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBlock\-session\fR [\fIID\fR\&...], \fBunlock\-session\fR [\fIID\fR\&...]
+.RS 4
+Activates/deactivates the screen lock on one or more sessions, if the session supports it\&. Takes one or more session identifiers as arguments\&. If no argument is specified, the session of the caller is locked/unlocked\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBlock\-sessions\fR, \fBunlock\-sessions\fR
+.RS 4
+Activates/deactivates the screen lock on all current sessions supporting it\&.
+.sp
+Added in version 188\&.
+.RE
+.PP
+\fBterminate\-session\fR \fIID\fR\&...
+.RS 4
+Terminates a session\&. This kills all processes of the session and deallocates all resources attached to the session\&. If the argument is specified as empty string the session invoking the command is terminated\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBkill\-session\fR \fIID\fR\&...
+.RS 4
+Send a signal to one or more processes of the session\&. Use
+\fB\-\-kill\-whom=\fR
+to select which process to kill\&. Use
+\fB\-\-signal=\fR
+to select the signal to send\&. If the argument is specified as empty string the signal is sent to the session invoking the command\&.
+.sp
+Added in version 233\&.
+.RE
+.SS "User Commands"
+.PP
+\fBlist\-users\fR
+.RS 4
+List currently logged in users\&.
+.RE
+.PP
+\fBuser\-status\fR [\fIUSER\fR\&...]
+.RS 4
+Show terse runtime status information about one or more logged in users, followed by the most recent log data from the journal\&. Takes one or more user names or numeric user IDs as parameters\&. If no parameters are passed, the status is shown for the user of the session of the caller\&. This function is intended to generate human\-readable output\&. If you are looking for computer\-parsable output, use
+\fBshow\-user\fR
+instead\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBshow\-user\fR [\fIUSER\fR\&...]
+.RS 4
+Show properties of one or more users or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a user is specified, properties of the user are shown\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBuser\-status\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBenable\-linger\fR [\fIUSER\fR\&...], \fBdisable\-linger\fR [\fIUSER\fR\&...]
+.RS 4
+Enable/disable user lingering for one or more users\&. If enabled for a specific user, a user manager is spawned for the user at boot and kept around after logouts\&. This allows users who are not logged in to run long\-running services\&. Takes one or more user names or numeric UIDs as argument\&. If no argument is specified, enables/disables lingering for the user of the session of the caller\&.
+.sp
+See also
+\fIKillUserProcesses=\fR
+setting in
+\fBlogind.conf\fR(5)\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBterminate\-user\fR \fIUSER\fR\&...
+.RS 4
+Terminates all sessions of a user\&. This kills all processes of all sessions of the user and deallocates all runtime resources attached to the user\&. If the argument is specified as empty string the sessions of the user invoking the command are terminated\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBkill\-user\fR \fIUSER\fR\&...
+.RS 4
+Send a signal to all processes of a user\&. Use
+\fB\-\-signal=\fR
+to select the signal to send\&. If the argument is specified as empty string the signal is sent to the sessions of the user invoking the command\&.
+.sp
+Added in version 233\&.
+.RE
+.SS "Seat Commands"
+.PP
+\fBlist\-seats\fR
+.RS 4
+List currently available seats on the local system\&.
+.RE
+.PP
+\fBseat\-status\fR [\fINAME\fR\&...]
+.RS 4
+Show terse runtime status information about one or more seats\&. Takes one or more seat names as parameters\&. If no seat names are passed the status of the caller\*(Aqs session\*(Aqs seat is shown\&. This function is intended to generate human\-readable output\&. If you are looking for computer\-parsable output, use
+\fBshow\-seat\fR
+instead\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBshow\-seat\fR [\fINAME\fR\&...]
+.RS 4
+Show properties of one or more seats or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a seat is specified, properties of the seat are shown\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBseat\-status\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBattach\fR \fINAME\fR \fIDEVICE\fR\&...
+.RS 4
+Persistently attach one or more devices to a seat\&. The devices should be specified via device paths in the
+/sys/
+file system\&. To create a new seat, attach at least one graphics card to a previously unused seat name\&. Seat names may consist only of a\(enz, A\(enZ, 0\(en9,
+"\-"
+and
+"_"
+and must be prefixed with
+"seat"\&. To drop assignment of a device to a specific seat, just reassign it to a different seat, or use
+\fBflush\-devices\fR\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBflush\-devices\fR
+.RS 4
+Removes all device assignments previously created with
+\fBattach\fR\&. After this call, only automatically generated seats will remain, and all seat hardware is assigned to them\&.
+.RE
+.PP
+\fBterminate\-seat\fR \fINAME\fR\&...
+.RS 4
+Terminates all sessions on a seat\&. This kills all processes of all sessions on the seat and deallocates all runtime resources attached to them\&.
+.sp
+Added in version 233\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-property=\fR
+.RS 4
+When showing session/user/seat properties, limit display to certain properties as specified as argument\&. If not specified, all set properties are shown\&. The argument should be a property name, such as
+"Sessions"\&. If specified more than once, all properties with the specified names are shown\&.
+.RE
+.PP
+\fB\-\-value\fR
+.RS 4
+When showing session/user/seat properties, only print the value, and skip the property name and
+"="\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-all\fR
+.RS 4
+When showing session/user/seat properties, show all properties regardless of whether they are set or not\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize process tree entries\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-\-kill\-whom=\fR
+.RS 4
+When used with
+\fBkill\-session\fR, choose which processes to kill\&. Takes one of
+"leader"
+or
+"all", to select whether to kill only the leader process of the session or all processes of the session\&. If omitted, defaults to
+\fBall\fR\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-s\fR, \fB\-\-signal=\fR
+.RS 4
+When used with
+\fBkill\-session\fR
+or
+\fBkill\-user\fR, choose which signal to send to selected processes\&. Must be one of the well known signal specifiers, such as
+\fBSIGTERM\fR,
+\fBSIGINT\fR
+or
+\fBSIGSTOP\fR\&. If omitted, defaults to
+\fBSIGTERM\fR\&.
+.sp
+The special value
+"help"
+will list the known values and the program will exit immediately, and the special value
+"list"
+will list known values along with the numerical signal numbers and the program will exit immediately\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-lines=\fR
+.RS 4
+When used with
+\fBuser\-status\fR
+and
+\fBsession\-status\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument\&. Defaults to 10\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-o\fR, \fB\-\-output=\fR
+.RS 4
+When used with
+\fBuser\-status\fR
+and
+\fBsession\-status\fR, controls the formatting of the journal entries that are shown\&. For the available choices, see
+\fBjournalctl\fR(1)\&. Defaults to
+"short"\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Querying user status\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ loginctl user\-status
+fatima (1005)
+           Since: Sat 2016\-04\-09 14:23:31 EDT; 54min ago
+           State: active
+        Sessions: 5 *3
+            Unit: user\-1005\&.slice
+                  ├─user@1005\&.service
+                    \&...
+                  ├─session\-3\&.scope
+                    \&...
+                  └─session\-5\&.scope
+                    ├─3473 login \-\- fatima
+                    └─3515 \-zsh
+
+Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
+                       session opened for user fatima by LOGIN(uid=0)
+Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+There are two sessions, 3 and 5\&. Session 3 is a graphical session, marked with a star\&. The tree of processing including the two corresponding scope units and the user manager unit are shown\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd-logind.service\fR(8),
+\fBlogind.conf\fR(5)
diff --git a/upstream/mageia-cauldron/man1/logname.1 b/upstream/mageia-cauldron/man1/logname.1
new file mode 100644
index 00000000..2a972d2c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/logname.1
@@ -0,0 +1,36 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH LOGNAME "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+logname \- print user\'s login name
+.SH SYNOPSIS
+.B logname
+[\fI\,OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the user's login name.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by FIXME: unknown.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBgetlogin\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/logname>
+.br
+or available locally via: info \(aq(coreutils) logname invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/lookbib.1 b/upstream/mageia-cauldron/man1/lookbib.1
new file mode 100644
index 00000000..b9635f76
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lookbib.1
@@ -0,0 +1,131 @@
+.TH LOOKBIB 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+lookbib \- search bibliographic databases
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY lookbib
+.OP \-i string
+.OP \-t n
+.I filename
+\&.\|.\|.\&
+.YS
+.
+.SY lookbib
+.B \-\-help
+.YS
+.
+.SY lookbib
+.B \-v
+.SY lookbib
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I lookbib
+prints a prompt on the standard error (unless the standard input is not
+a terminal),
+reads from the standard input a line containing a set of keywords,
+searches the bibliographic databases
+.I filename
+\&.\|.\|.\& for references containing those keywords,
+prints any references found on the standard output,
+and repeats this process until the end of input.
+.
+For each database
+.I filename
+to be searched,
+if an index
+.RI filename .i
+created by
+.IR indxbib (1)
+exists, then it will be searched instead;
+each index can cover multiple databases.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-\-help
+Display a usage message and exit.
+.
+.
+.TP
+.BI \-i string
+When searching files for which no index exists,
+ignore the contents of fields whose names are in
+.IR string .
+.
+.
+.TP
+.BI \-t n
+Only require the first
+.I n
+characters of keys to be given.
+Initially
+.I n
+is\~6.
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.RI filename .i
+Index files.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.IR refer (1),
+.IR lkbib (1),
+.IR indxbib (1)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/ls.1 b/upstream/mageia-cauldron/man1/ls.1
new file mode 100644
index 00000000..aa7bcea1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ls.1
@@ -0,0 +1,267 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH LS "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+ls \- list directory contents
+.SH SYNOPSIS
+.B ls
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+List information about the FILEs (the current directory by default).
+Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with .
+.TP
+\fB\-A\fR, \fB\-\-almost\-all\fR
+do not list implied . and ..
+.TP
+\fB\-\-author\fR
+with \fB\-l\fR, print the author of each file
+.TP
+\fB\-b\fR, \fB\-\-escape\fR
+print C\-style escapes for nongraphic characters
+.TP
+\fB\-\-block\-size\fR=\fI\,SIZE\/\fR
+with \fB\-l\fR, scale sizes by SIZE when printing them;
+e.g., '\-\-block\-size=M'; see SIZE format below
+.TP
+\fB\-B\fR, \fB\-\-ignore\-backups\fR
+do not list implied entries ending with ~
+.TP
+\fB\-c\fR
+with \fB\-lt\fR: sort by, and show, ctime (time of last
+modification of file status information);
+with \fB\-l\fR: show ctime and sort by name;
+otherwise: sort by ctime, newest first
+.TP
+\fB\-C\fR
+list entries by columns
+.TP
+\fB\-\-color\fR[=\fI\,WHEN\/\fR]
+color the output WHEN; more info below
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+list directories themselves, not their contents
+.TP
+\fB\-D\fR, \fB\-\-dired\fR
+generate output designed for Emacs' dired mode
+.TP
+\fB\-f\fR
+list all entries in directory order
+.TP
+\fB\-F\fR, \fB\-\-classify\fR[=\fI\,WHEN\/\fR]
+append indicator (one of */=>@|) to entries WHEN
+.TP
+\fB\-\-file\-type\fR
+likewise, except do not append '*'
+.TP
+\fB\-\-format\fR=\fI\,WORD\/\fR
+across \fB\-x\fR, commas \fB\-m\fR, horizontal \fB\-x\fR, long \fB\-l\fR,
+single\-column \fB\-1\fR, verbose \fB\-l\fR, vertical \fB\-C\fR
+.TP
+\fB\-\-full\-time\fR
+like \fB\-l\fR \fB\-\-time\-style\fR=\fI\,full\-iso\/\fR
+.TP
+\fB\-g\fR
+like \fB\-l\fR, but do not list owner
+.TP
+\fB\-\-group\-directories\-first\fR
+group directories before files;
+can be augmented with a \fB\-\-sort\fR option, but any
+use of \fB\-\-sort\fR=\fI\,none\/\fR (\fB\-U\fR) disables grouping
+.TP
+\fB\-G\fR, \fB\-\-no\-group\fR
+in a long listing, don't print group names
+.TP
+\fB\-h\fR, \fB\-\-human\-readable\fR
+with \fB\-l\fR and \fB\-s\fR, print sizes like 1K 234M 2G etc.
+.TP
+\fB\-\-si\fR
+likewise, but use powers of 1000 not 1024
+.TP
+\fB\-H\fR, \fB\-\-dereference\-command\-line\fR
+follow symbolic links listed on the command line
+.TP
+\fB\-\-dereference\-command\-line\-symlink\-to\-dir\fR
+follow each command line symbolic link
+that points to a directory
+.TP
+\fB\-\-hide\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+(overridden by \fB\-a\fR or \fB\-A\fR)
+.TP
+\fB\-\-hyperlink\fR[=\fI\,WHEN\/\fR]
+hyperlink file names WHEN
+.TP
+\fB\-\-indicator\-style\fR=\fI\,WORD\/\fR
+append indicator with style WORD to entry names:
+none (default), slash (\fB\-p\fR),
+file\-type (\fB\-\-file\-type\fR), classify (\fB\-F\fR)
+.TP
+\fB\-i\fR, \fB\-\-inode\fR
+print the index number of each file
+.TP
+\fB\-I\fR, \fB\-\-ignore\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+.TP
+\fB\-k\fR, \fB\-\-kibibytes\fR
+default to 1024\-byte blocks for file system usage;
+used only with \fB\-s\fR and per directory totals
+.TP
+\fB\-l\fR
+use a long listing format
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+when showing file information for a symbolic
+link, show information for the file the link
+references rather than for the link itself
+.TP
+\fB\-m\fR
+fill width with a comma separated list of entries
+.TP
+\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR
+like \fB\-l\fR, but list numeric user and group IDs
+.TP
+\fB\-N\fR, \fB\-\-literal\fR
+print entry names without quoting
+.TP
+\fB\-o\fR
+like \fB\-l\fR, but do not list group information
+.TP
+\fB\-p\fR, \fB\-\-indicator\-style\fR=\fI\,slash\/\fR
+append / indicator to directories
+.TP
+\fB\-q\fR, \fB\-\-hide\-control\-chars\fR
+print ? instead of nongraphic characters
+.TP
+\fB\-\-show\-control\-chars\fR
+show nongraphic characters as\-is (the default,
+unless program is 'ls' and output is a terminal)
+.TP
+\fB\-Q\fR, \fB\-\-quote\-name\fR
+enclose entry names in double quotes
+.TP
+\fB\-\-quoting\-style\fR=\fI\,WORD\/\fR
+use quoting style WORD for entry names:
+literal, locale, shell, shell\-always,
+shell\-escape, shell\-escape\-always, c, escape
+(overrides QUOTING_STYLE environment variable)
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse order while sorting
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+list subdirectories recursively
+.TP
+\fB\-s\fR, \fB\-\-size\fR
+print the allocated size of each file, in blocks
+.TP
+\fB\-S\fR
+sort by file size, largest first
+.TP
+\fB\-\-sort\fR=\fI\,WORD\/\fR
+sort by WORD instead of name: none (\fB\-U\fR), size (\fB\-S\fR),
+time (\fB\-t\fR), version (\fB\-v\fR), extension (\fB\-X\fR), width
+.TP
+\fB\-\-time\fR=\fI\,WORD\/\fR
+change the default of using modification times;
+access time (\fB\-u\fR): atime, access, use;
+change time (\fB\-c\fR): ctime, status;
+birth time: birth, creation;
+.IP
+with \fB\-l\fR, WORD determines which time to show;
+with \fB\-\-sort\fR=\fI\,time\/\fR, sort by WORD (newest first)
+.TP
+\fB\-\-time\-style\fR=\fI\,TIME_STYLE\/\fR
+time/date format with \fB\-l\fR; see TIME_STYLE below
+.TP
+\fB\-t\fR
+sort by time, newest first; see \fB\-\-time\fR
+.TP
+\fB\-T\fR, \fB\-\-tabsize\fR=\fI\,COLS\/\fR
+assume tab stops at each COLS instead of 8
+.TP
+\fB\-u\fR
+with \fB\-lt\fR: sort by, and show, access time;
+with \fB\-l\fR: show access time and sort by name;
+otherwise: sort by access time, newest first
+.TP
+\fB\-U\fR
+do not sort; list entries in directory order
+.TP
+\fB\-v\fR
+natural sort of (version) numbers within text
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,COLS\/\fR
+set output width to COLS.  0 means no limit
+.TP
+\fB\-x\fR
+list entries by lines instead of by columns
+.TP
+\fB\-X\fR
+sort alphabetically by entry extension
+.TP
+\fB\-Z\fR, \fB\-\-context\fR
+print any security context of each file
+.TP
+\fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-1\fR
+list one file per line
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+The TIME_STYLE argument can be full\-iso, long\-iso, iso, locale, or +FORMAT.
+FORMAT is interpreted like in \fBdate\fP(1).  If FORMAT is FORMAT1<newline>FORMAT2,
+then FORMAT1 applies to non\-recent files and FORMAT2 to recent files.
+TIME_STYLE prefixed with 'posix\-' takes effect only outside the POSIX locale.
+Also the TIME_STYLE environment variable sets the default style to use.
+.PP
+The WHEN argument defaults to 'always' and can also be 'auto' or 'never'.
+.PP
+Using color to distinguish file types is disabled both by default and
+with \fB\-\-color\fR=\fI\,never\/\fR.  With \fB\-\-color\fR=\fI\,auto\/\fR, ls emits color codes only when
+standard output is connected to a terminal.  The LS_COLORS environment
+variable can change the settings.  Use the \fBdircolors\fP(1) command to set it.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if minor problems (e.g., cannot access subdirectory),
+.TP
+2
+if serious trouble (e.g., cannot access command\-line argument).
+.SH AUTHOR
+Written by Richard M. Stallman and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBdircolors\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/ls>
+.br
+or available locally via: info \(aq(coreutils) ls invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/lsattr.1 b/upstream/mageia-cauldron/man1/lsattr.1
new file mode 100644
index 00000000..c95d859b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lsattr.1
@@ -0,0 +1,52 @@
+.\" -*- nroff -*-
+.TH LSATTR 1 "February 2023" "E2fsprogs version 1.47.0"
+.SH NAME
+lsattr \- list file attributes on a Linux second extended file system
+.SH SYNOPSIS
+.B lsattr
+[
+.B \-RVadlpv
+]
+[
+.I files...
+]
+.SH DESCRIPTION
+.B lsattr
+lists the file attributes on a second extended file system.  See
+.BR chattr (1)
+for a description of the attributes and what they mean.
+.SH OPTIONS
+.TP
+.B \-R
+Recursively list attributes of directories and their contents.
+.TP
+.B \-V
+Display the program version.
+.TP
+.B \-a
+List all files in directories, including files that start with `.'.
+.TP
+.B \-d
+List directories like other files, rather than listing their contents.
+.TP
+.B \-l
+Print the options using long names instead of single
+character abbreviations.
+.TP
+.B \-p
+List the file's project number.
+.TP
+.B \-v
+List the file's version/generation number.
+.SH AUTHOR
+.B lsattr
+was written by Remy Card <Remy.Card@linux.org>.  It is currently being
+maintained by Theodore Ts'o <tytso@alum.mit.edu>.
+.SH BUGS
+There are none :-).
+.SH AVAILABILITY
+.B lsattr
+is part of the e2fsprogs package and is available from
+http://e2fsprogs.sourceforge.net.
+.SH SEE ALSO
+.BR chattr (1)
diff --git a/upstream/mageia-cauldron/man1/lynx.1 b/upstream/mageia-cauldron/man1/lynx.1
new file mode 100644
index 00000000..ff4eb1b8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lynx.1
@@ -0,0 +1,1374 @@
+.\" $LynxId: lynx.man,v 1.123 2018/07/08 10:54:20 tom Exp $
+.\" **************************************************************************
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds AQ \(aq
+.el       .ds AQ '
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.de NS
+.ie n  .sp
+.el    .sp .5
+.ie n  .in +4
+.el    .in +2
+.nf
+.ft C			\" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n  .in -4
+.el    .in -2
+..
+.\" **************************************************************************
+.TH LYNX 1
+.SH NAME
+lynx \- a general purpose distributed information browser for the World Wide Web
+.SH SYNOPSIS
+.B lynx \fI[options] [optional paths or URLs]
+.sp
+.B lynx \fI[options] [path or URL]\fP \fB\-get_data
+.br
+.I data
+.br
+.B \-\-
+.sp
+.B lynx \fI[options] [path or URL]\fP \fB\-post_data
+.br
+.I data
+.br
+.B \-\-
+.PP
+Use \*(``lynx \-help\*('' to display a complete list of current options.
+.SH DESCRIPTION
+.hy 0
+.I
+Lynx
+is a fully-featured World Wide Web (WWW) client for users
+running cursor-addressable, character-cell display devices
+(e.g., vt100 terminals,
+vt100 emulators running on Windows 95/NT/XP/7/8 or any POSIX platform,
+or any other \*(``curses-oriented\*('' display).
+It will display hypertext
+markup language (HTML) documents containing links to
+files residing on the local system, as well as files residing on
+remote systems running Gopher, HTTP, FTP, WAIS, and NNTP servers.
+Current versions of
+.I
+Lynx
+run on
+Unix, VMS, Windows 95/NT/XP/7/8, DOS DJGPP and OS/2.
+.PP
+.I
+Lynx
+can be used to access information on the World Wide Web, or
+to build information systems intended primarily for local access.
+For example,
+.I
+Lynx
+has been used to build several Campus Wide
+Information Systems (CWIS).
+In addition,
+.I
+Lynx
+can be used to
+build systems isolated within a single LAN.
+.SH OPTIONS
+At start up, \fILynx\fR will load any local
+file or remote URL specified at the command line.
+For help with URLs, press \*(``\fB?\fR\*(''
+or \*(``\fBH\fR\*('' while running \fILynx\fR.
+Then follow the link titled, \*(``Help on URLs.\*(''
+.PP
+If more than one local file or remote URL is listed on the command line,
+\fILynx\fP will open only the last interactively.
+All of the names (local files and remote URLs)
+are added to the \fBG)oto\fP history.
+.PP
+\fILynx\fR uses only long option names.
+Option names can begin with double dash \*(``\-\-\*('' as well,
+underscores and dashes can be intermixed in
+option names (in the reference below, options
+are shown
+with one dash \*(``\-\*('' before them, and
+with underscores \*(``_\*('').
+.PP
+\fILynx\fR provides many command-line options.
+Some options require a value (string, number or keyword).
+These are noted in the reference below.
+The other options set boolean values in the program.
+There are three types of boolean options: set, unset and toggle.
+If no option value is given, these have the obvious meaning:
+set (to true), unset (to false), or toggle (between true/false).
+For any of these, an explicit value can be given in different
+forms to allow for operating system constraints,
+e.g.,
+.NS
+\fB\-center:off\fP
+\fB\-center=off\fP
+\fB\-center\-\fP
+.NE
+.PP
+\fILynx\fR recognizes
+\*(``1\*('', \*(``+\*('', \*(``on\*('' and \*(``true\*('' for true values, and
+\*(``0\*('', \*(``\-\*('', \*(``off\*('' and \*(``false\*('' for false values.
+Other option-values are ignored.
+.PP
+The default boolean, number and string option values that are compiled
+into \fILynx\fP are displayed in the help-message provided by \fBlynx \-help\fP.
+Some of those may differ according to how \fILynx\fP was built;
+see the help message itself for these values.
+The \fB\-help\fP option is processed in the third pass of options-processing,
+so any option which sets a value,
+as well as runtime configuration values are reflected in the help-message.
+.TP 7
+.B \-
+If the argument is only \*(``\-\*('', then \fILynx\fP expects to receive
+the arguments from the standard input.
+This is to allow for the
+potentially very long command line that can be associated
+with the \fB\-get_data\fR or \fB\-post_data\fR arguments (see below).
+It can also be used to avoid having sensitive information
+in the invoking command line (which would be visible to
+other processes on most systems), especially when
+the \fB\-auth\fR or \fB\-pauth\fR options are used.
+.TP
+.B \-accept_all_cookies
+accept all cookies.
+.TP
+.B \-anonymous
+apply restrictions for anonymous account, see also \fB\-restrictions\fR.
+.TP
+.B \-assume_charset\fR=\fIMIMEname
+charset for documents that do not specify it.
+.TP
+.B \-assume_local_charset\fR=\fIMIMEname
+charset assumed for local files,
+i.e., files which \fILynx\fP creates such as
+internal pages for the options menu.
+.TP
+.B \-assume_unrec_charset\fR=\fIMIMEname
+use this instead of unrecognized charsets.
+.TP
+.B \-auth\fR=\fIID\fR:\fIPASSWD
+set authorization ID and password for protected documents at startup.
+Be sure to protect any script files which use
+this switch.
+.TP
+.B \-base
+prepend a request URL comment and BASE tag to text/html
+outputs for \fB\-source\fR dumps.
+.TP
+.B \-bibhost\fR=\fIURL
+specify a local bibp server (default http://bibhost/).
+.TP
+.B \-blink
+forces high intensity background colors for color mode, if available
+and supported by the terminal.
+This applies to the \fBslang\fR library (for a few terminal emulators),
+or to OS/2 EMX with \fBncurses\fR.
+.TP
+.B \-book
+use the bookmark page as the startfile.
+The default or command
+line startfile is still set for the Main screen command, and will
+be used if the bookmark page is unavailable or blank.
+.TP
+.B \-buried_news
+toggles scanning of news articles for buried references, and
+converts them to news links.
+Not recommended because email
+addresses enclosed in angle brackets will be converted to
+false news links, and uuencoded messages can be trashed.
+.TP
+.B \-cache\fR=\fINUMBER
+set the NUMBER of documents cached in memory.
+The default is 10.
+.TP
+.B \-case
+enable case-sensitive string searching.
+.TP
+.B \-center
+Toggle center alignment in HTML TABLE.
+.TP
+.B \-cfg\fR=\fIFILENAME
+specifies a \fILynx\fP configuration file other than the default
+lynx.cfg.
+.TP
+.B \-child
+exit on left-arrow in startfile, and disable save to disk and associated
+print/mail options.
+.TP
+.B \-child_relaxed
+exit on left-arrow in startfile, but allow save to disk and associated
+print/mail options.
+.TP
+.B \-cmd_log\fR=\fIFILENAME
+write keystroke commands and related information to the specified file.
+.TP
+.B \-cmd_script\fR=\fIFILENAME
+read keystroke commands from the specified file.
+You can use the data written using the \fB\-cmd_log\fR option.
+\fILynx\fP will ignore other information which the command-logging may have
+written to the logfile.
+Each line of the command script contains either
+a comment beginning with \*(``#\*('',
+or a keyword:
+.RS
+.TP 3
+.B exit
+causes the script to stop, and forces \fILynx\fP to exit immediately.
+.TP
+.B key
+the character value, in printable form.
+Cursor and other special keys are given as names, e.g., \*(``Down Arrow\*(''.
+Printable 7-bit ASCII codes are given as-is,
+and hexadecimal values represent other 8-bit codes.
+.TP
+.B set
+followed by a \*(``name=value\*('' allows one to override values set in the
+lynx.cfg or \&.lynxrc files.
+\fILynx\fP tries the cfg-file setting first.
+.RE
+.TP
+.B \-collapse_br_tags
+toggles collapsing of BR tags.
+.TP
+.B \-color
+forces color mode on, if available.
+Default color control sequences
+which work for many terminal types are assumed if the terminal
+capability description does not specify how to handle color.
+\fILynx\fP needs to be compiled with the \fBslang\fR library for this flag,
+it is equivalent to setting the \fBCOLORTERM\fR environment variable.
+(If color support is instead provided by a color-capable curses
+library like \fBncurses\fR, \fILynx\fP relies completely on the terminal
+description to determine whether color mode is possible, and
+this flag is not needed and thus unavailable.)
+A saved show_color=always setting found in a \&.lynxrc file at
+startup has the same effect.
+A saved show_color=never found
+in \&.lynxrc on startup is overridden by this flag.
+.TP
+.B \-connect_timeout\fR=\fIN
+Sets the connection timeout, where N is given in seconds.
+.TP
+.B \-cookie_file\fR=\fIFILENAME
+specifies a file to use to read cookies.
+If none is specified, the default value is ~/.lynx_cookies
+for most systems, but ~/cookies for MS-DOS.
+.TP
+.B \-cookie_save_file\fR=\fIFILENAME
+specifies a file to use to store cookies.
+If none is specified, the value given by
+\fB\-cookie_file\fR is used.
+.TP
+.B \-cookies
+toggles handling of Set-Cookie headers.
+.TP
+.B \-core
+toggles forced core dumps on fatal errors.
+Turn this option off to ask \fILynx\fP to force
+a core dump if a fatal error occurs.
+.TP
+.B \-crawl
+with \fB\-traversal,\fR output each page to a file.
+with \fB\-dump\fR, format output as with \fB\-traversal\fR,
+but to the standard output.
+.TP
+.B \-curses_pads
+toggles the use of curses \*(``pad\*('' feature which supports
+left/right scrolling of the display.
+The feature is normally available for curses configurations,
+but inactive.
+To activate it, use the \*(``|\*('' character or the LINEWRAP_TOGGLE command.
+Toggling this option makes the feature altogether unavailable.
+.TP
+.B \-debug_partial
+separate incremental display stages with MessageSecs delay
+.TP
+.B \-default_colors
+toggles the default-colors feature which is normally set in the lynx.cfg file.
+.TP
+.B \-delay
+add DebugSecs delay after each progress-message
+.TP
+.B \-display\fR=\fIDISPLAY
+set the display variable for X rexec-ed programs.
+.TP
+.B \-display_charset\fR=\fIMIMEname
+set the charset for the terminal output.
+.TP
+.B \-dont_wrap_pre
+inhibit wrapping of text when \fB\-dump\fR'ing and \fB\-crawl\fR'ing,
+mark wrapped lines of <pre> in interactive session.
+.TP
+.B \-dump
+dumps the formatted output of the default document or those
+specified on the command line to standard output.
+Unlike interactive mode, all documents are processed.
+This can be used in the following way:
+.NS
+lynx \fB\-dump\fR http://www.subir.com/lynx.html
+.NE
+.IP
+Files specified on the command line are formatted as HTML if
+their names end with one of the standard web suffixes such
+as \*(``.htm\*('' or \*(``.html\*(''.
+Use the \fB\-force_html\fP option to format files whose names do not follow
+this convention.
+.TP
+.B \-editor\fR=\fIEDITOR
+enable external editing, using the specified
+EDITOR.
+(vi, ed, emacs, etc.)
+.TP
+.B \-emacskeys
+enable emacs-like key movement.
+.TP
+.B \-enable_scrollback
+toggles compatibility with communication programs' scrollback keys
+(may be incompatible with some curses packages).
+.TP
+.B \-error_file\fR=\fIFILE
+define a file where \fILynx\fP will report HTTP access codes.
+.TP
+.B \-exec
+enable local program execution (normally not configured).
+.TP
+.B \-fileversions
+include all versions of files in local VMS directory listings.
+.TP
+.B \-find_leaks
+toggle memory leak-checking.
+Normally this
+is not compiled-into your executable, but when it is,
+it can be disabled for a session.
+.TP
+.B \-force_empty_hrefless_a
+force HREF-less \*(``A\*('' elements to be empty
+(close them as soon as they are seen).
+.TP
+.B \-force_html
+forces the first document to be interpreted as HTML.
+.IP
+This is most useful when processing files specified on the command line
+which have an unrecognized suffix (or the suffix is associated with a
+non-HTML type, such as \*(``.txt\*('' for plain text files).
+.IP
+\fILynx\fP recognizes these file suffixes as HTML:
+.NS
+\*(``.ht3\*('',
+\*(``.htm\*('',
+\*(``.html3\*('',
+\*(``.html\*('',
+\*(``.htmlx\*('',
+\*(``.php3\*('',
+\*(``.php\*('',
+\*(``.phtml\*('',
+\*(``.sht\*('', and
+\*(``.shtml\*(''.
+.NE
+.TP
+.B \-force_secure
+toggles forcing of the secure flag for SSL cookies.
+.TP
+.B \-forms_options
+toggles whether the Options Menu is key-based or form-based.
+.TP
+.B \-from
+toggles transmissions of From headers.
+.TP
+.B \-ftp
+disable ftp access.
+.TP
+.B \-get_data
+properly formatted data for a \fIget\fP form are read in from
+the standard input and passed to the form.
+Input is terminated by a line that starts with \*(``\-\-\-\*(''.
+.IP
+\fILynx\fP issues an HTTP \fBGET\fP,
+sending the form to the path or URL given on the
+command-line and prints the response of the server.
+If no path or URL is given, \fILynx\fP sends the form to the start-page.
+.TP
+.B \-head
+send a HEAD request for the mime headers.
+.TP
+.B \-help
+print the \fILynx\fP command syntax usage message, and exit.
+.TP
+.B \-hiddenlinks=[option]
+control the display of hidden links.
+.RS
+.TP 3
+.B merge
+hidden links show up as bracketed numbers
+and are numbered together with other links in the sequence of their
+occurrence in the document.
+.TP
+.B listonly
+hidden links are shown only on \fBL)ist\fP screens and listings generated by
+.B \-dump
+or from the \fBP)rint\fP menu, but appear separately at the end of those lists.
+This is the default behavior.
+.TP
+.B ignore
+hidden links do not appear even in listings.
+.RE
+.TP
+.B \-historical
+toggles use of \*(``>\*('' or \*(``\-\->\*('' as a terminator for comments.
+.TP
+.B \-homepage\fR=\fIURL
+set homepage separate from start page.
+.TP
+.B \-image_links
+toggles inclusion of links for all images.
+.TP
+.B \-index\fR=\fIURL
+set the default index file to the specified URL.
+.TP
+.B \-ismap
+toggles inclusion of ISMAP links when client-side
+MAPs are present.
+.TP
+.B \-justify
+do justification of text.
+.TP
+.B \-link\fR=\fINUMBER
+starting count for lnk#.dat files produced by \fB\-crawl\fR.
+.TP
+.B \-list_inline
+for \fB\-dump\fR, show the links inline with the text.
+.TP
+.B \-listonly
+for \fB\-dump\fR, show only the list of links.
+.TP
+.B \-localhost
+disable URLs that point to remote hosts.
+.TP
+.B \-locexec
+enable local program execution from local files only (if
+\fILynx\fP was compiled with local execution enabled).
+.TP
+.B \-lss\fR=\fIFILENAME
+specify filename containing color-style information.
+The default is lynx.lss.
+If you give an empty filename, \fILynx\fP uses a built-in monochrome
+scheme which imitates the non-color-style configuration.
+.TP
+.B \-mime_header
+prints the MIME header of a fetched document along with its
+source.
+.TP
+.B \-minimal
+toggles minimal versus valid comment parsing.
+.TP
+.B \-nested_tables
+toggles nested-tables logic (for debugging).
+.TP
+.B \-newschunksize\fR=\fINUMBER
+number of articles in chunked news listings.
+.TP
+.B \-newsmaxchunk\fR=\fINUMBER
+maximum news articles in listings before chunking.
+.TP
+.B \-nobold
+disable bold video-attribute.
+.TP
+.B \-nobrowse
+disable directory browsing.
+.TP
+.B \-nocc
+disable Cc: prompts for self copies of mailings.
+Note that this does not disable any CCs which are incorporated
+within a mailto URL or form ACTION.
+.TP
+.B \-nocolor
+force color mode off, overriding terminal capabilities and any
+\-color flags, COLORTERM variable, and saved \&.lynxrc settings.
+.TP
+.B \-noexec
+disable local program execution.
+(DEFAULT)
+.TP
+.B \-nofilereferer
+disable transmissions of Referer headers for file URLs.
+.TP
+.B \-nolist
+disable the link list feature in dumps.
+.TP
+.B \-nolog
+disable mailing of error messages to document owners.
+.TP
+.B \-nomargins
+disable left/right margins in the default style sheet.
+.TP
+.B \-nomore
+disable \-more\- string in statusline messages.
+.TP
+.B \-nonrestarting_sigwinch
+This flag is not available on all systems,
+\fILynx\fP needs to be compiled with HAVE_SIGACTION defined.
+If available, this flag \fImay\fR cause \fILynx\fP to react
+more immediately to window changes when run within
+an \fBxterm\fR.
+.TP
+.B \-nonumbers
+disable link- and field-numbering.
+This overrides \fB\-number_fields\fR and \fB\-number_links\fR.
+.TP
+.B \-nopause
+disable forced pauses for statusline messages.
+.TP
+.B \-noprint
+disable most print functions.
+.TP
+.B \-noredir
+prevents automatic redirection and prints a message with a
+link to the new URL.
+.TP
+.B \-noreferer
+disable transmissions of Referer headers.
+.TP
+.B \-noreverse
+disable reverse video-attribute.
+.TP
+.B \-nosocks
+disable SOCKS proxy usage by a SOCKSified \fILynx\fP.
+.TP
+.B \-nostatus
+disable the retrieval status messages.
+.TP
+.B \-notitle
+disable title and blank line from top of page.
+.TP
+.B \-nounderline
+disable underline video-attribute.
+.TP
+.B \-number_fields
+force numbering of links as well as form input fields
+.TP
+.B \-number_links
+force numbering of links.
+.TP
+.B \-partial
+toggles display partial pages while loading.
+.TP
+.B \-partial_thres\fR=\fINUMBER
+number of lines to render before repainting display
+with partial-display logic
+.TP
+.B \-passive_ftp
+toggles passive ftp connections.
+.TP
+.B \-pauth\fR=\fIID\fR:\fIPASSWD
+set authorization ID and password for a protected proxy server at startup.
+Be sure to protect any script files which use this switch.
+.TP
+.B \-popup
+toggles handling of single-choice SELECT options via
+popup windows or as lists of radio buttons.
+.TP
+.B \-post_data
+properly formatted data for a \fIpost\fP form are read in from
+the standard input and passed to the form.
+Input is terminated by a line that starts with \*(``\-\-\-\*(''.
+.IP
+\fILynx\fP issues an HTTP \fBPOST\fP,
+sending the form to the path or URL given on the
+command-line and prints the response of the server.
+If no path or URL is given, \fILynx\fP sends the form to the start-page.
+.TP
+.B \-preparsed
+show HTML source preparsed and reformatted when used with \fB\-source\fR
+or in source view.
+.TP
+.B \-prettysrc
+show HTML source view with lexical elements and tags in color.
+.TP
+.B \-print
+enable print functions.
+(default)
+.TP
+.B \-pseudo_inlines
+toggles pseudo-ALTs for inline images with no ALT string.
+.TP
+.B \-raw
+toggles default setting of 8-bit character translations
+or CJK mode for the startup character set.
+.TP
+.B \-realm
+restricts access to URLs in the starting realm.
+.TP
+.B \-read_timeout\fR=\fIN
+Sets the read-timeout, where N is given in seconds.
+.TP
+.B \-reload
+flushes the cache on a proxy server
+(only the first document given on the command-line is affected).
+.TP
+.B \-restrictions\fR=\fI[option][,option][,option]...
+allows a list of services to be disabled selectively.
+Dashes and underscores in option names can be intermixed.
+The following list is printed if no options are specified.
+.RS
+.TP 3
+.B all
+restricts all options listed below.
+.TP
+.B bookmark
+disallow changing the location of the bookmark
+file.
+.TP
+.B bookmark_exec
+disallow execution links via the bookmark file.
+.TP
+.B change_exec_perms
+disallow changing the eXecute permission on files
+(but still allow it for directories) when local file
+management is enabled.
+.TP
+.B default
+same as command line option \fB\-anonymous\fR.
+Disables default services for anonymous users.
+Set to all restricted, except for:
+inside_telnet, outside_telnet,
+inside_ftp, outside_ftp,
+inside_rlogin, outside_rlogin,
+inside_news, outside_news, telnet_port,
+jump, mail, print, exec, and goto.
+The settings for these,
+as well as additional goto restrictions for
+specific URL schemes that are also applied,
+are derived from definitions within userdefs.h.
+.TP
+.B dired_support
+disallow local file management.
+.TP
+.B disk_save
+disallow saving to disk in the download and
+print menus.
+.TP
+.B dotfiles
+disallow access to, or creation of, hidden (dot) files.
+.TP
+.B download
+disallow some downloaders in the download menu (does not
+imply disk_save restriction).
+.TP
+.B editor
+disallow external editing.
+.TP
+.B exec
+disable execution scripts.
+.TP
+.B exec_frozen
+disallow the user from changing the local
+execution option.
+.TP
+.B externals
+disallow some \*(``EXTERNAL\*('' configuration lines
+if support for passing URLs to external
+applications (with the EXTERN command) is
+compiled in.
+.TP
+.B file_url
+disallow using \fBG)oto\fP, served links or bookmarks for
+file: URLs.
+.TP
+.B goto
+disable the \*(``g\*('' (goto) command.
+.TP
+.B inside_ftp
+disallow ftps for people coming from inside your
+domain (utmp required for selectivity).
+.TP
+.B inside_news
+disallow USENET news posting for people coming
+from inside your domain (utmp required for selectivity).
+.TP
+.B inside_rlogin
+disallow rlogins for people coming from inside
+your domain (utmp required for selectivity).
+.TP
+.B inside_telnet
+disallow telnets for people coming from inside
+your domain (utmp required for selectivity).
+.TP
+.B jump
+disable the \*(``j\*('' (jump) command.
+.TP
+.B multibook
+disallow multiple bookmarks.
+.TP
+.B mail
+disallow mail.
+.TP
+.B news_post
+disallow USENET News posting.
+.TP
+.B options_save
+disallow saving options in \&.lynxrc.
+.TP
+.B outside_ftp
+disallow ftps for people coming from outside your
+domain (utmp required for selectivity).
+.TP
+.B outside_news
+disallow USENET news reading and posting for people coming
+from outside your domain (utmp required for selectivity).
+This restriction applies to
+\*(``news\*('',
+\*(``nntp\*('',
+\*(``newspost\*('', and
+\*(``newsreply\*('' URLs,
+but not to \*(``snews\*('', \*(``snewspost\*('',
+or \*(``snewsreply\*('' in case they are supported.
+.TP
+.B outside_rlogin
+disallow rlogins for people coming from outside
+your domain (utmp required for selectivity).
+.TP
+.B outside_telnet
+disallow telnets for people coming from
+outside your domain (utmp required for selectivity).
+.TP
+.B print
+disallow most print options.
+.TP
+.B shell
+disallow shell escapes and lynxexec or lynxprog \fBG)oto\fP's.
+.TP
+.B suspend
+disallow Unix Control-Z suspends with escape to shell.
+.TP
+.B telnet_port
+disallow specifying a port in telnet \fBG)oto\fP's.
+.TP
+.B useragent
+disallow modifications of the User-Agent header.
+.RE
+.TP
+.B \-resubmit_posts
+toggles forced resubmissions (no-cache) of forms with
+method POST when the documents they returned are sought
+with the PREV_DOC command or from the History List.
+.TP
+.B \-rlogin
+disable recognition of rlogin commands.
+.TP
+.B \-scrollbar
+toggles showing scrollbar.
+.TP
+.B \-scrollbar_arrow
+toggles showing arrows at ends of the scrollbar.
+.TP
+.B \-selective
+require \&.www_browsable files to browse directories.
+.TP
+.B \-session\fR=\fIFILENAME
+resumes from specified file on startup and saves session to that file on exit.
+.TP
+.B \-sessionin\fR=\fIFILENAME
+resumes session from specified file.
+.TP
+.B \-sessionout\fR=\fIFILENAME
+saves session to specified file.
+.TP
+.B \-short_url
+show very long URLs in the status line with \*(``...\*('' to represent the
+portion which cannot be displayed.
+The beginning and end of the URL are displayed, rather than suppressing the end.
+.TP
+.B \-show_cfg
+Print the configuration settings,
+e.g., as read from \*(``lynx.cfg\*('', and exit.
+.TP
+.B \-show_cursor
+If enabled the cursor will not be hidden in the right hand
+corner but will instead be positioned at the start of the
+currently selected link.
+Show cursor is the default for systems without FANCY_CURSES capabilities.
+The default configuration can be changed in userdefs.h or lynx.cfg.
+The command line switch toggles the default.
+.TP
+.B \-show_rate
+If enabled the transfer rate is shown in bytes/second.
+If disabled, no transfer rate is shown.
+Use lynx.cfg or the options menu to select KB/second and/or ETA.
+.TP
+.B \-soft_dquotes
+toggles emulation of the old Netscape and Mosaic bug which
+treated \*(``>\*('' as a co-terminator for double-quotes and tags.
+.TP
+.B \-source
+works the same as dump but outputs HTML source instead of
+formatted text.
+For example
+.NS
+lynx \-source . >foo.html
+.NE
+.IP
+generates HTML source listing the files in the current directory.
+Each file is marked by an HREF relative to the parent directory.
+Add a trailing slash to make the HREF's relative to the current directory:
+.NS
+lynx \-source ./ >foo.html
+.NE
+.TP
+.B \-stack_dump
+disable SIGINT cleanup handler
+.TP
+.B \-startfile_ok
+allow non-http startfile and homepage with \fB\-validate\fR.
+.TP
+.B \-stderr
+When dumping a document using \fB\-dump\fR or \fB\-source\fR,
+\fILynx\fP normally does not display alert (error)
+messages that you see on the screen in the status line.
+Use the \fB\-stderr\fR option to tell \fILynx\fP to write these messages
+to the standard error.
+.TP
+.B \-stdin
+read the startfile from standard input
+(UNIX only).
+.TP
+.B \-syslog\fR=\fItext
+information for syslog call.
+.TP
+.B \-syslog_urls
+log requested URLs with syslog.
+.TP
+.B \-tagsoup
+initialize parser, using Tag Soup DTD rather than SortaSGML.
+.TP
+.B \-telnet
+disable recognition of telnet commands.
+.TP
+.B \-term\fR=\fITERM
+tell \fILynx\fP what terminal type to assume it is talking to.
+(This may be useful for remote execution, when, for example,
+\fILynx\fP connects to a remote TCP/IP port that starts a script that,
+in turn, starts another \fILynx\fP process.)
+.TP
+.B \-timeout\fR=\fIN
+For win32, sets the network read-timeout, where N is given in seconds.
+.TP
+.B \-tlog
+toggles between using a \fILynx\fP Trace Log and stderr for trace output
+from the session.
+.TP
+.B \-tna
+turns on \*(``Textfields Need Activation\*('' mode.
+.TP
+.B \-trace
+turns on \fILynx\fP trace mode.
+Destination of trace output depends
+on \-tlog.
+.TP
+.B \-trace_mask\fR=\fIvalue
+turn on optional traces, which may result in very large trace files.
+Logically OR the values to combine options:
+.RS
+.TP 3
+.B 1
+SGML character parsing states
+.TP
+.B 2
+color-style
+.TP
+.B 4
+TRST (table layout)
+.TP
+.B 8
+configuration
+(lynx.cfg,
+\&.lynxrc,
+\&.lynx-keymaps,
+mime.types and
+mailcap contents)
+.TP
+.B 16
+binary string copy/append, used in form data construction.
+.TP
+.B 32
+cookies
+.TP
+.B 64
+character sets
+.TP
+.B 128
+GridText parsing
+.TP
+.B 256
+timing
+.RE
+.TP
+.B \-traversal
+traverse all http links derived from startfile.
+When used with
+\fB\-crawl\fR, each link that begins with the same string as startfile
+is output to a file, intended for indexing.
+.IP
+See CRAWL.announce for more information.
+.TP
+.B \-trim_blank_lines
+toggles trimming of trailing blank lines as well as
+the related trimming of blank lines while collapsing BR tags.
+.TP
+.B \-trim_input_fields
+trim input text/textarea fields in forms.
+.TP
+.B \-underline_links
+toggles use of underline/bold attribute for links.
+.TP
+.B \-underscore
+toggles use of _underline_ format in dumps.
+.TP
+.B \-unique_urls
+check for duplicate link numbers in
+each page and corresponding lists,
+and reuse the original link number.
+.TP
+.B \-use_mouse
+turn on mouse support, if available.
+Clicking the left mouse button on a link traverses it.
+Clicking the right mouse button pops back.
+Click on the top line to scroll up.
+Click on the bottom line to scroll down.
+The first few positions in the top and bottom line may invoke
+additional functions.
+\fILynx\fP must be compiled with
+\fBncurses\fR or \fBslang\fR to support this feature.
+If \fBncurses\fR is used, clicking the middle mouse button pops up
+a simple menu.
+Mouse clicks may only work reliably while \fILynx\fP is
+idle waiting for input.
+.TP
+.B \-useragent=Name
+set alternate \fILynx\fP User-Agent header.
+.TP
+.B \-validate
+accept only http URLs (for validation).
+Complete security restrictions also are implemented.
+.TP
+.B \-verbose
+toggle [LINK], [IMAGE] and [INLINE] comments with filenames of these images.
+.TP
+.B \-version
+print version information, and exit.
+.TP
+.B \-vikeys
+enable vi-like key movement.
+.TP
+.B \-wdebug
+enable Waterloo tcp/ip packet debug (print to watt debugfile).
+This applies only to DOS versions compiled with WATTCP or WATT-32.
+.TP
+.B \-width\fR=\fINUMBER
+number of columns for formatting of dumps, default is 80.
+This is limited by the number of columns that \fILynx\fP could display,
+typically 1024 (the \fIMAX_LINE\fP symbol).
+.TP
+.B \-with_backspaces
+emit backspaces in output if \fB\-dump\fR'ing or \fB\-crawl\fR'ing
+(like \fBman\fP does)
+.TP
+.B \-xhtml_parsing
+tells \fILynx\fP that it can ignore certain tags which have no content
+in an XHTML 1.0 document.
+For example \*(``<p/>\*('' will be discarded.
+.SH COMMANDS
+.PP
+More than one key can be mapped to a given command.
+Here are some of the most useful:
+.bP
+Use \fBUp arrow\fR and \fBDown arrow\fR to scroll through hypertext links.
+.bP
+\fBRight arrow\fR or \fBReturn\fR will follow a highlighted hypertext link.
+.bP
+\fBLeft Arrow\fR or \*(``\fBu\fR\*('' will retreat from a link.
+.bP
+Type \*(``\fBH\fR\*('', \*(``\fB?\fR\*('', or \fBF1\fR
+for online help and descriptions of key-stroke commands.
+.bP
+Type \*(``\fBk\fR\*('' or \*(``\fBK\fR\*('' for a list of the current key-stroke
+command mappings.
+.IP
+If the same command is mapped to the same letter differing only
+by upper/lowercase only the lowercase mapping is shown.
+.bP
+Type \fBDelete\fR to view history list.
+.SH ENVIRONMENT
+In addition to various \*(``standard\*('' environment variables such as
+\fBHOME\fR, \fBPATH\fR, \fBUSER\fR, \fBDISPLAY\fR, \fBTMPDIR\fR, \fBetc\fR,
+\fILynx\fR utilizes several \fILynx\fP-specific environment variables, if they
+exist.
+.PP
+Others may be created or modified by \fILynx\fR to pass data to an external
+program, or for other reasons.
+These are listed separately below.
+.PP
+See also the sections on \fBSIMULATED CGI SUPPORT\fR and
+\fBNATIVE LANGUAGE SUPPORT\fR, below.
+.PP
+Note:  Not all environment variables apply to all types of platforms
+supported by \fILynx\fR, though most do.
+Feedback on platform dependencies is solicited.
+.PP
+Environment Variables Used By \fILynx\fR:
+.TP 20
+.B COLORTERM
+If set, color capability for the terminal is forced on at startup time.
+The actual value assigned to the variable is ignored.
+This variable is only meaningful if \fILynx\fR was built using the \fBslang\fR
+screen-handling library.
+.TP
+.B LYNX_CFG
+This variable, if set, will override the default location and name of
+the global configuration file (normally, \fBlynx.cfg\fR) that was defined
+by the LYNX_CFG_FILE constant in the userdefs.h file, during installation.
+.IP
+See the userdefs.h file for more information.
+.TP
+.B LYNX_CFG_PATH
+If set, this variable overrides the compiled-in search-list of directories
+used to find the configuration files, e.g., \fBlynx.cfg\fP and \fBlynx.lss\fP.
+The list is delimited with ":" (or ";" for Windows) like the \fBPATH\fP
+environment variable.
+.TP
+.B LYNX_HELPFILE
+If set, this variable overrides the compiled-in URL and configuration
+file URL for the \fILynx\fP help file.
+.TP
+.B LYNX_LOCALEDIR
+If set, this variable overrides the compiled-in location of the
+locale directory which contains native language (NLS) message text.
+.TP
+.B LYNX_LSS
+This variable, if set, specifies the location of the default \fILynx\fR
+character style sheet file.
+[Currently only meaningful if \fILynx\fR was
+built using curses color style support.]
+.TP
+.B LYNX_SAVE_SPACE
+This variable, if set, will override the default path prefix for files
+saved to disk that is defined in the \fBlynx.cfg SAVE_SPACE:\fR statement.
+.IP
+See the \fBlynx.cfg\fR file for more information.
+.TP
+.B LYNX_TEMP_SPACE
+This variable, if set, will override the default path prefix for temporary
+files that was defined during installation, as well as any value that may
+be assigned to the \fBTMPDIR\fR variable.
+.TP
+.B MAIL
+This variable specifies the default inbox \fILynx\fR will check for new
+mail, if such checking is enabled in the \fBlynx.cfg\fR file.
+.TP
+.B NEWS_ORGANIZATION
+This variable, if set, provides the string used in the \fBOrganization:\fR
+header of \fBUSENET\fR news postings.
+It will override the setting of the
+ORGANIZATION environment variable, if it is also set (and, on \fBUNIX\fR,
+the contents of an /etc/organization file, if present).
+.TP
+.B NNTPSERVER
+If set, this variable specifies the default NNTP server that will be used
+for \fBUSENET\fR news reading and posting with \fILynx\fR, via news: URL's.
+.TP
+.B ORGANIZATION
+This variable, if set, provides the string used in the \fBOrganization:\fR
+header of \fBUSENET\fR news postings.
+On \fBUNIX\fR, it will override the
+contents of an /etc/organization file, if present.
+.TP
+.I PROTOCOL\fB_proxy\fR
+\fILynx\fR supports the use of proxy servers that can act as firewall
+gateways and caching servers.
+They are preferable to the older gateway
+servers (see WWW_access_GATEWAY, below).
+.IP
+Each protocol used by \fILynx\fR,
+(http, ftp, gopher, etc), can be mapped separately by setting environment
+variables of the form \fIPROTOCOL\fP_proxy.
+Protocols are indicated in a URI by the name before \*(``:\*('', e.g.,
+\*(``http\*('' in 
+\*(``http://some.server.dom:port/\*('' for HTML. 
+.IP
+Depending on your system configuration and supported protocols,
+the environment variables recognized by \fIlynx\fP may include
+.NS
+cso_proxy
+finger_proxy
+ftp_proxy
+gopher_proxy
+https_proxy
+http_proxy
+newspost_proxy
+newsreply_proxy
+news_proxy
+nntp_proxy
+no_proxy
+snewspost_proxy
+snewsreply_proxy
+snews_proxy
+wais_proxy
+.NE
+.IP
+See \fBLynx Users Guide\fR for additional details and examples.
+.TP
+.B SSL_CERT_DIR
+Set to the directory containing trusted certificates.
+.TP
+.B SSL_CERT_FILE
+Set to the full path and filename for your file of trusted certificates.
+.TP
+.B WWW_\fIaccess\fB_GATEWAY
+\fILynx\fR still supports use of gateway servers, with the servers specified
+via \*(``WWW_\fIaccess\fP_GATEWAY\*('' variables
+(where \*(``\fIaccess\fP\*('' is lower case and can be
+\*(``http\*('', \*(``ftp\*('', \*(``gopher\*('' or \*(``wais\*('').
+However most gateway servers have been discontinued.
+Note that you do not include a terminal \*(``/\*('' for gateways, but
+do for proxies specified by \fIPROTOCOL\fP_proxy environment variables.
+.IP
+See \fBLynx Users Guide\fR for details.
+.TP
+.B WWW_HOME
+This variable, if set, will override the default startup URL specified
+in any of the \fILynx\fR configuration files.
+.PP
+Environment Variables \fBSet\fR or \fBModified\fR By \fILynx\fR:
+.TP 20
+.B LYNX_PRINT_DATE
+This variable is set by the \fILynx\fR p(rint) function, to the
+\fBDate:\fR
+string seen in the document's \*(``\fBInformation about\fR\*('' page (= cmd),
+if any.
+It is created for use by an external program, as defined in a
+\fBlynx.cfg PRINTER:\fR definition statement.
+If the field does not exist for the document, the variable is set to a
+null string under \fBUNIX\fR, or \*(``No Date\*('' under \fBVMS\fR.
+.TP
+.B LYNX_PRINT_LASTMOD
+This variable is set by the \fILynx\fR p(rint) function, to the
+\fBLast Mod:\fR
+string seen in the document's \*(``\fBInformation about\fR\*('' page (= cmd),
+if any.
+It is created for use by an external program, as defined in a
+\fBlynx.cfg PRINTER:\fR definition statement.
+If the field does not exist for the document, the variable is set to a
+null string under \fBUNIX\fR, or \*(``No LastMod\*('' under \fBVMS\fR.
+.TP
+.B LYNX_PRINT_TITLE
+This variable is set by the \fILynx\fR p(rint) function, to the
+\fBLinkname:\fR
+string seen in the document's \*(``\fBInformation about\fR\*('' page (= cmd),
+if any.
+It is created for use by an external program, as defined in a
+\fBlynx.cfg PRINTER:\fR definition statement.
+If the field does not exist for the document, the variable is set to a
+null string under \fBUNIX\fR, or \*(``No Title\*('' under \fBVMS\fR.
+.TP
+.B LYNX_PRINT_URL
+This variable is set by the \fILynx\fR p(rint) function, to the
+\fBURL:\fR
+string seen in the document's \*(``\fBInformation about\fR\*('' page (= cmd),
+if any.
+It is created for use by an external program, as defined in a
+\fBlynx.cfg PRINTER:\fR definition statement.
+If the field does not exist for the document, the variable is set to a
+null string under \fBUNIX\fR, or \*(``No URL\*('' under \fBVMS\fR.
+.TP
+.B LYNX_TRACE
+If set, causes \fILynx\fR to write a trace file as if the \fB\-trace\fR
+option were supplied.
+.TP
+.B LYNX_TRACE_FILE
+If set, overrides the compiled-in name of the trace file,
+which is either \fBLynx.trace\fP or \fBLY\-TRACE.LOG\fP
+(the latter on the DOS/Windows platforms).
+The trace file is in either case relative to the home directory.
+.TP
+.B LYNX_VERSION
+This variable is always set by \fILynx\fR, and may be used by an external
+program to determine if it was invoked by \fILynx\fR.
+.IP
+See also the comments
+in the distribution's sample \fBmailcap\fR file, for notes on usage in such
+a file.
+.TP
+.B TERM
+Normally, this variable is used by \fILynx\fR to determine the terminal type
+being used to invoke \fILynx\fR.
+If, however, it is unset at startup time
+(or has the value \*(``unknown\*(''),
+or if the \fB\-term\fR command-line option is used (see \fBOPTIONS\fR section
+above), \fILynx\fR will set or modify its value to the user specified
+terminal type (for the \fILynx\fR execution environment).
+Note: If set/modified by \fILynx\fR, the values of the \fBLINES\fR and/or
+\fBCOLUMNS\fR environment variables may also be changed.
+.SH SIMULATED CGI SUPPORT
+If built with the \fBcgi-links\fR option enabled, \fILynx\fR allows access
+to a cgi script directly without the need for an http daemon.
+.PP
+When executing such \*(``lynxcgi scripts\*('' (if enabled),
+the following variables may be set for simulating a CGI environment:
+.PP
+.B CONTENT_LENGTH
+.PP
+.B CONTENT_TYPE
+.PP
+.B DOCUMENT_ROOT
+.PP
+.B HTTP_ACCEPT_CHARSET
+.PP
+.B HTTP_ACCEPT_LANGUAGE
+.PP
+.B HTTP_USER_AGENT
+.PP
+.B PATH_INFO
+.PP
+.B PATH_TRANSLATED
+.PP
+.B QUERY_STRING
+.PP
+.B REMOTE_ADDR
+.PP
+.B REMOTE_HOST
+.PP
+.B REQUEST_METHOD
+.PP
+.B SERVER_SOFTWARE
+.PP
+Other environment variables are not inherited by the script, unless they
+are provided via a LYNXCGI_ENVIRONMENT statement in the configuration file.
+See the \fBlynx.cfg\fR file, and the (draft) CGI 1.1 Specification
+<http://Web.Golux.Com/coar/cgi/draft-coar-cgi-v11-00.txt> for the
+definition and usage of these variables.
+.PP
+The CGI Specification, and other associated documentation, should be consulted
+for general information on CGI script programming.
+.SH NATIVE LANGUAGE SUPPORT
+If configured and installed with \fBNative Language Support\fR, \fILynx\fR
+will display status and other messages in your local language.
+See the
+file \fBABOUT_NLS\fR in the source distribution, or at your local \fBGNU\fR
+site, for more information about internationalization.
+.PP
+The following environment variables may be used to alter default settings:
+.TP 20
+.B LANG
+This variable, if set, will override the default message language.
+It is an \fBISO 639\fR two-letter code identifying the language.
+Language codes are \fBNOT\fR the same
+as the country codes given in \fBISO 3166\fR.
+.TP
+.B LANGUAGE
+This variable, if set, will override the default message language.
+This is a \fBGNU\fR extension that has higher priority for setting
+the message catalog than \fBLANG\fR or \fBLC_ALL\fR.
+.TP
+.B LC_ALL
+and
+.TP
+.B LC_MESSAGES
+These variables, if set, specify the notion of native language
+formatting style.
+They are \fBPOSIXly\fR correct.
+.TP
+.B LINGUAS
+This variable, if set prior to configuration, limits the installed
+languages to specific values.
+It is a space-separated list of two-letter codes.
+Currently, it is hard-coded to a wish list.
+.TP
+.B NLSPATH
+This variable, if set, is used as the path prefix for message catalogs.
+.SH NOTES
+This is the \fILynx\fP v2.8.9 Release; development is in progress for 2.9.0.
+.PP
+If you wish to contribute to the further development
+of \fILynx\fR, subscribe to our mailing list.
+Send email to
+<lynx-dev-request@nongnu.org> with \*(``subscribe lynx-dev\*('' as the only line
+in the body of your message.
+.PP
+Send bug reports, comments, suggestions to <lynx-dev@nongnu.org>
+after subscribing.
+.PP
+Unsubscribe by sending email to <lynx-dev-request@nongnu.org> with
+\*(``unsubscribe lynx-dev\*('' as the only line in the body of your message.
+Do not send the unsubscribe message to the lynx-dev list, itself.
+.SH SEE ALSO
+.hy 0
+\fBcatgets\fR(3),
+\fBcurses\fR(3),
+\fBenviron\fR(7),
+\fBexecve\fR(2),
+\fBftp\fR(1),
+\fBgettext\fR(GNU),
+\fBlocaleconv\fR(3),
+\fBncurses\fR(3),
+\fBsetlocale\fR(3),
+\fBslang\fR(?),
+\fBtermcap\fR(5),
+\fBterminfo\fR(5),
+\fBwget\fR(GNU)
+.hy 1
+.PP
+Note that man page availability and section numbering is somewhat
+platform dependent, and may vary from the above references.
+.PP
+A section shown as (GNU), is intended to denote that the topic
+may be available via an info page, instead of a man page (i.e., try
+\*(``info subject\*('', rather than \*(``man subject\*('').
+.PP
+A section shown as \fB(?)\fP denotes that documentation on the topic exists,
+but is not part of an established documentation retrieval system (see
+the distribution files associated with the topic, or contact your
+System Administrator for further information).
+.SH ACKNOWLEDGMENTS
+\fILynx\fP has incorporated code from a variety of sources along the way.
+The earliest versions of \fILynx\fP included code from Earl Fogel of Computing
+Services at the University of Saskatchewan, who implemented HYPERREZ
+in the Unix environment.
+HYPERREZ was developed by Niel Larson of
+Think.com and served as the model for the early versions of \fILynx\fP.
+Those versions also incorporated libraries from the Unix Gopher clients
+developed at the University of Minnesota, and the later versions of
+\fILynx\fP rely on the WWW client library code developed by Tim Berners-Lee
+and the WWW community.
+Also a special thanks to Foteos Macrides who ported
+much of \fILynx\fP to VMS and did or organized most of its development since the
+departures of Lou Montulli and Garrett Blythe from the University of Kansas
+in the summer of 1994 through the release of v2.7.2, and to everyone
+on the net who has contributed to \fILynx\fP's development either directly
+(through patches, comments or bug reports) or indirectly
+(through inspiration and development of other systems).
+.SH AUTHORS
+Lou Montulli, Garrett Blythe, Craig Lavender, Michael Grobe, Charles Rezac
+.br
+Academic Computing Services
+.br
+University of Kansas
+.br
+Lawrence, Kansas 66047
+.PP
+Foteos Macrides
+.br
+Worcester Foundation for Biomedical Research
+.br
+Shrewsbury, Massachusetts 01545
+.PP
+Thomas E.\& Dickey
+.br
+<dickey@invisible-island.net>
diff --git a/upstream/mageia-cauldron/man1/lz4.1 b/upstream/mageia-cauldron/man1/lz4.1
new file mode 100644
index 00000000..7cb98d63
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/lz4.1
@@ -0,0 +1,249 @@
+.
+.TH "LZ4" "1" "August 2022" "lz4 v1.9.4" "User Commands"
+.
+.SH "NAME"
+\fBlz4\fR \- lz4, unlz4, lz4cat \- Compress or decompress \.lz4 files
+.
+.SH "SYNOPSIS"
+\fBlz4\fR [\fIOPTIONS\fR] [\-|INPUT\-FILE] \fIOUTPUT\-FILE\fR
+.
+.P
+\fBunlz4\fR is equivalent to \fBlz4 \-d\fR
+.
+.P
+\fBlz4cat\fR is equivalent to \fBlz4 \-dcfm\fR
+.
+.P
+When writing scripts that need to decompress files, it is recommended to always use the name \fBlz4\fR with appropriate arguments (\fBlz4 \-d\fR or \fBlz4 \-dc\fR) instead of the names \fBunlz4\fR and \fBlz4cat\fR\.
+.
+.SH "DESCRIPTION"
+\fBlz4\fR is an extremely fast lossless compression algorithm, based on \fBbyte\-aligned LZ77\fR family of compression scheme\. \fBlz4\fR offers compression speeds > 500 MB/s per core, linearly scalable with multi\-core CPUs\. It features an extremely fast decoder, offering speed in multiple GB/s per core, typically reaching RAM speed limit on multi\-core systems\. The native file format is the \fB\.lz4\fR format\.
+.
+.SS "Difference between lz4 and gzip"
+\fBlz4\fR supports a command line syntax similar \fIbut not identical\fR to \fBgzip(1)\fR\. Differences are :
+.
+.IP "\(bu" 4
+\fBlz4\fR compresses a single file by default (see \fB\-m\fR for multiple files)
+.
+.IP "\(bu" 4
+\fBlz4 file1 file2\fR means : compress file1 \fIinto\fR file2
+.
+.IP "\(bu" 4
+\fBlz4 file\.lz4\fR will default to decompression (use \fB\-z\fR to force compression)
+.
+.IP "\(bu" 4
+\fBlz4\fR preserves original files (see \fB\-\-rm\fR to erase source file on completion)
+.
+.IP "\(bu" 4
+\fBlz4\fR shows real\-time notification statistics during compression or decompression of a single file (use \fB\-q\fR to silence them)
+.
+.IP "\(bu" 4
+When no destination is specified, result is sent on implicit output, which depends on \fBstdout\fR status\. When \fBstdout\fR \fIis Not the console\fR, it becomes the implicit output\. Otherwise, if \fBstdout\fR is the console, the implicit output is \fBfilename\.lz4\fR\.
+.
+.IP "\(bu" 4
+It is considered bad practice to rely on implicit output in scripts\. because the script\'s environment may change\. Always use explicit output in scripts\. \fB\-c\fR ensures that output will be \fBstdout\fR\. Conversely, providing a destination name, or using \fB\-m\fR ensures that the output will be either the specified name, or \fBfilename\.lz4\fR respectively\.
+.
+.IP "" 0
+.
+.P
+Default behaviors can be modified by opt\-in commands, detailed below\.
+.
+.IP "\(bu" 4
+\fBlz4 \-m\fR makes it possible to provide multiple input filenames, which will be compressed into files using suffix \fB\.lz4\fR\. Progress notifications become disabled by default (use \fB\-v\fR to enable them)\. This mode has a behavior which more closely mimics \fBgzip\fR command line, with the main remaining difference being that source files are preserved by default\.
+.
+.IP "\(bu" 4
+Similarly, \fBlz4 \-m \-d\fR can decompress multiple \fB*\.lz4\fR files\.
+.
+.IP "\(bu" 4
+It\'s possible to opt\-in to erase source files on successful compression or decompression, using \fB\-\-rm\fR command\.
+.
+.IP "\(bu" 4
+Consequently, \fBlz4 \-m \-\-rm\fR behaves the same as \fBgzip\fR\.
+.
+.IP "" 0
+.
+.SS "Concatenation of \.lz4 files"
+It is possible to concatenate \fB\.lz4\fR files as is\. \fBlz4\fR will decompress such files as if they were a single \fB\.lz4\fR file\. For example:
+.
+.IP "" 4
+.
+.nf
+
+lz4 file1  > foo\.lz4
+lz4 file2 >> foo\.lz4
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Then \fBlz4cat foo\.lz4\fR is equivalent to \fBcat file1 file2\fR\.
+.
+.SH "OPTIONS"
+.
+.SS "Short commands concatenation"
+In some cases, some options can be expressed using short command \fB\-x\fR or long command \fB\-\-long\-word\fR\. Short commands can be concatenated together\. For example, \fB\-d \-c\fR is equivalent to \fB\-dc\fR\. Long commands cannot be concatenated\. They must be clearly separated by a space\.
+.
+.SS "Multiple commands"
+When multiple contradictory commands are issued on a same command line, only the latest one will be applied\.
+.
+.SS "Operation mode"
+.
+.TP
+\fB\-z\fR \fB\-\-compress\fR
+Compress\. This is the default operation mode when no operation mode option is specified, no other operation mode is implied from the command name (for example, \fBunlz4\fR implies \fB\-\-decompress\fR), nor from the input file name (for example, a file extension \fB\.lz4\fR implies \fB\-\-decompress\fR by default)\. \fB\-z\fR can also be used to force compression of an already compressed \fB\.lz4\fR file\.
+.
+.TP
+\fB\-d\fR \fB\-\-decompress\fR \fB\-\-uncompress\fR
+Decompress\. \fB\-\-decompress\fR is also the default operation when the input filename has an \fB\.lz4\fR extension\.
+.
+.TP
+\fB\-t\fR \fB\-\-test\fR
+Test the integrity of compressed \fB\.lz4\fR files\. The decompressed data is discarded\. No files are created nor removed\.
+.
+.TP
+\fB\-b#\fR
+Benchmark mode, using \fB#\fR compression level\.
+.
+.TP
+\fB\-\-list\fR
+List information about \.lz4 files\. note : current implementation is limited to single\-frame \.lz4 files\.
+.
+.SS "Operation modifiers"
+.
+.TP
+\fB\-#\fR
+Compression level, with # being any value from 1 to 12\. Higher values trade compression speed for compression ratio\. Values above 12 are considered the same as 12\. Recommended values are 1 for fast compression (default), and 9 for high compression\. Speed/compression trade\-off will vary depending on data to compress\. Decompression speed remains fast at all settings\.
+.
+.TP
+\fB\-\-fast[=#]\fR
+Switch to ultra\-fast compression levels\. The higher the value, the faster the compression speed, at the cost of some compression ratio\. If \fB=#\fR is not present, it defaults to \fB1\fR\. This setting overrides compression level if one was set previously\. Similarly, if a compression level is set after \fB\-\-fast\fR, it overrides it\.
+.
+.TP
+\fB\-\-best\fR
+Set highest compression level\. Same as \-12\.
+.
+.TP
+\fB\-\-favor\-decSpeed\fR
+Generate compressed data optimized for decompression speed\. Compressed data will be larger as a consequence (typically by ~0\.5%), while decompression speed will be improved by 5\-20%, depending on use cases\. This option only works in combination with very high compression levels (>=10)\.
+.
+.TP
+\fB\-D dictionaryName\fR
+Compress, decompress or benchmark using dictionary \fIdictionaryName\fR\. Compression and decompression must use the same dictionary to be compatible\. Using a different dictionary during decompression will either abort due to decompression error, or generate a checksum error\.
+.
+.TP
+\fB\-f\fR \fB\-\-[no\-]force\fR
+This option has several effects:
+.
+.IP
+If the target file already exists, overwrite it without prompting\.
+.
+.IP
+When used with \fB\-\-decompress\fR and \fBlz4\fR cannot recognize the type of the source file, copy the source file as is to standard output\. This allows \fBlz4cat \-\-force\fR to be used like \fBcat (1)\fR for files that have not been compressed with \fBlz4\fR\.
+.
+.TP
+\fB\-c\fR \fB\-\-stdout\fR \fB\-\-to\-stdout\fR
+Force write to standard output, even if it is the console\.
+.
+.TP
+\fB\-m\fR \fB\-\-multiple\fR
+Multiple input files\. Compressed file names will be appended a \fB\.lz4\fR suffix\. This mode also reduces notification level\. Can also be used to list multiple files\. \fBlz4 \-m\fR has a behavior equivalent to \fBgzip \-k\fR (it preserves source files by default)\.
+.
+.TP
+\fB\-r\fR
+operate recursively on directories\. This mode also sets \fB\-m\fR (multiple input files)\.
+.
+.TP
+\fB\-B#\fR
+Block size [4\-7](default : 7)
+.
+.br
+\fB\-B4\fR= 64KB ; \fB\-B5\fR= 256KB ; \fB\-B6\fR= 1MB ; \fB\-B7\fR= 4MB
+.
+.TP
+\fB\-BI\fR
+Produce independent blocks (default)
+.
+.TP
+\fB\-BD\fR
+Blocks depend on predecessors (improves compression ratio, more noticeable on small blocks)
+.
+.TP
+\fB\-BX\fR
+Generate block checksums (default:disabled)
+.
+.TP
+\fB\-\-[no\-]frame\-crc\fR
+Select frame checksum (default:enabled)
+.
+.TP
+\fB\-\-no\-crc\fR
+Disable both frame and block checksums
+.
+.TP
+\fB\-\-[no\-]content\-size\fR
+Header includes original size (default:not present)
+.
+.br
+Note : this option can only be activated when the original size can be determined, hence for a file\. It won\'t work with unknown source size, such as stdin or pipe\.
+.
+.TP
+\fB\-\-[no\-]sparse\fR
+Sparse mode support (default:enabled on file, disabled on stdout)
+.
+.TP
+\fB\-l\fR
+Use Legacy format (typically for Linux Kernel compression)
+.
+.br
+Note : \fB\-l\fR is not compatible with \fB\-m\fR (\fB\-\-multiple\fR) nor \fB\-r\fR
+.
+.SS "Other options"
+.
+.TP
+\fB\-v\fR \fB\-\-verbose\fR
+Verbose mode
+.
+.TP
+\fB\-q\fR \fB\-\-quiet\fR
+Suppress warnings and real\-time statistics; specify twice to suppress errors too
+.
+.TP
+\fB\-h\fR \fB\-H\fR \fB\-\-help\fR
+Display help/long help and exit
+.
+.TP
+\fB\-V\fR \fB\-\-version\fR
+Display Version number and exit
+.
+.TP
+\fB\-k\fR \fB\-\-keep\fR
+Preserve source files (default behavior)
+.
+.TP
+\fB\-\-rm\fR
+Delete source files on successful compression or decompression
+.
+.TP
+\fB\-\-\fR
+Treat all subsequent arguments as files
+.
+.SS "Benchmark mode"
+.
+.TP
+\fB\-b#\fR
+Benchmark file(s), using # compression level
+.
+.TP
+\fB\-e#\fR
+Benchmark multiple compression levels, from b# to e# (included)
+.
+.TP
+\fB\-i#\fR
+Minimum evaluation time in seconds [1\-9] (default : 3)
+.
+.SH "BUGS"
+Report bugs at: https://github\.com/lz4/lz4/issues
+.
+.SH "AUTHOR"
+Yann Collet
diff --git a/upstream/mageia-cauldron/man1/machinectl.1 b/upstream/mageia-cauldron/man1/machinectl.1
new file mode 100644
index 00000000..0fdde67e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/machinectl.1
@@ -0,0 +1,1277 @@
+'\" t
+.TH "MACHINECTL" "1" "" "systemd 255" "machinectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+machinectl \- Control the systemd machine manager
+.SH "SYNOPSIS"
+.HP \w'\fBmachinectl\fR\ 'u
+\fBmachinectl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBmachinectl\fR
+may be used to introspect and control the state of the
+\fBsystemd\fR(1)
+virtual machine and container registration manager
+\fBsystemd-machined.service\fR(8)\&.
+.PP
+\fBmachinectl\fR
+may be used to execute operations on machines and images\&. Machines in this sense are considered running instances of:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Virtual Machines (VMs) that virtualize hardware to run full operating system (OS) instances (including their kernels) in a virtualized environment on top of the host OS\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Containers that share the hardware and OS kernel with the host OS, in order to run OS userspace instances on top the host OS\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The host system itself\&.
+.RE
+.PP
+Machines are identified by names that follow the same rules as UNIX and DNS hostnames\&. For details, see below\&.
+.PP
+Machines are instantiated from disk or file system images that frequently\ \&\(em but not necessarily\ \&\(em carry the same name as machines running from them\&. Images in this sense may be:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Directory trees containing an OS, including the top\-level directories
+/usr/,
+/etc/, and so on\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+btrfs subvolumes containing OS trees, similar to regular directory trees\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Binary "raw" disk image files containing MBR or GPT partition tables and Linux file systems\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Similarly, block devices containing MBR or GPT partition tables and file systems\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The file system tree of the host OS itself\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.SS "Machine Commands"
+.PP
+\fBlist\fR
+.RS 4
+List currently running (online) virtual machines and containers\&. To enumerate machine images that can be started, use
+\fBlist\-images\fR
+(see below)\&. Note that this command hides the special
+"\&.host"
+machine by default\&. Use the
+\fB\-\-all\fR
+switch to show it\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBstatus\fR \fINAME\fR\&...
+.RS 4
+Show runtime status information about one or more virtual machines and containers, followed by the most recent log data from the journal\&. This function is intended to generate human\-readable output\&. If you are looking for computer\-parsable output, use
+\fBshow\fR
+instead\&. Note that the log data shown is reported by the virtual machine or container manager, and frequently contains console output of the machine, but not necessarily journal contents of the machine itself\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBshow\fR [\fINAME\fR\&...]
+.RS 4
+Show properties of one or more registered virtual machines or containers or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a NAME is specified, properties of this virtual machine or container are shown\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required, and does not print the control group tree or journal entries\&. Use
+\fBstatus\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBstart\fR \fINAME\fR\&...
+.RS 4
+Start a container as a system service, using
+\fBsystemd-nspawn\fR(1)\&. This starts
+systemd\-nspawn@\&.service, instantiated for the specified machine name, similar to the effect of
+\fBsystemctl start\fR
+on the service name\&.
+\fBsystemd\-nspawn\fR
+looks for a container image by the specified name in
+/var/lib/machines/
+(and other search paths, see below) and runs it\&. Use
+\fBlist\-images\fR
+(see below) for listing available container images to start\&.
+.sp
+Note that
+\fBsystemd-machined.service\fR(8)
+also interfaces with a variety of other container and VM managers,
+\fBsystemd\-nspawn\fR
+is just one implementation of it\&. Most of the commands available in
+\fBmachinectl\fR
+may be used on containers or VMs controlled by other managers, not just
+\fBsystemd\-nspawn\fR\&. Starting VMs and container images on those managers requires manager\-specific tools\&.
+.sp
+To interactively start a container on the command line with full access to the container\*(Aqs console, please invoke
+\fBsystemd\-nspawn\fR
+directly\&. To stop a running container use
+\fBmachinectl poweroff\fR\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBlogin\fR [\fINAME\fR]
+.RS 4
+Open an interactive terminal login session in a container or on the local host\&. If an argument is supplied, it refers to the container machine to connect to\&. If none is specified, or the container name is specified as the empty string, or the special machine name
+"\&.host"
+(see below) is specified, the connection is made to the local host instead\&. This will create a TTY connection to a specific container or the local host and asks for the execution of a getty on it\&. Note that this is only supported for containers running
+\fBsystemd\fR(1)
+as init system\&.
+.sp
+This command will open a full login prompt on the container or the local host, which then asks for username and password\&. Use
+\fBshell\fR
+(see below) or
+\fBsystemd-run\fR(1)
+with the
+\fB\-\-machine=\fR
+switch to directly invoke a single command, either interactively or in the background\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBshell\fR [[\fINAME\fR@]\fINAME\fR [\fIPATH\fR [\fIARGUMENTS\fR\&...]]]
+.RS 4
+Open an interactive shell session in a container or on the local host\&. The first argument refers to the container machine to connect to\&. If none is specified, or the machine name is specified as the empty string, or the special machine name
+"\&.host"
+(see below) is specified, the connection is made to the local host instead\&. This works similarly to
+\fBlogin\fR, but immediately invokes a user process\&. This command runs the specified executable with the specified arguments, or the default shell for the user if none is specified, or
+/bin/sh
+if no default shell is found\&. By default,
+\fB\-\-uid=\fR, or by prefixing the machine name with a username and an
+"@"
+character, a different user may be selected\&. Use
+\fB\-\-setenv=\fR
+to set environment variables for the executed process\&.
+.sp
+Note that
+\fBmachinectl shell\fR
+does not propagate the exit code/status of the invoked shell process\&. Use
+\fBsystemd\-run\fR
+instead if that information is required (see below)\&.
+.sp
+Using the
+\fBshell\fR
+command without arguments (thus invoking the executed shell or command on the local host), is in many ways similar to a
+\fBsu\fR(1)
+session, but, unlike
+\fBsu\fR, completely isolates the new session from the originating session, so that it shares no process or session properties and is in a clean well\-defined state\&. It will be tracked in a new utmp, login, audit, security, and keyring sessions, and will not inherit any environment variables or resource limits, among other properties\&.
+.sp
+Note that
+\fBsystemd-run\fR(1)
+with its
+\fB\-\-machine=\fR
+switch may be used in place of the
+\fBmachinectl shell\fR
+command, and allows non\-interactive operation, more detailed and low\-level configuration of the invoked unit, as well as access to runtime and exit code/status information of the invoked shell process\&. In particular, use
+\fBsystemd\-run\fR\*(Aqs
+\fB\-\-wait\fR
+switch to propagate exit status information of the invoked process\&. Use
+\fBsystemd\-run\fR\*(Aqs
+\fB\-\-pty\fR
+switch to acquire an interactive shell, similarly to
+\fBmachinectl shell\fR\&. In general,
+\fBsystemd\-run\fR
+is preferable for scripting purposes\&. However, note that
+\fBsystemd\-run\fR
+might require higher privileges than
+\fBmachinectl shell\fR\&.
+.sp
+Added in version 225\&.
+.RE
+.PP
+\fBenable\fR \fINAME\fR\&..., \fBdisable\fR \fINAME\fR\&...
+.RS 4
+Enable or disable a container as a system service to start at system boot, using
+\fBsystemd-nspawn\fR(1)\&. This enables or disables
+systemd\-nspawn@\&.service, instantiated for the specified machine name, similarly to the effect of
+\fBsystemctl enable\fR
+or
+\fBsystemctl disable\fR
+on the service name\&.
+.sp
+This command implicitly reloads the system manager configuration after completing the operation\&. Note that this command does not implicitly start or power off the containers that are being operated on\&. If this is desired, combine the command with the
+\fB\-\-now\fR
+switch\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBpoweroff\fR \fINAME\fR\&...
+.RS 4
+Power off one or more containers\&. This will trigger a reboot by sending SIGRTMIN+4 to the container\*(Aqs init process, which causes systemd\-compatible init systems to shut down cleanly\&. Use
+\fBstop\fR
+as alias for
+\fBpoweroff\fR\&. This operation does not work on containers that do not run a
+\fBsystemd\fR(1)\-compatible init system, such as sysvinit\&. Use
+\fBterminate\fR
+(see below) to immediately terminate a container or VM, without cleanly shutting it down\&.
+.sp
+Added in version 212\&.
+.RE
+.PP
+\fBreboot\fR \fINAME\fR\&...
+.RS 4
+Reboot one or more containers\&. This will trigger a reboot by sending SIGINT to the container\*(Aqs init process, which is roughly equivalent to pressing Ctrl+Alt+Del on a non\-containerized system, and is compatible with containers running any system manager\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBterminate\fR \fINAME\fR\&...
+.RS 4
+Immediately terminates a virtual machine or container, without cleanly shutting it down\&. This kills all processes of the virtual machine or container and deallocates all resources attached to that instance\&. Use
+\fBpoweroff\fR
+to issue a clean shutdown request\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBkill\fR \fINAME\fR\&...
+.RS 4
+Send a signal to one or more processes of the virtual machine or container\&. This means processes as seen by the host, not the processes inside the virtual machine or container\&. Use
+\fB\-\-kill\-whom=\fR
+to select which process to kill\&. Use
+\fB\-\-signal=\fR
+to select the signal to send\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBbind\fR \fINAME\fR \fIPATH\fR [\fIPATH\fR]
+.RS 4
+Bind mounts a file or directory from the host into the specified container\&. The first path argument is the source file or directory on the host, the second path argument is the destination file or directory in the container\&. When the latter is omitted, the destination path in the container is the same as the source path on the host\&. When combined with the
+\fB\-\-read\-only\fR
+switch, a ready\-only bind mount is created\&. When combined with the
+\fB\-\-mkdir\fR
+switch, the destination path is first created before the mount is applied\&. Note that this option is currently only supported for
+\fBsystemd-nspawn\fR(1)
+containers, and only if user namespacing (\fB\-\-private\-users\fR) is not used\&. This command supports bind mounting directories, regular files, device nodes,
+\fBAF_UNIX\fR
+socket nodes, as well as FIFOs\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBcopy\-to\fR \fINAME\fR \fIPATH\fR [\fIPATH\fR] \fB\-\-force\fR
+.RS 4
+Copies files or directories from the host system into a running container\&. Takes a container name, followed by the source path on the host and the destination path in the container\&. If the destination path is omitted, the same as the source path is used\&.
+.sp
+If host and container share the same user and group namespace, file ownership by numeric user ID and group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root user and group (UID/GID 0)\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBcopy\-from\fR \fINAME\fR \fIPATH\fR [\fIPATH\fR] \fB\-\-force\fR
+.RS 4
+Copies files or directories from a container into the host system\&. Takes a container name, followed by the source path in the container and the destination path on the host\&. If the destination path is omitted, the same as the source path is used\&.
+.sp
+If host and container share the same user and group namespace, file ownership by numeric user ID and group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root user and group (UID/GID 0)\&.
+.sp
+Added in version 219\&.
+.RE
+.SS "Image Commands"
+.PP
+\fBlist\-images\fR
+.RS 4
+Show a list of locally installed container and VM images\&. This enumerates all raw disk images and container directories and subvolumes in
+/var/lib/machines/
+(and other search paths, see below)\&. Use
+\fBstart\fR
+(see above) to run a container off one of the listed images\&. Note that, by default, containers whose name begins with a dot ("\&.") are not shown\&. To show these too, specify
+\fB\-\-all\fR\&. Note that a special image
+"\&.host"
+always implicitly exists and refers to the image the host itself is booted from\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBimage\-status\fR [\fINAME\fR\&...]
+.RS 4
+Show terse status information about one or more container or VM images\&. This function is intended to generate human\-readable output\&. Use
+\fBshow\-image\fR
+(see below) to generate computer\-parsable output instead\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBshow\-image\fR [\fINAME\fR\&...]
+.RS 4
+Show properties of one or more registered virtual machine or container images, or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a NAME is specified, properties of this virtual machine or container image are shown\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBimage\-status\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBedit\fR \fINAME|FILE\fR
+.RS 4
+Edit the settings file of the specified machines\&. For the format of the settings file, refer to
+\fBsystemd.nspawn\fR(5)\&. If an existing settings file of the given machine can\*(Aqt be found,
+\fBedit\fR
+automatically create a new settings file from scratch under
+/etc/systemd/nspawn/\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBcat\fR \fINAME|FILE\fR
+.RS 4
+Show the settings file of the specified machines\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBclone\fR \fINAME\fR \fINAME\fR
+.RS 4
+Clones a container or VM image\&. The arguments specify the name of the image to clone and the name of the newly cloned image\&. Note that plain directory container images are cloned into btrfs subvolume images with this command, if the underlying file system supports this\&. Note that cloning a container or VM image is optimized for file systems that support copy\-on\-write, and might not be efficient on others, due to file system limitations\&.
+.sp
+Note that this command leaves hostname, machine ID and all other settings that could identify the instance unmodified\&. The original image and the cloned copy will hence share these credentials, and it might be necessary to manually change them in the copy\&.
+.sp
+If combined with the
+\fB\-\-read\-only\fR
+switch a read\-only cloned image is created\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBrename\fR \fINAME\fR \fINAME\fR
+.RS 4
+Renames a container or VM image\&. The arguments specify the name of the image to rename and the new name of the image\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBread\-only\fR \fINAME\fR [\fIBOOL\fR]
+.RS 4
+Marks or (unmarks) a container or VM image read\-only\&. Takes a VM or container image name, followed by a boolean as arguments\&. If the boolean is omitted, positive is implied, i\&.e\&. the image is marked read\-only\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBremove\fR \fINAME\fR\&...
+.RS 4
+Removes one or more container or VM images\&. The special image
+"\&.host", which refers to the host\*(Aqs own directory tree, may not be removed\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBset\-limit\fR [\fINAME\fR] \fIBYTES\fR
+.RS 4
+Sets the maximum size in bytes that a specific container or VM image, or all images, may grow up to on disk (disk quota)\&. Takes either one or two parameters\&. The first, optional parameter refers to a container or VM image name\&. If specified, the size limit of the specified image is changed\&. If omitted, the overall size limit of the sum of all images stored locally is changed\&. The final argument specifies the size limit in bytes, possibly suffixed by the usual K, M, G, T units\&. If the size limit shall be disabled, specify
+"\-"
+as size\&.
+.sp
+Note that per\-container size limits are only supported on btrfs file systems\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fBclean\fR
+.RS 4
+Remove hidden VM or container images (or all)\&. This command removes all hidden machine images from
+/var/lib/machines/, i\&.e\&. those whose name begins with a dot\&. Use
+\fBmachinectl list\-images \-\-all\fR
+to see a list of all machine images, including the hidden ones\&.
+.sp
+When combined with the
+\fB\-\-all\fR
+switch removes all images, not just hidden ones\&. This command effectively empties
+/var/lib/machines/\&.
+.sp
+Note that commands such as
+\fBmachinectl pull\-tar\fR
+or
+\fBmachinectl pull\-raw\fR
+usually create hidden, read\-only, unmodified machine images from the downloaded image first, before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are reused multiple times\&. Use
+\fBmachinectl clean\fR
+to remove old, hidden images created this way\&.
+.sp
+Added in version 230\&.
+.RE
+.SS "Image Transfer Commands"
+.PP
+\fBpull\-tar\fR \fIURL\fR [\fINAME\fR]
+.RS 4
+Downloads a
+\&.tar
+container image from the specified URL, and makes it available under the specified local machine name\&. The URL must be of type
+"http://"
+or
+"https://", and must refer to a
+\&.tar,
+\&.tar\&.gz,
+\&.tar\&.xz
+or
+\&.tar\&.bz2
+archive file\&. If the local machine name is omitted, it is automatically derived from the last component of the URL, with its suffix removed\&.
+.sp
+The image is verified before it is made available, unless
+\fB\-\-verify=no\fR
+is specified\&. Verification is done either via an inline signed file with the name of the image and the suffix
+\&.sha256
+or via separate
+SHA256SUMS
+and
+SHA256SUMS\&.gpg
+files\&. The signature files need to be made available on the same web server, under the same URL as the
+\&.tar
+file\&. With
+\fB\-\-verify=checksum\fR, only the SHA256 checksum for the file is verified, based on the
+\&.sha256
+suffixed file or the
+SHA256SUMS
+file\&. With
+\fB\-\-verify=signature\fR, the sha checksum file is first verified with the inline signature in the
+\&.sha256
+file or the detached GPG signature file
+SHA256SUMS\&.gpg\&. The public key for this verification step needs to be available in
+/usr/lib/systemd/import\-pubring\&.gpg
+or
+/etc/systemd/import\-pubring\&.gpg\&.
+.sp
+The container image will be downloaded and stored in a read\-only subvolume in
+/var/lib/machines/
+that is named after the specified URL and its HTTP etag\&. A writable snapshot is then taken from this subvolume, and named after the specified local name\&. This behavior ensures that creating multiple container instances of the same URL is efficient, as multiple downloads are not necessary\&. In order to create only the read\-only image, and avoid creating its writable snapshot, specify
+"\-"
+as local machine name\&.
+.sp
+Note that the read\-only subvolume is prefixed with
+\&.tar\-, and is thus not shown by
+\fBlist\-images\fR, unless
+\fB\-\-all\fR
+is passed\&.
+.sp
+Note that pressing C\-c during execution of this command will not abort the download\&. Use
+\fBcancel\-transfer\fR, described below\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBpull\-raw\fR \fIURL\fR [\fINAME\fR]
+.RS 4
+Downloads a
+\&.raw
+container or VM disk image from the specified URL, and makes it available under the specified local machine name\&. The URL must be of type
+"http://"
+or
+"https://"\&. The container image must either be a
+\&.qcow2
+or raw disk image, optionally compressed as
+\&.gz,
+\&.xz, or
+\&.bz2\&. If the local machine name is omitted, it is automatically derived from the last component of the URL, with its suffix removed\&.
+.sp
+Image verification is identical for raw and tar images (see above)\&.
+.sp
+If the downloaded image is in
+\&.qcow2
+format it is converted into a raw image file before it is made available\&.
+.sp
+Downloaded images of this type will be placed as read\-only
+\&.raw
+file in
+/var/lib/machines/\&. A local, writable (reflinked) copy is then made under the specified local machine name\&. To omit creation of the local, writable copy pass
+"\-"
+as local machine name\&.
+.sp
+Similarly to the behavior of
+\fBpull\-tar\fR, the read\-only image is prefixed with
+\&.raw\-, and thus not shown by
+\fBlist\-images\fR, unless
+\fB\-\-all\fR
+is passed\&.
+.sp
+Note that pressing C\-c during execution of this command will not abort the download\&. Use
+\fBcancel\-transfer\fR, described below\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBimport\-tar\fR \fIFILE\fR [\fINAME\fR], \fBimport\-raw\fR \fIFILE\fR [\fINAME\fR]
+.RS 4
+Imports a TAR or RAW container or VM image, and places it under the specified name in
+/var/lib/machines/\&. When
+\fBimport\-tar\fR
+is used, the file specified as the first argument should be a tar archive, possibly compressed with xz, gzip or bzip2\&. It will then be unpacked into its own subvolume in
+/var/lib/machines/\&. When
+\fBimport\-raw\fR
+is used, the file should be a qcow2 or raw disk image, possibly compressed with xz, gzip or bzip2\&. If the second argument (the resulting image name) is not specified, it is automatically derived from the file name\&. If the filename is passed as
+"\-", the image is read from standard input, in which case the second argument is mandatory\&.
+.sp
+Optionally, the
+\fB\-\-read\-only\fR
+switch may be used to create a read\-only container or VM image\&. No cryptographic validation is done when importing the images\&.
+.sp
+Much like image downloads, ongoing imports may be listed with
+\fBlist\-transfers\fR
+and aborted with
+\fBcancel\-transfer\fR\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fBimport\-fs\fR \fIDIRECTORY\fR [\fINAME\fR]
+.RS 4
+Imports a container image stored in a local directory into
+/var/lib/machines/, operates similarly to
+\fBimport\-tar\fR
+or
+\fBimport\-raw\fR, but the first argument is the source directory\&. If supported, this command will create a btrfs snapshot or subvolume for the new image\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fBexport\-tar\fR \fINAME\fR [\fIFILE\fR], \fBexport\-raw\fR \fINAME\fR [\fIFILE\fR]
+.RS 4
+Exports a TAR or RAW container or VM image and stores it in the specified file\&. The first parameter should be a VM or container image name\&. The second parameter should be a file path the TAR or RAW image is written to\&. If the path ends in
+"\&.gz", the file is compressed with gzip, if it ends in
+"\&.xz", with xz, and if it ends in
+"\&.bz2", with bzip2\&. If the path ends in neither, the file is left uncompressed\&. If the second argument is missing, the image is written to standard output\&. The compression may also be explicitly selected with the
+\fB\-\-format=\fR
+switch\&. This is in particular useful if the second parameter is left unspecified\&.
+.sp
+Much like image downloads and imports, ongoing exports may be listed with
+\fBlist\-transfers\fR
+and aborted with
+\fBcancel\-transfer\fR\&.
+.sp
+Note that, currently, only directory and subvolume images may be exported as TAR images, and only raw disk images as RAW images\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fBlist\-transfers\fR
+.RS 4
+Shows a list of container or VM image downloads, imports and exports that are currently in progress\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBcancel\-transfer\fR \fIID\fR\&...
+.RS 4
+Aborts a download, import or export of the container or VM image with the specified ID\&. To list ongoing transfers and their IDs, use
+\fBlist\-transfers\fR\&.
+.sp
+Added in version 219\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-p\fR, \fB\-\-property=\fR
+.RS 4
+When showing machine or image properties, limit the output to certain properties as specified by the argument\&. If not specified, all set properties are shown\&. The argument should be a property name, such as
+"Name"\&. If specified more than once, all properties with the specified names are shown\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-all\fR
+.RS 4
+When showing machine or image properties, show all properties regardless of whether they are set or not\&.
+.sp
+When listing VM or container images, do not suppress images beginning in a dot character ("\&.")\&.
+.sp
+When cleaning VM or container images, remove all images, not just hidden ones\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-value\fR
+.RS 4
+When printing properties with
+\fBshow\fR, only print the value, and skip the property name and
+"="\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize process tree entries or table\&. This implies
+\fB\-\-max\-addresses=full\fR\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-kill\-whom=\fR
+.RS 4
+When used with
+\fBkill\fR, choose which processes to kill\&. Must be one of
+\fBleader\fR, or
+\fBall\fR
+to select whether to kill only the leader process of the machine or all processes of the machine\&. If omitted, defaults to
+\fBall\fR\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-s\fR, \fB\-\-signal=\fR
+.RS 4
+When used with
+\fBkill\fR, choose which signal to send to selected processes\&. Must be one of the well\-known signal specifiers such as
+\fBSIGTERM\fR,
+\fBSIGINT\fR
+or
+\fBSIGSTOP\fR\&. If omitted, defaults to
+\fBSIGTERM\fR\&.
+.sp
+The special value
+"help"
+will list the known values and the program will exit immediately, and the special value
+"list"
+will list known values along with the numerical signal numbers and the program will exit immediately\&.
+.RE
+.PP
+\fB\-\-uid=\fR
+.RS 4
+When used with the
+\fBshell\fR
+command, chooses the user ID to open the interactive shell session as\&. If the argument to the
+\fBshell\fR
+command also specifies a user name, this option is ignored\&. If the name is not specified in either way,
+"root"
+will be used by default\&. Note that this switch is not supported for the
+\fBlogin\fR
+command (see below)\&.
+.sp
+Added in version 225\&.
+.RE
+.PP
+\fB\-E \fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR, \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
+.RS 4
+When used with the
+\fBshell\fR
+command, sets an environment variable for the executed shell\&. This option may be used more than once to set multiple variables\&. When
+"="
+and
+\fIVALUE\fR
+are omitted, the value of the variable with the same name in the program environment will be used\&.
+.sp
+Note that this option is not supported for the
+\fBlogin\fR
+command\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-mkdir\fR
+.RS 4
+When used with
+\fBbind\fR, creates the destination file or directory before applying the bind mount\&. Note that even though the name of this option suggests that it is suitable only for directories, this option also creates the destination file node to mount over if the object to mount is not a directory, but a regular file, device node, socket or FIFO\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-read\-only\fR
+.RS 4
+When used with
+\fBbind\fR, creates a read\-only bind mount\&.
+.sp
+When used with
+\fBclone\fR,
+\fBimport\-raw\fR
+or
+\fBimport\-tar\fR
+a read\-only container or VM image is created\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-lines=\fR
+.RS 4
+When used with
+\fBstatus\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument\&. Defaults to 10\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-o\fR, \fB\-\-output=\fR
+.RS 4
+When used with
+\fBstatus\fR, controls the formatting of the journal entries that are shown\&. For the available choices, see
+\fBjournalctl\fR(1)\&. Defaults to
+"short"\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-verify=\fR
+.RS 4
+When downloading a container or VM image, specify whether the image shall be verified before it is made available\&. Takes one of
+"no",
+"checksum"
+and
+"signature"\&. If
+"no", no verification is done\&. If
+"checksum"
+is specified, the download is checked for integrity after the transfer is complete, but no signatures are verified\&. If
+"signature"
+is specified, the checksum is verified and the image\*(Aqs signature is checked against a local keyring of trustable vendors\&. It is strongly recommended to set this option to
+"signature"
+if the server and protocol support this\&. Defaults to
+"signature"\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-now\fR
+.RS 4
+When used with
+\fBenable\fR
+or
+\fBdisable\fR, the containers will also be started or powered off\&. The start or poweroff operation is only carried out when the respective enable or disable operation has been successful\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-force\fR
+.RS 4
+When downloading a container or VM image, and a local copy by the specified local machine name already exists, delete it first and replace it by the newly downloaded image\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-format=\fR
+.RS 4
+When used with the
+\fBexport\-tar\fR
+or
+\fBexport\-raw\fR
+commands, specifies the compression format to use for the resulting file\&. Takes one of
+"uncompressed",
+"xz",
+"gzip",
+"bzip2"\&. By default, the format is determined automatically from the image file name passed\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-max\-addresses=\fR
+.RS 4
+When used with the
+\fBlist\-machines\fR
+command, limits the number of IP addresses shown for every machine\&. Defaults to 1\&. All addresses can be requested with
+"all"\&. If the limit is 0, the address column is not shown\&. Otherwise, if the machine has more addresses than shown,
+"\&..."
+follows the last address\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppresses additional informational output while running\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Connect to
+\fBsystemd-machined.service\fR(8)
+running in a local container, to perform the specified operation within the container\&.
+.sp
+Added in version 235\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "MACHINE AND IMAGE NAMES"
+.PP
+The
+\fBmachinectl\fR
+tool operates on machines and images whose names must be chosen following strict rules\&. Machine names must be suitable for use as hostnames following a conservative subset of DNS and UNIX/Linux semantics\&. Specifically, they must consist of one or more non\-empty label strings, separated by dots\&. No leading or trailing dots are allowed\&. No sequences of multiple dots are allowed\&. The label strings may only consist of alphanumeric characters as well as the dash and underscore\&. The maximum length of a machine name is 64 characters\&.
+.PP
+A special machine with the name
+"\&.host"
+refers to the running host system itself\&. This is useful for execution operations or inspecting the host system as well\&. Note that
+\fBmachinectl list\fR
+will not show this special machine unless the
+\fB\-\-all\fR
+switch is specified\&.
+.PP
+Requirements on image names are less strict, however, they must be valid UTF\-8, must be suitable as file names (hence not be the single or double dot, and not include a slash), and may not contain control characters\&. Since many operations search for an image by the name of a requested machine, it is recommended to name images in the same strict fashion as machines\&.
+.PP
+A special image with the name
+"\&.host"
+refers to the image of the running host system\&. It hence conceptually maps to the special
+"\&.host"
+machine name described above\&. Note that
+\fBmachinectl list\-images\fR
+will not show this special image either, unless
+\fB\-\-all\fR
+is specified\&.
+.SH "FILES AND DIRECTORIES"
+.PP
+Machine images are preferably stored in
+/var/lib/machines/, but are also searched for in
+/usr/local/lib/machines/
+and
+/usr/lib/machines/\&. For compatibility reasons, the directory
+/var/lib/container/
+is searched, too\&. Note that images stored below
+/usr/
+are always considered read\-only\&. It is possible to symlink machines images from other directories into
+/var/lib/machines/
+to make them available for control with
+\fBmachinectl\fR\&.
+.PP
+Note that some image operations are only supported, efficient or atomic on btrfs file systems\&.
+.PP
+Disk images are understood by
+\fBsystemd-nspawn\fR(1)
+and
+\fBmachinectl\fR
+in three formats:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A simple directory tree, containing the files and directories of the container to boot\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Subvolumes (on btrfs file systems), which are similar to the simple directories, described above\&. However, they have additional benefits, such as efficient cloning and quota reporting\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+"Raw" disk images, i\&.e\&. binary images of disks with a GPT or MBR partition table\&. Images of this type are regular files with the suffix
+"\&.raw"\&.
+.RE
+.PP
+See
+\fBsystemd-nspawn\fR(1)
+for more information on image formats, in particular its
+\fB\-\-directory=\fR
+and
+\fB\-\-image=\fR
+options\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Download a Ubuntu image and open a shell in it\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# machinectl pull\-tar https://cloud\-images\&.ubuntu\&.com/trusty/current/trusty\-server\-cloudimg\-amd64\-root\&.tar\&.gz
+# systemd\-nspawn \-M trusty\-server\-cloudimg\-amd64\-root
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This downloads and verifies the specified
+\&.tar
+image, and then uses
+\fBsystemd-nspawn\fR(1)
+to open a shell in it\&.
+.PP
+\fBExample\ \&2.\ \&Download a Fedora image, set a root password in it, start it as a service\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# machinectl pull\-raw \-\-verify=no \e
+      https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora\-Cloud\-Base\-38\-1\&.6\&.x86_64\&.raw\&.xz \e
+      Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+# systemd\-nspawn \-M Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+# passwd
+# exit
+# machinectl start Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+# machinectl login Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This downloads the specified
+\&.raw
+image with verification disabled\&. Then, a shell is opened in it and a root password is set\&. Afterwards the shell is left, and the machine started as system service\&. With the last command a login prompt into the container is requested\&.
+.PP
+\fBExample\ \&3.\ \&Exports a container image as tar file\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# machinectl export\-tar fedora myfedora\&.tar\&.xz
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Exports the container
+"fedora"
+as an xz\-compressed tar file
+myfedora\&.tar\&.xz
+into the current directory\&.
+.PP
+\fBExample\ \&4.\ \&Create a new shell session\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# machinectl shell \-\-uid=lennart
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This creates a new shell session on the local host for the user ID
+"lennart", in a
+\fBsu\fR(1)\-like fashion\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-machined.service\fR(8),
+\fBsystemd-nspawn\fR(1),
+\fBsystemd.special\fR(7),
+\fBtar\fR(1),
+\fBxz\fR(1),
+\fBgzip\fR(1),
+\fBbzip2\fR(1)
diff --git a/upstream/mageia-cauldron/man1/macptopbm.1 b/upstream/mageia-cauldron/man1/macptopbm.1
new file mode 100644
index 00000000..8979128d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/macptopbm.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Macptopbm User Manual" 0 "29 March 1989" "netpbm documentation"
+
+.SH NAME
+macptopbm - convert a MacPaint file into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmacptopbm\fP [\fB-extraskip\fP \fIN\fP] [\fImacpfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBmacptopbm\fPreads a MacPaint file as input and produces a PBM
+image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBmacptopbm\fP recognizes the following
+command line option:
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB-extraskip\fP
+This option is to get around a problem with some methods of
+transferring files from the Mac world to the Unix world.  Most of
+these methods leave the Mac files alone, but a few of them add the
+"finderinfo" data onto the front of the Unix file.  This
+means an extra 128 bytes to skip over when reading the file.  The
+symptom to watch for is that the resulting PBM file looks shifted to
+one side.  If you get this, try \fB-extraskip\fP 128, and if that
+still doesn't look right try another value.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "picttoppm" (1)\c
+\&,
+.BR "pbmtomacp" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+
+The MacPaint-reading code is copyright (c) 1987 by Patrick J. Naughton
+(\fInaughton@wind.sun.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/macptopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/mailq.1 b/upstream/mageia-cauldron/man1/mailq.1
new file mode 100644
index 00000000..6b5069b8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mailq.1
@@ -0,0 +1,135 @@
+.\" Copyright (c) 1998-2000, 2002, 2007 Proofpoint, Inc. and its suppliers.
+.\"	 All rights reserved.
+.\" Copyright (c) 1983, 1997 Eric P. Allman.  All rights reserved.
+.\" Copyright (c) 1985, 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" By using this file, you agree to the terms and conditions set
+.\" forth in the LICENSE file which can be found at the top level of
+.\" the sendmail distribution.
+.\"
+.\"
+.\"     $Id: mailq.1,v 8.22 2013-11-22 20:51:55 ca Exp $
+.\"
+.TH MAILQ 1 "$Date: 2013-11-22 20:51:55 $"
+.SH NAME
+mailq
+\- print the mail queue
+.SH SYNOPSIS
+.B mailq
+.RB [ \-Ac ]
+.RB [ \-q... ]
+.RB [ \-v ]
+.SH DESCRIPTION
+.B Mailq
+prints a summary of the mail messages queued for future delivery.
+.PP
+The first line printed for each message
+shows the internal identifier used on this host
+for the message with a possible status character,
+the size of the message in bytes,
+the date and time the message was accepted into the queue,
+and the envelope sender of the message.
+The second line shows the error message that caused this message
+to be retained in the queue;
+it will not be present if the message is being processed
+for the first time.
+The status characters are either
+.B *
+to indicate the job is being processed;
+.B X
+to indicate that the load is too high to process the job; and
+.B -
+to indicate that the job is too young to process.
+The following lines show message recipients,
+one per line.
+.PP
+.B Mailq
+is identical to ``sendmail -bp''.
+.PP
+The relevant options are as follows:
+.TP
+.B \-Ac
+Show the mail submission queue specified in
+.I /etc/mail/submit.cf
+instead of the MTA queue specified in
+.IR /etc/mail/sendmail.cf .
+.TP
+.B \-qL
+Show the "lost" items in the mail queue instead of the normal queue items.
+.TP
+.B \-qQ
+Show the quarantined items in the mail queue instead of the normal queue
+items.
+.TP
+\fB\-q\fR[\fI!\fR]I substr
+Limit processed jobs to those containing
+.I substr
+as a substring of the queue id or not when
+.I !
+is specified.
+.TP
+\fB\-q\fR[\fI!\fR]Q substr
+Limit processed jobs to quarantined jobs containing
+.I substr
+as a substring of the quarantine reason or not when
+.I !
+is specified.
+.TP
+\fB\-q\fR[\fI!\fR]R substr
+Limit processed jobs to those containing
+.I substr
+as a substring of one of the recipients or not when
+.I !
+is specified.
+.TP
+\fB\-q\fR[\fI!\fR]S substr
+Limit processed jobs to those containing
+.I substr
+as a substring of the sender or not when
+.I !
+is specified.
+.TP
+.B \-v
+Print verbose information.
+This adds the priority of the message and
+a single character indicator (``+'' or blank)
+indicating whether a warning message has been sent
+on the first line of the message.
+Additionally, extra lines may be intermixed with the recipients
+indicating the ``controlling user'' information;
+this shows who will own any programs that are executed
+on behalf of this message
+and the name of the alias this command expanded from, if any.
+Moreover, status messages for each recipient are printed
+if available.
+.PP
+Several sendmail.cf options influence the behavior of the
+.B mailq
+utility:
+The number of items printed per queue group is restricted by
+.B MaxQueueRunSize
+if that value is set.
+The status character
+.B *
+is not printed for some values of
+.B QueueSortOrder,
+e.g.,
+filename,
+random,
+modification, and
+none,
+unless a
+.B -q
+option is used to limit the processed jobs.
+.PP
+The
+.B mailq
+utility exits 0 on success, and >0 if an error occurs.
+.SH SEE ALSO
+sendmail(8)
+.SH HISTORY
+The
+.B mailq
+command appeared in
+4.0BSD.
diff --git a/upstream/mageia-cauldron/man1/mailstat.1 b/upstream/mageia-cauldron/man1/mailstat.1
new file mode 100644
index 00000000..b437d2e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mailstat.1
@@ -0,0 +1,86 @@
+.\"if n .pl +(135i-\n(.pu)
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.rn SH Sh
+.de SH
+.br
+.ne 11
+.Sh "\\$1"
+..
+.rn SS Ss
+.de SS
+.br
+.ne 10
+.Ss "\\$1"
+..
+.rn TP Tp
+.de TP
+.br
+.ne 9
+.Tp \\$1
+..
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.Sh SOURCE
+This program is part of the
+.I procmail mail-processing-package
+(v3.24) available at http://www.procmail.org/ or
+ftp.procmail.org in
+.BR pub/procmail/ .
+.Sh MAILINGLIST
+There exists a mailinglist for questions relating to any program in the
+procmail package:
+.RS
+<procmail-users@procmail.org>
+.RS
+for submitting questions/answers.
+.RE
+<procmail-users-request@procmail.org>
+.RS
+for subscription requests.
+.RE
+.PP
+.RE
+If you would like to stay informed about new versions and official patches send
+a subscription request to
+.RS
+procmail-announce-request@procmail.org
+.RE
+(this is a readonly list).
+.SH AUTHORS
+Stephen R. van den Berg
+.RS
+<srb@cuci.nl>
+.RE
+.\".if n .pl -(\n(.tu-1i)
+.rm SH
+.rn Sh SH
+.rm SS
+.rn Ss SS
+.rm TP
+.rn Tp TP
+.rm RS
+.rn Rs RS
+.rm RE
+.rn Re RE
diff --git a/upstream/mageia-cauldron/man1/make.1 b/upstream/mageia-cauldron/man1/make.1
new file mode 100644
index 00000000..f02afbee
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/make.1
@@ -0,0 +1,413 @@
+.TH MAKE 1 "26 May 2023" "GNU" "User Commands"
+.SH NAME
+make \- GNU Make utility to maintain groups of programs
+.SH SYNOPSIS
+.B make
+[\fIOPTION\fR]... [\fITARGET\fR]...
+.SH DESCRIPTION
+.LP
+The
+.I make
+utility will determine automatically which pieces of a large program need to
+be recompiled, and issue the commands to recompile them.  The manual describes
+the GNU implementation of
+.BR make ,
+which was written by Richard Stallman and Roland McGrath, and is currently
+maintained by Paul Smith.  Our examples show C programs, since they are very
+common, but you can use
+.B make
+with any programming language whose compiler can be run with a shell command.
+In fact,
+.B make
+is not limited to programs.  You can use it to describe any task where some
+files must be updated automatically from others whenever the others change.
+.LP
+To prepare to use
+.BR make ,
+you must write a file called the
+.I makefile
+that describes the relationships among files in your program, and provides
+commands for updating each file.  In a program, typically the executable file
+is updated from object files, which are in turn made by compiling source
+files.
+.LP
+Once a suitable makefile exists, each time you change some source files,
+this simple shell command:
+.sp 1
+.RS
+.B make
+.RE
+.sp 1
+suffices to perform all necessary recompilations.
+The
+.B make
+program uses the makefile description and the last-modification times of the
+files to decide which of the files need to be updated.  For each of those
+files, it issues the commands recorded in the makefile.
+.LP
+.B make
+executes commands in the
+.I makefile
+to update one or more
+.IR targets ,
+where
+.I target
+is typically a program.
+If no
+.B \-f
+option is present,
+.B make
+will look for the makefiles
+.IR GNUmakefile ,
+.IR makefile ,
+and
+.IR Makefile ,
+in that order.
+.LP
+Normally you should call your makefile either
+.I makefile
+or
+.IR Makefile .
+(We recommend
+.I Makefile
+because it appears prominently near the beginning of a directory
+listing, right near other important files such as
+.IR  README .)
+The first name checked,
+.IR GNUmakefile ,
+is not recommended for most makefiles.  You should use this name if you have a
+makefile that is specific to GNU Make, and will not be understood by other
+versions of
+.BR make .
+If
+.I makefile
+is '\-', the standard input is read.
+.LP
+.B make
+updates a target if it depends on prerequisite files
+that have been modified since the target was last modified,
+or if the target does not exist.
+.SH OPTIONS
+.sp 1
+.TP 0.5i
+\fB\-b\fR, \fB\-m\fR
+These options are ignored for compatibility with other versions of
+.BR make .
+.TP 0.5i
+\fB\-B\fR, \fB\-\-always\-make\fR
+Unconditionally make all targets.
+.TP 0.5i
+\fB\-C\fR \fIdir\fR, \fB\-\-directory\fR=\fIdir\fR
+Change to directory
+.I dir
+before reading the makefiles or doing anything else.
+If multiple
+.B \-C
+options are specified, each is interpreted relative to the
+previous one:
+.BR "\-C " /
+.BR "\-C " etc
+is equivalent to
+.BR "\-C " /etc.
+This is typically used with recursive invocations of
+.BR make .
+.TP 0.5i
+.B \-d
+Print debugging information in addition to normal processing.
+The debugging information says which files are being considered for
+remaking, which file-times are being compared and with what results,
+which files actually need to be remade, which implicit rules are
+considered and which are applied---everything interesting about how
+.B make
+decides what to do.
+.TP 0.5i
+.BI \-\-debug "[=FLAGS]"
+Print debugging information in addition to normal processing.
+If the
+.I FLAGS
+are omitted, then the behavior is the same as if
+.B \-d
+was specified.
+.I FLAGS
+may be any or all of the following names, comma- or space-separated.  Only the
+first character is significant: the rest may be omitted:
+.I all
+for all debugging output (same as using
+.BR \-d ),
+.I basic
+for basic debugging,
+.I verbose
+for more verbose basic debugging,
+.I implicit
+for showing implicit rule search operations,
+.I jobs
+for details on invocation of commands,
+.I makefile
+for debugging while remaking makefiles,
+.I print
+shows all recipes that are run even if they are silent, and
+.I why
+shows the reason
+.BR make
+decided to rebuild each target.  Use
+.I none
+to disable all previous debugging flags.
+.TP 0.5i
+\fB\-e\fR, \fB\-\-environment\-overrides\fR
+Give variables taken from the environment precedence over variables
+from makefiles.
+.TP 0.5i
+\fB\-E\fR \fIstring\fR, \fB\-\-eval\fR \fIstring\fR
+Interpret \fIstring\fR using the \fBeval\fR function, before parsing any
+makefiles.
+.TP 0.5i
+\fB\-f\fR \fIfile\fR, \fB\-\-file\fR=\fIfile\fR, \fB\-\-makefile\fR=\fIFILE\fR
+Use
+.I file
+as a makefile.
+.TP 0.5i
+\fB\-i\fR, \fB\-\-ignore\-errors\fR
+Ignore all errors in commands executed to remake files.
+.TP 0.5i
+\fB\-I\fR \fIdir\fR, \fB\-\-include\-dir\fR=\fIdir\fR
+Specifies a directory
+.I dir
+to search for included makefiles.
+If several
+.B \-I
+options are used to specify several directories, the directories are
+searched in the order specified.
+Unlike the arguments to other flags of
+.BR make ,
+directories given with
+.B \-I
+flags may come directly after the flag:
+.BI \-I dir
+is allowed, as well as
+.B \-I
+.IR dir .
+This syntax is allowed for compatibility with the C
+preprocessor's
+.B \-I
+flag.
+.TP 0.5i
+\fB\-j\fR [\fIjobs\fR], \fB\-\-jobs\fR[=\fIjobs\fR]
+Specifies the number of
+.I jobs
+(commands) to run simultaneously.
+If there is more than one
+.B \-j
+option, the last one is effective.
+If the
+.B \-j
+option is given without an argument,
+.BR make
+will not limit the number of jobs that can run simultaneously.
+.TP 0.5i
+\fB\--jobserver-style=\fR\fIstyle\fR
+The style of jobserver to use.  The
+.I style
+may be one of
+.BR fifo ,
+.BR pipe ,
+or
+.B sem
+(Windows only).
+.TP 0.5i
+\fB\-k\fR, \fB\-\-keep\-going\fR
+Continue as much as possible after an error.
+While the target that failed, and those that depend on it, cannot
+be remade, the other dependencies of these targets can be processed
+all the same.
+.TP 0.5i
+\fB\-l\fR [\fIload\fR], \fB\-\-load\-average\fR[=\fIload\fR]
+Specifies that no new jobs (commands) should be started if there are
+others jobs running and the load average is at least
+.I load
+(a floating-point number).
+With no argument, removes a previous load limit.
+.TP 0.5i
+\fB\-L\fR, \fB\-\-check\-symlink\-times\fR
+Use the latest mtime between symlinks and target.
+.TP 0.5i
+\fB\-n\fR, \fB\-\-just\-print\fR, \fB\-\-dry\-run\fR, \fB\-\-recon\fR
+Print the commands that would be executed, but do not execute them (except in
+certain circumstances).
+.TP 0.5i
+\fB\-o\fR \fIfile\fR, \fB\-\-old\-file\fR=\fIfile\fR, \fB\-\-assume\-old\fR=\fIfile\fR
+Do not remake the file
+.I file
+even if it is older than its dependencies, and do not remake anything
+on account of changes in
+.IR file .
+Essentially the file is treated as very old and its rules are ignored.
+.TP 0.5i
+\fB\-O\fR[\fItype\fR], \fB\-\-output\-sync\fR[=\fItype\fR]
+When running multiple jobs in parallel with \fB-j\fR, ensure the output of
+each job is collected together rather than interspersed with output from
+other jobs.  If
+.I type
+is not specified or is
+.B target
+the output from the entire recipe for each target is grouped together.  If
+.I type
+is
+.B line
+the output from each command line within a recipe is grouped together.
+If
+.I type
+is
+.B recurse
+output from an entire recursive make is grouped together.  If
+.I type
+is
+.B none
+output synchronization is disabled.
+.TP 0.5i
+\fB\-p\fR, \fB\-\-print\-data\-base\fR
+Print the data base (rules and variable values) that results from
+reading the makefiles; then execute as usual or as otherwise
+specified.
+This also prints the version information given by the
+.B \-v
+switch (see below).
+To print the data base without trying to remake any files, use
+.IR "make \-p \-f/dev/null" .
+.TP 0.5i
+\fB\-q\fR, \fB\-\-question\fR
+``Question mode''.
+Do not run any commands, or print anything; just return an exit status
+that is zero if the specified targets are already up to date, nonzero
+otherwise.
+.TP 0.5i
+\fB\-r\fR, \fB\-\-no\-builtin\-rules\fR
+Eliminate use of the built\-in implicit rules.
+Also clear out the default list of suffixes for suffix rules.
+.TP 0.5i
+\fB\-R\fR, \fB\-\-no\-builtin\-variables\fR
+Don't define any built\-in variables.
+.TP 0.5i
+\fB\-s\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR
+Silent operation; do not print the commands as they are executed.
+.TP 0.5i
+.B \-\-no\-silent
+Cancel the effect of the \fB\-s\fR option.
+.TP 0.5i
+\fB\-S\fR, \fB\-\-no\-keep\-going\fR, \fB\-\-stop\fR
+Cancel the effect of the
+.B \-k
+option.
+.TP 0.5i
+\fB\-t\fR, \fB\-\-touch\fR
+Touch files (mark them up to date without really changing them)
+instead of running their commands.
+This is used to pretend that the commands were done, in order to fool
+future invocations of
+.BR make .
+.TP 0.5i
+.B \-\-trace
+Information about the disposition of each target is printed (why the target is
+being rebuilt and what commands are run to rebuild it).
+.TP 0.5i
+\fB\-v\fR, \fB\-\-version\fR
+Print the version of the
+.B make
+program plus a copyright, a list of authors and a notice that there
+is no warranty.
+.TP 0.5i
+\fB\-w\fR, \fB\-\-print\-directory\fR
+Print a message containing the working directory
+before and after other processing.
+This may be useful for tracking down errors from complicated nests of
+recursive
+.B make
+commands.
+.TP 0.5i
+.B \-\-no\-print\-directory
+Turn off
+.BR \-w ,
+even if it was turned on implicitly.
+.TP 0.5i
+.BI \-\-shuffle "[=MODE]"
+Enable shuffling of goal and prerequisite ordering.
+.I MODE
+is one of
+.I none
+to disable shuffle mode,
+.I random
+to shuffle prerequisites in random order,
+.I reverse
+to consider prerequisites in reverse order, or an integer
+.I <seed>
+which enables
+.I random
+mode with a specific
+.I seed
+value.  If
+.I MODE
+is omitted the default is
+.IR random .
+.TP 0.5i
+\fB\-W\fR \fIfile\fR, \fB\-\-what\-if\fR=\fIfile\fR, \fB\-\-new\-file\fR=\fIfile\fR, \fB\-\-assume\-new\fR=\fIfile\fR
+Pretend that the target
+.I file
+has just been modified.
+When used with the
+.B \-n
+flag, this shows you what would happen if you were to modify that file.
+Without
+.BR \-n ,
+it is almost the same as running a
+.I touch
+command on the given file before running
+.BR make ,
+except that the modification time is changed only in the imagination of
+.BR make .
+.TP 0.5i
+.B \-\-warn\-undefined\-variables
+Warn when an undefined variable is referenced.
+.SH "EXIT STATUS"
+GNU Make exits with a status of zero if all makefiles were successfully parsed
+and no targets that were built failed.  A status of one will be returned
+if the
+.B \-q
+flag was used and
+.B make
+determines that a target needs to be rebuilt.  A status of two will be
+returned if any errors were encountered.
+.SH "SEE ALSO"
+The full documentation for
+.B make
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B make
+programs are properly installed at your site, the command
+.IP
+.B info make
+.PP
+should give you access to the complete manual.
+.SH BUGS
+See the chapter ``Problems and Bugs'' in
+.IR "The GNU Make Manual" .
+.SH AUTHOR
+This manual page contributed by Dennis Morse of Stanford University.
+Further updates contributed by Mike Frysinger.  It has been reworked by Roland
+McGrath.  Maintained by Paul Smith.
+.SH "COPYRIGHT"
+Copyright \(co 1992-1993, 1996-2023 Free Software Foundation, Inc.
+This file is part of
+.IR "GNU Make" .
+.LP
+GNU Make 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.
+.LP
+GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+.LP
+You should have received a copy of the GNU General Public License along with
+this program.  If not, see
+.IR https://www.gnu.org/licenses/ .
diff --git a/upstream/mageia-cauldron/man1/makeinfo.1 b/upstream/mageia-cauldron/man1/makeinfo.1
new file mode 100644
index 00000000..7d9ceefb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/makeinfo.1
@@ -0,0 +1,273 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH TEXI2ANY "1" "October 2023" "GNU texinfo 7.1" "User Commands"
+.SH NAME
+texi2any \- translate Texinfo documents
+.SH SYNOPSIS
+.B makeinfo
+[\fI\,OPTION\/\fR]... \fI\,TEXINFO-FILE\/\fR...
+.SH DESCRIPTION
+Translate Texinfo source documentation to various other formats, by default
+Info files suitable for reading online with Emacs or standalone GNU Info.
+.PP
+This program is commonly installed as both `makeinfo' and `texi2any';
+the behavior is identical, and does not depend on the installed name.
+.SS "General options:"
+.TP
+\fB\-\-document\-language\fR=\fI\,STR\/\fR locale to use in translating Texinfo keywords
+for the output document (default C).
+.TP
+\fB\-\-error\-limit\fR=\fI\,NUM\/\fR
+quit after NUM errors (default 100).
+.TP
+\fB\-\-force\fR
+preserve output even if errors.
+.TP
+\fB\-\-help\fR
+display this help and exit.
+.TP
+\fB\-\-no\-validate\fR
+suppress node cross\-reference validation.
+.TP
+\fB\-\-no\-warn\fR
+suppress warnings (but not errors).
+.TP
+\fB\-\-conf\-dir\fR=\fI\,DIR\/\fR
+search also for initialization files in DIR.
+.TP
+\fB\-\-init\-file\fR=\fI\,FILE\/\fR
+load FILE to modify the default behavior.
+.TP
+\fB\-c\fR, \fB\-\-set\-customization\-variable\fR VAR=VAL
+set customization variable VAR
+to value VAL.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+explain what is being done.
+.TP
+\fB\-\-version\fR
+display version information and exit.
+.SS "Output format selection (default is to produce Info):"
+.TP
+\fB\-\-docbook\fR
+output Docbook XML.
+.TP
+\fB\-\-html\fR
+output HTML.
+.TP
+\fB\-\-epub3\fR
+output EPUB 3.
+.TP
+\fB\-\-latex\fR
+output LaTeX.
+.TP
+\fB\-\-plaintext\fR
+output plain text rather than Info.
+.TP
+\fB\-\-xml\fR
+output Texinfo XML.
+.TP
+\fB\-\-dvi\fR, \fB\-\-dvipdf\fR, \fB\-\-ps\fR, \fB\-\-pdf\fR
+call texi2dvi to generate given output,
+after checking validity of TEXINFO\-FILE.
+.SS "General output options:"
+.TP
+\fB\-E\fR, \fB\-\-macro\-expand\fR=\fI\,FILE\/\fR
+output macro\-expanded source to FILE,
+ignoring any @setfilename.
+.TP
+\fB\-\-no\-headers\fR
+suppress node separators, Node: lines, and menus
+from Info output (thus producing plain text)
+or from HTML (thus producing shorter output).
+Also, if producing Info, write to
+standard output by default.
+.TP
+\fB\-\-no\-split\fR
+suppress any splitting of the output;
+generate only one output file.
+.TP
+\fB\-\-[no\-]number\-sections\fR
+output chapter and sectioning numbers;
+default is on.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,DEST\/\fR
+output to DEST.
+With split output, create DEST as a directory
+and put the output files there.
+With non\-split output, if DEST is already
+a directory or ends with a /,
+put the output file there.
+Otherwise, DEST names the output file.
+.TP
+\fB\-\-disable\-encoding\fR
+do not output accented and special characters
+in Info and plain text output based on document
+encoding.
+.TP
+\fB\-\-enable\-encoding\fR
+override \fB\-\-disable\-encoding\fR (default).
+.SS "Options for Info and plain text:"
+.TP
+\fB\-\-fill\-column\fR=\fI\,NUM\/\fR
+break Info lines at NUM columns (default 72).
+.TP
+\fB\-\-footnote\-style\fR=\fI\,STYLE\/\fR
+output footnotes in Info according to STYLE:
+`separate' to put them in their own node;
+`end' to put them at the end of the node, in
+which they are defined (this is the default).
+.TP
+\fB\-\-paragraph\-indent\fR=\fI\,VAL\/\fR
+indent Info paragraphs by VAL spaces (default 3).
+If VAL is `none', do not indent; if VAL is
+`asis', preserve existing indentation.
+.TP
+\fB\-\-split\-size\fR=\fI\,NUM\/\fR
+split Info files at size NUM (default 300000).
+.SS "Options for HTML:"
+.TP
+\fB\-\-css\-include\fR=\fI\,FILE\/\fR
+include FILE in HTML <style> output;
+read stdin if FILE is \-.
+.TP
+\fB\-\-css\-ref\fR=\fI\,URL\/\fR
+generate CSS reference to URL.
+.TP
+\fB\-\-internal\-links\fR=\fI\,FILE\/\fR
+produce list of internal links in FILE.
+.TP
+\fB\-\-split\fR=\fI\,SPLIT\/\fR
+split at SPLIT, where SPLIT may be `chapter',
+`section' or `node'.
+.TP
+\fB\-\-transliterate\-file\-names\fR
+use file names in ASCII transliteration.
+.TP
+\fB\-\-node\-files\fR
+produce redirection files for nodes and
+anchors; default is set only if split.
+.SS "Options for DVI/PS/PDF:"
+.TP
+\fB\-\-Xopt\fR=\fI\,OPT\/\fR
+pass OPT to texi2dvi; can be repeated.
+.SS "Input file options:"
+.TP
+\fB\-D\fR VAR
+define the variable VAR, as with @set.
+.TP
+\fB\-D\fR 'VAR VAL'
+define VAR to VAL (one shell argument).
+.TP
+\fB\-I\fR DIR
+append DIR to the @include search path.
+.TP
+\fB\-P\fR DIR
+prepend DIR to the @include search path.
+.TP
+\fB\-U\fR VAR
+undefine the variable VAR, as with @clear.
+.SS "Conditional processing in input:"
+.TP
+\fB\-\-ifdocbook\fR
+process @ifdocbook and @docbook even if
+not generating Docbook.
+.TP
+\fB\-\-ifhtml\fR
+process @ifhtml and @html even if not generating HTML.
+.TP
+\fB\-\-ifinfo\fR
+process @ifinfo even if not generating Info.
+.TP
+\fB\-\-iflatex\fR
+process @iflatex and @latex.
+.TP
+\fB\-\-ifplaintext\fR
+process @ifplaintext even if not generating plain text.
+.TP
+\fB\-\-iftex\fR
+process @iftex and @tex.
+.TP
+\fB\-\-ifxml\fR
+process @ifxml and @xml.
+.TP
+\fB\-\-no\-ifdocbook\fR
+do not process @ifdocbook and @docbook text.
+.TP
+\fB\-\-no\-ifhtml\fR
+do not process @ifhtml and @html text.
+.TP
+\fB\-\-no\-ifinfo\fR
+do not process @ifinfo text.
+.TP
+\fB\-\-no\-iflatex\fR
+do not process @iflatex and @latex text.
+.TP
+\fB\-\-no\-ifplaintext\fR
+do not process @ifplaintext text.
+.TP
+\fB\-\-no\-iftex\fR
+do not process @iftex and @tex text.
+.TP
+\fB\-\-no\-ifxml\fR
+do not process @ifxml and @xml text.
+.P
+Also, for the \fB\-\-no\-ifFORMAT\fR options, do process @ifnotFORMAT text.
+.P
+The defaults for the @if... conditionals depend on the output format:
+if generating Docbook, \fB\-\-ifdocbook\fR is on and the others are off;
+if generating HTML, \fB\-\-ifhtml\fR is on and the others are off;
+if generating Info, \fB\-\-ifinfo\fR is on and the others are off;
+if generating plain text, \fB\-\-ifplaintext\fR is on and the others are off;
+if generating LaTeX, \fB\-\-iflatex\fR is on and the others are off;
+if generating XML, \fB\-\-ifxml\fR is on and the others are off.
+.SH EXAMPLES
+.TP
+makeinfo foo.texi
+write Info to foo's @setfilename
+.TP
+makeinfo \-\-html foo.texi
+write HTML to @setfilename
+.TP
+makeinfo \-\-xml foo.texi
+write Texinfo XML to @setfilename
+.TP
+makeinfo \-\-docbook foo.texi
+write Docbook XML to @setfilename
+.TP
+makeinfo \-\-plaintext foo.texi
+write plain text to standard output
+.TP
+makeinfo \-\-pdf foo.texi
+write PDF using texi2dvi
+.TP
+makeinfo \-\-html \-\-no\-headers foo.texi
+write html without node lines, menus
+.TP
+makeinfo \-\-number\-sections foo.texi
+write Info with numbered sections
+.TP
+makeinfo \-\-no\-split foo.texi
+write one Info file however big
+.SH "REPORTING BUGS"
+Email bug reports to bug\-texinfo@gnu.org,
+general questions and discussion to help\-texinfo@gnu.org.
+.br
+Texinfo home page: http://www.gnu.org/software/texinfo/
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B texi2any
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B texi2any
+programs are properly installed at your site, the command
+.IP
+.B info texi2any
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/manweb.1 b/upstream/mageia-cauldron/man1/manweb.1
new file mode 100644
index 00000000..9e73250a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/manweb.1
@@ -0,0 +1,278 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Manweb Reference Documentation" 0 "" "netpbm documentation"
+
+ .SH NAME
+manweb - browse netpbm (and other) documentation
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmanweb\fP \fB-help\fP
+.PP
+\fBmanweb\fP
+[\fB-config=\fIconfigfile\fP\fP]
+[\fItopic\fP [ \fIsubtopic\fP ... ] ]
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+manweb
+
+.fi
+This gets a master index of documentation.
+.nf
+manweb netpbm
+
+.fi
+This gets the main documentation page for the Netpbm package, with hyperlinks
+to the rest of the documentation.
+.nf
+manweb netpbm pngtopam
+
+.fi
+This goes directly to the documentation page for the Pngtopam program in
+the Netpbm package.
+.nf
+manweb pngtopam
+
+.fi
+This also goes directly to the documentation page for the Pngtopam program in
+the Netpbm package, if that's what would run in response to a \fBpngtopam\fP
+shell command (your \fBPATH\fP environment variable is involved).
+.nf
+manweb 3 fopen
+
+.fi
+This gets the traditional man page for the fopen() subroutine using
+\fBman\fP.
+.nf
+manweb cp
+
+.fi
+This gets the GNU Info manual for the \fBcp\fP program, using \fBinfo\fP.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+\fBmanweb\fP displays reference documentation via quick shell
+commands.  It is a replacement for the well-known \fBman\fP.
+
+.SH Differences Between Man and Manweb
+.PP
+\fBmanweb\fP's advantages over \fBman\fP are:
+
+
+.IP \(bu
+
+       You can access documentation that is on the worldwide web instead of
+       having locally installed copies.  This saves installation work and gets
+       you more current documentation.
+
+.IP \(bu
+
+       Documentation can be in HTML, which is more widely known, more widely
+       useful, and more expressive than the nroff/troff format used by
+       \fBman\fP.
+
+.IP \(bu
+
+       \fBmanweb\fP puts your topics in a tree for multilevel documentation.
+       \fBman\fP is intended for a single level of documentation.  For
+       example, you can have a man page for each shell command, but not for
+       the subcommands of a shell command.  And you cannot properly have
+       man pages for the members of multiple subroutine libraries.
+
+.IP \(bu
+
+       Documentation can be hyperlinked.
+
+.PP
+Web servers need not be involved -- the documentation can be in local
+files.  Graphics need not be involved -- the \fBlynx\fP browser works fine
+in the same kind of terminals in which \fBman\fP works.
+.PP
+\fBmanweb\fP finds the documentation you specify and calls a web
+browser of your choice to display it.  The documentation \fBmanweb\fP
+finds can be either an HTML file on your system, in which case,
+\fBmanweb\fP gives a \fBfile:\fP URL to your browser, or an explicit
+URL.  That explicit URL might be an \fBhttp:\fP URL referring to an
+HTML file on a web server somewhere, or anything else your browser
+understands.
+.PP
+If \fBmanweb\fP finds neither an HTML file nor a URL, but your parameters
+look like they could mean something to \fBman\fP, \fBmanweb\fP calls
+\fBman\fP.  Therefore, you can use a single command to access the vast
+body of traditional man pages, plus any newer \fBmanweb\fP documentation.
+You can make "man" a shell alias of "manweb".
+.PP
+\fBmanweb\fP finds Info documentation as well.  It looks for the
+topic you specify as an Info topic after looking for HTML and URL
+documentation and before running \fBman\fP.  If \fBmanweb\fP finds a
+corresponding Info topic, it runs the program \fBinfo\fP on it.  Info
+is the documentation system that the GNU project invented to, among
+other things, replace traditional Unix man pages.  However, HTML and the
+Worldwide Web were invented shortly afterward, so Info fizzled.  But there
+is still a lot of GNU software that is documented as Info topics.
+
+.SS How Manweb Finds Documentation
+.PP
+\fBmanweb\fP passes a URL to a web browser.  This section tells
+how your \fBmanweb\fP invocation parameters turn into that URL.
+.PP
+\fBmanweb\fP's search starts in the "web directory" directory.
+That's either the value of the \fBwebdir\fP keyword in your
+\fBmanweb\fP configuration file, or the default \fB/usr/man/web\fP.
+.PP
+Your invocation parameters form a "topic chain."  Going from left to right,
+the first parameter is the main topic, the 2nd is a subtopic of the main
+topic, and so on.
+.PP
+Let's look at the simple case where you specify exactly one parameter --
+a main topic.  We'll call it \fImaintopic\fP and look at 4 ways
+\fBmanweb\fP might find it:
+
+
+.IP \(bu
+
+.sp
+If \fBmanweb\fP finds a file named \fImaintopic\fP\fB.html\fP
+       in the web directory, the URL \fBmanweb\fP passes to the
+       browser is just a \fBfile:\fP URL that specifies that .html
+       file.
+
+.IP \(bu
+
+.sp
+If there's no .html file, but there is a file named
+       \fImaintopic\fP\fB.url\fP, the contents of the first line of
+       that .url file is what \fBmanweb\fP passes to the browser.  It
+       doesn't interpret the contents at all.  If it's garbage, the
+       browser chokes on it.
+
+.IP \(bu
+
+.sp
+If there's neither a .html nor a .url file, but there is a
+       directory named \fImaintopic\fP, \fBmanweb\fP looks in the
+       directory for a file named \fIindex.html\fP.  If there is one,
+       \fBmanweb\fP passes a \fBfile:\fP URL specifying that
+       index.html file to the browser.  If there's no
+       \fIindex.html\fP, \fBmanweb\fP uses a \fBfile:\fP URL that
+       specifies the directory itself.
+
+.IP \(bu
+
+.sp
+If \fBmanweb\fP doesn't find documentation in any of the
+       above ways, it searches your executable search path (as defined
+       by your \fBPATH\fP environment variable) for a program named
+       \fImaintopic\fP.  If it finds one, it looks in the directory
+       that contains the program for a file named \fBdoc.url\fP.  If
+       it finds one, it appends \fImaintopic\fP\fB.html\fP to the
+       first line of the file and passes that to the browser.  Unless 
+       the first line does \fInot\fP end with a slash -- in that 
+       case, \fBmanweb\fP passes the first line of the file unmodified
+       to the browser.
+       
+.PP
+It gets a little more interesting when you have subtopics.  Looking
+at each of the 4 cases above:
+
+
+.IP \(bu
+
+       Where \fImaintopic\fP\fB.html\fP exists, subtopics are invalid.
+       You get a warning message and the subtopics are ignored.
+
+.IP \(bu
+
+       Where there's no .html file but \fImaintopic\fP\fB.url\fP exists,
+       \fBmanweb\fP appends the subtopic chain to the URL it gets from the
+       .url file as in the following example:  .url file contains
+       \fBhttp://acme.com/productxyz/\fP and subtopics are
+       \fBcreate\fP and
+       \fBdatabase\fP.  The URL \fBmanweb\fP passes to the browser is
+       \fBhttp://acme.com/productxyz/create/database.html\fP.
+.sp
+\fBmanweb\fP doesn't check that this kind of appendage makes
+       any sense for the URL in question, except that if the URL in the
+       .url file doesn't end with a slash (\fB/\fP), \fBmanweb\fP
+       issues a warning and doesn't append anything (ignores the subtopics).
+.IP \(bu
+
+       Where there's neither a .html file nor a .url file, but there's a
+       \fImaintopic\fP directory, \fBmanweb\fP recurses into that
+       directory and begins a whole new search using the first subtopic
+       as the main topic and the rest of the subtopics as subtopics of that.
+.IP \(bu
+
+       When there are subtopics, the \fBPATH\fP thing doesn't make sense,
+       so \fBmanweb\fP doesn't do it.
+
+
+If you give subtopics, the \fBPATH\fP thing described above for one
+topic doesn't apply.
+.PP
+If you give no parameters at all, \fBmanweb\fP generates a URL for the
+web directory itself as described above for subdirectories.
+.PP
+The above is simplified by the assumption of a single web
+directory.  In reality, the \fBwebdir\fP keyword in the configuration
+file can specify a chain of web directories.  \fBmanweb\fP searches
+each one in turn, doing all the kinds of searches in each web directory
+before moving on to the next one.
+
+.SS The Configuration File
+.PP
+The default location of the \fBmanweb\fP configuration file is
+\fB/etc/manweb.conf\fP.  But you can override this with the environment
+variable \fBMANWEB_CONF_FILE\fP, and override that with the
+\fB-config\fP invocation option.
+.PP
+Lines starting with "#" are comments and are ignored, as are blank lines.
+.PP
+All other lines have the format \fIkeyword\fP=\fIvalue\fP.  The
+keywords defined are:
+
+.TP
+webdir
+  
+       A colon-delimited sequence of directories to search for
+       documentation as described above.  If you
+       don't specify this, the default is \fB/usr/man/web\fP alone.
+.TP
+browser
+  
+       The file specification \fBmanweb\fP of the web browser \fBmanweb\fP
+       is to invoke
+       to display documentation (except when it uses \fBman\fP to display
+       a conventional man page).
+       If the file specification does not include a slash, \fBmanweb\fP
+       searches for the file in the PATH search path.
+.sp
+If you don't specify this, the default is the value of the
+       \fBBROWSER\fP environment variable, and if that is not set,
+       \fBlynx\fP.
+
+
+Example:
+.nf
+# Configuration file for Manweb
+
+webdir=/usr/share/manweb
+browser=netscape
+
+.fi
+ 
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/manweb.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/mattrib.1 b/upstream/mageia-cauldron/man1/mattrib.1
new file mode 100644
index 00000000..fa981095
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mattrib.1
@@ -0,0 +1,128 @@
+'\" t
+.TH mattrib 1 "21Mar23" mtools-4.0.43
+.SH Name
+mattrib - change MSDOS file attribute flags
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+\&\fR\&\f(CWMattrib\fR is used to change MS-DOS file attribute bits. It has the
+following syntax:
+.PP
+\&\fR\&\f(CWmattrib\fR [\fR\&\f(CW-a|+a\fR] [\fR\&\f(CW-h|+h\fR] [\fR\&\f(CW-r|+r\fR]
+[\fR\&\f(CW-s|+s\fR] [\fR\&\f(CW-/\fR]  [\fR\&\f(CW-p\fR] [\fR\&\f(CW-X\fR] \fImsdosfile\fR [ \fImsdosfiles\fR \&... ]
+.PP
+\&\fR\&\f(CWMattrib\fR adds attribute bits to an MS-DOS file (with the
+`\fR\&\f(CW+\fR' operator) or remove attribute bits (with the `\fR\&\f(CW-\fR'
+operator).
+.PP
+\&\fR\&\f(CWMattrib\fR supports the following attribute bits:
+.TP
+\&\fR\&\f(CWa\fR\ 
+Archive bit.  Used by some backup programs to indicate a new file.
+.TP
+\&\fR\&\f(CWr\fR\ 
+Read-only bit.  Used to indicate a read-only file.  Files with this bit
+set cannot be erased by \fR\&\f(CWDEL\fR nor modified.
+.TP
+\&\fR\&\f(CWs\fR\ 
+System bit.  Used by MS-DOS to indicate a operating system file.
+.TP
+\&\fR\&\f(CWh\fR\ 
+Hidden bit.  Used to make files hidden from \fR\&\f(CWDIR\fR.
+.PP
+\&\fR\&\f(CWMattrib\fR supports the following command line flags:
+.TP
+\&\fR\&\f(CW/\fR\ 
+Recursive.  Recursively list the attributes of the files in the subdirectories.
+.TP
+\&\fR\&\f(CWX\fR\ 
+Concise. Prints the attributes without any whitespace padding.  If
+neither the "/" option is given, nor the \fImsdosfile\fR contains a
+wildcard, and there is only one MS-DOS file parameter on the command
+line, only the attribute is printed, and not the filename.  This option
+is convenient for scripts
+.TP
+\&\fR\&\f(CWp\fR\ 
+Replay mode.  Outputs a series of \fR\&\f(CWmformat\fR commands that will
+reproduce the current situation, starting from a situation as left by
+untarring the MS-DOS file system.  Commands are only output for
+attribute settings that differ from the default (archive bit set for
+files, unset for directories).  This option is intended to be used in
+addition to tar. The \fR\&\f(CWreadonly\fR attribute is not taken into
+account, as tar can set that one itself.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mbadblocks.1 b/upstream/mageia-cauldron/man1/mbadblocks.1
new file mode 100644
index 00000000..c758ebc5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mbadblocks.1
@@ -0,0 +1,115 @@
+'\" t
+.TH mbadblocks 1 "21Mar23" mtools-4.0.43
+.SH Name
+mbadblocks - tests a floppy disk, and marks the bad blocks in the FAT
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmbadblocks\fR command is used to mark some clusters on an
+MS-DOS filesystem bad. It has the following syntax:
+.PP
+\&\fR\&\f(CWmbadblocks\fR [\fR\&\f(CW-s\fR \fIsectorlist\fR|\fR\&\f(CW-c\fR \fIclusterlist\fR|-w] \fIdrive\fR\fR\&\f(CW:\fR
+.PP
+If no command line flags are supplied, \fR\&\f(CWMbadblocks\fR scans an
+MS-DOS filesystem for bad blocks by simply trying to read them and
+flag them if read fails. All blocks that are unused are scanned, and
+if detected bad are marked as such in the FAT.
+.PP
+This command is intended to be used right after \fR\&\f(CWmformat\fR.  It is
+not intended to salvage data from bad disks.
+.PP
+.SH Command\ line\ options
+.TP
+\&\fR\&\f(CWc\ \fIfile\fR\&\f(CW\fR\ 
+Use a list of bad clusters, rather than scanning for bad clusters
+itself.
+.TP
+\&\fR\&\f(CWs\ \fIfile\fR\&\f(CW\fR\ 
+Use a list of bad sectors (counted from beginning of filesystem),
+rather than trying for bad clusters itself.
+.TP
+\&\fR\&\f(CWw\fR\ 
+Write a random pattern to each cluster, then read it back and flag
+cluster as bad if mismatch. Only free clusters are tested in such a
+way, so any file data is preserved.
+.PP
+.SH Bugs
+\&\fR\&\f(CWMbadblocks\fR should (but doesn't yet :-( ) also try to salvage bad
+blocks which are in use by reading them repeatedly, and then mark them
+bad.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mcat.1 b/upstream/mageia-cauldron/man1/mcat.1
new file mode 100644
index 00000000..6071cac6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mcat.1
@@ -0,0 +1,100 @@
+'\" t
+.TH mcat 1 "21Mar23" mtools-4.0.43
+.SH Name
+mcat - dump raw disk image
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmcat\fR command is used to copy an entire disk image from or
+to the floppy device. It uses the following syntax:
+.PP
+\&\fR\&\f(CWmcat\fR [\fR\&\f(CW-w\fR] \fIdrive\fR\fR\&\f(CW:\fR
+.PP
+\&\fR\&\f(CWMcat\fR performs the same task as the Unix \fR\&\f(CWcat\fR command. It
+is included into the mtools package, since \fR\&\f(CWcat\fR cannot access
+remote floppy devices offered by the mtools floppy daemon.
+Now it is possible to create boot floppies remotely.
+.PP
+The default operation is reading. The output is written to stdout.
+.PP
+If the \fR\&\f(CW-w\fR option is specified, mcat reads a disk-image from 
+stdin and writes it to the given device. 
+\&\fBUse this carefully!\fR Because of the low-level nature of this 
+command, it will happily destroy any data written before on the
+disk without warning!
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mcd.1 b/upstream/mageia-cauldron/man1/mcd.1
new file mode 100644
index 00000000..4dc28b26
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mcd.1
@@ -0,0 +1,111 @@
+'\" t
+.TH mcd 1 "21Mar23" mtools-4.0.43
+.SH Name
+mcd - change MSDOS directory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmcd\fR command is used to change the mtools working directory
+on the MS-DOS disk. It uses the following syntax:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+\&\fR\&\f(CWmcd [\fImsdosdirectory\fR\&\f(CW]
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+Without arguments, \fR\&\f(CWmcd\fR reports the current device and working
+directory.  Otherwise, \fR\&\f(CWmcd\fR changes the current device and current
+working directory relative to an MS-DOS file system.
+.PP
+The environmental variable \fR\&\f(CWMCWD\fR may be used to locate the file
+where the device and current working directory information is stored.
+The default is \fR\&\f(CW\(if$HOME/.mcwd\(is\fR.  Information in this file is ignored
+if the file is more than 6 hours old.
+.PP
+\&\fR\&\f(CWMcd\fR returns 0 on success or 1 on failure.
+.PP
+Unlike MS-DOS versions of \fR\&\f(CWCD\fR, \fR\&\f(CWmcd\fR can be used to change to
+another device. It may be wise to remove old \fR\&\f(CW\(if.mcwd\(is\fR files at logout.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mcopy.1 b/upstream/mageia-cauldron/man1/mcopy.1
new file mode 100644
index 00000000..65b7d962
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mcopy.1
@@ -0,0 +1,178 @@
+'\" t
+.TH mcopy 1 "21Mar23" mtools-4.0.43
+.SH Name
+mcopy - copy MSDOS files to/from Unix
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmcopy\fR command is used to copy MS-DOS files to and from
+Unix. It uses the following syntax:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+\&\fR\&\f(CWmcopy [\fR\&\f(CW-bspanvmQT] [\fR\&\f(CW-D \fIclash_option\fR\&\f(CW] \fIsourcefile\fR\&\f(CW \fItargetfile\fR\&\f(CW
+\&\fR\&\f(CWmcopy [\fR\&\f(CW-bspanvmQT] [\fR\&\f(CW-D \fIclash_option\fR\&\f(CW] \fIsourcefile\fR\&\f(CW [ \fIsourcefiles\fR\&\f(CW\&... ] \fItargetdirectory\fR\&\f(CW
+\&\fR\&\f(CWmcopy [\fR\&\f(CW-tnvm] \fIMSDOSsourcefile\fR\&\f(CW
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+\&\fR\&\f(CWMcopy\fR copies the specified file to the named file, or copies
+multiple files to the named directory.  The source and target can be
+either MS-DOS or Unix files.
+.PP
+The use of a drive letter designation on the MS-DOS files, 'a:' for
+example, determines the direction of the transfer.  A missing drive
+designation implies a Unix file whose path starts in the current
+directory.  If a source drive letter is specified with no attached file
+name (e.g. \fR\&\f(CWmcopy a: .\fR), all files are copied from that drive.
+.PP
+If only a single, MS-DOS source parameter is provided (e.g. "mcopy
+a:foo.exe"), an implied destination of the current directory
+(`\fR\&\f(CW.\fR') is assumed.
+.PP
+A filename of `\fR\&\f(CW-\fR' means standard input or standard output, depending
+on its position on the command line.
+.PP
+\&\fR\&\f(CWMcopy\fR accepts the following command line options:
+.TP
+\&\fR\&\f(CWt\fR\ 
+Text file transfer.  Mcopy translates incoming carriage return/line
+feeds to line feeds when copying from MS-DOS to Unix, and vice-versa when
+copying from Unix to MS-DOS.
+.TP
+\&\fR\&\f(CWb\fR\ 
+Batch mode. Optimized for huge recursive copies, but less secure if a
+crash happens during the copy.
+.TP
+\&\fR\&\f(CWs\fR\ 
+Recursive copy.  Also copies directories and their contents
+.TP
+\&\fR\&\f(CWp\fR\ 
+Preserves the attributes of the copied files
+.TP
+\&\fR\&\f(CWQ\fR\ 
+When mcopying multiple files, quits as soon as one copy fails (for
+example due to lacking storage space on the target disk)
+.TP
+\&\fR\&\f(CWa\fR\ 
+Text (ASCII) file transfer.  \fR\&\f(CWASCII\fR translates incoming carriage
+return/line feeds to line feeds.
+.TP
+\&\fR\&\f(CWT\fR\ 
+Text (ASCII) file transfer with character set conversion.  Differs from
+\&\fR\&\f(CW-a\fR in the \fR\&\f(CWASCII\fR also translates incoming PC-8 characters
+to ISO-8859-1 equivalents as far as possible.  When reading DOS files,
+untranslatable characters are replaced by '\fR\&\f(CW#\fR'; when writing DOS files,
+untranslatable characters are replaced by '\fR\&\f(CW.\fR'.
+.TP
+\&\fR\&\f(CWn\fR\ 
+No confirmation when overwriting Unix files.  \fR\&\f(CWASCII\fR doesn't
+warn the user when overwriting an existing Unix file. If the target
+file already exists, and the \fR\&\f(CW-n\fR option is not in effect,
+\&\fR\&\f(CWmcopy\fR asks whether to overwrite the file or to rename the new
+file (see \(ifname clashes\(is) for details).  In order to switch off
+confirmation for DOS files, use \fR\&\f(CW-o\fR.
+.TP
+\&\fR\&\f(CWm\fR\ 
+Preserve the file modification time.
+.TP
+\&\fR\&\f(CWv\fR\ 
+Verbose. Displays the name of each file as it is copied.
+.PP
+.SH Bugs
+Unlike MS-DOS, the '+' operator (append) from MS-DOS is not
+supported. However, you may use \fR\&\f(CWmtype\fR to produce the same effect:
+ 
+.nf
+.ft 3
+.in +0.3i
+mtype a:file1 a:file2 a:file3 >unixfile
+mtype a:file1 a:file2 a:file3 | mcopy - a:msdosfile
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/md5sum.1 b/upstream/mageia-cauldron/man1/md5sum.1
new file mode 100644
index 00000000..282a88d6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/md5sum.1
@@ -0,0 +1,83 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MD5SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+md5sum \- compute and check MD5 message digest
+.SH SYNOPSIS
+.B md5sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check MD5 (128\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in RFC 1321.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH BUGS
+Do not use the MD5 algorithm for security related purposes.
+Instead, use an SHA\-2 algorithm, implemented in the programs
+\fBsha224sum\fP(1), \fBsha256sum\fP(1), \fBsha384sum\fP(1), \fBsha512sum\fP(1),
+or the BLAKE2 algorithm, implemented in \fBb2sum\fP(1)
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/md5sum>
+.br
+or available locally via: info \(aq(coreutils) md5sum invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mdatopbm.1 b/upstream/mageia-cauldron/man1/mdatopbm.1
new file mode 100644
index 00000000..8bc7b7e9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mdatopbm.1
@@ -0,0 +1,82 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Mdatopbm User Manual" 0 "03 December 2003" "netpbm documentation"
+
+.SH NAME
+
+mdatopbm - convert a Microdesign .mda or .mdp file into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmdatopbm\fP
+[\fB-d\fP]
+[\fB-i\fP]
+[\fB--\fP]
+[\fImdafile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBmdatopbm\fP reads a MicroDesign file as input and Produces a
+PBM image as output.
+.PP
+If you don't specify \fImdafile\fP, \fBmdatopbm\fP takes its input
+from Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBmdatopbm\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-d\fP
+Double the height of the output file, to compensate for the aspect
+ratio used in MicroDesign files.
+
+.TP
+\fB-i\fP
+Invert the colors used.
+
+.TP
+\fB--\fP
+End of options (use this if the filename starts with "-")
+
+
+.PP
+The program also accepts option \fB-a\fP for historical reasons, for
+  the same meaning as the Netpbm common option \fB-plain\fP.
+  
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtomda" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1999 John Elliott <\fIjce@seasip.demon.co.uk\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/mdatopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/mdel.1 b/upstream/mageia-cauldron/man1/mdel.1
new file mode 100644
index 00000000..b22b59f1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mdel.1
@@ -0,0 +1,96 @@
+'\" t
+.TH mdel 1 "21Mar23" mtools-4.0.43
+.SH Name
+mdel - delete an MSDOS file
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmdel\fR command is used to delete an MS-DOS file. Its syntax
+is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmdel\fR [\fR\&\f(CW-v\fR] \fImsdosfile\fR [ \fImsdosfiles\fR \&...  ]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMdel\fR deletes files on an MS-DOS file system.
+.PP
+\&\fR\&\f(CWMdel\fR asks for verification prior to removing a read-only file.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mdeltree.1 b/upstream/mageia-cauldron/man1/mdeltree.1
new file mode 100644
index 00000000..0a0c54fb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mdeltree.1
@@ -0,0 +1,96 @@
+'\" t
+.TH mdeltree 1 "21Mar23" mtools-4.0.43
+.SH Name
+mdeltree - recursively delete an MSDOS directory and its contents
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmdeltree\fR command is used to delete an MS-DOS file. Its syntax
+is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmdeltree\fR [\fR\&\f(CW-v\fR] \fImsdosdirectory\fR [\fImsdosdirectories\fR\&...]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMdeltree\fR removes a directory and all the files and subdirectories
+it contains from an MS-DOS file system. An error occurs if the directory
+to be removed does not exist.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mdir.1 b/upstream/mageia-cauldron/man1/mdir.1
new file mode 100644
index 00000000..e00daf11
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mdir.1
@@ -0,0 +1,118 @@
+'\" t
+.TH mdir 1 "21Mar23" mtools-4.0.43
+.SH Name
+mdir - display an MSDOS directory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmdir\fR command is used to display an MS-DOS directory. Its
+syntax is:
+.PP
+\&\fR\&\f(CWmdir\fR [\fR\&\f(CW-/\fR] [\fR\&\f(CW-f\fR] [\fR\&\f(CW-w\fR] [\fR\&\f(CW-a\fR] [\fR\&\f(CW-b\fR] \fImsdosfile\fR [ \fImsdosfiles\fR\&...] 
+.PP
+\&\fR\&\f(CWMdir\fR
+displays the contents of MS-DOS directories, or the entries for some
+MS-DOS files.
+.PP
+\&\fR\&\f(CWMdir\fR supports the following command line options:
+.TP
+\&\fR\&\f(CW/\fR\ 
+Recursive output, just like MS-DOS' \fR\&\f(CW-s\fR option
+.TP
+\&\fR\&\f(CWw\fR\ 
+Wide output.  With this option, \fR\&\f(CWmdir\fR prints the filenames across
+the page without displaying the file size or creation date.
+.TP
+\&\fR\&\f(CWa\fR\ 
+Also list hidden files.
+.TP
+\&\fR\&\f(CWf\fR\ 
+Fast.  Do not try to find out free space.  On larger disks, finding out
+the amount of free space takes up some non trivial amount of time, as
+the whole FAT must be read in and scanned.  The \fR\&\f(CW-f\fR flag bypasses
+this step.  This flag is not needed on FAT32 file systems, which store
+the size explicitly.
+.TP
+\&\fR\&\f(CWb\fR\ 
+Concise listing. Lists each directory name or filename, one per line
+(including the filename extension). This switch displays no heading
+information and no summary. Only a newline separated list of pathnames
+is displayed.
+.PP
+An error occurs if a component of the path is not a directory.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mdu.1 b/upstream/mageia-cauldron/man1/mdu.1
new file mode 100644
index 00000000..6b1e3201
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mdu.1
@@ -0,0 +1,95 @@
+'\" t
+.TH mdu 1 "21Mar23" mtools-4.0.43
+.SH Name
+mdu - display the amount of space occupied by an MSDOS directory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+\&\fR\&\f(CWMdu\fR is used to list the space occupied by a directory, its
+subdirectories and its files. It is similar to the \fR\&\f(CWdu\fR command on
+Unix.  The unit used are clusters.  Use the minfo command to find out
+the cluster size.
+.PP
+\&\fR\&\f(CWmdu\fR [\fR\&\f(CW-a\fR] [ \fImsdosfiles\fR \&... ]
+.TP
+\&\fR\&\f(CWa\fR\ 
+All files.  List also the space occupied for individual files.
+.TP
+\&\fR\&\f(CWs\fR\ 
+Only list the total space, don't give details for each subdirectory.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/memusage.1 b/upstream/mageia-cauldron/man1/memusage.1
new file mode 100644
index 00000000..cc21b83e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/memusage.1
@@ -0,0 +1,262 @@
+.\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
+.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.TH memusage 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+memusage \- profile memory usage of a program
+.SH SYNOPSIS
+.nf
+.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..."
+.fi
+.SH DESCRIPTION
+.B memusage
+is a bash script which profiles memory usage of the program,
+.IR program .
+It preloads the
+.B libmemusage.so
+library into the caller's environment (via the
+.B LD_PRELOAD
+environment variable; see
+.BR ld.so (8)).
+The
+.B libmemusage.so
+library traces memory allocation by intercepting calls to
+.BR malloc (3),
+.BR calloc (3),
+.BR free (3),
+and
+.BR realloc (3);
+optionally, calls to
+.BR mmap (2),
+.BR mremap (2),
+and
+.BR munmap (2)
+can also be intercepted.
+.P
+.B memusage
+can output the collected data in textual form, or it can use
+.BR memusagestat (1)
+(see the
+.B \-p
+option,  below)
+to create a PNG file containing graphical representation
+of the collected data.
+.SS Memory usage summary
+The "Memory usage summary" line output by
+.B memusage
+contains three fields:
+.RS 4
+.TP
+\fBheap total\fR
+Sum of \fIsize\fR arguments of all
+.BR malloc (3)
+calls,
+products of arguments (\fInmemb\fR*\fIsize\fR) of all
+.BR calloc (3)
+calls,
+and sum of \fIlength\fR arguments of all
+.BR mmap (2)
+calls.
+In the case of
+.BR realloc (3)
+and
+.BR mremap (2),
+if the new size of an allocation is larger than the previous size,
+the sum of all such differences (new size minus old size) is added.
+.TP
+.B "heap peak"
+Maximum of all \fIsize\fR arguments of
+.BR malloc (3),
+all products of \fInmemb\fR*\fIsize\fR of
+.BR calloc (3),
+all \fIsize\fR arguments of
+.BR realloc (3),
+.I length
+arguments of
+.BR mmap (2),
+and
+\fInew_size\fR arguments of
+.BR mremap (2).
+.TP
+.B "stack peak"
+Before the first call to any monitored function,
+the stack pointer address (base stack pointer) is saved.
+After each function call, the actual stack pointer address is read and
+the difference from the base stack pointer computed.
+The maximum of these differences is then the stack peak.
+.RE
+.P
+Immediately following this summary line, a table shows the number calls,
+total memory allocated or deallocated,
+and number of failed calls for each intercepted function.
+For
+.BR realloc (3)
+and
+.BR mremap (2),
+the additional field "nomove" shows reallocations that
+changed the address of a block,
+and the additional "dec" field shows reallocations that
+decreased the size of the block.
+For
+.BR realloc (3),
+the additional field "free" shows reallocations that
+caused a block to be freed (i.e., the reallocated size was 0).
+.P
+The "realloc/total memory" of the table output by
+.B memusage
+does not reflect cases where
+.BR realloc (3)
+is used to reallocate a block of memory
+to have a smaller size than previously.
+This can cause sum of all "total memory" cells (excluding "free")
+to be larger than the "free/total memory" cell.
+.SS Histogram for block sizes
+The "Histogram for block sizes" provides a breakdown of memory
+allocations into various bucket sizes.
+.SH OPTIONS
+.TP
+.BI \-n\  name \fR,\ \fB\-\-progname= name
+Name of the program file to profile.
+.TP
+.BI \-p\  file \fR,\ \fB\-\-png= file
+Generate PNG graphic and store it in
+.IR file .
+.TP
+.BI \-d\  file \fR,\ \fB\-\-data= file
+Generate binary data file and store it in
+.IR file .
+.TP
+.B \-u\fR,\ \fB\-\-unbuffered
+Do not buffer output.
+.TP
+.BI \-b\  size \fR,\ \fB\-\-buffer= size
+Collect
+.I size
+entries before writing them out.
+.TP
+.B \-\-no\-timer
+Disable timer-based
+.RB ( SIGPROF )
+sampling of stack pointer value.
+.TP
+.B \-m\fR,\ \fB\-\-mmap
+Also trace
+.BR mmap (2),
+.BR mremap (2),
+and
+.BR munmap (2).
+.TP
+.B \-?\fR,\ \fB\-\-help
+Print help and exit.
+.TP
+.B \-\-usage
+Print a short usage message and exit.
+.TP
+.B \-V\fR,\ \fB\-\-version
+Print version information and exit.
+.TP
+The following options apply only when generating graphical output:
+.TP
+.B \-t\fR,\ \fB\-\-time\-based
+Use time (rather than number of function calls) as the scale for the X axis.
+.TP
+.B \-T\fR,\ \fB\-\-total
+Also draw a graph of total memory use.
+.TP
+.BI \fB\-\-title= name
+Use
+.I name
+as the title of the graph.
+.TP
+.BI \-x\  size \fR,\ \fB\-\-x\-size= size
+Make the graph
+.I size
+pixels wide.
+.TP
+.BI \-y\  size \fR,\ \fB\-\-y\-size= size
+Make the graph
+.I size
+pixels high.
+.SH EXIT STATUS
+The exit status of
+.B memusage
+is equal to the exit status of the profiled program.
+.SH BUGS
+To report bugs, see
+.UR http://www.gnu.org/software/libc/bugs.html
+.UE
+.SH EXAMPLES
+Below is a simple program that reallocates a block of
+memory in cycles that rise to a peak before then cyclically
+reallocating the memory in smaller blocks that return to zero.
+After compiling the program and running the following commands,
+a graph of the memory usage of the program can be found in the file
+.IR memusage.png :
+.P
+.in +4n
+.EX
+$ \fBmemusage \-\-data=memusage.dat ./a.out\fP
+\&...
+Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
+        total calls  total memory  failed calls
+ malloc|         1           400             0
+realloc|        40         44800             0  (nomove:40, dec:19, free:0)
+ calloc|         0             0             0
+   free|         1           440
+Histogram for block sizes:
+  192\-207             1   2% ================
+\&...
+ 2192\-2207            1   2% ================
+ 2240\-2255            2   4% =================================
+ 2832\-2847            2   4% =================================
+ 3440\-3455            2   4% =================================
+ 4032\-4047            2   4% =================================
+ 4640\-4655            2   4% =================================
+ 5232\-5247            2   4% =================================
+ 5840\-5855            2   4% =================================
+ 6432\-6447            1   2% ================
+$ \fBmemusagestat memusage.dat memusage.png\fP
+.EE
+.in
+.SS Program source
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+\&
+#define CYCLES 20
+\&
+int
+main(int argc, char *argv[])
+{
+    int i, j;
+    size_t size;
+    int *p;
+\&
+    size = sizeof(*p) * 100;
+    printf("malloc: %zu\en", size);
+    p = malloc(size);
+\&
+    for (i = 0; i < CYCLES; i++) {
+        if (i < CYCLES / 2)
+            j = i;
+        else
+            j\-\-;
+\&
+        size = sizeof(*p) * (j * 50 + 110);
+        printf("realloc: %zu\en", size);
+        p = realloc(p, size);
+\&
+        size = sizeof(*p) * ((j + 1) * 150 + 110);
+        printf("realloc: %zu\en", size);
+        p = realloc(p, size);
+    }
+\&
+    free(p);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.SH SEE ALSO
+.BR memusagestat (1),
+.BR mtrace (1),
+.BR ld.so (8)
diff --git a/upstream/mageia-cauldron/man1/memusagestat.1 b/upstream/mageia-cauldron/man1/memusagestat.1
new file mode 100644
index 00000000..09d23659
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/memusagestat.1
@@ -0,0 +1,73 @@
+.\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.TH memusagestat 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+memusagestat \- generate graphic from memory profiling data
+.SH SYNOPSIS
+.nf
+.BR memusagestat " [\fIoption\fR]... \fIdatafile\fR [\fIoutfile\fR]"
+.fi
+.SH DESCRIPTION
+.B memusagestat
+creates a PNG file containing a graphical representation of the
+memory profiling data in the file
+.IR datafile ;
+that file is generated via the
+.I \-d
+(or
+.IR \-\-data )
+option of
+.BR memusage (1).
+.P
+The red line in the graph shows the heap usage (allocated memory)
+and the green line shows the stack usage.
+The x-scale is either the number of memory-handling function calls or
+(if the
+.I \-t
+option is specified)
+time.
+.SH OPTIONS
+.TP
+.BI \-o\  file \fR,\ \fB\-\-output= file
+Name of the output file.
+.TP
+.BI \-s\  string \fR,\ \fB\-\-string= string
+Use
+.I string
+as the title inside the output graph.
+.TP
+.B \-t\fR,\ \fB\-\-time
+Use time (rather than number of function calls) as the scale for the X axis.
+.TP
+.B \-T\fR,\ \fB\-\-total
+Also draw a graph of total memory consumption.
+.TP
+.BI \-x\  size \fR,\ \fB\-\-x\-size= size
+Make the output graph
+.I size
+pixels wide.
+.TP
+.BI \-y\  size \fR,\ \fB\-\-y\-size= size
+Make the output graph
+.I size
+pixels high.
+.TP
+.B \-?\fR,\ \fB\-\-help
+Print a help message and exit.
+.TP
+.B \-\-usage
+Print a short usage message and exit.
+.TP
+.B \-V\fR,\ \fB\-\-version
+Print version information and exit.
+.SH BUGS
+To report bugs, see
+.UR http://www.gnu.org/software/libc/bugs.html
+.UE
+.SH EXAMPLES
+See
+.BR memusage (1).
+.SH SEE ALSO
+.BR memusage (1),
+.BR mtrace (1)
diff --git a/upstream/mageia-cauldron/man1/merge.1 b/upstream/mageia-cauldron/man1/merge.1
new file mode 100644
index 00000000..b0e89ef6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/merge.1
@@ -0,0 +1,158 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.TH MERGE 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+merge \- three-way file merge
+.SH SYNOPSIS
+.B merge
+[
+.I "options"
+]
+.I "file1 file2 file3"
+.SH DESCRIPTION
+.B merge
+incorporates all changes that lead from
+.I file2
+to
+.I file3
+into
+.IR file1 .
+The result ordinarily goes into
+.IR file1 .
+.B merge
+is useful for combining separate changes to an original.  Suppose
+.I file2
+is the original, and both
+.I file1
+and
+.I file3
+are modifications of
+.IR file2 .
+Then
+.B merge
+combines both changes.
+.PP
+A conflict occurs if both
+.I file1
+and
+.I file3
+have changes in a common segment of lines.
+If a conflict is found,
+.B merge
+normally outputs a warning and brackets the conflict with
+.B <<<<<<<
+and
+.B >>>>>>>
+lines.
+A typical conflict will look like this:
+.LP
+.RS
+.nf
+.BI <<<<<<< " file A"
+.I "lines in file A"
+.B "======="
+.I "lines in file B"
+.BI >>>>>>> " file B"
+.RE
+.fi
+.LP
+If there are conflicts, the user should edit the result and delete one of the
+alternatives.
+.SH OPTIONS
+.TP
+.B \-A
+Output conflicts using the
+.B \-A
+style of
+.BR diff3 (1),
+if supported by
+.BR diff3 .
+This merges all changes leading from
+.I file2
+to
+.I file3
+into
+.IR file1 ,
+and generates the most verbose output.
+.TP
+\f3\-E\fP, \f3\-e\fP
+These options specify conflict styles that generate less information
+than
+.BR \-A .
+See
+.BR diff3 (1)
+for details.
+The default is
+.BR \-E .
+With
+.BR \-e ,
+.B merge
+does not warn about conflicts.
+.TP
+.BI \-L " label"
+This option may be given up to three times, and specifies labels
+to be used in place of the corresponding file names in conflict reports.
+That is,
+.B "merge\ \-L\ x\ \-L\ y\ \-L\ z\ a\ b\ c"
+generates output that looks like it came from files
+.BR x ,
+.B y
+and
+.B z
+instead of from files
+.BR a ,
+.B b
+and
+.BR c .
+.TP
+.BI \-p
+Send results to standard output instead of overwriting
+.IR file1 .
+.TP
+.BI \-q
+Quiet; do not warn about conflicts.
+.TP
+.BI \-V
+Print \*r's version number.
+.SH DIAGNOSTICS
+Exit status is 0 for no conflicts, 1 for some conflicts, 2 for trouble.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR diff3 (1),
+.BR diff (1),
+.BR rcsmerge (1),
+.BR co (1).
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
+.SH BUGS
+It normally does not make sense to merge binary files as if they were text, but
+.B merge
+tries to do it anyway.
+.br
diff --git a/upstream/mageia-cauldron/man1/mev.1 b/upstream/mageia-cauldron/man1/mev.1
new file mode 100644
index 00000000..78429ebd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mev.1
@@ -0,0 +1,133 @@
+.TH MEV 1 "February 1995"
+.UC 4
+.SH NAME
+mev \- a program to report mouse events
+.SH SYNOPSIS
+.B mev
+[
+.I options
+]
+.br
+.SH DESCRIPTION
+The `mev' program is part of the gpm package.
+The information below is extracted from the texinfo file, which is the
+preferred source of information.
+
+.LP
+The mev program is modeled after xev. It prints to stdout the
+mouse console events it gets.
+
+.LP
+mev's default behaviour is to get anything, but command line switches
+can be used to set the various fields in the Gpm_Connect structure, in
+order to customize the program's behaviour. I'm using mev to
+handle mouse events to Emacs.
+
+.LP
+Command line switches for mev are the following:
+.TP
+\-C \fBnumber\fP
+Select a virtual console to get events from.
+This is intended to be used for debugging.
+.TP
+\-d \fBnumber\fP
+Choose a default mask. By default the server gets
+any events not belonging to the event mask. The mask can be
+provided either as a
+decimal number, or as a symbolic string.
+.TP
+\-e \fBnumber\fP
+Choose the event mask. By default any event
+is received. The mask can be provided either as a
+decimal number, or as a symbolic string.
+.TP
+\-E
+Enter emacs mode. In emacs mode events are reported as
+lisp forms rather than numbers. This is the format used by the
+t-mouse package within emacs.
+.TP
+\-f
+Fit events inside the screen before reporting them. This options
+re-fits drag events, which are allowed to exit the screen border,
+
+.TP
+\-i
+Interactive. Accepts input from stdin to change connection
+parameters.
+.TP
+\-m \fBnumber\fP
+Choose the minimum modifier mask. Any event with
+fewer modifiers will not be reported to mev. It defaults to 0.
+The mask must be provided either as a
+decimal number, or as a symbolic string.
+.TP
+\-M \fBnumber\fP
+Choose the maximum modifier mask. Any event with
+more modifier than specified will not be reported to mev.
+It defaults to \~~0, i.e. all events are received.
+The mask must be provided either as a
+decimal number, or as a symbolic string.
+.TP
+\-p
+Requests to draw the pointer during drags. This option is used
+by emacs to avoid invoking ioctl() from lisp code.
+
+.LP
+When the arguments are not decimal integers, they are considered lists
+of alphanumeric characters, separated by a single non-alphanumeric
+character. I use the comma (,), but any will do.
+
+.LP
+Allowed names for events are move, drag, down or
+press, up or release, motion (which is both
+move and drag), and hard.
+
+.LP
+Allowed names for modifiers are shift, leftAlt,
+rightAlt, anyAlt (one or the other), control.
+
+.LP
+When the \-i switch is specified, mev looks at its standard input as
+command lines rather than events. The input lines are parsed, and the
+commands push and pop are recognized.
+
+.LP
+The push command, then, accepts the options \-d, \-e, \-m
+and \-M, with the same meaning described above. Unspecified options
+retain the previous value and the resulting masks are used to reopen
+the connection with the server. pop is used to pop the connection
+stack. If an empty stack is popped the program exits.
+
+.LP
+Other commands recognized are info, used to return the stack
+depth; quit to prematurely terminate the program; and
+snapshot to get some configuration information from the server.
+
+.LP
+.SH BUGS
+Beginning with release 1.16, \fBmev\fP no longer works under xterm.
+Please use the \fBrmev\fP program (provided in the \fBsample\fP
+directory) to watch gpm events under xterm or rxvt.  \fBrmev\fP also
+displays keyboard events besides mouse events.
+
+.LP
+.SH AUTHOR
+Alessandro Rubini <rubini@linux.it>
+.br
+Ian Zimmerman <itz@speakeasy.org>
+
+.LP
+.SH FILES
+.nf
+/dev/gpmctl The socket used to connect to gpm.
+.fi
+
+.LP
+.SH SEE ALSO
+.nf
+\fB gpm(8) \fP       The mouse server
+\fB gpm-types(7) \fP Description of mouse types supported by gpm.
+
+.fi
+The info file about `gpm', which gives more complete information and
+explains how to write a gpm client.
diff --git a/upstream/mageia-cauldron/man1/mformat.1 b/upstream/mageia-cauldron/man1/mformat.1
new file mode 100644
index 00000000..1d3d7e78
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mformat.1
@@ -0,0 +1,339 @@
+'\" t
+.TH mformat 1 "21Mar23" mtools-4.0.43
+.SH Name
+mformat - add an MSDOS filesystem to a low-level formatted floppy disk
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmformat\fR command is used to add an MS-DOS file system to a
+low-level formatted diskette. Its syntax is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmformat\fR [\fR\&\f(CW-t\fR \fIcylinders\fR|\fR\&\f(CW-T\fR \fItot_sectors\fR] [\fR\&\f(CW-h\fR \fIheads\fR] [\fR\&\f(CW-s\fR \fIsectors\fR]
+  [\fR\&\f(CW-f\fR \fIsize\fR] [\fR\&\f(CW-1\fR] [\fR\&\f(CW-4\fR] [\fR\&\f(CW-8\fR]
+  [\fR\&\f(CW-v\fR \fIvolume_label\fR]
+  [\fR\&\f(CW-F\fR] [\fR\&\f(CW-S\fR \fIsizecode\fR]
+  [\fR\&\f(CW-M\fR \fIsoftware_sector_size\fR]
+  [\fR\&\f(CW-N\fR \fIserial_number\fR] [\fR\&\f(CW-a\fR]
+  [\fR\&\f(CW-C\fR] [\fR\&\f(CW-H\fR \fIhidden_sectors\fR] [\fR\&\f(CW-I\fR \fIfsVersion\fR]
+  [\fR\&\f(CW-r\fR \fIroot_sectors\fR] [\fR\&\f(CW-L\fR \fIfat_len\fR] 
+  [\fR\&\f(CW-B\fR \fIboot_sector\fR] [\fR\&\f(CW-k\fR]
+  [\fR\&\f(CW-m\fR \fImedia_descriptor\fR]
+  [\fR\&\f(CW-K\fR \fIbackup_boot\fR]
+  [\fR\&\f(CW-R\fR \fInb_reserved_sectors\fR]
+  [\fR\&\f(CW-c\fR \fIclusters_per_sector\fR]
+  [\fR\&\f(CW-d\fR \fIfat_copies\fR]
+  [\fR\&\f(CW-X\fR] [\fR\&\f(CW-2\fR \fIsectors_on_track_0\fR] [\fR\&\f(CW-3\fR]
+  [\fR\&\f(CW-0\fR \fIrate_on_track_0\fR] [\fR\&\f(CW-A\fR \fIrate_on_other_tracks\fR]
+  \fIdrive:\fR
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMformat\fR adds a minimal MS-DOS file system (boot sector, FAT, and
+root directory) to a diskette that has already been formatted by a Unix
+low-level format.
+.PP
+The following options are supported: (The S, 2, 1 and M options may not
+exist if this copy of mtools has been compiled without the USE_2M
+option)
+.PP
+The following options are the same as for MS-DOS's format command:
+.PP
+.SH Options
+.TP
+\&\fR\&\f(CWv\fR\ 
+Specifies the volume label. A volume label identifies the disk and can
+be a maximum of 11 characters. If you omit the -v switch, mformat will
+assign no label to the disk.
+.TP
+\&\fR\&\f(CWf\fR\ 
+Specifies the size of the DOS file system to format. Only a certain
+number of predefined sizes are supported by this flag; for others use
+the -h/-t/-s flags. The following sizes are supported:
+.RS
+.TP
+160\ 
+160K, single-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD)
+.TP
+180\ 
+160K, single-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD)
+.TP
+320\ 
+320K, double-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD)
+.TP
+360\ 
+360K, double-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD)
+.TP
+720\ 
+720K, double-sided, 9 sectors per track, 80 cylinders (for 3 1/2 DD)
+.TP
+1200\ 
+1200K, double-sided, 15 sectors per track, 80 cylinders (for 5 1/4 HD)
+.TP
+1440\ 
+1440K, double-sided, 18 sectors per track, 80 cylinders (for 3 1/2 HD)
+.TP
+2880\ 
+2880K, double-sided, 36 sectors per track, 80 cylinders (for 3 1/2 ED)
+.RE
+.TP
+\&\fR\&\f(CWt\fR\ 
+Specifies the number of tracks on the disk.
+.TP
+\&\fR\&\f(CWT\fR\ 
+Specifies the number of total sectors on the disk. Only one of these 2
+options may be specified (tracks or total sectors)
+.TP
+\&\fR\&\f(CWh\fR\ 
+The number of heads (sides).
+.TP
+\&\fR\&\f(CWs\fR\ 
+Specifies the number of sectors per track. If the 2m option is given,
+number of 512-byte sector equivalents on generic tracks (i.e. not head 0
+track 0).  If the 2m option is not given, number of physical sectors per
+track (which may be bigger than 512 bytes).
+.TP
+\&\fR\&\f(CW1\fR\ 
+Formats a single side (equivalent to -h 1)
+.TP
+\&\fR\&\f(CW4\fR\ 
+Formats a 360K double-sided disk (equivalent to -f 360). When used
+together with -the 1 switch, this switch formats a 180K disk
+.TP
+\&\fR\&\f(CW8\fR\ 
+Formats a disk with 8 sectors per track.
+.PP
+MS-DOS format's \fR\&\f(CWq\fR, \fR\&\f(CWu\fR and \fR\&\f(CWb\fR options are not
+supported, and \fR\&\f(CWs\fR has a different meaning.
+.PP
+The following options are specific to mtools:
+.IP
+.TP
+\&\fR\&\f(CWF\fR\ 
+Format the partition as FAT32.
+.TP
+\&\fR\&\f(CWS\fR\ 
+The size code. The size of the sector is 2 ^ (sizecode + 7).
+.TP
+\&\fR\&\f(CWX\fR\ 
+formats the disk as an XDF disk. See section XDF, for more details. The disk
+has first to be low-level formatted using the xdfcopy utility included
+in the fdutils package. XDF disks are used for instance for OS/2 install
+disks.
+.TP
+\&\fR\&\f(CW2\fR\ 
+2m format. The parameter to this option describes the number of
+sectors on track 0, head 0. This option is recommended for sectors
+bigger than normal.
+.TP
+\&\fR\&\f(CW3\fR\ 
+don't use a 2m format, even if the current geometry of the disk is a 2m 
+geometry.
+.TP
+\&\fR\&\f(CW0\fR\ 
+Data transfer rate on track 0
+.TP
+\&\fR\&\f(CWA\fR\ 
+Data transfer rate on tracks other than 0
+.TP
+\&\fR\&\f(CWM\fR\ 
+software sector size. This parameter describes the sector size in bytes used
+by the MS-DOS file system. By default it is the physical sector size.
+.TP
+\&\fR\&\f(CWN\fR\ 
+Uses the requested serial number, instead of generating one
+automatically
+.TP
+\&\fR\&\f(CWa\fR\ 
+If this option is given, an Atari style serial number is generated.
+Ataris store their serial number in the OEM label.
+.TP
+\&\fR\&\f(CWC\fR\ 
+creates the disk image file to install the MS-DOS file system on
+it. Obviously, this is useless on physical devices such as floppies
+and hard disk partitions, but is interesting for image files.
+.TP
+\&\fR\&\f(CWH\fR\ 
+number of hidden sectors. This parameter is useful for formatting hard
+disk partition, which are not aligned on track boundaries (i.e. first
+head of first track doesn't belong to the partition, but contains a
+partition table). In that case the number of hidden sectors is in
+general the number of sectors per cylinder. This is untested.
+.TP
+\&\fR\&\f(CWI\fR\ 
+Sets the fsVersion id when formatting a FAT32 drive.  In order to find
+this out, run minfo on an existing FAT32 drive, and mail me about it, so
+I can include the correct value in future versions of mtools.
+.TP
+\&\fR\&\f(CWc\fR\ 
+Sets the size of a cluster (in sectors).  If this cluster size would
+generate a FAT that too big for its number of bits, mtools automatically
+increases the cluster size, until the FAT is small enough. If no
+cluster size is specified explicitly, mtools uses a default value as
+described in section ``Number of sectors per cluster'' below.
+.TP
+\&\fR\&\f(CWd\fR\ 
+Sets the number of FAT copies. Default is 2. This setting can also be
+specified using the \fR\&\f(CWMTOOLS_NFATS\fR environment variable.
+.TP
+\&\fR\&\f(CWr\fR\ 
+Sets the size of the root directory (in sectors).  Only applicable to 12
+and 16 bit FATs. This setting can also be specified using the
+\&\fR\&\f(CWMTOOLS_DIR_LEN\fR environment variable.
+.TP
+\&\fR\&\f(CWL\fR\ 
+Sets the length of the FAT.
+.TP
+\&\fR\&\f(CWB\fR\ 
+Use the boot sector stored in the given file or device, instead of using
+its own.  Only the geometry fields are updated to match the target disks
+parameters.
+.TP
+\&\fR\&\f(CWk\fR\ 
+Keep the existing boot sector as much as possible.  Only the geometry
+fields and other similar file system data are updated to match the target
+disks parameters.
+.TP
+\&\fR\&\f(CWK\fR\ 
+Sets the sector number where the backup of the boot sector should be
+stored (only relevant on FAT32).
+.TP
+\&\fR\&\f(CWR\fR\ 
+Sets the number of reserved sectors for this filesystem. This must be
+at least 1 for non-FAT32 disks, and at least 3 for FAT disks (in order
+to accommodate the boot sector, the info sector and the backup boot
+sector).
+.TP
+\&\fR\&\f(CWm\fR\ 
+Use a non-standard media descriptor byte for this disk. The media
+descriptor is stored at position 21 of the boot sector, and as first
+byte in each FAT copy. Using this option may confuse DOS or older mtools
+version, and may make the disk unreadable. Only use if you know what you
+are doing.
+.TP
+\&\fR\&\f(CWb\fR\ 
+Use a non-standard bios disk number for this disk. By default, bios
+disk number is inferred from media descriptor: 0x80 for media
+descriptor 0xf8, or 0x00 otherwise.
+.PP
+To format a diskette at a density other than the default, you must supply
+(at least) those command line parameters that are different from the
+default.
+.PP
+\&\fR\&\f(CWMformat\fR returns 0 on success or 1 on failure.
+.PP
+It doesn't record bad block information to the Fat, use
+\&\fR\&\f(CWmbadblocks\fR for that.
+.PP
+.SH Number\ of\ sectors\ per\ cluster
+.PP
+If the user indicates no cluster size, mformat figures out a default
+value for it.
+.PP
+For FAT32 it uses the following table to determine the number of
+sectors per cluster, depending on the total number of sectors on the
+filesystem.
+.PP
+more than 32*1024*1024*2: 64 sectors
+.br
+between 16*1024*1024*2 and 32*1024*1024*2: 32 sectors
+.br
+between 8*1024*1024*2 and 16*1024*1024*2: 16 sectors
+.br
+between 260*1024*2 and 81024*1024*2: 1 sectors
+.br
+.PP
+This is derived from information on page 20 of Microsoft's
+\&\fR\&\f(CWfatgen103\fR document, which currently can be found at the
+following address:
+.PP
+\&\fR\&\f(CWhttps://staff.washington.edu/dittrich/misc/fatgen103.pdf\fR
+.PP
+For FAT12 and FAT16, mformat uses an iterative approach, where it
+starts with a set value, which it doubles until it is able to fill up
+the disk using that cluster size and a number of cluster less than the
+maximum allowed.
+.PP
+The starting value is 1 for disks with one head or less than 2000
+sectors, and 2 for disks with more than one head, and more than 2000
+sectors.
+.PP
+The number of sectors per cluster cannot go beyond 128.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mftext.1 b/upstream/mageia-cauldron/man1/mftext.1
new file mode 100644
index 00000000..39757275
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mftext.1
@@ -0,0 +1,20 @@
+.TH MFTEXT 1
+.SH NAME
+mftext \- Dump a MIDI file as text
+.SH SYNOPSIS
+.BI mftext " file"
+.SH "DESCRIPTION"
+.PP
+.B mftext
+gives a verbose description of what is in a MIDI file.
+You may wish to use it to check the output from
+.BR abc2midi .
+It is part of the original midifilelib distribution
+available from
+.IR http://www.harmony-central.com/MIDI/midifilelib.tar.gz .
+.SH "SEE ALSO"
+.PP
+.IR abcmtex "(1), " abc2abc "(1), " abc2midi "(1), " midi2abc "(1)"
+.SH AUTHOR
+This manual page was written by Anselm Lingnau <lingnau@tm.informatik.uni-frankfurt.de>,
+for the Debian GNU/Linux system.
diff --git a/upstream/mageia-cauldron/man1/mgrtopbm.1 b/upstream/mageia-cauldron/man1/mgrtopbm.1
new file mode 100644
index 00000000..af1f7c98
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mgrtopbm.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Mgrtopbm User Manual" 0 "06 November 2006" "netpbm documentation"
+
+.SH NAME
+
+mgrtopbm - convert a MGR bitmap into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmgrtopbm\fP
+[\fImgrfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBmgrtopbm\fP reads a MGR bitmap as input and produces a PBM
+image as output.
+.PP
+.BR "MGR" (1)\c
+\& is
+a window manager that is a smaller alternative to the X Windows
+System.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBmgrtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtomgr" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/mgrtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/midi2abc.1 b/upstream/mageia-cauldron/man1/midi2abc.1
new file mode 100644
index 00000000..bf06f385
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/midi2abc.1
@@ -0,0 +1,264 @@
+.TH MIDI2ABC 1 "1 January 2017"
+.SH NAME
+\fBmidi2abc\fP \- program to convert MIDI format files to abc notation
+.SH SYNOPSIS
+midi2abc \-f \fIinfile\fP [\-xa] [\-ga]
+[\-a \fIacbeats\fP] [\-m \fItime signature\fP]
+[\-ppu \fiparts per unit\fP] [\-aul \fidenominator of unit length\fP]
+[\-gu] [\-b \fIbars\fP] [\-Q \fItempo\fP] [\-u \fipulses\fP]
+[\-k \fIkey\fP] [\-c \fIchannel\fP] [\-obpl] [\-bpl \fibars\fP] [\-bps \fPbars\fP]
+[\-o \fIfilename\fP] [\-s] [\-sr \fiunits\fP] [\-sum] [\-nb] [\-nt]
+[\-splitvoices] [\-midigram] [\-mftext] [-mftextpulses] [\-nogr] [\-title \fistring\fP]
+[\-origin \fistring\fP]
+
+
+
+.SH DESCRIPTION
+\fImidi2abc\fP takes a MIDI format file and converts it to something as close
+as possible to abc text format. The user then has to add text fields not
+present in the MIDI header and possibly tidy up the abc note output.
+.PP
+The output of midi2abc is printed to the screen. To save it to a file, use
+the redirection operator, (e.g. \fImidi2abc \-f file.mid > file.abc\fP) or
+specify the output file using the \-o option.
+.PP
+Use only one or none of the options \-u \-gu, \-b and \-Q. Midi2abc normally
+converts the MIDI time units into quantum units normally corresponding to the
+abc 1/16th note or 1/32nd note.  If none of these is present, the
+program will use the PPQN information in the MIDI header to compute the suitable
+conversion factor. For most MIDI files on the web, it is recommended to rely on 
+the MIDI header information and not use any of the options other than
+the formatting options.
+.PP
+The program will extract the time signature information from the MIDI file
+if it is present. Otherwise it will assume 4/4 or you could specify it with
+\-m. option. 
+.PP
+If the tune has an anacrusis, you can use either the \-ga or \-xa option to estimate the its length. Alternatively, you can specify its value using the \-a
+option. The anacrusis is specified in half unit lengths, where the unit
+length is defined by the L: field. For example if L: 1/8, then a
+quarter note would be indicated by the value 4, (4 1/16 units). 
+.SS OPTIONS
+.TP
+.B -a \fIacbeats\fP
+where acbeats specifies the anacrusis in half unit lengths. 
+.TP
+.B -xa
+extract the anacrusis from file by finding the first strong note
+.TP
+.B -ga
+guess the anacrusis by minimizing the number of ties across bars
+.TP
+.B -m \fItime signature\fP
+time signature
+.TP
+.B -b \fIbars\fP
+number of bars wanted in output 
+.TP
+.B -Q \fItempo\fP
+tempo in quarter\-notes per minute
+.TP
+.B -u \fipulses\fP
+Allows you to specify directly the number of midi pulses per
+abc time unit.
+.TP
+.B -ppu \fiparts per abc unit length\fP
+Normally, the smallest note unit that midi2abc can extract
+is half the L: unit length.This is called the quantum unit.
+Thus for L: 1/8, midi2abc can extract 1/16 notes but not 1/32 notes.
+You can change this by specifying \-ppu 4 for example. The number of parts
+should be a power of 2.
+.TP
+.B -aul \fidenominator of abc unit length\fP
+Normally midi2abc chooses a unit length of 1/8 or 1/16
+depending upon the time signature. For time signatures
+smaller than 3/4 the L: 1/16 is used and for larger time
+signatures L: 1/8 is used. You can specify the unit length
+to be used using this parameter. Thus \-aul 32 will cause
+midi2abc to use a unit length of 1/32 nd note.
+.TP
+.B -gu
+Tells midi2abc to estimate the number of midi pulses per abc
+time unit from the note duration or spacing in the MIDI file.
+.TP
+.B -gk
+Tells midi2abc to guess the key signature by minimizing
+the number of accidentals even if the key signature is
+already specified in the MIDI file. By default the key
+signature is the one specified in the MIDI file.
+If it is not specified, then the program guesses the
+key signature by minimizing accidentals.
+.TP
+.B -k \fIkey\fP
+key signature: \-6 to 6 sharps.
+.TP
+.B -c \fIchannel\fP
+select only this midi channel.
+.TP
+.B -f \fIinfile\fP
+input file in midi format
+.TP
+.B -o \fIoutput file\fP
+specifies the output abc file name.
+.TP
+.B -s
+do not discard very short notes.
+.TP
+.B -sr \fIquantum units\fP
+do not notate a short rest smaller than the specified size after a note. If the
+size (in quantum units) is zero, nothing is done. For larger values, the rest
+is absorbed into the preceding note. In other words, the preceding note
+is lengthened to include that rest.
+.TP
+.B -sum
+print a short summary of the input midi file.
+.TP
+.B -nb
+do not look for broken rhythms
+.TP
+.B -nt
+do not look for triplets
+.TP
+.B -obpl
+Print only one bar per line instead of 4. For complex music this
+improves the readability and avoids some problems with some abc
+to postscript converters. This option is deprecated.
+.TP
+.B -nogr
+(No note grouping.) Inserts a space between all notes. It makes
+a less pretty postscript file but it is easier to edit.
+.TP
+.B -bpl \finbars\fP
+Print nbars of music on every line followed by a backslash.
+.TP
+.B -bps \finbars\fP
+When nbars have been printed (including those lines joined by
+a backslash continuation) go to a new line (with no backslash).
+.TP
+.B -splitvoices
+This parameter handles polyphonic chords by
+splitting an entire voice into multiple voices. (A polyphonic
+chord is a chord composed of notes that do not start
+or end at the same time.) Normally, midi2abc joins the
+longer notes to the notes in the following chord using ties.
+Here is an example:  [Bd-]d [Bd-]d|. This should
+be separated into two voices ideally  Bz Bz and d2 d2. However,
+the separation is not unique. Bz d2 and d2 Bz are also ok.
+.TP
+.B -midigram
+When this option appears, all other options are ignored and
+no abc file is produced. Instead a list of all notes in the
+MIDI file are printed in a fixed format. Each line represents
+a pair of MIDI note on/off event. The line contains the
+on/off time of the note, its track number, channel number,
+midi pitch and midi velocity. The last record indicates
+the duration of the MIDI file in MIDI pulse units. The
+output is designed to go into a graphical user interface
+which will produce a graphical representation (piano roll).
+.TP
+.B -mftext
+When this option appears, all other options are ignored and
+no abc file is produced. Instead a list of all the MIDI
+commands are printed. The output is designed to go into
+a graphical user interface provided by runabc.tcl.
+.TP
+.B -mftextpulses
+Same as -mftext except the time units is in midi pulses.
+.TP
+.B -title \fistring\fP
+Replaces the default title field following T: with
+the given string.
+.TP
+.B -origin \fistring\fP
+Adds an O: field with the given string.
+.TP
+.B -stats
+Extracts the characteristics of the given midi file. They include
+ntrks - the number of tracks, ppqn - pulses per quarter note,
+timesig - time signature, keysig - key signature, program - mapping
+between channel number and midi program, npulses - length of the
+midi file in pulses, tempocmd - number of times the tempo has
+been specified, pitchbends - number of pitchbends, pitchbendin -
+number of pitchbends in each of the channels, programcmd - number of
+times the midi program has been revised, progs and progsact - the
+programs used and the number of pulses these programs used, drums -
+the drum numbers that were used, drumhits - the number of times
+each of those drums were hit, pitches - the number of times the
+11 pitch classes (C C# etc...) were activated and a few other
+complex variables. These characteristics are used in other
+applications such as midiexplorer. More details are available
+in the file midi2abc-stats.txt included in the doc/ folder
+of the abcmidi distribution package.
+
+
+.SS FEATURES
+* The key is chosen so as to minimize the number of accidentals. 
+Alternatively, the user can specify the key numerically (a positive number
+is the number of sharps, a negative number is minus the number of flats).
+.PP
+* Note length can be set by specifying the total number of bars or the 
+tempo of the piece. Alternatively the note length can be read from the file.
+However, by default it is deduced in a heuristic manner from the inter-note 
+distances.  This means that you do not have to use the MIDI clock as a 
+metronome when playing in a tune from a keyboard. 
+.PP
+* Barlines are automatically inserted. The user specifies the number of
+measures in the anacrusis before the first barline and the time signature.
+.PP
+* The program can guess how the length of the anacrusis,
+either by looking for the first strong note or minimizing the number of
+notes split by a tie across a barline.
+.PP
+* Where a note extends beyond a bar break, it is split into two tied notes.
+.PP
+* The output has 4 bars per line.
+.PP
+* Enough accidental signs are put in the music to ensure that no pitch
+errors occur if a barline is added or deleted.
+.PP
+* The program attempts to group notes sensibly in each bar.
+.PP
+* Triplets and broken rhythm (a>b) are supported.
+.PP
+* Chords are identified.
+.PP
+* Text information from the original MIDI file is included as comments.
+.PP
+* The \-c option can be used to select only 1 MIDI channel. Events on 
+other channels are ignored.
+.SS LIMITATIONS
+midi2abc does not ...
+.PP
+* Supply tune title, composer or any other field apart from X: , K:, Q:, M:
+and L: - these must be added by hand afterwards, though they may have been
+included in the text of the MIDI file.
+.PP
+* Support duplets, quadruplets, other esoteric features.
+.PP
+* Support mid-tune key or time signature changes.
+.PP
+* Deduce repeats. The output is just the notes in the input file.
+.PP
+* Recover an abc tune as supplied to abc2midi. However, if you want to
+do this, "midi2abc  \-xa \-f file.mid" comes close.
+.SH "SEE ALSO"
+abc2ps(1), abc2midi(1), abc2abc(1)
+.SH AUTHOR
+James Allwright <J.R.Allwright@westminster.ac.uk>
+.SH SUPPORTED
+Seymour Shlien <fy733@ncf.ca>
+.SH VERSION
+This man page describes midi2abc version 2.91 from March 09 2008.
+.SH COPYRIGHT
+Copyright 1999 James Allwright
+.PP
+midi2abc does not work correctly if lyrics are embedded in
+the same track as the notes. If you are producing the MIDI
+file using abc2midi, use the \-STFW option to ensure that the
+lyrics are put in a separate track.
+.PP
+midi2abc is supplied "as is" without any warranty. It
+is free software and can be used, copied, modified and
+distributed without fee under the terms of the GNU General 
+Public License. 
+
diff --git a/upstream/mageia-cauldron/man1/midi2ly.1 b/upstream/mageia-cauldron/man1/midi2ly.1
new file mode 100644
index 00000000..89a22a0b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/midi2ly.1
@@ -0,0 +1,79 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH MIDI2LY "1" "January 2024" "midi2ly (LilyPond) 2.24.3" "User Commands"
+.SH NAME
+midi2ly \- manual page for midi2ly (LilyPond) 2.24.3
+.SH SYNOPSIS
+.B midi2ly
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR
+.SH DESCRIPTION
+Convert MIDI to LilyPond input.
+.SH OPTIONS
+.TP
+\fB\-a\fR, \fB\-\-absolute\-pitches\fR
+print absolute pitches
+.TP
+\fB\-d\fR, \fB\-\-duration\-quant\fR=\fI\,DUR\/\fR
+quantise note durations on DUR
+.TP
+\fB\-D\fR, \fB\-\-debug\fR
+debug printing
+.TP
+\fB\-e\fR, \fB\-\-explicit\-durations\fR
+print explicit durations
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-i\fR, \fB\-\-include\-header\fR=\fI\,FILE\/\fR
+prepend FILE to output
+.TP
+\fB\-k\fR, \fB\-\-key\fR=\fI\,ALT[\/\fR:MINOR]
+set key: ALT=+sharps|\-flats; MINOR=1
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to FILE
+.TP
+\fB\-p\fR, \fB\-\-preview\fR
+preview of first 4 bars
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress progress messages and warnings about excess
+voices
+.TP
+\fB\-s\fR, \fB\-\-start\-quant\fR=\fI\,DUR\/\fR
+quantise note starts on DUR
+.TP
+\fB\-S\fR, \fB\-\-skip\fR
+use s instead of r for rests
+.TP
+\fB\-t\fR, \fB\-\-allow\-tuplet\fR=\fI\,DUR\/\fR*NUM/DEN
+allow tuplet durations DUR*NUM/DEN
+.TP
+\fB\-V\fR, \fB\-\-verbose\fR
+be verbose
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-w\fR, \fB\-\-warranty\fR
+show warranty and copyright
+.TP
+\fB\-x\fR, \fB\-\-text\-lyrics\fR
+treat every text as a lyric
+.SH EXAMPLES
+.IP
+\f(CW$ midi2ly --key=-2:1 --duration-quant=32 --allow-tuplet=4*2/3 --allow-tuplet=2*4/3 foo.midi\fR
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH "SEE ALSO"
+The full documentation for
+.B midi2ly
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B midi2ly
+programs are properly installed at your site, the command
+.IP
+.B info midi2ly
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/midicopy.1 b/upstream/mageia-cauldron/man1/midicopy.1
new file mode 100644
index 00000000..460f8549
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/midicopy.1
@@ -0,0 +1,157 @@
+.TH MIDICOPY 1
+.SH NAME
+midicopy \- Copy selected track, channel, time interval of a MIDI file to another MIDI file
+.SH SYNOPSIS
+\fBmidicopy\fP [\fB-ver\fP] [\fB-trks\fP \fIn1,n2,..\fP]\
+    [\fB-xtrks\fP \fIn1,n2,..\fP]\
+    [\fB-xchns\fP \fIn1,n2,..\fP]\
+    [\fB-chans\fP \fIn1,n2,...\fP]\
+    [\fB-from\fP \fIn (in midi ticks)\fP] [\fB-to\fP \fIn (in midi ticks)\fP]\
+    [\fB-fromsec %f\fP \fIn (in seconds)\fP] [\fB-tosec\fP \fIn (in seconds)\fP]\
+    [\fB-frombeat %f\fP \fIn (in beats)\fP] [\fB-tobeat\fP \fIn (in beats)\fP]\
+    [\fB-replace\fP \fItrk,loc,val\fP] [\fB-tempo %n\fP] [\fB-speed %f\fP]\
+    [\fB-drumfocus\fP \fIn \fIm\fP] [\fB-mutenodrum [%d]\fP]\
+    [\fB-setdrumloudness\fP \fIn \fIm\fP]\
+    [\fB-focusontrack\fP \fIn1,n2,... (from 1)\fP]\
+    [\fB-focusonchannel\fP \fIn1,n2,... (from 1)\fP]\
+    [\fB-attenuation\fP \fIn\fP]\
+    [\fB-nobends\fP]\
+    [\fB-indrums\fP \fIn1,n2,...\fP]\
+    [\fB-xdrums\fP \fIn1,n2,...\fP]\
+    [\fB-onlydrums\fP]\
+    [\fB-nodrums\fP]\
+ \fIinput.mid output.mid\fP
+.SH "DESCRIPTION"
+.PP
+.B midicopy
+is used to copy part of a MIDI file to another MIDI file. You can select
+a particular time interval, particular channels, and particular tracks
+or any combinations. If one or both of the run time parameters \-from or \-to
+are included, the program returns the playing time in seconds of the
+output file.  Midicopy was developed by Seymour Shlien from the
+midifilelib distribution available from
+.IR http://www.harmony-central.com/MIDI/midifilelib.tar.gz .
+.SH OPTIONS
+.TP
+.B -ver
+prints version number and then exits
+.TP
+.B -trks n1,n2, etc
+Selects the tracks to be copied where the track numbers start
+from 1.  If more than one track is specified, they should be separated by
+commas. You should always copy track 1 since by convention it contains
+information pertinent to all the other  tracks. By default all tracks
+are copied unless you specify particular tracks using this run time
+parameter.
+.TP
+.B -xtrks n1,n2, etc
+Lists the tracks to exclude from copying. All other tracks are copied.
+This option does not work in combination with \-trks.
+.TP
+.B -xchns n1,n2, etc
+Lists the channels to exclude from copying. All other channels are copied.
+This option does not work in combination with \-chns.
+.TP
+.B -chns n
+Like above, it specifies the MIDI channels to be copied. By default
+all channels are copied. Channel numbers also start from 1.
+.TP
+.B -from n
+The program will copy all MIDI commands starting from midi pulse
+number n. By default it will start from time zero or the beginning
+of the MIDI file.
+.TP
+.B -to n
+Stops copying all events after midi pulse number n. By default
+the file is copied to the end.
+.TP
+.B -frombeat n
+The program will copy all MIDI commands starting from quarter beat
+number n. By default it will start from time zero or the beginning
+of the MIDI file.
+.TP
+.B -tobeat n
+Stops copying all events after quarter beat number n. By default
+the file is copied to the end.
+.TP
+.B -fromsec n
+The program will copy all MIDI commands starting from time n 
+in seconds.
+.TP
+.B -tosec n
+Stops copying all events after time n in seconds. These two
+options (\-fromsec and \-tosec) do not work accurately if the
+MIDI file has more than one tempo command. Only the first
+one is used for converting seconds into MIDI pulse units.
+It is therefore preferable to use the \-from and \-to options.
+.TP
+.B -replace trk,loc,val
+This option should be used alone. Midicopy will copy the entire
+file verbatim except it will replace a byte by val, where the
+byte is located in the specified track (trk) and specified position
+(loc). Commonly this function is used for changing a particular
+MIDI program number (instrument) associated with a channel.
+You need to know the byte count in the track of that parameter
+in order to use this function,
+.TP
+.B -tempo quarter notes/minute
+All tempo indications in the midi file will be replaced with
+the above value.
+.TP
+.B -speed factor
+All tempo indications in the midi file will be multiplied with
+this factor. Values greater than 1.0 will speed up the music while
+lower values slow the music. The factor is a floating point value.
+.TP
+.B -drumfocus drum-code excluded_drum_velocities
+The selected drum line (specified by the drum-code pitch value) is
+highlighted by reducing the loudness of all other drum lines to
+the excluded_drum_velocities value. The drum-code value must
+be in the range of 35 to 81 inclusive.
+.TP
+.B -mutenodrum [level]
+All channels which are not 9 (drum channel) are attenuated to the
+given level. If level is not specified, it is assumed to be zero.
+.TP
+.B -setdrumloudness n m
+where n is between 35 to 81 inclusive and m is the loudness between
+0 and 127. The loudness of all instances of drum n are changed
+to m.
+.TP
+.B -focusontrack n1,n2,...
+The velocities of notes in all tracks except n are attenuated.
+.TP
+.B -focusonchannel n1,n2,...
+The velocities of notes in all channels except n are attenuated.
+.TP
+.B -attenuation n
+Specifies the amount the note velocities are reduced by either
+-focusontracks or -focusonchannels. Current default is 70. 
+.TP
+.B -nobends
+Suppresses all channel pitchbend commands.
+.TP
+.B -indrums  n1,n2,...
+Only allow percussions with codes n1,n2,...
+.TP
+.B -xdrums  n1,n2,...
+Exclude the percussions with codes n1,n2,...
+.TP
+.B -onlydrums
+Only copy the percussion channel.
+.TP
+.B -nodrums
+Copy all channels except the percussion channel.
+
+.SH EXAMPLE
+.B midicopy.exe -trks 1,5 -from 2669 -to 8634 uzicko.mid fragment.mid
+Midicopy will copy tracks 1 and 5 starting from midi pulse position
+2669 and ending at MIDI pulse position 8634.
+
+.SH "SEE ALSO"
+.PP
+.IR abcmtex "(1), " abc2abc "(1), " abc2midi "(1), " midi2abc "(1) ", yaps "(1)"
+.SH AUTHOR
+This manual page was written by Seymour Shlien.
+.SH VERSION
+This man page describes midicopy version 1.33 from December 22 2019.
diff --git a/upstream/mageia-cauldron/man1/minfo.1 b/upstream/mageia-cauldron/man1/minfo.1
new file mode 100644
index 00000000..f6a84057
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/minfo.1
@@ -0,0 +1,99 @@
+'\" t
+.TH minfo 1 "21Mar23" mtools-4.0.43
+.SH Name
+minfo - print the parameters of a MSDOS filesystem
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWminfo\fR command prints the parameters of a MS-DOS file system, such
+as number of sectors, heads and cylinders.  It also prints an mformat
+command line which can be used to create a similar MS-DOS file system on
+another media.  However, this doesn't work with 2m or XDF media, and
+with MS-DOS 1.0 file systems
+.ft I
+.nf
+\&\fR\&\f(CWminfo\fR \fIdrive\fR:
+.fi
+.ft R
+ 
+.PP
+Minfo supports the following option:
+.TP
+\&\fR\&\f(CWv\fR\ 
+Prints a hexdump of the boot sector, in addition to the other information
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mkdir.1 b/upstream/mageia-cauldron/man1/mkdir.1
new file mode 100644
index 00000000..33d51d23
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mkdir.1
@@ -0,0 +1,56 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MKDIR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+mkdir \- make directories
+.SH SYNOPSIS
+.B mkdir
+[\fI\,OPTION\/\fR]... \fI\,DIRECTORY\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Create the DIRECTORY(ies), if they do not already exist.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fI\,MODE\/\fR
+set file mode (as in chmod), not a=rwx \- umask
+.TP
+\fB\-p\fR, \fB\-\-parents\fR
+no error if existing, make parent directories as needed,
+with their file modes unaffected by any \fB\-m\fR option.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print a message for each created directory
+.TP
+\fB\-Z\fR
+set SELinux security context of each created directory
+to the default type
+.TP
+\fB\-\-context\fR[=\fI\,CTX\/\fR]
+like \fB\-Z\fR, or if CTX is specified then set the SELinux
+or SMACK security context to CTX
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBmkdir\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/mkdir>
+.br
+or available locally via: info \(aq(coreutils) mkdir invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mkfifo.1 b/upstream/mageia-cauldron/man1/mkfifo.1
new file mode 100644
index 00000000..9398e9b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mkfifo.1
@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MKFIFO "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+mkfifo \- make FIFOs (named pipes)
+.SH SYNOPSIS
+.B mkfifo
+[\fI\,OPTION\/\fR]... \fI\,NAME\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Create named pipes (FIFOs) with the given NAMEs.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fI\,MODE\/\fR
+set file permission bits to MODE, not a=rw \- umask
+.TP
+\fB\-Z\fR
+set the SELinux security context to default type
+.TP
+\fB\-\-context\fR[=\fI\,CTX\/\fR]
+like \fB\-Z\fR, or if CTX is specified then set the SELinux
+or SMACK security context to CTX
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBmkfifo\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/mkfifo>
+.br
+or available locally via: info \(aq(coreutils) mkfifo invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mkmanifest.1 b/upstream/mageia-cauldron/man1/mkmanifest.1
new file mode 100644
index 00000000..5ac94c6e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mkmanifest.1
@@ -0,0 +1,180 @@
+'\" t
+.TH mkmanifest 1 "21Mar23" mtools-4.0.43
+.SH Name
+mkmanifest - makes list of file names and their DOS 8+3 equivalent
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmkmanifest\fR command is used to create a shell script (packing
+list) to restore Unix filenames. Its syntax is:
+.PP
+\&\fR\&\f(CWmkmanifest\fR [ \fIfiles\fR ]
+.PP
+\&\fR\&\f(CWMkmanifest\fR creates a shell script that aids in the restoration of
+Unix filenames that got clobbered by the MS-DOS filename restrictions.
+MS-DOS filenames are restricted to 8 character names, 3 character
+extensions, upper case only, no device names, and no illegal characters.
+.PP
+The mkmanifest program is compatible with the methods used in
+\&\fR\&\f(CWpcomm, arc,\fR and \fR\&\f(CWmtools\fR to change perfectly good Unix
+filenames to fit the MS-DOS restrictions. This command is only useful if
+the target system which will read the diskette cannot handle VFAT long
+names.
+.PP
+.SH Example
+You want to copy the following Unix files to a MS-DOS diskette (using the
+\&\fR\&\f(CWmcopy\fR command).
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+  very_long_name
+  2.many.dots
+  illegal:
+  good.c
+  prn.dev
+  Capital
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+\&\fR\&\f(CWASCII\fR
+converts the names to:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+  very_lon
+  2xmany.dot
+  illegalx
+  good.c
+  xprn.dev
+  capital
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The command:
+ 
+.nf
+.ft 3
+.in +0.3i
+mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital >manifest
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRwould produce the following:
+ 
+.nf
+.ft 3
+.in +0.3i
+  mv very_lon very_long_name
+  mv 2xmany.dot 2.many.dots
+  mv illegalx illegal:
+  mv xprn.dev prn.dev
+  mv capital Capital
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+Notice that "good.c" did not require any conversion, so it did not
+appear in the output.
+.PP
+Suppose I've copied these files from the diskette to another Unix
+system, and I now want the files back to their original names.  If the
+file "manifest" (the output captured above) was sent along with those
+files, it could be used to convert the filenames.
+.PP
+.SH Bugs
+.PP
+The short names generated by \fR\&\f(CWmkmanifest\fR follow the old convention
+(from mtools-2.0.7) and not the one from Windows 95 and mtools-3.0.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mknod.1 b/upstream/mageia-cauldron/man1/mknod.1
new file mode 100644
index 00000000..c9974d3e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mknod.1
@@ -0,0 +1,66 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MKNOD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+mknod \- make block or character special files
+.SH SYNOPSIS
+.B mknod
+[\fI\,OPTION\/\fR]... \fI\,NAME TYPE \/\fR[\fI\,MAJOR MINOR\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Create the special file NAME of the given TYPE.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fI\,MODE\/\fR
+set file permission bits to MODE, not a=rw \- umask
+.TP
+\fB\-Z\fR
+set the SELinux security context to default type
+.TP
+\fB\-\-context\fR[=\fI\,CTX\/\fR]
+like \fB\-Z\fR, or if CTX is specified then set the SELinux
+or SMACK security context to CTX
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Both MAJOR and MINOR must be specified when TYPE is b, c, or u, and they
+must be omitted when TYPE is p.  If MAJOR or MINOR begins with 0x or 0X,
+it is interpreted as hexadecimal; otherwise, if it begins with 0, as octal;
+otherwise, as decimal.  TYPE may be:
+.TP
+b
+create a block (buffered) special file
+.TP
+c, u
+create a character (unbuffered) special file
+.TP
+p
+create a FIFO
+.PP
+NOTE: your shell may have its own version of mknod, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBmknod\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/mknod>
+.br
+or available locally via: info \(aq(coreutils) mknod invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mkosi.1 b/upstream/mageia-cauldron/man1/mkosi.1
new file mode 100644
index 00000000..e32d7ccb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mkosi.1
@@ -0,0 +1,1852 @@
+.\" Automatically generated by Pandoc 2.14.0.3
+.\"
+.TH "mkosi" "1" "2016-" "" ""
+.hy
+.SH NAME
+.PP
+mkosi \[em] Build Bespoke OS Images
+.SH SYNOPSIS
+.PP
+\f[C]mkosi [options\&...] build\f[R]
+.PP
+\f[C]mkosi [options\&...] clean\f[R]
+.PP
+\f[C]mkosi [options\&...] summary\f[R]
+.PP
+\f[C]mkosi [options\&...] shell [command line\&...]\f[R]
+.PP
+\f[C]mkosi [options\&...] boot [nspawn settings\&...]\f[R]
+.PP
+\f[C]mkosi [options\&...] qemu\f[R]
+.PP
+\f[C]mkosi [options\&...] ssh\f[R]
+.PP
+\f[C]mkosi [options\&...] serve\f[R]
+.PP
+\f[C]mkosi [options\&...] bump\f[R]
+.PP
+\f[C]mkosi [options\&...] genkey\f[R]
+.PP
+\f[C]mkosi [options\&...] help\f[R]
+.SH DESCRIPTION
+.PP
+\f[C]mkosi\f[R] is a tool for easily building customized OS images.
+It\[cq]s a fancy wrapper around \f[C]dnf --installroot\f[R],
+\f[C]debootstrap\f[R], \f[C]pacstrap\f[R] and \f[C]zypper\f[R] that may
+generate disk images with a number of bells and whistles.
+.SS Command Line Verbs
+.PP
+The following command line verbs are known:
+.TP
+\f[B]\f[CB]build\f[B]\f[R]
+This builds the image, based on the settings passed in on the command
+line or read from a \f[C]mkosi.default\f[R] file.
+This verb is the default if no verb is explicitly specified.
+This command must be executed as \f[C]root\f[R].
+Any arguments passed after \f[C]build\f[R] are passed as arguments to
+the build script (if there is one).
+.TP
+\f[B]\f[CB]clean\f[B]\f[R]
+Remove build artifacts generated on a previous build.
+If combined with \f[C]-f\f[R], also removes incremental build cache
+images.
+If \f[C]-f\f[R] is specified twice, also removes any package cache.
+.TP
+\f[B]\f[CB]summary\f[B]\f[R]
+Outputs a human-readable summary of all options used for building an
+image.
+This will parse the command line and \f[C]mkosi.default\f[R] file as it
+would do on \f[C]build\f[R], but only output what it is configured for
+and not actually build anything.\[ga]
+.TP
+\f[B]\f[CB]shell\f[B]\f[R]
+This builds the image if it is not built yet, and then invokes
+\f[C]systemd-nspawn\f[R] to acquire an interactive shell prompt in it.
+If this verb is used an optional command line may be specified which is
+then invoked in place of the shell in the container.
+Combine this with \f[C]-f\f[R] in order to rebuild the image
+unconditionally before acquiring the shell, see below.
+This command must be executed as \f[C]root\f[R].
+.TP
+\f[B]\f[CB]boot\f[B]\f[R]
+Similar to \f[C]shell\f[R] but boots the image up using
+\f[C]systemd-nspawn\f[R].
+If this verb is used an optional command line may be specified which is
+passed as \[lq]kernel command line\[rq] to the init system in the image.
+.TP
+\f[B]\f[CB]qemu\f[B]\f[R]
+Similar to \f[C]boot\f[R] but uses \f[C]qemu\f[R] to boot up the image,
+i.e.\ instead of container virtualization VM virtualization is used.
+This verb is only supported on images that contain a boot loader,
+i.e.\ those built with \f[C]Bootable=yes\f[R] (see below).
+This command must be executed as \f[C]root\f[R] unless the image already
+exists and \f[C]-f\f[R] is not specified.
+.TP
+\f[B]\f[CB]ssh\f[B]\f[R]
+When the image is built with the \f[C]Ssh=yes\f[R] option, this command
+connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container/VM
+via SSH.
+Make sure to run \f[C]mkosi ssh\f[R] with the same config as
+\f[C]mkosi build\f[R] was run with so that it has the necessary
+information available to connect to the running container/VM via SSH.
+.TP
+\f[B]\f[CB]serve\f[B]\f[R]
+This builds the image if it is not built yet, and then serves the output
+directory (i.e.\ usually \f[C]mkosi.output/\f[R], see below) via a small
+embedded HTTP server, listening on port 8081.
+Combine with \f[C]-f\f[R] in order to rebuild the image unconditionally
+before serving it.
+This command is useful for testing network based acquisition of OS
+images, for example via \f[C]machinectl pull-raw \&...\f[R] and
+\f[C]machinectl   pull-tar \&...\f[R].
+.TP
+\f[B]\f[CB]bump\f[B]\f[R]
+Determines the current image version string (as configured with
+\f[C]ImageVersion=\f[R]/\f[C]--image-version=\f[R]), increases its last
+dot-separated component by one and writes the resulting version string
+to \f[C]mkosi.version\f[R].
+This is useful for implementing a simple versioning scheme: each time
+this verb is called the version is bumped in preparation for the
+subsequent build.
+Note that \f[C]--auto-bump\f[R]/\f[C]-B\f[R] may be used to
+automatically bump the version after each successful build.
+.TP
+\f[B]\f[CB]genkey\f[B]\f[R]
+Generate a pair of SecureBoot keys for usage with the
+\f[C]SecureBootKey=\f[R]/\f[C]--secure-boot-key=\f[R] and
+\f[C]SecureBootCertificate=\f[R]/\f[C]--secure-boot-certificate=\f[R]
+options.
+.TP
+\f[B]\f[CB]help\f[B]\f[R]
+This verb is equivalent to the \f[C]--help\f[R] switch documented below:
+it shows a brief usage explanation.
+.SS Execution flow
+.PP
+Execution flow for \f[C]mkosi build\f[R].
+Columns represent the execution context.
+Default values/calls are shown in parentheses.
+When building with \f[C]--incremental\f[R] mkosi creates a cache of the
+distribution installation for both images if not already existing and
+replaces the distribution installation in consecutive runs with data
+from the cached one.
+.IP
+.nf
+\f[C]
+            HOST            .          BUILD          .          FINAL
+                            .          IMAGE          .          IMAGE
+                            .                         .
+   start                    .                         .
+     |                      .                         .
+     v                      .                         .
+build script?  -------exists----->     copy           .
+     |                      .      skeleton trees     .
+     |                      .     (mkosi.skeleton/)   .
+    none                    .            |            .
+     |                      .            v            .
+     v                      .         install         .
+    skip                    .       distribution,     .
+ build image                .       packages and      .
+     |                      .      build packages,    .
+     |                      .           run           .
+     |                      .      prepare script     .
+     |                      .   (mkosi.prepare build) .
+     |                      .     or if incremental   .
+     |                      .  use cached build image .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .          copy           .
+     |                      .      build sources      .
+     |                      .          (./)           .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .          copy           .
+     |                      .       extra trees       .
+     |                      .      (mkosi.extra/)     .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .           run           .
+     |                      .    postinstall script   .
+     |                      .  (mkosi.postinst build) .
+     |                      .            |            .
+     |         .-------------------------\[aq]            .
+     |         |            .                         .
+     |         v            .                         .
+     |        run           .                         .
+     |   finalize script    .                         .
+     |(mkosi.finalize build).                         .
+     |         |            .                         .
+     |         \[aq]-------------------------.            .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .           run           .
+     |                      .       build script      .
+     |                      .      (mkosi.build)      .
+     |                      .            |            .
+     \[aq]-----------------------------------+------------------------.
+                            .                         .           |
+                            .                         .           v
+                            .                         .          copy
+                            .                         .     skeleton trees
+                            .                         .    (mkosi.skeleton/)
+                            .                         .           |
+                            .                         .           v
+                            .                         .        install
+                            .                         .      distribution
+                            .                         .      and packages,
+                            .                         .          run
+                            .                         .     prepare script
+                            .                         .  (mkosi.prepare final)
+                            .                         .    or if incremental
+                            .                         . use cached final image
+                            .                         .           |
+                            .                         .           v
+                            .                         .         copy
+                            .                         .     build results
+                            .                         .           |
+                            .                         .           v
+                            .                         .         copy
+                            .                         .      extra trees
+                            .                         .     (mkosi.extra/)
+                            .                         .           |
+                            .                         .           v
+                            .                         .          run
+                            .                         .    postinstall script
+                            .                         .  (mkosi.postinst final)
+                            .                         .           |
+                            .                         .           v
+                            .                         .           |
+                            .                         .     perform cleanup
+                            .                         . (remove files, packages,
+                            .                         .     package metadata)
+                            .                         .           |
+               .--------------------------------------------------\[aq]
+               |            .                         .
+               v            .                         .
+              run           .                         .
+        finalize script     .                         .
+    (mkosi.finalize final)  .                         .
+               |            .                         .
+     .---------\[aq]            .                         .
+     |                      .                         .
+     v                      .                         .
+    end                     .                         .
+                            .                         .
+            HOST            .          BUILD          .          FINAL
+                            .          IMAGE          .          IMAGE
+                            .                         .
+\f[R]
+.fi
+.SS Supported output formats
+.PP
+The following output formats are supported:
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with ext4 as root (\f[I]gpt_ext4\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with xfs as root (\f[I]gpt_xfs\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with btrfs as root (\f[I]gpt_btrfs\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with squashfs as read-only root
+(\f[I]gpt_squashfs\f[R])
+.IP \[bu] 2
+Plain squashfs image, without partition table, as read-only root
+(\f[I]plain_squashfs\f[R])
+.IP \[bu] 2
+Plain directory, containing the OS tree (\f[I]directory\f[R])
+.IP \[bu] 2
+btrfs subvolume, with separate subvolumes for \f[C]/var\f[R],
+\f[C]/home\f[R], \f[C]/srv\f[R], \f[C]/var/tmp\f[R]
+(\f[I]subvolume\f[R])
+.IP \[bu] 2
+Tar archive (\f[I]tar\f[R])
+.IP \[bu] 2
+CPIO archive (\f[I]cpio\f[R]) in the format appropriate for a kernel
+initrd
+.PP
+When a \f[I]GPT\f[R] disk image is created, the following additional
+options are available:
+.IP \[bu] 2
+A swap partition may be added in
+.IP \[bu] 2
+The image may be made bootable on \f[I]EFI\f[R] and \f[I]BIOS\f[R]
+systems
+.IP \[bu] 2
+Separate partitions for \f[C]/srv\f[R] and \f[C]/home\f[R] may be added
+in
+.IP \[bu] 2
+The root, \f[C]/srv\f[R] and \f[C]/home\f[R] partitions may optionally
+be encrypted with LUKS.
+.IP \[bu] 2
+A dm-verity partition may be added in that adds runtime integrity data
+for the root partition
+.SS Configuration Settings
+.PP
+The following settings can be set through configuration files (the
+syntax with \f[C]SomeSetting=value\f[R]) and on the command line (the
+syntax with \f[C]--some-setting=value\f[R]).
+For some command line parameters, a single-letter shortcut is also
+allowed.
+In the configuration files, the setting must be in the appropriate
+section, so the settings are grouped by section below.
+.PP
+Command line options that take no argument are shown without \[lq]=\[rq]
+in their long version.
+In the config files, they should be specified with a boolean argument:
+either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or
+\[lq]0\[rq], \[lq]no\[rq], \[lq]false\[rq] to disable.
+.SS [Distribution] Section
+.TP
+\f[B]\f[CB]Distribution=\f[B]\f[R], \f[B]\f[CB]--distribution=\f[B]\f[R], \f[B]\f[CB]-d\f[B]\f[R]
+The distribution to install in the image.
+Takes one of the following arguments: \f[C]fedora\f[R],
+\f[C]debian\f[R], \f[C]ubuntu\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R],
+\f[C]mageia\f[R], \f[C]centos\f[R], \f[C]centos_epel\f[R],
+\f[C]clear\f[R], \f[C]photon\f[R], \f[C]openmandriva\f[R],
+\f[C]rocky\f[R], \f[C]rocky_epel\f[R], \f[C]alma\f[R],
+\f[C]alma_epel\f[R].
+If not specified, defaults to the distribution of the host.
+.TP
+\f[B]\f[CB]Release=\f[B]\f[R], \f[B]\f[CB]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R]
+The release of the distribution to install in the image.
+The precise syntax of the argument this takes depends on the
+distribution used, and is either a numeric string (in case of Fedora
+Linux, CentOS, \&..., e.g.\ \f[C]29\f[R]), or a distribution version
+name (in case of Debian, Ubuntu, \&..., e.g.\ \f[C]artful\f[R]).
+If neither this option, nor \f[C]Distribution=\f[R] is specified,
+defaults to the distribution version of the host.
+If the distribution is specified, defaults to a recent version of it.
+.TP
+\f[B]\f[CB]Mirror=\f[B]\f[R], \f[B]\f[CB]--mirror=\f[B]\f[R], \f[B]\f[CB]-m\f[B]\f[R]
+The mirror to use for downloading the distribution packages.
+Expects a mirror URL as argument.
+.TP
+\f[B]\f[CB]Repositories=\f[B]\f[R], \f[B]\f[CB]--repositories=\f[B]\f[R]
+Additional package repositories to use during installation.
+Expects one or more URLs as argument, separated by commas.
+This option may be used multiple times, in which case the list of
+repositories to use is combined.
+Use \[lq]!*\[rq] to remove all repositories from to the list or use
+e.g.\ \[lq]!repo-url\[rq] to remove just one specific repository.
+For Arch Linux, additional repositories must be passed in the form
+\f[C]<name>::<url>\f[R] (e.g.\ \f[C]myrepo::https://myrepo.net\f[R]).
+.TP
+\f[B]\f[CB]UseHostRepositories=\f[B]\f[R], \f[B]\f[CB]--use-host-repositories\f[B]\f[R]
+This option is only applicable for RPM-based distributions:
+\f[I]CentOS\f[R], \f[I]Fedora Linux\f[R], \f[I]Mageia\f[R],
+\f[I]Photon\f[R], \f[I]Rocky Linux\f[R], \f[I]Alma Linux\f[R] and
+\f[I]OpenMandriva\f[R].
+Allows use of the host\[cq]s existing RPM repositories.
+By default, a hardcoded set of default RPM repositories is generated and
+used.
+Use \f[C]--repositories=\f[R] to identify a custom set of repositories
+to be enabled and used for the build.
+.TP
+\f[B]\f[CB]RepositoryDirectory\f[B]\f[R], \f[B]\f[CB]--repository-directory\f[B]\f[R]
+This option can (for now) only be used with RPM-based istributions and
+Arch Linux.
+It identifies a directory containing extra repository definitions that
+will be used when installing packages.
+The files are passed directly to the corresponding package manager and
+should be written in the format expected by the package manager of the
+image\[cq]s distro.
+.TP
+\f[B]\f[CB]Architecture=\f[B]\f[R], \f[B]\f[CB]--architecture=\f[B]\f[R]
+The architecture to build the image for.
+Note that this currently only works for architectures compatible with
+the host\[cq]s architecture.
+.SS [Output] Section
+.TP
+\f[B]\f[CB]Format=\f[B]\f[R], \f[B]\f[CB]--format=\f[B]\f[R], \f[B]\f[CB]-t\f[B]\f[R]
+The image format type to generate.
+One of \f[C]directory\f[R] (for generating OS images inside a local
+directory), \f[C]subvolume\f[R] (similar, but as a btrfs subvolume),
+\f[C]tar\f[R] (similar, but a tarball of the image is generated),
+\f[C]cpio\f[R] (similar, but a cpio archive is generated),
+\f[C]gpt_ext4\f[R] (a block device image with an ext4 file system inside
+a GPT partition table), \f[C]gpt_xfs\f[R] (similar, but with an xfs file
+system), \f[C]gpt_btrfs\f[R] (similar, but with an btrfs file system),
+\f[C]gpt_squashfs\f[R] (similar, but with a squashfs file system),
+\f[C]plain_squashfs\f[R] (a plain squashfs file system without a
+partition table).
+.TP
+\f[B]\f[CB]ManifestFormat=\f[B]\f[R], \f[B]\f[CB]--manifest-format=\f[B]\f[R]
+The manifest format type or types to generate.
+A comma-delimited list consisting of \f[C]json\f[R] (the standard JSON
+output format that describes the packages installed),
+\f[C]changelog\f[R] (a human-readable text format designed for diffing).
+Defaults to \f[C]json\f[R].
+.TP
+\f[B]\f[CB]Output=\f[B]\f[R], \f[B]\f[CB]--output=\f[B]\f[R], \f[B]\f[CB]-o\f[B]\f[R]
+Path for the output image file to generate.
+Takes a relative or absolute path where the generated image will be
+placed.
+If neither this option nor \f[C]OutputDirectory=\f[R] is used, the image
+is generated under the name \f[C]image\f[R], but its name suffixed with
+an appropriate file suffix (e.g.\ \f[C]image.raw.xz\f[R] in case
+\f[C]gpt_ext4\f[R] is used in combination with \f[C]xz\f[R]
+compression).
+If the \f[C]ImageId=\f[R] option is configured it is used instead of
+\f[C]image\f[R] in the default output name.
+If an image version is specified via \f[C]ImageVersion=\f[R], it is
+included in the default name, e.g.\ a specified image version of
+\f[C]7.8\f[R] might result in an image file name of
+\f[C]image_7.8.raw.xz\f[R].
+.TP
+\f[B]\f[CB]OutputSplitRoot=\f[B]\f[R], \f[B]\f[CB]--output-split-root=\f[B]\f[R], \f[B]\f[CB]OutputSplitVerify=\f[B]\f[R], \f[B]\f[CB]--output-split-verity=\f[B]\f[R], \f[B]\f[CB]OutputSplitKernel=\f[B]\f[R], \f[B]\f[CB]--output-split-kernel=\f[B]\f[R]
+Paths for the split-out output image files, when
+\f[C]SplitArtifacts=yes\f[R] is used.
+If unspecified, the relevant split artifact files will be named like the
+main image, but with \f[C].root\f[R], \f[C].verity\f[R], and
+\f[C].efi\f[R] suffixes inserted (and in turn possibly suffixed by
+compression suffix, if compression is enabled).
+.TP
+\f[B]\f[CB]OutputDirectory=\f[B]\f[R], \f[B]\f[CB]--output-dir=\f[B]\f[R], \f[B]\f[CB]-O\f[B]\f[R]
+Path to a directory where to place all generated artifacts (i.e.\ the
+generated image when an output path is not given, \f[C]SHA256SUMS\f[R]
+file, etc.).
+If this is not specified and the directory \f[C]mkosi.output/\f[R]
+exists in the local directory, it is automatically used for this
+purpose.
+If the setting is not used and \f[C]mkosi.output/\f[R] does not exist,
+all output artifacts are placed adjacent to the output image file.
+.TP
+\f[B]\f[CB]WorkspaceDirectory=\f[B]\f[R], \f[B]\f[CB]--workspace-dir=\f[B]\f[R]
+Path to a directory where to store data required temporarily while
+building the image.
+This directory should have enough space to store the full OS image,
+though in most modes the actually used disk space is smaller.
+If not specified, and \f[C]mkosi.workspace/\f[R] exists in the local
+directory, it is used for this purpose.
+Otherwise, a subdirectory in the temporary storage area is used
+(\f[C]$TMPDIR\f[R] if set, \f[C]/var/tmp/\f[R] otherwise).
+The data in this directory is removed automatically after each build.
+It\[cq]s safe to manually remove the contents of this directory should
+an \f[C]mkosi\f[R] invocation be aborted abnormally (for example, due to
+reboot/power failure).
+If the \f[C]btrfs\f[R] output modes are selected this directory must be
+backed by \f[C]btrfs\f[R] too.
+.TP
+\f[B]\f[CB]Force=\f[B]\f[R], \f[B]\f[CB]--force\f[B]\f[R], \f[B]\f[CB]-f\f[B]\f[R]
+Replace the output file if it already exists, when building an image.
+By default when building an image and an output artifact already exists
+\f[C]mkosi\f[R] will refuse operation.
+Specify this option once to delete all build artifacts from a previous
+run before re-building the image.
+If incremental builds are enabled, specifying this option twice will
+ensure the intermediary cache files are removed, too, before the
+re-build is initiated.
+If a package cache is used (also see the \[lq]Files\[rq] section below),
+specifying this option thrice will ensure the package cache is removed
+too, before the re-build is initiated.
+For the \f[C]clean\f[R] operation this option has a slightly different
+effect: by default the verb will only remove build artifacts from a
+previous run, when specified once the incremental cache files are
+deleted too, and when specified twice the package cache is also removed.
+.PP
+.TP
+\f[B]\f[CB]GPTFirstLBA=\f[B]\f[R], \f[B]\f[CB]--gpt-first-lba=\f[B]\f[R]
+Override the first usable LBA (Logical Block Address) within the GPT
+header.
+This defaults to \f[C]2048\f[R], which is actually the desired value.
+However, some tools, e.g.\ the \f[C]prl_disk_tool\f[R] utility from the
+Parallels virtualization suite require this to be set to \f[C]34\f[R],
+otherwise they might fail to resize the disk image and/or partitions
+inside it.
+.TP
+\f[B]\f[CB]Bootable=\f[B]\f[R], \f[B]\f[CB]--bootable\f[B]\f[R], \f[B]\f[CB]-b\f[B]\f[R]
+Generate a bootable image.
+By default this will generate an image bootable on UEFI systems.
+Use \f[C]BootProtocols=\f[R] to select support for a different boot
+protocol.
+.TP
+\f[B]\f[CB]BootProtocols=\f[B]\f[R], \f[B]\f[CB]--boot-protocols=\f[B]\f[R]
+Pick one or more boot protocols to support when generating a bootable
+image, as enabled with \f[C]Bootable=\f[R].
+Takes a comma-separated list of \f[C]uefi\f[R] or \f[C]bios\f[R].
+May be specified more than once in which case the specified lists are
+merged.
+If \f[C]uefi\f[R] is specified the \f[C]sd-boot\f[R] UEFI boot loader is
+used, if \f[C]bios\f[R] is specified the GNU Grub boot loader is used.
+Use \[lq]!*\[rq] to remove all previously added protocols or
+\[lq]!protocol\[rq] to remove one protocol.
+.TP
+\f[B]\f[CB]KernelCommandLine=\f[B]\f[R], \f[B]\f[CB]--kernel-command-line=\f[B]\f[R]
+Use the specified kernel command line when building bootable images.
+By default command line arguments get appended.
+To remove all arguments from the current list pass \[lq]!*\[rq].
+To remove specific arguments add a space separated list of \[lq]!\[rq]
+prefixed arguments.
+For example adding \[lq]!* console=ttyS0 rw\[rq] to a
+\f[C]mkosi.default\f[R] file or the command line arguments passes
+\[lq]console=ttyS0 rw\[rq] to the kernel in any case.
+Just adding \[lq]console=ttyS0 rw\[rq] would append these two arguments
+to the kernel command line created by lower priority configuration files
+or previous \f[C]KernelCommandLine=\f[R] command line arguments.
+.TP
+\f[B]\f[CB]SecureBoot=\f[B]\f[R], \f[B]\f[CB]--secure-boot\f[B]\f[R]
+Sign the resulting kernel/initrd image for UEFI SecureBoot.
+.TP
+\f[B]\f[CB]SecureBootKey=\f[B]\f[R], \f[B]\f[CB]--secure-boot-key=\f[B]\f[R]
+Path to the PEM file containing the secret key for signing the UEFI
+kernel image, if \f[C]SecureBoot=\f[R] is used.
+.TP
+\f[B]\f[CB]SecureBootCertificate=\f[B]\f[R], \f[B]\f[CB]--secure-boot-certificate=\f[B]\f[R]
+Path to the X.509 file containing the certificate for the signed UEFI
+kernel image, if \f[C]SecureBoot=\f[R] is used.
+.TP
+\f[B]\f[CB]SecureBootCommonName=\f[B]\f[R], \f[B]\f[CB]--secure-boot-common-name=\f[B]\f[R]
+Common name to be used when generating SecureBoot keys via mkosi\[cq]s
+\f[C]genkey\f[R] command.
+Defaults to \f[C]mkosi of %u\f[R], where \f[C]%u\f[R] expands to the
+username of the user invoking mkosi.
+.TP
+\f[B]\f[CB]SecureBootValidDays=\f[B]\f[R], \f[B]\f[CB]--secure-boot-valid-days=\f[B]\f[R]
+Number of days that the keys should remain valid when generating
+SecureBoot keys via mkosi\[cq]s \f[C]genkey\f[R] command.
+Defaults to two years (730 days).
+.TP
+\f[B]\f[CB]ReadOnly=\f[B]\f[R], \f[B]\f[CB]--read-only\f[B]\f[R]
+Set the read-only flag on the root partition in the partition table.
+Only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R], \f[C]subvolume\f[R] output formats, and is implied
+on \f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R].
+The read-only flag is essentially a hint to tools using the image (see
+https://systemd.io/DISCOVERABLE_PARTITIONS/).
+In particular, all systemd tools like \f[C]systemd-nspawn\f[R] and
+\f[C]systemd-gpt-auto-generator\f[R] will mount such partitions
+read-only, but tools from other project may ignore the flag.
+.TP
+\f[B]\f[CB]Minimize=\f[B]\f[R], \f[B]\f[CB]--minimize\f[B]\f[R]
+Attempt to make the resulting root file system as small as possible by
+removing free space from the file system.
+Only supported for \f[C]gpt_ext4\f[R] and \f[C]gpt_btrfs\f[R].
+For ext4 this relies on \f[C]resize2fs -M\f[R], which reduces the free
+disk space but is not perfect and generally leaves some free space.
+For btrfs the results are optimal and no free space is left.
+.TP
+\f[B]\f[CB]Encrypt=\f[B]\f[R], \f[B]\f[CB]--encrypt\f[B]\f[R]
+Encrypt all partitions in the file system or just the root file system.
+Takes either \f[C]all\f[R] or \f[C]data\f[R] as argument.
+If \f[C]all\f[R], the root, \f[C]/home\f[R] and \f[C]/srv\f[R] file
+systems will be encrypted using dm-crypt/LUKS (with its default
+settings).
+If \f[C]data\f[R], the root file system will be left unencrypted, but
+\f[C]/home\f[R] and \f[C]/srv\f[R] will be encrypted.
+The passphrase to use is read from the \f[C]mkosi.passphrase\f[R] file
+in the current working directory.
+Note that the UEFI System Partition (ESP) containing the boot loader and
+kernel to boot is never encrypted since it needs to be accessible by the
+firmware.
+.TP
+\f[B]\f[CB]Verity=\f[B]\f[R], \f[B]\f[CB]--verity\f[B]\f[R]
+Add a \[lq]Verity\[rq] integrity partition to the image.
+Takes a boolean or the special value \f[C]signed\f[R], and defaults to
+disabled.
+If enabled, the root partition (or \f[C]/usr/\f[R] partition, in case
+\f[C]UsrOnly=\f[R] is enabled) is protected with \f[C]dm-verity\f[R]
+against offline modification, the verification data is placed in an
+additional GPT partition.
+Implies \f[C]ReadOnly=yes\f[R].
+If this is enabled, the Verity root hash is written to an output file
+with \f[C].roothash\f[R] or \f[C].usrhash\f[R] suffix.
+If set to \f[C]signed\f[R], Verity is also enabled, but the resulting
+root hash is then also signed (in PKCS#7 format) with the signature key
+configured with \f[C]SecureBootKey=\f[R].
+Or in other words: the SecureBoot key pair is then used to both sign the
+kernel, if that is enabled, and the root/\f[C]/usr/\f[R] file system.
+This signature is then stored in an additional output file with the
+\f[C].roothash.p7s\f[R] or \f[C].usrhash.p7s\f[R] suffix in DER format.
+It is also written to an additional partition in the image.
+The latter allows generating self-contained signed disk images,
+implementing the Verity provisions described in the Discoverable
+Partitions Specification (https://systemd.io/DISCOVERABLE_PARTITIONS).
+.TP
+\f[B]\f[CB]CompressFs=\f[B]\f[R], \f[B]\f[CB]--compress-fs=\f[B]\f[R]
+Enable or disable internal compression in the file system.
+Only applies to output formats with squashfs or btrfs.
+Takes one of \f[C]zlib\f[R], \f[C]lzo\f[R], \f[C]zstd\f[R],
+\f[C]lz4\f[R], \f[C]xz\f[R] or a boolean value as argument.
+If the latter is used compression is enabled/disabled and the default
+algorithm is used.
+In case of the \f[C]squashfs\f[R] output formats compression is implied,
+but this option may be used to select the algorithm.
+.TP
+\f[B]\f[CB]CompressOutput=\f[B]\f[R], \f[B]\f[CB]--compress-output=\f[B]\f[R]
+Configure compression for the resulting image or archive.
+The argument can be either a boolean or a compression algorithm
+(\f[C]xz\f[R], \f[C]zstd\f[R]).
+\f[C]xz\f[R] compression is used by default.
+Note that when applied to block device image types this means the image
+cannot be started directly but needs to be decompressed first.
+This also means that the \f[C]shell\f[R], \f[C]boot\f[R], \f[C]qemu\f[R]
+verbs are not available when this option is used.
+Implied for \f[C]tar\f[R] and \f[C]cpio\f[R].
+.TP
+\f[B]\f[CB]Compress=\f[B]\f[R], \f[B]\f[CB]--compress=\f[B]\f[R]
+Enable compression.
+Using this option is equivalent to either \f[C]CompressFs=\f[R] or
+\f[C]CompressOutput=\f[R]; the appropriate type of compression is
+selected automatically.
+.TP
+\f[B]\f[CB]Mksquashfs=\f[B]\f[R], \f[B]\f[CB]--mksquashfs=\f[B]\f[R]
+Set the path to the \f[C]mksquashfs\f[R] executable to use.
+This is useful in case the parameters for the tool shall be augmented,
+as the tool may be replaced by a script invoking it with the right
+parameters, this way.
+.TP
+\f[B]\f[CB]QCow2=\f[B]\f[R], \f[B]\f[CB]--qcow2\f[B]\f[R]
+Encode the resulting image as QEMU QCOW2 image.
+This only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R], \f[C]gpt_squashfs\f[R].
+QCOW2 images can be read natively by \f[C]qemu\f[R], but not by the
+Linux kernel.
+This means the \f[C]shell\f[R] and \f[C]boot\f[R] verbs are not
+available when this option is used, however \f[C]qemu\f[R] will work.
+.TP
+\f[B]\f[CB]Hostname=\f[B]\f[R], \f[B]\f[CB]--hostname=\f[B]\f[R]
+Set the image\[cq]s hostname to the specified name.
+.TP
+\f[B]\f[CB]ImageVersion=\f[B]\f[R], \f[B]\f[CB]--image-version=\f[B]\f[R]
+Configure the image version.
+This accepts any string, but it is recommended to specify a series of
+dot separated components.
+The version may also be configured in a file \f[C]mkosi.version\f[R] in
+which case it may be conveniently managed via the \f[C]bump\f[R] verb or
+the \f[C]--auto-bump\f[R] switch.
+When specified the image version is included in the default output file
+name, i.e.\ instead of \f[C]image.raw\f[R] the default will be
+\f[C]image_0.1.raw\f[R] for version \f[C]0.1\f[R] of the image, and
+similar.
+The version is also passed via the \f[C]$IMAGE_VERSION\f[R] to any build
+scripts invoked (which may be useful to patch it into
+\f[C]/etc/os-release\f[R] or similar, in particular the
+\f[C]IMAGE_VERSION=\f[R] field of it).
+.TP
+\f[B]\f[CB]ImageId=\f[B]\f[R], \f[B]\f[CB]--image-id=\f[B]\f[R]
+Configure the image identifier.
+This accepts a freeform string that shall be used to identify the image
+with.
+If set the default output file will be named after it (possibly suffixed
+with the version).
+If this option is used the root, \f[C]/usr/\f[R] and Verity partitions
+in the image will have their labels set to this (possibly suffixed by
+the image version).
+The identifier is also passed via the \f[C]$IMAGE_ID\f[R] to any build
+scripts invoked (which may be useful to patch it into
+\f[C]/etc/os-release\f[R] or similar, in particular the
+\f[C]IMAGE_ID=\f[R] field of it).
+.TP
+\f[B]\f[CB]WithUnifiedKernelImages=\f[B]\f[R], \f[B]\f[CB]--without-unified-kernel-images\f[B]\f[R]
+If specified, mkosi does not build unified kernel images and instead
+installs kernels with a separate initrd and boot loader config to the
+efi or bootloader partition.
+.TP
+\f[B]\f[CB]HostonlyInitrd=\f[B]\f[R], \f[B]\f[CB]--hostonly-initrd\f[B]\f[R]
+If specified, mkosi will run the tool to create the initrd such that a
+non-generic initrd is created that will only be able to run on the
+system mkosi is run on.
+Currently mkosi uses dracut for all supported distributions except Clear
+Linux and this option translates to enabling dracut\[cq]s hostonly
+option.
+.TP
+\f[B]\f[CB]UsrOnly=\f[B]\f[R], \f[B]\f[CB]--usr-only\f[B]\f[R]
+If specified, \f[C]mkosi\f[R] will only add the \f[C]/usr/\f[R]
+directory tree (instead of the whole root file system) to the image.
+This is useful for fully stateless systems that come up pristine on
+every single boot, where \f[C]/etc/\f[R] and \f[C]/var/\f[R] are
+populated by \f[C]systemd-tmpfiles\f[R]/\f[C]systemd-sysusers\f[R] and
+related calls, or systems that are originally shipped without a root
+file system, but where \f[C]systemd-repart\f[R] adds one on the first
+boot.
+.TP
+\f[B]\f[CB]SplitArtifacts=\f[B]\f[R], \f[B]\f[CB]--split-artifacts\f[B]\f[R]
+If specified and building an image with a partition table, also write
+out the root file system partition, its Verity partition (if configured)
+and the generated unified kernel (if configured) into separate output
+files.
+This is useful in A/B update scenarios where an existing disk image
+shall be augmented with a new version of a root or \f[C]/usr\f[R]
+partition along with its Verity partition and unified kernel.
+.TP
+\f[B]\f[CB]NoChown=\f[B]\f[R], \f[B]\f[CB]--no-chown\f[B]\f[R]
+By default, if \f[C]mkosi\f[R] is run inside a \f[C]sudo\f[R]
+environment all generated artifacts have their UNIX user/group ownership
+changed to the user which invoked \f[C]sudo\f[R].
+With this option this may be turned off and all generated files are
+owned by \f[C]root\f[R].
+.TP
+\f[B]\f[CB]TarStripSELinuxContext=\f[B]\f[R], \f[B]\f[CB]--tar-strip-selinux-context\f[B]\f[R]
+If running on a SELinux-enabled system (Fedora Linux, CentOS, Rocky
+Linux, Alma Linux), files inside the container are tagged with SELinux
+context extended attributes (\f[C]xattrs\f[R]), which may interfere with
+host SELinux rules in building or further container import stages.
+This option strips SELinux context attributes from the resulting tar
+archive.
+.TP
+\f[B]\f[CB]MachineID=\f[B]\f[R], \f[B]\f[CB]--machine-id\f[B]\f[R]
+Set the machine\[cq]s ID to the specified value.
+If unused, a random ID will be used while building the image and the
+final image will be shipped without a machine ID.
+.SS [Content] Section
+.TP
+\f[B]\f[CB]BasePackages=\f[B]\f[R], \f[B]\f[CB]--base-packages\f[B]\f[R]
+Takes a boolean or the special value \f[C]conditional\f[R].
+If true, automatically install packages to ensure basic functionality,
+as appropriate for the given image type.
+For example, \f[C]systemd\f[R] is always included,
+\f[C]systemd-udev\f[R] and \f[C]dracut\f[R] if the image is bootable,
+and so on.
+If false, only packages specified with \f[C]Packages=\f[R] will be
+installed.
+If \f[C]conditional\f[R], the list of packages to install will be
+extended with boolean dependencies (c.f.
+https://rpm.org/user_doc/boolean_dependencies.html), to install specific
+packages when \f[I]other\f[R] packages are in the list.
+For example, \f[C]systemd-udev\f[R] may be automatically included if the
+image is bootable and \f[C]systemd\f[R] is installed.
+With this, various \[lq]base\[rq] packages still need to be specified if
+they should be included, but the corresponding \[lq]extension\[rq]
+packages will be added automatically when appropriate.
+This feature depends on support in the package manager, so it is not
+implemented for all distributions.
+.TP
+\f[B]\f[CB]Packages=\f[B]\f[R], \f[B]\f[CB]--package=\f[B]\f[R], \f[B]\f[CB]-p\f[B]\f[R]
+Install the specified distribution packages (i.e.\ RPM, DEB, \&...) in
+the image.
+Takes a comma separated list of package specifications.
+This option may be used multiple times in which case the specified
+package lists are combined.
+Packages specified this way will be installed both in the development
+and the final image.
+Use \f[C]BuildPackages=\f[R] to specify packages that shall only be used
+for the image generated in the build image, but that shall not appear in
+the final image.
+The types and syntax of \[lq]package specifications\[rq] that are
+allowed depend on the package installer (e.g.\ \f[C]dnf\f[R] or
+\f[C]yum\f[R] for \f[C]rpm\f[R]-based distros or \f[C]apt\f[R] for
+\f[C]deb\f[R]-based distros), but may include package names, package
+names with version and/or architecture, package name globs, paths to
+packages in the file system, package groups, and virtual provides,
+including file paths.
+To remove a package e.g.\ added by a \f[C]mkosi.default\f[R]
+configuration file prepend the package name with \f[C]!\f[R].
+For example -p \[lq]!apache2\[rq] would remove the apache2 package.
+To replace the apache2 package by the httpd package just add -p
+\[lq]!apache2,httpd\[rq] to the command line arguments.
+To remove all packages use \[lq]!*\[rq].
+Example: when using an distro that uses \f[C]dnf\f[R],
+\f[C]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R]
+would install the \f[C]meson\f[R] package (in the latest version), the
+32-bit version of the \f[C]libfdisk-devel\f[R] package, all available
+packages that start with the \f[C]git-\f[R] prefix, a \f[C]systemd\f[R]
+rpm from the local file system, one of the packages that provides
+\f[C]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq]
+group, and the package that contains the \f[C]mypy\f[R] python module.
+.TP
+\f[B]\f[CB]WithDocs=\f[B]\f[R], \f[B]\f[CB]--with-docs\f[B]\f[R]
+Include documentation in the image built.
+By default if the underlying distribution package manager supports it
+documentation is not included in the image built.
+The \f[C]$WITH_DOCS\f[R] environment variable passed to the
+\f[C]mkosi.build\f[R] script indicates whether this option was used or
+not.
+.TP
+\f[B]\f[CB]WithTests=\f[B]\f[R], \f[B]\f[CB]--without-tests\f[B]\f[R], \f[B]\f[CB]-T\f[B]\f[R]
+If set to false (or when the command-line option is used), the
+\f[C]$WITH_TESTS\f[R] environment variable is set to \f[C]0\f[R] when
+the \f[C]mkosi.build\f[R] script is invoked.
+This is supposed to be used by the build script to bypass any unit or
+integration tests that are normally run during the source build process.
+Note that this option has no effect unless the \f[C]mkosi.build\f[R]
+build script honors it.
+.TP
+\f[B]\f[CB]Cache=\f[B]\f[R], \f[B]\f[CB]--cache=\f[B]\f[R]
+Takes a path to a directory to use as package cache for the distribution
+package manager used.
+If this option is not used, but a \f[C]mkosi.cache/\f[R] directory is
+found in the local directory it is automatically used for this purpose.
+The directory configured this way is mounted into both the development
+and the final image while the package manager is running.
+.TP
+\f[B]\f[CB]SkeletonTree=\f[B]\f[R], \f[B]\f[CB]--skeleton-tree=\f[B]\f[R]
+Takes a path to a directory to copy into the OS tree before invoking the
+package manager.
+Use this to insert files and directories into the OS tree before the
+package manager installs any packages.
+If this option is not used, but the \f[C]mkosi.skeleton/\f[R] directory
+is found in the local directory it is automatically used for this
+purpose (also see the \[lq]Files\[rq] section below).
+Instead of a directory, a tar file may be provided.
+In this case it is unpacked into the OS tree before the package manager
+is invoked.
+This mode of operation allows setting permissions and file ownership
+explicitly, in particular for projects stored in a version control
+system such as \f[C]git\f[R] which retain full file ownership and access
+mode metadata for committed files.
+If the tar file \f[C]mkosi.skeleton.tar\f[R] is found in the local
+directory it will be automatically used for this purpose.
+.TP
+\f[B]\f[CB]ExtraTree=\f[B]\f[R], \f[B]\f[CB]--extra-tree=\f[B]\f[R]
+Takes a path to a directory to copy on top of the OS tree the package
+manager generated.
+Use this to override any default configuration files shipped with the
+distribution.
+If this option is not used, but the \f[C]mkosi.extra/\f[R] directory is
+found in the local directory it is automatically used for this purpose
+(also see the \[lq]Files\[rq] section below).
+As with the skeleton tree logic above, instead of a directory, a tar
+file may be provided too.
+\f[C]mkosi.skeleton.tar\f[R] will be automatically used if found in the
+local directory.
+.TP
+\f[B]\f[CB]CleanPackageMetadata=\f[B]\f[R], \f[B]\f[CB]--clean-package-metadata=\f[B]\f[R]
+Enable/disable removal of package manager databases, caches, and logs at
+the end of installation.
+Can be specified as true, false, or \[lq]\f[C]auto\f[R]\[rq] (the
+default).
+With \[lq]\f[C]auto\f[R]\[rq], files will be removed if the respective
+package manager executable is \f[I]not\f[R] present at the end of the
+installation.
+.TP
+\f[B]\f[CB]RemoveFiles=\f[B]\f[R], \f[B]\f[CB]--remove-files=\f[B]\f[R]
+Takes a comma-separated list of globs.
+Files in the image matching the globs will be purged at the end.
+.TP
+\f[B]\f[CB]RemovePackages=\f[B]\f[R], \f[B]\f[CB]--remove-package=\f[B]\f[R]
+Takes a comma-separated list of package specifications for removal, in
+the same format as \f[C]Packages=\f[R].
+The removal will be performed as one of the last steps.
+This step is skipped if \f[C]CleanPackageMetadata=no\f[R] is used.
+This option is currently only implemented for distributions using
+\f[C]dnf\f[R].
+.TP
+\f[B]\f[CB]Environment=\f[B]\f[R], \f[B]\f[CB]--environment=\f[B]\f[R]
+Adds variables to the environment that the
+build/prepare/postinstall/finalize scripts are executed with.
+Takes a space-separated list of variable assignments or just variable
+names.
+In the latter case, the values of those variables will be passed through
+from the environment in which \f[C]mkosi\f[R] was invoked.
+This option may be specified more than once, in which case all listed
+variables will be set.
+If the same variable is set twice, the later setting overrides the
+earlier one.
+.TP
+\f[B]\f[CB]BuildSources=\f[B]\f[R], \f[B]\f[CB]--build-sources=\f[B]\f[R]
+Takes a path to a source tree to copy into the development image, if the
+build script is used.
+This only applies if a build script is used, and defaults to the local
+directory.
+Use \f[C]SourceFileTransfer=\f[R] to configure how the files are
+transferred from the host to the container image.
+.TP
+\f[B]\f[CB]BuildDirectory=\f[B]\f[R], \f[B]\f[CB]--build-dir=\f[B]\f[R]
+Takes a path of a directory to use as build directory for build systems
+that support out-of-tree builds (such as Meson).
+The directory used this way is shared between repeated builds, and
+allows the build system to reuse artifacts (such as object files,
+executable, \&...) generated on previous invocations.
+This directory is mounted into the development image when the build
+script is invoked.
+The build script can find the path to this directory in the
+\f[C]$BUILDDIR\f[R] environment variable.
+If this option is not specified, but a directory
+\f[C]mkosi.builddir/\f[R] exists in the local directory it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]IncludeDirectory=\f[B]\f[R], \f[B]\f[CB]--include-directory=\f[B]\f[R]
+Takes a path of a directory to use as the include directory.
+This directory is mounted at \f[C]/usr/include\f[R] when building the
+build image and running the build script.
+This means all include files installed to \f[C]/usr/include\f[R] will be
+stored in this directory.
+This is useful to make include files available on the host system for
+use by language servers to provide code completion.
+If this option is not specified, but a directory
+\f[C]mkosi.includedir/\f[R] exists in the local directory, it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]InstallDirectory=\f[B]\f[R], \f[B]\f[CB]--install-directory=\f[B]\f[R]
+Takes a path of a directory to use as the install directory.
+The directory used this way is shared between builds and allows the
+build system to not have to reinstall files that were already installed
+by a previous build and didn\[cq]t change.
+The build script can find the path to this directory in the
+\f[C]$DESTDIR\f[R] environment variable.
+If this option is not specified, but a directory
+\f[C]mkosi.installdir\f[R] exists in the local directory, it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]BuildPackages=\f[B]\f[R], \f[B]\f[CB]--build-package=\f[B]\f[R]
+Similar to \f[C]Packages=\f[R], but configures packages to install only
+in the first phase of the build, into the development image.
+This option should be used to list packages containing header files,
+compilers, build systems, linkers and other build tools the
+\f[C]mkosi.build\f[R] script requires to operate.
+Note that packages listed here are only included in the image created
+during the first phase of the build, and are absent in the final image.
+Use \f[C]Packages=\f[R] to list packages that shall be included in both.
+Packages are appended to the list.
+Packages prefixed with \[lq]!\[rq] are removed from the list.
+\[lq]!*\[rq] removes all packages from the list.
+.TP
+\f[B]\f[CB]Password=\f[B]\f[R], \f[B]\f[CB]--password=\f[B]\f[R]
+Set the password of the \f[C]root\f[R] user.
+By default the \f[C]root\f[R] account is locked.
+If this option is not used, but a file \f[C]mkosi.rootpw\f[R] exists in
+the local directory, the root password is automatically read from it.
+.TP
+\f[B]\f[CB]PasswordIsHashed=\f[B]\f[R], \f[B]\f[CB]--password-is-hashed\f[B]\f[R]
+Indicate that the password supplied for the \f[C]root\f[R] user has
+already been hashed, so that the string supplied with
+\f[C]Password=\f[R] or \f[C]mkosi.rootpw\f[R] will be written to
+\f[C]/etc/shadow\f[R] literally.
+.TP
+\f[B]\f[CB]Autologin=\f[B]\f[R], \f[B]\f[CB]--autologin\f[B]\f[R]
+Enable autologin for the \f[C]root\f[R] user on \f[C]/dev/pts/0\f[R]
+(nspawn), \f[C]/dev/tty1\f[R] (QEMU) and \f[C]/dev/ttyS0\f[R] (QEMU with
+\f[C]QemuHeadless=yes\f[R]) by patching \f[C]/etc/pam.d/login\f[R].
+.TP
+\f[B]\f[CB]SkipFinalPhase=\f[B]\f[R], \f[B]\f[CB]--skip-final-phase=\f[B]\f[R]
+Causes the (second) final image build stage to be skipped.
+This is useful in combination with a build script, for when you care
+about the artifacts that were created locally in \f[C]$BUILDDIR\f[R],
+but ultimately plan to discard the final image.
+.TP
+\f[B]\f[CB]BuildScript=\f[B]\f[R], \f[B]\f[CB]--build-script=\f[B]\f[R]
+Takes a path to an executable that is used as build script for this
+image.
+If this option is used the build process will be two-phased instead of
+single-phased.
+The specified script is copied onto the development image and executed
+inside an \f[C]systemd-nspawn\f[R] container environment.
+If this option is not used, but the \f[C]mkosi.build\f[R] file found in
+the local directory it is automatically used for this purpose (also see
+the \[lq]Files\[rq] section below).
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]PrepareScript=\f[B]\f[R], \f[B]\f[CB]--prepare-script=\f[B]\f[R]
+Takes a path to an executable that is invoked inside the image right
+after installing the software packages.
+It is the last step before the image is cached (if incremental mode is
+enabled).
+This script is invoked inside a \f[C]systemd-nspawn\f[R] container
+environment, and thus does not have access to host resources.
+If this option is not used, but an executable script
+\f[C]mkosi.prepare\f[R] is found in the local directory, it is
+automatically used for this purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]PostInstallationScript=\f[B]\f[R], \f[B]\f[CB]--postinst-script=\f[B]\f[R]
+Takes a path to an executable that is invoked inside the final image
+right after copying in the build artifacts generated in the first phase
+of the build.
+This script is invoked inside a \f[C]systemd-nspawn\f[R] container
+environment, and thus does not have access to host resources.
+If this option is not used, but an executable \f[C]mkosi.postinst\f[R]
+is found in the local directory, it is automatically used for this
+purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]FinalizeScript=\f[B]\f[R], \f[B]\f[CB]--finalize-script=\f[B]\f[R]
+Takes a path to an executable that is invoked outside the final image
+right after copying in the build artifacts generated in the first phase
+of the build, and after having executed the \f[C]mkosi.postinst\f[R]
+script (see \f[C]PostInstallationScript=\f[R]).
+This script is invoked directly in the host environment, and hence has
+full access to the host\[cq]s resources.
+If this option is not used, but an executable \f[C]mkosi.finalize\f[R]
+is found in the local directory, it is automatically used for this
+purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]SourceFileTransfer=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer=\f[B]\f[R]
+Configures how the source file tree (as configured with
+\f[C]BuildSources=\f[R]) is transferred into the container image during
+the first phase of the build.
+Takes one of \f[C]copy-all\f[R] (to copy all files from the source
+tree), \f[C]copy-git-cached\f[R] (to copy only those files
+\f[C]git ls-files --cached\f[R] lists), \f[C]copy-git-others\f[R] (to
+copy only those files \f[C]git ls-files --others\f[R] lists),
+\f[C]mount\f[R] to bind mount the source tree directly.
+Defaults to \f[C]copy-git-cached\f[R] if a \f[C]git\f[R] source tree is
+detected, otherwise \f[C]copy-all\f[R].
+When you specify \f[C]copy-git-more\f[R], it is the same as
+\f[C]copy-git-cached\f[R], except it also includes the \f[C].git/\f[R]
+directory.
+.TP
+\f[B]\f[CB]SourceFileTransferFinal=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer-final=\f[B]\f[R]
+Same as \f[C]SourceFileTransfer=\f[R], but for the final image instead
+of the build image.
+Takes the same values as \f[C]SourceFileFransfer=\f[R] except
+\f[C]mount\f[R].
+By default, sources are not copied into the final image.
+.TP
+\f[B]\f[CB]SourceResolveSymlinks=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks\f[B]\f[R]
+If given, any symbolic links in the source file tree are resolved and
+the file contents are copied to the build image.
+If not given, they are left as symbolic links.
+This only applies if \f[C]SourceFileTransfer=\f[R] is
+\f[C]copy-all\f[R].
+Defaults to leaving them as symbolic links.
+.TP
+\f[B]\f[CB]SourceResolveSymlinksFinal=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks-final\f[B]\f[R]
+Same as \f[C]SourceResolveSymlinks=\f[R], but for the final image
+instead of the build image.
+.TP
+\f[B]\f[CB]WithNetwork=\f[B]\f[R], \f[B]\f[CB]--with-network\f[B]\f[R]
+When true, enables network connectivity while the build script
+\f[C]mkosi.build\f[R] is invoked.
+By default, the build script runs with networking turned off.
+The \f[C]$WITH_NETWORK\f[R] environment variable is passed to the
+\f[C]mkosi.build\f[R] build script indicating whether the build is done
+with or without network.
+If specified as \f[C]never\f[R], the package manager is instructed not
+to contact the network for updating package data.
+This provides a minimal level of reproducibility, as long as the package
+data cache is already fully populated.
+.TP
+\f[B]\f[CB]Settings=\f[B]\f[R], \f[B]\f[CB]--settings=\f[B]\f[R]
+Specifies a \f[C].nspawn\f[R] settings file for \f[C]systemd-nspawn\f[R]
+to use in the \f[C]boot\f[R] and \f[C]shell\f[R] verbs, and to place
+next to the generated image file.
+This is useful to configure the \f[C]systemd-nspawn\f[R] environment
+when the image is run.
+If this setting is not used but an \f[C]mkosi.nspawn\f[R] file found in
+the local directory it is automatically used for this purpose.
+.SS [Partitions] Section
+.TP
+\f[B]\f[CB]BaseImage=\f[B]\f[R], \f[B]\f[CB]--base-image=\f[B]\f[R]
+Use the specified directory or file system image as the base image, and
+create the output image that consists only of changes from this base.
+The base image is attached as the lower file system in an overlayfs
+structure, and the output filesystem becomes the upper layer, initially
+empty.
+Thus files that are not modified compared to the base image are not
+present in the output image.
+This option may be used to create systemd \[lq]system extensions\[rq] or
+portable services.
+See https://systemd.io/PORTABLE_SERVICES/#extension-images for more
+information.
+.TP
+\f[B]\f[CB]RootSize=\f[B]\f[R], \f[B]\f[CB]--root-size=\f[B]\f[R]
+Takes a size in bytes for the root file system.
+The specified numeric value may be suffixed with \f[C]K\f[R],
+\f[C]M\f[R], \f[C]G\f[R] to indicate kilo-, mega- and gigabytes (all to
+the base of 1024).
+This applies to output formats \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R].
+Defaults to 3G.
+.TP
+\f[B]\f[CB]ESPSize=\f[B]\f[R], \f[B]\f[CB]--esp-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the UEFI System
+Partition (ESP).
+This is only relevant if the \f[C]Bootable=\f[R] option is used to
+generate a bootable image.
+Defaults to 256 MB.
+.TP
+\f[B]\f[CB]SwapSize=\f[B]\f[R], \f[B]\f[CB]--swap-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of a swap partition
+on the image.
+If omitted, no swap partition is created.
+.TP
+\f[B]\f[CB]HomeSize=\f[B]\f[R], \f[B]\f[CB]--home-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/home\f[R] partition.
+If omitted, no separate \f[C]/home\f[R] partition is created.
+.TP
+\f[B]\f[CB]SrvSize=\f[B]\f[R], \f[B]\f[CB]--srv-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/srv\f[R] partition.
+If omitted, no separate \f[C]/srv\f[R] partition is created.
+.SS [Validation] Section
+.TP
+\f[B]\f[CB]Checksum=\f[B]\f[R], \f[B]\f[CB]--checksum\f[B]\f[R]
+Generate a \f[C]SHA256SUMS\f[R] file of all generated artifacts after
+the build is complete.
+.TP
+\f[B]\f[CB]Sign=\f[B]\f[R], \f[B]\f[CB]--sign\f[B]\f[R]
+Sign the generated \f[C]SHA256SUMS\f[R] using \f[C]gpg\f[R] after
+completion.
+.TP
+\f[B]\f[CB]Key=\f[B]\f[R], \f[B]\f[CB]--key=\f[B]\f[R]
+Select the \f[C]gpg\f[R] key to use for signing \f[C]SHA256SUMS\f[R].
+This key must be already present in the \f[C]gpg\f[R] keyring.
+.TP
+\f[B]\f[CB]BMap=\f[B]\f[R], \f[B]\f[CB]--bmap\f[B]\f[R]
+Generate a \f[C]bmap\f[R] file for usage with \f[C]bmaptool\f[R] from
+the generated image file.
+.SS [Host] Section
+.TP
+\f[B]\f[CB]ExtraSearchPaths=\f[B]\f[R], \f[B]\f[CB]--extra-search-paths=\f[B]\f[R]
+List of colon-separated paths to look for tools in, before using the
+regular \f[C]$PATH\f[R] search path.
+.TP
+\f[B]\f[CB]QemuHeadless=\f[B]\f[R], \f[B]\f[CB]--qemu-headless=\f[B]\f[R]
+When used with the \f[C]build\f[R] verb, this option adds
+\f[C]console=ttyS0\f[R] to the image\[cq]s kernel command line and sets
+the terminal type of the serial console in the image to the terminal
+type of the host (more specifically, the value of the \f[C]$TERM\f[R]
+environment variable passed to mkosi).
+This makes sure that all terminal features such as colors and shortcuts
+still work as expected when connecting to the qemu VM over the serial
+console (for example via \f[C]-nographic\f[R]).
+When used with the \f[C]qemu\f[R] verb, this option adds the
+\f[C]-nographic\f[R] option to \f[C]qemu\f[R]\[cq]s command line so qemu
+starts a headless vm and connects to its serial console from the current
+terminal instead of launching the VM in a separate window.
+.TP
+\f[B]\f[CB]QemuSmp=\f[B]\f[R], \f[B]\f[CB]--qemu-smp=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-smp\f[R] argument which controls the number
+of guest\[cq]s CPUs.
+Defaults to \f[C]2\f[R].
+.TP
+\f[B]\f[CB]QemuMem=\f[B]\f[R], \f[B]\f[CB]--qemu-mem=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-m\f[R] argument which controls the amount of
+guest\[cq]s RAM.
+Defaults to \f[C]1G\f[R].
+.TP
+\f[B]\f[CB]QemuKvm=\f[B]\f[R], \f[B]\f[CB]--qemu-kvm=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this option specifies whether
+QEMU should use KVM acceleration.
+Defaults to yes if the host machine supports KVM acceleration, no
+otherwise.
+.TP
+\f[B]\f[CB]NspawnKeepUnit=\f[B]\f[R], \f[B]\f[CB]--nspawn-keep-unit\f[B]\f[R]
+When used, this option instructs underlying calls of systemd-nspawn to
+use the current unit scope, instead of creating a dedicated transcient
+scope unit for the containers.
+This option should be used when mkosi is run by a service unit.
+.TP
+\f[B]\f[CB]Netdev=\f[B]\f[R], \f[B]\f[CB]--netdev\f[B]\f[R]
+When used with the boot or qemu verbs, this option creates a virtual
+ethernet link between the host and the container/VM.
+The host interface is automatically picked up by systemd-networkd as
+documented in systemd-nspawn\[cq]s man page:
+https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-n
+.TP
+\f[B]\f[CB]Ephemeral=\f[B]\f[R], \f[B]\f[CB]--ephemeral\f[B]\f[R]
+When used with the \f[C]shell\f[R], \f[C]boot\f[R], or \f[C]qemu\f[R]
+verbs, this option runs the specified verb on a temporary snapshot of
+the output image that is removed immediately when the container
+terminates.
+Taking the temporary snapshot is more efficient on file systems that
+support subvolume snapshots or `reflinks' natively (\[lq]btrfs\[rq] or
+new \[lq]xfs\[rq]) than on more traditional file systems that do not
+(\[lq]ext4\[rq]).
+.TP
+\f[B]\f[CB]Ssh=\f[B]\f[R], \f[B]\f[CB]--ssh\f[B]\f[R]
+If specified, installs and enables \f[C]sshd\f[R] in the final image and
+generates a SSH keypair and adds the public key to root\[cq]s
+\f[C]authorized_keys\f[R] in the final image.
+The private key is stored in mkosi\[cq]s output directory.
+When building with this option and running the image using
+\f[C]mkosi boot\f[R] or \f[C]mkosi qemu\f[R], the \f[C]mkosi ssh\f[R]
+command can be used to connect to the container/VM via SSH.
+.TP
+\f[B]\f[CB]SshKey=\f[B]\f[R], \f[B]\f[CB]--ssh-key=\f[B]\f[R]
+If specified, use the given private key when connecting to the guest
+machine via \f[C]mkosi ssh\f[R].
+This requires the public key counterpart to be present in the same
+location, suffixed with \f[C].pub\f[R] (as done by
+\f[C]ssh-keygen\f[R]).
+If this option is not present, \f[C]mkosi\f[R] generates a new key pair
+automatically.
+.TP
+\f[B]\f[CB]SshAgent=\f[B]\f[R], \f[B]\f[CB]--ssh-agent=\f[B]\f[R]
+If specified as a path, use the given socket to connect to the ssh agent
+when building an image and when connecting via \f[C]mkosi ssh\f[R]
+instead of hard-coding a key.
+If specified as \f[C]true\f[R], \f[C]$SSH_AUTH_SOCK\f[R] will be parsed
+instead (hint: use \f[C]sudo\f[R] with \f[C]-E\f[R]).
+The keys listed by \f[C]ssh-add -L\f[R] will be installed as authorized
+keys in the built image.
+The \f[C]ssh\f[R] invocation done by \f[C]mkosi ssh\f[R] will inherit
+\f[C]$SSH_AUTH_SOCK\f[R] for authentication purposes.
+.TP
+\f[B]\f[CB]SshPort=\f[B]\f[R], \f[B]\f[CB]--ssh-port=\f[B]\f[R]
+In the image, sshd will be configured to listen on this port.
+\f[C]mkosi ssh\f[R] will connect to this port.
+.TP
+\f[B]\f[CB]SshTimeout=\f[B]\f[R], \f[B]\f[CB]--ssh-timeout=\f[B]\f[R]
+When used with the \f[C]ssh\f[R] verb, \f[C]mkosi\f[R] will attempt to
+retry the SSH connection up to given timeout (in seconds) in case it
+fails.
+This option is useful mainly in scripted environments where the
+\f[C]qemu\f[R] and \f[C]ssh\f[R] verbs are used in a quick succession
+and the virtual device might not get enough time to configure itself.
+.SS Commandline-only Options
+.PP
+Those settings cannot be configured in the configuration files.
+.TP
+\f[B]\f[CB]--directory=\f[B]\f[R], \f[B]\f[CB]-C\f[B]\f[R]
+Takes a path to a directory.
+\f[C]mkosi\f[R] switches to this directory before doing anything.
+Note that the various \f[C]mkosi.*\f[R] files are searched for only
+after changing to this directory, hence using this option is an
+effective way to build a project located in a specific directory.
+.TP
+\f[B]\f[CB]--default=\f[B]\f[R]
+Loads additional settings from the specified settings file.
+Most command line options may also be configured in a settings file.
+See the table below to see which command line options match which
+settings file option.
+If this option is not used, but a file \f[C]mkosi.default\f[R] is found
+in the local directory it is automatically used for this purpose.
+If a setting is configured both on the command line and in the settings
+file, the command line generally wins, except for options taking lists
+in which case both lists are combined.
+.TP
+\f[B]\f[CB]--all\f[B]\f[R], \f[B]\f[CB]-a\f[B]\f[R]
+Iterate through all files \f[C]mkosi.*\f[R] in the
+\f[C]mkosi.files/\f[R] subdirectory, and build each as if
+\f[C]--default=mkosi.files/mkosi.\&...\f[R] was invoked.
+This is a quick way to build a large number of images in one go.
+Any additional specified command line arguments override the relevant
+options in all files processed this way.
+.TP
+\f[B]\f[CB]--all-directory=\f[B]\f[R]
+If specified, overrides the directory the \f[C]--all\f[R] logic
+described above looks for settings files in.
+If unspecified, defaults to \f[C]mkosi.files/\f[R] in the current
+working directory.
+.TP
+\f[B]\f[CB]--incremental\f[B]\f[R], \f[B]\f[CB]-i\f[B]\f[R]
+Enable incremental build mode.
+This only applies if the two-phase \f[C]mkosi.build\f[R] build script
+logic is used.
+In this mode, a copy of the OS image is created immediately after all OS
+packages are unpacked but before the \f[C]mkosi.build\f[R] script is
+invoked in the development container.
+Similarly, a copy of the final image is created immediately before the
+build artifacts from the \f[C]mkosi.build\f[R] script are copied in.
+On subsequent invocations of \f[C]mkosi\f[R] with the \f[C]-i\f[R]
+switch these cached images may be used to skip the OS package unpacking,
+thus drastically speeding up repetitive build times.
+Note that when this is used and a pair of cached incremental images
+exists they are not automatically regenerated, even if options such as
+\f[C]Packages=\f[R] are modified.
+In order to force rebuilding of these cached images, combine
+\f[C]-i\f[R] with \f[C]-ff\f[R] to ensure cached images are first
+removed and then re-created.
+.TP
+\f[B]\f[CB]--debug=\f[B]\f[R]
+Enable additional debugging output.
+Takes a comma-separated list of arguments specifying the area of
+interest.
+Pass any invalid value (e.g.\ empty) to list currently accepted values.
+.TP
+\f[B]\f[CB]--version\f[B]\f[R]
+Show package version.
+.TP
+\f[B]\f[CB]--help\f[B]\f[R], \f[B]\f[CB]-h\f[B]\f[R]
+Show brief usage information.
+.TP
+\f[B]\f[CB]--auto-bump\f[B]\f[R], \f[B]\f[CB]-B\f[B]\f[R]
+If specified, after each successful build the the version is bumped in a
+fashion equivalent to the \f[C]bump\f[R] verb, in preparation for the
+next build.
+This is useful for simple, linear version management: each build in a
+series will have a version number one higher then the previous one.
+.SS Supported distributions
+.PP
+Images may be created containing installations of the following
+operating systems:
+.IP \[bu] 2
+\f[I]Fedora Linux\f[R]
+.IP \[bu] 2
+\f[I]Debian\f[R]
+.IP \[bu] 2
+\f[I]Ubuntu\f[R]
+.IP \[bu] 2
+\f[I]Arch Linux\f[R]
+.IP \[bu] 2
+\f[I]openSUSE\f[R]
+.IP \[bu] 2
+\f[I]Mageia\f[R]
+.IP \[bu] 2
+\f[I]CentOS\f[R]
+.IP \[bu] 2
+\f[I]Clear Linux\f[R]
+.IP \[bu] 2
+\f[I]Photon\f[R]
+.IP \[bu] 2
+\f[I]OpenMandriva\f[R]
+.IP \[bu] 2
+\f[I]Rocky Linux\f[R]
+.IP \[bu] 2
+\f[I]Alma Linux\f[R]
+.IP \[bu] 2
+\f[I]Gentoo\f[R]
+.PP
+In theory, any distribution may be used on the host for building images
+containing any other distribution, as long as the necessary tools are
+available.
+Specifically, any distribution that packages \f[C]debootstrap\f[R] may
+be used to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] images.
+Any distribution that packages \f[C]dnf\f[R] may be used to build
+\f[I]Fedora Linux\f[R], \f[I]Mageia\f[R] or \f[I]OpenMandriva\f[R]
+images.
+Any distro that packages \f[C]pacstrap\f[R] may be used to build
+\f[I]Arch Linux\f[R] images.
+Any distribution that packages \f[C]zypper\f[R] may be used to build
+\f[I]openSUSE\f[R] images.
+Any distribution that packages \f[C]yum\f[R] (or the newer replacement
+\f[C]dnf\f[R]) may be used to build \f[I]CentOS\f[R], \f[I]Rocky
+Linux\f[R], or \f[I]Alma Linux\f[R] images.
+Any distribution that packages \f[C]emerge\f[R] may be used to build
+\f[I]Gentoo\f[R] images.
+.PP
+Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of
+Fedora 28.
+.SS Compatibility
+.PP
+Legacy concepts are avoided: generated images use \f[I]GPT\f[R] disk
+labels (and no \f[I]MBR\f[R] labels), and only systemd-based images may
+be generated.
+.PP
+All generated \f[I]GPT\f[R] disk images may be booted in a local
+container directly with:
+.IP
+.nf
+\f[C]
+systemd-nspawn -bi image.raw
+\f[R]
+.fi
+.PP
+Additionally, bootable \f[I]GPT\f[R] disk images (as created with the
+\f[C]--bootable\f[R] flag) work when booted directly by \f[I]EFI\f[R]
+and \f[I]BIOS\f[R] systems, for example in \f[I]KVM\f[R] via:
+.IP
+.nf
+\f[C]
+qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
+\f[R]
+.fi
+.PP
+\f[I]EFI\f[R] bootable \f[I]GPT\f[R] images are larger than plain
+\f[I]GPT\f[R] images, as they additionally carry an \f[I]EFI\f[R] system
+partition containing a boot loader, as well as a kernel, kernel modules,
+udev and more.
+.PP
+All directory or btrfs subvolume images may be booted directly with:
+.IP
+.nf
+\f[C]
+systemd-nspawn -bD image
+\f[R]
+.fi
+.SH Files
+.PP
+To make it easy to build images for development versions of your
+projects, mkosi can read configuration data from the local directory,
+under the assumption that it is invoked from a \f[I]source\f[R] tree.
+Specifically, the following files are used if they exist in the local
+directory:
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.default\f[B]\f[R] file provides the default
+configuration for the image building process.
+For example, it may specify the distribution to use (\f[C]fedora\f[R],
+\f[C]ubuntu\f[R], \f[C]debian\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R],
+\f[C]mageia\f[R], \f[C]openmandriva\f[R], \f[C]gentoo\f[R]) for the
+image, or additional distribution packages to install.
+Note that all options encoded in this configuration file may also be set
+on the command line, and this file is hence little more than a way to
+make sure invoking \f[C]mkosi\f[R] without further parameters in your
+\f[I]source\f[R] tree is enough to get the right image of your choice
+set up.
+.RS 2
+.PP
+Additionally, if a \f[I]\f[CI]mkosi.default.d/\f[I]\f[R] directory
+exists, each file in it is loaded in the same manner adding/overriding
+the values specified in \f[C]mkosi.default\f[R].
+If \f[C]mkosi.default.d/\f[R] contains a directory named after the
+distribution being built, each file in that directory is also processed.
+.PP
+The file format is inspired by Windows \f[C].ini\f[R] files and supports
+multi-line assignments: any line with initial whitespace is considered a
+continuation line of the line before.
+Command-line arguments, as shown in the help description, have to be
+included in a configuration block (e.g.\ \[lq]\f[C][Content]\f[R]\[rq])
+corresponding to the argument group (e.g.\ \[lq]\f[C]Content\f[R]\[rq]),
+and the argument gets converted as follows:
+\[lq]\f[C]--with-network\f[R]\[rq] becomes
+\[lq]\f[C]WithNetwork=yes\f[R]\[rq].
+For further details see the table above.
+.RE
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.skeleton/\f[B]\f[R] directory or
+\f[B]\f[CB]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert
+files into the image.
+The files are copied \f[I]before\f[R] the distribution packages are
+installed into the image.
+This allows creation of files that need to be provided early, for
+example to configure the package manager or set systemd presets.
+.RS 2
+.PP
+When using the directory, file ownership is not preserved: all files
+copied will be owned by root.
+To preserve ownership, use a tar archive.
+.RE
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.extra/\f[B]\f[R] directory or
+\f[B]\f[CB]mkosi.extra.tar\f[B]\f[R] archive may be used to insert
+additional files into the image, on top of what the distribution
+includes in its packages.
+They are similar to \f[C]mkosi.skeleton/\f[R] and
+\f[C]mkosi.skeleton.tar\f[R], but the files are copied into the
+directory tree of the image \f[I]after\f[R] the OS was installed.
+.RS 2
+.PP
+When using the directory, file ownership is not preserved: all files
+copied will be owned by root.
+To preserve ownership, use a tar archive.
+.RE
+.IP \[bu] 2
+\f[B]\f[CB]mkosi.build\f[B]\f[R] may be an executable script.
+If it exists, the image will be built twice: the first iteration will be
+the \f[I]development\f[R] image, the second iteration will be the
+\f[I]final\f[R] image.
+The \f[I]development\f[R] image is used to build the project in the
+current working directory (the \f[I]source\f[R] tree).
+For that the whole directory is copied into the image, along with the
+\f[C]mkosi.build\f[R] script.
+The script is then invoked inside the image (via
+\f[C]systemd-nspawn\f[R]), with \f[C]$SRCDIR\f[R] pointing to the
+\f[I]source\f[R] tree.
+\f[C]$DESTDIR\f[R] points to a directory where the script should place
+any files generated it would like to end up in the \f[I]final\f[R]
+image.
+Note that \f[C]make\f[R]/\f[C]automake\f[R]/\f[C]meson\f[R] based build
+systems generally honor \f[C]$DESTDIR\f[R], thus making it very natural
+to build \f[I]source\f[R] trees from the build script.
+After the \f[I]development\f[R] image was built and the build script ran
+inside of it, it is removed again.
+After that the \f[I]final\f[R] image is built, without any
+\f[I]source\f[R] tree or build script copied in.
+However, this time the contents of \f[C]$DESTDIR\f[R] are added into the
+image.
+.RS 2
+.PP
+When the source tree is copied into the \f[I]build\f[R] image, all files
+are copied, except for \f[C]mkosi.builddir/\f[R], \f[C]mkosi.cache/\f[R]
+and \f[C]mkosi.output/\f[R].
+That said, \f[C].gitignore\f[R] is respected if the source tree is a
+\f[C]git\f[R] checkout.
+If multiple different images shall be built from the same source tree it
+is essential to exclude their output files from this copy operation, as
+otherwise a version of an image built earlier might be included in a
+later build, which is usually not intended.
+An alternative to excluding these built images via \f[C].gitignore\f[R]
+entries is to use the \f[C]mkosi.output/\f[R] directory, which is an
+easy way to exclude all build artifacts.
+.PP
+The \f[C]$MKOSI_DEFAULT\f[R] environment variable will be set inside of
+this script so that you know which \f[C]mkosi.default\f[R] (if any) was
+passed in.
+.RE
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.prepare\f[B]\f[R] script is invoked directly after
+the software packages are installed, from within the image context, if
+it exists.
+It is once called for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter,
+right before copying the extra tree.
+It is called a second time for the \f[I]final\f[R] image with the
+\[lq]final\[rq] command line parameter.
+This script has network access and may be used to install packages from
+other sources than the distro\[cq]s package manager
+(e.g.\ \f[C]pip\f[R], \f[C]npm\f[R], \&...), after all software packages
+are installed but before the image is cached (if incremental mode is
+enabled).
+This script is executed within \f[C]$SRCDIR\f[R].
+In contrast to a general purpose installation, it is safe to install
+packages to the system (\f[C]pip install\f[R],
+\f[C]npm   install -g\f[R]) instead of in \f[C]$SRCDIR\f[R] itself
+because the build image is only used for a single project and can easily
+be thrown away and rebuilt so there\[cq]s no risk of conflicting
+dependencies and no risk of polluting the host system.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.postinst\f[B]\f[R] script is invoked as the
+penultimate step of preparing an image, from within the image context,
+if it exists.
+It is called first for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter,
+right before invoking the build script.
+It is called a second time for the \f[I]final\f[R] image with the
+\[lq]final\[rq] command line parameter, right before the image is
+considered complete.
+This script may be used to alter the images without any restrictions,
+after all software packages and built sources have been installed.
+Note that this script is executed directly in the image context with the
+final root directory in place, without any
+\f[C]$SRCDIR\f[R]/\f[C]$DESTDIR\f[R] setup.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked
+as last step of preparing an image, from the host system.
+It is once called for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter, as
+the last step before invoking the build script, after the
+\f[C]mkosi.postinst\f[R] script is invoked.
+It is called the second time with the \[lq]final\[rq] command line
+parameter as the last step before the image is considered complete.
+The environment variable \f[C]$BUILDROOT\f[R] points to the root
+directory of the installation image.
+Additional verbs may be added in the future, the script should be
+prepared for that.
+This script may be used to alter the images without any restrictions,
+after all software packages and built sources have been installed.
+This script is more flexible than \f[C]mkosi.postinst\f[R] in two
+regards: it has access to the host file system so it\[cq]s easier to
+copy in additional files or to modify the image based on external
+configuration, and the script is run in the host, so it can be used even
+without emulation even if the image has a foreign architecture.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.mksquashfs-tool\f[B]\f[R] script, if it exists,
+will be called wherever \f[C]mksquashfs\f[R] would be called.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.nspawn\f[B]\f[R] nspawn settings file will be
+copied into the same place as the output image file, if it exists.
+This is useful since nspawn looks for settings files next to image files
+it boots, for additional container runtime settings.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.cache/\f[B]\f[R] directory, if it exists, is
+automatically used as package download cache, in order to speed repeated
+runs of the tool.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.builddir/\f[B]\f[R] directory, if it exists, is
+automatically used as out-of-tree build directory, if the build commands
+in the \f[C]mkosi.build\f[R] script support it.
+Specifically, this directory will be mounted into the build container,
+and the \f[C]$BUILDDIR\f[R] environment variable will be set to it when
+the build script is invoked.
+The build script may then use this directory as build directory, for
+automake-style or ninja-style out-of-tree builds.
+This speeds up builds considerably, in particular when \f[C]mkosi\f[R]
+is used in incremental mode (\f[C]-i\f[R]): not only the disk images,
+but also the build tree is reused between subsequent invocations.
+Note that if this directory does not exist the \f[C]$BUILDDIR\f[R]
+environment variable is not set, and it is up to build script to decide
+whether to do in in-tree or an out-of-tree build, and which build
+directory to use.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is
+automatically used as an out-of-tree include directory for header files.
+Specifically, it will be mounted in the build container at
+\f[C]/usr/include/\f[R] when building the build image and when running
+the build script.
+After building the (cached) build image, this directory will contain all
+the files installed to \f[C]/usr/include\f[R].
+Language servers or other tools can use these files to provide a better
+editing experience for developers working on a project.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is
+automatically used as the install directory.
+Specifically, this directory will be mounted into the container at
+\f[C]/root/dest\f[R] when running the build script.
+After running the build script, the contents of this directory are
+installed into the final image.
+This is useful to cache the install step of the build.
+If used, subsequent builds will only have to reinstall files that have
+changed since the previous build.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.rootpw\f[B]\f[R] file can be used to provide the
+password or hashed password (if \f[C]--password-is-hashed\f[R] is set)
+for the root user of the image.
+The password may optionally be followed by a newline character which is
+implicitly removed.
+The file must have an access mode of 0600 or less.
+If this file does not exist, the distribution\[cq]s default root
+password is set (which usually means access to the root user is
+blocked).
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.passphrase\f[B]\f[R] file provides the passphrase
+to use when LUKS encryption is selected.
+It should contain the passphrase literally, and not end in a newline
+character (i.e.\ in the same format as cryptsetup and
+\f[C]/etc/crypttab\f[R] expect the passphrase files).
+The file must have an access mode of 0600 or less.
+If this file does not exist and encryption is requested, the user is
+queried instead.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.secure-boot.crt\f[B]\f[R] and
+\f[B]\f[CB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509
+certificate and PEM private key to use when UEFI SecureBoot support is
+enabled.
+All EFI binaries included in the image\[cq]s ESP are signed with this
+key, as a late step in the build process.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.output/\f[B]\f[R] directory will be used for all
+build artifacts, if the image output path is not configured (i.e.\ no
+\f[C]--output=\f[R] setting specified), or configured to a filename
+(i.e.\ a path containing no \f[C]/\f[R] character).
+This includes the image itself, the root hash file in case Verity is
+used, the checksum and its signature if that\[cq]s enabled, and the
+nspawn settings file if there is any.
+Note that this directory is not used if the image output path contains
+at least one slash, and has no effect in that case.
+This setting is particularly useful if multiple different images shall
+be built from the same working directory, as otherwise the build result
+of a preceding run might be copied into a build image as part of the
+source tree (see above).
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is
+automatically used as the repository directory for extra repository
+files.
+See the \f[C]RepositoryDirectory\f[R] option for more information.
+.PP
+All these files are optional.
+.PP
+Note that the location of all these files may also be configured during
+invocation via command line switches, and as settings in
+\f[C]mkosi.default\f[R], in case the default settings are not acceptable
+for a project.
+.SH BUILD PHASES
+.PP
+If no build script \f[C]mkosi.build\f[R] (see above) is used the build
+consists of a single phase only: the final image is generated as the
+combination of \f[C]mkosi.skeleton/\f[R] (see above), the unpacked
+distribution packages and \f[C]mkosi.extra/\f[R].
+.PP
+If a build script \f[C]mkosi.build\f[R] is used the build consists of
+two phases: in the the first \f[C]development\f[R] phase an image that
+includes necessary build tools (i.e.\ the combination of
+\f[C]Packages=\f[R] and \f[C]BuildPackages=\f[R] is installed) is
+generated (i.e.\ the combination of \f[C]mkosi.skeleton/\f[R] and
+unpacked distribution packages).
+Into this image the source tree is copied and \f[C]mkosi.build\f[R]
+executed.
+The artifacts the \f[C]mkosi.build\f[R] generates are saved.
+Then, the second \f[C]final\f[R] phase starts: an image that excludes
+the build tools (i.e.\ only \f[C]Packages=\f[R] is installed,
+\f[C]BuildPackages=\f[R] is not) is generated.
+This time the build artifacts saved from the first phase are copied in,
+and \f[C]mkosi.extra\f[R] copied on top, thus generating the final
+image.
+.PP
+The two-phased approach ensures that source tree is executed in a clean
+and comprehensive environment, while at the same the final image remains
+minimal and contains only those packages necessary at runtime, but
+avoiding those necessary at build-time.
+.PP
+Note that only the package cache \f[C]mkosi.cache/\f[R] is shared
+between the two phases.
+The distribution package manager is executed exactly once in each phase,
+always starting from a directory tree that is populated with
+\f[C]mkosi.skeleton\f[R] but nothing else.
+.SH CACHING
+.PP
+\f[C]mkosi\f[R] supports three different caches for speeding up
+repetitive re-building of images.
+Specifically:
+.IP "1." 3
+The package cache of the distribution package manager may be cached
+between builds.
+This is configured with the \f[C]--cache=\f[R] option or the
+\f[C]mkosi.cache/\f[R] directory.
+This form of caching relies on the distribution\[cq]s package manager,
+and caches distribution packages (RPM, DEB, \&...) after they are
+downloaded, but before they are unpacked.
+.IP "2." 3
+If an \f[C]mkosi.build\f[R] script is used, by enabling incremental
+build mode with \f[C]--incremental\f[R], a cached copy of the
+development and final images can be made immediately before the build
+sources are copied in (for the development image) or the artifacts
+generated by \f[C]mkosi.build\f[R] are copied in (in case of the final
+image).
+This form of caching allows bypassing the time-consuming package
+unpacking step of the distribution package managers, but is only
+effective if the list of packages to use remains stable, but the build
+sources and its scripts change regularly.
+Note that this cache requires manual flushing: whenever the package list
+is modified the cached images need to be explicitly removed before the
+next re-build, using the \f[C]-f\f[R] switch.
+.IP "3." 3
+Finally, between multiple builds the build artifact directory may be
+shared, using the \f[C]mkosi.builddir/\f[R] directory.
+This directory allows build systems such as Meson to reuse already
+compiled sources from a previous built, thus speeding up the build
+process of the \f[C]mkosi.build\f[R] build script.
+.PP
+The package cache (i.e.\ the first item above) is unconditionally
+useful.
+The latter two caches only apply to uses of \f[C]mkosi\f[R] with a
+source tree and build script.
+When all three are enabled together turn-around times for complete image
+builds are minimal, as only changed source files need to be recompiled:
+an OS image rebuilt will be almost as quick to build the source tree
+only.
+.SH ENVIRONMENT VARIABLES
+.PP
+The build script \f[C]mkosi.build\f[R] receives the following
+environment variables:
+.IP \[bu] 2
+\f[C]$SRCDIR\f[R] contains the path to the sources to build.
+.IP \[bu] 2
+\f[C]$DESTDIR\f[R] is a directory into which any artifacts generated by
+the build script shall be placed.
+.IP \[bu] 2
+\f[C]$BUILDDIR\f[R] is only defined if \f[C]mkosi.builddir\f[R] and
+points to the build directory to use.
+This is useful for all build systems that support out-of-tree builds to
+reuse already built artifacts from previous runs.
+.IP \[bu] 2
+\f[C]$WITH_DOCS\f[R] is either \f[C]0\f[R] or \f[C]1\f[R] depending on
+whether a build without or with installed documentation was requested
+(\f[C]WithDocs=yes\f[R]).
+The build script should suppress installation of any package
+documentation to \f[C]$DESTDIR\f[R] in case \f[C]$WITH_DOCS\f[R] is set
+to \f[C]0\f[R].
+.IP \[bu] 2
+\f[C]$WITH_TESTS\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
+whether a build without or with running the test suite was requested
+(\f[C]WithTests=no\f[R]).
+The build script should avoid running any unit or integration tests in
+case \f[C]$WITH_TESTS\f[R] is \f[C]0\f[R].
+.IP \[bu] 2
+\f[C]$WITH_NETWORK\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
+whether a build without or with networking is being executed
+(\f[C]WithNetwork=no\f[R]).
+The build script should avoid any network communication in case
+\f[C]$WITH_NETWORK\f[R] is \f[C]0\f[R].
+.SH EXAMPLES
+.PP
+Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as
+\f[C]image.raw\f[R]:
+.IP
+.nf
+\f[C]
+# mkosi --bootable --incremental boot
+\f[R]
+.fi
+.PP
+Create and run a bootable btrfs \f[I]GPT\f[R] image, as
+\f[C]foobar.raw\f[R]:
+.IP
+.nf
+\f[C]
+# mkosi --format gpt_btrfs --bootable -o foobar.raw
+# mkosi --output foobar.raw boot
+# mkosi --output foobar.raw qemu
+\f[R]
+.fi
+.PP
+Create and run a \f[I]Fedora Linux\f[R] image into a plain directory:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --format directory boot
+\f[R]
+.fi
+.PP
+Create a compressed image \f[C]image.raw.xz\f[R] and add a checksum
+file, and install \f[I]SSH\f[R] into it:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --format gpt_squashfs --checksum --compress --package=openssh-clients
+\f[R]
+.fi
+.PP
+Inside the source directory of an \f[C]automake\f[R]-based project,
+configure \f[I]mkosi\f[R] so that simply invoking \f[C]mkosi\f[R]
+without any parameters builds an OS image containing a built version of
+the project in its current state:
+.IP
+.nf
+\f[C]
+# cat >mkosi.default <<EOF
+[Distribution]
+Distribution=fedora
+Release=24
+
+[Output]
+Format=gpt_btrfs
+Bootable=yes
+
+[Content]
+Packages=openssh-clients,httpd
+BuildPackages=make,gcc,libcurl-devel
+EOF
+# cat >mkosi.build <<EOF
+#!/bin/sh
+cd $SRCDIR
+\&./autogen.sh
+\&./configure --prefix=/usr
+make -j \[ga]nproc\[ga]
+make install
+EOF
+# chmod +x mkosi.build
+# mkosi --bootable --incremental boot
+# systemd-nspawn -bi image.raw
+\f[R]
+.fi
+.PP
+To create a \f[I]Fedora Linux\f[R] image with hostname:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --hostname image
+\f[R]
+.fi
+.PP
+Also you could set hostname in configuration file:
+.IP
+.nf
+\f[C]
+# cat mkosi.default
+\&...
+[Output]
+Hostname=image
+\&...
+\f[R]
+.fi
+.SH REQUIREMENTS
+.PP
+mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux,
+Fedora Linux, OpenMandriva, Gentoo.
+It is usually easiest to use the distribution package.
+.PP
+The current version requires systemd 233 (or actually, systemd-nspawn of
+it).
+.PP
+When not using distribution packages make sure to install the necessary
+dependencies.
+For example, on \f[I]Fedora Linux\f[R] you need:
+.IP
+.nf
+\f[C]
+dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
+\f[R]
+.fi
+.PP
+On Debian/Ubuntu it might be necessary to install the
+\f[C]ubuntu-keyring\f[R], \f[C]ubuntu-archive-keyring\f[R] and/or
+\f[C]debian-archive-keyring\f[R] packages explicitly, in addition to
+\f[C]debootstrap\f[R], depending on what kind of distribution images you
+want to build.
+\f[C]debootstrap\f[R] on Debian only pulls in the Debian keyring on its
+own, and the version on Ubuntu only the one from Ubuntu.
+.PP
+Note that the minimum required Python version is 3.7.
+.SH REFERENCES
+.IP \[bu] 2
+Primary mkosi git repository on
+GitHub (https://github.com/systemd/mkosi/)
+.IP \[bu] 2
+mkosi \[em] A Tool for Generating OS
+Images (http://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html)
+introductory blog post by Lennart Poettering
+.IP \[bu] 2
+The mkosi OS generation tool (https://lwn.net/Articles/726655/) story on
+LWN
+.SH SEE ALSO
+.PP
+\f[C]systemd-nspawn(1)\f[R], \f[C]dnf(8)\f[R], \f[C]debootstrap(8)\f[R]
+.SH AUTHORS
+The mkosi Authors.
diff --git a/upstream/mageia-cauldron/man1/mktemp.1 b/upstream/mageia-cauldron/man1/mktemp.1
new file mode 100644
index 00000000..d2f0a4d0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mktemp.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MKTEMP "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+mktemp \- create a temporary file or directory
+.SH SYNOPSIS
+.B mktemp
+[\fI\,OPTION\/\fR]... [\fI\,TEMPLATE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Create a temporary file or directory, safely, and print its name.
+TEMPLATE must contain at least 3 consecutive 'X's in last component.
+If TEMPLATE is not specified, use tmp.XXXXXXXXXX, and \fB\-\-tmpdir\fR is implied.
+Files are created u+rw, and directories u+rwx, minus umask restrictions.
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+create a directory, not a file
+.TP
+\fB\-u\fR, \fB\-\-dry\-run\fR
+do not create anything; merely print a name (unsafe)
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress diagnostics about file/dir\-creation failure
+.TP
+\fB\-\-suffix\fR=\fI\,SUFF\/\fR
+append SUFF to TEMPLATE; SUFF must not contain a slash.
+This option is implied if TEMPLATE does not end in X
+.TP
+\fB\-p\fR DIR, \fB\-\-tmpdir\fR[=\fI\,DIR\/\fR]
+interpret TEMPLATE relative to DIR; if DIR is not
+specified, use $TMPDIR if set, else \fI\,/tmp\/\fP.  With
+this option, TEMPLATE must not be an absolute name;
+unlike with \fB\-t\fR, TEMPLATE may contain slashes, but
+mktemp creates only the final component
+.TP
+\fB\-t\fR
+interpret TEMPLATE as a single file name component,
+relative to a directory: $TMPDIR, if set; else the
+directory specified via \fB\-p\fR; else \fI\,/tmp\/\fP [deprecated]
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Jim Meyering and Eric Blake.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBmkstemp\fP(3), \fBmkdtemp\fP(3), \fBmktemp\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/mktemp>
+.br
+or available locally via: info \(aq(coreutils) mktemp invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mlabel.1 b/upstream/mageia-cauldron/man1/mlabel.1
new file mode 100644
index 00000000..30d85088
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mlabel.1
@@ -0,0 +1,118 @@
+'\" t
+.TH mlabel 1 "21Mar23" mtools-4.0.43
+.SH Name
+mlabel - make an MSDOS volume label
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmlabel\fR command adds a volume label to a disk. Its syntax is:
+.ft I
+.nf
+\&\fR\&\f(CWmlabel\fR [\fR\&\f(CW-vcsn\fR] [\fR\&\f(CW-N\fR \fIserial\fR] \fIdrive\fR:[\fInew_label\fR]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMlabel\fR displays the current volume label, if present. If
+\&\fInew_label\fR is not given, and if neither the \fR\&\f(CWc\fR nor the
+\&\fR\&\f(CWs\fR options are set, it prompts the user for a new volume label.
+To delete an existing volume label, press return at the prompt.
+.PP
+The label is limited to 11 single-byte characters,
+e.g. \fR\&\f(CWName1234567\fR.
+.PP
+Reasonable care is taken to create a valid MS-DOS volume label.  If an
+invalid label is specified, \fR\&\f(CWmlabel\fR changes the label (and
+displays the new label if the verbose mode is set). \fR\&\f(CWMlabel\fR
+returns 0 on success or 1 on failure.
+.PP
+Mlabel supports the following options:
+.TP
+\&\fR\&\f(CWc\fR\ 
+Clears an existing label, without prompting the user
+.TP
+\&\fR\&\f(CWs\fR\ 
+Shows the existing label, without prompting the user.
+.TP
+\&\fR\&\f(CWn\ \fR\ 
+Assigns a new (random) serial number to the disk
+.TP
+\&\fR\&\f(CWN\ \fIserial\fR\&\f(CW\fR\ 
+Sets the supplied serial number. The serial number should be supplied as
+an 8 digit hexadecimal number, without spaces
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mmd.1 b/upstream/mageia-cauldron/man1/mmd.1
new file mode 100644
index 00000000..06bc2daf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mmd.1
@@ -0,0 +1,91 @@
+'\" t
+.TH mmd 1 "21Mar23" mtools-4.0.43
+.SH Name
+mmd - make an MSDOS subdirectory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmmd\fR command is used to make an MS-DOS subdirectory. Its
+syntax is:
+.PP
+\&\fR\&\f(CWmmd\fR [\fR\&\f(CW-D\fR \fIclash_option\fR] \fImsdosdirectory\fR [
+\&\fImsdosdirectories\fR\&... ]
+.PP
+\&\fR\&\f(CWMmd\fR makes a new directory on an MS-DOS file system. An error occurs
+if the directory already exists.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mmount.1 b/upstream/mageia-cauldron/man1/mmount.1
new file mode 100644
index 00000000..d4b83f17
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mmount.1
@@ -0,0 +1,96 @@
+'\" t
+.TH mmount 1 "21Mar23" mtools-4.0.43
+.SH Name
+mmount - mount an MSDOS disk
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmmount\fR command is used to mount an MS-DOS disk. It is only
+available on Linux, as it is only useful if the OS kernel allows
+configuration of the disk geometry. Its syntax is:
+.PP
+\&\fR\&\f(CWmmount\fR \fImsdosdrive\fR [\fImountargs\fR]
+.PP
+\&\fR\&\f(CWMmount\fR
+reads the boot sector of an MS-DOS disk, configures the drive geometry,
+and finally mounts it passing
+\&\fR\&\f(CWmountargs\fR to \fR\&\f(CWmount. \fR
+If no mount arguments are specified, the name of the device is
+used. If the disk is write protected, it is automatically mounted read
+only.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mmove.1 b/upstream/mageia-cauldron/man1/mmove.1
new file mode 100644
index 00000000..b3b82175
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mmove.1
@@ -0,0 +1,99 @@
+'\" t
+.TH mmove 1 "21Mar23" mtools-4.0.43
+.SH Name
+mmove - move or rename an MSDOS file or subdirectory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmmove\fR command is used to move or rename an existing MS-DOS
+file or subdirectory.
+.ft I
+.nf
+\&\fR\&\f(CWmmove\fR [\fR\&\f(CW-v\fR] [\fR\&\f(CW-D\fR \fIclash_option\fR] \fIsourcefile\fR \fItargetfile\fR
+\&\fR\&\f(CWmmove\fR [\fR\&\f(CW-v\fR]  [\fR\&\f(CW-D\fR \fIclash_option\fR] \fIsourcefile\fR [ \fIsourcefiles\fR\&... ] \fItargetdirectory\fR
+.fi
+.ft R
+ 
+\&\fR\&\f(CWMmove\fR moves or renames an existing MS-DOS file or
+subdirectory. Unlike the MS-DOS version of \fR\&\f(CWMOVE\fR, \fR\&\f(CWmmove\fR is
+able to move subdirectories.  Files or directories can only be moved
+within one file system. Data cannot be moved from MS-DOS to Unix or
+vice-versa.  If you omit the drive letter from the target file or
+directory, the same letter as for the source is assumed.  If you omit
+the drive letter from all parameters, drive a: is assumed by default.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/most.1 b/upstream/mageia-cauldron/man1/most.1
new file mode 100644
index 00000000..f4d08fcb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/most.1
@@ -0,0 +1,445 @@
+.\" This manpage has been automatically generated by docbook2man 
+.\" from a DocBook document.  This tool can be found at:
+.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
+.\" Please send any bug reports, improvements, comments, patches, 
+.\" etc. to Steve Cheng <steve@ggi-project.org>.
+.TH "MOST" "1" "30 July 2022" "" ""
+
+.SH NAME
+most \- browse or page through a text file
+.SH SYNOPSIS
+
+\fBmost\fR [ \fB-1\fR ] [ \fB-b\fR ] [ \fB-C\fR ] [ \fB-c\fR ] [ \fB-d\fR ] [ \fB-M\fR ] [ \fB-r\fR ] [ \fB-s\fR ] [ \fB-t\fR ] [ \fB-u\fR ] [ \fB-v\fR ] [ \fB-w\fR ] [ \fB-z\fR ] [ \fB+/\fIstring\fB\fR ] [ \fB+\fIline-number\fB\fR ] [ \fB+d\fR ] [ \fB+s\fR ] [ \fB+u\fR ] [ \fB\fIfile...\fB\fR ]
+
+.SH "DESCRIPTION"
+.PP
+\fBmost\fR is a paging program that displays, one windowful at a time,
+the contents of a file on a terminal.  It pauses after each
+windowful and prints on the window status line the screen the file
+name, current line number, and the percentage of the file so far
+displayed.
+.PP
+Unlike other paging programs, \fBmost\fR is capable of displaying an
+arbitrary number of windows as long as each window occupies at least
+two screen lines.  Each window may contain the same file or a
+different file.  In addition, each window has its own mode.  For
+example, one window may display a file with its lines wrapped while
+another may be truncating the lines. Windows may be `locked'
+together in the sense that if one of the locked windows scrolls, all
+locked windows will scroll.  \fBmost\fR is also capable of ignoring lines
+that are indented beyond a user specified value.  This is useful
+when viewing computer programs to pick out gross features of the
+code.  See the `:o' command for a description of this feature.
+.PP
+In addition to displaying ordinary text files, \fBmost\fR can also
+display binary files as well as files with arbitrary ascii
+characters.  When a file is read into a buffer, \fBmost\fR examines the
+first 32 bytes of the file to determine if the file is a binary file
+and then switches to the appropriate mode.  However, this feature
+may be disabled with the -k option.  See the description of the -b,
+-k, -v, and -t options for further details.
+.PP
+Text files may contain combinations of underscore and backspace
+characters causing a printer to underline or overstrike.  When \fBmost\fR
+recognizes this, it inserts the appropriate escape sequences to
+achieve the desired effect.  In addition, some files cause the
+printer to overstrike some characters by embedding carriage return
+characters in the middle of a line.  When this occurs, \fBmost\fR displays
+the overstruck character with a bold attribute.  This feature
+facilitates the reading of UNIX man pages or a document produced by
+runoff.  In particular, viewing this document with \fBmost\fR should
+illustrate this behavior provided that the underline characters
+have not been stripped.  This may be turned off with the -v option.
+.PP
+By default, lines with more characters than the terminal width are
+not wrapped but are instead truncated. When truncation occurs, this
+is indicated by a `$' in the far right column of the terminal
+screen.  The RIGHT and LEFT arrow keys may be used to view lines
+which extend past the margins of the screen.  The -w option may be
+used to override this feature.  When a window is wrapped, the
+character `\\' will appear at the right edge of the window.
+.PP
+Commands are listed below.
+.SH "COLOR SUPPORT"
+.PP
+\fBmost\fR has supported both 256-color and 24 bit truecolor terminals
+since version 5.2.  Not all terminals are capable of generating
+arbitrary 24 bit colors. If your terminal supports 24 bit colors,
+but \fBmost\fR does not detect it, then set the environment variable
+
+.nf
+     COLORTERM=truecolor
+.fi
+.PP
+to force 24 bit truecolors to be used.
+.PP
+.SH "OPTIONS"
+.TP
+\fB-1\fR
+VT100 mode.  This is meaningful only
+on VMS systems.  This option should be used if the terminal is
+strictly a VT100.  This implies that the terminal does not have the
+ability to delete and insert multiple lines.  VT102s and above have
+this ability. 
+.TP
+\fB-b\fR
+Binary mode.  Use this switch when
+you want to view files containing 8 bit characters.  \fBmost\fR will
+display the file 16 bytes per line in hexadecimal notation. A
+typical line looks like:
+
+.nf
+   01000000 40001575 9C23A020 4000168D     ....@..u.#. @...
+.fi
+
+When used with the -v option, the same line looks like:
+
+.nf
+   ^A^@^@^@  @^@^U u 9C #A0    @^@^V8D     ....@..u.#. @...
+.fi
+.TP
+\fB-C\fR
+Disable color support. 
+.TP
+\fB-c\fR
+Make searches case-sensitive 
+.TP
+\fB-d\fR
+Omit the backslash mark used to denote a wrapped line. 
+.TP
+\fB-M\fR
+Disable the use of mmap. 
+.TP
+\fB-r\fR
+Default to using regexp searches 
+.TP
+\fB-s\fR
+Squeeze-mode.  Replace multiple blank
+lines with a single blank line. 
+.TP
+\fB-t\fR
+Display tabs as ^I.  If this option
+is immediately followed by an integer, the integer sets the tab
+width, e.g., -t4 
+.TP
+\fB-u\fR
+Disable UTF-8 mode even if the
+locale dictates it 
+.TP
+\fB+u\fR
+Force UTF-8 mode.  By default \fBmost\fR
+will use the current locale to determine if UTF-8 mode should be
+used.  The +u and -u switches allow the behavior to be overridden 
+.TP
+\fB-v\fR
+Display control characters as in
+`^A' for control A.  Normally \fBmost\fR does not interpret control
+characters. 
+.TP
+\fB-w\fR
+Wrap lines 
+.TP
+\fB-z\fR
+Disable gunzip-on-the-fly 
+.TP
+\fB+/\fIstring\fB\fR
+Start up at the
+line containing the first occurrence of string 
+.TP
+\fB+\fIlineno\fB\fR
+Start up at the
+specified line-number 
+.TP
+\fB+d\fR
+This switch should only be used if
+you want the option to delete a file while viewing it.  This makes
+it easier to clean unwanted files out of a directory. The file is
+deleted with the interactive key sequence `:D' and then confirming
+with `y'. 
+.TP
+\fB+s\fR
+Secure Mode-- no edit, cd, shell,
+and reading files not already listed on the command line. 
+.SH "COMMAND USAGE"
+.PP
+The commands take effect immediately; it is not necessary to type a
+carriage return.  In the following commands, \fBi\fR is a numerical
+argument (1 by default).
+.TP
+\fBSPACE, CTRL-D, NEXT_SCREEN\fR
+Display another windowful, or jump \fBi\fR windowfuls if \fBi\fR is specified. 
+.TP
+\fBRETURN, DOWN_ARROW, V, CTRL-N\fR
+Display another line, or \fBi\fR more lines, if specified. 
+.TP
+\fBUP_ARROW, ^, CTRL-P\fR
+Display previous line, or \fBi\fR previous
+lines, if specified. 
+.TP
+\fBT, ESCAPE<\fR
+Move to top of buffer. 
+.TP
+\fBB, ESCAPE>\fR
+Move to bottom of buffer. 
+.TP
+\fBRIGHT_ARROW, TAB, >\fR
+Scroll window left 60\fBi\fR columns to view
+lines that are beyond the right margin of the window. 
+.TP
+\fBLEFT_ARROW, CTRL-B, <\fR
+Scroll window right 60\fBi\fR columns to
+view lines that are beyond the left margin of the window. 
+.TP
+\fBU, CTRL-U, DELETE, PREV_SCREEN\fR
+Skip back \fBi\fR windowfuls and
+then print a windowful. 
+.TP
+\fBR, CTRL-R\fR
+Redraw the window. 
+.TP
+\fBJ, G\fR
+If  \fBi\fR  is  not  specified, then prompt for a line
+number then jump to that line otherwise just jump to line i. 
+.TP
+\fB%\fR
+If \fBi\fR is not specified, then prompt for a percent number
+then jump to that percent of the file otherwise just jump to \fBi\fR percent
+of the file. 
+.TP
+\fBW, w\fR
+If  the  current  screen  width  is 80, make it 132 and
+vice-versa.  For other values, this command is ignored. 
+.TP
+\fBQ, CTRL-X CTRL-C, CTRL-K E\fR
+Exit from \fBmost\fR\&.  On VMS, ^Z also
+exits. 
+.TP
+\fBh, CTRL-H, HELP, PF2\fR
+Help.  Give a description of all the
+\fBmost\fR commands.  The \fBmost\fR environment variable MOST_HELP must be set
+for this to be meaningful. 
+.TP
+\fBf, /, CTRL-F, FIND, GOLD PF3\fR
+Prompt  for  a  string  and
+search forward from the current line for ith distinct line containing
+the string.  CTRL-G aborts. 
+.TP
+\fB?\fR
+Prompt for a string and search backward for the ith
+distinct line containing the string.  CTRL-G aborts. 
+.TP
+\fBn\fR
+Search for the next \fBi\fR lines containing an occurrence of
+the last search string in the direction of the previous search. 
+.TP
+\fBm, SELECT, CTRL-@, CTRL-K M, PERIOD\fR
+Set a mark on the
+current line for later reference. 
+.TP
+\fBINSERT_HERE, CTRL-X CTRL-X, COMMA, CTRL-K RETURN, GOLD PERIOD\fR
+Set a mark on the current line but return to previous mark.
+This allows the user to toggle back and forth between two positions in
+the file. 
+.TP
+\fBl, L\fR
+Toggle locking for this window.  The window is locked
+if there is a `*' at the left edge of the status line.  Windows locked
+together, scroll together. 
+.TP
+\fBCTRL-X 2, CTRL-W 2, GOLD X\fR
+Split this window in half. 
+.TP
+\fBCTRL-X o, CTRL-W o, o, GOLDUP, GOLDDOWN\fR
+Move to other window. 
+.TP
+\fBCTRL-X 0, CTRL-W 0, GOLD V\fR
+Delete this window. 
+.TP
+\fBCTRL-X 1, CTRL-W 1, GOLD O\fR
+Delete all other windows, leaving
+only one window. 
+.TP
+\fBE, e\fR
+Edit this file. 
+.TP
+\fB$, ESC $\fR
+This is system dependent.  On VMS, this causes \fBmost\fR
+to spawn a subprocess.  When the user exits the process, \fBmost\fR is
+resumed.  On UNIX systems, \fBmost\fR simply suspends itself. 
+.TP
+\fB:n\fR
+Skip to the next filename given in the command line.  Use
+the arrow keys to scroll forward or backward through the file list.
+`Q' quits \fBmost\fR and any other key selects the given file. 
+.TP
+\fB:c\fR
+Toggle case sensitive search. 
+.TP
+\fB:D\fR
+Delete current file.  This command is only meaningful
+with the +d switch. 
+.TP
+\fB:o, :O\fR
+Toggle various options.  With this key sequence, \fBmost\fR
+displays a prompt asking the user to hit one of: bdtvw.  The `b', `t',
+`v', and `w' options have the same meaning as the command line
+switches.  For example, the `w' option will toggle wrapping on and off
+for the current window.
+
+The `d' option must be used with a prefix integer i.  All lines
+indented beyond \fBi\fR columns will not be displayed.  For example,
+consider the fragment: 
+.TP
+\fB\fR
+
+.nf
+   int main(int argc, char **argv)
+   {
+     int i;
+     for (i = 0; i < argc, i++)
+       {
+         fprintf(stdout,"%i: %s\\n",i,argv[i]);
+       }
+     return 0;
+   }
+.fi
+The key sequence `1:od' will cause \fBmost\fR to display the file ignoring
+all lines indented beyond the first column.  So for the example above,
+\fBmost\fR would display:
+
+.nf
+   int main(int argc, char **argv)...
+   }
+.fi
+where the `...' indicates lines that follow are not displayed.
+.SH "HINTS"
+.PP
+CTRL-G aborts the commands requiring the user to type something in
+at a prompt.  The back-quote key has a special meaning here.  It is
+used to quote certain characters.  This is useful when search for
+the occurrence of a string with a control character or a string at
+the beginning of a line.  In the latter case, to find the occurrence
+of `The' at the beginning of a line, enter `^JThe where ` quotes the
+CTRL-J.
+.SH "ENVIRONMENT"
+.PP
+\fBmost\fR uses the following environment variables:
+.TP
+\fBMOST_SWITCHES\fR
+This  variable  sets  commonly used switches.
+For example, some people prefer to use \fBmost\fR with the -s option so that
+excess blank lines are not displayed.  On VMS this is normally done
+done in the login.com through the line: 
+.TP
+\fB\fR
+
+.nf
+   $ define MOST_SWITCHES "-s"
+.fi
+.TP
+\fBMOST_EDITOR, SLANG_EDITOR\fR
+Either  of  these environment
+variables specify an editor for \fBmost\fR to invoke to edit a file. The
+value can contain %s and %d formatting descriptors that represent the
+file name and line number, respectively.  For example, if JED is
+your editor, then set MOST_EDITOR to 'jed %s -g %d'. 
+.TP
+\fBMOST_HELP\fR
+This variable may be used to specify an alternate
+help file. 
+.TP
+\fBMOST_INITFILE\fR
+Set this variable to specify the
+initialization file to load during startup.  The default action is to
+load the system configuration file and then a personal configuration
+file called .mostrc on Unix, and most.rc on other systems. 
+.SH "CONFIGURATION FILE SYNTAX"
+.PP
+When \fBmost\fR starts up, it tries to read a system configuration file and
+then a personal configuration file. These files may be used to specify
+key-bindings and colors.
+.PP
+To bind a key to a particular function use the syntax:
+
+.nf
+    setkey function-name key-sequence
+.fi
+.PP
+The setkey command requires two arguments.  The function-name argument
+specifies the function that is to be executed as a response to the
+keys specified by the key-sequence argument are pressed.  For example,
+
+.nf
+    setkey   "up"     "^P"
+.fi
+.PP
+indicates that when Ctrl-P is pressed then the function up is to be executed.
+.PP
+Sometimes, it is necessary to first unbind a key-sequence before
+rebinding it in order via the unsetkey function:
+
+.nf
+    unsetkey "^F"
+.fi
+.PP
+Colors may be defined through the use of the color keyword in the the
+configuration file using the syntax:
+
+.nf
+    color OBJECT-NAME FOREGROUND-COLOR BACKGROUND-COLOR
+.fi
+.PP
+Here, OBJECT-NAME can be any one of the following items:
+
+.nf
+     status           -- the status line
+     underline        -- underlined text
+     overstrike       -- overstruck text
+     normal           -- anything else
+.fi
+.PP
+See the sample configuration files for more information.
+.SH "BUGS"
+.PP
+Almost all of the known bugs or limitations of \fBmost\fR are due to a
+desire to read and interpret control characters in files.  One
+problem concerns the use of backspace characters to underscore or
+overstrike other characters.  \fBmost\fR makes an attempt to use terminal
+escape sequences to simulate this behavior.  One side effect is the
+one does not always get what one expects when scrolling right and left
+through a file.  When in doubt, use the -v and -b options of \fBmost\fR\&.
+.PP
+The regular-expression searches may fail to find strings that involve
+backspace/underscore used for highlighting.  The regular-expression
+syntax is described in the S-Lang Library documentation.
+.SH "AUTHOR"
+.PP
+John E. Davis <jed@jedsoft.org>
+.SH "ACKNOWLEDGEMENTS"
+.PP
+Over the years, many people have contributed to \fBmost\fR in one way or
+another, e.g., via code patches, bug-fixes, comments, or criticisms.
+I am particularly grateful to the very early adopters of the program
+who took a chance with a fledgling software project headed by someone
+learning the underlying language.  These include:
+.PP
+Mats Akerberg, Henk D. Davids, Rex O. Livingston, and Mark Pizzolato
+contributed to the early VMS versions of \fBmost\fR\&.  In particular, Mark
+worked on it to get it ready for DECUS.
+.PP
+Foteos Macrides adapted \fBmost\fR for use in cswing and gopher.  A few
+features of the present version of \fBmost\fR was inspired from his work.
+.PP
+I am grateful to Robert Mills for re-writing the search routines to
+use regular expressions.
+.PP
+Sven Oliver Moll came up with the idea of automatic detection of
+zipped files.
+.PP
+I would also like to thank Shinichi Hama for his valuable criticisms
+of \fBmost\fR\&.
+.PP
+Javier Kohen was instrumental in the support for UTF-8.
+.PP
+Thanks to David W. Sanderson for adapting the early documentation to
+nroff man page source format.
diff --git a/upstream/mageia-cauldron/man1/mouse-test.1 b/upstream/mageia-cauldron/man1/mouse-test.1
new file mode 100644
index 00000000..54d32314
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mouse-test.1
@@ -0,0 +1,44 @@
+.TH mouse-test 1 "March 26, 1998" ""
+.SH NAME
+mouse-test \- a tool for determining mouse type and device it's attached to.
+.SH SYNTAX
+\fBmouse-test\fR [ \fIdevice\fR ... ]
+.SH DESCRIPTION
+
+.LP
+This experimental and incomplete application tries to help in detecting
+which protocol does your mouse speak. It is able to detect MouseMan
+devices, and to choose between \-t ms (three-buttons aware) and
+\-t bare old two-buttons-only serial mice.
+
+.LP
+.SH BUGS
+
+.LP
+I know the application is buggy, but I only own one mouse device.
+If you are interested in this application, just call me and awake me
+from my laziness.
+
+.LP
+.SS OPTIONS
+.IP \fIdevice\fP
+[ \fIdevice\fP ... ]
+.PP
+Check this \fIdevice\fP for a mouse.  If no devices are listed, mouse-test will try all possible devices.
+
+.LP
+.SH AUTHOR
+Alessandro Rubini <rubini@linux.it>
+
+.LP
+.SH FILES
+.nf
+/dev/*              The devices used to search for a mouse
+.fi
+
+.LP
+.SH SEE ALSO
+.nf
+gpm(8)
+
+.fi
diff --git a/upstream/mageia-cauldron/man1/mpartition.1 b/upstream/mageia-cauldron/man1/mpartition.1
new file mode 100644
index 00000000..618b4cc6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mpartition.1
@@ -0,0 +1,228 @@
+'\" t
+.TH mpartition 1 "21Mar23" mtools-4.0.43
+.SH Name
+mpartition - partition an MSDOS hard disk
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmpartition\fR command is used to create MS-DOS file systems as
+partitions.  This is intended to be used on non-Linux systems,
+i.e. systems where fdisk and easy access to SCSI devices are not
+available.  This command only works on drives whose partition variable
+is set.
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-p\fR \fIdrive\fR
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-r\fR \fIdrive\fR
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-I\fR [\fR\&\f(CW-B\fR \fIbootSector\fR] \fIdrive\fR 
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-a\fR \fIdrive\fR
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-d\fR \fIdrive\fR
+\&\fR\&\f(CWmpartition\fR \fR\&\f(CW-c\fR [\fR\&\f(CW-s\fR \fIsectors\fR] [\fR\&\f(CW-h\fR \fIheads\fR]
+[\fR\&\f(CW-t\fR \fIcylinders\fR] [\fR\&\f(CW-v\fR [\fR\&\f(CW-T\fR \fItype\fR] [\fR\&\f(CW-b\fR
+\&\fIbegin\fR] [\fR\&\f(CW-l\fR length] [\fR\&\f(CW-f\fR]
+\&\&
+.fi
+.ft R
+ 
+.PP
+Mpartition supports the following operations:
+.TP
+\&\fR\&\f(CWp\fR\ 
+Prints a command line to recreate the partition for the drive.  Nothing
+is printed if the partition for the drive is not defined, or an
+inconsistency has been detected.  If verbose (\fR\&\f(CW-v\fR) is also set,
+prints the current partition table.
+.TP
+\&\fR\&\f(CWr\fR\ 
+Removes the partition described by \fIdrive\fR.
+.TP
+\&\fR\&\f(CWI\fR\ 
+Initializes the partition table, and removes all partitions.
+.TP
+\&\fR\&\f(CWc\fR\ 
+Creates the partition described by \fIdrive\fR.
+.TP
+\&\fR\&\f(CWa\fR\ 
+"Activates" the partition, i.e. makes it bootable.  Only one partition
+can be bootable at a time.
+.TP
+\&\fR\&\f(CWd\fR\ 
+"Deactivates" the partition, i.e. makes it unbootable.
+.PP
+If no operation is given, the current settings are printed.
+.PP
+For partition creations, the following options are available:
+.TP
+\&\fR\&\f(CWs\ \fIsectors\fR\&\f(CW\fR\ 
+The number of sectors per track of the partition (which is also the
+number of sectors per track for the whole drive).
+.TP
+\&\fR\&\f(CWh\ \fIheads\fR\&\f(CW\fR\ 
+The number of heads of the partition (which is also the number of heads
+for the whole drive).  By default, the geometry information (number of
+sectors and heads) is figured out from neighboring partition table
+entries, or guessed from the size.
+.TP
+\&\fR\&\f(CWt\ \fIcylinders\fR\&\f(CW\fR\ 
+The number of cylinders of the partition (not the number of cylinders of
+the whole drive.
+.TP
+\&\fR\&\f(CWb\ \fIbegin\fR\&\f(CW\fR\ 
+The starting offset of the partition, expressed in sectors. If begin
+is not given, \fR\&\f(CWmpartition\fR lets the partition begin at the start
+of the disk (partition number 1), or immediately after the end of the
+previous partition.
+.TP
+\&\fR\&\f(CWl\ \fIlength\fR\&\f(CW\fR\ 
+The size (length) of the partition, expressed in sectors.  If end is
+not given, \fR\&\f(CWmpartition\fR figures out the size from the number of
+sectors, heads and cylinders.  If these are not given either, it gives
+the partition the biggest possible size, considering disk size and
+start of the next partition.
+.PP
+The following option is available for all operation which modify the
+partition table:
+.TP
+\&\fR\&\f(CWf\fR\ 
+Usually, before writing back any changes to the partition, mpartition
+performs certain consistency checks, such as checking for overlaps and
+proper alignment of the partitions.  If any of these checks fails, the
+partition table is not changed.  The \fR\&\f(CW-f\fR allows you to override
+these safeguards.
+.PP
+The following options are available for all operations:
+.TP
+\&\fR\&\f(CWv\fR\ 
+Together with \fR\&\f(CW-p\fR prints the partition table as it is now (no
+change operation), or as it is after it is modified.
+.TP
+\&\fR\&\f(CWvv\fR\ 
+If the verbosity flag is given twice, \fR\&\f(CWmpartition\fR will print out
+a hexdump of the partition table when reading it from and writing it
+to the device.
+.PP
+The following option is available for partition table initialization:
+.TP
+\&\fR\&\f(CWB\ \fIbootSector\fR\&\f(CW\fR\ 
+Reads the template master boot record from file \fIbootSector\fR.
+.PP
+.SH Choice\ of\ partition\ type
+.PP
+Mpartition proceeds as follows to pick a type for the partition:
+.TP
+-\ \ 
+FAT32 partitions are assigned type 0x0C (``\fR\&\f(CWWin95 FAT32, LBA\fR'')
+.TP
+-\ \ 
+For all others, if the partition fits entirely within the first 65536
+sectors of the disk, assign 0x01 (``\fR\&\f(CWDOS FAT12, CHS\fR'') for FAT12
+partition and 0x04 (``\fR\&\f(CWDOS FAT16, CHS\fR'') for FAT16 partitions
+.TP
+-\ \ 
+If not covered by the above, assign 0x06 (``\fR\&\f(CWDOS BIG FAT16 CHS\fR'') if partition fits entirely within the first 1024 cylinders (CHS mode)
+.TP
+-\ \ 
+All remaining cases get 0x0E (``\fR\&\f(CWWin95 BIG FAT16, LBA\fR'')
+.PP
+If number of fat bits is not known (not specified in drive's
+definition), then FAT12 is assumed for all drives with less than 4096
+sectors, and FAT16 for those with more than 4096 sectors.
+.PP
+This corresponds more or less to the definitions outlined at \fR\&\f(CWhttps://en.wikipedia.org/wiki/Partition_type#List_of_partition_IDs\fR
+and
+\&\fR\&\f(CWhttps://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/cc977219(v=technet.10)\fR,
+with two notable differences:
+.TP
+-\ \ 
+If fat bits are unknown, the reference documents consider drives with
+less than 32680 sectors to be FAT12. Mtools uses 4096 sectors as the
+cutoff point, as older versions of DOS only support FAT12 on disks
+with less than 4096 sectors (and these older versions are the ones
+which would be most likely to use FAT12 in the first place).
+.TP
+-\ \ 
+The reference documents use a 8GB (wikipedia) or a 4GB (Microsoft)
+cutoff between 0x06 (\fR\&\f(CWDOS BIG FAT16 CHS\fR) and 0x0E. Mtools uses
+1024 cylinders. This is because any partition beyond 1024 cylinders
+must be LBA and cannot be CHS. 8GB works out to be the biggest
+capacity which can be represented as CHS (63 sectors, 255 heads and
+1024 cylinders). 4GB is the capacity limit for windows 2000, so it
+makes sense that a documentation for windows 2000 would specify this
+as the upper limit for any partition type.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mpstat.1 b/upstream/mageia-cauldron/man1/mpstat.1
new file mode 100644
index 00000000..deb4eb19
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mpstat.1
@@ -0,0 +1,244 @@
+.\" mpstat manual page - (C) 2000-2020 Sebastien Godard (sysstat <at> orange.fr)
+.TH MPSTAT 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+mpstat \- Report processors related statistics.
+
+.SH SYNOPSIS
+.B mpstat [ -A ] [ --dec={ 0 | 1 | 2 } ] [ -H ] [ -n ] [ -u ] [ -T ] [ -V ] [ -I {
+.IB "keyword" "[,...] | ALL } ] [ -N { " "node_list " "| ALL } ] [ -o JSON ] [ -P {"
+.IB "cpu_list " "| ALL } ] [ " "interval " "[ " "count " "] ]"
+
+.SH DESCRIPTION
+.RB "The " "mpstat"
+command writes to standard output activities for each available processor,
+processor 0 being the first one.
+Global average activities among all processors are also reported.
+.RB "The " "mpstat"
+command can be used on both SMP and UP machines, but in the latter, only global
+average activities will be printed. If no activity has been selected, then the
+default report is the CPU utilization report.
+.PP
+.RI "The " "interval"
+parameter specifies the amount of time in seconds between each report.
+A value of 0 (or no parameters at all) indicates that processors statistics are
+to be reported for the time since system startup (boot). The
+.IR "count " "parameter can be specified in conjunction with the " "interval"
+parameter if this one is not set to zero. The value of
+.I count
+determines the number of reports generated at
+.IR "interval " "seconds apart. If the " "interval"
+parameter is specified without the
+.IR "count " "parameter, the"
+.B mpstat
+command generates reports continuously.
+
+.SH OPTIONS
+.TP
+.B -A
+This option is equivalent to specifying
+.BR "-n -u -I ALL" "."
+This option also implies specifying
+.B "-N ALL -P ALL"
+unless these options are explicitly set on the command line.
+.TP
+.B --dec={ 0 | 1 | 2 }
+Specify the number of decimal places to use (0 to 2, default value is 2).
+.TP
+.B -H
+Also detect and display statistics for physically hotplugged vCPUs.
+.TP
+.BI "-I { " "keyword" "[,...] | ALL }"
+Report interrupts statistics.
+.RI "Possible " "keywords " "are"
+.BR "CPU" ", " "SCPU" ", and " "SUM" "."
+.PP
+.RS
+.RB "With the " "CPU"
+keyword, the number of each individual interrupt received per
+second by the CPU or CPUs is displayed. Interrupts are those listed in
+.IR "/proc/interrupts " "file."
+.PP
+.RB "With the " "SCPU"
+keyword, the number of each individual software interrupt received per
+second by the CPU or CPUs is displayed. This option works only
+with kernels 2.6.31 and later. Software interrupts are those listed in
+.IR "/proc/softirqs " "file."
+.PP
+.RB "With the " "SUM " "keyword, the " "mpstat"
+command reports the total number of interrupts per processor.
+The following values are displayed:
+
+.IP CPU
+Processor number. The keyword
+.B all
+indicates that statistics are calculated as averages among all processors.
+
+.IP intr/s
+Show the total number of interrupts received per second by
+the CPU or CPUs.
+.RE
+.IP
+.RB "The " "ALL"
+keyword is equivalent to specifying all the keywords above and
+therefore all the interrupts statistics are displayed.
+.TP
+.BI "-N { " "node_list " "| ALL }"
+Indicate the NUMA nodes for which statistics are to be reported.
+.I node_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0,2,4-7,12-" "). Note that node " "all"
+is the global average among all nodes. The
+.B ALL
+keyword indicates that statistics are to be reported for all nodes.
+.TP
+.B -n
+Report summary CPU statistics based on NUMA node placement. The following
+values are displayed:
+.RS
+.IP NODE
+Logical NUMA node number. The keyword
+.B all
+indicates that statistics are calculated as averages among all nodes.
+.RE
+.IP
+All the other fields are the same as those displayed with option
+.BR "-u " "(see below)."
+.TP
+.B -o JSON
+Display the statistics in JSON (JavaScript Object Notation) format.
+JSON output field order is undefined, and new fields may be added
+in the future.
+.TP
+.BI "-P { " "cpu_list " "| ALL }"
+Indicate the processors for which statistics are to be reported.
+.I cpu_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0,2,4-7,12-" ")."
+Note that processor 0 is the first processor, and processor
+.B all
+is the global average among all processors.
+.RB "The " "ALL"
+keyword indicates that statistics are to be reported for all processors.
+Offline processors are not displayed.
+.TP
+.B -T
+Display topology elements in the CPU report (see option
+.B -u
+below). The following elements are displayed:
+.RS
+.IP CORE
+Logical core number.
+.IP SOCK
+Logical socket number.
+.IP NODE
+Logical NUMA node number.
+.RE
+.TP
+.B -u
+Report CPU utilization. The following values are displayed:
+.RS
+.IP CPU
+Processor number. The keyword
+.I all
+indicates that statistics are calculated as averages among all processors.
+.IP %usr
+Show the percentage of CPU utilization that occurred while
+executing at the user level (application).
+.IP %nice
+Show the percentage of CPU utilization that occurred while
+executing at the user level with nice priority.
+.IP %sys
+Show the percentage of CPU utilization that occurred while
+executing at the system level (kernel). Note that this does not
+include time spent servicing hardware and software interrupts.
+.IP %iowait
+Show the percentage of time that the CPU or CPUs were idle during which
+the system had an outstanding disk I/O request.
+.IP %irq
+Show the percentage of time spent by the CPU or CPUs to service hardware interrupts.
+.IP %soft
+Show the percentage of time spent by the CPU or CPUs to service software interrupts.
+.IP %steal
+Show the percentage of time spent in involuntary wait by the virtual CPU
+or CPUs while the hypervisor was servicing another virtual processor.
+.IP %guest
+Show the percentage of time spent by the CPU or CPUs to run a virtual processor.
+.IP %gnice
+Show the percentage of time spent by the CPU or CPUs to run a niced guest.
+.IP %idle
+Show the percentage of time that the CPU or CPUs were idle and the system
+did not have an outstanding disk I/O request.
+.RE
+.TP
+.B -V
+Print version number then exit.
+
+.SH ENVIRONMENT
+.RB "The " "mpstat"
+command takes into account the following environment variable:
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.IR "never" ", " "always " "or " "auto"
+(the latter is equivalent to the default settings).
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B I=
+SGR (Select Graphic Rendition) substring for CPU number.
+.TP
+.B N=
+SGR substring for non-zero statistics values.
+.TP
+.BR "W=" " (or " "M=" ")"
+SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
+metric's meaning).
+.TP
+.BR "X=" " (or " "H=" ")"
+SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
+metric's meaning).
+.TP
+.B Z=
+SGR substring for zero values.
+.RE
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.BR ISO
+then the current locale will be ignored when printing the date in the report header.
+.RB "The " "mpstat"
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+The timestamp will also be compliant with ISO 8601 format.
+
+.SH EXAMPLES
+.TP
+.B mpstat 2 5
+Display five reports of global statistics among all processors at two second intervals.
+.TP
+.B mpstat -P ALL 2 5
+Display five reports of statistics for all processors at two second intervals.
+
+.SH BUGS
+.IR "/proc " "filesystem must be mounted for the"
+.BR "mpstat " "command to work."
+
+.SH FILES
+.IR "/proc " "contains various files with system statistics."
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "pidstat" "(1), " "iostat" "(1), " "vmstat" "(8)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/mrd.1 b/upstream/mageia-cauldron/man1/mrd.1
new file mode 100644
index 00000000..46e2015d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mrd.1
@@ -0,0 +1,95 @@
+'\" t
+.TH mrd 1 "21Mar23" mtools-4.0.43
+.SH Name
+mrd - remove an MSDOS subdirectory
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmrd\fR command is used to remove an MS-DOS subdirectory. Its
+syntax is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmrd\fR [\fR\&\f(CW-v\fR] \fImsdosdirectory\fR [ \fImsdosdirectories\fR\&... ]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMrd\fR removes a directory from an MS-DOS file system. An error occurs
+if the directory does not exist or is not empty.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mren.1 b/upstream/mageia-cauldron/man1/mren.1
new file mode 100644
index 00000000..4d56089f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mren.1
@@ -0,0 +1,105 @@
+'\" t
+.TH mren 1 "21Mar23" mtools-4.0.43
+.SH Name
+mren - rename an existing MSDOS file
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmren\fR command is used to rename or move an existing MS-DOS
+file or subdirectory. Its syntax is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmren\fR [\fR\&\f(CW-voOsSrRA\fR] \fIsourcefile\fR \fItargetfile\fR
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMren\fR
+renames an existing file on an MS-DOS file system.
+.PP
+In verbose mode, \fR\&\f(CWMren\fR displays the new filename if the name
+supplied is invalid.
+.PP
+If the first syntax is used (only one source file), and if the target
+name doesn't contain any slashes or colons, the file (or subdirectory)
+is renamed in the same directory, instead of being moved to the current
+\&\fR\&\f(CWmcd\fR directory as would be the case with \fR\&\f(CWmmove\fR. Unlike the
+MS-DOS version of \fR\&\f(CWREN\fR, \fR\&\f(CWmren\fR can be used to rename
+directories.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mrf.1 b/upstream/mageia-cauldron/man1/mrf.1
new file mode 100644
index 00000000..cbb393f6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mrf.1
@@ -0,0 +1,131 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "MRF image format specification" 0 "1991" "netpbm documentation"
+
+.SH NAME
+
+MRF - monochrome recursive format (compressed bitmaps)
+
+.UN description
+.SH DESCRIPTION
+.PP
+This document describes the MRF format recognized by
+.BR "Netpbm" (1)\c
+\&.
+.PP
+MRF is a compressed format for bilevel (1-bit mono) images.  It
+achieves better compression for some such images than either GIF or
+PNG. (It's also very easy to implement (about the same difficulty as
+RLE, I'd say) and an MRF reader needs no tables/buffers, which may
+make it useful for tiny machines).
+.PP
+In case the above hasn't made it sufficiently clear, I'll make this
+next point explicitly: \fIMRF cannot represent color at all.\fP Nor
+can it represent grayscale.  It's a specifically mono format.  (If you
+want to compress a color or grayscale image, my advice is to use
+JPEG2000).
+.PP
+First, here's what goes where in an MRF file. I'll explain how the
+compression works afterward.
+
+
+.TP
+Offset
+Description
+.TP
+0
+magic number - "MRF1" (in ASCII)
+
+.TP
+4
+width (32-bit, MSB first (i.e. big-endian))
+
+.TP
+8
+height (same)
+
+.TP
+12
+reserved (single byte, must be zero)
+
+.TP
+13
+compressed data
+
+
+.PP
+Note that there is no end-of-file marker in the file itself - the
+compressed data carries on right up to EOF.
+.PP
+The way the picture is compressed is essentially very simple, but
+as they say, the devil is in the detail.  So don't be put off if it
+sounds confusing.
+.PP
+The image is treated as a number of 64x64 squares, forming a grid
+large enough to encompass it. (If an image is (say) 129x65, it'll be
+treated in the same way as a 192x128 one. On decompression, the extra
+area which was encoded (the contents of this area is undefined) should
+be ignored.) Each of these squares in turn (in left-to-right,
+top-to-bottom order) is recursively subdivided until the smallest
+completely black or white squares are found. Some pseudocode (eek!)
+for the recursive subdivision routine should make things clearer:
+
+.nf
+    if square size > 1x1 and square is all one color, output 1 bit
+    if whole square is black, output a 0 bit and return
+    if whole square is white, output a 1 bit and return
+    output a 0 bit
+    divide the square into four quarters, calling routine for
+    each in this order: top-left, top-right, bottom-left, bottom-right
+
+.fi
+.PP
+(Note that the "output a 0 bit" stage is not reached for squares
+of size 1x1, which is what stops it recursing infinitely.  I mention
+this as it may not be immediately obvious.)
+.PP
+The whole of the compressed data is made up of the bits output by
+the above routine. The bits are packed into bytes MSB first, so for
+example outputting the bits 1,0,0,0,0,0,0,0 would result in a 80h byte
+being output. Any `unused' bits in the last byte output are undefined;
+these are effectively after EOF and their value is unimportant.
+.PP
+If writing that sounds too much like hard work :-), you could
+always adapt \fBpbmtomrf\fP and/or \fBmrftopbm\fP.  That's the main
+reason their source code is public domain, after all.
+.PP
+Above, I said the contents of any extra area encoded (when a bitmap
+smaller than the grid of squares is compressed) is undefined.  This is
+deliberate so that the MRF compressor can make these unseen areas
+anything it wants so as to maximize compression, rather than simply
+leaving it blank. \fBpbmtomrf\fP does a little in this respect but
+could definitely be improved upon.
+.PP
+\fBmrftopbm\fP's \fB-1\fP option causes it to include the edges, if
+any, in the output PBM.  This may help when debugging a compressor's
+edge optimization.
+.PP
+Note that the "F" in the name "MRF" comes from "format," which is redundant
+because it is the name of a format.  That sort of makes "MRF format" sound
+as stupid as "PIN number," but it's not really that bad.
+
+.UN seealso
+.SH SEE ALSO
+.BR "mrftopbm" (1)\c
+\&,
+.BR "pbmtomrf" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Russell Marks.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/mrf.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/mrftopbm.1 b/upstream/mageia-cauldron/man1/mrftopbm.1
new file mode 100644
index 00000000..3d422925
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mrftopbm.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Mrftopbm User Manual" 0 "10 August 2003" "netpbm documentation"
+
+
+.SH NAME
+
+mrftopbm - convert an MRF image to PBM format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmrftopbm\fP
+[ \fB-a\fP ]
+[ \fIinput.mrf\fP ]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBmrftopbm\fP converts an MRF image to PBM format. 
+.PP
+\fBmrftopbm\fP takes the MRF image from the file named by the
+\fIinput.mrf\fP argument, or Standard Input if you don't specify
+\fIinput.mrf\fP.  The output goes to Standard Output.
+.PP
+For more information about mrf, see
+.BR "the MRF
+specification" (1)\c
+\&.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBmrftopbm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-a\fP
+causes \fBmrftopbm\fP to include the edges, if any, in the output
+PBM.  This may help when debugging a compressor's edge optimization.
+
+
+.UN author
+.SH AUTHOR
+
+Russell Marks.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtomrf" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "mrf" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/mrftopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/msgattrib.1 b/upstream/mageia-cauldron/man1/msgattrib.1
new file mode 100644
index 00000000..7534f56e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgattrib.1
@@ -0,0 +1,172 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGATTRIB "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgattrib \- attribute matching and manipulation on message catalog
+.SH SYNOPSIS
+.B msgattrib
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Filters the messages of a translation catalog according to their attributes,
+and manipulates the attributes.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Message selection:"
+.TP
+\fB\-\-translated\fR
+keep translated, remove untranslated messages
+.TP
+\fB\-\-untranslated\fR
+keep untranslated, remove translated messages
+.TP
+\fB\-\-no\-fuzzy\fR
+remove 'fuzzy' marked messages
+.TP
+\fB\-\-only\-fuzzy\fR
+keep 'fuzzy' marked messages
+.TP
+\fB\-\-no\-obsolete\fR
+remove obsolete #~ messages
+.TP
+\fB\-\-only\-obsolete\fR
+keep obsolete #~ messages
+.SS "Attribute manipulation:"
+.TP
+\fB\-\-set\-fuzzy\fR
+set all messages 'fuzzy'
+.TP
+\fB\-\-clear\-fuzzy\fR
+set all messages non\-'fuzzy'
+.TP
+\fB\-\-set\-obsolete\fR
+set all messages obsolete
+.TP
+\fB\-\-clear\-obsolete\fR
+set all messages non\-obsolete
+.TP
+\fB\-\-previous\fR
+when setting 'fuzzy', keep previous msgids
+of translated messages.
+.TP
+\fB\-\-clear\-previous\fR
+remove the "previous msgid" from all messages
+.TP
+\fB\-\-empty\fR
+when removing 'fuzzy', also set msgstr empty
+.TP
+\fB\-\-only\-file\fR=\fI\,FILE\/\fR.po
+manipulate only entries listed in FILE.po
+.TP
+\fB\-\-ignore\-file\fR=\fI\,FILE\/\fR.po
+manipulate only entries not listed in FILE.po
+.TP
+\fB\-\-fuzzy\fR
+synonym for \fB\-\-only\-fuzzy\fR \fB\-\-clear\-fuzzy\fR
+.TP
+\fB\-\-obsolete\fR
+synonym for \fB\-\-only\-obsolete\fR \fB\-\-clear\-obsolete\fR
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write the .po file using indented style
+.TP
+\fB\-\-no\-location\fR
+do not write '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+generate '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+write out strict Uniforum conforming .po file
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgattrib
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgattrib
+programs are properly installed at your site, the command
+.IP
+.B info msgattrib
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgcat.1 b/upstream/mageia-cauldron/man1/msgcat.1
new file mode 100644
index 00000000..2e7dd946
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgcat.1
@@ -0,0 +1,152 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGCAT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgcat \- combines several message catalogs
+.SH SYNOPSIS
+.B msgcat
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Concatenates and merges the specified PO files.
+Find messages which are common to two or more of the specified PO files.
+By using the \fB\-\-more\-than\fR option, greater commonality may be requested
+before messages are printed.  Conversely, the \fB\-\-less\-than\fR option may be
+used to specify less commonality before messages are printed (i.e.
+\fB\-\-less\-than\fR=\fI\,2\/\fR will only print the unique messages).  Translations,
+comments, extracted comments, and file positions will be cumulated, except
+that if \fB\-\-use\-first\fR is specified, they will be taken from the first PO file
+to define them.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE ...
+input files
+.TP
+\fB\-f\fR, \fB\-\-files\-from\fR=\fI\,FILE\/\fR
+get list of input files from FILE
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If input file is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Message selection:"
+.TP
+\-<, \fB\-\-less\-than\fR=\fI\,NUMBER\/\fR
+print messages with less than this many
+definitions, defaults to infinite if not set
+.TP
+\->, \fB\-\-more\-than\fR=\fI\,NUMBER\/\fR
+print messages with more than this many
+definitions, defaults to 0 if not set
+.TP
+\fB\-u\fR, \fB\-\-unique\fR
+shorthand for \fB\-\-less\-than\fR=\fI\,2\/\fR, requests
+that only unique messages be printed
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input files are in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input files are in NeXTstep/GNUstep .strings
+syntax
+.SS "Output details:"
+.TP
+\fB\-t\fR, \fB\-\-to\-code\fR=\fI\,NAME\/\fR
+encoding for output
+.TP
+\fB\-\-use\-first\fR
+use first available translation for each
+message, don't merge several translations
+.TP
+\fB\-\-lang\fR=\fI\,CATALOGNAME\/\fR
+set 'Language' field in the header entry
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write the .po file using indented style
+.TP
+\fB\-\-no\-location\fR
+do not write '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+generate '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+write out strict Uniforum conforming .po file
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgcat
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgcat
+programs are properly installed at your site, the command
+.IP
+.B info msgcat
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgcmp.1 b/upstream/mageia-cauldron/man1/msgcmp.1
new file mode 100644
index 00000000..e7b2ff84
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgcmp.1
@@ -0,0 +1,79 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGCMP "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgcmp \- compare message catalog and template
+.SH SYNOPSIS
+.B msgcmp
+[\fI\,OPTION\/\fR] \fI\,def.po ref.pot\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Compare two Uniforum style .po files to check that both contain the same
+set of msgid strings.  The def.po file is an existing PO file with the
+translations.  The ref.pot file is the last created PO file, or a PO Template
+file (generally created by xgettext).  This is useful for checking that
+you have translated each and every message in your program.  Where an exact
+match cannot be found, fuzzy matching is used to produce better diagnostics.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+def.po
+translations
+.TP
+ref.pot
+references to the sources
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.SS "Operation modifiers:"
+.TP
+\fB\-m\fR, \fB\-\-multi\-domain\fR
+apply ref.pot to each of the domains in def.po
+.TP
+\fB\-N\fR, \fB\-\-no\-fuzzy\-matching\fR
+do not use fuzzy matching
+.TP
+\fB\-\-use\-fuzzy\fR
+consider fuzzy entries
+.TP
+\fB\-\-use\-untranslated\fR
+consider untranslated entries
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input files are in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input files are in NeXTstep/GNUstep .strings
+syntax
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Peter Miller.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgcmp
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgcmp
+programs are properly installed at your site, the command
+.IP
+.B info msgcmp
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgcomm.1 b/upstream/mageia-cauldron/man1/msgcomm.1
new file mode 100644
index 00000000..22ec988c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgcomm.1
@@ -0,0 +1,144 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGCOMM "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgcomm \- match two message catalogs
+.SH SYNOPSIS
+.B msgcomm
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Find messages which are common to two or more of the specified PO files.
+By using the \fB\-\-more\-than\fR option, greater commonality may be requested
+before messages are printed.  Conversely, the \fB\-\-less\-than\fR option may be
+used to specify less commonality before messages are printed (i.e.
+\fB\-\-less\-than\fR=\fI\,2\/\fR will only print the unique messages).  Translations,
+comments and extracted comments will be preserved, but only from the first
+PO file to define them.  File positions from all PO files will be
+cumulated.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE ...
+input files
+.TP
+\fB\-f\fR, \fB\-\-files\-from\fR=\fI\,FILE\/\fR
+get list of input files from FILE
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If input file is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Message selection:"
+.TP
+\-<, \fB\-\-less\-than\fR=\fI\,NUMBER\/\fR
+print messages with less than this many
+definitions, defaults to infinite if not set
+.TP
+\->, \fB\-\-more\-than\fR=\fI\,NUMBER\/\fR
+print messages with more than this many
+definitions, defaults to 1 if not set
+.TP
+\fB\-u\fR, \fB\-\-unique\fR
+shorthand for \fB\-\-less\-than\fR=\fI\,2\/\fR, requests
+that only unique messages be printed
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input files are in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input files are in NeXTstep/GNUstep .strings
+syntax
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write the .po file using indented style
+.TP
+\fB\-\-no\-location\fR
+do not write '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+generate '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+write out strict Uniforum conforming .po file
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.TP
+\fB\-\-omit\-header\fR
+don't write header with 'msgid ""' entry
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Peter Miller.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgcomm
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgcomm
+programs are properly installed at your site, the command
+.IP
+.B info msgcomm
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgconv.1 b/upstream/mageia-cauldron/man1/msgconv.1
new file mode 100644
index 00000000..344cf5a9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgconv.1
@@ -0,0 +1,123 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGCONV "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgconv \- character set conversion for message catalog
+.SH SYNOPSIS
+.B msgconv
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Converts a translation catalog to a different character encoding.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Conversion target:"
+.TP
+\fB\-t\fR, \fB\-\-to\-code\fR=\fI\,NAME\/\fR
+encoding for output
+.PP
+The default encoding is the current locale's encoding.
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+indented output style
+.TP
+\fB\-\-no\-location\fR
+suppress '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+preserve '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+strict Uniforum output style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgconv
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgconv
+programs are properly installed at your site, the command
+.IP
+.B info msgconv
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgen.1 b/upstream/mageia-cauldron/man1/msgen.1
new file mode 100644
index 00000000..3977fd50
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgen.1
@@ -0,0 +1,123 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGEN "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgen \- create English message catalog
+.SH SYNOPSIS
+.B msgen
+[\fI\,OPTION\/\fR] \fI\,INPUTFILE\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Creates an English translation catalog.  The input file is the last
+created English PO file, or a PO Template file (generally created by
+xgettext).  Untranslated entries are assigned a translation that is
+identical to the msgid.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE
+input PO or POT file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If input file is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-\-lang\fR=\fI\,CATALOGNAME\/\fR
+set 'Language' field in the header entry
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+indented output style
+.TP
+\fB\-\-no\-location\fR
+suppress '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+preserve '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+strict Uniforum output style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgen
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgen
+programs are properly installed at your site, the command
+.IP
+.B info msgen
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgexec.1 b/upstream/mageia-cauldron/man1/msgexec.1
new file mode 100644
index 00000000..714abc6c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgexec.1
@@ -0,0 +1,70 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGEXEC "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgexec \- process translations of message catalog
+.SH SYNOPSIS
+.B msgexec
+[\fI\,OPTION\/\fR] \fI\,COMMAND \/\fR[\fI\,COMMAND-OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Applies a command to all translations of a translation catalog.
+The COMMAND can be any program that reads a translation from standard
+input.  It is invoked once for each translation.  Its output becomes
+msgexec's output.  msgexec's return code is the maximum return code
+across all invocations.
+.PP
+A special builtin command called '0' outputs the translation, followed by a
+null byte.  The output of "msgexec 0" is suitable as input for "xargs \fB\-0\fR".
+.SS "Command input:"
+.TP
+\fB\-\-newline\fR
+add newline at the end of input
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,INPUTFILE\/\fR
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgexec
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgexec
+programs are properly installed at your site, the command
+.IP
+.B info msgexec
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgfilter.1 b/upstream/mageia-cauldron/man1/msgfilter.1
new file mode 100644
index 00000000..30f816ac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgfilter.1
@@ -0,0 +1,139 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGFILTER "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgfilter \- edit translations of message catalog
+.SH SYNOPSIS
+.B msgfilter
+[\fI\,OPTION\/\fR] \fI\,FILTER \/\fR[\fI\,FILTER-OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Applies a filter to all translations of a translation catalog.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,INPUTFILE\/\fR
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.PP
+The FILTER can be any program that reads a translation from standard input
+and writes a modified translation to standard output.
+.SS "Filter input and output:"
+.TP
+\fB\-\-newline\fR
+add a newline at the end of input and
+remove a newline from the end of output
+.SS "Useful FILTER-OPTIONs when the FILTER is 'sed':"
+.TP
+\fB\-e\fR, \fB\-\-expression\fR=\fI\,SCRIPT\/\fR
+add SCRIPT to the commands to be executed
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fI\,SCRIPTFILE\/\fR
+add the contents of SCRIPTFILE to the commands
+to be executed
+.TP
+\fB\-n\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+suppress automatic printing of pattern space
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-\-indent\fR
+indented output style
+.TP
+\fB\-\-keep\-header\fR
+keep header entry unmodified, don't filter it
+.TP
+\fB\-\-no\-location\fR
+suppress '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+preserve '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+strict Uniforum output style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgfilter
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgfilter
+programs are properly installed at your site, the command
+.IP
+.B info msgfilter
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgfmt.1 b/upstream/mageia-cauldron/man1/msgfmt.1
new file mode 100644
index 00000000..512875c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgfmt.1
@@ -0,0 +1,218 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGFMT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgfmt \- compile message catalog to binary format
+.SH SYNOPSIS
+.B msgfmt
+[\fI\,OPTION\/\fR] \fI\,filename.po \/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Generate binary message catalog from textual translation description.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+Similarly for optional arguments.
+.SS "Input file location:"
+.TP
+filename.po ...
+input files
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If input file is \-, standard input is read.
+.SS "Operation mode:"
+.TP
+\fB\-j\fR, \fB\-\-java\fR
+Java mode: generate a Java ResourceBundle class
+.TP
+\fB\-\-java2\fR
+like \fB\-\-java\fR, and assume Java2 (JDK 1.2 or higher)
+.TP
+\fB\-\-csharp\fR
+C# mode: generate a .NET .dll file
+.TP
+\fB\-\-csharp\-resources\fR
+C# resources mode: generate a .NET .resources file
+.TP
+\fB\-\-tcl\fR
+Tcl mode: generate a tcl/msgcat .msg file
+.TP
+\fB\-\-qt\fR
+Qt mode: generate a Qt .qm file
+.TP
+\fB\-\-desktop\fR
+Desktop Entry mode: generate a .desktop file
+.TP
+\fB\-\-xml\fR
+XML mode: generate XML file
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.TP
+\fB\-\-strict\fR
+enable strict Uniforum mode
+.PP
+If output file is \-, output is written to standard output.
+.SS "Output file location in Java mode:"
+.TP
+\fB\-r\fR, \fB\-\-resource\fR=\fI\,RESOURCE\/\fR
+resource name
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-\-source\fR
+produce a .java file, instead of a .class file
+.TP
+\fB\-d\fR DIRECTORY
+base directory of classes directory hierarchy
+.PP
+The class name is determined by appending the locale name to the resource name,
+separated with an underscore.  The \fB\-d\fR option is mandatory.  The class is
+written under the specified directory.
+.SS "Output file location in C# mode:"
+.TP
+\fB\-r\fR, \fB\-\-resource\fR=\fI\,RESOURCE\/\fR
+resource name
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-d\fR DIRECTORY
+base directory for locale dependent .dll files
+.PP
+The \fB\-l\fR and \fB\-d\fR options are mandatory.  The .dll file is written in a
+subdirectory of the specified directory whose name depends on the locale.
+.SS "Output file location in Tcl mode:"
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-d\fR DIRECTORY
+base directory of .msg message catalogs
+.PP
+The \fB\-l\fR and \fB\-d\fR options are mandatory.  The .msg file is written in the
+specified directory.
+.SS "Desktop Entry mode options:"
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.TP
+\fB\-\-template\fR=\fI\,TEMPLATE\/\fR
+a .desktop file used as a template
+.TP
+\fB\-d\fR DIRECTORY
+base directory of .po files
+.TP
+\fB\-kWORD\fR, \fB\-\-keyword\fR=\fI\,WORD\/\fR
+look for WORD as an additional keyword
+.TP
+\fB\-k\fR, \fB\-\-keyword\fR
+do not to use default keywords
+.PP
+The \fB\-l\fR, \fB\-o\fR, and \fB\-\-template\fR options are mandatory.  If \fB\-D\fR is specified, input
+files are read from the directory instead of the command line arguments.
+.SS "XML mode options:"
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-L\fR, \fB\-\-language\fR=\fI\,NAME\/\fR
+recognise the specified XML language
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.TP
+\fB\-\-template\fR=\fI\,TEMPLATE\/\fR
+an XML file used as a template
+.TP
+\fB\-d\fR DIRECTORY
+base directory of .po files
+.PP
+The \fB\-l\fR, \fB\-o\fR, and \fB\-\-template\fR options are mandatory.  If \fB\-D\fR is specified, input
+files are read from the directory instead of the command line arguments.
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input files are in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input files are in NeXTstep/GNUstep .strings
+syntax
+.SS "Input file interpretation:"
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+perform all the checks implied by
+\fB\-\-check\-format\fR, \fB\-\-check\-header\fR, \fB\-\-check\-domain\fR
+.TP
+\fB\-\-check\-format\fR
+check language dependent format strings
+.TP
+\fB\-\-check\-header\fR
+verify presence and contents of the header entry
+.TP
+\fB\-\-check\-domain\fR
+check for conflicts between domain directives
+and the \fB\-\-output\-file\fR option
+.TP
+\fB\-C\fR, \fB\-\-check\-compatibility\fR
+check that GNU msgfmt behaves like X/Open msgfmt
+.TP
+\fB\-\-check\-accelerators\fR[=\fI\,CHAR\/\fR]
+check presence of keyboard accelerators for
+menu items
+.TP
+\fB\-f\fR, \fB\-\-use\-fuzzy\fR
+use fuzzy entries in output
+.SS "Output details:"
+.TP
+\fB\-a\fR, \fB\-\-alignment\fR=\fI\,NUMBER\/\fR
+align strings to NUMBER bytes (default: 1)
+.TP
+\fB\-\-endianness\fR=\fI\,BYTEORDER\/\fR
+write out 32\-bit numbers in the given byte order
+(big or little, default depends on platform)
+.TP
+\fB\-\-no\-hash\fR
+binary file will not include the hash table
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-\-statistics\fR
+print statistics about translations
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase verbosity level
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgfmt
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgfmt
+programs are properly installed at your site, the command
+.IP
+.B info msgfmt
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msggrep.1 b/upstream/mageia-cauldron/man1/msggrep.1
new file mode 100644
index 00000000..e26985c3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msggrep.1
@@ -0,0 +1,182 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGGREP "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msggrep \- pattern matching on message catalog
+.SH SYNOPSIS
+.B msggrep
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Extracts all messages of a translation catalog that match a given pattern
+or belong to some given source files.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Message selection:"
+.IP
+[\-N SOURCEFILE]... [\-M DOMAINNAME]...
+[\-J MSGCTXT\-PATTERN] [\-K MSGID\-PATTERN] [\-T MSGSTR\-PATTERN]
+[\-C COMMENT\-PATTERN] [\-X EXTRACTED\-COMMENT\-PATTERN]
+.PP
+A message is selected if it comes from one of the specified source files,
+or if it comes from one of the specified domains,
+or if \fB\-J\fR is given and its context (msgctxt) matches MSGCTXT\-PATTERN,
+or if \fB\-K\fR is given and its key (msgid or msgid_plural) matches MSGID\-PATTERN,
+or if \fB\-T\fR is given and its translation (msgstr) matches MSGSTR\-PATTERN,
+or if \fB\-C\fR is given and the translator's comment matches COMMENT\-PATTERN,
+or if \fB\-X\fR is given and the extracted comment matches EXTRACTED\-COMMENT\-PATTERN.
+.PP
+When more than one selection criterion is specified, the set of selected
+messages is the union of the selected messages of each criterion.
+.PP
+MSGCTXT\-PATTERN or MSGID\-PATTERN or MSGSTR\-PATTERN or COMMENT\-PATTERN or
+EXTRACTED\-COMMENT\-PATTERN syntax:
+.IP
+[\-E | \fB\-F]\fR [\-e PATTERN | \fB\-f\fR FILE]...
+.PP
+PATTERNs are basic regular expressions by default, or extended regular
+expressions if \fB\-E\fR is given, or fixed strings if \fB\-F\fR is given.
+.TP
+\fB\-N\fR, \fB\-\-location\fR=\fI\,SOURCEFILE\/\fR
+select messages extracted from SOURCEFILE
+.TP
+\fB\-M\fR, \fB\-\-domain\fR=\fI\,DOMAINNAME\/\fR
+select messages belonging to domain DOMAINNAME
+.TP
+\fB\-J\fR, \fB\-\-msgctxt\fR
+start of patterns for the msgctxt
+.TP
+\fB\-K\fR, \fB\-\-msgid\fR
+start of patterns for the msgid
+.TP
+\fB\-T\fR, \fB\-\-msgstr\fR
+start of patterns for the msgstr
+.TP
+\fB\-C\fR, \fB\-\-comment\fR
+start of patterns for the translator's comment
+.TP
+\fB\-X\fR, \fB\-\-extracted\-comment\fR
+start of patterns for the extracted comment
+.TP
+\fB\-E\fR, \fB\-\-extended\-regexp\fR
+PATTERN is an extended regular expression
+.TP
+\fB\-F\fR, \fB\-\-fixed\-strings\fR
+PATTERN is a set of newline\-separated strings
+.TP
+\fB\-e\fR, \fB\-\-regexp\fR=\fI\,PATTERN\/\fR
+use PATTERN as a regular expression
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fI\,FILE\/\fR
+obtain PATTERN from FILE
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+ignore case distinctions
+.TP
+\fB\-v\fR, \fB\-\-invert\-match\fR
+output only the messages that do not match any
+selection criterion
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-\-indent\fR
+indented output style
+.TP
+\fB\-\-no\-location\fR
+suppress '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+preserve '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+strict Uniforum output style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msggrep
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msggrep
+programs are properly installed at your site, the command
+.IP
+.B info msggrep
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msginit.1 b/upstream/mageia-cauldron/man1/msginit.1
new file mode 100644
index 00000000..1c33bcda
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msginit.1
@@ -0,0 +1,95 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGINIT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msginit \- initialize a message catalog
+.SH SYNOPSIS
+.B msginit
+[\fI\,OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Creates a new PO file, initializing the meta information with values from the
+user's environment.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,INPUTFILE\/\fR
+input POT file
+.PP
+If no input file is given, the current directory is searched for the POT file.
+If it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified PO file
+.PP
+If no output file is given, it depends on the \fB\-\-locale\fR option or the user's
+locale setting.  If it is \-, the results are written to standard output.
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LL_CC[\/\fR.ENCODING]
+set target locale
+.TP
+\fB\-\-no\-translator\fR
+assume the PO file is automatically generated
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msginit
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msginit
+programs are properly installed at your site, the command
+.IP
+.B info msginit
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgmerge.1 b/upstream/mageia-cauldron/man1/msgmerge.1
new file mode 100644
index 00000000..f2a6e4e9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgmerge.1
@@ -0,0 +1,185 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGMERGE "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgmerge \- merge message catalog and template
+.SH SYNOPSIS
+.B msgmerge
+[\fI\,OPTION\/\fR] \fI\,def.po ref.pot\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Merges two Uniforum style .po files together.  The def.po file is an
+existing PO file with translations which will be taken over to the newly
+created file as long as they still match; comments will be preserved,
+but extracted comments and file positions will be discarded.  The ref.pot
+file is the last created PO file with up\-to\-date source references but
+old translations, or a PO Template file (generally created by xgettext);
+any translations or comments in the file will be discarded, however dot
+comments and file positions will be preserved.  Where an exact match
+cannot be found, fuzzy matching is used to produce better results.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+def.po
+translations referring to old sources
+.TP
+ref.pot
+references to new sources
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.TP
+\fB\-C\fR, \fB\-\-compendium\fR=\fI\,FILE\/\fR
+additional library of message translations,
+may be specified more than once
+.SS "Operation mode:"
+.TP
+\fB\-U\fR, \fB\-\-update\fR
+update def.po,
+do nothing if def.po already up to date
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.PP
+Output file location in update mode:
+The result is written back to def.po.
+.TP
+\fB\-\-backup\fR=\fI\,CONTROL\/\fR
+make a backup of def.po
+.TP
+\fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+override the usual backup suffix
+.PP
+The version control method may be selected via the \fB\-\-backup\fR option or through
+the VERSION_CONTROL environment variable.  Here are the values:
+.TP
+none, off
+never make backups (even if \fB\-\-backup\fR is given)
+.TP
+numbered, t
+make numbered backups
+.TP
+existing, nil
+numbered if numbered backups exist, simple otherwise
+.TP
+simple, never
+always make simple backups
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or the SIMPLE_BACKUP_SUFFIX
+environment variable.
+.SS "Operation modifiers:"
+.TP
+\fB\-m\fR, \fB\-\-multi\-domain\fR
+apply ref.pot to each of the domains in def.po
+.TP
+\fB\-\-for\-msgfmt\fR
+produce output for 'msgfmt', not for a translator
+.TP
+\fB\-N\fR, \fB\-\-no\-fuzzy\-matching\fR
+do not use fuzzy matching
+.TP
+\fB\-\-previous\fR
+keep previous msgids of translated messages
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input files are in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input files are in NeXTstep/GNUstep .strings
+syntax
+.SS "Output details:"
+.TP
+\fB\-\-lang\fR=\fI\,CATALOGNAME\/\fR
+set 'Language' field in the header entry
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+indented output style
+.TP
+\fB\-\-no\-location\fR
+suppress '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+preserve '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+strict Uniforum output style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase verbosity level
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+suppress progress indicators
+.SH AUTHOR
+Written by Peter Miller.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgmerge
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgmerge
+programs are properly installed at your site, the command
+.IP
+.B info msgmerge
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msgunfmt.1 b/upstream/mageia-cauldron/man1/msgunfmt.1
new file mode 100644
index 00000000..4ed8bc40
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msgunfmt.1
@@ -0,0 +1,147 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGUNFMT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msgunfmt \- uncompile message catalog from binary format
+.SH SYNOPSIS
+.B msgunfmt
+[\fI\,OPTION\/\fR] [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Convert binary message catalog to Uniforum style .po file.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Operation mode:"
+.TP
+\fB\-j\fR, \fB\-\-java\fR
+Java mode: input is a Java ResourceBundle class
+.TP
+\fB\-\-csharp\fR
+C# mode: input is a .NET .dll file
+.TP
+\fB\-\-csharp\-resources\fR
+C# resources mode: input is a .NET .resources file
+.TP
+\fB\-\-tcl\fR
+Tcl mode: input is a tcl/msgcat .msg file
+.SS "Input file location:"
+.TP
+FILE ...
+input .mo files
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Input file location in Java mode:"
+.TP
+\fB\-r\fR, \fB\-\-resource\fR=\fI\,RESOURCE\/\fR
+resource name
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.PP
+The class name is determined by appending the locale name to the resource name,
+separated with an underscore.  The class is located using the CLASSPATH.
+.SS "Input file location in C# mode:"
+.TP
+\fB\-r\fR, \fB\-\-resource\fR=\fI\,RESOURCE\/\fR
+resource name
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-d\fR DIRECTORY
+base directory for locale dependent .dll files
+.PP
+The \fB\-l\fR and \fB\-d\fR options are mandatory.  The .dll file is located in a
+subdirectory of the specified directory whose name depends on the locale.
+.SS "Input file location in Tcl mode:"
+.TP
+\fB\-l\fR, \fB\-\-locale\fR=\fI\,LOCALE\/\fR
+locale name, either language or language_COUNTRY
+.TP
+\fB\-d\fR DIRECTORY
+base directory of .msg message catalogs
+.PP
+The \fB\-l\fR and \fB\-d\fR options are mandatory.  The .msg file is located in the
+specified directory.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write indented output style
+.TP
+\fB\-\-strict\fR
+write strict uniforum style
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase verbosity level
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msgunfmt
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msgunfmt
+programs are properly installed at your site, the command
+.IP
+.B info msgunfmt
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/msguniq.1 b/upstream/mageia-cauldron/man1/msguniq.1
new file mode 100644
index 00000000..fa67a704
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/msguniq.1
@@ -0,0 +1,138 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH MSGUNIQ "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+msguniq \- unify duplicate translations in message catalog
+.SH SYNOPSIS
+.B msguniq
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Unifies duplicate translations in a translation catalog.
+Finds duplicate translations of the same message ID.  Such duplicates are
+invalid input for other programs like msgfmt, msgmerge or msgcat.  By
+default, duplicates are merged together.  When using the \fB\-\-repeated\fR option,
+only duplicates are output, and all other messages are discarded.  Comments
+and extracted comments will be cumulated, except that if \fB\-\-use\-first\fR is
+specified, they will be taken from the first translation.  File positions
+will be cumulated.  When using the \fB\-\-unique\fR option, duplicates are discarded.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.SS "Input file location:"
+.TP
+INPUTFILE
+input PO file
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If no input file is given or if it is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-o\fR, \fB\-\-output\-file\fR=\fI\,FILE\/\fR
+write output to specified file
+.PP
+The results are written to standard output if no output file is specified
+or if it is \-.
+.SS "Message selection:"
+.TP
+\fB\-d\fR, \fB\-\-repeated\fR
+print only duplicates
+.TP
+\fB\-u\fR, \fB\-\-unique\fR
+print only unique messages, discard duplicates
+.SS "Input file syntax:"
+.TP
+\fB\-P\fR, \fB\-\-properties\-input\fR
+input file is in Java .properties syntax
+.TP
+\fB\-\-stringtable\-input\fR
+input file is in NeXTstep/GNUstep .strings syntax
+.SS "Output details:"
+.TP
+\fB\-t\fR, \fB\-\-to\-code\fR=\fI\,NAME\/\fR
+encoding for output
+.TP
+\fB\-\-use\-first\fR
+use first available translation for each
+message, don't merge several translations
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write the .po file using indented style
+.TP
+\fB\-\-no\-location\fR
+do not write '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+generate '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+write out strict Uniforum conforming .po file
+.TP
+\fB\-p\fR, \fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2001\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B msguniq
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B msguniq
+programs are properly installed at your site, the command
+.IP
+.B info msguniq
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/mshortname.1 b/upstream/mageia-cauldron/man1/mshortname.1
new file mode 100644
index 00000000..f58c23e3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mshortname.1
@@ -0,0 +1,95 @@
+'\" t
+.TH mshortname 1 "21Mar23" mtools-4.0.43
+.SH Name
+mshortname - shows short name of a file
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmshortname\fR command is used to display the short name of a
+file.  Syntax:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmshortname\fR \fIfiles\fR
+.fi
+.ft R
+ 
+.PP
+The shortname is displayed as it is stored in raw format on disk,
+without any character set conversion.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mshowfat.1 b/upstream/mageia-cauldron/man1/mshowfat.1
new file mode 100644
index 00000000..0312f8d8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mshowfat.1
@@ -0,0 +1,96 @@
+'\" t
+.TH mshowfat 1 "21Mar23" mtools-4.0.43
+.SH Name
+mshowfat - shows FAT clusters allocated to file
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmshowfat\fR command is used to display the FAT entries for a
+file.  Syntax:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmshowfat\fR [\fR\&\f(CW-o\fR \fIoffset\fR] \fIfiles\fR
+.fi
+.ft R
+ 
+.PP
+If no offset is given, a list of all clusters occupied by the file is
+printed. If an offset is given, only the number of the cluster
+containing that offset is printed.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mtools.1 b/upstream/mageia-cauldron/man1/mtools.1
new file mode 100644
index 00000000..09eadd7f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mtools.1
@@ -0,0 +1,503 @@
+'\" t
+.TH mtools 1 "21Mar23" mtools-4.0.43
+.SH Name
+mtools - utilities to access DOS disks in Unix.
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.PP
+.SH Introduction
+Mtools is a collection of tools to allow Unix systems to manipulate
+MS-DOS files: read, write, and move around files on an MS-DOS
+file system (typically a floppy disk).  Where reasonable, each program
+attempts to emulate the MS-DOS equivalent command. However,
+unnecessary restrictions and oddities of DOS are not emulated. For
+instance, it is possible to move subdirectories from one subdirectory
+to another.
+.PP
+Mtools is sufficient to give access to MS-DOS file systems.  For
+instance, commands such as \fR\&\f(CWmdir a:\fR work on the \fR\&\f(CWa:\fR floppy
+without any preliminary mounting or initialization (assuming the default
+\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR works on your machine).  With mtools, one can
+change floppies too without unmounting and mounting.
+.PP
+.SH Where\ to\ get\ mtools
+.PP
+Mtools can be found at the following places (and their mirrors):
+ 
+.nf
+.ft 3
+.in +0.3i
+http://ftp.gnu.org/gnu/mtools/mtools-4.0.43.tar.gz
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+These patches are named
+\&\fR\&\f(CWmtools-\fR\fIversion\fR\fR\&\f(CW-\fR\fIddmm\fR\fR\&\f(CW.taz\fR, where version
+stands for the base version, \fIdd\fR for the day and \fImm\fR for the
+month. Due to a lack of space, I usually leave only the most recent
+patch.
+.PP
+There is an mtools mailing list at info-mtools @ gnu.org .  Please
+send all bug reports to this list.  You may subscribe to the list at
+https://lists.gnu.org/mailman/listinfo/info-mtools. (N.B. Please
+remove the spaces around the "@". I left them there in order to fool
+spambots.)  Announcements of new mtools versions will also be sent to
+the list, in addition to the Linux announce newsgroups.  The mailing
+list is archived at http://lists.gnu.org/pipermail/info-mtools/
+.PP
+.SH Common\ features\ of\ all\ mtools\ commands
+.PP
+.SS Options\ and\ filenames
+MS-DOS filenames are composed of a drive letter followed by a colon, a
+subdirectory, and a filename. Only the filename part is mandatory, the
+drive letter and the subdirectory are optional. Filenames without a
+drive letter refer to Unix files. Subdirectory names can use either the
+\&'\fR\&\f(CW/\fR' or '\fR\&\f(CW\e\fR' separator.  The use of the '\fR\&\f(CW\e\fR' separator
+or wildcards requires the names to be enclosed in quotes to protect them
+from the shell. However, wildcards in Unix filenames should not be
+enclosed in quotes, because here we \fBwant\fR the shell to expand
+them.
+.PP
+The regular expression "pattern matching" routines follow the Unix-style
+rules.  For example, `\fR\&\f(CW*\fR' matches all MS-DOS files in lieu of
+`\fR\&\f(CW*.*\fR'.  The archive, hidden, read-only and system attribute bits
+are ignored during pattern matching.
+.PP
+All options use the \fR\&\f(CW-\fR (minus) as their first character, not
+\&\fR\&\f(CW/\fR as you'd expect in MS-DOS.
+.PP
+Most mtools commands allow multiple filename parameters, which
+doesn't follow MS-DOS conventions, but which is more user-friendly.
+.PP
+Most mtools commands allow options that instruct them how to handle
+file name clashes. See section name clashes, for more details on these.
+.PP
+All commands accept the \fR\&\f(CW-i\fR flag which allows to specify an
+image file (See section drive letters).
+.PP
+All commands accept the \fR\&\f(CW-V\fR flag which prints the version, and
+most accept the \fR\&\f(CW-v\fR flag, which switches on verbose mode. In
+verbose mode, these commands print out the name of the MS-DOS files
+upon which they act, unless stated otherwise. See section Commands, for a
+description of the options which are specific to each command.
+.PP
+.SS Drive\ letters
+.PP
+The meaning of the drive letters depends on the target architectures.
+However, on most target architectures, drive A is the first floppy
+drive, drive B is the second floppy drive (if available), drive J is a
+Jaz drive (if available), and drive Z is a Zip drive (if available).  On
+those systems where the device name is derived from the SCSI id, the Jaz
+drive is assumed to be at SCSI target 4, and the Zip at SCSI target 5
+(factory default settings).  On Linux, both drives are assumed to be the
+second drive on the SCSI bus (/dev/sdb). The default settings can be
+changes using a configuration file (see section  Configuration).
+.PP
+The drive letter : (colon) has a special meaning. It is used to access
+image files which are directly specified on the command line using the
+\&\fR\&\f(CW-i\fR options.
+.PP
+Example:
+ 
+.nf
+.ft 3
+.in +0.3i
+ mcopy -i my-image-file.bin ::file1 ::file2 .
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+This copies \fR\&\f(CWfile1\fR and \fR\&\f(CWfile2\fR from the image file
+(\fR\&\f(CWmy-image-file.bin\fR) to the \fR\&\f(CW/tmp\fR directory.
+.PP
+You can also supply an offset within the image file by including
+\&\fR\&\f(CW@@\fR\fIoffset\fR into the file name.
+.PP
+Example:
+ 
+.nf
+.ft 3
+.in +0.3i
+ mcopy -i my-image-file.bin@@1M ::file1 ::file2 .
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+This looks for the image at the offset of 1M in the file, rather than
+at its beginning.
+.PP
+.SS Current\ working\ directory
+.PP
+The \fR\&\f(CWmcd\fR command (\(ifmcd\(is) is used to establish the device and
+the current working directory (relative to the MS-DOS file system),
+otherwise the default is assumed to be \fR\&\f(CWA:/\fR. However, unlike
+MS-DOS, there is only one working directory for all drives, and not one
+per drive.
+.PP
+.SS VFAT-style\ long\ file\ names
+.PP
+This version of mtools supports VFAT style long filenames. If a Unix
+filename is too long to fit in a short DOS name, it is stored as a
+VFAT long name, and a companion short name is generated. This short
+name is what you see when you examine the disk with a pre-7.0 version
+of DOS.
+ The following table shows some examples of short names:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+Long name       MS-DOS name     Reason for the change
+---------       ----------      ---------------------
+thisisatest     THISIS~1        filename too long
+alain.knaff     ALAIN~1.KNA     extension too long
+prn.txt         PRN~1.TXT       PRN is a device name
+\&\&.abc            ABC~1           null filename
+hot+cold        HOT_CO~1        illegal character
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ As you see, the following transformations happen to derive a short
+name:
+.TP
+* \ \ 
+Illegal characters are replaced by underscores. The illegal characters
+are \fR\&\f(CW;+=[]',\e"*\e\e<>/?:|\fR.
+.TP
+* \ \ 
+Extra dots, which cannot be interpreted as a main name/extension
+separator are removed
+.TP
+* \ \ 
+A \fR\&\f(CW~\fR\fIn\fR number is generated,
+.TP
+* \ \ 
+The name is shortened so as to fit in the 8+3 limitation
+.PP
+ The initial Unix-style file name (whether long or short) is also called
+the \fIprimary\fR name, and the derived short name is also called the
+\&\fIsecondary\fR name.
+.PP
+ Example:
+ 
+.nf
+.ft 3
+.in +0.3i
+ mcopy /etc/motd a:Reallylongname
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR Mtools creates a VFAT entry for Reallylongname, and uses REALLYLO as
+a short name. Reallylongname is the primary name, and REALLYLO is the
+secondary name.
+ 
+.nf
+.ft 3
+.in +0.3i
+ mcopy /etc/motd a:motd
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR Motd fits into the DOS filename limits. Mtools doesn't need to
+derivate another name. Motd is the primary name, and there is no
+secondary name.
+.PP
+ In a nutshell: The primary name is the long name, if one exists, or
+the short name if there is no long name.
+.PP
+ Although VFAT is much more flexible than FAT, there are still names
+that are not acceptable, even in VFAT. There are still some illegal
+characters left (\fR\&\f(CW\e"*\e\e<>/?:|\fR), and device names are still
+reserved.
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+Unix name       Long name       Reason for the change
+---------       ----------      ---------------------
+prn             prn-1           PRN is a device name
+ab:c            ab_c-1          illegal character
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+ As you see, the following transformations happen if a long name is
+illegal:
+.TP
+* \ \ 
+Illegal characters are replaces by underscores,
+.TP
+* \ \ 
+A \fR\&\f(CW-\fR\fIn\fR number is generated,
+.PP
+.SS Name\ clashes
+.PP
+When writing a file to disk, its long name or short name may collide
+with an already existing file or directory. This may happen for all
+commands which create new directory entries, such as \fR\&\f(CWmcopy\fR,
+\&\fR\&\f(CWmmd\fR, \fR\&\f(CWmren\fR, \fR\&\f(CWmmove\fR. When a name clash happens, mtools
+asks you what it should do. It offers several choices:
+.TP
+\&\fR\&\f(CWoverwrite\fR\ 
+Overwrites the existing file. It is not possible to overwrite a
+directory with a file.
+.TP
+\&\fR\&\f(CWrename\fR\ 
+Renames the newly created file. Mtools prompts for the new filename
+.TP
+\&\fR\&\f(CWautorename\fR\ 
+Renames the newly created file. Mtools chooses a name by itself, without
+prompting
+.TP
+\&\fR\&\f(CWskip\fR\ 
+Gives up on this file, and moves on to the next (if any)
+.PP
+To chose one of these actions, type its first letter at the prompt. If
+you use a lower case letter, the action only applies for this file only,
+if you use an upper case letter, the action applies to all files, and
+you won't be prompted again.
+.PP
+You may also chose actions (for all files) on the command line, when
+invoking mtools:
+.TP
+\&\fR\&\f(CW-D\ o\fR\ 
+Overwrites primary names by default.
+.TP
+\&\fR\&\f(CW-D\ O\fR\ 
+Overwrites secondary names by default.
+.TP
+\&\fR\&\f(CW-D\ r\fR\ 
+Renames primary name by default.
+.TP
+\&\fR\&\f(CW-D\ R\fR\ 
+Renames secondary name by default.
+.TP
+\&\fR\&\f(CW-D\ a\fR\ 
+Autorenames primary name by default.
+.TP
+\&\fR\&\f(CW-D\ A\fR\ 
+Autorenames secondary name by default.
+.TP
+\&\fR\&\f(CW-D\ s\fR\ 
+Skip primary name by default.
+.TP
+\&\fR\&\f(CW-D\ S\fR\ 
+Skip secondary name by default.
+.TP
+\&\fR\&\f(CW-D\ m\fR\ 
+Ask user what to do with primary name.
+.TP
+\&\fR\&\f(CW-D\ M\fR\ 
+Ask user what to do with secondary name.
+.PP
+Note that for command line switches lower/upper differentiates between
+primary/secondary name whereas for interactive choices, lower/upper
+differentiates between just-this-time/always.
+.PP
+The primary name is the name as displayed in Windows 95 or Windows NT:
+i.e. the long name if it exists, and the short name otherwise.  The
+secondary name is the "hidden" name, i.e. the short name if a long name
+exists.
+.PP
+By default, the user is prompted if the primary name clashes, and the
+secondary name is autorenamed.
+.PP
+If a name clash occurs in a Unix directory, mtools only asks whether
+to overwrite the file, or to skip it.
+.PP
+.SS Case\ sensitivity\ of\ the\ VFAT\ file\ system
+.PP
+The VFAT file system is able to remember the case of the
+filenames. However, filenames which differ only in case are not allowed
+to coexist in the same directory. For example if you store a file called
+LongFileName on a VFAT file system, mdir shows this file as LongFileName,
+and not as Longfilename. However, if you then try to add LongFilename to
+the same directory, it is refused, because case is ignored for clash
+checks.
+.PP
+The VFAT file system allows you to store the case of a filename in the
+attribute byte, if all letters of the filename are the same case, and if
+all letters of the extension are the same case too. Mtools uses this
+information when displaying the files, and also to generate the Unix
+filename when mcopying to a Unix directory. This may have unexpected
+results when applied to files written using an pre-7.0 version of DOS:
+Indeed, the old style filenames map to all upper case. This is different
+from the behavior of the old version of mtools which used to generate
+lower case Unix filenames.
+.PP
+.SS high\ capacity\ formats
+.PP
+Mtools supports a number of formats which allow storage of more data on
+disk than usual. Due to different operating system abilities, these
+formats are not supported on all operating systems. Mtools recognizes
+these formats transparently where supported.
+.PP
+In order to format these disks, you need to use an operating system
+specific tool. For Linux, suitable floppy tools can be found in the
+\&\fR\&\f(CWfdutils\fR package at the following locations~:
+ 
+.nf
+.ft 3
+.in +0.3i
+\&\fR\&\f(CWhttp://www.fdutils.linux.lu/.
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+See the manual pages included in that package for further detail: Use
+\&\fR\&\f(CWsuperformat\fR to format all formats except XDF, and use
+\&\fR\&\f(CWxdfcopy\fR to format XDF.
+.PP
+.SS \ \ More\ sectors
+.PP
+The oldest method of fitting more data on a disk is to use more sectors
+and more cylinders. Although the standard format uses 80 cylinders and
+18 sectors (on a 3 1/2 high density disk), it is possible to use up to
+83 cylinders (on most drives) and up to 21 sectors. This method allows
+to store up to 1743K on a 3 1/2 HD disk. However, 21 sector disks are
+twice as slow as the standard 18 sector disks because the sectors are
+packed so close together that we need to interleave them. This problem
+doesn't exist for 20 sector formats.
+.PP
+These formats are supported by numerous DOS shareware utilities such as
+\&\fR\&\f(CWfdformat\fR and \fR\&\f(CWvgacopy\fR. In his infinite hubris, Bill Gate$
+believed that he invented this, and called it \fR\&\f(CW\(ifDMF disks\(is\fR, or
+\&\fR\&\f(CW\(ifWindows formatted disks\(is\fR. But in reality, it has already existed
+years before! Mtools supports these formats on Linux, on SunOS and on
+the DELL Unix PC.
+.PP
+.SS \ \ Bigger\ sectors
+By using bigger sectors it is possible to go beyond the capacity which
+can be obtained by the standard 512-byte sectors. This is because of the
+sector header. The sector header has the same size, regardless of how
+many data bytes are in the sector. Thus, we save some space by using
+\&\fIfewer\fR, but bigger sectors. For example, 1 sector of 4K only takes
+up header space once, whereas 8 sectors of 512 bytes have also 8
+headers, for the same amount of useful data.
+.PP
+This method permits storage of up to 1992K on a 3 1/2 HD disk.
+.PP
+Mtools supports these formats only on Linux.
+.PP
+.SS \ \ 2m
+.PP
+The 2m format was originally invented by Ciriaco Garcia de Celis. It
+also uses bigger sectors than usual in order to fit more data on the
+disk.  However, it uses the standard format (18 sectors of 512 bytes
+each) on the first cylinder, in order to make these disks easier to
+handle by DOS. Indeed this method allows you to have a standard sized
+boot sector, which contains a description of how the rest of the disk
+should be read.
+.PP
+However, the drawback of this is that the first cylinder can hold less
+data than the others. Unfortunately, DOS can only handle disks where
+each track contains the same amount of data. Thus 2m hides the fact that
+the first track contains less data by using a \fIshadow
+FAT\fR. (Usually, DOS stores the FAT in two identical copies, for
+additional safety.  XDF stores only one copy, but tells DOS that it
+stores two. Thus the space that would be taken up by the second FAT copy
+is saved.) This also means that you should \fBnever use a 2m disk
+to store anything else than a DOS file system\fR.
+.PP
+Mtools supports these formats only on Linux.
+.PP
+.SS \ \ XDF
+.PP
+XDF is a high capacity format used by OS/2. It can hold 1840 K per
+disk. That's lower than the best 2m formats, but its main advantage is
+that it is fast: 600 milliseconds per track. That's faster than the 21
+sector format, and almost as fast as the standard 18 sector format. In
+order to access these disks, make sure mtools has been compiled with XDF
+support, and set the \fR\&\f(CWuse_xdf\fR variable for the drive in the
+configuration file. See section Compiling mtools, and \(ifmiscellaneous variables\(is,
+for details on how to do this. Fast XDF access is only available for
+Linux kernels which are more recent than 1.1.34.
+.PP
+Mtools supports this format only on Linux.
+.PP
+\&\fBCaution / Attention distributors\fR: If mtools is compiled on a
+Linux kernel more recent than 1.3.34, it won't run on an older
+kernel. However, if it has been compiled on an older kernel, it still
+runs on a newer kernel, except that XDF access is slower. It is
+recommended that distribution authors only include mtools binaries
+compiled on kernels older than 1.3.34 until 2.0 comes out. When 2.0 will
+be out, mtools binaries compiled on newer kernels may (and should) be
+distributed. Mtools binaries compiled on kernels older than 1.3.34 won't
+run on any 2.1 kernel or later.
+.PP
+.SS Exit\ codes
+All the Mtools commands return 0 on success, 1 on utter failure, or 2
+on partial failure.  All the Mtools commands perform a few sanity
+checks before going ahead, to make sure that the disk is indeed an
+MS-DOS disk (as opposed to, say an ext2 or MINIX disk). These checks
+may reject partially corrupted disks, which might otherwise still be
+readable. To avoid these checks, set the MTOOLS_SKIP_CHECK
+environmental variable or the corresponding configuration file variable
+(see section  global variables)
+.SS Bugs
+An unfortunate side effect of not guessing the proper device (when
+multiple disk capacities are supported) is an occasional error message
+from the device driver.  These can be safely ignored.  
+.PP
+The fat checking code chokes on 1.72 Mb disks mformatted with pre-2.0.7
+mtools. Set the environmental variable MTOOLS_FAT_COMPATIBILITY (or the
+corresponding configuration file variable, \(ifglobal variables\(is) to
+bypass the fat checking.
+.PP
+.SH See also
+floppyd_installtest
+mattrib
+mbadblocks
+mcd
+mcopy
+mdel
+mdeltree
+mdir
+mdu
+mformat
+minfo
+mkmanifest
+mlabel
+mmd
+mmount
+mmove
+mrd
+mren
+mshortname
+mshowfat
+mtoolstest
+mtype
diff --git a/upstream/mageia-cauldron/man1/mtoolstest.1 b/upstream/mageia-cauldron/man1/mtoolstest.1
new file mode 100644
index 00000000..c1070430
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mtoolstest.1
@@ -0,0 +1,90 @@
+'\" t
+.TH mtoolstest 1 "21Mar23" mtools-4.0.43
+.SH Name
+mtoolstest - tests and displays the configuration
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmtoolstest\fR command is used to tests the mtools configuration
+files. To invoke it, just type \fR\&\f(CWmtoolstest\fR without any arguments.
+\&\fR\&\f(CWMtoolstest\fR reads the mtools configuration files, and prints the
+cumulative configuration to \fR\&\f(CWstdout\fR. The output can be used as a
+configuration file itself (although you might want to remove redundant
+clauses).  You may use this program to convert old-style configuration
+files into new style configuration files.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/mtrace.1 b/upstream/mageia-cauldron/man1/mtrace.1
new file mode 100644
index 00000000..0483a31b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mtrace.1
@@ -0,0 +1,47 @@
+.\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.com)
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.TH mtrace 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+mtrace \- interpret the malloc trace log
+.SH SYNOPSIS
+.nf
+.BR mtrace " [\fIoption\fR]... [\fIbinary\fR] \fImtracedata\fR"
+.fi
+.SH DESCRIPTION
+.B mtrace
+is a Perl script used to interpret and provide human readable output
+of the trace log contained in the file
+.IR mtracedata ,
+whose contents were produced by
+.BR mtrace (3).
+If
+.I binary
+is provided, the output of
+.B mtrace
+also contains the source file name with line number information
+for problem locations
+(assuming that
+.I binary
+was compiled with debugging information).
+.P
+For more information about the
+.BR mtrace (3)
+function and
+.B mtrace
+script usage, see
+.BR mtrace (3).
+.SH OPTIONS
+.TP
+.B \-\-help
+Print help and exit.
+.TP
+.B \-\-version
+Print version information and exit.
+.SH BUGS
+For bug reporting instructions, please see:
+.UR http://www.gnu.org/software/libc/bugs.html
+.UE .
+.SH SEE ALSO
+.BR memusage (1),
+.BR mtrace (3)
diff --git a/upstream/mageia-cauldron/man1/mtvtoppm.1 b/upstream/mageia-cauldron/man1/mtvtoppm.1
new file mode 100644
index 00000000..4cfefa53
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mtvtoppm.1
@@ -0,0 +1,55 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Mtvtoppm User Manual" 0 "02 February 1989" "netpbm documentation"
+
+.SH NAME
+
+mtvtoppm - convert output from an MTV or PRT ray tracer into a PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBmtvtoppm\fP
+[\fImtvfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBmtvtoppm\fP reads an input file from Mark VanDeWettering's MTV
+ray tracer and produces a PPM image as output.
+.PP
+The PRT raytracer also produces this format.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBmtvtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/mtvtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/mtype.1 b/upstream/mageia-cauldron/man1/mtype.1
new file mode 100644
index 00000000..39b8900d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mtype.1
@@ -0,0 +1,114 @@
+'\" t
+.TH mtype 1 "21Mar23" mtools-4.0.43
+.SH Name
+mtype - display contents of an MSDOS file
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmtype\fR command is used to display contents of an MS-DOS
+file. Its syntax is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmtype\fR [\fR\&\f(CW-ts\fR] \fImsdosfile\fR [ \fImsdosfiles\fR\&... ]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMtype\fR displays the specified MS-DOS file on the screen.
+.PP
+In addition to the standard options, \fR\&\f(CWMtype\fR allows the following
+command line options:
+.TP
+\&\fR\&\f(CWt\fR\ 
+Text file viewing.  \fR\&\f(CWMtype\fR translates incoming carriage
+return/line feeds to line feeds.
+.TP
+\&\fR\&\f(CWs\fR\ 
+\&\fR\&\f(CWMtype\fR strips the high bit from the data.
+.PP
+The \fR\&\f(CWmcd\fR command may be used to establish the device and the
+current working directory (relative to MS-DOS), otherwise the default is
+\&\fR\&\f(CWA:/\fR.
+.PP
+\&\fR\&\f(CWMtype\fR returns 0 on success, 1 on utter failure, or 2 on partial
+failure.
+.PP
+Unlike the MS-DOS version of \fR\&\f(CWTYPE\fR, \fR\&\f(CWmtype\fR allows multiple
+arguments.
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/musicxml2ly.1 b/upstream/mageia-cauldron/man1/musicxml2ly.1
new file mode 100644
index 00000000..ca9e9a0b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/musicxml2ly.1
@@ -0,0 +1,122 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.TH MUSICXML2LY "1" "January 2024" "musicxml2ly (LilyPond) 2.24.3" "User Commands"
+.SH NAME
+musicxml2ly \- manual page for musicxml2ly (LilyPond) 2.24.3
+.SH SYNOPSIS
+.B musicxml2ly
+[\fI\,OPTION\/\fR]... \fI\,FILE.xml\/\fR
+.SH DESCRIPTION
+Convert MusicXML from FILE.xml to LilyPond input.
+If the given filename is \-, musicxml2ly reads from the command line.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help and exit
+.TP
+\fB\-\-version\fR
+show version number and exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+be verbose
+.TP
+\fB\-\-lxml\fR
+use lxml.etree; uses less memory and cpu time
+.TP
+\fB\-z\fR, \fB\-\-compressed\fR
+input file is a compressed MusicXML file (by default,
+activate if file extension is .mxl)
+.TP
+\fB\-r\fR, \fB\-\-relative\fR
+convert pitches in relative mode (default)
+.TP
+\fB\-a\fR, \fB\-\-absolute\fR
+convert pitches in absolute mode
+.TP
+\fB\-l\fR, \fB\-\-language\fR=\fI\,LANG\/\fR
+use LANG for pitch names, e.g. 'deutsch' for note
+names in German
+.TP
+\fB\-\-loglevel\fR=\fI\,LOGLEVEL\/\fR
+Print log messages according to LOGLEVEL (NONE, ERROR,
+WARNING, PROGRESS (default), DEBUG)
+.TP
+\fB\-\-nd\fR \fB\-\-no\-articulation\-directions\fR
+do not convert directions (^, _ or \-) for
+articulations, dynamics, etc.
+.TP
+\fB\-\-nrp\fR \fB\-\-no\-rest\-positions\fR
+do not convert exact vertical positions of rests
+.TP
+\fB\-\-nsb\fR \fB\-\-no\-system\-breaks\fR
+ignore system breaks
+.TP
+\fB\-\-npb\fR \fB\-\-no\-page\-breaks\fR
+ignore page breaks
+.TP
+\fB\-\-npm\fR \fB\-\-no\-page\-margins\fR
+ignore page margins
+.TP
+\fB\-\-npl\fR \fB\-\-no\-page\-layout\fR
+do not convert the exact page layout and breaks
+(shortcut for "\-\-nsb \fB\-\-npb\fR \fB\-\-npm\fR" options)
+.TP
+\fB\-\-nsd\fR \fB\-\-no\-stem\-directions\fR
+ignore stem directions from MusicXML, use lilypond's
+automatic stemming instead
+.TP
+\fB\-\-nb\fR \fB\-\-no\-beaming\fR
+do not convert beaming information, use lilypond's
+automatic beaming instead
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+set output filename to FILE, stdout if \-
+.TP
+\fB\-m\fR, \fB\-\-midi\fR
+activate midi\-block in .ly file
+.TP
+\fB\-\-transpose\fR=\fI\,TOPITCH\/\fR
+set pitch to transpose by the interval between pitch
+\&'c' and TOPITCH
+.TP
+\fB\-\-sm\fR \fB\-\-shift\-meter\fR=\fI\,BEATS\/\fR/BEATTYPE
+change the length|duration of notes as a function of a
+given time signature to make the score look faster or
+slower, (eg. '4/4' or '2/2')
+.TP
+\fB\-\-tc\fR \fB\-\-tab\-clef\fR=\fI\,TABCLEFNAME\/\fR
+switch between two versions of tab clefs ("tab" and
+"moderntab")
+.TP
+\fB\-\-sn\fR \fB\-\-string\-numbers\fR=\fI\,t[rue]\/\fR/f[alse]
+deactivate string number stencil with \fB\-\-string\-numbers\fR
+f[alse]. Default is t[rue]
+.TP
+\fB\-\-fb\fR \fB\-\-fretboards\fR
+converts '<frame>' events to a separate FretBoards
+voice instead of markups
+.SH "REPORTING BUGS"
+Report bugs via bug\-lilypond@gnu.org
+.SH COPYRIGHT
+Copyright \(co 2005\-\-2023 by
+.IP
+Han\-Wen Nienhuys <hanwen@xs4all.nl>,
+Jan Nieuwenhuizen <janneke@gnu.org> and
+Reinhold Kainhofer <reinhold@kainhofer.com>
+Patrick L. Schmidt <pls@philomelos.net>
+.PP
+This program is free software.  It is covered by the GNU General Public
+License and you are welcome to change it and/or distribute copies of it
+under certain conditions.  Invoke as `lilypond \fB\-\-warranty\fR' for more
+information.
+.SH "SEE ALSO"
+The full documentation for
+.B musicxml2ly
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B musicxml2ly
+programs are properly installed at your site, the command
+.IP
+.B info musicxml2ly
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/mute.1 b/upstream/mageia-cauldron/man1/mute.1
new file mode 100644
index 00000000..0551843d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mute.1
@@ -0,0 +1,58 @@
+.\" $Aumix: aumix/doc/mute.1,v 1.1 2002/12/12 01:59:52 trevor Exp $
+.\" from mdoc.samples(7)
+.\"
+.\" The following requests are required for all man pages.
+.\"           .Dd Month day, year
+.\"           .Os OPERATING_SYSTEM [version/release]
+.\"           .Dt DOCUMENT_TITLE [section number] [volume]
+.\"           .Sh NAME
+.\"           .Nm name
+.\"           .Nd one line description of name
+.\"           .Sh SYNOPSIS
+.\"           .Sh DESCRIPTION
+.\" The following requests should be uncommented and
+.\" used where appropriate.  This next request is
+.\" for sections 2, 3 and 9 function return values only.
+.\" .Sh RETURN VALUES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\" .Sh ENVIRONMENT
+.\" .Sh FILES
+.\" .Sh EXAMPLES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\"     (command return values (to shell) and
+.\"       fprintf/stderr type diagnostics)
+.\" .Sh DIAGNOSTICS
+.\" The next request is for sections 2, 3 and 9 error
+.\" and signal handling only.
+.\" .Sh ERRORS
+.\" .Sh SEE ALSO
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.\" .Sh BUGS
+.\"
+.Dd December 11, 2002
+.Os
+.Dt MUTE 1
+.Sh NAME
+.Nm mute
+.Nd use aumix to mute and un-mute sound output
+.Sh SYNOPSIS
+This command does not take any command-line arguments.
+.Sh DESCRIPTION
+.Nm
+is a small script that uses 
+aumix
+to conveniently mute and un-mute sound. If sound is currently not
+muted, running
+.Nm
+will save your current settings to ~/.aumixrc (or /etc/aumixrc if
+you are root) and mute the sound.  Running
+.Nm
+again will restore the settings.
+.Sh BUGS
+The current ~/.aumixrc or /etc/aumixrc will be overwritten.
+.Sh AUTHORS
+Ben Ford
+.Sh SEE ALSO
+.Xr aumix 1
diff --git a/upstream/mageia-cauldron/man1/mutt.1 b/upstream/mageia-cauldron/man1/mutt.1
new file mode 100644
index 00000000..ec175e61
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mutt.1
@@ -0,0 +1,339 @@
+.\" -*-nroff-*-
+.\"
+.\"
+.\"     Copyright (C) 1996-2023 Michael R. Elkins <me@cs.hmc.edu>
+.\" 
+.\"     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 2 of the License, or
+.\"     (at your option) any later version.
+.\" 
+.\"     This program is distributed in the hope that it will be useful,
+.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"     GNU General Public License for more details.
+.\" 
+.\"     You should have received a copy of the GNU General Public License
+.\"     along with this program; if not, write to the Free Software
+.\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+.\"
+.TH MUTT 1 "July 24, 2020" Unix "User Manuals"
+.SH NAME
+mutt \- The Mutt Mail User Agent
+.SH SYNOPSIS
+.TP 6
+.B mutt
+[\fB\-nRyzZ\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+[\fB\-m \fItype\fR]
+[\fB\-f \fImailbox\fR]
+.TP 6
+.B mutt
+[\fB\-Enx\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+[\fB\-H \fIdraft\fR]
+[\fB\-i \fIinclude\fR]
+.br
+[\fB\-b \fIbcc-addr\fR]
+[\fB\-c \fIcc-addr\fR]
+[\fB\-s \fIsubject\fR]
+.br
+[\fB\-a \fIfile ... \fB\-\-\fR]
+\fIto-addr ...
+.TP 6
+.B mutt
+[\fB\-nx\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+[\fB\-b \fIbcc-addr\fR]
+[\fB\-c \fIcc-addr\fR]
+.br
+[\fB\-s \fIsubject\fR]
+[\fB\-a \fIfile ... \fB\-\-\fR]
+\fIto-addr ... \fR< message
+.TP 6
+.B mutt
+[\fB\-n\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+\fB\-p
+.TP 6
+.B mutt
+[\fB\-n\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+\fB\-A \fIalias
+.TP 6
+.B mutt
+[\fB\-n\fR]
+[\fB\-e \fIcommand\fR]
+[\fB\-F \fIrcfile\fR]
+\fB\-Q \fIvariable
+.TP 6
+.B mutt
+\fB\-v\fR[\fBv\fR]
+.TP 6
+.B mutt
+\fB\-D
+.SH DESCRIPTION
+.PP
+Mutt is a small but very powerful text based program for reading and sending electronic
+mail under unix operating systems, including support for color terminals, MIME,
+OpenPGP, and a threaded sorting mode.
+.PP
+.BR Note :
+This manual page gives a brief overview of the \fBmutt\fP executable command
+line options.
+A copy of the full manual is located in \fI/usr/share/doc/mutt-doc\fP, in text, HTML, and/or
+PDF format.
+Please refer to the manual to learn how to use and configure Mutt.
+.SH OPTIONS
+.TP
+.BI \-A " alias"
+Print an expanded version of the given \fIalias\fP and exit.
+.TP
+.BI \-a " file ... "
+Attach a \fIfile\fP using MIME.
+Separating \fIfile\fP and \fIto-addr\fP arguments with \*(lq\fB\-\-\fP\*(rq is
+mandatory.
+For example:
+.sp
+.in +4m
+.nf
+mutt \-a image.jpg \-\- to-addr
+mutt \-a img.jpg *.png \-\- to-addr-1 to-addr-2
+.fi
+.in
+.sp
+The \fB\-a\fP option must be placed at the end of command line options.
+.TP
+.BI \-b " bcc-addr"
+Specify a blind carbon copy (BCC) address.
+.TP
+.BI \-c " cc-addr"
+Specify a carbon copy (CC) address.
+.TP
+.BI \-d " level"
+If Mutt was compiled with \fB+DEBUG\fP log debugging output to
+\fI~/.muttdebug0\fP.
+\fILevel\fP can range from -5 to 5 and affects verbosity. A value of
+zero disables debugging. A value less than zero disables automatic log
+file rotation; the log level is then its absolute value. A value of 2
+(-2) is recommended for most diagnosis.
+.TP
+.B \-D
+Print the value of all configuration options to stdout.
+.TP
+.B \-E
+Edit the \fIdraft\fP file specified by \fB\-H\fP or \fIinclude\fP file
+specified by \fB-i\fP during message composition.
+.TP
+.BI \-e " command"
+Specify a configuration \fIcommand\fP to be run after processing of
+initialization files.
+.TP
+.BI \-f " mailbox"
+Specify a \fImailbox\fP to load.
+.TP
+.BI \-F " rcfile"
+Use \fIrcfile\fP instead of the user configuration file.
+.TP
+.B \-h
+Display a short option summary and exit.
+.TP
+.BI \-H " draft"
+Specify a \fIdraft\fP file which contains header and body to use to
+send a message.  If \fIdraft\fP is \*(lq\fB\-\fP\*(rq, then data is
+read from stdin.  The draft file is expected to contain just an RFC822
+email \(em headers and a body.  Although it is not an mbox file, if an
+mbox "\fBFrom\~\fP" line is present, it will be silently discarded.
+Draft files are processed the same in interactive and batch mode; they
+are not passed through untouched.  For example, encrypted draft files
+will be decrypted.
+.TP
+.BI \-i " include"
+Specify an \fIinclude\fP file to be inserted into the body of a message.
+Ignored if \fB\-H\fP is set.
+If \fIinclude\fP is \*(lq\fB\-\fP\*(rq, then data is read from stdin.
+.TP
+.BI \-m " type"
+Specify a default mailbox \fItype\fP for newly created folders.
+Can be one of the following: mbox, MMDF, MH or Maildir.
+See also \fB$mbox_type\fP in the manual.
+.TP
+.B \-n
+Do not read the system-wide Muttrc configuration file.
+.TP
+.B \-p
+Resume a postponed message.
+Exit immediately if there are no postponed messages.
+.TP
+.BI \-Q " variable"
+Query a configuration \fIvariable\fP.
+The query is performed after all configuration files have been parsed, and any
+\fIcommands\fP given on the command line have been executed.
+.TP
+.B \-R
+Open a mailbox in read-only mode.
+.TP
+.BI \-s " subject"
+Specify the \fIsubject\fP of the message.
+Must be enclosed in quotes if it contains spaces.
+.TP
+.B \-v
+Display the Mutt version number and compile-time definitions.
+.TP
+.B \-vv
+Display license and copyright information.
+.TP
+.B \-x
+Emulate the
+.BR mailx (1)
+compose mode.
+.TP
+.B \-y
+Start Mutt with a listing of all mailboxes specified by the \fImailboxes\fP
+configuration command.
+.TP
+.B \-z
+Exit immediately with code 1 if \fImailbox\fP specified by \fB\-f\fP does not
+contain any messages.
+.TP
+.B \-Z
+Open the first mailbox specified by the \fImailboxes\fP configuration command
+which contains new mail.
+Exit immediately with code 1 if there is no new mail in any of them.
+.TP
+.B \-\-
+Treat remaining arguments as \fIto-addr\fP even if they start with a dash.
+See also \fB\-a\fP above.
+\fITo-addr\fP can be a local or network mail address as well as mailto: URL.
+.SH ENVIRONMENT
+.IP "EDITOR, VISUAL"
+Specifies the editor to use when composing messages.
+If both EDITOR and VISUAL are set, VISUAL takes precedence.
+If neither EDITOR nor VISUAL are set, the default is
+.BR vi (1).
+.IP "EGDSOCKET, RANDFILE"
+Paths used to initialize the random engine for SSL library.
+.IP "EMAIL"
+The user's e-mail address.
+.IP "HOME"
+Full path of the user's home directory.
+.IP "MAIL"
+Full path of the user's spool mailbox.
+.IP "MAILDIR"
+Full path of the user's spool mailbox if MAIL is unset.
+Commonly used when the spool mailbox is a
+.BR maildir (5)
+folder.
+.IP "MAILCAPS"
+Path to search for mailcap files.
+.IP "MM_NOASK"
+If this variable is set, mailcap are always used without prompting first.
+.IP "PGPPATH"
+Directory in which the user's PGP public keyring can be found.
+When used with the original PGP program, mutt and
+.BR mutt_pgpring (1)
+rely on this being set.
+.IP "REPLYTO"
+Default Reply-To address.
+.IP "TMPDIR"
+Directory in which temporary files are created.
+If unset, \fI/tmp\fP is used.
+See also $tmpdir configuration variable.
+.IP "LC_ALL, LC_CTYPE, LANG"
+Used to determine charset and locale to use.
+.IP TEXTDOMAINDIR
+Directory containing translation files.
+If set, this path overwrite the Mutt installation directory.
+Used for testing translation changes.
+.SH FILES
+.TP
+.I ~/.muttrc
+.TQ
+.I ~/.mutt/muttrc
+.TQ
+.I $XDG_CONFIG_HOME/mutt/muttrc
+User configuration files.
+.TP
+.I /etc/Muttrc or /usr/share/mutt/Muttrc
+System-wide configuration file.
+.TP
+.I /tmp/muttXXXXXX
+Temporary files created by Mutt.
+.TP
+.I ~/.muttdebug0
+File containing debugging output.
+Log files are automatically rotated by \fBmutt\fP changing the number at the end.
+See \fB\-d\fP option above.
+.TP
+.I ~/.mailcap
+User definition for handling non-text MIME types.
+.TP
+.I /etc/mailcap
+System definition for handling non-text MIME types.
+.TP
+.I ~/.mime.types
+User's personal mapping between MIME types and file extensions.
+.TP
+.I /etc/mime.types
+System mapping between MIME types and file extensions.
+.TP
+.I /usr/bin/mutt_dotlock
+The privileged dotlocking program.
+.TP
+.I /usr/share/doc/mutt-doc/manual.txt
+The Mutt manual.
+.SH BUGS
+.PP
+None.  Mutts have fleas, not bugs.
+.SH FLEAS
+.PP
+Suspend/resume while editing a file with an external editor does not work
+under SunOS 4.x if you use the curses lib in /usr/5lib.  It \fIdoes\fP work
+with the S-Lang library, however.
+.PP
+Resizing the screen while using an external pager causes Mutt to go haywire
+on some systems.
+.PP
+Suspend/resume does not work under Ultrix.
+.PP
+The help line for the index menu is not updated if you change the bindings
+for one of the functions listed while Mutt is running.
+.PP
+For a more up-to-date list of bugs, errm, fleas, please visit the
+mutt project's bug tracking system under https://gitlab.com/muttmua/mutt/issues.
+.SH NO WARRANTIES
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+.SH SEE ALSO
+.PP
+.BR mutt_dotlock (1),
+.BR mutt_pgpring (1),
+.BR pgpewrap (1),
+.BR sendmail (1),
+.BR smail (1),
+.BR smime_keys (1),
+.BR curses (3),
+.BR ncurses (3),
+.BR mailcap (5),
+.BR maildir (5),
+.BR mbox (5),
+.BR mmdf (5),
+.BR muttrc (5)
+.PP
+Mutt Home Page: http://www.mutt.org/
+.PP
+The Mutt manual
+.PP
+RFC5322 \(em Internet Message Format: https://tools.ietf.org/rfcmarkup/5322
+(obsoletes RFC2822 and RFC822)
+.SH AUTHOR
+.PP
+Michael Elkins, and others.
+Use <mutt-dev@mutt.org> to contact the developers.
diff --git a/upstream/mageia-cauldron/man1/mutt_dotlock.1 b/upstream/mageia-cauldron/man1/mutt_dotlock.1
new file mode 100644
index 00000000..39768c47
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mutt_dotlock.1
@@ -0,0 +1,150 @@
+.\" -*-nroff-*-
+.\"
+.\"
+.\"     Copyright (C) 1996-8 Michael R. Elkins <me@cs.hmc.edu>
+.\"	Copyright (C) 1998-9 Thomas Roessler <roessler@does-not-exist.org>
+.\" 
+.\"     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 2 of the License, or
+.\"     (at your option) any later version.
+.\" 
+.\"     This program is distributed in the hope that it will be useful,
+.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"     GNU General Public License for more details.
+.\" 
+.\"     You should have received a copy of the GNU General Public License
+.\"     along with this program; if not, write to the Free Software
+.\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+.\"
+.TH dotlock 1 "AUGUST 1999" Unix "User Manuals"
+.SH NAME
+mutt_dotlock \- Lock mail spool files.
+.SH SYNOPSIS
+.PP
+.B mutt_dotlock 
+[\-t|\-f|\-u|\-d] [\-p] [\-r \fIretries\fP] \fIfile\fP
+.SH DESCRIPTION
+.PP
+.B mutt_dotlock
+implements the traditional mail spool file locking method:
+To lock \fIfile\fP, a file named \fIfile\fP.lock is
+created. The program operates with group mail privileges
+if necessary.
+.SH OPTIONS
+.PP
+.IP "-t"
+Just try.
+.B mutt_dotlock
+won't actually lock a file, but inform the invoking
+process if it's at all possible to lock \fIfile\fP.
+.IP "-f"
+Force the lock.  If another process holds a lock on
+\fIfile\fP longer than a certain amount of time, 
+.B mutt_dotlock
+will break that lock by removing the lockfile.
+.IP "-u"
+Unlock.
+.B mutt_dotlock 
+will remove \fIfile\fP.lock.
+.IP "-d"
+Delete.
+.B mutt_dotlock
+will lock \fIfile\fP, remove it if it has length 0, and afterwards
+remove \fIfile\fP.lock.
+.IP "-p"
+Use privileges.  If given this option, 
+.B mutt_dotlock
+will operate with group mail privileges when creating and
+deleting lock files.
+.IP "-r \fIretries\fP"
+This command line option tells 
+.B mutt_dotlock 
+to try locking
+\fIretries\fP times before giving up or (if invoked with
+the 
+.B -f
+command line option) break a lock.  The default value is 5.
+.B mutt_dotlock
+waits one second between successive locking attempts.  
+.SH FILES
+.PP
+.IP "\fIfile\fP.lock"
+The lock file 
+.B mutt_dotlock
+generates.
+.SH SEE ALSO
+.PP
+.BR fcntl (2),
+.BR flock (2),
+.BR lockfile (1),
+.BR mutt (1)
+.SH DIAGNOSTICS
+.PP
+.B mutt_dotlock
+gives all diagnostics in its return values:
+.TP
+.B "0 \- DL_EX_OK"
+The program was successful.
+.TP 
+.B "1 \- DL_EX_ERROR"
+An unspecified error such as bad command line parameters,
+lack of system memory and the like has occurred.
+.TP 
+.B "3 \- DL_EX_EXIST"
+The 
+user wants to lock a file which has been locked by
+another process already.  If 
+.B mutt_dotlock
+is invoked with the
+.B -f 
+command line option, 
+.B mutt_dotlock
+won't generate this error, but break other processes'
+locks.
+.TP 
+.B "4 \- DL_EX_NEED_RPIVS"
+This return value only occurs if 
+.B mutt_dotlock 
+has been invoked
+with the 
+.B -t
+command line option.  It means that
+.B mutt_dotlock
+will have to use its group mail privileges to lock
+\fIfile\fP.
+.TP
+.B "5 \- DL_EX_IMPOSSIBLE"
+This return value only occurs if
+.B mutt_dotlock
+has been invoked with the
+.B -t
+command line option.  It means that
+.B mutt_dotlock 
+is unable to lock \fIfile\fP even with group mail
+privileges.
+.SH NOTES
+.PP
+.B mutt_dotlock
+tries to implement an NFS-safe dotlocking method which was
+borrowed from 
+.B lockfile
+(1).  
+.PP
+If the user can't open \fIfile\fP for reading with his
+normal privileges, 
+.B mutt_dotlock 
+will return the
+.B DL_EX_ERROR
+exit value to avoid certain attacks against other users'
+spool files. The code carefully avoids race conditions
+when checking permissions; for details of all this see the
+comments in dotlock.c.
+.SH HISTORY
+.PP
+.B mutt_dotlock
+is part of the Mutt mail user agent package.  It has been
+created to avoid running mutt with group mail privileges.
+.SH AUTHOR
+Thomas Roessler <roessler@does-not-exist.org>
diff --git a/upstream/mageia-cauldron/man1/mutt_pgpring.1 b/upstream/mageia-cauldron/man1/mutt_pgpring.1
new file mode 100644
index 00000000..dace1ad2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mutt_pgpring.1
@@ -0,0 +1,65 @@
+.\" -*-nroff-*-
+.\"
+.\"     mutt_pgpring, a key ring dumper
+.\"     Manpage Copyright (c) 2004-2013 Matthew Wilcox, Honza Horak
+.\"
+.\"     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 2 of the License, or
+.\"     (at your option) any later version.
+.\"
+.\"     This program is distributed in the hope that it will be useful,
+.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"     GNU General Public License for more details.
+.\"
+.\"     You should have received a copy of the GNU General Public License
+.\"     along with this program; if not, write to the Free Software
+.\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+.\"
+.TH mutt_pgpring 1 "May 2013" Unix "User Manuals"
+.SH NAME
+mutt_pgpring \- Mutt key ring dumper
+
+.SH SYNTAX
+.PP
+\fBmutt_pgpring\fP [ \fB\-k\fP \fIkeyring\fP ] [ \fB\-2\fP | \fB\-5\fP ]
+[ \fB\-s\fP ] [ \fB\-S\fP ] [ \fB\-f\fP ]
+
+.SH DESCRIPTION
+.PP
+mutt_pgpring is a key ring dumper.  It extracts information from PGP's
+binary key ring and emits it in an (almost) readable output format
+understood by mutt's key selection routines.  This output format
+mimics the one used by the GNU Privacy Guard (GPG).
+
+.SH OPTIONS
+.TP
+.BI \-k " keyring"
+Dump the contents of the specified keyring.
+.TP
+.B \-2
+Use the default keyring for PGP 2.x.
+.TP
+.B \-5
+Use the default keyring for PGP 5.
+.TP
+.B \-s
+Dump the secret keyring.
+.TP
+.B \-S
+Dump signatures.
+.TP
+.B \-f
+Dump fingerprints.
+
+.SH ENVIRONMENT
+.PP
+.IP "HOME"
+Full path of the user's home directory.
+.IP "PGPPATH"
+Directory in which the user's PGP public keyring can be found.
+
+.SH AUTHORS
+Thomas Roessler <roessler@does\-not\-exist.org>
+
diff --git a/upstream/mageia-cauldron/man1/mv.1 b/upstream/mageia-cauldron/man1/mv.1
new file mode 100644
index 00000000..35f24d77
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mv.1
@@ -0,0 +1,102 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH MV "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+mv \- move (rename) files
+.SH SYNOPSIS
+.B mv
+[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,SOURCE DEST\/\fR
+.br
+.B mv
+[\fI\,OPTION\/\fR]... \fI\,SOURCE\/\fR... \fI\,DIRECTORY\/\fR
+.br
+.B mv
+[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY SOURCE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Rename SOURCE to DEST, or move SOURCE(s) to DIRECTORY.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-backup\fR[=\fI\,CONTROL\/\fR]
+make a backup of each existing destination file
+.TP
+\fB\-b\fR
+like \fB\-\-backup\fR but does not accept an argument
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+do not prompt before overwriting
+.TP
+\fB\-i\fR, \fB\-\-interactive\fR
+prompt before overwrite
+.TP
+\fB\-n\fR, \fB\-\-no\-clobber\fR
+do not overwrite an existing file
+.PP
+If you specify more than one of \fB\-i\fR, \fB\-f\fR, \fB\-n\fR, only the final one takes effect.
+.TP
+\fB\-\-strip\-trailing\-slashes\fR
+remove any trailing slashes from each SOURCE
+argument
+.TP
+\fB\-S\fR, \fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+override the usual backup suffix
+.TP
+\fB\-t\fR, \fB\-\-target\-directory\fR=\fI\,DIRECTORY\/\fR
+move all SOURCE arguments into DIRECTORY
+.TP
+\fB\-T\fR, \fB\-\-no\-target\-directory\fR
+treat DEST as a normal file
+.TP
+\fB\-u\fR, \fB\-\-update\fR
+move only when the SOURCE file is newer
+than the destination file or when the
+destination file is missing
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+explain what is being done
+.TP
+\fB\-Z\fR, \fB\-\-context\fR
+set SELinux security context of destination
+file to default type
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX.
+The version control method may be selected via the \fB\-\-backup\fR option or through
+the VERSION_CONTROL environment variable.  Here are the values:
+.TP
+none, off
+never make backups (even if \fB\-\-backup\fR is given)
+.TP
+numbered, t
+make numbered backups
+.TP
+existing, nil
+numbered if numbered backups exist, simple otherwise
+.TP
+simple, never
+always make simple backups
+.SH AUTHOR
+Written by Mike Parker, David MacKenzie, and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBrename\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/mv>
+.br
+or available locally via: info \(aq(coreutils) mv invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/mzip.1 b/upstream/mageia-cauldron/man1/mzip.1
new file mode 100644
index 00000000..10e00724
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mzip.1
@@ -0,0 +1,147 @@
+'\" t
+.TH mzip 1 "21Mar23" mtools-4.0.43
+.SH Name
+mzip - change protection mode and eject disk on Zip/Jaz drive
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.SH Note\ of\ warning
+This manpage has been automatically generated from mtools's texinfo
+documentation, and may not be entirely accurate or complete.  See the
+end of this man page for details.
+.PP
+.SH Description
+.PP
+The \fR\&\f(CWmzip\fR command is used to issue ZIP disk specific commands on
+Linux, Solaris or HP-UX. Its syntax is:
+.PP
+.ft I
+.nf
+\&\fR\&\f(CWmzip\fR [\fR\&\f(CW-epqrwx\fR]
+.fi
+.ft R
+ 
+.PP
+\&\fR\&\f(CWMzip\fR allows the following
+command line options:
+.TP
+\&\fR\&\f(CWe\fR\ 
+Ejects the disk.
+.TP
+\&\fR\&\f(CWf\fR\ 
+Force eject even if the disk is mounted (must be given in addition to
+\&\fR\&\f(CW-e\fR).
+.TP
+\&\fR\&\f(CWr\fR\ 
+Write protect the disk.
+.TP
+\&\fR\&\f(CWw\fR\ 
+Remove write protection.
+.TP
+\&\fR\&\f(CWp\fR\ 
+Password write protect.
+.TP
+\&\fR\&\f(CWx\fR\ 
+Password protect
+.TP
+\&\fR\&\f(CWu\fR\ 
+Temporarily unprotect the disk until it is ejected.  The disk becomes
+writable, and reverts back to its old state when ejected.
+.TP
+\&\fR\&\f(CWq\fR\ 
+Queries the status
+.PP
+To remove the password, set it to one of the password-less modes
+\&\fR\&\f(CW-r\fR or \fR\&\f(CW-w\fR: mzip will then ask you for the password, and
+unlock the disk.  If you have forgotten the password, you can get rid of
+it by low-level formatting the disk (using your SCSI adapter's BIOS
+setup).
+.PP
+The ZipTools disk shipped with the drive is also password protected.  On
+MS-DOS or on a Mac, this password is automatically removed once the
+ZipTools have been installed.  From various articles posted to Usenet, I
+learned that the password for the tools disk is
+\&\fR\&\f(CWAPlaceForYourStuff\fR\fR.  Mzip knows about this
+password, and tries it first, before prompting you for a password.  Thus
+\&\fR\&\f(CWmzip -w z:\fR unlocks the tools disk.  The tools disk is
+formatted in a special way so as to be usable both in a PC and in a Mac.
+On a PC, the Mac file system appears as a hidden file named
+\&\fR\&\f(CW\(ifpartishn.mac\(is\fR.  You may erase it to reclaim the 50 Megs of space
+taken up by the Mac file system.
+.PP
+.SH Bugs
+.PP
+This command is a big kludge.  A proper implementation would take a
+rework of significant parts of mtools, but unfortunately I don't have
+the time for this right now. The main downside of this implementation is
+that it is inefficient on some architectures (several successive calls
+to mtools, which defeats mtools' caching).
+.PP
+.SH See\ Also
+Mtools' texinfo doc
+.SH Viewing\ the\ texi\ doc
+This manpage has been automatically generated from mtools's texinfo
+documentation. However, this process is only approximative, and some
+items, such as crossreferences, footnotes and indices are lost in this
+translation process.  Indeed, these items have no appropriate
+representation in the manpage format.  Moreover, not all information has
+been translated into the manpage version.  Thus I strongly advise you to
+use the original texinfo doc.  See the end of this manpage for
+instructions how to view the texinfo doc.
+.TP
+* \ \ 
+To generate a printable copy from the texinfo doc, run the following
+commands:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make dvi; dvips mtools.dvi
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.TP
+* \ \ 
+To generate a html copy,  run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make html
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fRA premade html can be found at
+\&\fR\&\f(CW\(ifhttp://www.gnu.org/software/mtools/manual/mtools.html\(is\fR
+.TP
+* \ \ 
+To generate an info copy (browsable using emacs' info mode), run:
+ 
+.nf
+.ft 3
+.in +0.3i
+    ./configure; make info
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The texinfo doc looks most pretty when printed or as html.  Indeed, in
+the info version certain examples are difficult to read due to the
+quoting conventions used in info.
+.PP
diff --git a/upstream/mageia-cauldron/man1/nano.1 b/upstream/mageia-cauldron/man1/nano.1
new file mode 100644
index 00000000..1eb19c5f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nano.1
@@ -0,0 +1,427 @@
+.\" Copyright (C) 1999-2011, 2013-2023 Free Software Foundation, Inc.
+.\"
+.\" This document is dual-licensed.  You may distribute and/or modify it
+.\" under the terms of either of the following licenses:
+.\"
+.\" * The GNU General Public License, as published by the Free Software
+.\"   Foundation, version 3 or (at your option) any later version.  You
+.\"   should have received a copy of the GNU General Public License
+.\"   along with this program.  If not, see
+.\"   <https://www.gnu.org/licenses/>.
+.\"
+.\" * The GNU Free Documentation License, as published by the Free
+.\"   Software Foundation, version 1.2 or (at your option) any later
+.\"   version, with no Invariant Sections, no Front-Cover Texts, and no
+.\"   Back-Cover Texts.  You should have received a copy of the GNU Free
+.\"   Documentation License along with this program.  If not, see
+.\"   <https://www.gnu.org/licenses/>.
+.\"
+.TH NANO 1 "version 7.2" "January 2023"
+
+.SH NAME
+nano \- Nano's ANOther editor, inspired by Pico
+
+.SH SYNOPSIS
+.B nano
+.RI [ options "] [[\fB+" line [\fB, column "]] " file ]...
+.sp
+.BR nano " [" \fIoptions "] [[" + [ crCR ]( / | ? ) \fIstring "] " \fIfile ]...
+
+.SH DESCRIPTION
+\fBnano\fP is a small and friendly editor.  It copies the look and feel
+of Pico, but is free software, and implements several features that Pico
+lacks, such as: opening multiple files, scrolling per line, undo/redo,
+syntax coloring, line numbering, and soft-wrapping overlong lines.
+.sp
+When giving a filename on the command line, the cursor can be put on a
+specific line by adding the line number with a plus sign (\fB+\fR) before
+the filename, and even in a specific column by adding it with a comma.
+(Negative numbers count from the end of the file or line.)
+The cursor can be put on the first or last occurrence of a specific string
+by specifying that string after \fB+/\fR or \fB+?\fR before the filename.
+The string can be made case sensitive and/or caused to be interpreted as a
+regular expression by inserting \fBc\fR and/or \fBr\fR after the \fB+\fR sign.
+These search modes can be explicitly disabled by using the uppercase variant
+of those letters: \fBC\fR and/or \fBR\fR.  When the string contains spaces,
+it needs to be enclosed in quotes.  To give an example: to open a file at
+the first occurrence of the word "Foo", you would do:
+.sp
+.RS 4
+.BI "nano +c/Foo " file
+.RE
+.sp
+As a special case: if instead of a filename a dash (\fB\-\fR) is given,
+\fBnano\fR will read data from standard input.
+
+.SH EDITING
+Entering text and moving around in a file is straightforward: typing the
+letters and using the normal cursor movement keys.  Commands are entered
+by using the Control (^) and the Alt or Meta (M\-) keys.
+Typing \fB^K\fR deletes the current line and puts it in the cutbuffer.
+Consecutive \fB^K\fRs will put all deleted lines together in the cutbuffer.
+Any cursor movement or executing any other command will cause the next
+\fB^K\fR to overwrite the cutbuffer.  A \fB^U\fR will paste the current
+contents of the cutbuffer at the current cursor position.
+.sp
+When a more precise piece of text needs to be cut or copied, you can mark
+its start with \fB^6\fR, move the cursor to its end (the marked text will be
+highlighted), and then use \fB^K\fR to cut it, or \fBM\-6\fR to copy it to the
+cutbuffer.  You can also save the marked text to a file with \fB^O\fR, or
+spell check it with \fB^T^T\fR.
+.sp
+On some terminals, text can be selected also by holding down Shift while
+using the arrow keys.  Holding down the Ctrl or Alt key too will increase
+the stride.
+Any cursor movement without Shift being held will cancel such a selection.
+.sp
+Any valid Unicode code point can be inserted into the buffer by typing
+\fBM\-V\fR followed by the hexadecimal digits of the code point (concluded
+with \fB<Space>\fR or \fB<Enter>\fR when it are fewer than six digits).
+A literal control code (except \fB^J\fR) can be inserted by typing
+\fBM\-V\fR followed by the pertinent keystroke.
+.sp
+The two lines at the bottom of the screen show some important commands;
+the built-in help (\fB^G\fR) lists all the available ones.
+The default key bindings can be changed via a \fInanorc\fR file -- see
+.BR nanorc (5).
+
+.SH OPTIONS
+.TP
+.BR \-A ", " \-\-smarthome
+Make the Home key smarter.  When Home is pressed anywhere but at the
+very beginning of non-whitespace characters on a line, the cursor will
+jump to that beginning (either forwards or backwards).  If the cursor is
+already at that position, it will jump to the true beginning of the
+line.
+.TP
+.BR \-B ", " \-\-backup
+When saving a file, back up the previous version of it, using the current
+filename suffixed with a tilde (\fB~\fP).
+.TP
+.BR \-C\ \fIdirectory ", " \-\-backupdir= \fIdirectory
+Make and keep not just one backup file, but make and keep a uniquely
+numbered one every time a file is saved -- when backups are enabled (\fB\-B\fR).
+The uniquely numbered files are stored in the specified \fIdirectory\fR.
+.TP
+.BR \-D ", " \-\-boldtext
+For the interface, use bold instead of reverse video.  This will be overridden
+by setting the options \fBtitlecolor\fP, \fBstatuscolor\fP, \fBkeycolor\fP,
+\fBfunctioncolor\fP, \fBnumbercolor\fP, and/or \fBselectedcolor\fP in your
+nanorc file.  See \fBnanorc\fR(5).
+.TP
+.BR \-E ", " \-\-tabstospaces
+Convert each typed tab to spaces -- to the number of spaces
+that a tab at that position would take up.
+.TP
+.BR \-F ", " \-\-multibuffer
+Read a file into a new buffer by default.
+.TP
+.BR \-G ", " \-\-locking
+Use vim-style file locking when editing files.
+.TP
+.BR \-H ", " \-\-historylog
+Save the last hundred search strings and replacement strings and
+executed commands, so they can be easily reused in later sessions.
+.TP
+.BR \-I ", " \-\-ignorercfiles
+Don't look at the system's \fInanorc\fR nor at the user's \fInanorc\fR.
+.TP
+.BR \-J\ \fInumber ", " \-\-guidestripe= \fInumber
+Draw a vertical stripe at the given column, to help judge the width of the
+text.  (The color of the stripe can be changed with \fBset stripecolor\fR
+in your \fInanorc\fR file.)
+.TP
+.BR \-K ", " \-\-rawsequences
+Interpret escape sequences directly, instead of asking \fBncurses\fR
+to translate them.  (If you need this option to get some keys to work
+properly, it means that the terminfo terminal description that is used
+does not fully match the actual behavior of your terminal.  This can
+happen when you ssh into a BSD machine, for example.)
+Using this option disables \fBnano\fR's mouse support.
+.TP
+.BR \-L ", " \-\-nonewlines
+Don't automatically add a newline when a text does not end with one.
+(This can cause you to save non-POSIX text files.)
+.TP
+.BR \-M ", " \-\-trimblanks
+Snip trailing whitespace from the wrapped line when automatic
+hard-wrapping occurs or when text is justified.
+.TP
+.BR \-N ", " \-\-noconvert
+Disable automatic conversion of files from DOS/Mac format.
+.TP
+.BR \-O ", " \-\-bookstyle
+When justifying, treat any line that starts with whitespace as the
+beginning of a paragraph (unless auto-indenting is on).
+.TP
+.BR \-P ", " \-\-positionlog
+For the 200 most recent files, log the last position of the cursor,
+and place it at that position again upon reopening such a file.
+.TP
+.BR "\-Q ""\fIregex\fB""" ", " "\-\-quotestr=""" \fIregex """
+Set the regular expression for matching the quoting part of a line.
+The default value is "\fB^([\ \\t]*([!#%:;>|}]|//))+\fR".
+(Note that \fB\\t\fP stands for an actual Tab.)
+This makes it possible to rejustify blocks of quoted text when composing
+email, and to rewrap blocks of line comments when writing source code.
+.TP
+.BR \-R ", " \-\-restricted
+Restricted mode: don't read or write to any file not specified on the
+command line.  This means: don't read or write history files;
+don't allow suspending; don't allow spell checking;
+don't allow a file to be appended to, prepended to, or saved under a
+different name if it already has one; and don't make backup files.
+Restricted mode can also be activated by invoking \fBnano\fP
+with any name beginning with 'r' (e.g. "rnano").
+.TP
+.BR \-S ", " \-\-softwrap
+Display over multiple screen rows lines that exceed the screen's width.
+(You can make this soft-wrapping occur at whitespace instead of rudely at
+the screen's edge, by using also \fB\-\-atblanks\fR.)
+(The old short option, \fB\-$\fR, is deprecated.)
+.TP
+.BR \-T\ \fInumber ", " \-\-tabsize= \fInumber
+Set the size (width) of a tab to \fInumber\fP columns.  The value of
+\fInumber\fR must be greater than 0.  The default value is \fB8\fR.
+.TP
+.BR \-U ", " \-\-quickblank
+Make status-bar messages disappear after 1 keystroke instead of after 20.
+Note that option \fB\-c\fR (\fB\-\-constantshow\fR) overrides this.
+When option \fB\-\-minibar\fR or \fB\-\-zero\fR is in effect,
+\fB\-\-quickblank\fR makes a message disappear after
+0.8 seconds instead of after the default 1.5 seconds.
+.
+.TP
+.BR \-V ", " \-\-version
+Show the current version number and exit.
+.TP
+.BR \-W ", " \-\-wordbounds
+Detect word boundaries differently by treating punctuation
+characters as part of a word.
+.TP
+.BR "\-X ""\fIcharacters\fB""" ", " "\-\-wordchars=""" \fIcharacters """
+Specify which other characters (besides the normal alphanumeric ones)
+should be considered as part of a word.  When using this option, you
+probably want to omit \fB\-W\fR (\fB\-\-wordbounds\fR).
+.TP
+.BR \-Y\ \fIname ", " \-\-syntax= \fIname
+Specify the name of the syntax highlighting to use from among the ones
+defined in the \fInanorc\fP files.
+.TP
+.BR \-Z ", " \-\-zap
+Let an unmodified Backspace or Delete erase the marked region
+(instead of a single character, and without affecting the cutbuffer).
+.TP
+.BR \-a ", " \-\-atblanks
+When doing soft line wrapping, wrap lines at whitespace
+instead of always at the edge of the screen.
+.TP
+.BR \-b ", " \-\-breaklonglines
+Automatically hard-wrap the current line when it becomes overlong.
+(This option is the opposite of \fB\-w\fR (\fB\-\-nowrap\fR) --
+the last one given takes effect.)
+.TP
+.BR \-c ", " \-\-constantshow
+Constantly show the cursor position on the status bar.
+Note that this overrides option \fB\-U\fR (\fB\-\-quickblank\fR).
+.TP
+.BR \-d ", " \-\-rebinddelete
+Interpret the Delete and Backspace keys differently so that both Backspace
+and Delete work properly.  You should only use this option when on your
+system either Backspace acts like Delete or Delete acts like Backspace.
+.TP
+.BR \-e ", " \-\-emptyline
+Do not use the line below the title bar, leaving it entirely blank.
+.TP
+.BR \-f\ \fIfile ", " \-\-rcfile= \fIfile
+Read only this \fIfile\fR for setting nano's options, instead of reading
+both the system-wide and the user's nanorc files.
+.TP
+.BR \-g ", " \-\-showcursor
+Make the cursor visible in the file browser (putting it on the
+highlighted item) and in the help viewer.  Useful for braille users
+and people with poor vision.
+.TP
+.BR \-h ", " \-\-help
+Show a summary of the available command-line options and exit.
+.TP
+.BR \-i ", " \-\-autoindent
+Automatically indent a newly created line to the same number of tabs
+and/or spaces as the previous line (or as the next line if the previous
+line is the beginning of a paragraph).
+.TP
+.BR \-j ", " \-\-jumpyscrolling
+Scroll the buffer contents per half-screen instead of per line.
+.TP
+.BR \-k ", " \-\-cutfromcursor
+Make the 'Cut Text' command (normally \fB^K\fR) cut from the current cursor
+position to the end of the line, instead of cutting the entire line.
+.TP
+.BR \-l ", " \-\-linenumbers
+Display line numbers to the left of the text area.
+(Any line with an anchor additionally gets a mark in the margin.)
+.TP
+.BR \-m ", " \-\-mouse
+Enable mouse support, if available for your system.  When enabled, mouse
+clicks can be used to place the cursor, set the mark (with a double
+click), and execute shortcuts.  The mouse will work in the X Window
+System, and on the console when gpm is running.  Text can still be
+selected through dragging by holding down the Shift key.
+.TP
+.BR \-n ", " \-\-noread
+Treat any name given on the command line as a new file.  This allows
+\fBnano\fR to write to named pipes: it will start with a blank buffer,
+and will write to the pipe when the user saves the "file".  This way
+\fBnano\fR can be used as an editor in combination with for instance
+\fBgpg\fR without having to write sensitive data to disk first.
+.TP
+.BR \-o\ \fIdirectory ", " \-\-operatingdir= \fIdirectory
+Set the operating directory.  This makes \fBnano\fP set up something
+similar to a chroot.
+.TP
+.BR \-p ", " \-\-preserve
+Preserve the XON and XOFF sequences (\fB^Q\fR and \fB^S\fR) so they
+will be caught by the terminal.
+.TP
+.BR \-q ", " \-\-indicator
+Display a "scrollbar" on the righthand side of the edit window.
+It shows the position of the viewport in the buffer
+and how much of the buffer is covered by the viewport.
+.TP
+.BR \-r\ \fInumber ", " \-\-fill= \fInumber
+Set the target width for justifying and automatic hard-wrapping at this
+\fInumber\fR of columns.  If the value is 0 or less, wrapping will occur
+at the width of the screen minus \fInumber\fR columns, allowing the wrap
+point to vary along with the width of the screen if the screen is resized.
+The default value is \fB\-8\fR.
+.TP
+.B "\-s ""\fIprogram\fR [\fIargument \fR...]\fB""\fR, \fB\-\-speller=""\fIprogram\fR [\fIargument \fR...]\fB"""
+Use this command to perform spell checking and correcting, instead of
+using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1).
+.TP
+.BR \-t ", " \-\-saveonexit
+Save a changed buffer without prompting (when exiting with \fB^X\fR).
+.TP
+.BR \-u ", " \-\-unix
+Save a file by default in Unix format.  This overrides nano's
+default behavior of saving a file in the format that it had.
+(This option has no effect when you also use \fB\-\-noconvert\fR.)
+.TP
+.BR \-v ", " \-\-view
+Just view the file and disallow editing: read-only mode.
+This mode allows the user to open also other files for viewing,
+unless \fB\-\-restricted\fR is given too.
+.TP
+.BR \-w ", " \-\-nowrap
+Do not automatically hard-wrap the current line when it becomes overlong.
+This is the default.  (This option is the opposite of \fB\-b\fR
+(\fB\-\-breaklonglines\fR) -- the last one given takes effect.)
+.TP
+.BR \-x ", " \-\-nohelp
+Don't show the two help lines at the bottom of the screen.
+.TP
+.BR \-y ", " \-\-afterends
+Make Ctrl+Right and Ctrl+Delete stop at word ends instead of beginnings.
+.TP
+.BR \-! ", " \-\-magic
+When neither the file's name nor its first line give a clue,
+try using libmagic to determine the applicable syntax.
+.TP
+.BR \-% ", " \-\-stateflags
+Use the top-right corner of the screen for showing some state flags:
+\fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when
+hard-wrapping (breaking long lines), \fBR\fR when recording a macro,
+and \fBS\fR when soft-wrapping.
+When the buffer is modified, a star (\fB*\fR) is shown after the
+filename in the center of the title bar.
+.TP
+.BR \-_ ", " \-\-minibar
+Suppress the title bar and instead show information about
+the current buffer at the bottom of the screen, in the space
+for the status bar.  In this "minibar" the filename is shown
+on the left, followed by an asterisk if the buffer has been modified.
+On the right are displayed the current line and column number, the
+code of the character under the cursor (in Unicode format: U+xxxx),
+the same flags as are shown by \fB\-\-stateflags\fR, and a percentage
+that expresses how far the cursor is into the file (linewise).
+When a file is loaded or saved, and also when switching between buffers,
+the number of lines in the buffer is displayed after the filename.
+This number is cleared upon the next keystroke, or replaced with an
+[i/n] counter when multiple buffers are open.
+The line plus column numbers and the character code are displayed only when
+\fB\-\-constantshow\fR is used, and can be toggled on and off with \fBM\-C\fR.
+The state flags are displayed only when \fB\-\-stateflags\fR is used.
+.TP
+.BR \-0 ", " \-\-zero
+Hide all elements of the interface (title bar, status bar, and help lines)
+and use all rows of the terminal for showing the contents of the buffer.
+The status bar appears only when there is a significant message,
+and disappears after 1.5 seconds or upon the next keystroke.
+With \fBM\-Z\fR the title bar plus status bar can be toggled.
+With \fBM\-X\fR the help lines.
+
+.SH TOGGLES
+Several of the above options can be switched on and off also while
+\fBnano\fR is running.  For example, \fBM\-L\fR toggles the
+hard-wrapping of long lines, \fBM\-S\fR toggles soft-wrapping,
+\fBM\-N\fR toggles line numbers, \fBM\-M\fR toggles the mouse,
+\fBM\-I\fR auto-indentation, and \fBM\-X\fR the help lines.
+See at the end of the \fB^G\fR help text for a complete list.
+.sp
+The \fBM\-X\fR toggle is special: it works in all menus except
+the help viewer and the linter.  All other toggles work in
+the main menu only.
+
+.SH FILES
+When \fB\-\-rcfile\fR is given, \fBnano\fR will read just the specified file
+for setting its options and syntaxes and key bindings.  Without that option,
+\fBnano\fR will read two configuration files: first the system's
+\fInanorc\fR (if it exists), and then the user's \fInanorc\fR (if it
+exists), either \fI~/.nanorc\fR or \fI$XDG_CONFIG_HOME/nano/nanorc\fR
+or \fI~/.config/nano/nanorc\fR, whichever is encountered first.  See
+.BR nanorc (5)
+for more information on the possible contents of those files.
+.sp
+See \fI/usr/share/nano/\fR and \fI/usr/share/nano/extra/\fR
+for available syntax-coloring definitions.
+
+.SH NOTES
+Option \fB\-z\fR (\fB\-\-suspendable\fR) has been removed.
+Suspension is enabled by default, reachable via \fB^T^Z\fR.
+(If you want a plain \fB^Z\fR to suspend nano, add
+\fBbind ^Z suspend main\fR to your nanorc.)
+.sp
+If no alternative spell checker command is specified on the command
+line nor in one of the \fInanorc\fP files, \fBnano\fP will check the
+\fBSPELL\fP environment variable for one.
+.sp
+In some cases \fBnano\fP will try to dump the buffer into an emergency
+file.  This will happen mainly if \fBnano\fP receives a SIGHUP or
+SIGTERM or runs out of memory.  It will write the buffer into a file
+named \fInano.save\fP if the buffer didn't have a name already, or will
+add a ".save" suffix to the current filename.  If an emergency file with
+that name already exists in the current directory, it will add ".save"
+plus a number (e.g.\& ".save.1") to the current filename in order to make
+it unique.  In multibuffer mode, \fBnano\fP will write all the open
+buffers to their respective emergency files.
+
+.SH BUGS
+The recording and playback of keyboard macros works correctly only on a
+terminal emulator, not on a Linux console (VT), because the latter does
+not by default distinguish modified from unmodified arrow keys.
+.sp
+Please report any other bugs that you encounter via:
+.br
+.IR https://savannah.gnu.org/bugs/?group=nano .
+.sp
+When nano crashes, it will save any modified buffers to emergency .save files.
+If you are able to reproduce the crash and you want to get a backtrace, define
+the environment variable \fBNANO_NOCATCH\fR.
+
+.SH HOMEPAGE
+.I https://nano\-editor.org/
+
+.SH SEE ALSO
+.BR nanorc (5)
+.sp
+\fI/usr/share/doc/nano/\fP (or equivalent on your system)
diff --git a/upstream/mageia-cauldron/man1/ncursesw6-config.1 b/upstream/mageia-cauldron/man1/ncursesw6-config.1
new file mode 100644
index 00000000..cad634f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ncursesw6-config.1
@@ -0,0 +1,104 @@
+.\"***************************************************************************
+.\" Copyright 2020-2021,2023 Thomas E. Dickey                                *
+.\" Copyright 2010 Free Software Foundation, Inc.                            *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: MKncu_config.in,v 1.22 2023/12/23 23:44:26 tom Exp $
+.TH ncursesw6-config 1 2023-12-23 "ncurses 6.4" "User commands"
+.SH NAME
+\fB\%ncursesw6-config\fP \-
+configuration helper for \fI\%ncurses\fP libraries
+.SH SYNOPSIS
+.B ncursesw6-config
+.I option
+\&.\|.\|.
+.PP
+.B "ncursesw6-config \-\-version"
+.PP
+.B "ncursesw6-config \-\-help"
+.SH DESCRIPTION
+This program development aid simplifies the process of configuring
+applications against a particular set of \fI\%ncurses\fP libraries.
+.SH OPTIONS
+.TP 18 \" "--mouse-version" + 2n + adjustment for PDF
+\fB\-\-prefix\fP
+reports the package prefix of \fI\%ncurses\fP.
+.TP
+\fB\-\-exec\-prefix\fP
+reports the executable prefix of \fI\%ncurses\fP.
+.TP
+\fB\-\-cflags\fP
+reports the C compiler flags needed to compile with \fI\%ncurses\fP.
+.TP
+\fB\-\-libs\fP
+reports the libraries needed to link with \fI\%ncurses\fP.
+.TP
+\fB\-\-abi\-version\fP
+reports the ABI version of \fI\%ncurses\fP.
+.TP
+\fB\-\-mouse\-version\fP
+reports the mouse\-interface version of \fI\%ncurses\fP.
+.TP
+\fB\-\-bindir\fP
+reports the directory containing \fI\%ncurses\fP programs.
+.TP
+\fB\-\-datadir\fP
+reports the directory containing \fI\%ncurses\fP data.
+.TP
+\fB\-\-includedir\fP
+reports the directory containing \fI\%ncurses\fP header files.
+.TP
+\fB\-\-libdir\fP
+reports the directory containing \fI\%ncurses\fP libraries.
+.TP
+\fB\-\-mandir\fP
+reports the directory containing \fI\%ncurses\fP man pages.
+.TP
+\fB\-\-terminfo\fP
+reports the \fI\%TERMINFO\fP \fIterminfo\fP database path,
+for example \fI\%/usr/share/terminfo\fP.
+.TP
+\fB\-\-terminfo\-dirs\fP
+reports the \fI\%TERMINFO_DIRS\fP supplemental search path for the
+\fIterminfo\fP database,
+for example \fI\%/usr/share/terminfo\fP.
+.TP
+\fB\-\-termpath\fP
+reports the \fI\%TERMPATH\fP supplemental search path for the
+\fItermcap\fP database,
+if support for \fItermcap\fP is configured.
+.PP
+The following options cause all others to be ignored.
+.TP 11 .\" "--version" + 2n
+\fB\-\-help\fP
+issues a usage message and exits successfully.
+.TP
+\fB\-\-version\fP
+issues the release and patch date information of \fI\%ncurses\fP and
+exits successfully.
+.SH "SEE ALSO"
+\fB\%curses\fP(3X)
diff --git a/upstream/mageia-cauldron/man1/neotoppm.1 b/upstream/mageia-cauldron/man1/neotoppm.1
new file mode 100644
index 00000000..63d7e613
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/neotoppm.1
@@ -0,0 +1,56 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Neotoppm User Manual" 0 "24 April 2001" "netpbm documentation"
+
+.SH NAME
+
+neotoppm - convert an Atari Neochrome .neo into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBneotoppm\fP
+[\fIneofile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBneotoppm\fP reads an Atari Neochrome .neo file as input and
+produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBneotoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoneo" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2001 by Teemu Hukkanen <\fItjhukkan@iki.fi\fP>, based on
+pi1toppm by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/neotoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/neqn.1 b/upstream/mageia-cauldron/man1/neqn.1
new file mode 100644
index 00000000..32505edd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/neqn.1
@@ -0,0 +1,66 @@
+.TH NEQN 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+neqn \- format equations for ASCII output
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 2001-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY neqn
+.RI [ eqn-options ]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I neqn
+invokes the
+.IR eqn (1)
+command with the
+.B ascii
+output device.
+.
+.
+.LP
+Note that
+.I eqn
+does not support low-resolution, typewriter-like devices (although it
+may work adequately for very simple input).
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.IR eqn (1)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/networkctl.1 b/upstream/mageia-cauldron/man1/networkctl.1
new file mode 100644
index 00000000..7bdbc0e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/networkctl.1
@@ -0,0 +1,519 @@
+'\" t
+.TH "NETWORKCTL" "1" "" "systemd 255" "networkctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+networkctl \- Query or modify the status of network links
+.SH "SYNOPSIS"
+.HP \w'\fBnetworkctl\fR\ 'u
+\fBnetworkctl\fR [OPTIONS...] COMMAND [LINK...]
+.SH "DESCRIPTION"
+.PP
+\fBnetworkctl\fR
+may be used to query or modify the state of the network links as seen by
+\fBsystemd\-networkd\fR\&. Please refer to
+\fBsystemd-networkd.service\fR(8)
+for an introduction to the basic concepts, functionality, and configuration syntax\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR [\fIPATTERN\&...\fR]
+.RS 4
+Show a list of existing links and their status\&. If one or more
+\fIPATTERN\fRs are specified, only links matching one of them are shown\&. If no further arguments are specified shows all links, otherwise just the specified links\&. Produces output similar to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+IDX LINK         TYPE     OPERATIONAL SETUP
+  1 lo           loopback carrier     unmanaged
+  2 eth0         ether    routable    configured
+  3 virbr0       ether    no\-carrier  unmanaged
+  4 virbr0\-nic   ether    off         unmanaged
+
+4 links listed\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The operational status is one of the following:
+.PP
+missing
+.RS 4
+The device is missing\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+off
+.RS 4
+The device is powered down\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+no\-carrier
+.RS 4
+The device is powered up, but does not yet have a carrier\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+dormant
+.RS 4
+The device has a carrier, but is not yet ready for normal traffic\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+degraded\-carrier
+.RS 4
+One of the bonding or bridge slave network interfaces is in off, no\-carrier, or dormant state, and the master interface has no address\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+carrier
+.RS 4
+The link has carrier, or for bond or bridge master, all bonding or bridge slave network interfaces are enslaved to the master\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+degraded
+.RS 4
+The link has carrier and addresses valid on the local link configured\&. For bond or bridge master this means that not all slave network interfaces have carrier but at least one does\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+enslaved
+.RS 4
+The link has carrier and is enslaved to bond or bridge master network interface\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+routable
+.RS 4
+The link has carrier and routable address configured\&. For bond or bridge master it is not necessary for all slave network interfaces to have carrier, but at least one must\&.
+.sp
+Added in version 240\&.
+.RE
+.sp
+The setup status is one of the following:
+.PP
+pending
+.RS 4
+\fBsystemd-udevd\fR(8)
+is still processing the link, we don\*(Aqt yet know if we will manage it\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+initialized
+.RS 4
+\fBsystemd-udevd\fR(8)
+has processed the link, but we don\*(Aqt yet know if we will manage it\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+configuring
+.RS 4
+Configuration for the link is being retrieved or the link is being configured\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+configured
+.RS 4
+Link has been configured successfully\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+unmanaged
+.RS 4
+\fBsystemd\-networkd\fR
+is not handling the link\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+failed
+.RS 4
+\fBsystemd\-networkd\fR
+failed to configure the link\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+linger
+.RS 4
+The link is gone, but has not yet been dropped by
+\fBsystemd\-networkd\fR\&.
+.sp
+Added in version 240\&.
+.RE
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBstatus\fR [\fIPATTERN\&...\fR]
+.RS 4
+Show information about the specified links: type, state, kernel module driver, hardware and IP address, configured DNS servers, etc\&. If one or more
+\fIPATTERN\fRs are specified, only links matching one of them are shown\&.
+.sp
+When no links are specified, an overall network status is shown\&. Also see the option
+\fB\-\-all\fR\&.
+.sp
+Produces output similar to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+â—�        State: routable
+  Online state: online
+       Address: 10\&.193\&.76\&.5 on eth0
+                192\&.168\&.122\&.1 on virbr0
+                169\&.254\&.190\&.105 on eth0
+                fe80::5054:aa:bbbb:cccc on eth0
+       Gateway: 10\&.193\&.11\&.1 (CISCO SYSTEMS, INC\&.) on eth0
+           DNS: 8\&.8\&.8\&.8
+                8\&.8\&.4\&.4
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+In the overall network status, the online state depends on the individual online state of all required links\&. Managed links are required for online by default\&. In this case, the online state is one of the following:
+.PP
+unknown
+.RS 4
+All links have unknown online status (i\&.e\&. there are no required links)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+offline
+.RS 4
+All required links are offline\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+partial
+.RS 4
+Some, but not all, required links are online\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+online
+.RS 4
+All required links are online\&.
+.sp
+Added in version 249\&.
+.RE
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBlldp\fR [\fIPATTERN\&...\fR]
+.RS 4
+Show discovered LLDP (Link Layer Discovery Protocol) neighbors\&. If one or more
+\fIPATTERN\fRs are specified only neighbors on those interfaces are shown\&. Otherwise shows discovered neighbors on all interfaces\&. Note that for this feature to work,
+\fILLDP=\fR
+must be turned on for the specific interface, see
+\fBsystemd.network\fR(5)
+for details\&.
+.sp
+Produces output similar to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+LINK             CHASSIS ID        SYSTEM NAME      CAPS        PORT ID           PORT DESCRIPTION
+enp0s25          00:e0:4c:00:00:00 GS1900           \&.\&.b\&.\&.\&.\&.\&.\&.\&.\&. 2                 Port #2
+
+Capability Flags:
+o \- Other; p \- Repeater;  b \- Bridge; w \- WLAN Access Point; r \- Router;
+t \- Telephone; d \- DOCSIS cable device; a \- Station; c \- Customer VLAN;
+s \- Service VLAN, m \- Two\-port MAC Relay (TPMR)
+
+1 neighbors listed\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fBlabel\fR
+.RS 4
+Show numerical address labels that can be used for address selection\&. This is the same information that
+\fBip-addrlabel\fR(8)
+shows\&. See
+\m[blue]\fBRFC 3484\fR\m[]\&\s-2\u[1]\d\s+2
+for a discussion of address labels\&.
+.sp
+Produces output similar to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Prefix/Prefixlen                          Label
+        ::/0                                  1
+    fc00::/7                                  5
+    fec0::/10                                11
+    2002::/16                                 2
+    3ffe::/16                                12
+ 2001:10::/28                                 7
+    2001::/32                                 6
+::ffff:0\&.0\&.0\&.0/96                             4
+        ::/96                                 3
+       ::1/128                                0
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 234\&.
+.RE
+.PP
+\fBdelete\fR \fIDEVICE\&...\fR
+.RS 4
+Deletes virtual netdevs\&. Takes interface name or index number\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fBup\fR \fIDEVICE\&...\fR
+.RS 4
+Bring devices up\&. Takes interface name or index number\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBdown\fR \fIDEVICE\&...\fR
+.RS 4
+Bring devices down\&. Takes interface name or index number\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBrenew\fR \fIDEVICE\&...\fR
+.RS 4
+Renew dynamic configurations e\&.g\&. addresses received from DHCP server\&. Takes interface name or index number\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fBforcerenew\fR \fIDEVICE\&...\fR
+.RS 4
+Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration\&. Takes interface name or index number\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBreconfigure\fR \fIDEVICE\&...\fR
+.RS 4
+Reconfigure network interfaces\&. Takes interface name or index number\&. Note that this does not reload
+\&.netdev
+or
+\&.network
+corresponding to the specified interface\&. So, if you edit config files, it is necessary to call
+\fBnetworkctl reload\fR
+first to apply new settings\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fBreload\fR
+.RS 4
+Reload
+\&.netdev
+and
+\&.network
+files\&. If a new
+\&.netdev
+file is found, then the corresponding netdev is created\&. Note that even if an existing
+\&.netdev
+is modified or removed,
+\fBsystemd\-networkd\fR
+does not update or remove the netdev\&. If a new, modified or removed
+\&.network
+file is found, then all interfaces which match the file are reconfigured\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fBedit\fR \fIFILE\fR|\fI@DEVICE\fR\&...
+.RS 4
+Edit network configuration files, which include
+\&.network,
+\&.netdev, and
+\&.link
+files\&. If no network config file matching the given name is found, a new one will be created under
+/etc/\&. Specially, if the name is prefixed by
+"@", it will be treated as a network interface, and editing will be performed on the network config files associated with it\&. Additionally, the interface name can be suffixed with
+":network"
+(default) or
+":link", in order to choose the type of network config to operate on\&.
+.sp
+If
+\fB\-\-drop\-in=\fR
+is specified, edit the drop\-in file instead of the main configuration file\&. Unless
+\fB\-\-no\-reload\fR
+is specified,
+\fBsystemd\-networkd\fR
+will be reloaded after the edit of the
+\&.network
+or
+\&.netdev
+files finishes\&. The same applies for
+\&.link
+files and
+\fBsystemd-udevd\fR(8)\&. Note that the changed link settings are not automatically applied after reloading\&. To achieve that, trigger uevents for the corresponding interface\&. Refer to
+\fBsystemd.link\fR(5)
+for more information\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBcat\fR \fIFILE\fR|\fI@DEVICE\fR\&...
+.RS 4
+Show network configuration files\&. This command honors the
+"@"
+prefix in the same way as
+\fBedit\fR\&.
+.sp
+Added in version 254\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-a\fR \fB\-\-all\fR
+.RS 4
+Show all links with
+\fBstatus\fR\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-s\fR \fB\-\-stats\fR
+.RS 4
+Show link statistics with
+\fBstatus\fR\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize the output\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-lines=\fR
+.RS 4
+When used with
+\fBstatus\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument\&. Defaults to 10\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-drop\-in=\fR\fINAME\fR
+.RS 4
+When used with
+\fBedit\fR, edit the drop\-in file
+\fINAME\fR
+instead of the main configuration file\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-no\-reload\fR
+.RS 4
+When used with
+\fBedit\fR,
+\fBsystemd-networkd.service\fR(8)
+or
+\fBsystemd-udevd.service\fR(8)
+will not be reloaded after the editing finishes\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd-networkd.service\fR(8),
+\fBsystemd.network\fR(5),
+\fBsystemd.netdev\fR(5),
+\fBip\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+RFC 3484
+.RS 4
+\%https://tools.ietf.org/html/rfc3484
+.RE
diff --git a/upstream/mageia-cauldron/man1/newaliases.1 b/upstream/mageia-cauldron/man1/newaliases.1
new file mode 100644
index 00000000..9ba8752b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/newaliases.1
@@ -0,0 +1,50 @@
+.\" Copyright (c) 1998-2001 Proofpoint, Inc. and its suppliers.
+.\"	 All rights reserved.
+.\" Copyright (c) 1983, 1997 Eric P. Allman.  All rights reserved.
+.\" Copyright (c) 1985, 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" By using this file, you agree to the terms and conditions set
+.\" forth in the LICENSE file which can be found at the top level of
+.\" the sendmail distribution.
+.\"
+.\"
+.\"     $Id: newaliases.1,v 8.20 2013-11-22 20:51:56 ca Exp $
+.\"
+.TH NEWALIASES 1 "$Date: 2013-11-22 20:51:56 $"
+.SH NAME
+newaliases
+\- rebuild the data base for the mail aliases file
+.SH SYNOPSIS
+.B newaliases
+.SH DESCRIPTION
+.B Newaliases
+rebuilds the random access data base for the mail aliases file
+/etc/aliases.  It must be run each time this file is changed
+in order for the change to take effect.
+.PP
+.B Newaliases
+is identical to ``sendmail -bi''.
+.PP
+The
+.B newaliases
+utility exits 0 on success, and >0 if an error occurs.
+.PP
+Notice: do
+.B not
+use
+.B makemap
+to create the aliases data base, because
+.B newaliases
+puts a special token into the data base that is required by
+.B sendmail.
+.SH FILES
+.TP 2i
+/etc/aliases
+The mail aliases file
+.SH SEE ALSO
+aliases(5), sendmail(8)
+.SH HISTORY
+The
+.B newaliases
+command appeared in 4.0BSD.
diff --git a/upstream/mageia-cauldron/man1/ngettext.1 b/upstream/mageia-cauldron/man1/ngettext.1
new file mode 100644
index 00000000..72df2ab5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ngettext.1
@@ -0,0 +1,73 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH NGETTEXT "1" "October 2022" "GNU gettext-runtime 0.21.1" "User Commands"
+.SH NAME
+ngettext \- translate message and choose plural form
+.SH SYNOPSIS
+.B ngettext
+[\fI\,OPTION\/\fR] [\fI\,TEXTDOMAIN\/\fR] \fI\,MSGID MSGID-PLURAL COUNT\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+The \fBngettext\fP program translates a natural language message into the
+user's language, by looking up the translation in a message catalog, and
+chooses the appropriate plural form, which depends on the number \fICOUNT\fP
+and the language of the message catalog where the translation was found.
+.PP
+Display native language translation of a textual message whose grammatical
+form depends on a number.
+.TP
+\fB\-d\fR, \fB\-\-domain\fR=\fI\,TEXTDOMAIN\/\fR
+retrieve translated message from TEXTDOMAIN
+.TP
+\fB\-c\fR, \fB\-\-context\fR=\fI\,CONTEXT\/\fR
+specify context for MSGID
+.TP
+\fB\-e\fR
+enable expansion of some escape sequences
+.TP
+\fB\-E\fR
+(ignored for compatibility)
+.TP
+[TEXTDOMAIN]
+retrieve translated message from TEXTDOMAIN
+.TP
+MSGID MSGID\-PLURAL
+translate MSGID (singular) / MSGID\-PLURAL (plural)
+.TP
+COUNT
+choose singular/plural form based on this value
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+display version information and exit
+.PP
+If the TEXTDOMAIN parameter is not given, the domain is determined from the
+environment variable TEXTDOMAIN.  If the message catalog is not found in the
+regular directory, another location can be specified with the environment
+variable TEXTDOMAINDIR.
+Standard search directory: /usr/share/locale
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-1997, 2000\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B ngettext
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B ngettext
+programs are properly installed at your site, the command
+.IP
+.B info ngettext
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/nice.1 b/upstream/mageia-cauldron/man1/nice.1
new file mode 100644
index 00000000..441e5004
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nice.1
@@ -0,0 +1,47 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH NICE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+nice \- run a program with modified scheduling priority
+.SH SYNOPSIS
+.B nice
+[\fI\,OPTION\/\fR] [\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Run COMMAND with an adjusted niceness, which affects process scheduling.
+With no COMMAND, print the current niceness.  Niceness values range from
+\fB\-20\fR (most favorable to the process) to 19 (least favorable to the process).
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-n\fR, \fB\-\-adjustment\fR=\fI\,N\/\fR
+add integer N to the niceness (default 10)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NOTE: your shell may have its own version of nice, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBnice\fP(2), \fBrenice\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/nice>
+.br
+or available locally via: info \(aq(coreutils) nice invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/nl.1 b/upstream/mageia-cauldron/man1/nl.1
new file mode 100644
index 00000000..f521427a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nl.1
@@ -0,0 +1,103 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH NL "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+nl \- number lines of files
+.SH SYNOPSIS
+.B nl
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write each FILE to standard output, with line numbers added.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-body\-numbering\fR=\fI\,STYLE\/\fR
+use STYLE for numbering body lines
+.TP
+\fB\-d\fR, \fB\-\-section\-delimiter\fR=\fI\,CC\/\fR
+use CC for logical page delimiters
+.TP
+\fB\-f\fR, \fB\-\-footer\-numbering\fR=\fI\,STYLE\/\fR
+use STYLE for numbering footer lines
+.TP
+\fB\-h\fR, \fB\-\-header\-numbering\fR=\fI\,STYLE\/\fR
+use STYLE for numbering header lines
+.TP
+\fB\-i\fR, \fB\-\-line\-increment\fR=\fI\,NUMBER\/\fR
+line number increment at each line
+.TP
+\fB\-l\fR, \fB\-\-join\-blank\-lines\fR=\fI\,NUMBER\/\fR
+group of NUMBER empty lines counted as one
+.TP
+\fB\-n\fR, \fB\-\-number\-format\fR=\fI\,FORMAT\/\fR
+insert line numbers according to FORMAT
+.TP
+\fB\-p\fR, \fB\-\-no\-renumber\fR
+do not reset line numbers for each section
+.TP
+\fB\-s\fR, \fB\-\-number\-separator\fR=\fI\,STRING\/\fR
+add STRING after (possible) line number
+.TP
+\fB\-v\fR, \fB\-\-starting\-line\-number\fR=\fI\,NUMBER\/\fR
+first line number for each section
+.TP
+\fB\-w\fR, \fB\-\-number\-width\fR=\fI\,NUMBER\/\fR
+use NUMBER columns for line numbers
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Default options are: \fB\-bt\fR \fB\-d\fR'\e:' \fB\-fn\fR \fB\-hn\fR \fB\-i1\fR \fB\-l1\fR \fB\-n\fR'rn' \fB\-s\fR<TAB> \fB\-v1\fR \fB\-w6\fR
+.PP
+CC are two delimiter characters used to construct logical page delimiters;
+a missing second character implies ':'.  As a GNU extension one can specify
+more than two characters, and also specifying the empty string (\fB\-d\fR '')
+disables section matching.
+.PP
+STYLE is one of:
+.TP
+a
+number all lines
+.TP
+t
+number only nonempty lines
+.TP
+n
+number no lines
+.TP
+pBRE
+number only lines that contain a match for the basic regular
+expression, BRE
+.PP
+FORMAT is one of:
+.TP
+ln
+left justified, no leading zeros
+.TP
+rn
+right justified, no leading zeros
+.TP
+rz
+right justified, leading zeros
+.SH AUTHOR
+Written by Scott Bartram and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/nl>
+.br
+or available locally via: info \(aq(coreutils) nl invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/nm.1 b/upstream/mageia-cauldron/man1/nm.1
new file mode 100644
index 00000000..7dd0843c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nm.1
@@ -0,0 +1,689 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "NM 1"
+.TH NM 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+nm \- list symbols from object files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+nm [\fB\-A\fR|\fB\-o\fR|\fB\-\-print\-file\-name\fR]
+   [\fB\-a\fR|\fB\-\-debug\-syms\fR]
+   [\fB\-B\fR|\fB\-\-format=bsd\fR]
+   [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]]
+   [\fB\-D\fR|\fB\-\-dynamic\fR]
+   [\fB\-f\fR\fIformat\fR|\fB\-\-format=\fR\fIformat\fR]
+   [\fB\-g\fR|\fB\-\-extern\-only\fR]
+   [\fB\-h\fR|\fB\-\-help\fR]
+   [\fB\-\-ifunc\-chars=\fR\fI\s-1CHARS\s0\fR]
+   [\fB\-j\fR|\fB\-\-format=just\-symbols\fR]
+   [\fB\-l\fR|\fB\-\-line\-numbers\fR] [\fB\-\-inlines\fR]
+   [\fB\-n\fR|\fB\-v\fR|\fB\-\-numeric\-sort\fR]
+   [\fB\-P\fR|\fB\-\-portability\fR]
+   [\fB\-p\fR|\fB\-\-no\-sort\fR]
+   [\fB\-r\fR|\fB\-\-reverse\-sort\fR]
+   [\fB\-S\fR|\fB\-\-print\-size\fR]
+   [\fB\-s\fR|\fB\-\-print\-armap\fR]
+   [\fB\-t\fR \fIradix\fR|\fB\-\-radix=\fR\fIradix\fR]
+   [\fB\-u\fR|\fB\-\-undefined\-only\fR]
+   [\fB\-U\fR|\fB\-\-defined\-only\fR]
+   [\fB\-V\fR|\fB\-\-version\fR]
+   [\fB\-W\fR|\fB\-\-no\-weak\fR]
+   [\fB\-X 32_64\fR]
+   [\fB\-\-no\-demangle\fR]
+   [\fB\-\-no\-recurse\-limit\fR|\fB\-\-recurse\-limit\fR]]
+   [\fB\-\-plugin\fR \fIname\fR]
+   [\fB\-\-size\-sort\fR]
+   [\fB\-\-special\-syms\fR]
+   [\fB\-\-synthetic\fR]
+   [\fB\-\-target=\fR\fIbfdname\fR]
+   [\fB\-\-unicode=\fR\fImethod\fR]
+   [\fB\-\-with\-symbol\-versions\fR]
+   [\fB\-\-without\-symbol\-versions\fR]
+   [\fIobjfile\fR...]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\s-1GNU\s0 \fBnm\fR lists the symbols from object files \fIobjfile\fR....
+If no object files are listed as arguments, \fBnm\fR assumes the file
+\&\fIa.out\fR.
+.PP
+For each symbol, \fBnm\fR shows:
+.IP "\(bu" 4
+The symbol value, in the radix selected by options (see below), or
+hexadecimal by default.
+.IP "\(bu" 4
+The symbol type.  At least the following types are used; others are, as
+well, depending on the object file format.  If lowercase, the symbol is
+usually local; if uppercase, the symbol is global (external).  There
+are however a few lowercase symbols that are shown for special global
+symbols (\f(CW\*(C`u\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`w\*(C'\fR).
+.RS 4
+.ie n .IP """A""" 4
+.el .IP "\f(CWA\fR" 4
+.IX Item "A"
+The symbol's value is absolute, and will not be changed by further
+linking.
+.ie n .IP """B""" 4
+.el .IP "\f(CWB\fR" 4
+.IX Item "B"
+.PD 0
+.ie n .IP """b""" 4
+.el .IP "\f(CWb\fR" 4
+.IX Item "b"
+.PD
+The symbol is in the \s-1BSS\s0 data section.  This section typically
+contains zero-initialized or uninitialized data, although the exact
+behavior is system dependent.
+.ie n .IP """C""" 4
+.el .IP "\f(CWC\fR" 4
+.IX Item "C"
+.PD 0
+.ie n .IP """c""" 4
+.el .IP "\f(CWc\fR" 4
+.IX Item "c"
+.PD
+The symbol is common.  Common symbols are uninitialized data.  When
+linking, multiple common symbols may appear with the same name.  If the
+symbol is defined anywhere, the common symbols are treated as undefined
+references.
+The lower case \fIc\fR character is used when the symbol is in a
+special section for small commons.
+.ie n .IP """D""" 4
+.el .IP "\f(CWD\fR" 4
+.IX Item "D"
+.PD 0
+.ie n .IP """d""" 4
+.el .IP "\f(CWd\fR" 4
+.IX Item "d"
+.PD
+The symbol is in the initialized data section.
+.ie n .IP """G""" 4
+.el .IP "\f(CWG\fR" 4
+.IX Item "G"
+.PD 0
+.ie n .IP """g""" 4
+.el .IP "\f(CWg\fR" 4
+.IX Item "g"
+.PD
+The symbol is in an initialized data section for small objects.  Some
+object file formats permit more efficient access to small data objects,
+such as a global int variable as opposed to a large global array.
+.ie n .IP """i""" 4
+.el .IP "\f(CWi\fR" 4
+.IX Item "i"
+For \s-1PE\s0 format files this indicates that the symbol is in a section
+specific to the implementation of DLLs.
+.Sp
+For \s-1ELF\s0 format files this indicates that the symbol is an indirect
+function.  This is a \s-1GNU\s0 extension to the standard set of \s-1ELF\s0 symbol
+types.  It indicates a symbol which if referenced by a relocation does
+not evaluate to its address, but instead must be invoked at runtime.
+The runtime execution will then return the value to be used in the
+relocation.
+.Sp
+Note \- the actual symbols display for \s-1GNU\s0 indirect symbols is
+controlled by the \fB\-\-ifunc\-chars\fR command line option.  If this
+option has been provided then the first character in the string will
+be used for global indirect function symbols.  If the string contains
+a second character then that will be used for local indirect function
+symbols.
+.ie n .IP """I""" 4
+.el .IP "\f(CWI\fR" 4
+.IX Item "I"
+The symbol is an indirect reference to another symbol.
+.ie n .IP """N""" 4
+.el .IP "\f(CWN\fR" 4
+.IX Item "N"
+The symbol is a debugging symbol.
+.ie n .IP """n""" 4
+.el .IP "\f(CWn\fR" 4
+.IX Item "n"
+The symbol is in the read-only data section.
+.ie n .IP """p""" 4
+.el .IP "\f(CWp\fR" 4
+.IX Item "p"
+The symbol is in a stack unwind section.
+.ie n .IP """R""" 4
+.el .IP "\f(CWR\fR" 4
+.IX Item "R"
+.PD 0
+.ie n .IP """r""" 4
+.el .IP "\f(CWr\fR" 4
+.IX Item "r"
+.PD
+The symbol is in a read only data section.
+.ie n .IP """S""" 4
+.el .IP "\f(CWS\fR" 4
+.IX Item "S"
+.PD 0
+.ie n .IP """s""" 4
+.el .IP "\f(CWs\fR" 4
+.IX Item "s"
+.PD
+The symbol is in an uninitialized or zero-initialized data section
+for small objects.
+.ie n .IP """T""" 4
+.el .IP "\f(CWT\fR" 4
+.IX Item "T"
+.PD 0
+.ie n .IP """t""" 4
+.el .IP "\f(CWt\fR" 4
+.IX Item "t"
+.PD
+The symbol is in the text (code) section.
+.ie n .IP """U""" 4
+.el .IP "\f(CWU\fR" 4
+.IX Item "U"
+The symbol is undefined.
+.ie n .IP """u""" 4
+.el .IP "\f(CWu\fR" 4
+.IX Item "u"
+The symbol is a unique global symbol.  This is a \s-1GNU\s0 extension to the
+standard set of \s-1ELF\s0 symbol bindings.  For such a symbol the dynamic linker
+will make sure that in the entire process there is just one symbol with
+this name and type in use.
+.ie n .IP """V""" 4
+.el .IP "\f(CWV\fR" 4
+.IX Item "V"
+.PD 0
+.ie n .IP """v""" 4
+.el .IP "\f(CWv\fR" 4
+.IX Item "v"
+.PD
+The symbol is a weak object.  When a weak defined symbol is linked with
+a normal defined symbol, the normal defined symbol is used with no error.
+When a weak undefined symbol is linked and the symbol is not defined,
+the value of the weak symbol becomes zero with no error.  On some
+systems, uppercase indicates that a default value has been specified.
+.ie n .IP """W""" 4
+.el .IP "\f(CWW\fR" 4
+.IX Item "W"
+.PD 0
+.ie n .IP """w""" 4
+.el .IP "\f(CWw\fR" 4
+.IX Item "w"
+.PD
+The symbol is a weak symbol that has not been specifically tagged as a
+weak object symbol.  When a weak defined symbol is linked with a normal
+defined symbol, the normal defined symbol is used with no error.
+When a weak undefined symbol is linked and the symbol is not defined,
+the value of the symbol is determined in a system-specific manner without
+error.  On some systems, uppercase indicates that a default value has been
+specified.
+.ie n .IP """\-""" 4
+.el .IP "\f(CW\-\fR" 4
+.IX Item "-"
+The symbol is a stabs symbol in an a.out object file.  In this case, the
+next values printed are the stabs other field, the stabs desc field, and
+the stab type.  Stabs symbols are used to hold debugging information.
+.ie n .IP """?""" 4
+.el .IP "\f(CW?\fR" 4
+.IX Item "?"
+The symbol type is unknown, or object file format specific.
+.RE
+.RS 4
+.RE
+.IP "\(bu" 4
+The symbol name.  If a symbol has version information associated with it,
+then the version information is displayed as well.  If the versioned
+symbol is undefined or hidden from linker, the version string is displayed
+as a suffix to the symbol name, preceded by an @ character.  For example
+\&\fBfoo@VER_1\fR.  If the version is the default version to be used when
+resolving unversioned references to the symbol, then it is displayed as a
+suffix preceded by two @ characters.  For example \fBfoo@@VER_2\fR.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+.IP "\fB\-A\fR" 4
+.IX Item "-A"
+.PD 0
+.IP "\fB\-o\fR" 4
+.IX Item "-o"
+.IP "\fB\-\-print\-file\-name\fR" 4
+.IX Item "--print-file-name"
+.PD
+Precede each symbol by the name of the input file (or archive member)
+in which it was found, rather than identifying the input file once only,
+before all of its symbols.
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-debug\-syms\fR" 4
+.IX Item "--debug-syms"
+.PD
+Display all symbols, even debugger-only symbols; normally these are not
+listed.
+.IP "\fB\-B\fR" 4
+.IX Item "-B"
+The same as \fB\-\-format=bsd\fR (for compatibility with the \s-1MIPS\s0 \fBnm\fR).
+.IP "\fB\-C\fR" 4
+.IX Item "-C"
+.PD 0
+.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
+.IX Item "--demangle[=style]"
+.PD
+Decode (\fIdemangle\fR) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes \*(C+ function names readable. Different compilers have different
+mangling styles. The optional demangling style argument can be used to
+choose an appropriate demangling style for your compiler.
+.IP "\fB\-\-no\-demangle\fR" 4
+.IX Item "--no-demangle"
+Do not demangle low-level symbol names.  This is the default.
+.IP "\fB\-\-recurse\-limit\fR" 4
+.IX Item "--recurse-limit"
+.PD 0
+.IP "\fB\-\-no\-recurse\-limit\fR" 4
+.IX Item "--no-recurse-limit"
+.IP "\fB\-\-recursion\-limit\fR" 4
+.IX Item "--recursion-limit"
+.IP "\fB\-\-no\-recursion\-limit\fR" 4
+.IX Item "--no-recursion-limit"
+.PD
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings.  Since the name mangling formats allow for
+an infinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault.  The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+.Sp
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names.  Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.IP "\fB\-\-dynamic\fR" 4
+.IX Item "--dynamic"
+.PD
+Display the dynamic symbols rather than the normal symbols.  This is
+only meaningful for dynamic objects, such as certain types of shared
+libraries.
+.IP "\fB\-f\fR \fIformat\fR" 4
+.IX Item "-f format"
+.PD 0
+.IP "\fB\-\-format=\fR\fIformat\fR" 4
+.IX Item "--format=format"
+.PD
+Use the output format \fIformat\fR, which can be \f(CW\*(C`bsd\*(C'\fR,
+\&\f(CW\*(C`sysv\*(C'\fR, \f(CW\*(C`posix\*(C'\fR or \f(CW\*(C`just\-symbols\*(C'\fR.  The default is \f(CW\*(C`bsd\*(C'\fR.
+Only the first character of \fIformat\fR is significant; it can be
+either upper or lower case.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-\-extern\-only\fR" 4
+.IX Item "--extern-only"
+.PD
+Display only external symbols.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Show a summary of the options to \fBnm\fR and exit.
+.IP "\fB\-\-ifunc\-chars=\fR\fI\s-1CHARS\s0\fR" 4
+.IX Item "--ifunc-chars=CHARS"
+When display \s-1GNU\s0 indirect function symbols \fBnm\fR will default
+to using the \f(CW\*(C`i\*(C'\fR character for both local indirect functions and
+global indirect functions.  The \fB\-\-ifunc\-chars\fR option allows
+the user to specify a string containing one or two characters. The
+first character will be used for global indirect function symbols and
+the second character, if present, will be used for local indirect
+function symbols.
+.IP "\fBj\fR" 4
+.IX Item "j"
+The same as \fB\-\-format=just\-symbols\fR.
+.IP "\fB\-l\fR" 4
+.IX Item "-l"
+.PD 0
+.IP "\fB\-\-line\-numbers\fR" 4
+.IX Item "--line-numbers"
+.PD
+For each symbol, use debugging information to try to find a filename and
+line number.  For a defined symbol, look for the line number of the
+address of the symbol.  For an undefined symbol, look for the line
+number of a relocation entry which refers to the symbol.  If line number
+information can be found, print it after the other symbol information.
+.IP "\fB\-\-inlines\fR" 4
+.IX Item "--inlines"
+When option \fB\-l\fR is active, if the address belongs to a
+function that was inlined, then this option causes the source 
+information for all enclosing scopes back to the first non-inlined
+function to be printed as well.  For example, if \f(CW\*(C`main\*(C'\fR inlines
+\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from
+\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR
+will also be printed.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.IP "\fB\-\-numeric\-sort\fR" 4
+.IX Item "--numeric-sort"
+.PD
+Sort symbols numerically by their addresses, rather than alphabetically
+by their names.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-no\-sort\fR" 4
+.IX Item "--no-sort"
+.PD
+Do not bother to sort the symbols in any order; print them in the order
+encountered.
+.IP "\fB\-P\fR" 4
+.IX Item "-P"
+.PD 0
+.IP "\fB\-\-portability\fR" 4
+.IX Item "--portability"
+.PD
+Use the \s-1POSIX.2\s0 standard output format instead of the default format.
+Equivalent to \fB\-f posix\fR.
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-\-reverse\-sort\fR" 4
+.IX Item "--reverse-sort"
+.PD
+Reverse the order of the sort (whether numeric or alphabetic); let the
+last come first.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-print\-size\fR" 4
+.IX Item "--print-size"
+.PD
+Print both value and size of defined symbols for the \f(CW\*(C`bsd\*(C'\fR output style.
+This option has no effect for object formats that do not record symbol
+sizes, unless \fB\-\-size\-sort\fR is also used in which case a
+calculated size is displayed.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-print\-armap\fR" 4
+.IX Item "--print-armap"
+.PD
+When listing symbols from archive members, include the index: a mapping
+(stored in the archive by \fBar\fR or \fBranlib\fR) of which modules
+contain definitions for which names.
+.IP "\fB\-t\fR \fIradix\fR" 4
+.IX Item "-t radix"
+.PD 0
+.IP "\fB\-\-radix=\fR\fIradix\fR" 4
+.IX Item "--radix=radix"
+.PD
+Use \fIradix\fR as the radix for printing the symbol values.  It must be
+\&\fBd\fR for decimal, \fBo\fR for octal, or \fBx\fR for hexadecimal.
+.IP "\fB\-u\fR" 4
+.IX Item "-u"
+.PD 0
+.IP "\fB\-\-undefined\-only\fR" 4
+.IX Item "--undefined-only"
+.PD
+Display only undefined symbols (those external to each object file).
+By default both defined and undefined symbols are displayed.
+.IP "\fB\-U\fR" 4
+.IX Item "-U"
+.PD 0
+.IP "\fB\-\-defined\-only\fR" 4
+.IX Item "--defined-only"
+.PD
+Display only defined symbols for each object file.
+By default both defined and undefined symbols are displayed.
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Show the version number of \fBnm\fR and exit.
+.IP "\fB\-X\fR" 4
+.IX Item "-X"
+This option is ignored for compatibility with the \s-1AIX\s0 version of
+\&\fBnm\fR.  It takes one parameter which must be the string
+\&\fB32_64\fR.  The default mode of \s-1AIX\s0 \fBnm\fR corresponds
+to \fB\-X 32\fR, which is not supported by \s-1GNU\s0 \fBnm\fR.
+.IP "\fB\-\-plugin\fR \fIname\fR" 4
+.IX Item "--plugin name"
+Load the plugin called \fIname\fR to add support for extra target
+types.  This option is only available if the toolchain has been built
+with plugin support enabled.
+.Sp
+If \fB\-\-plugin\fR is not provided, but plugin support has been
+enabled then \fBnm\fR iterates over the files in
+\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
+plugin that claims the object in question is used.
+.Sp
+Please note that this plugin search directory is \fInot\fR the one
+used by \fBld\fR's \fB\-plugin\fR option.  In order to make
+\&\fBnm\fR use the  linker plugin it must be copied into the
+\&\fI${libdir}/bfd\-plugins\fR directory.  For \s-1GCC\s0 based compilations
+the linker plugin is called \fIliblto_plugin.so.0.0.0\fR.  For Clang
+based compilations it is called \fILLVMgold.so\fR.  The \s-1GCC\s0 plugin
+is always backwards compatible with earlier versions, so it is
+sufficient to just copy the newest one.
+.IP "\fB\-\-size\-sort\fR" 4
+.IX Item "--size-sort"
+Sort symbols by size.  For \s-1ELF\s0 objects symbol sizes are read from the
+\&\s-1ELF,\s0 for other object types the symbol sizes are computed as the
+difference between the value of the symbol and the value of the symbol
+with the next higher value.  If the \f(CW\*(C`bsd\*(C'\fR output format is used
+the size of the symbol is printed, rather than the value, and
+\&\fB\-S\fR must be used in order both size and value to be printed.
+.Sp
+Note \- this option does not work if \fB\-\-undefined\-only\fR has been
+enabled as undefined symbols have no size.
+.IP "\fB\-\-special\-syms\fR" 4
+.IX Item "--special-syms"
+Display symbols which have a target-specific special meaning.  These
+symbols are usually used by the target for some special processing and
+are not normally helpful when included in the normal symbol lists.
+For example for \s-1ARM\s0 targets this option would skip the mapping symbols
+used to mark transitions between \s-1ARM\s0 code, \s-1THUMB\s0 code and data.
+.IP "\fB\-\-synthetic\fR" 4
+.IX Item "--synthetic"
+Include synthetic symbols in the output.  These are special symbols
+created by the linker for various purposes.  They are not shown by
+default since they are not part of the binary's original source code.
+.IP "\fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR" 4
+.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
+Controls the display of \s-1UTF\-8\s0 encoded multibyte characters in strings.
+The default (\fB\-\-unicode=default\fR) is to give them no special
+treatment.  The \fB\-\-unicode=locale\fR option displays the sequence
+in the current locale, which may or may not support them.  The options
+\&\fB\-\-unicode=hex\fR and \fB\-\-unicode=invalid\fR display them as
+hex byte sequences enclosed by either angle brackets or curly braces.
+.Sp
+The \fB\-\-unicode=escape\fR option displays them as escape sequences
+(\fI\euxxxx\fR) and the \fB\-\-unicode=highlight\fR option displays
+them as escape sequences highlighted in red (if supported by the
+output device).  The colouring is intended to draw attention to the
+presence of unicode sequences where they might not be expected.
+.IP "\fB\-W\fR" 4
+.IX Item "-W"
+.PD 0
+.IP "\fB\-\-no\-weak\fR" 4
+.IX Item "--no-weak"
+.PD
+Do not display weak symbols.
+.IP "\fB\-\-with\-symbol\-versions\fR" 4
+.IX Item "--with-symbol-versions"
+.PD 0
+.IP "\fB\-\-without\-symbol\-versions\fR" 4
+.IX Item "--without-symbol-versions"
+.PD
+Enables or disables the display of symbol version information.  The
+version string is displayed as a suffix to the symbol name, preceded
+by an @ character.  For example \fBfoo@VER_1\fR.  If the version is
+the default version to be used when resolving unversioned references
+to the symbol then it is displayed as a suffix preceded by two @
+characters.  For example \fBfoo@@VER_2\fR.  By default, symbol
+version information is displayed.
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+Specify an object code format other than your system's default format.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBar\fR\|(1), \fBobjdump\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/nohup.1 b/upstream/mageia-cauldron/man1/nohup.1
new file mode 100644
index 00000000..a2049ab5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nohup.1
@@ -0,0 +1,46 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH NOHUP "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+nohup \- run a command immune to hangups, with output to a non-tty
+.SH SYNOPSIS
+.B nohup
+\fI\,COMMAND \/\fR[\fI\,ARG\/\fR]...
+.br
+.B nohup
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Run COMMAND, ignoring hangup signals.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If standard input is a terminal, redirect it from an unreadable file.
+If standard output is a terminal, append output to 'nohup.out' if possible,
+\&'$HOME/nohup.out' otherwise.
+If standard error is a terminal, redirect it to standard output.
+To save output to FILE, use 'nohup COMMAND > FILE'.
+.PP
+NOTE: your shell may have its own version of nohup, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/nohup>
+.br
+or available locally via: info \(aq(coreutils) nohup invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/nproc.1 b/upstream/mageia-cauldron/man1/nproc.1
new file mode 100644
index 00000000..0d9cc810
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nproc.1
@@ -0,0 +1,40 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH NPROC "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+nproc \- print the number of processing units available
+.SH SYNOPSIS
+.B nproc
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the number of processing units available to the current process,
+which may be less than the number of online processors
+.TP
+\fB\-\-all\fR
+print the number of installed processors
+.TP
+\fB\-\-ignore\fR=\fI\,N\/\fR
+if possible, exclude N processing units
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Giuseppe Scrivano.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/nproc>
+.br
+or available locally via: info \(aq(coreutils) nproc invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/nroff.1 b/upstream/mageia-cauldron/man1/nroff.1
new file mode 100644
index 00000000..c6919aea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/nroff.1
@@ -0,0 +1,255 @@
+.TH NROFF 1 "23 November 2018" "groff 1.22.4"
+.SH NAME
+nroff \- use groff to format documents for TTY devices
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY nroff
+.RB [ \-CchipStUv ]
+[\c
+.BI \-d cs\c
+]
+[\c
+.BI \-M dir\c
+]
+[\c
+.BI \-m name\c
+]
+[\c
+.BI \-n num\c
+]
+[\c
+.BI \-o list\c
+]
+[\c
+.BI \-r cn\c
+]
+[\c
+.BI \-T name\c
+]
+[\c
+.BI \-W warning\c
+]
+[\c
+.BI \-w warning\c
+]
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY nroff
+.B \-\-help
+.YS
+.
+.SY nroff
+.B \-v
+.SY nroff
+.B \-\-version
+.YS
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I nroff
+formats documents written in the
+.IR roff (7)
+language for typewriter-like devices such as terminal emulators.
+.
+.P
+GNU
+.I nroff
+emulates the traditional Unix
+.I nroff
+command using
+.IR groff (1).
+.
+.I nroff
+generates output via
+.IR grotty (1),
+.IR groff 's
+TTY output device,
+which needs to know the character encoding scheme used by the terminal.
+.
+Consequently,
+acceptable arguments to the
+.B \-T
+option are
+.BR ascii ,
+.BR latin1 ,
+.BR utf8 ,
+and
+.BR cp1047 ;
+any others are ignored.
+.
+If neither the
+.I \%GROFF_TYPESETTER
+environment variable nor the
+.B \-T
+command-line option (which overrides the environment variable)
+specifies a (valid) device,
+.I nroff
+consults the locale to select an appropriate output device.
+.
+It first tries the
+.IR locale (1)
+program,
+then checks several locale-related environment variables;
+see \(lqENVIRONMENT\(rq, below.
+.
+If all of the foregoing fail,
+.B \-Tascii
+is implied.
+.
+.
+.P
+Whitespace is not permitted between an option and its argument.
+.
+The
+.B \-h
+and
+.B \-c
+options
+are equivalent to
+.IR grotty 's
+options
+.B \-h
+(using tabs in the output) and
+.B \-c
+(using the old output scheme instead of SGR escape sequences).
+.
+The
+.BR \-d ,
+.BR \-C ,
+.BR \-i ,
+.BR \-M ,
+.BR \-m ,
+.BR \-n ,
+.BR \-o ,
+.BR \-r ,
+.BR \-w ,
+and
+.B \-W
+options have the effect described in
+.IR troff (1).
+.
+In addition,
+.I nroff
+ignores
+.BR \-e ,
+.BR \-q ,
+and
+.B \-s
+(which are not implemented in
+.IR troff ).
+.
+The options
+.B \-p
+(pic),
+.B \-t
+(tbl),
+.B \-S
+(safer), and
+.B \-U
+(unsafe) are passed to
+.IR groff .
+.
+.B \-v
+and
+.B \-\-version
+show version information,
+while
+.B \-\-help
+displays a usage message;
+all exit afterward.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_TYPESETTER
+specifies the default output device for
+.IR groff .
+.
+.
+.TP
+.I GROFF_BIN_PATH
+is a colon-separated list of directories in which to search for the
+.I groff
+executable before searching in
+.IR PATH .
+.
+If unset,
+.I /usr/\:bin
+is used.
+.
+.
+.TP
+.I LC_ALL
+.TQ
+.I LC_CTYPE
+.TQ
+.I LANG
+.TQ
+.I LESSCHARSET
+are pattern-matched in this order for standard character encodings
+supported by
+.I groff
+in the event no
+.B \-T
+option is given and
+.I GROFF_TYPESETTER
+is unset.
+.
+.
+.\" ====================================================================
+.SH NOTES
+.\" ====================================================================
+.
+Character definitions in the file
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/\:tty\-char.tmac
+are loaded to replace unrepresentable glyphs.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.IR groff (1),
+.IR troff (1),
+.IR grotty (1),
+.IR locale (1),
+.IR roff (7)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/numfmt.1 b/upstream/mageia-cauldron/man1/numfmt.1
new file mode 100644
index 00000000..0a8613ef
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/numfmt.1
@@ -0,0 +1,185 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH NUMFMT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+numfmt \- Convert numbers from/to human-readable strings
+.SH SYNOPSIS
+.B numfmt
+[\fI\,OPTION\/\fR]... [\fI\,NUMBER\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Reformat NUMBER(s), or the numbers from standard input if none are specified.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-\-debug\fR
+print warnings about invalid input
+.TP
+\fB\-d\fR, \fB\-\-delimiter\fR=\fI\,X\/\fR
+use X instead of whitespace for field delimiter
+.TP
+\fB\-\-field\fR=\fI\,FIELDS\/\fR
+replace the numbers in these input fields (default=1);
+see FIELDS below
+.TP
+\fB\-\-format\fR=\fI\,FORMAT\/\fR
+use printf style floating\-point FORMAT;
+see FORMAT below for details
+.TP
+\fB\-\-from\fR=\fI\,UNIT\/\fR
+auto\-scale input numbers to UNITs; default is 'none';
+see UNIT below
+.TP
+\fB\-\-from\-unit\fR=\fI\,N\/\fR
+specify the input unit size (instead of the default 1)
+.TP
+\fB\-\-grouping\fR
+use locale\-defined grouping of digits, e.g. 1,000,000
+(which means it has no effect in the C/POSIX locale)
+.TP
+\fB\-\-header\fR[=\fI\,N\/\fR]
+print (without converting) the first N header lines;
+N defaults to 1 if not specified
+.TP
+\fB\-\-invalid\fR=\fI\,MODE\/\fR
+failure mode for invalid numbers: MODE can be:
+abort (default), fail, warn, ignore
+.TP
+\fB\-\-padding\fR=\fI\,N\/\fR
+pad the output to N characters; positive N will
+right\-align; negative N will left\-align;
+padding is ignored if the output is wider than N;
+the default is to automatically pad if a whitespace
+is found
+.TP
+\fB\-\-round\fR=\fI\,METHOD\/\fR
+use METHOD for rounding when scaling; METHOD can be:
+up, down, from\-zero (default), towards\-zero, nearest
+.TP
+\fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
+add SUFFIX to output numbers, and accept optional
+SUFFIX in input numbers
+.TP
+\fB\-\-to\fR=\fI\,UNIT\/\fR
+auto\-scale output numbers to UNITs; see UNIT below
+.TP
+\fB\-\-to\-unit\fR=\fI\,N\/\fR
+the output unit size (instead of the default 1)
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SS "UNIT options:"
+.TP
+none
+no auto\-scaling is done; suffixes will trigger an error
+.TP
+auto
+accept optional single/two letter suffix:
+.IP
+1K = 1000,
+1Ki = 1024,
+1M = 1000000,
+1Mi = 1048576,
+.TP
+si
+accept optional single letter suffix:
+.IP
+1K = 1000,
+1M = 1000000,
+\&...
+.TP
+iec
+accept optional single letter suffix:
+.IP
+1K = 1024,
+1M = 1048576,
+\&...
+.TP
+iec\-i
+accept optional two\-letter suffix:
+.IP
+1Ki = 1024,
+1Mi = 1048576,
+\&...
+.SS "FIELDS supports \fBcut\fP(1) style field ranges:"
+.TP
+N
+N'th field, counted from 1
+.TP
+N\-
+from N'th field, to end of line
+.TP
+N\-M
+from N'th to M'th field (inclusive)
+.TP
+\fB\-M\fR
+from first to M'th field (inclusive)
+.TP
+\-
+all fields
+.PP
+Multiple fields/ranges can be separated with commas
+.PP
+FORMAT must be suitable for printing one floating\-point argument '%f'.
+Optional quote (%'f) will enable \fB\-\-grouping\fR (if supported by current locale).
+Optional width value (%10f) will pad output. Optional zero (%010f) width
+will zero pad the number. Optional negative values (%\-10f) will left align.
+Optional precision (%.1f) will override the input determined precision.
+.PP
+Exit status is 0 if all input numbers were successfully converted.
+By default, numfmt will stop at the first conversion error with exit status 2.
+With \fB\-\-invalid=\fR'fail' a warning is printed for each conversion error
+and the exit status is 2.  With \fB\-\-invalid=\fR'warn' each conversion error is
+diagnosed, but the exit status is 0.  With \fB\-\-invalid=\fR'ignore' conversion
+errors are not diagnosed and the exit status is 0.
+.SH EXAMPLES
+.IP
+\f(CW$ numfmt --to=si 1000\fR
+.IP
+\-> "1.0K"
+.IP
+\f(CW$ numfmt --to=iec 2048\fR
+.IP
+\-> "2.0K"
+.IP
+\f(CW$ numfmt --to=iec-i 4096\fR
+.IP
+\-> "4.0Ki"
+.IP
+\f(CW$ echo 1K | numfmt --from=si\fR
+.IP
+\-> "1000"
+.IP
+\f(CW$ echo 1K | numfmt --from=iec\fR
+.IP
+\-> "1024"
+.IP
+\f(CW$ df -B1 | numfmt --header --field 2-4 --to=si\fR
+.br
+\f(CW$ ls -l  | numfmt --header --field 5 --to=iec\fR
+.br
+\f(CW$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\fR
+.br
+\f(CW$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\fR
+.SH AUTHOR
+Written by Assaf Gordon.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/numfmt>
+.br
+or available locally via: info \(aq(coreutils) numfmt invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/objcopy.1 b/upstream/mageia-cauldron/man1/objcopy.1
new file mode 100644
index 00000000..63e6bc68
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/objcopy.1
@@ -0,0 +1,1250 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "OBJCOPY 1"
+.TH OBJCOPY 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+objcopy \- copy and translate object files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+objcopy [\fB\-F\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR]
+        [\fB\-I\fR \fIbfdname\fR|\fB\-\-input\-target=\fR\fIbfdname\fR]
+        [\fB\-O\fR \fIbfdname\fR|\fB\-\-output\-target=\fR\fIbfdname\fR]
+        [\fB\-B\fR \fIbfdarch\fR|\fB\-\-binary\-architecture=\fR\fIbfdarch\fR]
+        [\fB\-S\fR|\fB\-\-strip\-all\fR]
+        [\fB\-g\fR|\fB\-\-strip\-debug\fR]
+        [\fB\-\-strip\-unneeded\fR]
+        [\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-\-keep\-file\-symbols\fR]
+        [\fB\-\-keep\-section\-symbols\fR]
+        [\fB\-N\fR \fIsymbolname\fR|\fB\-\-strip\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-G\fR \fIsymbolname\fR|\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-\-localize\-hidden\fR]
+        [\fB\-L\fR \fIsymbolname\fR|\fB\-\-localize\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-\-globalize\-symbols=\fR\fIfilename\fR]
+        [\fB\-W\fR \fIsymbolname\fR|\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR]
+        [\fB\-w\fR|\fB\-\-wildcard\fR]
+        [\fB\-x\fR|\fB\-\-discard\-all\fR]
+        [\fB\-X\fR|\fB\-\-discard\-locals\fR]
+        [\fB\-b\fR \fIbyte\fR|\fB\-\-byte=\fR\fIbyte\fR]
+        [\fB\-i\fR [\fIbreadth\fR]|\fB\-\-interleave\fR[=\fIbreadth\fR]]
+        [\fB\-\-interleave\-width=\fR\fIwidth\fR]
+        [\fB\-j\fR \fIsectionpattern\fR|\fB\-\-only\-section=\fR\fIsectionpattern\fR]
+        [\fB\-R\fR \fIsectionpattern\fR|\fB\-\-remove\-section=\fR\fIsectionpattern\fR]
+        [\fB\-\-keep\-section=\fR\fIsectionpattern\fR]
+        [\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR]
+        [\fB\-p\fR|\fB\-\-preserve\-dates\fR]
+        [\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR]
+        [\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR]
+        [\fB\-\-debugging\fR]
+        [\fB\-\-gap\-fill=\fR\fIval\fR]
+        [\fB\-\-pad\-to=\fR\fIaddress\fR]
+        [\fB\-\-set\-start=\fR\fIval\fR]
+        [\fB\-\-adjust\-start=\fR\fIincr\fR]
+        [\fB\-\-change\-addresses=\fR\fIincr\fR]
+        [\fB\-\-change\-section\-address\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR]
+        [\fB\-\-change\-section\-lma\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR]
+        [\fB\-\-change\-section\-vma\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR]
+        [\fB\-\-change\-warnings\fR] [\fB\-\-no\-change\-warnings\fR]
+        [\fB\-\-set\-section\-flags\fR \fIsectionpattern\fR=\fIflags\fR]
+        [\fB\-\-set\-section\-alignment\fR \fIsectionpattern\fR=\fIalign\fR]
+        [\fB\-\-add\-section\fR \fIsectionname\fR=\fIfilename\fR]
+        [\fB\-\-dump\-section\fR \fIsectionname\fR=\fIfilename\fR]
+        [\fB\-\-update\-section\fR \fIsectionname\fR=\fIfilename\fR]
+        [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR[,\fIflags\fR]]
+        [\fB\-\-long\-section\-names\fR {enable,disable,keep}]
+        [\fB\-\-change\-leading\-char\fR] [\fB\-\-remove\-leading\-char\fR]
+        [\fB\-\-reverse\-bytes=\fR\fInum\fR]
+        [\fB\-\-srec\-len=\fR\fIival\fR] [\fB\-\-srec\-forceS3\fR]
+        [\fB\-\-redefine\-sym\fR \fIold\fR=\fInew\fR]
+        [\fB\-\-redefine\-syms=\fR\fIfilename\fR]
+        [\fB\-\-weaken\fR]
+        [\fB\-\-keep\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-strip\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-localize\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-weaken\-symbols=\fR\fIfilename\fR]
+        [\fB\-\-add\-symbol\fR \fIname\fR=[\fIsection\fR:]\fIvalue\fR[,\fIflags\fR]]
+        [\fB\-\-alt\-machine\-code=\fR\fIindex\fR]
+        [\fB\-\-prefix\-symbols=\fR\fIstring\fR]
+        [\fB\-\-prefix\-sections=\fR\fIstring\fR]
+        [\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR]
+        [\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR]
+        [\fB\-\-only\-keep\-debug\fR]
+        [\fB\-\-strip\-dwo\fR]
+        [\fB\-\-extract\-dwo\fR]
+        [\fB\-\-extract\-symbol\fR]
+        [\fB\-\-writable\-text\fR]
+        [\fB\-\-readonly\-text\fR]
+        [\fB\-\-pure\fR]
+        [\fB\-\-impure\fR]
+        [\fB\-\-file\-alignment=\fR\fInum\fR]
+        [\fB\-\-heap=\fR\fIsize\fR]
+        [\fB\-\-image\-base=\fR\fIaddress\fR]
+        [\fB\-\-section\-alignment=\fR\fInum\fR]
+        [\fB\-\-stack=\fR\fIsize\fR]
+        [\fB\-\-subsystem=\fR\fIwhich\fR:\fImajor\fR.\fIminor\fR]
+        [\fB\-\-compress\-debug\-sections\fR]
+        [\fB\-\-decompress\-debug\-sections\fR]
+        [\fB\-\-elf\-stt\-common=\fR\fIval\fR]
+        [\fB\-\-merge\-notes\fR]
+        [\fB\-\-no\-merge\-notes\fR]
+        [\fB\-\-verilog\-data\-width=\fR\fIval\fR]
+        [\fB\-v\fR|\fB\-\-verbose\fR]
+        [\fB\-V\fR|\fB\-\-version\fR]
+        [\fB\-\-help\fR] [\fB\-\-info\fR]
+        \fIinfile\fR [\fIoutfile\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \s-1GNU\s0 \fBobjcopy\fR utility copies the contents of an object
+file to another.  \fBobjcopy\fR uses the \s-1GNU BFD\s0 Library to
+read and write the object files.  It can write the destination object
+file in a format different from that of the source object file.  The
+exact behavior of \fBobjcopy\fR is controlled by command-line options.
+Note that \fBobjcopy\fR should be able to copy a fully linked file
+between any two formats. However, copying a relocatable object file
+between any two formats may not work as expected.
+.PP
+\&\fBobjcopy\fR creates temporary files to do its translations and
+deletes them afterward.  \fBobjcopy\fR uses \s-1BFD\s0 to do all its
+translation work; it has access to all the formats described in \s-1BFD\s0
+and thus is able to recognize most formats without being told
+explicitly.
+.PP
+\&\fBobjcopy\fR can be used to generate S\-records by using an output
+target of \fBsrec\fR (e.g., use \fB\-O srec\fR).
+.PP
+\&\fBobjcopy\fR can be used to generate a raw binary file by using an
+output target of \fBbinary\fR (e.g., use \fB\-O binary\fR).  When
+\&\fBobjcopy\fR generates a raw binary file, it will essentially produce
+a memory dump of the contents of the input object file.  All symbols and
+relocation information will be discarded.  The memory dump will start at
+the load address of the lowest section copied into the output file.
+.PP
+When generating an S\-record or a raw binary file, it may be helpful to
+use \fB\-S\fR to remove sections containing debugging information.  In
+some cases \fB\-R\fR will be useful to remove sections which contain
+information that is not needed by the binary file.
+.PP
+Note\-\-\-\fBobjcopy\fR is not able to change the endianness of its input
+files.  If the input format has an endianness (some formats do not),
+\&\fBobjcopy\fR can only copy the inputs into file formats that have the
+same endianness or which have no endianness (e.g., \fBsrec\fR).
+(However, see the \fB\-\-reverse\-bytes\fR option.)
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fIinfile\fR" 4
+.IX Item "infile"
+.PD 0
+.IP "\fIoutfile\fR" 4
+.IX Item "outfile"
+.PD
+The input and output files, respectively.
+If you do not specify \fIoutfile\fR, \fBobjcopy\fR creates a
+temporary file and destructively renames the result with
+the name of \fIinfile\fR.
+.IP "\fB\-I\fR \fIbfdname\fR" 4
+.IX Item "-I bfdname"
+.PD 0
+.IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4
+.IX Item "--input-target=bfdname"
+.PD
+Consider the source file's object format to be \fIbfdname\fR, rather than
+attempting to deduce it.
+.IP "\fB\-O\fR \fIbfdname\fR" 4
+.IX Item "-O bfdname"
+.PD 0
+.IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4
+.IX Item "--output-target=bfdname"
+.PD
+Write the output file using the object format \fIbfdname\fR.
+.IP "\fB\-F\fR \fIbfdname\fR" 4
+.IX Item "-F bfdname"
+.PD 0
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+.PD
+Use \fIbfdname\fR as the object format for both the input and the output
+file; i.e., simply transfer data from source to destination with no
+translation.
+.IP "\fB\-B\fR \fIbfdarch\fR" 4
+.IX Item "-B bfdarch"
+.PD 0
+.IP "\fB\-\-binary\-architecture=\fR\fIbfdarch\fR" 4
+.IX Item "--binary-architecture=bfdarch"
+.PD
+Useful when transforming a architecture-less input file into an object file.
+In this case the output architecture can be set to \fIbfdarch\fR.  This
+option will be ignored if the input file has a known \fIbfdarch\fR.  You
+can access this binary data inside a program by referencing the special
+symbols that are created by the conversion process.  These symbols are
+called _binary_\fIobjfile\fR_start, _binary_\fIobjfile\fR_end and
+_binary_\fIobjfile\fR_size.  e.g. you can transform a picture file into
+an object file and then access it in your code using these symbols.
+.IP "\fB\-j\fR \fIsectionpattern\fR" 4
+.IX Item "-j sectionpattern"
+.PD 0
+.IP "\fB\-\-only\-section=\fR\fIsectionpattern\fR" 4
+.IX Item "--only-section=sectionpattern"
+.PD
+Copy only the indicated sections from the input file to the output file.
+This option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.  Wildcard
+characters are accepted in \fIsectionpattern\fR.
+.Sp
+If the first character of \fIsectionpattern\fR is the exclamation
+point (!) then matching sections will not be copied, even if earlier
+use of \fB\-\-only\-section\fR on the same command line would
+otherwise copy it.  For example:
+.Sp
+.Vb 1
+\&          \-\-only\-section=.text.* \-\-only\-section=!.text.foo
+.Ve
+.Sp
+will copy all sectinos matching '.text.*' but not the section
+\&'.text.foo'.
+.IP "\fB\-R\fR \fIsectionpattern\fR" 4
+.IX Item "-R sectionpattern"
+.PD 0
+.IP "\fB\-\-remove\-section=\fR\fIsectionpattern\fR" 4
+.IX Item "--remove-section=sectionpattern"
+.PD
+Remove any section matching \fIsectionpattern\fR from the output file.
+This option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.  Wildcard
+characters are accepted in \fIsectionpattern\fR.  Using both the
+\&\fB\-j\fR and \fB\-R\fR options together results in undefined
+behaviour.
+.Sp
+If the first character of \fIsectionpattern\fR is the exclamation
+point (!) then matching sections will not be removed even if an
+earlier use of \fB\-\-remove\-section\fR on the same command line
+would otherwise remove it.  For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-section=.text.* \-\-remove\-section=!.text.foo
+.Ve
+.Sp
+will remove all sections matching the pattern '.text.*', but will not
+remove the section '.text.foo'.
+.IP "\fB\-\-keep\-section=\fR\fIsectionpattern\fR" 4
+.IX Item "--keep-section=sectionpattern"
+When removing sections from the output file, keep sections that match
+\&\fIsectionpattern\fR.
+.IP "\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR" 4
+.IX Item "--remove-relocations=sectionpattern"
+Remove non-dynamic relocations from the output file for any section
+matching \fIsectionpattern\fR.  This option may be given more than
+once.  Note that using this option inappropriately may make the output
+file unusable, and attempting to remove a dynamic relocation section
+such as \fB.rela.plt\fR from an executable or shared library with
+\&\fB\-\-remove\-relocations=.plt\fR will not work.  Wildcard characters
+are accepted in \fIsectionpattern\fR.
+For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-relocations=.text.*
+.Ve
+.Sp
+will remove the relocations for all sections matching the pattern
+\&'.text.*'.
+.Sp
+If the first character of \fIsectionpattern\fR is the exclamation
+point (!) then matching sections will not have their relocation
+removed even if an earlier use of \fB\-\-remove\-relocations\fR on the
+same command line would otherwise cause the relocations to be removed.
+For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-relocations=.text.* \-\-remove\-relocations=!.text.foo
+.Ve
+.Sp
+will remove all relocations for sections matching the pattern
+\&'.text.*', but will not remove relocations for the section
+\&'.text.foo'.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-strip\-all\fR" 4
+.IX Item "--strip-all"
+.PD
+Do not copy relocation and symbol information from the source file.
+Also deletes debug sections.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-\-strip\-debug\fR" 4
+.IX Item "--strip-debug"
+.PD
+Do not copy debugging symbols or sections from the source file.
+.IP "\fB\-\-strip\-unneeded\fR" 4
+.IX Item "--strip-unneeded"
+Remove all symbols that are not needed for relocation processing in
+addition to debugging symbols and sections stripped by
+\&\fB\-\-strip\-debug\fR.
+.IP "\fB\-K\fR \fIsymbolname\fR" 4
+.IX Item "-K symbolname"
+.PD 0
+.IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--keep-symbol=symbolname"
+.PD
+When stripping symbols, keep symbol \fIsymbolname\fR even if it would
+normally be stripped.  This option may be given more than once.
+.IP "\fB\-N\fR \fIsymbolname\fR" 4
+.IX Item "-N symbolname"
+.PD 0
+.IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--strip-symbol=symbolname"
+.PD
+Do not copy symbol \fIsymbolname\fR from the source file.  This option
+may be given more than once.
+.IP "\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--strip-unneeded-symbol=symbolname"
+Do not copy symbol \fIsymbolname\fR from the source file unless it is needed
+by a relocation.  This option may be given more than once.
+.IP "\fB\-G\fR \fIsymbolname\fR" 4
+.IX Item "-G symbolname"
+.PD 0
+.IP "\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--keep-global-symbol=symbolname"
+.PD
+Keep only symbol \fIsymbolname\fR global.  Make all other symbols local
+to the file, so that they are not visible externally.  This option may
+be given more than once.  Note: this option cannot be used in
+conjunction with the \fB\-\-globalize\-symbol\fR or
+\&\fB\-\-globalize\-symbols\fR options.
+.IP "\fB\-\-localize\-hidden\fR" 4
+.IX Item "--localize-hidden"
+In an \s-1ELF\s0 object, mark all symbols that have hidden or internal visibility
+as local.  This option applies on top of symbol-specific localization options
+such as \fB\-L\fR.
+.IP "\fB\-L\fR \fIsymbolname\fR" 4
+.IX Item "-L symbolname"
+.PD 0
+.IP "\fB\-\-localize\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--localize-symbol=symbolname"
+.PD
+Convert a global or weak symbol called \fIsymbolname\fR into a local
+symbol, so that it is not visible externally.  This option may be
+given more than once.  Note \- unique symbols are not converted.
+.IP "\fB\-W\fR \fIsymbolname\fR" 4
+.IX Item "-W symbolname"
+.PD 0
+.IP "\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--weaken-symbol=symbolname"
+.PD
+Make symbol \fIsymbolname\fR weak. This option may be given more than once.
+.IP "\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--globalize-symbol=symbolname"
+Give symbol \fIsymbolname\fR global scoping so that it is visible
+outside of the file in which it is defined.  This option may be given
+more than once.  Note: this option cannot be used in conjunction with
+the \fB\-G\fR or \fB\-\-keep\-global\-symbol\fR options.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+.PD 0
+.IP "\fB\-\-wildcard\fR" 4
+.IX Item "--wildcard"
+.PD
+Permit regular expressions in \fIsymbolname\fRs used in other command
+line options.  The question mark (?), asterisk (*), backslash (\e) and
+square brackets ([]) operators can be used anywhere in the symbol
+name.  If the first character of the symbol name is the exclamation
+point (!) then the sense of the switch is reversed for that symbol.
+For example:
+.Sp
+.Vb 1
+\&          \-w \-W !foo \-W fo*
+.Ve
+.Sp
+would cause objcopy to weaken all symbols that start with \*(L"fo\*(R"
+except for the symbol \*(L"foo\*(R".
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.IP "\fB\-\-discard\-all\fR" 4
+.IX Item "--discard-all"
+.PD
+Do not copy non-global symbols from the source file.
+.IP "\fB\-X\fR" 4
+.IX Item "-X"
+.PD 0
+.IP "\fB\-\-discard\-locals\fR" 4
+.IX Item "--discard-locals"
+.PD
+Do not copy compiler-generated local symbols.
+(These usually start with \fBL\fR or \fB.\fR.)
+.IP "\fB\-b\fR \fIbyte\fR" 4
+.IX Item "-b byte"
+.PD 0
+.IP "\fB\-\-byte=\fR\fIbyte\fR" 4
+.IX Item "--byte=byte"
+.PD
+If interleaving has been enabled via the \fB\-\-interleave\fR option
+then start the range of bytes to keep at the \fIbyte\fRth byte.
+\&\fIbyte\fR can be in the range from 0 to \fIbreadth\fR\-1, where
+\&\fIbreadth\fR is the value given by the \fB\-\-interleave\fR option.
+.IP "\fB\-i [\fR\fIbreadth\fR\fB]\fR" 4
+.IX Item "-i [breadth]"
+.PD 0
+.IP "\fB\-\-interleave[=\fR\fIbreadth\fR\fB]\fR" 4
+.IX Item "--interleave[=breadth]"
+.PD
+Only copy a range out of every \fIbreadth\fR bytes.  (Header data is
+not affected).  Select which byte in the range begins the copy with
+the \fB\-\-byte\fR option.  Select the width of the range with the
+\&\fB\-\-interleave\-width\fR option.
+.Sp
+This option is useful for creating files to program \s-1ROM.\s0  It is
+typically used with an \f(CW\*(C`srec\*(C'\fR output target.  Note that
+\&\fBobjcopy\fR will complain if you do not specify the
+\&\fB\-\-byte\fR option as well.
+.Sp
+The default interleave breadth is 4, so with \fB\-\-byte\fR set to 0,
+\&\fBobjcopy\fR would copy the first byte out of every four bytes
+from the input to the output.
+.IP "\fB\-\-interleave\-width=\fR\fIwidth\fR" 4
+.IX Item "--interleave-width=width"
+When used with the \fB\-\-interleave\fR option, copy \fIwidth\fR
+bytes at a time.  The start of the range of bytes to be copied is set
+by the \fB\-\-byte\fR option, and the extent of the range is set with
+the \fB\-\-interleave\fR option.
+.Sp
+The default value for this option is 1.  The value of \fIwidth\fR plus
+the \fIbyte\fR value set by the \fB\-\-byte\fR option must not exceed
+the interleave breadth set by the \fB\-\-interleave\fR option.
+.Sp
+This option can be used to create images for two 16\-bit flashes interleaved
+in a 32\-bit bus by passing \fB\-b 0 \-i 4 \-\-interleave\-width=2\fR
+and \fB\-b 2 \-i 4 \-\-interleave\-width=2\fR to two \fBobjcopy\fR
+commands.  If the input was '12345678' then the outputs would be
+\&'1256' and '3478' respectively.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-preserve\-dates\fR" 4
+.IX Item "--preserve-dates"
+.PD
+Set the access and modification dates of the output file to be the same
+as those of the input file.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.IP "\fB\-\-enable\-deterministic\-archives\fR" 4
+.IX Item "--enable-deterministic-archives"
+.PD
+Operate in \fIdeterministic\fR mode.  When copying archive members
+and writing the archive index, use zero for UIDs, GIDs, timestamps,
+and use consistent file modes for all files.
+.Sp
+If \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
+It can be disabled with the \fB\-U\fR option, below.
+.IP "\fB\-U\fR" 4
+.IX Item "-U"
+.PD 0
+.IP "\fB\-\-disable\-deterministic\-archives\fR" 4
+.IX Item "--disable-deterministic-archives"
+.PD
+Do \fInot\fR operate in \fIdeterministic\fR mode.  This is the
+inverse of the \fB\-D\fR option, above: when copying archive members
+and writing the archive index, use their actual \s-1UID, GID,\s0 timestamp,
+and file mode values.
+.Sp
+This is the default unless \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR.
+.IP "\fB\-\-debugging\fR" 4
+.IX Item "--debugging"
+Convert debugging information, if possible.  This is not the default
+because only certain debugging formats are supported, and the
+conversion process can be time consuming.
+.IP "\fB\-\-gap\-fill\fR \fIval\fR" 4
+.IX Item "--gap-fill val"
+Fill gaps between sections with \fIval\fR.  This operation applies to
+the \fIload address\fR (\s-1LMA\s0) of the sections.  It is done by increasing
+the size of the section with the lower address, and filling in the extra
+space created with \fIval\fR.
+.IP "\fB\-\-pad\-to\fR \fIaddress\fR" 4
+.IX Item "--pad-to address"
+Pad the output file up to the load address \fIaddress\fR.  This is
+done by increasing the size of the last section.  The extra space is
+filled in with the value specified by \fB\-\-gap\-fill\fR (default zero).
+.IP "\fB\-\-set\-start\fR \fIval\fR" 4
+.IX Item "--set-start val"
+Set the start address (also known as the entry address) of the new
+file to \fIval\fR.  Not all object file formats support setting the
+start address.
+.IP "\fB\-\-change\-start\fR \fIincr\fR" 4
+.IX Item "--change-start incr"
+.PD 0
+.IP "\fB\-\-adjust\-start\fR \fIincr\fR" 4
+.IX Item "--adjust-start incr"
+.PD
+Change the start address (also known as the entry address) by adding
+\&\fIincr\fR.  Not all object file formats support setting the start
+address.
+.IP "\fB\-\-change\-addresses\fR \fIincr\fR" 4
+.IX Item "--change-addresses incr"
+.PD 0
+.IP "\fB\-\-adjust\-vma\fR \fIincr\fR" 4
+.IX Item "--adjust-vma incr"
+.PD
+Change the \s-1VMA\s0 and \s-1LMA\s0 addresses of all sections, as well as the start
+address, by adding \fIincr\fR.  Some object file formats do not permit
+section addresses to be changed arbitrarily.  Note that this does not
+relocate the sections; if the program expects sections to be loaded at a
+certain address, and this option is used to change the sections such
+that they are loaded at a different address, the program may fail.
+.IP "\fB\-\-change\-section\-address\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4
+.IX Item "--change-section-address sectionpattern{=,+,-}val"
+.PD 0
+.IP "\fB\-\-adjust\-section\-vma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4
+.IX Item "--adjust-section-vma sectionpattern{=,+,-}val"
+.PD
+Set or change both the \s-1VMA\s0 address and the \s-1LMA\s0 address of any section
+matching \fIsectionpattern\fR.  If \fB=\fR is used, the section
+address is set to \fIval\fR.  Otherwise, \fIval\fR is added to or
+subtracted from the section address.  See the comments under
+\&\fB\-\-change\-addresses\fR, above. If \fIsectionpattern\fR does not
+match any sections in the input file, a warning will be issued, unless
+\&\fB\-\-no\-change\-warnings\fR is used.
+.IP "\fB\-\-change\-section\-lma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4
+.IX Item "--change-section-lma sectionpattern{=,+,-}val"
+Set or change the \s-1LMA\s0 address of any sections matching
+\&\fIsectionpattern\fR.  The \s-1LMA\s0 address is the address where the
+section will be loaded into memory at program load time.  Normally
+this is the same as the \s-1VMA\s0 address, which is the address of the
+section at program run time, but on some systems, especially those
+where a program is held in \s-1ROM,\s0 the two can be different.  If \fB=\fR
+is used, the section address is set to \fIval\fR.  Otherwise,
+\&\fIval\fR is added to or subtracted from the section address.  See the
+comments under \fB\-\-change\-addresses\fR, above.  If
+\&\fIsectionpattern\fR does not match any sections in the input file, a
+warning will be issued, unless \fB\-\-no\-change\-warnings\fR is used.
+.IP "\fB\-\-change\-section\-vma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4
+.IX Item "--change-section-vma sectionpattern{=,+,-}val"
+Set or change the \s-1VMA\s0 address of any section matching
+\&\fIsectionpattern\fR.  The \s-1VMA\s0 address is the address where the
+section will be located once the program has started executing.
+Normally this is the same as the \s-1LMA\s0 address, which is the address
+where the section will be loaded into memory, but on some systems,
+especially those where a program is held in \s-1ROM,\s0 the two can be
+different.  If \fB=\fR is used, the section address is set to
+\&\fIval\fR.  Otherwise, \fIval\fR is added to or subtracted from the
+section address.  See the comments under \fB\-\-change\-addresses\fR,
+above.  If \fIsectionpattern\fR does not match any sections in the
+input file, a warning will be issued, unless
+\&\fB\-\-no\-change\-warnings\fR is used.
+.IP "\fB\-\-change\-warnings\fR" 4
+.IX Item "--change-warnings"
+.PD 0
+.IP "\fB\-\-adjust\-warnings\fR" 4
+.IX Item "--adjust-warnings"
+.PD
+If \fB\-\-change\-section\-address\fR or \fB\-\-change\-section\-lma\fR or
+\&\fB\-\-change\-section\-vma\fR is used, and the section pattern does not
+match any sections, issue a warning.  This is the default.
+.IP "\fB\-\-no\-change\-warnings\fR" 4
+.IX Item "--no-change-warnings"
+.PD 0
+.IP "\fB\-\-no\-adjust\-warnings\fR" 4
+.IX Item "--no-adjust-warnings"
+.PD
+Do not issue a warning if \fB\-\-change\-section\-address\fR or
+\&\fB\-\-adjust\-section\-lma\fR or \fB\-\-adjust\-section\-vma\fR is used, even
+if the section pattern does not match any sections.
+.IP "\fB\-\-set\-section\-flags\fR \fIsectionpattern\fR\fB=\fR\fIflags\fR" 4
+.IX Item "--set-section-flags sectionpattern=flags"
+Set the flags for any sections matching \fIsectionpattern\fR.  The
+\&\fIflags\fR argument is a comma separated string of flag names.  The
+recognized names are \fBalloc\fR, \fBcontents\fR, \fBload\fR,
+\&\fBnoload\fR, \fBreadonly\fR, \fBcode\fR, \fBdata\fR, \fBrom\fR,
+\&\fBexclude\fR, \fBshare\fR, and \fBdebug\fR.  You can set the
+\&\fBcontents\fR flag for a section which does not have contents, but it
+is not meaningful to clear the \fBcontents\fR flag of a section which
+does have contents\*(--just remove the section instead.  Not all flags are
+meaningful for all object file formats.  In particular the
+\&\fBshare\fR flag is only meaningful for \s-1COFF\s0 format files and not for
+\&\s-1ELF\s0 format files.
+.IP "\fB\-\-set\-section\-alignment\fR \fIsectionpattern\fR\fB=\fR\fIalign\fR" 4
+.IX Item "--set-section-alignment sectionpattern=align"
+Set the alignment for any sections matching \fIsectionpattern\fR.
+\&\fIalign\fR specifies the alignment in bytes and must be a power of
+two, i.e. 1, 2, 4, 8....
+.IP "\fB\-\-add\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4
+.IX Item "--add-section sectionname=filename"
+Add a new section named \fIsectionname\fR while copying the file.  The
+contents of the new section are taken from the file \fIfilename\fR.  The
+size of the section will be the size of the file.  This option only
+works on file formats which can support sections with arbitrary names.
+Note \- it may be necessary to use the \fB\-\-set\-section\-flags\fR
+option to set the attributes of the newly created section.
+.IP "\fB\-\-dump\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4
+.IX Item "--dump-section sectionname=filename"
+Place the contents of section named \fIsectionname\fR into the file
+\&\fIfilename\fR, overwriting any contents that may have been there
+previously.  This option is the inverse of \fB\-\-add\-section\fR.
+This option is similar to the \fB\-\-only\-section\fR option except
+that it does not create a formatted file, it just dumps the contents
+as raw binary data, without applying any relocations.  The option can
+be specified more than once.
+.IP "\fB\-\-update\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4
+.IX Item "--update-section sectionname=filename"
+Replace the existing contents of a section named \fIsectionname\fR
+with the contents of file \fIfilename\fR.  The size of the section
+will be adjusted to the size of the file.  The section flags for
+\&\fIsectionname\fR will be unchanged.  For \s-1ELF\s0 format files the section
+to segment mapping will also remain unchanged, something which is not
+possible using \fB\-\-remove\-section\fR followed by
+\&\fB\-\-add\-section\fR.  The option can be specified more than once.
+.Sp
+Note \- it is possible to use \fB\-\-rename\-section\fR and
+\&\fB\-\-update\-section\fR to both update and rename a section from one
+command line.  In this case, pass the original section name to
+\&\fB\-\-update\-section\fR, and the original and new section names to
+\&\fB\-\-rename\-section\fR.
+.IP "\fB\-\-add\-symbol\fR \fIname\fR\fB=[\fR\fIsection\fR\fB:]\fR\fIvalue\fR\fB[,\fR\fIflags\fR\fB]\fR" 4
+.IX Item "--add-symbol name=[section:]value[,flags]"
+Add a new symbol named \fIname\fR while copying the file.  This option may be
+specified multiple times.  If the \fIsection\fR is given, the symbol will be
+associated with and relative to that section, otherwise it will be an \s-1ABS\s0
+symbol.  Specifying an undefined section will result in a fatal error.  There
+is no check for the value, it will be taken as specified.  Symbol flags can
+be specified and not all flags will be meaningful for all object file
+formats.  By default, the symbol will be global.  The special flag
+\&'before=\fIothersym\fR' will insert the new symbol in front of the specified
+\&\fIothersym\fR, otherwise the symbol(s) will be added at the end of the
+symbol table in the order they appear.
+.IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR\fB[,\fR\fIflags\fR\fB]\fR" 4
+.IX Item "--rename-section oldname=newname[,flags]"
+Rename a section from \fIoldname\fR to \fInewname\fR, optionally
+changing the section's flags to \fIflags\fR in the process.  This has
+the advantage over using a linker script to perform the rename in that
+the output stays as an object file and does not become a linked
+executable.  This option accepts the same set of flags as the
+\&\fB\-\-sect\-section\-flags\fR option.
+.Sp
+This option is particularly helpful when the input format is binary,
+since this will always create a section called .data.  If for example,
+you wanted instead to create a section called .rodata containing binary
+data you could use the following command line to achieve it:
+.Sp
+.Vb 3
+\&          objcopy \-I binary \-O <output_format> \-B <architecture> \e
+\&           \-\-rename\-section .data=.rodata,alloc,load,readonly,data,contents \e
+\&           <input_binary_file> <output_object_file>
+.Ve
+.IP "\fB\-\-long\-section\-names {enable,disable,keep}\fR" 4
+.IX Item "--long-section-names {enable,disable,keep}"
+Controls the handling of long section names when processing \f(CW\*(C`COFF\*(C'\fR
+and \f(CW\*(C`PE\-COFF\*(C'\fR object formats.  The default behaviour, \fBkeep\fR,
+is to preserve long section names if any are present in the input file.
+The \fBenable\fR and \fBdisable\fR options forcibly enable or disable
+the use of long section names in the output object; when \fBdisable\fR
+is in effect, any long section names in the input object will be truncated.
+The \fBenable\fR option will only emit long section names if any are
+present in the inputs; this is mostly the same as \fBkeep\fR, but it
+is left undefined whether the \fBenable\fR option might force the
+creation of an empty string table in the output file.
+.IP "\fB\-\-change\-leading\-char\fR" 4
+.IX Item "--change-leading-char"
+Some object file formats use special characters at the start of
+symbols.  The most common such character is underscore, which compilers
+often add before every symbol.  This option tells \fBobjcopy\fR to
+change the leading character of every symbol when it converts between
+object file formats.  If the object file formats use the same leading
+character, this option has no effect.  Otherwise, it will add a
+character, or remove a character, or change a character, as
+appropriate.
+.IP "\fB\-\-remove\-leading\-char\fR" 4
+.IX Item "--remove-leading-char"
+If the first character of a global symbol is a special symbol leading
+character used by the object file format, remove the character.  The
+most common symbol leading character is underscore.  This option will
+remove a leading underscore from all global symbols.  This can be useful
+if you want to link together objects of different file formats with
+different conventions for symbol names.  This is different from
+\&\fB\-\-change\-leading\-char\fR because it always changes the symbol name
+when appropriate, regardless of the object file format of the output
+file.
+.IP "\fB\-\-reverse\-bytes=\fR\fInum\fR" 4
+.IX Item "--reverse-bytes=num"
+Reverse the bytes in a section with output contents.  A section length must
+be evenly divisible by the value given in order for the swap to be able to
+take place. Reversing takes place before the interleaving is performed.
+.Sp
+This option is used typically in generating \s-1ROM\s0 images for problematic
+target systems.  For example, on some target boards, the 32\-bit words
+fetched from 8\-bit ROMs are re-assembled in little-endian byte order
+regardless of the \s-1CPU\s0 byte order.  Depending on the programming model, the
+endianness of the \s-1ROM\s0 may need to be modified.
+.Sp
+Consider a simple file with a section containing the following eight
+bytes:  \f(CW12345678\fR.
+.Sp
+Using \fB\-\-reverse\-bytes=2\fR for the above example, the bytes in the
+output file would be ordered \f(CW21436587\fR.
+.Sp
+Using \fB\-\-reverse\-bytes=4\fR for the above example, the bytes in the
+output file would be ordered \f(CW43218765\fR.
+.Sp
+By using \fB\-\-reverse\-bytes=2\fR for the above example, followed by
+\&\fB\-\-reverse\-bytes=4\fR on the output file, the bytes in the second
+output file would be ordered \f(CW34127856\fR.
+.IP "\fB\-\-srec\-len=\fR\fIival\fR" 4
+.IX Item "--srec-len=ival"
+Meaningful only for srec output.  Set the maximum length of the Srecords
+being produced to \fIival\fR.  This length covers both address, data and
+crc fields.
+.IP "\fB\-\-srec\-forceS3\fR" 4
+.IX Item "--srec-forceS3"
+Meaningful only for srec output.  Avoid generation of S1/S2 records,
+creating S3\-only record format.
+.IP "\fB\-\-redefine\-sym\fR \fIold\fR\fB=\fR\fInew\fR" 4
+.IX Item "--redefine-sym old=new"
+Change the name of a symbol \fIold\fR, to \fInew\fR.  This can be useful
+when one is trying link two things together for which you have no
+source, and there are name collisions.
+.IP "\fB\-\-redefine\-syms=\fR\fIfilename\fR" 4
+.IX Item "--redefine-syms=filename"
+Apply \fB\-\-redefine\-sym\fR to each symbol pair "\fIold\fR \fInew\fR"
+listed in the file \fIfilename\fR.  \fIfilename\fR is simply a flat file,
+with one symbol pair per line.  Line comments may be introduced by the hash
+character.  This option may be given more than once.
+.IP "\fB\-\-weaken\fR" 4
+.IX Item "--weaken"
+Change all global symbols in the file to be weak.  This can be useful
+when building an object which will be linked against other objects using
+the \fB\-R\fR option to the linker.  This option is only effective when
+using an object file format which supports weak symbols.
+.IP "\fB\-\-keep\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--keep-symbols=filename"
+Apply \fB\-\-keep\-symbol\fR option to each symbol listed in the file
+\&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
+name per line.  Line comments may be introduced by the hash character.
+This option may be given more than once.
+.IP "\fB\-\-strip\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--strip-symbols=filename"
+Apply \fB\-\-strip\-symbol\fR option to each symbol listed in the file
+\&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
+name per line.  Line comments may be introduced by the hash character.
+This option may be given more than once.
+.IP "\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--strip-unneeded-symbols=filename"
+Apply \fB\-\-strip\-unneeded\-symbol\fR option to each symbol listed in
+the file \fIfilename\fR.  \fIfilename\fR is simply a flat file, with one
+symbol name per line.  Line comments may be introduced by the hash
+character.  This option may be given more than once.
+.IP "\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--keep-global-symbols=filename"
+Apply \fB\-\-keep\-global\-symbol\fR option to each symbol listed in the
+file \fIfilename\fR.  \fIfilename\fR is simply a flat file, with one
+symbol name per line.  Line comments may be introduced by the hash
+character.  This option may be given more than once.
+.IP "\fB\-\-localize\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--localize-symbols=filename"
+Apply \fB\-\-localize\-symbol\fR option to each symbol listed in the file
+\&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
+name per line.  Line comments may be introduced by the hash character.
+This option may be given more than once.
+.IP "\fB\-\-globalize\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--globalize-symbols=filename"
+Apply \fB\-\-globalize\-symbol\fR option to each symbol listed in the file
+\&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
+name per line.  Line comments may be introduced by the hash character.
+This option may be given more than once.  Note: this option cannot be
+used in conjunction with the \fB\-G\fR or \fB\-\-keep\-global\-symbol\fR
+options.
+.IP "\fB\-\-weaken\-symbols=\fR\fIfilename\fR" 4
+.IX Item "--weaken-symbols=filename"
+Apply \fB\-\-weaken\-symbol\fR option to each symbol listed in the file
+\&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
+name per line.  Line comments may be introduced by the hash character.
+This option may be given more than once.
+.IP "\fB\-\-alt\-machine\-code=\fR\fIindex\fR" 4
+.IX Item "--alt-machine-code=index"
+If the output architecture has alternate machine codes, use the
+\&\fIindex\fRth code instead of the default one.  This is useful in case
+a machine is assigned an official code and the tool-chain adopts the
+new code, but other applications still depend on the original code
+being used.  For \s-1ELF\s0 based architectures if the \fIindex\fR
+alternative does not exist then the value is treated as an absolute
+number to be stored in the e_machine field of the \s-1ELF\s0 header.
+.IP "\fB\-\-writable\-text\fR" 4
+.IX Item "--writable-text"
+Mark the output text as writable.  This option isn't meaningful for all
+object file formats.
+.IP "\fB\-\-readonly\-text\fR" 4
+.IX Item "--readonly-text"
+Make the output text write protected.  This option isn't meaningful for all
+object file formats.
+.IP "\fB\-\-pure\fR" 4
+.IX Item "--pure"
+Mark the output file as demand paged.  This option isn't meaningful for all
+object file formats.
+.IP "\fB\-\-impure\fR" 4
+.IX Item "--impure"
+Mark the output file as impure.  This option isn't meaningful for all
+object file formats.
+.IP "\fB\-\-prefix\-symbols=\fR\fIstring\fR" 4
+.IX Item "--prefix-symbols=string"
+Prefix all symbols in the output file with \fIstring\fR.
+.IP "\fB\-\-prefix\-sections=\fR\fIstring\fR" 4
+.IX Item "--prefix-sections=string"
+Prefix all section names in the output file with \fIstring\fR.
+.IP "\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR" 4
+.IX Item "--prefix-alloc-sections=string"
+Prefix all the names of all allocated sections in the output file with
+\&\fIstring\fR.
+.IP "\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR" 4
+.IX Item "--add-gnu-debuglink=path-to-file"
+Creates a .gnu_debuglink section which contains a reference to
+\&\fIpath-to-file\fR and adds it to the output file.  Note: the file at
+\&\fIpath-to-file\fR must exist.  Part of the process of adding the
+\&.gnu_debuglink section involves embedding a checksum of the contents
+of the debug info file into the section.
+.Sp
+If the debug info file is built in one location but it is going to be
+installed at a later time into a different location then do not use
+the path to the installed location.  The \fB\-\-add\-gnu\-debuglink\fR
+option will fail because the installed file does not exist yet.
+Instead put the debug info file in the current directory and use the
+\&\fB\-\-add\-gnu\-debuglink\fR option without any directory components,
+like this:
+.Sp
+.Vb 1
+\&         objcopy \-\-add\-gnu\-debuglink=foo.debug
+.Ve
+.Sp
+At debug time the debugger will attempt to look for the separate debug
+info file in a set of known locations.  The exact set of these
+locations varies depending upon the distribution being used, but it
+typically includes:
+.RS 4
+.ie n .IP """* The same directory as the executable.""" 4
+.el .IP "\f(CW* The same directory as the executable.\fR" 4
+.IX Item "* The same directory as the executable."
+.PD 0
+.ie n .IP """* A sub\-directory of the directory containing the executable""" 4
+.el .IP "\f(CW* A sub\-directory of the directory containing the executable\fR" 4
+.IX Item "* A sub-directory of the directory containing the executable"
+.PD
+called .debug
+.ie n .IP """* A global debug directory such as /usr/lib/debug.""" 4
+.el .IP "\f(CW* A global debug directory such as /usr/lib/debug.\fR" 4
+.IX Item "* A global debug directory such as /usr/lib/debug."
+.RE
+.RS 4
+.Sp
+As long as the debug info file has been installed into one of these
+locations before the debugger is run everything should work
+correctly.
+.RE
+.IP "\fB\-\-keep\-section\-symbils\fR" 4
+.IX Item "--keep-section-symbils"
+When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
+\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying section names,
+which would otherwise get stripped.
+.IP "\fB\-\-keep\-file\-symbols\fR" 4
+.IX Item "--keep-file-symbols"
+When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
+\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names,
+which would otherwise get stripped.
+.IP "\fB\-\-only\-keep\-debug\fR" 4
+.IX Item "--only-keep-debug"
+Strip a file, removing contents of any sections that would not be
+stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections
+intact.  In \s-1ELF\s0 files, this preserves all note sections in the output.
+.Sp
+Note \- the section headers of the stripped sections are preserved,
+including their sizes, but the contents of the section are discarded.
+The section headers are preserved so that other tools can match up the
+debuginfo file with the real executable, even if that executable has
+been relocated to a different address space.
+.Sp
+The intention is that this option will be used in conjunction with
+\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable.  One a
+stripped binary which will occupy less space in \s-1RAM\s0 and in a
+distribution and the second a debugging information file which is only
+needed if debugging abilities are required.  The suggested procedure
+to create these files is as follows:
+.RS 4
+.IP "1.<Link the executable as normal.  Assuming that it is called>" 4
+.IX Item "1.<Link the executable as normal. Assuming that it is called>"
+\&\f(CW\*(C`foo\*(C'\fR then...
+.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4
+.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>"
+create a file containing the debugging info.
+.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4
+.IX Item "1.<Run objcopy --strip-debug foo to create a>"
+stripped executable.
+.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4
+.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>"
+to add a link to the debugging info into the stripped executable.
+.RE
+.RS 4
+.Sp
+Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info
+file is arbitrary.  Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is
+optional.  You could instead do this:
+.IP "1.<Link the executable as normal.>" 4
+.IX Item "1.<Link the executable as normal.>"
+.PD 0
+.ie n .IP "1.<Copy ""foo"" to  ""foo.full"">" 4
+.el .IP "1.<Copy \f(CWfoo\fR to  \f(CWfoo.full\fR>" 4
+.IX Item "1.<Copy foo to foo.full>"
+.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"">" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR>" 4
+.IX Item "1.<Run objcopy --strip-debug foo>"
+.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4
+.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>"
+.RE
+.RS 4
+.PD
+.Sp
+i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the
+full executable.  It does not have to be a file created by the
+\&\fB\-\-only\-keep\-debug\fR switch.
+.Sp
+Note\-\-\-this switch is only intended for use on fully linked files.  It
+does not make sense to use it on object files where the debugging
+information may be incomplete.  Besides the gnu_debuglink feature
+currently only supports the presence of one filename containing
+debugging information, not multiple filenames on a one-per-object-file
+basis.
+.RE
+.IP "\fB\-\-strip\-dwo\fR" 4
+.IX Item "--strip-dwo"
+Remove the contents of all \s-1DWARF\s0 .dwo sections, leaving the
+remaining debugging sections and all symbols intact.
+This option is intended for use by the compiler as part of
+the \fB\-gsplit\-dwarf\fR option, which splits debug information
+between the .o file and a separate .dwo file.  The compiler
+generates all debug information in the same file, then uses
+the \fB\-\-extract\-dwo\fR option to copy the .dwo sections to
+the .dwo file, then the \fB\-\-strip\-dwo\fR option to remove
+those sections from the original .o file.
+.IP "\fB\-\-extract\-dwo\fR" 4
+.IX Item "--extract-dwo"
+Extract the contents of all \s-1DWARF\s0 .dwo sections.  See the
+\&\fB\-\-strip\-dwo\fR option for more information.
+.IP "\fB\-\-file\-alignment\fR \fInum\fR" 4
+.IX Item "--file-alignment num"
+Specify the file alignment.  Sections in the file will always begin at
+file offsets which are multiples of this number.  This defaults to
+512.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-heap\fR \fIreserve\fR" 4
+.IX Item "--heap reserve"
+.PD 0
+.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
+.IX Item "--heap reserve,commit"
+.PD
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as heap for this program.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
+.IX Item "--image-base value"
+Use \fIvalue\fR as the base address of your program or dll.  This is
+the lowest memory location that will be used when your program or dll
+is loaded.  To reduce the need to relocate and improve performance of
+your dlls, each should have a unique base address and not overlap any
+other dlls.  The default is 0x400000 for executables, and 0x10000000
+for dlls.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-section\-alignment\fR \fInum\fR" 4
+.IX Item "--section-alignment num"
+Sets the section alignment field in the \s-1PE\s0 header.  Sections in memory
+will always begin at addresses which are a multiple of this number.
+Defaults to 0x1000.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-stack\fR \fIreserve\fR" 4
+.IX Item "--stack reserve"
+.PD 0
+.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
+.IX Item "--stack reserve,commit"
+.PD
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as stack for this program.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4
+.IX Item "--subsystem which"
+.PD 0
+.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4
+.IX Item "--subsystem which:major"
+.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4
+.IX Item "--subsystem which:major.minor"
+.PD
+Specifies the subsystem under which your program will execute.  The
+legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
+\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, \f(CW\*(C`efi\-app\*(C'\fR, \f(CW\*(C`efi\-bsd\*(C'\fR,
+\&\f(CW\*(C`efi\-rtd\*(C'\fR, \f(CW\*(C`sal\-rtd\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR.  You may optionally set
+the subsystem version also.  Numeric values are also accepted for
+\&\fIwhich\fR.
+[This option is specific to \s-1PE\s0 targets.]
+.IP "\fB\-\-extract\-symbol\fR" 4
+.IX Item "--extract-symbol"
+Keep the file's section flags and symbols but remove all section data.
+Specifically, the option:
+.RS 4
+.IP "*<removes the contents of all sections;>" 4
+.IX Item "*<removes the contents of all sections;>"
+.PD 0
+.IP "*<sets the size of every section to zero; and>" 4
+.IX Item "*<sets the size of every section to zero; and>"
+.IP "*<sets the file's start address to zero.>" 4
+.IX Item "*<sets the file's start address to zero.>"
+.RE
+.RS 4
+.PD
+.Sp
+This option is used to build a \fI.sym\fR file for a VxWorks kernel.
+It can also be a useful way of reducing the size of a \fB\-\-just\-symbols\fR
+linker input file.
+.RE
+.IP "\fB\-\-compress\-debug\-sections\fR" 4
+.IX Item "--compress-debug-sections"
+Compress \s-1DWARF\s0 debug sections using zlib with \s-1SHF_COMPRESSED\s0 from the
+\&\s-1ELF ABI.\s0  Note \- if compression would actually make a section
+\&\fIlarger\fR, then it is not compressed.
+.IP "\fB\-\-compress\-debug\-sections=none\fR" 4
+.IX Item "--compress-debug-sections=none"
+.PD 0
+.IP "\fB\-\-compress\-debug\-sections=zlib\fR" 4
+.IX Item "--compress-debug-sections=zlib"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gnu\fR" 4
+.IX Item "--compress-debug-sections=zlib-gnu"
+.IP "\fB\-\-compress\-debug\-sections=zlib\-gabi\fR" 4
+.IX Item "--compress-debug-sections=zlib-gabi"
+.IP "\fB\-\-compress\-debug\-sections=zstd\fR" 4
+.IX Item "--compress-debug-sections=zstd"
+.PD
+For \s-1ELF\s0 files, these options control how \s-1DWARF\s0 debug sections are
+compressed.  \fB\-\-compress\-debug\-sections=none\fR is equivalent
+to \fB\-\-decompress\-debug\-sections\fR.
+\&\fB\-\-compress\-debug\-sections=zlib\fR and
+\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR are equivalent to
+\&\fB\-\-compress\-debug\-sections\fR.
+\&\fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses \s-1DWARF\s0 debug sections
+using the obsoleted zlib-gnu format.  The debug sections are renamed to begin
+with \fB.zdebug\fR.
+\&\fB\-\-compress\-debug\-sections=zstd\fR compresses \s-1DWARF\s0 debug
+sections using zstd.  Note \- if compression would actually make a section
+\&\fIlarger\fR, then it is not compressed nor renamed.
+.IP "\fB\-\-decompress\-debug\-sections\fR" 4
+.IX Item "--decompress-debug-sections"
+Decompress \s-1DWARF\s0 debug sections.  For a \fB.zdebug\fR section, the original
+name is restored.
+.IP "\fB\-\-elf\-stt\-common=yes\fR" 4
+.IX Item "--elf-stt-common=yes"
+.PD 0
+.IP "\fB\-\-elf\-stt\-common=no\fR" 4
+.IX Item "--elf-stt-common=no"
+.PD
+For \s-1ELF\s0 files, these options control whether common symbols should be
+converted to the \f(CW\*(C`STT_COMMON\*(C'\fR or \f(CW\*(C`STT_OBJECT\*(C'\fR type.
+\&\fB\-\-elf\-stt\-common=yes\fR converts common symbol type to
+\&\f(CW\*(C`STT_COMMON\*(C'\fR. \fB\-\-elf\-stt\-common=no\fR converts common symbol
+type to \f(CW\*(C`STT_OBJECT\*(C'\fR.
+.IP "\fB\-\-merge\-notes\fR" 4
+.IX Item "--merge-notes"
+.PD 0
+.IP "\fB\-\-no\-merge\-notes\fR" 4
+.IX Item "--no-merge-notes"
+.PD
+For \s-1ELF\s0 files, attempt (or do not attempt) to reduce the size of any
+\&\s-1SHT_NOTE\s0 type sections by removing duplicate notes.
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Show the version number of \fBobjcopy\fR.
+.IP "\fB\-\-verilog\-data\-width=\fR\fIbytes\fR" 4
+.IX Item "--verilog-data-width=bytes"
+For Verilog output, this options controls the number of bytes
+converted for each output data element.  The input target controls the
+endianness of the conversion.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-verbose\fR" 4
+.IX Item "--verbose"
+.PD
+Verbose output: list all object files modified.  In the case of
+archives, \fBobjcopy \-V\fR lists all members of the archive.
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Show a summary of the options to \fBobjcopy\fR.
+.IP "\fB\-\-info\fR" 4
+.IX Item "--info"
+Display a list showing all architectures and object formats available.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBld\fR\|(1), \fBobjdump\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/objdump.1 b/upstream/mageia-cauldron/man1/objdump.1
new file mode 100644
index 00000000..bd133124
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/objdump.1
@@ -0,0 +1,1458 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "OBJDUMP 1"
+.TH OBJDUMP 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+objdump \- display information from object files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+objdump [\fB\-a\fR|\fB\-\-archive\-headers\fR]
+        [\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR]
+        [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR] ]
+        [\fB\-d\fR|\fB\-\-disassemble\fR[=\fIsymbol\fR]]
+        [\fB\-D\fR|\fB\-\-disassemble\-all\fR]
+        [\fB\-z\fR|\fB\-\-disassemble\-zeroes\fR]
+        [\fB\-EB\fR|\fB\-EL\fR|\fB\-\-endian=\fR{big | little }]
+        [\fB\-f\fR|\fB\-\-file\-headers\fR]
+        [\fB\-F\fR|\fB\-\-file\-offsets\fR]
+        [\fB\-\-file\-start\-context\fR]
+        [\fB\-g\fR|\fB\-\-debugging\fR]
+        [\fB\-e\fR|\fB\-\-debugging\-tags\fR]
+        [\fB\-h\fR|\fB\-\-section\-headers\fR|\fB\-\-headers\fR]
+        [\fB\-i\fR|\fB\-\-info\fR]
+        [\fB\-j\fR \fIsection\fR|\fB\-\-section=\fR\fIsection\fR]
+        [\fB\-l\fR|\fB\-\-line\-numbers\fR]
+        [\fB\-S\fR|\fB\-\-source\fR]
+        [\fB\-\-source\-comment\fR[=\fItext\fR]]
+        [\fB\-m\fR \fImachine\fR|\fB\-\-architecture=\fR\fImachine\fR]
+        [\fB\-M\fR \fIoptions\fR|\fB\-\-disassembler\-options=\fR\fIoptions\fR]
+        [\fB\-p\fR|\fB\-\-private\-headers\fR]
+        [\fB\-P\fR \fIoptions\fR|\fB\-\-private=\fR\fIoptions\fR]
+        [\fB\-r\fR|\fB\-\-reloc\fR]
+        [\fB\-R\fR|\fB\-\-dynamic\-reloc\fR]
+        [\fB\-s\fR|\fB\-\-full\-contents\fR]
+        [\fB\-W[lLiaprmfFsoORtUuTgAck]\fR|
+         \fB\-\-dwarf\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
+        [\fB\-WK\fR|\fB\-\-dwarf=follow\-links\fR]
+        [\fB\-WN\fR|\fB\-\-dwarf=no\-follow\-links\fR]
+        [\fB\-wD\fR|\fB\-\-dwarf=use\-debuginfod\fR]
+        [\fB\-wE\fR|\fB\-\-dwarf=do\-not\-use\-debuginfod\fR]
+        [\fB\-L\fR|\fB\-\-process\-links\fR]
+        [\fB\-\-ctf=\fR\fIsection\fR]
+        [\fB\-\-sframe=\fR\fIsection\fR]
+        [\fB\-G\fR|\fB\-\-stabs\fR]
+        [\fB\-t\fR|\fB\-\-syms\fR]
+        [\fB\-T\fR|\fB\-\-dynamic\-syms\fR]
+        [\fB\-x\fR|\fB\-\-all\-headers\fR]
+        [\fB\-w\fR|\fB\-\-wide\fR]
+        [\fB\-\-start\-address=\fR\fIaddress\fR]
+        [\fB\-\-stop\-address=\fR\fIaddress\fR]
+        [\fB\-\-no\-addresses\fR]
+        [\fB\-\-prefix\-addresses\fR]
+        [\fB\-\-[no\-]show\-raw\-insn\fR]
+        [\fB\-\-adjust\-vma=\fR\fIoffset\fR]
+        [\fB\-\-show\-all\-symbols\fR]
+        [\fB\-\-dwarf\-depth=\fR\fIn\fR]
+        [\fB\-\-dwarf\-start=\fR\fIn\fR]
+        [\fB\-\-ctf\-parent=\fR\fIsection\fR]
+        [\fB\-\-no\-recurse\-limit\fR|\fB\-\-recurse\-limit\fR]
+        [\fB\-\-special\-syms\fR]
+        [\fB\-\-prefix=\fR\fIprefix\fR]
+        [\fB\-\-prefix\-strip=\fR\fIlevel\fR]
+        [\fB\-\-insn\-width=\fR\fIwidth\fR]
+        [\fB\-\-visualize\-jumps[=color|=extended\-color|=off]\fR
+        [\fB\-\-disassembler\-color=[off|terminal|on|extended]\fR
+        [\fB\-U\fR \fImethod\fR] [\fB\-\-unicode=\fR\fImethod\fR]
+        [\fB\-V\fR|\fB\-\-version\fR]
+        [\fB\-H\fR|\fB\-\-help\fR]
+        \fIobjfile\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBobjdump\fR displays information about one or more object files.
+The options control what particular information to display.  This
+information is mostly useful to programmers who are working on the
+compilation tools, as opposed to programmers who just want their
+program to compile and work.
+.PP
+\&\fIobjfile\fR... are the object files to be examined.  When you
+specify archives, \fBobjdump\fR shows information on each of the member
+object files.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The long and short forms of options, shown here as alternatives, are
+equivalent.  At least one option from the list
+\&\fB\-a,\-d,\-D,\-e,\-f,\-g,\-G,\-h,\-H,\-p,\-P,\-r,\-R,\-s,\-S,\-t,\-T,\-V,\-x\fR must be given.
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-archive\-header\fR" 4
+.IX Item "--archive-header"
+.PD
+If any of the \fIobjfile\fR files are archives, display the archive
+header information (in a format similar to \fBls \-l\fR).  Besides the
+information you could list with \fBar tv\fR, \fBobjdump \-a\fR shows
+the object file format of each archive member.
+.IP "\fB\-\-adjust\-vma=\fR\fIoffset\fR" 4
+.IX Item "--adjust-vma=offset"
+When dumping information, first add \fIoffset\fR to all the section
+addresses.  This is useful if the section addresses do not correspond to
+the symbol table, which can happen when putting sections at particular
+addresses when using a format which can not represent section addresses,
+such as a.out.
+.IP "\fB\-b\fR \fIbfdname\fR" 4
+.IX Item "-b bfdname"
+.PD 0
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+.PD
+Specify that the object-code format for the object files is
+\&\fIbfdname\fR.  This option may not be necessary; \fIobjdump\fR can
+automatically recognize many formats.
+.Sp
+For example,
+.Sp
+.Vb 1
+\&        objdump \-b oasys \-m vax \-h fu.o
+.Ve
+.Sp
+displays summary information from the section headers (\fB\-h\fR) of
+\&\fIfu.o\fR, which is explicitly identified (\fB\-m\fR) as a \s-1VAX\s0 object
+file in the format produced by Oasys compilers.  You can list the
+formats available with the \fB\-i\fR option.
+.IP "\fB\-C\fR" 4
+.IX Item "-C"
+.PD 0
+.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
+.IX Item "--demangle[=style]"
+.PD
+Decode (\fIdemangle\fR) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes \*(C+ function names readable.  Different compilers have different
+mangling styles. The optional demangling style argument can be used to
+choose an appropriate demangling style for your compiler.
+.IP "\fB\-\-recurse\-limit\fR" 4
+.IX Item "--recurse-limit"
+.PD 0
+.IP "\fB\-\-no\-recurse\-limit\fR" 4
+.IX Item "--no-recurse-limit"
+.IP "\fB\-\-recursion\-limit\fR" 4
+.IX Item "--recursion-limit"
+.IP "\fB\-\-no\-recursion\-limit\fR" 4
+.IX Item "--no-recursion-limit"
+.PD
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings.  Since the name mangling formats allow for
+an infinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault.  The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+.Sp
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names.  Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-\-debugging\fR" 4
+.IX Item "--debugging"
+.PD
+Display debugging information.  This attempts to parse \s-1STABS\s0
+debugging format information stored in the file and print it out using
+a C like syntax.  If no \s-1STABS\s0 debugging was found this option
+falls back on the \fB\-W\fR option to print any \s-1DWARF\s0 information in
+the file.
+.IP "\fB\-e\fR" 4
+.IX Item "-e"
+.PD 0
+.IP "\fB\-\-debugging\-tags\fR" 4
+.IX Item "--debugging-tags"
+.PD
+Like \fB\-g\fR, but the information is generated in a format compatible
+with ctags tool.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-\-disassemble\fR" 4
+.IX Item "--disassemble"
+.IP "\fB\-\-disassemble=\fR\fIsymbol\fR" 4
+.IX Item "--disassemble=symbol"
+.PD
+Display the assembler mnemonics for the machine instructions from the
+input file.  This option only disassembles those sections which are 
+expected to contain instructions.  If the optional \fIsymbol\fR
+argument is given, then display the assembler mnemonics starting at
+\&\fIsymbol\fR.  If \fIsymbol\fR is a function name then disassembly
+will stop at the end of the function, otherwise it will stop when the
+next symbol is encountered.  If there are no matches for \fIsymbol\fR
+then nothing will be displayed.
+.Sp
+Note if the \fB\-\-dwarf=follow\-links\fR option is enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.IP "\fB\-\-disassemble\-all\fR" 4
+.IX Item "--disassemble-all"
+.PD
+Like \fB\-d\fR, but disassemble the contents of all sections, not just
+those expected to contain instructions.
+.Sp
+This option also has a subtle effect on the disassembly of
+instructions in code sections.  When option \fB\-d\fR is in effect
+objdump will assume that any symbols present in a code section occur
+on the boundary between instructions and it will refuse to disassemble
+across such a boundary.  When option \fB\-D\fR is in effect however
+this assumption is supressed.  This means that it is possible for the
+output of \fB\-d\fR and \fB\-D\fR to differ if, for example, data
+is stored in code sections.
+.Sp
+If the target is an \s-1ARM\s0 architecture this switch also has the effect
+of forcing the disassembler to decode pieces of data found in code
+sections as if they were instructions.
+.Sp
+Note if the \fB\-\-dwarf=follow\-links\fR option is enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
+.IP "\fB\-\-no\-addresses\fR" 4
+.IX Item "--no-addresses"
+When disassembling, don't print addresses on each line or for symbols
+and relocation offsets.  In combination with \fB\-\-no\-show\-raw\-insn\fR
+this may be useful for comparing compiler output.
+.IP "\fB\-\-prefix\-addresses\fR" 4
+.IX Item "--prefix-addresses"
+When disassembling, print the complete address on each line.  This is
+the older disassembly format.
+.IP "\fB\-EB\fR" 4
+.IX Item "-EB"
+.PD 0
+.IP "\fB\-EL\fR" 4
+.IX Item "-EL"
+.IP "\fB\-\-endian={big|little}\fR" 4
+.IX Item "--endian={big|little}"
+.PD
+Specify the endianness of the object files.  This only affects
+disassembly.  This can be useful when disassembling a file format which
+does not describe endianness information, such as S\-records.
+.IP "\fB\-f\fR" 4
+.IX Item "-f"
+.PD 0
+.IP "\fB\-\-file\-headers\fR" 4
+.IX Item "--file-headers"
+.PD
+Display summary information from the overall header of
+each of the \fIobjfile\fR files.
+.IP "\fB\-F\fR" 4
+.IX Item "-F"
+.PD 0
+.IP "\fB\-\-file\-offsets\fR" 4
+.IX Item "--file-offsets"
+.PD
+When disassembling sections, whenever a symbol is displayed, also
+display the file offset of the region of data that is about to be
+dumped.  If zeroes are being skipped, then when disassembly resumes,
+tell the user how many zeroes were skipped and the file offset of the
+location from where the disassembly resumes.  When dumping sections,
+display the file offset of the location from where the dump starts.
+.IP "\fB\-\-file\-start\-context\fR" 4
+.IX Item "--file-start-context"
+Specify that when displaying interlisted source code/disassembly
+(assumes \fB\-S\fR) from a file that has not yet been displayed, extend the
+context to the start of the file.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-\-section\-headers\fR" 4
+.IX Item "--section-headers"
+.IP "\fB\-\-headers\fR" 4
+.IX Item "--headers"
+.PD
+Display summary information from the section headers of the
+object file.
+.Sp
+File segments may be relocated to nonstandard addresses, for example by
+using the \fB\-Ttext\fR, \fB\-Tdata\fR, or \fB\-Tbss\fR options to
+\&\fBld\fR.  However, some object file formats, such as a.out, do not
+store the starting address of the file segments.  In those situations,
+although \fBld\fR relocates the sections correctly, using \fBobjdump
+\&\-h\fR to list the file section headers cannot show the correct addresses.
+Instead, it shows the usual addresses, which are implicit for the
+target.
+.Sp
+Note, in some cases it is possible for a section to have both the
+\&\s-1READONLY\s0 and the \s-1NOREAD\s0 attributes set.  In such cases the \s-1NOREAD\s0
+attribute takes precedence, but \fBobjdump\fR will report both
+since the exact setting of the flag bits might be important.
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Print a summary of the options to \fBobjdump\fR and exit.
+.IP "\fB\-i\fR" 4
+.IX Item "-i"
+.PD 0
+.IP "\fB\-\-info\fR" 4
+.IX Item "--info"
+.PD
+Display a list showing all architectures and object formats available
+for specification with \fB\-b\fR or \fB\-m\fR.
+.IP "\fB\-j\fR \fIname\fR" 4
+.IX Item "-j name"
+.PD 0
+.IP "\fB\-\-section=\fR\fIname\fR" 4
+.IX Item "--section=name"
+.PD
+Display information only for section \fIname\fR.
+.IP "\fB\-L\fR" 4
+.IX Item "-L"
+.PD 0
+.IP "\fB\-\-process\-links\fR" 4
+.IX Item "--process-links"
+.PD
+Display the contents of non-debug sections found in separate debuginfo
+files that are linked to the main file.  This option automatically
+implies the \fB\-WK\fR option, and only sections requested by other
+command line options will be displayed.
+.IP "\fB\-l\fR" 4
+.IX Item "-l"
+.PD 0
+.IP "\fB\-\-line\-numbers\fR" 4
+.IX Item "--line-numbers"
+.PD
+Label the display (using debugging information) with the filename and
+source line numbers corresponding to the object code or relocs shown.
+Only useful with \fB\-d\fR, \fB\-D\fR, or \fB\-r\fR.
+.IP "\fB\-m\fR \fImachine\fR" 4
+.IX Item "-m machine"
+.PD 0
+.IP "\fB\-\-architecture=\fR\fImachine\fR" 4
+.IX Item "--architecture=machine"
+.PD
+Specify the architecture to use when disassembling object files.  This
+can be useful when disassembling object files which do not describe
+architecture information, such as S\-records.  You can list the available
+architectures with the \fB\-i\fR option.
+.Sp
+For most architectures it is possible to supply an architecture
+name and a machine name, separated by a colon.  For example
+\&\fBfoo:bar\fR would refer to the \fBbar\fR machine type in the
+\&\fBfoo\fR architecture.  This can be helpful if objdump has been
+configured to support multiple architectures.
+.Sp
+If the target is an \s-1ARM\s0 architecture then this switch has an
+additional effect.  It restricts the disassembly to only those
+instructions supported by the architecture specified by \fImachine\fR.
+If it is necessary to use this switch because the input file does not
+contain any architecture information, but it is also desired to
+disassemble all the instructions use \fB\-marm\fR.
+.IP "\fB\-M\fR \fIoptions\fR" 4
+.IX Item "-M options"
+.PD 0
+.IP "\fB\-\-disassembler\-options=\fR\fIoptions\fR" 4
+.IX Item "--disassembler-options=options"
+.PD
+Pass target specific information to the disassembler.  Only supported on
+some targets.  If it is necessary to specify more than one
+disassembler option then multiple \fB\-M\fR options can be used or
+can be placed together into a comma separated list.
+.Sp
+For \s-1ARC,\s0 \fBdsp\fR controls the printing of \s-1DSP\s0 instructions,
+\&\fBspfp\fR selects the printing of \s-1FPX\s0 single precision \s-1FP\s0
+instructions, \fBdpfp\fR selects the printing of \s-1FPX\s0 double
+precision \s-1FP\s0 instructions, \fBquarkse_em\fR selects the printing of
+special QuarkSE-EM instructions, \fBfpuda\fR selects the printing
+of double precision assist instructions, \fBfpus\fR selects the
+printing of \s-1FPU\s0 single precision \s-1FP\s0 instructions, while \fBfpud\fR
+selects the printing of \s-1FPU\s0 double precision \s-1FP\s0 instructions.
+Additionally, one can choose to have all the immediates printed in
+hexadecimal using \fBhex\fR.  By default, the short immediates are
+printed using the decimal representation, while the long immediate
+values are printed as hexadecimal.
+.Sp
+\&\fBcpu=...\fR allows one to enforce a particular \s-1ISA\s0 when disassembling
+instructions, overriding the \fB\-m\fR value or whatever is in the \s-1ELF\s0 file.
+This might be useful to select \s-1ARC EM\s0 or \s-1HS ISA,\s0 because architecture is same
+for those and disassembler relies on private \s-1ELF\s0 header data to decide if code
+is for \s-1EM\s0 or \s-1HS.\s0  This option might be specified multiple times \- only the
+latest value will be used.  Valid values are same as for the assembler
+\&\fB\-mcpu=...\fR option.
+.Sp
+If the target is an \s-1ARM\s0 architecture then this switch can be used to
+select which register name set is used during disassembler.  Specifying
+\&\fB\-M reg-names-std\fR (the default) will select the register names as
+used in \s-1ARM\s0's instruction set documentation, but with register 13 called
+\&'sp', register 14 called 'lr' and register 15 called 'pc'.  Specifying
+\&\fB\-M reg-names-apcs\fR will select the name set used by the \s-1ARM\s0
+Procedure Call Standard, whilst specifying \fB\-M reg-names-raw\fR will
+just use \fBr\fR followed by the register number.
+.Sp
+There are also two variants on the \s-1APCS\s0 register naming scheme enabled
+by \fB\-M reg-names-atpcs\fR and \fB\-M reg-names-special-atpcs\fR which
+use the ARM/Thumb Procedure Call Standard naming conventions.  (Either
+with the normal register names or the special register names).
+.Sp
+This option can also be used for \s-1ARM\s0 architectures to force the
+disassembler to interpret all instructions as Thumb instructions by
+using the switch \fB\-\-disassembler\-options=force\-thumb\fR.  This can be
+useful when attempting to disassemble thumb code produced by other
+compilers.
+.Sp
+For AArch64 targets this switch can be used to set whether instructions are
+disassembled as the most general instruction using the \fB\-M no-aliases\fR
+option or whether instruction notes should be generated as comments in the
+disasssembly using \fB\-M notes\fR.
+.Sp
+For the x86, some of the options duplicate functions of the \fB\-m\fR
+switch, but allow finer grained control.
+.RS 4
+.ie n .IP """x86\-64""" 4
+.el .IP "\f(CWx86\-64\fR" 4
+.IX Item "x86-64"
+.PD 0
+.ie n .IP """i386""" 4
+.el .IP "\f(CWi386\fR" 4
+.IX Item "i386"
+.ie n .IP """i8086""" 4
+.el .IP "\f(CWi8086\fR" 4
+.IX Item "i8086"
+.PD
+Select disassembly for the given architecture.
+.ie n .IP """intel""" 4
+.el .IP "\f(CWintel\fR" 4
+.IX Item "intel"
+.PD 0
+.ie n .IP """att""" 4
+.el .IP "\f(CWatt\fR" 4
+.IX Item "att"
+.PD
+Select between intel syntax mode and \s-1AT&T\s0 syntax mode.
+.ie n .IP """amd64""" 4
+.el .IP "\f(CWamd64\fR" 4
+.IX Item "amd64"
+.PD 0
+.ie n .IP """intel64""" 4
+.el .IP "\f(CWintel64\fR" 4
+.IX Item "intel64"
+.PD
+Select between \s-1AMD64 ISA\s0 and Intel64 \s-1ISA.\s0
+.ie n .IP """intel\-mnemonic""" 4
+.el .IP "\f(CWintel\-mnemonic\fR" 4
+.IX Item "intel-mnemonic"
+.PD 0
+.ie n .IP """att\-mnemonic""" 4
+.el .IP "\f(CWatt\-mnemonic\fR" 4
+.IX Item "att-mnemonic"
+.PD
+Select between intel mnemonic mode and \s-1AT&T\s0 mnemonic mode.
+Note: \f(CW\*(C`intel\-mnemonic\*(C'\fR implies \f(CW\*(C`intel\*(C'\fR and
+\&\f(CW\*(C`att\-mnemonic\*(C'\fR implies \f(CW\*(C`att\*(C'\fR.
+.ie n .IP """addr64""" 4
+.el .IP "\f(CWaddr64\fR" 4
+.IX Item "addr64"
+.PD 0
+.ie n .IP """addr32""" 4
+.el .IP "\f(CWaddr32\fR" 4
+.IX Item "addr32"
+.ie n .IP """addr16""" 4
+.el .IP "\f(CWaddr16\fR" 4
+.IX Item "addr16"
+.ie n .IP """data32""" 4
+.el .IP "\f(CWdata32\fR" 4
+.IX Item "data32"
+.ie n .IP """data16""" 4
+.el .IP "\f(CWdata16\fR" 4
+.IX Item "data16"
+.PD
+Specify the default address size and operand size.  These five options
+will be overridden if \f(CW\*(C`x86\-64\*(C'\fR, \f(CW\*(C`i386\*(C'\fR or \f(CW\*(C`i8086\*(C'\fR
+appear later in the option string.
+.ie n .IP """suffix""" 4
+.el .IP "\f(CWsuffix\fR" 4
+.IX Item "suffix"
+When in \s-1AT&T\s0 mode and also for a limited set of instructions when in Intel
+mode, instructs the disassembler to print a mnemonic suffix even when the
+suffix could be inferred by the operands or, for certain instructions, the
+execution mode's defaults.
+.RE
+.RS 4
+.Sp
+For PowerPC, the \fB\-M\fR argument \fBraw\fR selects
+disasssembly of hardware insns rather than aliases.  For example, you
+will see \f(CW\*(C`rlwinm\*(C'\fR rather than \f(CW\*(C`clrlwi\*(C'\fR, and \f(CW\*(C`addi\*(C'\fR
+rather than \f(CW\*(C`li\*(C'\fR.  All of the \fB\-m\fR arguments for
+\&\fBgas\fR that select a \s-1CPU\s0 are supported.  These are:
+\&\fB403\fR, \fB405\fR, \fB440\fR, \fB464\fR, \fB476\fR,
+\&\fB601\fR, \fB603\fR, \fB604\fR, \fB620\fR, \fB7400\fR,
+\&\fB7410\fR, \fB7450\fR, \fB7455\fR, \fB750cl\fR,
+\&\fB821\fR, \fB850\fR, \fB860\fR, \fBa2\fR, \fBbooke\fR,
+\&\fBbooke32\fR, \fBcell\fR, \fBcom\fR, \fBe200z2\fR, \fBe200z4\fR,
+\&\fBe300\fR, \fBe500\fR, \fBe500mc\fR, \fBe500mc64\fR,
+\&\fBe500x2\fR, \fBe5500\fR, \fBe6500\fR, \fBefs\fR,
+\&\fBpower4\fR, \fBpower5\fR, \fBpower6\fR, \fBpower7\fR,
+\&\fBpower8\fR, \fBpower9\fR, \fBpower10\fR, \fBppc\fR,
+\&\fBppc32\fR, \fBppc64\fR, \fBppc64bridge\fR, \fBppcps\fR,
+\&\fBpwr\fR, \fBpwr2\fR, \fBpwr4\fR, \fBpwr5\fR, \fBpwr5x\fR,
+\&\fBpwr6\fR, \fBpwr7\fR, \fBpwr8\fR, \fBpwr9\fR, \fBpwr10\fR,
+\&\fBpwrx\fR, \fBtitan\fR, \fBvle\fR, and \fBfuture\fR.
+\&\fB32\fR and \fB64\fR modify the default or a prior \s-1CPU\s0
+selection, disabling and enabling 64\-bit insns respectively.  In
+addition, \fBaltivec\fR, \fBany\fR, \fBlsp\fR, \fBhtm\fR,
+\&\fBvsx\fR, \fBspe\fR and  \fBspe2\fR add capabilities to a
+previous \fIor later\fR \s-1CPU\s0 selection.
+\&\fBany\fR will disassemble any opcode known to
+binutils, but in cases where an opcode has two different meanings or
+different arguments, you may not see the disassembly you expect.
+If you disassemble without giving a \s-1CPU\s0 selection, a default will be
+chosen from information gleaned by \s-1BFD\s0 from the object files headers,
+but the result again may not be as you expect.
+.Sp
+For \s-1MIPS,\s0 this option controls the printing of instruction mnemonic
+names and register names in disassembled instructions.  Multiple
+selections from the following may be specified as a comma separated
+string, and invalid options are ignored:
+.ie n .IP """no\-aliases""" 4
+.el .IP "\f(CWno\-aliases\fR" 4
+.IX Item "no-aliases"
+Print the 'raw' instruction mnemonic instead of some pseudo
+instruction mnemonic.  I.e., print 'daddu' or 'or' instead of 'move',
+\&'sll' instead of 'nop', etc.
+.ie n .IP """msa""" 4
+.el .IP "\f(CWmsa\fR" 4
+.IX Item "msa"
+Disassemble \s-1MSA\s0 instructions.
+.ie n .IP """virt""" 4
+.el .IP "\f(CWvirt\fR" 4
+.IX Item "virt"
+Disassemble the virtualization \s-1ASE\s0 instructions.
+.ie n .IP """xpa""" 4
+.el .IP "\f(CWxpa\fR" 4
+.IX Item "xpa"
+Disassemble the eXtended Physical Address (\s-1XPA\s0) \s-1ASE\s0 instructions.
+.ie n .IP """gpr\-names=\fIABI\fP""" 4
+.el .IP "\f(CWgpr\-names=\f(CIABI\f(CW\fR" 4
+.IX Item "gpr-names=ABI"
+Print \s-1GPR\s0 (general-purpose register) names as appropriate
+for the specified \s-1ABI.\s0  By default, \s-1GPR\s0 names are selected according to
+the \s-1ABI\s0 of the binary being disassembled.
+.ie n .IP """fpr\-names=\fIABI\fP""" 4
+.el .IP "\f(CWfpr\-names=\f(CIABI\f(CW\fR" 4
+.IX Item "fpr-names=ABI"
+Print \s-1FPR\s0 (floating-point register) names as
+appropriate for the specified \s-1ABI.\s0  By default, \s-1FPR\s0 numbers are printed
+rather than names.
+.ie n .IP """cp0\-names=\fIARCH\fP""" 4
+.el .IP "\f(CWcp0\-names=\f(CIARCH\f(CW\fR" 4
+.IX Item "cp0-names=ARCH"
+Print \s-1CP0\s0 (system control coprocessor; coprocessor 0) register names
+as appropriate for the \s-1CPU\s0 or architecture specified by
+\&\fI\s-1ARCH\s0\fR.  By default, \s-1CP0\s0 register names are selected according to
+the architecture and \s-1CPU\s0 of the binary being disassembled.
+.ie n .IP """hwr\-names=\fIARCH\fP""" 4
+.el .IP "\f(CWhwr\-names=\f(CIARCH\f(CW\fR" 4
+.IX Item "hwr-names=ARCH"
+Print \s-1HWR\s0 (hardware register, used by the \f(CW\*(C`rdhwr\*(C'\fR instruction) names
+as appropriate for the \s-1CPU\s0 or architecture specified by
+\&\fI\s-1ARCH\s0\fR.  By default, \s-1HWR\s0 names are selected according to
+the architecture and \s-1CPU\s0 of the binary being disassembled.
+.ie n .IP """reg\-names=\fIABI\fP""" 4
+.el .IP "\f(CWreg\-names=\f(CIABI\f(CW\fR" 4
+.IX Item "reg-names=ABI"
+Print \s-1GPR\s0 and \s-1FPR\s0 names as appropriate for the selected \s-1ABI.\s0
+.ie n .IP """reg\-names=\fIARCH\fP""" 4
+.el .IP "\f(CWreg\-names=\f(CIARCH\f(CW\fR" 4
+.IX Item "reg-names=ARCH"
+Print CPU-specific register names (\s-1CP0\s0 register and \s-1HWR\s0 names)
+as appropriate for the selected \s-1CPU\s0 or architecture.
+.RE
+.RS 4
+.Sp
+For any of the options listed above, \fI\s-1ABI\s0\fR or
+\&\fI\s-1ARCH\s0\fR may be specified as \fBnumeric\fR to have numbers printed
+rather than names, for the selected types of registers.
+You can list the available values of \fI\s-1ABI\s0\fR and \fI\s-1ARCH\s0\fR using
+the \fB\-\-help\fR option.
+.Sp
+For \s-1VAX,\s0 you can specify function entry addresses with \fB\-M
+entry:0xf00ba\fR.  You can use this multiple times to properly
+disassemble \s-1VAX\s0 binary files that don't contain symbol tables (like
+\&\s-1ROM\s0 dumps).  In these cases, the function entry mask would otherwise
+be decoded as \s-1VAX\s0 instructions, which would probably lead the rest
+of the function being wrongly disassembled.
+.RE
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-private\-headers\fR" 4
+.IX Item "--private-headers"
+.PD
+Print information that is specific to the object file format.  The exact
+information printed depends upon the object file format.  For some
+object file formats, no additional information is printed.
+.IP "\fB\-P\fR \fIoptions\fR" 4
+.IX Item "-P options"
+.PD 0
+.IP "\fB\-\-private=\fR\fIoptions\fR" 4
+.IX Item "--private=options"
+.PD
+Print information that is specific to the object file format.  The
+argument \fIoptions\fR is a comma separated list that depends on the
+format (the lists of options is displayed with the help).
+.Sp
+For \s-1XCOFF,\s0 the available options are:
+.RS 4
+.ie n .IP """header""" 4
+.el .IP "\f(CWheader\fR" 4
+.IX Item "header"
+.PD 0
+.ie n .IP """aout""" 4
+.el .IP "\f(CWaout\fR" 4
+.IX Item "aout"
+.ie n .IP """sections""" 4
+.el .IP "\f(CWsections\fR" 4
+.IX Item "sections"
+.ie n .IP """syms""" 4
+.el .IP "\f(CWsyms\fR" 4
+.IX Item "syms"
+.ie n .IP """relocs""" 4
+.el .IP "\f(CWrelocs\fR" 4
+.IX Item "relocs"
+.ie n .IP """lineno,""" 4
+.el .IP "\f(CWlineno,\fR" 4
+.IX Item "lineno,"
+.ie n .IP """loader""" 4
+.el .IP "\f(CWloader\fR" 4
+.IX Item "loader"
+.ie n .IP """except""" 4
+.el .IP "\f(CWexcept\fR" 4
+.IX Item "except"
+.ie n .IP """typchk""" 4
+.el .IP "\f(CWtypchk\fR" 4
+.IX Item "typchk"
+.ie n .IP """traceback""" 4
+.el .IP "\f(CWtraceback\fR" 4
+.IX Item "traceback"
+.ie n .IP """toc""" 4
+.el .IP "\f(CWtoc\fR" 4
+.IX Item "toc"
+.ie n .IP """ldinfo""" 4
+.el .IP "\f(CWldinfo\fR" 4
+.IX Item "ldinfo"
+.RE
+.RS 4
+.PD
+.Sp
+Not all object formats support this option.  In particular the \s-1ELF\s0
+format does not use it.
+.RE
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-\-reloc\fR" 4
+.IX Item "--reloc"
+.PD
+Print the relocation entries of the file.  If used with \fB\-d\fR or
+\&\fB\-D\fR, the relocations are printed interspersed with the
+disassembly.
+.IP "\fB\-R\fR" 4
+.IX Item "-R"
+.PD 0
+.IP "\fB\-\-dynamic\-reloc\fR" 4
+.IX Item "--dynamic-reloc"
+.PD
+Print the dynamic relocation entries of the file.  This is only
+meaningful for dynamic objects, such as certain types of shared
+libraries.  As for \fB\-r\fR, if used with \fB\-d\fR or
+\&\fB\-D\fR, the relocations are printed interspersed with the
+disassembly.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-full\-contents\fR" 4
+.IX Item "--full-contents"
+.PD
+Display the full contents of any sections requested.  By default all
+non-empty sections are displayed.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-source\fR" 4
+.IX Item "--source"
+.PD
+Display source code intermixed with disassembly, if possible.  Implies
+\&\fB\-d\fR.
+.IP "\fB\-\-show\-all\-symbols\fR" 4
+.IX Item "--show-all-symbols"
+When disassembling, show all the symbols that match a given address,
+not just the first one.
+.IP "\fB\-\-source\-comment[=\fR\fItxt\fR\fB]\fR" 4
+.IX Item "--source-comment[=txt]"
+Like the \fB\-S\fR option, but all source code lines are displayed
+with a prefix of \fItxt\fR.  Typically \fItxt\fR will be a comment
+string which can be used to distinguish the assembler code from the
+source code.  If \fItxt\fR is not provided then a default string of
+\&\fI\*(L"# \*(R"\fR (hash followed by a space), will be used.
+.IP "\fB\-\-prefix=\fR\fIprefix\fR" 4
+.IX Item "--prefix=prefix"
+Specify \fIprefix\fR to add to the absolute paths when used with
+\&\fB\-S\fR.
+.IP "\fB\-\-prefix\-strip=\fR\fIlevel\fR" 4
+.IX Item "--prefix-strip=level"
+Indicate how many initial directory names to strip off the hardwired
+absolute paths. It has no effect without \fB\-\-prefix=\fR\fIprefix\fR.
+.IP "\fB\-\-show\-raw\-insn\fR" 4
+.IX Item "--show-raw-insn"
+When disassembling instructions, print the instruction in hex as well as
+in symbolic form.  This is the default except when
+\&\fB\-\-prefix\-addresses\fR is used.
+.IP "\fB\-\-no\-show\-raw\-insn\fR" 4
+.IX Item "--no-show-raw-insn"
+When disassembling instructions, do not print the instruction bytes.
+This is the default when \fB\-\-prefix\-addresses\fR is used.
+.IP "\fB\-\-insn\-width=\fR\fIwidth\fR" 4
+.IX Item "--insn-width=width"
+Display \fIwidth\fR bytes on a single line when disassembling
+instructions.
+.IP "\fB\-\-visualize\-jumps[=color|=extended\-color|=off]\fR" 4
+.IX Item "--visualize-jumps[=color|=extended-color|=off]"
+Visualize jumps that stay inside a function by drawing \s-1ASCII\s0 art between
+the start and target addresses.  The optional \fB=color\fR argument
+adds color to the output using simple terminal colors.  Alternatively
+the \fB=extended\-color\fR argument will add color using 8bit
+colors, but these might not work on all terminals.
+.Sp
+If it is necessary to disable the \fBvisualize-jumps\fR option
+after it has previously been enabled then use
+\&\fBvisualize\-jumps=off\fR.
+.IP "\fB\-\-disassembler\-color=off\fR" 4
+.IX Item "--disassembler-color=off"
+.PD 0
+.IP "\fB\-\-disassembler\-color=terminal\fR" 4
+.IX Item "--disassembler-color=terminal"
+.IP "\fB\-\-disassembler\-color=on|color|colour\fR" 4
+.IX Item "--disassembler-color=on|color|colour"
+.IP "\fB\-\-disassembler\-color=extened|extended\-color|extened\-colour\fR" 4
+.IX Item "--disassembler-color=extened|extended-color|extened-colour"
+.PD
+Enables or disables the use of colored syntax highlighting in
+disassembly output.  The default behaviour is determined via a
+configure time option.  Note, not all architectures support colored
+syntax highlighting, and depending upon the terminal used, colored
+output may not actually be legible.
+.Sp
+The \fBon\fR argument adds colors using simple terminal colors.
+.Sp
+The \fBterminal\fR argument does the same, but only if the output
+device is a terminal.
+.Sp
+The \fBextended-color\fR argument is similar to the \fBon\fR
+argument, but it uses 8\-bit colors.  These may not work on all
+terminals.
+.Sp
+The \fBoff\fR argument disables colored disassembly.
+.IP "\fB\-W[lLiaprmfFsoORtUuTgAckK]\fR" 4
+.IX Item "-W[lLiaprmfFsoORtUuTgAckK]"
+.PD 0
+.IP "\fB\-\-dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR" 4
+.IX Item "--dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
+.PD
+Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any
+are present.  Compressed debug sections are automatically decompressed
+(temporarily) before they are displayed.  If one or more of the
+optional letters or words follows the switch then only those type(s)
+of data will be dumped.  The letters and words refer to the following
+information:
+.RS 4
+.ie n .IP """a""" 4
+.el .IP "\f(CWa\fR" 4
+.IX Item "a"
+.PD 0
+.ie n .IP """=abbrev""" 4
+.el .IP "\f(CW=abbrev\fR" 4
+.IX Item "=abbrev"
+.PD
+Displays the contents of the \fB.debug_abbrev\fR section.
+.ie n .IP """A""" 4
+.el .IP "\f(CWA\fR" 4
+.IX Item "A"
+.PD 0
+.ie n .IP """=addr""" 4
+.el .IP "\f(CW=addr\fR" 4
+.IX Item "=addr"
+.PD
+Displays the contents of the \fB.debug_addr\fR section.
+.ie n .IP """c""" 4
+.el .IP "\f(CWc\fR" 4
+.IX Item "c"
+.PD 0
+.ie n .IP """=cu_index""" 4
+.el .IP "\f(CW=cu_index\fR" 4
+.IX Item "=cu_index"
+.PD
+Displays the contents of the \fB.debug_cu_index\fR and/or
+\&\fB.debug_tu_index\fR sections.
+.ie n .IP """f""" 4
+.el .IP "\f(CWf\fR" 4
+.IX Item "f"
+.PD 0
+.ie n .IP """=frames""" 4
+.el .IP "\f(CW=frames\fR" 4
+.IX Item "=frames"
+.PD
+Display the raw contents of a \fB.debug_frame\fR section.
+.ie n .IP """F""" 4
+.el .IP "\f(CWF\fR" 4
+.IX Item "F"
+.PD 0
+.ie n .IP """=frames\-interp""" 4
+.el .IP "\f(CW=frames\-interp\fR" 4
+.IX Item "=frames-interp"
+.PD
+Display the interpreted contents of a \fB.debug_frame\fR section.
+.ie n .IP """g""" 4
+.el .IP "\f(CWg\fR" 4
+.IX Item "g"
+.PD 0
+.ie n .IP """=gdb_index""" 4
+.el .IP "\f(CW=gdb_index\fR" 4
+.IX Item "=gdb_index"
+.PD
+Displays the contents of the \fB.gdb_index\fR and/or
+\&\fB.debug_names\fR sections.
+.ie n .IP """i""" 4
+.el .IP "\f(CWi\fR" 4
+.IX Item "i"
+.PD 0
+.ie n .IP """=info""" 4
+.el .IP "\f(CW=info\fR" 4
+.IX Item "=info"
+.PD
+Displays the contents of the \fB.debug_info\fR section.  Note: the
+output from this option can also be restricted by the use of the 
+\&\fB\-\-dwarf\-depth\fR and \fB\-\-dwarf\-start\fR options.
+.ie n .IP """k""" 4
+.el .IP "\f(CWk\fR" 4
+.IX Item "k"
+.PD 0
+.ie n .IP """=links""" 4
+.el .IP "\f(CW=links\fR" 4
+.IX Item "=links"
+.PD
+Displays the contents of the \fB.gnu_debuglink\fR,
+\&\fB.gnu_debugaltlink\fR and \fB.debug_sup\fR sections, if any of
+them are present.  Also displays any links to separate dwarf object
+files (dwo), if they are specified by the DW_AT_GNU_dwo_name or
+DW_AT_dwo_name attributes in the \fB.debug_info\fR section.
+.ie n .IP """K""" 4
+.el .IP "\f(CWK\fR" 4
+.IX Item "K"
+.PD 0
+.ie n .IP """=follow\-links""" 4
+.el .IP "\f(CW=follow\-links\fR" 4
+.IX Item "=follow-links"
+.PD
+Display the contents of any selected debug sections that are found in
+linked, separate debug info file(s).  This can result in multiple
+versions of the same debug section being displayed if it exists in
+more than one file.
+.Sp
+In addition, when displaying \s-1DWARF\s0 attributes, if a form is found that
+references the separate debug info file, then the referenced contents
+will also be displayed.
+.Sp
+Note \- in some distributions this option is enabled by default.  It
+can be disabled via the \fBN\fR debug option.  The default can be
+chosen when configuring the binutils via the
+\&\fB\-\-enable\-follow\-debug\-links=yes\fR or
+\&\fB\-\-enable\-follow\-debug\-links=no\fR options.  If these are not
+used then the default is to enable the following of debug links.
+.Sp
+Note \- if support for the debuginfod protocol was enabled when the
+binutils were built then this option will also include an attempt to
+contact any debuginfod servers mentioned in the \fI\s-1DEBUGINFOD_URLS\s0\fR
+environment variable.  This could take some time to resolve.  This
+behaviour can be disabled via the \fB=do\-not\-use\-debuginfod\fR debug
+option.
+.ie n .IP """N""" 4
+.el .IP "\f(CWN\fR" 4
+.IX Item "N"
+.PD 0
+.ie n .IP """=no\-follow\-links""" 4
+.el .IP "\f(CW=no\-follow\-links\fR" 4
+.IX Item "=no-follow-links"
+.PD
+Disables the following of links to separate debug info files.
+.ie n .IP """D""" 4
+.el .IP "\f(CWD\fR" 4
+.IX Item "D"
+.PD 0
+.ie n .IP """=use\-debuginfod""" 4
+.el .IP "\f(CW=use\-debuginfod\fR" 4
+.IX Item "=use-debuginfod"
+.PD
+Enables contacting debuginfod servers if there is a need to follow
+debug links.  This is the default behaviour.
+.ie n .IP """E""" 4
+.el .IP "\f(CWE\fR" 4
+.IX Item "E"
+.PD 0
+.ie n .IP """=do\-not\-use\-debuginfod""" 4
+.el .IP "\f(CW=do\-not\-use\-debuginfod\fR" 4
+.IX Item "=do-not-use-debuginfod"
+.PD
+Disables contacting debuginfod servers when there is a need to follow
+debug links.
+.ie n .IP """l""" 4
+.el .IP "\f(CWl\fR" 4
+.IX Item "l"
+.PD 0
+.ie n .IP """=rawline""" 4
+.el .IP "\f(CW=rawline\fR" 4
+.IX Item "=rawline"
+.PD
+Displays the contents of the \fB.debug_line\fR section in a raw
+format.
+.ie n .IP """L""" 4
+.el .IP "\f(CWL\fR" 4
+.IX Item "L"
+.PD 0
+.ie n .IP """=decodedline""" 4
+.el .IP "\f(CW=decodedline\fR" 4
+.IX Item "=decodedline"
+.PD
+Displays the interpreted contents of the \fB.debug_line\fR section.
+.ie n .IP """m""" 4
+.el .IP "\f(CWm\fR" 4
+.IX Item "m"
+.PD 0
+.ie n .IP """=macro""" 4
+.el .IP "\f(CW=macro\fR" 4
+.IX Item "=macro"
+.PD
+Displays the contents of the \fB.debug_macro\fR and/or
+\&\fB.debug_macinfo\fR sections.
+.ie n .IP """o""" 4
+.el .IP "\f(CWo\fR" 4
+.IX Item "o"
+.PD 0
+.ie n .IP """=loc""" 4
+.el .IP "\f(CW=loc\fR" 4
+.IX Item "=loc"
+.PD
+Displays the contents of the \fB.debug_loc\fR and/or
+\&\fB.debug_loclists\fR sections.
+.ie n .IP """O""" 4
+.el .IP "\f(CWO\fR" 4
+.IX Item "O"
+.PD 0
+.ie n .IP """=str\-offsets""" 4
+.el .IP "\f(CW=str\-offsets\fR" 4
+.IX Item "=str-offsets"
+.PD
+Displays the contents of the \fB.debug_str_offsets\fR section.
+.ie n .IP """p""" 4
+.el .IP "\f(CWp\fR" 4
+.IX Item "p"
+.PD 0
+.ie n .IP """=pubnames""" 4
+.el .IP "\f(CW=pubnames\fR" 4
+.IX Item "=pubnames"
+.PD
+Displays the contents of the \fB.debug_pubnames\fR and/or
+\&\fB.debug_gnu_pubnames\fR sections.
+.ie n .IP """r""" 4
+.el .IP "\f(CWr\fR" 4
+.IX Item "r"
+.PD 0
+.ie n .IP """=aranges""" 4
+.el .IP "\f(CW=aranges\fR" 4
+.IX Item "=aranges"
+.PD
+Displays the contents of the \fB.debug_aranges\fR section.
+.ie n .IP """R""" 4
+.el .IP "\f(CWR\fR" 4
+.IX Item "R"
+.PD 0
+.ie n .IP """=Ranges""" 4
+.el .IP "\f(CW=Ranges\fR" 4
+.IX Item "=Ranges"
+.PD
+Displays the contents of the \fB.debug_ranges\fR and/or
+\&\fB.debug_rnglists\fR sections.
+.ie n .IP """s""" 4
+.el .IP "\f(CWs\fR" 4
+.IX Item "s"
+.PD 0
+.ie n .IP """=str""" 4
+.el .IP "\f(CW=str\fR" 4
+.IX Item "=str"
+.PD
+Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR
+and/or \fB.debug_str_offsets\fR sections.
+.ie n .IP """t""" 4
+.el .IP "\f(CWt\fR" 4
+.IX Item "t"
+.PD 0
+.ie n .IP """=pubtype""" 4
+.el .IP "\f(CW=pubtype\fR" 4
+.IX Item "=pubtype"
+.PD
+Displays the contents of the \fB.debug_pubtypes\fR and/or
+\&\fB.debug_gnu_pubtypes\fR sections.
+.ie n .IP """T""" 4
+.el .IP "\f(CWT\fR" 4
+.IX Item "T"
+.PD 0
+.ie n .IP """=trace_aranges""" 4
+.el .IP "\f(CW=trace_aranges\fR" 4
+.IX Item "=trace_aranges"
+.PD
+Displays the contents of the \fB.trace_aranges\fR section.
+.ie n .IP """u""" 4
+.el .IP "\f(CWu\fR" 4
+.IX Item "u"
+.PD 0
+.ie n .IP """=trace_abbrev""" 4
+.el .IP "\f(CW=trace_abbrev\fR" 4
+.IX Item "=trace_abbrev"
+.PD
+Displays the contents of the \fB.trace_abbrev\fR section.
+.ie n .IP """U""" 4
+.el .IP "\f(CWU\fR" 4
+.IX Item "U"
+.PD 0
+.ie n .IP """=trace_info""" 4
+.el .IP "\f(CW=trace_info\fR" 4
+.IX Item "=trace_info"
+.PD
+Displays the contents of the \fB.trace_info\fR section.
+.RE
+.RS 4
+.Sp
+Note: displaying the contents of \fB.debug_static_funcs\fR,
+\&\fB.debug_static_vars\fR and \fBdebug_weaknames\fR sections is not
+currently supported.
+.RE
+.IP "\fB\-\-dwarf\-depth=\fR\fIn\fR" 4
+.IX Item "--dwarf-depth=n"
+Limit the dump of the \f(CW\*(C`.debug_info\*(C'\fR section to \fIn\fR children.
+This is only useful with \fB\-\-debug\-dump=info\fR.  The default is
+to print all DIEs; the special value 0 for \fIn\fR will also have this
+effect.
+.Sp
+With a non-zero value for \fIn\fR, DIEs at or deeper than \fIn\fR
+levels will not be printed.  The range for \fIn\fR is zero-based.
+.IP "\fB\-\-dwarf\-start=\fR\fIn\fR" 4
+.IX Item "--dwarf-start=n"
+Print only DIEs beginning with the \s-1DIE\s0 numbered \fIn\fR.  This is only
+useful with \fB\-\-debug\-dump=info\fR.
+.Sp
+If specified, this option will suppress printing of any header
+information and all DIEs before the \s-1DIE\s0 numbered \fIn\fR.  Only
+siblings and children of the specified \s-1DIE\s0 will be printed.
+.Sp
+This can be used in conjunction with \fB\-\-dwarf\-depth\fR.
+.IP "\fB\-\-dwarf\-check\fR" 4
+.IX Item "--dwarf-check"
+Enable additional checks for consistency of Dwarf information.
+.IP "\fB\-\-ctf[=\fR\fIsection\fR\fB]\fR" 4
+.IX Item "--ctf[=section]"
+Display the contents of the specified \s-1CTF\s0 section.  \s-1CTF\s0 sections themselves
+contain many subsections, all of which are displayed in order.
+.Sp
+By default, display the name of the section named \fI.ctf\fR, which is the
+name emitted by \fBld\fR.
+.IP "\fB\-\-ctf\-parent=\fR\fImember\fR" 4
+.IX Item "--ctf-parent=member"
+If the \s-1CTF\s0 section contains ambiguously-defined types, it will consist
+of an archive of many \s-1CTF\s0 dictionaries, all inheriting from one
+dictionary containing unambiguous types.  This member is by default
+named \fI.ctf\fR, like the section containing it, but it is possible to
+change this name using the \f(CW\*(C`ctf_link_set_memb_name_changer\*(C'\fR
+function at link time.  When looking at \s-1CTF\s0 archives that have been
+created by a linker that uses the name changer to rename the parent
+archive member, \fB\-\-ctf\-parent\fR can be used to specify the name
+used for the parent.
+.IP "\fB\-\-sframe[=\fR\fIsection\fR\fB]\fR" 4
+.IX Item "--sframe[=section]"
+Display the contents of the specified SFrame section.
+.Sp
+By default, display the name of the section named \fI.sframe\fR, which is the
+name emitted by \fBld\fR.
+.IP "\fB\-G\fR" 4
+.IX Item "-G"
+.PD 0
+.IP "\fB\-\-stabs\fR" 4
+.IX Item "--stabs"
+.PD
+Display the full contents of any sections requested.  Display the
+contents of the .stab and .stab.index and .stab.excl sections from an
+\&\s-1ELF\s0 file.  This is only useful on systems (such as Solaris 2.0) in which
+\&\f(CW\*(C`.stab\*(C'\fR debugging symbol-table entries are carried in an \s-1ELF\s0
+section.  In most other file formats, debugging symbol-table entries are
+interleaved with linkage symbols, and are visible in the \fB\-\-syms\fR
+output.
+.IP "\fB\-\-start\-address=\fR\fIaddress\fR" 4
+.IX Item "--start-address=address"
+Start displaying data at the specified address.  This affects the output
+of the \fB\-d\fR, \fB\-r\fR and \fB\-s\fR options.
+.IP "\fB\-\-stop\-address=\fR\fIaddress\fR" 4
+.IX Item "--stop-address=address"
+Stop displaying data at the specified address.  This affects the output
+of the \fB\-d\fR, \fB\-r\fR and \fB\-s\fR options.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.IP "\fB\-\-syms\fR" 4
+.IX Item "--syms"
+.PD
+Print the symbol table entries of the file.
+This is similar to the information provided by the \fBnm\fR program,
+although the display format is different.  The format of the output
+depends upon the format of the file being dumped, but there are two main
+types.  One looks like this:
+.Sp
+.Vb 2
+\&        [  4](sec  3)(fl 0x00)(ty   0)(scl   3) (nx 1) 0x00000000 .bss
+\&        [  6](sec  1)(fl 0x00)(ty   0)(scl   2) (nx 0) 0x00000000 fred
+.Ve
+.Sp
+where the number inside the square brackets is the number of the entry
+in the symbol table, the \fIsec\fR number is the section number, the
+\&\fIfl\fR value are the symbol's flag bits, the \fIty\fR number is the
+symbol's type, the \fIscl\fR number is the symbol's storage class and
+the \fInx\fR value is the number of auxiliary entries associated with
+the symbol.  The last two fields are the symbol's value and its name.
+.Sp
+The other common output format, usually seen with \s-1ELF\s0 based files,
+looks like this:
+.Sp
+.Vb 2
+\&        00000000 l    d  .bss   00000000 .bss
+\&        00000000 g       .text  00000000 fred
+.Ve
+.Sp
+Here the first number is the symbol's value (sometimes referred to as
+its address).  The next field is actually a set of characters and
+spaces indicating the flag bits that are set on the symbol.  These
+characters are described below.  Next is the section with which the
+symbol is associated or \fI*ABS*\fR if the section is absolute (ie
+not connected with any section), or \fI*UND*\fR if the section is
+referenced in the file being dumped, but not defined there.
+.Sp
+After the section name comes another field, a number, which for common
+symbols is the alignment and for other symbol is the size.  Finally
+the symbol's name is displayed.
+.Sp
+The flag characters are divided into 7 groups as follows:
+.RS 4
+.ie n .IP """l""" 4
+.el .IP "\f(CWl\fR" 4
+.IX Item "l"
+.PD 0
+.ie n .IP """g""" 4
+.el .IP "\f(CWg\fR" 4
+.IX Item "g"
+.ie n .IP """u""" 4
+.el .IP "\f(CWu\fR" 4
+.IX Item "u"
+.ie n .IP """!""" 4
+.el .IP "\f(CW!\fR" 4
+.IX Item "!"
+.PD
+The symbol is a local (l), global (g), unique global (u), neither
+global nor local (a space) or both global and local (!).  A
+symbol can be neither local or global for a variety of reasons, e.g.,
+because it is used for debugging, but it is probably an indication of
+a bug if it is ever both local and global.  Unique global symbols are
+a \s-1GNU\s0 extension to the standard set of \s-1ELF\s0 symbol bindings.  For such
+a symbol the dynamic linker will make sure that in the entire process
+there is just one symbol with this name and type in use.
+.ie n .IP """w""" 4
+.el .IP "\f(CWw\fR" 4
+.IX Item "w"
+The symbol is weak (w) or strong (a space).
+.ie n .IP """C""" 4
+.el .IP "\f(CWC\fR" 4
+.IX Item "C"
+The symbol denotes a constructor (C) or an ordinary symbol (a space).
+.ie n .IP """W""" 4
+.el .IP "\f(CWW\fR" 4
+.IX Item "W"
+The symbol is a warning (W) or a normal symbol (a space).  A warning
+symbol's name is a message to be displayed if the symbol following the
+warning symbol is ever referenced.
+.ie n .IP """I""" 4
+.el .IP "\f(CWI\fR" 4
+.IX Item "I"
+.PD 0
+.ie n .IP """i""" 4
+.el .IP "\f(CWi\fR" 4
+.IX Item "i"
+.PD
+The symbol is an indirect reference to another symbol (I), a function
+to be evaluated during reloc processing (i) or a normal symbol (a
+space).
+.ie n .IP """d""" 4
+.el .IP "\f(CWd\fR" 4
+.IX Item "d"
+.PD 0
+.ie n .IP """D""" 4
+.el .IP "\f(CWD\fR" 4
+.IX Item "D"
+.PD
+The symbol is a debugging symbol (d) or a dynamic symbol (D) or a
+normal symbol (a space).
+.ie n .IP """F""" 4
+.el .IP "\f(CWF\fR" 4
+.IX Item "F"
+.PD 0
+.ie n .IP """f""" 4
+.el .IP "\f(CWf\fR" 4
+.IX Item "f"
+.ie n .IP """O""" 4
+.el .IP "\f(CWO\fR" 4
+.IX Item "O"
+.PD
+The symbol is the name of a function (F) or a file (f) or an object
+(O) or just a normal symbol (a space).
+.RE
+.RS 4
+.RE
+.IP "\fB\-T\fR" 4
+.IX Item "-T"
+.PD 0
+.IP "\fB\-\-dynamic\-syms\fR" 4
+.IX Item "--dynamic-syms"
+.PD
+Print the dynamic symbol table entries of the file.  This is only
+meaningful for dynamic objects, such as certain types of shared
+libraries.  This is similar to the information provided by the \fBnm\fR
+program when given the \fB\-D\fR (\fB\-\-dynamic\fR) option.
+.Sp
+The output format is similar to that produced by the \fB\-\-syms\fR
+option, except that an extra field is inserted before the symbol's
+name, giving the version information associated with the symbol.
+If the version is the default version to be used when resolving
+unversioned references to the symbol then it's displayed as is,
+otherwise it's put into parentheses.
+.IP "\fB\-\-special\-syms\fR" 4
+.IX Item "--special-syms"
+When displaying symbols include those which the target considers to be
+special in some way and which would not normally be of interest to the
+user.
+.IP "\fB\-U\fR \fI[d|i|l|e|x|h]\fR" 4
+.IX Item "-U [d|i|l|e|x|h]"
+.PD 0
+.IP "\fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR" 4
+.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
+.PD
+Controls the display of \s-1UTF\-8\s0 encoded multibyte characters in strings.
+The default (\fB\-\-unicode=default\fR) is to give them no special
+treatment.  The \fB\-\-unicode=locale\fR option displays the sequence
+in the current locale, which may or may not support them.  The options
+\&\fB\-\-unicode=hex\fR and \fB\-\-unicode=invalid\fR display them as
+hex byte sequences enclosed by either angle brackets or curly braces.
+.Sp
+The \fB\-\-unicode=escape\fR option displays them as escape sequences
+(\fI\euxxxx\fR) and the \fB\-\-unicode=highlight\fR option displays
+them as escape sequences highlighted in red (if supported by the
+output device).  The colouring is intended to draw attention to the
+presence of unicode sequences where they might not be expected.
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Print the version number of \fBobjdump\fR and exit.
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.IP "\fB\-\-all\-headers\fR" 4
+.IX Item "--all-headers"
+.PD
+Display all available header information, including the symbol table and
+relocation entries.  Using \fB\-x\fR is equivalent to specifying all of
+\&\fB\-a \-f \-h \-p \-r \-t\fR.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+.PD 0
+.IP "\fB\-\-wide\fR" 4
+.IX Item "--wide"
+.PD
+Format some lines for output devices that have more than 80 columns.
+Also do not truncate symbol names when they are displayed.
+.IP "\fB\-z\fR" 4
+.IX Item "-z"
+.PD 0
+.IP "\fB\-\-disassemble\-zeroes\fR" 4
+.IX Item "--disassemble-zeroes"
+.PD
+Normally the disassembly output will skip blocks of zeroes.  This
+option directs the disassembler to disassemble those blocks, just like
+any other data.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBnm\fR\|(1), \fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/od.1 b/upstream/mageia-cauldron/man1/od.1
new file mode 100644
index 00000000..741b43cf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/od.1
@@ -0,0 +1,169 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH OD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+od \- dump files in octal and other formats
+.SH SYNOPSIS
+.B od
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.br
+.B od
+[\fI\,-abcdfilosx\/\fR]... [\fI\,FILE\/\fR] [[\fI\,+\/\fR]\fI\,OFFSET\/\fR[\fI\,.\/\fR][\fI\,b\/\fR]]
+.br
+.B od
+\fI\,--traditional \/\fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR] [[\fI\,+\/\fR]\fI\,OFFSET\/\fR[\fI\,.\/\fR][\fI\,b\/\fR] [\fI\,+\/\fR][\fI\,LABEL\/\fR][\fI\,.\/\fR][\fI\,b\/\fR]]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write an unambiguous representation, octal bytes by default,
+of FILE to standard output.  With more than one FILE argument,
+concatenate them in the listed order to form the input.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+If first and second call formats both apply, the second format is assumed
+if the last operand begins with + or (if there are 2 operands) a digit.
+An OFFSET operand means \fB\-j\fR OFFSET.  LABEL is the pseudo\-address
+at first byte printed, incremented when dump is progressing.
+For OFFSET and LABEL, a 0x or 0X prefix indicates hexadecimal;
+suffixes may be . for octal and b for multiply by 512.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-A\fR, \fB\-\-address\-radix\fR=\fI\,RADIX\/\fR
+output format for file offsets; RADIX is one
+of [doxn], for Decimal, Octal, Hex or None
+.TP
+\fB\-\-endian=\fR{big|little}
+swap input bytes according the specified order
+.TP
+\fB\-j\fR, \fB\-\-skip\-bytes\fR=\fI\,BYTES\/\fR
+skip BYTES input bytes first
+.TP
+\fB\-N\fR, \fB\-\-read\-bytes\fR=\fI\,BYTES\/\fR
+limit dump to BYTES input bytes
+.TP
+\fB\-S\fR BYTES, \fB\-\-strings\fR[=\fI\,BYTES\/\fR]
+output strings of at least BYTES graphic chars;
+3 is implied when BYTES is not specified
+.TP
+\fB\-t\fR, \fB\-\-format\fR=\fI\,TYPE\/\fR
+select output format or formats
+.TP
+\fB\-v\fR, \fB\-\-output\-duplicates\fR
+do not use * to mark line suppression
+.TP
+\fB\-w[BYTES]\fR, \fB\-\-width\fR[=\fI\,BYTES\/\fR]
+output BYTES bytes per output line;
+32 is implied when BYTES is not specified
+.TP
+\fB\-\-traditional\fR
+accept arguments in third form above
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SS "Traditional format specifications may be intermixed; they accumulate:"
+.TP
+\fB\-a\fR
+same as \fB\-t\fR a,  select named characters, ignoring high\-order bit
+.TP
+\fB\-b\fR
+same as \fB\-t\fR o1, select octal bytes
+.TP
+\fB\-c\fR
+same as \fB\-t\fR c,  select printable characters or backslash escapes
+.TP
+\fB\-d\fR
+same as \fB\-t\fR u2, select unsigned decimal 2\-byte units
+.TP
+\fB\-f\fR
+same as \fB\-t\fR fF, select floats
+.TP
+\fB\-i\fR
+same as \fB\-t\fR dI, select decimal ints
+.TP
+\fB\-l\fR
+same as \fB\-t\fR dL, select decimal longs
+.TP
+\fB\-o\fR
+same as \fB\-t\fR o2, select octal 2\-byte units
+.TP
+\fB\-s\fR
+same as \fB\-t\fR d2, select decimal 2\-byte units
+.TP
+\fB\-x\fR
+same as \fB\-t\fR x2, select hexadecimal 2\-byte units
+.SS "TYPE is made up of one or more of these specifications:"
+.TP
+a
+named character, ignoring high\-order bit
+.TP
+c
+printable character or backslash escape
+.TP
+d[SIZE]
+signed decimal, SIZE bytes per integer
+.TP
+f[SIZE]
+floating point, SIZE bytes per float
+.TP
+o[SIZE]
+octal, SIZE bytes per integer
+.TP
+u[SIZE]
+unsigned decimal, SIZE bytes per integer
+.TP
+x[SIZE]
+hexadecimal, SIZE bytes per integer
+.PP
+SIZE is a number.  For TYPE in [doux], SIZE may also be C for
+sizeof(char), S for sizeof(short), I for sizeof(int) or L for
+sizeof(long).  If TYPE is f, SIZE may also be F for sizeof(float), D
+for sizeof(double) or L for sizeof(long double).
+.PP
+Adding a z suffix to any type displays printable characters at the end of
+each output line.
+.SS "BYTES is hex with 0x or 0X prefix, and may have a multiplier suffix:"
+.TP
+b
+512
+.TP
+KB
+1000
+.TP
+K
+1024
+.TP
+MB
+1000*1000
+.TP
+M
+1024*1024
+.PP
+and so on for G, T, P, E, Z, Y.
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.SH EXAMPLES
+.TP
+.B od -A x -t x1z -v
+Display hexdump format output
+.TP
+.B od -A o -t oS -w16
+The default output format used by od
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/od>
+.br
+or available locally via: info \(aq(coreutils) od invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/ogg123.1 b/upstream/mageia-cauldron/man1/ogg123.1
new file mode 100644
index 00000000..59e69993
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ogg123.1
@@ -0,0 +1,436 @@
+.\" Process this file with
+.\" groff -man -Tascii ogg123.1
+.\"
+.TH ogg123 1 "2010 March 24" "Xiph.Org Foundation" "Vorbis Tools"
+
+.SH NAME
+ogg123 \- plays Ogg, and FLAC files
+
+.SH SYNOPSIS
+.B ogg123 
+[
+.B -vqrzZVh
+] [
+.B -k
+.I seconds 
+] [
+.B -x
+.I nth
+] [
+.B -y
+.I ntimes
+] [
+.B -b
+.I buffer_size 
+] [
+.B -d
+.I driver 
+[
+.B -o
+.I option:value
+] 
+[
+.B -f
+.I filename
+] ]
+.I file
+.B ...
+|
+.I directory
+.B ...
+|
+.I URL
+.B ...
+
+.SH DESCRIPTION
+.B ogg123
+reads Ogg/Vorbis, Ogg/Speex, Ogg/Opus, Ogg/FLAC, and native FLAC audio files
+and decodes them to the devices specified on the command line.  By default,
+.B ogg123
+writes to the standard sound device, but output can be sent to any
+number of devices.  Files can be read from the file system, or URLs
+can be streamed via HTTP.  If a directory is given, all of the files in
+it or its subdirectories will be played.
+
+.SH OPTIONS
+.IP "--audio-buffer n"
+Use an output audio buffer of approximately 'n' kilobytes.
+.IP "-@ playlist, --list playlist"
+Play all of the files named in the file 'playlist'.  The playlist should have
+one filename, directory name, or URL per line.  Blank lines are permitted.
+Directories will be treated in the same way as on the command line.
+.IP "-b n, --buffer n"
+Use an input buffer of approximately 'n' kilobytes.  HTTP-only option.
+.IP "-p n, --prebuffer n"
+Prebuffer 'n' percent of the input buffer.  Playback won't begin until
+this prebuffer is complete.  HTTP-only option.
+.IP "-d device, --device device"
+Specify output device.  See
+.B DEVICES
+section for a list of devices.  Any number of devices may be specified.
+.IP "-f filename, --file filename"
+Specify output file for a file device previously specified with
+--device.  The filename "-" writes to standard
+out.  If the file already exists,
+.B ogg123
+will overwrite it.
+.IP "-h, --help"
+Show command help.
+.IP "-k n, --skip n"
+Skip the first 'n' seconds.  'n' may also be in minutes:seconds or 
+hours:minutes:seconds form.
+.IP "-K n, --end n"
+Stops playing 'n' seconds from the start of the stream.  'n' may also have the
+same format as used in the
+.I --skip
+option.
+.IP "-o option[:value], --device-option option[:value]"
+Sets the option
+.I option
+to 
+.I value
+for the preceding device.  See
+.B DEVICES
+for a list of valid options for each device.
+.IP "-q, --quiet"
+Quiet mode.  No messages are displayed.
+.IP "-V, --version"
+Display version information.
+.IP "-v, --verbose"
+Increase verbosity.
+.IP "-x n, --nth"
+Play every 'n'th decoded block.  Has the effect of playing audio at 'n' times
+faster than normal speed.
+.IP "-y n, --ntimes"
+Repeat every played block 'n' times.  Has the effect of playing audio 'n'
+times slower than normal speed.  May be with -x for interesting fractional
+speeds.
+.IP "-r, --repeat"
+Repeat playlist indefinitely.
+.IP "-z, --shuffle"
+Play files in pseudo-random order.
+.IP "-Z, --random"
+Play files in pseudo-random order forever.
+
+.SH DEVICES
+
+.B ogg123
+supports a variety of audio output devices through libao.  Only those
+devices supported by the target platform will be available.  The
+.B -f
+option may only be used with devices that write to files.
+
+Options supported by all devices:
+.RS
+.IP debug
+Turn on debugging output [if any] for a chosen driver.
+.IP matrix:value
+Force a specific output channel ordering for a given device.  
+.I value
+is a comma 
+separated list of AO style channel names, eg, L,R,C,LFE,BL,BR,SL,SR.
+.IP verbose
+Turn on verbose output for a chosen driver. the -v option will also set the 
+driver verbose option.
+.IP quiet
+Force chosen driver to be completely silent.  Even errors will not produce any 
+output. -q will also set the driver quiet option.
+.RE
+
+.B
+.IP aixs
+AIX live output driver. Options:
+.RS
+.IP dev:value
+Set AIX output device to
+.I value
+.RE
+
+.B
+.IP alsa
+Advanced Linux Sound Architecture live output driver. Options:
+.RS
+.IP buffer_time:value
+Override the default hardware buffer size (in milliseconds).
+.IP dev:value
+ALSA device label to use. Examples include "hw:0" for the first soundcard 
+and "hw:1" for the second.  The alsa driver normally chooses one of 
+"surround71", 
+"surround51", 
+"surround40" or 
+"default" 
+automatically depending on number of output channels.  For more information,
+see http://alsa.opensrc.org/ALSA+device+labels
+.IP period_time:value
+Override the default hardware period size (in microseconds).
+.IP period_time:value
+Override the default hardware period size (in microseconds).
+.IP use_mmap:value
+.I value
+is set to "yes" or "no" to override the compiled-in default to use or not use 
+mmap device access.  In the past, some buggy alsa drivers have behaved better when
+not using mmap access at the penalty of slightly higher CPU usage.
+.RE
+
+.B
+.IP arts
+aRts Sound Daemon live output driver. Options:
+.RS
+.IP multi:value
+.I value
+is set to "yes" or "no" to allow opening the aRts playback device for multiply
+concurrent playback.  Although the driver works properly in multi mode, it is 
+known to occasionally crash the aRts server itself.  Default behavior is "no".
+.RE
+
+.B
+.IP au
+Sun audio file output.  Writes the audio samples in AU format.  The AU
+format supports writing to unseekable files like standard out.  In
+such circumstances, the AU header will specify the sample format, but
+not the length of the recording.
+
+.B
+.IP esd
+Enlightened Sound Daemon live output. Options:
+.RS
+.IP host:value
+.I value
+specifies the hostname where esd is running.  This can include a port number
+after a colon, as in "whizbang.com:555".  (Default = localhost)
+.IP client_name:value
+Sets the client name for the new audio stream. Defaults to "libao client".
+.RE
+
+.B
+.IP irix
+IRIX live output audio driver.
+
+.B
+.IP macosx
+MacOS X 'AUHAL' live output driver.  This driver supports MacOS X
+10.5 and later (10.4 and earlier uses an earlier, incompatible
+interface). Options:
+.RS
+.IP buffer_time:value
+Set the hardware buffer size to the equivalent of
+.I value
+milliseconds.
+.RE
+
+.B
+.IP nas
+Network Audio Server live output driver. Options:
+.RS
+.IP buf_size:value
+Set size of audio buffer on server in bytes.
+.IP host:value
+Set location of NAS server; See nas(1) for format. 
+.RE
+
+.B
+.IP null
+Null driver.  All audio data is discarded.  (Note: Audio data is not
+written to 
+.B /dev/null
+!)  You could use this driver to test raw decoding speed without
+output overhead. 
+
+.B
+.IP oss
+Open Sound System driver for Linux and FreeBSD, versions 2, 3 and 4. Options:
+.RS
+.IP dsp:value
+DSP device for soundcard.  Defaults to  
+.B /dev/dsp.
+.RE
+
+.B
+.IP pulse
+Pulseaudio live audio sound driver. Options:
+.RS
+.IP server:value
+Specifies location of remote or alternate Pulseaudio server.
+.IP sink:value
+Specifies a non-default Pulseaudio sink for audio stream.
+.RE
+
+.B
+.IP raw
+Raw file output.  Writes raw audio samples to a file. Options:
+.RS
+.IP byteorder:value
+Chooses big endian ("big"), little endian ("little"), or native ("native") byte order.  
+Default is native order.
+.RE
+
+.B
+.IP roar
+RoarAudio Daemon live output driver. Options:
+.RS
+.IP "server:value, host:value"
+Specifies location of remote RoarAudio server to use.
+.IP "id:value, dev:value"
+Specifies a non-default mixer within a RoarAudio server for audio stream.
+.IP role:value
+Sets the role setting for the audio stream.
+.IP client_name:value
+Sets the client name for the new audio stream. Defaults to "libao client".
+.RE
+
+.B
+.IP sndio
+OpenBSD SNDIO live output driver. Options:
+.RS
+.IP dev:value
+Specifies audio device to use for playback.
+.RE
+
+.B
+.IP sun
+Sun Audio live output driver for NetBSD, OpenBSD, and Solaris. Options:
+.RS
+.IP dev:value
+Audio device for soundcard.  Defaults to  
+.B /dev/audio.
+.RE
+
+
+.B
+.IP wav
+WAV file output.  Writes the sound data to disk in uncompressed form.
+If multiple files are played, all of them will be concatenated into
+the same WAV file.  WAV files cannot be written to unseekable files,
+such as standard out.  Use the AU format instead.
+
+.B
+.IP wmm
+Windows MultiMedia live output driver for Win98 and later. Options:
+.RS
+.IP dev:value
+Selects audio device to use for playback by device name.
+.IP id:value
+Selects audio device to use for playback by device id (card number).
+.RE
+
+.SH EXAMPLES
+
+The
+.B ogg123
+command line is fairly flexible, perhaps confusingly so.  Here are
+some sample command lines and an explanation of what they do.
+.PP
+
+Play on the default soundcard:
+.RS
+.B ogg123 test.ogg
+.RE
+.PP
+
+Play all of the files in the directory ~/music and its subdirectories.
+.RS
+.B ogg123 ~/music
+.RE
+.PP
+
+Play a file using the OSS driver:
+.RS
+.B ogg123 -d oss test.ogg
+.RE
+.PP
+
+Pass the "dsp" option to the OSS driver: 
+.RS
+.B ogg123 -d oss -o dsp:/dev/mydsp 
+.RE
+.PP
+
+Use the ESD driver
+.RS
+.B ogg123 -d esd test.ogg
+.RE
+.PP
+
+Use the WAV driver with the output file, "test.wav":
+.RS
+.B ogg123 -d wav -f test.wav test.ogg
+.RE
+.PP
+
+Listen to a file while you write it to a WAV file:
+.RS
+.B ogg123 -d oss -d wav -f test.wav test.ogg
+.RE
+.PP
+
+Note that options apply to the device declared to the left:
+.RS
+.B ogg123 -d oss -o dsp:/dev/mydsp -d raw -f test2.raw -o byteorder:big test.ogg
+.RE
+.PP
+
+Stress test your harddrive:
+.RS
+.B ogg123 -d oss -d wav -f 1.wav -d wav -f 2.wav -d wav -f 3.wav -d wav -f 4.wav -d wav -f 5.wav  test.ogg
+.RE
+.PP
+
+Create an echo effect with esd and a slow computer:
+.RS
+.B ogg123 -d esd -d esd test.ogg
+.RE
+.PP
+
+.SH INTERRUPT
+You can abort
+.B ogg123
+at any time by pressing Ctrl-C.  If you are playing multiple
+files, this will stop the current file and begin playing the
+next one.  If you want to abort playing immediately instead
+of skipping to the next file, press Ctrl-C within the first
+second of the playback of a new file.
+.P
+Note that the result of pressing Ctrl-C might not be audible
+immediately, due to audio data buffering in the audio device.
+This delay is system dependent, but it is usually not more
+than one or two seconds.
+
+.SH FILES
+
+.TP
+/etc/libao.conf
+Can be used to set the default output device for all libao programs.
+
+.TP
+~/.libao
+Per-user config file to override the system wide output device settings.
+.PP
+
+.SH BUGS
+
+Piped WAV files may cause strange behavior in other programs.  This is
+because WAV files store the data length in the header.  However, the
+output driver does not know the length when it writes the header, and
+there is no value that means "length unknown".  Use the raw or au
+output driver if you need to use ogg123 in a pipe.
+
+.SH AUTHORS
+
+.TP
+Program Authors:
+.br
+Kenneth Arnold <kcarnold-xiph@arnoldnet.net>
+.br
+Stan Seibert <volsung@xiph.org>
+.br
+
+.TP
+Manpage Author:
+.br
+Stan Seibert <volsung@xiph.org>
+
+.SH "SEE ALSO"
+
+.PP
+\fBlibao.conf\fR(5), \fBoggenc\fR(1), \fBvorbiscomment\fR(1), \fBogginfo\fR(1)
+
diff --git a/upstream/mageia-cauldron/man1/oggdec.1 b/upstream/mageia-cauldron/man1/oggdec.1
new file mode 100644
index 00000000..c4169730
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/oggdec.1
@@ -0,0 +1,120 @@
+.TH "oggdec" "1" "2008 September 9" "Xiph.Org Foundation" "Vorbis Tools"
+
+.SH "NAME"
+oggdec - simple decoder, Ogg Vorbis file to PCM audio file (Wave or RAW).
+
+.SH "SYNOPSIS"
+.B oggdec
+[
+.B -Qhv
+] [
+.B -b bits_per_sample
+] [
+.B -e endianness
+] [
+.B -R
+] [
+.B -s signedness
+] [
+.B -o outputfile
+] 
+.B file ...
+
+.SH "DESCRIPTION"
+
+.B oggdec
+decodes Ogg Vorbis files into PCM-encoded ("uncompressed") audio files, either Wave or RAW format.
+
+For each input file, 
+.B oggdec
+writes to a filename based on the input filename, but with the extension changed to ".wav" or ".raw" as appropriate.
+
+If the input file is specified as
+.B "-"
+, then 
+.B oggdec
+will read from stdin, and write to stdout unless an output filename is specified. Likewise, an output filename of
+.B -
+will cause output to be to stdout.
+
+Writing Wave format to stdout is a bad idea.  Wave requires a seekable medium for the header to be rewritten after all the data is written out; stdout is not seekable.
+
+.SH "OPTIONS"
+.IP "-Q, --quiet"
+Suppresses program output.
+.IP "-h, --help"
+Print help message.
+.IP "-V, --version"
+Display version information.
+.IP "-b n, --bits=n"
+Bits per sample.  Valid values are 8 or 16.
+.IP "-e n, --endian=n"
+Set endianness for 16-bit output.  0 (default) is little-endian (Intel byte order).  1 is big-endian (sane byte order).
+.IP "-R, --raw"
+Output in raw format.  If not specified, writes Wave file (RIFF headers).
+.IP "-s n, --sign=n"
+Set signedness for output.  0 for unsigned, 1 (default) for signed.
+.IP "-o filename, --output=filename"
+Write output to specified filename.  This option is only valid if one input [file] is specified, or if raw mode is used.
+
+.SH "EXAMPLES"
+Decode a file 
+.B enabler.ogg
+to 
+.B enabler.wav
+ as little-endian signed 16-bit (default options):
+.RS
+oggdec enabler.ogg
+.RE
+
+Decode a file 
+.B enabler.ogg
+to 
+.B enabler.raw
+as headerless little-endian signed 16-bit:
+.RS
+oggdec --raw enabler.ogg
+.RE
+
+Decode 
+.B enabler.ogg
+to 
+.B enabler.crazymonkey
+as unsigned 8-bit:
+.RS
+oggdec -b 8 -s 0 -o enabler.crazymonkey enabler.ogg
+.RE
+
+Decode 
+.B enabler.ogg
+to 
+.B enabler.raw
+as big-endian signed 16-bit (any of the following):
+.RS
+oggdec -R -e 1 -b 16 enabler.ogg
+.RE
+.RS
+oggdec -R -e 1 -b 16 -o enabler.raw - < enabler.ogg
+.RE
+.RS
+oggdec -R -e 1 -b 16 - < enabler.ogg > enabler.raw
+.RE
+
+Mass decoding (foo.ogg to foo.wav, bar.ogg to bar.wav, quux.ogg to quux.wav, etc.):
+.RS
+oggdec *.ogg
+.RE
+
+.SH "AUTHORS"
+.SS "Program Authors"
+Michael Smith <msmith@xiph.org>
+.SS "Manpage Authors"
+
+.br
+
+Frederick Lee <phaethon@linux.ucla.edu>, assisted by a few million monkeys armed with keyboards in irc://irc.openprojects.net/#vorbis
+
+.SH "SEE ALSO"
+
+.PP
+\fBogg123\fR(1), \fBoggenc\fR(1), \fBvorbiscomment\fR(1), \fBflac\fR(1), \fBspeexdec\fR(1)
diff --git a/upstream/mageia-cauldron/man1/oggenc.1 b/upstream/mageia-cauldron/man1/oggenc.1
new file mode 100644
index 00000000..817556f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/oggenc.1
@@ -0,0 +1,423 @@
+.\" Process this file with
+.\" groff -man -Tascii oggenc.1
+.\"
+.TH oggenc 1 "2008 October 05" "Xiph.Org Foundation" "Vorbis Tools"
+
+.SH NAME
+oggenc \- encode audio into the Ogg Vorbis format
+
+.SH SYNOPSIS
+.B oggenc
+[
+.B -hrQ
+]
+[
+.B -B
+.I raw input sample size
+]
+[
+.B -C
+.I raw input number of channels
+]
+[
+.B -R
+.I raw input samplerate
+]
+[
+.B -b
+.I nominal bitrate
+]
+[
+.B -m
+.I minimum bitrate
+]
+[
+.B -M
+.I maximum bitrate
+]
+[
+.B -q
+.I quality
+]
+[
+.B --resample 
+.I frequency
+]
+[
+.B --downmix 
+]
+[
+.B -s
+.I serial
+]
+[
+.B -o
+.I output_file
+]
+[
+.B -n
+.I pattern
+]
+[
+.B -c
+.I extra_comment
+]
+[
+.B -a
+.I artist
+]
+[
+.B -t
+.I title
+]
+[
+.B -l
+.I album
+]
+[
+.B -G
+.I genre
+]
+[
+.B -L
+.I lyrics file
+]
+[
+.B -Y
+.I language-string
+]
+.I input_files \fR...
+
+.SH DESCRIPTION
+.B oggenc
+reads audio data in either raw, Wave, or AIFF format and encodes it into an
+Ogg Vorbis stream.
+.B oggenc
+may also read audio data from FLAC and Ogg FLAC files depending upon compile-time options.  If the input file "-" is specified, audio data is
+read from
+.I stdin
+and the Vorbis stream is written to
+.I stdout
+unless the
+.B -o
+option is used to redirect the output.  By default, disk files are
+output to Ogg Vorbis files of the same name, with the extension
+changed to ".ogg" or ".oga".  This naming convention can be overridden
+by the
+.B -o
+option (in the case of one file) or the
+.B -n
+option (in the case of several files). Finally, if none of these
+are available, the output filename will be the input filename with the
+extension (that part after the final dot) replaced with ogg, so file.wav
+will become file.ogg.
+.br
+Optionally, lyrics may be embedded in the Ogg file, if Kate support was compiled in.
+.br
+Note that some old players mail fail to play streams with more than a single Vorbis stream
+(the so called "Vorbis I" simple profile).
+
+.SH OPTIONS
+.IP "-h, --help"
+Show command help.
+.IP "-V, --version"
+Show the version number.
+.IP "-r, --raw"
+Assume input data is raw little-endian audio data with no
+header information. If other options are not specified, defaults to 44.1kHz
+stereo 16 bit. See next three options for how to change this.
+.IP "-B n, --raw-bits=n"
+Sets raw mode input sample size in bits. Default is 16.
+.IP "-C n, --raw-chan=n"
+Sets raw mode input number of channels. Default is 2.
+.IP "-R n, --raw-rate=n"
+Sets raw mode input samplerate. Default is 44100.
+.IP "--raw-endianness n
+Sets raw mode endianness to big endian (1) or little endian (0). Default is
+little endian.
+.IP "--utf8 \ \ \ \ \ \ \ "
+Informs oggenc that the Vorbis Comments are already encoded as UTF-8.
+Useful in situations where the shell is using some other encoding.
+.IP "-k, --skeleton"
+Add a Skeleton bitstream.  Important if the output Ogg is intended to carry
+multiplexed or chained streams.  Output file uses .oga as file extension.
+.IP "--ignorelength"
+Support for Wave files over 4 GB and stdin data streams.
+.IP "-Q, --quiet"
+Quiet mode.  No messages are displayed.
+.IP "-b n, --bitrate=n"
+Sets target bitrate to n (in kb/s). The encoder will attempt to encode at approximately this bitrate. By default, this remains a VBR encoding. See the --managed option to force a managed bitrate encoding at the selected bitrate.
+.IP "-m n, --min-bitrate=n"
+Sets minimum bitrate to n (in kb/s). Enables bitrate management mode (see --managed).
+.IP "-M n, --max-bitrate=n"
+Sets maximum bitrate to n (in kb/s). Enables bitrate management mode (see --managed).
+.IP "--managed"
+Set bitrate management mode. This turns off the normal VBR encoding, but allows
+hard or soft bitrate constraints to be enforced by the encoder. This mode is
+much slower, and may also be lower quality. It is primarily useful for creating
+files for streaming.
+.IP "-q n, --quality=n"
+Sets encoding quality to n, between -1 (very low) and 10 (very high). This is the default mode of operation, with a default quality level of 3. Fractional quality levels such as 2.5 are permitted. Using this option allows the encoder to select an appropriate bitrate based on your desired quality level.
+.IP "--resample n"
+Resample input to the given sample rate (in Hz) before encoding. Primarily
+useful for downsampling for lower-bitrate encoding.
+.IP "--downmix"
+Downmix input from stereo to mono (has no effect on non-stereo streams). Useful
+for lower-bitrate encoding.
+.IP "--advanced-encode-option optionname=value"
+Sets an advanced option. See the Advanced Options section for details.
+.IP "-s, --serial"
+Forces a specific serial number in the output stream. This is primarily useful for testing.
+.IP "--discard-comments"
+Prevents comments in FLAC and Ogg FLAC files from being copied to the
+output Ogg Vorbis file.
+.IP "-o output_file, --output=output_file"
+Write the Ogg Vorbis stream to
+.I output_file
+(only valid if a single input file is specified).
+
+.IP "-n pattern, --names=pattern"
+Produce filenames as this string, with %g, %a, %l, %n, %t, %d replaced by
+genre, artist, album, track number, title, and date, respectively (see below
+for specifying these). Also, %% gives a literal %.
+.IP "-X, --name-remove=s"
+Remove the specified characters from parameters to the -n format string. This is useful to ensure legal filenames are generated.
+.IP "-P, --name-replace=s"
+Replace characters removed by --name-remove with the characters specified. If this string is shorter than the --name-remove list, or is not specified, the extra characters are just removed. The default settings for this option, and the -X option above, are platform specific (and chosen to ensure legal filenames are generated for each platform).
+
+.IP "-c comment, --comment comment"
+Add the string
+.I comment
+as an extra comment.  This may be used multiple times, and all
+instances will be added to each of the input files specified. The argument
+should be in the form "tag=value".
+
+.IP "-a artist, --artist artist"
+Set the artist comment field in the comments to
+.I artist.
+
+.IP "-G genre, --genre genre"
+Set the genre comment field in the comments to
+.I genre.
+
+.IP "-d date, --date date"
+Sets the date comment field to the given value. This should be the date of recording.
+
+.IP "-N n, --tracknum n"
+Sets the track number comment field to the given value.
+
+.IP "-t title, --title title"
+Set the track title comment field to
+.I title.
+
+.IP "-l album, --album album"
+Set the album comment field to
+.I album.
+
+.IP "-L filename, --lyrics filename"
+Loads lyrics from
+.I filename
+and encodes them into a Kate stream multiplexed with the Vorbis stream.
+Lyrics may be in LRC or SRT format, and should be encoded in UTF-8 or
+plain ASCII. Other encodings may be converted using tools such as iconv
+or recode. Alternatively, the same system as for comments will be used
+for conversion between encodings.
+So called "enhanced LRC" files are supported, and a simple karaoke style
+change will be saved with the lyrics. For more complex karaoke setups,
+.B kateenc(1)
+should be used instead.
+When embedding lyrics, the default output file extension is ".oga".
+Note that adding lyrics to a stream will automatically enable Skeleton
+(see the \fB-k\fR option for more information about Skeleton).
+
+.IP "-Y language-string, --lyrics-language language-string"
+Sets the language for the corresponding lyrics file to
+.I language-string.
+This should be an ISO 639-1 language code (eg, "en"), or a RFC 3066 language tag
+(eg, "en_US"),
+.B not
+a free form language name. Players will typically recognize this standard tag
+and display the language name in your own language.
+Note that the maximum length of this tag is 15 characters.
+.PP
+
+Note that the \fB-a\fR, \fB-t\fR, \fB-l\fR, \fB-L\fR, and \fB-Y\fR  options
+can be given multiple times.  They will be applied, one to each file, in the
+order given.  If there are fewer album, title, or artist comments given than
+there are input files,
+.B oggenc
+will reuse the final one for the remaining files, and issue a warning
+in the case of repeated titles.
+
+.SH "ADVANCED ENCODER OPTIONS"
+
+Oggenc allows you to set a number of advanced encoder options using the
+.B --advanced-encode-option
+option. These are intended for very advanced users only, and should be
+approached with caution. They may significantly degrade audio quality
+if misused. Not all these options are currently documented.
+
+.IP "lowpass_frequency=N"
+Set the lowpass frequency to N kHz.
+
+.IP "impulse_noisetune=N"
+Set a noise floor bias N (range from -15. to 0.) for impulse blocks.
+A negative bias instructs the encoder to pay special attention to the
+crispness of transients in the encoded audio.  The tradeoff for better
+transient response is a higher bitrate.
+
+.IP "bitrate_hard_max=N"
+Set the allowed bitrate maximum for the encoded file to N kilobits per 
+second.  This bitrate may be exceeded only when there is spare bits
+in the bit reservoir; if the bit reservoir is exhausted, frames will
+be held under this value.  This setting must be used with --managed 
+to have any effect.
+
+.IP "bitrate_hard_min=N"
+Set the allowed bitrate minimum for the encoded file to N kilobits per
+second.  This bitrate may be underrun only when the bit reservoir is
+not full; if the bit reservoir is full, frames will be held over this
+value; if it impossible to add bits constructively, the frame will be
+padded with zeroes.  This setting must be used with --managed to have
+any effect.
+
+.IP "bit_reservoir_bits=N"
+Set the total size of the bit reservoir to N bits; the default size of
+the reservoir is equal to the nominal number of bits coded in one
+second (eg, a nominal 128kbps file will have a bit reservoir of 128000
+bits by default).  This option must be used with --managed to have any
+effect and affects only minimum and maximum bitrate management.
+Average bitrate encoding with no hard bitrate boundaries does not use
+a bit reservoir.
+
+.IP "bit_reservoir_bias=N"
+Set the behavior bias of the bit reservoir (range: 0. to 1.).  When
+set closer to 0, the bitrate manager attempts to hoard bits for future
+use in sudden bitrate increases (biasing toward better transient
+reproduction).  When set closer to 1, the bitrate manager neglects
+transients in favor using bits for homogenous passages.  In the
+middle, the manager uses a balanced approach.  The default setting is \.2, 
+thus biasing slightly toward transient reproduction.
+
+.IP "bitrate_average=N"
+Set the average bitrate for the file to N kilobits per second.  When used
+without hard minimum or maximum limits, this option selects
+reservoirless Average Bit Rate encoding, where the encoder attempts to
+perfectly track a desired bitrate, but imposes no strict momentary
+fluctuation limits.  When used along with a minimum or maximum limit,
+the average bitrate still sets the average overall bitrate of the
+file, but will work within the bounds set by the bit reservoir.  When
+the min, max and average bitrates are identical, oggenc produces
+Constant Bit Rate Vorbis data.
+
+.IP "bitrate_average_damping=N"
+Set the reaction time for the average bitrate tracker to N seconds.
+This number represents the fastest reaction the bitrate tracker is
+allowed to make to hold the bitrate to the selected average.  The
+faster the reaction time, the less momentary fluctuation in the
+bitrate but (generally) the lower quality the audio output.  The
+slower the reaction time, the larger the ABR fluctuations, but
+(generally) the better the audio.  When used along with min or max
+bitrate limits, this option directly affects how deep and how quickly
+the encoder will dip into its bit reservoir; the higher the number,
+the more demand on the bit reservoir.
+
+The setting must be greater than zero and the useful range is
+approximately \.05 to 10.  The default is \.75 seconds.
+
+.IP "disable_coupling"
+Disable use of channel coupling for multichannel encoding.  At present,
+the encoder will normally use channel coupling to further increase
+compression with stereo and 5.1 inputs. This option forces the encoder
+to encode each channel fully independently using neither lossy nor
+lossless coupling. 
+
+.SH EXAMPLES
+
+Simplest version. Produces output as somefile.ogg:
+.RS
+oggenc somefile.wav
+.RE
+.PP
+
+Specifying an output filename:
+.RS
+oggenc somefile.wav -o out.ogg
+.RE
+.PP
+
+Specifying a high-quality encoding averaging 256 kbps (but still VBR):
+.RS
+oggenc infile.wav -b 256 -o out.ogg
+.RE
+.PP
+
+Specifying a maximum and average bitrate, and enforcing these:
+.RS
+oggenc infile.wav --managed -b 128 -M 160 -o out.ogg
+.RE
+.PP
+
+Specifying quality rather than bitrate (to a very high quality mode):
+.RS
+oggenc infile.wav -q 6 -o out.ogg
+.RE
+.PP
+
+Downsampling and downmixing to 11 kHz mono before encoding:
+.RS
+oggenc --resample 11025 --downmix infile.wav -q 1 -o out.ogg
+.RE
+.PP
+
+Adding some info about the track:
+.RS
+oggenc somefile.wav -t "The track title" -a "artist who performed this" -l
+"name of album" -c
+"OTHERFIELD=contents of some other field not explicitly supported"
+.RE
+.PP
+
+Adding embedded lyrics:
+.RS
+oggenc somefile.wav --lyrics lyrics.lrc --lyrics-language en -o out.oga
+.RE
+.PP
+
+This encodes the three files, each with the
+same artist/album tag, but with different title tags on each one. The
+string given as an argument to -n is used to generate filenames, as shown
+in the section above. This example gives filenames
+like "The Tea Party - Touch.ogg":
+.RS
+oggenc -b 192 -a "The Tea Party" -l "Triptych" -t "Touch" track01.wav -t
+"Underground" track02.wav -t "Great Big Lie" track03.wav -n "%a - %t.ogg"
+.RE
+.PP
+
+Encoding from stdin, to stdout (you can also use the various tagging
+options, like -t, -a, -l, etc.):
+.RS
+oggenc -
+.RE
+.PP
+
+.SH AUTHORS
+
+.TP
+Program Author:
+.br
+Michael Smith <msmith@xiph.org>
+
+.TP
+Manpage Author:
+.br
+Stan Seibert <indigo@aztec.asu.edu>
+
+.SH BUGS
+Reading type 3 Wave files (floating point samples) probably doesn't work other than on Intel (or other 32 bit, little endian machines).
+
+.SH "SEE ALSO"
+
+.PP
+\fBvorbiscomment\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBflac\fR(1), \fBspeexenc\fR(1), \fBffmpeg2theora\fR(1), \fBkateenc\fR(1)
diff --git a/upstream/mageia-cauldron/man1/ogginfo.1 b/upstream/mageia-cauldron/man1/ogginfo.1
new file mode 100644
index 00000000..126da20d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ogginfo.1
@@ -0,0 +1,60 @@
+.\" Process this file with
+.\" groff -man -Tascii ogginfo.1
+.\"
+.TH ogginfo 1 "July 10, 2002" "Xiph.Org Foundation" "Vorbis Tools"
+
+.SH NAME
+ogginfo \- gives information about Ogg files, and does extensive validity checking
+
+.SH SYNOPSIS
+.B ogginfo
+[
+.B -q
+] [
+.B -v
+] [
+.B -h
+]
+.I file1.ogg
+.B ...
+.I fileN.ogg
+
+.SH DESCRIPTION
+.B ogginfo
+reads one or more Ogg files and prints information about stream contents 
+(including chained and/or multiplexed streams) to standard output. It will 
+detect (but not correct) a wide range of common defects, with many 
+additional checks specifically for Ogg Vorbis streams.
+
+For all stream types
+.B ogginfo
+will print the filename being processed, the stream serial numbers, and various
+common error conditions.
+
+For
+.B Vorbis
+streams, information including the version used for encoding, the sample rate
+and number of channels, the bitrate and playback length, and the contents of
+the comment header are printed.
+
+Similarly, for
+.B Theora
+streams, basic information about the video is provided, including frame rate, aspect ratio, bitrate, length, and the comment header.
+
+.SH OPTIONS
+.IP -h
+Show a help and usage message.
+.IP -q
+Quiet mode. This may be specified multiple times. Doing so once will remove
+the detailed informative messages, twice will remove warnings as well.
+.IP -v
+Verbose mode. At the current time, this does not do anything.
+
+.SH AUTHORS
+.br
+Michael Smith <msmith@xiph.org>
+
+.SH "SEE ALSO"
+
+.PP
+\fBvorbiscomment\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBoggenc\fR(1)
diff --git a/upstream/mageia-cauldron/man1/oomctl.1 b/upstream/mageia-cauldron/man1/oomctl.1
new file mode 100644
index 00000000..7c672b24
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/oomctl.1
@@ -0,0 +1,70 @@
+'\" t
+.TH "OOMCTL" "1" "" "systemd 255" "oomctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+oomctl \- Analyze the state stored in \fBsystemd\-oomd\fR
+.SH "SYNOPSIS"
+.HP \w'\fBoomctl\fR\ 'u
+\fBoomctl\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+\fBoomctl\fR
+may be used to get information about the various contexts read in by the
+\fBsystemd\fR(1)
+userspace out\-of\-memory (OOM) killer,
+\fBsystemd-oomd\fR(8)\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBdump\fR
+.RS 4
+Show the current state of the cgroups and system contexts stored by
+\fBsystemd\-oomd\fR\&.
+.sp
+Added in version 247\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-oomd.service\fR(8),
+\fBoomd.conf\fR(5)
diff --git a/upstream/mageia-cauldron/man1/openvt.1 b/upstream/mageia-cauldron/man1/openvt.1
new file mode 100644
index 00000000..79bfe3f4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/openvt.1
@@ -0,0 +1,93 @@
+.\" Copyright 1994-95 Jon Tombs (jon@gtex02.us.es, jon@robots.ox.ac.uk)
+.\" May be distributed under the GNU General Public License
+.TH OPENVT 1 "19 Jul 1996" "kbd"
+.SH NAME
+openvt \- start a program on a new virtual terminal (VT).
+.SH SYNOPSIS
+.B openvt
+[\-c vtnumber] [OPTIONS] [\-\-] command
+.SH DESCRIPTION
+.B openvt
+will find the first available VT, and run on it the given
+.B command
+with the given
+.B "command options",
+standard input, output and error are directed to that terminal. The current
+search path ($PATH) is used to find the requested command. If no command is
+specified then the environment variable $SHELL is used.
+.SS OPTIONS
+.TP
+.I "\-c, \-\-console=VTNUMBER"
+Use the given VT number and not the first available. Note you
+must have write access to the supplied VT for this to work.
+.TP
+.I "\-f, \-\-force"
+Force opening a VT without checking whether it is already in use.
+.TP
+.I "\-e, \-\-exec"
+Directly execute the given command, without forking.
+This option is meant for use in
+.IR /etc/inittab .
+.TP
+.I "\-s, \-\-switch"
+Switch to the new VT when starting the command. The VT of the new command
+will be made the new current VT.
+.TP
+.I "\-u, \-\-user"
+Figure out the owner of the current VT, and run login as that user.
+Suitable to be called by init. Shouldn't be used with \fI\-c\fR or \fI\-l\fR.
+.TP
+.I "\-l, \-\-login"
+Make the command a login shell. A \- is prepended to the name of the command
+to be executed.
+.TP
+.I "\-v, \-\-verbose"
+Be a bit more verbose.
+.TP
+.I "\-w, \-\-wait"
+wait for command to complete. If \-w and \-s are used together then
+.B openvt
+will switch back to the controlling terminal when the command completes.
+.TP
+.I "\-V, \-\-version"
+print program version and exit.
+.TP
+.I "\-h, \-\-help"
+show this text and exit.
+.TP
+.I "\-\-"
+end of options to
+.BR openvt .
+.SH NOTE
+If
+.B openvt
+is compiled with a getopt_long() and you wish to set
+options to the command to be run, then you must supply
+the end of options \-\- flag before the command.
+.SH EXAMPLES
+.B openvt
+can be used to start a shell on the next free VT, by using the command:
+.TP
+.I "openvt bash"
+.TP
+
+To start the shell as a login shell, use:
+.TP
+.I "openvt -l bash"
+.TP
+
+To get a long listing you must supply the \-\- separator:
+.TP
+.I "openvt -- ls -l"
+.SH HISTORY
+Earlier,
+.B openvt
+was called
+.BR open .
+It was written by Jon Tombs <jon@gtex02.us.es> or <jon@robots.ox.ac.uk>.
+The \fI\-w\fR idea is from "sam".
+
+.SH "SEE ALSO"
+.BR chvt (1),
+.BR doshell (8),
+.BR login (1)
diff --git a/upstream/mageia-cauldron/man1/palmtopnm.1 b/upstream/mageia-cauldron/man1/palmtopnm.1
new file mode 100644
index 00000000..276591d8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/palmtopnm.1
@@ -0,0 +1,145 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Palmtopnm User Manual" 0 "26 January 2005" "netpbm documentation"
+
+.SH NAME
+palmtopnm - convert a Palm Bitmap to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpalmtopnm\fP
+
+[\fB-verbose\fP]
+
+[\fB-rendition\fP \fIN\fP]
+
+[\fB-showhist\fP]
+
+[\fIpalmfile\fP]
+\fBpalmtopnm\fP
+
+\fB-transparent\fP
+
+[\fB-verbose\fP]
+
+[\fIpalmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpalmtopnm\fP reads a Palm Bitmap as input, from Standard Input or
+\fIpalmfile\fP and produces a PPM image as output.
+.PP
+Alternatively (when you specify \fB-transparent\fP),
+\fBpalmtopnm\fP writes the value of the transparent color in the Palm
+Bitmap to Standard Output.
+.PP
+\fBPalmtopnm\fP can convert Palm Bitmaps with the following features.
+This does not mean that it doesn't handle other features.  These are just
+the ones we found worth mentioning.
+
+.IP \(bu
+Version 0
+.IP \(bu
+Version 1
+.IP \(bu
+Version 2
+.IP \(bu
+Version 3 (new in Netpbm 10.27 (March 2005))
+.IP \(bu
+Scanline compression
+.IP \(bu
+RLE compression
+.IP \(bu
+Packbits compression (new in Netpbm 10.27 (March 2005))
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpalmtopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display various interesting information about the input file and process.
+
+.TP
+\fB-transparent\fP
+If the Palm Bitmap has a transparent color set, 
+\fBpalmtopnm\fP writes the value for that
+color to Standard Output in the form #RRGGBB, where
+RR, GG, and BB are two-digit hexadecimal numbers
+indicating a value in the range 0 through 255.  If no transparent color is set
+in the Bitmap, \fBpalmtopnm\fP writes nothing.  \fBpalmtopnm\fP does not
+generate any output image when you specify \fB-transparent\fP.
+
+.TP
+\fB-rendition N\fP
+Palm Bitmaps may contain several different renditions of the same
+image, with different depths.  By default, \fBpalmtopnm \fP operates
+on the first rendition (rendition number 1) in the image.  This
+switch allows you to operate on a different rendition.  The value must
+be between 1 and the number of renditions in the image, inclusive.
+
+.TP
+\fB-showhist\fP
+This option causes \fBpalmtopnm\fP to 
+write a histogram of colors in the input file to Standard Error.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtopalm" (1)\c
+\&,
+.BR "pamtopdbimg" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+You cannot generate a transparency mask if the Palm Bitmap has a
+transparent color.  However, you can still do this with
+\fBppmcolormask\fP with a Netpbm pipe similar to:
+.PP
+\fBpalmtopnm bitmap.palm | 
+ppmcolormask `palmtopnm -transparent bitmap.palm`\fP
+
+.UN history
+.SH HISTORY
+.PP
+Before Netpbm 10.23 (July 2004), there was a \fB-forceplain\fP
+option.  But that had been redundant for a long time, since the Netpbm 
+common option \fB-plain\fP does the same thing.
+
+.UN authors
+.SH AUTHORS
+
+This program was originally written as Tbmptopnm.c, by Ian Goldberg.
+It was heavily modified by Bill Janssen to add color, compression, and
+transparency function.
+.PP
+Copyright 1995-2001 by Ian Goldberg and Bill Janssen.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/palmtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamaddnoise.1 b/upstream/mageia-cauldron/man1/pamaddnoise.1
new file mode 100644
index 00000000..bd2d217b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamaddnoise.1
@@ -0,0 +1,172 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamaddnoise User Manual" 0 "12 December 2020" "netpbm documentation"
+
+.SH NAME
+
+pamaddnoise - add noise to a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamaddnoise\fP
+{
+[\fB-type\fP \fBgaussian\fP]
+
+[\fB-sigma1\fP \fIvalue\fP]
+
+[\fB-sigma2\fP \fIvalue\fP]
+|
+\fB-type \fP \fBmultiplicative_gaussian\fP
+
+[\fB-mgsigma\fP \fIvalue\fP]
+|
+\fB-type\fP \fBimpulse\fP
+
+[\fB-tolerance\fP \fIratio\fP]
+|
+\fB-type \fP \fBlaplacian\fP
+
+[\fB-lsigma\fP \fIvalue\fP]
+|
+\fB-type \fP \fBpoisson\fP
+
+[\fB-lambda\fP \fIvalue\fP]
+}
+[\fB-seed\fP \fIint\fP]
+
+[\fInetpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamaddnoise\fP adds the specified noise type to a Netpbm image.
+\fBpamaddnoise\fP treats a PPM image as 3 independent planes, not as
+a plane of colors in a color space.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamaddnoise\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-lambda\fP \fIvalue\fP
+This is the expected value of the Poisson distribution for a sample value
+  of mximum intensity.  The expected value for other intensities is
+  proportional; e.g. for half intensity, it is half this value.
+.sp
+This is meaningful only with \fB-type=poisson\fP.
+.sp
+The default value is 12.
+
+.TP
+\fB-lsigma\fP \fIvalue\fP
+Used for laplacian noise only.  The default value is 10.0.
+
+.TP
+\fB-mgsigma\fP \fIvalue\fP
+Used for multiplicative gaussian noise only.  The default value is
+0.5.
+
+.TP
+\fB-seed\fP \fIint\fP
+Used for all noise types.  Set the initial random number generator
+seed value.
+
+.TP
+\fB-sigma1\fP \fIvalue\fP
+Used for gaussian noise only.  The default value is 4.0.
+
+.TP
+\fB-sigma2\fP \fIvalue\fP
+Used for gaussian noise only.  The default value is 20.0.
+
+.TP
+\fB-tolerance\fP \fIratio\fP
+Used for impulse noise only.  The default value is 0.10.  This means
+that 5% of all pixel values will be set to 0 and 5% will be set to
+the maxval
+
+.TP
+\fB-type\fP \fInoise_type\fP
+Select type of noise by name.  The following noise types are
+available: gaussian, multiplicative_gaussian, impulse, laplacian,
+poisson.  Only enough letters to be unique are required for the noise
+type option.  The default noise type is \fBgaussian\fP.
+
+
+.IP \(bu
+\fBgaussian\fP
+.IP \(bu
+\fBmultiplicative_gaussian\fP
+.IP \(bu
+\fBimpulse\fP
+.IP \(bu
+\fBlaplacian\fP
+.IP \(bu
+\fBpoisson\fP
+
+
+
+
+.UN references
+.SH REFERENCES
+
+
+.IP \(bu
+"Adaptive Image Restoration in Signal-Dependent Noise"
+by R. Kasturi Institute for Electronic Science, Texas Tech University,
+1982
+
+.IP \(bu
+"Digital Image Processing Algorithms" by Ioannis Pitas,
+Prentice Hall, 1993 ISBN 0-13-145814-0
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmnoise" (1)\c
+\&,
+.BR "pgmmedian" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamaddnoise\fP was added to Netpbm in Version 10.29 (August 2005).
+It had been distributed by Mike Burns via his own web site before that
+(and continued to be so).
+.PP
+Burns' version, and the one in Netpbm 10.29, was called \fBpnmaddnoise\fP
+and worked only on PNM images.  In Netpbm 10.30, it was converted to handle
+PAM images and renamed to \fBpamaddnoise\fP.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995 by Mike Burns <\fIburns@cac.psu.edu\fP>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamaddnoise.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamaltsat.1 b/upstream/mageia-cauldron/man1/pamaltsat.1
new file mode 100644
index 00000000..8f8442d3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamaltsat.1
@@ -0,0 +1,303 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamaltsat User Manual" 0 "14 September 2018" "netpbm documentation"
+
+.SH NAME
+pamaltsat - increase or decrease the saturation of an image using one of
+several alternative methods.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamaltsat\fP
+[\fB-method\fP \fIname\fP]
+[\fB-strength\fP \fInumber\fP]
+[\fB-linear\fP]
+[\fIinfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamaltsat\fP decreases or increases the saturation of a Netpbm image by
+one of various non-standard (\fIalt\fPernative) methods.
+.PP
+The input is a Netpbm image from Standard Input or a file named by the
+arguments.  The output is a Netpbm image in the same format written to
+Standard Output.
+.PP
+The most conventional way to change the saturation of an image is what
+\fBpambrighten\fP does.
+  
+
+.UN examples
+.SH EXAMPLES
+.PP
+To increase saturation by a factor of 2.1 using the
+logarithmic method:
+
+.nf
+\f(CW
+     pamaltsat -method log -strength 2.1 test.ppm
+\fP
+
+.fi
+.PP
+To convert a color image to grayscale:
+
+.nf
+\f(CW
+    pamaltsat -strength 0 test.ppm
+\fP
+
+.fi
+
+
+.UN saturation_methods
+.SH SATURATION METHODS
+.PP
+The following saturation methods are available.
+
+.SS Logarithmic Method
+.PP
+This saturation model is inspired by the concept of
+.BR "color integrity" (1)\c
+\&,
+which works with color in terms of intensity ratios, where intensity is a 
+value of the
+.UR https://en.wikipedia.org/wiki/Luminosity_function
+luminosity function
+.UE
+\&, rather than brightness, or the numerical value of the sample in
+the image file.  From this viewpoint, it is natural to define the saturation
+of a color as the ratio of maximum and minimum intensities of its primary
+components. In order, however, to make saturation an additive value and to
+endow the \fB-strength\fP parameter with the semantics of a multiplier,
+it is convenient to operate on the logarithm of that ratio.  The addition of
+such saturations acquires physical sense, and multiplication corresponds to
+the raising of intensity to the power of the multiplier.
+.PP
+With this method, \fBpamaltsat\fP raises the intensity of each component
+to the power of the \fBstrength\fP value. Since the total intensity of the
+resulting color will differ from that of the original, it is necessary to
+restore the intensity by multiplying the component intensities of the
+saturated color by the ratio of the intensity of the original color to that of
+the saturated color.
+.PP
+Although it is always possible to decrease saturation by any given factor,
+there are two cases where it cannot be increased.  When the total intensity
+(or brightness) of a color is too high for the desired
+saturation, \fBpamaltsat\fP applies the maximum possible saturation that
+keeps the original intensity.  For example, any color with at least one
+component at the maxiumum is already fully saturated.  When one of the primary
+components is zero, the definition of saturation given above no longer works
+because of a zero in the denominator.  \fBpamaltsat\fP offers no special
+treatment of this situation because it does not create discontinuities and
+therefore produces no visible defects at reasonable strength levels.  When,
+however, strength approaches infinity, each color tends to its primary
+component with the highest intensity.
+.PP
+This method was invented by Anton Shepelev.
+  
+
+.SS Spectral Method
+.PP
+This is the default method.  It treats color as a spectrum with three
+bands: one for the intensity of each primary component.  Since neutral gray
+has a uniform (constant) spectrum, saturation can be measured as the
+difference of the spectrum of the given color from the uniform spectrum of the
+same total intensity.  The spectral method uses one of the simplest measures
+of such a difference: the difference between the highest and lowest component
+intensities, which is an additive value and therefore amenable to
+multiplication with good physical sense.  Although a complete hue-saturation
+model can be dervied from this approach, \fBpamaltsat\fP need not concern
+itself with it because it always preserves both hue and total intensity.
+.PP
+In order to change saturation, \fBpamaltsat\fP first multiplies the
+intensity of each component by the desired strength.  The saturation of the
+result is the strength times the saturation of the original, and likewise the
+total intensity, but it is then restored by subtraction of the neutral gray
+with a suitable intensity.
+.PP
+The effect of this method on each component intensity may be expressed in
+the following equation:
+.nf
+
+    sat = orig * strength - Iorig * (strength - 1)
+
+
+.fi
+where sat is the saturated
+sample, orig the original sample,
+and Iorig the total intensity of
+the original color.
+.PP
+The method is also related to color integrity because both its operations
+are part of that concept: multiplication of component intensities by the same
+quotient is an important operation because changes brightness but keeps color
+balance, and subtraction of a constant from all component intensities is
+described by the inventor of color integrity as 'subtraction of
+white.'
+.PP
+This procedure may produce both negative and over-unity component
+intensities.  For such samples, \fBpamaltsat\fP decreases the strength to the
+highest value that keeps the resulting color in range.
+.PP
+This method was invented by Anton Shepelev.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamaltsat\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-method\fP \fImethod\fP
+specifies the saturation method to use:
+.TS
+method name	option value
+Logarithmic	\f(CWlog \fP
+Spectral   	\f(CWspectrum\fP
+.TE
+.sp
+The default is \fBspectrum\fP
+
+.TP
+\fB-strength\fP \fIstrength\fP
+This specifies a real nonnegative factor whereby to modify saturation.  A
+value greater than unity will increase saturation, whereas a value less than
+unity will decrease it. Unity will leave the image unchanged, and zero will
+produce greyscale output according to Rec 709.
+  
+\fBpamaltsat\fP preserves the total intensity of each pixel and never
+affects neutral gray pixels.
+.sp
+This option is mandatory.
+
+.TP
+\fB-linear\fP
+This tells \fBpamaltsat\fP that the input is the intensity-linear
+variation of a Netpbm image forat, in which the samples are proportional to
+light intensity rather than to brightness, as they are in true-or
+gamma-adjusted- Netpbm image formats.
+
+
+.UN usage_notes
+.SH USAGE NOTES
+.PP
+Since \fBpamaltsat\fP does not affect neutral colors, you should adjust
+the color balance before saturation. You can do this with \fBpamlevels\fP.
+
+  
+.UN extensibility
+.SH EXTENSIBILITY
+
+\fBpamaltsat\fP is written with an eye to extending it with new saturation
+methods, which programmers are welcome to contribute.  The only requirement is
+that every new method depend on a single strength parameter with the semantics
+described under the \fB-strength\fP command-line option.
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pambrighten" (1)\c
+\&,
+.BR "ppmflash" (1)\c
+\&, 
+
+
+.UN author
+.SH AUTHOR
+.PP
+This program was first submitted by Anton Shepelev
+(\fIanton.txt@gmail.com\fP).
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamaltsat\fP was new in Netpbm 10.84 (September 2018).
+  
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #examples
+EXAMPLES
+.UE
+\&
+.IP \(bu
+
+.UR #saturation_methods
+SATURATION METHODS
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #usage_notes
+USAGE NOTES
+.UE
+\&
+.IP \(bu
+
+.UR #extensibility
+EXTENSIBILITY
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #author
+AUTHOR
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamaltsat.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamarith.1 b/upstream/mageia-cauldron/man1/pamarith.1
new file mode 100644
index 00000000..6f471b16
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamarith.1
@@ -0,0 +1,386 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamarith User Manual" 0 "24 October 2020" "netpbm documentation"
+
+.SH NAME
+pamarith - perform arithmetic on two Netpbm images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamarith\fP
+\fB-add\fP | \fB-subtract\fP | \fB-multiply\fP | \fB-divide\fP |
+\fB-difference\fP |
+\fB-minimum\fP | \fB-maximum\fP | \fB-mean\fP |
+\fB-equal\fP | \fB-compare\fP |
+\fB-and\fP | \fB-or\fP | \fB-nand\fP | \fB-nor\fP | \fB-xor\fP |
+\fB-shiftleft\fP | \fB-shiftright\fP
+[\fB-closeness=\fP\fIN\fP]
+\fIpamfile1\fP \fIpamfile2\fP ...
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamarith\fP reads two or more PBM, PGM, PPM, or PAM images as input.
+It performs the specified binary arithmetic operation on their sample
+values and produces an output of a format which is the more general of
+the two input formats.  The two input images must be of the same width
+and height.  The arithmetic is performed on each pair of identically
+located tuples to generate the identically located tuple of the
+output.
+.PP
+For functions that are commutative and associative, \fBpamarith\fP applies
+  the binary function repetitively on as many input images as you supply.  For
+  example, for \fB-add\fP , the output is the sum of all the inputs.  For
+  other functions (e.g. \fB-subtract\fP), the program fails if you supply
+  more than two input images.  (Before Netpbm 10.93 (December 2020), the
+  program always failed with more than two input images).
+.PP
+For some other functions, \fBpamarith\fP could theoretically compute a
+  meaningful result for multiple arguments, but it fails nonetheless if you
+  give more than two input images.  \fB-mean\fP and \fB-equal\fP are in that
+  category.
+  
+.PP
+Most of what \fBpamarith\fP does is not meaningful for visual images.  It
+  works toward Netpbm's secondary purpose of just manipulating arbitrary
+  matrices of numbers.
+  
+.PP
+For the purpose of the calculation, it assumes any PBM, PGM, or PPM
+input image is the equivalent PAM image of tuple type
+\fBBLACKANDWHITE\fP, \fBGRAYSCALE\fP, or \fBRGB\fP, respectively,
+and if it produces a PBM, PGM, or PPM output, produces the equivalent
+of the PAM image which is the result of the calculation.
+.PP
+The first \fIpamfile\fP argument identifies the "left"
+argument image; the second \fIpamfile\fP argument identifies the
+"right" one.
+.PP
+If the output is PAM, the tuple type is the same as the tuple type of
+the left input image.
+.PP
+\fBpamarith\fP performs the arithmetic on each pair of identically
+located tuples in the two input images.
+.PP
+The arithmetic operation is in all cases fundamentally a function from two
+integers to an integer (but see below - the functions are defined in ways that
+you can effectively e.g. add real numbers).  The operation is performed on two
+tuples as follows.  The two input images must have the same depth, or one of
+them must have depth one.  \fBpamarith\fP fails if one of these is not the
+case.
+.PP
+If they have the same depth, \fBpamarith\fP simply carries out the
+arithmetic one sample at a time.  I.e. if at a particular position the
+left input image contains the tuple (s1,s2,...,sN) and the right
+input image contains the tuple (t1,t2,...tN), and the function is f,
+then the output image contains the tuple
+(f(s1,t1),f(s2,t2),...,f(sN,tN)).
+.PP
+If one of the images has depth 1, the arithmetic is performed
+between the one sample in that image and each of the samples in the
+other.  I.e. if at a particular position the left input image
+contains the tuple (s) and the right input image contains the tuple
+(t1,t2,...tN), and the function is f, then the output image contains
+the tuple (f(s,t1),f(s,t2),...,f(s,tN)).
+
+
+.UN pbmoddness
+.SS PBM Oddness
+.PP
+If you're familiar with the PBM format, you may find \fBpamarith\fP's
+operation on PBM images to be nonintuitive.  Because in PBM black is
+represented as 1 and white as 0, you might be expecting black minus black
+to be white.
+.PP
+But the PBM format is irrelevant, because \fBpamarith\fP operates on the
+numbers found in the PAM equivalent (see above).  In a PAM black and white
+image, black is 0 and white is 1.  So black minus black is black.
+
+  
+.UN maxval
+.SS Maxval
+.PP
+The meanings of the samples with respect to the maxval varies
+according to the function you select.
+.PP
+In PAM images in general, the most usual meaning of a sample (the
+one that applies when a PAM image represents a visual image), is that
+it represents a fraction of some maximum.  The maxval of the image
+corresponds to some maximum value (in the case of a visual image, it
+corresponds to "full intensity."), and a sample value
+divided by the maxval gives the fraction.
+.PP
+For \fBpamarith\fP, this interpretation applies to the regular
+arithmetic functions: \fB-add\fP, \fB-subtract\fP, \fB-multiply\fP,
+\fB-divide\fP,
+\fB-difference\fP, \fB-minimum\fP, \fB-maximum\fP, \fB-mean\fP,
+\fB-equal\fP,
+and \fB-compare\fP.  For those, you should think of the arguments and
+result as numbers in the range [0,1).  For example, if the maxval of
+the left argument image is 100 and the maxval of the right argument
+image is 200 and the maxval of the output image is 200, and the left
+sample value in an \fB-add\fP calculation is 50 and the right sample
+is 60, the actual calculation is 50/100 + 60/200 = 160/200, and
+the output sample value is 160.
+.PP
+For these functions, \fBpamarith\fP makes the output image's
+maxval the maximum of the two input maxvals, except with
+\fB-equal \fP and \fB-compare\fP.  For \fB-equal\fP, the output maxval is
+always 1.  For \fB-compare\fP, it is always 2.  (Before Netpbm 10.14
+(February 2003), there was no exception for \fB-compare\fP; in 10.14, the
+exception was just that the maxval was \fIat least\fP 2, and sometime
+between 10.18 and 10.26 (January 2005), it changed to being exactly 2).
+.PP
+If the result of a calculation falls outside the range [0, 1),
+\fBpamarith\fP clips it -- i.e.  considers it to be zero or 1-.
+.PP
+In many cases, where both your input maxvals are the same, you can
+just think of the operation as taking place between the sample values
+directly, with no consideration of the maxval except for the clipping.
+E.g. an \fB-add\fP of sample value 5 to sample value 8 yields sample
+value 13.
+.PP
+But with \fB-multiply\fP, this doesn't work.  Say your two input
+images have maxval 255, which means the output image also has maxval
+255.  Consider a location in the image where the input sample values
+are 5 and 10.  You might think the multiplicative product of those
+would yield 50 in the output.  But \fBpamarith\fP carries out the
+arithmetic on the fractions 5/255 and 10/255.  It multiplies those
+together and then rescales to the output maxval, giving a sample value
+in the output PAM of 50/255 rounded to the nearest integer: 0.
+.PP
+With the bit string operations, the maxval has a whole different
+meaning.  The operations in question are: \fB-and\fP, \fB-or\fP,
+\fB-nand\fP, \fB-nor\fP, \fB-xor\fP, and \fB-shiftleft\fP,
+\fB-shiftright\fP.
+.PP
+With these, each sample value in one or both input images, and in
+the output image, represents a bit string, not a number.  The maxval
+tells how wide the bit string is.  The maxval must be a full binary
+count (a power of two minus one, such as 0xff) and the number of ones
+in it is the width of the bit string.  For the dyadic bit string
+operations (that's everything but the shift functions), the maxvals of
+the input images must be the same and \fBpamarith\fP makes the maxval
+of the output image the same.
+.PP
+For the bit shift operations, the output maxval is the same as the
+left input maxval.  The right input image (which contains the shift
+counts) can have any maxval and the maxval is irrelevant to the
+interpretation of the samples.  The sample value is the actual shift
+count.  But it's still required that no sample value exceed the
+maxval.
+
+
+.UN note
+.SH NOTE: UNARY FUNCTIONS
+.PP
+\fBpamarith\fP applies only binary functions.  If you want to apply a
+unary function, e.g. "halve", to a single image, use \fBpamfunc\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamarith\fP recognizes the following
+command line options:
+
+.UN function
+.SS The Function
+.PP
+These options select the function that \fBpamarith\fP applies.
+.PP
+You must specify one of these, and cannot specify more than one.
+  
+
+
+.TP
+\fB-add\fP
+Adds the two values.  If the result is larger than maxval, it is
+clipped.
+
+.TP
+\fB-subtract\fP
+Subtracts a value in the right input image from a value in the left input
+image.
+
+.TP
+\fB-minimum\fP
+Chooses the smaller value of the two.
+
+.TP
+\fB-maximum\fP
+Chooses the larger value of the two.
+
+.TP
+\fB-difference\fP
+Calculates the absolute value of the difference.
+
+.TP
+\fB-multiply\fP
+Does an ordinary arithmetic multiplication, but tends to produce
+nonobvious results because of the way \fBpamarith\fP interprets
+sample values.  See 
+.UR #maxval
+Maxval
+.UE
+\&.
+
+.TP
+\fB-divide\fP
+Divides a value in the left input image by the value in the right
+input image.  But like \fB-multiply\fP, it tends to produce nonobvious
+results.  Note that \fBpamarith\fP clipping behavior makes this of
+little use when the left argument (dividend) is greater than the right
+argument (divisor) -- the result in that case is always the maxval.
+If the divisor is 0, the result is the maxval.
+.sp
+\fB-divide\fP was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-equal\fP
+Produces maxval when the values in the two images are equal and
+zero when they are not.  Note that the output maxval is always 1 for
+\fB-equal\fP.
+.sp
+If the maxvals of the input images are not identical, \fBpamarith\fP may
+claim two values are not equal when in fact they are, because of the precision
+with which it does the arithmetic.
+.sp
+You can make the equality test approximate with the \fB-closeness\fP
+option.  This gives the percentage of maxval by which the samples can
+differ and still be considered equal.
+.sp
+\fB-equal\fP was new in Netpbm 10.93 (December 2020).
+
+.TP
+\fB-compare\fP
+Produces the value \fB0\fP when the value in the
+left input image is less than the value in the right input image,
+\fB1\fP when the values are equal, and \fB2\fP when the left is
+greater than the right.
+.sp
+If the maxvals of the input images are not identical, \fBpamarith\fP
+may claim two values are not equal when in fact they are, because of
+the precision with which it does the arithmetic.  However, it will never
+say A is greater than B if A is less than B.
+.sp
+\fB-compare\fP was new in Netpbm 10.13 (December 2002).
+
+.TP
+\fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, \fB-xor\fP
+These consider the input and output images to contain bit strings;
+they compute bitwise logic operations.  Note that if the maxval is 1,
+you can also look at these as logic operations on boolean input values.
+See section 
+.UR #maxval
+Maxval
+.UE
+\& for the special meaning of
+maxval with respect to bit string operations such as these.
+
+.TP
+\fB-shiftleft\fP, \fB-shiftright\fP
+These consider the left input image and output image to contain
+bit strings.  They compute a bit shift operation, with bits falling
+off the left or right end and zeroes shifting in, as opposed to bits
+off one end to the other.  The right input image sample value is the
+number of bit positions to shift.
+.sp
+Note that the maxval (see 
+.UR #maxval
+Maxval
+.UE
+\&) determines
+the width of the frame within which you are shifting.
+
+
+  
+.UN otheroptions
+.SS Other
+  
+
+
+.TP
+\fB-closeness\fP
+This changes the meaning of \fB-equal\fP.  It is not valid with any
+other function.  See the description of \fB-equal\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpamfunc\fP" (1)\c
+\&,
+.BR "\fBpamsummcol\fP" (1)\c
+\&,
+.BR "\fBpamsumm\fP" (1)\c
+\&,
+.BR "\fBpnminvert\fP" (1)\c
+\&,
+.BR "\fBpambrighten\fP" (1)\c
+\&,
+.BR "\fBppmdim\fP" (1)\c
+\&,
+.BR "\fBpnmconvol\fP" (1)\c
+\&,
+.BR "\fBpamdepth\fP" (1)\c
+\&,
+.BR "\fBpnmpsnr\fP" (1)\c
+\&,
+.BR "\fBpnm\fP" (1)\c
+\&,
+.BR "\fBpam\fP" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamarith\fP replaced \fBpnmarith\fP in Netpbm 10.3 (June 2002).
+.PP
+In Netpbm 10.3 through 10.8, though, \fBpamarith\fP was not
+backward compatible because it required the input images to be of the
+same depth, so you could not multiply a PBM by a PPM as is often done
+for masking.  (It was not intended at the time that \fBpnmarith\fP
+would be removed from Netpbm -- the plan was just to rewrite it to use
+\fBpamarith\fP; it was removed by mistake).
+.PP
+But starting with Netpbm 10.9 (September 2002), \fBpamarith\fP allows
+the images to have different depths as long as one of them has depth 1, and
+that made it backward compatible with \fBpnmarith\fP.
+.PP
+The original \fBpnmarith\fP did not have the \fB-mean\fP option.
+.PP
+The \fB-compare\fP option was added in Netpbm 10.13 (December 2002).
+.PP
+The bit string operations were added in Netpbm 10.27 (March 2005).
+.PP
+The \fB-divide\fP option was added in Netpbm 10.30 (October 2005).
+.PP
+The ability to have more than one input (operand) was added in Netpbm
+10.93 (December 2020).
+.PP
+The \fB-equal\fP option was added in Netpbm 10.93 (December 2020).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamarith.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pambayer.1 b/upstream/mageia-cauldron/man1/pambayer.1
new file mode 100644
index 00000000..1b52e952
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pambayer.1
@@ -0,0 +1,131 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pambayer User Manual" 0 "18 August 2005" "netpbm documentation"
+
+.SH NAME
+pambayer - interpret Bayer patterns
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpambayer\fP
+\fB-type=\fP{\fB1\fP|\fB2\fP|\fB3\fP|\fB4\fP}
+[\fB-nointerpolate\fP]
+[\fIpamfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpambayer\fP reads a Bayer pattern in a 1-deep Netpbm image and
+produces a color image in PAM RGB format as output.
+.PP
+A Bayer pattern is what you get from the optical sensor in some
+digital cameras.  Such a camera doesn't have a red, green, and blue
+sensor in the exact same place for an individual pixel.  Instead, it
+has red, green, and blue sensors laid out in a two dimensional array.
+The pattern in which they are laid out is the Bayer pattern.  The
+input to \fBpambayer\fP is one sample value for each of those
+sensors, so some samples are red, some are green, and some are blue.
+.PP
+\fBpambayer\fP turns that into a regular visual image with one pixel
+per sensor.  For the two components of each pixel that are missing in the
+corresponding Bayer input, \fBpambayer\fP averages the sample values from
+the adjacent pixels that do have that component.
+.PP
+But you can have \fBpambayer\fP fill in black instead (see the
+\fB-noninterpolate\fP option), which gives you a simpler representation of
+what the camera saw, on which you might do further processing.  Such an image
+still looks right, though considerably dimmer, if you stand far enough away
+and let your eyes do the interpolation.
+.PP
+The input image is a pseudo-PNM image (pseudo- because while the structure
+is the same, the sample values have different meanings) or PAM image of
+arbitrary tuple type.  \fBpambayer\fP looks at only the first plane of the
+input.
+.PP
+The output image is a PAM image of tuple type "RGB", i.e.
+a standard color image.  You can convert this to PPM with
+.BR "\fBpamtopnm\fP" (1)\c
+\&.
+.PP
+If you're interested in just one of the primary colors, use
+\fBpamchannel\fP on the output of \fBpambayer\fP to extract it.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpambayer\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-type=\fP\fIn\fP
+This tells which Bayer pattern the input is:
+
+
+.TP
+1
+GBG/RGR/GBG matrix
+.TP
+2
+RGR/GBG/RGR matrix
+.TP
+3
+BGB/GRG/BGB matrix
+.TP
+4
+GRG/BGB/GRG matrix
+
+
+This option is mandatory.
+
+.TP
+\fB-nointerpolate\fP
+Each output pixel position corresponds to one position in the input
+Bayer pattern, which means only one of the three color components is
+supplied by the input.  For the other two, this option says to user zero.
+Without it, \fBpambayer\fP instead interpolates from the adjacent pixels
+that do have that color component.
+.sp
+This option was new in Netpbm 10.49 (December 2009).
+
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "cameratopam" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpambayer\fP was new in Netpbm 10.30 (October 2005).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pambayer.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pambrighten.1 b/upstream/mageia-cauldron/man1/pambrighten.1
new file mode 100644
index 00000000..5b57e535
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pambrighten.1
@@ -0,0 +1,188 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pambrighten User Manual" 0 "18 August 2020" "netpbm documentation"
+
+.SH NAME
+pambrighten - change a PPM image's Saturation and Value
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpambrighten\fP
+[\fB-saturation=\fP[\fB+\fP|\fB-\fP]\fIsaturation_percent\fP]
+[\fB-value=\fP[\fB+\fP|\fB-\fP]\fIvalue_percent\fP]
+[\fInetpbmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpambrighten\fP increases or decreases the Saturation and Value
+(from the HSV color space) of each pixel of a Netpbm image.  You specify
+the percentage change for each of those parameters.
+.PP
+You can also remap the colors of the pixels so their Values cover the full
+range of possible Values.
+.PP
+The input image is from the file named \fInetpbmfile\fP, or Standard
+Input if \fInetpbmfile\fP is not specified.
+  
+.PP
+The output format is the same as the input format and any extra channels,
+such as transparency, are passed through.
+  
+.PP
+Hue-Saturation-Value, or HSV, is one way to represent a color, like the
+more well-known RGB.  Hue, Saturation, and Value are numbers in the range from
+0 to 1.  We always capitalize them in this document when we mean the number
+from the HSV color space, especially since "value" as a conventional English
+word has a much more abstract meaning.
+.PP
+Value is a measure of how bright the color is, relative to some specified
+maximum (the Netpbm formats are also defined in terms of a specified maximum
+brightness -- For the purposes of this program, they are the same).  In
+particular, it is the brightness of the brightest primary color component of
+the color divided by the maximum brightness possible for a component.  Zero
+Value means black.  White has full Value.
+.PP
+Hue is an indication of the secondary color with the same brightness that
+most closely approximates the color.  A secondary color is made of a
+combination of at most two of the primary colors.
+.PP
+Saturation is a measure of how close the color is to the color indicated by
+the Hue and Value.  A lower number means more light of the third primary color
+must be added to get the exact color.  Full Saturation means the color is a
+secondary color.  Zero Saturation means the color is gray (or black or white).
+Decreasing the saturation of a color tends to make it washed out.
+.PP
+If it is impossible to increase the Value of a pixel by the amount you
+specify (e.g. the Value is .5 and you specify +200%), \fBpambrighten\fP
+increases it to full Value instead.
+.PP
+If it is impossible to increase the Saturation of a pixel by the amount
+you specify (e.g. it is already half saturated and you specify +200%),
+\fBpambrighten\fP increases it to full Saturation instead.
+.PP
+For a simpler kind of brightening, you can use \fBpamfunc -multiplier\fP
+simply to increase the brightness of each pixel by a specified percentage,
+clipping each RGB component where the calculated brightness would exceed full
+brightness.  Thus, the brightest colors in the image would change chromaticity
+in addition to not getting the specified brightness boost.  For
+\fIdecreasing\fP brightness, \fBpamfunc\fP should do the same thing as
+\fBpambrighten\fP.
+.PP
+\fBppmflash\fP does another kind of brightening.  It changes the color of
+each pixel to bring it a specified percentage closer to white.  This increases
+the value and saturation.
+.PP
+\fBpambrighten\fP is meant to replace \fBppmbrighten\fP.  It is the same
+as \fBppmbrighten\fP, except that it recognizes the various Netpbm image
+formats rather than treating them all as PPM.  The output format is the same
+as the input format and extra channels in a PAM image (such as a
+transparency channel) get passed through.
+.PP
+If you want to modify the hues in the image, use \fBpamhue\fP.
+
+  
+.UN examples
+.SH EXAMPLES
+.PP
+To double the Value of each pixel:
+.nf
+pambrighten -value=100
+
+.fi
+.PP
+To double the Saturation and halve the Value of each pixel:
+.nf
+pambrighten -saturation=+100 -value=-50
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpambrighten\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-value=\fP\fIvalue_percent\fP
+This option specifies the amount, as a percentage, by which you want to
+increase the Value of each pixel.  It may be negative.
+.sp
+The default is zero.
+  
+.TP
+\fB-saturation=\fP\fIvalue_percent\fP
+This option specifies the amount, as a percentage, by which you want to
+increase the Saturation of each pixel.  It may be negative.
+.sp
+The default is zero.
+
+  
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmnorm" (1)\c
+\&, 
+.BR "ppmdim" (1)\c
+\&, 
+.BR "pamfunc" (1)\c
+\&, 
+.BR "ppmflash" (1)\c
+\&, 
+.BR "pamaltsat" (1)\c
+\&, 
+.BR "pamdepth" (1)\c
+\&, 
+.BR "pnmgamma" (1)\c
+\&, 
+.BR "pamhue" (1)\c
+\&, 
+.BR "ppmhist" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpambrighten\fP was new in Netphm 10.86 (March 2019).  It was a PAM
+conversion of the much older \fBppmbrighten\fP.
+  
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1990 by Brian Moffet.
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.  This software is provided "as is" without express or
+implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pambrighten.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamcat.1 b/upstream/mageia-cauldron/man1/pamcat.1
new file mode 100644
index 00000000..a9f74941
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamcat.1
@@ -0,0 +1,282 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamcat User Manual" 0 "30 November 2022" "netpbm documentation"
+
+.SH NAME
+
+pamcat - concatenate Netpbm images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamcat\fP
+
+{\fB-leftright\fP | \fB-lr\fP | \fB-topbottom\fP | \fB-tb\fP}
+
+[\fB-white\fP|\fB-black\fP]
+
+[\fB-jtop\fP|\fB-jbottom\fP|\fB-jcenter\fP]
+[\fB-jleft\fP|\fB-jright\fP|\fB-jcenter\fP]
+
+[\fInetpbmfile\fP ... | \fB-listfile=\fP{\fIfilename\fP|\fB-\fP}]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may
+use white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamcat\fP reads one or more Netpbm images as input, concatenates them
+either left to right or top to bottom, and produces a single Netpbm image as
+output.
+.PP
+Options \fB-leftright\fP and \fB-topbottom\fP determine the direction
+  of the concatenation.
+  
+.PP
+The images do not have to be the same shape:  You can concatenate images
+  of different widths top to bottom and of different heights left to right.
+  You can concatenate images of different depths (numbers of planes).  You
+  can concatenate a PBM image with a PPM image.  Et cetera.
+.PP
+The format of the output image is the highest of the formats of the
+  input images, in the order PBM, PGM, PPM, PAM.
+.PP
+For PAM output, if all of the input images have the same tuple type
+  (including implied tuple types of PNM images), that is the tuple type of the
+  output.  If the inputs differ, but are all visual tuple types, the
+  output&apos;s tuple type is the most primitive that can represent all the
+  input.  E.g. if inputs are GRAYSCALE and RGB, the output is RGB, and if the
+  inputs are GRAYSCALE_ALPHA and RGB, the output is RGB_ALPHA.  If the inputs
+  differ and are not all visual, the output tuple type is a null string.
+.PP
+When the output is PAM, its depth is the maximum of the depths of the
+  inputs (including implied depths of PNM images), but at least enough to
+  represent the tuple type specified above.  In the case of nonvisual PAM
+  output, input images are padded to this output depth with higher numbered
+  planes of all zeroes.
+.PP
+Where the input images are of different widths and you concatenate top
+  to bottom, \fBpamcat\fP generates output as wide as the widest of the
+  inputs and pads the narrower ones.  The images can be justified either
+  left, right, or center within this padded field.  Use options
+  \fB-jleft\fP, \fB-jright\fP, and \fB-jcenter\fP to control this.
+.PP
+Similarly, where the input images are of different heights and you
+  concatenate left to right, \fBpamcat\fP generates output as tall as the
+  tallest of the inputs and pads the shorter ones.  The images can be
+  justified either top, bottom, or center within this padded field.  Use
+  options
+  \fB-jtop\fP, \fB-jbottom\fP, and \fB-jcenter\fP to control this.
+.PP
+You can make the padding black or white or let \fBpamcat\fP determine a
+  likely background color, with possibly different colored padding for each
+  input image.  Control this with the \fB-black\fP and \fB-white\fP options.
+.PP
+Where the output image contains transparency information (because at least
+  one of the input images does), the padding is opaque.  (That is consistent
+  with the result for an output image without transparency information, because
+  such an image is defined to be opaque).
+  
+.PP
+The arguments are names of input files.  Any one of these, but not more
+than one, may be "-" to indicate Standard Input.  If you have no arguments
+(and do not specify \fB-listfile\fP), that means a single input image from
+Standard Input (and that is pointless - the output is the same as the input).
+You can supply the file names in a file instead of as arguments with a
+\fB-listfile\fP option.
+.PP
+Regardless of how you specify the input files, you may not concatenate
+  more files than your system&apos;s limit on the number of concurrently
+  open files by one process.  16 is a typical number for that.
+.PP
+To assemble a regular grid of images, you can use \fBpamundice\fP.
+.PP
+To do the reverse, you might use \fBpamdice\fP to split an image
+up into smaller ones of equal size or \fBpamcut\fP to chop off part
+of an image or extract part of an image.
+.PP
+\fBpnmtile\fP concatenates a single input image to itself repeatedly.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamcat\fP recognizes the following
+command line options:
+
+.UN direction
+.SS Direction
+
+
+.TP
+\fB-topbottom\fP, \fB-tb\fP
+Combine images vertically, top to bottom.
+
+.TP
+\fB-leftright\fP, \fB-lr\fP
+Combine images horizontally, left to right.
+.sp
+You must specify the direction by specifying one of the above.  You cannot
+    specify both.
+
+
+
+.UN justification
+.SS Justification
+
+
+.TP
+\fB-jleft\fP
+  
+Left-justify images in a top-bottom concatenation.
+.sp
+You cannot specify this with \fB-jright\fP
+.sp
+This option is invalid in a left-right concatenation.
+
+.TP
+\fB-jright\fP
+  
+Right-justify images in a top-bottom concatenation.
+.sp
+You cannot specify this with \fB-jleft\fP
+.sp
+This option is invalid in a left-right concatenation.
+
+.TP
+\fB-jtop\fP
+  
+Top-justify images in a left-right concatenation.
+.sp
+You cannot specify this with \fB-jbottom\fP
+.sp
+This option is invalid in a top-bottom concatenation.
+
+.TP
+\fB-jbottom\fP
+  
+Bottom-justify images in a left-right concatenation.
+.sp
+You cannot specify this with \fB-jtop\fP
+.sp
+This option is invalid in a top-bottom concatenation.
+
+.TP
+\fB-jcenter\fP
+  
+Center images (valid for both left-right and top-bottom concatenations).
+    This is the default.
+    
+
+.PP
+By default, \fBpamcat\fP centers the smaller images.
+  \fB-topbottom -jleft\fP would stack the images on top of each other, flush
+  with the left edge.  \fB-leftright -jbottom\fP would line up the images
+  left to right with their bottom edges aligned as if sitting on a table.
+
+
+.UN paddingcolor
+.SS Padding Color
+These options specify what color to use to fill in the extra space when
+doing the justification.  If neither is specified, \fBpamcat\fP chooses
+whichever color seems to be right for the images, and the color may be
+different for each image.
+
+.TP
+\fB-white\fP
+Make all padding white.
+.sp
+You may not specify this with \fB-black\fP
+.TP
+\fB-black\fP
+Make all padding black.
+.sp
+You may not specify this with \fB-white\fP
+
+
+
+.UN miscellaneousopt
+.SS Miscellaneous
+
+
+.TP
+\fB-listfile=\fP{\fIfilename\fP|\fB-\fP}
+This specifies the name of a file that contains the list of input files.
+  Option value \fB-\fP means the list comes from Standard Input.
+.sp
+The file contains one file name per newline-delimited line in whatever
+    code the system \fBfopen\fP service expects.  You may omit the newline
+    on the last line.  Empty lines are ignored.  There is no mechanism for
+    including comments in the list (so if you want to have a commented list,
+    preprocess it to remove comments before supplying it to \fBpamcat\fP).
+.sp
+You may not specify file names as command line arguments together with
+    \fB-listfile\fP
+.sp
+You may not list more files than than your system&apos;s limit on the
+  number of concurrently open files by one process.  16 is a typical number
+  for that.
+.sp
+This option was new in Netpbm 11.01 (December 2022).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamundice" (1)\c
+\&,
+.BR "pamdice" (1)\c
+\&,
+.BR "pnmtile" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamcat\fP was new in Netpbm 11.00 (September 2022); in earlier versions,
+  \fBpnmcat\fP does most of the same thing.
+.PP
+Primordial Netpbm/Pbmplus contained concatenation tools, but there were two
+  of them: \fBpbmcatlr\fP for left-right concatenation of PBM images
+  and \fBpbmcattb\fP for top-bottom concatenation.  When the PGM and PPM
+  formats were added, these programs were combined and extended to handle all
+  three formats, as \fBpnmcat\fP.  All of this work was done by Pbmplus
+  author Jef Poskanzer.
+.PP
+In Netpbm 10.44 (September 2008), Akira F Urushibata added special fast
+  processing for raw PBM images, exploiting bitstring processing CPU
+  facilities.
+.PP
+\fBpnmcat\fP was one of the most essential programs in Netpbm, but one
+  thing it could not concatenate was PAM images with transparency.  So in
+  Netpbm 11.00 (September 2022), Bryan Henderson wrote \fBpamcat\fP to
+  replace it.  It reused the raw PBM fast path code from \fBpnmcat\fP almost
+  verbatim.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamcat.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamchannel.1 b/upstream/mageia-cauldron/man1/pamchannel.1
new file mode 100644
index 00000000..efc36a39
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamchannel.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamchannel User Manual" 0 "10 January 2006" "netpbm documentation"
+
+.SH NAME
+pamchannel - extract channels from a PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamchannel\fP
+[\fB-infile=\fP\fIinfile\fP]
+[\fB-tupletype=\fP\fItupletype\fP]
+[\fIchannum\fP ...]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamchannel\fP reads a Netpbm image as input and produces a
+PAM image as output, consisting of the indicated channels (planes) of
+the input.
+.PP
+Each \fIchannum\fP argument is the number of a channel of the input,
+with the first channel being zero.  The channels in the output are in the
+order of these arguments.
+.PP
+The output is the same dimensions as the input, except that the depth
+is the number of \fIchannum\fP arguments you supply.  The tuple type
+is a null string unless you specify the \fB-tupletype\fP option.
+.PP
+This program works on multi-image streams, producing a
+corresponding output stream.  But before Netpbm 10.32 (February 2006),
+it ignored every image after the first.
+.PP
+\fBpamstack\fP does the opposite of \fBpamchannel\fP:  It takes multiple
+PAM or PNM images as input and stacks their planes (channels) on top of
+one another to yield a single PAM.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamchannel\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-infile\fP \fIinfile\fP
+This specifies the input file, which defaults to Standard Input.  You
+may specify \fB-\fP to select Standard Input explicitly.
+.sp
+This is a little unconventional for Netpbm programs, which usually 
+have the input file specification as an argument.  For \fBpamchannel\fP,
+the arguments are channel numbers.
+
+.TP
+\fB-tupletype\fP \fItupletype\fP
+This specified the tuple type name to be recorded in the output.  You may
+use any string up to 255 characters.  Some programs recognize some names.
+If you omit this option, the default tuple type name is null.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+.BR "pamstack" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamchannel\fP was new, along with the PAM format, in Netpbm
+9.7 (August 2000).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamchannel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamcomp.1 b/upstream/mageia-cauldron/man1/pamcomp.1
new file mode 100644
index 00000000..c0b1b76e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamcomp.1
@@ -0,0 +1,379 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamcomp User Manual" 0 "13 August 2011" "netpbm documentation"
+.PP
+.SH NAME
+pamcomp - composite (overlay) two Netpbm images together
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamcomp\fP
+
+[\fB-align=\fP{\fBleft\fP | \fBcenter\fP | \fBright\fP |
+\fBbeyondleft\fP | \fBbeyondright\fP}]
+[\fB-valign=\fP{\fBtop\fP | \fBmiddle\fP | \fBbottom\fP|
+\fBabove\fP | \fBbelow\fP}]
+[\fB-xoff=\fP\fIX\fP]
+[\fB-yoff=\fP\fIY\fP]
+[\fB-alpha=\fP\fIalpha-pgmfile\fP]
+[\fB-invert\fP]
+[\fB-opacity=\fP\fIopacity\fP]
+[\fB-mixtransparency\fP]
+[\fB-linear\fP]
+\fIoverlay_file\fP
+[\fIunderlying_file\fP [\fIoutput_file\fP]]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpamcomp\fP reads two images and produces a composite image with
+one of the images overlayed on top of the other, possible
+translucently.  The images need not be the same size.  The input and
+outputs are Netpbm format image files.
+.PP
+In its simplest use, \fBpamcomp\fP simply places the image in the
+file \fIoverlay_file\fP on top of the image in the file
+\fIunderlying_file\fP, blocking out the part of \fIunderlying_file\fP
+beneath it.
+.PP
+If you add the \fB-alpha\fP option, then \fBpamcomp\fP uses the
+image in file \fIalpha-pgmfile\fP as a transparency mask, which means it
+determines the level of transparency of each point in the overlay
+image.  The transparency mask must have the same dimensions as the overlay
+image.  In places where the transparency mask defines the overlay image to be
+opaque, the composite output contains only the contents of the overlay
+image; the underlying image is totally blocked out.  In places where
+the transparency mask defines the overlay image to be transparent, the
+composite output contains none of the overlay image; the underlying
+image shows through completely.  In places where the transparency mask shows
+a value in between opaque and transparent (translucence), the
+composite image contains a mixture of the overlay image and the
+underlying image and the level of translucence determines how much of
+each.
+.PP
+The transparency mask is a PGM file in which a white pixel represents
+opaqueness and a black pixel transparency.  Anything in between is
+translucent.  (Like any Netpbm program, \fBpamcomp\fP will see a PBM
+file as if it is PGM).
+.PP
+If the overlay image is a PAM image of tuple type RGB_ALPHA or
+GRAYSCALE_ALPHA, then the overlay image contains transparency
+information itself and \fBpamcomp\fP uses it the same way as the
+transparency mask described above.  If you supply both an overlay image that
+has transparency information and a transparency mask, \fBpamcomp\fP
+multiplies the two opacities to get the opacity of the overlay pixel.
+.PP
+Before Netpbm 10.25 (October 2004), \fBpamcomp\fP did not recognize the
+transparency information in a PAM image -- it just ignored it.  So people had
+to make appropriate transparency masks in order to have a non-opaque overlay.  Some
+Netpbm programs that convert from image formats that contain transparency
+information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so
+you have to use the old method -- extract the transparency information from
+the original into a separate transparency mask and use that as input to
+\fBpamcomp\fP.
+.PP
+The output image is always of the same dimensions as the underlying
+image.  \fBpamcomp\fP uses only parts of the overlay image that fit
+within the underlying image.
+.PP
+The output image is a PAM image.  Its tuples are color, grayscale, or black
+and white, whichever is the "highest" format between the two input
+images.  The maxval of the output is the least common multiple of the maxvals
+of the input, up to the maximum possible PAM maxval, 65535.
+.PP
+The output has an opacity channel if and only if the underlying image does,
+and then the opacities are as described under the \fB-mixtransparency\fP
+option.  Before Netpbm 10.56 (September 2011), the output never has an opacity
+channel.
+.PP
+To specify where on the underlying image to place the overlay
+image, use the \fB-align\fP, \fB-valign\fP, \fB-xoff\fP, and
+\fB-yoff\fP options.  Without these options, the default horizontal
+position is flush left and the default vertical position is flush top.
+.PP
+The overlay image, in the position you specify, need not fit entirely
+within the underlying image.  \fBpamcomp\fP uses only the parts of the
+overlay image that appear above the underlying image.  It is possible to
+specify positioning such that \fInone\fP of the overlay image is 
+over the underlying image -- i.e. the overlay is out of frame.  If you
+do that, \fBpamcomp\fP issues a warning.
+.PP
+ The overlay and underlying images may be of different formats
+(e.g. overlaying a PBM text image over a full color PPM image) and
+have different maxvals.  The output image has the more general of the
+two input formats and a maxval that is the least common multiple the
+two maxvals (or the maximum maxval allowable by the format, if the LCM
+is more than that).
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+The \fIoverlay_file\fP argument is the name of the file containing the
+  overly image, while \fIunderlying_file\fP is the name of the file
+  containing the underlying image.  For either, you may specify '-'
+  to indicate Standard Input, and \fIunderlying\fP file defaults to Standard
+  Input.  Make sure you aren't specifying (or defaulting) Standard Input as
+  both.
+.PP
+Note that there may be a third input file, identified by an
+\fB-alphafile\fP option.
+.PP
+The \fIoutput_file\fP argument is the name of the file to which
+  \fBpamcomp\fP writes the output, creating or truncating it first.  You may
+  specify '-' to indicate Standard Output, in which
+  case \fBpamcomp\fP does not truncate it.  Note that \fBpamcomp\fP is
+  unusual among Netpbm programs, as a historical accident, in having an output
+  file argument; Netpbm programs normally write to Standard Output only.
+  
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamcomp\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-align=\fP\fIalignment\fP
+This option selects the basic horizontal position of the overlay image
+with respect to the underlying image, in syntax reminiscent of HTML.
+\fBleft\fP means flush left, \fBcenter\fP means centered, and \fBright\fP
+means flush right.
+.sp
+The \fB-xoff\fP option modifies this position.
+
+\fBbeyondleft\fP means just out of frame to the left -- the right edge of
+the overlay is flush with the left edge of the underlying image.  
+\fBbeyondright\fP means just out of frame to the right.  These alignments
+are useful only if you add a \fB-xoff\fP option.    These two values were
+added in Netpbm 10.10 (October 2002).
+.sp
+The default is \fBleft\fP.
+
+.TP
+\fB-valign=\fP\fIalignment\fP
+This option selects the basic vertical position of the overlay image
+with respect to the underlying image, in syntax reminiscent of HTML.
+\fBtop\fP means flush top, \fBmiddle\fP means centered, and \fBbottom\fP
+means flush bottom.
+.sp
+The \fB-yoff\fP option modifies this position.
+
+\fBabove\fP means just out of frame to the top -- the bottom edge of
+the overlay is flush with the top edge of the underlying image.  
+\fBbelow\fP means just out of frame to the bottom.  These alignments
+are useful only if you add a \fB-yoff\fP option.  These two values were
+added in Netpbm 10.10 (October 2002).
+.sp
+The default is \fBtop\fP.
+
+.TP
+\fB-xoff=\fP\fIx\fP
+This option modifies the horizontal positioning of the overlay
+image with respect to the underlying image as selected by the
+\fB-align\fP option.  \fBpamcomp\fP shifts the overlay image from
+that basic position \fIx\fP pixels to the right.  \fIx\fP can be
+negative to indicate shifting to the left.
+.sp
+The overlay need not fit entirely (or at all) on the underlying image.
+\fBpamcomp\fP uses only the parts that lie over the underlying image.
+.sp
+Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually 
+exclusive with \fB-align\fP and always measured from the left edge.
+
+.TP
+\fB-yoff=\fP\fIy\fP
+This option modifies the vertical positioning of the overlay
+image with respect to the underlying image as selected by the
+\fB-valign\fP option.  \fBpamcomp\fP shifts the overlay image from
+that basic position \fIy\fP pixels downward.  \fIy\fP can be
+negative to indicate shifting upward.
+.sp
+The overlay need not fit entirely (or at all) on the underlying image.
+\fBpamcomp\fP uses only the parts that lie over the underlying image.
+.sp
+Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually 
+exclusive with \fB-valign\fP and always measured from the top edge.
+
+.TP
+\fB-alpha=\fP\fIalpha-pgmfile\fP
+This option names a file that contains the transparency mask.  If you don't
+specify this option, there is no transparency mask, which is equivalent to 
+having a transparency mask specify total opaqueness everywhere.
+.sp
+You can specify \fB-\fP as the value of this option and the transparency
+mask will come from Standard Input.  If you do this, don't specify
+Standard Input as the source of any other input image.
+
+.TP
+\fB-invert\fP
+This option inverts the sense of the values in the transparency mask, which 
+effectively switches the roles of the overlay image and the underlying
+image in places where the two intersect.
+
+.TP
+\fB-opacity=\fP\fIopacity\fP
+This option tells how opaque the overlay image is to be, i.e. how much
+of the composite image should be from the overlay image, as opposed to
+the underlying image.  \fIopacity\fP is a floating point number, with
+1.0 meaning the overlay image is totally opaque and 0.0 meaning it is
+totally transparent.  The default is 1.0.
+.sp
+If you specify a transparency mask (the \fB-alpha\fP option),
+\fBpamcomp\fP uses the product of the opacity indicated by the transparency
+mask (as modified by the \fB-invert\fP option, as a fraction, and
+this opacity value.  The \fB-invert\fP option does not apply to this
+opacity value.
+.sp
+As a simple opacity value, the value makes sense only if it is
+between 0 and 1, inclusive.  However, \fBpamcomp\fP accepts all
+values and performs the same arithmetic computation using whatever
+value you provide.  An opacity value less than zero means the underlay
+image is intensified and then the overlay image is "subtracted" from
+it.  An opacity value greater than unity means the overlay image is
+intensified and the underlay image subtracted from it.  In either
+case, \fBpamcomp\fP clips the resulting color component intensities
+so they are nonnegative and don't exceed the output image's maxval.
+.sp
+This may seem like a strange thing to do, but it has uses.  You can use it
+to brighten or darken or saturate or desaturate areas of the underlay image.
+See
+.BR " this description" (1)\c
+\& of the technique.
+.sp
+This option was added in Netpbm 10.6 (July 2002).  Before Netpbm 10.15
+(April 2003), values less than zero or greater than unity were not allowed.
+
+.TP
+\fB-mixtransparency\fP
+This option controls what \fBpamcomp\fP does where both the underlying and
+overlay image are non-opaque.
+.sp
+By default, the output image has the same transparency as the underlying
+image and the transparency of the underlying image has no effect on the
+composition of color.
+.sp
+But with this option, \fBpamcomp\fP composes the image according to a
+plastic transparency metaphor: the underlying and overlay images are plastic
+slides.  The output image is the slide you get when you stack up those two
+slides.  So the transparency of the output is a combination of the
+transparency of the inputs and the transparency of the underlying image
+affects the underlying image's contribution to the output image's color.
+.sp
+Unlike the metaphorical slide, a PAM pixel has a color even where it is
+completely transparent, so \fBpamcomp\fP departs from the metaphor in that
+case and makes the output color identical to the underlying image.
+.sp
+This option was new in Netpbm 10.56 (September 2011).  Before that, the
+output is always opaque and the \fBpamcomp\fP ignores the transparency of the
+underlying image.
+
+.TP
+\fB-linear\fP
+This option indicates that the inputs are not true Netpbm images but
+rather a light-intesity-proportional variation.  This is relevant only when
+you mix pixels, using the \fB-opacity\fP option or a transparency mask
+(the \fB-alpha\fP option).
+.sp
+The transparency mask and \fB-opacity\fP values indicate a fraction of
+the light intensity of a pixel.  But the PNM and PNM-equivalent PAM
+image formats represent intensities with gamma-adjusted numbers that
+are not linearly proportional to intensity.  So \fBpamcomp\fP, by
+default, performs a calculation on each sample read from its input and
+each sample written to its output to convert between these
+gamma-adjusted numbers and internal intensity-proportional numbers.
+.sp
+Sometimes you are not working with true PNM or PAM images, but
+rather a variation in which the sample values are in fact directly
+proportional to intensity.  If so, use the \fB-linear\fP option to
+tell \fBpamcomp\fP this.  \fBpamcomp\fP then will skip the
+conversions.
+.sp
+The conversion takes time.  And the difference between
+intensity-proportional values and gamma-adjusted values may be small
+enough that you would barely see a difference in the result if you
+just pretended that the gamma-adjusted values were in fact
+intensity-proportional.  So just to save time, at the expense of some
+image quality, you can specify \fB-linear\fP even when you have true
+PPM input and expect true PPM output.
+.sp
+For the first 13 years of Netpbm's life, until Netpbm 10.20
+(January 2004), \fBpamcomp\fP's predecessor \fBpnmcomp\fP always
+treated the PPM samples as intensity-proportional even though they
+were not, and drew few complaints.  So using \fB-linear\fP as a lie
+is a reasonable thing to do if speed is important to you.
+.sp
+Another technique to consider is to convert your PNM image to the
+linear variation with \fBpnmgamma\fP, run \fBpamcomp\fP on it and
+other transformations that like linear PNM, and then convert it back
+to true PNM with \fBpnmgamma -ungamma\fP.  \fBpnmgamma\fP is often
+faster than \fBpamcomp\fP in doing the conversion.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pammixmulti.html" (1)\c
+\& mixes together
+two or more images of the same size, in various ways.
+.PP
+.BR "ppmmix" (1)\c
+\& and
+.BR "pnmpaste" (1)\c
+\& are simpler, less general
+versions of the same tool.
+.PP
+.BR "ppmcolormask" (1)\c
+\& and
+.BR "pbmmask" (1)\c
+\&, and
+.BR "\fBpambackground\fP" (1)\c
+\& can help with
+generating a transparency mask.
+.PP
+.BR "pnmcomp" (1)\c
+\& is an older program that
+runs faster, but has less function.
+.PP
+.BR "pnm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamcomp\fP was new in Netpbm 10.21 (March 2004).  Its predecessor,
+\fBpnmcomp\fP, was one of the first programs added to Netpbm when the
+project went global in 1993.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992 by David Koblas (\fIkoblas@mips.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamcomp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamcrater.1 b/upstream/mageia-cauldron/man1/pamcrater.1
new file mode 100644
index 00000000..0af58fc4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamcrater.1
@@ -0,0 +1,234 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamcrater User Manual" 0 "03 November 2014" "netpbm documentation"
+
+.SH NAME
+
+pamcrater - create cratered terrain by fractal forgery
+
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamcrater\fP
+
+[\fB-number\fP \fIn\fP]
+
+[\fB-height\fP \fIpixels\fP]
+
+[\fB-width\fP \fIpixels\fP]
+
+[\fB-randomseed=\fP\fIinteger\fP]
+
+[\fB-verbose\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamcrater\fP creates a PAM image which is a terrain map (not a visual
+image) of cratered terrain.  The terrain is as if a given number of impacts
+into a surface create craters with random position and size.
+.PP
+The size distribution of the craters is based on a power law which results
+in many more small craters than large ones.  The number of craters of a given
+size varies as the reciprocal of the area as described on pages 31 and 32 of
+Peitgen and Saupe[1]; cratered bodies in the Solar System are observed to obey
+this relationship.  The formula used to obtain crater radii governed by this
+law from a uniformly distributed pseudorandom sequence was developed by Rudy
+Rucker.
+.PP
+A terrain map is a two dimensional map of terrain elevations.  the PAM
+image that \fBpamcrater\fP produces is therefore not a visual image but a
+depth-one image of tuple type "elevation", with the sample value
+being proportional to an elevation.
+.PP
+You can visualize the terrain map by generating a shaded relief image of it
+with \fBpamshadedrelief\fP.  
+.PP
+High resolution images with large numbers of
+craters often benefit from being piped through \fBpnmsmooth\fP.  The
+averaging performed by this process eliminates some of the jagged pixels and
+lends a mellow ``telescopic image'' feel to the overall picture.
+.PP
+\fBpamcrater\fP generates only small craters, which are hemispherical in
+shape (regardless of the incidence angle of the impacting body, as long as the
+velocity is sufficiently high).  Large craters, such as Copernicus and Tycho
+on the Moon, have a ``walled plain'' shape with a cross-section more like:
+
+.nf
+                /\e                            /\e
+          _____/  \e____________/\e____________/  \e_____
+
+.fi
+.PP
+Larger craters should really use this profile, including the central
+peak, and totally obliterate the pre-existing terrain.
+.PP
+The maxval of the PAM image is always 65535.
+.PP
+The randomness in the image is limited before Netpbm 10.37 (December
+2006) -- if you run the program twice in the same second, you may get
+identical output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamcrater\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+
+.TP
+\fB-number\fP \fIn\fP
+This causes \fBpamcrater\fP to generate \fIn\fP craters.  If you do not
+specify \fB-number\fP, it generates 50000 craters.  Don't expect to see them
+all!  For every large crater there are many, many more tiny ones which tend
+simply to erode the landscape.  In general, the more craters you specify, the
+more realistic the result; ideally you want the entire terrain to have been
+extensively turned over again and again by cratering.  High resolution images
+containing five to ten million craters are stunning but take longer to create.
+
+.TP
+\fB-height\fP \fIheight\fP
+This sets the height of the generated image to \fIheight\fP pixels.
+The default height is 256 pixels.
+
+.TP
+\fB-width\fP \fIwidth\fP
+This sets the width of the generated image to \fIwidth\fP pixels.  The
+default width is 256 pixels.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpamcrater\fP uses a seed derived from the time of day and
+process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+.TP
+\fB-verbose\fP
+This causes \fBpamcrater\fP to issue additional messages about what it
+is doing.
+.sp
+This option was new in Neptbm 10.69 (December 2014).
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+\f(CW
+    $ pamcrater | pamshadedrelief | pamx
+
+    $ pamcrater -number=500000 -height=1000 -width=1000 >craters.pam
+\fP  
+
+.fi
+
+.UN designnotes
+.SH DESIGN NOTES
+.PP
+Real craters have two distinct morphologies.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamshadedrelief" (1)\c
+\&,
+.BR "ppmrelief" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&
+.BR "pam" (1)\c
+\&,
+
+
+.TP
+[1]
+Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images,
+New York: Springer Verlag, 1988.
+
+
+
+.UN author
+.SH AUTHOR
+.PP
+\fBpgmcrater\fP, from which this is derived, was written by John Walker:
+
+.nf
+John Walker
+Autodesk SA
+Avenue des Champs-Montants 14b
+CH-2074 MARIN
+Suisse/Schweiz/Svizzera/Svizra/Switzerland
+    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
+    \fBFax:\fP038/33 88 15
+    \fBVoice:\fP038/33 76 33
+
+.fi
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided
+"as is" without express or implied warranty.
+
+
+.UN history
+.SH HISTORY
+.PP
+John Walker wrote \fBpgmcrater\fP in 1991 and it was included in Pbmplus.
+\fBpgmcrater\fP did the equivalent of \f(CWpamcrater | pamshadedrelief\fP.
+In Netpbm 10.68 (September 2014), Bryan Henderson split the functions
+of \fBpgmcrater\fP into two programs, one (\fBpamcrater\fP) to compute
+elevations, and the other (\fBpamshadedrelief\fP) to generate a shaded relief
+visual image showing those elevations.  Bryan did this because it is more in
+keeping with Netpbm's modular architecture, and because
+the \fBpamshadedrelief\fP might be useful with other inputs.
+.PP
+(Like all Netpbm programs, \fBpgmcrater\fP was not static between the two
+events described above; minor changes, including replacement of most of the
+code, happened in between).
+.PP
+The original 1991 \fBpgmcrater\fP manual contains the following:
+
+.SS PLUGWARE!
+.PP
+If you like this kind of stuff, you may also enjoy "James Gleick's
+Chaos--The Software" for MS-DOS, available for $59.95 from your
+local software store or directly from Autodesk, Inc., Attn: Science
+Series, 2320 Marinship Way, Sausalito, CA 94965, USA.  Telephone:
+(800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext
+4886.  Fax: (415) 289-4718.  "Chaos--The Software" includes a more
+comprehensive fractal forgery generator which creates
+three-dimensional landscapes as well as clouds and planets, plus five
+more modules which explore other aspects of Chaos.  The user guide of
+more than 200 pages includes an introduction by James Gleick and
+detailed explanations by Rudy Rucker of the mathematics and algorithms
+used by each program.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamcrater.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamcut.1 b/upstream/mageia-cauldron/man1/pamcut.1
new file mode 100644
index 00000000..896d5db3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamcut.1
@@ -0,0 +1,244 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamcut User Manual" 0 "04 October 2019" "netpbm documentation"
+
+.SH NAME
+pamcut - cut a rectangle out of a PAM, PBM, PGM, or PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamcut\fP
+
+[\fB-left \fP\fIcolnum\fP]
+
+[\fB-right \fP\fIcolnum\fP]
+
+[\fB-top \fP\fIrownum\fP]
+
+[\fB-bottom \fP\fIrownum\fP]
+
+[\fB-width \fP\fIcols\fP]
+
+[\fB-height \fP\fIrows\fP]
+
+[\fB-pad\fP]
+
+[\fB-cropleft \fP\fInumcols\fP]
+
+[\fB-cropright \fP\fInumcols\fP]
+
+[\fB-croptop \fP\fInumrows\fP]
+
+[\fB-cropbottom \fP\fInumrows\fP]
+
+[\fB-verbose\fP]
+
+[\fIleft\fP \fItop\fP \fIwidth\fP \fIheight\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamcut\fP reads a PAM, PBM, PGM, or PPM image as input and
+extracts the specified rectangle, and produces the same kind of image
+as output.
+.PP
+You can specify either the rectangle to cut out and keep or specify the
+edges to crop off and discard, or a combination.
+.PP
+To request edges be cropped off, use options \fB-cropleft\fP,
+\fB-cropright\fP, \fB-croptop\fP, and \fB-cropbottom\fP to indicate how many
+rows or columns to discard.
+.PP
+For example, \fB-cropleft=50 -cropright=200\fP means to discard the
+leftmost 50 and rightmost 200 columns.
+.PP
+To specify the rectangle to keep, use \fB-left\fP, \fB-right\fP,
+\fB-top\fP, \fB-bottom\fP, \fB-width\fP, \fB-height\fP, and \fB-pad\fP
+options.
+.PP
+For example, \fB-left=50 -right=200\fP means to keep the 150 columns
+between Columns 50 and 200 inclusive.
+.PP
+You can code any mixture of the options.  What you don't specify defaults.
+Those defaults are in favor of minimal cutting and in favor of cutting the
+right and bottom edges off.  It is an error to overspecify, i.e. to specify
+all three of \fB-left\fP, \fB-right\fP, and \fB-width\fP or \fB-top\fP,
+\fB-bottom\fP, and \fB-height\fP or \fBright\fP as well as
+\fB-cropright\fP.
+.PP
+There is an older way to specify the rectangle to keep: positional
+arguments.  Arguments were the only way available before July 2000, but you
+should not use them in new applications.  Options are easier to remember and
+read, more expressive, and allow you to use defaults.
+.PP
+If you use both options and arguments, the two specifications get
+mixed in an unspecified way.
+.PP
+To use arguments, specify all four of the \fIleft\fP, \fItop\fP,
+\fIwidth\fP, and \fIheight\fP arguments.  \fIleft\fP and \fItop\fP have
+the same effect as specifying them as the argument of a \fB-left\fP or
+\fB-top\fP option, respectively.  \fIwidth\fP and \fIheight\fP have the
+same effect as specifying them as the argument of a \fB-width\fP or
+\fB-height\fP option, respectively, where they are positive.  Where they are
+not positive, they have the same effect as specifying one less than the value
+as the argument to a \fB-right\fP or \fB-bottom\fP option, respectively.
+(E.g. \fIwidth\fP = 0 makes the cut go all the way to the right edge).
+Before July 2000, negative numbers were not allowed for \fIwidth\fP and
+\fIheight\fP.
+.PP
+Input is from Standard Input if you don't specify the input file
+\fIpnmfile\fP.
+.PP
+Output is to Standard Output.
+.PP
+\fBpamcut\fP works on a multi-image stream.  It cuts each image in the
+stream independently and produces a multi-image stream output.  Before
+Netpbm 10.32 (March 2006), it ignored all but the first image in the stream.
+.PP
+If you are splitting a single image into multiple same-size images,
+\fBpamdice\fP is faster and easier than running \fBpamcut\fP
+multiple times.
+.PP
+\fBpamcomp\fP is also useful for cutting and padding an image to a
+certain size.  You create a background image of the desired frame
+dimensions and overlay the subject image on it.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamcut\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-left=\fP\fIcolnum\fP
+The column number of the leftmost column to be in the output.
+Columns left of this get cut out.  If a nonnegative number, it refers
+to columns numbered from 0 at the left, increasing to the right.  If
+negative, it refers to columns numbered -1 at the right, decreasing to
+the left.
+
+.TP
+\fB-right=\fP\fIcolnum\fP
+The column number of the rightmost column to be in the output,
+numbered the same as for \fB-left.\fP  Columns to the right of this
+get cut out.
+
+.TP
+\fB-top=\fP\fIrownum\fP
+The row number of the topmost row to be in the output.  Rows above
+this get cut out.  If a nonnegative number it refers to rows numbered
+from 0 at the top, increasing downward.  If negative, it refers to
+columns numbered -1 at the bottom, decreasing upward.
+
+.TP
+\fB-bottom=\fP\fIrownum\fP
+The row number of the bottom-most row to be in the output,
+numbered the same as for \fB-top\fP.  Rows below this get cut out.
+
+.TP
+\fB-width=\fP\fIcols\fP
+The number of columns to be in the output.  Must be positive.
+
+.TP
+\fB-height=\fP\fIrows\fP
+The number of rows to be in the output.  Must be positive.
+
+.TP
+\fB-cropleft\fP
+.TP
+\fB-cropright\fP
+.TP
+\fB-croptop\fP
+.TP
+\fB-cropbottom\fP
+These options tell how many rows or columns to crop from the left,
+right, top, or bottom edges, respectively.
+.sp
+The value must not be negative.
+.sp
+These option were new in Netpbm 10.85 (December 2018).  Before that, you
+can achieve the same thing with \fB-left\fP, \fBtop\fP, and negative values
+for \fB-right\fP and \fB-bottom\fP.  Remember to subtract one in the latter
+case; e.g. the equivalent of \fB-cropright=1\fP is \fB-right=-2\fP.
+  
+.TP
+\fB-pad\fP
+If the rectangle you specify is not entirely within the input
+image, \fBpamcut\fP fails unless you also specify \fB-pad\fP.  In
+that case, it pads the output with black up to the edges you specify.
+You can use this option if you need to have an image of certain
+dimensions and have an image of arbitrary dimensions.
+.sp
+\fBpnmpad\fP also adds borders to an image, but you specify their
+width directly.
+.sp
+\fBpamcomp\fP does a more general form of this padding.  Create a
+background image of the frame dimensions and overlay the subject image
+on it.  You can use options to have the subject image in the center of
+the frame or against any edge and make the padding any color (the padding
+color is the color of the background image).
+
+.TP
+\fB-verbose\fP
+Print information about the processing to Standard Error.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmcrop" (1)\c
+\&,
+.BR "pamdice" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pnmpad" (1)\c
+\&,
+.BR "pamcat" (1)\c
+\&,
+.BR "pgmslice" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamcut\fP was derived from \fBpnmcut\fP in Netpbm 9.20 (May 2001).
+It was the first Netpbm program adapted to the new PAM format and programming
+library.
+.PP
+The predecessor \fBpnmcut\fP was one of the oldest tools in the Netpbm
+package.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamcut.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamdeinterlace.1 b/upstream/mageia-cauldron/man1/pamdeinterlace.1
new file mode 100644
index 00000000..8f5ced4c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamdeinterlace.1
@@ -0,0 +1,99 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamdeinterlace User Manual" 0 "11 November 2001" "netpbm documentation"
+
+.SH NAME
+
+pamdeinterlace - remove every other row from a PAM/PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamdeinterlace\fP
+
+[\fB-takeodd\fP]
+
+[\fB-takeeven\fP]
+
+[\fIinfile\fP]
+.PP
+You can use the minimum unique abbreviation of the options.  You
+can use two hyphens instead of one.  You can separate an option name
+from its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamdeinterlace\fP removes all the even-numbered or odd-numbered
+rows from the input PNM or PAM image.  Specify which with the
+\fB-takeeven\fP and \fB-takeodd\fP options.
+.PP
+This can be useful if the image is a video capture from an
+interlaced video source.  In that case, each row shows the subject
+1/60 second before or after the two rows that surround it.  If the
+subject is moving, this can detract from the quality of the image.
+.PP
+Because the resulting image is half the height of the input image,
+you will then want to use \fBpamstretch\fP or \fBpamscale\fP to
+restore it to its normal height:
+
+.nf
+\f(CW
+pamdeinterlace myimage.ppm | pamstretch -yscale=2 >newimage.ppm
+\fP
+
+.fi
+.PP
+Another, usually better, way to deinterlace an image is with
+\fBpammixinterlace\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamdeinterlace\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-takeodd\fP
+Take the odd-numbered rows from the input and put them in the
+output.  The rows are numbered starting at zero, so the first row in
+the output is the second row from the input.  You cannot specify both
+\fB-takeeven\fP and \fB-takeodd\fP.
+
+.TP
+\fB-takeeven\fP
+Take the even-numbered rows from the input and put them in the
+output.  The rows are numbered starting at zero, so the first row in
+the output is the first row from the input.  This is the default.  You
+cannot specify both \fB-takeeven\fP and \fB-takeodd\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pammixinterlace" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamdeinterlace.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamdepth.1 b/upstream/mageia-cauldron/man1/pamdepth.1
new file mode 100644
index 00000000..3ed15285
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamdepth.1
@@ -0,0 +1,109 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamdepth User Manual" 0 "26 August 2020" "netpbm documentation"
+
+.SH NAME
+
+pamdepth - change the depth (color resolution) in a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamdepth\fP \fInewmaxval\fP [\fInetpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamdepth\fP reads a Netpbm image as input, changes its depth (color
+resolution), and writes out the resulting Netpbm image.  I.e. the output has a
+different maxval from the input, but all the same colors (apart from rounding
+error).
+.PP
+Reducing the depth results in some loss of information.
+.PP
+Here is an example of the effect at the image format level: Assume you
+start with an image with maxval 100 and sample values of 50 and 100.  You
+tell \fBpamdepth\fP to change it to depth 150.  The output has maxval
+200 and sample values 75 and 150.
+.PP
+This program works on multi-image streams.
+.PP
+Be careful of off-by-one errors when choosing the new maxval.  For
+instance, if you want the color values to be five bits wide, use a
+maxval of 31, not 32.
+.PP
+One important use of \fBpamdepth\fP is to convert a new format
+2-byte-per-sample PNM file to the older 1-byte-per-sample format.
+Before April 2000, essentially all raw (binary) format PNM files had a
+maxval less than 256 and one byte per sample, and many programs may
+rely on that.  If you specify a \fInewmaxval\fP less than 256, the
+resulting file should be readable by any program that worked with PNM
+files before April 2000.
+
+.UN output_format
+.SS Output Format
+.PP
+The output format (PBM, etc.) and, in the case of PAM, tuple type, of the
+output is usually the same as the input.
+.PP
+However, changing the depth of a black and white image does not make
+sense, except to turn it into a grayscale image, so if the input is a black
+and white image, \fBpamdepth\fP makes the output grayscale.  To be more
+precise, if the input is a PBM image, the output is PGM, and if the input
+is a PAM with tuple type BLACK_AND_WHITE or BLACK_AND_WHITE_ALPHA, the
+output is a PAM with tuple type GRAYSCALE or GRAYSCALE_ALPHA, respectively.
+.PP
+This conversion happens even if the new maxval is 1.
+.PP
+Before Netpbm 10.92 (September 2020), \fBpamdepth\fP failed if the input
+was PAM with a black and white tuple type and the new maxval was anything but
+1.  But it always promoted PBM to PGM.
+
+  
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamdepth\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&
+.BR "pambrighten" (1)\c
+\&
+.BR "pamfunc" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamdepth\fP was new in Netpbm 10.32 (February 2006).  It replaced
+\fBpnmdepth\fP, by Jef Poskanzer.  \fBpamdepth\fP is backward compatible
+with \fBpnmdepth\fP and adds the ability to process arbitrary PAM images
+and the ability to process multi-image input streams.  \fBpnmdepth\fP
+handled only PNM images and ignored all but the first in any stream.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamdepth.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamdice.1 b/upstream/mageia-cauldron/man1/pamdice.1
new file mode 100644
index 00000000..e994ac43
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamdice.1
@@ -0,0 +1,171 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamdice User Manual" 0 "01 April 2007" "netpbm documentation"
+
+.SH NAME
+pamdice - slice a Netpbm image into many horizontally and/or vertically
+
+.UN example
+.SH EXAMPLE
+
+.nf
+\f(CW
+    $ pamdice myimage.ppm -outstem=myimage_part -width=10 -height=8
+    $ pamundice myimage_part_%1d_%1a.ppm -across=10 -down=8 >myimage.ppm
+
+    $ pamdice myimage.ppm -outstem=myimage_part -height=12 -voverlap=9
+\fP
+
+.fi
+
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamdice\fP
+
+\fB-outstem=\fP\fIfilenamestem\fP
+
+[\fB-width=\fP\fIwidth\fP]
+
+[\fB-height=\fP\fIheight\fP]
+
+[\fB-hoverlap=\fP\fIhoverlap\fP]
+
+[\fB-voverlap=\fP\fIvoverlap\fP]
+
+[\fB-verbose\fP]
+
+[\fIfilename\fP]
+.PP
+You can use the minimum unique abbreviation of the options.  You can use
+two hyphens instead of one.  You can separate an option name from its value
+with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamdice\fP reads a PAM, PBM, PGM, or PPM image as input and
+splits it horizontally and/or vertically into equal size pieces and
+writes them into separate files as the same kind of image.  You can
+optionally make the pieces overlap.
+.PP
+See the \fB-outstem\fP option for information on naming of the
+output files.
+.PP
+The \fB-width\fP and \fB-height\fP options determine the size of
+the output pieces.
+.PP
+\fBpamundice\fP can rejoin the images.  For finer control, you can
+also use 
+.PP
+\fBpnmcat\fP.
+.PP
+One use for this is to make pieces that take less computer resources
+than the whole image to process.  For example, you might have an image
+so large that an image editor can't read it all into memory or processes
+it very slowly.  With \fBpamdice\fP, you can split it into smaller pieces,
+edit one at a time, and then reassemble them.
+.PP
+Another use for this is to print a large image in small printer-sized
+pieces that you can glue together.  \fBppmglobe\fP does a similar thing;
+it lets you glue the pieces together into a sphere.
+.PP
+If you want to cut pieces from an image individually, not in a regular
+grid, use \fBpamcut\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamdice\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-outstem=\fPfilenamestem
+This option determines the names of the output files.  Each output
+file is named
+\fIfilenamestem\fP\fB_\fP\fIy\fP\fB_\fP\fIx\fP\fB.\fP\fItype\fP
+where \fIfilenamestem\fP is the value of the \fB-outstem\fP option,
+\fIx\fP and y are the horizontal and vertical locations,
+respectively, in the input image of the output image, zero being the
+leftmost and top, and \fItype\fP is \fB.pbm\fP, \fB.pgm\fP,
+\fB.ppm\fP, or \fB.pam\fP, depending on the type of image.
+
+.TP
+\fB-width=\fP\fIwidth\fP
+gives the width in pixels of the output images.  The rightmost
+pieces are smaller than this if the input image is not a multiple of
+\fIwidth\fP pixels wide.
+
+.TP
+\fB-height=\fP\fIheight\fP
+gives the height in pixels of the output images.  The bottom
+pieces are smaller than this if the input image is not a multiple of
+\fIheight\fP pixels high.
+
+.TP
+\fB-hoverlap=\fP\fIhoverlap\fP
+gives the horizontal overlap in pixels between output images.
+Each image in a row will overlap the previous one by \fIhoverlap\fP
+pixels.  By default, there is no overlap.
+.sp
+This option was new in Netpbm 10.23 (July 2004).
+
+.TP
+\fB-voverlap=\fP\fIvoverlap\fP
+gives the vertical overlap in pixels between output images.
+Each row of images will overlap the previous row by \fIvoverlap\fP
+pixels.  By default, there is no overlap.
+.sp
+This option was new in Netpbm 10.23 (July 2004).
+
+.TP
+\fB-verbose\fP
+Print information about the processing to Standard Error.
+
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamdice\fP was new in Netpbm 9.25 (March 2002).
+.PP
+Before Netpbm 10.29 (August 2005), there was a limit of 100 slices
+in each direction.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamundice" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pgmslice" (1)\c
+\&,
+.BR "ppmglobe" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamdice.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamditherbw.1 b/upstream/mageia-cauldron/man1/pamditherbw.1
new file mode 100644
index 00000000..c60ace76
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamditherbw.1
@@ -0,0 +1,223 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamditherbw User Manual" 0 "10 May 2010" "netpbm documentation"
+
+.SH NAME
+
+pamditherbw - dither grayscale image to black and white
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamditherbw\fP
+
+[\fB-floyd\fP | \fB-fs\fP
+| \fB-atkinson\fP
+| \fB-threshold\fP
+| \fB-hilbert\fP
+| \fB-dither8\fP | \fB-d8\fP | \fB-cluster3\fP
+| \fB-c3\fP | \fB-cluster4\fP | \fB-c4\fP
+| \fB-cluster8\fP | \fB-c8\fP]
+
+[\fB-value\fP \fIval\fP]
+
+[\fB-clump\fP \fIsize\fP]
+
+[\fB-randomseed=\fP\fIinteger\fP]
+
+[\fIpamfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamditherbw\fP dithers a grayscale image.  Dithering means turning
+each shade of gray into a pattern of black and white pixels that, from
+a distance, look the same as the gray.
+.PP
+The input should be a PGM image or a PAM image of tuple type
+GRAYSCALE.  However, \fBpamditherbw\fP doesn't check, so if you feed
+it e.g. a PPM image, it will produce arbitrary results (actually, it
+just takes the first channel of whatever you give it and treats it as
+if it represented gray levels).
+.PP
+The output is a PAM with tuple type BLACKANDWHITE.  You can turn
+this into a PBM (if you need to use it with an older program that doesn't
+understand PAM) with \fBpamtopnm\fP.
+.PP
+To do the opposite of dithering, you can usually just scale the image
+down and then back up again with \fBpamscale\fP, possibly smoothing or
+blurring the result with \fBpnmsmooth\fP or \fBpnmconvol\fP.  Or use
+the special case program \fBpbmtopgm\fP.
+.PP
+To dither a color image (to reduce the number of pixel colors),
+use \fBppmdither\fP.
+.PP
+Another way to convert a grayscale image to a black and white image
+is thresholding.  Thresholding is simply replacing each grayscale pixel
+with a black or white pixel depending on whether its brightness is above or
+below a threshold.  That threshold might vary.  Simple thresholding is a
+degenerate case of dithering, so \fBpamditherbw\fP does very simple
+thresholding with its \fB-threshold\fP option.  But \fBpamthreshold\fP
+does more sophisticated thresholding.
+.PP
+If all you want is to change a PGM image with maxval 1 to a PBM image,
+\fBpamtopnm\fP will do that.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamditherbw\fP recognizes the following
+command line options:
+
+.UN quantmethod
+.SS Quantization Method
+.PP
+The default quantization method is boustrophedonic Floyd-Steinberg
+error diffusion (\fB-floyd\fP or \fB-fs\fP).
+.PP
+Also available are simple thresholding (\fB-threshold\fP); Bayer's
+ordered dither (\fB-dither8\fP) with a 16x16 matrix;
+.UR http://www.tinrocket.com/projects/programming/graphics/00158/
+ Atkinson
+.UE
+\&; and three different sizes of 45-degree clustered-dot
+dither (\fB-cluster3\fP, \fB-cluster4\fP, \fB-cluster8\fP).
+.PP
+A space filling curve halftoning method using the Hilbert curve is
+also available (\fB-hilbert\fP).
+.PP
+Floyd-Steinberg or Atkinson will almost always give the best
+looking results; however, looking good is not always what you want.
+For instance, you can use thresholding in a pipeline with the
+\fBpnmconvol\fP, for tasks such as edge and peak detection.  And
+clustered-dot dithering gives a newspaper-ish look, a useful special
+effect.
+.PP
+Floyd-Steinberg is by far the more traditional, but
+.UR http://www.tinrocket.com/projects/programming/graphics/00158/
+ some claim
+.UE
+\& Atkinson works better.
+.PP
+The Hilbert curve method is useful for processing images before
+display on devices that do not render individual pixels distinctly
+(like laser printers).  This dithering method can give better results
+than the dithering usually done by the laser printers themselves.  The
+\fB-clump\fP option alters the number of pixels in a clump.  Typically a PGM
+image will have to be scaled to fit on a laser printer page (2400 x 3000
+pixels for an A4 300 dpi page), and then dithered to a PBM image before being
+converted to a postscript file.  A printing pipeline might look something
+like:
+
+.nf
+    pamscale -xysize 2400 3000 image.pgm | pamditherbw -hilbert |  \e
+      pamtopnm | pnmtops -scale 0.25 > image.ps 
+
+.fi
+
+.UN otheropts
+.SS Other Options
+
+
+
+.TP
+\fB-value\fP
+This option alters the thresholding value for Floyd-Steinberg,
+Atkinson, and simple thresholding.  It should be a real number between
+0 and 1.  Above 0.5 means darker images; below 0.5 means lighter.
+
+.TP
+\fB-clump\fP
+This option alters the number of pixels in a clump when the
+Hilbert curve method is used.  This is usually an integer between 2
+and 100 (default 5).  Smaller clump sizes smear the image less and are
+less grainy, but seem to lose some grey scale linearity.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+The Floyd-Steiberg and Atkinson methods use random numbers to
+diffuse the error.  This is the seed for the random number generator.
+The other methods do not employ random numbers and ignore this option.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpamditherbw\fP uses a seed derived from the time of day
+and process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+.sp
+This option was new in Netpbm 10.45 (December 2008).
+
+
+
+
+.UN references
+.SH REFERENCES
+.PP
+The only reference you need for this stuff is "Digital
+Halftoning" by Robert Ulichney, MIT Press, ISBN 0-262-21009-6.
+.PP
+The Hilbert curve space filling method is taken from "Digital
+Halftoning with Space Filling Curves" by Luiz Velho, Computer
+Graphics Volume 25, Number 4, proceedings of SIGRAPH '91, page
+81. ISBN 0-89791-436-8
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pgmtopgm" (1)\c
+\&,
+.BR "pbmtopgm" (1)\c
+\&,
+.BR "pamthreshold" (1)\c
+\&,
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamditherbw\fP was new in Netpbm 10.23 (July 2004), but is
+essentially the same program as \fBpgmtopbm\fP that has existed
+practically since the beginning.  \fBpamditherbw\fP differs from its
+predecessor in that it properly adds brightnesses (using gamma
+transformations; \fBpgmtopbm\fP just adds them linearly) and that it
+accepts PAM input in addition to PGM and PBM and produces PAM output.
+.PP
+\fBpamditherbw\fP obsoletes \fBpgmtopbm\fP.
+.PP
+\fB-atkinson\fP was new in Netpbm 10.38 (March 2007).
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamditherbw.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamedge.1 b/upstream/mageia-cauldron/man1/pamedge.1
new file mode 100644
index 00000000..faac75e8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamedge.1
@@ -0,0 +1,91 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamedge User Manual" 0 "11 January 2003" "netpbm documentation"
+
+.SH NAME
+pamedge - edge-detect an image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamedge\fP [\fIimagefile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamedge\fP reads a Netpbm image (PNM or PAM) and produces
+an image that outlines the edges.
+.PP
+The output image is of the same type as the input, except that the
+maxval of the output is at least 255 and if the input is PBM, the output
+is PGM.
+.PP
+You can pipe the result through \f(CWpamditherbw -threshold\fP and
+play with the threshold value to get a PBM (bilevel image) of the edges.
+
+The edge detection technique used is to take the Pythagorean sum of
+two Sobel gradient operators at 90 degrees to each other.  For more
+details see "Digital Image Processing" by Gonzalez and
+Wintz, chapter 7.
+.PP
+The maxval of the output is the same as the maxval of the input, except at
+least 255.  The effect is better with larger maxvals, so you may want to
+increase the maxval of the input by running it through \fBpamdepth\fP first.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamedge\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmenhance" (1)\c
+\&,
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pammasksharpen" (1)\c
+\&,
+.BR "pamsharpness" (1)\c
+\&,
+.BR "pamsharpmap" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamedge\fP was added to Netpbm in Release 10.14 (March 2003).
+It replaced \fBpgmedge\fP, which was the same thing, but worked only on
+PGM and PBM images.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.  Adapted to \fBpnmedge\fP Peter
+Kichgessner in 1995, and then to \fBpamedge\fP by Bryan Henderson in
+2003.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamedge.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamendian.1 b/upstream/mageia-cauldron/man1/pamendian.1
new file mode 100644
index 00000000..9e185573
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamendian.1
@@ -0,0 +1,89 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamendian User Manual" 0 "16 March 2002" "netpbm documentation"
+
+.SH NAME
+
+pamendian - reverse endianness of a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamendian\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+All Netpbm formats that have samples in pure binary format with multiple
+bytes are defined to have them in big endian (most significant byte first)
+order.  However, there exist variations on these formats, primarily developed
+before official multibyte Netpbm formats existed, that are identical to 
+Netpbm formats in every respect except that samples are in little endian
+(least significant byte first) order.
+.PP
+\fBpamendian\fP reverses the byte order of the sample to convert
+between the two formats.  If the input is true PAM, PGM, or PPM, the
+output is the little endian variation on that format, and vice versa.
+.PP
+The X Window System viewer \fBxv\fP expects the little endian variation
+of PGM and PPM.
+.PP
+Programs that come with the Independent Jpeg Group's JPEG library
+are known to use the little endian variation of PGM and PPM.
+.PP
+The reason some programs use this variant is that at one time
+during Netpbm's
+.BR "dark age" (1)\c
+\&, there
+was a version of Netpbm around that used it.  But it was never
+formally specified.
+.PP
+This program takes input only on Standard Input.  Its output is
+always on Standard Output.
+.PP
+You should never have to use this program with images generated by
+programs in the Netpbm package or programs that use the Netpbm
+libraries.  If you do, that probably means something needs to be fixed
+in those programs.  The Netpbm converter for any graphics format that
+represents numbers in little endian form should properly reverse the
+bytes to create correct Netpbm output.
+.PP
+If you create a Netpbm image from a generic stream of samples,
+using \fBrawtopgm\fP or \fBrawtoppm\fP, use options on those
+programs to declare the endianness of your input, thus creating
+correct endianness in your PGM or PPM output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamendian\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamdepth" (1)\c
+\&,
+.BR "rawtopgm" (1)\c
+\&,
+.BR "rawtoppm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamendian.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamenlarge.1 b/upstream/mageia-cauldron/man1/pamenlarge.1
new file mode 100644
index 00000000..fc9e56ae
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamenlarge.1
@@ -0,0 +1,160 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamenlarge User Manual" 0 "07 January 2019" "netpbm documentation"
+
+.SH NAME
+pamenlarge - Enlarge a Netpbm image N times by duplicating pixels
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamenlarge\fP
+[\fB-scale=\fP\fIinteger\fP]
+[\fB-xscale=\fP\fIinteger\fP]
+[\fB-yscale=\fP\fIinteger\fP]
+[\fIfilename\fP]
+
+\fBpamenlarge\fP \fIN\fP [\fIpnmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamenlarge\fP reads a Netpbm image as input, replicates its pixels
+\fIN\fP times, and produces a Netpbm image as output.  The output is
+the same type of image as the input.
+.PP
+If you enlarge by a factor of 3 or more, you should probably add a
+\fBpnmsmooth\fP step; otherwise, you can see the original pixels in
+the resulting image.
+.PP
+For PBM images, \fBpamenlarge\fP uses special fast algorithms for scale
+factors up to 10.  For larger factors, it uses a simple but slow algorithm.
+As a result, you can often get a significantly faster scale by running
+\fBpamenlarge\fP multiple times.  For example, enlarging by 3 and
+then by 5 is faster than enlarging once by 15.  And because the algorithms
+are different for the different scale factors, some faster than others,
+the order matters too.  For example, the following examples all produce
+the same output -- an image 15 times bigger on edge than the input --
+but at different speeds, each being faster than the one before.
+
+.nf
+\f(CW
+     $ pamenlarge -scale=15 test.pbm
+     $ pamenlarge -scale=5 test.pbm | pamenlarge -scale=3
+     $ pamenlarge -scale=3 test.pbm | pamenlarge -scale=5
+\fP
+
+.fi
+.PP
+The special fast cases for factors up to 10 have existed since Release
+10.50 (March 2010).  The special cases for 1, 2, 3, and 5 go back to Release
+10.41 (December 2007).  Before 10.41, there are no special scale factors and
+PBM enlargement is significantly slower than today for all scale factors.
+.PP
+\fBpamenlarge\fP can enlarge only by integer factors.  The slower
+but more general \fBpamscale\fP can enlarge or reduce by arbitrary
+factors.  \fBpamscale\fP allows you to enlarge by resampling, which
+gives you smoother enlargements.  But it is much slower.
+.PP
+\fBpamstretch\fP is another enlarging program that enlarges by
+integer factors.  It does a simple kind of resampling that gives you a
+smoothed enlargement with less computational cost.
+.PP
+\fBpbmreduce\fP can reduce by integer factors, but only for PBM
+images.
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+As with most Netpbm programs, you can give the input file name as an
+argument or omit that argument and have it come from Standard Input (and
+you can specify '-' for the argument to specify Standard Input
+explicitly).
+.PP
+You can also specify the scale factor as an argument, for backward
+compatibility, but the preferred way to do that is with a \fB-scale\fP
+option, because it is easier to remember and read that way.  The scale factor
+argument goes before the file name argument.
+
+
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamenlarge\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-scale=\fP\fIinteger\fP
+.TP
+\fB-xscale=\fP\fIinteger\fP
+.TP
+\fB-yscale=\fP\fIinteger\fP
+These specify the scale factor.  \fB-xscale\fP specifies the horizontal
+scale factor; \fB-yscale\fP specifies the vertical scale factor
+and \fB-scale\fP specifies both.
+.sp
+If you specify \fB-xscale\fP but not \fB-yscale\fP, \fBpamenlarge\fP
+does not scale vertically (i.e. the vertical scale factor is 1).  The converse
+applies if you specify \fB-yscale\fP and not \fB-xscale\fP.
+.sp
+You cannot specify \fB-scale\fP and also \fB-xscale\fP or \fByscale\fP.
+.sp
+You must specify at least one of these options, unless you use the
+deprecaated method of specifying the scale factor via argument.
+.sp
+These options were all new in Netpbm 10.86 (March 2019).  Before that, use
+the scale argument.
+  
+
+
+  
+.UN history
+.SH HISTORY
+.PP
+\fBpamenlarge\fP was new in Netpbm 10.25 (October 2004).  It is
+designed as a replacement for \fBpnmenlarge\fP by Jef Poskanzer,
+which was in Pbmplus as far back as 1989.  The major difference is that
+\fBpamenlarge\fP can enlarge PAM format images in addition to PNM.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamstretch" (1)\c
+\&,
+.BR "pbmpscale" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamenlarge.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamexec.1 b/upstream/mageia-cauldron/man1/pamexec.1
new file mode 100644
index 00000000..4071b842
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamexec.1
@@ -0,0 +1,130 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamexec User Manual" 0 "21 December 2021" "netpbm documentation"
+
+.SH NAME
+pamexec - Execute a shell command on each image in a Netpbm image stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamexec\fP
+
+["\fIcommand\fP"]
+
+[\fInetpbmfile\fP]
+
+[\fB-check\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamexec\fP reads a Netpbm image stream as input.  For each image, it
+runs a specified shell command and supplies the image to it as Standard
+Input (with a pipe).
+.PP
+\fInetpbmfile\fP is the file name of the input file, or
+\fB-\fP to indicate Standard Input.  The default is Standard Input.
+.PP
+Many Netpbm programs understand multimage Netpbm streams themselves, so you
+don't need to use \fBpamexec\fP to run the program on the images in the
+stream.  Ideally, all Netpbm programs would have that capability, but
+multi-image streams are a relatively recent invention, so older Netpbm
+programs just process the first image in the stream and then stop.  Even many
+recently written Netpbm programs work that way, since the authors aren't aware
+of the multi-image possibility.
+.PP
+Another way to process a multi-image stream is to use \fBpamsplit\fP to
+explode it into multiple files, one image per file.  You can then process
+those files.
+.PP
+To run your command on a subset of the images in the stream, use
+\fBpampick\fP to select the desired images from the input stream and pipe
+the result to \fBpamexec\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamexec\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-check\fP
+This causes \fBpamexec\fP to exit without processing any further images
+if the command has a nonzero exit status.
+
+
+
+.UN applications
+.SH APPLICATIONS
+
+To make an animated GIF movie:
+
+.nf
+\f(CW
+    pamexec pamtogif myvideo.ppm | gifsicle --multifile >myvideo.gif
+\fP
+
+.fi
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBpamexec\fP assumes all commands consume all of Standard Input.
+If yours doesn't (perhaps it just exits when it's seen enough),
+  you can buffer through a temporary file like this, which copies the
+  first 3 lines of every image (the PPM header) to Standard Output:
+
+.nf
+\f(CW
+    pamexec "cat >/tmp/x; head --lines=3 x" myvideo.ppm  
+\fP
+
+.fi
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamexec\fP was new in Netpbm 10.56 (September 2011).
+.PP
+Michael Pot wrote it, borrowing from \fBpamsplit\fP.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&,
+.BR "pampick" (1)\c
+\&,
+.BR "pamsplit" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+\fBcat\fP man page
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamexec.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamfile.1 b/upstream/mageia-cauldron/man1/pamfile.1
new file mode 100644
index 00000000..8119acba
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamfile.1
@@ -0,0 +1,174 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamfile User Manual" 0 "04 July 2020" "netpbm documentation"
+
+.SH NAME
+pamfile - describe a Netpbm (PAM or PNM) file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamfile\fP
+
+[\fB-allimages\fP]
+[\fB-comments\fP]
+[\fB-count\fP]
+[\fB-machine\fP]
+[\fB-size\fP]
+
+[\fIfile\fP ...]
+.PP
+Minimum unique abbreviations of options are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamfile\fP reads one or more Netpbm files as input and writes
+out short descriptions of the image type, size, etc.  This is partly
+for use in shell scripts, so the format is not particularly pretty.
+.PP
+By default, \fBpamfile\fP reads only the header of the input file.
+If that file is a pipe, that might cause problems for the process that is
+feeding the pipe.  In that case, see the \fB-allimages\fP option.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamfile\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-allimages\fP
+This option causes \fBpamfile\fP to describe every image in each
+input file.  Without this option, \fBpamfile\fP describes only the
+first image in each input file.
+.sp
+This option also causes \fBpamfile\fP to read all the images from 
+the input stream, whereas without it, \fBpamfile\fP reads only the header
+of the first one.  If the input stream is from a pipe, the process that is
+feeding the pipe might require the entire stream to be consumed.  In
+that case, use this option even if the stream contains only one image.
+.sp
+This option has no effect if you also specify \fB-count\fP.
+.sp
+Note that before July 2000, a file could not contain more than one
+image and many programs ignore all but the first.
+.sp
+This option was new in Netpbm 9.5 (July 2000).
+
+.TP
+\fB-comments\fP
+This option causes \fBpamfile\fP to include for each PAM image
+a report of the comments from the header of the image.
+.sp
+For a PBM, PGM, or PPM image, \fBpamfile\fP reports there are no
+comments, even if there are.
+.sp
+This option was new in Netpbm 10.35 (August 2006).
+
+.TP
+\fB-count\fP
+This option causes \fBpamfile\fP to display only a count of how many
+images are in each input file.
+.sp
+As with \fB-allimages\fP, this causes \fBpamfile\fP to read all the
+images.
+.sp
+You may specify at most one of \fB-count\fP, \fB-machine\fP,
+and \fB-size\fP.
+.sp
+This option was new with Netpbm 10.31 (December 2005).
+
+.TP
+\fB-machine\fP
+This makes the output more convenient for a machine to use, while
+  less convenient for a human.  \fBpamfile\fP reports the same information
+  as with no options.
+.sp
+The output is one line of ASCII text per image.  Each line consists of
+     the file name, followed by a colon, followed by a space, then the
+     following tokens with a space in between:
+
+    
+.IP \(bu
+Format: 'PAM', 'PBM', 'PGM', or
+        'PPM',
+.IP \(bu
+Subformat: 'PLAIN' or 'RAW'
+.IP \(bu
+Width: in pixels, in decimal
+.IP \(bu
+Height: in pixels, in decimal
+.IP \(bu
+Depth: in decimal
+.IP \(bu
+Maxval: in decimal (1 if image is PBM)
+.IP \(bu
+Tuple type (emulated if the image is not PAM)
+    
+.sp
+You may specify at most one of \fB-count\fP, \fB-machine\fP,
+and \fB-size\fP.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-size\fP
+This makes the output contain only the height and width of the image,
+in a form convenient for machine processing.
+.sp
+There is one line of output per image, consising of two blank-delimited
+tokens:
+
+
+.IP \(bu
+Width: in pixels, in decimal
+.IP \(bu
+Height: in pixels, in decimal
+  
+.sp
+Note that there is no way to tell which image is in which file, if you have
+multiple input files with multiple images.  If that is your case,
+use \fB-machine\fP instead.
+.sp
+You may specify at most one of \fB-count\fP, \fB-machine\fP, and
+\fB-size\fP.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+\fBfile\fP
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamfile.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamfind.1 b/upstream/mageia-cauldron/man1/pamfind.1
new file mode 100644
index 00000000..adaea428
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamfind.1
@@ -0,0 +1,127 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamfind User Manual" 0 "13 March 2019" "netpbm documentation"
+
+.SH NAME
+pamfind - Print the locations of all tuples of a certain value in an image
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamfind\fP
+{
+\fB-target=\fP\fIsample0\fP\fB,\fP\fIsample1\fP\fB,\fP ... |
+\fB-color=\fP\fIcolor\fP
+}
+[\fB-machine\fP]
+[\fIimagefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamfind\fP reads a Netpbm image (PNM or PAM) and prints a list of all
+the locations (row and column) of the tuples that have a value you specify.
+For example, you can list all the places that a visual image is red.
+.PP
+You can specify the value in actual decimal sample values with
+a \fB-target\fP option or as a color with \fB-color\fP.  If you
+specify \fB-color\fP, the program fails if the input image does not have
+depth 3.  If it has depth 3 but the tuples aren't actually colors, you get
+results as if they are.
+.PP
+To do the opposite, see what tuple is at a given location, use
+\fBpamcut\fP and \fBpamtable\fP:
+
+.nf
+    
+      $ pamcut -left=5 -top=7 -width=1 -height=1 | pamtable
+    
+
+.fi
+.PP
+\fBppmcolormask\fP also finds all the tuples of a certain value, at least
+in visual images, but instead of printing their coordinates, it generates a
+mask image, which you can use to visualize where those tuples are or as input
+to another program.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamfind\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-target=\fP\fIsample0\fP\fB,\fP\fIsample1\fP\fB,\fP ... |
+This specifies the tuple value to find.  You specify the sample values in
+order, and must specify the proper number of sample values for the depth of
+the image (e.g. 3 if it is a color image).
+.sp
+You must specify exactly one of \fB-target\fP and \fB-color\fP.
+
+.TP
+\fB-color=\fP\fIcolor\fP
+This is the color to find, assuming the image is a color visual image.
+.sp
+\fIcolor\fP is as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+You must specify exactly one of \fB-target\fP and \fB-color\fP.
+
+.TP
+\fB-machine\fP
+This makes the output more convenient for a machine to use, while
+  less convenient for a human.  \fBpamfind\fP reports the same information
+  as with no options.
+.sp
+This option was new in Netpbm 10.87 (March 2020).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamdepth" (1)\c
+\&,
+.BR "pamgetcolor" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "ppmcolormask" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamtable" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamfind\fP was added to Netpbm in Release 10.86 (March 2019).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamfind.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamfix.1 b/upstream/mageia-cauldron/man1/pamfix.1
new file mode 100644
index 00000000..168fc29c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamfix.1
@@ -0,0 +1,180 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamfix User Manual" 0 "06 March 2014" "netpbm documentation"
+
+.SH NAME
+
+pamfix - repair a Netpbm image with various corruptions
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamfix\fP
+
+[\fB-truncate\fP]
+[\fB-changemaxval\fP]
+[\fB-clip\fP]
+[\fB-verbose\fP]
+
+[\fInetpbmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamfix\fP reads a stream that is mostly a Netpbm image but may have
+certain types of corruptions and produces a valid Netpbm image that preserves
+much of the information in the original.
+
+In particular, Netpbm salvages streams that are truncated and that contain
+illegally large sample values.
+.PP
+\fBpamfix\fP looks at only on the first image in a multi-image stream.
+
+
+.UN truncatedstream
+.SS Truncated Stream
+.PP
+This is a stream that is missing the last part.  Netpbm corrects this
+by creating an output image that simply has fewer rows.
+.PP
+You select this kind of repair with a \fB-truncate\fP option.
+.PP
+The header of a Netpbm image implies how large the image must
+be (how many bytes the file must contain).  If the file is actually
+smaller than that, a Netpbm program that tries to read the image
+fails, with an error message telling you that it couldn't read the
+whole file.  The data in the file is arranged in row order, from
+top to bottom, and the most common reason for the file being smaller
+than its header says it should be is because the bottommost rows are
+simply missing.  So \fBpamfix\fP assumes that is the case
+and generates a new image with just the rows that are readable.
+(technically, that means the output's header indicates a smaller
+number of rows and omits any partial last row).
+.PP
+The most common way for a Netpbm file to be small is that something
+interrupted the program that generated it before it was finished writing
+the file.  For example, the program ran out of its own input or
+encountered a bug or ran out of space in which to write the output.
+.PP
+Another problem \fBpamfix\fP deals with is where the file isn't
+actually too small, but because of a system error, a byte in the middle of
+it cannot be read (think of a disk storage failure).  \fBpamfix\fP
+reads the input sequentially until it can't read any further, for any
+reason.  So it treats such an image as a truncated one, ignoring all
+data after the unreadable byte.
+.PP
+But be aware that an image file is sometimes too small because of a
+bug in the program that generated it, and in that case it is not
+simply a matter of the bottom of the image missing, so
+\fBpamfix\fP simply creates a valid Netpbm image containing a
+garbage picture.
+.PP
+If you want to test an image file to see if it is corrupted by being
+too small, use \fBpamfile --allimages\fP .  It fails with an error
+message if the file is too small.
+.PP
+If you want to cut the bottom off a valid Netpbm image, use
+\fBpamcut\fP.
+
+
+.UN excessivesample
+.SS Excessive Sample Value
+.PP
+This is a stream that contains a purported sample value that is higher than
+the maxval of the image.
+.PP
+The header of a Netpbm image tells the maxval of the image, which is a
+value that gives meaning to all the sample values in the raster.  The
+sample values represent a fraction of the maxval, so a sample value that is
+greater than the maxval makes no sense.
+.PP
+A regular Netpbm program fails if you give it input that contains a value
+larger than the maxval where a sample value belongs.
+.PP
+\fBpamfix\fP has three ways of salvaging such a stream:
+
+
+.IP \(bu
+Clip to the maxval.  Request this with \fB-clip\fP.
+.IP \(bu
+Raise the maxval, thus lowering the fraction represented by every sample
+in the image.  Request this with \fB-changemaxval\fP.
+.IP \(bu
+Truncate the image at the first invalid sample value.  Request this with
+\fB-truncate\fP and neither \fB-clip\fP nor \fB-changemaxval\fP.
+
+.PP
+You cannot specify both \fB-clip\fP and \fB-changemaxval\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamfix\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-truncate\fP
+Create a truncated output image from all the valid input rows that
+could be read.
+
+.TP
+\fB-changemaxval\fP
+Raise the maxval to cope with pixel values that exceed the maxval
+stated in the header of the input file.
+
+.TP
+\fB-clip\fP
+Change all pixel values that exceed the maxval stated in the header
+of the input file.
+
+.TP
+\fB-verbose\fP
+Report details of the transportation to standard error.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamfile" (1)\c
+\&,
+.BR "pamvalidate" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamfix\fP was new in Netpbm 10.66 (March 2014).  But it grew out of
+\fBpamfixtrunc\fP, which was new in Netpbm 10.38 (March 2007) and did only
+the truncated image repair (and for invalid sample values would simply pass
+them through to its output, generating an invalid Netpbm image).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamfix.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamflip.1 b/upstream/mageia-cauldron/man1/pamflip.1
new file mode 100644
index 00000000..80868e79
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamflip.1
@@ -0,0 +1,289 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamflip User Manual" 0 "20 January 2008" "netpbm documentation"
+
+.SH NAME
+
+pamflip - flip or rotate a PAM or PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamflip\fP
+{
+\fB-leftright\fP | \fB-lr\fP |
+\fB-topbottom\fP | \fB-tb\fP |
+\fB-transpose\fP | \fB-xy\fP |
+\fB-rotate90\fP | \fB-r90\fP | \fB-cw\fP |
+\fB-rotate270\fP | \fB-r270\fP | \fB-ccw\fP |
+\fB-rotate180\fP | \fB-r180\fP
+\fB-null\fP |
+\fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
+}
+[\fB-memsize=\fP\fImebibytes\fP]
+[\fB-pagesize=\fP\fIbytes\fP]
+[\fIpamfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and
+its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamflip\fP flips a PAM or PNM image top for bottom or left for right,
+or transposes it horizontal for vertical, or rotates it 1, 2, or 3 quarter
+turns.
+.PP
+To rotate at other angles, use \fBpnmrotate\fP.  It is much slower,
+though.
+.PP
+The input image is \fIpamfile\fP, or Standard Input if \fIpamfile\fP
+is not specified.
+.PP
+To flip/rotate a JFIF (JPEG) image losslessly, use \fBjpegtran\fP.
+\fBjpegtran\fP is part of the Independent Jpeg Group's compression
+library package, not part of Netpbm.  The normal Netpbm way to flip a
+JFIF file would be to convert it to PNM, use \fBpamflip\fP, and convert
+back to JFIF.  But since JPEG compression is lossy, the resulting image
+would have less quality than the original.  \fBjpegtran\fP, on the other
+hand, can do this particular transformation directly on the compressed
+data without loss.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamflip\fP recognizes the following
+command line options:
+
+.UN transformation
+.SS Specifying the Transformation
+.PP
+You must supply exactly one of the following options:
+.PP
+\fBpamflip\fP's predecessor (before Netpbm 10.7 - August 2002)
+\fBpnmflip\fP did not have the \fB-xform\fP option and instead
+allowed you to specify any number of the other options, including
+zero.  It applied all the indicated transformations, in the order
+given, just like with \fBpamflip\fP's \fB-xform\fP option.  (Reason
+for the change: this kind of interpretation of options is inconsistent
+with the rest of Netpbm and most of the Unix world, and thus hard to
+understand and to implement).
+
+
+.TP
+\fB-leftright\fP
+.TP
+\fB-lr\fP
+Flip left for right.
+
+.TP
+\fB-topbottom\fP
+.TP
+\fB-tb\fP
+Flip top for bottom.
+
+.TP
+\fB-transpose\fP
+.TP
+\fB-xy\fP
+Transpose horizontal for vertical.  I.e. make the pixel at (x,y) be
+at (y,x).
+
+.TP
+\fB-rotate90\fP
+.TP
+\fB-r90\fP
+.TP
+\fB-ccw\fP
+Rotate counterclockwise 90 degrees.
+
+.TP
+\fB-rotate180\fP
+.TP
+\fB-r180\fP
+Rotate 180 degrees.
+
+.TP
+\fB-rotate270\fP
+.TP
+\fB-r270\fP
+.TP
+\fB-cw\fP
+Rotate counterclockwise 270 degrees (clockwise 90 degrees)
+
+.TP
+\fB-null\fP 
+No change.  (The purpose of this option is the
+convenience of programs that invoke \fBpamflip\fP after computing the
+kind of transformation desired, including none at all).
+.sp
+This option was new in Netpbm 10.13 (December 2002).
+     
+.TP
+\fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
+Apply all the transforms listed, in order.  The valid values for
+the transforms are as follows and have the same meanings as the
+identically named options above.
+
+.IP \(bu
+leftright
+.IP \(bu
+topbottom
+.IP \(bu
+transpose
+
+.sp
+This option was new in Netpbm 10.13 (December 2002).
+
+
+
+.UN memory
+.SS Memory Management
+.PP
+The following options help \fBpamflip\fP use memory efficiently.
+Some flipping operations on very large images can cause \fBpamflip\fP
+to have a very large working set, which means if you don't have enough
+real memory, the program can page thrash, which means it takes a
+ridiculous amount time to run.  If your entire image fits in real
+memory, you don't have a problem.  If you're just flipping top for
+bottom or left for right, you don't have a problem.  Otherwise, pay
+attention.  If you're interested in the details of the thrashing
+problem and how \fBpamflip\fP approaches it, you're invited to read
+a complete explanation in comments in the source code.
+
+
+.TP
+\fB-memsize=\fP\fImebibytes\fP
+\fImebibytes\fP is the size in mebibytes (aka megabytes) of
+memory available for \fBpamflip\fP.  It is the lesser of the amount
+of real or virtual memory available.
+
+\fBpamflip\fP does nothing special to allocate real memory or control
+it's allocation -- it gets whatever it gets just by referencing
+virtual memory normally.  The real memory figure in question is the
+maximum amount that \fBpamflip\fP can be expected to end up with by
+doing that.  This is just about impossible for you to know, of course,
+but you can estimate.  The total real memory in your system should be
+a major factor in your estimate.
+.sp
+If \fBpamflip\fP cannot fit the entire image in the amount of
+memory you specify, it does the transformation in chunks, using temporary
+files for intermediate results.
+.sp
+In strict horizontal transformations (left for right) or the null
+transformation, \fBpamflip\fP never keeps more than one row in memory, so the
+memory size is irrelevant and \fBpamflip\fP doesn't use temporary files.
+.sp
+In strict vertical transformations (top for bottom), even when you
+allow \fBpamflip\fP enough memory to keep the entire image in virtual memory,
+it accesses it in a single pass, which does not cause any thrashing; the
+chunks in temporary files thus don't help.
+.sp
+The real memory is important when you do a column for row type of
+transformation (e.g. \fB-rotate90\fP).  In that case, even if
+\fBpamflip\fP can fit the entire image in virtual memory at once, if
+it does not also fit in real memory, the program will thrash like
+crazy because of the order in which \fBpamflip\fP accesses the
+pixels, and that means it will take a ridiculously long time to run.
+A proper \fB-memsize\fP drastically reduces the paging.
+.sp
+If you specify \fB-memsize\fP too large, \fBpamflip\fP may
+attempt to get more virtual memory than the system allows it and fail.
+If it can get the virtual memory, but \fB-memsize\fP is larger than
+the amount of real memory the system allows it and the transformation
+is row for column, it will page thrash and run very slowly.  A value
+even slightly too high is the same as infinity.
+.sp
+If you specify \fB-memsize\fP too small, the program will run
+slightly more slowly because of extra overhead in manipulating temporary
+files.  Also, if your environment isn't set up to make temporary files
+possible, \fBpamflip\fP will fail.
+.sp
+Doing the entire transformation "in memory" doesn't speed
+things up as much as you might think, because even with the temporary
+files, the data is just as likely to be in memory.  Virtual memory
+gets paged to disk and disk files get cached in memory.  In fact, the
+pixels fit much more compactly into memory when stored in a temporary
+file than when stored "in memory" because \fBpamflip\fP
+uses a more efficient format.  So you're likely to have \fIless\fP
+disk I/O when you allow \fBpamflip\fP less memory.
+.sp
+If you do not specify \fB-memsize\fP, \fBpamflip\fP assumes
+infinity.
+.sp
+This option did not exist before Netpbm 10.7 (August 2002).
+.sp
+Before Netpbm 10.42 (March 2008), this option applied only to real
+memory.  \fBpamflip\fP would always keep the entire image in virtual
+memory and if it could not get enough virtual memory, it failed.
+\fBpamflip\fP accessed the pixels in an order designed to keep real
+memory use within the specified amount.
+     
+.TP
+\fB-pagesize=\fP\fIbytes\fP
+\fIbytes\fP is the size in bytes of a paging unit -- the amount of
+memory that gets paged in or out as an indivisible unit -- in your system.
+The default is 4KiB.
+.sp
+This option has no effect.
+.sp
+Before Netpbm 10.42 (March 2008), \fBpamflip\fP used it to control its
+use of real memory.
+.sp
+This option did not exist before Netpbm 10.7 (August 2002).
+
+
+
+.UN misc
+.SS Miscellaneous
+
+
+.TP
+\fB-verbose\fP
+This option causes \fBpamflip\fP to issue messages to Standard Error
+about its progress.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmrotate" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+\fBjpegtran\fP manual
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamflip\fP replaced \fBpnmflip\fP in Netpbm 10.13 (December 2002).
+\fBpamflip\fP is backward compatible, but also works on PAM images.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamflip.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamfunc.1 b/upstream/mageia-cauldron/man1/pamfunc.1
new file mode 100644
index 00000000..24f48c2a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamfunc.1
@@ -0,0 +1,359 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamfunc User Manual" 0 "09 September 2020" "netpbm documentation"
+
+.SH NAME
+pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamfunc\fP
+{
+\fB-multiplier=\fP\fIrealnum\fP |
+\fB-divisor=\fP\fIrealnum\fP |
+\fB-adder=\fP\fIinteger\fP |
+\fB-subtractor=\fP\fIinteger\fP |
+\fB-min=\fP\fIwholenum\fP |
+\fB-max=\fP\fIwholenum\fP
+\fB-andmask=\fP\fIhexmask\fP
+\fB-ormask=\fP\fIhexmask\fP
+\fB-xormask=\fP\fIhexmask\fP
+\fB-not\fP
+\fB-shiftleft=\fP\fIcount\fP
+\fB-shiftright=\fP\fIcount\fP
+[\fB-changemaxval\fP]
+}
+[\fIfilespec\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamfunc\fP reads a Netpbm image as input and produces a Netpbm
+image as output, with the same format, and dimensions as the
+input.  \fBpamfunc\fP applies a simple transfer function to each
+sample in the input to generate the corresponding sample in the
+output.  The options determine what function.
+.PP
+The samples involved are PAM samples.  If the input is PBM, PGM, or PPM,
+the output will be that same format, but \fBpamfunc\fP applies the functions
+to the PAM equivalent samples, yielding PAM equivalent samples.  This can
+be nonintuitive in the 
+.UR #pbmoddness
+PBM
+.UE
+\& case.
+  
+.PP
+\fBpamarith\fP is the same thing for binary functions -- it takes
+two images as input and applies a specified simple arithmetic function
+(e.g. addition) on pairs of samples from the two to produce the single
+output image.
+
+
+.UN values
+.SS Values
+.PP
+The functions fall into two categories: arithmetic (such as multiply by 5)
+and bit string (such as and with 01001000).  For the arithmetic functions, the
+function arguments and results are the fraction that a sample is of the
+maxval, i.e. normal interpretation of PAM tuples.  But for the bit string
+functions, the value is the bit string whose value as a binary cipher is
+the sample value, and the maxval indicates the width of the bit string.
+
+.B Arithmetic functions
+.PP
+The arithmetic functions are those selected by the options
+\fB-multiplier\fP, \fB-divisor\fP, \fB-adder\fP, \fB-subtractor\fP,
+\fB-min\fP, and \fB-max\fP.
+.PP
+As an example, consider an image with maxval 100 and a sample value of 10
+and a function of "multiply by 5." The argument to the function is
+10/100 (0.1) and the result is 5 * 0.1 = 0.5.  In the simplest case, the
+maxval of the output is also 100, so the output sample value is 0.5 * 100 =
+50.  As you can see, we could just talk about the sample values themselves
+instead of these fractions and get the same result (10 * 5 = 50), but we
+don't.
+.PP
+Where it makes a practical difference whether we consider the values to be
+the fraction of the maxval or the sample value alone is where \fBpamfunc\fP
+uses a different maxval in the output image than it finds in the input
+image.  See \fB-changemaxval\fP.
+.PP
+So remember in reading the descriptions below that the values are 0.1 and
+0.5 in this example, not 10 and 50.  All arguments and results are in the
+range [0,1].
+
+.B Bit string functions
+.PP
+The bit string functions are those selected by the options
+\fB-andmask\fP, \fB-ormask\fP, \fB-xormask\fP, \fB-not\fP,
+\fB-shiftleft\fP, and \fB-shiftright\fP.
+.PP
+With these functions, the maxval has a very different meaning than in
+normal Netpbm images: it tells how wide (how many bits) the bit string is.
+The maxval must be a full binary count (a power of two minus one, such as
+0xff) and the number of ones in it is the width of the bit string.
+.PP
+As an example, consider an image with maxval 15 and a sample value of 5
+and a function of "and with 0100".  The argument to the function is
+0101 and the result is 0100.
+.PP
+In this example, it doesn't make any practical difference what we consider
+the width of the string to be, as long as it is at least 3.  If the maxval
+were 255, the result would be the same.  But with a bit shift operation,
+it matters.  Consider shifting left by 2 bits.  In the example, where
+the input value is 0101, the result is 0100.  But if the maxval were 255,
+the result would be 00010100.
+.PP
+For a masking function, the mask value you specify must not have
+more significant bits than the width indicated by the maxval.
+.PP
+For a shifting operation, the shift count you specify must not be
+greater than the width indicated by the maxval.
+
+.UN pbmoddness
+.B PBM Oddness
+.PP
+If you're familiar with the PBM format, you may find \fBpamfunc\fP's
+operation on PBM images to be nonintuitive.  Because in PBM black is
+represented as 1 and white as 0 (1.0 and 0.0 normlized), you might be
+expecting adding 1 to white to yield black.
+.PP
+But the PBM format is irrelevant, because \fBpamfunc\fP operates on the
+numbers found in the PAM equivalent (see above).  In a PAM black and white
+image, black is 0 and white is 1 (0.0 and 1.0 normalized).  So white plus 1
+(clipped to the maximum of 1.0) is white.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamfunc\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-multiplier=\fIrealnum\fP\fP
+.sp
+This option makes the transfer function that of multiplying by
+     \fIrealnum\fP.  \fIrealnum\fP must be nonnegative.  If the result
+     is greater than one, it is clipped to one.
+.sp
+Where the input is a PGM or PPM image, this has the effect of
+     dimming or brightening it.  For a different kind of brightening,
+     see
+.BR "\fBpambrighten\fP" (1)\c
+\& and
+.BR "\fBppmflash\fP" (1)\c
+\&
+.sp
+Also, see
+.BR "\fBppmdim\fP" (1)\c
+\&, which does the same
+     thing as \fBpamfunc -multiplier\fP on a PPM image with a multiplier
+     between zero and one, except it uses integer arithmetic, so it may be
+     faster.
+.sp
+And
+.BR "\fBppmfade\fP" (1)\c
+\& can generate a whole
+     sequence of images of brightness declining to black or increasing to
+     white, if that's what you want.
+     
+.TP
+\fB-divisor=\fIrealnum\fP\fP
+.sp
+This option makes the transfer function that of dividing by
+     \fIrealnum\fP.  \fIrealnum\fP must be nonnegative.  If the result
+     is greater than one, it is clipped to one.
+.sp
+This is the same function as you would get with \fB-multiplier\fP,
+     specifying the multiplicative inverse of \fIrealnum\fP.
+     
+.TP
+\fB-adder=\fIinteger\fP\fP
+.sp
+This option makes the transfer function that of adding
+     \fIinteger\fP/\fImaxval\fP.  If the result is greater than one, it is
+     clipped to one.  If it is less than zero, it is clipped to zero.
+.sp
+Note that in mathematics, this entity is called an "addend,"
+     and an "adder" is a snake.  We use "adder" because
+     it makes more sense.
+     
+.TP
+\fB-subtractor=\fIinteger\fP\fP
+.sp
+This option makes the transfer function that of subtracting
+     \fIinteger\fP/\fImaxval\fP.  If the result is greater than one, it is
+     clipped to one.  If it is less than zero, it is clipped to zero.
+.sp
+Note that in mathematics, this entity is called a
+     "subtrahend" rather than a "subtractor." We use
+     "subtractor" because it makes more sense.
+.sp
+This is the same function as you would get with \fB-adder\fP,
+     specifying the negative of \fIinteger\fP.
+     
+.TP
+\fB-min=\fIwholenum\fP\fP
+.sp
+This option makes the transfer function that of taking the maximum of
+     the argument and \fIwholenum\fP/\fImaxval\fP.  I.e the minimum value in
+     the output will be \fIwholenum\fP/\fImaxval\fP.
+
+     If \fIwholenum\fP/\fImaxval\fP is greater than one, though, every value
+     in the output will be one.
+
+.TP
+\fB-max=\fIwholenum\fP\fP
+.sp
+This option makes the transfer function that of taking the minimum of
+     the argument and \fIwholenum\fP/\fImaxval\fP.  I.e the maximum value in
+     the output will be \fIwholenum\fP/\fImaxval\fP.
+
+     If \fIwholenum\fP/\fImaxval\fP is greater than one, the function is
+     idempotent -- the output is identical to the input.
+     
+.TP
+\fB-andmask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise anding
+     with \fIhexmask\fP.
+.sp
+\fIhexmask\fP is in hexadecimal.  Example: \f(CW0f\fP
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-ormask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise
+     inclusive oring with \fIhexmask\fP.
+.sp
+This is analogous to \fB-andmask\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-xormask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise
+     exclusive oring with \fIhexmask\fP.
+.sp
+This is analogous to \fB-andmask\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-not\fP
+.sp
+This option makes the transfer function that of bitwise logical
+     inversion (e.g. sample value 0xAA becomes 0x55).
+.sp
+\fBpnminvert\fP does the same thing for a bilevel visual image
+     which has maxval 1 or is of PBM type.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-shiftleft=\fIcount\fP\fP
+.sp
+This option makes the transfer function that of bitwise shifting
+     left by \fIcount\fP bits.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-shiftright=\fIcount\fP\fP
+.sp
+This option makes the transfer function that of bitwise shifting
+     right by \fIcount\fP bits.
+.sp
+This is analogous to \fB-shiftleft\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-changemaxval\fP
+.sp
+This option tells \fBpamfunc\fP to use a different maxval in the output
+image than the maxval of the input image, if it helps.  By default, the maxval
+of the output is unchanged from the input and \fBpamfunc\fP modifies the
+sample values as necessary to perform the operation.
+.sp
+But there is one case where \fBpamfunc\fP can achieve the same result just
+by changing the maxval and leaving the sample values unchanged: dividing by a
+number 1 or greater, or multiplying by a number 1 or less.  For example, to
+halve all of the values, \fBpamfunc\fP can just double the maxval.
+.sp
+With \fB-changemaxval\fP, \fBpamfunc\fP will do just that.
+.sp
+As the Netpbm formats have a maximum maxval of 65535, for large divisors,
+\fBpamfunc\fP may not be able to use this method.
+.sp
+An advantage of dividing by changing the maxval is that you don't lose
+precision.  The higher maxval means higher precision.  For example, consider
+an image with a maxval of 100 and sample value of 10.  You divide by 21 and
+then multiply by 21 again.  If \fBpamfunc\fP does this by changing the sample
+values while retaining maxval 100, the division will result in a sample value
+of 0 and the multiplication will also result in zero.  But if \fBpamfunc\fP
+instead keeps the sample value 10 and changes the maxval, the division will
+result in a maxval of 2100 and the multiplication will change it back to 100,
+and the round trip is idempotent.
+.sp
+This option was new in Netpbm 10.65 (December 2013).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdim" (1)\c
+\&,
+.BR "pambrighten" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pamarith" (1)\c
+\&,
+.BR "pamsummcol" (1)\c
+\&,
+.BR "pamsumm" (1)\c
+\&,
+.BR "ppmfade" (1)\c
+\&,
+.BR "pnminvert" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.3 (June 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamfunc.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamgauss.1 b/upstream/mageia-cauldron/man1/pamgauss.1
new file mode 100644
index 00000000..fc8cd8b1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamgauss.1
@@ -0,0 +1,182 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamgauss User Manual" 0 "18 May 2017" "netpbm documentation"
+
+.SH NAME
+\fBpamgauss\fP - create a two-dimensional Gaussian function as a PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamgauss\fP
+\fIwidth\fP
+\fIheight\fP
+\fB-sigma=\fP\fInumber\fP
+[\fB-maxval=\fP\fInumber\fP]
+[\fB-tupletype=\fP\fIstring\fP]
+[\fB-maximize\fP]
+[\fB-oversample=\fP\fInumber\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+     pamgauss 7 7 -sigma=.5 -maximize -tupletype=GRAYSCALE | pamtopnm >gauss.pgm
+     pnmconvol -nooffset -normalize gauss.pgm myimage.ppm >blurred.ppm
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamgauss\fP generates a one-plane PAM image whose samples are a
+Gaussian function of their distance from the center of the image.  I.e.
+the sample value is highest in the center and goes down, in a bell curve
+shape, as you move away from the center.
+.PP
+You can use this image as a convolution kernel with
+\fBpnmconvol\fP to blur an image.  (This technique is known as
+Gaussian blurring).
+
+\fIwidth\fP and \fIheight\fP are the dimensions of the image that
+\fBpamgauss\fP generates.  Mathematically speaking, they are the domain of
+the two-dimensional Gaussian function.  If you want to be sure you get a whole
+Gaussian function, make sure that you choose a standard deviation and image
+dimensions so that if you made it any larger, the sample values at the edges
+would be zero.
+.PP
+The output image is PAM.  To make it usable with \fBpnmconvol\fP,
+specify \fB-tupletype=GRAYSCALE\fP so \fBpnmconvol\fP can use it as
+if it were PGM.  You must use the \fB-nooffset\fP option on
+\fBpnmconvol\fP because zero means zero in the PAM that
+\fBpamgauss\fP generates.
+.PP
+Without \fB-maximize\fP, the sum of all the samples is equal to the
+image's maxval (within rounding error).  This is true even if you clip the
+Gaussian function by making the image too small.  This is what is normally
+required of a convolution kernel.
+.PP
+\fBpamgauss\fP oversamples and averages to represent the continuous
+Gaussian function in discrete samples in the PAM output.  Consider an image 11
+samples wide and an oversampling factor of 10.  The samples can be thought of
+as contiguous squares one unit wide.  The center of the image is thus the
+center of the 6th sample from the left.  The 3rd sample from the left covers a
+range of distances from 3 to 4 units from the center of the image.  Because
+the oversampling factor is 10, \fBpamgauss\fP computes the value of the
+Gaussian function at 10 points evenly spaced between 3 and 4 units from the
+center of the image and assigns the 3rd sample from the left the mean of those
+10 values.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamgauss\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-sigma=\fP\fInumber\fP
+This is the standard deviation of the Gaussian function.  The higher the
+number, the more spread out the function is.  Normally, you want to make this
+number low enough that the function reaches zero value before the edge of your
+image.
+.sp
+\fInumber\fP is in units of samples.
+.sp
+This option is required.  There is no default.
+
+.TP
+\fB-maximize\fP
+Causes \fBpamgauss\fP to use the whole dynamic range available in
+the output PAM image by choosing an amplitude for the Gaussian function that
+causes the maximum value in the image to be the maxval of the image.
+.sp
+If you select this, you probably want to normalize the output (scale the
+samples down so the volume under the surface of the two-dimensional Gaussian
+function is the maxval) before you use it, for example with
+\fBpnmconvol\fP's \fB-normalize\fP option.  The reason this is different
+from just not using \fB-maximize\fP is that this subsequent normalization can
+be done with much more precision than can be represented in a PAM image.
+.sp
+Without this option, \fBpamgauss\fP uses an amplitude that makes the volume
+under the surface of the two-dimensional Gaussian function the maxval of the
+image.  This means all the samples in the image are normally considerably less
+than the maxval.
+.sp
+This option was new in Netpbm 10.79 (June 2017).
+
+.TP
+\fB-maxval=\fP\fInumber\fP
+This is the maxval for the output image.  65535 is almost always the best
+value to use.  But there may be some programs (not part of Netpbm) that can't
+handle a maxval greater than 255.
+.sp
+The default is 255.
+
+.TP
+\fB-tupletype=\fP\fIstring\fP
+This is the value of the "tuple_type" attribute of the created PAM image.
+It can be any string up to 255 characters.
+.sp
+If you don't specify this, \fBpamgauss\fP generates a PAM with unspecified
+tuple type.
+
+.TP
+\fB-oversample=\fP\fInumber\fP
+This sets the oversampling factor.  \fBpamgauss\fP samples the Gaussian
+function this many times, both horizontally and vertically, to get the value
+of each sample in the output.
+.sp
+An oversampling factor of 1 means no oversampling, which means each 
+sample is based only on the value of the Gaussian function at the center of
+the sample.
+.sp
+The default is 5 divided by the standard deviation, rounded up to a whole
+number.
+.sp
+This option was new in Netpbm 10.79 (June 2017).  Before that, it is
+essentially 1 - there is no oversampling.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pgmkernel" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamgauss\fP was new in Netpbm 10.23 (July 2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamgauss.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamgetcolor.1 b/upstream/mageia-cauldron/man1/pamgetcolor.1
new file mode 100644
index 00000000..7462d862
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamgetcolor.1
@@ -0,0 +1,212 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamgetcolor User Manual" 0 "18 May 2018" "netpbm documentation"
+
+.SH NAME
+pamgetcolor - display the average colors from specified regions in an image.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamgetcolor\fP
+[\fB-format\fP \fIformat\fP]
+[\fB-radius\fP \fIradius\fP]
+[\fB-linear\fP]
+[\fB-infile\fP \fIpamfile\fP]
+\fIregion1\fP [\fIregion2\fP ...]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamgetcolor\fP prints the average colors of a set of circular
+regions in the input image.
+.PP
+You specify a region as a positional argument of the form
+\fIcolumn\fP,\fIrow\fP[:\fIlabel\fP], where \fIcolumn\fP and \fIrow\fP
+are the coordinates of the center of the circle (first row of pixels is row 0;
+leftmost column of pixels is column 0), and \fIlabel\fP an optional label
+that \fBpamgetcolor\fP shall display to identify that region in its output.
+All regions have he same radius, specified by the \fB-radius\fP option.  The
+region centers must lie within the image, but part of a region may fall
+outside the image; \fBpamgetcolor\fP considers only the part that is within
+the image in calculations.
+
+
+.UN examples
+.SH EXAMPLES
+
+To read the color of the pixel at location (10,14) in the default
+format:
+
+.nf
+\f(CW
+    pamgetcolor 10,14 -infile test.ppm
+\fP
+
+.fi
+.PP
+To read the colors of three pixels in the default format, assigning a
+label to each pixel:
+  
+.nf
+\f(CW
+    pamgetcolor 10,10:topleft 100,100:middle 200,200:bottomright -infile test.ppm
+\fP
+
+.fi
+.PP
+To read with 16-bit precision the average color in the circle with a radius
+of four pixels and the center at (100,100):
+
+.nf
+\f(CW
+    pamgetcolor -format int:65535 -radius 4 100,100 -infile test.ppm
+\fP
+
+.fi
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamgetcolor\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-format\fP
+This specifies the format in which to output the colors.  The output is
+always a 
+.UR libppm.html#colorname
+Netpbm color specification
+.UE
+\&; this
+format tells which of the various specifications for the same color the
+program uses.
+.sp
+This argument is of the form \fIformatId\fP[:\fIparam\fP], where
+\fIformatId\fP specifies the format and \fIparam\fP is a positive
+integer parameter that, depending on \fIformatId\fP, indicates
+either precision or normalization. The following values are possible for
+\fIformatId\fP:
+
+.TP
+int
+Samples are decimal integers normalized to the maxval specified by
+\fIparam\fP.  Example: \fBrgb-255:255/128/64\fP
+This format is the default, with a maxval of 255.
+.TP
+norm
+Samples are floating point numbers normalized to unity.  E.g.
+\fBrgbi:1.0/0.5/.25\fP
+\fIparam\fP specifies precision as the number of digits in the
+fractional part.
+.TP
+x11
+Samples are hexadecimal numbers with \fIparam\fP digits,
+e.g. \fBrgb:01/ff/8000\fP
+
+
+.TP
+\fB-radius\fP
+sets the radius of the regions.
+A value of zero causes \fBpamgetcolor\fP to measure a single pixel and
+is the default.
+
+.TP
+\fB-infile\fP
+This specifies the Netpbm file to analyze.
+.sp
+If you don't specify this option, \fBpamgetcolor\fP reads the image from
+Standard Input.
+
+.TP
+\fB-linear\fP
+This tells \fBpamgetcolor\fP to work with the intensity-linear variation
+of Netpbm images where the samples are proportional to light intensity rather
+than to brightness, as in true (gamma-adjusted) Netpbm formats.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pnmcolormap" (1)\c
+\&,
+
+
+.UN author
+.SH AUTHOR
+.PP
+This program was first submitted by Anton Shepelev
+(\fIanton.txt@gmail.com\fP).
+
+.UN history
+.SH HISTORY
+.PP
+This program was new in Netpbm 10.83 (June 2018).
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #examples
+EXAMPLES
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #author
+AUTHOR
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamgetcolor.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamgradient.1 b/upstream/mageia-cauldron/man1/pamgradient.1
new file mode 100644
index 00000000..a7e5a5b6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamgradient.1
@@ -0,0 +1,115 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamgradient User Manual" 0 "21 October 2005" "netpbm documentation"
+
+.SH NAME
+pamgradient - create a four-corner gradient PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamgradient\fP
+[\fB-maxval=\fP\fImaxval\fP]
+\fIcolor-tl\fP \fIcolor-tr\fP \fIcolor-bl\fP \fIcolor-br\fP
+\fIwidth\fP \fIheight\fP
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamgradient\fP creates an image of the specified
+dimensions \fIwidth\fP by \fIheight\fP which contains a smooth,
+two-dimensional gradient between the specified colors of the four
+corners (from top left to bottom right).
+.PP
+Specify the colors as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.PP
+If all four colors are gray values, \fBpamgradient\fP creates a
+grayscale image (PAM tuple type GRAYSCALE).  Otherwise, it creates
+a color image (PAM tuple type RGB).
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamgradient\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+
+  
+maxval of the generated image.  (See
+.BR "PAM" (1)\c
+\& and
+.BR "PNM" (1)\c
+\& specifications).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpamgradient\fP" (1)\c
+\&,
+.BR "\fBppmmake\fP" (1)\c
+\&,
+.BR "\fBppmrainbow\fP" (1)\c
+\&,
+.BR "\fBpgmramp\fP" (1)\c
+\&,
+.BR "\fBppmpat\fP" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN note
+.SH NOTE
+.PP
+Only the top left corner of the generated image has exactly
+the specified color.  The color of the top right corner is a bit
+shifted to the left, the bottom left corner a bit up, and the
+bottom right corner left and up. This ensures nice transitions
+when combining adjacent (very narrow) gradients, and doesn't play
+a role when the gradient butts against a solid surface.
+.PP
+This effect is created by the integer arithmetic used for the
+interpolation of the color values, and since it doesn't make a
+difference for all practical purposes I might as well sell it as a
+feature.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamgradient\fP was new in Netpbm 10.31 (December 2005).
+
+.UN author
+.SH AUTHOR
+.PP
+pamgradient was written by Daniel Haude in October 2005.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamgradient.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamhomography.1 b/upstream/mageia-cauldron/man1/pamhomography.1
new file mode 100644
index 00000000..41ad0495
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamhomography.1
@@ -0,0 +1,428 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "pamhomography" 1 "04 December 2022" "netpbm documentation"
+
+
+
+
+<script type="text/javascript" src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
+<script type="text/javascript" id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
+.SH NAME
+.PP
+pamhomography - stretch/shrink a quadrilateral region of an image to
+  another quadrilateral shape
+
+
+.UN SYNOPSIS
+.SH SYNOPSIS
+.PP
+\fBpamhomography\fP
+  [\fB-from\fP=\fIcoords\fP]
+  [\fB-to\fP=\fIcoords\fP]
+  [\fB-mapfile\fP=\fImap_file\fP]
+  [\fB-view\fP=\fIcoords\fP]
+  [\fB-fill\fP=\fIcolor\fP]
+  [\fB-verbose\fP
+  [\fIpam_file\fP]
+.PP
+You can abbreviate any option to its shortest unique prefix. You can use
+two hyphens instead of one to delimit an option. You can separate an option
+from its value with whitespace instead of \f(CW=\fP.
+
+
+.UN DESCRIPTION
+.SH DESCRIPTION
+.PP
+This program is part
+of 
+.UR http://netpbm.sourceforge.net/
+Netpbm
+.UE
+\&.
+.PP
+\fBpamhomography\fP stretches and shrinks an arbitrary quadrilateral
+portion of an input image you specify (not necessarily rectangular), into a
+new quadrilateral shape you specify, producing a new image.
+.PP
+You can do any
+.UR https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation
+affine image transformation
+.UE
+\&: translation, reflection, scaling,
+rotation, and shearing/skewing. However, \fBpamhomography\fP additionally can
+do \fIbilinear\fP transforms, which means it can warp any quadrilateral to any
+other quadrilateral, even when this mapping cannot be described using a single
+set of linear equations. This can be useful, for example, for creating
+perspective views of rectangular images or for reverse-mapping a perspective
+view back to a rectangular projection.
+
+
+.UN OPTIONS
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm (most
+notably \fB-quiet\fP, see 
+.UR http://index.html#commonoptions
+Common Options
+.UE
+\&), \fBpamhomography\fP recognizes the following command line
+options:
+
+
+
+.TP
+\fB-from\fP=\fIcoords\fP
+.sp
+This defines the source quadrilateral. \fIcoords\fP is a list of four
+  integer-valued (\fIx\fP, \fIy\fP) coordinates. If you do not specify the
+  source with either \fB-from\fP or \fB-mapfile\fP, the source quadrilateral
+  is the entire input image.
+
+
+.TP
+\fB-to\fP=\fIcoords\fP
+.sp
+This defines the target quadrilateral. \fIcoords\fP is a list of four
+integer-valued (\fIx\fP, \fIy\fP) coordinates. If you do not specify the
+target with either \fB-to\fP or \fB-mapfile\fP, the target quadrilateral is
+the same as the entire input image.
+
+.TP
+\fB-mapfile\fP=\fImap_file\fP
+.sp
+This names a text file that describes the mapping from the source to the
+target quadrilateral. The file \fImap_file\fP must contain either eight
+integer-valued (\fIx\fP, \fIy\fP) coordinates, being the four source
+coordinates followed by the corresponding four target coordinates, or only
+four (\fIx\fP, \fIy\fP) coordinates, being only the four target
+coordinates. In the latter case, the source quadrilateral is taken to be the
+four corners of the input image in clockwise order, starting from the upper
+left.
+.sp
+Anything you specify with \fB-to\fP or \fB-from\fP overrides what is in
+  this file.
+
+
+.TP
+\fB-view\fP=\fIcoords\fP
+.sp
+This defines the target view. \fIcoords\fP is a list of two integer-valued
+(\fIx\fP, \fIy\fP) coordinates: the upper left and lower right boundaries,
+respectively, of the pixels that will be visible in the output image. If
+\fB-view\fP is not specified, the target view will fit precisely the target
+quadrilateral.
+
+
+.TP
+\fB-fill\fP=\fIcolor\fP
+.sp
+This is the color with which the program fills all pixels that lie outside
+of the target quadrilateral. Specify the color as described for the
+.UR http://libnetpbm_image.html#colorname
+ argument of the pnm_parsecolor() library routine
+.UE
+\&.
+.sp
+The default is black, and for images with a transparency plane, transparent.
+
+
+
+.TP
+\fB-verbose\fP
+This makes the program issue some informational messages about what it is
+doing.
+
+
+.PP
+Cooordinates should normally be specified in clockwise order. The syntax is
+fairly flexible: all characters other than the plus sign, minus sign, and
+digits are treated as separators. Although coordinates need to be integers,
+they may lie outside the image's boundary.
+
+.UN PARAMETERS
+.SH PARAMETERS
+.PP
+\fBpamhomography\fP's only parameter, \fIpam_file\fP, is the name of the
+  file containing the input image. If you don't specify \fIpam_file\fP, the
+  image comes from Standard Input.
+
+  
+.UN NOTES
+.SH NOTES
+.PP
+The output image uses the same Netpbm format as the input image.
+.PP
+Simple transformations are best handled by other Netpbm programs, such as
+those listed in the 
+.UR #SEE-ALSO
+\&'SEE ALSO'
+.UE
+\& section
+below. Use \fBpamhomography\fP for more sophisticated transformations such as
+perspective adjustments, rotations around an arbitrary point in the image,
+extraction of non-rectangular quadrilaterals, shearings by coordinates rather
+than by angle, and, in general, all transformations that are most easily
+expressed as mapping four points in one image to four points in another
+image.
+
+.UN EXAMPLES
+.SH EXAMPLES
+.PP
+The following examples use the
+.UR park_row.ppm
+park_row.ppm 
+.UE
+\& test image, which is a
+.UR https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG
+ photograph of New York City's Park Row Building
+.UE
+\&, scaled to
+441&times;640, converted to a PPM file, and redistributed under the terms of
+the 
+.UR https://en.wikipedia.org/wiki/GNU_Free_Documentation_License
+ GFDL
+.UE
+\&.
+.PP
+The first example showcases the real power of bilinear transformations.
+Assuming \fIpark_row_rect.map\fP has the following contents:
+
+.nf\f(CW    (147, 51) (316, 105) (402, 595) (92, 560)
+      (0,  0) (440,   0) (440, 639)  (0, 639)\fP
+.fi
+.PP
+then
+
+.nf\f(CW    pamhomography -mapfile park_row_rect.map park_row.ppm > park_row_rect.ppm\fP
+.fi
+.PP
+projects the building's facade from a perspective view to a rectilinear
+front-on view. Remember that \fBpamhomography\fP ignores the parentheses and
+commas used in \fIpark_row_rect.map\fP; they merely make the file more
+human-readable. We equivalently could have written
+
+.nf\f(CW    147 51 316 105 402 595 92 560 0 0 440 0 440 639 0 639\fP
+.fi
+.PP
+or any of myriad other variations.
+.PP
+\fBpamhomography\fP can warp the image to a trapezoid to make it look like
+it's leaning backwards in 3-D:
+
+.nf\f(CW    pamhomography -to '50,0 390,0 440,200 0,200' park_row.ppm > park_row_trap.ppm\fP
+.fi
+.PP
+As a very simple example,
+
+.nf\f(CW    pamhomography -to '440,0 0,0 0,639 440,639' park_row.ppm > park_row_flip.ppm\fP
+.fi
+.PP
+flips the image left-to-right. Note that in this case the target
+quadrilateral's coordinates are listed in counterclockwise order because
+that represents the correspondence between points (0, 0) &harr; (440, 0) and
+(0, 639) &harr; (639, 0).
+.PP
+Scaling is also straightforward. The following command scales down the
+image from 441&times;640 to 341&times;540:
+
+.nf\f(CW    pamhomography -to '0,0 340,0 340,539 0,539' park_row.ppm > park_row_small.ppm\fP
+.fi
+.PP
+Let's add 100 pixels of tan border to the above. We use \fB-view\fP and
+\fB-fill\fP to accomplish that task:
+
+.nf\f(CW    pamhomography -to '0,0 340,0 340,539 0,539' -view '-100,-100 440,639' -fill tan park_row.ppm > park_row_small_border.ppm\fP
+.fi
+.PP
+We can add a border without having to scale the image:
+
+.nf\f(CW    pamhomography -view '-100,-100 540,739' -fill tan park_row.ppm > park_row_border.ppm\fP
+.fi
+.PP
+The \fB-view\fP option can also be used to extract a rectangle out of an
+image, discarding the rest of the image:
+
+.nf\f(CW    pamhomography -view '130,10 205,80' park_row.ppm > park_row_cut.ppm\fP
+.fi
+.PP
+Specifying the same set of coordinates to \fB-from\fP and \fB-to\fP has
+the same effect but also allows you to extract non-rectangular quadrilaterals
+from an image:
+
+.nf\f(CW    pamhomography -from '185,300 310,325 320,425 180,405' -to '185,300 310,325 320,425 180,405' park_row.ppm > park_row_cut_2.ppm\fP
+.fi
+.PP
+Rotation is doable but takes some effort. The challenge is that you need to
+compute the rotated coordinates yourself. The matrix expression to rotate
+points \e((x_1, y_1)\e) \e((x_2, y_2)\e), \e((x_3, y_3)\e), and \e((x_4, y_4)\e)
+clockwise by \e(\etheta\e) degrees around point \e((c_x, c_y)\e) is
+.PP
+\e[ \ebegin{bmatrix} 1 & 0 & c_x \e\e 0 & 1 & c_y \e\e 0 & 0
+& 1 \eend{bmatrix} \ebegin{bmatrix} \ecos \etheta & -\esin \etheta & 0
+\e\e \esin \etheta & \ecos \etheta & 0 \e\e 0 & 0 & 1 \eend{bmatrix}
+\ebegin{bmatrix} 1 & 0 & -c_x \e\e 0 & 1 & -c_y \e\e 0 & 0
+& 1 \eend{bmatrix} \ebegin{bmatrix} x_1 & x_2 & x_3 & x_4 \e\e y_1
+& y_2 & y_3 & y_4 \e\e 1 & 1 & 1 & 1 \eend{bmatrix}
+\equad. \e]
+.PP
+For example, to rotate \fIpark_row.ppm\fP 30&deg; clockwise around (220,
+320) you would compute
+.PP
+\e[ \ebegin{bmatrix} 1 & 0 & 220 \e\e 0 & 1 & 320 \e\e 0 & 0
+& 1 \eend{bmatrix} \ebegin{bmatrix} \ecos 30^{\ecirc} & -\esin 30^{\ecirc}
+& 0 \e\e \esin 30^{\ecirc} & \ecos 30^{\ecirc} & 0 \e\e 0 & 0 & 1
+\eend{bmatrix} \ebegin{bmatrix} 1 & 0 & -220 \e\e 0 & 1 & -320 \e\e
+0 & 0 & 1 \eend{bmatrix} \ebegin{bmatrix} 0 & 440 & 440 & 0
+\e\e 0 & 0 & 639 & 639 \e\e 1 & 1 & 1 & 1 \eend{bmatrix} =
+\ebegin{bmatrix} 189.4744 & 570.5256 & 251.0256 & -130.0256 \e\e
+-67.1281 & 152.8719 & 706.2621 & 486.2621 \e\e 1.0000 & 1.0000
+& 1.0000 & 1.0000 \eend{bmatrix} \equad, \e]
+.PP
+round these coordinates to integers, transpose the matrix, and produce the
+following map file, \fIpark_row_rot30.map\fP:
+
+.nf\f(CW     189  -67
+     571  153
+     251  706
+    -130  486\fP
+.fi
+.PP
+(These are the 'to' coordinates; we use the default, full-image
+\&'from' coordinates.) The mapping then works as in all of the
+preceding examples:
+
+.nf\f(CW    pamhomography -mapfile park_row_rot30.map park_row.ppm > park_row_rot30.ppm\fP
+.fi
+
+
+.UN SEE-ALSO
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pamcut" (1)\c
+\&
+.IP \(bu
+
+.BR "pamenlarge" (1)\c
+\&
+.IP \(bu
+
+.BR "pamflip" (1)\c
+\&
+.IP \(bu
+
+.BR "pamperspective" (1)\c
+\&
+.IP \(bu
+
+.BR "pamscale" (1)\c
+\&
+.IP \(bu
+
+.BR "pamstretch" (1)\c
+\&
+.IP \(bu
+
+.BR "pam" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmmargin" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmpad" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmrotate" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmshear" (1)\c
+\&
+
+
+
+.UN HISTORY
+.SH HISTORY
+.PP
+\fBpamhomography\fP was new in Netpbm 10.94 (March 2021).
+  
+
+.UN AUTHOR
+.SH AUTHOR
+.PP
+Copyright \(co 2020 Scott
+Pakin, \fIscott+pbm@pakin.org\fP
+
+
+.UN index
+.SH Table of Contents
+
+
+.IP \(bu
+
+.UR #SYNOPSIS
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #DESCRIPTION
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #OPTIONS
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #PARAMETERS
+PARAMETERS
+.UE
+\&
+.IP \(bu
+
+.UR #NOTES
+NOTES
+.UE
+\&
+.IP \(bu
+
+.UR #EXAMPLES
+EXAMPLES
+.UE
+\&
+.IP \(bu
+
+.UR #SEE-ALSO
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #HISTORY
+HISTORY
+.UE
+\&
+.IP \(bu
+
+.UR #AUTHOR
+AUTHOR
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamhomography.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamhue.1 b/upstream/mageia-cauldron/man1/pamhue.1
new file mode 100644
index 00000000..ff2146c7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamhue.1
@@ -0,0 +1,125 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamhue User Manual" 0 "07 January 2018" "netpbm documentation"
+
+.SH NAME
+pamhue - change a Netpbm image's hues
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamhue\fP
+[\fB-huechange=\fP[\fIdegrees\fP]]
+\fIfilename\fP
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamhue\fP shifts the hue of every pixel in an image by the same amount.
+.PP
+If the image is in a black and white or grayscale format, the image is
+fully desaturated, so the hue is meaningless and \fBpamhue\fP leaves the
+image unchanged.
+.PP
+Hue-Saturation-Value, or HSV, is one way to represent a color, like the
+more well-known RGB.  Hue is an indication of the secondary color with the
+same brightness that most closely approximates the color.  A secondary color
+is made of a combination of at most two of the primary colors.
+.PP
+In the HSV model, hue is an angular position on the color wheel.
+.PP
+With \fBpamhue\fP, you indicate an angle by which to change all the hues
+in the image; for example you can say move it 60 degrees clockwise.  That
+would change all red pixels to yellow and all yellow pixels to green, etc.
+  
+.PP
+To modify the saturation and value components of the colors, use
+\fBpambrighten\fP.
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+To shift the color of each pixel 120 degrees clockwise:
+.nf
+pamhue -huechange=120
+
+.fi
+.PP
+To shift the color of each pixel 120 degrees counterclockwise:
+.nf
+pamhue -huechange=-120
+
+.fi
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamhue\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-huechange=\fP\fIdegrees\fP
+This option specifies the amount to shift each color.  It is in degrees,
+with positive meaning clockwise and negative meaning counterclockwise.  It may
+be fractional and may be more than a full revolution.
+.sp
+This option is mandatory.
+
+  
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamhue\fP was new in Netpbm 10.86 (March 2019).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pambrighten" (1)\c
+\&, 
+.BR "ppmflash" (1)\c
+\&, 
+.BR "ppmhist" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2018 by Willem van Schaik.
+Copyright (C) 1990 by Brian Moffet.
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.  This software is provided "as is" without express or
+implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamhue.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamlevels.1 b/upstream/mageia-cauldron/man1/pamlevels.1
new file mode 100644
index 00000000..15de1332
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamlevels.1
@@ -0,0 +1,185 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamlevels User Manual" 0 "13 June 2018" "netpbm documentation"
+
+.SH NAME
+pamlevels - effect a 'levels' transformation
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamlevels\fP
+\fB-from1\fP \fIfrom1\fP
+\fB-to1\fP \fIto1\fP
+\fB-from2\fP \fIfrom2\fP
+\fB-to2\fP \fIto2\fP
+[\fB-from3\fP \fIfrom3\fP
+\fB-to3\fP \fIto3\fP]
+[\fB-linear\fP]
+[\fB-fitbrightness\fP]
+[\fIpamfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamlevels\fP reads a Netpbm image from \fIpamfile\fP or standard
+input, applies a 'levels' transformation, and sends the result to
+standard output. It finds a unique transformation that maps color
+\fIfrom1\fP to \fIto1\fP, color \fIfrom2\fP to \fIto2\fP,
+and-if \fB-from3\fP and \fB-to3\fP are supplied-color
+\fIfrom3\fP to \fIto3\fP. Transformations based on two mappings are linear
+in light intensity and those based on three mappings quadratic.  The
+color-mapping options may be shortened to \fB-f1\fP...\fB-f3\fP and
+\fB-t1\fP...\fB-t3\fP.  
+.PP
+Color values have the following format:
+\fIcolor\fP[:\fIscale\fP], where \fIcolor\fP is a
+.UR libppm.html#colorname
+ Netpbm color specification
+.UE
+\& and
+\fIscale\fP an optional coefficient that is applied to the intensity
+(i.e. \fInot\fP gamma-adjusted) of each RGB component of \fIcolor\fP.
+.PP
+When the transformation is linear (i.e. uses two mappings) and preserves
+zero (i.e. maps black to black), it corresponds to multiplication of light
+intensity by a constant and preserves
+.BR "color integrity" (1)\c
+\&.
+
+
+.UN examples
+.SH EXAMPLES
+In the examples below, \f(CW\e\fP denotes a line continuation:
+.PP
+To brighten an image by setting a darker white point-
+.nf
+    pamlevels -f1 black -t1 black \e
+      -f2 white:0.9 -t2 white in.ppm > out.ppm
+
+.fi
+.PP
+To adjust the white point-
+.nf
+    pamlevels -f1 black -t1 black \e
+      -f2 rgbi:0.9/0.83/0.80 -t2 white in.ppm > out.ppm
+
+.fi
+.PP
+To set a lighter black point-
+.nf
+    pamlevels -f1 white:0.06 -t1 black \e
+      -f2 white -t2 white in.ppm > out.ppm
+
+.fi
+.PP
+To increase brightness by compression-
+.nf
+    pamlevels \e
+      -f1 black -t1 black -f2 white -t2 white \e
+      -f3 white:0.5 -t3 white:0.6 in.ppm > out.ppm
+
+.fi
+The latter tranformation is similar to gamma-correction.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamlevels\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-from1\fP
+.TP
+\fB-to1\fP
+.TP
+\fB-from2\fP
+.TP
+\fB-to2\fP
+.TP
+\fB-from3\fP
+.TP
+\fB-to3\fP
+These options define the mappings of input colors to output colors that anchor
+the transformation function.  See 
+.UR #description
+DESCRIPTION
+.UE
+\&.
+.sp
+You must specify at least two of these pairs.
+
+.TP
+\fB-linear\fP
+This option tells \fBpamlevels\fP to work with the intensity-linear
+variation on PPM where the samples are proportional to light intensity, rather
+than brightness (gamma-adjusted) as in true PPM.  The input must be of this
+form and the \fBpamlevels\fP makes the output of this form.
+.sp
+Note that the numbers in a color specification like
+\fBrgbi:0.9/0.83/0.80\fP are brightness levels (gamma-adjusted) regardless of
+the input and output format.
+.sp
+You cannot use this with \fB-fitbrightness\fP because that function is
+not implemented.
+  
+.TP
+\fB-fitbrightness\fP
+This option selects a transformation which is not very useful - it is
+linear or quadratic in brightness rather than light intensity of the pixels.
+There is no physical basis for doing it this way and the result is normally
+undesirable.
+.sp
+Note that many tools other than Netpbm do the transformation this way.  One
+use for this option is simply to demonstrate the poor result of this method.
+.sp
+One advantage of this transformation is that it is faster, because the
+input and output image formats use brightness values.  The result is
+approximately correct.
+.sp
+You cannot use this with \fB-linear\fP because that function is not
+implemented.
+  
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmnorm" (1)\c
+\&,
+.BR "pamrecolor" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+This program was first submitted by Anton Shepelev
+(\fIanton.txt@gmail.com\fP).
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamlevels\fP was new in Netpbm 10.83 (June 2018).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamlevels.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamlookup.1 b/upstream/mageia-cauldron/man1/pamlookup.1
new file mode 100644
index 00000000..45f6d329
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamlookup.1
@@ -0,0 +1,404 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamlookup User Manual" 0 "25 July 2015" "netpbm documentation"
+
+.SH NAME
+pamlookup - map an image to a new image by using it as indices into a table
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamlookup\fP
+\fB-lookupfile=\fP\fIlookupfile\fP
+[\fB-byplane\fP]
+\fB-missingcolor=\fP\fIcolor\fP
+[\fB-fit\fP]
+\fIindexfile\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamlookup\fP takes a two dimensional array of indices and a lookup
+table as input.  For each position in the index array, it looks up the index
+in the lookup table and places the result of the lookup in the output image.
+
+There are two ways of indexing the lookup table: \fIwhole tuple\fP and
+\fIby plane\fP.  The \fB-byplane\fP option controls which \fBpamlookup\fP
+does.
+.PP
+In the simplest form of whole tuple indexing, each index in the index array
+is a single whole number and the lookup table associates a whole tuple with
+each possible whole number index.  So for example, the index array might have
+at Row 2, Column 9 the value 23.  The lookup table might associate the tuple
+(1,2,3) with the value 23.  In that case, the output image contains the tuple
+(1,2,3) at Row 2, Column 9.
+.PP
+In a more complex form of whole tuple indexing, each index in the index
+array is an ordered pair of whole numbers and the lookup table associates a
+whole tuple with each possible ordered pair index.  Modifying the example
+above, the index value could be (23, 5) instead of 23.
+.PP
+With whole tuple indexing, the output thus has the same width and height as
+the index image, and tuple depth and type and maxval determined by the lookup
+table.
+.PP
+With whole tuple indexing, if the index image has depth 1, its sample
+values are single whole number indices.  If the index image has depth greater
+than 1, its tuples are ordered pair indices composed of the first and second
+sample in the tuple.
+.PP
+In by plane indexing, the index image contains whole number indices.
+The first sample of each tuple in the index image is the index.  The lookup
+table maps each whole number index to another whole number.
+\fBpamlookup\fP looks up each sample from the index image in the lookup table
+and uses the resulting whole number as the sample value for the same
+row, column, and plane in the output.
+.PP
+With by plane indexing, the output thus has the same dimensions as the
+index image an the same maxval as the lookup image.
+
+
+.UN lookupimage
+.SS The Lookup Table Image
+.PP
+The lookup table is a PAM or PNM image.  If the index image
+contains whole number indices, the lookup image is a single row and
+the index is a column number.  The lookup result is the value of the
+tuple or pixel at the indicated column in the one row in the lookup
+table.  If the index image contains ordered pair indices, the first
+element of the ordered pair is a row number and the second element of
+the ordered pair is a column number.  The lookup result is the value
+of the tuple or pixel at the indicated row and column in the lookup
+table.
+.PP
+The width of the lookup image should normally be the maxval of the index
+image plus one, so that each possible index sample value corresponds to one
+entry in the lookup table.  There are two ways \fBpamlookup\fP deals
+with a lookup image that does not have such a width: 
+
+
+.IP \(bu
+Scale the lookup image to the required width.  \fBpamlookup\fP always
+does this with by plane indexing, and with whole tuple indexing, does it when
+you specify \fB-fit\fP.
+
+.IP \(bu
+Use a default value for indices that exceed the width of the lookup image
+and ignore lookup image columns beyond the maxval of the index
+image.  \fBpamlookup\fP does this with whole tuple indexing when you don't
+specify \fB-fit\fP.
+.sp
+You specify the default value with a \fB-missingcolor\fP option; it defaults
+to the value from the top left corner of the lookup image.
+
+.PP
+With ordered pair indexes (which implies whole tuple indexing), the same
+rule applies to the height of the index image as to the width.
+.PP
+The mandatory \fB-lookupfile\fP option identifies the file containing the
+lookup table image.  \fB-\fP means Standard Input.  It won't work if both the
+index image file and lookup table file are Standard Input.
+.PP
+You can use \fBppmmake\fP and \fBpnmcat\fP to create a lookup table file.
+
+
+.UN wholetuple
+.SS Example - Whole Tuple Indexing
+.PP
+Here is an example of \fBpamlookup\fP's function with whole
+tuple indexing (\fB-byplane\fP not specified).
+.PP
+Consider an index image consisting of a 3x2x1 PAM as follows:
+
+.TS
+l l l.
+0	1	0
+2	2	2
+.TE
+
+and a lookup table consisting of a 3x1 PPM image as follows:
+
+.TS
+l l l.
+red	yellow	beige
+.TE
+
+The lookup table above says Index 0 corresponds to the color red,
+Index 1 corresponds to yellow, and Index 2 corresponds to beige.  The output
+of \fBpamlookup\fP is the following PPM image:
+
+.TS
+l l l.
+red	yellow	red
+beige	beige	beige
+.TE
+.PP
+Now let's look at an example of the more complex case where the
+indices are ordered pairs of whole numbers instead of whole numbers.
+Our index image will be this 3x2x2 PAM image:
+
+.TS
+l l l.
+(0,0)	(0,1)	(0,0)
+(1,1)	(1,0)	(0,0)
+.TE
+
+Our lookup table for the example will be this two dimensional PPM:
+
+.TS
+l l l.
+red	yellow	red
+black	green	red
+.TE
+
+
+.UN byplane
+.SS Example - By Plane Indexing
+.PP
+Here is an example of \fBpamlookup\fP's function with by plane
+tuple indexing (\fB-byplane\fP specified).
+.PP
+Consider an index image consisting of a 3x2x3 PAM as follows:
+
+.TS
+l l l.
+(0,0,0)	(1,0,0)	(2,0,0)
+(2,2,0)	(2,0,2)	(2,0,0)
+.TE
+
+and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:
+
+.TS
+l l l.
+3	4	7
+.TE
+
+The lookup table above says Index 0 corresponds to the sample value 3, Index 1
+corresponds to 4, and Index 2 corresponds to 7.  The output of
+\fBpamlookup\fP is the following 3x2x3 PAM image:
+
+.TS
+l l l.
+(3,3,3)	(4,3,3)	(7,3,3)
+(7,7,3)	(7,3,7)	(7,3,3)
+.TE
+
+
+.UN misc
+.SS Miscellaneous
+.PP
+The \fIindexfile\fP argument identifies the file containing the index PAM
+or PNM image.  \fB-\fP means Standard Input.
+It won't work if both the
+index image file and lookup table file are Standard Input.
+
+The output image goes to Standard Output.
+.PP
+If you want to use two separate 1-plane images as indices (so that your
+output reflects the combination of both inputs), use \fBpamstack\fP to combine
+the two into one two-plane image (and use a 2-dimensional lookup table image).
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamlookup\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-lookupfile=\fP\fIlookupfile\fP
+\fIlookupfile\fP names the file that contains the PAM or PNM
+image that is the lookup table.  This option is mandatory.
+
+.TP
+\fB-byplane\fP
+This options selects by plane indexing.  The default is whole tuple
+indexing.
+.sp
+This option was new in Netpbm 10.72 (September 2015).  Before that, there
+is no by plane indexing.
+
+.TP
+\fB-missingcolor=\fP\fIcolor\fP
+This option is meaningful only if the lookup image (and therefore the 
+output) is a PNM image.  \fIcolor\fP specifies the color that 
+is to go in the output wherever the index from the input is not present
+in the lookup table (not present means the index exceeds the dimensions
+of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1
+PPM).
+.sp
+If you don't specify this option or \fB-fit\fP, \fBpamlookup\fP
+uses the value from the top left corner of the lookup image whenever
+an index exceeds the dimensions of the lookup image.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Another way to deal with a too-small lookup image is to use the 
+\fB-fit\fP option.
+.sp
+This option has no effect if you also specify \fB-fit\fP or
+\fB-byplane\fP.
+
+.TP
+\fB-fit\fP
+This option says to shrink or expand the lookup image as necessary
+to fit the indices present in the index image, per the index image's
+maxval.  For example, if your index image has a single plane and a
+maxval of 255 and your lookup image is 1 row of 10 columns,
+\fBpamlookup\fP stretches your lookup image to 255 columns before
+doing the lookups.  \fBpamlookup\fP does the stretching (or
+shrinking) with the
+.BR "\fBpamscale\fP" (1)\c
+\&
+program.
+.sp
+When you use \fB-fit\fP, \fBpamlookup\fP never fails or warns you
+because of invalid lookup image dimensions, and the \fB-missingcolor\fP
+option has no effect.
+.sp
+\fB-fit\fP has no effect when you specify \fB-byplane\fP.
+\fBpamlookup\fP always has the behavior requested by \fB-fit\fP when it does
+by plane indexing.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.SS Example: rainfall map
+.PP
+Say you have a set of rainfall data in a single plane PAM image.
+The rows and columns of the PAM indicate latitude and longitude.  The
+sample values are the annual rainfall in (whole) centimeters.  The highest
+rainfall value in the image is 199 centimeters.  The image is in the file
+rainfall.pam.
+.PP
+You want to produce a PPM rainfall map with green for the wettest places,
+red for the driest, and other colors in between.
+.PP
+First, compose a lookup table image, probably with a graphical editor
+and the image blown way up so you can work with individual pixels.  The
+image must have a single row and 200 columns.  Make the leftmost pixel 
+red and the rightmost pixel green and choose appropriate colors in between.
+Call it colorkey.ppm.
+
+.nf
+\f(CW
+    pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
+\fP
+
+.fi
+.PP
+Now lets say you're too lazy to type in 200 color values and nobody really
+cares about the places that have more than 99 centimeters of annual 
+rainfall.  In that case, just make colorkey.ppm 100 columns wide and do
+this:
+
+.nf
+\f(CW
+    pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \e
+       >rainfallmap.ppm
+\fP
+
+.fi
+
+Now if there are areas that get more than 100 centimeters of rainfall, they
+will just show up black in the output.
+
+.SS Example: graphical diff
+.PP
+Say you want to compare two PBM (black and white) images visually.  Each
+consists of black foreground pixels on a white background.  You want to
+create an image that contains background where both images contain background
+and foreground where both images contain foreground.  But where Image 1
+has a foreground pixel and Image 2 does not, you want red in the output;
+where Image 2 has a foreground pixel and Image 1 does not, you want green.
+.PP
+First, we create a single image that contains the information from both
+input PBMs:
+
+.nf
+\f(CW
+    pamstack image1.pbm image2.pbm >bothimages.pam
+\fP
+
+.fi
+
+Note that this image has 1 of 4 possible tuple values at each location:
+(0,0), (0,1), (1,0), or (1,1).
+.PP
+Now, we create a lookup table that we can index with those 4 values:
+
+.nf
+\f(CW
+    ppmmake white 1 1 >white.ppm
+    ppmmake black 1 1 >black.ppm
+    ppmmake red   1 1 >red.ppm
+    ppmmake green 1 1 >green.ppm
+    pnmcat -leftright black.ppm red.ppm   >blackred.ppm
+    pnmcat -leftright green.ppm white.ppm >greenwhite.ppm
+    pnmcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
+\fP
+
+.fi
+.PP
+Finally, we look up the indices from our index in our lookup table and
+produce the output:
+
+.nf
+\f(CW
+    pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
+\fP
+
+.fi
+
+     
+.UN seealso
+.SH SEE ALSO
+.BR "pamunlookup" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pamstack" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamlookup\fP was new in Netpbm 10.13 (December 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamlookup.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pammasksharpen.1 b/upstream/mageia-cauldron/man1/pammasksharpen.1
new file mode 100644
index 00000000..f93a2e03
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pammasksharpen.1
@@ -0,0 +1,156 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pammasksharpen User Manual" 0 "14 June 2006" "netpbm documentation"
+
+.SH NAME
+pammasksharpen - Sharpen an image via an unsharp mask
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpammasksharpen\fP
+[\fB-sharpness=\fP\fIrealnum\fP]
+[\fB-threshold=\fP\fIrealnum\fP]
+\fImaskfile\fP [\fIinputfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+   pamgauss 5 5 -sigma=.7 -tupletype=GRAYSCALE | pamtopnm > gauss.pgm
+   pnmconvol -nooffset gauss.pgm myimage.ppm > blurred.ppm
+   pammasksharpen blurred.ppm myimage.ppm > sharpened.ppm
+
+.fi
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpammasksharpen\fP reads a Netpbm image as input and produces a
+sharpened version of it, in the same format, as output.  It does this
+via an unsharp mask, which you supply as another Netpbm image.
+.PP
+An unsharp mask is generally a blurred version of the original
+image.  The sharpening computation is this: Calculate the
+"edgeness" of a sample in the input image as the signed
+difference between the sample value and the corresponding sample in
+the unsharp mask.  This tells how different the pixel is from its
+neighbors.  Add a multiple of the edgeness to the original sample to
+get the corresponding output sample.  Clip as necessary.  This causes
+pixels that are brighter than their neighbors to get even brighter,
+while pixels that are dimmer than their neighbors get even dimmer.
+This makes edges -- places where pixel values change quickly in space
+-- stand out more.
+.PP
+The unsharp mask must be the same dimensions and have the same maxval
+as the input image.
+
+.SS The Unsharp Mask
+.PP
+You usually create the unsharp mask as a Gaussian blur of the
+original image, which you can do using \fBpamgauss\fP and
+\fBpnmconvol\fP as in the example above.  The convolution kernel you
+use with \fBpnmconvol\fP is normally a square with side length an odd
+number of pixels.
+.PP
+When you create an unsharp mask like this, you will have to choose
+the side length of the convolution kernel.  That length implements the
+parameter of unsharp mask sharpening usually known as
+"radius."  In particular, a radius of R pixels corresponds to a 
+convolution kernel 2R+1 pixels on a side.
+.PP
+Radius is a very important parameter; you can ruin an image with a
+radius too large.  You can safely use the highest radius with an
+inanimate object, while a human face demands the least.  Landscapes
+fall in between.  But it really depends on the size of the details.
+Fine detail needs a smaller radius, or else you may obliterate tiny
+detail of the same size as the Radius width.  A large image often has
+larger detail (more pixels involved), so can use a larger radius.
+Radius and sharpness (see \fB-sharpness\fP option) interact: reducing
+one allows you to increase the other.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpammasksharpen\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-sharpness=\fP\fIrealnum\fP
+This specifies the magnitude of the sharpening.  It is the multiple
+of edgeness that gets added to each sample as described above.
+.sp
+\fIrealnum\fP is a nonnegative real decimal number.  Zero means
+no sharpening at all.
+.sp
+This parameter is known as "amount" in ImageMagick.
+.sp
+The default is 1.0.
+.sp
+This option was new in Netpbm 10.30 (October 2005).  Before that,
+the sharpness was always 1.0.
+
+.TP
+\fB-threshold=\fP\fIrealnum\fP
+This minimum amount of edgeness that will be considered edgeness
+at all.  i.e. if the magnitude of the edgeness is less than this,
+\fBpammasksharpen\fP will treat the edgeness as zero.
+.sp
+A nonzero value may be necessary here to avoid speckling in smooth
+areas.
+.sp
+This is a fraction of the maxval (so it is in the range [0, 1.0]).
+.sp
+The default is 0.
+.sp
+This option was new in Netpbm 10.34 (June 2006).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pamedge" (1)\c
+\&,
+.BR "pamsharpness" (1)\c
+\&,
+.BR "pamsharpmap" (1)\c
+\&,
+.BR "pamarith" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpammasksharpen\fP was new in Netpbm 10.23 (July 2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pammasksharpen.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pammixinterlace.1 b/upstream/mageia-cauldron/man1/pammixinterlace.1
new file mode 100644
index 00000000..706372b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pammixinterlace.1
@@ -0,0 +1,109 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pammixinterlace User Manual" 0 "22 February 2007" "netpbm documentation"
+
+.SH NAME
+pammixinterlace - mix adjacent lines to merge interlaced images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpammixinterlace\fP
+
+[\fB-filter=\fP{\fBlinear\fP, \fBfir\fP, \fBffmpeg\fP}]
+
+[\fB-adaptive\fP]
+
+[\fIinfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpammixinterlace\fP is meant to operate on an image which is the
+interlacing of two images, where raster rows 0, 2, 4, etc. are from
+one image and rows 1, 3, 5, etc. are from another.  (See below for
+why you might expect to encounter such an image).
+.PP
+\fBpammixinterlace\fP makes each row of the output a mixture
+of the corresponding row of the input and its two neighbors.  It uses
+half of the main row and a quarter each of the two neighbor rows.
+.PP
+This can be useful if the image is a video capture from an
+interlaced video source.  In that case, each row shows the subject
+1/60 second before or after the two rows that surround it.  If the
+subject is moving, this can detract from the quality of the image.
+.PP
+In video data streams, you often find each frame contains only half
+the rows of the image -- the odd half or the even half.  The displayer
+of the stream displays the rows in their proper positions on a CRT as
+they come in.  When you display the rows in this order, the CRT has
+less flicker because a particular area of the screen gets refreshed
+twice as often.  In the process of capturing such a stream, computers
+often generate the interlaced image of the type that
+\fBpammixinterlace\fP works with.  But this interlaced image, when
+displayed on a CRT, does not look the same as if a displayer were
+rendering the stream directly on a CRT as it arrived, because of the
+timing of when the various pixels get drawn and subsequently fade.
+That's why you need something like \fBpammixinterlace\fP.
+.PP
+You may prefer the effect of simply extracting one of two images.
+You can do that with \fBpamdeinterlace\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpammixinterlace\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-filter=\fP{\fBlinear\fP,\fBfir\fP,\fBffmpeg\fP}
+This option chooses between one of the three filtering mechanisms.
+\fBlinear\fP is a linear-blend formula.  \fBfir\fP is a size-5 FIR
+low-pass filter, and \fBffmpeg\fP is a formula pulled from the
+documentation of the program 
+.UR http://ffmpeg.mplayerhq.hu
+\fBffmpeg\fP
+.UE
+\&.
+.sp
+The default is \fBfir\fP.
+
+.TP
+\fB-adaptive\fP
+This option turns on "adaptive" filtering mode.  In this mode
+\fBpammixinterlace\fP modifies only pixels that are obviously part of
+a "comb" pattern.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamdeinterlace" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pammixinterlace.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pammosaicknit.1 b/upstream/mageia-cauldron/man1/pammosaicknit.1
new file mode 100644
index 00000000..a9081dcd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pammosaicknit.1
@@ -0,0 +1,159 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pammosaicknit User Manual" 0 "12 December 2010" "netpbm documentation"
+
+.SH NAME
+
+pammosaicknit - validate a mosaic knitting pattern
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpammosaicknit\fP [\fIin_netpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpammosaicknit\fP helps the user create
+.UR http://en.wikipedia.org/wiki/Slip-stitch_knitting#Mosaic_knitting
+mosaic knitting patterns
+.UE
+\&. The program inputs a black-and-white Netpbm image that
+describes a mosaic knitting pattern and outputs a color Netpbm image of the
+same pattern but with invalid runs shown in red.
+.PP
+A valid knitting pattern starts with a "black" row on the
+bottom and alternates "white" and "black"
+rows. A "black" row can contain any arrangement of black pixels
+but no more than three consecutive white pixels. A "white" row
+can contain any arrangement of white pixels but no more than three
+consecutive black pixels. Columns wrap horizontally, so a "white"
+row that both begins and ends with two black pixels is deemed to
+contain four consecutive black pixels. Because this is an invalid
+number for a "white" row, those four pixels will be recolored red
+in the output image.
+.PP
+For clarity, there are two shades of red in the output image.  Dark
+red pixels indicate pixels that were black in the input image but
+which must contain one or more white pixels. Light red pixels indicate
+pixels that were white in the input image but which must contain one
+or more black pixels.
+.PP
+If the output image contains no red pixels, then the input image
+represents a valid mosaic knitting pattern.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpammosaicknit\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+\fBpammosaicknit\fP's only argument,
+\fIin_netpbmfile\fP, is the name of an image file that represents a mosaic
+knitting pattern. If you don't specify
+\fIin_netpbmfile\fP, the program reads the image from Standard Input.
+
+
+.UN notes
+.SH NOTES
+.PP
+If the input image is not a black-and-white image, \fBpammosaicknit\fP
+converts it internally to black and white by thresholding each pixel's
+luminosity. The output image is always a color image containing at most four
+colors (black, white, dark red, light red).
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+pammosaicknit was new in Netpbm 10.53 (December 2010).
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2010 Scott Pakin,
+\fIscott+pbm@pakin.org\fP
+
+
+.UN index
+.SH Table Of Contents
+
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #arguments
+ARGUMENTS
+.UE
+\&
+.IP \(bu
+
+.UR #notes
+NOTES
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.IP \(bu
+
+.UR #author
+AUTHOR
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pammosaicknit.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamoil.1 b/upstream/mageia-cauldron/man1/pamoil.1
new file mode 100644
index 00000000..7cb0c1ca
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamoil.1
@@ -0,0 +1,92 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamoil User Manual" 0 "25 June 2001" "netpbm documentation"
+
+.SH NAME
+
+pamoil - turn a PAM image into an oil painting
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamoil\fP
+
+[\fB-n\fP \fIN\fP]
+
+[\fIpamfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamoil\fP reads a Netpbm image as input and does an "oil
+transfer", and writes the same type of Netpbm image as output.
+.PP
+The oil transfer is described in "Beyond Photography" by
+Holzmann, chapter 4, photo 7.  It's a sort of localized smearing.
+.PP
+The smearing works like this: First, assume a grayscale image.  For
+each pixel in the image, \fBpamoil\fP looks at a square neighborhood
+around it.  \fBpamoil\fP determines what is the most common pixel
+intensity in the neighborhood, and puts a pixel of that intensity into
+the output in the same position as the input pixel.
+.PP
+For color images, or any arbitrary multi-channel image,
+\fBpamoil\fP computes each channel (e.g. red, green, and blue)
+separately the same way as the grayscale case above.
+.PP
+At the edges of the image, where the regular neighborhood would run
+off the edge of the image, \fBpamoil\fP uses a clipped neighborhood.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamoil\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-n\fP \fIsize\fP
+This is the size of the neighborhood used in the smearing.  The
+neighborhood is this many pixels in all four directions.
+.sp
+The default is 3.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmbentley" (1)\c
+\&,
+.BR "ppmrelief" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+This program is based on pgmoil Copyright (C) 1990 by Wilson Bent
+(\fIwhb@hoh-2.att.com\fP)
+.PP
+Modified to ppm by Chris Sheppard, June 25, 2001
+.PP
+Modified to pnm, using pam functions, by Bryan Henderson June 28,
+2001.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamoil.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pampaintspill.1 b/upstream/mageia-cauldron/man1/pampaintspill.1
new file mode 100644
index 00000000..ffc21c56
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pampaintspill.1
@@ -0,0 +1,241 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pampaintspill User Manual" 0 "02 November 2021" "netpbm documentation"
+
+.SH NAME
+.PP
+pampaintspill - smoothly spill colors into the background
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpampaintspill\fP
+[\fB--bgcolor\fP=\fIcolor\fP]
+[\fB--wrap\fP]
+[\fB--all\fP]
+[\fB--downsample\fP=\fInumber\fP]
+[\fB--near\fP=\fInumber\fP]
+[\fB--power\fP=\fInumber\fP] [\fIfilename\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpampaintspill\fP produces a smooth color gradient from all of the
+non-background-colored pixels in an input image, effectively "spilling
+paint" onto the background.  \fBpampaintspill\fP is similar to
+\fBpamgradient\fP but differs in the following characteristics:
+
+
+.IP \(bu
+\fBpampaintspill\fP accepts any number of paint
+      sources (non-background-colored pixels), which can lie anywhere
+      on the canvas.  \fBpamgradient\fP accepts exactly
+      four paint sources, one in each corner of the image.
+
+.IP \(bu
+\fBpampaintspill\fP requires an input image while
+      \fBpamgradient\fP generates a new image from
+      scratch.
+
+.IP \(bu
+\fBpampaintspill\fP can produce tileable output and
+      can control how tightly the gradient colors bind to their source
+      pixels.
+
+.PP
+Results are generally best when the input image contains just a few, crisp
+spots of color. Use your drawing program's pencil tool - as opposed to a
+paintbrush or airbrush tool - with a small nib.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpampaintspill\fP recognizes the following
+command line options:
+
+
+.TP
+\fB--bgcolor\fP=\fIcolor\fP
+  
+Explicitly specify the background color. \fIcolor\fP can be
+      specified using any of the formats accepted by the 
+.UR libnetpbm_image.html#colorname
+\f(CWpnm_parsecolor()\fP library       routine
+.UE
+\& such as \f(CWred\fP or \f(CW#ff0000\fP.  If
+      \fB--bgcolor\fP is not specified, \fBpampaintspill\fP makes an
+      educated guess about the background color based on the colors in the
+      image's corners.
+
+.TP
+\fB--wrap\fP
+  
+Allow gradients to wrap around image borders. That is, colors
+      that spill off the right side of the image reappear on the left side of
+      the image and likewise for left/right, top/bottom, and
+      bottom/top. \fB--wrap\fP makes images tileable, which is nice for
+      producing desktop backgrounds.
+
+.TP
+\fB--all\fP
+  
+Recolor all pixels, not just background pixels. Normally,
+      non-background-colored pixels in the input image appear unmodified in
+      the output image. With \fB--all\fP, \fIall\fP pixels are colored
+      based on their distance from all of the (other) non-background-colored
+      pixels.
+
+.TP
+\fB--downsample\fP=\fInumber\fP
+  
+Ignore all but \fInumber\fP non-background-colored pixels.
+      When a large number of pixels in the input image differ in color from
+      the background, \fBpampaintspill\fP runs very slowly. The
+      \fB--downsample\fP option randomly selects a given number of colored
+      pixels to use as paint sources for the gradients and ignores the rest,
+      thereby trading off image quality for speed of execution.
+
+.TP
+\fB--near\fP=\fInumber\fP
+  
+Consider only the nearest \fInumber\fP paint sources when computing
+      a pixel's new color.  The default is to consider all paint sources.
+      In most cases, \fInumber\fP should be fairly small, or its impact
+      will be minimal and execution time will increase unnecessarily.  A
+      value of 1 produces a coloring that looks a lot like a Voronoi
+      diagram.
+.sp
+This option was new in Netpbm 10.97 (December 2021).
+
+.TP
+\fB--power\fP=\fInumber\fP
+  
+Control how color intensity changes as a function of the
+      distance from a paint source. The default value for \fInumber\fP is
+      -2.0, which means that intensity drops (because of the minus sign) with
+      the square (because of the 2.0) of the distance from each paint
+      source. -2.0 generally works well in practice, but other values can be
+      specified for various special effects. With very small numbers of paint
+      sources, -1.0 may produce subtler gradients, but these get muddier as
+      the number of paint sources increases. Positive numbers (e.g., 1.0 and
+      2.0) make the paint sources stand out in the output image by pushing the
+      gradients away from them.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+  
+This is the seed for the random number generator that generates the
+  pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+This option was new in Netpbm 10.94 (March 2021).
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "\fBpamgradient\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBppmmake\fP" (1)\c
+\&,
+.IP \(bu
+
+.BR "\fBppmrainbow\fP" (1)\c
+\&,
+.IP \(bu
+
+.BR "\fBpgmramp\fP" (1)\c
+\&,
+.IP \(bu
+
+.BR "\fBppmpat\fP" (1)\c
+\&,
+.IP \(bu
+
+.BR "\fBpam\fP" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpampaintspill\fP was new in Netpbm 10.50 (March 2010).
+
+
+.UN copyright
+.SH COPYRIGHT
+.PP
+Copyright\ \(co 2010&ndash;2021 Scott Pakin,
+\fI\fIscott+pbm@pakin.org\fP\fP.
+
+.UN index
+.SH Table Of Contents
+
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.IP \(bu
+
+.UR #copyright
+COPYRIGHT
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pampaintspill.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamperspective.1 b/upstream/mageia-cauldron/man1/pamperspective.1
new file mode 100644
index 00000000..49dab01d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamperspective.1
@@ -0,0 +1,599 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamperspective User Manual" 0 "02 September 2004" "netpbm documentation"
+
+.SH NAME
+
+pamperspective - a reverse scanline renderer for Netpbm images
+
+.UN synopsis
+.SH SYNOPSIS
+
+.nf
+\fBpamperspective\fP 
+    [\fB--bottom_margin=\fP\fInum\fP]
+    [\fB--detail=\fP\fInum\fP]
+    [\fB--frame_include=\fP\fIbool\fP]
+    [\fB--height=\fP\fInum\fP]
+    [\fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]]
+    [\fB--input_system=\fP\fIspec\fP]
+    [\fB--input_unit=\fP\fIspec\fP]
+    [\fB--interpolation=\fP\fIspec\fP]
+    [\fB--left_margin=\fP\fInum\fP]
+    [\fB--margin=\fP\fInum\fP]
+    [\fB--output_system=\fP\fIspec\fP]
+    [\fB--proportion=\fP\fIspec\fP]
+    [\fB--ratio=\fP\fInum\fP]
+    [\fB--right_margin=\fP\fInum\fP]
+    [\fB--top_margin=\fP\fInum\fP]
+    [\fB--width=\fP\fInum\fP]
+    {
+      {
+        \fIupper_left_x\fP \fIupper_left_y\fP \fIupper_right_x\fP \fIupper_right_y\fP
+        \fIlower_left_x\fP \fIlower_left_y\fP \fIlower_right_x\fP \fIlower_right_y\fP
+      }
+      |
+      {
+        {\fB--upper_left_x\fP|\fB--ulx\fP}\fB=\fP\fIupper_left_x\fP
+        {\fB--upper_left_y\fP|\fB--uly\fP}\fB=\fP\fIupper_left_y\fP
+        {\fB--upper_right_x\fP|\fB--urx\fP}\fB=\fP\fIupper_right_x\fP
+        {\fB--upper_right_y\fP|\fB--ury\fP}\fB=\fP\fIupper_right_y\fP
+        {\fB--lower_left_x\fP|\fB--llx\fP}\fB=\fP\fIlower_left_x\fP
+        {\fB--lower_left_y\fP|\fB--lly\fP}\fB=\fP\fIlower_left_y\fP
+        {\fB--lower_right_x\fP|\fB--lrx\fP}\fB=\fP\fIlower_right_x\fP
+        {\fB--lower_right_y\fP|\fB--lry\fP}\fB=\fP\fIlower_right_y\fP
+      }
+   }
+   [\fIinfile\fP]
+
+
+.fi
+
+.SH OPTION USAGE
+.PP
+Minimum unique abbreviation of option is acceptable. (But note 
+that shortest unique prefixes might be longer in future versions of 
+the program.) You may use single hyphens instead of double hyphen to 
+denote options. You may use white space in place of the equals sign 
+to separate an option name from its value. All options starting with 
+hyphens may be given in any order. 
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamperspective\fP reads a Netpbm image as input and produces a
+Netpbm image of the same format as output.
+.PP
+\fBpamperspective\fP interprets the input image as a perspective
+projection of another image which is in a plane oblique to that of the
+input image.  For example, a photograph of a painting, taken at an
+angle.  The arguments \fIupper_left_x\fP ... \fIlower_right_y\fP
+specify a quadrilateral in the photograph that \fBpamperspective\fP
+assumes corresponds to a parallelogram in the painting.  The output
+image consists of this parallelogram, sheared to a rectangle.  In this
+way \fBpamperspective\fP undoes the effect of a raytracer or scanline
+renderer.
+.PP
+Note that if the input image is a projection of a solid scene,
+rather than a plane, the result is like a different camera angle on
+that scene, to the extent that the scene is shallow from the other
+angle.
+.PP
+The input is from \fIinfile\fP, or from Standard Input, if
+\fIinfile\fP is not specified.  The output is to Standard Output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamperspective\fP recognizes the following
+command line options:
+.PP
+For options of the form \fB--name=\fP\fInum\fP, You can specify
+the value \fInum\fP in any of the traditional ways.  Additionally,
+you can specify it as \fInum1\fP/\fInum2\fP, where \fInum1\fP and
+\fInum2\fP are specified traditionally.  This is useful for
+specifying a width/height ratio of 4/3, without having to write
+infinitely many digits.  Where \fInum\fP is supposed to be a natural
+number, \fBpamperspective\fP does not allow this format.
+
+.UN quadspecoptions
+.SS Quadrilateral Specification Options
+
+
+.TP
+\fB--upper_left_x=\fP\fInum\fP
+.TP
+\fB--ulx=\fP\fInum\fP
+
+  
+This specifies the horizontal coordinate of the upper left
+  vertex of the quadrilateral.  The meaning of 'upper left' is
+  relative to the output image.  The interpretation of \fInum\fP
+  depends on the values for \fB--input_system\fP and
+  \fB--input_unit\fP.
+
+.TP
+\fB--upper_left_y=\fP\fInum\fP
+.TP
+\fB--uly=\fP\fInum\fP
+
+  
+This specifies the vertical coordinate of the upper left vertex
+  of the quadrilateral.  The meaning of 'upper left' is relative to
+  the output image.  The interpretation of \fInum\fP depends on the
+  values for \fB--input_system\fP and \fB--input_unit\fP.
+
+.TP
+\fB--upper_right_x=\fP\fInum\fP
+.TP
+\fB--urx=\fP\fInum\fP
+
+  
+This specifies the horizontal coordinate of the upper right
+  vertex of the quadrilateral.  The meaning of 'upper right' is
+  relative to the output image.  The interpretation of \fInum\fP
+  depends on the values for \fB--input_system\fP and
+  \fB--input_unit\fP.
+
+.TP
+\fB--upper_right_y=\fP\fInum\fP
+.TP
+\fB--ury=\fP\fInum\fP
+
+  
+This specifies the vertical coordinate of the upper right vertex
+  of the quadrilateral.  The meaning of 'upper right' is relative to
+  the output image.  The interpretation of \fInum\fP depends on the
+  values for \fB--input_system\fP and \fB--input_unit\fP.
+
+.TP
+\fB--lower_left_x=\fP\fInum\fP
+.TP
+\fB--llx=\fP\fInum\fP
+
+  
+This specifies the horizontal coordinate of the lower left
+  vertex of the quadrilateral.  The meaning of 'lower left' is
+  relative to the output image.  The interpretation of \fInum\fP
+  depends on the values for \fB--input_system\fP and
+  \fB--input_unit\fP.
+
+.TP
+\fB--lower_left_y=\fP\fInum\fP
+.TP
+\fB--lly=\fP\fInum\fP
+
+  
+This specifies the vertical coordinate of the lower left vertex
+  of the quadrilateral.  The meaning of 'lower left' is relative to
+  the output image.  The interpretation of \fInum\fP depends on the
+  values for \fB--input_system\fP and \fB--input_unit\fP.
+
+.TP
+\fB--lower_right_x=\fP\fInum\fP
+.TP
+\fB--lrx=\fP\fInum\fP
+
+  
+This specifies the horizontal coordinate of the lower right
+  vertex of the quadrilateral.  The meaning of 'lower right' is
+  relative to the output image.  The interpretation of \fInum\fP
+  depends on the values for \fB--input_system\fP and
+  \fB--input_unit\fP.
+
+.TP
+\fB--lower_right_y=\fP\fInum\fP
+.TP
+\fB--lry=\fP\fInum\fP
+
+  
+This specifies the vertical coordinate of the lower right vertex
+  of the quadrilateral.  The meaning of 'lower right' is relative to
+  the output image.  The interpretation of \fInum\fP depends on the
+  values for \fB--input_system\fP and \fB--input_unit\fP.
+
+.TP
+\fB--input_system=\fP\fIsystem\fP
+.TP
+\fB--input_unit=\fP\fIunit\fP
+
+  
+The input image consists of pixels, which are, from the point of
+  view of a scanline renderer, solid squares.  These options specify
+  how the coordinates are interpreted:
+
+
+.TP
+\fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBimage\fP
+
+    
+(0,0) refers to the upper left corner of the upper left pixel
+    and (1,1) refers to the lower right corner of the lower right
+    pixel.
+
+.TP
+\fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBpixel\fP
+
+    
+(0,0) refers to the upper left corner of the upper left pixel
+    and (\fIwidth\fP,\fIheight\fP) refers to the lower right corner
+    of the lower right pixel.  Here \fIwidth\fP and \fIheight\fP are
+    the width and height of the input image.
+
+.TP
+\fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBimage\fP
+
+    
+(0,0) refers to the center of the upper left pixel and (1,1)
+    refers to the center of the lower right pixel.
+
+.TP
+\fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBpixel\fP
+
+    
+(0,0) refers to the center of the upper left pixel and
+    (\fIwidth\fP-1,\fIheight\fP-1) refers to the center of the lower
+    right pixel.  Here \fIwidth\fP and \fIheight\fP are the width
+    and height of the input image.
+
+
+
+  The defaults are \fB--input_system\fP=\fBlattice\fP and
+  \fB--input_unit\fP=\fBpixel\fP.  Point-and-click front ends should
+  use \fB--input_system\fP=\fBpixel\fP.
+
+
+
+.UN frameoptions
+.SS Frame Options
+
+By default \fBpamperspective\fP outputs exactly the above
+parallelogram, sheared to a rectangle.  With the following options, it
+is possible to make \fBpamperspective\fP output a larger or smaller
+portion, which we call the "visible part." We refer to the
+default rectangle as the "frame." The visible part is always
+a rectangle the axes of which are parallel to those of the frame.
+.PP
+The frame options are additive.  All the parts of the image
+specified by either margin options, \fB--frame_include\fP, or
+\fB--include\fP (or their defaults) are in the visible part.  The
+visible part is the smallest possible rectangle that contains the
+parts specified those three ways.
+.PP
+The visible part must have nonzero size.  That means if you specify
+\fB--frame_include=no\fP (overriding the default), you'll need to
+specify other frame options in order to have something in the visible
+part.
+
+
+.TP
+[\fB--margin=\fP\fInum\fP]
+
+  
+This specifies an area surrounding the frame that is to be
+  included in the visible part.  The units of \fInum\fP are the width
+  of the frame for the horizontal extensions and the height of the
+  frame for vertical extensions.
+.sp
+For example, \fB--margin=1\fP makes the visible part 9 times as large,
+  because it makes the visible part extend one frame's worth to the left
+  of the frame, one frame's worth to the right, one frame's worth above
+  the frame, and one frame's worth below the frame, for a total of
+  3 frames' worth in both dimensions.
+.sp
+A negative value has an effect only if you specify
+  \fB--frame_include=no\fP.  The default is no margin.
+.sp
+The individual margin options below override this common margin
+  setting.
+
+
+.TP
+[\fB--top_margin=\fP\fInum\fP]
+.TP
+[\fB--left_margin=\fP\fInum\fP]
+.TP
+[\fB--right_margin=\fP\fInum\fP]
+.TP
+[\fB--bottom_margin=\fP\fInum\fP]
+
+  
+These are like \fB--margin\fP, but they specify only one of 
+  the 4 sides.  The default value for each is the value (or default) of
+  \fB--margin\fP.
+
+
+.TP
+[\fB--frame_include=\fP\fIbool\fP]
+
+  
+Valid values for \fIbool\fP are:
+
+
+.TP
+\fByes\fP
+.TP
+\fBtrue\fP
+.TP
+\fBon\fP
+
+    
+The frame itself is in the visible part.
+
+.TP
+\fBno\fP
+.TP
+\fBfalse\fP
+.TP
+\fBoff\fP
+
+    
+The frame itself is not necessarily in the visible part
+    (but it could be if other options cause it to be).
+
+
+
+
+  The default value is \fByes\fP
+
+.TP
+\fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]
+
+  
+The visible part is made large enough such that every point
+  (\fIx1\fP,\fIy1\fP), (\fIx2\fP,\fIy2\fP), of the \fIinput\fP image is 
+  visible.  The meaning of \fIx\fP and \fIy\fP is determined by
+  \fB--input_system\fP and \fB--input_unit\fP.  You can specify any
+  number of semicolon-delimited points, including zero.
+.sp
+If you're supplying these options via a Unix command shell, be
+  sure to use proper quoting, because semicolon (\fB;\fP) is usually
+  a shell control character.
+
+
+
+  
+.PP
+The frame options were new in Netpbm 10.25 (October 2004).
+
+.UN outputsizeoptions
+.SS Output Size Options
+
+
+.TP
+\fB--width=\fP\fIwidth\fP
+.TP
+\fB--height=\fP\fIheight\fP
+
+  
+These specify the size of the output image in horizontal and
+  vertical direction.  The values are numbers of pixels, so only
+  natural numbers are valid.  These values override the default
+  means to determine the output size.
+
+.TP
+\fB--detail=\fP\fInum\fP
+
+  
+If you do not specify \fB--width\fP, \fBpamperspective\fP
+  determines the width of the output image such that moving \fInum\fP
+  output pixels horizontally does not change the corresponding pixel
+  coordinates of the input image by more than 1.
+  \fBpamperspective\fP determines the height of the output image
+  analogously.  The default value is 1.
+
+.TP
+\fB--proportion=\fP\fIprop\fP
+.TP
+\fB--ratio=\fP\fIratio\fP
+
+  
+Valid values for \fIprop\fP are:
+
+
+.TP
+\fBfree\fP
+
+    
+In this case \fB--ratio\fP does not have any effect.
+
+.TP
+\fBfixed\fP
+After the width and height are determined
+    according to \fB--detail\fP, one of both will be increased, in
+    order to obtain width/height=\fIratio\fP.
+
+
+
+  The defaults are \fB--proportion\fP=\fBfree\fP and
+  \fB--ratio\fP=1.
+
+
+
+.UN outputoptions
+.SS Output Options
+
+
+.TP
+\fB--output_system=\fP\fIspec\fP
+
+  
+The output image consists of pixels, which are, from the point
+  of view of a scanline renderer, solid squares.  This option
+  specifies how the four vertices of the quadrilateral correspond to
+  the pixels of the output image.  Valid values for \fIspec\fP are:
+
+
+.TP
+\fBlattice\fP
+
+    
+The upper left vertex corresponds to the upper left corner of
+    the upper left pixel and The lower right vertex corresponds to the
+    lower right corner of the lower right
+    pixel.
+
+.TP
+\fBpixel\fP
+
+    
+The upper left vertex corresponds to the center of the upper
+    left pixel and The lower right vertex corresponds to the center of
+    the lower right pixel.
+
+
+
+  The default value is \fBlattice\fP.  Point-and-click front ends
+  should use \fBpixel\fP.
+
+.TP
+\fB--interpolation=\fP\fIspec\fP
+
+  
+Usually (centers of) output pixels do not exactly correspond to
+  (centers of) input pixels.  This option determines how the program
+  will choose the new pixels.  Valid values for \fIspec\fP are:
+
+
+.TP
+\fBnearest\fP
+
+    
+The output pixel will be identical to the nearest input
+    pixel.
+
+.TP
+\fBlinear\fP
+
+    
+The output pixel will be a bilinear interpolation of the four
+    surrounding input pixels.
+
+
+
+  The default value is \fBnearest\fP.
+
+
+
+.UN hints
+.SH HINTS
+.PP
+It might be tempting always to use the options
+\fB--include 0,0;0,1;1,0;1,1\fP 
+(assuming \fB--input_system=lattice\fP and \fB--input_unit=image\fP), 
+so that no part of the input image is missing in the output. 
+There are problems with that:
+
+
+.IP \(bu
+If the three dimensional plane defined by the quadrilateral has a
+  visible horizon in the input image, then the above asks \fBpamperspective\fP
+  to include points that cannot ever be part of the output.
+
+.IP \(bu
+If the horizon is not visible, but close to the border of the
+  input image, this may result in \fIvery\fP large output
+  files. Consider a picture of a road. If you ask for a point close to
+  the horizon to be included, then this point is far away from the
+  viewer. The output will cover many kilometers of road, while
+  \fB--detail\fP perhaps makes a pixel represent a square centimeter.
+
+  
+.PP
+When working with large files \fBpamperspective\fP's memory usage
+might be an issue.  In order to keep it small, you should minimize each
+of the following:
+
+
+.IP \(bu
+The vertical range that the top output line consumes in the
+  input image;
+
+.IP \(bu
+The vertical range that the bottom output line consumes in the
+  input image;
+
+.IP \(bu
+The vertical range from the topmost (with respect to the 
+  input image) quadrilateral point to the top (with respect to the output 
+  image) output line.
+
+  
+
+For this purpose you can use \fBpamflip\fP before and/or after
+\fBpamperspective\fP. Example: Instead of
+
+.nf
+\fBpamperspective 10 0 100 50 0 20 95 100 infile > outfile\fP
+
+.fi
+
+you can use
+
+.nf
+\fB
+pamflip -rotate90 infile | 
+   pamperspective 50 0 100 5 0 90 20 100 | 
+   pamflip -rotate270 > outfile
+\fP
+
+.fi
+  
+.UN seealso
+.SH SEE ALSO
+.BR "\fBnetpbm\fP" (1)\c
+\&,
+.BR "\fBpam\fP" (1)\c
+\&,
+.BR "\fBpnm\fP" (1)\c
+\&,
+.BR "\fBpamcut\fP" (1)\c
+\&,
+.BR "\fBpamflip\fP" (1)\c
+\&,
+.BR "\fBpnmrotate\fP" (1)\c
+\&,
+.BR "\fBpamscale\fP" (1)\c
+\&,
+.BR "\fBpnmshear\fP" (1)\c
+\&,
+.BR "\fBpamhomography\fP" (1)\c
+\&,
+.BR "\fBpnmstitch\fP" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Mark Weyer wrote \fBpamperspective\fP in March 2004.
+.PP
+It was new in Netpbm 10.22 (April 2004).
+
+
+.UN author
+.SH AUTHOR
+
+This documentation was written by Mark Weyer.  Permission is granted
+to copy, distribute and/or modify this document under the terms of the
+GNU General Public License, Version 2 or any later version published
+by the Free Software Foundation.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamperspective.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pampick.1 b/upstream/mageia-cauldron/man1/pampick.1
new file mode 100644
index 00000000..5fca18c5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pampick.1
@@ -0,0 +1,91 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pampick User Manual" 0 "25 October 2005" "netpbm documentation"
+
+.SH NAME
+
+pampick - pick images out of a multi-image Netpbm image stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpampick\fP
+
+\fIimage_sequence_number\fP ...
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpampick\fP reads a PNM or PAM image stream as input.  It
+picks certain images from the stream and copies them to a new image
+stream on Standard Output.
+.PP
+You identify the images to pick by sequence number within the stream.
+Each \fIimage_sequence_number\fP is a decimal sequence number, with zero
+meaning the first image.
+.PP
+The arguments must be in increasing order, without duplicates.  The
+results are undefined if they are not.  (There are a number of
+enhancements that might be made in future releases that would make
+whatever \fBpampick\fP does today when you break this rule change).
+\fBpampick\fP outputs the images in the same order as they appear in
+the input.  If you specify no sequence numbers, \fBpampick\fP outputs
+nothing.  If you specify a sequence number that is beyond what is in
+the input, \fBpampick\fP fails with an error message to that effect.
+.PP
+\fBpampick\fP always reads the entire input stream.  (This is helpful
+when the input stream is a pipe and whatever is feeding the pipe would be
+upset if it filled up or broke).
+.PP
+To see how many images, and what kind, are in a stream, use
+\fBpamfile\fP.
+.PP
+To extract all the images in a stream into separate named files,
+use \fBpamsplit\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpampick\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&,
+.BR "pamsplit" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+\fBcat\fP man page
+
+.UN history
+.SH HISTORY
+.PP
+\fBpampick\fP was new in Netpbm 10.31 (December 2005);
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pampick.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pampop9.1 b/upstream/mageia-cauldron/man1/pampop9.1
new file mode 100644
index 00000000..06f994eb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pampop9.1
@@ -0,0 +1,92 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pampop9 User Manual" 0 "02 March 2003" "netpbm documentation"
+
+.SH NAME
+pampop9 - simulate a multi-lens camera such as the Pop9
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpampop9\fP
+\fIpnmfile|-\fP
+\fIxtiles\fP
+\fIytiles\fP
+\fIxdelta\fP
+\fIydelta\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpampop9\fP tiles your starting image \fIxtiles\fP by \fIytiles\fP
+times.
+Each of these tiles is taken from a slightly different offset within the
+source, as determined by the \fIxdelta\fP and \fIydelta\fP arguments.
+.PP
+The top line of tiles in the output is taken from the top of the source
+image, the second starts with the \fIydelta\fP row of the source image,
+the next with the 2*\fIydelta\fP row, and so on.
+Similarly, the first column of tiles in the output is taken from the left
+of the source image, the next starts with the \fIxdelta\fP column, the
+next with the 2*\fIxdelta\fP column, and so on.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpampop9\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN examples
+.SH EXAMPLES
+.PP
+With a 100 x 100 source image, then the output image from
+\fBpampop9\fP \fI3 3 10 10\fP will appear to be a three-by-three grid,
+each tile being 80 x 80 pixels.
+If the origin is taken to be the top-left corner, then the top row of
+tiles will take start at (0, 0) (10, 0) (20, 0) within the source image,
+the middle row will start at (0, 10) (10, 10) (20, 10), and the bottom
+row at (0, 20) (10, 20) (20, 20).
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpampop9\fP was new in Netpbm 10.15 (April 2003).  It was
+adapted slightly from \fBpampup9\fP, which was distributed by Robert
+Tinsley.  At that time, it was distributed via
+http://www.thepoacher.net/code/#pampup9.  By October 2004, that URL
+no longer was valid.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtile" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2003 by Robert Tinsley.  This software is released
+under the GPL (
+.UR http://www.fsf.org/licensing/licenses/gpl.txt
+ http://www.fsf.org/licenses/gpl.txt
+.UE
+\&).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pampop9.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamrecolor.1 b/upstream/mageia-cauldron/man1/pamrecolor.1
new file mode 100644
index 00000000..171a37c3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamrecolor.1
@@ -0,0 +1,309 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamrecolor User Manual" 0 "31 July 2010" "netpbm documentation"
+.PP
+
+
+.SH NAME
+pamrecolor - alter colors without affecting luminance
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpamrecolor\fP
+[\fB--colorspace\fP=\fIname\fP]
+[\fB--rmult\fP=\fIfraction\fP]
+[\fB--gmult\fP=\fIfraction\fP]
+[\fB--bmult\fP=\fIfraction\fP]
+[\fB--targetcolor\fP=\fIcolor\fP]
+[\fB--colorfile\fP=\fIfile\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+
+[\fIinfile\fP]
+
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamrecolor\fP changes an image's colors to be as close as
+possible to given target colors but with the constraint that the
+luminance not be modified.  That is, the original image and the target
+image will look identical if both are converted to grayscale
+(e.g. with
+.BR "ppmtopgm" (1)\c
+\&).  You can have \fBpamrecolor\fP select
+target colors randomly, specify a single hue for the entire image, or take the
+target colors from a target image.
+.PP
+In addition to real Netpbm images, \fBpamrecolor\fP works on pseudo-Netpbm
+images based on arbitrary color spaces.  You can define the color space
+explicitly or choose one of many that \fBpamrecolor\fP knows by name.
+.PP
+The output is a PAM image on standard output.  Options control the
+exact format of the PAM.  If you want a PNM (PBM, PGM, or PPM) image,
+use
+.BR "pamtopnm" (1)\c
+\& on the output.  There is no
+need to convert if you will use the image as input to a current Netpbm
+program, but many other programs don't know what a PAM is.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamrecolor\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB--colorspace\fP=\fIname\fP
+Designate the color space to use for determining the contribution
+to luminance of each of the red, green, and blue color channels.  For
+example, in the SMPTE-C color space an RGB color is converted to
+grayscale by multiplying the red channel by 0.2124132, the green
+channel by 0.7010437, and the blue channel by 0.0865432 and summing
+the resulting three products.
+.sp
+When you use this option, the input and output images are not true Netpbm
+images, because the Netpbm image format specifies a particular color space.
+Instead, you are using a variation on the format in which the sample values in
+the raster have different meaning.  Many programs that ostensibly use Netpbm
+images actually use a variation with a different color space.  For example,
+.UR http://www.gimp.org/
+GIMP
+.UE
+\& uses sRGB internally and if you
+have GIMP generate a Netpbm image file, it really generates a variation of
+the format that uses sRGB.
+.sp
+\fBpamrecolor\fP knows the following color spaces (\fIname\fP values):
+
+
+.TP
+adobe
+  
+Adobe RGB (1998) with a D65 reference white
+
+.TP
+apple
+  
+Apple  RGB with a D65 reference white
+
+.TP
+cie
+  
+CIE with an Illuminant E reference white
+
+.TP
+ntsc
+  
+NTSC RGB with an Illuminant C reference white
+
+.TP
+pal
+  
+PAL/SECAM with a D65 reference white
+
+.TP
+smpte-c
+  
+SMPTE-C with a D65 reference white
+
+.TP
+srgb
+  
+sRGB with a D65 reference white
+
+.TP
+wide
+  
+Wide-gamut RGB with a D50 reference white
+
+.sp
+The default is "ntsc" because this is the color space that the Netpbm
+formats and many graphics utilities use.  As a counterexample,
+.UR http://www.gimp.org/
+GIMP
+.UE
+\& uses sRGB as its native color
+space.
+.sp
+The luminance values \fBpamrecolor\fP uses for each of the above come from
+Bruce Lindbloom's
+.BR "
+Computing RGB-to-XYZ and XYZ-to-RGB matrices" (1)\c
+\& page.
+
+.TP
+\fB--rmult\fP=\fIfraction\fP
+.TP
+\fB--gmult\fP=\fIfraction\fP
+.TP
+\fB--bmult\fP=\fIfraction\fP
+Instead of selecting a color space by name, you can specify explicitly the
+contribution of each color channel to the overall luminance as red, green, and
+blue multipliers.  These three options must be used together, and the
+three \fIfraction\fP values must sum to 1.0.  For example, you can specify
+the ProPhoto (ROMM) RGB color space with
+"\fB--rmult\fP=0.2880402 \fB--gmult\fP=0.7118741 \fB--bmult\fP=0.0000857".
+
+.TP
+\fB--targetcolor\fP=\fIcolor\fP
+Designate \fIcolor\fP as the target color for the
+image.  \fBpamrecolor\fP will make each pixel as close as possible
+to \fIcolor\fP subject to the constraint that the luminance must stay the
+same as in the original image.  Specify \fIcolor\fP as in
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\& (e.g.,\ "hotpink" or "#ff69b4").
+.sp
+If you specify neither \fB--targetcolor\fP nor
+\fB--colorfile\fP, \fBpamrecolor\fP will randomly select a target color for
+each pixel of the input image.
+.sp
+You may not specify both \fB-targetcolor\fP and \fB-colorfile\fP.
+
+
+
+.TP
+\fB--colorfile\fP=\fIfile\fP
+Take per-pixel target colors from Netpbm file \fIfile\fP instead
+of using a single target color for the entire image.
+\fIfile\fP should be a PPM or color PAM image.
+If the image in the file wider or taller than the input image,
+\fBpamrecolor\fP uses only the left and top part of it.
+If the image is narrower or shorter, \fBpamrecolor\fP considers the
+image to be repeated in a tile pattern.
+.sp
+If you specify neither \fB--targetcolor\fP nor
+\fB--colorfile\fP, \fBpamrecolor\fP will randomly select a target color for
+each pixel of the input image.
+.sp
+You may not specify both \fB-targetcolor\fP and \fB-colorfile\fP.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpamrecolor\fP uses a seed derived from the time of day
+and process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+This command tints an image yellow:
+
+.nf
+    pamrecolor --targetcolor=yellow colorpic.pam > yellowpic.pam
+
+.fi
+.PP
+This command takes the colors from \fBcolorpicture.ppm\fP and applies
+them to \fBgraypicture.pgm\fP:
+
+.nf
+    pamrecolor --colorfile=colorpic.ppm graypic.pgm > colorizedpic.pam
+
+.fi
+.PP
+The grayscale version of \fBcolorizedpic.pam\fP will look just like
+graypic.pgm.  Note that if you use a non-Netpbm tool to do the conversion to
+grayscale, you may additionally need to specify an
+appropriate \fB--colorspace\fP value for your conversion tool.
+
+
+.UN notes
+.SH NOTES
+.PP
+Here are a couple of fun special effects you can produce with
+\fBpamrecolor\fP:
+
+
+.IP \(bu
+Specify a color file that is identical to the input image but with
+some large, colored text added to it.  The text will "magically"
+vanish when the image is converted to grayscale.
+
+.IP \(bu
+Provide a low-contrast grayscale image - perhaps a secret
+message written in similar shades of gray - as the input file and
+a colorful but completely different image as the color file.  If done
+carefully, the grayscale image can be hidden by the colorful image.
+Only people who know to convert the result to grayscale can recover
+the original grayscale image.
+
+.IP \(bu
+Use \fB--targetcolor\fP=tan to make an image look like an
+old-timey photograph (or, more precisely, a
+.UR http://en.wikipedia.org/wiki/Photographic_print_toning
+sepia-toned photograph
+.UE
+\& of the late 1800s).
+
+
+
+.UN history
+.SH HISTORY
+.PP
+Scott Pakin wrote \fBpamrecolor\fP in July 2010.
+.PP
+\fBpamrecolor\fP was new in Netpbm 10.52 (September 2010).
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2010 Scott
+Pakin, \fIscott+pbm@pakin.org\fP
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "\fBppmtopgm\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBppmchange\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBpnmremap\fP" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamrecolor.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamrestack.1 b/upstream/mageia-cauldron/man1/pamrestack.1
new file mode 100644
index 00000000..c7614783
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamrestack.1
@@ -0,0 +1,206 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamrestack User Manual" 0 "" "netpbm documentation"
+
+Updated:
+.SH NAME
+pamrestack - Rearrange rows of a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamrestack\fP
+
+[\fB-width=\fP\fIwidth\fP]
+
+[\fB-trim=\fP{\fBfill\fP|\fBcrop\fP|\fBabort\fP}]
+
+[\fB-verbose\fP]
+
+[\fIpamfile\fP]
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamrestack\fP rearranges the pixels of a Netpbm image into different
+size rows.  E.g. if an image is 100 pixels wide and 50 pixels high, you can
+rearrange it to 125 wide and 40 high.  In that case, 25 pixels from the start
+of the 2nd row of the input would be moved to the end of the 1st row of input,
+50 pixels from the 3rd row would be moved to the 2nd row, etc.
+.PP
+Put another way, \fBpamrestack\fP arranges all the input rows into one
+long sequence and produces output rows therefrom, in FIFO order.
+.PP
+Input is from Standard Input if you don't specify the input
+file \fIpamfile\fP.
+.PP
+Output is to Standard Output.
+.PP
+\fBpamrestack\fP works on a multi-image stream.  It cuts each image in the
+stream independently and produces a multi-image stream output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamrestack\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-width=\fP\fIwidth\fP
+The width of the output.  If this option is not specified, the output will
+  consist of a single row wide enough to contain all the pixels of the input
+  image.
+
+.TP
+\fB-trim=\fP{\fBfill\fP|\fBcrop\fP|\fBabort\fP}
+This option specifies what to do when the new width does not cleanly
+divide the number of pixels in the input image.
+
+
+.TP
+\fBfill\fP
+  
+(Default) Complete the final row by adding black pixels as necessary.
+
+.TP
+\fBcrop\fP
+    
+Discard the final partial row.  If this means there is nothing to
+    output, fail the program.
+
+.TP
+\fBabort\fP
+  
+Fail the program..
+
+  
+.TP
+\fB-verbose\fP
+Print information about the processing to Standard Error.
+
+
+
+.UN usage
+.SH USAGE  
+.PP
+\fBpamrestack\fP is a general editor with many possible uses.
+
+.IP \(bu
+
+    \fBpamrestack\fP can rearrange into rectangles single-dimension images
+    produced by programs such as \fBppmhist\fP and \fBpamseq\fP.  This makes
+    the output easier to examine with a viewer.  Conversely, \fBpamrestack\fP
+    can be used to convert a normal rectangular image into one wide row or one
+    tall column if that is desirable for compression, conversion, or analysis.
+
+.IP \(bu
+
+    \fBpamrestack\fP can repair images corrupted by an incorrect width value
+    in the header.  Images grabbed from the framebuffer device often exhibit
+    this problem.
+
+.IP \(bu
+\fBpamrestack\fP can be used with \fBpamdice\fP, \fBpamundice\fP,
+    \fBpnmcat\fP, etc. to divide and combine images in the process of
+    interlacing.
+  
+
+
+.UN examples
+.SH EXAMPLES
+
+
+.IP \(bu
+Rearrange the one-dimensional output of \fBpamseq\fP into a square:
+
+.nf
+\f(CW
+pamseq 3 255 | pamrestack -width=4096
+\fP
+
+.fi
+
+.IP \(bu
+Combine two files, each 600 pixels wide, one with the odd rows and
+  another with the even rows, to construct an interlaced image:
+
+.nf
+\f(CW
+pnmcat -leftright oddrows.ppm evenrows.ppm | pamrestack -width=600
+\fP
+
+.fi
+
+
+.IP \(bu
+Like the above, but invert all pixels in the even rows left to right
+  to produce a serpentine interlace:
+
+.nf
+\f(CW
+  pamflip -leftright evenrows.ppm |
+    pnmcat -leftright oddrows.ppm - |
+      pamrestack -width 600
+\fP
+
+.fi
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamseq" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "pnmshear" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamdeinterlace" (1)\c
+\&,
+.BR "pamdice" (1)\c
+\&,
+.BR "pamundice" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamrestack\fP was new in Netpbm 10.99 (June 2022).
+
+
+.UN author
+.SH AUTHOR
+
+By Akira F. Urushibata.  Contributed to the public domain by the author.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamrestack.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamrgbatopng.1 b/upstream/mageia-cauldron/man1/pamrgbatopng.1
new file mode 100644
index 00000000..1b663b83
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamrgbatopng.1
@@ -0,0 +1,45 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamrgbtopng User Manual" 0 "28 June 2015" "netpbm documentation"
+
+.SH NAME
+
+pamrgbatopng - replaced by pamtopng
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamrgbatopng\fP
+[\fIpamfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamrgbatopng\fP was obsoleted by
+.BR "\fBpamtopng\fP" (1)\c
+\&, introduced with Netpbm 10.70
+(June 2015).  \fBpamtopng\fP is backward compatible with
+\fBpamrgbatopng\fP, plus adds a plethora additional functions.
+.PP
+Starting in Release 10.70, \fBpamrgbatopng\fP is just an alias for
+\fBpamtopng\fP.
+.PP
+\fBpamrgbatopng\fP was added to Netpbm in 2005, and was always expected to
+be retired eventually because it had almost no features, compared to the more
+popular and much older \fBpnmtopng\fP.  It had, in fact, no command line
+options.  But the one feature it had that \fBpnmtopng\fP lacked was the
+ability to recognize transparency in a PAM image.  \fBpamtopng\fP has that,
+as well as most of the features of \fBpnmtopng\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamrgbatopng.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamrubber.1 b/upstream/mageia-cauldron/man1/pamrubber.1
new file mode 100644
index 00000000..4e36695d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamrubber.1
@@ -0,0 +1,179 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamrubber User Manual" 0 "February 2011" "netpbm documentation"
+
+.SH NAME
+pamrubber - a rubber-sheeting utility that stretches an image
+based on control points
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamrubber\fP
+{\fB-tri | -quad\fP}
+[\fB-linear\fP]
+[\fB-frame\fP]
+[\fB-randomseed=\fP\fIN\fP]
+\fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
+\fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
+[\fIfilename\fP]
+.PP
+Minimum unique abbreviation of options is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+The \fBpamrubber\fP utility converts a pam image into a new image with the
+contents moved around.  The transformation is often called "rubber
+sheeting": you identify control points (CP) on the source image and
+specify new positions for those points in the new image.  \fBpamrubber\fP
+moves all the pixels around, stretching and compressing as necessary, as
+if the original image were on a sheet of rubber and you pulled on the sheet
+to make the control points move to their new locations.
+.PP
+The new image has the same dimensions and format as the original.
+.PP
+The transformation can happen in two very different ways, called
+"quad" and "tri." With the former, you must specify four
+control points (for both source and target).  These are the corners of two
+quadrilaterals that will act as the coordinate system for both source and
+target images.  Consider them as non-orthogonal (0,0), (0,1), (1,0) and (1,1)
+points.  This transformation comes close to the one \fBpamperspective\fP
+does, however that program does other corrections as well.
+.PP
+When you specify less than four control points, the program adds control
+points in the following way.  With three control points, \fBpamrubber\fP
+chooses the fourth one such that the four points form a parallelogram.  With
+two points, \fBpamrubber\fP considers them the opposite corners of a
+rectangle.  When you specify only one control point, \fBpamrubber\fP uses a
+rectangle from the top left corner of the image to the single control
+point.
+.PP
+In "tri" mode, \fBpamrubber\fP conceptually cuts up the source
+and target image into triangles.  It Transforms within each corresponding pair
+of triangles in a stretching fashion.  It's like pulling on the three corners
+of the triangle.  In this mode, each pixel in the source image gets mapped to
+a position in the target image. No pixels are lost.
+.PP
+When, in "tri" mode, you specify only a single control point in
+the source and target image, \fBpamrubber\fP creates four triangles from this
+point to the four corners of the image. With two points, the program creates
+six triangles from the two endpoints of the line connecting the two points,
+again to the four corners of the image. Three control points is in a way the
+core of this utility in "tri" mode.  Between the three edges of the
+central triangle and the four edges of the image, \fBpamrubber\fP constructs
+another seven triangles.  Four control points define two central connected
+triangles.  In total this results in cutting the source and target image up
+into ten triangles.
+.PP
+In this case clearly a picture says more than a thousand words.  There is a
+graphical illustration of these various modes at
+.UR http://www.schaik.com/netpbm/rubber
+ www.schaik.com/netpbm/rubber
+.UE
+\&.  An example of how to use this type of
+rubber sheeting in cartography is in the article
+.UR http://www.isprs.org/proceedings/XXXVI/5-W1/papers/21.pdf
+ Visualizing the Landscape of Old-Time Tokyo
+.UE
+\&.
+
+
+.UN parameters
+.SH PARAMETERS
+.PP
+The parameters are control points (\fIcp\fP) in pairs of \fIx\fP
+and \fIy\fP.  The source and target image must have the same number of
+control points.  The minimum number of values specified here is 4 for a single
+control point in the source and target image.  The maximum is 16 for four
+control points in each image.
+.PP
+\fIfilename\fP is the name of the input file. If you don't specify
+this, \fBpamrubber\fP reads the image from Standard Input.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamrubber\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-tri\fP | \fB-quad\fP
+.sp
+This selects the type of rubber sheeting done.
+You must specify exactly one of these options.
+
+
+.TP
+\fB-linear\fP
+.sp
+This determines whether \fBpamrubber\fP uses nearest neighbor
+interpolation or bilinear interpolation of four source pixels.
+
+
+
+.TP
+\fB-frame\fP
+.sp
+This option causes \fBpamrubber\fP to overlay the target image with the
+edges of the quadrilaterals, respectively the triangles used for the rubber
+sheeting.  To get the same overlay for the source image, use a \fBpamrubber\fP
+transformation with identical control points for source and target.
+
+
+.TP
+\fB-randomseed=\fP\fIN\fP
+.sp
+\fBpamrubber\fP randomizes some of its output.  So that you can produce
+repeatable results, you can choose the seed of the random number generator
+with this option.  If you use the same input image and the same random number
+generator seed, you should always get the exact same output.  By default,
+\fBpamrubber\fP uses the time of day as the seed, so you get slightly
+different output when you run the program twice on the same input.
+.sp
+Before Netpbm 10.61 (December 2012), this was called \fB-randseed\fP,
+and that still works.
+
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\& and
+.BR "pamperspective" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamrubber\fP was new in Netpbm 10.54 (March 2011).
+
+
+.UN authors
+.SH AUTHORS
+.PP
+\fIWillem van Schaik\fP wrote this program
+in February 2011 and contributed it to Netpbm.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamrubber.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamscale.1 b/upstream/mageia-cauldron/man1/pamscale.1
new file mode 100644
index 00000000..86a64130
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamscale.1
@@ -0,0 +1,770 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamscale User Manual" 0 "29 June 2020" "netpbm documentation"
+
+.SH NAME
+
+pamscale - scale a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+.nf
+   \fBpamscale\fP
+      [ 
+         \fIscale_factor\fP 
+         |
+         {\fB-xyfit\fP | \fB-xyfill\fP | \fB-xysize\fP}
+           \fIcols\fP \fIrows\fP 
+         |
+         \fB-reduce\fP \fIreduction_factor\fP 
+         |
+         [\fB-xsize=\fP\fIcols\fP | \fB-width=\fP\fIcols\fP | \fB-xscale=\fP\fIfactor\fP]
+         [\fB-ysize=\fP\fIrows\fP | \fB-height=\fP\fIrows\fP | \fB-yscale=\fP\fIfactor\fP]
+         |
+         \fB-pixels\fP \fIn\fP
+      ]
+      [
+         \fB-nomix\fP 
+         |
+         \fB-filter=\fP\fIfunctionName\fP [\fB-window=\fPfunctionName]
+      ]
+      [\fB-linear\fP]
+      [\fB-reportonly\fP]
+      [\fB-verbose\fP]
+
+      [\fIpnmfile\fP]
+
+
+.fi
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamscale\fP scales a Netpbm image by a specified factor, or
+scales individually horizontally and vertically by specified factors.
+.PP
+You can either enlarge (scale factor > 1) or reduce (scale factor
+< 1).
+.PP
+\fBpamscale\fP works on multi-image streams, scaling each one
+independently.  But before Netpbm 10.49 (December 2009), it scales only the
+first image and ignores the rest of the stream.
+
+.UN scalefactor
+.SS The Scale Factors
+.PP
+The options \fB-width\fP, \fB-height\fP, \fB-xsize\fP, \fB-ysize\fP,
+\fB-xscale\fP, \fB-yscale\fP, \fB-xyfit\fP, \fB-xyfill\fP, \fB-reduce\fP,
+and \fB-pixels\fP control the amount of scaling.  For backward compatibility,
+there are also \fB-xysize\fP and the \fIscale_factor\fP argument, but you
+shouldn't use those.
+.PP
+\fB-width\fP and \fB-height\fP specify the width and height in pixels
+you want the resulting image to be.  See below for rules when you specify
+one and not the other.
+.PP
+\fB-xsize\fP and \fB-ysize\fP are synonyms for \fB-width\fP and
+\fB-height\fP, respectively.
+.PP
+\fB-xscale\fP and \fB-yscale\fP tell the factor by which you want the
+width and height of the image to change from source to result (e.g.
+\fB-xscale 2\fP means you want to double the width; \fB-xscale .5\fP
+means you want to halve it).  See below for rules when you specify one and
+not the other.
+.PP
+When you specify an absolute size or scale factor for both
+dimensions, \fBpamscale\fP scales each dimension independently
+without consideration of the aspect ratio.
+.PP
+If you specify one dimension as a pixel size and don't specify the
+other dimension, \fBpamscale\fP scales the unspecified dimension to
+preserve the aspect ratio.
+.PP
+If you specify one dimension as a scale factor and don't specify
+the other dimension, \fBpamscale\fP leaves the unspecified dimension
+unchanged from the input.
+.PP
+If you specify the \fIscale_factor\fP parameter instead of
+dimension options, that is the scale factor for both dimensions.  It
+is equivalent to \fB-xscale=\fP\fIscale_factor\fP\fB
+-yscale=\fP\fIscale_factor\fP.
+.PP
+Specifying the \fB-reduce\fP \fIreduction_factor\fP option is
+equivalent to specifying the \fIscale_factor \fP parameter, where
+\fIscale_factor\fP is the reciprocal of \fIreduction_factor\fP.
+.PP
+\fB-xyfit\fP specifies a bounding box.  \fBpamscale\fP scales
+the input image to the largest size that fits within the box, while
+preserving its aspect ratio.  \fB-xysize\fP is a synonym for this.
+Before Netpbm 10.20 (January 2004), \fB-xyfit\fP did not exist, but
+\fB-xysize\fP did.
+.PP
+\fB-xyfill\fP is similar, but \fBpamscale\fP scales the input image
+to the smallest size that completely fills the box, while preserving
+its aspect ratio.  This option has existed since Netpbm 10.20 (January
+2004).
+.PP
+\fB-pixels\fP specifies a maximum total number of output pixels.
+\fBpamscale\fP scales the image down to that number of pixels.  If
+the input image is already no more than that many pixels,
+\fBpamscale\fP just copies it as output; \fBpamscale\fP does not
+scale up with \fB-pixels\fP.
+.PP
+If you enlarge by a factor of 3 or more, you should probably add a
+\fIpnmsmooth\fP step; otherwise, you can see the original pixels in
+the resulting image.
+
+.UN reportonly
+.B \fB-reportonly\fP
+.PP
+The option \fB-reportonly\fP causes \fBpamscale\fP not to scale the
+image, but instead to report to Standard Output what scaling the options and
+the input image dimensions indicate.  For example, if you specify
+.nf
+\f(CW    -xyfill 100 100 -reportonly \fP
+
+.fi
+and the input image is 500 x 400, \fBpamscale\fP tells you that this means
+scaling by .25 to end up with a 125 x 100 image.
+.PP
+You can use this information with other programs, such as
+\fBpamscalefixed\fP, that don't have as rich facilities as \fBpamscale\fP
+for choosing scale factors.
+.PP
+The output is intended to be convenient for machine processing.  In the
+example above, it would be
+
+.nf
+
+    500 400 0.250000 0.250000 125 100
+
+
+.fi
+.PP
+The output is a single line of text per input image, with blank-separated
+tokens as follows.
+
+
+.IP \(bu
+input width in pixels, decimal unsigned integer
+.IP \(bu
+input height in pixels, decimal unsigned integer
+.IP \(bu
+horizontal scale factor, floating point decimal, unsigned
+.IP \(bu
+vertical scale factor, floating point decimal, unsigned
+.IP \(bu
+output width in pixels, decimal unsigned integer
+.IP \(bu
+output height in pixels, decimal unsigned integer
+
+.PP
+\fB-reportonly\fP was new in Netpbm 10.86 (March 2019).
+
+
+.UN usage
+.SS Usage Notes
+.PP
+A useful application of \fBpamscale\fP is to blur an image.  Scale
+it down (without \fB-nomix\fP) to discard some information, then
+scale it back up using \fBpamstretch\fP.
+.PP
+Or scale it back up with \fBpamscale\fP and create a "pixelized" image,
+which is sort of a computer-age version of blurring.
+
+
+.UN transparency
+.SS Transparency
+.PP
+\fBpamscale\fP understands transparency and properly mixes pixels
+considering the pixels' transparency.  
+.PP
+Proper mixing \fIdoes not\fP mean just mixing the transparency
+value and the color component values separately.  In a PAM image, a
+pixel which is not opaque represents a color that contains light of
+the foreground color indicated explicitly in the PAM and light of a
+background color to be named later.  But the numerical scale of a
+color component sample in a PAM is as if the pixel is opaque.  So a
+pixel that is supposed to contain half-strength red light for the
+foreground plus some light from the background has a red color sample
+that says \fIfull\fP red and a transparency sample that says 50%
+opaque.  In order to mix pixels, you have to first convert the color
+sample values to numbers that represent amount of light directly
+(i.e. multiply by the opaqueness) and after mixing, convert back
+(divide by the opaqueness).
+
+.UN imagetype
+.SS Input And Output Image Types
+.PP
+\fBpamscale\fP produces output of the same type (and tuple type if
+the type is PAM) as the input, except if the input is PBM.  In that
+case, the output is PGM with maxval 255.  The purpose of this is to
+allow meaningful pixel mixing.  Note that there is no equivalent
+exception when the input is PAM.  If the PAM input tuple type is
+BLACKANDWHITE, the PAM output tuple type is also BLACKANDWHITE, and
+you get no meaningful pixel mixing.
+.PP
+If you want PBM output with PBM input, use \fBpamditherbw\fP to
+convert \fBpamscale\fP's output to PBM.  Also consider
+\fBpbmreduce\fP.
+.PP
+\fBpamscale\fP's function is essentially undefined for PAM input
+images that are not of tuple type RGB, GRAYSCALE, BLACKANDWHITE, or
+the _ALPHA variations of those.  (By standard Netpbm backward compatibility,
+this includes PBM, PGM, and PPM images).
+.PP
+You might think it would have an obvious effect on other tuple
+types, but remember that the aforementioned tuple types have
+gamma-adjusted sample values, and \fBpamscale\fP uses that fact in
+its calculations.  And it treats a transparency plane different from any
+other plane.
+.PP
+\fBpamscale\fP does not simply reject unrecognized tuple types
+because there's a possibility that just by coincidence you can get
+useful function out of it with some other tuple type and the right
+combination of options (consider \fB-linear\fP in particular).
+
+
+.UN methods
+.SS Methods Of Scaling
+.PP
+There are numerous ways to scale an image.  \fBpamscale\fP implements
+a bunch of them; you select among them with invocation options.
+
+.UN mixing
+.B Pixel Mixing
+.PP
+Pamscale's default method is pixel mixing.  To understand this, imagine the
+source image as composed of square tiles.  Each tile is a pixel and has
+uniform color.  The tiles are all the same size.  Now take a transparent sheet
+the size of the target image, marked with a square grid of tiles the same
+size.  Stretch or compress the source image to the size of the sheet and lay
+the sheet over the source.
+.PP
+Each cell in the overlay grid stands for a pixel of the target
+image.  For example, if you are scaling a 100x200 image up by 1.5, the
+source image is 100 x 200 tiles, and the transparent sheet is marked
+off in 150 x 300 cells.
+.PP
+Each cell covers parts of multiple tiles.  To make the target image,
+just color in each cell with the color which is the average of the colors
+the cell covers -- weighted by the amount of that color it covers.  A
+cell in our example might cover 4/9 of a blue tile, 2/9 of a red tile,
+2/9 of a green tile, and 1/9 of a white tile.  So the target pixel
+would be somewhat unsaturated blue.
+.PP
+When you are scaling up or down by an integer, the results are
+simple.  When scaling up, pixels get duplicated.  When scaling down,
+pixels get thrown away.  In either case, the colors in the target
+image are a subset of those in the source image.
+.PP
+When the scale factor is weirder than that, the target image can
+have colors that didn't exist in the original.  For example, a red
+pixel next to a white pixel in the source might become a red pixel,
+a pink pixel, and a white pixel in the target.
+.PP
+This method tends to replicate what the human eye does as it moves
+closer to or further away from an image.  It also tends to replicate
+what the human eye sees, when far enough away to make the pixelization
+disappear, if an image is not made of pixels and simply stretches
+or shrinks.
+
+.UN sampling
+.B Discrete Sampling
+.PP
+Discrete sampling is basically the same thing as pixel mixing except
+that, in the model described above, instead of averaging the colors of
+the tiles the cell covers, you pick the one color that covers the most
+area.
+.PP
+The result you see is that when you enlarge an image, pixels
+get duplicated and when you reduce an image, some pixels get discarded.
+.PP
+The advantage of this is that you end up with an image made from the
+same color palette as the original.  Sometimes that's important.
+.PP
+The disadvantage is that it distorts the picture.  If you scale up
+by 1.5 horizontally, for example, the even numbered input pixels are
+doubled in the output and the odd numbered ones are copied singly.  If
+you have a bunch of one pixel wide lines in the source, you may find
+that some of them stretch to 2 pixels, others remain 1 pixel when you
+enlarge.  When you reduce, you may find that some of the lines
+disappear completely.
+.PP
+You select discrete sampling with \fBpamscale\fP's \fB-nomix\fP
+option.
+.PP
+Actually, \fB-nomix\fP doesn't do exactly what I described above.
+It does the scaling in two passes - first horizontal, then vertical.
+This can produce slightly different results.
+.PP
+There is one common case in which one often finds it burdensome to
+have \fBpamscale\fP make up colors that weren't there originally:
+Where one is working with an image format such as GIF that has a
+limited number of possible colors per image.  If you take a GIF with
+256 colors, convert it to PPM, scale by .625, and convert back to GIF,
+you will probably find that the reduced image has way more than 256
+colors, and therefore cannot be converted to GIF.  One way to solve
+this problem is to do the reduction with discrete sampling instead of
+pixel mixing.  Probably a better way is to do the pixel mixing, but
+then color quantize the result with \fBpnmquant\fP before converting
+to GIF.
+.PP
+When the scale factor is an integer (which means you're scaling
+up), discrete sampling and pixel mixing are identical -- output pixels
+are always just N copies of the input pixels.  In this case, though,
+consider using \fBpamstretch\fP instead of \fBpamscale\fP to get the
+added pixels interpolated instead of just copied and thereby get a
+smoother enlargement.
+.PP
+\fBpamscale\fP's discrete sampling is faster than pixel mixing,
+but \fBpamenlarge\fP is faster still.  \fBpamenlarge\fP works only
+on integer enlargements.
+.PP
+discrete sampling (\fB-nomix\fP) was new in Netpbm 9.24 (January 2002).
+
+
+.UN resampling
+.B Resampling
+.PP
+Resampling assumes that the source image is a discrete sampling of some
+original continuous image.  That is, it assumes there is some non-pixelized
+original image and each pixel of the source image is simply the color of
+that image at a particular point.  Those points, naturally, are the
+intersections of a square grid.
+.PP
+The idea of resampling is just to compute that original image, then
+sample it at a different frequency (a grid of a different scale).
+.PP
+The problem, of course, is that sampling necessarily throws away the
+information you need to rebuild the original image.  So we have to make
+a bunch of assumptions about the makeup of the original image.
+.PP
+You tell \fBpamscale\fP to use the resampling method by specifying
+the \fB-filter\fP option.  The value of this option is the name of a
+function, from the set listed below.
+.PP
+\fBTo explain resampling, we are going to talk about a simple
+one dimensional scaling\fP -- scaling a single row of grayscale
+pixels horizontally.  If you can understand that, you can easily
+understand how to do a whole image: Scale each of the rows of the
+image, then scale each of the resulting columns.  And scale each of the
+color component planes separately.
+.PP
+As a first step in resampling, \fBpamscale\fP converts the source
+image, which is a set of discrete pixel values, into a continuous step
+function.  A step function is a function whose graph is a staircase-y
+thing.
+.PP
+Now, we convolve the step function with a proper scaling of the
+filter function that you identified with \fB-filter\fP.  If you don't
+know what the mathematical concept of convolution (convolving) is, you
+are officially lost.  You cannot understand this explanation.  The
+result of this convolution is the imaginary original continuous image
+we've been talking about.
+.PP
+Finally, we make target pixels by picking values from that function.
+.PP
+To understand what is going on, we use Fourier analysis:
+.PP
+The idea is that the only difference between our step function and
+the original continuous function (remember that we constructed the
+step function from the source image, which is itself a sampling of the
+original continuous function) is that the step function has a bunch of
+high frequency Fourier components added.  If we could chop out all the
+higher frequency components of the step function, and know that
+they're all higher than any frequency in the original function, we'd
+have the original function back.  
+.PP
+The resampling method \fIassumes\fP that the original function
+was sampled at a high enough frequency to form a perfect sampling.  A
+perfect sampling is one from which you can recover exactly the
+original continuous function.  The Nyquist theorem says that as long
+as your sample rate is at least twice the highest frequency in your
+original function, the sampling is perfect.  So we \fIassume\fP
+that the image is a sampling of something whose highest frequency is
+half the sample rate (pixel resolution) or less.  Given that, our
+filtering does in fact recover the original continuous image from the
+samples (pixels).
+.PP
+To chop out all the components above a certain frequency, we just
+multiply the Fourier transform of the step function by a rectangle
+function.
+.PP
+We could find the Fourier transform of the step function, multiply
+it by a rectangle function, and then Fourier transform the result
+back, but there's an easier way.  Mathematicians tell us that
+multiplying in the frequency domain is equivalent to convolving in the
+time domain.  That means multiplying the Fourier transform of F by a
+rectangle function R is the same as convolving F with the Fourier
+transform of R.  It's a lot better to take the Fourier transform of
+R, and build it into \fBpamscale\fP than to have \fBpamscale\fP
+take the Fourier transform of the input image dynamically.
+.PP
+That leaves only one question:  What \fIis\fP the Fourier
+transform of a rectangle function?  Answer: sinc.  Recall from
+math that sinc is defined as sinc(x) = sin(PI*x)/PI*x.
+.PP
+Hence, when you specify \fB-filter=sinc\fP, you are effectively
+passing the step function of the source image through a low pass
+frequency filter and recovering a good approximation of the original
+continuous image.
+
+.B Refiltering
+.PP
+There's another twist: If you simply sample the reconstructed
+original continuous image at the new sample rate, and that new sample
+rate isn't at least twice the highest frequency in the original
+continuous image, you won't get a perfect sampling.  In fact, you'll
+get something with ugly aliasing in it.  Note that this can't be a
+problem when you're scaling up (increasing the sample rate), because
+the fact that the old sample rate was above the Nyquist level means so
+is the new one.  But when scaling down, it's a problem.  Obviously,
+you have to give up image quality when scaling down, but aliasing is
+not the best way to do it.  It's better just to remove high frequency
+components from the original continuous image before sampling, and
+then get a perfect sampling of that.
+.PP
+Therefore, \fBpamscale\fP filters out frequencies above half the
+new sample rate before picking the new samples.
+
+.B Approximations
+.PP
+Unfortunately, \fBpamscale\fP doesn't do the convolution
+precisely.  Instead of evaluating the filter function at every point,
+it samples it -- assumes that it doesn't change any more often than
+the step function does.  \fBpamscale\fP could actually do the true
+integration fairly easily.  Since the filter functions are built into
+the program, the integrals of them could be too.  Maybe someday it
+will.
+.PP
+There is one more complication with the Fourier analysis.  sinc
+has nonzero values on out to infinity and minus infinity.  That makes
+it hard to compute a convolution with it.  So instead, there are
+filter functions that approximate sinc but are nonzero only within a
+manageable range.  To get those, you multiply the sinc function by a
+\fIwindow function\fP, which you select with the \fB-window\fP option.  The
+same holds for other filter functions that go on forever like sinc.  By
+default, for a filter that needs a window function, the window function is the
+Blackman function.  Hanning, Hamming, and Kaiser are alternatives.
+
+.B Filter Functions Besides Sinc
+.PP
+The math described above works only with sinc as the filter
+function.  \fBpamscale\fP offers many other filter functions, though.
+Some of these approximate sinc and are faster to compute.  For most of
+them, I have no idea of the mathematical explanation for them, but
+people do find they give pleasing results.  They may not be based on
+resampling at all, but just exploit the convolution that is
+coincidentally part of a resampling calculation.
+.PP
+For some filter functions, you can tell just by looking at the
+convolution how they vary the resampling process from the perfect one
+based on sinc:
+.PP
+The impulse filter assumes that the original continuous image is in
+fact a step function -- the very one we computed as the first step in
+the resampling.  This is mathematically equivalent to the discrete
+sampling method.
+.PP
+The box (rectangle) filter assumes the original image is a
+piecewise linear function.  Its graph just looks like straight lines
+connecting the pixel values.  This is mathematically equivalent to the
+pixel mixing method (but mixing brightness, not light intensity, so
+like \fBpamscale -linear\fP) when scaling down, and interpolation
+(ala \fBpamstretch\fP) when scaling up.
+
+.B Gamma
+.PP
+\fBpamscale\fP assumes the underlying continuous function is a
+function of brightness (as opposed to light intensity), and therefore
+does all this math using the gamma-adjusted numbers found in a PNM or
+PAM image.  The \fB-linear\fP option is not available with resampling
+(it causes \fBpamscale\fP to fail), because it wouldn't be useful enough
+to justify the implementation effort.
+.PP
+Resampling (\fB-filter\fP) was new in Netpbm 10.20 (January 2004).
+
+.B The filter and window functions
+.PP
+Here is a list of the function names you can specify for the
+\fB-filter\fP or \fB-window\fPoption.  For most of them, you're on your own
+to figure out just what the function is and what kind of scaling it does.
+These are common functions from mathematics.  Note that some of these make
+sense only as filter functions and some make sense only as window funcions.
+
+
+.TP
+point
+The graph of this is a single point at X=0, Y=1.
+
+.TP
+box
+The graph of this is a rectangle sitting on the X axis and centered
+on the Y axis with height 1 and base 1.
+
+.TP
+triangle
+The graph of this is an isosceles triangle sitting on the X axis
+and centered on the Y axis with height 1 and base 2.
+
+.TP
+quadratic
+.TP
+cubic
+.TP
+catrom
+.TP
+mitchell
+.TP
+gauss
+.TP
+sinc
+.TP
+bessel
+.TP
+hanning
+.TP
+hamming
+.TP
+blackman
+.TP
+kaiser
+.TP
+normal
+.TP
+hermite
+.TP
+lanczos
+Not documented
+
+
+
+.UN linear
+.SS Linear vs Gamma-adjusted
+.PP
+The pixel mixing scaling method described above involves intensities
+of pixels (more precisely, it involves individual intensities of
+primary color components of pixels).  But the PNM and PNM-equivalent
+PAM image formats represent intensities with gamma-adjusted numbers
+that are not linearly proportional to intensity.  So \fBpamscale\fP,
+by default, performs a calculation on each sample read from its input
+and each sample written to its output to convert between these
+gamma-adjusted numbers and internal intensity-proportional numbers.
+.PP
+Sometimes you are not working with true PNM or PAM images, but
+rather a variation in which the sample values are in fact directly
+proportional to intensity.  If so, use the \fB-linear\fP option to
+tell \fBpamscale\fP this.  \fBpamscale\fP then will skip the
+conversions.
+.PP
+The conversion takes time.  In one experiment, it increased by a factor of
+10 the time required to reduce an image.  And the difference between
+intensity-proportional values and gamma-adjusted values may be small enough
+that you would barely see a difference in the result if you just pretended
+that the gamma-adjusted values were in fact intensity-proportional.  So just
+to save time, at the expense of some image quality, you can specify
+\fB-linear\fP even when you have true PPM input and expect true PPM output.
+.PP
+For the first 13 years of Netpbm's life, until Netpbm 10.20
+(January 2004), \fBpamscale\fP's predecessor \fBpnmscale\fP always
+treated the PPM samples as intensity-proportional even though they
+were not, and drew few complaints.  So using \fB-linear\fP as a lie
+is a reasonable thing to do if speed is important to you.  But if
+speed is important, you also should consider the \fB-nomix\fP option
+and \fBpnmscalefixed\fP.
+.PP
+Another technique to consider is to convert your PNM image to the
+linear variation with \fBpnmgamma\fP, run \fBpamscale\fP on it and
+other transformations that like linear PNM, and then convert it back
+to true PNM with \fBpnmgamma -ungamma\fP.  \fBpnmgamma\fP is often
+faster than \fBpamscale\fP in doing the conversion.
+.PP
+With \fB-nomix\fP, \fB-linear\fP has no effect.  That's because
+\fBpamscale\fP does not concern itself with the meaning of the sample
+values in this method; \fBpamscale\fP just copies numbers from its
+input to its output.
+
+
+.UN precision
+.SS Precision
+.PP
+\fBpamscale\fP uses floating point arithmetic internally.  There
+is a speed cost associated with this.  For some images, you can get
+the acceptable results (in fact, sometimes identical results) faster
+with \fBpnmscalefixed\fP, which uses fixed point arithmetic.
+\fBpnmscalefixed\fP may, however, distort your image a little.  See
+the \fBpnmscalefixed\fP user manual for a complete discussion of the
+difference.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamscale\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-width\fP
+.TP
+\fB-height\fP
+.TP
+\fB-xsize\fP
+.TP
+\fB-ysize\fP
+.TP
+\fB-xscale\fP
+.TP
+\fB-yscale\fP
+.TP
+\fB-xyfit\fP
+.TP
+\fB-xyfill\fP
+.TP
+\fB-reduce\fP
+.TP
+\fB-pixels\fP
+.TP
+\fB-xysize\fP
+  These options determine the horizontal and vertical scale factors.
+.sp
+  See 
+.UR #scalefactor
+The Scale Factors
+.UE
+\&.
+
+.TP
+\fB-reportonly\fP
+  This causes \fBpamscale\fP not to scale the image, but instead to
+  report to Standard Output what scaling the options and the input image
+  dimensions indicate.
+.sp
+  See 
+.UR #reportonly
+-reportonly
+.UE
+\&.
+  
+.TP
+\fB-nomix\fP
+  This option selects 
+.UR #sampling
+discrete sampling
+.UE
+\& as the
+  
+.UR #methods
+method of scaling
+.UE
+\&.
+
+.TP
+\fB-filter=\fP\fIfunctionName\fP
+  This option selects 
+.UR #resampling
+resampling
+.UE
+\& as the
+  
+.UR #methods
+method of scaling
+.UE
+\&.
+
+.TP
+\fB-window=\fP\fIfunctionName\fP
+  This option selects a window function to modify the filter function
+  specified with \fB-filter\fP.
+.sp
+See 
+.UR #resampling
+Resampling
+.UE
+\&.
+
+.TP
+\fB-verbose\fP
+  This option causes \fBpamscale\fP to issue messages to Standard Error about
+  the scaling.
+  
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmscalefixed" (1)\c
+\&,
+.BR "pamstretch" (1)\c
+\&,
+.BR "pamstretch-gen" (1)\c
+\&,
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pbmpscale" (1)\c
+\&,
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnmscale" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamscale\fP was new in Netpbm 10.20 (January 2004).  It was
+adapted from, and obsoleted, \fBpnmscale\fP.  \fBpamscale\fP's
+primary difference from \fBpnmscale\fP is that it handles the PAM
+format and uses the "pam" facilities of the Netpbm programming
+library.  But it also added the resampling class of scaling method.
+Furthermore, it properly does its pixel mixing arithmetic (by default)
+using intensity-proportional values instead of the gamma-adjusted
+values the \fBpnmscale\fP uses.  To get the old \fBpnmscale\fP
+arithmetic, you can specify the \fB-linear\fP option.
+.PP
+The intensity proportional stuff came out of suggestions by \fIAdam M Costello\fP in January
+2004.
+.PP
+The resampling algorithms are mostly taken from code contributed by
+\fIMichael Reinelt\fP in December 2003.
+.PP
+The version of \fBpnmscale\fP from which \fBpamscale\fP was
+derived, itself evolved out of the original Pbmplus version of
+\fBpnmscale\fP by Jef Poskanzer (1989, 1991).  But none of that
+original code remains.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamscale.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamseq.1 b/upstream/mageia-cauldron/man1/pamseq.1
new file mode 100644
index 00000000..85069715
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamseq.1
@@ -0,0 +1,239 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamseq User Manual" 0 "30 April 2022" "netpbm documentation"
+
+
+.SH NAME
+
+pamseq - generate PAM image of a numerical sequence of tuple values
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamseq\fP
+[\fB-tupletype=\fP\fItupletype\fP]
+\fIdepth\fP
+\fImaxval\fP
+[\fB-min=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...]
+[\fB-max=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...]
+[\fB-step=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and its
+value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamseq\fP generates a PAM image of a specified depth and specified
+  maxval that consists of a single row.  The row consists of tuples
+  containing sample values in a numerical sequence.
+.PP
+For example
+
+.nf
+\f(CW
+    pamseq 1 4
+\fP
+
+.fi
+
+  generates a 5 pixel wide image of 1 row with depth 1 tuples containing these
+  samples, in order from left to right:
+
+.nf
+    0 1 2 3 4
+
+.fi
+
+  The following example uses depth 2:
+
+.nf
+\f(CW
+    pamseq 2 2
+\fP
+
+.fi
+
+  The resulting image is a 9 pixel wide image of 1 row with depth 2 containing
+  these samples, in order from left to right;
+
+.nf
+    (0,0) (0,1) (0,2) (1,0) (1,1) (1,2) (2,0) (2,1) 2,2)
+
+.fi
+.PP
+  You can choose the starting and ending sample values and the step for each
+  plane:  Here is an example of that:
+
+.nf
+\f(CW
+    pamseq 1 255 -min=4 -max=8 -step=2
+\fP
+
+.fi
+
+This generates
+
+.nf
+    4 6 8
+
+.fi
+
+In two dimensions:
+
+.nf
+\f(CW
+    pamseq 2 255 -min=0,4 -max=2,8 -step=1,2
+\fP
+
+.fi
+
+.nf
+    (0,4) (0,6) (0,8) (1,4) (1,6) (1,8) (2,4) (2,6) (2,8)
+
+.fi
+.PP
+  \fBpamseq\fP varies first the highest numbered plane, then the next lower
+  numbered plane, etc.  Within each plane, the program varies from low sample
+  value to high.
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamseq\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-tupletype\fP
+This is the value of the "tuple_type" attribute of the created PAM image.
+It can be any string up to 255 characters.
+
+.TP
+\fB-min=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...
+  This gives the starting value for the sequence in each plane.  The number
+  of comma-separated numbers must be equal to the number of planes in the
+  image (its depth).  Each number must be a whole number no greater than
+  the maxval of the image.  The first number is for Plane 0, the second for
+  Plane 1, etc.
+.sp
+The default is 0 in every plane.
+.sp
+This option was new in Netpbm 10.99 (June 2022).
+
+.TP
+\fB-max=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...
+.sp
+This is analogous to \fB-min\fP, giving the ending value for the
+    sequence.
+.sp
+Each value must be at least as great as the corresponding \fB-min\fP
+    value.
+.sp
+The default is the maxval in every plane.
+.sp
+This option was new in Netpbm 10.99 (June 2022).
+
+.TP
+\fB-step=\fP\fIn\fP\fB,\fP\fIn\fP\fB,\fP...
+.sp
+This is analogous to \fB-min\fP, giving the step value for the
+    sequence (difference between two consecutive numbers).
+.sp
+Each value must be positive and no greater than the maxval.
+.sp
+The default is 1.
+.sp
+This option was new in Netpbm 10.99 (June 2022).
+
+
+
+.UN usage
+.SH USAGE
+.PP
+To create a simple ramp of the values 0..255, for input to various matrix
+calculations, try
+.nf
+\f(CW
+  pamseq 1 255 
+\fP
+
+.fi
+(Before \fBpamseq\fP existed, \fBpgmramp\fP was often pressed into service
+for this).
+.PP
+To create a PPM color map of all the possible colors representable with a
+maxval of 5, do
+.nf
+\f(CW
+  pamseq 3 5 -tupletype=RGB | pamtopnm
+\fP
+
+.fi
+
+Again, with a modern program based on the Netpbm library, you don't need
+the \fBpamtopnm\fP because a PAM RGB image is equivalent to a PPM image.
+.PP
+You can use such a color map with
+.BR "pnmremap" (1)\c
+\& to quantize the colors in an
+image.  With the maxval of 5 given in the example, you get a color map
+of the set of "web safe" colors as defined by Netscape.  Most web
+browsers guarantee that they can produce at least these 216 colors
+(215 plus black).
+.PP
+\fBpamrestack\fP can often produce a useful two-dimensional image from
+\fBpamseq\fP's single row.
+
+.nf
+\f(CW
+    pamseq 2 255 -min=0,4 -max=2,8 -step=1,2 | pamrestack -width=3
+\fP
+
+.fi
+
+.nf
+    (0,4) (0,6) (0,8)
+    (1,4) (1,6) (1,8)
+    (2,4) (2,6) (2,8)
+
+.fi
+  
+
+  
+.UN seealso
+.SH SEE ALSO
+.BR "pnmremap" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pamrestack" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+
+\fBpamseq\fP was added to Netpbm in June 2002.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamseq.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamshadedrelief.1 b/upstream/mageia-cauldron/man1/pamshadedrelief.1
new file mode 100644
index 00000000..2952a6fd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamshadedrelief.1
@@ -0,0 +1,139 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamshadedrelief User Manual" 0 "26 July 2014" "netpbm documentation"
+
+.SH NAME
+
+pamshadedrelief - generate shaded relief image from an elevation map
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamshadedrelief\fP
+
+[\fB-gamma\fP \fIg\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamshadedrelief\fP creates a shaded relief image from an elevation map.
+A shaded relief image is a visual image of terrain, showing the terrain as if
+illuminated by oblique light and viewed from above, so that the brightess of
+each spot depends upon its slope.  A common example of a shaded relief image
+is a relief map of the Earth, which shows mountains and valleys.
+.PP
+The image \fBpamshadedrelief\fP creates is as if illumated by a light
+source from the left.
+.PP
+The output image is a PAM with tuple type \fBGRAYSCALE\fP.
+.PP
+The program \fBpamcrater\fP is a good thing to use to demonstrate the
+function of \fBpamshadedrelief\fP.  It generates a terrain map of a cratered
+landscape.
+
+.nf
+\f(CW
+    $ pamcrater | pamshadedrelief | pamx
+\fP  
+
+.fi
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamshadedrelief\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-gamma\fP \fIfactor\fP
+.TP
+\fB-g\fP \fIfactor\fP
+The specified \fIfactor\fP is used to gamma adjust the image in
+the same manner as performed by \fBpnmgamma\fP.  The default value is
+1.0, which results in a medium contrast image.  Values larger than 1
+lighten the image and reduce contrast, while values less than 1 darken
+the image, increasing contrast.
+.sp
+Note that this is separate from the gamma correction that is part of the
+definition of the PAM GRAYSCALE format.  The image \fBpamshadedrelief\fP
+generates is a genuine, gamma-corrected PAM GRAYSCALE image in any case.  This
+option simply changes the contrast and may compensate for a display device
+that does not correctly render PAM GRAYSCALE images.
+
+
+
+.UN designnotes
+.SH DESIGN NOTES
+
+The\fB-gamma\fP option isn't really necessary since you can achieve
+the same effect by piping the output from \fBpamshadedrelief\fP through
+\fBpnmgamma\fP.  However, \fBpamshadedrelief\fP performs an internal gamma
+map anyway in the process of rendering the elevation array into the PAM
+GRAYSCALE format, so there's no additional overhead in allowing an additional
+gamma adjustment.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmrelief" (1)\c
+\&
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&
+.BR "pamcrater" (1)\c
+\&
+.BR "pam" (1)\c
+\&,
+
+
+.UN author
+.SH AUTHOR
+.PP
+\fBpgmcrater\fP, from which this is derived, was written by John Walker:
+
+.nf
+John Walker
+Autodesk SA
+Avenue des Champs-Montants 14b
+CH-2074 MARIN
+Suisse/Schweiz/Svizzera/Svizra/Switzerland
+    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
+    \fBFax:\fP038/33 88 15
+    \fBVoice:\fP038/33 76 33
+
+.fi
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided
+"as is" without express or implied warranty.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpgmcrater\fP was split into \fBpamshadedrelief\fP and \fBpamcrater\fP
+in Netpbm 10.68 (September 2014).  See the history section of the
+\fBpamcrater\fP manual for details.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamshadedrelief.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsharpmap.1 b/upstream/mageia-cauldron/man1/pamsharpmap.1
new file mode 100644
index 00000000..7523acf6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsharpmap.1
@@ -0,0 +1,85 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsharpmap User Manual" 0 "07 February 2004" "netpbm documentation"
+
+.SH NAME
+pamsharpmap - create map of sharpness in a PNM/PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamsharpmap\fP [\fIimagefile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsharpmap\fP reads a Netpbm image (PNM or PAM) and produces
+an image that shows how sharp it is at each location.
+.PP
+Sharpness is a measure of how suddenly (in space) colors change in
+the image.  \fBpamsharpmap\fP computes the sharpness of each
+component color (R, G, B) separately and produces a pixel whose
+intensity of each component color is directly proportional to the
+sharpness of that component color at the same location in the input
+image.  Thus, at a point where the image is very sharp in its red and
+green components, but dull in its blue component, you will see a
+yellow pixel in the output.
+.PP
+\fBpamsharpmap\fP computes sharpness at a point simply as the
+average difference in intensity between the pixel at that point and
+the 8 pixels surrounding it.
+.PP
+At the edges of the image, where there are not 8 pixels surrounding
+a pixel, \fBpamsharpmap\fP assumes the image is extended with a black
+border.
+.PP
+\fBpamsharpmap\fP assumes that the image is a PNM or PNM
+equivalent PAM.  If it isn't, the results are not necessarily
+meaningful.
+.PP
+The output image is the same dimensions, depth, and tuple type as
+the input, and has maxval 255.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamsharpmap\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamsharpness" (1)\c
+\&,
+.BR "pammasksharpen" (1)\c
+\&,
+.BR "pamedge" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamsharpmap\fP was added to Netpbm in Release 10.21 (March
+2004).  Bryan Henderson derived it from the program \fBpnmsharp\fP by
+B.W. van Schooten and distributed as part of the Photopnmtools
+package.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsharpmap.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsharpness.1 b/upstream/mageia-cauldron/man1/pamsharpness.1
new file mode 100644
index 00000000..64aa82e9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsharpness.1
@@ -0,0 +1,71 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsharpness User Manual" 0 "07 February 2004" "netpbm documentation"
+
+.SH NAME
+pamsharpness - measure the sharpness of a PNM/PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamsharpness\fP [\fIimagefile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsharpness\fP reads a Netpbm image (PNM or PAM) and prints a
+message to Standard Output giving a number that tells how sharp it is.
+.PP
+Sharpness is a measure of how suddenly (in space) colors change in
+the image.  \fBpamsharpness\fP computes the sharpness of the image as
+the average difference in intensity between each pixel and its 8 surrounding
+pixels, in each of the color components (R, G, B).
+.PP
+\fBpamsharpness\fP does not include the edges of the image, where
+there are not 8 pixels surrounding a pixel, in its computation.
+.PP
+\fBpamsharpness\fP assumes that the image is a PNM or PNM
+equivalent PAM.  If it isn't, the results are not necessarily
+meaningful.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamsharpness\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamsharpmap" (1)\c
+\&,
+.BR "pammasksharpen" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamsharpness\fP was added to Netpbm in Release 10.21 (March
+2004).  Bryan Henderson derived it from the program \fBpnmsharp\fP by
+B.W. van Schooten and distributed as part of the Photopnmtools
+package.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsharpness.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamshuffle.1 b/upstream/mageia-cauldron/man1/pamshuffle.1
new file mode 100644
index 00000000..7a502eaa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamshuffle.1
@@ -0,0 +1,179 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamshuffle User Manual" 0 "" "netpbm documentation"
+
+Updated:
+.SH NAME
+pamshuffle - Shuffle pixels of a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamshuffle\fP
+[\fB-column\fP
+[\fB-randomseed\fP \fIinteger\fP]]
+[\fIpamfile\fP]
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamshuffle\fP reads a Netpbm image as input and produces an output file
+with the pixels shuffled.  The operation only changes the location of existing
+pixels; nothing is discarded or added.
+.PP
+By default, pixels change location within rows independently, but it is
+also possible to perform the same shuffle on every row, meaning the program is
+shuffling vertical columns of pixels.  Either way, there is no vertical
+rearrangement; this means images consisting entirely of horizontal stripes,
+such as the national banners of Germany, Thailand and Ukraine, will be
+unchanged.
+.PP
+To shuffle vertically, or to perform a complete scramble, use
+\fBpamshuffle\fP together with \fBpamflip\fP.  See examples below.
+.PP
+Input is from Standard Input if you don't specify the input file
+\fIpamfile\fP.
+.PP
+Output is to Standard Output.
+.PP
+\fBpamshuffle\fP works on a multi-image stream.  It operates on
+each image in the stream independently and produces a multi-image
+stream output.
+.PP
+The shuffling algorithm is the widely known
+.UR https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+ Fisher-Yates method
+.UE
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamshuffle\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-column\fP
+Shuffle vertical columns, i.e. perform the same movement on all rows.
+Without this option, the program shuffles each row independently.
+
+.TP
+\fB-randomseed\fP= \fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpamshuffle\fP uses a seed derived from the time of day
+and process ID, which gives you quite uncorrelated results in multiple
+invocations.
+
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+In the following example, output is to Standard Output.  You will probably
+want to add redirection to somewhere useful.
+
+
+.IP \(bu
+
+.sp
+\fBpamshuffle\fP is useful when you want to randomize the orderly
+output of image generators such as \fBpamseq\fP and \fBpgmramp\fP.
+.sp
+Produce five permutations of integers 0 to 15:
+
+.nf
+\f(CW
+pgmramp -lr -maxval=15 16 5 | pamshuffle -plain
+\fP
+
+.fi
+
+.IP \(bu
+Shuffle columns:
+
+.nf
+\f(CW
+pamshuffle -column image.ppm
+\fP
+
+.fi
+
+
+.IP \(bu
+Shuffle rows:
+
+.nf
+\f(CW
+pamflip -cw image.ppm | pamshuffle | pamflip -ccw
+\fP
+
+.fi
+
+.IP \(bu
+Perform complete shuffle:
+
+.nf
+\f(CW
+pamflip -cw image.ppm | pamshuffle | pamflip -ccw | pamshuffle
+\fP
+
+.fi
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamseq" (1)\c
+\&,
+.BR "pgmramp" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "ppmshift" (1)\c
+\&,
+.BR "ppmspread" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamshuffle\fP was new in Netpbm 10.99 (June 2022).
+
+
+.UN author
+.SH AUTHOR
+
+By Akira F. Urushibata.  Contributed to the public domain by the author.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamshuffle.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsistoaglyph.1 b/upstream/mageia-cauldron/man1/pamsistoaglyph.1
new file mode 100644
index 00000000..68b5986e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsistoaglyph.1
@@ -0,0 +1,208 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsistoaglyph User Manual" 0 "05 April 2009" "netpbm documentation"
+
+.SH NAME
+
+pamsistoaglyph - convert a single-image stereogram to a red/cyan
+anaglyphic image
+
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpamsistoaglyph\fP
+[--\fBinvert\fP]
+[--\fBsep\fP=\fInumber\fP]
+[--\fBminsep\fP=\fInumber\fP]
+[--\fBgray\fP=\fInumber\fP]
+[\fIin_netpbmfile\fP
+.PP
+All options can be abbreviated to their shortest unique prefix. You
+may use either white space or an equals sign between an option name
+and its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsistoaglyph\fP reads a Netpbm image as input and
+produces a Netpbm image as output.
+.PP
+\fBpamsistoaglyph\fP takes a single-image stereogram
+(SIS) such as those produced by
+.BR "pamstereogram" (1)\c
+\&
+and converts it to a red/cyan anaglyphic image such as those produced
+by
+.BR "ppm3d" (1)\c
+\&.
+Many people have trouble tricking their eyes into focusing beyond the
+image in front of them and are therefore unable to perceive the 3-D
+shape hidden within a single-image stereogram.  Anaglyphic stereograms
+are easier to perceive in 3-D but require a pair of red/cyan glasses
+such as those often used to watch 3-D movies. The goal of
+\fBpamsistoaglyph\fP is to help people who have trouble
+viewing single-image stereograms see the intriguing 3-D effect.
+.PP
+\fBpamsistoaglyph\fP can convert single-image random-dot
+stereograms (SIRDS), wallpaper stereograms, and even dual-image
+stereograms to anaglyphic images.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamsistoaglyph\fP recognizes the following
+command line options:
+.PP
+For most images, no command-line options need to be specified.  The
+following options are available, however, for unusual circumstances.
+
+
+.TP
+\fB--invert\fP
+Swap the left- and right-eye
+    images. \fBpamsistoaglyph\fP assumes that its input
+    represents a wall-eyed stereogram and generates the anaglyphic
+    image accordingly. If the generated image appears to recede into
+    the page where it should pop out of the page (and vice versa),
+    this typically implies that the input image represents a
+    cross-eyed stereogram. Use \fB--invert\fP to correct
+    the image depth.
+
+.TP
+\fB--sep\fP=\fInumber\fP
+Specify the distance in pixels between the left- and right-eye
+    images. Essentially, this corresponds to the distance between
+    repetitions of the background pattern.  The \fB--sep\fP
+    option should rarely be necessary
+    as \fBpamsistoaglyph\fP is fairly good at determining
+    automatically the eye-separation distance.
+
+.TP
+\fB--minsep\fP=\fInumber\fP
+This option is similar to \fB--sep\fP but
+    constrains \fBpamsistoaglyph\fP only to
+    a \fIminimum\fP eye-separation distance. Any distance larger
+    than \fInumber\fP is acceptable.  The \fB--minsep\fP
+    option should rarely be necessary
+    as \fBpamsistoaglyph\fP is fairly good at determining
+    automatically the eye-separation distance.  The default value for
+    the minimum eye-separation distance is 10% of the image width;
+    this value seems to work well in practice.
+
+.TP
+\fB--gray\fP=\fInumber\fP
+Limit the number of gray levels to use when searching for the
+    optimal eye-separation
+    distance.  Because \fBpamsistoaglyph\fP looks for
+    repeated patterns, it is vulnerable to being confused by slight
+    variations in color.  By reducing the input image to grayscale and
+    capping the number of gray levels,
+    \fBpamsistoaglyph\fP ameliorates the effects of
+    unintentional color variations (such as those caused by conversion
+    from a low-quality JPEG image, for example). The default of 63
+    seems to work well so the \fB--gray\fP option should
+    rarely be necessary.
+
+
+
+.UN notes
+.SH NOTES
+.PP
+The registration algorithm used by \fBpamsistoaglyph\fP
+was developed specifically for this program. As far as the author
+knows, there are no existing algorithms for converting stereograms to
+anaglyphs.  The algorithm works as follows:
+
+
+.IP \(bu
+Convert the image to grayscale to increase the ability to identify
+    matches.
+
+.IP \(bu
+Count the number of pixels that match \fIN\fP pixels ahead in the
+    image for all \fIN\fP in [1, \fIwidth\fP/2].
+
+.IP \(bu
+Maintain a running mean (mu) and standard deviation (sigma) of
+    the number of matched pixels.
+
+.IP \(bu
+Store the \fIN\fP corresponding to each spike in the number of
+    matched pixels. A spike is defined as a tally that exceeds the
+    mean plus one, two, or three standard deviations. Only the first
+    spike of a given standard-deviation multiplier is stored.
+
+.IP \(bu
+If a tally greater than mu+3sigma was encountered, return the
+    corresponding \fIN\fP. If not, then if a tally greater than
+    mu+2sigma was encountered, return the
+    corresponding \fIN\fP. If not, then if a tally greater than
+    mu+sigma was encountered, return the
+    corresponding \fIN\fP. If not, then return the \fIN\fP that
+    produces the minimum average distance between matched pixels
+    (i.e.,\ \fI#matches\fP divided by \fI#pixels\fP). If no
+    such \fIN\fP exceeds the minimum allowable eye-separation value,
+    return zero to indicate failure.
+
+.IP \(bu
+If the algorithm returned zero, rerun the algorithm independently
+    on each row of the input image and return the median of
+    all \fIN\fP that exceed the minimum allowable eye-separation
+    value. If no such \fIN\fP exists, abort with an error
+    message.
+
+
+.UN history
+.SH HISTORY
+.PP
+Scott Pakin wrote \fBpamsistoaglyph\fP in April 2009.  It first appeared
+in Netpbm in Release 10.47 (June 2009).
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2009 Scott
+Pakin, \fIscott+pbm@pakin.org\fP
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+
+.IP \(bu
+
+.BR "pamstereogram" (1)\c
+\&
+.IP \(bu
+
+.BR "ppm3d" (1)\c
+\&,
+.IP \(bu
+
+.UR http://en.wikipedia.org/wiki/Stereogram
+http://en.wikipedia.org/wiki/Stereogram
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsistoaglyph.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamslice.1 b/upstream/mageia-cauldron/man1/pamslice.1
new file mode 100644
index 00000000..d76201e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamslice.1
@@ -0,0 +1,131 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamslice User Manual" 0 "08 February 2010" "netpbm documentation"
+
+.SH NAME
+pamslice - extract one line of values out of a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamslice\fP
+{\fB-row=\fP\fIrownumber\fP | \fB-column=\fP\fIcolumnnumber\fP}
+[\fB-plane=\fP\fIplanenumber\fP]
+[\fIimagefile\fP]
+
+.SH OPTION USAGE
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamslice\fP extracts one line of tuples (pixels) out of a
+Netpbm image and prints their values in a table.  A line means a row
+or column.  It shows you a one-dimensional cross section of a
+two-dimensional image.  (With the \fB-plane\fP option, it can be
+thought of as a one-dimensional cross-section of a three-dimensional
+image).
+.PP
+The table has one line per tuple, consisting of blank-separated
+ASCII decimal numbers.  The first number is the column number if you
+specified a row slice or the row number if you specified a column
+slice.  The rest of the numbers are the sample values in plane number
+order.  For a PBM or PGM input, there is only one plane.  For a PPM
+input, Plane 0 is red, Plane 1 is green, and Plane 2 is blue.  See the
+specifications of the image formats for details on exactly what these
+numbers mean.
+.PP
+If you want to see the entire raster of a Netpbm image, use
+\fBpamtable\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamslice\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-row=\fP\fIrownumber\fP
+     This indicates that the slice is to be horizontal -- i.e. one row of the
+     image -- and indicates which row.  Rows are numbered from the top
+     starting with 0.
+.sp
+You cannot specify both \fB-row\fP and \fB-column\fP.
+
+.TP
+\fB-column=\fP\fIcolnumber\fP
+     This indicates that the slice is to be vertical -- i.e. one column of the
+     image -- and indicates which column.  Columns are numbered from the left
+     starting with 0.
+.sp
+You cannot specify both \fB-row\fP and \fB-column\fP.
+
+.TP
+\fB-plane=\fP\fIplanenumber\fP
+     This specifies that you are interested in only one plane of the image
+     and which one.  Planes are numbered from 0 and have meanings that vary
+     on the type of image.  In a PPM image, Plane 0 is red, Plane 1 is
+     green, and Plane 2 is blue.
+.sp
+If you don't specify \fB-plane\fP, you get all the planes -- each
+     line of output has multiple numbers in addition to the sequence number.
+     If you do specify \fB-plane\fP, each line of output contains one
+     number in addition to the sequence number.
+
+.TP
+\fB-xmgr\fP
+     This option causes \fBpamslice\fP to format the output as input for a
+     \fBxmgr\fP so you can plot it.  The only difference this option makes
+     is that it adds header information to the beginning of the output.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtable" (1)\c
+\&
+.BR "pamcut" (1)\c
+\&
+.BR "pamtopnm" (1)\c
+\&
+.BR "pamchannel" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamslice\fP replaced \fBpgmslice\fP in Netpbm 10.3 (June 2002).
+It was backward compatible, but worked on Netpbm images other than PGM and
+PBM and added the \fB-plane\fP and \fB-xmgr\fP options.
+
+.UN author
+.SH AUTHOR
+.PP
+Jos Dingjan <\fIjos@tuatha.org\fP> wrote
+\fBpgmslice\fP after being unable to find the source code to Marco
+Beijersbergen's program with the same name.  Bryan Henderson converted it
+to \fBpamslice\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamslice.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsplit.1 b/upstream/mageia-cauldron/man1/pamsplit.1
new file mode 100644
index 00000000..be959348
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsplit.1
@@ -0,0 +1,116 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsplit User Manual" 0 "11 August 2011" "netpbm documentation"
+
+.SH NAME
+
+pamsplit - split a multi-image Netpbm file into single-image files
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamsplit\fP
+
+[\fInetpbmfile\fP
+
+[\fI output_file_pattern\fP]]
+
+[\fB-padname=\fP\fIn\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsplit\fP reads a PNM or PAM stream as input.  It copies each image
+in the input into a separate file, in the same format.
+.PP
+\fInetpbmfile\fP is the file name of the input file, or
+\fB-\fP to indicate Standard Input.  The default is Standard Input.
+.PP
+\fIoutput_file_pattern\fP tells how to name the output files.  It
+is the file name of the output file, except that the first
+occurrence of "%d" in it is replaced by the image sequence
+number in unpadded ASCII decimal, with the sequence starting at 0.  If
+there is no "%d" in the pattern, \fBpamsplit\fP fails.
+.PP
+The default output file pattern is "image%d".
+.PP
+The \fB-padname\fP option specifies how many characters you
+want the image sequence number in the output file name padded with
+zeroes.  \fBpamsplit\fP adds leading zeroes to the image sequence
+number to get up to at least that number of characters.  This is just
+the number of characters in the sequence number part of the name.  For
+example, \f(CWpamsplit - outputfile%d.ppm -padname=3\fP would yield
+output filenames \fBoutputfile000.ppm\fP, \fBoutputfile001.ppm\fP,
+etc.
+.PP
+Note that to do the reverse operation (combining multiple
+single-image Netpbm files into a multi-image one), there is no special
+Netpbm program.  Just use \fBcat\fP.
+.PP
+If you just want to find out basic information about the images in a
+stream, you can use \fBpamfile\fP on the stream.
+.PP
+To extract images from a stream and generate a single stream containing
+them, use \fBpampick\fP.
+.PP
+To run a program on each image in a stream without the hassle of temporary
+files, use \fBpamexec\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamsplit\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-padname=\fP\fIn\fP
+Specify the width (i.e. number of digits) of the image sequence
+number field in the filenames of the output files.  The image
+sequence will be padded with leading zeroes to achieve the stated
+width.
+.sp
+The default is no padding (equivalent to \fB-padname=0\fP).
+.sp
+The \fB-padname\fP option was new in Netpbm 10.23 (July 2004).
+Before that, there was never any padding.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&,
+.BR "pampick" (1)\c
+\&,
+.BR "pamexec" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+\fBcat\fP man page
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsplit.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamstack.1 b/upstream/mageia-cauldron/man1/pamstack.1
new file mode 100644
index 00000000..29b7cb2c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamstack.1
@@ -0,0 +1,118 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamstack User Manual" 0 "10 January 2006" "netpbm documentation"
+
+.SH NAME
+pamstack - stack planes of multiple PAM images into one PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamstack\fP
+[\fB-tupletype \fP\fItupletype\fP]
+[\fIinputfilespec\fP ...]
+.PP
+All options may be abbreviated to the shortest unique prefix.  You
+may use two hyphens instead of one.  You may separate an option from
+its value with a space instead of \fB=\fP.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamstack\fP reads multiple PAM or PNM images as input and
+produces a PAM image as output, consisting of all the planes
+(channels) of the inputs, stacked in the order specified.
+.PP
+It can also just change the tuple type of a single PAM image.
+  
+.PP
+For any one (but not more) of the input files, you may specify
+"-" to mean Standard Input.  If you specify no arguments at all,
+the input is one file: Standard Input.
+.PP
+The output is the same dimensions as the inputs, except that the
+depth is the sum of the depths of the inputs.  It has the same maxval.
+\fBpamstack\fP fails if the inputs are not all the same width, height,
+and maxval.  The tuple type is a null string unless you specify the
+\fB-tupletype\fP option.
+.PP
+\fBpamstack\fP works with multi-image streams.  It stacks the 1st
+image in all the streams into one output image (the first one in the
+output stream), then stacks the 2nd image in all the streams into the
+2nd image in the output stream, and so on, until one of the streams
+runs dry.  It's like a matrix operation.
+.PP
+Before Netpbm 10.32 (February 2006), \fBpamstack\fP ignored all but
+the first image in each input stream.
+.PP
+\fBpamchannel\fP does the opposite of \fBpamstack\fP:  It extracts
+individual planes from a single PAM.
+.PP
+Use
+.BR "pamtopnm" (1)\c
+\& to convert a suitable PAM
+image to a more traditional PNM (PBM, PGM, or PPM) image.  (But there's
+no need to do that if you're going to feed it to a modern Netpbm program --
+they all take suitable PAM input directly).
+.PP
+One example of using \fBpamstack\fP is that some Netpbm programs
+accept as input a PAM that represents graphic image with transparency
+information.  Taking a color image for example, this would be a PAM
+with tuple type "RGB_ALPHA".  In Netpbm, such images were
+traditionally represented as two images - a PPM for the color and a
+PGM for the transparency.  To convert a PPM/PGM pair into
+PAM(RGB_ALPHA) input that newer programs require, do something like
+this:
+
+.nf
+\f(CW
+$ pamstack -tupletype=RGB_ALPHA myimage.ppm myalpha.pgm | \e
+      pamtouil >myimage.uil
+\fP
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamstack\fP recognizes the following
+command line option:
+
+
+
+.TP
+\fB-tupletype \fP\fItupletype\fP
+This specifies the tuple type name to be recorded in the output.  You may
+use any string up to 255 characters.  Some programs recognize some names.
+If you omit this option, the default tuple type name is null.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+.BR "pamchannel" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamstack\fP was new in Netpbm 10.0 (June 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamstack.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamstereogram.1 b/upstream/mageia-cauldron/man1/pamstereogram.1
new file mode 100644
index 00000000..ce57a6cc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamstereogram.1
@@ -0,0 +1,627 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamstereogram User Manual" 0 "2 January 2021" "netpbm documentation"
+.PP
+
+.PP
+.SH NAME
+
+pamstereogram - create a single-image stereogram from a PAM depth map
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpamstereogram\fP
+[\fB-help\fP]
+[\fB-verbose\fP]
+[\fB-blackandwhite\fP | \fB-grayscale\fP | \fB-color\fP]
+[\fB-maxval=\fP\fIvalue\fP]
+[\fB-patfile=\fP\fIpamfile\fP]
+[\fB-texfile=\fP\fIpamfile\fP]
+[\fB-bgcolor=\fP\fIcolor\fP]
+[\fB-smoothing=\fP\fIpixels\fP]
+[\fB-xbegin=\fP\fIpixels\fP]
+[\fB-xshift=\fP\fIpixels\fP]
+[\fB-yshift=\fP\fIpixels\fP]
+[\fB-yfillshift\fP \fIpixels\fP]
+[\fB-magnifypat=\fP\fIscale\fP]
+[\fB-guidetop\fP]
+[\fB-guidebottom\fP]
+[\fB-guidesize=\fP\fIpixels\fP]
+[\fB-dpi=\fP\fIresolution\fP]
+[\fB-crosseyed\fP]
+[\fB-makemask\fP]
+[\fB-eyesep=\fP\fIinches\fP]
+[\fB-depth=\fP\fIfraction\fP]
+[\fB-planes=\fP\fInear_pixels\fP,\fIfar_pixels\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+[\fB-tileable\fP]
+[\fIinfile\fP]
+
+
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamstereogram\fP inputs a depth map (a map of the distances
+from your eye of the points in a scene) and outputs a single-image
+stereogram (SIS). A SIS is a 2-D image specially designed to appear
+three dimensional when viewed with relaxed, slightly unfocused
+eyes. What's exciting about single-image stereograms is that they
+don't require special glasses to view, although it does require a bit
+of practice to train your eyes to unfocus properly.  The
+\fBpamstereogram\fP program provides a wealth of control over how the
+stereogram is generated, including the following:
+
+
+.IP \(bu
+black and white, grayscale, or color output
+
+.IP \(bu
+single-image random-dot stereograms (SIRDS), single-image
+stereograms (SIS) using a tiled image, or mapped-texture stereograms
+(MTS)
+
+.IP \(bu
+images targeting a given device resolution and eye separation
+
+.IP \(bu
+optional guide boxes to assist in focusing
+
+.IP \(bu
+the ability to trade off depth levels for easier viewing
+
+.IP \(bu
+choice of wall-eyed or cross-eyed stereograms
+
+
+.PP
+The output is a PAM image on standard output.  Options control
+the exact format of the PAM.  If you want a PNM (PBM, PGM, or PPM)
+image, use \fBpamtopnm\fP on the output.  There is no need to convert
+if you will use the image as input to a current Netpbm program, but
+many other programs don't know what a PAM is.
+.PP
+To make a red/cyan type of stereogram (that you view with 3-D
+glasses) instead, see \fBppm3d\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+You may use either single or double hyphens to denote options.  You
+may use either whitespace or an equals sign to separate an option name
+from its value.
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamstereogram\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-verbose\fP
+Display messages about image sizes and formats and properties
+of the stereogram being generated.
+
+.TP
+\fB-blackandwhite\fP
+Produce a single-image random-dot black-and-white stereogram.
+This is the default.
+
+.TP
+\fB-grayscale\fP
+Produce a single-image random-dot grayscale stereogram.
+
+.TP
+\fB-color\fP
+Produce a single-image random-dot color stereogram.
+
+.TP
+\fB-maxval=\fP\fIvalue\fP
+Designate the maximum value of each gray/color component, i.e.
+the color resolution. Smaller values make the output image have
+smaller numbers of unique grays/colors. If you don't specify
+\fB-maxval\fP, \fBpamstereogram\fP uses the maxval of the input
+image. This option has no effect with \fB-blackandwhite\fP.
+
+.TP
+\fB-patfile=\fP\fIpamfile\fP
+Specify an image to use as a repeated background pattern for
+the stereogram instead of a random-dot pattern. Intricate images
+generally produce a crisper 3-D effect that simpler images. The
+output file will have the same maxval and format (black and white,
+grayscale or color) as the pattern file. You cannot specify the
+\fB-patfile\fP option along with \fB-blackandwhite\fP,
+\fB-grayscale\fP, \fB-color\fP, or \fB-maxval\fP.  The
+\fB-verbose\fP option will give you information on the ideal
+dimensions of the pattern file.
+
+.TP
+\fB-xbegin=\fP\fIpixels\fP
+Specify the horizontal coordinate at which to begin stereogram generation.
+The background pattern will be minimally distorted at this point and more
+distorted at greater distances.  Consider using this in conjunction
+with \fB-xshift\fP to align the horizontal start of the pattern with the
+horizontal start of stereogram generation. \fB-xbegin\fP is meaningful only
+in conjunction with \fB-patfile\fP, \fB-makemask\fP, or \fB-texfile\fP,
+and \fBpamstereogram\fP actually ignores it with respect to \fB-texfile\fP
+(but may not in a future version of \fBpamstereogram\fP).
+.sp
+The default is to begin in the center.
+.sp
+This option was new in Netpbm 10.71 (June 2015).
+
+.TP
+\fB-texfile=\fP\fIpamfile\fP
+Specify an image to use as the texture for a mapped-texture
+stereogram.  The idea is that the depth-map image provides the depth
+values of the 3-D object/scene while the texture image provides the
+true-color values.  Consequently, the texture image should align with
+the depth-map image.  (Note that it's required to have the same
+dimensions.)  The texture image's background color is ignored when
+blending colors.
+.sp
+This option was new in Netpbm 10.53 (December 2010).
+
+
+.TP
+\fB-bgcolor=\fP\fIcolor\fP
+Use \fIcolor\fP as the texture image's background color instead
+of letting \fBpamstereogram\fP determine it automatically.  Specify
+the color as described for the
+.UR libnetpbm_image.html#colorname
+argument of the pnm_parsecolor() library routine
+.UE
+\&.  The \fB-bgcolor\fP option is meaningful only in conjunction
+with \fB-texfile\fP.
+.sp
+This option was new in Netpbm 10.53 (December 2010).
+
+
+.TP
+\fB-smoothing=\fP\fIpixels\fP
+When used without \fB-texfile\fP, attempt to eliminate artifacts
+introduced by edges in the depth map if \fIpixels\fP is greater than zero.
+.sp
+When used with \fB-texfile\fP, horizontally blur non-background
+colors into background pixels up to a distance of \fIpixels\fP pixels.
+This helps smooth over distracting glitches introduced
+by the stereogram's color constraints when producing a mapped-texture
+stereogram.  In this case, the \fB-smoothing\fP option is helpful
+when the texture image includes smooth color transitions (as in a
+photograph) but makes crisp texture images (as in a line drawing)
+appear blurry.
+.sp
+This option was new in Netpbm 10.53 (December 2010).  Before
+Netpbm 10.61 (December 2012), it has no effect without \fB-texfile\fP.
+
+
+.TP
+\fB-xshift=\fP\fIpixels\fP
+Shift the pattern image (designated by \fB-patfile\fP) to the
+right by \fIpixels\fP pixels (default: 0).
+.sp
+This option is valid only along with \fB-patfile\fP.
+
+.TP
+\fB-yshift\fP \fIpixels\fP
+Shift the pattern image (designated by \fB-patfile\fP)
+downwards by \fIpixels\fP pixels (default: 0). This option is
+valid only along with \fB-patfile\fP.
+
+.TP
+\fB-yfillshift\fP \fIpixels\fP
+Shift the pattern image (designated by \fB-patfile\fP) downwards
+by \fIpixels\fP pixels (default: 0) but only after the initial
+population of the pattern.  (If used with \fB-yshift\fP the resulting
+shifts are summed.)  A small \fB-yfillshift\fP helps reduce visual
+artifacts in the 3-D image.  Steer's website, referenced under
+.UR #seealso
+SEE ALSO
+.UE
+\&, recommends a shift of approximately
+1/16" (6-7 pixels at \fBpamstereogram\fP's default of 100 DPI).
+.sp
+This option was new in Netpbm 10.94 (March 2021).
+
+.TP
+\fB-magnifypat=\fP\fIscale\fP
+Magnify each pixel in the pattern file or each random dot by
+integral scaling factor \fIscale\fP. Note that
+\fBpamstereogram\fP applies the pattern magnification
+\fIafter\fP pattern shifting (\fB-xshift\fP and
+\fB-yshift\fP).
+
+.TP
+\fB-guidebottom\fP
+Draw a pair of black squares on a white background underneath the stereogram
+proper. These squares help you guide your eyes into proper focus to view the
+3-D image.  The trick is to focus your eyes some distance behind the image,
+causing you to see four black squares, then continue altering your focus
+distance until the middle two black squares fuse into a single black
+square. At that point, a crisp, 3-D image will appear.
+.sp
+This option was new in Netpbm 10.61 (December 2012).  Before that,
+the presence of \fB-guidesize\fP, with a positive value, has the same
+effect.
+
+
+.TP
+\fB-guidetop\fP
+Same as \fB-guidebottom\fP, except the guides go at the top of the image.
+.sp
+This option was new in Netpbm 10.61 (December 2012).  Before that,
+the presence of \fB-guidesize\fP, with a negative value, has the same
+effect.
+
+.TP
+\fB-guidesize=\fP\fIpixels\fP
+The size (width and height) of each guide box.
+.sp
+This is valid only with \fB-guidetop\fP or \fB-guidebottom\fP.
+.sp
+Default is 20.
+.sp
+Before Netpbm 10.61 (December 2012), if you don't specify this option,
+\fBpamstereogram\fP draws no guides.  If you specify it with a positive
+value, \fBpamstereogram\fP behaves as if you specified \fB-guidebottom\fP
+too, and if you specify it with a negative value, it behaves as if you
+specified \fB-guidetop\fP and specified \fBguidesize\fP with the absolute
+value of that negative value.
+
+.TP
+\fB-dpi=\fP\fIresolution\fP
+Specify the resolution of the output device in dots per inch.
+The default is 100 DPI, which represents a fairly crisp screen
+resolution.
+.sp
+Before Netpbm 10.53 (December 2010), the default was 96 DPI.
+
+
+.TP
+\fB-crosseyed\fP
+Invert the gray levels in the depth map (input image) so that the 3-D
+image pops out of the page where it would otherwise sink into the page and
+vice versa. Some people are unable to diverge their eyes and can only cross
+them. The \fB-crosseyed\fP option enables such people to see the 3-D image as
+intended.  You can also specify the \fB-crosseyed\fP option if you prefer
+using depth maps in which darker colors are closer to the eye and lighter
+colors are farther from the eye.
+.sp
+Before Netpbm 10.53 (December 2010), \fBpamstereogram\fP used higher
+(lighter) numbers for things closer to the eye \fIwithout\fP
+\fB-crosseyed\fP and vice versa.
+
+
+.TP
+\fB-makemask\fP
+Instead of a stereogram, output a PAM mask image showing
+coloring constraints. New pixels will be taken from the pattern
+file where the mask is black. Copies of existing pixels will be
+taken from the pattern file where the mask is white. The
+\fB-makemask\fP option can be used to help create more
+sophisticated pattern files (to use with \fB-patfile\fP) Note that
+\fB-makemask\fP ignores \fB-magnifypat\fP; it always produces
+masks that assume a pattern magnification of 1.
+
+.TP
+\fB-eyesep=\fP\fIinches\fP
+Specify the separation in inches between your eyes. The
+default, 2.5 inches (6.4 cm), should be sufficient for most people
+and probably doesn't need to be changed.
+
+.TP
+\fB-depth=\fP\fIfraction\fP
+Specify the output image's depth of field. That is,
+\fIfraction\fP represents the fractional distance of the near
+plane from the far plane. Smaller numbers make the 3-D image easier
+to perceive but flatter. Larger numbers make the 3-D image more
+difficult to perceive but deeper. The default, 0.3333, generally
+works fairly well.
+
+.TP
+\fB-planes=\fP\fInear_pixels\fP,\fIfar_pixels\fP
+Explicitly specify the distance between repeated pixels in the near plane
+and in the far plane.  This is an alternative to
+\fB-eyesep\fP and \fB-depth\fP.  The following equalities hold:
+
+
+.IP \(bu
+\fIeyesep\fP = 2 * \fIfar\fP
+.IP \(bu
+\fIdepth\fP = 2 * (\fIfar\fP - \fInear\fP) /
+      (2 * \fIfar\fP - \fInear\fP)
+
+.sp
+The number of distinct 3-D depths is \fIfar\fP
+- \fInear\fP + 1.  One might say that \fB-eyesep\fP
+and \fB-depth\fP are a more human-friendly way to specify stereoscopic
+parameters (distance between eyes and tradeoff between perceptibility
+and depth) while \fB-planes\fP is a more computer-centric way (pixel
+distances in the resulting stereogram).
+.sp
+This option was new in Netpbm 10.59 (June 2012).
+
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+Specify a seed to be used for the random number generator.
+The default is to use a seed based on the time of day, to one second
+granularity.
+.sp
+It is useful to specify the seed if you want to create reproducible
+results.  With the same random seed, you should get identical results
+every time you run \fBpamstereogram\fP.
+.sp
+This is irrelevant if you use a pattern file (\fB-patfile\fP
+option), because there is no random element to \fBpamstereogram\fP's
+behavior.
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-tileable\fP
+Make the generated image horizontally tileable.  This works by
+blending a left-to-right rendering (the equivalent
+of \fB-xbegin\fP=0) with a right-to-left rendering (the equivalent
+of \fB-xbegin\fP=\fIwidth-1\fP).
+.sp
+This option was new in Netpbm 10.91 (June 2020).
+
+
+
+
+.UN parameters
+.SH PARAMETERS
+.PP
+The only parameter, \fIinfile\fP, is the name of an input file
+that is a depth map image. If you don't specify \fIinfile\fP, the
+input is from standard input.
+.PP
+The input is a PAM image of depth 1. Each sample represents the
+distance from the eye that the 3-D image at that location should
+be.  Lower (darker) numbers mean further from the eye.
+
+.UN notes
+.SH NOTES
+
+.UN inputimages
+.SS Input Images
+.PP
+\fBpamstereogram\fP pays no attention to the image's tuple type and
+ignores all planes other than plane 0.
+.PP
+Like any Netpbm program, \fBpamstereogram\fP will accept PNM
+input as if it were the PAM equivalent.
+
+.UN mappedtexture
+.SS Mapped-texture Stereograms
+.PP
+In a \fImapped-texture stereogram\fP (MTS), the 3-D image can be
+drawn with true colors.  Unlike a SIRDS or tiled-image SIS, however,
+the image portrayed by an MTS is apparent in normal 2-D viewing.  It
+appears repeated multiple times and overlapped with itself, but it is
+not hidden.
+.PP
+You create an MTS with \fBpamstereogram\fP by passing the filename
+of a PAM "texture image" with a \fB-texfile\fP option.  A
+texture image portrays the same 3-D object as the depth-map image but
+indicates the colors that the program should apply to the object.
+.PP
+\fBpamstereogram\fP ignores the texture image's background color when it
+overlaps copies of the 3-D object.  This prevents, for example, a bright-red
+object on a black background from being drawn as a dark-red object (a blend of
+50% bright red and 50% black); instead, the program ignores the black and the
+object remains bright red.  A consequence of this feature is that an MTS looks
+best when the objects in the texture image have a crisp outline.  Smooth
+transitions to the background color result in unwanted color artifacts around
+edges because the program ignores only \fIexact\fP matches with the
+background color.
+.PP
+You should specify a larger-than-normal value for \fB-eyesep\fP
+(and/or \fB-dpi\fP) when producing an MTS.  Otherwise, the 3-D object will
+repeat so many times that most colored pixels will overlap other colored
+pixels, reducing the number of true-colored pixels that remain.
+.PP
+An MTS can employ a background pattern (\fB-patfile\fP).  In this
+case, \fBpamstereogram\fP replaces background pixels with pattern pixels in
+the final step of generating the image.
+
+
+.UN notes_misc
+.SS Miscellaneous
+.PP
+A good initial test is to input an image consisting of a solid
+shape of distance 0 within a large field of maximum distance (e.g., a
+white square on a black background).
+.PP
+With the default values for \fB-dpi\fP and \fB-eyesep\fP, pattern
+images that are 128 pixels wide can tile seamlessly.
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+Generate a SIRDS out of small, brightly colored squares and
+prepare it for display on an 87 DPI monitor:
+
+.nf
+    pamstereogram depthmap.pam \e
+        -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \e
+        >3d.pam
+
+.fi
+.PP
+Generate a SIS by tiling a PPM file (a prior run with
+\fB-verbose\fP indicates how wide the pattern file should be for
+seamless tiling, although any width is acceptable for producing
+SISes):
+
+.nf
+    pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
+
+.fi
+.PP
+Generate an MTS by associating colors with a depth-mapped object
+(using a large eye separation to reduce the number of repetitions of
+the texture image) and twice smoothing over background-colored
+speckles:
+
+.nf
+    pamstereogram depthmap.pam \e
+        -texfile colormap.pam -smoothing 2 -eyesep 3.5 \e
+        >3d.pam
+
+.fi
+
+
+.UN seealso
+.SH SEE ALSO
+
+.IP \(bu
+
+.BR "pam" (1)\c
+\&
+
+.IP \(bu
+
+.BR "pamsistoaglyph" (1)\c
+\&
+
+.IP \(bu
+
+.BR "ppm3d" (1)\c
+\&
+
+.IP \(bu
+Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten.
+\fIDisplaying 3D Images: Algorithms for Single Image Random Dot
+Stereograms\fP. In IEEE Computer, \fB27\fP(10):38-48,
+October 1994.  DOI: 
+.UR http://dx.doi.org/10.1109/2.318576
+10.1109/2.318576
+.UE
+\&.
+
+.IP \(bu
+W. A. Steer.
+\fIStereograms: Technical Details\fP.
+URL:
+.BR "http://www.techmind.org/stereo/stech.html" (1)\c
+\&.
+
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamstereogram\fP was new in Netpbm 10.22 (April 2004), but probably
+broken beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23
+(January 2006).
+.PP
+A backward incompatible change to the way you request guide boxes
+(\fB-guidetop\fP, \fB-guidebottom\fP, \fB-guidesize\fP happened in
+Netpbm 10.61 (December 2012).
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright \(co 2006-2020 Scott Pakin, \fIscott+pbm@pakin.org\fP.
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #parameters
+PARAMETERS
+.UE
+\&
+.IP \(bu
+
+.UR #notes
+NOTES
+.UE
+\&
+  
+.IP \(bu
+
+.UR #inputimages
+Input Images
+.UE
+\&
+.IP \(bu
+
+.UR #mappedtexture
+Mapped-texture Stereograms
+.UE
+\&
+.IP \(bu
+
+.UR #notes_misc
+Miscellaneous
+.UE
+\&
+  
+.IP \(bu
+
+.UR #examples
+EXAMPLES
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.IP \(bu
+
+.UR #author
+AUTHOR
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamstereogram.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamstretch-gen.1 b/upstream/mageia-cauldron/man1/pamstretch-gen.1
new file mode 100644
index 00000000..adecbefa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamstretch-gen.1
@@ -0,0 +1,69 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamstretch-gen User Manual" 0 "15 January 2019" "netpbm documentation"
+
+.SH NAME
+
+pamstretch-gen - use pamstretch and pamscale to scale by non-integer values
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamstretch-gen\fP \fIN\fP [\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpamstretch-gen\fP is a program which
+uses
+.BR "pamstretch" (1)\c
+\&
+and
+.BR "pamscale" (1)\c
+\& to smoothly scale up a Netpbm
+image by any factor; it's like a more general version of \fBpamstretch\fP
+(hence the name).
+
+\fBpamstretch-gen\fP uses the \fB-dropedge\fP option on \fBpamstretch\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamstretch-gen\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+.PP
+The Netpbm global options \fB-quiet\fP and \fB-plain\fP did not
+exist on \fBpamstretch-gen\fP prior to version 10.86 (March 2019).
+\fB-quiet\fP did not work until version 10.91 (June 2020).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamstretch" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Russell Marks (\fIrussell.marks@ntlworld.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamstretch-gen.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamstretch.1 b/upstream/mageia-cauldron/man1/pamstretch.1
new file mode 100644
index 00000000..379b89b6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamstretch.1
@@ -0,0 +1,143 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamstretch User Manual" 0 "02 February 2019" "netpbm documentation"
+
+.SH NAME
+pamstretch - scale up a PNM or PAM image by interpolating between pixels.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamstretch\fP
+
+[\fB-xscale=\fP\fIX\fP]
+
+[\fB-yscale=\fP\fIY\fP]
+[\fB-blackedge\fP]
+
+[\fB-dropedge\fP]
+
+\fIN\fP
+
+[\fIinfile\fP]
+.PP
+You can use the minimum unique abbreviation of the options.  You can use
+two hyphens instead of one.  You can separate an option name from its value
+with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamstretch \fP scales up pictures by integer values, either
+vertically, horizontally, or both.  \fBpamstretch \fP differs from
+\fBpamscale\fP and \fBpamenlarge\fP in that when it inserts the
+additional rows and columns, instead of making the new row or column a
+copy of its neighbor, \fBpamstretch\fP makes the new row or column an
+interpolation between its neighbors.  In some images, this produces
+better looking output.
+.PP
+To scale up to non-integer pixel sizes, e.g. 2.5, try
+.BR "pamstretch-gen" (1)\c
+\& instead.
+.PP
+Options let you select alternative methods of dealing with the
+right/bottom edges of the picture.  Since the interpolation is done
+between the top-left corners of the scaled-up pixels, it's not obvious
+what to do with the right/bottom edges.  The default behaviour is to
+scale those up without interpolation (more precisely, the right edge
+is only interpolated vertically, and the bottom edge is only
+interpolated horizontally), but there are two other possibilities,
+selected by the \fB-blackedge\fP and \fB-dropedge\fP options.
+.PP
+In the special case that the stretch factor is 1, there is no issue with
+the right and bottom edges, the edges of the output are identical to the edges
+of the input regardless of \fB-blackedge\fP and \fB-dropedge\fP.  However,
+before Netpbm 10.86 (March 2019), \fB-dropedge\fP would cause the edge to be
+dropped even where the stretch factor was 1.
+  
+  
+.UN parameters
+.SH PARAMETERS
+.PP
+The \fIN\fP parameter is the scale factor.  It is valid only if
+you \fIdon't\fP specify \fB-xscale\fP or \fB-yscale\fP.  In that
+case, \fBpamstretch\fP scales in both dimensions and by the scale
+factor \fIN\fP.
+.PP
+Before Netpbm 10.86 (March 2019), 1 was not a valid value.
+  
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamstretch\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-xscale=\fP\fIX\fP
+This is the horizontal scale factor.  If you don't specify this, but do
+specify a vertical scale factor, the horizontal scale factor is 1.
+.sp
+This option was new in Netpbm 9.21 (December 2001).
+  
+.TP
+\fB-yscale=\fP\fIY\fP
+This is the vertical scale factor.  If you don't specify this, but
+do specify a horizontal scale factor, the vertical scale factor is 1.
+.sp
+This option was new in Netpbm 9.21 (December 2001).
+
+.TP
+\fB-blackedge\fP
+interpolate to black at right/bottom edges.
+
+.TP
+\fB-dropedge\fP
+drop one (source) pixel at right/bottom edges. This is arguably
+more logical than the default behaviour, but it means producing output
+which is a slightly odd size.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+Usually produces fairly ugly output for PBMs. For most PBM input
+you'll probably want to reduce the `noise' first using something like
+.BR "pnmnlfilt" (1)\c
+\&.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamstretch-gen" (1)\c
+\&,
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pnmnlfilt" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Russell Marks (\fIrussell.marks@ntlworld.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamstretch.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsumm.1 b/upstream/mageia-cauldron/man1/pamsumm.1
new file mode 100644
index 00000000..f240e5f4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsumm.1
@@ -0,0 +1,146 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsumm User Manual" 0 "26 October 2012" "netpbm documentation"
+
+.SH NAME
+pamsumm - Summarize the samples in a Netpbm image arithmetically
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamsumm\fP
+{
+\fB-sum\fP |
+\fB-mean\fP |
+\fB-min\fP |
+\fB-max\fP
+}
+[\fB-normalize\fP]
+[\fB-brief\fP]
+[\fIimagefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsumm\fP reads a Netpbm image (PNM or PAM) and performs a
+summary function over all the samples in all the rows, columns, and planes
+and prints the result to Standard Output.
+.PP
+\fBpamsumm\fP performs the operation on the actual sample values.  In the
+case of a PGM or PPM or PAM equivalent (i.e. a visual image), this is not the
+same as the light intensities represented by those samples.  See the format
+specifications of
+.BR "PGM" (1)\c
+\&,
+.BR "PPM" (1)\c
+\&, and
+.BR "PAM" (1)\c
+\&, for the precise
+meanings of samples in these formats.  If you want to do arithmetic on light
+intensities of such a visual image, you can use \fBpnmgamma\fP to convert it
+to one with samples proportional to light intensity, and then
+use \fBpamsumm\fP on the result.
+.PP
+If you want to summarize by column (e.g. add up the columns
+separately), use \fBpamsummcol\fP.  If you want to summarize by row,
+use a combination of \fBpamsummcol\fP and \fBpamflip\fP.  If you
+want to summarize a particular plane, use \fBpamchannel\fP to
+extract it and then \fBpamsumm\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamsumm\fP recognizes the following
+command line options:
+.PP
+You must specify exactly one of \fB-sum\fP, \fB-mean\fP,
+\fB-min\fP, or \fB-max\fP.
+
+
+.TP
+\fB-sum\fP
+.sp
+This option makes the summary function addition.
+
+.TP
+\fB-mean\fP
+.sp
+This option makes the summary function arithmetic mean.
+
+.TP
+\fB-min\fP
+.sp
+This option makes the summary function arithmetic minimum.
+
+.TP
+\fB-max\fP
+.sp
+This option makes the summary function arithmetic maximum.
+
+.TP
+\fB-normalize\fP
+.sp
+This option causes each sample to be normalized to a fraction
+     (in the range 0..1) so the result is independent of the image's
+     maxval.  E.g. if you request the mean of an image which has maxval
+     200 and all the samples have value 50, \fBpamsumm\fP will give you
+     50 as an answer.  But \fBpamsumm -normalize\fP will give you .25.
+.sp
+If instead you want a result that is independent of maxval but still
+     in integers, you can use \fBpamdepth\fP to convert the input to some
+     standard maxval and not use \fB-normalize\fP.  For example, if you want
+     the mean brightness of a PPM image, on a scale of 0 to 99, do
+
+.nf
+\f(CW
+    pamdepth 99 myimage.ppm | pamsumm -mean
+\fP
+
+.fi
+.sp
+This option was new in Netpbm 10.22 (April 2004)
+     
+.TP
+\fB-brief\fP
+.sp
+This option causes \fBpamsumm\fP to display the answer as a bare
+     number, rather than in a complete sentence.
+.sp
+This option was new in Netpbm 10.22 (April 2004)
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamsummcol" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamsumm\fP was added to Netpbm in Release 10.21 (March
+2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsumm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamsummcol.1 b/upstream/mageia-cauldron/man1/pamsummcol.1
new file mode 100644
index 00000000..92455eda
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamsummcol.1
@@ -0,0 +1,142 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamsummcol User Manual" 0 "25 January 2009" "netpbm documentation"
+
+.SH NAME
+pamsummcol - summarize (sum, average, etc) a Netpbm image by column
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamsummcol\fP
+{
+\fB-sum\fP |
+\fB-mean\fP |
+\fB-min\fP |
+\fB-max\fP
+}
+[\fIimagefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamsummcol\fP reads a Netpbm image (PNM or PAM) and performs a
+summary function over all the rows in each column (sum, mean, etc.).
+It produces an image of the same kind that the same width and depth as
+the input, and one row high.  Its sample values are the result of the
+summary.
+.PP
+\fBpamsummcol\fP performs the summary operation on each plane
+independently.
+.PP
+\fBpamsummcol\fP performs the operation on the actual sample values,
+not on the light intensities represented by them in the case that the
+image is a PGM or PPM image.
+.PP
+If you want to summarize by row instead of by column, run the input
+through \fBpamflip\fP first (and if you want the output to be a single
+column instead of a single row, use \fBpamflip\fP again).
+.PP
+If you want to summarize over the entire image (getting a one-tuple
+output image), use \fBpamsumm\fP to get a summary row, \fBpamflip\fP
+to turn that into a column, the \fBpamsumm\fP again to summarize the
+column.
+.PP
+If you want to summarize the individual samples in an entire image,
+instead of by tuple, use \fBpamsumm\fP.
+.PP
+\fBpamsummcol\fP performs the operation on the actual sample values,
+not on the light intensities represented by them in the case that the
+image is a PGM or PPM image or PAM equivalent.  You can use
+\fBpnmgamma\fP to convert such an image to one with samples proportional
+to light intensity, and then use \fBpamsummcol\fP on the result.
+.PP
+You can achieve the same thing as \fBpamsummcol -mean\fP with
+\fBpamscale\fP.  Just scale vertically to a single row, without scaling
+horizontally at all.  Use the pixel mixing method.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamsummcol\fP recognizes the following
+command line options:
+.PP
+You must specify exactly one of \fB-sum\fP, \fB-mean\fP,
+\fB-min\fP, or \fB-max\fP.
+
+
+.TP
+\fB-sum\fP
+.sp
+This option makes the summary function addition.
+     In each column and plane of the output row, the sample value is the
+     sum of all the samples values in the same column and plane of the input.
+     If a result is greater than the image maxval, it is clipped to
+     the maxval.
+
+.TP
+\fB-mean\fP
+.sp
+This option makes the summary function arithmetic mean.
+     In each column and plane of the output row, the sample value is the
+     mean of all the samples values in the same column and plane of the input.
+
+.TP
+\fB-min\fP
+.sp
+This option makes the summary function arithmetic minimum.
+     In each column and plane of the output row, the sample value is the
+     minimum of all the samples values in the same column and plane of
+     the input.
+
+.TP
+\fB-max\fP
+.sp
+This option makes the summary function arithmetic maximum.
+     In each column and plane of the output row, the sample value is
+     the maximum of all the samples values in the same column and
+     plane of the input.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamsumm" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "pamfunc" (1)\c
+\&,
+.BR "pamarith" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamsummcol\fP was added to Netpbm in Release 10.21 (March
+2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamsummcol.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtable.1 b/upstream/mageia-cauldron/man1/pamtable.1
new file mode 100644
index 00000000..d151ab89
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtable.1
@@ -0,0 +1,147 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtable User Manual" 0 "15 April 2017" "netpbm documentation"
+
+.SH NAME
+
+pamtable - print the raster as a table of numerical sample values
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtable\fP
+
+[\fB-tuple\fP]
+[\fB-hex\fP]
+
+[\fInetpbmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtable\fP prints the raster of a Netpbm image as a table of numerical
+sample values.  For example, a 5-pixel wide, 2-pixel high rainbow (black, red,
+green, blue, white) PPM image with maxval 255 would appear as follows:
+
+.nf
+
+
+        0   0   0|255   0   0|  0 255   0|  0   0 255|255 255 255
+        0   0   0|255   0   0|  0 255   0|  0   0 255|255 255 255
+
+
+
+.fi
+.PP
+There are other output formats possible.  See the command line options.
+.PP
+If you care to see only certain rows or columns, use \fBpamcut\fP to
+filter the input.
+.PP
+If you care to see only certain planes, use \fBpamchannel\fP to filter the
+input.
+.PP
+\fBpamtable\fP prints vertical bars between tuples, unless there is only
+one sample per tuple, in which case it prints a single space between tuples.
+.PP
+\fBpamtable\fP prints a single space between samples within a tuple.
+.PP
+For each sample, \fBpamtable\fP prints the numerical value from the Netpbm
+image, uninterpreted.  It prints it in decimal, right justified in the minimum
+number of spaces required to print the maxval of the image.
+.PP
+If you want the samples to print more densely, use \fBpamdepth\fP to
+reduce the maxval (thus making the decimal numbers for the samples narrower).
+.PP
+The \fBless\fP program (not part of Netpbm) is good for browsing through
+the table.  Use its \fB--chop-long-lines\fP option and use cursor movement
+keys to scroll around in the image.
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+The only possible argument is the name of the file containing the input
+Netpbm image.  This is optional; if you don't specify any arguments, the input
+comes from Standard Input.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm (most
+notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtable\fP recognizes the following command line options:
+
+
+.TP
+\fB-tuple\fP
+Print the tuple values in mathematical tuple notation, like this:
+
+.nf
+
+
+        (0, 0, 0) (255, 0, 0) (0, 255, 0) (0, 0, 255) (255, 255, 255)
+        (0, 0, 0) (255, 0, 0) (0, 255, 0) (0, 0, 255) (255, 255, 255)
+
+
+
+.fi
+.sp
+This option was new in Netpbm 10.11.00 (September 2022).
+
+.TP
+\fB-hex\fP
+Display sample values in hexadecimal instead of decimal.
+.sp
+This option is not valid with \fB-tuple\fP.
+.sp
+This option was new in Netpbm 10.11.00 (September 2022).
+
+  
+.TP
+\fB-verbose\fP
+.sp
+Print additional messages about the processing.
+  
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamchannel" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pamslice" (1)\c
+\&,
+.BR "ppmtoarbtxt" (1)\c
+\&,
+.BR "ppmtoterm" (1)\c
+\&,
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtable\fP was new in Netpbm 10.79 (June 2017).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtable.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamthreshold.1 b/upstream/mageia-cauldron/man1/pamthreshold.1
new file mode 100644
index 00000000..465a441f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamthreshold.1
@@ -0,0 +1,192 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamthreshold User Manual" 0 "06 June 2007" "netpbm documentation"
+
+.SH NAME
+
+pamthreshold - threshold grayscale image to black and white
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamthreshold\fP
+[\fB-simple\fP]
+[\fB-local=\fP\fIwidth\fP\fBx\fP\fIheight\fP]
+[\fB-dual=\fP\fIwidth\fP\fBx\fP\fIheight\fP]
+[\fB-threshold=\fP\fIthreshold\fP]
+[\fB-contrast=\fP\fIthreshold\fP]
+[\fIinputpamfile\fP]
+.PP
+Minimum unique abbreviations of options are acceptable. You may use
+double hyphens instead of a single hyphen to denote options. You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamthreshold\fP thresholds a grayscale image. Thresholding means
+dividing the image into background and foreground by comparing every pixel
+to a thresholding value.
+.PP
+The input should be a PGM image or a PAM image of tuple type
+GRAYSCALE or GRAYSCALE_ALPHA.  However, pamthreshold doesn't check; it
+just thresholds the first channel as if it were grayscale samples and
+if there is a second channel, processes it as if it is a transparency
+(alpha) channel.  So if you feed it e.g. a PPM image, it will
+work but produce probably useless results.
+.PP
+The output is a PAM with tuple type BLACKANDWHITE or
+BLACKANDWHITE_ALPHA, depending on whether the input has a transparency
+channel.  You can turn this into a PBM (if you need to use it with an
+older program that doesn't understand PAM, or you can't afford the 8X
+amount of space that PAM uses for the image) with
+\fBpamtopnm\fP.
+.PP
+The output is to Standard Output.
+.PP
+When the input has a transparency channel, \fBpamthreshold\fP includes
+a transparency channel in the output.  Since the output has maxval 1, the
+transparency channel can indicate only fully transparent or fully opaque.
+\fBpamthreshold\fP make it fully transparent where the input is more
+than half transparent and fully opaque where it isn't.
+.PP
+The transparency function was new in Netpbm 10.43 (June 2008).  Before
+that, \fBpamthreshold\fP ignores any transparency channel in the input.
+.PP
+Another way to convert a grayscale image to black and white is to
+dither.  Dithering is using clustered black and white pixels such that
+if you step back and look at the picture, you see varying levels of
+gray.  \fBpamditherbw\fP does dithering.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamthreshold\fP recognizes the following
+command line options:
+.PP
+Without any options, \fBpamthreshold\fP uses a method based on the
+iterative algorithm found in
+the 
+.UR http://www.wikipedia.org/
+wikipedia
+.UE
+\& article
+.UR http://en.wikipedia.org/wiki/Thresholding_%28image_processing%29
+ \fIThresholding (image processing)\fP
+.UE
+\& to compute the thresholding
+value.  (
+.UR http://en.wikipedia.org/w/index.php?title=Thresholding_%28image_processing%29&oldid=132306976
+this version
+.UE
+\& of the Wikipedia article was current at the time of this
+writing).  It uses this threshold to globally threshold the image.
+This should work well for most images.  The program issues a message
+telling you what threshold it used.  (Netpbm messages go to Standard
+Error, and you can turn them off with the Netpbm common option
+\fB-quiet\fP).
+.PP
+Options \fB-simple\fP, \fB-local\fP, and \fB-dual\fP select other
+methods.
+
+
+
+.TP
+\fB-simple\fP
+This selects simple or global thresholding,
+i.e. \fBpamthreshold\fP compares every pixel to the threshold you
+specify with \fB-threshold\fP.  Those with a brightness greater than
+or equal to the threshold become white; others become black.  This
+works well for black and white text pages scanned with a flatbed
+scanner and is faster than the default method that iteratively
+determines the thresholding value first.
+
+.TP
+\fB-local=\fP\fIwidth\fP\fBx\fP\fIheight\fP
+This selects local adaptive thresholding (also known as dynamic
+thresholding) using the neighborhood which is the square \fIwidth\fP pixels
+wide and \fIheight\fP pixels high centered on the pixel in question.
+\fBpamthreshold\fP computes the threshold individually for each pixel of the
+image.  This can accommodate changing lighting conditions in the image.
+Depending on the size of the neighborhood this can be quite slow.
+
+.TP
+\fB-dual=\fP\fIwidth\fP\fBx\fP\fIheight\fP
+This selects a dual thresholding algorithm using a global threshold
+for low contrast neighborhoods and local thresholding otherwise.  This
+can preserve larger back- respectively foreground areas than local
+adaptive thresholding.  This algorithm was proposed in the paper
+"An Approach To Licence Plate Recognition" by J.R. Parker and Pavol Federl.
+
+.TP
+\fB-threshold=\fP\fIthreshold\fP
+This sets the thresholding value for simple or local thresholding.  The
+value is a floating point number in the range [0, 1] directly proportional to
+the Netpbm sample values, where 0 corresponds to black and 1 to the maxval of
+the image.
+.sp
+If you don't specify this option, \fBpamthreshold\fP uses a threshold
+of 0.5.
+.sp
+Without \fB-simple\fP, \fB-local\fP, or \fB-dual\fP, this option is
+meaningless.
+.sp
+The meaning of the threshold depends upon the kind of thresholding
+you do (as determined by other options).  Roughly, pixels at least as
+bright as the threshold become white in the output while others become
+black.
+
+.TP
+\fB-contrast=\fP\fIthreshold\fP
+This sets the threshold to determine if a neighborhood has low contrast
+or not for dual thresholding.  The value is a floating point number in
+the range [0, 1].
+.sp
+If you don't specify this option, \fBpamthreshold\fP uses a contrast
+threshold of 0.05.  Without \fB-dual\fP this option is meaningless.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamditherbw" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamthreshold\fP was new in Netpbm 10.34 (June 2006).
+
+.UN author
+.SH AUTHOR
+.PP
+\fBpamthreshold\fP is Copyright \(co 2006 by Erik Auerswald and released
+under the
+.BR "GPL" (1)\c
+\&.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamthreshold.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtilt.1 b/upstream/mageia-cauldron/man1/pamtilt.1
new file mode 100644
index 00000000..07b8c762
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtilt.1
@@ -0,0 +1,181 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtilt User Manual" 0 "28 August 2005" "netpbm documentation"
+
+.SH NAME
+pamtilt - print the tilt angle of a PGM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtilt\fP
+[\fB-angle=\fP\fImaxangle\fP]
+[\fB-fast\fP]
+[\fB-quality=\fP\fIq\fP]
+[\fB-hstep=\fP\fIn\fP]
+[\fB-vstep=\fP\fIn\fP]
+[\fB-dstep=\fP\fIn\fP]
+[\fB-astep=\fP\fIn\fP]
+[\fB-verbose\fP]
+[\fIpgmfile\fP]
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+\f(CW
+    scanimage --mode Gray --resolution 300 >crooked.pgm
+    pnmrotate -b white `pamtilt crooked.pgm` crooked.pgm >straight.pgm
+\fP
+    (then crop, threshold, etc.)
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtilt\fP tries to find the correct angle for untilting
+(de-skewing) a scanned text document.  The output is a single
+floating-point number (the angle in degrees) for use as the argument
+to pnmrotate.
+.PP
+"Document skew" is the name given to what happens when
+you feed a page into an image scanner at an angle: the resulting image
+is tilted.  \fBpamtilt\fP aims to help correct that.
+.PP
+\fBpamtilt\fP makes three iterations at successively finer
+increments, testing prospective rotation angles to find the best one.
+\fBpamtilt\fP works best for straightening images with strong
+horizontal lines and does poorly with arbitrary photos.  If
+\fBpamtilt\fP has no confidence in its results, it prints the special
+value 00.00; you can check for this or just pass it as a legal
+argument to pnmrotate.
+.PP
+\fBpamtilt\fP operates on the first plane of the input image,
+which is either PNM or PAM, and ignores any other planes.  Ordinarily,
+the input is PGM or GRAYSCALE PAM, so there is only one plane.
+.PP
+\fBpamtilt\fP works on bilevel (PBM, BLACKANDWHITE PAM) images as
+well as grayscale, but you will minimize artifacts if you scan and
+rotate in grayscale before you apply a threshold to make a bilevel
+image.
+        
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtilt\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-angle=\fP\fImaxangle\fP
+Assume a maximum tilt angle of \fImaxangle\fP (measured in degrees).
+The default value is sufficient for most images, even those scanned
+somewhat carelessly.
+.sp
+The default is 10.0.
+
+.TP
+\fB-fast\fP
+Skip the third iteration for speed at the expense of accuracy.
+
+.TP
+\fB-verbose\fP
+Show on Standard Error the measurements computed at each tested angle.
+
+
+.PP
+Here are some other options you can use to tune the operation of
+\fBpamtilt\fP but they're seldom needed.  The default values
+accommodate a wide variety of input documents.
+
+
+.TP
+
+\fB-quality=\fP\fIq\fP
+Require a signal-to-noise ratio of a least \fIq\fP on the first
+iteration to report a valid result.  Larger values reduce the chances
+of obtaining a bogus result at the risk of obtaining no result at all.
+.sp
+The default is 1.0.
+
+.TP
+\fB-hstep=\fP\fIn\fP
+Set the horizontal increment to check every \fIn\fPth column.  This
+value affects both run time and memory requirements.
+.sp
+The default is 11.
+
+.TP
+\fB-vstep=\fP\fIn\fP
+Set the vertical increment to check every nth row.  Larger values
+usually work, reducing run time, but they increase the risk of
+incorrect results.
+.sp
+The default is 5.
+
+.TP
+\fB-dstep=\fP\fIn\fP
+Set the vertical distance used when checking pixels in a column.  The
+default is intended to minimize the effect of noise along a horizontal
+boundary.
+.sp
+The default is 2.
+
+.TP
+\fB-astep=\fP\fIn\fP
+Set the angle increment of the first iteration, in degrees.
+.sp
+The default is 1.0.
+
+
+
+
+.UN references
+.SH REFERENCES
+.PP
+\fBpamtilt\fP implements a somewhat simplified algorithm inspired
+by: "Measuring Document Image Skew and Orientation", by Bloomberg,
+Kopec, and Dasari.  In SPIE Volume 2422, Document Recognition II,
+pages 302-316, February 1995.
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "\fBpnmrotate\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "pgm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtilt\fP was new in Netpbm 10.30 (October 2005).
+.PP
+Gregg Townsend wrote it and sent it to Bryan Henderson in August
+2005.  Bryan recoded it to fit Netpbm conventions.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtilt.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtoavs.1 b/upstream/mageia-cauldron/man1/pamtoavs.1
new file mode 100644
index 00000000..eda41b5a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtoavs.1
@@ -0,0 +1,82 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtoavs User Manual" 0 "07 February 2010" "netpbm documentation"
+
+.SH NAME
+.PP
+pamtoavs - convert a Netpbm image to an AVS X image
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpamtoavs\fP
+[\fInetpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtoavs\fP reads a Netpbm image as input and produces a Stardent
+AVS
+X image as output. AVS X images are one of the few image formats 
+.UR http://www.gnuplot.info/
+Gnuplot
+.UE
+\&\ v4.2 and later can use.
+.PP
+\fInetpbmfile\fP is the input file, which defaults to Standard Input.
+Output is always on Standard Output.
+.PP
+Try the following:
+
+.nf
+    gnuplot> plot 'myimage.avs' binary filetype=avs with rgbimage
+
+.fi
+.PP
+See the
+.BR "Gnuplot
+manual" (1)\c
+\& for more information.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamtoavs\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright\ \(co 2010 Scott Pakin,
+\fIscott+pbm@pakin.org\fP
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "avstopam" (1)\c
+\&,
+.UR http://www.gnuplot.info/
+gnuplot
+.UE
+\&,
+.BR "pam" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtoavs.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtodjvurle.1 b/upstream/mageia-cauldron/man1/pamtodjvurle.1
new file mode 100644
index 00000000..ac6cc4dd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtodjvurle.1
@@ -0,0 +1,78 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtodjvurle User Manual" 0 "10 April 2004" "netpbm documentation"
+
+.SH NAME
+pamtodjvurle - convert a Netpbm image to DjVu Color RLE format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtodjvurle\fP
+
+[\fB-transparent\fP \fIcolor\fP]
+[\fInetpbmfile\fP [\fIrlefile\fP]]
+.PP
+Minimum unique abbreviation of options in acceptable.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtodjvurle\fP reads a Netpbm image (PNM or PAM equivalent of
+PNM) as input and produces DjVu Color RLE format as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtodjvurle\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-transparent\fP \fIcolorname\fP
+This option indicates which color in the image should be
+considered transparent.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Default is "white".
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtodjvurle" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtodjvurle\fP was new in Netpbm 10.22 (April 2004) but a
+program that did almost the same thing, called \fBppmtodjvurle\fP,
+was in Netpbm 10.21 (March 2004).  The latter was written and
+contributed to Netpbm by Scott Pakin <scott+pbm@pakin.org>.
+\fBpamtodjvurle\fP uses techniques taken from \fBppmtodjvurle\fP,
+but no code is copied between them.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtodjvurle.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtofits.1 b/upstream/mageia-cauldron/man1/pamtofits.1
new file mode 100644
index 00000000..6623240f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtofits.1
@@ -0,0 +1,118 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtofits User Manual" 0 "25 September 2005" "netpbm documentation"
+
+.SH NAME
+
+pamtofits - convert a Netpbm image into FITS format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtofits\fP
+[\fB-max\fP \fIf\fP]
+[\fB-min\fP \fIf\fP]
+[\fIpamfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtofits\fP reads a PNM or PAM image as input and produces a FITS
+(Flexible Image Transport System) file as output.  The resolution of
+the output file is either 8 bits/pixel, or 16 bits/pixel, depending on
+the value of maxval in the input file.  If the input file is a PBM or
+PGM image, the output file consists of a single plane image (NAXIS =
+2). If instead the input file is a PPM image, the output file will
+consist of a three-plane image (NAXIS = 3, NAXIS3 = 3).
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtofits\fP recognizes the following
+command line options:
+.PP
+\fB-min\fP and \fB-max\fP tell \fBpamtofits\fP what "physical
+values" zero and maxval sample values, respectively, in the input
+image represent.  Physical values are a FITS concept.  \fBpamtofits\fP
+sets up the \fBBSCALE\fP and \fBBZERO\fP FITS header cards to indicate
+this information.
+.PP
+The default for \fB-min\fP is 0 and for \fB-max\fP is the maxval,
+which means if you don't specify these options, the FITS physical values
+are in fact the original Netpbm sample values.
+.PP
+\fBpamtofits\fP always sets up the FITS header \fBDATAMIN\fP and
+\fBDATAMAX\fP cards to indicate that the highest physical value in
+the image is the one corresponding to the Netpbm maxval and the lowest is
+that corresponding to Netpbm zero.  This isn't really how those cards are
+supposed to be used, since the input image doesn't necessarily contain
+the full possible range of sample values.  It is a conservative
+approximation.
+
+.UN notes
+.SH NOTES
+
+.UN pixelorder
+.SS Pixel Order
+.PP
+The FITS specification does not specify which data in the file corresponds
+to which pixel in the image (i.e. which bytes are the top left pixel,
+etc.).  Netpbm uses the common sense, most popular arrangement: row major, top
+to bottom, left to right.  That means in a 10 wide by 20 high image, the first
+10 pixels in the file are the top row and the last 10 are the bottom row.
+Within each row, the first pixel is the leftmost one and the last pixel is
+the rightmost one.
+.PP
+\fBNetpbm\fP has always done that, since it first understood the
+FITS format in 1989, so it is something of a de facto standard.  Nobody
+reported trouble with that until 2008.
+.PP
+However, at least some versions of ImageMagick and Gimp (as seen in 2008)
+use bottom to top order, so if you use on of these to display a FITS image
+generated by \fBpamtofits\fP, it will appear upside down.  To fix that,
+use \fBpamflip -topbottom\fP on the image before feeding it
+to \fBpamtofits\fP.
+.PP
+Since 2008, people have noted that NASA distributes FITS files with
+bottom to top order.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtofits\fP was originally \fBpnmtofits\fP and did not handle
+PAM input.  It was extended and renamed in Netpbm 10.30 (October 2005).
+.PP
+\fBpnmtofits\fP was itself an extension of \fBpgmtofits\fP, which
+was added to Pbmplus in 1989.
+
+.UN seealso
+.SH SEE ALSO
+.BR "fitstopnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Wilson H. Bent (\fIwhb@hoh-2.att.com\fP), with
+modifications by Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtofits.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtohdiff.1 b/upstream/mageia-cauldron/man1/pamtohdiff.1
new file mode 100644
index 00000000..e0b2e32e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtohdiff.1
@@ -0,0 +1,106 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtohdiff User Manual" 0 "15 April 2002" "netpbm documentation"
+
+.SH NAME
+
+pamtohdiff - convert PAM image to horizontal difference image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtohdiff\fP
+[\fIpamfile\fP]
+[\fB-verbose\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtohdiff\fP takes a PAM (or PNM) image as input and produces a
+horizontal difference image version of it as output.  A horizontal
+difference image is one where the samples in each row indicate the
+difference between the sample value in the corresponding sample of the
+input image and the sample directly above it (in the previous row) in
+the input image.  The horizontal difference image has the property
+that if a row of the original image is identical to the row above it
+over a long extent, the corresponding row in the horizontal difference
+image will contain all zeroes.  That makes it compress better than the
+original image.
+.PP
+Because the horizontal difference samples can be positive or
+negative, but PAM samples are unsigned integers, the samples in the
+horizontal difference image PAM are defined to be the difference
+modulus the range of the input (maxval + 1).  This doesn't lose any
+information, as it might seem, because: of the two differences that
+could result in the same \fBpamtohdiff\fP output value (e.g. if
+maxval is 99, +20 and -80 would both result in "20" in the output),
+only one is possible in context and the other would result, when
+reconstructing the original image, in a value less than 0 or greater
+than maxval.
+.PP
+Before the modulus operation, the values \fBpamtohdiff\fP
+computes are also biased by half the maxval.  This is to make the
+results easier to inspect visually.  Because of the bias, you can
+display the \fBpamtohdiff\fP output as if it were a PNM image.  As
+long as none of your differences are more than half the maxval, large
+negative differences show up as dark spots, smaller negative
+differences are lighter, zero differences are medium intensity, and
+positive differences are light.  If you want this to work even for
+images that have differences that exceed half the maxval, just use
+\fBppmdim 50\fP on the original image.  To avoid losing information,
+though, do a \fBpamdepth\fP to double the maxval first.
+.PP
+Note that because of the transfer function just described, a 
+difference of zero, which is most common, is represented by a PAM sample
+value in the output of one half the maxval.
+.PP
+The output PAM has a tuple type of "hdiff".
+.PP
+You can use \fBhdifftopam\fP to recover the original image from a
+horizontal difference image PAM.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtohdiff\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-verbose\fP
+Currently no effect.  This may change in future versions.
+
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "hdifftopam" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Bryan Henderson
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtohdiff.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtohtmltbl.1 b/upstream/mageia-cauldron/man1/pamtohtmltbl.1
new file mode 100644
index 00000000..b92f55df
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtohtmltbl.1
@@ -0,0 +1,103 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtohtmltbl User Manual" 0 "13 October 2008" "netpbm documentation"
+
+.SH NAME
+pamtohtmltbl - convert pnm/pam visual image to an HTML table
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtohtmltbl\fP
+[\fB-transparent=\fP\fIcolor\fP]
+[\fB-verbose\fP]
+[\fIfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtohtmltbl\fP converts a visual image to an HTML table with one
+cell per pixel.  The cell is empty, but its background color is that of the
+pixel.
+.PP
+\fIfile\fP is a PBM, PGM, PPM, or PAM file.  If PAM, it must be
+a standard visual image of tuple type RGB, GRAYSCALE, or BLACKANDWHITE, or
+something equivalent with extra higher numbered channels, but
+\fBpamtohtmltbl\fP doesn't check the tuple type; it just assumes.
+.PP
+Note that the more normal way to include a visual image in an HTML
+document is with a <IMG> tag.
+.PP
+Not all web browsers render tables as \fBpamtohtmltbl\fP expects,
+and therefore show a grossly distorted image.  Internet Explorer 7 on
+Windows and Opera 9.02 on Windows have been seen to work; Firefox
+2.0.0.16 on the same Windows system has been seen not to.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtohtmltbl\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-transparent=\fP\fIcolor\fP
+This option indicates that pixels of the specified color are to be transparent
+in the HTML table.  The table cell for a pixel of this color will have no
+background color specified.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+
+.TP
+\fB-verbose\fP
+This option causes \fBpamtohtmltbl\fP to display messages about the
+conversion process.
+     
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.sp
+\fBpamtohtmltbl\fP was new in Netpbm 10.15 (April 2003).
+
+
+.UN authors
+.SH AUTHORS
+.PP
+Alexander B. Ivanov (SSH) wrote a program he called
+\fBpnm2html\fP.  Bryan Henderson adapted it to use the Netpbm
+libraries and handle PAM images and follow Netpbm conventions, and
+named it \fBpamtohtmltbl\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtohtmltbl.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtojpeg2k.1 b/upstream/mageia-cauldron/man1/pamtojpeg2k.1
new file mode 100644
index 00000000..e2d2bbe1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtojpeg2k.1
@@ -0,0 +1,354 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtojpeg2k User Manual" 0 "1 November 2022" "netpbm documentation"
+
+.SH NAME
+pamtojpeg2k - convert PAM/PNM image to a JPEG-2000 code stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtojpeg2k\fP
+[\fB-imgareatlx=\fP\fIcolumn\fP]
+[\fB-imgareatly=\fP\fIrow\fP]
+[\fB-tilegrdtlx=\fP\fIcolumn\fP]
+[\fB-tilegrdtly=\fP\fIrow\fP]
+[\fB-tilewidth=\fP\fIcolumns\fP]
+[\fB-tileheight=\fP\fIrows\fP]
+[\fB-prcwidth=\fP\fIcolumns\fP]
+[\fB-prcheight=\fP\fIrows\fP]
+[\fB-cblkwidth=\fP\fIcolumns\fP]
+[\fB-cblkheight=\fP\fIrows\fP]
+[\fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}]
+[\fB-compression=\fP\fIratio\fP]
+[\fB-size=\fP\fIbytes\fP]
+[\fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
+[\fB-numrlvls=\fP\fInumber\fP]
+[\fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}]
+[\fB-numgbits=\fP\fInumber\fP]
+[\fB-nomct\fP]
+[\fB-sop\fP]
+[\fB-eph\fP]
+[\fB-lazy\fP]
+[\fB-termall\fP]
+[\fB-segsym\fP]
+[\fB-vcausal\fP]
+[\fB-pterm\fP]
+[\fB-resetprob\fP]
+[\fB-verbose\fP]
+[\fB-debuglevel=\fP\fInumber\fP]
+\fIfilename\fP
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtojpeg2k\fP converts the named PBM, PGM, PPM, or PAM file,
+or Standard Input if no file is named, to a JPEG-2000 code stream
+(JPC) file on Standard Output.
+.PP
+The JPEG-2000 specification specifies two separate formats: JP2
+and JPEG-2000 code stream (JPC).  JP2 represents a visual image quite
+specifically, whereas JPC is a more or less arbitrary array of codes.
+\fBpamtojpeg2k\fP can't produce a JP2, but the JPC image that
+\fBpamtojpeg2k\fP produces is very similar to a JP2 if the input is a
+PBM, PGM, or PPM image or equivalent PAM image.  One difference is
+that the RGB intensity values in a JP2 are SRGB values, while
+\fBpamtojpeg2k\fP produces ITU-R Recommendation BT.709 values.  Those
+are very similar, but not identical.  Another difference is that a JP2
+can contain extra information about an image that JPC cannot.
+.PP
+When the input is a PAM image other than a PBM, PGM, or PPM equivalent,
+the JPC raster produced contains whatever the PAM raster does.  It can have
+any number of planes with any meanings; the planes are in the same order in
+the JPC output as in the PAM input.
+.PP
+A JPC image has a "precision," which is the number of bits used for
+each code (in Netpbm lingo, "sample").  Actually, it has a separate
+precision for each component.  \fBpamtojpeg2k\fP uses for the
+precision of every component the least number of bits that can
+represent the maxval of the input image.  A JPC image does not have an
+independent concept of maxval; the maxval of a JPC sample is the
+maximum value that the number of bits specified by the precision can
+represent in pure binary code.  E.g. if the precision is 4, the maxval
+is 15.  \fBpamtojpeg2k\fP does of course scale the sample values from
+the input maxval to the output maxval.  Example: The input maxval is
+99.  This means JPC precision is 7 bits and the JPC maxval is 127.  A
+sample value of 33 in the input becomes a sample value of 43 in the
+output.
+.PP
+\fBpamtojpeg2k\fP generates the JPC output with the 
+.UR http://www.ece.uvic.ca/~mdadams/jasper/
+Jasper JPEG-2000 library
+.UE
+\&.  See documentation of the library for details on what
+\fBpamtojpeg2k\fP produces.  Note that the Jasper library contains
+facilities for reading PNM images, but \fBpamtojpeg2k\fP does not use
+those.  It uses the Netpbm library instead.  Note that the makers of
+the Jasper library write it "JasPer," but Netpbm documentation follows
+standard American English typography rules, which don't allow that
+kind of capitalization.
+.PP
+Use \fBjpeg2ktopam\fP to convert in the other direction.
+.PP
+The program \fBjasper\fP, which is packaged with the Jasper 
+JPEG-2000 library, also converts between JPEG-2000 and PNM formats.
+Because it's packaged with the library, it may exploit it better, 
+especially recently added features.  However, since it does not use the
+Netpbm library to read and write the Netpbm formats, it doesn't do as
+good a job on that side.
+.PP
+Another format with goals similar to those of JPEG-2000 but that allows for
+faster encoding and decoding, is
+JPEG-LS.  
+.UR http://charls.codeplex.com
+CharLS
+.UE
+\& is a package of
+software for using JPEG-LS.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtojpeg2k\fP recognizes the following
+command line options:
+
+.UN jasperopts
+.SS Jasper Library Options
+.PP
+These options are identical in name and function to options that the
+Jasper library JPC encoder subroutine takes.  See
+.UR http://www.ece.uvic.ca/~mdadams/jasper/
+Jasper documentation
+.UE
+\&
+for details.
+
+
+.TP
+\fB-imgareatlx=\fP\fIcolumn\fP
+.TP
+\fB-imgareatly=\fP\fIrow\fP
+.TP
+\fB-tilegrdtlx=\fP\fIcolumn\fP
+.TP
+\fB-tilegrdtly=\fP\fIrow\fP
+.TP
+\fB-tilewidth=\fP\fIcolumns\fP
+.TP
+\fB-tileheight=\fP\fIrows\fP
+.TP
+\fB-prcwidth=\fP\fIcolumns\fP
+.TP
+\fB-prcheight=\fP\fIrows\fP
+.TP
+\fB-cblkwidth=\fP\fIcolumns\fP
+.TP
+\fB-cblkheight=\fP\fIrows\fP
+.TP
+\fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}
+.TP
+\fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
+.TP
+\fB-numrlvls=\fP\fInumber\fP
+.TP
+\fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}
+.TP
+\fB-numgbits=\fP\fInumber\fP
+.TP
+\fB-nomct\fP
+.TP
+\fB-sop\fP
+.TP
+\fB-eph\fP
+.TP
+\fB-lazy\fP
+.TP
+\fB-termall\fP
+.TP
+\fB-segsym\fP
+.TP
+\fB-vcausal\fP
+.TP
+\fB-pterm\fP
+.TP
+\fB-resetprob\fP
+
+.PP
+\fB-ilyrrates\fP ('intermediate layer rates') lets you control
+  the compression at each layer.  The compressed image is arranged in layers,
+  so if you transmit it somewhere serially, enough information to make a low
+  quality image arrives soon, then later more information arrives to improve
+  the quality of the image, and so on until the entire image arrives.  The
+  value of this option is a list of ascending fractions, such as
+  '.1,.3,.5'.  Each fraction says the size of the layers up to and
+  including that layer should add up to that fraction of the size of the input
+  image.  If the size of the entire image is limited by \fB-compression\fP
+  or \fB-size\fP, none of these numbers may exceed that limit.
+
+.UN otheropts
+.SS Other Options
+
+
+
+.TP
+\fB-compression=\fP\fIratio\fP
+\fIratio\fP is a floating point number that specifies the compression
+ratio.  \fBpamtojpeg2k\fP will adjust quality as necessary to ensure that
+you get this compression ratio.  E.g. 4 means the output will be about
+one fourth the size in bytes of the input file.
+.sp
+The ratio concerns just the raster part of the image, with the denominator
+being what the raster would take if it were encoded the most naive way
+possible (e.g. 3 bytes per pixel in 8-bit-per-sample RGB).  It does,
+however, include metadata that is part of the compressed raster.  Because
+of that, it may not be possible to give you your requested compression ratio
+at any quality.  If it isn't, \fBpamtojpeg2k\fP fails with a message
+saying so.
+.sp
+If you don't specify this option, \fBpamtojpeg2k\fP gives you the best
+compression it can without losing any quality.  Because of the metadata issue
+described above, this may mean, for a small image, the image actually expands.
+.sp
+This option controls the 'rate' option of the Jasper library.
+Note that though the Jasper library takes a compression factor, this option
+specifies a compression ratio.  The compression factor is the multiplicative
+inverse of (1 divided by) the compression ratio.
+.sp
+You may not specify this with \fB-size\fP.
+.sp
+Before Netpbm 10.61 (December 2012), the default was a compression ratio
+of 1, and if \fBpamtojpeg2k\fP could not make the output that small, it just
+made it as small as it could, with zero quality.  You know this is happening
+when you see the warning message, "empty layer generated."
+
+.TP
+\fB-size=\fP\fIbytes\fP
+This option specifies the maximum size in bytes you want the output image
+to have.  This size is all-in, including headers and trailers and other
+metadata.  \fBpamtojpeg2k\fP will omit as much information as necessary to
+get under this limit.
+.sp
+It is possible to specify a value impossibly small, for example a value
+that doesn&apos;t even leave room for the image header.  If you do this, the
+program fails with an explanatory message.
+.sp
+This option controls the 'rate' option of the Jasper library.
+.sp
+You may not specify this with \fB-compression\fP.
+.sp
+This option was new in Netpbm 11.1 (December 2022).
+  
+  
+.TP
+\fB-verbose\fP
+This option causes \fBpamtojpeg2k\fP to issue informational messages about
+the conversion process.
+
+.TP
+\fB-debuglevel\fP=\fInumber\fP
+This option controls debug messages from the Jasper library.  
+\fBpamtojpeg2k\fP passes \fInumber\fP as the debug level to the Jasper
+JPC encoder.
+
+
+     
+.UN examples
+.SH EXAMPLES
+.PP
+This example compresses losslessly.
+
+.nf
+  pamtojpeg2k myimg.ppm >myimg.jpc
+
+.fi
+
+\fBjpeg2ktopam\fP will recreate myimg.ppm exactly.
+.PP
+This example compresses the file to one tenth its original size, throwing
+away information as necessary.
+
+.nf
+  pamtojpeg2k -compression=10 myimg.pgm >myimg.jpc
+
+.fi
+
+
+.UN jpeg2000
+.SH ABOUT JPEG-2000
+.PP
+JPEG-2000 is a format that compresses a visual image (or a similar set of
+data) into a minimal number of bytes for storage or transmission.  In that,
+its goal is similar to JPEG.  It has two main differences from JPEG.  
+.PP
+One difference is that it does a much better job on most images of
+throwing out information in order to achieve a smaller output.  That
+means when you reconstruct the image from the resulting compressed
+file, it looks a lot closer to the image you started with
+JPEG-2000 than with JPEG, for the same compressed file size.  Or, looked
+at another way, with JPEG-2000 you get a much smaller file than with 
+JPEG for the same image quality.
+.PP
+The second difference is that with JPEG-2000, you decide how much
+compression you want and the compressor adjusts the quality to meet your
+requirement, whereas with JPEG, you decide how much quality you want
+and the compressor adjusts the size of the output to meet your requirement.
+I.e. with JPEG-2000, the quality of the result depends on the compressibility
+of the input, but with JPEG, the \fIsize\fP of the result depends on
+the compressibility of the input.
+.PP
+With JPEG-2000, you can specify lossless compression, thus making it 
+compete with GIF and PNG.  With standard JPEG, you always lose something.
+(There are rumored to be variations of JPEG around that are lossless,
+though).
+.PP
+JPEG is much older than JPEG-2000 and far more popular.  JPEG is one of
+the half dozen most popular graphics formats and virtually all graphics
+facilities understand it.  JPEG-2000 is virtually unknown.
+.PP
+There is no compatibility between JPEG and JPEG-2000.  Programs that 
+read JPEG do not automatically read JPEG-2000 and vice versa.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "jpeg2ktopam" (1)\c
+\&,
+.BR "pnmtojpeg" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtojpeg2k\fP was added to Netpbm in Release 10.12 (November 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtojpeg2k.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtompfont.1 b/upstream/mageia-cauldron/man1/pamtompfont.1
new file mode 100644
index 00000000..ea181e54
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtompfont.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtompfont User Manual" 0 "18 May 2008" "netpbm documentation"
+
+.SH NAME
+pamtompfont - Convert Netpbm image to Mplayer bitmap font file
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamtompfont\fP
+[\fInetpbmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtompfont\fP reads a Netpbm image (PNM or PAM) and converts it
+to an Mplayer bitmap font raster file.
+.PP
+This is the original font format used by Mplayer (for subtitles,
+on-screen messages, etc.), before it had the ability to use Freetype
+to access standard fonts.
+.PP
+The format was apparently an image format before Mplayer adopted it
+for fonts, but I have no idea where it came from or where else it might
+be used.
+.PP
+An Mplayer bitmap font consists of a font descriptor file and
+raster files.  The font descriptor file identifies the raster files by
+file name.  A raster file contains a single rectangular raster image
+which contains an arrangement of a bunch of glyphs.  Each glyph is a
+rectangular image and the font descriptor indicates where in the image
+the glyph for each codepoint is.  Every glyph in the font has the same
+height, so the font descriptor just indicates the file position in the
+raster file of the to left corner of the glyph, and the width of the
+glyph in pixels.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamtompfont\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtompfont\fP was added to Netpbm in Release 10.43 (June 2008).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtompfont.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtopam.1 b/upstream/mageia-cauldron/man1/pamtopam.1
new file mode 100644
index 00000000..586185b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtopam.1
@@ -0,0 +1,76 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtopam User Manual" 0 "October 2007" "netpbm documentation"
+
+.SH NAME
+pamtopam - copy PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtopam\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtopam\fP simply copies a PAM image from Standard Input to
+Standard Output.  This may seem an unnecessary duplication of
+\fBcat\fP, but remember that a PAM program can read a PBM, PGM, or PPM
+image as if it were PAM.  So \fBpamtopam\fP can read either a PBM, PGM,
+PPM, or PAM image and produce a PAM image as output.
+.PP
+Even that is of limited usefulness because of the fact that almost
+any program to which you would feed the resulting PAM image could also
+just take the original image directly.  However, sometimes you really
+want a true PAM image.
+.PP
+You can do a more general job of translating PAM/PNM to PAM with
+\fBpamchannel\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamtopam\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopnm" (1)\c
+\&,
+.BR "ppmtoppm" (1)\c
+\&,
+.BR "pgmtopgm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.41 (December 2007).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtopdbimg.1 b/upstream/mageia-cauldron/man1/pamtopdbimg.1
new file mode 100644
index 00000000..0bb95cc7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtopdbimg.1
@@ -0,0 +1,117 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtopdbimg User Manual" 0 "12 March 2022" "netpbm documentation"
+
+.SH NAME
+pamtopdbimg - convert a Netpbm image to a Palm Pilot Image Viewer PDB Image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtopdbimg\fP
+
+[\fB-notefile=\fP\fIfilename\fP]
+[\fB-title=\fP\fItext\fP]
+[\fB-compressed\fP]
+[\fB-uncompressed\fP]
+[\fB-maybecompressed\fP]
+[\fB-4depth\fP]
+[\fB-fixedtime\fP]
+
+[\fInetpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtopdbimg\fP reads a Netpbm image as input and produced a Palm Pilot
+Image Viewer image (and Image record in a PDB file) as output.
+.PP
+If the Netpbm image is black and white, the Pilot image is monochrome.
+Otherwise, the Pilot image is either 4-level or 16-level grayscale, depending
+on the \fB-4depth\fP option.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtopdbimg\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-title=\fP\fItext\fP
+The title of the image, to be included in the image.
+
+.TP
+\fB-compressed\fP
+.TP
+\fB-uncompressed\fP
+.TP
+\fB-maybecompressed\fP
+You may specify only one of these.
+\fB-compressed\fP says to generate the image in compressed format.
+\fB-uncompressed\fP says to generate the image in uncompressed format.
+\fB-maybecompressed\fP says to generate whichever format is smaller
+(the compression algorithm sometimes actually makes the data larger).
+
+.TP
+\fB-4depth\fP
+This option makes \fBpamtopdbimg\fP create the image in 16-level
+grayscale (4 bits per pixel) format.  If you don't specify this,
+\fBpamtopdbimg\fP uses 4-level (2 bits per pixel) format.
+.sp
+This option has no effect when the input is black and white
+(maxval 1).  In that case, \fBpamtopdbimg\fP generates the monochrome
+(1 bit per pixel) format regardless.
+
+.TP
+\fB-notefile=\fP\fIfilename\fP
+Attach the note in the specified file to the image.
+.sp
+If you don't specify this, \fBpamtopdbimg\fP does not attach any note.
+
+.TP
+\fB-fixedtime\fP
+Fake the mtime and ctime vaues in the PDB image with a value that is the
+same every time you run the program.  This facilitates testing and
+verification because it means with the same input you always get the
+same output.
+.sp
+This option was new in Netpbm 10.98 (March 2022).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pdbimgtopam" (1)\c
+\&,
+.BR "palmtopnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtopdbimg\fP was new in Netpbm 10.52 (September 2010).
+It was modelled after Eric A. Howe's \fBimgvtopbm\fP package, which
+dates back to September 1997.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtopdbimg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtopfm.1 b/upstream/mageia-cauldron/man1/pamtopfm.1
new file mode 100644
index 00000000..263887be
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtopfm.1
@@ -0,0 +1,115 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtopfm User Manual" 0 "10 April 2004" "netpbm documentation"
+
+.SH NAME
+pamtopfm - Convert Netpbm image to PFM (Portable Float Map)
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamtopfm\fP
+[\fB-endian=\fP{\fBbig\fP|\fBlittle\fP}]
+[\fB-scale=\fP\fIfloat\fP]
+[\fIimagefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtopfm\fP reads a Netpbm image (PNM or PAM) and converts it
+to a PFM (Portable Float Map) image.
+.PP
+The PFM (Portable Float Map) image format is a lot like PPM, but uses
+floating point numbers with no maxval to achieve a High Dynamic Range
+(HDR) format.  That means it doesn't have a concept of absolute color
+and it can represent generic light intensity information rather than
+just visual information like PPM does.  For example, two pixels that
+are so close in intensity that the human eye cannot tell them apart
+are not visually distinct, so a visual image format such as PPM would
+have no reason to use different sample values for them.  But an HDR format
+would.
+.PP
+There are details of the PFM format in the
+.BR "PFM
+Format Description" (1)\c
+\&.
+.PP
+.UR https://vgl.ict.usc.edu/HDRShop/
+USC's HDRShop program
+.UE
+\& and a program called Lefty use it.
+
+\fBpamtopfm\fP creates a color PFM image if its input is RGB (PPM)
+and a non-color PFM otherwise.
+.PP
+Use
+.BR "\fBpfmtopam\fP" (1)\c
+\& to convert a PFM
+image to Netpbm format.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtopfm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-scale=\fP\fIfloat\fP
+.sp
+This specifies the scale factor of the PFM image.  
+     Scale factor is a component of the PFM format.
+     Default is 1.0.
+
+.TP
+\fB-endian=\fP{\fBbig\fP|\fBlittle\fP}
+.sp
+This specifies the endianness of the PFM image.  The samples
+     in the raster of a PFM image are 4 byte IEEE floating point
+     numbers.  A parameter of the IEEE format, and therefore the PFM
+     format, is endianness, i.e. whether the specified bytes are
+     ordered from low addresses to high addresses or vice versa.
+.sp
+\fBbig\fP means big endian -- the natural ordering;
+     \fBlittle\fP means little-endian, the Intel-friendly ordering.
+.sp
+Default is whichever endianness the machine on which \fBpamtopfm\fP
+     runs uses internally, which results in the faster execution.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "Netpbm" (1)\c
+\&,
+.BR "pfmtopam" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtopfm\fP was added to Netpbm in Release 10.22 (April 2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtopfm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtopng.1 b/upstream/mageia-cauldron/man1/pamtopng.1
new file mode 100644
index 00000000..5e2ec75f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtopng.1
@@ -0,0 +1,434 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtopng User Manual" 0 "13 March 2019" "netpbm documentation"
+
+.SH NAME
+pamtopng - convert a Netpbm image to PNG
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtopng\fP
+[\fB-verbose\fP]
+[\fB-transparent=\fP\fIcolor\fP]
+[\fB-background=\fP\fIcolor\fP]
+[\fB-gamma=\fP\fIvalue\fP]
+[\fB-chroma='\fP\fIwx\fP \fIwy\fP
+  \fIrx\fP \fIry\fP \fIgx\fP \fIgy\fP \fIbx\fP \fIby\fP\fB'\fP]
+[\fB-srgbintent=\fP\fIintent\fP]
+[\fB-time=\fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP
+  \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP]
+[\fB-text=\fP\fIfile\fP]
+[\fB-ztxt=\fP\fIfile\fP]
+[\fB-itxt=\fP\fIfile\fP]
+[\fB-interlace\fP]
+[\fIpnmfile\fP]
+
+.SH OPTION USAGE
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of a single hyphen to denote options.  You may use white space
+in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtopng\fP reads a Netpbm image as input and produces a PNG image as
+output.
+.PP
+Color component values in PNG files are either 8 or 16 bits wide, so where
+necessary \fBpamtopng\fP scales colors to have a maxval of 255 or 65535.
+In that case, it will add an sBIT chunk to indicated the original bit-depth.
+.PP
+\fBpamtopng\fP works only on images with maxval 1, 3, 15, 255, or 65535.
+You can use \fBpamdepth\fP to convert an image with some other maxval to one
+of these.
+.PP
+\fBpamtopng\fP produces a color PNG from a color PAM, even if the
+only colors in the image are shades of gray.  To create a graycale PNG,
+from such an image (which might be slightly smaller), you can use other
+Netpbm programs to convert the input to grayscale.
+
+.UN pnmtopng
+.SS Alternative: \fBpnmtopng\fP
+.PP
+Netpbm contains another program for generating PNG images: \fBpnmtopng\fP.
+\fBpnmtopng\fP is a much older program - it is in fact the first program in
+the world that could generate a PNG.  \fBpnmtopng\fP is a complex,
+feature-laden program.  It lets you control various arcane aspects of the
+conversion and create PNGs with various arcane features.  It does various
+transformations on the image to create the greatest compression possible, to a
+degree that probably doesn't make any difference in the modern world.
+.PP
+The main advantage \fBpamtopng\fP has over \fBpnmtopng\fP is that the
+former can use the transparency channel of a PAM image to generate the
+transparency information in the PNG.  In contrast, handling of the alpha
+channel is very cumbersome with \fBpnmotpng\fP.
+.PP
+One difference that \fIdoes not\fP exist, that some people might
+incorrectly infer from the names is the possible input formats.  Both programs
+can take PBM, PGM, PPM, and PAM input.
+.PP
+Because \fBpnmtopng\fP has been around virtually forever, programs and
+procedures that use it are more portable than those that use \fBpamtopng\fP.
+Its age and popularity also probably make it have fewer bugs.
+.PP
+\fBpamtopng\fP does not have any way to do what the following do in
+\fBpnmtopng\fP:
+
+
+.IP \(bu
+\fB-palette\fP
+.IP \(bu
+\fB-history\fP
+.IP \(bu
+\fB-filter\fP
+.IP \(bu
+\fB-size\fP
+.IP \(bu
+\fB-paeth\fP
+.IP \(bu
+\fB-hist\fP
+.IP \(bu
+\fB-nofilter\fP
+.IP \(bu
+\fB-sub\fP
+.IP \(bu
+\fB-up\fP
+.IP \(bu
+\fB-avg\fP
+.IP \(bu
+\fB-force\fP
+.IP \(bu
+\fB-libversion\fP
+.IP \(bu
+\fB-compression\fP
+.IP \(bu
+\fB-comp_\fP\fIxxx\fP
+
+.PP
+These are some of the other functions of \fBpnmtopng\fP that
+\fBpamtopng\fP lacks:
+
+
+.IP \(bu
+When you specify a transparent or background color that is not in the
+image, \fBpnmtopng\fP can optionally choose the closest one that is in the
+image.  \fBpamtopng\fP always uses the exact color you specify.
+
+.PP
+Features that exist in both programs are controlled by largely the same
+command syntax.  But there are these differences:
+
+
+.IP \(bu
+\fBpnmtopng\fP's \fB-rgb\fP option is \fB-chroma\fP in \fBpamtopng\fP.
+\fB-chroma\fP is a better name, and in fact was the name that \fBpnmtopng\fP
+used originally, but we had to change it when we had to change the syntax
+of the option value to conform to the rest of Netpbm.
+
+.IP \(bu
+\fBpnmtopng\fP's \fB-modtime\fP option is \fB-time\fP in
+\fBpamtopng\fP.  The origin of \fB-modtime\fP is analogous to that of
+\fB-rgb\fP.
+
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtopng\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-transparent=\fP\fIcolor\fP
+\fBpamtopng\fP marks the specified color as transparent in the PNG image --
+Every pixel of this color is fully transparent.  This causes \fBpamtopng\fP to
+include a tRNS chunk in the image identifying that color.
+.sp
+Specify the color (\fIcolor\fP) as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.  E.g. \fBred\fP or \fBrgb:ff/00/0d\fP.
+
+.TP
+\fB-background=\fP\fIcolor\fP
+This causes \fBpamtopng\fP to create a background color chunk in the PNG
+output which can be used for subsequent transparency channel or transparent
+color conversions.  Specify \fIcolor\fP the same as for \fB-transparent\fP.
+.sp
+\ 
+
+.TP
+\fB-gamma=\fP\fIvalue\fP
+This causes \fBpamtopng\fP to create a gAMA chunk.  This information
+helps describe how the color values in the PNG must be interpreted.  Without
+the gAMA chunk, whatever interprets the PNG must get this information
+separately (or just assume something standard).  If your input is a true PPM
+or PGM image, you should specify \fB-gamma=.45\fP.  But sometimes people
+generate images which are ostensibly PPM except the image uses a different
+gamma transfer function than the one specified for PPM.  A common case of this
+is when the image is created by simple hardware that doesn't have digital
+computational ability.  Also, some simple programs that generate images from
+scratch do it with a gamma transfer in which the gamma value is 1.0.
+.sp
+\ 
+  
+.TP
+\fB-chroma=\fP\fIchroma_list\fP
+This option specifies how red, green, and blue component values
+of a pixel specify a particular color, by telling the chromaticities
+of those 3 primary illuminants and of white (i.e. full strength of
+all three).
+.sp
+The \fIchroma_list\fP value is a blank-separated list of 8 floating
+point decimal numbers.  The CIE-1931 X and Y chromaticities (in that
+order) of each of white, red, green, and blue, in that order.
+.sp
+This information goes into the PNG's cHRM chunk.
+.sp
+In a shell command, make sure you use quotation marks so that the
+blanks in \fIchroma_list\fP don't make the shell see multiple command
+arguments.
+
+.TP
+\fB-srgbintent=\fP\fIintent\fP
+This asserts that the input is a pseudo-Netpbm image that uses an
+sRGB color space (unlike true Netpbm) and indicates how you intend for the
+colors to be rendered.  It causes \fBpamtopng\fP to include an sRGB chunk
+in the PNG image that specifies that intent, so see the PNG documentation for
+more information on what this really means.
+.sp
+\fIintent\fP is one of:
+
+
+.IP \(bu
+\fBperceptual\fP  
+.IP \(bu
+\fBrelativecolorimetric\fP  
+.IP \(bu
+\fBsaturation\fP  
+.IP \(bu
+\fBabsolutecolorimetric\fP  
+
+
+.TP
+\fB-text=\fP\fIfilename\fP
+This option lets you include arbitrary text strings in the PNG output, as tEXt
+chunks.
+
+\fIfilename\fP is the name of a file that contains your text strings.
+.sp
+The output contains a distinct tEXt chunk for each entry in the file.
+.sp
+Here is an example of a text string file:
+
+.nf
+	Title           PNG file
+	Author          John Doe
+	Description     how to include a text chunk
+                        PNG file
+	"Creation Date" 2015-may-11
+	Software        pamtopng
+
+.fi
+.sp
+The file is divided into entries, each entry comprising consecutive lines
+of text.  The first line of an entry starts in the first column (i.e. the
+first column is not white space) and every other line has white space in the
+first column.  The first entry starts in the first line, so it is not valid
+for the first line of the file to have white space in its first column.
+.sp
+The first word in an entry is the key of the text string
+(e.g. 'Title').  It begins in column one of the line and continues
+up to, but not including, the first delimiter character or the end of the
+line, whichever is first.  You can enclose the key in double quotes in
+which case the key can consists of multiple words.  The quotes are not
+part of the key.  The text string per se begins after the key and any
+delimiter characters after it, plus the text in subsequent continuation lines.
+.sp
+There is no limit on the length of a file line or entry or key or text
+string.  There is no limit on the number of entries.
+
+.TP
+\fB-ztxt=\fP\fIfilename\fP
+The same as \fB-text\fP, except the text string is compressed in the
+PNG output.  \fBpamtopng\fP uses zTXt chunks instead of a tEXt chunks.
+.sp
+\ 
+
+.TP
+\fB-itxt=\fP\fIfilename\fP
+Similar to \fB-text\fP, but the text strings can be in a language other
+than English.  The PNG image indicates what language that is and includes the
+text string key both in English and that language.  \fBpamtopng\fP uses
+iTXt chunks instead of tEXt chunks.
+.sp
+For each record, you must specify the language and give the key both in
+English and in the text string language.
+.sp
+Example:
+
+.nf
+	Language        nl-NL  Taal             nl-NL
+        Title           nl-NL  Titel            PNG file
+        Author          nl-NL  Auteur           Pietje Puk
+        Description     nl-NL  Omschrijving     Tekst in het Nederlands.
+
+.fi
+.sp
+The language specification is based on the ISO 639-1 standard, see
+http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the valid codes.
+The format is either a two character "nl" or an extended code like "en-US".
+
+.TP
+\fB-time='\fP[\fIyy\fP]\fIyy-mm-dd hh:mm:ss\fP\fB'\fP 
+This option allows you to specify the modification time value to be placed
+in the PNG output.  You can specify the year parameter either as a two or four
+digit value.
+.sp
+\ 
+    
+.TP
+\fB-interlace\fP
+This causes the PNG file to be interlaced, in Adam7 format.  The interlaced
+format is one in which the raster data starts with a low-resolution
+representation of the entire image, then continues with additional information
+for the entire image, then even more information, etc.  In Adam7 in
+particular, there are seven such passes of the whole image.  This is useful
+when you are receiving the image over a slow communication line as someone is
+waiting to see it.  The simplest thing to do in that case is wait for the
+entire image to arrive and then display it instantly, but then the user is
+wasting time staring at a blank space until the whole image arrives.  With the
+standard non-interlaced format, the data arrives row-by-row starting at the
+top, so the displayer could display each row of the image as it arrives and
+gradually paint down to the bottom.  But with an interlaced image, the
+displayer can start by showing a low-resolution version of the image, then
+gradually improve the display as more data arrives.
+.sp
+When you specify this option, \fBpamtopng\fP must hold the entire image in
+memory at once, whereas without it, the program holds only one raster row at a
+time.  If you don't have enough memory for that, you might suffer extreme
+slowdowns or failure - not just in the process running \fBpamtopng\fP, but
+potentially throughout the system that shares memory with it.  \fBpnmtopng\fP
+does not have this limitation (it holds only one row at a time in memory even
+when generating an interlaced PNG).
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+  
+.TP
+\fB-verbose\fP
+This causes the program to display various facts about the conversion.
+.sp
+\ 
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pngtopam" (1)\c
+\&,
+.BR "pnmtopng" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.PP
+For information on the PNG format, see
+.UR http://www.w3.org/TR/PNG/
+http://www.w3.org/TR/PNG/
+.UE
+\&,
+.UR http://libpng.org/pub/png/
+http://libpng.org/pub/png/
+.UE
+\&,
+.UR http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+.UE
+\& and
+.UR http://schaik.com/png/
+http://schaik.com/png/
+.UE
+\&.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtopng\fP was new in Netpbm 10.70 (June 2015).
+.PP
+Before \fBpamtopng\fP, the two ways to create PNG images with Netpbm
+were \fBpnmtopng\fP and \fBpamrgbatopng\fP.  The history of the former is
+discussed above.  The latter was added to Netpbm in 2005 as a cheap way to
+fill a significant need that \fBpnmtopng\fP did not: the ability to turn the
+alpha channel in a PAM image into the alpha channel in a PNG image.
+.PP
+Handling of the alpha channel with \fBpnmtopng\fP is very cumbersome (as
+was dealing with alpha channels in general before the introduction of the PAM
+format).  \fBpamrgbatopng\fP could do what people wanted with the alpha
+channel, but nothing else.  It was a very small program with literally no
+command line options.
+.PP
+The goal in those days was eventually to expand \fBpnmtopng\fP to do the
+PAM alpha channel thing, rename it to \fBpamtopng\fP, and retire
+\fBpamrgbatopng\fP.  But \fBpnmtopng\fP is such a complex program, because
+of its dizzying array of features and its need for backward compatibility,
+that adding that one capability to it was a daunting task and for ten years
+nobody attempted it.
+.PP
+In 2015, one of the authors of the original \fBpnmtopng\fP (from before it
+was even part of Netpbm -- a program that shared essentially no lines of code
+with \fBpnmtopng\fP of 2015) decided to go in a different direction.  While
+many features of \fBpnmtopng\fP were pretty important and easy to implement,
+many others were probably of no use in the modern world or at least not
+important enough to justify the complexity they lent to the code.  (The
+features thought to be outdated were ones that were intended to make the PNG
+output slightly smaller - something considerably less important with the
+declining cost of computer resources).  
+.PP
+And there was an opportunity to drop those features: We could use the new
+name 'pamtopng' for a new program, keep the existing program under
+the name 'pnmtopng', and avoid most backward compatibility trouble.
+.PP
+Therefore, Willem van Schaik wrote an intermediate level program that had
+all the most important features of \fBpnmtopng\fP, plus the alpha channel
+handling of \fBpamrgbatopng\fP, with nice, simple code.  That was
+\fBpamtopng\fP.
+.PP
+Because \fBpamrgbatopng\fP had no options, \fBpamtopng\fP was backward
+compatible with it without even trying.  Therefore, as soon as we
+added \fBpamtopng\fP to Netpbm, we removed \fBpamrgbatopng\fP and
+recommended that \fBpamrgbatopng\fP be installed as an alias for
+\fBpamtopng\fP.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
+Copyright (C) 2015 by Willem van Schaik.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtopng.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtopnm.1 b/upstream/mageia-cauldron/man1/pamtopnm.1
new file mode 100644
index 00000000..3698ae3b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtopnm.1
@@ -0,0 +1,126 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtopnm User Manual" 0 "02 February 2018" "netpbm documentation"
+
+.SH NAME
+pamtopnm - convert PAM image to PBM, PGM, or PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtopnm\fP
+
+[\fB-assume\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtopnm\fP reads a PAM image as input and produces an
+equivalent PBM, PGM, or PPM (i.e. PNM) image, whichever is most
+appropriate, as output.
+.PP
+\fBpamtopnm\fP assumes the PAM image represents the information
+required for a PBM, PGM, or PPM image if its tuple type is
+"BLACKANDWHITE", "GRAYSCALE", or "RGB"
+and its depth and maxval are appropriate.  If this is not the case,
+\fBpamtopnm\fP fails.
+.PP
+However, you can override the tuple type requirement with the
+\fB-assume\fP option.
+.PP
+\fBpamtopnm\fP produces a PPM image if the input PAM has depth 3 or 4; it
+produces PGM or PBM if the input PAM has depth 1 or 2.  Whether it produced
+PGM or PBM depends upon the maxval: PBM for 1, PGM for anything higher.  The
+tuple type does not play a role in determining the output type.  You can
+use Netpbm programs such as \fBpgmtopgm\fP to generate a different PNM
+output, but remember that Netpbm program that expects PGM input will take
+PBM and so on.
+.PP
+Note that it's possible for an image which is formally color to in fact
+contain only shades of gray and for an image which is formally grayscale to
+contain only black and white.  This program pays no attention to that; an RGB
+input image produces a PPM output image even if all the pixels are gray.  But
+you can use \fBppmtopgm\fP to convert a PPM that you know is grayscale to the
+equivalent PGM, and you can use \fBpamthreshold\fP to convert a PGM image you
+know is black and white to a black and white PAM image and then
+use \fBpamtopnm\fP to convert that to PBM.
+  
+.PP
+As with any Netpbm program that reads PAM images, \fBpamtopnm\fP
+also reads PNM images as if they were PAM.  In that case,
+\fBpamtopnm\fP's functions reduces to simply copying the input to the
+output.  But this can be useful in a program that doesn't know whether
+its input is PAM or PNM but needs to feed it to a program that only
+recognizes PNM.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtopnm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-assume\fP
+When you specify \fB-assume\fP, you tell \fBpamtopnm\fP that you
+personally vouch for the fact that the tuples contain the same data as
+belongs in the channels of a PBM, PGM, or PPM file.  The depth must
+still conform, though, so to truly force a conversion, you may have to
+run the input through \fBpamchannel\fP first.  But be careful with
+\fB-assume\fP.  When you -assume, you make an -ass of u and me.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtopgm" (1)\c
+\&,
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pgmtoppm" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "pamthreshold" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtopnm\fP was new, along with the PAM format, in Netpbm
+9.7 (August 2000).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtoqoi.1 b/upstream/mageia-cauldron/man1/pamtoqoi.1
new file mode 100644
index 00000000..ad340978
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtoqoi.1
@@ -0,0 +1,75 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtoqoi User Manual" 0 "21 May 2022" "netpbm documentation"
+
+.SH NAME
+pamtoqoi - Convert Netpbm image to QOI format (Quite OK Image format)
+
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamtoqoi\fP
+[\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtoqoi\fP reads a Netpbm image from standard input and converts it to
+a QOI image written to standard output.
+.PP
+For the QOI specification and details, see
+.UR http://qoiformat.org
+the QOI web site
+.UE
+\&.
+.PP
+Use
+.BR "\fBqoitopam\fP" (1)\c
+\& to convert a QOI
+image to Netpbm format.
+.PP
+Input is from Standard Input if you don't specify the input file
+\fIpnmfile\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+The only options are those common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "qoitopam" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtoqoi\fP was new in Netpbm 10.99 (June 2022).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtoqoi.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtosrf.1 b/upstream/mageia-cauldron/man1/pamtosrf.1
new file mode 100644
index 00000000..c2449343
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtosrf.1
@@ -0,0 +1,101 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtosrf User Manual" 0 "27 May 2011" "netpbm documentation"
+
+.SH NAME
+pamtosrf - convert a sequence of Netpbm images to a SRF image file
+
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpamtosrf\fP
+[\fB-verbose\fP]
+[\fInetpbmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtosrf\fP reads a Netpbm image stream as input and produces a
+an SRF image file as output.  I don't know exactly what SRF is, but on popular
+use of it is in Garmin vehicle information files, which tell a GPS receiver
+how to depict a vehicle on its display.
+.PP
+An SRF file can contain multiple images; each image in a multi-image
+Netpbm input stream becomes one image in the SRF.
+.PP
+\fBpamtosrf\fP does not care how many images there are or what their
+dimensions or content are.  However, a Garmin vehicle information file has
+specific requirements, so if you don't make your Netpbm input conform, neither
+will your SRF output.  For such a file, you should have two image: the first
+for 3D oblique views of the vehicle and the second for overhead views.  Each
+image is a horizontal concatenation of 36 square images, each rotated 10
+degrees from the previous, thereby covering the full 360 degree circle.
+You could create this concatenation with \fBpnmcat -lr\fP and you could
+create the invidual views with \fBpnmrotate\fP.
+.PP
+One way to use \fBpamtosrf\fP is to get an SRF file, convert it to PAM
+with \fBsrftopam\fP, manipulate it, then convert it back with
+\fBpamtosrf\fP.
+.PP
+\fInetpbmfile\fP is the input stream, which defaults to Standard Input.
+Output is always on Standard Output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtosrf\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-verbose\fP
+Issue informational messages about the input and the conversion process.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "srftopam" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmcat" (1)\c
+\&
+.IP \(bu
+
+.BR "pam" (1)\c
+\&
+  
+
+.UN history
+.SH HISTORY
+.PP
+\fBsrftopam\fP was new in Netpbm 10.55 (June 2011).
+.PP
+It was contributed by Mike Frysinger.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtosrf.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtosvg.1 b/upstream/mageia-cauldron/man1/pamtosvg.1
new file mode 100644
index 00000000..59e50d1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtosvg.1
@@ -0,0 +1,238 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtosvg User Manual" 0 "23 April 2006" "netpbm documentation"
+
+.SH NAME
+pamtosvg - convert a Netpbm image to a SVG (Scalable Vector Graphics) image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtosvg\fP
+
+[\fB-background-color=\fP\fIcolorname\fP]
+[\fB-centerline\fP]
+[\fB-corner-threshold=\fP\fIangle\fP]
+[\fB-corner-always-threshold=\fP\fIangle\fP]
+[\fB-corner-surround=\fP\fIinteger\fP]
+[\fB-tangent-surround=\fP\fIinteger\fP]
+[\fB-error-threshold=\fP\fIfloat\fP]
+[\fB-filter-iterations=\fP\fIcount\fP]
+[\fB-line-reversion-threshold=\fP\fIfloat\fP]
+[\fB-line-threshold=\fP\fIfloat\fP]
+[\fB-width-weight-factor=\fP\fIfloat\fP]
+[\fB-preserve-width\fP]
+[\fB-remove-adjacent-corners\fP]
+[\fB-log\fP]
+[\fB-report-progress\fP] [\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtosvg\fP reads a PNM image as input and produce an SVG
+(Scalable Vector Graphics) image as output.  Thus, it traces curves
+in the input image and creates a set of splines that represent the
+image.
+.PP
+SVG is a vector image format, which means it describes curves that
+compose an image.  By contrast, PNM is a raster format, which means it
+describes dots that compose an image.  The main practical difference
+between the two types is that you can scale vector images better.  A
+vector image also takes a lot less data to describe an image if the
+image is composed of simple curves.
+.PP
+That means it is really an understatement to say that \fBpamtosvg\fP
+is an image format converter.  It's really an image tracer.  Its main job
+is to trace a raster image and find the lines in it.  It then represents
+its findings in SVG format.
+.PP
+\fBpamtosvg\fP does the same kind of thing that StreamLine,
+CorelTrace, and Autotrace do.  It is in fact derived from Autotrace.
+.PP
+SVG is a gigantic format, capable of amazing things.  \fBpamtosvg\fP
+exploits only a morsel of it.  The SVG image produced by \fBpamtosvg\fP
+consists of a single <svg> element, which has a "width"
+attribute and a "height" attribute.  The value of that element
+is composed of <path> elements.  That's it.
+.PP
+In the SVG output, distances are unitless, with one unit corresponding
+to one pixel of the input.
+.PP
+So that \fBpamtosvg\fP will find simple curves in the image, you
+may want to remove speckles from it with \fBpbmclean\fP and consolidate
+multiple shades into single colors with \fBpnmquant\fP first.
+.PP
+For more information on SVG, see 
+.UR http://www.w3.org/Graphics/SVG/
+the Worldwide Web Consortium's SVG web page
+.UE
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtosvg\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-background-color=\fP\fIcolorname\fP
+Treat the specified color as the background color and ignore it.
+.sp
+If you don't specify this option, \fBpamtosvg\fP does not recognize
+any background color.
+.sp
+Specify the color (\fIcolorname\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+.TP
+\fB-centerline\fP
+Trace an object's centerline.
+.sp
+By default, \fBpamtosvg\fP traces an object's outline.
+
+.TP
+\fB-corner-always-threshold=\fP\fIangle\fP
+Consider any angle at a pixel which falls below angle \fIangle\fP
+(in decimal floating point degrees) as a corner, even if it is
+bordered by other corner pixels.  Default is 60 degrees.
+
+.TP
+\fB-corner-surround=\fP\fIinteger\fP
+Consider the specified number of pixels on either side of a
+point when determining if that point is a corner.  Default is 4.
+
+.TP
+\fB-corner-threshold=\fP\fIangle\fP
+Consider any pixel which forms an angle with its predecessors and
+successors that is smaller than \fIangle\fP (in decimal floating
+point degrees) as a corner.  Default is 100.
+
+.TP
+\fB-error-threshold=\fP\fIfloat\fP
+Subdivide fitted curves that are offset by a number of pixels
+exceeding the specified number.  Default is 2.0.
+
+.TP
+\fB-filter-iterations=\fP\fIinteger\fP
+Smooth the curve the specified number of times prior to fitting
+Default is 4.
+
+.TP
+\fB-line-reversion-threshold=\fP\fIfloat\fP
+When a spline is closer to a straight line than the specified real
+number weighted by the square of the curve length, maintain it as a
+straight line, even if it is a list with curves.
+.sp
+Default is .01.
+
+.TP
+\fB-line-threshold=\fP\fIfloat\fP
+If a spline does not deviate from the straight line defined by its
+endpoints by more than the specified number of pixels, then treat it
+as a straight line.
+.sp
+Default is 1.
+
+.TP
+\fB-log\fP
+Create a log of the curve tracing process (suitable for
+debugging).  Put it in the file named \fIinputfile\fP\fB.log\fP in
+the current directory, where \fIinputfile\fP is the root of the input
+file name, or "pamtosvg" if the input is from Standard Input
+or a file with a weird name.
+
+.TP
+\fB-preserve-width\fP
+Preserve line width prior to thinning.  Meaningful only with
+\fB-centerline\fP.
+
+.TP
+\fBremove-adjacent-corners\fP
+Remove adjacent corners.
+
+.TP
+\fB-report-progress\fP
+Report the progress of the tracing to Standard Error as it happens.
+
+.TP
+\fB-tangent-surround\fP
+Consider the specified number of points to either side of a point
+when computing the tangent at that point.  Default is 3.
+
+.TP
+\fB-width-weight-factor\fP
+Weight factor for fitting the linewidth.
+
+
+
+.UN applicationnotes
+.SH APPLICATION NOTES
+.PP
+A convenient way to view an SVG document is with a web browser.  Many
+understand a file whose name ends in ".svg" to be an SVG
+image and can render it.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmquant" (1)\c
+\&,
+.BR "pbmclean" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.UR http://autotrace.sourceforge.net
+Autotrace
+.UE
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtosvg\fP was added to Netpbm in Version 10.33 (March 2006).
+.PP
+The core of \fBpamtosvg\fP -- the curve tracing logic -- was taken
+nearly unmodified from Martin Weber's Autotrace program.  That program
+duplicates a lot of Netpbm function, so \fBpamtosvg\fP is a much leaner
+program.
+.PP
+Bryan Henderson created \fBpamtosvg\fP, basically just by adapting
+Autotrace to Netpbm.
+.PP
+Autotrace was first released in 2000 and updates were released
+through 2002.  A number of people wrote the code in it, but Masatake
+Yamato and Martin Weber appear to be the principal creators of it.
+.PP
+As of June 2006, there was a 
+.UR http://autotrace.sourceforge.net
+Sourceforge project
+.UE
+\& for it.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtosvg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtotga.1 b/upstream/mageia-cauldron/man1/pamtotga.1
new file mode 100644
index 00000000..36add1d1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtotga.1
@@ -0,0 +1,169 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtotga User Manual" 0 "06 November 2018" "netpbm documentation"
+
+.SH NAME
+pamtotga - convert a Netpbm image to a TrueVision Targa file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtotga\fP
+[\fB-mono|-cmap|-cmap16|-rgb\fP]
+[\fB-norle\fP]
+[\fB-name=\fP\fIname\fP
+[\fB-verhose\fP]
+[\fIpamfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtotga\fP reads a PBM, PGM, PPM, or PAM image as input and
+produces a TrueVision Targa file as output.  The PAM image may be
+either a BLACKANDWHITE, GRAYSCALE, RGB, or RGB_ALPHA image.
+.PP
+To create a TGA image with transparency (i.e. with a transparency mask),
+use RGB_ALPHA PAM input.  Some Netpbm programs that generate images with
+transparency masks generate them in that format.  For another way to create
+the proper input stream, see
+.BR "\fBpamstack\fP" (1)\c
+\&.
+.PP
+It is unclear that anything except \fBpamtotga\fP knows about TGAs
+with transparency.  The history behind this feature of \fBpamtotga\fP
+is not clear.  The format \fBpamtotga\fP produces is simply the same
+as an ordinary RGB TGA image except with a 4th plane added for
+transparency.  The PixelSize field of the TGA header specifies 32 bits
+instead of 24 and the raster has an extra byte added to each pixel, at
+the tail end.  The value of that byte has the same meaning as in a PAM
+image with maxval 255.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtotga\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-cmap\fP
+Make output Targa file use a color map (palette) to make the output smaller.
+.sp
+Each color in the color map is 3 bytes, 8 bits each of red, green, and blue,
+unless the input is black and white or grayscale, in which case each color in
+the palette is represented by one byte.
+.sp
+Input must contain no more than 256 distinct colors and must not contain
+transparency information.
+.sp
+(The transparency limitation is not a limitation of the format, but
+of \fBpamtotga\fP.  Implementing a color map that contains transparency
+information is harder to implement).
+
+.TP
+\fB-cmap16\fP
+Same as \fB-cmap\fP, except a color map entry for full color input is 5
+bits each of red, green, and blue, stored as two bytes (16 bits).
+.sp
+Restrictions are the same as for \fB-cmap\fP.
+.sp
+This option was new in Netpbm 10.85 (December 2018).
+    
+.TP
+\fB-mono\fP
+Make output Targa file of type 8 bit monochrome.  Input must be PBM or PGM
+or a PAM with BLACKANDWHITE or GRAYSCALE tuple type.
+See \fB-cmap\fP.
+.sp
+You may specify at most one of \fB-mono\fP, \fB-cmap\fP, and
+\fB-rgb\fP.  If you specify neither, the default image type is the
+most highly constrained compatible type is used, where monochrome is
+more constrained than colormapped which is in turn more constrained
+than unmapped.
+
+.TP
+\fB-rgb\fP
+Make output Targa file of type 24 bit unmapped color.  See \fB-cmap\fP.
+
+.TP
+\fB-norle\fP
+Do not use run-length encoding in the output Targa file.
+Run-length encoded files are smaller, but Some Targa readers can't
+read run-length encoded files.
+
+.TP
+\fB-name=\fP\fIname\fP
+This is the value for the image ID stated in the header of the TGA
+output file.  \fBpamtotga\fP truncates it as necessary to meet TGA
+standards.
+.sp
+By default, \fBpamtotga\fP uses the input file name argument, up to
+the first period (or the whole thing if there is no period).  It truncates
+it as necessary to meet TGA standards.  If you specify (or default to)
+Standard Input, \fBpamtotga\fP omits the image ID from the TGA header.
+
+.TP
+\fB-verbose\fP
+This causes \fBpamtotga\fP to issues messages about the conversion
+process.
+
+      
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "tgatoppm" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pamstack" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+This program was called \fBppmtotga\fP until Netpbm 10.6 (July 2002).
+That was always a misnomer, though, because a PPM class program would not be
+able to tell the difference between PGM and PPM input (it would all look like
+PPM), and thus could not choose the output Targa image type based on the type
+of the input.  Netpbm 10.6 also added the ability to handle a transparency
+channel, so it became a PAM class program.
+.PP
+In Netpbm 10.15 (April 2003), the program became the first in the
+Netpbm package to recognize a transparency channel in a PAM.  It recognized
+tuple type "RGBA".  But when this kind of PAM image was later
+added to the PAM specification, it was specified with tuple type
+"RGB_ALPHA".  So in Netpbm 10.26 (January 2005), \fBpamtotga\fP
+changed to recognize "RGB_ALPHA" instead of "RGBA".
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Mark Shand and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtotga.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtotiff.1 b/upstream/mageia-cauldron/man1/pamtotiff.1
new file mode 100644
index 00000000..9d6c1536
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtotiff.1
@@ -0,0 +1,622 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtotiff User Manual" 0 "05 April 2017" "netpbm documentation"
+
+.SH NAME
+pamtotiff - convert a Netpbm image to a TIFF file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtotiff\fP
+
+[\fB-none\fP | \fB-packbits\fP | \fB-lzw\fP | \fB-g3\fP | \fB-g4\fP
+| \fB-flate\fP | \fB-adobeflate\fP]
+
+[\fB-2d\fP]
+
+[\fB-fill\fP]
+
+[\fB-predictor=\fP\fIn\fP]
+
+[\fB-msb2lsb\fP|\fB-lsb2msb\fP]
+
+[\fB-rowsperstrip=\fP\fIn\fP]
+
+[\fB-minisblack\fP|\fB-miniswhite\fP|\fBmb\fP|\fBmw\fP]
+
+[\fB-truecolor\fP]
+
+[\fB-color\fP]
+
+[\fB-indexbits=\fP\fIbitwidthlist\fP]
+[\fB-xresolution=\fP\fIxres\fP]
+
+[\fB-yresolution=\fP\fIyres\fP]
+[\fB-resolutionunit=\fP{\fBinch\fP | \fBcentimeter\fP | \fBnone\fP |
+\fBin\fP | \fBcm\fP | \fBno\fP}]
+
+[\fB-append\fP]
+
+[\fB-tag=\fP\fItaglist\fP]
+
+[\fIpamfile\fP]
+.PP
+You can use the minimum unique abbreviation of the options.  You
+can use two hyphens instead of one.  You can separate an option name
+from its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtotiff\fP reads a PNM or PAM image as input and produces a TIFF file
+as output.
+.PP
+Actually, it handles multi-image Netpbm streams, producing multi-image
+TIFF streams (i.e. a TIFF stream with multiple
+"directories").  But before Netpbm 10.27 (March 2005), it
+ignored all but the first Netpbm image in the input stream.
+
+.UN output
+.SS The Output File
+.PP
+By default, the output goes to Standard Output.  Alternatively, you can
+specify an output file with the \fB-output\fP option and \fBpamtotiff\fP
+will write its output directly to that file.
+.PP
+Because of the way the TIFF library (which \fBpamtotiff\fP uses) works,
+when the program writes to Standard Output, it generates the entire TIFF image
+in a temporary file and then copies it to Standard Output; you may see
+negative performance effects of this.
+.PP
+The \fB-output\fP method avoids the performance effects of the copy
+through the temporary file, but there are restrictions on the output file: it
+must be seekable and it must be readable.  The program fails if it is not.
+With Standard Output, neither of those restrictions applies.
+.PP
+With \fB-output\fP, if the file already exists and has data in it,
+\fBpamtotiff\fP appends the image to the existing TIFF file.  (A TIFF file
+may contain multiple images).
+.PP
+By default, \fBpamtotiff\fP creates the file named by \fB-output\fP if it
+does not already exist.  But if you also specify \fB-append\fP, the program
+fails if the file named by \fB-output\fP does not already exist.
+.PP
+Before Netpbm 10.67 (June 2014), there is no \fB-output\fP option and
+Standard Output must be seekable.  So pipes are out.
+.PP
+Before Netpbm 10.67 (June 2014), you could append to Standard Output.  See
+below.  The current program does not have the ability; you must
+use \fB-output\fP to append to an existing TIFF file.
+.PP
+The difference above means current \fBpamtotiff\fP is actually not
+backward compatible, which is a rare thing for Netpbm.  But it's a good thing
+because the previous function was very strange and probably hardly ever
+exploited.
+
+
+.UN oldoutput
+.B Old Versions
+.PP
+As alluded to above, \fBpamtotiff\fP does output very differently
+in releases before 10.67.  The following describes the old function,
+which is unusual both for Netpbm and for Unix programs in general.
+
+
+.IP \(bu
+The output file must be seekable.  \fBpamtotiff\fP does not
+write it sequentially.  Therefore, you can't use a pipe; you can't
+pipe the output of \fBpamtotiff\fP to some other program.  But any
+regular file should work.
+
+.IP \(bu
+If the output file descriptor is readable, you must either specify
+\fB-append\fP so as to add to the existing file, or make sure the
+file is empty.  Otherwise, \fBpamtotiff\fP will fail with an
+unhelpful message telling you that a TIFF library function failed to
+open the TIFF output stream.
+
+.IP \(bu
+If you are converting multiple images (your input stream contains
+multiple images), the output file must be both readable and writable.
+
+
+.PP
+If you're using a Unix command shell to run \fBpamtotiff\fP, you
+use facilities of your shell to set up Standard Output.  In Bash,
+for example, you would set up a write-only Standard Output to the
+file /tmp/myimage.tiff like this:
+
+.nf
+\f(CW
+    $ pamtotiff myimage.pnm >/tmp/myimage.tiff
+\fP
+
+.fi
+
+In Bash, you would set up a read/write Standard Output to the file
+/tmp/myimage.tiff like this:
+
+.nf
+\f(CW
+    $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
+\fP
+
+.fi
+
+.UN library
+.SS TIFF Capability
+.PP
+\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever
+equivalent you provide) to generate the TIFF output.  Details of the
+format it produces are therefore controlled by that library.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtotiff\fP recognizes the following
+command line options:
+
+.UN compression
+.SS Compression
+.PP
+By default, \fBpamtotiff\fP creates a TIFF file with no
+compression.  This is your best bet most of the time.  If you want to
+try another compression scheme or tweak some of the other even more
+obscure output options, there are a number of options which to
+play.
+.PP
+Before Netpbm 8.4 (April 2000), the default was to use LZW compression.
+But then new releases of the TIFF library started omitting the LZW
+compression capability because of concern about patents on LZW.  So
+since then, the default has been no compression.  The LZW patents have
+now expired and new TIFF libraries do LZW, but the \fBpamtotiff\fP
+behavior remains the same for compatibility with older TIFF libraries
+and applications of \fBpamtotiff\fP.
+.PP
+The \fB-none\fP, \fB-packbits\fP, \fB-lzw\fP, \fB-g3\fP,
+\fB-g4\fP, \fB-flate\fP, and \fB-adobeflate\fP options are used to
+override the default and set the compression scheme used in creating
+the output file.
+
+The \fB-predictor\fP option is meaningful only with LZW compression: a
+predictor value of 2 causes each scanline of the output image to undergo
+horizontal differencing before it is encoded; a value of 1 forces each
+scanline to be encoded without differencing.  By default, \fBpamtotiff\fP
+creates a TIFF file with msb-to-lsb fill order.  The \fB-msb2lsb\fP and
+\fB-lsb2msb\fP options are used to override the default and set the fill
+order used in creating the file.
+.PP
+With some older TIFF libraries, \fB-lzw\fP doesn't work because
+the TIFF library doesn't do LZW compression.  This is because of
+concerns about Unisys's patent on LZW which was then in force.
+Actually, with very old TIFF libraries, \fB-lzw\fP works because no
+distributors of the TIFF library were sensitive yet to the patent
+issue.
+.PP
+\fB-flate\fP chooses "flate" compression, which is the
+patent-free compression common in the Unix world implemented by the 
+"Z" library.  It is what the PNG format uses.
+
+.UN faxcompression
+.B Fax Compression
+.PP
+If you have bilevel data (e.g. PBM), you can generate a TIFF that uses the
+same compression scheme specified for use by fax machines.  See the
+.BR "Fax Format" (1)\c
+\& page for more information on these
+compression schemes.
+.PP
+These formats all relate to ITU Group 3 and Group 4 fax machine
+standards.
+.PP
+The \fB-g3\fP option chooses MH or MR compression: MR with the additional
+option \fB-2d\fP; MH without it.  \fB-g4\fP selects MMR.  The option names
+are a little unfortunate and historical, but are consistent with the TIFF
+specification.
+.PP
+MMR has a better compression ratio than the other two.
+.PP
+\fB-fill\fP specifies that for MH or MR compression, each encoded scanline
+shall be zero-filled to a byte boundary.
+.PP
+\fB-2d\fP and \fB-fill\fP are meaningful only with \fB-g3\fP.
+
+
+.UN fillorder
+.SS Fill Order
+.PP
+The \fB-msb2lsb\fP and \fBlsb2msb\fP options control the fill order.
+.PP
+The fill order is the order in which pixels are packed into a byte in
+the Tiff raster, in the case that there are multiple pixels per byte.
+msb-to-lsb means that the leftmost columns go into the most
+significant bits of the byte in the Tiff image.  However, there is
+considerable confusion about the meaning of fill order.  Some believe
+it means whether 16 bit sample values in the Tiff image are
+little-endian or big-endian.  This is totally erroneous (The
+endianness of integers in a Tiff image is designated by the image's
+magic number).  However, ImageMagick and older Netpbm both have been known
+to implement that interpretation.  2001.09.06.
+.PP
+If the image does not have sub-byte pixels, these options have no
+effect other than to set the value of the FILLORDER tag in the Tiff
+image (which may be useful for those programs that misinterpret the
+tag with reference to 16 bit samples).
+
+.UN colorspace
+.SS Color Space
+.PP
+\fB-color\fP tells \fBpamtotiff\fP to produce a color, as
+opposed to grayscale, TIFF image if the input is PPM, even if it
+contains only shades of gray.  Without this option, \fBpamtotiff\fP
+produces a grayscale TIFF image if the input is PPM and contains only
+shades of gray, and at most 256 shades.  Otherwise, it produces a
+color TIFF output.  For PBM and PGM input, \fBpamtotiff\fP always
+produces grayscale TIFF output and this option has no effect.
+.PP
+The \fB-color\fP option can prevent \fBpamtotiff\fP from making
+two passes through the input file, thus improving speed and memory
+usage.  See 
+.UR #multipass
+Multiple Passes
+.UE
+\&.
+.PP
+\fB-truecolor\fP tells \fBpamtotiff\fP to produce the 24-bit RGB
+form of TIFF output if it is producing a color TIFF image.  Without
+this option, \fBpamtotiff\fP produces a colormapped (paletted) TIFF
+image unless there are more than 256 colors (and in the latter case,
+issues a warning).
+.PP
+The \fB-truecolor\fP option can prevent \fBpamtotiff\fP from
+making two passes through the input file, thus improving speed and
+memory usage.  See 
+.UR #multipass
+Multiple Passes
+.UE
+\&.
+.PP
+The \fB-color\fP and \fB-truecolor\fP options did not exist
+before Netpbm 9.21 (December 2001).
+.PP
+If \fBpamtotiff\fP produces a grayscale TIFF image, this option
+has no effect.
+.PP
+The \fB-minisblack\fP and \fB-miniswhite\fP options force the
+output image to have a "minimum is black" or "minimum
+is white" photometric, respectively.  If you don't specify
+either, \fBpamtotiff\fP uses minimum is black except when using Group
+3 or Group 4 compression, in which case \fBpamtotiff\fP follows CCITT
+fax standards and uses "minimum is white." This usually
+results in better compression and is generally preferred for bilevel
+coding.  These photometrics are for grayscale images, so these options are
+invalid if the image is color (but only if it is truly color; they are
+valid with, for example, a PPM image that contains only shades of gray).
+.PP
+Before Netpbm 9.11 (February 200)1, \fBpamtotiff\fP always produced
+"minimum is black," because of a bug.  In either case,
+\fBpamtotiff\fP sets the photometric interpretation tag in the TIFF
+output according to which photometric is actually used.
+.PP
+Before Netpbm 10.78 (March 2017), \fBpamtotiff\fP respected
+\fB-miniswhite\fP and \fB-minisblack\fP even with color images, producing
+invalid TIFF images that have the indicated photometric but red, green, and
+blue raster planes.
+.PP
+The \fB-indexbits\fP option is meaningful only for a colormapped
+(paletted) image.  In this kind of image, the raster contains values
+which are indexes into a table of colors, with the indexes normally
+taking less space that the color description in the table.
+\fBpamtotiff\fP can generate indexes of 1, 2, 4, or 8 bits.  By
+default, it will use 8, because many programs that interpret TIFF
+images can't handle any other width.
+.PP
+But if you have a small number of colors, you can make your image
+considerably smaller by allowing fewer than 8 bits per index, using the
+\fB-indexbits\fP option.  The value is a comma-separated list of the
+bit widths you allow.  \fBpamtotiff\fP chooses the smallest width you allow
+that allows it to index the entire color table.  If you don't allow any
+such width, \fBpamtotiff\fP fails.  Normally, the only useful value for
+this option is \fB1,2,4,8\fP, because a program either understands the 8
+bit width (default) or understands them all.
+.PP
+In a Baseline TIFF image, according to the 1992 TIFF 6.0
+specification, 4 and 8 are the only valid widths.  There are no formal
+standards that allow any other values.
+.PP
+This option was added in June 2002.  Before that, only 8 bit indices were
+possible.
+
+.UN extratags
+.SS Extra Tags
+.PP
+There are lots of tag types in the TIFF format that don't correspond to
+any information in the PNM format or to anything in the conversion process.
+For example, a TIFF_ARTIST tag names the artist who created the image.
+.PP
+You can tell \fBpamtotiff\fP explicitly to include tags such as this
+in its output with the \fB-tag\fP option.  You identify a list of tag
+types and values and \fBpamtotiff\fP includes a tag in the output for
+each item in your list.
+.PP
+The value of \fB-tag\fP is the list of tags, like this example:
+
+.nf
+\f(CW
+    -tag=subfiletype=reducedimage,documentname=Fred,xposition=25
+\fP
+
+.fi
+.PP
+As you see, it is a list of tag specifications separated by commas.
+Each tag specification is a name and a value separated by an equal
+sign.  The name is the name of the tag type, except in arbitrary
+upper/lower case.  One place to see the names of TIFF tag types is in
+the TIFF library's \fBtiff.h\fP file, where there is a macro defined
+for each consisting of "TIFF_" plus the name.  E.g. for
+the SUBFILETYPE tag type, there is a macro TIFF_SUBFILETYPE.
+.PP
+The format of the value specification for a tag (stuff after the
+equal sign) depends upon what kind of value the tag type has:
+
+
+.IP \(bu
+Integer: a decimal number
+
+.IP \(bu
+Floating point number: a decimal number
+
+.IP \(bu
+String: a string
+
+.IP \(bu
+Enumerated (For example, a 'subfiletype' tag takes an enumerated
+value.  Its possible values are REDUCEDIMAGE, PAGE, and MASK.): The
+name of the value.  You can see the possible value names in the TIFF
+library's \fBtiff.h\fP file, where there is a macro defined for each
+consisting of a qualifier plus the value name.  E.g. for the
+REDUCEDIMAGE value of a SUBFILETYPE tag, you see the macro
+FILETYPE_REDUCEDIMAGE.
+.sp
+The TIFF format assigns a unique number to each enumerated value and
+you can specify that number, in decimal, as an alternative.  This is useful
+if you are using an extension of TIFF that \fBpamtotiff\fP doesn't
+know about.
+
+
+.PP
+If you specify a tag type with \fB-tag\fP that is not independent
+of the content of your PNM source image and \fBpamtotiff\fP's
+conversion process (i.e. a tag type in which \fBpamtotiff\fP is
+interested), \fBpamtotiff\fP fails.  For example, you cannot specify
+an IMAGEWIDTH tag with \fB-tag\fP, because \fBpamtotiff\fP generates
+an IMAGEWIDTH tag that gives the actual width of the image.
+.PP
+\fB-tag\fP was new in Netpbm 10.31 (December 2005).
+
+.UN outputoptions
+.SS Output
+.PP
+See 
+.UR #output
+The Output File
+.UE
+\&.
+.PP
+\fB-output\fP names the output file.  Without this option
+\fBpamtotiff\fP writes to Standard Output.
+.PP
+The \fB-append\fP option tells \fBpamtotiff\fP only to append to the file
+named by \fBoutput\fP; not create it.  Without this option, the program
+creates the file it does not already exist.  But even then, if the file does
+already exist, the program appends the image to what is in the file already.
+(A TIFF file may contain multiple images).
+.PP
+\fB-append\fP has no effect if you don't also specify \fB-output\fP.
+.PP
+Before Netpbm 10.67 (June 2014), \fB-append\fP means something rather
+different: it means to append the image to the output TIFF file (which is
+always Standard Output in 10.67) instead of replacing its contents.
+.PP
+\fB-append\fP was new in Netpbm 10.27 (March 2005).
+
+
+
+.UN other
+.SS Other
+.PP
+You can use the \fB-rowsperstrip\fP option to set the number of
+rows (scanlines) in each strip of data in the output file.  By
+default, the output file has the number of rows per strip set to a
+value that will ensure each strip is no more than 8 kilobytes long.
+
+
+.UN notes
+.SH NOTES
+.PP
+There are myriad variations of the TIFF format, and this program
+generates only a few of them.  \fBpamtotiff\fP creates a grayscale
+TIFF file if its input is a PBM (monochrome) or PGM (grayscale) or
+equivalent PAM file.  \fBpamtotiff\fP also creates a grayscale file
+if it input is PPM (color) or equivalent PAM, but there is only one
+color in the image.
+.PP
+If the input is a PPM (color) file and there are 256 colors or
+fewer, but more than 1, \fBpamtotiff\fP generates a color palette
+TIFF file.  If there are more colors than that, \fBpamtotiff\fP
+generates an RGB (not RGBA) single plane TIFF file.  Use
+\fBpnmtotiffcmyk\fP to generate the cyan-magenta-yellow-black ink
+color separation TIFF format.
+.PP
+The number of bits per sample in the TIFF output is determined by
+the maxval of the Netpbm input.  If the maxval is less than 256, the bits
+per sample in the output is the smallest number that can encode the
+maxval.  If the maxval is greater than or equal to 256, there are 16
+bits per sample in the output.
+
+.UN extrachannel
+.SS Extra Channels
+.PP
+Like most Netpbm programs, \fBpamtotiff\fP's function is mostly
+undefined if the input is PAM image with tuple type other than
+BLACKANDWHITE, GRAYSCALE, or RGB.  Most of the statements in this manual
+assume the input is not such an exotic PAM.  But there is a little
+defined processing of other PAM subformats.
+.PP
+\fBpamtotiff\fP assumes any 1 plane PAM image is BLACKANDWHITE
+or GRAYSCALE (and doesn't distinguish between those two).
+.PP
+\fBpamtotiff\fP assumes a PAM with more than 1 plane is of tuple
+type RGB except with that number of planes instead of 3.
+\fBpamtotiff\fP doesn't really understand red, green, and blue, so it
+has no trouble with a 2-component or 5-component color space.  The
+TIFF format allows an arbitrary number of color components, so
+\fBpamtotiff\fP simply maps the PAM planes directly to TIFF color
+components.  I don't know if the meanings of 5 components in a TIFF image
+are standard at all, but the function is there if you want to use it.
+.PP
+Note that \fBpamtotiff\fP may generate either a truecolor or
+colormapped image with an arbitrary number of color components.  In
+the truecolor case, the raster has that number of planes.  In the
+colormapped case, the raster has of course 1 plane, but the color map
+has all the color components in it.
+.PP
+The most common reason for a PAM to have extra planes is when the tuple
+type is xxx_ALPHA, which means the highest numbered plane is a transparency
+plane (alpha channel).  At least one user found that a TIFF with an extra
+plane for transparency was useful.
+.PP
+Note that the grayscale detection works on N-component colors, so if
+your planes aren't really color components, you'll want to disable this
+via the \fB-color\fP option.
+
+
+.UN multipass
+.SS Multiple Passes
+.PP
+\fBpamtotiff\fP reads the input image once if it can, and
+otherwise twice.  It needs that second pass (which happens before the
+main pass, of course) to analyze the colors in the image and generate
+a color map (palette) and determine if the image is grayscale.  So the
+second pass happens only when the input is PPM.  And you can avoid it
+then by specifying both the \fB-truecolor\fP and \fB-color\fP
+options.
+.PP
+ If the input image is small enough to fit in your system's file
+cache, the second pass is very fast.  If not, it requires reading from
+disk twice, which can be slow.
+.PP
+When the input is from a file that cannot be rewound and reread,
+\fBpamtotiff\fP reads the entire input image into a temporary file
+which can, and works from that.  Even if it needs only one pass.
+.PP
+Before Netpbm 9.21 (December 2001), \fBpamtotiff\fP always read
+the entire image into virtual memory and then did one, two, or three
+passes through the memory copy.  The \fB-truecolor\fP and
+\fB-color\fP options did not exist.  The passes through memory would
+involve page faults if the entire image did not fit into real memory.
+The image in memory required considerably more memory (12 bytes per
+pixel) than the cached file version of the image would.
+
+
+.UN resolution
+.SS Resolution
+.PP
+A Tiff image may contain information about the resolution of the image,
+which means how big in real dimensions (centimeters, etc.) each pixel in the
+raster is.  That information is in the TIFF XRESOLUTION, YRESOLUTION,
+and RESOLUTIONUNIT tags.  By default, \fBpamtotiff\fP does not include
+any tags of these types, but you can specify them with the \fB-tags\fP
+option.
+.PP
+There are also options \fB-xresolution\fP, \fB-yresolution\fP,
+and \fB-resolutionunit\fP, but those are obsolete.  Before \fB-tags\fP
+existed (before Netpbm 10.31 (December 2005), they were the only way.
+.PP
+Note that the number of pixels in the image and how much information
+each contains is determined independently from the setting of the
+resolution tags.  The number of pixels in the output is the same as in
+the input, and each pixel contains the same information.  For your
+resolution tags to be meaningful, they have to consistent with
+whatever created the PNM input.  E.g. if a scanner turned a 10 centimeter
+wide image into a 1000 pixel wide PNM image, then your horizontal
+resolution is 100 pixels per centimeter, and if your XRESOLUTION
+tag says anything else, something that prints your TIFF image won't
+print the proper 10 centimeter image.
+.PP
+The value of the XRESOLUTION tag is a floating point decimal number
+that tells how many pixels there are per unit of distance in the
+horizontal direction.  \fB-yresolution\fP is analogous for the
+vertical direction.
+.PP
+The unit of distance is given by the value of the RESOLUTIONUNIT
+option.  That value is either INCH, CENTIMETER, or NONE.  NONE
+means the unit is arbitrary or unspecified.  This could mean that the
+creator and user of the image have a separate agreement as to what the
+unit is.  But usually, it just means that the horizontal and vertical
+resolution values cannot be used for anything except to determine
+aspect ratio (because even though the unit is arbitrary or
+unspecified, it has to be the same for both resolution numbers).
+.PP
+If you \fIdon't\fP use a \fB-tag\fP option to specify the
+resolution tag and use the obsolete options instead, note the
+following:
+
+
+.IP \(bu
+If you don't include an specify \fB-xresolution\fP, the Tiff image
+does not contain horizontal resolution information.  Likewise for
+\fB-yresolution\fP.  If you don't specify \fB-resolutionunit\fP, the
+default is inches.
+
+.IP \(bu
+Before Netpbm 10.16 (June 2003), \fB-resolutionunit\fP did not
+exist and the resolution unit was always inches.
+
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtotiff\fP was originally \fBpnmtotiff\fP and did not handle
+PAM input.  It was extended and renamed in Netpbm 10.30 (October 2005).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "tifftopnm" (1)\c
+\&,
+.BR "pnmtotiffcmyk" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Derived by Jef Poskanzer from ras2tiff.c, which is
+Copyright (c) 1990 by Sun Microsystems, Inc.
+Author: Patrick J. Naughton (\fInaughton@wind.sun.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtotiff.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtouil.1 b/upstream/mageia-cauldron/man1/pamtouil.1
new file mode 100644
index 00000000..577705fa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtouil.1
@@ -0,0 +1,91 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtouil User Manual" 0 "05 May 2002" "netpbm documentation"
+
+.SH NAME
+
+pamtouil - convert a PNM or PNM/transparency image into a Motif UIL icon file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtouil\fP [\fB-name=\fP\fIuilname\fP] [\fIpamfile\fP]
+.PP
+You may abbreviate any option to its shortest unique prefix.
+You may use two hyphens instead of one to delimit an option.  You may
+separate an option from its value with whitespace instead of \fB=\fP.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtouil\fP reads a PNM or PAM image as input and produces a Motif UIL
+icon file as output.  If the input is PAM, it may be either a regular
+grayscale or color image or grayscale+transparency or color+transparency.
+Where the transparency channel is present, \fBpamtouil\fP renders pixels that
+are more than half transparent as transparent in the output.
+.PP
+In the UIL's colormap, \fBpamtouil\fP uses the color names from
+the RGB database -- the same one
+.BR "ppmmake" (1)\c
+\&
+uses.  Where a color in the input does not exactly match one of the colors
+named in the RGB database, \fBpamtouil\fP uses the closest color named
+in the RGB database.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtouil\fP recognizes the following
+command line option:
+
+
+
+.TP
+\fB-name\fP
+     Allows you to specify the prefix string which is printed in the
+     resulting UIL output.  If not specified, will default to the filename
+     (without extension) of the ppmfile argument.  If \fB-name\fP is not
+     specified and no ppmfile is specified (i.e. piped input), the
+     prefix string will default to the string "noname".
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamstack" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Before May 2002, \fBpamtouil\fP was called \fBppmtouil\fP and had no
+way to specify transparency.
+
+.UN author
+.SH AUTHOR
+
+Converted by Bryan Henderson from ppmtouil.c, which was converted by
+Jef Poskanzer from ppmtoxpm.c, which is Copyright (C) 1990 by Mark
+W. Snitily
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtouil.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtowinicon.1 b/upstream/mageia-cauldron/man1/pamtowinicon.1
new file mode 100644
index 00000000..0269cb39
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtowinicon.1
@@ -0,0 +1,194 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtowinicon User Manual" 0 "12 April 2013" "netpbm documentation"
+
+.SH NAME
+
+pamtowinicon - convert Netpbm PAM images to a Microsoft Windows icon file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtowinicon\fP
+[\fB-pngthreshold=\fP\fIthreshold\fP]
+[\fB-truetransparent\fP]
+[\fB-verbose\fP]
+[\fIpam_file\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or equals signs between an option name and
+its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtowinicon\fP reads an RGB_ALPHA Netpbm PAM file and converts it to a
+Microsoft Windows icon file.
+.PP
+The output goes to Standard Output.
+.PP
+The input is a multi-image PAM file; each image becomes an icon in the
+output file.  If you have input images in multiple files, you can simply
+combine them with \fBcat\fP and pass the result to \fBpamtowinicon\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm (most
+notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+Common Options
+.UE
+\&), \fBpamtowinicon\fP recognizes the following command
+line options:
+
+
+.TP
+\fB-pngthreshold=\fP\fIthreshold\fP
+\fBpamtowinicon\fP encodes images with resolutions above or
+equal \fIthreshold\fP by \fIthreshold\fP as PNG by running
+.BR "\fBpnmtopng\fP" (1)\c
+\&.  Other images it encodes
+using the more traditional BMP format.
+.sp
+When the program uses PNG encoding for a 5-channel PAM with separate AND
+mask (see below), it discards the AND mask.  Because PNG has always had the
+ability to specify transparency, the Windows icon format does not provide for
+a separate and mask when the icon is encoded in PNG.
+.sp
+The default value for \fIthreshold\fP is 128.
+
+.TP
+\fB-truetransparent\fP
+Make all pixels outside the opaque area black, avoiding inversion
+and other effects on the background of the image
+(see
+.BR "Windows Icons" (1)\c
+\&).
+
+.TP
+\fB-verbose\fP
+Print more messages
+
+
+
+
+.UN images
+.SH IMAGES
+.PP
+\fBpamtowinicon\fP reads a (multi-image) Netpbm PAM file
+as input and outputs an single Windows icon file containing those images.
+.PP
+The images in the icon file are in the same order as in the PAM input.
+
+
+.UN paminput
+.SS PAM Input
+.PP
+\fBpamtowinicon\fP interprets the PAM images as follows, based on the number
+of channels.
+
+.TS
+l l.
+_
+channels	image
+1	fully opaque grayscale image
+2	grayscale image with transparency channel
+3	fully opaque color image
+4	color image with transparency channel
+5	color image with transparency channel and additional AND
+mask
+.TE
+.PP
+The tuple types of the PAMs are irrelevant.
+
+
+.UN andmask
+.SS AND Mask
+
+The so-called "AND mask" is a special feature of Microsoft
+Windows icons.  It is required for all BMP encoded images.  At the
+first sight, the AND mask is a 1-bit transparency channel, but it is also
+used for e.g. shading the icon while dragging.  See
+.BR "Windows Icons" (1)\c
+\& for details.
+.PP
+If there is no explicit AND mask, but transparency data in the
+input image, \fBpamtowinicon\fP sets the AND mask to opaque where the
+sample in the transparency channel is below maxval, and to transparent
+elsewhere.
+.PP
+If no transparency data is present in the input image,
+\fBpamtowinicon\fP assumes the whole image to be fully opaque.
+
+
+.UN bmpoutput
+.SS BMP Output
+
+When BMP encoding an image, \fBpamtowinicon\fP tries to use the most
+compact \fBBI_RGB\fP format allowed for icon images with a color
+depth of eight bits per channel.
+.PP
+\fBpamtowinicon\fP generates neither 16-bit \fBBI_RGB\fP nor
+\fBBI_BITFIELDS\fP BMP encoded images, even if the maxval of the input
+PAM is not 255.
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "\fBwinicontopam\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBppmtowinicon\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBpam\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBWindows Icons\fP" (1)\c
+\&
+
+.PP
+For information on the PNG format, see
+.UR http://schaik.com/png
+http://schaik.com/png
+.UE
+\&.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtowinicon\fP was new in Netpbm 10.63 (June 2013).  It obsoleted
+\fBppmtowinicon\fP by providing more function and conforming better to
+Netpbm conventions.
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2013 by Ludolf Holzheid.
+.PP
+Translated to Netpbm coding style by Bryan Henderson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtowinicon.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtoxvmini.1 b/upstream/mageia-cauldron/man1/pamtoxvmini.1
new file mode 100644
index 00000000..e41f7066
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtoxvmini.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtoxvmini User Manual" 0 "02 April 2006" "netpbm documentation"
+
+.SH NAME
+
+pamtoxvmini - convert Netpbm image to an XV "thumbnail" picture
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtoxvmini\fP
+
+[\fIpamfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtoxvmini\fP reads a Netpbm image (PAM or PNM) and produces
+an XV "thumbnail" picture (a miniature picture normally
+generated by the "VisualSchnauzer" browser) as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamtoxvmini\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "xvminitoppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+\fBxv\fP manual
+
+.UN history
+.SH HISTORY
+.PP
+This program was new in Netpbm 10.34 (April 2006).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtoxvmini.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamtris.1 b/upstream/mageia-cauldron/man1/pamtris.1
new file mode 100644
index 00000000..b65ec10d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtris.1
@@ -0,0 +1,808 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtris User Manual" 0 "15 April 2021" "netpbm documentation"
+.PP
+.SH NAME
+pamtris - triangle rasterizer featuring perspective-correct
+interpolation of generic vertex attributes and depth buffering
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtris\fP
+
+\fB-width=\fP\fIwidth\fP
+
+\fB-height=\fP\fIheight\fP
+
+{\ \fB-num_attribs=\fP\fIattributes_per_vertex\fP
+[\ \fB-tupletype=\fP\fItupletype\fP\ ]
+| \fB-rgb\fP
+| \fB-grayscale\fP\ }
+
+[\ \fB-maxval=\fP\fImaxval\fP\ ]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtris\fP can be used to draw a great variety of 2D and 3D graphics by
+composing arbitrarily complex pictures out of separate triangles, triangle
+strips and triangle fans. The program reads instructions written in a simple
+command script notation from Standard Input and outputs its results
+as a (potentially multi-image) PAM stream on Standard Output.
+.PP
+For example, the following input
+
+.nf
+  \f(CW
+      mode fan
+      attribs 0 128 0
+      vertex 0 0 1
+      attribs 0 0 128
+      vertex 200 0 1
+      attribs 50 20 103
+      vertex 190 61 1
+      attribs 100 40 78
+      vertex 161 117 1
+      attribs 150 60 53
+      vertex 117 161 1
+      attribs 200 80 28
+      vertex 61 190 1
+      attribs 250 100 3
+      vertex 0 200 1
+      print
+    \fP
+
+.fi
+  
+.PP
+produces this:
+.PP
+.B Example pamtris output for FAN mode
+.IMG -C pamtris_fan.png
+  
+.PP
+The input file gives triangle data by setting the appropriate drawing mode,
+if necessary, and then providing a list of vertices. Each vertex is also
+associated with a list of up to 20 "attributes," which are integer
+values between 0 and a given maxval. In the most common usage, you use
+\fBpamtris\fP to draw a visual image and a vertex has three attributes, which
+are an RGB specification of a color.  Such attribute lists may be provided on
+a per-vertex basis.
+.PP
+Prior to effectively writing a PAM image to Standard Output, \fBpamtris\fP
+first rasterizes it onto an internal frame buffer, which consists of an
+"image buffer" and a "depth buffer." The image buffer consists of a sequence
+of \fIheight\fP rows containing a sequence of \fIwidth\fP tuples. There is
+one sample for each vertex attribute in every tuple plus an opacity (alpha)
+sample. Each tuple in the image buffer is also associated with an integer
+depth in the depth buffer, which determines whether subsequent drawing
+operations affect that particular tuple or not. This provides a way of
+depth-sorting graphical objects which is adequate for many purposes in 2D
+and 3D computer graphics. One prominent shortcoming of such an approach
+to depth-sorting, however, is that it does not automatically work with
+objects which are intended to appear "translucent," therefore requiring
+more elaborate strategies to incorporate said objects into pictures
+generated using this technique.
+.PP
+The opacity sample is the last sample of the tuple.  \fBpamtris\fP
+manipulates opacity internally and for any tuple it is always either 0 or the
+maxval.  The program does not provide the user direct control over the alpha
+image plane.
+.PP
+\fBpamtris\fP rasterizes triangles by approximating their visible area as
+a collection of tuples at particular positions in the frame buffer, and to
+each sample of every such tuple it assigns a value which is a
+perspective-correct interpolation between the values of the corresponding
+attribute for each vertex of the triangle. Whenever a tuple within the area
+of the frame buffer is produced, it is written to the corresponding position
+in the frame buffer if and only if it passes a depth test.  This test works
+as follows: the depth value of every incoming tuple (which is itself an
+interpolation between the Z-coordinates of the vertices of the
+corresponding triangle) is compared against the value in the corresponding
+position in the depth buffer. If the depth value of the incoming tuple
+equals or is smaller than the depth value already present in said position in
+the depth buffer, the following happens.
+
+
+.IP \(bu
+Every sample \fIi\fP, where 0 &#8804; \fIi\fP < \fInum_attribs\fP,
+of the tuple in the corresponding position in the image buffer is set to equal
+the value of the respective sample of the incoming tuple; and the alpha
+sample (the last one) is updated to the \fImaxval\fP;
+
+.IP \(bu
+The depth value in the corresponding position in the depth buffer is
+updated to a depth value directly proportional to that of the incoming
+tuple.
+
+.PP
+Otherwise, that particular tuple effects no change at all in the frame
+buffer.
+.PP
+The frame buffer is initially set so that all samples in every tuple of the
+image buffer contain the value 0, and all entries in the depth buffer contain
+the maximum permitted depth value.
+.PP
+The attributes' values, and therefore the samples in the output
+PAM images, have no fixed interpretation ascribed to them (except for the
+last image plane, which is deliberately supposed to represent tuple opacity
+information); one may ascribe any suitable meaning to them, such as that of
+colors, texture coordinates, surface normals, light interaction
+characteristics, texture influence coefficients for multi-texturing, etc.
+
+
+.UN examples
+.SH EXAMPLES
+
+.UN examples_fan
+.SS Fan Mode
+.PP
+The following command generates the image from the fan mode example at the
+top of the 
+.UR #description
+DESCRIPTION
+.UE
+\& section. If the file
+\fBfan.tris\fP contains that code, you could process it with:
+
+.nf
+  \f(CW
+    $ pamtris -height=200 -width=200 -rgb <fan.tris >fan.pam
+  \fP
+
+.fi
+  
+.UN examples_strip
+.SS Strip Mode
+.PP
+The following is an example of strip mode:
+
+.nf
+  \f(CW
+      mode strip
+      attribs 255 0 0   # red
+      vertex   0 200 1
+      vertex  50   0 1
+      attribs 0 0 0     # black
+      vertex 100 200 1
+      attribs 0 205 205 # cyan
+      vertex 150 0 1
+      attribs 0 0 255   # blue
+      vertex 200 200 1
+      vertex 250   0 1
+      print
+    \fP
+
+.fi
+.PP
+Save the above code in a file named \fBstrip.tris\fP (for instance)
+and process it with:
+  
+.nf
+  \f(CW
+    $ pamtris -height=200 -width=200 -rgb <strip.tris >strip.pam
+  \fP
+
+.fi
+  
+to yield:
+.PP
+.B Example pamtris output for STRIP mode
+.IMG -C pamtris_strip.png
+
+.UN examples_triangles
+.SS Triangle Mode
+.PP
+The following is an example of triangle mode:
+
+.nf
+  \f(CW
+      # yellow square
+      mode strip
+      attrib 155 155 0
+      vertex 50  50 100
+      vertex 50 200 100 
+      vertex 200 50 100
+      vertex 200 200 100
+      
+      # blue triangle
+      mode triangles
+      attrib 0 205 205
+      vertex 20 125 70
+      attrib 0 0 140
+      vertex 230  70 120 # Change "120" and see what happens
+      vertex 230 180 120 #
+      print
+    \fP
+
+.fi
+.PP
+Save the above code in a file named \fBpierce.tris\fP (for instance)
+and process it with:
+  
+.nf
+  \f(CW
+    $ pamtris -height=200 -width=200 -rgb <pierce.tris >pierce.pam
+  \fP
+
+.fi
+
+to yield:
+.PP
+.B Example pamtris output for TRIANGLES mode
+.IMG -C pamtris_pierce.png
+
+
+.UN pamtris_c
+.SS Meta-programming
+.PP
+The \fBpamtris\fP command language is much too rudimentary to be used
+directly for any serious drawing; you will probably want to use a general
+purpose programming language to generate a temporary \fBpamtris\fP command
+file.
+.PP
+For example, the \fBdraw_polygon\fP procedure in the C program below
+outputs \fBpamtris\fP instructions to draw a regular polygon. It does this
+by generating a number of \fBvertex\fP instructions tracing around the
+perimeter of the corresponding circumscribed circle. (Note: The PAM image
+produced by piping the output of the below program into \fBpamtris\fP was
+subsequently downscaled through
+\fBpamscale\ -linear\ -xscale\ 0.25\ -yscale\ 0.25\fP
+to achieve an 
+.UR #antialias
+anti-aliased
+.UE
+\& effect.)
+.PP
+.B Regular Polygons
+.IMG -C pamtris_polygons.png
+
+.nf
+\f(CW
+/* ----------------------- *
+ * width       = 512       *
+ * height      = 512       *
+ * num_attribs = 3         *
+ * tupletype   = RGB_ALPHA *
+ * ----------------------- */
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#define PI 3.14159265358979323844
+
+void draw_polygon
+(int const center_x, int const center_y, int const radius, int const sides)
+{
+    printf("mode fan\en"
+           "vertex %d %d 0\en", center_x, center_y);
+
+    for(int i = 0; i <= sides; i++)
+    {
+        int const x = round(center_x + radius * cos(i*2.0*PI / sides));
+        int const y = round(center_y - radius * sin(i*2.0*PI / sides));
+
+        printf("vertex %d %d 0\en", x, y);
+    }
+}
+
+int main(void)
+{
+    puts("attribs 0 185 80");       /* color: green   */
+    draw_polygon(300, 210, 150, 5); /* draws pentagon */
+
+    puts("attribs 255 15 240");     /* color: magenta */
+    draw_polygon(150, 320, 100, 7); /* draws heptagon */
+
+    puts("!");
+}
+\fP
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtris\fP recognizes the following
+command line options:
+
+<dl compact="compact">
+.TP
+\fB-width=\fP\fIwidth\fP
+Sets the width of the internal frame buffer and, by extension, of the
+output PAM images, given in number of columns. This must be an integer in the
+closed range [1, 8192].
+.sp
+This option is mandatory.
+
+.TP
+\fB-height=\fP\fIheight\fP
+This is the height of the internal frame buffer and, by extension, of the
+output PAM images, given in number of rows. This must be an integer in
+the closed range [1, 8192].
+.sp
+This option is mandatory.
+
+.TP
+\fB-num_attribs=\fP\fIattributes_per_vertex\fP
+This is the number of attributes per vertex. The depth of the output
+PAM images equals this value plus one (to accomodate the alpha plane). The
+argument must be an integer in the closed range [1, 20].
+.sp
+The input instruction stream may override this with a \fBreset\fP
+command.
+.sp
+You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
+and \fB-grayscale\fP.
+
+
+.TP
+\fB-tupletype=\fP\fItupletype\fP
+This is the tuple type for the output PAM images. The argument is a string
+which may be no longer than 255 characters.
+.sp
+The input instruction stream may override this with a \fBreset\fP
+command.
+.sp
+The default is a null string.
+.sp
+This option cannot be specified together with  \fB-rgb\fP or
+\fB-grayscale\fP.
+
+
+
+.TP
+\fB-rgb\fP
+This is a convenience option which simply serves as an alias for
+\fB-num_attribs=\fP3 \fB-tupletype=\fPRGB_ALPHA. In other words, this option
+is a quick way to specify that you are going to use \fBpamtris\fP to draw
+RGB(_ALPHA) color images directly, and the three vertex attributes are the
+red, green and blue levels of the color associated with the vertex, in that
+order.
+.sp
+The input instruction stream may override this with a \fBreset\fP
+command.
+.sp
+You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
+and \fB-grayscale\fP.
+.sp
+This option was new in Netpbm 10.85 (December 2018).
+
+.TP
+\fB-grayscale\fP
+Another convenience option, similar to \fB-rgb\fP; except this one is an
+alias for \fB-num_attribs=\fP1 \fB-tupletype=GRAYSCALE_ALPHA\fP. The one
+vertex attribute is the gray level associated with the vertex.
+.sp
+The input instruction stream may override this with a \fBreset\fP
+command.
+.sp
+You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
+and \fB-grayscale\fP.
+.sp
+This option was new in Netpbm 10.85 (December 2018).
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+Sets the maxval of the output PAM images, which is also the maximum
+permitted value for each vertex attribute. This must be an integer in the
+closed range [1, 65535].
+.sp
+The default value is 255.
+.sp
+The input instruction stream may override this with a
+\fBreset\fP command.
+
+
+
+.UN instruction_code
+.SH INSTRUCTION CODE
+.PP
+The input for \fBpamtris\fP consists of a stream of text lines read from
+Standard Input.
+.PP
+Empty lines or lines that contain only white space characters are called
+blank lines and are ignored.
+.PP
+When a \fB#\fP occurs anywhere in a line, \fBpamtris\fP ignores it
+along with every character after it. In other words, everything from the
+\fB#\fP until the end of the line receives the same treatment as white
+space.
+.PP
+Lines which are not blank must contain a sequence of strings, called
+tokens, separated by white space.  The first such token must be one of the
+commands recognized by \fBpamtris\fP, and all further tokens are interpreted
+as the arguments for that command, if it takes any. When an insufficient
+number of arguments is provided for a command, the line is considered invalid
+and is given the same treatment as a blank line. The same happens when an out
+of range argument or one of a kind different of what is expected is given (for
+example, when you give a string of letters where a numerical value is
+expected), or when an unrecognized command/argument is found. When a number of
+arguments greater than that required for a particular command is provided,
+only the portion of the line up to the last required argument is considered
+and any further tokens are ignored.
+.PP
+\fBpamtris\fP is case-insensitive. That is, \fBmode\fP, \fBMODE\fP,
+\fBmODe\fP, etc. are all treated the same way.
+.PP
+The commands recognized by \fBpamtris\fP are:
+
+.TP
+\fBmode\fP
+.TP
+\fBattribs\fP
+.TP
+\fBvertex\fP
+.TP
+\fBprint\fP
+.TP
+\fBclear\fP
+.TP
+\fBreset\fP
+.TP
+\fBquit\fP
+
+.PP
+You may use a minimum unique abbreviation of a command name.  You may use
+an exclamation mark (\fB!\fP) in place of the \fBprint\fP command name and an
+asterisk (\fB*\fP) in place of \fBclear\fP.
+.PP
+The functions of the commands are as follows.
+
+
+.TP
+\fBmode\fP { triangles | strip | fan }
+.sp
+This makes \fBpamtris\fP enter a new drawing mode. The argument is a word
+which specifies the mode to change to. Instead of a full argument name, it is
+permissible to provide a minimum unique abbreviation, which has the same
+effect. The drawing mode will remain the same until the next \fBmode\fP
+command is given.
+.sp
+This command also resets the current vertex list, which is
+(re)initialized to an empty state after the command is executed. One may add
+new vertices to this list through successive invocations of the \fBvertex\fP
+command (see below). You do not have to worry about providing "too many"
+vertices, since the vertex list is virtualized: \fBpamtris\fP maintains only
+the state pertaining to three vertices at any one time. The current vertex
+list is initially empty.
+.sp
+It is permissible to give \fBpamtris\fP a \fBmode\fP command which
+instructs it to enter a drawing mode it is currently already in. One might
+use this approach to reset the current vertex list without changing the
+current drawing mode.
+.sp
+Regardless of the current drawing mode, the program immediately rasterizes
+a new triangle into the frame buffer as soon as you provide the necessary
+vertices for it through the current vertex list. (If you reset the vertex list
+before giving all the vertices necessary to draw a new triangle, the program
+effectively discards from the list any vertices that might have been pushed
+into the vertex list up to that point without using them to draw any new
+triangles.)
+.sp
+In the following descriptions of each drawing mode, triangles' and
+vertices' indices (ordinal numbers) are 0-based.
+.sp
+The \fBtriangles\fP argument instructs \fBpamtris\fP to enter the
+"TRIANGLES" drawing mode. While in this mode, a series of separate triangles
+is constructed. Every three vertices pushed into the current vertex list
+specify a new triangle.  Formally, this means that every
+\fIN\uth\d\fP triangle is specified by vertices 3*\fIN\fP,
+3*\fIN\fP\ +\ 1, and 3*\fIN\fP\ +\ 2. This is the default
+initial mode and is therefore not required to be set explicitly before
+drawing any triangles.
+.sp
+The \fBstrip\fP argument instructs \fBpamtris\fP to enter the "STRIP"
+drawing mode.  While in this mode, \fBpamtris\fP constructs a "triangle
+strip." That is, the first three vertices pushed into the current vertex
+list specify the first triangle, and every new vertex pushed after that
+specifies, together with the previous two, the next triangle. Formally, this
+means that every \fIN\fP\uth\d triangle is specified by vertices
+\fIN\fP, \fIN\fP\ +\ 1, and \fIN\fP\ +\ 2.
+.sp
+The \fBfan\fP argument instructs \fBpamtris\fP to enter the "FAN" 
+drawing mode.  While in this mode, a so-called "triangle fan" is constructed.
+That is, the first three vertices pushed into the current vertex list specify
+the first triangle, and every new vertex pushed after that specifies, together
+with the previous vertex and the first one, the next triangle. Formally, this
+means that every \fIN\fP\uth\d triangle is specified by vertices
+\fI0\fP, \fIN\fP\ +\ 1, and \fIN\fP\ +\ 2. 
+
+
+.TP
+
+\fBattribs\fP \fIa<sub>0\fP \fIa<sub>1\fP
+\fIa<sub>2\fP ... \fIa<sub>num_attribs - 1\fP
+.sp
+This updates the current attribute values list. This command takes as
+arguments a sequence of \fInum_attribs\fP integers which represent the
+values of the attributes to be associated with the next vertex. This
+sequence of values is the just mentioned "current attribute values list."
+.sp
+Each \fIi\uth\d\fP argument, where 0 &#8804; \fIi\fP <
+\fInum_attribs\fP, indicates the value to be assigned to the
+\fIi\fP\uth\d attribute of the current attribute values list. All
+arguments must be integer values in the closed range [0, \fImaxval\fP].
+If a number of arguments less than the current value of \fInum_attribs\fP
+is given, the command is considered invalid and is therefore ignored.
+.sp
+The current attribute values list remains unchanged until the next valid
+\fBattribs\fP or \fBreset\fP command is given. The \fBattribs\fP command
+allows one to change the values of each attribute individually, while the
+\fBreset\fP command is not specifically designed for that function, but it
+has the side effect of setting all values in the current attribute values
+list to the \fImaxval\fP (see below).
+.sp
+All values in the current attribute values list are initially set to the
+\fImaxval\fP.
+
+<dt id="cmd_vertex">\fBvertex\fP \fIx\fP \fIy\fP \fIz\fP [\fIw\fP]
+.sp
+Adds a new vertex to the current vertex list (see the \fBmode\fP
+command above), assigning the values of the arguments to its respective
+coordinates, and the values in the current attribute values list (see the
+\fBattribs\fP command above) to the respective entries in the 
+attribute list associated with the vertex.
+.sp
+\fIx\fP, \fIy\fP and \fIz\fP
+must be integer values in the closed range [-32767, 32767].
+\fIx\fP and \fIy\fP represent, respectively, the column and row of the
+tuple which corresponds to the location of the vertex. Such values may
+correspond to tuples outside the limits of the frame buffer. The origin of
+the coordinate system is at the top-left tuple of the frame buffer. The
+X-axis goes from left to right, and the Y-axis from top to bottom. A
+negative value for \fIx\fP indicates a column that many tuples to the
+left of the leftmost column of the frame buffer.  Likewise, a negative
+value for \fIy\fP indicates a row that many tuples above the uppermost
+row of the frame buffer. Observe that those coordinates correspond
+directly to a particular point in the coordinate system delineated
+above, regardless of whether you are trying to draw an image which is
+supposed to look as if viewed "in perspective" or not; \fBpamtris\fP
+does \fInot\fP "warp" the coordinates you give in any way.
+Therefore, if you want to draw images in perspective, you must compute
+values for \fIx\fP and \fIy\fP already projected into \fBpamtris\fP'
+coordinate system yourself, using an external perspective projection
+method, prior to giving them to the program.
+.sp
+The \fIz\fP parameter represents the  Z-coordinate of the vertex, which
+is used to compute depth values for tuples within the areas of rasterized
+triangles. Intuitively, smaller values for \fIz\fP mean "closer to
+the viewer," and larger ones mean "farther away from the viewer" (but
+remember: as said above, the \fIx\fP and \fIy\fP coordinates are not
+warped in any way, which implies that they are not affected by \fIz\fP;
+neither by the next parameter, for that matter).
+.sp
+Optionally, you may provide a \fIw\fP parameter which represents a
+"perspective correction factor" used to properly interpolate vertex attributes
+across the area of the corresponding triangle. This must be an integer value
+in the closed range [1, 1048575]. If you don't provide a value for it, the
+default value of 1 is used (hence, if you want to nullify the effects of
+perspective correction on a triangle so the output samples are computed as if
+just linearly interpolated, simply do not provide a value for \fIw\fP for any
+vertex of the triangle). If, however, you intend to draw 3D geometry in
+perspective, you must provide an appropriate value for this parameter,
+otherwise the output images might look very wrong.  \fIw\fP was new in Netpbm
+10.85 (December 2018).
+.sp
+Consider the
+.UR https://en.wikipedia.org/wiki/Viewing_frustum
+ typical model
+.UE
+\& of the so-called "viewing frustum" used to project vertices
+in 3D "world space" onto a planar "image space." If we adopt the convention
+that a "z-plane" means any plane parallel to the view-plane (a.k.a. picture
+plane, a.k.a. near plane), the value of \fIw\fP for a vertex should then be
+the (smallest/euclidean/orthogonal) distance in pixels between the projection
+reference point (PRP, or "eye") and the z-plane containing the vertex. One
+way to compute this value amounts to simply taking the dot product between
+the 3D vector \fBr\fP and the 3D unit vector \fBn\fP, where \fBr\fP is
+the vector which goes from the projection reference point (PRP, or "eye") to
+the vertex, and \fBn\fP is a view-plane normal (VPN) of unit length which
+points away from the PRP. In other words, this is equal to the length of the
+orthogonal projection of \fBr\fP on the line "determined" by \fBn\fP.
+.sp
+(Note: For any two 3D vectors \fBa\fP and \fBb\fP, with respective real
+scalar components a<sub>x, a<sub>y, a<sub>z and
+b<sub>x, b<sub>y, b<sub>z, the dot product between \fBa\fP
+and \fBb\fP is simply
+a<sub>x*b<sub>x\ +\ a<sub>y*b<sub>y\ +\ a<sub>z*b<sub>z.)
+
+
+.TP
+\fBprint\fP
+.sp
+This writes a PAM image to Standard Output whose raster is a copy of the
+current contents of the image buffer. The values of the WIDTH and HEIGHT
+fields are the same as the width and height, respectively, of the frame
+buffer, which were given on the command line during program invocation. The
+MAXVAL field is equal to the current maxval; the DEPTH field is equal to
+the current value of \fInum_attribs\fP + 1; and the TUPLTYPE field is
+equal to the current tupletype.
+.sp
+This command has no effect upon the current drawing state. E. g. it does
+not modify the current drawing mode, the current vertex list, etc.
+.sp
+One may issue an arbitrary number of \fBprint\fP commands at different
+positions in the input instruction sequence to produce a multi-image PAM
+stream.
+
+.TP
+\fBclear\fP [ image | depth ]
+.sp
+Clears the frame buffer. That is, all samples in the image buffer are once
+again set to 0, and all entries in the depth buffer are once again set to the
+maximum permitted depth value.
+.sp
+Optionally, one may provide an argument to only clear either the image
+buffer or the depth buffer individually, while leaving the other intact. With
+the \fBimage\fP argument, only the image buffer is cleared; with the
+\fBdepth\fP argument, only the depth buffer is cleared. Instead of full
+argument names, one may provide a minimum unique abbreviation, which has the
+same effect. The single character \fBz\fP is also accepted as an alias for
+\fBdepth\fP.
+.sp
+Like the \fBprint\fP command, this command has no effect upon the
+current drawing state either.
+
+
+.TP
+\fBreset\fP \fImaxval\fP \fInum_attribs\fP [\fItupletype\fP]
+.sp
+This updates the current maxval and number of attributes per vertex
+(num_attribs), resetting the <u>image</u> buffer with a new maxval and number
+of samples per tuple while at it. The parameter \fImaxval\fP must be an
+integer in the closed range [1, 65535], and \fInum_attribs\fP must be an
+integer in the closed range [1, 20].
+.sp
+Optionally, after the second argument, one may provide a string to be
+assigned to the current \fItupletype\fP. The string goes from the first
+character after the second argument which is not white space and continues
+until (and including) the last character before the end of the line which is
+not white space.  If a new tupletype is not provided, or the provided string
+is longer than 255 characters, the empty string is assigned to the current
+\fItupletype\fP.
+.sp
+The side effects of running this command are
+
+
+.IP \(bu
+
+The new image buffer is completely cleared once the command is executed.
+
+.IP \(bu
+
+All values in the current attribute values list are set to the new maxval.
+
+.IP \(bu
+
+The current vertex list is reset.
+
+
+.sp
+However, it does not touch the depth buffer: it is left the same way as it
+was found before the command. Also the drawing mode remains the same (e. g. if
+\fBpamtris\fP was in FAN mode, it will continue in that same mode, etc.).
+.sp
+If this command is given with an invalid value for \fImaxval\fP or
+\fInum_attribs\fP, it is ignored and therefore none of the above side
+effects apply, nor do the current maxval, num_attribs or tupletype change at
+all.
+.sp
+It is permissible to give a value for \fImaxval\fP and \fInum_attribs\fP
+equal to the current maxval and num_attribs, respectively, although the above
+side effects will still apply even in such cases.
+.sp
+Since this command deals with memory allocation, it may fail to execute
+successfully. If that happens, no lines of input will be read anymore and
+\fBpamtris\fP will be terminated as if the \fBquit\fP command was given.
+.TP
+\fBquit\fP
+.sp
+This terminates \fBpamtris\fP. It will not read any more lines of input
+after this command.
+
+
+
+
+.UN tips
+.SH TIPS
+
+.SS Texturing
+.PP
+It is possible to apply so-called "textures" to images produced with
+\fBpamtris\fP by using a pair of vertex attributes as texture
+coordinates, then using
+.BR "\fBpamchannel\fP" (1)\c
+\& to
+select the appropriate channels in the output image(s), and finally
+processing the result through
+.BR "\fBpamlookup\fP" (1)\c
+\&,
+providing the desired texture file as a "lookup table."  If you are drawing
+pictures in perspective, make sure to provide adequate values for the
+\fIw\fP parameter to your vertex commands
+(
+.UR #cmd_vertex
+see above
+.UE
+\&) so that the resulting samples in
+the images produced by \fBpamtris\fP are perspective-correct. You might
+want to consider using
+.BR "\fBpnmtile\fP" (1)\c
+\& to make
+textures which are inteded to be "repeated" along triangle meshes.
+.PP
+ The animated GIF below is an example of what can be achieved using the
+technique described above (Earth texture from
+.UR https://visibleearth.nasa.gov/view.php?id=73580
+nasa.gov
+.UE
+\&).
+.PP
+.B Rotating Earth
+.IMG -C pamtris_earth.gif
+
+.UN antialias
+.SS Anti-aliased edges
+.PP
+\fBpamtris\fP performs no anti-aliasing on triangle edges by itself.
+However, it is possible to obtain anti-aliased images through a
+"super-sampling" approach: draw your image(s) at a size larger than
+the desired final size, and then, when all postprocessing is done,
+downscale the final image(s) to the desired size. Drawing images with
+twice the desired width and height, then downscaling them to the intended
+size while disregarding gamma (i.e. what \fBpamscale\ -linear\fP does)
+often produces good enough results; but the larger the ratio \fI
+"size\ of\ original\ image"\ /\ "size\ of\ downscaled\  image"
+\fP, the better the quality of the anti-aliasing effect.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pampick" (1)\c
+\&
+.BR "pamchannel" (1)\c
+\&
+.BR "pamstack" (1)\c
+\&
+.BR "pamlookup" (1)\c
+\&
+.BR "pamarith" (1)\c
+\&
+.BR "pamscale" (1)\c
+\&
+.BR "pamdepth" (1)\c
+\&
+.BR "pamexec" (1)\c
+\&
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtris\fP was new in Netpbm 10.84 (September 2018).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtris.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamunlookup.1 b/upstream/mageia-cauldron/man1/pamunlookup.1
new file mode 100644
index 00000000..07c97be7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamunlookup.1
@@ -0,0 +1,143 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamunlookup User Manual" 0 "09 August 2015" "netpbm documentation"
+
+.SH NAME
+pamunlookup - inverse of pamlookup
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamunlookup\fP
+\fB-lookupfile=\fP\fIlookupfile\fP
+\fIinputfile\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamunlookup\fP is best described as the inverse of \fBpamlookup\fP
+(without \fB-byplane\fP).  For example, the following normally yields output
+identical to the input:
+
+.nf
+\f(CW
+    $ cat input.ppm | \e
+        pamunlookup -lookupfile=map.pam | \e
+        pamlookup -lookupfile=map.pam \e
+        > output.ppm
+\fP
+
+.fi
+.PP
+Specifically, \fBpamunlookup\fP takes an input image and produces an
+output image of the same width and height in which each tuple is a single
+number.  That number is the index in a given lookup table of the tuple value
+that is in the same position in the input image.
+.PP
+You specify the lookup table the same way as for
+.UR pamlookup.html#lookupimage
+\fBpamlookup\fP
+.UE
+\&.
+.PP
+Where a tuple in the input image is not in the lookup table, the
+number \fBpamunlookup\fP places in the output index image is one greater than
+the highest index in the lookup table.  Accordingly, the maxval of the output
+index image is the size of the lookup table.
+
+
+.UN example
+.SS Example
+.PP
+Here is an example of \fBpamunlookup\fP's function.
+.PP
+Consider an input image consisting of a 3x2 PPM as follows:
+
+.TS
+l l l.
+red	yellow	red
+beige	beige	beige
+.TE
+
+and a lookup table consisting of a 3x1 PPM image as follows:
+
+.TS
+l l l.
+red	yellow	beige
+.TE
+
+The lookup table above says Index 0 corresponds to the color red,
+Index 1 corresponds to yellow, and Index 2 corresponds to beige.  The output
+of \fBpamunlookup\fP is the following index image:
+
+.TS
+l l l.
+0	1	0
+2	2	2
+.TE
+
+.UN misc
+.SS Miscellaneous
+.PP
+The \fIinputfile\fP argument identifies the file containing the index PAM
+or PNM image.  \fB-\fP means Standard Input.  It won't work if both the input
+image file and lookup table file are Standard Input.
+
+The output index image goes to Standard Output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamunlookup\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-lookupfile=\fP\fIlookupfile\fP
+\fIlookupfile\fP names the file that contains the PAM or PNM
+image that is the lookup table.  This option is mandatory.
+
+
+
+     
+.UN seealso
+.SH SEE ALSO
+.BR "pamlookup" (1)\c
+\&,
+.BR "ppmchange" (1)\c
+\&,
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamunlookup\fP was new in Netpbm 10.72 (September 2015).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamunlookup.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamvalidate.1 b/upstream/mageia-cauldron/man1/pamvalidate.1
new file mode 100644
index 00000000..3ac976a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamvalidate.1
@@ -0,0 +1,85 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamvalidate User Manual" 0 "22 March 2014" "netpbm documentation"
+
+.SH NAME
+
+pamvalidate - validate Netpbm image format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamvalidate\fP
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamvalidate\fP copies a Netpbm image from Standard Input to Standard
+Output, except that if there are certain violations of the image format in the
+input, \fBpamvalidate\fP fails \fIwithout producing any output\fP.
+.PP
+This is most useful in a pipeline, before a stage you don't want to start
+working on Netpbm input until it knows it can get all the way through it.  For
+example, assume you are converting PPM images to PNG and you don't want to
+produce a partial PNG file under any circumstance.  If you just
+use \fBpnmtopng\fP, and the PPM input is truncated halfway through the
+raster, \fBpnmtopng\fP fails, but also produces about half of a PNG file.
+To prevent that, pass your PPM input through \fBpamvalidate\fP on its way
+to \fBpnmtopng\fP.  Then, \fBpamvalidate\fP will fail, and consequently
+the pipeline will fail, before \fBpnmtopng\fP has seen any input and 
+therefore before \fBpnmtopng\fP has produced any output.
+.PP
+These are the kinds of format violations \fBpamvalidate\fP detects:
+
+
+.IP \(bu
+A purported sample value exceeds the declared maxval.
+.IP \(bu
+The stream ends prematurely.
+
+.PP
+This program works on multi-image streams, producing a corresponding output
+stream.
+.PP
+See \fBpamfix\fP for a way to salvage an invalid Netpbm image stream.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpamvalidate\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+.BR "pamfix" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamvalidate\fP was new in Netpbm 10.66 (March 2014).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamvalidate.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamwipeout.1 b/upstream/mageia-cauldron/man1/pamwipeout.1
new file mode 100644
index 00000000..57581b95
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamwipeout.1
@@ -0,0 +1,104 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamwipeout User Manual" 0 "26 February 2011" "netpbm documentation"
+
+.SH NAME
+pamwipeout - replace detail with smooth gradient from one edge to the other
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpamwipeout\fP
+{\fB-lr | -tb\fP}
+[\fB\fIfilename\fP\fP]
+.PP
+Minimum unique abbreviation of options is acceptable. 
+You may use double hyphens instead of single hyphen to denote options.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+The \fBpamwipeout\fP utility takes a Netpbm image as input and the uses
+two opposite edges of the image to wipe out anything in between.  You can use
+it in combination with \fBpamcut\fP and \fBpnmpaste\fP / \fBpamcomp\fP to
+remove unwanted parts of a larger image.  The program replaces the pixels in
+between the two edges with a gradient from one edge to the other.
+.PP
+In \fBtop-bottom\fP mode, the program reads the whole image into memory
+before it can start processing.  In \fBleft-right\fP it will read the image a
+row at the time, process that row and write it to the output file.  Therefore,
+in case of very large images, it may be better to use instead of
+"\fBpamwipeout -tb\fP" a pipe of "\fBpamflip -cw | pamwipeout -lr | pamflip
+-ccw\fP".
+.PP
+In his blog at
+ 
+.UR http://www.i-am.ws/entry/pnmblend_disappearing_act
+www.i-am.ws
+.UE
+\&,
+the author wrote about a predecessor of "pamwipeout" at the time named
+"pnmblend". It shows a good example of what can be accomplished with this
+utility.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+\fB\fIFilename\fP\fP is the name of the input file. If you don't
+specify this, \fBpamwipeout\fP reads the image from Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamwipeout\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-tb\fP | \fB-lr\fP
+.sp
+This option chooses between a vertical and a horizontal gradient.  You must
+specify one of these, but not both.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\& and
+.BR "pamflip" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pnmpaste" (1)\c
+\&.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamwipeout\fP was new in Netpbm 10.54 (March 2011).
+
+.UN authors
+.SH AUTHORS
+.PP
+\fIWillem van Schaik\fP
+wrote this program in January 2011 and contributed it to Netpbm.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamwipeout.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pamx.1 b/upstream/mageia-cauldron/man1/pamx.1
new file mode 100644
index 00000000..c3cef9a0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamx.1
@@ -0,0 +1,268 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamx User Manual" 0 "02 July 2011" "netpbm documentation"
+
+.SH NAME
+pamx - display Netpbm image in X Window System window
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamx\fP
+
+[\fB-fullscreen\fP]
+[\fB-install\fP]
+[\fB-private\fP]
+[\fB-fit\fP]
+[\fB-pixmap\fP]
+[\fB-verbose\fP]
+[\fB-display=\fP\fIx-display\fP]
+[\fB-title=\fP\fItext\fP]
+[\fB-foreground=\fP\fIcolor\fP]
+[\fB-background=\fP\fIcolor\fP]
+[\fB-border=\fP\fIcolor\fP]
+[\fB-geometry=\fP\fIx-geometry-string\fP]
+[\fB-visual=\fP\fIname\fP] \fInetpbm_file\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and its
+value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamx\fP displays a Netpbm image in an X Window System window.
+It is like a very simple version of the classic X image viewer
+\fBxloadimage\fP.
+.PP
+If you don't specify the input file \fInetpbm_file\fP, the input is
+from Standard Input.  The input image can be any Netpbm image format.
+If the input is a multi-image stream, \fBpamx\fP ignores all but the
+first image.
+.PP
+\fBpamx\fP is not the best choice for general purpose viewing of
+images, because it is a traditional simple Netpbm building block.  It
+is a good thing to build into other programs and can be useful for
+debugging more complex systems, but you can get much more powerful
+viewers that can display Netpbm images.  For example, \fBxloadimage\fP,
+\fBxli\fP, \fBxzgv\fP, and any web browser.
+.PP
+The program \fBxwud\fP (X Window Undump) is part of the X Window System
+and performs the same basic display function, though with input in the special
+X Window Dump format (for which Netpbm has converters).
+.PP
+The initial window is at most 90% of the size of the display unless
+the window manager does not correctly handle window size requests or
+if you've used the \fB-fullscreen\fP option.  You may move the image
+around in the window by dragging with the first mouse button.  The
+cursor will indicate which directions you may drag, if any.  You may
+exit the window by typing 'q' or control-C when the keyboard focus is
+on the window.
+.PP
+\fBppmsvgalib\fP is a similar program that displays an image on a
+Linux system without the need for the X Window System.
+
+
+.UN resource
+.SH X RESOURCE CLASS
+.PP
+\fBpamx\fP uses the resource class name \fBXloadimage\fP for
+window managers which need this resource set.  This is, of course, the
+same resource class that the conventional viewer program
+\fBxloadimage\fP uses.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamx\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-border=\fP\fIcolor\fP
+This sets the background portion of the window which is not
+covered by any images to be \fIcolor\fP.
+
+.TP
+\fB-display=\fP\fIdisplay_name\fP
+This names the X display in which to put the window.  E.g. \fB0:0\fP.
+
+.TP
+\fB-fit\fP
+Force image to use the default visual and colormap.  This is
+useful if you do not want technicolor effects when the colormap focus
+is inside the image window, but it may reduce the quality of the
+displayed image.
+
+.TP
+\fB-fullscreen\fP
+Use the entire screen to display the image.
+
+.TP
+\fB-geometry=\fP\fIW\fP\fBx\fP\fIH\fP[{\fB+\fP,\fB-\fP}\fIX\fP{\fB+\fP,\fB-\fP}\fIY\fP
+This sets the size and position of the window in which \fBpamx\fP
+displays the image.
+.sp
+By default, the window size exactly matches the image size, except that
+if you don't specify \fB-fullscreen\fP, the maximum is 90% of the screen
+dimensions.
+
+.TP
+\fB-install\fP
+Forcibly install the image's colormap when the window is focused.
+This violates ICCCM standards and only exists to allow operation with
+naive window managers.  Use this option only if your window manager
+does not install colormaps properly.
+
+.TP
+\fB-pixmap\fP
+Force the use of a pixmap as backing-store.  This is provided for
+servers where backing-store is broken (such as some versions of the
+AIXWindows server).  It may improve scrolling performance on servers
+which provide backing-store.
+
+.TP
+\fB-private\fP
+Force \fBpamx\fP to use of a private colormap.  By default,
+\fBpamx\fP allocates colors shared unless there are not enough colors
+available.
+
+.TP
+\fB-verbose\fP
+Causes \fBpamx\fP to print various information about what it's
+doing to Standard Error.
+
+.TP
+\fB-visual=\fP\fIvisual_name\fP
+Force the use of a specific visual type to display an image.  By
+default, \fBpamx\fP tries to pick the best available image for a
+particular image type.  The available visual types are:
+\fBDirectColor\fP, \fBTrueColor\fP, \fBPseudoColor\fP,
+\fBStaticColor\fP, \fBGrayScale\fP, and \fBStaticGray\fP.
+You may use the shortest unique prefix of these names, and case is
+not significant.
+
+.TP
+\fB-background=\fP\fIcolor\fP
+Use \fIcolor\fP as the background color instead of the default
+(usually white but this depends on the image type) if you are
+transferring a monochrome image to a color display.
+
+.TP
+\fB-foreground=\fP\fIcolor\fP
+Use \fIcolor\fP as the foreground color instead of black if you are
+transferring a monochrome image to a color display.  You can also use
+this to invert the foreground and background colors of a monochrome
+image.
+
+.TP
+\fB-title=\fP\fItext\fP
+Set the title bar title of the window.  Default is the file name of
+the input file, or "stdin" if the image is from Standard Input.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmsvgalib" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBxzgv\fP,
+\fBxwud\fP,
+\fBxloadimage\fP,
+\fBxli\fP
+
+
+.UN author
+.SH AUTHOR
+.PP
+\fBpamx\fP is by Bryan Henderson, in March 2006, based on
+\fBxloadimage\fP by Jim Frost, Centerline Software,
+jimf@centerline.com, 1989-1993.
+.PP
+Jim's code contained the following copyright notice and license:
+
+.RS
+.PP
+Copyright 1989, 1993 Jim Frost
+   
+.PP
+Permission to use, copy, modify, distribute, and sell this software
+and its documentation for any purpose is hereby granted without fee,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.  The author makes no representations about
+the suitability of this software for any purpose.  It is provided "as
+is" without express or implied warranty.
+   
+.PP
+THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+.RE
+.PP
+Lots of other people contributed to Xloadimage, and they are listed
+in the file COPYRIGHT in the source code.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamx\fP was new in Netpbm 10.34 (May 2006).
+.PP
+\fBpamx\fP is essentially based on the classic X displayer program
+\fBxloadimage\fP by Jim Frost, 1989.  Bryan Henderson stripped it
+down and adapted it to Netpbm in March 2006.
+.PP
+The following features of \fBxloadimage\fP are left out of \fBpamx\fP,
+to be more compatible with Netpbm's philosophy of simple building blocks.
+Note that there are other programs in Netpbm that do most of these things:
+
+.IP \(bu
+zoom in/out
+.IP \(bu
+ability to accept formats other than Netpbm
+.IP \(bu
+image transformations (brightening, clipping, rotating, etc)
+.IP \(bu
+decompressing and other decoding of input
+.IP \(bu
+ability to display on the root window
+.IP \(bu
+slide show
+
+
+\fBpamx\fP also differs from \fBxloadimage\fP in that it uses
+Libnetpbm.
+.PP
+There is virtually no code from \fBxloadimage\fP actually in
+\fBpamx\fP, because Bryan rewrote it all to make it easier to
+understand.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamx.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/paste.1 b/upstream/mageia-cauldron/man1/paste.1
new file mode 100644
index 00000000..4934cec4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/paste.1
@@ -0,0 +1,47 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PASTE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+paste \- merge lines of files
+.SH SYNOPSIS
+.B paste
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write lines consisting of the sequentially corresponding lines from
+each FILE, separated by TABs, to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-d\fR, \fB\-\-delimiters\fR=\fI\,LIST\/\fR
+reuse characters from LIST instead of TABs
+.TP
+\fB\-s\fR, \fB\-\-serial\fR
+paste one file at a time instead of in parallel
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David M. Ihnat and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/paste>
+.br
+or available locally via: info \(aq(coreutils) paste invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/pathchk.1 b/upstream/mageia-cauldron/man1/pathchk.1
new file mode 100644
index 00000000..158dad68
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pathchk.1
@@ -0,0 +1,42 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PATHCHK "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+pathchk \- check whether file names are valid or portable
+.SH SYNOPSIS
+.B pathchk
+[\fI\,OPTION\/\fR]... \fI\,NAME\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Diagnose invalid or unportable file names.
+.TP
+\fB\-p\fR
+check for most POSIX systems
+.TP
+\fB\-P\fR
+check for empty names and leading "\-"
+.TP
+\fB\-\-portability\fR
+check for all POSIX systems (equivalent to \fB\-p\fR \fB\-P\fR)
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Paul Eggert, David MacKenzie, and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/pathchk>
+.br
+or available locally via: info \(aq(coreutils) pathchk invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/pbmclean.1 b/upstream/mageia-cauldron/man1/pbmclean.1
new file mode 100644
index 00000000..51e8c062
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmclean.1
@@ -0,0 +1,167 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmclean User Manual" 0 "19 November 2011" "netpbm documentation"
+
+.SH NAME
+pbmclean - despeckle a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmclean\fP
+[\fB-minneighbors=\fP\fIN\fP]
+[\fB-black\fP|\fB-white\fP]
+[\fB-extended\fP]
+[\fIpbmfile\fP]
+
+.SH OPTION USAGE
+.PP
+You can use the minimum unique abbreviation of the options.  You
+can use two hyphens instead of one.  You can separate an option name
+from its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmclean\fP cleans up a PBM image of random specks.  It reads a
+PBM image as input and outputs a PBM that is the same as the input
+except with isolated pixels inverted.
+.PP
+You can use \fBpbmclean \fP to clean up "snow" on bitmap
+images.
+.PP
+There are two ways \fBpbmclean\fP can define "isolated" pixels:
+simple and extended.  When you specify \fB-extended\fP, \fBpbmclean\fP
+uses extended; otherwise it uses basic.
+
+.UN basic
+.SS Basic Mode
+.PP
+In basic mode, \fBpbmclean\fP looks at each pixel individually, and any
+pixel that doesn't have at least a minimum number of pixels of the same color
+touching it is considered isolated and \fBpbmclean\fP erases it.
+.PP
+The \fB-minneighbors\fP option specifies the minimum number of neighboring
+pixels of the same color for a pixel \fInot\fP to be considered
+isolated.
+.PP
+For example, if \fB-minneighbors\fP is two and there are two contiguous
+black pixels in an otherwise white field, each of those pixels is isolated,
+so \fBpbmclean\fP erases them - turns both white.
+.PP
+The default minimum 1 pixel - \fBpbmclean\fP flips only completely
+isolated pixels.
+.PP
+(A \fB-minneighbors\fP value greater than 8 generates a completely
+inverted image (but use \fBpnminvert\fP to do that) -- or a
+completely white or completely black image with the \fB-black\fP or
+\fB-white\fP option).
+.PP
+\fBpbmclean\fP considers the area beyond the edges of the image to
+be white.  (This matters when you consider pixels right on the edge of
+the image).
+.PP
+\fBpbmclean\fP does not distinguish between foreground and background; by
+default, it flips isolated pixels of either color.  But you can
+specify \fB-black\fP or \fB-white\fP to have it flip only pixels of one
+color.
+
+.UN extended
+.SS Extended Mode
+.PP
+In extended mode, \fBpbmclean\fP erases all blobs which don't have the
+specified minimum number of pixels.  A blob is a set of contiguous pixels of
+the foreground color.  The minimum number of pixels is one plus
+the \fB-minneighbors\fP value.  You specify the foreground color with
+\fB-black\fP and \fB-white\fP (default is black).
+.PP
+For example, if \fB-minneighbors\fP is 2 and the foreground color is
+black, and the image contains a straight line 4 pixels long, \fBpbmclean\fP
+erases that -- turns all four pixels white.  \fBpbmclean\fP also erases
+4 pixels in a square or L-shape.
+.PP
+The default \fB-minneighbors\fP is 4, so a blob must have at least 5
+pixels to escape \fBpbmclean\fP's purge.
+.PP
+Extended mode was new in Netpbm 10.56 (September 2011).
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmclean\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-black\fP
+
+.TP
+\fB-white\fP
+Flip pixels of the specified color.  By default, if you specify
+neither \fB-black\fP nor \fB-white\fP, \fBpbmclean\fP flips both
+black and white pixels which do not have sufficient identical
+neighbors.  If you specify \fB-black\fP, \fBpbmclean\fP leaves the
+white pixels alone and just erases isolated black pixels.  Vice versa
+for \fB-white\fP.  You may specify both \fB-black\fP and
+\fB-white\fP to get the same as the default behavior.
+
+.TP
+\fB-minneighbors=\fP\fIN\fP
+This determines how many pixels must be in a cluster in order
+for \fBpbmclean\fP to consider them legitimate and not clean them
+out of the image.  See 
+.UR #description
+Description
+.UE
+\&.
+.sp
+Before December 2001, \fBpbmclean\fP accepted \fB-\fP\fIN\fP
+instead of \fB-minneighbors\fP.  Before Netpbm 10.27 (March 2005),
+\fB-minneighbors\fP was \fB-minneighbor\fP.
+
+.TP
+\fB-extended\fP
+\fBpbmclean\fP uses extended, as opposed to basic, isolated pixel
+detection.
+.sp
+This option was new in Netpbm 10.56 (September 2011).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Angus Duggan
+Copyright (C) 1989 by Jef Poskanzer.
+Copyright (C) 2001 by Michael Sternberg.
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.  This software is provided "as is" without express or
+implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmclean.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmlife.1 b/upstream/mageia-cauldron/man1/pbmlife.1
new file mode 100644
index 00000000..e07f4f06
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmlife.1
@@ -0,0 +1,56 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmlife User Manual" 0 "21 February 1991" "netpbm documentation"
+
+.SH NAME
+
+pbmlife - apply Conway's rules of Life to a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmlife\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmlife\fP reads a PBM image as input, applies the rules
+of Life to it for one generation, and produces a PBM image as output.
+.PP
+A white pixel in the image is interpreted as a live beastie, and a
+black pixel as an empty space.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmlife\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmlife.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmmake.1 b/upstream/mageia-cauldron/man1/pbmmake.1
new file mode 100644
index 00000000..03059cbd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmmake.1
@@ -0,0 +1,80 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmmake User Manual" 0 "13 December 2003" "netpbm documentation"
+
+.SH NAME
+
+pbmmake - create a blank bitmap of a specified size
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmmake\fP
+[\fB-white\fP|\fB-black\fP|\fB-gray\fP]
+\fIwidth\fP
+\fIheight\fP
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmmake\fP produces a PBM image of the specified width and
+height, either all black, all white, or a dithered gray.  The default
+is white.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmmake\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-white\fP
+.TP
+\fB-black\fP
+.TP
+\fB-gray\fP
+.sp
+In addition to the usual \fB-white\fP and \fB-black\fP, this
+program implements \fB-gray\fP.  This gives a simple 50% gray pattern
+with 1's and 0's alternating.
+.sp
+With none of the above specified, the output image will be entirely
+white.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmmake" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmmake.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmmask.1 b/upstream/mageia-cauldron/man1/pbmmask.1
new file mode 100644
index 00000000..49f11545
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmmask.1
@@ -0,0 +1,131 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmmask User Manual" 0 "28 September 2021" "netpbm documentation"
+
+.SH NAME
+
+pbmmask - create a mask bitmap from a regular bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmmask\fP
+[\fB-expand\fP]
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmmask\fP reads a PBM image as input and generates a
+corresponding mask of the foreground areas as another PBM image.
+.PP
+This is probably obsoleted by \fBpambackground\fP.
+  
+.PP
+The color to be interpreted as "background" is determined automatically.
+Regardless of which color is background, the mask will be white where the
+background is and black where the figure is.
+.PP
+This lets you do a masked paste like this, for objects with a black
+background:
+
+.nf
+    pbmmask obj > objmask
+    pnmpaste < dest -and objmask <x> <y> | pnmpaste -or obj <x> <y>
+
+.fi
+
+For objects with a white background, you can either invert them or
+add a step:
+.nf
+    pbmmask obj > objmask
+    pnminvert objmask | pnmpaste -and obj 0 0 > blackback
+    pnmpaste < dest -and objmask <x> <y> | pnmpaste -or blackback <x> <y>
+
+.fi
+
+Note that this three-step version works for objects with black backgrounds
+too, if you don't care about the wasted time.
+.PP
+You can also use masks with grayscale and color images, using the
+\fIpnmarith\fP tool.  For instance:
+
+.nf
+    ppmtopgm obj.ppm | pamditherbw -threshold | pbmmask > objmask.pbm
+    pnmarith -multiply dest.ppm objmask.pbm > t1.ppm
+    pnminvert objmask.pbm | pnmarith -multiply obj.ppm - > t2.ppm
+    pnmarith -add t1.ppm t2.ppm
+
+.fi
+
+An interesting variation on this is to pipe the mask through
+\fIpnmsmooth\fP before using it.  This makes the boundary between the
+two images less sharp.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmmask\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-expand\fP
+Expands the mask by one pixel out from the image.  This is useful
+if you want a little white border around your image.  (A better
+solution might be to turn the \fBpbmlife\fP program into a general
+cellular automaton tool...)
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pambackground" (1)\c
+\&
+.BR "ppmcolormask" (1)\c
+\&,
+.BR "pnmpaste" (1)\c
+\&,
+.BR "pnminvert" (1)\c
+\&,
+.BR "pnmarith" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&
+.BR "pbm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmmask\fP is one of the oldest programs in Netpbm.  In September 2021,
+  the date on this manual was August 8, 1989 (being the date of the last
+  substantial update).  We updated the page  then just to add this historical
+  information and recommend \fBpambackground\fP.
+.PP
+It is likely that when Bryan wrote \fBpambackground\fP in 2006, he was
+  unaware \fBpbmmask\fP existed.  Otherwise, he would presumably have
+  replaced \fBpbmmask\fP with a wrapper around \fBpambackground\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmmask.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmminkowski.1 b/upstream/mageia-cauldron/man1/pbmminkowski.1
new file mode 100644
index 00000000..34453d22
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmminkowski.1
@@ -0,0 +1,41 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmminkowski User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+
+pbmminkowski - compute Minkowski integral
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmminkowski\fP \fIpbmfile\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpbmminkowski\fP computes the 3 Minkowski integrals of a PBM image. 
+.PP
+It is similar to
+.BR "\fBpgmminkowski\fP" (1)\c
+\&.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmminkowski" (1)\c
+\&
+.BR "pbm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmminkowski.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmnoise.1 b/upstream/mageia-cauldron/man1/pbmnoise.1
new file mode 100644
index 00000000..8e9e32aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmnoise.1
@@ -0,0 +1,177 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmnoise User Manual" 0 "18 December 2021" "netpbm documentation"
+
+.SH NAME
+pbmnoise - create a PBM image made up of white noise
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmnoise\fP \fIwidth\fP \fIheight\fP
+
+[\fB-ratio=\fP\fIM\fP\fB/\fP\fIN\fP]
+[\fB-pack\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+[\fB-endian=\fP]{\fBbig\fP|\fBlittle\fP|\fBnative\fP|\fBswap\fP}] 
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white space
+in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmnoise\fP creates a PBM image with random pixels.  You specify the
+probability each pixel will be black or white (essentially, the proportion of
+black to white pixels in the image).
+.PP
+You specify the dimensions of the image with the \fIwidth\fP and
+\fIheight\fP arguments.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm (most
+notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmnoise\fP recognizes the following command line options:
+
+
+.TP
+\fB-ratio=\fP\fIM\fP\fB/\fP\fIN\fP
+The proportion of black pixels in the generated image.
+.sp
+To be precise, this is the probability that any given pixel will be black.
+By the law of large numbers, we can expect the proportion of black pixels in a
+reasonably large image to be close to this fraction.
+.sp
+The option value is a fraction.  The denominator must be 1 or an integer
+power of 2 up to 65536.  the numerator must be 0 or a positive integer not
+exceeding denominator.
+.sp
+The default is 1/2, meaning the output image has essentially the same
+number of black and white pixels.
+.sp
+If the ratio is 0 the output image is entirely white.  If 1, the output is
+entirely black.
+
+.TP
+\fB-pack\fP
+The program generates pixels in 32-bit units discarding any fractional pixels
+at row ends by default.  When this option is specified, the unused pixels are
+carried over to the next row, eliminating waste in exchange for some overhead
+cost.
+.sp
+Using this option improves performance when the image width is small.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that generates the pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpbmnoise\fP uses a seed derived from the time of day and
+process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+
+.TP
+\fB-endian=\fP\fImode\fP
+\fBpbmnoise\fP internally generates random 32-bit integers and uses the
+machine's binary encoding of those integers as strings of pixels.  Because the
+integers are random, it doesn't normally matter what binaary encoding is used
+for them, but if you need consistent results between machines using the same
+random number generator, it matters.  For that reason (mainly for testing the
+program), this option lets you control that encoding, between big-endian and
+little-endian.
+.sp
+\fImode\fP is one of the following:
+
+
+.TP
+\fBbig\fP
+Force big-endian output by rearranging bytes on little-endian machines.  No
+effect on big-endian machines.
+
+.TP
+\fBlittle\fP
+Likewise, force little-endian output.
+
+.TP
+\fBnative\fP
+Do not rearrange anything.  This is the default.
+
+.TP
+\fBswap\fP
+Always swap regardless of system endianness.
+
+
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+This generates a random PBM image with roughly one-third of pixels colored
+black:
+.nf\f(CW
+  pbmnoise -ratio=11/32 1200 1200 > random.pbm
+\fP
+.fi
+.PP
+The following is an alternate method for generating a random PBM image
+which uses \fBpgmnoise\fP and \fBpgmtopbm\fP instead of \fBpbmnoise\fP.  It
+is less efficient.
+.nf\f(CW
+  pgmnoise -maxval=100 1200 1200 | \e
+    pgmtopbm -threshold -value=0.333 > random.pbm
+\fP
+.fi
+.PP
+This generates a random PPM image, maxval 1:
+.nf\f(CW
+  pbmnoise 600 400 > red.pbm
+  pbmnoise 600 400 > green.pbm
+  pbmnoise 600 400 > blue.pbm
+  rgb3topbm red.pbm green.pbm blue.pbm > random.ppm
+\fP
+.fi
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+.BR "pgmnoise" (1)\c
+\&
+.BR "pgmtopbm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmnoise\fP was new in Netpbm 10.97 (December 2021).
+.PP
+In Netpbm before that, you can use \fBpgmnoise\fP.
+
+  
+.UN author
+.SH AUTHOR
+.PP
+Akira F Urushibata wrote this program and contributed it to the public domain
+in December 2021.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmnoise.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmpage.1 b/upstream/mageia-cauldron/man1/pbmpage.1
new file mode 100644
index 00000000..7a7f26f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmpage.1
@@ -0,0 +1,108 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmpage User Manual" 0 "08 June 2019" "netpbm documentation"
+
+.SH NAME
+pbmpage - create a one page test pattern for printing
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmpage\fP
+[\fB-a4\fP]
+\fItest_pattern\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmpage\fP generates a one page test pattern to print on a
+sheet of paper, for use in calibrating a printer.  The test pattern in
+is PBM format.
+.PP
+\fBpbmpage\fP produces an image intended for 600 dots per inch
+printer resolution.
+.PP
+If you are printing on an HP PPA printer, you can convert the
+output of this program to a stream that you can feed to the printer
+with \fBpbmtoppa\fP.
+.PP
+Bear in mind that when you print the test pattern, you are testing not
+only the printer, but any converter or driver software along the
+printing path.  Any one of these components may adjust margins, crop
+the image, erase edges, and such.
+.PP
+If, because of addition of margins, the printer refuses to print the
+image because it is too big, use \fBpamcut\fP to cut the right and
+bottom edges off the test pattern until it is small enough to print.
+.PP
+\fItest_pattern \fP is the number of the test pattern to generate,
+as follows.  The default is \fB1\fP.
+
+
+.TP
+\fB1\fP
+A black on white grid ruled in numbers of pixels.  A black one pixel box
+is at the very edges of the paper.
+.sp
+Before Netpbm 10.18 (August 2003), the perimeter box was not there.
+
+.TP
+\fB2\fP
+A vertical line segment, one pixel wide, extending 1/2" up from the
+exact center of the page.
+.TP
+\fB3\fP
+Two diagonal line segments, one starting at the upper left corner of the
+page, the other starting from the lower right corner of the page.  Both
+extend 1/2" toward the center of the page at 45 degrees.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmpage\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-a4\fP
+Generate an image for A4 (European) paper.  Without this option,
+\fBpbmpage\fP generates an image for US standard paper (8 1/2"
+wide x 11" high).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoppa" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Tim Norman.  Copyright (C) 1998.  Licensed under GNU Public License
+.PP
+Manual page by Bryan Henderson, May 2000.  Contributed to the public
+domain by its author.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmpage.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmpscale.1 b/upstream/mageia-cauldron/man1/pbmpscale.1
new file mode 100644
index 00000000..e5d111f1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmpscale.1
@@ -0,0 +1,79 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmpscale User Manual" 0 "03 October 2003" "netpbm documentation"
+
+.SH NAME
+
+pbmpscale - enlarge a PBM image with edge smoothing
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmpscale\fP
+\fIN\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmpscale\fP reads a PBM image as input, and outputs a PBM
+image enlarged N times.  \fBpbmpscale\fP does this enlargement by
+pixel replication, with some additional smoothing of corners and
+edges.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmpscale\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamstretch" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Angus Duggan
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.  This software is provided "as is" without express or
+implied warranty.
+
+.UN notes
+.SH NOTES
+.PP
+\fBpbmpscale\fP works best for enlargements of 2. To do
+enlargements greater than 2, you should do as many enlargements of 2 as
+possible, then enlarge by the remaining factor.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmpscale.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmreduce.1 b/upstream/mageia-cauldron/man1/pbmreduce.1
new file mode 100644
index 00000000..2316171c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmreduce.1
@@ -0,0 +1,109 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmreduce User Manual" 0 "13 April 2016" "netpbm documentation"
+
+.SH NAME
+pbmreduce - read a PBM image and reduce it N times
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmreduce\fP
+[\fB-floyd\fP|\fB-fs\fP|\fB-threshold\fP]
+[\fB-value\fP \fIval\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+\fIN\fP
+[\fIpbmfile\fP]
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmreduce\fP reads a PBM image as input and reduces it by a
+factor of \fIN\fP, producing a PBM image as output.
+.PP
+\fBpbmreduce\fP duplicates a lot of the functionality of
+\fBpamditherbw\fP; you could do something like \f(CWpamscale |
+pamditherbw\fP, but \fBpbmreduce\fP is a lot faster.
+.PP
+You can use \fBpbmreduce\fP to "re-halftone" an image.
+Let's say you have a scanner that only produces black&white, not
+grayscale, and it does a terrible job of halftoning (most b&w
+scanners fit this description).  One way to fix the halftoning is to
+scan at the highest possible resolution, say 300 dpi, and then reduce
+by a factor of three or so using \fBpbmreduce\fP.  You can even
+correct the brightness of an image, by using the \fB-value\fP option.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmreduce\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-threshold\fP
+By default, \fBpbmreduce\fP does the halftoning after the reduction via
+boustrophedonic Floyd-Steinberg error diffusion; however, you can use this
+option to specify simple thresholding.  This gives better results when
+reducing line drawings.
+
+.TP
+\fB-floyd\fP, \fB-fs\fP
+Specify the Floyd-Steinberg error diffusion method.  This is the
+default.
+
+.TP
+\fB-value\fP
+.sp
+This option alters the thresholding value for all quantizations.  It should
+be a real number between 0 and 1.  Above 0.5 means darker images; below 0.5
+means lighter.
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that controls the
+halftoning.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+This option was new in Netpbm 10.75 (June 2016).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmreduce.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtext.1 b/upstream/mageia-cauldron/man1/pbmtext.1
new file mode 100644
index 00000000..a0297bf6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtext.1
@@ -0,0 +1,541 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtext User Manual" 0 "29 May 2020" "netpbm documentation"
+
+.SH NAME
+pbmtext - render text into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtext\fP
+[\fB-wchar\fP]
+[\fB-font\fP \fIfontfile\fP]
+[\fB-builtin\fP \fIfontname\fP]
+[\fB-space\fP \fIpixels\fP]
+[\fB-lspace\fP \fIpixels\fP]
+[\fB-nomargins\fP]
+[\fB-width\fP \fIpixels\fP]
+[\fB-load-entire-font\fP]
+[\fB-verbose\fP]
+[\fB-dry-run\fP]
+[\fB-text-dump\fP]
+[\fItext\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtext\fP takes the specified text, either a single line from
+the command line or multiple lines from standard input, and renders it
+into a PBM graphical image.
+.PP
+The text rendered is all the non-option command line arguments, separated
+by spaces, except that if there are no non-option command line arguments, it
+is Standard Input.
+  
+.PP
+In the image, each line of input is a line of output.  Lines are
+  delimited by newline characters.
+.PP
+The program renders any character in an input line that is not in the font
+  as a space.  Note that control characters usually aren't in the font, but
+  some fonts have glyphs for them.  The newline characters that delimit lines
+  in of Standard Input are not in any line.
+.PP
+Tab characters are rendered as a number of spaces; any entry in the font
+  for the tab code point is irrelevant.  The number of spaces is such as to
+  create tab stops every 8 characters.  Note that this is not useful if the
+  font is proportional.
+  
+.PP
+The image is just wide enough for the longest line of text, plus
+margins, and just high enough to contain the lines of text, plus
+margins.
+.PP
+The left and right margins are twice the width of the widest
+character in the font; the top and bottom margins are the height of
+the tallest character in the font.  But if the text is only one line,
+all the margins are half of this.  You can use the \fB-nomargins\fP option
+to eliminate the margins.
+.PP
+\fBpbmtext\fP renders left to right.  It cannot render vertically
+or right to left.
+.PP
+\fBpbmtextps\fP does the same thing as \fBpbmtext\fP, but uses
+Ghostscript to generate the characters, which means you can use
+Postscript fonts.  But it also means you have to have Ghostscript
+installed and it isn't as fast.  Also, \fBpbmtextps\fP generates only
+one line of text, whereas \fBpbmtext\fP can create multiple lines.
+.PP
+\fBpbmtext\fP is meant for simple text.  If you're working with
+a \fIdocument\fP, you would be better off using a document formatting
+program to "print" to a Postscript file, then feeding that Postscript
+to \fBpstopnm\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtext\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-wchar\fP
+.sp
+By default, \fBpbmtext\fP takes a single-byte character stream as input.
+When you specify \fB-wchar\fP, it treats input text as a multibyte character
+stream encoded according to the current locale.  Normally, the user would
+supply a BDF font file encoded in ISO-10646-1 with a \fB-font\fP option.
+.sp
+With \fB-wchar\fP, you cannot supply the text on the command line; it must
+be fed from standard input.
+.sp
+This option was new in Netpbm 10.82 (March 2018).
+
+
+.TP
+\fB-font\fP
+.TP
+\fB-builtin\fP
+\fB-builtin\fP selects a font among those built into Netpbm.
+
+\fB-font\fP selects a font that you supply yourself either as an X
+Window System 
+.UR http://xfree86.org/current/bdf.pdf
+BDF (Bitmap Distribution Format)
+.UE
+\& file or as a PBM file in a special form.
+.sp
+The default is the built in font "bdf."
+.sp
+"bdf" is Times-Roman 15 pixels high.  (That's about 14
+point type printed at 75 dpi).
+.sp
+"fixed" is a built in fixed width font.
+.sp
+For information about other fonts, and how to make one of your own,
+see 
+.UR #fonts
+Fonts
+.UE
+\& below.
+
+
+.TP
+\fB-space\fP \fIpixels\fP
+ Add \fIpixels\fP pixels of space between characters.  This is in
+addition to whatever space surrounding characters is built into the
+font, which is usually enough to produce a reasonable string of text.
+.sp
+\fIpixels\fP may be fractional, in which case the number of
+pixels added varies so as to achieve the specified average.  For
+example \fB-space=1.5\fP causes half the spaces to be 1 pixel and
+half to be 2 pixels.
+.sp
+\fIpixels\fP may be negative to crowd text together, but the
+author has not put much thought or testing into how this works in
+every possible case, so it might cause disastrous results.
+
+.TP
+\fB-lspace\fP \fIpixels\fP
+ Add \fIpixels\fP pixels of space between lines.  This is in
+addition to whatever space above and below characters is built into
+the font, which is usually enough to produce a reasonable line
+spacing.
+.sp
+\fIpixels\fP must be a whole number.
+.sp
+\fIpixels\fP may be negative to crowd lines together, but the
+author has not put much thought or testing into how this works in
+every possible case, so it might cause disastrous results.
+
+.TP
+\fB-nomargins\fP
+By default, \fBpbmtext\fP adds margins all around the image as
+described above.  This option causes \fBpbmtext\fP not to add any
+margins.
+.sp
+Note that there may still be space beyond the edges of the type
+because a character itself may include space at its edges.  To eliminate
+all surrounding background, so the type touches all four edges of the
+image, use \fBpnmcrop\fP.
+
+.TP
+\fB-width\fP \fIpixels\fP
+This specifies how much horizontal space the text is supposed to fit
+into.
+.sp
+If the input is one line, \fBpbmtext\fP breaks it into multiple
+lines as needed to fit the specified width.  It breaks it between
+characters, but does not pay attention to white space; it may break in
+the middle of a word and a line may begin or end with white space.
+.sp
+If the input is multiple lines, \fBpbmtext\fP assumes you already
+have line breaks where they make sense, and \fBpbmtext\fP simply
+truncates each line as needed to fit the specified width.
+
+.TP
+\fB-load-entire-font\fP
+  
+When you use a BDF font, \fBpbmtext\fP will normally load from the font
+    only the characters needed for your text, not wasting time loading other
+    characters.  With this option, \fBpbmtext\fP will instead read the entire
+    font.  It won't make any difference in the rendered output, but it lets
+    you check the integrity of the font file.
+.sp
+This option was new in Netpbm 10.91 (June 2020).  Before that,
+\fBpbmtext\fP always reads the entire font.
+
+.TP
+\fB-verbose\fP
+This makes \fBpbmtext\fP issue informtional messages about its processing.
+
+.TP
+\fB-dry-run\fP
+.sp
+With this option, instead of outputting an image of the text,
+\fBpbmtext\fP just writes to Standard Output a message telling the dimensions
+of the image it would have produced.
+.sp
+You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP.
+.sp
+This option was new in Netpbm 10.75 (June 2016).
+  
+.TP
+\fB-text-dump\fP
+This option causes \fBpbmtext\fP just to write to Standard Output the text in
+ASCII that would be rendered.  The output reflects any text formatting,
+unprintable character substitution, tab expansion, etc.  It is for diagnosing
+problems.  This option was new in Netpbm 10.82 (March 2018).
+.sp
+When \fB-wchar\fP is in effect, the output text will be in the encoding
+specified by the current locale.
+.sp
+You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP.
+.sp
+This option was new in Netpbm 10.82 (March 2018).
+
+
+
+
+.UN usage
+.SH USAGE
+.PP
+Often, you want to place text over another image.  One way to do this is
+with \fBppmlabel\fP.  For more flexible (but complex) drawing of text on an
+image, there is \fBppmdraw\fP.  These do not give you the font options that
+\fBpbmtext\fP does, though.
+.PP
+Another way is to use \fBpbmtext\fP to create an image containing
+the text, then use \fBpamcomp\fP to overlay the text image onto your
+base image.  To make only the text (and not the entire rectangle
+containing it) cover the base image, you will need to give
+\fBpamcomp\fP a mask, via its \fB-alpha\fP option.  You can just use
+the text image itself as the mask, as long as you also specify the
+\fB-invert\fP option to \fBpamcomp\fP.
+.PP
+If you want to overlay colored text instead of black, just use
+\fBppmchange\fP to change all black pixels to the color of your
+choice before overlaying the text image.  But still use the original
+black and white image for the transparency mask.
+.PP
+If you want the text at an angle, use \fBpnmrotate\fP on the text
+image (and transparency mask) before overlaying.
+
+.UN fonts
+.SH FONTS
+.PP
+There are three kinds of fonts you an use with \fBpbmtext\fP:
+
+
+.IP \(bu
+built in
+.IP \(bu
+BDF
+.IP \(bu
+PBM
+
+
+.SS Built In Fonts
+.PP
+There are two built in fonts: \fBbdf\fP and \fBfixed\fP.  You select
+these fonts with a \fB-builtin\fP option.
+.PP
+\fBbdf\fP is the default when you specify no font information on the
+command line.  \fIThe naming reflects the fact that it shares many
+characteristics of BDF style fonts.  When this font was implemented,
+\fBpbmtext\fP did not have the ability to read arbitrary BDF fonts
+specified by the \fB-font\fP option.  There is no external font file
+involved.\fP
+.PP
+\fBbdf\fP is encoded in ISO 8859-1 (Latin 1, 8-bit).  In addition to
+English it can handle most West European languages (Spanish, French, German,
+Swedish ...)  This set lacks the Euro currency sign.
+.PP
+\fBfixed\fP is ASCII (7-bit) only.
+.PP
+While it is not an error to do so, you should not use the above built-in
+fonts with \fB-wchar\fP.
+
+
+.SS BDF Font
+.PP
+BDF is an ancient font format that at one time was standard for the
+X Window System.  Now, you don't see it very often, but you can find
+some BDF fonts on the 
+.UR http://cvsweb.xfree86.org/cvsweb/xc/fonts/bdf/
+Xfree86
+.UE
+\&
+web site.
+.PP
+You can get the full package of the BDF fonts from XFree86 (see
+above) from the 
+.UR http://netpbm.sourceforge.net/bdffont.tgz
+Netpbm web site
+.UE
+\&.
+
+.SS PBM Font
+.PP
+To create a font as a PBM file (to use with the \fB-font\fP
+option), you just create a PBM image of the text matrix below.
+.PP
+The first step is to display text matrix below on the screen,
+e.g. in an X11 window.
+
+.nf
+
+    M ",/^_[`jpqy| M
+
+    /  !"#$%&'()*+ /
+    < ,-./01234567 <
+    > 89:;<=>?@ABC >
+    @ DEFGHIJKLMNO @
+    _ PQRSTUVWXYZ[ _
+    { \e]^_`abcdefg {
+    } hijklmnopqrs }
+    ~ tuvwxyz{|}~  ~
+
+    M ",/^_[`jpqy| M
+
+
+.fi
+.PP
+Make sure it's a fixed width font -- This should display as a
+perfect rectangle.
+.PP
+Also, try to use a simple display program.  Pbmtext divides this
+into a matrix of cells, all the same size, each containing one
+character, so it is important that whatever you use to display it
+display with uniform horizontal and vertical spacing.  Fancy word
+processing programs sometimes stretch characters in both directions to
+fit certain dimensions, and that won't work.  Sometimes a display
+program scales a font to show a character larger or smaller than its
+natural size.  That too won't often work because the rounding involved
+in such scaling causes non-uniform distances between characters.
+.PP
+If you display the text matrix improperly, the usual symptom is
+that when you try to use the font, \fBpbmtext\fP fails with an error
+message telling you that the number of lines in the font isn't
+divisible by 11, or it can't find the blank band around the inner
+rectangle.  Sometimes the symptom is that one of the characters
+displays with a piece of the character that is next to it in the
+matrix.  For example, "l" might display with a little piece
+of the "m" attached on its right.
+.PP
+Do a screen grab or window dump of that text, using for instance 
+\fBxwd\fP, \fBxgrabsc\fP, or \fBscreendump\fP.  Convert the result into a
+pbm file.  If necessary, use \fBpamcut\fP to remove anything you grabbed in
+addition to the text pictured above (or be a wimp and use a graphical editor
+such as Gimp).  Finally, run it through \fBpnmcrop\fP to make sure the edges
+are right up against the text.  \fBpbmtext\fP can figure out the sizes and
+spacings from that.
+.PP
+There are some historical computer fonts, such as that used by the original
+IBM PC, in the form that you can screen-grab and turn into a PBM font file
+available from
+.BR "Stewart
+C Russell" (1)\c
+\&.  There are fonts with various duodecimal digit glyphs at
+.UR http://treisaran.deviantart.com/gallery/38695571/NetPBM-Fonts
+ treisara.deviantart.com
+.UE
+\&.
+.PP
+PBM fonts cannot be used with \fB-wchar\fP.
+
+
+
+.UN multibyte
+.SH MULTI-BYTE INPUT
+.PP
+In the past, English text was encoded in 7-bit ASCII.  8-bit and multibyte
+encodings were needed only for non-English languages.  This is not the case
+today.  As of this writing, 90% of all web pages are encoded in UTF-8.  While
+many of them are actually restricted to 7-bit ASCII, which is a subset of
+UTF-8, English text encoded in UTF-8 commonly employs "66 99" style quotation
+marks, which do not appear in ASCII.
+.PP
+If your input text is UTF-8, you should use \fB-wchar\fP.  You may have to
+tweak the locale setting.  \fBpbmtext\fP recognizes code points up to 65535.
+This is sufficient for the vast majority of text written in modern languages.
+.PP
+In the default single-byte (or "narrow") character
+mode, \fBpbmtext\fP can handle 7-bit and 8-bit character sets.
+Examples are ASCII, ISO 8859 family, koi8-r/u and VISCII.  It is up to
+the user to supply a BDF file covering the necessary glyphs with the
+"-font" option.  The font file must be in the right encoding.
+.PP
+\fBpbmtext\fP does not inspect the encoding of the font file.
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+If the text is from Standard Input, no line may be longer than 4999
+characters.  If one is, the program aborts with an appropriate error message.
+.PP
+If the text is from Standard Input and contains a null character, the
+results are abnormal.  Lines may be truncated, and a single line may be
+considered multiple lines.  Normal text does not contain null characters, so
+this isn't a big problem.
+
+
+.UN tips
+.SH TIPS
+.PP
+If you get garbled output, check the input text encoding and font file
+encoding.  When using \fB-wchar\fP, also check the current locale.
+.PP
+To convert the encoding of a text file, use \fBiconv\fP or \fBluit\fP.
+.PP
+To check the encoding of a BDF file, examine the CHARSET_REGISTRY
+line and the next line, which should be CHARSET_ENCODING:
+
+.nf
+\f(CW
+    $ grep -A1 CHARSET_REGISTRY font-a.bdf
+    CHARSET_REGISTRY "ISO8859"
+    CHARSET_ENCODING "1"
+    
+    $ grep -A1 CHARSET_REGISTRY font-b.bdf
+    CHARSET_REGISTRY "ISO10646"
+    CHARSET_ENCODING "1"
+\fP
+
+.fi
+.PP
+The latter is Unicode.  BDF files coded in ISO 16046-1 usually work for
+Western European languages, because ISO 16046-1 expands ISO 8859-1 (also
+called "Latin-1") while maintaining the first 256 code points.  ISO
+8859-1 itself is a superset of ASCII.  Run the above command and verify the
+necessary  glyphs are present.
+.PP
+\fBIMPORTANT:\fP For input text, a different rule applies.  If
+you feed ISO 8859-1 text to \fBpbmtext -wchar\fP set up for UTF-8, the output
+will be garbled.  Unicode provides several encoding schemes and different ones
+are in effect for input text and font.  \fIThe difference between Unicode
+codepoint and the various encodings is a formidable stumbling block; beware of
+web pages that get the concept wrong.\fP
+.PP
+75% of the BDF files in the font collection available from
+.UR http://netpbm.sourceforge.net/bdffont.tgz
+the Netpbm website
+.UE
+\& are
+in ISO 10646-1.  Many have the Euro sign, Greek letters, etc., but they are
+placed at code points available to \fBpbmtext\fP only with \fB-wchar\fP.
+.PP
+Before \fBpbmtext\fP had the \fB-wchar\fP option, one often had to
+produce a BDF file in an 8-bit encoding from a master BDF file encoded in ISO
+10646-1.
+.PP
+There are several programs that perform BDF encoding conversion.  If you
+have the X Window System installed, first look for \fBucs2any\fP.  If you
+don't, you can download \fBucs2any.pl\fP from
+.BR "Unicode fonts and tools
+for X11" (1)\c
+\&.  This website has much useful information on fonts.
+.PP
+Another converter is \fBtrbdf\fP, included in the "trscripts"
+package, available in some GNU/Linux distributions.
+.PP
+BDF files encoded in ISO 8859-2, ISO 8859-7, koi8-r, etc. are available
+from
+.BR "ISO 8859 Alphabet
+Soup" (1)\c
+\& and its sister page
+.BR "The Cyrillic Charset
+Soup" (1)\c
+\&.  Though the information is dated, these pages give a good overview
+of 8-bit character sets.
+.PP
+To convert OTF or TTF font files to BDF, use 
+.UR http://www.math.nmsu.edu/~mleisher/Software/otf2bdf
+ \fBotf2bdf\fP by Mike Leisher
+.UE
+\&.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtextps" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmcrop" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppmchange" (1)\c
+\&,
+.BR "pnmrotate" (1)\c
+\&,
+.BR "ppmlabel" (1)\c
+\&,
+.BR "ppmdraw" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+\fB
+.UR http://www.pango.org
+Pango
+.UE
+\&\fP,
+\fB
+.UR http://cairographics.org
+Cairo
+.UE
+\&\fP
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Jef Poskanzer and George Phillips
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtext.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtextps.1 b/upstream/mageia-cauldron/man1/pbmtextps.1
new file mode 100644
index 00000000..109eb6e9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtextps.1
@@ -0,0 +1,435 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtextps User Manual" 0 "17 February 2023" "netpbm documentation"
+
+.SH NAME
+pbmtextps - render text into a PBM image using a postscript interpreter
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtextps\fP
+[\fB-font\fP \fIfontname\fP]
+[\fB-fontsize\fP \fIfloat\fP]
+[\fB-resolution\fP \fIn\fP]
+[\fB-leftmargin=\fP\fIn\fP]
+[\fB-rightmargin=\fP\fIn\fP]
+[\fB-topmargin=\fP\fIn\fP]
+[\fB-bottommargin=\fP\fIn\fP]
+[\fB-ascent=\fP\fIn\fP]
+[\fB-descent=\fP\fIn\fP]
+[\fB-pad\fP]
+[\fB-crop\fP]
+[\fB-stroke\fP \fIn\fP]
+[\fB-asciihex\fP]
+[\fB-ascii85\fP]
+[\fB-verbose\fP]
+[\fB-dump-ps\fP]
+\fItext\fP [\fItext\fP ...]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtextps\fP takes a single line of text from the command line and
+renders it into a PBM image.  The image is of a single line of text; newline
+characters in the input have no effect.
+.PP
+See \fBpbmtext\fP for a more sophisticated generator of text, but using
+less common font formats.  \fBpbmtext\fP can generate multiple lines of text.
+.PP
+The \fB-plain\fP 
+.UR index.html#commonoptions
+common option
+.UE
+\& has
+no effect before Netpbm 10.42 (March 2008).  The output is always raw PBM.
+
+.UN margins
+.SS Margins
+.PP
+By default, the image is cropped at the top and the right.  It is not
+cropped at the left or bottom so that the text begins at the same position
+relative to the origin.  The size of the default left and bottom margins is
+explained below.
+.PP
+You can set whatever margin you want with options
+\fB-leftmargin\fP, \fB-rightmargin\fP, \fB-topmargin\fP and
+\fB-bottommargin\fP.  The specified amount of white space gets added to the
+far edge of type, e.g. if you specify 10 points for \fB-topmargin\fP, you
+will get 10 points of white space above the highest character on the line.
+Specify 0 to crop a side.
+.PP
+\fB-ascent\fP adds white space to the top to reach a specified distance
+above the text baseline, and \fB-descent\fP adds white space to to the bottom
+to reach a specified distance below the text baseline.
+.PP
+\fB-ascent\fP and \fB-descent\fP are more useful than \fB-topmargin\fP
+and \fB-bottomargin\fP when you render two pieces of text (in separate
+invocations of \fBpbmtextps\fP) that you will concatenate horizontally.
+With \fB-ascent\fP and \fB-descent\fP, as long as you specify a value
+greater than the height or detph of every character in the font, the two
+images will be the same height with the text baseline in the same place.
+With \fB-topmargin\fP and \fB-bottommargin\fP, that may not be the case.
+.PP
+Example:
+
+.nf
+\f(CW
+     $ pbmtextps -font=Times-Roman -descent=20 \e
+          'The soup is called' > a1.pbm
+     $ pbmtextps -font=Itallic -descent=20 'Goulash.' > a2.pbm
+     $ pnmcat -leftright -jbottom a1.pbm a2.pbm > out.pbm
+\fP
+
+.fi
+.PP
+If you're using \fB-descent\fP to line up the segments of text you are
+  concatenating horizontally with \fBpnmcat\fP, use the \fB-jbottom\fP
+  (justify to bottom) option on \fBpnmcat\fP as in the example above.  If you
+  use \fB-ascent\fP, use \fB-jtop\fP instead.
+.PP
+Similarly, if you render two lines of text (in separate invocations of
+  \fBpbmtextps\fP) that you will concatenate vertically, \fB-ascent\fP and
+  \fB-descent\fP with sufficiently large values will ensure your baselines
+  are uniformly spaced.
+.PP
+If you have \fB-ascent\fP, there is probably no point in specifying
+\fB-topmargin\fP too, but if you do, the effect is cumulative.  The same is
+true of \fB-descent\fP and \fB-bottommargin\fP.
+.PP
+\fB-pad\fP pads the image on the top and bottom to the where the highest
+and lowest characters in the font would reach, even if you don't have those
+characters in your text.  This is useful if you will generate multiple images
+of text (with multiple invocations of \fBpbmtextps\fP) and concatenate them
+vertically to create a multiline text image.  \fB-pad\fP makes sure the lines
+in this image are equally spaced.
+.PP
+Example:
+
+.nf
+\f(CW
+    $ pbmtextps 'cat'   | pamfile
+    $ pbmtextps 'Catty' | pamfile
+\fP
+
+.fi
+.PP
+The commands above, with no \fB-pad\fP, show that the 'Catty'
+image is higher because capital C reaches high and 'y' reaches low.
+
+.nf
+\f(CW
+    $ pbmtextps -pad 'cat'   | pamfile
+    $ pbmtextps -pad 'Catty' | pamfile
+\fP
+
+.fi
+.PP
+The commands above, with \fB-pad\fP, show that both images are the same
+height.
+.PP
+If you specify \fB-pad\fP with \fB-ascent\fP or \fB-descent\fP, the
+larger value is effective.
+.PP
+\fB-crop\fP makes the program crop all sides to the far edge of the type.
+It is the same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0
+-bottommargin=0\fP.
+.PP
+You cannot specify any other margin-affecting options with \fB-crop\fP.
+.PP
+The default top margin, when you specify neither \fB-ascent\fP,
+\fB-topmargin\fP, nor \fB-pad\fP, is as if you specified
+\fBtopmargin=0\fP.
+.PP
+The default bottom margin, when you specify neither \fB-descent\fP,
+\fB-bottommargin\fP, nor \fB-pad\fP, is as if you specified
+\fB-descent=\fP\fI1.5*fontsize\fP.
+.PP
+The default left margin, when you do not specify \fB-leftmargin\fP, is
+as if you specified \fB-leftmargin=\fP\fI0.5*fontsize\fP.
+.PP
+The default right margin, when you do not specify \fB-rightmargin\fP,
+is as if you specified \fB-rightmargin=0\fP.
+
+
+<h3 id="input_text">Input Text</h2>
+.PP
+The simplest way to specify the text to render is just to specify it,
+  in ASCII, as the sole argument of the command.  For example,
+
+.nf
+    \f(CW
+  $ pbmtextps 'hello world'
+    \fP
+
+.fi
+.PP
+But you can also spread it across multiple arguments.  \fBpbmtextps\fP
+  concatenates them right to left with a single space in between:
+  
+.nf
+    \f(CW
+  $ pbmtextps hello world
+    \fP
+
+.fi
+.PP
+With an \fB-asciihex\fP option, you can specify the text in
+Postscript&apos;s ASCII-HEX code:
+  
+.nf
+    \f(CW
+  $ pbmtextps -asciihex 68656c6c6f20776f726c64
+    \fP
+
+.fi
+.PP
+You can optionally include the ASCII-HEX text delimiters that would appear
+around the text in a Postscript program:
+
+.nf
+    \f(CW
+  $ pbmtextps -asciihex '<68656c6c6f20776f726c64>'
+    \fP
+
+.fi
+.PP
+Note that the <> delimiters have special meaning to command shells, so if
+you are invoking \fBpbmtextps\fP via a command shell, be sure to quote them,
+as is done in this example.
+  
+.PP
+With \fB-asciihex\fP, you can include white space anywhere in the coded
+text; it has no effect.  And you can spread the argument across multiple
+arguments as for plain ASCII input:
+
+.nf
+    \f(CW
+  $ pbmtextps -asciihex '<' 68656c6c6f 20 776f726c64 '>'
+    \fP
+
+.fi
+.PP
+But note that while Postscript allows an ASCII NUL character as white
+  space, there is no way to pass an argument including a NUL character to
+  \fBpbmtextps\fP.
+  
+.PP
+With an \fB-ascii85\fP option, you can specify the text in
+Postscript&apos;s ASCII-85 code.  This is analogous to \fB-asciihex\fP.  The
+Postscript delimiters for an ASCII-85 text string are <~ ~>.
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtextps\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-font=\fP\fIfontname\fP
+.sp
+This specifies the font to use.  \fIfontname\fP is the name of any valid
+Postscript font which is installed on the system.
+.sp
+The default is \fBTimesRoman\fP.
+.sp
+Here is a way to get a list of the names of all the available fonts:
+
+.nf
+\f(CW
+        $ gs -c &apos;(*) {==} 256 string /Font resourceforall&apos;
+\fP
+
+.fi
+.sp
+\fBWarning:\fP if \fIfontname\fP does not name a valid font,
+\fBpbmtextps\fP just uses the default font.  It does not tell you it is doing
+this.
+
+.TP
+\fB-fontsize=\fP\fIfloat\fP
+This is the size of the font in points.  See the \fB-resolution\fP option for
+information on how to interpret this size.
+.sp
+The default is 24 points.
+.sp
+Before Netpbm 10.75 (June 2016), this has to be a whole number.
+
+.TP
+\fB-resolution=\fP\fIn\fP
+This is the resolution in dots per inch of distance measurements pertaining to
+generation of the image.  PBM images don't have any inherent resolution, so a
+distance such as "1 inch" doesn't mean anything unless you separately specify
+what resolution you're talking about.  That's what this option does.
+.sp
+In particular, the meaning of the font size is determined by this
+resolution.  If the font size is 24 points and the resolution is 150 dpi, then
+the font size is 50 pixels.
+.sp
+The default is 150 dpi.
+
+.TP
+\fB-leftmargin=\fP\fIn\fP
+.TP
+\fB-rightmargin=\fP\fIn\fP
+.TP
+\fB-topmargin=\fP\fIn\fP
+.TP
+\fB-bottommargin=\fP\fIn\fP
+These options control the margins added to the image, measured from the far
+edge of the type.  See 
+.UR #margins
+Margins
+.UE
+\& for details.
+.sp
+All sizes are in points, as a floating point number.
+.sp
+These options were new in Netpbm 10.75 (June 2016).
+
+.TP
+\fB-ascent=\fP\fIn\fP
+.TP
+\fB-descent=\fP\fIn\fP
+These options control the margins added to the image, measured from
+the text baseline.  See 
+.UR #margins
+Margins
+.UE
+\& for details.
+.sp
+Sizes are in points, as a floating point number.
+.sp
+These options were new in Netpbm 10.75 (June 2016).
+
+.TP
+\fB-pad\fP
+This pads the image on the top and bottom to the where the highest and lowest
+characters in the font would reach, even if you don't have those characters in
+your text.  See 
+.UR #margins
+Margins
+.UE
+\& for details.
+.sp
+This option was new in Netpbm 10.75 (June 2016).
+
+.TP
+\fB-crop\fP
+This makes the program crop all sides to the far edge of the type.  It is the
+same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0 -bottommargin=0\fP.
+See 
+.UR #margins
+Margins
+.UE
+\& for details.
+.sp
+This option was new in Netpbm 10.75 (June 2016).
+
+.TP
+\fB-asciihex\fP
+This means the text in the arguments is in Postscript ASCII-HEX code.
+See 
+.UR #input_text
+Input Text
+.UE
+\&.
+.sp
+You cannot specify this together with \fB-ascii85\fP.
+.sp
+This option was new in Netpbm 11.02 (March 2023)
+
+.TP
+\fB-ascii85\fP
+This means the text in the arguments is in Postscript ASCII-85 code.
+See 
+.UR #input_text
+Input Text
+.UE
+\&.
+.sp
+You cannot specify this together with \fB-asciihex\fP.
+.sp
+This option was new in Netpbm 11.02 (March 2023)
+  
+.TP
+\fB-stroke=\fP\fIn\fP
+This is the width of line, in points, to use for stroke font.  There is no
+default stroke width because the characters are solid by default.
+
+.TP
+\fB-verbose\fP
+This option makes \fBpbmtextps\fP display extra information on Standard Error
+about its processing.
+
+.TP
+\fB-dump-ps\fP
+This option makes \fBpbmtextps\fP write to Standard Output the Postscript
+program it would use to create the image, rather than the image itself.  You
+can use this as input to a Postscript interpreter (such as Ghostscript or a
+printer) or to understand the program better.
+.sp
+This option was new in Netpbm 10.75 (June 2016).
+
+
+
+.UN usage
+.SH USAGE
+
+You can generate antialiased text by using a larger resolution than the
+default and scaling the image down using \fBpamscale\fP.
+.PP
+See the manual for the similar \fBpbmtext\fP for more advice on
+usage.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtextps\fP was added to Netpbm in Release 10.0 (June 2002).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtext" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmcrop" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppmchange" (1)\c
+\&,
+.BR "pnmrotate" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "ppmlabel" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2002 by James McCann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtextps.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmto10x.1 b/upstream/mageia-cauldron/man1/pbmto10x.1
new file mode 100644
index 00000000..3d2c5227
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmto10x.1
@@ -0,0 +1,67 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmto10x User Manual" 0 "01 January 1990" "netpbm documentation"
+
+.SH NAME
+pbmto10x - convert a PBM image into Gemini 10X printer graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmto10x\fP
+[\fB-h\fP]
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmto10x\fP reads a PBM image as input and produces a file of
+Gemini 10X printer graphics as output.  The 10x's printer codes are
+alleged to be similar to the Epson codes.
+.PP
+Note that there is no 10xtopbm tool - this transformation is one
+way.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmto10x\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-h\fP
+.sp
+The resolution is normally 60H by 72V.  If you specify the
+\fB-h\fP option, resolution is 120H by 144V.  You may find it useful
+to rotate landscape images before printing.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Ken Yap
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmto10x.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmto4425.1 b/upstream/mageia-cauldron/man1/pbmto4425.1
new file mode 100644
index 00000000..354ce935
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmto4425.1
@@ -0,0 +1,75 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmto4425 User Manual" 0 "1994" "netpbm documentation"
+
+.SH NAME
+
+pbmto4425 - Display PBM images on an AT&T 4425 terminal
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmto4425\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmto4425\fP displays PBM format images on an AT&T 4425 ASCII
+terminal using that terminal's mosaic graphics character set.  The
+program should also work with other VT100-like terminals with mosaic
+graphics character sets such as the C. Itoh CIT-101, but it has not
+yet been tested on terminals other than the 4425.
+.PP
+\fBPbmto4425\fP puts the terminal into 132 column mode to achieve
+the maximum resolution of the terminal.  In this mode the terminal has
+a resolution of 264 columns by 69 rows.  The pixels have an aspect
+ratio of 1:2.6, therefore an image should be processed before being
+displayed in a manner such as this:
+
+.nf
+\fB% pamscale -xscale 2.6 \fP\fIpamfile\fP \fB\e
+    | pamscale -xysize 264 69 \e
+    | ppmtopgm \e
+    | pamditherbw \e
+    | pbmto4425\fP
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmto4425\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoascii" (1)\c
+\&,
+.BR "ppmtoterm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Robert Perlberg
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmto4425.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoascii.1 b/upstream/mageia-cauldron/man1/pbmtoascii.1
new file mode 100644
index 00000000..d6cb36b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoascii.1
@@ -0,0 +1,85 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoascii User Manual" 0 "02 April 2010" "netpbm documentation"
+
+.SH NAME
+pbmtoascii - convert a PBM image to ASCII graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoascii\fP
+
+[\fB-1x2\fP|\fB-2x4\fP]
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoascii\fP reads a PBM image as input and produces a somewhat
+crude ASCII graphic image as output.
+.PP
+To convert back, use
+.BR "asciitopgm" (1)\c
+\&.
+.PP
+\fBppmtoterm\fP does a similar thing for color images to be displayed
+on color text terminals.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoascii\fP recognizes the following
+command line options:
+.PP
+The \fB-1x2\fP and \fB-2x4\fP options give you two alternate ways for the
+pixels to get mapped to characters.  With \fB1x2\fP, the default, each
+character represents a group of 1 pixel across by 2 pixels down.  With
+\fB-2x4\fP, each character represents 2 pixels across by 4 pixels down.  With
+the 1x2 mode you can see the individual pixels, so it's useful for previewing
+small images on a non-graphics terminal.  The 2x4 mode lets you display larger
+images on a small display, but it obscures pixel-level details.  2x4 mode is
+also good for displaying PGM images:
+
+.nf
+pamscale -width 158 | pnmnorm | pamditherbw -threshold | pbmtoascii -2x4
+
+.fi
+
+should give good results.
+
+.UN seealso
+.SH SEE ALSO
+.BR "asciitopgm" (1)\c
+\&
+.BR "ppmtoascii" (1)\c
+\&
+.BR "ppmtoterm" (1)\c
+\&
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988, 1992 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoascii.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoatk.1 b/upstream/mageia-cauldron/man1/pbmtoatk.1
new file mode 100644
index 00000000..3a26d7b3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoatk.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoatk User Manual" 0 "26 September 1991" "netpbm documentation"
+
+.SH NAME
+pbmtoatk - convert a PBM image to a Andrew Toolkit raster object
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoatk\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoatk\fP reads a PBM image as input and produces a Andrew
+Toolkit raster object as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtoatk\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "atktopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Bill Janssen.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoatk.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtobbnbg.1 b/upstream/mageia-cauldron/man1/pbmtobbnbg.1
new file mode 100644
index 00000000..c76eebad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtobbnbg.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtobbnbg User Manual" 0 "16 May 1989" "netpbm documentation"
+
+.SH NAME
+pbmtobbnbg - convert a PBM image into BitGraph graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtobbng\fP
+[\fIrasterop\fP]
+[\fIx\fP \fIy\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtobbnbg\fP reads a PBM image as input and produces BBN BitGraph
+terminal Display Pixel Data (DPD) sequence as output.
+.PP
+  The rasterop can be specified on the command line.  If you omit this, the
+  program uses 3 (replace).  You can also specify a position in (x,y)
+  coordinates.  If you give both, the rasterop comes first.  The PBM always
+  comes from Standard Input.
+.PP
+Note that there is no \fBbbnbgtopbm\fP tool.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtobbnbg\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright 1989 by Mike Parker.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtobbnbg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtocis.1 b/upstream/mageia-cauldron/man1/pbmtocis.1
new file mode 100644
index 00000000..5e7e8b6d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtocis.1
@@ -0,0 +1,87 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtocis User Manual" 0 "13 August 2020" "netpbm documentation"
+
+.SH NAME
+pbmtocis - convert a PBM image to a CompuServe RLE image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtocis\fP
+[\fB-i\fP]
+[\fB-w\fP]
+[\fIcisfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtocis\fP reads a PBM image as input and produces a CompuServe
+RLE image as output.
+.PP
+A CompuServe RLE image can be either 128 x 96 pixels or 256 x 192 pixels.
+Anything in excess on the right or bottom is cropped.  If width or height
+is insufficient, padding is added on the right or bottom.  For better
+control of the size adjustment use \fBpamcut\fP or \fBpnmpad\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtocis\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-i\fP
+Inverse: Reverse the mapping of foreground/background to black/white.
+
+.TP
+\fB-w\fP
+If the input image is smaller than the fixed size of the output image,
+pad with white pixels rather than black.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "cistopbm" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmpad" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.UR https://web.archive.org/web/20140721001738/staticweb.rasip.fer.hr/research/compress/algorithms_run-length_coding.htm
+CompuServe RLE file format
+.UE
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtocis\fP was new in Netpbm 10.48 (September 2009).
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2009 John Elliot <jce@seasip.demon.co.uk>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtocis.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtocmuwm.1 b/upstream/mageia-cauldron/man1/pbmtocmuwm.1
new file mode 100644
index 00000000..c7767cf2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtocmuwm.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtocmuwm User Manual" 0 "15 April 1989" "netpbm documentation"
+
+.SH NAME
+pbmtocmuwm - convert a PBM image into a CMU window manager bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtocmuwm\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtocmuwm\fP reads a portable bitmap as input and produces a CMU
+window manager bitmap as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtocmuwm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "cmuwmtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtocmuwm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtodjvurle.1 b/upstream/mageia-cauldron/man1/pbmtodjvurle.1
new file mode 100644
index 00000000..6c32d2f8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtodjvurle.1
@@ -0,0 +1,61 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtodjvurle User Manual" 0 "10 April 2004" "netpbm documentation"
+
+.SH NAME
+
+pbmtodjvurle - convert a PBM image to DjVu Bitonal RLE format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtodjvurle\fP
+
+[\fIpbmfile\fP [\fIrlefile\fP]]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtodjvurle\fP reads a PBM image as input and produces
+DjVu Bitonal RLE format as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtodjvurle\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtodjvurle" (1)\c
+\&
+.BR "pbm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtodjvurle\fP was new in Netpbm 10.22 (April 2004).
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2004 Scott Pakin <scott+pbm@pakin.org>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtodjvurle.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoepsi.1 b/upstream/mageia-cauldron/man1/pbmtoepsi.1
new file mode 100644
index 00000000..6384570d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoepsi.1
@@ -0,0 +1,109 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoepsi User Manual" 0 "June 2002" "netpbm documentation"
+
+.SH NAME
+pbmtoepsi - convert a PBM image to an encapsulated PostScript
+style preview bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoepsi\fP
+[\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]]
+[\fB-bbonly\fP]
+[\fIpbmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Reads a PBM image as input.  Produces an encapsulated Postscript
+style bitmap as output.  The output is not a stand alone postscript
+file, it is only a preview bitmap, which can be included in an
+encapsulated PostScript file.
+.PP
+\fBpbmtoepsi\fP assumes the PBM input describes a whole output
+page, with one pixel on the page corresponding to one PBM pixel.  It
+detects white borders in the image and generates Postscript output
+that contains a Bounding Box statement to describe the location of the
+principal image (the image excluding the white borders) on the page
+and thus does not include the borders in the raster part of the
+Postscript output.
+.PP
+There is no \fBepsitopbm\fP tool - this transformation is one way.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoepsi\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]
+.sp
+This option specifies the resolution in dots per inch of the
+     ultimate output device.  You must specify this because the
+     Bounding Box statement defines the bounding box in absolute
+     distances, not in pixels.  \fBpbmtoepsi\fP assumes in
+     calculating the bounding box that each PBM pixel will become one
+     dot on the output device, and applies your \fBdpi\fP
+     specification to calculate the size and location on the page of
+     the bounding box.
+.sp
+If you specify \fIN\fP\fBx\fPN, the first number is the
+     horizontal resolution and the second number is the vertical
+     resolution.  If you specify just a single number \fIN\fP, that is the
+     resolution in both directions.
+.sp
+The default is 72 dots per inch in both directions.
+.sp
+This option was new In Netpbm 10.3 (June 2002).  Before that, 
+     \fBpbmtoepsi\fP always assumed 72 dots per inch in both directions.
+     
+.TP
+\fB-bbonly\fP
+Only create a boundary box, don't fill it with the image.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&,
+.BR "pnmtops" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "psidtopgm" (1)\c
+\&,
+.BR "pbmtolps" (1)\c
+\&,
+
+Postscript language documentation
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 Jef Poskanzer, modified by Doug Crabill 1992
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoepsi.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoepson.1 b/upstream/mageia-cauldron/man1/pbmtoepson.1
new file mode 100644
index 00000000..d34dbbd4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoepson.1
@@ -0,0 +1,115 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoepson User Manual" 0 "08 August 2003" "netpbm documentation"
+
+.SH NAME
+pbmtoepson - convert a PBM image into Epson printer graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoepson\fP
+
+[\fB-dpi=\fP\fIn\fP]
+[\fB-protocol=\fP{\fBescp9\fP|\fBescp\fP}]
+[\fB-adjacent\fP]
+[\fB-noadjacent\fP]
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpbmtoepson\fP reads a PBM image as input and produces a stream of
+Epson printer graphics as output.
+.PP
+The input is from the file identified by the \fIpbmfile\fP argument
+or, if you don't specify \fIpbmfile\fP, from Standard Input.  Output is
+to Standard Output.
+.PP
+The output is for traditional (ca 1991) Epson 9-wire dot matrix
+(sometimes called ESC/P 9-wire) printers or newer ESC/P printers.  For
+a more modern Epson ESC/P2 type printer, try \fBpbmtoescp2\fP.
+.PP
+Before Netpbm 10.23 (July 2004), \fBpbmtoepson\fP could not produce
+ESC/P streams -- only ESC/P 9-wire.
+.PP
+The Epson printer protocols are described in Epson's protocol
+specification.
+.PP
+Note that there is no epsontopbm tool - this transformation is one way.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoepson\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-protocol=\fP{\fBescp9\fP|\fBescp\fP}
+This determines which Epson printer protocol the output uses.
+\fBescp9\fP is the older ESC/P 9-pin protocol.  \fBescp\fP is the
+newer ESC/P protocol.  For the even newer \fBESC/P2\fP protocol, you
+have to use \fBpbmtoescp2\fP instead.
+.sp
+This option was new in Netpbm 10.23 (July 2004).     
+
+
+.TP
+\fB-dpi=\fP\fIn\fP
+This specifies the horizontal print density in dots per inch.  The
+protocol allows only certain values: 60, 72, 80, 90, 120, 144, and 240.
+Actually, the ESC/P protocol allows a few others, but \fBpbmtoepson\fP
+doesn't know how to generate the command streams that use them.
+.sp
+If you don't specify this, \fBpbmtoepson\fP chooses a horizontal
+print density for you consistent with your other options.
+.sp
+This option was new in Netpbm 10.23 (July 2004).     
+
+.TP
+\fB-adjacent\fP
+.TP
+\fB-noadjacent\fP
+These options determine whether the output uses "adjacent dot
+printing" or not, whatever that is.
+.sp
+If you don't specify this, \fBpbmtoepson\fP selects adjacent dot
+printing unless that is incompatible with your other options.
+.sp
+This option was new in Netpbm 10.23 (July 2004).     
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoescp2" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by John Tiller (\fItiller@galois.msfc.nasa.gov\fP)
+and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoepson.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoescp2.1 b/upstream/mageia-cauldron/man1/pbmtoescp2.1
new file mode 100644
index 00000000..71ded5b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoescp2.1
@@ -0,0 +1,179 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoescp2 User Manual" 0 "14 July 2015" "netpbm documentation"
+
+.SH NAME
+
+pbmtoescp2 - convert a PBM image to a ESC/P2 printer file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoescp2\fP
+
+[\fB-compress=\fP\fIcompressionmode\fP]
+[\fB-resolution=\fP{\fB180\fP|\fB360\fP|\fB720\fP}]
+[\fB-stripeheight=\fP\fIn\fP]
+[\fB-formfeed\fP]
+[\fB-raw\fP]
+[\fIpbmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoescp2\fP reads a PBM image as input.  It produces an ESC/P2
+raster graphic printer control stream as output.
+.PP
+ This program creates an output that is printable on Epson printers that
+understand the ESC/P2 printer control language (e.g. the Stylus models).  For
+older Epson 9-pin dot matrix printers, which use the ESC/P protocol, see
+\fBpbmtoepson\fP.
+.PP
+The printed output has one pixel for each pixel of the input image, except
+that it is padded up to the stripe size (see \fB-stripeheight\fP option)
+vertically and to a multiple of 8 columns horizontally.  Before Netpbm 10.72
+(September 2015), the output is instead truncated to those boundaries.
+.PP
+Input is read from file \fIpbmfile\fP if specified, otherwise from
+stdin. Output is written to stdout.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoescp2\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-compress=\fP\fIcompressionmode\fP
+This determines the compression mode that \fBpbmtoescp2\fP uses
+in its output.  Valid values for \fIcompressionmode\fP are \fB0\fP
+and \fB1\fP.  \fB-compress=0\fP results in a printer control stream
+with uncompressed raster graphic data.  \fB-compress=1\fP results in
+a printer control stream with RLE compressed raster graphic data
+(RLE means Run Length Encoding).  The default is \fB-compress=1\fP.
+
+
+.TP
+\fB-resolution=\fP\fIdpi\fP
+This determines the horizontal and the vertical print resolution
+set in the printer control stream.  Another way of looking at it is a
+declaration of what the resolution of the input image is (PBM images
+don't have inherent resolution).  Valid values for \fIdpi\fP are
+\fB180\fP, \fB360\fP, and \fB720\fP.  See 
+.UR #hints
+hints
+.UE
+\& for
+more information on this.
+.sp
+The default is \fB-resolution=360\fP.
+.sp
+Before Netpbm 10.72 (September 2015), \fB720\fP is not valid.
+
+
+
+.TP
+\fB-stripeheight=\fP\fIn\fP
+This option controls the height in lines of the stripes in the output.
+.sp
+The valid stripe heights in the printer language are 1, 8, and 24, but
+it is capable of expressing any height up to 255 and \fBpbmtoescp2\fP
+accepts any value in the range 1-255.  It issues a warning, though, if you
+choose something other than 1, 8, or 24.
+.sp
+The default is 24.
+.sp
+This option was new in Netpbm 10.72 (September 2015).  Before that, the
+stripe size is always 24.
+
+.TP
+\fB-formfeed\fP
+This option causes \fBpbmtoescp2\fP to place a formfeed command at the
+end of the output.
+.sp
+This option was new in Netpbm 10.72 (September 2015).
+
+
+.TP
+\fB-raw\fP
+This option causes \fBpbmtoescp2\fP to generate only the data blocks.
+It does not generate printer commands to set up the output (for example,
+setting the line spacing).
+.sp
+You can use this to insert graphics into a larger printer command stream.
+.sp
+This option was new in Netpbm 10.72 (September 2015).
+
+
+
+.UN hints
+.SH HINTS
+.PP
+RLE compresses very well bitmaps of line drawings, preferably horizontal
+oriented contents like texts, sheets of music, etc.  However, bitmaps derived
+from photographs are not ideal for RLE.  In extreme cases, when no byte
+repetitions occur in the input, the result will be even slightly bigger than
+the input.  To avoid this, use compression mode 0 to switch off RLE.
+.PP
+Each pixel in the input PBM image becomes one dot in the printed output.
+Therefore, you must make sure the width and height of the input are
+appropriate for the print resolution you choose and the print area you want.
+E.g. if you print at 180 dpi and want the image to print as 8 inches by 10,
+you must supply a PBM that is 1440 pixels wide by 1800 pixels high.  You can
+adjust the size of the input
+with \fBpamscale\fP, \fBpamstretch\fP, \fBpbmreduce\fP, or
+\fBpamenlarge\fP.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "escp2topbm" (1)\c
+\&,
+.BR "pbmtoepson" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamstretch" (1)\c
+\&,
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2003 by Ulrich Walcher (\fIu.walcher@gmx.de\fP).
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtoescp2\fP was added to Netpbm in Release 10.18 (August 2003);
+it was created around the same time.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoescp2.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtog3.1 b/upstream/mageia-cauldron/man1/pbmtog3.1
new file mode 100644
index 00000000..dbeda206
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtog3.1
@@ -0,0 +1,112 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtog3 User Manual" 0 "20 April 2017" "netpbm documentation"
+
+.SH NAME
+pbmtog3 - convert a PBM image into a Group 3 MH fax file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtog3\fP
+[\fB-reversebits\fP]
+[\fB-nofixedwidth\fP]
+[\fB-align8\fP|\fB-align16\fP]
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtog3\fP reads a PBM image as input and produces a Group 3 MH fax
+file as output.
+.PP
+You can also generate a TIFF file that uses the same encoding
+inside, with \fBpamtotiff\fP.
+.PP
+There is no program in Netpbm that generates other fax formats,
+such as MR and MMR, but \fBpamtotiff\fP can generate TIFF files that
+use those encodings.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtog3\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-reversebits\fP
+This option causes the output to have the bits in every byte
+reversed so the least significant bit becomes the most significant bit.
+Some fax modems expect bits in reverse order, and this compensates for
+that. If you get a whole bunch of "bad code word" messages when you try
+to read the G3 file (e.g. with \fBg3topbm\fP), try using this option.
+Note that the output is not G3 when you use this option.
+
+.TP
+\fB-nofixedwidth\fP
+Most fax machines expect the image to be 1728 columns wide, so
+\fBpbmtog3\fP cuts the output to this width by default.  If you want to
+keep the width of the original image, use this option.
+.sp
+This option was new in Netpbm 10.6 (July 2002).  Before that,
+\fBpbmtog3\fP always kept the width of the original image.
+
+.TP
+\fB-align8\fP
+.TP
+\fB-align16\fP
+These options say to align output rows to 8-bit or 16-bit boundaries,
+respectively, by adding padding bits in front of EOL codes
+.sp
+Without these options, \fBpbmtog3\fP adds no padding and rows may begin
+and ends anywhere within a byte.
+.sp
+You cannot specify both.
+.sp
+These options were new in Netpbm 10.79 (June 2017).     
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "g3topbm" (1)\c
+\&,
+.BR "pamtotiff" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "fax formats" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Before Netpbm 10.79 (June 2017), there was a different program by the same
+name in Netpbm, which was written by Paul Haeberli
+<\fIpaul@manray.sgi.com\fP> in 1989
+and then modified extensively by others.
+.PP
+Akira Urushibata <afu@wta.att.ne.jp> wrote the current version, with
+an entirely different algorithm, in April 2017 and contributed his work to the
+public domain.
+.PP
+The current program is backward compatible with the pre-10.79 version.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtog3.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtogem.1 b/upstream/mageia-cauldron/man1/pbmtogem.1
new file mode 100644
index 00000000..5490c4ba
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtogem.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtogem User Manual" 0 "11 July 1992" "netpbm documentation"
+
+.SH NAME
+
+pbmtogem - convert a PBM image into a GEM .img file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtogem\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtogem\fP reads a PBM image as input and produces a
+compressed GEM .img file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtogem\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN limitations
+.SH LIMITATIONS
+
+\fBpbmtogem\fP cannot compress repeated lines.
+
+.UN seealso
+.SH SEE ALSO
+.BR "gemtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by David Beckemeyer (bdt!david) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtogem.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtogo.1 b/upstream/mageia-cauldron/man1/pbmtogo.1
new file mode 100644
index 00000000..d99f35b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtogo.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtogo User Manual" 0 "24 November 1989" "netpbm documentation"
+
+.SH NAME
+
+pbmtogo - convert a PBM image into compressed GraphOn graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtogo\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtogo\fP reads a PBM image as input and produces 2D
+compressed GraphOn graphics as output.
+.PP
+Be sure to set up your GraphOn with the following modes: 8 bits /
+no parity; obeys no XON/XOFF; NULs are accepted.  These are all on the
+Comm menu.  Also, remember to turn off tty post processing.  Note that
+there is no gotopbm tool.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtogo\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988, 1989 by Jef Poskanzer, Michael Haberler, and Bo Thide'.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtogo.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoibm23xx.1 b/upstream/mageia-cauldron/man1/pbmtoibm23xx.1
new file mode 100644
index 00000000..ed9d5d86
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoibm23xx.1
@@ -0,0 +1,100 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoibm23xx User Manual" 0 "28 January 2022" "netpbm documentation"
+
+.SH NAME
+pbmtoibm23xx - convert a PBM image to IBM 23XX printer stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoibm23xxx\fP
+\fB-xres=\fP\fIdpi\fP
+\fB-yres=\fP\fIdpi\fP
+[\fBslow\fP
+[\fIpbmfile\fP ...]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoibm23xx\fP reads one or more PBM files as input and
+writes an IBM 23XX printer command stream to generate all the images in
+all the files to Standard Output.
+.PP
+If you don't specify any file names, \fBpbmtoibm23xx\fP reads from
+Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoibm23xx\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-xres=\fP\fIdpi\fP
+This option specifies the horizontal resolution in dots per inch.
+Valid values are 60, 120, and 240.
+.sp
+This option is mandatory.
+
+.TP
+\fB-yres=\fP\fIdpi\fP
+This option specifies the vertical resolution in dots per inch.
+Valid values are 60, 120, and 240.
+.sp
+This option is mandatory.
+
+.TP
+\fB-slow\fP
+Use the slower printing mode where two modes with the same resolution
+are available.  This usually produces better quality prints.  This
+affects only modes with horizontal resolution 120, but might affect
+other modes in future versions of the program.
+     
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+There are probably better ways to control the IBM 23XX printers.  Let
+me know if you find any.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtoibm23xx\fP was new in Netpbm 10.25 (October 2004).
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&,
+Ghostscript (\fBgs\fP).
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2004 Jorrit Fahlke <jorrit@jorrit.de>.  Copying
+policy: GNU GPL version 2
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoibm23xx.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoicon.1 b/upstream/mageia-cauldron/man1/pbmtoicon.1
new file mode 100644
index 00000000..d58eb210
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoicon.1
@@ -0,0 +1,47 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoicon User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+
+pbmtoicon - replaced by pbmtosunicon
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoicon\fP
+[\fIiconfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoicon\fP was obsoleted by
+.BR "\fBpbmtosunicon\fP" (1)\c
+\&, introduced with Netpbm 10.53
+(December 2010).  \fBpbmtosunicon\fP is backward compatible with
+\fBpbmtoicon\fP, plus adds additional functions, including the
+ability to convert a Depth=8 Sun icon, producing a PGM image.
+.PP
+Starting in Release 10.53, \fBpbmtoicon\fP is just an alias for
+\fBpbmtosunicon\fP.
+.PP
+The point of the name change is that there are many kinds of icons in the
+world besides Sun icons, and in 2010, the Sun variety isn't even common.
+.PP
+In releases before 10.53, you can use the \fBpbmtosunicon\fP documentation
+for \fBpbmtoicon\fP, as long as you recognize that any change the
+\fBpbmtosunicon\fP manual says happened in or after Netpbm 10.53 doesn't
+apply to \fBpbmtoicon\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoicon.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtolj.1 b/upstream/mageia-cauldron/man1/pbmtolj.1
new file mode 100644
index 00000000..4243fd61
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtolj.1
@@ -0,0 +1,133 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtolj User Manual" 0 "23 April 2005" "netpbm documentation"
+
+.SH NAME
+pbmtolj - convert a PBM image to HP LaserJet format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtolj\fP
+[\fB-resolution\fP \fIN\fP]
+[\fB-float\fP]
+[\fB-noreset\fP]
+[\fB-packbits\fP]
+[\fB-delta\fP]
+[\fB-compress\fP]
+[\fIpbmfile\fP]
+[\fB-copies\fP \fIN\fP]
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtolj\fP reads a PBM image as input and produces HP LaserJet
+data as output.  You can send this data to a LaserJet or DeskJet printer
+(at least some of them).
+.PP
+Each pixel in the input PBM image becomes one dot in the printed
+output.  Therefore, you must make sure the width and height of the
+input are appropriate for the print resolution you choose and the
+print area you want.  E.g. if you print at 300 dpi and want the image
+to print as 8 inches by 10, you must supply a PBM that is 2400
+pixels wide by 3000 pixels high.  You can adjust the size of the
+input with \fBpamscale\fP, \fBpamstretch\fP, \fBpbmreduce\fP, or
+\fBpamenlarge\fP.
+.PP
+The input may be a multi-image PBM stream.  Each input image
+becomes a page of output.  But before Netpbm 10.28 (June 2005), images
+after the first one are ignored.
+.PP
+Note that there is no ljtopbm tool.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtolj\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-resolution\fP
+Specifies the resolution of the output device, in dpi.  Another
+way to look at this is as a declaration of the resolution of the input
+image (PBM images don't have inherent resolution).  Typical values are
+75, 100, 150, 300, and 600.  The default is 75.
+
+.TP
+\fB-float\fP
+Suppresses positioning commands.  By default, \fBpbmtolj\fP
+places the sequence \fIESC & l 0 E\fP in the output, which means
+to force the top margin to zero.  With \fB-float\fP, \fBpbmtolj\fP
+omits that command.
+
+.TP
+\fB-noreset\fP
+Prevents pbmtolj from writing the reset sequences to the beginning
+and end of the output file.
+
+.TP
+\fB-packbits\fP
+Enables use of TIFF packbits compression.
+
+.TP
+\fB-delta\fP
+Enables use of delta-between-rows compression.
+
+.TP
+\fB-compress\fP
+Enables use of both TIFF packbits, and delta-between-rows compression.
+
+.TP
+\fB-copies\fP
+Specifies the number of copies. The default is 1.  This option
+controls the "number of copies" printer control;
+\fBpbmtolj\fP generates only one copy of the image.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpnmtopclxl\fP" (1)\c
+\&,
+.BR "\fBppmtolj\fP" (1)\c
+\&,
+.BR "\fBpjtoppm\fP" (1)\c
+\&,
+.BR "\fBppmtopj\fP" (1)\c
+\&,
+.BR "\fBppmtopjxl\fP" (1)\c
+\&,
+.BR "\fBthinkjettopbm\fP" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer and Michael Haberler.
+\fB-float\fP and \fB-noreset\fP options added by Wim Lewis.
+\fB-delta\fP, \fB-packbits\fP, and \fB-compress\fP options added by
+Dave Platt.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtolj.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoln03.1 b/upstream/mageia-cauldron/man1/pbmtoln03.1
new file mode 100644
index 00000000..0504c4d8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoln03.1
@@ -0,0 +1,76 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoln03 User Manual" 0 "07 May 1993" "netpbm documentation"
+
+.SH NAME
+pbmtoln03 - convert PBM image to DEC LN03+ Sixel output
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoln03\fP
+[\fB-rltbf\fP]
+\fIpbmfile\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoln03\fP reads a PBM image as input and produces a DEC
+LN03+ Sixel output file.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoln03\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-l nn\fP
+Use "nn" as value for left margin (default 0).
+
+.TP
+\fB-r nn\fP
+Use "nn" as value for right margin (default 2400).
+
+.TP
+\fB-t nn\fP
+Use "nn" as value for top margin (default 0).
+
+.TP
+\fB-b nn\fP
+Use "nn" as value for bottom margin (default 3400).
+
+.TP
+\fB-f nn\fP
+Use "nn" as value for form length (default 3400).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Tim Cook, 26 Feb 1992
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoln03.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtolps.1 b/upstream/mageia-cauldron/man1/pbmtolps.1
new file mode 100644
index 00000000..528cdab5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtolps.1
@@ -0,0 +1,89 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtolps User Manual" 0 "06 July 2019" "netpbm documentation"
+
+.SH NAME
+pbmtolps - convert PBM image to PostScript
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtolps\fP
+[\fB-dpi\fP=\fIn\fP]
+[\fIpbmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtolps\fP reads a PBM image as input and outputs PostScript.  The
+output Postscript uses lines instead of the image operator to generate a
+(device dependent) picture which will be imaged much faster.
+.PP
+\fBpnmtops\fP is a more general program for converting from the Netpbm
+formats to Postscript, though it cannot produce the particular arcane
+subformat that \fBpbmtolps\fP does.
+.PP
+One pixel of the input image corresponds to one printed pixel
+('dot').  For this to work, you must use a \fB-dpi\fP option to
+tell \fBpmtolps\fP the resolution of the target printer, in dots per inch.
+  
+.PP
+The Postscript program \fBpbmtolps\fP generates draws paths of less than
+1000 segments so as not to overrun limits on the Apple Laserwriter and
+possibly other printers.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtolps\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-dpi=\fP\fIn\fP
+The resolution of the target printer, in dots per inch.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtops" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbmtoepsi" (1)\c
+\&,
+.BR "psidtopgm" (1)\c
+\&,
+\fBgs\fP,
+.BR "pbm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+George Phillips <\fIphillips@cs.ubc.ca\fP>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtolps.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtomacp.1 b/upstream/mageia-cauldron/man1/pbmtomacp.1
new file mode 100644
index 00000000..b11733a2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtomacp.1
@@ -0,0 +1,119 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtomacp User Manual" 0 "26 April 2015" "netpbm documentation"
+
+.SH NAME
+pbmtomacp - convert a PBM image to a MacPaint file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtomacp\fP
+[\fB-left\fP \fIleft\fP]
+
+[\fB-right\fP \fIright\fP]
+
+[\fB-top\fP \fItop\fP]
+
+[\fB-bottom\fP \fIbottom\fP]
+
+[\fIpbmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or equals signs between an option name and
+its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtomacp\fP reads a PBM image as input and produces a MacPaint
+file as output.
+.PP
+If you do not specify \fIpbmfile\fP, \fBpbmtomacp\fP uses Standard Input.
+.PP
+ The generated file is only the data fork of a picture.  You will
+need a program such as \fBmcvert\fP to generate a Macbinary or a
+BinHex file that contains the necessary information to identify the
+file as a PNTG file to MacOS.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtomacp\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-norle\fP
+This option tells \fBpbmtomacp\fP not to use any run length encoding
+compression in the MacPaint image it produces.  This output, while not
+normal, conforms to MacPaint specifications and can be read by any
+MacPaint decoder without any special settings.
+.sp
+The only value of this option is testing and experimentation.  The option
+causes every output image to contain exactly 53072 bytes, which is the
+theoretical maximum size for a MacPaint image.
+.sp
+Without \fB-norle\fP, MacPaint compresses the image as much as possible
+and the output size depends on the nature of the input.
+
+.TP
+\fB-left\fP
+\fB-right\fP
+\fB-top\fP
+\fB-bottom\fP
+These options let you define a rectangle within the image to convert.  The
+default is the whole file.  If the specified image is too large for a
+MacPaint-file, \fBpbmtomacp\fP cuts the image to fit, starting at the
+specified top left corner.
+.sp
+These options exist for backward compatibility with an unfortunate original
+design.  They do the same thing that you can do in a more Netpbm-like way and
+more flexibly by processing the input through \fBpamcut\fP.
+    
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "macptopbm" (1)\c
+\&,
+.BR "ppmtopict" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+\fBmcvert\fP documentation
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtomacp\fP was added to Netpbm in 1988, written by Douwe van der
+Schaaf (...!mcvax!uvapsy!vdschaaf).
+.PP
+In 2015, Akira Urushibata replaced the program with the current
+version, using different logic and none of the original code.  The new
+version used the "packed PBM" facilities of the Netpbm library and the
+shhopt method of command line parsing.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtomacp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtomatrixorbital.1 b/upstream/mageia-cauldron/man1/pbmtomatrixorbital.1
new file mode 100644
index 00000000..28c24436
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtomatrixorbital.1
@@ -0,0 +1,65 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtomatrixorbital User Manual" 0 "06 September 2003" "netpbm documentation"
+
+.SH NAME
+pbmtomatrixorbital - convert a PBM image to a Matrix Orbital LCD image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtomatrixorbital\fP
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpbmtomatrixorbital\fP reads a PBM image as input and produces as output
+an image that can be uploaded to a Matrix Orbital LCD display.
+.PP
+You can upload the image to the LCD via the serial port to which it
+is connected with the program \fBmo-upload.pl\fP, which you can get from
+the package \fBpbmtomatrixorbital\fP.  Yes, the package is the same name
+as this Netpbm program, and it contains its own \fBpbmtomatrixorbital\fP
+program which is slightly different from this one because it is not part
+of the Netpbm package.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtomatrixorbital\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN history
+.SH HISTORY
+.PP
+\fBpbmtomatrixorbital\fP was added to Netpbm in Release 10.18
+(September 2003).
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtox10bm" (1)\c
+\&,
+.BR "xbmtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtomatrixorbital.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtomda.1 b/upstream/mageia-cauldron/man1/pbmtomda.1
new file mode 100644
index 00000000..028c982b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtomda.1
@@ -0,0 +1,82 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtomda User Manual" 0 "03 June 1999" "netpbm documentation"
+
+.SH NAME
+
+pbmtomda - convert a PBM image to a Microdesign .mda
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtomda\fP
+
+[\fB-d\fP]
+[\fB-i\fP]
+[\fB--\fP]
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtomda\fP reads a PBM image as input and
+produces a MicroDesign 2 area file (.MDA) as output.
+.PP
+If you do not specify \fIpbmfile\fP, \fBpbmtomda\fP uses Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtomda\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-d\fP
+Halve the height of the output file, to compensate for the aspect 
+ratio used in MicroDesign files.
+.TP
+\fB-i\fP
+Invert the colors used.
+.TP
+\fB--\fP
+End of options (use this if the filename starts with "-")
+
+
+.UN limitations
+.SH LIMITATIONS
+
+There's no way to produce files in MicroDesign 3 format. MD3 itself and 
+.BR "mdatopbm" (1)\c
+\& can read files in either format.
+
+.UN seealso
+.SH SEE ALSO
+.BR "mdatopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1999 John Elliott <\fIjce@seasip.demon.co.uk\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtomda.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtomgr.1 b/upstream/mageia-cauldron/man1/pbmtomgr.1
new file mode 100644
index 00000000..63a5af95
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtomgr.1
@@ -0,0 +1,61 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtomgr User Manual" 0 "06 November 2006" "netpbm documentation"
+
+.SH NAME
+
+pbmtomgr - convert a PBM image into a MGR bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtomgr\fP
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtomgr\fP reads a PBM image as input and produces a MGR
+bitmap as output.
+.PP
+.BR "MGR" (1)\c
+\& is
+a window manager that is a smaller alternative to the X Windows
+System.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtomgr\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "mgrtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtomgr.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtomrf.1 b/upstream/mageia-cauldron/man1/pbmtomrf.1
new file mode 100644
index 00000000..5977132b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtomrf.1
@@ -0,0 +1,68 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtomrf User Manual" 0 "1991" "netpbm documentation"
+
+.SH NAME
+pbmtomrf - convert a PBM format image to MRF
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtomrf\fP
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtomrf\fP converts a PBM image to MRF format.
+.PP
+For more information about mrf, see
+.BR "the MRF
+specification" (1)\c
+\&.
+.PP
+\fBpbmtomrf\fP takes the PBM image from the file named by the
+\fIinput.pbm\fP argument, or Standard Input if you don't specify
+\fIinput.pbm\fP.  The output goes to Standard Output.
+.PP
+The compression of the edges of pictures with width and/or height
+not an exact multiple of 64 is not optimal in all cases.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtomrf\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN author
+.SH AUTHOR
+
+Russell Marks.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtomrf" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "mrf" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtomrf.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtonokia.1 b/upstream/mageia-cauldron/man1/pbmtonokia.1
new file mode 100644
index 00000000..03e8a1a7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtonokia.1
@@ -0,0 +1,164 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtonokia User Manual" 0 "14 September 2006" "netpbm documentation"
+
+.SH NAME
+pbmtonokia - convert a PBM image to Nokia Smart Messaging Formats
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtonokia\fP
+[
+\fB-fmt\fP
+  {
+    \fBHEX_NOL\fP,
+    \fBHEX_NGG\fP,
+    \fBHEX_NPM\fP,
+    \fBNOL\fP,
+    \fBNGG\fP,
+    \fBNPM\fP
+  }   
+]
+[\fB-net\fP \fInetworkcode\fP]
+[\fB-txt\fP \fItext\fP]
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtonokia\fP reads a PBM image as input and produces a Nokia
+Smart Messaging (hexcode, .ngg, .nol, .npm) file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtonokia\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-fmt\fP
+Specifies the output format (default is HEX_NOL).
+
+
+.TP
+\fBHEX_NOL\fP
+Nokia Operator Logo as (uploadable) hexcode.
+Use option -net to specify network code.
+
+.TP
+\fBHEX_NGG\fP
+Nokia Group Graphic as (uploadable) hexcode.
+
+.TP
+\fBHEX_NPM\fP
+Nokia Picture Message as (uploadable) hexcode.
+Use option \fB-txt\fP to specify an optional text message.
+
+.TP
+\fBNOL\fP
+Nokia Operator Logo as .nol format. This is editable by
+the Group-Graphic Editor from Kessler Wireless Design (
+.UR http://www.kessler-design.com
+www.kessler-design.com
+.UE
+\&)
+
+.TP
+\fBNGG\fP
+Nokia Group Graphic as .ngg format. This is editable by the
+Group-Graphic Editor from Kessler Wireless Design (
+.UR http://www.kessler-design.com
+www.kessler-design.com
+.UE
+\&)
+
+.TP
+\fBNPM\fP
+Nokia Picture Message as .npm format. This is editable by the
+Picture-Message Editor from Kessler Wireless Design (
+.UR http://www.kessler-design.com
+www.kessler-design.com
+.UE
+\&)
+.sp
+This option was new in Netpbm 10.36 (October 2006).
+
+
+     
+.TP
+\fB-net\fP
+Specifies the 6 hex-digit operator network code for Operator
+Logos (Default is 62F210 = D1,Germany).
+
+.TP
+\fB-txt\fP
+Specifies the text message for Picture Messages.  The maximum size
+text message allowed by the format is 120 characters.
+.sp
+Default is no text message.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+
+This program currently accepts all PBM images with up to 255 rows or up to 255
+columns.  (Valid Nokia Group Graphics or Operator Logos can be 72 columns by 14
+rows and 78 columns by 21 rows; valid Nokia Picture Messages are 72 columns by
+28 rows.)  This program generates black and white graphics, not animated.
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pbm" (1)\c
+\&,
+
+.IP \(bu
+Nokia Smart Messaging Specification (
+.UR http://forum.nokia.com
+http://forum.nokia.com
+.UE
+\&)
+
+.IP \(bu
+
+.BR "
+http://www.kessler-design.com/wireless/samples.html" (1)\c
+\&
+
+.IP \(bu
+
+.UR http://www.gnokii.org
+Gnokii
+.UE
+\&
+
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2001 Tim Ruehsen <\fItim.ruehsen@openmediasystem.de\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtonokia.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtopgm.1 b/upstream/mageia-cauldron/man1/pbmtopgm.1
new file mode 100644
index 00000000..062a03b7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtopgm.1
@@ -0,0 +1,92 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtopgm User Manual" 0 "05 Feb 2003" "netpbm documentation"
+
+.SH NAME
+
+pbmtopgm - convert PBM image to PGM by averaging areas
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtopgm \fP
+\fIwidth\fP
+\fIheight\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtopgm\fP reads a PBM image as input.  It outputs a PGM image
+in which each pixel's gray level is the average of the surrounding
+black and white input pixels.  The surrounding area is a rectangle of
+\fIwidth\fP by \fIheight\fP pixels.
+.PP
+In other words, this is a convolution.  \fBpbmtopgm\fP is similar
+to a special case of \fBpnmconvol\fP.
+.PP
+You may need a \fBpnmsmooth\fP step after \fBpbmtopgm\fP.
+.PP
+\fBpbmtopgm\fP has the effect of anti-aliasing bitmaps which
+contain distinct line features.
+.PP
+\fBpbmtopgm\fP works best with odd sample width and heights.
+.PP
+You don't need \fBpbmtopgm\fP just to use a PGM program on a PBM
+image.  Any PGM program (assuming it uses the Netpbm libraries to read
+the PGM input) takes PBM input as if it were PGM, with only the
+minimum and maximum gray levels.  So unless your convolution rectangle
+is bigger than one pixel, you're not gaining anything with a
+\fBpbmtopgm\fP step.
+.PP
+The opposite transformation (which would turn a PGM into a PBM) is
+dithering.  See \fBpamditherbw\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1990 by Angus Duggan.
+.PP
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.  This software is provided "as is"
+without express or implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtopi3.1 b/upstream/mageia-cauldron/man1/pbmtopi3.1
new file mode 100644
index 00000000..9e150f6e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtopi3.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtopi3 User Manual" 0 "11 March 1990" "netpbm documentation"
+
+.SH NAME
+pbmtopi3 - convert a PBM image into an Atari Degas .pi3 file 
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtopi3\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtopi3\fP reads a PBM image as input and produces an Atari
+Degas .pi3 file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtopi3\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pi3topbm" (1)\c
+\&,
+.BR "ppmtopi1" (1)\c
+\&,
+.BR "pi1toppm" (1)\c
+\&
+.BR "pbm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by David Beckemeyer (bdt!david) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtopi3.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtopk.1 b/upstream/mageia-cauldron/man1/pbmtopk.1
new file mode 100644
index 00000000..1e5c3ab8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtopk.1
@@ -0,0 +1,162 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtopk User Manual" 0 "06 August 1990" "netpbm documentation"
+
+.SH NAME
+pbmtopk - convert a PBM image into a packed (PK) format font
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtopk\fP
+\fIpkfile\fP[\fB.pk\fP]
+\fItfmfile\fP[\fB.tfm\fP]
+\fIresolution\fP
+[\fB-s\fP \fIdesignsize\fP]
+[\fB-p\fP \fInum\fP \fIparam\fP...]
+[\fB-C\fP \fIcodingscheme\fP]
+[\fB-F\fP \fIfamily\fP]
+[\fB-f\fP \fIoptfile\fP]
+[\fB-c\fP \fInum\fP]
+[\fB-W\fP \fIwidth\fP]
+[\fB-H\fP \fIheight\fP]
+[\fB-D\fP \fIdepth\fP]
+[\fB-I\fP \fIital\fP]
+[\fB-h\fP \fIhoriz\fP]
+[\fB-v\fP \fIvert\fP]
+[\fB-x\fP \fIxoff\fP]
+[\fB-y\fP \fIyoff\fP]
+[\fIpbmfile\fP ...]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtopk\fP reads PBM images as input and produces a packed (PK)
+font file and a TFM (TeX font metric) file as output. The resolution
+parameter indicates the resolution of the font, in dots per inch. If
+the filename "-" is used for any of the filenames,
+\fBpbmtopk\fP uses Standard Input or Standard Output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtopk\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-s\fP \fIdesignsize\fP
+Sets the design size of the font, in TeX's points (72.27pt to the inch). The
+default design size is 1. The TFM parameters are given as multiples of the
+design size.
+
+.TP
+\fB-p\fP \fInum\fP \fIparam\fP...
+Sets the first num font parameters for the font. The first seven
+parameters are the slant, interword spacing, interword space
+stretchability, interword space shrinkability, x-height, quad width,
+and post-sentence extra space of the font. Math and symbol fonts may
+have more parameters; see The TeXbook for a list of these. Reasonable
+default values are chosen for parameters which are not specified.
+
+.TP
+\fB-C\fP \fIcodingscheme\fP
+Sets the coding scheme comment in the TFM file.
+
+.TP
+\fB-F\fP \fIfamily\fP
+Sets the font family comment in the TFM file.
+
+.TP
+\fB-f\fP \fIoptfile\fP
+Reads the file optfile, which should contain a lines of the form:
+
+.nf
+   filename xoff yoff horiz vert width height depth ital
+
+.fi
+.sp
+The PBM files specified by the filename parameters are inserted
+consecutively in the font with the specified attributes. If any of the
+attributes are omitted, or replaced with "*", a default
+value will be calculated from the size of the bitmap. The settings of
+the -W, -H, -D, -I, -h, -v, -x, and -y options do not affected
+characters created in this way.  The character number can be changed
+by including a line starting with "=", followed by the new
+number.  Lines beginning with "%" or "#" are
+ignored.
+
+.TP
+\fB-c\fP \fInum\fP
+Sets the character number of the next bitmap encountered to num.
+
+.TP
+\fB-W\fP \fIwidth\fP
+Sets the TFM width of the next character to width (in design size
+multiples).
+
+.TP
+\fB-H\fP \fIheight\fP
+Sets the TFM height of the next character to height (in design
+size multiples).
+
+.TP
+\fB-D\fP \fIdepth\fP
+Sets the TFM depth of the next character to depth (in design size
+multiples).
+
+.TP
+\fB-I\fP \fIital\fP
+Sets the italic correction of the next character to ital (in
+design size multiples).
+
+.TP
+\fB-h\fP \fIhoriz\fP
+Sets the horizontal escapement of the next character to horiz (in
+pixels).
+
+.TP
+\fB-v\fP \fIvert\fP
+Sets the vertical escapement of the next character to vert (in pixels).
+
+.TP
+\fB-x\fP \fIxoff\fP
+Sets the horizontal offset of the next character to xoff (in
+pixels).
+
+.TP
+\fB-y\fP \fIyoff\fP
+Sets the vertical offset of the next character to yoff (in pixels,
+from the top row).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pktopbm" (1)\c
+\&, 
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Adapted from Tom Rokicki's pxtopk by Angus Duggan <\fIajcd@dcs.ed.ac.uk\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtopk.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoplot.1 b/upstream/mageia-cauldron/man1/pbmtoplot.1
new file mode 100644
index 00000000..c8fd1e2a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoplot.1
@@ -0,0 +1,55 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoplot User Manual" 0 "01 September 1990" "netpbm documentation"
+
+.SH NAME
+pbmtoplot - convert a PBM image into a Unix 'plot' file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoplot\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoplot\fP reads a PBM image as input and produces a Unix
+\fBplot\fP file as output.
+.PP
+Note that there is no plottopbm tool - this transformation is one-way.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtoplot\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&,
+\fBplot\fP(1)
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Arthur David Olson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoplot.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoppa.1 b/upstream/mageia-cauldron/man1/pbmtoppa.1
new file mode 100644
index 00000000..0ed693a1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoppa.1
@@ -0,0 +1,325 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoppa User Manual" 0 "01 May 2005" "netpbm documentation"
+
+.SH NAME
+pbmtoppa - convert PBM image to HP Printer Performance Architecture (PPA)
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoppa\fP
+[\fIpbm_file\fP
+[\fIppa_file\fP]]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpbmtoppa\fP converts page images in PBM format to Hewlett
+Packard's PPA (Printer Performance Architecture) format, which is the
+data stream format expected by some HP "Windows-only"
+printers including the HP Deskjet 820C series, the HP DeskJet 720
+series, and the HP DeskJet 1000 series.
+.PP
+\fIpbm_file\fP is the file specification of the input file or
+\fB-\fP for Standard Input.  The default is Standard Input.
+.PP
+The input file contains one or more PBM images, with each one
+being a single page.  Each image must have the exact dimensions of a
+page (at 600 pixels per inch in both directions).  Significantly, this
+is the format that Ghostscript produces.
+.PP
+\fIppa_file\fP is the file specification of the output file or
+\fB-\fP for Standard Output.  The default is Standard Output.
+.PP
+To print Postscript on an HP PPA printer, just use Ghostscript with
+the \fBpbmraw\fP (or \fBpbm\fP) device driver.
+.PP
+You can generate a test page for use with this program with
+\fBpbmpage\fP.
+.PP
+You can also set up a printer filter so you can submit PBM input
+directly to your print queue.  See the documentation for your print
+spooler for information on how to do that, or look in hp820install.doc
+for an example lpd print filter for Postscript and text files.
+.PP
+Sometimes, \fBpbmtoppa\fP generates a file which the printer will
+not print (because \fBpbmtoppa\fP's input is unprintable).  When this
+happens, all three lights blink to signal the error.  This is usually
+because there is material outside of the printer's printable area.  To
+make the file print, increase the margins via \fBpbmtoppa\fP options
+or a configuration file.  See 
+.UR #calibration
+the section on calibration 
+.UE
+\& below.
+
+.SS About PPA
+.PP
+The PPA printer language is a far lower level language than most.
+When you use a PPA printer, most of the processing that a conventional
+printer does is done instead on the computer end of the wire.  In
+particular, \fBpbmtoppa\fP has to do "swath cutting," and
+"sweep formatting," which other printers do themselves.
+There is very little intelligence inside a PPA printer;
+\fBpbmtoppa\fP generates direct controls for the printer's hardware.
+.PP
+The design goal of PPA was to reduce the cost of a printer by exploiting
+computing resources already present in the computer that requests the
+printing.  CPU power, ROM, and RAM requirements inside the printer are all
+reduced compared to a conventional printer.
+.PP
+PPA was new in 1997.  It was preceded by Hewlett Packard's PCL
+(Printer Control Language) language.  HP manufactured PPA printers for only
+a few years, and no one else ever did.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoppa\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-v\fP \fIversion\fP
+printer version (720, 820, or 1000)
+
+.TP
+\fB-x\fP \fIxoff\fP
+horizontal offset adjustment in 1/600 inches.
+
+.TP
+\fB-y\fP \fIyoff\fP
+vertical offset adjustment in 1/600 inches.
+
+.TP
+\fB-t\fP \fItopmarg\fP
+top margin in 1/600 inches    (default: 150 = 0.25 inch)
+
+.TP
+\fB-l\fP \fIleftmarg\fP
+left margin in 1/600 inches   (default: 150 = 0.25 inch)
+
+.TP
+\fB-r\fP \fIrightmarg\fP
+right margin in 1/600 inches (default: 150 = 0.25 inch)
+
+.TP
+\fB-b\fP \fIbotmarg\fP
+bottom margin in 1/600 inches (default: 150 = 0.25 inch)
+
+.TP
+\fB-s\fP \fIpaper\fP
+paper size: \fBus\fP or \fBa4\fP.  Default is \fBus\fP.
+
+.TP
+\fB-d\fP \fIdpi\fP
+Print resolution in dots per inch.
+
+.TP
+\fB-f\fP \fIcfgfile\fP
+Read parameters from the configuration file named \fIcfgfile\fP.
+See 
+.UR #configfile
+CONFIGURATION FILES
+.UE
+\&
+
+
+.PP
+The offset adjustments you specify with \fB-x\fP and \fB-y\fP
+accumulate.  I.e. if you specify them multiple times, the total offset
+adjustment is the sum of the adjustments you specify.  \fB-x 60 -x 120\fP
+is the same as \fB-x 180\fP.
+.PP
+The \fB-v\fP option undoes any preceding \fB-x\fP and \fB-y\fP
+options, leaving the horizontal and vertical adjustments their
+default values.
+
+
+.UN configfile
+.SH CONFIGURATION FILES
+.PP
+You can use a configuration file to specify parameters rather than
+use invocation options.  \fBpbmtoppa\fP processes the file
+\fB/etc/pbmtoppa.conf\fP, if it exists, before processing any
+options.  It then processes each configuration file named by a
+\fB-f\fP option in order, applying the parameters from the
+configuration file as if they were invocation options used in the
+place of the \fB-f\fP option.
+.PP
+Configuration files have the following format:
+
+.nf
+\fB#\fP\fIComment\fP
+\fIkey1\fP \fIvalue1\fP
+\fIkey2\fP \fIvalue2\fP
+[etc.]
+
+.fi
+.PP
+Valid \fIkey\fPs are \fBversion\fP, \fBxoffset\fP,
+\fByoffset\fP, \fBtopmargin\fP, \fBleftmargin\fP,
+\fBrightmargin\fP, \fBbottommargin\fP, \fBpapersize\fP, or any
+non-null prefix of these words.  Valid values are the same as with the
+corresponding invocation parameters.
+
+.UN examples
+.SH EXAMPLES
+.PP
+Print a test pattern: 
+.nf
+\fBpbmpage | pbmppa >/dev/lp1\fP
+
+.fi
+.PP
+Print three pages:
+.nf
+\fBcat page1.pbm page2.pbm page3.pbm | pbmppa >/dev/lp1\fP
+
+.fi
+.PP
+Print the Postscript file myfile.ps:
+.nf
+gs -sDEVICE=rawpbm -q -dNOPAUSE -r600 \e
+   -sOutputFile=- myfile.ps ;\e
+| pbmtoppa | lpr
+
+.fi
+
+.UN calibration
+.SH CALIBRATION
+.PP
+To be able to print successfully and properly, you need to tell
+\fBpbmtoppa\fP an X and a Y offset appropriate for your printer to
+use when generating the page.  You can specify these offsets with the
+\fB-x\fP and \fB-y\fP invocation options or with the \fBxoff\fP and
+\fByoff\fP parameters in a \fBpbmtoppa\fP configuration file.
+.PP
+To determine the correct offsets, use the \fBpbmpage\fP program.
+.PP
+If while trying to do this calibration, the printer refuses to
+print a page, but just blinks all three lights, specify large margins
+(e.g. 600 pixels -- one inch) via \fBpbmpage\fP invocation options
+while doing the calibration.
+.PP
+For example:
+.nf
+\fBpbmpage | pbmtoppa >/dev/lp1\fP
+
+.fi
+or
+.nf
+\fBpbmpage | pbmtoppa | lpr -l\fP
+
+.fi
+
+(if your printer filter recognizes the '-l' (direct output) parameter).
+.PP
+In the test pattern, the grid is marked off in pixel coordinate
+numbers.  Unfortunately, these coordinates are probably cut off before
+the edge of the paper.  You'll have to use a ruler to estimate the
+pixel coordinate of the left and top edges of the actual sheet of
+paper (should be within +/- 300, may be negative; there are 600 pixels
+per inch).
+.PP
+Add these coordinates to the X and Y offsets by either editing the
+configuration file or using the \fB-x \fP and \fB-y\fP command-line
+parameters.
+.PP
+When \fBpbmtoppa\fP is properly calibrated, the center mark should
+be in the center of the paper.  Also, the margins should be able to be
+as small as 1/4 inch without causing the printer to choke with
+\&'blinking lights syndrome'.
+
+.UN redhat
+.SH RED HAT LINUX INSTALLATION
+.PP
+RedHat users may find the following tip from Panayotis Vryonis
+<\fIvrypan@hol.gr\fP> helpful.  The
+same should work for the 820 and 1000, but it hasn't been tested.
+Also, use the pbmraw GSDriver if you have it; it's faster.
+.PP
+Here is a tip to integrate HP720C capability in RedHat's printtool:
+.PP
+Install pbmtoppa. Copy pbmtoppa to /usr/bin.
+.PP
+Edit "printerdb" (in my system it is found in
+/usr/lib/rhs/rhs-printfilters ) and append the following lines:
+
+.nf
+\f(CW
+  
+----------------------Cut here-----------------------
+
+StartEntry: DeskJet720C
+  GSDriver: pbm
+  Description:\ {HP\ DeskJet\ 720C}
+  About: { \e
+        This driver drives the HP DeskJet 720C \e
+        inkjet printer. \e
+        It cannot do color printing. \e
+        IMPORTANT! Insert \e
+           "- | pbm2ppa -" \e
+        in the "Extra GS Options " field.\e
+      }
+
+  Resolution: {600} {600} {}
+
+EndEntry
+----------------------------------------------------
+  \fP
+
+.fi
+.PP
+Now you can add an HP720C printer just like any other, using
+printtool.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmpage" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.PP
+This program was derived from \fBpbm2ppa\fP.  \fBpbm2ppa\fP is obsolete 
+and has been replaced by \fBpnm2ppa\fP, which does the same things as 
+\fBpbmtoppa\fP except it also works with color and has lots more features.  See 
+.UR http://pnm2ppa.sourceforge.net
+http://pnm2ppa.sourceforge.net
+.UE
+\& 
+for more information about the PPA protocol and the separately distributed 
+\fBpnm2ppa\fP program.
+.PP
+The file INSTALL-MORE in the pbmtoppa directory of the Netpbm
+source code contains detailed instructions on setting up a system to
+use pbmtoppa to allow convenient printing on HP PPA printers.  It was
+written by Michael Buehlmann.
+
+.UN author
+.SH AUTHOR
+.PP
+Tim Norman.  Copyright (C) 1998.  Licensed under GNU Public License
+.PP
+Manual page by Bryan Henderson, May 2000.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoppa.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtopsg3.1 b/upstream/mageia-cauldron/man1/pbmtopsg3.1
new file mode 100644
index 00000000..3e701e5d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtopsg3.1
@@ -0,0 +1,93 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtopsg3 User Manual" 0 "12 March 2017" "netpbm documentation"
+
+.SH NAME
+pbmtopsg3 - convert PBM images to Postscript with G3 fax compression
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtopsg3\fP
+[\fB--title=\fP\fItitle\fP]
+[\fB--dpi=\fP\fIdpi\fP]
+[\fIfilespec\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtopsg3\fP converts the PBM images in the input PBM file to
+pages in a Postscript file encoded with G3 fax compression.
+.PP
+\fBpnmtops\fP is a more general program for converting from the Netpbm
+formats to Postscript, though it cannot produce the particular subformat
+that \fBpbmtopsg3\fP does.
+.PP
+If you don't specify \fIfilespec\fP, the input is from Standard
+Input.
+.PP
+Remember that you can create a multi-image PBM file simply by
+concatenating single-image PBM files, so if each page is in a
+different file, you might do:
+
+.nf
+cat faxpage* | pbmtopsg3 >fax.ps
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtopsg3\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-title\fP
+The Postscript title value.  Default is no title.
+
+.TP
+\fB-dpi\fP
+The resolution of the Postscript output.  Default is 72 dpi.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtops" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+\fBgs\fP,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbmtolps" (1)\c
+\&,
+.BR "pbmtoepsi" (1)\c
+\&,
+.BR "pbmtog3" (1)\c
+\&,
+.BR "g3topbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "fax formats" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtopsg3.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoptx.1 b/upstream/mageia-cauldron/man1/pbmtoptx.1
new file mode 100644
index 00000000..42d73f60
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoptx.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoptx User Manual" 0 "31 August 1988" "netpbm documentation"
+
+.SH NAME
+pbmtoptx - convert a PBM image into Printronix printer graphics
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoptx\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoptx\fP reads a PBM image as input and produces a file of
+Printronix printer graphics as output.
+.PP
+Note that there is no ptxtopbm tool - this transformation is one way.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtoptx\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoptx.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtosunicon.1 b/upstream/mageia-cauldron/man1/pbmtosunicon.1
new file mode 100644
index 00000000..1800c4cf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtosunicon.1
@@ -0,0 +1,61 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtosunicon User Manual" 0 "30 January 2011" "netpbm documentation"
+
+.SH NAME
+
+pbmtosunicon - convert a PBM image into a Sun icon
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtosunicon\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtosunicon\fP reads a PBM image as input and produces a Sun icon
+as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtosunicon\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "sunicontopnm" (1)\c
+\&,
+.BR "ppmtowinicon" (1)\c
+\&,
+.BR "pbmtozinc" (1)\c
+\&,
+.BR "ppmtouil" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtosunicon.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtowbmp.1 b/upstream/mageia-cauldron/man1/pbmtowbmp.1
new file mode 100644
index 00000000..55031129
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtowbmp.1
@@ -0,0 +1,62 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtowbmp User Manual" 0 "19 November 1999" "netpbm documentation"
+
+.SH NAME
+pbmtowbmp - convert a PBM image to a wireless bitmap (wbmp) file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtowbmp\fP
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtowbmp\fP reads a PBM image as input and
+produces a wbmp file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtowbmp\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBpbmtowbmp\fP can generate only WBMP type 0. This is the only
+type specified in the WAP 1.1 specifications.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&,
+.BR "wbmptopbm" (1)\c
+\&,
+
+\fBWireless Application Environment Specification\fP.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1999 Terje Sannum <\fIterje@looplab.com\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtowbmp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtox10bm.1 b/upstream/mageia-cauldron/man1/pbmtox10bm.1
new file mode 100644
index 00000000..7fe16f23
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtox10bm.1
@@ -0,0 +1,33 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtox10bm User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+pbmtox10bm - replaced by pbmtoxbm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtox10bm\fP was replaced in Netpbm 10.37 (December 2006) by
+.BR "pbmtoxbm" (1)\c
+\&.
+.PP
+\fBpbmtoxbm\fP with the \fB-x10\fP option is backward compatible
+with \fBpbmtox10bm\fP.  \fBpbmtoxbm\fP also can generate X11 bitmaps.
+.PP
+You should not make any new use of \fBpbmtox10bm\fP and if you modify an
+existing use, you should upgrade to \fBpbmtoxbm\fP.  But note that if you
+write a program that might have to be used with old Netpbm, \fBpbmtox10bm\fP
+is the only way to do that.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtox10bm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoxbm.1 b/upstream/mageia-cauldron/man1/pbmtoxbm.1
new file mode 100644
index 00000000..2ddaf7f4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoxbm.1
@@ -0,0 +1,83 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoxbm User Manual" 0 "25 October 2006" "netpbm documentation"
+
+.SH NAME
+pbmtoxbm - convert a PBM image to an X11 bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoxbm\fP
+
+[{\fB-x10\fP|\fB-x11\fP}]
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpbmtoxbm\fP reads a PBM image as input and produces an X10 or X11 bitmap
+as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmtoxbm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-x10\fP
+This option causes \fBpbmtoxbm\fP to generate the X10 version of
+XBM.
+.sp
+You may not specify this with \fB-x11\fP.
+.sp
+This option was new with Netpbm 10.37 (December 2006).  Before that,
+use \fBpbmtox10bm\fP instead.
+
+.TP
+\fB-x11\fP
+This option causes \fBpbmtoxbm\fP to generate the X11 version of
+XBM.
+.sp
+You may not specify this with \fB-x10\fP.
+.sp
+The X11 version is the default, so this option has no effect.
+.sp
+This option was new with Netpbm 10.37 (December 2006).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtox10bm" (1)\c
+\&,
+.BR "xbmtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoxbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtoybm.1 b/upstream/mageia-cauldron/man1/pbmtoybm.1
new file mode 100644
index 00000000..d3f53b77
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtoybm.1
@@ -0,0 +1,57 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtoybm User Manual" 0 "06 March 1990" "netpbm documentation"
+
+.SH NAME
+
+pbmtoybm - convert a PBM image into a Bennet Yee "face" file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtoybm\fP
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtoybm\fP reads a PBM image as input and produces as output a
+file acceptable to the \fBface\fP and \fBxbm\fP programs by Bennet
+Yee (\fIbsy+@cs.cmu.edu\fP).
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtoybm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ybmtopbm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtoybm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmtozinc.1 b/upstream/mageia-cauldron/man1/pbmtozinc.1
new file mode 100644
index 00000000..debbdad4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmtozinc.1
@@ -0,0 +1,55 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmtozinc User Manual" 0 "02 November 1990" "netpbm documentation"
+
+.SH NAME
+
+pbmtozinc - convert a PBM image into a Zinc bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmtozinc\fP
+
+[\fIpbmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmtozinc\fP reads a PBM image as input and produces a bitmap
+in the format used by the Zinc Interface Library (ZIL) Version 1.0 as
+output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpbmtozinc\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by James Darrell McCauley (\fIjdm5548@diamond.tamu.edu\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmtozinc.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pbmupc.1 b/upstream/mageia-cauldron/man1/pbmupc.1
new file mode 100644
index 00000000..7a54524f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pbmupc.1
@@ -0,0 +1,87 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pbmupc User Manual" 0 "29 April 2015" "netpbm documentation"
+
+.SH NAME
+
+pbmupc - create a Universal Product Code PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpbmupc\fP
+
+[\fB-s1\fP | \fB-s2\fP] \fItype\fP \fImanufacturer\fP \fIproduct\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpbmupc\fP generates an image of a Universal Product Code symbol.
+The three arguments are: a one digit product type, a five digit
+manufacturer code, and a five digit product code.
+For example, "0 72890 00011" is the code for Heineken.
+.PP
+\fBpbmupc\fP produces an image 230 bits wide and 175 bits high.  If you
+want a different size run the output through \fBpamscale\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpbmupc\fP recognizes the following
+command line options:
+.PP
+The \fB-s1\fP and \fB-s2\fP options select the style of UPC to
+generate.  The default, \fB-s1\fP, looks more or less like this:
+
+.nf
+ ||||||||||||||||
+ ||||||||||||||||
+ ||||||||||||||||
+ ||||||||||||||||
+0||12345||67890||5
+
+.fi
+
+The other style, \fB-s2\fP, puts the product type digit higher up,
+and doesn't display the checksum digit:
+
+.nf
+ ||||||||||||||||
+ ||||||||||||||||
+0||||||||||||||||
+ ||||||||||||||||
+ ||12345||67890||
+
+.fi
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamscale" (1)\c
+\&
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pbmupc.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pc1toppm.1 b/upstream/mageia-cauldron/man1/pc1toppm.1
new file mode 100644
index 00000000..ffa8449b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pc1toppm.1
@@ -0,0 +1,62 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pc1toppm User Manual" 0 "30 April 2004" "netpbm documentation"
+
+.SH NAME
+
+pc1toppm - convert an Atari Degas .pc1 into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpc1toppm\fP
+
+[\fIpc1file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpc1toppm\fP reads an Atari Degas .pc1 file as input and
+produces a PPM image as output.
+.PP
+The .pc1 format is a compressed (run length encoded) variation on .pi1.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpc1toppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN history
+.SH HISTORY
+.PP
+\fBpc1toppm\fP was new in Netpbm 10.22 (April 2004)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&,
+.BR "pi1toppm" (1)\c
+\&,
+.BR "pi3topbm" (1)\c
+\&,
+.BR "pbmtopi3" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pc1toppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pcdindex.1 b/upstream/mageia-cauldron/man1/pcdindex.1
new file mode 100644
index 00000000..8d6d679c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pcdindex.1
@@ -0,0 +1,26 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "pcdindex" 1 "" "netpbm documentation"
+
+.SH NAME
+
+pcdindex - renamed to pcdovtoppm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpcdindex\fP has been renamed to \fB
+.BR "pcdovtoppm" (1)\c
+\&.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pcdindex.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pcxtoppm.1 b/upstream/mageia-cauldron/man1/pcxtoppm.1
new file mode 100644
index 00000000..12d0d02d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pcxtoppm.1
@@ -0,0 +1,105 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pcxtoppm User Manual" 0 "19 April 2004" "netpbm documentation"
+
+.SH NAME
+
+pcxtoppm - convert a PCX file into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpcxtoppm\fP
+[\fB-stdpalette\fP]
+[\fB-verbose\fP]
+[\fIpcxfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpcxtoppm\fP reads a PCX file as input and produces a PPM image
+as output.
+.PP
+\fBpcxtoppm\fP recognizes the following PCX types:
+
+
+.IP \(bu
+Colormapped files with 2-16 colors.
+.sp
+"Packed pixel" format (1, 2 or 4 bits/pixel, 1 plane) or
+bitplane format (1 bit/pixel, 1-4 planes).  The program uses a
+predefined standard palette if the image does not provide one.
+"Does not provide one" means the palette in the PCX header is
+completely black.
+
+.IP \(bu
+Colormapped files with 256 colors.
+.sp
+8 bits/pixel, 1 plane, colormap at the end of the file.
+
+.IP \(bu
+24bit truecolor files.
+.sp
+24bit RGB: 8 bits/pixel, 3 planes.
+
+.IP \(bu
+32bit truecolor files.
+.sp
+24bit RGB + 8bit intensity: 8 bits/pixel, 4 planes.
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpcxtoppm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-stdpalette\fP
+This option causes \fBpcxtoppm\fP to use its predefined standard 
+palette even if the PCX image provides its own.  This is meaningful only
+for an image in the 16 color paletted PCX format.
+.sp
+The image may appear to provide its own palette but in fact be created
+by a program too primitive to understand palettes that created a random
+palette by accident.
+
+.TP
+\fB-verbose\fP
+Report details of the PCX header.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtopcx" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+.PP
+Copyright 1990 by Michael Davidson.
+.PP
+Modified 1994 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pcxtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pdbimgtopam.1 b/upstream/mageia-cauldron/man1/pdbimgtopam.1
new file mode 100644
index 00000000..bc7e1ee0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pdbimgtopam.1
@@ -0,0 +1,81 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pdbimgtopam User Manual" 0 "25 September 2010" "netpbm documentation"
+
+.SH NAME
+pdbimgtopam - convert a Palm Pilot Image Viewer PDB Image to a PAM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpdbimgtopam\fP
+
+[\fB-notefile=\fP\fIfilename\fP]
+[\fB-verbose\fP]
+
+[\fIpdbimgfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpdbimgtopam\fP reads a Palm Pilot Image Viewer image (and Image
+record in a PDB file) as input, from Standard Input or
+\fIpalmfile\fP, and produces a PAM image as output.
+.PP
+If the Pilot image is monochrome, the PAM output has maxval 1.
+Otherwise, it has maxval 255.  Note that Pilot images are always
+monochrome.  The PAM image has tuple type GRAYSCALE.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpdbimgtopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display various interesting information about the input file and process.
+
+.TP
+\fB-notefile=\fP\fIfilename\fP
+Write the image note (if any) to the specified file.
+.sp
+If you don't specify this, \fBpdbimgtopam\fP ignores any image note.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopdbimg" (1)\c
+\&,
+.BR "pnmtopalm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpdbimgtopam\fP was new in Netpbm 10.52 (September 2010).
+It was modelled after Eric A. Howe's \fBimgvtopbm\fP package, which
+dates back to September 1997.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pdbimgtopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pdf2dsc.1 b/upstream/mageia-cauldron/man1/pdf2dsc.1
new file mode 100644
index 00000000..ff73bf90
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pdf2dsc.1
@@ -0,0 +1,33 @@
+.TH PDF2DSC 1 "01 November 2023" 10.02.1 "Ghostscript Tools" \" -*- nroff -*-
+.SH NAME
+pdf2dsc \- generate a PostScript page list of a PDF document
+.SH SYNOPSIS
+\fBpdf2dsc\fR \fIinput.pdf\fR [ \fIoutput.dsc\fR ]
+.SH DESCRIPTION
+\fBpdf2dsc\fR uses \fBgs\fR(1) to read an Adobe \fBPortable Document
+Format\fR (PDF) document "input.pdf" and create a \fBPostScript\fR(tm)
+document "output.dsc" that conforms to Adobe's \fBDocument Structuring
+Conventions\fR (DSC) requirements.
+.PP
+This new document simply tells Ghostscript to read the PDF file and to
+display pages one at a time.  The generated document can then be viewed
+with any PostScript viewer based on Ghostscript, like \fBghostview\fR(1) on
+Unix or \fBGSview\fR on Windows, with which the user can browse through the
+pages of the PDF document in any order.
+.PP
+If no output file is named on the command line, the name of the output file
+is that of the input file with any extension removed, followed by the
+extension "\.dsc".
+.SH CAVEATS
+The DSC document uses Ghostscript-specific procedures.  In addition, the
+original PDF document must be accessible when the DSC document is
+processed.
+.PP
+You need the file "pdf2dsc.ps" (originally by Russell Lang) supplied with
+Ghostscript since release 3.53.
+.SH SEE ALSO
+gs(1), ghostview(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Yves Arrouye <yves.arrouye@usa.net> and Russell Lang gsview at ghostgum.com.au
diff --git a/upstream/mageia-cauldron/man1/pdf2ps.1 b/upstream/mageia-cauldron/man1/pdf2ps.1
new file mode 100644
index 00000000..b81c5710
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pdf2ps.1
@@ -0,0 +1,20 @@
+.TH PDF2PS 1 "01 November 2023" 10.02.1 "Ghostscript Tools" \" -*- nroff -*-
+.SH NAME
+pdf2ps \- Ghostscript PDF to PostScript translator
+.SH SYNOPSIS
+\fBpdf2ps\fR [ \fIoptions\fR ] \fIinput.pdf [output.ps]\fR
+.SH DESCRIPTION
+\fBpdf2ps\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document
+Format\fR (PDF) file "input.pdf" to \fBPostScript\fR(tm) in "output.ps".
+Normally the output is allowed to use PostScript Level 2 (but not PostScript
+LanguageLevel 3) constructs; the \fB-dLanguageLevel=1\fR option restricts
+the output to Level 1, while \fB-dLanguageLevel=3\fR allows using
+LanguageLevel 3 in the output.
+.SH FILES
+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your
+system, from which you can get more details.
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
diff --git a/upstream/mageia-cauldron/man1/pdfroff.1 b/upstream/mageia-cauldron/man1/pdfroff.1
new file mode 100644
index 00000000..b29563b0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pdfroff.1
@@ -0,0 +1,839 @@
+.TH PDFROFF 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+pdfroff \- create PDF documents using groff
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr pdfroff_C \n[.C]
+.cp 0
+.
+.
+.\" pdfroff.1
+.\" File position: <groff-source>/contrib/pdfmark/pdfroff.man
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 2005-2018 Free Software Foundation, Inc.
+.\"
+.\" This file is part of groff, the GNU roff type-setting system.
+.\"
+.\" Permission is granted to copy, distribute and/or modify this
+.\" document under the terms of the GNU Free Documentation License,
+.\" Version 1.3 or any later version published by the Free Software
+.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
+.\" and with no Back-Cover Texts.
+.\"
+.\" A copy of the Free Documentation License is included as a file
+.\" called FDL in the main directory of the groff source package.
+.
+.
+.\" ====================================================================
+.\" Local macro definitions
+.
+.hw pdfmark
+.
+.
+.\" ====================================================================
+.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY pdfroff
+.OP \-abcegilpstzCEGNRSUVXZ
+.OP \-d cs
+.OP \-f fam
+.OP \-F dir
+.OP \-I dir
+.OP \-L arg
+.OP \-m name
+.OP \-M dir
+.OP \-n num
+.OP \-o list
+.OP \-P arg
+.OP \-r cn
+.OP \-T dev
+.OP \-w name
+.OP \-W name
+.OP \-\-emit\-ps
+.OP \-\-no\-toc\-relocation
+.OP \-\-no-kill\-null\-pages
+.RB [ \-\-stylesheet=\c
+.IR name ]
+.OP \-\-no\-pdf\-output
+.RB [ \-\-pdf\-output=\c
+.IR name ]
+.OP \-\-no\-reference\-dictionary
+.RB [ \-\-reference\-dictionary=\c
+.IR  name ]
+.OP \-\-report\-progress
+.OP \-\-keep\-temporary\-files
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY pdfroff
+.B \-h
+.SY pdfroff
+.B \-\-help
+.YS
+.
+.SY pdfroff
+.B \-v
+.RI [ groff-option
+\&.\|.\|.\&]
+.SY pdfroff
+.B \-\-version
+.RI [ groff-option
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B pdfroff
+is a wrapper program for the GNU text processing system,
+.BR  groff .
+.
+It transparently handles the mechanics of multiple pass
+.B groff
+processing, when applied to suitably marked up
+.B groff
+source files,
+such that tables of contents and body text are formatted separately,
+and are subsequently combined in the correct order, for final publication
+as a single PDF document.
+.
+A further optional
+\*(lqstyle sheet\*(rq
+capability is provided;
+this allows for the definition of content which is required to precede the
+table of contents, in the published document.
+.
+.P
+For each invocation of
+.BR pdfroff ,
+the ultimate
+.B groff
+output stream is post-processed by the GhostScript interpreter,
+to produce a finished PDF document.
+.
+.P
+.B pdfroff
+makes no assumptions about, and imposes no restrictions on, the use of
+any
+.B groff
+macro packages which the user may choose to employ,
+in order to achieve a desired document format;
+however, it
+.I does
+include specific built in support for the
+.B pdfmark
+macro package, should the user choose to employ it.
+.
+Specifically, if the
+.I pdfhref
+macro, defined in the
+.I pdfmark.tmac
+package, is used to define public reference marks, or dynamic links to
+such reference marks, then
+.B pdfroff
+performs as many preformatting
+.B groff
+passes as required, up to a maximum limit of
+.IR four ,
+in order to compile a document reference dictionary, to resolve
+references, and to expand the dynamically defined content of links.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+The command line is parsed in accordance with normal GNU conventions,
+but with one exception \(em when specifying any short form option
+(i.e., a single character option introduced by a single hyphen),
+and if that option expects an argument, then it
+.I must
+be specified independently (i.e., it may
+.I not
+be appended to any group of other single character short form options).
+.
+.
+.P
+Long form option names (i.e., those introduced by a double hyphen) may
+be abbreviated to their minimum length unambiguous initial substring.
+.
+.
+.P
+Otherwise,
+.B pdfroff
+usage closely mirrors that of
+.B groff
+itself.
+.
+Indeed, with the exception of the
+.BR \-h ,
+.BR \-v ,
+and
+.BI \-T \ dev
+short form options, and all long form options, which are parsed
+internally by
+.BR pdfroff ,
+all options and file name arguments specified on the command line are
+passed on to
+.BR groff ,
+to control the formatting of the PDF document.
+.
+Consequently,
+.B pdfroff
+accepts all options and arguments, as specified in
+.BR groff (1),
+which may also be considered as the definitive reference for all standard
+.B pdfroff
+options and argument usage.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.B pdfroff
+accepts all of the short form options (i.e., those introduced by a
+single hyphen), which are available with
+.B groff
+itself.
+.
+In most cases, these are simply passed transparently to
+.BR groff ;
+the following, however, are handled specially by
+.BR pdfroff .
+.
+.TP
+.B \-h
+Same as
+.BR \-\-help ;
+see below.
+.
+.TP
+.B \-i
+Process standard input, after all other specified input files.
+.
+This is passed transparently to
+.BR groff ,
+but, if grouped with other options, it
+.I must
+be the first in the group.
+.
+Hiding it within a group breaks standard input processing, in the
+multiple pass
+.B groff
+processing context of
+.BR pdfroff .
+.
+.TP
+.BI \-T \ dev
+Only
+.B \-T\ ps
+is supported by
+.BR pdfroff .
+.
+Attempting to specify any other device causes
+.B pdfroff
+to abort.
+.
+.TP
+.B \-v
+Same as
+.BR \-\-version ;
+see below.
+.
+.
+.P
+See
+.BR groff (1)
+for a description of all other short form options, which are
+transparently passed through
+.B pdfroff
+to
+.BR groff .
+.
+.
+.P
+All long form options (i.e., those introduced by a double hyphen) are
+interpreted locally by
+.BR pdfroff ;
+they are
+.B not
+passed on to
+.BR groff ,
+unless otherwise stated below.
+.
+.TP
+.B \-\-help
+Causes
+.B pdfroff
+to display a summary of the its usage syntax, and supported options,
+and then exit.
+.
+.TP
+.B \-\-emit\-ps
+Suppresses the final output conversion step, causing
+.B pdfroff
+to emit PostScript output instead of PDF.
+.
+This may be useful, to capture intermediate PostScript output, when
+using a specialised postprocessor, such as
+.I gpresent
+for example,
+in place of the default
+.I GhostScript
+PDF writer.
+.
+.TP
+.B \-\-keep\-temporary\-files
+Suppresses the deletion of temporary files, which normally occurs
+after
+.B pdfroff
+has completed PDF document formatting; this may be useful, when
+debugging formatting problems.
+.
+.IP
+See section \[lq]Files\[rq] below for a description of the temporary
+files used by
+.BR pdfroff .
+.
+.TP
+.B \-\-no\-pdf\-output
+May be used with the
+.BI \%\-\-reference\-dictionary= name
+option (described below) to eliminate the overhead of PDF formatting,
+when running
+.B pdfroff
+to create a reference dictionary, for use in a different document.
+.
+.TP
+.B \-\-no\-reference\-dictionary
+May be used to eliminate the overhead of creating a reference dictionary,
+when it is known that the target PDF document contains no public
+references, created by the
+.I pdfhref
+macro.
+.
+.TP
+.B \-\-no\-toc\-relocation
+May be used to eliminate the extra
+.B groff
+processing pass,
+which is required to generate a table of contents,
+and relocate it to the start of the PDF document,
+when processing any document which lacks an automatically
+generated table of contents.
+.
+.TP
+.B \-\-no\-kill\-null\-pages
+While preparing for simulation of the manual collation step,
+which is traditionally required to relocate a
+.I "table of contents"
+to the start of a document,
+.B pdfroff
+accumulates a number of empty page descriptions
+into the intermediate
+.I PostScript
+output stream.
+During the final collation step,
+these empty pages are normally discarded from the finished document;
+this option forces
+.B pdfroff
+to leave them in place.
+.
+.TP
+.BI \-\-pdf\-output= name
+Specifies the name to be used for the resultant PDF document;
+if unspecified, the PDF output is written to standard output.
+A future version of
+.B pdfroff
+may use this option,
+to encode the document name in a generated reference dictionary.
+.
+.TP
+.BI \-\-reference\-dictionary= name
+Specifies the name to be used for the generated reference dictionary file;
+if unspecified, the reference dictionary is created in a temporary file,
+which is deleted when
+.B pdfroff
+completes processing of the current document.
+.
+This option
+.I must
+be specified, if it is desired to save the reference dictionary,
+for use in references placed in other PDF documents.
+.
+.TP
+.B \-\-report\-progress
+Causes
+.B pdfroff
+to display an informational message on standard error,
+at the start of each
+.B groff
+processing pass.
+.
+.TP
+.BI \-\-stylesheet= name
+Specifies the name of an
+.IR "input file" ,
+to be used as a style sheet for formatting of content,
+which is to be placed
+.I before
+the table of contents,
+in the formatted PDF document.
+.
+.TP
+.B \-\-version
+Causes
+.B pdfroff
+to display a version identification message.
+.
+The entire command line is then passed transparently to
+.BR groff ,
+in a
+.I one
+pass operation
+.IR only ,
+in order to display the associated
+.B groff
+version information, before exiting.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+The following environment variables may be set, and exported,
+to modify the behaviour of
+.BR pdfroff .
+.
+.TP
+.I PDFROFF_COLLATE
+Specifies the program to be used
+for collation of the finished PDF document.
+.
+.IP
+This collation step may be required to move
+.I tables of contents
+to the start of the finished PDF document,
+when formatting with traditional macro packages,
+which print them at the end.
+.
+However, users should not normally need to specify
+.IR \%PDFROFF_COLLATE ,
+(and indeed, are not encouraged to do so).  If unspecified,
+.B pdfroff
+uses
+.BR sed (1)
+by default,
+which normally suffices.
+.
+.IP
+If
+.I \%PDFROFF_COLLATE
+.I is
+specified,
+then it must act as a filter,
+accepting a list of file name arguments,
+and write its output to the
+.I stdout
+stream,
+whence it is piped to the
+.IR \%PDFROFF_POSTPROCESSOR_COMMAND ,
+to produce the finished PDF output.
+.
+.IP
+When specifying
+.IR \%PDFROFF_COLLATE ,
+it is normally necessary to also specify
+.IR \%PDFROFF_KILL_NULL_PAGES .
+.
+.IP
+.I \%PDFROFF_COLLATE
+is ignored,
+if
+.B pdfroff
+is invoked with the
+.I \%\-\-no\-kill\-null\-pages
+option.
+.
+.TP
+.I PDFROFF_KILL_NULL_PAGES
+Specifies options to be passed to the
+.I \%PDFROFF_COLLATE
+program.
+.
+.IP
+It should not normally be necessary to specify
+.IR \%PDFROFF_KILL_NULL_PAGES .
+.
+The internal default is a
+.BR sed (1)
+script,
+which is intended to remove completely blank pages
+from the collated output stream,
+and which should be appropriate in most applications of
+.BR pdfroff .
+.
+However,
+if any alternative to
+.BR sed (1)
+is specified for
+.IR \%PDFROFF_COLLATE ,
+then it is likely that a corresponding alternative specification for
+.I \%PDFROFF_KILL_NULL_PAGES
+is required.
+.
+.IP
+As in the case of
+.IR \%PDFROFF_COLLATE ,
+.I \%PDFROFF_KILL_NULL_PAGES
+is ignored, if
+.B pdfroff
+is invoked with the
+.I \%\-\-no\-kill\-null\-pages
+option.
+.
+.TP
+.I PDFROFF_POSTPROCESSOR_COMMAND
+Specifies the command to be used for the final document conversion
+from PostScript intermediate output to PDF.
+.
+It must behave as a filter,
+writing its output to the
+.I stdout
+stream,
+and must accept an arbitrary number of
+.I files .\|.\|.\&
+arguments,
+with the special case of
+.I \-
+representing the
+.I stdin
+stream.
+.
+.IP
+If unspecified,
+.I \%PDFROFF_POSTPROCESSOR_COMMAND
+defaults to
+.
+.RS 12n
+.EX
+gs \-dBATCH \-dQUIET \-dNOPAUSE \-dSAFER \-sDEVICE=pdfwrite \e
+	\-sOutputFile=\-
+.EE
+.RE
+.
+.TP
+.I GROFF_TMPDIR
+Identifies the directory in which
+.B pdfroff
+should create temporary files.
+.
+If
+.I \%GROFF_TMPDIR
+is
+.I not
+specified, then the variables
+.IR TMPDIR ,
+.I TMP
+and
+.I TEMP
+are considered in turn, as possible temporary file repositories.
+If none of these are set, then temporary files are created
+in the current directory.
+.
+.TP
+.I GROFF_GHOSTSCRIPT_INTERPRETER
+Specifies the program to be invoked, when
+.B pdfroff
+converts
+.B groff
+PostScript output to PDF.
+.
+If
+.I \%PDFROFF_POSTPROCESSOR_COMMAND
+is specified,
+then the command name it specifies is
+.I implicitly
+assigned to
+.IR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
+overriding any explicit setting specified in the environment.
+.
+If
+.I \%GROFF_GHOSTSCRIPT_INTERPRETER
+is not specified, then
+.B pdfroff
+searches the process
+.IR PATH ,
+looking for a program with any of the well known names
+for the GhostScript interpreter;
+if no GhostScript interpreter can be found,
+.B pdfroff
+aborts.
+.
+.TP
+.I GROFF_AWK_INTERPRETER
+Specifies the program to be invoked, when
+.B pdfroff
+is extracting reference dictionary entries from a
+.B groff
+intermediate message stream.
+.
+If
+.I \%GROFF_AWK_INTERPRETER
+is not specified, then
+.B pdfroff
+searches the process
+.IR PATH ,
+looking for any of the preferred programs, \[oq]gawk\[cq],
+\[oq]mawk\[cq], \[oq]nawk\[cq], and \[oq]awk\[cq], in this order; if
+none of these are found,
+.B pdfroff
+issues a warning message, and continue processing;
+however, in this case, no reference dictionary is created.
+.
+.TP
+.I OSTYPE
+Typically defined automatically by the operating system,
+.I \%OSTYPE
+is used on Microsoft Win32/MS-DOS platforms
+.IR only ,
+to infer the default
+.I \%PATH_SEPARATOR
+character,
+which is used when parsing the process
+.I PATH
+to search for external helper programs.
+.
+.TP
+.I PATH_SEPARATOR
+If set,
+.I \%PATH_SEPARATOR
+overrides the default separator character,
+(\[oq]:\[cq] on POSIX/Unix systems,
+inferred from
+.I \%OSTYPE
+on Microsoft Win32/MS-DOS),
+which is used when parsing the process
+.I PATH
+to search for external helper programs.
+.
+.TP
+.I SHOW_PROGRESS
+If this is set to a non-empty value, then
+.B pdfroff
+always behaves as if the
+.B \%\-\-report\-progress
+option is specified, on the command line.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+Input and output files for
+.B pdfroff
+may be named according to any convention of the user's choice.
+Typically, input files may be named according to the choice of the
+principal formatting macro package, e.g.,
+.RI file .ms
+might be an input file for formatting using the
+.B ms
+macros
+.RI ( s.tmac );
+normally, the final output file should be named
+.RI file .pdf .
+.
+.
+.P
+Temporary files, created by
+.BR pdfroff ,
+are placed in the file system hierarchy,
+in or below the directory specified by environment variables
+(see section \[lq]Environment\[rq] above).
+.
+If
+.BR mktemp (1)
+is available,
+it is invoked to create a private subdirectory of
+the nominated temporary files directory,
+(with subdirectory name derived from the template
+.IR pdfroff\-XXXXXXXXXX );
+if this subdirectory is successfully created,
+the temporary files will be placed within it,
+otherwise they will be placed directly in the directory
+nominated in the environment.
+.P
+All temporary files themselves
+are named according to the convention
+.IR pdf $$ . *,
+where
+.I $$
+is the standard shell variable representing the process ID of the
+.B pdfroff
+process itself, and
+.I *
+represents any of the extensions used by
+.B pdfroff
+to identify the following temporary and intermediate files.
+.
+.TP
+.IR pdf $$ .tmp
+A scratch pad file,
+used to capture reference data emitted by
+.BR groff ,
+during the
+.I reference dictionary
+compilation phase.
+.
+.TP
+.IR pdf $$ .ref
+The
+.IR "reference dictionary" ,
+as compiled in the last but one pass of the
+.I reference dictionary
+compilation phase;
+(at the start of the first pass,
+this file is created empty;
+in successive passes,
+it contains the
+.I reference dictionary
+entries,
+as collected in the preceding pass).
+.
+.IP
+If the
+.BR \%\-\-reference\-dictionary =\c
+.I name
+option is specified,
+this intermediate file becomes permanent,
+and is named
+.IR name ,
+rather than
+.IR pdf $$ .ref .
+.
+.TP
+.IR pdf $$ .cmp
+Used to collect
+.I reference dictionary
+entries during the active pass of the
+.I reference dictionary
+compilation phase.
+.
+At the end of any pass,
+when the content of
+.IR pdf $$ .cmp
+compares as identical to
+.IR pdf $$ .ref ,
+(or the corresponding file named by the
+.BR \%\-\-reference\-dictionary =\c
+.I name
+option),
+then
+.I reference dictionary
+compilation is terminated,
+and the
+.I document reference map
+is appended to this intermediate file,
+for inclusion in the final formatting passes.
+.
+.TP
+.IR pdf $$ .tc
+An intermediate
+.I PostScript
+file,
+in which \[lq]Table of Contents\[rq] entries are collected,
+to facilitate relocation before the body text,
+on ultimate output to the
+.I GhostScript
+postprocessor.
+.
+.TP
+.IR pdf $$ .ps
+An intermediate
+.I PostScript
+file,
+in which the body text is collected prior to ultimate output to the
+.I GhostScript
+postprocessor,
+in the proper sequence,
+.I after
+.IR pdf $$ .tc .
+.
+.
+.\" ====================================================================
+.SH AUTHORS
+.\" ====================================================================
+.B pdfroff
+was written by
+.MT keith.d.marshall@\:ntlworld.com
+Keith Marshall
+.ME .
+.
+.
+.\" ====================================================================
+.SH SEE ALSO
+.\" ====================================================================
+.
+See
+.BR groff (1)
+for the definitive reference to document formatting with
+.BR groff .
+.
+Since
+.B pdfroff
+provides a superset of all
+.B groff
+capabilities,
+.BR groff (1)
+may also be considered to be the definitive reference to all
+.I standard
+capabilities of
+.BR pdfroff ,
+with this document providing the reference to
+.BR pdfroff 's
+extended features.
+.
+.
+.P
+While
+.B pdfroff
+imposes neither any restriction on, nor any requirement for,
+the use of any specific
+.B groff
+macro package, a number of supplied macro packages,
+and in particular those associated with the package
+.IR pdfmark.tmac ,
+are best suited for use with
+.B pdfroff
+as the preferred formatter.
+.
+Detailed documentation on the use of these packages may be found,
+in PDF format, in the reference guide
+.BR "\*(lqPortable Document Format Publishing with GNU Troff\*(rq" ,
+included in the installed documentation set as
+.IR /usr/\:share/\:doc/\:groff\-1.22.4/\:pdf/pdfmark.pdf .
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[pdfroff_C]
+.
+.
+.\" ====================================================================
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/perl.1 b/upstream/mageia-cauldron/man1/perl.1
new file mode 100644
index 00000000..e1e77fde
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl.1
@@ -0,0 +1,496 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL 1"
+.TH PERL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl \- The Perl 5 language interpreter
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBperl\fR	[\ \fB\-sTtuUWX\fR\ ]
+	[\ \fB\-hv\fR\ ]\ [\ \fB\-V\fR[:\fIconfigvar\fR]\ ]
+	[\ \fB\-cw\fR\ ]\ [\ \fB\-d\fR[\fBt\fR][:\fIdebugger\fR]\ ]\ [\ \fB\-D\fR[\fInumber/list\fR]\ ]
+	[\ \fB\-pna\fR\ ]\ [\ \fB\-F\fR\fIpattern\fR\ ]\ [\ \fB\-l\fR[\fIoctal\fR]\ ]\ [\ \fB\-0\fR[\fIoctal/hexadecimal\fR]\ ]
+	[\ \fB\-I\fR\fIdir\fR\ ]\ [\ \fB\-m\fR[\fB\-\fR]\fImodule\fR\ ]\ [\ \fB\-M\fR[\fB\-\fR]\fI'module...'\fR\ ]\ [\ \fB\-f\fR\ ]
+	[\ \fB\-C\ [\fR\f(BInumber/list\fR\fB]\ \fR]
+	[\ \fB\-S\fR\ ]
+	[\ \fB\-x\fR[\fIdir\fR]\ ]
+	[\ \fB\-i\fR[\fIextension\fR]\ ]
+	[\ [\fB\-e\fR|\fB\-E\fR]\ \fI'command'\fR\ ]\ [\ \fB\-\-\fR\ ]\ [\ \fIprogramfile\fR\ ]\ [\ \fIargument\fR\ ]...
+.PP
+For more information on these options, you can run \f(CW\*(C`perldoc perlrun\*(C'\fR.
+.SH "GETTING HELP"
+.IX Header "GETTING HELP"
+The \fIperldoc\fR program gives you access to all the documentation that comes
+with Perl.  You can get more documentation, tutorials and community support
+online at <https://www.perl.org/>.
+.PP
+If you're new to Perl, you should start by running \f(CW\*(C`perldoc perlintro\*(C'\fR,
+which is a general intro for beginners and provides some background to help
+you navigate the rest of Perl's extensive documentation.  Run \f(CW\*(C`perldoc
+perldoc\*(C'\fR to learn more things you can do with \fIperldoc\fR.
+.PP
+For ease of access, the Perl manual has been split up into several sections.
+.SS Overview
+.IX Subsection "Overview"
+.Vb 4
+\&    perl                Perl overview (this section)
+\&    perlintro           Perl introduction for beginners
+\&    perlrun             Perl execution and options
+\&    perltoc             Perl documentation table of contents
+.Ve
+.SS Tutorials
+.IX Subsection "Tutorials"
+.Vb 3
+\&    perlreftut          Perl references short introduction
+\&    perldsc             Perl data structures intro
+\&    perllol             Perl data structures: arrays of arrays
+\&
+\&    perlrequick         Perl regular expressions quick start
+\&    perlretut           Perl regular expressions tutorial
+\&
+\&    perlootut           Perl OO tutorial for beginners
+\&
+\&    perlperf            Perl Performance and Optimization Techniques
+\&
+\&    perlstyle           Perl style guide
+\&
+\&    perlcheat           Perl cheat sheet
+\&    perltrap            Perl traps for the unwary
+\&    perldebtut          Perl debugging tutorial
+\&
+\&    perlfaq             Perl frequently asked questions
+\&      perlfaq1          General Questions About Perl
+\&      perlfaq2          Obtaining and Learning about Perl
+\&      perlfaq3          Programming Tools
+\&      perlfaq4          Data Manipulation
+\&      perlfaq5          Files and Formats
+\&      perlfaq6          Regexes
+\&      perlfaq7          Perl Language Issues
+\&      perlfaq8          System Interaction
+\&      perlfaq9          Networking
+.Ve
+.SS "Reference Manual"
+.IX Subsection "Reference Manual"
+.Vb 10
+\&    perlsyn             Perl syntax
+\&    perldata            Perl data structures
+\&    perlop              Perl operators and precedence
+\&    perlsub             Perl subroutines
+\&    perlfunc            Perl built\-in functions
+\&      perlopentut       Perl open() tutorial
+\&      perlpacktut       Perl pack() and unpack() tutorial
+\&    perlpod             Perl plain old documentation
+\&    perlpodspec         Perl plain old documentation format specification
+\&    perldocstyle        Perl style guide for core docs
+\&    perlpodstyle        Perl POD style guide
+\&    perldiag            Perl diagnostic messages
+\&    perldeprecation     Perl deprecations
+\&    perllexwarn         Perl warnings and their control
+\&    perldebug           Perl debugging
+\&    perlvar             Perl predefined variables
+\&    perlre              Perl regular expressions, the rest of the story
+\&    perlrebackslash     Perl regular expression backslash sequences
+\&    perlrecharclass     Perl regular expression character classes
+\&    perlreref           Perl regular expressions quick reference
+\&    perlref             Perl references, the rest of the story
+\&    perlform            Perl formats
+\&    perlobj             Perl objects
+\&    perltie             Perl objects hidden behind simple variables
+\&    perlclass           Perl class syntax
+\&      perldbmfilter     Perl DBM filters
+\&
+\&    perlipc             Perl interprocess communication
+\&    perlfork            Perl fork() information
+\&    perlnumber          Perl number semantics
+\&
+\&    perlthrtut          Perl threads tutorial
+\&
+\&    perlport            Perl portability guide
+\&    perllocale          Perl locale support
+\&    perluniintro        Perl Unicode introduction
+\&    perlunicode         Perl Unicode support
+\&    perlunicook         Perl Unicode cookbook
+\&    perlunifaq          Perl Unicode FAQ
+\&    perluniprops        Index of Unicode properties in Perl
+\&    perlunitut          Perl Unicode tutorial
+\&    perlebcdic          Considerations for running Perl on EBCDIC platforms
+\&
+\&    perlsec             Perl security
+\&    perlsecpolicy       Perl security report handling policy
+\&
+\&    perlmod             Perl modules: how they work
+\&    perlmodlib          Perl modules: how to write and use
+\&    perlmodstyle        Perl modules: how to write modules with style
+\&    perlmodinstall      Perl modules: how to install from CPAN
+\&    perlnewmod          Perl modules: preparing a new module for distribution
+\&    perlpragma          Perl modules: writing a user pragma
+\&
+\&    perlutil            utilities packaged with the Perl distribution
+\&
+\&    perlfilter          Perl source filters
+\&
+\&    perldtrace          Perl\*(Aqs support for DTrace
+\&
+\&    perlglossary        Perl Glossary
+.Ve
+.SS "Internals and C Language Interface"
+.IX Subsection "Internals and C Language Interface"
+.Vb 12
+\&    perlembed           Perl ways to embed perl in your C or C++ application
+\&    perldebguts         Perl debugging guts and tips
+\&    perlxstut           Perl XS tutorial
+\&    perlxs              Perl XS application programming interface
+\&    perlxstypemap       Perl XS C/Perl type conversion tools
+\&    perlclib            Internal replacements for standard C library functions
+\&    perlguts            Perl internal functions for those doing extensions
+\&    perlcall            Perl calling conventions from C
+\&    perlmroapi          Perl method resolution plugin interface
+\&    perlreapi           Perl regular expression plugin interface
+\&    perlreguts          Perl regular expression engine internals
+\&    perlclassguts       Internals of class syntax
+\&
+\&    perlapi             Perl API listing (autogenerated)
+\&    perlintern          Perl internal functions (autogenerated)
+\&    perliol             C API for Perl\*(Aqs implementation of IO in Layers
+\&    perlapio            Perl internal IO abstraction interface
+\&
+\&    perlhack            Perl hackers guide
+\&    perlsource          Guide to the Perl source tree
+\&    perlinterp          Overview of the Perl interpreter source and how it works
+\&    perlhacktut         Walk through the creation of a simple C code patch
+\&    perlhacktips        Tips for Perl core C code hacking
+\&    perlpolicy          Perl development policies
+\&    perlgov             Perl Rules of Governance
+\&    perlgit             Using git with the Perl repository
+.Ve
+.SS History
+.IX Subsection "History"
+.Vb 10
+\&    perlhist            Perl history records
+\&    perldelta           Perl changes since previous version
+\&    perl5381delta       Perl changes in version 5.38.1
+\&    perl5380delta       Perl changes in version 5.38.0
+\&    perl5363delta       Perl changes in version 5.36.3
+\&    perl5362delta       Perl changes in version 5.36.2
+\&    perl5361delta       Perl changes in version 5.36.1
+\&    perl5360delta       Perl changes in version 5.36.0
+\&    perl5343delta       Perl changes in version 5.34.3
+\&    perl5342delta       Perl changes in version 5.34.2
+\&    perl5341delta       Perl changes in version 5.34.1
+\&    perl5340delta       Perl changes in version 5.34.0
+\&    perl5321delta       Perl changes in version 5.32.1
+\&    perl5320delta       Perl changes in version 5.32.0
+\&    perl5303delta       Perl changes in version 5.30.3
+\&    perl5302delta       Perl changes in version 5.30.2
+\&    perl5301delta       Perl changes in version 5.30.1
+\&    perl5300delta       Perl changes in version 5.30.0
+\&    perl5283delta       Perl changes in version 5.28.3
+\&    perl5282delta       Perl changes in version 5.28.2
+\&    perl5281delta       Perl changes in version 5.28.1
+\&    perl5280delta       Perl changes in version 5.28.0
+\&    perl5263delta       Perl changes in version 5.26.3
+\&    perl5262delta       Perl changes in version 5.26.2
+\&    perl5261delta       Perl changes in version 5.26.1
+\&    perl5260delta       Perl changes in version 5.26.0
+\&    perl5244delta       Perl changes in version 5.24.4
+\&    perl5243delta       Perl changes in version 5.24.3
+\&    perl5242delta       Perl changes in version 5.24.2
+\&    perl5241delta       Perl changes in version 5.24.1
+\&    perl5240delta       Perl changes in version 5.24.0
+\&    perl5224delta       Perl changes in version 5.22.4
+\&    perl5223delta       Perl changes in version 5.22.3
+\&    perl5222delta       Perl changes in version 5.22.2
+\&    perl5221delta       Perl changes in version 5.22.1
+\&    perl5220delta       Perl changes in version 5.22.0
+\&    perl5203delta       Perl changes in version 5.20.3
+\&    perl5202delta       Perl changes in version 5.20.2
+\&    perl5201delta       Perl changes in version 5.20.1
+\&    perl5200delta       Perl changes in version 5.20.0
+\&    perl5184delta       Perl changes in version 5.18.4
+\&    perl5182delta       Perl changes in version 5.18.2
+\&    perl5181delta       Perl changes in version 5.18.1
+\&    perl5180delta       Perl changes in version 5.18.0
+\&    perl5163delta       Perl changes in version 5.16.3
+\&    perl5162delta       Perl changes in version 5.16.2
+\&    perl5161delta       Perl changes in version 5.16.1
+\&    perl5160delta       Perl changes in version 5.16.0
+\&    perl5144delta       Perl changes in version 5.14.4
+\&    perl5143delta       Perl changes in version 5.14.3
+\&    perl5142delta       Perl changes in version 5.14.2
+\&    perl5141delta       Perl changes in version 5.14.1
+\&    perl5140delta       Perl changes in version 5.14.0
+\&    perl5125delta       Perl changes in version 5.12.5
+\&    perl5124delta       Perl changes in version 5.12.4
+\&    perl5123delta       Perl changes in version 5.12.3
+\&    perl5122delta       Perl changes in version 5.12.2
+\&    perl5121delta       Perl changes in version 5.12.1
+\&    perl5120delta       Perl changes in version 5.12.0
+\&    perl5101delta       Perl changes in version 5.10.1
+\&    perl5100delta       Perl changes in version 5.10.0
+\&    perl589delta        Perl changes in version 5.8.9
+\&    perl588delta        Perl changes in version 5.8.8
+\&    perl587delta        Perl changes in version 5.8.7
+\&    perl586delta        Perl changes in version 5.8.6
+\&    perl585delta        Perl changes in version 5.8.5
+\&    perl584delta        Perl changes in version 5.8.4
+\&    perl583delta        Perl changes in version 5.8.3
+\&    perl582delta        Perl changes in version 5.8.2
+\&    perl581delta        Perl changes in version 5.8.1
+\&    perl58delta         Perl changes in version 5.8.0
+\&    perl561delta        Perl changes in version 5.6.1
+\&    perl56delta         Perl changes in version 5.6
+\&    perl5005delta       Perl changes in version 5.005
+\&    perl5004delta       Perl changes in version 5.004
+.Ve
+.SS Miscellaneous
+.IX Subsection "Miscellaneous"
+.Vb 2
+\&    perlbook            Perl book information
+\&    perlcommunity       Perl community information
+\&
+\&    perldoc             Look up Perl documentation in Pod format
+\&
+\&    perlexperiment      A listing of experimental features in Perl
+\&
+\&    perlartistic        Perl Artistic License
+\&    perlgpl             GNU General Public License
+.Ve
+.SS Language-Specific
+.IX Subsection "Language-Specific"
+.Vb 4
+\&    perlcn              Perl for Simplified Chinese (in UTF\-8)
+\&    perljp              Perl for Japanese (in EUC\-JP)
+\&    perlko              Perl for Korean (in EUC\-KR)
+\&    perltw              Perl for Traditional Chinese (in Big5)
+.Ve
+.SS Platform-Specific
+.IX Subsection "Platform-Specific"
+.Vb 10
+\&    perlaix             Perl notes for AIX
+\&    perlamiga           Perl notes for AmigaOS
+\&    perlandroid         Perl notes for Android
+\&    perlbs2000          Perl notes for POSIX\-BC BS2000
+\&    perlcygwin          Perl notes for Cygwin
+\&    perlfreebsd         Perl notes for FreeBSD
+\&    perlhaiku           Perl notes for Haiku
+\&    perlhpux            Perl notes for HP\-UX
+\&    perlhurd            Perl notes for Hurd
+\&    perlirix            Perl notes for Irix
+\&    perllinux           Perl notes for Linux
+\&    perlmacosx          Perl notes for Mac OS X
+\&    perlopenbsd         Perl notes for OpenBSD
+\&    perlos2             Perl notes for OS/2
+\&    perlos390           Perl notes for OS/390
+\&    perlos400           Perl notes for OS/400
+\&    perlplan9           Perl notes for Plan 9
+\&    perlqnx             Perl notes for QNX
+\&    perlriscos          Perl notes for RISC OS
+\&    perlsolaris         Perl notes for Solaris
+\&    perlsynology        Perl notes for Synology
+\&    perltru64           Perl notes for Tru64
+\&    perlvms             Perl notes for VMS
+\&    perlvos             Perl notes for Stratus VOS
+\&    perlwin32           Perl notes for Windows
+.Ve
+.SS "Stubs for Deleted Documents"
+.IX Subsection "Stubs for Deleted Documents"
+.Vb 6
+\&    perlboot            
+\&    perlbot             
+\&    perlrepository
+\&    perltodo
+\&    perltooc            
+\&    perltoot
+.Ve
+.PP
+On a Unix-like system, these documentation files will usually also be
+available as manpages for use with the \fIman\fR program.
+.PP
+Some documentation is not available as man pages, so if a
+cross-reference is not found by man, try it with perldoc.  Perldoc can
+also take you directly to documentation for functions (with the \fB\-f\fR
+switch). See \f(CW\*(C`perldoc\ \-\-help\*(C'\fR (or \f(CW\*(C`perldoc\ perldoc\*(C'\fR or
+\&\f(CW\*(C`man\ perldoc\*(C'\fR) for other helpful options perldoc has to offer.
+.PP
+In general, if something strange has gone wrong with your program and you're
+not sure where you should look for help, try making your code comply with
+\&\fBuse strict\fR and \fBuse warnings\fR.  These will often point out exactly
+where the trouble is.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl officially stands for Practical Extraction and Report Language,
+except when it doesn't.
+.PP
+Perl was originally a language optimized for scanning arbitrary
+text files, extracting information from those text files, and printing
+reports based on that information.  It quickly became a good language
+for many system management tasks. Over the years, Perl has grown into
+a general-purpose programming language. It's widely used for everything
+from quick "one-liners" to full-scale application development.
+.PP
+The language is intended to be practical (easy to use, efficient,
+complete) rather than beautiful (tiny, elegant, minimal).  It combines
+(in the author's opinion, anyway) some of the best features of \fBsed\fR,
+\&\fBawk\fR, and \fBsh\fR, making it familiar and easy to use for Unix users to
+whip up quick solutions to annoying problems.  Its general-purpose
+programming facilities support procedural, functional, and
+object-oriented programming paradigms, making Perl a comfortable
+language for the long haul on major projects, whatever your bent.
+.PP
+Perl's roots in text processing haven't been forgotten over the years.
+It still boasts some of the most powerful regular expressions to be
+found anywhere, and its support for Unicode text is world-class.  It
+handles all kinds of structured text, too, through an extensive
+collection of extensions.  Those libraries, collected in the CPAN,
+provide ready-made solutions to an astounding array of problems.  When
+they haven't set the standard themselves, they steal from the best
+\&\-\- just like Perl itself.
+.SH AVAILABILITY
+.IX Header "AVAILABILITY"
+Perl is available for most operating systems, including virtually
+all Unix-like platforms.  See "Supported Platforms" in perlport
+for a listing.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+See "ENVIRONMENT" in perlrun.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall <larry@wall.org>, with the help of oodles of other folks.
+.PP
+If your Perl success stories and testimonials may be of help to others 
+who wish to advocate the use of Perl in their applications, 
+or if you wish to simply express your gratitude to Larry and the 
+Perl developers, please write to perl\-thanks@perl.org .
+.SH FILES
+.IX Header "FILES"
+.Vb 1
+\& "@INC"                 locations of perl libraries
+.Ve
+.PP
+"@INC" above is a reference to the built-in variable of the same name;
+see perlvar for more information.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.Vb 4
+\& https://www.perl.org/       the Perl homepage
+\& https://www.perl.com/       Perl articles
+\& https://www.cpan.org/       the Comprehensive Perl Archive
+\& https://www.pm.org/         the Perl Mongers
+.Ve
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+Using the \f(CW\*(C`use strict\*(C'\fR pragma ensures that all variables are properly
+declared and prevents other misuses of legacy Perl features.
+These are enabled by default within the scope of
+\&\f(CW\*(C`use v5.12\*(C'\fR (or higher).
+.PP
+The \f(CW\*(C`use warnings\*(C'\fR pragma produces some lovely diagnostics.
+It is enabled by default when you say \f(CW\*(C`use v5.35\*(C'\fR (or higher).
+One can also use the \fB\-w\fR flag, but its use is normally discouraged,
+because it gets applied to all executed Perl code, including that not under
+your control.
+.PP
+See perldiag for explanations of all Perl's diagnostics.  The \f(CW\*(C`use
+diagnostics\*(C'\fR pragma automatically turns Perl's normally terse warnings
+and errors into these longer forms.
+.PP
+Compilation errors will tell you the line number of the error, with an
+indication of the next token or token type that was to be examined.
+(In a script passed to Perl via \fB\-e\fR switches, each
+\&\fB\-e\fR is counted as one line.)
+.PP
+Setuid scripts have additional constraints that can produce error
+messages such as "Insecure dependency".  See perlsec.
+.PP
+Did we mention that you should definitely consider using the \fBuse warnings\fR
+pragma?
+.SH BUGS
+.IX Header "BUGS"
+The behavior implied by the \fBuse warnings\fR pragma is not mandatory.
+.PP
+Perl is at the mercy of your machine's definitions of various
+operations such as type casting, \fBatof()\fR, and floating-point
+output with \fBsprintf()\fR.
+.PP
+If your stdio requires a seek or eof between reads and writes on a
+particular stream, so does Perl.  (This doesn't apply to \fBsysread()\fR
+and \fBsyswrite()\fR.)
+.PP
+While none of the built-in data types have any arbitrary size limits
+(apart from memory size), there are still a few arbitrary limits:  a
+given variable name may not be longer than 251 characters.  Line numbers
+displayed by diagnostics are internally stored as short integers,
+so they are limited to a maximum of 65535 (higher numbers usually being
+affected by wraparound).
+.PP
+You may submit your bug reports (be sure to include full configuration
+information as output by the myconfig program in the perl source
+tree, or by \f(CW\*(C`perl \-V\*(C'\fR) to <https://github.com/Perl/perl5/issues>.
+.PP
+Perl actually stands for Pathologically Eclectic Rubbish Lister, but
+don't tell anyone I said that.
+.SH NOTES
+.IX Header "NOTES"
+The Perl motto is "There's more than one way to do it."  Divining
+how many more is left as an exercise to the reader.
+.PP
+The three principal virtues of a programmer are Laziness,
+Impatience, and Hubris.  See the Camel Book for why.
diff --git a/upstream/mageia-cauldron/man1/perl5004delta.1 b/upstream/mageia-cauldron/man1/perl5004delta.1
new file mode 100644
index 00000000..af9d39eb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5004delta.1
@@ -0,0 +1,1567 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5004DELTA 1"
+.TH PERL5004DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5004delta \- what's new for perl5.004
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.003 release (as
+documented in \fIProgramming Perl\fR, second edition\-\-the Camel Book) and
+this one.
+.SH "Supported Environments"
+.IX Header "Supported Environments"
+Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2,
+QNX, AmigaOS, and Windows NT.  Perl runs on Windows 95 as well, but it
+cannot be built there, for lack of a reasonable command interpreter.
+.SH "Core Changes"
+.IX Header "Core Changes"
+Most importantly, many bugs were fixed, including several security
+problems.  See the \fIChanges\fR file in the distribution for details.
+.ie n .SS "List assignment to %ENV works"
+.el .SS "List assignment to \f(CW%ENV\fP works"
+.IX Subsection "List assignment to %ENV works"
+\&\f(CW\*(C`%ENV = ()\*(C'\fR and \f(CW\*(C`%ENV = @list\*(C'\fR now work as expected (except on VMS
+where it generates a fatal error).
+.ie n .SS "Change to ""Can't locate Foo.pm in @INC"" error"
+.el .SS "Change to ""Can't locate Foo.pm in \f(CW@INC\fP"" error"
+.IX Subsection "Change to ""Can't locate Foo.pm in @INC"" error"
+The error "Can't locate Foo.pm in \f(CW@INC\fR" now lists the contents of \f(CW@INC\fR
+for easier debugging.
+.SS "Compilation option: Binary compatibility with 5.003"
+.IX Subsection "Compilation option: Binary compatibility with 5.003"
+There is a new Configure question that asks if you want to maintain
+binary compatibility with Perl 5.003.  If you choose binary
+compatibility, you do not have to recompile your extensions, but you
+might have symbol conflicts if you embed Perl in another application,
+just as in the 5.003 release.  By default, binary compatibility
+is preserved at the expense of symbol table pollution.
+.ie n .SS "$PERL5OPT environment variable"
+.el .SS "\f(CW$PERL5OPT\fP environment variable"
+.IX Subsection "$PERL5OPT environment variable"
+You may now put Perl options in the \f(CW$PERL5OPT\fR environment variable.
+Unless Perl is running with taint checks, it will interpret this
+variable as if its contents had appeared on a "#!perl" line at the
+beginning of your script, except that hyphens are optional.  PERL5OPT
+may only be used to set the following switches: \fB\-[DIMUdmw]\fR.
+.SS "Limitations on \fB\-M\fP, \fB\-m\fP, and \fB\-T\fP options"
+.IX Subsection "Limitations on -M, -m, and -T options"
+The \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-m\*(C'\fR options are no longer allowed on the \f(CW\*(C`#!\*(C'\fR line of
+a script.  If a script needs a module, it should invoke it with the
+\&\f(CW\*(C`use\*(C'\fR pragma.
+.PP
+The \fB\-T\fR option is also forbidden on the \f(CW\*(C`#!\*(C'\fR line of a script,
+unless it was present on the Perl command line.  Due to the way \f(CW\*(C`#!\*(C'\fR
+works, this usually means that \fB\-T\fR must be in the first argument.
+Thus:
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-T \-w
+.Ve
+.PP
+will probably work for an executable script invoked as \f(CW\*(C`scriptname\*(C'\fR,
+while:
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-w \-T
+.Ve
+.PP
+will probably fail under the same conditions.  (Non-Unix systems will
+probably not follow this rule.)  But \f(CW\*(C`perl scriptname\*(C'\fR is guaranteed
+to fail, since then there is no chance of \fB\-T\fR being found on the
+command line before it is found on the \f(CW\*(C`#!\*(C'\fR line.
+.SS "More precise warnings"
+.IX Subsection "More precise warnings"
+If you removed the \fB\-w\fR option from your Perl 5.003 scripts because it
+made Perl too verbose, we recommend that you try putting it back when
+you upgrade to Perl 5.004.  Each new perl version tends to remove some
+undesirable warnings, while adding new warnings that may catch bugs in
+your scripts.
+.ie n .SS "Deprecated: Inherited ""AUTOLOAD"" for non-methods"
+.el .SS "Deprecated: Inherited \f(CWAUTOLOAD\fP for non-methods"
+.IX Subsection "Deprecated: Inherited AUTOLOAD for non-methods"
+Before Perl 5.004, \f(CW\*(C`AUTOLOAD\*(C'\fR functions were looked up as methods
+(using the \f(CW@ISA\fR hierarchy), even when the function to be autoloaded
+was called as a plain function (e.g. \f(CWFoo::bar()\fR), not a method
+(e.g. \f(CW\*(C`Foo\->bar()\*(C'\fR or \f(CW\*(C`$obj\->bar()\*(C'\fR).
+.PP
+Perl 5.005 will use method lookup only for methods' \f(CW\*(C`AUTOLOAD\*(C'\fRs.
+However, there is a significant base of existing code that may be using
+the old behavior.  So, as an interim step, Perl 5.004 issues an optional
+warning when a non-method uses an inherited \f(CW\*(C`AUTOLOAD\*(C'\fR.
+.PP
+The simple rule is:  Inheritance will not work when autoloading
+non-methods.  The simple fix for old code is:  In any module that used to
+depend on inheriting \f(CW\*(C`AUTOLOAD\*(C'\fR for non-methods from a base class named
+\&\f(CW\*(C`BaseClass\*(C'\fR, execute \f(CW\*(C`*AUTOLOAD = \e&BaseClass::AUTOLOAD\*(C'\fR during startup.
+.ie n .SS "Previously deprecated %OVERLOAD is no longer usable"
+.el .SS "Previously deprecated \f(CW%OVERLOAD\fP is no longer usable"
+.IX Subsection "Previously deprecated %OVERLOAD is no longer usable"
+Using \f(CW%OVERLOAD\fR to define overloading was deprecated in 5.003.
+Overloading is now defined using the overload pragma. \f(CW%OVERLOAD\fR is
+still used internally but should not be used by Perl scripts. See
+overload for more details.
+.SS "Subroutine arguments created only when they're modified"
+.IX Subsection "Subroutine arguments created only when they're modified"
+In Perl 5.004, nonexistent array and hash elements used as subroutine
+parameters are brought into existence only if they are actually
+assigned to (via \f(CW@_\fR).
+.PP
+Earlier versions of Perl vary in their handling of such arguments.
+Perl versions 5.002 and 5.003 always brought them into existence.
+Perl versions 5.000 and 5.001 brought them into existence only if
+they were not the first argument (which was almost certainly a bug).
+Earlier versions of Perl never brought them into existence.
+.PP
+For example, given this code:
+.PP
+.Vb 5
+\&     undef @a; undef %a;
+\&     sub show { print $_[0] };
+\&     sub change { $_[0]++ };
+\&     show($a[2]);
+\&     change($a{b});
+.Ve
+.PP
+After this code executes in Perl 5.004, \f(CW$a\fR{b} exists but \f(CW$a\fR[2] does
+not.  In Perl 5.002 and 5.003, both \f(CW$a\fR{b} and \f(CW$a\fR[2] would have existed
+(but \f(CW$a\fR[2]'s value would have been undefined).
+.ie n .SS "Group vector changeable with $)"
+.el .SS "Group vector changeable with \f(CW$)\fP"
+.IX Subsection "Group vector changeable with $)"
+The \f(CW$)\fR special variable has always (well, in Perl 5, at least)
+reflected not only the current effective group, but also the group list
+as returned by the \f(CWgetgroups()\fR C function (if there is one).
+However, until this release, there has not been a way to call the
+\&\f(CWsetgroups()\fR C function from Perl.
+.PP
+In Perl 5.004, assigning to \f(CW$)\fR is exactly symmetrical with examining
+it: The first number in its string value is used as the effective gid;
+if there are any numbers after the first one, they are passed to the
+\&\f(CWsetgroups()\fR C function (if there is one).
+.SS "Fixed parsing of $$<digit>, &$<digit>, etc."
+.IX Subsection "Fixed parsing of $$<digit>, &$<digit>, etc."
+Perl versions before 5.004 misinterpreted any type marker followed by
+"$" and a digit.  For example, "$$0" was incorrectly taken to mean
+"${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
+.PP
+However, the developers of Perl 5.004 could not fix this bug completely,
+because at least two widely-used modules depend on the old meaning of
+"$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
+old (broken) way inside strings; but it generates this message as a
+warning.  And in Perl 5.005, this special treatment will cease.
+.SS "Fixed localization of $<digit>, $&, etc."
+.IX Subsection "Fixed localization of $<digit>, $&, etc."
+Perl versions before 5.004 did not always properly localize the
+regex-related special variables.  Perl 5.004 does localize them, as
+the documentation has always said it should.  This may result in \f(CW$1\fR,
+\&\f(CW$2\fR, etc. no longer being set where existing programs use them.
+.SS "No resetting of $. on implicit close"
+.IX Subsection "No resetting of $. on implicit close"
+The documentation for Perl 5.0 has always stated that \f(CW$.\fR is \fInot\fR
+reset when an already-open file handle is reopened with no intervening
+call to \f(CW\*(C`close\*(C'\fR.  Due to a bug, perl versions 5.000 through 5.003
+\&\fIdid\fR reset \f(CW$.\fR under that circumstance; Perl 5.004 does not.
+.ie n .SS """wantarray"" may return undef"
+.el .SS "\f(CWwantarray\fP may return undef"
+.IX Subsection "wantarray may return undef"
+The \f(CW\*(C`wantarray\*(C'\fR operator returns true if a subroutine is expected to
+return a list, and false otherwise.  In Perl 5.004, \f(CW\*(C`wantarray\*(C'\fR can
+also return the undefined value if a subroutine's return value will
+not be used at all, which allows subroutines to avoid a time-consuming
+calculation of a return value if it isn't going to be used.
+.ie n .SS """eval EXPR"" determines value of EXPR in scalar context"
+.el .SS "\f(CWeval EXPR\fP determines value of EXPR in scalar context"
+.IX Subsection "eval EXPR determines value of EXPR in scalar context"
+Perl (version 5) used to determine the value of EXPR inconsistently,
+sometimes incorrectly using the surrounding context for the determination.
+Now, the value of EXPR (before being parsed by eval) is always determined in
+a scalar context.  Once parsed, it is executed as before, by providing
+the context that the scope surrounding the eval provided.  This change
+makes the behavior Perl4 compatible, besides fixing bugs resulting from
+the inconsistent behavior.  This program:
+.PP
+.Vb 3
+\&    @a = qw(time now is time);
+\&    print eval @a;
+\&    print \*(Aq|\*(Aq, scalar eval @a;
+.Ve
+.PP
+used to print something like "timenowis881399109|4", but now (and in perl4)
+prints "4|4".
+.SS "Changes to tainting checks"
+.IX Subsection "Changes to tainting checks"
+A bug in previous versions may have failed to detect some insecure
+conditions when taint checks are turned on.  (Taint checks are used
+in setuid or setgid scripts, or when explicitly turned on with the
+\&\f(CW\*(C`\-T\*(C'\fR invocation option.)  Although it's unlikely, this may cause a
+previously-working script to now fail, which should be construed
+as a blessing since that indicates a potentially-serious security
+hole was just plugged.
+.PP
+The new restrictions when tainting include:
+.IP "No \fBglob()\fR or <*>" 4
+.IX Item "No glob() or <*>"
+These operators may spawn the C shell (csh), which cannot be made
+safe.  This restriction will be lifted in a future version of Perl
+when globbing is implemented without the use of an external program.
+.ie n .IP "No spawning if tainted $CDPATH, $ENV, $BASH_ENV" 4
+.el .IP "No spawning if tainted \f(CW$CDPATH\fR, \f(CW$ENV\fR, \f(CW$BASH_ENV\fR" 4
+.IX Item "No spawning if tainted $CDPATH, $ENV, $BASH_ENV"
+These environment variables may alter the behavior of spawned programs
+(especially shells) in ways that subvert security.  So now they are
+treated as dangerous, in the manner of \f(CW$IFS\fR and \f(CW$PATH\fR.
+.ie n .IP "No spawning if tainted $TERM doesn't look like a terminal name" 4
+.el .IP "No spawning if tainted \f(CW$TERM\fR doesn't look like a terminal name" 4
+.IX Item "No spawning if tainted $TERM doesn't look like a terminal name"
+Some termcap libraries do unsafe things with \f(CW$TERM\fR.  However, it would be
+unnecessarily harsh to treat all \f(CW$TERM\fR values as unsafe, since only shell
+metacharacters can cause trouble in \f(CW$TERM\fR.  So a tainted \f(CW$TERM\fR is
+considered to be safe if it contains only alphanumerics, underscores,
+dashes, and colons, and unsafe if it contains other characters (including
+whitespace).
+.SS "New Opcode module and revised Safe module"
+.IX Subsection "New Opcode module and revised Safe module"
+A new Opcode module supports the creation, manipulation and
+application of opcode masks.  The revised Safe module has a new API
+and is implemented using the new Opcode module.  Please read the new
+Opcode and Safe documentation.
+.SS "Embedding improvements"
+.IX Subsection "Embedding improvements"
+In older versions of Perl it was not possible to create more than one
+Perl interpreter instance inside a single process without leaking like a
+sieve and/or crashing.  The bugs that caused this behavior have all been
+fixed.  However, you still must take care when embedding Perl in a C
+program.  See the updated perlembed manpage for tips on how to manage
+your interpreters.
+.SS "Internal change: FileHandle class based on IO::* classes"
+.IX Subsection "Internal change: FileHandle class based on IO::* classes"
+File handles are now stored internally as type IO::Handle.  The
+FileHandle module is still supported for backwards compatibility, but
+it is now merely a front end to the IO::* modules, specifically
+IO::Handle, IO::Seekable, and IO::File.  We suggest, but do not
+require, that you use the IO::* modules in new code.
+.PP
+In harmony with this change, \f(CW*GLOB{FILEHANDLE}\fR is now just a
+backward-compatible synonym for \f(CW*GLOB{IO}\fR.
+.SS "Internal change: PerlIO abstraction interface"
+.IX Subsection "Internal change: PerlIO abstraction interface"
+It is now possible to build Perl with AT&T's sfio IO package
+instead of stdio.  See perlapio for more details, and
+the \fIINSTALL\fR file for how to use it.
+.SS "New and changed syntax"
+.IX Subsection "New and changed syntax"
+.ie n .IP $coderef\->(PARAMS) 4
+.el .IP \f(CW$coderef\fR\->(PARAMS) 4
+.IX Item "$coderef->(PARAMS)"
+A subroutine reference may now be suffixed with an arrow and a
+(possibly empty) parameter list.  This syntax denotes a call of the
+referenced subroutine, with the given parameters (if any).
+.Sp
+This new syntax follows the pattern of \f(CW\*(C`$hashref\->{FOO}\*(C'\fR and
+\&\f(CW\*(C`$aryref\->[$foo]\*(C'\fR: You may now write \f(CW&$subref($foo)\fR as
+\&\f(CW$subref\->($foo)\fR.  All these arrow terms may be chained;
+thus, \f(CW\*(C`&{$table\->{FOO}}($bar)\*(C'\fR may now be written
+\&\f(CW\*(C`$table\->{FOO}\->($bar)\*(C'\fR.
+.SS "New and changed builtin constants"
+.IX Subsection "New and changed builtin constants"
+.IP _\|_PACKAGE_\|_ 4
+.IX Item "__PACKAGE__"
+The current package name at compile time, or the undefined value if
+there is no current package (due to a \f(CW\*(C`package;\*(C'\fR directive).  Like
+\&\f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR does \fInot\fR interpolate
+into strings.
+.SS "New and changed builtin variables"
+.IX Subsection "New and changed builtin variables"
+.IP $^E 4
+.IX Item "$^E"
+Extended error message on some platforms.  (Also known as
+\&\f(CW$EXTENDED_OS_ERROR\fR if you \f(CW\*(C`use English\*(C'\fR).
+.IP $^H 4
+.IX Item "$^H"
+The current set of syntax checks enabled by \f(CW\*(C`use strict\*(C'\fR.  See the
+documentation of \f(CW\*(C`strict\*(C'\fR for more details.  Not actually new, but
+newly documented.
+Because it is intended for internal use by Perl core components,
+there is no \f(CW\*(C`use English\*(C'\fR long name for this variable.
+.IP $^M 4
+.IX Item "$^M"
+By default, running out of memory it is not trappable.  However, if
+compiled for this, Perl may use the contents of \f(CW$^M\fR as an emergency
+pool after \fBdie()\fRing with this message.  Suppose that your Perl were
+compiled with \-DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
+.Sp
+.Vb 1
+\&    $^M = \*(Aqa\*(Aq x (1<<16);
+.Ve
+.Sp
+would allocate a 64K buffer for use when in emergency.
+See the \fIINSTALL\fR file for information on how to enable this option.
+As a disincentive to casual use of this advanced feature,
+there is no \f(CW\*(C`use English\*(C'\fR long name for this variable.
+.SS "New and changed builtin functions"
+.IX Subsection "New and changed builtin functions"
+.IP "delete on slices" 4
+.IX Item "delete on slices"
+This now works.  (e.g. \f(CW\*(C`delete @ENV{\*(AqPATH\*(Aq, \*(AqMANPATH\*(Aq}\*(C'\fR)
+.IP flock 4
+.IX Item "flock"
+is now supported on more platforms, prefers fcntl to lockf when
+emulating, and always flushes before (un)locking.
+.IP "printf and sprintf" 4
+.IX Item "printf and sprintf"
+Perl now implements these functions itself; it doesn't use the C
+library function \fBsprintf()\fR any more, except for floating-point
+numbers, and even then only known flags are allowed.  As a result, it
+is now possible to know which conversions and flags will work, and
+what they will do.
+.Sp
+The new conversions in Perl's \fBsprintf()\fR are:
+.Sp
+.Vb 4
+\&   %i   a synonym for %d
+\&   %p   a pointer (the address of the Perl value, in hexadecimal)
+\&   %n   special: *stores* the number of characters output so far
+\&        into the next variable in the parameter list
+.Ve
+.Sp
+The new flags that go between the \f(CW\*(C`%\*(C'\fR and the conversion are:
+.Sp
+.Vb 3
+\&   #    prefix octal with "0", hex with "0x"
+\&   h    interpret integer as C type "short" or "unsigned short"
+\&   V    interpret integer as Perl\*(Aqs standard integer type
+.Ve
+.Sp
+Also, where a number would appear in the flags, an asterisk ("*") may
+be used instead, in which case Perl uses the next item in the
+parameter list as the given number (that is, as the field width or
+precision).  If a field width obtained through "*" is negative, it has
+the same effect as the '\-' flag: left-justification.
+.Sp
+See "sprintf" in perlfunc for a complete list of conversion and flags.
+.IP "keys as an lvalue" 4
+.IX Item "keys as an lvalue"
+As an lvalue, \f(CW\*(C`keys\*(C'\fR allows you to increase the number of hash buckets
+allocated for the given hash.  This can gain you a measure of efficiency if
+you know the hash is going to get big.  (This is similar to pre-extending
+an array by assigning a larger number to $#array.)  If you say
+.Sp
+.Vb 1
+\&    keys %hash = 200;
+.Ve
+.Sp
+then \f(CW%hash\fR will have at least 200 buckets allocated for it.  These
+buckets will be retained even if you do \f(CW\*(C`%hash = ()\*(C'\fR; use \f(CWundef
+%hash\fR if you want to free the storage while \f(CW%hash\fR is still in scope.
+You can't shrink the number of buckets allocated for the hash using
+\&\f(CW\*(C`keys\*(C'\fR in this way (but you needn't worry about doing this by accident,
+as trying has no effect).
+.IP "\fBmy()\fR in Control Structures" 4
+.IX Item "my() in Control Structures"
+You can now use \fBmy()\fR (with or without the parentheses) in the control
+expressions of control structures such as:
+.Sp
+.Vb 5
+\&    while (defined(my $line = <>)) {
+\&        $line = lc $line;
+\&    } continue {
+\&        print $line;
+\&    }
+\&
+\&    if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
+\&        user_agrees();
+\&    } elsif ($answer =~ /^n(o)?$/i) {
+\&        user_disagrees();
+\&    } else {
+\&        chomp $answer;
+\&        die "\`$answer\*(Aq is neither \`yes\*(Aq nor \`no\*(Aq";
+\&    }
+.Ve
+.Sp
+Also, you can declare a foreach loop control variable as lexical by
+preceding it with the word "my".  For example, in:
+.Sp
+.Vb 3
+\&    foreach my $i (1, 2, 3) {
+\&        some_function();
+\&    }
+.Ve
+.Sp
+\&\f(CW$i\fR is a lexical variable, and the scope of \f(CW$i\fR extends to the end of
+the loop, but not beyond it.
+.Sp
+Note that you still cannot use \fBmy()\fR on global punctuation variables
+such as \f(CW$_\fR and the like.
+.IP "\fBpack()\fR and \fBunpack()\fR" 4
+.IX Item "pack() and unpack()"
+A new format 'w' represents a BER compressed integer (as defined in
+ASN.1).  Its format is a sequence of one or more bytes, each of which
+provides seven bits of the total value, with the most significant
+first.  Bit eight of each byte is set, except for the last byte, in
+which bit eight is clear.
+.Sp
+If 'p' or 'P' are given undef as values, they now generate a NULL
+pointer.
+.Sp
+Both \fBpack()\fR and \fBunpack()\fR now fail when their templates contain invalid
+types.  (Invalid types used to be ignored.)
+.IP \fBsysseek()\fR 4
+.IX Item "sysseek()"
+The new \fBsysseek()\fR operator is a variant of \fBseek()\fR that sets and gets the
+file's system read/write position, using the \fBlseek\fR\|(2) system call.  It is
+the only reliable way to seek before using \fBsysread()\fR or \fBsyswrite()\fR.  Its
+return value is the new position, or the undefined value on failure.
+.IP "use VERSION" 4
+.IX Item "use VERSION"
+If the first argument to \f(CW\*(C`use\*(C'\fR is a number, it is treated as a version
+number instead of a module name.  If the version of the Perl interpreter
+is less than VERSION, then an error message is printed and Perl exits
+immediately.  Because \f(CW\*(C`use\*(C'\fR occurs at compile time, this check happens
+immediately during the compilation process, unlike \f(CW\*(C`require VERSION\*(C'\fR,
+which waits until runtime for the check.  This is often useful if you
+need to check the current Perl version before \f(CW\*(C`use\*(C'\fRing library modules
+which have changed in incompatible ways from older versions of Perl.
+(We try not to do this more than we have to.)
+.IP "use Module VERSION LIST" 4
+.IX Item "use Module VERSION LIST"
+If the VERSION argument is present between Module and LIST, then the
+\&\f(CW\*(C`use\*(C'\fR will call the VERSION method in class Module with the given
+version as an argument.  The default VERSION method, inherited from
+the UNIVERSAL class, croaks if the given version is larger than the
+value of the variable \f(CW$Module::VERSION\fR.  (Note that there is not a
+comma after VERSION!)
+.Sp
+This version-checking mechanism is similar to the one currently used
+in the Exporter module, but it is faster and can be used with modules
+that don't use the Exporter.  It is the recommended method for new
+code.
+.IP prototype(FUNCTION) 4
+.IX Item "prototype(FUNCTION)"
+Returns the prototype of a function as a string (or \f(CW\*(C`undef\*(C'\fR if the
+function has no prototype).  FUNCTION is a reference to or the name of the
+function whose prototype you want to retrieve.
+(Not actually new; just never documented before.)
+.IP srand 4
+.IX Item "srand"
+The default seed for \f(CW\*(C`srand\*(C'\fR, which used to be \f(CW\*(C`time\*(C'\fR, has been changed.
+Now it's a heady mix of difficult-to-predict system-dependent values,
+which should be sufficient for most everyday purposes.
+.Sp
+Previous to version 5.004, calling \f(CW\*(C`rand\*(C'\fR without first calling \f(CW\*(C`srand\*(C'\fR
+would yield the same sequence of random numbers on most or all machines.
+Now, when perl sees that you're calling \f(CW\*(C`rand\*(C'\fR and haven't yet called
+\&\f(CW\*(C`srand\*(C'\fR, it calls \f(CW\*(C`srand\*(C'\fR with the default seed. You should still call
+\&\f(CW\*(C`srand\*(C'\fR manually if your code might ever be run on a pre\-5.004 system,
+of course, or if you want a seed other than the default.
+.ie n .IP "$_ as Default" 4
+.el .IP "\f(CW$_\fR as Default" 4
+.IX Item "$_ as Default"
+Functions documented in the Camel to default to \f(CW$_\fR now in
+fact do, and all those that do are so documented in perlfunc.
+.ie n .IP """m//gc"" does not reset search position on failure" 4
+.el .IP "\f(CWm//gc\fR does not reset search position on failure" 4
+.IX Item "m//gc does not reset search position on failure"
+The \f(CW\*(C`m//g\*(C'\fR match iteration construct has always reset its target
+string's search position (which is visible through the \f(CW\*(C`pos\*(C'\fR operator)
+when a match fails; as a result, the next \f(CW\*(C`m//g\*(C'\fR match after a failure
+starts again at the beginning of the string.  With Perl 5.004, this
+reset may be disabled by adding the "c" (for "continue") modifier,
+i.e. \f(CW\*(C`m//gc\*(C'\fR.  This feature, in conjunction with the \f(CW\*(C`\eG\*(C'\fR zero-width
+assertion, makes it possible to chain matches together.  See perlop
+and perlre.
+.ie n .IP """m//x"" ignores whitespace before ?*+{}" 4
+.el .IP "\f(CWm//x\fR ignores whitespace before ?*+{}" 4
+.IX Item "m//x ignores whitespace before ?*+{}"
+The \f(CW\*(C`m//x\*(C'\fR construct has always been intended to ignore all unescaped
+whitespace.  However, before Perl 5.004, whitespace had the effect of
+escaping repeat modifiers like "*" or "?"; for example, \f(CW\*(C`/a *b/x\*(C'\fR was
+(mis)interpreted as \f(CW\*(C`/a\e*b/x\*(C'\fR.  This bug has been fixed in 5.004.
+.ie n .IP "nested ""sub{}"" closures work now" 4
+.el .IP "nested \f(CWsub{}\fR closures work now" 4
+.IX Item "nested sub{} closures work now"
+Prior to the 5.004 release, nested anonymous functions didn't work
+right.  They do now.
+.IP "formats work right on changing lexicals" 4
+.IX Item "formats work right on changing lexicals"
+Just like anonymous functions that contain lexical variables
+that change (like a lexical index variable for a \f(CW\*(C`foreach\*(C'\fR loop),
+formats now work properly.  For example, this silently failed
+before (printed only zeros), but is fine now:
+.Sp
+.Vb 8
+\&    my $i;
+\&    foreach $i ( 1 .. 10 ) {
+\&        write;
+\&    }
+\&    format =
+\&        my i is @#
+\&        $i
+\&    .
+.Ve
+.Sp
+However, it still fails (without a warning) if the foreach is within a
+subroutine:
+.Sp
+.Vb 11
+\&    my $i;
+\&    sub foo {
+\&      foreach $i ( 1 .. 10 ) {
+\&        write;
+\&      }
+\&    }
+\&    foo;
+\&    format =
+\&        my i is @#
+\&        $i
+\&    .
+.Ve
+.SS "New builtin methods"
+.IX Subsection "New builtin methods"
+The \f(CW\*(C`UNIVERSAL\*(C'\fR package automatically contains the following methods that
+are inherited by all other classes:
+.IP isa(CLASS) 4
+.IX Item "isa(CLASS)"
+\&\f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if its object is blessed into a subclass of \f(CW\*(C`CLASS\*(C'\fR
+.Sp
+\&\f(CW\*(C`isa\*(C'\fR is also exportable and can be called as a sub with two arguments. This
+allows the ability to check what a reference points to. Example:
+.Sp
+.Vb 1
+\&    use UNIVERSAL qw(isa);
+\&
+\&    if(isa($ref, \*(AqARRAY\*(Aq)) {
+\&       ...
+\&    }
+.Ve
+.IP can(METHOD) 4
+.IX Item "can(METHOD)"
+\&\f(CW\*(C`can\*(C'\fR checks to see if its object has a method called \f(CW\*(C`METHOD\*(C'\fR,
+if it does then a reference to the sub is returned; if it does not then
+\&\fIundef\fR is returned.
+.IP "VERSION( [NEED] )" 4
+.IX Item "VERSION( [NEED] )"
+\&\f(CW\*(C`VERSION\*(C'\fR returns the version number of the class (package).  If the
+NEED argument is given then it will check that the current version (as
+defined by the \f(CW$VERSION\fR variable in the given package) not less than
+NEED; it will die if this is not the case.  This method is normally
+called as a class method.  This method is called automatically by the
+\&\f(CW\*(C`VERSION\*(C'\fR form of \f(CW\*(C`use\*(C'\fR.
+.Sp
+.Vb 3
+\&    use A 1.2 qw(some imported subs);
+\&    # implies:
+\&    A\->VERSION(1.2);
+.Ve
+.PP
+\&\fBNOTE:\fR \f(CW\*(C`can\*(C'\fR directly uses Perl's internal code for method lookup, and
+\&\f(CW\*(C`isa\*(C'\fR uses a very similar method and caching strategy. This may cause
+strange effects if the Perl code dynamically changes \f(CW@ISA\fR in any package.
+.PP
+You may add other methods to the UNIVERSAL class via Perl or XS code.
+You do not need to \f(CW\*(C`use UNIVERSAL\*(C'\fR in order to make these methods
+available to your program.  This is necessary only if you wish to
+have \f(CW\*(C`isa\*(C'\fR available as a plain subroutine in the current package.
+.SS "TIEHANDLE now supported"
+.IX Subsection "TIEHANDLE now supported"
+See perltie for other kinds of \fBtie()\fRs.
+.IP "TIEHANDLE classname, LIST" 4
+.IX Item "TIEHANDLE classname, LIST"
+This is the constructor for the class.  That means it is expected to
+return an object of some sort. The reference can be used to
+hold some internal information.
+.Sp
+.Vb 5
+\&    sub TIEHANDLE {
+\&        print "<shout>\en";
+\&        my $i;
+\&        return bless \e$i, shift;
+\&    }
+.Ve
+.IP "PRINT this, LIST" 4
+.IX Item "PRINT this, LIST"
+This method will be triggered every time the tied handle is printed to.
+Beyond its self reference it also expects the list that was passed to
+the print function.
+.Sp
+.Vb 5
+\&    sub PRINT {
+\&        $r = shift;
+\&        $$r++;
+\&        return print join( $, => map {uc} @_), $\e;
+\&    }
+.Ve
+.IP "PRINTF this, LIST" 4
+.IX Item "PRINTF this, LIST"
+This method will be triggered every time the tied handle is printed to
+with the \f(CWprintf()\fR function.
+Beyond its self reference it also expects the format and list that was
+passed to the printf function.
+.Sp
+.Vb 5
+\&    sub PRINTF {
+\&        shift;
+\&          my $fmt = shift;
+\&        print sprintf($fmt, @_)."\en";
+\&    }
+.Ve
+.IP "READ this LIST" 4
+.IX Item "READ this LIST"
+This method will be called when the handle is read from via the \f(CW\*(C`read\*(C'\fR
+or \f(CW\*(C`sysread\*(C'\fR functions.
+.Sp
+.Vb 5
+\&    sub READ {
+\&        $r = shift;
+\&        my($buf,$len,$offset) = @_;
+\&        print "READ called, \e$buf=$buf, \e$len=$len, \e$offset=$offset";
+\&    }
+.Ve
+.IP "READLINE this" 4
+.IX Item "READLINE this"
+This method will be called when the handle is read from. The method
+should return undef when there is no more data.
+.Sp
+.Vb 4
+\&    sub READLINE {
+\&        $r = shift;
+\&        return "PRINT called $$r times\en"
+\&    }
+.Ve
+.IP "GETC this" 4
+.IX Item "GETC this"
+This method will be called when the \f(CW\*(C`getc\*(C'\fR function is called.
+.Sp
+.Vb 1
+\&    sub GETC { print "Don\*(Aqt GETC, Get Perl"; return "a"; }
+.Ve
+.IP "DESTROY this" 4
+.IX Item "DESTROY this"
+As with the other types of ties, this method will be called when the
+tied handle is about to be destroyed. This is useful for debugging and
+possibly for cleaning up.
+.Sp
+.Vb 3
+\&    sub DESTROY {
+\&        print "</shout>\en";
+\&    }
+.Ve
+.SS "Malloc enhancements"
+.IX Subsection "Malloc enhancements"
+If perl is compiled with the malloc included with the perl distribution
+(that is, if \f(CW\*(C`perl \-V:d_mymalloc\*(C'\fR is 'define') then you can print
+memory statistics at runtime by running Perl thusly:
+.PP
+.Vb 1
+\&  env PERL_DEBUG_MSTATS=2 perl your_script_here
+.Ve
+.PP
+The value of 2 means to print statistics after compilation and on
+exit; with a value of 1, the statistics are printed only on exit.
+(If you want the statistics at an arbitrary time, you'll need to
+install the optional module Devel::Peek.)
+.PP
+Three new compilation flags are recognized by malloc.c.  (They have no
+effect if perl is compiled with system \fBmalloc()\fR.)
+.IP \-DPERL_EMERGENCY_SBRK 4
+.IX Item "-DPERL_EMERGENCY_SBRK"
+If this macro is defined, running out of memory need not be a fatal
+error: a memory pool can allocated by assigning to the special
+variable \f(CW$^M\fR.  See "$^M".
+.IP \-DPACK_MALLOC 4
+.IX Item "-DPACK_MALLOC"
+Perl memory allocation is by bucket with sizes close to powers of two.
+Because of these malloc overhead may be big, especially for data of
+size exactly a power of two.  If \f(CW\*(C`PACK_MALLOC\*(C'\fR is defined, perl uses
+a slightly different algorithm for small allocations (up to 64 bytes
+long), which makes it possible to have overhead down to 1 byte for
+allocations which are powers of two (and appear quite often).
+.Sp
+Expected memory savings (with 8\-byte alignment in \f(CW\*(C`alignbytes\*(C'\fR) is
+about 20% for typical Perl usage.  Expected slowdown due to additional
+malloc overhead is in fractions of a percent (hard to measure, because
+of the effect of saved memory on speed).
+.IP \-DTWO_POT_OPTIMIZE 4
+.IX Item "-DTWO_POT_OPTIMIZE"
+Similarly to \f(CW\*(C`PACK_MALLOC\*(C'\fR, this macro improves allocations of data
+with size close to a power of two; but this works for big allocations
+(starting with 16K by default).  Such allocations are typical for big
+hashes and special-purpose scripts, especially image processing.
+.Sp
+On recent systems, the fact that perl requires 2M from system for 1M
+allocation will not affect speed of execution, since the tail of such
+a chunk is not going to be touched (and thus will not require real
+memory).  However, it may result in a premature out-of-memory error.
+So if you will be manipulating very large blocks with sizes close to
+powers of two, it would be wise to define this macro.
+.Sp
+Expected saving of memory is 0\-100% (100% in applications which
+require most memory in such 2**n chunks); expected slowdown is
+negligible.
+.SS "Miscellaneous efficiency enhancements"
+.IX Subsection "Miscellaneous efficiency enhancements"
+Functions that have an empty prototype and that do nothing but return
+a fixed value are now inlined (e.g. \f(CW\*(C`sub PI () { 3.14159 }\*(C'\fR).
+.PP
+Each unique hash key is only allocated once, no matter how many hashes
+have an entry with that key.  So even if you have 100 copies of the
+same hash, the hash keys never have to be reallocated.
+.SH "Support for More Operating Systems"
+.IX Header "Support for More Operating Systems"
+Support for the following operating systems is new in Perl 5.004.
+.SS Win32
+.IX Subsection "Win32"
+Perl 5.004 now includes support for building a "native" perl under
+Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
+and above) or the Borland C++ compiler (versions 5.02 and above).
+The resulting perl can be used under Windows 95 (if it
+is installed in the same directory locations as it got installed
+in Windows NT).  This port includes support for perl extension
+building tools like ExtUtils::MakeMaker and h2xs, so that many extensions
+available on the Comprehensive Perl Archive Network (CPAN) can now be
+readily built under Windows NT.  See http://www.perl.com/ for more
+information on CPAN and \fIREADME.win32\fR in the perl distribution for more
+details on how to get started with building this port.
+.PP
+There is also support for building perl under the Cygwin32 environment.
+Cygwin32 is a set of GNU tools that make it possible to compile and run
+many Unix programs under Windows NT by providing a mostly Unix-like 
+interface for compilation and execution.  See \fIREADME.cygwin32\fR in the
+perl distribution for more details on this port and how to obtain the
+Cygwin32 toolkit.
+.SS "Plan 9"
+.IX Subsection "Plan 9"
+See \fIREADME.plan9\fR in the perl distribution.
+.SS QNX
+.IX Subsection "QNX"
+See \fIREADME.qnx\fR in the perl distribution.
+.SS AmigaOS
+.IX Subsection "AmigaOS"
+See \fIREADME.amigaos\fR in the perl distribution.
+.SH Pragmata
+.IX Header "Pragmata"
+Six new pragmatic modules exist:
+.IP "use autouse MODULE => qw(sub1 sub2 sub3)" 4
+.IX Item "use autouse MODULE => qw(sub1 sub2 sub3)"
+Defers \f(CW\*(C`require MODULE\*(C'\fR until someone calls one of the specified
+subroutines (which must be exported by MODULE).  This pragma should be
+used with caution, and only when necessary.
+.IP "use blib" 4
+.IX Item "use blib"
+.PD 0
+.IP "use blib 'dir'" 4
+.IX Item "use blib 'dir'"
+.PD
+Looks for MakeMaker-like \fI'blib'\fR directory structure starting in
+\&\fIdir\fR (or current directory) and working back up to five levels of
+parent directories.
+.Sp
+Intended for use on command line with \fB\-M\fR option as a way of testing
+arbitrary scripts against an uninstalled version of a package.
+.IP "use constant NAME => VALUE" 4
+.IX Item "use constant NAME => VALUE"
+Provides a convenient interface for creating compile-time constants,
+See "Constant Functions" in perlsub.
+.IP "use locale" 4
+.IX Item "use locale"
+Tells the compiler to enable (or disable) the use of POSIX locales for
+builtin operations.
+.Sp
+When \f(CW\*(C`use locale\*(C'\fR is in effect, the current LC_CTYPE locale is used
+for regular expressions and case mapping; LC_COLLATE for string
+ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
+(but \fBnot\fR in print).  LC_NUMERIC is always used in write, since
+lexical scoping of formats is problematic at best.
+.Sp
+Each \f(CW\*(C`use locale\*(C'\fR or \f(CW\*(C`no locale\*(C'\fR affects statements to the end of
+the enclosing BLOCK or, if not inside a BLOCK, to the end of the
+current file.  Locales can be switched and queried with
+\&\fBPOSIX::setlocale()\fR.
+.Sp
+See perllocale for more information.
+.IP "use ops" 4
+.IX Item "use ops"
+Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
+.IP "use vmsish" 4
+.IX Item "use vmsish"
+Enable VMS-specific language features.  Currently, there are three
+VMS-specific features available: 'status', which makes \f(CW$?\fR and
+\&\f(CW\*(C`system\*(C'\fR return genuine VMS status values instead of emulating POSIX;
+\&'exit', which makes \f(CW\*(C`exit\*(C'\fR take a genuine VMS status value instead of
+assuming that \f(CW\*(C`exit 1\*(C'\fR is an error; and 'time', which makes all times
+relative to the local time zone, in the VMS tradition.
+.SH Modules
+.IX Header "Modules"
+.SS "Required Updates"
+.IX Subsection "Required Updates"
+Though Perl 5.004 is compatible with almost all modules that work
+with Perl 5.003, there are a few exceptions:
+.PP
+.Vb 5
+\&    Module   Required Version for Perl 5.004
+\&    \-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    Filter   Filter\-1.12
+\&    LWP      libwww\-perl\-5.08
+\&    Tk       Tk400.202 (\-w makes noise)
+.Ve
+.PP
+Also, the majordomo mailing list program, version 1.94.1, doesn't work
+with Perl 5.004 (nor with perl 4), because it executes an invalid
+regular expression.  This bug is fixed in majordomo version 1.94.2.
+.SS "Installation directories"
+.IX Subsection "Installation directories"
+The \fIinstallperl\fR script now places the Perl source files for
+extensions in the architecture-specific library directory, which is
+where the shared libraries for extensions have always been.  This
+change is intended to allow administrators to keep the Perl 5.004
+library directory unchanged from a previous version, without running
+the risk of binary incompatibility between extensions' Perl source and
+shared libraries.
+.SS "Module information summary"
+.IX Subsection "Module information summary"
+Brand new modules, arranged by topic rather than strictly
+alphabetically:
+.PP
+.Vb 6
+\&    CGI.pm               Web server interface ("Common Gateway Interface")
+\&    CGI/Apache.pm        Support for Apache\*(Aqs Perl module
+\&    CGI/Carp.pm          Log server errors with helpful context
+\&    CGI/Fast.pm          Support for FastCGI (persistent server process)
+\&    CGI/Push.pm          Support for server push
+\&    CGI/Switch.pm        Simple interface for multiple server types
+\&
+\&    CPAN                 Interface to Comprehensive Perl Archive Network
+\&    CPAN::FirstTime      Utility for creating CPAN configuration file
+\&    CPAN::Nox            Runs CPAN while avoiding compiled extensions
+\&
+\&    IO.pm                Top\-level interface to IO::* classes
+\&    IO/File.pm           IO::File extension Perl module
+\&    IO/Handle.pm         IO::Handle extension Perl module
+\&    IO/Pipe.pm           IO::Pipe extension Perl module
+\&    IO/Seekable.pm       IO::Seekable extension Perl module
+\&    IO/Select.pm         IO::Select extension Perl module
+\&    IO/Socket.pm         IO::Socket extension Perl module
+\&
+\&    Opcode.pm            Disable named opcodes when compiling Perl code
+\&
+\&    ExtUtils/Embed.pm    Utilities for embedding Perl in C programs
+\&    ExtUtils/testlib.pm  Fixes up @INC to use just\-built extension
+\&
+\&    FindBin.pm           Find path of currently executing program
+\&
+\&    Class/Struct.pm      Declare struct\-like datatypes as Perl classes
+\&    File/stat.pm         By\-name interface to Perl\*(Aqs builtin stat
+\&    Net/hostent.pm       By\-name interface to Perl\*(Aqs builtin gethost*
+\&    Net/netent.pm        By\-name interface to Perl\*(Aqs builtin getnet*
+\&    Net/protoent.pm      By\-name interface to Perl\*(Aqs builtin getproto*
+\&    Net/servent.pm       By\-name interface to Perl\*(Aqs builtin getserv*
+\&    Time/gmtime.pm       By\-name interface to Perl\*(Aqs builtin gmtime
+\&    Time/localtime.pm    By\-name interface to Perl\*(Aqs builtin localtime
+\&    Time/tm.pm           Internal object for Time::{gm,local}time
+\&    User/grent.pm        By\-name interface to Perl\*(Aqs builtin getgr*
+\&    User/pwent.pm        By\-name interface to Perl\*(Aqs builtin getpw*
+\&
+\&    Tie/RefHash.pm       Base class for tied hashes with references as keys
+\&
+\&    UNIVERSAL.pm         Base class for *ALL* classes
+.Ve
+.SS Fcntl
+.IX Subsection "Fcntl"
+New constants in the existing Fcntl modules are now supported,
+provided that your operating system happens to support them:
+.PP
+.Vb 3
+\&    F_GETOWN F_SETOWN
+\&    O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
+\&    O_EXLOCK O_SHLOCK
+.Ve
+.PP
+These constants are intended for use with the Perl operators \fBsysopen()\fR
+and \fBfcntl()\fR and the basic database modules like SDBM_File.  For the
+exact meaning of these and other Fcntl constants please refer to your
+operating system's documentation for \fBfcntl()\fR and \fBopen()\fR.
+.PP
+In addition, the Fcntl module now provides these constants for use
+with the Perl operator \fBflock()\fR:
+.PP
+.Vb 1
+\&        LOCK_SH LOCK_EX LOCK_NB LOCK_UN
+.Ve
+.PP
+These constants are defined in all environments (because where there is
+no \fBflock()\fR system call, Perl emulates it).  However, for historical
+reasons, these constants are not exported unless they are explicitly
+requested with the ":flock" tag (e.g. \f(CW\*(C`use Fcntl \*(Aq:flock\*(Aq\*(C'\fR).
+.SS IO
+.IX Subsection "IO"
+The IO module provides a simple mechanism to load all the IO modules at one
+go.  Currently this includes:
+.PP
+.Vb 5
+\&     IO::Handle
+\&     IO::Seekable
+\&     IO::File
+\&     IO::Pipe
+\&     IO::Socket
+.Ve
+.PP
+For more information on any of these modules, please see its
+respective documentation.
+.SS Math::Complex
+.IX Subsection "Math::Complex"
+The Math::Complex module has been totally rewritten, and now supports
+more operations.  These are overloaded:
+.PP
+.Vb 1
+\&     + \- * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
+.Ve
+.PP
+And these functions are now exported:
+.PP
+.Vb 11
+\&    pi i Re Im arg
+\&    log10 logn ln cbrt root
+\&    tan
+\&    csc sec cot
+\&    asin acos atan
+\&    acsc asec acot
+\&    sinh cosh tanh
+\&    csch sech coth
+\&    asinh acosh atanh
+\&    acsch asech acoth
+\&    cplx cplxe
+.Ve
+.SS Math::Trig
+.IX Subsection "Math::Trig"
+This new module provides a simpler interface to parts of Math::Complex for
+those who need trigonometric functions only for real numbers.
+.SS DB_File
+.IX Subsection "DB_File"
+There have been quite a few changes made to DB_File. Here are a few of
+the highlights:
+.IP \(bu 4
+Fixed a handful of bugs.
+.IP \(bu 4
+By public demand, added support for the standard hash function \fBexists()\fR.
+.IP \(bu 4
+Made it compatible with Berkeley DB 1.86.
+.IP \(bu 4
+Made negative subscripts work with RECNO interface.
+.IP \(bu 4
+Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
+mode from 0640 to 0666.
+.IP \(bu 4
+Made DB_File automatically import the \fBopen()\fR constants (O_RDWR,
+O_CREAT etc.) from Fcntl, if available.
+.IP \(bu 4
+Updated documentation.
+.PP
+Refer to the HISTORY section in DB_File.pm for a complete list of
+changes. Everything after DB_File 1.01 has been added since 5.003.
+.SS Net::Ping
+.IX Subsection "Net::Ping"
+Major rewrite \- support added for both udp echo and real icmp pings.
+.SS "Object-oriented overrides for builtin operators"
+.IX Subsection "Object-oriented overrides for builtin operators"
+Many of the Perl builtins returning lists now have
+object-oriented overrides.  These are:
+.PP
+.Vb 9
+\&    File::stat
+\&    Net::hostent
+\&    Net::netent
+\&    Net::protoent
+\&    Net::servent
+\&    Time::gmtime
+\&    Time::localtime
+\&    User::grent
+\&    User::pwent
+.Ve
+.PP
+For example, you can now say
+.PP
+.Vb 3
+\&    use File::stat;
+\&    use User::pwent;
+\&    $his = (stat($filename)\->st_uid == pwent($whoever)\->pw_uid);
+.Ve
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS pod2html
+.IX Subsection "pod2html"
+.IP "Sends converted HTML to standard output" 4
+.IX Item "Sends converted HTML to standard output"
+The \fIpod2html\fR utility included with Perl 5.004 is entirely new.
+By default, it sends the converted HTML to its standard output,
+instead of writing it to a file like Perl 5.003's \fIpod2html\fR did.
+Use the \fB\-\-outfile=FILENAME\fR option to write to a file.
+.SS xsubpp
+.IX Subsection "xsubpp"
+.ie n .IP """void"" XSUBs now default to returning nothing" 4
+.el .IP "\f(CWvoid\fR XSUBs now default to returning nothing" 4
+.IX Item "void XSUBs now default to returning nothing"
+Due to a documentation/implementation bug in previous versions of
+Perl, XSUBs with a return type of \f(CW\*(C`void\*(C'\fR have actually been
+returning one value.  Usually that value was the GV for the XSUB,
+but sometimes it was some already freed or reused value, which would
+sometimes lead to program failure.
+.Sp
+In Perl 5.004, if an XSUB is declared as returning \f(CW\*(C`void\*(C'\fR, it
+actually returns no value, i.e. an empty list (though there is a
+backward-compatibility exception; see below).  If your XSUB really
+does return an SV, you should give it a return type of \f(CW\*(C`SV *\*(C'\fR.
+.Sp
+For backward compatibility, \fIxsubpp\fR tries to guess whether a
+\&\f(CW\*(C`void\*(C'\fR XSUB is really \f(CW\*(C`void\*(C'\fR or if it wants to return an \f(CW\*(C`SV *\*(C'\fR.
+It does so by examining the text of the XSUB: if \fIxsubpp\fR finds
+what looks like an assignment to \f(CWST(0)\fR, it assumes that the
+XSUB's return type is really \f(CW\*(C`SV *\*(C'\fR.
+.SH "C Language API Changes"
+.IX Header "C Language API Changes"
+.ie n .IP """gv_fetchmethod"" and ""perl_call_sv""" 4
+.el .IP "\f(CWgv_fetchmethod\fR and \f(CWperl_call_sv\fR" 4
+.IX Item "gv_fetchmethod and perl_call_sv"
+The \f(CW\*(C`gv_fetchmethod\*(C'\fR function finds a method for an object, just like
+in Perl 5.003.  The GV it returns may be a method cache entry.
+However, in Perl 5.004, method cache entries are not visible to users;
+therefore, they can no longer be passed directly to \f(CW\*(C`perl_call_sv\*(C'\fR.
+Instead, you should use the \f(CW\*(C`GvCV\*(C'\fR macro on the GV to extract its CV,
+and pass the CV to \f(CW\*(C`perl_call_sv\*(C'\fR.
+.Sp
+The most likely symptom of passing the result of \f(CW\*(C`gv_fetchmethod\*(C'\fR to
+\&\f(CW\*(C`perl_call_sv\*(C'\fR is Perl's producing an "Undefined subroutine called"
+error on the \fIsecond\fR call to a given method (since there is no cache
+on the first call).
+.ie n .IP """perl_eval_pv""" 4
+.el .IP \f(CWperl_eval_pv\fR 4
+.IX Item "perl_eval_pv"
+A new function handy for eval'ing strings of Perl code inside C code.
+This function returns the value from the eval statement, which can
+be used instead of fetching globals from the symbol table.  See
+perlguts, perlembed and perlcall for details and examples.
+.IP "Extended API for manipulating hashes" 4
+.IX Item "Extended API for manipulating hashes"
+Internal handling of hash keys has changed.  The old hashtable API is
+still fully supported, and will likely remain so.  The additions to the
+API allow passing keys as \f(CW\*(C`SV*\*(C'\fRs, so that \f(CW\*(C`tied\*(C'\fR hashes can be given
+real scalars as keys rather than plain strings (nontied hashes still
+can only use strings as keys).  New extensions must use the new hash
+access functions and macros if they wish to use \f(CW\*(C`SV*\*(C'\fR keys.  These
+additions also make it feasible to manipulate \f(CW\*(C`HE*\*(C'\fRs (hash entries),
+which can be more efficient.  See perlguts for details.
+.SH "Documentation Changes"
+.IX Header "Documentation Changes"
+Many of the base and library pods were updated.  These
+new pods are included in section 1:
+.IP perldelta 4
+.IX Item "perldelta"
+This document.
+.IP perlfaq 4
+.IX Item "perlfaq"
+Frequently asked questions.
+.IP perllocale 4
+.IX Item "perllocale"
+Locale support (internationalization and localization).
+.IP perltoot 4
+.IX Item "perltoot"
+Tutorial on Perl OO programming.
+.IP perlapio 4
+.IX Item "perlapio"
+Perl internal IO abstraction interface.
+.IP perlmodlib 4
+.IX Item "perlmodlib"
+Perl module library and recommended practice for module creation.
+Extracted from perlmod (which is much smaller as a result).
+.IP perldebug 4
+.IX Item "perldebug"
+Although not new, this has been massively updated.
+.IP perlsec 4
+.IX Item "perlsec"
+Although not new, this has been massively updated.
+.SH "New Diagnostics"
+.IX Header "New Diagnostics"
+Several new conditions will trigger warnings that were
+silent before.  Some only affect certain platforms.
+The following new warnings and errors outline these.
+These messages are classified as follows (listed in
+increasing order of desperation):
+.PP
+.Vb 7
+\&   (W) A warning (optional).
+\&   (D) A deprecation (optional).
+\&   (S) A severe warning (mandatory).
+\&   (F) A fatal error (trappable).
+\&   (P) An internal error you should never see (trappable).
+\&   (X) A very fatal error (nontrappable).
+\&   (A) An alien error message (not generated by Perl).
+.Ve
+.ie n .IP """my"" variable %s masks earlier declaration in same scope" 4
+.el .IP """my"" variable \f(CW%s\fR masks earlier declaration in same scope" 4
+.IX Item """my"" variable %s masks earlier declaration in same scope"
+(W) A lexical variable has been redeclared in the same scope, effectively
+eliminating all access to the previous instance.  This is almost always
+a typographical error.  Note that the earlier variable will still exist
+until the end of the scope or until all closure referents to it are
+destroyed.
+.ie n .IP "%s argument is not a HASH element or slice" 4
+.el .IP "\f(CW%s\fR argument is not a HASH element or slice" 4
+.IX Item "%s argument is not a HASH element or slice"
+(F) The argument to \fBdelete()\fR must be either a hash element, such as
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->[12]\->{"susie"}
+.Ve
+.Sp
+or a hash slice, such as
+.Sp
+.Vb 2
+\&    @foo{$bar, $baz, $xyzzy}
+\&    @{$ref\->[12]}{"susie", "queue"}
+.Ve
+.ie n .IP "Allocation too large: %lx" 4
+.el .IP "Allocation too large: \f(CW%lx\fR" 4
+.IX Item "Allocation too large: %lx"
+(X) You can't allocate more than 64K on an MS-DOS machine.
+.IP "Allocation too large" 4
+.IX Item "Allocation too large"
+(F) You can't allocate more than 2^31+"small amount" bytes.
+.ie n .IP "Applying %s to %s will act on scalar(%s)" 4
+.el .IP "Applying \f(CW%s\fR to \f(CW%s\fR will act on scalar(%s)" 4
+.IX Item "Applying %s to %s will act on scalar(%s)"
+(W) The pattern match (//), substitution (s///), and transliteration (tr///)
+operators work on scalar values.  If you apply one of them to an array
+or a hash, it will convert the array or hash to a scalar value (the
+length of an array or the population info of a hash) and then work on
+that scalar value.  This is probably not what you meant to do.  See
+"grep" in perlfunc and "map" in perlfunc for alternatives.
+.IP "Attempt to free nonexistent shared string" 4
+.IX Item "Attempt to free nonexistent shared string"
+(P) Perl maintains a reference counted internal table of strings to
+optimize the storage and access of hash keys and other strings.  This
+indicates someone tried to decrement the reference count of a string
+that can no longer be found in the table.
+.IP "Attempt to use reference as lvalue in substr" 4
+.IX Item "Attempt to use reference as lvalue in substr"
+(W) You supplied a reference as the first argument to \fBsubstr()\fR used
+as an lvalue, which is pretty strange.  Perhaps you forgot to
+dereference it first.  See "substr" in perlfunc.
+.IP "Bareword ""%s"" refers to nonexistent package" 4
+.IX Item "Bareword ""%s"" refers to nonexistent package"
+(W) You used a qualified bareword of the form \f(CW\*(C`Foo::\*(C'\fR, but
+the compiler saw no other uses of that namespace before that point.
+Perhaps you need to predeclare a package?
+.ie n .IP "Can't redefine active sort subroutine %s" 4
+.el .IP "Can't redefine active sort subroutine \f(CW%s\fR" 4
+.IX Item "Can't redefine active sort subroutine %s"
+(F) Perl optimizes the internal handling of sort subroutines and keeps
+pointers into them.  You tried to redefine one such sort subroutine when it
+was currently active, which is not allowed.  If you really want to do
+this, you should write \f(CW\*(C`sort { &func } @x\*(C'\fR instead of \f(CW\*(C`sort func @x\*(C'\fR.
+.ie n .IP "Can't use bareword (""%s"") as %s ref while ""strict refs"" in use" 4
+.el .IP "Can't use bareword (""%s"") as \f(CW%s\fR ref while ""strict refs"" in use" 4
+.IX Item "Can't use bareword (""%s"") as %s ref while ""strict refs"" in use"
+(F) Only hard references are allowed by "strict refs".  Symbolic references
+are disallowed.  See perlref.
+.IP "Cannot resolve method `%s' overloading `%s' in package `%s'" 4
+.IX Item "Cannot resolve method `%s' overloading `%s' in package `%s'"
+(P) Internal error trying to resolve overloading specified by a method
+name (as opposed to a subroutine reference).
+.ie n .IP "Constant subroutine %s redefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR redefined" 4
+.IX Item "Constant subroutine %s redefined"
+(S) You redefined a subroutine which had previously been eligible for
+inlining.  See "Constant Functions" in perlsub for commentary and
+workarounds.
+.ie n .IP "Constant subroutine %s undefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR undefined" 4
+.IX Item "Constant subroutine %s undefined"
+(S) You undefined a subroutine which had previously been eligible for
+inlining.  See "Constant Functions" in perlsub for commentary and
+workarounds.
+.IP "Copy method did not return a reference" 4
+.IX Item "Copy method did not return a reference"
+(F) The method which overloads "=" is buggy. See "Copy Constructor" in overload.
+.IP Died 4
+.IX Item "Died"
+(F) You passed \fBdie()\fR an empty string (the equivalent of \f(CW\*(C`die ""\*(C'\fR) or
+you called it with no args and both \f(CW$@\fR and \f(CW$_\fR were empty.
+.ie n .IP "Exiting pseudo-block via %s" 4
+.el .IP "Exiting pseudo-block via \f(CW%s\fR" 4
+.IX Item "Exiting pseudo-block via %s"
+(W) You are exiting a rather special block construct (like a sort block or
+subroutine) by unconventional means, such as a goto, or a loop control
+statement.  See "sort" in perlfunc.
+.IP "Identifier too long" 4
+.IX Item "Identifier too long"
+(F) Perl limits identifiers (names for variables, functions, etc.) to
+252 characters for simple names, somewhat more for compound names (like
+\&\f(CW$A::B\fR).  You've exceeded Perl's limits.  Future versions of Perl are
+likely to eliminate these arbitrary limitations.
+.ie n .IP "Illegal character %s (carriage return)" 4
+.el .IP "Illegal character \f(CW%s\fR (carriage return)" 4
+.IX Item "Illegal character %s (carriage return)"
+(F) A carriage return character was found in the input.  This is an
+error, and not a warning, because carriage return characters can break
+multi-line strings, including here documents (e.g., \f(CW\*(C`print <<EOF;\*(C'\fR).
+.ie n .IP "Illegal switch in PERL5OPT: %s" 4
+.el .IP "Illegal switch in PERL5OPT: \f(CW%s\fR" 4
+.IX Item "Illegal switch in PERL5OPT: %s"
+(X) The PERL5OPT environment variable may only be used to set the
+following switches: \fB\-[DIMUdmw]\fR.
+.IP "Integer overflow in hex number" 4
+.IX Item "Integer overflow in hex number"
+(S) The literal hex number you have specified is too big for your
+architecture. On a 32\-bit architecture the largest hex literal is
+0xFFFFFFFF.
+.IP "Integer overflow in octal number" 4
+.IX Item "Integer overflow in octal number"
+(S) The literal octal number you have specified is too big for your
+architecture. On a 32\-bit architecture the largest octal literal is
+037777777777.
+.IP "internal error: glob failed" 4
+.IX Item "internal error: glob failed"
+(P) Something went wrong with the external program(s) used for \f(CW\*(C`glob\*(C'\fR
+and \f(CW\*(C`<*.c>\*(C'\fR.  This may mean that your csh (C shell) is
+broken.  If so, you should change all of the csh-related variables in
+config.sh:  If you have tcsh, make the variables refer to it as if it
+were csh (e.g. \f(CW\*(C`full_csh=\*(Aq/usr/bin/tcsh\*(Aq\*(C'\fR); otherwise, make them all
+empty (except that \f(CW\*(C`d_csh\*(C'\fR should be \f(CW\*(Aqundef\*(Aq\fR) so that Perl will
+think csh is missing.  In either case, after editing config.sh, run
+\&\f(CW\*(C`./Configure \-S\*(C'\fR and rebuild Perl.
+.ie n .IP "Invalid conversion in %s: ""%s""" 4
+.el .IP "Invalid conversion in \f(CW%s:\fR ""%s""" 4
+.IX Item "Invalid conversion in %s: ""%s"""
+(W) Perl does not understand the given format conversion.
+See "sprintf" in perlfunc.
+.IP "Invalid type in pack: '%s'" 4
+.IX Item "Invalid type in pack: '%s'"
+(F) The given character is not a valid pack type.  See "pack" in perlfunc.
+.IP "Invalid type in unpack: '%s'" 4
+.IX Item "Invalid type in unpack: '%s'"
+(F) The given character is not a valid unpack type.  See "unpack" in perlfunc.
+.IP "Name ""%s::%s"" used only once: possible typo" 4
+.IX Item "Name ""%s::%s"" used only once: possible typo"
+(W) Typographical errors often show up as unique variable names.
+If you had a good reason for having a unique name, then just mention
+it again somehow to suppress the message (the \f(CW\*(C`use vars\*(C'\fR pragma is
+provided for just this purpose).
+.IP "Null picture in formline" 4
+.IX Item "Null picture in formline"
+(F) The first argument to formline must be a valid format picture
+specification.  It was found to be empty, which probably means you
+supplied it an uninitialized value.  See perlform.
+.IP "Offset outside string" 4
+.IX Item "Offset outside string"
+(F) You tried to do a read/write/send/recv operation with an offset
+pointing outside the buffer.  This is difficult to imagine.
+The sole exception to this is that \f(CWsysread()\fRing past the buffer
+will extend the buffer and zero pad the new area.
+.IP "Out of memory!" 4
+.IX Item "Out of memory!"
+(X|F) The \fBmalloc()\fR function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request.
+.Sp
+The request was judged to be small, so the possibility to trap it
+depends on the way Perl was compiled.  By default it is not trappable.
+However, if compiled for this, Perl may use the contents of \f(CW$^M\fR as
+an emergency pool after \fBdie()\fRing with this message.  In this case the
+error is trappable \fIonce\fR.
+.ie n .IP "Out of memory during request for %s" 4
+.el .IP "Out of memory during request for \f(CW%s\fR" 4
+.IX Item "Out of memory during request for %s"
+(F) The \fBmalloc()\fR function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request. However,
+the request was judged large enough (compile-time default is 64K), so
+a possibility to shut down by trapping this error is granted.
+.IP "panic: frexp" 4
+.IX Item "panic: frexp"
+(P) The library function \fBfrexp()\fR failed, making printf("%f") impossible.
+.IP "Possible attempt to put comments in \fBqw()\fR list" 4
+.IX Item "Possible attempt to put comments in qw() list"
+(W) \fBqw()\fR lists contain items separated by whitespace; as with literal
+strings, comment characters are not ignored, but are instead treated
+as literal data.  (You may have used different delimiters than the
+parentheses shown here; braces are also frequently used.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a # a comment
+\&        b # another comment
+\&    );
+.Ve
+.Sp
+when you should have written this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a
+\&        b
+\&    );
+.Ve
+.Sp
+If you really want comments, build your list the
+old-fashioned way, with quotes and commas:
+.Sp
+.Vb 4
+\&    @list = (
+\&        \*(Aqa\*(Aq,    # a comment
+\&        \*(Aqb\*(Aq,    # another comment
+\&    );
+.Ve
+.IP "Possible attempt to separate words with commas" 4
+.IX Item "Possible attempt to separate words with commas"
+(W) \fBqw()\fR lists contain items separated by whitespace; therefore commas
+aren't needed to separate the items. (You may have used different
+delimiters than the parentheses shown here; braces are also frequently
+used.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 1
+\&    qw! a, b, c !;
+.Ve
+.Sp
+which puts literal commas into some of the list items.  Write it without
+commas if you don't want them to appear in your data:
+.Sp
+.Vb 1
+\&    qw! a b c !;
+.Ve
+.IP "Scalar value @%s{%s} better written as $%s{%s}" 4
+.IX Item "Scalar value @%s{%s} better written as $%s{%s}"
+(W) You've used a hash slice (indicated by @) to select a single element of
+a hash.  Generally it's better to ask for a scalar value (indicated by $).
+The difference is that \f(CW$foo{&bar}\fR always behaves like a scalar, both when
+assigning to it and when evaluating its argument, while \f(CW@foo{&bar}\fR behaves
+like a list when you assign to it, and provides a list context to its
+subscript, which can do weird things if you're expecting only one subscript.
+.ie n .IP "Stub found while resolving method `%s' overloading `%s' in %s" 4
+.el .IP "Stub found while resolving method `%s' overloading `%s' in \f(CW%s\fR" 4
+.IX Item "Stub found while resolving method `%s' overloading `%s' in %s"
+(P) Overloading resolution over \f(CW@ISA\fR tree may be broken by importing stubs.
+Stubs should never be implicitly created, but explicit calls to \f(CW\*(C`can\*(C'\fR
+may break this.
+.IP "Too late for ""\fB\-T\fR"" option" 4
+.IX Item "Too late for ""-T"" option"
+(X) The #! line (or local equivalent) in a Perl script contains the
+\&\fB\-T\fR option, but Perl was not invoked with \fB\-T\fR in its argument
+list.  This is an error because, by the time Perl discovers a \fB\-T\fR in
+a script, it's too late to properly taint everything from the
+environment.  So Perl gives up.
+.ie n .IP "untie attempted while %d inner references still exist" 4
+.el .IP "untie attempted while \f(CW%d\fR inner references still exist" 4
+.IX Item "untie attempted while %d inner references still exist"
+(W) A copy of the object returned from \f(CW\*(C`tie\*(C'\fR (or \f(CW\*(C`tied\*(C'\fR) was still
+valid when \f(CW\*(C`untie\*(C'\fR was called.
+.ie n .IP "Unrecognized character %s" 4
+.el .IP "Unrecognized character \f(CW%s\fR" 4
+.IX Item "Unrecognized character %s"
+(F) The Perl parser has no idea what to do with the specified character
+in your Perl script (or eval).  Perhaps you tried to run a compressed
+script, a binary program, or a directory as a Perl program.
+.IP "Unsupported function fork" 4
+.IX Item "Unsupported function fork"
+(F) Your version of executable does not support forking.
+.Sp
+Note that under some systems, like OS/2, there may be different flavors of
+Perl executables, some of which may support fork, some not. Try changing
+the name you call Perl by to \f(CW\*(C`perl_\*(C'\fR, \f(CW\*(C`perl_\|_\*(C'\fR, and so on.
+.IP "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated" 4
+.IX Item "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated"
+(D) Perl versions before 5.004 misinterpreted any type marker followed
+by "$" and a digit.  For example, "$$0" was incorrectly taken to mean
+"${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
+.Sp
+However, the developers of Perl 5.004 could not fix this bug completely,
+because at least two widely-used modules depend on the old meaning of
+"$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
+old (broken) way inside strings; but it generates this message as a
+warning.  And in Perl 5.005, this special treatment will cease.
+.ie n .IP "Value of %s can be ""0""; test with \fBdefined()\fR" 4
+.el .IP "Value of \f(CW%s\fR can be ""0""; test with \fBdefined()\fR" 4
+.IX Item "Value of %s can be ""0""; test with defined()"
+(W) In a conditional expression, you used <HANDLE>, <*> (glob), \f(CWeach()\fR,
+or \f(CWreaddir()\fR as a boolean value.  Each of these constructs can return a
+value of "0"; that would make the conditional expression false, which is
+probably not what you intended.  When using these constructs in conditional
+expressions, test their values with the \f(CW\*(C`defined\*(C'\fR operator.
+.IP "Variable ""%s"" may be unavailable" 4
+.IX Item "Variable ""%s"" may be unavailable"
+(W) An inner (nested) \fIanonymous\fR subroutine is inside a \fInamed\fR
+subroutine, and outside that is another subroutine; and the anonymous
+(innermost) subroutine is referencing a lexical variable defined in
+the outermost subroutine.  For example:
+.Sp
+.Vb 1
+\&   sub outermost { my $a; sub middle { sub { $a } } }
+.Ve
+.Sp
+If the anonymous subroutine is called or referenced (directly or
+indirectly) from the outermost subroutine, it will share the variable
+as you would expect.  But if the anonymous subroutine is called or
+referenced when the outermost subroutine is not active, it will see
+the value of the shared variable as it was before and during the
+*first* call to the outermost subroutine, which is probably not what
+you want.
+.Sp
+In these circumstances, it is usually best to make the middle
+subroutine anonymous, using the \f(CW\*(C`sub {}\*(C'\fR syntax.  Perl has specific
+support for shared variables in nested anonymous subroutines; a named
+subroutine in between interferes with this feature.
+.IP "Variable ""%s"" will not stay shared" 4
+.IX Item "Variable ""%s"" will not stay shared"
+(W) An inner (nested) \fInamed\fR subroutine is referencing a lexical
+variable defined in an outer subroutine.
+.Sp
+When the inner subroutine is called, it will probably see the value of
+the outer subroutine's variable as it was before and during the
+*first* call to the outer subroutine; in this case, after the first
+call to the outer subroutine is complete, the inner and outer
+subroutines will no longer share a common value for the variable.  In
+other words, the variable will no longer be shared.
+.Sp
+Furthermore, if the outer subroutine is anonymous and references a
+lexical variable outside itself, then the outer and inner subroutines
+will \fInever\fR share the given variable.
+.Sp
+This problem can usually be solved by making the inner subroutine
+anonymous, using the \f(CW\*(C`sub {}\*(C'\fR syntax.  When inner anonymous subs that
+reference variables in outer subroutines are called or referenced,
+they are automatically rebound to the current values of such
+variables.
+.IP "Warning: something's wrong" 4
+.IX Item "Warning: something's wrong"
+(W) You passed \fBwarn()\fR an empty string (the equivalent of \f(CW\*(C`warn ""\*(C'\fR) or
+you called it with no args and \f(CW$_\fR was empty.
+.IP "Ill-formed logical name |%s| in prime_env_iter" 4
+.IX Item "Ill-formed logical name |%s| in prime_env_iter"
+(W) A warning peculiar to VMS.  A logical name was encountered when preparing
+to iterate over \f(CW%ENV\fR which violates the syntactic rules governing logical
+names.  Since it cannot be translated normally, it is skipped, and will not
+appear in \f(CW%ENV\fR.  This may be a benign occurrence, as some software packages
+might directly modify logical name tables and introduce nonstandard names,
+or it may indicate that a logical name table has been corrupted.
+.IP "Got an error from DosAllocMem" 4
+.IX Item "Got an error from DosAllocMem"
+(P) An error peculiar to OS/2.  Most probably you're using an obsolete
+version of Perl, and this should not happen anyway.
+.IP "Malformed PERLLIB_PREFIX" 4
+.IX Item "Malformed PERLLIB_PREFIX"
+(F) An error peculiar to OS/2.  PERLLIB_PREFIX should be of the form
+.Sp
+.Vb 1
+\&    prefix1;prefix2
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&    prefix1 prefix2
+.Ve
+.Sp
+with nonempty prefix1 and prefix2.  If \f(CW\*(C`prefix1\*(C'\fR is indeed a prefix
+of a builtin library search path, prefix2 is substituted.  The error
+may appear if components are not found, or are too long.  See
+"PERLLIB_PREFIX" in \fIREADME.os2\fR.
+.IP "PERL_SH_DIR too long" 4
+.IX Item "PERL_SH_DIR too long"
+(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
+\&\f(CW\*(C`sh\*(C'\fR\-shell in.  See "PERL_SH_DIR" in \fIREADME.os2\fR.
+.IP "Process terminated by SIG%s" 4
+.IX Item "Process terminated by SIG%s"
+(W) This is a standard message issued by OS/2 applications, while *nix
+applications die in silence.  It is considered a feature of the OS/2
+port.  One can easily disable this by appropriate sighandlers, see
+"Signals" in perlipc.  See also "Process terminated by SIGTERM/SIGINT"
+in \fIREADME.os2\fR.
+.SH BUGS
+.IX Header "BUGS"
+If you find what you think is a bug, you might check the headers of
+recently posted articles in the comp.lang.perl.misc newsgroup.
+There may also be information at http://www.perl.com/perl/ , the Perl
+Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Make sure you trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to <\fIperlbug@perl.com\fR> to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.  This file has been
+significantly updated for 5.004, so even veteran users should
+look through it.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fICopying\fR file for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Constructed by Tom Christiansen, grabbing material with permission
+from innumerable contributors, with kibitzing by more than a few Perl
+porters.
+.PP
+Last update: Wed May 14 11:14:09 EDT 1997
diff --git a/upstream/mageia-cauldron/man1/perl5005delta.1 b/upstream/mageia-cauldron/man1/perl5005delta.1
new file mode 100644
index 00000000..f534375c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5005delta.1
@@ -0,0 +1,939 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5005DELTA 1"
+.TH PERL5005DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5005delta \- what's new for perl5.005
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.004 release and this one.
+.SH "About the new versioning system"
+.IX Header "About the new versioning system"
+Perl is now developed on two tracks: a maintenance track that makes
+small, safe updates to released production versions with emphasis on
+compatibility; and a development track that pursues more aggressive
+evolution.  Maintenance releases (which should be considered production
+quality) have subversion numbers that run from \f(CW1\fR to \f(CW49\fR, and
+development releases (which should be considered "alpha" quality) run
+from \f(CW50\fR to \f(CW99\fR.
+.PP
+Perl 5.005 is the combined product of the new dual-track development
+scheme.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "WARNING:  This version is not binary compatible with Perl 5.004."
+.IX Subsection "WARNING: This version is not binary compatible with Perl 5.004."
+Starting with Perl 5.004_50 there were many deep and far-reaching changes
+to the language internals.  If you have dynamically loaded extensions
+that you built under perl 5.003 or 5.004, you can continue to use them
+with 5.004, but you will need to rebuild and reinstall those extensions
+to use them 5.005.  See \fIINSTALL\fR for detailed instructions on how to
+upgrade.
+.SS "Default installation structure has changed"
+.IX Subsection "Default installation structure has changed"
+The new Configure defaults are designed to allow a smooth upgrade from
+5.004 to 5.005, but you should read \fIINSTALL\fR for a detailed
+discussion of the changes in order to adapt them to your system.
+.SS "Perl Source Compatibility"
+.IX Subsection "Perl Source Compatibility"
+When none of the experimental features are enabled, there should be
+very few user-visible Perl source compatibility issues.
+.PP
+If threads are enabled, then some caveats apply. \f(CW@_\fR and \f(CW$_\fR become
+lexical variables.  The effect of this should be largely transparent to
+the user, but there are some boundary conditions under which user will
+need to be aware of the issues.  For example, \f(CWlocal(@_)\fR results in
+a "Can't localize lexical variable \f(CW@_\fR ..." message.  This may be enabled
+in a future version.
+.PP
+Some new keywords have been introduced.  These are generally expected to
+have very little impact on compatibility.  See "New \f(CW\*(C`INIT\*(C'\fR keyword",
+"New \f(CW\*(C`lock\*(C'\fR keyword", and "New \f(CW\*(C`qr//\*(C'\fR operator".
+.PP
+Certain barewords are now reserved.  Use of these will provoke a warning
+if you have asked for them with the \f(CW\*(C`\-w\*(C'\fR switch.
+See "\f(CW\*(C`our\*(C'\fR is now a reserved word".
+.SS "C Source Compatibility"
+.IX Subsection "C Source Compatibility"
+There have been a large number of changes in the internals to support
+the new features in this release.
+.IP \(bu 4
+Core sources now require ANSI C compiler
+.Sp
+An ANSI C compiler is now \fBrequired\fR to build perl.  See \fIINSTALL\fR.
+.IP \(bu 4
+All Perl global variables must now be referenced with an explicit prefix
+.Sp
+All Perl global variables that are visible for use by extensions now
+have a \f(CW\*(C`PL_\*(C'\fR prefix.  New extensions should \f(CW\*(C`not\*(C'\fR refer to perl globals
+by their unqualified names.  To preserve sanity, we provide limited
+backward compatibility for globals that are being widely used like
+\&\f(CW\*(C`sv_undef\*(C'\fR and \f(CW\*(C`na\*(C'\fR (which should now be written as \f(CW\*(C`PL_sv_undef\*(C'\fR,
+\&\f(CW\*(C`PL_na\*(C'\fR etc.)
+.Sp
+If you find that your XS extension does not compile anymore because a
+perl global is not visible, try adding a \f(CW\*(C`PL_\*(C'\fR prefix to the global
+and rebuild.
+.Sp
+It is strongly recommended that all functions in the Perl API that don't
+begin with \f(CW\*(C`perl\*(C'\fR be referenced with a \f(CW\*(C`Perl_\*(C'\fR prefix.  The bare function
+names without the \f(CW\*(C`Perl_\*(C'\fR prefix are supported with macros, but this
+support may cease in a future release.
+.Sp
+See perlapi.
+.IP \(bu 4
+Enabling threads has source compatibility issues
+.Sp
+Perl built with threading enabled requires extensions to use the new
+\&\f(CW\*(C`dTHR\*(C'\fR macro to initialize the handle to access per-thread data.
+If you see a compiler error that talks about the variable \f(CW\*(C`thr\*(C'\fR not
+being declared (when building a module that has XS code),  you need
+to add \f(CW\*(C`dTHR;\*(C'\fR at the beginning of the block that elicited the error.
+.Sp
+The API function \f(CW\*(C`perl_get_sv("@",GV_ADD)\*(C'\fR should be used instead of
+directly accessing perl globals as \f(CWGvSV(errgv)\fR.  The API call is
+backward compatible with existing perls and provides source compatibility
+with threading is enabled.
+.Sp
+See "C Source Compatibility" for more information.
+.SS "Binary Compatibility"
+.IX Subsection "Binary Compatibility"
+This version is NOT binary compatible with older versions.  All extensions
+will need to be recompiled.  Further binaries built with threads enabled
+are incompatible with binaries built without.  This should largely be
+transparent to the user, as all binary incompatible configurations have
+their own unique architecture name, and extension binaries get installed at
+unique locations.  This allows coexistence of several configurations in
+the same directory hierarchy.  See \fIINSTALL\fR.
+.SS "Security fixes may affect compatibility"
+.IX Subsection "Security fixes may affect compatibility"
+A few taint leaks and taint omissions have been corrected.  This may lead
+to "failure" of scripts that used to work with older versions.  Compiling
+with \-DINCOMPLETE_TAINTS provides a perl with minimal amounts of changes
+to the tainting behavior.  But note that the resulting perl will have
+known insecurities.
+.PP
+Oneliners with the \f(CW\*(C`\-e\*(C'\fR switch do not create temporary files anymore.
+.SS "Relaxed new mandatory warnings introduced in 5.004"
+.IX Subsection "Relaxed new mandatory warnings introduced in 5.004"
+Many new warnings that were introduced in 5.004 have been made
+optional.  Some of these warnings are still present, but perl's new
+features make them less often a problem.  See "New Diagnostics".
+.SS Licensing
+.IX Subsection "Licensing"
+Perl has a new Social Contract for contributors.  See \fIPorting/Contract\fR.
+.PP
+The license included in much of the Perl documentation has changed.
+Most of the Perl documentation was previously under the implicit GNU
+General Public License or the Artistic License (at the user's choice).
+Now much of the documentation unambiguously states the terms under which
+it may be distributed.  Those terms are in general much less restrictive
+than the GNU GPL.  See perl and the individual perl manpages listed
+therein.
+.SH "Core Changes"
+.IX Header "Core Changes"
+.SS Threads
+.IX Subsection "Threads"
+WARNING: Threading is considered an \fBexperimental\fR feature.  Details of the
+implementation may change without notice.  There are known limitations
+and some bugs.  These are expected to be fixed in future versions.
+.PP
+See \fIREADME.threads\fR.
+.SS Compiler
+.IX Subsection "Compiler"
+WARNING: The Compiler and related tools are considered \fBexperimental\fR.
+Features may change without notice, and there are known limitations
+and bugs.  Since the compiler is fully external to perl, the default
+configuration will build and install it.
+.PP
+The Compiler produces three different types of transformations of a
+perl program.  The C backend generates C code that captures perl's state
+just before execution begins.  It eliminates the compile-time overheads
+of the regular perl interpreter, but the run-time performance remains
+comparatively the same.  The CC backend generates optimized C code
+equivalent to the code path at run-time.  The CC backend has greater
+potential for big optimizations, but only a few optimizations are
+implemented currently.  The Bytecode backend generates a platform
+independent bytecode representation of the interpreter's state
+just before execution.  Thus, the Bytecode back end also eliminates
+much of the compilation overhead of the interpreter.
+.PP
+The compiler comes with several valuable utilities.
+.PP
+\&\f(CW\*(C`B::Lint\*(C'\fR is an experimental module to detect and warn about suspicious
+code, especially the cases that the \f(CW\*(C`\-w\*(C'\fR switch does not detect.
+.PP
+\&\f(CW\*(C`B::Deparse\*(C'\fR can be used to demystify perl code, and understand
+how perl optimizes certain constructs.
+.PP
+\&\f(CW\*(C`B::Xref\*(C'\fR generates cross reference reports of all definition and use
+of variables, subroutines and formats in a program.
+.PP
+\&\f(CW\*(C`B::Showlex\*(C'\fR show the lexical variables used by a subroutine or file
+at a glance.
+.PP
+\&\f(CW\*(C`perlcc\*(C'\fR is a simple frontend for compiling perl.
+.PP
+See \f(CW\*(C`ext/B/README\*(C'\fR, B, and the respective compiler modules.
+.SS "Regular Expressions"
+.IX Subsection "Regular Expressions"
+Perl's regular expression engine has been seriously overhauled, and
+many new constructs are supported.  Several bugs have been fixed.
+.PP
+Here is an itemized summary:
+.IP "Many new and improved optimizations" 4
+.IX Item "Many new and improved optimizations"
+Changes in the RE engine:
+.Sp
+.Vb 7
+\&        Unneeded nodes removed;
+\&        Substrings merged together;
+\&        New types of nodes to process (SUBEXPR)* and similar expressions
+\&            quickly, used if the SUBEXPR has no side effects and matches
+\&            strings of the same length;
+\&        Better optimizations by lookup for constant substrings;
+\&        Better search for constants substrings anchored by $ ;
+.Ve
+.Sp
+Changes in Perl code using RE engine:
+.Sp
+.Vb 5
+\&        More optimizations to s/longer/short/;
+\&        study() was not working;
+\&        /blah/ may be optimized to an analogue of index() if $& $\` $\*(Aq not seen;
+\&        Unneeded copying of matched\-against string removed;
+\&        Only matched part of the string is copying if $\` $\*(Aq were not seen;
+.Ve
+.IP "Many bug fixes" 4
+.IX Item "Many bug fixes"
+Note that only the major bug fixes are listed here.  See \fIChanges\fR for others.
+.Sp
+.Vb 10
+\&        Backtracking might not restore start of $3.
+\&        No feedback if max count for * or + on "complex" subexpression
+\&            was reached, similarly (but at compile time) for {3,34567}
+\&        Primitive restrictions on max count introduced to decrease a 
+\&            possibility of a segfault;
+\&        (ZERO\-LENGTH)* could segfault;
+\&        (ZERO\-LENGTH)* was prohibited;
+\&        Long REs were not allowed;
+\&        /RE/g could skip matches at the same position after a 
+\&          zero\-length match;
+.Ve
+.IP "New regular expression constructs" 4
+.IX Item "New regular expression constructs"
+The following new syntax elements are supported:
+.Sp
+.Vb 8
+\&        (?<=RE)
+\&        (?<!RE)
+\&        (?{ CODE })
+\&        (?i\-x)
+\&        (?i:RE)
+\&        (?(COND)YES_RE|NO_RE)
+\&        (?>RE)
+\&        \ez
+.Ve
+.IP "New operator for precompiled regular expressions" 4
+.IX Item "New operator for precompiled regular expressions"
+See "New \f(CW\*(C`qr//\*(C'\fR operator".
+.IP "Other improvements" 4
+.IX Item "Other improvements"
+.Vb 7
+\&        Better debugging output (possibly with colors),
+\&            even from non\-debugging Perl;
+\&        RE engine code now looks like C, not like assembler;
+\&        Behaviour of RE modifiable by \`use re\*(Aq directive;
+\&        Improved documentation;
+\&        Test suite significantly extended;
+\&        Syntax [:^upper:] etc., reserved inside character classes;
+.Ve
+.IP "Incompatible changes" 4
+.IX Item "Incompatible changes"
+.Vb 4
+\&        (?i) localized inside enclosing group;
+\&        $( is not interpolated into RE any more;
+\&        /RE/g may match at the same position (with non\-zero length)
+\&            after a zero\-length match (bug fix).
+.Ve
+.PP
+See perlre and perlop.
+.SS "Improved \fBmalloc()\fP"
+.IX Subsection "Improved malloc()"
+See banner at the beginning of \f(CW\*(C`malloc.c\*(C'\fR for details.
+.SS "Quicksort is internally implemented"
+.IX Subsection "Quicksort is internally implemented"
+Perl now contains its own highly optimized \fBqsort()\fR routine.  The new \fBqsort()\fR
+is resistant to inconsistent comparison functions, so Perl's \f(CWsort()\fR will
+not provoke coredumps any more when given poorly written sort subroutines.
+(Some C library \f(CWqsort()\fRs that were being used before used to have this
+problem.)  In our testing, the new \f(CWqsort()\fR required the minimal number
+of pair-wise compares on average, among all known \f(CWqsort()\fR implementations.
+.PP
+See \f(CW\*(C`perlfunc/sort\*(C'\fR.
+.SS "Reliable signals"
+.IX Subsection "Reliable signals"
+Perl's signal handling is susceptible to random crashes, because signals
+arrive asynchronously, and the Perl runtime is not reentrant at arbitrary
+times.
+.PP
+However, one experimental implementation of reliable signals is available
+when threads are enabled.  See \f(CW\*(C`Thread::Signal\*(C'\fR.  Also see \fIINSTALL\fR for
+how to build a Perl capable of threads.
+.SS "Reliable stack pointers"
+.IX Subsection "Reliable stack pointers"
+The internals now reallocate the perl stack only at predictable times.
+In particular, magic calls never trigger reallocations of the stack,
+because all reentrancy of the runtime is handled using a "stack of stacks".
+This should improve reliability of cached stack pointers in the internals
+and in XSUBs.
+.SS "More generous treatment of carriage returns"
+.IX Subsection "More generous treatment of carriage returns"
+Perl used to complain if it encountered literal carriage returns in
+scripts.  Now they are mostly treated like whitespace within program text.
+Inside string literals and here documents, literal carriage returns are
+ignored if they occur paired with linefeeds, or get interpreted as whitespace
+if they stand alone.  This behavior means that literal carriage returns
+in files should be avoided.  You can get the older, more compatible (but
+less generous) behavior by defining the preprocessor symbol
+\&\f(CW\*(C`PERL_STRICT_CR\*(C'\fR when building perl.  Of course, all this has nothing
+whatever to do with how escapes like \f(CW\*(C`\er\*(C'\fR are handled within strings.
+.PP
+Note that this doesn't somehow magically allow you to keep all text files
+in DOS format.  The generous treatment only applies to files that perl
+itself parses.  If your C compiler doesn't allow carriage returns in
+files, you may still be unable to build modules that need a C compiler.
+.SS "Memory leaks"
+.IX Subsection "Memory leaks"
+\&\f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`pos\*(C'\fR and \f(CW\*(C`vec\*(C'\fR don't leak memory anymore when used in lvalue
+context.  Many small leaks that impacted applications that embed multiple
+interpreters have been fixed.
+.SS "Better support for multiple interpreters"
+.IX Subsection "Better support for multiple interpreters"
+The build-time option \f(CW\*(C`\-DMULTIPLICITY\*(C'\fR has had many of the details
+reworked.  Some previously global variables that should have been
+per-interpreter now are.  With care, this allows interpreters to call
+each other.  See the \f(CW\*(C`PerlInterp\*(C'\fR extension on CPAN.
+.SS "Behavior of \fBlocal()\fP on array and hash elements is now well-defined"
+.IX Subsection "Behavior of local() on array and hash elements is now well-defined"
+See "Temporary Values via \fBlocal()\fR" in perlsub.
+.ie n .SS """%!"" is transparently tied to the Errno module"
+.el .SS "\f(CW%!\fP is transparently tied to the Errno module"
+.IX Subsection "%! is transparently tied to the Errno module"
+See perlvar, and Errno.
+.SS "Pseudo-hashes are supported"
+.IX Subsection "Pseudo-hashes are supported"
+See perlref.
+.ie n .SS """EXPR foreach EXPR"" is supported"
+.el .SS "\f(CWEXPR foreach EXPR\fP is supported"
+.IX Subsection "EXPR foreach EXPR is supported"
+See perlsyn.
+.SS "Keywords can be globally overridden"
+.IX Subsection "Keywords can be globally overridden"
+See perlsub.
+.ie n .SS "$^E is meaningful on Win32"
+.el .SS "\f(CW$^E\fP is meaningful on Win32"
+.IX Subsection "$^E is meaningful on Win32"
+See perlvar.
+.ie n .SS """foreach (1..1000000)"" optimized"
+.el .SS "\f(CWforeach (1..1000000)\fP optimized"
+.IX Subsection "foreach (1..1000000) optimized"
+\&\f(CW\*(C`foreach (1..1000000)\*(C'\fR is now optimized into a counting loop.  It does
+not try to allocate a 1000000\-size list anymore.
+.ie n .SS """Foo::"" can be used as implicitly quoted package name"
+.el .SS "\f(CWFoo::\fP can be used as implicitly quoted package name"
+.IX Subsection "Foo:: can be used as implicitly quoted package name"
+Barewords caused unintuitive behavior when a subroutine with the same
+name as a package happened to be defined.  Thus, \f(CW\*(C`new Foo @args\*(C'\fR,
+use the result of the call to \f(CWFoo()\fR instead of \f(CW\*(C`Foo\*(C'\fR being treated
+as a literal.  The recommended way to write barewords in the indirect
+object slot is \f(CW\*(C`new Foo:: @args\*(C'\fR.  Note that the method \f(CWnew()\fR is
+called with a first argument of \f(CW\*(C`Foo\*(C'\fR, not \f(CW\*(C`Foo::\*(C'\fR when you do that.
+.ie n .SS """exists $Foo::{Bar::}"" tests existence of a package"
+.el .SS "\f(CWexists $Foo::{Bar::}\fP tests existence of a package"
+.IX Subsection "exists $Foo::{Bar::} tests existence of a package"
+It was impossible to test for the existence of a package without
+actually creating it before.  Now \f(CW\*(C`exists $Foo::{Bar::}\*(C'\fR can be
+used to test if the \f(CW\*(C`Foo::Bar\*(C'\fR namespace has been created.
+.SS "Better locale support"
+.IX Subsection "Better locale support"
+See perllocale.
+.SS "Experimental support for 64\-bit platforms"
+.IX Subsection "Experimental support for 64-bit platforms"
+Perl5 has always had 64\-bit support on systems with 64\-bit longs.
+Starting with 5.005, the beginnings of experimental support for systems
+with 32\-bit long and 64\-bit 'long long' integers has been added.
+If you add \-DUSE_LONG_LONG to your ccflags in config.sh (or manually
+define it in perl.h) then perl will be built with 'long long' support.
+There will be many compiler warnings, and the resultant perl may not
+work on all systems.  There are many other issues related to
+third-party extensions and libraries.  This option exists to allow
+people to work on those issues.
+.SS "\fBprototype()\fP returns useful results on builtins"
+.IX Subsection "prototype() returns useful results on builtins"
+See "prototype" in perlfunc.
+.SS "Extended support for exception handling"
+.IX Subsection "Extended support for exception handling"
+\&\f(CWdie()\fR now accepts a reference value, and \f(CW$@\fR gets set to that
+value in exception traps.  This makes it possible to propagate
+exception objects.  This is an undocumented \fBexperimental\fR feature.
+.SS "Re-blessing in \fBDESTROY()\fP supported for chaining \fBDESTROY()\fP methods"
+.IX Subsection "Re-blessing in DESTROY() supported for chaining DESTROY() methods"
+See "Destructors" in perlobj.
+.ie n .SS "All ""printf"" format conversions are handled internally"
+.el .SS "All \f(CWprintf\fP format conversions are handled internally"
+.IX Subsection "All printf format conversions are handled internally"
+See "printf" in perlfunc.
+.ie n .SS "New ""INIT"" keyword"
+.el .SS "New \f(CWINIT\fP keyword"
+.IX Subsection "New INIT keyword"
+\&\f(CW\*(C`INIT\*(C'\fR subs are like \f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`END\*(C'\fR, but they get run just before
+the perl runtime begins execution.  e.g., the Perl Compiler makes use of
+\&\f(CW\*(C`INIT\*(C'\fR blocks to initialize and resolve pointers to XSUBs.
+.ie n .SS "New ""lock"" keyword"
+.el .SS "New \f(CWlock\fP keyword"
+.IX Subsection "New lock keyword"
+The \f(CW\*(C`lock\*(C'\fR keyword is the fundamental synchronization primitive
+in threaded perl.  When threads are not enabled, it is currently a noop.
+.PP
+To minimize impact on source compatibility this keyword is "weak", i.e., any
+user-defined subroutine of the same name overrides it, unless a \f(CW\*(C`use Thread\*(C'\fR
+has been seen.
+.ie n .SS "New ""qr//"" operator"
+.el .SS "New \f(CWqr//\fP operator"
+.IX Subsection "New qr// operator"
+The \f(CW\*(C`qr//\*(C'\fR operator, which is syntactically similar to the other quote-like
+operators, is used to create precompiled regular expressions.  This compiled
+form can now be explicitly passed around in variables, and interpolated in
+other regular expressions.  See perlop.
+.ie n .SS """our"" is now a reserved word"
+.el .SS "\f(CWour\fP is now a reserved word"
+.IX Subsection "our is now a reserved word"
+Calling a subroutine with the name \f(CW\*(C`our\*(C'\fR will now provoke a warning when
+using the \f(CW\*(C`\-w\*(C'\fR switch.
+.SS "Tied arrays are now fully supported"
+.IX Subsection "Tied arrays are now fully supported"
+See Tie::Array.
+.SS "Tied handles support is better"
+.IX Subsection "Tied handles support is better"
+Several missing hooks have been added.  There is also a new base class for
+TIEARRAY implementations.  See Tie::Array.
+.SS "4th argument to substr"
+.IX Subsection "4th argument to substr"
+\&\fBsubstr()\fR can now both return and replace in one operation.  The optional
+4th argument is the replacement string.  See "substr" in perlfunc.
+.SS "Negative LENGTH argument to splice"
+.IX Subsection "Negative LENGTH argument to splice"
+\&\fBsplice()\fR with a negative LENGTH argument now work similar to what the
+LENGTH did for \fBsubstr()\fR.  Previously a negative LENGTH was treated as
+0.  See "splice" in perlfunc.
+.SS "Magic lvalues are now more magical"
+.IX Subsection "Magic lvalues are now more magical"
+When you say something like \f(CW\*(C`substr($x, 5) = "hi"\*(C'\fR, the scalar returned
+by \fBsubstr()\fR is special, in that any modifications to it affect \f(CW$x\fR.
+(This is called a 'magic lvalue' because an 'lvalue' is something on
+the left side of an assignment.)  Normally, this is exactly what you
+would expect to happen, but Perl uses the same magic if you use \fBsubstr()\fR,
+\&\fBpos()\fR, or \fBvec()\fR in a context where they might be modified, like taking
+a reference with \f(CW\*(C`\e\*(C'\fR or as an argument to a sub that modifies \f(CW@_\fR.
+In previous versions, this 'magic' only went one way, but now changes
+to the scalar the magic refers to ($x in the above example) affect the
+magic lvalue too. For instance, this code now acts differently:
+.PP
+.Vb 6
+\&    $x = "hello";
+\&    sub printit {
+\&        $x = "g\*(Aqbye";
+\&        print $_[0], "\en";
+\&    }
+\&    printit(substr($x, 0, 5));
+.Ve
+.PP
+In previous versions, this would print "hello", but it now prints "g'bye".
+.SS "<> now reads in records"
+.IX Subsection "<> now reads in records"
+If \f(CW$/\fR is a reference to an integer, or a scalar that holds an integer,
+<> will read in records instead of lines. For more info, see
+"$/" in perlvar.
+.SH "Supported Platforms"
+.IX Header "Supported Platforms"
+Configure has many incremental improvements.  Site-wide policy for building
+perl can now be made persistent, via Policy.sh.  Configure also records
+the command-line arguments used in \fIconfig.sh\fR.
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+BeOS is now supported.  See \fIREADME.beos\fR.
+.PP
+DOS is now supported under the DJGPP tools.  See \fIREADME.dos\fR (installed 
+as perldos on some systems).
+.PP
+MiNT is now supported.  See \fIREADME.mint\fR.
+.PP
+MPE/iX is now supported.  See README.mpeix.
+.PP
+MVS (aka OS390, aka Open Edition) is now supported.  See \fIREADME.os390\fR 
+(installed as perlos390 on some systems).
+.PP
+Stratus VOS is now supported.  See \fIREADME.vos\fR.
+.SS "Changes in existing support"
+.IX Subsection "Changes in existing support"
+Win32 support has been vastly enhanced.  Support for Perl Object, a C++
+encapsulation of Perl.  GCC and EGCS are now supported on Win32.
+See \fIREADME.win32\fR, aka perlwin32.
+.PP
+VMS configuration system has been rewritten.  See \fIREADME.vms\fR (installed 
+as \fIREADME_vms\fR on some systems).
+.PP
+The hints files for most Unix platforms have seen incremental improvements.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules"
+.IX Subsection "New Modules"
+.IP B 4
+.IX Item "B"
+Perl compiler and tools.  See B.
+.IP Data::Dumper 4
+.IX Item "Data::Dumper"
+A module to pretty print Perl data.  See Data::Dumper.
+.IP Dumpvalue 4
+.IX Item "Dumpvalue"
+A module to dump perl values to the screen. See Dumpvalue.
+.IP Errno 4
+.IX Item "Errno"
+A module to look up errors more conveniently.  See Errno.
+.IP File::Spec 4
+.IX Item "File::Spec"
+A portable API for file operations.
+.IP ExtUtils::Installed 4
+.IX Item "ExtUtils::Installed"
+Query and manage installed modules.
+.IP ExtUtils::Packlist 4
+.IX Item "ExtUtils::Packlist"
+Manipulate .packlist files.
+.IP Fatal 4
+.IX Item "Fatal"
+Make functions/builtins succeed or die.
+.IP IPC::SysV 4
+.IX Item "IPC::SysV"
+Constants and other support infrastructure for System V IPC operations
+in perl.
+.IP Test 4
+.IX Item "Test"
+A framework for writing test suites.
+.IP Tie::Array 4
+.IX Item "Tie::Array"
+Base class for tied arrays.
+.IP Tie::Handle 4
+.IX Item "Tie::Handle"
+Base class for tied handles.
+.IP Thread 4
+.IX Item "Thread"
+Perl thread creation, manipulation, and support.
+.IP attrs 4
+.IX Item "attrs"
+Set subroutine attributes.
+.IP fields 4
+.IX Item "fields"
+Compile-time class fields.
+.IP re 4
+.IX Item "re"
+Various pragmata to control behavior of regular expressions.
+.SS "Changes in existing modules"
+.IX Subsection "Changes in existing modules"
+.IP Benchmark 4
+.IX Item "Benchmark"
+You can now run tests for \fIx\fR seconds instead of guessing the right
+number of tests to run.
+.Sp
+Keeps better time.
+.IP Carp 4
+.IX Item "Carp"
+Carp has a new function \fBcluck()\fR. \fBcluck()\fR warns, like \fBcarp()\fR, but also adds
+a stack backtrace to the error message, like \fBconfess()\fR.
+.IP CGI 4
+.IX Item "CGI"
+CGI has been updated to version 2.42.
+.IP Fcntl 4
+.IX Item "Fcntl"
+More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
+large (more than 4G) file access (the 64\-bit support is not yet
+working, though, so no need to get overly excited), Free/Net/OpenBSD
+locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and
+O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
+.IP Math::Complex 4
+.IX Item "Math::Complex"
+The accessors methods Re, Im, arg, abs, rho, theta, methods can
+($z\->\fBRe()\fR) now also act as mutators ($z\->\fBRe\fR\|(3)).
+.IP Math::Trig 4
+.IX Item "Math::Trig"
+A little bit of radial trigonometry (cylindrical and spherical) added,
+for example the great circle distance.
+.IP POSIX 4
+.IX Item "POSIX"
+POSIX now has its own platform-specific hints files.
+.IP DB_File 4
+.IX Item "DB_File"
+DB_File supports version 2.x of Berkeley DB.  See \f(CW\*(C`ext/DB_File/Changes\*(C'\fR.
+.IP MakeMaker 4
+.IX Item "MakeMaker"
+MakeMaker now supports writing empty makefiles, provides a way to
+specify that site \fBumask()\fR policy should be honored.  There is also
+better support for manipulation of .packlist files, and getting
+information about installed modules.
+.Sp
+Extensions that have both architecture-dependent and
+architecture-independent files are now always installed completely in
+the architecture-dependent locations.  Previously, the shareable parts
+were shared both across architectures and across perl versions and were
+therefore liable to be overwritten with newer versions that might have
+subtle incompatibilities.
+.IP CPAN 4
+.IX Item "CPAN"
+See perlmodinstall and CPAN.
+.IP Cwd 4
+.IX Item "Cwd"
+Cwd::cwd is faster on most platforms.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\&\f(CW\*(C`h2ph\*(C'\fR and related utilities have been vastly overhauled.
+.PP
+\&\f(CW\*(C`perlcc\*(C'\fR, a new experimental front end for the compiler is available.
+.PP
+The crude GNU \f(CW\*(C`configure\*(C'\fR emulator is now called \f(CW\*(C`configure.gnu\*(C'\fR to
+avoid trampling on \f(CW\*(C`Configure\*(C'\fR under case-insensitive filesystems.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR used to be rather slow.  The slower features are now optional.
+In particular, case-insensitive searches need the \f(CW\*(C`\-i\*(C'\fR switch, and
+recursive searches need \f(CW\*(C`\-r\*(C'\fR.  You can set these switches in the
+\&\f(CW\*(C`PERLDOC\*(C'\fR environment variable to get the old behavior.
+.SH "Documentation Changes"
+.IX Header "Documentation Changes"
+Config.pm now has a glossary of variables.
+.PP
+\&\fIPorting/patching.pod\fR has detailed instructions on how to create and
+submit patches for perl.
+.PP
+perlport specifies guidelines on how to write portably.
+.PP
+perlmodinstall describes how to fetch and install modules from \f(CW\*(C`CPAN\*(C'\fR
+sites.
+.PP
+Some more Perl traps are documented now.  See perltrap.
+.PP
+perlopentut gives a tutorial on using \fBopen()\fR.
+.PP
+perlreftut gives a tutorial on references.
+.PP
+perlthrtut gives a tutorial on threads.
+.SH "New Diagnostics"
+.IX Header "New Diagnostics"
+.IP "Ambiguous call resolved as CORE::%s(), qualify as such or use &" 4
+.IX Item "Ambiguous call resolved as CORE::%s(), qualify as such or use &"
+(W) A subroutine you have declared has the same name as a Perl keyword,
+and you have used the name without qualification for calling one or the
+other.  Perl decided to call the builtin because the subroutine is
+not imported.
+.Sp
+To force interpretation as a subroutine call, either put an ampersand
+before the subroutine name, or qualify the name with its package.
+Alternatively, you can import the subroutine (or pretend that it's
+imported with the \f(CW\*(C`use subs\*(C'\fR pragma).
+.Sp
+To silently interpret it as the Perl operator, use the \f(CW\*(C`CORE::\*(C'\fR prefix
+on the operator (e.g. \f(CWCORE::log($x)\fR) or by declaring the subroutine
+to be an object method (see "attrs").
+.IP "Bad index while coercing array into hash" 4
+.IX Item "Bad index while coercing array into hash"
+(F) The index looked up in the hash found as the 0'th element of a
+pseudo-hash is not legal.  Index values must be at 1 or greater.
+See perlref.
+.IP "Bareword ""%s"" refers to nonexistent package" 4
+.IX Item "Bareword ""%s"" refers to nonexistent package"
+(W) You used a qualified bareword of the form \f(CW\*(C`Foo::\*(C'\fR, but
+the compiler saw no other uses of that namespace before that point.
+Perhaps you need to predeclare a package?
+.IP "Can't call method ""%s"" on an undefined value" 4
+.IX Item "Can't call method ""%s"" on an undefined value"
+(F) You used the syntax of a method call, but the slot filled by the
+object reference or package name contains an undefined value.
+Something like this will reproduce the error:
+.Sp
+.Vb 3
+\&    $BADREF = 42;
+\&    process $BADREF 1,2,3;
+\&    $BADREF\->process(1,2,3);
+.Ve
+.IP "Can't check filesystem of script ""%s"" for nosuid" 4
+.IX Item "Can't check filesystem of script ""%s"" for nosuid"
+(P) For some reason you can't check the filesystem of the script for nosuid.
+.IP "Can't coerce array into hash" 4
+.IX Item "Can't coerce array into hash"
+(F) You used an array where a hash was expected, but the array has no
+information on how to map from keys to array indices.  You can do that
+only with arrays that have a hash reference at index 0.
+.IP "Can't goto subroutine from an eval-string" 4
+.IX Item "Can't goto subroutine from an eval-string"
+(F) The "goto subroutine" call can't be used to jump out of an eval "string".
+(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)
+.IP "Can't localize pseudo-hash element" 4
+.IX Item "Can't localize pseudo-hash element"
+(F) You said something like \f(CW\*(C`local $ar\->{\*(Aqkey\*(Aq}\*(C'\fR, where \f(CW$ar\fR is
+a reference to a pseudo-hash.  That hasn't been implemented yet, but
+you can get a similar effect by localizing the corresponding array
+element directly: \f(CW\*(C`local $ar\->[$ar\->[0]{\*(Aqkey\*(Aq}]\*(C'\fR.
+.IP "Can't use %%! because Errno.pm is not available" 4
+.IX Item "Can't use %%! because Errno.pm is not available"
+(F) The first time the %! hash is used, perl automatically loads the
+Errno.pm module. The Errno module is expected to tie the %! hash to
+provide symbolic names for \f(CW$!\fR errno values.
+.IP "Cannot find an opnumber for ""%s""" 4
+.IX Item "Cannot find an opnumber for ""%s"""
+(F) A string of a form \f(CW\*(C`CORE::word\*(C'\fR was given to \fBprototype()\fR, but
+there is no builtin with the name \f(CW\*(C`word\*(C'\fR.
+.IP "Character class syntax [. .] is reserved for future extensions" 4
+.IX Item "Character class syntax [. .] is reserved for future extensions"
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[." and ending with ".]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\e[." and ".\e]".
+.IP "Character class syntax [: :] is reserved for future extensions" 4
+.IX Item "Character class syntax [: :] is reserved for future extensions"
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\e[:" and ":\e]".
+.IP "Character class syntax [= =] is reserved for future extensions" 4
+.IX Item "Character class syntax [= =] is reserved for future extensions"
+(W) Within regular expression character classes ([]) the syntax
+beginning with "[=" and ending with "=]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\e[=" and "=\e]".
+.ie n .IP "%s: Eval-group in insecure regular expression" 4
+.el .IP "\f(CW%s:\fR Eval-group in insecure regular expression" 4
+.IX Item "%s: Eval-group in insecure regular expression"
+(F) Perl detected tainted data when trying to compile a regular expression
+that contains the \f(CW\*(C`(?{ ... })\*(C'\fR zero-width assertion, which is unsafe.
+See "(?{ code })" in perlre, and perlsec.
+.ie n .IP "%s: Eval-group not allowed, use re 'eval'" 4
+.el .IP "\f(CW%s:\fR Eval-group not allowed, use re 'eval'" 4
+.IX Item "%s: Eval-group not allowed, use re 'eval'"
+(F) A regular expression contained the \f(CW\*(C`(?{ ... })\*(C'\fR zero-width assertion,
+but that construct is only allowed when the \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR pragma is
+in effect.  See "(?{ code })" in perlre.
+.ie n .IP "%s: Eval-group not allowed at run time" 4
+.el .IP "\f(CW%s:\fR Eval-group not allowed at run time" 4
+.IX Item "%s: Eval-group not allowed at run time"
+(F) Perl tried to compile a regular expression containing the \f(CW\*(C`(?{ ... })\*(C'\fR
+zero-width assertion at run time, as it would when the pattern contains
+interpolated values.  Since that is a security risk, it is not allowed.
+If you insist, you may still do this by explicitly building the pattern
+from an interpolated string at run time and using that in an \fBeval()\fR.
+See "(?{ code })" in perlre.
+.IP "Explicit blessing to '' (assuming package main)" 4
+.IX Item "Explicit blessing to '' (assuming package main)"
+(W) You are blessing a reference to a zero length string.  This has
+the effect of blessing the reference into the package main.  This is
+usually not what you want.  Consider providing a default target
+package, e.g. bless($ref, \f(CW$p\fR || 'MyPackage');
+.IP "Illegal hex digit ignored" 4
+.IX Item "Illegal hex digit ignored"
+(W) You may have tried to use a character other than 0 \- 9 or A \- F in a
+hexadecimal number.  Interpretation of the hexadecimal number stopped
+before the illegal character.
+.IP "No such array field" 4
+.IX Item "No such array field"
+(F) You tried to access an array as a hash, but the field name used is
+not defined.  The hash at index 0 should map all valid field names to
+array indices for that to work.
+.ie n .IP "No such field ""%s"" in variable %s of type %s" 4
+.el .IP "No such field ""%s"" in variable \f(CW%s\fR of type \f(CW%s\fR" 4
+.IX Item "No such field ""%s"" in variable %s of type %s"
+(F) You tried to access a field of a typed variable where the type
+does not know about the field name.  The field names are looked up in
+the \f(CW%FIELDS\fR hash in the type package at compile time.  The \f(CW%FIELDS\fR hash
+is usually set up with the 'fields' pragma.
+.IP "Out of memory during ridiculously large request" 4
+.IX Item "Out of memory during ridiculously large request"
+(F) You can't allocate more than 2^31+"small amount" bytes.  This error
+is most likely to be caused by a typo in the Perl program. e.g., \f(CW$arr[time]\fR
+instead of \f(CW$arr[$time]\fR.
+.IP "Range iterator outside integer range" 4
+.IX Item "Range iterator outside integer range"
+(F) One (or both) of the numeric arguments to the range operator ".."
+are outside the range which can be represented by integers internally.
+One possible workaround is to force Perl to use magical string
+increment by prepending "0" to your numbers.
+.ie n .IP "Recursive inheritance detected while looking for method '%s' %s" 4
+.el .IP "Recursive inheritance detected while looking for method '%s' \f(CW%s\fR" 4
+.IX Item "Recursive inheritance detected while looking for method '%s' %s"
+(F) More than 100 levels of inheritance were encountered while invoking a
+method.  Probably indicates an unintended loop in your inheritance hierarchy.
+.IP "Reference found where even-sized list expected" 4
+.IX Item "Reference found where even-sized list expected"
+(W) You gave a single reference where Perl was expecting a list with
+an even number of elements (for assignment to a hash). This
+usually means that you used the anon hash constructor when you meant 
+to use parens. In any case, a hash requires key/value \fBpairs\fR.
+.Sp
+.Vb 4
+\&    %hash = { one => 1, two => 2, };   # WRONG
+\&    %hash = [ qw/ an anon array / ];   # WRONG
+\&    %hash = ( one => 1, two => 2, );   # right
+\&    %hash = qw( one 1 two 2 );                 # also fine
+.Ve
+.IP "Undefined value assigned to typeglob" 4
+.IX Item "Undefined value assigned to typeglob"
+(W) An undefined value was assigned to a typeglob, a la \f(CW\*(C`*foo = undef\*(C'\fR.
+This does nothing.  It's possible that you really mean \f(CW\*(C`undef *foo\*(C'\fR.
+.IP "Use of reserved word ""%s"" is deprecated" 4
+.IX Item "Use of reserved word ""%s"" is deprecated"
+(D) The indicated bareword is a reserved word.  Future versions of perl
+may use it as a keyword, so you're better off either explicitly quoting
+the word in a manner appropriate for its context of use, or using a
+different name altogether.  The warning can be suppressed for subroutine
+names by either adding a \f(CW\*(C`&\*(C'\fR prefix, or using a package qualifier,
+e.g. \f(CW&our()\fR, or \f(CWFoo::our()\fR.
+.IP "perl: warning: Setting locale failed." 4
+.IX Item "perl: warning: Setting locale failed."
+(S) The whole warning message will look something like:
+.Sp
+.Vb 6
+\&       perl: warning: Setting locale failed.
+\&       perl: warning: Please check that your locale settings:
+\&               LC_ALL = "En_US",
+\&               LANG = (unset)
+\&           are supported and installed on your system.
+\&       perl: warning: Falling back to the standard locale ("C").
+.Ve
+.Sp
+Exactly what were the failed locale settings varies.  In the above the
+settings were that the LC_ALL was "En_US" and the LANG had no value.
+This error means that Perl detected that you and/or your system
+administrator have set up the so-called variable system but Perl could
+not use those settings.  This was not dead serious, fortunately: there
+is a "default locale" called "C" that Perl can and will use, the
+script will be run.  Before you really fix the problem, however, you
+will get the same error message each time you run Perl.  How to really
+fix the problem can be found in "LOCALE PROBLEMS" in perllocale.
+.SH "Obsolete Diagnostics"
+.IX Header "Obsolete Diagnostics"
+.IP "Can't \fBmktemp()\fR" 4
+.IX Item "Can't mktemp()"
+(F) The \fBmktemp()\fR routine failed for some reason while trying to process
+a \fB\-e\fR switch.  Maybe your /tmp partition is full, or clobbered.
+.Sp
+Removed because \fB\-e\fR doesn't use temporary files any more.
+.ie n .IP "Can't write to temp file for \fB\-e\fR: %s" 4
+.el .IP "Can't write to temp file for \fB\-e\fR: \f(CW%s\fR" 4
+.IX Item "Can't write to temp file for -e: %s"
+(F) The write routine failed for some reason while trying to process
+a \fB\-e\fR switch.  Maybe your /tmp partition is full, or clobbered.
+.Sp
+Removed because \fB\-e\fR doesn't use temporary files any more.
+.IP "Cannot open temporary file" 4
+.IX Item "Cannot open temporary file"
+(F) The create routine failed for some reason while trying to process
+a \fB\-e\fR switch.  Maybe your /tmp partition is full, or clobbered.
+.Sp
+Removed because \fB\-e\fR doesn't use temporary files any more.
+.IP "regexp too big" 4
+.IX Item "regexp too big"
+(F) The current implementation of regular expressions uses shorts as
+address offsets within a string.  Unfortunately this means that if
+the regular expression compiles to longer than 32767, it'll blow up.
+Usually when you want a regular expression this big, there is a better
+way to do it with multiple statements.  See perlre.
+.SH "Configuration Changes"
+.IX Header "Configuration Changes"
+You can use "Configure \-Uinstallusrbinperl" which causes installperl
+to skip installing perl also as /usr/bin/perl.  This is useful if you
+prefer not to modify /usr/bin for some reason or another but harmful
+because many scripts assume to find Perl in /usr/bin/perl.
+.SH BUGS
+.IX Header "BUGS"
+If you find what you think is a bug, you might check the headers of
+recently posted articles in the comp.lang.perl.misc newsgroup.
+There may also be information at http://www.perl.com/perl/ , the Perl
+Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Make sure you trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to <\fIperlbug@perl.com\fR> to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Written by Gurusamy Sarathy <\fIgsar@activestate.com\fR>, with many contributions
+from The Perl Porters.
+.PP
+Send omissions or corrections to <\fIperlbug@perl.com\fR>.
diff --git a/upstream/mageia-cauldron/man1/perl5100delta.1 b/upstream/mageia-cauldron/man1/perl5100delta.1
new file mode 100644
index 00000000..d835a05c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5100delta.1
@@ -0,0 +1,1500 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5100DELTA 1"
+.TH PERL5100DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5100delta \- what is new for perl 5.10.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the differences between the 5.8.8 release and
+the 5.10.0 release.
+.PP
+Many of the bug fixes in 5.10.0 were already seen in the 5.8.X maintenance
+releases; they are not duplicated here and are documented in the set of
+man pages named perl58[1\-8]?delta.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS "The ""feature"" pragma"
+.el .SS "The \f(CWfeature\fP pragma"
+.IX Subsection "The feature pragma"
+The \f(CW\*(C`feature\*(C'\fR pragma is used to enable new syntax that would break Perl's
+backwards-compatibility with older releases of the language. It's a lexical
+pragma, like \f(CW\*(C`strict\*(C'\fR or \f(CW\*(C`warnings\*(C'\fR.
+.PP
+Currently the following new features are available: \f(CW\*(C`switch\*(C'\fR (adds a
+switch statement), \f(CW\*(C`say\*(C'\fR (adds a \f(CW\*(C`say\*(C'\fR built-in function), and \f(CW\*(C`state\*(C'\fR
+(adds a \f(CW\*(C`state\*(C'\fR keyword for declaring "static" variables). Those
+features are described in their own sections of this document.
+.PP
+The \f(CW\*(C`feature\*(C'\fR pragma is also implicitly loaded when you require a minimal
+perl version (with the \f(CW\*(C`use VERSION\*(C'\fR construct) greater than, or equal
+to, 5.9.5. See feature for details.
+.SS "New \fB\-E\fP command-line switch"
+.IX Subsection "New -E command-line switch"
+\&\fB\-E\fR is equivalent to \fB\-e\fR, but it implicitly enables all
+optional features (like \f(CW\*(C`use feature ":5.10"\*(C'\fR).
+.SS "Defined-or operator"
+.IX Subsection "Defined-or operator"
+A new operator \f(CW\*(C`//\*(C'\fR (defined-or) has been implemented.
+The following expression:
+.PP
+.Vb 1
+\&    $a // $b
+.Ve
+.PP
+is merely equivalent to
+.PP
+.Vb 1
+\&   defined $a ? $a : $b
+.Ve
+.PP
+and the statement
+.PP
+.Vb 1
+\&   $c //= $d;
+.Ve
+.PP
+can now be used instead of
+.PP
+.Vb 1
+\&   $c = $d unless defined $c;
+.Ve
+.PP
+The \f(CW\*(C`//\*(C'\fR operator has the same precedence and associativity as \f(CW\*(C`||\*(C'\fR.
+Special care has been taken to ensure that this operator Do What You Mean
+while not breaking old code, but some edge cases involving the empty
+regular expression may now parse differently.  See perlop for
+details.
+.SS "Switch and Smart Match operator"
+.IX Subsection "Switch and Smart Match operator"
+Perl 5 now has a switch statement. It's available when \f(CWuse feature
+\&\*(Aqswitch\*(Aq\fR is in effect. This feature introduces three new keywords,
+\&\f(CW\*(C`given\*(C'\fR, \f(CW\*(C`when\*(C'\fR, and \f(CW\*(C`default\*(C'\fR:
+.PP
+.Vb 6
+\&    given ($foo) {
+\&        when (/^abc/) { $abc = 1; }
+\&        when (/^def/) { $def = 1; }
+\&        when (/^xyz/) { $xyz = 1; }
+\&        default { $nothing = 1; }
+\&    }
+.Ve
+.PP
+A more complete description of how Perl matches the switch variable
+against the \f(CW\*(C`when\*(C'\fR conditions is given in "Switch statements" in perlsyn.
+.PP
+This kind of match is called \fIsmart match\fR, and it's also possible to use
+it outside of switch statements, via the new \f(CW\*(C`~~\*(C'\fR operator. See
+"Smart matching in detail" in perlsyn.
+.PP
+This feature was contributed by Robin Houston.
+.SS "Regular expressions"
+.IX Subsection "Regular expressions"
+.IP "Recursive Patterns" 4
+.IX Item "Recursive Patterns"
+It is now possible to write recursive patterns without using the \f(CW\*(C`(??{})\*(C'\fR
+construct. This new way is more efficient, and in many cases easier to
+read.
+.Sp
+Each capturing parenthesis can now be treated as an independent pattern
+that can be entered by using the \f(CW\*(C`(?PARNO)\*(C'\fR syntax (\f(CW\*(C`PARNO\*(C'\fR standing for
+"parenthesis number"). For example, the following pattern will match
+nested balanced angle brackets:
+.Sp
+.Vb 10
+\&    /
+\&     ^                      # start of line
+\&     (                      # start capture buffer 1
+\&        <                   #   match an opening angle bracket
+\&        (?:                 #   match one of:
+\&            (?>             #     don\*(Aqt backtrack over the inside of this group
+\&                [^<>]+      #       one or more non angle brackets
+\&            )               #     end non backtracking group
+\&        |                   #     ... or ...
+\&            (?1)            #     recurse to bracket 1 and try it again
+\&        )*                  #   0 or more times.
+\&        >                   #   match a closing angle bracket
+\&     )                      # end capture buffer one
+\&     $                      # end of line
+\&    /x
+.Ve
+.Sp
+PCRE users should note that Perl's recursive regex feature allows
+backtracking into a recursed pattern, whereas in PCRE the recursion is
+atomic or "possessive" in nature.  As in the example above, you can
+add (?>) to control this selectively.  (Yves Orton)
+.IP "Named Capture Buffers" 4
+.IX Item "Named Capture Buffers"
+It is now possible to name capturing parenthesis in a pattern and refer to
+the captured contents by name. The naming syntax is \f(CW\*(C`(?<NAME>....)\*(C'\fR.
+It's possible to backreference to a named buffer with the \f(CW\*(C`\ek<NAME>\*(C'\fR
+syntax. In code, the new magical hashes \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR can be used to
+access the contents of the capture buffers.
+.Sp
+Thus, to replace all doubled chars with a single copy, one could write
+.Sp
+.Vb 1
+\&    s/(?<letter>.)\ek<letter>/$+{letter}/g
+.Ve
+.Sp
+Only buffers with defined contents will be "visible" in the \f(CW\*(C`%+\*(C'\fR hash, so
+it's possible to do something like
+.Sp
+.Vb 3
+\&    foreach my $name (keys %+) {
+\&        print "content of buffer \*(Aq$name\*(Aq is $+{$name}\en";
+\&    }
+.Ve
+.Sp
+The \f(CW\*(C`%\-\*(C'\fR hash is a bit more complete, since it will contain array refs
+holding values from all capture buffers similarly named, if there should
+be many of them.
+.Sp
+\&\f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR are implemented as tied hashes through the new module
+\&\f(CW\*(C`Tie::Hash::NamedCapture\*(C'\fR.
+.Sp
+Users exposed to the .NET regex engine will find that the perl
+implementation differs in that the numerical ordering of the buffers
+is sequential, and not "unnamed first, then named". Thus in the pattern
+.Sp
+.Vb 1
+\&   /(A)(?<B>B)(C)(?<D>D)/
+.Ve
+.Sp
+\&\f(CW$1\fR will be 'A', \f(CW$2\fR will be 'B', \f(CW$3\fR will be 'C' and \f(CW$4\fR will be 'D' and not
+\&\f(CW$1\fR is 'A', \f(CW$2\fR is 'C' and \f(CW$3\fR is 'B' and \f(CW$4\fR is 'D' that a .NET programmer
+would expect. This is considered a feature. :\-) (Yves Orton)
+.IP "Possessive Quantifiers" 4
+.IX Item "Possessive Quantifiers"
+Perl now supports the "possessive quantifier" syntax of the "atomic match"
+pattern. Basically a possessive quantifier matches as much as it can and never
+gives any back. Thus it can be used to control backtracking. The syntax is
+similar to non-greedy matching, except instead of using a '?' as the modifier
+the '+' is used. Thus \f(CW\*(C`?+\*(C'\fR, \f(CW\*(C`*+\*(C'\fR, \f(CW\*(C`++\*(C'\fR, \f(CW\*(C`{min,max}+\*(C'\fR are now legal
+quantifiers. (Yves Orton)
+.IP "Backtracking control verbs" 4
+.IX Item "Backtracking control verbs"
+The regex engine now supports a number of special-purpose backtrack
+control verbs: (*THEN), (*PRUNE), (*MARK), (*SKIP), (*COMMIT), (*FAIL)
+and (*ACCEPT). See perlre for their descriptions. (Yves Orton)
+.IP "Relative backreferences" 4
+.IX Item "Relative backreferences"
+A new syntax \f(CW\*(C`\eg{N}\*(C'\fR or \f(CW\*(C`\egN\*(C'\fR where "N" is a decimal integer allows a
+safer form of back-reference notation as well as allowing relative
+backreferences. This should make it easier to generate and embed patterns
+that contain backreferences. See "Capture buffers" in perlre. (Yves Orton)
+.ie n .IP """\eK"" escape" 4
+.el .IP "\f(CW\eK\fR escape" 4
+.IX Item "K escape"
+The functionality of Jeff Pinyan's module Regexp::Keep has been added to
+the core. In regular expressions you can now use the special escape \f(CW\*(C`\eK\*(C'\fR
+as a way to do something like floating length positive lookbehind. It is
+also useful in substitutions like:
+.Sp
+.Vb 1
+\&  s/(foo)bar/$1/g
+.Ve
+.Sp
+that can now be converted to
+.Sp
+.Vb 1
+\&  s/foo\eKbar//g
+.Ve
+.Sp
+which is much more efficient. (Yves Orton)
+.IP "Vertical and horizontal whitespace, and linebreak" 4
+.IX Item "Vertical and horizontal whitespace, and linebreak"
+Regular expressions now recognize the \f(CW\*(C`\ev\*(C'\fR and \f(CW\*(C`\eh\*(C'\fR escapes that match
+vertical and horizontal whitespace, respectively. \f(CW\*(C`\eV\*(C'\fR and \f(CW\*(C`\eH\*(C'\fR
+logically match their complements.
+.Sp
+\&\f(CW\*(C`\eR\*(C'\fR matches a generic linebreak, that is, vertical whitespace, plus
+the multi-character sequence \f(CW"\ex0D\ex0A"\fR.
+.IP "Optional pre-match and post-match captures with the /p flag" 4
+.IX Item "Optional pre-match and post-match captures with the /p flag"
+There is a new flag \f(CW\*(C`/p\*(C'\fR for regular expressions.  Using this
+makes the engine preserve a copy of the part of the matched string before
+the matching substring to the new special variable \f(CW\*(C`${^PREMATCH}\*(C'\fR, the
+part after the matching substring to \f(CW\*(C`${^POSTMATCH}\*(C'\fR, and the matched
+substring itself to \f(CW\*(C`${^MATCH}\*(C'\fR.
+.Sp
+Perl is still able to store these substrings to the special variables
+\&\f(CW\*(C`$\`\*(C'\fR, \f(CW\*(C`$\*(Aq\*(C'\fR, \f(CW$&\fR, but using these variables anywhere in the program
+adds a penalty to all regular expression matches, whereas if you use
+the \f(CW\*(C`/p\*(C'\fR flag and the new special variables instead, you pay only for
+the regular expressions where the flag is used.
+.Sp
+For more detail on the new variables, see perlvar; for the use of
+the regular expression flag, see perlop and perlre.
+.ie n .SS say()
+.el .SS \f(CWsay()\fP
+.IX Subsection "say()"
+\&\fBsay()\fR is a new built-in, only available when \f(CW\*(C`use feature \*(Aqsay\*(Aq\*(C'\fR is in
+effect, that is similar to \fBprint()\fR, but that implicitly appends a newline
+to the printed string. See "say" in perlfunc. (Robin Houston)
+.ie n .SS "Lexical $_"
+.el .SS "Lexical \f(CW$_\fP"
+.IX Subsection "Lexical $_"
+The default variable \f(CW$_\fR can now be lexicalized, by declaring it like
+any other lexical variable, with a simple
+.PP
+.Vb 1
+\&    my $_;
+.Ve
+.PP
+The operations that default on \f(CW$_\fR will use the lexically-scoped
+version of \f(CW$_\fR when it exists, instead of the global \f(CW$_\fR.
+.PP
+In a \f(CW\*(C`map\*(C'\fR or a \f(CW\*(C`grep\*(C'\fR block, if \f(CW$_\fR was previously my'ed, then the
+\&\f(CW$_\fR inside the block is lexical as well (and scoped to the block).
+.PP
+In a scope where \f(CW$_\fR has been lexicalized, you can still have access to
+the global version of \f(CW$_\fR by using \f(CW$::_\fR, or, more simply, by
+overriding the lexical declaration with \f(CW\*(C`our $_\*(C'\fR. (Rafael Garcia-Suarez)
+.ie n .SS "The ""_"" prototype"
+.el .SS "The \f(CW_\fP prototype"
+.IX Subsection "The _ prototype"
+A new prototype character has been added. \f(CW\*(C`_\*(C'\fR is equivalent to \f(CW\*(C`$\*(C'\fR but
+defaults to \f(CW$_\fR if the corresponding argument isn't supplied (both \f(CW\*(C`$\*(C'\fR
+and \f(CW\*(C`_\*(C'\fR denote a scalar). Due to the optional nature of the argument, 
+you can only use it at the end of a prototype, or before a semicolon.
+.PP
+This has a small incompatible consequence: the \fBprototype()\fR function has
+been adjusted to return \f(CW\*(C`_\*(C'\fR for some built-ins in appropriate cases (for
+example, \f(CWprototype(\*(AqCORE::rmdir\*(Aq)\fR). (Rafael Garcia-Suarez)
+.SS "UNITCHECK blocks"
+.IX Subsection "UNITCHECK blocks"
+\&\f(CW\*(C`UNITCHECK\*(C'\fR, a new special code block has been introduced, in addition to
+\&\f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR.
+.PP
+\&\f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR blocks, while useful for some specialized purposes,
+are always executed at the transition between the compilation and the
+execution of the main program, and thus are useless whenever code is
+loaded at runtime. On the other hand, \f(CW\*(C`UNITCHECK\*(C'\fR blocks are executed
+just after the unit which defined them has been compiled. See perlmod
+for more information. (Alex Gough)
+.ie n .SS "New Pragma, ""mro"""
+.el .SS "New Pragma, \f(CWmro\fP"
+.IX Subsection "New Pragma, mro"
+A new pragma, \f(CW\*(C`mro\*(C'\fR (for Method Resolution Order) has been added. It
+permits to switch, on a per-class basis, the algorithm that perl uses to
+find inherited methods in case of a multiple inheritance hierarchy. The
+default MRO hasn't changed (DFS, for Depth First Search). Another MRO is
+available: the C3 algorithm. See mro for more information.
+(Brandon Black)
+.PP
+Note that, due to changes in the implementation of class hierarchy search,
+code that used to undef the \f(CW*ISA\fR glob will most probably break. Anyway,
+undef'ing \f(CW*ISA\fR had the side-effect of removing the magic on the \f(CW@ISA\fR
+array and should not have been done in the first place. Also, the
+cache \f(CW*::ISA::CACHE::\fR no longer exists; to force reset the \f(CW@ISA\fR cache,
+you now need to use the \f(CW\*(C`mro\*(C'\fR API, or more simply to assign to \f(CW@ISA\fR
+(e.g. with \f(CW\*(C`@ISA = @ISA\*(C'\fR).
+.SS "\fBreaddir()\fP may return a ""short filename"" on Windows"
+.IX Subsection "readdir() may return a ""short filename"" on Windows"
+The \fBreaddir()\fR function may return a "short filename" when the long
+filename contains characters outside the ANSI codepage.  Similarly
+\&\fBCwd::cwd()\fR may return a short directory name, and \fBglob()\fR may return short
+names as well.  On the NTFS file system these short names can always be
+represented in the ANSI codepage.  This will not be true for all other file
+system drivers; e.g. the FAT filesystem stores short filenames in the OEM
+codepage, so some files on FAT volumes remain inaccessible through the
+ANSI APIs.
+.PP
+Similarly, $^X, \f(CW@INC\fR, and \f(CW$ENV\fR{PATH} are preprocessed at startup to make
+sure all paths are valid in the ANSI codepage (if possible).
+.PP
+The \fBWin32::GetLongPathName()\fR function now returns the UTF\-8 encoded
+correct long file name instead of using replacement characters to force
+the name into the ANSI codepage.  The new \fBWin32::GetANSIPathName()\fR
+function can be used to turn a long pathname into a short one only if the
+long one cannot be represented in the ANSI codepage.
+.PP
+Many other functions in the \f(CW\*(C`Win32\*(C'\fR module have been improved to accept
+UTF\-8 encoded arguments.  Please see Win32 for details.
+.SS "\fBreadpipe()\fP is now overridable"
+.IX Subsection "readpipe() is now overridable"
+The built-in function \fBreadpipe()\fR is now overridable. Overriding it permits
+also to override its operator counterpart, \f(CW\*(C`qx//\*(C'\fR (a.k.a. \f(CW\`\`\fR).
+Moreover, it now defaults to \f(CW$_\fR if no argument is provided. (Rafael
+Garcia-Suarez)
+.SS "Default argument for \fBreadline()\fP"
+.IX Subsection "Default argument for readline()"
+\&\fBreadline()\fR now defaults to \f(CW*ARGV\fR if no argument is provided. (Rafael
+Garcia-Suarez)
+.SS "\fBstate()\fP variables"
+.IX Subsection "state() variables"
+A new class of variables has been introduced. State variables are similar
+to \f(CW\*(C`my\*(C'\fR variables, but are declared with the \f(CW\*(C`state\*(C'\fR keyword in place of
+\&\f(CW\*(C`my\*(C'\fR. They're visible only in their lexical scope, but their value is
+persistent: unlike \f(CW\*(C`my\*(C'\fR variables, they're not undefined at scope entry,
+but retain their previous value. (Rafael Garcia-Suarez, Nicholas Clark)
+.PP
+To use state variables, one needs to enable them by using
+.PP
+.Vb 1
+\&    use feature \*(Aqstate\*(Aq;
+.Ve
+.PP
+or by using the \f(CW\*(C`\-E\*(C'\fR command-line switch in one-liners.
+See "Persistent Private Variables" in perlsub.
+.SS "Stacked filetest operators"
+.IX Subsection "Stacked filetest operators"
+As a new form of syntactic sugar, it's now possible to stack up filetest
+operators. You can now write \f(CW\*(C`\-f \-w \-x $file\*(C'\fR in a row to mean
+\&\f(CW\*(C`\-x $file && \-w _ && \-f _\*(C'\fR. See "\-X" in perlfunc.
+.SS \fBUNIVERSAL::DOES()\fP
+.IX Subsection "UNIVERSAL::DOES()"
+The \f(CW\*(C`UNIVERSAL\*(C'\fR class has a new method, \f(CWDOES()\fR. It has been added to
+solve semantic problems with the \f(CWisa()\fR method. \f(CWisa()\fR checks for
+inheritance, while \f(CWDOES()\fR has been designed to be overridden when
+module authors use other types of relations between classes (in addition
+to inheritance). (chromatic)
+.PP
+See "$obj\->DOES( ROLE )" in UNIVERSAL.
+.SS Formats
+.IX Subsection "Formats"
+Formats were improved in several ways. A new field, \f(CW\*(C`^*\*(C'\fR, can be used for
+variable-width, one-line-at-a-time text. Null characters are now handled
+correctly in picture lines. Using \f(CW\*(C`@#\*(C'\fR and \f(CW\*(C`~~\*(C'\fR together will now
+produce a compile-time error, as those format fields are incompatible.
+perlform has been improved, and miscellaneous bugs fixed.
+.SS "Byte-order modifiers for \fBpack()\fP and \fBunpack()\fP"
+.IX Subsection "Byte-order modifiers for pack() and unpack()"
+There are two new byte-order modifiers, \f(CW\*(C`>\*(C'\fR (big-endian) and \f(CW\*(C`<\*(C'\fR
+(little-endian), that can be appended to most \fBpack()\fR and \fBunpack()\fR template
+characters and groups to force a certain byte-order for that type or group.
+See "pack" in perlfunc and perlpacktut for details.
+.ie n .SS """no VERSION"""
+.el .SS "\f(CWno VERSION\fP"
+.IX Subsection "no VERSION"
+You can now use \f(CW\*(C`no\*(C'\fR followed by a version number to specify that you
+want to use a version of perl older than the specified one.
+.ie n .SS """chdir"", ""chmod"" and ""chown"" on filehandles"
+.el .SS "\f(CWchdir\fP, \f(CWchmod\fP and \f(CWchown\fP on filehandles"
+.IX Subsection "chdir, chmod and chown on filehandles"
+\&\f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR and \f(CW\*(C`chown\*(C'\fR can now work on filehandles as well as
+filenames, if the system supports respectively \f(CW\*(C`fchdir\*(C'\fR, \f(CW\*(C`fchmod\*(C'\fR and
+\&\f(CW\*(C`fchown\*(C'\fR, thanks to a patch provided by Gisle Aas.
+.SS "OS groups"
+.IX Subsection "OS groups"
+\&\f(CW$(\fR and \f(CW$)\fR now return groups in the order where the OS returns them,
+thanks to Gisle Aas. This wasn't previously the case.
+.SS "Recursive sort subs"
+.IX Subsection "Recursive sort subs"
+You can now use recursive subroutines with \fBsort()\fR, thanks to Robin Houston.
+.SS "Exceptions in constant folding"
+.IX Subsection "Exceptions in constant folding"
+The constant folding routine is now wrapped in an exception handler, and
+if folding throws an exception (such as attempting to evaluate 0/0), perl
+now retains the current optree, rather than aborting the whole program.
+Without this change, programs would not compile if they had expressions that
+happened to generate exceptions, even though those expressions were in code
+that could never be reached at runtime. (Nicholas Clark, Dave Mitchell)
+.ie n .SS "Source filters in @INC"
+.el .SS "Source filters in \f(CW@INC\fP"
+.IX Subsection "Source filters in @INC"
+It's possible to enhance the mechanism of subroutine hooks in \f(CW@INC\fR by
+adding a source filter on top of the filehandle opened and returned by the
+hook. This feature was planned a long time ago, but wasn't quite working
+until now. See "require" in perlfunc for details. (Nicholas Clark)
+.SS "New internal variables"
+.IX Subsection "New internal variables"
+.ie n .IP """${^RE_DEBUG_FLAGS}""" 4
+.el .IP \f(CW${^RE_DEBUG_FLAGS}\fR 4
+.IX Item "${^RE_DEBUG_FLAGS}"
+This variable controls what debug flags are in effect for the regular
+expression engine when running under \f(CW\*(C`use re "debug"\*(C'\fR. See re for
+details.
+.ie n .IP """${^CHILD_ERROR_NATIVE}""" 4
+.el .IP \f(CW${^CHILD_ERROR_NATIVE}\fR 4
+.IX Item "${^CHILD_ERROR_NATIVE}"
+This variable gives the native status returned by the last pipe close,
+backtick command, successful call to \fBwait()\fR or \fBwaitpid()\fR, or from the
+\&\fBsystem()\fR operator. See perlvar for details. (Contributed by Gisle Aas.)
+.ie n .IP """${^RE_TRIE_MAXBUF}""" 4
+.el .IP \f(CW${^RE_TRIE_MAXBUF}\fR 4
+.IX Item "${^RE_TRIE_MAXBUF}"
+See "Trie optimisation of literal string alternations".
+.ie n .IP """${^WIN32_SLOPPY_STAT}""" 4
+.el .IP \f(CW${^WIN32_SLOPPY_STAT}\fR 4
+.IX Item "${^WIN32_SLOPPY_STAT}"
+See "Sloppy stat on Windows".
+.SS Miscellaneous
+.IX Subsection "Miscellaneous"
+\&\f(CWunpack()\fR now defaults to unpacking the \f(CW$_\fR variable.
+.PP
+\&\f(CWmkdir()\fR without arguments now defaults to \f(CW$_\fR.
+.PP
+The internal dump output has been improved, so that non-printable characters
+such as newline and backspace are output in \f(CW\*(C`\ex\*(C'\fR notation, rather than
+octal.
+.PP
+The \fB\-C\fR option can no longer be used on the \f(CW\*(C`#!\*(C'\fR line. It wasn't
+working there anyway, since the standard streams are already set up
+at this point in the execution of the perl interpreter. You can use
+\&\fBbinmode()\fR instead to get the desired behaviour.
+.SS "UCD 5.0.0"
+.IX Subsection "UCD 5.0.0"
+The copy of the Unicode Character Database included in Perl 5 has
+been updated to version 5.0.0.
+.SS MAD
+.IX Subsection "MAD"
+MAD, which stands for \fIMiscellaneous Attribute Decoration\fR, is a
+still-in-development work leading to a Perl 5 to Perl 6 converter. To
+enable it, it's necessary to pass the argument \f(CW\*(C`\-Dmad\*(C'\fR to Configure. The
+obtained perl isn't binary compatible with a regular perl 5.10, and has
+space and speed penalties; moreover not all regression tests still pass
+with it. (Larry Wall, Nicholas Clark)
+.SS "\fBkill()\fP on Windows"
+.IX Subsection "kill() on Windows"
+On Windows platforms, \f(CW\*(C`kill(\-9, $pid)\*(C'\fR now kills a process tree.
+(On Unix, this delivers the signal to all processes in the same process
+group.)
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Packing and UTF\-8 strings"
+.IX Subsection "Packing and UTF-8 strings"
+The semantics of \fBpack()\fR and \fBunpack()\fR regarding UTF\-8\-encoded data has been
+changed. Processing is now by default character per character instead of
+byte per byte on the underlying encoding. Notably, code that used things
+like \f(CW\*(C`pack("a*", $string)\*(C'\fR to see through the encoding of string will now
+simply get back the original \f(CW$string\fR. Packed strings can also get upgraded
+during processing when you store upgraded characters. You can get the old
+behaviour by using \f(CW\*(C`use bytes\*(C'\fR.
+.PP
+To be consistent with \fBpack()\fR, the \f(CW\*(C`C0\*(C'\fR in \fBunpack()\fR templates indicates
+that the data is to be processed in character mode, i.e. character by
+character; on the contrary, \f(CW\*(C`U0\*(C'\fR in \fBunpack()\fR indicates UTF\-8 mode, where
+the packed string is processed in its UTF\-8\-encoded Unicode form on a byte
+by byte basis. This is reversed with regard to perl 5.8.X, but now consistent
+between \fBpack()\fR and \fBunpack()\fR.
+.PP
+Moreover, \f(CW\*(C`C0\*(C'\fR and \f(CW\*(C`U0\*(C'\fR can also be used in \fBpack()\fR templates to specify
+respectively character and byte modes.
+.PP
+\&\f(CW\*(C`C0\*(C'\fR and \f(CW\*(C`U0\*(C'\fR in the middle of a pack or unpack format now switch to the
+specified encoding mode, honoring parens grouping. Previously, parens were
+ignored.
+.PP
+Also, there is a new \fBpack()\fR character format, \f(CW\*(C`W\*(C'\fR, which is intended to
+replace the old \f(CW\*(C`C\*(C'\fR. \f(CW\*(C`C\*(C'\fR is kept for unsigned chars coded as bytes in
+the strings internal representation. \f(CW\*(C`W\*(C'\fR represents unsigned (logical)
+character values, which can be greater than 255. It is therefore more
+robust when dealing with potentially UTF\-8\-encoded data (as \f(CW\*(C`C\*(C'\fR will wrap
+values outside the range 0..255, and not respect the string encoding).
+.PP
+In practice, that means that pack formats are now encoding-neutral, except
+\&\f(CW\*(C`C\*(C'\fR.
+.PP
+For consistency, \f(CW\*(C`A\*(C'\fR in \fBunpack()\fR format now trims all Unicode whitespace
+from the end of the string. Before perl 5.9.2, it used to strip only the
+classical ASCII space characters.
+.SS "Byte/character count feature in \fBunpack()\fP"
+.IX Subsection "Byte/character count feature in unpack()"
+A new \fBunpack()\fR template character, \f(CW"."\fR, returns the number of bytes or
+characters (depending on the selected encoding mode, see above) read so far.
+.ie n .SS "The $* and $# variables have been removed"
+.el .SS "The \f(CW$*\fP and \f(CW$#\fP variables have been removed"
+.IX Subsection "The $* and $# variables have been removed"
+\&\f(CW$*\fR, which was deprecated in favor of the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR regexp
+modifiers, has been removed.
+.PP
+The deprecated \f(CW$#\fR variable (output format for numbers) has been
+removed.
+.PP
+Two new severe warnings, \f(CW\*(C`$#/$* is no longer supported\*(C'\fR, have been added.
+.SS "\fBsubstr()\fP lvalues are no longer fixed-length"
+.IX Subsection "substr() lvalues are no longer fixed-length"
+The lvalues returned by the three argument form of \fBsubstr()\fR used to be a
+"fixed length window" on the original string. In some cases this could
+cause surprising action at distance or other undefined behaviour. Now the
+length of the window adjusts itself to the length of the string assigned to
+it.
+.ie n .SS "Parsing of ""\-f _"""
+.el .SS "Parsing of \f(CW\-f _\fP"
+.IX Subsection "Parsing of -f _"
+The identifier \f(CW\*(C`_\*(C'\fR is now forced to be a bareword after a filetest
+operator. This solves a number of misparsing issues when a global \f(CW\*(C`_\*(C'\fR
+subroutine is defined.
+.ie n .SS """:unique"""
+.el .SS \f(CW:unique\fP
+.IX Subsection ":unique"
+The \f(CW\*(C`:unique\*(C'\fR attribute has been made a no-op, since its current
+implementation was fundamentally flawed and not threadsafe.
+.SS "Effect of pragmas in eval"
+.IX Subsection "Effect of pragmas in eval"
+The compile-time value of the \f(CW\*(C`%^H\*(C'\fR hint variable can now propagate into
+eval("")uated code. This makes it more useful to implement lexical
+pragmas.
+.PP
+As a side-effect of this, the overloaded-ness of constants now propagates
+into eval("").
+.SS "chdir FOO"
+.IX Subsection "chdir FOO"
+A bareword argument to \fBchdir()\fR is now recognized as a file handle.
+Earlier releases interpreted the bareword as a directory name.
+(Gisle Aas)
+.SS "Handling of .pmc files"
+.IX Subsection "Handling of .pmc files"
+An old feature of perl was that before \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR look for a
+file with a \fI.pm\fR extension, they will first look for a similar filename
+with a \fI.pmc\fR extension. If this file is found, it will be loaded in
+place of any potentially existing file ending in a \fI.pm\fR extension.
+.PP
+Previously, \fI.pmc\fR files were loaded only if more recent than the
+matching \fI.pm\fR file. Starting with 5.9.4, they'll be always loaded if
+they exist.
+.ie n .SS "$^V is now a ""version"" object instead of a v\-string"
+.el .SS "$^V is now a \f(CWversion\fP object instead of a v\-string"
+.IX Subsection "$^V is now a version object instead of a v-string"
+$^V can still be used with the \f(CW%vd\fR format in printf, but any
+character-level operations will now access the string representation
+of the \f(CW\*(C`version\*(C'\fR object and not the ordinals of a v\-string.
+Expressions like \f(CW\*(C`substr($^V, 0, 2)\*(C'\fR or \f(CW\*(C`split //, $^V\*(C'\fR
+no longer work and must be rewritten.
+.SS "@\- and @+ in patterns"
+.IX Subsection "@- and @+ in patterns"
+The special arrays \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR are no longer interpolated in regular
+expressions. (Sadahiro Tomoyuki)
+.ie n .SS "$AUTOLOAD can now be tainted"
+.el .SS "\f(CW$AUTOLOAD\fP can now be tainted"
+.IX Subsection "$AUTOLOAD can now be tainted"
+If you call a subroutine by a tainted name, and if it defers to an
+AUTOLOAD function, then \f(CW$AUTOLOAD\fR will be (correctly) tainted.
+(Rick Delaney)
+.SS "Tainting and printf"
+.IX Subsection "Tainting and printf"
+When perl is run under taint mode, \f(CWprintf()\fR and \f(CWsprintf()\fR will now
+reject any tainted format argument. (Rafael Garcia-Suarez)
+.SS "undef and signal handlers"
+.IX Subsection "undef and signal handlers"
+Undefining or deleting a signal handler via \f(CW\*(C`undef $SIG{FOO}\*(C'\fR is now
+equivalent to setting it to \f(CW\*(AqDEFAULT\*(Aq\fR. (Rafael Garcia-Suarez)
+.SS "strictures and dereferencing in \fBdefined()\fP"
+.IX Subsection "strictures and dereferencing in defined()"
+\&\f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR was ignoring taking a hard reference in an argument
+to \fBdefined()\fR, as in :
+.PP
+.Vb 3
+\&    use strict \*(Aqrefs\*(Aq;
+\&    my $x = \*(Aqfoo\*(Aq;
+\&    if (defined $$x) {...}
+.Ve
+.PP
+This now correctly produces the run-time error \f(CW\*(C`Can\*(Aqt use string as a
+SCALAR ref while "strict refs" in use\*(C'\fR.
+.PP
+\&\f(CW\*(C`defined @$foo\*(C'\fR and \f(CW\*(C`defined %$bar\*(C'\fR are now also subject to \f(CWstrict
+\&\*(Aqrefs\*(Aq\fR (that is, \f(CW$foo\fR and \f(CW$bar\fR shall be proper references there.)
+(\f(CWdefined(@foo)\fR and \f(CWdefined(%bar)\fR are discouraged constructs anyway.)
+(Nicholas Clark)
+.ie n .SS """(?p{})"" has been removed"
+.el .SS "\f(CW(?p{})\fP has been removed"
+.IX Subsection "(?p{}) has been removed"
+The regular expression construct \f(CW\*(C`(?p{})\*(C'\fR, which was deprecated in perl
+5.8, has been removed. Use \f(CW\*(C`(??{})\*(C'\fR instead. (Rafael Garcia-Suarez)
+.SS "Pseudo-hashes have been removed"
+.IX Subsection "Pseudo-hashes have been removed"
+Support for pseudo-hashes has been removed from Perl 5.9. (The \f(CW\*(C`fields\*(C'\fR
+pragma remains here, but uses an alternate implementation.)
+.SS "Removal of the bytecode compiler and of perlcc"
+.IX Subsection "Removal of the bytecode compiler and of perlcc"
+\&\f(CW\*(C`perlcc\*(C'\fR, the byteloader and the supporting modules (B::C, B::CC,
+B::Bytecode, etc.) are no longer distributed with the perl sources. Those
+experimental tools have never worked reliably, and, due to the lack of
+volunteers to keep them in line with the perl interpreter developments, it
+was decided to remove them instead of shipping a broken version of those.
+The last version of those modules can be found with perl 5.9.4.
+.PP
+However the B compiler framework stays supported in the perl core, as with
+the more useful modules it has permitted (among others, B::Deparse and
+B::Concise).
+.SS "Removal of the JPL"
+.IX Subsection "Removal of the JPL"
+The JPL (Java-Perl Lingo) has been removed from the perl sources tarball.
+.SS "Recursive inheritance detected earlier"
+.IX Subsection "Recursive inheritance detected earlier"
+Perl will now immediately throw an exception if you modify any package's
+\&\f(CW@ISA\fR in such a way that it would cause recursive inheritance.
+.PP
+Previously, the exception would not occur until Perl attempted to make
+use of the recursive inheritance while resolving a method or doing a
+\&\f(CW\*(C`$foo\->isa($bar)\*(C'\fR lookup.
+.SS "warnings::enabled and warnings::warnif changed to favor users of modules"
+.IX Subsection "warnings::enabled and warnings::warnif changed to favor users of modules"
+The behaviour in 5.10.x favors the person using the module;
+The behaviour in 5.8.x favors the module writer;
+.PP
+Assume the following code:
+.PP
+.Vb 5
+\&  main calls Foo::Bar::baz()
+\&  Foo::Bar inherits from Foo::Base
+\&  Foo::Bar::baz() calls Foo::Base::_bazbaz()
+\&  Foo::Base::_bazbaz() calls: warnings::warnif(\*(Aqsubstr\*(Aq, \*(Aqsome warning 
+\&message\*(Aq);
+.Ve
+.PP
+On 5.8.x, the code warns when Foo::Bar contains \f(CW\*(C`use warnings;\*(C'\fR
+It does not matter if Foo::Base or main have warnings enabled
+to disable the warning one has to modify Foo::Bar.
+.PP
+On 5.10.0 and newer, the code warns when main contains \f(CW\*(C`use warnings;\*(C'\fR
+It does not matter if Foo::Base or Foo::Bar have warnings enabled
+to disable the warning one has to modify main.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Upgrading individual core modules"
+.IX Subsection "Upgrading individual core modules"
+Even more core modules are now also available separately through the
+CPAN.  If you wish to update one of these modules, you don't need to
+wait for a new perl release.  From within the cpan shell, running the
+\&'r' command will report on modules with upgrades available.  See
+\&\f(CW\*(C`perldoc CPAN\*(C'\fR for more information.
+.SS "Pragmata Changes"
+.IX Subsection "Pragmata Changes"
+.ie n .IP """feature""" 4
+.el .IP \f(CWfeature\fR 4
+.IX Item "feature"
+The new pragma \f(CW\*(C`feature\*(C'\fR is used to enable new features that might break
+old code. See "The \f(CW\*(C`feature\*(C'\fR pragma" above.
+.ie n .IP """mro""" 4
+.el .IP \f(CWmro\fR 4
+.IX Item "mro"
+This new pragma enables to change the algorithm used to resolve inherited
+methods. See "New Pragma, \f(CW\*(C`mro\*(C'\fR" above.
+.ie n .IP "Scoping of the ""sort"" pragma" 4
+.el .IP "Scoping of the \f(CWsort\fR pragma" 4
+.IX Item "Scoping of the sort pragma"
+The \f(CW\*(C`sort\*(C'\fR pragma is now lexically scoped. Its effect used to be global.
+.ie n .IP "Scoping of ""bignum"", ""bigint"", ""bigrat""" 4
+.el .IP "Scoping of \f(CWbignum\fR, \f(CWbigint\fR, \f(CWbigrat\fR" 4
+.IX Item "Scoping of bignum, bigint, bigrat"
+The three numeric pragmas \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`bigint\*(C'\fR and \f(CW\*(C`bigrat\*(C'\fR are now
+lexically scoped. (Tels)
+.ie n .IP """base""" 4
+.el .IP \f(CWbase\fR 4
+.IX Item "base"
+The \f(CW\*(C`base\*(C'\fR pragma now warns if a class tries to inherit from itself.
+(Curtis "Ovid" Poe)
+.ie n .IP """strict"" and ""warnings""" 4
+.el .IP "\f(CWstrict\fR and \f(CWwarnings\fR" 4
+.IX Item "strict and warnings"
+\&\f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR will now complain loudly if they are loaded via
+incorrect casing (as in \f(CW\*(C`use Strict;\*(C'\fR). (Johan Vromans)
+.ie n .IP """version""" 4
+.el .IP \f(CWversion\fR 4
+.IX Item "version"
+The \f(CW\*(C`version\*(C'\fR module provides support for version objects.
+.ie n .IP """warnings""" 4
+.el .IP \f(CWwarnings\fR 4
+.IX Item "warnings"
+The \f(CW\*(C`warnings\*(C'\fR pragma doesn't load \f(CW\*(C`Carp\*(C'\fR anymore. That means that code
+that used \f(CW\*(C`Carp\*(C'\fR routines without having loaded it at compile time might
+need to be adjusted; typically, the following (faulty) code won't work
+anymore, and will require parentheses to be added after the function name:
+.Sp
+.Vb 3
+\&    use warnings;
+\&    require Carp;
+\&    Carp::confess \*(Aqargh\*(Aq;
+.Ve
+.ie n .IP """less""" 4
+.el .IP \f(CWless\fR 4
+.IX Item "less"
+\&\f(CW\*(C`less\*(C'\fR now does something useful (or at least it tries to). In fact, it
+has been turned into a lexical pragma. So, in your modules, you can now
+test whether your users have requested to use less CPU, or less memory,
+less magic, or maybe even less fat. See less for more. (Joshua ben
+Jore)
+.SS "New modules"
+.IX Subsection "New modules"
+.IP \(bu 4
+\&\f(CW\*(C`encoding::warnings\*(C'\fR, by Audrey Tang, is a module to emit warnings
+whenever an ASCII character string containing high-bit bytes is implicitly
+converted into UTF\-8. It's a lexical pragma since Perl 5.9.4; on older
+perls, its effect is global.
+.IP \(bu 4
+\&\f(CW\*(C`Module::CoreList\*(C'\fR, by Richard Clamp, is a small handy module that tells
+you what versions of core modules ship with any versions of Perl 5. It
+comes with a command-line frontend, \f(CW\*(C`corelist\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Math::BigInt::FastCalc\*(C'\fR is an XS-enabled, and thus faster, version of
+\&\f(CW\*(C`Math::BigInt::Calc\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Compress::Zlib\*(C'\fR is an interface to the zlib compression library. It
+comes with a bundled version of zlib, so having a working zlib is not a
+prerequisite to install it. It's used by \f(CW\*(C`Archive::Tar\*(C'\fR (see below).
+.IP \(bu 4
+\&\f(CW\*(C`IO::Zlib\*(C'\fR is an \f(CW\*(C`IO::\*(C'\fR\-style interface to \f(CW\*(C`Compress::Zlib\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Archive::Tar\*(C'\fR is a module to manipulate \f(CW\*(C`tar\*(C'\fR archives.
+.IP \(bu 4
+\&\f(CW\*(C`Digest::SHA\*(C'\fR is a module used to calculate many types of SHA digests,
+has been included for SHA support in the CPAN module.
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::CBuilder\*(C'\fR and \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR have been added.
+.IP \(bu 4
+\&\f(CW\*(C`Hash::Util::FieldHash\*(C'\fR, by Anno Siegel, has been added. This module
+provides support for \fIfield hashes\fR: hashes that maintain an association
+of a reference with a value, in a thread-safe garbage-collected way.
+Such hashes are useful to implement inside-out objects.
+.IP \(bu 4
+\&\f(CW\*(C`Module::Build\*(C'\fR, by Ken Williams, has been added. It's an alternative to
+\&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR to build and install perl modules.
+.IP \(bu 4
+\&\f(CW\*(C`Module::Load\*(C'\fR, by Jos Boumans, has been added. It provides a single
+interface to load Perl modules and \fI.pl\fR files.
+.IP \(bu 4
+\&\f(CW\*(C`Module::Loaded\*(C'\fR, by Jos Boumans, has been added. It's used to mark
+modules as loaded or unloaded.
+.IP \(bu 4
+\&\f(CW\*(C`Package::Constants\*(C'\fR, by Jos Boumans, has been added. It's a simple
+helper to list all constants declared in a given package.
+.IP \(bu 4
+\&\f(CW\*(C`Win32API::File\*(C'\fR, by Tye McQueen, has been added (for Windows builds).
+This module provides low-level access to Win32 system API calls for
+files/dirs.
+.IP \(bu 4
+\&\f(CW\*(C`Locale::Maketext::Simple\*(C'\fR, needed by CPANPLUS, is a simple wrapper around
+\&\f(CW\*(C`Locale::Maketext::Lexicon\*(C'\fR. Note that \f(CW\*(C`Locale::Maketext::Lexicon\*(C'\fR isn't
+included in the perl core; the behaviour of \f(CW\*(C`Locale::Maketext::Simple\*(C'\fR
+gracefully degrades when the later isn't present.
+.IP \(bu 4
+\&\f(CW\*(C`Params::Check\*(C'\fR implements a generic input parsing/checking mechanism. It
+is used by CPANPLUS.
+.IP \(bu 4
+\&\f(CW\*(C`Term::UI\*(C'\fR simplifies the task to ask questions at a terminal prompt.
+.IP \(bu 4
+\&\f(CW\*(C`Object::Accessor\*(C'\fR provides an interface to create per-object accessors.
+.IP \(bu 4
+\&\f(CW\*(C`Module::Pluggable\*(C'\fR is a simple framework to create modules that accept
+pluggable sub-modules.
+.IP \(bu 4
+\&\f(CW\*(C`Module::Load::Conditional\*(C'\fR provides simple ways to query and possibly
+load installed modules.
+.IP \(bu 4
+\&\f(CW\*(C`Time::Piece\*(C'\fR provides an object oriented interface to time functions,
+overriding the built-ins \fBlocaltime()\fR and \fBgmtime()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`IPC::Cmd\*(C'\fR helps to find and run external commands, possibly
+interactively.
+.IP \(bu 4
+\&\f(CW\*(C`File::Fetch\*(C'\fR provide a simple generic file fetching mechanism.
+.IP \(bu 4
+\&\f(CW\*(C`Log::Message\*(C'\fR and \f(CW\*(C`Log::Message::Simple\*(C'\fR are used by the log facility
+of \f(CW\*(C`CPANPLUS\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Archive::Extract\*(C'\fR is a generic archive extraction mechanism
+for \fI.tar\fR (plain, gzipped or bzipped) or \fI.zip\fR files.
+.IP \(bu 4
+\&\f(CW\*(C`CPANPLUS\*(C'\fR provides an API and a command-line tool to access the CPAN
+mirrors.
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Escapes\*(C'\fR provides utilities that are useful in decoding Pod
+E<...> sequences.
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Simple\*(C'\fR is now the backend for several of the Pod-related modules
+included with Perl.
+.SS "Selected Changes to Core Modules"
+.IX Subsection "Selected Changes to Core Modules"
+.ie n .IP """Attribute::Handlers""" 4
+.el .IP \f(CWAttribute::Handlers\fR 4
+.IX Item "Attribute::Handlers"
+\&\f(CW\*(C`Attribute::Handlers\*(C'\fR can now report the caller's file and line number.
+(David Feldman)
+.Sp
+All interpreted attributes are now passed as array references. (Damian
+Conway)
+.ie n .IP """B::Lint""" 4
+.el .IP \f(CWB::Lint\fR 4
+.IX Item "B::Lint"
+\&\f(CW\*(C`B::Lint\*(C'\fR is now based on \f(CW\*(C`Module::Pluggable\*(C'\fR, and so can be extended
+with plugins. (Joshua ben Jore)
+.ie n .IP """B""" 4
+.el .IP \f(CWB\fR 4
+.IX Item "B"
+It's now possible to access the lexical pragma hints (\f(CW\*(C`%^H\*(C'\fR) by using the
+method \fBB::COP::hints_hash()\fR. It returns a \f(CW\*(C`B::RHE\*(C'\fR object, which in turn
+can be used to get a hash reference via the method \fBB::RHE::HASH()\fR. (Joshua
+ben Jore)
+.ie n .IP """Thread""" 4
+.el .IP \f(CWThread\fR 4
+.IX Item "Thread"
+As the old 5005thread threading model has been removed, in favor of the
+ithreads scheme, the \f(CW\*(C`Thread\*(C'\fR module is now a compatibility wrapper, to
+be used in old code only. It has been removed from the default list of
+dynamic extensions.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.IP "perl \-d" 4
+.IX Item "perl -d"
+The Perl debugger can now save all debugger commands for sourcing later;
+notably, it can now emulate stepping backwards, by restarting and
+rerunning all bar the last command from a saved command history.
+.Sp
+It can also display the parent inheritance tree of a given class, with the
+\&\f(CW\*(C`i\*(C'\fR command.
+.IP ptar 4
+.IX Item "ptar"
+\&\f(CW\*(C`ptar\*(C'\fR is a pure perl implementation of \f(CW\*(C`tar\*(C'\fR that comes with
+\&\f(CW\*(C`Archive::Tar\*(C'\fR.
+.IP ptardiff 4
+.IX Item "ptardiff"
+\&\f(CW\*(C`ptardiff\*(C'\fR is a small utility used to generate a diff between the contents
+of a tar archive and a directory tree. Like \f(CW\*(C`ptar\*(C'\fR, it comes with
+\&\f(CW\*(C`Archive::Tar\*(C'\fR.
+.IP shasum 4
+.IX Item "shasum"
+\&\f(CW\*(C`shasum\*(C'\fR is a command-line utility, used to print or to check SHA
+digests. It comes with the new \f(CW\*(C`Digest::SHA\*(C'\fR module.
+.IP corelist 4
+.IX Item "corelist"
+The \f(CW\*(C`corelist\*(C'\fR utility is now installed with perl (see "New modules"
+above).
+.IP "h2ph and h2xs" 4
+.IX Item "h2ph and h2xs"
+\&\f(CW\*(C`h2ph\*(C'\fR and \f(CW\*(C`h2xs\*(C'\fR have been made more robust with regard to
+"modern" C code.
+.Sp
+\&\f(CW\*(C`h2xs\*(C'\fR implements a new option \f(CW\*(C`\-\-use\-xsloader\*(C'\fR to force use of
+\&\f(CW\*(C`XSLoader\*(C'\fR even in backwards compatible modules.
+.Sp
+The handling of authors' names that had apostrophes has been fixed.
+.Sp
+Any enums with negative values are now skipped.
+.IP perlivp 4
+.IX Item "perlivp"
+\&\f(CW\*(C`perlivp\*(C'\fR no longer checks for \fI*.ph\fR files by default.  Use the new \f(CW\*(C`\-a\*(C'\fR
+option to run \fIall\fR tests.
+.IP find2perl 4
+.IX Item "find2perl"
+\&\f(CW\*(C`find2perl\*(C'\fR now assumes \f(CW\*(C`\-print\*(C'\fR as a default action. Previously, it
+needed to be specified explicitly.
+.Sp
+Several bugs have been fixed in \f(CW\*(C`find2perl\*(C'\fR, regarding \f(CW\*(C`\-exec\*(C'\fR and
+\&\f(CW\*(C`\-eval\*(C'\fR. Also the options \f(CW\*(C`\-path\*(C'\fR, \f(CW\*(C`\-ipath\*(C'\fR and \f(CW\*(C`\-iname\*(C'\fR have been
+added.
+.IP config_data 4
+.IX Item "config_data"
+\&\f(CW\*(C`config_data\*(C'\fR is a new utility that comes with \f(CW\*(C`Module::Build\*(C'\fR. It
+provides a command-line interface to the configuration of Perl modules
+that use Module::Build's framework of configurability (that is,
+\&\f(CW*::ConfigData\fR modules that contain local configuration information for
+their parent modules.)
+.IP cpanp 4
+.IX Item "cpanp"
+\&\f(CW\*(C`cpanp\*(C'\fR, the CPANPLUS shell, has been added. (\f(CW\*(C`cpanp\-run\-perl\*(C'\fR, a
+helper for CPANPLUS operation, has been added too, but isn't intended for
+direct use).
+.IP cpan2dist 4
+.IX Item "cpan2dist"
+\&\f(CW\*(C`cpan2dist\*(C'\fR is a new utility that comes with CPANPLUS. It's a tool to
+create distributions (or packages) from CPAN modules.
+.IP pod2html 4
+.IX Item "pod2html"
+The output of \f(CW\*(C`pod2html\*(C'\fR has been enhanced to be more customizable via
+CSS. Some formatting problems were also corrected. (Jari Aalto)
+.SH "New Documentation"
+.IX Header "New Documentation"
+The perlpragma manpage documents how to write one's own lexical
+pragmas in pure Perl (something that is possible starting with 5.9.4).
+.PP
+The new perlglossary manpage is a glossary of terms used in the Perl
+documentation, technical and otherwise, kindly provided by O'Reilly Media,
+Inc.
+.PP
+The perlreguts manpage, courtesy of Yves Orton, describes internals of the
+Perl regular expression engine.
+.PP
+The perlreapi manpage describes the interface to the perl interpreter
+used to write pluggable regular expression engines (by Ævar Arnfjörð
+Bjarmason).
+.PP
+The perlunitut manpage is a tutorial for programming with Unicode and
+string encodings in Perl, courtesy of Juerd Waalboer.
+.PP
+A new manual page, perlunifaq (the Perl Unicode FAQ), has been added
+(Juerd Waalboer).
+.PP
+The perlcommunity manpage gives a description of the Perl community
+on the Internet and in real life. (Edgar "Trizor" Bering)
+.PP
+The CORE manual page documents the \f(CW\*(C`CORE::\*(C'\fR namespace. (Tels)
+.PP
+The long-existing feature of \f(CW\*(C`/(?{...})/\*(C'\fR regexps setting \f(CW$_\fR and \fBpos()\fR
+is now documented.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.SS "In-place sorting"
+.IX Subsection "In-place sorting"
+Sorting arrays in place (\f(CW\*(C`@a = sort @a\*(C'\fR) is now optimized to avoid
+making a temporary copy of the array.
+.PP
+Likewise, \f(CW\*(C`reverse sort ...\*(C'\fR is now optimized to sort in reverse,
+avoiding the generation of a temporary intermediate list.
+.SS "Lexical array access"
+.IX Subsection "Lexical array access"
+Access to elements of lexical arrays via a numeric constant between 0 and
+255 is now faster. (This used to be only the case for global arrays.)
+.SS "XS-assisted SWASHGET"
+.IX Subsection "XS-assisted SWASHGET"
+Some pure-perl code that perl was using to retrieve Unicode properties and
+transliteration mappings has been reimplemented in XS.
+.SS "Constant subroutines"
+.IX Subsection "Constant subroutines"
+The interpreter internals now support a far more memory efficient form of
+inlineable constants. Storing a reference to a constant value in a symbol
+table is equivalent to a full typeglob referencing a constant subroutine,
+but using about 400 bytes less memory. This proxy constant subroutine is
+automatically upgraded to a real typeglob with subroutine if necessary.
+The approach taken is analogous to the existing space optimisation for
+subroutine stub declarations, which are stored as plain scalars in place
+of the full typeglob.
+.PP
+Several of the core modules have been converted to use this feature for
+their system dependent constants \- as a result \f(CW\*(C`use POSIX;\*(C'\fR now takes about
+200K less memory.
+.ie n .SS """PERL_DONT_CREATE_GVSV"""
+.el .SS \f(CWPERL_DONT_CREATE_GVSV\fP
+.IX Subsection "PERL_DONT_CREATE_GVSV"
+The new compilation flag \f(CW\*(C`PERL_DONT_CREATE_GVSV\*(C'\fR, introduced as an option
+in perl 5.8.8, is turned on by default in perl 5.9.3. It prevents perl
+from creating an empty scalar with every new typeglob. See perl589delta
+for details.
+.SS "Weak references are cheaper"
+.IX Subsection "Weak references are cheaper"
+Weak reference creation is now \fIO(1)\fR rather than \fIO(n)\fR, courtesy of
+Nicholas Clark. Weak reference deletion remains \fIO(n)\fR, but if deletion only
+happens at program exit, it may be skipped completely.
+.SS "\fBsort()\fP enhancements"
+.IX Subsection "sort() enhancements"
+Salvador Fandiño provided improvements to reduce the memory usage of \f(CW\*(C`sort\*(C'\fR
+and to speed up some cases.
+.SS "Memory optimisations"
+.IX Subsection "Memory optimisations"
+Several internal data structures (typeglobs, GVs, CVs, formats) have been
+restructured to use less memory. (Nicholas Clark)
+.SS "UTF\-8 cache optimisation"
+.IX Subsection "UTF-8 cache optimisation"
+The UTF\-8 caching code is now more efficient, and used more often.
+(Nicholas Clark)
+.SS "Sloppy stat on Windows"
+.IX Subsection "Sloppy stat on Windows"
+On Windows, perl's \fBstat()\fR function normally opens the file to determine
+the link count and update attributes that may have been changed through
+hard links. Setting ${^WIN32_SLOPPY_STAT} to a true value speeds up
+\&\fBstat()\fR by not performing this operation. (Jan Dubois)
+.SS "Regular expressions optimisations"
+.IX Subsection "Regular expressions optimisations"
+.IP "Engine de-recursivised" 4
+.IX Item "Engine de-recursivised"
+The regular expression engine is no longer recursive, meaning that
+patterns that used to overflow the stack will either die with useful
+explanations, or run to completion, which, since they were able to blow
+the stack before, will likely take a very long time to happen. If you were
+experiencing the occasional stack overflow (or segfault) and upgrade to
+discover that now perl apparently hangs instead, look for a degenerate
+regex. (Dave Mitchell)
+.IP "Single char char-classes treated as literals" 4
+.IX Item "Single char char-classes treated as literals"
+Classes of a single character are now treated the same as if the character
+had been used as a literal, meaning that code that uses char-classes as an
+escaping mechanism will see a speedup. (Yves Orton)
+.IP "Trie optimisation of literal string alternations" 4
+.IX Item "Trie optimisation of literal string alternations"
+Alternations, where possible, are optimised into more efficient matching
+structures. String literal alternations are merged into a trie and are
+matched simultaneously.  This means that instead of O(N) time for matching
+N alternations at a given point, the new code performs in O(1) time.
+A new special variable, ${^RE_TRIE_MAXBUF}, has been added to fine-tune
+this optimization. (Yves Orton)
+.Sp
+\&\fBNote:\fR Much code exists that works around perl's historic poor
+performance on alternations. Often the tricks used to do so will disable
+the new optimisations. Hopefully the utility modules used for this purpose
+will be educated about these new optimisations.
+.IP "Aho-Corasick start-point optimisation" 4
+.IX Item "Aho-Corasick start-point optimisation"
+When a pattern starts with a trie-able alternation and there aren't
+better optimisations available, the regex engine will use Aho-Corasick
+matching to find the start point. (Yves Orton)
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Configuration improvements"
+.IX Subsection "Configuration improvements"
+.ie n .IP """\-Dusesitecustomize""" 4
+.el .IP \f(CW\-Dusesitecustomize\fR 4
+.IX Item "-Dusesitecustomize"
+Run-time customization of \f(CW@INC\fR can be enabled by passing the
+\&\f(CW\*(C`\-Dusesitecustomize\*(C'\fR flag to Configure. When enabled, this will make perl
+run \fR\f(CI$sitelibexp\fR\fI/sitecustomize.pl\fR before anything else.  This script can
+then be set up to add additional entries to \f(CW@INC\fR.
+.IP "Relocatable installations" 4
+.IX Item "Relocatable installations"
+There is now Configure support for creating a relocatable perl tree. If
+you Configure with \f(CW\*(C`\-Duserelocatableinc\*(C'\fR, then the paths in \f(CW@INC\fR (and
+everything else in \f(CW%Config\fR) can be optionally located via the path of the
+perl executable.
+.Sp
+That means that, if the string \f(CW".../"\fR is found at the start of any
+path, it's substituted with the directory of $^X. So, the relocation can
+be configured on a per-directory basis, although the default with
+\&\f(CW\*(C`\-Duserelocatableinc\*(C'\fR is that everything is relocated. The initial
+install is done to the original configured prefix.
+.IP "\fBstrlcat()\fR and \fBstrlcpy()\fR" 4
+.IX Item "strlcat() and strlcpy()"
+The configuration process now detects whether \fBstrlcat()\fR and \fBstrlcpy()\fR are
+available.  When they are not available, perl's own version is used (from
+Russ Allbery's public domain implementation).  Various places in the perl
+interpreter now use them. (Steve Peters)
+.ie n .IP """d_pseudofork"" and ""d_printf_format_null""" 4
+.el .IP "\f(CWd_pseudofork\fR and \f(CWd_printf_format_null\fR" 4
+.IX Item "d_pseudofork and d_printf_format_null"
+A new configuration variable, available as \f(CW$Config{d_pseudofork}\fR in
+the Config module, has been added, to distinguish real \fBfork()\fR support
+from fake pseudofork used on Windows platforms.
+.Sp
+A new configuration variable, \f(CW\*(C`d_printf_format_null\*(C'\fR, has been added, 
+to see if printf-like formats are allowed to be NULL.
+.IP "Configure help" 4
+.IX Item "Configure help"
+\&\f(CW\*(C`Configure \-h\*(C'\fR has been extended with the most commonly used options.
+.SS "Compilation improvements"
+.IX Subsection "Compilation improvements"
+.IP "Parallel build" 4
+.IX Item "Parallel build"
+Parallel makes should work properly now, although there may still be problems
+if \f(CW\*(C`make test\*(C'\fR is instructed to run in parallel.
+.IP "Borland's compilers support" 4
+.IX Item "Borland's compilers support"
+Building with Borland's compilers on Win32 should work more smoothly. In
+particular Steve Hay has worked to side step many warnings emitted by their
+compilers and at least one C compiler internal error.
+.IP "Static build on Windows" 4
+.IX Item "Static build on Windows"
+Perl extensions on Windows now can be statically built into the Perl DLL.
+.Sp
+Also, it's now possible to build a \f(CW\*(C`perl\-static.exe\*(C'\fR that doesn't depend
+on the Perl DLL on Win32. See the Win32 makefiles for details.
+(Vadim Konovalov)
+.IP "ppport.h files" 4
+.IX Item "ppport.h files"
+All \fIppport.h\fR files in the XS modules bundled with perl are now
+autogenerated at build time. (Marcus Holland-Moritz)
+.IP "C++ compatibility" 4
+.IX Item "C++ compatibility"
+Efforts have been made to make perl and the core XS modules compilable
+with various C++ compilers (although the situation is not perfect with
+some of the compilers on some of the platforms tested.)
+.IP "Support for Microsoft 64\-bit compiler" 4
+.IX Item "Support for Microsoft 64-bit compiler"
+Support for building perl with Microsoft's 64\-bit compiler has been
+improved. (ActiveState)
+.IP "Visual C++" 4
+.IX Item "Visual C++"
+Perl can now be compiled with Microsoft Visual C++ 2005 (and 2008 Beta 2).
+.IP "Win32 builds" 4
+.IX Item "Win32 builds"
+All win32 builds (MS-Win, WinCE) have been merged and cleaned up.
+.SS "Installation improvements"
+.IX Subsection "Installation improvements"
+.IP "Module auxiliary files" 4
+.IX Item "Module auxiliary files"
+README files and changelogs for CPAN modules bundled with perl are no
+longer installed.
+.SS "New Or Improved Platforms"
+.IX Subsection "New Or Improved Platforms"
+Perl has been reported to work on Symbian OS. See perlsymbian for more
+information.
+.PP
+Many improvements have been made towards making Perl work correctly on
+z/OS.
+.PP
+Perl has been reported to work on DragonFlyBSD and MidnightBSD.
+.PP
+Perl has also been reported to work on NexentaOS
+( http://www.gnusolaris.org/ ).
+.PP
+The VMS port has been improved. See perlvms.
+.PP
+Support for Cray XT4 Catamount/Qk has been added. See
+\&\fIhints/catamount.sh\fR in the source code distribution for more
+information.
+.PP
+Vendor patches have been merged for RedHat and Gentoo.
+.PP
+\&\fBDynaLoader::dl_unload_file()\fR now works on Windows.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP "strictures in regexp-eval blocks" 4
+.IX Item "strictures in regexp-eval blocks"
+\&\f(CW\*(C`strict\*(C'\fR wasn't in effect in regexp-eval blocks (\f(CW\*(C`/(?{...})/\*(C'\fR).
+.IP "Calling \fBCORE::require()\fR" 4
+.IX Item "Calling CORE::require()"
+\&\fBCORE::require()\fR and \fBCORE::do()\fR were always parsed as \fBrequire()\fR and \fBdo()\fR
+when they were overridden. This is now fixed.
+.IP "Subscripts of slices" 4
+.IX Item "Subscripts of slices"
+You can now use a non-arrowed form for chained subscripts after a list
+slice, like in:
+.Sp
+.Vb 1
+\&    ({foo => "bar"})[0]{foo}
+.Ve
+.Sp
+This used to be a syntax error; a \f(CW\*(C`\->\*(C'\fR was required.
+.ie n .IP """no warnings \*(Aqcategory\*(Aq"" works correctly with \-w" 4
+.el .IP "\f(CWno warnings \*(Aqcategory\*(Aq\fR works correctly with \-w" 4
+.IX Item "no warnings category works correctly with -w"
+Previously when running with warnings enabled globally via \f(CW\*(C`\-w\*(C'\fR, selective
+disabling of specific warning categories would actually turn off all warnings.
+This is now fixed; now \f(CW\*(C`no warnings \*(Aqio\*(Aq;\*(C'\fR will only turn off warnings in the
+\&\f(CW\*(C`io\*(C'\fR class. Previously it would erroneously turn off all warnings.
+.IP "threads improvements" 4
+.IX Item "threads improvements"
+Several memory leaks in ithreads were closed. Also, ithreads were made
+less memory-intensive.
+.Sp
+\&\f(CW\*(C`threads\*(C'\fR is now a dual-life module, also available on CPAN. It has been
+expanded in many ways. A \fBkill()\fR method is available for thread signalling.
+One can get thread status, or the list of running or joinable threads.
+.Sp
+A new \f(CW\*(C`threads\->exit()\*(C'\fR method is used to exit from the application
+(this is the default for the main thread) or from the current thread only
+(this is the default for all other threads). On the other hand, the \fBexit()\fR
+built-in now always causes the whole application to terminate. (Jerry
+D. Hedden)
+.IP "\fBchr()\fR and negative values" 4
+.IX Item "chr() and negative values"
+\&\fBchr()\fR on a negative value now gives \f(CW\*(C`\ex{FFFD}\*(C'\fR, the Unicode replacement
+character, unless when the \f(CW\*(C`bytes\*(C'\fR pragma is in effect, where the low
+eight bits of the value are used.
+.IP "PERL5SHELL and tainting" 4
+.IX Item "PERL5SHELL and tainting"
+On Windows, the PERL5SHELL environment variable is now checked for
+taintedness. (Rafael Garcia-Suarez)
+.IP "Using *FILE{IO}" 4
+.IX Item "Using *FILE{IO}"
+\&\f(CWstat()\fR and \f(CW\*(C`\-X\*(C'\fR filetests now treat *FILE{IO} filehandles like *FILE
+filehandles. (Steve Peters)
+.IP "Overloading and reblessing" 4
+.IX Item "Overloading and reblessing"
+Overloading now works when references are reblessed into another class.
+Internally, this has been implemented by moving the flag for "overloading"
+from the reference to the referent, which logically is where it should
+always have been. (Nicholas Clark)
+.IP "Overloading and UTF\-8" 4
+.IX Item "Overloading and UTF-8"
+A few bugs related to UTF\-8 handling with objects that have
+stringification overloaded have been fixed. (Nicholas Clark)
+.IP "eval memory leaks fixed" 4
+.IX Item "eval memory leaks fixed"
+Traditionally, \f(CW\*(C`eval \*(Aqsyntax error\*(Aq\*(C'\fR has leaked badly. Many (but not all)
+of these leaks have now been eliminated or reduced. (Dave Mitchell)
+.IP "Random device on Windows" 4
+.IX Item "Random device on Windows"
+In previous versions, perl would read the file \fI/dev/urandom\fR if it
+existed when seeding its random number generator.  That file is unlikely
+to exist on Windows, and if it did would probably not contain appropriate
+data, so perl no longer tries to read it on Windows. (Alex Davies)
+.IP PERLIO_DEBUG 4
+.IX Item "PERLIO_DEBUG"
+The \f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable no longer has any effect for
+setuid scripts and for scripts run with \fB\-T\fR.
+.Sp
+Moreover, with a thread-enabled perl, using \f(CW\*(C`PERLIO_DEBUG\*(C'\fR could lead to
+an internal buffer overflow. This has been fixed.
+.IP "PerlIO::scalar and read-only scalars" 4
+.IX Item "PerlIO::scalar and read-only scalars"
+PerlIO::scalar will now prevent writing to read-only scalars. Moreover,
+\&\fBseek()\fR is now supported with PerlIO::scalar\-based filehandles, the
+underlying string being zero-filled as needed. (Rafael, Jarkko Hietaniemi)
+.IP "\fBstudy()\fR and UTF\-8" 4
+.IX Item "study() and UTF-8"
+\&\fBstudy()\fR never worked for UTF\-8 strings, but could lead to false results.
+It's now a no-op on UTF\-8 data. (Yves Orton)
+.IP "Critical signals" 4
+.IX Item "Critical signals"
+The signals SIGILL, SIGBUS and SIGSEGV are now always delivered in an
+"unsafe" manner (contrary to other signals, that are deferred until the
+perl interpreter reaches a reasonably stable state; see
+"Deferred Signals (Safe Signals)" in perlipc). (Rafael)
+.ie n .IP "@INC\-hook fix" 4
+.el .IP "\f(CW@INC\fR\-hook fix" 4
+.IX Item "@INC-hook fix"
+When a module or a file is loaded through an \f(CW@INC\fR\-hook, and when this hook
+has set a filename entry in \f(CW%INC\fR, _\|_FILE_\|_ is now set for this module
+accordingly to the contents of that \f(CW%INC\fR entry. (Rafael)
+.ie n .IP """\-t"" switch fix" 4
+.el .IP "\f(CW\-t\fR switch fix" 4
+.IX Item "-t switch fix"
+The \f(CW\*(C`\-w\*(C'\fR and \f(CW\*(C`\-t\*(C'\fR switches can now be used together without messing
+up which categories of warnings are activated. (Rafael)
+.IP "Duping UTF\-8 filehandles" 4
+.IX Item "Duping UTF-8 filehandles"
+Duping a filehandle which has the \f(CW\*(C`:utf8\*(C'\fR PerlIO layer set will now
+properly carry that layer on the duped filehandle. (Rafael)
+.IP "Localisation of hash elements" 4
+.IX Item "Localisation of hash elements"
+Localizing a hash element whose key was given as a variable didn't work
+correctly if the variable was changed while the \fBlocal()\fR was in effect (as
+in \f(CW\*(C`local $h{$x}; ++$x\*(C'\fR). (Bo Lindbergh)
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.IP "Use of uninitialized value" 4
+.IX Item "Use of uninitialized value"
+Perl will now try to tell you the name of the variable (if any) that was
+undefined.
+.IP "Deprecated use of \fBmy()\fR in false conditional" 4
+.IX Item "Deprecated use of my() in false conditional"
+A new deprecation warning, \fIDeprecated use of \fR\f(BImy()\fR\fI in false conditional\fR,
+has been added, to warn against the use of the dubious and deprecated
+construct
+.Sp
+.Vb 1
+\&    my $x if 0;
+.Ve
+.Sp
+See perldiag. Use \f(CW\*(C`state\*(C'\fR variables instead.
+.IP "!=~ should be !~" 4
+.IX Item "!=~ should be !~"
+A new warning, \f(CW\*(C`!=~ should be !~\*(C'\fR, is emitted to prevent this misspelling
+of the non-matching operator.
+.IP "Newline in left-justified string" 4
+.IX Item "Newline in left-justified string"
+The warning \fINewline in left-justified string\fR has been removed.
+.IP "Too late for ""\-T"" option" 4
+.IX Item "Too late for ""-T"" option"
+The error \fIToo late for "\-T" option\fR has been reformulated to be more
+descriptive.
+.ie n .IP """%s"" variable %s masks earlier declaration" 4
+.el .IP """%s"" variable \f(CW%s\fR masks earlier declaration" 4
+.IX Item """%s"" variable %s masks earlier declaration"
+This warning is now emitted in more consistent cases; in short, when one
+of the declarations involved is a \f(CW\*(C`my\*(C'\fR variable:
+.Sp
+.Vb 3
+\&    my $x;   my $x;     # warns
+\&    my $x;  our $x;     # warns
+\&    our $x;  my $x;     # warns
+.Ve
+.Sp
+On the other hand, the following:
+.Sp
+.Vb 1
+\&    our $x; our $x;
+.Ve
+.Sp
+now gives a \f(CW\*(C`"our" variable %s redeclared\*(C'\fR warning.
+.IP "\fBreaddir()\fR/\fBclosedir()\fR/etc. attempted on invalid dirhandle" 4
+.IX Item "readdir()/closedir()/etc. attempted on invalid dirhandle"
+These new warnings are now emitted when a dirhandle is used but is
+either closed or not really a dirhandle.
+.ie n .IP "Opening dirhandle/filehandle %s also as a file/directory" 4
+.el .IP "Opening dirhandle/filehandle \f(CW%s\fR also as a file/directory" 4
+.IX Item "Opening dirhandle/filehandle %s also as a file/directory"
+Two deprecation warnings have been added: (Rafael)
+.Sp
+.Vb 2
+\&    Opening dirhandle %s also as a file
+\&    Opening filehandle %s also as a directory
+.Ve
+.IP "Use of \-P is deprecated" 4
+.IX Item "Use of -P is deprecated"
+Perl's command-line switch \f(CW\*(C`\-P\*(C'\fR is now deprecated.
+.IP "v\-string in use/require is non-portable" 4
+.IX Item "v-string in use/require is non-portable"
+Perl will warn you against potential backwards compatibility problems with
+the \f(CW\*(C`use VERSION\*(C'\fR syntax.
+.IP "perl \-V" 4
+.IX Item "perl -V"
+\&\f(CW\*(C`perl \-V\*(C'\fR has several improvements, making it more useable from shell
+scripts to get the value of configuration variables. See perlrun for
+details.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+In general, the source code of perl has been refactored, tidied up,
+and optimized in many places. Also, memory management and allocation
+has been improved in several points.
+.PP
+When compiling the perl core with gcc, as many gcc warning flags are
+turned on as is possible on the platform.  (This quest for cleanliness
+doesn't extend to XS code because we cannot guarantee the tidiness of
+code we didn't write.)  Similar strictness flags have been added or
+tightened for various other C compilers.
+.SS "Reordering of SVt_* constants"
+.IX Subsection "Reordering of SVt_* constants"
+The relative ordering of constants that define the various types of \f(CW\*(C`SV\*(C'\fR
+have changed; in particular, \f(CW\*(C`SVt_PVGV\*(C'\fR has been moved before \f(CW\*(C`SVt_PVLV\*(C'\fR,
+\&\f(CW\*(C`SVt_PVAV\*(C'\fR, \f(CW\*(C`SVt_PVHV\*(C'\fR and \f(CW\*(C`SVt_PVCV\*(C'\fR.  This is unlikely to make any
+difference unless you have code that explicitly makes assumptions about that
+ordering. (The inheritance hierarchy of \f(CW\*(C`B::*\*(C'\fR objects has been changed
+to reflect this.)
+.SS "Elimination of SVt_PVBM"
+.IX Subsection "Elimination of SVt_PVBM"
+Related to this, the internal type \f(CW\*(C`SVt_PVBM\*(C'\fR has been removed. This
+dedicated type of \f(CW\*(C`SV\*(C'\fR was used by the \f(CW\*(C`index\*(C'\fR operator and parts of the
+regexp engine to facilitate fast Boyer-Moore matches. Its use internally has
+been replaced by \f(CW\*(C`SV\*(C'\fRs of type \f(CW\*(C`SVt_PVGV\*(C'\fR.
+.SS "New type SVt_BIND"
+.IX Subsection "New type SVt_BIND"
+A new type \f(CW\*(C`SVt_BIND\*(C'\fR has been added, in readiness for the project to
+implement Perl 6 on 5. There deliberately is no implementation yet, and
+they cannot yet be created or destroyed.
+.SS "Removal of CPP symbols"
+.IX Subsection "Removal of CPP symbols"
+The C preprocessor symbols \f(CW\*(C`PERL_PM_APIVERSION\*(C'\fR and
+\&\f(CW\*(C`PERL_XS_APIVERSION\*(C'\fR, which were supposed to give the version number of
+the oldest perl binary-compatible (resp. source-compatible) with the
+present one, were not used, and sometimes had misleading values. They have
+been removed.
+.SS "Less space is used by ops"
+.IX Subsection "Less space is used by ops"
+The \f(CW\*(C`BASEOP\*(C'\fR structure now uses less space. The \f(CW\*(C`op_seq\*(C'\fR field has been
+removed and replaced by a single bit bit-field \f(CW\*(C`op_opt\*(C'\fR. \f(CW\*(C`op_type\*(C'\fR is now 9
+bits long. (Consequently, the \f(CW\*(C`B::OP\*(C'\fR class doesn't provide an \f(CW\*(C`seq\*(C'\fR
+method anymore.)
+.SS "New parser"
+.IX Subsection "New parser"
+perl's parser is now generated by bison (it used to be generated by
+byacc.) As a result, it seems to be a bit more robust.
+.PP
+Also, Dave Mitchell improved the lexer debugging output under \f(CW\*(C`\-DT\*(C'\fR.
+.ie n .SS "Use of ""const"""
+.el .SS "Use of \f(CWconst\fP"
+.IX Subsection "Use of const"
+Andy Lester supplied many improvements to determine which function
+parameters and local variables could actually be declared \f(CW\*(C`const\*(C'\fR to the C
+compiler. Steve Peters provided new \f(CW*_set\fR macros and reworked the core to
+use these rather than assigning to macros in LVALUE context.
+.SS Mathoms
+.IX Subsection "Mathoms"
+A new file, \fImathoms.c\fR, has been added. It contains functions that are
+no longer used in the perl core, but that remain available for binary or
+source compatibility reasons. However, those functions will not be
+compiled in if you add \f(CW\*(C`\-DNO_MATHOMS\*(C'\fR in the compiler flags.
+.ie n .SS """AvFLAGS"" has been removed"
+.el .SS "\f(CWAvFLAGS\fP has been removed"
+.IX Subsection "AvFLAGS has been removed"
+The \f(CW\*(C`AvFLAGS\*(C'\fR macro has been removed.
+.ie n .SS """av_*"" changes"
+.el .SS "\f(CWav_*\fP changes"
+.IX Subsection "av_* changes"
+The \f(CW\*(C`av_*()\*(C'\fR functions, used to manipulate arrays, no longer accept null
+\&\f(CW\*(C`AV*\*(C'\fR parameters.
+.SS "$^H and %^H"
+.IX Subsection "$^H and %^H"
+The implementation of the special variables $^H and %^H has changed, to
+allow implementing lexical pragmas in pure Perl.
+.SS "B:: modules inheritance changed"
+.IX Subsection "B:: modules inheritance changed"
+The inheritance hierarchy of \f(CW\*(C`B::\*(C'\fR modules has changed; \f(CW\*(C`B::NV\*(C'\fR now
+inherits from \f(CW\*(C`B::SV\*(C'\fR (it used to inherit from \f(CW\*(C`B::IV\*(C'\fR).
+.SS "Anonymous hash and array constructors"
+.IX Subsection "Anonymous hash and array constructors"
+The anonymous hash and array constructors now take 1 op in the optree
+instead of 3, now that pp_anonhash and pp_anonlist return a reference to
+a hash/array when the op is flagged with OPf_SPECIAL. (Nicholas Clark)
+.SH "Known Problems"
+.IX Header "Known Problems"
+There's still a remaining problem in the implementation of the lexical
+\&\f(CW$_\fR: it doesn't work inside \f(CW\*(C`/(?{...})/\*(C'\fR blocks. (See the TODO test in
+\&\fIt/op/mydef.t\fR.)
+.PP
+Stacked filetest operators won't work when the \f(CW\*(C`filetest\*(C'\fR pragma is in
+effect, because they rely on the \fBstat()\fR buffer \f(CW\*(C`_\*(C'\fR being populated, and
+filetest bypasses \fBstat()\fR.
+.SS "UTF\-8 problems"
+.IX Subsection "UTF-8 problems"
+The handling of Unicode still is unclean in several places, where it's
+dependent on whether a string is internally flagged as UTF\-8. This will
+be made more consistent in perl 5.12, but that won't be possible without
+a certain amount of backwards incompatibility.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+When compiled with g++ and thread support on Linux, it's reported that the
+\&\f(CW$!\fR stops working correctly. This is related to the fact that the glibc
+provides two \fBstrerror_r\fR\|(3) implementation, and perl selects the wrong
+one.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/rt3/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file and the perl590delta to perl595delta man pages for
+exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5101delta.1 b/upstream/mageia-cauldron/man1/perl5101delta.1
new file mode 100644
index 00000000..4da61f10
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5101delta.1
@@ -0,0 +1,1550 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5101DELTA 1"
+.TH PERL5101DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5101delta \- what is new for perl v5.10.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.10.0 release and
+the 5.10.1 release.
+.PP
+If you are upgrading from an earlier release such as 5.8.8, first read
+the perl5100delta, which describes differences between 5.8.8 and
+5.10.0
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Switch statement changes"
+.IX Subsection "Switch statement changes"
+The handling of complex expressions by the \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR switch
+statement has been enhanced. There are two new cases where \f(CW\*(C`when\*(C'\fR now
+interprets its argument as a boolean, instead of an expression to be used
+in a smart match:
+.IP "flip-flop operators" 4
+.IX Item "flip-flop operators"
+The \f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR flip-flop operators are now evaluated in boolean
+context, following their usual semantics; see "Range Operators" in perlop.
+.Sp
+Note that, as in perl 5.10.0, \f(CW\*(C`when (1..10)\*(C'\fR will not work to test
+whether a given value is an integer between 1 and 10; you should use
+\&\f(CW\*(C`when ([1..10])\*(C'\fR instead (note the array reference).
+.Sp
+However, contrary to 5.10.0, evaluating the flip-flop operators in boolean
+context ensures it can now be useful in a \f(CWwhen()\fR, notably for
+implementing bistable conditions, like in:
+.Sp
+.Vb 3
+\&    when (/^=begin/ .. /^=end/) {
+\&      # do something
+\&    }
+.Ve
+.IP "defined-or operator" 4
+.IX Item "defined-or operator"
+A compound expression involving the defined-or operator, as in
+\&\f(CW\*(C`when (expr1 // expr2)\*(C'\fR, will be treated as boolean if the first
+expression is boolean. (This just extends the existing rule that applies
+to the regular or operator, as in \f(CW\*(C`when (expr1 || expr2)\*(C'\fR.)
+.PP
+The next section details more changes brought to the semantics to
+the smart match operator, that naturally also modify the behaviour
+of the switch statements where smart matching is implicitly used.
+.SS "Smart match changes"
+.IX Subsection "Smart match changes"
+\fIChanges to type-based dispatch\fR
+.IX Subsection "Changes to type-based dispatch"
+.PP
+The smart match operator \f(CW\*(C`~~\*(C'\fR is no longer commutative. The behaviour of
+a smart match now depends primarily on the type of its right hand
+argument. Moreover, its semantics have been adjusted for greater
+consistency or usefulness in several cases. While the general backwards
+compatibility is maintained, several changes must be noted:
+.IP \(bu 4
+Code references with an empty prototype are no longer treated specially.
+They are passed an argument like the other code references (even if they
+choose to ignore it).
+.IP \(bu 4
+\&\f(CW\*(C`%hash ~~ sub {}\*(C'\fR and \f(CW\*(C`@array ~~ sub {}\*(C'\fR now test that the subroutine
+returns a true value for each key of the hash (or element of the
+array), instead of passing the whole hash or array as a reference to
+the subroutine.
+.IP \(bu 4
+Due to the commutativity breakage, code references are no longer
+treated specially when appearing on the left of the \f(CW\*(C`~~\*(C'\fR operator,
+but like any vulgar scalar.
+.IP \(bu 4
+\&\f(CW\*(C`undef ~~ %hash\*(C'\fR is always false (since \f(CW\*(C`undef\*(C'\fR can't be a key in a
+hash). No implicit conversion to \f(CW""\fR is done (as was the case in perl
+5.10.0).
+.IP \(bu 4
+\&\f(CW\*(C`$scalar ~~ @array\*(C'\fR now always distributes the smart match across the
+elements of the array. It's true if one element in \f(CW@array\fR verifies
+\&\f(CW\*(C`$scalar ~~ $element\*(C'\fR. This is a generalization of the old behaviour
+that tested whether the array contained the scalar.
+.PP
+The full dispatch table for the smart match operator is given in
+"Smart matching in detail" in perlsyn.
+.PP
+\fISmart match and overloading\fR
+.IX Subsection "Smart match and overloading"
+.PP
+According to the rule of dispatch based on the rightmost argument type,
+when an object overloading \f(CW\*(C`~~\*(C'\fR appears on the right side of the
+operator, the overload routine will always be called (with a 3rd argument
+set to a true value, see overload.) However, when the object will
+appear on the left, the overload routine will be called only when the
+rightmost argument is a simple scalar. This way distributivity of smart match
+across arrays is not broken, as well as the other behaviours with complex
+types (coderefs, hashes, regexes). Thus, writers of overloading routines
+for smart match mostly need to worry only with comparing against a scalar,
+and possibly with stringification overloading; the other common cases
+will be automatically handled consistently.
+.PP
+\&\f(CW\*(C`~~\*(C'\fR will now refuse to work on objects that do not overload it (in order
+to avoid relying on the object's underlying structure). (However, if the
+object overloads the stringification or the numification operators, and
+if overload fallback is active, it will be used instead, as usual.)
+.SS "Other incompatible changes"
+.IX Subsection "Other incompatible changes"
+.IP \(bu 4
+The semantics of \f(CW\*(C`use feature :5.10*\*(C'\fR have changed slightly.
+See "Modules and Pragmata" for more information.
+.IP \(bu 4
+It is now a run-time error to use the smart match operator \f(CW\*(C`~~\*(C'\fR
+with an object that has no overload defined for it. (This way
+\&\f(CW\*(C`~~\*(C'\fR will not break encapsulation by matching against the
+object's internal representation as a reference.)
+.IP \(bu 4
+The version control system used for the development of the perl
+interpreter has been switched from Perforce to git.  This is mainly an
+internal issue that only affects people actively working on the perl core;
+but it may have minor external visibility, for example in some of details
+of the output of \f(CW\*(C`perl \-V\*(C'\fR. See perlrepository for more information.
+.IP \(bu 4
+The internal structure of the \f(CW\*(C`ext/\*(C'\fR directory in the perl source has
+been reorganised. In general, a module \f(CW\*(C`Foo::Bar\*(C'\fR whose source was
+stored under \fIext/Foo/Bar/\fR is now located under \fIext/Foo\-Bar/\fR. Also,
+some modules have been moved from \fIlib/\fR to \fIext/\fR. This is purely a
+source tarball change, and should make no difference to the compilation or
+installation of perl, unless you have a very customised build process that
+explicitly relies on this structure, or which hard-codes the \f(CW\*(C`nonxs_ext\*(C'\fR
+\&\fIConfigure\fR parameter. Specifically, this change does not by default
+alter the location of any files in the final installation.
+.IP \(bu 4
+As part of the \f(CW\*(C`Test::Harness\*(C'\fR 2.x to 3.x upgrade, the experimental
+\&\f(CW\*(C`Test::Harness::Straps\*(C'\fR module has been removed.
+See "Updated Modules" for more details.
+.IP \(bu 4
+As part of the \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR upgrade, the
+\&\f(CW\*(C`ExtUtils::MakeMaker::bytes\*(C'\fR and \f(CW\*(C`ExtUtils::MakeMaker::vmsish\*(C'\fR modules
+have been removed from this distribution.
+.IP \(bu 4
+\&\f(CW\*(C`Module::CoreList\*(C'\fR no longer contains the \f(CW%:patchlevel\fR hash.
+.IP \(bu 4
+This one is actually a change introduced in 5.10.0, but it was missed
+from that release's perldelta, so it is mentioned here instead.
+.Sp
+A bugfix related to the handling of the \f(CW\*(C`/m\*(C'\fR modifier and \f(CW\*(C`qr\*(C'\fR resulted
+in a change of behaviour between 5.8.x and 5.10.0:
+.Sp
+.Vb 2
+\&    # matches in 5.8.x, doesn\*(Aqt match in 5.10.0
+\&    $re = qr/^bar/; "foo\enbar" =~ /$re/m;
+.Ve
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Unicode Character Database 5.1.0"
+.IX Subsection "Unicode Character Database 5.1.0"
+The copy of the Unicode Character Database included in Perl 5.10.1 has
+been updated to 5.1.0 from 5.0.0. See
+<http://www.unicode.org/versions/Unicode5.1.0/#Notable_Changes> for the
+notable changes.
+.SS "A proper interface for pluggable Method Resolution Orders"
+.IX Subsection "A proper interface for pluggable Method Resolution Orders"
+As of Perl 5.10.1 there is a new interface for plugging and using method
+resolution orders other than the default (linear depth first search).
+The C3 method resolution order added in 5.10.0 has been re-implemented as
+a plugin, without changing its Perl-space interface. See perlmroapi for
+more information.
+.ie n .SS "The ""overloading"" pragma"
+.el .SS "The \f(CWoverloading\fP pragma"
+.IX Subsection "The overloading pragma"
+This pragma allows you to lexically disable or enable overloading
+for some or all operations. (Yuval Kogman)
+.SS "Parallel tests"
+.IX Subsection "Parallel tests"
+The core distribution can now run its regression tests in parallel on
+Unix-like platforms. Instead of running \f(CW\*(C`make test\*(C'\fR, set \f(CW\*(C`TEST_JOBS\*(C'\fR in
+your environment to the number of tests to run in parallel, and run
+\&\f(CW\*(C`make test_harness\*(C'\fR. On a Bourne-like shell, this can be done as
+.PP
+.Vb 1
+\&    TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
+.Ve
+.PP
+An environment variable is used, rather than parallel make itself, because
+TAP::Harness needs to be able to schedule individual non-conflicting test
+scripts itself, and there is no standard interface to \f(CW\*(C`make\*(C'\fR utilities to
+interact with their job schedulers.
+.PP
+Note that currently some test scripts may fail when run in parallel (most
+notably \f(CW\*(C`ext/IO/t/io_dir.t\*(C'\fR). If necessary run just the failing scripts
+again sequentially and see if the failures go away.
+.SS "DTrace support"
+.IX Subsection "DTrace support"
+Some support for DTrace has been added. See "DTrace support" in \fIINSTALL\fR.
+.ie n .SS "Support for ""configure_requires"" in CPAN module metadata"
+.el .SS "Support for \f(CWconfigure_requires\fP in CPAN module metadata"
+.IX Subsection "Support for configure_requires in CPAN module metadata"
+Both \f(CW\*(C`CPAN\*(C'\fR and \f(CW\*(C`CPANPLUS\*(C'\fR now support the \f(CW\*(C`configure_requires\*(C'\fR keyword
+in the \f(CW\*(C`META.yml\*(C'\fR metadata file included in most recent CPAN distributions.
+This allows distribution authors to specify configuration prerequisites that
+must be installed before running \fIMakefile.PL\fR or \fIBuild.PL\fR.
+.PP
+See the documentation for \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR or \f(CW\*(C`Module::Build\*(C'\fR for more
+on how to specify \f(CW\*(C`configure_requires\*(C'\fR when creating a distribution for CPAN.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.ie n .IP """autodie""" 4
+.el .IP \f(CWautodie\fR 4
+.IX Item "autodie"
+This is a new lexically-scoped alternative for the \f(CW\*(C`Fatal\*(C'\fR module.
+The bundled version is 2.06_01. Note that in this release, using a string
+eval when \f(CW\*(C`autodie\*(C'\fR is in effect can cause the autodie behaviour to leak
+into the surrounding scope. See "BUGS" in autodie for more details.
+.ie n .IP """Compress::Raw::Bzip2""" 4
+.el .IP \f(CWCompress::Raw::Bzip2\fR 4
+.IX Item "Compress::Raw::Bzip2"
+This has been added to the core (version 2.020).
+.ie n .IP """parent""" 4
+.el .IP \f(CWparent\fR 4
+.IX Item "parent"
+This pragma establishes an ISA relationship with base classes at compile
+time. It provides the key feature of \f(CW\*(C`base\*(C'\fR without the feature creep.
+.ie n .IP """Parse::CPAN::Meta""" 4
+.el .IP \f(CWParse::CPAN::Meta\fR 4
+.IX Item "Parse::CPAN::Meta"
+This has been added to the core (version 1.39).
+.SS "Pragmata Changes"
+.IX Subsection "Pragmata Changes"
+.ie n .IP """attributes""" 4
+.el .IP \f(CWattributes\fR 4
+.IX Item "attributes"
+Upgraded from version 0.08 to 0.09.
+.ie n .IP """attrs""" 4
+.el .IP \f(CWattrs\fR 4
+.IX Item "attrs"
+Upgraded from version 1.02 to 1.03.
+.ie n .IP """base""" 4
+.el .IP \f(CWbase\fR 4
+.IX Item "base"
+Upgraded from version 2.13 to 2.14. See parent for a replacement.
+.ie n .IP """bigint""" 4
+.el .IP \f(CWbigint\fR 4
+.IX Item "bigint"
+Upgraded from version 0.22 to 0.23.
+.ie n .IP """bignum""" 4
+.el .IP \f(CWbignum\fR 4
+.IX Item "bignum"
+Upgraded from version 0.22 to 0.23.
+.ie n .IP """bigrat""" 4
+.el .IP \f(CWbigrat\fR 4
+.IX Item "bigrat"
+Upgraded from version 0.22 to 0.23.
+.ie n .IP """charnames""" 4
+.el .IP \f(CWcharnames\fR 4
+.IX Item "charnames"
+Upgraded from version 1.06 to 1.07.
+.Sp
+The Unicode \fINameAliases.txt\fR database file has been added. This has the
+effect of adding some extra \f(CW\*(C`\eN\*(C'\fR character names that formerly wouldn't
+have been recognised; for example, \f(CW"\eN{LATIN CAPITAL LETTER GHA}"\fR.
+.ie n .IP """constant""" 4
+.el .IP \f(CWconstant\fR 4
+.IX Item "constant"
+Upgraded from version 1.13 to 1.17.
+.ie n .IP """feature""" 4
+.el .IP \f(CWfeature\fR 4
+.IX Item "feature"
+The meaning of the \f(CW\*(C`:5.10\*(C'\fR and \f(CW\*(C`:5.10.X\*(C'\fR feature bundles has
+changed slightly. The last component, if any (i.e. \f(CW\*(C`X\*(C'\fR) is simply ignored.
+This is predicated on the assumption that new features will not, in
+general, be added to maintenance releases. So \f(CW\*(C`:5.10\*(C'\fR and \f(CW\*(C`:5.10.X\*(C'\fR
+have identical effect. This is a change to the behaviour documented for
+5.10.0.
+.ie n .IP """fields""" 4
+.el .IP \f(CWfields\fR 4
+.IX Item "fields"
+Upgraded from version 2.13 to 2.14 (this was just a version bump; there
+were no functional changes).
+.ie n .IP """lib""" 4
+.el .IP \f(CWlib\fR 4
+.IX Item "lib"
+Upgraded from version 0.5565 to 0.62.
+.ie n .IP """open""" 4
+.el .IP \f(CWopen\fR 4
+.IX Item "open"
+Upgraded from version 1.06 to 1.07.
+.ie n .IP """overload""" 4
+.el .IP \f(CWoverload\fR 4
+.IX Item "overload"
+Upgraded from version 1.06 to 1.07.
+.ie n .IP """overloading""" 4
+.el .IP \f(CWoverloading\fR 4
+.IX Item "overloading"
+See "The \f(CW\*(C`overloading\*(C'\fR pragma" above.
+.ie n .IP """version""" 4
+.el .IP \f(CWversion\fR 4
+.IX Item "version"
+Upgraded from version 0.74 to 0.77.
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+.ie n .IP """Archive::Extract""" 4
+.el .IP \f(CWArchive::Extract\fR 4
+.IX Item "Archive::Extract"
+Upgraded from version 0.24 to 0.34.
+.ie n .IP """Archive::Tar""" 4
+.el .IP \f(CWArchive::Tar\fR 4
+.IX Item "Archive::Tar"
+Upgraded from version 1.38 to 1.52.
+.ie n .IP """Attribute::Handlers""" 4
+.el .IP \f(CWAttribute::Handlers\fR 4
+.IX Item "Attribute::Handlers"
+Upgraded from version 0.79 to 0.85.
+.ie n .IP """AutoLoader""" 4
+.el .IP \f(CWAutoLoader\fR 4
+.IX Item "AutoLoader"
+Upgraded from version 5.63 to 5.68.
+.ie n .IP """AutoSplit""" 4
+.el .IP \f(CWAutoSplit\fR 4
+.IX Item "AutoSplit"
+Upgraded from version 1.05 to 1.06.
+.ie n .IP """B""" 4
+.el .IP \f(CWB\fR 4
+.IX Item "B"
+Upgraded from version 1.17 to 1.22.
+.ie n .IP """B::Debug""" 4
+.el .IP \f(CWB::Debug\fR 4
+.IX Item "B::Debug"
+Upgraded from version 1.05 to 1.11.
+.ie n .IP """B::Deparse""" 4
+.el .IP \f(CWB::Deparse\fR 4
+.IX Item "B::Deparse"
+Upgraded from version 0.83 to 0.89.
+.ie n .IP """B::Lint""" 4
+.el .IP \f(CWB::Lint\fR 4
+.IX Item "B::Lint"
+Upgraded from version 1.09 to 1.11.
+.ie n .IP """B::Xref""" 4
+.el .IP \f(CWB::Xref\fR 4
+.IX Item "B::Xref"
+Upgraded from version 1.01 to 1.02.
+.ie n .IP """Benchmark""" 4
+.el .IP \f(CWBenchmark\fR 4
+.IX Item "Benchmark"
+Upgraded from version 1.10 to 1.11.
+.ie n .IP """Carp""" 4
+.el .IP \f(CWCarp\fR 4
+.IX Item "Carp"
+Upgraded from version 1.08 to 1.11.
+.ie n .IP """CGI""" 4
+.el .IP \f(CWCGI\fR 4
+.IX Item "CGI"
+Upgraded from version 3.29 to 3.43.
+(also includes the "default_value for \fBpopup_menu()\fR" fix from 3.45).
+.ie n .IP """Compress::Zlib""" 4
+.el .IP \f(CWCompress::Zlib\fR 4
+.IX Item "Compress::Zlib"
+Upgraded from version 2.008 to 2.020.
+.ie n .IP """CPAN""" 4
+.el .IP \f(CWCPAN\fR 4
+.IX Item "CPAN"
+Upgraded from version 1.9205 to 1.9402. \f(CW\*(C`CPAN::FTP\*(C'\fR has a local fix to
+stop it being too verbose on download failure.
+.ie n .IP """CPANPLUS""" 4
+.el .IP \f(CWCPANPLUS\fR 4
+.IX Item "CPANPLUS"
+Upgraded from version 0.84 to 0.88.
+.ie n .IP """CPANPLUS::Dist::Build""" 4
+.el .IP \f(CWCPANPLUS::Dist::Build\fR 4
+.IX Item "CPANPLUS::Dist::Build"
+Upgraded from version 0.06_02 to 0.36.
+.ie n .IP """Cwd""" 4
+.el .IP \f(CWCwd\fR 4
+.IX Item "Cwd"
+Upgraded from version 3.25_01 to 3.30.
+.ie n .IP """Data::Dumper""" 4
+.el .IP \f(CWData::Dumper\fR 4
+.IX Item "Data::Dumper"
+Upgraded from version 2.121_14 to 2.124.
+.ie n .IP """DB""" 4
+.el .IP \f(CWDB\fR 4
+.IX Item "DB"
+Upgraded from version 1.01 to 1.02.
+.ie n .IP """DB_File""" 4
+.el .IP \f(CWDB_File\fR 4
+.IX Item "DB_File"
+Upgraded from version 1.816_1 to 1.820.
+.ie n .IP """Devel::PPPort""" 4
+.el .IP \f(CWDevel::PPPort\fR 4
+.IX Item "Devel::PPPort"
+Upgraded from version 3.13 to 3.19.
+.ie n .IP """Digest::MD5""" 4
+.el .IP \f(CWDigest::MD5\fR 4
+.IX Item "Digest::MD5"
+Upgraded from version 2.36_01 to 2.39.
+.ie n .IP """Digest::SHA""" 4
+.el .IP \f(CWDigest::SHA\fR 4
+.IX Item "Digest::SHA"
+Upgraded from version 5.45 to 5.47.
+.ie n .IP """DirHandle""" 4
+.el .IP \f(CWDirHandle\fR 4
+.IX Item "DirHandle"
+Upgraded from version 1.01 to 1.03.
+.ie n .IP """Dumpvalue""" 4
+.el .IP \f(CWDumpvalue\fR 4
+.IX Item "Dumpvalue"
+Upgraded from version 1.12 to 1.13.
+.ie n .IP """DynaLoader""" 4
+.el .IP \f(CWDynaLoader\fR 4
+.IX Item "DynaLoader"
+Upgraded from version 1.08 to 1.10.
+.ie n .IP """Encode""" 4
+.el .IP \f(CWEncode\fR 4
+.IX Item "Encode"
+Upgraded from version 2.23 to 2.35.
+.ie n .IP """Errno""" 4
+.el .IP \f(CWErrno\fR 4
+.IX Item "Errno"
+Upgraded from version 1.10 to 1.11.
+.ie n .IP """Exporter""" 4
+.el .IP \f(CWExporter\fR 4
+.IX Item "Exporter"
+Upgraded from version 5.62 to 5.63.
+.ie n .IP """ExtUtils::CBuilder""" 4
+.el .IP \f(CWExtUtils::CBuilder\fR 4
+.IX Item "ExtUtils::CBuilder"
+Upgraded from version 0.21 to 0.2602.
+.ie n .IP """ExtUtils::Command""" 4
+.el .IP \f(CWExtUtils::Command\fR 4
+.IX Item "ExtUtils::Command"
+Upgraded from version 1.13 to 1.16.
+.ie n .IP """ExtUtils::Constant""" 4
+.el .IP \f(CWExtUtils::Constant\fR 4
+.IX Item "ExtUtils::Constant"
+Upgraded from 0.20 to 0.22. (Note that neither of these versions are
+available on CPAN.)
+.ie n .IP """ExtUtils::Embed""" 4
+.el .IP \f(CWExtUtils::Embed\fR 4
+.IX Item "ExtUtils::Embed"
+Upgraded from version 1.27 to 1.28.
+.ie n .IP """ExtUtils::Install""" 4
+.el .IP \f(CWExtUtils::Install\fR 4
+.IX Item "ExtUtils::Install"
+Upgraded from version 1.44 to 1.54.
+.ie n .IP """ExtUtils::MakeMaker""" 4
+.el .IP \f(CWExtUtils::MakeMaker\fR 4
+.IX Item "ExtUtils::MakeMaker"
+Upgraded from version 6.42 to 6.55_02.
+.Sp
+Note that \f(CW\*(C`ExtUtils::MakeMaker::bytes\*(C'\fR and \f(CW\*(C`ExtUtils::MakeMaker::vmsish\*(C'\fR
+have been removed from this distribution.
+.ie n .IP """ExtUtils::Manifest""" 4
+.el .IP \f(CWExtUtils::Manifest\fR 4
+.IX Item "ExtUtils::Manifest"
+Upgraded from version 1.51_01 to 1.56.
+.ie n .IP """ExtUtils::ParseXS""" 4
+.el .IP \f(CWExtUtils::ParseXS\fR 4
+.IX Item "ExtUtils::ParseXS"
+Upgraded from version 2.18_02 to 2.2002.
+.ie n .IP """Fatal""" 4
+.el .IP \f(CWFatal\fR 4
+.IX Item "Fatal"
+Upgraded from version 1.05 to 2.06_01. See also the new pragma \f(CW\*(C`autodie\*(C'\fR.
+.ie n .IP """File::Basename""" 4
+.el .IP \f(CWFile::Basename\fR 4
+.IX Item "File::Basename"
+Upgraded from version 2.76 to 2.77.
+.ie n .IP """File::Compare""" 4
+.el .IP \f(CWFile::Compare\fR 4
+.IX Item "File::Compare"
+Upgraded from version 1.1005 to 1.1006.
+.ie n .IP """File::Copy""" 4
+.el .IP \f(CWFile::Copy\fR 4
+.IX Item "File::Copy"
+Upgraded from version 2.11 to 2.14.
+.ie n .IP """File::Fetch""" 4
+.el .IP \f(CWFile::Fetch\fR 4
+.IX Item "File::Fetch"
+Upgraded from version 0.14 to 0.20.
+.ie n .IP """File::Find""" 4
+.el .IP \f(CWFile::Find\fR 4
+.IX Item "File::Find"
+Upgraded from version 1.12 to 1.14.
+.ie n .IP """File::Path""" 4
+.el .IP \f(CWFile::Path\fR 4
+.IX Item "File::Path"
+Upgraded from version 2.04 to 2.07_03.
+.ie n .IP """File::Spec""" 4
+.el .IP \f(CWFile::Spec\fR 4
+.IX Item "File::Spec"
+Upgraded from version 3.2501 to 3.30.
+.ie n .IP """File::stat""" 4
+.el .IP \f(CWFile::stat\fR 4
+.IX Item "File::stat"
+Upgraded from version 1.00 to 1.01.
+.ie n .IP """File::Temp""" 4
+.el .IP \f(CWFile::Temp\fR 4
+.IX Item "File::Temp"
+Upgraded from version 0.18 to 0.22.
+.ie n .IP """FileCache""" 4
+.el .IP \f(CWFileCache\fR 4
+.IX Item "FileCache"
+Upgraded from version 1.07 to 1.08.
+.ie n .IP """FileHandle""" 4
+.el .IP \f(CWFileHandle\fR 4
+.IX Item "FileHandle"
+Upgraded from version 2.01 to 2.02.
+.ie n .IP """Filter::Simple""" 4
+.el .IP \f(CWFilter::Simple\fR 4
+.IX Item "Filter::Simple"
+Upgraded from version 0.82 to 0.84.
+.ie n .IP """Filter::Util::Call""" 4
+.el .IP \f(CWFilter::Util::Call\fR 4
+.IX Item "Filter::Util::Call"
+Upgraded from version 1.07 to 1.08.
+.ie n .IP """FindBin""" 4
+.el .IP \f(CWFindBin\fR 4
+.IX Item "FindBin"
+Upgraded from version 1.49 to 1.50.
+.ie n .IP """GDBM_File""" 4
+.el .IP \f(CWGDBM_File\fR 4
+.IX Item "GDBM_File"
+Upgraded from version 1.08 to 1.09.
+.ie n .IP """Getopt::Long""" 4
+.el .IP \f(CWGetopt::Long\fR 4
+.IX Item "Getopt::Long"
+Upgraded from version 2.37 to 2.38.
+.ie n .IP """Hash::Util::FieldHash""" 4
+.el .IP \f(CWHash::Util::FieldHash\fR 4
+.IX Item "Hash::Util::FieldHash"
+Upgraded from version 1.03 to 1.04. This fixes a memory leak.
+.ie n .IP """I18N::Collate""" 4
+.el .IP \f(CWI18N::Collate\fR 4
+.IX Item "I18N::Collate"
+Upgraded from version 1.00 to 1.01.
+.ie n .IP """IO""" 4
+.el .IP \f(CWIO\fR 4
+.IX Item "IO"
+Upgraded from version 1.23_01 to 1.25.
+.Sp
+This makes non-blocking mode work on Windows in \f(CW\*(C`IO::Socket::INET\*(C'\fR
+[CPAN #43573].
+.ie n .IP """IO::Compress::*""" 4
+.el .IP \f(CWIO::Compress::*\fR 4
+.IX Item "IO::Compress::*"
+Upgraded from version 2.008 to 2.020.
+.ie n .IP """IO::Dir""" 4
+.el .IP \f(CWIO::Dir\fR 4
+.IX Item "IO::Dir"
+Upgraded from version 1.06 to 1.07.
+.ie n .IP """IO::Handle""" 4
+.el .IP \f(CWIO::Handle\fR 4
+.IX Item "IO::Handle"
+Upgraded from version 1.27 to 1.28.
+.ie n .IP """IO::Socket""" 4
+.el .IP \f(CWIO::Socket\fR 4
+.IX Item "IO::Socket"
+Upgraded from version 1.30_01 to 1.31.
+.ie n .IP """IO::Zlib""" 4
+.el .IP \f(CWIO::Zlib\fR 4
+.IX Item "IO::Zlib"
+Upgraded from version 1.07 to 1.09.
+.ie n .IP """IPC::Cmd""" 4
+.el .IP \f(CWIPC::Cmd\fR 4
+.IX Item "IPC::Cmd"
+Upgraded from version 0.40_1 to 0.46.
+.ie n .IP """IPC::Open3""" 4
+.el .IP \f(CWIPC::Open3\fR 4
+.IX Item "IPC::Open3"
+Upgraded from version 1.02 to 1.04.
+.ie n .IP """IPC::SysV""" 4
+.el .IP \f(CWIPC::SysV\fR 4
+.IX Item "IPC::SysV"
+Upgraded from version 1.05 to 2.01.
+.ie n .IP """lib""" 4
+.el .IP \f(CWlib\fR 4
+.IX Item "lib"
+Upgraded from version 0.5565 to 0.62.
+.ie n .IP """List::Util""" 4
+.el .IP \f(CWList::Util\fR 4
+.IX Item "List::Util"
+Upgraded from version 1.19 to 1.21.
+.ie n .IP """Locale::MakeText""" 4
+.el .IP \f(CWLocale::MakeText\fR 4
+.IX Item "Locale::MakeText"
+Upgraded from version 1.12 to 1.13.
+.ie n .IP """Log::Message""" 4
+.el .IP \f(CWLog::Message\fR 4
+.IX Item "Log::Message"
+Upgraded from version 0.01 to 0.02.
+.ie n .IP """Math::BigFloat""" 4
+.el .IP \f(CWMath::BigFloat\fR 4
+.IX Item "Math::BigFloat"
+Upgraded from version 1.59 to 1.60.
+.ie n .IP """Math::BigInt""" 4
+.el .IP \f(CWMath::BigInt\fR 4
+.IX Item "Math::BigInt"
+Upgraded from version 1.88 to 1.89.
+.ie n .IP """Math::BigInt::FastCalc""" 4
+.el .IP \f(CWMath::BigInt::FastCalc\fR 4
+.IX Item "Math::BigInt::FastCalc"
+Upgraded from version 0.16 to 0.19.
+.ie n .IP """Math::BigRat""" 4
+.el .IP \f(CWMath::BigRat\fR 4
+.IX Item "Math::BigRat"
+Upgraded from version 0.21 to 0.22.
+.ie n .IP """Math::Complex""" 4
+.el .IP \f(CWMath::Complex\fR 4
+.IX Item "Math::Complex"
+Upgraded from version 1.37 to 1.56.
+.ie n .IP """Math::Trig""" 4
+.el .IP \f(CWMath::Trig\fR 4
+.IX Item "Math::Trig"
+Upgraded from version 1.04 to 1.20.
+.ie n .IP """Memoize""" 4
+.el .IP \f(CWMemoize\fR 4
+.IX Item "Memoize"
+Upgraded from version 1.01_02 to 1.01_03 (just a minor documentation
+change).
+.ie n .IP """Module::Build""" 4
+.el .IP \f(CWModule::Build\fR 4
+.IX Item "Module::Build"
+Upgraded from version 0.2808_01 to 0.34_02.
+.ie n .IP """Module::CoreList""" 4
+.el .IP \f(CWModule::CoreList\fR 4
+.IX Item "Module::CoreList"
+Upgraded from version 2.13 to 2.18. This release no longer contains the
+\&\f(CW%Module::CoreList::patchlevel\fR hash.
+.ie n .IP """Module::Load""" 4
+.el .IP \f(CWModule::Load\fR 4
+.IX Item "Module::Load"
+Upgraded from version 0.12 to 0.16.
+.ie n .IP """Module::Load::Conditional""" 4
+.el .IP \f(CWModule::Load::Conditional\fR 4
+.IX Item "Module::Load::Conditional"
+Upgraded from version 0.22 to 0.30.
+.ie n .IP """Module::Loaded""" 4
+.el .IP \f(CWModule::Loaded\fR 4
+.IX Item "Module::Loaded"
+Upgraded from version 0.01 to 0.02.
+.ie n .IP """Module::Pluggable""" 4
+.el .IP \f(CWModule::Pluggable\fR 4
+.IX Item "Module::Pluggable"
+Upgraded from version 3.6 to 3.9.
+.ie n .IP """NDBM_File""" 4
+.el .IP \f(CWNDBM_File\fR 4
+.IX Item "NDBM_File"
+Upgraded from version 1.07 to 1.08.
+.ie n .IP """Net::Ping""" 4
+.el .IP \f(CWNet::Ping\fR 4
+.IX Item "Net::Ping"
+Upgraded from version 2.33 to 2.36.
+.ie n .IP """NEXT""" 4
+.el .IP \f(CWNEXT\fR 4
+.IX Item "NEXT"
+Upgraded from version 0.60_01 to 0.64.
+.ie n .IP """Object::Accessor""" 4
+.el .IP \f(CWObject::Accessor\fR 4
+.IX Item "Object::Accessor"
+Upgraded from version 0.32 to 0.34.
+.ie n .IP """OS2::REXX""" 4
+.el .IP \f(CWOS2::REXX\fR 4
+.IX Item "OS2::REXX"
+Upgraded from version 1.03 to 1.04.
+.ie n .IP """Package::Constants""" 4
+.el .IP \f(CWPackage::Constants\fR 4
+.IX Item "Package::Constants"
+Upgraded from version 0.01 to 0.02.
+.ie n .IP """PerlIO""" 4
+.el .IP \f(CWPerlIO\fR 4
+.IX Item "PerlIO"
+Upgraded from version 1.04 to 1.06.
+.ie n .IP """PerlIO::via""" 4
+.el .IP \f(CWPerlIO::via\fR 4
+.IX Item "PerlIO::via"
+Upgraded from version 0.04 to 0.07.
+.ie n .IP """Pod::Man""" 4
+.el .IP \f(CWPod::Man\fR 4
+.IX Item "Pod::Man"
+Upgraded from version 2.16 to 2.22.
+.ie n .IP """Pod::Parser""" 4
+.el .IP \f(CWPod::Parser\fR 4
+.IX Item "Pod::Parser"
+Upgraded from version 1.35 to 1.37.
+.ie n .IP """Pod::Simple""" 4
+.el .IP \f(CWPod::Simple\fR 4
+.IX Item "Pod::Simple"
+Upgraded from version 3.05 to 3.07.
+.ie n .IP """Pod::Text""" 4
+.el .IP \f(CWPod::Text\fR 4
+.IX Item "Pod::Text"
+Upgraded from version 3.08 to 3.13.
+.ie n .IP """POSIX""" 4
+.el .IP \f(CWPOSIX\fR 4
+.IX Item "POSIX"
+Upgraded from version 1.13 to 1.17.
+.ie n .IP """Safe""" 4
+.el .IP \f(CWSafe\fR 4
+.IX Item "Safe"
+Upgraded from 2.12 to 2.18.
+.ie n .IP """Scalar::Util""" 4
+.el .IP \f(CWScalar::Util\fR 4
+.IX Item "Scalar::Util"
+Upgraded from version 1.19 to 1.21.
+.ie n .IP """SelectSaver""" 4
+.el .IP \f(CWSelectSaver\fR 4
+.IX Item "SelectSaver"
+Upgraded from 1.01 to 1.02.
+.ie n .IP """SelfLoader""" 4
+.el .IP \f(CWSelfLoader\fR 4
+.IX Item "SelfLoader"
+Upgraded from 1.11 to 1.17.
+.ie n .IP """Socket""" 4
+.el .IP \f(CWSocket\fR 4
+.IX Item "Socket"
+Upgraded from 1.80 to 1.82.
+.ie n .IP """Storable""" 4
+.el .IP \f(CWStorable\fR 4
+.IX Item "Storable"
+Upgraded from 2.18 to 2.20.
+.ie n .IP """Switch""" 4
+.el .IP \f(CWSwitch\fR 4
+.IX Item "Switch"
+Upgraded from version 2.13 to 2.14. Please see "Deprecations".
+.ie n .IP """Symbol""" 4
+.el .IP \f(CWSymbol\fR 4
+.IX Item "Symbol"
+Upgraded from version 1.06 to 1.07.
+.ie n .IP """Sys::Syslog""" 4
+.el .IP \f(CWSys::Syslog\fR 4
+.IX Item "Sys::Syslog"
+Upgraded from version 0.22 to 0.27.
+.ie n .IP """Term::ANSIColor""" 4
+.el .IP \f(CWTerm::ANSIColor\fR 4
+.IX Item "Term::ANSIColor"
+Upgraded from version 1.12 to 2.00.
+.ie n .IP """Term::ReadLine""" 4
+.el .IP \f(CWTerm::ReadLine\fR 4
+.IX Item "Term::ReadLine"
+Upgraded from version 1.03 to 1.04.
+.ie n .IP """Term::UI""" 4
+.el .IP \f(CWTerm::UI\fR 4
+.IX Item "Term::UI"
+Upgraded from version 0.18 to 0.20.
+.ie n .IP """Test::Harness""" 4
+.el .IP \f(CWTest::Harness\fR 4
+.IX Item "Test::Harness"
+Upgraded from version 2.64 to 3.17.
+.Sp
+Note that one side-effect of the 2.x to 3.x upgrade is that the
+experimental \f(CW\*(C`Test::Harness::Straps\*(C'\fR module (and its supporting
+\&\f(CW\*(C`Assert\*(C'\fR, \f(CW\*(C`Iterator\*(C'\fR, \f(CW\*(C`Point\*(C'\fR and \f(CW\*(C`Results\*(C'\fR modules) have been
+removed. If you still need this, then they are available in the
+(unmaintained) \f(CW\*(C`Test\-Harness\-Straps\*(C'\fR distribution on CPAN.
+.ie n .IP """Test::Simple""" 4
+.el .IP \f(CWTest::Simple\fR 4
+.IX Item "Test::Simple"
+Upgraded from version 0.72 to 0.92.
+.ie n .IP """Text::ParseWords""" 4
+.el .IP \f(CWText::ParseWords\fR 4
+.IX Item "Text::ParseWords"
+Upgraded from version 3.26 to 3.27.
+.ie n .IP """Text::Tabs""" 4
+.el .IP \f(CWText::Tabs\fR 4
+.IX Item "Text::Tabs"
+Upgraded from version 2007.1117 to 2009.0305.
+.ie n .IP """Text::Wrap""" 4
+.el .IP \f(CWText::Wrap\fR 4
+.IX Item "Text::Wrap"
+Upgraded from version 2006.1117 to 2009.0305.
+.ie n .IP """Thread::Queue""" 4
+.el .IP \f(CWThread::Queue\fR 4
+.IX Item "Thread::Queue"
+Upgraded from version 2.00 to 2.11.
+.ie n .IP """Thread::Semaphore""" 4
+.el .IP \f(CWThread::Semaphore\fR 4
+.IX Item "Thread::Semaphore"
+Upgraded from version 2.01 to 2.09.
+.ie n .IP """threads""" 4
+.el .IP \f(CWthreads\fR 4
+.IX Item "threads"
+Upgraded from version 1.67 to 1.72.
+.ie n .IP """threads::shared""" 4
+.el .IP \f(CWthreads::shared\fR 4
+.IX Item "threads::shared"
+Upgraded from version 1.14 to 1.29.
+.ie n .IP """Tie::RefHash""" 4
+.el .IP \f(CWTie::RefHash\fR 4
+.IX Item "Tie::RefHash"
+Upgraded from version 1.37 to 1.38.
+.ie n .IP """Tie::StdHandle""" 4
+.el .IP \f(CWTie::StdHandle\fR 4
+.IX Item "Tie::StdHandle"
+This has documentation changes, and has been assigned a version for the
+first time: version 4.2.
+.ie n .IP """Time::HiRes""" 4
+.el .IP \f(CWTime::HiRes\fR 4
+.IX Item "Time::HiRes"
+Upgraded from version 1.9711 to 1.9719.
+.ie n .IP """Time::Local""" 4
+.el .IP \f(CWTime::Local\fR 4
+.IX Item "Time::Local"
+Upgraded from version 1.18 to 1.1901.
+.ie n .IP """Time::Piece""" 4
+.el .IP \f(CWTime::Piece\fR 4
+.IX Item "Time::Piece"
+Upgraded from version 1.12 to 1.15.
+.ie n .IP """Unicode::Normalize""" 4
+.el .IP \f(CWUnicode::Normalize\fR 4
+.IX Item "Unicode::Normalize"
+Upgraded from version 1.02 to 1.03.
+.ie n .IP """Unicode::UCD""" 4
+.el .IP \f(CWUnicode::UCD\fR 4
+.IX Item "Unicode::UCD"
+Upgraded from version 0.25 to 0.27.
+.Sp
+\&\f(CWcharinfo()\fR now works on Unified CJK code points added to later versions
+of Unicode.
+.Sp
+\&\f(CWcasefold()\fR has new fields returned to provide both a simpler interface
+and previously missing information. The old fields are retained for
+backwards compatibility. Information about Turkic-specific code points is
+now returned.
+.Sp
+The documentation has been corrected and expanded.
+.ie n .IP """UNIVERSAL""" 4
+.el .IP \f(CWUNIVERSAL\fR 4
+.IX Item "UNIVERSAL"
+Upgraded from version 1.04 to 1.05.
+.ie n .IP """Win32""" 4
+.el .IP \f(CWWin32\fR 4
+.IX Item "Win32"
+Upgraded from version 0.34 to 0.39.
+.ie n .IP """Win32API::File""" 4
+.el .IP \f(CWWin32API::File\fR 4
+.IX Item "Win32API::File"
+Upgraded from version 0.1001_01 to 0.1101.
+.ie n .IP """XSLoader""" 4
+.el .IP \f(CWXSLoader\fR 4
+.IX Item "XSLoader"
+Upgraded from version 0.08 to 0.10.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.IP \fIh2ph\fR 4
+.IX Item "h2ph"
+Now looks in \f(CW\*(C`include\-fixed\*(C'\fR too, which is a recent addition to gcc's
+search path.
+.IP \fIh2xs\fR 4
+.IX Item "h2xs"
+No longer incorrectly treats enum values like macros (Daniel Burr).
+.Sp
+Now handles C++ style constants (\f(CW\*(C`//\*(C'\fR) properly in enums. (A patch from
+Rainer Weikusat was used; Daniel Burr also proposed a similar fix).
+.IP \fIperl5db.pl\fR 4
+.IX Item "perl5db.pl"
+\&\f(CW\*(C`LVALUE\*(C'\fR subroutines now work under the debugger.
+.Sp
+The debugger now correctly handles proxy constant subroutines, and
+subroutine stubs.
+.IP \fIperlthanks\fR 4
+.IX Item "perlthanks"
+Perl 5.10.1 adds a new utility \fIperlthanks\fR, which is a variant of
+\&\fIperlbug\fR, but for sending non-bug-reports to the authors and maintainers
+of Perl. Getting nothing but bug reports can become a bit demoralising:
+we'll see if this changes things.
+.SH "New Documentation"
+.IX Header "New Documentation"
+.IP perlhaiku 4
+.IX Item "perlhaiku"
+This contains instructions on how to build perl for the Haiku platform.
+.IP perlmroapi 4
+.IX Item "perlmroapi"
+This describes the new interface for pluggable Method Resolution Orders.
+.IP perlperf 4
+.IX Item "perlperf"
+This document, by Richard Foley, provides an introduction to the use of
+performance and optimization techniques which can be used with particular
+reference to perl programs.
+.IP perlrepository 4
+.IX Item "perlrepository"
+This describes how to access the perl source using the \fIgit\fR version
+control system.
+.IP perlthanks 4
+.IX Item "perlthanks"
+This describes the new \fIperlthanks\fR utility.
+.SH "Changes to Existing Documentation"
+.IX Header "Changes to Existing Documentation"
+The various large \f(CW\*(C`Changes*\*(C'\fR files (which listed every change made to perl
+over the last 18 years) have been removed, and replaced by a small file,
+also called \f(CW\*(C`Changes\*(C'\fR, which just explains how that same information may
+be extracted from the git version control system.
+.PP
+The file \fIPorting/patching.pod\fR has been deleted, as it mainly described
+interacting with the old Perforce-based repository, which is now obsolete.
+Information still relevant has been moved to perlrepository.
+.PP
+perlapi, perlintern, perlmodlib and perltoc are now all
+generated at build time, rather than being shipped as part of the release.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+A new internal cache means that \f(CWisa()\fR will often be faster.
+.IP \(bu 4
+Under \f(CW\*(C`use locale\*(C'\fR, the locale-relevant information is now cached on
+read-only values, such as the list returned by \f(CW\*(C`keys %hash\*(C'\fR. This makes
+operations such as \f(CW\*(C`sort keys %hash\*(C'\fR in the scope of \f(CW\*(C`use locale\*(C'\fR much
+faster.
+.IP \(bu 4
+Empty \f(CW\*(C`DESTROY\*(C'\fR methods are no longer called.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "\fIext/\fP reorganisation"
+.IX Subsection "ext/ reorganisation"
+The layout of directories in \fIext\fR has been revised. Specifically, all
+extensions are now flat, and at the top level, with \f(CW\*(C`/\*(C'\fR in pathnames
+replaced by \f(CW\*(C`\-\*(C'\fR, so that \fIext/Data/Dumper/\fR is now \fIext/Data\-Dumper/\fR,
+etc.  The names of the extensions as specified to \fIConfigure\fR, and as
+reported by \f(CW%Config::Config\fR under the keys \f(CW\*(C`dynamic_ext\*(C'\fR,
+\&\f(CW\*(C`known_extensions\*(C'\fR, \f(CW\*(C`nonxs_ext\*(C'\fR and \f(CW\*(C`static_ext\*(C'\fR have not changed, and
+still use \f(CW\*(C`/\*(C'\fR. Hence this change will not have any affect once perl is
+installed. However, \f(CW\*(C`Attribute::Handlers\*(C'\fR, \f(CW\*(C`Safe\*(C'\fR and \f(CW\*(C`mro\*(C'\fR have now
+become extensions in their own right, so if you run \fIConfigure\fR with
+options to specify an exact list of extensions to build, you will need to
+change it to account for this.
+.PP
+For 5.10.2, it is planned that many dual-life modules will have been moved
+from \fIlib\fR to \fIext\fR; again this will have no effect on an installed
+perl, but will matter if you invoke \fIConfigure\fR with a pre-canned list of
+extensions to build.
+.SS "Configuration improvements"
+.IX Subsection "Configuration improvements"
+If \f(CW\*(C`vendorlib\*(C'\fR and \f(CW\*(C`vendorarch\*(C'\fR are the same, then they are only added to
+\&\f(CW@INC\fR once.
+.PP
+\&\f(CW$Config{usedevel}\fR and the C\-level \f(CW\*(C`PERL_USE_DEVEL\*(C'\fR are now defined if
+perl is built with  \f(CW\*(C`\-Dusedevel\*(C'\fR.
+.PP
+\&\fIConfigure\fR will enable use of \f(CW\*(C`\-fstack\-protector\*(C'\fR, to provide protection
+against stack-smashing attacks, if the compiler supports it.
+.PP
+\&\fIConfigure\fR will now determine the correct prototypes for re-entrant
+functions, and for \f(CW\*(C`gconvert\*(C'\fR, if you are using a C++ compiler rather
+than a C compiler.
+.PP
+On Unix, if you build from a tree containing a git repository, the
+configuration process will note the commit hash you have checked out, for
+display in the output of \f(CW\*(C`perl \-v\*(C'\fR and \f(CW\*(C`perl \-V\*(C'\fR. Unpushed local commits
+are automatically added to the list of local patches displayed by
+\&\f(CW\*(C`perl \-V\*(C'\fR.
+.SS "Compilation improvements"
+.IX Subsection "Compilation improvements"
+As part of the flattening of \fIext\fR, all extensions on all platforms are
+built by \fImake_ext.pl\fR. This replaces the Unix-specific
+\&\fIext/util/make_ext\fR, VMS-specific \fImake_ext.com\fR and Win32\-specific
+\&\fIwin32/buildext.pl\fR.
+.SS "Platform Specific Changes"
+.IX Subsection "Platform Specific Changes"
+.IP AIX 4
+.IX Item "AIX"
+Removed \fIlibbsd\fR for AIX 5L and 6.1. Only \fBflock()\fR was used from \fIlibbsd\fR.
+.Sp
+Removed \fIlibgdbm\fR for AIX 5L and 6.1. The \fIlibgdbm\fR is delivered as an
+optional package with the AIX Toolbox. Unfortunately the 64 bit version 
+is broken.
+.Sp
+Hints changes mean that AIX 4.2 should work again.
+.IP Cygwin 4
+.IX Item "Cygwin"
+On Cygwin we now strip the last number from the DLL. This has been the
+behaviour in the cygwin.com build for years. The hints files have been
+updated.
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+The hints files now identify the correct threading libraries on FreeBSD 7
+and later.
+.IP Irix 4
+.IX Item "Irix"
+We now work around a bizarre preprocessor bug in the Irix 6.5 compiler:
+\&\f(CW\*(C`cc \-E \-\*(C'\fR unfortunately goes into K&R mode, but \f(CW\*(C`cc \-E file.c\*(C'\fR doesn't.
+.IP Haiku 4
+.IX Item "Haiku"
+Patches from the Haiku maintainers have been merged in. Perl should now
+build on Haiku.
+.IP "MirOS BSD" 4
+.IX Item "MirOS BSD"
+Perl should now build on MirOS BSD.
+.IP NetBSD 4
+.IX Item "NetBSD"
+Hints now supports versions 5.*.
+.IP "Stratus VOS" 4
+.IX Item "Stratus VOS"
+Various changes from Stratus have been merged in.
+.IP Symbian 4
+.IX Item "Symbian"
+There is now support for Symbian S60 3.2 SDK and S60 5.0 SDK.
+.IP Win32 4
+.IX Item "Win32"
+Improved message window handling means that \f(CW\*(C`alarm\*(C'\fR and \f(CW\*(C`kill\*(C'\fR messages
+will no longer be dropped under race conditions.
+.IP VMS 4
+.IX Item "VMS"
+Reads from the in-memory temporary files of \f(CW\*(C`PerlIO::scalar\*(C'\fR used to fail
+if \f(CW$/\fR was set to a numeric reference (to indicate record-style reads).
+This is now fixed.
+.Sp
+VMS now supports \f(CW\*(C`getgrgid\*(C'\fR.
+.Sp
+Many improvements and cleanups have been made to the VMS file name handling
+and conversion code.
+.Sp
+Enabling the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR logical name now encodes a POSIX exit
+status in a VMS condition value for better interaction with GNV's bash
+shell and other utilities that depend on POSIX exit values.  See
+"$?" in perlvms for details.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+5.10.0 inadvertently disabled an optimisation, which caused a measurable
+performance drop in list assignment, such as is often used to assign
+function parameters from \f(CW@_\fR. The optimisation has been re-instated, and
+the performance regression fixed.
+.IP \(bu 4
+Fixed memory leak on \f(CW\*(C`while (1) { map 1, 1 }\*(C'\fR [RT #53038].
+.IP \(bu 4
+Some potential coredumps in PerlIO fixed [RT #57322,54828].
+.IP \(bu 4
+The debugger now works with lvalue subroutines.
+.IP \(bu 4
+The debugger's \f(CW\*(C`m\*(C'\fR command was broken on modules that defined constants
+[RT #61222].
+.IP \(bu 4
+\&\f(CWcrypt()\fR and string complement could return tainted values for untainted
+arguments [RT #59998].
+.IP \(bu 4
+The \f(CW\*(C`\-i.suffix\*(C'\fR command-line switch now recreates the file using
+restricted permissions, before changing its mode to match the original
+file. This eliminates a potential race condition [RT #60904].
+.IP \(bu 4
+On some Unix systems, the value in \f(CW$?\fR would not have the top bit set
+(\f(CW\*(C`$? & 128\*(C'\fR) even if the child core dumped.
+.IP \(bu 4
+Under some circumstances, $^R could incorrectly become undefined
+[RT #57042].
+.IP \(bu 4
+(XS) In various hash functions, passing a pre-computed hash to when the
+key is UTF\-8 might result in an incorrect lookup.
+.IP \(bu 4
+(XS) Including \fIXSUB.h\fR before \fIperl.h\fR gave a compile-time error
+[RT #57176].
+.IP \(bu 4
+\&\f(CW\*(C`$object\->isa(\*(AqFoo\*(Aq)\*(C'\fR would report false if the package \f(CW\*(C`Foo\*(C'\fR didn't
+exist, even if the object's \f(CW@ISA\fR contained \f(CW\*(C`Foo\*(C'\fR.
+.IP \(bu 4
+Various bugs in the new-to 5.10.0 mro code, triggered by manipulating
+\&\f(CW@ISA\fR, have been found and fixed.
+.IP \(bu 4
+Bitwise operations on references could crash the interpreter, e.g.
+\&\f(CW\*(C`$x=\e$y; $x |= "foo"\*(C'\fR [RT #54956].
+.IP \(bu 4
+Patterns including alternation might be sensitive to the internal UTF\-8
+representation, e.g.
+.Sp
+.Vb 3
+\&    my $byte = chr(192);
+\&    my $utf8 = chr(192); utf8::upgrade($utf8);
+\&    $utf8 =~ /$byte|X}/i;       # failed in 5.10.0
+.Ve
+.IP \(bu 4
+Within UTF8\-encoded Perl source files (i.e. where \f(CW\*(C`use utf8\*(C'\fR is in
+effect), double-quoted literal strings could be corrupted where a \f(CW\*(C`\exNN\*(C'\fR,
+\&\f(CW\*(C`\e0NNN\*(C'\fR or \f(CW\*(C`\eN{}\*(C'\fR is followed by a literal character with ordinal value
+greater than 255 [RT #59908].
+.IP \(bu 4
+\&\f(CW\*(C`B::Deparse\*(C'\fR failed to correctly deparse various constructs:
+\&\f(CW\*(C`readpipe STRING\*(C'\fR [RT #62428], \f(CWCORE::require(STRING)\fR [RT #62488],
+\&\f(CW\*(C`sub foo(_)\*(C'\fR [RT #62484].
+.IP \(bu 4
+Using \f(CWsetpgrp()\fR with no arguments could corrupt the perl stack.
+.IP \(bu 4
+The block form of \f(CW\*(C`eval\*(C'\fR is now specifically trappable by \f(CW\*(C`Safe\*(C'\fR and
+\&\f(CW\*(C`ops\*(C'\fR.  Previously it was erroneously treated like string \f(CW\*(C`eval\*(C'\fR.
+.IP \(bu 4
+In 5.10.0, the two characters \f(CW\*(C`[~\*(C'\fR were sometimes parsed as the smart
+match operator (\f(CW\*(C`~~\*(C'\fR) [RT #63854].
+.IP \(bu 4
+In 5.10.0, the \f(CW\*(C`*\*(C'\fR quantifier in patterns was sometimes treated as
+\&\f(CW\*(C`{0,32767}\*(C'\fR [RT #60034, #60464]. For example, this match would fail:
+.Sp
+.Vb 1
+\&    ("ab" x 32768) =~ /^(ab)*$/
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`shmget\*(C'\fR was limited to a 32 bit segment size on a 64 bit OS [RT #63924].
+.IP \(bu 4
+Using \f(CW\*(C`next\*(C'\fR or \f(CW\*(C`last\*(C'\fR to exit a \f(CW\*(C`given\*(C'\fR block no longer produces a
+spurious warning like the following:
+.Sp
+.Vb 1
+\&    Exiting given via last at foo.pl line 123
+.Ve
+.IP \(bu 4
+On Windows, \f(CW\*(Aq.\efoo\*(Aq\fR and \f(CW\*(Aq..\efoo\*(Aq\fR  were treated differently than
+\&\f(CW\*(Aq./foo\*(Aq\fR and \f(CW\*(Aq../foo\*(Aq\fR by \f(CW\*(C`do\*(C'\fR and \f(CW\*(C`require\*(C'\fR [RT #63492].
+.IP \(bu 4
+Assigning a format to a glob could corrupt the format; e.g.:
+.Sp
+.Vb 1
+\&     *bar=*foo{FORMAT}; # foo format now bad
+.Ve
+.IP \(bu 4
+Attempting to coerce a typeglob to a string or number could cause an
+assertion failure. The correct error message is now generated,
+\&\f(CW\*(C`Can\*(Aqt coerce GLOB to \fR\f(CI$type\fR\f(CW\*(C'\fR.
+.IP \(bu 4
+Under \f(CW\*(C`use filetest \*(Aqaccess\*(Aq\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR was using the wrong access mode. This
+has been fixed [RT #49003].
+.IP \(bu 4
+\&\f(CW\*(C`length\*(C'\fR on a tied scalar that returned a Unicode value would not be
+correct the first time. This has been fixed.
+.IP \(bu 4
+Using an array \f(CW\*(C`tie\*(C'\fR inside in array \f(CW\*(C`tie\*(C'\fR could SEGV. This has been
+fixed. [RT #51636]
+.IP \(bu 4
+A race condition inside \f(CWPerlIOStdio_close()\fR has been identified and
+fixed. This used to cause various threading issues, including SEGVs.
+.IP \(bu 4
+In \f(CW\*(C`unpack\*(C'\fR, the use of \f(CW\*(C`()\*(C'\fR groups in scalar context was internally
+placing a list on the interpreter's stack, which manifested in various
+ways, including SEGVs.  This is now fixed [RT #50256].
+.IP \(bu 4
+Magic was called twice in \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`\e&$x\*(C'\fR, \f(CW\*(C`tie $x, $m\*(C'\fR and \f(CW\*(C`chop\*(C'\fR.
+These have all been fixed.
+.IP \(bu 4
+A 5.10.0 optimisation to clear the temporary stack within the implicit
+loop of \f(CW\*(C`s///ge\*(C'\fR has been reverted, as it turned out to be the cause of
+obscure bugs in seemingly unrelated parts of the interpreter [commit 
+ef0d4e17921ee3de].
+.IP \(bu 4
+The line numbers for warnings inside \f(CW\*(C`elsif\*(C'\fR are now correct.
+.IP \(bu 4
+The \f(CW\*(C`..\*(C'\fR operator now works correctly with ranges whose ends are at or
+close to the values of the smallest and largest integers.
+.IP \(bu 4
+\&\f(CW\*(C`binmode STDIN, \*(Aq:raw\*(Aq\*(C'\fR could lead to segmentation faults on some platforms.
+This has been fixed [RT #54828].
+.IP \(bu 4
+An off-by-one error meant that \f(CW\*(C`index $str, ...\*(C'\fR was effectively being
+executed as \f(CW\*(C`index "$str\e0", ...\*(C'\fR. This has been fixed [RT #53746].
+.IP \(bu 4
+Various leaks associated with named captures in regexes have been fixed
+[RT #57024].
+.IP \(bu 4
+A weak reference to a hash would leak. This was affecting \f(CW\*(C`DBI\*(C'\fR
+[RT #56908].
+.IP \(bu 4
+Using (?|) in a regex could cause a segfault [RT #59734].
+.IP \(bu 4
+Use of a UTF\-8 \f(CW\*(C`tr//\*(C'\fR within a closure could cause a segfault [RT #61520].
+.IP \(bu 4
+Calling \f(CWsv_chop()\fR or otherwise upgrading an SV could result in an
+unaligned 64\-bit access on the SPARC architecture [RT #60574].
+.IP \(bu 4
+In the 5.10.0 release, \f(CW\*(C`inc_version_list\*(C'\fR would incorrectly list
+\&\f(CW\*(C`5.10.*\*(C'\fR after \f(CW\*(C`5.8.*\*(C'\fR; this affected the \f(CW@INC\fR search order
+[RT #67628].
+.IP \(bu 4
+In 5.10.0, \f(CW\*(C`pack "a*", $tainted_value\*(C'\fR returned a non-tainted value
+[RT #52552].
+.IP \(bu 4
+In 5.10.0, \f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR could produce the fatal error
+\&\f(CW\*(C`panic: utf8_mg_pos_cache_update\*(C'\fR when printing UTF\-8 strings
+[RT #62666].
+.IP \(bu 4
+In the 5.10.0 release, a dynamically created \f(CW\*(C`AUTOLOAD\*(C'\fR method might be
+missed (method cache issue) [RT #60220,60232].
+.IP \(bu 4
+In the 5.10.0 release, a combination of \f(CW\*(C`use feature\*(C'\fR and \f(CW\*(C`//ee\*(C'\fR could
+cause a memory leak [RT #63110].
+.IP \(bu 4
+\&\f(CW\*(C`\-C\*(C'\fR on the shebang (\f(CW\*(C`#!\*(C'\fR) line is once more permitted if it is also
+specified on the command line. \f(CW\*(C`\-C\*(C'\fR on the shebang line used to be a
+silent no-op \fIif\fR it was not also on the command line, so perl 5.10.0
+disallowed it, which broke some scripts. Now perl checks whether it is
+also on the command line and only dies if it is not [RT #67880].
+.IP \(bu 4
+In 5.10.0, certain types of re-entrant regular expression could crash,
+or cause the following assertion failure [RT #60508]:
+.Sp
+.Vb 1
+\&    Assertion rx\->sublen >= (s \- rx\->subbeg) + i failed
+.Ve
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.ie n .IP """panic: sv_chop %s""" 4
+.el .IP "\f(CWpanic: sv_chop %s\fR" 4
+.IX Item "panic: sv_chop %s"
+This new fatal error occurs when the C routine \f(CWPerl_sv_chop()\fR was
+passed a position that is not within the scalar's string buffer. This
+could be caused by buggy XS code, and at this point recovery is not
+possible.
+.ie n .IP """Can\*(Aqt locate package %s for the parents of %s""" 4
+.el .IP "\f(CWCan\*(Aqt locate package %s for the parents of %s\fR" 4
+.IX Item "Cant locate package %s for the parents of %s"
+This warning has been removed. In general, it only got produced in
+conjunction with other warnings, and removing it allowed an ISA lookup
+optimisation to be added.
+.ie n .IP """v\-string in use/require is non\-portable""" 4
+.el .IP "\f(CWv\-string in use/require is non\-portable\fR" 4
+.IX Item "v-string in use/require is non-portable"
+This warning has been removed.
+.ie n .IP """Deep recursion on subroutine ""%s""""" 4
+.el .IP "\f(CWDeep recursion on subroutine ""%s""\fR" 4
+.IX Item "Deep recursion on subroutine ""%s"""
+It is now possible to change the depth threshold for this warning from the
+default of 100, by recompiling the \fIperl\fR binary, setting the C
+pre-processor macro \f(CW\*(C`PERL_SUB_DEPTH_WARN\*(C'\fR to the desired value.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+.IP \(bu 4
+The J.R.R. Tolkien quotes at the head of C source file have been checked and
+proper citations added, thanks to a patch from Tom Christiansen.
+.IP \(bu 4
+\&\f(CWvcroak()\fR now accepts a null first argument. In addition, a full audit
+was made of the "not NULL" compiler annotations, and those for several
+other internal functions were corrected.
+.IP \(bu 4
+New macros \f(CW\*(C`dSAVEDERRNO\*(C'\fR, \f(CW\*(C`dSAVE_ERRNO\*(C'\fR, \f(CW\*(C`SAVE_ERRNO\*(C'\fR, \f(CW\*(C`RESTORE_ERRNO\*(C'\fR
+have been added to formalise the temporary saving of the \f(CW\*(C`errno\*(C'\fR
+variable.
+.IP \(bu 4
+The function \f(CW\*(C`Perl_sv_insert_flags\*(C'\fR has been added to augment
+\&\f(CW\*(C`Perl_sv_insert\*(C'\fR.
+.IP \(bu 4
+The function \f(CWPerl_newSV_type(type)\fR has been added, equivalent to
+\&\f(CWPerl_newSV()\fR followed by \f(CWPerl_sv_upgrade(type)\fR.
+.IP \(bu 4
+The function \f(CWPerl_newSVpvn_flags()\fR has been added, equivalent to
+\&\f(CWPerl_newSVpvn()\fR and then performing the action relevant to the flag.
+.Sp
+Two flag bits are currently supported.
+.RS 4
+.ie n .IP """SVf_UTF8""" 4
+.el .IP \f(CWSVf_UTF8\fR 4
+.IX Item "SVf_UTF8"
+This will call \f(CWSvUTF8_on()\fR for you. (Note that this does not convert an
+sequence of ISO 8859\-1 characters to UTF\-8). A wrapper, \f(CWnewSVpvn_utf8()\fR
+is available for this.
+.ie n .IP """SVs_TEMP""" 4
+.el .IP \f(CWSVs_TEMP\fR 4
+.IX Item "SVs_TEMP"
+Call \f(CWsv_2mortal()\fR on the new SV.
+.RE
+.RS 4
+.Sp
+There is also a wrapper that takes constant strings, \f(CWnewSVpvs_flags()\fR.
+.RE
+.IP \(bu 4
+The function \f(CW\*(C`Perl_croak_xs_usage\*(C'\fR has been added as a wrapper to
+\&\f(CW\*(C`Perl_croak\*(C'\fR.
+.IP \(bu 4
+The functions \f(CW\*(C`PerlIO_find_layer\*(C'\fR and \f(CW\*(C`PerlIO_list_alloc\*(C'\fR are now
+exported.
+.IP \(bu 4
+\&\f(CW\*(C`PL_na\*(C'\fR has been exterminated from the core code, replaced by local STRLEN
+temporaries, or \f(CW*_nolen()\fR calls. Either approach is faster than \f(CW\*(C`PL_na\*(C'\fR,
+which is a pointer deference into the interpreter structure under ithreads,
+and a global variable otherwise.
+.IP \(bu 4
+\&\f(CWPerl_mg_free()\fR used to leave freed memory accessible via \fBSvMAGIC()\fR on
+the scalar. It now updates the linked list to remove each piece of magic
+as it is freed.
+.IP \(bu 4
+Under ithreads, the regex in \f(CW\*(C`PL_reg_curpm\*(C'\fR is now reference counted. This
+eliminates a lot of hackish workarounds to cope with it not being reference
+counted.
+.IP \(bu 4
+\&\f(CWPerl_mg_magical()\fR would sometimes incorrectly turn on \f(CWSvRMAGICAL()\fR.
+This has been fixed.
+.IP \(bu 4
+The \fIpublic\fR IV and NV flags are now not set if the string value has
+trailing "garbage". This behaviour is consistent with not setting the
+public IV or NV flags if the value is out of range for the type.
+.IP \(bu 4
+SV allocation tracing has been added to the diagnostics enabled by \f(CW\*(C`\-Dm\*(C'\fR.
+The tracing can alternatively output via the \f(CW\*(C`PERL_MEM_LOG\*(C'\fR mechanism, if
+that was enabled when the \fIperl\fR binary was compiled.
+.IP \(bu 4
+Uses of \f(CW\*(C`Nullav\*(C'\fR, \f(CW\*(C`Nullcv\*(C'\fR, \f(CW\*(C`Nullhv\*(C'\fR, \f(CW\*(C`Nullop\*(C'\fR, \f(CW\*(C`Nullsv\*(C'\fR etc have been
+replaced by \f(CW\*(C`NULL\*(C'\fR in the core code, and non-dual-life modules, as \f(CW\*(C`NULL\*(C'\fR
+is clearer to those unfamiliar with the core code.
+.IP \(bu 4
+A macro \f(CWMUTABLE_PTR(p)\fR has been added, which on (non-pedantic) gcc will
+not cast away \f(CW\*(C`const\*(C'\fR, returning a \f(CW\*(C`void *\*(C'\fR. Macros \f(CWMUTABLE_SV(av)\fR,
+\&\f(CWMUTABLE_SV(cv)\fR etc build on this, casting to \f(CW\*(C`AV *\*(C'\fR etc without
+casting away \f(CW\*(C`const\*(C'\fR. This allows proper compile-time auditing of
+\&\f(CW\*(C`const\*(C'\fR correctness in the core, and helped picked up some errors (now
+fixed).
+.IP \(bu 4
+Macros \f(CWmPUSHs()\fR and \f(CWmXPUSHs()\fR have been added, for pushing SVs on the
+stack and mortalizing them.
+.IP \(bu 4
+Use of the private structure \f(CW\*(C`mro_meta\*(C'\fR has changed slightly. Nothing
+outside the core should be accessing this directly anyway.
+.IP \(bu 4
+A new tool, \f(CW\*(C`Porting/expand\-macro.pl\*(C'\fR has been added, that allows you
+to view how a C preprocessor macro would be expanded when compiled.
+This is handy when trying to decode the macro hell that is the perl
+guts.
+.SH "New Tests"
+.IX Header "New Tests"
+Many modules updated from CPAN incorporate new tests.
+.PP
+Several tests that have the potential to hang forever if they fail now
+incorporate a "watchdog" functionality that will kill them after a timeout,
+which helps ensure that \f(CW\*(C`make test\*(C'\fR and \f(CW\*(C`make test_harness\*(C'\fR run to
+completion automatically. (Jerry Hedden).
+.PP
+Some core-specific tests have been added:
+.IP t/comp/retainedlines.t 4
+.IX Item "t/comp/retainedlines.t"
+Check that the debugger can retain source lines from \f(CW\*(C`eval\*(C'\fR.
+.IP t/io/perlio_fail.t 4
+.IX Item "t/io/perlio_fail.t"
+Check that bad layers fail.
+.IP t/io/perlio_leaks.t 4
+.IX Item "t/io/perlio_leaks.t"
+Check that PerlIO layers are not leaking.
+.IP t/io/perlio_open.t 4
+.IX Item "t/io/perlio_open.t"
+Check that certain special forms of open work.
+.IP t/io/perlio.t 4
+.IX Item "t/io/perlio.t"
+General PerlIO tests.
+.IP t/io/pvbm.t 4
+.IX Item "t/io/pvbm.t"
+Check that there is no unexpected interaction between the internal types
+\&\f(CW\*(C`PVBM\*(C'\fR and \f(CW\*(C`PVGV\*(C'\fR.
+.IP t/mro/package_aliases.t 4
+.IX Item "t/mro/package_aliases.t"
+Check that mro works properly in the presence of aliased packages.
+.IP t/op/dbm.t 4
+.IX Item "t/op/dbm.t"
+Tests for \f(CW\*(C`dbmopen\*(C'\fR and \f(CW\*(C`dbmclose\*(C'\fR.
+.IP t/op/index_thr.t 4
+.IX Item "t/op/index_thr.t"
+Tests for the interaction of \f(CW\*(C`index\*(C'\fR and threads.
+.IP t/op/pat_thr.t 4
+.IX Item "t/op/pat_thr.t"
+Tests for the interaction of esoteric patterns and threads.
+.IP t/op/qr_gc.t 4
+.IX Item "t/op/qr_gc.t"
+Test that \f(CW\*(C`qr\*(C'\fR doesn't leak.
+.IP t/op/reg_email_thr.t 4
+.IX Item "t/op/reg_email_thr.t"
+Tests for the interaction of regex recursion and threads.
+.IP t/op/regexp_qr_embed_thr.t 4
+.IX Item "t/op/regexp_qr_embed_thr.t"
+Tests for the interaction of patterns with embedded \f(CW\*(C`qr//\*(C'\fR and threads.
+.IP t/op/regexp_unicode_prop.t 4
+.IX Item "t/op/regexp_unicode_prop.t"
+Tests for Unicode properties in regular expressions.
+.IP t/op/regexp_unicode_prop_thr.t 4
+.IX Item "t/op/regexp_unicode_prop_thr.t"
+Tests for the interaction of Unicode properties and threads.
+.IP t/op/reg_nc_tie.t 4
+.IX Item "t/op/reg_nc_tie.t"
+Test the tied methods of \f(CW\*(C`Tie::Hash::NamedCapture\*(C'\fR.
+.IP t/op/reg_posixcc.t 4
+.IX Item "t/op/reg_posixcc.t"
+Check that POSIX character classes behave consistently.
+.IP t/op/re.t 4
+.IX Item "t/op/re.t"
+Check that exportable \f(CW\*(C`re\*(C'\fR functions in \fIuniversal.c\fR work.
+.IP t/op/setpgrpstack.t 4
+.IX Item "t/op/setpgrpstack.t"
+Check that \f(CW\*(C`setpgrp\*(C'\fR works.
+.IP t/op/substr_thr.t 4
+.IX Item "t/op/substr_thr.t"
+Tests for the interaction of \f(CW\*(C`substr\*(C'\fR and threads.
+.IP t/op/upgrade.t 4
+.IX Item "t/op/upgrade.t"
+Check that upgrading and assigning scalars works.
+.IP t/uni/lex_utf8.t 4
+.IX Item "t/uni/lex_utf8.t"
+Check that Unicode in the lexer works.
+.IP t/uni/tie.t 4
+.IX Item "t/uni/tie.t"
+Check that Unicode and \f(CW\*(C`tie\*(C'\fR work.
+.SH "Known Problems"
+.IX Header "Known Problems"
+This is a list of some significant unfixed bugs, which are regressions
+from either 5.10.0 or 5.8.x.
+.IP \(bu 4
+\&\f(CW\*(C`List::Util::first\*(C'\fR misbehaves in the presence of a lexical \f(CW$_\fR
+(typically introduced by \f(CW\*(C`my $_\*(C'\fR or implicitly by \f(CW\*(C`given\*(C'\fR). The variable
+which gets set for each iteration is the package variable \f(CW$_\fR, not the
+lexical \f(CW$_\fR [RT #67694].
+.Sp
+A similar issue may occur in other modules that provide functions which
+take a block as their first argument, like
+.Sp
+.Vb 1
+\&    foo { ... $_ ...} list
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`charnames\*(C'\fR pragma may generate a run-time error when a regex is
+interpolated [RT #56444]:
+.Sp
+.Vb 4
+\&    use charnames \*(Aq:full\*(Aq;
+\&    my $r1 = qr/\eN{THAI CHARACTER SARA I}/;
+\&    "foo" =~ $r1;    # okay
+\&    "foo" =~ /$r1+/; # runtime error
+.Ve
+.Sp
+A workaround is to generate the character outside of the regex:
+.Sp
+.Vb 2
+\&    my $a = "\eN{THAI CHARACTER SARA I}";
+\&    my $r1 = qr/$a/;
+.Ve
+.IP \(bu 4
+Some regexes may run much more slowly when run in a child thread compared
+with the thread the pattern was compiled into [RT #55600].
+.SH Deprecations
+.IX Header "Deprecations"
+The following items are now deprecated.
+.IP \(bu 4
+\&\f(CW\*(C`Switch\*(C'\fR is buggy and should be avoided. From perl 5.11.0 onwards, it is
+intended that any use of the core version of this module will emit a
+warning, and that the module will eventually be removed from the core
+(probably in perl 5.14.0). See "Switch statements" in perlsyn for its
+replacement.
+.IP \(bu 4
+\&\f(CW\*(C`suidperl\*(C'\fR will be removed in 5.12.0. This provides a mechanism to
+emulate setuid permission bits on systems that don't support it properly.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Some of the work in this release was funded by a TPF grant.
+.PP
+Nicholas Clark officially retired from maintenance pumpking duty at the
+end of 2008; however in reality he has put much effort in since then to
+help get 5.10.1 into a fit state to be released, including writing a
+considerable chunk of this perldelta.
+.PP
+Steffen Mueller and David Golden in particular helped getting CPAN modules
+polished and synchronised with their in-core equivalents.
+.PP
+Craig Berry was tireless in getting maint to run under VMS, no matter how
+many times we broke it for him.
+.PP
+The other core committers contributed most of the changes, and applied most
+of the patches sent in by the hundreds of contributors listed in \fIAUTHORS\fR.
+.PP
+(Sorry to all the people I haven't mentioned by name).
+.PP
+Finally, thanks to Larry Wall, without whom none of this would be
+necessary.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5120delta.1 b/upstream/mageia-cauldron/man1/perl5120delta.1
new file mode 100644
index 00000000..5eb75037
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5120delta.1
@@ -0,0 +1,2580 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5120DELTA 1"
+.TH PERL5120DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5120delta \- what is new for perl v5.12.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.10.0 release and the
+5.12.0 release.
+.PP
+Many of the bug fixes in 5.12.0 are already included in the 5.10.1
+maintenance release.
+.PP
+You can see the list of those changes in the 5.10.1 release notes
+(perl5101delta).
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS "New ""package NAME VERSION"" syntax"
+.el .SS "New \f(CWpackage NAME VERSION\fP syntax"
+.IX Subsection "New package NAME VERSION syntax"
+This new syntax allows a module author to set the \f(CW$VERSION\fR of a namespace
+when the namespace is declared with 'package'. It eliminates the need
+for \f(CW\*(C`our $VERSION = ...\*(C'\fR and similar constructs. E.g.
+.PP
+.Vb 2
+\&      package Foo::Bar 1.23;
+\&      # $Foo::Bar::VERSION == 1.23
+.Ve
+.PP
+There are several advantages to this:
+.IP \(bu 4
+\&\f(CW$VERSION\fR is parsed in exactly the same way as \f(CW\*(C`use NAME VERSION\*(C'\fR
+.IP \(bu 4
+\&\f(CW$VERSION\fR is set at compile time
+.IP \(bu 4
+\&\f(CW$VERSION\fR is a version object that provides proper overloading of
+comparison operators so comparing \f(CW$VERSION\fR to decimal (1.23) or
+dotted-decimal (v1.2.3) version numbers works correctly.
+.IP \(bu 4
+Eliminates \f(CW\*(C`$VERSION = ...\*(C'\fR and \f(CW\*(C`eval $VERSION\*(C'\fR clutter
+.IP \(bu 4
+As it requires VERSION to be a numeric literal or v\-string
+literal, it can be statically parsed by toolchain modules
+without \f(CW\*(C`eval\*(C'\fR the way MM\->parse_version does for \f(CW\*(C`$VERSION = ...\*(C'\fR
+.PP
+It does not break old code with only \f(CW\*(C`package NAME\*(C'\fR, but code that uses
+\&\f(CW\*(C`package NAME VERSION\*(C'\fR will need to be restricted to perl 5.12.0 or newer
+This is analogous to the change to \f(CW\*(C`open\*(C'\fR from two-args to three-args.
+Users requiring the latest Perl will benefit, and perhaps after several
+years, it will become a standard practice.
+.PP
+However, \f(CW\*(C`package NAME VERSION\*(C'\fR requires a new, 'strict' version
+number format. See "Version number formats" for details.
+.ie n .SS "The ""..."" operator"
+.el .SS "The \f(CW...\fP operator"
+.IX Subsection "The ... operator"
+A new operator, \f(CW\*(C`...\*(C'\fR, nicknamed the Yada Yada operator, has been added.
+It is intended to mark placeholder code that is not yet implemented.
+See "Yada Yada Operator" in perlop.
+.SS "Implicit strictures"
+.IX Subsection "Implicit strictures"
+Using the \f(CW\*(C`use VERSION\*(C'\fR syntax with a version number greater or equal
+to 5.11.0 will lexically enable strictures just like \f(CW\*(C`use strict\*(C'\fR
+would do (in addition to enabling features.) The following:
+.PP
+.Vb 1
+\&    use 5.12.0;
+.Ve
+.PP
+means:
+.PP
+.Vb 2
+\&    use strict;
+\&    use feature \*(Aq:5.12\*(Aq;
+.Ve
+.SS "Unicode improvements"
+.IX Subsection "Unicode improvements"
+Perl 5.12 comes with Unicode 5.2, the latest version available to
+us at the time of release.  This version of Unicode was released in
+October 2009. See <http://www.unicode.org/versions/Unicode5.2.0> for
+further details about what's changed in this version of the standard.
+See perlunicode for instructions on installing and using other versions
+of Unicode.
+.PP
+Additionally, Perl's developers have significantly improved Perl's Unicode
+implementation. For full details, see "Unicode overhaul" below.
+.SS "Y2038 compliance"
+.IX Subsection "Y2038 compliance"
+Perl's core time-related functions are now Y2038 compliant. (It may not mean much to you, but your kids will love it!)
+.SS "qr overloading"
+.IX Subsection "qr overloading"
+It is now possible to overload the \f(CW\*(C`qr//\*(C'\fR operator, that is,
+conversion to regexp, like it was already possible to overload
+conversion to boolean, string or number of objects. It is invoked when
+an object appears on the right hand side of the \f(CW\*(C`=~\*(C'\fR operator or when
+it is interpolated into a regexp. See overload.
+.SS "Pluggable keywords"
+.IX Subsection "Pluggable keywords"
+Extension modules can now cleanly hook into the Perl parser to define
+new kinds of keyword-headed expression and compound statement. The
+syntax following the keyword is defined entirely by the extension. This
+allows a completely non-Perl sublanguage to be parsed inline, with the
+correct ops cleanly generated.
+.PP
+See "PL_keyword_plugin" in perlapi for the mechanism. The Perl core
+source distribution also includes a new module
+XS::APItest::KeywordRPN, which implements reverse Polish notation
+arithmetic via pluggable keywords. This module is mainly used for test
+purposes, and is not normally installed, but also serves as an example
+of how to use the new mechanism.
+.PP
+Perl's developers consider this feature to be experimental. We may remove
+it or change it in a backwards-incompatible way in Perl 5.14.
+.SS "APIs for more internals"
+.IX Subsection "APIs for more internals"
+The lowest layers of the lexer and parts of the pad system now have C
+APIs available to XS extensions. These are necessary to support proper
+use of pluggable keywords, but have other uses too. The new APIs are
+experimental, and only cover a small proportion of what would be
+necessary to take full advantage of the core's facilities in these
+areas. It is intended that the Perl 5.13 development cycle will see the
+addition of a full range of clean, supported interfaces.
+.PP
+Perl's developers consider this feature to be experimental. We may remove
+it or change it in a backwards-incompatible way in Perl 5.14.
+.SS "Overridable function lookup"
+.IX Subsection "Overridable function lookup"
+Where an extension module hooks the creation of rv2cv ops to modify the
+subroutine lookup process, this now works correctly for bareword
+subroutine calls. This means that prototypes on subroutines referenced
+this way will be processed correctly. (Previously bareword subroutine
+names were initially looked up, for parsing purposes, by an unhookable
+mechanism, so extensions could only properly influence subroutine names
+that appeared with an \f(CW\*(C`&\*(C'\fR sigil.)
+.SS "A proper interface for pluggable Method Resolution Orders"
+.IX Subsection "A proper interface for pluggable Method Resolution Orders"
+As of Perl 5.12.0 there is a new interface for plugging and using method
+resolution orders other than the default linear depth first search.
+The C3 method resolution order added in 5.10.0 has been re-implemented as
+a plugin, without changing its Perl-space interface. See perlmroapi for
+more information.
+.ie n .SS """\eN"" experimental regex escape"
+.el .SS "\f(CW\eN\fP experimental regex escape"
+.IX Subsection "N experimental regex escape"
+Perl now supports \f(CW\*(C`\eN\*(C'\fR, a new regex escape which you can think of as
+the inverse of \f(CW\*(C`\en\*(C'\fR. It will match any character that is not a newline,
+independently from the presence or absence of the single line match
+modifier \f(CW\*(C`/s\*(C'\fR. It is not usable within a character class.  \f(CW\*(C`\eN{3}\*(C'\fR
+means to match 3 non-newlines; \f(CW\*(C`\eN{5,}\*(C'\fR means to match at least 5.
+\&\f(CW\*(C`\eN{NAME}\*(C'\fR still means the character or sequence named \f(CW\*(C`NAME\*(C'\fR, but
+\&\f(CW\*(C`NAME\*(C'\fR no longer can be things like \f(CW3\fR, or \f(CW\*(C`5,\*(C'\fR.
+.PP
+This will break a custom charnames translator which allows numbers for character names, as \f(CW\*(C`\eN{3}\*(C'\fR will
+now mean to match 3 non-newline characters, and not the character whose
+name is \f(CW3\fR. (No name defined by the Unicode standard is a number,
+so only custom translators might be affected.)
+.PP
+Perl's developers are somewhat concerned about possible user confusion
+with the existing \f(CW\*(C`\eN{...}\*(C'\fR construct which matches characters by their
+Unicode name. Consequently, this feature is experimental. We may remove
+it or change it in a backwards-incompatible way in Perl 5.14.
+.SS "DTrace support"
+.IX Subsection "DTrace support"
+Perl now has some support for DTrace. See "DTrace support" in \fIINSTALL\fR.
+.ie n .SS "Support for ""configure_requires"" in CPAN module metadata"
+.el .SS "Support for \f(CWconfigure_requires\fP in CPAN module metadata"
+.IX Subsection "Support for configure_requires in CPAN module metadata"
+Both \f(CW\*(C`CPAN\*(C'\fR and \f(CW\*(C`CPANPLUS\*(C'\fR now support the \f(CW\*(C`configure_requires\*(C'\fR
+keyword in the \fIMETA.yml\fR metadata file included in most recent CPAN
+distributions.  This allows distribution authors to specify configuration
+prerequisites that must be installed before running \fIMakefile.PL\fR
+or \fIBuild.PL\fR.
+.PP
+See the documentation for \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR or \f(CW\*(C`Module::Build\*(C'\fR for
+more on how to specify \f(CW\*(C`configure_requires\*(C'\fR when creating a distribution
+for CPAN.
+.ie n .SS """each"", ""keys"", ""values"" are now more flexible"
+.el .SS "\f(CWeach\fP, \f(CWkeys\fP, \f(CWvalues\fP are now more flexible"
+.IX Subsection "each, keys, values are now more flexible"
+The \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR function can now operate on arrays.
+.ie n .SS """when"" as a statement modifier"
+.el .SS "\f(CWwhen\fP as a statement modifier"
+.IX Subsection "when as a statement modifier"
+\&\f(CW\*(C`when\*(C'\fR is now allowed to be used as a statement modifier.
+.ie n .SS "$, flexibility"
+.el .SS "\f(CW$,\fP flexibility"
+.IX Subsection "$, flexibility"
+The variable \f(CW$,\fR may now be tied.
+.SS "// in when clauses"
+.IX Subsection "// in when clauses"
+// now behaves like || in when clauses
+.SS "Enabling warnings from your shell environment"
+.IX Subsection "Enabling warnings from your shell environment"
+You can now set \f(CW\*(C`\-W\*(C'\fR from the \f(CW\*(C`PERL5OPT\*(C'\fR environment variable
+.ie n .SS """delete local"""
+.el .SS "\f(CWdelete local\fP"
+.IX Subsection "delete local"
+\&\f(CW\*(C`delete local\*(C'\fR now allows you to locally delete a hash entry.
+.SS "New support for Abstract namespace sockets"
+.IX Subsection "New support for Abstract namespace sockets"
+Abstract namespace sockets are Linux-specific socket type that live in
+AF_UNIX family, slightly abusing it to be able to use arbitrary
+character arrays as addresses: They start with nul byte and are not
+terminated by nul byte, but with the length passed to the \fBsocket()\fR
+system call.
+.SS "32\-bit limit on substr arguments removed"
+.IX Subsection "32-bit limit on substr arguments removed"
+The 32\-bit limit on \f(CW\*(C`substr\*(C'\fR arguments has now been removed. The full
+range of the system's signed and unsigned integers is now available for
+the \f(CW\*(C`pos\*(C'\fR and \f(CW\*(C`len\*(C'\fR arguments.
+.SH "Potentially Incompatible Changes"
+.IX Header "Potentially Incompatible Changes"
+.SS "Deprecations warn by default"
+.IX Subsection "Deprecations warn by default"
+Over the years, Perl's developers have deprecated a number of language
+features for a variety of reasons.  Perl now defaults to issuing a
+warning if a deprecated language feature is used. Many of the deprecations
+Perl now warns you about have been deprecated for many years.  You can
+find a list of what was deprecated in a given release of Perl in the
+\&\f(CW\*(C`perl5xxdelta.pod\*(C'\fR file for that release.
+.PP
+To disable this feature in a given lexical scope, you should use \f(CW\*(C`no
+warnings \*(Aqdeprecated\*(Aq;\*(C'\fR For information about which language features
+are deprecated and explanations of various deprecation warnings, please
+see perldiag. See "Deprecations" below for the list of features
+and modules Perl's developers have deprecated as part of this release.
+.SS "Version number formats"
+.IX Subsection "Version number formats"
+Acceptable version number formats have been formalized into "strict" and
+"lax" rules. \f(CW\*(C`package NAME VERSION\*(C'\fR takes a strict version number.
+\&\f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR and the version object constructors take lax
+version numbers. Providing an invalid version will result in a fatal
+error. The version argument in \f(CW\*(C`use NAME VERSION\*(C'\fR is first parsed as a
+numeric literal or v\-string and then passed to \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR
+(and must then pass the "lax" format test).
+.PP
+These formats are documented fully in the version module. To a first
+approximation, a "strict" version number is a positive decimal number
+(integer or decimal-fraction) without exponentiation or else a
+dotted-decimal v\-string with a leading 'v' character and at least three
+components. A "lax" version number allows v\-strings with fewer than
+three components or without a leading 'v'. Under "lax" rules, both
+decimal and dotted-decimal versions may have a trailing "alpha"
+component separated by an underscore character after a fractional or
+dotted-decimal component.
+.PP
+The version module adds \f(CW\*(C`version::is_strict\*(C'\fR and \f(CW\*(C`version::is_lax\*(C'\fR
+functions to check a scalar against these rules.
+.ie n .SS "@INC reorganization"
+.el .SS "\f(CW@INC\fP reorganization"
+.IX Subsection "@INC reorganization"
+In \f(CW@INC\fR, \f(CW\*(C`ARCHLIB\*(C'\fR and \f(CW\*(C`PRIVLIB\*(C'\fR now occur after the current
+version's \f(CW\*(C`site_perl\*(C'\fR and \f(CW\*(C`vendor_perl\*(C'\fR.  Modules installed into
+\&\f(CW\*(C`site_perl\*(C'\fR and \f(CW\*(C`vendor_perl\*(C'\fR will now be loaded in preference to
+those installed in \f(CW\*(C`ARCHLIB\*(C'\fR and \f(CW\*(C`PRIVLIB\*(C'\fR.
+.SS "REGEXPs are now first class"
+.IX Subsection "REGEXPs are now first class"
+Internally, Perl now treats compiled regular expressions (such as
+those created with \f(CW\*(C`qr//\*(C'\fR) as first class entities. Perl modules which
+serialize, deserialize or otherwise have deep interaction with Perl's
+internal data structures need to be updated for this change.  Most
+affected CPAN modules have already been updated as of this writing.
+.SS "Switch statement changes"
+.IX Subsection "Switch statement changes"
+The \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR switch statement handles complex statements better
+than Perl 5.10.0 did (These enhancements are also available in
+5.10.1 and subsequent 5.10 releases.) There are two new cases where
+\&\f(CW\*(C`when\*(C'\fR now interprets its argument as a boolean, instead of an
+expression to be used in a smart match:
+.IP "flip-flop operators" 4
+.IX Item "flip-flop operators"
+The \f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR flip-flop operators are now evaluated in boolean
+context, following their usual semantics; see "Range Operators" in perlop.
+.Sp
+Note that, as in perl 5.10.0, \f(CW\*(C`when (1..10)\*(C'\fR will not work to test
+whether a given value is an integer between 1 and 10; you should use
+\&\f(CW\*(C`when ([1..10])\*(C'\fR instead (note the array reference).
+.Sp
+However, contrary to 5.10.0, evaluating the flip-flop operators in
+boolean context ensures it can now be useful in a \f(CWwhen()\fR, notably
+for implementing bistable conditions, like in:
+.Sp
+.Vb 3
+\&    when (/^=begin/ .. /^=end/) {
+\&      # do something
+\&    }
+.Ve
+.IP "defined-or operator" 4
+.IX Item "defined-or operator"
+A compound expression involving the defined-or operator, as in
+\&\f(CW\*(C`when (expr1 // expr2)\*(C'\fR, will be treated as boolean if the first
+expression is boolean. (This just extends the existing rule that applies
+to the regular or operator, as in \f(CW\*(C`when (expr1 || expr2)\*(C'\fR.)
+.SS "Smart match changes"
+.IX Subsection "Smart match changes"
+Since Perl 5.10.0, Perl's developers have made a number of changes to
+the smart match operator. These, of course, also alter the behaviour
+of the switch statements where smart matching is implicitly used.
+These changes were also made for the 5.10.1 release, and will remain in
+subsequent 5.10 releases.
+.PP
+\fIChanges to type-based dispatch\fR
+.IX Subsection "Changes to type-based dispatch"
+.PP
+The smart match operator \f(CW\*(C`~~\*(C'\fR is no longer commutative. The behaviour of
+a smart match now depends primarily on the type of its right hand
+argument. Moreover, its semantics have been adjusted for greater
+consistency or usefulness in several cases. While the general backwards
+compatibility is maintained, several changes must be noted:
+.IP \(bu 4
+Code references with an empty prototype are no longer treated specially.
+They are passed an argument like the other code references (even if they
+choose to ignore it).
+.IP \(bu 4
+\&\f(CW\*(C`%hash ~~ sub {}\*(C'\fR and \f(CW\*(C`@array ~~ sub {}\*(C'\fR now test that the subroutine
+returns a true value for each key of the hash (or element of the
+array), instead of passing the whole hash or array as a reference to
+the subroutine.
+.IP \(bu 4
+Due to the commutativity breakage, code references are no longer
+treated specially when appearing on the left of the \f(CW\*(C`~~\*(C'\fR operator,
+but like any vulgar scalar.
+.IP \(bu 4
+\&\f(CW\*(C`undef ~~ %hash\*(C'\fR is always false (since \f(CW\*(C`undef\*(C'\fR can't be a key in a
+hash). No implicit conversion to \f(CW""\fR is done (as was the case in perl
+5.10.0).
+.IP \(bu 4
+\&\f(CW\*(C`$scalar ~~ @array\*(C'\fR now always distributes the smart match across the
+elements of the array. It's true if one element in \f(CW@array\fR verifies
+\&\f(CW\*(C`$scalar ~~ $element\*(C'\fR. This is a generalization of the old behaviour
+that tested whether the array contained the scalar.
+.PP
+The full dispatch table for the smart match operator is given in
+"Smart matching in detail" in perlsyn.
+.PP
+\fISmart match and overloading\fR
+.IX Subsection "Smart match and overloading"
+.PP
+According to the rule of dispatch based on the rightmost argument type,
+when an object overloading \f(CW\*(C`~~\*(C'\fR appears on the right side of the
+operator, the overload routine will always be called (with a 3rd argument
+set to a true value, see overload.) However, when the object will
+appear on the left, the overload routine will be called only when the
+rightmost argument is a simple scalar. This way, distributivity of smart
+match across arrays is not broken, as well as the other behaviours with
+complex types (coderefs, hashes, regexes). Thus, writers of overloading
+routines for smart match mostly need to worry only with comparing
+against a scalar, and possibly with stringification overloading; the
+other common cases will be automatically handled consistently.
+.PP
+\&\f(CW\*(C`~~\*(C'\fR will now refuse to work on objects that do not overload it (in order
+to avoid relying on the object's underlying structure). (However, if the
+object overloads the stringification or the numification operators, and
+if overload fallback is active, it will be used instead, as usual.)
+.SS "Other potentially incompatible changes"
+.IX Subsection "Other potentially incompatible changes"
+.IP \(bu 4
+The definitions of a number of Unicode properties have changed to match
+those of the current Unicode standard. These are listed above under
+"Unicode overhaul". This change may break code that expects the old
+definitions.
+.IP \(bu 4
+The boolkeys op has moved to the group of hash ops. This breaks binary
+compatibility.
+.IP \(bu 4
+Filehandles are now always blessed into \f(CW\*(C`IO::File\*(C'\fR.
+.Sp
+The previous behaviour was to bless Filehandles into FileHandle
+(an empty proxy class) if it was loaded into memory and otherwise
+to bless them into \f(CW\*(C`IO::Handle\*(C'\fR.
+.IP \(bu 4
+The semantics of \f(CW\*(C`use feature :5.10*\*(C'\fR have changed slightly.
+See "Modules and Pragmata" for more information.
+.IP \(bu 4
+Perl's developers now use git, rather than Perforce.  This should be
+a purely internal change only relevant to people actively working on
+the core.  However, you may see minor difference in perl as a consequence
+of the change.  For example in some of details of the output of \f(CW\*(C`perl
+\&\-V\*(C'\fR. See perlrepository for more information.
+.IP \(bu 4
+As part of the \f(CW\*(C`Test::Harness\*(C'\fR 2.x to 3.x upgrade, the experimental
+\&\f(CW\*(C`Test::Harness::Straps\*(C'\fR module has been removed.
+See "Modules and Pragmata" for more details.
+.IP \(bu 4
+As part of the \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR upgrade, the
+\&\f(CW\*(C`ExtUtils::MakeMaker::bytes\*(C'\fR and \f(CW\*(C`ExtUtils::MakeMaker::vmsish\*(C'\fR modules
+have been removed from this distribution.
+.IP \(bu 4
+\&\f(CW\*(C`Module::CoreList\*(C'\fR no longer contains the \f(CW%:patchlevel\fR hash.
+.IP \(bu 4
+\&\f(CW\*(C`length undef\*(C'\fR now returns undef.
+.IP \(bu 4
+Unsupported private C API functions are now declared "static" to prevent
+leakage to Perl's public API.
+.IP \(bu 4
+To support the bootstrapping process, \fIminiperl\fR no longer builds with
+UTF\-8 support in the regexp engine.
+.Sp
+This allows a build to complete with PERL_UNICODE set and a UTF\-8 locale.
+Without this there's a bootstrapping problem, as miniperl can't load
+the UTF\-8 components of the regexp engine, because they're not yet built.
+.IP \(bu 4
+\&\fIminiperl\fR's \f(CW@INC\fR is now restricted to just \f(CW\*(C`\-I...\*(C'\fR, the split of
+\&\f(CW$ENV{PERL5LIB}\fR, and "\f(CW\*(C`.\*(C'\fR"
+.IP \(bu 4
+A space or a newline is now required after a \f(CW"#line XXX"\fR directive.
+.IP \(bu 4
+Tied filehandles now have an additional method EOF which provides the
+EOF type.
+.IP \(bu 4
+To better match all other flow control statements, \f(CW\*(C`foreach\*(C'\fR may no
+longer be used as an attribute.
+.IP \(bu 4
+Perl's command-line switch "\-P", which was deprecated in version 5.10.0, has
+now been removed. The CPAN module \f(CW\*(C`Filter::cpp\*(C'\fR can be used as an 
+alternative.
+.SH Deprecations
+.IX Header "Deprecations"
+From time to time, Perl's developers find it necessary to deprecate
+features or modules we've previously shipped as part of the core
+distribution. We are well aware of the pain and frustration that a
+backwards-incompatible change to Perl can cause for developers building
+or maintaining software in Perl. You can be sure that when we deprecate
+a functionality or syntax, it isn't a choice we make lightly. Sometimes,
+we choose to deprecate functionality or syntax because it was found to
+be poorly designed or implemented. Sometimes, this is because they're
+holding back other features or causing performance problems. Sometimes,
+the reasons are more complex. Wherever possible, we try to keep deprecated
+functionality available to developers in its previous form for at least
+one major release. So long as a deprecated feature isn't actively
+disrupting our ability to maintain and extend Perl, we'll try to leave
+it in place as long as possible.
+.PP
+The following items are now deprecated:
+.IP suidperl 4
+.IX Item "suidperl"
+\&\f(CW\*(C`suidperl\*(C'\fR is no longer part of Perl. It used to provide a mechanism to
+emulate setuid permission bits on systems that don't support it properly.
+.ie n .IP "Use of "":="" to mean an empty attribute list" 4
+.el .IP "Use of \f(CW:=\fR to mean an empty attribute list" 4
+.IX Item "Use of := to mean an empty attribute list"
+An accident of Perl's parser meant that these constructions were all
+equivalent:
+.Sp
+.Vb 3
+\&    my $pi := 4;
+\&    my $pi : = 4;
+\&    my $pi :  = 4;
+.Ve
+.Sp
+with the \f(CW\*(C`:\*(C'\fR being treated as the start of an attribute list, which
+ends before the \f(CW\*(C`=\*(C'\fR. As whitespace is not significant here, all are
+parsed as an empty attribute list, hence all the above are equivalent
+to, and better written as
+.Sp
+.Vb 1
+\&    my $pi = 4;
+.Ve
+.Sp
+because no attribute processing is done for an empty list.
+.Sp
+As is, this meant that \f(CW\*(C`:=\*(C'\fR cannot be used as a new token, without
+silently changing the meaning of existing code. Hence that particular
+form is now deprecated, and will become a syntax error. If it is
+absolutely necessary to have empty attribute lists (for example,
+because of a code generator) then avoid the warning by adding a space
+before the \f(CW\*(C`=\*(C'\fR.
+.ie n .IP """UNIVERSAL\->import()""" 4
+.el .IP \f(CWUNIVERSAL\->import()\fR 4
+.IX Item "UNIVERSAL->import()"
+The method \f(CW\*(C`UNIVERSAL\->import()\*(C'\fR is now deprecated. Attempting to
+pass import arguments to a \f(CW\*(C`use UNIVERSAL\*(C'\fR statement will result in a
+deprecation warning.
+.IP "Use of ""goto"" to jump into a construct" 4
+.IX Item "Use of ""goto"" to jump into a construct"
+Using \f(CW\*(C`goto\*(C'\fR to jump from an outer scope into an inner scope is now
+deprecated. This rare use case was causing problems in the
+implementation of scopes.
+.IP "Custom character names in \eN{name} that don't look like names" 4
+.IX Item "Custom character names in N{name} that don't look like names"
+In \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR, \fIname\fR can be just about anything. The standard
+Unicode names have a very limited domain, but a custom name translator
+could create names that are, for example, made up entirely of punctuation
+symbols. It is now deprecated to make names that don't begin with an
+alphabetic character, and aren't alphanumeric or contain other than
+a very few other characters, namely spaces, dashes, parentheses
+and colons. Because of the added meaning of \f(CW\*(C`\eN\*(C'\fR (See \f(CW\*(C`"\eN"
+experimental regex escape\*(C'\fR), names that look like curly brace \-enclosed
+quantifiers won't work. For example, \f(CW\*(C`\eN{3,4}\*(C'\fR now means to match 3 to
+4 non-newlines; before a custom name \f(CW\*(C`3,4\*(C'\fR could have been created.
+.IP "Deprecated Modules" 4
+.IX Item "Deprecated Modules"
+The following modules will be removed from the core distribution in a
+future release, and should be installed from CPAN instead. Distributions
+on CPAN which require these should add them to their prerequisites. The
+core versions of these modules warnings will issue a deprecation warning.
+.Sp
+If you ship a packaged version of Perl, either alone or as part of a
+larger system, then you should carefully consider the repercussions of
+core module deprecations. You may want to consider shipping your default
+build of Perl with packages for some or all deprecated modules which
+install into \f(CW\*(C`vendor\*(C'\fR or \f(CW\*(C`site\*(C'\fR perl library directories. This will
+inhibit the deprecation warnings.
+.Sp
+Alternatively, you may want to consider patching \fIlib/deprecate.pm\fR
+to provide deprecation warnings specific to your packaging system
+or distribution of Perl, consistent with how your packaging system
+or distribution manages a staged transition from a release where the
+installation of a single package provides the given functionality, to
+a later release where the system administrator needs to know to install
+multiple packages to get that same functionality.
+.Sp
+You can silence these deprecation warnings by installing the modules
+in question from CPAN.  To install the latest version of all of them,
+just install \f(CW\*(C`Task::Deprecations::5_12\*(C'\fR.
+.RS 4
+.IP Class::ISA 4
+.IX Item "Class::ISA"
+.PD 0
+.IP Pod::Plainer 4
+.IX Item "Pod::Plainer"
+.IP Shell 4
+.IX Item "Shell"
+.IP Switch 4
+.IX Item "Switch"
+.PD
+Switch is buggy and should be avoided. You may find Perl's new
+\&\f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR feature a suitable replacement.  See "Switch
+statements" in perlsyn for more information.
+.RE
+.RS 4
+.RE
+.IP "Assignment to $[" 4
+.IX Item "Assignment to $["
+.PD 0
+.IP "Use of the attribute :locked on subroutines" 4
+.IX Item "Use of the attribute :locked on subroutines"
+.IP "Use of ""locked"" with the attributes pragma" 4
+.IX Item "Use of ""locked"" with the attributes pragma"
+.IP "Use of ""unique"" with the attributes pragma" 4
+.IX Item "Use of ""unique"" with the attributes pragma"
+.IP Perl_pmflag 4
+.IX Item "Perl_pmflag"
+.PD
+\&\f(CW\*(C`Perl_pmflag\*(C'\fR is no longer part of Perl's public API. Calling it now
+generates a deprecation warning, and it will be removed in a future
+release. Although listed as part of the API, it was never documented,
+and only ever used in \fItoke.c\fR, and prior to 5.10, \fIregcomp.c\fR. In
+core, it has been replaced by a static function.
+.IP "Numerous Perl 4\-era libraries" 4
+.IX Item "Numerous Perl 4-era libraries"
+\&\fItermcap.pl\fR, \fItainted.pl\fR, \fIstat.pl\fR, \fIshellwords.pl\fR, \fIpwd.pl\fR,
+\&\fIopen3.pl\fR, \fIopen2.pl\fR, \fInewgetopt.pl\fR, \fIlook.pl\fR, \fIfind.pl\fR,
+\&\fIfinddepth.pl\fR, \fIimportenv.pl\fR, \fIhostname.pl\fR, \fIgetopts.pl\fR,
+\&\fIgetopt.pl\fR, \fIgetcwd.pl\fR, \fIflush.pl\fR, \fIfastcwd.pl\fR, \fIexceptions.pl\fR,
+\&\fIctime.pl\fR, \fIcomplete.pl\fR, \fIcacheout.pl\fR, \fIbigrat.pl\fR, \fIbigint.pl\fR,
+\&\fIbigfloat.pl\fR, \fIassert.pl\fR, \fIabbrev.pl\fR, \fIdotsh.pl\fR, and
+\&\fItimelocal.pl\fR are all now deprecated.  Earlier, Perl's developers
+intended to remove these libraries from Perl's core for the 5.14.0 release.
+.Sp
+During final testing before the release of 5.12.0, several developers
+discovered current production code using these ancient libraries, some
+inside the Perl core itself.  Accordingly, the pumpking granted them
+a stay of execution. They will begin to warn about their deprecation
+in the 5.14.0 release and will be removed in the 5.16.0 release.
+.SH "Unicode overhaul"
+.IX Header "Unicode overhaul"
+Perl's developers have made a concerted effort to update Perl to be in
+sync with the latest Unicode standard. Changes for this include:
+.PP
+Perl can now handle every Unicode character property. New documentation,
+perluniprops, lists all available non-Unihan character properties. By
+default, perl does not expose Unihan, deprecated or Unicode-internal
+properties.  See below for more details on these; there is also a section
+in the pod listing them, and explaining why they are not exposed.
+.PP
+Perl now fully supports the Unicode compound-style of using \f(CW\*(C`=\*(C'\fR
+and \f(CW\*(C`:\*(C'\fR in writing regular expressions: \f(CW\*(C`\ep{property=value}\*(C'\fR and
+\&\f(CW\*(C`\ep{property:value}\*(C'\fR (both of which mean the same thing).
+.PP
+Perl now fully supports the Unicode loose matching rules for text between
+the braces in \f(CW\*(C`\ep{...}\*(C'\fR constructs. In addition, Perl allows underscores
+between digits of numbers.
+.PP
+Perl now accepts all the Unicode-defined synonyms for properties and
+property values.
+.PP
+\&\f(CW\*(C`qr/\eX/\*(C'\fR, which matches a Unicode logical character, has
+been expanded to work better with various Asian languages. It
+now is defined as an \fIextended grapheme cluster\fR. (See
+<http://www.unicode.org/reports/tr29/>).  Anything matched previously
+and that made sense will continue to be accepted.   Additionally:
+.IP \(bu 4
+\&\f(CW\*(C`\eX\*(C'\fR will not break apart a \f(CW\*(C`CR\ LF\*(C'\fR sequence.
+.IP \(bu 4
+\&\f(CW\*(C`\eX\*(C'\fR will now match a sequence which includes the \f(CW\*(C`ZWJ\*(C'\fR and \f(CW\*(C`ZWNJ\*(C'\fR
+characters.
+.IP \(bu 4
+\&\f(CW\*(C`\eX\*(C'\fR will now always match at least one character, including an initial
+mark.  Marks generally come after a base character, but it is possible in
+Unicode to have them in isolation, and \f(CW\*(C`\eX\*(C'\fR will now handle that case,
+for example at the beginning of a line, or after a \f(CW\*(C`ZWSP\*(C'\fR. And this is
+the part where \f(CW\*(C`\eX\*(C'\fR doesn't match the things that it used to that don't
+make sense. Formerly, for example, you could have the nonsensical case
+of an accented LF.
+.IP \(bu 4
+\&\f(CW\*(C`\eX\*(C'\fR will now match a (Korean) Hangul syllable sequence, and the Thai
+and Lao exception cases.
+.PP
+Otherwise, this change should be transparent for the non-affected
+languages.
+.PP
+\&\f(CW\*(C`\ep{...}\*(C'\fR matches using the Canonical_Combining_Class property were
+completely broken in previous releases of Perl.  They should now work
+correctly.
+.PP
+Before Perl 5.12, the Unicode \f(CW\*(C`Decomposition_Type=Compat\*(C'\fR property
+and a Perl extension had the same name, which led to neither matching
+all the correct values (with more than 100 mistakes in one, and several
+thousand in the other). The Perl extension has now been renamed to be
+\&\f(CW\*(C`Decomposition_Type=Noncanonical\*(C'\fR (short: \f(CW\*(C`dt=noncanon\*(C'\fR). It has the
+same meaning as was previously intended, namely the union of all the
+non-canonical Decomposition types, with Unicode \f(CW\*(C`Compat\*(C'\fR being just
+one of those.
+.PP
+\&\f(CW\*(C`\ep{Decomposition_Type=Canonical}\*(C'\fR now includes the Hangul syllables.
+.PP
+\&\f(CW\*(C`\ep{Uppercase}\*(C'\fR and \f(CW\*(C`\ep{Lowercase}\*(C'\fR now work as the Unicode standard
+says they should.  This means they each match a few more characters than
+they used to.
+.PP
+\&\f(CW\*(C`\ep{Cntrl}\*(C'\fR now matches the same characters as \f(CW\*(C`\ep{Control}\*(C'\fR. This
+means it no longer will match Private Use (gc=co), Surrogates (gc=cs),
+nor Format (gc=cf) code points. The Format code points represent the
+biggest possible problem. All but 36 of them are either officially
+deprecated or strongly discouraged from being used. Of those 36, likely
+the most widely used are the soft hyphen (U+00AD), and BOM, ZWSP, ZWNJ,
+WJ, and similar characters, plus bidirectional controls.
+.PP
+\&\f(CW\*(C`\ep{Alpha}\*(C'\fR now matches the same characters as \f(CW\*(C`\ep{Alphabetic}\*(C'\fR. Before
+5.12, Perl's definition included a number of things that aren't
+really alpha (all marks) while omitting many that were. The definitions
+of \f(CW\*(C`\ep{Alnum}\*(C'\fR and \f(CW\*(C`\ep{Word}\*(C'\fR depend on Alpha's definition and have
+changed accordingly.
+.PP
+\&\f(CW\*(C`\ep{Word}\*(C'\fR no longer incorrectly matches non-word characters such
+as fractions.
+.PP
+\&\f(CW\*(C`\ep{Print}\*(C'\fR no longer matches the line control characters: Tab, LF,
+CR, FF, VT, and NEL. This brings it in line with standards and the
+documentation.
+.PP
+\&\f(CW\*(C`\ep{XDigit}\*(C'\fR now matches the same characters as \f(CW\*(C`\ep{Hex_Digit}\*(C'\fR. This
+means that in addition to the characters it currently matches,
+\&\f(CW\*(C`[A\-Fa\-f0\-9]\*(C'\fR, it will also match the 22 fullwidth equivalents, for
+example U+FF10: FULLWIDTH DIGIT ZERO.
+.PP
+The Numeric type property has been extended to include the Unihan
+characters.
+.PP
+There is a new Perl extension, the 'Present_In', or simply 'In',
+property. This is an extension of the Unicode Age property, but
+\&\f(CW\*(C`\ep{In=5.0}\*(C'\fR matches any code point whose usage has been determined
+\&\fIas of\fR Unicode version 5.0. The \f(CW\*(C`\ep{Age=5.0}\*(C'\fR only matches code points
+added in \fIprecisely\fR version 5.0.
+.PP
+A number of properties now have the correct values for unassigned
+code points. The affected properties are Bidi_Class, East_Asian_Width,
+Joining_Type, Decomposition_Type, Hangul_Syllable_Type, Numeric_Type,
+and Line_Break.
+.PP
+The Default_Ignorable_Code_Point, ID_Continue, and ID_Start properties
+are now up to date with current Unicode definitions.
+.PP
+Earlier versions of Perl erroneously exposed certain properties that
+are supposed to be Unicode internal-only.  Use of these in regular
+expressions will now generate, if enabled, a deprecation warning message.
+The properties are: Other_Alphabetic, Other_Default_Ignorable_Code_Point,
+Other_Grapheme_Extend, Other_ID_Continue, Other_ID_Start, Other_Lowercase,
+Other_Math, and Other_Uppercase.
+.PP
+It is now possible to change which Unicode properties Perl understands
+on a per-installation basis. As mentioned above, certain properties
+are turned off by default.  These include all the Unihan properties
+(which should be accessible via the CPAN module Unicode::Unihan) and any
+deprecated or Unicode internal-only property that Perl has never exposed.
+.PP
+The generated files in the \f(CW\*(C`lib/unicore/To\*(C'\fR directory are now more
+clearly marked as being stable, directly usable by applications.  New hash
+entries in them give the format of the normal entries, which allows for
+easier machine parsing. Perl can generate files in this directory for
+any property, though most are suppressed.  You can find instructions
+for changing which are written in perluniprops.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.ie n .IP """autodie""" 4
+.el .IP \f(CWautodie\fR 4
+.IX Item "autodie"
+\&\f(CW\*(C`autodie\*(C'\fR is a new lexically-scoped alternative for the \f(CW\*(C`Fatal\*(C'\fR module.
+The bundled version is 2.06_01. Note that in this release, using a string
+eval when \f(CW\*(C`autodie\*(C'\fR is in effect can cause the autodie behaviour to leak
+into the surrounding scope. See "BUGS" in autodie for more details.
+.Sp
+Version 2.06_01 has been added to the Perl core.
+.ie n .IP """Compress::Raw::Bzip2""" 4
+.el .IP \f(CWCompress::Raw::Bzip2\fR 4
+.IX Item "Compress::Raw::Bzip2"
+Version 2.024 has been added to the Perl core.
+.ie n .IP """overloading""" 4
+.el .IP \f(CWoverloading\fR 4
+.IX Item "overloading"
+\&\f(CW\*(C`overloading\*(C'\fR allows you to lexically disable or enable overloading
+for some or all operations.
+.Sp
+Version 0.001 has been added to the Perl core.
+.ie n .IP """parent""" 4
+.el .IP \f(CWparent\fR 4
+.IX Item "parent"
+\&\f(CW\*(C`parent\*(C'\fR establishes an ISA relationship with base classes at compile
+time. It provides the key feature of \f(CW\*(C`base\*(C'\fR without further unwanted
+behaviors.
+.Sp
+Version 0.223 has been added to the Perl core.
+.ie n .IP """Parse::CPAN::Meta""" 4
+.el .IP \f(CWParse::CPAN::Meta\fR 4
+.IX Item "Parse::CPAN::Meta"
+Version 1.40 has been added to the Perl core.
+.ie n .IP """VMS::DCLsym""" 4
+.el .IP \f(CWVMS::DCLsym\fR 4
+.IX Item "VMS::DCLsym"
+Version 1.03 has been added to the Perl core.
+.ie n .IP """VMS::Stdio""" 4
+.el .IP \f(CWVMS::Stdio\fR 4
+.IX Item "VMS::Stdio"
+Version 2.4 has been added to the Perl core.
+.ie n .IP """XS::APItest::KeywordRPN""" 4
+.el .IP \f(CWXS::APItest::KeywordRPN\fR 4
+.IX Item "XS::APItest::KeywordRPN"
+Version 0.003 has been added to the Perl core.
+.SS "Updated Pragmata"
+.IX Subsection "Updated Pragmata"
+.ie n .IP """base""" 4
+.el .IP \f(CWbase\fR 4
+.IX Item "base"
+Upgraded from version 2.13 to 2.15.
+.ie n .IP """bignum""" 4
+.el .IP \f(CWbignum\fR 4
+.IX Item "bignum"
+Upgraded from version 0.22 to 0.23.
+.ie n .IP """charnames""" 4
+.el .IP \f(CWcharnames\fR 4
+.IX Item "charnames"
+\&\f(CW\*(C`charnames\*(C'\fR now contains the Unicode \fINameAliases.txt\fR database file.
+This has the effect of adding some extra \f(CW\*(C`\eN\*(C'\fR character names that
+formerly wouldn't have been recognised; for example, \f(CW"\eN{LATIN CAPITAL
+LETTER GHA}"\fR.
+.Sp
+Upgraded from version 1.06 to 1.07.
+.ie n .IP """constant""" 4
+.el .IP \f(CWconstant\fR 4
+.IX Item "constant"
+Upgraded from version 1.13 to 1.20.
+.ie n .IP """diagnostics""" 4
+.el .IP \f(CWdiagnostics\fR 4
+.IX Item "diagnostics"
+\&\f(CW\*(C`diagnostics\*(C'\fR now supports %.0f formatting internally.
+.Sp
+\&\f(CW\*(C`diagnostics\*(C'\fR no longer suppresses \f(CW\*(C`Use of uninitialized value in range
+(or flip)\*(C'\fR warnings. [perl #71204]
+.Sp
+Upgraded from version 1.17 to 1.19.
+.ie n .IP """feature""" 4
+.el .IP \f(CWfeature\fR 4
+.IX Item "feature"
+In \f(CW\*(C`feature\*(C'\fR, the meaning of the \f(CW\*(C`:5.10\*(C'\fR and \f(CW\*(C`:5.10.X\*(C'\fR feature
+bundles has changed slightly. The last component, if any (i.e. \f(CW\*(C`X\*(C'\fR) is
+simply ignored.  This is predicated on the assumption that new features
+will not, in general, be added to maintenance releases. So \f(CW\*(C`:5.10\*(C'\fR
+and \f(CW\*(C`:5.10.X\*(C'\fR have identical effect. This is a change to the behaviour
+documented for 5.10.0.
+.Sp
+\&\f(CW\*(C`feature\*(C'\fR now includes the \f(CW\*(C`unicode_strings\*(C'\fR feature:
+.Sp
+.Vb 1
+\&    use feature "unicode_strings";
+.Ve
+.Sp
+This pragma turns on Unicode semantics for the case-changing operations
+(\f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR) on strings that don't have the
+internal UTF\-8 flag set, but that contain single-byte characters between
+128 and 255.
+.Sp
+Upgraded from version 1.11 to 1.16.
+.ie n .IP """less""" 4
+.el .IP \f(CWless\fR 4
+.IX Item "less"
+\&\f(CW\*(C`less\*(C'\fR now includes the \f(CW\*(C`stash_name\*(C'\fR method to allow subclasses of
+\&\f(CW\*(C`less\*(C'\fR to pick where in %^H to store their stash.
+.Sp
+Upgraded from version 0.02 to 0.03.
+.ie n .IP """lib""" 4
+.el .IP \f(CWlib\fR 4
+.IX Item "lib"
+Upgraded from version 0.5565 to 0.62.
+.ie n .IP """mro""" 4
+.el .IP \f(CWmro\fR 4
+.IX Item "mro"
+\&\f(CW\*(C`mro\*(C'\fR is now implemented as an XS extension. The documented interface has
+not changed. Code relying on the implementation detail that some \f(CW\*(C`mro::\*(C'\fR
+methods happened to be available at all times gets to "keep both pieces".
+.Sp
+Upgraded from version 1.00 to 1.02.
+.ie n .IP """overload""" 4
+.el .IP \f(CWoverload\fR 4
+.IX Item "overload"
+\&\f(CW\*(C`overload\*(C'\fR now allow overloading of 'qr'.
+.Sp
+Upgraded from version 1.06 to 1.10.
+.ie n .IP """threads""" 4
+.el .IP \f(CWthreads\fR 4
+.IX Item "threads"
+Upgraded from version 1.67 to 1.75.
+.ie n .IP """threads::shared""" 4
+.el .IP \f(CWthreads::shared\fR 4
+.IX Item "threads::shared"
+Upgraded from version 1.14 to 1.32.
+.ie n .IP """version""" 4
+.el .IP \f(CWversion\fR 4
+.IX Item "version"
+\&\f(CW\*(C`version\*(C'\fR now has support for "Version number formats" as described
+earlier in this document and in its own documentation.
+.Sp
+Upgraded from version 0.74 to 0.82.
+.ie n .IP """warnings""" 4
+.el .IP \f(CWwarnings\fR 4
+.IX Item "warnings"
+\&\f(CW\*(C`warnings\*(C'\fR has a new \f(CWwarnings::fatal_enabled()\fR function.  It also
+includes a new \f(CW\*(C`illegalproto\*(C'\fR warning category. See also "New or
+Changed Diagnostics" for this change.
+.Sp
+Upgraded from version 1.06 to 1.09.
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+.ie n .IP """Archive::Extract""" 4
+.el .IP \f(CWArchive::Extract\fR 4
+.IX Item "Archive::Extract"
+Upgraded from version 0.24 to 0.38.
+.ie n .IP """Archive::Tar""" 4
+.el .IP \f(CWArchive::Tar\fR 4
+.IX Item "Archive::Tar"
+Upgraded from version 1.38 to 1.54.
+.ie n .IP """Attribute::Handlers""" 4
+.el .IP \f(CWAttribute::Handlers\fR 4
+.IX Item "Attribute::Handlers"
+Upgraded from version 0.79 to 0.87.
+.ie n .IP """AutoLoader""" 4
+.el .IP \f(CWAutoLoader\fR 4
+.IX Item "AutoLoader"
+Upgraded from version 5.63 to 5.70.
+.ie n .IP """B::Concise""" 4
+.el .IP \f(CWB::Concise\fR 4
+.IX Item "B::Concise"
+Upgraded from version 0.74 to 0.78.
+.ie n .IP """B::Debug""" 4
+.el .IP \f(CWB::Debug\fR 4
+.IX Item "B::Debug"
+Upgraded from version 1.05 to 1.12.
+.ie n .IP """B::Deparse""" 4
+.el .IP \f(CWB::Deparse\fR 4
+.IX Item "B::Deparse"
+Upgraded from version 0.83 to 0.96.
+.ie n .IP """B::Lint""" 4
+.el .IP \f(CWB::Lint\fR 4
+.IX Item "B::Lint"
+Upgraded from version 1.09 to 1.11_01.
+.ie n .IP """CGI""" 4
+.el .IP \f(CWCGI\fR 4
+.IX Item "CGI"
+Upgraded from version 3.29 to 3.48.
+.ie n .IP """Class::ISA""" 4
+.el .IP \f(CWClass::ISA\fR 4
+.IX Item "Class::ISA"
+Upgraded from version 0.33 to 0.36.
+.Sp
+NOTE: \f(CW\*(C`Class::ISA\*(C'\fR is deprecated and may be removed from a future
+version of Perl.
+.ie n .IP """Compress::Raw::Zlib""" 4
+.el .IP \f(CWCompress::Raw::Zlib\fR 4
+.IX Item "Compress::Raw::Zlib"
+Upgraded from version 2.008 to 2.024.
+.ie n .IP """CPAN""" 4
+.el .IP \f(CWCPAN\fR 4
+.IX Item "CPAN"
+Upgraded from version 1.9205 to 1.94_56.
+.ie n .IP """CPANPLUS""" 4
+.el .IP \f(CWCPANPLUS\fR 4
+.IX Item "CPANPLUS"
+Upgraded from version 0.84 to 0.90.
+.ie n .IP """CPANPLUS::Dist::Build""" 4
+.el .IP \f(CWCPANPLUS::Dist::Build\fR 4
+.IX Item "CPANPLUS::Dist::Build"
+Upgraded from version 0.06_02 to 0.46.
+.ie n .IP """Data::Dumper""" 4
+.el .IP \f(CWData::Dumper\fR 4
+.IX Item "Data::Dumper"
+Upgraded from version 2.121_14 to 2.125.
+.ie n .IP """DB_File""" 4
+.el .IP \f(CWDB_File\fR 4
+.IX Item "DB_File"
+Upgraded from version 1.816_1 to 1.820.
+.ie n .IP """Devel::PPPort""" 4
+.el .IP \f(CWDevel::PPPort\fR 4
+.IX Item "Devel::PPPort"
+Upgraded from version 3.13 to 3.19.
+.ie n .IP """Digest""" 4
+.el .IP \f(CWDigest\fR 4
+.IX Item "Digest"
+Upgraded from version 1.15 to 1.16.
+.ie n .IP """Digest::MD5""" 4
+.el .IP \f(CWDigest::MD5\fR 4
+.IX Item "Digest::MD5"
+Upgraded from version 2.36_01 to 2.39.
+.ie n .IP """Digest::SHA""" 4
+.el .IP \f(CWDigest::SHA\fR 4
+.IX Item "Digest::SHA"
+Upgraded from version 5.45 to 5.47.
+.ie n .IP """Encode""" 4
+.el .IP \f(CWEncode\fR 4
+.IX Item "Encode"
+Upgraded from version 2.23 to 2.39.
+.ie n .IP """Exporter""" 4
+.el .IP \f(CWExporter\fR 4
+.IX Item "Exporter"
+Upgraded from version 5.62 to 5.64_01.
+.ie n .IP """ExtUtils::CBuilder""" 4
+.el .IP \f(CWExtUtils::CBuilder\fR 4
+.IX Item "ExtUtils::CBuilder"
+Upgraded from version 0.21 to 0.27.
+.ie n .IP """ExtUtils::Command""" 4
+.el .IP \f(CWExtUtils::Command\fR 4
+.IX Item "ExtUtils::Command"
+Upgraded from version 1.13 to 1.16.
+.ie n .IP """ExtUtils::Constant""" 4
+.el .IP \f(CWExtUtils::Constant\fR 4
+.IX Item "ExtUtils::Constant"
+Upgraded from version 0.2 to 0.22.
+.ie n .IP """ExtUtils::Install""" 4
+.el .IP \f(CWExtUtils::Install\fR 4
+.IX Item "ExtUtils::Install"
+Upgraded from version 1.44 to 1.55.
+.ie n .IP """ExtUtils::MakeMaker""" 4
+.el .IP \f(CWExtUtils::MakeMaker\fR 4
+.IX Item "ExtUtils::MakeMaker"
+Upgraded from version 6.42 to 6.56.
+.ie n .IP """ExtUtils::Manifest""" 4
+.el .IP \f(CWExtUtils::Manifest\fR 4
+.IX Item "ExtUtils::Manifest"
+Upgraded from version 1.51_01 to 1.57.
+.ie n .IP """ExtUtils::ParseXS""" 4
+.el .IP \f(CWExtUtils::ParseXS\fR 4
+.IX Item "ExtUtils::ParseXS"
+Upgraded from version 2.18_02 to 2.21.
+.ie n .IP """File::Fetch""" 4
+.el .IP \f(CWFile::Fetch\fR 4
+.IX Item "File::Fetch"
+Upgraded from version 0.14 to 0.24.
+.ie n .IP """File::Path""" 4
+.el .IP \f(CWFile::Path\fR 4
+.IX Item "File::Path"
+Upgraded from version 2.04 to 2.08_01.
+.ie n .IP """File::Temp""" 4
+.el .IP \f(CWFile::Temp\fR 4
+.IX Item "File::Temp"
+Upgraded from version 0.18 to 0.22.
+.ie n .IP """Filter::Simple""" 4
+.el .IP \f(CWFilter::Simple\fR 4
+.IX Item "Filter::Simple"
+Upgraded from version 0.82 to 0.84.
+.ie n .IP """Filter::Util::Call""" 4
+.el .IP \f(CWFilter::Util::Call\fR 4
+.IX Item "Filter::Util::Call"
+Upgraded from version 1.07 to 1.08.
+.ie n .IP """Getopt::Long""" 4
+.el .IP \f(CWGetopt::Long\fR 4
+.IX Item "Getopt::Long"
+Upgraded from version 2.37 to 2.38.
+.ie n .IP """IO""" 4
+.el .IP \f(CWIO\fR 4
+.IX Item "IO"
+Upgraded from version 1.23_01 to 1.25_02.
+.ie n .IP """IO::Zlib""" 4
+.el .IP \f(CWIO::Zlib\fR 4
+.IX Item "IO::Zlib"
+Upgraded from version 1.07 to 1.10.
+.ie n .IP """IPC::Cmd""" 4
+.el .IP \f(CWIPC::Cmd\fR 4
+.IX Item "IPC::Cmd"
+Upgraded from version 0.40_1 to 0.54.
+.ie n .IP """IPC::SysV""" 4
+.el .IP \f(CWIPC::SysV\fR 4
+.IX Item "IPC::SysV"
+Upgraded from version 1.05 to 2.01.
+.ie n .IP """Locale::Maketext""" 4
+.el .IP \f(CWLocale::Maketext\fR 4
+.IX Item "Locale::Maketext"
+Upgraded from version 1.12 to 1.14.
+.ie n .IP """Locale::Maketext::Simple""" 4
+.el .IP \f(CWLocale::Maketext::Simple\fR 4
+.IX Item "Locale::Maketext::Simple"
+Upgraded from version 0.18 to 0.21.
+.ie n .IP """Log::Message""" 4
+.el .IP \f(CWLog::Message\fR 4
+.IX Item "Log::Message"
+Upgraded from version 0.01 to 0.02.
+.ie n .IP """Log::Message::Simple""" 4
+.el .IP \f(CWLog::Message::Simple\fR 4
+.IX Item "Log::Message::Simple"
+Upgraded from version 0.04 to 0.06.
+.ie n .IP """Math::BigInt""" 4
+.el .IP \f(CWMath::BigInt\fR 4
+.IX Item "Math::BigInt"
+Upgraded from version 1.88 to 1.89_01.
+.ie n .IP """Math::BigInt::FastCalc""" 4
+.el .IP \f(CWMath::BigInt::FastCalc\fR 4
+.IX Item "Math::BigInt::FastCalc"
+Upgraded from version 0.16 to 0.19.
+.ie n .IP """Math::BigRat""" 4
+.el .IP \f(CWMath::BigRat\fR 4
+.IX Item "Math::BigRat"
+Upgraded from version 0.21 to 0.24.
+.ie n .IP """Math::Complex""" 4
+.el .IP \f(CWMath::Complex\fR 4
+.IX Item "Math::Complex"
+Upgraded from version 1.37 to 1.56.
+.ie n .IP """Memoize""" 4
+.el .IP \f(CWMemoize\fR 4
+.IX Item "Memoize"
+Upgraded from version 1.01_02 to 1.01_03.
+.ie n .IP """MIME::Base64""" 4
+.el .IP \f(CWMIME::Base64\fR 4
+.IX Item "MIME::Base64"
+Upgraded from version 3.07_01 to 3.08.
+.ie n .IP """Module::Build""" 4
+.el .IP \f(CWModule::Build\fR 4
+.IX Item "Module::Build"
+Upgraded from version 0.2808_01 to 0.3603.
+.ie n .IP """Module::CoreList""" 4
+.el .IP \f(CWModule::CoreList\fR 4
+.IX Item "Module::CoreList"
+Upgraded from version 2.12 to 2.29.
+.ie n .IP """Module::Load""" 4
+.el .IP \f(CWModule::Load\fR 4
+.IX Item "Module::Load"
+Upgraded from version 0.12 to 0.16.
+.ie n .IP """Module::Load::Conditional""" 4
+.el .IP \f(CWModule::Load::Conditional\fR 4
+.IX Item "Module::Load::Conditional"
+Upgraded from version 0.22 to 0.34.
+.ie n .IP """Module::Loaded""" 4
+.el .IP \f(CWModule::Loaded\fR 4
+.IX Item "Module::Loaded"
+Upgraded from version 0.01 to 0.06.
+.ie n .IP """Module::Pluggable""" 4
+.el .IP \f(CWModule::Pluggable\fR 4
+.IX Item "Module::Pluggable"
+Upgraded from version 3.6 to 3.9.
+.ie n .IP """Net::Ping""" 4
+.el .IP \f(CWNet::Ping\fR 4
+.IX Item "Net::Ping"
+Upgraded from version 2.33 to 2.36.
+.ie n .IP """NEXT""" 4
+.el .IP \f(CWNEXT\fR 4
+.IX Item "NEXT"
+Upgraded from version 0.60_01 to 0.64.
+.ie n .IP """Object::Accessor""" 4
+.el .IP \f(CWObject::Accessor\fR 4
+.IX Item "Object::Accessor"
+Upgraded from version 0.32 to 0.36.
+.ie n .IP """Package::Constants""" 4
+.el .IP \f(CWPackage::Constants\fR 4
+.IX Item "Package::Constants"
+Upgraded from version 0.01 to 0.02.
+.ie n .IP """PerlIO""" 4
+.el .IP \f(CWPerlIO\fR 4
+.IX Item "PerlIO"
+Upgraded from version 1.04 to 1.06.
+.ie n .IP """Pod::Parser""" 4
+.el .IP \f(CWPod::Parser\fR 4
+.IX Item "Pod::Parser"
+Upgraded from version 1.35 to 1.37.
+.ie n .IP """Pod::Perldoc""" 4
+.el .IP \f(CWPod::Perldoc\fR 4
+.IX Item "Pod::Perldoc"
+Upgraded from version 3.14_02 to 3.15_02.
+.ie n .IP """Pod::Plainer""" 4
+.el .IP \f(CWPod::Plainer\fR 4
+.IX Item "Pod::Plainer"
+Upgraded from version 0.01 to 1.02.
+.Sp
+NOTE: \f(CW\*(C`Pod::Plainer\*(C'\fR is deprecated and may be removed from a future
+version of Perl.
+.ie n .IP """Pod::Simple""" 4
+.el .IP \f(CWPod::Simple\fR 4
+.IX Item "Pod::Simple"
+Upgraded from version 3.05 to 3.13.
+.ie n .IP """Safe""" 4
+.el .IP \f(CWSafe\fR 4
+.IX Item "Safe"
+Upgraded from version 2.12 to 2.22.
+.ie n .IP """SelfLoader""" 4
+.el .IP \f(CWSelfLoader\fR 4
+.IX Item "SelfLoader"
+Upgraded from version 1.11 to 1.17.
+.ie n .IP """Storable""" 4
+.el .IP \f(CWStorable\fR 4
+.IX Item "Storable"
+Upgraded from version 2.18 to 2.22.
+.ie n .IP """Switch""" 4
+.el .IP \f(CWSwitch\fR 4
+.IX Item "Switch"
+Upgraded from version 2.13 to 2.16.
+.Sp
+NOTE: \f(CW\*(C`Switch\*(C'\fR is deprecated and may be removed from a future version
+of Perl.
+.ie n .IP """Sys::Syslog""" 4
+.el .IP \f(CWSys::Syslog\fR 4
+.IX Item "Sys::Syslog"
+Upgraded from version 0.22 to 0.27.
+.ie n .IP """Term::ANSIColor""" 4
+.el .IP \f(CWTerm::ANSIColor\fR 4
+.IX Item "Term::ANSIColor"
+Upgraded from version 1.12 to 2.02.
+.ie n .IP """Term::UI""" 4
+.el .IP \f(CWTerm::UI\fR 4
+.IX Item "Term::UI"
+Upgraded from version 0.18 to 0.20.
+.ie n .IP """Test""" 4
+.el .IP \f(CWTest\fR 4
+.IX Item "Test"
+Upgraded from version 1.25 to 1.25_02.
+.ie n .IP """Test::Harness""" 4
+.el .IP \f(CWTest::Harness\fR 4
+.IX Item "Test::Harness"
+Upgraded from version 2.64 to 3.17.
+.ie n .IP """Test::Simple""" 4
+.el .IP \f(CWTest::Simple\fR 4
+.IX Item "Test::Simple"
+Upgraded from version 0.72 to 0.94.
+.ie n .IP """Text::Balanced""" 4
+.el .IP \f(CWText::Balanced\fR 4
+.IX Item "Text::Balanced"
+Upgraded from version 2.0.0 to 2.02.
+.ie n .IP """Text::ParseWords""" 4
+.el .IP \f(CWText::ParseWords\fR 4
+.IX Item "Text::ParseWords"
+Upgraded from version 3.26 to 3.27.
+.ie n .IP """Text::Soundex""" 4
+.el .IP \f(CWText::Soundex\fR 4
+.IX Item "Text::Soundex"
+Upgraded from version 3.03 to 3.03_01.
+.ie n .IP """Thread::Queue""" 4
+.el .IP \f(CWThread::Queue\fR 4
+.IX Item "Thread::Queue"
+Upgraded from version 2.00 to 2.11.
+.ie n .IP """Thread::Semaphore""" 4
+.el .IP \f(CWThread::Semaphore\fR 4
+.IX Item "Thread::Semaphore"
+Upgraded from version 2.01 to 2.09.
+.ie n .IP """Tie::RefHash""" 4
+.el .IP \f(CWTie::RefHash\fR 4
+.IX Item "Tie::RefHash"
+Upgraded from version 1.37 to 1.38.
+.ie n .IP """Time::HiRes""" 4
+.el .IP \f(CWTime::HiRes\fR 4
+.IX Item "Time::HiRes"
+Upgraded from version 1.9711 to 1.9719.
+.ie n .IP """Time::Local""" 4
+.el .IP \f(CWTime::Local\fR 4
+.IX Item "Time::Local"
+Upgraded from version 1.18 to 1.1901_01.
+.ie n .IP """Time::Piece""" 4
+.el .IP \f(CWTime::Piece\fR 4
+.IX Item "Time::Piece"
+Upgraded from version 1.12 to 1.15.
+.ie n .IP """Unicode::Collate""" 4
+.el .IP \f(CWUnicode::Collate\fR 4
+.IX Item "Unicode::Collate"
+Upgraded from version 0.52 to 0.52_01.
+.ie n .IP """Unicode::Normalize""" 4
+.el .IP \f(CWUnicode::Normalize\fR 4
+.IX Item "Unicode::Normalize"
+Upgraded from version 1.02 to 1.03.
+.ie n .IP """Win32""" 4
+.el .IP \f(CWWin32\fR 4
+.IX Item "Win32"
+Upgraded from version 0.34 to 0.39.
+.ie n .IP """Win32API::File""" 4
+.el .IP \f(CWWin32API::File\fR 4
+.IX Item "Win32API::File"
+Upgraded from version 0.1001_01 to 0.1101.
+.ie n .IP """XSLoader""" 4
+.el .IP \f(CWXSLoader\fR 4
+.IX Item "XSLoader"
+Upgraded from version 0.08 to 0.10.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+.ie n .IP """attrs""" 4
+.el .IP \f(CWattrs\fR 4
+.IX Item "attrs"
+Removed from the Perl core.  Prior version was 1.02.
+.ie n .IP """CPAN::API::HOWTO""" 4
+.el .IP \f(CWCPAN::API::HOWTO\fR 4
+.IX Item "CPAN::API::HOWTO"
+Removed from the Perl core.  Prior version was 'undef'.
+.ie n .IP """CPAN::DeferedCode""" 4
+.el .IP \f(CWCPAN::DeferedCode\fR 4
+.IX Item "CPAN::DeferedCode"
+Removed from the Perl core.  Prior version was 5.50.
+.ie n .IP """CPANPLUS::inc""" 4
+.el .IP \f(CWCPANPLUS::inc\fR 4
+.IX Item "CPANPLUS::inc"
+Removed from the Perl core.  Prior version was 'undef'.
+.ie n .IP """DCLsym""" 4
+.el .IP \f(CWDCLsym\fR 4
+.IX Item "DCLsym"
+Removed from the Perl core.  Prior version was 1.03.
+.ie n .IP """ExtUtils::MakeMaker::bytes""" 4
+.el .IP \f(CWExtUtils::MakeMaker::bytes\fR 4
+.IX Item "ExtUtils::MakeMaker::bytes"
+Removed from the Perl core.  Prior version was 6.42.
+.ie n .IP """ExtUtils::MakeMaker::vmsish""" 4
+.el .IP \f(CWExtUtils::MakeMaker::vmsish\fR 4
+.IX Item "ExtUtils::MakeMaker::vmsish"
+Removed from the Perl core.  Prior version was 6.42.
+.ie n .IP """Stdio""" 4
+.el .IP \f(CWStdio\fR 4
+.IX Item "Stdio"
+Removed from the Perl core.  Prior version was 2.3.
+.ie n .IP """Test::Harness::Assert""" 4
+.el .IP \f(CWTest::Harness::Assert\fR 4
+.IX Item "Test::Harness::Assert"
+Removed from the Perl core.  Prior version was 0.02.
+.ie n .IP """Test::Harness::Iterator""" 4
+.el .IP \f(CWTest::Harness::Iterator\fR 4
+.IX Item "Test::Harness::Iterator"
+Removed from the Perl core.  Prior version was 0.02.
+.ie n .IP """Test::Harness::Point""" 4
+.el .IP \f(CWTest::Harness::Point\fR 4
+.IX Item "Test::Harness::Point"
+Removed from the Perl core.  Prior version was 0.01.
+.ie n .IP """Test::Harness::Results""" 4
+.el .IP \f(CWTest::Harness::Results\fR 4
+.IX Item "Test::Harness::Results"
+Removed from the Perl core.  Prior version was 0.01.
+.ie n .IP """Test::Harness::Straps""" 4
+.el .IP \f(CWTest::Harness::Straps\fR 4
+.IX Item "Test::Harness::Straps"
+Removed from the Perl core.  Prior version was 0.26_01.
+.ie n .IP """Test::Harness::Util""" 4
+.el .IP \f(CWTest::Harness::Util\fR 4
+.IX Item "Test::Harness::Util"
+Removed from the Perl core.  Prior version was 0.01.
+.ie n .IP """XSSymSet""" 4
+.el .IP \f(CWXSSymSet\fR 4
+.IX Item "XSSymSet"
+Removed from the Perl core.  Prior version was 1.1.
+.SS "Deprecated Modules and Pragmata"
+.IX Subsection "Deprecated Modules and Pragmata"
+See "Deprecated Modules" above.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+.IP \(bu 4
+perlhaiku contains instructions on how to build perl for the Haiku
+platform.
+.IP \(bu 4
+perlmroapi describes the new interface for pluggable Method Resolution
+Orders.
+.IP \(bu 4
+perlperf, by Richard Foley, provides an introduction to the use of
+performance and optimization techniques which can be used with particular
+reference to perl programs.
+.IP \(bu 4
+perlrepository describes how to access the perl source using the \fIgit\fR
+version control system.
+.IP \(bu 4
+perlpolicy extends the "Social contract about contributed modules" into
+the beginnings of a document on Perl porting policies.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+.IP \(bu 4
+The various large \fIChanges*\fR files (which listed every change made
+to perl over the last 18 years) have been removed, and replaced by a
+small file, also called \fIChanges\fR, which just explains how that same
+information may be extracted from the git version control system.
+.IP \(bu 4
+\&\fIPorting/patching.pod\fR has been deleted, as it mainly described
+interacting with the old Perforce-based repository, which is now obsolete.
+Information still relevant has been moved to perlrepository.
+.IP \(bu 4
+The syntax \f(CW\*(C`unless (EXPR) BLOCK else BLOCK\*(C'\fR is now documented as valid,
+as is the syntax \f(CW\*(C`unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else
+BLOCK\*(C'\fR, although actually using the latter may not be the best idea for
+the readability of your source code.
+.IP \(bu 4
+Documented \-X overloading.
+.IP \(bu 4
+Documented that \f(CWwhen()\fR treats specially most of the filetest operators
+.IP \(bu 4
+Documented \f(CW\*(C`when\*(C'\fR as a syntax modifier.
+.IP \(bu 4
+Eliminated "Old Perl threads tutorial", which described 5005 threads.
+.Sp
+\&\fIpod/perlthrtut.pod\fR is the same material reworked for ithreads.
+.IP \(bu 4
+Correct previous documentation: v\-strings are not deprecated
+.Sp
+With version objects, we need them to use MODULE VERSION syntax. This
+patch removes the deprecation notice.
+.IP \(bu 4
+Security contact information is now part of perlsec.
+.IP \(bu 4
+A significant fraction of the core documentation has been updated to
+clarify the behavior of Perl's Unicode handling.
+.Sp
+Much of the remaining core documentation has been reviewed and edited
+for clarity, consistent use of language, and to fix the spelling of Tom
+Christiansen's name.
+.IP \(bu 4
+The Pod specification (perlpodspec) has been updated to bring the
+specification in line with modern usage already supported by most Pod
+systems. A parameter string may now follow the format name in a
+"begin/end" region. Links to URIs with a text description are now
+allowed. The usage of \f(CW\*(C`L<"section">\*(C'\fR has been marked as
+deprecated.
+.IP \(bu 4
+if.pm has been documented in "use" in perlfunc as a means to get
+conditional loading of modules despite the implicit BEGIN block around
+\&\f(CW\*(C`use\*(C'\fR.
+.IP \(bu 4
+The documentation for \f(CW$1\fR in perlvar.pod has been clarified.
+.IP \(bu 4
+\&\f(CW\*(C`\eN{U+\fR\f(CIcode point\fR\f(CW}\*(C'\fR is now documented.
+.SH "Selected Performance Enhancements"
+.IX Header "Selected Performance Enhancements"
+.IP \(bu 4
+A new internal cache means that \f(CWisa()\fR will often be faster.
+.IP \(bu 4
+The implementation of \f(CW\*(C`C3\*(C'\fR Method Resolution Order has been
+optimised \- linearisation for classes with single inheritance is 40%
+faster. Performance for multiple inheritance is unchanged.
+.IP \(bu 4
+Under \f(CW\*(C`use locale\*(C'\fR, the locale-relevant information is now cached on
+read-only values, such as the list returned by \f(CW\*(C`keys %hash\*(C'\fR. This makes
+operations such as \f(CW\*(C`sort keys %hash\*(C'\fR in the scope of \f(CW\*(C`use locale\*(C'\fR
+much faster.
+.IP \(bu 4
+Empty \f(CW\*(C`DESTROY\*(C'\fR methods are no longer called.
+.IP \(bu 4
+\&\f(CWPerl_sv_utf8_upgrade()\fR is now faster.
+.IP \(bu 4
+\&\f(CW\*(C`keys\*(C'\fR on empty hash is now faster.
+.IP \(bu 4
+\&\f(CW\*(C`if (%foo)\*(C'\fR has been optimized to be faster than \f(CW\*(C`if (keys %foo)\*(C'\fR.
+.IP \(bu 4
+The string repetition operator (\f(CW\*(C`$str x $num\*(C'\fR) is now several times
+faster when \f(CW$str\fR has length one or \f(CW$num\fR is large.
+.IP \(bu 4
+Reversing an array to itself (as in \f(CW\*(C`@a = reverse @a\*(C'\fR) in void context
+now happens in-place and is several orders of magnitude faster than
+it used to be. It will also preserve non-existent elements whenever
+possible, i.e. for non magical arrays or tied arrays with \f(CW\*(C`EXISTS\*(C'\fR
+and \f(CW\*(C`DELETE\*(C'\fR methods.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.IP \(bu 4
+perlapi, perlintern, perlmodlib and perltoc are now all
+generated at build time, rather than being shipped as part of the release.
+.IP \(bu 4
+If \f(CW\*(C`vendorlib\*(C'\fR and \f(CW\*(C`vendorarch\*(C'\fR are the same, then they are only added
+to \f(CW@INC\fR once.
+.IP \(bu 4
+\&\f(CW$Config{usedevel}\fR and the C\-level \f(CW\*(C`PERL_USE_DEVEL\*(C'\fR are now defined if
+perl is built with  \f(CW\*(C`\-Dusedevel\*(C'\fR.
+.IP \(bu 4
+\&\fIConfigure\fR will enable use of \f(CW\*(C`\-fstack\-protector\*(C'\fR, to provide protection
+against stack-smashing attacks, if the compiler supports it.
+.IP \(bu 4
+\&\fIConfigure\fR will now determine the correct prototypes for re-entrant
+functions and for \f(CW\*(C`gconvert\*(C'\fR if you are using a C++ compiler rather
+than a C compiler.
+.IP \(bu 4
+On Unix, if you build from a tree containing a git repository, the
+configuration process will note the commit hash you have checked out, for
+display in the output of \f(CW\*(C`perl \-v\*(C'\fR and \f(CW\*(C`perl \-V\*(C'\fR. Unpushed local commits
+are automatically added to the list of local patches displayed by
+\&\f(CW\*(C`perl \-V\*(C'\fR.
+.IP \(bu 4
+Perl now supports SystemTap's \f(CW\*(C`dtrace\*(C'\fR compatibility layer and an
+issue with linking \f(CW\*(C`miniperl\*(C'\fR has been fixed in the process.
+.IP \(bu 4
+perldoc now uses \f(CW\*(C`less \-R\*(C'\fR instead of \f(CW\*(C`less\*(C'\fR for improved behaviour
+in the face of \f(CW\*(C`groff\*(C'\fR's new usage of ANSI escape codes.
+.IP \(bu 4
+\&\f(CW\*(C`perl \-V\*(C'\fR now reports use of the compile-time options \f(CW\*(C`USE_PERL_ATOF\*(C'\fR and
+\&\f(CW\*(C`USE_ATTRIBUTES_FOR_PERLIO\*(C'\fR.
+.IP \(bu 4
+As part of the flattening of \fIext\fR, all extensions on all platforms are
+built by \fImake_ext.pl\fR. This replaces the Unix-specific
+\&\fIext/util/make_ext\fR, VMS-specific \fImake_ext.com\fR and Win32\-specific
+\&\fIwin32/buildext.pl\fR.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+Each release of Perl sees numerous internal changes which shouldn't
+affect day to day usage but may still be notable for developers working
+with Perl's source code.
+.IP \(bu 4
+The J.R.R. Tolkien quotes at the head of C source file have been checked
+and proper citations added, thanks to a patch from Tom Christiansen.
+.IP \(bu 4
+The internal structure of the dual-life modules traditionally found in
+the \fIlib/\fR and \fIext/\fR directories in the perl source has changed
+significantly. Where possible, dual-lifed modules have been extracted
+from \fIlib/\fR and \fIext/\fR.
+.Sp
+Dual-lifed modules maintained by Perl's developers as part of the Perl
+core now live in \fIdist/\fR.  Dual-lifed modules maintained primarily on
+CPAN now live in \fIcpan/\fR.  When reporting a bug in a module located
+under \fIcpan/\fR, please send your bug report directly to the module's
+bug tracker or author, rather than Perl's bug tracker.
+.IP \(bu 4
+\&\f(CW\*(C`\eN{...}\*(C'\fR now compiles better, always forces UTF\-8 internal representation
+.Sp
+Perl's developers have fixed several problems with the recognition of
+\&\f(CW\*(C`\eN{...}\*(C'\fR constructs.  As part of this, perl will store any scalar
+or regex containing \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR or \f(CW\*(C`\eN{U+\fR\f(CIcode point\fR\f(CW}\*(C'\fR in its
+definition in UTF\-8 format. (This was true previously for all occurrences
+of \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR that did not use a custom translator, but now it's
+always true.)
+.IP \(bu 4
+Perl_magic_setmglob now knows about globs, fixing RT #71254.
+.IP \(bu 4
+\&\f(CW\*(C`SVt_RV\*(C'\fR no longer exists. RVs are now stored in IVs.
+.IP \(bu 4
+\&\f(CWPerl_vcroak()\fR now accepts a null first argument. In addition, a full
+audit was made of the "not NULL" compiler annotations, and those for
+several other internal functions were corrected.
+.IP \(bu 4
+New macros \f(CW\*(C`dSAVEDERRNO\*(C'\fR, \f(CW\*(C`dSAVE_ERRNO\*(C'\fR, \f(CW\*(C`SAVE_ERRNO\*(C'\fR, \f(CW\*(C`RESTORE_ERRNO\*(C'\fR
+have been added to formalise the temporary saving of the \f(CW\*(C`errno\*(C'\fR
+variable.
+.IP \(bu 4
+The function \f(CW\*(C`Perl_sv_insert_flags\*(C'\fR has been added to augment
+\&\f(CW\*(C`Perl_sv_insert\*(C'\fR.
+.IP \(bu 4
+The function \f(CWPerl_newSV_type(type)\fR has been added, equivalent to
+\&\f(CWPerl_newSV()\fR followed by \f(CWPerl_sv_upgrade(type)\fR.
+.IP \(bu 4
+The function \f(CWPerl_newSVpvn_flags()\fR has been added, equivalent to
+\&\f(CWPerl_newSVpvn()\fR and then performing the action relevant to the flag.
+.Sp
+Two flag bits are currently supported.
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`SVf_UTF8\*(C'\fR will call \f(CWSvUTF8_on()\fR for you. (Note that this does
+not convert a sequence of ISO 8859\-1 characters to UTF\-8). A wrapper,
+\&\f(CWnewSVpvn_utf8()\fR is available for this.
+.IP \(bu 4
+\&\f(CW\*(C`SVs_TEMP\*(C'\fR now calls \f(CWPerl_sv_2mortal()\fR on the new SV.
+.RE
+.RS 4
+.Sp
+There is also a wrapper that takes constant strings, \f(CWnewSVpvs_flags()\fR.
+.RE
+.IP \(bu 4
+The function \f(CW\*(C`Perl_croak_xs_usage\*(C'\fR has been added as a wrapper to
+\&\f(CW\*(C`Perl_croak\*(C'\fR.
+.IP \(bu 4
+Perl now exports the functions \f(CW\*(C`PerlIO_find_layer\*(C'\fR and \f(CW\*(C`PerlIO_list_alloc\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`PL_na\*(C'\fR has been exterminated from the core code, replaced by local
+STRLEN temporaries, or \f(CW*_nolen()\fR calls. Either approach is faster than
+\&\f(CW\*(C`PL_na\*(C'\fR, which is a pointer dereference into the interpreter structure
+under ithreads, and a global variable otherwise.
+.IP \(bu 4
+\&\f(CWPerl_mg_free()\fR used to leave freed memory accessible via \f(CWSvMAGIC()\fR
+on the scalar. It now updates the linked list to remove each piece of
+magic as it is freed.
+.IP \(bu 4
+Under ithreads, the regex in \f(CW\*(C`PL_reg_curpm\*(C'\fR is now reference
+counted. This eliminates a lot of hackish workarounds to cope with it
+not being reference counted.
+.IP \(bu 4
+\&\f(CWPerl_mg_magical()\fR would sometimes incorrectly turn on \f(CWSvRMAGICAL()\fR.
+This has been fixed.
+.IP \(bu 4
+The \fIpublic\fR IV and NV flags are now not set if the string value has
+trailing "garbage". This behaviour is consistent with not setting the
+public IV or NV flags if the value is out of range for the type.
+.IP \(bu 4
+Uses of \f(CW\*(C`Nullav\*(C'\fR, \f(CW\*(C`Nullcv\*(C'\fR, \f(CW\*(C`Nullhv\*(C'\fR, \f(CW\*(C`Nullop\*(C'\fR, \f(CW\*(C`Nullsv\*(C'\fR etc have
+been replaced by \f(CW\*(C`NULL\*(C'\fR in the core code, and non-dual-life modules,
+as \f(CW\*(C`NULL\*(C'\fR is clearer to those unfamiliar with the core code.
+.IP \(bu 4
+A macro \f(CWMUTABLE_PTR(p)\fR has been added, which on (non-pedantic) gcc will
+not cast away \f(CW\*(C`const\*(C'\fR, returning a \f(CW\*(C`void *\*(C'\fR. Macros \f(CWMUTABLE_SV(av)\fR,
+\&\f(CWMUTABLE_SV(cv)\fR etc build on this, casting to \f(CW\*(C`AV *\*(C'\fR etc without
+casting away \f(CW\*(C`const\*(C'\fR. This allows proper compile-time auditing of
+\&\f(CW\*(C`const\*(C'\fR correctness in the core, and helped picked up some errors
+(now fixed).
+.IP \(bu 4
+Macros \f(CWmPUSHs()\fR and \f(CWmXPUSHs()\fR have been added, for pushing SVs on the
+stack and mortalizing them.
+.IP \(bu 4
+Use of the private structure \f(CW\*(C`mro_meta\*(C'\fR has changed slightly. Nothing
+outside the core should be accessing this directly anyway.
+.IP \(bu 4
+A new tool, \fIPorting/expand\-macro.pl\fR has been added, that allows you
+to view how a C preprocessor macro would be expanded when compiled.
+This is handy when trying to decode the macro hell that is the perl
+guts.
+.SH Testing
+.IX Header "Testing"
+.SS "Testing improvements"
+.IX Subsection "Testing improvements"
+.IP "Parallel tests" 4
+.IX Item "Parallel tests"
+The core distribution can now run its regression tests in parallel on
+Unix-like platforms. Instead of running \f(CW\*(C`make test\*(C'\fR, set \f(CW\*(C`TEST_JOBS\*(C'\fR in
+your environment to the number of tests to run in parallel, and run
+\&\f(CW\*(C`make test_harness\*(C'\fR. On a Bourne-like shell, this can be done as
+.Sp
+.Vb 1
+\&    TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
+.Ve
+.Sp
+An environment variable is used, rather than parallel make itself, because
+TAP::Harness needs to be able to schedule individual non-conflicting test
+scripts itself, and there is no standard interface to \f(CW\*(C`make\*(C'\fR utilities to
+interact with their job schedulers.
+.Sp
+Note that currently some test scripts may fail when run in parallel (most
+notably \f(CW\*(C`ext/IO/t/io_dir.t\*(C'\fR). If necessary run just the failing scripts
+again sequentially and see if the failures go away.
+.IP "Test harness flexibility" 4
+.IX Item "Test harness flexibility"
+It's now possible to override \f(CW\*(C`PERL5OPT\*(C'\fR and friends in \fIt/TEST\fR
+.IP "Test watchdog" 4
+.IX Item "Test watchdog"
+Several tests that have the potential to hang forever if they fail now
+incorporate a "watchdog" functionality that will kill them after a timeout,
+which helps ensure that \f(CW\*(C`make test\*(C'\fR and \f(CW\*(C`make test_harness\*(C'\fR run to
+completion automatically.
+.SS "New Tests"
+.IX Subsection "New Tests"
+Perl's developers have added a number of new tests to the core.
+In addition to the items listed below, many modules updated from CPAN
+incorporate new tests.
+.IP \(bu 4
+Significant cleanups to core tests to ensure that language and
+interpreter features are not used before they're tested.
+.IP \(bu 4
+\&\f(CW\*(C`make test_porting\*(C'\fR now runs a number of important pre-commit checks
+which might be of use to anyone working on the Perl core.
+.IP \(bu 4
+\&\fIt/porting/podcheck.t\fR automatically checks the well-formedness of
+POD found in all .pl, .pm and .pod files in the \fIMANIFEST\fR, other than in
+dual-lifed modules which are primarily maintained outside the Perl core.
+.IP \(bu 4
+\&\fIt/porting/manifest.t\fR now tests that all files listed in MANIFEST
+are present.
+.IP \(bu 4
+\&\fIt/op/while_readdir.t\fR tests that a bare readdir in while loop sets \f(CW$_\fR.
+.IP \(bu 4
+\&\fIt/comp/retainedlines.t\fR checks that the debugger can retain source
+lines from \f(CW\*(C`eval\*(C'\fR.
+.IP \(bu 4
+\&\fIt/io/perlio_fail.t\fR checks that bad layers fail.
+.IP \(bu 4
+\&\fIt/io/perlio_leaks.t\fR checks that PerlIO layers are not leaking.
+.IP \(bu 4
+\&\fIt/io/perlio_open.t\fR checks that certain special forms of open work.
+.IP \(bu 4
+\&\fIt/io/perlio.t\fR includes general PerlIO tests.
+.IP \(bu 4
+\&\fIt/io/pvbm.t\fR checks that there is no unexpected interaction between
+the internal types \f(CW\*(C`PVBM\*(C'\fR and \f(CW\*(C`PVGV\*(C'\fR.
+.IP \(bu 4
+\&\fIt/mro/package_aliases.t\fR checks that mro works properly in the presence
+of aliased packages.
+.IP \(bu 4
+\&\fIt/op/dbm.t\fR tests \f(CW\*(C`dbmopen\*(C'\fR and \f(CW\*(C`dbmclose\*(C'\fR.
+.IP \(bu 4
+\&\fIt/op/index_thr.t\fR tests the interaction of \f(CW\*(C`index\*(C'\fR and threads.
+.IP \(bu 4
+\&\fIt/op/pat_thr.t\fR tests the interaction of esoteric patterns and threads.
+.IP \(bu 4
+\&\fIt/op/qr_gc.t\fR tests that \f(CW\*(C`qr\*(C'\fR doesn't leak.
+.IP \(bu 4
+\&\fIt/op/reg_email_thr.t\fR tests the interaction of regex recursion and threads.
+.IP \(bu 4
+\&\fIt/op/regexp_qr_embed_thr.t\fR tests the interaction of patterns with
+embedded \f(CW\*(C`qr//\*(C'\fR and threads.
+.IP \(bu 4
+\&\fIt/op/regexp_unicode_prop.t\fR tests Unicode properties in regular
+expressions.
+.IP \(bu 4
+\&\fIt/op/regexp_unicode_prop_thr.t\fR tests the interaction of Unicode
+properties and threads.
+.IP \(bu 4
+\&\fIt/op/reg_nc_tie.t\fR tests the tied methods of \f(CW\*(C`Tie::Hash::NamedCapture\*(C'\fR.
+.IP \(bu 4
+\&\fIt/op/reg_posixcc.t\fR checks that POSIX character classes behave
+consistently.
+.IP \(bu 4
+\&\fIt/op/re.t\fR checks that exportable \f(CW\*(C`re\*(C'\fR functions in \fIuniversal.c\fR work.
+.IP \(bu 4
+\&\fIt/op/setpgrpstack.t\fR checks that \f(CW\*(C`setpgrp\*(C'\fR works.
+.IP \(bu 4
+\&\fIt/op/substr_thr.t\fR tests the interaction of \f(CW\*(C`substr\*(C'\fR and threads.
+.IP \(bu 4
+\&\fIt/op/upgrade.t\fR checks that upgrading and assigning scalars works.
+.IP \(bu 4
+\&\fIt/uni/lex_utf8.t\fR checks that Unicode in the lexer works.
+.IP \(bu 4
+\&\fIt/uni/tie.t\fR checks that Unicode and \f(CW\*(C`tie\*(C'\fR work.
+.IP \(bu 4
+\&\fIt/comp/final_line_num.t\fR tests whether line numbers are correct at EOF
+.IP \(bu 4
+\&\fIt/comp/form_scope.t\fR tests format scoping.
+.IP \(bu 4
+\&\fIt/comp/line_debug.t\fR tests whether \f(CW\*(C`@{"_<$file"}\*(C'\fR works.
+.IP \(bu 4
+\&\fIt/op/filetest_t.t\fR tests if \-t file test works.
+.IP \(bu 4
+\&\fIt/op/qr.t\fR tests \f(CW\*(C`qr\*(C'\fR.
+.IP \(bu 4
+\&\fIt/op/utf8cache.t\fR tests malfunctions of the utf8 cache.
+.IP \(bu 4
+\&\fIt/re/uniprops.t\fR test unicodes \f(CW\*(C`\ep{}\*(C'\fR regex constructs.
+.IP \(bu 4
+\&\fIt/op/filehandle.t\fR tests some suitably portable filetest operators
+to check that they work as expected, particularly in the light of some
+internal changes made in how filehandles are blessed.
+.IP \(bu 4
+\&\fIt/op/time_loop.t\fR tests that unix times greater than \f(CW\*(C`2**63\*(C'\fR, which
+can now be handed to \f(CW\*(C`gmtime\*(C'\fR and \f(CW\*(C`localtime\*(C'\fR, do not cause an internal
+overflow or an excessively long loop.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+.IP \(bu 4
+SV allocation tracing has been added to the diagnostics enabled by \f(CW\*(C`\-Dm\*(C'\fR.
+The tracing can alternatively output via the \f(CW\*(C`PERL_MEM_LOG\*(C'\fR mechanism, if
+that was enabled when the \fIperl\fR binary was compiled.
+.IP \(bu 4
+Smartmatch resolution tracing has been added as a new diagnostic. Use
+\&\f(CW\*(C`\-DM\*(C'\fR to enable it.
+.IP \(bu 4
+A new debugging flag \f(CW\*(C`\-DB\*(C'\fR now dumps subroutine definitions, leaving
+\&\f(CW\*(C`\-Dx\*(C'\fR for its original purpose of dumping syntax trees.
+.IP \(bu 4
+Perl 5.12 provides a number of new diagnostic messages to help you write
+better code.  See perldiag for details of these new messages.
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`Bad plugin affecting keyword \*(Aq%s\*(Aq\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`gmtime(%.0f) too large\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Lexing code attempted to stuff non\-Latin\-1 character into Latin\-1 input\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Lexing code internal error (%s)\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`localtime(%.0f) too large\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Overloaded dereference did not return a reference\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Overloaded qr did not return a REGEXP\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Perl_pmflag() is deprecated, and will be removed from the XS API\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`lvalue attribute ignored after the subroutine has been defined\*(C'\fR
+.Sp
+This new warning is issued when one attempts to mark a subroutine as
+lvalue after it has been defined.
+.IP \(bu 4
+Perl now warns you if \f(CW\*(C`++\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR are unable to change the value
+because it's beyond the limit of representation.
+.Sp
+This uses a new warnings category: "imprecision".
+.IP \(bu 4
+\&\f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, and \f(CW\*(C`ucfirst\*(C'\fR warn when passed undef.
+.IP \(bu 4
+\&\f(CW\*(C`Show constant in "Useless use of a constant in void context"\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Prototype after \*(Aq%s\*(Aq\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`panic: sv_chop %s\*(C'\fR
+.Sp
+This new fatal error occurs when the C routine \f(CWPerl_sv_chop()\fR was
+passed a position that is not within the scalar's string buffer. This
+could be caused by buggy XS code, and at this point recovery is not
+possible.
+.IP \(bu 4
+The fatal error \f(CW\*(C`Malformed UTF\-8 returned by \eN\*(C'\fR is now produced if the
+\&\f(CW\*(C`charnames\*(C'\fR handler returns malformed UTF\-8.
+.IP \(bu 4
+If an unresolved named character or sequence was encountered when
+compiling a regex pattern then the fatal error \f(CW\*(C`\eN{NAME} must be resolved
+by the lexer\*(C'\fR is now produced. This can happen, for example, when using a
+single-quotish context like \f(CW\*(C`$re = \*(Aq\eN{SPACE}\*(Aq; /$re/;\*(C'\fR. See perldiag
+for more examples of how the lexer can get bypassed.
+.IP \(bu 4
+\&\f(CW\*(C`Invalid hexadecimal number in \eN{U+...}\*(C'\fR is a new fatal error
+triggered when the character constant represented by \f(CW\*(C`...\*(C'\fR is not a
+valid hexadecimal number.
+.IP \(bu 4
+The new meaning of \f(CW\*(C`\eN\*(C'\fR as \f(CW\*(C`[^\en]\*(C'\fR is not valid in a bracketed character
+class, just like \f(CW\*(C`.\*(C'\fR in a character class loses its special meaning,
+and will cause the fatal error \f(CW\*(C`\eN in a character class must be a named
+character: \eN{...}\*(C'\fR.
+.IP \(bu 4
+The rules on what is legal for the \f(CW\*(C`...\*(C'\fR in \f(CW\*(C`\eN{...}\*(C'\fR have been
+tightened up so that unless the \f(CW\*(C`...\*(C'\fR begins with an alphabetic
+character and continues with a combination of alphanumerics, dashes,
+spaces, parentheses or colons then the warning \f(CW\*(C`Deprecated character(s)
+in \eN{...} starting at \*(Aq%s\*(Aq\*(C'\fR is now issued.
+.IP \(bu 4
+The warning \f(CW\*(C`Using just the first characters returned by \eN{}\*(C'\fR will
+be issued if the \f(CW\*(C`charnames\*(C'\fR handler returns a sequence of characters
+which exceeds the limit of the number of characters that can be used. The
+message will indicate which characters were used and which were discarded.
+.RE
+.RS 4
+.RE
+.SS "Changed Diagnostics"
+.IX Subsection "Changed Diagnostics"
+A number of existing diagnostic messages have been improved or corrected:
+.IP \(bu 4
+A new warning category \f(CW\*(C`illegalproto\*(C'\fR allows finer-grained control of
+warnings around function prototypes.
+.Sp
+The two warnings:
+.RS 4
+.ie n .IP """Illegal character in prototype for %s : %s""" 4
+.el .IP "\f(CWIllegal character in prototype for %s : %s\fR" 4
+.IX Item "Illegal character in prototype for %s : %s"
+.PD 0
+.ie n .IP """Prototype after \*(Aq%c\*(Aq for %s : %s""" 4
+.el .IP "\f(CWPrototype after \*(Aq%c\*(Aq for %s : %s\fR" 4
+.IX Item "Prototype after %c for %s : %s"
+.RE
+.RS 4
+.PD
+.Sp
+have been moved from the \f(CW\*(C`syntax\*(C'\fR top-level warnings category into a new
+first-level category, \f(CW\*(C`illegalproto\*(C'\fR. These two warnings are currently
+the only ones emitted during parsing of an invalid/illegal prototype,
+so one can now use
+.Sp
+.Vb 1
+\&  no warnings \*(Aqillegalproto\*(Aq;
+.Ve
+.Sp
+to suppress only those, but not other syntax-related warnings. Warnings
+where prototypes are changed, ignored, or not met are still in the
+\&\f(CW\*(C`prototype\*(C'\fR category as before.
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Deep recursion on subroutine "%s"\*(C'\fR
+.Sp
+It is now possible to change the depth threshold for this warning from the
+default of 100, by recompiling the \fIperl\fR binary, setting the C
+pre-processor macro \f(CW\*(C`PERL_SUB_DEPTH_WARN\*(C'\fR to the desired value.
+.IP \(bu 4
+\&\f(CW\*(C`Illegal character in prototype\*(C'\fR warning is now more precise
+when reporting illegal characters after _
+.IP \(bu 4
+mro merging error messages are now very similar to those produced by
+Algorithm::C3.
+.IP \(bu 4
+Amelioration of the error message "Unrecognized character \f(CW%s\fR in column \f(CW%d\fR"
+.Sp
+Changes the error message to "Unrecognized character \f(CW%s\fR; marked by <\-\-
+HERE after \f(CW%s\fR<\-\- HERE near column \f(CW%d\fR". This should make it a little
+simpler to spot and correct the suspicious character.
+.IP \(bu 4
+Perl now explicitly points to \f(CW$.\fR when it causes an uninitialized
+warning for ranges in scalar context.
+.IP \(bu 4
+\&\f(CW\*(C`split\*(C'\fR now warns when called in void context.
+.IP \(bu 4
+\&\f(CW\*(C`printf\*(C'\fR\-style functions called with too few arguments will now issue the
+warning \f(CW"Missing argument in %s"\fR [perl #71000]
+.IP \(bu 4
+Perl now properly returns a syntax error instead of segfaulting
+if \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, or \f(CW\*(C`values\*(C'\fR is used without an argument.
+.IP \(bu 4
+\&\f(CWtell()\fR now fails properly if called without an argument and when no
+previous file was read.
+.Sp
+\&\f(CWtell()\fR now returns \f(CW\-1\fR, and sets errno to \f(CW\*(C`EBADF\*(C'\fR, thus restoring
+the 5.8.x behaviour.
+.IP \(bu 4
+\&\f(CW\*(C`overload\*(C'\fR no longer implicitly unsets fallback on repeated 'use
+overload' lines.
+.IP \(bu 4
+\&\fBPOSIX::strftime()\fR can now handle Unicode characters in the format string.
+.IP \(bu 4
+The \f(CW\*(C`syntax\*(C'\fR category was removed from 5 warnings that should only be in
+\&\f(CW\*(C`deprecated\*(C'\fR.
+.IP \(bu 4
+Three fatal \f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR error messages have been normalized to
+\&\f(CW\*(C`panic: %s\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Unicode character is illegal\*(C'\fR has been rephrased to be more accurate
+.Sp
+It now reads \f(CW\*(C`Unicode non\-character is illegal in interchange\*(C'\fR and the
+perldiag documentation has been expanded a bit.
+.IP \(bu 4
+Currently, all but the first of the several characters that the
+\&\f(CW\*(C`charnames\*(C'\fR handler may return are discarded when used in a regular
+expression pattern bracketed character class. If this happens then the
+warning \f(CW\*(C`Using just the first character returned by \eN{} in character
+class\*(C'\fR will be issued.
+.IP \(bu 4
+The warning \f(CW\*(C`Missing right brace on \eN{} or unescaped left brace after
+\&\eN.  Assuming the latter\*(C'\fR will be issued if Perl encounters a \f(CW\*(C`\eN{\*(C'\fR
+but doesn't find a matching \f(CW\*(C`}\*(C'\fR. In this case Perl doesn't know if it
+was mistakenly omitted, or if "match non-newline" followed by "match
+a \f(CW\*(C`{\*(C'\fR" was desired.  It assumes the latter because that is actually a
+valid interpretation as written, unlike the other case.  If you meant
+the former, you need to add the matching right brace.  If you did mean
+the latter, you can silence this warning by writing instead \f(CW\*(C`\eN\e{\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`gmtime\*(C'\fR and \f(CW\*(C`localtime\*(C'\fR called with numbers smaller than they can
+reliably handle will now issue the warnings \f(CW\*(C`gmtime(%.0f) too small\*(C'\fR
+and \f(CW\*(C`localtime(%.0f) too small\*(C'\fR.
+.PP
+The following diagnostic messages have been removed:
+.IP \(bu 4
+\&\f(CW\*(C`Runaway format\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`Can\*(Aqt locate package %s for the parents of %s\*(C'\fR
+.Sp
+In general this warning it only got produced in
+conjunction with other warnings, and removing it allowed an ISA lookup
+optimisation to be added.
+.IP \(bu 4
+\&\f(CW\*(C`v\-string in use/require is non\-portable\*(C'\fR
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.IP \(bu 4
+\&\fIh2ph\fR now looks in \f(CW\*(C`include\-fixed\*(C'\fR too, which is a recent addition
+to gcc's search path.
+.IP \(bu 4
+\&\fIh2xs\fR no longer incorrectly treats enum values like macros.
+It also now handles C++ style comments (\f(CW\*(C`//\*(C'\fR) properly in enums.
+.IP \(bu 4
+\&\fIperl5db.pl\fR now supports \f(CW\*(C`LVALUE\*(C'\fR subroutines.  Additionally, the
+debugger now correctly handles proxy constant subroutines, and
+subroutine stubs.
+.IP \(bu 4
+\&\fIperlbug\fR now uses \f(CW%Module::CoreList::bug_tracker\fR to print out
+upstream bug tracker URLs.  If a user identifies a particular module
+as the topic of their bug report and we're able to divine the URL for
+its upstream bug tracker, perlbug now provide a message to the user
+explaining that the core copies the CPAN version directly, and provide
+the URL for reporting the bug directly to the upstream author.
+.Sp
+\&\fIperlbug\fR no longer reports "Message sent" when it hasn't actually sent
+the message
+.IP \(bu 4
+\&\fIperlthanks\fR is a new utility for sending non-bug-reports to the
+authors and maintainers of Perl. Getting nothing but bug reports can
+become a bit demoralising. If Perl 5.12 works well for you, please try
+out \fIperlthanks\fR. It will make the developers smile.
+.IP \(bu 4
+Perl's developers have fixed bugs in \fIa2p\fR having to do with the
+\&\f(CWmatch()\fR operator in list context.  Additionally, \fIa2p\fR no longer
+generates code that uses the \f(CW$[\fR variable.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+U+0FFFF is now a legal character in regular expressions.
+.IP \(bu 4
+pp_qr now always returns a new regexp SV. Resolves RT #69852.
+.Sp
+Instead of returning a(nother) reference to the (pre-compiled) regexp
+in the optree, use \fBreg_temp_copy()\fR to create a copy of it, and return a
+reference to that. This resolves issues about Regexp::DESTROY not being
+called in a timely fashion (the original bug tracked by RT #69852), as
+well as bugs related to blessing regexps, and of assigning to regexps,
+as described in correspondence added to the ticket.
+.Sp
+It transpires that we also need to undo the \fBSvPVX()\fR sharing when ithreads
+cloning a Regexp SV, because mother_re is set to NULL, instead of a
+cloned copy of the mother_re. This change might fix bugs with regexps
+and threads in certain other situations, but as yet neither tests nor
+bug reports have indicated any problems, so it might not actually be an
+edge case that it's possible to reach.
+.IP \(bu 4
+Several compilation errors and segfaults when perl was built with \f(CW\*(C`\-Dmad\*(C'\fR
+were fixed.
+.IP \(bu 4
+Fixes for lexer API changes in 5.11.2 which broke NYTProf's savesrc option.
+.IP \(bu 4
+\&\f(CW\*(C`\-t\*(C'\fR should only return TRUE for file handles connected to a TTY
+.Sp
+The Microsoft C version of \f(CWisatty()\fR returns TRUE for all character mode
+devices, including the \fI/dev/null\fR\-style "nul" device and printers like
+"lpt1".
+.IP \(bu 4
+Fixed a regression caused by commit fafafbaf which caused a panic during
+parameter passing [perl #70171]
+.IP \(bu 4
+On systems which in-place edits without backup files, \-i'*' now works as
+the documentation says it does [perl #70802]
+.IP \(bu 4
+Saving and restoring magic flags no longer loses readonly flag.
+.IP \(bu 4
+The malformed syntax \f(CW\*(C`grep EXPR LIST\*(C'\fR (note the missing comma) no longer
+causes abrupt and total failure.
+.IP \(bu 4
+Regular expressions compiled with \f(CW\*(C`qr{}\*(C'\fR literals properly set \f(CW\*(C`$\*(Aq\*(C'\fR when
+matching again.
+.IP \(bu 4
+Using named subroutines with \f(CW\*(C`sort\*(C'\fR should no longer lead to bus errors
+[perl #71076]
+.IP \(bu 4
+Numerous bugfixes catch small issues caused by the recently-added Lexer API.
+.IP \(bu 4
+Smart match against \f(CW@_\fR sometimes gave false negatives. [perl #71078]
+.IP \(bu 4
+\&\f(CW$@\fR may now be assigned a read-only value (without error or busting
+the stack).
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR called recursively from within an active comparison subroutine no
+longer causes a bus error if run multiple times. [perl #71076]
+.IP \(bu 4
+Tie::Hash::NamedCapture::* will not abort if passed bad input (RT #71828)
+.IP \(bu 4
+\&\f(CW@_\fR and \f(CW$_\fR no longer leak under threads (RT #34342 and #41138, also
+#70602, #70974)
+.IP \(bu 4
+\&\f(CW\*(C`\-I\*(C'\fR on shebang line now adds directories in front of \f(CW@INC\fR
+as documented, and as does \f(CW\*(C`\-I\*(C'\fR when specified on the command-line.
+.IP \(bu 4
+\&\f(CW\*(C`kill\*(C'\fR is now fatal when called on non-numeric process identifiers.
+Previously, an \f(CW\*(C`undef\*(C'\fR process identifier would be interpreted as a
+request to kill process 0, which would terminate the current process
+group on POSIX systems. Since process identifiers are always integers,
+killing a non-numeric process is now fatal.
+.IP \(bu 4
+5.10.0 inadvertently disabled an optimisation, which caused a measurable
+performance drop in list assignment, such as is often used to assign
+function parameters from \f(CW@_\fR. The optimisation has been re-instated, and
+the performance regression fixed. (This fix is also present in 5.10.1)
+.IP \(bu 4
+Fixed memory leak on \f(CW\*(C`while (1) { map 1, 1 }\*(C'\fR [RT #53038].
+.IP \(bu 4
+Some potential coredumps in PerlIO fixed [RT #57322,54828].
+.IP \(bu 4
+The debugger now works with lvalue subroutines.
+.IP \(bu 4
+The debugger's \f(CW\*(C`m\*(C'\fR command was broken on modules that defined constants
+[RT #61222].
+.IP \(bu 4
+\&\f(CW\*(C`crypt\*(C'\fR and string complement could return tainted values for untainted
+arguments [RT #59998].
+.IP \(bu 4
+The \f(CW\*(C`\-i\*(C'\fR\fI.suffix\fR command-line switch now recreates the file using
+restricted permissions, before changing its mode to match the original
+file. This eliminates a potential race condition [RT #60904].
+.IP \(bu 4
+On some Unix systems, the value in \f(CW$?\fR would not have the top bit set
+(\f(CW\*(C`$? & 128\*(C'\fR) even if the child core dumped.
+.IP \(bu 4
+Under some circumstances, \f(CW$^R\fR could incorrectly become undefined
+[RT #57042].
+.IP \(bu 4
+In the XS API, various hash functions, when passed a pre-computed hash where
+the key is UTF\-8, might result in an incorrect lookup.
+.IP \(bu 4
+XS code including \fIXSUB.h\fR before \fIperl.h\fR gave a compile-time error
+[RT #57176].
+.IP \(bu 4
+\&\f(CW\*(C`$object\->isa(\*(AqFoo\*(Aq)\*(C'\fR would report false if the package \f(CW\*(C`Foo\*(C'\fR
+didn't exist, even if the object's \f(CW@ISA\fR contained \f(CW\*(C`Foo\*(C'\fR.
+.IP \(bu 4
+Various bugs in the new-to 5.10.0 mro code, triggered by manipulating
+\&\f(CW@ISA\fR, have been found and fixed.
+.IP \(bu 4
+Bitwise operations on references could crash the interpreter, e.g.
+\&\f(CW\*(C`$x=\e$y; $x |= "foo"\*(C'\fR [RT #54956].
+.IP \(bu 4
+Patterns including alternation might be sensitive to the internal UTF\-8
+representation, e.g.
+.Sp
+.Vb 3
+\&    my $byte = chr(192);
+\&    my $utf8 = chr(192); utf8::upgrade($utf8);
+\&    $utf8 =~ /$byte|X}/i;       # failed in 5.10.0
+.Ve
+.IP \(bu 4
+Within UTF8\-encoded Perl source files (i.e. where \f(CW\*(C`use utf8\*(C'\fR is in
+effect), double-quoted literal strings could be corrupted where a \f(CW\*(C`\exNN\*(C'\fR,
+\&\f(CW\*(C`\e0NNN\*(C'\fR or \f(CW\*(C`\eN{}\*(C'\fR is followed by a literal character with ordinal value
+greater than 255 [RT #59908].
+.IP \(bu 4
+\&\f(CW\*(C`B::Deparse\*(C'\fR failed to correctly deparse various constructs:
+\&\f(CW\*(C`readpipe STRING\*(C'\fR [RT #62428], \f(CWCORE::require(STRING)\fR [RT #62488],
+\&\f(CW\*(C`sub foo(_)\*(C'\fR [RT #62484].
+.IP \(bu 4
+Using \f(CW\*(C`setpgrp\*(C'\fR with no arguments could corrupt the perl stack.
+.IP \(bu 4
+The block form of \f(CW\*(C`eval\*(C'\fR is now specifically trappable by \f(CW\*(C`Safe\*(C'\fR and
+\&\f(CW\*(C`ops\*(C'\fR. Previously it was erroneously treated like string \f(CW\*(C`eval\*(C'\fR.
+.IP \(bu 4
+In 5.10.0, the two characters \f(CW\*(C`[~\*(C'\fR were sometimes parsed as the smart
+match operator (\f(CW\*(C`~~\*(C'\fR) [RT #63854].
+.IP \(bu 4
+In 5.10.0, the \f(CW\*(C`*\*(C'\fR quantifier in patterns was sometimes treated as
+\&\f(CW\*(C`{0,32767}\*(C'\fR [RT #60034, #60464]. For example, this match would fail:
+.Sp
+.Vb 1
+\&    ("ab" x 32768) =~ /^(ab)*$/
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`shmget\*(C'\fR was limited to a 32 bit segment size on a 64 bit OS [RT #63924].
+.IP \(bu 4
+Using \f(CW\*(C`next\*(C'\fR or \f(CW\*(C`last\*(C'\fR to exit a \f(CW\*(C`given\*(C'\fR block no longer produces a
+spurious warning like the following:
+.Sp
+.Vb 1
+\&    Exiting given via last at foo.pl line 123
+.Ve
+.IP \(bu 4
+Assigning a format to a glob could corrupt the format; e.g.:
+.Sp
+.Vb 1
+\&     *bar=*foo{FORMAT}; # foo format now bad
+.Ve
+.IP \(bu 4
+Attempting to coerce a typeglob to a string or number could cause an
+assertion failure. The correct error message is now generated,
+\&\f(CW\*(C`Can\*(Aqt coerce GLOB to \fR\f(CI$type\fR\f(CW\*(C'\fR.
+.IP \(bu 4
+Under \f(CW\*(C`use filetest \*(Aqaccess\*(Aq\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR was using the wrong access
+mode. This has been fixed [RT #49003].
+.IP \(bu 4
+\&\f(CW\*(C`length\*(C'\fR on a tied scalar that returned a Unicode value would not be
+correct the first time. This has been fixed.
+.IP \(bu 4
+Using an array \f(CW\*(C`tie\*(C'\fR inside in array \f(CW\*(C`tie\*(C'\fR could SEGV. This has been
+fixed. [RT #51636]
+.IP \(bu 4
+A race condition inside \f(CWPerlIOStdio_close()\fR has been identified and
+fixed. This used to cause various threading issues, including SEGVs.
+.IP \(bu 4
+In \f(CW\*(C`unpack\*(C'\fR, the use of \f(CW\*(C`()\*(C'\fR groups in scalar context was internally
+placing a list on the interpreter's stack, which manifested in various
+ways, including SEGVs. This is now fixed [RT #50256].
+.IP \(bu 4
+Magic was called twice in \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`\e&$x\*(C'\fR, \f(CW\*(C`tie $x, $m\*(C'\fR and \f(CW\*(C`chop\*(C'\fR.
+These have all been fixed.
+.IP \(bu 4
+A 5.10.0 optimisation to clear the temporary stack within the implicit
+loop of \f(CW\*(C`s///ge\*(C'\fR has been reverted, as it turned out to be the cause of
+obscure bugs in seemingly unrelated parts of the interpreter [commit
+ef0d4e17921ee3de].
+.IP \(bu 4
+The line numbers for warnings inside \f(CW\*(C`elsif\*(C'\fR are now correct.
+.IP \(bu 4
+The \f(CW\*(C`..\*(C'\fR operator now works correctly with ranges whose ends are at or
+close to the values of the smallest and largest integers.
+.IP \(bu 4
+\&\f(CW\*(C`binmode STDIN, \*(Aq:raw\*(Aq\*(C'\fR could lead to segmentation faults on some platforms.
+This has been fixed [RT #54828].
+.IP \(bu 4
+An off-by-one error meant that \f(CW\*(C`index $str, ...\*(C'\fR was effectively being
+executed as \f(CW\*(C`index "$str\e0", ...\*(C'\fR. This has been fixed [RT #53746].
+.IP \(bu 4
+Various leaks associated with named captures in regexes have been fixed
+[RT #57024].
+.IP \(bu 4
+A weak reference to a hash would leak. This was affecting \f(CW\*(C`DBI\*(C'\fR
+[RT #56908].
+.IP \(bu 4
+Using (?|) in a regex could cause a segfault [RT #59734].
+.IP \(bu 4
+Use of a UTF\-8 \f(CW\*(C`tr//\*(C'\fR within a closure could cause a segfault [RT #61520].
+.IP \(bu 4
+Calling \f(CWPerl_sv_chop()\fR or otherwise upgrading an SV could result in an
+unaligned 64\-bit access on the SPARC architecture [RT #60574].
+.IP \(bu 4
+In the 5.10.0 release, \f(CW\*(C`inc_version_list\*(C'\fR would incorrectly list
+\&\f(CW\*(C`5.10.*\*(C'\fR after \f(CW\*(C`5.8.*\*(C'\fR; this affected the \f(CW@INC\fR search order
+[RT #67628].
+.IP \(bu 4
+In 5.10.0, \f(CW\*(C`pack "a*", $tainted_value\*(C'\fR returned a non-tainted value
+[RT #52552].
+.IP \(bu 4
+In 5.10.0, \f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR could produce the fatal error
+\&\f(CW\*(C`panic: utf8_mg_pos_cache_update\*(C'\fR when printing UTF\-8 strings
+[RT #62666].
+.IP \(bu 4
+In the 5.10.0 release, a dynamically created \f(CW\*(C`AUTOLOAD\*(C'\fR method might be
+missed (method cache issue) [RT #60220,60232].
+.IP \(bu 4
+In the 5.10.0 release, a combination of \f(CW\*(C`use feature\*(C'\fR and \f(CW\*(C`//ee\*(C'\fR could
+cause a memory leak [RT #63110].
+.IP \(bu 4
+\&\f(CW\*(C`\-C\*(C'\fR on the shebang (\f(CW\*(C`#!\*(C'\fR) line is once more permitted if it is also
+specified on the command line. \f(CW\*(C`\-C\*(C'\fR on the shebang line used to be a
+silent no-op \fIif\fR it was not also on the command line, so perl 5.10.0
+disallowed it, which broke some scripts. Now perl checks whether it is
+also on the command line and only dies if it is not [RT #67880].
+.IP \(bu 4
+In 5.10.0, certain types of re-entrant regular expression could crash,
+or cause the following assertion failure [RT #60508]:
+.Sp
+.Vb 1
+\&    Assertion rx\->sublen >= (s \- rx\->subbeg) + i failed
+.Ve
+.IP \(bu 4
+Perl now includes previously missing files from the Unicode Character
+Database.
+.IP \(bu 4
+Perl now honors \f(CW\*(C`TMPDIR\*(C'\fR when opening an anonymous temporary file.
+.SH "Platform Specific Changes"
+.IX Header "Platform Specific Changes"
+Perl is incredibly portable. In general, if a platform has a C compiler,
+someone has ported Perl to it (or will soon).  We're happy to announce
+that Perl 5.12 includes support for several new platforms.  At the same
+time, it's time to bid farewell to some (very) old friends.
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+.IP Haiku 4
+.IX Item "Haiku"
+Perl's developers have merged patches from Haiku's maintainers. Perl
+should now build on Haiku.
+.IP "MirOS BSD" 4
+.IX Item "MirOS BSD"
+Perl should now build on MirOS BSD.
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP Domain/OS 4
+.IX Item "Domain/OS"
+.PD 0
+.IP MiNT 4
+.IX Item "MiNT"
+.IP "Tenon MachTen" 4
+.IX Item "Tenon MachTen"
+.PD
+.SS "Updated Platforms"
+.IX Subsection "Updated Platforms"
+.IP AIX 4
+.IX Item "AIX"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Removed \fIlibbsd\fR for AIX 5L and 6.1. Only \f(CWflock()\fR was used from
+\&\fIlibbsd\fR.
+.IP \(bu 4
+Removed \fIlibgdbm\fR for AIX 5L and 6.1 if \fIlibgdbm\fR < 1.8.3\-5 is
+installed.  The \fIlibgdbm\fR is delivered as an optional package with the
+AIX Toolbox.  Unfortunately the versions below 1.8.3\-5 are broken.
+.IP \(bu 4
+Hints changes mean that AIX 4.2 should work again.
+.RE
+.RS 4
+.RE
+.IP Cygwin 4
+.IX Item "Cygwin"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Perl now supports IPv6 on Cygwin 1.7 and newer.
+.IP \(bu 4
+On Cygwin we now strip the last number from the DLL. This has been the
+behaviour in the cygwin.com build for years. The hints files have been
+updated.
+.RE
+.RS 4
+.RE
+.IP "Darwin (Mac OS X)" 4
+.IX Item "Darwin (Mac OS X)"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Skip testing the be_BY.CP1131 locale on Darwin 10 (Mac OS X 10.6),
+as it's still buggy.
+.IP \(bu 4
+Correct infelicities in the regexp used to identify buggy locales
+on Darwin 8 and 9 (Mac OS X 10.4 and 10.5, respectively).
+.RE
+.RS 4
+.RE
+.IP "DragonFly BSD" 4
+.IX Item "DragonFly BSD"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Fix thread library selection [perl #69686]
+.RE
+.RS 4
+.RE
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The hints files now identify the correct threading libraries on FreeBSD 7
+and later.
+.RE
+.RS 4
+.RE
+.IP Irix 4
+.IX Item "Irix"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+We now work around a bizarre preprocessor bug in the Irix 6.5 compiler:
+\&\f(CW\*(C`cc \-E \-\*(C'\fR unfortunately goes into K&R mode, but \f(CW\*(C`cc \-E file.c\*(C'\fR doesn't.
+.RE
+.RS 4
+.RE
+.IP NetBSD 4
+.IX Item "NetBSD"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Hints now supports versions 5.*.
+.RE
+.RS 4
+.RE
+.IP OpenVMS 4
+.IX Item "OpenVMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\f(CW\*(C`\-UDEBUGGING\*(C'\fR is now the default on VMS.
+.Sp
+Like it has been everywhere else for ages and ages. Also make command-line
+selection of \-UDEBUGGING and \-DDEBUGGING work in configure.com; before
+the only way to turn it off was by saying no in answer to the interactive
+question.
+.IP \(bu 4
+The default pipe buffer size on VMS has been updated to 8192 on 64\-bit
+systems.
+.IP \(bu 4
+Reads from the in-memory temporary files of \f(CW\*(C`PerlIO::scalar\*(C'\fR used to fail
+if \f(CW$/\fR was set to a numeric reference (to indicate record-style reads).
+This is now fixed.
+.IP \(bu 4
+VMS now supports \f(CW\*(C`getgrgid\*(C'\fR.
+.IP \(bu 4
+Many improvements and cleanups have been made to the VMS file name handling
+and conversion code.
+.IP \(bu 4
+Enabling the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR logical name now encodes a POSIX exit
+status in a VMS condition value for better interaction with GNV's bash
+shell and other utilities that depend on POSIX exit values. See
+"$?" in perlvms for details.
+.IP \(bu 4
+\&\f(CW\*(C`File::Copy\*(C'\fR now detects Unix compatibility mode on VMS.
+.RE
+.RS 4
+.RE
+.IP "Stratus VOS" 4
+.IX Item "Stratus VOS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Various changes from Stratus have been merged in.
+.RE
+.RS 4
+.RE
+.IP Symbian 4
+.IX Item "Symbian"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+There is now support for Symbian S60 3.2 SDK and S60 5.0 SDK.
+.RE
+.RS 4
+.RE
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Perl 5.12 supports Windows 2000 and later. The supporting code for
+legacy versions of Windows is still included, but will be removed
+during the next development cycle.
+.IP \(bu 4
+Initial support for building Perl with MinGW\-w64 is now available.
+.IP \(bu 4
+\&\fIperl.exe\fR now includes a manifest resource to specify the \f(CW\*(C`trustInfo\*(C'\fR
+settings for Windows Vista and later. Without this setting Windows
+would treat \fIperl.exe\fR as a legacy application and apply various
+heuristics like redirecting access to protected file system areas
+(like the "Program Files" folder) to the users "VirtualStore"
+instead of generating a proper "permission denied" error.
+.Sp
+The manifest resource also requests the Microsoft Common-Controls
+version 6.0 (themed controls introduced in Windows XP).  Check out the
+Win32::VisualStyles module on CPAN to switch back to old style
+unthemed controls for legacy applications.
+.IP \(bu 4
+The \f(CW\*(C`\-t\*(C'\fR filetest operator now only returns true if the filehandle
+is connected to a console window.  In previous versions of Perl it
+would return true for all character mode devices, including \fINUL\fR
+and \fILPT1\fR.
+.IP \(bu 4
+The \f(CW\*(C`\-p\*(C'\fR filetest operator now works correctly, and the
+Fcntl::S_IFIFO constant is defined when Perl is compiled with
+Microsoft Visual C.  In previous Perl versions \f(CW\*(C`\-p\*(C'\fR always
+returned a false value, and the Fcntl::S_IFIFO constant
+was not defined.
+.Sp
+This bug is specific to Microsoft Visual C and never affected
+Perl binaries built with MinGW.
+.IP \(bu 4
+The socket error codes are now more widely supported:  The POSIX
+module will define the symbolic names, like POSIX::EWOULDBLOCK,
+and stringification of socket error codes in $! works as well
+now;
+.Sp
+.Vb 2
+\&  C:\e>perl \-MPOSIX \-E "$!=POSIX::EWOULDBLOCK; say $!"
+\&  A non\-blocking socket operation could not be completed immediately.
+.Ve
+.IP \(bu 4
+\&\fBflock()\fR will now set sensible error codes in $!.  Previous Perl versions
+copied the value of $^E into $!, which caused much confusion.
+.IP \(bu 4
+\&\fBselect()\fR now supports all empty \f(CW\*(C`fd_set\*(C'\fRs more correctly.
+.IP \(bu 4
+\&\f(CW\*(Aq.\efoo\*(Aq\fR and \f(CW\*(Aq..\efoo\*(Aq\fR  were treated differently than
+\&\f(CW\*(Aq./foo\*(Aq\fR and \f(CW\*(Aq../foo\*(Aq\fR by \f(CW\*(C`do\*(C'\fR and \f(CW\*(C`require\*(C'\fR [RT #63492].
+.IP \(bu 4
+Improved message window handling means that \f(CW\*(C`alarm\*(C'\fR and \f(CW\*(C`kill\*(C'\fR messages
+will no longer be dropped under race conditions.
+.IP \(bu 4
+Various bits of Perl's build infrastructure are no longer converted to
+win32 line endings at release time. If this hurts you, please report the
+problem with the perlbug program included with perl.
+.RE
+.RS 4
+.RE
+.SH "Known Problems"
+.IX Header "Known Problems"
+This is a list of some significant unfixed bugs, which are regressions
+from either 5.10.x or 5.8.x.
+.IP \(bu 4
+Some CPANPLUS tests may fail if there is a functioning file
+\&\fI../../cpanp\-run\-perl\fR outside your build directory. The failure
+shouldn't imply there's a problem with the actual functional
+software. The bug is already fixed in [RT #74188] and is scheduled for
+inclusion in perl\-v5.12.1.
+.IP \(bu 4
+\&\f(CW\*(C`List::Util::first\*(C'\fR misbehaves in the presence of a lexical \f(CW$_\fR
+(typically introduced by \f(CW\*(C`my $_\*(C'\fR or implicitly by \f(CW\*(C`given\*(C'\fR). The variable
+which gets set for each iteration is the package variable \f(CW$_\fR, not the
+lexical \f(CW$_\fR [RT #67694].
+.Sp
+A similar issue may occur in other modules that provide functions which
+take a block as their first argument, like
+.Sp
+.Vb 1
+\&    foo { ... $_ ...} list
+.Ve
+.IP \(bu 4
+Some regexes may run much more slowly when run in a child thread compared
+with the thread the pattern was compiled into [RT #55600].
+.IP \(bu 4
+Things like \f(CW\*(C`"\eN{LATIN SMALL LIGATURE FF}" =~ /\eN{LATIN SMALL LETTER F}+/\*(C'\fR
+will appear to hang as they get into a very long running loop [RT #72998].
+.IP \(bu 4
+Several porters have reported mysterious crashes when Perl's entire
+test suite is run after a build on certain Windows 2000 systems. When
+run by hand, the individual tests reportedly work fine.
+.SH Errata
+.IX Header "Errata"
+.IP \(bu 4
+This one is actually a change introduced in 5.10.0, but it was missed
+from that release's perldelta, so it is mentioned here instead.
+.Sp
+A bugfix related to the handling of the \f(CW\*(C`/m\*(C'\fR modifier and \f(CW\*(C`qr\*(C'\fR resulted
+in a change of behaviour between 5.8.x and 5.10.0:
+.Sp
+.Vb 2
+\&    # matches in 5.8.x, doesn\*(Aqt match in 5.10.0
+\&    $re = qr/^bar/; "foo\enbar" =~ /$re/m;
+.Ve
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.0 represents approximately two years of development since
+Perl 5.10.0 and contains over 750,000 lines of changes across over
+3,000 files from over 200 authors and committers.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.12.0:
+.PP
+Aaron Crane, Abe Timmerman, Abhijit Menon-Sen, Abigail, Adam Russell,
+Adriano Ferreira, Ævar Arnfjörð Bjarmason, Alan Grover, Alexandr
+Ciornii, Alex Davies, Alex Vandiver, Andreas Koenig, Andrew Rodland,
+andrew@sundale.net, Andy Armstrong, Andy Dougherty, Jose AUGUSTE-ETIENNE,
+Benjamin Smith, Ben Morrow, bharanee rathna, Bo Borgerson, Bo Lindbergh,
+Brad Gilbert, Bram, Brendan O'Dea, brian d foy, Charles Bailey,
+Chip Salzenberg, Chris 'BinGOs' Williams, Christoph Lamprecht, Chris
+Williams, chromatic, Claes Jakobsson, Craig A. Berry, Dan Dascalescu,
+Daniel Frederick Crisman, Daniel M. Quinlan, Dan Jacobson, Dan Kogai,
+Dave Mitchell, Dave Rolsky, David Cantrell, David Dick, David Golden,
+David Mitchell, David M. Syzdek, David Nicol, David Wheeler, Dennis
+Kaarsemaker, Dintelmann, Peter, Dominic Dunlop, Dr.Ruud, Duke Leto,
+Enrico Sorcinelli, Eric Brine, Father Chrysostomos, Florian Ragwitz,
+Frank Wiegand, Gabor Szabo, Gene Sullivan, Geoffrey T. Dairiki, George
+Greer, Gerard Goossen, Gisle Aas, Goro Fuji, Graham Barr, Green, Paul,
+Hans Dieter Pearcey, Harmen, H. Merijn Brand, Hugo van der Sanden,
+Ian Goodacre, Igor Sutton, Ingo Weinhold, James Bence, James Mastros,
+Jan Dubois, Jari Aalto, Jarkko Hietaniemi, Jay Hannah, Jerry Hedden,
+Jesse Vincent, Jim Cromie, Jody Belka, John E. Malmberg, John Malmberg,
+John Peacock, John Peacock via RT, John P. Linderman, John Wright,
+Josh ben Jore, Jos I. Boumans, Karl Williamson, Kenichi Ishigaki, Ken
+Williams, Kevin Brintnall, Kevin Ryde, Kurt Starsinic, Leon Brocard,
+Lubomir Rintel, Luke Ross, Marcel Grünauer, Marcus Holland-Moritz, Mark
+Jason Dominus, Marko Asplund, Martin Hasch, Mashrab Kuvatov, Matt Kraai,
+Matt S Trout, Max Maischein, Michael Breen, Michael Cartmell, Michael
+G Schwern, Michael Witten, Mike Giroux, Milosz Tanski, Moritz Lenz,
+Nicholas Clark, Nick Cleaton, Niko Tyni, Offer Kaye, Osvaldo Villalon,
+Paul Fenwick, Paul Gaborit, Paul Green, Paul Johnson, Paul Marquess,
+Philip Hazel, Philippe Bruhat, Rafael Garcia-Suarez, Rainer Tammer,
+Rajesh Mandalemula, Reini Urban, Renée Bäcker, Ricardo Signes,
+Ricardo SIGNES, Richard Foley, Rich Rauenzahn, Rick Delaney, Risto
+Kankkunen, Robert May, Roberto C. Sanchez, Robin Barker, SADAHIRO
+Tomoyuki, Salvador Ortiz Garcia, Sam Vilain, Scott Lanning, Sébastien
+Aperghis-Tramoni, Sérgio Durigan Júnior, Shlomi Fish, Simon 'corecode'
+Schubert, Sisyphus, Slaven Rezic, Smylers, Steffen Müller, Steffen
+Ullrich, Stepan Kasal, Steve Hay, Steven Schubiger, Steve Peters, Tels,
+The Doctor, Tim Bunce, Tim Jenness, Todd Rinaldo, Tom Christiansen,
+Tom Hukins, Tom Wyant, Tony Cook, Torsten Schoenfeld, Tye McQueen,
+Vadim Konovalov, Vincent Pit, Hio YAMASHINA, Yasuhiro Matsumoto,
+Yitzchak Scott-Thoennes, Yuval Kogman, Yves Orton, Zefram, Zsban Ambrus
+.PP
+This is woefully incomplete as it's automatically generated from version
+control history.  In particular, it doesn't include the names of the
+(very much appreciated) contributors who reported issues in previous
+versions of Perl that helped make Perl 5.12.0 better. For a more complete
+list of all of Perl's historical contributors, please see the \f(CW\*(C`AUTHORS\*(C'\fR
+file in the Perl 5.12.0 distribution.
+.PP
+Our "retired" pumpkings Nicholas Clark and Rafael Garcia-Suarez
+deserve special thanks for their brilliant and substantive ongoing
+contributions. Nicholas personally authored over 30% of the patches
+since 5.10.0. Rafael comes in second in patch authorship with 11%,
+but is first by a long shot in committing patches authored by others,
+pushing 44% of the commits since 5.10.0 in this category, often after
+providing considerable coaching to the patch authors. These statistics
+in no way comprise all of their contributions, but express in shorthand
+that we couldn't have done it without them.
+.PP
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at <http://rt.perl.org/perlbug/>. There may also be
+information at <http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analyzed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
+.PP
+<http://dev.perl.org/perl5/errata.html> for a list of issues
+found after this release, as well as a list of CPAN modules known
+to be incompatible with this release.
diff --git a/upstream/mageia-cauldron/man1/perl5121delta.1 b/upstream/mageia-cauldron/man1/perl5121delta.1
new file mode 100644
index 00000000..18da69d7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5121delta.1
@@ -0,0 +1,325 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5121DELTA 1"
+.TH PERL5121DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5121delta \- what is new for perl v5.12.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.0 release and
+the 5.12.1 release.
+.PP
+If you are upgrading from an earlier release such as 5.10.1, first read
+perl5120delta, which describes differences between 5.10.0 and
+5.12.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.12.0. If any
+incompatibilities with 5.12.0 exist, they are bugs. Please report them.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+Other than the bug fixes listed below, there should be no user-visible
+changes to the core language in this release.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Pragmata Changes"
+.IX Subsection "Pragmata Changes"
+.IP \(bu 4
+We fixed exporting of \f(CW\*(C`is_strict\*(C'\fR and \f(CW\*(C`is_lax\*(C'\fR from version.
+.Sp
+These were being exported with a wrapper that treated them as method
+calls, which caused them to fail.  They are just functions, are
+documented as such, and should never be subclassed, so this patch
+just exports them directly as functions without the wrapper.
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+.IP \(bu 4
+We upgraded CGI to version 3.49 to incorporate fixes for regressions
+introduced in the release we shipped with Perl 5.12.0.
+.IP \(bu 4
+We upgraded Pod::Simple to version 3.14 to get an improvement to \eC\e<\e< \e>\e>
+parsing.
+.IP \(bu 4
+We made a small fix to the CPANPLUS test suite to fix an occasional spurious test failure.
+.IP \(bu 4
+We upgraded Safe to version 2.27 to wrap coderefs returned by \f(CWreval()\fR and \f(CWrdo()\fR.
+.SH "Changes to Existing Documentation"
+.IX Header "Changes to Existing Documentation"
+.IP \(bu 4
+We added the new maintenance release policy to perlpolicy
+.IP \(bu 4
+We've clarified the multiple-angle-bracket construct in the spec for POD
+in perlpodspec
+.IP \(bu 4
+We added a missing explanation for a warning about \f(CW\*(C`:=\*(C'\fR to perldiag
+.IP \(bu 4
+We removed a false claim in perlunitut that all text strings are Unicode strings in Perl.
+.IP \(bu 4
+We updated the GitHub mirror link in perlrepository to mirrors/perl, not github/perl
+.IP \(bu 4
+We fixed a minor error in perl5114delta.
+.IP \(bu 4
+We replaced a mention of the now-obsolete Switch with \fIgiven\fR/\fIwhen\fR.
+.IP \(bu 4
+We improved documentation about \fR\f(CI$sitelibexp\fR\fI/sitecustomize.pl\fR in perlrun.
+.IP \(bu 4
+We corrected perlmodlib which had unintentionally omitted a number of modules.
+.IP \(bu 4
+We updated the documentation for 'require' in perlfunc relating to putting Perl code in \f(CW@INC\fR.
+.IP \(bu 4
+We reinstated some erroneously-removed documentation about quotemeta in perlfunc.
+.IP \(bu 4
+We fixed an \fIa2p\fR example in perlutil.
+.IP \(bu 4
+We filled in a blank in perlport with the release date of Perl 5.12.
+.IP \(bu 4
+We fixed broken links in a number of perldelta files.
+.IP \(bu 4
+The documentation for Carp incorrectly stated that the \f(CW$Carp::Verbose\fR
+variable makes cluck generate stack backtraces.
+.IP \(bu 4
+We fixed a number of typos in Pod::Functions
+.IP \(bu 4
+We improved documentation of case-changing functions in perlfunc
+.IP \(bu 4
+We corrected perlgpl to contain the correct version of the GNU
+General Public License.
+.SH Testing
+.IX Header "Testing"
+.SS "Testing Improvements"
+.IX Subsection "Testing Improvements"
+.IP \(bu 4
+\&\fIt/op/sselect.t\fR is now less prone to clock jitter during timing checks
+on Windows.
+.Sp
+\&\fBsleep()\fR time on Win32 may be rounded down to multiple of
+the clock tick interval.
+.IP \(bu 4
+\&\fIlib/blib.t\fR and \fIlib/locale.t\fR: Fixes for test failures on Darwin/PPC
+.IP \(bu 4
+\&\fIperl5db.t\fR: Fix for test failures when \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR is installed.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Configuration improvements"
+.IX Subsection "Configuration improvements"
+.IP \(bu 4
+We updated \fIINSTALL\fR with notes about how to deal with broken \fIdbm.h\fR
+on OpenSUSE (and possibly other platforms)
+.SH "Bug Fixes"
+.IX Header "Bug Fixes"
+.IP \(bu 4
+A bug in how we process filetest operations could cause a segfault.
+Filetests don't always expect an op on the stack, so we now use
+TOPs only if we're sure that we're not stat'ing the _ filehandle.
+This is indicated by OPf_KIDS (as checked in ck_ftst).
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10335>
+.IP \(bu 4
+When deparsing a nextstate op that has both a change of package (relative
+to the previous nextstate) and a label, the package declaration is now
+emitted first, because it is syntactically impermissible for a label to
+prefix a package declaration.
+.IP \(bu 4
+XSUB.h now correctly redefines fgets under PERL_IMPLICIT_SYS
+.Sp
+See also: <http://rt.cpan.org/Public/Bug/Display.html?id=55049>
+.IP \(bu 4
+utf8::is_utf8 now respects GMAGIC (e.g. \f(CW$1\fR)
+.IP \(bu 4
+XS code using \f(CWfputc()\fR or \f(CWfputs()\fR: on Windows could cause an error
+due to their arguments being swapped.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10156>
+.IP \(bu 4
+We fixed a small bug in \fBlex_stuff_pvn()\fR that caused spurious syntax errors
+in an obscure situation.  It happened when stuffing was performed on the
+last line of a file and the line ended with a statement that lacked a
+terminating semicolon.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10273>
+.IP \(bu 4
+We fixed a bug that could cause \eN{} constructs followed by a single . to
+be parsed incorrectly.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10367>
+.IP \(bu 4
+We fixed a bug that caused when(scalar) without an argument not to be
+treated as a syntax error.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10287>
+.IP \(bu 4
+We fixed a regression in the handling of labels immediately before string
+evals that was introduced in Perl 5.12.0.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10301>
+.IP \(bu 4
+We fixed a regression in case-insensitive matching of folded characters
+in regular expressions introduced in Perl 5.10.1.
+.Sp
+See also: <https://github.com/Perl/perl5/issues/10193>
+.SH "Platform Specific Notes"
+.IX Header "Platform Specific Notes"
+.SS HP-UX
+.IX Subsection "HP-UX"
+.IP \(bu 4
+Perl now allows \-Duse64bitint without promoting to use64bitall on HP-UX
+.SS AIX
+.IX Subsection "AIX"
+.IP \(bu 4
+Perl now builds on AIX 4.2
+.Sp
+The changes required work around AIX 4.2s' lack of support for IPv6,
+and limited support for POSIX \f(CWsigaction()\fR.
+.SS "FreeBSD 7"
+.IX Subsection "FreeBSD 7"
+.IP \(bu 4
+FreeBSD 7 no longer contains \fI/usr/bin/objformat\fR. At build time,
+Perl now skips the \fIobjformat\fR check for versions 7 and higher and
+assumes ELF.
+.SS VMS
+.IX Subsection "VMS"
+.IP \(bu 4
+It's now possible to build extensions on older (pre 7.3\-2) VMS systems.
+.Sp
+DCL symbol length was limited to 1K up until about seven years or
+so ago, but there was no particularly deep reason to prevent those
+older systems from configuring and building Perl.
+.IP \(bu 4
+We fixed the previously-broken \f(CW\*(C`\-Uuseperlio\*(C'\fR build on VMS.
+.Sp
+We were checking a variable that doesn't exist in the non-default
+case of disabling perlio.  Now we only look at it when it exists.
+.IP \(bu 4
+We fixed the \-Uuseperlio command-line option in configure.com.
+.Sp
+Formerly it only worked if you went through all the questions
+interactively and explicitly answered no.
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+\&\f(CW\*(C`List::Util::first\*(C'\fR misbehaves in the presence of a lexical \f(CW$_\fR
+(typically introduced by \f(CW\*(C`my $_\*(C'\fR or implicitly by \f(CW\*(C`given\*(C'\fR). The variable
+which gets set for each iteration is the package variable \f(CW$_\fR, not the
+lexical \f(CW$_\fR.
+.Sp
+A similar issue may occur in other modules that provide functions which
+take a block as their first argument, like
+.Sp
+.Vb 1
+\&    foo { ... $_ ...} list
+.Ve
+.Sp
+See also: <https://github.com/Perl/perl5/issues/9798>
+.IP \(bu 4
+\&\f(CW\*(C`Module::Load::Conditional\*(C'\fR and \f(CW\*(C`version\*(C'\fR have an unfortunate
+interaction which can cause \f(CW\*(C`CPANPLUS\*(C'\fR to crash when it encounters
+an unparseable version string.  Upgrading to \f(CW\*(C`CPANPLUS\*(C'\fR 0.9004 or
+\&\f(CW\*(C`Module::Load::Conditional\*(C'\fR 0.38 from CPAN will resolve this issue.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.1 represents approximately four weeks of development since
+Perl 5.12.0 and contains approximately 4,000 lines of changes
+across 142 files from 28 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.12.1:
+.PP
+Ævar Arnfjörð Bjarmason, Chris Williams, chromatic, Craig A. Berry,
+David Golden, Father Chrysostomos, Florian Ragwitz, Frank Wiegand,
+Gene Sullivan, Goro Fuji, H.Merijn Brand, James E Keenan, Jan Dubois,
+Jesse Vincent, Josh ben Jore, Karl Williamson, Leon Brocard, Michael
+Schwern, Nga Tang Chan, Nicholas Clark, Niko Tyni, Philippe Bruhat,
+Rafael Garcia-Suarez, Ricardo Signes, Steffen Mueller, Todd Rinaldo,
+Vincent Pit and Zefram.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5122delta.1 b/upstream/mageia-cauldron/man1/perl5122delta.1
new file mode 100644
index 00000000..6437cc1c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5122delta.1
@@ -0,0 +1,300 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5122DELTA 1"
+.TH PERL5122DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5122delta \- what is new for perl v5.12.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.1 release and
+the 5.12.2 release.
+.PP
+If you are upgrading from an earlier major version, such as 5.10.1,
+first read perl5120delta, which describes differences between 5.10.0
+and 5.12.0, as well as perl5121delta, which describes earlier changes
+in the 5.12 stable release series.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.12.1. If any exist, they
+are bugs and reports are welcome.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+Other than the bug fixes listed below, there should be no user-visible
+changes to the core language in this release.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+This release does not introduce any new modules or pragmata.
+.SS "Pragmata Changes"
+.IX Subsection "Pragmata Changes"
+In the previous release, \f(CW\*(C`no \fR\f(CIVERSION\fR\f(CW;\*(C'\fR statements triggered a bug
+which could cause feature bundles to be loaded and strict mode to
+be enabled unintentionally.
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+.ie n .IP """Carp""" 4
+.el .IP \f(CWCarp\fR 4
+.IX Item "Carp"
+Upgraded from version 1.16 to 1.17.
+.Sp
+Carp now detects incomplete \fBcaller()\fR
+overrides and avoids using bogus \f(CW@DB::args\fR. To provide backtraces, Carp
+relies on particular behaviour of the caller built-in. Carp now detects
+if other code has overridden this with an incomplete implementation, and
+modifies its backtrace accordingly. Previously incomplete overrides would
+cause incorrect values in backtraces (best case), or obscure fatal errors
+(worst case)
+.Sp
+This fixes certain cases of \f(CW\*(C`Bizarre copy of ARRAY\*(C'\fR caused by modules
+overriding \f(CWcaller()\fR incorrectly.
+.ie n .IP """CPANPLUS""" 4
+.el .IP \f(CWCPANPLUS\fR 4
+.IX Item "CPANPLUS"
+A patch to \fIcpanp-run-perl\fR has been backported from CPANPLUS \f(CW0.9004\fR. This
+resolves RT #55964 <http://rt.cpan.org/Public/Bug/Display.html?id=55964>
+and RT #57106 <http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both
+of which related to failures to install distributions that use
+\&\f(CW\*(C`Module::Install::DSL\*(C'\fR.
+.ie n .IP """File::Glob""" 4
+.el .IP \f(CWFile::Glob\fR 4
+.IX Item "File::Glob"
+A regression which caused a failure to find \f(CW\*(C`CORE::GLOBAL::glob\*(C'\fR after
+loading \f(CW\*(C`File::Glob\*(C'\fR to crash has been fixed.  Now, it correctly falls back
+to external globbing via \f(CW\*(C`pp_glob\*(C'\fR.
+.ie n .IP """File::Copy""" 4
+.el .IP \f(CWFile::Copy\fR 4
+.IX Item "File::Copy"
+\&\f(CW\*(C`File::Copy::copy(FILE, DIR)\*(C'\fR is now documented.
+.ie n .IP """File::Spec""" 4
+.el .IP \f(CWFile::Spec\fR 4
+.IX Item "File::Spec"
+Upgraded from version 3.31 to 3.31_01.
+.Sp
+Several portability fixes were made in \f(CW\*(C`File::Spec::VMS\*(C'\fR: a colon is now
+recognized as a delimiter in native filespecs; caret-escaped delimiters are
+recognized for better handling of extended filespecs; \f(CWcatpath()\fR returns
+an empty directory rather than the current directory if the input directory
+name is empty; \f(CWabs2rel()\fR properly handles Unix-style input.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.IP \(bu 4
+\&\fIperlbug\fR now always gives the reporter a chance to change the email address it
+guesses for them.
+.IP \(bu 4
+\&\fIperlbug\fR should no longer warn about uninitialized values when using the \f(CW\*(C`\-d\*(C'\fR
+and \f(CW\*(C`\-v\*(C'\fR options.
+.SH "Changes to Existing Documentation"
+.IX Header "Changes to Existing Documentation"
+.IP \(bu 4
+The existing policy on backward-compatibility and deprecation has
+been added to perlpolicy, along with definitions of terms like
+\&\fIdeprecation\fR.
+.IP \(bu 4
+"srand" in perlfunc's usage has been clarified.
+.IP \(bu 4
+The entry for "die" in perlfunc was reorganized to emphasize its
+role in the exception mechanism.
+.IP \(bu 4
+Perl's INSTALL file has been clarified to explicitly state that Perl
+requires a C89 compliant ANSI C Compiler.
+.IP \(bu 4
+IO::Socket's \f(CWgetsockopt()\fR and \f(CWsetsockopt()\fR have been documented.
+.IP \(bu 4
+\&\fR\f(BIalarm()\fR\fI\fR's inability to interrupt blocking IO on Windows has been documented.
+.IP \(bu 4
+Math::TrulyRandom hasn't been updated since 1996 and has been removed
+as a recommended solution for random number generation.
+.IP \(bu 4
+perlrun has been updated to clarify the behaviour of octal flags to \fIperl\fR.
+.IP \(bu 4
+To ease user confusion, \f(CW$#\fR and \f(CW$*\fR, two special variables that were
+removed in earlier versions of Perl have been documented.
+.IP \(bu 4
+The version of perlfaq shipped with the Perl core has been updated from the
+official FAQ version, which is now maintained in the \f(CW\*(C`briandfoy/perlfaq\*(C'\fR
+branch of the Perl repository at <git://perl5.git.perl.org/perl.git>.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Configuration improvements"
+.IX Subsection "Configuration improvements"
+.IP \(bu 4
+The \f(CW\*(C`d_u32align\*(C'\fR configuration probe on ARM has been fixed.
+.SS "Compilation improvements"
+.IX Subsection "Compilation improvements"
+.IP \(bu 4
+An "\f(CW\*(C`incompatible operand types\*(C'\fR" error in ternary expressions when building
+with \f(CW\*(C`clang\*(C'\fR has been fixed.
+.IP \(bu 4
+Perl now skips setuid \f(CW\*(C`File::Copy\*(C'\fR tests on partitions it detects to be mounted
+as \f(CW\*(C`nosuid\*(C'\fR.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+A possible segfault in the \f(CW\*(C`T_PRTOBJ\*(C'\fR default typemap has been fixed.
+.IP \(bu 4
+A possible memory leak when using \fBcaller()\fR to set
+\&\f(CW@DB::args\fR has been fixed.
+.IP \(bu 4
+Several memory leaks when loading XS modules were fixed.
+.IP \(bu 4
+\&\f(CWunpack()\fR now handles scalar context correctly for \f(CW%32H\fR and \f(CW%32u\fR,
+fixing a potential crash.  \f(CWsplit()\fR would crash because the third item
+on the stack wasn't the regular expression it expected.  \f(CW\*(C`unpack("%2H",
+\&...)\*(C'\fR would return both the unpacked result and the checksum on the stack,
+as would \f(CW\*(C`unpack("%2u", ...)\*(C'\fR.
+[GH #10257] <https://github.com/Perl/perl5/issues/10257>
+.IP \(bu 4
+Perl now avoids using memory after calling \f(CWfree()\fR in \fIpp_require\fR
+when there are CODEREFs in \f(CW@INC\fR.
+.IP \(bu 4
+A bug that could cause "\f(CW\*(C`Unknown error\*(C'\fR" messages when
+"\f(CW\*(C`call_sv(code, G_EVAL)\*(C'\fR" is called from an XS destructor has been fixed.
+.IP \(bu 4
+The implementation of the \f(CW\*(C`open $fh, \*(Aq>\*(Aq \e$buffer\*(C'\fR feature
+now supports get/set magic and thus tied buffers correctly.
+.IP \(bu 4
+The \f(CW\*(C`pp_getc\*(C'\fR, \f(CW\*(C`pp_tell\*(C'\fR, and \f(CW\*(C`pp_eof\*(C'\fR opcodes now make room on the
+stack for their return values in cases where no argument was passed in.
+.IP \(bu 4
+When matching unicode strings under some conditions inappropriate backtracking would
+result in a \f(CW\*(C`Malformed UTF\-8 character (fatal)\*(C'\fR error. This should no longer occur.
+See  [GH #10434] <https://github.com/Perl/perl5/issues/10434>
+.SH "Platform Specific Notes"
+.IX Header "Platform Specific Notes"
+.SS AIX
+.IX Subsection "AIX"
+.IP \(bu 4
+\&\fIREADME.aix\fR has been updated with information about the XL C/C++ V11 compiler
+suite.
+.SS Windows
+.IX Subsection "Windows"
+.IP \(bu 4
+When building Perl with the mingw64 x64 cross-compiler \f(CW\*(C`incpath\*(C'\fR,
+\&\f(CW\*(C`libpth\*(C'\fR, \f(CW\*(C`ldflags\*(C'\fR, \f(CW\*(C`lddlflags\*(C'\fR and \f(CW\*(C`ldflags_nolargefiles\*(C'\fR values
+in \fIConfig.pm\fR and \fIConfig_heavy.pl\fR were not previously being set
+correctly because, with that compiler, the include and lib directories
+are not immediately below \f(CW\*(C`$(CCHOME)\*(C'\fR.
+.SS VMS
+.IX Subsection "VMS"
+.IP \(bu 4
+\&\fIgit_version.h\fR is now installed on VMS. This was an oversight in v5.12.0 which
+caused some extensions to fail to build.
+.IP \(bu 4
+Several memory leaks in \fBstat()\fR have been fixed.
+.IP \(bu 4
+A memory leak in \f(CWPerl_rename()\fR due to a double allocation has been
+fixed.
+.IP \(bu 4
+A memory leak in \f(CWvms_fid_to_name()\fR (used by \f(CWrealpath()\fR and
+\&\f(CWrealname()\fR) has been fixed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.2 represents approximately three months of development since
+Perl 5.12.1 and contains approximately 2,000 lines of changes across
+100 files from 36 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.12.2:
+.PP
+Abigail, Ævar Arnfjörð Bjarmason, Ben Morrow, brian d foy, Brian
+Phillips, Chas. Owens, Chris 'BinGOs' Williams, Chris Williams,
+Craig A. Berry, Curtis Jewell, Dan Dascalescu, David Golden, David
+Mitchell, Father Chrysostomos, Florian Ragwitz, George Greer, H.Merijn
+Brand, Jan Dubois, Jesse Vincent, Jim Cromie, Karl Williamson, Lars
+Dɪᴇᴄᴋ�ᴡ 迪拉斯, Leon Brocard, Maik Hentsche, Matt S Trout,
+Nicholas Clark, Rafael Garcia-Suarez, Rainer Tammer, Ricardo Signes,
+Salvador Ortiz Garcia, Sisyphus, Slaven Rezic, Steffen Mueller, Tony Cook,
+Vincent Pit and Yves Orton.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5123delta.1 b/upstream/mageia-cauldron/man1/perl5123delta.1
new file mode 100644
index 00000000..aa31e226
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5123delta.1
@@ -0,0 +1,166 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5123DELTA 1"
+.TH PERL5123DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5123delta \- what is new for perl v5.12.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.2 release and
+the 5.12.3 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.1, first read
+perl5122delta, which describes differences between 5.12.1 and
+5.12.2.  The major changes made in 5.12.0 are described in perl5120delta.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.Vb 2
+\&    There are no changes intentionally incompatible with 5.12.2. If any
+\&    exist, they are bugs and reports are welcome.
+.Ve
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS """keys"", ""values"" work on arrays"
+.el .SS "\f(CWkeys\fP, \f(CWvalues\fP work on arrays"
+.IX Subsection "keys, values work on arrays"
+You can now use the \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR, \f(CW\*(C`each\*(C'\fR builtin functions on arrays
+(previously you could only use them on hashes).  See perlfunc for details.
+This is actually a change introduced in perl 5.12.0, but it was missed from
+that release's perldelta.
+.SH "Bug Fixes"
+.IX Header "Bug Fixes"
+"no VERSION" will now correctly deparse with B::Deparse, as will certain
+constant expressions.
+.PP
+Module::Build should be more reliably pass its tests under cygwin.
+.PP
+Lvalue subroutines are again able to return copy-on-write scalars.  This
+had been broken since version 5.10.0.
+.SH "Platform Specific Notes"
+.IX Header "Platform Specific Notes"
+.IP Solaris 4
+.IX Item "Solaris"
+A separate DTrace is now build for miniperl, which means that perl can be
+compiled with \-Dusedtrace on Solaris again.
+.IP VMS 4
+.IX Item "VMS"
+A number of regressions on VMS have been fixed.  In addition to minor cleanup
+of questionable expressions in \fIvms.c\fR, file permissions should no longer be
+garbled by the PerlIO layer, and spurious record boundaries should no longer be
+introduced by the PerlIO layer during output.
+.Sp
+For more details and discussion on the latter, see:
+.Sp
+.Vb 1
+\&    http://www.nntp.perl.org/group/perl.vmsperl/2010/11/msg15419.html
+.Ve
+.IP VOS 4
+.IX Item "VOS"
+A few very small changes were made to the build process on VOS to better
+support the platform.  Longer\-than\-32\-character filenames are now supported on
+OpenVOS, and build properly without IPv6 support.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.3 represents approximately four months of development since
+Perl 5.12.2 and contains approximately 2500 lines of changes across
+54 files from 16 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.12.3:
+.PP
+Craig A. Berry, David Golden, David Leadbeater, Father Chrysostomos, Florian
+Ragwitz, Jesse Vincent, Karl Williamson, Nick Johnston, Nicolas Kaiser, Paul
+Green, Rafael Garcia-Suarez, Rainer Tammer, Ricardo Signes, Steffen Mueller,
+Zsbán Ambrus, Ævar Arnfjörð Bjarmason
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5124delta.1 b/upstream/mageia-cauldron/man1/perl5124delta.1
new file mode 100644
index 00000000..84bf2271
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5124delta.1
@@ -0,0 +1,151 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5124DELTA 1"
+.TH PERL5124DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5124delta \- what is new for perl v5.12.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.3 release and
+the 5.12.4 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.2, first read
+perl5123delta, which describes differences between 5.12.2
+and 5.12.3. The major changes made in 5.12.0 are described in perl5120delta.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.12.3. If any
+exist, they are bugs and reports are welcome.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+When strict "refs" mode is off, \f(CW\*(C`%{...}\*(C'\fR in rvalue context returns
+\&\f(CW\*(C`undef\*(C'\fR if its argument is undefined.  An optimisation introduced in Perl
+5.12.0 to make \f(CW\*(C`keys %{...}\*(C'\fR faster when used as a boolean did not take
+this into account, causing \f(CW\*(C`keys %{+undef}\*(C'\fR (and \f(CW\*(C`keys %$foo\*(C'\fR when
+\&\f(CW$foo\fR is undefined) to be an error, which it should be so in strict
+mode only [perl #81750].
+.PP
+\&\f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, and \f(CW\*(C`ucfirst\*(C'\fR no longer return untainted strings
+when the argument is tainted. This has been broken since perl 5.8.9
+[perl #87336].
+.PP
+Fixed a case where it was possible that a freed buffer may have been read
+from when parsing a here document.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+Module::CoreList has been upgraded from version 2.43 to 2.50.
+.SH Testing
+.IX Header "Testing"
+The \fIcpan/CGI/t/http.t\fR test script has been fixed to work when the
+environment has HTTPS_* environment variables, such as HTTPS_PROXY.
+.SH Documentation
+.IX Header "Documentation"
+Updated the documentation for \fBrand()\fR in perlfunc to note that it is not
+cryptographically secure.
+.SH "Platform Specific Notes"
+.IX Header "Platform Specific Notes"
+.IP Linux 4
+.IX Item "Linux"
+Support Ubuntu 11.04's new multi-arch library layout.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.4 represents approximately 5 months of development since
+Perl 5.12.3 and contains approximately 200 lines of changes across
+11 files from 8 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.12.4:
+.PP
+Andy Dougherty, David Golden, David Leadbeater, Father Chrysostomos,
+Florian Ragwitz, Jesse Vincent, Leon Brocard, Zsbán Ambrus.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5125delta.1 b/upstream/mageia-cauldron/man1/perl5125delta.1
new file mode 100644
index 00000000..eaf737d2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5125delta.1
@@ -0,0 +1,266 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5125DELTA 1"
+.TH PERL5125DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5125delta \- what is new for perl v5.12.5
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.4 release and
+the 5.12.5 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.3, first read
+perl5124delta, which describes differences between 5.12.3 and
+5.12.4.
+.SH Security
+.IX Header "Security"
+.ie n .SS """Encode"" decode_xs n\-byte heap-overflow (CVE\-2011\-2939)"
+.el .SS "\f(CWEncode\fP decode_xs n\-byte heap-overflow (CVE\-2011\-2939)"
+.IX Subsection "Encode decode_xs n-byte heap-overflow (CVE-2011-2939)"
+A bug in \f(CW\*(C`Encode\*(C'\fR could, on certain inputs, cause the heap to overflow.
+This problem has been corrected.  Bug reported by Robert Zacek.
+.ie n .SS "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.el .SS "\f(CWFile::Glob::bsd_glob()\fP memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.IX Subsection "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+Calling \f(CW\*(C`File::Glob::bsd_glob\*(C'\fR with the unsupported flag GLOB_ALTDIRFUNC would 
+cause an access violation / segfault.  A Perl program that accepts a flags value from
+an external source could expose itself to denial of service or arbitrary code
+execution attacks.  There are no known exploits in the wild.  The problem has been
+corrected by explicitly disabling all unsupported flags and setting unused function
+pointers to null.  Bug reported by Clément Lecigne.
+.SS "Heap buffer overrun in 'x' string repeat operator (CVE\-2012\-5195)"
+.IX Subsection "Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)"
+Poorly written perl code that allows an attacker to specify the count to
+perl's 'x' string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before 5.15.5 can
+escalate that into a heap buffer overrun; coupled with versions of glibc
+before 2.16, it possibly allows the execution of arbitrary code.
+.PP
+This problem has been fixed.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.12.4. If any
+exist, they are bugs and reports are welcome.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+\fIB::Concise\fR
+.IX Subsection "B::Concise"
+.PP
+B::Concise no longer produces mangled output with the \fB\-tree\fR option
+[perl #80632].
+.PP
+\fIcharnames\fR
+.IX Subsection "charnames"
+.PP
+A regression introduced in Perl 5.8.8 has been fixed, that caused
+\&\f(CWcharnames::viacode(0)\fR to return \f(CW\*(C`undef\*(C'\fR instead of the string "NULL"
+[perl #72624].
+.PP
+\fIEncode has been upgraded from version 2.39 to version 2.39_01.\fR
+.IX Subsection "Encode has been upgraded from version 2.39 to version 2.39_01."
+.PP
+See "Security".
+.PP
+\fIFile::Glob has been upgraded from version 1.07 to version 1.07_01.\fR
+.IX Subsection "File::Glob has been upgraded from version 1.07 to version 1.07_01."
+.PP
+See "Security".
+.PP
+\fIUnicode::UCD\fR
+.IX Subsection "Unicode::UCD"
+.PP
+The documentation for the \f(CW\*(C`upper\*(C'\fR function now actually says "upper", not
+"lower".
+.PP
+\fIModule::CoreList\fR
+.IX Subsection "Module::CoreList"
+.PP
+Module::CoreList has been updated to version 2.50_02 to add data for
+this release.
+.SH "Changes to Existing Documentation"
+.IX Header "Changes to Existing Documentation"
+.SS perlebcdic
+.IX Subsection "perlebcdic"
+The perlebcdic document contains a helpful table to use in \f(CW\*(C`tr///\*(C'\fR to
+convert between EBCDIC and Latin1/ASCII.  Unfortunately, the table was the
+inverse of the one it describes.  This has been corrected.
+.SS perlunicode
+.IX Subsection "perlunicode"
+The section on
+User-Defined Case Mappings had
+some bad markup and unclear sentences, making parts of it unreadable.  This
+has been rectified.
+.SS perluniprops
+.IX Subsection "perluniprops"
+This document has been corrected to take non-ASCII platforms into account.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Platform Specific Changes"
+.IX Subsection "Platform Specific Changes"
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+There have been configuration and test fixes to make Perl build cleanly on
+Lion and Mountain Lion.
+.IP NetBSD 4
+.IX Item "NetBSD"
+The NetBSD hints file was corrected to be compatible with NetBSD 6.*
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\f(CW\*(C`chop\*(C'\fR now correctly handles characters above "\ex{7fffffff}"
+[perl #73246].
+.IP \(bu 4
+\&\f(CW\*(C`($<,$>) = (...)\*(C'\fR stopped working properly in 5.12.0.  It is supposed
+to make a single \f(CWsetreuid()\fR call, rather than calling \f(CWsetruid()\fR and
+\&\f(CWseteuid()\fR separately.  Consequently it did not work properly.  This has
+been fixed [perl #75212].
+.IP \(bu 4
+Fixed a regression of \fBkill()\fR when a match variable is used for the
+process ID to kill [perl #75812].
+.IP \(bu 4
+\&\f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR no longer leaks memory.  It started leaking in Perl
+5.10.0.
+.IP \(bu 4
+The C\-level \f(CW\*(C`my_strftime\*(C'\fR functions no longer leaks memory.  This fixes a
+memory leak in \f(CW\*(C`POSIX::strftime\*(C'\fR [perl #73520].
+.IP \(bu 4
+\&\f(CW\*(C`caller\*(C'\fR no longer leaks memory when called from the DB package if
+\&\f(CW@DB::args\fR was assigned to after the first call to \f(CW\*(C`caller\*(C'\fR.  Carp
+was triggering this bug [perl #97010].
+.IP \(bu 4
+Passing to \f(CW\*(C`index\*(C'\fR an offset beyond the end of the string when the string
+is encoded internally in UTF8 no longer causes panics [perl #75898].
+.IP \(bu 4
+Syntax errors in \f(CW\*(C`(?{...})\*(C'\fR blocks in regular expressions no longer
+cause panic messages [perl #2353].
+.IP \(bu 4
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty.  This has
+been fixed [perl #90160].
+.SH Errata
+.IX Header "Errata"
+.ie n .SS "\fBsplit()\fP and @_"
+.el .SS "\fBsplit()\fP and \f(CW@_\fP"
+.IX Subsection "split() and @_"
+\&\fBsplit()\fR no longer modifies \f(CW@_\fR when called in scalar or void context.
+In void context it now produces a "Useless use of split" warning.
+This is actually a change introduced in perl 5.12.0, but it was missed from
+that release's perl5120delta.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.12.5 represents approximately 17 months of development since Perl 5.12.4
+and contains approximately 1,900 lines of changes across 64 files from 18
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.12.5:
+.PP
+Andy Dougherty, Chris 'BinGOs' Williams, Craig A. Berry, David Mitchell,
+Dominic Hargreaves, Father Chrysostomos, Florian Ragwitz, George Greer, Goro
+Fuji, Jesse Vincent, Karl Williamson, Leon Brocard, Nicholas Clark, Rafael
+Garcia-Suarez, Reini Urban, Ricardo Signes, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5140delta.1 b/upstream/mageia-cauldron/man1/perl5140delta.1
new file mode 100644
index 00000000..73af95f8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5140delta.1
@@ -0,0 +1,3862 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5140DELTA 1"
+.TH PERL5140DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5140delta \- what is new for perl v5.14.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.12.0 release and
+the 5.14.0 release.
+.PP
+If you are upgrading from an earlier release such as 5.10.0, first read
+perl5120delta, which describes differences between 5.10.0 and
+5.12.0.
+.PP
+Some of the bug fixes in this release have been backported to subsequent
+releases of 5.12.x.  Those are indicated with the 5.12.x version in
+parentheses.
+.SH Notice
+.IX Header "Notice"
+As described in perlpolicy, the release of Perl 5.14.0 marks the
+official end of support for Perl 5.10.  Users of Perl 5.10 or earlier
+should consider upgrading to a more recent release of Perl.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS Unicode
+.IX Subsection "Unicode"
+\fIUnicode Version 6.0 is now supported (mostly)\fR
+.IX Subsection "Unicode Version 6.0 is now supported (mostly)"
+.PP
+Perl comes with the Unicode 6.0 data base updated with
+Corrigendum #8 <http://www.unicode.org/versions/corrigendum8.html>,
+with one exception noted below.
+See <http://unicode.org/versions/Unicode6.0.0/> for details on the new
+release.  Perl does not support any Unicode provisional properties,
+including the new ones for this release.
+.PP
+Unicode 6.0 has chosen to use the name \f(CW\*(C`BELL\*(C'\fR for the character at U+1F514,
+which is a symbol that looks like a bell, and is used in Japanese cell
+phones.  This conflicts with the long-standing Perl usage of having
+\&\f(CW\*(C`BELL\*(C'\fR mean the ASCII \f(CW\*(C`BEL\*(C'\fR character, U+0007.  In Perl 5.14,
+\&\f(CW\*(C`\eN{BELL}\*(C'\fR continues to mean U+0007, but its use generates a
+deprecation warning message unless such warnings are turned off.  The
+new name for U+0007 in Perl is \f(CW\*(C`ALERT\*(C'\fR, which corresponds nicely
+with the existing shorthand sequence for it, \f(CW"\ea"\fR.  \f(CW\*(C`\eN{BEL}\*(C'\fR
+means U+0007, with no warning given.  The character at U+1F514 has no
+name in 5.14, but can be referred to by \f(CW\*(C`\eN{U+1F514}\*(C'\fR. 
+In Perl 5.16, \f(CW\*(C`\eN{BELL}\*(C'\fR will refer to U+1F514; all code
+that uses \f(CW\*(C`\eN{BELL}\*(C'\fR should be converted to use \f(CW\*(C`\eN{ALERT}\*(C'\fR,
+\&\f(CW\*(C`\eN{BEL}\*(C'\fR, or \f(CW"\ea"\fR before upgrading.
+.PP
+\fIFull functionality for \fR\f(CI\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR
+.IX Subsection "Full functionality for use feature unicode_strings"
+.PP
+This release provides full functionality for \f(CWuse feature
+\&\*(Aqunicode_strings\*(Aq\fR.  Under its scope, all string operations executed and
+regular expressions compiled (even if executed outside its scope) have
+Unicode semantics.  See "the 'unicode_strings' feature" in feature.
+However, see "Inverted bracketed character classes and multi-character folds",
+below.
+.PP
+This feature avoids most forms of the "Unicode Bug" (see
+"The "Unicode Bug"" in perlunicode for details).  If there is any
+possibility that your code will process Unicode strings, you are
+\&\fIstrongly\fR encouraged to use this subpragma to avoid nasty surprises.
+.PP
+\fR\f(CI\*(C`\eN{NAME}\*(C'\fR\fI and \fR\f(CI\*(C`charnames\*(C'\fR\fI enhancements\fR
+.IX Subsection "N{NAME} and charnames enhancements"
+.IP \(bu 4
+\&\f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR and \f(CW\*(C`charnames::vianame\*(C'\fR now know about the abbreviated
+character names listed by Unicode, such as NBSP, SHY, LRO, ZWJ, etc.; all
+customary abbreviations for the C0 and C1 control characters (such as
+ACK, BEL, CAN, etc.); and a few new variants of some C1 full names that
+are in common usage.
+.IP \(bu 4
+Unicode has several \fInamed character sequences\fR, in which particular sequences
+of code points are given names.  \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR now recognizes these.
+.IP \(bu 4
+\&\f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR, \f(CW\*(C`charnames::vianame\*(C'\fR, and \f(CW\*(C`charnames::viacode\*(C'\fR
+now know about every character in Unicode.  In earlier releases of
+Perl, they didn't know about the Hangul syllables nor several
+CJK (Chinese/Japanese/Korean) characters.
+.IP \(bu 4
+It is now possible to override Perl's abbreviations with your own custom aliases.
+.IP \(bu 4
+You can now create a custom alias of the ordinal of a
+character, known by \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR, \f(CWcharnames::vianame()\fR, and
+\&\f(CWcharnames::viacode()\fR.  Previously, aliases had to be to official
+Unicode character names.  This made it impossible to create an alias for
+unnamed code points, such as those reserved for private
+use.
+.IP \(bu 4
+The new function \fBcharnames::string_vianame()\fR is a run-time version
+of \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}}\*(C'\fR, returning the string of characters whose Unicode
+name is its parameter.  It can handle Unicode named character
+sequences, whereas the pre-existing \fBcharnames::vianame()\fR cannot,
+as the latter returns a single code point.
+.PP
+See charnames for details on all these changes.
+.PP
+\fINew warnings categories for problematic (non\-)Unicode code points.\fR
+.IX Subsection "New warnings categories for problematic (non-)Unicode code points."
+.PP
+Three new warnings subcategories of "utf8" have been added.  These
+allow you to turn off some "utf8" warnings, while allowing
+other warnings to remain on.  The three categories are:
+\&\f(CW\*(C`surrogate\*(C'\fR when UTF\-16 surrogates are encountered;
+\&\f(CW\*(C`nonchar\*(C'\fR when Unicode non-character code points are encountered;
+and \f(CW\*(C`non_unicode\*(C'\fR when code points above the legal Unicode
+maximum of 0x10FFFF are encountered.
+.PP
+\fIAny unsigned value can be encoded as a character\fR
+.IX Subsection "Any unsigned value can be encoded as a character"
+.PP
+With this release, Perl is adopting a model that any unsigned value
+can be treated as a code point and encoded internally (as utf8)
+without warnings, not just the code points that are legal in Unicode.
+However, unless utf8 or the corresponding sub-category (see previous
+item) of lexical warnings have been explicitly turned off, outputting
+or executing a Unicode-defined operation such as upper-casing
+on such a code point generates a warning.  Attempting to input these
+using strict rules (such as with the \f(CW:encoding(UTF\-8)\fR layer)
+will continue to fail.  Prior to this release, handling was
+inconsistent and in places, incorrect.
+.PP
+Unicode non-characters, some of which previously were erroneously
+considered illegal in places by Perl, contrary to the Unicode Standard,
+are now always legal internally.  Inputting or outputting them 
+works the same as with the non-legal Unicode code points, because the Unicode
+Standard says they are (only) illegal for "open interchange".
+.PP
+\fIUnicode database files not installed\fR
+.IX Subsection "Unicode database files not installed"
+.PP
+The Unicode database files are no longer installed with Perl.  This
+doesn't affect any functionality in Perl and saves significant disk
+space.  If you need these files, you can download them from
+<http://www.unicode.org/Public/zipped/6.0.0/>.
+.SS "Regular Expressions"
+.IX Subsection "Regular Expressions"
+\fR\f(CI\*(C`(?^...)\*(C'\fR\fI construct signifies default modifiers\fR
+.IX Subsection "(?^...) construct signifies default modifiers"
+.PP
+An ASCII caret \f(CW"^"\fR immediately following a \f(CW"(?"\fR in a regular
+expression now means that the subexpression does not inherit surrounding
+modifiers such as \f(CW\*(C`/i\*(C'\fR, but reverts to the Perl defaults.  Any modifiers
+following the caret override the defaults.
+.PP
+Stringification of regular expressions now uses this notation.  
+For example, \f(CW\*(C`qr/hlagh/i\*(C'\fR would previously be stringified as
+\&\f(CW\*(C`(?i\-xsm:hlagh)\*(C'\fR, but now it's stringified as \f(CW\*(C`(?^i:hlagh)\*(C'\fR.
+.PP
+The main purpose of this change is to allow tests that rely on the
+stringification \fInot\fR to have to change whenever new modifiers are added.
+See "Extended Patterns" in perlre.
+.PP
+This change is likely to break code that compares stringified regular
+expressions with fixed strings containing \f(CW\*(C`?\-xism\*(C'\fR.
+.PP
+\fR\f(CI\*(C`/d\*(C'\fR\fI, \fR\f(CI\*(C`/l\*(C'\fR\fI, \fR\f(CI\*(C`/u\*(C'\fR\fI, and \fR\f(CI\*(C`/a\*(C'\fR\fI modifiers\fR
+.IX Subsection "/d, /l, /u, and /a modifiers"
+.PP
+Four new regular expression modifiers have been added.  These are mutually
+exclusive: one only can be turned on at a time.
+.IP \(bu 4
+The \f(CW\*(C`/l\*(C'\fR modifier says to compile the regular expression as if it were
+in the scope of \f(CW\*(C`use locale\*(C'\fR, even if it is not.
+.IP \(bu 4
+The \f(CW\*(C`/u\*(C'\fR modifier says to compile the regular expression as if it were
+in the scope of a \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR pragma.
+.IP \(bu 4
+The \f(CW\*(C`/d\*(C'\fR (default) modifier is used to override any \f(CW\*(C`use locale\*(C'\fR and
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR pragmas in effect at the time
+of compiling the regular expression.
+.IP \(bu 4
+The \f(CW\*(C`/a\*(C'\fR regular expression modifier restricts \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\ed\*(C'\fR and \f(CW\*(C`\ew\*(C'\fR and
+the POSIX (\f(CW\*(C`[[:posix:]]\*(C'\fR) character classes to the ASCII range.  Their
+complements and \f(CW\*(C`\eb\*(C'\fR and \f(CW\*(C`\eB\*(C'\fR are correspondingly
+affected.  Otherwise, \f(CW\*(C`/a\*(C'\fR behaves like the \f(CW\*(C`/u\*(C'\fR modifier, in that
+case-insensitive matching uses Unicode semantics.
+.Sp
+If the \f(CW\*(C`/a\*(C'\fR modifier is repeated, then additionally in case-insensitive
+matching, no ASCII character can match a non-ASCII character.
+For example,
+.Sp
+.Vb 2
+\&    "k"     =~ /\eN{KELVIN SIGN}/ai
+\&    "\exDF" =~ /ss/ai
+.Ve
+.Sp
+match but
+.Sp
+.Vb 2
+\&    "k"    =~ /\eN{KELVIN SIGN}/aai
+\&    "\exDF" =~ /ss/aai
+.Ve
+.Sp
+do not match.
+.PP
+See "Modifiers" in perlre for more detail.
+.PP
+\fINon-destructive substitution\fR
+.IX Subsection "Non-destructive substitution"
+.PP
+The substitution (\f(CW\*(C`s///\*(C'\fR) and transliteration
+(\f(CW\*(C`y///\*(C'\fR) operators now support an \f(CW\*(C`/r\*(C'\fR option that
+copies the input variable, carries out the substitution on
+the copy, and returns the result.  The original remains unmodified.
+.PP
+.Vb 3
+\&  my $old = "cat";
+\&  my $new = $old =~ s/cat/dog/r;
+\&  # $old is "cat" and $new is "dog"
+.Ve
+.PP
+This is particularly useful with \f(CW\*(C`map\*(C'\fR.  See perlop for more examples.
+.PP
+\fIRe-entrant regular expression engine\fR
+.IX Subsection "Re-entrant regular expression engine"
+.PP
+It is now safe to use regular expressions within \f(CW\*(C`(?{...})\*(C'\fR and
+\&\f(CW\*(C`(??{...})\*(C'\fR code blocks inside regular expressions.
+.PP
+These blocks are still experimental, however, and still have problems with
+lexical (\f(CW\*(C`my\*(C'\fR) variables and abnormal exiting.
+.PP
+\fR\f(CI\*(C`use re \*(Aq/flags\*(Aq\*(C'\fR\fI\fR
+.IX Subsection "use re /flags"
+.PP
+The \f(CW\*(C`re\*(C'\fR pragma now has the ability to turn on regular expression flags
+till the end of the lexical scope:
+.PP
+.Vb 2
+\&    use re "/x";
+\&    "foo" =~ / (.+) /;  # /x implied
+.Ve
+.PP
+See "'/flags' mode" in re for details.
+.PP
+\fI\eo{...} for octals\fR
+.IX Subsection "o{...} for octals"
+.PP
+There is a new octal escape sequence, \f(CW"\eo"\fR, in doublequote-like
+contexts.  This construct allows large octal ordinals beyond the
+current max of 0777 to be represented.  It also allows you to specify a
+character in octal which can safely be concatenated with other regex
+snippets and which won't be confused with being a backreference to
+a regex capture group.  See "Capture groups" in perlre.
+.PP
+\fIAdd \fR\f(CI\*(C`\ep{Titlecase}\*(C'\fR\fI as a synonym for \fR\f(CI\*(C`\ep{Title}\*(C'\fR
+.IX Subsection "Add p{Titlecase} as a synonym for p{Title}"
+.PP
+This synonym is added for symmetry with the Unicode property names
+\&\f(CW\*(C`\ep{Uppercase}\*(C'\fR and \f(CW\*(C`\ep{Lowercase}\*(C'\fR.
+.PP
+\fIRegular expression debugging output improvement\fR
+.IX Subsection "Regular expression debugging output improvement"
+.PP
+Regular expression debugging output (turned on by \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR) now
+uses hexadecimal when escaping non-ASCII characters, instead of octal.
+.PP
+\fIReturn value of \fR\f(CI\*(C`delete $+{...}\*(C'\fR
+.IX Subsection "Return value of delete $+{...}"
+.PP
+Custom regular expression engines can now determine the return value of
+\&\f(CW\*(C`delete\*(C'\fR on an entry of \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR.
+.SS "Syntactical Enhancements"
+.IX Subsection "Syntactical Enhancements"
+\fIArray and hash container functions accept references\fR
+.IX Subsection "Array and hash container functions accept references"
+.PP
+\&\fBWarning:\fR This feature is considered experimental, as the exact behaviour
+may change in a future version of Perl.
+.PP
+All builtin functions that operate directly on array or hash
+containers now also accept unblessed hard references to arrays
+or hashes:
+.PP
+.Vb 10
+\&  |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
+\&  | Traditional syntax         | Terse syntax              |
+\&  |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
+\&  | push @$arrayref, @stuff    | push $arrayref, @stuff    |
+\&  | unshift @$arrayref, @stuff | unshift $arrayref, @stuff |
+\&  | pop @$arrayref             | pop $arrayref             |
+\&  | shift @$arrayref           | shift $arrayref           |
+\&  | splice @$arrayref, 0, 2    | splice $arrayref, 0, 2    |
+\&  | keys %$hashref             | keys $hashref             |
+\&  | keys @$arrayref            | keys $arrayref            |
+\&  | values %$hashref           | values $hashref           |
+\&  | values @$arrayref          | values $arrayref          |
+\&  | ($k,$v) = each %$hashref   | ($k,$v) = each $hashref   |
+\&  | ($k,$v) = each @$arrayref  | ($k,$v) = each $arrayref  |
+\&  |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
+.Ve
+.PP
+This allows these builtin functions to act on long dereferencing chains
+or on the return value of subroutines without needing to wrap them in
+\&\f(CW\*(C`@{}\*(C'\fR or \f(CW\*(C`%{}\*(C'\fR:
+.PP
+.Vb 2
+\&  push @{$obj\->tags}, $new_tag;  # old way
+\&  push $obj\->tags,    $new_tag;  # new way
+\&
+\&  for ( keys %{$hoh\->{genres}{artists}} ) {...} # old way 
+\&  for ( keys $hoh\->{genres}{artists}    ) {...} # new way
+.Ve
+.PP
+\fISingle term prototype\fR
+.IX Subsection "Single term prototype"
+.PP
+The \f(CW\*(C`+\*(C'\fR prototype is a special alternative to \f(CW\*(C`$\*(C'\fR that acts like
+\&\f(CW\*(C`\e[@%]\*(C'\fR when given a literal array or hash variable, but will otherwise
+force scalar context on the argument.  See "Prototypes" in perlsub.
+.PP
+\fR\f(CI\*(C`package\*(C'\fR\fI block syntax\fR
+.IX Subsection "package block syntax"
+.PP
+A package declaration can now contain a code block, in which case the
+declaration is in scope inside that block only.  So \f(CW\*(C`package Foo { ... }\*(C'\fR
+is precisely equivalent to \f(CW\*(C`{ package Foo; ... }\*(C'\fR.  It also works with
+a version number in the declaration, as in \f(CW\*(C`package Foo 1.2 { ... }\*(C'\fR, 
+which is its most attractive feature.  See perlfunc.
+.PP
+\fIStatement labels can appear in more places\fR
+.IX Subsection "Statement labels can appear in more places"
+.PP
+Statement labels can now occur before any type of statement or declaration,
+such as \f(CW\*(C`package\*(C'\fR.
+.PP
+\fIStacked labels\fR
+.IX Subsection "Stacked labels"
+.PP
+Multiple statement labels can now appear before a single statement.
+.PP
+\fIUppercase X/B allowed in hexadecimal/binary literals\fR
+.IX Subsection "Uppercase X/B allowed in hexadecimal/binary literals"
+.PP
+Literals may now use either upper case \f(CW\*(C`0X...\*(C'\fR or \f(CW\*(C`0B...\*(C'\fR prefixes,
+in addition to the already supported \f(CW\*(C`0x...\*(C'\fR and \f(CW\*(C`0b...\*(C'\fR
+syntax [perl #76296].
+.PP
+C, Ruby, Python, and PHP already support this syntax, and it makes
+Perl more internally consistent: a round-trip with \f(CW\*(C`eval sprintf
+"%#X", 0x10\*(C'\fR now returns \f(CW16\fR, just like \f(CW\*(C`eval sprintf "%#x", 0x10\*(C'\fR.
+.PP
+\fIOverridable tie functions\fR
+.IX Subsection "Overridable tie functions"
+.PP
+\&\f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR and \f(CW\*(C`untie\*(C'\fR can now be overridden [perl #75902].
+.SS "Exception Handling"
+.IX Subsection "Exception Handling"
+To make them more reliable and consistent, several changes have been made
+to how \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, and \f(CW$@\fR behave.
+.IP \(bu 4
+When an exception is thrown inside an \f(CW\*(C`eval\*(C'\fR, the exception is no
+longer at risk of being clobbered by destructor code running during unwinding.
+Previously, the exception was written into \f(CW$@\fR
+early in the throwing process, and would be overwritten if \f(CW\*(C`eval\*(C'\fR was
+used internally in the destructor for an object that had to be freed
+while exiting from the outer \f(CW\*(C`eval\*(C'\fR.  Now the exception is written
+into \f(CW$@\fR last thing before exiting the outer \f(CW\*(C`eval\*(C'\fR, so the code
+running immediately thereafter can rely on the value in \f(CW$@\fR correctly
+corresponding to that \f(CW\*(C`eval\*(C'\fR.  (\f(CW$@\fR is still also set before exiting the
+\&\f(CW\*(C`eval\*(C'\fR, for the sake of destructors that rely on this.)
+.Sp
+Likewise, a \f(CW\*(C`local $@\*(C'\fR inside an \f(CW\*(C`eval\*(C'\fR no longer clobbers any
+exception thrown in its scope.  Previously, the restoration of \f(CW$@\fR upon
+unwinding would overwrite any exception being thrown.  Now the exception
+gets to the \f(CW\*(C`eval\*(C'\fR anyway.  So \f(CW\*(C`local $@\*(C'\fR is safe before a \f(CW\*(C`die\*(C'\fR.
+.Sp
+Exceptions thrown from object destructors no longer modify the \f(CW$@\fR
+of the surrounding context.  (If the surrounding context was exception
+unwinding, this used to be another way to clobber the exception being
+thrown.)  Previously such an exception was
+sometimes emitted as a warning, and then either was
+string-appended to the surrounding \f(CW$@\fR or completely replaced the
+surrounding \f(CW$@\fR, depending on whether that exception and the surrounding
+\&\f(CW$@\fR were strings or objects.  Now, an exception in this situation is
+always emitted as a warning, leaving the surrounding \f(CW$@\fR untouched.
+In addition to object destructors, this also affects any function call
+run by XS code using the \f(CW\*(C`G_KEEPERR\*(C'\fR flag.
+.IP \(bu 4
+Warnings for \f(CW\*(C`warn\*(C'\fR can now be objects in the same way as exceptions
+for \f(CW\*(C`die\*(C'\fR.  If an object-based warning gets the default handling
+of writing to standard error, it is stringified as before with the
+filename and line number appended.  But a \f(CW$SIG{_\|_WARN_\|_}\fR handler now
+receives an object-based warning as an object, where previously it
+was passed the result of stringifying the object.
+.SS "Other Enhancements"
+.IX Subsection "Other Enhancements"
+\fIAssignment to \fR\f(CI$0\fR\fI sets the legacy process name with \fR\f(BIprctl()\fR\fI on Linux\fR
+.IX Subsection "Assignment to $0 sets the legacy process name with prctl() on Linux"
+.PP
+On Linux the legacy process name is now set with \fBprctl\fR\|(2), in
+addition to altering the POSIX name via \f(CW\*(C`argv[0]\*(C'\fR, as Perl has done
+since version 4.000.  Now system utilities that read the legacy process
+name such as \fIps\fR, \fItop\fR, and \fIkillall\fR recognize the name you set when
+assigning to \f(CW$0\fR.  The string you supply is truncated at 16 bytes;
+this limitation is imposed by Linux.
+.PP
+\fR\f(BIsrand()\fR\fI now returns the seed\fR
+.IX Subsection "srand() now returns the seed"
+.PP
+This allows programs that need to have repeatable results not to have to come
+up with their own seed-generating mechanism.  Instead, they can use \fBsrand()\fR
+and stash the return value for future use.  One example is a test program with
+too many combinations to test comprehensively in the time available for
+each run.  It can test a random subset each time and, should there be a failure,
+log the seed used for that run so this can later be used to produce the same results.
+.PP
+\fIprintf-like functions understand post\-1980 size modifiers\fR
+.IX Subsection "printf-like functions understand post-1980 size modifiers"
+.PP
+Perl's printf and sprintf operators, and Perl's internal printf replacement
+function, now understand the C90 size modifiers "hh" (\f(CW\*(C`char\*(C'\fR), "z"
+(\f(CW\*(C`size_t\*(C'\fR), and "t" (\f(CW\*(C`ptrdiff_t\*(C'\fR).  Also, when compiled with a C99
+compiler, Perl now understands the size modifier "j" (\f(CW\*(C`intmax_t\*(C'\fR) 
+(but this is not portable).
+.PP
+So, for example, on any modern machine, \f(CW\*(C`sprintf("%hhd", 257)\*(C'\fR returns "1".
+.PP
+\fINew global variable \fR\f(CI\*(C`${^GLOBAL_PHASE}\*(C'\fR
+.IX Subsection "New global variable ${^GLOBAL_PHASE}"
+.PP
+A new global variable, \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR, has been added to allow
+introspection of the current phase of the Perl interpreter.  It's explained in
+detail in "${^GLOBAL_PHASE}" in perlvar and in
+"BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod.
+.PP
+\fR\f(CI\*(C`\-d:\-foo\*(C'\fR\fI calls \fR\f(CI\*(C`Devel::foo::unimport\*(C'\fR\fI\fR
+.IX Subsection "-d:-foo calls Devel::foo::unimport"
+.PP
+The syntax \fB\-d:foo\fR was extended in 5.6.1 to make \fB\-d:foo=bar\fR
+equivalent to \fB\-MDevel::foo=bar\fR, which expands
+internally to \f(CW\*(C`use Devel::foo \*(Aqbar\*(Aq\*(C'\fR.
+Perl now allows prefixing the module name with \fB\-\fR, with the same
+semantics as \fB\-M\fR; that is:
+.ie n .IP """\-d:\-foo""" 4
+.el .IP \f(CW\-d:\-foo\fR 4
+.IX Item "-d:-foo"
+Equivalent to \fB\-M\-Devel::foo\fR: expands to
+\&\f(CW\*(C`no Devel::foo\*(C'\fR and calls \f(CW\*(C`Devel::foo\->unimport()\*(C'\fR
+if that method exists.
+.ie n .IP """\-d:\-foo=bar""" 4
+.el .IP \f(CW\-d:\-foo=bar\fR 4
+.IX Item "-d:-foo=bar"
+Equivalent to \fB\-M\-Devel::foo=bar\fR: expands to \f(CW\*(C`no Devel::foo \*(Aqbar\*(Aq\*(C'\fR,
+and calls \f(CW\*(C`Devel::foo\->unimport("bar")\*(C'\fR if that method exists.
+.PP
+This is particularly useful for suppressing the default actions of a
+\&\f(CW\*(C`Devel::*\*(C'\fR module's \f(CW\*(C`import\*(C'\fR method whilst still loading it for debugging.
+.PP
+\fIFilehandle method calls load IO::File on demand\fR
+.IX Subsection "Filehandle method calls load IO::File on demand"
+.PP
+When a method call on a filehandle would die because the method cannot
+be resolved and IO::File has not been loaded, Perl now loads IO::File
+via \f(CW\*(C`require\*(C'\fR and attempts method resolution again:
+.PP
+.Vb 2
+\&  open my $fh, ">", $file;
+\&  $fh\->binmode(":raw");     # loads IO::File and succeeds
+.Ve
+.PP
+This also works for globs like \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`STDERR\*(C'\fR, and \f(CW\*(C`STDIN\*(C'\fR:
+.PP
+.Vb 1
+\&  STDOUT\->autoflush(1);
+.Ve
+.PP
+Because this on-demand load happens only if method resolution fails, the
+legacy approach of manually loading an IO::File parent class for partial
+method support still works as expected:
+.PP
+.Vb 3
+\&  use IO::Handle;
+\&  open my $fh, ">", $file;
+\&  $fh\->autoflush(1);        # IO::File not loaded
+.Ve
+.PP
+\fIImproved IPv6 support\fR
+.IX Subsection "Improved IPv6 support"
+.PP
+The \f(CW\*(C`Socket\*(C'\fR module provides new affordances for IPv6,
+including implementations of the \f(CWSocket::getaddrinfo()\fR and
+\&\f(CWSocket::getnameinfo()\fR functions, along with related constants and a
+handful of new functions.  See Socket.
+.PP
+\fIDTrace probes now include package name\fR
+.IX Subsection "DTrace probes now include package name"
+.PP
+The \f(CW\*(C`DTrace\*(C'\fR probes now include an additional argument, \f(CW\*(C`arg3\*(C'\fR, which contains
+the package the subroutine being entered or left was compiled in.
+.PP
+For example, using the following DTrace script:
+.PP
+.Vb 4
+\&  perl$target:::sub\-entry
+\&  {
+\&      printf("%s::%s\en", copyinstr(arg0), copyinstr(arg3));
+\&  }
+.Ve
+.PP
+and then running:
+.PP
+.Vb 1
+\&  $ perl \-e \*(Aqsub test { }; test\*(Aq
+.Ve
+.PP
+\&\f(CW\*(C`DTrace\*(C'\fR will print:
+.PP
+.Vb 1
+\&  main::test
+.Ve
+.SS "New C APIs"
+.IX Subsection "New C APIs"
+See "Internal Changes".
+.SH Security
+.IX Header "Security"
+.SS "User-defined regular expression properties"
+.IX Subsection "User-defined regular expression properties"
+"User-Defined Character Properties" in perlunicode documented that you can
+create custom properties by defining subroutines whose names begin with
+"In" or "Is".  However, Perl did not actually enforce that naming
+restriction, so \f(CW\*(C`\ep{foo::bar}\*(C'\fR could call \fBfoo::bar()\fR if it existed.  The documented
+convention is now enforced.
+.PP
+Also, Perl no longer allows tainted regular expressions to invoke a
+user-defined property.  It simply dies instead [perl #82616].
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+Perl 5.14.0 is not binary-compatible with any previous stable release.
+.PP
+In addition to the sections that follow, see "C API Changes".
+.SS "Regular Expressions and String Escapes"
+.IX Subsection "Regular Expressions and String Escapes"
+\fIInverted bracketed character classes and multi-character folds\fR
+.IX Subsection "Inverted bracketed character classes and multi-character folds"
+.PP
+Some characters match a sequence of two or three characters in \f(CW\*(C`/i\*(C'\fR
+regular expression matching under Unicode rules.  One example is
+\&\f(CW\*(C`LATIN SMALL LETTER SHARP S\*(C'\fR which matches the sequence \f(CW\*(C`ss\*(C'\fR.
+.PP
+.Vb 1
+\& \*(Aqss\*(Aq =~ /\eA[\eN{LATIN SMALL LETTER SHARP S}]\ez/i  # Matches
+.Ve
+.PP
+This, however, can lead to very counter-intuitive results, especially
+when inverted.  Because of this, Perl 5.14 does not use multi-character \f(CW\*(C`/i\*(C'\fR
+matching in inverted character classes.
+.PP
+.Vb 1
+\& \*(Aqss\*(Aq =~ /\eA[^\eN{LATIN SMALL LETTER SHARP S}]+\ez/i  # ???
+.Ve
+.PP
+This should match any sequences of characters that aren't the \f(CW\*(C`SHARP S\*(C'\fR
+nor what \f(CW\*(C`SHARP S\*(C'\fR matches under \f(CW\*(C`/i\*(C'\fR.  \f(CW"s"\fR isn't \f(CW\*(C`SHARP S\*(C'\fR, but
+Unicode says that \f(CW"ss"\fR is what \f(CW\*(C`SHARP S\*(C'\fR matches under \f(CW\*(C`/i\*(C'\fR.  So
+which one "wins"? Do you fail the match because the string has \f(CW\*(C`ss\*(C'\fR or
+accept it because it has an \f(CW\*(C`s\*(C'\fR followed by another \f(CW\*(C`s\*(C'\fR?
+.PP
+Earlier releases of Perl did allow this multi-character matching,
+but due to bugs, it mostly did not work.
+.PP
+\fI\e400\-\e777\fR
+.IX Subsection "400-777"
+.PP
+In certain circumstances, \f(CW\*(C`\e400\*(C'\fR\-\f(CW\*(C`\e777\*(C'\fR in regexes have behaved
+differently than they behave in all other doublequote-like contexts.
+Since 5.10.1, Perl has issued a deprecation warning when this happens.
+Now, these literals behave the same in all doublequote-like contexts,
+namely to be equivalent to \f(CW\*(C`\ex{100}\*(C'\fR\-\f(CW\*(C`\ex{1FF}\*(C'\fR, with no deprecation
+warning.
+.PP
+Use of \f(CW\*(C`\e400\*(C'\fR\-\f(CW\*(C`\e777\*(C'\fR in the command-line option \fB\-0\fR retain their
+conventional meaning.  They slurp whole input files; previously, this
+was documented only for \fB\-0777\fR.
+.PP
+Because of various ambiguities, you should use the new
+\&\f(CW\*(C`\eo{...}\*(C'\fR construct to represent characters in octal instead.
+.PP
+\fIMost \fR\f(CI\*(C`\ep{}\*(C'\fR\fI properties are now immune to case-insensitive matching\fR
+.IX Subsection "Most p{} properties are now immune to case-insensitive matching"
+.PP
+For most Unicode properties, it doesn't make sense to have them match
+differently under \f(CW\*(C`/i\*(C'\fR case-insensitive matching.  Doing so can lead
+to unexpected results and potential security holes.  For example
+.PP
+.Vb 1
+\& m/\ep{ASCII_Hex_Digit}+/i
+.Ve
+.PP
+could previously match non-ASCII characters because of the Unicode
+matching rules (although there were several bugs with this).  Now
+matching under \f(CW\*(C`/i\*(C'\fR gives the same results as non\-\f(CW\*(C`/i\*(C'\fR matching except
+for those few properties where people have come to expect differences,
+namely the ones where casing is an integral part of their meaning, such
+as \f(CW\*(C`m/\ep{Uppercase}/i\*(C'\fR and \f(CW\*(C`m/\ep{Lowercase}/i\*(C'\fR, both of which match
+the same code points as matched by \f(CW\*(C`m/\ep{Cased}/i\*(C'\fR.
+Details are in "Unicode Properties" in perlrecharclass.
+.PP
+User-defined property handlers that need to match differently under \f(CW\*(C`/i\*(C'\fR
+must be changed to read the new boolean parameter passed to them, which
+is non-zero if case-insensitive matching is in effect and 0 otherwise.
+See "User-Defined Character Properties" in perlunicode.
+.PP
+\fI\ep{} implies Unicode semantics\fR
+.IX Subsection "p{} implies Unicode semantics"
+.PP
+Specifying a Unicode property in the pattern indicates
+that the pattern is meant for matching according to Unicode rules, the way
+\&\f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR does.
+.PP
+\fIRegular expressions retain their localeness when interpolated\fR
+.IX Subsection "Regular expressions retain their localeness when interpolated"
+.PP
+Regular expressions compiled under \f(CW\*(C`use locale\*(C'\fR now retain this when
+interpolated into a new regular expression compiled outside a
+\&\f(CW\*(C`use locale\*(C'\fR, and vice-versa.
+.PP
+Previously, one regular expression interpolated into another inherited
+the localeness of the surrounding regex, losing whatever state it
+originally had.  This is considered a bug fix, but may trip up code that
+has come to rely on the incorrect behaviour.
+.PP
+\fIStringification of regexes has changed\fR
+.IX Subsection "Stringification of regexes has changed"
+.PP
+Default regular expression modifiers are now notated using
+\&\f(CW\*(C`(?^...)\*(C'\fR.  Code relying on the old stringification will fail.  
+This is so that when new modifiers are added, such code won't
+have to keep changing each time this happens, because the stringification 
+will automatically incorporate the new modifiers.
+.PP
+Code that needs to work properly with both old\- and new-style regexes
+can avoid the whole issue by using (for perls since 5.9.5; see re):
+.PP
+.Vb 2
+\& use re qw(regexp_pattern);
+\& my ($pat, $mods) = regexp_pattern($re_ref);
+.Ve
+.PP
+If the actual stringification is important or older Perls need to be
+supported, you can use something like the following:
+.PP
+.Vb 2
+\&    # Accept both old and new\-style stringification
+\&    my $modifiers = (qr/foobar/ =~ /\eQ(?^/) ? "^" : "\-xism";
+.Ve
+.PP
+And then use \f(CW$modifiers\fR instead of \f(CW\*(C`\-xism\*(C'\fR.
+.PP
+\fIRun-time code blocks in regular expressions inherit pragmata\fR
+.IX Subsection "Run-time code blocks in regular expressions inherit pragmata"
+.PP
+Code blocks in regular expressions (\f(CW\*(C`(?{...})\*(C'\fR and \f(CW\*(C`(??{...})\*(C'\fR) previously
+did not inherit pragmata (strict, warnings, etc.) if the regular expression
+was compiled at run time as happens in cases like these two:
+.PP
+.Vb 3
+\&  use re "eval";
+\&  $foo =~ $bar; # when $bar contains (?{...})
+\&  $foo =~ /$bar(?{ $finished = 1 })/;
+.Ve
+.PP
+This bug has now been fixed, but code that relied on the buggy behaviour
+may need to be fixed to account for the correct behaviour.
+.SS "Stashes and Package Variables"
+.IX Subsection "Stashes and Package Variables"
+\fILocalised tied hashes and arrays are no longed tied\fR
+.IX Subsection "Localised tied hashes and arrays are no longed tied"
+.PP
+In the following:
+.PP
+.Vb 6
+\&    tie @a, ...;
+\&    {
+\&            local @a;
+\&            # here, @a is a now a new, untied array
+\&    }
+\&    # here, @a refers again to the old, tied array
+.Ve
+.PP
+Earlier versions of Perl incorrectly tied the new local array.  This has
+now been fixed.  This fix could however potentially cause a change in
+behaviour of some code.
+.PP
+\fIStashes are now always defined\fR
+.IX Subsection "Stashes are now always defined"
+.PP
+\&\f(CW\*(C`defined %Foo::\*(C'\fR now always returns true, even when no symbols have yet been
+defined in that package.
+.PP
+This is a side-effect of removing a special-case kludge in the tokeniser,
+added for 5.10.0, to hide side-effects of changes to the internal storage of
+hashes.  The fix drastically reduces hashes' memory overhead.
+.PP
+Calling defined on a stash has been deprecated since 5.6.0, warned on
+lexicals since 5.6.0, and warned for stashes and other package
+variables since 5.12.0.  \f(CW\*(C`defined %hash\*(C'\fR has always exposed an
+implementation detail: emptying a hash by deleting all entries from it does
+not make \f(CW\*(C`defined %hash\*(C'\fR false.  Hence \f(CW\*(C`defined %hash\*(C'\fR is not valid code to
+determine whether an arbitrary hash is empty.  Instead, use the behaviour
+of an empty \f(CW%hash\fR always returning false in scalar context.
+.PP
+\fIClearing stashes\fR
+.IX Subsection "Clearing stashes"
+.PP
+Stash list assignment \f(CW\*(C`%foo:: = ()\*(C'\fR used to make the stash temporarily 
+anonymous while it was being emptied.  Consequently, any of its
+subroutines referenced elsewhere would become anonymous,  showing up as
+"(unknown)" in \f(CW\*(C`caller\*(C'\fR.  They now retain their package names such that
+\&\f(CW\*(C`caller\*(C'\fR returns the original sub name if there is still a reference
+to its typeglob and "foo::_\|_ANON_\|_" otherwise [perl #79208].
+.PP
+\fIDereferencing typeglobs\fR
+.IX Subsection "Dereferencing typeglobs"
+.PP
+If you assign a typeglob to a scalar variable:
+.PP
+.Vb 1
+\&    $glob = *foo;
+.Ve
+.PP
+the glob that is copied to \f(CW$glob\fR is marked with a special flag
+indicating that the glob is just a copy.  This allows subsequent
+assignments to \f(CW$glob\fR to overwrite the glob.  The original glob,
+however, is immutable.
+.PP
+Some Perl operators did not distinguish between these two types of globs.
+This would result in strange behaviour in edge cases: \f(CW\*(C`untie $scalar\*(C'\fR
+would not untie the scalar if the last thing assigned to it was a glob
+(because it treated it as \f(CW\*(C`untie *$scalar\*(C'\fR, which unties a handle).
+Assignment to a glob slot (such as \f(CW\*(C`*$glob = \e@some_array\*(C'\fR) would simply
+assign \f(CW\*(C`\e@some_array\*(C'\fR to \f(CW$glob\fR.
+.PP
+To fix this, the \f(CW\*(C`*{}\*(C'\fR operator (including its \f(CW*foo\fR and \f(CW*$foo\fR forms)
+has been modified to make a new immutable glob if its operand is a glob
+copy.  This allows operators that make a distinction between globs and
+scalars to be modified to treat only immutable globs as globs.  (\f(CW\*(C`tie\*(C'\fR,
+\&\f(CW\*(C`tied\*(C'\fR and \f(CW\*(C`untie\*(C'\fR have been left as they are for compatibility's sake,
+but will warn.  See "Deprecations".)
+.PP
+This causes an incompatible change in code that assigns a glob to the
+return value of \f(CW\*(C`*{}\*(C'\fR when that operator was passed a glob copy.  Take the
+following code, for instance:
+.PP
+.Vb 2
+\&    $glob = *foo;
+\&    *$glob = *bar;
+.Ve
+.PP
+The \f(CW*$glob\fR on the second line returns a new immutable glob.  That new
+glob is made an alias to \f(CW*bar\fR.  Then it is discarded.  So the second
+assignment has no effect.
+.PP
+See <https://github.com/Perl/perl5/issues/10625> for
+more detail.
+.PP
+\fIMagic variables outside the main package\fR
+.IX Subsection "Magic variables outside the main package"
+.PP
+In previous versions of Perl, magic variables like \f(CW$!\fR, \f(CW%SIG\fR, etc. would
+"leak" into other packages.  So \f(CW%foo::SIG\fR could be used to access signals,
+\&\f(CW\*(C`${"foo::!"}\*(C'\fR (with strict mode off) to access C's \f(CW\*(C`errno\*(C'\fR, etc.
+.PP
+This was a bug, or an "unintentional" feature, which caused various ill effects,
+such as signal handlers being wiped when modules were loaded, etc.
+.PP
+This has been fixed (or the feature has been removed, depending on how you see
+it).
+.PP
+\fIlocal($_) strips all magic from \fR\f(CI$_\fR
+.IX Subsection "local($_) strips all magic from $_"
+.PP
+\&\fBlocal()\fR on scalar variables gives them a new value but keeps all
+their magic intact.  This has proven problematic for the default
+scalar variable \f(CW$_\fR, where perlsub recommends that any subroutine
+that assigns to \f(CW$_\fR should first localize it.  This would throw an
+exception if \f(CW$_\fR is aliased to a read-only variable, and could in general have
+various unintentional side-effects.
+.PP
+Therefore, as an exception to the general rule, local($_) will not
+only assign a new value to \f(CW$_\fR, but also remove all existing magic from
+it as well.
+.PP
+\fIParsing of package and variable names\fR
+.IX Subsection "Parsing of package and variable names"
+.PP
+Parsing the names of packages and package variables has changed: 
+multiple adjacent pairs of colons, as in \f(CW\*(C`foo::::bar\*(C'\fR, are now all 
+treated as package separators.
+.PP
+Regardless of this change, the exact parsing of package separators has
+never been guaranteed and is subject to change in future Perl versions.
+.SS "Changes to Syntax or to Perl Operators"
+.IX Subsection "Changes to Syntax or to Perl Operators"
+\fR\f(CI\*(C`given\*(C'\fR\fI return values\fR
+.IX Subsection "given return values"
+.PP
+\&\f(CW\*(C`given\*(C'\fR blocks now return the last evaluated
+expression, or an empty list if the block was exited by \f(CW\*(C`break\*(C'\fR.  Thus you
+can now write:
+.PP
+.Vb 8
+\&    my $type = do {
+\&     given ($num) {
+\&      break     when undef;
+\&      "integer" when /^[+\-]?[0\-9]+$/;
+\&      "float"   when /^[+\-]?[0\-9]+(?:\e.[0\-9]+)?$/;
+\&      "unknown";
+\&     }
+\&    };
+.Ve
+.PP
+See "Return value" in perlsyn for details.
+.PP
+\fIChange in parsing of certain prototypes\fR
+.IX Subsection "Change in parsing of certain prototypes"
+.PP
+Functions declared with the following prototypes now behave correctly as unary
+functions:
+.PP
+.Vb 6
+\&  *
+\&  \e$ \e% \e@ \e* \e&
+\&  \e[...]
+\&  ;$ ;*
+\&  ;\e$ ;\e% etc.
+\&  ;\e[...]
+.Ve
+.PP
+Due to this bug fix [perl #75904], functions
+using the \f(CW\*(C`(*)\*(C'\fR, \f(CW\*(C`(;$)\*(C'\fR and \f(CW\*(C`(;*)\*(C'\fR prototypes
+are parsed with higher precedence than before.  So
+in the following example:
+.PP
+.Vb 2
+\&  sub foo(;$);
+\&  foo $a < $b;
+.Ve
+.PP
+the second line is now parsed correctly as \f(CW\*(C`foo($a) < $b\*(C'\fR, rather than
+\&\f(CW\*(C`foo($a < $b)\*(C'\fR.  This happens when one of these operators is used in
+an unparenthesised argument:
+.PP
+.Vb 10
+\&  < > <= >= lt gt le ge
+\&  == != <=> eq ne cmp ~~
+\&  &
+\&  | ^
+\&  &&
+\&  || //
+\&  .. ...
+\&  ?:
+\&  = += \-= *= etc.
+\&  , =>
+.Ve
+.PP
+\fISmart-matching against array slices\fR
+.IX Subsection "Smart-matching against array slices"
+.PP
+Previously, the following code resulted in a successful match:
+.PP
+.Vb 3
+\&    my @a = qw(a y0 z);
+\&    my @b = qw(a x0 z);
+\&    @a[0 .. $#b] ~~ @b;
+.Ve
+.PP
+This odd behaviour has now been fixed [perl #77468].
+.PP
+\fINegation treats strings differently from before\fR
+.IX Subsection "Negation treats strings differently from before"
+.PP
+The unary negation operator, \f(CW\*(C`\-\*(C'\fR, now treats strings that look like numbers
+as numbers [perl #57706].
+.PP
+\fINegative zero\fR
+.IX Subsection "Negative zero"
+.PP
+Negative zero (\-0.0), when converted to a string, now becomes "0" on all
+platforms.  It used to become "\-0" on some, but "0" on others.
+.PP
+If you still need to determine whether a zero is negative, use
+\&\f(CW\*(C`sprintf("%g", $zero) =~ /^\-/\*(C'\fR or the Data::Float module on CPAN.
+.PP
+\fR\f(CI\*(C`:=\*(C'\fR\fI is now a syntax error\fR
+.IX Subsection ":= is now a syntax error"
+.PP
+Previously \f(CW\*(C`my $pi := 4\*(C'\fR was exactly equivalent to \f(CW\*(C`my $pi : = 4\*(C'\fR,
+with the \f(CW\*(C`:\*(C'\fR being treated as the start of an attribute list, ending before
+the \f(CW\*(C`=\*(C'\fR.  The use of \f(CW\*(C`:=\*(C'\fR to mean \f(CW\*(C`: =\*(C'\fR was deprecated in 5.12.0, and is
+now a syntax error.  This allows future use of \f(CW\*(C`:=\*(C'\fR as a new token.
+.PP
+Outside the core's tests for it, we find no Perl 5 code on CPAN
+using this construction, so we believe that this change will have
+little impact on real-world codebases.
+.PP
+If it is absolutely necessary to have empty attribute lists (for example,
+because of a code generator), simply avoid the error by adding a space before
+the \f(CW\*(C`=\*(C'\fR.
+.PP
+\fIChange in the parsing of identifiers\fR
+.IX Subsection "Change in the parsing of identifiers"
+.PP
+Characters outside the Unicode "XIDStart" set are no longer allowed at the
+beginning of an identifier.  This means that certain accents and marks
+that normally follow an alphabetic character may no longer be the first
+character of an identifier.
+.SS "Threads and Processes"
+.IX Subsection "Threads and Processes"
+\fIDirectory handles not copied to threads\fR
+.IX Subsection "Directory handles not copied to threads"
+.PP
+On systems other than Windows that do not have
+a \f(CW\*(C`fchdir\*(C'\fR function, newly-created threads no
+longer inherit directory handles from their parent threads.  Such programs
+would usually have crashed anyway [perl #75154].
+.PP
+\fR\f(CI\*(C`close\*(C'\fR\fI on shared pipes\fR
+.IX Subsection "close on shared pipes"
+.PP
+To avoid deadlocks, the \f(CW\*(C`close\*(C'\fR function no longer waits for the
+child process to exit if the underlying file descriptor is still
+in use by another thread.  It returns true in such cases.
+.PP
+\fR\f(BIfork()\fR\fI emulation will not wait for signalled children\fR
+.IX Subsection "fork() emulation will not wait for signalled children"
+.PP
+On Windows parent processes would not terminate until all forked
+children had terminated first.  However, \f(CW\*(C`kill("KILL", ...)\*(C'\fR is
+inherently unstable on pseudo-processes, and \f(CW\*(C`kill("TERM", ...)\*(C'\fR
+might not get delivered if the child is blocked in a system call.
+.PP
+To avoid the deadlock and still provide a safe mechanism to terminate
+the hosting process, Perl now no longer waits for children that
+have been sent a SIGTERM signal.  It is up to the parent process to
+\&\fBwaitpid()\fR for these children if child-cleanup processing must be
+allowed to finish.  However, it is also then the responsibility of the
+parent to avoid the deadlock by making sure the child process
+can't be blocked on I/O.
+.PP
+See perlfork for more information about the \fBfork()\fR emulation on
+Windows.
+.SS Configuration
+.IX Subsection "Configuration"
+\fINaming fixes in Policy_sh.SH may invalidate Policy.sh\fR
+.IX Subsection "Naming fixes in Policy_sh.SH may invalidate Policy.sh"
+.PP
+Several long-standing typos and naming confusions in \fIPolicy_sh.SH\fR have
+been fixed, standardizing on the variable names used in \fIconfig.sh\fR.
+.PP
+This will change the behaviour of \fIPolicy.sh\fR if you happen to have been
+accidentally relying on its incorrect behaviour.
+.PP
+\fIPerl source code is read in text mode on Windows\fR
+.IX Subsection "Perl source code is read in text mode on Windows"
+.PP
+Perl scripts used to be read in binary mode on Windows for the benefit
+of the ByteLoader module (which is no longer part of core Perl).  This
+had the side-effect of breaking various operations on the \f(CW\*(C`DATA\*(C'\fR filehandle,
+including \fBseek()\fR/\fBtell()\fR, and even simply reading from \f(CW\*(C`DATA\*(C'\fR after filehandles
+have been flushed by a call to \fBsystem()\fR, backticks, \fBfork()\fR etc.
+.PP
+The default build options for Windows have been changed to read Perl source
+code on Windows in text mode now.  ByteLoader will (hopefully) be updated on
+CPAN to automatically handle this situation [perl #28106].
+.SH Deprecations
+.IX Header "Deprecations"
+See also "Deprecated C APIs".
+.SS "Omitting a space between a regular expression and subsequent word"
+.IX Subsection "Omitting a space between a regular expression and subsequent word"
+Omitting the space between a regular expression operator or
+its modifiers and the following word is deprecated.  For
+example, \f(CW\*(C`m/foo/sand $bar\*(C'\fR is for now still parsed
+as \f(CW\*(C`m/foo/s and $bar\*(C'\fR, but will now issue a warning.
+.ie n .SS """\ec\fIX\fP"""
+.el .SS \f(CW\ec\fP\f(CIX\fP\f(CW\fP
+.IX Subsection "cX"
+The backslash-c construct was designed as a way of specifying
+non-printable characters, but there were no restrictions (on ASCII
+platforms) on what the character following the \f(CW\*(C`c\*(C'\fR could be.  Now,
+a deprecation warning is raised if that character isn't an ASCII character.
+Also, a deprecation warning is raised for \f(CW"\ec{"\fR (which is the same
+as simply saying \f(CW";"\fR).
+.ie n .SS """\eb{"" and ""\eB{"""
+.el .SS "\f(CW""\eb{""\fP and \f(CW""\eB{""\fP"
+.IX Subsection """b{"" and ""B{"""
+In regular expressions, a literal \f(CW"{"\fR immediately following a \f(CW"\eb"\fR
+(not in a bracketed character class) or a \f(CW"\eB{"\fR is now deprecated
+to allow for its future use by Perl itself.
+.SS "Perl 4\-era .pl libraries"
+.IX Subsection "Perl 4-era .pl libraries"
+Perl bundles a handful of library files that predate Perl 5.
+This bundling is now deprecated for most of these files, which are now
+available from CPAN.  The affected files now warn when run, if they were
+installed as part of the core.
+.PP
+This is a mandatory warning, not obeying \fB\-X\fR or lexical warning bits.
+The warning is modelled on that supplied by \fIdeprecate.pm\fR for
+deprecated-in-core \fI.pm\fR libraries.  It points to the specific CPAN
+distribution that contains the \fI.pl\fR libraries.  The CPAN versions, of
+course, do not generate the warning.
+.ie n .SS "List assignment to $["
+.el .SS "List assignment to \f(CW$[\fP"
+.IX Subsection "List assignment to $["
+Assignment to \f(CW$[\fR was deprecated and started to give warnings in
+Perl version 5.12.0.  This version of Perl (5.14) now also emits a warning 
+when assigning to \f(CW$[\fR in list context.  This fixes an oversight in 5.12.0.
+.SS "Use of qw(...) as parentheses"
+.IX Subsection "Use of qw(...) as parentheses"
+Historically the parser fooled itself into thinking that \f(CWqw(...)\fR literals
+were always enclosed in parentheses, and as a result you could sometimes omit
+parentheses around them:
+.PP
+.Vb 1
+\&    for $x qw(a b c) { ... }
+.Ve
+.PP
+The parser no longer lies to itself in this way.  Wrap the list literal in
+parentheses like this:
+.PP
+.Vb 1
+\&    for $x (qw(a b c)) { ... }
+.Ve
+.PP
+This is being deprecated because the parentheses in \f(CW\*(C`for $i (1,2,3) { ... }\*(C'\fR
+are not part of expression syntax.  They are part of the statement
+syntax, with the \f(CW\*(C`for\*(C'\fR statement wanting literal parentheses.
+The synthetic parentheses that a \f(CW\*(C`qw\*(C'\fR expression acquired were only
+intended to be treated as part of expression syntax.
+.PP
+Note that this does not change the behaviour of cases like:
+.PP
+.Vb 2
+\&    use POSIX qw(setlocale localeconv);
+\&    our @EXPORT = qw(foo bar baz);
+.Ve
+.PP
+where parentheses were never required around the expression.
+.ie n .SS """\eN{BELL}"""
+.el .SS \f(CW\eN{BELL}\fP
+.IX Subsection "N{BELL}"
+This is because Unicode is using that name for a different character.
+See "Unicode Version 6.0 is now supported (mostly)" for more
+explanation.
+.ie n .SS """?PATTERN?"""
+.el .SS \f(CW?PATTERN?\fP
+.IX Subsection "?PATTERN?"
+\&\f(CW\*(C`?PATTERN?\*(C'\fR (without the initial \f(CW\*(C`m\*(C'\fR) has been deprecated and now produces
+a warning.  This is to allow future use of \f(CW\*(C`?\*(C'\fR in new operators.
+The match-once functionality is still available as \f(CW\*(C`m?PATTERN?\*(C'\fR.
+.SS "Tie functions on scalars holding typeglobs"
+.IX Subsection "Tie functions on scalars holding typeglobs"
+Calling a tie function (\f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR, \f(CW\*(C`untie\*(C'\fR) with a scalar argument
+acts on a filehandle if the scalar happens to hold a typeglob.
+.PP
+This is a long-standing bug that will be removed in Perl 5.16, as
+there is currently no way to tie the scalar itself when it holds
+a typeglob, and no way to untie a scalar that has had a typeglob
+assigned to it.
+.PP
+Now there is a deprecation warning whenever a tie
+function is used on a handle without an explicit \f(CW\*(C`*\*(C'\fR.
+.SS "User-defined case-mapping"
+.IX Subsection "User-defined case-mapping"
+This feature is being deprecated due to its many issues, as documented in
+"User-Defined Case Mappings (for serious hackers only)" in perlunicode.
+This feature will be removed in Perl 5.16.  Instead use the CPAN module
+Unicode::Casing, which provides improved functionality.
+.SS "Deprecated modules"
+.IX Subsection "Deprecated modules"
+The following module will be removed from the core distribution in a
+future release, and should be installed from CPAN instead.  Distributions
+on CPAN that require this should add it to their prerequisites.  The
+core version of these module now issues a deprecation warning.
+.PP
+If you ship a packaged version of Perl, either alone or as part of a
+larger system, then you should carefully consider the repercussions of
+core module deprecations.  You may want to consider shipping your default
+build of Perl with a package for the deprecated module that
+installs into \f(CW\*(C`vendor\*(C'\fR or \f(CW\*(C`site\*(C'\fR Perl library directories.  This will
+inhibit the deprecation warnings.
+.PP
+Alternatively, you may want to consider patching \fIlib/deprecate.pm\fR
+to provide deprecation warnings specific to your packaging system
+or distribution of Perl, consistent with how your packaging system
+or distribution manages a staged transition from a release where the
+installation of a single package provides the given functionality, to
+a later release where the system administrator needs to know to install
+multiple packages to get that same functionality.
+.PP
+You can silence these deprecation warnings by installing the module
+in question from CPAN.  To install the latest version of it by role
+rather than by name, just install \f(CW\*(C`Task::Deprecations::5_14\*(C'\fR.
+.IP Devel::DProf 4
+.IX Item "Devel::DProf"
+We strongly recommend that you install and use Devel::NYTProf instead
+of Devel::DProf, as Devel::NYTProf offers significantly
+improved profiling and reporting.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.SS """Safe signals"" optimisation"
+.IX Subsection """Safe signals"" optimisation"
+Signal dispatch has been moved from the runloop into control ops.
+This should give a few percent speed increase, and eliminates nearly
+all the speed penalty caused by the introduction of "safe signals"
+in 5.8.0.  Signals should still be dispatched within the same
+statement as they were previously.  If this does \fInot\fR happen, or
+if you find it possible to create uninterruptible loops, this is a
+bug, and reports are encouraged of how to recreate such issues.
+.SS "Optimisation of \fBshift()\fP and \fBpop()\fP calls without arguments"
+.IX Subsection "Optimisation of shift() and pop() calls without arguments"
+Two fewer OPs are used for \fBshift()\fR and \fBpop()\fR calls with no argument (with
+implicit \f(CW@_\fR).  This change makes \fBshift()\fR 5% faster than \f(CW\*(C`shift @_\*(C'\fR
+on non-threaded perls, and 25% faster on threaded ones.
+.SS "Optimisation of regexp engine string comparison work"
+.IX Subsection "Optimisation of regexp engine string comparison work"
+The \f(CW\*(C`foldEQ_utf8\*(C'\fR API function for case-insensitive comparison of strings (which
+is used heavily by the regexp engine) was substantially refactored and
+optimised \-\- and its documentation much improved as a free bonus.
+.SS "Regular expression compilation speed-up"
+.IX Subsection "Regular expression compilation speed-up"
+Compiling regular expressions has been made faster when upgrading
+the regex to utf8 is necessary but this isn't known when the compilation begins.
+.SS "String appending is 100 times faster"
+.IX Subsection "String appending is 100 times faster"
+When doing a lot of string appending, perls built to use the system's
+\&\f(CW\*(C`malloc\*(C'\fR could end up allocating a lot more memory than needed in a
+inefficient way.
+.PP
+\&\f(CW\*(C`sv_grow\*(C'\fR, the function used to allocate more memory if necessary
+when appending to a string, has been taught to round up the memory
+it requests to a certain geometric progression, making it much faster on
+certain platforms and configurations.  On Win32, it's now about 100 times
+faster.
+.ie n .SS "Eliminate ""PL_*"" accessor functions under ithreads"
+.el .SS "Eliminate \f(CWPL_*\fP accessor functions under ithreads"
+.IX Subsection "Eliminate PL_* accessor functions under ithreads"
+When \f(CW\*(C`MULTIPLICITY\*(C'\fR was first developed, and interpreter state moved into
+an interpreter struct, thread\- and interpreter-local \f(CW\*(C`PL_*\*(C'\fR variables
+were defined as macros that called accessor functions (returning the
+address of the value) outside the Perl core.  The intent was to allow
+members within the interpreter struct to change size without breaking
+binary compatibility, so that bug fixes could be merged to a maintenance
+branch that necessitated such a size change.  This mechanism was redundant
+and penalised well-behaved code.  It has been removed.
+.SS "Freeing weak references"
+.IX Subsection "Freeing weak references"
+When there are many weak references to an object, freeing that object
+can under some circumstances take O(\fIN*N\fR) time to free, where
+\&\fIN\fR is the number of references.  The circumstances in which this can happen
+have been reduced [perl #75254]
+.SS "Lexical array and hash assignments"
+.IX Subsection "Lexical array and hash assignments"
+An earlier optimisation to speed up \f(CW\*(C`my @array = ...\*(C'\fR and
+\&\f(CW\*(C`my %hash = ...\*(C'\fR assignments caused a bug and was disabled in Perl 5.12.0.
+.PP
+Now we have found another way to speed up these assignments [perl #82110].
+.ie n .SS "@_ uses less memory"
+.el .SS "\f(CW@_\fP uses less memory"
+.IX Subsection "@_ uses less memory"
+Previously, \f(CW@_\fR was allocated for every subroutine at compile time with
+enough space for four entries.  Now this allocation is done on demand when
+the subroutine is called [perl #72416].
+.SS "Size optimisations to SV and HV structures"
+.IX Subsection "Size optimisations to SV and HV structures"
+\&\f(CW\*(C`xhv_fill\*(C'\fR has been eliminated from \f(CW\*(C`struct xpvhv\*(C'\fR, saving 1 IV per hash and
+on some systems will cause \f(CW\*(C`struct xpvhv\*(C'\fR to become cache-aligned.  To avoid
+this memory saving causing a slowdown elsewhere, boolean use of \f(CW\*(C`HvFILL\*(C'\fR
+now calls \f(CW\*(C`HvTOTALKEYS\*(C'\fR instead (which is equivalent), so while the fill
+data when actually required are now calculated on demand, cases when
+this needs to be done should be rare.
+.PP
+The order of structure elements in SV bodies has changed.  Effectively,
+the NV slot has swapped location with STASH and MAGIC.  As all access to
+SV members is via macros, this should be completely transparent.  This
+change allows the space saving for PVHVs documented above, and may reduce
+the memory allocation needed for PVIVs on some architectures.
+.PP
+\&\f(CW\*(C`XPV\*(C'\fR, \f(CW\*(C`XPVIV\*(C'\fR, and \f(CW\*(C`XPVNV\*(C'\fR now allocate only the parts of the \f(CW\*(C`SV\*(C'\fR body
+they actually use, saving some space.
+.PP
+Scalars containing regular expressions now allocate only the part of the \f(CW\*(C`SV\*(C'\fR
+body they actually use, saving some space.
+.SS "Memory consumption improvements to Exporter"
+.IX Subsection "Memory consumption improvements to Exporter"
+The \f(CW@EXPORT_FAIL\fR AV is no longer created unless needed, hence neither is
+the typeglob backing it.  This saves about 200 bytes for every package that
+uses Exporter but doesn't use this functionality.
+.SS "Memory savings for weak references"
+.IX Subsection "Memory savings for weak references"
+For weak references, the common case of just a single weak reference
+per referent has been optimised to reduce the storage required.  In this
+case it saves the equivalent of one small Perl array per referent.
+.ie n .SS """%+"" and ""%\-"" use less memory"
+.el .SS "\f(CW%+\fP and \f(CW%\-\fP use less memory"
+.IX Subsection "%+ and %- use less memory"
+The bulk of the \f(CW\*(C`Tie::Hash::NamedCapture\*(C'\fR module used to be in the Perl
+core.  It has now been moved to an XS module to reduce overhead for
+programs that do not use \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR.
+.SS "Multiple small improvements to threads"
+.IX Subsection "Multiple small improvements to threads"
+The internal structures of threading now make fewer API calls and fewer
+allocations, resulting in noticeably smaller object code.  Additionally,
+many thread context checks have been deferred so they're done only 
+as needed (although this is only possible for non-debugging builds).
+.SS "Adjacent pairs of nextstate opcodes are now optimized away"
+.IX Subsection "Adjacent pairs of nextstate opcodes are now optimized away"
+Previously, in code such as
+.PP
+.Vb 1
+\&    use constant DEBUG => 0;
+\&
+\&    sub GAK {
+\&        warn if DEBUG;
+\&        print "stuff\en";
+\&    }
+.Ve
+.PP
+the ops for \f(CW\*(C`warn if DEBUG\*(C'\fR would be folded to a \f(CW\*(C`null\*(C'\fR op (\f(CW\*(C`ex\-const\*(C'\fR), but
+the \f(CW\*(C`nextstate\*(C'\fR op would remain, resulting in a runtime op dispatch of
+\&\f(CW\*(C`nextstate\*(C'\fR, \f(CW\*(C`nextstate\*(C'\fR, etc.
+.PP
+The execution of a sequence of \f(CW\*(C`nextstate\*(C'\fR ops is indistinguishable from just
+the last \f(CW\*(C`nextstate\*(C'\fR op so the peephole optimizer now eliminates the first of
+a pair of \f(CW\*(C`nextstate\*(C'\fR ops except when the first carries a label, since labels
+must not be eliminated by the optimizer, and label usage isn't conclusively known
+at compile time.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+CPAN::Meta::YAML 0.003 has been added as a dual-life module.  It supports a
+subset of YAML sufficient for reading and writing \fIMETA.yml\fR and \fIMYMETA.yml\fR files
+included with CPAN distributions or generated by the module installation
+toolchain.  It should not be used for any other general YAML parsing or
+generation task.
+.IP \(bu 4
+CPAN::Meta version 2.110440 has been added as a dual-life module.  It
+provides a standard library to read, interpret and write CPAN distribution
+metadata files (like \fIMETA.json\fR and \fIMETA.yml\fR) that describe a
+distribution, its contents, and the requirements for building it and
+installing it.  The latest CPAN distribution metadata specification is
+included as CPAN::Meta::Spec and notes on changes in the specification
+over time are given in CPAN::Meta::History.
+.IP \(bu 4
+HTTP::Tiny 0.012 has been added as a dual-life module.  It is a very
+small, simple HTTP/1.1 client designed for simple GET requests and file
+mirroring.  It has been added so that \fICPAN.pm\fR and CPANPLUS can
+"bootstrap" HTTP access to CPAN using pure Perl without relying on external
+binaries like \fBcurl\fR\|(1) or \fBwget\fR\|(1).
+.IP \(bu 4
+JSON::PP 2.27105 has been added as a dual-life module to allow CPAN
+clients to read \fIMETA.json\fR files in CPAN distributions.
+.IP \(bu 4
+Module::Metadata 1.000004 has been added as a dual-life module.  It gathers
+package and POD information from Perl module files.  It is a standalone module
+based on Module::Build::ModuleInfo for use by other module installation
+toolchain components.  Module::Build::ModuleInfo has been deprecated in
+favor of this module instead.
+.IP \(bu 4
+Perl::OSType 1.002 has been added as a dual-life module.  It maps Perl
+operating system names (like "dragonfly" or "MSWin32") to more generic types
+with standardized names (like "Unix" or "Windows").  It has been refactored
+out of Module::Build and ExtUtils::CBuilder and consolidates such mappings into
+a single location for easier maintenance.
+.IP \(bu 4
+The following modules were added by the Unicode::Collate 
+upgrade.  See below for details.
+.Sp
+Unicode::Collate::CJK::Big5
+.Sp
+Unicode::Collate::CJK::GB2312
+.Sp
+Unicode::Collate::CJK::JISX0208
+.Sp
+Unicode::Collate::CJK::Korean
+.Sp
+Unicode::Collate::CJK::Pinyin
+.Sp
+Unicode::Collate::CJK::Stroke
+.IP \(bu 4
+Version::Requirements version 0.101020 has been added as a dual-life
+module.  It provides a standard library to model and manipulates module
+prerequisites and version constraints defined in CPAN::Meta::Spec.
+.SS "Updated Modules and Pragma"
+.IX Subsection "Updated Modules and Pragma"
+.IP \(bu 4
+attributes has been upgraded from version 0.12 to 0.14.
+.IP \(bu 4
+Archive::Extract has been upgraded from version 0.38 to 0.48.
+.Sp
+Updates since 0.38 include: a safe print method that guards
+Archive::Extract from changes to \f(CW\*(C`$\e\*(C'\fR; a fix to the tests when run in core
+Perl; support for TZ files; a modification for the lzma
+logic to favour IO::Uncompress::Unlzma; and a fix
+for an issue with NetBSD-current and its new \fBunzip\fR\|(1)
+executable.
+.IP \(bu 4
+Archive::Tar has been upgraded from version 1.54 to 1.76.
+.Sp
+Important changes since 1.54 include the following:
+.RS 4
+.IP \(bu 4
+Compatibility with busybox implementations of \fBtar\fR\|(1).
+.IP \(bu 4
+A fix so that \fBwrite()\fR and \fBcreate_archive()\fR
+close only filehandles they themselves opened.
+.IP \(bu 4
+A bug was fixed regarding the exit code of extract_archive.
+.IP \(bu 4
+The \fBptar\fR\|(1) utility has a new option to allow safe creation of
+tarballs without world-writable files on Windows, allowing those
+archives to be uploaded to CPAN.
+.IP \(bu 4
+A new \fBptargrep\fR\|(1) utility for using regular expressions against 
+the contents of files in a tar archive.
+.IP \(bu 4
+pax extended headers are now skipped.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 0.87 to 0.89.
+.IP \(bu 4
+autodie has been upgraded from version 2.06_01 to 2.1001.
+.IP \(bu 4
+AutoLoader has been upgraded from version 5.70 to 5.71.
+.IP \(bu 4
+The B module has been upgraded from version 1.23 to 1.29.
+.Sp
+It no longer crashes when taking apart a \f(CW\*(C`y///\*(C'\fR containing characters
+outside the octet range or compiled in a \f(CW\*(C`use utf8\*(C'\fR scope.
+.Sp
+The size of the shared object has been reduced by about 40%, with no
+reduction in functionality.
+.IP \(bu 4
+B::Concise has been upgraded from version 0.78 to 0.83.
+.Sp
+B::Concise marks \fBrv2sv()\fR, \fBrv2av()\fR, and \fBrv2hv()\fR ops with the new
+\&\f(CW\*(C`OPpDEREF\*(C'\fR flag as "DREFed".
+.Sp
+It no longer produces mangled output with the \fB\-tree\fR option
+[perl #80632].
+.IP \(bu 4
+B::Debug has been upgraded from version 1.12 to 1.16.
+.IP \(bu 4
+B::Deparse has been upgraded from version 0.96 to 1.03.
+.Sp
+The deparsing of a \f(CW\*(C`nextstate\*(C'\fR op has changed when it has both a
+change of package relative to the previous nextstate, or a change of
+\&\f(CW\*(C`%^H\*(C'\fR or other state and a label.  The label was previously emitted
+first, but is now emitted last (5.12.1).
+.Sp
+The \f(CW\*(C`no 5.13.2\*(C'\fR or similar form is now correctly handled by B::Deparse
+(5.12.3).
+.Sp
+B::Deparse now properly handles the code that applies a conditional
+pattern match against implicit \f(CW$_\fR as it was fixed in [perl #20444].
+.Sp
+Deparsing of \f(CW\*(C`our\*(C'\fR followed by a variable with funny characters
+(as permitted under the \f(CW\*(C`use utf8\*(C'\fR pragma) has also been fixed [perl #33752].
+.IP \(bu 4
+B::Lint has been upgraded from version 1.11_01 to 1.13.
+.IP \(bu 4
+base has been upgraded from version 2.15 to 2.16.
+.IP \(bu 4
+Benchmark has been upgraded from version 1.11 to 1.12.
+.IP \(bu 4
+bignum has been upgraded from version 0.23 to 0.27.
+.IP \(bu 4
+Carp has been upgraded from version 1.15 to 1.20.
+.Sp
+Carp now detects incomplete \fBcaller()\fR
+overrides and avoids using bogus \f(CW@DB::args\fR.  To provide backtraces,
+Carp relies on particular behaviour of the \fBcaller()\fR builtin.
+Carp now detects if other code has overridden this with an
+incomplete implementation, and modifies its backtrace accordingly.
+Previously incomplete overrides would cause incorrect values in
+backtraces (best case), or obscure fatal errors (worst case).
+.Sp
+This fixes certain cases of "Bizarre copy of ARRAY" caused by modules
+overriding \fBcaller()\fR incorrectly (5.12.2).
+.Sp
+It now also avoids using regular expressions that cause Perl to
+load its Unicode tables, so as to avoid the "BEGIN not safe after
+errors" error that ensue if there has been a syntax error
+[perl #82854].
+.IP \(bu 4
+CGI has been upgraded from version 3.48 to 3.52.
+.Sp
+This provides the following security fixes: the MIME boundary in 
+\&\fBmultipart_init()\fR is now random and the handling of 
+newlines embedded in header values has been improved.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.024 to 2.033.
+.Sp
+It has been updated to use \fBbzip2\fR\|(1) 1.0.6.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.024 to 2.033.
+.IP \(bu 4
+constant has been upgraded from version 1.20 to 1.21.
+.Sp
+Unicode constants work once more.  They have been broken since Perl 5.10.0
+[CPAN RT #67525].
+.IP \(bu 4
+CPAN has been upgraded from version 1.94_56 to 1.9600.
+.Sp
+Major highlights:
+.RS 4
+.IP \(bu 4
+much less configuration dialog hassle
+.IP \(bu 4
+support for \fIMETA/MYMETA.json\fR
+.IP \(bu 4
+support for local::lib
+.IP \(bu 4
+support for HTTP::Tiny to reduce the dependency on FTP sites
+.IP \(bu 4
+automatic mirror selection
+.IP \(bu 4
+iron out all known bugs in configure_requires
+.IP \(bu 4
+support for distributions compressed with \fBbzip2\fR\|(1)
+.IP \(bu 4
+allow \fIFoo/Bar.pm\fR on the command line to mean \f(CW\*(C`Foo::Bar\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+CPANPLUS has been upgraded from version 0.90 to 0.9103.
+.Sp
+A change to \fIcpanp-run-perl\fR
+resolves RT #55964 <http://rt.cpan.org/Public/Bug/Display.html?id=55964>
+and RT #57106 <http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both
+of which related to failures to install distributions that use
+\&\f(CW\*(C`Module::Install::DSL\*(C'\fR (5.12.2).
+.Sp
+A dependency on Config was not recognised as a
+core module dependency.  This has been fixed.
+.Sp
+CPANPLUS now includes support for \fIMETA.json\fR and \fIMYMETA.json\fR.
+.IP \(bu 4
+CPANPLUS::Dist::Build has been upgraded from version 0.46 to 0.54.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.125 to 2.130_02.
+.Sp
+The indentation used to be off when \f(CW$Data::Dumper::Terse\fR was set.  This
+has been fixed [perl #73604].
+.Sp
+This upgrade also fixes a crash when using custom sort functions that might
+cause the stack to change [perl #74170].
+.Sp
+Dumpxs no longer crashes with globs returned by \f(CW*$io_ref\fR
+[perl #72332].
+.IP \(bu 4
+DB_File has been upgraded from version 1.820 to 1.821.
+.IP \(bu 4
+DBM_Filter has been upgraded from version 0.03 to 0.04.
+.IP \(bu 4
+Devel::DProf has been upgraded from version 20080331.00 to 20110228.00.
+.Sp
+Merely loading Devel::DProf now no longer triggers profiling to start.
+Both \f(CW\*(C`use Devel::DProf\*(C'\fR and \f(CW\*(C`perl \-d:DProf ...\*(C'\fR behave as before and start
+the profiler.
+.Sp
+\&\fBNOTE\fR: Devel::DProf is deprecated and will be removed from a future
+version of Perl.  We strongly recommend that you install and use
+Devel::NYTProf instead, as it offers significantly improved
+profiling and reporting.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.04 to 1.07.
+.IP \(bu 4
+Devel::SelfStubber has been upgraded from version 1.03 to 1.05.
+.IP \(bu 4
+diagnostics has been upgraded from version 1.19 to 1.22.
+.Sp
+It now renders pod links slightly better, and has been taught to find
+descriptions for messages that share their descriptions with other
+messages.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.39 to 2.51.
+.Sp
+It is now safe to use this module in combination with threads.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.47 to 5.61.
+.Sp
+\&\f(CW\*(C`shasum\*(C'\fR now more closely mimics \fBsha1sum\fR\|(1)/\fBmd5sum\fR\|(1).
+.Sp
+\&\f(CW\*(C`addfile\*(C'\fR accepts all POSIX filenames.
+.Sp
+New SHA\-512/224 and SHA\-512/256 transforms (ref. NIST Draft FIPS 180\-4
+[February 2011])
+.IP \(bu 4
+DirHandle has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+Dumpvalue has been upgraded from version 1.13 to 1.16.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.10 to 1.13.
+.Sp
+It fixes a buffer overflow when passed a very long file name.
+.Sp
+It no longer inherits from AutoLoader; hence it no longer
+produces weird error messages for unsuccessful method calls on classes that
+inherit from DynaLoader [perl #84358].
+.IP \(bu 4
+Encode has been upgraded from version 2.39 to 2.42.
+.Sp
+Now, all 66 Unicode non-characters are treated the same way U+FFFF has
+always been treated: in cases when it was disallowed, all 66 are
+disallowed, and in cases where it warned, all 66 warn.
+.IP \(bu 4
+Env has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+Errno has been upgraded from version 1.11 to 1.13.
+.Sp
+The implementation of Errno has been refactored to use about 55% less memory.
+.Sp
+On some platforms with unusual header files, like Win32 \fBgcc\fR\|(1) using \f(CW\*(C`mingw64\*(C'\fR
+headers, some constants that weren't actually error numbers have been exposed
+by Errno.  This has been fixed [perl #77416].
+.IP \(bu 4
+Exporter has been upgraded from version 5.64_01 to 5.64_03.
+.Sp
+Exporter no longer overrides \f(CW$SIG{_\|_WARN_\|_}\fR [perl #74472]
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.27 to 0.280203.
+.IP \(bu 4
+ExtUtils::Command has been upgraded from version 1.16 to 1.17.
+.IP \(bu 4
+ExtUtils::Constant has been upgraded from 0.22 to 0.23.
+.Sp
+The AUTOLOAD helper code generated by \f(CW\*(C`ExtUtils::Constant::ProxySubs\*(C'\fR
+can now \fBcroak()\fR for missing constants, or generate a complete \f(CW\*(C`AUTOLOAD\*(C'\fR
+subroutine in XS, allowing simplification of many modules that use it
+(Fcntl, File::Glob, GDBM_File, I18N::Langinfo, POSIX,
+Socket).
+.Sp
+ExtUtils::Constant::ProxySubs can now optionally push the names of all
+constants onto the package's \f(CW@EXPORT_OK\fR.
+.IP \(bu 4
+ExtUtils::Install has been upgraded from version 1.55 to 1.56.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 6.56 to 6.57_05.
+.IP \(bu 4
+ExtUtils::Manifest has been upgraded from version 1.57 to 1.58.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 2.21 to 2.2210.
+.IP \(bu 4
+Fcntl has been upgraded from version 1.06 to 1.11.
+.IP \(bu 4
+File::Basename has been upgraded from version 2.78 to 2.82.
+.IP \(bu 4
+File::CheckTree has been upgraded from version 4.4 to 4.41.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.17 to 2.21.
+.IP \(bu 4
+File::DosGlob has been upgraded from version 1.01 to 1.04.
+.Sp
+It allows patterns containing literal parentheses: they no longer need to
+be escaped.  On Windows, it no longer
+adds an extra \fI./\fR to file names
+returned when the pattern is a relative glob with a drive specification,
+like \fIC:*.pl\fR [perl #71712].
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.24 to 0.32.
+.Sp
+HTTP::Lite is now supported for the "http" scheme.
+.Sp
+The \fBfetch\fR\|(1) utility is supported on FreeBSD, NetBSD, and
+Dragonfly BSD for the \f(CW\*(C`http\*(C'\fR and \f(CW\*(C`ftp\*(C'\fR schemes.
+.IP \(bu 4
+File::Find has been upgraded from version 1.15 to 1.19.
+.Sp
+It improves handling of backslashes on Windows, so that paths like
+\&\fIC:\edir\e/file\fR are no longer generated [perl #71710].
+.IP \(bu 4
+File::Glob has been upgraded from version 1.07 to 1.12.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.31 to 3.33.
+.Sp
+Several portability fixes were made in File::Spec::VMS: a colon is now
+recognized as a delimiter in native filespecs; caret-escaped delimiters are
+recognized for better handling of extended filespecs; \fBcatpath()\fR returns
+an empty directory rather than the current directory if the input directory
+name is empty; and \fBabs2rel()\fR properly handles Unix-style input (5.12.2).
+.IP \(bu 4
+File::stat has been upgraded from 1.02 to 1.05.
+.Sp
+The \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR file test operators now work correctly when run
+by the superuser.
+.IP \(bu 4
+Filter::Simple has been upgraded from version 0.84 to 0.86.
+.IP \(bu 4
+GDBM_File has been upgraded from 1.10 to 1.14.
+.Sp
+This fixes a memory leak when DBM filters are used.
+.IP \(bu 4
+Hash::Util has been upgraded from 0.07 to 0.11.
+.Sp
+Hash::Util no longer emits spurious "uninitialized" warnings when
+recursively locking hashes that have undefined values [perl #74280].
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.04 to 1.09.
+.IP \(bu 4
+I18N::Collate has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.03 to 0.08.
+.Sp
+\&\fBlanginfo()\fR now defaults to using \f(CW$_\fR if there is no argument given, just
+as the documentation has always claimed.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.35 to 0.35_01.
+.IP \(bu 4
+if has been upgraded from version 0.05 to 0.0601.
+.IP \(bu 4
+IO has been upgraded from version 1.25_02 to 1.25_04.
+.Sp
+This version of IO includes a new IO::Select, which now allows IO::Handle
+objects (and objects in derived classes) to be removed from an IO::Select set
+even if the underlying file descriptor is closed or invalid.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.54 to 0.70.
+.Sp
+Resolves an issue with splitting Win32 command lines.  An argument
+consisting of the single character "0" used to be omitted (CPAN RT #62961).
+.IP \(bu 4
+IPC::Open3 has been upgraded from 1.05 to 1.09.
+.Sp
+\&\fBopen3()\fR now produces an error if the \f(CW\*(C`exec\*(C'\fR call fails, allowing this
+condition to be distinguished from a child process that exited with a
+non-zero status [perl #72016].
+.Sp
+The internal \fBxclose()\fR routine now knows how to handle file descriptors as
+documented, so duplicating \f(CW\*(C`STDIN\*(C'\fR in a child process using its file
+descriptor now works [perl #76474].
+.IP \(bu 4
+IPC::SysV has been upgraded from version 2.01 to 2.03.
+.IP \(bu 4
+lib has been upgraded from version 0.62 to 0.63.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.14 to 1.19.
+.Sp
+Locale::Maketext now supports external caches.
+.Sp
+This upgrade also fixes an infinite loop in
+\&\f(CWLocale::Maketext::Guts::_compile()\fR when
+working with tainted values (CPAN RT #40727).
+.Sp
+\&\f(CW\*(C`\->maketext\*(C'\fR calls now back up and restore \f(CW$@\fR so error
+messages are not suppressed (CPAN RT #34182).
+.IP \(bu 4
+Log::Message has been upgraded from version 0.02 to 0.04.
+.IP \(bu 4
+Log::Message::Simple has been upgraded from version 0.06 to 0.08.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.89_01 to 1.994.
+.Sp
+This fixes, among other things, incorrect results when computing binomial
+coefficients [perl #77640].
+.Sp
+It also prevents \f(CWsqrt($int)\fR from crashing under \f(CW\*(C`use bigrat\*(C'\fR.
+[perl #73534].
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.19 to 0.28.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.24 to 0.26_02.
+.IP \(bu 4
+Memoize has been upgraded from version 1.01_03 to 1.02.
+.IP \(bu 4
+MIME::Base64 has been upgraded from 3.08 to 3.13.
+.Sp
+Includes new functions to calculate the length of encoded and decoded
+base64 strings.
+.Sp
+Now provides \fBencode_base64url()\fR and \fBdecode_base64url()\fR functions to process
+the base64 scheme for "URL applications".
+.IP \(bu 4
+Module::Build has been upgraded from version 0.3603 to 0.3800.
+.Sp
+A notable change is the deprecation of several modules.
+Module::Build::Version has been deprecated and Module::Build now
+relies on the version pragma directly.  Module::Build::ModuleInfo has
+been deprecated in favor of a standalone copy called Module::Metadata.
+Module::Build::YAML has been deprecated in favor of CPAN::Meta::YAML.
+.Sp
+Module::Build now also generates \fIMETA.json\fR and \fIMYMETA.json\fR files
+in accordance with version 2 of the CPAN distribution metadata specification,
+CPAN::Meta::Spec.  The older format \fIMETA.yml\fR and \fIMYMETA.yml\fR files are
+still generated.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 2.29 to 2.47.
+.Sp
+Besides listing the updated core modules of this release, it also stops listing
+the \f(CW\*(C`Filespec\*(C'\fR module.  That module never existed in core.  The scripts
+generating Module::CoreList confused it with VMS::Filespec, which actually
+is a core module as of Perl 5.8.7.
+.IP \(bu 4
+Module::Load has been upgraded from version 0.16 to 0.18.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded from version 0.34 to 0.44.
+.IP \(bu 4
+The mro pragma has been upgraded from version 1.02 to 1.07.
+.IP \(bu 4
+NDBM_File has been upgraded from version 1.08 to 1.12.
+.Sp
+This fixes a memory leak when DBM filters are used.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.36 to 2.38.
+.IP \(bu 4
+NEXT has been upgraded from version 0.64 to 0.65.
+.IP \(bu 4
+Object::Accessor has been upgraded from version 0.36 to 0.38.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.07 to 1.10.
+.Sp
+This fixes a memory leak when DBM filters are used.
+.IP \(bu 4
+Opcode has been upgraded from version 1.15 to 1.18.
+.IP \(bu 4
+The overload pragma has been upgraded from 1.10 to 1.13.
+.Sp
+\&\f(CW\*(C`overload::Method\*(C'\fR can now handle subroutines that are themselves blessed
+into overloaded classes [perl #71998].
+.Sp
+The documentation has greatly improved.  See "Documentation" below.
+.IP \(bu 4
+Params::Check has been upgraded from version 0.26 to 0.28.
+.IP \(bu 4
+The parent pragma has been upgraded from version 0.223 to 0.225.
+.IP \(bu 4
+Parse::CPAN::Meta has been upgraded from version 1.40 to 1.4401.
+.Sp
+The latest Parse::CPAN::Meta can now read YAML and JSON files using
+CPAN::Meta::YAML and JSON::PP, which are now part of the Perl core.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.12 to 0.14.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from 0.07 to 0.11.
+.Sp
+A \fBread()\fR after a \fBseek()\fR beyond the end of the string no longer thinks it
+has data to read [perl #78716].
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.09 to 0.11.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.09 to 1.11.
+.IP \(bu 4
+Pod::LaTeX has been upgraded from version 0.58 to 0.59.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.15_02 to 3.15_03.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.13 to 3.16.
+.IP \(bu 4
+POSIX has been upgraded from 1.19 to 1.24.
+.Sp
+It now includes constants for POSIX signal constants.
+.IP \(bu 4
+The re pragma has been upgraded from version 0.11 to 0.18.
+.Sp
+The \f(CW\*(C`use re \*(Aq/flags\*(Aq\*(C'\fR subpragma is new.
+.Sp
+The \fBregmust()\fR function used to crash when called on a regular expression
+belonging to a pluggable engine.  Now it croaks instead.
+.Sp
+\&\fBregmust()\fR no longer leaks memory.
+.IP \(bu 4
+Safe has been upgraded from version 2.25 to 2.29.
+.Sp
+Coderefs returned by \fBreval()\fR and \fBrdo()\fR are now wrapped via
+\&\fBwrap_code_refs()\fR (5.12.1).
+.Sp
+This fixes a possible infinite loop when looking for coderefs.
+.Sp
+It adds several \f(CW\*(C`version::vxs::*\*(C'\fR routines to the default share.
+.IP \(bu 4
+SDBM_File has been upgraded from version 1.06 to 1.09.
+.IP \(bu 4
+SelfLoader has been upgraded from 1.17 to 1.18.
+.Sp
+It now works in taint mode [perl #72062].
+.IP \(bu 4
+The sigtrap pragma has been upgraded from version 1.04 to 1.05.
+.Sp
+It no longer tries to modify read-only arguments when generating a
+backtrace [perl #72340].
+.IP \(bu 4
+Socket has been upgraded from version 1.87 to 1.94.
+.Sp
+See "Improved IPv6 support" above.
+.IP \(bu 4
+Storable has been upgraded from version 2.22 to 2.27.
+.Sp
+Includes performance improvement for overloaded classes.
+.Sp
+This adds support for serialising code references that contain UTF\-8 strings
+correctly.  The Storable minor version
+number changed as a result, meaning that
+Storable users who set \f(CW$Storable::accept_future_minor\fR to a \f(CW\*(C`FALSE\*(C'\fR value
+will see errors (see "FORWARD COMPATIBILITY" in Storable for more details).
+.Sp
+Freezing no longer gets confused if the Perl stack gets reallocated
+during freezing [perl #80074].
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.11 to 1.16.
+.IP \(bu 4
+Term::ANSIColor has been upgraded from version 2.02 to 3.00.
+.IP \(bu 4
+Term::UI has been upgraded from version 0.20 to 0.26.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.17 to 3.23.
+.IP \(bu 4
+Test::Simple has been upgraded from version 0.94 to 0.98.
+.Sp
+Among many other things, subtests without a \f(CW\*(C`plan\*(C'\fR or \f(CW\*(C`no_plan\*(C'\fR now have an
+implicit \fBdone_testing()\fR added to them.
+.IP \(bu 4
+Thread::Semaphore has been upgraded from version 2.09 to 2.12.
+.Sp
+It provides two new methods that give more control over the decrementing of
+semaphores: \f(CW\*(C`down_nb\*(C'\fR and \f(CW\*(C`down_force\*(C'\fR.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 2.11 to 2.12.
+.IP \(bu 4
+The threads pragma has been upgraded from version 1.75 to 1.83.
+.IP \(bu 4
+The threads::shared pragma has been upgraded from version 1.32 to 1.37.
+.IP \(bu 4
+Tie::Hash has been upgraded from version 1.03 to 1.04.
+.Sp
+Calling \f(CW\*(C`Tie::Hash\->TIEHASH()\*(C'\fR used to loop forever.  Now it \f(CW\*(C`croak\*(C'\fRs.
+.IP \(bu 4
+Tie::Hash::NamedCapture has been upgraded from version 0.06 to 0.08.
+.IP \(bu 4
+Tie::RefHash has been upgraded from version 1.38 to 1.39.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9719 to 1.9721_01.
+.IP \(bu 4
+Time::Local has been upgraded from version 1.1901_01 to 1.2000.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.15_01 to 1.20_01.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 0.52_01 to 0.73.
+.Sp
+Unicode::Collate has been updated to use Unicode 6.0.0.
+.Sp
+Unicode::Collate::Locale now supports a plethora of new locales: \fIar, be,
+bg, de_\|_phonebook, hu, hy, kk, mk, nso, om, tn, vi, hr, ig, ja, ko, ru, sq, 
+se, sr, to, uk, zh, zh_\|_big5han, zh_\|_gb2312han, zh_\|_pinyin\fR, and \fIzh_\|_stroke\fR.
+.Sp
+The following modules have been added:
+.Sp
+Unicode::Collate::CJK::Big5 for \f(CW\*(C`zh_\|_big5han\*(C'\fR which makes 
+tailoring of CJK Unified Ideographs in the order of CLDR's big5han ordering.
+.Sp
+Unicode::Collate::CJK::GB2312 for \f(CW\*(C`zh_\|_gb2312han\*(C'\fR which makes
+tailoring of CJK Unified Ideographs in the order of CLDR's gb2312han ordering.
+.Sp
+Unicode::Collate::CJK::JISX0208 which makes tailoring of 6355 kanji 
+(CJK Unified Ideographs) in the JIS X 0208 order.
+.Sp
+Unicode::Collate::CJK::Korean which makes tailoring of CJK Unified Ideographs 
+in the order of CLDR's Korean ordering.
+.Sp
+Unicode::Collate::CJK::Pinyin for \f(CW\*(C`zh_\|_pinyin\*(C'\fR which makes
+tailoring of CJK Unified Ideographs in the order of CLDR's pinyin ordering.
+.Sp
+Unicode::Collate::CJK::Stroke for \f(CW\*(C`zh_\|_stroke\*(C'\fR which makes
+tailoring of CJK Unified Ideographs in the order of CLDR's stroke ordering.
+.Sp
+This also sees the switch from using the pure-Perl version of this
+module to the XS version.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.03 to 1.10.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.27 to 0.32.
+.Sp
+A new function, \fBUnicode::UCD::num()\fR, has been added.  This function
+returns the numeric value of the string passed it or \f(CW\*(C`undef\*(C'\fR if the string
+in its entirety has no "safe" numeric value.  (For more detail, and for the
+definition of "safe", see "\fBnum()\fR" in Unicode::UCD.)
+.Sp
+This upgrade also includes several bug fixes:
+.RS 4
+.IP \fBcharinfo()\fR 4
+.IX Item "charinfo()"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+It is now updated to Unicode Version 6.0.0 with \fICorrigendum #8\fR, 
+excepting that, just as with Perl 5.14, the code point at U+1F514 has no name.
+.IP \(bu 4
+Hangul syllable code points have the correct names, and their
+decompositions are always output without requiring Lingua::KO::Hangul::Util
+to be installed.
+.IP \(bu 4
+CJK (Chinese-Japanese-Korean) code points U+2A700 to U+2B734
+and U+2B740 to U+2B81D are now properly handled.
+.IP \(bu 4
+Numeric values are now output for those CJK code points that have them.
+.IP \(bu 4
+Names output for code points with multiple aliases are now the
+corrected ones.
+.RE
+.RS 4
+.RE
+.IP \fBcharscript()\fR 4
+.IX Item "charscript()"
+This now correctly returns "Unknown" instead of \f(CW\*(C`undef\*(C'\fR for the script
+of a code point that hasn't been assigned another one.
+.IP \fBcharblock()\fR 4
+.IX Item "charblock()"
+This now correctly returns "No_Block" instead of \f(CW\*(C`undef\*(C'\fR for the block
+of a code point that hasn't been assigned to another one.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+The version pragma has been upgraded from 0.82 to 0.88.
+.Sp
+Because of a bug, now fixed, the \fBis_strict()\fR and \fBis_lax()\fR functions did not
+work when exported (5.12.1).
+.IP \(bu 4
+The warnings pragma has been upgraded from version 1.09 to 1.12.
+.Sp
+Calling \f(CW\*(C`use warnings\*(C'\fR without arguments is now significantly more efficient.
+.IP \(bu 4
+The warnings::register pragma has been upgraded from version 1.01 to 1.02.
+.Sp
+It is now possible to register warning categories other than the names of
+packages using warnings::register.  See \fBperllexwarn\fR\|(1) for more information.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.10 to 0.13.
+.IP \(bu 4
+VMS::DCLsym has been upgraded from version 1.03 to 1.05.
+.Sp
+Two bugs have been fixed [perl #84086]:
+.Sp
+The symbol table name was lost when tying a hash, due to a thinko in
+\&\f(CW\*(C`TIEHASH\*(C'\fR.  The result was that all tied hashes interacted with the
+local symbol table.
+.Sp
+Unless a symbol table name had been explicitly specified in the call
+to the constructor, querying the special key \f(CW\*(C`:LOCAL\*(C'\fR failed to
+identify objects connected to the local symbol table.
+.IP \(bu 4
+The Win32 module has been upgraded from version 0.39 to 0.44.
+.Sp
+This release has several new functions: \fBWin32::GetSystemMetrics()\fR,
+\&\fBWin32::GetProductInfo()\fR, \fBWin32::GetOSDisplayName()\fR.
+.Sp
+The names returned by \fBWin32::GetOSName()\fR and \fBWin32::GetOSDisplayName()\fR
+have been corrected.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.03 to 0.05.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+As promised in Perl 5.12.0's release notes, the following modules have
+been removed from the core distribution, and if needed should be installed
+from CPAN instead.
+.IP \(bu 4
+Class::ISA has been removed from the Perl core.  Prior version was 0.36.
+.IP \(bu 4
+Pod::Plainer has been removed from the Perl core.  Prior version was 1.02.
+.IP \(bu 4
+Switch has been removed from the Perl core.  Prior version was 2.16.
+.PP
+The removal of Shell has been deferred until after 5.14, as the
+implementation of Shell shipped with 5.12.0 did not correctly issue the
+warning that it was to be removed from core.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlgpl\fR
+.IX Subsection "perlgpl"
+.PP
+perlgpl has been updated to contain GPL version 1, as is included in the
+\&\fIREADME\fR distributed with Perl (5.12.1).
+.PP
+\fIPerl 5.12.x delta files\fR
+.IX Subsection "Perl 5.12.x delta files"
+.PP
+The perldelta files for Perl 5.12.1 to 5.12.3 have been added from the
+maintenance branch: perl5121delta, perl5122delta, perl5123delta.
+.PP
+\fIperlpodstyle\fR
+.IX Subsection "perlpodstyle"
+.PP
+New style guide for POD documentation,
+split mostly from the NOTES section of the \fBpod2man\fR\|(1) manpage.
+.PP
+\fIperlsource, perlinterp, perlhacktut, and perlhacktips\fR
+.IX Subsection "perlsource, perlinterp, perlhacktut, and perlhacktips"
+.PP
+See "perlhack and perlrepository revamp", below.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlmodlib is now complete\fR
+.IX Subsection "perlmodlib is now complete"
+.PP
+The perlmodlib manpage that came with Perl 5.12.0 was missing several
+modules due to a bug in the script that generates the list.  This has been
+fixed [perl #74332] (5.12.1).
+.PP
+\fIReplace incorrect tr/// table in perlebcdic\fR
+.IX Subsection "Replace incorrect tr/// table in perlebcdic"
+.PP
+perlebcdic contains a helpful table to use in \f(CW\*(C`tr///\*(C'\fR to convert
+between EBCDIC and Latin1/ASCII.  The table was the inverse of the one
+it describes, though the code that used the table worked correctly for
+the specific example given.
+.PP
+The table has been corrected and the sample code changed to correspond.
+.PP
+The table has also been changed to hex from octal, and the recipes in the
+pod have been altered to print out leading zeros to make all values
+the same length.
+.PP
+\fITricks for user-defined casing\fR
+.IX Subsection "Tricks for user-defined casing"
+.PP
+perlunicode now contains an explanation of how to override, mangle
+and otherwise tweak the way Perl handles upper\-, lower\- and other-case
+conversions on Unicode data, and how to provide scoped changes to alter
+one's own code's behaviour without stomping on anybody else's.
+.PP
+\fIINSTALL explicitly states that Perl requires a C89 compiler\fR
+.IX Subsection "INSTALL explicitly states that Perl requires a C89 compiler"
+.PP
+This was already true, but it's now Officially Stated For The Record
+(5.12.2).
+.PP
+\fIExplanation of \fR\f(CI\*(C`\exHH\*(C'\fR\fI and \fR\f(CI\*(C`\eoOOO\*(C'\fR\fI escapes\fR
+.IX Subsection "Explanation of xHH and oOOO escapes"
+.PP
+perlop has been updated with more detailed explanation of these two
+character escapes.
+.PP
+\fR\f(BI\-0NNN\fR\fI switch\fR
+.IX Subsection "-0NNN switch"
+.PP
+In perlrun, the behaviour of the \fB\-0NNN\fR switch for \fB\-0400\fR or higher
+has been clarified (5.12.2).
+.PP
+\fIMaintenance policy\fR
+.IX Subsection "Maintenance policy"
+.PP
+perlpolicy now contains the policy on what patches are acceptable for
+maintenance branches (5.12.1).
+.PP
+\fIDeprecation policy\fR
+.IX Subsection "Deprecation policy"
+.PP
+perlpolicy now contains the policy on compatibility and deprecation
+along with definitions of terms like "deprecation" (5.12.2).
+.PP
+\fINew descriptions in perldiag\fR
+.IX Subsection "New descriptions in perldiag"
+.PP
+The following existing diagnostics are now documented:
+.IP \(bu 4
+Ambiguous use of \f(CW%c\fR resolved as operator \f(CW%c\fR
+.IP \(bu 4
+Ambiguous use of \f(CW%c\fR{%s} resolved to \f(CW%c\fR%s
+.IP \(bu 4
+Ambiguous use of \f(CW%c\fR{%s[...]} resolved to \f(CW%c\fR%s[...]
+.IP \(bu 4
+Ambiguous use of \f(CW%c\fR{%s{...}} resolved to \f(CW%c\fR%s{...}
+.IP \(bu 4
+Ambiguous use of \-%s resolved as \-&%s()
+.IP \(bu 4
+Invalid strict version format (%s)
+.IP \(bu 4
+Invalid version format (%s)
+.IP \(bu 4
+Invalid version object
+.PP
+\fIperlbook\fR
+.IX Subsection "perlbook"
+.PP
+perlbook has been expanded to cover many more popular books.
+.PP
+\fR\f(CI\*(C`SvTRUE\*(C'\fR\fI macro\fR
+.IX Subsection "SvTRUE macro"
+.PP
+The documentation for the \f(CW\*(C`SvTRUE\*(C'\fR macro in
+perlapi was simply wrong in stating that
+get-magic is not processed.  It has been corrected.
+.PP
+\fIop manipulation functions\fR
+.IX Subsection "op manipulation functions"
+.PP
+Several API functions that process optrees have been newly documented.
+.PP
+\fIperlvar revamp\fR
+.IX Subsection "perlvar revamp"
+.PP
+perlvar reorders the variables and groups them by topic.  Each variable
+introduced after Perl 5.000 notes the first version in which it is 
+available.  perlvar also has a new section for deprecated variables to
+note when they were removed.
+.PP
+\fIArray and hash slices in scalar context\fR
+.IX Subsection "Array and hash slices in scalar context"
+.PP
+These are now documented in perldata.
+.PP
+\fR\f(CI\*(C`use locale\*(C'\fR\fI and formats\fR
+.IX Subsection "use locale and formats"
+.PP
+perlform and perllocale have been corrected to state that
+\&\f(CW\*(C`use locale\*(C'\fR affects formats.
+.PP
+\fIoverload\fR
+.IX Subsection "overload"
+.PP
+overload's documentation has practically undergone a rewrite.  It
+is now much more straightforward and clear.
+.PP
+\fIperlhack and perlrepository revamp\fR
+.IX Subsection "perlhack and perlrepository revamp"
+.PP
+The perlhack document is now much shorter, and focuses on the Perl 5
+development process and submitting patches to Perl.  The technical content
+has been moved to several new documents, perlsource, perlinterp,
+perlhacktut, and perlhacktips.  This technical content has 
+been only lightly edited.
+.PP
+The perlrepository document has been renamed to perlgit.  This new
+document is just a how-to on using git with the Perl source code.
+Any other content that used to be in perlrepository has been moved
+to perlhack.
+.PP
+\fITime::Piece examples\fR
+.IX Subsection "Time::Piece examples"
+.PP
+Examples in perlfaq4 have been updated to show the use of
+Time::Piece.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP "Closure prototype called" 4
+.IX Item "Closure prototype called"
+This error occurs when a subroutine reference passed to an attribute
+handler is called, if the subroutine is a closure [perl #68560].
+.ie n .IP "Insecure user-defined property %s" 4
+.el .IP "Insecure user-defined property \f(CW%s\fR" 4
+.IX Item "Insecure user-defined property %s"
+Perl detected tainted data when trying to compile a regular
+expression that contains a call to a user-defined character property
+function, meaning \f(CW\*(C`\ep{IsFoo}\*(C'\fR or \f(CW\*(C`\ep{InFoo}\*(C'\fR.
+See "User-Defined Character Properties" in perlunicode and perlsec.
+.IP "panic: gp_free failed to free glob pointer \- something is repeatedly re-creating entries" 4
+.IX Item "panic: gp_free failed to free glob pointer - something is repeatedly re-creating entries"
+This new error is triggered if a destructor called on an object in a
+typeglob that is being freed creates a new typeglob entry containing an
+object with a destructor that creates a new entry containing an object etc.
+.IP "Parsing code internal error (%s)" 4
+.IX Item "Parsing code internal error (%s)"
+This new fatal error is produced when parsing
+code supplied by an extension violates the
+parser's API in a detectable way.
+.ie n .IP "refcnt: fd %d%s" 4
+.el .IP "refcnt: fd \f(CW%d\fR%s" 4
+.IX Item "refcnt: fd %d%s"
+This new error only occurs if an internal consistency check fails when a
+pipe is about to be closed.
+.IP "Regexp modifier ""/%c"" may not appear twice" 4
+.IX Item "Regexp modifier ""/%c"" may not appear twice"
+The regular expression pattern has one of the
+mutually exclusive modifiers repeated.
+.IP "Regexp modifiers ""/%c"" and ""/%c"" are mutually exclusive" 4
+.IX Item "Regexp modifiers ""/%c"" and ""/%c"" are mutually exclusive"
+The regular expression pattern has more than one of the mutually
+exclusive modifiers.
+.ie n .IP "Using !~ with %s doesn't make sense" 4
+.el .IP "Using !~ with \f(CW%s\fR doesn't make sense" 4
+.IX Item "Using !~ with %s doesn't make sense"
+This error occurs when \f(CW\*(C`!~\*(C'\fR is used with \f(CW\*(C`s///r\*(C'\fR or \f(CW\*(C`y///r\*(C'\fR.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP """\eb{"" is deprecated; use ""\eb\e{"" instead" 4
+.IX Item """b{"" is deprecated; use ""b{"" instead"
+.PD 0
+.IP """\eB{"" is deprecated; use ""\eB\e{"" instead" 4
+.IX Item """B{"" is deprecated; use ""B{"" instead"
+.PD
+Use of an unescaped "{" immediately following a \f(CW\*(C`\eb\*(C'\fR or \f(CW\*(C`\eB\*(C'\fR is now
+deprecated in order to reserve its use for Perl itself in a future release.
+.IP "Operation ""%s"" returns its argument for ..." 4
+.IX Item "Operation ""%s"" returns its argument for ..."
+Performing an operation requiring Unicode semantics (such as case-folding)
+on a Unicode surrogate or a non-Unicode character now triggers this
+warning.
+.IP "Use of qw(...) as parentheses is deprecated" 4
+.IX Item "Use of qw(...) as parentheses is deprecated"
+See "Use of qw(...) as parentheses", above, for details.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+The "Variable \f(CW$foo\fR is not imported" warning that precedes a
+\&\f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR error has now been assigned the "misc" category, so that
+\&\f(CW\*(C`no warnings\*(C'\fR will suppress it [perl #73712].
+.IP \(bu 4
+\&\fBwarn()\fR and \fBdie()\fR now produce "Wide character" warnings when fed a
+character outside the byte range if \f(CW\*(C`STDERR\*(C'\fR is a byte-sized handle.
+.IP \(bu 4
+The "Layer does not match this perl" error message has been replaced with
+these more helpful messages [perl #73754]:
+.RS 4
+.IP \(bu 4
+PerlIO layer function table size (%d) does not match size expected by this
+perl (%d)
+.IP \(bu 4
+PerlIO layer instance size (%d) does not match size expected by this perl
+(%d)
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+The "Found = in conditional" warning that is emitted when a constant is
+assigned to a variable in a condition is now withheld if the constant is
+actually a subroutine or one generated by \f(CW\*(C`use constant\*(C'\fR, since the value
+of the constant may not be known at the time the program is written
+[perl #77762].
+.IP \(bu 4
+Previously, if none of the \fBgethostbyaddr()\fR, \fBgethostbyname()\fR and
+\&\fBgethostent()\fR functions were implemented on a given platform, they would
+all die with the message "Unsupported socket function 'gethostent' called",
+with analogous messages for getnet*() and getserv*().  This has been
+corrected.
+.IP \(bu 4
+The warning message about unrecognized regular expression escapes passed
+through has been changed to include any literal "{" following the
+two-character escape.  For example, "\eq{" is now emitted instead of "\eq".
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\fR\f(BIperlbug\fR\fI\|(1)\fR
+.IX Subsection "perlbug"
+.IP \(bu 4
+perlbug now looks in the EMAIL environment variable for a return address
+if the REPLY-TO and REPLYTO variables are empty.
+.IP \(bu 4
+perlbug did not previously generate a "From:" header, potentially
+resulting in dropped mail; it now includes that header.
+.IP \(bu 4
+The user's address is now used as the Return-Path.
+.Sp
+Many systems these days don't have a valid Internet domain name, and
+perlbug@perl.org does not accept email with a return-path that does
+not resolve.  So the user's address is now passed to sendmail so it's
+less likely to get stuck in a mail queue somewhere [perl #82996].
+.IP \(bu 4
+perlbug now always gives the reporter a chance to change the email
+address it guesses for them (5.12.2).
+.IP \(bu 4
+perlbug should no longer warn about uninitialized values when using the \fB\-d\fR
+and \fB\-v\fR options (5.12.2).
+.PP
+\fIperl5db.pl\fR
+.IX Subsection "perl5db.pl"
+.IP \(bu 4
+The remote terminal works after forking and spawns new sessions, one
+per forked process.
+.PP
+\fIptargrep\fR
+.IX Subsection "ptargrep"
+.IP \(bu 4
+ptargrep is a new utility to apply pattern matching to the contents of
+files  in a tar archive.  It comes with \f(CW\*(C`Archive::Tar\*(C'\fR.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+See also "Naming fixes in Policy_sh.SH may invalidate Policy.sh",
+above.
+.IP \(bu 4
+CCINCDIR and CCLIBDIR for the mingw64 cross-compiler are now correctly
+under \fI$(CCHOME)\emingw\einclude\fR and \fI\elib\fR rather than immediately below
+\&\fI$(CCHOME)\fR.
+.Sp
+This means the "incpath", "libpth", "ldflags", "lddlflags" and
+"ldflags_nolargefiles" values in \fIConfig.pm\fR and \fIConfig_heavy.pl\fR are now
+set correctly.
+.IP \(bu 4
+\&\f(CW\*(C`make test.valgrind\*(C'\fR has been adjusted to account for \fIcpan/dist/ext\fR
+separation.
+.IP \(bu 4
+On compilers that support it, \fB\-Wwrite\-strings\fR is now added to cflags by
+default.
+.IP \(bu 4
+The Encode module can now (once again) be included in a static Perl
+build.  The special-case handling for this situation got broken in Perl
+5.11.0, and has now been repaired.
+.IP \(bu 4
+The previous default size of a PerlIO buffer (4096 bytes) has been increased
+to the larger of 8192 bytes and your local BUFSIZ.  Benchmarks show that doubling
+this decade-old default increases read and write performance by around
+25% to 50% when using the default layers of perlio on top of unix.  To choose
+a non-default size, such as to get back the old value or to obtain an even
+larger value, configure with:
+.Sp
+.Vb 1
+\&     ./Configure \-Accflags=\-DPERLIOBUF_DEFAULT_BUFSIZ=N
+.Ve
+.Sp
+where N is the desired size in bytes; it should probably be a multiple of
+your page size.
+.IP \(bu 4
+An "incompatible operand types" error in ternary expressions when building
+with \f(CW\*(C`clang\*(C'\fR has been fixed (5.12.2).
+.IP \(bu 4
+Perl now skips setuid File::Copy tests on partitions it detects mounted
+as \f(CW\*(C`nosuid\*(C'\fR (5.12.2).
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+.IP AIX 4
+.IX Item "AIX"
+Perl now builds on AIX 4.2 (5.12.1).
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP "Apollo DomainOS" 4
+.IX Item "Apollo DomainOS"
+The last vestiges of support for this platform have been excised from
+the Perl distribution.  It was officially discontinued in version 5.12.0.
+It had not worked for years before that.
+.IP "MacOS Classic" 4
+.IX Item "MacOS Classic"
+The last vestiges of support for this platform have been excised from the
+Perl distribution.  It was officially discontinued in an earlier version.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+\fIAIX\fR
+.IX Subsection "AIX"
+.IP \(bu 4
+\&\fIREADME.aix\fR has been updated with information about the XL C/C++ V11 compiler
+suite (5.12.2).
+.PP
+\fIARM\fR
+.IX Subsection "ARM"
+.IP \(bu 4
+The \f(CW\*(C`d_u32align\*(C'\fR configuration probe on ARM has been fixed (5.12.2).
+.PP
+\fICygwin\fR
+.IX Subsection "Cygwin"
+.IP \(bu 4
+MakeMaker has been updated to build manpages on cygwin.
+.IP \(bu 4
+Improved rebase behaviour
+.Sp
+If a DLL is updated on cygwin the old imagebase address is reused.
+This solves most rebase errors, especially when updating on core DLL's.
+See <http://www.tishler.net/jason/software/rebase/rebase\-2.4.2.README> 
+for more information.
+.IP \(bu 4
+Support for the standard cygwin dll prefix (needed for FFIs)
+.IP \(bu 4
+Updated build hints file
+.PP
+\fIFreeBSD 7\fR
+.IX Subsection "FreeBSD 7"
+.IP \(bu 4
+FreeBSD 7 no longer contains \fI/usr/bin/objformat\fR.  At build time,
+Perl now skips the \fIobjformat\fR check for versions 7 and higher and
+assumes ELF (5.12.1).
+.PP
+\fIHP-UX\fR
+.IX Subsection "HP-UX"
+.IP \(bu 4
+Perl now allows \fB\-Duse64bitint\fR without promoting to \f(CW\*(C`use64bitall\*(C'\fR on HP-UX
+(5.12.1).
+.PP
+\fIIRIX\fR
+.IX Subsection "IRIX"
+.IP \(bu 4
+Conversion of strings to floating-point numbers is now more accurate on
+IRIX systems [perl #32380].
+.PP
+\fIMac OS X\fR
+.IX Subsection "Mac OS X"
+.IP \(bu 4
+Early versions of Mac OS X (Darwin) had buggy implementations of the
+\&\fBsetregid()\fR, \fBsetreuid()\fR, setrgid(,) and \fBsetruid()\fR functions, so Perl
+would pretend they did not exist.
+.Sp
+These functions are now recognised on Mac OS 10.5 (Leopard; Darwin 9) and
+higher, as they have been fixed [perl #72990].
+.PP
+\fIMirBSD\fR
+.IX Subsection "MirBSD"
+.IP \(bu 4
+Previously if you built Perl with a shared \fIlibperl.so\fR on MirBSD (the
+default config), it would work up to the installation; however, once
+installed, it would be unable to find \fIlibperl\fR.  Path handling is now
+treated as in the other BSD dialects.
+.PP
+\fINetBSD\fR
+.IX Subsection "NetBSD"
+.IP \(bu 4
+The NetBSD hints file has been changed to make the system malloc the
+default.
+.PP
+\fIOpenBSD\fR
+.IX Subsection "OpenBSD"
+.IP \(bu 4
+OpenBSD > 3.7 has a new malloc implementation which is \fImmap\fR\-based,
+and as such can release memory back to the OS; however, Perl's use of
+this malloc causes a substantial slowdown, so we now default to using
+Perl's malloc instead [perl #75742].
+.PP
+\fIOpenVOS\fR
+.IX Subsection "OpenVOS"
+.IP \(bu 4
+Perl now builds again with OpenVOS (formerly known as Stratus VOS)
+[perl #78132] (5.12.3).
+.PP
+\fISolaris\fR
+.IX Subsection "Solaris"
+.IP \(bu 4
+DTrace is now supported on Solaris.  There used to be build failures, but
+these have been fixed [perl #73630] (5.12.3).
+.PP
+\fIVMS\fR
+.IX Subsection "VMS"
+.IP \(bu 4
+Extension building on older (pre 7.3\-2) VMS systems was broken because
+configure.com hit the DCL symbol length limit of 1K.  We now work within
+this limit when assembling the list of extensions in the core build (5.12.1).
+.IP \(bu 4
+We fixed configuring and building Perl with \fB\-Uuseperlio\fR (5.12.1).
+.IP \(bu 4
+\&\f(CW\*(C`PerlIOUnix_open\*(C'\fR now honours the default permissions on VMS.
+.Sp
+When \f(CW\*(C`perlio\*(C'\fR became the default and \f(CW\*(C`unix\*(C'\fR became the default bottom layer,
+the most common path for creating files from Perl became \f(CW\*(C`PerlIOUnix_open\*(C'\fR,
+which has always explicitly used \f(CW0666\fR as the permission mask.  This prevents
+inheriting permissions from RMS defaults and ACLs, so to avoid that problem,
+we now pass \f(CW0777\fR to \fBopen()\fR.  In the VMS CRTL, \f(CW0777\fR has a special
+meaning over and above intersecting with the current umask; specifically, it
+allows Unix syscalls to preserve native default permissions (5.12.3).
+.IP \(bu 4
+The shortening of symbols longer than 31 characters in the core C sources
+and in extensions is now by default done by the C compiler rather than by
+xsubpp (which could only do so for generated symbols in XS code).  You can
+reenable xsubpp's symbol shortening by configuring with \-Uuseshortenedsymbols,
+but you'll have some work to do to get the core sources to compile.
+.IP \(bu 4
+Record-oriented files (record format variable or variable with fixed control)
+opened for write by the \f(CW\*(C`perlio\*(C'\fR layer will now be line-buffered to prevent the
+introduction of spurious line breaks whenever the perlio buffer fills up.
+.IP \(bu 4
+\&\fIgit_version.h\fR is now installed on VMS.  This was an oversight in v5.12.0 which
+caused some extensions to fail to build (5.12.2).
+.IP \(bu 4
+Several memory leaks in \fBstat()\fR have been fixed (5.12.2).
+.IP \(bu 4
+A memory leak in \fBPerl_rename()\fR due to a double allocation has been
+fixed (5.12.2).
+.IP \(bu 4
+A memory leak in \fBvms_fid_to_name()\fR (used by \fBrealpath()\fR and
+\&\fBrealname()\fR> has been fixed (5.12.2).
+.PP
+\fIWindows\fR
+.IX Subsection "Windows"
+.PP
+See also "\fBfork()\fR emulation will not wait for signalled children" and
+"Perl source code is read in text mode on Windows", above.
+.IP \(bu 4
+Fixed build process for SDK2003SP1 compilers.
+.IP \(bu 4
+Compilation with Visual Studio 2010 is now supported.
+.IP \(bu 4
+When using old 32\-bit compilers, the define \f(CW\*(C`_USE_32BIT_TIME_T\*(C'\fR is now
+set in \f(CW$Config{ccflags}\fR.  This improves portability when compiling
+XS extensions using new compilers, but for a Perl compiled with old 32\-bit
+compilers.
+.IP \(bu 4
+\&\f(CW$Config{gccversion}\fR is now set correctly when Perl is built using the
+mingw64 compiler from <http://mingw64.org> [perl #73754].
+.IP \(bu 4
+When building Perl with the mingw64 x64 cross-compiler \f(CW\*(C`incpath\*(C'\fR,
+\&\f(CW\*(C`libpth\*(C'\fR, \f(CW\*(C`ldflags\*(C'\fR, \f(CW\*(C`lddlflags\*(C'\fR and \f(CW\*(C`ldflags_nolargefiles\*(C'\fR values
+in \fIConfig.pm\fR and \fIConfig_heavy.pl\fR were not previously being set
+correctly because, with that compiler, the include and lib directories
+are not immediately below \f(CW\*(C`$(CCHOME)\*(C'\fR (5.12.2).
+.IP \(bu 4
+The build process proceeds more smoothly with mingw and dmake when
+\&\fIC:\eMSYS\ebin\fR is in the PATH, due to a \f(CW\*(C`Cwd\*(C'\fR fix.
+.IP \(bu 4
+Support for building with Visual C++ 2010 is now underway, but is not yet
+complete.  See \fIREADME.win32\fR or perlwin32 for more details.
+.IP \(bu 4
+The option to use an externally-supplied \fBcrypt()\fR, or to build with no
+\&\fBcrypt()\fR at all, has been removed.  Perl supplies its own \fBcrypt()\fR
+implementation for Windows, and the political situation that required
+this part of the distribution to sometimes be omitted is long gone.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.SS "New APIs"
+.IX Subsection "New APIs"
+\fICLONE_PARAMS structure added to ease correct thread creation\fR
+.IX Subsection "CLONE_PARAMS structure added to ease correct thread creation"
+.PP
+Modules that create threads should now create \f(CW\*(C`CLONE_PARAMS\*(C'\fR structures
+by calling the new function \fBPerl_clone_params_new()\fR, and free them with
+\&\fBPerl_clone_params_del()\fR.  This will ensure compatibility with any future
+changes to the internals of the \f(CW\*(C`CLONE_PARAMS\*(C'\fR structure layout, and that
+it is correctly allocated and initialised.
+.PP
+\fINew parsing functions\fR
+.IX Subsection "New parsing functions"
+.PP
+Several functions have been added for parsing Perl statements and
+expressions.  These functions are meant to be used by XS code invoked
+during Perl parsing, in a recursive-descent manner, to allow modules to
+augment the standard Perl syntax.
+.IP \(bu 4
+\&\fBparse_stmtseq()\fR
+parses a sequence of statements, up to closing brace or EOF.
+.IP \(bu 4
+\&\fBparse_fullstmt()\fR
+parses a complete Perl statement, including optional label.
+.IP \(bu 4
+\&\fBparse_barestmt()\fR
+parses a statement without a label.
+.IP \(bu 4
+\&\fBparse_block()\fR
+parses a code block.
+.IP \(bu 4
+\&\fBparse_label()\fR
+parses a statement label, separate from statements.
+.IP \(bu 4
+\&\f(CWparse_fullexpr()\fR,
+\&\f(CWparse_listexpr()\fR,
+\&\f(CWparse_termexpr()\fR, and
+\&\f(CWparse_arithexpr()\fR
+parse expressions at various precedence levels.
+.PP
+\fIHints hash API\fR
+.IX Subsection "Hints hash API"
+.PP
+A new C API for introspecting the hinthash \f(CW\*(C`%^H\*(C'\fR at runtime has been
+added.  See \f(CW\*(C`cop_hints_2hv\*(C'\fR, \f(CW\*(C`cop_hints_fetchpvn\*(C'\fR, \f(CW\*(C`cop_hints_fetchpvs\*(C'\fR,
+\&\f(CW\*(C`cop_hints_fetchsv\*(C'\fR, and \f(CW\*(C`hv_copy_hints_hv\*(C'\fR in perlapi for details.
+.PP
+A new, experimental API has been added for accessing the internal
+structure that Perl uses for \f(CW\*(C`%^H\*(C'\fR.  See the functions beginning with
+\&\f(CW\*(C`cophh_\*(C'\fR in perlapi.
+.PP
+\fIC interface to \fR\f(BIcaller()\fR
+.IX Subsection "C interface to caller()"
+.PP
+The \f(CW\*(C`caller_cx\*(C'\fR function has been added as an XSUB-writer's equivalent of
+\&\fBcaller()\fR.  See perlapi for details.
+.PP
+\fICustom per-subroutine check hooks\fR
+.IX Subsection "Custom per-subroutine check hooks"
+.PP
+XS code in an extension module can now annotate a subroutine (whether
+implemented in XS or in Perl) so that nominated XS code will be called
+at compile time (specifically as part of op checking) to change the op
+tree of that subroutine.  The compile-time check function (supplied by
+the extension module) can implement argument processing that can't be
+expressed as a prototype, generate customised compile-time warnings,
+perform constant folding for a pure function, inline a subroutine
+consisting of sufficiently simple ops, replace the whole call with a
+custom op, and so on.  This was previously all possible by hooking the
+\&\f(CW\*(C`entersub\*(C'\fR op checker, but the new mechanism makes it easy to tie the
+hook to a specific subroutine.  See "cv_set_call_checker" in perlapi.
+.PP
+To help in writing custom check hooks, several subtasks within standard
+\&\f(CW\*(C`entersub\*(C'\fR op checking have been separated out and exposed in the API.
+.PP
+\fIImproved support for custom OPs\fR
+.IX Subsection "Improved support for custom OPs"
+.PP
+Custom ops can now be registered with the new \f(CW\*(C`custom_op_register\*(C'\fR C
+function and the \f(CW\*(C`XOP\*(C'\fR structure.  This will make it easier to add new
+properties of custom ops in the future.  Two new properties have been added
+already, \f(CW\*(C`xop_class\*(C'\fR and \f(CW\*(C`xop_peep\*(C'\fR.
+.PP
+\&\f(CW\*(C`xop_class\*(C'\fR is one of the OA_*OP constants.  It allows B and other
+introspection mechanisms to work with custom ops
+that aren't BASEOPs.  \f(CW\*(C`xop_peep\*(C'\fR is a pointer to
+a function that will be called for ops of this
+type from \f(CW\*(C`Perl_rpeep\*(C'\fR.
+.PP
+See "Custom Operators" in perlguts and "Custom Operators" in perlapi for more
+detail.
+.PP
+The old \f(CW\*(C`PL_custom_op_names\*(C'\fR/\f(CW\*(C`PL_custom_op_descs\*(C'\fR interface is still
+supported but discouraged.
+.PP
+\fIScope hooks\fR
+.IX Subsection "Scope hooks"
+.PP
+It is now possible for XS code to hook into Perl's lexical scope
+mechanism at compile time, using the new \f(CW\*(C`Perl_blockhook_register\*(C'\fR
+function.  See "Compile-time scope hooks" in perlguts.
+.PP
+\fIThe recursive part of the peephole optimizer is now hookable\fR
+.IX Subsection "The recursive part of the peephole optimizer is now hookable"
+.PP
+In addition to \f(CW\*(C`PL_peepp\*(C'\fR, for hooking into the toplevel peephole optimizer, a
+\&\f(CW\*(C`PL_rpeepp\*(C'\fR is now available to hook into the optimizer recursing into
+side-chains of the optree.
+.PP
+\fINew non-magical variants of existing functions\fR
+.IX Subsection "New non-magical variants of existing functions"
+.PP
+The following functions/macros have been added to the API.  The \f(CW*_nomg\fR
+macros are equivalent to their non\-\f(CW\*(C`_nomg\*(C'\fR variants, except that they ignore
+get-magic.  Those ending in \f(CW\*(C`_flags\*(C'\fR allow one to specify whether
+get-magic is processed.
+.PP
+.Vb 8
+\&  sv_2bool_flags
+\&  SvTRUE_nomg
+\&  sv_2nv_flags
+\&  SvNV_nomg
+\&  sv_cmp_flags
+\&  sv_cmp_locale_flags
+\&  sv_eq_flags
+\&  sv_collxfrm_flags
+.Ve
+.PP
+In some of these cases, the non\-\f(CW\*(C`_flags\*(C'\fR functions have
+been replaced with wrappers around the new functions.
+.PP
+\fIpv/pvs/sv versions of existing functions\fR
+.IX Subsection "pv/pvs/sv versions of existing functions"
+.PP
+Many functions ending with pvn now have equivalent \f(CW\*(C`pv/pvs/sv\*(C'\fR versions.
+.PP
+\fIList op-building functions\fR
+.IX Subsection "List op-building functions"
+.PP
+List op-building functions have been added to the
+API.  See op_append_elem,
+op_append_list, and
+op_prepend_elem in perlapi.
+.PP
+\fR\f(CI\*(C`LINKLIST\*(C'\fR\fI\fR
+.IX Subsection "LINKLIST"
+.PP
+The LINKLIST macro, part of op building that
+constructs the execution-order op chain, has been added to the API.
+.PP
+\fILocalisation functions\fR
+.IX Subsection "Localisation functions"
+.PP
+The \f(CW\*(C`save_freeop\*(C'\fR, \f(CW\*(C`save_op\*(C'\fR, \f(CW\*(C`save_pushi32ptr\*(C'\fR and \f(CW\*(C`save_pushptrptr\*(C'\fR
+functions have been added to the API.
+.PP
+\fIStash names\fR
+.IX Subsection "Stash names"
+.PP
+A stash can now have a list of effective names in addition to its usual
+name.  The first effective name can be accessed via the \f(CW\*(C`HvENAME\*(C'\fR macro,
+which is now the recommended name to use in MRO linearisations (\f(CW\*(C`HvNAME\*(C'\fR
+being a fallback if there is no \f(CW\*(C`HvENAME\*(C'\fR).
+.PP
+These names are added and deleted via \f(CW\*(C`hv_ename_add\*(C'\fR and
+\&\f(CW\*(C`hv_ename_delete\*(C'\fR.  These two functions are \fInot\fR part of the API.
+.PP
+\fINew functions for finding and removing magic\fR
+.IX Subsection "New functions for finding and removing magic"
+.PP
+The \f(CWmg_findext()\fR and
+\&\f(CWsv_unmagicext()\fR
+functions have been added to the API.
+They allow extension authors to find and remove magic attached to
+scalars based on both the magic type and the magic virtual table, similar to how
+\&\fBsv_magicext()\fR attaches magic of a certain type and with a given virtual table
+to a scalar.  This eliminates the need for extensions to walk the list of
+\&\f(CW\*(C`MAGIC\*(C'\fR pointers of an \f(CW\*(C`SV\*(C'\fR to find the magic that belongs to them.
+.PP
+\fR\f(CI\*(C`find_rundefsv\*(C'\fR\fI\fR
+.IX Subsection "find_rundefsv"
+.PP
+This function returns the SV representing \f(CW$_\fR, whether it's lexical
+or dynamic.
+.PP
+\fR\f(CI\*(C`Perl_croak_no_modify\*(C'\fR\fI\fR
+.IX Subsection "Perl_croak_no_modify"
+.PP
+\&\fBPerl_croak_no_modify()\fR is short-hand for
+\&\f(CW\*(C`Perl_croak("%s", PL_no_modify)\*(C'\fR.
+.PP
+\fR\f(CI\*(C`PERL_STATIC_INLINE\*(C'\fR\fI define\fR
+.IX Subsection "PERL_STATIC_INLINE define"
+.PP
+The \f(CW\*(C`PERL_STATIC_INLINE\*(C'\fR define has been added to provide the best-guess
+incantation to use for static inline functions, if the C compiler supports
+C99\-style static inline.  If it doesn't, it'll give a plain \f(CW\*(C`static\*(C'\fR.
+.PP
+\&\f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR can be used to check if the compiler actually supports
+inline functions.
+.PP
+\fINew \fR\f(CI\*(C`pv_escape\*(C'\fR\fI option for hexadecimal escapes\fR
+.IX Subsection "New pv_escape option for hexadecimal escapes"
+.PP
+A new option, \f(CW\*(C`PERL_PV_ESCAPE_NONASCII\*(C'\fR, has been added to \f(CW\*(C`pv_escape\*(C'\fR to
+dump all characters above ASCII in hexadecimal.  Before, one could get all
+characters as hexadecimal or the Latin1 non-ASCII as octal.
+.PP
+\fR\f(CI\*(C`lex_start\*(C'\fR\fI\fR
+.IX Subsection "lex_start"
+.PP
+\&\f(CW\*(C`lex_start\*(C'\fR has been added to the API, but is considered experimental.
+.PP
+\fR\f(BIop_scope()\fR\fI and \fR\f(BIop_lvalue()\fR\fI\fR
+.IX Subsection "op_scope() and op_lvalue()"
+.PP
+The \fBop_scope()\fR and \fBop_lvalue()\fR functions have been added to the API,
+but are considered experimental.
+.SS "C API Changes"
+.IX Subsection "C API Changes"
+\fR\f(CI\*(C`PERL_POLLUTE\*(C'\fR\fI has been removed\fR
+.IX Subsection "PERL_POLLUTE has been removed"
+.PP
+The option to define \f(CW\*(C`PERL_POLLUTE\*(C'\fR to expose older 5.005 symbols for
+backwards compatibility has been removed.  Its use was always discouraged,
+and MakeMaker contains a more specific escape hatch:
+.PP
+.Vb 1
+\&    perl Makefile.PL POLLUTE=1
+.Ve
+.PP
+This can be used for modules that have not been upgraded to 5.6 naming
+conventions (and really should be completely obsolete by now).
+.PP
+\fICheck API compatibility when loading XS modules\fR
+.IX Subsection "Check API compatibility when loading XS modules"
+.PP
+When Perl's API changes in incompatible ways (which usually happens between
+major releases), XS modules compiled for previous versions of Perl will no
+longer work.  They need to be recompiled against the new Perl.
+.PP
+The \f(CW\*(C`XS_APIVERSION_BOOTCHECK\*(C'\fR macro has been added to ensure that modules
+are recompiled and to prevent users from accidentally loading modules
+compiled for old perls into newer perls.  That macro, which is called when
+loading every newly compiled extension, compares the API version of the
+running perl with the version a module has been compiled for and raises an
+exception if they don't match.
+.PP
+\fIPerl_fetch_cop_label\fR
+.IX Subsection "Perl_fetch_cop_label"
+.PP
+The first argument of the C API function \f(CW\*(C`Perl_fetch_cop_label\*(C'\fR has changed
+from \f(CW\*(C`struct refcounted_he *\*(C'\fR to \f(CW\*(C`COP *\*(C'\fR, to insulate the user from
+implementation details.
+.PP
+This API function was marked as "may change", and likely isn't in use outside
+the core.  (Neither an unpacked CPAN nor Google's codesearch finds any other
+references to it.)
+.PP
+\fR\f(BIGvCV()\fR\fI and \fR\f(BIGvGP()\fR\fI are no longer lvalues\fR
+.IX Subsection "GvCV() and GvGP() are no longer lvalues"
+.PP
+The new \fBGvCV_set()\fR and \fBGvGP_set()\fR macros are now provided to replace
+assignment to those two macros.
+.PP
+This allows a future commit to eliminate some backref magic between GV
+and CVs, which will require complete control over assignment to the
+\&\f(CW\*(C`gp_cv\*(C'\fR slot.
+.PP
+\fR\f(BICvGV()\fR\fI is no longer an lvalue\fR
+.IX Subsection "CvGV() is no longer an lvalue"
+.PP
+Under some circumstances, the \fBCvGV()\fR field of a CV is now
+reference-counted.  To ensure consistent behaviour, direct assignment to
+it, for example \f(CW\*(C`CvGV(cv) = gv\*(C'\fR is now a compile-time error.  A new macro,
+\&\f(CW\*(C`CvGV_set(cv,gv)\*(C'\fR has been introduced to run this operation
+safely.  Note that modification of this field is not part of the public
+API, regardless of this new macro (and despite its being listed in this section).
+.PP
+\fR\f(BICvSTASH()\fR\fI is no longer an lvalue\fR
+.IX Subsection "CvSTASH() is no longer an lvalue"
+.PP
+The \fBCvSTASH()\fR macro can now only be used as an rvalue.  \fBCvSTASH_set()\fR
+has been added to replace assignment to \fBCvSTASH()\fR.  This is to ensure
+that backreferences are handled properly.  These macros are not part of the
+API.
+.PP
+\fICalling conventions for \fR\f(CI\*(C`newFOROP\*(C'\fR\fI and \fR\f(CI\*(C`newWHILEOP\*(C'\fR
+.IX Subsection "Calling conventions for newFOROP and newWHILEOP"
+.PP
+The way the parser handles labels has been cleaned up and refactored.  As a
+result, the \fBnewFOROP()\fR constructor function no longer takes a parameter
+stating what label is to go in the state op.
+.PP
+The \fBnewWHILEOP()\fR and \fBnewFOROP()\fR functions no longer accept a line
+number as a parameter.
+.PP
+\fIFlags passed to \fR\f(CI\*(C`uvuni_to_utf8_flags\*(C'\fR\fI and \fR\f(CI\*(C`utf8n_to_uvuni\*(C'\fR
+.IX Subsection "Flags passed to uvuni_to_utf8_flags and utf8n_to_uvuni"
+.PP
+Some of the flags parameters to \fBuvuni_to_utf8_flags()\fR and
+\&\fButf8n_to_uvuni()\fR have changed.  This is a result of Perl's now allowing
+internal storage and manipulation of code points that are problematic
+in some situations.  Hence, the default actions for these functions has
+been complemented to allow these code points.  The new flags are
+documented in perlapi.  Code that requires the problematic code
+points to be rejected needs to change to use the new flags.  Some flag
+names are retained for backward source compatibility, though they do
+nothing, as they are now the default.  However the flags
+\&\f(CW\*(C`UNICODE_ALLOW_FDD0\*(C'\fR, \f(CW\*(C`UNICODE_ALLOW_FFFF\*(C'\fR, \f(CW\*(C`UNICODE_ILLEGAL\*(C'\fR, and
+\&\f(CW\*(C`UNICODE_IS_ILLEGAL\*(C'\fR have been removed, as they stem from a
+fundamentally broken model of how the Unicode non-character code points
+should be handled, which is now described in
+"Non-character code points" in perlunicode.  See also the Unicode section
+under "Selected Bug Fixes".
+.SS "Deprecated C APIs"
+.IX Subsection "Deprecated C APIs"
+.ie n .IP """Perl_ptr_table_clear""" 4
+.el .IP \f(CWPerl_ptr_table_clear\fR 4
+.IX Item "Perl_ptr_table_clear"
+\&\f(CW\*(C`Perl_ptr_table_clear\*(C'\fR is no longer part of Perl's public API.  Calling it
+now generates a deprecation warning, and it will be removed in a future
+release.
+.ie n .IP """sv_compile_2op""" 4
+.el .IP \f(CWsv_compile_2op\fR 4
+.IX Item "sv_compile_2op"
+The \fBsv_compile_2op()\fR API function is now deprecated.  Searches suggest
+that nothing on CPAN is using it, so this should have zero impact.
+.Sp
+It attempted to provide an API to compile code down to an optree, but failed
+to bind correctly to lexicals in the enclosing scope.  It's not possible to
+fix this problem within the constraints of its parameters and return value.
+.ie n .IP """find_rundefsvoffset""" 4
+.el .IP \f(CWfind_rundefsvoffset\fR 4
+.IX Item "find_rundefsvoffset"
+The \f(CW\*(C`find_rundefsvoffset\*(C'\fR function has been deprecated.  It appeared that
+its design was insufficient for reliably getting the lexical \f(CW$_\fR at
+run-time.
+.Sp
+Use the new \f(CW\*(C`find_rundefsv\*(C'\fR function or the \f(CW\*(C`UNDERBAR\*(C'\fR macro
+instead.  They directly return the right SV
+representing \f(CW$_\fR, whether it's
+lexical or dynamic.
+.ie n .IP """CALL_FPTR"" and ""CPERLscope""" 4
+.el .IP "\f(CWCALL_FPTR\fR and \f(CWCPERLscope\fR" 4
+.IX Item "CALL_FPTR and CPERLscope"
+Those are left from an old implementation of \f(CW\*(C`MULTIPLICITY\*(C'\fR using C++ objects,
+which was removed in Perl 5.8.  Nowadays these macros do exactly nothing, so
+they shouldn't be used anymore.
+.Sp
+For compatibility, they are still defined for external \f(CW\*(C`XS\*(C'\fR code.  Only
+extensions defining \f(CW\*(C`PERL_CORE\*(C'\fR must be updated now.
+.SS "Other Internal Changes"
+.IX Subsection "Other Internal Changes"
+\fIStack unwinding\fR
+.IX Subsection "Stack unwinding"
+.PP
+The protocol for unwinding the C stack at the last stage of a \f(CW\*(C`die\*(C'\fR
+has changed how it identifies the target stack frame.  This now uses
+a separate variable \f(CW\*(C`PL_restartjmpenv\*(C'\fR, where previously it relied on
+the \f(CW\*(C`blk_eval.cur_top_env\*(C'\fR pointer in the \f(CW\*(C`eval\*(C'\fR context frame that
+has nominally just been discarded.  This change means that code running
+during various stages of Perl-level unwinding no longer needs to take
+care to avoid destroying the ghost frame.
+.PP
+\fIScope stack entries\fR
+.IX Subsection "Scope stack entries"
+.PP
+The format of entries on the scope stack has been changed, resulting in a
+reduction of memory usage of about 10%.  In particular, the memory used by
+the scope stack to record each active lexical variable has been halved.
+.PP
+\fIMemory allocation for pointer tables\fR
+.IX Subsection "Memory allocation for pointer tables"
+.PP
+Memory allocation for pointer tables has been changed.  Previously
+\&\f(CW\*(C`Perl_ptr_table_store\*(C'\fR allocated memory from the same arena system as
+\&\f(CW\*(C`SV\*(C'\fR bodies and \f(CW\*(C`HE\*(C'\fRs, with freed memory remaining bound to those arenas
+until interpreter exit.  Now it allocates memory from arenas private to the
+specific pointer table, and that memory is returned to the system when
+\&\f(CW\*(C`Perl_ptr_table_free\*(C'\fR is called.  Additionally, allocation and release are
+both less CPU intensive.
+.PP
+\fR\f(CI\*(C`UNDERBAR\*(C'\fR\fI\fR
+.IX Subsection "UNDERBAR"
+.PP
+The \f(CW\*(C`UNDERBAR\*(C'\fR macro now calls \f(CW\*(C`find_rundefsv\*(C'\fR.  \f(CW\*(C`dUNDERBAR\*(C'\fR is now a
+noop but should still be used to ensure past and future compatibility.
+.PP
+\fIString comparison routines renamed\fR
+.IX Subsection "String comparison routines renamed"
+.PP
+The \f(CW\*(C`ibcmp_*\*(C'\fR functions have been renamed and are now called \f(CW\*(C`foldEQ\*(C'\fR,
+\&\f(CW\*(C`foldEQ_locale\*(C'\fR, and \f(CW\*(C`foldEQ_utf8\*(C'\fR.  The old names are still available as
+macros.
+.PP
+\fR\f(CI\*(C`chop\*(C'\fR\fI and \fR\f(CI\*(C`chomp\*(C'\fR\fI implementations merged\fR
+.IX Subsection "chop and chomp implementations merged"
+.PP
+The opcode bodies for \f(CW\*(C`chop\*(C'\fR and \f(CW\*(C`chomp\*(C'\fR and for \f(CW\*(C`schop\*(C'\fR and \f(CW\*(C`schomp\*(C'\fR
+have been merged.  The implementation functions \fBPerl_do_chop()\fR and
+\&\fBPerl_do_chomp()\fR, never part of the public API, have been merged and
+moved to a static function in \fIpp.c\fR.  This shrinks the Perl binary
+slightly, and should not affect any code outside the core (unless it is
+relying on the order of side-effects when \f(CW\*(C`chomp\*(C'\fR is passed a \fIlist\fR of
+values).
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS I/O
+.IX Subsection "I/O"
+.IP \(bu 4
+Perl no longer produces this warning:
+.Sp
+.Vb 2
+\&    $ perl \-we \*(Aqopen(my $f, ">", \emy $x); binmode($f, "scalar")\*(Aq
+\&    Use of uninitialized value in binmode at \-e line 1.
+.Ve
+.IP \(bu 4
+Opening a glob reference via \f(CW\*(C`open($fh, ">", \e*glob)\*(C'\fR no longer
+causes the glob to be corrupted when the filehandle is printed to.  This would
+cause Perl to crash whenever the glob's contents were accessed
+[perl #77492].
+.IP \(bu 4
+PerlIO no longer crashes when called recursively, such as from a signal
+handler.  Now it just leaks memory [perl #75556].
+.IP \(bu 4
+Most I/O functions were not warning for unopened handles unless the
+"closed" and "unopened" warnings categories were both enabled.  Now only
+\&\f(CW\*(C`use warnings \*(Aqunopened\*(Aq\*(C'\fR is necessary to trigger these warnings, as
+had always been the intention.
+.IP \(bu 4
+There have been several fixes to PerlIO layers:
+.Sp
+When \f(CW\*(C`binmode(FH, ":crlf")\*(C'\fR pushes the \f(CW\*(C`:crlf\*(C'\fR layer on top of the stack,
+it no longer enables crlf layers lower in the stack so as to avoid
+unexpected results [perl #38456].
+.Sp
+Opening a file in \f(CW\*(C`:raw\*(C'\fR mode now does what it advertises to do (first
+open the file, then \f(CW\*(C`binmode\*(C'\fR it), instead of simply leaving off the top
+layer [perl #80764].
+.Sp
+The three layers \f(CW\*(C`:pop\*(C'\fR, \f(CW\*(C`:utf8\*(C'\fR, and \f(CW\*(C`:bytes\*(C'\fR didn't allow stacking when
+opening a file.  For example
+this:
+.Sp
+.Vb 1
+\&    open(FH, ">:pop:perlio", "some.file") or die $!;
+.Ve
+.Sp
+would throw an "Invalid argument" error.  This has been fixed in this
+release [perl #82484].
+.SS "Regular Expression Bug Fixes"
+.IX Subsection "Regular Expression Bug Fixes"
+.IP \(bu 4
+The regular expression engine no longer loops when matching
+\&\f(CW\*(C`"\eN{LATIN SMALL LIGATURE FF}" =~ /f+/i\*(C'\fR and similar expressions
+[perl #72998] (5.12.1).
+.IP \(bu 4
+The trie runtime code should no longer allocate massive amounts of memory,
+fixing #74484.
+.IP \(bu 4
+Syntax errors in \f(CW\*(C`(?{...})\*(C'\fR blocks no longer cause panic messages
+[perl #2353].
+.IP \(bu 4
+A pattern like \f(CW\*(C`(?:(o){2})?\*(C'\fR no longer causes a "panic" error
+[perl #39233].
+.IP \(bu 4
+A fatal error in regular expressions containing \f(CW\*(C`(.*?)\*(C'\fR when processing
+UTF\-8 data has been fixed [perl #75680] (5.12.2).
+.IP \(bu 4
+An erroneous regular expression engine optimisation that caused regex verbs like
+\&\f(CW*COMMIT\fR sometimes to be ignored has been removed.
+.IP \(bu 4
+The regular expression bracketed character class \f(CW\*(C`[\e8\e9]\*(C'\fR was effectively the
+same as \f(CW\*(C`[89\e000]\*(C'\fR, incorrectly matching a NULL character.  It also gave
+incorrect warnings that the \f(CW8\fR and \f(CW9\fR were ignored.  Now \f(CW\*(C`[\e8\e9]\*(C'\fR is the
+same as \f(CW\*(C`[89]\*(C'\fR and gives legitimate warnings that \f(CW\*(C`\e8\*(C'\fR and \f(CW\*(C`\e9\*(C'\fR are
+unrecognized escape sequences, passed-through.
+.IP \(bu 4
+A regular expression match in the right-hand side of a global substitution
+(\f(CW\*(C`s///g\*(C'\fR) that is in the same scope will no longer cause match variables
+to have the wrong values on subsequent iterations.  This can happen when an
+array or hash subscript is interpolated in the right-hand side, as in
+\&\f(CW\*(C`s|(.)|@a{ print($1), /./ }|g\*(C'\fR [perl #19078].
+.IP \(bu 4
+Several cases in which characters in the Latin\-1 non-ASCII range (0x80 to
+0xFF) used not to match themselves, or used to match both a character class
+and its complement, have been fixed.  For instance, U+00E2 could match both
+\&\f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eW\*(C'\fR [perl #78464] [perl #18281] [perl #60156].
+.IP \(bu 4
+Matching a Unicode character against an alternation containing characters
+that happened to match continuation bytes in the former's UTF8
+representation (like \f(CW\*(C`qq{\ex{30ab}} =~ /\exab|\exa9/\*(C'\fR) would cause erroneous
+warnings [perl #70998].
+.IP \(bu 4
+The trie optimisation was not taking empty groups into account, preventing
+"foo" from matching \f(CW\*(C`/\eA(?:(?:)foo|bar|zot)\ez/\*(C'\fR [perl #78356].
+.IP \(bu 4
+A pattern containing a \f(CW\*(C`+\*(C'\fR inside a lookahead would sometimes cause an
+incorrect match failure in a global match (for example, \f(CW\*(C`/(?=(\eS+))/g\*(C'\fR)
+[perl #68564].
+.IP \(bu 4
+A regular expression optimisation would sometimes cause a match with a
+\&\f(CW\*(C`{n,m}\*(C'\fR quantifier to fail when it should have matched [perl #79152].
+.IP \(bu 4
+Case-insensitive matching in regular expressions compiled under
+\&\f(CW\*(C`use locale\*(C'\fR now works much more sanely when the pattern or target
+string is internally encoded in UTF8.  Previously, under these
+conditions the localeness was completely lost.  Now, code points
+above 255 are treated as Unicode, but code points between 0 and 255
+are treated using the current locale rules, regardless of whether
+the pattern or the string is encoded in UTF8.  The few case-insensitive
+matches that cross the 255/256 boundary are not allowed.  For
+example, 0xFF does not caselessly match the character at 0x178,
+LATIN CAPITAL LETTER Y WITH DIAERESIS, because 0xFF may not be LATIN
+SMALL LETTER Y in the current locale, and Perl has no way of knowing
+if that character even exists in the locale, much less what code
+point it is.
+.IP \(bu 4
+The \f(CW\*(C`(?|...)\*(C'\fR regular expression construct no longer crashes if the final
+branch has more sets of capturing parentheses than any other branch.  This
+was fixed in Perl 5.10.1 for the case of a single branch, but that fix did
+not take multiple branches into account [perl #84746].
+.IP \(bu 4
+A bug has been fixed in the implementation of \f(CW\*(C`{...}\*(C'\fR quantifiers in
+regular expressions that prevented the code block in
+\&\f(CW\*(C`/((\ew+)(?{ print $2 })){2}/\*(C'\fR from seeing the \f(CW$2\fR sometimes
+[perl #84294].
+.SS "Syntax/Parsing Bugs"
+.IX Subsection "Syntax/Parsing Bugs"
+.IP \(bu 4
+\&\f(CW\*(C`when (scalar) {...}\*(C'\fR no longer crashes, but produces a syntax error
+[perl #74114] (5.12.1).
+.IP \(bu 4
+A label right before a string eval (\f(CW\*(C`foo: eval $string\*(C'\fR) no longer causes
+the label to be associated also with the first statement inside the eval
+[perl #74290] (5.12.1).
+.IP \(bu 4
+The \f(CW\*(C`no 5.13.2\*(C'\fR form of \f(CW\*(C`no\*(C'\fR no longer tries to turn on features or
+pragmata (like strict) [perl #70075] (5.12.2).
+.IP \(bu 4
+\&\f(CW\*(C`BEGIN {require 5.12.0}\*(C'\fR now behaves as documented, rather than behaving
+identically to \f(CW\*(C`use 5.12.0\*(C'\fR.  Previously, \f(CW\*(C`require\*(C'\fR in a \f(CW\*(C`BEGIN\*(C'\fR block
+was erroneously executing the \f(CW\*(C`use feature \*(Aq:5.12.0\*(Aq\*(C'\fR and
+\&\f(CW\*(C`use strict\*(C'\fR behaviour, which only \f(CW\*(C`use\*(C'\fR was documented to
+provide [perl #69050].
+.IP \(bu 4
+A regression introduced in Perl 5.12.0, making
+\&\f(CW\*(C`my $x = 3; $x = length(undef)\*(C'\fR result in \f(CW$x\fR set to \f(CW3\fR has been
+fixed.  \f(CW$x\fR will now be \f(CW\*(C`undef\*(C'\fR [perl #85508] (5.12.2).
+.IP \(bu 4
+When strict "refs" mode is off, \f(CW\*(C`%{...}\*(C'\fR in rvalue context returns
+\&\f(CW\*(C`undef\*(C'\fR if its argument is undefined.  An optimisation introduced in Perl
+5.12.0 to make \f(CW\*(C`keys %{...}\*(C'\fR faster when used as a boolean did not take
+this into account, causing \f(CW\*(C`keys %{+undef}\*(C'\fR (and \f(CW\*(C`keys %$foo\*(C'\fR when
+\&\f(CW$foo\fR is undefined) to be an error, which it should be so in strict
+mode only [perl #81750].
+.IP \(bu 4
+Constant-folding used to cause
+.Sp
+.Vb 1
+\&  $text =~ ( 1 ? /phoo/ : /bear/)
+.Ve
+.Sp
+to turn into
+.Sp
+.Vb 1
+\&  $text =~ /phoo/
+.Ve
+.Sp
+at compile time.  Now it correctly matches against \f(CW$_\fR [perl #20444].
+.IP \(bu 4
+Parsing Perl code (either with string \f(CW\*(C`eval\*(C'\fR or by loading modules) from
+within a \f(CW\*(C`UNITCHECK\*(C'\fR block no longer causes the interpreter to crash
+[perl #70614].
+.IP \(bu 4
+String \f(CW\*(C`eval\*(C'\fRs no longer fail after 2 billion scopes have been
+compiled [perl #83364].
+.IP \(bu 4
+The parser no longer hangs when encountering certain Unicode characters,
+such as U+387 [perl #74022].
+.IP \(bu 4
+Defining a constant with the same name as one of Perl's special blocks
+(like \f(CW\*(C`INIT\*(C'\fR) stopped working in 5.12.0, but has now been fixed
+[perl #78634].
+.IP \(bu 4
+A reference to a literal value used as a hash key (\f(CW$hash{\e"foo"}\fR) used
+to be stringified, even if the hash was tied [perl #79178].
+.IP \(bu 4
+A closure containing an \f(CW\*(C`if\*(C'\fR statement followed by a constant or variable
+is no longer treated as a constant [perl #63540].
+.IP \(bu 4
+\&\f(CW\*(C`state\*(C'\fR can now be used with attributes.  It
+used to mean the same thing as
+\&\f(CW\*(C`my\*(C'\fR if any attributes were present [perl #68658].
+.IP \(bu 4
+Expressions like \f(CW\*(C`@$a > 3\*(C'\fR no longer cause \f(CW$a\fR to be mentioned in
+the "Use of uninitialized value in numeric gt" warning when \f(CW$a\fR is
+undefined (since it is not part of the \f(CW\*(C`>\*(C'\fR expression, but the operand
+of the \f(CW\*(C`@\*(C'\fR) [perl #72090].
+.IP \(bu 4
+Accessing an element of a package array with a hard-coded number (as
+opposed to an arbitrary expression) would crash if the array did not exist.
+Usually the array would be autovivified during compilation, but typeglob
+manipulation could remove it, as in these two cases which used to crash:
+.Sp
+.Vb 2
+\&  *d = *a;  print $d[0];
+\&  undef *d; print $d[0];
+.Ve
+.IP \(bu 4
+The \fB\-C\fR command-line option, when used on the shebang line, can now be
+followed by other options [perl #72434].
+.IP \(bu 4
+The \f(CW\*(C`B\*(C'\fR module was returning \f(CW\*(C`B::OP\*(C'\fRs instead of \f(CW\*(C`B::LOGOP\*(C'\fRs for
+\&\f(CW\*(C`entertry\*(C'\fR [perl #80622].  This was due to a bug in the Perl core,
+not in \f(CW\*(C`B\*(C'\fR itself.
+.SS "Stashes, Globs and Method Lookup"
+.IX Subsection "Stashes, Globs and Method Lookup"
+Perl 5.10.0 introduced a new internal mechanism for caching MROs (method
+resolution orders, or lists of parent classes; aka "isa" caches) to make
+method lookup faster (so \f(CW@ISA\fR arrays would not have to be searched
+repeatedly).  Unfortunately, this brought with it quite a few bugs.  Almost
+all of these have been fixed now, along with a few MRO-related bugs that
+existed before 5.10.0:
+.IP \(bu 4
+The following used to have erratic effects on method resolution, because
+the "isa" caches were not reset or otherwise ended up listing the wrong
+classes.  These have been fixed.
+.RS 4
+.IP "Aliasing packages by assigning to globs [perl #77358]" 4
+.IX Item "Aliasing packages by assigning to globs [perl #77358]"
+.PD 0
+.IP "Deleting packages by deleting their containing stash elements" 4
+.IX Item "Deleting packages by deleting their containing stash elements"
+.ie n .IP "Undefining the glob containing a package (""undef *Foo::"")" 4
+.el .IP "Undefining the glob containing a package (\f(CWundef *Foo::\fR)" 4
+.IX Item "Undefining the glob containing a package (undef *Foo::)"
+.ie n .IP "Undefining an ISA glob (""undef *Foo::ISA"")" 4
+.el .IP "Undefining an ISA glob (\f(CWundef *Foo::ISA\fR)" 4
+.IX Item "Undefining an ISA glob (undef *Foo::ISA)"
+.ie n .IP "Deleting an ISA stash element (""delete $Foo::{ISA}"")" 4
+.el .IP "Deleting an ISA stash element (\f(CWdelete $Foo::{ISA}\fR)" 4
+.IX Item "Deleting an ISA stash element (delete $Foo::{ISA})"
+.ie n .IP "Sharing @ISA arrays between classes (via ""*Foo::ISA = \e@Bar::ISA"" or ""*Foo::ISA = *Bar::ISA"") [perl #77238]" 4
+.el .IP "Sharing \f(CW@ISA\fR arrays between classes (via \f(CW*Foo::ISA = \e@Bar::ISA\fR or \f(CW*Foo::ISA = *Bar::ISA\fR) [perl #77238]" 4
+.IX Item "Sharing @ISA arrays between classes (via *Foo::ISA = @Bar::ISA or *Foo::ISA = *Bar::ISA) [perl #77238]"
+.RE
+.RS 4
+.PD
+.Sp
+\&\f(CW\*(C`undef *Foo::ISA\*(C'\fR would even stop a new \f(CW@Foo::ISA\fR array from updating
+caches.
+.RE
+.IP \(bu 4
+Typeglob assignments would crash if the glob's stash no longer existed, so
+long as the glob assigned to were named \f(CW\*(C`ISA\*(C'\fR or the glob on either side of
+the assignment contained a subroutine.
+.IP \(bu 4
+\&\f(CW\*(C`PL_isarev\*(C'\fR, which is accessible to Perl via \f(CW\*(C`mro::get_isarev\*(C'\fR is now
+updated properly when packages are deleted or removed from the \f(CW@ISA\fR of
+other classes.  This allows many packages to be created and deleted without
+causing a memory leak [perl #75176].
+.PP
+In addition, various other bugs related to typeglobs and stashes have been
+fixed:
+.IP \(bu 4
+Some work has been done on the internal pointers that link between symbol
+tables (stashes), typeglobs, and subroutines.  This has the effect that
+various edge cases related to deleting stashes or stash entries (for example,
+<%FOO:: = ()>), and complex typeglob or code-reference aliasing, will no
+longer crash the interpreter.
+.IP \(bu 4
+Assigning a reference to a glob copy now assigns to a glob slot instead of
+overwriting the glob with a scalar [perl #1804] [perl #77508].
+.IP \(bu 4
+A bug when replacing the glob of a loop variable within the loop has been fixed
+[perl #21469].  This
+means the following code will no longer crash:
+.Sp
+.Vb 3
+\&    for $x (...) {
+\&        *x = *y;
+\&    }
+.Ve
+.IP \(bu 4
+Assigning a glob to a PVLV used to convert it to a plain string.  Now it
+works correctly, and a PVLV can hold a glob.  This would happen when a
+nonexistent hash or array element was passed to a subroutine:
+.Sp
+.Vb 2
+\&  sub { $_[0] = *foo }\->($hash{key});
+\&  # $_[0] would have been the string "*main::foo"
+.Ve
+.Sp
+It also happened when a glob was assigned to, or returned from, an element
+of a tied array or hash [perl #36051].
+.IP \(bu 4
+When trying to report \f(CW\*(C`Use of uninitialized value $Foo::BAR\*(C'\fR, crashes could
+occur if the glob holding the global variable in question had been detached
+from its original stash by, for example, \f(CW\*(C`delete $::{"Foo::"}\*(C'\fR.  This has
+been fixed by disabling the reporting of variable names in those
+cases.
+.IP \(bu 4
+During the restoration of a localised typeglob on scope exit, any
+destructors called as a result would be able to see the typeglob in an
+inconsistent state, containing freed entries, which could result in a
+crash.  This would affect code like this:
+.Sp
+.Vb 5
+\&  local *@;
+\&  eval { die bless [] }; # puts an object in $@
+\&  sub DESTROY {
+\&    local $@; # boom
+\&  }
+.Ve
+.Sp
+Now the glob entries are cleared before any destructors are called.  This
+also means that destructors can vivify entries in the glob.  So Perl tries
+again and, if the entries are re-created too many times, dies with a
+"panic: gp_free ..." error message.
+.IP \(bu 4
+If a typeglob is freed while a subroutine attached to it is still
+referenced elsewhere, the subroutine is renamed to \f(CW\*(C`_\|_ANON_\|_\*(C'\fR in the same
+package, unless the package has been undefined, in which case the \f(CW\*(C`_\|_ANON_\|_\*(C'\fR
+package is used.  This could cause packages to be sometimes autovivified,
+such as if the package had been deleted.  Now this no longer occurs.
+The \f(CW\*(C`_\|_ANON_\|_\*(C'\fR package is also now used when the original package is
+no longer attached to the symbol table.  This avoids memory leaks in some
+cases [perl #87664].
+.IP \(bu 4
+Subroutines and package variables inside a package whose name ends with
+\&\f(CW\*(C`::\*(C'\fR can now be accessed with a fully qualified name.
+.SS Unicode
+.IX Subsection "Unicode"
+.IP \(bu 4
+What has become known as "the Unicode Bug" is almost completely resolved in
+this release.  Under \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR (which is
+automatically selected by \f(CW\*(C`use 5.012\*(C'\fR and above), the internal
+storage format of a string no longer affects the external semantics.
+[perl #58182].
+.Sp
+There are two known exceptions:
+.RS 4
+.IP 1. 4
+The now-deprecated, user-defined case-changing
+functions require utf8\-encoded strings to operate.  The CPAN module
+Unicode::Casing has been written to replace this feature without its
+drawbacks, and the feature is scheduled to be removed in 5.16.
+.IP 2. 4
+\&\fBquotemeta()\fR (and its in-line equivalent \f(CW\*(C`\eQ\*(C'\fR) can also give different
+results depending on whether a string is encoded in UTF\-8.  See
+"The "Unicode Bug"" in perlunicode.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Handling of Unicode non-character code points has changed.
+Previously they were mostly considered illegal, except that in some
+place only one of the 66 of them was known.  The Unicode Standard
+considers them all legal, but forbids their "open interchange".
+This is part of the change to allow internal use of any code
+point (see "Core Enhancements").  Together, these changes resolve
+[perl #38722], [perl #51918], [perl #51936], and [perl #63446].
+.IP \(bu 4
+Case-insensitive \f(CW"/i"\fR regular expression matching of Unicode
+characters that match multiple characters now works much more as
+intended.  For example
+.Sp
+.Vb 1
+\& "\eN{LATIN SMALL LIGATURE FFI}" =~ /ffi/ui
+.Ve
+.Sp
+and
+.Sp
+.Vb 1
+\& "ffi" =~ /\eN{LATIN SMALL LIGATURE FFI}/ui
+.Ve
+.Sp
+are both true.  Previously, there were many bugs with this feature.
+What hasn't been fixed are the places where the pattern contains the
+multiple characters, but the characters are split up by other things,
+such as in
+.Sp
+.Vb 1
+\& "\eN{LATIN SMALL LIGATURE FFI}" =~ /(f)(f)i/ui
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\& "\eN{LATIN SMALL LIGATURE FFI}" =~ /ffi*/ui
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\& "\eN{LATIN SMALL LIGATURE FFI}" =~ /[a\-f][f\-m][g\-z]/ui
+.Ve
+.Sp
+None of these match.
+.Sp
+Also, this matching doesn't fully conform to the current Unicode
+Standard, which asks that the matching be made upon the NFD
+(Normalization Form Decomposed) of the text.  However, as of this
+writing (April 2010), the Unicode Standard is currently in flux about
+what they will recommend doing with regard in such scenarios.  It may be
+that they will throw out the whole concept of multi-character matches.
+[perl #71736].
+.IP \(bu 4
+Naming a deprecated character in \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR no longer leaks memory.
+.IP \(bu 4
+We fixed a bug that could cause \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR constructs followed by
+a single \f(CW"."\fR to be parsed incorrectly [perl #74978] (5.12.1).
+.IP \(bu 4
+\&\f(CW\*(C`chop\*(C'\fR now correctly handles characters above \f(CW"\ex{7fffffff}"\fR
+[perl #73246].
+.IP \(bu 4
+Passing to \f(CW\*(C`index\*(C'\fR an offset beyond the end of the string when the string
+is encoded internally in UTF8 no longer causes panics [perl #75898].
+.IP \(bu 4
+\&\fBwarn()\fR and \fBdie()\fR now respect utf8\-encoded scalars [perl #45549].
+.IP \(bu 4
+Sometimes the UTF8 length cache would not be reset on a value
+returned by substr, causing \f(CW\*(C`length(substr($uni_string, ...))\*(C'\fR to give
+wrong answers.  With \f(CW\*(C`${^UTF8CACHE}\*(C'\fR set to \-1, it would also produce
+a "panic" error message [perl #77692].
+.SS "Ties, Overloading and Other Magic"
+.IX Subsection "Ties, Overloading and Other Magic"
+.IP \(bu 4
+Overloading now works properly in conjunction with tied
+variables.  What formerly happened was that most ops checked their
+arguments for overloading \fIbefore\fR checking for magic, so for example
+an overloaded object returned by a tied array access would usually be
+treated as not overloaded [RT #57012].
+.IP \(bu 4
+Various instances of magic (like tie methods) being called on tied variables
+too many or too few times have been fixed:
+.RS 4
+.IP \(bu 4
+\&\f(CW$tied\->()\fR did not always call FETCH [perl #8438].
+.IP \(bu 4
+Filetest operators and \f(CW\*(C`y///\*(C'\fR and \f(CW\*(C`tr///\*(C'\fR were calling FETCH too
+many times.
+.IP \(bu 4
+The \f(CW\*(C`=\*(C'\fR operator used to ignore magic on its right-hand side if the
+scalar happened to hold a typeglob (if a typeglob was the last thing
+returned from or assigned to a tied scalar) [perl #77498].
+.IP \(bu 4
+Dereference operators used to ignore magic if the argument was a
+reference already (such as from a previous FETCH) [perl #72144].
+.IP \(bu 4
+\&\f(CW\*(C`splice\*(C'\fR now calls set-magic (so changes made
+by \f(CW\*(C`splice @ISA\*(C'\fR are respected by method calls) [perl #78400].
+.IP \(bu 4
+In-memory files created by \f(CW\*(C`open($fh, ">", \e$buffer)\*(C'\fR were not calling
+FETCH/STORE at all [perl #43789] (5.12.2).
+.IP \(bu 4
+\&\fButf8::is_utf8()\fR now respects get-magic (like \f(CW$1\fR) (5.12.1).
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Non-commutative binary operators used to swap their operands if the same
+tied scalar was used for both operands and returned a different value for
+each FETCH.  For instance, if \f(CW$t\fR returned 2 the first time and 3 the
+second, then \f(CW\*(C`$t/$t\*(C'\fR would evaluate to 1.5.  This has been fixed
+[perl #87708].
+.IP \(bu 4
+String \f(CW\*(C`eval\*(C'\fR now detects taintedness of overloaded or tied
+arguments [perl #75716].
+.IP \(bu 4
+String \f(CW\*(C`eval\*(C'\fR and regular expression matches against objects with string
+overloading no longer cause memory corruption or crashes [perl #77084].
+.IP \(bu 4
+readline now honors \f(CW\*(C`<>\*(C'\fR overloading on tied
+arguments.
+.IP \(bu 4
+\&\f(CW\*(C`<expr>\*(C'\fR always respects overloading now if the expression is
+overloaded.
+.Sp
+Because "<>\ as glob" was parsed differently from
+"<>\ as filehandle" from 5.6 onwards, something like \f(CW\*(C`<$foo[0]>\*(C'\fR did
+not handle overloading, even if \f(CW$foo[0]\fR was an overloaded object.  This
+was contrary to the documentation for overload, and meant that \f(CW\*(C`<>\*(C'\fR
+could not be used as a general overloaded iterator operator.
+.IP \(bu 4
+The fallback behaviour of overloading on binary operators was asymmetric
+[perl #71286].
+.IP \(bu 4
+Magic applied to variables in the main package no longer affects other packages.
+See "Magic variables outside the main package" above [perl #76138].
+.IP \(bu 4
+Sometimes magic (ties, taintedness, etc.) attached to variables could cause
+an object to last longer than it should, or cause a crash if a tied
+variable were freed from within a tie method.  These have been fixed
+[perl #81230].
+.IP \(bu 4
+DESTROY methods of objects implementing ties are no longer able to crash by
+accessing the tied variable through a weak reference [perl #86328].
+.IP \(bu 4
+Fixed a regression of \fBkill()\fR when a match variable is used for the
+process ID to kill [perl #75812].
+.IP \(bu 4
+\&\f(CW$AUTOLOAD\fR used to remain tainted forever if it ever became tainted.  Now
+it is correctly untainted if an autoloaded method is called and the method
+name was not tainted.
+.IP \(bu 4
+\&\f(CW\*(C`sprintf\*(C'\fR now dies when passed a tainted scalar for the format.  It did
+already die for arbitrary expressions, but not for simple scalars
+[perl #82250].
+.IP \(bu 4
+\&\f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, and \f(CW\*(C`ucfirst\*(C'\fR no longer return untainted strings
+when the argument is tainted.  This has been broken since perl 5.8.9
+[perl #87336].
+.SS "The Debugger"
+.IX Subsection "The Debugger"
+.IP \(bu 4
+The Perl debugger now also works in taint mode [perl #76872].
+.IP \(bu 4
+Subroutine redefinition works once more in the debugger [perl #48332].
+.IP \(bu 4
+When \fB\-d\fR is used on the shebang (\f(CW\*(C`#!\*(C'\fR) line, the debugger now has access
+to the lines of the main program.  In the past, this sometimes worked and
+sometimes did not, depending on the order in which things happened to be
+arranged in memory [perl #71806].
+.IP \(bu 4
+A possible memory leak when using \fBcaller()\fR to set
+\&\f(CW@DB::args\fR has been fixed (5.12.2).
+.IP \(bu 4
+Perl no longer stomps on \f(CW$DB::single\fR, \f(CW$DB::trace\fR, and \f(CW$DB::signal\fR 
+if these variables already have values when \f(CW$^P\fR is assigned to [perl #72422].
+.IP \(bu 4
+\&\f(CW\*(C`#line\*(C'\fR directives in string evals were not properly updating the arrays
+of lines of code (\f(CW\*(C`@{"_< ..."}\*(C'\fR) that the debugger (or any debugging or
+profiling module) uses.  In threaded builds, they were not being updated at
+all.  In non-threaded builds, the line number was ignored, so any change to
+the existing line number would cause the lines to be misnumbered
+[perl #79442].
+.SS Threads
+.IX Subsection "Threads"
+.IP \(bu 4
+Perl no longer accidentally clones lexicals in scope within active stack
+frames in the parent when creating a child thread [perl #73086].
+.IP \(bu 4
+Several memory leaks in cloning and freeing threaded Perl interpreters have been
+fixed [perl #77352].
+.IP \(bu 4
+Creating a new thread when directory handles were open used to cause a
+crash, because the handles were not cloned, but simply passed to the new
+thread, resulting in a double free.
+.Sp
+Now directory handles are cloned properly on Windows
+and on systems that have a \f(CW\*(C`fchdir\*(C'\fR function.  On other
+systems, new threads simply do not inherit directory
+handles from their parent threads [perl #75154].
+.IP \(bu 4
+The typeglob \f(CW\*(C`*,\*(C'\fR, which holds the scalar variable \f(CW$,\fR (output field
+separator), had the wrong reference count in child threads.
+.IP \(bu 4
+[perl #78494] When pipes are shared between threads, the \f(CW\*(C`close\*(C'\fR function
+(and any implicit close, such as on thread exit) no longer blocks.
+.IP \(bu 4
+Perl now does a timely cleanup of SVs that are cloned into a new
+thread but then discovered to be orphaned (that is, their owners
+are \fInot\fR cloned).  This eliminates several "scalars leaked"
+warnings when joining threads.
+.SS "Scoping and Subroutines"
+.IX Subsection "Scoping and Subroutines"
+.IP \(bu 4
+Lvalue subroutines are again able to return copy-on-write scalars.  This
+had been broken since version 5.10.0 [perl #75656] (5.12.3).
+.IP \(bu 4
+\&\f(CW\*(C`require\*(C'\fR no longer causes \f(CW\*(C`caller\*(C'\fR to return the wrong file name for
+the scope that called \f(CW\*(C`require\*(C'\fR and other scopes higher up that had the
+same file name [perl #68712].
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR with a \f(CW\*(C`($$)\*(C'\fR\-prototyped comparison routine used to cause the value
+of \f(CW@_\fR to leak out of the sort.  Taking a reference to \f(CW@_\fR within the
+sorting routine could cause a crash [perl #72334].
+.IP \(bu 4
+Match variables (like \f(CW$1\fR) no longer persist between calls to a sort
+subroutine [perl #76026].
+.IP \(bu 4
+Iterating with \f(CW\*(C`foreach\*(C'\fR over an array returned by an lvalue sub now works
+[perl #23790].
+.IP \(bu 4
+\&\f(CW$@\fR is now localised during calls to \f(CW\*(C`binmode\*(C'\fR to prevent action at a
+distance [perl #78844].
+.IP \(bu 4
+Calling a closure prototype (what is passed to an attribute handler for a
+closure) now results in a "Closure prototype called" error message instead
+of a crash [perl #68560].
+.IP \(bu 4
+Mentioning a read-only lexical variable from the enclosing scope in a
+string \f(CW\*(C`eval\*(C'\fR no longer causes the variable to become writable
+[perl #19135].
+.SS Signals
+.IX Subsection "Signals"
+.IP \(bu 4
+Within signal handlers, \f(CW$!\fR is now implicitly localized.
+.IP \(bu 4
+CHLD signals are no longer unblocked after a signal handler is called if
+they were blocked before by \f(CW\*(C`POSIX::sigprocmask\*(C'\fR [perl #82040].
+.IP \(bu 4
+A signal handler called within a signal handler could cause leaks or
+double-frees.  Now fixed [perl #76248].
+.SS "Miscellaneous Memory Leaks"
+.IX Subsection "Miscellaneous Memory Leaks"
+.IP \(bu 4
+Several memory leaks when loading XS modules were fixed (5.12.2).
+.IP \(bu 4
+\&\fBsubstr()\fR,
+\&\fBpos()\fR, \fBkeys()\fR,
+and \fBvec()\fR could, when used in combination
+with lvalues, result in leaking the scalar value they operate on, and cause its
+destruction to happen too late.  This has now been fixed.
+.IP \(bu 4
+The postincrement and postdecrement operators, \f(CW\*(C`++\*(C'\fR and \f(CW\*(C`\-\-\*(C'\fR, used to cause
+leaks when used on references.  This has now been fixed.
+.IP \(bu 4
+Nested \f(CW\*(C`map\*(C'\fR and \f(CW\*(C`grep\*(C'\fR blocks no longer leak memory when processing
+large lists [perl #48004].
+.IP \(bu 4
+\&\f(CW\*(C`use \fR\f(CIVERSION\fR\f(CW\*(C'\fR and \f(CW\*(C`no \fR\f(CIVERSION\fR\f(CW\*(C'\fR no longer leak memory [perl #78436]
+[perl #69050].
+.IP \(bu 4
+\&\f(CW\*(C`.=\*(C'\fR followed by \f(CW\*(C`<>\*(C'\fR or \f(CW\*(C`readline\*(C'\fR would leak memory if \f(CW$/\fR
+contained characters beyond the octet range and the scalar assigned to
+happened to be encoded as UTF8 internally [perl #72246].
+.IP \(bu 4
+\&\f(CW\*(C`eval \*(AqBEGIN{die}\*(Aq\*(C'\fR no longer leaks memory on non-threaded builds.
+.SS "Memory Corruption and Crashes"
+.IX Subsection "Memory Corruption and Crashes"
+.IP \(bu 4
+\&\fBglob()\fR no longer crashes when \f(CW%File::Glob::\fR is empty and
+\&\f(CW\*(C`CORE::GLOBAL::glob\*(C'\fR isn't present [perl #75464] (5.12.2).
+.IP \(bu 4
+\&\fBreadline()\fR has been fixed when interrupted by signals so it no longer
+returns the "same thing" as before or random memory.
+.IP \(bu 4
+When assigning a list with duplicated keys to a hash, the assignment used to
+return garbage and/or freed values:
+.Sp
+.Vb 1
+\&    @a = %h = (list with some duplicate keys);
+.Ve
+.Sp
+This has now been fixed [perl #31865].
+.IP \(bu 4
+The mechanism for freeing objects in globs used to leave dangling
+pointers to freed SVs, meaning Perl users could see corrupted state
+during destruction.
+.Sp
+Perl now frees only the affected slots of the GV, rather than freeing
+the GV itself.  This makes sure that there are no dangling refs or
+corrupted state during destruction.
+.IP \(bu 4
+The interpreter no longer crashes when freeing deeply-nested arrays of
+arrays.  Hashes have not been fixed yet [perl #44225].
+.IP \(bu 4
+Concatenating long strings under \f(CW\*(C`use encoding\*(C'\fR no longer causes Perl to
+crash [perl #78674].
+.IP \(bu 4
+Calling \f(CW\*(C`\->import\*(C'\fR on a class lacking an import method could corrupt
+the stack, resulting in strange behaviour.  For instance,
+.Sp
+.Vb 1
+\&  push @a, "foo", $b = bar\->import;
+.Ve
+.Sp
+would assign "foo" to \f(CW$b\fR [perl #63790].
+.IP \(bu 4
+The \f(CW\*(C`recv\*(C'\fR function could crash when called with the MSG_TRUNC flag
+[perl #75082].
+.IP \(bu 4
+\&\f(CW\*(C`formline\*(C'\fR no longer crashes when passed a tainted format picture.  It also
+taints \f(CW$^A\fR now if its arguments are tainted [perl #79138].
+.IP \(bu 4
+A bug in how we process filetest operations could cause a segfault.
+Filetests don't always expect an op on the stack, so we now use
+TOPs only if we're sure that we're not \f(CW\*(C`stat\*(C'\fRing the \f(CW\*(C`_\*(C'\fR filehandle.
+This is indicated by \f(CW\*(C`OPf_KIDS\*(C'\fR (as checked in ck_ftst) [perl #74542]
+(5.12.1).
+.IP \(bu 4
+\&\fBunpack()\fR now handles scalar context correctly for \f(CW%32H\fR and \f(CW%32u\fR,
+fixing a potential crash.  \fBsplit()\fR would crash because the third item
+on the stack wasn't the regular expression it expected.  \f(CW\*(C`unpack("%2H",
+\&...)\*(C'\fR would return both the unpacked result and the checksum on the stack,
+as would \f(CW\*(C`unpack("%2u", ...)\*(C'\fR [perl #73814] (5.12.2).
+.SS "Fixes to Various Perl Operators"
+.IX Subsection "Fixes to Various Perl Operators"
+.IP \(bu 4
+The \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, and \f(CW\*(C`^\*(C'\fR bitwise operators no longer coerce read-only arguments
+[perl #20661].
+.IP \(bu 4
+Stringifying a scalar containing "\-0.0" no longer has the effect of turning
+false into true [perl #45133].
+.IP \(bu 4
+Some numeric operators were converting integers to floating point,
+resulting in loss of precision on 64\-bit platforms [perl #77456].
+.IP \(bu 4
+\&\fBsprintf()\fR was ignoring locales when called with constant arguments
+[perl #78632].
+.IP \(bu 4
+Combining the vector (\f(CW%v\fR) flag and dynamic precision would
+cause \f(CW\*(C`sprintf\*(C'\fR to confuse the order of its arguments, making it 
+treat the string as the precision and vice-versa [perl #83194].
+.SS "Bugs Relating to the C API"
+.IX Subsection "Bugs Relating to the C API"
+.IP \(bu 4
+The C\-level \f(CW\*(C`lex_stuff_pvn\*(C'\fR function would sometimes cause a spurious
+syntax error on the last line of the file if it lacked a final semicolon
+[perl #74006] (5.12.1).
+.IP \(bu 4
+The \f(CW\*(C`eval_sv\*(C'\fR and \f(CW\*(C`eval_pv\*(C'\fR C functions now set \f(CW$@\fR correctly when
+there is a syntax error and no \f(CW\*(C`G_KEEPERR\*(C'\fR flag, and never set it if the
+\&\f(CW\*(C`G_KEEPERR\*(C'\fR flag is present [perl #3719].
+.IP \(bu 4
+The XS multicall API no longer causes subroutines to lose reference counts
+if called via the multicall interface from within those very subroutines.
+This affects modules like List::Util.  Calling one of its functions with an
+active subroutine as the first argument could cause a crash [perl #78070].
+.IP \(bu 4
+The \f(CW\*(C`SvPVbyte\*(C'\fR function available to XS modules now calls magic before
+downgrading the SV, to avoid warnings about wide characters [perl #72398].
+.IP \(bu 4
+The ref types in the typemap for XS bindings now support magical variables
+[perl #72684].
+.IP \(bu 4
+\&\f(CW\*(C`sv_catsv_flags\*(C'\fR no longer calls \f(CW\*(C`mg_get\*(C'\fR on its second argument (the
+source string) if the flags passed to it do not include SV_GMAGIC.  So it
+now matches the documentation.
+.IP \(bu 4
+\&\f(CW\*(C`my_strftime\*(C'\fR no longer leaks memory.  This fixes a memory leak in
+\&\f(CW\*(C`POSIX::strftime\*(C'\fR [perl #73520].
+.IP \(bu 4
+\&\fIXSUB.h\fR now correctly redefines fgets under PERL_IMPLICIT_SYS [perl #55049]
+(5.12.1).
+.IP \(bu 4
+XS code using \fBfputc()\fR or \fBfputs()\fR on Windows could cause an error
+due to their arguments being swapped [perl #72704] (5.12.1).
+.IP \(bu 4
+A possible segfault in the \f(CW\*(C`T_PTROBJ\*(C'\fR default typemap has been fixed
+(5.12.2).
+.IP \(bu 4
+A bug that could cause "Unknown error" messages when
+\&\f(CW\*(C`call_sv(code, G_EVAL)\*(C'\fR is called from an XS destructor has been fixed
+(5.12.2).
+.SH "Known Problems"
+.IX Header "Known Problems"
+This is a list of significant unresolved issues which are regressions
+from earlier versions of Perl or which affect widely-used CPAN modules.
+.IP \(bu 4
+\&\f(CW\*(C`List::Util::first\*(C'\fR misbehaves in the presence of a lexical \f(CW$_\fR
+(typically introduced by \f(CW\*(C`my $_\*(C'\fR or implicitly by \f(CW\*(C`given\*(C'\fR).  The variable
+that gets set for each iteration is the package variable \f(CW$_\fR, not the
+lexical \f(CW$_\fR.
+.Sp
+A similar issue may occur in other modules that provide functions which
+take a block as their first argument, like
+.Sp
+.Vb 1
+\&    foo { ... $_ ...} list
+.Ve
+.Sp
+See also: <https://github.com/Perl/perl5/issues/9798>
+.IP \(bu 4
+\&\fBreadline()\fR returns an empty string instead of a cached previous value
+when it is interrupted by a signal
+.IP \(bu 4
+The changes in prototype handling break Switch.  A patch has been sent
+upstream and will hopefully appear on CPAN soon.
+.IP \(bu 4
+The upgrade to \fIExtUtils\-MakeMaker\-6.57_05\fR has caused
+some tests in the \fIModule-Install\fR distribution on CPAN to
+fail. (Specifically, \fI02_mymeta.t\fR tests 5 and 21; \fI18_all_from.t\fR
+tests 6 and 15; \fI19_authors.t\fR tests 5, 13, 21, and 29; and
+\&\fI20_authors_with_special_characters.t\fR tests 6, 15, and 23 in version
+1.00 of that distribution now fail.)
+.IP \(bu 4
+On VMS, \f(CW\*(C`Time::HiRes\*(C'\fR tests will fail due to a bug in the CRTL's
+implementation of \f(CW\*(C`setitimer\*(C'\fR: previous timer values would be cleared
+if a timer expired but not if the timer was reset before expiring.  HP
+OpenVMS Engineering have corrected the problem and will release a patch
+in due course (Quix case # QXCM1001115136).
+.IP \(bu 4
+On VMS, there were a handful of \f(CW\*(C`Module::Build\*(C'\fR test failures we didn't
+get to before the release; please watch CPAN for updates.
+.SH Errata
+.IX Header "Errata"
+.SS "\fBkeys()\fP, \fBvalues()\fP, and \fBeach()\fP work on arrays"
+.IX Subsection "keys(), values(), and each() work on arrays"
+You can now use the \fBkeys()\fR, \fBvalues()\fR, and \fBeach()\fR builtins on arrays;
+previously you could use them only on hashes.  See perlfunc for details.
+This is actually a change introduced in perl 5.12.0, but it was missed from
+that release's perl5120delta.
+.ie n .SS "\fBsplit()\fP and @_"
+.el .SS "\fBsplit()\fP and \f(CW@_\fP"
+.IX Subsection "split() and @_"
+\&\fBsplit()\fR no longer modifies \f(CW@_\fR when called in scalar or void context.
+In void context it now produces a "Useless use of split" warning.
+This was also a perl 5.12.0 change that missed the perldelta.
+.SH Obituary
+.IX Header "Obituary"
+Randy Kobes, creator of http://kobesearch.cpan.org/ and
+contributor/maintainer to several core Perl toolchain modules, passed
+away on September 18, 2010 after a battle with lung cancer.  The community
+was richer for his involvement.  He will be missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.14.0 represents one year of development since
+Perl 5.12.0 and contains nearly 550,000 lines of changes across nearly
+3,000 files from 150 authors and committers.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.14.0:
+.PP
+Aaron Crane, Abhijit Menon-Sen, Abigail, Ævar Arnfjörð Bjarmason,
+Alastair Douglas, Alexander Alekseev, Alexander Hartmaier, Alexandr
+Ciornii, Alex Davies, Alex Vandiver, Ali Polatel, Allen Smith, Andreas
+König, Andrew Rodland, Andy Armstrong, Andy Dougherty, Aristotle
+Pagaltzis, Arkturuz, Arvan, A. Sinan Unur, Ben Morrow, Bo Lindbergh,
+Boris Ratner, Brad Gilbert, Bram, brian d foy, Brian Phillips, Casey
+West, Charles Bailey, Chas. Owens, Chip Salzenberg, Chris 'BinGOs'
+Williams, chromatic, Craig A. Berry, Curtis Jewell, Dagfinn Ilmari
+Mannsåker, Dan Dascalescu, Dave Rolsky, David Caldwell, David Cantrell,
+David Golden, David Leadbeater, David Mitchell, David Wheeler, Eric
+Brine, Father Chrysostomos, Fingle Nark, Florian Ragwitz, Frank Wiegand,
+Franz Fasching, Gene Sullivan, George Greer, Gerard Goossen, Gisle Aas,
+Goro Fuji, Grant McLean, gregor herrmann, H.Merijn Brand, Hongwen Qiu,
+Hugo van der Sanden, Ian Goodacre, James E Keenan, James Mastros, Jan
+Dubois, Jay Hannah, Jerry D. Hedden, Jesse Vincent, Jim Cromie, Jirka
+Hruška, John Peacock, Joshua ben Jore, Joshua Pritikin, Karl Williamson,
+Kevin Ryde, kmx, Lars Dɪᴇᴄᴋ�ᴡ 迪拉斯, Larwan Berke, Leon Brocard, Leon
+Timmermans, Lubomir Rintel, Lukas Mai, Maik Hentsche, Marty Pauley,
+Marvin Humphrey, Matt Johnson, Matt S Trout, Max Maischein, Michael
+Breen, Michael Fig, Michael G Schwern, Michael Parker, Michael Stevens,
+Michael Witten, Mike Kelly, Moritz Lenz, Nicholas Clark, Nick Cleaton,
+Nick Johnston, Nicolas Kaiser, Niko Tyni, Noirin Shirley, Nuno Carvalho,
+Paul Evans, Paul Green, Paul Johnson, Paul Marquess, Peter J. Holzer,
+Peter John Acklam, Peter Martini, Philippe Bruhat (BooK), Piotr Fusik,
+Rafael Garcia-Suarez, Rainer Tammer, Reini Urban, Renee Baecker, Ricardo
+Signes, Richard Möhn, Richard Soderberg, Rob Hoelz, Robin Barker, Ruslan
+Zakirov, Salvador Fandiño, Salvador Ortiz Garcia, Shlomi Fish, Sinan
+Unur, Sisyphus, Slaven Rezic, Steffen Müller, Steve Hay, Steven
+Schubiger, Steve Peters, Sullivan Beck, Tatsuhiko Miyagawa, Tim Bunce,
+Todd Rinaldo, Tom Christiansen, Tom Hukins, Tony Cook, Tye McQueen,
+Vadim Konovalov, Vernon Lyon, Vincent Pit, Walt Mankowski, Wolfram
+Humann, Yves Orton, Zefram, and Zsbán Ambrus.
+.PP
+This is woefully incomplete as it's automatically generated from version
+control history.  In particular, it doesn't include the names of the
+(very much appreciated) contributors who reported issues in previous
+versions of Perl that helped make Perl 5.14.0 better. For a more complete
+list of all of Perl's historical contributors, please see the \f(CW\*(C`AUTHORS\*(C'\fR
+file in the Perl 5.14.0 distribution.
+.PP
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the Perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who are able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please use this address for
+security issues in the Perl core \fIonly\fR, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5141delta.1 b/upstream/mageia-cauldron/man1/perl5141delta.1
new file mode 100644
index 00000000..28536240
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5141delta.1
@@ -0,0 +1,304 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5141DELTA 1"
+.TH PERL5141DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5141delta \- what is new for perl v5.14.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.14.0 release and
+the 5.14.1 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.0, first read
+perl5140delta, which describes differences between 5.12.0 and
+5.14.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+No changes since 5.14.0.
+.SH Security
+.IX Header "Security"
+No changes since 5.14.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+.SH Deprecations
+.IX Header "Deprecations"
+There have been no deprecations since 5.14.0.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+None
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.03 to 1.04, to address two
+regressions in Perl 5.14.0:
+.Sp
+Deparsing of the \f(CW\*(C`glob\*(C'\fR operator and its diamond (\f(CW\*(C`<>\*(C'\fR) form now
+works again. [perl #90898]
+.Sp
+The presence of subroutines named \f(CW\*(C`::::\*(C'\fR or \f(CW\*(C`::::::\*(C'\fR no longer causes
+B::Deparse to hang.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.15_03 to 3.15_04.
+.Sp
+It corrects the search paths on VMS. [perl #90640]
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+None
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+None
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+\&\f(CW\*(C`given\*(C'\fR, \f(CW\*(C`when\*(C'\fR and \f(CW\*(C`default\*(C'\fR are now listed in perlfunc.
+.IP \(bu 4
+Documentation for \f(CW\*(C`use\*(C'\fR now includes a pointer to \fIif.pm\fR.
+.PP
+\fIperllol\fR
+.IX Subsection "perllol"
+.IP \(bu 4
+perllol has been expanded with examples using the new \f(CW\*(C`push $scalar\*(C'\fR
+syntax introduced in Perl 5.14.0.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+The explanation of bitwise operators has been expanded to explain how they
+work on Unicode strings.
+.IP \(bu 4
+The section on the triple-dot or yada-yada operator has been moved up, as
+it used to separate two closely related sections about the comma operator.
+.IP \(bu 4
+More examples for \f(CW\*(C`m//g\*(C'\fR have been added.
+.IP \(bu 4
+The \f(CW\*(C`<<\eFOO\*(C'\fR here-doc syntax has been documented.
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+perlrun has undergone a significant clean-up.  Most notably, the
+\&\fB\-0x...\fR form of the \fB\-0\fR flag has been clarified, and the final section
+on environment variables has been corrected and expanded.
+.PP
+\fIPOSIX\fR
+.IX Subsection "POSIX"
+.IP \(bu 4
+The invocation documentation for \f(CW\*(C`WIFEXITED\*(C'\fR, \f(CW\*(C`WEXITSTATUS\*(C'\fR,
+\&\f(CW\*(C`WIFSIGNALED\*(C'\fR, \f(CW\*(C`WTERMSIG\*(C'\fR, \f(CW\*(C`WIFSTOPPED\*(C'\fR, and \f(CW\*(C`WSTOPSIG\*(C'\fR was corrected.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+None
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+None
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+None
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\fIregexp.h\fR has been modified for compatibility with GCC's \f(CW\*(C`\-Werror\*(C'\fR
+option, as used by some projects that include perl's header files.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+Some test failures in \fIdist/Locale\-Maketext/t/09_compile.t\fR that could
+occur depending on the environment have been fixed. [perl #89896]
+.IP \(bu 4
+A watchdog timer for \fIt/re/re.t\fR was lengthened to accommodate SH\-4 systems
+which were unable to complete the tests before the previous timer ran out.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+None
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+None
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+\fISolaris\fR
+.IX Subsection "Solaris"
+.IP \(bu 4
+Documentation listing the Solaris packages required to build Perl on
+Solaris 9 and Solaris 10 has been corrected.
+.PP
+\fIMac OS X\fR
+.IX Subsection "Mac OS X"
+.IP \(bu 4
+The \fIlib/locale.t\fR test script has been updated to work on the upcoming
+Lion release.
+.IP \(bu 4
+Mac OS X specific compilation instructions have been clarified.
+.PP
+\fIUbuntu Linux\fR
+.IX Subsection "Ubuntu Linux"
+.IP \(bu 4
+The ODBM_File installation process has been updated with the new library
+paths on Ubuntu natty.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+The compiled representation of formats is now stored via the mg_ptr of
+their PERL_MAGIC_fm. Previously it was stored in the string buffer,
+beyond \fBSvLEN()\fR, the regular end of the string. \fBSvCOMPILED()\fR and
+SvCOMPILED_{on,off}() now exist solely for compatibility for XS code.
+The first is always 0, the other two now no-ops.
+.SH "Bug Fixes"
+.IX Header "Bug Fixes"
+.IP \(bu 4
+A bug has been fixed that would cause a "Use of freed value in iteration"
+error if the next two hash elements that would be iterated over are
+deleted. [perl #85026]
+.IP \(bu 4
+Passing the same constant subroutine to both \f(CW\*(C`index\*(C'\fR and \f(CW\*(C`formline\*(C'\fR no
+longer causes one or the other to fail. [perl #89218]
+.IP \(bu 4
+5.14.0 introduced some memory leaks in regular expression character
+classes such as \f(CW\*(C`[\ew\es]\*(C'\fR, which have now been fixed.
+.IP \(bu 4
+An edge case in regular expression matching could potentially loop.
+This happened only under \f(CW\*(C`/i\*(C'\fR in bracketed character classes that have
+characters with multi-character folds, and the target string to match
+against includes the first portion of the fold, followed by another
+character that has a multi-character fold that begins with the remaining
+portion of the fold, plus some more.
+.Sp
+.Vb 1
+\& "s\eN{U+DF}" =~ /[\ex{DF}foo]/i
+.Ve
+.Sp
+is one such case.  \f(CW\*(C`\exDF\*(C'\fR folds to \f(CW"ss"\fR.
+.IP \(bu 4
+Several Unicode case-folding bugs have been fixed.
+.IP \(bu 4
+The new (in 5.14.0) regular expression modifier \f(CW\*(C`/a\*(C'\fR when repeated like
+\&\f(CW\*(C`/aa\*(C'\fR forbids the characters outside the ASCII range that match
+characters inside that range from matching under \f(CW\*(C`/i\*(C'\fR.  This did not
+work under some circumstances, all involving alternation, such as:
+.Sp
+.Vb 1
+\& "\eN{KELVIN SIGN}" =~ /k|foo/iaa;
+.Ve
+.Sp
+succeeded inappropriately.  This is now fixed.
+.IP \(bu 4
+Fixed a case where it was possible that a freed buffer may have been read
+from when parsing a here document.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.14.1 represents approximately four weeks of development since
+Perl 5.14.0 and contains approximately 3500 lines of changes
+across 38 files from 17 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.14.1:
+.PP
+Bo Lindbergh, Claudio Ramirez, Craig A. Berry, David Leadbeater, Father
+Chrysostomos, Jesse Vincent, Jim Cromie, Justin Case, Karl Williamson,
+Leo Lapworth, Nicholas Clark, Nobuhiro Iwamatsu, smash, Tom Christiansen,
+Ton Hospel, Vladimir Timofeev, and Zsbán Ambrus.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5142delta.1 b/upstream/mageia-cauldron/man1/perl5142delta.1
new file mode 100644
index 00000000..7d23408a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5142delta.1
@@ -0,0 +1,243 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5142DELTA 1"
+.TH PERL5142DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5142delta \- what is new for perl v5.14.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.14.1 release and
+the 5.14.2 release.
+.PP
+If you are upgrading from an earlier release such as 5.14.0, first read
+perl5141delta, which describes differences between 5.14.0 and
+5.14.1.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+No changes since 5.14.0.
+.SH Security
+.IX Header "Security"
+.ie n .SS "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.el .SS "\f(CWFile::Glob::bsd_glob()\fP memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.IX Subsection "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+Calling \f(CW\*(C`File::Glob::bsd_glob\*(C'\fR with the unsupported flag GLOB_ALTDIRFUNC would
+cause an access violation / segfault.  A Perl program that accepts a flags value from
+an external source could expose itself to denial of service or arbitrary code
+execution attacks.  There are no known exploits in the wild.  The problem has been
+corrected by explicitly disabling all unsupported flags and setting unused function
+pointers to null.  Bug reported by Clément Lecigne.
+.ie n .SS """Encode"" decode_xs n\-byte heap-overflow (CVE\-2011\-2939)"
+.el .SS "\f(CWEncode\fP decode_xs n\-byte heap-overflow (CVE\-2011\-2939)"
+.IX Subsection "Encode decode_xs n-byte heap-overflow (CVE-2011-2939)"
+A bug in \f(CW\*(C`Encode\*(C'\fR could, on certain inputs, cause the heap to overflow.
+This problem has been corrected.  Bug reported by Robert Zacek.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+.SH Deprecations
+.IX Header "Deprecations"
+There have been no deprecations since 5.14.0.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+None
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+CPAN has been upgraded from version 1.9600 to version 1.9600_01.
+.Sp
+CPAN::Distribution has been upgraded from version 1.9602 to 1.9602_01.
+.Sp
+Backported bugfixes from CPAN version 1.9800.  Ensures proper
+detection of \f(CW\*(C`configure_requires\*(C'\fR prerequisites from CPAN Meta files
+in the case where \f(CW\*(C`dynamic_config\*(C'\fR is true.  [rt.cpan.org #68835]
+.Sp
+Also ensures that \f(CW\*(C`configure_requires\*(C'\fR is only checked in META files,
+not MYMETA files, so protect against MYMETA generation that drops
+\&\f(CW\*(C`configure_requires\*(C'\fR.
+.IP \(bu 4
+Encode has been upgraded from version 2.42 to 2.42_01.
+.Sp
+See "Security".
+.IP \(bu 4
+File::Glob has been upgraded from version 1.12 to version 1.13.
+.Sp
+See "Security".
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.11 to 0.11_01.
+.Sp
+It fixes a problem with \f(CW\*(C`open my $fh, ">", \e$scalar\*(C'\fR not working if
+\&\f(CW$scalar\fR is a copy-on-write scalar.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+None
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+None
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+None
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP "HP-UX PA\-RISC/64 now supports gcc\-4.x" 4
+.IX Item "HP-UX PA-RISC/64 now supports gcc-4.x"
+A fix to correct the socketsize now makes the test suite pass on HP-UX
+PA-RISC for 64bitall builds.
+.IP "Building on OS X 10.7 Lion and Xcode 4 works again" 4
+.IX Item "Building on OS X 10.7 Lion and Xcode 4 works again"
+The build system has been updated to work with the build tools under Mac OS X
+10.7.
+.SH "Bug Fixes"
+.IX Header "Bug Fixes"
+.IP \(bu 4
+In \f(CW@INC\fR filters (subroutines returned by subroutines in \f(CW@INC\fR), \f(CW$_\fR used to
+misbehave: If returned from a subroutine, it would not be copied, but the
+variable itself would be returned; and freeing \f(CW$_\fR (e.g., with \f(CW\*(C`undef *_\*(C'\fR)
+would cause perl to crash.  This has been fixed [perl #91880].
+.IP \(bu 4
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty.  This has
+been fixed [perl #90160].
+.IP \(bu 4
+\&\f(CW\*(C`caller\*(C'\fR no longer leaks memory when called from the DB package if
+\&\f(CW@DB::args\fR was assigned to after the first call to \f(CW\*(C`caller\*(C'\fR.  Carp
+was triggering this bug [perl #97010].
+.IP \(bu 4
+\&\f(CW\*(C`utf8::decode\*(C'\fR had a nasty bug that would modify copy-on-write scalars'
+string buffers in place (i.e., skipping the copy).  This could result in
+hashes having two elements with the same key [perl #91834].
+.IP \(bu 4
+Localising a tied variable used to make it read-only if it contained a
+copy-on-write string.
+.IP \(bu 4
+Elements of restricted hashes (see the fields pragma) containing
+copy-on-write values couldn't be deleted, nor could such hashes be cleared
+(\f(CW\*(C`%hash = ()\*(C'\fR).
+.IP \(bu 4
+Locking a hash element that is a glob copy no longer causes subsequent
+assignment to it to corrupt the glob.
+.IP \(bu 4
+A panic involving the combination of the regular expression modifiers
+\&\f(CW\*(C`/aa\*(C'\fR introduced in 5.14.0 and the \f(CW\*(C`\eb\*(C'\fR escape sequence has been
+fixed [perl #95964].
+.SH "Known Problems"
+.IX Header "Known Problems"
+This is a list of some significant unfixed bugs, which are regressions
+from 5.12.0.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_GLOBAL_STRUCT\*(C'\fR is broken.
+.Sp
+Since perl 5.14.0, building with \f(CW\*(C`\-DPERL_GLOBAL_STRUCT\*(C'\fR hasn't been
+possible. This means that perl currently doesn't work on any platforms that
+require it to be built this way, including Symbian.
+.Sp
+While \f(CW\*(C`PERL_GLOBAL_STRUCT\*(C'\fR now works again on recent development versions of
+perl, it actually working on Symbian again hasn't been verified.
+.Sp
+We'd be very interested in hearing from anyone working with Perl on Symbian.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.14.2 represents approximately three months of development since
+Perl 5.14.1 and contains approximately 1200 lines of changes
+across 61 files from 9 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.14.2:
+.PP
+Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn
+Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5143delta.1 b/upstream/mageia-cauldron/man1/perl5143delta.1
new file mode 100644
index 00000000..f1f33ef7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5143delta.1
@@ -0,0 +1,278 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5143DELTA 1"
+.TH PERL5143DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5143delta \- what is new for perl v5.14.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.14.2 release and
+the 5.14.3 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.0, first read
+perl5140delta, which describes differences between 5.12.0 and
+5.14.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+No changes since 5.14.0.
+.SH Security
+.IX Header "Security"
+.ie n .SS """Digest"" unsafe use of eval (CVE\-2011\-3597)"
+.el .SS "\f(CWDigest\fP unsafe use of eval (CVE\-2011\-3597)"
+.IX Subsection "Digest unsafe use of eval (CVE-2011-3597)"
+The \f(CW\*(C`Digest\->new()\*(C'\fR function did not properly sanitize input before
+using it in an \fBeval()\fR call, which could lead to the injection of arbitrary
+Perl code.
+.PP
+In order to exploit this flaw, the attacker would need to be able to set
+the algorithm name used, or be able to execute arbitrary Perl code already.
+.PP
+This problem has been fixed.
+.SS "Heap buffer overrun in 'x' string repeat operator (CVE\-2012\-5195)"
+.IX Subsection "Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)"
+Poorly written perl code that allows an attacker to specify the count to
+perl's 'x' string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before 5.15.5 can
+escalate that into a heap buffer overrun; coupled with versions of glibc
+before 2.16, it possibly allows the execution of arbitrary code.
+.PP
+This problem has been fixed.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+.SH Deprecations
+.IX Header "Deprecations"
+There have been no deprecations since 5.14.0.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+None
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+PerlIO::scalar was updated to fix a bug in which opening a filehandle to
+a glob copy caused assertion failures (under debugging) or hangs or other
+erratic behaviour without debugging.
+.IP \(bu 4
+ODBM_File and NDBM_File were updated to allow building on GNU/Hurd.
+.IP \(bu 4
+IPC::Open3 has been updated to fix a regression introduced in perl
+5.12, which broke \f(CW\*(C`IPC::Open3::open3($in, $out, $err, \*(Aq\-\*(Aq)\*(C'\fR.
+[perl #95748]
+.IP \(bu 4
+Digest has been upgraded from version 1.16 to 1.16_01.
+.Sp
+See "Security".
+.IP \(bu 4
+Module::CoreList has been updated to version 2.49_04 to add data for
+this release.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+None
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+None
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlcheat\fR
+.IX Subsection "perlcheat"
+.IP \(bu 4
+perlcheat was updated to 5.14.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+h2ph was updated to search correctly gcc include directories on platforms
+such as Debian with multi-architecture support.
+.IP \(bu 4
+In Configure, the test for procselfexe was refactored into a loop.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+None
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+None
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+The FreeBSD hints file was corrected to be compatible with FreeBSD 10.0.
+.IP "Solaris and NetBSD" 4
+.IX Item "Solaris and NetBSD"
+Configure was updated for "procselfexe" support on Solaris and NetBSD.
+.IP HP-UX 4
+.IX Item "HP-UX"
+README.hpux was updated to note the existence of a broken header in
+HP-UX 11.00.
+.IP Linux 4
+.IX Item "Linux"
+libutil is no longer used when compiling on Linux platforms, which avoids
+warnings being emitted.
+.Sp
+The system gcc (rather than any other gcc which might be in the compiling
+user's path) is now used when searching for libraries such as \f(CW\*(C`\-lm\*(C'\fR.
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+The locale tests were updated to reflect the behaviour of locales in
+Mountain Lion.
+.IP GNU/Hurd 4
+.IX Item "GNU/Hurd"
+Various build and test fixes were included for GNU/Hurd.
+.Sp
+LFS support was enabled in GNU/Hurd.
+.IP NetBSD 4
+.IX Item "NetBSD"
+The NetBSD hints file was corrected to be compatible with NetBSD 6.*
+.SH "Bug Fixes"
+.IX Header "Bug Fixes"
+.IP \(bu 4
+A regression has been fixed that was introduced in 5.14, in \f(CW\*(C`/i\*(C'\fR
+regular expression matching, in which a match improperly fails if the
+pattern is in UTF\-8, the target string is not, and a Latin\-1 character
+precedes a character in the string that should match the pattern.  [perl
+#101710]
+.IP \(bu 4
+In case-insensitive regular expression pattern matching, no longer on
+UTF\-8 encoded strings does the scan for the start of match only look at
+the first possible position.  This caused matches such as
+\&\f(CW\*(C`"f\ex{FB00}" =~ /ff/i\*(C'\fR to fail.
+.IP \(bu 4
+The sitecustomize support was made relocatableinc aware, so that
+\&\-Dusesitecustomize and \-Duserelocatableinc may be used together.
+.IP \(bu 4
+The smartmatch operator (\f(CW\*(C`~~\*(C'\fR) was changed so that the right-hand side
+takes precedence during \f(CW\*(C`Any ~~ Object\*(C'\fR operations.
+.IP \(bu 4
+A bug has been fixed in the tainting support, in which an \f(CWindex()\fR
+operation on a tainted constant would cause all other constants to become
+tainted.  [perl #64804]
+.IP \(bu 4
+A regression has been fixed that was introduced in perl 5.12, whereby
+tainting errors were not correctly propagated through \f(CWdie()\fR.
+[perl #111654]
+.IP \(bu 4
+A regression has been fixed that was introduced in perl 5.14, in which
+\&\f(CW\*(C`/[[:lower:]]/i\*(C'\fR and \f(CW\*(C`/[[:upper:]]/i\*(C'\fR no longer matched the opposite case.
+[perl #101970]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.14.3 represents approximately 12 months of development since Perl 5.14.2
+and contains approximately 2,300 lines of changes across 64 files from 22
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.14.3:
+.PP
+Abigail, Andy Dougherty, Carl Hayter, Chris 'BinGOs' Williams, Dave Rolsky,
+David Mitchell, Dominic Hargreaves, Father Chrysostomos, Florian Ragwitz,
+H.Merijn Brand, Jilles Tjoelker, Karl Williamson, Leon Timmermans, Michael G
+Schwern, Nicholas Clark, Niko Tyni, Pino Toscano, Ricardo Signes, Salvador
+Fandiño, Samuel Thibault, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5144delta.1 b/upstream/mageia-cauldron/man1/perl5144delta.1
new file mode 100644
index 00000000..ee4bfc26
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5144delta.1
@@ -0,0 +1,255 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5144DELTA 1"
+.TH PERL5144DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5144delta \- what is new for perl v5.14.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.14.3 release and
+the 5.14.4 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.0, first read
+perl5140delta, which describes differences between 5.12.0 and
+5.14.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+No changes since 5.14.0.
+.SH Security
+.IX Header "Security"
+This release contains one major, and medium, and a number of minor
+security fixes.  The latter are included mainly to allow the test suite to
+pass cleanly with the clang compiler's address sanitizer facility.
+.SS "CVE\-2013\-1667: memory exhaustion with arbitrary hash keys"
+.IX Subsection "CVE-2013-1667: memory exhaustion with arbitrary hash keys"
+With a carefully crafted set of hash keys (for example arguments on a
+URL), it is possible to cause a hash to consume a large amount of memory
+and CPU, and thus possibly to achieve a Denial-of-Service.
+.PP
+This problem has been fixed.
+.SS "memory leak in Encode"
+.IX Subsection "memory leak in Encode"
+The UTF\-8 encoding implementation in Encode.xs had a memory leak which has been
+fixed.
+.SS "[perl #111594] Socket::unpack_sockaddr_un heap-buffer-overflow"
+.IX Subsection "[perl #111594] Socket::unpack_sockaddr_un heap-buffer-overflow"
+A read buffer overflow could occur when copying \f(CW\*(C`sockaddr\*(C'\fR buffers.
+Fairly harmless.
+.PP
+This problem has been fixed.
+.SS "[perl #111586] SDBM_File: fix off-by-one access to global "".dir"""
+.IX Subsection "[perl #111586] SDBM_File: fix off-by-one access to global "".dir"""
+An extra byte was being copied for some string literals. Fairly harmless.
+.PP
+This problem has been fixed.
+.SS "off-by-two error in List::Util"
+.IX Subsection "off-by-two error in List::Util"
+A string literal was being used that included two bytes beyond the
+end of the string. Fairly harmless.
+.PP
+This problem has been fixed.
+.SS "[perl #115994] fix segv in regcomp.\fBc:S_join_exact()\fP"
+.IX Subsection "[perl #115994] fix segv in regcomp.c:S_join_exact()"
+Under debugging builds, while marking optimised-out regex nodes as type
+\&\f(CW\*(C`OPTIMIZED\*(C'\fR, it could treat blocks of exact text as if they were nodes,
+and thus SEGV. Fairly harmless.
+.PP
+This problem has been fixed.
+.SS "[perl #115992] PL_eval_start use-after-free"
+.IX Subsection "[perl #115992] PL_eval_start use-after-free"
+The statement \f(CW\*(C`local $[;\*(C'\fR, when preceded by an \f(CW\*(C`eval\*(C'\fR, and when not part
+of an assignment, could crash. Fairly harmless.
+.PP
+This problem has been fixed.
+.SS "wrap-around with IO on long strings"
+.IX Subsection "wrap-around with IO on long strings"
+Reading or writing strings greater than 2**31 bytes in size could segfault
+due to integer wraparound.
+.PP
+This problem has been fixed.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+.SH Deprecations
+.IX Header "Deprecations"
+There have been no deprecations since 5.14.0.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+None
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+The following modules have just the minor code fixes as listed above in
+"Security" (version numbers have not changed):
+.IP Socket 4
+.IX Item "Socket"
+.PD 0
+.IP SDBM_File 4
+.IX Item "SDBM_File"
+.IP List::Util 4
+.IX Item "List::Util"
+.PD
+.PP
+Encode has been upgraded from version 2.42_01 to version 2.42_02.
+.PP
+Module::CoreList has been updated to version 2.49_06 to add data for
+this release.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+None.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+None.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+None.
+.SH Diagnostics
+.IX Header "Diagnostics"
+No new or changed diagnostics.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+None
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+No changes.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+None.
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+None.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP VMS 4
+.IX Item "VMS"
+5.14.3 failed to compile on VMS due to incomplete application of a patch
+series that allowed \f(CW\*(C`userelocatableinc\*(C'\fR and \f(CW\*(C`usesitecustomize\*(C'\fR to be
+used simultaneously.  Other platforms were not affected and the problem
+has now been corrected.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+In Perl 5.14.0, \f(CW\*(C`$tainted ~~ @array\*(C'\fR stopped working properly.  Sometimes
+it would erroneously fail (when \f(CW$tainted\fR contained a string that occurs
+in the array \fIafter\fR the first element) or erroneously succeed (when
+\&\f(CW\*(C`undef\*(C'\fR occurred after the first element) [perl #93590].
+.SH "Known Problems"
+.IX Header "Known Problems"
+None.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.14.4 represents approximately 5 months of development since Perl 5.14.3
+and contains approximately 1,700 lines of changes across 49 files from 12
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.14.4:
+.PP
+Andy Dougherty, Chris 'BinGOs' Williams, Christian Hansen, Craig A. Berry,
+Dave Rolsky, David Mitchell, Dominic Hargreaves, Father Chrysostomos,
+Florian Ragwitz, Reini Urban, Ricardo Signes, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5160delta.1 b/upstream/mageia-cauldron/man1/perl5160delta.1
new file mode 100644
index 00000000..0453167b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5160delta.1
@@ -0,0 +1,3342 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5160DELTA 1"
+.TH PERL5160DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5160delta \- what is new for perl v5.16.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.14.0 release and
+the 5.16.0 release.
+.PP
+If you are upgrading from an earlier release such as 5.12.0, first read
+perl5140delta, which describes differences between 5.12.0 and
+5.14.0.
+.PP
+Some bug fixes in this release have been backported to later
+releases of 5.14.x.  Those are indicated with the 5.14.x version in
+parentheses.
+.SH Notice
+.IX Header "Notice"
+With the release of Perl 5.16.0, the 5.12.x series of releases is now out of
+its support period.  There may be future 5.12.x releases, but only in the
+event of a critical security issue.  Users of Perl 5.12 or earlier should
+consider upgrading to a more recent release of Perl.
+.PP
+This policy is described in greater detail in
+perlpolicy.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS """use \fIVERSION\fP"""
+.el .SS "\f(CWuse \fP\f(CIVERSION\fP\f(CW\fP"
+.IX Subsection "use VERSION"
+As of this release, version declarations like \f(CW\*(C`use v5.16\*(C'\fR now disable
+all features before enabling the new feature bundle.  This means that
+the following holds true:
+.PP
+.Vb 4
+\&    use 5.016;
+\&    # only 5.16 features enabled here
+\&    use 5.014;
+\&    # only 5.14 features enabled here (not 5.16)
+.Ve
+.PP
+\&\f(CW\*(C`use v5.12\*(C'\fR and higher continue to enable strict, but explicit \f(CW\*(C`use
+strict\*(C'\fR and \f(CW\*(C`no strict\*(C'\fR now override the version declaration, even
+when they come first:
+.PP
+.Vb 3
+\&    no strict;
+\&    use 5.012;
+\&    # no strict here
+.Ve
+.PP
+There is a new ":default" feature bundle that represents the set of
+features enabled before any version declaration or \f(CW\*(C`use feature\*(C'\fR has
+been seen.  Version declarations below 5.10 now enable the ":default"
+feature set.  This does not actually change the behavior of \f(CW\*(C`use
+v5.8\*(C'\fR, because features added to the ":default" set are those that were
+traditionally enabled by default, before they could be turned off.
+.PP
+\&\f(CW\*(C`no feature\*(C'\fR now resets to the default feature set.  To disable all
+features (which is likely to be a pretty special-purpose request, since
+it presumably won't match any named set of semantics) you can now  
+write \f(CW\*(C`no feature \*(Aq:all\*(Aq\*(C'\fR.
+.PP
+\&\f(CW$[\fR is now disabled under \f(CW\*(C`use v5.16\*(C'\fR.  It is part of the default
+feature set and can be turned on or off explicitly with \f(CWuse feature
+\&\*(Aqarray_base\*(Aq\fR.
+.ie n .SS """_\|_SUB_\|_"""
+.el .SS \f(CW_\|_SUB_\|_\fP
+.IX Subsection "__SUB__"
+The new \f(CW\*(C`_\|_SUB_\|_\*(C'\fR token, available under the \f(CW\*(C`current_sub\*(C'\fR feature
+(see feature) or \f(CW\*(C`use v5.16\*(C'\fR, returns a reference to the current
+subroutine, making it easier to write recursive closures.
+.SS "New and Improved Built-ins"
+.IX Subsection "New and Improved Built-ins"
+\fIMore consistent \fR\f(CI\*(C`eval\*(C'\fR
+.IX Subsection "More consistent eval"
+.PP
+The \f(CW\*(C`eval\*(C'\fR operator sometimes treats a string argument as a sequence of
+characters and sometimes as a sequence of bytes, depending on the
+internal encoding.  The internal encoding is not supposed to make any
+difference, but there is code that relies on this inconsistency.
+.PP
+The new \f(CW\*(C`unicode_eval\*(C'\fR and \f(CW\*(C`evalbytes\*(C'\fR features (enabled under \f(CWuse
+5.16.0\fR) resolve this.  The \f(CW\*(C`unicode_eval\*(C'\fR feature causes \f(CWeval
+$string\fR to treat the string always as Unicode.  The \f(CW\*(C`evalbytes\*(C'\fR
+features provides a function, itself called \f(CW\*(C`evalbytes\*(C'\fR, which
+evaluates its argument always as a string of bytes.
+.PP
+These features also fix oddities with source filters leaking to outer
+dynamic scopes.
+.PP
+See feature for more detail.
+.PP
+\fR\f(CI\*(C`substr\*(C'\fR\fI lvalue revamp\fR
+.IX Subsection "substr lvalue revamp"
+.PP
+When \f(CW\*(C`substr\*(C'\fR is called in lvalue or potential lvalue context with two
+or three arguments, a special lvalue scalar is returned that modifies
+the original string (the first argument) when assigned to.
+.PP
+Previously, the offsets (the second and third arguments) passed to
+\&\f(CW\*(C`substr\*(C'\fR would be converted immediately to match the string, negative
+offsets being translated to positive and offsets beyond the end of the
+string being truncated.
+.PP
+Now, the offsets are recorded without modification in the special
+lvalue scalar that is returned, and the original string is not even
+looked at by \f(CW\*(C`substr\*(C'\fR itself, but only when the returned lvalue is
+read or modified.
+.PP
+These changes result in an incompatible change:
+.PP
+If the original string changes length after the call to \f(CW\*(C`substr\*(C'\fR but
+before assignment to its return value, negative offsets will remember
+their position from the end of the string, affecting code like this:
+.PP
+.Vb 5
+\&    my $string = "string";
+\&    my $lvalue = \esubstr $string, \-4, 2;
+\&    print $$lvalue, "\en"; # prints "ri"
+\&    $string = "bailing twine";
+\&    print $$lvalue, "\en"; # prints "wi"; used to print "il"
+.Ve
+.PP
+The same thing happens with an omitted third argument.  The returned
+lvalue will always extend to the end of the string, even if the string
+becomes longer.
+.PP
+Since this change also allowed many bugs to be fixed (see
+"The \f(CW\*(C`substr\*(C'\fR operator"), and since the behavior
+of negative offsets has never been specified, the
+change was deemed acceptable.
+.PP
+\fIReturn value of \fR\f(CI\*(C`tied\*(C'\fR
+.IX Subsection "Return value of tied"
+.PP
+The value returned by \f(CW\*(C`tied\*(C'\fR on a tied variable is now the actual
+scalar that holds the object to which the variable is tied.  This
+lets ties be weakened with \f(CW\*(C`Scalar::Util::weaken(tied
+$tied_variable)\*(C'\fR.
+.SS "Unicode Support"
+.IX Subsection "Unicode Support"
+\fISupports (almost) Unicode 6.1\fR
+.IX Subsection "Supports (almost) Unicode 6.1"
+.PP
+Besides the addition of whole new scripts, and new characters in
+existing scripts, this new version of Unicode, as always, makes some
+changes to existing characters.  One change that may trip up some
+applications is that the General Category of two characters in the
+Latin\-1 range, PILCROW SIGN and SECTION SIGN, has been changed from
+Other_Symbol to Other_Punctuation.  The same change has been made for
+a character in each of Tibetan, Ethiopic, and Aegean.
+The code points U+3248..U+324F (CIRCLED NUMBER TEN ON BLACK SQUARE
+through CIRCLED NUMBER EIGHTY ON BLACK SQUARE) have had their General
+Category changed from Other_Symbol to Other_Numeric.  The Line Break
+property has changes for Hebrew and Japanese; and because of
+other changes in 6.1, the Perl regular expression construct \f(CW\*(C`\eX\*(C'\fR now
+works differently for some characters in Thai and Lao.
+.PP
+New aliases (synonyms) have been defined for many property values;
+these, along with the previously existing ones, are all cross-indexed in
+perluniprops.
+.PP
+The return value of \f(CWcharnames::viacode()\fR is affected by other
+changes:
+.PP
+.Vb 10
+\& Code point      Old Name             New Name
+\&   U+000A    LINE FEED (LF)        LINE FEED
+\&   U+000C    FORM FEED (FF)        FORM FEED
+\&   U+000D    CARRIAGE RETURN (CR)  CARRIAGE RETURN
+\&   U+0085    NEXT LINE (NEL)       NEXT LINE
+\&   U+008E    SINGLE\-SHIFT 2        SINGLE\-SHIFT\-2
+\&   U+008F    SINGLE\-SHIFT 3        SINGLE\-SHIFT\-3
+\&   U+0091    PRIVATE USE 1         PRIVATE USE\-1
+\&   U+0092    PRIVATE USE 2         PRIVATE USE\-2
+\&   U+2118    SCRIPT CAPITAL P      WEIERSTRASS ELLIPTIC FUNCTION
+.Ve
+.PP
+Perl will accept any of these names as input, but
+\&\f(CWcharnames::viacode()\fR now returns the new name of each pair.  The
+change for U+2118 is considered by Unicode to be a correction, that is
+the original name was a mistake (but again, it will remain forever valid
+to use it to refer to U+2118).  But most of these changes are the
+fallout of the mistake Unicode 6.0 made in naming a character used in
+Japanese cell phones to be "BELL", which conflicts with the longstanding
+industry use of (and Unicode's recommendation to use) that name
+to mean the ASCII control character at U+0007.  Therefore, that name
+has been deprecated in Perl since v5.14, and any use of it will raise a
+warning message (unless turned off).  The name "ALERT" is now the
+preferred name for this code point, with "BEL" an acceptable short
+form.  The name for the new cell phone character, at code point U+1F514,
+remains undefined in this version of Perl (hence we don't 
+implement quite all of Unicode 6.1), but starting in v5.18, BELL will mean
+this character, and not U+0007.
+.PP
+Unicode has taken steps to make sure that this sort of mistake does not
+happen again.  The Standard now includes all generally accepted
+names and abbreviations for control characters, whereas previously it
+didn't (though there were recommended names for most of them, which Perl
+used).  This means that most of those recommended names are now
+officially in the Standard.  Unicode did not recommend names for the
+four code points listed above between U+008E and U+008F, and in
+standardizing them Unicode subtly changed the names that Perl had
+previously given them, by replacing the final blank in each name by a
+hyphen.  Unicode also officially accepts names that Perl had deprecated,
+such as FILE SEPARATOR.  Now the only deprecated name is BELL.
+Finally, Perl now uses the new official names instead of the old
+(now considered obsolete) names for the first four code points in the
+list above (the ones which have the parentheses in them).
+.PP
+Now that the names have been placed in the Unicode standard, these kinds
+of changes should not happen again, though corrections, such as to
+U+2118, are still possible.
+.PP
+Unicode also added some name abbreviations, which Perl now accepts:
+SP for SPACE;
+TAB for CHARACTER TABULATION;
+NEW LINE, END OF LINE, NL, and EOL for LINE FEED;
+LOCKING-SHIFT ONE for SHIFT OUT;
+LOCKING-SHIFT ZERO for SHIFT IN;
+and ZWNBSP for ZERO WIDTH NO-BREAK SPACE.
+.PP
+More details on this version of Unicode are provided in
+<http://www.unicode.org/versions/Unicode6.1.0/>.
+.PP
+\fR\f(CI\*(C`use charnames\*(C'\fR\fI is no longer needed for \fR\f(CI\*(C`\eN{name}\*(C'\fR\fI\fR
+.IX Subsection "use charnames is no longer needed for N{name}"
+.PP
+When \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR is encountered, the \f(CW\*(C`charnames\*(C'\fR module is now
+automatically loaded when needed as if the \f(CW\*(C`:full\*(C'\fR and \f(CW\*(C`:short\*(C'\fR
+options had been specified.  See charnames for more information.
+.PP
+\fR\f(CI\*(C`\eN{...}\*(C'\fR\fI can now have Unicode loose name matching\fR
+.IX Subsection "N{...} can now have Unicode loose name matching"
+.PP
+This is described in the \f(CW\*(C`charnames\*(C'\fR item in
+"Updated Modules and Pragmata" below.
+.PP
+\fIUnicode Symbol Names\fR
+.IX Subsection "Unicode Symbol Names"
+.PP
+Perl now has proper support for Unicode in symbol names.  It used to be
+that \f(CW\*(C`*{$foo}\*(C'\fR would ignore the internal UTF8 flag and use the bytes of
+the underlying representation to look up the symbol.  That meant that
+\&\f(CW\*(C`*{"\ex{100}"}\*(C'\fR and \f(CW\*(C`*{"\exc4\ex80"}\*(C'\fR would return the same thing.  All
+these parts of Perl have been fixed to account for Unicode:
+.IP \(bu 4
+Method names (including those passed to \f(CW\*(C`use overload\*(C'\fR)
+.IP \(bu 4
+Typeglob names (including names of variables, subroutines, and filehandles)
+.IP \(bu 4
+Package names
+.IP \(bu 4
+\&\f(CW\*(C`goto\*(C'\fR
+.IP \(bu 4
+Symbolic dereferencing
+.IP \(bu 4
+Second argument to \f(CWbless()\fR and \f(CWtie()\fR
+.IP \(bu 4
+Return value of \f(CWref()\fR
+.IP \(bu 4
+Subroutine prototypes
+.IP \(bu 4
+Attributes
+.IP \(bu 4
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+.PP
+In addition, a parsing bug has been fixed that prevented \f(CW\*(C`*{é}\*(C'\fR from
+implicitly quoting the name, but instead interpreted it as \f(CW\*(C`*{+é}\*(C'\fR, which
+would cause a strict violation.
+.PP
+\&\f(CW\*(C`*{"*a::b"}\*(C'\fR automatically strips off the * if it is followed by an ASCII
+letter.  That has been extended to all Unicode identifier characters.
+.PP
+One-character non-ASCII non-punctuation variables (like \f(CW$é\fR) are now
+subject to "Used only once" warnings.  They used to be exempt, as they
+were treated as punctuation variables.
+.PP
+Also, single-character Unicode punctuation variables (like \f(CW$‰\fR) are now
+supported [perl #69032].
+.PP
+\fIImproved ability to mix locales and Unicode, including UTF\-8 locales\fR
+.IX Subsection "Improved ability to mix locales and Unicode, including UTF-8 locales"
+.PP
+An optional parameter has been added to \f(CW\*(C`use locale\*(C'\fR
+.PP
+.Vb 1
+\& use locale \*(Aq:not_characters\*(Aq;
+.Ve
+.PP
+which tells Perl to use all but the \f(CW\*(C`LC_CTYPE\*(C'\fR and \f(CW\*(C`LC_COLLATE\*(C'\fR
+portions of the current locale.  Instead, the character set is assumed
+to be Unicode.  This lets locales and Unicode be seamlessly mixed,
+including the increasingly frequent UTF\-8 locales.  When using this
+hybrid form of locales, the \f(CW\*(C`:locale\*(C'\fR layer to the open pragma can
+be used to interface with the file system, and there are CPAN modules
+available for ARGV and environment variable conversions.
+.PP
+Full details are in perllocale.
+.PP
+\fINew function \fR\f(CI\*(C`fc\*(C'\fR\fI and corresponding escape sequence \fR\f(CI\*(C`\eF\*(C'\fR\fI for Unicode foldcase\fR
+.IX Subsection "New function fc and corresponding escape sequence F for Unicode foldcase"
+.PP
+Unicode foldcase is an extension to lowercase that gives better results
+when comparing two strings case-insensitively.  It has long been used
+internally in regular expression \f(CW\*(C`/i\*(C'\fR matching.  Now it is available
+explicitly through the new \f(CW\*(C`fc\*(C'\fR function call (enabled by
+\&\f(CW"use\ feature\ \*(Aqfc\*(Aq"\fR, or \f(CW\*(C`use v5.16\*(C'\fR, or explicitly callable via
+\&\f(CW\*(C`CORE::fc\*(C'\fR) or through the new \f(CW\*(C`\eF\*(C'\fR sequence in double-quotish
+strings.
+.PP
+Full details are in "fc" in perlfunc.
+.PP
+\fIThe Unicode \fR\f(CI\*(C`Script_Extensions\*(C'\fR\fI property is now supported.\fR
+.IX Subsection "The Unicode Script_Extensions property is now supported."
+.PP
+New in Unicode 6.0, this is an improved \f(CW\*(C`Script\*(C'\fR property.  Details
+are in "Scripts" in perlunicode.
+.SS "XS Changes"
+.IX Subsection "XS Changes"
+\fIImproved typemaps for Some Builtin Types\fR
+.IX Subsection "Improved typemaps for Some Builtin Types"
+.PP
+Most XS authors will know there is a longstanding bug in the
+OUTPUT typemap for T_AVREF (\f(CW\*(C`AV*\*(C'\fR), T_HVREF (\f(CW\*(C`HV*\*(C'\fR), T_CVREF (\f(CW\*(C`CV*\*(C'\fR),
+and T_SVREF (\f(CW\*(C`SVREF\*(C'\fR or \f(CW\*(C`\e$foo\*(C'\fR) that requires manually decrementing
+the reference count of the return value instead of the typemap taking
+care of this.  For backwards-compatibility, this cannot be changed in the
+default typemaps.  But we now provide additional typemaps
+\&\f(CW\*(C`T_AVREF_REFCOUNT_FIXED\*(C'\fR, etc. that do not exhibit this bug.  Using
+them in your extension is as simple as having one line in your
+\&\f(CW\*(C`TYPEMAP\*(C'\fR section:
+.PP
+.Vb 1
+\&  HV*   T_HVREF_REFCOUNT_FIXED
+.Ve
+.PP
+\fR\f(CIis_utf8_char()\fR\fI\fR
+.IX Subsection "is_utf8_char()"
+.PP
+The XS-callable function \f(CWis_utf8_char()\fR, when presented with
+malformed UTF\-8 input, can read up to 12 bytes beyond the end of the
+string.  This cannot be fixed without changing its API, and so its
+use is now deprecated.  Use \f(CWis_utf8_char_buf()\fR (described just below)
+instead.
+.PP
+\fIAdded \fR\f(CIis_utf8_char_buf()\fR
+.IX Subsection "Added is_utf8_char_buf()"
+.PP
+This function is designed to replace the deprecated "\fBis_utf8_char()\fR"
+function.  It includes an extra parameter to make sure it doesn't read
+past the end of the input buffer.
+.PP
+\fIOther \fR\f(CIis_utf8_foo()\fR\fI functions, as well as \fR\f(CIutf8_to_foo()\fR\fI, etc.\fR
+.IX Subsection "Other is_utf8_foo() functions, as well as utf8_to_foo(), etc."
+.PP
+Most other XS-callable functions that take UTF\-8 encoded input
+implicitly assume that the UTF\-8 is valid (not malformed) with respect to
+buffer length.  Do not do things such as change a character's case or
+see if it is alphanumeric without first being sure that it is valid
+UTF\-8.  This can be safely done for a whole string by using one of the
+functions \f(CWis_utf8_string()\fR, \f(CWis_utf8_string_loc()\fR, and
+\&\f(CWis_utf8_string_loclen()\fR.
+.PP
+\fINew Pad API\fR
+.IX Subsection "New Pad API"
+.PP
+Many new functions have been added to the API for manipulating lexical
+pads.  See "Pad Data Structures" in perlapi for more information.
+.SS "Changes to Special Variables"
+.IX Subsection "Changes to Special Variables"
+\fR\f(CI$$\fR\fI can be assigned to\fR
+.IX Subsection "$$ can be assigned to"
+.PP
+\&\f(CW$$\fR was made read-only in Perl 5.8.0.  But only sometimes: \f(CW\*(C`local $$\*(C'\fR
+would make it writable again.  Some CPAN modules were using \f(CW\*(C`local $$\*(C'\fR or
+XS code to bypass the read-only check, so there is no reason to keep \f(CW$$\fR
+read-only.  (This change also allowed a bug to be fixed while maintaining
+backward compatibility.)
+.PP
+\fR\f(CI$^X\fR\fI converted to an absolute path on FreeBSD, OS X and Solaris\fR
+.IX Subsection "$^X converted to an absolute path on FreeBSD, OS X and Solaris"
+.PP
+\&\f(CW$^X\fR is now converted to an absolute path on OS X, FreeBSD (without
+needing \fI/proc\fR mounted) and Solaris 10 and 11.  This augments the
+previous approach of using \fI/proc\fR on Linux, FreeBSD, and NetBSD
+(in all cases, where mounted).
+.PP
+This makes relocatable perl installations more useful on these platforms.
+(See "Relocatable \f(CW@INC\fR" in \fIINSTALL\fR)
+.SS "Debugger Changes"
+.IX Subsection "Debugger Changes"
+\fIFeatures inside the debugger\fR
+.IX Subsection "Features inside the debugger"
+.PP
+The current Perl's feature bundle is now enabled for commands entered
+in the interactive debugger.
+.PP
+\fINew option for the debugger's \fR\f(BIt\fR\fI command\fR
+.IX Subsection "New option for the debugger's t command"
+.PP
+The \fBt\fR command in the debugger, which toggles tracing mode, now
+accepts a numeric argument that determines how many levels of subroutine
+calls to trace.
+.PP
+\fR\f(CI\*(C`enable\*(C'\fR\fI and \fR\f(CI\*(C`disable\*(C'\fR\fI\fR
+.IX Subsection "enable and disable"
+.PP
+The debugger now has \f(CW\*(C`disable\*(C'\fR and \f(CW\*(C`enable\*(C'\fR commands for disabling
+existing breakpoints and re-enabling them.  See perldebug.
+.PP
+\fIBreakpoints with file names\fR
+.IX Subsection "Breakpoints with file names"
+.PP
+The debugger's "b" command for setting breakpoints now lets a line
+number be prefixed with a file name.  See
+"b [file]:[line] [condition]" in perldebug.
+.ie n .SS "The ""CORE"" Namespace"
+.el .SS "The \f(CWCORE\fP Namespace"
+.IX Subsection "The CORE Namespace"
+\fIThe \fR\f(CI\*(C`CORE::\*(C'\fR\fI prefix\fR
+.IX Subsection "The CORE:: prefix"
+.PP
+The \f(CW\*(C`CORE::\*(C'\fR prefix can now be used on keywords enabled by
+feature.pm, even outside the scope of \f(CW\*(C`use feature\*(C'\fR.
+.PP
+\fISubroutines in the \fR\f(CI\*(C`CORE\*(C'\fR\fI namespace\fR
+.IX Subsection "Subroutines in the CORE namespace"
+.PP
+Many Perl keywords are now available as subroutines in the CORE namespace.
+This lets them be aliased:
+.PP
+.Vb 2
+\&    BEGIN { *entangle = \e&CORE::tie }
+\&    entangle $variable, $package, @args;
+.Ve
+.PP
+And for prototypes to be bypassed:
+.PP
+.Vb 5
+\&    sub mytie(\e[%$*@]$@) {
+\&        my ($ref, $pack, @args) = @_;
+\&        ... do something ...
+\&        goto &CORE::tie;
+\&    }
+.Ve
+.PP
+Some of these cannot be called through references or via \f(CW&foo\fR syntax,
+but must be called as barewords.
+.PP
+See CORE for details.
+.SS "Other Changes"
+.IX Subsection "Other Changes"
+\fIAnonymous handles\fR
+.IX Subsection "Anonymous handles"
+.PP
+Automatically generated file handles are now named _\|_ANONIO_\|_ when the
+variable name cannot be determined, rather than \f(CW$_\fR\|_ANONIO_\|_.
+.PP
+\fIAutoloaded sort Subroutines\fR
+.IX Subsection "Autoloaded sort Subroutines"
+.PP
+Custom sort subroutines can now be autoloaded [perl #30661]:
+.PP
+.Vb 2
+\&    sub AUTOLOAD { ... }
+\&    @sorted = sort foo @list; # uses AUTOLOAD
+.Ve
+.PP
+\fR\f(CI\*(C`continue\*(C'\fR\fI no longer requires the "switch" feature\fR
+.IX Subsection "continue no longer requires the ""switch"" feature"
+.PP
+The \f(CW\*(C`continue\*(C'\fR keyword has two meanings.  It can introduce a \f(CW\*(C`continue\*(C'\fR
+block after a loop, or it can exit the current \f(CW\*(C`when\*(C'\fR block.  Up to now,
+the latter meaning was valid only with the "switch" feature enabled, and
+was a syntax error otherwise.  Since the main purpose of feature.pm is to
+avoid conflicts with user-defined subroutines, there is no reason for
+\&\f(CW\*(C`continue\*(C'\fR to depend on it.
+.PP
+\fIDTrace probes for interpreter phase change\fR
+.IX Subsection "DTrace probes for interpreter phase change"
+.PP
+The \f(CW\*(C`phase\-change\*(C'\fR probes will fire when the interpreter's phase
+changes, which tracks the \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable.  \f(CW\*(C`arg0\*(C'\fR is
+the new phase name; \f(CW\*(C`arg1\*(C'\fR is the old one.  This is useful 
+for limiting your instrumentation to one or more of: compile time,
+run time, or destruct time.
+.PP
+\fR\f(CI\*(C`_\|_FILE_\|_()\*(C'\fR\fI Syntax\fR
+.IX Subsection "__FILE__() Syntax"
+.PP
+The \f(CW\*(C`_\|_FILE_\|_\*(C'\fR, \f(CW\*(C`_\|_LINE_\|_\*(C'\fR and \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR tokens can now be written
+with an empty pair of parentheses after them.  This makes them parse the
+same way as \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`fork\*(C'\fR and other built-in functions.
+.PP
+\fIThe \fR\f(CI\*(C`\e$\*(C'\fR\fI prototype accepts any scalar lvalue\fR
+.IX Subsection "The $ prototype accepts any scalar lvalue"
+.PP
+The \f(CW\*(C`\e$\*(C'\fR and \f(CW\*(C`\e[$]\*(C'\fR subroutine prototypes now accept any scalar lvalue
+argument.  Previously they accepted only scalars beginning with \f(CW\*(C`$\*(C'\fR and
+hash and array elements.  This change makes them consistent with the way
+the built-in \f(CW\*(C`read\*(C'\fR and \f(CW\*(C`recv\*(C'\fR functions (among others) parse their
+arguments.  This means that one can override the built-in functions with
+custom subroutines that parse their arguments the same way.
+.PP
+\fR\f(CI\*(C`_\*(C'\fR\fI in subroutine prototypes\fR
+.IX Subsection "_ in subroutine prototypes"
+.PP
+The \f(CW\*(C`_\*(C'\fR character in subroutine prototypes is now allowed before \f(CW\*(C`@\*(C'\fR or
+\&\f(CW\*(C`%\*(C'\fR.
+.SH Security
+.IX Header "Security"
+.ie n .SS "Use is_utf8_char_buf() and not is_utf8_char()"
+.el .SS "Use \f(CWis_utf8_char_buf()\fP and not \f(CWis_utf8_char()\fP"
+.IX Subsection "Use is_utf8_char_buf() and not is_utf8_char()"
+The latter function is now deprecated because its API is insufficient to
+guarantee that it doesn't read (up to 12 bytes in the worst case) beyond
+the end of its input string.  See
+\&\fBis_utf8_char_buf()\fR.
+.SS "Malformed UTF\-8 input could cause attempts to read beyond the end of the buffer"
+.IX Subsection "Malformed UTF-8 input could cause attempts to read beyond the end of the buffer"
+Two new XS-accessible functions, \f(CWutf8_to_uvchr_buf()\fR and
+\&\f(CWutf8_to_uvuni_buf()\fR are now available to prevent this, and the Perl
+core has been converted to use them.
+See "Internal Changes".
+.ie n .SS "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.el .SS "\f(CWFile::Glob::bsd_glob()\fP memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)."
+.IX Subsection "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+Calling \f(CW\*(C`File::Glob::bsd_glob\*(C'\fR with the unsupported flag
+GLOB_ALTDIRFUNC would cause an access violation / segfault.  A Perl
+program that accepts a flags value from an external source could expose
+itself to denial of service or arbitrary code execution attacks.  There
+are no known exploits in the wild.  The problem has been corrected by
+explicitly disabling all unsupported flags and setting unused function
+pointers to null.  Bug reported by Clément Lecigne. (5.14.2)
+.ie n .SS "Privileges are now set correctly when assigning to $("
+.el .SS "Privileges are now set correctly when assigning to \f(CW$(\fP"
+.IX Subsection "Privileges are now set correctly when assigning to $("
+A hypothetical bug (probably unexploitable in practice) because the
+incorrect setting of the effective group ID while setting \f(CW$(\fR has been
+fixed.  The bug would have affected only systems that have \f(CWsetresgid()\fR
+but not \f(CWsetregid()\fR, but no such systems are known to exist.
+.SH Deprecations
+.IX Header "Deprecations"
+.SS "Don't read the Unicode data base files in \fIlib/unicore\fP"
+.IX Subsection "Don't read the Unicode data base files in lib/unicore"
+It is now deprecated to directly read the Unicode data base files.
+These are stored in the \fIlib/unicore\fR directory.  Instead, you should
+use the new functions in Unicode::UCD.  These provide a stable API,
+and give complete information.
+.PP
+Perl may at some point in the future change or remove these files.  The
+file which applications were most likely to have used is
+\&\fIlib/unicore/ToDigit.pl\fR.  "\fBprop_invmap()\fR" in Unicode::UCD can be used to
+get at its data instead.
+.ie n .SS "XS functions is_utf8_char(), utf8_to_uvchr() and utf8_to_uvuni()"
+.el .SS "XS functions \f(CWis_utf8_char()\fP, \f(CWutf8_to_uvchr()\fP and \f(CWutf8_to_uvuni()\fP"
+.IX Subsection "XS functions is_utf8_char(), utf8_to_uvchr() and utf8_to_uvuni()"
+This function is deprecated because it could read beyond the end of the
+input string.  Use the new \fBis_utf8_char_buf()\fR,
+\&\f(CWutf8_to_uvchr_buf()\fR and \f(CWutf8_to_uvuni_buf()\fR instead.
+.SH "Future Deprecations"
+.IX Header "Future Deprecations"
+This section serves as a notice of features that are \fIlikely\fR to be
+removed or deprecated in the next release of
+perl (5.18.0).  If your code depends on these features, you should
+contact the Perl 5 Porters via the mailing
+list <http://lists.perl.org/list/perl5-porters.html> or perlbug to
+explain your use case and inform the deprecation process.
+.SS "Core Modules"
+.IX Subsection "Core Modules"
+These modules may be marked as deprecated \fIfrom the core\fR.  This only
+means that they will no longer be installed by default with the core
+distribution, but will remain available on the CPAN.
+.IP \(bu 4
+CPANPLUS
+.IP \(bu 4
+Filter::Simple
+.IP \(bu 4
+PerlIO::mmap
+.IP \(bu 4
+Pod::LaTeX
+.IP \(bu 4
+Pod::Parser
+.IP \(bu 4
+SelfLoader
+.IP \(bu 4
+Text::Soundex
+.IP \(bu 4
+Thread.pm
+.SS "Platforms with no supporting programmers"
+.IX Subsection "Platforms with no supporting programmers"
+These platforms will probably have their
+special build support removed during the
+5.17.0 development series.
+.IP \(bu 4
+BeOS
+.IP \(bu 4
+djgpp
+.IP \(bu 4
+dgux
+.IP \(bu 4
+EPOC
+.IP \(bu 4
+MPE/iX
+.IP \(bu 4
+Rhapsody
+.IP \(bu 4
+UTS
+.IP \(bu 4
+VM/ESA
+.SS "Other Future Deprecations"
+.IX Subsection "Other Future Deprecations"
+.IP \(bu 4
+Swapping of $< and $>
+.Sp
+For more information about this future deprecation, see the relevant RT
+ticket <https://github.com/Perl/perl5/issues/11547>.
+.IP \(bu 4
+sfio, stdio
+.Sp
+Perl supports being built without PerlIO proper, using a stdio or sfio
+wrapper instead.  A perl build like this will not support IO layers and
+thus Unicode IO, making it rather handicapped.
+.Sp
+PerlIO supports a \f(CW\*(C`stdio\*(C'\fR layer if stdio use is desired, and similarly a
+sfio layer could be produced.
+.IP \(bu 4
+Unescaped literal \f(CW"{"\fR in regular expressions.
+.Sp
+Starting with v5.20, it is planned to require a literal \f(CW"{"\fR to be
+escaped, for example by preceding it with a backslash.  In v5.18, a
+deprecated warning message will be emitted for all such uses.  
+This affects only patterns that are to match a literal \f(CW"{"\fR.  Other
+uses of this character, such as part of a quantifier or sequence as in
+those below, are completely unaffected:
+.Sp
+.Vb 3
+\&    /foo{3,5}/
+\&    /\ep{Alphabetic}/
+\&    /\eN{DIGIT ZERO}
+.Ve
+.Sp
+Removing this will permit extensions to Perl's pattern syntax and better
+error checking for existing syntax.  See "Quantifiers" in perlre for an
+example.
+.IP \(bu 4
+Revamping \f(CW"\eQ"\fR semantics in double-quotish strings when combined with other escapes.
+.Sp
+There are several bugs and inconsistencies involving combinations
+of \f(CW\*(C`\eQ\*(C'\fR and escapes like \f(CW\*(C`\ex\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, etc., within a \f(CW\*(C`\eQ...\eE\*(C'\fR pair.
+These need to be fixed, and doing so will necessarily change current
+behavior.  The changes have not yet been settled.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Special blocks called in void context"
+.IX Subsection "Special blocks called in void context"
+Special blocks (\f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`END\*(C'\fR) are now
+called in void context.  This avoids wasteful copying of the result of the
+last statement [perl #108794].
+.ie n .SS "The ""overloading"" pragma and regexp objects"
+.el .SS "The \f(CWoverloading\fP pragma and regexp objects"
+.IX Subsection "The overloading pragma and regexp objects"
+With \f(CW\*(C`no overloading\*(C'\fR, regular expression objects returned by \f(CW\*(C`qr//\*(C'\fR are
+now stringified as "Regexp=REGEXP(0xbe600d)" instead of the regular
+expression itself [perl #108780].
+.SS "Two XS typemap Entries removed"
+.IX Subsection "Two XS typemap Entries removed"
+Two presumably unused XS typemap entries have been removed from the
+core typemap: T_DATAUNIT and T_CALLBACK.  If you are, against all odds,
+a user of these, please see the instructions on how to restore them
+in perlxstypemap.
+.SS "Unicode 6.1 has incompatibilities with Unicode 6.0"
+.IX Subsection "Unicode 6.1 has incompatibilities with Unicode 6.0"
+These are detailed in "Supports (almost) Unicode 6.1" above.
+You can compile this version of Perl to use Unicode 6.0.  See
+"Hacking Perl to work on earlier Unicode versions (for very serious hackers only)" in perlunicode.
+.SS "Borland compiler"
+.IX Subsection "Borland compiler"
+All support for the Borland compiler has been dropped.  The code had not
+worked for a long time anyway.
+.SS "Certain deprecated Unicode properties are no longer supported by default"
+.IX Subsection "Certain deprecated Unicode properties are no longer supported by default"
+Perl should never have exposed certain Unicode properties that are used
+by Unicode internally and not meant to be publicly available.  Use of
+these has generated deprecated warning messages since Perl 5.12.  The
+removed properties are Other_Alphabetic,
+Other_Default_Ignorable_Code_Point, Other_Grapheme_Extend,
+Other_ID_Continue, Other_ID_Start, Other_Lowercase, Other_Math, and
+Other_Uppercase.
+.PP
+Perl may be recompiled to include any or all of them; instructions are
+given in
+"Unicode character properties that are NOT accepted by Perl" in perluniprops.
+.SS "Dereferencing IO thingies as typeglobs"
+.IX Subsection "Dereferencing IO thingies as typeglobs"
+The \f(CW\*(C`*{...}\*(C'\fR operator, when passed a reference to an IO thingy (as in
+\&\f(CW\*(C`*{*STDIN{IO}}\*(C'\fR), creates a new typeglob containing just that IO object.
+Previously, it would stringify as an empty string, but some operators would
+treat it as undefined, producing an "uninitialized" warning.
+Now it stringifies as _\|_ANONIO_\|_ [perl #96326].
+.SS "User-defined case-changing operations"
+.IX Subsection "User-defined case-changing operations"
+This feature was deprecated in Perl 5.14, and has now been removed.
+The CPAN module Unicode::Casing provides better functionality without
+the drawbacks that this feature had, as are detailed in the 5.14
+documentation:
+<http://perldoc.perl.org/5.14.0/perlunicode.html#User\-Defined\-Case\-Mappings\-%28for\-serious\-hackers\-only%29>
+.SS "XSUBs are now 'static'"
+.IX Subsection "XSUBs are now 'static'"
+XSUB C functions are now 'static', that is, they are not visible from
+outside the compilation unit.  Users can use the new \f(CWXS_EXTERNAL(name)\fR
+and \f(CWXS_INTERNAL(name)\fR macros to pick the desired linking behavior.
+The ordinary \f(CWXS(name)\fR declaration for XSUBs will continue to declare
+non\-'static' XSUBs for compatibility, but the XS compiler,
+ExtUtils::ParseXS (\f(CW\*(C`xsubpp\*(C'\fR) will emit 'static' XSUBs by default.
+ExtUtils::ParseXS's behavior can be reconfigured from XS using the
+\&\f(CW\*(C`EXPORT_XSUB_SYMBOLS\*(C'\fR keyword.  See perlxs for details.
+.SS "Weakening read-only references"
+.IX Subsection "Weakening read-only references"
+Weakening read-only references is no longer permitted.  It should never
+have worked anyway, and could sometimes result in crashes.
+.SS "Tying scalars that hold typeglobs"
+.IX Subsection "Tying scalars that hold typeglobs"
+Attempting to tie a scalar after a typeglob was assigned to it would
+instead tie the handle in the typeglob's IO slot.  This meant that it was
+impossible to tie the scalar itself.  Similar problems affected \f(CW\*(C`tied\*(C'\fR and
+\&\f(CW\*(C`untie\*(C'\fR: \f(CW\*(C`tied $scalar\*(C'\fR would return false on a tied scalar if the last
+thing returned was a typeglob, and \f(CW\*(C`untie $scalar\*(C'\fR on such a tied scalar
+would do nothing.
+.PP
+We fixed this problem before Perl 5.14.0, but it caused problems with some
+CPAN modules, so we put in a deprecation cycle instead.
+.PP
+Now the deprecation has been removed and this bug has been fixed.  So
+\&\f(CW\*(C`tie $scalar\*(C'\fR will always tie the scalar, not the handle it holds.  To tie
+the handle, use \f(CW\*(C`tie *$scalar\*(C'\fR (with an explicit asterisk).  The same
+applies to \f(CW\*(C`tied *$scalar\*(C'\fR and \f(CW\*(C`untie *$scalar\*(C'\fR.
+.ie n .SS "IPC::Open3 no longer provides xfork(), xclose_on_exec() and xpipe_anon()"
+.el .SS "IPC::Open3 no longer provides \f(CWxfork()\fP, \f(CWxclose_on_exec()\fP and \f(CWxpipe_anon()\fP"
+.IX Subsection "IPC::Open3 no longer provides xfork(), xclose_on_exec() and xpipe_anon()"
+All three functions were private, undocumented, and unexported.  They do
+not appear to be used by any code on CPAN.  Two have been inlined and one
+deleted entirely.
+.ie n .SS "$$ no longer caches PID"
+.el .SS "\f(CW$$\fP no longer caches PID"
+.IX Subsection "$$ no longer caches PID"
+Previously, if one called \fBfork\fR\|(3) from C, Perl's
+notion of \f(CW$$\fR could go out of sync with what \fBgetpid()\fR returns.  By always
+fetching the value of \f(CW$$\fR via \fBgetpid()\fR, this potential bug is eliminated.
+Code that depends on the caching behavior will break.  As described in
+Core Enhancements,
+\&\f(CW$$\fR is now writable, but it will be reset during a
+fork.
+.ie n .SS "$$ and getppid() no longer emulate POSIX semantics under LinuxThreads"
+.el .SS "\f(CW$$\fP and \f(CWgetppid()\fP no longer emulate POSIX semantics under LinuxThreads"
+.IX Subsection "$$ and getppid() no longer emulate POSIX semantics under LinuxThreads"
+The POSIX emulation of \f(CW$$\fR and \f(CWgetppid()\fR under the obsolete
+LinuxThreads implementation has been removed.
+This only impacts users of Linux 2.4 and
+users of Debian GNU/kFreeBSD up to and including 6.0, not the vast
+majority of Linux installations that use NPTL threads.
+.PP
+This means that \f(CWgetppid()\fR, like \f(CW$$\fR, is now always guaranteed to
+return the OS's idea of the current state of the process, not perl's
+cached version of it.
+.PP
+See the documentation for $$ for details.
+.ie n .SS "$<, $>, $( and $) are no longer cached"
+.el .SS "\f(CW$<\fP, \f(CW$>\fP, \f(CW$(\fP and \f(CW$)\fP are no longer cached"
+.IX Subsection "$<, $>, $( and $) are no longer cached"
+Similarly to the changes to \f(CW$$\fR and \f(CWgetppid()\fR, the internal
+caching of \f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR has been removed.
+.PP
+When we cached these values our idea of what they were would drift out
+of sync with reality if someone (e.g., someone embedding perl) called
+\&\f(CW\*(C`sete?[ug]id()\*(C'\fR without updating \f(CW\*(C`PL_e?[ug]id\*(C'\fR.  Having to deal with
+this complexity wasn't worth it given how cheap the \f(CW\*(C`gete?[ug]id()\*(C'\fR
+system call is.
+.PP
+This change will break a handful of CPAN modules that use the XS-level
+\&\f(CW\*(C`PL_uid\*(C'\fR, \f(CW\*(C`PL_gid\*(C'\fR, \f(CW\*(C`PL_euid\*(C'\fR or \f(CW\*(C`PL_egid\*(C'\fR variables.
+.PP
+The fix for those breakages is to use \f(CW\*(C`PerlProc_gete?[ug]id()\*(C'\fR to
+retrieve them (e.g., \f(CWPerlProc_getuid()\fR), and not to assign to
+\&\f(CW\*(C`PL_e?[ug]id\*(C'\fR if you change the UID/GID/EUID/EGID.  There is no longer
+any need to do so since perl will always retrieve the up-to-date
+version of those values from the OS.
+.ie n .SS "Which Non-ASCII characters get quoted by ""quotemeta"" and ""\eQ"" has changed"
+.el .SS "Which Non-ASCII characters get quoted by \f(CWquotemeta\fP and \f(CW\eQ\fP has changed"
+.IX Subsection "Which Non-ASCII characters get quoted by quotemeta and Q has changed"
+This is unlikely to result in a real problem, as Perl does not attach
+special meaning to any non-ASCII character, so it is currently
+irrelevant which are quoted or not.  This change fixes bug [perl #77654] and
+brings Perl's behavior more into line with Unicode's recommendations.
+See "quotemeta" in perlfunc.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Improved performance for Unicode properties in regular expressions
+.Sp
+Matching a code point against a Unicode property is now done via a
+binary search instead of linear.  This means for example that the worst
+case for a 1000 item property is 10 probes instead of 1000.  This
+inefficiency has been compensated for in the past by permanently storing
+in a hash the results of a given probe plus the results for the adjacent
+64 code points, under the theory that near-by code points are likely to
+be searched for.  A separate hash was used for each mention of a Unicode
+property in each regular expression.  Thus, \f(CW\*(C`qr/\ep{foo}abc\ep{foo}/\*(C'\fR
+would generate two hashes.  Any probes in one instance would be unknown
+to the other, and the hashes could expand separately to be quite large
+if the regular expression were used on many different widely-separated
+code points.
+Now, however, there is just one hash shared by all instances of a given
+property.  This means that if \f(CW\*(C`\ep{foo}\*(C'\fR is matched against "A" in one
+regular expression in a thread, the result will be known immediately to
+all regular expressions, and the relentless march of using up memory is
+slowed considerably.
+.IP \(bu 4
+Version declarations with the \f(CW\*(C`use\*(C'\fR keyword (e.g., \f(CW\*(C`use 5.012\*(C'\fR) are now
+faster, as they enable features without loading \fIfeature.pm\fR.
+.IP \(bu 4
+\&\f(CW\*(C`local $_\*(C'\fR is faster now, as it no longer iterates through magic that it
+is not going to copy anyway.
+.IP \(bu 4
+Perl 5.12.0 sped up the destruction of objects whose classes define
+empty \f(CW\*(C`DESTROY\*(C'\fR methods (to prevent autoloading), by simply not
+calling such empty methods.  This release takes this optimization a
+step further, by not calling any \f(CW\*(C`DESTROY\*(C'\fR method that begins with a
+\&\f(CW\*(C`return\*(C'\fR statement.  This can be useful for destructors that are only
+used for debugging:
+.Sp
+.Vb 2
+\&    use constant DEBUG => 1;
+\&    sub DESTROY { return unless DEBUG; ... }
+.Ve
+.Sp
+Constant-folding will reduce the first statement to \f(CW\*(C`return;\*(C'\fR if DEBUG
+is set to 0, triggering this optimization.
+.IP \(bu 4
+Assigning to a variable that holds a typeglob or copy-on-write scalar
+is now much faster.  Previously the typeglob would be stringified or
+the copy-on-write scalar would be copied before being clobbered.
+.IP \(bu 4
+Assignment to \f(CW\*(C`substr\*(C'\fR in void context is now more than twice its
+previous speed.  Instead of creating and returning a special lvalue
+scalar that is then assigned to, \f(CW\*(C`substr\*(C'\fR modifies the original string
+itself.
+.IP \(bu 4
+\&\f(CW\*(C`substr\*(C'\fR no longer calculates a value to return when called in void
+context.
+.IP \(bu 4
+Due to changes in File::Glob, Perl's \f(CW\*(C`glob\*(C'\fR function and its \f(CW\*(C`<...>\*(C'\fR equivalent are now much faster.  The splitting of the pattern
+into words has been rewritten in C, resulting in speed-ups of 20% for
+some cases.
+.Sp
+This does not affect \f(CW\*(C`glob\*(C'\fR on VMS, as it does not use File::Glob.
+.IP \(bu 4
+The short-circuiting operators \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR, and \f(CW\*(C`//\*(C'\fR, when chained
+(such as \f(CW\*(C`$a || $b || $c\*(C'\fR), are now considerably faster to short-circuit,
+due to reduced optree traversal.
+.IP \(bu 4
+The implementation of \f(CW\*(C`s///r\*(C'\fR makes one fewer copy of the scalar's value.
+.IP \(bu 4
+Recursive calls to lvalue subroutines in lvalue scalar context use less
+memory.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Deprecated Modules"
+.IX Subsection "Deprecated Modules"
+.IP Version::Requirements 4
+.IX Item "Version::Requirements"
+Version::Requirements is now DEPRECATED, use CPAN::Meta::Requirements,
+which is a drop-in replacement.  It will be deleted from perl.git blead
+in v5.17.0.
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+arybase \-\- this new module implements the \f(CW$[\fR variable.
+.IP \(bu 4
+PerlIO::mmap 0.010 has been added to the Perl core.
+.Sp
+The \f(CW\*(C`mmap\*(C'\fR PerlIO layer is no longer implemented by perl itself, but has
+been moved out into the new PerlIO::mmap module.
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+This is only an overview of selected module updates.  For a complete list of
+updates, run:
+.PP
+.Vb 1
+\&    $ corelist \-\-diff 5.14.0 5.16.0
+.Ve
+.PP
+You can substitute your favorite version in place of 5.14.0, too.
+.IP \(bu 4
+Archive::Extract has been upgraded from version 0.48 to 0.58.
+.Sp
+Includes a fix for FreeBSD to only use \f(CW\*(C`unzip\*(C'\fR if it is located in
+\&\f(CW\*(C`/usr/local/bin\*(C'\fR, as FreeBSD 9.0 will ship with a limited \f(CW\*(C`unzip\*(C'\fR in
+\&\f(CW\*(C`/usr/bin\*(C'\fR.
+.IP \(bu 4
+Archive::Tar has been upgraded from version 1.76 to 1.82.
+.Sp
+Adjustments to handle files >8gb (>0777777777777 octal) and a feature
+to return the MD5SUM of files in the archive.
+.IP \(bu 4
+base has been upgraded from version 2.16 to 2.18.
+.Sp
+\&\f(CW\*(C`base\*(C'\fR no longer sets a module's \f(CW$VERSION\fR to "\-1" when a module it
+loads does not define a \f(CW$VERSION\fR.  This change has been made because
+"\-1" is not a valid version number under the new "lax" criteria used
+internally by \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR.  (See version for more on "lax"
+version criteria.)
+.Sp
+\&\f(CW\*(C`base\*(C'\fR no longer internally skips loading modules it has already loaded
+and instead relies on \f(CW\*(C`require\*(C'\fR to inspect \f(CW%INC\fR.  This fixes a bug
+when \f(CW\*(C`base\*(C'\fR is used with code that clear \f(CW%INC\fR to force a module to
+be reloaded.
+.IP \(bu 4
+Carp has been upgraded from version 1.20 to 1.26.
+.Sp
+It now includes last read filehandle info and puts a dot after the file
+and line number, just like errors from \f(CW\*(C`die\*(C'\fR [perl #106538].
+.IP \(bu 4
+charnames has been updated from version 1.18 to 1.30.
+.Sp
+\&\f(CW\*(C`charnames\*(C'\fR can now be invoked with a new option, \f(CW\*(C`:loose\*(C'\fR,
+which is like the existing \f(CW\*(C`:full\*(C'\fR option, but enables Unicode loose
+name matching.  Details are in "LOOSE MATCHES" in charnames.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.03 to 1.14.  This fixes
+numerous deparsing bugs.
+.IP \(bu 4
+CGI has been upgraded from version 3.52 to 3.59.
+.Sp
+It uses the public and documented FCGI.pm API in CGI::Fast.  CGI::Fast was
+using an FCGI API that was deprecated and removed from documentation
+more than ten years ago.  Usage of this deprecated API with FCGI >=
+0.70 or FCGI <= 0.73 introduces a security issue.
+<https://rt.cpan.org/Public/Bug/Display.html?id=68380>
+<http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE\-2011\-2766>
+.Sp
+Things that may break your code:
+.Sp
+\&\f(CWurl()\fR was fixed to return \f(CW\*(C`PATH_INFO\*(C'\fR when it is explicitly requested
+with either the \f(CW\*(C`path=>1\*(C'\fR or \f(CW\*(C`path_info=>1\*(C'\fR flag.
+.Sp
+If your code is running under mod_rewrite (or compatible) and you are
+calling \f(CWself_url()\fR or you are calling \f(CWurl()\fR and passing
+\&\f(CW\*(C`path_info=>1\*(C'\fR, these methods will actually be returning
+\&\f(CW\*(C`PATH_INFO\*(C'\fR now, as you have explicitly requested or \f(CWself_url()\fR
+has requested on your behalf.
+.Sp
+The \f(CW\*(C`PATH_INFO\*(C'\fR has been omitted in such URLs since the issue was
+introduced in the 3.12 release in December, 2005.
+.Sp
+This bug is so old your application may have come to depend on it or
+workaround it. Check for application before upgrading to this release.
+.Sp
+Examples of affected method calls:
+.Sp
+.Vb 5
+\&  $q\->url(\-absolute => 1, \-query => 1, \-path_info => 1);
+\&  $q\->url(\-path=>1);
+\&  $q\->url(\-full=>1,\-path=>1);
+\&  $q\->url(\-rewrite=>1,\-path=>1);
+\&  $q\->self_url();
+.Ve
+.Sp
+We no longer read from STDIN when the Content-Length is not set,
+preventing requests with no Content-Length from sometimes freezing.
+This is consistent with the CGI RFC 3875, and is also consistent with
+CGI::Simple.  However, the old behavior may have been expected by some
+command-line uses of CGI.pm.
+.Sp
+In addition, the DELETE HTTP verb is now supported.
+.IP \(bu 4
+Compress::Zlib has been upgraded from version 2.035 to 2.048.
+.Sp
+IO::Compress::Zip and IO::Uncompress::Unzip now have support for LZMA
+(method 14).  There is a fix for a CRC issue in IO::Compress::Unzip and
+it supports Streamed Stored context now.  And fixed a Zip64 issue in
+IO::Compress::Zip when the content size was exactly 0xFFFFFFFF.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.61 to 5.71.
+.Sp
+Added BITS mode to the addfile method and shasum.  This makes
+partial-byte inputs possible via files/STDIN and lets shasum check
+all 8074 NIST Msg vectors, where previously special programming was
+required to do this.
+.IP \(bu 4
+Encode has been upgraded from version 2.42 to 2.44.
+.Sp
+Missing aliases added, a deep recursion error fixed and various
+documentation updates.
+.Sp
+Addressed 'decode_xs n\-byte heap\-overflow' security bug in Unicode.xs
+(CVE\-2011\-2939). (5.14.2)
+.IP \(bu 4
+ExtUtils::CBuilder updated from version 0.280203 to 0.280206.
+.Sp
+The new version appends CFLAGS and LDFLAGS to their Config.pm
+counterparts.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 2.2210 to 3.16.
+.Sp
+Much of ExtUtils::ParseXS, the module behind the XS compiler \f(CW\*(C`xsubpp\*(C'\fR,
+was rewritten and cleaned up.  It has been made somewhat more extensible
+and now finally uses strictures.
+.Sp
+The typemap logic has been moved into a separate module,
+ExtUtils::Typemaps.  See "New Modules and Pragmata", above.
+.Sp
+For a complete set of changes, please see the ExtUtils::ParseXS
+changelog, available on the CPAN.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.12 to 1.17.
+.Sp
+On Windows, tilde (~) expansion now checks the \f(CW\*(C`USERPROFILE\*(C'\fR environment
+variable, after checking \f(CW\*(C`HOME\*(C'\fR.
+.Sp
+It has a new \f(CW\*(C`:bsd_glob\*(C'\fR export tag, intended to replace \f(CW\*(C`:glob\*(C'\fR.  Like
+\&\f(CW\*(C`:glob\*(C'\fR it overrides \f(CW\*(C`glob\*(C'\fR with a function that does not split the glob
+pattern into words, but, unlike \f(CW\*(C`:glob\*(C'\fR, it iterates properly in scalar
+context, instead of returning the last file.
+.Sp
+There are other changes affecting Perl's own \f(CW\*(C`glob\*(C'\fR operator (which uses
+File::Glob internally, except on VMS).  See "Performance Enhancements"
+and "Selected Bug Fixes".
+.IP \(bu 4
+FindBin updated from version 1.50 to 1.51.
+.Sp
+It no longer returns a wrong result if a script of the same name as the
+current one exists in the path and is executable.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.012 to 0.017.
+.Sp
+Added support for using \f(CW$ENV{http_proxy}\fR to set the default proxy host.
+.Sp
+Adds additional shorthand methods for all common HTTP verbs,
+a \f(CWpost_form()\fR method for POST-ing x\-www-form-urlencoded data and
+a \f(CWwww_form_urlencode()\fR utility method.
+.IP \(bu 4
+IO has been upgraded from version 1.25_04 to 1.25_06, and IO::Handle
+from version 1.31 to 1.33.
+.Sp
+Together, these upgrades fix a problem with IO::Handle's \f(CW\*(C`getline\*(C'\fR and
+\&\f(CW\*(C`getlines\*(C'\fR methods.  When these methods are called on the special ARGV
+handle, the next file is automatically opened, as happens with the built-in
+\&\f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`readline\*(C'\fR functions.  But, unlike the built-ins, these
+methods were not respecting the caller's use of the open pragma and
+applying the appropriate I/O layers to the newly-opened file
+[rt.cpan.org #66474].
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.70 to 0.76.
+.Sp
+Capturing of command output (both \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR) is now supported
+using IPC::Open3 on MSWin32 without requiring IPC::Run.
+.IP \(bu 4
+IPC::Open3 has been upgraded from version 1.09 to 1.12.
+.Sp
+Fixes a bug which prevented use of \f(CW\*(C`open3\*(C'\fR on Windows when \f(CW*STDIN\fR,
+\&\f(CW*STDOUT\fR or \f(CW*STDERR\fR had been localized.
+.Sp
+Fixes a bug which prevented duplicating numeric file descriptors on Windows.
+.Sp
+\&\f(CW\*(C`open3\*(C'\fR with "\-" for the program name works once more.  This was broken in
+version 1.06 (and hence in Perl 5.14.0) [perl #95748].
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.16 to 3.21.
+.Sp
+Added Language Extension codes (langext) and Language Variation codes (langvar)
+as defined in the IANA language registry.
+.Sp
+Added language codes from ISO 639\-5
+.Sp
+Added language/script codes from the IANA language subtag registry
+.Sp
+Fixed an uninitialized value warning [rt.cpan.org #67438].
+.Sp
+Fixed the return value for the all_XXX_codes and all_XXX_names functions
+[rt.cpan.org #69100].
+.Sp
+Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to allow
+for cleaner future additions.  The original four modules (Locale::Language,
+Locale::Currency, Locale::Country, Locale::Script) will continue to work, but
+all new sets of codes will be added in the Locale::Codes namespace.
+.Sp
+The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions now
+support retired codes.  All codesets may be specified by a constant or
+by their name now.  Previously, they were specified only by a constant.
+.Sp
+The alias_code function exists for backward compatibility.  It has been
+replaced by rename_country_code.  The alias_code function will be
+removed some time after September, 2013.
+.Sp
+All work is now done in the central module (Locale::Codes).  Previously,
+some was still done in the wrapper modules (Locale::Codes::*).  Added
+Language Family codes (langfam) as defined in ISO 639\-5.
+.IP \(bu 4
+Math::BigFloat has been upgraded from version 1.993 to 1.997.
+.Sp
+The \f(CW\*(C`numify\*(C'\fR method has been corrected to return a normalized Perl number
+(the result of \f(CW\*(C`0 + $thing\*(C'\fR), instead of a string [rt.cpan.org #66732].
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.994 to 1.998.
+.Sp
+It provides a new \f(CW\*(C`bsgn\*(C'\fR method that complements the \f(CW\*(C`babs\*(C'\fR method.
+.Sp
+It fixes the internal \f(CW\*(C`objectify\*(C'\fR function's handling of "foreign objects"
+so they are converted to the appropriate class (Math::BigInt or
+Math::BigFloat).
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2602 to 0.2603.
+.Sp
+\&\f(CWint()\fR on a Math::BigRat object containing \-1/2 now creates a
+Math::BigInt containing 0, rather than \-0.  Math::BigInt does not even
+support negative zero, so the resulting object was actually malformed
+[perl #95530].
+.IP \(bu 4
+Math::Complex has been upgraded from version 1.56 to 1.59
+and Math::Trig from version 1.2 to 1.22.
+.Sp
+Fixes include: correct copy constructor usage; fix polarwise formatting with
+numeric format specifier; and more stable \f(CW\*(C`great_circle_direction\*(C'\fR algorithm.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 2.51 to 2.66.
+.Sp
+The \f(CW\*(C`corelist\*(C'\fR utility now understands the \f(CW\*(C`\-r\*(C'\fR option for displaying
+Perl release dates and the \f(CW\*(C`\-\-diff\*(C'\fR option to print the set of modlib
+changes between two perl distributions.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000004 to 1.000009.
+.Sp
+Adds \f(CW\*(C`provides\*(C'\fR method to generate a CPAN META provides data structure
+correctly; use of \f(CW\*(C`package_versions_from_directory\*(C'\fR is discouraged.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.10 to 1.12.
+.Sp
+The XS code is now compiled with \f(CW\*(C`PERL_NO_GET_CONTEXT\*(C'\fR, which will aid
+performance under ithreads.
+.IP \(bu 4
+open has been upgraded from version 1.08 to 1.10.
+.Sp
+It no longer turns off layers on standard handles when invoked without the
+":std" directive.  Similarly, when invoked \fIwith\fR the ":std" directive, it
+now clears layers on STDERR before applying the new ones, and not just on
+STDIN and STDOUT [perl #92728].
+.IP \(bu 4
+overload has been upgraded from version 1.13 to 1.18.
+.Sp
+\&\f(CW\*(C`overload::Overloaded\*(C'\fR no longer calls \f(CW\*(C`can\*(C'\fR on the class, but uses
+another means to determine whether the object has overloading.  It was
+never correct for it to call \f(CW\*(C`can\*(C'\fR, as overloading does not respect
+AUTOLOAD.  So classes that autoload methods and implement \f(CW\*(C`can\*(C'\fR no longer
+have to account for overloading [perl #40333].
+.Sp
+A warning is now produced for invalid arguments.  See "New Diagnostics".
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.11 to 0.14.
+.Sp
+(This is the module that implements \f(CW\*(C`open $fh, \*(Aq>\*(Aq, \e$scalar\*(C'\fR.)
+.Sp
+It fixes a problem with \f(CW\*(C`open my $fh, ">", \e$scalar\*(C'\fR not working if
+\&\f(CW$scalar\fR is a copy-on-write scalar. (5.14.2)
+.Sp
+It also fixes a hang that occurs with \f(CW\*(C`readline\*(C'\fR or \f(CW\*(C`<$fh>\*(C'\fR if a
+typeglob has been assigned to \f(CW$scalar\fR [perl #92258].
+.Sp
+It no longer assumes during \f(CW\*(C`seek\*(C'\fR that \f(CW$scalar\fR is a string internally.
+If it didn't crash, it was close to doing so [perl #92706].  Also, the
+internal print routine no longer assumes that the position set by \f(CW\*(C`seek\*(C'\fR
+is valid, but extends the string to that position, filling the intervening
+bytes (between the old length and the seek position) with nulls
+[perl #78980].
+.Sp
+Printing to an in-memory handle now works if the \f(CW$scalar\fR holds a reference,
+stringifying the reference before modifying it.  References used to be
+treated as empty strings.
+.Sp
+Printing to an in-memory handle no longer crashes if the \f(CW$scalar\fR happens to
+hold a number internally, but no string buffer.
+.Sp
+Printing to an in-memory handle no longer creates scalars that confuse
+the regular expression engine [perl #108398].
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.04 to 1.05.
+.Sp
+\&\fIFunctions.pm\fR is now generated at perl build time from annotations in
+\&\fIperlfunc.pod\fR.  This will ensure that Pod::Functions and perlfunc
+remain in synchronisation.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.11 to 1.1502.
+.Sp
+This is an extensive rewrite of Pod::Html to use Pod::Simple under
+the hood.  The output has changed significantly.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.15_03 to 3.17.
+.Sp
+It corrects the search paths on VMS [perl #90640]. (5.14.1)
+.Sp
+The \fB\-v\fR option now fetches the right section for \f(CW$0\fR.
+.Sp
+This upgrade has numerous significant fixes.  Consult its changelog on
+the CPAN for more information.
+.IP \(bu 4
+POSIX has been upgraded from version 1.24 to 1.30.
+.Sp
+POSIX no longer uses AutoLoader.  Any code which was relying on this
+implementation detail was buggy, and may fail because of this change.
+The module's Perl code has been considerably simplified, roughly halving
+the number of lines, with no change in functionality.  The XS code has
+been refactored to reduce the size of the shared object by about 12%,
+with no change in functionality.  More POSIX functions now have tests.
+.Sp
+\&\f(CW\*(C`sigsuspend\*(C'\fR and \f(CW\*(C`pause\*(C'\fR now run signal handlers before returning, as the
+whole point of these two functions is to wait until a signal has
+arrived, and then return \fIafter\fR it has been triggered.  Delayed, or
+"safe", signals were preventing that from happening, possibly resulting in
+race conditions [perl #107216].
+.Sp
+\&\f(CW\*(C`POSIX::sleep\*(C'\fR is now a direct call into the underlying OS \f(CW\*(C`sleep\*(C'\fR
+function, instead of being a Perl wrapper on \f(CW\*(C`CORE::sleep\*(C'\fR.
+\&\f(CW\*(C`POSIX::dup2\*(C'\fR now returns the correct value on Win32 (\fIi.e.\fR, the file
+descriptor).  \f(CW\*(C`POSIX::SigSet\*(C'\fR \f(CW\*(C`sigsuspend\*(C'\fR and \f(CW\*(C`sigpending\*(C'\fR and
+\&\f(CW\*(C`POSIX::pause\*(C'\fR now dispatch safe signals immediately before returning to
+their caller.
+.Sp
+\&\f(CW\*(C`POSIX::Termios::setattr\*(C'\fR now defaults the third argument to \f(CW\*(C`TCSANOW\*(C'\fR,
+instead of 0. On most platforms \f(CW\*(C`TCSANOW\*(C'\fR is defined to be 0, but on some
+0 is not a valid parameter, which caused a call with defaults to fail.
+.IP \(bu 4
+Socket has been upgraded from version 1.94 to 2.001.
+.Sp
+It has new functions and constants for handling IPv6 sockets:
+.Sp
+.Vb 11
+\&    pack_ipv6_mreq
+\&    unpack_ipv6_mreq
+\&    IPV6_ADD_MEMBERSHIP
+\&    IPV6_DROP_MEMBERSHIP
+\&    IPV6_MTU
+\&    IPV6_MTU_DISCOVER
+\&    IPV6_MULTICAST_HOPS
+\&    IPV6_MULTICAST_IF
+\&    IPV6_MULTICAST_LOOP
+\&    IPV6_UNICAST_HOPS
+\&    IPV6_V6ONLY
+.Ve
+.IP \(bu 4
+Storable has been upgraded from version 2.27 to 2.34.
+.Sp
+It no longer turns copy-on-write scalars into read-only scalars when
+freezing and thawing.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.27 to 0.29.
+.Sp
+This upgrade closes many outstanding bugs.
+.IP \(bu 4
+Term::ANSIColor has been upgraded from version 3.00 to 3.01.
+.Sp
+Only interpret an initial array reference as a list of colors, not any initial
+reference, allowing the colored function to work properly on objects with
+stringification defined.
+.IP \(bu 4
+Term::ReadLine has been upgraded from version 1.07 to 1.09.
+.Sp
+Term::ReadLine now supports any event loop, including unpublished ones and
+simple IO::Select, loops without the need to rewrite existing code for
+any particular framework [perl #108470].
+.IP \(bu 4
+threads::shared has been upgraded from version 1.37 to 1.40.
+.Sp
+Destructors on shared objects used to be ignored sometimes if the objects
+were referenced only by shared data structures.  This has been mostly
+fixed, but destructors may still be ignored if the objects still exist at
+global destruction time [perl #98204].
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 0.73 to 0.89.
+.Sp
+Updated to CLDR 1.9.1
+.Sp
+Locales updated to CLDR 2.0: mk, mt, nb, nn, ro, ru, sk, sr, sv, uk,
+zh_\|_pinyin, zh_\|_stroke
+.Sp
+Newly supported locales: bn, fa, ml, mr, or, pa, sa, si, si_\|_dictionary,
+sr_Latn, sv_\|_reformed, ta, te, th, ur, wae.
+.Sp
+Tailored compatibility ideographs as well as unified ideographs for the
+locales: ja, ko, zh_\|_big5han, zh_\|_gb2312han, zh_\|_pinyin, zh_\|_stroke.
+.Sp
+Locale/*.pl files are now searched for in \f(CW@INC\fR.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.10 to 1.14.
+.Sp
+Fixes for the removal of \fIunicore/CompositionExclusions.txt\fR from core.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.32 to 0.43.
+.Sp
+This adds four new functions:  \f(CWprop_aliases()\fR and
+\&\f(CWprop_value_aliases()\fR, which are used to find all Unicode-approved
+synonyms for property names, or to convert from one name to another;
+\&\f(CW\*(C`prop_invlist\*(C'\fR which returns all code points matching a given
+Unicode binary property; and \f(CW\*(C`prop_invmap\*(C'\fR which returns the complete
+specification of a given Unicode property.
+.IP \(bu 4
+Win32API::File has been upgraded from version 0.1101 to 0.1200.
+.Sp
+Added SetStdHandle and GetStdHandle functions
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+As promised in Perl 5.14.0's release notes, the following modules have
+been removed from the core distribution, and if needed should be installed
+from CPAN instead.
+.IP \(bu 4
+Devel::DProf has been removed from the Perl core.  Prior version was
+20110228.00.
+.IP \(bu 4
+Shell has been removed from the Perl core.  Prior version was 0.72_01.
+.IP \(bu 4
+Several old perl4\-style libraries which have been deprecated with 5.14
+are now removed:
+.Sp
+.Vb 5
+\&    abbrev.pl assert.pl bigfloat.pl bigint.pl bigrat.pl cacheout.pl
+\&    complete.pl ctime.pl dotsh.pl exceptions.pl fastcwd.pl flush.pl
+\&    getcwd.pl getopt.pl getopts.pl hostname.pl importenv.pl
+\&    lib/find{,depth}.pl look.pl newgetopt.pl open2.pl open3.pl
+\&    pwd.pl shellwords.pl stat.pl tainted.pl termcap.pl timelocal.pl
+.Ve
+.Sp
+They can be found on CPAN as Perl4::CoreLibs.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperldtrace\fR
+.IX Subsection "perldtrace"
+.PP
+perldtrace describes Perl's DTrace support, listing the provided probes
+and gives examples of their use.
+.PP
+\fIperlexperiment\fR
+.IX Subsection "perlexperiment"
+.PP
+This document is intended to provide a list of experimental features in
+Perl.  It is still a work in progress.
+.PP
+\fIperlootut\fR
+.IX Subsection "perlootut"
+.PP
+This a new OO tutorial.  It focuses on basic OO concepts, and then recommends
+that readers choose an OO framework from CPAN.
+.PP
+\fIperlxstypemap\fR
+.IX Subsection "perlxstypemap"
+.PP
+The new manual describes the XS typemapping mechanism in unprecedented
+detail and combines new documentation with information extracted from
+perlxs and the previously unofficial list of all core typemaps.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+The HV API has long accepted negative lengths to show that the key is
+in UTF8.  This is now documented.
+.IP \(bu 4
+The \f(CWboolSV()\fR macro is now documented.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+\&\f(CW\*(C`dbmopen\*(C'\fR treats a 0 mode as a special case, that prevents a nonexistent
+file from being created.  This has been the case since Perl 5.000, but was
+never documented anywhere.  Now the perlfunc entry mentions it
+[perl #90064].
+.IP \(bu 4
+As an accident of history, \f(CW\*(C`open $fh, \*(Aq<:\*(Aq, ...\*(C'\fR applies the default
+layers for the platform (\f(CW\*(C`:raw\*(C'\fR on Unix, \f(CW\*(C`:crlf\*(C'\fR on Windows), ignoring
+whatever is declared by open.pm.  This seems such a useful feature
+it has been documented in perlfunc and open.
+.IP \(bu 4
+The entry for \f(CW\*(C`split\*(C'\fR has been rewritten.  It is now far clearer than
+before.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+A new section, Autoloading with XSUBs,
+has been added, which explains the two APIs for accessing the name of the
+autoloaded sub.
+.IP \(bu 4
+Some function descriptions in perlguts were confusing, as it was
+not clear whether they referred to the function above or below the
+description.  This has been clarified [perl #91790].
+.PP
+\fIperlobj\fR
+.IX Subsection "perlobj"
+.IP \(bu 4
+This document has been rewritten from scratch, and its coverage of various OO
+concepts has been expanded.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Documentation of the smartmatch operator has been reworked and moved from
+perlsyn to perlop where it belongs.
+.Sp
+It has also been corrected for the case of \f(CW\*(C`undef\*(C'\fR on the left-hand
+side.  The list of different smart match behaviors had an item in the
+wrong place.
+.IP \(bu 4
+Documentation of the ellipsis statement (\f(CW\*(C`...\*(C'\fR) has been reworked and
+moved from perlop to perlsyn.
+.IP \(bu 4
+The explanation of bitwise operators has been expanded to explain how they
+work on Unicode strings (5.14.1).
+.IP \(bu 4
+More examples for \f(CW\*(C`m//g\*(C'\fR have been added (5.14.1).
+.IP \(bu 4
+The \f(CW\*(C`<<\eFOO\*(C'\fR here-doc syntax has been documented (5.14.1).
+.PP
+\fIperlpragma\fR
+.IX Subsection "perlpragma"
+.IP \(bu 4
+There is now a standard convention for naming keys in the \f(CW\*(C`%^H\*(C'\fR,
+documented under Key naming.
+.PP
+\fI"Laundering and Detecting Tainted Data" in perlsec\fR
+.IX Subsection """Laundering and Detecting Tainted Data"" in perlsec"
+.IP \(bu 4
+The example function for checking for taintedness contained a subtle
+error.  \f(CW$@\fR needs to be localized to prevent its changing this
+global's value outside the function.  The preferred method to check for
+this remains "tainted" in Scalar::Util.
+.PP
+\fIperllol\fR
+.IX Subsection "perllol"
+.IP \(bu 4
+perllol has been expanded with examples using the new \f(CW\*(C`push $scalar\*(C'\fR
+syntax introduced in Perl 5.14.0 (5.14.1).
+.PP
+\fIperlmod\fR
+.IX Subsection "perlmod"
+.IP \(bu 4
+perlmod now states explicitly that some types of explicit symbol table
+manipulation are not supported.  This codifies what was effectively already
+the case [perl #78074].
+.PP
+\fIperlpodstyle\fR
+.IX Subsection "perlpodstyle"
+.IP \(bu 4
+The tips on which formatting codes to use have been corrected and greatly
+expanded.
+.IP \(bu 4
+There are now a couple of example one-liners for previewing POD files after
+they have been edited.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+The \f(CW\*(C`(*COMMIT)\*(C'\fR directive is now listed in the right section
+(Verbs without an argument).
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+perlrun has undergone a significant clean-up.  Most notably, the
+\&\fB\-0x...\fR form of the \fB\-0\fR flag has been clarified, and the final section
+on environment variables has been corrected and expanded (5.14.1).
+.PP
+\fIperlsub\fR
+.IX Subsection "perlsub"
+.IP \(bu 4
+The ($;) prototype syntax, which has existed for rather a long time, is now
+documented in perlsub.  It lets a unary function have the same
+precedence as a list operator.
+.PP
+\fIperltie\fR
+.IX Subsection "perltie"
+.IP \(bu 4
+The required syntax for tying handles has been documented.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+The documentation for $! has been corrected and clarified.
+It used to state that $! could be \f(CW\*(C`undef\*(C'\fR, which is not the case.  It was
+also unclear whether system calls set C's \f(CW\*(C`errno\*(C'\fR or Perl's \f(CW$!\fR
+[perl #91614].
+.IP \(bu 4
+Documentation for $$ has been amended with additional
+cautions regarding changing the process ID.
+.PP
+\fIOther Changes\fR
+.IX Subsection "Other Changes"
+.IP \(bu 4
+perlxs was extended with documentation on inline typemaps.
+.IP \(bu 4
+perlref has a new Circular References
+section explaining how circularities may not be freed and how to solve that
+with weak references.
+.IP \(bu 4
+Parts of perlapi were clarified, and Perl equivalents of some C
+functions have been added as an additional mode of exposition.
+.IP \(bu 4
+A few parts of perlre and perlrecharclass were clarified.
+.SS "Removed Documentation"
+.IX Subsection "Removed Documentation"
+\fIOld OO Documentation\fR
+.IX Subsection "Old OO Documentation"
+.PP
+The old OO tutorials, perltoot, perltooc, and perlboot, have been
+removed.  The perlbot (bag of object tricks) document has been removed
+as well.
+.PP
+\fIDevelopment Deltas\fR
+.IX Subsection "Development Deltas"
+.PP
+The perldelta files for development releases are no longer packaged with
+perl.  These can still be found in the perl source code repository.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Cannot set tied \f(CW@DB::args\fR
+.Sp
+This error occurs when \f(CW\*(C`caller\*(C'\fR tries to set \f(CW@DB::args\fR but finds it
+tied.  Before this error was added, it used to crash instead.
+.IP \(bu 4
+Cannot tie unreifiable array
+.Sp
+This error is part of a safety check that the \f(CW\*(C`tie\*(C'\fR operator does before
+tying a special array like \f(CW@_\fR.  You should never see this message.
+.IP \(bu 4
+&CORE::%s cannot be called directly
+.Sp
+This occurs when a subroutine in the \f(CW\*(C`CORE::\*(C'\fR namespace is called
+with \f(CW&foo\fR syntax or through a reference.  Some subroutines
+in this package cannot yet be called that way, but must be
+called as barewords.  See "Subroutines in the \f(CW\*(C`CORE\*(C'\fR namespace", above.
+.IP \(bu 4
+Source filters apply only to byte streams
+.Sp
+This new error occurs when you try to activate a source filter (usually by
+loading a source filter module) within a string passed to \f(CW\*(C`eval\*(C'\fR under the
+\&\f(CW\*(C`unicode_eval\*(C'\fR feature.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+defined(@array) is deprecated
+.Sp
+The long-deprecated \f(CWdefined(@array)\fR now also warns for package variables.
+Previously it issued a warning for lexical variables only.
+.IP \(bu 4
+\&\fBlength()\fR used on \f(CW%s\fR
+.Sp
+This new warning occurs when \f(CW\*(C`length\*(C'\fR is used on an array or hash, instead
+of \f(CWscalar(@array)\fR or \f(CW\*(C`scalar(keys %hash)\*(C'\fR.
+.IP \(bu 4
+lvalue attribute \f(CW%s\fR already-defined subroutine
+.Sp
+attributes.pm now emits this warning when the :lvalue
+attribute is applied to a Perl subroutine that has already been defined, as
+doing so can have unexpected side-effects.
+.IP \(bu 4
+overload arg '%s' is invalid
+.Sp
+This warning, in the "overload" category, is produced when the overload
+pragma is given an argument it doesn't recognize, presumably a mistyped
+operator.
+.IP \(bu 4
+$[ used in \f(CW%s\fR (did you mean $] ?)
+.Sp
+This new warning exists to catch the mistaken use of \f(CW$[\fR in version
+checks.  \f(CW$]\fR, not \f(CW$[\fR, contains the version number.
+.IP \(bu 4
+Useless assignment to a temporary
+.Sp
+Assigning to a temporary scalar returned
+from an lvalue subroutine now produces this
+warning [perl #31946].
+.IP \(bu 4
+Useless use of \eE
+.Sp
+\&\f(CW\*(C`\eE\*(C'\fR does nothing unless preceded by \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR or \f(CW\*(C`\eU\*(C'\fR.
+.SS "Removed Errors"
+.IX Subsection "Removed Errors"
+.IP \(bu 4
+"sort is now a reserved word"
+.Sp
+This error used to occur when \f(CW\*(C`sort\*(C'\fR was called without arguments,
+followed by \f(CW\*(C`;\*(C'\fR or \f(CW\*(C`)\*(C'\fR.  (E.g., \f(CW\*(C`sort;\*(C'\fR would die, but \f(CW\*(C`{sort}\*(C'\fR was
+OK.)  This error message was added in Perl 3 to catch code like
+\&\f(CWclose(sort)\fR which would no longer work.  More than two decades later,
+this message is no longer appropriate.  Now \f(CW\*(C`sort\*(C'\fR without arguments is
+always allowed, and returns an empty list, as it did in those cases
+where it was already allowed [perl #90030].
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+The "Applying pattern match..." or similar warning produced when an
+array or hash is on the left-hand side of the \f(CW\*(C`=~\*(C'\fR operator now
+mentions the name of the variable.
+.IP \(bu 4
+The "Attempt to free non-existent shared string" has had the spelling
+of "non-existent" corrected to "nonexistent".  It was already listed
+with the correct spelling in perldiag.
+.IP \(bu 4
+The error messages for using \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`when\*(C'\fR outside a
+topicalizer have been standardized to match the messages for \f(CW\*(C`continue\*(C'\fR
+and loop controls.  They now read 'Can't "default" outside a
+topicalizer' and 'Can't "when" outside a topicalizer'.  They both used
+to be 'Can't use \fBwhen()\fR outside a topicalizer' [perl #91514].
+.IP \(bu 4
+The message, "Code point 0x%X is not Unicode, no properties match it;
+all inverse properties do" has been changed to "Code point 0x%X is not
+Unicode, all \ep{} matches fail; all \eP{} matches succeed".
+.IP \(bu 4
+Redefinition warnings for constant subroutines used to be mandatory,
+even occurring under \f(CW\*(C`no warnings\*(C'\fR.  Now they respect the warnings
+pragma.
+.IP \(bu 4
+The "glob failed" warning message is now suppressible via \f(CW\*(C`no warnings\*(C'\fR
+[perl #111656].
+.IP \(bu 4
+The Invalid version format
+error message now says "negative version number" within the parentheses,
+rather than "non-numeric data", for negative numbers.
+.IP \(bu 4
+The two warnings
+Possible attempt to put comments in \fBqw()\fR list
+and
+Possible attempt to separate words with commas
+are no longer mutually exclusive: the same \f(CW\*(C`qw\*(C'\fR construct may produce
+both.
+.IP \(bu 4
+The uninitialized warning for \f(CW\*(C`y///r\*(C'\fR when \f(CW$_\fR is implicit and
+undefined now mentions the variable name, just like the non\-/r variation
+of the operator.
+.IP \(bu 4
+The 'Use of "foo" without parentheses is ambiguous' warning has been
+extended to apply also to user-defined subroutines with a (;$)
+prototype, and not just to built-in functions.
+.IP \(bu 4
+Warnings that mention the names of lexical (\f(CW\*(C`my\*(C'\fR) variables with
+Unicode characters in them now respect the presence or absence of the
+\&\f(CW\*(C`:utf8\*(C'\fR layer on the output handle, instead of outputting UTF8
+regardless.  Also, the correct names are included in the strings passed
+to \f(CW$SIG{_\|_WARN_\|_}\fR handlers, rather than the raw UTF8 bytes.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\fIh2ph\fR
+.IX Subsection "h2ph"
+.IP \(bu 4
+h2ph used to generate code of the form
+.Sp
+.Vb 3
+\&  unless(defined(&FOO)) {
+\&    sub FOO () {42;}
+\&  }
+.Ve
+.Sp
+But the subroutine is a compile-time declaration, and is hence unaffected
+by the condition.  It has now been corrected to emit a string \f(CW\*(C`eval\*(C'\fR
+around the subroutine [perl #99368].
+.PP
+\fIsplain\fR
+.IX Subsection "splain"
+.IP \(bu 4
+\&\fIsplain\fR no longer emits backtraces with the first line number repeated.
+.Sp
+This:
+.Sp
+.Vb 6
+\&    Uncaught exception from user code:
+\&            Cannot fwiddle the fwuddle at \-e line 1.
+\&     at \-e line 1
+\&            main::baz() called at \-e line 1
+\&            main::bar() called at \-e line 1
+\&            main::foo() called at \-e line 1
+.Ve
+.Sp
+has become this:
+.Sp
+.Vb 5
+\&    Uncaught exception from user code:
+\&            Cannot fwiddle the fwuddle at \-e line 1.
+\&            main::baz() called at \-e line 1
+\&            main::bar() called at \-e line 1
+\&            main::foo() called at \-e line 1
+.Ve
+.IP \(bu 4
+Some error messages consist of multiple lines that are listed as separate
+entries in perldiag.  splain has been taught to find the separate
+entries in these cases, instead of simply failing to find the message.
+.PP
+\fIzipdetails\fR
+.IX Subsection "zipdetails"
+.IP \(bu 4
+This is a new utility, included as part of an
+IO::Compress::Base upgrade.
+.Sp
+zipdetails displays information about the internal record structure
+of the zip file.  It is not concerned with displaying any details of
+the compressed data stored in the zip file.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\fIregexp.h\fR has been modified for compatibility with GCC's \fB\-Werror\fR
+option, as used by some projects that include perl's header files (5.14.1).
+.IP \(bu 4
+\&\f(CW\*(C`USE_LOCALE{,_COLLATE,_CTYPE,_NUMERIC}\*(C'\fR have been added the output of perl \-V
+as they have affect the behavior of the interpreter binary (albeit
+in only a small area).
+.IP \(bu 4
+The code and tests for IPC::Open2 have been moved from \fIext/IPC\-Open2\fR
+into \fIext/IPC\-Open3\fR, as \f(CWIPC::Open2::open2()\fR is implemented as a thin
+wrapper around \f(CWIPC::Open3::_open3()\fR, and hence is very tightly coupled to
+it.
+.IP \(bu 4
+The magic types and magic vtables are now generated from data in a new script
+\&\fIregen/mg_vtable.pl\fR, instead of being maintained by hand.  As different
+EBCDIC variants can't agree on the code point for '~', the character to code
+point conversion is done at build time by \fIgenerate_uudmap\fR to a new generated
+header \fImg_data.h\fR.  \f(CW\*(C`PL_vtbl_bm\*(C'\fR and \f(CW\*(C`PL_vtbl_fm\*(C'\fR are now defined by the
+pre-processor as \f(CW\*(C`PL_vtbl_regexp\*(C'\fR, instead of being distinct C variables.
+\&\f(CW\*(C`PL_vtbl_sig\*(C'\fR has been removed.
+.IP \(bu 4
+Building with \f(CW\*(C`\-DPERL_GLOBAL_STRUCT\*(C'\fR works again.  This configuration is not
+generally used.
+.IP \(bu 4
+Perl configured with \fIMAD\fR now correctly frees \f(CW\*(C`MADPROP\*(C'\fR structures when
+OPs are freed.  \f(CW\*(C`MADPROP\*(C'\fRs are now allocated with \f(CWPerlMemShared_malloc()\fR
+.IP \(bu 4
+\&\fImakedef.pl\fR has been refactored.  This should have no noticeable affect on
+any of the platforms that use it as part of their build (AIX, VMS, Win32).
+.IP \(bu 4
+\&\f(CW\*(C`useperlio\*(C'\fR can no longer be disabled.
+.IP \(bu 4
+The file \fIglobal.sym\fR is no longer needed, and has been removed.  It
+contained a list of all exported functions, one of the files generated by
+\&\fIregen/embed.pl\fR from data in \fIembed.fnc\fR and \fIregen/opcodes\fR.  The code
+has been refactored so that the only user of \fIglobal.sym\fR, \fImakedef.pl\fR,
+now reads \fIembed.fnc\fR and \fIregen/opcodes\fR directly, removing the need to
+store the list of exported functions in an intermediate file.
+.Sp
+As \fIglobal.sym\fR was never installed, this change should not be visible
+outside the build process.
+.IP \(bu 4
+\&\fIpod/buildtoc\fR, used by the build process to build perltoc, has been
+refactored and simplified.  It now contains only code to build perltoc;
+the code to regenerate Makefiles has been moved to \fIPorting/pod_rules.pl\fR.
+It's a bug if this change has any material effect on the build process.
+.IP \(bu 4
+\&\fIpod/roffitall\fR is now built by \fIpod/buildtoc\fR, instead of being
+shipped with the distribution.  Its list of manpages is now generated
+(and therefore current).  See also RT #103202 for an unresolved related
+issue.
+.IP \(bu 4
+The man page for \f(CW\*(C`XS::Typemap\*(C'\fR is no longer installed.  \f(CW\*(C`XS::Typemap\*(C'\fR
+is a test module which is not installed, hence installing its
+documentation makes no sense.
+.IP \(bu 4
+The \-Dusesitecustomize and \-Duserelocatableinc options now work
+together properly.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+\fICygwin\fR
+.IX Subsection "Cygwin"
+.IP \(bu 4
+Since version 1.7, Cygwin supports native UTF\-8 paths.  If Perl is built
+under that environment, directory and filenames will be UTF\-8 encoded.
+.IP \(bu 4
+Cygwin does not initialize all original Win32 environment variables.  See
+\&\fIREADME.cygwin\fR for a discussion of the newly-added
+\&\f(CWCygwin::sync_winenv()\fR function [perl #110190] and for
+further links.
+.PP
+\fIHP-UX\fR
+.IX Subsection "HP-UX"
+.IP \(bu 4
+HP-UX PA\-RISC/64 now supports gcc\-4.x
+.Sp
+A fix to correct the socketsize now makes the test suite pass on HP-UX
+PA-RISC for 64bitall builds. (5.14.2)
+.PP
+\fIVMS\fR
+.IX Subsection "VMS"
+.IP \(bu 4
+Remove unnecessary includes, fix miscellaneous compiler warnings and
+close some unclosed comments on \fIvms/vms.c\fR.
+.IP \(bu 4
+Remove sockadapt layer from the VMS build.
+.IP \(bu 4
+Explicit support for VMS versions before v7.0 and DEC C versions
+before v6.0 has been removed.
+.IP \(bu 4
+Since Perl 5.10.1, the home-grown \f(CW\*(C`stat\*(C'\fR wrapper has been unable to
+distinguish between a directory name containing an underscore and an
+otherwise-identical filename containing a dot in the same position
+(e.g., t/test_pl as a directory and t/test.pl as a file).  This problem
+has been corrected.
+.IP \(bu 4
+The build on VMS now permits names of the resulting symbols in C code for
+Perl longer than 31 characters.  Symbols like
+\&\f(CW\*(C`Perl_\|_it_was_the_best_of_times_it_was_the_worst_of_times\*(C'\fR can now be
+created freely without causing the VMS linker to seize up.
+.PP
+\fIGNU/Hurd\fR
+.IX Subsection "GNU/Hurd"
+.IP \(bu 4
+Numerous build and test failures on GNU/Hurd have been resolved with hints
+for building DBM modules, detection of the library search path, and enabling
+of large file support.
+.PP
+\fIOpenVOS\fR
+.IX Subsection "OpenVOS"
+.IP \(bu 4
+Perl is now built with dynamic linking on OpenVOS, the minimum supported
+version of which is now Release 17.1.0.
+.PP
+\fISunOS\fR
+.IX Subsection "SunOS"
+.PP
+The CC workshop C++ compiler is now detected and used on systems that ship
+without cc.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+The compiled representation of formats is now stored via the \f(CW\*(C`mg_ptr\*(C'\fR of
+their \f(CW\*(C`PERL_MAGIC_fm\*(C'\fR.  Previously it was stored in the string buffer,
+beyond \f(CWSvLEN()\fR, the regular end of the string.  \f(CWSvCOMPILED()\fR and
+\&\f(CW\*(C`SvCOMPILED_{on,off}()\*(C'\fR now exist solely for compatibility for XS code.
+The first is always 0, the other two now no-ops. (5.14.1)
+.IP \(bu 4
+Some global variables have been marked \f(CW\*(C`const\*(C'\fR, members in the interpreter
+structure have been re-ordered, and the opcodes have been re-ordered.  The
+op \f(CW\*(C`OP_AELEMFAST\*(C'\fR has been split into \f(CW\*(C`OP_AELEMFAST\*(C'\fR and \f(CW\*(C`OP_AELEMFAST_LEX\*(C'\fR.
+.IP \(bu 4
+When empting a hash of its elements (e.g., via undef(%h), or \f(CW%h\fR=()), HvARRAY
+field is no longer temporarily zeroed.  Any destructors called on the freed
+elements see the remaining elements.  Thus, \f(CW%h\fR=() becomes more like
+\&\f(CW\*(C`delete $h{$_} for keys %h\*(C'\fR.
+.IP \(bu 4
+Boyer-Moore compiled scalars are now PVMGs, and the Boyer-Moore tables are now
+stored via the mg_ptr of their \f(CW\*(C`PERL_MAGIC_bm\*(C'\fR.
+Previously they were PVGVs, with the tables stored in
+the string buffer, beyond \f(CWSvLEN()\fR.  This eliminates
+the last place where the core stores data beyond \f(CWSvLEN()\fR.
+.IP \(bu 4
+Simplified logic in \f(CWPerl_sv_magic()\fR introduces a small change of
+behavior for error cases involving unknown magic types.  Previously, if
+\&\f(CWPerl_sv_magic()\fR was passed a magic type unknown to it, it would
+.RS 4
+.IP 1. 4
+Croak "Modification of a read-only value attempted" if read only
+.IP 2. 4
+Return without error if the SV happened to already have this magic
+.IP 3. 4
+otherwise croak "Don't know how to handle magic of type \e\e%o"
+.RE
+.RS 4
+.Sp
+Now it will always croak "Don't know how to handle magic of type \e\e%o", even
+on read-only values, or SVs which already have the unknown magic type.
+.RE
+.IP \(bu 4
+The experimental \f(CW\*(C`fetch_cop_label\*(C'\fR function has been renamed to
+\&\f(CW\*(C`cop_fetch_label\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`cop_store_label\*(C'\fR function has been added to the API, but is
+experimental.
+.IP \(bu 4
+\&\fIembedvar.h\fR has been simplified, and one level of macro indirection for
+PL_* variables has been removed for the default (non-multiplicity)
+configuration.  PERLVAR*() macros now directly expand their arguments to
+tokens such as \f(CW\*(C`PL_defgv\*(C'\fR, instead of expanding to \f(CW\*(C`PL_Idefgv\*(C'\fR, with
+\&\fIembedvar.h\fR defining a macro to map \f(CW\*(C`PL_Idefgv\*(C'\fR to \f(CW\*(C`PL_defgv\*(C'\fR.  XS code
+which has unwarranted chumminess with the implementation may need updating.
+.IP \(bu 4
+An API has been added to explicitly choose whether to export XSUB
+symbols.  More detail can be found in the comments for commit e64345f8.
+.IP \(bu 4
+The \f(CW\*(C`is_gv_magical_sv\*(C'\fR function has been eliminated and merged with
+\&\f(CW\*(C`gv_fetchpvn_flags\*(C'\fR.  It used to be called to determine whether a GV
+should be autovivified in rvalue context.  Now it has been replaced with a
+new \f(CW\*(C`GV_ADDMG\*(C'\fR flag (not part of the API).
+.IP \(bu 4
+The returned code point from the function \f(CWutf8n_to_uvuni()\fR
+when the input is malformed UTF\-8, malformations are allowed, and
+\&\f(CW\*(C`utf8\*(C'\fR warnings are off is now the Unicode REPLACEMENT CHARACTER
+whenever the malformation is such that no well-defined code point can be
+computed.  Previously the returned value was essentially garbage.  The
+only malformations that have well-defined values are a zero-length
+string (0 is the return), and overlong UTF\-8 sequences.
+.IP \(bu 4
+Padlists are now marked \f(CW\*(C`AvREAL\*(C'\fR; i.e., reference-counted.  They have
+always been reference-counted, but were not marked real, because \fIpad.c\fR
+did its own clean-up, instead of using the usual clean-up code in \fIsv.c\fR.
+That caused problems in thread cloning, so now the \f(CW\*(C`AvREAL\*(C'\fR flag is on,
+but is turned off in \fIpad.c\fR right before the padlist is freed (after
+\&\fIpad.c\fR has done its custom freeing of the pads).
+.IP \(bu 4
+All C files that make up the Perl core have been converted to UTF\-8.
+.IP \(bu 4
+These new functions have been added as part of the work on Unicode symbols:
+.Sp
+.Vb 10
+\&    HvNAMELEN
+\&    HvNAMEUTF8
+\&    HvENAMELEN
+\&    HvENAMEUTF8
+\&    gv_init_pv
+\&    gv_init_pvn
+\&    gv_init_pvsv
+\&    gv_fetchmeth_pv
+\&    gv_fetchmeth_pvn
+\&    gv_fetchmeth_sv
+\&    gv_fetchmeth_pv_autoload
+\&    gv_fetchmeth_pvn_autoload
+\&    gv_fetchmeth_sv_autoload
+\&    gv_fetchmethod_pv_flags
+\&    gv_fetchmethod_pvn_flags
+\&    gv_fetchmethod_sv_flags
+\&    gv_autoload_pv
+\&    gv_autoload_pvn
+\&    gv_autoload_sv
+\&    newGVgen_flags
+\&    sv_derived_from_pv
+\&    sv_derived_from_pvn
+\&    sv_derived_from_sv
+\&    sv_does_pv
+\&    sv_does_pvn
+\&    sv_does_sv
+\&    whichsig_pv
+\&    whichsig_pvn
+\&    whichsig_sv
+\&    newCONSTSUB_flags
+.Ve
+.Sp
+The gv_fetchmethod_*_flags functions, like gv_fetchmethod_flags, are
+experimental and may change in a future release.
+.IP \(bu 4
+The following functions were added.  These are \fInot\fR part of the API:
+.Sp
+.Vb 9
+\&    GvNAMEUTF8
+\&    GvENAMELEN
+\&    GvENAME_HEK
+\&    CopSTASH_flags
+\&    CopSTASH_flags_set
+\&    PmopSTASH_flags
+\&    PmopSTASH_flags_set
+\&    sv_sethek
+\&    HEKfARG
+.Ve
+.Sp
+There is also a \f(CW\*(C`HEKf\*(C'\fR macro corresponding to \f(CW\*(C`SVf\*(C'\fR, for
+interpolating HEKs in formatted strings.
+.IP \(bu 4
+\&\f(CW\*(C`sv_catpvn_flags\*(C'\fR takes a couple of new internal-only flags,
+\&\f(CW\*(C`SV_CATBYTES\*(C'\fR and \f(CW\*(C`SV_CATUTF8\*(C'\fR, which tell it whether the char array to
+be concatenated is UTF8.  This allows for more efficient concatenation than
+creating temporary SVs to pass to \f(CW\*(C`sv_catsv\*(C'\fR.
+.IP \(bu 4
+For XS AUTOLOAD subs, \f(CW$AUTOLOAD\fR is set once more, as it was in 5.6.0.  This
+is in addition to setting \f(CWSvPVX(cv)\fR, for compatibility with 5.8 to 5.14.
+See "Autoloading with XSUBs" in perlguts.
+.IP \(bu 4
+Perl now checks whether the array (the linearized isa) returned by a MRO
+plugin begins with the name of the class itself, for which the array was
+created, instead of assuming that it does.  This prevents the first element
+from being skipped during method lookup.  It also means that
+\&\f(CW\*(C`mro::get_linear_isa\*(C'\fR may return an array with one more element than the
+MRO plugin provided [perl #94306].
+.IP \(bu 4
+\&\f(CW\*(C`PL_curstash\*(C'\fR is now reference-counted.
+.IP \(bu 4
+There are now feature bundle hints in \f(CW\*(C`PL_hints\*(C'\fR (\f(CW$^H\fR) that version
+declarations use, to avoid having to load \fIfeature.pm\fR.  One setting of
+the hint bits indicates a "custom" feature bundle, which means that the
+entries in \f(CW\*(C`%^H\*(C'\fR still apply.  \fIfeature.pm\fR uses that.
+.Sp
+The \f(CW\*(C`HINT_FEATURE_MASK\*(C'\fR macro is defined in \fIperl.h\fR along with other
+hints.  Other macros for setting and testing features and bundles are in
+the new \fIfeature.h\fR.  \f(CW\*(C`FEATURE_IS_ENABLED\*(C'\fR (which has moved to
+\&\fIfeature.h\fR) is no longer used throughout the codebase, but more specific
+macros, e.g., \f(CW\*(C`FEATURE_SAY_IS_ENABLED\*(C'\fR, that are defined in \fIfeature.h\fR.
+.IP \(bu 4
+\&\fIlib/feature.pm\fR is now a generated file, created by the new
+\&\fIregen/feature.pl\fR script, which also generates \fIfeature.h\fR.
+.IP \(bu 4
+Tied arrays are now always \f(CW\*(C`AvREAL\*(C'\fR.  If \f(CW@_\fR or \f(CW\*(C`DB::args\*(C'\fR is tied, it
+is reified first, to make sure this is always the case.
+.IP \(bu 4
+Two new functions \f(CWutf8_to_uvchr_buf()\fR and \f(CWutf8_to_uvuni_buf()\fR have
+been added.  These are the same as \f(CW\*(C`utf8_to_uvchr\*(C'\fR and
+\&\f(CW\*(C`utf8_to_uvuni\*(C'\fR (which are now deprecated), but take an extra parameter
+that is used to guard against reading beyond the end of the input
+string.
+See "utf8_to_uvchr_buf" in perlapi and "utf8_to_uvuni_buf" in perlapi.
+.IP \(bu 4
+The regular expression engine now does TRIE case insensitive matches
+under Unicode. This may change the output of \f(CW\*(C`use re \*(Aqdebug\*(Aq;\*(C'\fR,
+and will speed up various things.
+.IP \(bu 4
+There is a new \f(CWwrap_op_checker()\fR function, which provides a thread-safe
+alternative to writing to \f(CW\*(C`PL_check\*(C'\fR directly.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS "Array and hash"
+.IX Subsection "Array and hash"
+.IP \(bu 4
+A bug has been fixed that would cause a "Use of freed value in iteration"
+error if the next two hash elements that would be iterated over are
+deleted [perl #85026]. (5.14.1)
+.IP \(bu 4
+Deleting the current hash iterator (the hash element that would be returned
+by the next call to \f(CW\*(C`each\*(C'\fR) in void context used not to free it
+[perl #85026].
+.IP \(bu 4
+Deletion of methods via \f(CW\*(C`delete $Class::{method}\*(C'\fR syntax used to update
+method caches if called in void context, but not scalar or list context.
+.IP \(bu 4
+When hash elements are deleted in void context, the internal hash entry is
+now freed before the value is freed, to prevent destructors called by that
+latter freeing from seeing the hash in an inconsistent state.  It was
+possible to cause double-frees if the destructor freed the hash itself
+[perl #100340].
+.IP \(bu 4
+A \f(CW\*(C`keys\*(C'\fR optimization in Perl 5.12.0 to make it faster on empty hashes
+caused \f(CW\*(C`each\*(C'\fR not to reset the iterator if called after the last element
+was deleted.
+.IP \(bu 4
+Freeing deeply nested hashes no longer crashes [perl #44225].
+.IP \(bu 4
+It is possible from XS code to create hashes with elements that have no
+values.  The hash element and slice operators used to crash
+when handling these in lvalue context.  They now
+produce a "Modification of non-creatable hash value attempted" error
+message.
+.IP \(bu 4
+If list assignment to a hash or array triggered destructors that freed the
+hash or array itself, a crash would ensue.  This is no longer the case
+[perl #107440].
+.IP \(bu 4
+It used to be possible to free the typeglob of a localized array or hash
+(e.g., \f(CW\*(C`local @{"x"}; delete $::{x}\*(C'\fR), resulting in a crash on scope exit.
+.IP \(bu 4
+Some core bugs affecting Hash::Util have been fixed: locking a hash
+element that is a glob copy no longer causes the next assignment to it to
+corrupt the glob (5.14.2), and unlocking a hash element that holds a
+copy-on-write scalar no longer causes modifications to that scalar to
+modify other scalars that were sharing the same string buffer.
+.SS "C API fixes"
+.IX Subsection "C API fixes"
+.IP \(bu 4
+The \f(CW\*(C`newHVhv\*(C'\fR XS function now works on tied hashes, instead of crashing or
+returning an empty hash.
+.IP \(bu 4
+The \f(CW\*(C`SvIsCOW\*(C'\fR C macro now returns false for read-only copies of typeglobs,
+such as those created by:
+.Sp
+.Vb 2
+\&  $hash{elem} = *foo;
+\&  Hash::Util::lock_value %hash, \*(Aqelem\*(Aq;
+.Ve
+.Sp
+It used to return true.
+.IP \(bu 4
+The \f(CW\*(C`SvPVutf8\*(C'\fR C function no longer tries to modify its argument,
+resulting in errors [perl #108994].
+.IP \(bu 4
+\&\f(CW\*(C`SvPVutf8\*(C'\fR now works properly with magical variables.
+.IP \(bu 4
+\&\f(CW\*(C`SvPVbyte\*(C'\fR now works properly non-PVs.
+.IP \(bu 4
+When presented with malformed UTF\-8 input, the XS-callable functions
+\&\f(CWis_utf8_string()\fR, \f(CWis_utf8_string_loc()\fR, and
+\&\f(CWis_utf8_string_loclen()\fR could read beyond the end of the input
+string by up to 12 bytes.  This no longer happens.  [perl #32080].
+However, currently, \f(CWis_utf8_char()\fR still has this defect, see
+"\fBis_utf8_char()\fR" above.
+.IP \(bu 4
+The C\-level \f(CW\*(C`pregcomp\*(C'\fR function could become confused about whether the
+pattern was in UTF8 if the pattern was an overloaded, tied, or otherwise
+magical scalar [perl #101940].
+.SS "Compile-time hints"
+.IX Subsection "Compile-time hints"
+.IP \(bu 4
+Tying \f(CW\*(C`%^H\*(C'\fR no longer causes perl to crash or ignore the contents of
+\&\f(CW\*(C`%^H\*(C'\fR when entering a compilation scope [perl #106282].
+.IP \(bu 4
+\&\f(CW\*(C`eval $string\*(C'\fR and \f(CW\*(C`require\*(C'\fR used not to
+localize \f(CW\*(C`%^H\*(C'\fR during compilation if it
+was empty at the time the \f(CW\*(C`eval\*(C'\fR call itself was compiled.  This could
+lead to scary side effects, like \f(CW\*(C`use re "/m"\*(C'\fR enabling other flags that
+the surrounding code was trying to enable for its caller [perl #68750].
+.IP \(bu 4
+\&\f(CW\*(C`eval $string\*(C'\fR and \f(CW\*(C`require\*(C'\fR no longer localize hints (\f(CW$^H\fR and \f(CW\*(C`%^H\*(C'\fR)
+at run time, but only during compilation of the \f(CW$string\fR or required file.
+This makes \f(CW\*(C`BEGIN { $^H{foo}=7 }\*(C'\fR equivalent to
+\&\f(CW\*(C`BEGIN { eval \*(Aq$^H{foo}=7\*(Aq }\*(C'\fR [perl #70151].
+.IP \(bu 4
+Creating a BEGIN block from XS code (via \f(CW\*(C`newXS\*(C'\fR or \f(CW\*(C`newATTRSUB\*(C'\fR) would,
+on completion, make the hints of the current compiling code the current
+hints.  This could cause warnings to occur in a non-warning scope.
+.SS "Copy-on-write scalars"
+.IX Subsection "Copy-on-write scalars"
+Copy-on-write or shared hash key scalars
+were introduced in 5.8.0, but most Perl code
+did not encounter them (they were used mostly internally).  Perl
+5.10.0 extended them, such that assigning \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR or a
+hash key to a scalar would make it copy-on-write.  Several parts
+of Perl were not updated to account for them, but have now been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`utf8::decode\*(C'\fR had a nasty bug that would modify copy-on-write scalars'
+string buffers in place (i.e., skipping the copy).  This could result in
+hashes having two elements with the same key [perl #91834]. (5.14.2)
+.IP \(bu 4
+Lvalue subroutines were not allowing COW scalars to be returned.  This was
+fixed for lvalue scalar context in Perl 5.12.3 and 5.14.0, but list context
+was not fixed until this release.
+.IP \(bu 4
+Elements of restricted hashes (see the fields pragma) containing
+copy-on-write values couldn't be deleted, nor could such hashes be cleared
+(\f(CW\*(C`%hash = ()\*(C'\fR). (5.14.2)
+.IP \(bu 4
+Localizing a tied variable used to make it read-only if it contained a
+copy-on-write string. (5.14.2)
+.IP \(bu 4
+Assigning a copy-on-write string to a stash
+element no longer causes a double free.  Regardless of this change, the
+results of such assignments are still undefined.
+.IP \(bu 4
+Assigning a copy-on-write string to a tied variable no longer stops that
+variable from being tied if it happens to be a PVMG or PVLV internally.
+.IP \(bu 4
+Doing a substitution on a tied variable returning a copy-on-write
+scalar used to cause an assertion failure or an "Attempt to free
+nonexistent shared string" warning.
+.IP \(bu 4
+This one is a regression from 5.12: In 5.14.0, the bitwise assignment
+operators \f(CW\*(C`|=\*(C'\fR, \f(CW\*(C`^=\*(C'\fR and \f(CW\*(C`&=\*(C'\fR started leaving the left-hand side
+undefined if it happened to be a copy-on-write string [perl #108480].
+.IP \(bu 4
+Storable, Devel::Peek and PerlIO::scalar had similar problems.
+See "Updated Modules and Pragmata", above.
+.SS "The debugger"
+.IX Subsection "The debugger"
+.IP \(bu 4
+\&\fIdumpvar.pl\fR, and therefore the \f(CW\*(C`x\*(C'\fR command in the debugger, have been
+fixed to handle objects blessed into classes whose names contain "=".  The
+contents of such objects used not to be dumped [perl #101814].
+.IP \(bu 4
+The "R" command for restarting a debugger session has been fixed to work on
+Windows, or any other system lacking a \f(CW\*(C`POSIX::_SC_OPEN_MAX\*(C'\fR constant
+[perl #87740].
+.IP \(bu 4
+The \f(CW\*(C`#line 42 foo\*(C'\fR directive used not to update the arrays of lines used
+by the debugger if it occurred in a string eval.  This was partially fixed
+in 5.14, but it worked only for a single \f(CW\*(C`#line 42 foo\*(C'\fR in each eval.  Now
+it works for multiple.
+.IP \(bu 4
+When subroutine calls are intercepted by the debugger, the name of the
+subroutine or a reference to it is stored in \f(CW$DB::sub\fR, for the debugger
+to access.  Sometimes (such as \f(CW\*(C`$foo = *bar; undef *bar; &$foo\*(C'\fR)
+\&\f(CW$DB::sub\fR would be set to a name that could not be used to find the
+subroutine, and so the debugger's attempt to call it would fail.  Now the
+check to see whether a reference is needed is more robust, so those
+problems should not happen anymore [rt.cpan.org #69862].
+.IP \(bu 4
+Every subroutine has a filename associated with it that the debugger uses.
+The one associated with constant subroutines used to be misallocated when
+cloned under threads.  Consequently, debugging threaded applications could
+result in memory corruption [perl #96126].
+.SS "Dereferencing operators"
+.IX Subsection "Dereferencing operators"
+.IP \(bu 4
+\&\f(CWdefined(${"..."})\fR, \f(CWdefined(*{"..."})\fR, etc., used to
+return true for most, but not all built-in variables, if
+they had not been used yet.  This bug affected \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR and
+\&\f(CW\*(C`${^UTF8CACHE}\*(C'\fR, among others.  It also used to return false if the
+package name was given as well (\f(CW\*(C`${"::!"}\*(C'\fR) [perl #97978, #97492].
+.IP \(bu 4
+Perl 5.10.0 introduced a similar bug: \f(CWdefined(*{"foo"})\fR where "foo"
+represents the name of a built-in global variable used to return false if
+the variable had never been used before, but only on the \fIfirst\fR call.
+This, too, has been fixed.
+.IP \(bu 4
+Since 5.6.0, \f(CW\*(C`*{ ... }\*(C'\fR has been inconsistent in how it treats undefined
+values.  It would die in strict mode or lvalue context for most undefined
+values, but would be treated as the empty string (with a warning) for the
+specific scalar return by \f(CWundef()\fR (\f(CW&PL_sv_undef\fR internally).  This
+has been corrected.  \f(CWundef()\fR is now treated like other undefined
+scalars, as in Perl 5.005.
+.SS "Filehandle, last-accessed"
+.IX Subsection "Filehandle, last-accessed"
+Perl has an internal variable that stores the last filehandle to be
+accessed.  It is used by \f(CW$.\fR and by \f(CW\*(C`tell\*(C'\fR and \f(CW\*(C`eof\*(C'\fR without
+arguments.
+.IP \(bu 4
+It used to be possible to set this internal variable to a glob copy and
+then modify that glob copy to be something other than a glob, and still
+have the last-accessed filehandle associated with the variable after
+assigning a glob to it again:
+.Sp
+.Vb 4
+\&    my $foo = *STDOUT;  # $foo is a glob copy
+\&    <$foo>;             # $foo is now the last\-accessed handle
+\&    $foo = 3;           # no longer a glob
+\&    $foo = *STDERR;     # still the last\-accessed handle
+.Ve
+.Sp
+Now the \f(CW\*(C`$foo = 3\*(C'\fR assignment unsets that internal variable, so there
+is no last-accessed filehandle, just as if \f(CW\*(C`<$foo>\*(C'\fR had never
+happened.
+.Sp
+This also prevents some unrelated handle from becoming the last-accessed
+handle if \f(CW$foo\fR falls out of scope and the same internal SV gets used for
+another handle [perl #97988].
+.IP \(bu 4
+A regression in 5.14 caused these statements not to set that internal
+variable:
+.Sp
+.Vb 8
+\&    my $fh = *STDOUT;
+\&    tell $fh;
+\&    eof  $fh;
+\&    seek $fh, 0,0;
+\&    tell     *$fh;
+\&    eof      *$fh;
+\&    seek     *$fh, 0,0;
+\&    readline *$fh;
+.Ve
+.Sp
+This is now fixed, but \f(CW\*(C`tell *{ *$fh }\*(C'\fR still has the problem, and it
+is not clear how to fix it [perl #106536].
+.ie n .SS "Filetests and ""stat"""
+.el .SS "Filetests and \f(CWstat\fP"
+.IX Subsection "Filetests and stat"
+The term "filetests" refers to the operators that consist of a hyphen
+followed by a single letter: \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, etc.  The term "stacked"
+when applied to filetests means followed by another filetest operator
+sharing the same operand, as in \f(CW\*(C`\-r \-x \-w $fooo\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`stat\*(C'\fR produces more consistent warnings.  It no longer warns for "_"
+[perl #71002] and no longer skips the warning at times for other unopened
+handles.  It no longer warns about an unopened handle when the operating
+system's \f(CW\*(C`fstat\*(C'\fR function fails.
+.IP \(bu 4
+\&\f(CW\*(C`stat\*(C'\fR would sometimes return negative numbers for large inode numbers,
+because it was using the wrong internal C type. [perl #84590]
+.IP \(bu 4
+\&\f(CW\*(C`lstat\*(C'\fR is documented to fall back to \f(CW\*(C`stat\*(C'\fR (with a warning) when given
+a filehandle.  When passed an IO reference, it was actually doing the
+equivalent of \f(CW\*(C`stat\ _\*(C'\fR and ignoring the handle.
+.IP \(bu 4
+\&\f(CW\*(C`\-T _\*(C'\fR with no preceding \f(CW\*(C`stat\*(C'\fR used to produce a
+confusing "uninitialized" warning, even though there
+is no visible uninitialized value to speak of.
+.IP \(bu 4
+\&\f(CW\*(C`\-T\*(C'\fR, \f(CW\*(C`\-B\*(C'\fR, \f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-t\*(C'\fR now work
+when stacked with other filetest operators
+[perl #77388].
+.IP \(bu 4
+In 5.14.0, filetest ops (\f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, etc.) started calling FETCH on a
+tied argument belonging to the previous argument to a list operator, if
+called with a bareword argument or no argument at all.  This has been
+fixed, so \f(CW\*(C`push @foo, $tied, \-r\*(C'\fR no longer calls FETCH on \f(CW$tied\fR.
+.IP \(bu 4
+In Perl 5.6, \f(CW\*(C`\-l\*(C'\fR followed by anything other than a bareword would treat
+its argument as a file name.  That was changed in 5.8 for glob references
+(\f(CW\*(C`\e*foo\*(C'\fR), but not for globs themselves (\f(CW*foo\fR).  \f(CW\*(C`\-l\*(C'\fR started
+returning \f(CW\*(C`undef\*(C'\fR for glob references without setting the last
+stat buffer that the "_" handle uses, but only if warnings
+were turned on.  With warnings off, it was the same as 5.6.
+In other words, it was simply buggy and inconsistent.  Now the 5.6
+behavior has been restored.
+.IP \(bu 4
+\&\f(CW\*(C`\-l\*(C'\fR followed by a bareword no longer "eats" the previous argument to
+the list operator in whose argument list it resides.  Hence,
+\&\f(CW\*(C`print "bar", \-l foo\*(C'\fR now actually prints "bar", because \f(CW\*(C`\-l\*(C'\fR
+on longer eats it.
+.IP \(bu 4
+Perl keeps several internal variables to keep track of the last stat
+buffer, from which file(handle) it originated, what type it was, and
+whether the last stat succeeded.
+.Sp
+There were various cases where these could get out of synch, resulting in
+inconsistent or erratic behavior in edge cases (every mention of \f(CW\*(C`\-T\*(C'\fR
+applies to \f(CW\*(C`\-B\*(C'\fR as well):
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`\-T \fR\f(CIHANDLE\fR\f(CW\*(C'\fR, even though it does a \f(CW\*(C`stat\*(C'\fR, was not resetting the last
+stat type, so an \f(CW\*(C`lstat _\*(C'\fR following it would merrily return the wrong
+results.  Also, it was not setting the success status.
+.IP \(bu 4
+Freeing the handle last used by \f(CW\*(C`stat\*(C'\fR or a filetest could result in
+\&\f(CW\*(C`\-T\ _\*(C'\fR using an unrelated handle.
+.IP \(bu 4
+\&\f(CW\*(C`stat\*(C'\fR with an IO reference would not reset the stat type or record the
+filehandle for \f(CW\*(C`\-T\ _\*(C'\fR to use.
+.IP \(bu 4
+Fatal warnings could cause the stat buffer not to be reset
+for a filetest operator on an unopened filehandle or \f(CW\*(C`\-l\*(C'\fR on any handle.
+Fatal warnings also stopped \f(CW\*(C`\-T\*(C'\fR from setting \f(CW$!\fR.
+.IP \(bu 4
+When the last stat was on an unreadable file, \f(CW\*(C`\-T _\*(C'\fR is supposed to
+return \f(CW\*(C`undef\*(C'\fR, leaving the last stat buffer unchanged.  But it was
+setting the stat type, causing \f(CW\*(C`lstat _\*(C'\fR to stop working.
+.IP \(bu 4
+\&\f(CW\*(C`\-T \fR\f(CIFILENAME\fR\f(CW\*(C'\fR was not resetting the internal stat buffers for
+unreadable files.
+.RE
+.RS 4
+.Sp
+These have all been fixed.
+.RE
+.SS Formats
+.IX Subsection "Formats"
+.IP \(bu 4
+Several edge cases have been fixed with formats and \f(CW\*(C`formline\*(C'\fR;
+in particular, where the format itself is potentially variable (such as
+with ties and overloading), and where the format and data differ in their
+encoding.  In both these cases, it used to possible for the output to be
+corrupted [perl #91032].
+.IP \(bu 4
+\&\f(CW\*(C`formline\*(C'\fR no longer converts its argument into a string in-place.  So
+passing a reference to \f(CW\*(C`formline\*(C'\fR no longer destroys the reference
+[perl #79532].
+.IP \(bu 4
+Assignment to \f(CW$^A\fR (the format output accumulator) now recalculates
+the number of lines output.
+.ie n .SS """given"" and ""when"""
+.el .SS "\f(CWgiven\fP and \f(CWwhen\fP"
+.IX Subsection "given and when"
+.IP \(bu 4
+\&\f(CW\*(C`given\*(C'\fR was not scoping its implicit \f(CW$_\fR properly, resulting in memory
+leaks or "Variable is not available" warnings [perl #94682].
+.IP \(bu 4
+\&\f(CW\*(C`given\*(C'\fR was not calling set-magic on the implicit lexical \f(CW$_\fR that it
+uses.  This meant, for example, that \f(CW\*(C`pos\*(C'\fR would be remembered from one
+execution of the same \f(CW\*(C`given\*(C'\fR block to the next, even if the input were a
+different variable [perl #84526].
+.IP \(bu 4
+\&\f(CW\*(C`when\*(C'\fR blocks are now capable of returning variables declared inside the
+enclosing \f(CW\*(C`given\*(C'\fR block [perl #93548].
+.ie n .SS "The ""glob"" operator"
+.el .SS "The \f(CWglob\fP operator"
+.IX Subsection "The glob operator"
+.IP \(bu 4
+On OSes other than VMS, Perl's \f(CW\*(C`glob\*(C'\fR operator (and the \f(CW\*(C`<...>\*(C'\fR form)
+use File::Glob underneath.  File::Glob splits the pattern into words,
+before feeding each word to its \f(CW\*(C`bsd_glob\*(C'\fR function.
+.Sp
+There were several inconsistencies in the way the split was done.  Now
+quotation marks (' and ") are always treated as shell-style word delimiters
+(that allow whitespace as part of a word) and backslashes are always
+preserved, unless they exist to escape quotation marks.  Before, those
+would only sometimes be the case, depending on whether the pattern
+contained whitespace.  Also, escaped whitespace at the end of the pattern
+is no longer stripped [perl #40470].
+.IP \(bu 4
+\&\f(CW\*(C`CORE::glob\*(C'\fR now works as a way to call the default globbing function.  It
+used to respect overrides, despite the \f(CW\*(C`CORE::\*(C'\fR prefix.
+.IP \(bu 4
+Under miniperl (used to configure modules when perl itself is built),
+\&\f(CW\*(C`glob\*(C'\fR now clears \f(CW%ENV\fR before calling csh, since the latter croaks on some
+systems if it does not like the contents of the LS_COLORS environment
+variable [perl #98662].
+.SS "Lvalue subroutines"
+.IX Subsection "Lvalue subroutines"
+.IP \(bu 4
+Explicit return now returns the actual argument passed to return, instead
+of copying it [perl #72724, #72706].
+.IP \(bu 4
+Lvalue subroutines used to enforce lvalue syntax (i.e., whatever can go on
+the left-hand side of \f(CW\*(C`=\*(C'\fR) for the last statement and the arguments to
+return.  Since lvalue subroutines are not always called in lvalue context,
+this restriction has been lifted.
+.IP \(bu 4
+Lvalue subroutines are less restrictive about what values can be returned.
+It used to croak on values returned by \f(CW\*(C`shift\*(C'\fR and \f(CW\*(C`delete\*(C'\fR and from
+other subroutines, but no longer does so [perl #71172].
+.IP \(bu 4
+Empty lvalue subroutines (\f(CW\*(C`sub :lvalue {}\*(C'\fR) used to return \f(CW@_\fR in list
+context.  All subroutines used to do this, but regular subs were fixed in
+Perl 5.8.2.  Now lvalue subroutines have been likewise fixed.
+.IP \(bu 4
+Autovivification now works on values returned from lvalue subroutines
+[perl #7946], as does returning \f(CW\*(C`keys\*(C'\fR in lvalue context.
+.IP \(bu 4
+Lvalue subroutines used to copy their return values in rvalue context.  Not
+only was this a waste of CPU cycles, but it also caused bugs.  A \f(CW\*(C`($)\*(C'\fR
+prototype would cause an lvalue sub to copy its return value [perl #51408],
+and \f(CW\*(C`while(lvalue_sub() =~ m/.../g) { ... }\*(C'\fR would loop endlessly
+[perl #78680].
+.IP \(bu 4
+When called in potential lvalue context
+(e.g., subroutine arguments or a list
+passed to \f(CW\*(C`for\*(C'\fR), lvalue subroutines used to copy
+any read-only value that was returned.  E.g., \f(CW\*(C` sub :lvalue { $] } \*(C'\fR
+would not return \f(CW$]\fR, but a copy of it.
+.IP \(bu 4
+When called in potential lvalue context, an lvalue subroutine returning
+arrays or hashes used to bind the arrays or hashes to scalar variables,
+resulting in bugs.  This was fixed in 5.14.0 if an array were the first
+thing returned from the subroutine (but not for \f(CW\*(C`$scalar, @array\*(C'\fR or
+hashes being returned).  Now a more general fix has been applied
+[perl #23790].
+.IP \(bu 4
+Method calls whose arguments were all surrounded with \f(CWmy()\fR or \f(CWour()\fR
+(as in \f(CW\*(C`$object\->method(my($a,$b))\*(C'\fR) used to force lvalue context on
+the subroutine.  This would prevent lvalue methods from returning certain
+values.
+.IP \(bu 4
+Lvalue sub calls that are not determined to be such at compile time
+(\f(CW&$name\fR or &{"name"}) are no longer exempt from strict refs if they
+occur in the last statement of an lvalue subroutine [perl #102486].
+.IP \(bu 4
+Sub calls whose subs are not visible at compile time, if
+they occurred in the last statement of an lvalue subroutine,
+would reject non-lvalue subroutines and die with "Can't modify non-lvalue
+subroutine call" [perl #102486].
+.Sp
+Non-lvalue sub calls whose subs \fIare\fR visible at compile time exhibited
+the opposite bug.  If the call occurred in the last statement of an lvalue
+subroutine, there would be no error when the lvalue sub was called in
+lvalue context.  Perl would blindly assign to the temporary value returned
+by the non-lvalue subroutine.
+.IP \(bu 4
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR routines used to take precedence over the actual sub being
+called (i.e., when autoloading wasn't needed), for sub calls in lvalue or
+potential lvalue context, if the subroutine was not visible at compile
+time.
+.IP \(bu 4
+Applying the \f(CW\*(C`:lvalue\*(C'\fR attribute to an XSUB or to an aliased subroutine
+stub with \f(CW\*(C`sub foo :lvalue;\*(C'\fR syntax stopped working in Perl 5.12.
+This has been fixed.
+.IP \(bu 4
+Applying the :lvalue attribute to subroutine that is already defined does
+not work properly, as the attribute changes the way the sub is compiled.
+Hence, Perl 5.12 began warning when an attempt is made to apply the
+attribute to an already defined sub.  In such cases, the attribute is
+discarded.
+.Sp
+But the change in 5.12 missed the case where custom attributes are also
+present: that case still silently and ineffectively applied the attribute.
+That omission has now been corrected.  \f(CW\*(C`sub foo :lvalue :Whatever\*(C'\fR (when
+\&\f(CW\*(C`foo\*(C'\fR is already defined) now warns about the :lvalue attribute, and does
+not apply it.
+.IP \(bu 4
+A bug affecting lvalue context propagation through nested lvalue subroutine
+calls has been fixed.  Previously, returning a value in nested rvalue
+context would be treated as lvalue context by the inner subroutine call,
+resulting in some values (such as read-only values) being rejected.
+.SS Overloading
+.IX Subsection "Overloading"
+.IP \(bu 4
+Arithmetic assignment (\f(CW\*(C`$left += $right\*(C'\fR) involving overloaded objects
+that rely on the 'nomethod' override no longer segfault when the left
+operand is not overloaded.
+.IP \(bu 4
+Errors that occur when methods cannot be found during overloading now
+mention the correct package name, as they did in 5.8.x, instead of
+erroneously mentioning the "overload" package, as they have since 5.10.0.
+.IP \(bu 4
+Undefining \f(CW%overload::\fR no longer causes a crash.
+.SS "Prototypes of built-in keywords"
+.IX Subsection "Prototypes of built-in keywords"
+.IP \(bu 4
+The \f(CW\*(C`prototype\*(C'\fR function no longer dies for the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR, \f(CW\*(C`_\|_LINE_\|_\*(C'\fR
+and \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR directives.  It now returns an empty-string prototype
+for them, because they are syntactically indistinguishable from nullary
+functions like \f(CW\*(C`time\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`prototype\*(C'\fR now returns \f(CW\*(C`undef\*(C'\fR for all overridable infix operators,
+such as \f(CW\*(C`eq\*(C'\fR, which are not callable in any way resembling functions.
+It used to return incorrect prototypes for some and die for others
+[perl #94984].
+.IP \(bu 4
+The prototypes of several built-in functions\-\-\f(CW\*(C`getprotobynumber\*(C'\fR, \f(CW\*(C`lock\*(C'\fR,
+\&\f(CW\*(C`not\*(C'\fR and \f(CW\*(C`select\*(C'\fR\-\-have been corrected, or at least are now closer to
+reality than before.
+.SS "Regular expressions"
+.IX Subsection "Regular expressions"
+.IP \(bu 4
+\&\f(CW\*(C`/[[:ascii:]]/\*(C'\fR and \f(CW\*(C`/[[:blank:]]/\*(C'\fR now use locale rules under
+\&\f(CW\*(C`use locale\*(C'\fR when the platform supports that.  Previously, they used
+the platform's native character set.
+.IP \(bu 4
+\&\f(CW\*(C`m/[[:ascii:]]/i\*(C'\fR and \f(CW\*(C`/\ep{ASCII}/i\*(C'\fR now match identically (when not
+under a differing locale).  This fixes a regression introduced in 5.14
+in which the first expression could match characters outside of ASCII,
+such as the KELVIN SIGN.
+.IP \(bu 4
+\&\f(CW\*(C`/.*/g\*(C'\fR would sometimes refuse to match at the end of a string that ends
+with "\en".  This has been fixed [perl #109206].
+.IP \(bu 4
+Starting with 5.12.0, Perl used to get its internal bookkeeping muddled up
+after assigning \f(CW\*(C`${ qr// }\*(C'\fR to a hash element and locking it with
+Hash::Util.  This could result in double frees, crashes, or erratic
+behavior.
+.IP \(bu 4
+The new (in 5.14.0) regular expression modifier \f(CW\*(C`/a\*(C'\fR when repeated like
+\&\f(CW\*(C`/aa\*(C'\fR forbids the characters outside the ASCII range that match
+characters inside that range from matching under \f(CW\*(C`/i\*(C'\fR.  This did not
+work under some circumstances, all involving alternation, such as:
+.Sp
+.Vb 1
+\& "\eN{KELVIN SIGN}" =~ /k|foo/iaa;
+.Ve
+.Sp
+succeeded inappropriately.  This is now fixed.
+.IP \(bu 4
+5.14.0 introduced some memory leaks in regular expression character
+classes such as \f(CW\*(C`[\ew\es]\*(C'\fR, which have now been fixed. (5.14.1)
+.IP \(bu 4
+An edge case in regular expression matching could potentially loop.
+This happened only under \f(CW\*(C`/i\*(C'\fR in bracketed character classes that have
+characters with multi-character folds, and the target string to match
+against includes the first portion of the fold, followed by another
+character that has a multi-character fold that begins with the remaining
+portion of the fold, plus some more.
+.Sp
+.Vb 1
+\& "s\eN{U+DF}" =~ /[\ex{DF}foo]/i
+.Ve
+.Sp
+is one such case.  \f(CW\*(C`\exDF\*(C'\fR folds to \f(CW"ss"\fR. (5.14.1)
+.IP \(bu 4
+A few characters in regular expression pattern matches did not
+match correctly in some circumstances, all involving \f(CW\*(C`/i\*(C'\fR.  The
+affected characters are:
+COMBINING GREEK YPOGEGRAMMENI,
+GREEK CAPITAL LETTER IOTA,
+GREEK CAPITAL LETTER UPSILON,
+GREEK PROSGEGRAMMENI,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND OXIA,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND OXIA,
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
+LATIN SMALL LETTER LONG S,
+LATIN SMALL LIGATURE LONG S T,
+and
+LATIN SMALL LIGATURE ST.
+.IP \(bu 4
+A memory leak regression in regular expression compilation
+under threading has been fixed.
+.IP \(bu 4
+A regression introduced in 5.14.0 has
+been fixed.  This involved an inverted
+bracketed character class in a regular expression that consisted solely
+of a Unicode property.  That property wasn't getting inverted outside the
+Latin1 range.
+.IP \(bu 4
+Three problematic Unicode characters now work better in regex pattern matching under \f(CW\*(C`/i\*(C'\fR.
+.Sp
+In the past, three Unicode characters:
+LATIN SMALL LETTER SHARP S,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
+and
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
+along with the sequences that they fold to
+(including "ss" for LATIN SMALL LETTER SHARP S),
+did not properly match under \f(CW\*(C`/i\*(C'\fR.  5.14.0 fixed some of these cases,
+but introduced others, including a panic when one of the characters or
+sequences was used in the \f(CW\*(C`(?(DEFINE)\*(C'\fR regular expression predicate.
+The known bugs that were introduced in 5.14 have now been fixed; as well
+as some other edge cases that have never worked until now.  These all
+involve using the characters and sequences outside bracketed character
+classes under \f(CW\*(C`/i\*(C'\fR.  This closes [perl #98546].
+.Sp
+There remain known problems when using certain characters with
+multi-character folds inside bracketed character classes, including such
+constructs as \f(CW\*(C`qr/[\eN{LATIN SMALL LETTER SHARP}a\-z]/i\*(C'\fR.  These
+remaining bugs are addressed in [perl #89774].
+.IP \(bu 4
+RT #78266: The regex engine has been leaking memory when accessing
+named captures that weren't matched as part of a regex ever since 5.10
+when they were introduced; e.g., this would consume over a hundred MB of
+memory:
+.Sp
+.Vb 6
+\&    for (1..10_000_000) {
+\&        if ("foo" =~ /(foo|(?<capture>bar))?/) {
+\&            my $capture = $+{capture}
+\&        }
+\&    }
+\&    system "ps \-o rss $$"\*(Aq
+.Ve
+.IP \(bu 4
+In 5.14, \f(CW\*(C`/[[:lower:]]/i\*(C'\fR and \f(CW\*(C`/[[:upper:]]/i\*(C'\fR no longer matched the
+opposite case.  This has been fixed [perl #101970].
+.IP \(bu 4
+A regular expression match with an overloaded object on the right-hand side
+would sometimes stringify the object too many times.
+.IP \(bu 4
+A regression has been fixed that was introduced in 5.14, in \f(CW\*(C`/i\*(C'\fR
+regular expression matching, in which a match improperly fails if the
+pattern is in UTF\-8, the target string is not, and a Latin\-1 character
+precedes a character in the string that should match the pattern.
+[perl #101710]
+.IP \(bu 4
+In case-insensitive regular expression pattern matching, no longer on
+UTF\-8 encoded strings does the scan for the start of match look only at
+the first possible position.  This caused matches such as
+\&\f(CW\*(C`"f\ex{FB00}" =~ /ff/i\*(C'\fR to fail.
+.IP \(bu 4
+The regexp optimizer no longer crashes on debugging builds when merging
+fixed-string nodes with inconvenient contents.
+.IP \(bu 4
+A panic involving the combination of the regular expression modifiers
+\&\f(CW\*(C`/aa\*(C'\fR and the \f(CW\*(C`\eb\*(C'\fR escape sequence introduced in 5.14.0 has been
+fixed [perl #95964]. (5.14.2)
+.IP \(bu 4
+The combination of the regular expression modifiers \f(CW\*(C`/aa\*(C'\fR and the \f(CW\*(C`\eb\*(C'\fR
+and \f(CW\*(C`\eB\*(C'\fR escape sequences did not work properly on UTF\-8 encoded
+strings.  All non-ASCII characters under \f(CW\*(C`/aa\*(C'\fR should be treated as
+non-word characters, but what was happening was that Unicode rules were
+used to determine wordness/non\-wordness for non-ASCII characters.  This
+is now fixed [perl #95968].
+.IP \(bu 4
+\&\f(CW\*(C`(?foo: ...)\*(C'\fR no longer loses passed in character set.
+.IP \(bu 4
+The trie optimization used to have problems with alternations containing
+an empty \f(CW\*(C`(?:)\*(C'\fR, causing \f(CW\*(C`"x" =~ /\eA(?>(?:(?:)A|B|C?x))\ez/\*(C'\fR not to
+match, whereas it should [perl #111842].
+.IP \(bu 4
+Use of lexical (\f(CW\*(C`my\*(C'\fR) variables in code blocks embedded in regular
+expressions will no longer result in memory corruption or crashes.
+.Sp
+Nevertheless, these code blocks are still experimental, as there are still
+problems with the wrong variables being closed over (in loops for instance)
+and with abnormal exiting (e.g., \f(CW\*(C`die\*(C'\fR) causing memory corruption.
+.IP \(bu 4
+The \f(CW\*(C`\eh\*(C'\fR, \f(CW\*(C`\eH\*(C'\fR, \f(CW\*(C`\ev\*(C'\fR and \f(CW\*(C`\eV\*(C'\fR regular expression metacharacters used to
+cause a panic error message when trying to match at the end of the
+string [perl #96354].
+.IP \(bu 4
+The abbreviations for four C1 control characters \f(CW\*(C`MW\*(C'\fR \f(CW\*(C`PM\*(C'\fR, \f(CW\*(C`RI\*(C'\fR, and
+\&\f(CW\*(C`ST\*(C'\fR were previously unrecognized by \f(CW\*(C`\eN{}\*(C'\fR, \fBvianame()\fR, and
+\&\fBstring_vianame()\fR.
+.IP \(bu 4
+Mentioning a variable named "&" other than \f(CW$&\fR (i.e., \f(CW\*(C`@&\*(C'\fR or \f(CW\*(C`%&\*(C'\fR) no
+longer stops \f(CW$&\fR from working.  The same applies to variables named "'"
+and "`" [perl #24237].
+.IP \(bu 4
+Creating a \f(CW\*(C`UNIVERSAL::AUTOLOAD\*(C'\fR sub no longer stops \f(CW\*(C`%+\*(C'\fR, \f(CW\*(C`%\-\*(C'\fR and
+\&\f(CW\*(C`%!\*(C'\fR from working some of the time [perl #105024].
+.SS Smartmatching
+.IX Subsection "Smartmatching"
+.IP \(bu 4
+\&\f(CW\*(C`~~\*(C'\fR now correctly handles the precedence of Any~~Object, and is not tricked
+by an overloaded object on the left-hand side.
+.IP \(bu 4
+In Perl 5.14.0, \f(CW\*(C`$tainted ~~ @array\*(C'\fR stopped working properly.  Sometimes
+it would erroneously fail (when \f(CW$tainted\fR contained a string that occurs
+in the array \fIafter\fR the first element) or erroneously succeed (when
+\&\f(CW\*(C`undef\*(C'\fR occurred after the first element) [perl #93590].
+.ie n .SS "The ""sort"" operator"
+.el .SS "The \f(CWsort\fP operator"
+.IX Subsection "The sort operator"
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR was not treating \f(CW\*(C`sub {}\*(C'\fR and \f(CW\*(C`sub {()}\*(C'\fR as equivalent when
+such a sub was provided as the comparison routine.  It used to croak on
+\&\f(CW\*(C`sub {()}\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR now works once more with custom sort routines that are XSUBs.  It
+stopped working in 5.10.0.
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR with a constant for a custom sort routine, although it produces
+unsorted results, no longer crashes.  It started crashing in 5.10.0.
+.IP \(bu 4
+Warnings emitted by \f(CW\*(C`sort\*(C'\fR when a custom comparison routine returns a
+non-numeric value now contain "in sort" and show the line number of the
+\&\f(CW\*(C`sort\*(C'\fR operator, rather than the last line of the comparison routine.  The
+warnings also now occur only if warnings are enabled in the scope where
+\&\f(CW\*(C`sort\*(C'\fR occurs.  Previously the warnings would occur if enabled in the
+comparison routine's scope.
+.IP \(bu 4
+\&\f(CW\*(C`sort { $a <=> $b }\*(C'\fR, which is optimized internally, now produces
+"uninitialized" warnings for NaNs (not-a-number values), since \f(CW\*(C`<=>\*(C'\fR
+returns \f(CW\*(C`undef\*(C'\fR for those.  This brings it in line with
+\&\f(CW\*(C`sort\ {\ 1;\ $a\ <=>\ $b\ }\*(C'\fR and other more complex cases, which are not
+optimized [perl #94390].
+.ie n .SS "The ""substr"" operator"
+.el .SS "The \f(CWsubstr\fP operator"
+.IX Subsection "The substr operator"
+.IP \(bu 4
+Tied (and otherwise magical) variables are no longer exempt from the
+"Attempt to use reference as lvalue in substr" warning.
+.IP \(bu 4
+That warning now occurs when the returned lvalue is assigned to, not
+when \f(CW\*(C`substr\*(C'\fR itself is called.  This makes a difference only if the
+return value of \f(CW\*(C`substr\*(C'\fR is referenced and later assigned to.
+.IP \(bu 4
+Passing a substring of a read-only value or a typeglob to a function
+(potential lvalue context) no longer causes an immediate "Can't coerce"
+or "Modification of a read-only value" error.  That error occurs only 
+if the passed value is assigned to.
+.Sp
+The same thing happens with the "substr outside of string" error.  If
+the lvalue is only read from, not written to, it is now just a warning, as
+with rvalue \f(CW\*(C`substr\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`substr\*(C'\fR assignments no longer call FETCH twice if the first argument
+is a tied variable, just once.
+.SS "Support for embedded nulls"
+.IX Subsection "Support for embedded nulls"
+Some parts of Perl did not work correctly with nulls (\f(CW\*(C`chr 0\*(C'\fR) embedded in
+strings.  That meant that, for instance, \f(CW\*(C`$m = "a\e0b"; foo\->$m\*(C'\fR would
+call the "a" method, instead of the actual method name contained in \f(CW$m\fR.
+These parts of perl have been fixed to support nulls:
+.IP \(bu 4
+Method names
+.IP \(bu 4
+Typeglob names (including filehandle and subroutine names)
+.IP \(bu 4
+Package names, including the return value of \f(CWref()\fR
+.IP \(bu 4
+Typeglob elements (\f(CW*foo{"THING\e0stuff"}\fR)
+.IP \(bu 4
+Signal names
+.IP \(bu 4
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+.PP
+One side effect of these changes is that blessing into "\e0" no longer
+causes \f(CWref()\fR to return false.
+.SS "Threading bugs"
+.IX Subsection "Threading bugs"
+.IP \(bu 4
+Typeglobs returned from threads are no longer cloned if the parent thread
+already has a glob with the same name.  This means that returned
+subroutines will now assign to the right package variables [perl #107366].
+.IP \(bu 4
+Some cases of threads crashing due to memory allocation during cloning have
+been fixed [perl #90006].
+.IP \(bu 4
+Thread joining would sometimes emit "Attempt to free unreferenced scalar"
+warnings if \f(CW\*(C`caller\*(C'\fR had been used from the \f(CW\*(C`DB\*(C'\fR package before thread
+creation [perl #98092].
+.IP \(bu 4
+Locking a subroutine (via \f(CW\*(C`lock &sub\*(C'\fR) is no longer a compile-time error
+for regular subs.  For lvalue subroutines, it no longer tries to return the
+sub as a scalar, resulting in strange side effects like \f(CW\*(C`ref \e$_\*(C'\fR
+returning "CODE" in some instances.
+.Sp
+\&\f(CW\*(C`lock &sub\*(C'\fR is now a run-time error if threads::shared is loaded (a
+no-op otherwise), but that may be rectified in a future version.
+.SS "Tied variables"
+.IX Subsection "Tied variables"
+.IP \(bu 4
+Various cases in which FETCH was being ignored or called too many times
+have been fixed:
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::get_layers\*(C'\fR [perl #97956]
+.IP \(bu 4
+\&\f(CW\*(C`$tied =~ y/a/b/\*(C'\fR, \f(CW\*(C`chop $tied\*(C'\fR and \f(CW\*(C`chomp $tied\*(C'\fR when \f(CW$tied\fR holds a
+reference.
+.IP \(bu 4
+When calling \f(CW\*(C`local $_\*(C'\fR [perl #105912]
+.IP \(bu 4
+Four-argument \f(CW\*(C`select\*(C'\fR
+.IP \(bu 4
+A tied buffer passed to \f(CW\*(C`sysread\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`$tied .= <>\*(C'\fR
+.IP \(bu 4
+Three-argument \f(CW\*(C`open\*(C'\fR, the third being a tied file handle
+(as in \f(CW\*(C`open $fh, ">&", $tied\*(C'\fR)
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR with a reference to a tied glob for the comparison routine.
+.IP \(bu 4
+\&\f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR in list context [perl #53554].
+.IP \(bu 4
+\&\f(CW\*(C`${$tied}\*(C'\fR, \f(CW\*(C`@{$tied}\*(C'\fR, \f(CW\*(C`%{$tied}\*(C'\fR and \f(CW\*(C`*{$tied}\*(C'\fR where the tied
+variable returns a string (\f(CW\*(C`&{}\*(C'\fR was unaffected)
+.IP \(bu 4
+\&\f(CW\*(C`defined ${ $tied_variable }\*(C'\fR
+.IP \(bu 4
+Various functions that take a filehandle argument in rvalue context
+(\f(CW\*(C`close\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, etc.) [perl #97482]
+.IP \(bu 4
+Some cases of dereferencing a complex expression, such as
+\&\f(CW\*(C`${ (), $tied } = 1\*(C'\fR, used to call \f(CW\*(C`FETCH\*(C'\fR multiple times, but now call
+it once.
+.IP \(bu 4
+\&\f(CW\*(C`$tied\->method\*(C'\fR where \f(CW$tied\fR returns a package name\-\-even resulting in
+a failure to call the method, due to memory corruption
+.IP \(bu 4
+Assignments like \f(CW\*(C`*$tied = \e&{"..."}\*(C'\fR and \f(CW\*(C`*glob = $tied\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR and
+the filetest ops (\f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, etc.)
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`caller\*(C'\fR sets \f(CW@DB::args\fR to the subroutine arguments when called from
+the DB package.  It used to crash when doing so if \f(CW@DB::args\fR happened to
+be tied.  Now it croaks instead.
+.IP \(bu 4
+Tying an element of \f(CW%ENV\fR or \f(CW\*(C`%^H\*(C'\fR and then deleting that element would
+result in a call to the tie object's DELETE method, even though tying the
+element itself is supposed to be equivalent to tying a scalar (the element
+is, of course, a scalar) [perl #67490].
+.IP \(bu 4
+When Perl autovivifies an element of a tied array or hash (which entails
+calling STORE with a new reference), it now calls FETCH immediately after
+the STORE, instead of assuming that FETCH would have returned the same
+reference.  This can make it easier to implement tied objects [perl #35865, #43011].
+.IP \(bu 4
+Four-argument \f(CW\*(C`select\*(C'\fR no longer produces its "Non-string passed as
+bitmask" warning on tied or tainted variables that are strings.
+.IP \(bu 4
+Localizing a tied scalar that returns a typeglob no longer stops it from
+being tied till the end of the scope.
+.IP \(bu 4
+Attempting to \f(CW\*(C`goto\*(C'\fR out of a tied handle method used to cause memory
+corruption or crashes.  Now it produces an error message instead
+[perl #8611].
+.IP \(bu 4
+A bug has been fixed that occurs when a tied variable is used as a
+subroutine reference:  if the last thing assigned to or returned from the
+variable was a reference or typeglob, the \f(CW\*(C`\e&$tied\*(C'\fR could either crash or
+return the wrong subroutine.  The reference case is a regression introduced
+in Perl 5.10.0.  For typeglobs, it has probably never worked till now.
+.SS "Version objects and vstrings"
+.IX Subsection "Version objects and vstrings"
+.IP \(bu 4
+The bitwise complement operator (and possibly other operators, too) when
+passed a vstring would leave vstring magic attached to the return value,
+even though the string had changed.  This meant that
+\&\f(CW\*(C`version\->new(~v1.2.3)\*(C'\fR would create a version looking like "v1.2.3"
+even though the string passed to \f(CW\*(C`version\->new\*(C'\fR was actually
+"\e376\e375\e374".  This also caused B::Deparse to deparse \f(CW\*(C`~v1.2.3\*(C'\fR
+incorrectly, without the \f(CW\*(C`~\*(C'\fR [perl #29070].
+.IP \(bu 4
+Assigning a vstring to a magic (e.g., tied, \f(CW$!\fR) variable and then
+assigning something else used to blow away all magic.  This meant that
+tied variables would come undone, \f(CW$!\fR would stop getting updated on
+failed system calls, \f(CW$|\fR would stop setting autoflush, and other
+mischief would take place.  This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`version\->new("version")\*(C'\fR and \f(CW\*(C`printf "%vd", "version"\*(C'\fR no longer
+crash [perl #102586].
+.IP \(bu 4
+Version comparisons, such as those that happen implicitly with \f(CW\*(C`use
+v5.43\*(C'\fR, no longer cause locale settings to change [perl #105784].
+.IP \(bu 4
+Version objects no longer cause memory leaks in boolean context
+[perl #109762].
+.SS "Warnings, redefinition"
+.IX Subsection "Warnings, redefinition"
+.IP \(bu 4
+Subroutines from the \f(CW\*(C`autouse\*(C'\fR namespace are once more exempt from
+redefinition warnings.  This used to work in 5.005, but was broken in
+5.6 for most subroutines.  For subs created via XS that redefine
+subroutines from the \f(CW\*(C`autouse\*(C'\fR package, this stopped working in 5.10.
+.IP \(bu 4
+New XSUBs now produce redefinition warnings if they overwrite existing
+subs, as they did in 5.8.x.  (The \f(CW\*(C`autouse\*(C'\fR logic was reversed in
+5.10\-14.  Only subroutines from the \f(CW\*(C`autouse\*(C'\fR namespace would warn
+when clobbered.)
+.IP \(bu 4
+\&\f(CW\*(C`newCONSTSUB\*(C'\fR used to use compile-time warning hints, instead of
+run-time hints.  The following code should never produce a redefinition
+warning, but it used to, if \f(CW\*(C`newCONSTSUB\*(C'\fR redefined an existing
+subroutine:
+.Sp
+.Vb 5
+\&    use warnings;
+\&    BEGIN {
+\&        no warnings;
+\&        some_XS_function_that_calls_new_CONSTSUB();
+\&    }
+.Ve
+.IP \(bu 4
+Redefinition warnings for constant subroutines are on by default (what
+are known as severe warnings in perldiag).  This occurred only
+when it was a glob assignment or declaration of a Perl subroutine that
+caused the warning.  If the creation of XSUBs triggered the warning, it
+was not a default warning.  This has been corrected.
+.IP \(bu 4
+The internal check to see whether a redefinition warning should occur
+used to emit "uninitialized" warnings in cases like this:
+.Sp
+.Vb 4
+\&    use warnings "uninitialized";
+\&    use constant {u => undef, v => undef};
+\&    sub foo(){u}
+\&    sub foo(){v}
+.Ve
+.SS "Warnings, ""Uninitialized"""
+.IX Subsection "Warnings, ""Uninitialized"""
+.IP \(bu 4
+Various functions that take a filehandle argument in rvalue context
+(\f(CW\*(C`close\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, etc.) used to warn twice for an undefined handle
+[perl #97482].
+.IP \(bu 4
+\&\f(CW\*(C`dbmopen\*(C'\fR now only warns once, rather than three times, if the mode
+argument is \f(CW\*(C`undef\*(C'\fR [perl #90064].
+.IP \(bu 4
+The \f(CW\*(C`+=\*(C'\fR operator does not usually warn when the left-hand side is
+\&\f(CW\*(C`undef\*(C'\fR, but it was doing so for tied variables.  This has been fixed
+[perl #44895].
+.IP \(bu 4
+A bug fix in Perl 5.14 introduced a new bug, causing "uninitialized"
+warnings to report the wrong variable if the operator in question had
+two operands and one was \f(CW\*(C`%{...}\*(C'\fR or \f(CW\*(C`@{...}\*(C'\fR.  This has been fixed
+[perl #103766].
+.IP \(bu 4
+\&\f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR in list context now mention the name of the variable in
+"uninitialized" warnings for string (as opposed to numeric) ranges.
+.SS "Weak references"
+.IX Subsection "Weak references"
+.IP \(bu 4
+Weakening the first argument to an automatically-invoked \f(CW\*(C`DESTROY\*(C'\fR method
+could result in erroneous "DESTROY created new reference" errors or
+crashes.  Now it is an error to weaken a read-only reference.
+.IP \(bu 4
+Weak references to lexical hashes going out of scope were not going stale
+(becoming undefined), but continued to point to the hash.
+.IP \(bu 4
+Weak references to lexical variables going out of scope are now broken
+before any magical methods (e.g., DESTROY on a tie object) are called.
+This prevents such methods from modifying the variable that will be seen
+the next time the scope is entered.
+.IP \(bu 4
+Creating a weak reference to an \f(CW@ISA\fR array or accessing the array index
+(\f(CW$#ISA\fR) could result in confused internal bookkeeping for elements
+later added to the \f(CW@ISA\fR array.  For instance, creating a weak
+reference to the element itself could push that weak reference on to \f(CW@ISA\fR;
+and elements added after use of \f(CW$#ISA\fR would be ignored by method lookup
+[perl #85670].
+.SS "Other notable fixes"
+.IX Subsection "Other notable fixes"
+.IP \(bu 4
+\&\f(CW\*(C`quotemeta\*(C'\fR now quotes consistently the same non-ASCII characters under
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR, regardless of whether the string is
+encoded in UTF\-8 or not, hence fixing the last vestiges (we hope) of the
+notorious "The "Unicode Bug"" in perlunicode.  [perl #77654].
+.Sp
+Which of these code points is quoted has changed, based on Unicode's
+recommendations.  See "quotemeta" in perlfunc for details.
+.IP \(bu 4
+\&\f(CW\*(C`study\*(C'\fR is now a no-op, presumably fixing all outstanding bugs related to
+study causing regex matches to behave incorrectly!
+.IP \(bu 4
+When one writes \f(CW\*(C`open foo || die\*(C'\fR, which used to work in Perl 4, a
+"Precedence problem" warning is produced.  This warning used erroneously to
+apply to fully-qualified bareword handle names not followed by \f(CW\*(C`||\*(C'\fR.  This
+has been corrected.
+.IP \(bu 4
+After package aliasing (\f(CW\*(C`*foo:: = *bar::\*(C'\fR), \f(CW\*(C`select\*(C'\fR with 0 or 1 argument
+would sometimes return a name that could not be used to refer to the
+filehandle, or sometimes it would return \f(CW\*(C`undef\*(C'\fR even when a filehandle
+was selected.  Now it returns a typeglob reference in such cases.
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::get_layers\*(C'\fR no longer ignores some arguments that it thinks are
+numeric, while treating others as filehandle names.  It is now consistent
+for flat scalars (i.e., not references).
+.IP \(bu 4
+Unrecognized switches on \f(CW\*(C`#!\*(C'\fR line
+.Sp
+If a switch, such as \fB\-x\fR, that cannot occur on the \f(CW\*(C`#!\*(C'\fR line is used
+there, perl dies with "Can't emulate...".
+.Sp
+It used to produce the same message for switches that perl did not
+recognize at all, whether on the command line or the \f(CW\*(C`#!\*(C'\fR line.
+.Sp
+Now it produces the "Unrecognized switch" error message [perl #104288].
+.IP \(bu 4
+\&\f(CW\*(C`system\*(C'\fR now temporarily blocks the SIGCHLD signal handler, to prevent the
+signal handler from stealing the exit status [perl #105700].
+.IP \(bu 4
+The \f(CW%n\fR formatting code for \f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR, which causes the number
+of characters to be assigned to the next argument, now actually
+assigns the number of characters, instead of the number of bytes.
+.Sp
+It also works now with special lvalue functions like \f(CW\*(C`substr\*(C'\fR and with
+nonexistent hash and array elements [perl #3471, #103492].
+.IP \(bu 4
+Perl skips copying values returned from a subroutine, for the sake of
+speed, if doing so would make no observable difference.  Because of faulty
+logic, this would happen with the
+result of \f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`shift\*(C'\fR or \f(CW\*(C`splice\*(C'\fR, even if the result was
+referenced elsewhere.  It also did so with tied variables about to be freed
+[perl #91844, #95548].
+.IP \(bu 4
+\&\f(CW\*(C`utf8::decode\*(C'\fR now refuses to modify read-only scalars [perl #91850].
+.IP \(bu 4
+Freeing \f(CW$_\fR inside a \f(CW\*(C`grep\*(C'\fR or \f(CW\*(C`map\*(C'\fR block, a code block embedded in a
+regular expression, or an \f(CW@INC\fR filter (a subroutine returned by a
+subroutine in \f(CW@INC\fR) used to result in double frees or crashes
+[perl #91880, #92254, #92256].
+.IP \(bu 4
+\&\f(CW\*(C`eval\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR in scalar context or an empty list in list
+context when there is a run-time error.  When \f(CW\*(C`eval\*(C'\fR was passed a
+string in list context and a syntax error occurred, it used to return a
+list containing a single undefined element.  Now it returns an empty
+list in list context for all errors [perl #80630].
+.IP \(bu 4
+\&\f(CW\*(C`goto &func\*(C'\fR no longer crashes, but produces an error message, when
+the unwinding of the current subroutine's scope fires a destructor that
+undefines the subroutine being "goneto" [perl #99850].
+.IP \(bu 4
+Perl now holds an extra reference count on the package that code is
+currently compiling in.  This means that the following code no longer
+crashes [perl #101486]:
+.Sp
+.Vb 3
+\&    package Foo;
+\&    BEGIN {*Foo:: = *Bar::}
+\&    sub foo;
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`x\*(C'\fR repetition operator no longer crashes on 64\-bit builds with large
+repeat counts [perl #94560].
+.IP \(bu 4
+Calling \f(CW\*(C`require\*(C'\fR on an implicit \f(CW$_\fR when \f(CW*CORE::GLOBAL::require\fR has
+been overridden does not segfault anymore, and \f(CW$_\fR is now passed to the
+overriding subroutine [perl #78260].
+.IP \(bu 4
+\&\f(CW\*(C`use\*(C'\fR and \f(CW\*(C`require\*(C'\fR are no longer affected by the I/O layers active in
+the caller's scope (enabled by open.pm) [perl #96008].
+.IP \(bu 4
+\&\f(CW\*(C`our $::é; $é\*(C'\fR (which is invalid) no longer produces the "Compilation
+error at lib/utf8_heavy.pl..." error message, which it started emitting in
+5.10.0 [perl #99984].
+.IP \(bu 4
+On 64\-bit systems, \f(CWread()\fR now understands large string offsets beyond
+the 32\-bit range.
+.IP \(bu 4
+Errors that occur when processing subroutine attributes no longer cause the
+subroutine's op tree to leak.
+.IP \(bu 4
+Passing the same constant subroutine to both \f(CW\*(C`index\*(C'\fR and \f(CW\*(C`formline\*(C'\fR no
+longer causes one or the other to fail [perl #89218]. (5.14.1)
+.IP \(bu 4
+List assignment to lexical variables declared with attributes in the same
+statement (\f(CW\*(C`my ($x,@y) : blimp = (72,94)\*(C'\fR) stopped working in Perl 5.8.0.
+It has now been fixed.
+.IP \(bu 4
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty.  This has
+been fixed [perl #90160]. (5.14.2)
+.IP \(bu 4
+Destructors on objects were not called during global destruction on objects
+that were not referenced by any scalars.  This could happen if an array
+element were blessed (e.g., \f(CW\*(C`bless \e$a[0]\*(C'\fR) or if a closure referenced a
+blessed variable (\f(CW\*(C`bless \emy @a; sub foo { @a }\*(C'\fR).
+.Sp
+Now there is an extra pass during global destruction to fire destructors on
+any objects that might be left after the usual passes that check for
+objects referenced by scalars [perl #36347].
+.IP \(bu 4
+Fixed a case where it was possible that a freed buffer may have been read
+from when parsing a here document [perl #90128]. (5.14.1)
+.IP \(bu 4
+\&\f(CWeach(\fR\f(CIARRAY\fR\f(CW)\fR is now wrapped in \f(CWdefined(...)\fR, like \f(CWeach(\fR\f(CIHASH\fR\f(CW)\fR,
+inside a \f(CW\*(C`while\*(C'\fR condition [perl #90888].
+.IP \(bu 4
+A problem with context propagation when a \f(CW\*(C`do\*(C'\fR block is an argument to
+\&\f(CW\*(C`return\*(C'\fR has been fixed.  It used to cause \f(CW\*(C`undef\*(C'\fR to be returned in
+certain cases of a \f(CW\*(C`return\*(C'\fR inside an \f(CW\*(C`if\*(C'\fR block which itself is followed by
+another \f(CW\*(C`return\*(C'\fR.
+.IP \(bu 4
+Calling \f(CW\*(C`index\*(C'\fR with a tainted constant no longer causes constants in
+subsequently compiled code to become tainted [perl #64804].
+.IP \(bu 4
+Infinite loops like \f(CW\*(C`1 while 1\*(C'\fR used to stop \f(CW\*(C`strict \*(Aqsubs\*(Aq\*(C'\fR mode from
+working for the rest of the block.
+.IP \(bu 4
+For list assignments like \f(CW\*(C`($a,$b) = ($b,$a)\*(C'\fR, Perl has to make a copy of
+the items on the right-hand side before assignment them to the left.  For
+efficiency's sake, it assigns the values on the right straight to the items
+on the left if no one variable is mentioned on both sides, as in \f(CW\*(C`($a,$b) =
+($c,$d)\*(C'\fR.  The logic for determining when it can cheat was faulty, in that
+\&\f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR on the right-hand side could fool it.  So \f(CW\*(C`($a,$b) =
+$some_true_value && ($b,$a)\*(C'\fR would end up assigning the value of \f(CW$b\fR to
+both scalars.
+.IP \(bu 4
+Perl no longer tries to apply lvalue context to the string in
+\&\f(CW\*(C`("string", $variable) ||= 1\*(C'\fR (which used to be an error).  Since the
+left-hand side of \f(CW\*(C`||=\*(C'\fR is evaluated in scalar context, that's a scalar
+comma operator, which gives all but the last item void context.  There is
+no such thing as void lvalue context, so it was a mistake for Perl to try
+to force it [perl #96942].
+.IP \(bu 4
+\&\f(CW\*(C`caller\*(C'\fR no longer leaks memory when called from the DB package if
+\&\f(CW@DB::args\fR was assigned to after the first call to \f(CW\*(C`caller\*(C'\fR.  Carp
+was triggering this bug [perl #97010]. (5.14.2)
+.IP \(bu 4
+\&\f(CW\*(C`close\*(C'\fR and similar filehandle functions, when called on built-in global
+variables (like \f(CW$+\fR), used to die if the variable happened to hold the
+undefined value, instead of producing the usual "Use of uninitialized
+value" warning.
+.IP \(bu 4
+When autovivified file handles were introduced in Perl 5.6.0, \f(CW\*(C`readline\*(C'\fR
+was inadvertently made to autovivify when called as \f(CWreadline($foo)\fR (but
+not as \f(CW\*(C`<$foo>\*(C'\fR).  It has now been fixed never to autovivify.
+.IP \(bu 4
+Calling an undefined anonymous subroutine (e.g., what \f(CW$x\fR holds after
+\&\f(CW\*(C`undef &{$x = sub{}}\*(C'\fR) used to cause a "Not a CODE reference" error, which
+has been corrected to "Undefined subroutine called" [perl #71154].
+.IP \(bu 4
+Causing \f(CW@DB::args\fR to be freed between uses of \f(CW\*(C`caller\*(C'\fR no longer
+results in a crash [perl #93320].
+.IP \(bu 4
+\&\f(CWsetpgrp($foo)\fR used to be equivalent to \f(CW\*(C`($foo, setpgrp)\*(C'\fR, because
+\&\f(CW\*(C`setpgrp\*(C'\fR was ignoring its argument if there was just one.  Now it is
+equivalent to \f(CW\*(C`setpgrp($foo,0)\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`shmread\*(C'\fR was not setting the scalar flags correctly when reading from
+shared memory, causing the existing cached numeric representation in the
+scalar to persist [perl #98480].
+.IP \(bu 4
+\&\f(CW\*(C`++\*(C'\fR and \f(CW\*(C`\-\-\*(C'\fR now work on copies of globs, instead of dying.
+.IP \(bu 4
+\&\f(CWsplice()\fR doesn't warn when truncating
+.Sp
+You can now limit the size of an array using \f(CW\*(C`splice(@a,MAX_LEN)\*(C'\fR without
+worrying about warnings.
+.IP \(bu 4
+\&\f(CW$$\fR is no longer tainted.  Since this value comes directly from
+\&\f(CWgetpid()\fR, it is always safe.
+.IP \(bu 4
+The parser no longer leaks a filehandle if STDIN was closed before parsing
+started [perl #37033].
+.IP \(bu 4
+\&\f(CW\*(C`die;\*(C'\fR with a non-reference, non-string, or magical (e.g., tainted)
+value in $@ now properly propagates that value [perl #111654].
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+On Solaris, we have two kinds of failure.
+.Sp
+If \fImake\fR is Sun's \fImake\fR, we get an error about a badly formed macro
+assignment in the \fIMakefile\fR.  That happens when \fI./Configure\fR tries to
+make depends.  \fIConfigure\fR then exits 0, but further \fImake\fR\-ing fails.
+.Sp
+If \fImake\fR is \fIgmake\fR, \fIConfigure\fR completes, then we get errors related
+to \fI/usr/include/stdbool.h\fR
+.IP \(bu 4
+On Win32, a number of tests hang unless STDERR is redirected.  The cause of
+this is still under investigation.
+.IP \(bu 4
+When building as root with a umask that prevents files from being
+other-readable, \fIt/op/filetest.t\fR will fail.  This is a test bug, not a
+bug in perl's behavior.
+.IP \(bu 4
+Configuring with a recent gcc and link-time-optimization, such as
+\&\f(CW\*(C`Configure \-Doptimize=\*(Aq\-O2 \-flto\*(Aq\*(C'\fR fails
+because the optimizer optimizes away some of Configure's tests.  A
+workaround is to omit the \f(CW\*(C`\-flto\*(C'\fR flag when running Configure, but add
+it back in while actually building, something like
+.Sp
+.Vb 2
+\&    sh Configure \-Doptimize=\-O2                                             
+\&    make OPTIMIZE=\*(Aq\-O2 \-flto\*(Aq
+.Ve
+.IP \(bu 4
+The following CPAN modules have test failures with perl 5.16.  Patches have
+been submitted for all of these, so hopefully there will be new releases
+soon:
+.RS 4
+.IP \(bu 4
+Date::Pcalc version 6.1
+.IP \(bu 4
+Module::CPANTS::Analyse version 0.85
+.Sp
+This fails due to problems in Module::Find 0.10 and File::MMagic
+1.27.
+.IP \(bu 4
+PerlIO::Util version 0.72
+.RE
+.RS 4
+.RE
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.16.0 represents approximately 12 months of development since Perl
+5.14.0 and contains approximately 590,000 lines of changes across 2,500
+files from 139 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers.  The following people are known to
+have contributed the improvements that became Perl 5.16.0:
+.PP
+Aaron Crane, Abhijit Menon-Sen, Abigail, Alan Haggai Alavi, Alberto
+Simões, Alexandr Ciornii, Andreas König, Andy Dougherty, Aristotle
+Pagaltzis, Bo Johansson, Bo Lindbergh, Breno G. de Oliveira, brian d
+foy, Brian Fraser, Brian Greenfield, Carl Hayter, Chas. Owens,
+Chia-liang Kao, Chip Salzenberg, Chris 'BinGOs' Williams, Christian
+Hansen, Christopher J. Madsen, chromatic, Claes Jacobsson, Claudio
+Ramirez, Craig A. Berry, Damian Conway, Daniel Kahn Gillmor, Darin
+McBride, Dave Rolsky, David Cantrell, David Golden, David Leadbeater,
+David Mitchell, Dee Newcum, Dennis Kaarsemaker, Dominic Hargreaves,
+Douglas Christopher Wilson, Eric Brine, Father Chrysostomos, Florian
+Ragwitz, Frederic Briere, George Greer, Gerard Goossen, Gisle Aas,
+H.Merijn Brand, Hojung Youn, Ian Goodacre, James E Keenan, Jan Dubois,
+Jerry D. Hedden, Jesse Luehrs, Jesse Vincent, Jilles Tjoelker, Jim
+Cromie, Jim Meyering, Joel Berger, Johan Vromans, Johannes Plunien, John
+Hawkinson, John P. Linderman, John Peacock, Joshua ben Jore, Juerd
+Waalboer, Karl Williamson, Karthik Rajagopalan, Keith Thompson, Kevin J.
+Woolley, Kevin Ryde, Laurent Dami, Leo Lapworth, Leon Brocard, Leon
+Timmermans, Louis Strous, Lukas Mai, Marc Green, Marcel Grünauer, Mark
+A.  Stratman, Mark Dootson, Mark Jason Dominus, Martin Hasch, Matthew
+Horsfall, Max Maischein, Michael G Schwern, Michael Witten, Mike
+Sheldrake, Moritz Lenz, Nicholas Clark, Niko Tyni, Nuno Carvalho, Pau
+Amma, Paul Evans, Paul Green, Paul Johnson, Perlover, Peter John Acklam,
+Peter Martini, Peter Scott, Phil Monsen, Pino Toscano, Rafael
+Garcia-Suarez, Rainer Tammer, Reini Urban, Ricardo Signes, Robin Barker,
+Rodolfo Carvalho, Salvador Fandiño, Sam Kimbrel, Samuel Thibault, Shawn
+M Moore, Shigeya Suzuki, Shirakata Kentaro, Shlomi Fish, Sisyphus,
+Slaven Rezic, Spiros Denaxas, Steffen Müller, Steffen Schwigon, Stephen
+Bennett, Stephen Oberholtzer, Stevan Little, Steve Hay, Steve Peters,
+Thomas Sibley, Thorsten Glaser, Timothe Litt, Todd Rinaldo, Tom
+Christiansen, Tom Hukins, Tony Cook, Vadim Konovalov, Vincent Pit,
+Vladimir Timofeev, Walt Mankowski, Yves Orton, Zefram, Zsbán Ambrus,
+Ævar Arnfjörð Bjarmason.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history.  In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core.  We're grateful to the entire CPAN
+community for helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors,
+please see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at <http://rt.perl.org/perlbug/>.  There may also be
+information at <http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5\-security\-report@perl.org.  This points to a closed
+subscription unarchived mailing list, which includes all core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported.  Please use this address only for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5161delta.1 b/upstream/mageia-cauldron/man1/perl5161delta.1
new file mode 100644
index 00000000..8c4f8d14
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5161delta.1
@@ -0,0 +1,207 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5161DELTA 1"
+.TH PERL5161DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5161delta \- what is new for perl v5.16.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.16.0 release and
+the 5.16.1 release.
+.PP
+If you are upgrading from an earlier release such as 5.14.0, first read
+perl5160delta, which describes differences between 5.14.0 and
+5.16.0.
+.SH Security
+.IX Header "Security"
+.SS "an off-by-two error in Scalar-List-Util has been fixed"
+.IX Subsection "an off-by-two error in Scalar-List-Util has been fixed"
+The bugfix was in Scalar-List-Util 1.23_04, and perl 5.16.1 includes
+Scalar-List-Util 1.25.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.16.0 If any
+exist, they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Scalar::Util and List::Util have been upgraded from version 1.23 to
+version 1.25.
+.IP \(bu 4
+B::Deparse has been updated from version 1.14 to 1.14_01.  An
+"uninitialized" warning emitted by B::Deparse has been squashed
+[perl #113464].
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Building perl with some Windows compilers used to fail due to a problem
+with miniperl's \f(CW\*(C`glob\*(C'\fR operator (which uses the \f(CW\*(C`perlglob\*(C'\fR program)
+deleting the PATH environment variable [perl #113798].
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP VMS 4
+.IX Item "VMS"
+All C header files from the top-level directory of the distribution are now
+installed on VMS, providing consistency with a long-standing practice on other
+platforms. Previously only a subset were installed, which broke non-core extension
+builds for extensions that depended on the missing include files.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+A regression introduced in Perl v5.16.0 involving
+\&\f(CW\*(C`tr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/\*(C'\fR has been fixed.  Only the first
+instance is supposed to be meaningful if a character appears more than
+once in \f(CW\*(C`\fR\f(CISEARCHLIST\fR\f(CW\*(C'\fR.  Under some circumstances, the final instance
+was overriding all earlier ones.  [perl #113584]
+.IP \(bu 4
+\&\f(CW\*(C`B::COP::stashlen\*(C'\fR has been added.   This provides access to an internal
+field added in perl 5.16 under threaded builds.  It was broken at the last
+minute before 5.16 was released [perl #113034].
+.IP \(bu 4
+The re pragma will no longer clobber \f(CW$_\fR. [perl #113750]
+.IP \(bu 4
+Unicode 6.1 published an incorrect alias for one of the
+Canonical_Combining_Class property's values (which range between 0 and
+254).  The alias \f(CW\*(C`CCC133\*(C'\fR should have been \f(CW\*(C`CCC132\*(C'\fR.  Perl now
+overrides the data file furnished by Unicode to give the correct value.
+.IP \(bu 4
+Duplicating scalar filehandles works again.  [perl #113764]
+.IP \(bu 4
+Under threaded perls, a runtime code block in a regular expression could
+corrupt the package name stored in the op tree, resulting in bad reads
+in \f(CW\*(C`caller\*(C'\fR, and possibly crashes [perl #113060].
+.IP \(bu 4
+For efficiency's sake, many operators and built-in functions return the
+same scalar each time.  Lvalue subroutines and subroutines in the CORE::
+namespace were allowing this implementation detail to leak through.
+\&\f(CW\*(C`print &CORE::uc("a"), &CORE::uc("b")\*(C'\fR used to print "BB".  The same thing
+would happen with an lvalue subroutine returning the return value of \f(CW\*(C`uc\*(C'\fR.
+Now the value is copied in such cases [perl #113044].
+.IP \(bu 4
+\&\f(CW\*(C`_\|_SUB_\|_\*(C'\fR now works in special blocks (\f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`END\*(C'\fR, etc.).
+.IP \(bu 4
+Formats that reference lexical variables from outside no longer result
+in crashes.
+.SH "Known Problems"
+.IX Header "Known Problems"
+There are no new known problems, but consult "Known
+Problems" in perl5160delta to see those identified in the 5.16.0 release.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.16.1 represents approximately 2 months of development since Perl
+5.16.0 and contains approximately 14,000 lines of changes across 96
+files from 8 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.16.1:
+.PP
+Chris 'BinGOs' Williams, Craig A. Berry, Father Chrysostomos, Karl
+Williamson, Paul Johnson, Reini Urban, Ricardo Signes, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors,
+please see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5\-security\-report@perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5162delta.1 b/upstream/mageia-cauldron/man1/perl5162delta.1
new file mode 100644
index 00000000..cd6573b8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5162delta.1
@@ -0,0 +1,157 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5162DELTA 1"
+.TH PERL5162DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5162delta \- what is new for perl v5.16.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.16.1 release and
+the 5.16.2 release.
+.PP
+If you are upgrading from an earlier release such as 5.16.0, first read
+perl5161delta, which describes differences between 5.16.0 and
+5.16.1.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.16.0
+If any exist, they are bugs, and we request that you submit a
+report.  See "Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 2.70 to version 2.76.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+configuration should no longer be confused by ls colorization
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP AIX 4
+.IX Item "AIX"
+Configure now always adds \-qlanglvl=extc99 to the CC flags on AIX when
+using xlC.  This will make it easier to compile a number of XS-based modules
+that assume C99 [perl #113778].
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+fix /\eh/ equivalence with /[\eh]/
+.Sp
+see [perl #114220]
+.SH "Known Problems"
+.IX Header "Known Problems"
+There are no new known problems.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.16.2 represents approximately 2 months of development since Perl
+5.16.1 and contains approximately 740 lines of changes across 20 files
+from 9 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.16.2:
+.PP
+Andy Dougherty, Craig A. Berry, Darin McBride, Dominic Hargreaves, Karen
+Etheridge, Karl Williamson, Peter Martini, Ricardo Signes, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+.PP
+For a more complete list of all of Perl's historical contributors,
+please see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5\-security\-report@perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5163delta.1 b/upstream/mageia-cauldron/man1/perl5163delta.1
new file mode 100644
index 00000000..0b8e4a39
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5163delta.1
@@ -0,0 +1,168 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5163DELTA 1"
+.TH PERL5163DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5163delta \- what is new for perl v5.16.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.16.2 release and
+the 5.16.3 release.
+.PP
+If you are upgrading from an earlier release such as 5.16.1, first read
+perl5162delta, which describes differences between 5.16.1 and
+5.16.2.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+No changes since 5.16.0.
+.SH Security
+.IX Header "Security"
+This release contains one major and a number of minor security fixes.
+These latter are included mainly to allow the test suite to pass cleanly
+with the clang compiler's address sanitizer facility.
+.SS "CVE\-2013\-1667: memory exhaustion with arbitrary hash keys"
+.IX Subsection "CVE-2013-1667: memory exhaustion with arbitrary hash keys"
+With a carefully crafted set of hash keys (for example arguments on a
+URL), it is possible to cause a hash to consume a large amount of memory
+and CPU, and thus possibly to achieve a Denial-of-Service.
+.PP
+This problem has been fixed.
+.SS "wrap-around with IO on long strings"
+.IX Subsection "wrap-around with IO on long strings"
+Reading or writing strings greater than 2**31 bytes in size could segfault
+due to integer wraparound.
+.PP
+This problem has been fixed.
+.SS "memory leak in Encode"
+.IX Subsection "memory leak in Encode"
+The UTF\-8 encoding implementation in Encode.xs had a memory leak which has been
+fixed.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.16.0. If any
+exist, they are bugs and reports are welcome.
+.SH Deprecations
+.IX Header "Deprecations"
+There have been no deprecations since 5.16.0.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Encode has been upgraded from version 2.44 to version 2.44_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 2.76 to version 2.76_02.
+.IP \(bu 4
+XS::APItest has been upgraded from version 0.38 to version 0.39.
+.SH "Known Problems"
+.IX Header "Known Problems"
+None.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.16.3 represents approximately 4 months of development since Perl 5.16.2
+and contains approximately 870 lines of changes across 39 files from 7 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.16.3:
+.PP
+Andy Dougherty, Chris 'BinGOs' Williams, Dave Rolsky, David Mitchell, Michael
+Schroeder, Ricardo Signes, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5\-security\-report@perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details
+on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5180delta.1 b/upstream/mageia-cauldron/man1/perl5180delta.1
new file mode 100644
index 00000000..59292314
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5180delta.1
@@ -0,0 +1,3014 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5180DELTA 1"
+.TH PERL5180DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5180delta \- what is new for perl v5.18.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the v5.16.0 release and the v5.18.0
+release.
+.PP
+If you are upgrading from an earlier release such as v5.14.0, first read
+perl5160delta, which describes differences between v5.14.0 and v5.16.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "New mechanism for experimental features"
+.IX Subsection "New mechanism for experimental features"
+Newly-added experimental features will now require this incantation:
+.PP
+.Vb 2
+\&    no warnings "experimental::feature_name";
+\&    use feature "feature_name";  # would warn without the prev line
+.Ve
+.PP
+There is a new warnings category, called "experimental", containing
+warnings that the feature pragma emits when enabling experimental
+features.
+.PP
+Newly-added experimental features will also be given special warning IDs,
+which consist of "experimental::" followed by the name of the feature.  (The
+plan is to extend this mechanism eventually to all warnings, to allow them
+to be enabled or disabled individually, and not just by category.)
+.PP
+By saying
+.PP
+.Vb 1
+\&    no warnings "experimental::feature_name";
+.Ve
+.PP
+you are taking responsibility for any breakage that future changes to, or
+removal of, the feature may cause.
+.PP
+Since some features (like \f(CW\*(C`~~\*(C'\fR or \f(CW\*(C`my $_\*(C'\fR) now emit experimental warnings,
+and you may want to disable them in code that is also run on perls that do not
+recognize these warning categories, consider using the \f(CW\*(C`if\*(C'\fR pragma like this:
+.PP
+.Vb 1
+\&    no if $] >= 5.018, warnings => "experimental::feature_name";
+.Ve
+.PP
+Existing experimental features may begin emitting these warnings, too.  Please
+consult perlexperiment for information on which features are considered
+experimental.
+.SS "Hash overhaul"
+.IX Subsection "Hash overhaul"
+Changes to the implementation of hashes in perl v5.18.0 will be one of the most
+visible changes to the behavior of existing code.
+.PP
+By default, two distinct hash variables with identical keys and values may now
+provide their contents in a different order where it was previously identical.
+.PP
+When encountering these changes, the key to cleaning up from them is to accept
+that \fBhashes are unordered collections\fR and to act accordingly.
+.PP
+\fIHash randomization\fR
+.IX Subsection "Hash randomization"
+.PP
+The seed used by Perl's hash function is now random.  This means that the
+order which keys/values will be returned from functions like \f(CWkeys()\fR,
+\&\f(CWvalues()\fR, and \f(CWeach()\fR will differ from run to run.
+.PP
+This change was introduced to make Perl's hashes more robust to algorithmic
+complexity attacks, and also because we discovered that it exposes hash
+ordering dependency bugs and makes them easier to track down.
+.PP
+Toolchain maintainers might want to invest in additional infrastructure to
+test for things like this.  Running tests several times in a row and then
+comparing results will make it easier to spot hash order dependencies in
+code.  Authors are strongly encouraged not to expose the key order of
+Perl's hashes to insecure audiences.
+.PP
+Further, every hash has its own iteration order, which should make it much
+more difficult to determine what the current hash seed is.
+.PP
+\fINew hash functions\fR
+.IX Subsection "New hash functions"
+.PP
+Perl v5.18 includes support for multiple hash functions, and changed
+the default (to ONE_AT_A_TIME_HARD), you can choose a different
+algorithm by defining a symbol at compile time.  For a current list,
+consult the \fIINSTALL\fR document.  Note that as of Perl v5.18 we can
+only recommend use of the default or SIPHASH. All the others are
+known to have security issues and are for research purposes only.
+.PP
+\fIPERL_HASH_SEED environment variable now takes a hex value\fR
+.IX Subsection "PERL_HASH_SEED environment variable now takes a hex value"
+.PP
+\&\f(CW\*(C`PERL_HASH_SEED\*(C'\fR no longer accepts an integer as a parameter;
+instead the value is expected to be a binary value encoded in a hex
+string, such as "0xf5867c55039dc724".  This is to make the
+infrastructure support hash seeds of arbitrary lengths, which might
+exceed that of an integer.  (SipHash uses a 16 byte seed.)
+.PP
+\fIPERL_PERTURB_KEYS environment variable added\fR
+.IX Subsection "PERL_PERTURB_KEYS environment variable added"
+.PP
+The \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR environment variable allows one to control the level of
+randomization applied to \f(CW\*(C`keys\*(C'\fR and friends.
+.PP
+When \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR is 0, perl will not randomize the key order at all. The
+chance that \f(CW\*(C`keys\*(C'\fR changes due to an insert will be the same as in previous
+perls, basically only when the bucket size is changed.
+.PP
+When \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR is 1, perl will randomize keys in a non-repeatable
+way. The chance that \f(CW\*(C`keys\*(C'\fR changes due to an insert will be very high.  This
+is the most secure and default mode.
+.PP
+When \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR is 2, perl will randomize keys in a repeatable way.
+Repeated runs of the same program should produce the same output every time.
+.PP
+\&\f(CW\*(C`PERL_HASH_SEED\*(C'\fR implies a non-default \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR setting. Setting
+\&\f(CW\*(C`PERL_HASH_SEED=0\*(C'\fR (exactly one 0) implies \f(CW\*(C`PERL_PERTURB_KEYS=0\*(C'\fR (hash key
+randomization disabled); setting \f(CW\*(C`PERL_HASH_SEED\*(C'\fR to any other value implies
+\&\f(CW\*(C`PERL_PERTURB_KEYS=2\*(C'\fR (deterministic and repeatable hash key randomization).
+Specifying \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR explicitly to a different level overrides this
+behavior.
+.PP
+\fR\f(BIHash::Util::hash_seed()\fR\fI now returns a string\fR
+.IX Subsection "Hash::Util::hash_seed() now returns a string"
+.PP
+\&\fBHash::Util::hash_seed()\fR now returns a string instead of an integer.  This
+is to make the infrastructure support hash seeds of arbitrary lengths
+which might exceed that of an integer.  (SipHash uses a 16 byte seed.)
+.PP
+\fIOutput of PERL_HASH_SEED_DEBUG has been changed\fR
+.IX Subsection "Output of PERL_HASH_SEED_DEBUG has been changed"
+.PP
+The environment variable PERL_HASH_SEED_DEBUG now makes perl show both the
+hash function perl was built with, \fIand\fR the seed, in hex, in use for that
+process. Code parsing this output, should it exist, must change to accommodate
+the new format.  Example of the new format:
+.PP
+.Vb 2
+\&    $ PERL_HASH_SEED_DEBUG=1 ./perl \-e1
+\&    HASH_FUNCTION = MURMUR3 HASH_SEED = 0x1476bb9f
+.Ve
+.SS "Upgrade to Unicode 6.2"
+.IX Subsection "Upgrade to Unicode 6.2"
+Perl now supports Unicode 6.2.  A list of changes from Unicode
+6.1 is at <http://www.unicode.org/versions/Unicode6.2.0>.
+.SS "Character name aliases may now include non\-Latin1\-range characters"
+.IX Subsection "Character name aliases may now include non-Latin1-range characters"
+It is possible to define your own names for characters for use in
+\&\f(CW\*(C`\eN{...}\*(C'\fR, \f(CWcharnames::vianame()\fR, etc.  These names can now be
+comprised of characters from the whole Unicode range.  This allows for
+names to be in your native language, and not just English.  Certain
+restrictions apply to the characters that may be used (you can't define
+a name that has punctuation in it, for example).  See "CUSTOM
+ALIASES" in charnames.
+.SS "New DTrace probes"
+.IX Subsection "New DTrace probes"
+The following new DTrace probes have been added:
+.IP \(bu 4
+\&\f(CW\*(C`op\-entry\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`loading\-file\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`loaded\-file\*(C'\fR
+.ie n .SS """${^LAST_FH}"""
+.el .SS \f(CW${^LAST_FH}\fP
+.IX Subsection "${^LAST_FH}"
+This new variable provides access to the filehandle that was last read.
+This is the handle used by \f(CW$.\fR and by \f(CW\*(C`tell\*(C'\fR and \f(CW\*(C`eof\*(C'\fR without
+arguments.
+.SS "Regular Expression Set Operations"
+.IX Subsection "Regular Expression Set Operations"
+This is an \fBexperimental\fR feature to allow matching against the union,
+intersection, etc., of sets of code points, similar to
+Unicode::Regex::Set.  It can also be used to extend \f(CW\*(C`/x\*(C'\fR processing
+to [bracketed] character classes, and as a replacement of user-defined
+properties, allowing more complex expressions than they do.  See
+"Extended Bracketed Character Classes" in perlrecharclass.
+.SS "Lexical subroutines"
+.IX Subsection "Lexical subroutines"
+This new feature is still considered \fBexperimental\fR.  To enable it:
+.PP
+.Vb 3
+\&    use 5.018;
+\&    no warnings "experimental::lexical_subs";
+\&    use feature "lexical_subs";
+.Ve
+.PP
+You can now declare subroutines with \f(CW\*(C`state sub foo\*(C'\fR, \f(CW\*(C`my sub foo\*(C'\fR, and
+\&\f(CW\*(C`our sub foo\*(C'\fR.  (\f(CW\*(C`state sub\*(C'\fR requires that the "state" feature be
+enabled, unless you write it as \f(CW\*(C`CORE::state sub foo\*(C'\fR.)
+.PP
+\&\f(CW\*(C`state sub\*(C'\fR creates a subroutine visible within the lexical scope in which
+it is declared.  The subroutine is shared between calls to the outer sub.
+.PP
+\&\f(CW\*(C`my sub\*(C'\fR declares a lexical subroutine that is created each time the
+enclosing block is entered.  \f(CW\*(C`state sub\*(C'\fR is generally slightly faster than
+\&\f(CW\*(C`my sub\*(C'\fR.
+.PP
+\&\f(CW\*(C`our sub\*(C'\fR declares a lexical alias to the package subroutine of the same
+name.
+.PP
+For more information, see "Lexical Subroutines" in perlsub.
+.SS "Computed Labels"
+.IX Subsection "Computed Labels"
+The loop controls \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR and \f(CW\*(C`redo\*(C'\fR, and the special \f(CW\*(C`dump\*(C'\fR
+operator, now allow arbitrary expressions to be used to compute labels at run
+time.  Previously, any argument that was not a constant was treated as the
+empty string.
+.SS "More CORE:: subs"
+.IX Subsection "More CORE:: subs"
+Several more built-in functions have been added as subroutines to the
+CORE:: namespace \- namely, those non-overridable keywords that can be
+implemented without custom parsers: \f(CW\*(C`defined\*(C'\fR, \f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`exists\*(C'\fR,
+\&\f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`prototype\*(C'\fR, \f(CW\*(C`scalar\*(C'\fR, \f(CW\*(C`split\*(C'\fR, \f(CW\*(C`study\*(C'\fR, and \f(CW\*(C`undef\*(C'\fR.
+.PP
+As some of these have prototypes, \f(CWprototype(\*(AqCORE::...\*(Aq)\fR has been
+changed to not make a distinction between overridable and non-overridable
+keywords.  This is to make \f(CWprototype(\*(AqCORE::pos\*(Aq)\fR consistent with
+\&\f(CWprototype(&CORE::pos)\fR.
+.ie n .SS """kill"" with negative signal names"
+.el .SS "\f(CWkill\fP with negative signal names"
+.IX Subsection "kill with negative signal names"
+\&\f(CW\*(C`kill\*(C'\fR has always allowed a negative signal number, which kills the
+process group instead of a single process.  It has also allowed signal
+names.  But it did not behave consistently, because negative signal names
+were treated as 0.  Now negative signals names like \f(CW\*(C`\-INT\*(C'\fR are supported
+and treated the same way as \-2 [perl #112990].
+.SH Security
+.IX Header "Security"
+.SS "See also: hash overhaul"
+.IX Subsection "See also: hash overhaul"
+Some of the changes in the hash overhaul were made to
+enhance security.  Please read that section.
+.ie n .SS """Storable"" security warning in documentation"
+.el .SS "\f(CWStorable\fP security warning in documentation"
+.IX Subsection "Storable security warning in documentation"
+The documentation for \f(CW\*(C`Storable\*(C'\fR now includes a section which warns readers
+of the danger of accepting Storable documents from untrusted sources. The
+short version is that deserializing certain types of data can lead to loading
+modules and other code execution. This is documented behavior and wanted
+behavior, but this opens an attack vector for malicious entities.
+.ie n .SS """Locale::Maketext"" allowed code injection via a malicious template"
+.el .SS "\f(CWLocale::Maketext\fP allowed code injection via a malicious template"
+.IX Subsection "Locale::Maketext allowed code injection via a malicious template"
+If users could provide a translation string to Locale::Maketext, this could be
+used to invoke arbitrary Perl subroutines available in the current process.
+.PP
+This has been fixed, but it is still possible to invoke any method provided by
+\&\f(CW\*(C`Locale::Maketext\*(C'\fR itself or a subclass that you are using. One of these
+methods in turn will invoke the Perl core's \f(CW\*(C`sprintf\*(C'\fR subroutine.
+.PP
+In summary, allowing users to provide translation strings without auditing
+them is a bad idea.
+.PP
+This vulnerability is documented in CVE\-2012\-6329.
+.SS "Avoid calling memset with a negative count"
+.IX Subsection "Avoid calling memset with a negative count"
+Poorly written perl code that allows an attacker to specify the count to perl's
+\&\f(CW\*(C`x\*(C'\fR string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before v5.15.5 can escalate
+that into a heap buffer overrun; coupled with versions of glibc before 2.16, it
+possibly allows the execution of arbitrary code.
+.PP
+The flaw addressed to this commit has been assigned identifier CVE\-2012\-5195
+and was researched by Tim Brown.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "See also: hash overhaul"
+.IX Subsection "See also: hash overhaul"
+Some of the changes in the hash overhaul are not fully
+compatible with previous versions of perl.  Please read that section.
+.ie n .SS "An unknown character name in ""\eN{...}"" is now a syntax error"
+.el .SS "An unknown character name in \f(CW\eN{...}\fP is now a syntax error"
+.IX Subsection "An unknown character name in N{...} is now a syntax error"
+Previously, it warned, and the Unicode REPLACEMENT CHARACTER was
+substituted.  Unicode now recommends that this situation be a syntax
+error.  Also, the previous behavior led to some confusing warnings and
+behaviors, and since the REPLACEMENT CHARACTER has no use other than as
+a stand-in for some unknown character, any code that has this problem is
+buggy.
+.ie n .SS "Formerly deprecated characters in ""\eN{}"" character name aliases are now errors."
+.el .SS "Formerly deprecated characters in \f(CW\eN{}\fP character name aliases are now errors."
+.IX Subsection "Formerly deprecated characters in N{} character name aliases are now errors."
+Since v5.12.0, it has been deprecated to use certain characters in
+user-defined \f(CW\*(C`\eN{...}\*(C'\fR character names.  These now cause a syntax
+error.  For example, it is now an error to begin a name with a digit,
+such as in
+.PP
+.Vb 1
+\& my $undraftable = "\eN{4F}";    # Syntax error!
+.Ve
+.PP
+or to have commas anywhere in the name.  See "CUSTOM ALIASES" in charnames.
+.ie n .SS """\eN{BELL}"" now refers to U+1F514 instead of U+0007"
+.el .SS "\f(CW\eN{BELL}\fP now refers to U+1F514 instead of U+0007"
+.IX Subsection "N{BELL} now refers to U+1F514 instead of U+0007"
+Unicode 6.0 reused the name "BELL" for a different code point than it
+traditionally had meant.  Since Perl v5.14, use of this name still
+referred to U+0007, but would raise a deprecation warning.  Now, "BELL"
+refers to U+1F514, and the name for U+0007 is "ALERT".  All the
+functions in charnames have been correspondingly updated.
+.SS "New Restrictions in Multi-Character Case-Insensitive Matching in Regular Expression Bracketed Character Classes"
+.IX Subsection "New Restrictions in Multi-Character Case-Insensitive Matching in Regular Expression Bracketed Character Classes"
+Unicode has now withdrawn their previous recommendation for regular
+expressions to automatically handle cases where a single character can
+match multiple characters case-insensitively, for example, the letter
+LATIN SMALL LETTER SHARP S and the sequence \f(CW\*(C`ss\*(C'\fR.  This is because
+it turns out to be impracticable to do this correctly in all
+circumstances.  Because Perl has tried to do this as best it can, it
+will continue to do so.  (We are considering an option to turn it off.)
+However, a new restriction is being added on such matches when they
+occur in [bracketed] character classes.  People were specifying
+things such as \f(CW\*(C`/[\e0\-\exff]/i\*(C'\fR, and being surprised that it matches the
+two character sequence \f(CW\*(C`ss\*(C'\fR (since LATIN SMALL LETTER SHARP S occurs in
+this range).  This behavior is also inconsistent with using a
+property instead of a range:  \f(CW\*(C`\ep{Block=Latin1}\*(C'\fR also includes LATIN
+SMALL LETTER SHARP S, but \f(CW\*(C`/[\ep{Block=Latin1}]/i\*(C'\fR does not match \f(CW\*(C`ss\*(C'\fR.
+The new rule is that for there to be a multi-character case-insensitive
+match within a bracketed character class, the character must be
+explicitly listed, and not as an end point of a range.  This more
+closely obeys the Principle of Least Astonishment.  See
+"Bracketed Character Classes" in perlrecharclass.  Note that a bug [perl
+#89774], now fixed as part of this change, prevented the previous
+behavior from working fully.
+.SS "Explicit rules for variable names and identifiers"
+.IX Subsection "Explicit rules for variable names and identifiers"
+Due to an oversight, single character variable names in v5.16 were
+completely unrestricted.  This opened the door to several kinds of
+insanity.  As of v5.18, these now follow the rules of other identifiers,
+in addition to accepting characters that match the \f(CW\*(C`\ep{POSIX_Punct}\*(C'\fR
+property.
+.PP
+There is no longer any difference in the parsing of identifiers
+specified by using braces versus without braces.  For instance, perl
+used to allow \f(CW\*(C`${foo:bar}\*(C'\fR (with a single colon) but not \f(CW$foo:bar\fR.
+Now that both are handled by a single code path, they are both treated
+the same way: both are forbidden.  Note that this change is about the
+range of permissible literal identifiers, not other expressions.
+.SS "Vertical tabs are now whitespace"
+.IX Subsection "Vertical tabs are now whitespace"
+No one could recall why \f(CW\*(C`\es\*(C'\fR didn't match \f(CW\*(C`\ecK\*(C'\fR, the vertical tab.
+Now it does.  Given the extreme rarity of that character, very little
+breakage is expected.  That said, here's what it means:
+.PP
+\&\f(CW\*(C`\es\*(C'\fR in a regex now matches a vertical tab in all circumstances.
+.PP
+Literal vertical tabs in a regex literal are ignored when the \f(CW\*(C`/x\*(C'\fR
+modifier is used.
+.PP
+Leading vertical tabs, alone or mixed with other whitespace, are now
+ignored when interpreting a string as a number.  For example:
+.PP
+.Vb 2
+\&  $dec = " \ecK \et 123";
+\&  $hex = " \ecK \et 0xF";
+\&
+\&  say 0 + $dec;   # was 0 with warning, now 123
+\&  say int $dec;   # was 0, now 123
+\&  say oct $hex;   # was 0, now  15
+.Ve
+.ie n .SS """/(?{})/"" and ""/(??{})/"" have been heavily reworked"
+.el .SS "\f(CW/(?{})/\fP and \f(CW/(??{})/\fP have been heavily reworked"
+.IX Subsection "/(?{})/ and /(??{})/ have been heavily reworked"
+The implementation of this feature has been almost completely rewritten.
+Although its main intent is to fix bugs, some behaviors, especially
+related to the scope of lexical variables, will have changed.  This is
+described more fully in the "Selected Bug Fixes" section.
+.SS "Stricter parsing of substitution replacement"
+.IX Subsection "Stricter parsing of substitution replacement"
+It is no longer possible to abuse the way the parser parses \f(CW\*(C`s///e\*(C'\fR like
+this:
+.PP
+.Vb 3
+\&    %_=(_,"Just another ");
+\&    $_="Perl hacker,\en";
+\&    s//_}\->{_/e;print
+.Ve
+.ie n .SS """given"" now aliases the global $_"
+.el .SS "\f(CWgiven\fP now aliases the global \f(CW$_\fP"
+.IX Subsection "given now aliases the global $_"
+Instead of assigning to an implicit lexical \f(CW$_\fR, \f(CW\*(C`given\*(C'\fR now makes the
+global \f(CW$_\fR an alias for its argument, just like \f(CW\*(C`foreach\*(C'\fR.  However, it
+still uses lexical \f(CW$_\fR if there is lexical \f(CW$_\fR in scope (again, just like
+\&\f(CW\*(C`foreach\*(C'\fR) [perl #114020].
+.SS "The smartmatch family of features are now experimental"
+.IX Subsection "The smartmatch family of features are now experimental"
+Smart match, added in v5.10.0 and significantly revised in v5.10.1, has been
+a regular point of complaint.  Although there are a number of ways in which
+it is useful, it has also proven problematic and confusing for both users and
+implementors of Perl.  There have been a number of proposals on how to best
+address the problem.  It is clear that smartmatch is almost certainly either
+going to change or go away in the future.  Relying on its current behavior
+is not recommended.
+.PP
+Warnings will now be issued when the parser sees \f(CW\*(C`~~\*(C'\fR, \f(CW\*(C`given\*(C'\fR, or \f(CW\*(C`when\*(C'\fR.
+To disable these warnings, you can add this line to the appropriate scope:
+.PP
+.Vb 1
+\&  no if $] >= 5.018, warnings => "experimental::smartmatch";
+.Ve
+.PP
+Consider, though, replacing the use of these features, as they may change
+behavior again before becoming stable.
+.ie n .SS "Lexical $_ is now experimental"
+.el .SS "Lexical \f(CW$_\fP is now experimental"
+.IX Subsection "Lexical $_ is now experimental"
+Since it was introduced in Perl v5.10, it has caused much confusion with no
+obvious solution:
+.IP \(bu 4
+Various modules (e.g., List::Util) expect callback routines to use the
+global \f(CW$_\fR.  \f(CW\*(C`use List::Util \*(Aqfirst\*(Aq; my $_; first { $_ == 1 } @list\*(C'\fR
+does not work as one would expect.
+.IP \(bu 4
+A \f(CW\*(C`my $_\*(C'\fR declaration earlier in the same file can cause confusing closure
+warnings.
+.IP \(bu 4
+The "_" subroutine prototype character allows called subroutines to access
+your lexical \f(CW$_\fR, so it is not really private after all.
+.IP \(bu 4
+Nevertheless, subroutines with a "(@)" prototype and methods cannot access
+the caller's lexical \f(CW$_\fR, unless they are written in XS.
+.IP \(bu 4
+But even XS routines cannot access a lexical \f(CW$_\fR declared, not in the
+calling subroutine, but in an outer scope, iff that subroutine happened not
+to mention \f(CW$_\fR or use any operators that default to \f(CW$_\fR.
+.PP
+It is our hope that lexical \f(CW$_\fR can be rehabilitated, but this may
+cause changes in its behavior.  Please use it with caution until it
+becomes stable.
+.ie n .SS "\fBreadline()\fP with ""$/ = \eN"" now reads N characters, not N bytes"
+.el .SS "\fBreadline()\fP with \f(CW$/ = \eN\fP now reads N characters, not N bytes"
+.IX Subsection "readline() with $/ = N now reads N characters, not N bytes"
+Previously, when reading from a stream with I/O layers such as
+\&\f(CW\*(C`encoding\*(C'\fR, the \fBreadline()\fR function, otherwise known as the \f(CW\*(C`<>\*(C'\fR
+operator, would read \fIN\fR bytes from the top-most layer. [perl #79960]
+.PP
+Now, \fIN\fR characters are read instead.
+.PP
+There is no change in behaviour when reading from streams with no
+extra layers, since bytes map exactly to characters.
+.ie n .SS "Overridden ""glob"" is now passed one argument"
+.el .SS "Overridden \f(CWglob\fP is now passed one argument"
+.IX Subsection "Overridden glob is now passed one argument"
+\&\f(CW\*(C`glob\*(C'\fR overrides used to be passed a magical undocumented second argument
+that identified the caller.  Nothing on CPAN was using this, and it got in
+the way of a bug fix, so it was removed.  If you really need to identify
+the caller, see Devel::Callsite on CPAN.
+.SS "Here doc parsing"
+.IX Subsection "Here doc parsing"
+The body of a here document inside a quote-like operator now always begins
+on the line after the "<<foo" marker.  Previously, it was documented to
+begin on the line following the containing quote-like operator, but that
+was only sometimes the case [perl #114040].
+.SS "Alphanumeric operators must now be separated from the closing delimiter of regular expressions"
+.IX Subsection "Alphanumeric operators must now be separated from the closing delimiter of regular expressions"
+You may no longer write something like:
+.PP
+.Vb 1
+\& m/a/and 1
+.Ve
+.PP
+Instead you must write
+.PP
+.Vb 1
+\& m/a/ and 1
+.Ve
+.PP
+with whitespace separating the operator from the closing delimiter of
+the regular expression.  Not having whitespace has resulted in a
+deprecation warning since Perl v5.14.0.
+.SS "qw(...) can no longer be used as parentheses"
+.IX Subsection "qw(...) can no longer be used as parentheses"
+\&\f(CW\*(C`qw\*(C'\fR lists used to fool the parser into thinking they were always
+surrounded by parentheses.  This permitted some surprising constructions
+such as \f(CW\*(C`foreach $x qw(a b c) {...}\*(C'\fR, which should really be written
+\&\f(CW\*(C`foreach $x (qw(a b c)) {...}\*(C'\fR.  These would sometimes get the lexer into
+the wrong state, so they didn't fully work, and the similar \f(CW\*(C`foreach qw(a
+b c) {...}\*(C'\fR that one might expect to be permitted never worked at all.
+.PP
+This side effect of \f(CW\*(C`qw\*(C'\fR has now been abolished.  It has been deprecated
+since Perl v5.13.11.  It is now necessary to use real parentheses
+everywhere that the grammar calls for them.
+.SS "Interaction of lexical and default warnings"
+.IX Subsection "Interaction of lexical and default warnings"
+Turning on any lexical warnings used first to disable all default warnings
+if lexical warnings were not already enabled:
+.PP
+.Vb 3
+\&    $*; # deprecation warning
+\&    use warnings "void";
+\&    $#; # void warning; no deprecation warning
+.Ve
+.PP
+Now, the \f(CW\*(C`debugging\*(C'\fR, \f(CW\*(C`deprecated\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`inplace\*(C'\fR and \f(CW\*(C`malloc\*(C'\fR warnings
+categories are left on when turning on lexical warnings (unless they are
+turned off by \f(CW\*(C`no warnings\*(C'\fR, of course).
+.PP
+This may cause deprecation warnings to occur in code that used to be free
+of warnings.
+.PP
+Those are the only categories consisting only of default warnings.  Default
+warnings in other categories are still disabled by \f(CW\*(C`use warnings "category"\*(C'\fR,
+as we do not yet have the infrastructure for controlling
+individual warnings.
+.ie n .SS """state sub"" and ""our sub"""
+.el .SS "\f(CWstate sub\fP and \f(CWour sub\fP"
+.IX Subsection "state sub and our sub"
+Due to an accident of history, \f(CW\*(C`state sub\*(C'\fR and \f(CW\*(C`our sub\*(C'\fR were equivalent
+to a plain \f(CW\*(C`sub\*(C'\fR, so one could even create an anonymous sub with
+\&\f(CW\*(C`our sub { ... }\*(C'\fR.  These are now disallowed outside of the "lexical_subs"
+feature.  Under the "lexical_subs" feature they have new meanings described
+in "Lexical Subroutines" in perlsub.
+.SS "Defined values stored in environment are forced to byte strings"
+.IX Subsection "Defined values stored in environment are forced to byte strings"
+A value stored in an environment variable has always been stringified when
+inherited by child processes.
+.PP
+In this release, when assigning to \f(CW%ENV\fR, values are immediately stringified,
+and converted to be only a byte string.
+.PP
+First, it is forced to be only a string.  Then if the string is utf8 and the
+equivalent of \f(CWutf8::downgrade()\fR works, that result is used; otherwise, the
+equivalent of \f(CWutf8::encode()\fR is used, and a warning is issued about wide
+characters ("Diagnostics").
+.ie n .SS """require"" dies for unreadable files"
+.el .SS "\f(CWrequire\fP dies for unreadable files"
+.IX Subsection "require dies for unreadable files"
+When \f(CW\*(C`require\*(C'\fR encounters an unreadable file, it now dies.  It used to
+ignore the file and continue searching the directories in \f(CW@INC\fR
+[perl #113422].
+.ie n .SS """gv_fetchmeth_*"" and SUPER"
+.el .SS "\f(CWgv_fetchmeth_*\fP and SUPER"
+.IX Subsection "gv_fetchmeth_* and SUPER"
+The various \f(CW\*(C`gv_fetchmeth_*\*(C'\fR XS functions used to treat a package whose
+named ended with \f(CW\*(C`::SUPER\*(C'\fR specially.  A method lookup on the \f(CW\*(C`Foo::SUPER\*(C'\fR
+package would be treated as a \f(CW\*(C`SUPER\*(C'\fR method lookup on the \f(CW\*(C`Foo\*(C'\fR package.  This
+is no longer the case.  To do a \f(CW\*(C`SUPER\*(C'\fR lookup, pass the \f(CW\*(C`Foo\*(C'\fR stash and the
+\&\f(CW\*(C`GV_SUPER\*(C'\fR flag.
+.ie n .SS """split""'s first argument is more consistently interpreted"
+.el .SS "\f(CWsplit\fP's first argument is more consistently interpreted"
+.IX Subsection "split's first argument is more consistently interpreted"
+After some changes earlier in v5.17, \f(CW\*(C`split\*(C'\fR's behavior has been
+simplified: if the PATTERN argument evaluates to a string
+containing one space, it is treated the way that a \fIliteral\fR string
+containing one space once was.
+.SH Deprecations
+.IX Header "Deprecations"
+.SS "Module removals"
+.IX Subsection "Module removals"
+The following modules will be removed from the core distribution in a future
+release, and will at that time need to be installed from CPAN. Distributions
+on CPAN which require these modules will need to list them as prerequisites.
+.PP
+The core versions of these modules will now issue \f(CW"deprecated"\fR\-category
+warnings to alert you to this fact. To silence these deprecation warnings,
+install the modules in question from CPAN.
+.PP
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use. Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
+.IP encoding 4
+.IX Item "encoding"
+The use of this pragma is now strongly discouraged. It conflates the encoding
+of source text with the encoding of I/O data, reinterprets escape sequences in
+source text (a questionable choice), and introduces the UTF\-8 bug to all runtime
+handling of character strings. It is broken as designed and beyond repair.
+.Sp
+For using non-ASCII literal characters in source text, please refer to utf8.
+For dealing with textual I/O data, please refer to Encode and open.
+.IP Archive::Extract 4
+.IX Item "Archive::Extract"
+.PD 0
+.IP B::Lint 4
+.IX Item "B::Lint"
+.IP B::Lint::Debug 4
+.IX Item "B::Lint::Debug"
+.ie n .IP "CPANPLUS and all included ""CPANPLUS::*"" modules" 4
+.el .IP "CPANPLUS and all included \f(CWCPANPLUS::*\fR modules" 4
+.IX Item "CPANPLUS and all included CPANPLUS::* modules"
+.IP Devel::InnerPackage 4
+.IX Item "Devel::InnerPackage"
+.IP Log::Message 4
+.IX Item "Log::Message"
+.IP Log::Message::Config 4
+.IX Item "Log::Message::Config"
+.IP Log::Message::Handlers 4
+.IX Item "Log::Message::Handlers"
+.IP Log::Message::Item 4
+.IX Item "Log::Message::Item"
+.IP Log::Message::Simple 4
+.IX Item "Log::Message::Simple"
+.IP Module::Pluggable 4
+.IX Item "Module::Pluggable"
+.IP Module::Pluggable::Object 4
+.IX Item "Module::Pluggable::Object"
+.IP Object::Accessor 4
+.IX Item "Object::Accessor"
+.IP Pod::LaTeX 4
+.IX Item "Pod::LaTeX"
+.IP Term::UI 4
+.IX Item "Term::UI"
+.IP Term::UI::History 4
+.IX Item "Term::UI::History"
+.PD
+.SS "Deprecated Utilities"
+.IX Subsection "Deprecated Utilities"
+The following utilities will be removed from the core distribution in a
+future release as their associated modules have been deprecated. They
+will remain available with the applicable CPAN distribution.
+.IP cpanp 4
+.IX Item "cpanp"
+.PD 0
+.ie n .IP """cpanp\-run\-perl""" 4
+.el .IP \f(CWcpanp\-run\-perl\fR 4
+.IX Item "cpanp-run-perl"
+.IP cpan2dist 4
+.IX Item "cpan2dist"
+.PD
+These items are part of the \f(CW\*(C`CPANPLUS\*(C'\fR distribution.
+.IP pod2latex 4
+.IX Item "pod2latex"
+This item is part of the \f(CW\*(C`Pod::LaTeX\*(C'\fR distribution.
+.SS PL_sv_objcount
+.IX Subsection "PL_sv_objcount"
+This interpreter-global variable used to track the total number of
+Perl objects in the interpreter. It is no longer maintained and will
+be removed altogether in Perl v5.20.
+.ie n .SS "Five additional characters should be escaped in patterns with ""/x"""
+.el .SS "Five additional characters should be escaped in patterns with \f(CW/x\fP"
+.IX Subsection "Five additional characters should be escaped in patterns with /x"
+When a regular expression pattern is compiled with \f(CW\*(C`/x\*(C'\fR, Perl treats 6
+characters as white space to ignore, such as SPACE and TAB.  However,
+Unicode recommends 11 characters be treated thusly.  We will conform
+with this in a future Perl version.  In the meantime, use of any of the
+missing characters will raise a deprecation warning, unless turned off.
+The five characters are:
+.PP
+.Vb 5
+\&    U+0085 NEXT LINE
+\&    U+200E LEFT\-TO\-RIGHT MARK
+\&    U+200F RIGHT\-TO\-LEFT MARK
+\&    U+2028 LINE SEPARATOR
+\&    U+2029 PARAGRAPH SEPARATOR
+.Ve
+.SS "User-defined charnames with surprising whitespace"
+.IX Subsection "User-defined charnames with surprising whitespace"
+A user-defined character name with trailing or multiple spaces in a row is
+likely a typo.  This now generates a warning when defined, on the assumption
+that uses of it will be unlikely to include the excess whitespace.
+.SS "Various XS-callable functions are now deprecated"
+.IX Subsection "Various XS-callable functions are now deprecated"
+All the functions used to classify characters will be removed from a
+future version of Perl, and should not be used.  With participating C
+compilers (e.g., gcc), compiling any file that uses any of these will
+generate a warning.  These were not intended for public use; there are
+equivalent, faster, macros for most of them.
+.PP
+See "Character classes" in perlapi.  The complete list is:
+.PP
+\&\f(CW\*(C`is_uni_alnum\*(C'\fR, \f(CW\*(C`is_uni_alnumc\*(C'\fR, \f(CW\*(C`is_uni_alnumc_lc\*(C'\fR,
+\&\f(CW\*(C`is_uni_alnum_lc\*(C'\fR, \f(CW\*(C`is_uni_alpha\*(C'\fR, \f(CW\*(C`is_uni_alpha_lc\*(C'\fR,
+\&\f(CW\*(C`is_uni_ascii\*(C'\fR, \f(CW\*(C`is_uni_ascii_lc\*(C'\fR, \f(CW\*(C`is_uni_blank\*(C'\fR,
+\&\f(CW\*(C`is_uni_blank_lc\*(C'\fR, \f(CW\*(C`is_uni_cntrl\*(C'\fR, \f(CW\*(C`is_uni_cntrl_lc\*(C'\fR,
+\&\f(CW\*(C`is_uni_digit\*(C'\fR, \f(CW\*(C`is_uni_digit_lc\*(C'\fR, \f(CW\*(C`is_uni_graph\*(C'\fR,
+\&\f(CW\*(C`is_uni_graph_lc\*(C'\fR, \f(CW\*(C`is_uni_idfirst\*(C'\fR, \f(CW\*(C`is_uni_idfirst_lc\*(C'\fR,
+\&\f(CW\*(C`is_uni_lower\*(C'\fR, \f(CW\*(C`is_uni_lower_lc\*(C'\fR, \f(CW\*(C`is_uni_print\*(C'\fR,
+\&\f(CW\*(C`is_uni_print_lc\*(C'\fR, \f(CW\*(C`is_uni_punct\*(C'\fR, \f(CW\*(C`is_uni_punct_lc\*(C'\fR,
+\&\f(CW\*(C`is_uni_space\*(C'\fR, \f(CW\*(C`is_uni_space_lc\*(C'\fR, \f(CW\*(C`is_uni_upper\*(C'\fR,
+\&\f(CW\*(C`is_uni_upper_lc\*(C'\fR, \f(CW\*(C`is_uni_xdigit\*(C'\fR, \f(CW\*(C`is_uni_xdigit_lc\*(C'\fR,
+\&\f(CW\*(C`is_utf8_alnum\*(C'\fR, \f(CW\*(C`is_utf8_alnumc\*(C'\fR, \f(CW\*(C`is_utf8_alpha\*(C'\fR,
+\&\f(CW\*(C`is_utf8_ascii\*(C'\fR, \f(CW\*(C`is_utf8_blank\*(C'\fR, \f(CW\*(C`is_utf8_char\*(C'\fR,
+\&\f(CW\*(C`is_utf8_cntrl\*(C'\fR, \f(CW\*(C`is_utf8_digit\*(C'\fR, \f(CW\*(C`is_utf8_graph\*(C'\fR,
+\&\f(CW\*(C`is_utf8_idcont\*(C'\fR, \f(CW\*(C`is_utf8_idfirst\*(C'\fR, \f(CW\*(C`is_utf8_lower\*(C'\fR,
+\&\f(CW\*(C`is_utf8_mark\*(C'\fR, \f(CW\*(C`is_utf8_perl_space\*(C'\fR, \f(CW\*(C`is_utf8_perl_word\*(C'\fR,
+\&\f(CW\*(C`is_utf8_posix_digit\*(C'\fR, \f(CW\*(C`is_utf8_print\*(C'\fR, \f(CW\*(C`is_utf8_punct\*(C'\fR,
+\&\f(CW\*(C`is_utf8_space\*(C'\fR, \f(CW\*(C`is_utf8_upper\*(C'\fR, \f(CW\*(C`is_utf8_xdigit\*(C'\fR,
+\&\f(CW\*(C`is_utf8_xidcont\*(C'\fR, \f(CW\*(C`is_utf8_xidfirst\*(C'\fR.
+.PP
+In addition these three functions that have never worked properly are
+deprecated:
+\&\f(CW\*(C`to_uni_lower_lc\*(C'\fR, \f(CW\*(C`to_uni_title_lc\*(C'\fR, and \f(CW\*(C`to_uni_upper_lc\*(C'\fR.
+.SS "Certain rare uses of backslashes within regexes are now deprecated"
+.IX Subsection "Certain rare uses of backslashes within regexes are now deprecated"
+There are three pairs of characters that Perl recognizes as
+metacharacters in regular expression patterns: \f(CW\*(C`{}\*(C'\fR, \f(CW\*(C`[]\*(C'\fR, and \f(CW\*(C`()\*(C'\fR.
+These can be used as well to delimit patterns, as in:
+.PP
+.Vb 2
+\&  m{foo}
+\&  s(foo)(bar)
+.Ve
+.PP
+Since they are metacharacters, they have special meaning to regular
+expression patterns, and it turns out that you can't turn off that
+special meaning by the normal means of preceding them with a backslash,
+if you use them, paired, within a pattern delimited by them.  For
+example, in
+.PP
+.Vb 1
+\&  m{foo\e{1,3\e}}
+.Ve
+.PP
+the backslashes do not change the behavior, and this matches
+\&\f(CW"f\ o"\fR followed by one to three more occurrences of \f(CW"o"\fR.
+.PP
+Usages like this, where they are interpreted as metacharacters, are
+exceedingly rare; we think there are none, for example, in all of CPAN.
+Hence, this deprecation should affect very little code.  It does give
+notice, however, that any such code needs to change, which will in turn
+allow us to change the behavior in future Perl versions so that the
+backslashes do have an effect, and without fear that we are silently
+breaking any existing code.
+.ie n .SS "Splitting the tokens ""(?"" and ""(*"" in regular expressions"
+.el .SS "Splitting the tokens \f(CW(?\fP and \f(CW(*\fP in regular expressions"
+.IX Subsection "Splitting the tokens (? and (* in regular expressions"
+A deprecation warning is now raised if the \f(CW\*(C`(\*(C'\fR and \f(CW\*(C`?\*(C'\fR are separated
+by white space or comments in \f(CW\*(C`(?...)\*(C'\fR regular expression constructs.
+Similarly, if the \f(CW\*(C`(\*(C'\fR and \f(CW\*(C`*\*(C'\fR are separated in \f(CW\*(C`(*VERB...)\*(C'\fR
+constructs.
+.SS "Pre-PerlIO IO implementations"
+.IX Subsection "Pre-PerlIO IO implementations"
+In theory, you can currently build perl without PerlIO.  Instead, you'd use a
+wrapper around stdio or sfio.  In practice, this isn't very useful.  It's not
+well tested, and without any support for IO layers or (thus) Unicode, it's not
+much of a perl.  Building without PerlIO will most likely be removed in the
+next version of perl.
+.PP
+PerlIO supports a \f(CW\*(C`stdio\*(C'\fR layer if stdio use is desired.  Similarly a
+sfio layer could be produced in the future, if needed.
+.SH "Future Deprecations"
+.IX Header "Future Deprecations"
+.IP \(bu 4
+Platforms without support infrastructure
+.Sp
+Both Windows CE and z/OS have been historically under-maintained, and are
+currently neither successfully building nor regularly being smoke tested.
+Efforts are underway to change this situation, but it should not be taken for
+granted that the platforms are safe and supported.  If they do not become
+buildable and regularly smoked, support for them may be actively removed in
+future releases.  If you have an interest in these platforms and you can lend
+your time, expertise, or hardware to help support these platforms, please let
+the perl development effort know by emailing \f(CW\*(C`perl5\-porters@perl.org\*(C'\fR.
+.Sp
+Some platforms that appear otherwise entirely dead are also on the short list
+for removal between now and v5.20.0:
+.RS 4
+.IP DG/UX 4
+.IX Item "DG/UX"
+.PD 0
+.IP NeXT 4
+.IX Item "NeXT"
+.RE
+.RS 4
+.PD
+.Sp
+We also think it likely that current versions of Perl will no longer
+build AmigaOS, DJGPP, NetWare (natively), OS/2 and Plan 9. If you
+are using Perl on such a platform and have an interest in ensuring
+Perl's future on them, please contact us.
+.Sp
+We believe that Perl has long been unable to build on mixed endian
+architectures (such as PDP\-11s), and intend to remove any remaining
+support code. Similarly, code supporting the long unmaintained GNU
+dld will be removed soon if no-one makes themselves known as an
+active user.
+.RE
+.IP \(bu 4
+Swapping of $< and $>
+.Sp
+Perl has supported the idiom of swapping $< and $> (and likewise $( and
+$)) to temporarily drop permissions since 5.0, like this:
+.Sp
+.Vb 1
+\&    ($<, $>) = ($>, $<);
+.Ve
+.Sp
+However, this idiom modifies the real user/group id, which can have
+undesirable side-effects, is no longer useful on any platform perl
+supports and complicates the implementation of these variables and list
+assignment in general.
+.Sp
+As an alternative, assignment only to \f(CW$>\fR is recommended:
+.Sp
+.Vb 1
+\&    local $> = $<;
+.Ve
+.Sp
+See also: Setuid Demystified <http://www.cs.berkeley.edu/~daw/papers/setuid-usenix02.pdf>.
+.IP \(bu 4
+\&\f(CW\*(C`microperl\*(C'\fR, long broken and of unclear present purpose, will be removed.
+.IP \(bu 4
+Revamping \f(CW"\eQ"\fR semantics in double-quotish strings when combined with
+other escapes.
+.Sp
+There are several bugs and inconsistencies involving combinations
+of \f(CW\*(C`\eQ\*(C'\fR and escapes like \f(CW\*(C`\ex\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, etc., within a \f(CW\*(C`\eQ...\eE\*(C'\fR pair.
+These need to be fixed, and doing so will necessarily change current
+behavior.  The changes have not yet been settled.
+.IP \(bu 4
+Use of \f(CW$x\fR, where \f(CW\*(C`x\*(C'\fR stands for any actual (non-printing) C0 control
+character will be disallowed in a future Perl version.  Use \f(CW\*(C`${x}\*(C'\fR
+instead (where again \f(CW\*(C`x\*(C'\fR stands for a control character),
+or better, \f(CW$^A\fR , where \f(CW\*(C`^\*(C'\fR is a caret (CIRCUMFLEX ACCENT),
+and \f(CW\*(C`A\*(C'\fR stands for any of the characters listed at the end of
+"OPERATOR DIFFERENCES" in perlebcdic.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Lists of lexical variable declarations (\f(CW\*(C`my($x, $y)\*(C'\fR) are now optimised
+down to a single op and are hence faster than before.
+.IP \(bu 4
+A new C preprocessor define \f(CW\*(C`NO_TAINT_SUPPORT\*(C'\fR was added that, if set,
+disables Perl's taint support altogether.  Using the \-T or \-t command
+line flags will cause a fatal error.  Beware that both core tests as
+well as many a CPAN distribution's tests will fail with this change.  On
+the upside, it provides a small performance benefit due to reduced
+branching.
+.Sp
+\&\fBDo not enable this unless you know exactly what you are getting yourself
+into.\fR
+.IP \(bu 4
+\&\f(CW\*(C`pack\*(C'\fR with constant arguments is now constant folded in most cases
+[perl #113470].
+.IP \(bu 4
+Speed up in regular expression matching against Unicode properties.  The
+largest gain is for \f(CW\*(C`\eX\*(C'\fR, the Unicode "extended grapheme cluster."  The
+gain for it is about 35% \- 40%.  Bracketed character classes, e.g.,
+\&\f(CW\*(C`[0\-9\ex{100}]\*(C'\fR containing code points above 255 are also now faster.
+.IP \(bu 4
+On platforms supporting it, several former macros are now implemented as static
+inline functions. This should speed things up slightly on non-GCC platforms.
+.IP \(bu 4
+The optimisation of hashes in boolean context has been extended to
+affect \f(CWscalar(%hash)\fR, \f(CW\*(C`%hash ? ... : ...\*(C'\fR, and \f(CW\*(C`sub { %hash || ... }\*(C'\fR.
+.IP \(bu 4
+Filetest operators manage the stack in a fractionally more efficient manner.
+.IP \(bu 4
+Globs used in a numeric context are now numified directly in most cases,
+rather than being numified via stringification.
+.IP \(bu 4
+The \f(CW\*(C`x\*(C'\fR repetition operator is now folded to a single constant at compile
+time if called in scalar context with constant operands and no parentheses
+around the left operand.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+Config::Perl::V version 0.16 has been added as a dual-lifed module.
+It provides structured data retrieval of \f(CW\*(C`perl \-V\*(C'\fR output including
+information only known to the \f(CW\*(C`perl\*(C'\fR binary and not available via Config.
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+For a complete list of updates, run:
+.PP
+.Vb 1
+\&  $ corelist \-\-diff 5.16.0 5.18.0
+.Ve
+.PP
+You can substitute your favorite version in place of \f(CW5.16.0\fR, too.
+.IP \(bu 4
+Archive::Extract has been upgraded to 0.68.
+.Sp
+Work around an edge case on Linux with Busybox's unzip.
+.IP \(bu 4
+Archive::Tar has been upgraded to 1.90.
+.Sp
+ptar now supports the \-T option as well as dashless options
+[rt.cpan.org #75473], [rt.cpan.org #75475].
+.Sp
+Auto-encode filenames marked as UTF\-8 [rt.cpan.org #75474].
+.Sp
+Don't use \f(CW\*(C`tell\*(C'\fR on IO::Zlib handles [rt.cpan.org #64339].
+.Sp
+Don't try to \f(CW\*(C`chown\*(C'\fR on symlinks.
+.IP \(bu 4
+autodie has been upgraded to 2.13.
+.Sp
+\&\f(CW\*(C`autodie\*(C'\fR now plays nicely with the 'open' pragma.
+.IP \(bu 4
+B has been upgraded to 1.42.
+.Sp
+The \f(CW\*(C`stashoff\*(C'\fR method of COPs has been added.   This provides access to an
+internal field added in perl 5.16 under threaded builds [perl #113034].
+.Sp
+\&\f(CW\*(C`B::COP::stashpv\*(C'\fR now supports UTF\-8 package names and embedded NULs.
+.Sp
+All \f(CW\*(C`CVf_*\*(C'\fR and \f(CW\*(C`GVf_*\*(C'\fR
+and more SV-related flag values are now provided as constants in the \f(CW\*(C`B::\*(C'\fR
+namespace and available for export.  The default export list has not changed.
+.Sp
+This makes the module work with the new pad API.
+.IP \(bu 4
+B::Concise has been upgraded to 0.95.
+.Sp
+The \f(CW\*(C`\-nobanner\*(C'\fR option has been fixed, and \f(CW\*(C`format\*(C'\fRs can now be dumped.
+When passed a sub name to dump, it will check also to see whether it
+is the name of a format.  If a sub and a format share the same name,
+it will dump both.
+.Sp
+This adds support for the new \f(CW\*(C`OpMAYBE_TRUEBOOL\*(C'\fR and \f(CW\*(C`OPpTRUEBOOL\*(C'\fR flags.
+.IP \(bu 4
+B::Debug has been upgraded to 1.18.
+.Sp
+This adds support (experimentally) for \f(CW\*(C`B::PADLIST\*(C'\fR, which was
+added in Perl 5.17.4.
+.IP \(bu 4
+B::Deparse has been upgraded to 1.20.
+.Sp
+Avoid warning when run under \f(CW\*(C`perl \-w\*(C'\fR.
+.Sp
+It now deparses
+loop controls with the correct precedence, and multiple statements in a
+\&\f(CW\*(C`format\*(C'\fR line are also now deparsed correctly.
+.Sp
+This release suppresses trailing semicolons in formats.
+.Sp
+This release adds stub deparsing for lexical subroutines.
+.Sp
+It no longer dies when deparsing \f(CW\*(C`sort\*(C'\fR without arguments.  It now
+correctly omits the comma for \f(CW\*(C`system $prog @args\*(C'\fR and \f(CWexec $prog
+@args\fR.
+.IP \(bu 4
+bignum, bigint and bigrat have been upgraded to 0.33.
+.Sp
+The overrides for \f(CW\*(C`hex\*(C'\fR and \f(CW\*(C`oct\*(C'\fR have been rewritten, eliminating
+several problems, and making one incompatible change:
+.RS 4
+.IP \(bu 4
+Formerly, whichever of \f(CW\*(C`use bigint\*(C'\fR or \f(CW\*(C`use bigrat\*(C'\fR was compiled later
+would take precedence over the other, causing \f(CW\*(C`hex\*(C'\fR and \f(CW\*(C`oct\*(C'\fR not to
+respect the other pragma when in scope.
+.IP \(bu 4
+Using any of these three pragmata would cause \f(CW\*(C`hex\*(C'\fR and \f(CW\*(C`oct\*(C'\fR anywhere
+else in the program to evaluate their arguments in list context and prevent
+them from inferring \f(CW$_\fR when called without arguments.
+.IP \(bu 4
+Using any of these three pragmata would make \f(CWoct("1234")\fR return 1234
+(for any number not beginning with 0) anywhere in the program.  Now "1234"
+is translated from octal to decimal, whether within the pragma's scope or
+not.
+.IP \(bu 4
+The global overrides that facilitate lexical use of \f(CW\*(C`hex\*(C'\fR and \f(CW\*(C`oct\*(C'\fR now
+respect any existing overrides that were in place before the new overrides
+were installed, falling back to them outside of the scope of \f(CW\*(C`use bignum\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`use bignum "hex"\*(C'\fR, \f(CW\*(C`use bignum "oct"\*(C'\fR and similar invocations for bigint
+and bigrat now export a \f(CW\*(C`hex\*(C'\fR or \f(CW\*(C`oct\*(C'\fR function, instead of providing a
+global override.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Carp has been upgraded to 1.29.
+.Sp
+Carp is no longer confused when \f(CW\*(C`caller\*(C'\fR returns undef for a package that
+has been deleted.
+.Sp
+The \f(CWlongmess()\fR and \f(CWshortmess()\fR functions are now documented.
+.IP \(bu 4
+CGI has been upgraded to 3.63.
+.Sp
+Unrecognized HTML escape sequences are now handled better, problematic
+trailing newlines are no longer inserted after <form> tags
+by \f(CWstartform()\fR or \f(CWstart_form()\fR, and bogus "Insecure Dependency"
+warnings appearing with some versions of perl are now worked around.
+.IP \(bu 4
+Class::Struct has been upgraded to 0.64.
+.Sp
+The constructor now respects overridden accessor methods [perl #29230].
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded to 2.060.
+.Sp
+The misuse of Perl's "magic" API has been fixed.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded to 2.060.
+.Sp
+Upgrade bundled zlib to version 1.2.7.
+.Sp
+Fix build failures on Irix, Solaris, and Win32, and also when building as C++
+[rt.cpan.org #69985], [rt.cpan.org #77030], [rt.cpan.org #75222].
+.Sp
+The misuse of Perl's "magic" API has been fixed.
+.Sp
+\&\f(CWcompress()\fR, \f(CWuncompress()\fR, \f(CWmemGzip()\fR and \f(CWmemGunzip()\fR have
+been speeded up by making parameter validation more efficient.
+.IP \(bu 4
+CPAN::Meta::Requirements has been upgraded to 2.122.
+.Sp
+Treat undef requirements to \f(CW\*(C`from_string_hash\*(C'\fR as 0 (with a warning).
+.Sp
+Added \f(CW\*(C`requirements_for_module\*(C'\fR method.
+.IP \(bu 4
+CPANPLUS has been upgraded to 0.9135.
+.Sp
+Allow adding \fIblib/script\fR to PATH.
+.Sp
+Save the history between invocations of the shell.
+.Sp
+Handle multiple \f(CW\*(C`makemakerargs\*(C'\fR and \f(CW\*(C`makeflags\*(C'\fR arguments better.
+.Sp
+This resolves issues with the SQLite source engine.
+.IP \(bu 4
+Data::Dumper has been upgraded to 2.145.
+.Sp
+It has been optimized to only build a seen-scalar hash as necessary,
+thereby speeding up serialization drastically.
+.Sp
+Additional tests were added in order to improve statement, branch, condition
+and subroutine coverage.  On the basis of the coverage analysis, some of the
+internals of Dumper.pm were refactored.  Almost all methods are now
+documented.
+.IP \(bu 4
+DB_File has been upgraded to 1.827.
+.Sp
+The main Perl module no longer uses the \f(CW"@_"\fR construct.
+.IP \(bu 4
+Devel::Peek has been upgraded to 1.11.
+.Sp
+This fixes compilation with C++ compilers and makes the module work with
+the new pad API.
+.IP \(bu 4
+Digest::MD5 has been upgraded to 2.52.
+.Sp
+Fix \f(CW\*(C`Digest::Perl::MD5\*(C'\fR OO fallback [rt.cpan.org #66634].
+.IP \(bu 4
+Digest::SHA has been upgraded to 5.84.
+.Sp
+This fixes a double-free bug, which might have caused vulnerabilities
+in some cases.
+.IP \(bu 4
+DynaLoader has been upgraded to 1.18.
+.Sp
+This is due to a minor code change in the XS for the VMS implementation.
+.Sp
+This fixes warnings about using \f(CW\*(C`CODE\*(C'\fR sections without an \f(CW\*(C`OUTPUT\*(C'\fR
+section.
+.IP \(bu 4
+Encode has been upgraded to 2.49.
+.Sp
+The Mac alias x\-mac-ce has been added, and various bugs have been fixed
+in Encode::Unicode, Encode::UTF7 and Encode::GSM0338.
+.IP \(bu 4
+Env has been upgraded to 1.04.
+.Sp
+Its SPLICE implementation no longer misbehaves in list context.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded to 0.280210.
+.Sp
+Manifest files are now correctly embedded for those versions of VC++ which
+make use of them. [perl #111782, #111798].
+.Sp
+A list of symbols to export can now be passed to \f(CWlink()\fR when on
+Windows, as on other OSes [perl #115100].
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded to 3.18.
+.Sp
+The generated C code now avoids unnecessarily incrementing
+\&\f(CW\*(C`PL_amagic_generation\*(C'\fR on Perl versions where it's done automatically
+(or on current Perl where the variable no longer exists).
+.Sp
+This avoids a bogus warning for initialised XSUB non-parameters [perl
+#112776].
+.IP \(bu 4
+File::Copy has been upgraded to 2.26.
+.Sp
+\&\f(CWcopy()\fR no longer zeros files when copying into the same directory,
+and also now fails (as it has long been documented to do) when attempting
+to copy a file over itself.
+.IP \(bu 4
+File::DosGlob has been upgraded to 1.10.
+.Sp
+The internal cache of file names that it keeps for each caller is now
+freed when that caller is freed.  This means
+\&\f(CW\*(C`use File::DosGlob \*(Aqglob\*(Aq; eval \*(Aqscalar <*>\*(Aq\*(C'\fR no longer leaks memory.
+.IP \(bu 4
+File::Fetch has been upgraded to 0.38.
+.Sp
+Added the 'file_default' option for URLs that do not have a file
+component.
+.Sp
+Use \f(CW\*(C`File::HomeDir\*(C'\fR when available, and provide \f(CW\*(C`PERL5_CPANPLUS_HOME\*(C'\fR to
+override the autodetection.
+.Sp
+Always re-fetch \fICHECKSUMS\fR if \f(CW\*(C`fetchdir\*(C'\fR is set.
+.IP \(bu 4
+File::Find has been upgraded to 1.23.
+.Sp
+This fixes inconsistent unixy path handling on VMS.
+.Sp
+Individual files may now appear in list of directories to be searched
+[perl #59750].
+.IP \(bu 4
+File::Glob has been upgraded to 1.20.
+.Sp
+File::Glob has had exactly the same fix as File::DosGlob.  Since it is
+what Perl's own \f(CW\*(C`glob\*(C'\fR operator itself uses (except on VMS), this means
+\&\f(CW\*(C`eval \*(Aqscalar <*>\*(Aq\*(C'\fR no longer leaks.
+.Sp
+A space-separated list of patterns return long lists of results no longer
+results in memory corruption or crashes.  This bug was introduced in
+Perl 5.16.0.  [perl #114984]
+.IP \(bu 4
+File::Spec::Unix has been upgraded to 3.40.
+.Sp
+\&\f(CW\*(C`abs2rel\*(C'\fR could produce incorrect results when given two relative paths or
+the root directory twice [perl #111510].
+.IP \(bu 4
+File::stat has been upgraded to 1.07.
+.Sp
+\&\f(CW\*(C`File::stat\*(C'\fR ignores the filetest pragma, and warns when used in
+combination therewith.  But it was not warning for \f(CW\*(C`\-r\*(C'\fR.  This has been
+fixed [perl #111640].
+.Sp
+\&\f(CW\*(C`\-p\*(C'\fR now works, and does not return false for pipes [perl #111638].
+.Sp
+Previously \f(CW\*(C`File::stat\*(C'\fR's overloaded \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR operators did not give
+the correct results for directories or executable files when running as
+root. They had been treating executable permissions for root just like for
+any other user, performing group membership tests \fIetc\fR for files not owned
+by root. They now follow the correct Unix behaviour \- for a directory they
+are always true, and for a file if any of the three execute permission bits
+are set then they report that root can execute the file. Perl's builtin
+\&\f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR operators have always been correct.
+.IP \(bu 4
+File::Temp has been upgraded to 0.23
+.Sp
+Fixes various bugs involving directory removal.  Defers unlinking tempfiles if
+the initial unlink fails, which fixes problems on NFS.
+.IP \(bu 4
+GDBM_File has been upgraded to 1.15.
+.Sp
+The undocumented optional fifth parameter to \f(CW\*(C`TIEHASH\*(C'\fR has been
+removed. This was intended to provide control of the callback used by
+\&\f(CW\*(C`gdbm*\*(C'\fR functions in case of fatal errors (such as filesystem problems),
+but did not work (and could never have worked). No code on CPAN even
+attempted to use it. The callback is now always the previous default,
+\&\f(CW\*(C`croak\*(C'\fR. Problems on some platforms with how the \f(CW\*(C`C\*(C'\fR \f(CW\*(C`croak\*(C'\fR function
+is called have also been resolved.
+.IP \(bu 4
+Hash::Util has been upgraded to 0.15.
+.Sp
+\&\f(CW\*(C`hash_unlocked\*(C'\fR and \f(CW\*(C`hashref_unlocked\*(C'\fR now returns true if the hash is
+unlocked, instead of always returning false [perl #112126].
+.Sp
+\&\f(CW\*(C`hash_unlocked\*(C'\fR, \f(CW\*(C`hashref_unlocked\*(C'\fR, \f(CW\*(C`lock_hash_recurse\*(C'\fR and
+\&\f(CW\*(C`unlock_hash_recurse\*(C'\fR are now exportable [perl #112126].
+.Sp
+Two new functions, \f(CW\*(C`hash_locked\*(C'\fR and \f(CW\*(C`hashref_locked\*(C'\fR, have been added.
+Oddly enough, these two functions were already exported, even though they
+did not exist [perl #112126].
+.IP \(bu 4
+HTTP::Tiny has been upgraded to 0.025.
+.Sp
+Add SSL verification features [github #6], [github #9].
+.Sp
+Include the final URL in the response hashref.
+.Sp
+Add \f(CW\*(C`local_address\*(C'\fR option.
+.Sp
+This improves SSL support.
+.IP \(bu 4
+IO has been upgraded to 1.28.
+.Sp
+\&\f(CWsync()\fR can now be called on read-only file handles [perl #64772].
+.Sp
+IO::Socket tries harder to cache or otherwise fetch socket
+information.
+.IP \(bu 4
+IPC::Cmd has been upgraded to 0.80.
+.Sp
+Use \f(CW\*(C`POSIX::_exit\*(C'\fR instead of \f(CW\*(C`exit\*(C'\fR in \f(CW\*(C`run_forked\*(C'\fR [rt.cpan.org #76901].
+.IP \(bu 4
+IPC::Open3 has been upgraded to 1.13.
+.Sp
+The \f(CWopen3()\fR function no longer uses \f(CWPOSIX::close()\fR to close file
+descriptors since that breaks the ref-counting of file descriptors done by
+PerlIO in cases where the file descriptors are shared by PerlIO streams,
+leading to attempts to close the file descriptors a second time when
+any such PerlIO streams are closed later on.
+.IP \(bu 4
+Locale::Codes has been upgraded to 3.25.
+.Sp
+It includes some new codes.
+.IP \(bu 4
+Memoize has been upgraded to 1.03.
+.Sp
+Fix the \f(CW\*(C`MERGE\*(C'\fR cache option.
+.IP \(bu 4
+Module::Build has been upgraded to 0.4003.
+.Sp
+Fixed bug where modules without \f(CW$VERSION\fR might have a version of '0' listed
+in 'provides' metadata, which will be rejected by PAUSE.
+.Sp
+Fixed bug in PodParser to allow numerals in module names.
+.Sp
+Fixed bug where giving arguments twice led to them becoming arrays, resulting
+in install paths like \fR\f(BIARRAY\fR\fI\|(0xdeadbeef)/lib/Foo.pm\fR.
+.Sp
+A minor bug fix allows markup to be used around the leading "Name" in
+a POD "abstract" line, and some documentation improvements have been made.
+.IP \(bu 4
+Module::CoreList has been upgraded to 2.90
+.Sp
+Version information is now stored as a delta, which greatly reduces the
+size of the \fICoreList.pm\fR file.
+.Sp
+This restores compatibility with older versions of perl and cleans up
+the corelist data for various modules.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded to 0.54.
+.Sp
+Fix use of \f(CW\*(C`requires\*(C'\fR on perls installed to a path with spaces.
+.Sp
+Various enhancements include the new use of Module::Metadata.
+.IP \(bu 4
+Module::Metadata has been upgraded to 1.000011.
+.Sp
+The creation of a Module::Metadata object for a typical module file has
+been sped up by about 40%, and some spurious warnings about \f(CW$VERSION\fRs
+have been suppressed.
+.IP \(bu 4
+Module::Pluggable has been upgraded to 4.7.
+.Sp
+Amongst other changes, triggers are now allowed on events, which gives
+a powerful way to modify behaviour.
+.IP \(bu 4
+Net::Ping has been upgraded to 2.41.
+.Sp
+This fixes some test failures on Windows.
+.IP \(bu 4
+Opcode has been upgraded to 1.25.
+.Sp
+Reflect the removal of the boolkeys opcode and the addition of the
+clonecv, introcv and padcv opcodes.
+.IP \(bu 4
+overload has been upgraded to 1.22.
+.Sp
+\&\f(CW\*(C`no overload\*(C'\fR now warns for invalid arguments, just like \f(CW\*(C`use overload\*(C'\fR.
+.IP \(bu 4
+PerlIO::encoding has been upgraded to 0.16.
+.Sp
+This is the module implementing the ":encoding(...)" I/O layer.  It no
+longer corrupts memory or crashes when the encoding back-end reallocates
+the buffer or gives it a typeglob or shared hash key scalar.
+.IP \(bu 4
+PerlIO::scalar has been upgraded to 0.16.
+.Sp
+The buffer scalar supplied may now only contain code points 0xFF or
+lower. [perl #109828]
+.IP \(bu 4
+Perl::OSType has been upgraded to 1.003.
+.Sp
+This fixes a bug detecting the VOS operating system.
+.IP \(bu 4
+Pod::Html has been upgraded to 1.18.
+.Sp
+The option \f(CW\*(C`\-\-libpods\*(C'\fR has been reinstated. It is deprecated, and its use
+does nothing other than issue a warning that it is no longer supported.
+.Sp
+Since the HTML files generated by pod2html claim to have a UTF\-8 charset,
+actually write the files out using UTF\-8 [perl #111446].
+.IP \(bu 4
+Pod::Simple has been upgraded to 3.28.
+.Sp
+Numerous improvements have been made, mostly to Pod::Simple::XHTML,
+which also has a compatibility change: the \f(CW\*(C`codes_in_verbatim\*(C'\fR option
+is now disabled by default.  See \fIcpan/Pod\-Simple/ChangeLog\fR for the
+full details.
+.IP \(bu 4
+re has been upgraded to 0.23
+.Sp
+Single character [class]es like \f(CW\*(C`/[s]/\*(C'\fR or \f(CW\*(C`/[s]/i\*(C'\fR are now optimized
+as if they did not have the brackets, i.e. \f(CW\*(C`/s/\*(C'\fR or \f(CW\*(C`/s/i\*(C'\fR.
+.Sp
+See note about \f(CW\*(C`op_comp\*(C'\fR in the "Internal Changes" section below.
+.IP \(bu 4
+Safe has been upgraded to 2.35.
+.Sp
+Fix interactions with \f(CW\*(C`Devel::Cover\*(C'\fR.
+.Sp
+Don't eval code under \f(CW\*(C`no strict\*(C'\fR.
+.IP \(bu 4
+Scalar::Util has been upgraded to version 1.27.
+.Sp
+Fix an overloading issue with \f(CW\*(C`sum\*(C'\fR.
+.Sp
+\&\f(CW\*(C`first\*(C'\fR and \f(CW\*(C`reduce\*(C'\fR now check the callback first (so \f(CW&first(1)\fR is
+disallowed).
+.Sp
+Fix \f(CW\*(C`tainted\*(C'\fR on magical values [rt.cpan.org #55763].
+.Sp
+Fix \f(CW\*(C`sum\*(C'\fR on previously magical values [rt.cpan.org #61118].
+.Sp
+Fix reading past the end of a fixed buffer [rt.cpan.org #72700].
+.IP \(bu 4
+Search::Dict has been upgraded to 1.07.
+.Sp
+No longer require \f(CW\*(C`stat\*(C'\fR on filehandles.
+.Sp
+Use \f(CW\*(C`fc\*(C'\fR for casefolding.
+.IP \(bu 4
+Socket has been upgraded to 2.009.
+.Sp
+Constants and functions required for IP multicast source group membership
+have been added.
+.Sp
+\&\f(CWunpack_sockaddr_in()\fR and \f(CWunpack_sockaddr_in6()\fR now return just the IP
+address in scalar context, and \f(CWinet_ntop()\fR now guards against incorrect
+length scalars being passed in.
+.Sp
+This fixes an uninitialized memory read.
+.IP \(bu 4
+Storable has been upgraded to 2.41.
+.Sp
+Modifying \f(CW$_[0]\fR within \f(CW\*(C`STORABLE_freeze\*(C'\fR no longer results in crashes
+[perl #112358].
+.Sp
+An object whose class implements \f(CW\*(C`STORABLE_attach\*(C'\fR is now thawed only once
+when there are multiple references to it in the structure being thawed
+[perl #111918].
+.Sp
+Restricted hashes were not always thawed correctly [perl #73972].
+.Sp
+Storable would croak when freezing a blessed REF object with a
+\&\f(CWSTORABLE_freeze()\fR method [perl #113880].
+.Sp
+It can now freeze and thaw vstrings correctly.  This causes a slight
+incompatible change in the storage format, so the format version has
+increased to 2.9.
+.Sp
+This contains various bugfixes, including compatibility fixes for older
+versions of Perl and vstring handling.
+.IP \(bu 4
+Sys::Syslog has been upgraded to 0.32.
+.Sp
+This contains several bug fixes relating to \f(CWgetservbyname()\fR,
+\&\f(CWsetlogsock()\fRand log levels in \f(CWsyslog()\fR, together with fixes for
+Windows, Haiku-OS and GNU/kFreeBSD.  See \fIcpan/Sys\-Syslog/Changes\fR
+for the full details.
+.IP \(bu 4
+Term::ANSIColor has been upgraded to 4.02.
+.Sp
+Add support for italics.
+.Sp
+Improve error handling.
+.IP \(bu 4
+Term::ReadLine has been upgraded to 1.10.  This fixes the
+use of the \fBcpan\fR and \fBcpanp\fR shells on Windows in the event that the current
+drive happens to contain a \fI\edev\etty\fR file.
+.IP \(bu 4
+Test::Harness has been upgraded to 3.26.
+.Sp
+Fix glob semantics on Win32 [rt.cpan.org #49732].
+.Sp
+Don't use \f(CW\*(C`Win32::GetShortPathName\*(C'\fR when calling perl [rt.cpan.org #47890].
+.Sp
+Ignore \-T when reading shebang [rt.cpan.org #64404].
+.Sp
+Handle the case where we don't know the wait status of the test more
+gracefully.
+.Sp
+Make the test summary 'ok' line overridable so that it can be changed to a
+plugin to make the output of prove idempotent.
+.Sp
+Don't run world-writable files.
+.IP \(bu 4
+Text::Tabs and Text::Wrap have been upgraded to
+2012.0818.  Support for Unicode combining characters has been added to them
+both.
+.IP \(bu 4
+threads::shared has been upgraded to 1.31.
+.Sp
+This adds the option to warn about or ignore attempts to clone structures
+that can't be cloned, as opposed to just unconditionally dying in
+that case.
+.Sp
+This adds support for dual-valued values as created by
+Scalar::Util::dualvar.
+.IP \(bu 4
+Tie::StdHandle has been upgraded to 4.3.
+.Sp
+\&\f(CW\*(C`READ\*(C'\fR now respects the offset argument to \f(CW\*(C`read\*(C'\fR [perl #112826].
+.IP \(bu 4
+Time::Local has been upgraded to 1.2300.
+.Sp
+Seconds values greater than 59 but less than 60 no longer cause
+\&\f(CWtimegm()\fR and \f(CWtimelocal()\fR to croak.
+.IP \(bu 4
+Unicode::UCD has been upgraded to 0.53.
+.Sp
+This adds a function \fBall_casefolds()\fR
+that returns all the casefolds.
+.IP \(bu 4
+Win32 has been upgraded to 0.47.
+.Sp
+New APIs have been added for getting and setting the current code page.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+.IP \(bu 4
+Version::Requirements has been removed from the core distribution.  It is
+available under a different name: CPAN::Meta::Requirements.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlcheat\fR
+.IX Subsection "perlcheat"
+.IP \(bu 4
+perlcheat has been reorganized, and a few new sections were added.
+.PP
+\fIperldata\fR
+.IX Subsection "perldata"
+.IP \(bu 4
+Now explicitly documents the behaviour of hash initializer lists that
+contain duplicate keys.
+.PP
+\fIperldiag\fR
+.IX Subsection "perldiag"
+.IP \(bu 4
+The explanation of symbolic references being prevented by "strict refs"
+now doesn't assume that the reader knows what symbolic references are.
+.PP
+\fIperlfaq\fR
+.IX Subsection "perlfaq"
+.IP \(bu 4
+perlfaq has been synchronized with version 5.0150040 from CPAN.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+The return value of \f(CW\*(C`pipe\*(C'\fR is now documented.
+.IP \(bu 4
+Clarified documentation of \f(CW\*(C`our\*(C'\fR.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Loop control verbs (\f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR and \f(CW\*(C`redo\*(C'\fR) have always
+had the same precedence as assignment operators, but this was not documented
+until now.
+.PP
+\fIDiagnostics\fR
+.IX Subsection "Diagnostics"
+.PP
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Unterminated delimiter for here document
+.Sp
+This message now occurs when a here document label has an initial quotation
+mark but the final quotation mark is missing.
+.Sp
+This replaces a bogus and misleading error message about not finding the label
+itself [perl #114104].
+.IP \(bu 4
+panic: child pseudo-process was never scheduled
+.Sp
+This error is thrown when a child pseudo-process in the ithreads implementation
+on Windows was not scheduled within the time period allowed and therefore was
+not able to initialize properly [perl #88840].
+.IP \(bu 4
+Group name must start with a non-digit word character in regex; marked by <\-\- HERE in m/%s/
+.Sp
+This error has been added for \f(CW\*(C`(?&0)\*(C'\fR, which is invalid.  It used to
+produce an incomprehensible error message [perl #101666].
+.IP \(bu 4
+Can't use an undefined value as a subroutine reference
+.Sp
+Calling an undefined value as a subroutine now produces this error message.
+It used to, but was accidentally disabled, first in Perl 5.004 for
+non-magical variables, and then in Perl v5.14 for magical (e.g., tied)
+variables.  It has now been restored.  In the mean time, undef was treated
+as an empty string [perl #113576].
+.IP \(bu 4
+Experimental "%s" subs not enabled
+.Sp
+To use lexical subs, you must first enable them:
+.Sp
+.Vb 3
+\&    no warnings \*(Aqexperimental::lexical_subs\*(Aq;
+\&    use feature \*(Aqlexical_subs\*(Aq;
+\&    my sub foo { ... }
+.Ve
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+\&'Strings with code points over 0xFF may not be mapped into in-memory file handles'
+.IP \(bu 4
+\&'%s' resolved to '\eo{%s}%d'
+.IP \(bu 4
+\&'Trailing white-space in a charnames alias definition is deprecated'
+.IP \(bu 4
+\&'A sequence of multiple spaces in a charnames alias definition is deprecated'
+.IP \(bu 4
+\&'Passing malformed UTF\-8 to "%s" is deprecated'
+.IP \(bu 4
+Subroutine "&%s" is not available
+.Sp
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical subroutine that is not currently
+available.  This can happen for one of two reasons.  First, the lexical
+subroutine may be declared in an outer anonymous subroutine that has not
+yet been created.  (Remember that named subs are created at compile time,
+while anonymous subs are created at run-time.)  For example,
+.Sp
+.Vb 1
+\&    sub { my sub a {...} sub f { \e&a } }
+.Ve
+.Sp
+At the time that f is created, it can't capture the current the "a" sub,
+since the anonymous subroutine hasn't been created yet.  Conversely, the
+following won't give a warning since the anonymous subroutine has by now
+been created and is live:
+.Sp
+.Vb 1
+\&    sub { my sub a {...} eval \*(Aqsub f { \e&a }\*(Aq }\->();
+.Ve
+.Sp
+The second situation is caused by an eval accessing a variable that has
+gone out of scope, for example,
+.Sp
+.Vb 5
+\&    sub f {
+\&        my sub a {...}
+\&        sub { eval \*(Aq\e&a\*(Aq }
+\&    }
+\&    f()\->();
+.Ve
+.Sp
+Here, when the '\e&a' in the eval is being compiled, f() is not currently
+being executed, so its &a is not available for capture.
+.IP \(bu 4
+"%s" subroutine &%s masks earlier declaration in same \f(CW%s\fR
+.Sp
+(W misc) A "my" or "state" subroutine has been redeclared in the
+current scope or statement, effectively eliminating all access to
+the previous instance.  This is almost always a typographical error.
+Note that the earlier subroutine will still exist until the end of
+the scope or until all closure references to it are destroyed.
+.IP \(bu 4
+The \f(CW%s\fR feature is experimental
+.Sp
+(S experimental) This warning is emitted if you enable an experimental
+feature via \f(CW\*(C`use feature\*(C'\fR.  Simply suppress the warning if you want
+to use the feature, but know that in doing so you are taking the risk
+of using an experimental feature which may change or be removed in a
+future Perl version:
+.Sp
+.Vb 2
+\&    no warnings "experimental::lexical_subs";
+\&    use feature "lexical_subs";
+.Ve
+.IP \(bu 4
+sleep(%u) too large
+.Sp
+(W overflow) You called \f(CW\*(C`sleep\*(C'\fR with a number that was larger than it can
+reliably handle and \f(CW\*(C`sleep\*(C'\fR probably slept for less time than requested.
+.IP \(bu 4
+Wide character in setenv
+.Sp
+Attempts to put wide characters into environment variables via \f(CW%ENV\fR now
+provoke this warning.
+.IP \(bu 4
+"Invalid negative number (%s) in chr"
+.Sp
+\&\f(CWchr()\fR now warns when passed a negative value [perl #83048].
+.IP \(bu 4
+"Integer overflow in srand"
+.Sp
+\&\f(CWsrand()\fR now warns when passed a value that doesn't fit in a \f(CW\*(C`UV\*(C'\fR (since the
+value will be truncated rather than overflowing) [perl #40605].
+.IP \(bu 4
+"\-i used with no filenames on the command line, reading from STDIN"
+.Sp
+Running perl with the \f(CW\*(C`\-i\*(C'\fR flag now warns if no input files are provided on
+the command line [perl #113410].
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+$* is no longer supported
+.Sp
+The warning that use of \f(CW$*\fR and \f(CW$#\fR is no longer supported is now
+generated for every location that references them.  Previously it would fail
+to be generated if another variable using the same typeglob was seen first
+(e.g. \f(CW\*(C`@*\*(C'\fR before \f(CW$*\fR), and would not be generated for the second and
+subsequent uses.  (It's hard to fix the failure to generate warnings at all
+without also generating them every time, and warning every time is
+consistent with the warnings that \f(CW$[\fR used to generate.)
+.IP \(bu 4
+The warnings for \f(CW\*(C`\eb{\*(C'\fR and \f(CW\*(C`\eB{\*(C'\fR were added.  They are a deprecation
+warning which should be turned off by that category.  One should not
+have to turn off regular regexp warnings as well to get rid of these.
+.IP \(bu 4
+Constant(%s): Call to &{$^H{%s}} did not return a defined value
+.Sp
+Constant overloading that returns \f(CW\*(C`undef\*(C'\fR results in this error message.
+For numeric constants, it used to say "Constant(undef)".  "undef" has been
+replaced with the number itself.
+.IP \(bu 4
+The error produced when a module cannot be loaded now includes a hint that
+the module may need to be installed: "Can't locate hopping.pm in \f(CW@INC\fR (you
+may need to install the hopping module) (@INC contains: ...)"
+.IP \(bu 4
+vector argument not supported with alpha versions
+.Sp
+This warning was not suppressible, even with \f(CW\*(C`no warnings\*(C'\fR.  Now it is
+suppressible, and has been moved from the "internal" category to the
+"printf" category.
+.IP \(bu 4
+\&\f(CW\*(C`Can\*(Aqt do {n,m} with n > m in regex; marked by <\-\- HERE in m/%s/\*(C'\fR
+.Sp
+This fatal error has been turned into a warning that reads:
+.Sp
+Quantifier {n,m} with n > m can't match in regex
+.Sp
+(W regexp) Minima should be less than or equal to maxima.  If you really want
+your regexp to match something 0 times, just put {0}.
+.IP \(bu 4
+The "Runaway prototype" warning that occurs in bizarre cases has been
+removed as being unhelpful and inconsistent.
+.IP \(bu 4
+The "Not a format reference" error has been removed, as the only case in
+which it could be triggered was a bug.
+.IP \(bu 4
+The "Unable to create sub named \f(CW%s\fR" error has been removed for the same
+reason.
+.IP \(bu 4
+The 'Can't use "my \f(CW%s\fR" in sort comparison' error has been downgraded to a
+warning, '"my \f(CW%s\fR" used in sort comparison' (with 'state' instead of 'my'
+for state variables).  In addition, the heuristics for guessing whether
+lexical \f(CW$a\fR or \f(CW$b\fR has been misused have been improved to generate fewer
+false positives.  Lexical \f(CW$a\fR and \f(CW$b\fR are no longer disallowed if they are
+outside the sort block.  Also, a named unary or list operator inside the
+sort block no longer causes the \f(CW$a\fR or \f(CW$b\fR to be ignored [perl #86136].
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\fIh2xs\fR
+.IX Subsection "h2xs"
+.IP \(bu 4
+\&\fIh2xs\fR no longer produces invalid code for empty defines.  [perl #20636]
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Added \f(CW\*(C`useversionedarchname\*(C'\fR option to Configure
+.Sp
+When set, it includes 'api_versionstring' in 'archname'. E.g.
+x86_64\-linux\-5.13.6\-thread\-multi.  It is unset by default.
+.Sp
+This feature was requested by Tim Bunce, who observed that
+\&\f(CW\*(C`INSTALL_BASE\*(C'\fR creates a library structure that does not
+differentiate by perl version.  Instead, it places architecture
+specific files in "$install_base/lib/perl5/$archname".  This makes
+it difficult to use a common \f(CW\*(C`INSTALL_BASE\*(C'\fR library path with
+multiple versions of perl.
+.Sp
+By setting \f(CW\*(C`\-Duseversionedarchname\*(C'\fR, the \f(CW$archname\fR will be
+distinct for architecture \fIand\fR API version, allowing mixed use of
+\&\f(CW\*(C`INSTALL_BASE\*(C'\fR.
+.IP \(bu 4
+Add a \f(CW\*(C`PERL_NO_INLINE_FUNCTIONS\*(C'\fR option
+.Sp
+If \f(CW\*(C`PERL_NO_INLINE_FUNCTIONS\*(C'\fR is defined, don't include "inline.h"
+.Sp
+This permits test code to include the perl headers for definitions without
+creating a link dependency on the perl library (which may not exist yet).
+.IP \(bu 4
+Configure will honour the external \f(CW\*(C`MAILDOMAIN\*(C'\fR environment variable, if set.
+.IP \(bu 4
+\&\f(CW\*(C`installman\*(C'\fR no longer ignores the silent option
+.IP \(bu 4
+Both \f(CW\*(C`META.yml\*(C'\fR and \f(CW\*(C`META.json\*(C'\fR files are now included in the distribution.
+.IP \(bu 4
+\&\fIConfigure\fR will now correctly detect \f(CWisblank()\fR when compiling with a C++
+compiler.
+.IP \(bu 4
+The pager detection in \fIConfigure\fR has been improved to allow responses which
+specify options after the program name, e.g. \fB/usr/bin/less \-R\fR, if the user
+accepts the default value.  This helps \fBperldoc\fR when handling ANSI escapes
+[perl #72156].
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+The test suite now has a section for tests that require very large amounts
+of memory.  These tests won't run by default; they can be enabled by
+setting the \f(CW\*(C`PERL_TEST_MEMORY\*(C'\fR environment variable to the number of
+gibibytes of memory that may be safely used.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP BeOS 4
+.IX Item "BeOS"
+BeOS was an operating system for personal computers developed by Be Inc,
+initially for their BeBox hardware. The OS Haiku was written as an open
+source replacement for/continuation of BeOS, and its perl port is current and
+actively maintained.
+.IP "UTS Global" 4
+.IX Item "UTS Global"
+Support code relating to UTS global has been removed.  UTS was a mainframe
+version of System V created by Amdahl, subsequently sold to UTS Global.  The
+port has not been touched since before Perl v5.8.0, and UTS Global is now
+defunct.
+.IP VM/ESA 4
+.IX Item "VM/ESA"
+Support for VM/ESA has been removed. The port was tested on 2.3.0, which
+IBM ended service on in March 2002. 2.4.0 ended service in June 2003, and
+was superseded by Z/VM. The current version of Z/VM is V6.2.0, and scheduled
+for end of service on 2015/04/30.
+.IP MPE/IX 4
+.IX Item "MPE/IX"
+Support for MPE/IX has been removed.
+.IP EPOC 4
+.IX Item "EPOC"
+Support code relating to EPOC has been removed.  EPOC was a family of
+operating systems developed by Psion for mobile devices.  It was the
+predecessor of Symbian.  The port was last updated in April 2002.
+.IP Rhapsody 4
+.IX Item "Rhapsody"
+Support for Rhapsody has been removed.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+\fIAIX\fR
+.IX Subsection "AIX"
+.PP
+Configure now always adds \f(CW\*(C`\-qlanglvl=extc99\*(C'\fR to the CC flags on AIX when
+using xlC.  This will make it easier to compile a number of XS-based modules
+that assume C99 [perl #113778].
+.PP
+\fIclang++\fR
+.IX Subsection "clang++"
+.PP
+There is now a workaround for a compiler bug that prevented compiling
+with clang++ since Perl v5.15.7 [perl #112786].
+.PP
+\fIC++\fR
+.IX Subsection "C++"
+.PP
+When compiling the Perl core as C++ (which is only semi-supported), the
+mathom functions are now compiled as \f(CW\*(C`extern "C"\*(C'\fR, to ensure proper
+binary compatibility.  (However, binary compatibility isn't generally
+guaranteed anyway in the situations where this would matter.)
+.PP
+\fIDarwin\fR
+.IX Subsection "Darwin"
+.PP
+Stop hardcoding an alignment on 8 byte boundaries to fix builds using
+\&\-Dusemorebits.
+.PP
+\fIHaiku\fR
+.IX Subsection "Haiku"
+.PP
+Perl should now work out of the box on Haiku R1 Alpha 4.
+.PP
+\fIMidnightBSD\fR
+.IX Subsection "MidnightBSD"
+.PP
+\&\f(CW\*(C`libc_r\*(C'\fR was removed from recent versions of MidnightBSD and older versions
+work better with \f(CW\*(C`pthread\*(C'\fR. Threading is now enabled using \f(CW\*(C`pthread\*(C'\fR which
+corrects build errors with threading enabled on 0.4\-CURRENT.
+.PP
+\fISolaris\fR
+.IX Subsection "Solaris"
+.PP
+In Configure, avoid running sed commands with flags not supported on Solaris.
+.PP
+\fIVMS\fR
+.IX Subsection "VMS"
+.IP \(bu 4
+Where possible, the case of filenames and command-line arguments is now
+preserved by enabling the CRTL features \f(CW\*(C`DECC$EFS_CASE_PRESERVE\*(C'\fR and
+\&\f(CW\*(C`DECC$ARGV_PARSE_STYLE\*(C'\fR at start-up time.  The latter only takes effect
+when extended parse is enabled in the process from which Perl is run.
+.IP \(bu 4
+The character set for Extended Filename Syntax (EFS) is now enabled by default
+on VMS.  Among other things, this provides better handling of dots in directory
+names, multiple dots in filenames, and spaces in filenames.  To obtain the old
+behavior, set the logical name \f(CW\*(C`DECC$EFS_CHARSET\*(C'\fR to \f(CW\*(C`DISABLE\*(C'\fR.
+.IP \(bu 4
+Fixed linking on builds configured with \f(CW\*(C`\-Dusemymalloc=y\*(C'\fR.
+.IP \(bu 4
+Experimental support for building Perl with the HP C++ compiler is available
+by configuring with \f(CW\*(C`\-Dusecxx\*(C'\fR.
+.IP \(bu 4
+All C header files from the top-level directory of the distribution are now
+installed on VMS, providing consistency with a long-standing practice on other
+platforms. Previously only a subset were installed, which broke non-core
+extension builds for extensions that depended on the missing include files.
+.IP \(bu 4
+Quotes are now removed from the command verb (but not the parameters) for
+commands spawned via \f(CW\*(C`system\*(C'\fR, backticks, or a piped \f(CW\*(C`open\*(C'\fR.  Previously,
+quotes on the verb were passed through to DCL, which would fail to recognize
+the command.  Also, if the verb is actually a path to an image or command
+procedure on an ODS\-5 volume, quoting it now allows the path to contain spaces.
+.IP \(bu 4
+The \fBa2p\fR build has been fixed for the HP C++ compiler on OpenVMS.
+.PP
+\fIWin32\fR
+.IX Subsection "Win32"
+.IP \(bu 4
+Perl can now be built using Microsoft's Visual C++ 2012 compiler by specifying
+CCTYPE=MSVC110 (or MSVC110FREE if you are using the free Express edition for
+Windows Desktop) in \fIwin32/Makefile\fR.
+.IP \(bu 4
+The option to build without \f(CW\*(C`USE_SOCKETS_AS_HANDLES\*(C'\fR has been removed.
+.IP \(bu 4
+Fixed a problem where perl could crash while cleaning up threads (including the
+main thread) in threaded debugging builds on Win32 and possibly other platforms
+[perl #114496].
+.IP \(bu 4
+A rare race condition that would lead to sleep taking more
+time than requested, and possibly even hanging, has been fixed [perl #33096].
+.IP \(bu 4
+\&\f(CW\*(C`link\*(C'\fR on Win32 now attempts to set \f(CW$!\fR to more appropriate values
+based on the Win32 API error code. [perl #112272]
+.Sp
+Perl no longer mangles the environment block, e.g. when launching a new
+sub-process, when the environment contains non-ASCII characters. Known
+problems still remain, however, when the environment contains characters
+outside of the current ANSI codepage (e.g. see the item about Unicode in
+\&\f(CW%ENV\fR in <http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod>).
+[perl #113536]
+.IP \(bu 4
+Building perl with some Windows compilers used to fail due to a problem
+with miniperl's \f(CW\*(C`glob\*(C'\fR operator (which uses the \f(CW\*(C`perlglob\*(C'\fR program)
+deleting the PATH environment variable [perl #113798].
+.IP \(bu 4
+A new makefile option, \f(CW\*(C`USE_64_BIT_INT\*(C'\fR, has been added to the Windows
+makefiles.  Set this to "define" when building a 32\-bit perl if you want
+it to use 64\-bit integers.
+.Sp
+Machine code size reductions, already made to the DLLs of XS modules in
+Perl v5.17.2, have now been extended to the perl DLL itself.
+.Sp
+Building with VC++ 6.0 was inadvertently broken in Perl v5.17.2 but has
+now been fixed again.
+.PP
+\fIWinCE\fR
+.IX Subsection "WinCE"
+.PP
+Building on WinCE is now possible once again, although more work is required
+to fully restore a clean build.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Synonyms for the misleadingly named \f(CWav_len()\fR have been created:
+\&\f(CWav_top_index()\fR and \f(CW\*(C`av_tindex\*(C'\fR.  All three of these return the
+number of the highest index in the array, not the number of elements it
+contains.
+.IP \(bu 4
+\&\fBSvUPGRADE()\fR is no longer an expression. Originally this macro (and its
+underlying function, \fBsv_upgrade()\fR) were documented as boolean, although
+in reality they always croaked on error and never returned false. In 2005
+the documentation was updated to specify a void return value, but
+\&\fBSvUPGRADE()\fR was left always returning 1 for backwards compatibility. This
+has now been removed, and \fBSvUPGRADE()\fR is now a statement with no return
+value.
+.Sp
+So this is now a syntax error:
+.Sp
+.Vb 1
+\&    if (!SvUPGRADE(sv)) { croak(...); }
+.Ve
+.Sp
+If you have code like that, simply replace it with
+.Sp
+.Vb 1
+\&    SvUPGRADE(sv);
+.Ve
+.Sp
+or to avoid compiler warnings with older perls, possibly
+.Sp
+.Vb 1
+\&    (void)SvUPGRADE(sv);
+.Ve
+.IP \(bu 4
+Perl has a new copy-on-write mechanism that allows any SvPOK scalar to be
+upgraded to a copy-on-write scalar.  A reference count on the string buffer
+is stored in the string buffer itself.  This feature is \fBnot enabled by
+default\fR.
+.Sp
+It can be enabled in a perl build by running \fIConfigure\fR with
+\&\fB\-Accflags=\-DPERL_NEW_COPY_ON_WRITE\fR, and we would encourage XS authors
+to try their code with such an enabled perl, and provide feedback.
+Unfortunately, there is not yet a good guide to updating XS code to cope
+with COW.  Until such a document is available, consult the perl5\-porters
+mailing list.
+.Sp
+It breaks a few XS modules by allowing copy-on-write scalars to go
+through code paths that never encountered them before.
+.IP \(bu 4
+Copy-on-write no longer uses the SvFAKE and SvREADONLY flags.  Hence,
+SvREADONLY indicates a true read-only SV.
+.Sp
+Use the SvIsCOW macro (as before) to identify a copy-on-write scalar.
+.IP \(bu 4
+\&\f(CW\*(C`PL_glob_index\*(C'\fR is gone.
+.IP \(bu 4
+The private Perl_croak_no_modify has had its context parameter removed.  It is
+now has a void prototype.  Users of the public API croak_no_modify remain
+unaffected.
+.IP \(bu 4
+Copy-on-write (shared hash key) scalars are no longer marked read-only.
+\&\f(CW\*(C`SvREADONLY\*(C'\fR returns false on such an SV, but \f(CW\*(C`SvIsCOW\*(C'\fR still returns
+true.
+.IP \(bu 4
+A new op type, \f(CW\*(C`OP_PADRANGE\*(C'\fR has been introduced.  The perl peephole
+optimiser will, where possible, substitute a single padrange op for a
+pushmark followed by one or more pad ops, and possibly also skipping list
+and nextstate ops.  In addition, the op can carry out the tasks associated
+with the RHS of a \f(CW\*(C`my(...) = @_\*(C'\fR assignment, so those ops may be optimised
+away too.
+.IP \(bu 4
+Case-insensitive matching inside a [bracketed] character class with a
+multi-character fold no longer excludes one of the possibilities in the
+circumstances that it used to. [perl #89774].
+.IP \(bu 4
+\&\f(CW\*(C`PL_formfeed\*(C'\fR has been removed.
+.IP \(bu 4
+The regular expression engine no longer reads one byte past the end of the
+target string.  While for all internally well-formed scalars this should
+never have been a problem, this change facilitates clever tricks with
+string buffers in CPAN modules.  [perl #73542]
+.IP \(bu 4
+Inside a BEGIN block, \f(CW\*(C`PL_compcv\*(C'\fR now points to the currently-compiling
+subroutine, rather than the BEGIN block itself.
+.IP \(bu 4
+\&\f(CW\*(C`mg_length\*(C'\fR has been deprecated.
+.IP \(bu 4
+\&\f(CW\*(C`sv_len\*(C'\fR now always returns a byte count and \f(CW\*(C`sv_len_utf8\*(C'\fR a character
+count.  Previously, \f(CW\*(C`sv_len\*(C'\fR and \f(CW\*(C`sv_len_utf8\*(C'\fR were both buggy and would
+sometimes returns bytes and sometimes characters.  \f(CW\*(C`sv_len_utf8\*(C'\fR no longer
+assumes that its argument is in UTF\-8.  Neither of these creates UTF\-8 caches
+for tied or overloaded values or for non-PVs any more.
+.IP \(bu 4
+\&\f(CW\*(C`sv_mortalcopy\*(C'\fR now copies string buffers of shared hash key scalars when
+called from XS modules [perl #79824].
+.IP \(bu 4
+The new \f(CW\*(C`RXf_MODIFIES_VARS\*(C'\fR flag can be set by custom regular expression
+engines to indicate that the execution of the regular expression may cause
+variables to be modified.  This lets \f(CW\*(C`s///\*(C'\fR know to skip certain
+optimisations.  Perl's own regular expression engine sets this flag for the
+special backtracking verbs that set \f(CW$REGMARK\fR and \f(CW$REGERROR\fR.
+.IP \(bu 4
+The APIs for accessing lexical pads have changed considerably.
+.Sp
+\&\f(CW\*(C`PADLIST\*(C'\fRs are now longer \f(CW\*(C`AV\*(C'\fRs, but their own type instead.
+\&\f(CW\*(C`PADLIST\*(C'\fRs now contain a \f(CW\*(C`PAD\*(C'\fR and a \f(CW\*(C`PADNAMELIST\*(C'\fR of \f(CW\*(C`PADNAME\*(C'\fRs,
+rather than \f(CW\*(C`AV\*(C'\fRs for the pad and the list of pad names.  \f(CW\*(C`PAD\*(C'\fRs,
+\&\f(CW\*(C`PADNAMELIST\*(C'\fRs, and \f(CW\*(C`PADNAME\*(C'\fRs are to be accessed as such through the
+newly added pad API instead of the plain \f(CW\*(C`AV\*(C'\fR and \f(CW\*(C`SV\*(C'\fR APIs.  See
+perlapi for details.
+.IP \(bu 4
+In the regex API, the numbered capture callbacks are passed an index
+indicating what match variable is being accessed. There are special
+index values for the \f(CW\*(C`$\`, $&, $&\*(C'\fR variables. Previously the same three
+values were used to retrieve \f(CW\*(C`${^PREMATCH}, ${^MATCH}, ${^POSTMATCH}\*(C'\fR
+too, but these have now been assigned three separate values. See
+"Numbered capture callbacks" in perlreapi.
+.IP \(bu 4
+\&\f(CW\*(C`PL_sawampersand\*(C'\fR was previously a boolean indicating that any of
+\&\f(CW\*(C`$\`, $&, $&\*(C'\fR had been seen; it now contains three one-bit flags
+indicating the presence of each of the variables individually.
+.IP \(bu 4
+The \f(CW\*(C`CV *\*(C'\fR typemap entry now supports \f(CW\*(C`&{}\*(C'\fR overloading and typeglobs,
+just like \f(CW\*(C`&{...}\*(C'\fR [perl #96872].
+.IP \(bu 4
+The \f(CW\*(C`SVf_AMAGIC\*(C'\fR flag to indicate overloading is now on the stash, not the
+object.  It is now set automatically whenever a method or \f(CW@ISA\fR changes, so
+its meaning has changed, too.  It now means "potentially overloaded".  When
+the overload table is calculated, the flag is automatically turned off if
+there is no overloading, so there should be no noticeable slowdown.
+.Sp
+The staleness of the overload tables is now checked when overload methods
+are invoked, rather than during \f(CW\*(C`bless\*(C'\fR.
+.Sp
+"A" magic is gone.  The changes to the handling of the \f(CW\*(C`SVf_AMAGIC\*(C'\fR flag
+eliminate the need for it.
+.Sp
+\&\f(CW\*(C`PL_amagic_generation\*(C'\fR has been removed as no longer necessary.  For XS
+modules, it is now a macro alias to \f(CW\*(C`PL_na\*(C'\fR.
+.Sp
+The fallback overload setting is now stored in a stash entry separate from
+overloadedness itself.
+.IP \(bu 4
+The character-processing code has been cleaned up in places.  The changes
+should be operationally invisible.
+.IP \(bu 4
+The \f(CW\*(C`study\*(C'\fR function was made a no-op in v5.16.  It was simply disabled via
+a \f(CW\*(C`return\*(C'\fR statement; the code was left in place.  Now the code supporting
+what \f(CW\*(C`study\*(C'\fR used to do has been removed.
+.IP \(bu 4
+Under threaded perls, there is no longer a separate PV allocated for every
+COP to store its package name (\f(CW\*(C`cop\->stashpv\*(C'\fR).  Instead, there is an
+offset (\f(CW\*(C`cop\->stashoff\*(C'\fR) into the new \f(CW\*(C`PL_stashpad\*(C'\fR array, which
+holds stash pointers.
+.IP \(bu 4
+In the pluggable regex API, the \f(CW\*(C`regexp_engine\*(C'\fR struct has acquired a new
+field \f(CW\*(C`op_comp\*(C'\fR, which is currently just for perl's internal use, and
+should be initialized to NULL by other regex plugin modules.
+.IP \(bu 4
+A new function \f(CW\*(C`alloccopstash\*(C'\fR has been added to the API, but is considered
+experimental.  See perlapi.
+.IP \(bu 4
+Perl used to implement get magic in a way that would sometimes hide bugs in
+code that could call \fBmg_get()\fR too many times on magical values.  This hiding of
+errors no longer occurs, so long-standing bugs may become visible now.  If
+you see magic-related errors in XS code, check to make sure it, together
+with the Perl API functions it uses, calls \fBmg_get()\fR only once on \fBSvGMAGICAL()\fR
+values.
+.IP \(bu 4
+OP allocation for CVs now uses a slab allocator.  This simplifies
+memory management for OPs allocated to a CV, so cleaning up after a
+compilation error is simpler and safer [perl #111462][perl #112312].
+.IP \(bu 4
+\&\f(CW\*(C`PERL_DEBUG_READONLY_OPS\*(C'\fR has been rewritten to work with the new slab
+allocator, allowing it to catch more violations than before.
+.IP \(bu 4
+The old slab allocator for ops, which was only enabled for \f(CW\*(C`PERL_IMPLICIT_SYS\*(C'\fR
+and \f(CW\*(C`PERL_DEBUG_READONLY_OPS\*(C'\fR, has been retired.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Here document terminators no longer require a terminating newline character when
+they occur at the end of a file.  This was already the case at the end of a
+string eval [perl #65838].
+.IP \(bu 4
+\&\f(CW\*(C`\-DPERL_GLOBAL_STRUCT\*(C'\fR builds now free the global struct \fBafter\fR
+they've finished using it.
+.IP \(bu 4
+A trailing '/' on a path in \f(CW@INC\fR will no longer have an additional '/'
+appended.
+.IP \(bu 4
+The \f(CW\*(C`:crlf\*(C'\fR layer now works when unread data doesn't fit into its own
+buffer. [perl #112244].
+.IP \(bu 4
+\&\f(CWungetc()\fR now handles UTF\-8 encoded data. [perl #116322].
+.IP \(bu 4
+A bug in the core typemap caused any C types that map to the T_BOOL core
+typemap entry to not be set, updated, or modified when the T_BOOL variable was
+used in an OUTPUT: section with an exception for RETVAL. T_BOOL in an INPUT:
+section was not affected. Using a T_BOOL return type for an XSUB (RETVAL)
+was not affected. A side effect of fixing this bug is, if a T_BOOL is specified
+in the OUTPUT: section (which previous did nothing to the SV), and a read only
+SV (literal) is passed to the XSUB, croaks like "Modification of a read-only
+value attempted" will happen. [perl #115796]
+.IP \(bu 4
+On many platforms, providing a directory name as the script name caused perl
+to do nothing and report success.  It should now universally report an error
+and exit nonzero. [perl #61362]
+.IP \(bu 4
+\&\f(CW\*(C`sort {undef} ...\*(C'\fR under fatal warnings no longer crashes.  It had
+begun crashing in Perl v5.16.
+.IP \(bu 4
+Stashes blessed into each other
+(\f(CW\*(C`bless \e%Foo::, \*(AqBar\*(Aq; bless \e%Bar::, \*(AqFoo\*(Aq\*(C'\fR) no longer result in double
+frees.  This bug started happening in Perl v5.16.
+.IP \(bu 4
+Numerous memory leaks have been fixed, mostly involving fatal warnings and
+syntax errors.
+.IP \(bu 4
+Some failed regular expression matches such as \f(CW\*(C`\*(Aqf\*(Aq =~ /../g\*(C'\fR were not
+resetting \f(CW\*(C`pos\*(C'\fR.  Also, "match-once" patterns (\f(CW\*(C`m?...?g\*(C'\fR) failed to reset
+it, too, when invoked a second time [perl #23180].
+.IP \(bu 4
+Several bugs involving \f(CW\*(C`local *ISA\*(C'\fR and \f(CW\*(C`local *Foo::\*(C'\fR causing stale
+MRO caches have been fixed.
+.IP \(bu 4
+Defining a subroutine when its typeglob has been aliased no longer results
+in stale method caches.  This bug was introduced in Perl v5.10.
+.IP \(bu 4
+Localising a typeglob containing a subroutine when the typeglob's package
+has been deleted from its parent stash no longer produces an error.  This
+bug was introduced in Perl v5.14.
+.IP \(bu 4
+Under some circumstances, \f(CW\*(C`local *method=...\*(C'\fR would fail to reset method
+caches upon scope exit.
+.IP \(bu 4
+\&\f(CW\*(C`/[.foo.]/\*(C'\fR is no longer an error, but produces a warning (as before) and
+is treated as \f(CW\*(C`/[.fo]/\*(C'\fR [perl #115818].
+.IP \(bu 4
+\&\f(CW\*(C`goto $tied_var\*(C'\fR now calls FETCH before deciding what type of goto
+(subroutine or label) this is.
+.IP \(bu 4
+Renaming packages through glob assignment
+(\f(CW\*(C`*Foo:: = *Bar::; *Bar:: = *Baz::\*(C'\fR) in combination with \f(CW\*(C`m?...?\*(C'\fR and
+\&\f(CW\*(C`reset\*(C'\fR no longer makes threaded builds crash.
+.IP \(bu 4
+A number of bugs related to assigning a list to hash have been fixed. Many of
+these involve lists with repeated keys like \f(CW\*(C`(1, 1, 1, 1)\*(C'\fR.
+.RS 4
+.IP \(bu 4
+The expression \f(CW\*(C`scalar(%h = (1, 1, 1, 1))\*(C'\fR now returns \f(CW4\fR, not \f(CW2\fR.
+.IP \(bu 4
+The return value of \f(CW\*(C`%h = (1, 1, 1)\*(C'\fR in list context was wrong. Previously
+this would return \f(CW\*(C`(1, undef, 1)\*(C'\fR, now it returns \f(CW\*(C`(1, undef)\*(C'\fR.
+.IP \(bu 4
+Perl now issues the same warning on \f(CW\*(C`($s, %h) = (1, {})\*(C'\fR as it does for
+\&\f(CW\*(C`(%h) = ({})\*(C'\fR, "Reference found where even-sized list expected".
+.IP \(bu 4
+A number of additional edge cases in list assignment to hashes were
+corrected. For more details see commit 23b7025ebc.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Attributes applied to lexical variables no longer leak memory.
+[perl #114764]
+.IP \(bu 4
+\&\f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`redo\*(C'\fR or \f(CW\*(C`require\*(C'\fR followed by a
+bareword (or version) and then an infix operator is no longer a syntax
+error.  It used to be for those infix operators (like \f(CW\*(C`+\*(C'\fR) that have a
+different meaning where a term is expected.  [perl #105924]
+.IP \(bu 4
+\&\f(CW\*(C`require a::b . 1\*(C'\fR and \f(CW\*(C`require a::b + 1\*(C'\fR no longer produce erroneous
+ambiguity warnings.  [perl #107002]
+.IP \(bu 4
+Class method calls are now allowed on any string, and not just strings
+beginning with an alphanumeric character.  [perl #105922]
+.IP \(bu 4
+An empty pattern created with \f(CW\*(C`qr//\*(C'\fR used in \f(CW\*(C`m///\*(C'\fR no longer triggers
+the "empty pattern reuses last pattern" behaviour.  [perl #96230]
+.IP \(bu 4
+Tying a hash during iteration no longer results in a memory leak.
+.IP \(bu 4
+Freeing a tied hash during iteration no longer results in a memory leak.
+.IP \(bu 4
+List assignment to a tied array or hash that dies on STORE no longer
+results in a memory leak.
+.IP \(bu 4
+If the hint hash (\f(CW\*(C`%^H\*(C'\fR) is tied, compile-time scope entry (which copies
+the hint hash) no longer leaks memory if FETCH dies.  [perl #107000]
+.IP \(bu 4
+Constant folding no longer inappropriately triggers the special
+\&\f(CW\*(C`split " "\*(C'\fR behaviour.  [perl #94490]
+.IP \(bu 4
+\&\f(CW\*(C`defined scalar(@array)\*(C'\fR, \f(CW\*(C`defined do { &foo }\*(C'\fR, and similar constructs
+now treat the argument to \f(CW\*(C`defined\*(C'\fR as a simple scalar.  [perl #97466]
+.IP \(bu 4
+Running a custom debugging that defines no \f(CW*DB::DB\fR glob or provides a
+subroutine stub for \f(CW&DB::DB\fR no longer results in a crash, but an error
+instead.  [perl #114990]
+.IP \(bu 4
+\&\f(CW\*(C`reset ""\*(C'\fR now matches its documentation.  \f(CW\*(C`reset\*(C'\fR only resets \f(CW\*(C`m?...?\*(C'\fR
+patterns when called with no argument.  An empty string for an argument now
+does nothing.  (It used to be treated as no argument.)  [perl #97958]
+.IP \(bu 4
+\&\f(CW\*(C`printf\*(C'\fR with an argument returning an empty list no longer reads past the
+end of the stack, resulting in erratic behaviour.  [perl #77094]
+.IP \(bu 4
+\&\f(CW\*(C`\-\-subname\*(C'\fR no longer produces erroneous ambiguity warnings.
+[perl #77240]
+.IP \(bu 4
+\&\f(CW\*(C`v10\*(C'\fR is now allowed as a label or package name.  This was inadvertently
+broken when v\-strings were added in Perl v5.6.  [perl #56880]
+.IP \(bu 4
+\&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`substr\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR could be confused by ties,
+overloading, references and typeglobs if the stringification of such
+changed the internal representation to or from UTF\-8.  [perl #114410]
+.IP \(bu 4
+utf8::encode now calls FETCH and STORE on tied variables.  utf8::decode now
+calls STORE (it was already calling FETCH).
+.IP \(bu 4
+\&\f(CW\*(C`$tied =~ s/$non_utf8/$utf8/\*(C'\fR no longer loops infinitely if the tied
+variable returns a Latin\-1 string, shared hash key scalar, or reference or
+typeglob that stringifies as ASCII or Latin\-1.  This was a regression from
+v5.12.
+.IP \(bu 4
+\&\f(CW\*(C`s///\*(C'\fR without /e is now better at detecting when it needs to forego
+certain optimisations, fixing some buggy cases:
+.RS 4
+.IP \(bu 4
+Match variables in certain constructs (\f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`..\*(C'\fR and others) in
+the replacement part; e.g., \f(CW\*(C`s/(.)/$l{$a||$1}/g\*(C'\fR.  [perl #26986]
+.IP \(bu 4
+Aliases to match variables in the replacement.
+.IP \(bu 4
+\&\f(CW$REGERROR\fR or \f(CW$REGMARK\fR in the replacement.  [perl #49190]
+.IP \(bu 4
+An empty pattern (\f(CW\*(C`s//$foo/\*(C'\fR) that causes the last-successful pattern to
+be used, when that pattern contains code blocks that modify the variables
+in the replacement.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+The taintedness of the replacement string no longer affects the taintedness
+of the return value of \f(CW\*(C`s///e\*(C'\fR.
+.IP \(bu 4
+The \f(CW$|\fR autoflush variable is created on-the-fly when needed.  If this
+happened (e.g., if it was mentioned in a module or eval) when the
+currently-selected filehandle was a typeglob with an empty IO slot, it used
+to crash.  [perl #115206]
+.IP \(bu 4
+Line numbers at the end of a string eval are no longer off by one.
+[perl #114658]
+.IP \(bu 4
+\&\f(CW@INC\fR filters (subroutines returned by subroutines in \f(CW@INC\fR) that set \f(CW$_\fR to a
+copy-on-write scalar no longer cause the parser to modify that string
+buffer in place.
+.IP \(bu 4
+\&\f(CWlength($object)\fR no longer returns the undefined value if the object has
+string overloading that returns undef.  [perl #115260]
+.IP \(bu 4
+The use of \f(CW\*(C`PL_stashcache\*(C'\fR, the stash name lookup cache for method calls, has
+been restored,
+.Sp
+Commit da6b625f78f5f133 in August 2011 inadvertently broke the code that looks
+up values in \f(CW\*(C`PL_stashcache\*(C'\fR. As it's only a cache, quite correctly everything
+carried on working without it.
+.IP \(bu 4
+The error "Can't localize through a reference" had disappeared in v5.16.0
+when \f(CW\*(C`local %$ref\*(C'\fR appeared on the last line of an lvalue subroutine.
+This error disappeared for \f(CW\*(C`\elocal %$ref\*(C'\fR in perl v5.8.1.  It has now
+been restored.
+.IP \(bu 4
+The parsing of here-docs has been improved significantly, fixing several
+parsing bugs and crashes and one memory leak, and correcting wrong
+subsequent line numbers under certain conditions.
+.IP \(bu 4
+Inside an eval, the error message for an unterminated here-doc no longer
+has a newline in the middle of it [perl #70836].
+.IP \(bu 4
+A substitution inside a substitution pattern (\f(CW\*(C`s/${s|||}//\*(C'\fR) no longer
+confuses the parser.
+.IP \(bu 4
+It may be an odd place to allow comments, but \f(CW\*(C`s//"" # hello/e\*(C'\fR has
+always worked, \fIunless\fR there happens to be a null character before the
+first #.  Now it works even in the presence of nulls.
+.IP \(bu 4
+An invalid range in \f(CW\*(C`tr///\*(C'\fR or \f(CW\*(C`y///\*(C'\fR no longer results in a memory leak.
+.IP \(bu 4
+String eval no longer treats a semicolon-delimited quote-like operator at
+the very end (\f(CW\*(C`eval \*(Aqq;;\*(Aq\*(C'\fR) as a syntax error.
+.IP \(bu 4
+\&\f(CW\*(C`warn {$_ => 1} + 1\*(C'\fR is no longer a syntax error.  The parser used to
+get confused with certain list operators followed by an anonymous hash and
+then an infix operator that shares its form with a unary operator.
+.IP \(bu 4
+\&\f(CW\*(C`(caller $n)[6]\*(C'\fR (which gives the text of the eval) used to return the
+actual parser buffer.  Modifying it could result in crashes.  Now it always
+returns a copy.  The string returned no longer has "\en;" tacked on to the
+end.  The returned text also includes here-doc bodies, which used to be
+omitted.
+.IP \(bu 4
+The UTF\-8 position cache is now reset when accessing magical variables, to
+avoid the string buffer and the UTF\-8 position cache getting out of sync
+[perl #114410].
+.IP \(bu 4
+Various cases of get magic being called twice for magical UTF\-8
+strings have been fixed.
+.IP \(bu 4
+This code (when not in the presence of \f(CW$&\fR etc)
+.Sp
+.Vb 2
+\&    $_ = \*(Aqx\*(Aq x 1_000_000;
+\&    1 while /(.)/;
+.Ve
+.Sp
+used to skip the buffer copy for performance reasons, but suffered from \f(CW$1\fR
+etc changing if the original string changed.  That's now been fixed.
+.IP \(bu 4
+Perl doesn't use PerlIO anymore to report out of memory messages, as PerlIO
+might attempt to allocate more memory.
+.IP \(bu 4
+In a regular expression, if something is quantified with \f(CW\*(C`{n,m}\*(C'\fR where
+\&\f(CW\*(C`n\ >\ m\*(C'\fR, it can't possibly match.  Previously this was a fatal
+error, but now is merely a warning (and that something won't match).
+[perl #82954].
+.IP \(bu 4
+It used to be possible for formats defined in subroutines that have
+subsequently been undefined and redefined to close over variables in the
+wrong pad (the newly-defined enclosing sub), resulting in crashes or
+"Bizarre copy" errors.
+.IP \(bu 4
+Redefinition of XSUBs at run time could produce warnings with the wrong
+line number.
+.IP \(bu 4
+The \f(CW%vd\fR sprintf format does not support version objects for alpha versions.
+It used to output the format itself (%vd) when passed an alpha version, and
+also emit an "Invalid conversion in printf" warning.  It no longer does,
+but produces the empty string in the output.  It also no longer leaks
+memory in this case.
+.IP \(bu 4
+\&\f(CW\*(C`$obj\->SUPER::method\*(C'\fR calls in the main package could fail if the
+SUPER package had already been accessed by other means.
+.IP \(bu 4
+Stash aliasing (\f(CW\*(C`*foo:: = *bar::\*(C'\fR) no longer causes SUPER calls to ignore
+changes to methods or \f(CW@ISA\fR or use the wrong package.
+.IP \(bu 4
+Method calls on packages whose names end in ::SUPER are no longer treated
+as SUPER method calls, resulting in failure to find the method.
+Furthermore, defining subroutines in such packages no longer causes them to
+be found by SUPER method calls on the containing package [perl #114924].
+.IP \(bu 4
+\&\f(CW\*(C`\ew\*(C'\fR now matches the code points U+200C (ZERO WIDTH NON-JOINER) and U+200D
+(ZERO WIDTH JOINER).  \f(CW\*(C`\eW\*(C'\fR no longer matches these.  This change is because
+Unicode corrected their definition of what \f(CW\*(C`\ew\*(C'\fR should match.
+.IP \(bu 4
+\&\f(CW\*(C`dump LABEL\*(C'\fR no longer leaks its label.
+.IP \(bu 4
+Constant folding no longer changes the behaviour of functions like \f(CWstat()\fR
+and \f(CWtruncate()\fR that can take either filenames or handles.
+\&\f(CW\*(C`stat 1 ? foo : bar\*(C'\fR nows treats its argument as a file name (since it is an
+arbitrary expression), rather than the handle "foo".
+.IP \(bu 4
+\&\f(CW\*(C`truncate FOO, $len\*(C'\fR no longer falls back to treating "FOO" as a file name if
+the filehandle has been deleted.  This was broken in Perl v5.16.0.
+.IP \(bu 4
+Subroutine redefinitions after sub-to-glob and glob-to-glob assignments no
+longer cause double frees or panic messages.
+.IP \(bu 4
+\&\f(CW\*(C`s///\*(C'\fR now turns vstrings into plain strings when performing a substitution,
+even if the resulting string is the same (\f(CW\*(C`s/a/a/\*(C'\fR).
+.IP \(bu 4
+Prototype mismatch warnings no longer erroneously treat constant subs as having
+no prototype when they actually have "".
+.IP \(bu 4
+Constant subroutines and forward declarations no longer prevent prototype
+mismatch warnings from omitting the sub name.
+.IP \(bu 4
+\&\f(CW\*(C`undef\*(C'\fR on a subroutine now clears call checkers.
+.IP \(bu 4
+The \f(CW\*(C`ref\*(C'\fR operator started leaking memory on blessed objects in Perl v5.16.0.
+This has been fixed [perl #114340].
+.IP \(bu 4
+\&\f(CW\*(C`use\*(C'\fR no longer tries to parse its arguments as a statement, making
+\&\f(CW\*(C`use constant { () };\*(C'\fR a syntax error [perl #114222].
+.IP \(bu 4
+On debugging builds, "uninitialized" warnings inside formats no longer cause
+assertion failures.
+.IP \(bu 4
+On debugging builds, subroutines nested inside formats no longer cause
+assertion failures [perl #78550].
+.IP \(bu 4
+Formats and \f(CW\*(C`use\*(C'\fR statements are now permitted inside formats.
+.IP \(bu 4
+\&\f(CW\*(C`print $x\*(C'\fR and \f(CW\*(C`sub { print $x }\->()\*(C'\fR now always produce the same output.
+It was possible for the latter to refuse to close over \f(CW$x\fR if the variable was
+not active; e.g., if it was defined outside a currently-running named
+subroutine.
+.IP \(bu 4
+Similarly, \f(CW\*(C`print $x\*(C'\fR and \f(CW\*(C`print eval \*(Aq$x\*(Aq\*(C'\fR now produce the same output.
+This also allows "my \f(CW$x\fR if 0" variables to be seen in the debugger [perl
+#114018].
+.IP \(bu 4
+Formats called recursively no longer stomp on their own lexical variables, but
+each recursive call has its own set of lexicals.
+.IP \(bu 4
+Attempting to free an active format or the handle associated with it no longer
+results in a crash.
+.IP \(bu 4
+Format parsing no longer gets confused by braces, semicolons and low-precedence
+operators.  It used to be possible to use braces as format delimiters (instead
+of \f(CW\*(C`=\*(C'\fR and \f(CW\*(C`.\*(C'\fR), but only sometimes.  Semicolons and low-precedence operators
+in format argument lines no longer confuse the parser into ignoring the line's
+return value.  In format argument lines, braces can now be used for anonymous
+hashes, instead of being treated always as \f(CW\*(C`do\*(C'\fR blocks.
+.IP \(bu 4
+Formats can now be nested inside code blocks in regular expressions and other
+quoted constructs (\f(CW\*(C`/(?{...})/\*(C'\fR and \f(CW\*(C`qq/${...}/\*(C'\fR) [perl #114040].
+.IP \(bu 4
+Formats are no longer created after compilation errors.
+.IP \(bu 4
+Under debugging builds, the \fB\-DA\fR command line option started crashing in Perl
+v5.16.0.  It has been fixed [perl #114368].
+.IP \(bu 4
+A potential deadlock scenario involving the premature termination of a pseudo\-
+forked child in a Windows build with ithreads enabled has been fixed.  This
+resolves the common problem of the \fIt/op/fork.t\fR test hanging on Windows [perl
+#88840].
+.IP \(bu 4
+The code which generates errors from \f(CWrequire()\fR could potentially read one or
+two bytes before the start of the filename for filenames less than three bytes
+long and ending \f(CW\*(C`/\e.p?\ez/\*(C'\fR.  This has now been fixed.  Note that it could
+never have happened with module names given to \f(CWuse()\fR or \f(CWrequire()\fR anyway.
+.IP \(bu 4
+The handling of pathnames of modules given to \f(CWrequire()\fR has been made
+thread-safe on VMS.
+.IP \(bu 4
+Non-blocking sockets have been fixed on VMS.
+.IP \(bu 4
+Pod can now be nested in code inside a quoted construct outside of a string
+eval.  This used to work only within string evals [perl #114040].
+.IP \(bu 4
+\&\f(CW\*(C`goto \*(Aq\*(Aq\*(C'\fR now looks for an empty label, producing the "goto must have
+label" error message, instead of exiting the program [perl #111794].
+.IP \(bu 4
+\&\f(CW\*(C`goto "\e0"\*(C'\fR now dies with "Can't find label" instead of "goto must have
+label".
+.IP \(bu 4
+The C function \f(CW\*(C`hv_store\*(C'\fR used to result in crashes when used on \f(CW\*(C`%^H\*(C'\fR
+[perl #111000].
+.IP \(bu 4
+A call checker attached to a closure prototype via \f(CW\*(C`cv_set_call_checker\*(C'\fR
+is now copied to closures cloned from it.  So \f(CW\*(C`cv_set_call_checker\*(C'\fR now
+works inside an attribute handler for a closure.
+.IP \(bu 4
+Writing to \f(CW$^N\fR used to have no effect.  Now it croaks with "Modification
+of a read-only value" by default, but that can be overridden by a custom
+regular expression engine, as with \f(CW$1\fR [perl #112184].
+.IP \(bu 4
+\&\f(CW\*(C`undef\*(C'\fR on a control character glob (\f(CW\*(C`undef *^H\*(C'\fR) no longer emits an
+erroneous warning about ambiguity [perl #112456].
+.IP \(bu 4
+For efficiency's sake, many operators and built-in functions return the
+same scalar each time.  Lvalue subroutines and subroutines in the CORE::
+namespace were allowing this implementation detail to leak through.
+\&\f(CW\*(C`print &CORE::uc("a"), &CORE::uc("b")\*(C'\fR used to print "BB".  The same thing
+would happen with an lvalue subroutine returning the return value of \f(CW\*(C`uc\*(C'\fR.
+Now the value is copied in such cases.
+.IP \(bu 4
+\&\f(CW\*(C`method {}\*(C'\fR syntax with an empty block or a block returning an empty list
+used to crash or use some random value left on the stack as its invocant.
+Now it produces an error.
+.IP \(bu 4
+\&\f(CW\*(C`vec\*(C'\fR now works with extremely large offsets (>2 GB) [perl #111730].
+.IP \(bu 4
+Changes to overload settings now take effect immediately, as do changes to
+inheritance that affect overloading.  They used to take effect only after
+\&\f(CW\*(C`bless\*(C'\fR.
+.Sp
+Objects that were created before a class had any overloading used to remain
+non-overloaded even if the class gained overloading through \f(CW\*(C`use overload\*(C'\fR
+or \f(CW@ISA\fR changes, and even after \f(CW\*(C`bless\*(C'\fR.  This has been fixed
+[perl #112708].
+.IP \(bu 4
+Classes with overloading can now inherit fallback values.
+.IP \(bu 4
+Overloading was not respecting a fallback value of 0 if there were
+overloaded objects on both sides of an assignment operator like \f(CW\*(C`+=\*(C'\fR
+[perl #111856].
+.IP \(bu 4
+\&\f(CW\*(C`pos\*(C'\fR now croaks with hash and array arguments, instead of producing
+erroneous warnings.
+.IP \(bu 4
+\&\f(CW\*(C`while(each %h)\*(C'\fR now implies \f(CW\*(C`while(defined($_ = each %h))\*(C'\fR, like
+\&\f(CW\*(C`readline\*(C'\fR and \f(CW\*(C`readdir\*(C'\fR.
+.IP \(bu 4
+Subs in the CORE:: namespace no longer crash after \f(CW\*(C`undef *_\*(C'\fR when called
+with no argument list (\f(CW&CORE::time\fR with no parentheses).
+.IP \(bu 4
+\&\f(CW\*(C`unpack\*(C'\fR no longer produces the "'/' must follow a numeric type in unpack"
+error when it is the data that are at fault [perl #60204].
+.IP \(bu 4
+\&\f(CW\*(C`join\*(C'\fR and \f(CW"@array"\fR now call FETCH only once on a tied \f(CW$"\fR
+[perl #8931].
+.IP \(bu 4
+Some subroutine calls generated by compiling core ops affected by a
+\&\f(CW\*(C`CORE::GLOBAL\*(C'\fR override had op checking performed twice.  The checking
+is always idempotent for pure Perl code, but the double checking can
+matter when custom call checkers are involved.
+.IP \(bu 4
+A race condition used to exist around fork that could cause a signal sent to
+the parent to be handled by both parent and child. Signals are now blocked
+briefly around fork to prevent this from happening [perl #82580].
+.IP \(bu 4
+The implementation of code blocks in regular expressions, such as \f(CW\*(C`(?{})\*(C'\fR
+and \f(CW\*(C`(??{})\*(C'\fR, has been heavily reworked to eliminate a whole slew of bugs.
+The main user-visible changes are:
+.RS 4
+.IP \(bu 4
+Code blocks within patterns are now parsed in the same pass as the
+surrounding code; in particular it is no longer necessary to have balanced
+braces: this now works:
+.Sp
+.Vb 1
+\&    /(?{  $x=\*(Aq{\*(Aq  })/
+.Ve
+.Sp
+This means that this error message is no longer generated:
+.Sp
+.Vb 1
+\&    Sequence (?{...}) not terminated or not {}\-balanced in regex
+.Ve
+.Sp
+but a new error may be seen:
+.Sp
+.Vb 1
+\&    Sequence (?{...}) not terminated with \*(Aq)\*(Aq
+.Ve
+.Sp
+In addition, literal code blocks within run-time patterns are only
+compiled once, at perl compile-time:
+.Sp
+.Vb 5
+\&    for my $p (...) {
+\&        # this \*(AqFOO\*(Aq block of code is compiled once,
+\&        # at the same time as the surrounding \*(Aqfor\*(Aq loop
+\&        /$p{(?{FOO;})/;
+\&    }
+.Ve
+.IP \(bu 4
+Lexical variables are now sane as regards scope, recursion and closure
+behavior. In particular, \f(CW\*(C`/A(?{B})C/\*(C'\fR behaves (from a closure viewpoint)
+exactly like \f(CW\*(C`/A/ && do { B } && /C/\*(C'\fR, while  \f(CW\*(C`qr/A(?{B})C/\*(C'\fR is like
+\&\f(CW\*(C`sub {/A/ && do { B } && /C/}\*(C'\fR. So this code now works how you might
+expect, creating three regexes that match 0, 1, and 2:
+.Sp
+.Vb 4
+\&    for my $i (0..2) {
+\&        push @r, qr/^(??{$i})$/;
+\&    }
+\&    "1" =~ $r[1]; # matches
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR pragma is now only required for code blocks defined
+at runtime; in particular in the following, the text of the \f(CW$r\fR pattern is
+still interpolated into the new pattern and recompiled, but the individual
+compiled code-blocks within \f(CW$r\fR are reused rather than being recompiled,
+and \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR isn't needed any more:
+.Sp
+.Vb 2
+\&    my $r = qr/abc(?{....})def/;
+\&    /xyz$r/;
+.Ve
+.IP \(bu 4
+Flow control operators no longer crash. Each code block runs in a new
+dynamic scope, so \f(CW\*(C`next\*(C'\fR etc. will not see
+any enclosing loops. \f(CW\*(C`return\*(C'\fR returns a value
+from the code block, not from any enclosing subroutine.
+.IP \(bu 4
+Perl normally caches the compilation of run-time patterns, and doesn't
+recompile if the pattern hasn't changed, but this is now disabled if
+required for the correct behavior of closures. For example:
+.Sp
+.Vb 5
+\&    my $code = \*(Aq(??{$x})\*(Aq;
+\&    for my $x (1..3) {
+\&        # recompile to see fresh value of $x each time
+\&        $x =~ /$code/;
+\&    }
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`/msix\*(C'\fR and \f(CW\*(C`(?msix)\*(C'\fR etc. flags are now propagated into the return
+value from \f(CW\*(C`(??{})\*(C'\fR; this now works:
+.Sp
+.Vb 1
+\&    "AB" =~ /a(??{\*(Aqb\*(Aq})/i;
+.Ve
+.IP \(bu 4
+Warnings and errors will appear to come from the surrounding code (or for
+run-time code blocks, from an eval) rather than from an \f(CW\*(C`re_eval\*(C'\fR:
+.Sp
+.Vb 2
+\&    use re \*(Aqeval\*(Aq; $c = \*(Aq(?{ warn "foo" })\*(Aq; /$c/;
+\&    /(?{ warn "foo" })/;
+.Ve
+.Sp
+formerly gave:
+.Sp
+.Vb 2
+\&    foo at (re_eval 1) line 1.
+\&    foo at (re_eval 2) line 1.
+.Ve
+.Sp
+and now gives:
+.Sp
+.Vb 2
+\&    foo at (eval 1) line 1.
+\&    foo at /some/prog line 2.
+.Ve
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Perl now can be recompiled to use any Unicode version.  In v5.16, it
+worked on Unicodes 6.0 and 6.1, but there were various bugs if earlier
+releases were used; the older the release the more problems.
+.IP \(bu 4
+\&\f(CW\*(C`vec\*(C'\fR no longer produces "uninitialized" warnings in lvalue context
+[perl #9423].
+.IP \(bu 4
+An optimization involving fixed strings in regular expressions could cause
+a severe performance penalty in edge cases.  This has been fixed
+[perl #76546].
+.IP \(bu 4
+In certain cases, including empty subpatterns within a regular expression (such
+as \f(CW\*(C`(?:)\*(C'\fR or \f(CW\*(C`(?:|)\*(C'\fR) could disable some optimizations. This has been fixed.
+.IP \(bu 4
+The "Can't find an opnumber" message that \f(CW\*(C`prototype\*(C'\fR produces when passed
+a string like "CORE::nonexistent_keyword" now passes UTF\-8 and embedded
+NULs through unchanged [perl #97478].
+.IP \(bu 4
+\&\f(CW\*(C`prototype\*(C'\fR now treats magical variables like \f(CW$1\fR the same way as
+non-magical variables when checking for the CORE:: prefix, instead of
+treating them as subroutine names.
+.IP \(bu 4
+Under threaded perls, a runtime code block in a regular expression could
+corrupt the package name stored in the op tree, resulting in bad reads
+in \f(CW\*(C`caller\*(C'\fR, and possibly crashes [perl #113060].
+.IP \(bu 4
+Referencing a closure prototype (\f(CW\*(C`\e&{$_[1]}\*(C'\fR in an attribute handler for a
+closure) no longer results in a copy of the subroutine (or assertion
+failures on debugging builds).
+.IP \(bu 4
+\&\f(CW\*(C`eval \*(Aq_\|_PACKAGE_\|_\*(Aq\*(C'\fR now returns the right answer on threaded builds if
+the current package has been assigned over (as in
+\&\f(CW\*(C`*ThisPackage:: = *ThatPackage::\*(C'\fR) [perl #78742].
+.IP \(bu 4
+If a package is deleted by code that it calls, it is possible for \f(CW\*(C`caller\*(C'\fR
+to see a stack frame belonging to that deleted package.  \f(CW\*(C`caller\*(C'\fR could
+crash if the stash's memory address was reused for a scalar and a
+substitution was performed on the same scalar [perl #113486].
+.IP \(bu 4
+\&\f(CW\*(C`UNIVERSAL::can\*(C'\fR no longer treats its first argument differently
+depending on whether it is a string or number internally.
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR with \f(CW\*(C`<&\*(C'\fR for the mode checks to see whether the third argument is
+a number, in determining whether to treat it as a file descriptor or a handle
+name.  Magical variables like \f(CW$1\fR were always failing the numeric check and
+being treated as handle names.
+.IP \(bu 4
+\&\f(CW\*(C`warn\*(C'\fR's handling of magical variables (\f(CW$1\fR, ties) has undergone several
+fixes.  \f(CW\*(C`FETCH\*(C'\fR is only called once now on a tied argument or a tied \f(CW$@\fR
+[perl #97480].  Tied variables returning objects that stringify as "" are
+no longer ignored.  A tied \f(CW$@\fR that happened to return a reference the
+\&\fIprevious\fR time it was used is no longer ignored.
+.IP \(bu 4
+\&\f(CW\*(C`warn ""\*(C'\fR now treats \f(CW$@\fR with a number in it the same way, regardless of
+whether it happened via \f(CW\*(C`$@=3\*(C'\fR or \f(CW\*(C`$@="3"\*(C'\fR.  It used to ignore the
+former.  Now it appends "\et...caught", as it has always done with
+\&\f(CW\*(C`$@="3"\*(C'\fR.
+.IP \(bu 4
+Numeric operators on magical variables (e.g., \f(CW\*(C`$1\ +\ 1\*(C'\fR) used to use
+floating point operations even where integer operations were more appropriate,
+resulting in loss of accuracy on 64\-bit platforms [perl #109542].
+.IP \(bu 4
+Unary negation no longer treats a string as a number if the string happened
+to be used as a number at some point.  So, if \f(CW$x\fR contains the string "dogs",
+\&\f(CW\*(C`\-$x\*(C'\fR returns "\-dogs" even if \f(CW\*(C`$y=0+$x\*(C'\fR has happened at some point.
+.IP \(bu 4
+In Perl v5.14, \f(CW\*(C`\-\*(Aq\-10\*(Aq\*(C'\fR was fixed to return "10", not "+10".  But magical
+variables (\f(CW$1\fR, ties) were not fixed till now [perl #57706].
+.IP \(bu 4
+Unary negation now treats strings consistently, regardless of the internal
+\&\f(CW\*(C`UTF8\*(C'\fR flag.
+.IP \(bu 4
+A regression introduced in Perl v5.16.0 involving
+\&\f(CW\*(C`tr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/\*(C'\fR has been fixed.  Only the first
+instance is supposed to be meaningful if a character appears more than
+once in \f(CW\*(C`\fR\f(CISEARCHLIST\fR\f(CW\*(C'\fR.  Under some circumstances, the final instance
+was overriding all earlier ones.  [perl #113584]
+.IP \(bu 4
+Regular expressions like \f(CW\*(C`qr/\e87/\*(C'\fR previously silently inserted a NUL
+character, thus matching as if it had been written \f(CW\*(C`qr/\e00087/\*(C'\fR.  Now it
+matches as if it had been written as \f(CW\*(C`qr/87/\*(C'\fR, with a message that the
+sequence \f(CW"\e8"\fR is unrecognized.
+.IP \(bu 4
+\&\f(CW\*(C`_\|_SUB_\|_\*(C'\fR now works in special blocks (\f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`END\*(C'\fR, etc.).
+.IP \(bu 4
+Thread creation on Windows could theoretically result in a crash if done
+inside a \f(CW\*(C`BEGIN\*(C'\fR block.  It still does not work properly, but it no longer
+crashes [perl #111610].
+.IP \(bu 4
+\&\f(CW\*(C`\e&{\*(Aq\*(Aq}\*(C'\fR (with the empty string) now autovivifies a stub like any other
+sub name, and no longer produces the "Unable to create sub" error
+[perl #94476].
+.IP \(bu 4
+A regression introduced in v5.14.0 has been fixed, in which some calls
+to the \f(CW\*(C`re\*(C'\fR module would clobber \f(CW$_\fR [perl #113750].
+.IP \(bu 4
+\&\f(CW\*(C`do FILE\*(C'\fR now always either sets or clears \f(CW$@\fR, even when the file can't be
+read. This ensures that testing \f(CW$@\fR first (as recommended by the
+documentation) always returns the correct result.
+.IP \(bu 4
+The array iterator used for the \f(CW\*(C`each @array\*(C'\fR construct is now correctly
+reset when \f(CW@array\fR is cleared [perl #75596]. This happens, for example, when
+the array is globally assigned to, as in \f(CW\*(C`@array = (...)\*(C'\fR, but not when its
+\&\fBvalues\fR are assigned to. In terms of the XS API, it means that \f(CWav_clear()\fR
+will now reset the iterator.
+.Sp
+This mirrors the behaviour of the hash iterator when the hash is cleared.
+.IP \(bu 4
+\&\f(CW\*(C`$class\->can\*(C'\fR, \f(CW\*(C`$class\->isa\*(C'\fR, and \f(CW\*(C`$class\->DOES\*(C'\fR now return
+correct results, regardless of whether that package referred to by \f(CW$class\fR
+exists [perl #47113].
+.IP \(bu 4
+Arriving signals no longer clear \f(CW$@\fR [perl #45173].
+.IP \(bu 4
+Allow \f(CW\*(C`my ()\*(C'\fR declarations with an empty variable list [perl #113554].
+.IP \(bu 4
+During parsing, subs declared after errors no longer leave stubs
+[perl #113712].
+.IP \(bu 4
+Closures containing no string evals no longer hang on to their containing
+subroutines, allowing variables closed over by outer subroutines to be
+freed when the outer sub is freed, even if the inner sub still exists
+[perl #89544].
+.IP \(bu 4
+Duplication of in-memory filehandles by opening with a "<&=" or ">&=" mode
+stopped working properly in v5.16.0.  It was causing the new handle to
+reference a different scalar variable.  This has been fixed [perl #113764].
+.IP \(bu 4
+\&\f(CW\*(C`qr//\*(C'\fR expressions no longer crash with custom regular expression engines
+that do not set \f(CW\*(C`offs\*(C'\fR at regular expression compilation time
+[perl #112962].
+.IP \(bu 4
+\&\f(CW\*(C`delete local\*(C'\fR no longer crashes with certain magical arrays and hashes
+[perl #112966].
+.IP \(bu 4
+\&\f(CW\*(C`local\*(C'\fR on elements of certain magical arrays and hashes used not to
+arrange to have the element deleted on scope exit, even if the element did
+not exist before \f(CW\*(C`local\*(C'\fR.
+.IP \(bu 4
+\&\f(CWscalar(write)\fR no longer returns multiple items [perl #73690].
+.IP \(bu 4
+String to floating point conversions no longer misparse certain strings under
+\&\f(CW\*(C`use locale\*(C'\fR [perl #109318].
+.IP \(bu 4
+\&\f(CW@INC\fR filters that die no longer leak memory [perl #92252].
+.IP \(bu 4
+The implementations of overloaded operations are now called in the correct
+context. This allows, among other things, being able to properly override
+\&\f(CW\*(C`<>\*(C'\fR [perl #47119].
+.IP \(bu 4
+Specifying only the \f(CW\*(C`fallback\*(C'\fR key when calling \f(CW\*(C`use overload\*(C'\fR now behaves
+properly [perl #113010].
+.IP \(bu 4
+\&\f(CW\*(C`sub foo { my $a = 0; while ($a) { ... } }\*(C'\fR and
+\&\f(CW\*(C`sub foo { while (0) { ... } }\*(C'\fR now return the same thing [perl #73618].
+.IP \(bu 4
+String negation now behaves the same under \f(CW\*(C`use integer;\*(C'\fR as it does
+without [perl #113012].
+.IP \(bu 4
+\&\f(CW\*(C`chr\*(C'\fR now returns the Unicode replacement character (U+FFFD) for \-1,
+regardless of the internal representation.  \-1 used to wrap if the argument
+was tied or a string internally.
+.IP \(bu 4
+Using a \f(CW\*(C`format\*(C'\fR after its enclosing sub was freed could crash as of
+perl v5.12.0, if the format referenced lexical variables from the outer sub.
+.IP \(bu 4
+Using a \f(CW\*(C`format\*(C'\fR after its enclosing sub was undefined could crash as of
+perl v5.10.0, if the format referenced lexical variables from the outer sub.
+.IP \(bu 4
+Using a \f(CW\*(C`format\*(C'\fR defined inside a closure, which format references
+lexical variables from outside, never really worked unless the \f(CW\*(C`write\*(C'\fR
+call was directly inside the closure.  In v5.10.0 it even started crashing.
+Now the copy of that closure nearest the top of the call stack is used to
+find those variables.
+.IP \(bu 4
+Formats that close over variables in special blocks no longer crash if a
+stub exists with the same name as the special block before the special
+block is compiled.
+.IP \(bu 4
+The parser no longer gets confused, treating \f(CW\*(C`eval foo ()\*(C'\fR as a syntax
+error if preceded by \f(CW\*(C`print;\*(C'\fR [perl #16249].
+.IP \(bu 4
+The return value of \f(CW\*(C`syscall\*(C'\fR is no longer truncated on 64\-bit platforms
+[perl #113980].
+.IP \(bu 4
+Constant folding no longer causes \f(CW\*(C`print 1 ? FOO : BAR\*(C'\fR to print to the
+FOO handle [perl #78064].
+.IP \(bu 4
+\&\f(CW\*(C`do subname\*(C'\fR now calls the named subroutine and uses the file name it
+returns, instead of opening a file named "subname".
+.IP \(bu 4
+Subroutines looked up by rv2cv check hooks (registered by XS modules) are
+now taken into consideration when determining whether \f(CW\*(C`foo bar\*(C'\fR should be
+the sub call \f(CWfoo(bar)\fR or the method call \f(CW\*(C`"bar"\->foo\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`CORE::foo::bar\*(C'\fR is no longer treated specially, allowing global overrides
+to be called directly via \f(CWCORE::GLOBAL::uc(...)\fR [perl #113016].
+.IP \(bu 4
+Calling an undefined sub whose typeglob has been undefined now produces the
+customary "Undefined subroutine called" error, instead of "Not a CODE
+reference".
+.IP \(bu 4
+Two bugs involving \f(CW@ISA\fR have been fixed.  \f(CW\*(C`*ISA = *glob_without_array\*(C'\fR and
+\&\f(CW\*(C`undef *ISA; @{*ISA}\*(C'\fR would prevent future modifications to \f(CW@ISA\fR from
+updating the internal caches used to look up methods.  The
+*glob_without_array case was a regression from Perl v5.12.
+.IP \(bu 4
+Regular expression optimisations sometimes caused \f(CW\*(C`$\*(C'\fR with \f(CW\*(C`/m\*(C'\fR to
+produce failed or incorrect matches [perl #114068].
+.IP \(bu 4
+\&\f(CW\*(C`_\|_SUB_\|_\*(C'\fR now works in a \f(CW\*(C`sort\*(C'\fR block when the enclosing subroutine is
+predeclared with \f(CW\*(C`sub foo;\*(C'\fR syntax [perl #113710].
+.IP \(bu 4
+Unicode properties only apply to Unicode code points, which leads to
+some subtleties when regular expressions are matched against
+above-Unicode code points.  There is a warning generated to draw your
+attention to this.  However, this warning was being generated
+inappropriately in some cases, such as when a program was being parsed.
+Non-Unicode matches such as \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`[:word:]\*(C'\fR should not generate the
+warning, as their definitions don't limit them to apply to only Unicode
+code points.  Now the message is only generated when matching against
+\&\f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR.  There remains a bug, [perl #114148], for the very
+few properties in Unicode that match just a single code point.  The
+warning is not generated if they are matched against an above-Unicode
+code point.
+.IP \(bu 4
+Uninitialized warnings mentioning hash elements would only mention the
+element name if it was not in the first bucket of the hash, due to an
+off-by-one error.
+.IP \(bu 4
+A regular expression optimizer bug could cause multiline "^" to behave
+incorrectly in the presence of line breaks, such that
+\&\f(CW\*(C`"/\en\en" =~ m#\eA(?:^/$)#im\*(C'\fR would not match [perl #115242].
+.IP \(bu 4
+Failed \f(CW\*(C`fork\*(C'\fR in list context no longer corrupts the stack.
+\&\f(CW\*(C`@a = (1, 2, fork, 3)\*(C'\fR used to gobble up the 2 and assign \f(CW\*(C`(1, undef, 3)\*(C'\fR
+if the \f(CW\*(C`fork\*(C'\fR call failed.
+.IP \(bu 4
+Numerous memory leaks have been fixed, mostly involving tied variables that
+die, regular expression character classes and code blocks, and syntax
+errors.
+.IP \(bu 4
+Assigning a regular expression (\f(CW\*(C`${qr//}\*(C'\fR) to a variable that happens to
+hold a floating point number no longer causes assertion failures on
+debugging builds.
+.IP \(bu 4
+Assigning a regular expression to a scalar containing a number no longer
+causes subsequent numification to produce random numbers.
+.IP \(bu 4
+Assigning a regular expression to a magic variable no longer wipes away the
+magic.  This was a regression from v5.10.
+.IP \(bu 4
+Assigning a regular expression to a blessed scalar no longer results in
+crashes.  This was also a regression from v5.10.
+.IP \(bu 4
+Regular expression can now be assigned to tied hash and array elements with
+flattening into strings.
+.IP \(bu 4
+Numifying a regular expression no longer results in an uninitialized
+warning.
+.IP \(bu 4
+Negative array indices no longer cause EXISTS methods of tied variables to
+be ignored.  This was a regression from v5.12.
+.IP \(bu 4
+Negative array indices no longer result in crashes on arrays tied to
+non-objects.
+.IP \(bu 4
+\&\f(CW\*(C`$byte_overload .= $utf8\*(C'\fR no longer results in doubly-encoded UTF\-8 if the
+left-hand scalar happened to have produced a UTF\-8 string the last time
+overloading was invoked.
+.IP \(bu 4
+\&\f(CW\*(C`goto &sub\*(C'\fR now uses the current value of \f(CW@_\fR, instead of using the array
+the subroutine was originally called with.  This means
+\&\f(CW\*(C`local @_ = (...); goto &sub\*(C'\fR now works [perl #43077].
+.IP \(bu 4
+If a debugger is invoked recursively, it no longer stomps on its own
+lexical variables.  Formerly under recursion all calls would share the same
+set of lexical variables [perl #115742].
+.IP \(bu 4
+\&\f(CW*_{ARRAY}\fR returned from a subroutine no longer spontaneously
+becomes empty.
+.IP \(bu 4
+When using \f(CW\*(C`say\*(C'\fR to print to a tied filehandle, the value of \f(CW\*(C`$\e\*(C'\fR is
+correctly localized, even if it was previously undef.  [perl #119927]
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+UTF8\-flagged strings in \f(CW%ENV\fR on HP-UX 11.00 are buggy
+.Sp
+The interaction of UTF8\-flagged strings and \f(CW%ENV\fR on HP-UX 11.00 is
+currently dodgy in some not-yet-fully-diagnosed way.  Expect test
+failures in \fIt/op/magic.t\fR, followed by unknown behavior when storing
+wide characters in the environment.
+.SH Obituary
+.IX Header "Obituary"
+Hojung Yoon (AMORETTE), 24, of Seoul, South Korea, went to his long rest
+on May 8, 2013 with llama figurine and autographed TIMTOADY card.  He
+was a brilliant young Perl 5 & 6 hacker and a devoted member of
+Seoul.pm.  He programmed Perl, talked Perl, ate Perl, and loved Perl.  We
+believe that he is still programming in Perl with his broken IBM laptop
+somewhere.  He will be missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl v5.18.0 represents approximately 12 months of development since
+Perl v5.16.0 and contains approximately 400,000 lines of changes across
+2,100 files from 113 authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl v5.18.0:
+.PP
+Aaron Crane, Aaron Trevena, Abhijit Menon-Sen, Adrian M. Enache, Alan
+Haggai Alavi, Alexandr Ciornii, Andrew Tam, Andy Dougherty, Anton Nikishaev,
+Aristotle Pagaltzis, Augustina Blair, Bob Ernst, Brad Gilbert, Breno G. de
+Oliveira, Brian Carlson, Brian Fraser, Charlie Gonzalez, Chip Salzenberg, Chris
+\&'BinGOs' Williams, Christian Hansen, Colin Kuskie, Craig A. Berry, Dagfinn
+Ilmari Mannsåker, Daniel Dragan, Daniel Perrett, Darin McBride, Dave Rolsky,
+David Golden, David Leadbeater, David Mitchell, David Nicol, Dominic
+Hargreaves, E. Choroba, Eric Brine, Evan Miller, Father Chrysostomos, Florian
+Ragwitz, François Perrad, George Greer, Goro Fuji, H.Merijn Brand, Herbert
+Breunung, Hugo van der Sanden, Igor Zaytsev, James E Keenan, Jan Dubois,
+Jasmine Ahuja, Jerry D. Hedden, Jess Robinson, Jesse Luehrs, Joaquin Ferrero,
+Joel Berger, John Goodyear, John Peacock, Karen Etheridge, Karl Williamson,
+Karthik Rajagopalan, Kent Fredric, Leon Timmermans, Lucas Holt, Lukas Mai,
+Marcus Holland-Moritz, Markus Jansen, Martin Hasch, Matthew Horsfall, Max
+Maischein, Michael G Schwern, Michael Schroeder, Moritz Lenz, Nicholas Clark,
+Niko Tyni, Oleg Nesterov, Patrik Hägglund, Paul Green, Paul Johnson, Paul
+Marquess, Peter Martini, Rafael Garcia-Suarez, Reini Urban, Renee Baecker,
+Rhesa Rozendaal, Ricardo Signes, Robin Barker, Ronald J. Kimball, Ruslan
+Zakirov, Salvador Fandiño, Sawyer X, Scott Lanning, Sergey Alekseev, Shawn M
+Moore, Shirakata Kentaro, Shlomi Fish, Sisyphus, Smylers, Steffen Müller,
+Steve Hay, Steve Peters, Steven Schubiger, Sullivan Beck, Sven Strickroth,
+Sébastien Aperghis-Tramoni, Thomas Sibley, Tobias Leich, Tom Wyant, Tony Cook,
+Vadim Konovalov, Vincent Pit, Volker Schatz, Walt Mankowski, Yves Orton,
+Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5181delta.1 b/upstream/mageia-cauldron/man1/perl5181delta.1
new file mode 100644
index 00000000..9e54b489
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5181delta.1
@@ -0,0 +1,221 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5181DELTA 1"
+.TH PERL5181DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5181delta \- what is new for perl v5.18.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.18.0 release and the 5.18.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.16.0, first read
+perl5180delta, which describes differences between 5.16.0 and 5.18.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.18.0
+If any exist, they are bugs, and we request that you submit a
+report.  See "Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+B has been upgraded from 1.42 to 1.42_01, fixing bugs related to lexical
+subroutines.
+.IP \(bu 4
+Digest::SHA has been upgraded from 5.84 to 5.84_01, fixing a crashing bug.
+[RT #118649]
+.IP \(bu 4
+Module::CoreList has been upgraded from 2.89 to 2.96.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP AIX 4
+.IX Item "AIX"
+A rarely-encountered configuration bug in the AIX hints file has been corrected.
+.IP MidnightBSD 4
+.IX Item "MidnightBSD"
+After a patch to the relevant hints file, perl should now build correctly on
+MidnightBSD 0.4\-RELEASE.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Starting in v5.18.0, a construct like \f(CW\*(C`/[#](?{})/x\*(C'\fR would have its \f(CW\*(C`#\*(C'\fR
+incorrectly interpreted as a comment.  The code block would be skipped,
+unparsed.  This has been corrected.
+.IP \(bu 4
+A number of memory leaks related to the new, experimental regexp bracketed
+character class feature have been plugged.
+.IP \(bu 4
+The OP allocation code now returns correctly aligned memory in all cases
+for \f(CW\*(C`struct pmop\*(C'\fR. Previously it could return memory only aligned to a
+4\-byte boundary, which is not correct for an ithreads build with 64 bit IVs
+on some 32 bit platforms. Notably, this caused the build to fail completely
+on sparc GNU/Linux. [RT #118055]
+.IP \(bu 4
+The debugger's \f(CW\*(C`man\*(C'\fR command been fixed. It was broken in the v5.18.0
+release. The \f(CW\*(C`man\*(C'\fR command is aliased to the names \f(CW\*(C`doc\*(C'\fR and \f(CW\*(C`perldoc\*(C'\fR \-
+all now work again.
+.IP \(bu 4
+\&\f(CW@_\fR is now correctly visible in the debugger, fixing a regression
+introduced in v5.18.0's debugger. [RT #118169]
+.IP \(bu 4
+Fixed a small number of regexp constructions that could either fail to
+match or crash perl when the string being matched against was
+allocated above the 2GB line on 32\-bit systems. [RT #118175]
+.IP \(bu 4
+Perl v5.16 inadvertently introduced a bug whereby calls to XSUBs that were
+not visible at compile time were treated as lvalues and could be assigned
+to, even when the subroutine was not an lvalue sub.  This has been fixed.
+[perl #117947]
+.IP \(bu 4
+Perl v5.18 inadvertently introduced a bug whereby dual-vars (i.e.
+variables with both string and numeric values, such as \f(CW$!\fR ) where the
+truthness of the variable was determined by the numeric value rather than
+the string value. [RT #118159]
+.IP \(bu 4
+Perl v5.18 inadvertently introduced a bug whereby interpolating mixed up\-
+and down-graded UTF\-8 strings in a regex could result in malformed UTF\-8
+in the pattern: specifically if a downgraded character in the range
+\&\f(CW\*(C`\ex80..\exff\*(C'\fR followed a UTF\-8 string, e.g.
+.Sp
+.Vb 3
+\&    utf8::upgrade(  my $u = "\ex{e5}");
+\&    utf8::downgrade(my $d = "\ex{e5}");
+\&    /$u$d/
+.Ve
+.Sp
+[perl #118297].
+.IP \(bu 4
+Lexical constants (\f(CW\*(C`my sub a() { 42 }\*(C'\fR) no longer crash when inlined.
+.IP \(bu 4
+Parameter prototypes attached to lexical subroutines are now respected when
+compiling sub calls without parentheses.  Previously, the prototypes were
+honoured only for calls \fIwith\fR parentheses. [RT #116735]
+.IP \(bu 4
+Syntax errors in lexical subroutines in combination with calls to the same
+subroutines no longer cause crashes at compile time.
+.IP \(bu 4
+The dtrace sub-entry probe now works with lexical subs, instead of
+crashing [perl #118305].
+.IP \(bu 4
+Undefining an inlinable lexical subroutine (\f(CWmy sub foo() { 42 } undef
+&foo\fR) would result in a crash if warnings were turned on.
+.IP \(bu 4
+Deep recursion warnings no longer crash lexical subroutines. [RT #118521]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.18.1 represents approximately 2 months of development since Perl 5.18.0
+and contains approximately 8,400 lines of changes across 60 files from 12
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.18.1:
+.PP
+Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, David
+Mitchell, Father Chrysostomos, Karl Williamson, Lukas Mai, Nicholas Clark,
+Peter Martini, Ricardo Signes, Shlomi Fish, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5182delta.1 b/upstream/mageia-cauldron/man1/perl5182delta.1
new file mode 100644
index 00000000..053dae16
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5182delta.1
@@ -0,0 +1,188 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5182DELTA 1"
+.TH PERL5182DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5182delta \- what is new for perl v5.18.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.18.1 release and the 5.18.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.18.0, first read
+perl5181delta, which describes differences between 5.18.0 and 5.18.1.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+B has been upgraded from version 1.42_01 to 1.42_02.
+.Sp
+The fix for [perl #118525] introduced a regression in the behaviour of
+\&\f(CW\*(C`B::CV::GV\*(C'\fR, changing the return value from a \f(CW\*(C`B::SPECIAL\*(C'\fR object on
+a \f(CW\*(C`NULL\*(C'\fR \f(CW\*(C`CvGV\*(C'\fR to \f(CW\*(C`undef\*(C'\fR.  \f(CW\*(C`B::CV::GV\*(C'\fR again returns a
+\&\f(CW\*(C`B::SPECIAL\*(C'\fR object in this case.  [perl #119413]
+.IP \(bu 4
+B::Concise has been upgraded from version 0.95 to 0.95_01.
+.Sp
+This fixes a bug in dumping unexpected SPECIALs.
+.IP \(bu 4
+English has been upgraded from version 1.06 to 1.06_01.  This fixes an
+error about the performance of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR, and \f(CW\*(C`$\*(Aq\*(C'\fR.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.20 to 1.20_01.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+.IP \(bu 4
+perlrepository has been restored with a pointer to more useful pages.
+.IP \(bu 4
+perlhack has been updated with the latest changes from blead.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Perl 5.18.1 introduced a regression along with a bugfix for lexical subs.
+Some B::SPECIAL results from B::CV::GV became undefs instead.  This broke
+Devel::Cover among other libraries.  This has been fixed.  [perl #119351]
+.IP \(bu 4
+Perl 5.18.0 introduced a regression whereby \f(CW\*(C`[:^ascii:]\*(C'\fR, if used in the same
+character class as other qualifiers, would fail to match characters in the
+Latin\-1 block.  This has been fixed.  [perl #120799]
+.IP \(bu 4
+Perl 5.18.0 introduced a regression when using \->SUPER::method with AUTOLOAD
+by looking up AUTOLOAD from the current package, rather than the current
+package’s superclass.  This has been fixed. [perl #120694]
+.IP \(bu 4
+Perl 5.18.0 introduced a regression whereby \f(CW\*(C`\-bareword\*(C'\fR was no longer
+permitted under the \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`integer\*(C'\fR pragmata when used together.  This
+has been fixed.  [perl #120288]
+.IP \(bu 4
+Previously PerlIOBase_dup didn't check if pushing the new layer succeeded
+before (optionally) setting the utf8 flag. This could cause
+segfaults-by-nullpointer.  This has been fixed.
+.IP \(bu 4
+A buffer overflow with very long identifiers has been fixed.
+.IP \(bu 4
+A regression from 5.16 in the handling of padranges led to assertion failures
+if a keyword plugin declined to handle the second ‘my’, but only after creating
+a padop.
+.Sp
+This affected, at least, Devel::CallParser under threaded builds.
+.Sp
+This has been fixed.
+.IP \(bu 4
+The construct \f(CW\*(C`$r=qr/.../; /$r/p\*(C'\fR is now handled properly, an issue which
+had been worsened by changes 5.18.0. [perl #118213]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.18.2 represents approximately 3 months of development since Perl
+5.18.1 and contains approximately 980 lines of changes across 39 files from 4
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.18.2:
+.PP
+Craig A. Berry, David Mitchell, Ricardo Signes, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5184delta.1 b/upstream/mageia-cauldron/man1/perl5184delta.1
new file mode 100644
index 00000000..3ac86281
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5184delta.1
@@ -0,0 +1,177 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5184DELTA 1"
+.TH PERL5184DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5184delta \- what is new for perl v5.18.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.18.4 release and the 5.18.2
+release.  \fBPlease note:\fR  This document ignores perl 5.18.3, a broken release
+which existed for a few hours only.
+.PP
+If you are upgrading from an earlier release such as 5.18.1, first read
+perl5182delta, which describes differences between 5.18.1 and 5.18.2.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Digest::SHA has been upgraded from 5.84_01 to 5.84_02.
+.IP \(bu 4
+perl5db.pl has been upgraded from version 1.39_10 to 1.39_11.
+.Sp
+This fixes a crash in tab completion, where available. [perl #120827]  Also,
+filehandle information is properly reset after a pager is run. [perl #121456]
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Introduced by
+[GH #12161] <https://github.com/Perl/perl5/issues/12161>, a memory
+leak on every call to \f(CW\*(C`system\*(C'\fR and backticks (\f(CW \`\` \fR), on most Win32 Perls
+starting from 5.18.0 has been fixed.  The memory leak only occurred if you
+enabled pseudo-fork in your build of Win32 Perl, and were running that build on
+Server 2003 R2 or newer OS.  The leak does not appear on WinXP SP3.
+[GH #13741] <https://github.com/Perl/perl5/issues/13741>
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The debugger now properly resets filehandles as needed. [perl #121456]
+.IP \(bu 4
+A segfault in Digest::SHA has been addressed.  [perl #121421]
+.IP \(bu 4
+perl can again be built with USE_64_BIT_INT, with Visual C 2003, 32 bit.
+[perl #120925]
+.IP \(bu 4
+A leading { (brace) in formats is properly parsed again. [perl #119973]
+.IP \(bu 4
+Copy the values used to perturb hash iteration when cloning an
+interpreter.  This was fairly harmless but caused \f(CW\*(C`valgrind\*(C'\fR to
+complain. [perl #121336]
+.IP \(bu 4
+In Perl v5.18 \f(CW\*(C`undef *_; goto &sub\*(C'\fR and \f(CW\*(C`local *_; goto &sub\*(C'\fR started
+crashing.  This has been fixed. [perl #119949]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.18.4 represents approximately 9 months of development since Perl 5.18.2
+and contains approximately 2,000 lines of changes across 53 files from 13
+authors.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.18.4:
+.PP
+Daniel Dragan, David Mitchell, Doug Bell, Father Chrysostomos, Hiroo Hayashi,
+James E Keenan, Karl Williamson, Mark Shelor, Ricardo Signes, Shlomi Fish,
+Smylers, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5200delta.1 b/upstream/mageia-cauldron/man1/perl5200delta.1
new file mode 100644
index 00000000..f4143974
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5200delta.1
@@ -0,0 +1,2722 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5200DELTA 1"
+.TH PERL5200DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5200delta \- what is new for perl v5.20.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.18.0 release and the
+5.20.0 release.
+.PP
+If you are upgrading from an earlier release such as 5.16.0, first read
+perl5180delta, which describes differences between 5.16.0 and 5.18.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Experimental Subroutine signatures"
+.IX Subsection "Experimental Subroutine signatures"
+Declarative syntax to unwrap argument list into lexical variables.
+\&\f(CW\*(C`sub foo ($a,$b) {...}\*(C'\fR checks the number of arguments and puts the
+arguments into lexical variables.  Signatures are not equivalent to
+the existing idiom of \f(CW\*(C`sub foo { my($a,$b) = @_; ... }\*(C'\fR.  Signatures
+are only available by enabling a non-default feature, and generate
+warnings about being experimental.  The syntactic clash with
+prototypes is managed by disabling the short prototype syntax when
+signatures are enabled.
+.PP
+See "Signatures" in perlsub for details.
+.ie n .SS """sub""s now take a ""prototype"" attribute"
+.el .SS "\f(CWsub\fPs now take a \f(CWprototype\fP attribute"
+.IX Subsection "subs now take a prototype attribute"
+When declaring or defining a \f(CW\*(C`sub\*(C'\fR, the prototype can now be specified inside
+of a \f(CW\*(C`prototype\*(C'\fR attribute instead of in parens following the name.
+.PP
+For example, \f(CW\*(C`sub foo($$){}\*(C'\fR could be rewritten as
+\&\f(CW\*(C`sub foo : prototype($$){}\*(C'\fR.
+.SS "More consistent prototype parsing"
+.IX Subsection "More consistent prototype parsing"
+Multiple semicolons in subroutine prototypes have long been tolerated and
+treated as a single semicolon.  There was one case where this did not
+happen.  A subroutine whose prototype begins with "*" or ";*" can affect
+whether a bareword is considered a method name or sub call.  This now
+applies also to ";;;*".
+.PP
+Whitespace has long been allowed inside subroutine prototypes, so
+\&\f(CW\*(C`sub( $ $ )\*(C'\fR is equivalent to \f(CWsub($$)\fR, but until now it was stripped
+when the subroutine was parsed.  Hence, whitespace was \fInot\fR allowed in
+prototypes set by \f(CW\*(C`Scalar::Util::set_prototype\*(C'\fR.  Now it is permitted,
+and the parser no longer strips whitespace.  This means
+\&\f(CW\*(C`prototype &mysub\*(C'\fR returns the original prototype, whitespace and all.
+.ie n .SS """rand"" now uses a consistent random number generator"
+.el .SS "\f(CWrand\fP now uses a consistent random number generator"
+.IX Subsection "rand now uses a consistent random number generator"
+Previously perl would use a platform specific random number generator, varying
+between the libc \fBrand()\fR, \fBrandom()\fR or \fBdrand48()\fR.
+.PP
+This meant that the quality of perl's random numbers would vary from platform
+to platform, from the 15 bits of \fBrand()\fR on Windows to 48\-bits on POSIX
+platforms such as Linux with \fBdrand48()\fR.
+.PP
+Perl now uses its own internal \fBdrand48()\fR implementation on all platforms.  This
+does not make perl's \f(CW\*(C`rand\*(C'\fR cryptographically secure.  [perl #115928]
+.SS "New slice syntax"
+.IX Subsection "New slice syntax"
+The new \f(CW%hash{...}\fR and \f(CW%array[...]\fR syntax returns a list of key/value (or
+index/value) pairs.  See "Key/Value Hash Slices" in perldata.
+.SS "Experimental Postfix Dereferencing"
+.IX Subsection "Experimental Postfix Dereferencing"
+When the \f(CW\*(C`postderef\*(C'\fR feature is in effect, the following syntactical
+equivalencies are set up:
+.PP
+.Vb 5
+\&  $sref\->$*;  # same as ${ $sref }  # interpolates
+\&  $aref\->@*;  # same as @{ $aref }  # interpolates
+\&  $href\->%*;  # same as %{ $href }
+\&  $cref\->&*;  # same as &{ $cref }
+\&  $gref\->**;  # same as *{ $gref }
+\&
+\&  $aref\->$#*; # same as $#{ $aref }
+\&
+\&  $gref\->*{ $slot }; # same as *{ $gref }{ $slot }
+\&
+\&  $aref\->@[ ... ];  # same as @$aref[ ... ]  # interpolates
+\&  $href\->@{ ... };  # same as @$href{ ... }  # interpolates
+\&  $aref\->%[ ... ];  # same as %$aref[ ... ]
+\&  $href\->%{ ... };  # same as %$href{ ... }
+.Ve
+.PP
+Those marked as interpolating only interpolate if the associated
+\&\f(CW\*(C`postderef_qq\*(C'\fR feature is also enabled.  This feature is \fBexperimental\fR and
+will trigger \f(CW\*(C`experimental::postderef\*(C'\fR\-category warnings when used, unless
+they are suppressed.
+.PP
+For more information, consult the Postfix Dereference Syntax section of
+perlref.
+.SS "Unicode 6.3 now supported"
+.IX Subsection "Unicode 6.3 now supported"
+Perl now supports and is shipped with Unicode 6.3 (though Perl may be
+recompiled with any previous Unicode release as well).  A detailed list of
+Unicode 6.3 changes is at <http://www.unicode.org/versions/Unicode6.3.0/>.
+.ie n .SS "New ""\ep{Unicode}"" regular expression pattern property"
+.el .SS "New \f(CW\ep{Unicode}\fP regular expression pattern property"
+.IX Subsection "New p{Unicode} regular expression pattern property"
+This is a synonym for \f(CW\*(C`\ep{Any}\*(C'\fR and matches the set of Unicode-defined
+code points 0 \- 0x10FFFF.
+.SS "Better 64\-bit support"
+.IX Subsection "Better 64-bit support"
+On 64\-bit platforms, the internal array functions now use 64\-bit offsets,
+allowing Perl arrays to hold more than 2**31 elements, if you have the memory
+available.
+.PP
+The regular expression engine now supports strings longer than 2**31
+characters.  [perl #112790, #116907]
+.PP
+The functions PerlIO_get_bufsiz, PerlIO_get_cnt, PerlIO_set_cnt and
+PerlIO_set_ptrcnt now have SSize_t, rather than int, return values and
+parameters.
+.ie n .SS """use\ locale"" now works on UTF\-8 locales"
+.el .SS "\f(CWuse\ locale\fP now works on UTF\-8 locales"
+.IX Subsection "use locale now works on UTF-8 locales"
+Until this release, only single-byte locales, such as the ISO 8859
+series were supported.  Now, the increasingly common multi-byte UTF\-8
+locales are also supported.  A UTF\-8 locale is one in which the
+character set is Unicode and the encoding is UTF\-8.  The POSIX
+\&\f(CW\*(C`LC_CTYPE\*(C'\fR category operations (case changing (like \f(CWlc()\fR, \f(CW"\eU"\fR),
+and character classification (\f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\eD\*(C'\fR, \f(CW\*(C`qr/[[:punct:]]/\*(C'\fR)) under
+such a locale work just as if not under locale, but instead as if under
+\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR, except taint rules are followed.
+Sorting remains by code point order in this release.  [perl #56820].
+.ie n .SS """use\ locale"" now compiles on systems without locale ability"
+.el .SS "\f(CWuse\ locale\fP now compiles on systems without locale ability"
+.IX Subsection "use locale now compiles on systems without locale ability"
+Previously doing this caused the program to not compile.  Within its
+scope the program behaves as if in the "C" locale.  Thus programs
+written for platforms that support locales can run on locale-less
+platforms without change.  Attempts to change the locale away from the
+"C" locale will, of course, fail.
+.SS "More locale initialization fallback options"
+.IX Subsection "More locale initialization fallback options"
+If there was an error with locales during Perl start-up, it immediately
+gave up and tried to use the \f(CW"C"\fR locale.  Now it first tries using
+other locales given by the environment variables, as detailed in
+"ENVIRONMENT" in perllocale.  For example, if \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LANG\*(C'\fR are
+both set, and using the \f(CW\*(C`LC_ALL\*(C'\fR locale fails, Perl will now try the
+\&\f(CW\*(C`LANG\*(C'\fR locale, and only if that fails, will it fall back to \f(CW"C"\fR.  On
+Windows machines, Perl will try, ahead of using \f(CW"C"\fR, the system
+default locale if all the locales given by environment variables fail.
+.ie n .SS """\-DL"" runtime option now added for tracing locale setting"
+.el .SS "\f(CW\-DL\fP runtime option now added for tracing locale setting"
+.IX Subsection "-DL runtime option now added for tracing locale setting"
+This is designed for Perl core developers to aid in field debugging bugs
+regarding locales.
+.SS "\fB\-F\fP now implies \fB\-a\fP and \fB\-a\fP implies \fB\-n\fP"
+.IX Subsection "-F now implies -a and -a implies -n"
+Previously \fB\-F\fR without \fB\-a\fR was a no-op, and \fB\-a\fR without \fB\-n\fR or \fB\-p\fR
+was a no-op, with this change, if you supply \fB\-F\fR then both \fB\-a\fR and \fB\-n\fR
+are implied and if you supply \fB\-a\fR then \fB\-n\fR is implied.
+.PP
+You can still use \fB\-p\fR for its extra behaviour. [perl #116190]
+.ie n .SS "$a and $b warnings exemption"
+.el .SS "\f(CW$a\fP and \f(CW$b\fP warnings exemption"
+.IX Subsection "$a and $b warnings exemption"
+The special variables \f(CW$a\fR and \f(CW$b\fR, used in \f(CW\*(C`sort\*(C'\fR, are now exempt from "used
+once" warnings, even where \f(CW\*(C`sort\*(C'\fR is not used.  This makes it easier for
+CPAN modules to provide functions using \f(CW$a\fR and \f(CW$b\fR for similar purposes.
+[perl #120462]
+.SH Security
+.IX Header "Security"
+.SS "Avoid possible read of \fBfree()\fPd memory during parsing"
+.IX Subsection "Avoid possible read of free()d memory during parsing"
+It was possible that \fBfree()\fRd memory could be read during parsing in the unusual
+circumstance of the Perl program ending with a heredoc and the last line of the
+file on disk having no terminating newline character.  This has now been fixed.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.ie n .SS """do"" can no longer be used to call subroutines"
+.el .SS "\f(CWdo\fP can no longer be used to call subroutines"
+.IX Subsection "do can no longer be used to call subroutines"
+The \f(CW\*(C`do SUBROUTINE(LIST)\*(C'\fR form has resulted in a deprecation warning
+since Perl v5.0.0, and is now a syntax error.
+.SS "Quote-like escape changes"
+.IX Subsection "Quote-like escape changes"
+The character after \f(CW\*(C`\ec\*(C'\fR in a double-quoted string ("..." or qq(...))
+or regular expression must now be a printable character and may not be
+\&\f(CW\*(C`{\*(C'\fR.
+.PP
+A literal \f(CW\*(C`{\*(C'\fR after \f(CW\*(C`\eB\*(C'\fR or \f(CW\*(C`\eb\*(C'\fR is now fatal.
+.PP
+These were deprecated in perl v5.14.0.
+.SS "Tainting happens under more circumstances; now conforms to documentation"
+.IX Subsection "Tainting happens under more circumstances; now conforms to documentation"
+This affects regular expression matching and changing the case of a
+string (\f(CW\*(C`lc\*(C'\fR, \f(CW"\eU"\fR, \fIetc\fR.) within the scope of \f(CW\*(C`use locale\*(C'\fR.
+The result is now tainted based on the operation, no matter what the
+contents of the string were, as the documentation (perlsec,
+"SECURITY" in perllocale) indicates it should.  Previously, for the case
+change operation, if the string contained no characters whose case
+change could be affected by the locale, the result would not be tainted.
+For example, the result of \f(CWuc()\fR on an empty string or one containing
+only above\-Latin1 code points is now tainted, and wasn't before.  This
+leads to more consistent tainting results.  Regular expression patterns
+taint their non-binary results (like \f(CW$&\fR, \f(CW$2\fR) if and only if the
+pattern contains elements whose matching depends on the current
+(potentially tainted) locale.  Like the case changing functions, the
+actual contents of the string being matched now do not matter, whereas
+formerly it did.  For example, if the pattern contains a \f(CW\*(C`\ew\*(C'\fR, the
+results will be tainted even if the match did not have to use that
+portion of the pattern to succeed or fail, because what a \f(CW\*(C`\ew\*(C'\fR matches
+depends on locale.  However, for example, a \f(CW\*(C`.\*(C'\fR in a pattern will not
+enable tainting, because the dot matches any single character, and what
+the current locale is doesn't change in any way what matches and what
+doesn't.
+.ie n .SS """\ep{}"", ""\eP{}"" matching has changed for non-Unicode code points."
+.el .SS "\f(CW\ep{}\fP, \f(CW\eP{}\fP matching has changed for non-Unicode code points."
+.IX Subsection "p{}, P{} matching has changed for non-Unicode code points."
+\&\f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR are defined by Unicode only on Unicode-defined code
+points (\f(CW\*(C`U+0000\*(C'\fR through \f(CW\*(C`U+10FFFF\*(C'\fR).  Their behavior on matching
+these legal Unicode code points is unchanged, but there are changes for
+code points \f(CW0x110000\fR and above.  Previously, Perl treated the result
+of matching \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR against these as \f(CW\*(C`undef\*(C'\fR, which
+translates into "false".  For \f(CW\*(C`\eP{}\*(C'\fR, this was then complemented into
+"true".  A warning was supposed to be raised when this happened.
+However, various optimizations could prevent the warning, and the
+results were often counter-intuitive, with both a match and its seeming
+complement being false.  Now all non-Unicode code points are treated as
+typical unassigned Unicode code points.  This generally is more
+Do-What-I-Mean.  A warning is raised only if the results are arguably
+different from a strict Unicode approach, and from what Perl used to do.
+Code that needs to be strictly Unicode compliant can make this warning
+fatal, and then Perl always raises the warning.
+.PP
+Details are in "Beyond Unicode code points" in perlunicode.
+.ie n .SS """\ep{All}"" has been expanded to match all possible code points"
+.el .SS "\f(CW\ep{All}\fP has been expanded to match all possible code points"
+.IX Subsection "p{All} has been expanded to match all possible code points"
+The Perl-defined regular expression pattern element \f(CW\*(C`\ep{All}\*(C'\fR, unused
+on CPAN, used to match just the Unicode code points; now it matches all
+possible code points; that is, it is equivalent to \f(CW\*(C`qr/./s\*(C'\fR.  Thus
+\&\f(CW\*(C`\ep{All}\*(C'\fR is no longer synonymous with \f(CW\*(C`\ep{Any}\*(C'\fR, which continues to
+match just the Unicode code points, as Unicode says it should.
+.SS "Data::Dumper's output may change"
+.IX Subsection "Data::Dumper's output may change"
+Depending on the data structures dumped and the settings set for
+Data::Dumper, the dumped output may have changed from previous
+versions.
+.PP
+If you have tests that depend on the exact output of Data::Dumper,
+they may fail.
+.PP
+To avoid this problem in your code, test against the data structure
+from evaluating the dumped structure, instead of the dump itself.
+.ie n .SS "Locale decimal point character no longer leaks outside of ""use\ locale"" scope"
+.el .SS "Locale decimal point character no longer leaks outside of \f(CWuse\ locale\fP scope"
+.IX Subsection "Locale decimal point character no longer leaks outside of use locale scope"
+This is actually a bug fix, but some code has come to rely on the bug
+being present, so this change is listed here.  The current locale that
+the program is running under is not supposed to be visible to Perl code
+except within the scope of a \f(CW\*(C`use\ locale\*(C'\fR.  However, until now under
+certain circumstances, the character used for a decimal point (often a
+comma) leaked outside the scope.  If your code is affected by this
+change, simply add a \f(CW\*(C`use\ locale\*(C'\fR.
+.SS "Assignments of Windows sockets error codes to $! now prefer \fIerrno.h\fP values over \fBWSAGetLastError()\fP values"
+.IX Subsection "Assignments of Windows sockets error codes to $! now prefer errno.h values over WSAGetLastError() values"
+In previous versions of Perl, Windows sockets error codes as returned by
+\&\fBWSAGetLastError()\fR were assigned to $!, and some constants such as ECONNABORTED,
+not in \fIerrno.h\fR in VC++ (or the various Windows ports of gcc) were defined to
+corresponding WSAE* values to allow $! to be tested against the E* constants
+exported by Errno and POSIX.
+.PP
+This worked well until VC++ 2010 and later, which introduced new E* constants
+with values > 100 into \fIerrno.h\fR, including some being (re)defined by perl
+to WSAE* values.  That caused problems when linking XS code against other
+libraries which used the original definitions of \fIerrno.h\fR constants.
+.PP
+To avoid this incompatibility, perl now maps WSAE* error codes to E* values
+where possible, and assigns those values to $!.  The E* constants exported by
+Errno and POSIX are updated to match so that testing $! against them,
+wherever previously possible, will continue to work as expected, and all E*
+constants found in \fIerrno.h\fR are now exported from those modules with their
+original \fIerrno.h\fR values.
+.PP
+In order to avoid breakage in existing Perl code which assigns WSAE* values to
+$!, perl now intercepts the assignment and performs the same mapping to E*
+values as it uses internally when assigning to $! itself.
+.PP
+However, one backwards-incompatibility remains: existing Perl code which
+compares $! against the numeric values of the WSAE* error codes that were
+previously assigned to $! will now be broken in those cases where a
+corresponding E* value has been assigned instead.  This is only an issue for
+those E* values < 100, which were always exported from Errno and
+POSIX with their original \fIerrno.h\fR values, and therefore could not be used
+for WSAE* error code tests (e.g. WSAEINVAL is 10022, but the corresponding
+EINVAL is 22).  (E* values > 100, if present, were redefined to WSAE*
+values anyway, so compatibility can be achieved by using the E* constants,
+which will work both before and after this change, albeit using different
+numeric values under the hood.)
+.ie n .SS "Functions ""PerlIO_vsprintf"" and ""PerlIO_sprintf"" have been removed"
+.el .SS "Functions \f(CWPerlIO_vsprintf\fP and \f(CWPerlIO_sprintf\fP have been removed"
+.IX Subsection "Functions PerlIO_vsprintf and PerlIO_sprintf have been removed"
+These two functions, undocumented, unused in CPAN, and problematic, have been
+removed.
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS "The ""/\eC/"" character class"
+.el .SS "The \f(CW/\eC/\fP character class"
+.IX Subsection "The /C/ character class"
+The \f(CW\*(C`/\eC/\*(C'\fR regular expression character class is deprecated. From perl
+5.22 onwards it will generate a warning, and from perl 5.24 onwards it
+will be a regular expression compiler error. If you need to examine the
+individual bytes that make up a UTF8\-encoded character, then use
+\&\f(CWutf8::encode()\fR on the string (or a copy) first.
+.SS "Literal control characters in variable names"
+.IX Subsection "Literal control characters in variable names"
+This deprecation affects things like $\ecT, where \ecT is a literal control (such
+as a \f(CW\*(C`NAK\*(C'\fR or \f(CW\*(C`NEGATIVE ACKNOWLEDGE\*(C'\fR character) in
+the source code.  Surprisingly, it appears that originally this was intended as
+the canonical way of accessing variables like $^T, with the caret form only
+being added as an alternative.
+.PP
+The literal control form is being deprecated for two main reasons.  It has what
+are likely unfixable bugs, such as $\ecI not working as an alias for $^I, and
+their usage not being portable to non-ASCII platforms: While $^T will work
+everywhere, \ecT is whitespace in EBCDIC.  [perl #119123]
+.ie n .SS "References to non-integers and non-positive integers in $/"
+.el .SS "References to non-integers and non-positive integers in \f(CW$/\fP"
+.IX Subsection "References to non-integers and non-positive integers in $/"
+Setting \f(CW$/\fR to a reference to zero or a reference to a negative integer is
+now deprecated, and will behave \fBexactly\fR as though it was set to \f(CW\*(C`undef\*(C'\fR.
+If you want slurp behavior set \f(CW$/\fR to \f(CW\*(C`undef\*(C'\fR explicitly.
+.PP
+Setting \f(CW$/\fR to a reference to a non integer is now forbidden and will
+throw an error. Perl has never documented what would happen in this
+context and while it used to behave the same as setting \f(CW$/\fR to
+the address of the references in future it may behave differently, so we
+have forbidden this usage.
+.SS "Character matching routines in POSIX"
+.IX Subsection "Character matching routines in POSIX"
+Use of any of these functions in the \f(CW\*(C`POSIX\*(C'\fR module is now deprecated:
+\&\f(CW\*(C`isalnum\*(C'\fR, \f(CW\*(C`isalpha\*(C'\fR, \f(CW\*(C`iscntrl\*(C'\fR, \f(CW\*(C`isdigit\*(C'\fR, \f(CW\*(C`isgraph\*(C'\fR, \f(CW\*(C`islower\*(C'\fR,
+\&\f(CW\*(C`isprint\*(C'\fR, \f(CW\*(C`ispunct\*(C'\fR, \f(CW\*(C`isspace\*(C'\fR, \f(CW\*(C`isupper\*(C'\fR, and \f(CW\*(C`isxdigit\*(C'\fR.  The
+functions are buggy and don't work on UTF\-8 encoded strings.  See their
+entries in POSIX for more information.
+.PP
+A warning is raised on the first call to any of them from each place in
+the code that they are called.  (Hence a repeated statement in a loop
+will raise just the one warning.)
+.SS "Interpreter-based threads are now \fIdiscouraged\fP"
+.IX Subsection "Interpreter-based threads are now discouraged"
+The "interpreter-based threads" provided by Perl are not the fast, lightweight
+system for multitasking that one might expect or hope for.  Threads are
+implemented in a way that make them easy to misuse.  Few people know how to
+use them correctly or will be able to provide help.
+.PP
+The use of interpreter-based threads in perl is officially
+discouraged.
+.SS "Module removals"
+.IX Subsection "Module removals"
+The following modules will be removed from the core distribution in a
+future release, and will at that time need to be installed from CPAN.
+Distributions on CPAN which require these modules will need to list them as
+prerequisites.
+.PP
+The core versions of these modules will now issue \f(CW"deprecated"\fR\-category
+warnings to alert you to this fact.  To silence these deprecation warnings,
+install the modules in question from CPAN.
+.PP
+Note that the planned removal of these modules from core does not reflect a
+judgement about the quality of the code and should not be taken as a suggestion
+that their use be halted.  Their disinclusion from core primarily hinges on
+their necessity to bootstrapping a fully functional, CPAN-capable Perl
+installation, not on concerns over their design.
+.IP "CGI and its associated CGI:: packages" 4
+.IX Item "CGI and its associated CGI:: packages"
+.PD 0
+.IP inc::latest 4
+.IX Item "inc::latest"
+.IP Package::Constants 4
+.IX Item "Package::Constants"
+.IP "Module::Build and its associated Module::Build:: packages" 4
+.IX Item "Module::Build and its associated Module::Build:: packages"
+.PD
+.SS "Utility removals"
+.IX Subsection "Utility removals"
+The following utilities will be removed from the core distribution in a
+future release, and will at that time need to be installed from CPAN.
+.IP find2perl 4
+.IX Item "find2perl"
+.PD 0
+.IP s2p 4
+.IX Item "s2p"
+.IP a2p 4
+.IX Item "a2p"
+.PD
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Perl has a new copy-on-write mechanism that avoids the need to copy the
+internal string buffer when assigning from one scalar to another. This
+makes copying large strings appear much faster.  Modifying one of the two
+(or more) strings after an assignment will force a copy internally. This
+makes it unnecessary to pass strings by reference for efficiency.
+.Sp
+This feature was already available in 5.18.0, but wasn't enabled by
+default. It is the default now, and so you no longer need build perl with
+the \fIConfigure\fR argument:
+.Sp
+.Vb 1
+\&    \-Accflags=\-DPERL_NEW_COPY_ON_WRITE
+.Ve
+.Sp
+It can be disabled (for now) in a perl build with:
+.Sp
+.Vb 1
+\&    \-Accflags=\-DPERL_NO_COW
+.Ve
+.Sp
+On some operating systems Perl can be compiled in such a way that any
+attempt to modify string buffers shared by multiple SVs will crash.  This
+way XS authors can test that their modules handle copy-on-write scalars
+correctly.  See "Copy on Write" in perlguts for detail.
+.IP \(bu 4
+Perl has an optimizer for regular expression patterns.  It analyzes the pattern
+to find things such as the minimum length a string has to be to match, etc.  It
+now better handles code points that are above the Latin1 range.
+.IP \(bu 4
+Executing a regex that contains the \f(CW\*(C`^\*(C'\fR anchor (or its variant under the
+\&\f(CW\*(C`/m\*(C'\fR flag) has been made much faster in several situations.
+.IP \(bu 4
+Precomputed hash values are now used in more places during method lookup.
+.IP \(bu 4
+Constant hash key lookups (\f(CW$hash{key}\fR as opposed to \f(CW$hash{$key}\fR) have
+long had the internal hash value computed at compile time, to speed up
+lookup.  This optimisation has only now been applied to hash slices as
+well.
+.IP \(bu 4
+Combined \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR operators in void context, like those
+generated for \f(CW\*(C`unless ($a && $b)\*(C'\fR and \f(CW\*(C`if ($a || b)\*(C'\fR now
+short circuit directly to the end of the statement. [perl #120128]
+.IP \(bu 4
+In certain situations, when \f(CW\*(C`return\*(C'\fR is the last statement in a subroutine's
+main scope, it will be optimized out. This means code like:
+.Sp
+.Vb 1
+\&  sub baz { return $cat; }
+.Ve
+.Sp
+will now behave like:
+.Sp
+.Vb 1
+\&  sub baz { $cat; }
+.Ve
+.Sp
+which is notably faster.
+.Sp
+[perl #120765]
+.IP \(bu 4
+Code like:
+.Sp
+.Vb 2
+\&  my $x; # or @x, %x
+\&  my $y;
+.Ve
+.Sp
+is now optimized to:
+.Sp
+.Vb 1
+\&  my ($x, $y);
+.Ve
+.Sp
+In combination with the padrange optimization introduced in
+v5.18.0, this means longer uninitialized my
+variable statements are also optimized, so:
+.Sp
+.Vb 1
+\&  my $x; my @y; my %z;
+.Ve
+.Sp
+becomes:
+.Sp
+.Vb 1
+\&  my ($x, @y, %z);
+.Ve
+.Sp
+[perl #121077]
+.IP \(bu 4
+The creation of certain sorts of lists, including array and hash slices, is now
+faster.
+.IP \(bu 4
+The optimisation for arrays indexed with a small constant integer is now
+applied for integers in the range \-128..127, rather than 0..255. This should
+speed up Perl code using expressions like \f(CW$x[\-1]\fR, at the expense of
+(presumably much rarer) code using expressions like \f(CW$x[200]\fR.
+.IP \(bu 4
+The first iteration over a large hash (using \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`each\*(C'\fR) is now
+faster. This is achieved by preallocating the hash's internal iterator
+state, rather than lazily creating it when the hash is first iterated. (For
+small hashes, the iterator is still created only when first needed. The
+assumption is that small hashes are more likely to be used as objects, and
+therefore never allocated. For large hashes, that's less likely to be true,
+and the cost of allocating the iterator is swamped by the cost of allocating
+space for the hash itself.)
+.IP \(bu 4
+When doing a global regex match on a string that came from the \f(CW\*(C`readline\*(C'\fR
+or \f(CW\*(C`<>\*(C'\fR operator, the data is no longer copied unnecessarily.
+[perl #121259]
+.IP \(bu 4
+Dereferencing (as in \f(CW\*(C`$obj\->[0]\*(C'\fR or \f(CW\*(C`$obj\->{k}\*(C'\fR) is now faster
+when \f(CW$obj\fR is an instance of a class that has overloaded methods, but
+doesn't overload any of the dereferencing methods \f(CW\*(C`@{}\*(C'\fR, \f(CW\*(C`%{}\*(C'\fR, and so on.
+.IP \(bu 4
+Perl's optimiser no longer skips optimising code that follows certain
+\&\f(CW\*(C`eval {}\*(C'\fR expressions (including those with an apparent infinite loop).
+.IP \(bu 4
+The implementation now does a better job of avoiding meaningless work at
+runtime. Internal effect-free "null" operations (created as a side-effect of
+parsing Perl programs) are normally deleted during compilation. That
+deletion is now applied in some situations that weren't previously handled.
+.IP \(bu 4
+Perl now does less disk I/O when dealing with Unicode properties that cover
+up to three ranges of consecutive code points.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+experimental 0.007 has been added to the Perl core.
+.IP \(bu 4
+IO::Socket::IP 0.29 has been added to the Perl core.
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 1.90 to 1.96.
+.IP \(bu 4
+arybase has been upgraded from version 0.06 to 0.07.
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 0.94 to 0.96.
+.IP \(bu 4
+attributes has been upgraded from version 0.21 to 0.22.
+.IP \(bu 4
+autodie has been upgraded from version 2.13 to 2.23.
+.IP \(bu 4
+AutoLoader has been upgraded from version 5.73 to 5.74.
+.IP \(bu 4
+autouse has been upgraded from version 1.07 to 1.08.
+.IP \(bu 4
+B has been upgraded from version 1.42 to 1.48.
+.IP \(bu 4
+B::Concise has been upgraded from version 0.95 to 0.992.
+.IP \(bu 4
+B::Debug has been upgraded from version 1.18 to 1.19.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.20 to 1.26.
+.IP \(bu 4
+base has been upgraded from version 2.18 to 2.22.
+.IP \(bu 4
+Benchmark has been upgraded from version 1.15 to 1.18.
+.IP \(bu 4
+bignum has been upgraded from version 0.33 to 0.37.
+.IP \(bu 4
+Carp has been upgraded from version 1.29 to 1.3301.
+.IP \(bu 4
+CGI has been upgraded from version 3.63 to 3.65.
+NOTE: CGI is deprecated and may be removed from a future version of Perl.
+.IP \(bu 4
+charnames has been upgraded from version 1.36 to 1.40.
+.IP \(bu 4
+Class::Struct has been upgraded from version 0.64 to 0.65.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.060 to 2.064.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.060 to 2.065.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.17 to 0.20.
+.IP \(bu 4
+constant has been upgraded from version 1.27 to 1.31.
+.IP \(bu 4
+CPAN has been upgraded from version 2.00 to 2.05.
+.IP \(bu 4
+CPAN::Meta has been upgraded from version 2.120921 to 2.140640.
+.IP \(bu 4
+CPAN::Meta::Requirements has been upgraded from version 2.122 to 2.125.
+.IP \(bu 4
+CPAN::Meta::YAML has been upgraded from version 0.008 to 0.012.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.145 to 2.151.
+.IP \(bu 4
+DB has been upgraded from version 1.04 to 1.07.
+.IP \(bu 4
+DB_File has been upgraded from version 1.827 to 1.831.
+.IP \(bu 4
+DBM_Filter has been upgraded from version 0.05 to 0.06.
+.IP \(bu 4
+deprecate has been upgraded from version 0.02 to 0.03.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.11 to 1.16.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.20 to 3.21.
+.IP \(bu 4
+diagnostics has been upgraded from version 1.31 to 1.34.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.52 to 2.53.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.84 to 5.88.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.18 to 1.25.
+.IP \(bu 4
+Encode has been upgraded from version 2.49 to 2.60.
+.IP \(bu 4
+encoding has been upgraded from version 2.6_01 to 2.12.
+.IP \(bu 4
+English has been upgraded from version 1.06 to 1.09.
+.Sp
+\&\f(CW$OLD_PERL_VERSION\fR was added as an alias of \f(CW$]\fR.
+.IP \(bu 4
+Errno has been upgraded from version 1.18 to 1.20_03.
+.IP \(bu 4
+Exporter has been upgraded from version 5.68 to 5.70.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280210 to 0.280216.
+.IP \(bu 4
+ExtUtils::Command has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+ExtUtils::Embed has been upgraded from version 1.30 to 1.32.
+.IP \(bu 4
+ExtUtils::Install has been upgraded from version 1.59 to 1.67.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 6.66 to 6.98.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version  to 1.01.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.18 to 3.24.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.19 to 3.24.
+.IP \(bu 4
+ExtUtils::XSSymSet has been upgraded from version 1.2 to 1.3.
+.IP \(bu 4
+feature has been upgraded from version 1.32 to 1.36.
+.IP \(bu 4
+fields has been upgraded from version 2.16 to 2.17.
+.IP \(bu 4
+File::Basename has been upgraded from version 2.84 to 2.85.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.26 to 2.29.
+.IP \(bu 4
+File::DosGlob has been upgraded from version 1.10 to 1.12.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.38 to 0.48.
+.IP \(bu 4
+File::Find has been upgraded from version 1.23 to 1.27.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.20 to 1.23.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.40 to 3.47.
+.IP \(bu 4
+File::Temp has been upgraded from version 0.23 to 0.2304.
+.IP \(bu 4
+FileCache has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+Filter::Simple has been upgraded from version 0.89 to 0.91.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.45 to 1.49.
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.39 to 2.42.
+.IP \(bu 4
+Getopt::Std has been upgraded from version 1.07 to 1.10.
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.10 to 1.15.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.025 to 0.043.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.10 to 0.11.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.39 to 0.40.
+.IP \(bu 4
+if has been upgraded from version 0.0602 to 0.0603.
+.IP \(bu 4
+inc::latest has been upgraded from version 0.4003 to 0.4205.
+NOTE: inc::latest is deprecated and may be removed from a future version of Perl.
+.IP \(bu 4
+integer has been upgraded from version 1.00 to 1.01.
+.IP \(bu 4
+IO has been upgraded from version 1.28 to 1.31.
+.IP \(bu 4
+IO::Compress::Gzip and friends have been upgraded from version 2.060 to
+2.064.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.80 to 0.92.
+.IP \(bu 4
+IPC::Open3 has been upgraded from version 1.13 to 1.16.
+.IP \(bu 4
+IPC::SysV has been upgraded from version 2.03 to 2.04.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.27202 to 2.27203.
+.IP \(bu 4
+List::Util has been upgraded from version 1.27 to 1.38.
+.IP \(bu 4
+locale has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.25 to 3.30.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.23 to 1.25.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.9991 to 1.9993.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.30 to 0.31.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2604 to 0.2606.
+.IP \(bu 4
+MIME::Base64 has been upgraded from version 3.13 to 3.14.
+.IP \(bu 4
+Module::Build has been upgraded from version 0.4003 to 0.4205.
+NOTE: Module::Build is deprecated and may be removed from a future version of Perl.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 2.89 to 3.10.
+.IP \(bu 4
+Module::Load has been upgraded from version 0.24 to 0.32.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded from version 0.54 to 0.62.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000011 to 1.000019.
+.IP \(bu 4
+mro has been upgraded from version 1.11 to 1.16.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.41 to 2.43.
+.IP \(bu 4
+Opcode has been upgraded from version 1.25 to 1.27.
+.IP \(bu 4
+Package::Constants has been upgraded from version 0.02 to 0.04.
+NOTE: Package::Constants is deprecated and may be removed from a future version of Perl.
+.IP \(bu 4
+Params::Check has been upgraded from version 0.36 to 0.38.
+.IP \(bu 4
+parent has been upgraded from version 0.225 to 0.228.
+.IP \(bu 4
+Parse::CPAN::Meta has been upgraded from version 1.4404 to 1.4414.
+.IP \(bu 4
+Perl::OSType has been upgraded from version 1.003 to 1.007.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.0150042 to 5.0150044.
+.IP \(bu 4
+PerlIO has been upgraded from version 1.07 to 1.09.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.16 to 0.18.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.16 to 0.18.
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.12 to 0.14.
+.IP \(bu 4
+Pod::Escapes has been upgraded from version 1.04 to 1.06.
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.06 to 1.08.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.18 to 1.21.
+.IP \(bu 4
+Pod::Parser has been upgraded from version 1.60 to 1.62.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.19 to 3.23.
+.IP \(bu 4
+Pod::Usage has been upgraded from version 1.61 to 1.63.
+.IP \(bu 4
+POSIX has been upgraded from version 1.32 to 1.38_03.
+.IP \(bu 4
+re has been upgraded from version 0.23 to 0.26.
+.IP \(bu 4
+Safe has been upgraded from version 2.35 to 2.37.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.27 to 1.38.
+.IP \(bu 4
+SDBM_File has been upgraded from version 1.09 to 1.11.
+.IP \(bu 4
+Socket has been upgraded from version 2.009 to 2.013.
+.IP \(bu 4
+Storable has been upgraded from version 2.41 to 2.49.
+.IP \(bu 4
+strict has been upgraded from version 1.07 to 1.08.
+.IP \(bu 4
+subs has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.32 to 0.33.
+.IP \(bu 4
+Term::Cap has been upgraded from version 1.13 to 1.15.
+.IP \(bu 4
+Term::ReadLine has been upgraded from version 1.12 to 1.14.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.26 to 3.30.
+.IP \(bu 4
+Test::Simple has been upgraded from version 0.98 to 1.001002.
+.IP \(bu 4
+Text::ParseWords has been upgraded from version 3.28 to 3.29.
+.IP \(bu 4
+Text::Tabs has been upgraded from version 2012.0818 to 2013.0523.
+.IP \(bu 4
+Text::Wrap has been upgraded from version 2012.0818 to 2013.0523.
+.IP \(bu 4
+Thread has been upgraded from version 3.02 to 3.04.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 3.02 to 3.05.
+.IP \(bu 4
+threads has been upgraded from version 1.86 to 1.93.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.43 to 1.46.
+.IP \(bu 4
+Tie::Array has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+Tie::File has been upgraded from version 0.99 to 1.00.
+.IP \(bu 4
+Tie::Hash has been upgraded from version 1.04 to 1.05.
+.IP \(bu 4
+Tie::Scalar has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+Tie::StdHandle has been upgraded from version 4.3 to 4.4.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9725 to 1.9726.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.20_01 to 1.27.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 0.97 to 1.04.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.16 to 1.17.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.51 to 0.57.
+.IP \(bu 4
+utf8 has been upgraded from version 1.10 to 1.13.
+.IP \(bu 4
+version has been upgraded from version 0.9902 to 0.9908.
+.IP \(bu 4
+vmsish has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+warnings has been upgraded from version 1.18 to 1.23.
+.IP \(bu 4
+Win32 has been upgraded from version 0.47 to 0.49.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.10 to 0.13.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.16 to 0.17.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlrepository\fR
+.IX Subsection "perlrepository"
+.PP
+This document was removed (actually, renamed perlgit and given a major
+overhaul) in Perl v5.14, causing Perl documentation websites to show the now
+out of date version in Perl v5.12 as the latest version.  It has now been
+restored in stub form, directing readers to current information.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperldata\fR
+.IX Subsection "perldata"
+.IP \(bu 4
+New sections have been added to document the new index/value array slice and
+key/value hash slice syntax.
+.PP
+\fIperldebguts\fR
+.IX Subsection "perldebguts"
+.IP \(bu 4
+The \f(CW\*(C`DB::goto\*(C'\fR and \f(CW\*(C`DB::lsub\*(C'\fR debugger subroutines are now documented.  [perl
+#77680]
+.PP
+\fIperlexperiment\fR
+.IX Subsection "perlexperiment"
+.IP \(bu 4
+\&\f(CW\*(C`\es\*(C'\fR matching \f(CW\*(C`\ecK\*(C'\fR is marked experimental.
+.IP \(bu 4
+ithreads were accepted in v5.8.0 (but are discouraged as of v5.20.0).
+.IP \(bu 4
+Long doubles are not considered experimental.
+.IP \(bu 4
+Code in regular expressions, regular expression backtracking verbs,
+and lvalue subroutines are no longer listed as experimental.  (This
+also affects perlre and perlsub.)
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+\&\f(CW\*(C`chop\*(C'\fR and \f(CW\*(C`chomp\*(C'\fR now note that they can reset the hash iterator.
+.IP \(bu 4
+\&\f(CW\*(C`exec\*(C'\fR's handling of arguments is now more clearly documented.
+.IP \(bu 4
+\&\f(CW\*(C`eval EXPR\*(C'\fR now has caveats about expanding floating point numbers in some
+locales.
+.IP \(bu 4
+\&\f(CW\*(C`goto EXPR\*(C'\fR is now documented to handle an expression that evaluates to a
+code reference as if it was \f(CW\*(C`goto &$coderef\*(C'\fR.  This behavior is at least ten
+years old.
+.IP \(bu 4
+Since Perl v5.10, it has been possible for subroutines in \f(CW@INC\fR to return
+a reference to a scalar holding initial source code to prepend to the file.
+This is now documented.
+.IP \(bu 4
+The documentation of \f(CW\*(C`ref\*(C'\fR has been updated to recommend the use of
+\&\f(CW\*(C`blessed\*(C'\fR, \f(CW\*(C`isa\*(C'\fR and \f(CW\*(C`reftype\*(C'\fR when dealing with references to blessed
+objects.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+Numerous minor changes have been made to reflect changes made to the perl
+internals in this release.
+.IP \(bu 4
+New sections on Read-Only Values and
+Copy on Write have been added.
+.PP
+\fIperlhack\fR
+.IX Subsection "perlhack"
+.IP \(bu 4
+The Super Quick Patch Guide section has
+been updated.
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+The documentation has been updated to include some more examples of \f(CW\*(C`gdb\*(C'\fR
+usage.
+.PP
+\fIperllexwarn\fR
+.IX Subsection "perllexwarn"
+.IP \(bu 4
+The perllexwarn documentation used to describe the hierarchy of warning
+categories understood by the warnings pragma. That description has now
+been moved to the warnings documentation itself, leaving perllexwarn
+as a stub that points to it. This change consolidates all documentation for
+lexical warnings in a single place.
+.PP
+\fIperllocale\fR
+.IX Subsection "perllocale"
+.IP \(bu 4
+The documentation now mentions \fR\f(BIfc()\fR\fI\fR and \f(CW\*(C`\eF\*(C'\fR, and includes many
+clarifications and corrections in general.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+The language design of Perl has always called for monomorphic operators.
+This is now mentioned explicitly.
+.PP
+\fIperlopentut\fR
+.IX Subsection "perlopentut"
+.IP \(bu 4
+The \f(CW\*(C`open\*(C'\fR tutorial has been completely rewritten by Tom Christiansen, and now
+focuses on covering only the basics, rather than providing a comprehensive
+reference to all things openable.  This rewrite came as the result of a
+vigorous discussion on perl5\-porters kicked off by a set of improvements
+written by Alexander Hartmaier to the existing perlopentut.  A "more than
+you ever wanted to know about \f(CW\*(C`open\*(C'\fR" document may follow in subsequent
+versions of perl.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+The fact that the regexp engine makes no effort to call (?{}) and (??{})
+constructs any specified number of times (although it will basically DWIM
+in case of a successful match) has been documented.
+.IP \(bu 4
+The \f(CW\*(C`/r\*(C'\fR modifier (for non-destructive substitution) is now documented. [perl
+#119151]
+.IP \(bu 4
+The documentation for \f(CW\*(C`/x\*(C'\fR and \f(CW\*(C`(?# comment)\*(C'\fR has been expanded and clarified.
+.PP
+\fIperlreguts\fR
+.IX Subsection "perlreguts"
+.IP \(bu 4
+The documentation has been updated in the light of recent changes to
+\&\fIregcomp.c\fR.
+.PP
+\fIperlsub\fR
+.IX Subsection "perlsub"
+.IP \(bu 4
+The need to predeclare recursive functions with prototypes in order for the
+prototype to be honoured in the recursive call is now documented. [perl #2726]
+.IP \(bu 4
+A list of subroutine names used by the perl implementation is now included.
+[perl #77680]
+.PP
+\fIperltrap\fR
+.IX Subsection "perltrap"
+.IP \(bu 4
+There is now a JavaScript section.
+.PP
+\fIperlunicode\fR
+.IX Subsection "perlunicode"
+.IP \(bu 4
+The documentation has been updated to reflect \f(CW\*(C`Bidi_Class\*(C'\fR changes in
+Unicode 6.3.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+A new section explaining the performance issues of $`, $& and $', including
+workarounds and changes in different versions of Perl, has been added.
+.IP \(bu 4
+Three English variable names which have long been documented but do not
+actually exist have been removed from the documentation.  These were
+\&\f(CW$OLD_PERL_VERSION\fR, \f(CW$OFMT\fR, and \f(CW$ARRAY_BASE\fR.
+.Sp
+(Actually, \f(CW\*(C`OLD_PERL_VERSION\*(C'\fR \fIdoes\fR exist, starting with this revision, but
+remained undocumented until perl 5.22.0.)
+.PP
+\fIperlxs\fR
+.IX Subsection "perlxs"
+.IP \(bu 4
+Several problems in the \f(CW\*(C`MY_CXT\*(C'\fR example have been fixed.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+delete argument is index/value array slice, use array slice
+.Sp
+(F) You used index/value array slice syntax (\f(CW%array[...]\fR) as the argument to
+\&\f(CW\*(C`delete\*(C'\fR.  You probably meant \f(CW@array[...]\fR with an @ symbol instead.
+.IP \(bu 4
+delete argument is key/value hash slice, use hash slice
+.Sp
+(F) You used key/value hash slice syntax (\f(CW%hash{...}\fR) as the argument to
+\&\f(CW\*(C`delete\*(C'\fR.  You probably meant \f(CW@hash{...}\fR with an @ symbol instead.
+.IP \(bu 4
+Magical list constants are not supported
+.Sp
+(F) You assigned a magical array to a stash element, and then tried to use the
+subroutine from the same slot.  You are asking Perl to do something it cannot
+do, details subject to change between Perl versions.
+.IP \(bu 4
+Added Setting $/ to a \f(CW%s\fR reference is forbidden
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+\&\f(CW%s\fR on reference is experimental:
+.Sp
+The "auto-deref" feature is experimental.
+.Sp
+Starting in v5.14.0, it was possible to use push, pop, keys, and other
+built-in functions not only on aggregate types, but on references to
+them.  The feature was not deployed to its original intended
+specification, and now may become redundant to postfix dereferencing.
+It has always been categorized as an experimental feature, and in
+v5.20.0 is carries a warning as such.
+.Sp
+Warnings will now be issued at compile time when these operations are
+detected.
+.Sp
+.Vb 1
+\&  no if $] >= 5.01908, warnings => "experimental::autoderef";
+.Ve
+.Sp
+Consider, though, replacing the use of these features, as they may
+change behavior again before becoming stable.
+.IP \(bu 4
+A sequence of multiple spaces in a charnames alias definition is deprecated
+.Sp
+Trailing white-space in a charnames alias definition is deprecated
+.Sp
+These two deprecation warnings involving \f(CW\*(C`\eN{...}\*(C'\fR were incorrectly
+implemented.  They did not warn by default (now they do) and could not be
+made fatal via \f(CW\*(C`use warnings FATAL => \*(Aqdeprecated\*(Aq\*(C'\fR (now they can).
+.IP \(bu 4
+Attribute prototype(%s) discards earlier prototype attribute in same sub
+.Sp
+(W misc) A sub was declared as \f(CW\*(C`sub foo : prototype(A) : prototype(B) {}\*(C'\fR, for
+example.  Since each sub can only have one prototype, the earlier
+declaration(s) are discarded while the last one is applied.
+.IP \(bu 4
+Invalid \e0 character in \f(CW%s\fR for \f(CW%s:\fR \f(CW%s\fR\e0%s
+.Sp
+(W syscalls) Embedded \e0 characters in pathnames or other system call arguments
+produce a warning as of 5.20.  The parts after the \e0 were formerly ignored by
+system calls.
+.IP \(bu 4
+Matched non-Unicode code point 0x%X against Unicode property; may not be portable.
+.Sp
+This replaces the message "Code point 0x%X is not Unicode, all \ep{} matches
+fail; all \eP{} matches succeed".
+.IP \(bu 4
+Missing ']' in prototype for \f(CW%s\fR : \f(CW%s\fR
+.Sp
+(W illegalproto) A grouping was started with \f(CW\*(C`[\*(C'\fR but never closed with \f(CW\*(C`]\*(C'\fR.
+.IP \(bu 4
+Possible precedence issue with control flow operator
+.Sp
+(W syntax) There is a possible problem with the mixing of a control flow
+operator (e.g. \f(CW\*(C`return\*(C'\fR) and a low-precedence operator like \f(CW\*(C`or\*(C'\fR.  Consider:
+.Sp
+.Vb 1
+\&    sub { return $a or $b; }
+.Ve
+.Sp
+This is parsed as:
+.Sp
+.Vb 1
+\&    sub { (return $a) or $b; }
+.Ve
+.Sp
+Which is effectively just:
+.Sp
+.Vb 1
+\&    sub { return $a; }
+.Ve
+.Sp
+Either use parentheses or the high-precedence variant of the operator.
+.Sp
+Note this may be also triggered for constructs like:
+.Sp
+.Vb 1
+\&    sub { 1 if die; }
+.Ve
+.IP \(bu 4
+Postfix dereference is experimental
+.Sp
+(S experimental::postderef) This warning is emitted if you use the experimental
+postfix dereference syntax.  Simply suppress the warning if you want to use the
+feature, but know that in doing so you are taking the risk of using an
+experimental feature which may change or be removed in a future Perl version:
+.Sp
+.Vb 6
+\&    no warnings "experimental::postderef";
+\&    use feature "postderef", "postderef_qq";
+\&    $ref\->$*;
+\&    $aref\->@*;
+\&    $aref\->@[@indices];
+\&    ... etc ...
+.Ve
+.IP \(bu 4
+Prototype '%s' overridden by attribute 'prototype(%s)' in \f(CW%s\fR
+.Sp
+(W prototype) A prototype was declared in both the parentheses after the sub
+name and via the prototype attribute.  The prototype in parentheses is useless,
+since it will be replaced by the prototype from the attribute before it's ever
+used.
+.IP \(bu 4
+Scalar value @%s[%s] better written as $%s[%s]
+.Sp
+(W syntax) In scalar context, you've used an array index/value slice (indicated
+by %) to select a single element of an array.  Generally it's better to ask for
+a scalar value (indicated by $).  The difference is that \f(CW$foo[&bar]\fR always
+behaves like a scalar, both in the value it returns and when evaluating its
+argument, while \f(CW%foo[&bar]\fR provides a list context to its subscript, which
+can do weird things if you're expecting only one subscript.  When called in
+list context, it also returns the index (what \f(CW&bar\fR returns) in addition to
+the value.
+.IP \(bu 4
+Scalar value @%s{%s} better written as $%s{%s}
+.Sp
+(W syntax) In scalar context, you've used a hash key/value slice (indicated by
+%) to select a single element of a hash.  Generally it's better to ask for a
+scalar value (indicated by $).  The difference is that \f(CW$foo{&bar}\fR always
+behaves like a scalar, both in the value it returns and when evaluating its
+argument, while \f(CW@foo{&bar}\fR and provides a list context to its subscript,
+which can do weird things if you're expecting only one subscript.  When called
+in list context, it also returns the key in addition to the value.
+.IP \(bu 4
+Setting $/ to a reference to \f(CW%s\fR as a form of slurp is deprecated, treating as undef
+.IP \(bu 4
+Unexpected exit \f(CW%u\fR
+.Sp
+(S) \fBexit()\fR was called or the script otherwise finished gracefully when
+\&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR was set in \f(CW\*(C`PL_exit_flags\*(C'\fR.
+.IP \(bu 4
+Unexpected exit failure \f(CW%d\fR
+.Sp
+(S) An uncaught \fBdie()\fR was called when \f(CW\*(C`PERL_EXIT_WARN\*(C'\fR was set in
+\&\f(CW\*(C`PL_exit_flags\*(C'\fR.
+.IP \(bu 4
+Use of literal control characters in variable names is deprecated
+.Sp
+(D deprecated) Using literal control characters in the source to refer to the
+^FOO variables, like $^X and ${^GLOBAL_PHASE} is now deprecated.  This only
+affects code like $\ecT, where \ecT is a control (like a \f(CW\*(C`SOH\*(C'\fR) in the
+source code: ${"\ecT"} and $^T remain valid.
+.IP \(bu 4
+Useless use of greediness modifier
+.Sp
+This fixes [Perl #42957].
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Warnings and errors from the regexp engine are now UTF\-8 clean.
+.IP \(bu 4
+The "Unknown switch condition" error message has some slight changes.  This
+error triggers when there is an unknown condition in a \f(CW\*(C`(?(foo))\*(C'\fR conditional.
+The error message used to read:
+.Sp
+.Vb 1
+\&    Unknown switch condition (?(%s in regex;
+.Ve
+.Sp
+But what \f(CW%s\fR could be was mostly up to luck.  For \f(CW\*(C`(?(foobar))\*(C'\fR, you might have
+seen "fo" or "f".  For Unicode characters, you would generally get a corrupted
+string.  The message has been changed to read:
+.Sp
+.Vb 1
+\&    Unknown switch condition (?(...)) in regex;
+.Ve
+.Sp
+Additionally, the \f(CW\*(Aq<\-\- HERE\*(Aq\fR marker in the error will now point to the
+correct spot in the regex.
+.IP \(bu 4
+The "%s "\ex%X" does not map to Unicode" warning is now correctly listed as a
+severe warning rather than as a fatal error.
+.IP \(bu 4
+Under rare circumstances, one could get a "Can't coerce readonly REF to
+string" instead of the customary "Modification of a read-only value".  This
+alternate error message has been removed.
+.IP \(bu 4
+"Ambiguous use of * resolved as operator *": This and similar warnings
+about "%" and "&" used to occur in some circumstances where there was no
+operator of the type cited, so the warning was completely wrong.  This has
+been fixed [perl #117535, #76910].
+.IP \(bu 4
+Warnings about malformed subroutine prototypes are now more consistent in
+how the prototypes are rendered.  Some of these warnings would truncate
+prototypes containing nulls.  In other cases one warning would suppress
+another.  The warning about illegal characters in prototypes no longer says
+"after '_'" if the bad character came before the underscore.
+.IP \(bu 4
+Perl folding rules are not up-to-date for 0x%X; please use the perlbug
+utility to report; in regex; marked by <\-\- HERE in
+m/%s/
+.Sp
+This message is now only in the regexp category, and not in the deprecated
+category.  It is still a default (i.e., severe) warning [perl #89648].
+.IP \(bu 4
+%%s[%s] in scalar context better written as $%s[%s]
+.Sp
+This warning now occurs for any \f(CW%array[$index]\fR or \f(CW%hash{key}\fR known to
+be in scalar context at compile time.  Previously it was worded "Scalar
+value %%s[%s] better written as $%s[%s]".
+.IP \(bu 4
+Switch condition not recognized in regex; marked by <\-\- HERE in m/%s/:
+.Sp
+The description for this diagnostic has been extended to cover all cases where the warning may occur.
+Issues with the positioning of the arrow indicator have also been resolved.
+.IP \(bu 4
+The error messages for \f(CWmy($a?$b$c)\fR and \f(CWmy(do{})\fR now mention "conditional
+expression" and "do block", respectively, instead of reading 'Can't declare
+null operation in "my"'.
+.IP \(bu 4
+When \f(CW\*(C`use re "debug"\*(C'\fR executes a regex containing a backreference, the
+debugging output now shows what string is being matched.
+.IP \(bu 4
+The now fatal error message \f(CW\*(C`Character following "\ec" must be ASCII\*(C'\fR has been
+reworded as \f(CW\*(C`Character following "\ec" must be printable ASCII\*(C'\fR to emphasize
+that in \f(CW\*(C`\ec\fR\f(CIX\fR\f(CW\*(C'\fR, \fIX\fR must be a \fIprintable (non-control)\fR ASCII character.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\fIa2p\fR
+.IX Subsection "a2p"
+.IP \(bu 4
+A possible crash from an off-by-one error when trying to access before the
+beginning of a buffer has been fixed.  [perl #120244]
+.PP
+\fIbisect.pl\fR
+.IX Subsection "bisect.pl"
+.PP
+The git bisection tool \fIPorting/bisect.pl\fR has had many enhancements.
+.PP
+It is provided as part of the source distribution but not installed because
+it is not self-contained as it relies on being run from within a git
+checkout. Note also that it makes no attempt to fix tests, correct runtime
+bugs or make something useful to install \- its purpose is to make minimal
+changes to get any historical revision of interest to build and run as close
+as possible to "as-was", and thereby make \f(CW\*(C`git bisect\*(C'\fR easy to use.
+.IP \(bu 4
+Can optionally run the test case with a timeout.
+.IP \(bu 4
+Can now run in-place in a clean git checkout.
+.IP \(bu 4
+Can run the test case under \f(CW\*(C`valgrind\*(C'\fR.
+.IP \(bu 4
+Can apply user supplied patches and fixes to the source checkout before
+building.
+.IP \(bu 4
+Now has fixups to enable building several more historical ranges of bleadperl,
+which can be useful for pinpointing the origins of bugs or behaviour changes.
+.PP
+\fIfind2perl\fR
+.IX Subsection "find2perl"
+.IP \(bu 4
+find2perl now handles \f(CW\*(C`?\*(C'\fR wildcards correctly.  [perl #113054]
+.PP
+\fIperlbug\fR
+.IX Subsection "perlbug"
+.IP \(bu 4
+\&\fIperlbug\fR now has a \f(CW\*(C`\-p\*(C'\fR option for attaching patches with a bug report.
+.IP \(bu 4
+perlbug has been modified to supply the report template with CRLF line
+endings on Windows.
+[GH #13612] <https://github.com/Perl/perl5/issues/13612>
+.IP \(bu 4
+perlbug now makes as few assumptions as possible about the encoding of the
+report.  This will likely change in the future to assume UTF\-8 by default but
+allow a user override.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+The \fIMakefile.PL\fR for SDBM_File now generates a better \fIMakefile\fR, which
+avoids a race condition during parallel makes, which could cause the build to
+fail.  This is the last known parallel make problem (on *nix platforms), and
+therefore we believe that a parallel make should now always be error free.
+.IP \(bu 4
+\&\fIinstallperl\fR and \fIinstallman\fR's option handling has been refactored to use
+Getopt::Long. Both are used by the \fIMakefile\fR \f(CW\*(C`install\*(C'\fR targets, and
+are not installed, so these changes are only likely to affect custom
+installation scripts.
+.RS 4
+.IP \(bu 4
+Single letter options now also have long names.
+.IP \(bu 4
+Invalid options are now rejected.
+.IP \(bu 4
+Command line arguments that are not options are now rejected.
+.IP \(bu 4
+Each now has a \f(CW\*(C`\-\-help\*(C'\fR option to display the usage message.
+.RE
+.RS 4
+.Sp
+The behaviour for all valid documented invocations is unchanged.
+.RE
+.IP \(bu 4
+Where possible, the build now avoids recursive invocations of \fImake\fR when
+building pure-Perl extensions, without removing any parallelism from the
+build. Currently around 80 extensions can be processed directly by the
+\&\fImake_ext.pl\fR tool, meaning that 80 invocations of \fImake\fR and 160
+invocations of \fIminiperl\fR are no longer made.
+.IP \(bu 4
+The build system now works correctly when compiling under GCC or Clang with
+link-time optimization enabled (the \f(CW\*(C`\-flto\*(C'\fR option). [perl #113022]
+.IP \(bu 4
+Distinct library basenames with \f(CW\*(C`d_libname_unique\*(C'\fR.
+.Sp
+When compiling perl with this option, the library files for XS modules are
+named something "unique" \-\- for example, Hash/Util/Util.so becomes
+Hash/Util/PL_Hash_\|_Util.so.  This behavior is similar to what currently
+happens on VMS, and serves as groundwork for the Android port.
+.IP \(bu 4
+\&\f(CW\*(C`sysroot\*(C'\fR option to indicate the logical root directory under gcc and clang.
+.Sp
+When building with this option set, both Configure and the compilers search
+for all headers and libraries under this new sysroot, instead of /.
+.Sp
+This is a huge time saver if cross-compiling, but can also help
+on native builds if your toolchain's files have non-standard locations.
+.IP \(bu 4
+The cross-compilation model has been renovated.
+There's several new options, and some backwards-incompatible changes:
+.Sp
+We now build binaries for miniperl and generate_uudmap to be used on the host,
+rather than running every miniperl call on the target; this means that, short
+of 'make test', we no longer need access to the target system once Configure is
+done.  You can provide already-built binaries through the \f(CW\*(C`hostperl\*(C'\fR and
+\&\f(CW\*(C`hostgenerate\*(C'\fR options to Configure.
+.Sp
+Additionally, if targeting an EBCDIC platform from an ASCII host,
+or viceversa, you'll need to run Configure with \f(CW\*(C`\-Uhostgenerate\*(C'\fR, to
+indicate that generate_uudmap should be run on the target.
+.Sp
+Finally, there's also a way of having Configure end early, right after
+building the host binaries, by cross-compiling without specifying a
+\&\f(CW\*(C`targethost\*(C'\fR.
+.Sp
+The incompatible changes include no longer using xconfig.h, xlib, or
+Cross.pm, so canned config files and Makefiles will have to be updated.
+.IP \(bu 4
+Related to the above, there is now a way of specifying the location of sh
+(or equivalent) on the target system: \f(CW\*(C`targetsh\*(C'\fR.
+.Sp
+For example, Android has its sh in /system/bin/sh, so if cross-compiling
+from a more normal Unixy system with sh in /bin/sh, "targetsh" would end
+up as /system/bin/sh, and "sh" as /bin/sh.
+.IP \(bu 4
+By default, \fBgcc\fR 4.9 does some optimizations that break perl.  The \fB\-fwrapv\fR
+option disables those optimizations (and probably others), so for \fBgcc\fR 4.3
+and later (since the there might be similar problems lurking on older versions
+too, but \fB\-fwrapv\fR was broken before 4.3, and the optimizations probably won't
+go away), \fIConfigure\fR now adds \fB\-fwrapv\fR unless the user requests
+\&\fB\-fno\-wrapv\fR, which disables \fB\-fwrapv\fR, or \fB\-fsanitize=undefined\fR, which
+turns the overflows \fB\-fwrapv\fR ignores into runtime errors.
+[GH #13690] <https://github.com/Perl/perl5/issues/13690>
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+The \f(CW\*(C`test.valgrind\*(C'\fR make target now allows tests to be run in parallel.
+This target allows Perl's test suite to be run under Valgrind, which detects
+certain sorts of C programming errors, though at significant cost in running
+time. On suitable hardware, allowing parallel execution claws back a lot of
+that additional cost. [perl #121431]
+.IP \(bu 4
+Various tests in \fIt/porting/\fR are no longer skipped when the perl
+\&\fI.git\fR directory is outside the perl tree and pointed to by
+\&\f(CW$GIT_DIR\fR. [perl #120505]
+.IP \(bu 4
+The test suite no longer fails when the user's interactive shell maintains a
+\&\f(CW$PWD\fR environment variable, but the \fI/bin/sh\fR used for running tests
+doesn't.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+.IP Android 4
+.IX Item "Android"
+Perl can now be built for Android, either natively or through
+cross-compilation, for all three currently available architectures (ARM,
+MIPS, and x86), on a wide range of versions.
+.IP Bitrig 4
+.IX Item "Bitrig"
+Compile support has been added for Bitrig, a fork of OpenBSD.
+.IP FreeMiNT 4
+.IX Item "FreeMiNT"
+Support has been added for FreeMiNT, a free open-source OS for the Atari ST
+system and its successors, based on the original MiNT that was officially
+adopted by Atari.
+.IP Synology 4
+.IX Item "Synology"
+Synology ships its NAS boxes with a lean Linux distribution (DSM) on relative
+cheap CPU's (like the Marvell Kirkwood mv6282 \- ARMv5tel or Freescale QorIQ
+P1022 ppc \- e500v2) not meant for workstations or development. These boxes
+should build now. The basic problems are the non-standard location for tools.
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.ie n .IP """sfio""" 4
+.el .IP \f(CWsfio\fR 4
+.IX Item "sfio"
+Code related to supporting the \f(CW\*(C`sfio\*(C'\fR I/O system has been removed.
+.Sp
+Perl 5.004 added support to use the native API of \f(CW\*(C`sfio\*(C'\fR, AT&T's Safe/Fast
+I/O library. This code still built with v5.8.0, albeit with many regression
+tests failing, but was inadvertently broken before the v5.8.1 release,
+meaning that it has not worked on any version of Perl released since then.
+In over a decade we have received no bug reports about this, hence it is clear
+that no-one is using this functionality on any version of Perl that is still
+supported to any degree.
+.IP "AT&T 3b1" 4
+.IX Item "AT&T 3b1"
+Configure support for the 3b1, also known as the AT&T Unix PC (and the similar
+AT&T 7300), has been removed.
+.IP DG/UX 4
+.IX Item "DG/UX"
+DG/UX was a Unix sold by Data General. The last release was in April 2001.
+It only runs on Data General's own hardware.
+.IP EBCDIC 4
+.IX Item "EBCDIC"
+In the absence of a regular source of smoke reports, code intended to support
+native EBCDIC platforms will be removed from perl before 5.22.0.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Cygwin 4
+.IX Item "Cygwin"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\fBrecv()\fR on a connected handle would populate the returned sender
+address with whatever happened to be in the working buffer.  \fBrecv()\fR
+now uses a workaround similar to the Win32 \fBrecv()\fR wrapper and returns
+an empty string when \fBrecvfrom\fR\|(2) doesn't modify the supplied address
+length. [perl #118843]
+.IP \(bu 4
+Fixed a build error in cygwin.c on Cygwin 1.7.28.
+.Sp
+Tests now handle the errors that occur when \f(CW\*(C`cygserver\*(C'\fR isn't
+running.
+.RE
+.RS 4
+.RE
+.IP GNU/Hurd 4
+.IX Item "GNU/Hurd"
+The BSD compatibility library \f(CW\*(C`libbsd\*(C'\fR is no longer required for builds.
+.IP Linux 4
+.IX Item "Linux"
+The hints file now looks for \f(CW\*(C`libgdbm_compat\*(C'\fR only if \f(CW\*(C`libgdbm\*(C'\fR itself is
+also wanted. The former is never useful without the latter, and in some
+circumstances, including it could actually prevent building.
+.IP "Mac OS" 4
+.IX Item "Mac OS"
+The build system now honors an \f(CW\*(C`ld\*(C'\fR setting supplied by the user running
+\&\fIConfigure\fR.
+.IP MidnightBSD 4
+.IX Item "MidnightBSD"
+\&\f(CW\*(C`objformat\*(C'\fR was removed from version 0.4\-RELEASE of MidnightBSD and had been
+deprecated on earlier versions.  This caused the build environment to be
+erroneously configured for \f(CW\*(C`a.out\*(C'\fR rather than \f(CW\*(C`elf\*(C'\fR.  This has been now
+been corrected.
+.IP "Mixed-endian platforms" 4
+.IX Item "Mixed-endian platforms"
+The code supporting \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR operations on mixed endian
+platforms has been removed. We believe that Perl has long been unable to
+build on mixed endian architectures (such as PDP\-11s), so we don't think
+that this change will affect any platforms which were able to build v5.18.0.
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The \f(CW\*(C`PERL_ENV_TABLES\*(C'\fR feature to control the population of \f(CW%ENV\fR at perl
+start-up was broken in Perl 5.16.0 but has now been fixed.
+.IP \(bu 4
+Skip access checks on remotes in \fBopendir()\fR.  [perl #121002]
+.IP \(bu 4
+A check for glob metacharacters in a path returned by the
+\&\f(CWglob()\fR operator has been replaced with a check for VMS
+wildcard characters.  This saves a significant number of unnecessary
+\&\f(CWlstat()\fR calls such that some simple glob operations become
+60\-80% faster.
+.RE
+.RS 4
+.RE
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\f(CW\*(C`rename\*(C'\fR and \f(CW\*(C`link\*(C'\fR on Win32 now set $! to ENOSPC and EDQUOT when
+appropriate.  [perl #119857]
+.IP \(bu 4
+The BUILD_STATIC and ALL_STATIC makefile options for linking some or (nearly)
+all extensions statically (into perl520.dll, and into a separate
+perl\-static.exe too) were broken for MinGW builds. This has now been fixed.
+.Sp
+The ALL_STATIC option has also been improved to include the Encode and Win32
+extensions (for both VC++ and MinGW builds).
+.IP \(bu 4
+Support for building with Visual C++ 2013 has been added.  There are currently
+two possible test failures (see "Testing Perl on Windows" in perlwin32) which
+will hopefully be resolved soon.
+.IP \(bu 4
+Experimental support for building with Intel C++ Compiler has been added.  The
+nmake makefile (win32/Makefile) and the dmake makefile (win32/makefile.mk) can
+be used.  A "nmake test" will not pass at this time due to \fIcpan/CGI/t/url.t\fR.
+.IP \(bu 4
+Killing a process tree with "kill" in perlfunc and a negative signal, was broken
+starting in 5.18.0. In this bug, \f(CW\*(C`kill\*(C'\fR always returned 0 for a negative
+signal even for valid PIDs, and no processes were terminated. This has been
+fixed [perl #121230].
+.IP \(bu 4
+The time taken to build perl on Windows has been reduced quite significantly
+(time savings in the region of 30\-40% are typically seen) by reducing the
+number of, usually failing, I/O calls for each \f(CWrequire()\fR
+(for \fBminiperl.exe\fR only).
+[GH #13566] <https://github.com/Perl/perl5/issues/13566>
+.IP \(bu 4
+About 15 minutes of idle sleeping was removed from running \f(CW\*(C`make test\*(C'\fR due to
+a bug in which the timeout monitor used for tests could not be cancelled once
+the test completes, and the full timeout period elapsed before running the next
+test file.
+[GH #13647] <https://github.com/Perl/perl5/issues/13647>
+.IP \(bu 4
+On a perl built without pseudo-fork (pseudo-fork builds were not affected by
+this bug), killing a process tree with \f(CWkill()\fR and a negative
+signal resulted in \f(CWkill()\fR inverting the returned value.  For example, if
+\&\f(CWkill()\fR killed 1 process tree PID then it returned 0 instead of 1, and if
+\&\f(CWkill()\fR was passed 2 invalid PIDs then it returned 2 instead of 0.  This has
+probably been the case since the process tree kill feature was implemented on
+Win32.  It has now been corrected to follow the documented behaviour.
+[GH #13595] <https://github.com/Perl/perl5/issues/13595>
+.IP \(bu 4
+When building a 64\-bit perl, an uninitialized memory read in \fBminiperl.exe\fR,
+used during the build process, could lead to a 4GB \fBwperl.exe\fR being created.
+This has now been fixed.  (Note that \fBperl.exe\fR itself was unaffected, but
+obviously \fBwperl.exe\fR would have been completely broken.)
+[GH #13677] <https://github.com/Perl/perl5/issues/13677>
+.IP \(bu 4
+Perl can now be built with \fBgcc\fR version 4.8.1 from <http://www.mingw.org>.
+This was previously broken due to an incorrect definition of \fBDllMain()\fR in one
+of perl's source files.  Earlier \fBgcc\fR versions were also affected when using
+version 4 of the w32api package.  Versions of \fBgcc\fR available from
+<http://mingw\-w64.sourceforge.net/> were not affected.
+[GH #13733] <https://github.com/Perl/perl5/issues/13733>
+.IP \(bu 4
+The test harness now has no failures when perl is built on a FAT drive with the
+Windows OS on an NTFS drive.
+[GH #6348] <https://github.com/Perl/perl5/issues/6348>
+.IP \(bu 4
+When cloning the context stack in \fBfork()\fR emulation, \fBPerl_cx_dup()\fR
+would crash accessing parameter information for context stack entries
+that included no parameters, as with \f(CW\*(C`&foo;\*(C'\fR.
+[GH #13763] <https://github.com/Perl/perl5/issues/13763>
+.IP \(bu 4
+Introduced by
+[GH #12161] <https://github.com/Perl/perl5/issues/12161>, a memory
+leak on every call to \f(CW\*(C`system\*(C'\fR and backticks (\f(CW \`\` \fR), on most Win32 Perls
+starting from 5.18.0 has been fixed.  The memory leak only occurred if you
+enabled pseudo-fork in your build of Win32 Perl, and were running that build on
+Server 2003 R2 or newer OS.  The leak does not appear on WinXP SP3.
+[GH #13741] <https://github.com/Perl/perl5/issues/13741>
+.RE
+.RS 4
+.RE
+.IP WinCE 4
+.IX Item "WinCE"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The building of XS modules has largely been restored.  Several still cannot
+(yet) be built but it is now possible to build Perl on WinCE with only a couple
+of further patches (to Socket and ExtUtils::MakeMaker), hopefully to be
+incorporated soon.
+.IP \(bu 4
+Perl can now be built in one shot with no user intervention on WinCE by running
+\&\f(CW\*(C`nmake \-f Makefile.ce all\*(C'\fR.
+.Sp
+Support for building with EVC (Embedded Visual C++) 4 has been restored.  Perl
+can also be built using Smart Devices for Visual C++ 2005 or 2008.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+The internal representation has changed for the match variables \f(CW$1\fR, \f(CW$2\fR etc.,
+$`, $&, $', ${^PREMATCH}, ${^MATCH} and ${^POSTMATCH}.  It uses slightly less
+memory, avoids string comparisons and numeric conversions during lookup, and
+uses 23 fewer lines of C.  This change should not affect any external code.
+.IP \(bu 4
+Arrays now use NULL internally to represent unused slots, instead of
+&PL_sv_undef.  &PL_sv_undef is no longer treated as a special value, so
+av_store(av, 0, &PL_sv_undef) will cause element 0 of that array to hold a
+read-only undefined scalar.  \f(CW\*(C`$array[0] = anything\*(C'\fR will croak and
+\&\f(CW\*(C`\e$array[0]\*(C'\fR will compare equal to \f(CW\*(C`\eundef\*(C'\fR.
+.IP \(bu 4
+The SV returned by \fBHeSVKEY_force()\fR now correctly reflects the UTF8ness of the
+underlying hash key when that key is not stored as a SV.  [perl #79074]
+.IP \(bu 4
+Certain rarely used functions and macros available to XS code are now
+deprecated.  These are:
+\&\f(CW\*(C`utf8_to_uvuni_buf\*(C'\fR (use \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR instead),
+\&\f(CW\*(C`valid_utf8_to_uvuni\*(C'\fR (use \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR instead),
+\&\f(CW\*(C`NATIVE_TO_NEED\*(C'\fR (this did not work properly anyway),
+and \f(CW\*(C`ASCII_TO_NEED\*(C'\fR (this did not work properly anyway).
+.Sp
+Starting in this release, almost never does application code need to
+distinguish between the platform's character set and Latin1, on which the
+lowest 256 characters of Unicode are based.  New code should not use
+\&\f(CW\*(C`utf8n_to_uvuni\*(C'\fR (use \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR instead),
+nor
+\&\f(CW\*(C`uvuni_to_utf8\*(C'\fR (use \f(CW\*(C`uvchr_to_utf8\*(C'\fR instead),
+.IP \(bu 4
+The Makefile shortcut targets for many rarely (or never) used testing and
+profiling targets have been removed, or merged into the only other Makefile
+target that uses them.  Specifically, these targets are gone, along with
+documentation that referenced them or explained how to use them:
+.Sp
+.Vb 10
+\&    check.third check.utf16 check.utf8 coretest minitest.prep
+\&    minitest.utf16 perl.config.dashg perl.config.dashpg
+\&    perl.config.gcov perl.gcov perl.gprof perl.gprof.config
+\&    perl.pixie perl.pixie.atom perl.pixie.config perl.pixie.irix
+\&    perl.third perl.third.config perl.valgrind.config purecovperl
+\&    pureperl quantperl test.deparse test.taintwarn test.third
+\&    test.torture test.utf16 test.utf8 test_notty.deparse
+\&    test_notty.third test_notty.valgrind test_prep.third
+\&    test_prep.valgrind torturetest ucheck ucheck.third ucheck.utf16
+\&    ucheck.valgrind utest utest.third utest.utf16 utest.valgrind
+.Ve
+.Sp
+It's still possible to run the relevant commands by "hand" \- no underlying
+functionality has been removed.
+.IP \(bu 4
+It is now possible to keep Perl from initializing locale handling.
+For the most part, Perl doesn't pay attention to locale.  (See
+perllocale.)  Nonetheless, until now, on startup, it has always
+initialized locale handling to the system default, just in case the
+program being executed ends up using locales.  (This is one of the first
+things a locale-aware program should do, long before Perl knows if it
+will actually be needed or not.)  This works well except when Perl is
+embedded in another application which wants a locale that isn't the
+system default.  Now, if the environment variable
+\&\f(CW\*(C`PERL_SKIP_LOCALE_INIT\*(C'\fR is set at the time Perl is started, this
+initialization step is skipped.  Prior to this, on Windows platforms,
+the only workaround for this deficiency was to use a hacked-up copy of
+internal Perl code.  Applications that need to use older Perls can
+discover if the embedded Perl they are using needs the workaround by
+testing that the C preprocessor symbol \f(CW\*(C`HAS_SKIP_LOCALE_INIT\*(C'\fR is not
+defined.  [RT #38193]
+.IP \(bu 4
+\&\f(CW\*(C`BmRARE\*(C'\fR and \f(CW\*(C`BmPREVIOUS\*(C'\fR have been removed.  They were not used anywhere
+and are not part of the API.  For XS modules, they are now #defined as 0.
+.IP \(bu 4
+\&\f(CW\*(C`sv_force_normal\*(C'\fR, which usually croaks on read-only values, used to allow
+read-only values to be modified at compile time.  This has been changed to
+croak on read-only values regardless.  This change uncovered several core
+bugs.
+.IP \(bu 4
+Perl's new copy-on-write mechanism  (which is now enabled by default),
+allows any \f(CW\*(C`SvPOK\*(C'\fR scalar to be automatically upgraded to a copy-on-write
+scalar when copied. A reference count on the string buffer is stored in
+the string buffer itself.
+.Sp
+For example:
+.Sp
+.Vb 10
+\&    $ perl \-MDevel::Peek \-e\*(Aq$a="abc"; $b = $a; Dump $a; Dump $b\*(Aq
+\&    SV = PV(0x260cd80) at 0x2620ad8
+\&      REFCNT = 1
+\&      FLAGS = (POK,IsCOW,pPOK)
+\&      PV = 0x2619bc0 "abc"\e0
+\&      CUR = 3
+\&      LEN = 16
+\&      COW_REFCNT = 1
+\&    SV = PV(0x260ce30) at 0x2620b20
+\&      REFCNT = 1
+\&      FLAGS = (POK,IsCOW,pPOK)
+\&      PV = 0x2619bc0 "abc"\e0
+\&      CUR = 3
+\&      LEN = 16
+\&      COW_REFCNT = 1
+.Ve
+.Sp
+Note that both scalars share the same PV buffer and have a COW_REFCNT
+greater than zero.
+.Sp
+This means that XS code which wishes to modify the \f(CWSvPVX()\fR buffer of an
+SV should call \f(CWSvPV_force()\fR or similar first, to ensure a valid (and
+unshared) buffer, and to call \f(CWSvSETMAGIC()\fR afterwards. This in fact has
+always been the case (for example hash keys were already copy-on-write);
+this change just spreads the COW behaviour to a wider variety of SVs.
+.Sp
+One important difference is that before 5.18.0, shared hash-key scalars
+used to have the \f(CW\*(C`SvREADONLY\*(C'\fR flag set; this is no longer the case.
+.Sp
+This new behaviour can still be disabled by running \fIConfigure\fR with
+\&\fB\-Accflags=\-DPERL_NO_COW\fR.  This option will probably be removed in Perl
+5.22.
+.IP \(bu 4
+\&\f(CW\*(C`PL_sawampersand\*(C'\fR is now a constant.  The switch this variable provided
+(to enable/disable the pre-match copy depending on whether \f(CW$&\fR had been
+seen) has been removed and replaced with copy-on-write, eliminating a few
+bugs.
+.Sp
+The previous behaviour can still be enabled by running \fIConfigure\fR with
+\&\fB\-Accflags=\-DPERL_SAWAMPERSAND\fR.
+.IP \(bu 4
+The functions \f(CW\*(C`my_swap\*(C'\fR, \f(CW\*(C`my_htonl\*(C'\fR and \f(CW\*(C`my_ntohl\*(C'\fR have been removed.
+It is unclear why these functions were ever marked as \fIA\fR, part of the
+API. XS code can't call them directly, as it can't rely on them being
+compiled. Unsurprisingly, no code on CPAN references them.
+.IP \(bu 4
+The signature of the \f(CWPerl_re_intuit_start()\fR regex function has changed;
+the function pointer \f(CW\*(C`intuit\*(C'\fR in the regex engine plugin structure
+has also changed accordingly. A new parameter, \f(CW\*(C`strbeg\*(C'\fR has been added;
+this has the same meaning as the same-named parameter in
+\&\f(CW\*(C`Perl_regexec_flags\*(C'\fR. Previously intuit would try to guess the start of
+the string from the passed SV (if any), and would sometimes get it wrong
+(e.g. with an overloaded SV).
+.IP \(bu 4
+The signature of the \f(CWPerl_regexec_flags()\fR regex function has
+changed; the function pointer \f(CW\*(C`exec\*(C'\fR in the regex engine plugin
+structure has also changed to match.  The \f(CW\*(C`minend\*(C'\fR parameter now has
+type \f(CW\*(C`SSize_t\*(C'\fR to better support 64\-bit systems.
+.IP \(bu 4
+XS code may use various macros to change the case of a character or code
+point (for example \f(CWtoLOWER_utf8()\fR).  Only a couple of these were
+documented until now;
+and now they should be used in preference to calling the underlying
+functions.  See "Character case changing" in perlapi.
+.IP \(bu 4
+The code dealt rather inconsistently with uids and gids. Some
+places assumed that they could be safely stored in UVs, others
+in IVs, others in ints. Four new macros are introduced:
+\&\fBSvUID()\fR, \fBsv_setuid()\fR, \fBSvGID()\fR, and \fBsv_setgid()\fR
+.IP \(bu 4
+\&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR has been added to the API.  It is similar to \f(CW\*(C`sv_pos_b2u\*(C'\fR,
+but supports long strings on 64\-bit platforms.
+.IP \(bu 4
+\&\f(CW\*(C`PL_exit_flags\*(C'\fR can now be used by perl embedders or other XS code to have
+perl \f(CW\*(C`warn\*(C'\fR or \f(CW\*(C`abort\*(C'\fR on an attempted exit. [perl #52000]
+.IP \(bu 4
+Compiling with \f(CW\*(C`\-Accflags=\-PERL_BOOL_AS_CHAR\*(C'\fR now allows C99 and C++
+compilers to emulate the aliasing of \f(CW\*(C`bool\*(C'\fR to \f(CW\*(C`char\*(C'\fR that perl does for
+C89 compilers.  [perl #120314]
+.IP \(bu 4
+The \f(CW\*(C`sv\*(C'\fR argument in "sv_2pv_flags" in perlapi, "sv_2iv_flags" in perlapi,
+"sv_2uv_flags" in perlapi, and "sv_2nv_flags" in perlapi and their older wrappers
+sv_2pv, sv_2iv, sv_2uv, sv_2nv, is now non-NULL. Passing NULL now will crash.
+When the non-NULL marker was introduced en masse in 5.9.3 the functions
+were marked non-NULL, but since the creation of the SV API in 5.0 alpha 2, if
+NULL was passed, the functions returned 0 or false-type values. The code that
+supports \f(CW\*(C`sv\*(C'\fR argument being non-NULL dates to 5.0 alpha 2 directly, and
+indirectly to Perl 1.0 (pre 5.0 api). The lack of documentation that the
+functions accepted a NULL \f(CW\*(C`sv\*(C'\fR was corrected in 5.11.0 and between 5.11.0
+and 5.19.5 the functions were marked NULLOK. As an optimization the NULLOK code
+has now been removed, and the functions became non-NULL marked again, because
+core getter-type macros never pass NULL to these functions and would crash
+before ever passing NULL.
+.Sp
+The only way a NULL \f(CW\*(C`sv\*(C'\fR can be passed to sv_2*v* functions is if XS code
+directly calls sv_2*v*. This is unlikely as XS code uses Sv*V* macros to get
+the underlying value out of the SV. One possible situation which leads to
+a NULL \f(CW\*(C`sv\*(C'\fR being passed to sv_2*v* functions, is if XS code defines its own
+getter type Sv*V* macros, which check for NULL \fBbefore\fR dereferencing and
+checking the SV's flags through public API Sv*OK* macros or directly using
+private API \f(CW\*(C`SvFLAGS\*(C'\fR, and if \f(CW\*(C`sv\*(C'\fR is NULL, then calling the sv_2*v functions
+with a NULL literal or passing the \f(CW\*(C`sv\*(C'\fR containing a NULL value.
+.IP \(bu 4
+newATTRSUB is now a macro
+.Sp
+The public API newATTRSUB was previously a macro to the private
+function Perl_newATTRSUB. Function Perl_newATTRSUB has been removed. newATTRSUB
+is now macro to a different internal function.
+.IP \(bu 4
+Changes in warnings raised by \f(CWutf8n_to_uvchr()\fR
+.Sp
+This bottom level function decodes the first character of a UTF\-8 string
+into a code point.  It is accessible to \f(CW\*(C`XS\*(C'\fR level code, but it's
+discouraged from using it directly.  There are higher level functions
+that call this that should be used instead, such as
+"utf8_to_uvchr_buf" in perlapi.  For completeness though, this documents
+some changes to it.  Now, tests for malformations are done before any
+tests for other potential issues.  One of those issues involves code
+points so large that they have never appeared in any official standard
+(the current standard has scaled back the highest acceptable code point
+from earlier versions).  It is possible (though not done in CPAN) to
+warn and/or forbid these code points, while accepting smaller code
+points that are still above the legal Unicode maximum.  The warning
+message for this now includes the code point if representable on the
+machine.  Previously it always displayed raw bytes, which is what it
+still does for non-representable code points.
+.IP \(bu 4
+Regexp engine changes that affect the pluggable regex engine interface
+.Sp
+Many flags that used to be exposed via regexp.h and used to populate the
+extflags member of struct regexp have been removed. These fields were
+technically private to Perl's own regexp engine and should not have been
+exposed there in the first place.
+.Sp
+The affected flags are:
+.Sp
+.Vb 8
+\&    RXf_NOSCAN
+\&    RXf_CANY_SEEN
+\&    RXf_GPOS_SEEN
+\&    RXf_GPOS_FLOAT
+\&    RXf_ANCH_BOL
+\&    RXf_ANCH_MBOL
+\&    RXf_ANCH_SBOL
+\&    RXf_ANCH_GPOS
+.Ve
+.Sp
+As well as the follow flag masks:
+.Sp
+.Vb 2
+\&    RXf_ANCH_SINGLE
+\&    RXf_ANCH
+.Ve
+.Sp
+All have been renamed to PREGf_ equivalents and moved to regcomp.h.
+.Sp
+The behavior previously achieved by setting one or more of the RXf_ANCH_
+flags (via the RXf_ANCH mask) have now been replaced by a *single* flag bit
+in extflags:
+.Sp
+.Vb 1
+\&    RXf_IS_ANCHORED
+.Ve
+.Sp
+pluggable regex engines which previously used to set these flags should
+now set this flag ALONE.
+.IP \(bu 4
+The Perl core now consistently uses \f(CWav_tindex()\fR ("the top index of an
+array") as a more clearly-named synonym for \f(CWav_len()\fR.
+.IP \(bu 4
+The obscure interpreter variable \f(CW\*(C`PL_timesbuf\*(C'\fR is expected to be removed
+early in the 5.21.x development series, so that Perl 5.22.0 will not provide
+it to XS authors.  While the variable still exists in 5.20.0, we hope that
+this advance warning of the deprecation will help anyone who is using that
+variable.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS "Regular Expressions"
+.IX Subsection "Regular Expressions"
+.IP \(bu 4
+Fixed a small number of regexp constructions that could either fail to
+match or crash perl when the string being matched against was
+allocated above the 2GB line on 32\-bit systems. [RT #118175]
+.IP \(bu 4
+Various memory leaks involving the parsing of the \f(CW\*(C`(?[...])\*(C'\fR regular
+expression construct have been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`(?[...])\*(C'\fR now allows interpolation of precompiled patterns consisting of
+\&\f(CW\*(C`(?[...])\*(C'\fR with bracketed character classes inside (\f(CW\*(C`$pat =
+qr/(?[\ [a]\ ])/; /(?[\ $pat\ ])/\*(C'\fR).  Formerly, the brackets would
+confuse the regular expression parser.
+.IP \(bu 4
+The "Quantifier unexpected on zero-length expression" warning message could
+appear twice starting in Perl v5.10 for a regular expression also
+containing alternations (e.g., "a|b") triggering the trie optimisation.
+.IP \(bu 4
+Perl v5.18 inadvertently introduced a bug whereby interpolating mixed up\-
+and down-graded UTF\-8 strings in a regex could result in malformed UTF\-8
+in the pattern: specifically if a downgraded character in the range
+\&\f(CW\*(C`\ex80..\exff\*(C'\fR followed a UTF\-8 string, e.g.
+.Sp
+.Vb 3
+\&    utf8::upgrade(  my $u = "\ex{e5}");
+\&    utf8::downgrade(my $d = "\ex{e5}");
+\&    /$u$d/
+.Ve
+.Sp
+[RT #118297]
+.IP \(bu 4
+In regular expressions containing multiple code blocks, the values of
+\&\f(CW$1\fR, \f(CW$2\fR, etc., set by nested regular expression calls would leak from
+one block to the next.  Now these variables always refer to the outer
+regular expression at the start of an embedded block [perl #117917].
+.IP \(bu 4
+\&\f(CW\*(C`/$qr/p\*(C'\fR was broken in Perl 5.18.0; the \f(CW\*(C`/p\*(C'\fR flag was ignored.  This has been
+fixed. [perl #118213]
+.IP \(bu 4
+Starting in Perl 5.18.0, a construct like \f(CW\*(C`/[#](?{})/x\*(C'\fR would have its \f(CW\*(C`#\*(C'\fR
+incorrectly interpreted as a comment.  The code block would be skipped,
+unparsed.  This has been corrected.
+.IP \(bu 4
+Starting in Perl 5.001, a regular expression like \f(CW\*(C`/[#$a]/x\*(C'\fR or \f(CW\*(C`/[#]$a/x\*(C'\fR
+would have its \f(CW\*(C`#\*(C'\fR incorrectly interpreted as a comment, so the variable would
+not interpolate.  This has been corrected. [perl #45667]
+.IP \(bu 4
+Perl 5.18.0 inadvertently made dereferenced regular expressions
+(\f(CW\*(C`${\ qr//\ }\*(C'\fR) false as booleans.  This has been fixed.
+.IP \(bu 4
+The use of \f(CW\*(C`\eG\*(C'\fR in regular expressions, where it's not at the start of the
+pattern, is now slightly less buggy (although it is still somewhat
+problematic).
+.IP \(bu 4
+Where a regular expression included code blocks (\f(CW\*(C`/(?{...})/\*(C'\fR), and where the
+use of constant overloading triggered a re-compilation of the code block, the
+second compilation didn't see its outer lexical scope.  This was a regression
+in Perl 5.18.0.
+.IP \(bu 4
+The string position set by \f(CW\*(C`pos\*(C'\fR could shift if the string changed
+representation internally to or from utf8.  This could happen, e.g., with
+references to objects with string overloading.
+.IP \(bu 4
+Taking references to the return values of two \f(CW\*(C`pos\*(C'\fR calls with the same
+argument, and then assigning a reference to one and \f(CW\*(C`undef\*(C'\fR to the other,
+could result in assertion failures or memory leaks.
+.IP \(bu 4
+Elements of @\- and @+ now update correctly when they refer to non-existent
+captures.  Previously, a referenced element (\f(CW\*(C`$ref = \e$\-[1]\*(C'\fR) could refer to
+the wrong match after subsequent matches.
+.IP \(bu 4
+The code that parses regex backrefs (or ambiguous backref/octals) such as \e123
+did a simple \fBatoi()\fR, which could wrap round to negative values on long digit
+strings and cause segmentation faults.  This has now been fixed.  [perl
+#119505]
+.IP \(bu 4
+Assigning another typeglob to \f(CW\*(C`*^R\*(C'\fR no longer makes the regular expression
+engine crash.
+.IP \(bu 4
+The \f(CW\*(C`\eN\*(C'\fR regular expression escape, when used without the curly braces (to
+mean \f(CW\*(C`[^\en]\*(C'\fR), was ignoring a following \f(CW\*(C`*\*(C'\fR if followed by whitespace
+under /x.  It had been this way since \f(CW\*(C`\eN\*(C'\fR to mean \f(CW\*(C`[^\en]\*(C'\fR was introduced
+in 5.12.0.
+.IP \(bu 4
+\&\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR and \f(CW\*(C`y///\*(C'\fR now work when a wide character is used as the
+delimiter.  [perl #120463]
+.IP \(bu 4
+Some cases of unterminated (?...) sequences in regular expressions (e.g.,
+\&\f(CW\*(C`/(?</\*(C'\fR) have been fixed to produce the proper error message instead of
+"panic: memory wrap".  Other cases (e.g., \f(CW\*(C`/(?(/\*(C'\fR) have yet to be fixed.
+.IP \(bu 4
+When a reference to a reference to an overloaded object was returned from
+a regular expression \f(CW\*(C`(??{...})\*(C'\fR code block, an incorrect implicit
+dereference could take place if the inner reference had been returned by
+a code block previously.
+.IP \(bu 4
+A tied variable returned from \f(CW\*(C`(??{...})\*(C'\fR sees the inner values of match
+variables (i.e., the \f(CW$1\fR etc. from any matches inside the block) in its
+FETCH method.  This was not the case if a reference to an overloaded object
+was the last thing assigned to the tied variable.  Instead, the match
+variables referred to the outer pattern during the FETCH call.
+.IP \(bu 4
+Fix unexpected tainting via regexp using locale. Previously, under certain
+conditions, the use of character classes could cause tainting when it
+shouldn't. Some character classes are locale-dependent, but before this
+patch, sometimes tainting was happening even for character classes that
+don't depend on the locale. [perl #120675]
+.IP \(bu 4
+Under certain conditions, Perl would throw an error if in a lookbehind
+assertion in a regexp, the assertion referred to a named subpattern,
+complaining the lookbehind was variable when it wasn't. This has been
+fixed. [perl #120600], [perl #120618]. The current fix may be improved
+on in the future.
+.IP \(bu 4
+\&\f(CW$^R\fR wasn't available outside of the regular expression that
+initialized it.  [perl #121070]
+.IP \(bu 4
+A large set of fixes and refactoring for \fBre_intuit_start()\fR was merged,
+the highlights are:
+.RS 4
+.IP \(bu 4
+Fixed a panic when compiling the regular expression
+\&\f(CW\*(C`/\ex{100}[xy]\ex{100}{2}/\*(C'\fR.
+.IP \(bu 4
+Fixed a performance regression when performing a global pattern match
+against a UTF\-8 string.  [perl #120692]
+.IP \(bu 4
+Fixed another performance issue where matching a regular expression
+like \f(CW\*(C`/ab.{1,2}x/\*(C'\fR against a long UTF\-8 string would unnecessarily
+calculate byte offsets for a large portion of the string. [perl
+#120692]
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Fixed an alignment error when compiling regular expressions when built
+with GCC on HP-UX 64\-bit.
+.IP \(bu 4
+On 64\-bit platforms \f(CW\*(C`pos\*(C'\fR can now be set to a value higher than 2**31\-1.
+[perl #72766]
+.SS "Perl 5 Debugger and \-d"
+.IX Subsection "Perl 5 Debugger and -d"
+.IP \(bu 4
+The debugger's \f(CW\*(C`man\*(C'\fR command been fixed. It was broken in the v5.18.0
+release. The \f(CW\*(C`man\*(C'\fR command is aliased to the names \f(CW\*(C`doc\*(C'\fR and \f(CW\*(C`perldoc\*(C'\fR \-
+all now work again.
+.IP \(bu 4
+\&\f(CW@_\fR is now correctly visible in the debugger, fixing a regression
+introduced in v5.18.0's debugger. [RT #118169]
+.IP \(bu 4
+Under copy-on-write builds (the default as of 5.20.0) \f(CW\*(C`${\*(Aq_<\-e\*(Aq}[0]\*(C'\fR
+no longer gets mangled.  This is the first line of input saved for the
+debugger's use for one-liners [perl #118627].
+.IP \(bu 4
+On non-threaded builds, setting \f(CW\*(C`${"_<filename"}\*(C'\fR to a reference or
+typeglob no longer causes \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and some error messages to produce a
+corrupt string, and no longer prevents \f(CW\*(C`#line\*(C'\fR directives in string evals from
+providing the source lines to the debugger.  Threaded builds were unaffected.
+.IP \(bu 4
+Starting with Perl 5.12, line numbers were off by one if the \fB\-d\fR switch was
+used on the #! line.  Now they are correct.
+.IP \(bu 4
+\&\f(CW\*(C`*DB::DB = sub {} if 0\*(C'\fR no longer stops Perl's debugging mode from finding
+\&\f(CW\*(C`DB::DB\*(C'\fR subs declared thereafter.
+.IP \(bu 4
+\&\f(CW\*(C`%{\*(Aq_<...\*(Aq}\*(C'\fR hashes now set breakpoints on the corresponding \f(CW\*(C`@{\*(Aq_<...\*(Aq}\*(C'\fR
+rather than whichever array \f(CW@DB::dbline\fR is aliased to.  [perl #119799]
+.IP \(bu 4
+Call set-magic when setting \f(CW$DB::sub\fR.  [perl #121255]
+.IP \(bu 4
+The debugger's "n" command now respects lvalue subroutines and steps over
+them [perl #118839].
+.SS "Lexical Subroutines"
+.IX Subsection "Lexical Subroutines"
+.IP \(bu 4
+Lexical constants (\f(CW\*(C`my sub a() { 42 }\*(C'\fR) no longer crash when inlined.
+.IP \(bu 4
+Parameter prototypes attached to lexical subroutines are now respected when
+compiling sub calls without parentheses.  Previously, the prototypes were
+honoured only for calls \fIwith\fR parentheses. [RT #116735]
+.IP \(bu 4
+Syntax errors in lexical subroutines in combination with calls to the same
+subroutines no longer cause crashes at compile time.
+.IP \(bu 4
+Deep recursion warnings no longer crash lexical subroutines. [RT #118521]
+.IP \(bu 4
+The dtrace sub-entry probe now works with lexical subs, instead of
+crashing [perl #118305].
+.IP \(bu 4
+Undefining an inlinable lexical subroutine (\f(CWmy sub foo() { 42 } undef
+&foo\fR) would result in a crash if warnings were turned on.
+.IP \(bu 4
+An undefined lexical sub used as an inherited method no longer crashes.
+.IP \(bu 4
+The presence of a lexical sub named "CORE" no longer stops the CORE::
+prefix from working.
+.SS "Everything Else"
+.IX Subsection "Everything Else"
+.IP \(bu 4
+The OP allocation code now returns correctly aligned memory in all cases
+for \f(CW\*(C`struct pmop\*(C'\fR. Previously it could return memory only aligned to a
+4\-byte boundary, which is not correct for an ithreads build with 64 bit IVs
+on some 32 bit platforms. Notably, this caused the build to fail completely
+on sparc GNU/Linux. [RT #118055]
+.IP \(bu 4
+Evaluating large hashes in scalar context is now much faster, as the number
+of used chains in the hash is now cached for larger hashes. Smaller hashes
+continue not to store it and calculate it when needed, as this saves one IV.
+That would be 1 IV overhead for every object built from a hash. [RT #114576]
+.IP \(bu 4
+Perl v5.16 inadvertently introduced a bug whereby calls to XSUBs that were
+not visible at compile time were treated as lvalues and could be assigned
+to, even when the subroutine was not an lvalue sub.  This has been fixed.
+[RT #117947]
+.IP \(bu 4
+In Perl v5.18.0 dualvars that had an empty string for the string part but a
+non-zero number for the number part starting being treated as true.  In
+previous versions they were treated as false, the string representation
+taking precedence.  The old behaviour has been restored. [RT #118159]
+.IP \(bu 4
+Since Perl v5.12, inlining of constants that override built-in keywords of
+the same name had countermanded \f(CW\*(C`use subs\*(C'\fR, causing subsequent mentions of
+the constant to use the built-in keyword instead.  This has been fixed.
+.IP \(bu 4
+The warning produced by \f(CW\*(C`\-l $handle\*(C'\fR now applies to IO refs and globs, not
+just to glob refs.  That warning is also now UTF8\-clean. [RT #117595]
+.IP \(bu 4
+\&\f(CW\*(C`delete local $ENV{nonexistent_env_var}\*(C'\fR no longer leaks memory.
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR and \f(CW\*(C`require\*(C'\fR followed by a keyword prefixed with \f(CW\*(C`CORE::\*(C'\fR now
+treat it as a keyword, and not as a subroutine or module name. [RT #24482]
+.IP \(bu 4
+Through certain conundrums, it is possible to cause the current package to
+be freed.  Certain operators (\f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`reset\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`eval\*(C'\fR) could
+not cope and would crash.  They have been made more resilient. [RT #117941]
+.IP \(bu 4
+Aliasing filehandles through glob-to-glob assignment would not update
+internal method caches properly if a package of the same name as the
+filehandle existed, resulting in filehandle method calls going to the
+package instead.  This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`./Configure \-de \-Dusevendorprefix\*(C'\fR didn't default. [RT #64126]
+.IP \(bu 4
+The \f(CW\*(C`Statement unlikely to be reached\*(C'\fR warning was listed in
+perldiag as an \f(CW\*(C`exec\*(C'\fR\-category warning, but was enabled and disabled
+by the \f(CW\*(C`syntax\*(C'\fR category.  On the other hand, the \f(CW\*(C`exec\*(C'\fR category
+controlled its fatal-ness.  It is now entirely handled by the \f(CW\*(C`exec\*(C'\fR
+category.
+.IP \(bu 4
+The "Replacement list is longer that search list" warning for \f(CW\*(C`tr///\*(C'\fR and
+\&\f(CW\*(C`y///\*(C'\fR no longer occurs in the presence of the \f(CW\*(C`/c\*(C'\fR flag. [RT #118047]
+.IP \(bu 4
+Stringification of NVs are not cached so that the lexical locale controls
+stringification of the decimal point. [perl #108378] [perl #115800]
+.IP \(bu 4
+There have been several fixes related to Perl's handling of locales.  perl
+#38193 was described above in "Internal Changes".
+Also fixed is 
+#118197, where the radix (decimal point) character had to be an ASCII
+character (which doesn't work for some non-Western languages);
+and #115808, in which \f(CWPOSIX::setlocale()\fR on failure returned an
+\&\f(CW\*(C`undef\*(C'\fR which didn't warn about not being defined even if those
+warnings were enabled.
+.IP \(bu 4
+Compiling a \f(CW\*(C`split\*(C'\fR operator whose third argument is a named constant
+evaluating to 0 no longer causes the constant's value to change.
+.IP \(bu 4
+A named constant used as the second argument to \f(CW\*(C`index\*(C'\fR no longer gets
+coerced to a string if it is a reference, regular expression, dualvar, etc.
+.IP \(bu 4
+A named constant evaluating to the undefined value used as the second
+argument to \f(CW\*(C`index\*(C'\fR no longer produces "uninitialized" warnings at compile
+time.  It will still produce them at run time.
+.IP \(bu 4
+When a scalar was returned from a subroutine in \f(CW@INC\fR, the referenced scalar
+was magically converted into an IO thingy, possibly resulting in "Bizarre
+copy" errors if that scalar continued to be used elsewhere.  Now Perl uses
+an internal copy of the scalar instead.
+.IP \(bu 4
+Certain uses of the \f(CW\*(C`sort\*(C'\fR operator are optimised to modify an array in
+place, such as \f(CW\*(C`@a = sort @a\*(C'\fR.  During the sorting, the array is made
+read-only.  If a sort block should happen to die, then the array remained
+read-only even outside the \f(CW\*(C`sort\*(C'\fR.  This has been fixed.
+.IP \(bu 4
+\&\f(CW$a\fR and \f(CW$b\fR inside a sort block are aliased to the actual arguments to
+\&\f(CW\*(C`sort\*(C'\fR, so they can be modified through those two variables.  This did not
+always work, e.g., for lvalue subs and \f(CW$#ary\fR, and probably many other
+operators.  It works now.
+.IP \(bu 4
+The arguments to \f(CW\*(C`sort\*(C'\fR are now all in list context.  If the \f(CW\*(C`sort\*(C'\fR
+itself were called in void or scalar context, then \fIsome\fR, but not all, of
+the arguments used to be in void or scalar context.
+.IP \(bu 4
+Subroutine prototypes with Unicode characters above U+00FF were getting
+mangled during closure cloning.  This would happen with subroutines closing
+over lexical variables declared outside, and with lexical subs.
+.IP \(bu 4
+\&\f(CW\*(C`UNIVERSAL::can\*(C'\fR now treats its first argument the same way that method
+calls do: Typeglobs and glob references with non-empty IO slots are treated
+as handles, and strings are treated as filehandles, rather than packages,
+if a handle with that name exists [perl #113932].
+.IP \(bu 4
+Method calls on typeglobs (e.g., \f(CW\*(C`*ARGV\->getline\*(C'\fR) used to stringify
+the typeglob and then look it up again.  Combined with changes in Perl
+5.18.0, this allowed \f(CW\*(C`*foo\->bar\*(C'\fR to call methods on the "foo" package
+(like \f(CW\*(C`foo\->bar\*(C'\fR).  In some cases it could cause the method to be
+called on the wrong handle.  Now a typeglob argument is treated as a
+handle (just like \f(CW\*(C`(\e*foo)\->bar\*(C'\fR), or, if its IO slot is empty, an
+error is raised.
+.IP \(bu 4
+Assigning a vstring to a tied variable or to a subroutine argument aliased
+to a nonexistent hash or array element now works, without flattening the
+vstring into a regular string.
+.IP \(bu 4
+\&\f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR and \f(CW\*(C`untie\*(C'\fR did not work
+properly on subroutine arguments aliased to nonexistent
+hash and array elements [perl #77814, #27010].
+.IP \(bu 4
+The \f(CW\*(C`=>\*(C'\fR fat arrow operator can now quote built-in keywords even if it
+occurs on the next line, making it consistent with how it treats other
+barewords.
+.IP \(bu 4
+Autovivifying a subroutine stub via \f(CW\*(C`\e&$glob\*(C'\fR started causing crashes in Perl
+5.18.0 if the \f(CW$glob\fR was merely a copy of a real glob, i.e., a scalar that had
+had a glob assigned to it.  This has been fixed. [perl #119051]
+.IP \(bu 4
+Perl used to leak an implementation detail when it came to referencing the
+return values of certain operators.  \f(CW\*(C`for ($a+$b) { warn \e$_; warn \e$_ }\*(C'\fR used
+to display two different memory addresses, because the \f(CW\*(C`\e\*(C'\fR operator was
+copying the variable.  Under threaded builds, it would also happen for
+constants (\f(CW\*(C`for(1) { ... }\*(C'\fR).  This has been fixed. [perl #21979, #78194,
+#89188, #109746, #114838, #115388]
+.IP \(bu 4
+The range operator \f(CW\*(C`..\*(C'\fR was returning the same modifiable scalars with each
+call, unless it was the only thing in a \f(CW\*(C`foreach\*(C'\fR loop header.  This meant
+that changes to values within the list returned would be visible the next time
+the operator was executed. [perl #3105]
+.IP \(bu 4
+Constant folding and subroutine inlining no longer cause operations that would
+normally return new modifiable scalars to return read-only values instead.
+.IP \(bu 4
+Closures of the form \f(CW\*(C`sub () { $some_variable }\*(C'\fR are no longer inlined,
+causing changes to the variable to be ignored by callers of the subroutine.
+[perl #79908]
+.IP \(bu 4
+Return values of certain operators such as \f(CW\*(C`ref\*(C'\fR would sometimes be shared
+between recursive calls to the same subroutine, causing the inner call to
+modify the value returned by \f(CW\*(C`ref\*(C'\fR in the outer call.  This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR and constants returning a package name or hash key are now
+consistently read-only.  In various previous Perl releases, they have become
+mutable under certain circumstances.
+.IP \(bu 4
+Enabling "used once" warnings no longer causes crashes on stash circularities
+created at compile time (\f(CW\*(C`*Foo::Bar::Foo:: = *Foo::\*(C'\fR).
+.IP \(bu 4
+Undef constants used in hash keys (\f(CW\*(C`use constant u => undef; $h{+u}\*(C'\fR) no
+longer produce "uninitialized" warnings at compile time.
+.IP \(bu 4
+Modifying a substitution target inside the substitution replacement no longer
+causes crashes.
+.IP \(bu 4
+The first statement inside a string eval used to use the wrong pragma setting
+sometimes during constant folding.  \f(CW\*(C`eval \*(Aquc chr 0xe0\*(Aq\*(C'\fR would randomly choose
+between Unicode, byte, and locale semantics.  This has been fixed.
+.IP \(bu 4
+The handling of return values of \f(CW@INC\fR filters (subroutines returned by
+subroutines in \f(CW@INC\fR) has been fixed in various ways.  Previously tied variables
+were mishandled, and setting \f(CW$_\fR to a reference or typeglob could result in
+crashes.
+.IP \(bu 4
+The \f(CW\*(C`SvPVbyte\*(C'\fR XS function has been fixed to work with tied scalars returning
+something other than a string.  It used to return utf8 in those cases where
+\&\f(CW\*(C`SvPV\*(C'\fR would.
+.IP \(bu 4
+Perl 5.18.0 inadvertently made \f(CW\*(C`\-\-\*(C'\fR and \f(CW\*(C`++\*(C'\fR crash on dereferenced regular
+expressions, and stopped \f(CW\*(C`++\*(C'\fR from flattening vstrings.
+.IP \(bu 4
+\&\f(CW\*(C`bless\*(C'\fR no longer dies with "Can't bless non-reference value" if its first
+argument is a tied reference.
+.IP \(bu 4
+\&\f(CW\*(C`reset\*(C'\fR with an argument no longer skips copy-on-write scalars, regular
+expressions, typeglob copies, and vstrings.  Also, when encountering those or
+read-only values, it no longer skips any array or hash with the same name.
+.IP \(bu 4
+\&\f(CW\*(C`reset\*(C'\fR with an argument now skips scalars aliased to typeglobs
+(\f(CW\*(C`for $z (*foo) { reset "z" }\*(C'\fR).  Previously it would corrupt memory or crash.
+.IP \(bu 4
+\&\f(CW\*(C`ucfirst\*(C'\fR and \f(CW\*(C`lcfirst\*(C'\fR were not respecting the bytes pragma.  This was a
+regression from Perl 5.12. [perl #117355]
+.IP \(bu 4
+Changes to \f(CW\*(C`UNIVERSAL::DESTROY\*(C'\fR now update DESTROY caches in all classes,
+instead of causing classes that have already had objects destroyed to continue
+using the old sub.  This was a regression in Perl 5.18. [perl #114864]
+.IP \(bu 4
+All known false-positive occurrences of the deprecation warning "Useless use of
+\&'\e'; doesn't escape metacharacter '%c'", added in Perl 5.18.0, have been
+removed. [perl #119101]
+.IP \(bu 4
+The value of $^E is now saved across signal handlers on Windows.  [perl #85104]
+.IP \(bu 4
+A lexical filehandle (as in \f(CW\*(C`open my $fh...\*(C'\fR) is usually given a name based on
+the current package and the name of the variable, e.g. "main::$fh".  Under
+recursion, the filehandle was losing the "$fh" part of the name.  This has been
+fixed.
+.IP \(bu 4
+Uninitialized values returned by XSUBs are no longer exempt from uninitialized
+warnings.  [perl #118693]
+.IP \(bu 4
+\&\f(CW\*(C`elsif ("")\*(C'\fR no longer erroneously produces a warning about void context.
+[perl #118753]
+.IP \(bu 4
+Passing \f(CW\*(C`undef\*(C'\fR to a subroutine now causes \f(CW@_\fR to contain the same read-only
+undefined scalar that \f(CW\*(C`undef\*(C'\fR returns.  Furthermore, \f(CW\*(C`exists $_[0]\*(C'\fR will now
+return true if \f(CW\*(C`undef\*(C'\fR was the first argument.  [perl #7508, #109726]
+.IP \(bu 4
+Passing a non-existent array element to a subroutine does not usually
+autovivify it unless the subroutine modifies its argument.  This did not work
+correctly with negative indices and with non-existent elements within the
+array.  The element would be vivified immediately.  The delayed vivification
+has been extended to work with those.  [perl #118691]
+.IP \(bu 4
+Assigning references or globs to the scalar returned by $#foo after the \f(CW@foo\fR
+array has been freed no longer causes assertion failures on debugging builds
+and memory leaks on regular builds.
+.IP \(bu 4
+On 64\-bit platforms, large ranges like 1..1000000000000 no longer crash, but
+eat up all your memory instead.  [perl #119161]
+.IP \(bu 4
+\&\f(CW\*(C`_\|_DATA_\|_\*(C'\fR now puts the \f(CW\*(C`DATA\*(C'\fR handle in the right package, even if the
+current package has been renamed through glob assignment.
+.IP \(bu 4
+When \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`goto\*(C'\fR and \f(CW\*(C`exit\*(C'\fR unwind the scope,
+it is possible for \f(CW\*(C`DESTROY\*(C'\fR recursively to call a subroutine or format that
+is currently being exited.  It that case, sometimes the lexical variables
+inside the sub would start out having values from the outer call, instead of
+being undefined as they should.  This has been fixed.  [perl #119311]
+.IP \(bu 4
+${^MPEN} is no longer treated as a synonym for ${^MATCH}.
+.IP \(bu 4
+Perl now tries a little harder to return the correct line number in
+\&\f(CW\*(C`(caller)[2]\*(C'\fR.  [perl #115768]
+.IP \(bu 4
+Line numbers inside multiline quote-like operators are now reported correctly.
+[perl #3643]
+.IP \(bu 4
+\&\f(CW\*(C`#line\*(C'\fR directives inside code embedded in quote-like operators are now
+respected.
+.IP \(bu 4
+Line numbers are now correct inside the second here-doc when two here-doc
+markers occur on the same line.
+.IP \(bu 4
+An optimization in Perl 5.18 made incorrect assumptions causing a bad
+interaction with the Devel::CallParser CPAN module.  If the module was
+loaded then lexical variables declared in separate statements following a
+\&\f(CWmy(...)\fR list might fail to be cleared on scope exit.
+.IP \(bu 4
+\&\f(CW&xsub\fR and \f(CW\*(C`goto &xsub\*(C'\fR calls now allow the called subroutine to autovivify
+elements of \f(CW@_\fR.
+.IP \(bu 4
+\&\f(CW&xsub\fR and \f(CW\*(C`goto &xsub\*(C'\fR no longer crash if *_ has been undefined and has no
+ARRAY entry (i.e. \f(CW@_\fR does not exist).
+.IP \(bu 4
+\&\f(CW&xsub\fR and \f(CW\*(C`goto &xsub\*(C'\fR now work with tied \f(CW@_\fR.
+.IP \(bu 4
+Overlong identifiers no longer cause a buffer overflow (and a crash).  They
+started doing so in Perl 5.18.
+.IP \(bu 4
+The warning "Scalar value \f(CW@hash\fR{foo} better written as \f(CW$hash\fR{foo}" now produces
+far fewer false positives.  In particular, \f(CW@hash{+function_returning_a_list}\fR
+and \f(CW@hash{ qw "foo bar baz" }\fR no longer warn.  The same applies to array
+slices.  [perl #28380, #114024]
+.IP \(bu 4
+\&\f(CW\*(C`$! = EINVAL; waitpid(0, WNOHANG);\*(C'\fR no longer goes into an internal infinite
+loop.  [perl #85228]
+.IP \(bu 4
+A possible segmentation fault in filehandle duplication has been fixed.
+.IP \(bu 4
+A subroutine in \f(CW@INC\fR can return a reference to a scalar containing the initial
+contents of the file.  However, that scalar was freed prematurely if not
+referenced elsewhere, giving random results.
+.IP \(bu 4
+\&\f(CW\*(C`last\*(C'\fR no longer returns values that the same statement has accumulated so
+far, fixing amongst other things the long-standing bug that \f(CW\*(C`push @a, last\*(C'\fR
+would try to return the \f(CW@a\fR, copying it like a scalar in the process and
+resulting in the error, "Bizarre copy of ARRAY in last."  [perl #3112]
+.IP \(bu 4
+In some cases, closing file handles opened to pipe to or from a process, which
+had been duplicated into a standard handle, would call perl's internal waitpid
+wrapper with a pid of zero.  With the fix for [perl #85228] this zero pid was
+passed to \f(CW\*(C`waitpid\*(C'\fR, possibly blocking the process.  This wait for process
+zero no longer occurs.  [perl #119893]
+.IP \(bu 4
+\&\f(CW\*(C`select\*(C'\fR used to ignore magic on the fourth (timeout) argument, leading to
+effects such as \f(CW\*(C`select\*(C'\fR blocking indefinitely rather than the expected sleep
+time.  This has now been fixed.  [perl #120102]
+.IP \(bu 4
+The class name in \f(CW\*(C`for my class $foo\*(C'\fR is now parsed correctly.  In the case of
+the second character of the class name being followed by a digit (e.g. 'a1b')
+this used to give the error "Missing $ on loop variable".  [perl #120112]
+.IP \(bu 4
+Perl 5.18.0 accidentally disallowed \f(CW\*(C`\-bareword\*(C'\fR under \f(CW\*(C`use strict\*(C'\fR and
+\&\f(CW\*(C`use integer\*(C'\fR.  This has been fixed.  [perl #120288]
+.IP \(bu 4
+\&\f(CW\*(C`\-a\*(C'\fR at the start of a line (or a hyphen with any single letter that is
+not a filetest operator) no longer produces an erroneous 'Use of "\-a"
+without parentheses is ambiguous' warning.  [perl #120288]
+.IP \(bu 4
+Lvalue context is now properly propagated into bare blocks and \f(CW\*(C`if\*(C'\fR and
+\&\f(CW\*(C`else\*(C'\fR blocks in lvalue subroutines.  Previously, arrays and hashes would
+sometimes incorrectly be flattened when returned in lvalue list context, or
+"Bizarre copy" errors could occur.  [perl #119797]
+.IP \(bu 4
+Lvalue context is now propagated to the branches of \f(CW\*(C`||\*(C'\fR and \f(CW\*(C`&&\*(C'\fR (and
+their alphabetic equivalents, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`and\*(C'\fR).  This means
+\&\f(CW\*(C`foreach (pos $x || pos $y) {...}\*(C'\fR now allows \f(CW\*(C`pos\*(C'\fR to be modified
+through \f(CW$_\fR.
+.IP \(bu 4
+\&\f(CW\*(C`stat\*(C'\fR and \f(CW\*(C`readline\*(C'\fR remember the last handle used; the former
+for the special \f(CW\*(C`_\*(C'\fR filehandle, the latter for \f(CW\*(C`${^LAST_FH}\*(C'\fR.
+\&\f(CW\*(C`eval "*foo if 0"\*(C'\fR where *foo was the last handle passed to \f(CW\*(C`stat\*(C'\fR
+or \f(CW\*(C`readline\*(C'\fR could cause that handle to be forgotten if the
+handle were not opened yet.  This has been fixed.
+.IP \(bu 4
+Various cases of \f(CW\*(C`delete $::{a}\*(C'\fR, \f(CW\*(C`delete $::{ENV}\*(C'\fR etc. causing a crash
+have been fixed.  [perl #54044]
+.IP \(bu 4
+Setting \f(CW$!\fR to EACCESS before calling \f(CW\*(C`require\*(C'\fR could affect
+\&\f(CW\*(C`require\*(C'\fR's behaviour.  This has been fixed.
+.IP \(bu 4
+The "Can't use \e1 to mean \f(CW$1\fR in expression" warning message now only occurs
+on the right-hand (replacement) part of a substitution.  Formerly it could
+happen in code embedded in the left-hand side, or in any other quote-like
+operator.
+.IP \(bu 4
+Blessing into a reference (\f(CW\*(C`bless $thisref, $thatref\*(C'\fR) has long been
+disallowed, but magical scalars for the second like \f(CW$/\fR and those tied
+were exempt.  They no longer are.  [perl #119809]
+.IP \(bu 4
+Blessing into a reference was accidentally allowed in 5.18 if the class
+argument were a blessed reference with stale method caches (i.e., whose
+class had had subs defined since the last method call).  They are
+disallowed once more, as in 5.16.
+.IP \(bu 4
+\&\f(CW\*(C`$x\->{key}\*(C'\fR where \f(CW$x\fR was declared as \f(CW\*(C`my Class $x\*(C'\fR no longer crashes
+if a Class::FIELDS subroutine stub has been declared.
+.IP \(bu 4
+\&\f(CW@$obj{\*(Aqkey\*(Aq}\fR and \f(CW\*(C`${$obj}{key}\*(C'\fR used to be exempt from compile-time
+field checking ("No such class field"; see fields) but no longer are.
+.IP \(bu 4
+A nonexistent array element with a large index passed to a subroutine that
+ties the array and then tries to access the element no longer results in a
+crash.
+.IP \(bu 4
+Declaring a subroutine stub named NEGATIVE_INDICES no longer makes negative
+array indices crash when the current package is a tied array class.
+.IP \(bu 4
+Declaring a \f(CW\*(C`require\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, or \f(CW\*(C`do\*(C'\fR subroutine stub in the
+CORE::GLOBAL:: package no longer makes compilation of calls to the
+corresponding functions crash.
+.IP \(bu 4
+Aliasing CORE::GLOBAL:: functions to constants stopped working in Perl 5.10
+but has now been fixed.
+.IP \(bu 4
+When \f(CW\`...\`\fR or \f(CW\*(C`qx/.../\*(C'\fR calls a \f(CW\*(C`readpipe\*(C'\fR override, double-quotish
+interpolation now happens, as is the case when there is no override.
+Previously, the presence of an override would make these quote-like
+operators act like \f(CW\*(C`q{}\*(C'\fR, suppressing interpolation.  [perl #115330]
+.IP \(bu 4
+\&\f(CW\*(C`<<<\`...\`\*(C'\fR here-docs (with backticks as the delimiters) now call
+\&\f(CW\*(C`readpipe\*(C'\fR overrides.  [perl #119827]
+.IP \(bu 4
+\&\f(CW&CORE::exit()\fR and \f(CW&CORE::die()\fR now respect vmsish hints.
+.IP \(bu 4
+Undefining a glob that triggers a DESTROY method that undefines the same
+glob is now safe.  It used to produce "Attempt to free unreferenced glob
+pointer" warnings and leak memory.
+.IP \(bu 4
+If subroutine redefinition (\f(CW\*(C`eval \*(Aqsub foo{}\*(Aq\*(C'\fR or \f(CW\*(C`newXS\*(C'\fR for XS code)
+triggers a DESTROY method on the sub that is being redefined, and that
+method assigns a subroutine to the same slot (\f(CW\*(C`*foo = sub {}\*(C'\fR), \f(CW$_[0]\fR
+is no longer left pointing to a freed scalar.  Now DESTROY is delayed until
+the new subroutine has been installed.
+.IP \(bu 4
+On Windows, perl no longer calls \fBCloseHandle()\fR on a socket handle.  This makes
+debugging easier on Windows by removing certain irrelevant bad handle
+exceptions.  It also fixes a race condition that made socket functions randomly
+fail in a Perl process with multiple OS threads, and possible test failures in
+\&\fIdist/IO/t/cachepropagate\-tcp.t\fR.  [perl #120091/118059]
+.IP \(bu 4
+Formats involving UTF\-8 encoded strings, or strange vars like ties,
+overloads, or stringified refs (and in recent
+perls, pure NOK vars) would generally do the wrong thing in formats
+when the var is treated as a string and repeatedly chopped, as in
+\&\f(CW\*(C`^<<<~~\*(C'\fR and similar. This has now been resolved.
+[perl #33832/45325/113868/119847/119849/119851]
+.IP \(bu 4
+\&\f(CW\*(C`semctl(..., SETVAL, ...)\*(C'\fR would set the semaphore to the top
+32\-bits of the supplied integer instead of the bottom 32\-bits on
+64\-bit big-endian systems. [perl #120635]
+.IP \(bu 4
+\&\f(CWreaddir()\fR now only sets \f(CW$!\fR on error.  \f(CW$!\fR is no longer set
+to \f(CW\*(C`EBADF\*(C'\fR when then terminating \f(CW\*(C`undef\*(C'\fR is read from the directory
+unless the system call sets \f(CW$!\fR. [perl #118651]
+.IP \(bu 4
+\&\f(CW&CORE::glob\fR no longer causes an intermittent crash due to perl's stack
+getting corrupted. [perl #119993]
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR with layers that load modules (e.g., "<:encoding(utf8)") no longer
+runs the risk of crashing due to stack corruption.
+.IP \(bu 4
+Perl 5.18 broke autoloading via \f(CW\*(C`\->SUPER::foo\*(C'\fR method calls by looking
+up AUTOLOAD from the current package rather than the current package's
+superclass.  This has been fixed. [perl #120694]
+.IP \(bu 4
+A longstanding bug causing \f(CW\*(C`do {} until CONSTANT\*(C'\fR, where the constant
+holds a true value, to read unallocated memory has been resolved.  This
+would usually happen after a syntax error.  In past versions of Perl it has
+crashed intermittently. [perl #72406]
+.IP \(bu 4
+Fix HP-UX \f(CW$!\fR failure. HP-UX \fBstrerror()\fR returns an empty string for an
+unknown error code.  This caused an assertion to fail under DEBUGGING
+builds.  Now instead, the returned string for \f(CW"$!"\fR contains text
+indicating the code is for an unknown error.
+.IP \(bu 4
+Individually-tied elements of \f(CW@INC\fR (as in \f(CW\*(C`tie $INC[0]...\*(C'\fR) are now
+handled correctly.  Formerly, whether a sub returned by such a tied element
+would be treated as a sub depended on whether a FETCH had occurred
+previously.
+.IP \(bu 4
+\&\f(CW\*(C`getc\*(C'\fR on a byte-sized handle after the same \f(CW\*(C`getc\*(C'\fR operator had been
+used on a utf8 handle used to treat the bytes as utf8, resulting in erratic
+behavior (e.g., malformed UTF\-8 warnings).
+.IP \(bu 4
+An initial \f(CW\*(C`{\*(C'\fR at the beginning of a format argument line was always
+interpreted as the beginning of a block prior to v5.18.  In Perl v5.18, it
+started being treated as an ambiguous token.  The parser would guess
+whether it was supposed to be an anonymous hash constructor or a block
+based on the contents.  Now the previous behaviour has been restored.
+[perl #119973]
+.IP \(bu 4
+In Perl v5.18 \f(CW\*(C`undef *_; goto &sub\*(C'\fR and \f(CW\*(C`local *_; goto &sub\*(C'\fR started
+crashing.  This has been fixed. [perl #119949]
+.IP \(bu 4
+Backticks (\f(CW \`\` \fR or \f(CW\*(C` qx// \*(C'\fR) combined with multiple threads on
+Win32 could result in output sent to stdout on one thread being
+captured by backticks of an external command in another thread.
+.Sp
+This could occur for pseudo-forked processes too, as Win32's
+pseudo-fork is implemented in terms of threads.  [perl #77672]
+.IP \(bu 4
+\&\f(CW\*(C`open $fh, ">+", undef\*(C'\fR no longer leaks memory when TMPDIR is set
+but points to a directory a temporary file cannot be created in.  [perl
+#120951]
+.IP \(bu 4
+\&\f(CW\*(C` for ( $h{k} || \*(Aq\*(Aq ) \*(C'\fR no longer auto-vivifies \f(CW$h{k}\fR.  [perl
+#120374]
+.IP \(bu 4
+On Windows machines, Perl now emulates the POSIX use of the environment
+for locale initialization.  Previously, the environment was ignored.
+See "ENVIRONMENT" in perllocale.
+.IP \(bu 4
+Fixed a crash when destroying a self-referencing GLOB.  [perl #121242]
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+IO::Socket is known to fail tests on AIX 5.3.  There is
+a patch <https://github.com/Perl/perl5/issues/13484> in the request
+tracker, #120835, which may be applied to future releases.
+.IP \(bu 4
+The following modules are known to have test failures with this version of
+Perl.  Patches have been submitted, so there will hopefully be new releases
+soon:
+.RS 4
+.IP \(bu 4
+Data::Structure::Util version 0.15
+.IP \(bu 4
+HTML::StripScripts version 1.05
+.IP \(bu 4
+List::Gather version 0.08.
+.RE
+.RS 4
+.RE
+.SH Obituary
+.IX Header "Obituary"
+Diana Rosa, 27, of Rio de Janeiro, went to her long rest on May 10,
+2014, along with the plush camel she kept hanging on her computer screen
+all the time. She was a passionate Perl hacker who loved the language and its
+community, and who never missed a Rio.pm event. She was a true artist, an
+enthusiast about writing code, singing arias and graffiting walls. We'll never
+forget you.
+.PP
+Greg McCarroll died on August 28, 2013.
+.PP
+Greg was well known for many good reasons. He was one of the organisers of
+the first YAPC::Europe, which concluded with an unscheduled auction where he
+frantically tried to raise extra money to avoid the conference making a
+loss. It was Greg who mistakenly arrived for a london.pm meeting a week
+late; some years later he was the one who sold the choice of official
+meeting date at a YAPC::Europe auction, and eventually as glorious leader of
+london.pm he got to inherit the irreverent confusion that he had created.
+.PP
+Always helpful, friendly and cheerfully optimistic, you will be missed, but
+never forgotten.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.20.0 represents approximately 12 months of development since Perl 5.18.0
+and contains approximately 470,000 lines of changes across 2,900 files from 124
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 280,000 lines of changes to 1,800 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.20.0:
+.PP
+Aaron Crane, Abhijit Menon-Sen, Abigail, Abir Viqar, Alan Haggai Alavi, Alan
+Hourihane, Alexander Voronov, Alexandr Ciornii, Andy Dougherty, Anno Siegel,
+Aristotle Pagaltzis, Arthur Axel 'fREW' Schmidt, Brad Gilbert, Brendan Byrd,
+Brian Childs, Brian Fraser, Brian Gottreu, Chris 'BinGOs' Williams, Christian
+Millour, Colin Kuskie, Craig A. Berry, Dabrien 'Dabe' Murphy, Dagfinn Ilmari
+Mannsåker, Daniel Dragan, Darin McBride, David Golden, David Leadbeater, David
+Mitchell, David Nicol, David Steinbrunner, Dennis Kaarsemaker, Dominic
+Hargreaves, Ed Avis, Eric Brine, Evan Zacks, Father Chrysostomos, Florian
+Ragwitz, François Perrad, Gavin Shelley, Gideon Israel Dsouza, Gisle Aas,
+Graham Knop, H.Merijn Brand, Hauke D, Heiko Eissfeldt, Hiroo Hayashi, Hojung
+Youn, James E Keenan, Jarkko Hietaniemi, Jerry D. Hedden, Jess Robinson, Jesse
+Luehrs, Johan Vromans, John Gardiner Myers, John Goodyear, John P. Linderman,
+John Peacock, kafka, Kang-min Liu, Karen Etheridge, Karl Williamson, Keedi Kim,
+Kent Fredric, kevin dawson, Kevin Falcone, Kevin Ryde, Leon Timmermans, Lukas
+Mai, Marc Simpson, Marcel Grünauer, Marco Peereboom, Marcus Holland-Moritz,
+Mark Jason Dominus, Martin McGrath, Matthew Horsfall, Max Maischein, Mike
+Doherty, Moritz Lenz, Nathan Glenn, Nathan Trapuzzano, Neil Bowers, Neil
+Williams, Nicholas Clark, Niels Thykier, Niko Tyni, Olivier Mengué, Owain G.
+Ainsworth, Paul Green, Paul Johnson, Peter John Acklam, Peter Martini, Peter
+Rabbitson, Petr Písař, Philip Boulain, Philip Guenther, Piotr Roszatycki,
+Rafael Garcia-Suarez, Reini Urban, Reuben Thomas, Ricardo Signes, Ruslan
+Zakirov, Sergey Alekseev, Shirakata Kentaro, Shlomi Fish, Slaven Rezic,
+Smylers, Steffen Müller, Steve Hay, Sullivan Beck, Thomas Sibley, Tobias
+Leich, Toby Inkster, Tokuhiro Matsuno, Tom Christiansen, Tom Hukins, Tony Cook,
+Victor Efimov, Viktor Turskyi, Vladimir Timofeev, YAMASHINA Hio, Yves Orton,
+Zefram, Zsbán Ambrus, Ævar Arnfjörð Bjarmason.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5201delta.1 b/upstream/mageia-cauldron/man1/perl5201delta.1
new file mode 100644
index 00000000..db011ba9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5201delta.1
@@ -0,0 +1,340 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5201DELTA 1"
+.TH PERL5201DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5201delta \- what is new for perl v5.20.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.20.0 release and the 5.20.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.18.0, first read
+perl5200delta, which describes differences between 5.18.0 and 5.20.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.20.0.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting Bugs"
+below.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+An optimization to avoid problems with COW and deliberately overallocated PVs
+has been disabled because it interfered with another, more important,
+optimization, causing a slowdown on some platforms.
+[GH #13878] <https://github.com/Perl/perl5/issues/13878>
+.IP \(bu 4
+Returning a string from a lexical variable could be slow in some cases.  This
+has now been fixed.
+[GH #13880] <https://github.com/Perl/perl5/issues/13880>
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.20 to 0.22.
+.Sp
+The list of Perl versions covered has been updated and some flaws in the
+parsing have been fixed.
+.IP \(bu 4
+Exporter has been upgraded from version 5.70 to 5.71.
+.Sp
+Illegal POD syntax in the documentation has been corrected.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280216 to 0.280217.
+.Sp
+Android builds now link to both \fB\-lperl\fR and \f(CW$Config::Config{perllibs}\fR.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.29 to 2.30.
+.Sp
+The documentation now notes that \f(CW\*(C`copy\*(C'\fR will not overwrite read-only files.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 3.11 to 5.020001.
+.Sp
+The list of Perl versions covered has been updated.
+.IP \(bu 4
+The PathTools module collection has been upgraded from version 3.47 to 3.48.
+.Sp
+Fallbacks are now in place when cross-compiling for Android and
+\&\f(CW$Config::Config{sh}\fR is not yet defined.
+[GH #13872] <https://github.com/Perl/perl5/issues/13872>
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.14 to 0.15.
+.Sp
+A minor portability improvement has been made to the XS implementation.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.57 to 0.58.
+.Sp
+The documentation includes many clarifications and fixes.
+.IP \(bu 4
+utf8 has been upgraded from version 1.13 to 1.13_01.
+.Sp
+The documentation has some minor formatting improvements.
+.IP \(bu 4
+version has been upgraded from version 0.9908 to 0.9909.
+.Sp
+External libraries and Perl may have different ideas of what the locale is.
+This is problematic when parsing version strings if the locale's numeric
+separator has been changed.  Version parsing has been patched to ensure it
+handles the locales correctly.
+[GH #13863] <https://github.com/Perl/perl5/issues/13863>
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+\&\f(CW\*(C`av_len\*(C'\fR \- Emphasize that this returns the highest index in the array, not the
+size of the array.
+[GH #13377] <https://github.com/Perl/perl5/issues/13377>
+.IP \(bu 4
+Note that \f(CW\*(C`SvSetSV\*(C'\fR doesn't do set magic.
+.IP \(bu 4
+\&\f(CW\*(C`sv_usepvn_flags\*(C'\fR \- Fix documentation to mention the use of \f(CW\*(C`NewX\*(C'\fR instead of
+\&\f(CW\*(C`malloc\*(C'\fR.
+[GH #13835] <https://github.com/Perl/perl5/issues/13835>
+.IP \(bu 4
+Clarify where \f(CW\*(C`NUL\*(C'\fR may be embedded or is required to terminate a string.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+Clarify the meaning of \f(CW\*(C`\-B\*(C'\fR and \f(CW\*(C`\-T\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`\-l\*(C'\fR now notes that it will return false if symlinks aren't supported by the
+file system.
+[GH #13695] <https://github.com/Perl/perl5/issues/13695>
+.IP \(bu 4
+Note that \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR and \f(CW\*(C`values\*(C'\fR may produce different orderings for
+tied hashes compared to other perl hashes.
+[GH #13650] <https://github.com/Perl/perl5/issues/13650>
+.IP \(bu 4
+Note that \f(CW\*(C`exec LIST\*(C'\fR and \f(CW\*(C`system LIST\*(C'\fR may fall back to the shell on Win32.
+Only \f(CW\*(C`exec PROGRAM LIST\*(C'\fR and \f(CW\*(C`system PROGRAM LIST\*(C'\fR indirect object syntax
+will reliably avoid using the shell.  This has also been noted in perlport.
+[GH #13907] <https://github.com/Perl/perl5/issues/13907>
+.IP \(bu 4
+Clarify the meaning of \f(CW\*(C`our\*(C'\fR.
+[GH #13938] <https://github.com/Perl/perl5/issues/13938>
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+Explain various ways of modifying an existing SV's buffer.
+[GH #12813] <https://github.com/Perl/perl5/issues/12813>
+.PP
+\fIperlpolicy\fR
+.IX Subsection "perlpolicy"
+.IP \(bu 4
+We now have a code of conduct for the \fIp5p\fR mailing list, as documented in
+"STANDARDS OF CONDUCT" in perlpolicy.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+The \f(CW\*(C`/x\*(C'\fR modifier has been clarified to note that comments cannot be continued
+onto the next line by escaping them.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+Mention the use of empty conditionals in \f(CW\*(C`for\*(C'\fR/\f(CW\*(C`while\*(C'\fR loops for infinite
+loops.
+.PP
+\fIperlxs\fR
+.IX Subsection "perlxs"
+.IP \(bu 4
+Added a discussion of locale issues in XS code.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Variable length lookbehind not implemented in regex m/%s/
+.Sp
+Information about Unicode behaviour has been added.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Building Perl no longer writes to the source tree when configured with
+\&\fIConfigure\fR's \fB\-Dmksymlinks\fR option.
+[GH #13712] <https://github.com/Perl/perl5/issues/13712>
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Android 4
+.IX Item "Android"
+Build support has been improved for cross-compiling in general and for Android
+in particular.
+.IP OpenBSD 4
+.IX Item "OpenBSD"
+Corrected architectures and version numbers used in configuration hints when
+building Perl.
+.IP Solaris 4
+.IX Item "Solaris"
+\&\fBc99\fR options have been cleaned up, hints look for \fBsolstudio\fR as well as
+\&\fBSUNWspro\fR, and support for native \f(CW\*(C`setenv\*(C'\fR has been added.
+.IP VMS 4
+.IX Item "VMS"
+An old bug in feature checking, mainly affecting pre\-7.3 systems, has been
+fixed.
+.IP Windows 4
+.IX Item "Windows"
+\&\f(CW%I64d\fR is now being used instead of \f(CW%lld\fR for MinGW.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Added "sync_locale" in perlapi.
+Changing the program's locale should be avoided by XS code.  Nevertheless,
+certain non-Perl libraries called from XS, such as \f(CW\*(C`Gtk\*(C'\fR do so.  When this
+happens, Perl needs to be told that the locale has changed.  Use this function
+to do so, before returning to Perl.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+A bug has been fixed where zero-length assertions and code blocks inside of a
+regex could cause \f(CW\*(C`pos\*(C'\fR to see an incorrect value.
+[GH #14016] <https://github.com/Perl/perl5/issues/14016>
+.IP \(bu 4
+Using \f(CW\*(C`s///e\*(C'\fR on tainted utf8 strings could issue bogus "Malformed UTF\-8
+character (unexpected end of string)" warnings.  This has now been fixed.
+[GH #13948] <https://github.com/Perl/perl5/issues/13948>
+.IP \(bu 4
+\&\f(CW\*(C`system\*(C'\fR and friends should now work properly on more Android builds.
+.Sp
+Due to an oversight, the value specified through \fB\-Dtargetsh\fR to \fIConfigure\fR
+would end up being ignored by some of the build process.  This caused perls
+cross-compiled for Android to end up with defective versions of \f(CW\*(C`system\*(C'\fR,
+\&\f(CW\*(C`exec\*(C'\fR and backticks: the commands would end up looking for \fI/bin/sh\fR instead
+of \fI/system/bin/sh\fR, and so would fail for the vast majority of devices,
+leaving \f(CW$!\fR as \f(CW\*(C`ENOENT\*(C'\fR.
+.IP \(bu 4
+Many issues have been detected by Coverity <http://www.coverity.com/> and 
+fixed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.20.1 represents approximately 4 months of development since Perl 5.20.0
+and contains approximately 12,000 lines of changes across 170 files from 36
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 2,600 lines of changes to 110 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.20.1:
+.PP
+Aaron Crane, Abigail, Alberto Simões, Alexandr Ciornii, Alexandre (Midnite)
+Jousset, Andrew Fresh, Andy Dougherty, Brian Fraser, Chris 'BinGOs' Williams,
+Craig A. Berry, Daniel Dragan, David Golden, David Mitchell, H.Merijn Brand,
+James E Keenan, Jan Dubois, Jarkko Hietaniemi, John Peacock, kafka, Karen
+Etheridge, Karl Williamson, Lukas Mai, Matthew Horsfall, Michael Bunk, Peter
+Martini, Rafael Garcia-Suarez, Reini Urban, Ricardo Signes, Shirakata Kentaro,
+Smylers, Steve Hay, Thomas Sibley, Todd Rinaldo, Tony Cook, Vladimir Marek,
+Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at http://www.perl.org/ ,
+the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5202delta.1 b/upstream/mageia-cauldron/man1/perl5202delta.1
new file mode 100644
index 00000000..8e3cf47c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5202delta.1
@@ -0,0 +1,357 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5202DELTA 1"
+.TH PERL5202DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5202delta \- what is new for perl v5.20.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.20.1 release and the 5.20.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.20.0, first read
+perl5201delta, which describes differences between 5.20.0 and 5.20.1.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.20.1.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting Bugs"
+below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+attributes has been upgraded from version 0.22 to 0.23.
+.Sp
+The usage of \f(CW\*(C`memEQs\*(C'\fR in the XS has been corrected.
+[GH #14072] <https://github.com/Perl/perl5/issues/14072>
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.151 to 2.151_01.
+.Sp
+Fixes CVE\-2014\-4330 by adding a configuration variable/option to limit
+recursion when dumping deep data structures.
+.IP \(bu 4
+Errno has been upgraded from version 1.20_03 to 1.20_05.
+.Sp
+Warnings when building the XS on Windows with the Visual C++ compiler are now
+avoided.
+.IP \(bu 4
+feature has been upgraded from version 1.36 to 1.36_01.
+.Sp
+The \f(CW\*(C`postderef\*(C'\fR feature has now been documented.  This feature was actually
+added in Perl 5.20.0 but was accidentally omitted from the feature
+documentation until now.
+.IP \(bu 4
+IO::Socket has been upgraded from version 1.37 to 1.38.
+.Sp
+Document the limitations of the \fBconnected()\fR method.
+[GH #14199] <https://github.com/Perl/perl5/issues/14199>
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.020001 to 5.20150214.
+.Sp
+The list of Perl versions covered has been updated.
+.IP \(bu 4
+PathTools has been upgraded from version 3.48 to 3.48_01.
+.Sp
+A warning from the \fBgcc\fR compiler is now avoided when building the XS.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.18 to 0.18_01.
+.Sp
+Reading from a position well past the end of the scalar now correctly returns
+end of file.
+[GH #14342] <https://github.com/Perl/perl5/issues/14342>
+.Sp
+Seeking to a negative position still fails, but no longer leaves the file
+position set to a negation location.
+.Sp
+\&\f(CWeof()\fR on a \f(CW\*(C`PerlIO::scalar\*(C'\fR handle now properly returns true when the file
+position is past the 2GB mark on 32\-bit systems.
+.IP \(bu 4
+Storable has been upgraded from version 2.49 to 2.49_01.
+.Sp
+Minor grammatical change to the documentation only.
+.IP \(bu 4
+VMS::DCLsym has been upgraded from version 1.05 to 1.05_01.
+.Sp
+Minor formatting change to the documentation only.
+.IP \(bu 4
+VMS::Stdio has been upgraded from version 2.4 to 2.41.
+.Sp
+Minor formatting change to the documentation only.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlunicook\fR
+.IX Subsection "perlunicook"
+.PP
+This document, by Tom Christiansen, provides examples of handling Unicode in
+Perl.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlexperiment\fR
+.IX Subsection "perlexperiment"
+.IP \(bu 4
+Added reference to subroutine signatures.  This feature was actually added in
+Perl 5.20.0 but was accidentally omitted from the experimental feature
+documentation until now.
+.PP
+\fIperlpolicy\fR
+.IX Subsection "perlpolicy"
+.IP \(bu 4
+The process whereby features may graduate from experimental status has now been
+formally documented.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+An ambiguity in the documentation of the ellipsis statement has been corrected.
+[GH #14054] <https://github.com/Perl/perl5/issues/14054>
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Bad symbol for scalar is now documented.
+This error is not new, but was not previously documented here.
+.IP \(bu 4
+Missing right brace on \eN{} is now
+documented.  This error is not new, but was not previously documented here.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+The test script \fIre/rt122747.t\fR has been added to verify that
+[GH #14081] <https://github.com/Perl/perl5/issues/14081> remains
+fixed.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Regained Platforms"
+.IX Subsection "Regained Platforms"
+IRIX and Tru64 platforms are working again.  (Some \f(CW\*(C`make test\*(C'\fR failures
+remain.)
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+AIX now sets the length in \f(CW\*(C`getsockopt\*(C'\fR correctly.
+[GH #13484] <https://github.com/Perl/perl5/issues/13484>,
+[cpan #91183] <https://rt.cpan.org/Ticket/Display.html?id=91183>,
+[cpan #85570] <https://rt.cpan.org/Ticket/Display.html?id=85570>
+.IP \(bu 4
+In Perl 5.20.0, \f(CW$^N\fR accidentally had the internal UTF8 flag turned off if
+accessed from a code block within a regular expression, effectively
+UTF8\-encoding the value.  This has been fixed.
+[GH #14211] <https://github.com/Perl/perl5/issues/14211>
+.IP \(bu 4
+Various cases where the name of a sub is used (autoload, overloading, error
+messages) used to crash for lexical subs, but have been fixed.
+.IP \(bu 4
+An assertion failure when parsing \f(CW\*(C`sort\*(C'\fR with debugging enabled has been
+fixed.
+[GH #14087] <https://github.com/Perl/perl5/issues/14087>
+.IP \(bu 4
+Loading UTF8 tables during a regular expression match could cause assertion
+failures under debugging builds if the previous match used the very same
+regular expression.
+[GH #14081] <https://github.com/Perl/perl5/issues/14081>
+.IP \(bu 4
+Due to a mistake in the string-copying logic, copying the value of a state
+variable could instead steal the value and undefine the variable.  This bug,
+introduced in Perl 5.20, would happen mostly for long strings (1250 chars or
+more), but could happen for any strings under builds with copy-on-write
+disabled.
+[GH #14175] <https://github.com/Perl/perl5/issues/14175>
+.IP \(bu 4
+Fixed a bug that could cause perl to execute an infinite loop during
+compilation.
+[GH #14165] <https://github.com/Perl/perl5/issues/14165>
+.IP \(bu 4
+On Win32, restoring in a child pseudo-process a variable that was \f(CWlocal()\fRed
+in a parent pseudo-process before the \f(CW\*(C`fork\*(C'\fR happened caused memory corruption
+and a crash in the child pseudo-process (and therefore OS process).
+[GH #8641] <https://github.com/Perl/perl5/issues/8641>
+.IP \(bu 4
+Tainted constants evaluated at compile time no longer cause unrelated
+statements to become tainted.
+[GH #14059] <https://github.com/Perl/perl5/issues/14059>
+.IP \(bu 4
+Calling \f(CW\*(C`write\*(C'\fR on a format with a \f(CW\*(C`^**\*(C'\fR field could produce a panic in
+\&\fBsv_chop()\fR if there were insufficient arguments or if the variable used to fill
+the field was empty.
+[GH #14255] <https://github.com/Perl/perl5/issues/14255>
+.IP \(bu 4
+In Perl 5.20.0, \f(CW\*(C`sort CORE::fake\*(C'\fR where 'fake' is anything other than a
+keyword started chopping of the last 6 characters and treating the result as a
+sort sub name.  The previous behaviour of treating "CORE::fake" as a sort sub
+name has been restored.
+[GH #14323] <https://github.com/Perl/perl5/issues/14323>
+.IP \(bu 4
+A bug in regular expression patterns that could lead to segfaults and other
+crashes has been fixed.  This occurred only in patterns compiled with \f(CW"/i"\fR,
+while taking into account the current POSIX locale (this usually means they
+have to be compiled within the scope of \f(CW"use\ locale"\fR), and there must be
+a string of at least 128 consecutive bytes to match.
+[GH #14389] <https://github.com/Perl/perl5/issues/14389>
+.IP \(bu 4
+\&\f(CW\*(C`qr/@array(?{block})/\*(C'\fR no longer dies with "Bizarre copy of ARRAY".
+[GH #14292] <https://github.com/Perl/perl5/issues/14292>
+.IP \(bu 4
+\&\f(CW\*(C`gmtime\*(C'\fR no longer crashes with not-a-number values.
+[GH #14365] <https://github.com/Perl/perl5/issues/14365>
+.IP \(bu 4
+Certain syntax errors in substitutions, such as \f(CW\*(C`s/${<>{})//\*(C'\fR, would
+crash, and had done so since Perl 5.10.  (In some cases the crash did not start
+happening until Perl 5.16.)  The crash has, of course, been fixed.
+[GH #14391] <https://github.com/Perl/perl5/issues/14391>
+.IP \(bu 4
+A memory leak in some regular expressions, introduced in Perl 5.20.1, has been
+fixed.
+[GH #14236] <https://github.com/Perl/perl5/issues/14236>
+.IP \(bu 4
+\&\f(CW\*(C`formline("@...", "a");\*(C'\fR would crash.  The \f(CW\*(C`FF_CHECKNL\*(C'\fR case in
+\&\fBpp_formline()\fR didn't set the pointer used to mark the chop position, which led
+to the \f(CW\*(C`FF_MORE\*(C'\fR case crashing with a segmentation fault.  This has been
+fixed.
+[GH #14388] <https://github.com/Perl/perl5/issues/14388>
+[GH #14425] <https://github.com/Perl/perl5/issues/14425>
+.IP \(bu 4
+A possible buffer overrun and crash when parsing a literal pattern during
+regular expression compilation has been fixed.
+[GH #14416] <https://github.com/Perl/perl5/issues/14416>
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+It is a known bug that lexical subroutines cannot be used as the \f(CW\*(C`SUBNAME\*(C'\fR
+argument to \f(CW\*(C`sort\*(C'\fR.  This will be fixed in a future version of Perl.
+.SH "Errata From Previous Releases"
+.IX Header "Errata From Previous Releases"
+.IP \(bu 4
+A regression has been fixed that was introduced in Perl 5.20.0 (fixed in Perl
+5.20.1 as well as here) in which a UTF\-8 encoded regular expression pattern
+that contains a single ASCII lowercase letter does not match its uppercase
+counterpart.
+[GH #14051] <https://github.com/Perl/perl5/issues/14051>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.20.2 represents approximately 5 months of development since Perl 5.20.1
+and contains approximately 6,300 lines of changes across 170 files from 34
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,900 lines of changes to 80 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.20.2:
+.PP
+Aaron Crane, Abigail, Andreas Voegele, Andy Dougherty, Anthony Heading,
+Aristotle Pagaltzis, Chris 'BinGOs' Williams, Craig A. Berry, Daniel Dragan,
+Doug Bell, Ed J, Father Chrysostomos, Glenn D. Golden, H.Merijn Brand, Hugo van
+der Sanden, James E Keenan, Jarkko Hietaniemi, Jim Cromie, Karen Etheridge,
+Karl Williamson, kmx, Matthew Horsfall, Max Maischein, Peter Martini, Rafael
+Garcia-Suarez, Ricardo Signes, Shlomi Fish, Slaven Rezic, Steffen Müller,
+Steve Hay, Tadeusz Sośnierz, Tony Cook, Yves Orton, Ævar Arnfjörð
+Bjarmason.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at http://www.perl.org/ ,
+the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5203delta.1 b/upstream/mageia-cauldron/man1/perl5203delta.1
new file mode 100644
index 00000000..70c3bcb0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5203delta.1
@@ -0,0 +1,283 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5203DELTA 1"
+.TH PERL5203DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5203delta \- what is new for perl v5.20.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.20.2 release and the 5.20.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.20.1, first read
+perl5202delta, which describes differences between 5.20.1 and 5.20.2.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.20.2.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting Bugs"
+below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Errno has been upgraded from version 1.20_05 to 1.20_06.
+.Sp
+Add \fB\-P\fR to the pre-processor command-line on GCC 5.  GCC added extra line
+directives, breaking parsing of error code definitions.
+[GH #14491] <https://github.com/Perl/perl5/issues/14491>
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20150214 to 5.20150822.
+.Sp
+Updated to cover the latest releases of Perl.
+.IP \(bu 4
+perl5db.pl has been upgraded from 1.44 to 1.44_01.
+.Sp
+The debugger would cause an assertion failure.
+[GH #14605] <https://github.com/Perl/perl5/issues/14605>
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+Mention that \f(CWstudy()\fR is currently a no-op.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+The OOK example has been updated to account for COW changes and a change in the
+storage of the offset.
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+Documentation has been added illustrating the perils of assuming the contents
+of static memory pointed to by the return values of Perl wrappers for C library
+functions doesn't change.
+.PP
+\fIperlpodspec\fR
+.IX Subsection "perlpodspec"
+.IP \(bu 4
+The specification of the POD language is changing so that the default encoding
+of PODs that aren't in UTF\-8 (unless otherwise indicated) is CP1252 instead of
+ISO\-8859\-1 (Latin1).
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS h2ph
+.IX Subsection "h2ph"
+.IP \(bu 4
+\&\fBh2ph\fR now handles hexadecimal constants in the compiler's predefined macro
+definitions, as visible in \f(CW$Config{cppsymbols}\fR.
+[GH #14491] <https://github.com/Perl/perl5/issues/14491>
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+\&\fIt/perf/taint.t\fR has been added to see if optimisations with taint issues are
+keeping things fast.
+.IP \(bu 4
+\&\fIt/porting/re_context.t\fR has been added to test that utf8 and its
+dependencies only use the subset of the \f(CW\*(C`$1..$n\*(C'\fR capture vars that
+\&\fBPerl_save_re_context()\fR is hard-coded to localize, because that function has no
+efficient way of determining at runtime what vars to localize.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Previously, when compiling with a 64\-bit Visual C++, every Perl XS module
+(including CPAN ones) and Perl aware C file would unconditionally have around a
+dozen warnings from \fIhv_func.h\fR.  These warnings have been silenced.  GCC (all
+bitness) and 32\-bit Visual C++ were not affected.
+.IP \(bu 4
+\&\fBminiperl.exe\fR is now built with \fB\-fno\-strict\-aliasing\fR, allowing 64\-bit
+builds to complete with GCC 4.8.
+[GH #14556] <https://github.com/Perl/perl5/issues/14556>
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Repeated global pattern matches in scalar context on large tainted strings were
+exponentially slow depending on the current match position in the string.
+[GH #14238] <https://github.com/Perl/perl5/issues/14238>
+.IP \(bu 4
+The original visible value of \f(CW$/\fR is now preserved
+when it is set to an invalid value.  Previously if you set \f(CW$/\fR to a reference
+to an array, for example, perl would produce a runtime error and not set PL_rs,
+but Perl code that checked \f(CW$/\fR would see the array reference.
+[GH #14245] <https://github.com/Perl/perl5/issues/14245>
+.IP \(bu 4
+Perl 5.14.0 introduced a bug whereby \f(CW\*(C`eval { LABEL: }\*(C'\fR would crash.  This has
+been fixed.
+[GH #14438] <https://github.com/Perl/perl5/issues/14438>
+.IP \(bu 4
+Extending an array cloned from a parent thread could result in "Modification of
+a read-only value attempted" errors when attempting to modify the new elements.
+[GH #14605] <https://github.com/Perl/perl5/issues/14605>
+.IP \(bu 4
+Several cases of data used to store environment variable contents in core C
+code being potentially overwritten before being used have been fixed.
+[GH #14476] <https://github.com/Perl/perl5/issues/14476>
+.IP \(bu 4
+UTF\-8 variable names used in array indexes, unquoted UTF\-8 HERE-document
+terminators and UTF\-8 function names all now work correctly.
+[GH #14601] <https://github.com/Perl/perl5/issues/14601>
+.IP \(bu 4
+A subtle bug introduced in Perl 5.20.2 involving UTF\-8 in regular expressions
+and sometimes causing a crash has been fixed.  A new test script has been added
+to test this fix; see under "Testing".
+[GH #14600] <https://github.com/Perl/perl5/issues/14600>
+.IP \(bu 4
+Some patterns starting with \f(CW\*(C`/.*..../\*(C'\fR matched against long strings have been
+slow since Perl 5.8, and some of the form \f(CW\*(C`/.*..../i\*(C'\fR have been slow since
+Perl 5.18.  They are now all fast again.
+[GH #14475] <https://github.com/Perl/perl5/issues/14475>
+.IP \(bu 4
+Warning fatality is now ignored when rewinding the stack.  This prevents
+infinite recursion when the now fatal error also causes rewinding of the stack.
+[GH #14319] <https://github.com/Perl/perl5/issues/14319>
+.IP \(bu 4
+\&\f(CWsetpgrp($nonzero)\fR (with one argument) was accidentally changed in Perl 5.16
+to mean \f(CWsetpgrp(0)\fR.  This has been fixed.
+.IP \(bu 4
+A crash with \f(CW\*(C`%::=(); J\->${\e"::"}\*(C'\fR has been fixed.
+[GH #14790] <https://github.com/Perl/perl5/issues/14790>
+.IP \(bu 4
+Regular expression possessive quantifier Perl 5.20 regression now fixed.
+\&\f(CW\*(C`qr/\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`}+\*(C'\fR\f(CW\*(C`/\*(C'\fR is supposed to behave identically to
+\&\f(CW\*(C`qr/(?>\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`})/\*(C'\fR.  Since Perl 5.20, this didn't work
+if \fImin\fR and \fImax\fR were equal.
+[GH #14857] <https://github.com/Perl/perl5/issues/14857>
+.IP \(bu 4
+Code like \f(CW\*(C`/$a[/\*(C'\fR used to read the next line of input and treat it as though
+it came immediately after the opening bracket.  Some invalid code consequently
+would parse and run, but some code caused crashes, so this is now disallowed.
+[GH #14462] <https://github.com/Perl/perl5/issues/14462>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.20.3 represents approximately 7 months of development since Perl 5.20.2
+and contains approximately 3,200 lines of changes across 99 files from 26
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,500 lines of changes to 43 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.20.3:
+.PP
+Alex Vandiver, Andy Dougherty, Aristotle Pagaltzis, Chris 'BinGOs' Williams,
+Craig A. Berry, Dagfinn Ilmari Mannsåker, Daniel Dragan, David Mitchell,
+Father Chrysostomos, H.Merijn Brand, James E Keenan, James McCoy, Jarkko
+Hietaniemi, Karen Etheridge, Karl Williamson, kmx, Lajos Veres, Lukas Mai,
+Matthew Horsfall, Petr Písař, Randy Stauner, Ricardo Signes, Sawyer X, Steve
+Hay, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5220delta.1 b/upstream/mageia-cauldron/man1/perl5220delta.1
new file mode 100644
index 00000000..f7188d67
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5220delta.1
@@ -0,0 +1,3128 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5220DELTA 1"
+.TH PERL5220DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5220delta \- what is new for perl v5.22.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.20.0 release and the 5.22.0
+release.
+.PP
+If you are upgrading from an earlier release such as 5.18.0, first read
+perl5200delta, which describes differences between 5.18.0 and 5.20.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "New bitwise operators"
+.IX Subsection "New bitwise operators"
+A new experimental facility has been added that makes the four standard
+bitwise operators (\f(CW\*(C`& | ^ ~\*(C'\fR) treat their operands consistently as
+numbers, and introduces four new dotted operators (\f(CW\*(C`&. |. ^. ~.\*(C'\fR) that
+treat their operands consistently as strings.  The same applies to the
+assignment variants (\f(CW\*(C`&= |= ^= &.= |.= ^.=\*(C'\fR).
+.PP
+To use this, enable the "bitwise" feature and disable the
+"experimental::bitwise" warnings category.  See "Bitwise String
+Operators" in perlop for details.
+[GH #14348] <https://github.com/Perl/perl5/issues/14348>.
+.SS "New double-diamond operator"
+.IX Subsection "New double-diamond operator"
+\&\f(CW\*(C`<<>>\*(C'\fR is like \f(CW\*(C`<>\*(C'\fR but uses three-argument \f(CW\*(C`open\*(C'\fR to open
+each file in \f(CW@ARGV\fR.  This means that each element of \f(CW@ARGV\fR will be treated
+as an actual file name, and \f(CW"|foo"\fR won't be treated as a pipe open.
+.ie n .SS "New ""\eb"" boundaries in regular expressions"
+.el .SS "New \f(CW\eb\fP boundaries in regular expressions"
+.IX Subsection "New b boundaries in regular expressions"
+\fR\f(CI\*(C`qr/\eb{gcb}/\*(C'\fR\fI\fR
+.IX Subsection "qr/b{gcb}/"
+.PP
+\&\f(CW\*(C`gcb\*(C'\fR stands for Grapheme Cluster Boundary.  It is a Unicode property
+that finds the boundary between sequences of characters that look like a
+single character to a native speaker of a language.  Perl has long had
+the ability to deal with these through the \f(CW\*(C`\eX\*(C'\fR regular escape
+sequence.  Now, there is an alternative way of handling these.  See
+"\eb{}, \eb, \eB{}, \eB" in perlrebackslash for details.
+.PP
+\fR\f(CI\*(C`qr/\eb{wb}/\*(C'\fR\fI\fR
+.IX Subsection "qr/b{wb}/"
+.PP
+\&\f(CW\*(C`wb\*(C'\fR stands for Word Boundary.  It is a Unicode property
+that finds the boundary between words.  This is similar to the plain
+\&\f(CW\*(C`\eb\*(C'\fR (without braces) but is more suitable for natural language
+processing.  It knows, for example, that apostrophes can occur in the
+middle of words.  See "\eb{}, \eb, \eB{}, \eB" in perlrebackslash for details.
+.PP
+\fR\f(CI\*(C`qr/\eb{sb}/\*(C'\fR\fI\fR
+.IX Subsection "qr/b{sb}/"
+.PP
+\&\f(CW\*(C`sb\*(C'\fR stands for Sentence Boundary.  It is a Unicode property
+to aid in parsing natural language sentences.
+See "\eb{}, \eb, \eB{}, \eB" in perlrebackslash for details.
+.SS "Non-Capturing Regular Expression Flag"
+.IX Subsection "Non-Capturing Regular Expression Flag"
+Regular expressions now support a \f(CW\*(C`/n\*(C'\fR flag that disables capturing
+and filling in \f(CW$1\fR, \f(CW$2\fR, etc inside of groups:
+.PP
+.Vb 1
+\&  "hello" =~ /(hi|hello)/n; # $1 is not set
+.Ve
+.PP
+This is equivalent to putting \f(CW\*(C`?:\*(C'\fR at the beginning of every capturing group.
+.PP
+See "n" in perlre for more information.
+.ie n .SS """use re \*(Aqstrict\*(Aq"""
+.el .SS "\f(CWuse re \*(Aqstrict\*(Aq\fP"
+.IX Subsection "use re strict"
+This applies stricter syntax rules to regular expression patterns
+compiled within its scope. This will hopefully alert you to typos and
+other unintentional behavior that backwards-compatibility issues prevent
+us from reporting in normal regular expression compilations.  Because the
+behavior of this is subject to change in future Perl releases as we gain
+experience, using this pragma will raise a warning of category
+\&\f(CW\*(C`experimental::re_strict\*(C'\fR.
+See 'strict' in re.
+.SS "Unicode 7.0 (with correction) is now supported"
+.IX Subsection "Unicode 7.0 (with correction) is now supported"
+For details on what is in this release, see
+<http://www.unicode.org/versions/Unicode7.0.0/>.
+The version of Unicode 7.0 that comes with Perl includes
+a correction dealing with glyph shaping in Arabic
+(see <http://www.unicode.org/errata/#current_errata>).
+.ie n .SS """use\ locale"" can restrict which locale categories are affected"
+.el .SS "\f(CWuse\ locale\fP can restrict which locale categories are affected"
+.IX Subsection "use locale can restrict which locale categories are affected"
+It is now possible to pass a parameter to \f(CW\*(C`use\ locale\*(C'\fR to specify
+a subset of locale categories to be locale-aware, with the remaining
+ones unaffected.  See "The "use locale" pragma" in perllocale for details.
+.SS "Perl now supports POSIX 2008 locale currency additions"
+.IX Subsection "Perl now supports POSIX 2008 locale currency additions"
+On platforms that are able to handle POSIX.1\-2008, the
+hash returned by
+\&\f(CWPOSIX::localeconv()\fR
+includes the international currency fields added by that version of the
+POSIX standard.  These are
+\&\f(CW\*(C`int_n_cs_precedes\*(C'\fR,
+\&\f(CW\*(C`int_n_sep_by_space\*(C'\fR,
+\&\f(CW\*(C`int_n_sign_posn\*(C'\fR,
+\&\f(CW\*(C`int_p_cs_precedes\*(C'\fR,
+\&\f(CW\*(C`int_p_sep_by_space\*(C'\fR,
+and
+\&\f(CW\*(C`int_p_sign_posn\*(C'\fR.
+.SS "Better heuristics on older platforms for determining locale UTF\-8ness"
+.IX Subsection "Better heuristics on older platforms for determining locale UTF-8ness"
+On platforms that implement neither the C99 standard nor the POSIX 2001
+standard, determining if the current locale is UTF\-8 or not depends on
+heuristics.  These are improved in this release.
+.SS "Aliasing via reference"
+.IX Subsection "Aliasing via reference"
+Variables and subroutines can now be aliased by assigning to a reference:
+.PP
+.Vb 2
+\&    \e$c = \e$d;
+\&    \e&x = \e&y;
+.Ve
+.PP
+Aliasing can also be accomplished
+by using a backslash before a \f(CW\*(C`foreach\*(C'\fR iterator variable; this is
+perhaps the most useful idiom this feature provides:
+.PP
+.Vb 1
+\&    foreach \e%hash (@array_of_hash_refs) { ... }
+.Ve
+.PP
+This feature is experimental and must be enabled via \f(CWuse\ feature\ \*(Aqrefaliasing\*(Aq\fR.  It will warn unless the \f(CW\*(C`experimental::refaliasing\*(C'\fR
+warnings category is disabled.
+.PP
+See "Assigning to References" in perlref
+.ie n .SS """prototype"" with no arguments"
+.el .SS "\f(CWprototype\fP with no arguments"
+.IX Subsection "prototype with no arguments"
+\&\f(CWprototype()\fR with no arguments now infers \f(CW$_\fR.
+[GH #14376] <https://github.com/Perl/perl5/issues/14376>.
+.ie n .SS "New "":const"" subroutine attribute"
+.el .SS "New \f(CW:const\fP subroutine attribute"
+.IX Subsection "New :const subroutine attribute"
+The \f(CW\*(C`const\*(C'\fR attribute can be applied to an anonymous subroutine.  It
+causes the new sub to be executed immediately whenever one is created
+(\fIi.e.\fR when the \f(CW\*(C`sub\*(C'\fR expression is evaluated).  Its value is captured
+and used to create a new constant subroutine that is returned.  This
+feature is experimental.  See "Constant Functions" in perlsub.
+.ie n .SS """fileno"" now works on directory handles"
+.el .SS "\f(CWfileno\fP now works on directory handles"
+.IX Subsection "fileno now works on directory handles"
+When the relevant support is available in the operating system, the
+\&\f(CW\*(C`fileno\*(C'\fR builtin now works on directory handles, yielding the
+underlying file descriptor in the same way as for filehandles. On
+operating systems without such support, \f(CW\*(C`fileno\*(C'\fR on a directory handle
+continues to return the undefined value, as before, but also sets \f(CW$!\fR to
+indicate that the operation is not supported.
+.PP
+Currently, this uses either a \f(CW\*(C`dd_fd\*(C'\fR member in the OS \f(CW\*(C`DIR\*(C'\fR
+structure, or a \f(CWdirfd(3)\fR function as specified by POSIX.1\-2008.
+.SS "List form of pipe open implemented for Win32"
+.IX Subsection "List form of pipe open implemented for Win32"
+The list form of pipe:
+.PP
+.Vb 1
+\&  open my $fh, "\-|", "program", @arguments;
+.Ve
+.PP
+is now implemented on Win32.  It has the same limitations as \f(CW\*(C`system
+LIST\*(C'\fR on Win32, since the Win32 API doesn't accept program arguments
+as a list.
+.SS "Assignment to list repetition"
+.IX Subsection "Assignment to list repetition"
+\&\f(CW\*(C`(...) x ...\*(C'\fR can now be used within a list that is assigned to, as long
+as the left-hand side is a valid lvalue.  This allows \f(CW\*(C`(undef,undef,$foo)\ =\ that_function()\*(C'\fR to be written as \f(CW\*(C`((undef)x2,\ $foo)\ =\ that_function()\*(C'\fR.
+.SS "Infinity and NaN (not-a-number) handling improved"
+.IX Subsection "Infinity and NaN (not-a-number) handling improved"
+Floating point values are able to hold the special values infinity, negative
+infinity, and NaN (not-a-number).  Now we more robustly recognize and
+propagate the value in computations, and on output normalize them to the strings
+\&\f(CW\*(C`Inf\*(C'\fR, \f(CW\*(C`\-Inf\*(C'\fR, and \f(CW\*(C`NaN\*(C'\fR.
+.PP
+See also the POSIX enhancements.
+.SS "Floating point parsing has been improved"
+.IX Subsection "Floating point parsing has been improved"
+Parsing and printing of floating point values has been improved.
+.PP
+As a completely new feature, hexadecimal floating point literals
+(like \f(CW\*(C`0x1.23p\-4\*(C'\fR)  are now supported, and they can be output with
+\&\f(CW\*(C`printf\ "%a"\*(C'\fR. See "Scalar value constructors" in perldata for more
+details.
+.SS "Packing infinity or not-a-number into a character is now fatal"
+.IX Subsection "Packing infinity or not-a-number into a character is now fatal"
+Before, when trying to pack infinity or not-a-number into a
+(signed) character, Perl would warn, and assumed you tried to
+pack \f(CW0xFF\fR; if you gave it as an argument to \f(CW\*(C`chr\*(C'\fR,
+\&\f(CW\*(C`U+FFFD\*(C'\fR was returned.
+.PP
+But now, all such actions (\f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, and \f(CW\*(C`print \*(Aq%c\*(Aq\*(C'\fR)
+result in a fatal error.
+.SS "Experimental C Backtrace API"
+.IX Subsection "Experimental C Backtrace API"
+Perl now supports (via a C level API) retrieving
+the C level backtrace (similar to what symbolic debuggers like gdb do).
+.PP
+The backtrace returns the stack trace of the C call frames,
+with the symbol names (function names), the object names (like "perl"),
+and if it can, also the source code locations (file:line).
+.PP
+The supported platforms are Linux and OS X (some *BSD might work at
+least partly, but they have not yet been tested).
+.PP
+The feature needs to be enabled with \f(CW\*(C`Configure \-Dusecbacktrace\*(C'\fR.
+.PP
+See "C backtrace" in perlhacktips for more information.
+.SH Security
+.IX Header "Security"
+.ie n .SS "Perl is now compiled with ""\-fstack\-protector\-strong"" if available"
+.el .SS "Perl is now compiled with \f(CW\-fstack\-protector\-strong\fP if available"
+.IX Subsection "Perl is now compiled with -fstack-protector-strong if available"
+Perl has been compiled with the anti-stack-smashing option
+\&\f(CW\*(C`\-fstack\-protector\*(C'\fR since 5.10.1.  Now Perl uses the newer variant
+called \f(CW\*(C`\-fstack\-protector\-strong\*(C'\fR, if available.
+.SS "The Safe module could allow outside packages to be replaced"
+.IX Subsection "The Safe module could allow outside packages to be replaced"
+Critical bugfix: outside packages could be replaced.  Safe has
+been patched to 2.38 to address this.
+.ie n .SS "Perl is now always compiled with ""\-D_FORTIFY_SOURCE=2"" if available"
+.el .SS "Perl is now always compiled with \f(CW\-D_FORTIFY_SOURCE=2\fP if available"
+.IX Subsection "Perl is now always compiled with -D_FORTIFY_SOURCE=2 if available"
+The 'code hardening' option called \f(CW\*(C`_FORTIFY_SOURCE\*(C'\fR, available in
+gcc 4.*, is now always used for compiling Perl, if available.
+.PP
+Note that this isn't necessarily a huge step since in many platforms
+the step had already been taken several years ago: many Linux
+distributions (like Fedora) have been using this option for Perl,
+and OS X has enforced the same for many years.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Subroutine signatures moved before attributes"
+.IX Subsection "Subroutine signatures moved before attributes"
+The experimental sub signatures feature, as introduced in 5.20, parsed
+signatures after attributes. In this release, following feedback from users
+of the experimental feature, the positioning has been moved such that
+signatures occur after the subroutine name (if any) and before the attribute
+list (if any).
+.ie n .SS """&"" and ""\e&"" prototypes accepts only subs"
+.el .SS "\f(CW&\fP and \f(CW\e&\fP prototypes accepts only subs"
+.IX Subsection "& and & prototypes accepts only subs"
+The \f(CW\*(C`&\*(C'\fR prototype character now accepts only anonymous subs (\f(CW\*(C`sub
+{...}\*(C'\fR), things beginning with \f(CW\*(C`\e&\*(C'\fR, or an explicit \f(CW\*(C`undef\*(C'\fR.  Formerly
+it erroneously also allowed references to arrays, hashes, and lists.
+[GH #2776] <https://github.com/Perl/perl5/issues/2776>.
+[GH #14186] <https://github.com/Perl/perl5/issues/14186>.
+[GH #14353] <https://github.com/Perl/perl5/issues/14353>.
+.PP
+In addition, the \f(CW\*(C`\e&\*(C'\fR prototype was allowing subroutine calls, whereas
+now it only allows subroutines: \f(CW&foo\fR is still permitted as an argument,
+while \f(CW&foo()\fR and \f(CWfoo()\fR no longer are.
+[GH #10633] <https://github.com/Perl/perl5/issues/10633>.
+.ie n .SS """use encoding"" is now lexical"
+.el .SS "\f(CWuse encoding\fP is now lexical"
+.IX Subsection "use encoding is now lexical"
+The encoding pragma's effect is now limited to lexical scope.  This
+pragma is deprecated, but in the meantime, it could adversely affect
+unrelated modules that are included in the same program; this change
+fixes that.
+.SS "List slices returning empty lists"
+.IX Subsection "List slices returning empty lists"
+List slices now return an empty list only if the original list was empty
+(or if there are no indices).  Formerly, a list slice would return an empty
+list if all indices fell outside the original list; now it returns a list
+of \f(CW\*(C`undef\*(C'\fR values in that case.
+[GH #12335] <https://github.com/Perl/perl5/issues/12335>.
+.ie n .SS """\eN{}"" with a sequence of multiple spaces is now a fatal error"
+.el .SS "\f(CW\eN{}\fP with a sequence of multiple spaces is now a fatal error"
+.IX Subsection "N{} with a sequence of multiple spaces is now a fatal error"
+E.g. \f(CW\*(C`\eN{TOO\ \ MANY\ SPACES}\*(C'\fR or \f(CW\*(C`\eN{TRAILING\ SPACE\ }\*(C'\fR.
+This has been deprecated since v5.18.
+.ie n .SS """use\ UNIVERSAL\ \*(Aq...\*(Aq"" is now a fatal error"
+.el .SS "\f(CWuse\ UNIVERSAL\ \*(Aq...\*(Aq\fP is now a fatal error"
+.IX Subsection "use UNIVERSAL ... is now a fatal error"
+Importing functions from \f(CW\*(C`UNIVERSAL\*(C'\fR has been deprecated since v5.12, and
+is now a fatal error.  \f(CW\*(C`use\ UNIVERSAL\*(C'\fR without any arguments is still
+allowed.
+.ie n .SS "In double-quotish ""\ec\fIX\fP"", \fIX\fP must now be a printable ASCII character"
+.el .SS "In double-quotish \f(CW\ec\fP\f(CIX\fP\f(CW\fP, \fIX\fP must now be a printable ASCII character"
+.IX Subsection "In double-quotish cX, X must now be a printable ASCII character"
+In prior releases, failure to do this raised a deprecation warning.
+.ie n .SS "Splitting the tokens ""(?"" and ""(*"" in regular expressions is now a fatal compilation error."
+.el .SS "Splitting the tokens \f(CW(?\fP and \f(CW(*\fP in regular expressions is now a fatal compilation error."
+.IX Subsection "Splitting the tokens (? and (* in regular expressions is now a fatal compilation error."
+These had been deprecated since v5.18.
+.ie n .SS """qr/foo/x"" now ignores all Unicode pattern white space"
+.el .SS "\f(CWqr/foo/x\fP now ignores all Unicode pattern white space"
+.IX Subsection "qr/foo/x now ignores all Unicode pattern white space"
+The \f(CW\*(C`/x\*(C'\fR regular expression modifier allows the pattern to contain
+white space and comments (both of which are ignored) for improved
+readability.  Until now, not all the white space characters that Unicode
+designates for this purpose were handled.  The additional ones now
+recognized are:
+.PP
+.Vb 5
+\&    U+0085 NEXT LINE
+\&    U+200E LEFT\-TO\-RIGHT MARK
+\&    U+200F RIGHT\-TO\-LEFT MARK
+\&    U+2028 LINE SEPARATOR
+\&    U+2029 PARAGRAPH SEPARATOR
+.Ve
+.PP
+The use of these characters with \f(CW\*(C`/x\*(C'\fR outside bracketed character
+classes and when not preceded by a backslash has raised a deprecation
+warning since v5.18.  Now they will be ignored.
+.ie n .SS "Comment lines within ""(?[\ ])"" are now ended only by a ""\en"""
+.el .SS "Comment lines within \f(CW(?[\ ])\fP are now ended only by a \f(CW\en\fP"
+.IX Subsection "Comment lines within (?[ ]) are now ended only by a n"
+\&\f(CW\*(C`(?[\ ])\*(C'\fR  is an experimental feature, introduced in v5.18.  It operates
+as if \f(CW\*(C`/x\*(C'\fR is always enabled.  But there was a difference: comment
+lines (following a \f(CW\*(C`#\*(C'\fR character) were terminated by anything matching
+\&\f(CW\*(C`\eR\*(C'\fR which includes all vertical whitespace, such as form feeds.  For
+consistency, this is now changed to match what terminates comment lines
+outside \f(CW\*(C`(?[\ ])\*(C'\fR, namely a \f(CW\*(C`\en\*(C'\fR (even if escaped), which is the
+same as what terminates a heredoc string and formats.
+.ie n .SS """(?[...])"" operators now follow standard Perl precedence"
+.el .SS "\f(CW(?[...])\fP operators now follow standard Perl precedence"
+.IX Subsection "(?[...]) operators now follow standard Perl precedence"
+This experimental feature allows set operations in regular expression patterns.
+Prior to this, the intersection operator had the same precedence as the other
+binary operators.  Now it has higher precedence.  This could lead to different
+outcomes than existing code expects (though the documentation has always noted
+that this change might happen, recommending fully parenthesizing the
+expressions).  See "Extended Bracketed Character Classes" in perlrecharclass.
+.ie n .SS "Omitting ""%"" and ""@"" on hash and array names is no longer permitted"
+.el .SS "Omitting \f(CW%\fP and \f(CW@\fP on hash and array names is no longer permitted"
+.IX Subsection "Omitting % and @ on hash and array names is no longer permitted"
+Really old Perl let you omit the \f(CW\*(C`@\*(C'\fR on array names and the \f(CW\*(C`%\*(C'\fR on hash
+names in some spots.  This has issued a deprecation warning since Perl
+5.000, and is no longer permitted.
+.ie n .SS """$!"" text is now in English outside the scope of ""use locale"""
+.el .SS "\f(CW""$!""\fP text is now in English outside the scope of \f(CWuse locale\fP"
+.IX Subsection """$!"" text is now in English outside the scope of use locale"
+Previously, the text, unlike almost everything else, always came out
+based on the current underlying locale of the program.  (Also affected
+on some systems is \f(CW"$^E"\fR.)  For programs that are unprepared to
+handle locale differences, this can cause garbage text to be displayed.
+It's better to display text that is translatable via some tool than
+garbage text which is much harder to figure out.
+.ie n .SS """$!"" text will be returned in UTF\-8 when appropriate"
+.el .SS "\f(CW""$!""\fP text will be returned in UTF\-8 when appropriate"
+.IX Subsection """$!"" text will be returned in UTF-8 when appropriate"
+The stringification of \f(CW$!\fR and \f(CW$^E\fR will have the UTF\-8 flag set
+when the text is actually non-ASCII UTF\-8.  This will enable programs
+that are set up to be locale-aware to properly output messages in the
+user's native language.  Code that needs to continue the 5.20 and
+earlier behavior can do the stringification within the scopes of both
+\&\f(CW\*(C`use\ bytes\*(C'\fR and \f(CW\*(C`use\ locale\ ":messages"\*(C'\fR.  Within these two
+scopes, no other Perl operations will
+be affected by locale; only \f(CW$!\fR and \f(CW$^E\fR stringification.  The
+\&\f(CW\*(C`bytes\*(C'\fR pragma causes the UTF\-8 flag to not be set, just as in previous
+Perl releases.  This resolves
+[GH #12035] <https://github.com/Perl/perl5/issues/12035>.
+.ie n .SS "Support for ""?PATTERN?"" without explicit operator has been removed"
+.el .SS "Support for \f(CW?PATTERN?\fP without explicit operator has been removed"
+.IX Subsection "Support for ?PATTERN? without explicit operator has been removed"
+The \f(CW\*(C`m?PATTERN?\*(C'\fR construct, which allows matching a regex only once,
+previously had an alternative form that was written directly with a question
+mark delimiter, omitting the explicit \f(CW\*(C`m\*(C'\fR operator.  This usage has produced
+a deprecation warning since 5.14.0.  It is now a syntax error, so that the
+question mark can be available for use in new operators.
+.ie n .SS "defined(@array) and defined(%hash) are now fatal errors"
+.el .SS "\f(CWdefined(@array)\fP and \f(CWdefined(%hash)\fP are now fatal errors"
+.IX Subsection "defined(@array) and defined(%hash) are now fatal errors"
+These have been deprecated since v5.6.1 and have raised deprecation
+warnings since v5.16.
+.SS "Using a hash or an array as a reference are now fatal errors"
+.IX Subsection "Using a hash or an array as a reference are now fatal errors"
+For example, \f(CW\*(C`%foo\->{"bar"}\*(C'\fR now causes a fatal compilation
+error.  These have been deprecated since before v5.8, and have raised
+deprecation warnings since then.
+.ie n .SS "Changes to the ""*"" prototype"
+.el .SS "Changes to the \f(CW*\fP prototype"
+.IX Subsection "Changes to the * prototype"
+The \f(CW\*(C`*\*(C'\fR character in a subroutine's prototype used to allow barewords to take
+precedence over most, but not all, subroutine names.  It was never
+consistent and exhibited buggy behavior.
+.PP
+Now it has been changed, so subroutines always take precedence over barewords,
+which brings it into conformity with similarly prototyped built-in functions:
+.PP
+.Vb 6
+\&    sub splat(*) { ... }
+\&    sub foo { ... }
+\&    splat(foo); # now always splat(foo())
+\&    splat(bar); # still splat(\*(Aqbar\*(Aq) as before
+\&    close(foo); # close(foo())
+\&    close(bar); # close(\*(Aqbar\*(Aq)
+.Ve
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS "Setting ""${^ENCODING}"" to anything but ""undef"""
+.el .SS "Setting \f(CW${^ENCODING}\fP to anything but \f(CWundef\fP"
+.IX Subsection "Setting ${^ENCODING} to anything but undef"
+This variable allows Perl scripts to be written in an encoding other than
+ASCII or UTF\-8.  However, it affects all modules globally, leading
+to wrong answers and segmentation faults.  New scripts should be written
+in UTF\-8; old scripts should be converted to UTF\-8, which is easily done
+with the piconv utility.
+.SS "Use of non-graphic characters in single-character variable names"
+.IX Subsection "Use of non-graphic characters in single-character variable names"
+The syntax for single-character variable names is more lenient than
+for longer variable names, allowing the one-character name to be a
+punctuation character or even invisible (a non-graphic).  Perl v5.20
+deprecated the ASCII-range controls as such a name.  Now, all
+non-graphic characters that formerly were allowed are deprecated.
+The practical effect of this occurs only when not under \f(CW\*(C`use\ utf8\*(C'\fR, and affects just the C1 controls (code points 0x80 through
+0xFF), NO-BREAK SPACE, and SOFT HYPHEN.
+.ie n .SS "Inlining of ""sub () { $var }"" with observable side-effects"
+.el .SS "Inlining of \f(CWsub () { $var }\fP with observable side-effects"
+.IX Subsection "Inlining of sub () { $var } with observable side-effects"
+In many cases Perl makes \f(CW\*(C`sub\ ()\ {\ $var\ }\*(C'\fR into an inlinable constant
+subroutine, capturing the value of \f(CW$var\fR at the time the \f(CW\*(C`sub\*(C'\fR expression
+is evaluated.  This can break the closure behavior in those cases where
+\&\f(CW$var\fR is subsequently modified, since the subroutine won't return the
+changed value. (Note that this all only applies to anonymous subroutines
+with an empty prototype (\f(CW\*(C`sub\ ()\*(C'\fR).)
+.PP
+This usage is now deprecated in those cases where the variable could be
+modified elsewhere.  Perl detects those cases and emits a deprecation
+warning.  Such code will likely change in the future and stop producing a
+constant.
+.PP
+If your variable is only modified in the place where it is declared, then
+Perl will continue to make the sub inlinable with no warnings.
+.PP
+.Vb 4
+\&    sub make_constant {
+\&        my $var = shift;
+\&        return sub () { $var }; # fine
+\&    }
+\&
+\&    sub make_constant_deprecated {
+\&        my $var;
+\&        $var = shift;
+\&        return sub () { $var }; # deprecated
+\&    }
+\&
+\&    sub make_constant_deprecated2 {
+\&        my $var = shift;
+\&        log_that_value($var); # could modify $var
+\&        return sub () { $var }; # deprecated
+\&    }
+.Ve
+.PP
+In the second example above, detecting that \f(CW$var\fR is assigned to only once
+is too hard to detect.  That it happens in a spot other than the \f(CW\*(C`my\*(C'\fR
+declaration is enough for Perl to find it suspicious.
+.PP
+This deprecation warning happens only for a simple variable for the body of
+the sub.  (A \f(CW\*(C`BEGIN\*(C'\fR block or \f(CW\*(C`use\*(C'\fR statement inside the sub is ignored,
+because it does not become part of the sub's body.)  For more complex
+cases, such as \f(CW\*(C`sub\ ()\ {\ do_something()\ if\ 0;\ $var\ }\*(C'\fR the behavior has
+changed such that inlining does not happen if the variable is modifiable
+elsewhere.  Such cases should be rare.
+.ie n .SS "Use of multiple ""/x"" regexp modifiers"
+.el .SS "Use of multiple \f(CW/x\fP regexp modifiers"
+.IX Subsection "Use of multiple /x regexp modifiers"
+It is now deprecated to say something like any of the following:
+.PP
+.Vb 3
+\&    qr/foo/xx;
+\&    /(?xax:foo)/;
+\&    use re qw(/amxx);
+.Ve
+.PP
+That is, now \f(CW\*(C`x\*(C'\fR should only occur once in any string of contiguous
+regular expression pattern modifiers.  We do not believe there are any
+occurrences of this in all of CPAN.  This is in preparation for a future
+Perl release having \f(CW\*(C`/xx\*(C'\fR permit white-space for readability in
+bracketed character classes (those enclosed in square brackets:
+\&\f(CW\*(C`[...]\*(C'\fR).
+.ie n .SS "Using a NO-BREAK space in a character alias for ""\eN{...}"" is now deprecated"
+.el .SS "Using a NO-BREAK space in a character alias for \f(CW\eN{...}\fP is now deprecated"
+.IX Subsection "Using a NO-BREAK space in a character alias for N{...} is now deprecated"
+This non-graphic character is essentially indistinguishable from a
+regular space, and so should not be allowed.  See
+"CUSTOM ALIASES" in charnames.
+.ie n .SS "A literal ""{"" should now be escaped in a pattern"
+.el .SS "A literal \f(CW""{""\fP should now be escaped in a pattern"
+.IX Subsection "A literal ""{"" should now be escaped in a pattern"
+If you want a literal left curly bracket (also called a left brace) in a
+regular expression pattern, you should now escape it by either
+preceding it with a backslash (\f(CW"\e{"\fR) or enclosing it within square
+brackets \f(CW"[{]"\fR, or by using \f(CW\*(C`\eQ\*(C'\fR; otherwise a deprecation warning
+will be raised.  This was first announced as forthcoming in the v5.16
+release; it will allow future extensions to the language to happen.
+.SS "Making all warnings fatal is discouraged"
+.IX Subsection "Making all warnings fatal is discouraged"
+The documentation for fatal warnings notes that
+\&\f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq\*(C'\fR is discouraged, and provides stronger
+language about the risks of fatal warnings in general.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+If a method or class name is known at compile time, a hash is precomputed
+to speed up run-time method lookup.  Also, compound method names like
+\&\f(CW\*(C`SUPER::new\*(C'\fR are parsed at compile time, to save having to parse them at
+run time.
+.IP \(bu 4
+Array and hash lookups (especially nested ones) that use only constants
+or simple variables as keys, are now considerably faster. See
+"Internal Changes" for more details.
+.IP \(bu 4
+\&\f(CW\*(C`(...)x1\*(C'\fR, \f(CW\*(C`("constant")x0\*(C'\fR and \f(CW\*(C`($scalar)x0\*(C'\fR are now optimised in list
+context.  If the right-hand argument is a constant 1, the repetition
+operator disappears.  If the right-hand argument is a constant 0, the whole
+expression is optimised to the empty list, so long as the left-hand
+argument is a simple scalar or constant.  (That is, \f(CW\*(C`(foo())x0\*(C'\fR is not
+subject to this optimisation.)
+.IP \(bu 4
+\&\f(CW\*(C`substr\*(C'\fR assignment is now optimised into 4\-argument \f(CW\*(C`substr\*(C'\fR at the end
+of a subroutine (or as the argument to \f(CW\*(C`return\*(C'\fR).  Previously, this
+optimisation only happened in void context.
+.IP \(bu 4
+In \f(CW"\eL..."\fR, \f(CW"\eQ..."\fR, etc., the extra "stringify" op is now optimised
+away, making these just as fast as \f(CW\*(C`lcfirst\*(C'\fR, \f(CW\*(C`quotemeta\*(C'\fR, etc.
+.IP \(bu 4
+Assignment to an empty list is now sometimes faster.  In particular, it
+never calls \f(CW\*(C`FETCH\*(C'\fR on tied arguments on the right-hand side, whereas it
+used to sometimes.
+.IP \(bu 4
+There is a performance improvement of up to 20% when \f(CW\*(C`length\*(C'\fR is applied to
+a non-magical, non-tied string, and either \f(CW\*(C`use bytes\*(C'\fR is in scope or the
+string doesn't use UTF\-8 internally.
+.IP \(bu 4
+On most perl builds with 64\-bit integers, memory usage for non-magical,
+non-tied scalars containing only a floating point value has been reduced
+by between 8 and 32 bytes, depending on OS.
+.IP \(bu 4
+In \f(CW\*(C`@array = split\*(C'\fR, the assignment can be optimized away, so that \f(CW\*(C`split\*(C'\fR
+writes directly to the array.  This optimisation was happening only for
+package arrays other than \f(CW@_\fR, and only sometimes.  Now this
+optimisation happens almost all the time.
+.IP \(bu 4
+\&\f(CW\*(C`join\*(C'\fR is now subject to constant folding.  So for example
+\&\f(CW\*(C`join\ "\-",\ "a",\ "b"\*(C'\fR is converted at compile-time to \f(CW"a\-b"\fR.
+Moreover, \f(CW\*(C`join\*(C'\fR with a scalar or constant for the separator and a
+single-item list to join is simplified to a stringification, and the
+separator doesn't even get evaluated.
+.IP \(bu 4
+\&\f(CWqq(@array)\fR is implemented using two ops: a stringify op and a join op.
+If the \f(CW\*(C`qq\*(C'\fR contains nothing but a single array, the stringification is
+optimized away.
+.IP \(bu 4
+\&\f(CW\*(C`our\ $var\*(C'\fR and \f(CW\*(C`our($s,@a,%h)\*(C'\fR in void context are no longer evaluated at
+run time.  Even a whole sequence of \f(CW\*(C`our\ $foo;\*(C'\fR statements will simply be
+skipped over.  The same applies to \f(CW\*(C`state\*(C'\fR variables.
+.IP \(bu 4
+Many internal functions have been refactored to improve performance and reduce
+their memory footprints.
+[GH #13659] <https://github.com/Perl/perl5/issues/13659>
+[GH #13856] <https://github.com/Perl/perl5/issues/13856>
+[GH #13874] <https://github.com/Perl/perl5/issues/13874>
+.IP \(bu 4
+\&\f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR filetests will return sooner when an empty file is detected.
+[GH #13686] <https://github.com/Perl/perl5/issues/13686>
+.IP \(bu 4
+Hash lookups where the key is a constant are faster.
+.IP \(bu 4
+Subroutines with an empty prototype and a body containing just \f(CW\*(C`undef\*(C'\fR are now
+eligible for inlining.
+[GH #14077] <https://github.com/Perl/perl5/issues/14077>
+.IP \(bu 4
+Subroutines in packages no longer need to be stored in typeglobs:
+declaring a subroutine will now put a simple sub reference directly in the
+stash if possible, saving memory.  The typeglob still notionally exists,
+so accessing it will cause the stash entry to be upgraded to a typeglob
+(\fIi.e.\fR this is just an internal implementation detail).
+This optimization does not currently apply to XSUBs or exported
+subroutines, and method calls will undo it, since they cache things in
+typeglobs.
+[GH #13392] <https://github.com/Perl/perl5/issues/13392>
+.IP \(bu 4
+The functions \f(CWutf8::native_to_unicode()\fR and \f(CWutf8::unicode_to_native()\fR
+(see utf8) are now optimized out on ASCII platforms.  There is now not even
+a minimal performance hit in writing code portable between ASCII and EBCDIC
+platforms.
+.IP \(bu 4
+Win32 Perl uses 8 KB less of per-process memory than before for every perl
+process, because some data is now memory mapped from disk and shared
+between processes from the same perl binary.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+Many of the libraries distributed with perl have been upgraded since v5.20.0.
+For a complete list of changes, run:
+.PP
+.Vb 1
+\&  corelist \-\-diff 5.20.0 5.22.0
+.Ve
+.PP
+You can substitute your favorite version in place of 5.20.0, too.
+.PP
+Some notable changes include:
+.IP \(bu 4
+Archive::Tar has been upgraded to version 2.04.
+.Sp
+Tests can now be run in parallel.
+.IP \(bu 4
+attributes has been upgraded to version 0.27.
+.Sp
+The usage of \f(CW\*(C`memEQs\*(C'\fR in the XS has been corrected.
+[GH #14072] <https://github.com/Perl/perl5/issues/14072>
+.Sp
+Avoid reading beyond the end of a buffer. [perl #122629]
+.IP \(bu 4
+B has been upgraded to version 1.58.
+.Sp
+It provides a new \f(CW\*(C`B::safename\*(C'\fR function, based on the existing
+\&\f(CW\*(C`B::GV\->SAFENAME\*(C'\fR, that converts \f(CW\*(C`\ecOPEN\*(C'\fR to \f(CW\*(C`^OPEN\*(C'\fR.
+.Sp
+Nulled COPs are now of class \f(CW\*(C`B::COP\*(C'\fR, rather than \f(CW\*(C`B::OP\*(C'\fR.
+.Sp
+\&\f(CW\*(C`B::REGEXP\*(C'\fR objects now provide a \f(CW\*(C`qr_anoncv\*(C'\fR method for accessing the
+implicit CV associated with \f(CW\*(C`qr//\*(C'\fR things containing code blocks, and a
+\&\f(CW\*(C`compflags\*(C'\fR method that returns the pertinent flags originating from the
+\&\f(CW\*(C`qr//blahblah\*(C'\fR op.
+.Sp
+\&\f(CW\*(C`B::PMOP\*(C'\fR now provides a \f(CW\*(C`pmregexp\*(C'\fR method returning a \f(CW\*(C`B::REGEXP\*(C'\fR object.
+Two new classes, \f(CW\*(C`B::PADNAME\*(C'\fR and \f(CW\*(C`B::PADNAMELIST\*(C'\fR, have been introduced.
+.Sp
+A bug where, after an ithread creation or pseudofork, special/immortal SVs in
+the child ithread/pseudoprocess did not have the correct class of
+\&\f(CW\*(C`B::SPECIAL\*(C'\fR, has been fixed.
+The \f(CW\*(C`id\*(C'\fR and \f(CW\*(C`outid\*(C'\fR PADLIST methods have been added.
+.IP \(bu 4
+B::Concise has been upgraded to version 0.996.
+.Sp
+Null ops that are part of the execution chain are now given sequence
+numbers.
+.Sp
+Private flags for nulled ops are now dumped with mnemonics as they would be
+for the non-nulled counterparts.
+.IP \(bu 4
+B::Deparse has been upgraded to version 1.35.
+.Sp
+It now deparses \f(CW\*(C`+sub : attr { ... }\*(C'\fR correctly at the start of a
+statement.  Without the initial \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`sub\*(C'\fR would be a statement label.
+.Sp
+\&\f(CW\*(C`BEGIN\*(C'\fR blocks are now emitted in the right place most of the time, but
+the change unfortunately introduced a regression, in that \f(CW\*(C`BEGIN\*(C'\fR blocks
+occurring just before the end of the enclosing block may appear below it
+instead.
+.Sp
+\&\f(CW\*(C`B::Deparse\*(C'\fR no longer puts erroneous \f(CW\*(C`local\*(C'\fR here and there, such as for
+\&\f(CW\*(C`LIST = tr/a//d\*(C'\fR.  [perl #119815]
+.Sp
+Adjacent \f(CW\*(C`use\*(C'\fR statements are no longer accidentally nested if one
+contains a \f(CW\*(C`do\*(C'\fR block.  [perl #115066]
+.Sp
+Parenthesised arrays in lists passed to \f(CW\*(C`\e\*(C'\fR are now correctly deparsed
+with parentheses (\fIe.g.\fR, \f(CW\*(C`\e(@a, (@b), @c)\*(C'\fR now retains the parentheses
+around \f(CW@b\fR), thus preserving the flattening behavior of referenced
+parenthesised arrays.  Formerly, it only worked for one array: \f(CW\*(C`\e(@a)\*(C'\fR.
+.Sp
+\&\f(CW\*(C`local our\*(C'\fR is now deparsed correctly, with the \f(CW\*(C`our\*(C'\fR included.
+.Sp
+\&\f(CW\*(C`for($foo; !$bar; $baz) {...}\*(C'\fR was deparsed without the \f(CW\*(C`!\*(C'\fR (or \f(CW\*(C`not\*(C'\fR).
+This has been fixed.
+.Sp
+Core keywords that conflict with lexical subroutines are now deparsed with
+the \f(CW\*(C`CORE::\*(C'\fR prefix.
+.Sp
+\&\f(CW\*(C`foreach state $x (...) {...}\*(C'\fR now deparses correctly with \f(CW\*(C`state\*(C'\fR and
+not \f(CW\*(C`my\*(C'\fR.
+.Sp
+\&\f(CW\*(C`our @array = split(...)\*(C'\fR now deparses correctly with \f(CW\*(C`our\*(C'\fR in those
+cases where the assignment is optimized away.
+.Sp
+It now deparses \f(CWour(\fR\f(CILIST\fR\f(CW)\fR and typed lexical (\f(CW\*(C`my Dog $spot\*(C'\fR) correctly.
+.Sp
+Deparse \f(CW$#_\fR as that instead of as \f(CW$#{_}\fR.
+[GH #14545] <https://github.com/Perl/perl5/issues/14545>
+.Sp
+BEGIN blocks at the end of the enclosing scope are now deparsed in the
+right place.  [perl #77452]
+.Sp
+BEGIN blocks were sometimes deparsed as _\|_ANON_\|_, but are now always called
+BEGIN.
+.Sp
+Lexical subroutines are now fully deparsed.  [perl #116553]
+.Sp
+\&\f(CW\*(C`Anything =~ y///r\*(C'\fR with \f(CW\*(C`/r\*(C'\fR no longer omits the left-hand operand.
+.Sp
+The op trees that make up regexp code blocks are now deparsed for real.
+Formerly, the original string that made up the regular expression was used.
+That caused problems with \f(CW\*(C`qr/(?{<<heredoc})/\*(C'\fR and multiline code blocks,
+which were deparsed incorrectly.  [perl #123217] [perl #115256]
+.Sp
+\&\f(CW$;\fR at the end of a statement no longer loses its semicolon.
+[perl #123357]
+.Sp
+Some cases of subroutine declarations stored in the stash in shorthand form
+were being omitted.
+.Sp
+Non-ASCII characters are now consistently escaped in strings, instead of
+some of the time.  (There are still outstanding problems with regular
+expressions and identifiers that have not been fixed.)
+.Sp
+When prototype sub calls are deparsed with \f(CW\*(C`&\*(C'\fR (\fIe.g.\fR, under the \fB\-P\fR
+option), \f(CW\*(C`scalar\*(C'\fR is now added where appropriate, to force the scalar
+context implied by the prototype.
+.Sp
+\&\f(CW\*(C`require(foo())\*(C'\fR, \f(CW\*(C`do(foo())\*(C'\fR, \f(CW\*(C`goto(foo())\*(C'\fR and similar constructs with
+loop controls are now deparsed correctly.  The outer parentheses are not
+optional.
+.Sp
+Whitespace is no longer escaped in regular expressions, because it was
+getting erroneously escaped within \f(CW\*(C`(?x:...)\*(C'\fR sections.
+.Sp
+\&\f(CW\*(C`sub foo { foo() }\*(C'\fR is now deparsed with those mandatory parentheses.
+.Sp
+\&\f(CW\*(C`/@array/\*(C'\fR is now deparsed as a regular expression, and not just
+\&\f(CW@array\fR.
+.Sp
+\&\f(CW\*(C`/@{\-}/\*(C'\fR, \f(CW\*(C`/@{+}/\*(C'\fR and \f(CW$#{1}\fR are now deparsed with the braces, which
+are mandatory in these cases.
+.Sp
+In deparsing feature bundles, \f(CW\*(C`B::Deparse\*(C'\fR was emitting \f(CW\*(C`no feature;\*(C'\fR first
+instead of \f(CW\*(C`no feature \*(Aq:all\*(Aq;\*(C'\fR.  This has been fixed.
+.Sp
+\&\f(CW\*(C`chdir FH\*(C'\fR is now deparsed without quotation marks.
+.Sp
+\&\f(CW\*(C`\emy @a\*(C'\fR is now deparsed without parentheses.  (Parenthese would flatten
+the array.)
+.Sp
+\&\f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR followed by a block are now deparsed correctly.
+Formerly there was an erroneous \f(CW\*(C`do\*(C'\fR before the block.
+.Sp
+\&\f(CW\*(C`use constant QR => qr/.../flags\*(C'\fR followed by \f(CW\*(C`"" =~ QR\*(C'\fR is no longer
+without the flags.
+.Sp
+Deparsing \f(CW\*(C`BEGIN { undef &foo }\*(C'\fR with the \fB\-w\fR switch enabled started to
+emit 'uninitialized' warnings in Perl 5.14.  This has been fixed.
+.Sp
+Deparsing calls to subs with a \f(CW\*(C`(;+)\*(C'\fR prototype resulted in an infinite
+loop.  The \f(CW\*(C`(;$\*(C'\fR) \f(CW\*(C`(_)\*(C'\fR and \f(CW\*(C`(;_)\*(C'\fR prototypes were given the wrong
+precedence, causing \f(CWfoo($a<$b)\fR to be deparsed without the parentheses.
+.Sp
+Deparse now provides a defined state sub in inner subs.
+.IP \(bu 4
+B::Op_private has been added.
+.Sp
+B::Op_private provides detailed information about the flags used in the
+\&\f(CW\*(C`op_private\*(C'\fR field of perl opcodes.
+.IP \(bu 4
+bigint, bignum, bigrat have been upgraded to version 0.39.
+.Sp
+Document in CAVEATS that using strings as numbers won't always invoke
+the big number overloading, and how to invoke it.  [rt.perl.org #123064]
+.IP \(bu 4
+Carp has been upgraded to version 1.36.
+.Sp
+\&\f(CW\*(C`Carp::Heavy\*(C'\fR now ignores version mismatches with Carp if Carp is newer
+than 1.12, since \f(CW\*(C`Carp::Heavy\*(C'\fR's guts were merged into Carp at that
+point.
+[GH #13708] <https://github.com/Perl/perl5/issues/13708>
+.Sp
+Carp now handles non-ASCII platforms better.
+.Sp
+Off-by-one error fix for Perl < 5.14.
+.IP \(bu 4
+constant has been upgraded to version 1.33.
+.Sp
+It now accepts fully-qualified constant names, allowing constants to be defined
+in packages other than the caller.
+.IP \(bu 4
+CPAN has been upgraded to version 2.11.
+.Sp
+Add support for \f(CWCwd::getdcwd()\fR and introduce workaround for a misbehavior
+seen on Strawberry Perl 5.20.1.
+.Sp
+Fix \f(CWchdir()\fR after building dependencies bug.
+.Sp
+Introduce experimental support for plugins/hooks.
+.Sp
+Integrate the \f(CW\*(C`App::Cpan\*(C'\fR sources.
+.Sp
+Do not check recursion on optional dependencies.
+.Sp
+Sanity check \fIMETA.yml\fR to contain a hash.
+[cpan #95271] <https://rt.cpan.org/Ticket/Display.html?id=95271>
+.IP \(bu 4
+CPAN::Meta::Requirements has been upgraded to version 2.132.
+.Sp
+Works around limitations in \f(CW\*(C`version::vpp\*(C'\fR detecting v\-string magic and adds
+support for forthcoming ExtUtils::MakeMaker bootstrap \fIversion.pm\fR for
+Perls older than 5.10.0.
+.IP \(bu 4
+Data::Dumper has been upgraded to version 2.158.
+.Sp
+Fixes CVE\-2014\-4330 by adding a configuration variable/option to limit
+recursion when dumping deep data structures.
+.Sp
+Changes to resolve Coverity issues.
+XS dumps incorrectly stored the name of code references stored in a
+GLOB.
+[GH #13911] <https://github.com/Perl/perl5/issues/13911>
+.IP \(bu 4
+DynaLoader has been upgraded to version 1.32.
+.Sp
+Remove \f(CW\*(C`dl_nonlazy\*(C'\fR global if unused in Dynaloader. [perl #122926]
+.IP \(bu 4
+Encode has been upgraded to version 2.72.
+.Sp
+\&\f(CW\*(C`piconv\*(C'\fR now has better error handling when the encoding name is nonexistent,
+and a build breakage when upgrading Encode in perl\-5.8.2 and earlier has
+been fixed.
+.Sp
+Building in C++ mode on Windows now works.
+.IP \(bu 4
+Errno has been upgraded to version 1.23.
+.Sp
+Add \f(CW\*(C`\-P\*(C'\fR to the preprocessor command-line on GCC 5.  GCC added extra
+line directives, breaking parsing of error code definitions.  [rt.perl.org
+#123784]
+.IP \(bu 4
+experimental has been upgraded to version 0.013.
+.Sp
+Hardcodes features for Perls older than 5.15.7.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded to version 0.280221.
+.Sp
+Fixes a regression on Android.
+[GH #14064] <https://github.com/Perl/perl5/issues/14064>
+.IP \(bu 4
+ExtUtils::Manifest has been upgraded to version 1.70.
+.Sp
+Fixes a bug with \f(CWmaniread()\fR's handling of quoted filenames and improves
+\&\f(CWmanifind()\fR to follow symlinks.
+[GH #14003] <https://github.com/Perl/perl5/issues/14003>
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded to version 3.28.
+.Sp
+Only declare \f(CW\*(C`file\*(C'\fR unused if we actually define it.
+Improve generated \f(CW\*(C`RETVAL\*(C'\fR code generation to avoid repeated
+references to \f(CWST(0)\fR.  [perl #123278]
+Broaden and document the \f(CW\*(C`/OBJ$/\*(C'\fR to \f(CW\*(C`/REF$/\*(C'\fR typemap optimization
+for the \f(CW\*(C`DESTROY\*(C'\fR method.  [perl #123418]
+.IP \(bu 4
+Fcntl has been upgraded to version 1.13.
+.Sp
+Add support for the Linux pipe buffer size \f(CWfcntl()\fR commands.
+.IP \(bu 4
+File::Find has been upgraded to version 1.29.
+.Sp
+\&\f(CWfind()\fR and \f(CWfinddepth()\fR will now warn if passed inappropriate or
+misspelled options.
+.IP \(bu 4
+File::Glob has been upgraded to version 1.24.
+.Sp
+Avoid \f(CWSvIV()\fR expanding to call \f(CWget_sv()\fR three times in a few
+places. [perl #123606]
+.IP \(bu 4
+HTTP::Tiny has been upgraded to version 0.054.
+.Sp
+\&\f(CW\*(C`keep_alive\*(C'\fR is now fork-safe and thread-safe.
+.IP \(bu 4
+IO has been upgraded to version 1.35.
+.Sp
+The XS implementation has been fixed for the sake of older Perls.
+.IP \(bu 4
+IO::Socket has been upgraded to version 1.38.
+.Sp
+Document the limitations of the \f(CWconnected()\fR method.  [perl #123096]
+.IP \(bu 4
+IO::Socket::IP has been upgraded to version 0.37.
+.Sp
+A better fix for subclassing \f(CWconnect()\fR.
+[cpan #95983] <https://rt.cpan.org/Ticket/Display.html?id=95983>
+[cpan #97050] <https://rt.cpan.org/Ticket/Display.html?id=97050>
+.Sp
+Implements Timeout for \f(CWconnect()\fR.
+[cpan #92075] <https://rt.cpan.org/Ticket/Display.html?id=92075>
+.IP \(bu 4
+The libnet collection of modules has been upgraded to version 3.05.
+.Sp
+Support for IPv6 and SSL to \f(CW\*(C`Net::FTP\*(C'\fR, \f(CW\*(C`Net::NNTP\*(C'\fR, \f(CW\*(C`Net::POP3\*(C'\fR and \f(CW\*(C`Net::SMTP\*(C'\fR.
+Improvements in \f(CW\*(C`Net::SMTP\*(C'\fR authentication.
+.IP \(bu 4
+Locale::Codes has been upgraded to version 3.34.
+.Sp
+Fixed a bug in the scripts used to extract data from spreadsheets that
+prevented the SHP currency code from being found.
+[cpan #94229] <https://rt.cpan.org/Ticket/Display.html?id=94229>
+.Sp
+New codes have been added.
+.IP \(bu 4
+Math::BigInt has been upgraded to version 1.9997.
+.Sp
+Synchronize POD changes from the CPAN release.
+\&\f(CW\*(C`Math::BigFloat\->blog(x)\*(C'\fR would sometimes return \f(CWblog(2*x)\fR when
+the accuracy was greater than 70 digits.
+The result of \f(CW\*(C`Math::BigFloat\->bdiv()\*(C'\fR in list context now
+satisfies \f(CW\*(C`x = quotient * divisor + remainder\*(C'\fR.
+.Sp
+Correct handling of subclasses.
+[cpan #96254] <https://rt.cpan.org/Ticket/Display.html?id=96254>
+[cpan #96329] <https://rt.cpan.org/Ticket/Display.html?id=96329>
+.IP \(bu 4
+Module::Metadata has been upgraded to version 1.000026.
+.Sp
+Support installations on older perls with an ExtUtils::MakeMaker earlier
+than 6.63_03
+.IP \(bu 4
+overload has been upgraded to version 1.26.
+.Sp
+A redundant \f(CW\*(C`ref $sub\*(C'\fR check has been removed.
+.IP \(bu 4
+The PathTools module collection has been upgraded to version 3.56.
+.Sp
+A warning from the \fBgcc\fR compiler is now avoided when building the XS.
+.Sp
+Don't turn leading \f(CW\*(C`//\*(C'\fR into \f(CW\*(C`/\*(C'\fR on Cygwin. [perl #122635]
+.IP \(bu 4
+perl5db.pl has been upgraded to version 1.49.
+.Sp
+The debugger would cause an assertion failure.
+[GH #14605] <https://github.com/Perl/perl5/issues/14605>
+.Sp
+\&\f(CWfork()\fR in the debugger under \f(CW\*(C`tmux\*(C'\fR will now create a new window for
+the forked process. [GH #13602] <https://github.com/Perl/perl5/issues/13602>
+.Sp
+The debugger now saves the current working directory on startup and
+restores it when you restart your program with \f(CW\*(C`R\*(C'\fR or \f(CW\*(C`rerun\*(C'\fR.
+[GH #13691] <https://github.com/Perl/perl5/issues/13691>
+.IP \(bu 4
+PerlIO::scalar has been upgraded to version 0.22.
+.Sp
+Reading from a position well past the end of the scalar now correctly
+returns end of file.  [perl #123443]
+.Sp
+Seeking to a negative position still fails, but no longer leaves the
+file position set to a negation location.
+.Sp
+\&\f(CWeof()\fR on a \f(CW\*(C`PerlIO::scalar\*(C'\fR handle now properly returns true when
+the file position is past the 2GB mark on 32\-bit systems.
+.Sp
+Attempting to write at file positions impossible for the platform now
+fail early rather than wrapping at 4GB.
+.IP \(bu 4
+Pod::Perldoc has been upgraded to version 3.25.
+.Sp
+Filehandles opened for reading or writing now have \f(CW:encoding(UTF\-8)\fR set.
+[cpan #98019] <https://rt.cpan.org/Ticket/Display.html?id=98019>
+.IP \(bu 4
+POSIX has been upgraded to version 1.53.
+.Sp
+The C99 math functions and constants (for example \f(CW\*(C`acosh\*(C'\fR, \f(CW\*(C`isinf\*(C'\fR, \f(CW\*(C`isnan\*(C'\fR, \f(CW\*(C`round\*(C'\fR,
+\&\f(CW\*(C`trunc\*(C'\fR; \f(CW\*(C`M_E\*(C'\fR, \f(CW\*(C`M_SQRT2\*(C'\fR, \f(CW\*(C`M_PI\*(C'\fR) have been added.
+.Sp
+\&\f(CWPOSIX::tmpnam()\fR now produces a deprecation warning.  [perl #122005]
+.IP \(bu 4
+Safe has been upgraded to version 2.39.
+.Sp
+\&\f(CW\*(C`reval\*(C'\fR was not propagating void context properly.
+.IP \(bu 4
+Scalar-List-Utils has been upgraded to version 1.41.
+.Sp
+A new module, Sub::Util, has been added, containing functions related to
+CODE refs, including \f(CW\*(C`subname\*(C'\fR (inspired by \f(CW\*(C`Sub::Identity\*(C'\fR) and \f(CW\*(C`set_subname\*(C'\fR
+(copied and renamed from \f(CW\*(C`Sub::Name\*(C'\fR).
+The use of \f(CW\*(C`GetMagic\*(C'\fR in \f(CWList::Util::reduce()\fR has also been fixed.
+[cpan #63211] <https://rt.cpan.org/Ticket/Display.html?id=63211>
+.IP \(bu 4
+SDBM_File has been upgraded to version 1.13.
+.Sp
+Simplified the build process.  [perl #123413]
+.IP \(bu 4
+Time::Piece has been upgraded to version 1.29.
+.Sp
+When pretty printing negative \f(CW\*(C`Time::Seconds\*(C'\fR, the "minus" is no longer lost.
+.IP \(bu 4
+Unicode::Collate has been upgraded to version 1.12.
+.Sp
+Version 0.67's improved discontiguous contractions is invalidated by default
+and is supported as a parameter \f(CW\*(C`long_contraction\*(C'\fR.
+.IP \(bu 4
+Unicode::Normalize has been upgraded to version 1.18.
+.Sp
+The XSUB implementation has been removed in favor of pure Perl.
+.IP \(bu 4
+Unicode::UCD has been upgraded to version 0.61.
+.Sp
+A new function \fBproperty_values()\fR
+has been added to return a given property's possible values.
+.Sp
+A new function \fBcharprop()\fR
+has been added to return the value of a given property for a given code
+point.
+.Sp
+A new function \fBcharprops_all()\fR
+has been added to return the values of all Unicode properties for a
+given code point.
+.Sp
+A bug has been fixed so that \fBpropaliases()\fR
+returns the correct short and long names for the Perl extensions where
+it was incorrect.
+.Sp
+A bug has been fixed so that
+\&\fBprop_value_aliases()\fR
+returns \f(CW\*(C`undef\*(C'\fR instead of a wrong result for properties that are Perl
+extensions.
+.Sp
+This module now works on EBCDIC platforms.
+.IP \(bu 4
+utf8 has been upgraded to version 1.17
+.Sp
+A mismatch between the documentation and the code in \f(CWutf8::downgrade()\fR
+was fixed in favor of the documentation. The optional second argument
+is now correctly treated as a perl boolean (true/false semantics) and
+not as an integer.
+.IP \(bu 4
+version has been upgraded to version 0.9909.
+.Sp
+Numerous changes.  See the \fIChanges\fR file in the CPAN distribution for
+details.
+.IP \(bu 4
+Win32 has been upgraded to version 0.51.
+.Sp
+\&\f(CWGetOSName()\fR now supports Windows 8.1, and building in C++ mode now works.
+.IP \(bu 4
+Win32API::File has been upgraded to version 0.1202
+.Sp
+Building in C++ mode now works.
+.IP \(bu 4
+XSLoader has been upgraded to version 0.20.
+.Sp
+Allow XSLoader to load modules from a different namespace.
+[perl #122455]
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+The following modules (and associated modules) have been removed from the core
+perl distribution:
+.IP \(bu 4
+CGI
+.IP \(bu 4
+Module::Build
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlunicook\fR
+.IX Subsection "perlunicook"
+.PP
+This document, by Tom Christiansen, provides examples of handling Unicode in
+Perl.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlaix\fR
+.IX Subsection "perlaix"
+.IP \(bu 4
+A note on long doubles has been added.
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+Note that \f(CW\*(C`SvSetSV\*(C'\fR doesn't do set magic.
+.IP \(bu 4
+\&\f(CW\*(C`sv_usepvn_flags\*(C'\fR \- fix documentation to mention the use of \f(CW\*(C`Newx\*(C'\fR instead of
+\&\f(CW\*(C`malloc\*(C'\fR.
+.Sp
+[GH #13835] <https://github.com/Perl/perl5/issues/13835>
+.IP \(bu 4
+Clarify where \f(CW\*(C`NUL\*(C'\fR may be embedded or is required to terminate a string.
+.IP \(bu 4
+Some documentation that was previously missing due to formatting errors is
+now included.
+.IP \(bu 4
+Entries are now organized into groups rather than by the file where they
+are found.
+.IP \(bu 4
+Alphabetical sorting of entries is now done consistently (automatically
+by the POD generator) to make entries easier to find when scanning.
+.PP
+\fIperldata\fR
+.IX Subsection "perldata"
+.IP \(bu 4
+The syntax of single-character variable names has been brought
+up-to-date and more fully explained.
+.IP \(bu 4
+Hexadecimal floating point numbers are described, as are infinity and
+NaN.
+.PP
+\fIperlebcdic\fR
+.IX Subsection "perlebcdic"
+.IP \(bu 4
+This document has been significantly updated in the light of recent
+improvements to EBCDIC support.
+.PP
+\fIperlfilter\fR
+.IX Subsection "perlfilter"
+.IP \(bu 4
+Added a LIMITATIONS section.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+Mention that \f(CWstudy()\fR is currently a no-op.
+.IP \(bu 4
+Calling \f(CW\*(C`delete\*(C'\fR or \f(CW\*(C`exists\*(C'\fR on array values is now described as "strongly
+discouraged" rather than "deprecated".
+.IP \(bu 4
+Improve documentation of \f(CW\*(C`our\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`\-l\*(C'\fR now notes that it will return false if symlinks aren't supported by the
+file system.
+[GH #13695] <https://github.com/Perl/perl5/issues/13695>
+.IP \(bu 4
+Note that \f(CW\*(C`exec LIST\*(C'\fR and \f(CW\*(C`system LIST\*(C'\fR may fall back to the shell on
+Win32. Only the indirect-object syntax \f(CW\*(C`exec PROGRAM LIST\*(C'\fR and
+\&\f(CW\*(C`system PROGRAM LIST\*(C'\fR will reliably avoid using the shell.
+.Sp
+This has also been noted in perlport.
+.Sp
+[GH #13907] <https://github.com/Perl/perl5/issues/13907>
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+The OOK example has been updated to account for COW changes and a change in the
+storage of the offset.
+.IP \(bu 4
+Details on C level symbols and libperl.t added.
+.IP \(bu 4
+Information on Unicode handling has been added
+.IP \(bu 4
+Information on EBCDIC handling has been added
+.PP
+\fIperlhack\fR
+.IX Subsection "perlhack"
+.IP \(bu 4
+A note has been added about running on platforms with non-ASCII
+character sets
+.IP \(bu 4
+A note has been added about performance testing
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+Documentation has been added illustrating the perils of assuming that
+there is no change to the contents of static memory pointed to by the
+return values of Perl's wrappers for C library functions.
+.IP \(bu 4
+Replacements for \f(CW\*(C`tmpfile\*(C'\fR, \f(CW\*(C`atoi\*(C'\fR, \f(CW\*(C`strtol\*(C'\fR, and \f(CW\*(C`strtoul\*(C'\fR are now
+recommended.
+.IP \(bu 4
+Updated documentation for the \f(CW\*(C`test.valgrind\*(C'\fR \f(CW\*(C`make\*(C'\fR target.
+[GH #13658] <https://github.com/Perl/perl5/issues/13658>
+.IP \(bu 4
+Information is given about writing test files portably to non-ASCII
+platforms.
+.IP \(bu 4
+A note has been added about how to get a C language stack backtrace.
+.PP
+\fIperlhpux\fR
+.IX Subsection "perlhpux"
+.IP \(bu 4
+Note that the message "Redeclaration of "sendpath" with a different
+storage class specifier" is harmless.
+.PP
+\fIperllocale\fR
+.IX Subsection "perllocale"
+.IP \(bu 4
+Updated for the enhancements in v5.22, along with some clarifications.
+.PP
+\fIperlmodstyle\fR
+.IX Subsection "perlmodstyle"
+.IP \(bu 4
+Instead of pointing to the module list, we are now pointing to
+PrePAN <http://prepan.org/>.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Updated for the enhancements in v5.22, along with some clarifications.
+.PP
+\fIperlpodspec\fR
+.IX Subsection "perlpodspec"
+.IP \(bu 4
+The specification of the pod language is changing so that the default
+encoding of pods that aren't in UTF\-8 (unless otherwise indicated) is
+CP1252 instead of ISO 8859\-1 (Latin1).
+.PP
+\fIperlpolicy\fR
+.IX Subsection "perlpolicy"
+.IP \(bu 4
+We now have a code of conduct for the \fIp5p\fR mailing list, as documented
+in "STANDARDS OF CONDUCT" in perlpolicy.
+.IP \(bu 4
+The conditions for marking an experimental feature as non-experimental are now
+set out.
+.IP \(bu 4
+Clarification has been made as to what sorts of changes are permissible in
+maintenance releases.
+.PP
+\fIperlport\fR
+.IX Subsection "perlport"
+.IP \(bu 4
+Out-of-date VMS-specific information has been fixed and/or simplified.
+.IP \(bu 4
+Notes about EBCDIC have been added.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+The description of the \f(CW\*(C`/x\*(C'\fR modifier has been clarified to note that
+comments cannot be continued onto the next line by escaping them; and
+there is now a list of all the characters that are considered whitespace
+by this modifier.
+.IP \(bu 4
+The new \f(CW\*(C`/n\*(C'\fR modifier is described.
+.IP \(bu 4
+A note has been added on how to make bracketed character class ranges
+portable to non-ASCII machines.
+.PP
+\fIperlrebackslash\fR
+.IX Subsection "perlrebackslash"
+.IP \(bu 4
+Added documentation of \f(CW\*(C`\eb{sb}\*(C'\fR, \f(CW\*(C`\eb{wb}\*(C'\fR, \f(CW\*(C`\eb{gcb}\*(C'\fR, and \f(CW\*(C`\eb{g}\*(C'\fR.
+.PP
+\fIperlrecharclass\fR
+.IX Subsection "perlrecharclass"
+.IP \(bu 4
+Clarifications have been added to "Character Ranges" in perlrecharclass
+to the effect \f(CW\*(C`[A\-Z]\*(C'\fR, \f(CW\*(C`[a\-z]\*(C'\fR, \f(CW\*(C`[0\-9]\*(C'\fR and
+any subranges thereof in regular expression bracketed character classes
+are guaranteed to match exactly what a naive English speaker would
+expect them to match, even on platforms (such as EBCDIC) where perl
+has to do extra work to accomplish this.
+.IP \(bu 4
+The documentation of Bracketed Character Classes has been expanded to cover the
+improvements in \f(CW\*(C`qr/[\eN{named sequence}]/\*(C'\fR (see under "Selected Bug Fixes").
+.PP
+\fIperlref\fR
+.IX Subsection "perlref"
+.IP \(bu 4
+A new section has been added
+Assigning to References
+.PP
+\fIperlsec\fR
+.IX Subsection "perlsec"
+.IP \(bu 4
+Comments added on algorithmic complexity and tied hashes.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+An ambiguity in the documentation of the \f(CW\*(C`...\*(C'\fR statement has been corrected.
+[GH #14054] <https://github.com/Perl/perl5/issues/14054>
+.IP \(bu 4
+The empty conditional in \f(CW\*(C`for\*(C'\fR and \f(CW\*(C`while\*(C'\fR is now documented
+in perlsyn.
+.PP
+\fIperlunicode\fR
+.IX Subsection "perlunicode"
+.IP \(bu 4
+This has had extensive revisions to bring it up-to-date with current
+Unicode support and to make it more readable.  Notable is that Unicode
+7.0 changed what it should do with non-characters.  Perl retains the old
+way of handling for reasons of backward compatibility.  See
+"Noncharacter code points" in perlunicode.
+.PP
+\fIperluniintro\fR
+.IX Subsection "perluniintro"
+.IP \(bu 4
+Advice for how to make sure your strings and regular expression patterns are
+interpreted as Unicode has been updated.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+\&\f(CW$]\fR is no longer listed as being deprecated.  Instead, discussion has
+been added on the advantages and disadvantages of using it versus
+\&\f(CW$^V\fR.  \f(CW$OLD_PERL_VERSION\fR was re-added to the documentation as the long
+form of \f(CW$]\fR.
+.IP \(bu 4
+\&\f(CW\*(C`${^ENCODING}\*(C'\fR is now marked as deprecated.
+.IP \(bu 4
+The entry for \f(CW\*(C`%^H\*(C'\fR has been clarified to indicate it can only handle
+simple values.
+.PP
+\fIperlvms\fR
+.IX Subsection "perlvms"
+.IP \(bu 4
+Out-of-date and/or incorrect material has been removed.
+.IP \(bu 4
+Updated documentation on environment and shell interaction in VMS.
+.PP
+\fIperlxs\fR
+.IX Subsection "perlxs"
+.IP \(bu 4
+Added a discussion of locale issues in XS code.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Bad symbol for scalar
+.Sp
+(P) An internal request asked to add a scalar entry to something that
+wasn't a symbol table entry.
+.IP \(bu 4
+Can't use a hash as a reference
+.Sp
+(F) You tried to use a hash as a reference, as in
+\&\f(CW\*(C`%foo\->{"bar"}\*(C'\fR or \f(CW\*(C`%$ref\->{"hello"}\*(C'\fR.  Versions of perl <= 5.6.1
+used to allow this syntax, but shouldn't have.
+.IP \(bu 4
+Can't use an array as a reference
+.Sp
+(F) You tried to use an array as a reference, as in
+\&\f(CW\*(C`@foo\->[23]\*(C'\fR or \f(CW\*(C`@$ref\->[99]\*(C'\fR.  Versions of perl <= 5.6.1 used to
+allow this syntax, but shouldn't have.
+.IP \(bu 4
+Can't use 'defined(@array)' (Maybe you should just omit the \fBdefined()\fR?)
+.Sp
+(F) \f(CWdefined()\fR is not useful on arrays because it
+checks for an undefined \fIscalar\fR value.  If you want to see if the
+array is empty, just use \f(CW\*(C`if\ (@array)\ {\ #\ not\ empty\ }\*(C'\fR for example.
+.IP \(bu 4
+Can't use 'defined(%hash)' (Maybe you should just omit the \fBdefined()\fR?)
+.Sp
+(F) \f(CWdefined()\fR is not usually right on hashes.
+.Sp
+Although \f(CW\*(C`defined\ %hash\*(C'\fR is false on a plain not-yet-used hash, it
+becomes true in several non-obvious circumstances, including iterators,
+weak references, stash names, even remaining true after \f(CW\*(C`undef\ %hash\*(C'\fR.
+These things make \f(CW\*(C`defined\ %hash\*(C'\fR fairly useless in practice, so it now
+generates a fatal error.
+.Sp
+If a check for non-empty is what you wanted then just put it in boolean
+context (see "Scalar values" in perldata):
+.Sp
+.Vb 3
+\&    if (%hash) {
+\&       # not empty
+\&    }
+.Ve
+.Sp
+If you had \f(CW\*(C`defined\ %Foo::Bar::QUUX\*(C'\fR to check whether such a package
+variable exists then that's never really been reliable, and isn't
+a good way to enquire about the features of a package, or whether
+it's loaded, etc.
+.IP \(bu 4
+Cannot chr \f(CW%f\fR
+.Sp
+(F) You passed an invalid number (like an infinity or not-a-number) to
+\&\f(CW\*(C`chr\*(C'\fR.
+.IP \(bu 4
+Cannot compress \f(CW%f\fR in pack
+.Sp
+(F) You tried converting an infinity or not-a-number to an unsigned
+character, which makes no sense.
+.IP \(bu 4
+Cannot pack \f(CW%f\fR with '%c'
+.Sp
+(F) You tried converting an infinity or not-a-number to a character,
+which makes no sense.
+.IP \(bu 4
+Cannot print \f(CW%f\fR with '%c'
+.Sp
+(F) You tried printing an infinity or not-a-number as a character (\f(CW%c\fR),
+which makes no sense.  Maybe you meant \f(CW\*(Aq%s\*(Aq\fR, or just stringifying it?
+.IP \(bu 4
+charnames alias definitions may not contain a sequence of multiple spaces
+.Sp
+(F) You defined a character name which had multiple space
+characters in a row.  Change them to single spaces.  Usually these
+names are defined in the \f(CW\*(C`:alias\*(C'\fR import argument to \f(CW\*(C`use charnames\*(C'\fR, but
+they could be defined by a translator installed into \f(CW$^H{charnames}\fR.
+See "CUSTOM ALIASES" in charnames.
+.IP \(bu 4
+charnames alias definitions may not contain trailing white-space
+.Sp
+(F) You defined a character name which ended in a space
+character.  Remove the trailing space(s).  Usually these names are
+defined in the \f(CW\*(C`:alias\*(C'\fR import argument to \f(CW\*(C`use charnames\*(C'\fR, but they
+could be defined by a translator installed into \f(CW$^H{charnames}\fR.
+See "CUSTOM ALIASES" in charnames.
+.IP \(bu 4
+:const is not permitted on named subroutines
+.Sp
+(F) The \f(CW\*(C`const\*(C'\fR attribute causes an anonymous subroutine to be run and
+its value captured at the time that it is cloned.  Named subroutines are
+not cloned like this, so the attribute does not make sense on them.
+.IP \(bu 4
+Hexadecimal float: internal error
+.Sp
+(F) Something went horribly bad in hexadecimal float handling.
+.IP \(bu 4
+Hexadecimal float: unsupported long double format
+.Sp
+(F) You have configured Perl to use long doubles but
+the internals of the long double format are unknown,
+therefore the hexadecimal float output is impossible.
+.IP \(bu 4
+Illegal suidscript
+.Sp
+(F) The script run under suidperl was somehow illegal.
+.IP \(bu 4
+In '(?...)', the '(' and '?' must be adjacent in regex; marked by <\-\-\ HERE in m/%s/
+.Sp
+(F) The two-character sequence \f(CW"(?"\fR in
+this context in a regular expression pattern should be an
+indivisible token, with nothing intervening between the \f(CW"("\fR
+and the \f(CW"?"\fR, but you separated them.
+.IP \(bu 4
+In '(*VERB...)', the '(' and '*' must be adjacent in regex; marked by <\-\-\ HERE in m/%s/
+.Sp
+(F) The two-character sequence \f(CW"(*"\fR in
+this context in a regular expression pattern should be an
+indivisible token, with nothing intervening between the \f(CW"("\fR
+and the \f(CW"*"\fR, but you separated them.
+.IP \(bu 4
+Invalid quantifier in {,} in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(F) The pattern looks like a {min,max} quantifier, but the min or max could not
+be parsed as a valid number: either it has leading zeroes, or it represents
+too big a number to cope with.  The <\-\-\ HERE shows where in the regular
+expression the problem was discovered.  See perlre.
+.IP \(bu 4
+\&'%s' is an unknown bound type in regex
+.Sp
+(F) You used \f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR and the \f(CW\*(C`...\*(C'\fR is not known to
+Perl.  The current valid ones are given in
+"\eb{}, \eb, \eB{}, \eB" in perlrebackslash.
+.IP \(bu 4
+Missing or undefined argument to require
+.Sp
+(F) You tried to call \f(CW\*(C`require\*(C'\fR with no argument or with an undefined
+value as an argument.  \f(CW\*(C`require\*(C'\fR expects either a package name or a
+file-specification as an argument.  See "require" in perlfunc.
+.Sp
+Formerly, \f(CW\*(C`require\*(C'\fR with no argument or \f(CW\*(C`undef\*(C'\fR warned about a Null filename.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+\&\eC is deprecated in regex
+.Sp
+(D deprecated) The \f(CW\*(C`/\eC/\*(C'\fR character class was deprecated in v5.20, and
+now emits a warning. It is intended that it will become an error in v5.24.
+This character class matches a single byte even if it appears within a
+multi-byte character, breaks encapsulation, and can corrupt UTF\-8
+strings.
+.IP \(bu 4
+"%s" is more clearly written simply as "%s" in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+You specified a character that has the given plainer way of writing it,
+and which is also portable to platforms running with different character
+sets.
+.IP \(bu 4
+Argument "%s" treated as 0 in increment (++)
+.Sp
+(W numeric) The indicated string was fed as an argument to the \f(CW\*(C`++\*(C'\fR operator
+which expects either a number or a string matching \f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR.
+See "Auto-increment and Auto-decrement" in perlop for details.
+.IP \(bu 4
+Both or neither range ends should be Unicode in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+In a bracketed character class in a regular expression pattern, you
+had a range which has exactly one end of it specified using \f(CW\*(C`\eN{}\*(C'\fR, and
+the other end is specified using a non-portable mechanism.  Perl treats
+the range as a Unicode range, that is, all the characters in it are
+considered to be the Unicode characters, and which may be different code
+points on some platforms Perl runs on.  For example, \f(CW\*(C`[\eN{U+06}\-\ex08]\*(C'\fR
+is treated as if you had instead said \f(CW\*(C`[\eN{U+06}\-\eN{U+08}]\*(C'\fR, that is it
+matches the characters whose code points in Unicode are 6, 7, and 8.
+But that \f(CW\*(C`\ex08\*(C'\fR might indicate that you meant something different, so
+the warning gets raised.
+.IP \(bu 4
+Can't do %s("%s") on non\-UTF\-8 locale; resolved to "%s".
+.Sp
+(W locale) You are 1) running under "\f(CW\*(C`use locale\*(C'\fR"; 2) the current
+locale is not a UTF\-8 one; 3) you tried to do the designated case-change
+operation on the specified Unicode character; and 4) the result of this
+operation would mix Unicode and locale rules, which likely conflict.
+.Sp
+The warnings category \f(CW\*(C`locale\*(C'\fR is new.
+.IP \(bu 4
+:const is experimental
+.Sp
+(S experimental::const_attr) The \f(CW\*(C`const\*(C'\fR attribute is experimental.
+If you want to use the feature, disable the warning with \f(CWno warnings
+\&\*(Aqexperimental::const_attr\*(Aq\fR, but know that in doing so you are taking
+the risk that your code may break in a future Perl version.
+.IP \(bu 4
+gmtime(%f) failed
+.Sp
+(W overflow) You called \f(CW\*(C`gmtime\*(C'\fR with a number that it could not handle:
+too large, too small, or NaN.  The returned value is \f(CW\*(C`undef\*(C'\fR.
+.IP \(bu 4
+Hexadecimal float: exponent overflow
+.Sp
+(W overflow) The hexadecimal floating point has larger exponent
+than the floating point supports.
+.IP \(bu 4
+Hexadecimal float: exponent underflow
+.Sp
+(W overflow) The hexadecimal floating point has smaller exponent
+than the floating point supports.
+.IP \(bu 4
+Hexadecimal float: mantissa overflow
+.Sp
+(W overflow) The hexadecimal floating point literal had more bits in
+the mantissa (the part between the \f(CW\*(C`0x\*(C'\fR and the exponent, also known as
+the fraction or the significand) than the floating point supports.
+.IP \(bu 4
+Hexadecimal float: precision loss
+.Sp
+(W overflow) The hexadecimal floating point had internally more
+digits than could be output.  This can be caused by unsupported
+long double formats, or by 64\-bit integers not being available
+(needed to retrieve the digits under some configurations).
+.IP \(bu 4
+Locale '%s' may not work well.%s
+.Sp
+(W locale) You are using the named locale, which is a non\-UTF\-8 one, and
+which perl has determined is not fully compatible with what it can
+handle.  The second \f(CW%s\fR gives a reason.
+.Sp
+The warnings category \f(CW\*(C`locale\*(C'\fR is new.
+.IP \(bu 4
+localtime(%f) failed
+.Sp
+(W overflow) You called \f(CW\*(C`localtime\*(C'\fR with a number that it could not handle:
+too large, too small, or NaN.  The returned value is \f(CW\*(C`undef\*(C'\fR.
+.IP \(bu 4
+Negative repeat count does nothing
+.Sp
+(W numeric) You tried to execute the
+\&\f(CW\*(C`x\*(C'\fR repetition operator fewer than 0
+times, which doesn't make sense.
+.IP \(bu 4
+NO-BREAK SPACE in a charnames alias definition is deprecated
+.Sp
+(D deprecated) You defined a character name which contained a no-break
+space character.  Change it to a regular space.  Usually these names are
+defined in the \f(CW\*(C`:alias\*(C'\fR import argument to \f(CW\*(C`use charnames\*(C'\fR, but they
+could be defined by a translator installed into \f(CW$^H{charnames}\fR.  See
+"CUSTOM ALIASES" in charnames.
+.IP \(bu 4
+Non-finite repeat count does nothing
+.Sp
+(W numeric) You tried to execute the
+\&\f(CW\*(C`x\*(C'\fR repetition operator \f(CW\*(C`Inf\*(C'\fR (or
+\&\f(CW\*(C`\-Inf\*(C'\fR) or NaN times, which doesn't make sense.
+.IP \(bu 4
+PerlIO layer ':win32' is experimental
+.Sp
+(S experimental::win32_perlio) The \f(CW\*(C`:win32\*(C'\fR PerlIO layer is
+experimental.  If you want to take the risk of using this layer,
+simply disable this warning:
+.Sp
+.Vb 1
+\&    no warnings "experimental::win32_perlio";
+.Ve
+.IP \(bu 4
+Ranges of ASCII printables should be some subset of "0\-9", "A\-Z", or "a\-z" in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+Stricter rules help to find typos and other errors.  Perhaps you didn't
+even intend a range here, if the \f(CW"\-"\fR was meant to be some other
+character, or should have been escaped (like \f(CW"\e\-"\fR).  If you did
+intend a range, the one that was used is not portable between ASCII and
+EBCDIC platforms, and doesn't have an obvious meaning to a casual
+reader.
+.Sp
+.Vb 7
+\& [3\-7]    # OK; Obvious and portable
+\& [d\-g]    # OK; Obvious and portable
+\& [A\-Y]    # OK; Obvious and portable
+\& [A\-z]    # WRONG; Not portable; not clear what is meant
+\& [a\-Z]    # WRONG; Not portable; not clear what is meant
+\& [%\-.]    # WRONG; Not portable; not clear what is meant
+\& [\ex41\-Z] # WRONG; Not portable; not obvious to non\-geek
+.Ve
+.Sp
+(You can force portability by specifying a Unicode range, which means that
+the endpoints are specified by
+\&\f(CW\*(C`\eN{...}\*(C'\fR, but the meaning may
+still not be obvious.)
+The stricter rules require that ranges that start or stop with an ASCII
+character that is not a control have all their endpoints be a literal
+character, and not some escape sequence (like \f(CW"\ex41"\fR), and the ranges
+must be all digits, or all uppercase letters, or all lowercase letters.
+.IP \(bu 4
+Ranges of digits should be from the same group in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+Stricter rules help to find typos and other errors.  You included a
+range, and at least one of the end points is a decimal digit.  Under the
+stricter rules, when this happens, both end points should be digits in
+the same group of 10 consecutive digits.
+.IP \(bu 4
+Redundant argument in \f(CW%s\fR
+.Sp
+(W redundant) You called a function with more arguments than were
+needed, as indicated by information within other arguments you supplied
+(\fIe.g\fR. a printf format). Currently only emitted when a printf-type format
+required fewer arguments than were supplied, but might be used in the
+future for \fIe.g.\fR "pack" in perlfunc.
+.Sp
+The warnings category \f(CW\*(C`redundant\*(C'\fR is new. See also
+[GH #13534] <https://github.com/Perl/perl5/issues/13534>.
+.IP \(bu 4
+Replacement list is longer than search list
+.Sp
+This is not a new diagnostic, but in earlier releases was accidentally
+not displayed if the transliteration contained wide characters.  This is
+now fixed, so that you may see this diagnostic in places where you
+previously didn't (but should have).
+.IP \(bu 4
+Use of \eb{} for non\-UTF\-8 locale is wrong.  Assuming a UTF\-8 locale
+.Sp
+(W locale) You are matching a regular expression using locale rules,
+and a Unicode boundary is being matched, but the locale is not a Unicode
+one.  This doesn't make sense.  Perl will continue, assuming a Unicode
+(UTF\-8) locale, but the results could well be wrong except if the locale
+happens to be ISO\-8859\-1 (Latin1) where this message is spurious and can
+be ignored.
+.Sp
+The warnings category \f(CW\*(C`locale\*(C'\fR is new.
+.IP \(bu 4
+Using /u for '%s' instead of /%s in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(W regexp) You used a Unicode boundary (\f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR) in a
+portion of a regular expression where the character set modifiers \f(CW\*(C`/a\*(C'\fR
+or \f(CW\*(C`/aa\*(C'\fR are in effect.  These two modifiers indicate an ASCII
+interpretation, and this doesn't make sense for a Unicode definition.
+The generated regular expression will compile so that the boundary uses
+all of Unicode.  No other portion of the regular expression is affected.
+.IP \(bu 4
+The bitwise feature is experimental
+.Sp
+(S experimental::bitwise) This warning is emitted if you use bitwise
+operators (\f(CW\*(C`& | ^ ~ &. |. ^. ~.\*(C'\fR) with the "bitwise" feature enabled.
+Simply suppress the warning if you want to use the feature, but know
+that in doing so you are taking the risk of using an experimental
+feature which may change or be removed in a future Perl version:
+.Sp
+.Vb 3
+\&    no warnings "experimental::bitwise";
+\&    use feature "bitwise";
+\&    $x |.= $y;
+.Ve
+.IP \(bu 4
+Unescaped left brace in regex is deprecated, passed through in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(D deprecated, regexp) You used a literal \f(CW"{"\fR character in a regular
+expression pattern. You should change to use \f(CW"\e{"\fR instead, because a future
+version of Perl (tentatively v5.26) will consider this to be a syntax error.  If
+the pattern delimiters are also braces, any matching right brace
+(\f(CW"}"\fR) should also be escaped to avoid confusing the parser, for
+example,
+.Sp
+.Vb 1
+\&    qr{abc\e{def\e}ghi}
+.Ve
+.IP \(bu 4
+Use of literal non-graphic characters in variable names is deprecated
+.Sp
+(D deprecated) Using literal non-graphic (including control)
+characters in the source to refer to the \fI^FOO\fR variables, like \f(CW$^X\fR and
+\&\f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR is now deprecated.
+.IP \(bu 4
+Useless use of attribute "const"
+.Sp
+(W misc) The \f(CW\*(C`const\*(C'\fR attribute has no effect except
+on anonymous closure prototypes.  You applied it to
+a subroutine via attributes.pm.  This is only useful
+inside an attribute handler for an anonymous subroutine.
+.IP \(bu 4
+Useless use of /d modifier in transliteration operator
+.Sp
+This is not a new diagnostic, but in earlier releases was accidentally
+not displayed if the transliteration contained wide characters.  This is
+now fixed, so that you may see this diagnostic in places where you
+previously didn't (but should have).
+.IP \(bu 4
+"use re 'strict'" is experimental
+.Sp
+(S experimental::re_strict) The things that are different when a regular
+expression pattern is compiled under \f(CW\*(Aqstrict\*(Aq\fR are subject to change
+in future Perl releases in incompatible ways; there are also proposals
+to change how to enable strict checking instead of using this subpragma.
+This means that a pattern that compiles today may not in a future Perl
+release.  This warning is to alert you to that risk.
+.IP \(bu 4
+Warning: unable to close filehandle properly: \f(CW%s\fR
+.Sp
+Warning: unable to close filehandle \f(CW%s\fR properly: \f(CW%s\fR
+.Sp
+(S io) Previously, perl silently ignored any errors when doing an implicit
+close of a filehandle, \fIi.e.\fR where the reference count of the filehandle
+reached zero and the user's code hadn't already called \f(CWclose()\fR; \fIe.g.\fR
+.Sp
+.Vb 4
+\&    {
+\&        open my $fh, \*(Aq>\*(Aq, $file  or die "open: \*(Aq$file\*(Aq: $!\en";
+\&        print $fh, $data  or die;
+\&    } # implicit close here
+.Ve
+.Sp
+In a situation such as disk full, due to buffering, the error may only be
+detected during the final close, so not checking the result of the close is
+dangerous.
+.Sp
+So perl now warns in such situations.
+.IP \(bu 4
+Wide character (U+%X) in \f(CW%s\fR
+.Sp
+(W locale) While in a single-byte locale (\fIi.e.\fR, a non\-UTF\-8
+one), a multi-byte character was encountered.   Perl considers this
+character to be the specified Unicode code point.  Combining non\-UTF\-8
+locales and Unicode is dangerous.  Almost certainly some characters
+will have two different representations.  For example, in the ISO 8859\-7
+(Greek) locale, the code point 0xC3 represents a Capital Gamma.  But so
+also does 0x393.  This will make string comparisons unreliable.
+.Sp
+You likely need to figure out how this multi-byte character got mixed up
+with your single-byte locale (or perhaps you thought you had a UTF\-8
+locale, but Perl disagrees).
+.Sp
+The warnings category \f(CW\*(C`locale\*(C'\fR is new.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+<> should be quotes
+.Sp
+This warning has been changed to
+<> at require-statement should be quotes
+to make the issue more identifiable.
+.IP \(bu 4
+Argument "%s" isn't numeric%s
+.Sp
+The perldiag entry for this warning has added this clarifying note:
+.Sp
+.Vb 4
+\& Note that for the Inf and NaN (infinity and not\-a\-number) the
+\& definition of "numeric" is somewhat unusual: the strings themselves
+\& (like "Inf") are considered numeric, and anything following them is
+\& considered non\-numeric.
+.Ve
+.IP \(bu 4
+Global symbol "%s" requires explicit package name
+.Sp
+This message has had '(did you forget to declare "my \f(CW%s\fR"?)' appended to it, to
+make it more helpful to new Perl programmers.
+[GH #13732] <https://github.com/Perl/perl5/issues/13732>
+.IP \(bu 4
+\&'"my" variable &foo::bar can't be in a package' has been reworded to say
+\&'subroutine' instead of 'variable'.
+.IP \(bu 4
+\&\eN{} in character class restricted to one character in regex; marked by
+<\-\-\ HERE in m/%s/
+.Sp
+This message has had \fIcharacter class\fR changed to \fIinverted character
+class or as a range end-point is\fR to reflect improvements in
+\&\f(CW\*(C`qr/[\eN{named sequence}]/\*(C'\fR (see under "Selected Bug Fixes").
+.IP \(bu 4
+panic: frexp
+.Sp
+This message has had ': \f(CW%f\fR' appended to it, to show what the offending
+floating point number is.
+.IP \(bu 4
+\&\fIPossible precedence problem on bitwise \fR\f(CI%c\fR\fI operator\fR reworded as
+Possible precedence problem on bitwise \f(CW%s\fR operator.
+.IP \(bu 4
+Unsuccessful \f(CW%s\fR on filename containing newline
+.Sp
+This warning is now only produced when the newline is at the end of
+the filename.
+.IP \(bu 4
+"Variable \f(CW%s\fR will not stay shared" has been changed to say "Subroutine"
+when it is actually a lexical sub that will not stay shared.
+.IP \(bu 4
+Variable length lookbehind not implemented in regex m/%s/
+.Sp
+The perldiag entry for this warning has had information about Unicode
+behavior added.
+.SS "Diagnostic Removals"
+.IX Subsection "Diagnostic Removals"
+.IP \(bu 4
+"Ambiguous use of \-foo resolved as \-&\fBfoo()\fR"
+.Sp
+There is actually no ambiguity here, and this impedes the use of negated
+constants; \fIe.g.\fR, \f(CW\*(C`\-Inf\*(C'\fR.
+.IP \(bu 4
+"Constant is not a FOO reference"
+.Sp
+Compile-time checking of constant dereferencing (\fIe.g.\fR, \f(CWmy_constant\->()\fR)
+has been removed, since it was not taking overloading into account.
+[GH #9891] <https://github.com/Perl/perl5/issues/9891>
+[GH #14044] <https://github.com/Perl/perl5/issues/14044>
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "\fIfind2perl\fP, \fIs2p\fP and \fIa2p\fP removal"
+.IX Subsection "find2perl, s2p and a2p removal"
+.IP \(bu 4
+The \fIx2p/\fR directory has been removed from the Perl core.
+.Sp
+This removes find2perl, s2p and a2p. They have all been released to CPAN as
+separate distributions (\f(CW\*(C`App::find2perl\*(C'\fR, \f(CW\*(C`App::s2p\*(C'\fR, \f(CW\*(C`App::a2p\*(C'\fR).
+.SS h2ph
+.IX Subsection "h2ph"
+.IP \(bu 4
+\&\fIh2ph\fR now handles hexadecimal constants in the compiler's predefined
+macro definitions, as visible in \f(CW$Config{cppsymbols}\fR.
+[GH #14491] <https://github.com/Perl/perl5/issues/14491>.
+.SS encguess
+.IX Subsection "encguess"
+.IP \(bu 4
+No longer depends on non-core modules.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\fIConfigure\fR now checks for \f(CWlrintl()\fR, \f(CWlroundl()\fR, \f(CWllrintl()\fR, and
+\&\f(CWllroundl()\fR.
+.IP \(bu 4
+\&\fIConfigure\fR with \f(CW\*(C`\-Dmksymlinks\*(C'\fR should now be faster.
+[GH #13890] <https://github.com/Perl/perl5/issues/13890>.
+.IP \(bu 4
+The \f(CW\*(C`pthreads\*(C'\fR and \f(CW\*(C`cl\*(C'\fR libraries will be linked by default if present.
+This allows XS modules that require threading to work on non-threaded
+perls. Note that you must still pass \f(CW\*(C`\-Dusethreads\*(C'\fR if you want a
+threaded perl.
+.IP \(bu 4
+To get more precision and range for floating point numbers one can now
+use the GCC quadmath library which implements the quadruple precision
+floating point numbers on x86 and IA\-64 platforms.  See \fIINSTALL\fR for
+details.
+.IP \(bu 4
+MurmurHash64A and MurmurHash64B can now be configured as the internal hash
+function.
+.IP \(bu 4
+\&\f(CW\*(C`make test.valgrind\*(C'\fR now supports parallel testing.
+.Sp
+For example:
+.Sp
+.Vb 1
+\&    TEST_JOBS=9 make test.valgrind
+.Ve
+.Sp
+See "valgrind" in perlhacktips for more information.
+.Sp
+[GH #13658] <https://github.com/Perl/perl5/issues/13658>
+.IP \(bu 4
+The MAD (Misc Attribute Decoration) build option has been removed
+.Sp
+This was an unmaintained attempt at preserving
+the Perl parse tree more faithfully so that automatic conversion of
+Perl 5 to Perl 6 would have been easier.
+.Sp
+This build-time configuration option had been unmaintained for years,
+and had probably seriously diverged on both Perl 5 and Perl 6 sides.
+.IP \(bu 4
+A new compilation flag, \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR is available. For details,
+see the discussion below at "Internal Changes".
+.IP \(bu 4
+Pathtools no longer tries to load XS on miniperl. This speeds up building perl
+slightly.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+\&\fIt/porting/re_context.t\fR has been added to test that utf8 and its
+dependencies only use the subset of the \f(CW\*(C`$1..$n\*(C'\fR capture vars that
+\&\f(CWPerl_save_re_context()\fR is hard-coded to localize, because that function
+has no efficient way of determining at runtime what vars to localize.
+.IP \(bu 4
+Tests for performance issues have been added in the file \fIt/perf/taint.t\fR.
+.IP \(bu 4
+Some regular expression tests are written in such a way that they will
+run very slowly if certain optimizations break. These tests have been
+moved into new files, \fIt/re/speed.t\fR and \fIt/re/speed_thr.t\fR,
+and are run with a \f(CWwatchdog()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`test.pl\*(C'\fR now allows \f(CW\*(C`plan skip_all => $reason\*(C'\fR, to make it
+more compatible with \f(CW\*(C`Test::More\*(C'\fR.
+.IP \(bu 4
+A new test script, \fIop/infnan.t\fR, has been added to test if infinity and NaN are
+working correctly.  See "Infinity and NaN (not-a-number) handling improved".
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Regained Platforms"
+.IX Subsection "Regained Platforms"
+.IP "IRIX and Tru64 platforms are working again." 4
+.IX Item "IRIX and Tru64 platforms are working again."
+Some \f(CW\*(C`make test\*(C'\fR failures remain:
+[GH #14557] <https://github.com/Perl/perl5/issues/14557>
+and [GH #14727] <https://github.com/Perl/perl5/issues/14727>
+for IRIX; [GH #14629] <https://github.com/Perl/perl5/issues/14629>,
+[cpan #99605] <https://rt.cpan.org/Public/Bug/Display.html?id=99605>, and
+[cpan #104836] <https://rt.cpan.org/Ticket/Display.html?id=104836> for Tru64.
+.IP "z/OS running EBCDIC Code Page 1047" 4
+.IX Item "z/OS running EBCDIC Code Page 1047"
+Core perl now works on this EBCDIC platform.  Earlier perls also worked, but,
+even though support wasn't officially withdrawn, recent perls would not compile
+and run well.  Perl 5.20 would work, but had many bugs which have now been
+fixed.  Many CPAN modules that ship with Perl still fail tests, including
+\&\f(CW\*(C`Pod::Simple\*(C'\fR.  However the version of \f(CW\*(C`Pod::Simple\*(C'\fR currently on CPAN should work;
+it was fixed too late to include in Perl 5.22.  Work is under way to fix many
+of the still-broken CPAN modules, which likely will be installed on CPAN when
+completed, so that you may not have to wait until Perl 5.24 to get a working
+version.
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP NeXTSTEP/OPENSTEP 4
+.IX Item "NeXTSTEP/OPENSTEP"
+NeXTSTEP was a proprietary operating system bundled with NeXT's
+workstations in the early to mid 90s; OPENSTEP was an API specification
+that provided a NeXTSTEP-like environment on a non-NeXTSTEP system.  Both
+are now long dead, so support for building Perl on them has been removed.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP EBCDIC 4
+.IX Item "EBCDIC"
+Special handling is required of the perl interpreter on EBCDIC platforms
+to get \f(CW\*(C`qr/[i\-j]/\*(C'\fR to match only \f(CW"i"\fR and \f(CW"j"\fR, since there are 7
+characters between the
+code points for \f(CW"i"\fR and \f(CW"j"\fR.  This special handling had only been
+invoked when both ends of the range are literals.  Now it is also
+invoked if any of the \f(CW\*(C`\eN{...}\*(C'\fR forms for specifying a character by
+name or Unicode code point is used instead of a literal.  See
+"Character Ranges" in perlrecharclass.
+.IP HP-UX 4
+.IX Item "HP-UX"
+The archname now distinguishes use64bitint from use64bitall.
+.IP Android 4
+.IX Item "Android"
+Build support has been improved for cross-compiling in general and for
+Android in particular.
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+When spawning a subprocess without waiting, the return value is now
+the correct PID.
+.IP \(bu 4
+Fix a prototype so linking doesn't fail under the VMS C++ compiler.
+.IP \(bu 4
+\&\f(CW\*(C`finite\*(C'\fR, \f(CW\*(C`finitel\*(C'\fR, and \f(CW\*(C`isfinite\*(C'\fR detection has been added to
+\&\f(CW\*(C`configure.com\*(C'\fR, environment handling has had some minor changes, and
+a fix for legacy feature checking status.
+.RE
+.RS 4
+.RE
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\fIminiperl.exe\fR is now built with \f(CW\*(C`\-fno\-strict\-aliasing\*(C'\fR, allowing 64\-bit
+builds to complete on GCC 4.8.
+[GH #14556] <https://github.com/Perl/perl5/issues/14556>
+.IP \(bu 4
+\&\f(CW\*(C`nmake minitest\*(C'\fR now works on Win32.  Due to dependency issues you
+need to build \f(CW\*(C`nmake test\-prep\*(C'\fR first, and a small number of the
+tests fail.
+[GH #14318] <https://github.com/Perl/perl5/issues/14318>
+.IP \(bu 4
+Perl can now be built in C++ mode on Windows by setting the makefile macro
+\&\f(CW\*(C`USE_CPLUSPLUS\*(C'\fR to the value "define".
+.IP \(bu 4
+The list form of piped open has been implemented for Win32.  Note: unlike
+\&\f(CW\*(C`system LIST\*(C'\fR this does not fall back to the shell.
+[GH #13574] <https://github.com/Perl/perl5/issues/13574>
+.IP \(bu 4
+New \f(CW\*(C`DebugSymbols\*(C'\fR and \f(CW\*(C`DebugFull\*(C'\fR configuration options added to
+Windows makefiles.
+.IP \(bu 4
+Previously, compiling XS modules (including CPAN ones) using Visual C++ for
+Win64 resulted in around a dozen warnings per file from \fIhv_func.h\fR.  These
+warnings have been silenced.
+.IP \(bu 4
+Support for building without PerlIO has been removed from the Windows
+makefiles.  Non-PerlIO builds were all but deprecated in Perl 5.18.0 and are
+already not supported by \fIConfigure\fR on POSIX systems.
+.IP \(bu 4
+Between 2 and 6 milliseconds and seven I/O calls have been saved per attempt
+to open a perl module for each path in \f(CW@INC\fR.
+.IP \(bu 4
+Intel C builds are now always built with C99 mode on.
+.IP \(bu 4
+\&\f(CW%I64d\fR is now being used instead of \f(CW%lld\fR for MinGW.
+.IP \(bu 4
+In the experimental \f(CW\*(C`:win32\*(C'\fR layer, a crash in \f(CW\*(C`open\*(C'\fR was fixed. Also
+opening \fI/dev/null\fR (which works under Win32 Perl's default \f(CW\*(C`:unix\*(C'\fR
+layer) was implemented for \f(CW\*(C`:win32\*(C'\fR.
+[GH #13968] <https://github.com/Perl/perl5/issues/13968>
+.IP \(bu 4
+A new makefile option, \f(CW\*(C`USE_LONG_DOUBLE\*(C'\fR, has been added to the Windows
+dmake makefile for gcc builds only.  Set this to "define" if you want perl to
+use long doubles to give more accuracy and range for floating point numbers.
+.RE
+.RS 4
+.RE
+.IP OpenBSD 4
+.IX Item "OpenBSD"
+On OpenBSD, Perl will now default to using the system \f(CW\*(C`malloc\*(C'\fR due to the
+security features it provides. Perl's own malloc wrapper has been in use
+since v5.14 due to performance reasons, but the OpenBSD project believes
+the tradeoff is worth it and would prefer that users who need the speed
+specifically ask for it.
+.Sp
+[GH #13888] <https://github.com/Perl/perl5/issues/13888>.
+.IP Solaris 4
+.IX Item "Solaris"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+We now look for the Sun Studio compiler in both \fI/opt/solstudio*\fR and
+\&\fI/opt/solarisstudio*\fR.
+.IP \(bu 4
+Builds on Solaris 10 with \f(CW\*(C`\-Dusedtrace\*(C'\fR would fail early since make
+didn't follow implied dependencies to build \f(CW\*(C`perldtrace.h\*(C'\fR.  Added an
+explicit dependency to \f(CW\*(C`depend\*(C'\fR.
+[GH #13334] <https://github.com/Perl/perl5/issues/13334>
+.IP \(bu 4
+C99 options have been cleaned up; hints look for \f(CW\*(C`solstudio\*(C'\fR
+as well as \f(CW\*(C`SUNWspro\*(C'\fR; and support for native \f(CW\*(C`setenv\*(C'\fR has been added.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Experimental support has been added to allow ops in the optree to locate
+their parent, if any. This is enabled by the non-default build option
+\&\f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR. It is envisaged that this will eventually become
+enabled by default, so XS code which directly accesses the \f(CW\*(C`op_sibling\*(C'\fR
+field of ops should be updated to be future-proofed.
+.Sp
+On \f(CW\*(C`PERL_OP_PARENT\*(C'\fR builds, the \f(CW\*(C`op_sibling\*(C'\fR field has been renamed
+\&\f(CW\*(C`op_sibparent\*(C'\fR and a new flag, \f(CW\*(C`op_moresib\*(C'\fR, added. On the last op in a
+sibling chain, \f(CW\*(C`op_moresib\*(C'\fR is false and \f(CW\*(C`op_sibparent\*(C'\fR points to the
+parent (if any) rather than being \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+To make existing code work transparently whether using \f(CW\*(C`PERL_OP_PARENT\*(C'\fR
+or not, a number of new macros and functions have been added that should
+be used, rather than directly manipulating \f(CW\*(C`op_sibling\*(C'\fR.
+.Sp
+For the case of just reading \f(CW\*(C`op_sibling\*(C'\fR to determine the next sibling,
+two new macros have been added. A simple scan through a sibling chain
+like this:
+.Sp
+.Vb 1
+\&    for (; kid\->op_sibling; kid = kid\->op_sibling) { ... }
+.Ve
+.Sp
+should now be written as:
+.Sp
+.Vb 1
+\&    for (; OpHAS_SIBLING(kid); kid = OpSIBLING(kid)) { ... }
+.Ve
+.Sp
+For altering optrees, a general-purpose function \f(CWop_sibling_splice()\fR
+has been added, which allows for manipulation of a chain of sibling ops.
+By analogy with the Perl function \f(CWsplice()\fR, it allows you to cut out
+zero or more ops from a sibling chain and replace them with zero or more
+new ops.  It transparently handles all the updating of sibling, parent,
+op_last pointers etc.
+.Sp
+If you need to manipulate ops at a lower level, then three new macros,
+\&\f(CW\*(C`OpMORESIB_set\*(C'\fR, \f(CW\*(C`OpLASTSIB_set\*(C'\fR and \f(CW\*(C`OpMAYBESIB_set\*(C'\fR are intended to
+be a low-level portable way to set \f(CW\*(C`op_sibling\*(C'\fR / \f(CW\*(C`op_sibparent\*(C'\fR while
+also updating \f(CW\*(C`op_moresib\*(C'\fR.  The first sets the sibling pointer to a new
+sibling, the second makes the op the last sibling, and the third
+conditionally does the first or second action.  Note that unlike
+\&\f(CWop_sibling_splice()\fR these macros won't maintain consistency in the
+parent at the same time (\fIe.g.\fR by updating \f(CW\*(C`op_first\*(C'\fR and \f(CW\*(C`op_last\*(C'\fR where
+appropriate).
+.Sp
+A C\-level \f(CWPerl_op_parent()\fR function and a Perl-level \f(CWB::OP::parent()\fR
+method have been added. The C function only exists under
+\&\f(CW\*(C`PERL_OP_PARENT\*(C'\fR builds (using it is build-time error on vanilla
+perls).  \f(CWB::OP::parent()\fR exists always, but on a vanilla build it
+always returns \f(CW\*(C`NULL\*(C'\fR. Under \f(CW\*(C`PERL_OP_PARENT\*(C'\fR, they return the parent
+of the current op, if any. The variable \f(CW$B::OP::does_parent\fR allows you
+to determine whether \f(CW\*(C`B\*(C'\fR supports retrieving an op's parent.
+.Sp
+\&\f(CW\*(C`PERL_OP_PARENT\*(C'\fR was introduced in 5.21.2, but the interface was
+changed considerably in 5.21.11. If you updated your code before the
+5.21.11 changes, it may require further revision. The main changes after
+5.21.2 were:
+.RS 4
+.IP \(bu 4
+The \f(CW\*(C`OP_SIBLING\*(C'\fR and \f(CW\*(C`OP_HAS_SIBLING\*(C'\fR macros have been renamed
+\&\f(CW\*(C`OpSIBLING\*(C'\fR and \f(CW\*(C`OpHAS_SIBLING\*(C'\fR for consistency with other
+op-manipulating macros.
+.IP \(bu 4
+The \f(CW\*(C`op_lastsib\*(C'\fR field has been renamed \f(CW\*(C`op_moresib\*(C'\fR, and its meaning
+inverted.
+.IP \(bu 4
+The macro \f(CW\*(C`OpSIBLING_set\*(C'\fR has been removed, and has been superseded by
+\&\f(CW\*(C`OpMORESIB_set\*(C'\fR \fIet al\fR.
+.IP \(bu 4
+The \f(CWop_sibling_splice()\fR function now accepts a null \f(CW\*(C`parent\*(C'\fR argument
+where the splicing doesn't affect the first or last ops in the sibling
+chain
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Macros have been created to allow XS code to better manipulate the POSIX locale
+category \f(CW\*(C`LC_NUMERIC\*(C'\fR.  See "Locale-related functions and macros" in perlapi.
+.IP \(bu 4
+The previous \f(CW\*(C`atoi\*(C'\fR \fIet al\fR replacement function, \f(CW\*(C`grok_atou\*(C'\fR, has now been
+superseded by \f(CW\*(C`grok_atoUV\*(C'\fR.  See perlclib for details.
+.IP \(bu 4
+A new function, \f(CWPerl_sv_get_backrefs()\fR, has been added which allows you
+retrieve the weak references, if any, which point at an SV.
+.IP \(bu 4
+The \f(CWscreaminstr()\fR function has been removed. Although marked as
+public API, it was undocumented and had no usage in CPAN modules. Calling
+it has been fatal since 5.17.0.
+.IP \(bu 4
+The \f(CWnewDEFSVOP()\fR, \f(CWblock_start()\fR, \f(CWblock_end()\fR and \f(CWintro_my()\fR
+functions have been added to the API.
+.IP \(bu 4
+The internal \f(CW\*(C`convert\*(C'\fR function in \fIop.c\fR has been renamed
+\&\f(CW\*(C`op_convert_list\*(C'\fR and added to the API.
+.IP \(bu 4
+The \f(CWsv_magic()\fR function no longer forbids "ext" magic on read-only
+values.  After all, perl can't know whether the custom magic will modify
+the SV or not.
+[GH #14202] <https://github.com/Perl/perl5/issues/14202>.
+.IP \(bu 4
+Accessing "CvPADLIST" in perlapi on an XSUB is now forbidden.
+.Sp
+The \f(CW\*(C`CvPADLIST\*(C'\fR field has been reused for a different internal purpose
+for XSUBs. So in particular, you can no longer rely on it being NULL as a
+test of whether a CV is an XSUB. Use \f(CWCvISXSUB()\fR instead.
+.IP \(bu 4
+SVs of type \f(CW\*(C`SVt_NV\*(C'\fR are now sometimes bodiless when the build
+configuration and platform allow it: specifically, when \f(CWsizeof(NV) <=
+sizeof(IV)\fR. "Bodiless" means that the NV value is stored directly in
+the head of an SV, without requiring a separate body to be allocated. This
+trick has already been used for IVs since 5.9.2 (though in the case of
+IVs, it is always used, regardless of platform and build configuration).
+.IP \(bu 4
+The \f(CW$DB::single\fR, \f(CW$DB::signal\fR and \f(CW$DB::trace\fR variables now have set\- and
+get-magic that stores their values as IVs, and those IVs are used when
+testing their values in \f(CWpp_dbstate()\fR.  This prevents perl from
+recursing infinitely if an overloaded object is assigned to any of those
+variables.
+[GH #14013] <https://github.com/Perl/perl5/issues/14013>.
+.IP \(bu 4
+\&\f(CWPerl_tmps_grow()\fR, which is marked as public API but is undocumented, has
+been removed from the public API. This change does not affect XS code that
+uses the \f(CW\*(C`EXTEND_MORTAL\*(C'\fR macro to pre-extend the mortal stack.
+.IP \(bu 4
+Perl's internals no longer sets or uses the \f(CW\*(C`SVs_PADMY\*(C'\fR flag.
+\&\f(CWSvPADMY()\fR now returns a true value for anything not marked \f(CW\*(C`PADTMP\*(C'\fR
+and \f(CW\*(C`SVs_PADMY\*(C'\fR is now defined as 0.
+.IP \(bu 4
+The macros \f(CW\*(C`SETsv\*(C'\fR and \f(CW\*(C`SETsvUN\*(C'\fR have been removed. They were no longer used
+in the core since commit 6f1401dc2a five years ago, and have not been
+found present on CPAN.
+.IP \(bu 4
+The \f(CW\*(C`SvFAKE\*(C'\fR bit (unused on HVs) got informally reserved by
+David Mitchell for future work on vtables.
+.IP \(bu 4
+The \f(CWsv_catpvn_flags()\fR function accepts \f(CW\*(C`SV_CATBYTES\*(C'\fR and \f(CW\*(C`SV_CATUTF8\*(C'\fR
+flags, which specify whether the appended string is bytes or UTF\-8,
+respectively. (These flags have in fact been present since 5.16.0, but
+were formerly not regarded as part of the API.)
+.IP \(bu 4
+A new opcode class, \f(CW\*(C`METHOP\*(C'\fR, has been introduced. It holds
+information used at runtime to improve the performance
+of class/object method calls.
+.Sp
+\&\f(CW\*(C`OP_METHOD\*(C'\fR and \f(CW\*(C`OP_METHOD_NAMED\*(C'\fR have changed from being
+\&\f(CW\*(C`UNOP/SVOP\*(C'\fR to being \f(CW\*(C`METHOP\*(C'\fR.
+.IP \(bu 4
+\&\f(CWcv_name()\fR is a new API function that can be passed a CV or GV.  It
+returns an SV containing the name of the subroutine, for use in
+diagnostics.
+.Sp
+[GH #12767] <https://github.com/Perl/perl5/issues/12767>
+[GH #13392] <https://github.com/Perl/perl5/issues/13392>
+.IP \(bu 4
+\&\f(CWcv_set_call_checker_flags()\fR is a new API function that works like
+\&\f(CWcv_set_call_checker()\fR, except that it allows the caller to specify
+whether the call checker requires a full GV for reporting the subroutine's
+name, or whether it could be passed a CV instead.  Whatever value is
+passed will be acceptable to \f(CWcv_name()\fR.  \f(CWcv_set_call_checker()\fR
+guarantees there will be a GV, but it may have to create one on the fly,
+which is inefficient.
+[GH #12767] <https://github.com/Perl/perl5/issues/12767>
+.IP \(bu 4
+\&\f(CW\*(C`CvGV\*(C'\fR (which is not part of the API) is now a more complex macro, which may
+call a function and reify a GV.  For those cases where it has been used as a
+boolean, \f(CW\*(C`CvHASGV\*(C'\fR has been added, which will return true for CVs that
+notionally have GVs, but without reifying the GV.  \f(CW\*(C`CvGV\*(C'\fR also returns a GV
+now for lexical subs.
+[GH #13392] <https://github.com/Perl/perl5/issues/13392>
+.IP \(bu 4
+The "sync_locale" in perlapi function has been added to the public API.
+Changing the program's locale should be avoided by XS code. Nevertheless,
+certain non-Perl libraries called from XS need to do so, such as \f(CW\*(C`Gtk\*(C'\fR.
+When this happens, Perl needs to be told that the locale has
+changed.  Use this function to do so, before returning to Perl.
+.IP \(bu 4
+The defines and labels for the flags in the \f(CW\*(C`op_private\*(C'\fR field of OPs are now
+auto-generated from data in \fIregen/op_private\fR.  The noticeable effect of this
+is that some of the flag output of \f(CW\*(C`Concise\*(C'\fR might differ slightly, and the
+flag output of \f(CW\*(C`perl\ \-Dx\*(C'\fR may differ considerably (they both use the same set
+of labels now).  Also, debugging builds now have a new assertion in
+\&\f(CWop_free()\fR to ensure that the op doesn't have any unrecognized flags set in
+\&\f(CW\*(C`op_private\*(C'\fR.
+.IP \(bu 4
+The deprecated variable \f(CW\*(C`PL_sv_objcount\*(C'\fR has been removed.
+.IP \(bu 4
+Perl now tries to keep the locale category \f(CW\*(C`LC_NUMERIC\*(C'\fR set to "C"
+except around operations that need it to be set to the program's
+underlying locale.  This protects the many XS modules that cannot cope
+with the decimal radix character not being a dot.  Prior to this
+release, Perl initialized this category to "C", but a call to
+\&\f(CWPOSIX::setlocale()\fR would change it.  Now such a call will change the
+underlying locale of the \f(CW\*(C`LC_NUMERIC\*(C'\fR category for the program, but the
+locale exposed to XS code will remain "C".  There are new macros
+to manipulate the LC_NUMERIC locale, including
+\&\f(CW\*(C`STORE_LC_NUMERIC_SET_TO_NEEDED\*(C'\fR and
+\&\f(CW\*(C`STORE_LC_NUMERIC_FORCE_TO_UNDERLYING\*(C'\fR.
+See "Locale-related functions and macros" in perlapi.
+.IP \(bu 4
+A new macro \f(CW\*(C`isUTF8_CHAR\*(C'\fR has been written which
+efficiently determines if the string given by its parameters begins
+with a well-formed UTF\-8 encoded character.
+.IP \(bu 4
+The following private API functions had their context parameter removed:
+\&\f(CW\*(C`Perl_cast_ulong\*(C'\fR,  \f(CW\*(C`Perl_cast_i32\*(C'\fR, \f(CW\*(C`Perl_cast_iv\*(C'\fR,    \f(CW\*(C`Perl_cast_uv\*(C'\fR,
+\&\f(CW\*(C`Perl_cv_const_sv\*(C'\fR, \f(CW\*(C`Perl_mg_find\*(C'\fR,  \f(CW\*(C`Perl_mg_findext\*(C'\fR, \f(CW\*(C`Perl_mg_magical\*(C'\fR,
+\&\f(CW\*(C`Perl_mini_mktime\*(C'\fR, \f(CW\*(C`Perl_my_dirfd\*(C'\fR, \f(CW\*(C`Perl_sv_backoff\*(C'\fR, \f(CW\*(C`Perl_utf8_hop\*(C'\fR.
+.Sp
+Note that the prefix-less versions of those functions that are part of the
+public API, such as \f(CWcast_i32()\fR, remain unaffected.
+.IP \(bu 4
+The \f(CW\*(C`PADNAME\*(C'\fR and \f(CW\*(C`PADNAMELIST\*(C'\fR types are now separate types, and no
+longer simply aliases for SV and AV.
+[GH #14250] <https://github.com/Perl/perl5/issues/14250>.
+.IP \(bu 4
+Pad names are now always UTF\-8.  The \f(CW\*(C`PadnameUTF8\*(C'\fR macro always returns
+true.  Previously, this was effectively the case already, but any support
+for two different internal representations of pad names has now been
+removed.
+.IP \(bu 4
+A new op class, \f(CW\*(C`UNOP_AUX\*(C'\fR, has been added. This is a subclass of
+\&\f(CW\*(C`UNOP\*(C'\fR with an \f(CW\*(C`op_aux\*(C'\fR field added, which points to an array of unions
+of UV, SV* etc. It is intended for where an op needs to store more data
+than a simple \f(CW\*(C`op_sv\*(C'\fR or whatever. Currently the only op of this type is
+\&\f(CW\*(C`OP_MULTIDEREF\*(C'\fR (see next item).
+.IP \(bu 4
+A new op has been added, \f(CW\*(C`OP_MULTIDEREF\*(C'\fR, which performs one or more
+nested array and hash lookups where the key is a constant or simple
+variable. For example the expression \f(CW\*(C`$a[0]{$k}[$i]\*(C'\fR, which previously
+involved ten \f(CW\*(C`rv2Xv\*(C'\fR, \f(CW\*(C`Xelem\*(C'\fR, \f(CW\*(C`gvsv\*(C'\fR and \f(CW\*(C`const\*(C'\fR ops is now performed
+by a single \f(CW\*(C`multideref\*(C'\fR op. It can also handle \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`exists\*(C'\fR and
+\&\f(CW\*(C`delete\*(C'\fR. A non-simple index expression, such as \f(CW\*(C`[$i+1]\*(C'\fR is still done
+using \f(CW\*(C`aelem\*(C'\fR/\f(CW\*(C`helem\*(C'\fR, and single-level array lookup with a small constant
+index is still done using \f(CW\*(C`aelemfast\*(C'\fR.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\f(CW\*(C`close\*(C'\fR now sets \f(CW$!\fR
+.Sp
+When an I/O error occurs, the fact that there has been an error is recorded
+in the handle.  \f(CW\*(C`close\*(C'\fR returns false for such a handle.  Previously, the
+value of \f(CW$!\fR would be untouched by \f(CW\*(C`close\*(C'\fR, so the common convention of
+writing \f(CW\*(C`close\ $fh\ or\ die\ $!\*(C'\fR did not work reliably.  Now the handle
+records the value of \f(CW$!\fR, too, and \f(CW\*(C`close\*(C'\fR restores it.
+.IP \(bu 4
+\&\f(CW\*(C`no re\*(C'\fR now can turn off everything that \f(CW\*(C`use re\*(C'\fR enables
+.Sp
+Previously, running \f(CW\*(C`no re\*(C'\fR would turn off only a few things. Now it
+can turn off all the enabled things. For example, the only way to
+stop debugging, once enabled, was to exit the enclosing block; that is
+now fixed.
+.IP \(bu 4
+\&\f(CW\*(C`pack("D", $x)\*(C'\fR and \f(CW\*(C`pack("F", $x)\*(C'\fR now zero the padding on x86 long
+double builds.  Under some build options on GCC 4.8 and later, they used
+to either overwrite the zero-initialized padding, or bypass the
+initialized buffer entirely.  This caused \fIop/pack.t\fR to fail.
+[GH #14554] <https://github.com/Perl/perl5/issues/14554>
+.IP \(bu 4
+Extending an array cloned from a parent thread could result in "Modification of
+a read-only value attempted" errors when attempting to modify the new elements.
+[GH #14605] <https://github.com/Perl/perl5/issues/14605>
+.IP \(bu 4
+An assertion failure and subsequent crash with \f(CW\*(C`*x=<y>\*(C'\fR has been fixed.
+[GH #14493] <https://github.com/Perl/perl5/issues/14493>
+.IP \(bu 4
+A possible crashing/looping bug related to compiling lexical subs has been
+fixed.
+[GH #14596] <https://github.com/Perl/perl5/issues/14596>
+.IP \(bu 4
+UTF\-8 now works correctly in function names, in unquoted HERE-document
+terminators, and in variable names used as array indexes.
+[GH #14601] <https://github.com/Perl/perl5/issues/14601>
+.IP \(bu 4
+Repeated global pattern matches in scalar context on large tainted strings were
+exponentially slow depending on the current match position in the string.
+[GH #14238] <https://github.com/Perl/perl5/issues/14238>
+.IP \(bu 4
+Various crashes due to the parser getting confused by syntax errors have been
+fixed.
+[GH #14496] <https://github.com/Perl/perl5/issues/14496>
+[GH #14497] <https://github.com/Perl/perl5/issues/14497>
+[GH #14548] <https://github.com/Perl/perl5/issues/14548>
+[GH #14564] <https://github.com/Perl/perl5/issues/14564>
+.IP \(bu 4
+\&\f(CW\*(C`split\*(C'\fR in the scope of lexical \f(CW$_\fR has been fixed not to fail assertions.
+[GH #14483] <https://github.com/Perl/perl5/issues/14483>
+.IP \(bu 4
+\&\f(CW\*(C`my $x : attr\*(C'\fR syntax inside various list operators no longer fails
+assertions.
+[GH #14500] <https://github.com/Perl/perl5/issues/14500>
+.IP \(bu 4
+An \f(CW\*(C`@\*(C'\fR sign in quotes followed by a non-ASCII digit (which is not a valid
+identifier) would cause the parser to crash, instead of simply trying the
+\&\f(CW\*(C`@\*(C'\fR as literal.  This has been fixed.
+[GH #14553] <https://github.com/Perl/perl5/issues/14553>
+.IP \(bu 4
+\&\f(CW\*(C`*bar::=*foo::=*glob_with_hash\*(C'\fR has been crashing since Perl 5.14, but no
+longer does.
+[GH #14512] <https://github.com/Perl/perl5/issues/14512>
+.IP \(bu 4
+\&\f(CW\*(C`foreach\*(C'\fR in scalar context was not pushing an item on to the stack, resulting
+in bugs.  (\f(CW\*(C`print\ 4,\ scalar\ do\ {\ foreach(@x){}\ }\ +\ 1\*(C'\fR would print 5.)
+It has been fixed to return \f(CW\*(C`undef\*(C'\fR.
+[GH #14569] <https://github.com/Perl/perl5/issues/14569>
+.IP \(bu 4
+Several cases of data used to store environment variable contents in core C
+code being potentially overwritten before being used have been fixed.
+[GH #14476] <https://github.com/Perl/perl5/issues/14476>
+.IP \(bu 4
+Some patterns starting with \f(CW\*(C`/.*..../\*(C'\fR matched against long strings have
+been slow since v5.8, and some of the form \f(CW\*(C`/.*..../i\*(C'\fR have been slow
+since v5.18. They are now all fast again.
+[GH #14475] <https://github.com/Perl/perl5/issues/14475>.
+.IP \(bu 4
+The original visible value of \f(CW$/\fR is now preserved when it is set to
+an invalid value.  Previously if you set \f(CW$/\fR to a reference to an
+array, for example, perl would produce a runtime error and not set
+\&\f(CW\*(C`PL_rs\*(C'\fR, but Perl code that checked \f(CW$/\fR would see the array
+reference.
+[GH #14245] <https://github.com/Perl/perl5/issues/14245>.
+.IP \(bu 4
+In a regular expression pattern, a POSIX class, like \f(CW\*(C`[:ascii:]\*(C'\fR, must
+be inside a bracketed character class, like \f(CW\*(C`qr/[[:ascii:]]/\*(C'\fR.  A
+warning is issued when something looking like a POSIX class is not
+inside a bracketed class.  That warning wasn't getting generated when
+the POSIX class was negated: \f(CW\*(C`[:^ascii:]\*(C'\fR.  This is now fixed.
+.IP \(bu 4
+Perl 5.14.0 introduced a bug whereby \f(CW\*(C`eval\ {\ LABEL:\ }\*(C'\fR would crash.  This
+has been fixed.
+[GH #14438] <https://github.com/Perl/perl5/issues/14438>.
+.IP \(bu 4
+Various crashes due to the parser getting confused by syntax errors have
+been fixed.
+[GH #14421] <https://github.com/Perl/perl5/issues/14421>.
+[GH #14472] <https://github.com/Perl/perl5/issues/14472>.
+[GH #14480] <https://github.com/Perl/perl5/issues/14480>.
+[GH #14447] <https://github.com/Perl/perl5/issues/14447>.
+.IP \(bu 4
+Code like \f(CW\*(C`/$a[/\*(C'\fR used to read the next line of input and treat it as
+though it came immediately after the opening bracket.  Some invalid code
+consequently would parse and run, but some code caused crashes, so this is
+now disallowed.
+[GH #14462] <https://github.com/Perl/perl5/issues/14462>.
+.IP \(bu 4
+Fix argument underflow for \f(CW\*(C`pack\*(C'\fR.
+[GH #14525] <https://github.com/Perl/perl5/issues/14525>.
+.IP \(bu 4
+Fix handling of non-strict \f(CW\*(C`\ex{}\*(C'\fR. Now \f(CW\*(C`\ex{}\*(C'\fR is equivalent to \f(CW\*(C`\ex{0}\*(C'\fR
+instead of faulting.
+.IP \(bu 4
+\&\f(CW\*(C`stat \-t\*(C'\fR is now no longer treated as stackable, just like \f(CW\*(C`\-t stat\*(C'\fR.
+[GH #14499] <https://github.com/Perl/perl5/issues/14499>.
+.IP \(bu 4
+The following no longer causes a SEGV: \f(CW\*(C`qr{x+(y(?0))*}\*(C'\fR.
+.IP \(bu 4
+Fixed infinite loop in parsing backrefs in regexp patterns.
+.IP \(bu 4
+Several minor bug fixes in behavior of Infinity and NaN, including
+warnings when stringifying Infinity-like or NaN-like strings. For example,
+"NaNcy" doesn't numify to NaN anymore.
+.IP \(bu 4
+A bug in regular expression patterns that could lead to segfaults and
+other crashes has been fixed.  This occurred only in patterns compiled
+with \f(CW\*(C`/i\*(C'\fR while taking into account the current POSIX locale (which usually
+means they have to be compiled within the scope of \f(CW\*(C`use\ locale\*(C'\fR),
+and there must be a string of at least 128 consecutive bytes to match.
+[GH #14389] <https://github.com/Perl/perl5/issues/14389>.
+.IP \(bu 4
+\&\f(CW\*(C`s///g\*(C'\fR now works on very long strings (where there are more than 2
+billion iterations) instead of dying with 'Substitution loop'.
+[GH #11742] <https://github.com/Perl/perl5/issues/11742>.
+[GH #14190] <https://github.com/Perl/perl5/issues/14190>.
+.IP \(bu 4
+\&\f(CW\*(C`gmtime\*(C'\fR no longer crashes with not-a-number values.
+[GH #14365] <https://github.com/Perl/perl5/issues/14365>.
+.IP \(bu 4
+\&\f(CW\*(C`\e()\*(C'\fR (a reference to an empty list), and \f(CW\*(C`y///\*(C'\fR with lexical \f(CW$_\fR in
+scope, could both do a bad write past the end of the stack.  They have
+both been fixed to extend the stack first.
+.IP \(bu 4
+\&\f(CWprototype()\fR with no arguments used to read the previous item on the
+stack, so \f(CW\*(C`print\ "foo",\ prototype()\*(C'\fR would print foo's prototype.
+It has been fixed to infer \f(CW$_\fR instead.
+[GH #14376] <https://github.com/Perl/perl5/issues/14376>.
+.IP \(bu 4
+Some cases of lexical state subs declared inside predeclared subs could
+crash, for example when evalling a string including the name of an outer
+variable, but no longer do.
+.IP \(bu 4
+Some cases of nested lexical state subs inside anonymous subs could cause
+\&'Bizarre copy' errors or possibly even crashes.
+.IP \(bu 4
+When trying to emit warnings, perl's default debugger (\fIperl5db.pl\fR) was
+sometimes giving 'Undefined subroutine &DB::db_warn called' instead.  This
+bug, which started to occur in Perl 5.18, has been fixed.
+[GH #14400] <https://github.com/Perl/perl5/issues/14400>.
+.IP \(bu 4
+Certain syntax errors in substitutions, such as \f(CW\*(C`s/${<>{})//\*(C'\fR, would
+crash, and had done so since Perl 5.10.  (In some cases the crash did not
+start happening till 5.16.)  The crash has, of course, been fixed.
+[GH #14391] <https://github.com/Perl/perl5/issues/14391>.
+.IP \(bu 4
+Fix a couple of string grow size calculation overflows; in particular,
+a repeat expression like \f(CW\*(C`33\ x\ ~3\*(C'\fR could cause a large buffer
+overflow since the new output buffer size was not correctly handled by
+\&\f(CWSvGROW()\fR.  An expression like this now properly produces a memory wrap
+panic.
+[GH #14401] <https://github.com/Perl/perl5/issues/14401>.
+.IP \(bu 4
+\&\f(CW\*(C`formline("@...", "a");\*(C'\fR would crash.  The \f(CW\*(C`FF_CHECKNL\*(C'\fR case in
+\&\f(CWpp_formline()\fR didn't set the pointer used to mark the chop position,
+which led to the \f(CW\*(C`FF_MORE\*(C'\fR case crashing with a segmentation fault.
+This has been fixed.
+[GH #14388] <https://github.com/Perl/perl5/issues/14388>.
+.IP \(bu 4
+A possible buffer overrun and crash when parsing a literal pattern during
+regular expression compilation has been fixed.
+[GH #14416] <https://github.com/Perl/perl5/issues/14416>.
+.IP \(bu 4
+\&\f(CWfchmod()\fR and \f(CWfutimes()\fR now set \f(CW$!\fR when they fail due to being
+passed a closed file handle.
+[GH #14073] <https://github.com/Perl/perl5/issues/14073>.
+.IP \(bu 4
+\&\f(CWop_free()\fR and \f(CWscalarvoid()\fR no longer crash due to a stack overflow
+when freeing a deeply recursive op tree.
+[GH #11866] <https://github.com/Perl/perl5/issues/11866>.
+.IP \(bu 4
+In Perl 5.20.0, \f(CW$^N\fR accidentally had the internal UTF\-8 flag turned off
+if accessed from a code block within a regular expression, effectively
+UTF\-8\-encoding the value.  This has been fixed.
+[GH #14211] <https://github.com/Perl/perl5/issues/14211>.
+.IP \(bu 4
+A failed \f(CW\*(C`semctl\*(C'\fR call no longer overwrites existing items on the stack,
+which means that \f(CW\*(C`(semctl(\-1,0,0,0))[0]\*(C'\fR no longer gives an
+"uninitialized" warning.
+.IP \(bu 4
+\&\f(CW\*(C`else{foo()}\*(C'\fR with no space before \f(CW\*(C`foo\*(C'\fR is now better at assigning the
+right line number to that statement.
+[GH #14070] <https://github.com/Perl/perl5/issues/14070>.
+.IP \(bu 4
+Sometimes the assignment in \f(CW\*(C`@array = split\*(C'\fR gets optimised so that \f(CW\*(C`split\*(C'\fR
+itself writes directly to the array.  This caused a bug, preventing this
+assignment from being used in lvalue context.  So
+\&\f(CW\*(C`(@a=split//,"foo")=bar()\*(C'\fR was an error.  (This bug probably goes back to
+Perl 3, when the optimisation was added.) It has now been fixed.
+[GH #14183] <https://github.com/Perl/perl5/issues/14183>.
+.IP \(bu 4
+When an argument list fails the checks specified by a subroutine
+signature (which is still an experimental feature), the resulting error
+messages now give the file and line number of the caller, not of the
+called subroutine.
+[GH #13643] <https://github.com/Perl/perl5/issues/13643>.
+.IP \(bu 4
+The flip-flop operators (\f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR in scalar context) used to maintain
+a separate state for each recursion level (the number of times the
+enclosing sub was called recursively), contrary to the documentation.  Now
+each closure has one internal state for each flip-flop.
+[GH #14110] <https://github.com/Perl/perl5/issues/14110>.
+.IP \(bu 4
+The flip-flop operator (\f(CW\*(C`..\*(C'\fR in scalar context) would return the same
+scalar each time, unless the containing subroutine was called recursively.
+Now it always returns a new scalar.
+[GH #14110] <https://github.com/Perl/perl5/issues/14110>.
+.IP \(bu 4
+\&\f(CW\*(C`use\*(C'\fR, \f(CW\*(C`no\*(C'\fR, statement labels, special blocks (\f(CW\*(C`BEGIN\*(C'\fR) and pod are now
+permitted as the first thing in a \f(CW\*(C`map\*(C'\fR or \f(CW\*(C`grep\*(C'\fR block, the block after
+\&\f(CW\*(C`print\*(C'\fR or \f(CW\*(C`say\*(C'\fR (or other functions) returning a handle, and within
+\&\f(CW\*(C`${...}\*(C'\fR, \f(CW\*(C`@{...}\*(C'\fR, etc.
+[GH #14088] <https://github.com/Perl/perl5/issues/14088>.
+.IP \(bu 4
+The repetition operator \f(CW\*(C`x\*(C'\fR now propagates lvalue context to its left-hand
+argument when used in contexts like \f(CW\*(C`foreach\*(C'\fR.  That allows
+\&\f(CW\*(C`for(($#that_array)x2)\ {\ ...\ }\*(C'\fR to work as expected if the loop modifies
+\&\f(CW$_\fR.
+.IP \(bu 4
+\&\f(CW\*(C`(...) x ...\*(C'\fR in scalar context used to corrupt the stack if one operand
+was an object with "x" overloading, causing erratic behavior.
+[GH #13811] <https://github.com/Perl/perl5/issues/13811>.
+.IP \(bu 4
+Assignment to a lexical scalar is often optimised away; for example in
+\&\f(CW\*(C`my $x; $x = $y + $z\*(C'\fR, the assign operator is optimised away and the add
+operator writes its result directly to \f(CW$x\fR.  Various bugs related to
+this optimisation have been fixed.  Certain operators on the right-hand
+side would sometimes fail to assign the value at all or assign the wrong
+value, or would call STORE twice or not at all on tied variables.  The
+operators affected were \f(CW\*(C`$foo++\*(C'\fR, \f(CW\*(C`$foo\-\-\*(C'\fR, and \f(CW\*(C`\-$foo\*(C'\fR under \f(CW\*(C`use
+integer\*(C'\fR, \f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chr\*(C'\fR and \f(CW\*(C`setpgrp\*(C'\fR.
+.IP \(bu 4
+List assignments were sometimes buggy if the same scalar ended up on both
+sides of the assignment due to use of \f(CW\*(C`tied\*(C'\fR, \f(CW\*(C`values\*(C'\fR or \f(CW\*(C`each\*(C'\fR.  The
+result would be the wrong value getting assigned.
+.IP \(bu 4
+\&\f(CWsetpgrp($nonzero)\fR (with one argument) was accidentally changed in 5.16
+to mean \f(CWsetpgrp(0)\fR.  This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`_\|_SUB_\|_\*(C'\fR could return the wrong value or even corrupt memory under the
+debugger (the \f(CW\*(C`\-d\*(C'\fR switch) and in subs containing \f(CW\*(C`eval $string\*(C'\fR.
+.IP \(bu 4
+When \f(CW\*(C`sub\ ()\ {\ $var\ }\*(C'\fR becomes inlinable, it now returns a different
+scalar each time, just as a non-inlinable sub would, though Perl still
+optimises the copy away in cases where it would make no observable
+difference.
+.IP \(bu 4
+\&\f(CW\*(C`my\ sub\ f\ ()\ {\ $var\ }\*(C'\fR and \f(CW\*(C`sub\ ()\ :\ attr\ {\ $var\ }\*(C'\fR are no longer
+eligible for inlining.  The former would crash; the latter would just
+throw the attributes away.  An exception is made for the little-known
+\&\f(CW\*(C`:method\*(C'\fR attribute, which does nothing much.
+.IP \(bu 4
+Inlining of subs with an empty prototype is now more consistent than
+before. Previously, a sub with multiple statements, of which all but the last
+were optimised away, would be inlinable only if it were an anonymous sub
+containing a string \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`state\*(C'\fR declaration or closing over an
+outer lexical variable (or any anonymous sub under the debugger).  Now any
+sub that gets folded to a single constant after statements have been
+optimised away is eligible for inlining.  This applies to things like \f(CW\*(C`sub
+() { jabber() if DEBUG; 42 }\*(C'\fR.
+.Sp
+Some subroutines with an explicit \f(CW\*(C`return\*(C'\fR were being made inlinable,
+contrary to the documentation,  Now \f(CW\*(C`return\*(C'\fR always prevents inlining.
+.IP \(bu 4
+On some systems, such as VMS, \f(CW\*(C`crypt\*(C'\fR can return a non-ASCII string.  If a
+scalar assigned to had contained a UTF\-8 string previously, then \f(CW\*(C`crypt\*(C'\fR
+would not turn off the UTF\-8 flag, thus corrupting the return value.  This
+would happen with \f(CW\*(C`$lexical\ =\ crypt\ ...\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`crypt\*(C'\fR no longer calls \f(CW\*(C`FETCH\*(C'\fR twice on a tied first argument.
+.IP \(bu 4
+An unterminated here-doc on the last line of a quote-like operator
+(\f(CW\*(C`qq[${ <<END }]\*(C'\fR, \f(CW\*(C`/(?{ <<END })/\*(C'\fR) no longer causes a double free.  It
+started doing so in 5.18.
+.IP \(bu 4
+\&\f(CWindex()\fR and \f(CWrindex()\fR no longer crash when used on strings over 2GB in
+size.
+[GH #13700] <https://github.com/Perl/perl5/issues/13700>.
+.IP \(bu 4
+A small, previously intentional, memory leak in
+\&\f(CW\*(C`PERL_SYS_INIT\*(C'\fR/\f(CW\*(C`PERL_SYS_INIT3\*(C'\fR on Win32 builds was fixed. This might
+affect embedders who repeatedly create and destroy perl engines within
+the same process.
+.IP \(bu 4
+\&\f(CWPOSIX::localeconv()\fR now returns the data for the program's underlying
+locale even when called from outside the scope of \f(CW\*(C`use\ locale\*(C'\fR.
+.IP \(bu 4
+\&\f(CWPOSIX::localeconv()\fR now works properly on platforms which don't have
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR and/or \f(CW\*(C`LC_MONETARY\*(C'\fR, or for which Perl has been compiled
+to disregard either or both of these locale categories.  In such
+circumstances, there are now no entries for the corresponding values in
+the hash returned by \f(CWlocaleconv()\fR.
+.IP \(bu 4
+\&\f(CWPOSIX::localeconv()\fR now marks appropriately the values it returns as
+UTF\-8 or not.  Previously they were always returned as bytes, even if
+they were supposed to be encoded as UTF\-8.
+.IP \(bu 4
+On Microsoft Windows, within the scope of \f(CW\*(C`use\ locale\*(C'\fR, the following
+POSIX character classes gave results for many locales that did not
+conform to the POSIX standard:
+\&\f(CW\*(C`[[:alnum:]]\*(C'\fR,
+\&\f(CW\*(C`[[:alpha:]]\*(C'\fR,
+\&\f(CW\*(C`[[:blank:]]\*(C'\fR,
+\&\f(CW\*(C`[[:digit:]]\*(C'\fR,
+\&\f(CW\*(C`[[:graph:]]\*(C'\fR,
+\&\f(CW\*(C`[[:lower:]]\*(C'\fR,
+\&\f(CW\*(C`[[:print:]]\*(C'\fR,
+\&\f(CW\*(C`[[:punct:]]\*(C'\fR,
+\&\f(CW\*(C`[[:upper:]]\*(C'\fR,
+\&\f(CW\*(C`[[:word:]]\*(C'\fR,
+and
+\&\f(CW\*(C`[[:xdigit:]]\*(C'\fR.
+This was because the underlying Microsoft implementation does not
+follow the standard.  Perl now takes special precautions to correct for
+this.
+.IP \(bu 4
+Many issues have been detected by Coverity <http://www.coverity.com/> and
+fixed.
+.IP \(bu 4
+\&\f(CWsystem()\fR and friends should now work properly on more Android builds.
+.Sp
+Due to an oversight, the value specified through \f(CW\*(C`\-Dtargetsh\*(C'\fR to \fIConfigure\fR
+would end up being ignored by some of the build process.  This caused perls
+cross-compiled for Android to end up with defective versions of \f(CWsystem()\fR,
+\&\f(CWexec()\fR and backticks: the commands would end up looking for \f(CW\*(C`/bin/sh\*(C'\fR
+instead of \f(CW\*(C`/system/bin/sh\*(C'\fR, and so would fail for the vast majority
+of devices, leaving \f(CW$!\fR as \f(CW\*(C`ENOENT\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`qr(...\e(...\e)...)\*(C'\fR,
+\&\f(CW\*(C`qr[...\e[...\e]...]\*(C'\fR,
+and
+\&\f(CW\*(C`qr{...\e{...\e}...}\*(C'\fR
+now work.  Previously it was impossible to escape these three
+left-characters with a backslash within a regular expression pattern
+where otherwise they would be considered metacharacters, and the pattern
+opening delimiter was the character, and the closing delimiter was its
+mirror character.
+.IP \(bu 4
+\&\f(CW\*(C`s///e\*(C'\fR on tainted UTF\-8 strings corrupted \f(CWpos()\fR. This bug,
+introduced in 5.20, is now fixed.
+[GH #13948] <https://github.com/Perl/perl5/issues/13948>.
+.IP \(bu 4
+A non-word boundary in a regular expression (\f(CW\*(C`\eB\*(C'\fR) did not always
+match the end of the string; in particular \f(CW\*(C`q{} =~ /\eB/\*(C'\fR did not
+match. This bug, introduced in perl 5.14, is now fixed.
+[GH #13917] <https://github.com/Perl/perl5/issues/13917>.
+.IP \(bu 4
+\&\f(CW\*(C`" P" =~ /(?=.*P)P/\*(C'\fR should match, but did not. This is now fixed.
+[GH #13954] <https://github.com/Perl/perl5/issues/13954>.
+.IP \(bu 4
+Failing to compile \f(CW\*(C`use Foo\*(C'\fR in an \f(CW\*(C`eval\*(C'\fR could leave a spurious
+\&\f(CW\*(C`BEGIN\*(C'\fR subroutine definition, which would produce a "Subroutine
+BEGIN redefined" warning on the next use of \f(CW\*(C`use\*(C'\fR, or other \f(CW\*(C`BEGIN\*(C'\fR
+block.
+[GH #13926] <https://github.com/Perl/perl5/issues/13926>.
+.IP \(bu 4
+\&\f(CW\*(C`method { BLOCK } ARGS\*(C'\fR syntax now correctly parses the arguments if they
+begin with an opening brace.
+[GH #9085] <https://github.com/Perl/perl5/issues/9085>.
+.IP \(bu 4
+External libraries and Perl may have different ideas of what the locale is.
+This is problematic when parsing version strings if the locale's numeric
+separator has been changed.  Version parsing has been patched to ensure
+it handles the locales correctly.
+[GH #13863] <https://github.com/Perl/perl5/issues/13863>.
+.IP \(bu 4
+A bug has been fixed where zero-length assertions and code blocks inside of a
+regex could cause \f(CW\*(C`pos\*(C'\fR to see an incorrect value.
+[GH #14016] <https://github.com/Perl/perl5/issues/14016>.
+.IP \(bu 4
+Dereferencing of constants now works correctly for typeglob constants.  Previously
+the glob was stringified and its name looked up.  Now the glob itself is used.
+[GH #9891] <https://github.com/Perl/perl5/issues/9891>
+.IP \(bu 4
+When parsing a sigil (\f(CW\*(C`$\*(C'\fR \f(CW\*(C`@\*(C'\fR \f(CW\*(C`%\*(C'\fR \f(CW\*(C`&)\*(C'\fR followed by braces,
+the parser no
+longer tries to guess whether it is a block or a hash constructor (causing a
+syntax error when it guesses the latter), since it can only be a block.
+.IP \(bu 4
+\&\f(CW\*(C`undef\ $reference\*(C'\fR now frees the referent immediately, instead of hanging on
+to it until the next statement.
+[GH #14032] <https://github.com/Perl/perl5/issues/14032>
+.IP \(bu 4
+Various cases where the name of a sub is used (autoload, overloading, error
+messages) used to crash for lexical subs, but have been fixed.
+.IP \(bu 4
+Bareword lookup now tries to avoid vivifying packages if it turns out the
+bareword is not going to be a subroutine name.
+.IP \(bu 4
+Compilation of anonymous constants (\fIe.g.\fR, \f(CW\*(C`sub () { 3 }\*(C'\fR) no longer deletes
+any subroutine named \f(CW\*(C`_\|_ANON_\|_\*(C'\fR in the current package.  Not only was
+\&\f(CW\*(C`*_\|_ANON_\|_{CODE}\*(C'\fR cleared, but there was a memory leak, too.  This bug goes
+back to Perl 5.8.0.
+.IP \(bu 4
+Stub declarations like \f(CW\*(C`sub f;\*(C'\fR and \f(CW\*(C`sub f ();\*(C'\fR no longer wipe out constants
+of the same name declared by \f(CW\*(C`use constant\*(C'\fR.  This bug was introduced in Perl
+5.10.0.
+.IP \(bu 4
+\&\f(CW\*(C`qr/[\eN{named sequence}]/\*(C'\fR now works properly in many instances.
+.Sp
+Some names
+known to \f(CW\*(C`\eN{...}\*(C'\fR refer to a sequence of multiple characters, instead of the
+usual single character.  Bracketed character classes generally only match
+single characters, but now special handling has been added so that they can
+match named sequences, but not if the class is inverted or the sequence is
+specified as the beginning or end of a range.  In these cases, the only
+behavior change from before is a slight rewording of the fatal error message
+given when this class is part of a \f(CW\*(C`?[...])\*(C'\fR construct.  When the \f(CW\*(C`[...]\*(C'\fR
+stands alone, the same non-fatal warning as before is raised, and only the
+first character in the sequence is used, again just as before.
+.IP \(bu 4
+Tainted constants evaluated at compile time no longer cause unrelated
+statements to become tainted.
+[GH #14059] <https://github.com/Perl/perl5/issues/14059>
+.IP \(bu 4
+\&\f(CW\*(C`open\ $$fh,\ ...\*(C'\fR, which vivifies a handle with a name like
+\&\f(CW"main::_GEN_0"\fR, was not giving the handle the right reference count, so
+a double free could happen.
+.IP \(bu 4
+When deciding that a bareword was a method name, the parser would get confused
+if an \f(CW\*(C`our\*(C'\fR sub with the same name existed, and look up the method in the
+package of the \f(CW\*(C`our\*(C'\fR sub, instead of the package of the invocant.
+.IP \(bu 4
+The parser no longer gets confused by \f(CW\*(C`\eU=\*(C'\fR within a double-quoted string.  It
+used to produce a syntax error, but now compiles it correctly.
+[GH #10882] <https://github.com/Perl/perl5/issues/10882>
+.IP \(bu 4
+It has always been the intention for the \f(CW\*(C`\-B\*(C'\fR and \f(CW\*(C`\-T\*(C'\fR file test operators to
+treat UTF\-8 encoded files as text.  (perlfunc has
+been updated to say this.)  Previously, it was possible for some files to be
+considered UTF\-8 that actually weren't valid UTF\-8.  This is now fixed.  The
+operators now work on EBCDIC platforms as well.
+.IP \(bu 4
+Under some conditions warning messages raised during regular expression pattern
+compilation were being output more than once.  This has now been fixed.
+.IP \(bu 4
+Perl 5.20.0 introduced a regression in which a UTF\-8 encoded regular
+expression pattern that contains a single ASCII lowercase letter did not
+match its uppercase counterpart. That has been fixed in both 5.20.1 and
+5.22.0.
+[GH #14051] <https://github.com/Perl/perl5/issues/14051>
+.IP \(bu 4
+Constant folding could incorrectly suppress warnings if lexical warnings
+(\f(CW\*(C`use warnings\*(C'\fR or \f(CW\*(C`no warnings\*(C'\fR) were not in effect and \f(CW$^W\fR were
+false at compile time and true at run time.
+.IP \(bu 4
+Loading Unicode tables during a regular expression match could cause assertion
+failures under debugging builds if the previous match used the very same
+regular expression.
+[GH #14081] <https://github.com/Perl/perl5/issues/14081>
+.IP \(bu 4
+Thread cloning used to work incorrectly for lexical subs, possibly causing
+crashes or double frees on exit.
+.IP \(bu 4
+Since Perl 5.14.0, deleting \f(CW$SomePackage::{_\|_ANON_\|_}\fR and then undefining an
+anonymous subroutine could corrupt things internally, resulting in
+Devel::Peek crashing or B.pm giving nonsensical data.  This has been
+fixed.
+.IP \(bu 4
+\&\f(CW\*(C`(caller\ $n)[3]\*(C'\fR now reports names of lexical subs, instead of
+treating them as \f(CW"(unknown)"\fR.
+.IP \(bu 4
+\&\f(CW\*(C`sort subname LIST\*(C'\fR now supports using a lexical sub as the comparison
+routine.
+.IP \(bu 4
+Aliasing (\fIe.g.\fR, via \f(CW\*(C`*x\ =\ *y\*(C'\fR) could confuse list assignments that mention the
+two names for the same variable on either side, causing wrong values to be
+assigned.
+[GH #5788] <https://github.com/Perl/perl5/issues/5788>
+.IP \(bu 4
+Long here-doc terminators could cause a bad read on short lines of input.  This
+has been fixed.  It is doubtful that any crash could have occurred.  This bug
+goes back to when here-docs were introduced in Perl 3.000 twenty-five years
+ago.
+.IP \(bu 4
+An optimization in \f(CW\*(C`split\*(C'\fR to treat \f(CW\*(C`split\ /^/\*(C'\fR like \f(CW\*(C`split\ /^/m\*(C'\fR had the
+unfortunate side-effect of also treating \f(CW\*(C`split\ /\eA/\*(C'\fR like \f(CW\*(C`split\ /^/m\*(C'\fR,
+which it should not.  This has been fixed.  (Note, however, that \f(CW\*(C`split\ /^x/\*(C'\fR
+does not behave like \f(CW\*(C`split\ /^x/m\*(C'\fR, which is also considered to be a bug and
+will be fixed in a future version.)
+[GH #14086] <https://github.com/Perl/perl5/issues/14086>
+.IP \(bu 4
+The little-known \f(CW\*(C`my\ Class\ $var\*(C'\fR syntax (see fields and attributes)
+could get confused in the scope of \f(CW\*(C`use utf8\*(C'\fR if \f(CW\*(C`Class\*(C'\fR were a constant
+whose value contained Latin\-1 characters.
+.IP \(bu 4
+Locking and unlocking values via Hash::Util or \f(CW\*(C`Internals::SvREADONLY\*(C'\fR
+no longer has any effect on values that were read-only to begin with.
+Previously, unlocking such values could result in crashes, hangs or
+other erratic behavior.
+.IP \(bu 4
+Some unterminated \f(CW\*(C`(?(...)...)\*(C'\fR constructs in regular expressions would
+either crash or give erroneous error messages.  \f(CW\*(C`/(?(1)/\*(C'\fR is one such
+example.
+.IP \(bu 4
+\&\f(CW\*(C`pack\ "w",\ $tied\*(C'\fR no longer calls FETCH twice.
+.IP \(bu 4
+List assignments like \f(CW\*(C`($x,\ $z)\ =\ (1,\ $y)\*(C'\fR now work correctly if \f(CW$x\fR and
+\&\f(CW$y\fR have been aliased by \f(CW\*(C`foreach\*(C'\fR.
+.IP \(bu 4
+Some patterns including code blocks with syntax errors, such as
+\&\f(CW\*(C`/\ (?{(^{})/\*(C'\fR, would hang or fail assertions on debugging builds.  Now
+they produce errors.
+.IP \(bu 4
+An assertion failure when parsing \f(CW\*(C`sort\*(C'\fR with debugging enabled has been
+fixed.
+[GH #14087] <https://github.com/Perl/perl5/issues/14087>.
+.IP \(bu 4
+\&\f(CW\*(C`*a\ =\ *b;\ @a\ =\ split\ //,\ $b[1]\*(C'\fR could do a bad read and produce junk
+results.
+.IP \(bu 4
+In \f(CW\*(C`()\ =\ @array\ =\ split\*(C'\fR, the \f(CW\*(C`()\ =\*(C'\fR at the beginning no longer confuses
+the optimizer into assuming a limit of 1.
+.IP \(bu 4
+Fatal warnings no longer prevent the output of syntax errors.
+[GH #14155] <https://github.com/Perl/perl5/issues/14155>.
+.IP \(bu 4
+Fixed a NaN double-to-long-double conversion error on VMS. For quiet NaNs
+(and only on Itanium, not Alpha) negative infinity instead of NaN was
+produced.
+.IP \(bu 4
+Fixed the issue that caused \f(CW\*(C`make distclean\*(C'\fR to incorrectly leave some
+files behind.
+[GH #14108] <https://github.com/Perl/perl5/issues/14108>.
+.IP \(bu 4
+AIX now sets the length in \f(CW\*(C`getsockopt\*(C'\fR correctly.
+[GH #13484] <https://github.com/Perl/perl5/issues/13484>.
+[cpan #91183] <https://rt.cpan.org/Ticket/Display.html?id=91183>.
+[cpan #85570] <https://rt.cpan.org/Ticket/Display.html?id=85570>.
+.IP \(bu 4
+The optimization phase of a regexp compilation could run "forever" and
+exhaust all memory under certain circumstances; now fixed.
+[GH #13984] <https://github.com/Perl/perl5/issues/13984>.
+.IP \(bu 4
+The test script \fIt/op/crypt.t\fR now uses the SHA\-256 algorithm if the
+default one is disabled, rather than giving failures.
+[GH #13715] <https://github.com/Perl/perl5/issues/13715>.
+.IP \(bu 4
+Fixed an off-by-one error when setting the size of a shared array.
+[GH #14151] <https://github.com/Perl/perl5/issues/14151>.
+.IP \(bu 4
+Fixed a bug that could cause perl to enter an infinite loop during
+compilation. In particular, a \f(CWwhile(1)\fR within a sublist, \fIe.g.\fR
+.Sp
+.Vb 1
+\&    sub foo { () = ($a, my $b, ($c, do { while(1) {} })) }
+.Ve
+.Sp
+The bug was introduced in 5.20.0
+[GH #14165] <https://github.com/Perl/perl5/issues/14165>.
+.IP \(bu 4
+On Win32, if a variable was \f(CW\*(C`local\*(C'\fR\-ized in a pseudo-process that later
+forked, restoring the original value in the child pseudo-process caused
+memory corruption and a crash in the child pseudo-process (and therefore the
+OS process).
+[GH #8641] <https://github.com/Perl/perl5/issues/8641>.
+.IP \(bu 4
+Calling \f(CW\*(C`write\*(C'\fR on a format with a \f(CW\*(C`^**\*(C'\fR field could produce a panic
+in \f(CWsv_chop()\fR if there were insufficient arguments or if the variable
+used to fill the field was empty.
+[GH #14255] <https://github.com/Perl/perl5/issues/14255>.
+.IP \(bu 4
+Non-ASCII lexical sub names now appear without trailing junk when they
+appear in error messages.
+.IP \(bu 4
+The \f(CW\*(C`\e@\*(C'\fR subroutine prototype no longer flattens parenthesized arrays
+(taking a reference to each element), but takes a reference to the array
+itself.
+[GH #9111] <https://github.com/Perl/perl5/issues/9111>.
+.IP \(bu 4
+A block containing nothing except a C\-style \f(CW\*(C`for\*(C'\fR loop could corrupt the
+stack, causing lists outside the block to lose elements or have elements
+overwritten.  This could happen with \f(CW\*(C`map { for(...){...} } ...\*(C'\fR and with
+lists containing \f(CW\*(C`do { for(...){...} }\*(C'\fR.
+[GH #14269] <https://github.com/Perl/perl5/issues/14269>.
+.IP \(bu 4
+\&\f(CWscalar()\fR now propagates lvalue context, so that
+\&\f(CW\*(C`for(scalar($#foo))\ {\ ...\ }\*(C'\fR can modify \f(CW$#foo\fR through \f(CW$_\fR.
+.IP \(bu 4
+\&\f(CW\*(C`qr/@array(?{block})/\*(C'\fR no longer dies with "Bizarre copy of ARRAY".
+[GH #14292] <https://github.com/Perl/perl5/issues/14292>.
+.IP \(bu 4
+\&\f(CW\*(C`eval\ \*(Aq$variable\*(Aq\*(C'\fR in nested named subroutines would sometimes look up a
+global variable even with a lexical variable in scope.
+.IP \(bu 4
+In perl 5.20.0, \f(CW\*(C`sort CORE::fake\*(C'\fR where 'fake' is anything other than a
+keyword, started chopping off the last 6 characters and treating the result
+as a sort sub name.  The previous behavior of treating \f(CW\*(C`CORE::fake\*(C'\fR as a
+sort sub name has been restored.
+[GH #14323] <https://github.com/Perl/perl5/issues/14323>.
+.IP \(bu 4
+Outside of \f(CW\*(C`use utf8\*(C'\fR, a single-character Latin\-1 lexical variable is
+disallowed.  The error message for it, "Can't use global \f(CW$foo\fR...", was
+giving garbage instead of the variable name.
+.IP \(bu 4
+\&\f(CW\*(C`readline\*(C'\fR on a nonexistent handle was causing \f(CW\*(C`${^LAST_FH}\*(C'\fR to produce a
+reference to an undefined scalar (or fail an assertion).  Now
+\&\f(CW\*(C`${^LAST_FH}\*(C'\fR ends up undefined.
+.IP \(bu 4
+\&\f(CW\*(C`(...) x ...\*(C'\fR in void context now applies scalar context to the left-hand
+argument, instead of the context the current sub was called in.
+[GH #14174] <https://github.com/Perl/perl5/issues/14174>.
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+\&\f(CW\*(C`pack\*(C'\fR\-ing a NaN on a perl compiled with Visual C 6 does not behave properly,
+leading to a test failure in \fIt/op/infnan.t\fR.
+[GH #14705] <https://github.com/Perl/perl5/issues/14705>
+.IP \(bu 4
+A goal is for Perl to be able to be recompiled to work reasonably well on any
+Unicode version.  In Perl 5.22, though, the earliest such version is Unicode
+5.1 (current is 7.0).
+.IP \(bu 4
+EBCDIC platforms
+.RS 4
+.IP \(bu 4
+The \f(CW\*(C`cmp\*(C'\fR (and hence \f(CW\*(C`sort\*(C'\fR) operators do not necessarily give the
+correct results when both operands are UTF-EBCDIC encoded strings and
+there is a mixture of ASCII and/or control characters, along with other
+characters.
+.IP \(bu 4
+Ranges containing \f(CW\*(C`\eN{...}\*(C'\fR in the \f(CW\*(C`tr///\*(C'\fR (and \f(CW\*(C`y///\*(C'\fR)
+transliteration operators are treated differently than the equivalent
+ranges in regular expression patterns.  They should, but don't, cause
+the values in the ranges to all be treated as Unicode code points, and
+not native ones.  ("Version 8 Regular Expressions" in perlre gives
+details as to how it should work.)
+.IP \(bu 4
+Encode and encoding are mostly broken.
+.IP \(bu 4
+Many CPAN modules that are shipped with core show failing tests.
+.IP \(bu 4
+\&\f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR with \f(CW"U0"\fR format may not work properly.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+The following modules are known to have test failures with this version of
+Perl.  In many cases, patches have been submitted, so there will hopefully be
+new releases soon:
+.RS 4
+.IP \(bu 4
+B::Generate version 1.50
+.IP \(bu 4
+B::Utils version 0.25
+.IP \(bu 4
+Coro version 6.42
+.IP \(bu 4
+Dancer version 1.3130
+.IP \(bu 4
+Data::Alias version 1.18
+.IP \(bu 4
+Data::Dump::Streamer version 2.38
+.IP \(bu 4
+Data::Util version 0.63
+.IP \(bu 4
+Devel::Spy version 0.07
+.IP \(bu 4
+invoker version 0.34
+.IP \(bu 4
+Lexical::Var version 0.009
+.IP \(bu 4
+LWP::ConsoleLogger version 0.000018
+.IP \(bu 4
+Mason version 2.22
+.IP \(bu 4
+NgxQueue version 0.02
+.IP \(bu 4
+Padre version 1.00
+.IP \(bu 4
+Parse::Keyword 0.08
+.RE
+.RS 4
+.RE
+.SH Obituary
+.IX Header "Obituary"
+Brian McCauley died on May 8, 2015.  He was a frequent poster to Usenet, Perl
+Monks, and other Perl forums, and made several CPAN contributions under the
+nick NOBULL, including to the Perl FAQ.  He attended almost every
+YAPC::Europe, and indeed, helped organise YAPC::Europe 2006 and the QA
+Hackathon 2009.  His wit and his delight in intricate systems were
+particularly apparent in his love of board games; many Perl mongers will
+have fond memories of playing Fluxx and other games with Brian.  He will be
+missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.22.0 represents approximately 12 months of development since Perl 5.20.0
+and contains approximately 590,000 lines of changes across 2,400 files from 94
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 370,000 lines of changes to 1,500 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.22.0:
+.PP
+Aaron Crane, Abhijit Menon-Sen, Abigail, Alberto Simões, Alex Solovey, Alex
+Vandiver, Alexandr Ciornii, Alexandre (Midnite) Jousset, Andreas König,
+Andreas Voegele, Andrew Fresh, Andy Dougherty, Anthony Heading, Aristotle
+Pagaltzis, brian d foy, Brian Fraser, Chad Granum, Chris 'BinGOs' Williams,
+Craig A. Berry, Dagfinn Ilmari Mannsåker, Daniel Dragan, Darin McBride, Dave
+Rolsky, David Golden, David Mitchell, David Wheeler, Dmitri Tikhonov, Doug
+Bell, E. Choroba, Ed J, Eric Herman, Father Chrysostomos, George Greer, Glenn
+D. Golden, Graham Knop, H.Merijn Brand, Herbert Breunung, Hugo van der Sanden,
+James E Keenan, James McCoy, James Raspass, Jan Dubois, Jarkko Hietaniemi,
+Jasmine Ngan, Jerry D. Hedden, Jim Cromie, John Goodyear, kafka, Karen
+Etheridge, Karl Williamson, Kent Fredric, kmx, Lajos Veres, Leon Timmermans,
+Lukas Mai, Mathieu Arnold, Matthew Horsfall, Max Maischein, Michael Bunk,
+Nicholas Clark, Niels Thykier, Niko Tyni, Norman Koch, Olivier Mengué, Peter
+John Acklam, Peter Martini, Petr Písař, Philippe Bruhat (BooK), Pierre
+Bogossian, Rafael Garcia-Suarez, Randy Stauner, Reini Urban, Ricardo Signes,
+Rob Hoelz, Rostislav Skudnov, Sawyer X, Shirakata Kentaro, Shlomi Fish,
+Sisyphus, Slaven Rezic, Smylers, Steffen Müller, Steve Hay, Sullivan Beck,
+syber, Tadeusz Sośnierz, Thomas Sibley, Todd Rinaldo, Tony Cook, Vincent Pit,
+Vladimir Marek, Yaroslav Kuzmin, Yves Orton, Ævar Arnfjörð Bjarmason.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+<https://rt.perl.org/>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5221delta.1 b/upstream/mageia-cauldron/man1/perl5221delta.1
new file mode 100644
index 00000000..19a233c6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5221delta.1
@@ -0,0 +1,305 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5221DELTA 1"
+.TH PERL5221DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5221delta \- what is new for perl v5.22.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.22.0 release and the 5.22.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.20.0, first read
+perl5220delta, which describes differences between 5.20.0 and 5.22.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.20.0 other than the
+following single exception, which we deemed to be a sensible change to make in
+order to get the new \f(CW\*(C`\eb{wb}\*(C'\fR and (in particular) \f(CW\*(C`\eb{sb}\*(C'\fR features sane
+before people decided they're worthless because of bugs in their Perl 5.22.0
+implementation and avoided them in the future.
+If any others exist, they are bugs, and we request that you submit a report.
+See "Reporting Bugs" below.
+.SS "Bounds Checking Constructs"
+.IX Subsection "Bounds Checking Constructs"
+Several bugs, including a segmentation fault, have been fixed with the bounds
+checking constructs (introduced in Perl 5.22) \f(CW\*(C`\eb{gcb}\*(C'\fR, \f(CW\*(C`\eb{sb}\*(C'\fR, \f(CW\*(C`\eb{wb}\*(C'\fR,
+\&\f(CW\*(C`\eB{gcb}\*(C'\fR, \f(CW\*(C`\eB{sb}\*(C'\fR, and \f(CW\*(C`\eB{wb}\*(C'\fR.  All the \f(CW\*(C`\eB{}\*(C'\fR ones now match an empty
+string; none of the \f(CW\*(C`\eb{}\*(C'\fR ones do.
+[GH #14976] <https://github.com/Perl/perl5/issues/14976>
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20150520 to 5.20151213.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.22 to 0.23.
+.IP \(bu 4
+POSIX has been upgraded from version 1.53 to 1.53_01.
+.Sp
+If \f(CW\*(C`POSIX::strerror\*(C'\fR was passed \f(CW$!\fR as its argument then it accidentally
+cleared \f(CW$!\fR.  This has been fixed.
+[GH #14951] <https://github.com/Perl/perl5/issues/14951>
+.IP \(bu 4
+Storable has been upgraded from version 2.53 to 2.53_01.
+.IP \(bu 4
+warnings has been upgraded from version 1.32 to 1.34.
+.Sp
+The \f(CW\*(C`warnings::enabled\*(C'\fR example now actually uses \f(CW\*(C`warnings::enabled\*(C'\fR.
+[GH #14905] <https://github.com/Perl/perl5/issues/14905>
+.IP \(bu 4
+Win32 has been upgraded from version 0.51 to 0.52.
+.Sp
+This has been updated for Windows 8.1, 10 and 2012 R2 Server.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperltie\fR
+.IX Subsection "perltie"
+.IP \(bu 4
+The usage of \f(CW\*(C`FIRSTKEY\*(C'\fR and \f(CW\*(C`NEXTKEY\*(C'\fR has been clarified.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+The specific true value of \f(CW$!{E...}\fR is now documented, noting that it is
+subject to change and not guaranteed.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+The \f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR builtins are now more careful about the warnings
+they emit: argument reordering now disables the "redundant argument" warning in
+all cases.
+[GH #14772] <https://github.com/Perl/perl5/issues/14772>
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Using the \f(CW\*(C`NO_HASH_SEED\*(C'\fR define in combination with the default hash algorithm
+\&\f(CW\*(C`PERL_HASH_FUNC_ONE_AT_A_TIME_HARD\*(C'\fR resulted in a fatal error while compiling
+the interpreter, since Perl 5.17.10.  This has been fixed.
+.IP \(bu 4
+Configuring with ccflags containing quotes (e.g.
+\&\f(CW\*(C`\-Accflags=\*(Aq\-DAPPLLIB_EXP=\e"/usr/libperl\e"\*(Aq\*(C'\fR) was broken in Perl 5.22.0
+but has now been fixed again.
+[GH #14732] <https://github.com/Perl/perl5/issues/14732>
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP IRIX 4
+.IX Item "IRIX"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Under some circumstances IRIX stdio \fBfgetc()\fR and \fBfread()\fR set the errno to
+\&\f(CW\*(C`ENOENT\*(C'\fR, which made no sense according to either IRIX or POSIX docs.  Errno
+is now cleared in such cases.
+[GH #14557] <https://github.com/Perl/perl5/issues/14557>
+.IP \(bu 4
+Problems when multiplying long doubles by infinity have been fixed.
+[GH #14993] <https://github.com/Perl/perl5/issues/14993>
+.IP \(bu 4
+All tests pass now on IRIX with the default build configuration.
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\f(CW\*(C`qr/(?[ () ])/\*(C'\fR no longer segfaults, giving a syntax error message instead.
+[GH #14851] <https://github.com/Perl/perl5/issues/14851>
+.IP \(bu 4
+Regular expression possessive quantifier Perl 5.20 regression now fixed.
+\&\f(CW\*(C`qr/\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`}+\*(C'\fR\f(CW\*(C`/\*(C'\fR is supposed to behave identically to
+\&\f(CW\*(C`qr/(?>\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`})/\*(C'\fR.  Since Perl 5.20, this didn't work
+if \fImin\fR and \fImax\fR were equal.
+[GH #14857] <https://github.com/Perl/perl5/issues/14857>
+.IP \(bu 4
+Certain syntax errors in
+"Extended Bracketed Character Classes" in perlrecharclass caused panics instead
+of the proper error message.  This has now been fixed.
+[GH #15016] <https://github.com/Perl/perl5/issues/15016>
+.IP \(bu 4
+\&\f(CW\*(C`BEGIN <>\*(C'\fR no longer segfaults and properly produces an error message.
+[GH #13546] <https://github.com/Perl/perl5/issues/13546>
+.IP \(bu 4
+A regression from Perl 5.20 has been fixed, in which some syntax errors in
+\&\f(CW\*(C`(?[...])\*(C'\fR constructs
+within regular expression patterns could cause a segfault instead of a proper
+error message.
+[GH #14933] <https://github.com/Perl/perl5/issues/14933>
+.IP \(bu 4
+Another problem with
+\&\f(CW\*(C`(?[...])\*(C'\fR
+constructs has been fixed wherein things like \f(CW\*(C`\ec]\*(C'\fR could cause panics.
+[GH #14934] <https://github.com/Perl/perl5/issues/14934>
+.IP \(bu 4
+In Perl 5.22.0, the logic changed when parsing a numeric parameter to the \-C
+option, such that the successfully parsed number was not saved as the option
+value if it parsed to the end of the argument.
+[GH #14748] <https://github.com/Perl/perl5/issues/14748>
+.IP \(bu 4
+Warning fatality is now ignored when rewinding the stack.  This prevents
+infinite recursion when the now fatal error also causes rewinding of the stack.
+[GH #14319] <https://github.com/Perl/perl5/issues/14319>
+.IP \(bu 4
+A crash with \f(CW\*(C`%::=(); J\->${\e"::"}\*(C'\fR has been fixed.
+[GH #14790] <https://github.com/Perl/perl5/issues/14790>
+.IP \(bu 4
+Nested quantifiers such as \f(CW\*(C`/.{1}??/\*(C'\fR should cause perl to throw a fatal
+error, but were being silently accepted since Perl 5.20.0.  This has been
+fixed.
+[GH #14960] <https://github.com/Perl/perl5/issues/14960>
+.IP \(bu 4
+Regular expression sequences such as \f(CW\*(C`/(?i/\*(C'\fR (and similarly with other
+recognized flags or combination of flags) should cause perl to throw a fatal
+error, but were being silently accepted since Perl 5.18.0.  This has been
+fixed.
+[GH #14931] <https://github.com/Perl/perl5/issues/14931>
+.IP \(bu 4
+A bug in hexadecimal floating point literal support meant that high-order bits
+could be lost in cases where mantissa overflow was caused by too many trailing
+zeros in the fractional part.  This has been fixed.
+[GH #15032] <https://github.com/Perl/perl5/issues/15032>
+.IP \(bu 4
+Another hexadecimal floating point bug, causing low-order bits to be lost in
+cases where the last hexadecimal digit of the mantissa has bits straddling the
+limit of the number of bits allowed for the mantissa, has also been fixed.
+[GH #15033] <https://github.com/Perl/perl5/issues/15033>
+.IP \(bu 4
+Further hexadecimal floating point bugs have been fixed: In some circumstances,
+the \f(CW%a\fR format specifier could variously lose the sign of the negative zero,
+fail to display zeros after the radix point with the requested precision, or
+even lose the radix point after the leftmost hexadecimal digit completely.
+.IP \(bu 4
+A crash caused by incomplete expressions within \f(CW\*(C`/(?[ ])/\*(C'\fR (e.g.
+\&\f(CW\*(C`/(?[[0]+()+])/\*(C'\fR) has been fixed.
+[GH #15045] <https://github.com/Perl/perl5/issues/15045>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.22.1 represents approximately 6 months of development since Perl 5.22.0
+and contains approximately 19,000 lines of changes across 130 files from 27
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,700 lines of changes to 44 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.22.1:
+.PP
+Aaron Crane, Abigail, Andy Broad, Aristotle Pagaltzis, Chase Whitener, Chris
+\&'BinGOs' Williams, Craig A. Berry, Daniel Dragan, David Mitchell, Father
+Chrysostomos, Herbert Breunung, Hugo van der Sanden, James E Keenan, Jan
+Dubois, Jarkko Hietaniemi, Karen Etheridge, Karl Williamson, Lukas Mai, Matthew
+Horsfall, Peter Martini, Rafael Garcia-Suarez, Ricardo Signes, Shlomi Fish,
+Sisyphus, Steve Hay, Tony Cook, Victor Adam.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5222delta.1 b/upstream/mageia-cauldron/man1/perl5222delta.1
new file mode 100644
index 00000000..f45dc4ff
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5222delta.1
@@ -0,0 +1,354 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5222DELTA 1"
+.TH PERL5222DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5222delta \- what is new for perl v5.22.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.22.1 release and the 5.22.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.22.0, first read
+perl5221delta, which describes differences between 5.22.0 and 5.22.1.
+.SH Security
+.IX Header "Security"
+.SS "Fix out of boundary access in Win32 path handling"
+.IX Subsection "Fix out of boundary access in Win32 path handling"
+This is CVE\-2015\-8608.  For more information see
+[GH #15067] <https://github.com/Perl/perl5/issues/15067>.
+.ie n .SS "Fix loss of taint in canonpath()"
+.el .SS "Fix loss of taint in \f(CWcanonpath()\fP"
+.IX Subsection "Fix loss of taint in canonpath()"
+This is CVE\-2015\-8607.  For more information see
+[GH #15084] <https://github.com/Perl/perl5/issues/15084>.
+.ie n .SS "Set proper umask before calling mkstemp(3)"
+.el .SS "Set proper umask before calling \f(CWmkstemp(3)\fP"
+.IX Subsection "Set proper umask before calling mkstemp(3)"
+In 5.22.0 perl started setting umask to \f(CW0600\fR before calling \f(CWmkstemp(3)\fR
+and restoring it afterwards.  This wrongfully tells \f(CWopen(2)\fR to strip the
+owner read and write bits from the given mode before applying it, rather than
+the intended negation of leaving only those bits in place.
+.PP
+Systems that use mode \f(CW0666\fR in \f(CWmkstemp(3)\fR (like old versions of glibc)
+create a file with permissions \f(CW0066\fR, leaving world read and write permissions
+regardless of current umask.
+.PP
+This has been fixed by using umask \f(CW0177\fR instead.
+.PP
+[GH #15135] <https://github.com/Perl/perl5/issues/15135>
+.ie n .SS "Avoid accessing uninitialized memory in Win32 crypt()"
+.el .SS "Avoid accessing uninitialized memory in Win32 \f(CWcrypt()\fP"
+.IX Subsection "Avoid accessing uninitialized memory in Win32 crypt()"
+Validation that will detect both a short salt and invalid characters in the
+salt has been added.
+.PP
+[GH #15091] <https://github.com/Perl/perl5/issues/15091>
+.ie n .SS "Remove duplicate environment variables from ""environ"""
+.el .SS "Remove duplicate environment variables from \f(CWenviron\fP"
+.IX Subsection "Remove duplicate environment variables from environ"
+Previously, if an environment variable appeared more than once in \f(CW\*(C`environ[]\*(C'\fR,
+\&\f(CW%ENV\fR would contain the last entry for that name, while a
+typical \f(CWgetenv()\fR would return the first entry.  We now make sure \f(CW%ENV\fR
+contains the same as what \f(CWgetenv()\fR returns.
+.PP
+Secondly, we now remove duplicates from \f(CW\*(C`environ[]\*(C'\fR, so if a setting with that
+name is set in \f(CW%ENV\fR we won't pass an unsafe value to a child process.
+.PP
+This is CVE\-2016\-2381.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with Perl 5.22.1.  If any
+exist, they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+File::Spec has been upgraded from version 3.56 to 3.56_01.
+.Sp
+\&\f(CWcanonpath()\fR now preserves taint.  See "Fix loss of taint in
+\&\f(CWcanonpath()\fR".
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20151213 to 5.20160429.
+.Sp
+The version number of Digest::SHA listed for Perl 5.18.4 was wrong and has
+been corrected.  Likewise for the version number of Config in 5.18.3 and
+5.18.4.
+[GH #15202] <https://github.com/Perl/perl5/issues/15202>
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperldiag\fR
+.IX Subsection "perldiag"
+.IP \(bu 4
+The explanation of the warning "unable to close filehandle \f(CW%s\fR properly: \f(CW%s\fR"
+which can occur when doing an implicit close of a filehandle has been expanded
+and improved.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+The documentation of \f(CWhex()\fR has been revised to clarify valid
+inputs.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Dtrace builds now build successfully on systems with a newer dtrace that
+require an input object file that uses the probes in the \fI.d\fR file.
+.Sp
+Previously the probe would fail and cause a build failure.
+.Sp
+[GH #13985] <https://github.com/Perl/perl5/issues/13985>
+.IP \(bu 4
+\&\fIConfigure\fR no longer probes for \fIlibnm\fR by default.  Originally this was the
+"New Math" library, but the name has been re-used by the GNOME NetworkManager.
+.Sp
+[GH #15115] <https://github.com/Perl/perl5/issues/15115>
+.IP \(bu 4
+\&\fIConfigure\fR now knows about gcc 5.
+.IP \(bu 4
+Compiling perl with \fB\-DPERL_MEM_LOG\fR now works again.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Darwin 4
+.IX Item "Darwin"
+Compiling perl with \fB\-Dusecbacktrace\fR on Darwin now works again.
+.Sp
+[GH #15245] <https://github.com/Perl/perl5/issues/15245>
+.IP "OS X/Darwin" 4
+.IX Item "OS X/Darwin"
+Builds with both \fB\-DDEBUGGING\fR and threading enabled would fail with a "panic:
+free from wrong pool" error when built or tested from Terminal on OS X.  This
+was caused by perl's internal management of the environment conflicting with an
+atfork handler using the libc \f(CWsetenv()\fR function to update the environment.
+.Sp
+Perl now uses \f(CWsetenv()\fR/\f(CWunsetenv()\fR to update the environment on OS X.
+.Sp
+[GH #14955] <https://github.com/Perl/perl5/issues/14955>
+.IP ppc64el 4
+.IX Item "ppc64el"
+The floating point format of ppc64el (Debian naming for little-endian PowerPC)
+is now detected correctly.
+.IP Tru64 4
+.IX Item "Tru64"
+A test failure in \fIt/porting/extrefs.t\fR has been fixed.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+An unwarranted assertion in \f(CWPerl_newATTRSUB_x()\fR has been removed.  If a stub
+subroutine definition with a prototype has been seen, then any subsequent stub
+(or definition) of the same subroutine with an attribute was causing an
+assertion failure because of a null pointer.
+.Sp
+[GH #15081] <https://github.com/Perl/perl5/issues/15081>
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Calls to the placeholder \f(CW&PL_sv_yes\fR used internally when an \f(CWimport()\fR or
+\&\f(CWunimport()\fR method isn't found now correctly handle scalar context.
+[GH #14902] <https://github.com/Perl/perl5/issues/14902>
+.IP \(bu 4
+The \f(CWpipe()\fR operator would assert for \f(CW\*(C`DEBUGGING\*(C'\fR builds
+instead of producing the correct error message.  The condition asserted on is
+detected and reported on correctly without the assertions, so the assertions
+were removed.
+[GH #15015] <https://github.com/Perl/perl5/issues/15015>
+.IP \(bu 4
+In some cases, failing to parse a here-doc would attempt to use freed memory.
+This was caused by a pointer not being restored correctly.
+[GH #15009] <https://github.com/Perl/perl5/issues/15009>
+.IP \(bu 4
+Perl now reports more context when it sees an array where it expects to see an
+operator, and avoids an assertion failure.
+[GH #14472] <https://github.com/Perl/perl5/issues/14472>
+.IP \(bu 4
+If a here-doc was found while parsing another operator, the parser had already
+read end of file, and the here-doc was not terminated, perl could produce an
+assertion or a segmentation fault.  This now reliably complains about the
+unterminated here-doc.
+[GH #14789] <https://github.com/Perl/perl5/issues/14789>
+.IP \(bu 4
+Parsing beyond the end of the buffer when processing a \f(CW\*(C`#line\*(C'\fR directive with
+no filename is now avoided.
+[GH #15139] <https://github.com/Perl/perl5/issues/15139>
+.IP \(bu 4
+Perl 5.22.0 added support for the C99 hexadecimal floating point notation, but
+sometimes misparsed hex floats.  This has been fixed.
+[GH #15120] <https://github.com/Perl/perl5/issues/15120>
+.IP \(bu 4
+Certain regex patterns involving a complemented posix class in an inverted
+bracketed character class, and matching something else optionally would
+improperly fail to match.  An example of one that could fail is
+\&\f(CW\*(C`qr/_?[^\eWbar]\ex{100}/\*(C'\fR.  This has been fixed.
+[GH #15181] <https://github.com/Perl/perl5/issues/15181>
+.IP \(bu 4
+Fixed an issue with \f(CWpack()\fR where \f(CW\*(C`pack "H"\*(C'\fR (and
+\&\f(CW\*(C`pack "h"\*(C'\fR) could read past the source when given a non\-utf8 source and a
+utf8 target.
+[GH #14977] <https://github.com/Perl/perl5/issues/14977>
+.IP \(bu 4
+Fixed some cases where perl would abort due to a segmentation fault, or a
+C\-level assert.
+[GH #14941] <https://github.com/Perl/perl5/issues/14941>
+[GH #14962] <https://github.com/Perl/perl5/issues/14962>
+[GH #14963] <https://github.com/Perl/perl5/issues/14963>
+[GH #14997] <https://github.com/Perl/perl5/issues/14997>
+[GH #15039] <https://github.com/Perl/perl5/issues/15039>
+[GH #15247] <https://github.com/Perl/perl5/issues/15247>
+[GH #15251] <https://github.com/Perl/perl5/issues/15251>
+.IP \(bu 4
+A memory leak when setting \f(CW$ENV{foo}\fR on Darwin has been fixed.
+[GH #14955] <https://github.com/Perl/perl5/issues/14955>
+.IP \(bu 4
+Perl now correctly raises an error when trying to compile patterns with
+unterminated character classes while there are trailing backslashes.
+[GH #14919] <https://github.com/Perl/perl5/issues/14919>
+.IP \(bu 4
+\&\f(CW\*(C`NOTHING\*(C'\fR regops and \f(CW\*(C`EXACTFU_SS\*(C'\fR regops in \f(CWmake_trie()\fR are now handled
+properly.
+[GH #14945] <https://github.com/Perl/perl5/issues/14945>
+.IP \(bu 4
+Perl now only tests \f(CWsemctl()\fR if we have everything needed to use it.  In
+FreeBSD the \f(CWsemctl()\fR entry point may exist, but it can be disabled by
+policy.
+[GH #15180] <https://github.com/Perl/perl5/issues/15180>
+.IP \(bu 4
+A regression that allowed undeclared barewords as hash keys to work despite
+strictures has been fixed.
+[GH #15099] <https://github.com/Perl/perl5/issues/15099>
+.IP \(bu 4
+As an optimization (introduced in Perl 5.20.0), \f(CWuc()\fR,
+\&\f(CWlc()\fR, \f(CWucfirst()\fR and
+\&\f(CWlcfirst()\fR sometimes modify their argument in-place
+rather than returning a modified copy.  The criteria for this optimization has
+been made stricter to avoid these functions accidentally modifying in-place
+when they should not, which has been happening in some cases, e.g. in
+List::Util.
+.IP \(bu 4
+Excessive memory usage in the compilation of some regular expressions involving
+non-ASCII characters has been reduced.  A more complete fix is forthcoming in
+Perl 5.24.0.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.22.2 represents approximately 5 months of development since Perl 5.22.1
+and contains approximately 3,000 lines of changes across 110 files from 24
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,500 lines of changes to 52 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.22.2:
+.PP
+Aaron Crane, Abigail, Andreas König, Aristotle Pagaltzis, Chris 'BinGOs'
+Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, David Golden, David
+Mitchell, H.Merijn Brand, James E Keenan, Jarkko Hietaniemi, Karen Etheridge,
+Karl Williamson, Matthew Horsfall, Niko Tyni, Ricardo Signes, Sawyer X, Stevan
+Little, Steve Hay, Todd Rinaldo, Tony Cook, Vladimir Timofeev, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at http://www.perl.org/ ,
+the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5223delta.1 b/upstream/mageia-cauldron/man1/perl5223delta.1
new file mode 100644
index 00000000..34bda697
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5223delta.1
@@ -0,0 +1,289 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5223DELTA 1"
+.TH PERL5223DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5223delta \- what is new for perl v5.22.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.22.2 release and the 5.22.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.22.1, first read
+perl5222delta, which describes differences between 5.22.1 and 5.22.2.
+.SH Security
+.IX Header "Security"
+.SS "\fB\-Di\fP switch is now required for PerlIO debugging output"
+.IX Subsection "-Di switch is now required for PerlIO debugging output"
+Previously PerlIO debugging output would be sent to the file specified by the
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable if perl wasn't running setuid and the
+\&\fB\-T\fR or \fB\-t\fR switches hadn't been parsed yet.
+.PP
+If perl performed output at a point where it hadn't yet parsed its switches
+this could result in perl creating or overwriting the file named by
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR even when the \fB\-T\fR switch had been supplied.
+.PP
+Perl now requires the \fB\-Di\fR switch to produce PerlIO debugging output.  By
+default this is written to \f(CW\*(C`stderr\*(C'\fR, but can optionally be redirected to a
+file by setting the \f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable.
+.PP
+If perl is running setuid or the \fB\-T\fR switch was supplied \f(CW\*(C`PERLIO_DEBUG\*(C'\fR is
+ignored and the debugging output is sent to \f(CW\*(C`stderr\*(C'\fR as for any other \fB\-D\fR
+switch.
+.SS "Core modules and tools no longer search \fI"".""\fP for optional modules"
+.IX Subsection "Core modules and tools no longer search ""."" for optional modules"
+The tools and many modules supplied in core no longer search the default
+current directory entry in \f(CW@INC\fR for optional modules.  For
+example, Storable will remove the final \fI"."\fR from \f(CW@INC\fR before trying to
+load Log::Agent.
+.PP
+This prevents an attacker injecting an optional module into a process run by
+another user where the current directory is writable by the attacker, e.g. the
+\&\fI/tmp\fR directory.
+.PP
+In most cases this removal should not cause problems, but difficulties were
+encountered with base, which treats every module name supplied as optional.
+These difficulties have not yet been resolved, so for this release there are no
+changes to base.  We hope to have a fix for base in Perl 5.22.4.
+.PP
+To protect your own code from this attack, either remove the default \fI"."\fR
+entry from \f(CW@INC\fR at the start of your script, so:
+.PP
+.Vb 3
+\&  #!/usr/bin/perl
+\&  use strict;
+\&  ...
+.Ve
+.PP
+becomes:
+.PP
+.Vb 4
+\&  #!/usr/bin/perl
+\&  BEGIN { pop @INC if $INC[\-1] eq \*(Aq.\*(Aq }
+\&  use strict;
+\&  ...
+.Ve
+.PP
+or for modules, remove \fI"."\fR from a localized \f(CW@INC\fR, so:
+.PP
+.Vb 1
+\&  my $can_foo = eval { require Foo; }
+.Ve
+.PP
+becomes:
+.PP
+.Vb 5
+\&  my $can_foo = eval {
+\&      local @INC = @INC;
+\&      pop @INC if $INC[\-1] eq \*(Aq.\*(Aq;
+\&      require Foo;
+\&  };
+.Ve
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+Other than the security changes above there are no changes intentionally
+incompatible with Perl 5.22.2.  If any exist, they are bugs, and we request
+that you submit a report.  See "Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.04 to 2.04_01.
+.IP \(bu 4
+bignum has been upgraded from version 0.39 to 0.39_01.
+.IP \(bu 4
+CPAN has been upgraded from version 2.11 to 2.11_01.
+.IP \(bu 4
+Digest has been upgraded from version 1.17 to 1.17_01.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.95 to 5.95_01.
+.IP \(bu 4
+Encode has been upgraded from version 2.72 to 2.72_01.
+.IP \(bu 4
+ExtUtils::Command has been upgraded from version 1.20 to 1.20_01.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.04_01 to 7.04_02.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.48 to 0.48_01.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.56_01 to 3.56_02.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.054 to 0.054_01.
+.IP \(bu 4
+IO has been upgraded from version 1.35 to 1.35_01.
+.IP \(bu 4
+The IO-Compress modules have been upgraded from version 2.068 to 2.068_001.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.92 to 0.92_01.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.27300 to 2.27300_01.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.26 to 1.26_01.
+.IP \(bu 4
+Locale::Maketext::Simple has been upgraded from version 0.21 to 0.21_01.
+.IP \(bu 4
+Memoize has been upgraded from version 1.03 to 1.03_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20160429 to 5.20170114_22.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.43 to 2.43_01.
+.IP \(bu 4
+Parse::CPAN::Meta has been upgraded from version 1.4414 to 1.4414_001.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.22 to 1.2201.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.25 to 3.25_01.
+.IP \(bu 4
+Storable has been upgraded from version 2.53_01 to 2.53_02.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.33 to 0.33_01.
+.IP \(bu 4
+Test has been upgraded from version 1.26 to 1.26_01.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.35 to 3.35_01.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.20 to 0.20_01, fixing a security
+hole in which binary files could be loaded from a path outside of \f(CW@INC\fR.
+[GH #15418] <https://github.com/Perl/perl5/issues/15418>
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlapio\fR
+.IX Subsection "perlapio"
+.IP \(bu 4
+The documentation of \f(CW\*(C`PERLIO_DEBUG\*(C'\fR has been updated.
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+The new \fB\-Di\fR switch has been documented, and the documentation of
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR has been updated.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+A new test script, \fIt/run/switchDx.t\fR, has been added to test that the new
+\&\fB\-Di\fR switch is working correctly.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The \f(CW\*(C`PadlistNAMES\*(C'\fR macro is an lvalue again.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.22.3 represents approximately 9 months of development since Perl 5.22.2
+and contains approximately 4,400 lines of changes across 240 files from 20
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 2,200 lines of changes to 170 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.22.3:
+.PP
+Aaron Crane, Abigail, Alex Vandiver, Aristotle Pagaltzis, Chad Granum, Chris
+\&'BinGOs' Williams, Craig A. Berry, David Mitchell, Father Chrysostomos, James E
+Keenan, Jarkko Hietaniemi, Karen Etheridge, Karl Williamson, Matthew Horsfall,
+Niko Tyni, Ricardo Signes, Sawyer X, Stevan Little, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the Perl bug database at
+https://rt.perl.org/ .  There may also be information at http://www.perl.org/ ,
+the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5224delta.1 b/upstream/mageia-cauldron/man1/perl5224delta.1
new file mode 100644
index 00000000..08825035
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5224delta.1
@@ -0,0 +1,163 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5224DELTA 1"
+.TH PERL5224DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5224delta \- what is new for perl v5.22.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.22.3 release and the 5.22.4
+release.
+.PP
+If you are upgrading from an earlier release such as 5.22.2, first read
+perl5223delta, which describes differences between 5.22.2 and 5.22.3.
+.SH Security
+.IX Header "Security"
+.ie n .SS "Improved handling of '.' in @INC in base.pm"
+.el .SS "Improved handling of '.' in \f(CW@INC\fP in base.pm"
+.IX Subsection "Improved handling of '.' in @INC in base.pm"
+The handling of (the removal of) \f(CW\*(Aq.\*(Aq\fR in \f(CW@INC\fR in base has been
+improved.  This resolves some problematic behaviour in the approach taken in
+Perl 5.22.3, which is probably best described in the following two threads on
+the Perl 5 Porters mailing list:
+<http://www.nntp.perl.org/group/perl.perl5.porters/2016/08/msg238991.html>,
+<http://www.nntp.perl.org/group/perl.perl5.porters/2016/10/msg240297.html>.
+.SS """Escaped"" colons and relative paths in PATH"
+.IX Subsection """Escaped"" colons and relative paths in PATH"
+On Unix systems, Perl treats any relative paths in the PATH environment
+variable as tainted when starting a new process.  Previously, it was allowing a
+backslash to escape a colon (unlike the OS), consequently allowing relative
+paths to be considered safe if the PATH was set to something like \f(CW\*(C`/\e:.\*(C'\fR.  The
+check has been fixed to treat \f(CW\*(C`.\*(C'\fR as tainted in that example.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+base has been upgraded from version 2.22 to 2.22_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170114_22 to 5.20170715_22.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Fixed a crash with \f(CW\*(C`s///l\*(C'\fR where it thought it was dealing with UTF\-8 when it
+wasn't.
+[GH #15543] <https://github.com/Perl/perl5/issues/15543>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.22.4 represents approximately 6 months of development since Perl 5.22.3
+and contains approximately 2,200 lines of changes across 52 files from 16
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 970 lines of changes to 18 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.22.4:
+.PP
+Aaron Crane, Abigail, Aristotle Pagaltzis, Chris 'BinGOs' Williams, David
+Mitchell, Eric Herman, Father Chrysostomos, James E Keenan, Karl Williamson,
+Lukas Mai, Renee Baecker, Ricardo Signes, Sawyer X, Stevan Little, Steve Hay,
+Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5\-security\-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5240delta.1 b/upstream/mageia-cauldron/man1/perl5240delta.1
new file mode 100644
index 00000000..655e96df
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5240delta.1
@@ -0,0 +1,1628 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5240DELTA 1"
+.TH PERL5240DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5240delta \- what is new for perl v5.24.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the differences between the 5.22.0 release and the
+5.24.0 release.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Postfix dereferencing is no longer experimental"
+.IX Subsection "Postfix dereferencing is no longer experimental"
+Using the \f(CW\*(C`postderef\*(C'\fR and \f(CW\*(C`postderef_qq\*(C'\fR features no longer emits a
+warning. Existing code that disables the \f(CW\*(C`experimental::postderef\*(C'\fR warning
+category that they previously used will continue to work. The \f(CW\*(C`postderef\*(C'\fR
+feature has no effect; all Perl code can use postfix dereferencing,
+regardless of what feature declarations are in scope. The \f(CW5.24\fR feature
+bundle now includes the \f(CW\*(C`postderef_qq\*(C'\fR feature.
+.SS "Unicode 8.0 is now supported"
+.IX Subsection "Unicode 8.0 is now supported"
+For details on what is in this release, see
+<http://www.unicode.org/versions/Unicode8.0.0/>.
+.SS "perl will now croak when closing an in-place output file fails"
+.IX Subsection "perl will now croak when closing an in-place output file fails"
+Until now, failure to close the output file for an in-place edit was not
+detected, meaning that the input file could be clobbered without the edit being
+successfully completed.  Now, when the output file cannot be closed
+successfully, an exception is raised.
+.ie n .SS "New ""\eb{lb}"" boundary in regular expressions"
+.el .SS "New \f(CW\eb{lb}\fP boundary in regular expressions"
+.IX Subsection "New b{lb} boundary in regular expressions"
+\&\f(CW\*(C`lb\*(C'\fR stands for Line Break.  It is a Unicode property
+that determines where a line of text is suitable to break (typically so
+that it can be output without overflowing the available horizontal
+space).  This capability has long been furnished by the
+Unicode::LineBreak module, but now a light-weight, non-customizable
+version that is suitable for many purposes is in core Perl.
+.ie n .SS """qr/(?[ ])/"" now works in UTF\-8 locales"
+.el .SS "\f(CWqr/(?[ ])/\fP now works in UTF\-8 locales"
+.IX Subsection "qr/(?[ ])/ now works in UTF-8 locales"
+Extended Bracketed Character Classes
+now will successfully compile when \f(CW\*(C`use\ locale\*(C'\fR is in effect.  The compiled
+pattern will use standard Unicode rules.  If the runtime locale is not a
+UTF\-8 one, a warning is raised and standard Unicode rules are used
+anyway.  No tainting is done since the outcome does not actually depend
+on the locale.
+.ie n .SS "Integer shift (""<<"" and "">>"") now more explicitly defined"
+.el .SS "Integer shift (\f(CW<<\fP and \f(CW>>\fP) now more explicitly defined"
+.IX Subsection "Integer shift (<< and >>) now more explicitly defined"
+Negative shifts are reverse shifts: left shift becomes right shift,
+and right shift becomes left shift.
+.PP
+Shifting by the number of bits in a native integer (or more) is zero,
+except when the "overshift" is right shifting a negative value under
+\&\f(CW\*(C`use integer\*(C'\fR, in which case the result is \-1 (arithmetic shift).
+.PP
+Until now negative shifting and overshifting have been undefined
+because they have relied on whatever the C implementation happens
+to do.  For example, for the overshift a common C behavior is
+"modulo shift":
+.PP
+.Vb 1
+\&  1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1  # Common C behavior.
+\&
+\&  # And the same for <<, while Perl now produces 0 for both.
+.Ve
+.PP
+Now these behaviors are well-defined under Perl, regardless of what
+the underlying C implementation does.  Note, however, that you are still
+constrained by the native integer width: you need to know how far left you
+can go.  You can use for example:
+.PP
+.Vb 2
+\&  use Config;
+\&  my $wordbits = $Config{uvsize} * 8;  # Or $Config{uvsize} << 3.
+.Ve
+.PP
+If you need a more bits on the left shift, you can use for example
+the \f(CW\*(C`bigint\*(C'\fR pragma, or the \f(CW\*(C`Bit::Vector\*(C'\fR module from CPAN.
+.SS "printf and sprintf now allow reordered precision arguments"
+.IX Subsection "printf and sprintf now allow reordered precision arguments"
+That is, \f(CW\*(C`sprintf \*(Aq|%.*2$d|\*(Aq, 2, 3\*(C'\fR now returns \f(CW\*(C`|002|\*(C'\fR. This extends
+the existing reordering mechanism (which allows reordering for arguments
+that are used as format fields, widths, and vector separators).
+.ie n .SS "More fields provided to ""sigaction"" callback with ""SA_SIGINFO"""
+.el .SS "More fields provided to \f(CWsigaction\fP callback with \f(CWSA_SIGINFO\fP"
+.IX Subsection "More fields provided to sigaction callback with SA_SIGINFO"
+When passing the \f(CW\*(C`SA_SIGINFO\*(C'\fR flag to sigaction, the
+\&\f(CW\*(C`errno\*(C'\fR, \f(CW\*(C`status\*(C'\fR, \f(CW\*(C`uid\*(C'\fR, \f(CW\*(C`pid\*(C'\fR, \f(CW\*(C`addr\*(C'\fR and \f(CW\*(C`band\*(C'\fR fields are now
+included in the hash passed to the handler, if supported by the
+platform.
+.SS "Hashbang redirection to Perl 6"
+.IX Subsection "Hashbang redirection to Perl 6"
+Previously perl would redirect to another interpreter if it found a
+hashbang path unless the path contains "perl" (see perlrun). To improve
+compatibility with Perl 6 this behavior has been extended to also redirect
+if "perl" is followed by "6".
+.SH Security
+.IX Header "Security"
+.ie n .SS "Set proper umask before calling mkstemp(3)"
+.el .SS "Set proper umask before calling \f(CWmkstemp(3)\fP"
+.IX Subsection "Set proper umask before calling mkstemp(3)"
+In 5.22 perl started setting umask to 0600 before calling \f(CWmkstemp(3)\fR
+and restoring it afterwards. This wrongfully tells \f(CWopen(2)\fR to strip
+the owner read and write bits from the given mode before applying it,
+rather than the intended negation of leaving only those bits in place.
+.PP
+Systems that use mode 0666 in \f(CWmkstemp(3)\fR (like old versions of
+glibc) create a file with permissions 0066, leaving world read and
+write permissions regardless of current umask.
+.PP
+This has been fixed by using umask 0177 instead. [perl #127322]
+.SS "Fix out of boundary access in Win32 path handling"
+.IX Subsection "Fix out of boundary access in Win32 path handling"
+This is CVE\-2015\-8608.  For more information see
+[GH #15067] <https://github.com/Perl/perl5/issues/15067>
+.SS "Fix loss of taint in canonpath"
+.IX Subsection "Fix loss of taint in canonpath"
+This is CVE\-2015\-8607.  For more information see
+[GH #15084] <https://github.com/Perl/perl5/issues/15084>
+.ie n .SS "Avoid accessing uninitialized memory in win32 crypt()"
+.el .SS "Avoid accessing uninitialized memory in win32 \f(CWcrypt()\fP"
+.IX Subsection "Avoid accessing uninitialized memory in win32 crypt()"
+Added validation that will detect both a short salt and invalid characters
+in the salt.
+[GH #15091] <https://github.com/Perl/perl5/issues/15091>
+.ie n .SS "Remove duplicate environment variables from ""environ"""
+.el .SS "Remove duplicate environment variables from \f(CWenviron\fP"
+.IX Subsection "Remove duplicate environment variables from environ"
+Previously, if an environment variable appeared more than once in
+\&\f(CW\*(C`environ[]\*(C'\fR, \f(CW%ENV\fR would contain the last entry for that name,
+while a typical \f(CWgetenv()\fR would return the first entry. We now
+make sure \f(CW%ENV\fR contains the same as what \f(CW\*(C`getenv\*(C'\fR returns.
+.PP
+Second, we remove duplicates from \f(CW\*(C`environ[]\*(C'\fR, so if a setting
+with that name is set in \f(CW%ENV\fR, we won't pass an unsafe value
+to a child process.
+.PP
+[CVE\-2016\-2381]
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.ie n .SS "The ""autoderef"" feature has been removed"
+.el .SS "The \f(CWautoderef\fP feature has been removed"
+.IX Subsection "The autoderef feature has been removed"
+The experimental \f(CW\*(C`autoderef\*(C'\fR feature (which allowed calling \f(CW\*(C`push\*(C'\fR,
+\&\f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR, \f(CW\*(C`splice\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR, and \f(CW\*(C`each\*(C'\fR on
+a scalar argument) has been deemed unsuccessful. It has now been removed;
+trying to use the feature (or to disable the \f(CW\*(C`experimental::autoderef\*(C'\fR
+warning it previously triggered) now yields an exception.
+.ie n .SS "Lexical $_ has been removed"
+.el .SS "Lexical \f(CW$_\fP has been removed"
+.IX Subsection "Lexical $_ has been removed"
+\&\f(CW\*(C`my $_\*(C'\fR was introduced in Perl 5.10, and subsequently caused much confusion
+with no obvious solution.  In Perl 5.18.0, it was made experimental on the
+theory that it would either be removed or redesigned in a less confusing (but
+backward-incompatible) way.  Over the following years, no alternatives were
+proposed.  The feature has now been removed and will fail to compile.
+.ie n .SS """qr/\eb{wb}/"" is now tailored to Perl expectations"
+.el .SS "\f(CWqr/\eb{wb}/\fP is now tailored to Perl expectations"
+.IX Subsection "qr/b{wb}/ is now tailored to Perl expectations"
+This is now more suited to be a drop-in replacement for plain \f(CW\*(C`\eb\*(C'\fR, but
+giving better results for parsing natural language.  Previously it
+strictly followed the current Unicode rules which calls for it to match
+between each white space character.  Now it doesn't generally match
+within spans of white space, behaving like \f(CW\*(C`\eb\*(C'\fR does.  See
+"\eb{wb}" in perlrebackslash
+.SS "Regular expression compilation errors"
+.IX Subsection "Regular expression compilation errors"
+Some regular expression patterns that had runtime errors now
+don't compile at all.
+.PP
+Almost all Unicode properties using the \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR regular
+expression pattern constructs are now checked for validity at pattern
+compilation time, and invalid ones will cause the program to not
+compile.  In earlier releases, this check was often deferred until run
+time.  Whenever an error check is moved from run\- to compile time,
+erroneous code is caught 100% of the time, whereas before it would only
+get caught if and when the offending portion actually gets executed,
+which for unreachable code might be never.
+.ie n .SS """qr/\eN{}/"" now disallowed under ""use re ""strict"""""
+.el .SS "\f(CWqr/\eN{}/\fP now disallowed under \f(CWuse re ""strict""\fP"
+.IX Subsection "qr/N{}/ now disallowed under use re ""strict"""
+An empty \f(CW\*(C`\eN{}\*(C'\fR makes no sense, but for backwards compatibility is
+accepted as doing nothing, though a deprecation warning is raised by
+default.  But now this is a fatal error under the experimental feature
+"'strict' mode" in re.
+.SS "Nested declarations are now disallowed"
+.IX Subsection "Nested declarations are now disallowed"
+A \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, or \f(CW\*(C`state\*(C'\fR declaration is no longer allowed inside
+of another \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, or \f(CW\*(C`state\*(C'\fR declaration.
+.PP
+For example, these are now fatal:
+.PP
+.Vb 2
+\&   my ($x, my($y));
+\&   our (my $x);
+.Ve
+.PP
+[GH #14799] <https://github.com/Perl/perl5/issues/14799>
+.PP
+[GH #13548] <https://github.com/Perl/perl5/issues/13548>
+.ie n .SS "The ""/\eC/"" character class has been removed."
+.el .SS "The \f(CW/\eC/\fP character class has been removed."
+.IX Subsection "The /C/ character class has been removed."
+This regular expression character class was deprecated in v5.20.0 and has
+produced a deprecation warning since v5.22.0. It is now a compile-time
+error. If you need to examine the individual bytes that make up a
+UTF8\-encoded character, then use \f(CWutf8::encode()\fR on the string (or a
+copy) first.
+.ie n .SS "chdir(\*(Aq\*(Aq) no longer chdirs home"
+.el .SS "\f(CWchdir(\*(Aq\*(Aq)\fP no longer chdirs home"
+.IX Subsection "chdir() no longer chdirs home"
+Using \f(CWchdir(\*(Aq\*(Aq)\fR or \f(CWchdir(undef)\fR to chdir home has been deprecated since
+perl v5.8, and will now fail.  Use \f(CWchdir()\fR instead.
+.SS "ASCII characters in variable names must now be all visible"
+.IX Subsection "ASCII characters in variable names must now be all visible"
+It was legal until now on ASCII platforms for variable names to contain
+non-graphical ASCII control characters (ordinals 0 through 31, and 127,
+which are the C0 controls and \f(CW\*(C`DELETE\*(C'\fR).  This usage has been
+deprecated since v5.20, and as of now causes a syntax error.  The
+variables these names referred to are special, reserved by Perl for
+whatever use it may choose, now, or in the future.  Each such variable
+has an alternative way of spelling it.  Instead of the single
+non-graphic control character, a two character sequence beginning with a
+caret is used, like \f(CW$^]\fR and \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR.  Details are at
+perlvar.   It remains legal, though unwise and deprecated (raising a
+deprecation warning), to use certain non-graphic non-ASCII characters in
+variables names when not under \f(CW\*(C`use\ utf8\*(C'\fR.  No code should do this,
+as all such variables are reserved by Perl, and Perl doesn't currently
+define any of them (but could at any time, without notice).
+.ie n .SS "An off by one issue in $Carp::MaxArgNums has been fixed"
+.el .SS "An off by one issue in \f(CW$Carp::MaxArgNums\fP has been fixed"
+.IX Subsection "An off by one issue in $Carp::MaxArgNums has been fixed"
+\&\f(CW$Carp::MaxArgNums\fR is supposed to be the number of arguments to display.
+Prior to this version, it was instead showing \f(CW$Carp::MaxArgNums\fR + 1 arguments,
+contrary to the documentation.
+.ie n .SS "Only blanks and tabs are now allowed within ""[...]"" within ""(?[...])""."
+.el .SS "Only blanks and tabs are now allowed within \f(CW[...]\fP within \f(CW(?[...])\fP."
+.IX Subsection "Only blanks and tabs are now allowed within [...] within (?[...])."
+The experimental Extended Bracketed Character Classes can contain regular
+bracketed character classes within them.  These differ from regular ones in
+that white space is generally ignored, unless escaped by preceding it with a
+backslash.  The white space that is ignored is now limited to just tab \f(CW\*(C`\et\*(C'\fR
+and SPACE characters.  Previously, it was any white space.  See
+"Extended Bracketed Character Classes" in perlrecharclass.
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS "Using code points above the platform's ""IV_MAX"" is now deprecated"
+.el .SS "Using code points above the platform's \f(CWIV_MAX\fP is now deprecated"
+.IX Subsection "Using code points above the platform's IV_MAX is now deprecated"
+Unicode defines code points in the range \f(CW\*(C`0..0x10FFFF\*(C'\fR.  Some standards
+at one time defined them up to 2**31 \- 1, but Perl has allowed them to
+be as high as anything that will fit in a word on the platform being
+used.  However, use of those above the platform's \f(CW\*(C`IV_MAX\*(C'\fR is broken in
+some constructs, notably \f(CW\*(C`tr///\*(C'\fR, regular expression patterns involving
+quantifiers, and in some arithmetic and comparison operations, such as
+being the upper limit of a loop.  Now the use of such code points raises
+a deprecation warning, unless that warning category is turned off.
+\&\f(CW\*(C`IV_MAX\*(C'\fR is typically 2**31 \-1 on 32\-bit platforms, and 2**63\-1 on
+64\-bit ones.
+.SS "Doing bitwise operations on strings containing code points above 0xFF is deprecated"
+.IX Subsection "Doing bitwise operations on strings containing code points above 0xFF is deprecated"
+The string bitwise operators treat their operands as strings of bytes,
+and values beyond 0xFF are nonsensical in this context.  To operate on
+encoded bytes, first encode the strings.  To operate on code points'
+numeric values, use \f(CW\*(C`split\*(C'\fR and \f(CW\*(C`map ord\*(C'\fR.  In the future, this
+warning will be replaced by an exception.
+.ie n .SS "sysread(), syswrite(), recv() and send() are deprecated on :utf8 handles"
+.el .SS "\f(CWsysread()\fP, \f(CWsyswrite()\fP, \f(CWrecv()\fP and \f(CWsend()\fP are deprecated on :utf8 handles"
+.IX Subsection "sysread(), syswrite(), recv() and send() are deprecated on :utf8 handles"
+The \f(CWsysread()\fR, \f(CWrecv()\fR, \f(CWsyswrite()\fR and \f(CWsend()\fR operators
+are deprecated on handles that have the \f(CW\*(C`:utf8\*(C'\fR layer, either
+explicitly, or implicitly, eg., with the \f(CW:encoding(UTF\-16LE)\fR layer.
+.PP
+Both \f(CWsysread()\fR and \f(CWrecv()\fR currently use only the \f(CW\*(C`:utf8\*(C'\fR flag for the
+stream, ignoring the actual layers.  Since \f(CWsysread()\fR and \f(CWrecv()\fR do no
+UTF\-8 validation they can end up creating invalidly encoded scalars.
+.PP
+Similarly, \f(CWsyswrite()\fR and \f(CWsend()\fR use only the \f(CW\*(C`:utf8\*(C'\fR flag, otherwise
+ignoring any layers.  If the flag is set, both write the value UTF\-8
+encoded, even if the layer is some different encoding, such as the
+example above.
+.PP
+Ideally, all of these operators would completely ignore the \f(CW\*(C`:utf8\*(C'\fR
+state, working only with bytes, but this would result in silently
+breaking existing code.  To avoid this a future version of perl will
+throw an exception when any of \f(CWsysread()\fR, \f(CWrecv()\fR, \f(CWsyswrite()\fR or \f(CWsend()\fR
+are called on handle with the \f(CW\*(C`:utf8\*(C'\fR layer.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+The overhead of scope entry and exit has been considerably reduced, so
+for example subroutine calls, loops and basic blocks are all faster now.
+This empty function call now takes about a third less time to execute:
+.Sp
+.Vb 1
+\&    sub f{} f();
+.Ve
+.IP \(bu 4
+Many languages, such as Chinese, are caseless.  Perl now knows about
+most common ones, and skips much of the work when
+a program tries to change case in them (like \f(CWucfirst()\fR) or match
+caselessly (\f(CW\*(C`qr//i\*(C'\fR).  This will speed up a program, such as a web
+server, that can operate on multiple languages, while it is operating on a
+caseless one.
+.IP \(bu 4
+\&\f(CW\*(C`/fixed\-substr/\*(C'\fR has been made much faster.
+.Sp
+On platforms with a libc \f(CWmemchr()\fR implementation which makes good use of
+underlying hardware support, patterns which include fixed substrings will now
+often be much faster; for example with glibc on a recent x86_64 CPU, this:
+.Sp
+.Vb 2
+\&    $s = "a" x 1000 . "wxyz";
+\&    $s =~ /wxyz/ for 1..30000
+.Ve
+.Sp
+is now about 7 times faster.  On systems with slow \f(CWmemchr()\fR, e.g. 32\-bit ARM
+Raspberry Pi, there will be a small or little speedup.  Conversely, some
+pathological cases, such as \f(CW\*(C`"ab" x 1000 =~ /aa/\*(C'\fR will be slower now; up to 3
+times slower on the rPi, 1.5x slower on x86_64.
+.IP \(bu 4
+Faster addition, subtraction and multiplication.
+.Sp
+Since 5.8.0, arithmetic became slower due to the need to support
+64\-bit integers. To deal with 64\-bit integers, a lot more corner
+cases need to be checked, which adds time. We now detect common
+cases where there is no need to check for those corner cases,
+and special-case them.
+.IP \(bu 4
+Preincrement, predecrement, postincrement, and postdecrement have been
+made faster by internally splitting the functions which handled multiple
+cases into different functions.
+.IP \(bu 4
+Creating Perl debugger data structures (see "Debugger Internals" in perldebguts)
+for XSUBs and const subs has been removed.  This removed one glob/scalar combo
+for each unique \f(CW\*(C`.c\*(C'\fR file that XSUBs and const subs came from.  On startup
+(\f(CW\*(C`perl \-e"0"\*(C'\fR) about half a dozen glob/scalar debugger combos were created.
+Loading XS modules created more glob/scalar combos.  These things were
+being created regardless of whether the perl debugger was being used,
+and despite the fact that it can't debug C code anyway
+.IP \(bu 4
+On Win32, \f(CW\*(C`stat\*(C'\fRing or \f(CW\*(C`\-X\*(C'\fRing a path, if the file or directory does not
+exist, is now 3.5x faster than before.
+.IP \(bu 4
+Single arguments in list assign are now slightly faster:
+.Sp
+.Vb 2
+\&  ($x) = (...);
+\&  (...) = ($x);
+.Ve
+.IP \(bu 4
+Less peak memory is now used when compiling regular expression patterns.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+arybase has been upgraded from version 0.10 to 0.11.
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 0.97 to 0.99.
+.IP \(bu 4
+autodie has been upgraded from version 2.26 to 2.29.
+.IP \(bu 4
+autouse has been upgraded from version 1.08 to 1.11.
+.IP \(bu 4
+B has been upgraded from version 1.58 to 1.62.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.35 to 1.37.
+.IP \(bu 4
+base has been upgraded from version 2.22 to 2.23.
+.IP \(bu 4
+Benchmark has been upgraded from version 1.2 to 1.22.
+.IP \(bu 4
+bignum has been upgraded from version 0.39 to 0.42.
+.IP \(bu 4
+bytes has been upgraded from version 1.04 to 1.05.
+.IP \(bu 4
+Carp has been upgraded from version 1.36 to 1.40.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.068 to 2.069.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.068 to 2.069.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.24 to 0.25.
+.IP \(bu 4
+CPAN::Meta has been upgraded from version 2.150001 to 2.150005.
+.IP \(bu 4
+CPAN::Meta::Requirements has been upgraded from version 2.132 to 2.140.
+.IP \(bu 4
+CPAN::Meta::YAML has been upgraded from version 0.012 to 0.018.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.158 to 2.160.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.22 to 1.23.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.31 to 3.32.
+.IP \(bu 4
+Dumpvalue has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.32 to 1.38.
+.IP \(bu 4
+Encode has been upgraded from version 2.72 to 2.80.
+.IP \(bu 4
+encoding has been upgraded from version 2.14 to 2.17.
+.IP \(bu 4
+encoding::warnings has been upgraded from version 0.11 to 0.12.
+.IP \(bu 4
+English has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+Errno has been upgraded from version 1.23 to 1.25.
+.IP \(bu 4
+experimental has been upgraded from version 0.013 to 0.016.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280221 to 0.280225.
+.IP \(bu 4
+ExtUtils::Embed has been upgraded from version 1.32 to 1.33.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.04_01 to 7.10_01.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.28 to 3.31.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.28 to 3.31.
+.IP \(bu 4
+feature has been upgraded from version 1.40 to 1.42.
+.IP \(bu 4
+fields has been upgraded from version 2.17 to 2.23.
+.IP \(bu 4
+File::Find has been upgraded from version 1.29 to 1.34.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.24 to 1.26.
+.IP \(bu 4
+File::Path has been upgraded from version 2.09 to 2.12_01.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.56 to 3.63.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.54 to 1.55.
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.45 to 2.48.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.18 to 0.19.
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.15 to 1.19.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.054 to 0.056.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.12 to 0.13.
+.IP \(bu 4
+if has been upgraded from version 0.0604 to 0.0606.
+.IP \(bu 4
+IO has been upgraded from version 1.35 to 1.36.
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.068 to 2.069.
+.IP \(bu 4
+IPC::Open3 has been upgraded from version 1.18 to 1.20.
+.IP \(bu 4
+IPC::SysV has been upgraded from version 2.04 to 2.06_01.
+.IP \(bu 4
+List::Util has been upgraded from version 1.41 to 1.42_02.
+.IP \(bu 4
+locale has been upgraded from version 1.06 to 1.08.
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.34 to 3.37.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.9997 to 1.999715.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.31 to 0.40.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2608 to 0.260802.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20150520 to 5.20160320.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000026 to 1.000031.
+.IP \(bu 4
+mro has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.12 to 1.14.
+.IP \(bu 4
+Opcode has been upgraded from version 1.32 to 1.34.
+.IP \(bu 4
+parent has been upgraded from version 0.232 to 0.234.
+.IP \(bu 4
+Parse::CPAN::Meta has been upgraded from version 1.4414 to 1.4417.
+.IP \(bu 4
+Perl::OSType has been upgraded from version 1.008 to 1.009.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.021009 to 5.021010.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.21 to 0.24.
+.IP \(bu 4
+PerlIO::mmap has been upgraded from version 0.014 to 0.016.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.22 to 0.24.
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.15 to 0.16.
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.25 to 3.25_02.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.29 to 3.32.
+.IP \(bu 4
+Pod::Usage has been upgraded from version 1.64 to 1.68.
+.IP \(bu 4
+POSIX has been upgraded from version 1.53 to 1.65.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.41 to 1.42_02.
+.IP \(bu 4
+SDBM_File has been upgraded from version 1.13 to 1.14.
+.IP \(bu 4
+SelfLoader has been upgraded from version 1.22 to 1.23.
+.IP \(bu 4
+Socket has been upgraded from version 2.018 to 2.020_03.
+.IP \(bu 4
+Storable has been upgraded from version 2.53 to 2.56.
+.IP \(bu 4
+strict has been upgraded from version 1.09 to 1.11.
+.IP \(bu 4
+Term::ANSIColor has been upgraded from version 4.03 to 4.04.
+.IP \(bu 4
+Term::Cap has been upgraded from version 1.15 to 1.17.
+.IP \(bu 4
+Test has been upgraded from version 1.26 to 1.28.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.35 to 3.36.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 3.05 to 3.08.
+.IP \(bu 4
+threads has been upgraded from version 2.01 to 2.06.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.48 to 1.50.
+.IP \(bu 4
+Tie::File has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+Tie::Scalar has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9726 to 1.9732.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.29 to 1.31.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.12 to 1.14.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.18 to 1.25.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.61 to 0.64.
+.IP \(bu 4
+UNIVERSAL has been upgraded from version 1.12 to 1.13.
+.IP \(bu 4
+utf8 has been upgraded from version 1.17 to 1.19.
+.IP \(bu 4
+version has been upgraded from version 0.9909 to 0.9916.
+.IP \(bu 4
+warnings has been upgraded from version 1.32 to 1.36.
+.IP \(bu 4
+Win32 has been upgraded from version 0.51 to 0.52.
+.IP \(bu 4
+Win32API::File has been upgraded from version 0.1202 to 0.1203.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.13 to 0.14.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.20 to 0.21.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+The process of using undocumented globals has been documented, namely, that one
+should send email to perl5\-porters@perl.org <mailto:perl5-porters@perl.org>
+first to get the go-ahead for documenting and using an undocumented function or
+global variable.
+.PP
+\fIperlcall\fR
+.IX Subsection "perlcall"
+.IP \(bu 4
+A number of cleanups have been made to perlcall, including:
+.RS 4
+.IP \(bu 4
+use \f(CW\*(C`EXTEND(SP, n)\*(C'\fR and \f(CWPUSHs()\fR instead of \f(CWXPUSHs()\fR where applicable
+and update prose to match
+.IP \(bu 4
+add POPu, POPul and POPpbytex to the "complete list of POP macros"
+and clarify the documentation for some of the existing entries, and
+a note about side-effects
+.IP \(bu 4
+add API documentation for POPu and POPul
+.IP \(bu 4
+use ERRSV more efficiently
+.IP \(bu 4
+approaches to thread-safety storage of SVs.
+.RE
+.RS 4
+.RE
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+The documentation of \f(CW\*(C`hex\*(C'\fR has been revised to clarify valid inputs.
+.IP \(bu 4
+Better explain meaning of negative PIDs in \f(CW\*(C`waitpid\*(C'\fR.
+[GH #15108] <https://github.com/Perl/perl5/issues/15108>
+.IP \(bu 4
+General cleanup: there's more consistency now (in POD usage, grammar, code
+examples), better practices in code examples (use of \f(CW\*(C`my\*(C'\fR, removal of bareword
+filehandles, dropped usage of \f(CW\*(C`&\*(C'\fR when calling subroutines, ...), etc.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+A new section has been added, "Dynamic Scope and the Context
+Stack" in perlguts, which explains how the perl context stack works.
+.PP
+\fIperllocale\fR
+.IX Subsection "perllocale"
+.IP \(bu 4
+A stronger caution about using locales in threaded applications is
+given.  Locales are not thread-safe, and you can get wrong results or
+even segfaults if you use them there.
+.PP
+\fIperlmodlib\fR
+.IX Subsection "perlmodlib"
+.IP \(bu 4
+We now recommend contacting the module-authors list or PAUSE in seeking
+guidance on the naming of modules.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+The documentation of \f(CW\*(C`qx//\*(C'\fR now describes how \f(CW$?\fR is affected.
+.PP
+\fIperlpolicy\fR
+.IX Subsection "perlpolicy"
+.IP \(bu 4
+This note has been added to perlpolicy:
+.Sp
+.Vb 3
+\& While civility is required, kindness is encouraged; if you have any
+\& doubt about whether you are being civil, simply ask yourself, "Am I
+\& being kind?" and aspire to that.
+.Ve
+.PP
+\fIperlreftut\fR
+.IX Subsection "perlreftut"
+.IP \(bu 4
+Fix some examples to be strict clean.
+.PP
+\fIperlrebackslash\fR
+.IX Subsection "perlrebackslash"
+.IP \(bu 4
+Clarify that in languages like Japanese and Thai, dictionary lookup
+is required to determine word boundaries.
+.PP
+\fIperlsub\fR
+.IX Subsection "perlsub"
+.IP \(bu 4
+Updated to note that anonymous subroutines can have signatures.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+Fixed a broken example where \f(CW\*(C`=\*(C'\fR was used instead of
+\&\f(CW\*(C`==\*(C'\fR in conditional in do/while example.
+.PP
+\fIperltie\fR
+.IX Subsection "perltie"
+.IP \(bu 4
+The usage of \f(CW\*(C`FIRSTKEY\*(C'\fR and \f(CW\*(C`NEXTKEY\*(C'\fR has been clarified.
+.PP
+\fIperlunicode\fR
+.IX Subsection "perlunicode"
+.IP \(bu 4
+Discourage use of 'In' as a prefix signifying the Unicode Block property.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+The documentation of \f(CW$@\fR was reworded to clarify that it is not just for
+syntax errors in \f(CW\*(C`eval\*(C'\fR.
+[GH #14572] <https://github.com/Perl/perl5/issues/14572>
+.IP \(bu 4
+The specific true value of \f(CW$!{E...}\fR is now documented, noting that it is
+subject to change and not guaranteed.
+.IP \(bu 4
+Use of \f(CW$OLD_PERL_VERSION\fR is now discouraged.
+.PP
+\fIperlxs\fR
+.IX Subsection "perlxs"
+.IP \(bu 4
+The documentation of \f(CW\*(C`PROTOTYPES\*(C'\fR has been corrected; they are \fIdisabled\fR
+by default, not \fIenabled\fR.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+\&\f(CW%s\fR must not be a named sequence in transliteration operator
+.IP \(bu 4
+Can't find Unicode property definition "%s" in regex;
+.IP \(bu 4
+Can't redeclare "%s" in "%s"
+.IP \(bu 4
+Character following \ep must be '{' or a single-character Unicode property name in regex;
+.IP \(bu 4
+Empty \e%c in regex; marked by <\-\- HERE in m/%s/
+.IP \(bu 4
+Illegal user-defined property name
+.IP \(bu 4
+Invalid number '%s' for \-C option.
+.IP \(bu 4
+Sequence (?... not terminated in regex; marked by <\-\-\ HERE in m/%s/
+.IP \(bu 4
+Sequence (?P<... not terminated in regex; marked by <\-\- HERE in m/%s/
+.IP \(bu 4
+Sequence (?P>... not terminated in regex; marked by <\-\- HERE in m/%s/
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Assuming NOT a POSIX class since \f(CW%s\fR in regex; marked by <\-\- HERE in m/%s/
+.IP \(bu 4
+%s() is deprecated on :utf8 handles
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Accessing the \f(CW\*(C`IO\*(C'\fR part of a glob as \f(CW\*(C`FILEHANDLE\*(C'\fR instead of \f(CW\*(C`IO\*(C'\fR is no
+longer deprecated.  It is discouraged to encourage uniformity (so that, for
+example, one can grep more easily) but it will not be removed.
+[GH #15105] <https://github.com/Perl/perl5/issues/15105>
+.IP \(bu 4
+The diagnostic \f(CW\*(C`Hexadecimal float: internal error\*(C'\fR has been changed to
+\&\f(CW\*(C`Hexadecimal float: internal error (%s)\*(C'\fR to include more information.
+.IP \(bu 4
+Can't modify non-lvalue subroutine call of &%s
+.Sp
+This error now reports the name of the non-lvalue subroutine you attempted to
+use as an lvalue.
+.IP \(bu 4
+When running out of memory during an attempt the increase the stack
+size, previously, perl would die using the cryptic message
+\&\f(CW\*(C`panic: av_extend_guts() negative count (\-9223372036854775681)\*(C'\fR.
+This has been fixed to show the prettier message:
+Out of memory during stack extend
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\f(CW\*(C`Configure\*(C'\fR now acts as if the \f(CW\*(C`\-O\*(C'\fR option is always passed, allowing command
+line options to override saved configuration.  This should eliminate confusion
+when command line options are ignored for no obvious reason.  \f(CW\*(C`\-O\*(C'\fR is now
+permitted, but ignored.
+.IP \(bu 4
+Bison 3.0 is now supported.
+.IP \(bu 4
+\&\fIConfigure\fR no longer probes for \fIlibnm\fR by default.  Originally
+this was the "New Math" library, but the name has been re-used by the
+GNOME NetworkManager.
+[GH #15115] <https://github.com/Perl/perl5/issues/15115>
+.IP \(bu 4
+Added \fIConfigure\fR probes for \f(CW\*(C`newlocale\*(C'\fR, \f(CW\*(C`freelocale\*(C'\fR, and \f(CW\*(C`uselocale\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`PPPort.so/PPPort.dll\*(C'\fR no longer get installed, as they are
+not used by \f(CW\*(C`PPPort.pm\*(C'\fR, only by its test files.
+.IP \(bu 4
+It is now possible to specify which compilation date to show on
+\&\f(CW\*(C`perl \-V\*(C'\fR output, by setting the macro \f(CW\*(C`PERL_BUILD_DATE\*(C'\fR.
+.IP \(bu 4
+Using the \f(CW\*(C`NO_HASH_SEED\*(C'\fR define in combination with the default hash algorithm
+\&\f(CW\*(C`PERL_HASH_FUNC_ONE_AT_A_TIME_HARD\*(C'\fR resulted in a fatal error while compiling
+the interpreter, since Perl 5.17.10.  This has been fixed.
+.IP \(bu 4
+\&\fIConfigure\fR should handle spaces in paths a little better.
+.IP \(bu 4
+No longer generate EBCDIC POSIX-BC tables.  We don't believe anyone is
+using Perl and POSIX-BC at this time, and by not generating these tables
+it saves time during development, and makes the resulting tar ball smaller.
+.IP \(bu 4
+The GNU Make makefile for Win32 now supports parallel builds.  [perl #126632]
+.IP \(bu 4
+You can now build perl with MSVC++ on Win32 using GNU Make.  [perl #126632]
+.IP \(bu 4
+The Win32 miniperl now has a real \f(CW\*(C`getcwd\*(C'\fR which increases build performance
+resulting in \f(CWgetcwd()\fR being 605x faster in Win32 miniperl.
+.IP \(bu 4
+Configure now takes \f(CW\*(C`\-Dusequadmath\*(C'\fR into account when calculating the
+\&\f(CW\*(C`alignbytes\*(C'\fR configuration variable.  Previously the mis-calculated
+\&\f(CW\*(C`alignbytes\*(C'\fR could cause alignment errors on debugging builds. [perl
+#127894]
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+A new test (\fIt/op/aassign.t\fR) has been added to test the list assignment operator
+\&\f(CW\*(C`OP_AASSIGN\*(C'\fR.
+.IP \(bu 4
+Parallel building has been added to the dmake \f(CW\*(C`makefile.mk\*(C'\fR makefile. All
+Win32 compilers are supported.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP AmigaOS 4
+.IX Item "AmigaOS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The AmigaOS port has been reintegrated into the main tree, based off of
+Perl 5.22.1.
+.RE
+.RS 4
+.RE
+.IP Cygwin 4
+.IX Item "Cygwin"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Tests are more robust against unusual cygdrive prefixes.
+[GH #15076] <https://github.com/Perl/perl5/issues/15076>
+.RE
+.RS 4
+.RE
+.IP EBCDIC 4
+.IX Item "EBCDIC"
+.RS 4
+.PD 0
+.IP "UTF-EBCDIC extended" 4
+.IX Item "UTF-EBCDIC extended"
+.PD
+UTF-EBCDIC is like UTF\-8, but for EBCDIC platforms.  It now has been
+extended so that it can represent code points up to 2 ** 64 \- 1 on
+platforms with 64\-bit words.  This brings it into parity with UTF\-8.
+This enhancement requires an incompatible change to the representation
+of code points in the range 2 ** 30 to 2 ** 31 \-1 (the latter was the
+previous maximum representable code point).  This means that a file that
+contains one of these code points, written out with previous versions of
+perl cannot be read in, without conversion, by a perl containing this
+change.  We do not believe any such files are in existence, but if you
+do have one, submit a ticket at perlbug@perl.org <mailto:perlbug@perl.org>,
+and we will write a conversion script for you.
+.ie n .IP "EBCDIC cmp() and sort() fixed for UTF-EBCDIC strings" 4
+.el .IP "EBCDIC \f(CWcmp()\fR and \f(CWsort()\fR fixed for UTF-EBCDIC strings" 4
+.IX Item "EBCDIC cmp() and sort() fixed for UTF-EBCDIC strings"
+Comparing two strings that were both encoded in UTF\-8 (or more
+precisely, UTF-EBCDIC) did not work properly until now.  Since \f(CWsort()\fR
+uses \f(CWcmp()\fR, this fixes that as well.
+.ie n .IP "EBCDIC ""tr///"" and ""y///"" fixed for ""\eN{}"", and ""use\ utf8"" ranges" 4
+.el .IP "EBCDIC \f(CWtr///\fR and \f(CWy///\fR fixed for \f(CW\eN{}\fR, and \f(CWuse\ utf8\fR ranges" 4
+.IX Item "EBCDIC tr/// and y/// fixed for N{}, and use utf8 ranges"
+Perl v5.22 introduced the concept of portable ranges to regular
+expression patterns.  A portable range matches the same set of
+characters no matter what platform is being run on.  This concept is now
+extended to \f(CW\*(C`tr///\*(C'\fR.  See
+\&\f(CW\*(C`tr///\*(C'\fR.
+.Sp
+There were also some problems with these operations under \f(CW\*(C`use\ utf8\*(C'\fR, which are now fixed
+.RE
+.RS 4
+.RE
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Use the \f(CWfdclose()\fR function from FreeBSD if it is available.
+[GH #15082] <https://github.com/Perl/perl5/issues/15082>
+.RE
+.RS 4
+.RE
+.IP IRIX 4
+.IX Item "IRIX"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Under some circumstances IRIX stdio \f(CWfgetc()\fR and \f(CWfread()\fR set the errno to
+\&\f(CW\*(C`ENOENT\*(C'\fR, which made no sense according to either IRIX or POSIX docs.  Errno
+is now cleared in such cases.
+[GH #14557] <https://github.com/Perl/perl5/issues/14557>
+.IP \(bu 4
+Problems when multiplying long doubles by infinity have been fixed.
+[GH #14993] <https://github.com/Perl/perl5/issues/14993>
+.RE
+.RS 4
+.RE
+.IP "MacOS X" 4
+.IX Item "MacOS X"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Until now OS X builds of perl have specified a link target of 10.3 (Panther,
+2003) but have not specified a compiler target.  From now on, builds of perl on
+OS X 10.6 or later (Snow Leopard, 2008) by default capture the current OS X
+version and specify that as the explicit build target in both compiler and
+linker flags, thus preserving binary compatibility for extensions built later
+regardless of changes in OS X, SDK, or compiler and linker versions.  To
+override the default value used in the build and preserved in the flags,
+specify \f(CW\*(C`export MACOSX_DEPLOYMENT_TARGET=10.N\*(C'\fR before configuring and building
+perl, where 10.N is the version of OS X you wish to target.  In OS X 10.5 or
+earlier there is no change to the behavior present when those systems were
+current; the link target is still OS X 10.3 and there is no explicit compiler
+target.
+.IP \(bu 4
+Builds with both \-DDEBUGGING and threading enabled would fail with a
+"panic: free from wrong pool" error when built or tested from Terminal
+on OS X.  This was caused by perl's internal management of the
+environment conflicting with an atfork handler using the libc
+\&\f(CWsetenv()\fR function to update the environment.
+.Sp
+Perl now uses \f(CWsetenv()\fR/\f(CWunsetenv()\fR to update the environment on OS X.
+[GH #14955] <https://github.com/Perl/perl5/issues/14955>
+.RE
+.RS 4
+.RE
+.IP Solaris 4
+.IX Item "Solaris"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+All Solaris variants now build a shared libperl
+.Sp
+Solaris and variants like OpenIndiana now always build with the shared
+Perl library (Configure \-Duseshrplib).  This was required for the
+OpenIndiana builds, but this has also been the setting for Oracle/Sun
+Perl builds for several years.
+.RE
+.RS 4
+.RE
+.IP Tru64 4
+.IX Item "Tru64"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Workaround where Tru64 balks when prototypes are listed as
+\&\f(CW\*(C`PERL_STATIC_INLINE\*(C'\fR, but where the test is build with
+\&\f(CW\*(C`\-DPERL_NO_INLINE_FUNCTIONS\*(C'\fR.
+.RE
+.RS 4
+.RE
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+On VMS, the math function prototypes in \f(CW\*(C`math.h\*(C'\fR are now visible under C++.
+Now building the POSIX extension with C++ will no longer crash.
+.IP \(bu 4
+VMS has had \f(CW\*(C`setenv\*(C'\fR/\f(CW\*(C`unsetenv\*(C'\fR since v7.0 (released in 1996),
+\&\f(CW\*(C`Perl_vmssetenv\*(C'\fR now always uses \f(CW\*(C`setenv\*(C'\fR/\f(CW\*(C`unsetenv\*(C'\fR.
+.IP \(bu 4
+Perl now implements its own \f(CW\*(C`killpg\*(C'\fR by scanning for processes in the
+specified process group, which may not mean exactly the same thing as a Unix
+process group, but allows us to send a signal to a parent (or master) process
+and all of its sub-processes.  At the perl level, this means we can now send a
+negative pid like so:
+.Sp
+.Vb 1
+\&    kill SIGKILL, \-$pid;
+.Ve
+.Sp
+to signal all processes in the same group as \f(CW$pid\fR.
+.IP \(bu 4
+For those \f(CW%ENV\fR elements based on the CRTL environ array, we've always
+preserved case when setting them but did look-ups only after upcasing the
+key first, which made lower\- or mixed-case entries go missing. This problem
+has been corrected by making \f(CW%ENV\fR elements derived from the environ array
+case-sensitive on look-up as well as case-preserving on store.
+.IP \(bu 4
+Environment look-ups for \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`PERLLIB\*(C'\fR previously only
+considered logical names, but now consider all sources of \f(CW%ENV\fR as
+determined by \f(CW\*(C`PERL_ENV_TABLES\*(C'\fR and as documented in "%ENV" in perlvms.
+.IP \(bu 4
+The minimum supported version of VMS is now v7.3\-2, released in 2003.  As a
+side effect of this change, VAX is no longer supported as the terminal
+release of OpenVMS VAX was v7.3 in 2001.
+.RE
+.RS 4
+.RE
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+A new build option \f(CW\*(C`USE_NO_REGISTRY\*(C'\fR has been added to the makefiles.  This
+option is off by default, meaning the default is to do Windows registry
+lookups.  This option stops Perl from looking inside the registry for anything.
+For what values are looked up in the registry see perlwin32.  Internally, in
+C, the name of this option is \f(CW\*(C`WIN32_NO_REGISTRY\*(C'\fR.
+.IP \(bu 4
+The behavior of Perl using \f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR and
+\&\f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR to lookup certain values, including \f(CW%ENV\fR
+vars starting with \f(CW\*(C`PERL\*(C'\fR has changed.  Previously, the 2 keys were checked
+for entries at all times through the perl process's life time even if
+they did not
+exist.  For performance reasons, now, if the root key (i.e.
+\&\f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR or \f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR) does
+not exist at process start time, it will not be checked again for \f(CW%ENV\fR
+override entries for the remainder of the perl process's life.  This more
+closely matches Unix behavior in that the environment is copied or inherited
+on startup and changing the variable in the parent process or another process
+or editing \fI.bashrc\fR will not change the environmental variable in other
+existing, running, processes.
+.IP \(bu 4
+One glob fetch was removed for each \f(CW\*(C`\-X\*(C'\fR or \f(CW\*(C`stat\*(C'\fR call whether done from
+Perl code or internally from Perl's C code.  The glob being looked up was
+\&\f(CW\*(C`${^WIN32_SLOPPY_STAT}\*(C'\fR which is a special variable.  This makes \f(CW\*(C`\-X\*(C'\fR and
+\&\f(CW\*(C`stat\*(C'\fR slightly faster.
+.IP \(bu 4
+During miniperl's process startup, during the build process, 4 to 8 IO calls
+related to the process starting \fI.pl\fR and the \fIbuildcustomize.pl\fR file were
+removed from the code opening and executing the first 1 or 2 \fI.pl\fR files.
+.IP \(bu 4
+Builds using Microsoft Visual C++ 2003 and earlier no longer produce
+an "INTERNAL COMPILER ERROR" message.  [perl #126045]
+.IP \(bu 4
+Visual C++ 2013 builds will now execute on XP and higher. Previously they would
+only execute on Vista and higher.
+.IP \(bu 4
+You can now build perl with GNU Make and GCC.  [perl #123440]
+.IP \(bu 4
+\&\f(CW\*(C`truncate($filename, $size)\*(C'\fR now works for files over 4GB in size.
+[perl #125347]
+.IP \(bu 4
+Parallel building has been added to the dmake \f(CW\*(C`makefile.mk\*(C'\fR makefile. All
+Win32 compilers are supported.
+.IP \(bu 4
+Building a 64\-bit perl with a 64\-bit GCC but a 32\-bit gmake would
+result in an invalid \f(CW$Config{archname}\fR for the resulting perl.
+[perl #127584]
+.IP \(bu 4
+Errors set by Winsock functions are now put directly into \f(CW$^E\fR, and the
+relevant \f(CW\*(C`WSAE*\*(C'\fR error codes are now exported from the Errno and POSIX
+modules for testing this against.
+.Sp
+The previous behavior of putting the errors (converted to POSIX-style \f(CW\*(C`E*\*(C'\fR
+error codes since Perl 5.20.0) into \f(CW$!\fR was buggy due to the non-equivalence
+of like-named Winsock and POSIX error constants, a relationship between which
+has unfortunately been established in one way or another since Perl 5.8.0.
+.Sp
+The new behavior provides a much more robust solution for checking Winsock
+errors in portable software without accidentally matching POSIX tests that were
+intended for other OSes and may have different meanings for Winsock.
+.Sp
+The old behavior is currently retained, warts and all, for backwards
+compatibility, but users are encouraged to change any code that tests \f(CW$!\fR
+against \f(CW\*(C`E*\*(C'\fR constants for Winsock errors to instead test \f(CW$^E\fR against
+\&\f(CW\*(C`WSAE*\*(C'\fR constants.  After a suitable deprecation period, the old behavior may
+be removed, leaving \f(CW$!\fR unchanged after Winsock function calls, to avoid any
+possible confusion over which error variable to check.
+.RE
+.RS 4
+.RE
+.IP ppc64el 4
+.IX Item "ppc64el"
+.RS 4
+.PD 0
+.IP "floating point" 4
+.IX Item "floating point"
+.PD
+The floating point format of ppc64el (Debian naming for little-endian
+PowerPC) is now detected correctly.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+The implementation of perl's context stack system, and its internal API,
+have been heavily reworked. Note that no significant changes have been
+made to any external APIs, but XS code which relies on such internal
+details may need to be fixed. The main changes are:
+.RS 4
+.IP \(bu 4
+The \f(CWPUSHBLOCK()\fR, \f(CWPOPSUB()\fR etc. macros have been replaced with static
+inline functions such as \f(CWcx_pushblock()\fR, \f(CWcx_popsub()\fR etc. These use
+function args rather than implicitly relying on local vars such as
+\&\f(CW\*(C`gimme\*(C'\fR and \f(CW\*(C`newsp\*(C'\fR being available. Also their functionality has
+changed: in particular, \f(CWcx_popblock()\fR no longer decrements
+\&\f(CW\*(C`cxstack_ix\*(C'\fR. The ordering of the steps in the \f(CW\*(C`pp_leave*\*(C'\fR functions
+involving \f(CWcx_popblock()\fR, \f(CWcx_popsub()\fR etc. has changed. See the new
+documentation, "Dynamic Scope and the Context Stack" in perlguts, for
+details on how to use them.
+.IP \(bu 4
+Various macros, which now consistently have a CX_ prefix, have been added:
+.Sp
+.Vb 1
+\&  CX_CUR(), CX_LEAVE_SCOPE(), CX_POP()
+.Ve
+.Sp
+or renamed:
+.Sp
+.Vb 1
+\&  CX_POP_SAVEARRAY(), CX_DEBUG(), CX_PUSHSUBST(), CX_POPSUBST()
+.Ve
+.IP \(bu 4
+\&\f(CWcx_pushblock()\fR now saves \f(CW\*(C`PL_savestack_ix\*(C'\fR and \f(CW\*(C`PL_tmps_floor\*(C'\fR, so
+\&\f(CW\*(C`pp_enter*\*(C'\fR and \f(CW\*(C`pp_leave*\*(C'\fR no longer do
+.Sp
+.Vb 1
+\&  ENTER; SAVETMPS; ....; LEAVE
+.Ve
+.IP \(bu 4
+\&\f(CWcx_popblock()\fR now also restores \f(CW\*(C`PL_curpm\*(C'\fR.
+.IP \(bu 4
+In \f(CWdounwind()\fR for every context type, the current savestack frame is
+now processed before each context is popped; formerly this was only done
+for sub-like context frames. This action has been removed from
+\&\f(CWcx_popsub()\fR and placed into its own macro, \f(CWCX_LEAVE_SCOPE(cx)\fR, which
+must be called before \f(CWcx_popsub()\fR etc.
+.Sp
+\&\f(CWdounwind()\fR now also does a \f(CWcx_popblock()\fR on the last popped frame
+(formerly it only did the \f(CWcx_popsub()\fR etc. actions on each frame).
+.IP \(bu 4
+The temps stack is now freed on scope exit; previously, temps created
+during the last statement of a block wouldn't be freed until the next
+\&\f(CW\*(C`nextstate\*(C'\fR following the block (apart from an existing hack that did
+this for recursive subs in scalar context); and in something like
+\&\f(CW\*(C`f(g())\*(C'\fR, the temps created by the last statement in \f(CWg()\fR would
+formerly not be freed until the statement following the return from
+\&\f(CWf()\fR.
+.IP \(bu 4
+Most values that were saved on the savestack on scope entry are now
+saved in suitable new fields in the context struct, and saved and
+restored directly by \f(CWcx_pushfoo()\fR and \f(CWcx_popfoo()\fR, which is much
+faster.
+.IP \(bu 4
+Various context struct fields have been added, removed or modified.
+.IP \(bu 4
+The handling of \f(CW@_\fR in \f(CWcx_pushsub()\fR and \f(CWcx_popsub()\fR has been
+considerably tidied up, including removing the \f(CW\*(C`argarray\*(C'\fR field from the
+context struct, and extracting out some common (but rarely used) code into
+a separate function, \f(CWclear_defarray()\fR. Also, useful subsets of
+\&\f(CWcx_popsub()\fR which had been unrolled in places like \f(CW\*(C`pp_goto\*(C'\fR have been
+gathered into the new functions \f(CWcx_popsub_args()\fR and
+\&\f(CWcx_popsub_common()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`pp_leavesub\*(C'\fR and \f(CW\*(C`pp_leavesublv\*(C'\fR now use the same function as the rest
+of the \f(CW\*(C`pp_leave*\*(C'\fR's to process return args.
+.IP \(bu 4
+\&\f(CW\*(C`CXp_FOR_PAD\*(C'\fR and \f(CW\*(C`CXp_FOR_GV\*(C'\fR flags have been added, and
+\&\f(CW\*(C`CXt_LOOP_FOR\*(C'\fR has been split into \f(CW\*(C`CXt_LOOP_LIST\*(C'\fR, \f(CW\*(C`CXt_LOOP_ARY\*(C'\fR.
+.IP \(bu 4
+Some variables formerly declared by \f(CW\*(C`dMULTICALL\*(C'\fR (but not documented) have
+been removed.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+The obscure \f(CW\*(C`PL_timesbuf\*(C'\fR variable, effectively a vestige of Perl 1, has
+been removed. It was documented as deprecated in Perl 5.20, with a statement
+that it would be removed early in the 5.21.x series; that has now finally
+happened.
+[GH #13632] <https://github.com/Perl/perl5/issues/13632>
+.IP \(bu 4
+An unwarranted assertion in \f(CWPerl_newATTRSUB_x()\fR has been removed.  If
+a stub subroutine
+definition with a prototype has been seen, then any subsequent stub (or
+definition) of the same subroutine with an attribute was causing an assertion
+failure because of a null pointer.
+[GH #15081] <https://github.com/Perl/perl5/issues/15081>
+.IP \(bu 4
+\&\f(CW\*(C`::\*(C'\fR has been replaced by \f(CW\*(C`_\|_\*(C'\fR in \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR, like it's done for
+parameters/return values. This is more consistent, and simplifies writing XS
+code wrapping C++ classes into a nested Perl namespace (it requires only
+a typedef for \f(CW\*(C`Foo_\|_Bar\*(C'\fR rather than two, one for \f(CW\*(C`Foo_Bar\*(C'\fR and the other
+for \f(CW\*(C`Foo::Bar\*(C'\fR).
+.IP \(bu 4
+The \f(CWto_utf8_case()\fR function is now deprecated.  Instead use
+\&\f(CW\*(C`toUPPER_utf8\*(C'\fR, \f(CW\*(C`toTITLE_utf8\*(C'\fR, \f(CW\*(C`toLOWER_utf8\*(C'\fR, and \f(CW\*(C`toFOLD_utf8\*(C'\fR.
+(See <http://nntp.perl.org/group/perl.perl5.porters/233287>.)
+.IP \(bu 4
+Perl core code and the threads extension have been annotated so that,
+if Perl is configured to use threads, then during compile-time clang (3.6
+or later) will warn about suspicious uses of mutexes.
+See <http://clang.llvm.org/docs/ThreadSafetyAnalysis.html> for more
+information.
+.IP \(bu 4
+The \f(CWsignbit()\fR emulation has been enhanced.  This will help older
+and/or more exotic platforms or configurations.
+.IP \(bu 4
+Most EBCDIC-specific code in the core has been unified with non-EBCDIC
+code, to avoid repetition and make maintenance easier.
+.IP \(bu 4
+MSWin32 code for \f(CW$^X\fR has been moved out of the \fIwin32\fR directory to
+\&\fIcaretx.c\fR, where other operating systems set that variable.
+.IP \(bu 4
+\&\f(CWsv_ref()\fR is now part of the API.
+.IP \(bu 4
+"sv_backoff" in perlapi had its return type changed from \f(CW\*(C`int\*(C'\fR to \f(CW\*(C`void\*(C'\fR.  It
+previously has always returned \f(CW0\fR since Perl 5.000 stable but that was
+undocumented.  Although \f(CW\*(C`sv_backoff\*(C'\fR is marked as public API, XS code is not
+expected to be impacted since the proper API call would be through public API
+\&\f(CW\*(C`sv_setsv(sv, &PL_sv_undef)\*(C'\fR, or quasi-public \f(CW\*(C`SvOOK_off\*(C'\fR, or non-public
+\&\f(CW\*(C`SvOK_off\*(C'\fR calls, and the return value of \f(CW\*(C`sv_backoff\*(C'\fR was previously a
+meaningless constant that can be rewritten as \f(CW\*(C`(sv_backoff(sv),0)\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`EXTEND\*(C'\fR and \f(CW\*(C`MEXTEND\*(C'\fR macros have been improved to avoid various issues
+with integer truncation and wrapping.  In particular, some casts formerly used
+within the macros have been removed.  This means for example that passing an
+unsigned \f(CW\*(C`nitems\*(C'\fR argument is likely to raise a compiler warning now
+(it's always been documented to require a signed value; formerly int,
+lately SSize_t).
+.IP \(bu 4
+\&\f(CW\*(C`PL_sawalias\*(C'\fR and \f(CW\*(C`GPf_ALIASED_SV\*(C'\fR have been removed.
+.IP \(bu 4
+\&\f(CW\*(C`GvASSIGN_GENERATION\*(C'\fR and \f(CW\*(C`GvASSIGN_GENERATION_set\*(C'\fR have been removed.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+It now works properly to specify a user-defined property, such as
+.Sp
+.Vb 1
+\& qr/\ep{mypkg1::IsMyProperty}/i
+.Ve
+.Sp
+with \f(CW\*(C`/i\*(C'\fR caseless matching, an explicit package name, and
+\&\fIIsMyProperty\fR not defined at the time of the pattern compilation.
+.IP \(bu 4
+Perl's \f(CWmemcpy()\fR, \f(CWmemmove()\fR, \f(CWmemset()\fR and \f(CWmemcmp()\fR fallbacks are now
+more compatible with the originals.  [perl #127619]
+.IP \(bu 4
+Fixed the issue where a \f(CW\*(C`s///r\*(C'\fR) with \fB\-DPERL_NO_COW\fR attempts
+to modify the source SV, resulting in the program dying. [perl #127635]
+.IP \(bu 4
+Fixed an EBCDIC-platform-only case where a pattern could fail to match. This
+occurred when matching characters from the set of C1 controls when the
+target matched string was in UTF\-8.
+.IP \(bu 4
+Narrow the filename check in \fIstrict.pm\fR and \fIwarnings.pm\fR. Previously,
+it assumed that if the filename (without the \fI.pmc?\fR extension) differed
+from the package name, if was a misspelled use statement (i.e. \f(CW\*(C`use Strict\*(C'\fR
+instead of \f(CW\*(C`use strict\*(C'\fR). We now check whether there's really a
+miscapitalization happening, and not some other issue.
+.IP \(bu 4
+Turn an assertion into a more user friendly failure when parsing
+regexes. [perl #127599]
+.IP \(bu 4
+Correctly raise an error when trying to compile patterns with
+unterminated character classes while there are trailing backslashes.
+[perl #126141].
+.IP \(bu 4
+Line numbers larger than 2**31\-1 but less than 2**32 are no longer
+returned by \f(CWcaller()\fR as negative numbers.  [perl #126991]
+.IP \(bu 4
+\&\f(CW\*(C`unless ( \fR\f(CIassignment\fR\f(CW )\*(C'\fR now properly warns when syntax
+warnings are enabled.  [perl #127122]
+.IP \(bu 4
+Setting an \f(CW\*(C`ISA\*(C'\fR glob to an array reference now properly adds
+\&\f(CW\*(C`isaelem\*(C'\fR magic to any existing elements.  Previously modifying such
+an element would not update the ISA cache, so method calls would call
+the wrong function.  Perl would also crash if the \f(CW\*(C`ISA\*(C'\fR glob was
+destroyed, since new code added in 5.23.7 would try to release the
+\&\f(CW\*(C`isaelem\*(C'\fR magic from the elements.  [perl #127351]
+.IP \(bu 4
+If a here-doc was found while parsing another operator, the parser had
+already read end of file, and the here-doc was not terminated, perl
+could produce an assertion or a segmentation fault.  This now reliably
+complains about the unterminated here-doc.  [perl #125540]
+.IP \(bu 4
+\&\f(CWuntie()\fR would sometimes return the last value returned by the \f(CWUNTIE()\fR
+handler as well as its normal value, messing up the stack.  [perl
+#126621]
+.IP \(bu 4
+Fixed an operator precedence problem when \f(CW\*(C` castflags & 2\*(C'\fR is true.
+[perl #127474]
+.IP \(bu 4
+Caching of DESTROY methods could result in a non-pointer or a
+non-STASH stored in the \f(CWSvSTASH()\fR slot of a stash, breaking the B
+\&\f(CWSTASH()\fR method.  The DESTROY method is now cached in the MRO metadata
+for the stash.  [perl #126410]
+.IP \(bu 4
+The AUTOLOAD method is now called when searching for a DESTROY method,
+and correctly sets \f(CW$AUTOLOAD\fR too.  [perl #124387]  [perl #127494]
+.IP \(bu 4
+Avoid parsing beyond the end of the buffer when processing a \f(CW\*(C`#line\*(C'\fR
+directive with no filename.  [perl #127334]
+.IP \(bu 4
+Perl now raises a warning when a regular expression pattern looks like
+it was supposed to contain a POSIX class, like \f(CW\*(C`qr/[[:alpha:]]/\*(C'\fR, but
+there was some slight defect in its specification which causes it to
+instead be treated as a regular bracketed character class.  An example
+would be missing the second colon in the above like this:
+\&\f(CW\*(C`qr/[[:alpha]]/\*(C'\fR.  This compiles to match a sequence of two characters.
+The second is \f(CW"]"\fR, and the first is any of: \f(CW"["\fR, \f(CW":"\fR, \f(CW"a"\fR,
+\&\f(CW"h"\fR, \f(CW"l"\fR, or \f(CW"p"\fR.   This is unlikely to be the intended
+meaning, and now a warning is raised.  No warning is raised unless the
+specification is very close to one of the 14 legal POSIX classes.  (See
+"POSIX Character Classes" in perlrecharclass.)
+[perl #8904]
+.IP \(bu 4
+Certain regex patterns involving a complemented POSIX class in an
+inverted bracketed character class, and matching something else
+optionally would improperly fail to match.  An example of one that could
+fail is \f(CW\*(C`qr/_?[^\eWbar]\ex{100}/\*(C'\fR.  This has been fixed.
+[perl #127537]
+.IP \(bu 4
+Perl 5.22 added support to the C99 hexadecimal floating point notation,
+but sometimes misparses hex floats. This has been fixed.
+[perl #127183]
+.IP \(bu 4
+A regression that allowed undeclared barewords in hash keys to work despite
+strictures has been fixed.
+[GH #15099] <https://github.com/Perl/perl5/issues/15099>
+.IP \(bu 4
+Calls to the placeholder \f(CW&PL_sv_yes\fR used internally when an \f(CWimport()\fR
+or \f(CWunimport()\fR method isn't found now correctly handle scalar context.
+[GH #14902] <https://github.com/Perl/perl5/issues/14902>
+.IP \(bu 4
+Report more context when we see an array where we expect to see an
+operator and avoid an assertion failure.
+[GH #14472] <https://github.com/Perl/perl5/issues/14472>
+.IP \(bu 4
+Modifying an array that was previously a package \f(CW@ISA\fR no longer
+causes assertion failures or crashes.
+[GH #14492] <https://github.com/Perl/perl5/issues/14492>
+.IP \(bu 4
+Retain binary compatibility across plain and DEBUGGING perl builds.
+[GH #15122] <https://github.com/Perl/perl5/issues/15122>
+.IP \(bu 4
+Avoid leaking memory when setting \f(CW$ENV{foo}\fR on darwin.
+[GH #14955] <https://github.com/Perl/perl5/issues/14955>
+.IP \(bu 4
+\&\f(CW\*(C`/...\eG/\*(C'\fR no longer crashes on utf8 strings. When \f(CW\*(C`\eG\*(C'\fR is a fixed number
+of characters from the start of the regex, perl needs to count back that
+many characters from the current \f(CWpos()\fR position and start matching from
+there. However, it was counting back bytes rather than characters, which
+could lead to panics on utf8 strings.
+.IP \(bu 4
+In some cases operators that return integers would return negative
+integers as large positive integers.
+[GH #15049] <https://github.com/Perl/perl5/issues/15049>
+.IP \(bu 4
+The \f(CWpipe()\fR operator would assert for DEBUGGING builds instead of
+producing the correct error message.  The condition asserted on is
+detected and reported on correctly without the assertions, so the
+assertions were removed.
+[GH #15015] <https://github.com/Perl/perl5/issues/15015>
+.IP \(bu 4
+In some cases, failing to parse a here-doc would attempt to use freed
+memory.  This was caused by a pointer not being restored correctly.
+[GH #15009] <https://github.com/Perl/perl5/issues/15009>
+.IP \(bu 4
+\&\f(CW\*(C`@x = sort { *a = 0; $a <=> $b } 0 .. 1\*(C'\fR no longer frees the GP
+for *a before restoring its SV slot.
+[GH #14595] <https://github.com/Perl/perl5/issues/14595>
+.IP \(bu 4
+Multiple problems with the new hexadecimal floating point printf
+format \f(CW%a\fR were fixed:
+[GH #15032] <https://github.com/Perl/perl5/issues/15032>,
+[GH #15033] <https://github.com/Perl/perl5/issues/15033>,
+[GH #15074] <https://github.com/Perl/perl5/issues/15074>
+.IP \(bu 4
+Calling \f(CWmg_set()\fR in \f(CWleave_scope()\fR no longer leaks.
+.IP \(bu 4
+A regression from Perl v5.20 was fixed in which debugging output of regular
+expression compilation was wrong.  (The pattern was correctly compiled, but
+what got displayed for it was wrong.)
+.IP \(bu 4
+\&\f(CW\*(C`\eb{sb}\*(C'\fR works much better.  In Perl v5.22.0, this new construct didn't
+seem to give the expected results, yet passed all the tests in the
+extensive suite furnished by Unicode.  It turns out that it was because
+these were short input strings, and the failures had to do with longer
+inputs.
+.IP \(bu 4
+Certain syntax errors in
+"Extended Bracketed Character Classes" in perlrecharclass caused panics
+instead of the proper error message.  This has now been fixed. [perl
+#126481]
+.IP \(bu 4
+Perl 5.20 added a message when a quantifier in a regular
+expression was useless, but then caused the parser to skip it;
+this caused the surplus quantifier to be silently ignored, instead
+of throwing an error. This is now fixed. [perl #126253]
+.IP \(bu 4
+The switch to building non-XS modules last in win32/makefile.mk (introduced
+by design as part of the changes to enable parallel building) caused the
+build of POSIX to break due to problems with the version module. This
+is now fixed.
+.IP \(bu 4
+Improved parsing of hex float constants.
+.IP \(bu 4
+Fixed an issue with \f(CW\*(C`pack\*(C'\fR where \f(CW\*(C`pack "H"\*(C'\fR (and \f(CW\*(C`pack "h"\*(C'\fR)
+could read past the source when given a non\-utf8 source, and a utf8 target.
+[perl #126325]
+.IP \(bu 4
+Fixed several cases where perl would abort due to a segmentation fault,
+or a C\-level assert. [perl #126615], [perl #126602], [perl #126193].
+.IP \(bu 4
+There were places in regular expression patterns where comments (\f(CW\*(C`(?#...)\*(C'\fR)
+weren't allowed, but should have been.  This is now fixed.
+[GH #12755] <https://github.com/Perl/perl5/issues/12755>
+.IP \(bu 4
+Some regressions from Perl 5.20 have been fixed, in which some syntax errors in
+\&\f(CW\*(C`(?[...])\*(C'\fR constructs
+within regular expression patterns could cause a segfault instead of a proper
+error message.
+[GH #14933] <https://github.com/Perl/perl5/issues/14933>
+[GH #14996] <https://github.com/Perl/perl5/issues/14996>
+.IP \(bu 4
+Another problem with
+\&\f(CW\*(C`(?[...])\*(C'\fR
+constructs has been fixed wherein things like \f(CW\*(C`\ec]\*(C'\fR could cause panics.
+[GH #14934] <https://github.com/Perl/perl5/issues/14934>
+.IP \(bu 4
+Some problems with attempting to extend the perl stack to around 2G or 4G
+entries have been fixed.  This was particularly an issue on 32\-bit perls built
+to use 64\-bit integers, and was easily noticeable with the list repetition
+operator, e.g.
+.Sp
+.Vb 1
+\&    @a = (1) x $big_number
+.Ve
+.Sp
+Formerly perl may have crashed, depending on the exact value of \f(CW$big_number\fR;
+now it will typically raise an exception.
+[GH #14880] <https://github.com/Perl/perl5/issues/14880>
+.IP \(bu 4
+In a regex conditional expression \f(CW\*(C`(?(condition)yes\-pattern|no\-pattern)\*(C'\fR, if
+the condition is \f(CW\*(C`(?!)\*(C'\fR then perl failed the match outright instead of
+matching the no-pattern.  This has been fixed.
+[GH #14947] <https://github.com/Perl/perl5/issues/14947>
+.IP \(bu 4
+The special backtracking control verbs \f(CW\*(C`(*VERB:ARG)\*(C'\fR now all allow an optional
+argument and set \f(CW\*(C`REGERROR\*(C'\fR/\f(CW\*(C`REGMARK\*(C'\fR appropriately as well.
+[GH #14937] <https://github.com/Perl/perl5/issues/14937>
+.IP \(bu 4
+Several bugs, including a segmentation fault, have been fixed with the boundary
+checking constructs (introduced in Perl 5.22) \f(CW\*(C`\eb{gcb}\*(C'\fR, \f(CW\*(C`\eb{sb}\*(C'\fR, \f(CW\*(C`\eb{wb}\*(C'\fR,
+\&\f(CW\*(C`\eB{gcb}\*(C'\fR, \f(CW\*(C`\eB{sb}\*(C'\fR, and \f(CW\*(C`\eB{wb}\*(C'\fR.  All the \f(CW\*(C`\eB{}\*(C'\fR ones now match an empty
+string; none of the \f(CW\*(C`\eb{}\*(C'\fR ones do.
+[GH #14976] <https://github.com/Perl/perl5/issues/14976>
+.IP \(bu 4
+Duplicating a closed file handle for write no longer creates a
+filename of the form \fIGLOB(0xXXXXXXXX)\fR.  [perl #125115]
+.IP \(bu 4
+Warning fatality is now ignored when rewinding the stack.  This
+prevents infinite recursion when the now fatal error also causes
+rewinding of the stack.  [perl #123398]
+.IP \(bu 4
+In perl v5.22.0, the logic changed when parsing a numeric parameter to the \-C
+option, such that the successfully parsed number was not saved as the option
+value if it parsed to the end of the argument.  [perl #125381]
+.IP \(bu 4
+The PadlistNAMES macro is an lvalue again.
+.IP \(bu 4
+Zero \-DPERL_TRACE_OPS memory for sub-threads.
+.Sp
+\&\f(CWperl_clone_using()\fR was missing Zero init of PL_op_exec_cnt[].  This
+caused sub-threads in threaded \-DPERL_TRACE_OPS builds to spew exceedingly
+large op-counts at destruct.  These counts would print \f(CW%x\fR as "ABABABAB",
+clearly a mem-poison value.
+.IP \(bu 4
+A leak in the XS typemap caused one scalar to be leaked each time a \f(CW\*(C`FILE *\*(C'\fR
+or a \f(CW\*(C`PerlIO *\*(C'\fR was \f(CW\*(C`OUTPUT:\*(C'\fRed or imported to Perl, since perl 5.000. These
+particular typemap entries are thought to be extremely rarely used by XS
+modules. [perl #124181]
+.IP \(bu 4
+\&\f(CWalarm()\fR and \f(CWsleep()\fR will now warn if the argument is a negative number
+and return undef. Previously they would pass the negative value to the
+underlying C function which may have set up a timer with a surprising value.
+.IP \(bu 4
+Perl can again be compiled with any Unicode version.  This used to
+(mostly) work, but was lost in v5.18 through v5.20.  The property
+\&\f(CW\*(C`Name_Alias\*(C'\fR did not exist prior to Unicode 5.0.  Unicode::UCD
+incorrectly said it did.  This has been fixed.
+.IP \(bu 4
+Very large code-points (beyond Unicode) in regular expressions no
+longer cause a buffer overflow in some cases when converted to UTF\-8.
+[GH #14858] <https://github.com/Perl/perl5/issues/14858>
+.IP \(bu 4
+The integer overflow check for the range operator (...) in list
+context now correctly handles the case where the size of the range is
+larger than the address space.  This could happen on 32\-bits with
+\&\-Duse64bitint.
+[GH #14843] <https://github.com/Perl/perl5/issues/14843>
+.IP \(bu 4
+A crash with \f(CW\*(C`%::=(); J\->${\e"::"}\*(C'\fR has been fixed.
+[GH #14790] <https://github.com/Perl/perl5/issues/14790>
+.IP \(bu 4
+\&\f(CW\*(C`qr/(?[ () ])/\*(C'\fR no longer segfaults, giving a syntax error message instead.
+[perl #125805]
+.IP \(bu 4
+Regular expression possessive quantifier v5.20 regression now fixed.
+\&\f(CW\*(C`qr/\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`}+\*(C'\fR\f(CW\*(C`/\*(C'\fR is supposed to behave identically
+to \f(CW\*(C`qr/(?>\*(C'\fR\fIPAT\fR\f(CW\*(C`{\*(C'\fR\fImin\fR,\fImax\fR\f(CW\*(C`})/\*(C'\fR.  Since v5.20, this didn't
+work if \fImin\fR and \fImax\fR were equal.  [perl #125825]
+.IP \(bu 4
+\&\f(CW\*(C`BEGIN <>\*(C'\fR no longer segfaults and properly produces an error
+message.  [perl #125341]
+.IP \(bu 4
+In \f(CW\*(C`tr///\*(C'\fR an illegal backwards range like \f(CW\*(C`tr/\ex{101}\-\ex{100}//\*(C'\fR was
+not always detected, giving incorrect results.  This is now fixed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.24.0 represents approximately 11 months of development since Perl 5.24.0
+and contains approximately 360,000 lines of changes across 1,800 files from 75
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 250,000 lines of changes to 1,200 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.24.0:
+.PP
+Aaron Crane, Aaron Priven, Abigail, Achim Gratz, Alexander D'Archangel, Alex
+Vandiver, Andreas König, Andy Broad, Andy Dougherty, Aristotle Pagaltzis,
+Chase Whitener, Chas. Owens, Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn
+Ilmari Mannsåker, Dan Collins, Daniel Dragan, David Golden, David Mitchell,
+Doug Bell, Dr.Ruud, Ed Avis, Ed J, Father Chrysostomos, Herbert Breunung,
+H.Merijn Brand, Hugo van der Sanden, Ivan Pozdeev, James E Keenan, Jan Dubois,
+Jarkko Hietaniemi, Jerry D. Hedden, Jim Cromie, John Peacock, John SJ Anderson,
+Karen Etheridge, Karl Williamson, kmx, Leon Timmermans, Ludovic E. R.
+Tolhurst-Cleaver, Lukas Mai, Martijn Lievaart, Matthew Horsfall, Mattia Barbon,
+Max Maischein, Mohammed El-Afifi, Nicholas Clark, Nicolas R., Niko Tyni, Peter
+John Acklam, Peter Martini, Peter Rabbitson, Pip Cet, Rafael Garcia-Suarez,
+Reini Urban, Ricardo Signes, Sawyer X, Shlomi Fish, Sisyphus, Stanislaw Pusep,
+Steffen Müller, Stevan Little, Steve Hay, Sullivan Beck, Thomas Sibley, Todd
+Rinaldo, Tom Hukins, Tony Cook, Unicode Consortium, Victor Adam, Vincent Pit,
+Vladimir Timofeev, Yves Orton, Zachary Storer, Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5241delta.1 b/upstream/mageia-cauldron/man1/perl5241delta.1
new file mode 100644
index 00000000..d444aaf4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5241delta.1
@@ -0,0 +1,285 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5241DELTA 1"
+.TH PERL5241DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5241delta \- what is new for perl v5.24.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.24.0 release and the 5.24.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.22.0, first read
+perl5240delta, which describes differences between 5.22.0 and 5.24.0.
+.SH Security
+.IX Header "Security"
+.SS "\fB\-Di\fP switch is now required for PerlIO debugging output"
+.IX Subsection "-Di switch is now required for PerlIO debugging output"
+Previously PerlIO debugging output would be sent to the file specified by the
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable if perl wasn't running setuid and the
+\&\fB\-T\fR or \fB\-t\fR switches hadn't been parsed yet.
+.PP
+If perl performed output at a point where it hadn't yet parsed its switches
+this could result in perl creating or overwriting the file named by
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR even when the \fB\-T\fR switch had been supplied.
+.PP
+Perl now requires the \fB\-Di\fR switch to produce PerlIO debugging output.  By
+default this is written to \f(CW\*(C`stderr\*(C'\fR, but can optionally be redirected to a
+file by setting the \f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable.
+.PP
+If perl is running setuid or the \fB\-T\fR switch was supplied \f(CW\*(C`PERLIO_DEBUG\*(C'\fR is
+ignored and the debugging output is sent to \f(CW\*(C`stderr\*(C'\fR as for any other \fB\-D\fR
+switch.
+.SS "Core modules and tools no longer search \fI"".""\fP for optional modules"
+.IX Subsection "Core modules and tools no longer search ""."" for optional modules"
+The tools and many modules supplied in core no longer search the default
+current directory entry in \f(CW@INC\fR for optional modules.  For
+example, Storable will remove the final \fI"."\fR from \f(CW@INC\fR before trying to
+load Log::Agent.
+.PP
+This prevents an attacker injecting an optional module into a process run by
+another user where the current directory is writable by the attacker, e.g. the
+\&\fI/tmp\fR directory.
+.PP
+In most cases this removal should not cause problems, but difficulties were
+encountered with base, which treats every module name supplied as optional.
+These difficulties have not yet been resolved, so for this release there are no
+changes to base.  We hope to have a fix for base in Perl 5.24.2.
+.PP
+To protect your own code from this attack, either remove the default \fI"."\fR
+entry from \f(CW@INC\fR at the start of your script, so:
+.PP
+.Vb 3
+\&  #!/usr/bin/perl
+\&  use strict;
+\&  ...
+.Ve
+.PP
+becomes:
+.PP
+.Vb 4
+\&  #!/usr/bin/perl
+\&  BEGIN { pop @INC if $INC[\-1] eq \*(Aq.\*(Aq }
+\&  use strict;
+\&  ...
+.Ve
+.PP
+or for modules, remove \fI"."\fR from a localized \f(CW@INC\fR, so:
+.PP
+.Vb 1
+\&  my $can_foo = eval { require Foo; }
+.Ve
+.PP
+becomes:
+.PP
+.Vb 5
+\&  my $can_foo = eval {
+\&      local @INC = @INC;
+\&      pop @INC if $INC[\-1] eq \*(Aq.\*(Aq;
+\&      require Foo;
+\&  };
+.Ve
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+Other than the security changes above there are no changes intentionally
+incompatible with Perl 5.24.0.  If any exist, they are bugs, and we request
+that you submit a report.  See "Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.04 to 2.04_01.
+.IP \(bu 4
+bignum has been upgraded from version 0.42 to 0.42_01.
+.IP \(bu 4
+CPAN has been upgraded from version 2.11 to 2.11_01.
+.IP \(bu 4
+Digest has been upgraded from version 1.17 to 1.17_01.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.95 to 5.95_01.
+.IP \(bu 4
+Encode has been upgraded from version 2.80 to 2.80_01.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.10_01 to 7.10_02.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.48 to 0.48_01.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.63 to 3.63_01.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.056 to 0.056_001.
+.IP \(bu 4
+IO has been upgraded from version 1.36 to 1.36_01.
+.IP \(bu 4
+The IO-Compress modules have been upgraded from version 2.069 to 2.069_001.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.92 to 0.92_01.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.27300 to 2.27300_01.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.26 to 1.26_01.
+.IP \(bu 4
+Locale::Maketext::Simple has been upgraded from version 0.21 to 0.21_01.
+.IP \(bu 4
+Memoize has been upgraded from version 1.03 to 1.03_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20160506 to 5.20170114_24.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.43 to 2.43_01.
+.IP \(bu 4
+Parse::CPAN::Meta has been upgraded from version 1.4417 to 1.4417_001.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.22 to 1.2201.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.25_02 to 3.25_03.
+.IP \(bu 4
+Storable has been upgraded from version 2.56 to 2.56_01.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.33 to 0.33_01.
+.IP \(bu 4
+Test has been upgraded from version 1.28 to 1.28_01.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.36 to 3.36_01.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.21 to 0.22, fixing a security hole
+in which binary files could be loaded from a path outside of \f(CW@INC\fR.
+[GH #15418] <https://github.com/Perl/perl5/issues/15418>
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperlapio\fR
+.IX Subsection "perlapio"
+.IP \(bu 4
+The documentation of \f(CW\*(C`PERLIO_DEBUG\*(C'\fR has been updated.
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+The new \fB\-Di\fR switch has been documented, and the documentation of
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR has been updated.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+A new test script, \fIt/run/switchDx.t\fR, has been added to test that the new
+\&\fB\-Di\fR switch is working correctly.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The change to hashbang redirection introduced in Perl 5.24.0, whereby perl
+would redirect to another interpreter (Perl 6) if it found a hashbang path
+which contains "perl" followed by "6", has been reverted because it broke in
+cases such as \f(CW\*(C`#!/opt/perl64/bin/perl\*(C'\fR.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.24.1 represents approximately 8 months of development since Perl 5.24.0
+and contains approximately 8,100 lines of changes across 240 files from 18
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 2,200 lines of changes to 170 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.24.1:
+.PP
+Aaron Crane, Alex Vandiver, Aristotle Pagaltzis, Chad Granum, Chris 'BinGOs'
+Williams, Craig A. Berry, Father Chrysostomos, James E Keenan, Jarkko
+Hietaniemi, Karen Etheridge, Leon Timmermans, Matthew Horsfall, Ricardo Signes,
+Sawyer X, Sébastien Aperghis-Tramoni, Stevan Little, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the Perl bug database at
+<https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5242delta.1 b/upstream/mageia-cauldron/man1/perl5242delta.1
new file mode 100644
index 00000000..fc7b6e70
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5242delta.1
@@ -0,0 +1,158 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5242DELTA 1"
+.TH PERL5242DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5242delta \- what is new for perl v5.24.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.24.1 release and the 5.24.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.24.0, first read
+perl5241delta, which describes differences between 5.24.0 and 5.24.1.
+.SH Security
+.IX Header "Security"
+.ie n .SS "Improved handling of '.' in @INC in base.pm"
+.el .SS "Improved handling of '.' in \f(CW@INC\fP in base.pm"
+.IX Subsection "Improved handling of '.' in @INC in base.pm"
+The handling of (the removal of) \f(CW\*(Aq.\*(Aq\fR in \f(CW@INC\fR in base has been
+improved.  This resolves some problematic behaviour in the approach taken in
+Perl 5.24.1, which is probably best described in the following two threads on
+the Perl 5 Porters mailing list:
+<http://www.nntp.perl.org/group/perl.perl5.porters/2016/08/msg238991.html>,
+<http://www.nntp.perl.org/group/perl.perl5.porters/2016/10/msg240297.html>.
+.SS """Escaped"" colons and relative paths in PATH"
+.IX Subsection """Escaped"" colons and relative paths in PATH"
+On Unix systems, Perl treats any relative paths in the PATH environment
+variable as tainted when starting a new process.  Previously, it was allowing a
+backslash to escape a colon (unlike the OS), consequently allowing relative
+paths to be considered safe if the PATH was set to something like \f(CW\*(C`/\e:.\*(C'\fR.  The
+check has been fixed to treat \f(CW\*(C`.\*(C'\fR as tainted in that example.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+base has been upgraded from version 2.23 to 2.23_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170114_24 to 5.20170715_24.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Fixed a crash with \f(CW\*(C`s///l\*(C'\fR where it thought it was dealing with UTF\-8 when it
+wasn't.
+[GH #15543] <https://github.com/Perl/perl5/issues/15543>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.24.2 represents approximately 6 months of development since Perl 5.24.1
+and contains approximately 2,500 lines of changes across 53 files from 18
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 960 lines of changes to 17 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.24.2:
+.PP
+Aaron Crane, Abigail, Aristotle Pagaltzis, Chris 'BinGOs' Williams, Dan
+Collins, David Mitchell, Eric Herman, Father Chrysostomos, James E Keenan, Karl
+Williamson, Lukas Mai, Renee Baecker, Ricardo Signes, Sawyer X, Stevan Little,
+Steve Hay, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+<https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5243delta.1 b/upstream/mageia-cauldron/man1/perl5243delta.1
new file mode 100644
index 00000000..31333ff3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5243delta.1
@@ -0,0 +1,315 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5243DELTA 1"
+.TH PERL5243DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5243delta \- what is new for perl v5.24.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.24.2 release and the 5.24.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.24.1, first read
+perl5242delta, which describes differences between 5.24.1 and 5.24.2.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler"
+.IX Subsection "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+Compiling certain regular expression patterns with the case-insensitive
+modifier could cause a heap buffer overflow and crash perl.  This has now been
+fixed.
+[GH #16021] <https://github.com/Perl/perl5/issues/16021>
+.SS "[CVE\-2017\-12883] Buffer over-read in regular expression parser"
+.IX Subsection "[CVE-2017-12883] Buffer over-read in regular expression parser"
+For certain types of syntax error in a regular expression pattern, the error
+message could either contain the contents of a random, possibly large, chunk of
+memory, or could crash perl.  This has now been fixed.
+[GH #16025] <https://github.com/Perl/perl5/issues/16025>
+.ie n .SS "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows"
+.el .SS "[CVE\-2017\-12814] \f(CW$ENV{$key}\fP stack buffer overflow on Windows"
+.IX Subsection "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+A possible stack buffer overflow in the \f(CW%ENV\fR code on Windows has been fixed
+by removing the buffer completely since it was superfluous anyway.
+[GH #16051] <https://github.com/Perl/perl5/issues/16051>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.24.2.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting
+Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170715_24 to
+5.20170922_24.
+.IP \(bu 4
+POSIX has been upgraded from version 1.65 to 1.65_01.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9733 to 1.9741.
+.Sp
+[GH #15396] <https://github.com/Perl/perl5/issues/15396>
+[GH #15401] <https://github.com/Perl/perl5/issues/15401>
+[GH #15524] <https://github.com/Perl/perl5/issues/15524>
+[cpan #120032] <https://rt.cpan.org/Public/Bug/Display.html?id=120032>
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+When building with GCC 6 and link-time optimization (the \fB\-flto\fR option to
+\&\fBgcc\fR), \fIConfigure\fR was treating all probed symbols as present on the system,
+regardless of whether they actually exist.  This has been fixed.
+[GH #15322] <https://github.com/Perl/perl5/issues/15322>
+.IP \(bu 4
+\&\fIConfigure\fR now aborts if both \f(CW\*(C`\-Duselongdouble\*(C'\fR and \f(CW\*(C`\-Dusequadmath\*(C'\fR are
+requested.
+[GH #14944] <https://github.com/Perl/perl5/issues/14944>
+.IP \(bu 4
+Fixed a bug in which \fIConfigure\fR could append \f(CW\*(C`\-quadmath\*(C'\fR to the archname
+even if it was already present.
+[GH #15423] <https://github.com/Perl/perl5/issues/15423>
+.IP \(bu 4
+Clang builds with \f(CW\*(C`\-DPERL_GLOBAL_STRUCT\*(C'\fR or \f(CW\*(C`\-DPERL_GLOBAL_STRUCT_PRIVATE\*(C'\fR
+have been fixed (by disabling Thread Safety Analysis for these configurations).
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\f(CW\*(C`configure.com\*(C'\fR now recognizes the VSI-branded C compiler.
+.RE
+.RS 4
+.RE
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Building XS modules with GCC 6 in a 64\-bit build of Perl failed due to
+incorrect mapping of \f(CW\*(C`strtoll\*(C'\fR and \f(CW\*(C`strtoull\*(C'\fR.  This has now been fixed.
+[GH #16074] <https://github.com/Perl/perl5/issues/16074>
+[cpan #121683] <https://rt.cpan.org/Public/Bug/Display.html?id=121683>
+[cpan #122353] <https://rt.cpan.org/Public/Bug/Display.html?id=122353>
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\f(CW\*(C`/@0{0*\->@*/*0\*(C'\fR and similar contortions used to crash, but no longer
+do, but merely produce a syntax error.
+[GH #15333] <https://github.com/Perl/perl5/issues/15333>
+.IP \(bu 4
+\&\f(CW\*(C`do\*(C'\fR or \f(CW\*(C`require\*(C'\fR with an argument which is a reference or typeglob which,
+when stringified, contains a null character, started crashing in Perl 5.20, but
+has now been fixed.
+[GH #15337] <https://github.com/Perl/perl5/issues/15337>
+.IP \(bu 4
+Expressions containing an \f(CW\*(C`&&\*(C'\fR or \f(CW\*(C`||\*(C'\fR operator (or their synonyms \f(CW\*(C`and\*(C'\fR and
+\&\f(CW\*(C`or\*(C'\fR) were being compiled incorrectly in some cases.  If the left-hand side
+consisted of either a negated bareword constant or a negated \f(CW\*(C`do {}\*(C'\fR block
+containing a constant expression, and the right-hand side consisted of a
+negated non-foldable expression, one of the negations was effectively ignored.
+The same was true of \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR statement modifiers, though with the
+left-hand and right-hand sides swapped.  This long-standing bug has now been
+fixed.
+[GH #15285] <https://github.com/Perl/perl5/issues/15285>
+.IP \(bu 4
+\&\f(CW\*(C`reset\*(C'\fR with an argument no longer crashes when encountering stash entries
+other than globs.
+[GH #15314] <https://github.com/Perl/perl5/issues/15314>
+.IP \(bu 4
+Assignment of hashes to, and deletion of, typeglobs named \f(CW*::::::\fR no longer
+causes crashes.
+[GH #15307] <https://github.com/Perl/perl5/issues/15307>
+.IP \(bu 4
+Assignment variants of any bitwise ops under the \f(CW\*(C`bitwise\*(C'\fR feature would crash
+if the left-hand side was an array or hash.
+[GH #15346] <https://github.com/Perl/perl5/issues/15346>
+.IP \(bu 4
+\&\f(CW\*(C`socket\*(C'\fR now leaves the error code returned by the system in \f(CW$!\fR on failure.
+[GH #15383] <https://github.com/Perl/perl5/issues/15383>
+.IP \(bu 4
+Parsing bad POSIX charclasses no longer leaks memory.
+[GH #15382] <https://github.com/Perl/perl5/issues/15382>
+.IP \(bu 4
+Since Perl 5.20, line numbers have been off by one when perl is invoked with
+the \fB\-x\fR switch.  This has been fixed.
+[GH #15413] <https://github.com/Perl/perl5/issues/15413>
+.IP \(bu 4
+Some obscure cases of subroutines and file handles being freed at the same time
+could result in crashes, but have been fixed.  The crash was introduced in Perl
+5.22.
+[GH #15435] <https://github.com/Perl/perl5/issues/15435>
+.IP \(bu 4
+Some regular expression parsing glitches could lead to assertion failures with
+regular expressions such as \f(CW\*(C`/(?<=/\*(C'\fR and \f(CW\*(C`/(?<!/\*(C'\fR.  This has now been
+fixed.
+[GH #15332] <https://github.com/Perl/perl5/issues/15332>
+.IP \(bu 4
+\&\f(CW\*(C`gethostent\*(C'\fR and similar functions now perform a null check internally, to
+avoid crashing with the torsocks library.  This was a regression from Perl
+5.22.
+[GH #15478] <https://github.com/Perl/perl5/issues/15478>
+.IP \(bu 4
+Mentioning the same constant twice in a row (which is a syntax error) no longer
+fails an assertion under debugging builds.  This was a regression from Perl
+5.20.
+[GH #15017] <https://github.com/Perl/perl5/issues/15017>
+.IP \(bu 4
+In Perl 5.24 \f(CW\*(C`fchown\*(C'\fR was changed not to accept negative one as an argument
+because in some platforms that is an error.  However, in some other platforms
+that is an acceptable argument.  This change has been reverted.
+[GH #15523] <https://github.com/Perl/perl5/issues/15523>.
+.IP \(bu 4
+\&\f(CW\*(C`@{x\*(C'\fR followed by a newline where \f(CW"x"\fR represents a control or non-ASCII
+character no longer produces a garbled syntax error message or a crash.
+[GH #15518] <https://github.com/Perl/perl5/issues/15518>
+.IP \(bu 4
+A regression in Perl 5.24 with \f(CW\*(C`tr/\eN{U+...}/foo/\*(C'\fR when the code point was
+between 128 and 255 has been fixed.
+[GH #15475] <https://github.com/Perl/perl5/issues/15475>.
+.IP \(bu 4
+Many issues relating to \f(CW\*(C`printf "%a"\*(C'\fR of hexadecimal floating point were
+fixed.  In addition, the "subnormals" (formerly known as "denormals") floating
+point numbers are now supported both with the plain IEEE 754 floating point
+numbers (64\-bit or 128\-bit) and the x86 80\-bit "extended precision".  Note that
+subnormal hexadecimal floating point literals will give a warning about
+"exponent underflow".
+[GH #15495] <https://github.com/Perl/perl5/issues/15495>
+[GH #15502] <https://github.com/Perl/perl5/issues/15502>
+[GH #15503] <https://github.com/Perl/perl5/issues/15503>
+[GH #15504] <https://github.com/Perl/perl5/issues/15504>
+[GH #15505] <https://github.com/Perl/perl5/issues/15505>
+[GH #15510] <https://github.com/Perl/perl5/issues/15510>
+[GH #15512] <https://github.com/Perl/perl5/issues/15512>
+.IP \(bu 4
+The parser could sometimes crash if a bareword came after \f(CW\*(C`evalbytes\*(C'\fR.
+[GH #15586] <https://github.com/Perl/perl5/issues/15586>
+.IP \(bu 4
+Fixed a place where the regex parser was not setting the syntax error correctly
+on a syntactically incorrect pattern.
+[GH #15565] <https://github.com/Perl/perl5/issues/15565>
+.IP \(bu 4
+A vulnerability in Perl's \f(CW\*(C`sprintf\*(C'\fR implementation has been fixed by avoiding
+a possible memory wrap.
+[GH #15970] <https://github.com/Perl/perl5/issues/15970>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.24.3 represents approximately 2 months of development since Perl 5.24.2
+and contains approximately 3,200 lines of changes across 120 files from 23
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,600 lines of changes to 56 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.24.3:
+.PP
+Aaron Crane, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Collins, Daniel
+Dragan, Dave Cross, David Mitchell, Eric Herman, Father Chrysostomos, H.Merijn
+Brand, Hugo van der Sanden, James E Keenan, Jarkko Hietaniemi, John SJ
+Anderson, Karl Williamson, Ken Brown, Lukas Mai, Matthew Horsfall, Stevan
+Little, Steve Hay, Steven Humphrey, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+<https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5244delta.1 b/upstream/mageia-cauldron/man1/perl5244delta.1
new file mode 100644
index 00000000..1ad33ef7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5244delta.1
@@ -0,0 +1,166 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5244DELTA 1"
+.TH PERL5244DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5244delta \- what is new for perl v5.24.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.24.3 release and the 5.24.4
+release.
+.PP
+If you are upgrading from an earlier release such as 5.24.2, first read
+perl5243delta, which describes differences between 5.24.2 and 5.24.3.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2018\-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+.IX Subsection "[CVE-2018-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+A crafted regular expression could cause a heap buffer write overflow, with
+control over the bytes written.
+[GH #16185] <https://github.com/Perl/perl5/issues/16185>
+.SS "[CVE\-2018\-6798] Heap-buffer-overflow in Perl_\|_byte_dump_string (utf8.c)"
+.IX Subsection "[CVE-2018-6798] Heap-buffer-overflow in Perl__byte_dump_string (utf8.c)"
+Matching a crafted locale dependent regular expression could cause a heap
+buffer read overflow and potentially information disclosure.
+[GH #16143] <https://github.com/Perl/perl5/issues/16143>
+.SS "[CVE\-2018\-6913] heap-buffer-overflow in S_pack_rec"
+.IX Subsection "[CVE-2018-6913] heap-buffer-overflow in S_pack_rec"
+\&\f(CWpack()\fR could cause a heap buffer write overflow with a large item count.
+[GH #16098] <https://github.com/Perl/perl5/issues/16098>
+.SS "Assertion failure in Perl_\|_core_swash_init (utf8.c)"
+.IX Subsection "Assertion failure in Perl__core_swash_init (utf8.c)"
+Control characters in a supposed Unicode property name could cause perl to
+crash.  This has been fixed.
+[perl #132055] <https://rt.perl.org/Public/Bug/Display.html?id=132055>
+[perl #132553] <https://rt.perl.org/Public/Bug/Display.html?id=132553>
+[perl #132658] <https://rt.perl.org/Public/Bug/Display.html?id=132658>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.24.3.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting
+Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170922_24 to 5.20180414_24.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The \f(CWreadpipe()\fR built-in function now checks at compile time that it has only
+one parameter expression, and puts it in scalar context, thus ensuring that it
+doesn't corrupt the stack at runtime.
+[GH #2793] <https://github.com/Perl/perl5/issues/2793>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.24.4 represents approximately 7 months of development since Perl 5.24.3
+and contains approximately 2,400 lines of changes across 49 files from 12
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,300 lines of changes to 12 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.24.4:
+.PP
+Abigail, Chris 'BinGOs' Williams, John SJ Anderson, Karen Etheridge, Karl
+Williamson, Renee Baecker, Sawyer X, Steve Hay, Todd Rinaldo, Tony Cook, Yves
+Orton, Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+<https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5260delta.1 b/upstream/mageia-cauldron/man1/perl5260delta.1
new file mode 100644
index 00000000..39769e74
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5260delta.1
@@ -0,0 +1,2481 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5260DELTA 1"
+.TH PERL5260DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5260delta \- what is new for perl v5.26.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the differences between the 5.24.0 release and the
+5.26.0 release.
+.SH Notice
+.IX Header "Notice"
+This release includes three updates with widespread effects:
+.IP \(bu 4
+\&\f(CW"."\fR no longer in \f(CW@INC\fR
+.Sp
+For security reasons, the current directory (\f(CW"."\fR) is no longer included
+by default at the end of the module search path (\f(CW@INC\fR). This may have
+widespread implications for the building, testing and installing of
+modules, and for the execution of scripts.  See the section
+"Removal of the current directory (\f(CW"."\fR) from \f(CW@INC\fR"
+for the full details.
+.IP \(bu 4
+\&\f(CW\*(C`do\*(C'\fR may now warn
+.Sp
+\&\f(CW\*(C`do\*(C'\fR now gives a deprecation warning when it fails to load a file which
+it would have loaded had \f(CW"."\fR been in \f(CW@INC\fR.
+.IP \(bu 4
+In regular expression patterns, a literal left brace \f(CW"{"\fR
+should be escaped
+.Sp
+See "Unescaped literal \f(CW"{"\fR characters in regular expression patterns are no longer permissible".
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Lexical subroutines are no longer experimental"
+.IX Subsection "Lexical subroutines are no longer experimental"
+Using the \f(CW\*(C`lexical_subs\*(C'\fR feature introduced in v5.18 no longer emits a warning.  Existing
+code that disables the \f(CW\*(C`experimental::lexical_subs\*(C'\fR warning category
+that the feature previously used will continue to work.  The
+\&\f(CW\*(C`lexical_subs\*(C'\fR feature has no effect; all Perl code can use lexical
+subroutines, regardless of what feature declarations are in scope.
+.SS "Indented Here-documents"
+.IX Subsection "Indented Here-documents"
+This adds a new modifier \f(CW"~"\fR to here-docs that tells the parser
+that it should look for \f(CW\*(C`/^\es*$DELIM\en/\*(C'\fR as the closing delimiter.
+.PP
+These syntaxes are all supported:
+.PP
+.Vb 8
+\&    <<~EOF;
+\&    <<~\eEOF;
+\&    <<~\*(AqEOF\*(Aq;
+\&    <<~"EOF";
+\&    <<~\`EOF\`;
+\&    <<~ \*(AqEOF\*(Aq;
+\&    <<~ "EOF";
+\&    <<~ \`EOF\`;
+.Ve
+.PP
+The \f(CW"~"\fR modifier will strip, from each line in the here-doc, the
+same whitespace that appears before the delimiter.
+.PP
+Newlines will be copied as-is, and lines that don't include the
+proper beginning whitespace will cause perl to croak.
+.PP
+For example:
+.PP
+.Vb 5
+\&    if (1) {
+\&      print <<~EOF;
+\&        Hello there
+\&        EOF
+\&    }
+.Ve
+.PP
+prints "Hello there\en" with no leading whitespace.
+.ie n .SS "New regular expression modifier ""/xx"""
+.el .SS "New regular expression modifier \f(CW/xx\fP"
+.IX Subsection "New regular expression modifier /xx"
+Specifying two \f(CW"x"\fR characters to modify a regular expression pattern
+does everything that a single one does, but additionally TAB and SPACE
+characters within a bracketed character class are generally ignored and
+can be added to improve readability, like
+\&\f(CW\*(C`/[\ ^\ A\-Z\ d\-f\ p\-x\ ]/xx\*(C'\fR.  Details are at
+"/x and /xx" in perlre.
+.ie n .SS """@{^CAPTURE}"", ""%{^CAPTURE}"", and ""%{^CAPTURE_ALL}"""
+.el .SS "\f(CW@{^CAPTURE}\fP, \f(CW%{^CAPTURE}\fP, and \f(CW%{^CAPTURE_ALL}\fP"
+.IX Subsection "@{^CAPTURE}, %{^CAPTURE}, and %{^CAPTURE_ALL}"
+\&\f(CW\*(C`@{^CAPTURE}\*(C'\fR exposes the capture buffers of the last match as an
+array.  So \f(CW$1\fR is \f(CW\*(C`${^CAPTURE}[0]\*(C'\fR.  This is a more efficient equivalent
+to code like \f(CW\*(C`substr($matched_string,$\-[0],$+[0]\-$\-[0])\*(C'\fR, and you don't
+have to keep track of the \f(CW$matched_string\fR either.  This variable has no
+single character equivalent.  Note that, like the other regex magic variables,
+the contents of this variable is dynamic; if you wish to store it beyond
+the lifetime of the match you must copy it to another array.
+.PP
+\&\f(CW\*(C`%{^CAPTURE}\*(C'\fR is equivalent to \f(CW\*(C`%+\*(C'\fR (\fIi.e.\fR, named captures).  Other than
+being more self-documenting there is no difference between the two forms.
+.PP
+\&\f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR is equivalent to \f(CW\*(C`%\-\*(C'\fR (\fIi.e.\fR, all named captures).
+Other than being more self-documenting there is no difference between the
+two forms.
+.SS "Declaring a reference to a variable"
+.IX Subsection "Declaring a reference to a variable"
+As an experimental feature, Perl now allows the referencing operator to come
+after \f(CWmy()\fR, \f(CWstate()\fR,
+\&\f(CWour()\fR, or \f(CWlocal()\fR.  This syntax must
+be enabled with \f(CW\*(C`use feature \*(Aqdeclared_refs\*(Aq\*(C'\fR.  It is experimental, and will
+warn by default unless \f(CW\*(C`no warnings \*(Aqexperimental::refaliasing\*(Aq\*(C'\fR is in effect.
+It is intended mainly for use in assignments to references.  For example:
+.PP
+.Vb 2
+\&    use experimental \*(Aqrefaliasing\*(Aq, \*(Aqdeclared_refs\*(Aq;
+\&    my \e$a = \e$b;
+.Ve
+.PP
+See "Assigning to References" in perlref for more details.
+.SS "Unicode 9.0 is now supported"
+.IX Subsection "Unicode 9.0 is now supported"
+A list of changes is at <http://www.unicode.org/versions/Unicode9.0.0/>.
+Modules that are shipped with core Perl but not maintained by p5p do not
+necessarily support Unicode 9.0.  Unicode::Normalize does work on 9.0.
+.ie n .SS "Use of ""\ep{\fIscript\fP}"" uses the improved Script_Extensions property"
+.el .SS "Use of \f(CW\ep{\fP\f(CIscript\fP\f(CW}\fP uses the improved Script_Extensions property"
+.IX Subsection "Use of p{script} uses the improved Script_Extensions property"
+Unicode 6.0 introduced an improved form of the Script (\f(CW\*(C`sc\*(C'\fR) property, and
+called it Script_Extensions (\f(CW\*(C`scx\*(C'\fR).  Perl now uses this improved
+version when a property is specified as just \f(CW\*(C`\ep{\fR\f(CIscript\fR\f(CW}\*(C'\fR.  This
+should make programs more accurate when determining if a character is
+used in a given script, but there is a slight chance of breakage for
+programs that very specifically needed the old behavior.  The meaning of
+compound forms, like \f(CW\*(C`\ep{sc=\fR\f(CIscript\fR\f(CW}\*(C'\fR are unchanged.  See
+"Scripts" in perlunicode.
+.SS "Perl can now do default collation in UTF\-8 locales on platforms that support it"
+.IX Subsection "Perl can now do default collation in UTF-8 locales on platforms that support it"
+Some platforms natively do a reasonable job of collating and sorting in
+UTF\-8 locales.  Perl now works with those.  For portability and full
+control, Unicode::Collate is still recommended, but now you may
+not need to do anything special to get good-enough results, depending on
+your application.  See
+"Category \f(CW\*(C`LC_COLLATE\*(C'\fR: Collation: Text Comparisons and Sorting" in perllocale.
+.ie n .SS "Better locale collation of strings containing embedded ""NUL"" characters"
+.el .SS "Better locale collation of strings containing embedded \f(CWNUL\fP characters"
+.IX Subsection "Better locale collation of strings containing embedded NUL characters"
+In locales that have multi-level character weights, \f(CW\*(C`NUL\*(C'\fRs are now
+ignored at the higher priority ones.  There are still some gotchas in
+some strings, though.  See
+"Collation of strings containing embedded \f(CW\*(C`NUL\*(C'\fR characters" in perllocale.
+.ie n .SS """CORE"" subroutines for hash and array functions callable via reference"
+.el .SS "\f(CWCORE\fP subroutines for hash and array functions callable via reference"
+.IX Subsection "CORE subroutines for hash and array functions callable via reference"
+The hash and array functions in the \f(CW\*(C`CORE\*(C'\fR namespace (\f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`each\*(C'\fR,
+\&\f(CW\*(C`values\*(C'\fR, \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR and \f(CW\*(C`splice\*(C'\fR) can now
+be called with ampersand syntax (\f(CW\*(C`&CORE::keys(\e%hash\*(C'\fR) and via reference
+(\f(CW\*(C`my $k = \e&CORE::keys; $k\->(\e%hash)\*(C'\fR).  Previously they could only be
+used when inlined.
+.SS "New Hash Function For 64\-bit Builds"
+.IX Subsection "New Hash Function For 64-bit Builds"
+We have switched to a hybrid hash function to better balance
+performance for short and long keys.
+.PP
+For short keys, 16 bytes and under, we use an optimised variant of
+One At A Time Hard, and for longer keys we use Siphash 1\-3.  For very
+long keys this is a big improvement in performance.  For shorter keys
+there is a modest improvement.
+.SH Security
+.IX Header "Security"
+.ie n .SS "Removal of the current directory (""."") from @INC"
+.el .SS "Removal of the current directory (\f(CW"".""\fP) from \f(CW@INC\fP"
+.IX Subsection "Removal of the current directory (""."") from @INC"
+The perl binary includes a default set of paths in \f(CW@INC\fR.  Historically
+it has also included the current directory (\f(CW"."\fR) as the final entry,
+unless run with taint mode enabled (\f(CW\*(C`perl \-T\*(C'\fR).  While convenient, this has
+security implications: for example, where a script attempts to load an
+optional module when its current directory is untrusted (such as \fI/tmp\fR),
+it could load and execute code from under that directory.
+.PP
+Starting with v5.26, \f(CW"."\fR is always removed by default, not just under
+tainting.  This has major implications for installing modules and executing
+scripts.
+.PP
+The following new features have been added to help ameliorate these
+issues.
+.IP \(bu 4
+\&\fIConfigure \-Udefault_inc_excludes_dot\fR
+.Sp
+There is a new \fIConfigure\fR option, \f(CW\*(C`default_inc_excludes_dot\*(C'\fR (enabled
+by default) which builds a perl executable without \f(CW"."\fR; unsetting this
+option using \f(CW\*(C`\-U\*(C'\fR reverts perl to the old behaviour.  This may fix your
+path issues but will reintroduce all the security concerns, so don't
+build a perl executable like this unless you're \fIreally\fR confident that
+such issues are not a concern in your environment.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR
+.Sp
+There is a new environment variable recognised by the perl interpreter.
+If this variable has the value 1 when the perl interpreter starts up,
+then \f(CW"."\fR will be automatically appended to \f(CW@INC\fR (except under tainting).
+.Sp
+This allows you restore the old perl interpreter behaviour on a
+case-by-case basis.  But note that this is intended to be a temporary crutch,
+and this feature will likely be removed in some future perl version.
+It is currently set by the \f(CW\*(C`cpan\*(C'\fR utility and \f(CW\*(C`Test::Harness\*(C'\fR to
+ease installation of CPAN modules which have not been updated to handle the
+lack of dot.  Once again, don't use this unless you are sure that this
+will not reintroduce any security concerns.
+.IP \(bu 4
+A new deprecation warning issued by \f(CW\*(C`do\*(C'\fR.
+.Sp
+While it is well-known that \f(CW\*(C`use\*(C'\fR and \f(CW\*(C`require\*(C'\fR use \f(CW@INC\fR to search
+for the file to load, many people don't realise that \f(CW\*(C`do "file"\*(C'\fR also
+searches \f(CW@INC\fR if the file is a relative path.  With the removal of \f(CW"."\fR,
+a simple \f(CW\*(C`do "file.pl"\*(C'\fR will fail to read in and execute \f(CW\*(C`file.pl\*(C'\fR from
+the current directory.  Since this is commonly expected behaviour, a new
+deprecation warning is now issued whenever \f(CW\*(C`do\*(C'\fR fails to load a file which
+it otherwise would have found if a dot had been in \f(CW@INC\fR.
+.PP
+Here are some things script and module authors may need to do to make
+their software work in the new regime.
+.IP \(bu 4
+Script authors
+.Sp
+If the issue is within your own code (rather than within included
+modules), then you have two main options.  Firstly, if you are confident
+that your script will only be run within a trusted directory (under which
+you expect to find trusted files and modules), then add \f(CW"."\fR back into the
+path; \fIe.g.\fR:
+.Sp
+.Vb 6
+\&    BEGIN {
+\&        my $dir = "/some/trusted/directory";
+\&        chdir $dir or die "Can\*(Aqt chdir to $dir: $!\en";
+\&        # safe now
+\&        push @INC, \*(Aq.\*(Aq;
+\&    }
+\&
+\&    use "Foo::Bar"; # may load /some/trusted/directory/Foo/Bar.pm
+\&    do "config.pl"; # may load /some/trusted/directory/config.pl
+.Ve
+.Sp
+On the other hand, if your script is intended to be run from within
+untrusted directories (such as \fI/tmp\fR), then your script suddenly failing
+to load files may be indicative of a security issue.  You most likely want
+to replace any relative paths with full paths; for example,
+.Sp
+.Vb 1
+\&    do "foo_config.pl"
+.Ve
+.Sp
+might become
+.Sp
+.Vb 1
+\&    do "$ENV{HOME}/foo_config.pl"
+.Ve
+.Sp
+If you are absolutely certain that you want your script to load and
+execute a file from the current directory, then use a \f(CW\*(C`./\*(C'\fR prefix; for
+example:
+.Sp
+.Vb 1
+\&    do "./foo_config.pl"
+.Ve
+.IP \(bu 4
+Installing and using CPAN modules
+.Sp
+If you install a CPAN module using an automatic tool like \f(CW\*(C`cpan\*(C'\fR, then
+this tool will itself set the \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR environment variable
+while building and testing the module, which may be sufficient to install
+a distribution which hasn't been updated to be dot-aware.  If you want to
+install such a module manually, then you'll need to replace the
+traditional invocation:
+.Sp
+.Vb 1
+\&    perl Makefile.PL && make && make test && make install
+.Ve
+.Sp
+with something like
+.Sp
+.Vb 2
+\&    (export PERL_USE_UNSAFE_INC=1; \e
+\&     perl Makefile.PL && make && make test && make install)
+.Ve
+.Sp
+Note that this only helps build and install an unfixed module.  It's
+possible for the tests to pass (since they were run under
+\&\f(CW\*(C`PERL_USE_UNSAFE_INC=1\*(C'\fR), but for the module itself to fail to perform
+correctly in production.  In this case, you may have to temporarily modify
+your script until a fixed version of the module is released.
+For example:
+.Sp
+.Vb 6
+\&    use Foo::Bar;
+\&    {
+\&        local @INC = (@INC, \*(Aq.\*(Aq);
+\&        # assuming read_config() needs \*(Aq.\*(Aq in @INC
+\&        $config = Foo::Bar\->read_config();
+\&    }
+.Ve
+.Sp
+This is only rarely expected to be necessary.  Again, if doing this,
+assess the resultant risks first.
+.IP \(bu 4
+Module Authors
+.Sp
+If you maintain a CPAN distribution, it may need updating to run in
+a dotless environment.  Although \f(CW\*(C`cpan\*(C'\fR and other such tools will
+currently set the \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR during module build, this is a
+temporary workaround for the set of modules which rely on \f(CW"."\fR being in
+\&\f(CW@INC\fR for installation and testing, and this may mask deeper issues.  It
+could result in a module which passes tests and installs, but which
+fails at run time.
+.Sp
+During build, test, and install, it will normally be the case that any perl
+processes will be executing directly within the root directory of the
+untarred distribution, or a known subdirectory of that, such as \fIt/\fR.  It
+may well be that \fIMakefile.PL\fR or \fIt/foo.t\fR will attempt to include
+local modules and configuration files using their direct relative
+filenames, which will now fail.
+.Sp
+However, as described above, automatic tools like \fIcpan\fR will (for now)
+set the \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR environment variable, which introduces
+dot during a build.
+.Sp
+This makes it likely that your existing build and test code will work, but
+this may mask issues with your code which only manifest when used after
+install.  It is prudent to try and run your build process with that
+variable explicitly disabled:
+.Sp
+.Vb 2
+\&    (export PERL_USE_UNSAFE_INC=0; \e
+\&     perl Makefile.PL && make && make test && make install)
+.Ve
+.Sp
+This is more likely to show up any potential problems with your module's
+build process, or even with the module itself.  Fixing such issues will
+ensure both that your module can again be installed manually, and that
+it will still build once the \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR crutch goes away.
+.Sp
+When fixing issues in tests due to the removal of dot from \f(CW@INC\fR,
+reinsertion of dot into \f(CW@INC\fR should be performed with caution, for this
+too may suppress real errors in your runtime code.  You are encouraged
+wherever possible to apply the aforementioned approaches with explicit
+absolute/relative paths, or to relocate your needed files into a
+subdirectory and insert that subdirectory into \f(CW@INC\fR instead.
+.Sp
+If your runtime code has problems under the dotless \f(CW@INC\fR, then the comments
+above on how to fix for script authors will mostly apply here too.  Bear in
+mind though that it is considered bad form for a module to globally add a dot to
+\&\f(CW@INC\fR, since it introduces both a security risk and hides issues of
+accidentally requiring dot in \f(CW@INC\fR, as explained above.
+.SS "Escaped colons and relative paths in PATH"
+.IX Subsection "Escaped colons and relative paths in PATH"
+On Unix systems, Perl treats any relative paths in the \f(CW\*(C`PATH\*(C'\fR environment
+variable as tainted when starting a new process.  Previously, it was
+allowing a backslash to escape a colon (unlike the OS), consequently
+allowing relative paths to be considered safe if the PATH was set to
+something like \f(CW\*(C`/\e:.\*(C'\fR.  The check has been fixed to treat \f(CW"."\fR as tainted
+in that example.
+.ie n .SS "New ""\-Di"" switch is now required for PerlIO debugging output"
+.el .SS "New \f(CW\-Di\fP switch is now required for PerlIO debugging output"
+.IX Subsection "New -Di switch is now required for PerlIO debugging output"
+This is used for debugging of code within PerlIO to avoid recursive
+calls.  Previously this output would be sent to the file specified
+by the \f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment variable if perl wasn't running
+setuid and the \f(CW\*(C`\-T\*(C'\fR or \f(CW\*(C`\-t\*(C'\fR switches hadn't been parsed yet.
+.PP
+If perl performed output at a point where it hadn't yet parsed its
+switches this could result in perl creating or overwriting the file
+named by \f(CW\*(C`PERLIO_DEBUG\*(C'\fR even when the \f(CW\*(C`\-T\*(C'\fR switch had been supplied.
+.PP
+Perl now requires the \f(CW\*(C`\-Di\*(C'\fR switch to be present before it will produce
+PerlIO debugging
+output.  By default this is written to \f(CW\*(C`stderr\*(C'\fR, but can optionally
+be redirected to a file by setting the \f(CW\*(C`PERLIO_DEBUG\*(C'\fR environment
+variable.
+.PP
+If perl is running setuid or the \f(CW\*(C`\-T\*(C'\fR switch was supplied,
+\&\f(CW\*(C`PERLIO_DEBUG\*(C'\fR is ignored and the debugging output is sent to
+\&\f(CW\*(C`stderr\*(C'\fR as for any other \f(CW\*(C`\-D\*(C'\fR switch.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.ie n .SS "Unescaped literal ""{"" characters in regular expression patterns are no longer permissible"
+.el .SS "Unescaped literal \f(CW""{""\fP characters in regular expression patterns are no longer permissible"
+.IX Subsection "Unescaped literal ""{"" characters in regular expression patterns are no longer permissible"
+You have to now say something like \f(CW"\e{"\fR or \f(CW"[{]"\fR to specify to
+match a LEFT CURLY BRACKET; otherwise, it is a fatal pattern compilation
+error.  This change will allow future extensions to the language.
+.PP
+These have been deprecated since v5.16, with a deprecation message
+raised for some uses starting in v5.22.  Unfortunately, the code added
+to raise the message was buggy and failed to warn in some cases where
+it should have.  Therefore, enforcement of this ban for these cases is
+deferred until Perl 5.30, but the code has been fixed to raise a
+default-on deprecation message for them in the meantime.
+.PP
+Some uses of literal \f(CW"{"\fR occur in contexts where we do not foresee
+the meaning ever being anything but the literal, such as the very first
+character in the pattern, or after a \f(CW"|"\fR meaning alternation.  Thus
+.PP
+.Vb 1
+\& qr/{fee|{fie/
+.Ve
+.PP
+matches either of the strings \f(CW\*(C`{fee\*(C'\fR or \f(CW\*(C`{fie\*(C'\fR.  To avoid forcing
+unnecessary code changes, these uses do not need to be escaped, and no
+warning is raised about them, and there are no current plans to change this.
+.PP
+But it is always correct to escape \f(CW"{"\fR, and the simple rule to
+remember is to always do so.
+.PP
+See Unescaped left brace in regex is illegal here.
+.ie n .SS "scalar(%hash) return signature changed"
+.el .SS "\f(CWscalar(%hash)\fP return signature changed"
+.IX Subsection "scalar(%hash) return signature changed"
+The value returned for \f(CWscalar(%hash)\fR will no longer show information about
+the buckets allocated in the hash.  It will simply return the count of used
+keys.  It is thus equivalent to \f(CW\*(C`0+keys(%hash)\*(C'\fR.
+.PP
+A form of backward compatibility is provided via
+\&\f(CWHash::Util::bucket_ratio()\fR which provides
+the same behavior as
+\&\f(CWscalar(%hash)\fR provided in Perl 5.24 and earlier.
+.ie n .SS """keys"" returned from an lvalue subroutine"
+.el .SS "\f(CWkeys\fP returned from an lvalue subroutine"
+.IX Subsection "keys returned from an lvalue subroutine"
+\&\f(CW\*(C`keys\*(C'\fR returned from an lvalue subroutine can no longer be assigned
+to in list context.
+.PP
+.Vb 4
+\&    sub foo : lvalue { keys(%INC) }
+\&    (foo) = 3; # death
+\&    sub bar : lvalue { keys(@_) }
+\&    (bar) = 3; # also an error
+.Ve
+.PP
+This makes the lvalue sub case consistent with \f(CW\*(C`(keys %hash) = ...\*(C'\fR and
+\&\f(CW\*(C`(keys @_) = ...\*(C'\fR, which are also errors.
+[GH #15339] <https://github.com/Perl/perl5/issues/15339>
+.ie n .SS "The ""${^ENCODING}"" facility has been removed"
+.el .SS "The \f(CW${^ENCODING}\fP facility has been removed"
+.IX Subsection "The ${^ENCODING} facility has been removed"
+The special behaviour associated with assigning a value to this variable
+has been removed.  As a consequence, the encoding pragma's default mode
+is no longer supported.  If
+you still need to write your source code in encodings other than UTF\-8, use a
+source filter such as Filter::Encoding on CPAN or encoding's \f(CW\*(C`Filter\*(C'\fR
+option.
+.ie n .SS "POSIX::tmpnam() has been removed"
+.el .SS "\f(CWPOSIX::tmpnam()\fP has been removed"
+.IX Subsection "POSIX::tmpnam() has been removed"
+The fundamentally unsafe \f(CWtmpnam()\fR interface was deprecated in
+Perl 5.22 and has now been removed.  In its place, you can use,
+for example, the File::Temp interfaces.
+.SS "require ::Foo::Bar is now illegal."
+.IX Subsection "require ::Foo::Bar is now illegal."
+Formerly, \f(CW\*(C`require ::Foo::Bar\*(C'\fR would try to read \fI/Foo/Bar.pm\fR.  Now any
+bareword require which starts with a double colon dies instead.
+.SS "Literal control character variable names are no longer permissible"
+.IX Subsection "Literal control character variable names are no longer permissible"
+A variable name may no longer contain a literal control character under
+any circumstances.  These previously were allowed in single-character
+names on ASCII platforms, but have been deprecated there since Perl
+5.20.  This affects things like \f(CW\*(C`$\fR\f(CI\ecT\fR\f(CW\*(C'\fR, where \fI\ecT\fR is a literal
+control (such as a \f(CW\*(C`NAK\*(C'\fR or \f(CW\*(C`NEGATIVE ACKNOWLEDGE\*(C'\fR character) in the
+source code.
+.ie n .SS """NBSP"" is no longer permissible in ""\eN{...}"""
+.el .SS "\f(CWNBSP\fP is no longer permissible in \f(CW\eN{...}\fP"
+.IX Subsection "NBSP is no longer permissible in N{...}"
+The name of a character may no longer contain non-breaking spaces.  It
+has been deprecated to do so since Perl 5.22.
+.SH Deprecations
+.IX Header "Deprecations"
+.SS "String delimiters that aren't stand-alone graphemes are now deprecated"
+.IX Subsection "String delimiters that aren't stand-alone graphemes are now deprecated"
+For Perl to eventually allow string delimiters to be Unicode
+grapheme clusters (which look like a single character, but may be
+a sequence of several ones), we have to stop allowing a single character
+delimiter that isn't a grapheme by itself.  These are unlikely to exist
+in actual code, as they would typically display as attached to the
+character in front of them.
+.ie n .SS """\ec\fIX\fP"" that maps to a printable is no longer deprecated"
+.el .SS "\f(CW\ec\fP\f(CIX\fP\f(CW\fP that maps to a printable is no longer deprecated"
+.IX Subsection "cX that maps to a printable is no longer deprecated"
+This means we have no plans to remove this feature.  It still raises a
+warning, but only if syntax warnings are enabled.  The feature was
+originally intended to be a way to express non-printable characters that
+don't have a mnemonic (\f(CW\*(C`\et\*(C'\fR and \f(CW\*(C`\en\*(C'\fR are mnemonics for two
+non-printable characters, but most non-printables don't have a
+mnemonic.)  But the feature can be used to specify a few printable
+characters, though those are more clearly expressed as the printable
+itself.  See
+<http://www.nntp.perl.org/group/perl.perl5.porters/2017/02/msg242944.html>.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+A hash in boolean context is now sometimes faster, \fIe.g.\fR
+.Sp
+.Vb 1
+\&    if (!%h) { ... }
+.Ve
+.Sp
+This was already special-cased, but some cases were missed (such as
+\&\f(CW\*(C`grep %$_, @AoH\*(C'\fR), and even the ones which weren't have been improved.
+.IP \(bu 4
+New Faster Hash Function on 64 bit builds
+.Sp
+We use a different hash function for short and long keys.  This should
+improve performance and security, especially for long keys.
+.IP \(bu 4
+readline is faster
+.Sp
+Reading from a file line-by-line with \f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR should
+now typically be faster due to a better implementation of the code that
+searches for the next newline character.
+.IP \(bu 4
+Assigning one reference to another, \fIe.g.\fR \f(CW\*(C`$ref1 = $ref2\*(C'\fR has been
+optimized in some cases.
+.IP \(bu 4
+Remove some exceptions to creating Copy-on-Write strings. The string
+buffer growth algorithm has been slightly altered so that you're less
+likely to encounter a string which can't be COWed.
+.IP \(bu 4
+Better optimise array and hash assignment: where an array or hash appears
+in the LHS of a list assignment, such as \f(CW\*(C`(..., @a) = (...);\*(C'\fR, it's
+likely to be considerably faster, especially if it involves emptying the
+array/hash. For example, this code runs about a third faster compared to
+Perl 5.24.0:
+.Sp
+.Vb 5
+\&    my @a;
+\&    for my $i (1..10_000_000) {
+\&        @a = (1,2,3);
+\&        @a = ();
+\&    }
+.Ve
+.IP \(bu 4
+Converting a single-digit string to a number is now substantially faster.
+.IP \(bu 4
+The \f(CW\*(C`split\*(C'\fR builtin is now slightly faster in many cases: in particular
+for the two specially-handled forms
+.Sp
+.Vb 2
+\&    my    @a = split ...;
+\&    local @a = split ...;
+.Ve
+.IP \(bu 4
+The rather slow implementation for the experimental subroutine signatures
+feature has been made much faster; it is now comparable in speed with the
+traditional \f(CW\*(C`my ($a, $b, @c) = @_\*(C'\fR.
+.IP \(bu 4
+Bareword constant strings are now permitted to take part in constant
+folding.  They were originally exempted from constant folding in August 1999,
+during the development of Perl 5.6, to ensure that \f(CW\*(C`use strict "subs"\*(C'\fR
+would still apply to bareword constants.  That has now been accomplished a
+different way, so barewords, like other constants, now gain the performance
+benefits of constant folding.
+.Sp
+This also means that void-context warnings on constant expressions of
+barewords now report the folded constant operand, rather than the operation;
+this matches the behaviour for non-bareword constants.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+IO::Compress has been upgraded from version 2.069 to 2.074.
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.04 to 2.24.
+.IP \(bu 4
+arybase has been upgraded from version 0.11 to 0.12.
+.IP \(bu 4
+attributes has been upgraded from version 0.27 to 0.29.
+.Sp
+The deprecation message for the \f(CW\*(C`:unique\*(C'\fR and \f(CW\*(C`:locked\*(C'\fR attributes
+now mention that they will disappear in Perl 5.28.
+.IP \(bu 4
+B has been upgraded from version 1.62 to 1.68.
+.IP \(bu 4
+B::Concise has been upgraded from version 0.996 to 0.999.
+.Sp
+Its output is now more descriptive for \f(CW\*(C`op_private\*(C'\fR flags.
+.IP \(bu 4
+B::Debug has been upgraded from version 1.23 to 1.24.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.37 to 1.40.
+.IP \(bu 4
+B::Xref has been upgraded from version 1.05 to 1.06.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+base has been upgraded from version 2.23 to 2.25.
+.IP \(bu 4
+bignum has been upgraded from version 0.42 to 0.47.
+.IP \(bu 4
+Carp has been upgraded from version 1.40 to 1.42.
+.IP \(bu 4
+charnames has been upgraded from version 1.43 to 1.44.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.069 to 2.074.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.069 to 2.074.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.25 to 0.28.
+.IP \(bu 4
+CPAN has been upgraded from version 2.11 to 2.18.
+.IP \(bu 4
+CPAN::Meta has been upgraded from version 2.150005 to 2.150010.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.160 to 2.167.
+.Sp
+The XS implementation now supports Deparse.
+.IP \(bu 4
+DB_File has been upgraded from version 1.835 to 1.840.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.23 to 1.26.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.32 to 3.35.
+.IP \(bu 4
+Devel::SelfStubber has been upgraded from version 1.05 to 1.06.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+diagnostics has been upgraded from version 1.34 to 1.36.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+Digest has been upgraded from version 1.17 to 1.17_01.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.54 to 2.55.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.95 to 5.96.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.38 to 1.42.
+.IP \(bu 4
+Encode has been upgraded from version 2.80 to 2.88.
+.IP \(bu 4
+encoding has been upgraded from version 2.17 to 2.19.
+.Sp
+This module's default mode is no longer supported.  It now
+dies when imported, unless the \f(CW\*(C`Filter\*(C'\fR option is being used.
+.IP \(bu 4
+encoding::warnings has been upgraded from version 0.12 to 0.13.
+.Sp
+This module is no longer supported.  It emits a warning to
+that effect and then does nothing.
+.IP \(bu 4
+Errno has been upgraded from version 1.25 to 1.28.
+.Sp
+It now documents that using \f(CW\*(C`%!\*(C'\fR automatically loads Errno for you.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+ExtUtils::Embed has been upgraded from version 1.33 to 1.34.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.10_01 to 7.24.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.31 to 3.34.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.31 to 3.34.
+.IP \(bu 4
+feature has been upgraded from version 1.42 to 1.47.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.31 to 2.32.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.48 to 0.52.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.26 to 1.28.
+.Sp
+It now Issues a deprecation message for \f(CWFile::Glob::glob()\fR.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.63 to 3.67.
+.IP \(bu 4
+FileHandle has been upgraded from version 2.02 to 2.03.
+.IP \(bu 4
+Filter::Simple has been upgraded from version 0.92 to 0.93.
+.Sp
+It no longer treats \f(CW\*(C`no MyFilter\*(C'\fR immediately following \f(CW\*(C`use MyFilter\*(C'\fR as
+end-of-file.
+[GH #11853] <https://github.com/Perl/perl5/issues/11853>
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.48 to 2.49.
+.IP \(bu 4
+Getopt::Std has been upgraded from version 1.11 to 1.12.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.19 to 0.22.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.056 to 0.070.
+.Sp
+Internal 599\-series errors now include the redirect history.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.40 to 0.42.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+IO has been upgraded from version 1.36 to 1.38.
+.IP \(bu 4
+IO::Socket::IP has been upgraded from version 0.37 to 0.38.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.92 to 0.96.
+.IP \(bu 4
+IPC::SysV has been upgraded from version 2.06_01 to 2.07.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.27300 to 2.27400_02.
+.IP \(bu 4
+lib has been upgraded from version 0.63 to 0.64.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+List::Util has been upgraded from version 1.42_02 to 1.46_02.
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.37 to 3.42.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.26 to 1.28.
+.IP \(bu 4
+Locale::Maketext::Simple has been upgraded from version 0.21 to 0.21_01.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999715 to 1.999806.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.40 to 0.5005.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.260802 to 0.2611.
+.IP \(bu 4
+Math::Complex has been upgraded from version 1.59 to 1.5901.
+.IP \(bu 4
+Memoize has been upgraded from version 1.03 to 1.03_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170420 to 5.20170530.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded from version 0.64 to 0.68.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000031 to 1.000033.
+.IP \(bu 4
+mro has been upgraded from version 1.18 to 1.20.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.43 to 2.55.
+.Sp
+IPv6 addresses and \f(CW\*(C`AF_INET6\*(C'\fR sockets are now supported, along with several
+other enhancements.
+.IP \(bu 4
+NEXT has been upgraded from version 0.65 to 0.67.
+.IP \(bu 4
+Opcode has been upgraded from version 1.34 to 1.39.
+.IP \(bu 4
+open has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+OS2::Process has been upgraded from version 1.11 to 1.12.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+overload has been upgraded from version 1.26 to 1.28.
+.Sp
+Its compilation speed has been improved slightly.
+.IP \(bu 4
+parent has been upgraded from version 0.234 to 0.236.
+.IP \(bu 4
+perl5db.pl has been upgraded from version 1.50 to 1.51.
+.Sp
+It now ignores \fI/dev/tty\fR on non-Unix systems.
+[GH #12244] <https://github.com/Perl/perl5/issues/12244>
+.IP \(bu 4
+Perl::OSType has been upgraded from version 1.009 to 1.010.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.021010 to 5.021011.
+.IP \(bu 4
+PerlIO has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.24 to 0.25.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.24 to 0.26.
+.IP \(bu 4
+Pod::Checker has been upgraded from version 1.60 to 1.73.
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.22 to 1.2202.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.25_02 to 3.28.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.32 to 3.35.
+.IP \(bu 4
+Pod::Usage has been upgraded from version 1.68 to 1.69.
+.IP \(bu 4
+POSIX has been upgraded from version 1.65 to 1.76.
+.Sp
+This remedies several defects in making its symbols exportable.
+[GH #15260] <https://github.com/Perl/perl5/issues/15260>
+.Sp
+The \f(CWPOSIX::tmpnam()\fR interface has been removed,
+see "\fBPOSIX::tmpnam()\fR has been removed".
+.Sp
+The following deprecated functions have been removed:
+.Sp
+.Vb 10
+\&    POSIX::isalnum
+\&    POSIX::isalpha
+\&    POSIX::iscntrl
+\&    POSIX::isdigit
+\&    POSIX::isgraph
+\&    POSIX::islower
+\&    POSIX::isprint
+\&    POSIX::ispunct
+\&    POSIX::isspace
+\&    POSIX::isupper
+\&    POSIX::isxdigit
+\&    POSIX::tolower
+\&    POSIX::toupper
+.Ve
+.Sp
+Trying to import POSIX subs that have no real implementations
+(like \f(CWPOSIX::atend()\fR) now fails at import time, instead of
+waiting until runtime.
+.IP \(bu 4
+re has been upgraded from version 0.32 to 0.34
+.Sp
+This adds support for the new \f(CW\*(C`/xx\*(C'\fR
+regular expression pattern modifier, and a change to the \f(CWuse\ re\ \*(Aqstrict\*(Aq\fR experimental feature.  When \f(CWre\ \*(Aqstrict\*(Aq\fR is enabled, a warning now will be generated for all
+unescaped uses of the two characters \f(CW"}"\fR and \f(CW"]"\fR in regular
+expression patterns (outside bracketed character classes) that are taken
+literally.  This brings them more in line with the \f(CW")"\fR character which
+is always a metacharacter unless escaped.  Being a metacharacter only
+sometimes, depending on an action at a distance, can lead to silently
+having the pattern mean something quite different than was intended,
+which the \f(CW\*(C`re\ \*(Aqstrict\*(Aq\*(C'\fR mode is intended to minimize.
+.IP \(bu 4
+Safe has been upgraded from version 2.39 to 2.40.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.42_02 to 1.46_02.
+.IP \(bu 4
+Storable has been upgraded from version 2.56 to 2.62.
+.Sp
+Fixes
+[GH #15714] <https://github.com/Perl/perl5/issues/15714>.
+.IP \(bu 4
+Symbol has been upgraded from version 1.07 to 1.08.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.33 to 0.35.
+.IP \(bu 4
+Term::ANSIColor has been upgraded from version 4.04 to 4.06.
+.IP \(bu 4
+Term::ReadLine has been upgraded from version 1.15 to 1.16.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+Test has been upgraded from version 1.28 to 1.30.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.36 to 3.38.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.001014 to 1.302073.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 3.09 to 3.12.
+.IP \(bu 4
+Thread::Semaphore has been upgraded from 2.12 to 2.13.
+.Sp
+Added the \f(CW\*(C`down_timed\*(C'\fR method.
+.IP \(bu 4
+threads has been upgraded from version 2.07 to 2.15.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.51 to 1.56.
+.IP \(bu 4
+Tie::Hash::NamedCapture has been upgraded from version 0.09 to 0.10.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9733 to 1.9741.
+.Sp
+It now builds on systems with C++11 compilers (such as G++ 6 and Clang++
+3.9).
+.Sp
+Now uses \f(CW\*(C`clockid_t\*(C'\fR.
+.IP \(bu 4
+Time::Local has been upgraded from version 1.2300 to 1.25.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.14 to 1.19.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.64 to 0.68.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+version has been upgraded from version 0.9916 to 0.9917.
+.IP \(bu 4
+VMS::DCLsym has been upgraded from version 1.06 to 1.08.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.IP \(bu 4
+warnings has been upgraded from version 1.36 to 1.37.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.14 to 0.15.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.21 to 0.27.
+.Sp
+Fixed a security hole in which binary files could be loaded from a path
+outside of \f(CW@INC\fR.
+.Sp
+It now uses 3\-arg \f(CWopen()\fR instead of 2\-arg \f(CWopen()\fR.
+[GH #15721] <https://github.com/Perl/perl5/issues/15721>
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperldeprecation\fR
+.IX Subsection "perldeprecation"
+.PP
+This file documents all upcoming deprecations, and some of the deprecations
+which already have been removed.  The purpose of this documentation is
+two-fold: document what will disappear, and by which version, and serve
+as a guide for people dealing with code which has features that no longer
+work after an upgrade of their perl.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, send email to
+perlbug@perl.org <mailto:perlbug@perl.org>.
+.PP
+Additionally, all references to Usenet have been removed, and the
+following selected changes have been made:
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+Removed obsolete text about \f(CWdefined()\fR
+on aggregates that should have been deleted earlier, when the feature
+was removed.
+.IP \(bu 4
+Corrected documentation of \f(CWeval()\fR,
+and \f(CWevalbytes()\fR.
+.IP \(bu 4
+Clarified documentation of \f(CWseek()\fR,
+\&\f(CWtell()\fR and \f(CWsysseek()\fR
+emphasizing that positions are in bytes and not characters.
+[GH #15438] <https://github.com/Perl/perl5/issues/15438>
+.IP \(bu 4
+Clarified documentation of \f(CWsort()\fR concerning
+the variables \f(CW$a\fR and \f(CW$b\fR.
+.IP \(bu 4
+In \f(CWsplit()\fR noted that certain pattern modifiers are
+legal, and added a caution about its use in Perls before v5.11.
+.IP \(bu 4
+Removed obsolete documentation of \f(CWstudy()\fR, noting
+that it is now a no-op.
+.IP \(bu 4
+Noted that \f(CWvec()\fR doesn't work well when the string
+contains characters whose code points are above 255.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+Added advice on
+formatted printing of operands of \f(CW\*(C`Size_t\*(C'\fR and \f(CW\*(C`SSize_t\*(C'\fR
+.PP
+\fIperlhack\fR
+.IX Subsection "perlhack"
+.IP \(bu 4
+Clarify what editor tab stop rules to use, and note that we are
+migrating away from using tabs, replacing them with sequences of SPACE
+characters.
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+Give another reason to use \f(CW\*(C`cBOOL\*(C'\fR to cast an expression to boolean.
+.IP \(bu 4
+Note that the macros \f(CW\*(C`TRUE\*(C'\fR and \f(CW\*(C`FALSE\*(C'\fR are available to express
+boolean values.
+.PP
+\fIperlinterp\fR
+.IX Subsection "perlinterp"
+.IP \(bu 4
+perlinterp has been expanded to give a more detailed example of how to
+hunt around in the parser for how a given operator is handled.
+.PP
+\fIperllocale\fR
+.IX Subsection "perllocale"
+.IP \(bu 4
+Some locales aren't compatible with Perl.  Note that these can cause
+core dumps.
+.PP
+\fIperlmod\fR
+.IX Subsection "perlmod"
+.IP \(bu 4
+Various clarifications have been added.
+.PP
+\fIperlmodlib\fR
+.IX Subsection "perlmodlib"
+.IP \(bu 4
+Updated the site mirror list.
+.PP
+\fIperlobj\fR
+.IX Subsection "perlobj"
+.IP \(bu 4
+Added a section on calling methods using their fully qualified names.
+.IP \(bu 4
+Do not discourage manual \f(CW@ISA\fR.
+.PP
+\fIperlootut\fR
+.IX Subsection "perlootut"
+.IP \(bu 4
+Mention \f(CW\*(C`Moo\*(C'\fR more.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Note that white space must be used for quoting operators if the
+delimiter is a word character (\fIi.e.\fR, matches \f(CW\*(C`\ew\*(C'\fR).
+.IP \(bu 4
+Clarify that in regular expression patterns delimited by single quotes,
+no variable interpolation is done.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+The first part was extensively rewritten to incorporate various basic
+points, that in earlier versions were mentioned in sort of an appendix
+on Version 8 regular expressions.
+.IP \(bu 4
+Note that it is common to have the \f(CW\*(C`/x\*(C'\fR modifier and forget that this
+means that \f(CW"#"\fR has to be escaped.
+.PP
+\fIperlretut\fR
+.IX Subsection "perlretut"
+.IP \(bu 4
+Add introductory material.
+.IP \(bu 4
+Note that a metacharacter occurring in a context where it can't mean
+that, silently loses its meta-ness and matches literally.
+\&\f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR can catch some of these.
+.PP
+\fIperlunicode\fR
+.IX Subsection "perlunicode"
+.IP \(bu 4
+Corrected the text about Unicode BYTE ORDER MARK handling.
+.IP \(bu 4
+Updated the text to correspond with changes in Unicode UTS#18, concerning
+regular expressions, and Perl compatibility with what it says.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+Document \f(CW@ISA\fR.  It was documented in other places, but not in perlvar.
+.SH Diagnostics
+.IX Header "Diagnostics"
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+A signature parameter must start with \f(CW\*(Aq$\*(Aq\fR, \f(CW\*(Aq@\*(Aq\fR or \f(CW\*(Aq%\*(Aq\fR
+.IP \(bu 4
+Bareword in require contains "%s"
+.IP \(bu 4
+Bareword in require maps to empty filename
+.IP \(bu 4
+Bareword in require maps to disallowed filename "%s"
+.IP \(bu 4
+Bareword in require must not start with a double-colon: "%s"
+.IP \(bu 4
+\&\f(CW%s:\fR command not found
+.Sp
+(A) You've accidentally run your script through \fBbash\fR or another shell
+instead of Perl.  Check the \f(CW\*(C`#!\*(C'\fR line, or manually feed your script into
+Perl yourself.  The \f(CW\*(C`#!\*(C'\fR line at the top of your file could look like:
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl
+.Ve
+.IP \(bu 4
+\&\f(CW%s:\fR command not found: \f(CW%s\fR
+.Sp
+(A) You've accidentally run your script through \fBzsh\fR or another shell
+instead of Perl.  Check the \f(CW\*(C`#!\*(C'\fR line, or manually feed your script into
+Perl yourself.  The \f(CW\*(C`#!\*(C'\fR line at the top of your file could look like:
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl
+.Ve
+.IP \(bu 4
+The experimental declared_refs feature is not enabled
+.Sp
+(F) To declare references to variables, as in \f(CW\*(C`my \e%x\*(C'\fR, you must first enable
+the feature:
+.Sp
+.Vb 2
+\&    no warnings "experimental::declared_refs";
+\&    use feature "declared_refs";
+.Ve
+.Sp
+See "Declaring a reference to a variable".
+.IP \(bu 4
+Illegal character following sigil in a subroutine signature
+.IP \(bu 4
+Indentation on line \f(CW%d\fR of here-doc doesn't match delimiter
+.IP \(bu 4
+Infinite recursion via empty pattern.
+.Sp
+Using the empty pattern (which re-executes the last successfully-matched
+pattern) inside a code block in another regex, as in \f(CW\*(C`/(?{ s!!new! })/\*(C'\fR, has
+always previously yielded a segfault.  It now produces this error.
+.IP \(bu 4
+Malformed UTF\-8 string in "%s"
+.IP \(bu 4
+Multiple slurpy parameters not allowed
+.IP \(bu 4
+\&\f(CW\*(Aq#\*(Aq\fR not allowed immediately following a sigil in a subroutine signature
+.IP \(bu 4
+panic: unknown OA_*: \f(CW%x\fR
+.IP \(bu 4
+Unescaped left brace in regex is illegal here
+.Sp
+Unescaped left braces are now illegal in some contexts in regular expression
+patterns.  In other contexts, they are still just deprecated; they will
+be illegal in Perl 5.30.
+.IP \(bu 4
+Version control conflict marker
+.Sp
+(F) The parser found a line starting with \f(CW\*(C`<<<<<<<\*(C'\fR,
+\&\f(CW\*(C`>>>>>>>\*(C'\fR, or \f(CW\*(C`=======\*(C'\fR.  These may be left by a
+version control system to mark conflicts after a failed merge operation.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Can't determine class of operator \f(CW%s\fR, assuming \f(CW\*(C`BASEOP\*(C'\fR
+.IP \(bu 4
+Declaring references is experimental
+.Sp
+(S experimental::declared_refs) This warning is emitted if you use a reference
+constructor on the right-hand side of \f(CWmy()\fR, \f(CWstate()\fR, \f(CWour()\fR, or
+\&\f(CWlocal()\fR.  Simply suppress the warning if you want to use the feature, but
+know that in doing so you are taking the risk of using an experimental feature
+which may change or be removed in a future Perl version:
+.Sp
+.Vb 3
+\&    no warnings "experimental::declared_refs";
+\&    use feature "declared_refs";
+\&    $fooref = my \e$foo;
+.Ve
+.Sp
+See "Declaring a reference to a variable".
+.IP \(bu 4
+do "%s" failed, '.' is no longer in \f(CW@INC\fR
+.Sp
+Since \f(CW"."\fR is now removed from \f(CW@INC\fR by default, \f(CW\*(C`do\*(C'\fR will now trigger a warning recommending to fix the \f(CW\*(C`do\*(C'\fR statement.
+.IP \(bu 4
+\&\f(CWFile::Glob::glob()\fR will disappear in perl 5.30. Use \f(CWFile::Glob::bsd_glob()\fR instead.
+.IP \(bu 4
+Unescaped literal '%c' in regex; marked by <\-\- HERE in m/%s/
+.IP \(bu 4
+Use of unassigned code point or non-standalone grapheme for a delimiter will be a fatal error starting in Perl 5.30
+.Sp
+See "Deprecations"
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+When a \f(CW\*(C`require\*(C'\fR fails, we now do not provide \f(CW@INC\fR when the \f(CW\*(C`require\*(C'\fR
+is for a file instead of a module.
+.IP \(bu 4
+When \f(CW@INC\fR is not scanned for a \f(CW\*(C`require\*(C'\fR call, we no longer display
+\&\f(CW@INC\fR to avoid confusion.
+.IP \(bu 4
+Attribute "locked" is deprecated, and will disappear in Perl 5.28
+.Sp
+This existing warning has had the \fIand will disappear\fR text added in this
+release.
+.IP \(bu 4
+Attribute "unique" is deprecated, and will disappear in Perl 5.28
+.Sp
+This existing warning has had the \fIand will disappear\fR text added in this
+release.
+.IP \(bu 4
+Calling POSIX::%s() is deprecated
+.Sp
+This warning has been removed, as the deprecated functions have been
+removed from POSIX.
+.IP \(bu 4
+Constants from lexical variables potentially modified elsewhere are deprecated. This will not be allowed in Perl 5.32
+.Sp
+This existing warning has had the \fIthis will not be allowed\fR text added
+in this release.
+.IP \(bu 4
+Deprecated use of \f(CWmy()\fR in false conditional. This will be a fatal error in Perl 5.30
+.Sp
+This existing warning has had the \fIthis will be a fatal error\fR text added
+in this release.
+.IP \(bu 4
+\&\f(CWdump()\fR better written as \f(CWCORE::dump()\fR. \f(CWdump()\fR will no longer be available in Perl 5.30
+.Sp
+This existing warning has had the \fIno longer be available\fR text added in
+this release.
+.IP \(bu 4
+Experimental \f(CW%s\fR on scalar is now forbidden
+.Sp
+This message is now followed by more helpful text.
+[GH #15291] <https://github.com/Perl/perl5/issues/15291>
+.IP \(bu 4
+Experimental "%s" subs not enabled
+.Sp
+This warning was been removed, as lexical subs are no longer experimental.
+.IP \(bu 4
+Having more than one /%c regexp modifier is deprecated
+.Sp
+This deprecation warning has been removed, since \f(CW\*(C`/xx\*(C'\fR now has a new
+meaning.
+.IP \(bu 4
+%s() is deprecated on \f(CW\*(C`:utf8\*(C'\fR handles. This will be a fatal error in Perl 5.30
+\&.
+.Sp
+where "%s" is one of \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`recv\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, or \f(CW\*(C`send\*(C'\fR.
+.Sp
+This existing warning has had the \fIthis will be a fatal error\fR text added
+in this release.
+.Sp
+This warning is now enabled by default, as all \f(CW\*(C`deprecated\*(C'\fR category
+warnings should be.
+.IP \(bu 4
+\&\f(CW$*\fR is no longer supported. Its use will be fatal in Perl 5.30
+.Sp
+This existing warning has had the \fIits use will be fatal\fR text added in
+this release.
+.IP \(bu 4
+\&\f(CW$#\fR is no longer supported. Its use will be fatal in Perl 5.30
+.Sp
+This existing warning has had the \fIits use will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Malformed UTF\-8 character%s
+.Sp
+Details as to the exact problem have been added at the end of this
+message
+.IP \(bu 4
+Missing or undefined argument to \f(CW%s\fR
+.Sp
+This warning used to warn about \f(CW\*(C`require\*(C'\fR, even if it was actually \f(CW\*(C`do\*(C'\fR
+which being executed. It now gets the operation name right.
+.IP \(bu 4
+NO-BREAK SPACE in a charnames alias definition is deprecated
+.Sp
+This warning has been removed as the behavior is now an error.
+.IP \(bu 4
+Odd name/value argument for subroutine '%s'
+.Sp
+This warning now includes the name of the offending subroutine.
+.IP \(bu 4
+Opening dirhandle \f(CW%s\fR also as a file. This will be a fatal error in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be a fatal error\fR text added
+in this release.
+.IP \(bu 4
+Opening filehandle \f(CW%s\fR also as a directory. This will be a fatal error in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be a fatal error\fR text added
+in this release.
+.IP \(bu 4
+panic: ck_split, type=%u
+.Sp
+panic: pp_split, pm=%p, s=%p
+.Sp
+These panic errors have been removed.
+.IP \(bu 4
+Passing malformed UTF\-8 to "%s" is deprecated
+.Sp
+This warning has been changed to the fatal
+Malformed UTF\-8 string in "%s"
+.IP \(bu 4
+Setting \f(CW$/\fR to a reference to \f(CW%s\fR as a form of slurp is deprecated, treating as undef. This will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be fatal\fR text added in
+this release.
+.IP \(bu 4
+\&\f(CW\*(C`${^ENCODING}\*(C'\fR is no longer supported. Its use will be fatal in Perl 5.28
+.Sp
+This warning used to be: "Setting \f(CW\*(C`${^ENCODING}\*(C'\fR is deprecated".
+.Sp
+The special action of the variable \f(CW\*(C`${^ENCODING}\*(C'\fR was formerly used to
+implement the \f(CW\*(C`encoding\*(C'\fR pragma. As of Perl 5.26, rather than being
+deprecated, assigning to this variable now has no effect except to issue
+the warning.
+.IP \(bu 4
+Too few arguments for subroutine '%s'
+.Sp
+This warning now includes the name of the offending subroutine.
+.IP \(bu 4
+Too many arguments for subroutine '%s'
+.Sp
+This warning now includes the name of the offending subroutine.
+.IP \(bu 4
+Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <\-\-\ HERE in m/%s/
+.Sp
+This existing warning has had the \fIhere (and will be fatal...)\fR text
+added in this release.
+.IP \(bu 4
+Unknown charname '' is deprecated. Its use will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIits use will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Use of bare << to mean <<"" is deprecated. Its use will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIits use will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Use of code point 0x%s is deprecated; the permissible max is 0x%s.  This will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Use of comma-less variable list is deprecated. Its use will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIits use will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Use of inherited \f(CW\*(C`AUTOLOAD\*(C'\fR for non-method %s() is deprecated. This will be fatal in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be fatal\fR text added in
+this release.
+.IP \(bu 4
+Use of strings with code points over 0xFF as arguments to \f(CW%s\fR operator is deprecated. This will be a fatal error in Perl 5.28
+.Sp
+This existing warning has had the \fIthis will be a fatal error\fR text added in
+this release.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "\fIc2ph\fP and \fIpstruct\fP"
+.IX Subsection "c2ph and pstruct"
+.IP \(bu 4
+These old utilities have long since superceded by h2xs, and are
+now gone from the distribution.
+.SS \fIPorting/pod_lib.pl\fP
+.IX Subsection "Porting/pod_lib.pl"
+.IP \(bu 4
+Removed spurious executable bit.
+.IP \(bu 4
+Account for the possibility of DOS file endings.
+.SS \fIPorting/sync\-with\-cpan\fP
+.IX Subsection "Porting/sync-with-cpan"
+.IP \(bu 4
+Many improvements.
+.SS \fIperf/benchmarks\fP
+.IX Subsection "perf/benchmarks"
+.IP \(bu 4
+Tidy file, rename some symbols.
+.SS \fIPorting/checkAUTHORS.pl\fP
+.IX Subsection "Porting/checkAUTHORS.pl"
+.IP \(bu 4
+Replace obscure character range with \f(CW\*(C`\ew\*(C'\fR.
+.SS \fIt/porting/regen.t\fP
+.IX Subsection "t/porting/regen.t"
+.IP \(bu 4
+Try to be more helpful when tests fail.
+.SS \fIutils/h2xs.PL\fP
+.IX Subsection "utils/h2xs.PL"
+.IP \(bu 4
+Avoid infinite loop for enums.
+.SS perlbug
+.IX Subsection "perlbug"
+.IP \(bu 4
+Long lines in the message body are now wrapped at 900 characters, to stay
+well within the 1000\-character limit imposed by SMTP mail transfer agents.
+This is particularly likely to be important for the list of arguments to
+\&\fIConfigure\fR, which can readily exceed the limit if, for example, it names
+several non-default installation paths.  This change also adds the first unit
+tests for perlbug.
+[perl #128020] <https://rt.perl.org/Public/Bug/Display.html?id=128020>
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\f(CW\*(C`\-Ddefault_inc_excludes_dot\*(C'\fR has added, and enabled by default.
+.IP \(bu 4
+The \f(CW\*(C`dtrace\*(C'\fR build process has further changes
+[GH #15718] <https://github.com/Perl/perl5/issues/15718>:
+.RS 4
+.IP \(bu 4
+If the \f(CW\*(C`\-xnolibs\*(C'\fR is available, use that so a \fIdtrace\fR perl can be
+built within a FreeBSD jail.
+.IP \(bu 4
+On systems that build a \fIdtrace\fR object file (FreeBSD, Solaris, and
+SystemTap's dtrace emulation), copy the input objects to a separate
+directory and process them there, and use those objects in the link,
+since \f(CW\*(C`dtrace \-G\*(C'\fR also modifies these objects.
+.IP \(bu 4
+Add \fIlibelf\fR to the build on FreeBSD 10.x, since \fIdtrace\fR adds
+references to \fIlibelf\fR symbols.
+.IP \(bu 4
+Generate a dummy \fIdtrace_main.o\fR if \f(CW\*(C`dtrace \-G\*(C'\fR fails to build it.  A
+default build on Solaris generates probes from the unused inline
+functions, while they don't on FreeBSD, which causes \f(CW\*(C`dtrace \-G\*(C'\fR to
+fail.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+You can now disable perl's use of the \f(CW\*(C`PERL_HASH_SEED\*(C'\fR and
+\&\f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR environment variables by configuring perl with
+\&\f(CW\*(C`\-Accflags=NO_PERL_HASH_ENV\*(C'\fR.
+.IP \(bu 4
+You can now disable perl's use of the \f(CW\*(C`PERL_HASH_SEED_DEBUG\*(C'\fR environment
+variable by configuring perl with
+\&\f(CW\*(C`\-Accflags=\-DNO_PERL_HASH_SEED_DEBUG\*(C'\fR.
+.IP \(bu 4
+\&\fIConfigure\fR now zeroes out the alignment bytes when calculating the bytes
+for 80\-bit \f(CW\*(C`NaN\*(C'\fR and \f(CW\*(C`Inf\*(C'\fR to make builds more reproducible.
+[GH #15725] <https://github.com/Perl/perl5/issues/15725>
+.IP \(bu 4
+Since v5.18, for testing purposes we have included support for
+building perl with a variety of non-standard, and non-recommended
+hash functions.  Since we do not recommend the use of these functions,
+we have removed them and their corresponding build options.  Specifically
+this includes the following build options:
+.Sp
+.Vb 8
+\&    PERL_HASH_FUNC_SDBM
+\&    PERL_HASH_FUNC_DJB2
+\&    PERL_HASH_FUNC_SUPERFAST
+\&    PERL_HASH_FUNC_MURMUR3
+\&    PERL_HASH_FUNC_ONE_AT_A_TIME
+\&    PERL_HASH_FUNC_ONE_AT_A_TIME_OLD
+\&    PERL_HASH_FUNC_MURMUR_HASH_64A
+\&    PERL_HASH_FUNC_MURMUR_HASH_64B
+.Ve
+.IP \(bu 4
+Remove "Warning: perl appears in your path"
+.Sp
+This install warning is more or less obsolete, since most platforms already
+\&\fBwill\fR have a \fI/usr/bin/perl\fR or similar provided by the OS.
+.IP \(bu 4
+Reduce verbosity of \f(CW\*(C`make install.man\*(C'\fR
+.Sp
+Previously, two progress messages were emitted for each manpage: one by
+installman itself, and one by the function in \fIinstall_lib.pl\fR that it calls to
+actually install the file.  Disabling the second of those in each case saves
+over 750 lines of unhelpful output.
+.IP \(bu 4
+Cleanup for \f(CW\*(C`clang \-Weverything\*(C'\fR support.
+[GH #15683] <https://github.com/Perl/perl5/issues/15683>
+.IP \(bu 4
+\&\fIConfigure\fR: signbit scan was assuming too much, stop assuming negative 0.
+.IP \(bu 4
+Various compiler warnings have been silenced.
+.IP \(bu 4
+Several smaller changes have been made to remove impediments to compiling
+under C++11.
+.IP \(bu 4
+Builds using \f(CW\*(C`USE_PAD_RESET\*(C'\fR now work again; this configuration had
+bit-rotted.
+.IP \(bu 4
+A probe for \f(CW\*(C`gai_strerror\*(C'\fR was added to \fIConfigure\fR that checks if
+the \f(CWgai_strerror()\fR routine is available and can be used to
+translate error codes returned by \f(CWgetaddrinfo()\fR into human
+readable strings.
+.IP \(bu 4
+\&\fIConfigure\fR now aborts if both \f(CW\*(C`\-Duselongdouble\*(C'\fR and \f(CW\*(C`\-Dusequadmath\*(C'\fR are
+requested.
+[GH #14944] <https://github.com/Perl/perl5/issues/14944>
+.IP \(bu 4
+Fixed a bug in which \fIConfigure\fR could append \f(CW\*(C`\-quadmath\*(C'\fR to the
+archname even if it was already present.
+[GH #15423] <https://github.com/Perl/perl5/issues/15423>
+.IP \(bu 4
+Clang builds with \f(CW\*(C`\-DPERL_GLOBAL_STRUCT\*(C'\fR or
+\&\f(CW\*(C`\-DPERL_GLOBAL_STRUCT_PRIVATE\*(C'\fR have
+been fixed (by disabling Thread Safety Analysis for these configurations).
+.IP \(bu 4
+\&\fImake_ext.pl\fR no longer updates a module's \fIpm_to_blib\fR file when no
+files require updates.  This could cause dependencies, \fIperlmain.c\fR
+in particular, to be rebuilt unnecessarily.
+[GH #15060] <https://github.com/Perl/perl5/issues/15060>
+.IP \(bu 4
+The output of \f(CW\*(C`perl \-V\*(C'\fR has been reformatted so that each configuration
+and compile-time option is now listed one per line, to improve
+readability.
+.IP \(bu 4
+\&\fIConfigure\fR now builds \f(CW\*(C`miniperl\*(C'\fR and \f(CW\*(C`generate_uudmap\*(C'\fR if you
+invoke it with \f(CW\*(C`\-Dusecrosscompiler\*(C'\fR but not \f(CW\*(C`\-Dtargethost=somehost\*(C'\fR.
+This means you can supply your target platform \f(CW\*(C`config.sh\*(C'\fR, generate
+the headers and proceed to build your cross-target perl.
+[GH #15126] <https://github.com/Perl/perl5/issues/15126>
+.IP \(bu 4
+Perl built with \f(CW\*(C`\-Accflags=\-DPERL_TRACE_OPS\*(C'\fR now only dumps the operator
+counts when the environment variable \f(CW\*(C`PERL_TRACE_OPS\*(C'\fR is set to a
+non-zero integer.  This allows \f(CW\*(C`make test\*(C'\fR to pass on such a build.
+.IP \(bu 4
+When building with GCC 6 and link-time optimization (the \f(CW\*(C`\-flto\*(C'\fR option to
+\&\f(CW\*(C`gcc\*(C'\fR), \fIConfigure\fR was treating all probed symbols as present on the
+system, regardless of whether they actually exist.  This has been fixed.
+[GH #15322] <https://github.com/Perl/perl5/issues/15322>
+.IP \(bu 4
+The \fIt/test.pl\fR library is used for internal testing of Perl itself, and
+also copied by several CPAN modules.  Some of those modules must work on
+older versions of Perl, so \fIt/test.pl\fR must in turn avoid newer Perl
+features.  Compatibility with Perl 5.8 was inadvertently removed some time
+ago; it has now been restored.
+[GH #15302] <https://github.com/Perl/perl5/issues/15302>
+.IP \(bu 4
+The build process no longer emits an extra blank line before building each
+"simple" extension (those with only \fI*.pm\fR and \fI*.pod\fR files).
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes
+in this release.  Furthermore, these substantive changes were made:
+.IP \(bu 4
+A new test script, \fIcomp/parser_run.t\fR, has been added that is like
+\&\fIcomp/parser.t\fR but with \fItest.pl\fR included so that \f(CWrunperl()\fR and the
+like are available for use.
+.IP \(bu 4
+Tests for locales were erroneously using locales incompatible with Perl.
+.IP \(bu 4
+Some parts of the test suite that try to exhaustively test edge cases in the
+regex implementation have been restricted to running for a maximum of five
+minutes.  On slow systems they could otherwise take several hours, without
+significantly improving our understanding of the correctness of the code
+under test.
+.IP \(bu 4
+A new internal facility allows analysing the time taken by the individual
+tests in Perl's own test suite; see \fIPorting/harness\-timer\-report.pl\fR.
+.IP \(bu 4
+\&\fIt/re/regexp_nonull.t\fR has been added to test that the regular expression
+engine can handle scalars that do not have a null byte just past the end of
+the string.
+.IP \(bu 4
+A new test script, \fIt/op/decl\-refs.t\fR, has been added to test the new feature
+"Declaring a reference to a variable".
+.IP \(bu 4
+A new test script, \fIt/re/keep_tabs.t\fR has been added to contain tests
+where \f(CW\*(C`\et\*(C'\fR characters should not be expanded into spaces.
+.IP \(bu 4
+A new test script, \fIt/re/anyof.t\fR, has been added to test that the ANYOF nodes
+generated by bracketed character classes are as expected.
+.IP \(bu 4
+There is now more extensive testing of the Unicode-related API macros
+and functions.
+.IP \(bu 4
+Several of the longer running API test files have been split into
+multiple test files so that they can be run in parallel.
+.IP \(bu 4
+\&\fIt/harness\fR now tries really hard not to run tests which are located
+outside of the Perl source tree.
+[GH #14578] <https://github.com/Perl/perl5/issues/14578>
+.IP \(bu 4
+Prevent debugger tests (\fIlib/perl5db.t\fR) from failing due to the contents
+of \f(CW$ENV{PERLDB_OPTS}\fR.
+[GH #15782] <https://github.com/Perl/perl5/issues/15782>
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+.IP NetBSD/VAX 4
+.IX Item "NetBSD/VAX"
+Perl now compiles under NetBSD on VAX machines.  However, it's not
+possible for that platform to implement floating-point infinities and
+NaNs compatible with most modern systems, which implement the IEEE\-754
+floating point standard.  The hexadecimal floating point (\f(CW\*(C`0x...p[+\-]n\*(C'\fR
+literals, \f(CW\*(C`printf %a\*(C'\fR) is not implemented, either.
+The \f(CW\*(C`make test\*(C'\fR passes 98% of tests.
+.RS 4
+.IP \(bu 4
+Test fixes and minor updates.
+.IP \(bu 4
+Account for lack of \f(CW\*(C`inf\*(C'\fR, \f(CW\*(C`nan\*(C'\fR, and \f(CW\-0.0\fR support.
+.RE
+.RS 4
+.RE
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Darwin 4
+.IX Item "Darwin"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Don't treat \f(CW\*(C`\-Dprefix=/usr\*(C'\fR as special: instead require an extra option
+\&\f(CW\*(C`\-Ddarwin_distribution\*(C'\fR to produce the same results.
+.IP \(bu 4
+OS X El Capitan doesn't implement the \f(CWclock_gettime()\fR or
+\&\f(CWclock_getres()\fR APIs; emulate them as necessary.
+.IP \(bu 4
+Deprecated \f(CWsyscall(2)\fR on macOS 10.12.
+.RE
+.RS 4
+.RE
+.IP EBCDIC 4
+.IX Item "EBCDIC"
+Several tests have been updated to work (or be skipped) on EBCDIC platforms.
+.IP HP-UX 4
+.IX Item "HP-UX"
+The Net::Ping UDP test is now skipped on HP-UX.
+.IP Hurd 4
+.IX Item "Hurd"
+The hints for Hurd have been improved, enabling malloc wrap and reporting the
+GNU libc used (previously it was an empty string when reported).
+.IP VAX 4
+.IX Item "VAX"
+VAX floating point formats are now supported on NetBSD.
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The path separator for the \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`PERLLIB\*(C'\fR environment entries is
+now a colon (\f(CW":"\fR) when running under a Unix shell.  There is no change when
+running under DCL (it's still \f(CW"|"\fR).
+.IP \(bu 4
+\&\fIconfigure.com\fR now recognizes the VSI-branded C compiler and no longer
+recognizes the "DEC"\-branded C compiler (as there hasn't been such a thing for
+15 or more years).
+.RE
+.RS 4
+.RE
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Support for compiling perl on Windows using Microsoft Visual Studio 2015
+(containing Visual C++ 14.0) has been added.
+.Sp
+This version of VC++ includes a completely rewritten C run-time library, some
+of the changes in which mean that work done to resolve a socket
+\&\f(CWclose()\fR bug in
+perl #120091 and perl #118059 is not workable in its current state with this
+version of VC++.  Therefore, we have effectively reverted that bug fix for
+VS2015 onwards on the basis that being able to build with VS2015 onwards is
+more important than keeping the bug fix.  We may revisit this in the future to
+attempt to fix the bug again in a way that is compatible with VS2015.
+.Sp
+These changes do not affect compilation with GCC or with Visual Studio versions
+up to and including VS2013, \fIi.e.\fR, the bug fix is retained (unchanged) for those
+compilers.
+.Sp
+Note that you may experience compatibility problems if you mix a perl built
+with GCC or VS <= VS2013 with XS modules built with VS2015, or if you mix a
+perl built with VS2015 with XS modules built with GCC or VS <= VS2013.
+Some incompatibility may arise because of the bug fix that has been reverted
+for VS2015 builds of perl, but there may well be incompatibility anyway because
+of the rewritten CRT in VS2015 (\fIe.g.\fR, see discussion at
+<http://stackoverflow.com/questions/30412951>).
+.IP \(bu 4
+It now automatically detects GCC versus Visual C and sets the VC version
+number on Win32.
+.RE
+.RS 4
+.RE
+.IP Linux 4
+.IX Item "Linux"
+Drop support for Linux \fIa.out\fR executable format. Linux has used ELF for
+over twenty years.
+.IP "OpenBSD 6" 4
+.IX Item "OpenBSD 6"
+OpenBSD 6 still does not support returning \f(CW\*(C`pid\*(C'\fR, \f(CW\*(C`gid\*(C'\fR, or \f(CW\*(C`uid\*(C'\fR with
+\&\f(CW\*(C`SA_SIGINFO\*(C'\fR.  Make sure to account for it.
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+\&\fIt/uni/overload.t\fR: Skip hanging test on FreeBSD.
+.IP "DragonFly BSD" 4
+.IX Item "DragonFly BSD"
+DragonFly BSD now has support for \f(CWsetproctitle()\fR.
+[GH #15703] <https://github.com/Perl/perl5/issues/15703>.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+A new API function \f(CWsv_setpv_bufsize()\fR
+allows simultaneously setting the
+length and the allocated size of the buffer in an \f(CW\*(C`SV\*(C'\fR, growing the
+buffer if necessary.
+.IP \(bu 4
+A new API macro \f(CWSvPVCLEAR()\fR sets its \f(CW\*(C`SV\*(C'\fR
+argument to an empty string,
+like Perl-space \f(CW\*(C`$x = \*(Aq\*(Aq\*(C'\fR, but with several optimisations.
+.IP \(bu 4
+Several new macros and functions for dealing with Unicode and
+UTF\-8\-encoded strings have been added to the API, as well as some
+changes in the
+functionality of existing functions (see "Unicode Support" in perlapi for
+more details):
+.RS 4
+.IP \(bu 4
+New versions of the API macros like \f(CW\*(C`isALPHA_utf8\*(C'\fR and \f(CW\*(C`toLOWER_utf8\*(C'\fR
+have been added, each with the suffix \f(CW\*(C`_safe\*(C'\fR, like
+\&\f(CW\*(C`isSPACE_utf8_safe\*(C'\fR.  These take an extra
+parameter, giving an upper
+limit of how far into the string it is safe to read.  Using the old
+versions could cause attempts to read beyond the end of the input buffer
+if the UTF\-8 is not well-formed, and their use now raises a deprecation
+warning.  Details are at "Character classification" in perlapi.
+.IP \(bu 4
+Macros like \f(CW\*(C`isALPHA_utf8\*(C'\fR and
+\&\f(CW\*(C`toLOWER_utf8\*(C'\fR now die if they detect
+that their input UTF\-8 is malformed.  A deprecation warning had been
+issued since Perl 5.18.
+.IP \(bu 4
+Several new macros for analysing the validity of utf8 sequences. These
+are:
+.Sp
+\&\f(CW\*(C`UTF8_GOT_ABOVE_31_BIT\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_CONTINUATION\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_EMPTY\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_LONG\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_NONCHAR\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_OVERFLOW\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_SUPER\*(C'\fR
+\&\f(CW\*(C`UTF8_GOT_SURROGATE\*(C'\fR
+\&\f(CW\*(C`UTF8_IS_INVARIANT\*(C'\fR
+\&\f(CW\*(C`UTF8_IS_NONCHAR\*(C'\fR
+\&\f(CW\*(C`UTF8_IS_SUPER\*(C'\fR
+\&\f(CW\*(C`UTF8_IS_SURROGATE\*(C'\fR
+\&\f(CW\*(C`UVCHR_IS_INVARIANT\*(C'\fR
+\&\f(CW\*(C`isUTF8_CHAR_flags\*(C'\fR
+\&\f(CW\*(C`isSTRICT_UTF8_CHAR\*(C'\fR
+\&\f(CW\*(C`isC9_STRICT_UTF8_CHAR\*(C'\fR
+.IP \(bu 4
+Functions that are all extensions of the \f(CW\*(C`is_utf8_string_\fR\f(CI*\fR\f(CW()\*(C'\fR functions,
+that apply various restrictions to the UTF\-8 recognized as valid:
+.Sp
+\&\f(CW\*(C`is_strict_utf8_string\*(C'\fR,
+\&\f(CW\*(C`is_strict_utf8_string_loc\*(C'\fR,
+\&\f(CW\*(C`is_strict_utf8_string_loclen\*(C'\fR,
+.Sp
+\&\f(CW\*(C`is_c9strict_utf8_string\*(C'\fR,
+\&\f(CW\*(C`is_c9strict_utf8_string_loc\*(C'\fR,
+\&\f(CW\*(C`is_c9strict_utf8_string_loclen\*(C'\fR,
+.Sp
+\&\f(CW\*(C`is_utf8_string_flags\*(C'\fR,
+\&\f(CW\*(C`is_utf8_string_loc_flags\*(C'\fR,
+\&\f(CW\*(C`is_utf8_string_loclen_flags\*(C'\fR,
+.Sp
+\&\f(CW\*(C`is_utf8_fixed_width_buf_flags\*(C'\fR,
+\&\f(CW\*(C`is_utf8_fixed_width_buf_loc_flags\*(C'\fR,
+\&\f(CW\*(C`is_utf8_fixed_width_buf_loclen_flags\*(C'\fR.
+.Sp
+\&\f(CW\*(C`is_utf8_invariant_string\*(C'\fR.
+\&\f(CW\*(C`is_utf8_valid_partial_char\*(C'\fR.
+\&\f(CW\*(C`is_utf8_valid_partial_char_flags\*(C'\fR.
+.IP \(bu 4
+The functions \f(CW\*(C`utf8n_to_uvchr\*(C'\fR and its
+derivatives have had several changes of behaviour.
+.Sp
+Calling them, while passing a string length of 0 is now asserted against
+in DEBUGGING builds, and otherwise, returns the Unicode REPLACEMENT
+CHARACTER.   If you have nothing to decode, you shouldn't call the decode
+function.
+.Sp
+They now return the Unicode REPLACEMENT CHARACTER if called with UTF\-8
+that has the overlong malformation and that malformation is allowed by
+the input parameters.  This malformation is where the UTF\-8 looks valid
+syntactically, but there is a shorter sequence that yields the same code
+point.  This has been forbidden since Unicode version 3.1.
+.Sp
+They now accept an input
+flag to allow the overflow malformation.  This malformation is when the
+UTF\-8 may be syntactically valid, but the code point it represents is
+not capable of being represented in the word length on the platform.
+What "allowed" means, in this case, is that the function doesn't return an
+error, and it advances the parse pointer to beyond the UTF\-8 in
+question, but it returns the Unicode REPLACEMENT CHARACTER as the value
+of the code point (since the real value is not representable).
+.Sp
+They no longer abandon searching for other malformations when the first
+one is encountered.  A call to one of these functions thus can generate
+multiple diagnostics, instead of just one.
+.IP \(bu 4
+\&\f(CWvalid_utf8_to_uvchr()\fR has been added
+to the API (although it was
+present in core earlier). Like \f(CWutf8_to_uvchr_buf()\fR, but assumes that
+the next character is well-formed.  Use with caution.
+.IP \(bu 4
+A new function, \f(CW\*(C`utf8n_to_uvchr_error\*(C'\fR,
+has been added for
+use by modules that need to know the details of UTF\-8 malformations
+beyond pass/fail.  Previously, the only ways to know why a sequence was
+ill-formed was to capture and parse the generated diagnostics or to do
+your own analysis.
+.IP \(bu 4
+There is now a safer version of \fButf8_hop()\fR, called
+\&\f(CWutf8_hop_safe()\fR.
+Unlike \fButf8_hop()\fR, \fButf8_hop_safe()\fR won't navigate before the beginning or
+after the end of the supplied buffer.
+.IP \(bu 4
+Two new functions, \f(CWutf8_hop_forward()\fR and
+\&\f(CWutf8_hop_back()\fR are
+similar to \f(CWutf8_hop_safe()\fR but are for when you know which direction
+you wish to travel.
+.IP \(bu 4
+Two new macros which return useful utf8 byte sequences:
+.Sp
+\&\f(CW\*(C`BOM_UTF8\*(C'\fR
+.Sp
+\&\f(CW\*(C`REPLACEMENT_CHARACTER_UTF8\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Perl is now built with the \f(CW\*(C`PERL_OP_PARENT\*(C'\fR compiler define enabled by
+default.  To disable it, use the \f(CW\*(C`PERL_NO_OP_PARENT\*(C'\fR compiler define.
+This flag alters how the \f(CW\*(C`op_sibling\*(C'\fR field is used in \f(CW\*(C`OP\*(C'\fR structures,
+and has been available optionally since perl 5.22.
+.Sp
+See "Internal Changes" in perl5220delta for more details of what this
+build option does.
+.IP \(bu 4
+Three new ops, \f(CW\*(C`OP_ARGELEM\*(C'\fR, \f(CW\*(C`OP_ARGDEFELEM\*(C'\fR, and \f(CW\*(C`OP_ARGCHECK\*(C'\fR have
+been added.  These are intended principally to implement the individual
+elements of a subroutine signature, plus any overall checking required.
+.IP \(bu 4
+The \f(CW\*(C`OP_PUSHRE\*(C'\fR op has been eliminated and the \f(CW\*(C`OP_SPLIT\*(C'\fR op has been
+changed from class \f(CW\*(C`LISTOP\*(C'\fR to \f(CW\*(C`PMOP\*(C'\fR.
+.Sp
+Formerly the first child of a split would be a \f(CW\*(C`pushre\*(C'\fR, which would have the
+\&\f(CW\*(C`split\*(C'\fR's regex attached to it. Now the regex is attached directly to the
+\&\f(CW\*(C`split\*(C'\fR op, and the \f(CW\*(C`pushre\*(C'\fR has been eliminated.
+.IP \(bu 4
+The \f(CWop_class()\fR API function has been added.  This
+is like the existing
+\&\f(CWOP_CLASS()\fR macro, but can more accurately determine what struct an op
+has been allocated as.  For example \f(CWOP_CLASS()\fR might return
+\&\f(CW\*(C`OA_BASEOP_OR_UNOP\*(C'\fR indicating that ops of this type are usually
+allocated as an \f(CW\*(C`OP\*(C'\fR or \f(CW\*(C`UNOP\*(C'\fR; while \f(CWop_class()\fR will return
+\&\f(CW\*(C`OPclass_BASEOP\*(C'\fR or \f(CW\*(C`OPclass_UNOP\*(C'\fR as appropriate.
+.IP \(bu 4
+All parts of the internals now agree that the \f(CW\*(C`sassign\*(C'\fR op is a \f(CW\*(C`BINOP\*(C'\fR;
+previously it was listed as a \f(CW\*(C`BASEOP\*(C'\fR in \fIregen/opcodes\fR, which meant
+that several parts of the internals had to be special-cased to accommodate
+it.  This oddity's original motivation was to handle code like \f(CW\*(C`$x ||= 1\*(C'\fR;
+that is now handled in a simpler way.
+.IP \(bu 4
+The output format of the \f(CWop_dump()\fR function (as
+used by \f(CW\*(C`perl \-Dx\*(C'\fR)
+has changed: it now displays an "ASCII-art" tree structure, and shows more
+low-level details about each op, such as its address and class.
+.IP \(bu 4
+The \f(CW\*(C`PADOFFSET\*(C'\fR type has changed from being unsigned to signed, and
+several pad-related variables such as \f(CW\*(C`PL_padix\*(C'\fR have changed from being
+of type \f(CW\*(C`I32\*(C'\fR to type \f(CW\*(C`PADOFFSET\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`DEBUGGING\*(C'\fR\-mode output for regex compilation and execution has been
+enhanced.
+.IP \(bu 4
+Several obscure SV flags have been eliminated, sometimes along with the
+macros which manipulate them: \f(CW\*(C`SVpbm_VALID\*(C'\fR, \f(CW\*(C`SVpbm_TAIL\*(C'\fR, \f(CW\*(C`SvTAIL_on\*(C'\fR,
+\&\f(CW\*(C`SvTAIL_off\*(C'\fR, \f(CW\*(C`SVrepl_EVAL\*(C'\fR, \f(CW\*(C`SvEVALED\*(C'\fR.
+.IP \(bu 4
+An OP \f(CW\*(C`op_private\*(C'\fR flag has been eliminated: \f(CW\*(C`OPpRUNTIME\*(C'\fR. This used to
+often get set on \f(CW\*(C`PMOP\*(C'\fR ops, but had become meaningless over time.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Perl no longer panics when switching into some locales on machines with
+buggy \f(CWstrxfrm()\fR implementations in their \fIlibc\fR.
+[GH #13768] <https://github.com/Perl/perl5/issues/13768>
+.IP \(bu 4
+\&\f(CW\*(C` $\-{$name} \*(C'\fR would leak an \f(CW\*(C`AV\*(C'\fR on each access if the regular
+expression had no named captures.  The same applies to access to any
+hash tied with Tie::Hash::NamedCapture and \f(CW\*(C`all => 1\*(C'\fR.
+[GH #15882] <https://github.com/Perl/perl5/issues/15882>
+.IP \(bu 4
+Attempting to use the deprecated variable \f(CW$#\fR as the object in an
+indirect object method call could cause a heap use after free or
+buffer overflow.
+[GH #15599] <https://github.com/Perl/perl5/issues/15599>
+.IP \(bu 4
+When checking for an indirect object method call, in some rare cases
+the parser could reallocate the line buffer but then continue to use
+pointers to the old buffer.
+[GH #15585] <https://github.com/Perl/perl5/issues/15585>
+.IP \(bu 4
+Supplying a glob as the format argument to
+\&\f(CW\*(C`formline\*(C'\fR would
+cause an assertion failure.
+[GH #15862] <https://github.com/Perl/perl5/issues/15862>
+.IP \(bu 4
+Code like \f(CW\*(C` $value1 =~ qr/.../ ~~ $value2 \*(C'\fR would have the match
+converted into a \f(CW\*(C`qr//\*(C'\fR operator, leaving extra elements on the stack to
+confuse any surrounding expression.
+[GH #15859] <https://github.com/Perl/perl5/issues/15859>
+.IP \(bu 4
+Since v5.24 in some obscure cases, a regex which included code blocks
+from multiple sources (\fIe.g.\fR, via embedded via \f(CW\*(C`qr//\*(C'\fR objects) could end up
+with the wrong current pad and crash or give weird results.
+[GH #15657] <https://github.com/Perl/perl5/issues/15657>
+.IP \(bu 4
+Occasionally \f(CWlocal()\fRs in a code block within a patterns weren't being
+undone when the pattern matching backtracked over the code block.
+[GH #15056] <https://github.com/Perl/perl5/issues/15056>
+.IP \(bu 4
+Using \f(CWsubstr()\fR to modify a magic variable could access freed memory
+in some cases.
+[GH #15871] <https://github.com/Perl/perl5/issues/15871>
+.IP \(bu 4
+Under \f(CW\*(C`use utf8\*(C'\fR, the entire source code is now checked for being UTF\-8
+well formed, not just quoted strings as before.
+[GH #14973] <https://github.com/Perl/perl5/issues/14973>.
+.IP \(bu 4
+The range operator \f(CW".."\fR on strings now handles its arguments correctly when in
+the scope of the \f(CW\*(C`unicode_strings\*(C'\fR
+feature.  The previous behaviour was sufficiently unexpected that we believe no
+correct program could have made use of it.
+.IP \(bu 4
+The \f(CW\*(C`split\*(C'\fR operator did not ensure enough space was allocated for
+its return value in scalar context.  It could then write a single
+pointer immediately beyond the end of the memory block allocated for
+the stack.
+[GH #15749] <https://github.com/Perl/perl5/issues/15749>
+.IP \(bu 4
+Using a large code point with the \f(CW"W"\fR pack template character with
+the current output position aligned at just the right point could
+cause a write of a single zero byte immediately beyond the end of an
+allocated buffer.
+[GH #15572] <https://github.com/Perl/perl5/issues/15572>
+.IP \(bu 4
+Supplying a format's picture argument as part of the format argument list
+where the picture specifies modifying the argument could cause an
+access to the new freed compiled format.
+[GH #15566] <https://github.com/Perl/perl5/issues/15566>
+.IP \(bu 4
+The \fBsort()\fR operator's built-in numeric comparison
+function didn't handle large integers that weren't exactly
+representable by a double.  This now uses the same code used to
+implement the \f(CW\*(C`<=>\*(C'\fR operator.
+[GH #15768] <https://github.com/Perl/perl5/issues/15768>
+.IP \(bu 4
+Fix issues with \f(CW\*(C`/(?{ ... <<EOF })/\*(C'\fR that broke
+Method::Signatures.
+[GH #15779] <https://github.com/Perl/perl5/issues/15779>
+.IP \(bu 4
+Fixed an assertion failure with \f(CW\*(C`chop\*(C'\fR and \f(CW\*(C`chomp\*(C'\fR, which
+could be triggered by \f(CW\*(C`chop(@x =~ tr/1/1/)\*(C'\fR.
+[GH #15738] <https://github.com/Perl/perl5/issues/15738>.
+.IP \(bu 4
+Fixed a comment skipping error in patterns under \f(CW\*(C`/x\*(C'\fR; it could stop
+skipping a byte early, which could be in the middle of a UTF\-8
+character.
+[GH #15790] <https://github.com/Perl/perl5/issues/15790>.
+.IP \(bu 4
+\&\fIperldb\fR now ignores \fI/dev/tty\fR on non-Unix systems.
+[GH #12244] <https://github.com/Perl/perl5/issues/12244>;
+.IP \(bu 4
+Fix assertion failure for \f(CW\*(C`{}\->$x\*(C'\fR when \f(CW$x\fR isn't defined.
+[GH #15791] <https://github.com/Perl/perl5/issues/15791>.
+.IP \(bu 4
+Fix an assertion error which could be triggered when a lookahead string
+in patterns exceeded a minimum length.
+[GH #15796] <https://github.com/Perl/perl5/issues/15796>.
+.IP \(bu 4
+Only warn once per literal number about a misplaced \f(CW"_"\fR.
+[GH #9989] <https://github.com/Perl/perl5/issues/9989>.
+.IP \(bu 4
+The \f(CW\*(C`tr///\*(C'\fR parse code could be looking at uninitialized data after a
+perse error.
+[GH #15624] <https://github.com/Perl/perl5/issues/15624>.
+.IP \(bu 4
+In a pattern match, a back-reference (\f(CW\*(C`\e1\*(C'\fR) to an unmatched capture could
+read back beyond the start of the string being matched.
+[GH #15634] <https://github.com/Perl/perl5/issues/15634>.
+.IP \(bu 4
+\&\f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR is supposed to warn if you use a range (such as
+\&\f(CW\*(C`/(?[ [ X\-Y ] ])/\*(C'\fR) whose start and end digit aren't from the same group
+of 10.  It didn't do that for five groups of mathematical digits starting
+at \f(CW\*(C`U+1D7E\*(C'\fR.
+.IP \(bu 4
+A sub containing a "forward" declaration with the same name (\fIe.g.\fR,
+\&\f(CW\*(C`sub c { sub c; }\*(C'\fR) could sometimes crash or loop infinitely.
+[GH #15557] <https://github.com/Perl/perl5/issues/15557>
+.IP \(bu 4
+A crash in executing a regex with a non-anchored UTF\-8 substring against a
+target string that also used UTF\-8 has been fixed.
+[GH #15628] <https://github.com/Perl/perl5/issues/15628>
+.IP \(bu 4
+Previously, a shebang line like \f(CW\*(C`#!perl \-i u\*(C'\fR could be erroneously
+interpreted as requesting the \f(CW\*(C`\-u\*(C'\fR option.  This has been fixed.
+[GH #15623] <https://github.com/Perl/perl5/issues/15623>
+.IP \(bu 4
+The regex engine was previously producing incorrect results in some rare
+situations when backtracking past an alternation that matches only one
+thing; this
+showed up as capture buffers (\f(CW$1\fR, \f(CW$2\fR, \fIetc.\fR) erroneously containing data
+from regex execution paths that weren't actually executed for the final
+match.
+[GH #15666] <https://github.com/Perl/perl5/issues/15666>
+.IP \(bu 4
+Certain regexes making use of the experimental \f(CW\*(C`regex_sets\*(C'\fR feature could
+trigger an assertion failure.  This has been fixed.
+[GH #15620] <https://github.com/Perl/perl5/issues/15620>
+.IP \(bu 4
+Invalid assignments to a reference constructor (\fIe.g.\fR, \f(CW\*(C`\eeval=time\*(C'\fR) could
+sometimes crash in addition to giving a syntax error.
+[GH #14815] <https://github.com/Perl/perl5/issues/14815>
+.IP \(bu 4
+The parser could sometimes crash if a bareword came after \f(CW\*(C`evalbytes\*(C'\fR.
+[GH #15586] <https://github.com/Perl/perl5/issues/15586>
+.IP \(bu 4
+Autoloading via a method call would warn erroneously ("Use of inherited
+AUTOLOAD for non-method") if there was a stub present in the package into
+which the invocant had been blessed.  The warning is no longer emitted in
+such circumstances.
+[GH #9094] <https://github.com/Perl/perl5/issues/9094>
+.IP \(bu 4
+The use of \f(CW\*(C`splice\*(C'\fR on arrays with non-existent elements could cause other
+operators to crash.
+[GH #15577] <https://github.com/Perl/perl5/issues/15577>
+.IP \(bu 4
+A possible buffer overrun when a pattern contains a fixed utf8 substring.
+[GH #15534] <https://github.com/Perl/perl5/issues/15534>
+.IP \(bu 4
+Fixed two possible use-after-free bugs in perl's lexer.
+[GH #15549] <https://github.com/Perl/perl5/issues/15549>
+.IP \(bu 4
+Fixed a crash with \f(CW\*(C`s///l\*(C'\fR where it thought it was dealing with UTF\-8
+when it wasn't.
+[GH #15543] <https://github.com/Perl/perl5/issues/15543>
+.IP \(bu 4
+Fixed a place where the regex parser was not setting the syntax error
+correctly on a syntactically incorrect pattern.
+[GH #15565] <https://github.com/Perl/perl5/issues/15565>
+.IP \(bu 4
+The \f(CW\*(C`&.\*(C'\fR operator (and the \f(CW"&"\fR operator, when it treats its arguments as
+strings) were failing to append a trailing null byte if at least one string
+was marked as utf8 internally.  Many code paths (system calls, regexp
+compilation) still expect there to be a null byte in the string buffer
+just past the end of the logical string.  An assertion failure was the
+result.
+[GH #15606] <https://github.com/Perl/perl5/issues/15606>
+.IP \(bu 4
+Avoid a heap-after-use error in the parser when creating an error messge
+for a syntactically invalid heredoc.
+[GH #15527] <https://github.com/Perl/perl5/issues/15527>
+.IP \(bu 4
+Fix a segfault when run with \f(CW\*(C`\-DC\*(C'\fR options on DEBUGGING builds.
+[GH #15563] <https://github.com/Perl/perl5/issues/15563>
+.IP \(bu 4
+Fixed the parser error handling in subroutine attributes for an
+\&'\f(CW\*(C`:attr(foo\*(C'\fR' that does not have an ending '\f(CW")"\fR'.
+.IP \(bu 4
+Fix the perl lexer to correctly handle a backslash as the last char in
+quoted-string context. This actually fixed two bugs,
+[GH #15546] <https://github.com/Perl/perl5/issues/15546> and
+[GH #15582] <https://github.com/Perl/perl5/issues/15582>.
+.IP \(bu 4
+In the API function \f(CW\*(C`gv_fetchmethod_pvn_flags\*(C'\fR, rework separator parsing
+to prevent possible string overrun with an invalid \f(CW\*(C`len\*(C'\fR argument.
+[GH #15598] <https://github.com/Perl/perl5/issues/15598>
+.IP \(bu 4
+Problems with in-place array sorts: code like \f(CW\*(C`@a = sort { ... } @a\*(C'\fR,
+where the source and destination of the sort are the same plain array, are
+optimised to do less copying around.  Two side-effects of this optimisation
+were that the contents of \f(CW@a\fR as seen by sort routines were
+partially sorted; and under some circumstances accessing \f(CW@a\fR during the
+sort could crash the interpreter.  Both these issues have been fixed, and
+Sort functions see the original value of \f(CW@a\fR.
+[GH #15387] <https://github.com/Perl/perl5/issues/15387>
+.IP \(bu 4
+Non-ASCII string delimiters are now reported correctly in error messages
+for unterminated strings.
+[GH #15469] <https://github.com/Perl/perl5/issues/15469>
+.IP \(bu 4
+\&\f(CW\*(C`pack("p", ...)\*(C'\fR used to emit its warning ("Attempt to pack pointer to
+temporary value") erroneously in some cases, but has been fixed.
+.IP \(bu 4
+\&\f(CW@DB::args\fR is now exempt from "used once" warnings.  The warnings only
+occurred under \fB\-w\fR, because \fIwarnings.pm\fR itself uses \f(CW@DB::args\fR
+multiple times.
+.IP \(bu 4
+The use of built-in arrays or hash slices in a double-quoted string no
+longer issues a warning ("Possible unintended interpolation...") if the
+variable has not been mentioned before.  This affected code like
+\&\f(CW\*(C`qq|@DB::args|\*(C'\fR and \f(CW\*(C`qq|@SIG{\*(AqCHLD\*(Aq, \*(AqHUP\*(Aq}|\*(C'\fR.  (The special variables
+\&\f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR were already exempt from the warning.)
+.IP \(bu 4
+\&\f(CW\*(C`gethostent\*(C'\fR and similar functions now perform a null check internally, to
+avoid crashing with the torsocks library.  This was a regression from v5.22.
+[GH #15478] <https://github.com/Perl/perl5/issues/15478>
+.IP \(bu 4
+\&\f(CW\*(C`defined *{\*(Aq!\*(Aq}\*(C'\fR, \f(CW\*(C`defined *{\*(Aq[\*(Aq}\*(C'\fR, and \f(CW\*(C`defined *{\*(Aq\-\*(Aq}\*(C'\fR no longer leak
+memory if the typeglob in question has never been accessed before.
+.IP \(bu 4
+Mentioning the same constant twice in a row (which is a syntax error) no
+longer fails an assertion under debugging builds.  This was a regression
+from v5.20.
+[GH #15017] <https://github.com/Perl/perl5/issues/15017>
+.IP \(bu 4
+Many issues relating to \f(CW\*(C`printf "%a"\*(C'\fR of hexadecimal floating point
+were fixed.  In addition, the "subnormals" (formerly known as "denormals")
+floating point numbers are now supported both with the plain IEEE 754
+floating point numbers (64\-bit or 128\-bit) and the x86 80\-bit
+"extended precision".  Note that subnormal hexadecimal floating
+point literals will give a warning about "exponent underflow".
+[GH #15495] <https://github.com/Perl/perl5/issues/15495>
+[GH #15503] <https://github.com/Perl/perl5/issues/15503>
+[GH #15504] <https://github.com/Perl/perl5/issues/15504>
+[GH #15505] <https://github.com/Perl/perl5/issues/15505>
+[GH #15510] <https://github.com/Perl/perl5/issues/15510>
+[GH #15512] <https://github.com/Perl/perl5/issues/15512>
+.IP \(bu 4
+A regression in v5.24 with \f(CW\*(C`tr/\eN{U+...}/foo/\*(C'\fR when the code point was between
+128 and 255 has been fixed.
+[GH #15475] <https://github.com/Perl/perl5/issues/15475>.
+.IP \(bu 4
+Use of a string delimiter whose code point is above 2**31 now works
+correctly on platforms that allow this.  Previously, certain characters,
+due to truncation, would be confused with other delimiter characters
+with special meaning (such as \f(CW"?"\fR in \f(CW\*(C`m?...?\*(C'\fR), resulting
+in inconsistent behaviour.  Note that this is non-portable,
+and is based on Perl's extension to UTF\-8, and is probably not
+displayable nor enterable by any editor.
+[GH #15477] <https://github.com/Perl/perl5/issues/15477>
+.IP \(bu 4
+\&\f(CW\*(C`@{x\*(C'\fR followed by a newline where \f(CW"x"\fR represents a control or non-ASCII
+character no longer produces a garbled syntax error message or a crash.
+[GH #15518] <https://github.com/Perl/perl5/issues/15518>
+.IP \(bu 4
+An assertion failure with \f(CW\*(C`%: = 0\*(C'\fR has been fixed.
+[GH #15358] <https://github.com/Perl/perl5/issues/15358>
+.IP \(bu 4
+In Perl 5.18, the parsing of \f(CW"$foo::$bar"\fR was accidentally changed, such
+that it would be treated as \f(CW\*(C`$foo."::".$bar\*(C'\fR.  The previous behavior, which
+was to parse it as \f(CW\*(C`$foo:: . $bar\*(C'\fR, has been restored.
+[GH #15408] <https://github.com/Perl/perl5/issues/15408>
+.IP \(bu 4
+Since Perl 5.20, line numbers have been off by one when perl is invoked with
+the \fB\-x\fR switch.  This has been fixed.
+[GH #15413] <https://github.com/Perl/perl5/issues/15413>
+.IP \(bu 4
+Vivifying a subroutine stub in a deleted stash (\fIe.g.\fR,
+\&\f(CW\*(C`delete $My::{"Foo::"}; \e&My::Foo::foo\*(C'\fR) no longer crashes.  It had begun
+crashing in Perl 5.18.
+[GH #15420] <https://github.com/Perl/perl5/issues/15420>
+.IP \(bu 4
+Some obscure cases of subroutines and file handles being freed at the same time
+could result in crashes, but have been fixed.  The crash was introduced in Perl
+5.22.
+[GH #15435] <https://github.com/Perl/perl5/issues/15435>
+.IP \(bu 4
+Code that looks for a variable name associated with an uninitialized value
+could cause an assertion failure in cases where magic is involved, such as
+\&\f(CW\*(C`$ISA[0][0]\*(C'\fR.  This has now been fixed.
+[GH #15364] <https://github.com/Perl/perl5/issues/15364>
+.IP \(bu 4
+A crash caused by code generating the warning "Subroutine STASH::NAME
+redefined" in cases such as \f(CW\*(C`sub P::f{} undef *P::; *P::f =sub{};\*(C'\fR has been
+fixed.  In these cases, where the STASH is missing, the warning will now appear
+as "Subroutine NAME redefined".
+[GH #15368] <https://github.com/Perl/perl5/issues/15368>
+.IP \(bu 4
+Fixed an assertion triggered by some code that handles deprecated behavior in
+formats, \fIe.g.\fR, in cases like this:
+.Sp
+.Vb 3
+\&    format STDOUT =
+\&    @
+\&    0"$x"
+.Ve
+.Sp
+[GH #15366] <https://github.com/Perl/perl5/issues/15366>
+.IP \(bu 4
+A possible divide by zero in string transformation code on Windows has been
+avoided, fixing a crash when collating an empty string.
+[GH #15439] <https://github.com/Perl/perl5/issues/15439>
+.IP \(bu 4
+Some regular expression parsing glitches could lead to assertion failures with
+regular expressions such as \f(CW\*(C`/(?<=/\*(C'\fR and \f(CW\*(C`/(?<!/\*(C'\fR.  This has now been fixed.
+[GH #15332] <https://github.com/Perl/perl5/issues/15332>
+.IP \(bu 4
+\&\f(CW\*(C` until ($x = 1) { ... } \*(C'\fR and \f(CW\*(C` ... until $x = 1 \*(C'\fR now properly
+warn when syntax warnings are enabled.
+[GH #15138] <https://github.com/Perl/perl5/issues/15138>
+.IP \(bu 4
+\&\fBsocket()\fR now leaves the error code returned by the system in \f(CW$!\fR on
+failure.
+[GH #15383] <https://github.com/Perl/perl5/issues/15383>
+.IP \(bu 4
+Assignment variants of any bitwise ops under the \f(CW\*(C`bitwise\*(C'\fR feature would
+crash if the left-hand side was an array or hash.
+[GH #15346] <https://github.com/Perl/perl5/issues/15346>
+.IP \(bu 4
+\&\f(CW\*(C`require\*(C'\fR followed by a single colon (as in \f(CW\*(C`foo() ? require : ...\*(C'\fR is
+now parsed correctly as \f(CW\*(C`require\*(C'\fR with implicit \f(CW$_\fR, rather than
+\&\f(CW\*(C`require ""\*(C'\fR.
+[GH #15380] <https://github.com/Perl/perl5/issues/15380>
+.IP \(bu 4
+Scalar \f(CW\*(C`keys %hash\*(C'\fR can now be assigned to consistently in all scalar
+lvalue contexts.  Previously it worked for some contexts but not others.
+.IP \(bu 4
+List assignment to \f(CW\*(C`vec\*(C'\fR or \f(CW\*(C`substr\*(C'\fR with an array or hash for its first
+argument used to result in crashes or "Can't coerce" error messages at run
+time, unlike scalar assignment, which would give an error at compile time.
+List assignment now gives a compile-time error, too.
+[GH #15370] <https://github.com/Perl/perl5/issues/15370>
+.IP \(bu 4
+Expressions containing an \f(CW\*(C`&&\*(C'\fR or \f(CW\*(C`||\*(C'\fR operator (or their synonyms \f(CW\*(C`and\*(C'\fR
+and \f(CW\*(C`or\*(C'\fR) were being compiled incorrectly in some cases.  If the left-hand
+side consisted of either a negated bareword constant or a negated \f(CW\*(C`do {}\*(C'\fR
+block containing a constant expression, and the right-hand side consisted of
+a negated non-foldable expression, one of the negations was effectively
+ignored.  The same was true of \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR statement modifiers,
+though with the left-hand and right-hand sides swapped.  This long-standing
+bug has now been fixed.
+[GH #15285] <https://github.com/Perl/perl5/issues/15285>
+.IP \(bu 4
+\&\f(CW\*(C`reset\*(C'\fR with an argument no longer crashes when encountering stash entries
+other than globs.
+[GH #15314] <https://github.com/Perl/perl5/issues/15314>
+.IP \(bu 4
+Assignment of hashes to, and deletion of, typeglobs named \f(CW*::::::\fR no
+longer causes crashes.
+[GH #15307] <https://github.com/Perl/perl5/issues/15307>
+.IP \(bu 4
+Perl wasn't correctly handling true/false values in the LHS of a list
+assign; specifically the truth values returned by boolean operators.
+This could trigger an assertion failure in something like the following:
+.Sp
+.Vb 3
+\&    for ($x > $y) {
+\&        ($_, ...) = (...); # here $_ is aliased to a truth value
+\&    }
+.Ve
+.Sp
+This was a regression from v5.24.
+[GH #15690] <https://github.com/Perl/perl5/issues/15690>
+.IP \(bu 4
+Assertion failure with user-defined Unicode-like properties.
+[GH #15696] <https://github.com/Perl/perl5/issues/15696>
+.IP \(bu 4
+Fix error message for unclosed \f(CW\*(C`\eN{\*(C'\fR in a regex.  An unclosed \f(CW\*(C`\eN{\*(C'\fR
+could give the wrong error message:
+\&\f(CW"\eN{NAME} must be resolved by the lexer"\fR.
+.IP \(bu 4
+List assignment in list context where the LHS contained aggregates and
+where there were not enough RHS elements, used to skip scalar lvalues.
+Previously, \f(CW\*(C`(($a,$b,@c,$d) = (1))\*(C'\fR in list context returned \f(CW\*(C`($a)\*(C'\fR; now
+it returns \f(CW\*(C`($a,$b,$d)\*(C'\fR.  \f(CW\*(C`(($a,$b,$c) = (1))\*(C'\fR is unchanged: it still
+returns \f(CW\*(C`($a,$b,$c)\*(C'\fR.  This can be seen in the following:
+.Sp
+.Vb 2
+\&    sub inc { $_++ for @_ }
+\&    inc(($a,$b,@c,$d) = (10))
+.Ve
+.Sp
+Formerly, the values of \f(CW\*(C`($a,$b,$d)\*(C'\fR would be left as \f(CW\*(C`(11,undef,undef)\*(C'\fR;
+now they are \f(CW\*(C`(11,1,1)\*(C'\fR.
+.IP \(bu 4
+Code like this: \f(CW\*(C`/(?{ s!!! })/\*(C'\fR could trigger infinite recursion on the C
+stack (not the normal perl stack) when the last successful pattern in
+scope is itself.  We avoid the segfault by simply forbidding the use of
+the empty pattern when it would resolve to the currently executing
+pattern.
+[GH #15669] <https://github.com/Perl/perl5/issues/15669>
+.IP \(bu 4
+Avoid reading beyond the end of the line buffer in perl's lexer when
+there's a short UTF\-8 character at the end.
+[GH #15531] <https://github.com/Perl/perl5/issues/15531>
+.IP \(bu 4
+Alternations in regular expressions were sometimes failing to match
+a utf8 string against a utf8 alternate.
+[GH #15680] <https://github.com/Perl/perl5/issues/15680>
+.IP \(bu 4
+Make \f(CW\*(C`do "a\e0b"\*(C'\fR fail silently (and return \f(CW\*(C`undef\*(C'\fR and set \f(CW$!\fR)
+instead of throwing an error.
+[GH #15676] <https://github.com/Perl/perl5/issues/15676>
+.IP \(bu 4
+\&\f(CW\*(C`chdir\*(C'\fR with no argument didn't ensure that there was stack space
+available for returning its result.
+[GH #15569] <https://github.com/Perl/perl5/issues/15569>
+.IP \(bu 4
+All error messages related to \f(CW\*(C`do\*(C'\fR now refer to \f(CW\*(C`do\*(C'\fR; some formerly
+claimed to be from \f(CW\*(C`require\*(C'\fR instead.
+.IP \(bu 4
+Executing \f(CW\*(C`undef $x\*(C'\fR where \f(CW$x\fR is tied or magical no longer incorrectly
+blames the variable for an uninitialized-value warning encountered by the
+tied/magical code.
+.IP \(bu 4
+Code like \f(CW\*(C`$x = $x . "a"\*(C'\fR was incorrectly failing to yield a
+use of uninitialized value
+warning when \f(CW$x\fR was a lexical variable with an undefined value. That has
+now been fixed.
+[GH #15269] <https://github.com/Perl/perl5/issues/15269>
+.IP \(bu 4
+\&\f(CW\*(C`undef *_; shift\*(C'\fR or \f(CW\*(C`undef *_; pop\*(C'\fR inside a subroutine, with no
+argument to \f(CW\*(C`shift\*(C'\fR or \f(CW\*(C`pop\*(C'\fR, began crashing in Perl 5.14, but has now
+been fixed.
+.IP \(bu 4
+\&\f(CW"string$scalar\->$*"\fR now correctly prefers concatenation
+overloading to string overloading if \f(CW\*(C`$scalar\->$*\*(C'\fR returns an
+overloaded object, bringing it into consistency with \f(CW$$scalar\fR.
+.IP \(bu 4
+\&\f(CW\*(C`/@0{0*\->@*/*0\*(C'\fR and similar contortions used to crash, but no longer
+do, but merely produce a syntax error.
+[GH #15333] <https://github.com/Perl/perl5/issues/15333>
+.IP \(bu 4
+\&\f(CW\*(C`do\*(C'\fR or \f(CW\*(C`require\*(C'\fR with an argument which is a reference or typeglob
+which, when stringified,
+contains a null character, started crashing in Perl 5.20, but has now been
+fixed.
+[GH #15337] <https://github.com/Perl/perl5/issues/15337>
+.IP \(bu 4
+Improve the error message for a missing \f(CWtie()\fR package/method. This
+brings the error messages in line with the ones used for normal method
+calls.
+.IP \(bu 4
+Parsing bad POSIX charclasses no longer leaks memory.
+[GH #15382] <https://github.com/Perl/perl5/issues/15382>
+.SH "Known Problems"
+.IX Header "Known Problems"
+.IP \(bu 4
+G++ 6 handles subnormal (denormal) floating point values differently
+than gcc 6 or g++ 5 resulting in "flush-to-zero". The end result is
+that if you specify very small values using the hexadecimal floating
+point format, like \f(CW\*(C`0x1.fffffffffffffp\-1022\*(C'\fR, they become zeros.
+[GH #15990] <https://github.com/Perl/perl5/issues/15990>
+.SH "Errata From Previous Releases"
+.IX Header "Errata From Previous Releases"
+.IP \(bu 4
+Fixed issues with recursive regexes.  The behavior was fixed in Perl 5.24.
+[GH #14935] <https://github.com/Perl/perl5/issues/14935>
+.SH Obituary
+.IX Header "Obituary"
+Jon Portnoy (AVENJ), a prolific Perl author and admired Gentoo community
+member, has passed away on August 10, 2016.  He will be remembered and
+missed by all those who he came in contact with, and enriched with his
+intellect, wit, and spirit.
+.PP
+It is with great sadness that we also note Kip Hampton's passing.  Probably
+best known as the author of the Perl & XML column on XML.com, he was a
+core contributor to AxKit, an XML server platform that became an Apache
+Foundation project.  He was a frequent speaker in the early days at
+OSCON, and most recently at YAPC::NA in Madison.  He was frequently on
+irc.perl.org as ubu, generally in the #axkit\-dahut community, the
+group responsible for YAPC::NA Asheville in 2011.
+.PP
+Kip and his constant contributions to the community will be greatly
+missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.26.0 represents approximately 13 months of development since Perl 5.24.0
+and contains approximately 360,000 lines of changes across 2,600 files from 86
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 230,000 lines of changes to 1,800 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed the
+improvements that became Perl 5.26.0:
+.PP
+Aaron Crane, Abigail, Ævar Arnfjörð Bjarmason, Alex Vandiver, Andreas
+König, Andreas Voegele, Andrew Fresh, Andy Lester, Aristotle Pagaltzis, Chad
+Granum, Chase Whitener, Chris 'BinGOs' Williams, Chris Lamb, Christian Hansen,
+Christian Millour, Colin Newell, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan
+Collins, Daniel Dragan, Dave Cross, Dave Rolsky, David Golden, David H.
+Gutteridge, David Mitchell, Dominic Hargreaves, Doug Bell, E. Choroba, Ed Avis,
+Father Chrysostomos, François Perrad, Hauke D, H.Merijn Brand, Hugo van der
+Sanden, Ivan Pozdeev, James E Keenan, James Raspass, Jarkko Hietaniemi, Jerry
+D. Hedden, Jim Cromie, J. Nick Koston, John Lightsey, Karen Etheridge, Karl
+Williamson, Leon Timmermans, Lukas Mai, Matthew Horsfall, Maxwell Carey, Misty
+De Meo, Neil Bowers, Nicholas Clark, Nicolas R., Niko Tyni, Pali, Paul
+Marquess, Peter Avalos, Petr Písař, Pino Toscano, Rafael Garcia-Suarez, Reini
+Urban, Renee Baecker, Ricardo Signes, Richard Levitte, Rick Delaney, Salvador
+Fandiño, Samuel Thibault, Sawyer X, Sébastien Aperghis-Tramoni, Sergey
+Aleynikov, Shlomi Fish, Smylers, Stefan Seifert, Steffen Müller, Stevan
+Little, Steve Hay, Steven Humphrey, Sullivan Beck, Theo Buehler, Thomas Sibley,
+Todd Rinaldo, Tomasz Konojacki, Tony Cook, Unicode Consortium, Yaroslav Kuzmin,
+Yves Orton, Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://rt.perl.org/>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to \f(CW\*(C`perlbug@perl.org\*(C'\fR to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5261delta.1 b/upstream/mageia-cauldron/man1/perl5261delta.1
new file mode 100644
index 00000000..0e73604a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5261delta.1
@@ -0,0 +1,256 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5261DELTA 1"
+.TH PERL5261DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5261delta \- what is new for perl v5.26.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.26.0 release and the 5.26.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.24.0, first read
+perl5260delta, which describes differences between 5.24.0 and 5.26.0.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler"
+.IX Subsection "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+Compiling certain regular expression patterns with the case-insensitive
+modifier could cause a heap buffer overflow and crash perl.  This has now been
+fixed.
+[GH #16021] <https://github.com/Perl/perl5/issues/16021>
+.SS "[CVE\-2017\-12883] Buffer over-read in regular expression parser"
+.IX Subsection "[CVE-2017-12883] Buffer over-read in regular expression parser"
+For certain types of syntax error in a regular expression pattern, the error
+message could either contain the contents of a random, possibly large, chunk of
+memory, or could crash perl.  This has now been fixed.
+[GH #16025] <https://github.com/Perl/perl5/issues/16025>
+.ie n .SS "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows"
+.el .SS "[CVE\-2017\-12814] \f(CW$ENV{$key}\fP stack buffer overflow on Windows"
+.IX Subsection "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+A possible stack buffer overflow in the \f(CW%ENV\fR code on Windows has been fixed
+by removing the buffer completely since it was superfluous anyway.
+[GH #16051] <https://github.com/Perl/perl5/issues/16051>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.26.0.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting
+Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+base has been upgraded from version 2.25 to 2.26.
+.Sp
+The effects of dotless \f(CW@INC\fR on this module have been limited by the
+introduction of a more refined and accurate solution for removing \f(CW\*(Aq.\*(Aq\fR from
+\&\f(CW@INC\fR while reducing the false positives.
+.IP \(bu 4
+charnames has been upgraded from version 1.44 to 1.45.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170530 to 5.20170922_26.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Building with \fBg++\fR on FreeBSD\-11.0 has been fixed.
+[GH #15984] <https://github.com/Perl/perl5/issues/15984>
+.RE
+.RS 4
+.RE
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Support for compiling perl on Windows using Microsoft Visual Studio 2017
+(containing Visual C++ 14.1) has been added.
+.IP \(bu 4
+Building XS modules with GCC 6 in a 64\-bit build of Perl failed due to
+incorrect mapping of \f(CW\*(C`strtoll\*(C'\fR and \f(CW\*(C`strtoull\*(C'\fR.  This has now been fixed.
+[GH #16074] <https://github.com/Perl/perl5/issues/16074>
+[cpan #121683] <https://rt.cpan.org/Public/Bug/Display.html?id=121683>
+[cpan #122353] <https://rt.cpan.org/Public/Bug/Display.html?id=122353>
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Several built-in functions previously had bugs that could cause them to write
+to the internal stack without allocating room for the item being written.  In
+rare situations, this could have led to a crash.  These bugs have now been
+fixed, and if any similar bugs are introduced in future, they will be detected
+automatically in debugging builds.
+[GH #16076] <https://github.com/Perl/perl5/issues/16076>
+.IP \(bu 4
+Using a symbolic ref with postderef syntax as the key in a hash lookup was
+yielding an assertion failure on debugging builds.
+[GH #16029] <https://github.com/Perl/perl5/issues/16029>
+.IP \(bu 4
+List assignment (\f(CW\*(C`aassign\*(C'\fR) could in some rare cases allocate an entry on the
+mortal stack and leave the entry uninitialized.
+[GH #16017] <https://github.com/Perl/perl5/issues/16017>
+.IP \(bu 4
+Attempting to apply an attribute to an \f(CW\*(C`our\*(C'\fR variable where a function of that
+name already exists could result in a NULL pointer being supplied where an SV
+was expected, crashing perl.
+[perl #131597] <https://rt.perl.org/Public/Bug/Display.html?id=131597>
+.IP \(bu 4
+The code that vivifies a typeglob out of a code ref made some false assumptions
+that could lead to a crash in cases such as \f(CW\*(C`$::{"A"} = sub {}; \e&{"A"}\*(C'\fR.
+This has now been fixed.
+[GH #15937] <https://github.com/Perl/perl5/issues/15937>
+.IP \(bu 4
+\&\f(CW\*(C`my_atof2\*(C'\fR no longer reads beyond the terminating NUL, which previously
+occurred if the decimal point is immediately before the NUL.
+[GH #16002] <https://github.com/Perl/perl5/issues/16002>
+.IP \(bu 4
+Occasional "Malformed UTF\-8 character" crashes in \f(CW\*(C`s//\*(C'\fR on utf8 strings have
+been fixed.
+[GH #16019] <https://github.com/Perl/perl5/issues/16019>
+.IP \(bu 4
+\&\f(CW\*(C`perldoc \-f s\*(C'\fR now finds \f(CW\*(C`s///\*(C'\fR.
+[GH #15989] <https://github.com/Perl/perl5/issues/15989>
+.IP \(bu 4
+Some erroneous warnings after utf8 conversion have been fixed.
+[GH #15958] <https://github.com/Perl/perl5/issues/15958>
+.IP \(bu 4
+The \f(CW\*(C`jmpenv\*(C'\fR frame to catch Perl exceptions is set up lazily, and this used to
+be a bit too lazy.  The catcher is now set up earlier, preventing some possible
+crashes.
+[GH #11804] <https://github.com/Perl/perl5/issues/11804>
+.IP \(bu 4
+Spurious "Assuming NOT a POSIX class" warnings have been removed.
+[GH #16001] <https://github.com/Perl/perl5/issues/16001>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.26.1 represents approximately 4 months of development since Perl 5.26.0
+and contains approximately 8,900 lines of changes across 85 files from 23
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 990 lines of changes to 38 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.26.1:
+.PP
+Aaron Crane, Andy Dougherty, Aristotle Pagaltzis, Chris 'BinGOs' Williams,
+Craig A. Berry, Dagfinn Ilmari Mannsåker, David Mitchell, E. Choroba, Eric
+Herman, Father Chrysostomos, Jacques Germishuys, James E Keenan, John SJ
+Anderson, Karl Williamson, Ken Brown, Lukas Mai, Matthew Horsfall, Ricardo
+Signes, Sawyer X, Steve Hay, Tony Cook, Yves Orton, Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5262delta.1 b/upstream/mageia-cauldron/man1/perl5262delta.1
new file mode 100644
index 00000000..05d4d973
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5262delta.1
@@ -0,0 +1,247 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5262DELTA 1"
+.TH PERL5262DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5262delta \- what is new for perl v5.26.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.26.1 release and the 5.26.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.26.0, first read
+perl5261delta, which describes differences between 5.26.0 and 5.26.1.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2018\-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+.IX Subsection "[CVE-2018-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+A crafted regular expression could cause a heap buffer write overflow, with
+control over the bytes written.
+[GH #16185] <https://github.com/Perl/perl5/issues/16185>
+.SS "[CVE\-2018\-6798] Heap-buffer-overflow in Perl_\|_byte_dump_string (utf8.c)"
+.IX Subsection "[CVE-2018-6798] Heap-buffer-overflow in Perl__byte_dump_string (utf8.c)"
+Matching a crafted locale dependent regular expression could cause a heap
+buffer read overflow and potentially information disclosure.
+[GH #16143] <https://github.com/Perl/perl5/issues/16143>
+.SS "[CVE\-2018\-6913] heap-buffer-overflow in S_pack_rec"
+.IX Subsection "[CVE-2018-6913] heap-buffer-overflow in S_pack_rec"
+\&\f(CWpack()\fR could cause a heap buffer write overflow with a large item count.
+[GH #16098] <https://github.com/Perl/perl5/issues/16098>
+.SS "Assertion failure in Perl_\|_core_swash_init (utf8.c)"
+.IX Subsection "Assertion failure in Perl__core_swash_init (utf8.c)"
+Control characters in a supposed Unicode property name could cause perl to
+crash.  This has been fixed.
+[perl #132055] <https://rt.perl.org/Public/Bug/Display.html?id=132055>
+[perl #132553] <https://rt.perl.org/Public/Bug/Display.html?id=132553>
+[perl #132658] <https://rt.perl.org/Public/Bug/Display.html?id=132658>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.26.1.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting
+Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170922_26 to 5.20180414_26.
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.16 to 0.17.
+.IP \(bu 4
+Term::ReadLine has been upgraded from version 1.16 to 1.17.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.68 to 0.69.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+\fIperluniprops\fR
+.IX Subsection "perluniprops"
+.IP \(bu 4
+This has been updated to note that \f(CW\*(C`\ep{Word}\*(C'\fR now includes code points
+matching the \f(CW\*(C`\ep{Join_Control}\*(C'\fR property.  The change to the property was made
+in Perl 5.18, but not documented until now.  There are currently only two code
+points that match this property: U+200C (ZERO WIDTH NON-JOINER) and U+200D
+(ZERO WIDTH JOINER).
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Windows 4
+.IX Item "Windows"
+Visual C++ compiler version detection has been improved to work on non-English
+language systems.
+[GH #16235] <https://github.com/Perl/perl5/issues/16235>
+.Sp
+We now set \f(CW$Config{libpth}\fR correctly for 64\-bit builds using Visual C++
+versions earlier than 14.1.
+[GH #16269] <https://github.com/Perl/perl5/issues/16269>
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The \f(CWreadpipe()\fR built-in function now checks at compile time that it has only
+one parameter expression, and puts it in scalar context, thus ensuring that it
+doesn't corrupt the stack at runtime.
+[GH #2793] <https://github.com/Perl/perl5/issues/2793>
+.IP \(bu 4
+Fixed a use after free bug in \f(CW\*(C`pp_list\*(C'\fR introduced in Perl 5.27.1.
+[GH #16124] <https://github.com/Perl/perl5/issues/16124>
+.IP \(bu 4
+Parsing a \f(CW\*(C`sub\*(C'\fR definition could cause a use after free if the \f(CW\*(C`sub\*(C'\fR keyword
+was followed by whitespace including newlines (and comments).
+[GH #16097] <https://github.com/Perl/perl5/issues/16097>
+.IP \(bu 4
+The tokenizer now correctly adjusts a parse pointer when skipping whitespace in
+an \f(CW\*(C` ${identifier} \*(C'\fR construct.
+[perl #131949] <https://rt.perl.org/Public/Bug/Display.html?id=131949>
+.IP \(bu 4
+Accesses to \f(CW\*(C`${^LAST_FH}\*(C'\fR no longer assert after using any of a variety of I/O
+operations on a non-glob.
+[GH #15372] <https://github.com/Perl/perl5/issues/15372>
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR now performs correct reference counting when aliasing \f(CW$a\fR and \f(CW$b\fR,
+thus avoiding premature destruction and leakage of scalars if they are
+re-aliased during execution of the sort comparator.
+[GH #11422] <https://github.com/Perl/perl5/issues/11422>
+.IP \(bu 4
+Some convoluted kinds of regexp no longer cause an arithmetic overflow when
+compiled.
+[GH #16113] <https://github.com/Perl/perl5/issues/16113>
+.IP \(bu 4
+Fixed a duplicate symbol failure with \fB\-flto \-mieee\-fp\fR builds.  \fIpp.c\fR
+defined \f(CW\*(C`_LIB_VERSION\*(C'\fR which \fB\-lieee\fR already defines.
+[GH #16086] <https://github.com/Perl/perl5/issues/16086>
+.IP \(bu 4
+A NULL pointer dereference in the \f(CWS_regmatch()\fR function has been fixed.
+[perl #132017] <https://rt.perl.org/Public/Bug/Display.html?id=132017>
+.IP \(bu 4
+Failures while compiling code within other constructs, such as with string
+interpolation and the right part of \f(CW\*(C`s///e\*(C'\fR now cause compilation to abort
+earlier.
+.Sp
+Previously compilation could continue in order to report other errors, but the
+failed sub-parse could leave partly parsed constructs on the parser
+shift-reduce stack, confusing the parser, leading to perl crashes.
+[GH #14739] <https://github.com/Perl/perl5/issues/14739>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.26.2 represents approximately 7 months of development since Perl 5.26.1
+and contains approximately 3,300 lines of changes across 82 files from 17
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,800 lines of changes to 36 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.26.2:
+.PP
+Aaron Crane, Abigail, Chris 'BinGOs' Williams, H.Merijn Brand, James E Keenan,
+Jarkko Hietaniemi, John SJ Anderson, Karen Etheridge, Karl Williamson, Lukas
+Mai, Renee Baecker, Sawyer X, Steve Hay, Todd Rinaldo, Tony Cook, Yves Orton,
+Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5263delta.1 b/upstream/mageia-cauldron/man1/perl5263delta.1
new file mode 100644
index 00000000..d624a9f2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5263delta.1
@@ -0,0 +1,228 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5263DELTA 1"
+.TH PERL5263DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5263delta \- what is new for perl v5.26.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.26.2 release and the 5.26.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.26.1, first read
+perl5262delta, which describes differences between 5.26.1 and 5.26.2.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2018\-12015] Directory traversal in module Archive::Tar"
+.IX Subsection "[CVE-2018-12015] Directory traversal in module Archive::Tar"
+By default, Archive::Tar doesn't allow extracting files outside the current
+working directory.  However, this secure extraction mode could be bypassed by
+putting a symlink and a regular file with the same name into the tar file.
+.PP
+[GH #16580] <https://github.com/Perl/perl5/issues/16580>
+[cpan #125523] <https://rt.cpan.org/Ticket/Display.html?id=125523>
+.SS "[CVE\-2018\-18311] Integer overflow leading to buffer overflow and segmentation fault"
+.IX Subsection "[CVE-2018-18311] Integer overflow leading to buffer overflow and segmentation fault"
+Integer arithmetic in \f(CWPerl_my_setenv()\fR could wrap when the combined length
+of the environment variable name and value exceeded around 0x7fffffff.  This
+could lead to writing beyond the end of an allocated buffer with attacker
+supplied data.
+.PP
+[GH #16560] <https://github.com/Perl/perl5/issues/16560>
+.SS "[CVE\-2018\-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.IX Subsection "[CVE-2018-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+A crafted regular expression could cause heap-buffer-overflow write during
+compilation, potentially allowing arbitrary code execution.
+.PP
+[GH #16649] <https://github.com/Perl/perl5/issues/16649>
+.SS "[CVE\-2018\-18313] Heap-buffer-overflow read in S_grok_bslash_N (regcomp.c)"
+.IX Subsection "[CVE-2018-18313] Heap-buffer-overflow read in S_grok_bslash_N (regcomp.c)"
+A crafted regular expression could cause heap-buffer-overflow read during
+compilation, potentially leading to sensitive information being leaked.
+.PP
+[GH #16554] <https://github.com/Perl/perl5/issues/16554>
+.SS "[CVE\-2018\-18314] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.IX Subsection "[CVE-2018-18314] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+A crafted regular expression could cause heap-buffer-overflow write during
+compilation, potentially allowing arbitrary code execution.
+.PP
+[GH #16041] <https://github.com/Perl/perl5/issues/16041>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.26.2.  If any exist,
+they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.24 to 2.24_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20180414_26 to 5.20181129_26.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Unexpected ']' with no following ')' in (?[... in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(F) While parsing an extended character class a ']' character was encountered
+at a point in the definition where the only legal use of ']' is to close the
+character class definition as part of a '])', you may have forgotten the close
+paren, or otherwise confused the parser.
+.IP \(bu 4
+Expecting close paren for nested extended charclass in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(F) While parsing a nested extended character class like:
+.Sp
+.Vb 2
+\&    (?[ ... (?flags:(?[ ... ])) ... ])
+\&                             ^
+.Ve
+.Sp
+we expected to see a close paren ')' (marked by ^) but did not.
+.IP \(bu 4
+Expecting close paren for wrapper for nested extended charclass in regex; marked by <\-\- HERE in m/%s/
+.Sp
+(F) While parsing a nested extended character class like:
+.Sp
+.Vb 2
+\&    (?[ ... (?flags:(?[ ... ])) ... ])
+\&                              ^
+.Ve
+.Sp
+we expected to see a close paren ')' (marked by ^) but did not.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Syntax error in (?[...]) in regex; marked by <\-\- HERE in m/%s/
+.Sp
+This fatal error message has been slightly expanded (from "Syntax error in
+(?[...]) in regex m/%s/") for greater clarity.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.26.3 represents approximately 8 months of development since Perl 5.26.2
+and contains approximately 4,500 lines of changes across 51 files from 15
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 770 lines of changes to 10 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.26.3:
+.PP
+Aaron Crane, Abigail, Chris 'BinGOs' Williams, Dagfinn Ilmari Mannsåker, David
+Mitchell, H.Merijn Brand, James E Keenan, John SJ Anderson, Karen Etheridge,
+Karl Williamson, Sawyer X, Steve Hay, Todd Rinaldo, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5280delta.1 b/upstream/mageia-cauldron/man1/perl5280delta.1
new file mode 100644
index 00000000..b01ddcfa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5280delta.1
@@ -0,0 +1,1863 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5280DELTA 1"
+.TH PERL5280DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5280delta \- what is new for perl v5.28.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.26.0 release and the 5.28.0
+release.
+.PP
+If you are upgrading from an earlier release such as 5.24.0, first read
+perl5260delta, which describes differences between 5.24.0 and 5.26.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Unicode 10.0 is supported"
+.IX Subsection "Unicode 10.0 is supported"
+A list of changes is at
+<http://www.unicode.org/versions/Unicode10.0.0>.
+.ie n .SS """delete"" on key/value hash slices"
+.el .SS "\f(CWdelete\fP on key/value hash slices"
+.IX Subsection "delete on key/value hash slices"
+\&\f(CW\*(C`delete\*(C'\fR can now be used on
+key/value hash slices,
+returning the keys along with the deleted values.
+[GH #15982] <https://github.com/Perl/perl5/issues/15982>
+.SS "Experimentally, there are now alphabetic synonyms for some regular expression assertions"
+.IX Subsection "Experimentally, there are now alphabetic synonyms for some regular expression assertions"
+If you find it difficult to remember how to write certain of the pattern
+assertions, there are now alphabetic synonyms.
+.PP
+.Vb 7
+\& CURRENT                NEW SYNONYMS
+\& \-\-\-\-\-\-                 \-\-\-\-\-\-\-\-\-\-\-\-
+\& (?=...)        (*pla:...) or (*positive_lookahead:...)
+\& (?!...)        (*nla:...) or (*negative_lookahead:...)
+\& (?<=...)       (*plb:...) or (*positive_lookbehind:...)
+\& (?<!...)       (*nlb:...) or (*negative_lookbehind:...)
+\& (?>...)        (*atomic:...)
+.Ve
+.PP
+These are considered experimental, so using any of these will raise
+(unless turned off) a warning in the \f(CW\*(C`experimental::alpha_assertions\*(C'\fR
+category.
+.SS "Mixed Unicode scripts are now detectable"
+.IX Subsection "Mixed Unicode scripts are now detectable"
+A mixture of scripts, such as Cyrillic and Latin, in a string is often
+the sign of a spoofing attack.  A new regular expression construct
+now allows for easy detection of these.  For example, you can say
+.PP
+.Vb 1
+\& qr/(*script_run: \ed+ \eb )/x
+.Ve
+.PP
+And the digits matched will all be from the same set of 10.  You won't
+get a look-alike digit from a different script that has a different
+value than what it appears to be.
+.PP
+Or:
+.PP
+.Vb 1
+\& qr/(*sr: \eb \ew+ \eb )/x
+.Ve
+.PP
+makes sure that all the characters come from the same script.
+.PP
+You can also combine script runs with \f(CW\*(C`(?>...)\*(C'\fR (or
+\&\f(CW\*(C`*atomic:...)\*(C'\fR).
+.PP
+Instead of writing:
+.PP
+.Vb 1
+\&    (*sr:(?<...))
+.Ve
+.PP
+you can now run:
+.PP
+.Vb 3
+\&    (*asr:...)
+\&    # or
+\&    (*atomic_script_run:...)
+.Ve
+.PP
+This is considered experimental, so using it will raise (unless turned
+off) a warning in the \f(CW\*(C`experimental::script_run\*(C'\fR category.
+.PP
+See "Script Runs" in perlre.
+.ie n .SS "In-place editing with ""perl \-i"" is now safer"
+.el .SS "In-place editing with \f(CWperl \-i\fP is now safer"
+.IX Subsection "In-place editing with perl -i is now safer"
+Previously in-place editing (\f(CW\*(C`perl \-i\*(C'\fR) would delete or rename the
+input file as soon as you started working on a new file.
+.PP
+Without backups this would result in loss of data if there was an
+error, such as a full disk, when writing to the output file.
+.PP
+This has changed so that the input file isn't replaced until the
+output file has been completely written and successfully closed.
+.PP
+This works by creating a work file in the same directory, which is
+renamed over the input file once the output file is complete.
+.PP
+Incompatibilities:
+.IP \(bu 4
+Since this renaming needs to only happen once, if you create a thread
+or child process, that renaming will only happen in the original
+thread or process.
+.IP \(bu 4
+If you change directories while processing a file, and your operating
+system doesn't provide the \f(CWunlinkat()\fR, \f(CWrenameat()\fR and \f(CWfchmodat()\fR
+functions, the final rename step may fail.
+.PP
+[GH #15216] <https://github.com/Perl/perl5/issues/15216>
+.SS "Initialisation of aggregate state variables"
+.IX Subsection "Initialisation of aggregate state variables"
+A persistent lexical array or hash variable can now be initialized,
+by an expression such as \f(CW\*(C`state @a = qw(x y z)\*(C'\fR.  Initialization of a
+list of persistent lexical variables is still not possible.
+.SS "Full-size inode numbers"
+.IX Subsection "Full-size inode numbers"
+On platforms where inode numbers are of a type larger than perl's native
+integer numerical types, stat will preserve the full
+content of large inode numbers by returning them in the form of strings of
+decimal digits.  Exact comparison of inode numbers can thus be achieved by
+comparing with \f(CW\*(C`eq\*(C'\fR rather than \f(CW\*(C`==\*(C'\fR.  Comparison with \f(CW\*(C`==\*(C'\fR, and other
+numerical operations (which are usually meaningless on inode numbers),
+work as well as they did before, which is to say they fall back to
+floating point, and ultimately operate on a fairly useless rounded inode
+number if the real inode number is too big for the floating point format.
+.ie n .SS "The ""sprintf"" %j format size modifier is now available with pre\-C99 compilers"
+.el .SS "The \f(CWsprintf\fP \f(CW%j\fP format size modifier is now available with pre\-C99 compilers"
+.IX Subsection "The sprintf %j format size modifier is now available with pre-C99 compilers"
+The actual size used depends on the platform, so remains unportable.
+.SS "Close-on-exec flag set atomically"
+.IX Subsection "Close-on-exec flag set atomically"
+When opening a file descriptor, perl now generally opens it with its
+close-on-exec flag already set, on platforms that support doing so.
+This improves thread safety, because it means that an \f(CW\*(C`exec\*(C'\fR initiated
+by one thread can no longer cause a file descriptor in the process
+of being opened by another thread to be accidentally passed to the
+executed program.
+.PP
+Additionally, perl now sets the close-on-exec flag more reliably, whether
+it does so atomically or not.  Most file descriptors were getting the
+flag set, but some were being missed.
+.SS "String\- and number-specific bitwise ops are no longer experimental"
+.IX Subsection "String- and number-specific bitwise ops are no longer experimental"
+The new string-specific (\f(CW\*(C`&. |. ^. ~.\*(C'\fR) and number-specific (\f(CW\*(C`& | ^ ~\*(C'\fR)
+bitwise operators introduced in Perl 5.22 that are available within the
+scope of \f(CW\*(C`use feature \*(Aqbitwise\*(Aq\*(C'\fR are no longer experimental.
+Because the number-specific ops are spelled the same way as the existing
+operators that choose their behaviour based on their operands, these
+operators must still be enabled via the "bitwise" feature, in either of
+these two ways:
+.PP
+.Vb 1
+\&    use feature "bitwise";
+\&
+\&    use v5.28; # "bitwise" now included
+.Ve
+.PP
+They are also now enabled by the \fB\-E\fR command-line switch.
+.PP
+The "bitwise" feature no longer emits a warning.  Existing code that
+disables the "experimental::bitwise" warning category that the feature
+previously used will continue to work.
+.PP
+One caveat that module authors ought to be aware of is that the numeric
+operators now pass a fifth TRUE argument to overload methods.  Any methods
+that check the number of operands may croak if they do not expect so many.
+XS authors in particular should be aware that this:
+.PP
+.Vb 2
+\&    SV *
+\&    bitop_handler (lobj, robj, swap)
+.Ve
+.PP
+may need to be changed to this:
+.PP
+.Vb 2
+\&    SV *
+\&    bitop_handler (lobj, robj, swap, ...)
+.Ve
+.SS "Locales are now thread-safe on systems that support them"
+.IX Subsection "Locales are now thread-safe on systems that support them"
+These systems include Windows starting with Visual Studio 2005, and in
+POSIX 2008 systems.
+.PP
+The implication is that you are now free to use locales and change them
+in a threaded environment.  Your changes affect only your thread.
+See "Multi-threaded operation" in perllocale
+.ie n .SS "New read-only predefined variable ""${^SAFE_LOCALES}"""
+.el .SS "New read-only predefined variable \f(CW${^SAFE_LOCALES}\fP"
+.IX Subsection "New read-only predefined variable ${^SAFE_LOCALES}"
+This variable is 1 if the Perl interpreter is operating in an
+environment where it is safe to use and change locales (see
+perllocale.)  This variable is true when the perl is
+unthreaded, or compiled in a platform that supports thread-safe locale
+operation (see previous item).
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler"
+.IX Subsection "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+Compiling certain regular expression patterns with the case-insensitive
+modifier could cause a heap buffer overflow and crash perl.  This has now been
+fixed.
+[GH #16021] <https://github.com/Perl/perl5/issues/16021>
+.SS "[CVE\-2017\-12883] Buffer over-read in regular expression parser"
+.IX Subsection "[CVE-2017-12883] Buffer over-read in regular expression parser"
+For certain types of syntax error in a regular expression pattern, the error
+message could either contain the contents of a random, possibly large, chunk of
+memory, or could crash perl.  This has now been fixed.
+[GH #16025] <https://github.com/Perl/perl5/issues/16025>
+.ie n .SS "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows"
+.el .SS "[CVE\-2017\-12814] \f(CW$ENV{$key}\fP stack buffer overflow on Windows"
+.IX Subsection "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+A possible stack buffer overflow in the \f(CW%ENV\fR code on Windows has been fixed
+by removing the buffer completely since it was superfluous anyway.
+[GH #16051] <https://github.com/Perl/perl5/issues/16051>
+.SS "Default Hash Function Change"
+.IX Subsection "Default Hash Function Change"
+Perl 5.28.0 retires various older hash functions which are not viewed as
+sufficiently secure for use in Perl. We now support four general purpose
+hash functions, Siphash (2\-4 and 1\-3 variants), and  Zaphod32, and StadtX
+hash. In addition we support SBOX32 (a form of tabular hashing) for hashing
+short strings, in conjunction with any of the other hash functions provided.
+.PP
+By default Perl is configured to support SBOX hashing of strings up to 24
+characters, in conjunction with StadtX hashing on 64 bit builds, and
+Zaphod32 hashing for 32 bit builds.
+.PP
+You may control these settings with the following options to Configure:
+.PP
+.Vb 4
+\&    \-DPERL_HASH_FUNC_SIPHASH
+\&    \-DPERL_HASH_FUNC_SIPHASH13
+\&    \-DPERL_HASH_FUNC_STADTX
+\&    \-DPERL_HASH_FUNC_ZAPHOD32
+.Ve
+.PP
+To disable SBOX hashing you can use
+.PP
+.Vb 1
+\&    \-DPERL_HASH_USE_SBOX32_ALSO=0
+.Ve
+.PP
+And to set the maximum length to use SBOX32 hashing on with:
+.PP
+.Vb 1
+\&    \-DSBOX32_MAX_LEN=16
+.Ve
+.PP
+The maximum length allowed is 256. There probably isn't much point
+in setting it higher than the default.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Subroutine attribute and signature order"
+.IX Subsection "Subroutine attribute and signature order"
+The experimental subroutine signatures feature has been changed so that
+subroutine attributes must now come before the signature rather than
+after. This is because attributes like \f(CW\*(C`:lvalue\*(C'\fR can affect the
+compilation of code within the signature, for example:
+.PP
+.Vb 1
+\&    sub f :lvalue ($a = do { $x = "abc"; return substr($x,0,1)}) { ...}
+.Ve
+.PP
+Note that this the second time they have been flipped:
+.PP
+.Vb 2
+\&    sub f :lvalue ($a, $b) { ... }; # 5.20; 5.28 onwards
+\&    sub f ($a, $b) :lvalue { ... }; # 5.22 \- 5.26
+.Ve
+.SS "Comma-less variable lists in formats are no longer allowed"
+.IX Subsection "Comma-less variable lists in formats are no longer allowed"
+Omitting the commas between variables passed to formats is no longer
+allowed.  This has been deprecated since Perl 5.000.
+.ie n .SS "The "":locked"" and "":unique"" attributes have been removed"
+.el .SS "The \f(CW:locked\fP and \f(CW:unique\fP attributes have been removed"
+.IX Subsection "The :locked and :unique attributes have been removed"
+These have been no-ops and deprecated since Perl 5.12 and 5.10,
+respectively.
+.ie n .SS """\eN{}"" with nothing between the braces is now illegal"
+.el .SS "\f(CW\eN{}\fP with nothing between the braces is now illegal"
+.IX Subsection "N{} with nothing between the braces is now illegal"
+This has been deprecated since Perl 5.24.
+.SS "Opening the same symbol as both a file and directory handle is no longer allowed"
+.IX Subsection "Opening the same symbol as both a file and directory handle is no longer allowed"
+Using \f(CWopen()\fR and \f(CWopendir()\fR to associate both a filehandle and a dirhandle
+to the same symbol (glob or scalar) has been deprecated since Perl 5.10.
+.ie n .SS "Use of bare ""<<"" to mean ""<<"""""" is no longer allowed"
+.el .SS "Use of bare \f(CW<<\fP to mean \f(CW<<""""\fP is no longer allowed"
+.IX Subsection "Use of bare << to mean <<"""" is no longer allowed"
+Use of a bare terminator has been deprecated since Perl 5.000.
+.SS "Setting $/ to a reference to a non-positive integer no longer allowed"
+.IX Subsection "Setting $/ to a reference to a non-positive integer no longer allowed"
+This used to work like setting it to \f(CW\*(C`undef\*(C'\fR, but has been deprecated
+since Perl 5.20.
+.ie n .SS "Unicode code points with values exceeding ""IV_MAX"" are now fatal"
+.el .SS "Unicode code points with values exceeding \f(CWIV_MAX\fP are now fatal"
+.IX Subsection "Unicode code points with values exceeding IV_MAX are now fatal"
+This was deprecated since Perl 5.24.
+.ie n .SS "The ""B::OP::terse"" method has been removed"
+.el .SS "The \f(CWB::OP::terse\fP method has been removed"
+.IX Subsection "The B::OP::terse method has been removed"
+Use \f(CW\*(C`B::Concise::b_terse\*(C'\fR instead.
+.SS "Use of inherited AUTOLOAD for non-methods is no longer allowed"
+.IX Subsection "Use of inherited AUTOLOAD for non-methods is no longer allowed"
+This was deprecated in Perl 5.004.
+.SS "Use of strings with code points over 0xFF is not allowed for bitwise string operators"
+.IX Subsection "Use of strings with code points over 0xFF is not allowed for bitwise string operators"
+Code points over \f(CW0xFF\fR do not make sense for bitwise operators and such
+an operation will now croak, except for a few remaining cases. See
+perldeprecation.
+.PP
+This was deprecated in Perl 5.24.
+.ie n .SS "Setting ""${^ENCODING}"" to a defined value is now illegal"
+.el .SS "Setting \f(CW${^ENCODING}\fP to a defined value is now illegal"
+.IX Subsection "Setting ${^ENCODING} to a defined value is now illegal"
+This has been deprecated since Perl 5.22 and a no-op since Perl 5.26.
+.ie n .SS "Backslash no longer escapes colon in PATH for the ""\-S"" switch"
+.el .SS "Backslash no longer escapes colon in PATH for the \f(CW\-S\fP switch"
+.IX Subsection "Backslash no longer escapes colon in PATH for the -S switch"
+Previously the \f(CW\*(C`\-S\*(C'\fR switch incorrectly treated backslash ("\e") as an
+escape for colon when traversing the \f(CW\*(C`PATH\*(C'\fR environment variable.
+[GH #15584] <https://github.com/Perl/perl5/issues/15584>
+.SS "the \-DH (DEBUG_H) misfeature has been removed"
+.IX Subsection "the -DH (DEBUG_H) misfeature has been removed"
+On a perl built with debugging support, the \f(CW\*(C`H\*(C'\fR flag to the \f(CW\*(C`\-D\*(C'\fR
+debugging option has been removed. This was supposed to dump hash values,
+but has been broken for many years.
+.SS "Yada-yada is now strictly a statement"
+.IX Subsection "Yada-yada is now strictly a statement"
+By the time of its initial stable release in Perl 5.12, the \f(CW\*(C`...\*(C'\fR
+(yada-yada) operator was explicitly intended to serve as a statement,
+not an expression.  However, the original implementation was confused
+on this point, leading to inconsistent parsing.  The operator was
+accidentally accepted in a few situations where it did not serve as a
+complete statement, such as
+.PP
+.Vb 2
+\&    ... . "foo";
+\&    ... if $a < $b;
+.Ve
+.PP
+The parsing has now been made consistent, permitting yada-yada only as
+a statement.  Affected code can use \f(CW\*(C`do{...}\*(C'\fR to put a yada-yada into
+an arbitrary expression context.
+.SS "Sort algorithm can no longer be specified"
+.IX Subsection "Sort algorithm can no longer be specified"
+Since Perl 5.8, the sort pragma has had subpragmata \f(CW\*(C`_mergesort\*(C'\fR,
+\&\f(CW\*(C`_quicksort\*(C'\fR, and \f(CW\*(C`_qsort\*(C'\fR that can be used to specify which algorithm
+perl should use to implement the sort builtin.
+This was always considered a dubious feature that might not last,
+hence the underscore spellings, and they were documented as not being
+portable beyond Perl 5.8.  These subpragmata have now been deleted,
+and any attempt to use them is an error.  The sort pragma otherwise
+remains, and the algorithm-neutral \f(CW\*(C`stable\*(C'\fR subpragma can be used to
+control sorting behaviour.
+[GH #13234] <https://github.com/Perl/perl5/issues/13234>
+.SS "Over-radix digits in floating point literals"
+.IX Subsection "Over-radix digits in floating point literals"
+Octal and binary floating point literals used to permit any hexadecimal
+digit to appear after the radix point.  The digits are now restricted
+to those appropriate for the radix, as digits before the radix point
+always were.
+.ie n .SS "Return type of unpackstring()"
+.el .SS "Return type of \f(CWunpackstring()\fP"
+.IX Subsection "Return type of unpackstring()"
+The return types of the C API functions \f(CWunpackstring()\fR and
+\&\f(CWunpack_str()\fR have changed from \f(CW\*(C`I32\*(C'\fR to \f(CW\*(C`SSize_t\*(C'\fR, in order to
+accommodate datasets of more than two billion items.
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS "Use of ""vec"" on strings with code points above 0xFF is deprecated"
+.el .SS "Use of \f(CWvec\fP on strings with code points above 0xFF is deprecated"
+.IX Subsection "Use of vec on strings with code points above 0xFF is deprecated"
+Such strings are represented internally in UTF\-8, and \f(CW\*(C`vec\*(C'\fR is a
+bit-oriented operation that will likely give unexpected results on those
+strings.
+.ie n .SS "Some uses of unescaped ""{"" in regexes are no longer fatal"
+.el .SS "Some uses of unescaped \f(CW""{""\fP in regexes are no longer fatal"
+.IX Subsection "Some uses of unescaped ""{"" in regexes are no longer fatal"
+Perl 5.26.0 fatalized some uses of an unescaped left brace, but an
+exception was made at the last minute, specifically crafted to be a
+minimal change to allow GNU Autoconf to work.  That tool is heavily
+depended upon, and continues to use the deprecated usage.  Its use of an
+unescaped left brace is one where we have no intention of repurposing
+\&\f(CW"{"\fR to be something other than itself.
+.PP
+That exception is now generalized to include various other such cases
+where the \f(CW"{"\fR will not be repurposed.
+.PP
+Note that these uses continue to raise a deprecation message.
+.ie n .SS "Use of unescaped ""{"" immediately after a ""("" in regular expression patterns is deprecated"
+.el .SS "Use of unescaped \f(CW""{""\fP immediately after a \f(CW""(""\fP in regular expression patterns is deprecated"
+.IX Subsection "Use of unescaped ""{"" immediately after a ""("" in regular expression patterns is deprecated"
+Using unescaped left braces is officially deprecated everywhere, but it
+is not enforced in contexts where their use does not interfere with
+expected extensions to the language.  A deprecation is added in this
+release when the brace appears immediately after an opening parenthesis.
+Before this, even if the brace was part of a legal quantifier, it was
+not interpreted as such, but as the literal characters, unlike other
+quantifiers that follow a \f(CW"("\fR which are considered errors.  Now,
+their use will raise a deprecation message, unless turned off.
+.ie n .SS "Assignment to $[ will be fatal in Perl 5.30"
+.el .SS "Assignment to \f(CW$[\fP will be fatal in Perl 5.30"
+.IX Subsection "Assignment to $[ will be fatal in Perl 5.30"
+Assigning a non-zero value to \f(CW$[\fR has been deprecated
+since Perl 5.12, but was never given a deadline for removal.  This has
+now been scheduled for Perl 5.30.
+.SS "\fBhostname()\fP won't accept arguments in Perl 5.32"
+.IX Subsection "hostname() won't accept arguments in Perl 5.32"
+Passing arguments to \f(CWSys::Hostname::hostname()\fR was already deprecated,
+but didn't have a removal date.  This has now been scheduled for Perl
+5.32.  [GH #14662] <https://github.com/Perl/perl5/issues/14662>
+.SS "Module removals"
+.IX Subsection "Module removals"
+The following modules will be removed from the core distribution in a
+future release, and will at that time need to be installed from CPAN.
+Distributions on CPAN which require these modules will need to list them as
+prerequisites.
+.PP
+The core versions of these modules will now issue \f(CW"deprecated"\fR\-category
+warnings to alert you to this fact.  To silence these deprecation warnings,
+install the modules in question from CPAN.
+.PP
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use.  Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
+.IP B::Debug 4
+.IX Item "B::Debug"
+.PD 0
+.IP "Locale::Codes and its associated Country, Currency and Language modules" 4
+.IX Item "Locale::Codes and its associated Country, Currency and Language modules"
+.PD
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+The start up overhead for creating regular expression patterns with
+Unicode properties (\f(CW\*(C`\ep{...}\*(C'\fR) has been greatly reduced in most cases.
+.IP \(bu 4
+Many string concatenation expressions are now considerably faster, due
+to the introduction internally of a \f(CW\*(C`multiconcat\*(C'\fR opcode which combines
+multiple concatenations, and optionally a \f(CW\*(C`=\*(C'\fR or \f(CW\*(C`.=\*(C'\fR, into a single
+action. For example, apart from retrieving \f(CW$s\fR, \f(CW$a\fR and \f(CW$b\fR, this
+whole expression is now handled as a single op:
+.Sp
+.Vb 1
+\&    $s .= "a=$a b=$b\en"
+.Ve
+.Sp
+As a special case, if the LHS of an assignment is a lexical variable or
+\&\f(CW\*(C`my $s\*(C'\fR, the op itself handles retrieving the lexical variable, which
+is faster.
+.Sp
+In general, the more the expression includes a mix of constant strings and
+variable expressions, the longer the expression, and the more it mixes
+together non\-utf8 and utf8 strings, the more marked the performance
+improvement. For example on a \f(CW\*(C`x86_64\*(C'\fR system, this code has been
+benchmarked running four times faster:
+.Sp
+.Vb 4
+\&    my $s;
+\&    my $a = "ab\ex{100}cde";
+\&    my $b = "fghij";
+\&    my $c = "\ex{101}klmn";
+\&
+\&    for my $i (1..10_000_000) {
+\&        $s = "\ex{100}wxyz";
+\&        $s .= "foo=$a bar=$b baz=$c";
+\&    }
+.Ve
+.Sp
+In addition, \f(CW\*(C`sprintf\*(C'\fR expressions which have a constant format
+containing only \f(CW%s\fR and \f(CW\*(C`%%\*(C'\fR format elements, and which have a fixed
+number of arguments, are now also optimised into a \f(CW\*(C`multiconcat\*(C'\fR op.
+.IP \(bu 4
+The \f(CWref()\fR builtin is now much faster in boolean context, since it no
+longer bothers to construct a temporary string like \f(CW\*(C`Foo=ARRAY(0x134af48)\*(C'\fR.
+.IP \(bu 4
+\&\f(CWkeys()\fR in void and scalar contexts is now more efficient.
+.IP \(bu 4
+The common idiom of comparing the result of \fBindex()\fR with \-1 is now
+specifically optimised,  e.g.
+.Sp
+.Vb 1
+\&    if (index(...) != \-1) { ... }
+.Ve
+.IP \(bu 4
+\&\f(CWfor()\fR loops and similar constructs are now more efficient in most cases.
+.IP \(bu 4
+File::Glob has been modified to remove unnecessary backtracking and
+recursion, thanks to Russ Cox. See <https://research.swtch.com/glob>
+for more details.
+.IP \(bu 4
+The XS-level \f(CWSvTRUE()\fR API function is now more efficient.
+.IP \(bu 4
+Various integer-returning ops are now more efficient in scalar/boolean context.
+.IP \(bu 4
+Slightly improved performance when parsing stash names.
+[GH #15689] <https://github.com/Perl/perl5/issues/15689>
+.IP \(bu 4
+Calls to \f(CW\*(C`require\*(C'\fR for an already loaded module are now slightly faster.
+[GH #16175] <https://github.com/Perl/perl5/issues/16175>
+.IP \(bu 4
+The performance of pattern matching \f(CW\*(C`[[:ascii:]]\*(C'\fR and \f(CW\*(C`[[:^ascii:]]\*(C'\fR
+has been improved significantly except on EBCDIC platforms.
+.IP \(bu 4
+Various optimizations have been applied to matching regular expression
+patterns, so under the right circumstances, significant performance
+gains may be noticed.  But in an application with many varied patterns,
+little overall improvement likely will be seen.
+.IP \(bu 4
+Other optimizations have been applied to UTF\-8 handling, but these are
+not typically a major factor in most applications.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+Key highlights in this release across several modules:
+.SS "Removal of use vars"
+.IX Subsection "Removal of use vars"
+The usage of \f(CW\*(C`use vars\*(C'\fR has been discouraged since the introduction of
+\&\f(CW\*(C`our\*(C'\fR in Perl 5.6.0. Where possible the usage of this pragma has now been
+removed from the Perl source code.
+.PP
+This had a slight effect (for the better) on the output of WARNING_BITS in
+B::Deparse.
+.SS "Use of DynaLoader changed to XSLoader in many modules"
+.IX Subsection "Use of DynaLoader changed to XSLoader in many modules"
+XSLoader is more modern, and most modules already require perl 5.6 or
+greater, so no functionality is lost by switching. In some cases, we have
+also made changes to the local implementation that may not be reflected in
+the version on CPAN due to a desire to maintain more backwards
+compatibility.
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.24 to 2.30.
+.Sp
+This update also handled CVE\-2018\-12015: directory traversal
+vulnerability.
+[cpan #125523] <https://rt.cpan.org/Ticket/Display.html?id=125523>
+.IP \(bu 4
+arybase has been upgraded from version 0.12 to 0.15.
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 0.99 to 1.01.
+.IP \(bu 4
+attributes has been upgraded from version 0.29 to 0.33.
+.IP \(bu 4
+B has been upgraded from version 1.68 to 1.74.
+.IP \(bu 4
+B::Concise has been upgraded from version 0.999 to 1.003.
+.IP \(bu 4
+B::Debug has been upgraded from version 1.24 to 1.26.
+.Sp
+NOTE: B::Debug is deprecated and may be removed from a future version
+of Perl.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.40 to 1.48.
+.Sp
+It includes many bug fixes, and in particular, it now deparses variable
+attributes correctly:
+.Sp
+.Vb 2
+\&    my $x :foo;  # used to deparse as
+\&                 # \*(Aqattributes\*(Aq\->import(\*(Aqmain\*(Aq, \e$x, \*(Aqfoo\*(Aq), my $x;
+.Ve
+.IP \(bu 4
+base has been upgraded from version 2.25 to 2.27.
+.IP \(bu 4
+bignum has been upgraded from version 0.47 to 0.49.
+.IP \(bu 4
+blib has been upgraded from version 1.06 to 1.07.
+.IP \(bu 4
+bytes has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+Carp has been upgraded from version 1.42 to 1.50.
+.Sp
+If a package on the call stack contains a constant named \f(CW\*(C`ISA\*(C'\fR, Carp no
+longer throws a "Not a GLOB reference" error.
+.Sp
+Carp, when generating stack traces, now attempts to work around
+longstanding bugs resulting from Perl's non-reference-counted stack.
+[GH #9282] <https://github.com/Perl/perl5/issues/9282>
+.Sp
+Carp has been modified to avoid assuming that objects cannot be
+overloaded without the overload module loaded (this can happen with
+objects created by XS modules).  Previously, infinite recursion would
+result if an XS-defined overload method itself called Carp.
+[GH #16407] <https://github.com/Perl/perl5/issues/16407>
+.Sp
+Carp now avoids using \f(CW\*(C`overload::StrVal\*(C'\fR, partly because older versions
+of overload (included with perl 5.14 and earlier) load Scalar::Util
+at run time, which will fail if Carp has been invoked after a syntax error.
+.IP \(bu 4
+charnames has been upgraded from version 1.44 to 1.45.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.074 to 2.076.
+.Sp
+This addresses a security vulnerability in older versions of the 'zlib' library
+(which is bundled with Compress-Raw-Zlib).
+.IP \(bu 4
+Config::Extensions has been upgraded from version 0.01 to 0.02.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.28 to 0.29.
+.IP \(bu 4
+CPAN has been upgraded from version 2.18 to 2.20.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.167 to 2.170.
+.Sp
+Quoting of glob names now obeys the Useqq option
+[GH #13274] <https://github.com/Perl/perl5/issues/13274>.
+.Sp
+Attempts to set an option to \f(CW\*(C`undef\*(C'\fR through a combined getter/setter
+method are no longer mistaken for getter calls
+[GH #12135] <https://github.com/Perl/perl5/issues/12135>.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.26 to 1.27.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.35 to 3.40.
+.Sp
+Devel::PPPort has moved from cpan-first to perl-first maintenance
+.Sp
+Primary responsibility for the code in Devel::PPPort has moved into core perl.
+In a practical sense there should be no change except that hopefully it will
+stay more up to date with changes made to symbols in perl, rather than needing
+to be updated after the fact.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 5.96 to 6.01.
+.IP \(bu 4
+DirHandle has been upgraded from version 1.04 to 1.05.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.42 to 1.45.
+.Sp
+Its documentation now shows the use of \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR and direct object
+syntax
+[GH #16190] <https://github.com/Perl/perl5/issues/16190>.
+.IP \(bu 4
+Encode has been upgraded from version 2.88 to 2.97.
+.IP \(bu 4
+encoding has been upgraded from version 2.19 to 2.22.
+.IP \(bu 4
+Errno has been upgraded from version 1.28 to 1.29.
+.IP \(bu 4
+experimental has been upgraded from version 0.016 to 0.019.
+.IP \(bu 4
+Exporter has been upgraded from version 5.72 to 5.73.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280225 to 0.280230.
+.IP \(bu 4
+ExtUtils::Constant has been upgraded from version 0.23 to 0.25.
+.IP \(bu 4
+ExtUtils::Embed has been upgraded from version 1.34 to 1.35.
+.IP \(bu 4
+ExtUtils::Install has been upgraded from version 2.04 to 2.14.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.24 to 7.34.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.06 to 1.08.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.34 to 3.39.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.34 to 3.38.
+.IP \(bu 4
+ExtUtils::XSSymSet has been upgraded from version 1.3 to 1.4.
+.IP \(bu 4
+feature has been upgraded from version 1.47 to 1.52.
+.IP \(bu 4
+fields has been upgraded from version 2.23 to 2.24.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.32 to 2.33.
+.Sp
+It will now use the sub-second precision variant of \fButime()\fR supplied by
+Time::HiRes where available.
+[GH #16225] <https://github.com/Perl/perl5/issues/16225>.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.52 to 0.56.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.28 to 1.31.
+.IP \(bu 4
+File::Path has been upgraded from version 2.12_01 to 2.15.
+.IP \(bu 4
+File::Spec and Cwd have been upgraded from version 3.67 to 3.74.
+.IP \(bu 4
+File::stat has been upgraded from version 1.07 to 1.08.
+.IP \(bu 4
+FileCache has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+Filter::Simple has been upgraded from version 0.93 to 0.95.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.55 to 1.58.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.15 to 1.17.
+.Sp
+Its documentation now explains that \f(CW\*(C`each\*(C'\fR and \f(CW\*(C`delete\*(C'\fR don't mix in
+hashes tied to this module
+[GH #12894] <https://github.com/Perl/perl5/issues/12894>.
+.Sp
+It will now retry opening with an acceptable block size if asking gdbm
+to default the block size failed
+[GH #13232] <https://github.com/Perl/perl5/issues/13232>.
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.49 to 2.5.
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.19 to 1.20.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.13 to 0.17.
+.Sp
+This module is now available on all platforms, emulating the system
+\&\fBnl_langinfo\fR\|(3) on systems that lack it.  Some caveats apply, as
+detailed in its documentation, the most severe being
+that, except for MS Windows, the \f(CW\*(C`CODESET\*(C'\fR item is not implemented on
+those systems, always returning \f(CW""\fR.
+.Sp
+It now sets the UTF\-8 flag in its returned scalar if the string contains
+legal non-ASCII UTF\-8, and the locale is UTF\-8
+[GH #15131] <https://github.com/Perl/perl5/issues/15131>.
+.Sp
+This update also fixes a bug in which the underlying locale was ignored
+for the \f(CW\*(C`RADIXCHAR\*(C'\fR (always was returned as a dot) and the \f(CW\*(C`THOUSEP\*(C'\fR
+(always empty).  Now the locale-appropriate values are returned.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.42 to 0.43.
+.IP \(bu 4
+if has been upgraded from version 0.0606 to 0.0608.
+.IP \(bu 4
+IO has been upgraded from version 1.38 to 1.39.
+.IP \(bu 4
+IO::Socket::IP has been upgraded from version 0.38 to 0.39.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 0.96 to 1.00.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.27400_02 to 2.97001.
+.IP \(bu 4
+The \f(CW\*(C`libnet\*(C'\fR distribution has been upgraded from version 3.10 to 3.11.
+.IP \(bu 4
+List::Util has been upgraded from version 1.46_02 to 1.49.
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.42 to 3.56.
+.Sp
+\&\fBNOTE\fR: Locale::Codes scheduled to be removed from core in Perl 5.30.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.28 to 1.29.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999806 to 1.999811.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.5005 to 0.5006.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2611 to 0.2613.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20170530 to 5.20180622.
+.IP \(bu 4
+mro has been upgraded from version 1.20 to 1.22.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.55 to 2.62.
+.IP \(bu 4
+NEXT has been upgraded from version 0.67 to 0.67_01.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.14 to 1.15.
+.IP \(bu 4
+Opcode has been upgraded from version 1.39 to 1.43.
+.IP \(bu 4
+overload has been upgraded from version 1.28 to 1.30.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.25 to 0.26.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.26 to 0.29.
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.16 to 0.17.
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.11 to 1.13.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.2202 to 1.24.
+.Sp
+A title for the HTML document will now be automatically generated by
+default from a "NAME" section in the POD document, as it used to be
+before the module was rewritten to use Pod::Simple::XHTML to do the
+core of its job
+[GH #11954] <https://github.com/Perl/perl5/issues/11954>.
+.IP \(bu 4
+Pod::Perldoc has been upgraded from version 3.28 to 3.2801.
+.IP \(bu 4
+The \f(CW\*(C`podlators\*(C'\fR distribution has been upgraded from version 4.09 to 4.10.
+.Sp
+Man page references and function names now follow the Linux man page
+formatting standards, instead of the Solaris standard.
+.IP \(bu 4
+POSIX has been upgraded from version 1.76 to 1.84.
+.Sp
+Some more cautions were added about using locale-specific functions in
+threaded applications.
+.IP \(bu 4
+re has been upgraded from version 0.34 to 0.36.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.46_02 to 1.50.
+.IP \(bu 4
+SelfLoader has been upgraded from version 1.23 to 1.25.
+.IP \(bu 4
+Socket has been upgraded from version 2.020_03 to 2.027.
+.IP \(bu 4
+sort has been upgraded from version 2.02 to 2.04.
+.IP \(bu 4
+Storable has been upgraded from version 2.62 to 3.08.
+.IP \(bu 4
+Sub::Util has been upgraded from version 1.48 to 1.49.
+.IP \(bu 4
+subs has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.20 to 1.22.
+.IP \(bu 4
+Term::ReadLine has been upgraded from version 1.16 to 1.17.
+.IP \(bu 4
+Test has been upgraded from version 1.30 to 1.31.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.38 to 3.42.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302073 to 1.302133.
+.IP \(bu 4
+threads has been upgraded from version 2.15 to 2.22.
+.Sp
+The documentation now better describes the problems that arise when
+returning values from threads, and no longer warns about creating threads
+in \f(CW\*(C`BEGIN\*(C'\fR blocks.
+[GH #11563] <https://github.com/Perl/perl5/issues/11563>
+.IP \(bu 4
+threads::shared has been upgraded from version 1.56 to 1.58.
+.IP \(bu 4
+Tie::Array has been upgraded from version 1.06 to 1.07.
+.IP \(bu 4
+Tie::StdHandle has been upgraded from version 4.4 to 4.5.
+.IP \(bu 4
+Time::gmtime has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9741 to 1.9759.
+.IP \(bu 4
+Time::localtime has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.31 to 1.3204.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.19 to 1.25.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.25 to 1.26.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.68 to 0.70.
+.Sp
+The function \f(CW\*(C`num\*(C'\fR now accepts an optional parameter to help in
+diagnosing error returns.
+.IP \(bu 4
+User::grent has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+User::pwent has been upgraded from version 1.00 to 1.01.
+.IP \(bu 4
+utf8 has been upgraded from version 1.19 to 1.21.
+.IP \(bu 4
+vars has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+version has been upgraded from version 0.9917 to 0.9923.
+.IP \(bu 4
+VMS::DCLsym has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+VMS::Stdio has been upgraded from version 2.41 to 2.44.
+.IP \(bu 4
+warnings has been upgraded from version 1.37 to 1.42.
+.Sp
+It now includes new functions with names ending in \f(CW\*(C`_at_level\*(C'\fR, allowing
+callers to specify the exact call frame.
+[GH #16257] <https://github.com/Perl/perl5/issues/16257>
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.15 to 0.16.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.27 to 0.30.
+.Sp
+Its documentation now shows the use of \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR, and direct object
+syntax for example \f(CW\*(C`DynaLoader\*(C'\fR usage
+[GH #16190] <https://github.com/Perl/perl5/issues/16190>.
+.Sp
+Platforms that use \f(CW\*(C`mod2fname\*(C'\fR to edit the names of loadable
+libraries now look for bootstrap (.bs) files under the correct,
+non-edited name.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+.IP \(bu 4
+The \f(CW\*(C`VMS::stdio\*(C'\fR compatibility shim has been removed.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, send email
+to perlbug@perl.org <mailto:perlbug@perl.org>.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+The API functions \f(CWperl_parse()\fR, \f(CWperl_run()\fR, and \f(CWperl_destruct()\fR
+are now documented comprehensively, where previously the only
+documentation was a reference to the perlembed tutorial.
+.IP \(bu 4
+The documentation of \f(CWnewGIVENOP()\fR has been belatedly updated to
+account for the removal of lexical \f(CW$_\fR.
+.IP \(bu 4
+The API functions \f(CWnewCONSTSUB()\fR and \f(CWnewCONSTSUB_flags()\fR are
+documented much more comprehensively than before.
+.PP
+\fIperldata\fR
+.IX Subsection "perldata"
+.IP \(bu 4
+The section "Truth and Falsehood" in perlsyn has been moved into
+perldata.
+.PP
+\fIperldebguts\fR
+.IX Subsection "perldebguts"
+.IP \(bu 4
+The description of the conditions under which \f(CWDB::sub()\fR will be called
+has been clarified.
+[GH #16055] <https://github.com/Perl/perl5/issues/16055>
+.PP
+\fIperldiag\fR
+.IX Subsection "perldiag"
+.IP \(bu 4
+"Variable length lookbehind not implemented in regex m/%s/" in perldiag
+.Sp
+This now gives more ideas as to workarounds to the issue that was
+introduced in Perl 5.18 (but not documented explicitly in its perldelta)
+for the fact that some Unicode \f(CW\*(C`/i\*(C'\fR rules cause a few sequences such as
+.Sp
+.Vb 1
+\& (?<!st)
+.Ve
+.Sp
+to be considered variable length, and hence disallowed.
+.IP \(bu 4
+"Use of state \f(CW$_\fR is experimental" in perldiag
+.Sp
+This entry has been removed, as the experimental support of this construct was
+removed in perl 5.24.0.
+.IP \(bu 4
+The diagnostic \f(CW\*(C`Initialization of state variables in list context
+currently forbidden\*(C'\fR has changed to \f(CW\*(C`Initialization of state variables
+in list currently forbidden\*(C'\fR, because list-context initialization of
+single aggregate state variables is now permitted.
+.PP
+\fIperlembed\fR
+.IX Subsection "perlembed"
+.IP \(bu 4
+The examples in perlembed have been made more portable in the way
+they exit, and the example that gets an exit code from the embedded Perl
+interpreter now gets it from the right place.  The examples that pass
+a constructed argv to Perl now show the mandatory null \f(CW\*(C`argv[argc]\*(C'\fR.
+.IP \(bu 4
+An example in perlembed used the string value of \f(CW\*(C`ERRSV\*(C'\fR as a
+format string when calling \fBcroak()\fR.  If that string contains format
+codes such as \f(CW%s\fR this could crash the program.
+.Sp
+This has been changed to a call to \fBcroak_sv()\fR.
+.Sp
+An alternative could have been to supply a trivial format string:
+.Sp
+.Vb 1
+\&  croak("%s", SvPV_nolen(ERRSV));
+.Ve
+.Sp
+or as a special case for \f(CW\*(C`ERRSV\*(C'\fR simply:
+.Sp
+.Vb 1
+\&  croak(NULL);
+.Ve
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+There is now a note that warnings generated by built-in functions are
+documented in perldiag and warnings.
+[GH #12642] <https://github.com/Perl/perl5/issues/12642>
+.IP \(bu 4
+The documentation for the \f(CW\*(C`exists\*(C'\fR operator no longer says that
+autovivification behaviour "may be fixed in a future release".
+We've determined that we're not going to change the default behaviour.
+[GH #15231] <https://github.com/Perl/perl5/issues/15231>
+.IP \(bu 4
+A couple of small details in the documentation for the \f(CW\*(C`bless\*(C'\fR operator
+have been clarified.
+[GH #14684] <https://github.com/Perl/perl5/issues/14684>
+.IP \(bu 4
+The description of \f(CW@INC\fR hooks in the documentation for \f(CW\*(C`require\*(C'\fR
+has been corrected to say that filter subroutines receive a useless
+first argument.
+[GH #12569] <https://github.com/Perl/perl5/issues/12569>
+.IP \(bu 4
+The documentation of \f(CW\*(C`ref\*(C'\fR has been rewritten for clarity.
+.IP \(bu 4
+The documentation of \f(CW\*(C`use\*(C'\fR now explains what syntactically qualifies
+as a version number for its module version checking feature.
+.IP \(bu 4
+The documentation of \f(CW\*(C`warn\*(C'\fR has been updated to reflect that since Perl
+5.14 it has treated complex exception objects in a manner equivalent
+to \f(CW\*(C`die\*(C'\fR.
+[GH #13641] <https://github.com/Perl/perl5/issues/13641>
+.IP \(bu 4
+The documentation of \f(CW\*(C`die\*(C'\fR and \f(CW\*(C`warn\*(C'\fR has been revised for clarity.
+.IP \(bu 4
+The documentation of \f(CW\*(C`each\*(C'\fR has been improved, with a slightly more
+explicit description of the sharing of iterator state, and with
+caveats regarding the fragility of while-each loops.
+[GH #16334] <https://github.com/Perl/perl5/issues/16334>
+.IP \(bu 4
+Clarification to \f(CW\*(C`require\*(C'\fR was added to explain the differences between
+.Sp
+.Vb 2
+\&    require Foo::Bar;
+\&    require "Foo/Bar.pm";
+.Ve
+.PP
+\fIperlgit\fR
+.IX Subsection "perlgit"
+.IP \(bu 4
+The precise rules for identifying \f(CW\*(C`smoke\-me\*(C'\fR branches are now stated.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+The section on reference counting in perlguts has been heavily revised,
+to describe references in the way a programmer needs to think about them
+rather than in terms of the physical data structures.
+.IP \(bu 4
+Improve documentation related to UTF\-8 multibytes.
+.PP
+\fIperlintern\fR
+.IX Subsection "perlintern"
+.IP \(bu 4
+The internal functions \f(CWnewXS_len_flags()\fR and \f(CWnewATTRSUB_x()\fR are
+now documented.
+.PP
+\fIperlobj\fR
+.IX Subsection "perlobj"
+.IP \(bu 4
+The documentation about \f(CW\*(C`DESTROY\*(C'\fR methods has been corrected, updated,
+and revised, especially in regard to how they interact with exceptions.
+[GH #14083] <https://github.com/Perl/perl5/issues/14083>
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+The description of the \f(CW\*(C`x\*(C'\fR operator in perlop has been clarified.
+[GH #16253] <https://github.com/Perl/perl5/issues/16253>
+.IP \(bu 4
+perlop has been updated to note that \f(CW\*(C`qw\*(C'\fR's whitespace rules differ
+from that of \f(CW\*(C`split\*(C'\fR's in that only ASCII whitespace is used.
+.IP \(bu 4
+The general explanation of operator precedence and associativity has
+been corrected and clarified.
+[GH #15153] <https://github.com/Perl/perl5/issues/15153>
+.IP \(bu 4
+The documentation for the \f(CW\*(C`\e\*(C'\fR referencing operator now explains the
+unusual context that it supplies to its operand.
+[GH #15932] <https://github.com/Perl/perl5/issues/15932>
+.PP
+\fIperlrequick\fR
+.IX Subsection "perlrequick"
+.IP \(bu 4
+Clarifications on metacharacters and character classes
+.PP
+\fIperlretut\fR
+.IX Subsection "perlretut"
+.IP \(bu 4
+Clarify metacharacters.
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+Clarify the differences between \fB\-M\fR and \fB\-m\fR.
+[GH #15998] <https://github.com/Perl/perl5/issues/15998>
+.PP
+\fIperlsec\fR
+.IX Subsection "perlsec"
+.IP \(bu 4
+The documentation about set-id scripts has been updated and revised.
+[GH #10289] <https://github.com/Perl/perl5/issues/10289>
+.IP \(bu 4
+A section about using \f(CW\*(C`sudo\*(C'\fR to run Perl scripts has been added.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+The section "Truth and Falsehood" in perlsyn has been removed from
+that document, where it didn't belong, and merged into the existing
+paragraph on the same topic in perldata.
+.IP \(bu 4
+The means to disambiguate between code blocks and hash constructors,
+already documented in perlref, are now documented in perlsyn too.
+[GH #15918] <https://github.com/Perl/perl5/issues/15918>
+.PP
+\fIperluniprops\fR
+.IX Subsection "perluniprops"
+.IP \(bu 4
+perluniprops has been updated to note that \f(CW\*(C`\ep{Word}\*(C'\fR now includes
+code points matching the \f(CW\*(C`\ep{Join_Control}\*(C'\fR property.  The change to
+the property was made in Perl 5.18, but not documented until now.  There
+are currently only two code points that match this property U+200C (ZERO
+WIDTH NON-JOINER) and U+200D (ZERO WIDTH JOINER).
+.IP \(bu 4
+For each binary table or property, the documentation now includes which
+characters in the range \f(CW\*(C`\ex00\-\exFF\*(C'\fR it matches, as well as a list of
+the first few ranges of code points matched above that.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+The entry for \f(CW$+\fR in perlvar has been expanded upon to describe handling of
+multiply-named capturing groups.
+.PP
+\fIperlfunc, perlop, perlsyn\fR
+.IX Subsection "perlfunc, perlop, perlsyn"
+.IP \(bu 4
+In various places, improve the documentation of the special cases
+in the condition expression of a while loop, such as implicit \f(CW\*(C`defined\*(C'\fR
+and assignment to \f(CW$_\fR.
+[GH #16334] <https://github.com/Perl/perl5/issues/16334>
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Can't "goto" into a "given" block
+.Sp
+(F) A "goto" statement was executed to jump into the middle of a \f(CW\*(C`given\*(C'\fR
+block.  You can't get there from here.  See "goto" in perlfunc.
+.IP \(bu 4
+Can't "goto" into a binary or list expression
+.Sp
+Use of \f(CW\*(C`goto\*(C'\fR to jump into the parameter of a binary or list operator has
+been prohibited, to prevent crashes and stack corruption.
+[GH #15914] <https://github.com/Perl/perl5/issues/15914>
+.Sp
+You may only enter the \fIfirst\fR argument of an operator that takes a fixed
+number of arguments, since this is a case that will not cause stack
+corruption.
+[GH #16415] <https://github.com/Perl/perl5/issues/16415>
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Old package separator used in string
+.Sp
+(W syntax) You used the old package separator, "'", in a variable
+named inside a double-quoted string; e.g., \f(CW"In $name\*(Aqs house"\fR.  This
+is equivalent to \f(CW"In $name::s house"\fR.  If you meant the former, put
+a backslash before the apostrophe (\f(CW"In $name\e\*(Aqs house"\fR).
+.IP \(bu 4
+"Locale '%s' contains (at least) the following characters which
+have unexpected meanings: \f(CW%s\fR  The Perl program will use the expected
+meanings" in perldiag
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+A false-positive warning that was issued when using a
+numerically-quantified sub-pattern in a recursive regex has been
+silenced. [GH #16106] <https://github.com/Perl/perl5/issues/16106>
+.IP \(bu 4
+The warning about useless use of a concatenation operator in void context
+is now generated for expressions with multiple concatenations, such as
+\&\f(CW\*(C`$a.$b.$c\*(C'\fR, which used to mistakenly not warn.
+[GH #3990] <https://github.com/Perl/perl5/issues/3990>
+.IP \(bu 4
+Warnings that a variable or subroutine "masks earlier declaration in same
+\&...", or that an \f(CW\*(C`our\*(C'\fR variable has been redeclared, have been moved to a
+new warnings category "shadow".  Previously they were in category "misc".
+.IP \(bu 4
+The deprecation warning from \f(CWSys::Hostname::hostname()\fR saying that
+it doesn't accept arguments now states the Perl version in which the
+warning will be upgraded to an error.
+[GH #14662] <https://github.com/Perl/perl5/issues/14662>
+.IP \(bu 4
+The perldiag entry for the error regarding a set-id script has been
+expanded to make clear that the error is reporting a specific security
+vulnerability, and to advise how to fix it.
+.IP \(bu 4
+The \f(CW\*(C`Unable to flush stdout\*(C'\fR error message was missing a trailing
+newline. [debian #875361]
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS perlbug
+.IX Subsection "perlbug"
+.IP \(bu 4
+\&\f(CW\*(C`\-\-help\*(C'\fR and \f(CW\*(C`\-\-version\*(C'\fR options have been added.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+C89 requirement
+.Sp
+Perl has been documented as requiring a C89 compiler to build since October
+1998.  A variety of simplifications have now been made to Perl's internals to
+rely on the features specified by the C89 standard. We believe that this
+internal change hasn't altered the set of platforms that Perl builds on, but
+please report a bug if Perl now has new problems building on your platform.
+.IP \(bu 4
+On GCC, \f(CW\*(C`\-Werror=pointer\-arith\*(C'\fR is now enabled by default,
+disallowing arithmetic on void and function pointers.
+.IP \(bu 4
+Where an HTML version of the documentation is installed, the HTML
+documents now use relative links to refer to each other.  Links from
+the index page of perlipc to the individual section documents are
+now correct.
+[GH #11941] <https://github.com/Perl/perl5/issues/11941>
+.IP \(bu 4
+\&\fIlib/unicore/mktables\fR now correctly canonicalizes the names of the
+dependencies stored in the files it generates.
+.Sp
+\&\fIregen/mk_invlists.pl\fR, unlike the other \fIregen/*.pl\fR scripts, used
+\&\f(CW$0\fR to name itself in the dependencies stored in the files it
+generates.  It now uses a literal so that the path stored in the
+generated files doesn't depend on how \fIregen/mk_invlists.pl\fR is
+invoked.
+.Sp
+This lack of canonical names could cause test failures in \fIt/porting/regen.t\fR.
+[GH #16446] <https://github.com/Perl/perl5/issues/16446>
+.IP \(bu 4
+New probes
+.RS 4
+.IP HAS_BUILTIN_ADD_OVERFLOW 2
+.IX Item "HAS_BUILTIN_ADD_OVERFLOW"
+.PD 0
+.IP HAS_BUILTIN_MUL_OVERFLOW 2
+.IX Item "HAS_BUILTIN_MUL_OVERFLOW"
+.IP HAS_BUILTIN_SUB_OVERFLOW 2
+.IX Item "HAS_BUILTIN_SUB_OVERFLOW"
+.IP HAS_THREAD_SAFE_NL_LANGINFO_L 2
+.IX Item "HAS_THREAD_SAFE_NL_LANGINFO_L"
+.IP HAS_LOCALECONV_L 2
+.IX Item "HAS_LOCALECONV_L"
+.IP HAS_MBRLEN 2
+.IX Item "HAS_MBRLEN"
+.IP HAS_MBRTOWC 2
+.IX Item "HAS_MBRTOWC"
+.IP HAS_MEMRCHR 2
+.IX Item "HAS_MEMRCHR"
+.IP HAS_NANOSLEEP 2
+.IX Item "HAS_NANOSLEEP"
+.IP HAS_STRNLEN 2
+.IX Item "HAS_STRNLEN"
+.IP HAS_STRTOLD_L 2
+.IX Item "HAS_STRTOLD_L"
+.IP I_WCHAR 2
+.IX Item "I_WCHAR"
+.RE
+.RS 4
+.RE
+.PD
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+Testing of the XS-APItest directory is now done in parallel, where
+applicable.
+.IP \(bu 4
+Perl now includes a default \fI.travis.yml\fR file for Travis CI testing
+on github mirrors.
+[GH #14558] <https://github.com/Perl/perl5/issues/14558>
+.IP \(bu 4
+The watchdog timer count in \fIre/pat_psycho.t\fR can now be overridden.
+.Sp
+This test can take a long time to run, so there is a timer to keep
+this in check (currently, 5 minutes). This commit adds checking
+the environment variable \f(CW\*(C`PERL_TEST_TIME_OUT_FACTOR\*(C'\fR; if set,
+the time out setting is multiplied by its value.
+.IP \(bu 4
+\&\fIharness\fR no longer waits for 30 seconds when running \fIt/io/openpid.t\fR.
+[GH #13535] <https://github.com/Perl/perl5/issues/13535>
+[GH #16420] <https://github.com/Perl/perl5/issues/16420>
+.SH Packaging
+.IX Header "Packaging"
+For the past few years we have released perl using three different archive
+formats: bzip (\f(CW\*(C`.bz2\*(C'\fR), LZMA2 (\f(CW\*(C`.xz\*(C'\fR) and gzip (\f(CW\*(C`.gz\*(C'\fR). Since xz compresses
+better and decompresses faster, and gzip is more compatible and uses less
+memory, we have dropped the \f(CW\*(C`.bz2\*(C'\fR archive format with this release.
+(If this poses a problem, do let us know; see "Reporting Bugs", below.)
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP "PowerUX / Power MAX OS" 4
+.IX Item "PowerUX / Power MAX OS"
+Compiler hints and other support for these apparently long-defunct
+platforms has been removed.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP CentOS 4
+.IX Item "CentOS"
+Compilation on CentOS 5 is now fixed.
+.IP Cygwin 4
+.IX Item "Cygwin"
+A build with the quadmath library can now be done on Cygwin.
+.IP Darwin 4
+.IX Item "Darwin"
+Perl now correctly uses reentrant functions, like \f(CW\*(C`asctime_r\*(C'\fR, on
+versions of Darwin that have support for them.
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+FreeBSD's \fI/usr/share/mk/sys.mk\fR specifies \f(CW\*(C`\-O2\*(C'\fR for
+architectures other than ARM and MIPS. By default, perl is now compiled
+with the same optimization levels.
+.IP VMS 4
+.IX Item "VMS"
+Several fix-ups for \fIconfigure.com\fR, marking function VMS has
+(or doesn't have).
+.Sp
+CRTL features can now be set by embedders before invoking Perl by using
+the \f(CW\*(C`decc$feature_set\*(C'\fR and \f(CW\*(C`decc$feature_set_value\*(C'\fR functions.
+Previously any attempt to set features after image initialization were
+ignored.
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Support for compiling perl on Windows using Microsoft Visual Studio 2017
+(containing Visual C++ 14.1) has been added.
+.IP \(bu 4
+Visual C++ compiler version detection has been improved to work on non-English
+language systems.
+.IP \(bu 4
+We now set \f(CW$Config{libpth}\fR correctly for 64\-bit builds using Visual C++
+versions earlier than 14.1.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+A new optimisation phase has been added to the compiler,
+\&\f(CWoptimize_optree()\fR, which does a top-down scan of a complete optree
+just before the peephole optimiser is run. This phase is not currently
+hookable.
+.IP \(bu 4
+An \f(CW\*(C`OP_MULTICONCAT\*(C'\fR op has been added. At \f(CWoptimize_optree()\fR time, a
+chain of \f(CW\*(C`OP_CONCAT\*(C'\fR and \f(CW\*(C`OP_CONST\*(C'\fR ops, together optionally with an
+\&\f(CW\*(C`OP_STRINGIFY\*(C'\fR and/or \f(CW\*(C`OP_SASSIGN\*(C'\fR, are combined into a single
+\&\f(CW\*(C`OP_MULTICONCAT\*(C'\fR op. The op is of type \f(CW\*(C`UNOP_AUX\*(C'\fR, and the aux array
+contains the argument count, plus a pointer to a constant string and a set
+of segment lengths. For example with
+.Sp
+.Vb 1
+\&    my $x = "foo=$foo, bar=$bar\en";
+.Ve
+.Sp
+the constant string would be \f(CW"foo=, bar=\en"\fR and the segment lengths
+would be (4,6,1). If the string contains characters such as \f(CW\*(C`\ex80\*(C'\fR, whose
+representation changes under utf8, two sets of strings plus lengths are
+precomputed and stored.
+.IP \(bu 4
+Direct access to \f(CW\*(C`PL_keyword_plugin\*(C'\fR is not
+safe in the presence of multithreading. A new
+\&\f(CW\*(C`wrap_keyword_plugin\*(C'\fR function has been
+added to allow XS modules to safely define custom keywords even when
+loaded from a thread, analogous to \f(CW\*(C`PL_check\*(C'\fR /
+\&\f(CW\*(C`wrap_op_checker\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`PL_statbuf\*(C'\fR interpreter variable has been removed.
+.IP \(bu 4
+The deprecated function \f(CWto_utf8_case()\fR, accessible from XS code, has
+been removed.
+.IP \(bu 4
+A new function
+\&\f(CWis_utf8_invariant_string_loc()\fR
+has been added that is like
+\&\f(CWis_utf8_invariant_string()\fR
+but takes an extra pointer parameter into which is stored the location
+of the first variant character, if any are found.
+.IP \(bu 4
+A new function, \f(CWPerl_langinfo()\fR has been
+added.  It is an (almost) drop-in replacement for the system
+\&\f(CWnl_langinfo(3)\fR, but works on platforms that lack that; as well as
+being more thread-safe, and hiding some gotchas with locale handling
+from the caller.  Code that uses this, needn't use \f(CWlocaleconv(3)\fR
+(and be affected by the gotchas) to find the decimal point, thousands
+separator, or currency symbol.  See "Perl_langinfo" in perlapi.
+.IP \(bu 4
+A new API function \f(CWsv_rvunweaken()\fR has
+been added to complement \f(CWsv_rvweaken()\fR.
+The implementation was taken from "unweaken" in Scalar::Util.
+.IP \(bu 4
+A new flag, \f(CW\*(C`SORTf_UNSTABLE\*(C'\fR, has been added. This will allow a
+future commit to make mergesort unstable when the user specifies ‘no
+sort stable’, since it has been decided that mergesort should remain
+stable by default.
+.IP \(bu 4
+XS modules can now automatically get reentrant versions of system
+functions on threaded perls.
+.Sp
+By adding
+.Sp
+.Vb 1
+\&    #define PERL_REENTRANT
+.Ve
+.Sp
+near the beginning of an \f(CW\*(C`XS\*(C'\fR file, it will be compiled so that
+whatever reentrant functions perl knows about on that system will
+automatically and invisibly be used instead of the plain, non-reentrant
+versions.  For example, if you write \f(CWgetpwnam()\fR in your code, on a
+system that has \f(CWgetpwnam_r()\fR all calls to the former will be translated
+invisibly into the latter.  This does not happen except on threaded
+perls, as they aren't needed otherwise.  Be aware that which functions
+have reentrant versions varies from system to system.
+.IP \(bu 4
+The \f(CW\*(C`PERL_NO_OP_PARENT\*(C'\fR build define is no longer supported, which means
+that perl is now always built with \f(CW\*(C`PERL_OP_PARENT\*(C'\fR enabled.
+.IP \(bu 4
+The format and content of the non\-utf8 transliteration table attached to
+the \f(CW\*(C`op_pv\*(C'\fR field of \f(CW\*(C`OP_TRANS\*(C'\fR/\f(CW\*(C`OP_TRANSR\*(C'\fR ops has changed. It's now a
+\&\f(CW\*(C`struct OPtrans_map\*(C'\fR.
+.IP \(bu 4
+A new compiler \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`dTHX_DEBUGGING\*(C'\fR. has been added.  This is
+useful for XS or C code that only need the thread context because their
+debugging statements that get compiled only under \f(CW\*(C`\-DDEBUGGING\*(C'\fR need
+one.
+.IP \(bu 4
+A new API function "Perl_setlocale" in perlapi has been added.
+.IP \(bu 4
+"sync_locale" in perlapi has been revised to return a boolean as to
+whether the system was using the global locale or not.
+.IP \(bu 4
+A new kind of magic scalar, called a "nonelem" scalar, has been introduced.
+It is stored in an array to denote a non-existent element, whenever such an
+element is accessed in a potential lvalue context.  It replaces the
+existing "defelem" (deferred element) magic wherever this is possible,
+being significantly more efficient.  This means that
+\&\f(CWsome_sub($sparse_array[$nonelem])\fR no longer has to create a new magic
+defelem scalar each time, as long as the element is within the array.
+.Sp
+It partially fixes the rare bug of deferred elements getting out of synch
+with their arrays when the array is shifted or unshifted.
+[GH #16364] <https://github.com/Perl/perl5/issues/16364>
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+List assignment (\f(CW\*(C`aassign\*(C'\fR) could in some rare cases allocate an
+entry on the mortals stack and leave the entry uninitialized, leading to
+possible crashes.
+[GH #16017] <https://github.com/Perl/perl5/issues/16017>
+.IP \(bu 4
+Attempting to apply an attribute to an \f(CW\*(C`our\*(C'\fR variable where a
+function of that name already exists could result in a NULL pointer
+being supplied where an SV was expected, crashing perl.
+[perl #131597] <https://rt.perl.org/Ticket/Display.html?id=131597>
+.IP \(bu 4
+\&\f(CW\*(C`split \*(Aq \*(Aq\*(C'\fR now correctly handles the argument being split when in the
+scope of the \f(CW\*(C`unicode_strings\*(C'\fR feature. Previously, when a string using the single-byte internal
+representation contained characters that are whitespace by Unicode rules but
+not by ASCII rules, it treated those characters as part of fields rather
+than as field separators.
+[GH #15904] <https://github.com/Perl/perl5/issues/15904>
+.IP \(bu 4
+Several built-in functions previously had bugs that could cause them to
+write to the internal stack without allocating room for the item being
+written. In rare situations, this could have led to a crash. These bugs have
+now been fixed, and if any similar bugs are introduced in future, they will
+be detected automatically in debugging builds.
+.Sp
+These internal stack usage checks introduced are also done
+by the \f(CW\*(C`entersub\*(C'\fR operator when calling XSUBs.  This means we can
+report which XSUB failed to allocate enough stack space.
+[GH #16126] <https://github.com/Perl/perl5/issues/16126>
+.IP \(bu 4
+Using a symbolic ref with postderef syntax as the key in a hash lookup was
+yielding an assertion failure on debugging builds.
+[GH #16029] <https://github.com/Perl/perl5/issues/16029>
+.IP \(bu 4
+Array and hash variables whose names begin with a caret now admit indexing
+inside their curlies when interpolated into strings, as in \f(CW"${^CAPTURE[0]}"\fR to index \f(CW\*(C`@{^CAPTURE}\*(C'\fR.
+[GH #16050] <https://github.com/Perl/perl5/issues/16050>
+.IP \(bu 4
+Fetching the name of a glob that was previously UTF\-8 but wasn't any
+longer would return that name flagged as UTF\-8.
+[GH #15971] <https://github.com/Perl/perl5/issues/15971>
+.IP \(bu 4
+The perl \f(CWsprintf()\fR function (via the underlying C function
+\&\f(CWPerl_sv_vcatpvfn_flags()\fR) has been heavily reworked to fix many minor
+bugs, including the integer wrapping of large width and precision
+specifiers and potential buffer overruns. It has also been made faster in
+many cases.
+.IP \(bu 4
+Exiting from an \f(CW\*(C`eval\*(C'\fR, whether normally or via an exception, now always
+frees temporary values (possibly calling destructors) \fIbefore\fR setting
+\&\f(CW$@\fR. For example:
+.Sp
+.Vb 3
+\&    sub DESTROY { eval { die "died in DESTROY"; } }
+\&    eval { bless []; };
+\&    # $@ used to be equal to "died in DESTROY" here; it\*(Aqs now "".
+.Ve
+.IP \(bu 4
+Fixed a duplicate symbol failure with \f(CW\*(C`\-flto \-mieee\-fp\*(C'\fR builds.
+\&\fIpp.c\fR defined \f(CW\*(C`_LIB_VERSION\*(C'\fR which \f(CW\*(C`\-lieee\*(C'\fR already defines.
+[GH #16086] <https://github.com/Perl/perl5/issues/16086>
+.IP \(bu 4
+The tokenizer no longer consumes the exponent part of a floating
+point number if it's incomplete.
+[GH #16073] <https://github.com/Perl/perl5/issues/16073>
+.IP \(bu 4
+On non-threaded builds, for \f(CW\*(C`m/$null/\*(C'\fR where \f(CW$null\fR is an empty
+string is no longer treated as if the \f(CW\*(C`/o\*(C'\fR flag was present when the
+previous matching match operator included the \f(CW\*(C`/o\*(C'\fR flag.  The
+rewriting used to implement this behavior could confuse the
+interpreter.  This matches the behaviour of threaded builds.
+[GH #14668] <https://github.com/Perl/perl5/issues/14668>
+.IP \(bu 4
+Parsing a \f(CW\*(C`sub\*(C'\fR definition could cause a use after free if the \f(CW\*(C`sub\*(C'\fR
+keyword was followed by whitespace including newlines (and comments.)
+[GH #16097] <https://github.com/Perl/perl5/issues/16097>
+.IP \(bu 4
+The tokenizer now correctly adjusts a parse pointer when skipping
+whitespace in a \f(CW\*(C`${identifier}\*(C'\fR construct.
+[perl #131949] <https://rt.perl.org/Public/Bug/Display.html?id=131949>
+.IP \(bu 4
+Accesses to \f(CW\*(C`${^LAST_FH}\*(C'\fR no longer assert after using any of a
+variety of I/O operations on a non-glob.
+[GH #15372] <https://github.com/Perl/perl5/issues/15372>
+.IP \(bu 4
+The XS-level \f(CWCopy()\fR, \f(CWMove()\fR, \f(CWZero()\fR macros and their variants now
+assert if the pointers supplied are \f(CW\*(C`NULL\*(C'\fR.  ISO C considers
+supplying NULL pointers to the functions these macros are built upon
+as undefined behaviour even when their count parameters are zero.
+Based on these assertions and the original bug report three macro
+calls were made conditional.
+[GH #16079] <https://github.com/Perl/perl5/issues/16079>
+[GH #16112] <https://github.com/Perl/perl5/issues/16112>
+.IP \(bu 4
+Only the \f(CW\*(C`=\*(C'\fR operator is permitted for defining defaults for
+parameters in subroutine signatures.  Previously other assignment
+operators, e.g. \f(CW\*(C`+=\*(C'\fR, were also accidentally permitted.
+[GH #16084] <https://github.com/Perl/perl5/issues/16084>
+.IP \(bu 4
+Package names are now always included in \f(CW\*(C`:prototype\*(C'\fR warnings
+[perl #131833] <https://rt.perl.org/Public/Bug/Display.html?id=131833>
+.IP \(bu 4
+The \f(CW\*(C`je_old_stack_hwm\*(C'\fR field, previously only found in the \f(CW\*(C`jmpenv\*(C'\fR
+structure on debugging builds, has been added to non-debug builds as
+well. This fixes an issue with some CPAN modules caused by the size of
+this structure varying between debugging and non-debugging builds.
+[GH #16122] <https://github.com/Perl/perl5/issues/16122>
+.IP \(bu 4
+The arguments to the \f(CWninstr()\fR macro are now correctly parenthesized.
+.IP \(bu 4
+A NULL pointer dereference in the \f(CWS_regmatch()\fR function has been
+fixed.
+[perl #132017] <https://rt.perl.org/Public/Bug/Display.html?id=132017>
+.IP \(bu 4
+Calling exec PROGRAM LIST with an empty \f(CW\*(C`LIST\*(C'\fR
+has been fixed.  This should call \f(CWexecvp()\fR with an empty \f(CW\*(C`argv\*(C'\fR array
+(containing only the terminating \f(CW\*(C`NULL\*(C'\fR pointer), but was instead just
+returning false (and not setting \f(CW$!\fR).
+[GH #16075] <https://github.com/Perl/perl5/issues/16075>
+.IP \(bu 4
+The \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR C function stopped working properly in Perl 5.22 when
+fetching a constant with a UTF\-8 name if that constant subroutine was stored in
+the stash as a simple scalar reference, rather than a full typeglob.  This has
+been corrected.
+.IP \(bu 4
+Single-letter debugger commands followed by an argument which starts with
+punctuation  (e.g. \f(CW\*(C`p$^V\*(C'\fR and \f(CW\*(C`x@ARGV\*(C'\fR) now work again.  They had been
+wrongly requiring a space between the command and the argument.
+[GH #13342] <https://github.com/Perl/perl5/issues/13342>
+.IP \(bu 4
+splice now throws an exception
+("Modification of a read-only value attempted") when modifying a read-only
+array.  Until now it had been silently modifying the array.  The new behaviour
+is consistent with the behaviour of push and
+unshift.
+[GH #15923] <https://github.com/Perl/perl5/issues/15923>
+.IP \(bu 4
+\&\f(CWstat()\fR, \f(CWlstat()\fR, and file test operators now fail if given a
+filename containing a nul character, in the same way that \f(CWopen()\fR
+already fails.
+.IP \(bu 4
+\&\f(CWstat()\fR, \f(CWlstat()\fR, and file test operators now reliably set \f(CW$!\fR when
+failing due to being applied to a closed or otherwise invalid file handle.
+.IP \(bu 4
+File test operators for Unix permission bits that don't exist on a
+particular platform, such as \f(CW\*(C`\-k\*(C'\fR (sticky bit) on Windows, now check that
+the file being tested exists before returning the blanket false result,
+and yield the appropriate errors if the argument doesn't refer to a file.
+.IP \(bu 4
+Fixed a 'read before buffer' overrun when parsing a range starting with
+\&\f(CW\*(C`\eN{}\*(C'\fR at the beginning of the character set for the transliteration
+operator.
+[GH #16189] <https://github.com/Perl/perl5/issues/16189>
+.IP \(bu 4
+Fixed a leaked scalar when parsing an empty \f(CW\*(C`\eN{}\*(C'\fR at compile-time.
+[GH #16189] <https://github.com/Perl/perl5/issues/16189>
+.IP \(bu 4
+Calling \f(CW\*(C`do $path\*(C'\fR on a directory or block device now yields a meaningful
+error code in \f(CW$!\fR.
+[GH #14841] <https://github.com/Perl/perl5/issues/14841>
+.IP \(bu 4
+Regexp substitution using an overloaded replacement value that provides
+a tainted stringification now correctly taints the resulting string.
+[GH #12495] <https://github.com/Perl/perl5/issues/12495>
+.IP \(bu 4
+Lexical sub declarations in \f(CW\*(C`do\*(C'\fR blocks such as \f(CW\*(C`do { my sub lex; 123 }\*(C'\fR
+could corrupt the stack, erasing items already on the stack in the
+enclosing statement.  This has been fixed.
+[GH #16243] <https://github.com/Perl/perl5/issues/16243>
+.IP \(bu 4
+\&\f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR can now handle repeat counts and lengths that
+exceed two billion.
+[GH #13179] <https://github.com/Perl/perl5/issues/13179>
+.IP \(bu 4
+Digits past the radix point in octal and binary floating point literals
+now have the correct weight on platforms where a floating point
+significand doesn't fit into an integer type.
+.IP \(bu 4
+The canonical truth value no longer has a spurious special meaning as a
+callable subroutine.  It used to be a magic placeholder for a missing
+\&\f(CW\*(C`import\*(C'\fR or \f(CW\*(C`unimport\*(C'\fR method, but is now treated like any other string
+\&\f(CW1\fR.
+[GH #14902] <https://github.com/Perl/perl5/issues/14902>
+.IP \(bu 4
+\&\f(CW\*(C`system\*(C'\fR now reduces its arguments to strings in the parent process, so
+any effects of stringifying them (such as overload methods being called
+or warnings being emitted) are visible in the way the program expects.
+[GH #13561] <https://github.com/Perl/perl5/issues/13561>
+.IP \(bu 4
+The \f(CWreadpipe()\fR built-in function now checks at compile time that
+it has only one parameter expression, and puts it in scalar context,
+thus ensuring that it doesn't corrupt the stack at runtime.
+[GH #2793] <https://github.com/Perl/perl5/issues/2793>
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR now performs correct reference counting when aliasing \f(CW$a\fR and
+\&\f(CW$b\fR, thus avoiding premature destruction and leakage of scalars if they
+are re-aliased during execution of the sort comparator.
+[GH #11422] <https://github.com/Perl/perl5/issues/11422>
+.IP \(bu 4
+\&\f(CW\*(C`reverse\*(C'\fR with no operand, reversing \f(CW$_\fR by default, is no longer in
+danger of corrupting the stack.
+[GH #16291] <https://github.com/Perl/perl5/issues/16291>
+.IP \(bu 4
+\&\f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`system\*(C'\fR, et al are no longer liable to have their argument
+lists corrupted by reentrant calls and by magic such as tied scalars.
+[GH #15660] <https://github.com/Perl/perl5/issues/15660>
+.IP \(bu 4
+Perl's own \f(CW\*(C`malloc\*(C'\fR no longer gets confused by attempts to allocate
+more than a gigabyte on a 64\-bit platform.
+[GH #13273] <https://github.com/Perl/perl5/issues/13273>
+.IP \(bu 4
+Stacked file test operators in a sort comparator expression no longer
+cause a crash.
+[GH #15626] <https://github.com/Perl/perl5/issues/15626>
+.IP \(bu 4
+An identity \f(CW\*(C`tr///\*(C'\fR transformation on a reference is no longer mistaken
+for that reference for the purposes of deciding whether it can be
+assigned to.
+[GH #15812] <https://github.com/Perl/perl5/issues/15812>
+.IP \(bu 4
+Lengthy hexadecimal, octal, or binary floating point literals no
+longer cause undefined behaviour when parsing digits that are of such
+low significance that they can't affect the floating point value.
+[GH #16114] <https://github.com/Perl/perl5/issues/16114>
+.IP \(bu 4
+\&\f(CW\*(C`open $$scalarref...\*(C'\fR and similar invocations no longer leak the file
+handle.
+[GH #12593] <https://github.com/Perl/perl5/issues/12593>
+.IP \(bu 4
+Some convoluted kinds of regexp no longer cause an arithmetic overflow
+when compiled.
+[GH #16113] <https://github.com/Perl/perl5/issues/16113>
+.IP \(bu 4
+The default typemap, by avoiding \f(CW\*(C`newGVgen\*(C'\fR, now no longer leaks when
+XSUBs return file handles (\f(CW\*(C`PerlIO *\*(C'\fR or \f(CW\*(C`FILE *\*(C'\fR).
+[GH #12593] <https://github.com/Perl/perl5/issues/12593>
+.IP \(bu 4
+Creating a \f(CW\*(C`BEGIN\*(C'\fR block as an XS subroutine with a prototype no longer
+crashes because of the early freeing of the subroutine.
+.IP \(bu 4
+The \f(CW\*(C`printf\*(C'\fR format specifier \f(CW\*(C`%.0f\*(C'\fR no longer rounds incorrectly
+[GH #9125] <https://github.com/Perl/perl5/issues/9125>,
+and now shows the correct sign for a negative zero.
+.IP \(bu 4
+Fixed an issue where the error \f(CW\*(C`Scalar value @arrayname[0] better
+written as $arrayname\*(C'\fR would give an error \f(CW\*(C`Cannot printf Inf with \*(Aqc\*(Aq\*(C'\fR
+when arrayname starts with \f(CW\*(C`Inf\*(C'\fR.
+[GH #16335] <https://github.com/Perl/perl5/issues/16335>
+.IP \(bu 4
+The Perl implementation of \f(CWgetcwd()\fR in \f(CW\*(C`Cwd\*(C'\fR in the PathTools
+distribution now behaves the same as XS implementation on errors: it
+returns an error, and sets \f(CW$!\fR.
+[GH #16338] <https://github.com/Perl/perl5/issues/16338>
+.IP \(bu 4
+Vivify array elements when putting them on the stack.
+Fixes [GH #5310] <https://github.com/Perl/perl5/issues/5310>
+(reported in April 2002).
+.IP \(bu 4
+Fixed parsing of braced subscript after parens. Fixes
+[GH #4688] <https://github.com/Perl/perl5/issues/4688>
+(reported in December 2001).
+.IP \(bu 4
+\&\f(CW\*(C`tr/non_utf8/long_non_utf8/c\*(C'\fR could give the wrong results when the
+length of the replacement character list was greater than 0x7fff.
+.IP \(bu 4
+\&\f(CW\*(C`tr/non_utf8/non_utf8/cd\*(C'\fR failed to add the implied
+\&\f(CW\*(C`\ex{100}\-\ex{7fffffff}\*(C'\fR to the search character list.
+.IP \(bu 4
+Compilation failures within "perl-within-perl" constructs, such as with
+string interpolation and the right part of \f(CW\*(C`s///e\*(C'\fR, now cause
+compilation to abort earlier.
+.Sp
+Previously compilation could continue in order to report other errors,
+but the failed sub-parse could leave partly parsed constructs on the
+parser shift-reduce stack, confusing the parser, leading to perl
+crashes.
+[GH #14739] <https://github.com/Perl/perl5/issues/14739>
+.IP \(bu 4
+On threaded perls where the decimal point (radix) character is not a
+dot, it has been possible for a race to occur between threads when one
+needs to use the real radix character (such as with \f(CW\*(C`sprintf\*(C'\fR).  This has
+now been fixed by use of a mutex on systems without thread-safe locales,
+and the problem just doesn't come up on those with thread-safe locales.
+.IP \(bu 4
+Errors while compiling a regex character class could sometime trigger an
+assertion failure.
+[GH #16172] <https://github.com/Perl/perl5/issues/16172>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.28.0 represents approximately 13 months of development since Perl
+5.26.0 and contains approximately 730,000 lines of changes across 2,200
+files from 77 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 580,000 lines of changes to 1,300 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.28.0:
+.PP
+Aaron Crane, Abigail, Ævar Arnfjörð Bjarmason, Alberto Simões, Alexandr
+Savca, Andrew Fresh, Andy Dougherty, Andy Lester, Aristotle Pagaltzis, Ask
+Bjørn Hansen, Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari
+Mannsåker, Dan Collins, Daniel Dragan, David Cantrell, David Mitchell,
+Dmitry Ulanov, Dominic Hargreaves, E. Choroba, Eric Herman, Eugen Konkov,
+Father Chrysostomos, Gene Sullivan, George Hartzell, Graham Knop, Harald
+Jörg, H.Merijn Brand, Hugo van der Sanden, Jacques Germishuys, James E
+Keenan, Jarkko Hietaniemi, Jerry D. Hedden, J. Nick Koston, John Lightsey,
+John Peacock, John P. Linderman, John SJ Anderson, Karen Etheridge, Karl
+Williamson, Ken Brown, Ken Cotterill, Leon Timmermans, Lukas Mai, Marco
+Fontani, Marc-Philip Werner, Matthew Horsfall, Neil Bowers, Nicholas Clark,
+Nicolas R., Niko Tyni, Pali, Paul Marquess, Peter John Acklam, Reini Urban,
+Renee Baecker, Ricardo Signes, Robin Barker, Sawyer X, Scott Lanning, Sergey
+Aleynikov, Shirakata Kentaro, Shoichi Kaji, Slaven Rezic, Smylers, Steffen
+Müller, Steve Hay, Sullivan Beck, Thomas Sibley, Todd Rinaldo, Tomasz
+Konojacki, Tom Hukins, Tom Wyant, Tony Cook, Vitali Peil, Yves Orton,
+Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5281delta.1 b/upstream/mageia-cauldron/man1/perl5281delta.1
new file mode 100644
index 00000000..00c9647b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5281delta.1
@@ -0,0 +1,176 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5281DELTA 1"
+.TH PERL5281DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5281delta \- what is new for perl v5.28.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.28.0 release and the 5.28.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.26.0, first read
+perl5280delta, which describes differences between 5.26.0 and 5.28.0.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2018\-18311] Integer overflow leading to buffer overflow and segmentation fault"
+.IX Subsection "[CVE-2018-18311] Integer overflow leading to buffer overflow and segmentation fault"
+Integer arithmetic in \f(CWPerl_my_setenv()\fR could wrap when the combined length
+of the environment variable name and value exceeded around 0x7fffffff.  This
+could lead to writing beyond the end of an allocated buffer with attacker
+supplied data.
+.PP
+[GH #16560] <https://github.com/Perl/perl5/issues/16560>
+.SS "[CVE\-2018\-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.IX Subsection "[CVE-2018-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+A crafted regular expression could cause heap-buffer-overflow write during
+compilation, potentially allowing arbitrary code execution.
+.PP
+[GH #16649] <https://github.com/Perl/perl5/issues/16649>
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.28.0.  If any exist,
+they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20180622 to 5.20181129_28.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Perl 5.28 introduced an \f(CWindex()\fR optimization when comparing to \-1 (or
+indirectly, e.g. >= 0).  When this optimization was triggered inside a \f(CW\*(C`when\*(C'\fR
+clause it caused a warning ("Argument \f(CW%s\fR isn't numeric in smart match").  This
+has now been fixed.
+[GH #16626] <https://github.com/Perl/perl5/issues/16626>
+.IP \(bu 4
+Matching of decimal digits in script runs, introduced in Perl 5.28, had a bug
+that led to \f(CW"1\eN{THAI DIGIT FIVE}"\fR matching \f(CW\*(C`/^(*sr:\ed+)$/\*(C'\fR when it should
+not.  This has now been fixed.
+.IP \(bu 4
+The new in-place editing code no longer leaks directory handles.
+[GH #16602] <https://github.com/Perl/perl5/issues/16602>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.28.1 represents approximately 5 months of development since Perl 5.28.0
+and contains approximately 6,100 lines of changes across 44 files from 12
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 700 lines of changes to 12 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.28.1:
+.PP
+Aaron Crane, Abigail, Chris 'BinGOs' Williams, Dagfinn Ilmari Mannsåker, David
+Mitchell, James E Keenan, John SJ Anderson, Karen Etheridge, Karl Williamson,
+Sawyer X, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5282delta.1 b/upstream/mageia-cauldron/man1/perl5282delta.1
new file mode 100644
index 00000000..483eb71d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5282delta.1
@@ -0,0 +1,227 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5282DELTA 1"
+.TH PERL5282DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5282delta \- what is new for perl v5.28.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.28.1 release and the 5.28.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.28.0, first read
+perl5281delta, which describes differences between 5.28.0 and 5.28.1.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Any set of digits in the Common script are legal in a script run of another script"
+.IX Subsection "Any set of digits in the Common script are legal in a script run of another script"
+There are several sets of digits in the Common script.  \f(CW\*(C`[0\-9]\*(C'\fR is the most
+familiar.  But there are also \f(CW\*(C`[\ex{FF10}\-\ex{FF19}]\*(C'\fR (FULLWIDTH DIGIT ZERO \-
+FULLWIDTH DIGIT NINE), and several sets for use in mathematical notation, such
+as the MATHEMATICAL DOUBLE-STRUCK DIGITs.  Any of these sets should be able to
+appear in script runs of, say, Greek.  But the previous design overlooked all
+but the ASCII digits \f(CW\*(C`[0\-9]\*(C'\fR, so the design was flawed.  This has been fixed,
+so is both a bug fix and an incompatibility.
+.PP
+All digits in a run still have to come from the same set of ten digits.
+.PP
+[GH #16704] <https://github.com/Perl/perl5/issues/16704>
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20181129_28 to 5.20190419.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.29 to 0.30.
+.IP \(bu 4
+Storable has been upgraded from version 3.08 to 3.08_01.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Windows 4
+.IX Item "Windows"
+The Windows Server 2003 SP1 Platform SDK build, with its early x64 compiler and
+tools, was accidentally broken in Perl 5.27.9.  This has now been fixed.
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+Perl's build and testing process on Mac OS X for \f(CW\*(C`\-Duseshrplib\*(C'\fR builds is now
+compatible with Mac OS X System Integrity Protection (SIP).
+.Sp
+SIP prevents binaries in \fI/bin\fR (and a few other places) being passed the
+\&\f(CW\*(C`DYLD_LIBRARY_PATH\*(C'\fR environment variable.  For our purposes this prevents
+\&\f(CW\*(C`DYLD_LIBRARY_PATH\*(C'\fR from being passed to the shell, which prevents that
+variable being passed to the testing or build process, so running \f(CW\*(C`perl\*(C'\fR
+couldn't find \fIlibperl.dylib\fR.
+.Sp
+To work around that, the initial build of the \fIperl\fR executable expects to
+find \fIlibperl.dylib\fR in the build directory, and the library path is then
+adjusted during installation to point to the installed library.
+.Sp
+[GH #15057] <https://github.com/Perl/perl5/issues/15057>
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+If an in-place edit is still in progress during global destruction and the
+process exit code (as stored in \f(CW$?\fR) is zero, perl will now treat the
+in-place edit as successful, replacing the input file with any output produced.
+.Sp
+This allows code like:
+.Sp
+.Vb 1
+\&  perl \-i \-ne \*(Aqprint "Foo"; last\*(Aq
+.Ve
+.Sp
+to replace the input file, while code like:
+.Sp
+.Vb 1
+\&  perl \-i \-ne \*(Aqprint "Foo"; die\*(Aq
+.Ve
+.Sp
+will not.  Partly resolves [perl #133659].
+.Sp
+[GH #16748] <https://github.com/Perl/perl5/issues/16748>
+.IP \(bu 4
+A regression in Perl 5.28 caused the following code to fail
+.Sp
+.Vb 1
+\& close(STDIN); open(CHILD, "|wc \-l")\*(Aq
+.Ve
+.Sp
+because the child's stdin would be closed on exec.  This has now been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`pack "u", "invalid uuencoding"\*(C'\fR now properly NUL terminates the zero-length
+SV produced.
+.Sp
+[GH #16343] <https://github.com/Perl/perl5/issues/16343>
+.IP \(bu 4
+Failing to compile a format now aborts compilation.  Like other errors in
+sub-parses this could leave the parser in a strange state, possibly crashing
+perl if compilation continued.
+.Sp
+[GH #16169] <https://github.com/Perl/perl5/issues/16169>
+.IP \(bu 4
+See "Any set of digits in the Common script are legal in a script run of
+another script".
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.28.2 represents approximately 4 months of development since Perl 5.28.1
+and contains approximately 2,500 lines of changes across 75 files from 13
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,200 lines of changes to 29 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.28.2:
+.PP
+Aaron Crane, Abigail, Andy Dougherty, David Mitchell, Karen Etheridge, Karl
+Williamson, Leon Timmermans, Nicolas R., Sawyer X, Steve Hay, Tina Müller,
+Tony Cook, Zak B. Elep.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/> .  There may also be information at
+<http://www.perl.org/> , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5283delta.1 b/upstream/mageia-cauldron/man1/perl5283delta.1
new file mode 100644
index 00000000..fe1a5ef3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5283delta.1
@@ -0,0 +1,186 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5283DELTA 1"
+.TH PERL5283DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5283delta \- what is new for perl v5.28.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.28.2 release and the 5.28.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.28.1, first read
+perl5282delta, which describes differences between 5.28.1 and 5.28.2.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+A signed \f(CW\*(C`size_t\*(C'\fR integer overflow in the storage space calculations for
+nested regular expression quantifiers could cause a heap buffer overflow in
+Perl's regular expression compiler that overwrites memory allocated after the
+regular expression storage space with attacker supplied data.
+.PP
+The target system needs a sufficient amount of memory to allocate partial
+expansions of the nested quantifiers prior to the overflow occurring.  This
+requirement is unlikely to be met on 64\-bit systems.
+.PP
+Discovered by: ManhND of The Tarantula Team, VinCSS (a member of Vingroup).
+.SS "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IX Subsection "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+Integer overflows in the calculation of offsets between instructions for the
+regular expression engine could cause corruption of the intermediate language
+state of a compiled regular expression.  An attacker could abuse this behaviour
+to insert instructions into the compiled form of a Perl regular expression.
+.PP
+Discovered by: Hugo van der Sanden and Slaven Rezic.
+.SS "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+Recursive calls to \f(CWS_study_chunk()\fR by Perl's regular expression compiler to
+optimize the intermediate language representation of a regular expression could
+cause corruption of the intermediate language state of a compiled regular
+expression.
+.PP
+Discovered by: Sergey Aleynikov.
+.SS "Additional Note"
+.IX Subsection "Additional Note"
+An application written in Perl would only be vulnerable to any of the above
+flaws if it evaluates regular expressions supplied by the attacker.  Evaluating
+regular expressions in this fashion is known to be dangerous since the regular
+expression engine does not protect against denial of service attacks in this
+usage scenario.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with Perl 5.28.2.  If any
+exist, they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20190419 to 5.20200601_28.
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.28.3 represents approximately 13 months of development since Perl 5.28.2
+and contains approximately 3,100 lines of changes across 48 files from 16
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,700 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.28.3:
+.PP
+Chris 'BinGOs' Williams, Dan Book, Hugo van der Sanden, James E Keenan, John
+Lightsey, Karen Etheridge, Karl Williamson, Matthew Horsfall, Max Maischein,
+Nicolas R., Renee Baecker, Sawyer X, Steve Hay, Tom Hukins, Tony Cook, Zak B.
+Elep.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://github.com/Perl/perl5/issues>.  There may also be information at
+<https://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5300delta.1 b/upstream/mageia-cauldron/man1/perl5300delta.1
new file mode 100644
index 00000000..53845950
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5300delta.1
@@ -0,0 +1,1073 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5300DELTA 1"
+.TH PERL5300DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5300delta \- what is new for perl v5.30.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.28.0 release and the 5.30.0
+release.
+.PP
+If you are upgrading from an earlier release such as 5.26.0, first read
+perl5280delta, which describes differences between 5.26.0 and 5.28.0.
+.SH Notice
+.IX Header "Notice"
+sv_utf8_(downgrade|decode) are no longer marked as experimental.
+[GH #16822] <https://github.com/Perl/perl5/issues/16822>.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Limited variable length lookbehind in regular expression pattern matching is now experimentally supported"
+.IX Subsection "Limited variable length lookbehind in regular expression pattern matching is now experimentally supported"
+Using a lookbehind assertion (like \f(CW\*(C`(?<=foo?)\*(C'\fR or \f(CW\*(C`(?<!ba{1,9}r)\*(C'\fR previously
+would generate an error and refuse to compile.  Now it compiles (if the
+maximum lookbehind is at most 255 characters), but raises a warning in
+the new \f(CW\*(C`experimental::vlb\*(C'\fR warnings category.  This is to caution you
+that the precise behavior is subject to change based on feedback from
+use in the field.
+.PP
+See "(?<=pattern)" in perlre and "(?<!pattern)" in perlre.
+.ie n .SS "The upper limit ""n"" specifiable in a regular expression quantifier of the form ""{m,n}"" has been doubled to 65534"
+.el .SS "The upper limit \f(CW""n""\fP specifiable in a regular expression quantifier of the form \f(CW""{m,n}""\fP has been doubled to 65534"
+.IX Subsection "The upper limit ""n"" specifiable in a regular expression quantifier of the form ""{m,n}"" has been doubled to 65534"
+The meaning of an unbounded upper quantifier \f(CW"{m,}"\fR remains unchanged.
+It matches 2**31 \- 1 times on most platforms, and more on ones where a C
+language short variable is more than 4 bytes long.
+.SS "Unicode 12.1 is supported"
+.IX Subsection "Unicode 12.1 is supported"
+Because of a change in Unicode release cycles, Perl jumps from Unicode
+10.0 in Perl 5.28 to Unicode 12.1 in Perl 5.30.
+.PP
+For details on the Unicode changes, see
+<https://www.unicode.org/versions/Unicode11.0.0/> for 11.0;
+<https://www.unicode.org/versions/Unicode12.0.0/> for 12.0;
+and
+<https://www.unicode.org/versions/Unicode12.1.0/> for 12.1.
+(Unicode 12.1 differs from 12.0 only in the addition of a single
+character, that for the new Japanese era name.)
+.PP
+The Word_Break property, as in past Perl releases, remains tailored to
+behave more in line with expectations of Perl users.  This means that
+sequential runs of horizontal white space characters are not broken
+apart, but kept as a single run.  Unicode 11 changed from past versions
+to be more in line with Perl, but it left several white space characters
+as causing breaks: TAB, NO BREAK SPACE, and FIGURE SPACE (U+2007).  We
+have decided to continue to use the previous Perl tailoring with regards
+to these.
+.SS "Wildcards in Unicode property value specifications are now partially supported"
+.IX Subsection "Wildcards in Unicode property value specifications are now partially supported"
+You can now do something like this in a regular expression pattern
+.PP
+.Vb 1
+\& qr! \ep{nv= /(?x) \eA [0\-5] \ez / }!
+.Ve
+.PP
+which matches all Unicode code points whose numeric value is
+between 0 and 5 inclusive.  So, it could match the Thai or Bengali
+digits whose numeric values are 0, 1, 2, 3, 4, or 5.
+.PP
+This marks another step in implementing the regular expression features
+the Unicode Consortium suggests.
+.PP
+Most properties are supported, with the remainder planned for 5.32.
+Details are in "Wildcards in Property Values" in perlunicode.
+.SS "qr'\eN{name}' is now supported"
+.IX Subsection "qr'N{name}' is now supported"
+Previously it was an error to evaluate a named character \f(CW\*(C`\eN{...}\*(C'\fR
+within a single quoted regular expression pattern (whose evaluation is
+deferred from the normal place).  This restriction is now removed.
+.SS "Turkic UTF\-8 locales are now seamlessly supported"
+.IX Subsection "Turkic UTF-8 locales are now seamlessly supported"
+Turkic languages have different casing rules than other languages for
+the characters \f(CW"i"\fR and \f(CW"I"\fR.  The uppercase of \f(CW"i"\fR is LATIN
+CAPITAL LETTER I WITH DOT ABOVE (U+0130); and the lowercase of \f(CW"I"\fR is LATIN
+SMALL LETTER DOTLESS I (U+0131).  Unicode furnishes alternate casing
+rules for use with Turkic languages.  Previously, Perl ignored these,
+but now, it uses them when it detects that it is operating under a
+Turkic UTF\-8 locale.
+.SS "It is now possible to compile perl to always use thread-safe locale operations."
+.IX Subsection "It is now possible to compile perl to always use thread-safe locale operations."
+Previously, these calls were only used when the perl was compiled to be
+multi-threaded.  To always enable them, add
+.PP
+.Vb 1
+\& \-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq
+.Ve
+.PP
+to your \fIConfigure\fR flags.
+.SS "Eliminate opASSIGN macro usage from core"
+.IX Subsection "Eliminate opASSIGN macro usage from core"
+This macro is still defined but no longer used in core
+.ie n .SS """\-Drv"" now means something on ""\-DDEBUGGING"" builds"
+.el .SS "\f(CW\-Drv\fP now means something on \f(CW\-DDEBUGGING\fP builds"
+.IX Subsection "-Drv now means something on -DDEBUGGING builds"
+Now, adding the verbose flag (\f(CW\*(C`\-Dv\*(C'\fR) to the \f(CW\*(C`\-Dr\*(C'\fR flag turns on all
+possible regular expression debugging.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.ie n .SS "Assigning non-zero to $[ is fatal"
+.el .SS "Assigning non-zero to \f(CW$[\fP is fatal"
+.IX Subsection "Assigning non-zero to $[ is fatal"
+Setting \f(CW$[\fR to a non-zero value has been deprecated since
+Perl 5.12 and now throws a fatal error.
+See "Assigning non-zero to \f(CW$[\fR is fatal" in perldeprecation.
+.SS "Delimiters must now be graphemes"
+.IX Subsection "Delimiters must now be graphemes"
+See "Use of unassigned code point or non-standalone grapheme
+for a delimiter." in perldeprecation
+.ie n .SS "Some formerly deprecated uses of an unescaped left brace ""{"" in regular expression patterns are now illegal"
+.el .SS "Some formerly deprecated uses of an unescaped left brace \f(CW""{""\fP in regular expression patterns are now illegal"
+.IX Subsection "Some formerly deprecated uses of an unescaped left brace ""{"" in regular expression patterns are now illegal"
+But to avoid breaking code unnecessarily, most instances that issued a
+deprecation warning, remain legal and now have a non-deprecation warning
+raised.  See "Unescaped left braces in regular expressions" in perldeprecation.
+.SS "Previously deprecated \fBsysread()\fP/\fBsyswrite()\fP on :utf8 handles is now fatal"
+.IX Subsection "Previously deprecated sysread()/syswrite() on :utf8 handles is now fatal"
+Calling \fBsysread()\fR, \fBsyswrite()\fR, \fBsend()\fR or \fBrecv()\fR on a \f(CW\*(C`:utf8\*(C'\fR handle,
+whether applied explicitly or implicitly, is now fatal.  This was
+deprecated in perl 5.24.
+.PP
+There were two problems with calling these functions on \f(CW\*(C`:utf8\*(C'\fR
+handles:
+.IP \(bu 4
+All four functions only paid attention to the \f(CW\*(C`:utf8\*(C'\fR flag.  Other
+layers were completely ignored, so a handle with
+\&\f(CW:encoding(UTF\-16LE)\fR layer would be treated as UTF\-8.  Other layers,
+such as compression are completely ignored with or without the
+\&\f(CW\*(C`:utf8\*(C'\fR flag.
+.IP \(bu 4
+\&\fBsysread()\fR and \fBrecv()\fR would read from the handle, skipping any
+validation by the layers, and do no validation of their own.  This
+could lead to invalidly encoded perl scalars.
+.PP
+[GH #14839] <https://github.com/Perl/perl5/issues/14839>.
+.SS "\fBmy()\fP in false conditional prohibited"
+.IX Subsection "my() in false conditional prohibited"
+Declarations such as \f(CW\*(C`my $x if 0\*(C'\fR are no longer permitted.
+.PP
+[GH #16702] <https://github.com/Perl/perl5/issues/16702>.
+.SS "Fatalize $* and $#"
+.IX Subsection "Fatalize $* and $#"
+These special variables, long deprecated, now throw exceptions when used.
+.PP
+[GH #16718] <https://github.com/Perl/perl5/issues/16718>.
+.SS "Fatalize unqualified use of \fBdump()\fP"
+.IX Subsection "Fatalize unqualified use of dump()"
+The \f(CWdump()\fR function, long discouraged, may no longer be used unless it is
+fully qualified, \fIi.e.\fR, \f(CWCORE::dump()\fR.
+.PP
+[GH #16719] <https://github.com/Perl/perl5/issues/16719>.
+.SS "Remove \fBFile::Glob::glob()\fP"
+.IX Subsection "Remove File::Glob::glob()"
+The \f(CWFile::Glob::glob()\fR function, long deprecated, has been removed and now
+throws an exception which advises use of \f(CWFile::Glob::bsd_glob()\fR instead.
+.PP
+[GH #16721] <https://github.com/Perl/perl5/issues/16721>.
+.ie n .SS "pack() no longer can return malformed UTF\-8"
+.el .SS "\f(CWpack()\fP no longer can return malformed UTF\-8"
+.IX Subsection "pack() no longer can return malformed UTF-8"
+It croaks if it would otherwise return a UTF\-8 string that contains
+malformed UTF\-8.  This protects against potential security threats.  This
+is considered a bug fix as well.
+[GH #16035] <https://github.com/Perl/perl5/issues/16035>.
+.SS "Any set of digits in the Common script are legal in a script run of another script"
+.IX Subsection "Any set of digits in the Common script are legal in a script run of another script"
+There are several sets of digits in the Common script.  \f(CW\*(C`[0\-9]\*(C'\fR is the
+most familiar.  But there are also \f(CW\*(C`[\ex{FF10}\-\ex{FF19}]\*(C'\fR (FULLWIDTH
+DIGIT ZERO \- FULLWIDTH DIGIT NINE), and several sets for use in
+mathematical notation, such as the MATHEMATICAL DOUBLE-STRUCK DIGITs.
+Any of these sets should be able to appear in script runs of, say,
+Greek.  But the design of 5.30 overlooked all but the ASCII digits
+\&\f(CW\*(C`[0\-9]\*(C'\fR, so the design was flawed.  This has been fixed, so is both a
+bug fix and an incompatibility.
+[GH #16704] <https://github.com/Perl/perl5/issues/16704>.
+.PP
+All digits in a run still have to come from the same set of ten digits.
+.SS "JSON::PP enables allow_nonref by default"
+.IX Subsection "JSON::PP enables allow_nonref by default"
+As JSON::XS 4.0 changed its policy and enabled allow_nonref
+by default, JSON::PP also enabled allow_nonref by default.
+.SH Deprecations
+.IX Header "Deprecations"
+.SS "In XS code, use of various macros dealing with UTF\-8."
+.IX Subsection "In XS code, use of various macros dealing with UTF-8."
+This deprecation was scheduled to become fatal in 5.30, but has been
+delayed to 5.32 due to problems that showed up with some CPAN modules.
+For details of what's affected, see perldeprecation.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Translating from UTF\-8 into the code point it represents now is done via a
+deterministic finite automaton, speeding it up.  As a typical example,
+\&\f(CWord("\ex7fff")\fR now requires 12% fewer instructions than before.  The
+performance of checking that a sequence of bytes is valid UTF\-8 is similarly
+improved, again by using a DFA.
+.IP \(bu 4
+Eliminate recursion from \fBfinalize_op()\fR.
+[GH #11866] <https://github.com/Perl/perl5/issues/11866>.
+.IP \(bu 4
+A handful of small optimizations related to character folding
+and character classes in regular expressions.
+.IP \(bu 4
+Optimization of \f(CW\*(C`IV\*(C'\fR to \f(CW\*(C`UV\*(C'\fR conversions.
+[GH #16761] <https://github.com/Perl/perl5/issues/16761>.
+.IP \(bu 4
+Speed up of the integer stringification algorithm by processing
+two digits at a time instead of one.
+[GH #16769] <https://github.com/Perl/perl5/issues/16769>.
+.IP \(bu 4
+Improvements based on LGTM analysis and recommendation.
+(<https://lgtm.com/projects/g/Perl/perl5/alerts/?mode=tree>). 
+[GH #16765] <https://github.com/Perl/perl5/issues/16765>.
+[GH #16773] <https://github.com/Perl/perl5/issues/16773>.
+.IP \(bu 4
+Code optimizations in \fIregcomp.c\fR, \fIregcomp.h\fR, \fIregexec.c\fR.
+.IP \(bu 4
+Regular expression pattern matching of things like \f(CW\*(C`qr/[^\fR\f(CIa\fR\f(CW]/\*(C'\fR is
+significantly sped up, where \fIa\fR is any ASCII character.  Other classes
+can get this speed up, but which ones is complicated and depends on the
+underlying bit patterns of those characters, so differs between ASCII
+and EBCDIC platforms, but all case pairs, like \f(CW\*(C`qr/[Gg]/\*(C'\fR are included,
+as is \f(CW\*(C`[^01]\*(C'\fR.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.30 to 2.32.
+.IP \(bu 4
+B has been upgraded from version 1.74 to 1.76.
+.IP \(bu 4
+B::Concise has been upgraded from version 1.003 to 1.004.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.48 to 1.49.
+.IP \(bu 4
+bignum has been upgraded from version 0.49 to 0.51.
+.IP \(bu 4
+bytes has been upgraded from version 1.06 to 1.07.
+.IP \(bu 4
+Carp has been upgraded from version 1.38 to 1.50
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.074 to 2.084.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.076 to 2.084.
+.IP \(bu 4
+Config::Extensions has been upgraded from version 0.02 to 0.03.
+.IP \(bu 4
+Config::Perl::V. has been upgraded from version 0.29 to 0.32. This was due
+to a new configuration variable that has influence on binary compatibility:
+\&\f(CW\*(C`USE_THREAD_SAFE_LOCALE\*(C'\fR.
+.IP \(bu 4
+CPAN has been upgraded from version 2.20 to 2.22.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.170 to 2.174
+.Sp
+Data::Dumper now avoids leaking when \f(CW\*(C`croak\*(C'\fRing.
+.IP \(bu 4
+DB_File has been upgraded from version 1.840 to 1.843.
+.IP \(bu 4
+deprecate has been upgraded from version 0.03 to 0.04.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.27 to 1.28.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.40 to 3.52.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 6.01 to 6.02.
+.IP \(bu 4
+Encode has been upgraded from version 2.97 to 3.01.
+.IP \(bu 4
+Errno has been upgraded from version 1.29 to 1.30.
+.IP \(bu 4
+experimental has been upgraded from version 0.019 to 0.020.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280230 to 0.280231.
+.IP \(bu 4
+ExtUtils::Manifest has been upgraded from version 1.70 to 1.72.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.39 to 3.40.
+\&\f(CW\*(C`OUTLIST\*(C'\fR parameters are no longer incorrectly included in the
+automatically generated function prototype.
+[GH #16746] <https://github.com/Perl/perl5/issues/16746>.
+.IP \(bu 4
+feature has been upgraded from version 1.52 to 1.54.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.33 to 2.34.
+.IP \(bu 4
+File::Find has been upgraded from version 1.34 to 1.36.
+.Sp
+\&\f(CW$File::Find::dont_use_nlink\fR now defaults to 1 on all
+platforms.
+[GH #16759] <https://github.com/Perl/perl5/issues/16759>.
+.Sp
+Variables \f(CW$Is_Win32\fR and \f(CW$Is_VMS\fR are being initialized.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.31 to 1.32.
+.IP \(bu 4
+File::Path has been upgraded from version 2.15 to 2.16.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.74 to 3.78.
+.Sp
+Silence Cwd warning on Android builds if \f(CW\*(C`targetsh\*(C'\fR is not defined.
+.IP \(bu 4
+File::Temp has been upgraded from version 0.2304 to 0.2309.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.58 to 1.59.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.070 to 0.076.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.17 to 0.18.
+.IP \(bu 4
+IO has been upgraded from version 1.39 to 1.40.
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.074 to 2.084.
+.Sp
+Adds support for \f(CW\*(C`IO::Uncompress::Zstd\*(C'\fR and
+\&\f(CW\*(C`IO::Uncompress::UnLzip\*(C'\fR.
+.Sp
+The \f(CW\*(C`BinModeIn\*(C'\fR and \f(CW\*(C`BinModeOut\*(C'\fR options are now no-ops.
+ALL files will be read/written in binmode.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 1.00 to 1.02.
+.IP \(bu 4
+JSON::PP has been upgraded from version 2.97001 to 4.02.
+.Sp
+JSON::PP as JSON::XS 4.0 enables \f(CW\*(C`allow_nonref\*(C'\fR by default.
+.IP \(bu 4
+lib has been upgraded from version 0.64 to 0.65.
+.IP \(bu 4
+Locale::Codes has been upgraded from version 3.56 to 3.57.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999811 to 1.999816.
+.Sp
+\&\f(CWbnok()\fR now supports the full Kronenburg extension.
+[cpan #95628] <https://rt.cpan.org/Ticket/Display.html?id=95628>.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.5006 to 0.5008.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2613 to 0.2614.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20180622 to 5.20190520.
+.Sp
+Changes to B::Op_private and Config
+.IP \(bu 4
+Module::Load has been upgraded from version 0.32 to 0.34.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000033 to 1.000036.
+.Sp
+Properly clean up temporary directories after testing.
+.IP \(bu 4
+NDBM_File has been upgraded from version 1.14 to 1.15.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.62 to 2.71.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.15 to 1.16.
+.IP \(bu 4
+PathTools has been upgraded from version 3.74 to 3.78.
+.IP \(bu 4
+parent has been upgraded from version 0.236 to 0.237.
+.IP \(bu 4
+perl5db.pl has been upgraded from version 1.54 to 1.55.
+.Sp
+Debugging threaded code no longer deadlocks in \f(CW\*(C`DB::sub\*(C'\fR nor
+\&\f(CW\*(C`DB::lsub\*(C'\fR.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.021011 to 5.20190126.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.26 to 0.27.
+.Sp
+Warnings enabled by setting the \f(CW\*(C`WARN_ON_ERR\*(C'\fR flag in
+\&\f(CW$PerlIO::encoding::fallback\fR are now only produced if warnings are
+enabled with \f(CW\*(C`use warnings "utf8";\*(C'\fR or setting \f(CW$^W\fR.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.29 to 0.30.
+.IP \(bu 4
+podlators has been upgraded from version 4.10 to 4.11.
+.IP \(bu 4
+POSIX has been upgraded from version 1.84 to 1.88.
+.IP \(bu 4
+re has been upgraded from version 0.36 to 0.37.
+.IP \(bu 4
+SDBM_File has been upgraded from version 1.14 to 1.15.
+.IP \(bu 4
+sigtrap has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+Storable has been upgraded from version 3.08 to 3.15.
+.Sp
+Storable no longer probes for recursion limits at build time.
+[GH #16780] <https://github.com/Perl/perl5/issues/16780>
+and others.
+.Sp
+Metasploit exploit code was included to test for CVE\-2015\-1592
+detection, this caused anti-virus detections on at least one AV suite.
+The exploit code has been removed and replaced with a simple
+functional test.
+[GH #16778] <https://github.com/Perl/perl5/issues/16778>
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302133 to 1.302162.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 3.12 to 3.13.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.58 to 1.60.
+.Sp
+Added support for extra tracing of locking, this requires a
+\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR and extra compilation flags.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9759 to 1.9760.
+.IP \(bu 4
+Time::Local has been upgraded from version 1.25 to 1.28.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.3204 to 1.33.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.25 to 1.27.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.70 to 0.72.
+.IP \(bu 4
+User::grent has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+utf8 has been upgraded from version 1.21 to 1.22.
+.IP \(bu 4
+vars has been upgraded from version 1.04 to 1.05.
+.Sp
+\&\f(CW\*(C`vars.pm\*(C'\fR no longer disables non-vars strict when checking if strict
+vars is enabled.
+[GH #15851] <https://github.com/Perl/perl5/issues/15851>.
+.IP \(bu 4
+version has been upgraded from version 0.9923 to 0.9924.
+.IP \(bu 4
+warnings has been upgraded from version 1.42 to 1.44.
+.IP \(bu 4
+XS::APItest has been upgraded from version 0.98 to 1.00.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.16 to 0.17.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+The following modules will be removed from the core distribution in a
+future release, and will at that time need to be installed from CPAN.
+Distributions on CPAN which require these modules will need to list them as
+prerequisites.
+.PP
+The core versions of these modules will now issue \f(CW"deprecated"\fR\-category
+warnings to alert you to this fact.  To silence these deprecation warnings,
+install the modules in question from CPAN.
+.PP
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use.  Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
+.IP \(bu 4
+B::Debug is no longer distributed with the core distribution.  It
+continues to be available on CPAN as
+\&\f(CW\*(C`B::Debug <https://metacpan.org/pod/B::Debug>\*(C'\fR.
+.IP \(bu 4
+Locale::Codes has been removed at the request of its author.  It
+continues to be available on CPAN as
+\&\f(CW\*(C`Locale::Codes <https://metacpan.org/pod/Locale::Codes>\*(C'\fR
+[GH #16660] <https://github.com/Perl/perl5/issues/16660>.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, send email
+to perlbug@perl.org <mailto:perlbug@perl.org>.
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+\&\f(CWAvFILL()\fR was wrongly listed as deprecated.  This has been corrected.
+[GH #16586] <https://github.com/Perl/perl5/issues/16586>
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+We no longer have null (empty line) here doc terminators, so
+perlop should not refer to them.
+.IP \(bu 4
+The behaviour of \f(CW\*(C`tr\*(C'\fR when the delimiter is an apostrophe has been clarified.
+In particular, hyphens aren't special, and \f(CW\*(C`\ex{}\*(C'\fR isn't interpolated.
+[GH #15853] <https://github.com/Perl/perl5/issues/15853>
+.PP
+\fIperlreapi, perlvar\fR
+.IX Subsection "perlreapi, perlvar"
+.IP \(bu 4
+Improve docs for lastparen, lastcloseparen.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+The entry for "\-X" in perlfunc has been clarified to indicate that symbolic
+links are followed for most tests.
+.IP \(bu 4
+Clarification of behaviour of \f(CW\*(C`reset EXPR\*(C'\fR.
+.IP \(bu 4
+Try to clarify that \f(CWref(qr/xx/)\fR returns \f(CW\*(C`Regexp\*(C'\fR rather than
+\&\f(CW\*(C`REGEXP\*(C'\fR and why.
+[GH #16801] <https://github.com/Perl/perl5/issues/16801>.
+.PP
+\fIperlreref\fR
+.IX Subsection "perlreref"
+.IP \(bu 4
+Clarification of the syntax of /(?(cond)yes)/.
+.PP
+\fIperllocale\fR
+.IX Subsection "perllocale"
+.IP \(bu 4
+There are actually two slightly different types of UTF\-8 locales: one for Turkic
+languages and one for everything else. Starting in Perl v5.30, Perl seamlessly 
+handles both types.
+.PP
+\fIperlrecharclass\fR
+.IX Subsection "perlrecharclass"
+.IP \(bu 4
+Added a note for the ::xdigit:: character class.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+More specific documentation of paragraph mode.
+[GH #16787] <https://github.com/Perl/perl5/issues/16787>.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+As noted under "Incompatible Changes" above, the deprecation warning
+"Unescaped left brace in regex is deprecated here (and will be fatal in Perl
+5.30), passed through in regex; marked by <\-\-\ HERE in m/%s/" has been
+changed to the non-deprecation warning "Unescaped left brace in regex is passed
+through in regex; marked by <\-\-\ HERE in m/%s/".
+.IP \(bu 4
+Specifying \f(CW\*(C`\eo{}\*(C'\fR without anything between the braces now yields the
+fatal error message "Empty \eo{}".  Previously it was  "Number with no
+digits".  This means the same wording is used for this kind of error as
+with similar constructs such as \f(CW\*(C`\ep{}\*(C'\fR.
+.IP \(bu 4
+Within the scope of the experimental feature \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR,
+specifying \f(CW\*(C`\ex{}\*(C'\fR without anything between the braces now yields the
+fatal error message "Empty \ex{}".  Previously it was  "Number with no
+digits".  This means the same wording is used for this kind of error as
+with similar constructs such as \f(CW\*(C`\ep{}\*(C'\fR.  It is legal, though not wise
+to have an empty \f(CW\*(C`\ex\*(C'\fR outside of \f(CW\*(C`re \*(Aqstrict\*(Aq\*(C'\fR; it silently generates
+a NUL character.
+.IP \(bu 4
+Type of arg \f(CW%d\fR to \f(CW%s\fR must be \f(CW%s\fR (not \f(CW%s\fR)
+.Sp
+Attempts to push, pop, etc on a hash or glob now produce this message
+rather than complaining that they no longer work on scalars.
+[GH #15774] <https://github.com/Perl/perl5/issues/15774>.
+.IP \(bu 4
+Prototype not terminated
+.Sp
+The file and line number is now reported for this error.
+[GH #16697] <https://github.com/Perl/perl5/issues/16697>
+.IP \(bu 4
+Under \f(CW\*(C`\-Dr\*(C'\fR (or \f(CW\*(C`use re \*(AqDebug\*(Aq\*(C'\fR) the compiled regex engine
+program is displayed. It used to use two different spellings for \fIinfinity\fR,
+\&\f(CW\*(C`INFINITY\*(C'\fR, and \f(CW\*(C`INFTY\*(C'\fR. It now uses the latter exclusively,
+as that spelling has been around the longest.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS xsubpp
+.IX Subsection "xsubpp"
+.IP \(bu 4
+The generated prototype (with \f(CW\*(C`PROTOTYPES: ENABLE\*(C'\fR) would include
+\&\f(CW\*(C`OUTLIST\*(C'\fR parameters, but these aren't arguments to the perl function.
+This has been rectified.
+[GH #16746] <https://github.com/Perl/perl5/issues/16746>.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Normally the thread-safe locale functions are used only on threaded
+builds.  It is now possible to force their use on unthreaded builds on
+systems that have them available, by including the
+\&\f(CW\*(C`\-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq\*(C'\fR option to \fIConfigure\fR.
+.IP \(bu 4
+Improve detection of memrchr, strlcat, and strlcpy
+.IP \(bu 4
+Improve Configure detection of \fBmemmem()\fR.
+[GH #16807] <https://github.com/Perl/perl5/issues/16807>.
+.IP \(bu 4
+Multiple improvements and fixes for \-DPERL_GLOBAL_STRUCT build option.
+.IP \(bu 4
+Fix \-DPERL_GLOBAL_STRUCT_PRIVATE build option.
+.SH Testing
+.IX Header "Testing"
+.IP \(bu 4
+\&\fIt/lib/croak/op\fR
+[GH #15774] <https://github.com/Perl/perl5/issues/15774>.
+.Sp
+separate error for \f(CW\*(C`push\*(C'\fR, etc. on hash/glob.
+.IP \(bu 4
+\&\fIt/op/svleak.t\fR
+[GH #16749] <https://github.com/Perl/perl5/issues/16749>.
+.Sp
+Add test for \f(CW\*(C`goto &sub\*(C'\fR in overload leaking.
+.IP \(bu 4
+Split \fIt/re/fold_grind.t\fR into multiple test files.
+.IP \(bu 4
+Fix intermittent tests which failed due to race conditions which
+surface during parallel testing.
+[GH #16795] <https://github.com/Perl/perl5/issues/16795>.
+.IP \(bu 4
+Thoroughly test paragraph mode, using a new test file,
+\&\fIt/io/paragraph_mode.t\fR.
+[GH #16787] <https://github.com/Perl/perl5/issues/16787>.
+.IP \(bu 4
+Some tests in \fIt/io/eintr.t\fR caused the process to hang on
+pre\-16 Darwin. These tests are skipped for those version of Darwin.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP "HP-UX 11.11" 4
+.IX Item "HP-UX 11.11"
+An obscure problem in \f(CWpack()\fR when compiling with HP C\-ANSI-C has been fixed
+by disabling optimizations in \fIpp_pack.c\fR.
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+Perl's build and testing process on Mac OS X for \f(CW\*(C`\-Duseshrplib\*(C'\fR
+builds is now compatible with Mac OS X System Integrity Protection
+(SIP).
+.Sp
+SIP prevents binaries in \fI/bin\fR (and a few other places) being passed
+the \f(CW\*(C`DYLD_LIBRARY_PATH\*(C'\fR environment variable.  For our purposes this
+prevents \f(CW\*(C`DYLD_LIBRARY_PATH\*(C'\fR from being passed to the shell, which
+prevents that variable being passed to the testing or build process,
+so running \f(CW\*(C`perl\*(C'\fR couldn't find \fIlibperl.dylib\fR.
+.Sp
+To work around that, the initial build of the \fIperl\fR executable
+expects to find \fIlibperl.dylib\fR in the build directory, and the
+library path is then adjusted during installation to point to the
+installed library.
+.Sp
+[GH #15057] <https://github.com/Perl/perl5/issues/15057>.
+.IP Minix3 4
+.IX Item "Minix3"
+Some support for Minix3 has been re-added.
+.IP Cygwin 4
+.IX Item "Cygwin"
+Cygwin doesn't make \f(CW\*(C`cuserid\*(C'\fR visible.
+.IP "Win32 Mingw" 4
+.IX Item "Win32 Mingw"
+C99 math functions are now available.
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The \f(CW\*(C`USE_CPLUSPLUS\*(C'\fR build option which has long been available in
+\&\fIwin32/Makefile\fR (for \fBnmake\fR) and \fIwin32/makefile.mk\fR (for \fBdmake\fR) is now
+also available in \fIwin32/GNUmakefile\fR (for \fBgmake\fR).
+.IP \(bu 4
+The \fBnmake\fR makefile no longer defaults to Visual C++ 6.0 (a very old version
+which is unlikely to be widely used today).  As a result, it is now a
+requirement to specify the \f(CW\*(C`CCTYPE\*(C'\fR since there is no obvious choice of which
+modern version to default to instead.  Failure to specify \f(CW\*(C`CCTYPE\*(C'\fR will result
+in an error being output and the build will stop.
+.Sp
+(The \fBdmake\fR and \fBgmake\fR makefiles will automatically detect which compiler
+is being used, so do not require \f(CW\*(C`CCTYPE\*(C'\fR to be set.  This feature has not yet
+been added to the \fBnmake\fR makefile.)
+.IP \(bu 4
+\&\f(CWsleep()\fR with warnings enabled for a \f(CW\*(C`USE_IMP_SYS\*(C'\fR build no longer
+warns about the sleep timeout being too large.
+[GH #16631] <https://github.com/Perl/perl5/issues/16631>.
+.IP \(bu 4
+Support for compiling perl on Windows using Microsoft Visual Studio 2019
+(containing Visual C++ 14.2) has been added.
+.IP \(bu 4
+\&\fBsocket()\fR now sets \f(CW$!\fR if the protocol, address family and socket
+type combination is not found.
+[GH #16849] <https://github.com/Perl/perl5/issues/16849>.
+.IP \(bu 4
+The Windows Server 2003 SP1 Platform SDK build, with its early x64 compiler and
+tools, was accidentally broken in Perl 5.27.9.  This has now been fixed.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+The sizing pass has been eliminated from the regular expression
+compiler.  An extra pass may instead be needed in some cases to count
+the number of parenthetical capture groups.
+.IP \(bu 4
+A new function "\f(CW\*(C`my_strtod\*(C'\fR" in perlapi or its synonym, \fBStrtod()\fR, is
+now available with the same signature as the libc \fBstrtod()\fR.  It provides
+\&\fBstrotod()\fR equivalent behavior on all platforms, using the best available
+precision, depending on platform capabilities and \fIConfigure\fR options,
+while handling locale-related issues, such as if the radix character
+should be a dot or comma.
+.IP \(bu 4
+Added \f(CWnewSVsv_nomg()\fR to copy a SV without processing get magic on
+the source.
+[GH #16461] <https://github.com/Perl/perl5/issues/16461>.
+.IP \(bu 4
+It is now forbidden to malloc more than \f(CW\*(C`PTRDIFF_T_MAX\*(C'\fR bytes.  Much
+code (including C optimizers) assumes that all data structures will not
+be larger than this, so this catches such attempts before overflow
+happens.
+.IP \(bu 4
+Two new regnodes have been introduced \f(CW\*(C`EXACT_ONLY8\*(C'\fR, and
+\&\f(CW\*(C`EXACTFU_ONLY8\*(C'\fR. They're equivalent to \f(CW\*(C`EXACT\*(C'\fR and \f(CW\*(C`EXACTFU\*(C'\fR,
+except that they contain a code point which requires UTF\-8 to
+represent/match. Hence, if the target string isn't UTF\-8, we know
+it can't possibly match, without needing to try.
+.IP \(bu 4
+\&\f(CWprint_bytes_for_locale()\fR is now defined if \f(CW\*(C`DEBUGGING\*(C'\fR,
+Prior, it didn't get defined unless \f(CW\*(C`LC_COLLATE\*(C'\fR was defined
+on the platform.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Compilation under \f(CW\*(C`\-DPERL_MEM_LOG\*(C'\fR and \f(CW\*(C`\-DNO_LOCALE\*(C'\fR have been fixed.
+.IP \(bu 4
+Perl 5.28 introduced an \f(CWindex()\fR optimization when comparing to \-1 (or
+indirectly, e.g. >= 0).  When this optimization was triggered inside a \f(CW\*(C`when\*(C'\fR
+clause it caused a warning ("Argument \f(CW%s\fR isn't numeric in smart match").  This
+has now been fixed.
+[GH #16626] <https://github.com/Perl/perl5/issues/16626>
+.IP \(bu 4
+The new in-place editing code no longer leaks directory handles.
+[GH #16602] <https://github.com/Perl/perl5/issues/16602>.
+.IP \(bu 4
+Warnings produced from constant folding operations on overloaded
+values no longer produce spurious "Use of uninitialized value"
+warnings.
+[GH #16349] <https://github.com/Perl/perl5/issues/16349>.
+.IP \(bu 4
+Fix for "mutator not seen in (lex = ...) .= ..."
+[GH #16655] <https://github.com/Perl/perl5/issues/16655>.
+.IP \(bu 4
+\&\f(CW\*(C`pack "u", "invalid uuencoding"\*(C'\fR now properly NUL terminates the
+zero-length SV produced.
+[GH #16343] <https://github.com/Perl/perl5/issues/16343>.
+.IP \(bu 4
+Improve the debugging output for \fBcalloc()\fR calls with \f(CW\*(C`\-Dm\*(C'\fR.
+[GH #16653] <https://github.com/Perl/perl5/issues/16653>.
+.IP \(bu 4
+Regexp script runs were failing to permit ASCII digits in some cases.
+[GH #16704] <https://github.com/Perl/perl5/issues/16704>.
+.IP \(bu 4
+On Unix-like systems supporting a platform-specific technique for
+determining \f(CW$^X\fR, Perl failed to fall back to the
+generic technique when the platform-specific one fails (for example, a Linux
+system with /proc not mounted).  This was a regression in Perl 5.28.0.
+[GH #16715] <https://github.com/Perl/perl5/issues/16715>.
+.IP \(bu 4
+SDBM_File is now more robust with corrupt database files.  The
+improvements do not make SDBM files suitable as an interchange format.
+[GH #16164] <https://github.com/Perl/perl5/issues/16164>.
+.IP \(bu 4
+\&\f(CW\*(C`binmode($fh);\*(C'\fR or \f(CW\*(C`binmode($fh, \*(Aq:raw\*(Aq);\*(C'\fR now properly removes the
+\&\f(CW\*(C`:utf8\*(C'\fR flag from the default \f(CW\*(C`:crlf\*(C'\fR I/O layer on Win32.
+[GH #16730] <https://github.com/Perl/perl5/issues/16730>.
+.IP \(bu 4
+The experimental reference aliasing feature was misinterpreting array and
+hash slice assignment as being localised, e.g.
+.Sp
+.Vb 1
+\&    \e(@a[3,5,7]) = \e(....);
+.Ve
+.Sp
+was being interpreted as:
+.Sp
+.Vb 1
+\&    local \e(@a[3,5,7]) = \e(....);
+.Ve
+.Sp
+[GH #16701] <https://github.com/Perl/perl5/issues/16701>.
+.IP \(bu 4
+\&\f(CW\*(C`sort SUBNAME\*(C'\fR within an \f(CW\*(C`eval EXPR\*(C'\fR when \f(CW\*(C`EXPR\*(C'\fR was UTF\-8 upgraded
+could panic if the \f(CW\*(C`SUBNAME\*(C'\fR was non-ASCII.
+[GH #16979] <https://github.com/Perl/perl5/issues/16979>.
+.IP \(bu 4
+Correctly handle \fBrealloc()\fR modifying \f(CW\*(C`errno\*(C'\fR on success so that the
+modification isn't visible to the perl user, since \fBrealloc()\fR is called
+implicitly by the interpreter.  This modification is permitted by the
+C standard, but has only been observed on FreeBSD 13.0\-CURRENT.
+[GH #16907] <https://github.com/Perl/perl5/issues/16907>.
+.IP \(bu 4
+Perl now exposes POSIX \f(CW\*(C`getcwd\*(C'\fR as \f(CWInternals::getcwd()\fR if
+available.  This is intended for use by \f(CW\*(C`Cwd.pm\*(C'\fR during bootstrapping
+and may be removed or changed without notice.  This fixes some
+bootstrapping issues while building perl in a directory where some
+ancestor directory isn't readable.
+[GH #16903] <https://github.com/Perl/perl5/issues/16903>.
+.IP \(bu 4
+\&\f(CWpack()\fR no longer can return malformed UTF\-8.  It croaks if it would
+otherwise return a UTF\-8 string that contains malformed UTF\-8.  This
+protects against potential security threats.
+[GH #16035] <https://github.com/Perl/perl5/issues/16035>.
+.IP \(bu 4
+See "Any set of digits in the Common script are legal in a script run
+of another script".
+.IP \(bu 4
+Regular expression matching no longer leaves stale UTF\-8 length magic
+when updating \f(CW$^R\fR. This could result in \f(CWlength($^R)\fR returning
+an incorrect value.
+.IP \(bu 4
+Reduce recursion on ops
+[GH #11866] <https://github.com/Perl/perl5/issues/11866>.
+.Sp
+This can prevent stack overflow when processing extremely deep op
+trees.
+.IP \(bu 4
+Avoid leak in multiconcat with overloading.
+[GH #16823] <https://github.com/Perl/perl5/issues/16823>.
+.IP \(bu 4
+The handling of user-defined \f(CW\*(C`\ep{}\*(C'\fR properties (see
+"User-Defined Character Properties" in perlunicode) has been rewritten to
+be in C (instead of Perl).  This speeds things up, but in the process
+several inconsistencies and bug fixes are made.
+.RS 4
+.IP 1. 4
+A few error messages have minor wording changes.  This is essentially
+because the new way is integrated into the regex error handling
+mechanism that marks the position in the input at which the error
+occurred.  That was not possible previously.  The messages now also
+contain additional back-trace-like information in case the error occurs
+deep in nested calls.
+.IP 2. 4
+A user-defined property is implemented as a perl subroutine with certain
+highly constrained naming conventions.  It was documented previously
+that the sub would be in the current package if the package was
+unspecified.  This turned out not to be true in all cases, but now it
+is.
+.IP 3. 4
+All recursive calls are treated as infinite recursion.  Previously they
+would cause the interpreter to panic.  Now, they cause the regex pattern
+to fail to compile.
+.IP 4. 4
+Similarly, any other error likely would lead to a panic; now to just the
+pattern failing to compile.
+.IP 5. 4
+The old mechanism did not detect illegal ranges in the definition of the
+property.  Now, the range max must not be smaller than the range min.
+Otherwise, the pattern fails to compile.
+.IP 6. 4
+The intention was to have each sub called only once during the lifetime
+of the program, so that a property's definition is immutable.  This was
+relaxed so that it could be called once for all /i compilations, and
+potentially a second time for non\-/i (the sub is passed a parameter
+indicating which).  However, in practice there were instances when this
+was broken, and multiple calls were possible.  Those have been fixed.
+Now (besides the /i,non\-/i cases) the only way a sub can be called
+multiple times is if some component of it has not been defined yet.  For
+example, suppose we have sub \fBIsA()\fR whose definition is known at compile
+time, and it in turn calls \fBisB()\fR whose definition is not yet known.
+\&\fBisA()\fR will be called each time a pattern it appears in is compiled.  If
+\&\fBisA()\fR also calls \fBisC()\fR and that definition is known, \fBisC()\fR will be
+called just once.
+.IP 7. 4
+There were some races and very long hangs should one thread be compiling
+the same property as another simultaneously.  These have now been fixed.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Fixed a failure to match properly.
+.Sp
+An EXACTFish regnode has a finite length it can hold for the string
+being matched.  If that length is exceeded, a second node is used for
+the next segment of the string, for as many regnodes as are needed.
+Care has to be taken where to break the string, in order to deal
+multi-character folds in Unicode correctly. If we want to break a
+string at a place which could potentially be in the middle of a
+multi-character fold, we back off one (or more) characters, leaving
+a shorter EXACTFish regnode. This backing off mechanism contained
+an off-by-one error.
+[GH #16806] <https://github.com/Perl/perl5/issues/16806>.
+.IP \(bu 4
+A bare \f(CW\*(C`eof\*(C'\fR call with no previous file handle now returns true.
+[GH #16786] <https://github.com/Perl/perl5/issues/16786>
+.IP \(bu 4
+Failing to compile a format now aborts compilation.  Like other errors
+in sub-parses this could leave the parser in a strange state, possibly
+crashing perl if compilation continued.
+[GH #16169] <https://github.com/Perl/perl5/issues/16169>
+.IP \(bu 4
+If an in-place edit is still in progress during global destruction and
+the process exit code (as stored in \f(CW$?\fR) is zero, perl will now
+treat the in-place edit as successful, replacing the input file with
+any output produced.
+.Sp
+This allows code like:
+.Sp
+.Vb 1
+\&  perl \-i \-ne \*(Aqprint "Foo"; last\*(Aq
+.Ve
+.Sp
+to replace the input file, while code like:
+.Sp
+.Vb 1
+\&  perl \-i \-ne \*(Aqprint "Foo"; die\*(Aq
+.Ve
+.Sp
+will not.  Partly resolves
+[GH #16748] <https://github.com/Perl/perl5/issues/16748>.
+.IP \(bu 4
+A regression in 5.28 caused the following code to fail
+.Sp
+.Vb 1
+\& close(STDIN); open(CHILD, "|wc \-l")\*(Aq
+.Ve
+.Sp
+because the child's stdin would be closed on exec. This has now been fixed.
+.IP \(bu 4
+Fixed an issue where compiling a regexp containing both compile-time
+and run-time code blocks could lead to trying to compile something
+which is invalid syntax.
+.IP \(bu 4
+Fixed build failures with \f(CW\*(C`\-DNO_LOCALE_NUMERIC\*(C'\fR and
+\&\f(CW\*(C`\-DNO_LOCALE_COLLATE\*(C'\fR.
+[GH #16771] <https://github.com/Perl/perl5/issues/16771>.
+.IP \(bu 4
+Prevent the tests in \fIext/B/t/strict.t\fR from being skipped.
+[GH #16783] <https://github.com/Perl/perl5/issues/16783>.
+.IP \(bu 4
+\&\f(CW\*(C`/di\*(C'\fR nodes ending or beginning in \fIs\fR are now \f(CW\*(C`EXACTF\*(C'\fR. We do not
+want two \f(CW\*(C`EXACTFU\*(C'\fR to be joined together during optimization,
+and to form a \f(CW\*(C`ss\*(C'\fR, \f(CW\*(C`sS\*(C'\fR, \f(CW\*(C`Ss\*(C'\fR or \f(CW\*(C`SS\*(C'\fR sequence;
+they are the only multi-character sequences which may match differently
+under \f(CW\*(C`/ui\*(C'\fR and \f(CW\*(C`/di\*(C'\fR.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.30.0 represents approximately 11 months of development since Perl
+5.28.0 and contains approximately 620,000 lines of changes across 1,300
+files from 58 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 510,000 lines of changes to 750 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.30.0:
+.PP
+Aaron Crane, Abigail, Alberto Simões, Alexandr Savca, Andreas König, Andy
+Dougherty, Aristotle Pagaltzis, Brian Greenfield, Chad Granum, Chris
+\&'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Book, Dan
+Dedrick, Daniel Dragan, Dan Kogai, David Cantrell, David Mitchell, Dominic
+Hargreaves, E. Choroba, Ed J, Eugen Konkov, François Perrad, Graham Knop,
+Hauke D, H.Merijn Brand, Hugo van der Sanden, Jakub Wilk, James Clarke,
+James E Keenan, Jerry D. Hedden, Jim Cromie, John SJ Anderson, Karen
+Etheridge, Karl Williamson, Leon Timmermans, Matthias Bethke, Nicholas
+Clark, Nicolas R., Niko Tyni, Pali, Petr Písař, Phil Pearl (Lobbes),
+Richard Leach, Ryan Voots, Sawyer X, Shlomi Fish, Sisyphus, Slaven Rezic,
+Steve Hay, Sullivan Beck, Tina Müller, Tomasz Konojacki, Tom Wyant, Tony
+Cook, Unicode Consortium, Yves Orton, Zak B. Elep.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of most of the (very much appreciated) contributors who reported
+issues to the Perl bug tracker. Noteworthy in this release were the large
+number of bug fixes made possible by Sergey Aleynikov's high quality perlbug
+reports for issues he discovered by fuzzing with AFL.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://rt.perl.org/>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5301delta.1 b/upstream/mageia-cauldron/man1/perl5301delta.1
new file mode 100644
index 00000000..9b9316da
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5301delta.1
@@ -0,0 +1,206 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5301DELTA 1"
+.TH PERL5301DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5301delta \- what is new for perl v5.30.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.30.0 release and the 5.30.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.28.0, first read
+perl5300delta, which describes differences between 5.28.0 and 5.30.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.30.1.  If any exist,
+they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20190522 to 5.20191110.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes listed in
+this document.  If you find any we have missed, send email to
+perlbug@perl.org <mailto:perlbug@perl.org>.
+.PP
+Additionally, documentation has been updated to reference GitHub as the new
+canonical repository and to describe the new GitHub pull request workflow.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+The \f(CW\*(C`ECHO\*(C'\fR macro is now defined.  This is used in a \f(CW\*(C`dtrace\*(C'\fR rule that was
+originally changed for FreeBSD, and the FreeBSD make apparently predefines it.
+The Solaris make does not predefine \f(CW\*(C`ECHO\*(C'\fR which broke this rule on Solaris.
+[perl #17057] <https://github.com/perl/perl5/issues/17057>
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Win32 4
+.IX Item "Win32"
+The locale tests could crash on Win32 due to a Windows bug, and separately due
+to the CRT throwing an exception if the locale name wasn't validly encoded in
+the current code page.
+.Sp
+For the second we now decode the locale name ourselves, and always decode it as
+UTF\-8.
+.Sp
+[perl #16922] <https://github.com/perl/perl5/issues/16922>
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Setting \f(CW$)\fR now properly sets supplementary group ids, if you have the
+necessary privileges.
+[perl #17031] <https://github.com/perl/perl5/issues/17031>
+.IP \(bu 4
+\&\f(CW\*(C`readline @foo\*(C'\fR now evaluates \f(CW@foo\fR in scalar context.  Previously, it would
+be evaluated in list context, and since \fBreadline()\fR pops only one argument from
+the stack, the stack could underflow, or be left with unexpected values on it.
+[perl #16929] <https://github.com/perl/perl5/issues/16929>
+.IP \(bu 4
+\&\fBsv_gets()\fR now recovers better if the target SV is modified by a signal handler.
+[perl #16960] <https://github.com/perl/perl5/issues/16960>
+.IP \(bu 4
+Matching a non\-\f(CW\*(C`SVf_UTF8\*(C'\fR string against a regular expression containing
+Unicode literals could leak an SV on each match attempt.
+[perl #17140] <https://github.com/perl/perl5/issues/17140>
+.IP \(bu 4
+\&\f(CW\*(C`sprintf("%.*a", \-10000, $x)\*(C'\fR would cause a buffer overflow due to
+mishandling of the negative precision value.
+[perl #16942] <https://github.com/perl/perl5/issues/16942>
+.IP \(bu 4
+\&\f(CWscalar()\fR on a reference could cause an erroneous assertion failure during
+compilation.
+[perl #16969] <https://github.com/perl/perl5/issues/16969>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.30.1 represents approximately 6 months of development since Perl 5.30.0
+and contains approximately 4,700 lines of changes across 67 files from 14
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 910 lines of changes to 20 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.30.1:
+.PP
+Chris 'BinGOs' Williams, Dan Book, David Mitchell, Hugo van der Sanden, James E
+Keenan, Karen Etheridge, Karl Williamson, Manuel Mausz, Max Maischein, Nicolas
+R., Sawyer X, Steve Hay, Tom Hukins, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://rt.perl.org/>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the perlbug program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of \f(CW\*(C`perl \-V\*(C'\fR,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5302delta.1 b/upstream/mageia-cauldron/man1/perl5302delta.1
new file mode 100644
index 00000000..42e0fc6b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5302delta.1
@@ -0,0 +1,192 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5302DELTA 1"
+.TH PERL5302DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5302delta \- what is new for perl v5.30.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.30.1 release and the 5.30.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.30.0, first read
+perl5301delta, which describes differences between 5.30.0 and 5.30.1.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.30.0.  If any exist,
+they are bugs, and we request that you submit a report.  See "Reporting Bugs"
+below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.084 to 2.089.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20191110 to 5.20200314.
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, send email
+to <https://github.com/Perl/perl5/issues>.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+GCC 10 is now supported by \fIConfigure\fR.
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Windows 4
+.IX Item "Windows"
+The MYMALLOC (PERL_MALLOC) build on Windows has been fixed.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\fBprintf()\fR or \fBsprintf()\fR with the \f(CW%n\fR format no longer cause a panic on
+debugging builds, or report an incorrectly cached length value when producing
+\&\f(CW\*(C`SVfUTF8\*(C'\fR flagged strings.
+.Sp
+[GH #17221 <https://github.com/Perl/perl5/issues/17221>]
+.IP \(bu 4
+A memory leak in regular expression patterns has been fixed.
+.Sp
+[GH #17218 <https://github.com/Perl/perl5/issues/17218>]
+.IP \(bu 4
+A read beyond buffer in grok_infnan has been fixed.
+.Sp
+[GH #17370 <https://github.com/Perl/perl5/issues/17370>]
+.IP \(bu 4
+An assertion failure in the regular expression engine has been fixed.
+.Sp
+[GH #17372 <https://github.com/Perl/perl5/issues/17372>]
+.IP \(bu 4
+\&\f(CW\*(C`(?{...})\*(C'\fR eval groups in regular expressions no longer unintentionally
+trigger "EVAL without pos change exceeded limit in regex".
+.Sp
+[GH #17490 <https://github.com/Perl/perl5/issues/17490>]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.30.2 represents approximately 4 months of development since Perl 5.30.1
+and contains approximately 2,100 lines of changes across 110 files from 15
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 920 lines of changes to 30 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.30.2:
+.PP
+Chris 'BinGOs' Williams, Dan Book, David Mitchell, Hugo van der Sanden, Karen
+Etheridge, Karl Williamson, Matthew Horsfall, Nicolas R., Petr Písař, Renee
+Baecker, Sawyer X, Steve Hay, Tomasz Konojacki, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://rt.perl.org/>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see "SECURITY
+VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5303delta.1 b/upstream/mageia-cauldron/man1/perl5303delta.1
new file mode 100644
index 00000000..f80f0989
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5303delta.1
@@ -0,0 +1,184 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5303DELTA 1"
+.TH PERL5303DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5303delta \- what is new for perl v5.30.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.30.2 release and the 5.30.3
+release.
+.PP
+If you are upgrading from an earlier release such as 5.30.1, first read
+perl5302delta, which describes differences between 5.30.1 and 5.30.2.
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+A signed \f(CW\*(C`size_t\*(C'\fR integer overflow in the storage space calculations for
+nested regular expression quantifiers could cause a heap buffer overflow in
+Perl's regular expression compiler that overwrites memory allocated after the
+regular expression storage space with attacker supplied data.
+.PP
+The target system needs a sufficient amount of memory to allocate partial
+expansions of the nested quantifiers prior to the overflow occurring.  This
+requirement is unlikely to be met on 64\-bit systems.
+.PP
+Discovered by: ManhND of The Tarantula Team, VinCSS (a member of Vingroup).
+.SS "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IX Subsection "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+Integer overflows in the calculation of offsets between instructions for the
+regular expression engine could cause corruption of the intermediate language
+state of a compiled regular expression.  An attacker could abuse this behaviour
+to insert instructions into the compiled form of a Perl regular expression.
+.PP
+Discovered by: Hugo van der Sanden and Slaven Rezic.
+.SS "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+Recursive calls to \f(CWS_study_chunk()\fR by Perl's regular expression compiler to
+optimize the intermediate language representation of a regular expression could
+cause corruption of the intermediate language state of a compiled regular
+expression.
+.PP
+Discovered by: Sergey Aleynikov.
+.SS "Additional Note"
+.IX Subsection "Additional Note"
+An application written in Perl would only be vulnerable to any of the above
+flaws if it evaluates regular expressions supplied by the attacker.  Evaluating
+regular expressions in this fashion is known to be dangerous since the regular
+expression engine does not protect against denial of service attacks in this
+usage scenario.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with Perl 5.30.2.  If any
+exist, they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20200314 to 5.20200601_30.
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.30.3 represents approximately 3 months of development since Perl 5.30.2
+and contains approximately 1,100 lines of changes across 42 files from 7
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 350 lines of changes to 8 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.30.3:
+.PP
+Chris 'BinGOs' Williams, Hugo van der Sanden, John Lightsey, Karl Williamson,
+Nicolas R., Sawyer X, Steve Hay.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://github.com/Perl/perl5/issues>.  There may also be information at
+<https://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5320delta.1 b/upstream/mageia-cauldron/man1/perl5320delta.1
new file mode 100644
index 00000000..a9b2845a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5320delta.1
@@ -0,0 +1,1401 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5320DELTA 1"
+.TH PERL5320DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5320delta \- what is new for perl v5.32.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.30.0 release and the 5.32.0
+release.
+.PP
+If you are upgrading from an earlier release such as 5.28.0, first read
+perl5300delta, which describes differences between 5.28.0 and 5.30.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "The isa Operator"
+.IX Subsection "The isa Operator"
+A new experimental infix operator called \f(CW\*(C`isa\*(C'\fR tests whether a given object
+is an instance of a given class or a class derived from it:
+.PP
+.Vb 1
+\&    if( $obj isa Package::Name ) { ... }
+.Ve
+.PP
+For more detail see "Class Instance Operator" in perlop.
+.SS "Unicode 13.0 is supported"
+.IX Subsection "Unicode 13.0 is supported"
+See <https://www.unicode.org/versions/Unicode13.0.0/> for details.
+.SS "Chained comparisons capability"
+.IX Subsection "Chained comparisons capability"
+Some comparison operators, as their associativity, \fIchain\fR with some
+operators of the same precedence (but never with operators of different
+precedence).
+.PP
+.Vb 1
+\&    if ( $x < $y <= $z ) {...}
+.Ve
+.PP
+behaves exactly like:
+.PP
+.Vb 1
+\&    if ( $x < $y && $y <= $z ) {...}
+.Ve
+.PP
+(assuming that \f(CW"$y"\fR is as simple a scalar as it looks.)
+.PP
+You can read more about this in perlop under
+"Operator Precedence and Associativity" in perlop.
+.ie n .SS "New Unicode properties ""Identifier_Status"" and ""Identifier_Type"" supported"
+.el .SS "New Unicode properties \f(CWIdentifier_Status\fP and \f(CWIdentifier_Type\fP supported"
+.IX Subsection "New Unicode properties Identifier_Status and Identifier_Type supported"
+Unicode has revised its regular expression requirements:
+<https://www.unicode.org/reports/tr18/tr18\-21.html>.
+As part of that they are wanting more properties to be exposed, ones
+that aren't part of the strict UCD (Unicode character database). These
+two are used for examining inputs for security purposes. Details on
+their usage is at <https://www.unicode.org/reports/tr39/>.
+.ie n .SS "It is now possible to write ""qr/\ep{Name=...}/"", or ""qr!\ep{na=/(SMILING|GRINNING) FACE/}!"""
+.el .SS "It is now possible to write \f(CWqr/\ep{Name=...}/\fP, or \f(CWqr!\ep{na=/(SMILING|GRINNING) FACE/}!\fP"
+.IX Subsection "It is now possible to write qr/p{Name=...}/, or qr!p{na=/(SMILING|GRINNING) FACE/}!"
+The Unicode Name property is now accessible in regular expression
+patterns, as an alternative to \f(CW\*(C`\eN{...}\*(C'\fR.
+A comparison of the two methods is given in
+"Comparison of \eN{...} and \ep{name=...}" in perlunicode.
+.PP
+The second example above shows that wildcard subpatterns are also usable
+in this property. See "Wildcards in Property Values" in perlunicode.
+.ie n .SS "Improvement of POSIX::mblen(), ""mbtowc"", and ""wctomb"""
+.el .SS "Improvement of \f(CWPOSIX::mblen()\fP, \f(CWmbtowc\fP, and \f(CWwctomb\fP"
+.IX Subsection "Improvement of POSIX::mblen(), mbtowc, and wctomb"
+The \f(CWPOSIX::mblen()\fR, \f(CW\*(C`mbtowc\*(C'\fR, and \f(CW\*(C`wctomb\*(C'\fR functions now
+work on shift state locales and are thread-safe on C99 and above
+compilers when executed on a platform that has locale thread-safety; the
+length parameters are now optional.
+.PP
+These functions are always executed under the current C language locale.
+(See perllocale.)  Most locales are stateless, but a few, notably the
+very rarely encountered ISO 2022, maintain a state between calls to
+these functions. Previously the state was cleared on every call, but
+now the state is not reset unless the appropriate parameter is \f(CW\*(C`undef\*(C'\fR.
+.PP
+On threaded perls, the C99 functions \fBmbrlen\fR\|(3), \fBmbrtowc\fR\|(3), and
+\&\fBwcrtomb\fR\|(3), when available, are substituted for the plain functions.
+This makes these functions thread-safe when executing on a locale
+thread-safe platform.
+.PP
+The string length parameters in \f(CW\*(C`mblen\*(C'\fR and \f(CW\*(C`mbtowc\*(C'\fR are now optional;
+useful only if you wish to restrict the length parsed in the source
+string to less than the actual length.
+.SS "Alpha assertions are no longer experimental"
+.IX Subsection "Alpha assertions are no longer experimental"
+See "(*pla:pattern)" in perlre, "(*plb:pattern)" in perlre,
+"(*nla:pattern)" in perlre>, and "(*nlb:pattern)" in perlre.
+Use of these no longer generates a warning; existing code that disables
+the warning category \f(CW\*(C`experimental::alpha_assertions\*(C'\fR will continue to work
+without any changes needed. Enabling the category has no effect.
+.SS "Script runs are no longer experimental"
+.IX Subsection "Script runs are no longer experimental"
+See "Script Runs" in perlre. Use of these no longer generates a warning;
+existing code that disables the warning category
+\&\f(CW\*(C`experimental::script_run\*(C'\fR will continue to work without any
+changes needed. Enabling the category has no effect.
+.SS "Feature checks are now faster"
+.IX Subsection "Feature checks are now faster"
+Previously feature checks in the parser required a hash lookup when
+features were set outside of a feature bundle, this has been optimized
+to a bit mask check. [GH #17229 <https://github.com/Perl/perl5/issues/17229>]
+.SS "Perl is now developed on GitHub"
+.IX Subsection "Perl is now developed on GitHub"
+Perl is now developed on GitHub. You can find us at
+<https://github.com/Perl/perl5>.
+.PP
+Non-security bugs should now be reported via GitHub. Security issues should
+continue to be reported as documented in perlsec.
+.SS "Compiled patterns can now be dumped before optimization"
+.IX Subsection "Compiled patterns can now be dumped before optimization"
+This is primarily useful for tracking down bugs in the regular
+expression compiler. This dump happens on \f(CW\*(C`\-DDEBUGGING\*(C'\fR perls, if you
+specify \f(CW\*(C`\-Drv\*(C'\fR on the command line; or on any perl if the pattern is
+compiled within the scope of \f(CW\*(C`use\ re\ qw(Debug\ DUMP_PRE_OPTIMIZE)\*(C'\fR or
+\&\f(CW\*(C`use\ re\ qw(Debug\ COMPILE\ EXTRA)\*(C'\fR. (All but the second case display
+other information as well.)
+.SH Security
+.IX Header "Security"
+.SS "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+A signed \f(CW\*(C`size_t\*(C'\fR integer overflow in the storage space calculations for
+nested regular expression quantifiers could cause a heap buffer overflow in
+Perl's regular expression compiler that overwrites memory allocated after the
+regular expression storage space with attacker supplied data.
+.PP
+The target system needs a sufficient amount of memory to allocate partial
+expansions of the nested quantifiers prior to the overflow occurring.  This
+requirement is unlikely to be met on 64\-bit systems.
+.PP
+Discovered by: ManhND of The Tarantula Team, VinCSS (a member of Vingroup).
+.SS "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IX Subsection "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+Integer overflows in the calculation of offsets between instructions for the
+regular expression engine could cause corruption of the intermediate language
+state of a compiled regular expression.  An attacker could abuse this behaviour
+to insert instructions into the compiled form of a Perl regular expression.
+.PP
+Discovered by: Hugo van der Sanden and Slaven Rezic.
+.SS "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression"
+.IX Subsection "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+Recursive calls to \f(CWS_study_chunk()\fR by Perl's regular expression compiler to
+optimize the intermediate language representation of a regular expression could
+cause corruption of the intermediate language state of a compiled regular
+expression.
+.PP
+Discovered by: Sergey Aleynikov.
+.SS "Additional Note"
+.IX Subsection "Additional Note"
+An application written in Perl would only be vulnerable to any of the above
+flaws if it evaluates regular expressions supplied by the attacker.  Evaluating
+regular expressions in this fashion is known to be dangerous since the regular
+expression engine does not protect against denial of service attacks in this
+usage scenario.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Certain pattern matching features are now prohibited in compiling Unicode property value wildcard subpatterns"
+.IX Subsection "Certain pattern matching features are now prohibited in compiling Unicode property value wildcard subpatterns"
+These few features are either inappropriate or interfere with the
+algorithm used to accomplish this task. The complete list is in
+"Wildcards in Property Values" in perlunicode.
+.ie n .SS "Unused functions ""POSIX::mbstowcs"" and ""POSIX::wcstombs"" are removed"
+.el .SS "Unused functions \f(CWPOSIX::mbstowcs\fP and \f(CWPOSIX::wcstombs\fP are removed"
+.IX Subsection "Unused functions POSIX::mbstowcs and POSIX::wcstombs are removed"
+These functions could never have worked due to a defective interface
+specification. There is clearly no demand for them, given that no one
+has ever complained in the many years the functions were claimed to be
+available, hence so-called "support" for them is now dropped.
+.ie n .SS "A bug fix for ""(?[...])"" may have caused some patterns to no longer compile"
+.el .SS "A bug fix for \f(CW(?[...])\fP may have caused some patterns to no longer compile"
+.IX Subsection "A bug fix for (?[...]) may have caused some patterns to no longer compile"
+See "Selected Bug Fixes". The heuristics previously used may have let
+some constructs compile (perhaps not with the programmer's intended
+effect) that should have been errors. None are known, but it is
+possible that some erroneous constructs no longer compile.
+.ie n .SS """\ep{\fIuser\-defined\fP}"" properties now always override official Unicode ones"
+.el .SS "\f(CW\ep{\fP\f(CIuser\-defined\fP\f(CW}\fP properties now always override official Unicode ones"
+.IX Subsection "p{user-defined} properties now always override official Unicode ones"
+Previously, if and only if a user-defined property was declared prior to
+the compilation of the regular expression pattern that contains it, its
+definition was used instead of any official Unicode property with the
+same name. Now, it always overrides the official property. This
+change could break existing code that relied (likely unwittingly) on the
+previous behavior. Without this fix, if Unicode released a new version
+with a new property that happens to have the same name as the one you
+had long been using, your program would break when you upgraded to a
+perl that used that new Unicode version. See "User-Defined
+Character Properties" in perlunicode. [GH #17205 <https://github.com/Perl/perl5/issues/17205>]
+.SS "Modifiable variables are no longer permitted in constants"
+.IX Subsection "Modifiable variables are no longer permitted in constants"
+Code like:
+.PP
+.Vb 2
+\&    my $var;
+\&    $sub = sub () { $var };
+.Ve
+.PP
+where \f(CW$var\fR is referenced elsewhere in some sort of modifiable context now
+produces an exception when the sub is defined.
+.PP
+This error can be avoided by adding a return to the sub definition:
+.PP
+.Vb 1
+\&    $sub = sub () { return $var };
+.Ve
+.PP
+This has been deprecated since Perl 5.22.
+[GH #17020] <https://github.com/Perl/perl5/issues/17020>
+.ie n .SS "Use of ""vec"" on strings with code points above 0xFF is forbidden"
+.el .SS "Use of \f(CWvec\fP on strings with code points above 0xFF is forbidden"
+.IX Subsection "Use of vec on strings with code points above 0xFF is forbidden"
+Such strings are represented internally in UTF\-8, and \f(CW\*(C`vec\*(C'\fR is a
+bit-oriented operation that will likely give unexpected results on those
+strings. This was deprecated in perl 5.28.0.
+.SS "Use of code points over 0xFF in string bitwise operators"
+.IX Subsection "Use of code points over 0xFF in string bitwise operators"
+Some uses of these were already illegal after a previous deprecation
+cycle. The remaining uses are now prohibited, having been deprecated in perl
+5.28.0. See perldeprecation.
+.ie n .SS "Sys::Hostname::hostname() does not accept arguments"
+.el .SS "\f(CWSys::Hostname::hostname()\fP does not accept arguments"
+.IX Subsection "Sys::Hostname::hostname() does not accept arguments"
+This usage was deprecated in perl 5.28.0 and is now fatal.
+.SS "Plain ""0"" string now treated as a number for range operator"
+.IX Subsection "Plain ""0"" string now treated as a number for range operator"
+Previously a range \f(CW"0" .. "\-1"\fR would produce a range of numeric
+strings from "0" through "99"; this now produces an empty list, just
+as \f(CW\*(C`0 .. \-1\*(C'\fR does. This also means that \f(CW"0" .. "9"\fR now produces a
+list of integers, where previously it would produce a list of strings.
+.PP
+This was due to a special case that treated strings starting with "0"
+as strings so ranges like \f(CW"00" .. "03"\fR produced \f(CW"00", "01", "02", "03"\fR,
+but didn't specially handle the string \f(CW"0"\fR.
+[GH #16770] <https://github.com/Perl/perl5/issues/16770>
+.ie n .SS """\eK"" now disallowed in look-ahead and look-behind assertions"
+.el .SS "\f(CW\eK\fP now disallowed in look-ahead and look-behind assertions"
+.IX Subsection "K now disallowed in look-ahead and look-behind assertions"
+This was disallowed because it causes unexpected behaviour, and no-one
+could define what the desired behaviour should be.
+[GH #14638] <https://github.com/Perl/perl5/issues/14638>
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+\&\f(CW\*(C`my_strnlen\*(C'\fR has been sped up for systems that don't have their own
+\&\f(CW\*(C`strnlen\*(C'\fR implementation.
+.IP \(bu 4
+\&\f(CW\*(C`grok_bin_oct_hex\*(C'\fR (and so, \f(CW\*(C`grok_bin\*(C'\fR, \f(CW\*(C`grok_oct\*(C'\fR, and \f(CW\*(C`grok_hex\*(C'\fR)
+have been sped up.
+.IP \(bu 4
+\&\f(CW\*(C`grok_number_flags\*(C'\fR has been sped up.
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR is now noticeably faster in cases such as \f(CW\*(C`sort {$a <=> $b}\*(C'\fR or
+\&\f(CW\*(C`sort {$b <=> $a}\*(C'\fR. [GH #17608 <https://github.com/Perl/perl5/pull/17608>]
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.32 to 2.36.
+.IP \(bu 4
+autodie has been upgraded from version 2.29 to 2.32.
+.IP \(bu 4
+B has been upgraded from version 1.76 to 1.80.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.49 to 1.54.
+.IP \(bu 4
+Benchmark has been upgraded from version 1.22 to 1.23.
+.IP \(bu 4
+charnames has been upgraded from version 1.45 to 1.48.
+.IP \(bu 4
+Class::Struct has been upgraded from version 0.65 to 0.66.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.084 to 2.093.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.084 to 2.093.
+.IP \(bu 4
+CPAN has been upgraded from version 2.22 to 2.27.
+.IP \(bu 4
+DB_File has been upgraded from version 1.843 to 1.853.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.52 to 3.57.
+.Sp
+The test files generated on Win32 are now identical to when they are
+generated on POSIX-like systems.
+.IP \(bu 4
+diagnostics has been upgraded from version 1.36 to 1.37.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.55 to 2.55_01.
+.IP \(bu 4
+Dumpvalue has been upgraded from version 1.18 to 1.21.
+.Sp
+Previously, when dumping elements of an array and encountering an undefined
+value, the string printed would have been \f(CW\*(C`empty array\*(C'\fR. This has been
+changed to what was apparently originally intended:  \f(CW\*(C`empty slot\*(C'\fR.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.45 to 1.47.
+.IP \(bu 4
+Encode has been upgraded from version 3.01 to 3.06.
+.IP \(bu 4
+encoding has been upgraded from version 2.22 to 3.00.
+.IP \(bu 4
+English has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+Exporter has been upgraded from version 5.73 to 5.74.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280231 to 0.280234.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.34 to 7.44.
+.IP \(bu 4
+feature has been upgraded from version 1.54 to 1.58.
+.Sp
+A new \f(CW\*(C`indirect\*(C'\fR feature has been added, which is enabled by default
+but allows turning off indirect object syntax.
+.IP \(bu 4
+File::Find has been upgraded from version 1.36 to 1.37.
+.Sp
+On Win32, the tests no longer require either a file in the drive root
+directory, or a writable root directory.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.32 to 1.33.
+.IP \(bu 4
+File::stat has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+Filter::Simple has been upgraded from version 0.95 to 0.96.
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.5 to 2.51.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.22 to 0.23.
+.Sp
+The Synopsis has been updated as the example code stopped working with
+newer perls.
+[GH #17399 <https://github.com/Perl/perl5/issues/17399>]
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.18 to 0.19.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.43 to 0.44.
+.Sp
+Document the \f(CW\*(C`IGNORE_WIN32_LOCALE\*(C'\fR environment variable.
+.IP \(bu 4
+IO has been upgraded from version 1.40 to 1.43.
+.Sp
+IO::Socket no longer caches a zero protocol value, since this
+indicates that the implementation will select a protocol. This means
+that on platforms that don't implement \f(CW\*(C`SO_PROTOCOL\*(C'\fR for a given
+socket type the protocol method may return \f(CW\*(C`undef\*(C'\fR.
+.Sp
+The supplied \fITO\fR is now always honoured on calls to the \f(CWsend()\fR
+method. [GH #16891] <https://github.com/Perl/perl5/issues/16891>
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.084 to 2.093.
+.IP \(bu 4
+IPC::Cmd has been upgraded from version 1.02 to 1.04.
+.IP \(bu 4
+IPC::Open3 has been upgraded from version 1.20 to 1.21.
+.IP \(bu 4
+JSON::PP has been upgraded from version 4.02 to 4.04.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999816 to 1.999818.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.5008 to 0.5009.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20190522 to 5.20200620.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded from version 0.68 to 0.70.
+.IP \(bu 4
+Module::Metadata has been upgraded from version 1.000036 to 1.000037.
+.IP \(bu 4
+mro has been upgraded from version 1.22 to 1.23.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.71 to 2.72.
+.IP \(bu 4
+Opcode has been upgraded from version 1.43 to 1.47.
+.IP \(bu 4
+open has been upgraded from version 1.11 to 1.12.
+.IP \(bu 4
+overload has been upgraded from version 1.30 to 1.31.
+.IP \(bu 4
+parent has been upgraded from version 0.237 to 0.238.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.20190126 to 5.20200523.
+.IP \(bu 4
+PerlIO has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.27 to 0.28.
+.IP \(bu 4
+PerlIO::via has been upgraded from version 0.17 to 0.18.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.24 to 1.25.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.35 to 3.40.
+.IP \(bu 4
+podlators has been upgraded from version 4.11 to 4.14.
+.IP \(bu 4
+POSIX has been upgraded from version 1.88 to 1.94.
+.IP \(bu 4
+re has been upgraded from version 0.37 to 0.40.
+.IP \(bu 4
+Safe has been upgraded from version 2.40 to 2.41.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.50 to 1.55.
+.IP \(bu 4
+SelfLoader has been upgraded from version 1.25 to 1.26.
+.IP \(bu 4
+Socket has been upgraded from version 2.027 to 2.029.
+.IP \(bu 4
+Storable has been upgraded from version 3.15 to 3.21.
+.Sp
+Use of \f(CWnote()\fR from Test::More is now optional in tests. This works
+around a circular dependency with Test::More when installing on very
+old perls from CPAN.
+.Sp
+Vstring magic strings over 2GB are now disallowed.
+.Sp
+Regular expressions objects weren't properly counted for object id
+purposes on retrieve. This would corrupt the resulting structure, or
+cause a runtime error in some cases. [GH #17037] <https://github.com/Perl/perl5/issues/17037>
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.22 to 1.23.
+.IP \(bu 4
+Sys::Syslog has been upgraded from version 0.35 to 0.36.
+.IP \(bu 4
+Term::ANSIColor has been upgraded from version 4.06 to 5.01.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302162 to 1.302175.
+.IP \(bu 4
+Thread has been upgraded from version 3.04 to 3.05.
+.IP \(bu 4
+Thread::Queue has been upgraded from version 3.13 to 3.14.
+.IP \(bu 4
+threads has been upgraded from version 2.22 to 2.25.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.60 to 1.61.
+.IP \(bu 4
+Tie::File has been upgraded from version 1.02 to 1.06.
+.IP \(bu 4
+Tie::Hash::NamedCapture has been upgraded from version 0.10 to 0.13.
+.IP \(bu 4
+Tie::Scalar has been upgraded from version 1.04 to 1.05.
+.IP \(bu 4
+Tie::StdHandle has been upgraded from version 4.5 to 4.6.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9760 to 1.9764.
+.Sp
+Removed obsolete code such as support for pre\-5.6 perl and classic
+MacOS. [GH #17096] <https://github.com/Perl/perl5/issues/17096>
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.33 to 1.3401.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.26 to 1.27.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.72 to 0.75.
+.IP \(bu 4
+VMS::Stdio has been upgraded from version 2.44 to 2.45.
+.IP \(bu 4
+warnings has been upgraded from version 1.44 to 1.47.
+.IP \(bu 4
+Win32 has been upgraded from version 0.52 to 0.53.
+.IP \(bu 4
+Win32API::File has been upgraded from version 0.1203 to 0.1203_01.
+.IP \(bu 4
+XS::APItest has been upgraded from version 1.00 to 1.09.
+.SS "Removed Modules and Pragmata"
+.IX Subsection "Removed Modules and Pragmata"
+.IP \(bu 4
+Pod::Parser has been removed from the core distribution.
+It still is available for download from CPAN. This resolves 
+[#13194 <https://github.com/Perl/perl5/issues/13194>].
+.SH Documentation
+.IX Header "Documentation"
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document. If you find any we have missed, open an issue
+at <https://github.com/Perl/perl5/issues>.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIperldebguts\fR
+.IX Subsection "perldebguts"
+.IP \(bu 4
+Simplify a few regnode definitions
+.Sp
+Update \f(CW\*(C`BOUND\*(C'\fR and \f(CW\*(C`NBOUND\*(C'\fR definitions.
+.IP \(bu 4
+Add ANYOFHs regnode
+.Sp
+This node is like \f(CW\*(C`ANYOFHb\*(C'\fR, but is used when more than one leading byte
+is the same in all the matched code points.
+.Sp
+\&\f(CW\*(C`ANYOFHb\*(C'\fR is used to avoid having to convert from UTF\-8 to code point for
+something that won't match. It checks that the first byte in the UTF\-8
+encoded target is the desired one, thus ruling out most of the possible
+code points.
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+\&\f(CW\*(C`sv_2pvbyte\*(C'\fR updated to mention it will croak if the SV cannot be
+downgraded.
+.IP \(bu 4
+\&\f(CW\*(C`sv_setpvn\*(C'\fR updated to mention that the UTF\-8 flag will not be changed by
+this function, and a terminating NUL byte is guaranteed.
+.IP \(bu 4
+Documentation for \f(CW\*(C`PL_phase\*(C'\fR has been added.
+.IP \(bu 4
+The documentation for \f(CW\*(C`grok_bin\*(C'\fR, \f(CW\*(C`grok_oct\*(C'\fR, and \f(CW\*(C`grok_hex\*(C'\fR has been
+updated and clarified.
+.PP
+\fIperldiag\fR
+.IX Subsection "perldiag"
+.IP \(bu 4
+Add documentation for experimental 'isa' operator
+.Sp
+(S experimental::isa) This warning is emitted if you use the (\f(CW\*(C`isa\*(C'\fR)
+operator. This operator is currently experimental and its behaviour may
+change in future releases of Perl.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.ie n .IP """caller""" 4
+.el .IP \f(CWcaller\fR 4
+.IX Item "caller"
+Like \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, the filename and
+line number returned here may be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.ie n .IP """_\|_FILE_\|_""" 4
+.el .IP \f(CW_\|_FILE_\|_\fR 4
+.IX Item "__FILE__"
+It can be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.ie n .IP """_\|_LINE_\|_""" 4
+.el .IP \f(CW_\|_LINE_\|_\fR 4
+.IX Item "__LINE__"
+It can be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.ie n .IP """return""" 4
+.el .IP \f(CWreturn\fR 4
+.IX Item "return"
+Now mentions that you cannot return from \f(CW\*(C`do BLOCK\*(C'\fR.
+.ie n .IP """open""" 4
+.el .IP \f(CWopen\fR 4
+.IX Item "open"
+The \f(CWopen()\fR section had been renovated significantly.
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+No longer suggesting using perl's \f(CW\*(C`malloc\*(C'\fR. Modern system \f(CW\*(C`malloc\*(C'\fR is
+assumed to be much better than perl's implementation now.
+.IP \(bu 4
+Documentation about \fIembed.fnc\fR flags has been removed. \fIembed.fnc\fR now has
+sufficient comments within it. Anyone changing that file will see those
+comments first, so entries here are now redundant.
+.IP \(bu 4
+Updated documentation for \f(CW\*(C`UTF8f\*(C'\fR
+.IP \(bu 4
+Added missing \f(CW\*(C`=for apidoc\*(C'\fR lines
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+The differences between Perl strings and C strings are now detailed.
+.PP
+\fIperlintro\fR
+.IX Subsection "perlintro"
+.IP \(bu 4
+The documentation for the repetition operator \f(CW\*(C`x\*(C'\fR have been clarified.
+[GH #17335 <https://github.com/Perl/perl5/issues/17335>]
+.PP
+\fIperlipc\fR
+.IX Subsection "perlipc"
+.IP \(bu 4
+The documentation surrounding \f(CW\*(C`open\*(C'\fR and handle usage has been modernized
+to prefer 3\-arg open and lexical variables instead of barewords.
+.IP \(bu 4
+Various updates and fixes including making all examples strict-safe and
+replacing \f(CW\*(C`\-w\*(C'\fR with \f(CW\*(C`use warnings\*(C'\fR.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+\&'isa' operator is experimental
+.Sp
+This is an experimental feature and is available when enabled
+by \f(CW\*(C`use feature \*(Aqisa\*(Aq\*(C'\fR. It emits a warning in the \f(CW\*(C`experimental::isa\*(C'\fR
+category.
+.PP
+\fIperlpod\fR
+.IX Subsection "perlpod"
+.IP \(bu 4
+Details of the various stacks within the perl interpreter are now explained
+here.
+.IP \(bu 4
+Advice has been added regarding the usage of \f(CW\*(C`Z<>\*(C'\fR.
+.PP
+\fIperlport\fR
+.IX Subsection "perlport"
+.IP \(bu 4
+Update \f(CW\*(C`timegm\*(C'\fR example to use the correct year format \fI1970\fR instead of \fI70\fR.
+[GH #16431 <https://github.com/Perl/perl5/issues/16431>]
+.PP
+\fIperlreref\fR
+.IX Subsection "perlreref"
+.IP \(bu 4
+Fix some typos.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+Now recommends stringifying \f(CW$]\fR and comparing it numerically.
+.PP
+\fIperlapi, perlintern\fR
+.IX Subsection "perlapi, perlintern"
+.IP \(bu 4
+Documentation has been added for several functions that were
+lacking it before.
+.PP
+\fIperlxs\fR
+.IX Subsection "perlxs"
+.IP \(bu 4
+Suggest using \f(CW\*(C`libffi\*(C'\fR for simple library bindings via CPAN modules
+like FFI::Platypus or FFI::Raw.
+.PP
+\fIPOSIX\fR
+.IX Subsection "POSIX"
+.IP \(bu 4
+\&\f(CW\*(C`setlocale\*(C'\fR warning about threaded builds updated to note it does not
+apply on Perl 5.28.X and later.
+.IP \(bu 4
+\&\f(CW\*(C`Posix::SigSet\->new(...)\*(C'\fR updated to state it throws an error if any of
+the supplied signals cannot be added to the set.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIUpdating of links\fR
+.IX Subsection "Updating of links"
+.IP \(bu 4
+Links to the now defunct <https://search.cpan.org> site now point at
+the equivalent <https://metacpan.org> URL. [GH #17393 <https://github.com/Perl/perl5/issues/17393>]
+.IP \(bu 4
+The man page for ExtUtils::XSSymSet is now only installed on VMS,
+which is the only platform the module is installed on. [GH #17424 <https://github.com/Perl/perl5/issues/17424>]
+.IP \(bu 4
+URLs have been changed to \f(CW\*(C`https://\*(C'\fR and stale links have been updated.
+.Sp
+Where applicable, the URLs in the documentation have been moved from using the
+\&\f(CW\*(C`http://\*(C'\fR protocol to \f(CW\*(C`https://\*(C'\fR. This also affects the location of the bug
+tracker at <https://rt.perl.org>.
+.IP \(bu 4
+Some links to OS/2 libraries, Address Sanitizer and other system tools had gone
+stale. These have been updated with working links.
+.IP \(bu 4
+Some links to old email addresses on perl5\-porters had gone stale. These have been
+updated with working links.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages. For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Expecting interpolated extended charclass in regex; marked by <\-\- HERE in m/%s/
+.Sp
+This is a replacement for several error messages listed under
+"Changes to Existing Diagnostics".
+.IP \(bu 4
+\&\f(CW\*(C`No digits found for %s literal\*(C'\fR
+.Sp
+(F) No hexadecimal digits were found following \f(CW\*(C`0x\*(C'\fR or no binary digits were
+found following \f(CW\*(C`0b\*(C'\fR.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Code point 0x%X is not Unicode, and not portable
+.Sp
+This is actually not a new message, but it is now output when the
+warnings category \f(CW\*(C`portable\*(C'\fR is enabled.
+.Sp
+When raised during regular expression pattern compilation, the warning
+has extra text added at the end marking where precisely in the pattern
+it occurred.
+.IP \(bu 4
+Non-hex character '%c' terminates \ex early.  Resolved as "%s"
+.Sp
+This replaces a warning that was much less specific, and which gave
+false information. This new warning parallels the similar
+already-existing one raised for \f(CW\*(C`\eo{}\*(C'\fR.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Character following "\ec" must be printable ASCII
+.Sp
+\&...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+.IP \(bu 4
+Use "%s" instead of "%s"
+.Sp
+\&...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+.IP \(bu 4
+Sequence "\ec{" invalid
+.Sp
+\&...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+.IP \(bu 4
+"\ec%c" is more clearly written simply as "%s"
+.Sp
+\&...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+.IP \(bu 4
+Non-octal character '%c' terminates \eo early.  Resolved as "%s"
+.Sp
+\&...now includes the phrase "terminates \eo early", and has extra text added
+at the end, when raised during regular expression pattern compilation,
+marking where precisely in the pattern it occurred. In some instances
+the text of the resolution has been clarified.
+.IP \(bu 4
+\&'%s' resolved to '\eo{%s}%d'
+.Sp
+As of Perl 5.32, this message is no longer generated. Instead,
+"Non-octal character '%c' terminates \eo early.  Resolved as "%s"" in perldiag
+is used instead.
+.IP \(bu 4
+Use of code point 0x%s is not allowed; the permissible max is 0x%X
+.Sp
+Some instances of this message previously output the hex digits \f(CW\*(C`A\*(C'\fR,
+\&\f(CW\*(C`B\*(C'\fR, \f(CW\*(C`C\*(C'\fR, \f(CW\*(C`D\*(C'\fR, \f(CW\*(C`E\*(C'\fR, and \f(CW\*(C`F\*(C'\fR in lower case. Now they are all
+consistently upper case.
+.IP \(bu 4
+The following three diagnostics have been removed, and replaced by
+\&\f(CW\*(C`Expecting interpolated extended charclass in regex; marked by <\-\- HERE in m/%s/\*(C'\fR
+:
+\&\f(CW\*(C`Expecting close paren for nested extended charclass in regex; marked
+by <\-\- HERE in m/%s/\*(C'\fR,
+\&\f(CW\*(C`Expecting close paren for wrapper for nested extended charclass in
+regex; marked by <\-\- HERE in m/%s/\*(C'\fR,
+and
+\&\f(CW\*(C`Expecting \*(Aq(?flags:(?[...\*(Aq in regex; marked by <\-\-\ HERE in m/%s/\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`Code point 0x%X is not Unicode, and not portable\*(C'\fR warning removed
+the line \f(CW\*(C`Code points above 0xFFFF_FFFF require larger than a 32 bit word.\*(C'\fR
+as code points that large are no longer legal on 32\-bit platforms.
+.IP \(bu 4
+Can't use global \f(CW%s\fR in \f(CW%s\fR
+.Sp
+This error message has been slightly reformatted from the original \f(CW\*(C`Can\*(Aqt use
+global %s in "%s"\*(C'\fR, and in particular misleading error messages like \f(CW\*(C`Can\*(Aqt
+use global $_ in "my"\*(C'\fR are now rendered as \f(CW\*(C`Can\*(Aqt use global $_ in subroutine
+signature\*(C'\fR.
+.IP \(bu 4
+Constants from lexical variables potentially modified elsewhere are no longer permitted
+.Sp
+This error message replaces the former \f(CWConstants from lexical variables
+potentially modified elsewhere are deprecated. This will not be allowed in Perl
+5.32\fR to reflect the fact that this previously deprecated usage has now been
+transformed into an exception. The message's classification has also been
+updated from D (deprecated) to F (fatal).
+.Sp
+See also "Incompatible Changes".
+.IP \(bu 4
+\&\f(CW\*(C`\eN{} here is restricted to one character\*(C'\fR is now emitted in the same
+circumstances where previously \f(CW\*(C`\eN{} in inverted character class or as a range
+end\-point is restricted to one character\*(C'\fR was.
+.Sp
+This is due to new circumstances having been added in Perl 5.30 that weren't
+covered by the earlier wording.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS perlbug
+.IX Subsection "perlbug"
+.IP \(bu 4
+The bug tracker homepage URL now points to GitHub.
+.SS streamzip
+.IX Subsection "streamzip"
+.IP \(bu 4
+This is a new utility, included as part of an
+IO::Compress::Base upgrade.
+.Sp
+streamzip creates a zip file from stdin. The program will read data
+from stdin, compress it into a zip container and, by default, write a
+streamed zip file to stdout.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.SS \fIConfigure\fP
+.IX Subsection "Configure"
+.IP \(bu 4
+For clang++, add \f(CW\*(C`#include <stdlib.h>\*(C'\fR to Configure's probes for
+\&\f(CW\*(C`futimes\*(C'\fR, \f(CW\*(C`strtoll\*(C'\fR, \f(CW\*(C`strtoul\*(C'\fR, \f(CW\*(C`strtoull\*(C'\fR, \f(CW\*(C`strtouq\*(C'\fR, otherwise the
+probes would fail to compile.
+.IP \(bu 4
+Use a compile and run test for \f(CW\*(C`lchown\*(C'\fR to satisfy clang++ which should
+more reliably detect it.
+.IP \(bu 4
+For C++ compilers, add \f(CW\*(C`#include <stdio.h>\*(C'\fR to Configure's probes for
+\&\f(CW\*(C`getpgrp\*(C'\fR and \f(CW\*(C`setpgrp\*(C'\fR as they use printf and C++ compilers may fail
+compilation instead of just warning.
+.IP \(bu 4
+Check if the compiler can handle inline attribute.
+.IP \(bu 4
+Check for character data alignment.
+.IP \(bu 4
+\&\fIConfigure\fR now correctly handles gcc\-10. Previously it was interpreting it
+as gcc\-1 and turned on \f(CW\*(C`\-fpcc\-struct\-return\*(C'\fR.
+.IP \(bu 4
+Perl now no longer probes for \f(CW\*(C`d_u32align\*(C'\fR, defaulting to \f(CW\*(C`define\*(C'\fR on all
+platforms. This check was error-prone when it was done, which was on 32\-bit
+platforms only.
+[GH #16680] <https://github.com/Perl/perl5/issues/16680>
+.IP \(bu 4
+Documentation and hints for building perl on Z/OS (native EBCDIC) have been
+updated. This is still a work in progress.
+.IP \(bu 4
+A new probe for \f(CW\*(C`malloc_usable_size\*(C'\fR has been added.
+.IP \(bu 4
+Improvements in \fIConfigure\fR to detection in C++ and clang++. Work ongoing by
+Andy Dougherty. [GH #17033] <https://github.com/Perl/perl5/issues/17033>
+.IP \(bu 4
+\&\fIautodoc.pl\fR
+.Sp
+This tool that regenerates perlintern and perlapi has been overhauled
+significantly, restoring consistency in flags used in \fIembed.fnc\fR and
+Devel::PPPort and allowing removal of many redundant \f(CW\*(C`=for apidoc\*(C'\fR
+entries in code.
+.IP \(bu 4
+The \f(CW\*(C`ECHO\*(C'\fR macro is now defined. This is used in a \f(CW\*(C`dtrace\*(C'\fR rule that was
+originally changed for FreeBSD, and the FreeBSD make apparently predefines it.
+The Solaris make does not predefine \f(CW\*(C`ECHO\*(C'\fR which broke this rule on Solaris.
+[GH #17057] <https://github.com/Perl/perl5/issues/17057>
+.IP \(bu 4
+Bison versions 3.1 through 3.4 are now supported.
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and
+changes in this release. Furthermore, these significant changes were
+made:
+.IP \(bu 4
+\&\fIt/run/switches.t\fR no longer uses (and re-uses) the \fItmpinplace/\fR
+directory under \fIt/\fR. This may prevent spurious failures. [GH #17424 <https://github.com/Perl/perl5/issues/17424>]
+.IP \(bu 4
+Various bugs in \f(CW\*(C`POSIX::mbtowc\*(C'\fR were fixed. Potential races with
+other threads are now avoided, and previously the returned wide
+character could well be garbage.
+.IP \(bu 4
+Various bugs in \f(CW\*(C`POSIX::wctomb\*(C'\fR were fixed. Potential races with other
+threads are now avoided, and previously it would segfault if the string
+parameter was shared or hadn't been pre-allocated with a string of
+sufficient length to hold the result.
+.IP \(bu 4
+Certain test output of scalars containing control characters and Unicode
+has been fixed on EBCDIC.
+.IP \(bu 4
+\&\fIt/charset_tools.pl\fR: Avoid some work on ASCII platforms.
+.IP \(bu 4
+\&\fIt/re/regexp.t\fR: Speed up many regex tests on ASCII platform
+.IP \(bu 4
+\&\fIt/re/pat.t\fR: Skip tests that don't work on EBCDIC.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP "Windows CE" 4
+.IX Item "Windows CE"
+Support for building perl on Windows CE has now been removed.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Linux 4
+.IX Item "Linux"
+\&\f(CW\*(C`cc\*(C'\fR will be used to populate \f(CW\*(C`plibpth\*(C'\fR if \f(CW\*(C`cc\*(C'\fR is \f(CW\*(C`clang\*(C'\fR.
+[GH #17043] <https://github.com/Perl/perl5/issues/17043>
+.IP "NetBSD 8.0" 4
+.IX Item "NetBSD 8.0"
+Fix compilation of Perl on NetBSD 8.0 with g++.
+[GH #17381 <https://github.com/Perl/perl5/issues/17381>]
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+The configuration for \f(CW\*(C`ccflags\*(C'\fR and \f(CW\*(C`optimize\*(C'\fR are now separate, as
+with POSIX platforms. [GH #17156 <https://github.com/Perl/perl5/issues/17156>]
+.IP \(bu 4
+Support for building perl with Visual C++ 6.0 has now been removed.
+.IP \(bu 4
+The locale tests could crash on Win32 due to a Windows bug, and
+separately due to the CRT throwing an exception if the locale name
+wasn't validly encoded in the current code page.
+.Sp
+For the second we now decode the locale name ourselves, and always
+decode it as UTF\-8. [GH #16922] <https://github.com/Perl/perl5/issues/16922>
+.IP \(bu 4
+\&\fIt/op/magic.t\fR could fail if environment variables starting with
+\&\f(CW\*(C`FOO\*(C'\fR already existed.
+.IP \(bu 4
+MYMALLOC (PERL_MALLOC) build has been fixed.
+.RE
+.RS 4
+.RE
+.IP Solaris 4
+.IX Item "Solaris"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+\&\f(CW\*(C`Configure\*(C'\fR will now find recent versions of the Oracle Developer Studio
+compiler, which are found under \f(CW\*(C`/opt/developerstudio*\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Configure\*(C'\fR now uses the detected types for \f(CW\*(C`gethostby*\*(C'\fR functions, allowing
+Perl to once again compile on certain configurations of Solaris.
+.RE
+.RS 4
+.RE
+.IP VMS 4
+.IX Item "VMS"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+With the release of the patch kit C99 V2.0, VSI has provided support for a
+number of previously-missing C99 features. On systems with that patch kit
+installed, Perl's configuration process will now detect the presence of the
+header \f(CW\*(C`stdint.h\*(C'\fR and the following functions: \f(CW\*(C`fpclassify\*(C'\fR, \f(CW\*(C`isblank\*(C'\fR, \f(CW\*(C`isless\*(C'\fR,
+\&\f(CW\*(C`llrint\*(C'\fR, \f(CW\*(C`llrintl\*(C'\fR, \f(CW\*(C`llround\*(C'\fR, \f(CW\*(C`llroundl\*(C'\fR, \f(CW\*(C`nearbyint\*(C'\fR, \f(CW\*(C`round\*(C'\fR, \f(CW\*(C`scalbn\*(C'\fR,
+and \f(CW\*(C`scalbnl\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`\-Duse64bitint\*(C'\fR is now the default on VMS.
+.RE
+.RS 4
+.RE
+.IP z/OS 4
+.IX Item "z/OS"
+Perl 5.32 has been tested on z/OS 2.4, with the following caveats:
+.RS 4
+.IP \(bu 4
+Only static builds (the default) build reliably
+.IP \(bu 4
+When using locales, z/OS does not handle the \f(CW\*(C`LC_MESSAGES\*(C'\fR category
+properly, so when compiling perl, you should add the following to your
+\&\fIConfigure\fR options
+.Sp
+.Vb 1
+\& ./Configure <other options> \-Accflags=\-DNO_LOCALE_MESSAGES
+.Ve
+.IP \(bu 4
+z/OS does not support locales with threads, so when compiling a threaded
+perl, you should add the following to your \fIConfigure\fR options
+.Sp
+.Vb 1
+\& ./Configure <other Configure options> \-Accflags=\-DNO_LOCALE
+.Ve
+.IP \(bu 4
+Some CPAN modules that are shipped with perl fail at least one of their
+self-tests.  These are:
+Archive::Tar,
+Config::Perl::V,
+CPAN::Meta,
+CPAN::Meta::YAML,
+Digest::MD5,
+Digest::SHA,
+Encode,
+ExtUtils::MakeMaker,
+ExtUtils::Manifest,
+HTTP::Tiny,
+IO::Compress,
+IPC::Cmd,
+JSON::PP,
+libnet,
+MIME::Base64,
+Module::Metadata,
+PerlIO::via\-QuotedPrint,
+Pod::Checker,
+podlators,
+Pod::Simple,
+Socket,
+and Test::Harness.
+.Sp
+The causes of the failures range from the self-test itself is flawed,
+and the module actually works fine, up to the module doesn't work at all
+on EBCDIC platforms.
+.RE
+.RS 4
+.RE
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+\&\f(CW\*(C`savepvn\*(C'\fR's len parameter is now a \f(CW\*(C`Size_t\*(C'\fR instead of an \f(CW\*(C`I32\*(C'\fR since we
+can handle longer strings than 31 bits.
+.IP \(bu 4
+The lexer (\f(CWPerl_yylex()\fR in \fItoke.c\fR) was previously a single 4100\-line
+function, relying heavily on \f(CW\*(C`goto\*(C'\fR and a lot of widely-scoped local variables
+to do its work. It has now been pulled apart into a few dozen smaller static
+functions; the largest remaining chunk (\f(CWyyl_word_or_keyword()\fR) is a little
+over 900 lines, and consists of a single \f(CW\*(C`switch\*(C'\fR statement, all of whose
+\&\f(CW\*(C`case\*(C'\fR groups are independent. This should be much easier to understand and
+maintain.
+.IP \(bu 4
+The OS-level signal handlers and type (Sighandler_t) used by the perl core
+were declared as having three parameters, but the OS was always told to
+call them with one argument. This has been fixed by declaring them to have
+one parameter. See the merge commit \f(CW\*(C`v5.31.5\-346\-g116e19abbf\*(C'\fR for full
+details.
+.IP \(bu 4
+The code that handles \f(CW\*(C`tr///\*(C'\fR has been extensively revised, fixing
+various bugs, especially when the source and/or replacement strings
+contain characters whose code points are above 255. Some of the bugs
+were undocumented, one being that under some circumstances (but not all)
+with \f(CW\*(C`/s\*(C'\fR, the squeezing was done based on the source, rather than the
+replacement. A documented bug that got fixed was
+[GH #14777] <https://github.com/Perl/perl5/issues/14777>.
+.IP \(bu 4
+A new macro for XS writers dealing with UTF\-8\-encoded Unicode strings
+has been created "\f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR" in perlapi that is safer in the face
+of malformed UTF\-8 input than "\f(CW\*(C`UTF8_SKIP\*(C'\fR" in perlapi (but not as safe
+as "\f(CW\*(C`UTF8_SAFE_SKIP\*(C'\fR" in perlapi). It won't read past a NUL character.
+It has been backported in Devel::PPPort 3.55 and later.
+.IP \(bu 4
+Added the \f(CW\*(C`PL_curstackinfo\->si_cxsubix\*(C'\fR field. This records the stack index
+of the most recently pushed sub/format/eval context. It is set and restored
+automatically by \f(CWcx_pushsub()\fR, \f(CWcx_popsub()\fR etc., but would need to be
+manually managed if you do any unusual manipulation of the context stack.
+.IP \(bu 4
+Various macros dealing with character type classification and changing case
+where the input is encoded in UTF\-8 now require an extra parameter to prevent
+potential reads beyond the end of the buffer. Use of these has generated a
+deprecation warning since Perl 5.26. Details are in
+"In XS code, use of various macros dealing with UTF\-8." in perldeprecation
+.IP \(bu 4
+A new parser function \fBparse_subsignature()\fR
+allows a keyword plugin to parse a subroutine signature while \f(CWuse feature
+\&\*(Aqsignatures\*(Aq\fR is in effect. This allows custom keywords to implement
+semantics similar to regular \f(CW\*(C`sub\*(C'\fR declarations that include signatures.
+[GH #16261] <https://github.com/Perl/perl5/issues/16261>
+.IP \(bu 4
+Since on some platforms we need to hold a mutex when temporarily
+switching locales, new macros (\f(CW\*(C`STORE_LC_NUMERIC_SET_TO_NEEDED_IN\*(C'\fR,
+\&\f(CW\*(C`WITH_LC_NUMERIC_SET_TO_NEEDED\*(C'\fR and \f(CW\*(C`WITH_LC_NUMERIC_SET_TO_NEEDED_IN\*(C'\fR)
+have been added to make it easier to do this safely and efficiently
+as part of [GH #17034] <https://github.com/Perl/perl5/issues/17034>.
+.IP \(bu 4
+The memory bookkeeping overhead for allocating an OP structure has been
+reduced by 8 bytes per OP on 64\-bit systems.
+.IP \(bu 4
+\&\fBeval_pv()\fR no longer stringifies the exception when
+\&\f(CW\*(C`[GH #17035]|https://github.com/Perl/perl5/issues/17035\*(C'\fR]
+.IP \(bu 4
+The PERL_DESTRUCT_LEVEL environment variable was formerly only honoured on perl
+binaries built with DEBUGGING support. It is now checked on all perl builds.
+Its normal use is to force perl to individually free every block of memory
+which it has allocated before exiting, which is useful when using automated
+leak detection tools such as valgrind.
+.IP \(bu 4
+The API \fBeval_sv()\fR now accepts a \f(CW\*(C`G_RETHROW\*(C'\fR flag. If this flag is set and an
+exception is thrown while compiling or executing the supplied code, it will be
+rethrown, and \fBeval_sv()\fR will not return.
+[GH #17036] <https://github.com/Perl/perl5/issues/17036>
+.IP \(bu 4
+As part of the fix for
+[GH #1537] <https://github.com/Perl/perl5/issues/1537> \fBperl_parse()\fR
+now returns non-zero if \fBexit\fR\|(0) is called in a \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR or
+\&\f(CW\*(C`CHECK\*(C'\fR block.
+.IP \(bu 4
+Most functions which recursively walked an op tree during compilation have been
+made non-recursive. This avoids SEGVs from stack overflow when the op tree is
+deeply nested, such as \f(CW\*(C`$n == 1 ? "one" : $n == 2 ? "two" : ....\*(C'\fR (especially
+in code which is auto-generated).
+.Sp
+This is particularly noticeable where the code is compiled within a separate
+thread, as threads tend to have small stacks by default.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Previously "require" in perlfunc would only treat the special built-in
+SV \f(CW&PL_sv_undef\fR as a value in \f(CW%INC\fR as if a previous \f(CW\*(C`require\*(C'\fR
+has failed, treating other undefined SVs as if the previous \f(CW\*(C`require\*(C'\fR
+has succeeded. This could cause unexpected success from \f(CW\*(C`require\*(C'\fR
+e.g., on \f(CW\*(C`local %INC = %INC;\*(C'\fR. This has been fixed. [GH #17428 <https://github.com/Perl/perl5/issues/17428>]
+.IP \(bu 4
+\&\f(CW\*(C`(?{...})\*(C'\fR eval groups in regular expressions no longer unintentionally
+trigger "EVAL without pos change exceeded limit in regex" [GH #17490 <https://github.com/Perl/perl5/issues/17490>].
+.IP \(bu 4
+\&\f(CW\*(C`(?[...])\*(C'\fR extended bracketed character classes do not wrongly raise an
+error on some cases where a previously-compiled such class is
+interpolated into another. The heuristics previously used have been
+replaced by a reliable method, and hence the diagnostics generated have
+changed. See "Diagnostics".
+.IP \(bu 4
+The debug display (say by specifying \f(CW\*(C`\-Dr\*(C'\fR or \f(CW\*(C`use\ re\*(C'\fR (with
+appropriate options) of compiled Unicode property wildcard subpatterns no
+longer has extraneous output.
+.IP \(bu 4
+Fix an assertion failure in the regular expression engine.
+[GH #17372 <https://github.com/Perl/perl5/issues/17372>]
+.IP \(bu 4
+Fix coredump in pp_hot.c after \f(CWB::UNOP_AUX::aux_list()\fR.
+[GH #17301 <https://github.com/Perl/perl5/issues/17301>]
+.IP \(bu 4
+Loading IO is now threadsafe.
+[GH #14816 <https://github.com/Perl/perl5/issues/14816>]
+.IP \(bu 4
+\&\f(CW\*(C`\ep{user\-defined}\*(C'\fR overrides official Unicode [GH #17025 <https://github.com/Perl/perl5/issues/17025>]
+.Sp
+Prior to this patch, the override was only sometimes in effect.
+.IP \(bu 4
+Properly handle filled \f(CW\*(C`/il\*(C'\fR regnodes and multi-char folds
+.IP \(bu 4
+Compilation error during make minitest [GH #17293 <https://github.com/Perl/perl5/issues/17293>]
+.IP \(bu 4
+Move the implementation of \f(CW\*(C`%\-\*(C'\fR, \f(CW\*(C`%+\*(C'\fR into core.
+.IP \(bu 4
+Read beyond buffer in \f(CW\*(C`grok_inf_nan\*(C'\fR [GH #17370 <https://github.com/Perl/perl5/issues/17370>]
+.IP \(bu 4
+Workaround glibc bug with \f(CW\*(C`LC_MESSAGES\*(C'\fR [GH #17081 <https://github.com/Perl/perl5/issues/17081>]
+.IP \(bu 4
+\&\f(CWprintf()\fR or \f(CWsprintf()\fR with the \f(CW%n\fR format could cause a panic on
+debugging builds, or report an incorrectly cached length value when
+producing \f(CW\*(C`SVfUTF8\*(C'\fR flagged strings. [GH #17221 <https://github.com/Perl/perl5/issues/17221>]
+.IP \(bu 4
+The tokenizer has been extensively refactored.
+[GH #17241 <https://github.com/Perl/perl5/issues/17241>]
+[GH #17189 <https://github.com/Perl/perl5/issues/17189>]
+.IP \(bu 4
+\&\f(CW\*(C`use strict "subs"\*(C'\fR is now enforced for bareword constants optimized
+into a \f(CW\*(C`multiconcat\*(C'\fR operator. [GH #17254 <https://github.com/Perl/perl5/issues/17254>]
+.IP \(bu 4
+A memory leak in regular expression patterns has been fixed. [GH #17218 <https://github.com/Perl/perl5/issues/17218>]
+.IP \(bu 4
+Perl no longer treats strings starting with "0x" or "0b" as hex or
+binary numbers respectively when converting a string to a number.
+This reverts a change in behaviour inadvertently introduced in perl
+5.30.0 intended to improve precision when converting a string to a
+floating point number. [GH #17062] <https://github.com/Perl/perl5/issues/17062>
+.IP \(bu 4
+Matching a non\-\f(CW\*(C`SVf_UTF8\*(C'\fR string against a regular expression
+containing unicode literals could leak a SV on each match attempt.
+[GH #17140] <https://github.com/Perl/perl5/issues/17140>
+.IP \(bu 4
+Overloads for octal and binary floating point literals were always
+passed a string with a \f(CW\*(C`0x\*(C'\fR prefix instead of the appropriate \f(CW0\fR or
+\&\f(CW\*(C`[GH #14791]|https://github.com/Perl/perl5/issues/14791\*(C'\fR]
+.IP \(bu 4
+\&\f(CW\*(C`$@ = 100; die;\*(C'\fR now correctly propagates the 100 as an exception
+instead of ignoring it. [GH #17098] <https://github.com/Perl/perl5/issues/17098>
+.IP \(bu 4
+\&\f(CW\*(C`[GH #17108]|https://github.com/Perl/perl5/issues/17108\*(C'\fR]
+.IP \(bu 4
+Exceptions thrown while \f(CW$@\fR is read-only could result in infinite
+recursion as perl tried to update \f(CW$@\fR, which throws another
+exception, resulting in a stack overflow. Perl now replaces \f(CW$@\fR
+with a copy if it's not a simple writable SV. [GH #17083] <https://github.com/Perl/perl5/issues/17083>
+.IP \(bu 4
+Setting \f(CW$)\fR now properly sets supplementary group ids if you have
+the necessary privileges. [GH #17031] <https://github.com/Perl/perl5/issues/17031>
+.IP \(bu 4
+\&\fBclose()\fR on a pipe now preemptively clears the PerlIO object from the
+IO SV. This prevents a second attempt to close the already closed
+PerlIO object if a signal handler calls \fBdie()\fR or \fBexit()\fR while \fBclose()\fR
+is waiting for the child process to complete. [GH #13929] <https://github.com/Perl/perl5/issues/13929>
+.IP \(bu 4
+\&\f(CW\*(C`sprintf("%.*a", \-10000, $x)\*(C'\fR would cause a buffer overflow due
+to mishandling of the negative precision value. [GH #16942] <https://github.com/Perl/perl5/issues/16942>
+.IP \(bu 4
+\&\fBscalar()\fR on a reference could cause an erroneous assertion failure
+during compilation. [GH #16969] <https://github.com/Perl/perl5/issues/16969>
+.IP \(bu 4
+\&\f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR is now an alias to \f(CW\*(C`%\-\*(C'\fR as documented, rather than
+incorrectly an alias for \f(CW\*(C`[GH #16105]|https://github.com/Perl/perl5/issues/16105\*(C'\fR]
+.IP \(bu 4
+\&\f(CW\*(C`%{^CAPTURE}\*(C'\fR didn't work if \f(CW\*(C`@{^CAPTURE}\*(C'\fR was mentioned first.
+Similarly for \f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR and \f(CW\*(C`@{^CAPTURE_ALL}\*(C'\fR, though
+\&\f(CW\*(C`[GH #17045]|https://github.com/Perl/perl5/issues/17045\*(C'\fR]
+.IP \(bu 4
+Extraordinarily large (over 2GB) floating point format widths could
+cause an integer overflow in the underlying call to \fBsnprintf()\fR,
+resulting in an assertion. Formatted floating point widths are now
+limited to the range of int, the return value of \fBsnprintf()\fR. 
+[#16881 <https://github.com/Perl/perl5/issues/16881>]
+.IP \(bu 4
+Parsing the following constructs within a sub-parse (such as with
+\&\f(CW"${code here}"\fR or \f(CW\*(C`s/.../code here/e\*(C'\fR) has changed to match how
+they're parsed normally:
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`print $fh ...\*(C'\fR no longer produces a syntax error.
+.IP \(bu 4
+Code like \f(CW\*(C`s/.../ ${time} /e\*(C'\fR now properly produces an "Ambiguous use
+of ${time} resolved to \f(CW$time\fR at ..." warning when warnings are enabled.
+.IP \(bu 4
+\&\f(CW\*(C`@x {"a"}\*(C'\fR (with the space) in a sub-parse now properly produces a
+"better written as" warning when warnings are enabled.
+.IP \(bu 4
+Attributes can now be used in a sub-parse.
+[GH #16847] <https://github.com/Perl/perl5/issues/16847>
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Incomplete hex and binary literals like \f(CW\*(C`0x\*(C'\fR and \f(CW\*(C`0b\*(C'\fR are now
+treated as if the \f(CW\*(C`x\*(C'\fR or \f(CW\*(C`b\*(C'\fR is part of the next token. 
+[#17010 <https://github.com/Perl/perl5/issues/17010>]
+.IP \(bu 4
+A spurious \f(CW\*(C`)\*(C'\fR in a subparse, such as in \f(CW\*(C`s/.../code here/e\*(C'\fR or
+\&\f(CW"...${code here}"\fR, no longer confuses the parser.
+.Sp
+Previously a subparse was bracketed with generated \f(CW\*(C`(\*(C'\fR and \f(CW\*(C`)\*(C'\fR
+tokens, so a spurious \f(CW\*(C`)\*(C'\fR would close the construct without doing the
+normal subparse clean up, confusing the parser and possible causing an
+assertion failure.
+.Sp
+Such constructs are now surrounded by artificial tokens that can't be
+included in the source. [GH #15814] <https://github.com/Perl/perl5/issues/15814>
+.IP \(bu 4
+Reference assignment of a sub, such as \f(CW\*(C`\e&foo = \e&bar;\*(C'\fR, silently did
+nothing in the \f(CW\*(C`[GH #16987]|https://github.com/Perl/perl5/issues/16987\*(C'\fR]
+.IP \(bu 4
+\&\fBsv_gets()\fR now recovers better if the target SV is modified by a signal
+handler. [GH #16960] <https://github.com/Perl/perl5/issues/16960>
+.IP \(bu 4
+\&\f(CW\*(C`readline @foo\*(C'\fR now evaluates \f(CW@foo\fR in scalar context. Previously
+it would be evaluated in list context, and since \fBreadline()\fR pops only
+one argument from the stack, the stack could underflow, or be left
+with unexpected values on the stack. [GH #16929] <https://github.com/Perl/perl5/issues/16929>
+.IP \(bu 4
+Parsing incomplete hex or binary literals was changed in 5.31.1 to treat such a
+literal as just the 0, leaving the following \f(CW\*(C`x\*(C'\fR or \f(CW\*(C`b\*(C'\fR to be parsed as part
+of the next token. This could lead to some silent changes in behaviour, so now
+incomplete hex or binary literals produce a fatal error.
+[GH #17010] <https://github.com/Perl/perl5/issues/17010>
+.IP \(bu 4
+\&\fBeval_pv()\fR's \fIcroak_on_error\fR flag will now throw even if the exception is a
+false overloaded value.
+[GH #17036] <https://github.com/Perl/perl5/issues/17036>
+.IP \(bu 4
+\&\f(CW\*(C`INIT\*(C'\fR blocks and the program itself are no longer run if \fBexit\fR\|(0) is called
+within a \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR or \f(CW\*(C`CHECK\*(C'\fR block.
+[GH #1537] <https://github.com/Perl/perl5/issues/1537>
+.IP \(bu 4
+\&\f(CW\*(C`open my $fh, ">>+", undef\*(C'\fR now opens the temporary file in append mode:
+writes will seek to the end of file before writing.
+[GH #17058] <https://github.com/Perl/perl5/issues/17058>
+.IP \(bu 4
+Fixed a SEGV when searching for the source of an uninitialized value warning on
+an op whose subtree includes an OP_MULTIDEREF.
+[GH #17088] <https://github.com/Perl/perl5/issues/17088>
+.SH Obituary
+.IX Header "Obituary"
+Jeff Goff (JGOFF or DrForr), an integral part of the Perl and Raku
+communities and a dear friend to all of us, has passed away on March
+13th, 2020. DrForr was a prominent member of the communities, attending
+and speaking at countless events, contributing to numerous projects,
+and assisting and helping in any way he could.
+.PP
+His passing leaves a hole in our hearts and in our communities and he
+will be sorely missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.32.0 represents approximately 13 months of development since Perl
+5.30.0 and contains approximately 220,000 lines of changes across 1,800
+files from 89 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 140,000 lines of changes to 880 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.32.0:
+.PP
+Aaron Crane, Alberto Simões, Alexandr Savca, Andreas König, Andrew Fresh,
+Andy Dougherty, Ask Bjørn Hansen, Atsushi Sugawara, Bernhard M. Wiedemann,
+brian d foy, Bryan Stenson, Chad Granum, Chase Whitener, Chris 'BinGOs'
+Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Book, Daniel
+Dragan, Dan Kogai, Dave Cross, Dave Rolsky, David Cantrell, David Mitchell,
+Dominic Hargreaves, E. Choroba, Felipe Gasper, Florian Weimer, Graham Knop,
+Håkon Hægland, Hauke D, H.Merijn Brand, Hugo van der Sanden, Ichinose
+Shogo, James E Keenan, Jason McIntosh, Jerome Duval, Johan Vromans, John
+Lightsey, John Paul Adrian Glaubitz, Kang-min Liu, Karen Etheridge, Karl
+Williamson, Leon Timmermans, Manuel Mausz, Marc Green, Matthew Horsfall,
+Matt Turner, Max Maischein, Michael Haardt, Nicholas Clark, Nicolas R., Niko
+Tyni, Pali, Paul Evans, Paul Johnson, Paul Marquess, Peter Eisentraut, Peter
+John Acklam, Peter Oliver, Petr Písař, Renee Baecker, Ricardo Signes,
+Richard Leach, Russ Allbery, Samuel Smith, Santtu Ojanperä, Sawyer X,
+Sergey Aleynikov, Sergiy Borodych, Shirakata Kentaro, Shlomi Fish, Sisyphus,
+Slaven Rezic, Smylers, Stefan Seifert, Steve Hay, Steve Peters, Svyatoslav,
+Thibault Duponchelle, Todd Rinaldo, Tomasz Konojacki, Tom Hukins, Tony Cook,
+Unicode Consortium, VanL, Vickenty Fesunov, Vitali Peil, Yves Orton, Zefram.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>. There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>. Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5321delta.1 b/upstream/mageia-cauldron/man1/perl5321delta.1
new file mode 100644
index 00000000..1a9799d0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5321delta.1
@@ -0,0 +1,264 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5321DELTA 1"
+.TH PERL5321DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5321delta \- what is new for perl v5.32.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.32.0 release and the 5.32.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.30.0, first read
+perl5320delta, which describes differences between 5.30.0 and 5.32.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with Perl 5.32.0.  If any
+exist, they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.174 to 2.174_01.
+.Sp
+A number of memory leaks have been fixed.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.47 to 1.47_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20200620 to 5.20210123.
+.IP \(bu 4
+Opcode has been upgraded from version 1.47 to 1.48.
+.Sp
+A warning has been added about evaluating untrusted code with the perl
+interpreter.
+.IP \(bu 4
+Safe has been upgraded from version 2.41 to 2.41_01.
+.Sp
+A warning has been added about evaluating untrusted code with the perl
+interpreter.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlgov\fR
+.IX Subsection "perlgov"
+.PP
+Documentation of the newly formed rules of governance for Perl.
+.PP
+\fIperlsecpolicy\fR
+.IX Subsection "perlsecpolicy"
+.PP
+Documentation of how the Perl security team operates and how the team evaluates
+new security reports.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes listed in
+this document.  If you find any we have missed, open an issue at
+<https://github.com/Perl/perl5/issues>.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Document range op behaviour change.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+\&\eK not permitted in lookahead/lookbehind in regex; marked by <\-\- HERE in m/%s/
+.Sp
+This error was incorrectly produced in some cases involving nested lookarounds.
+This has been fixed.
+.Sp
+[GH #18123 <https://github.com/Perl/perl5/issues/18123>]
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Newer 64\-bit versions of the Intel C/C++ compiler are now recognized and have
+the correct flags set.
+.IP \(bu 4
+We now trap SIGBUS when \fIConfigure\fR checks for \f(CW\*(C`va_copy\*(C'\fR.
+.Sp
+On several systems the attempt to determine if we need \f(CW\*(C`va_copy\*(C'\fR or similar
+results in a SIGBUS instead of the expected SIGSEGV, which previously caused a
+core dump.
+.Sp
+[GH #18148 <https://github.com/Perl/perl5/issues/18148>]
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP "MacOS (Darwin)" 4
+.IX Item "MacOS (Darwin)"
+The hints file for darwin has been updated to handle future macOS versions
+beyond 10.  Perl can now be built on macOS Big Sur.
+.Sp
+[GH #17946 <https://github.com/Perl/perl5/issues/17946>,
+GH #18406 <https://github.com/Perl/perl5/issues/18406>]
+.IP Minix 4
+.IX Item "Minix"
+Build errors on Minix have been fixed.
+.Sp
+[GH #17908 <https://github.com/Perl/perl5/issues/17908>]
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Some list assignments involving \f(CW\*(C`undef\*(C'\fR on the left-hand side were
+over-optimized and produced incorrect results.
+.Sp
+[GH #16685 <https://github.com/Perl/perl5/issues/16685>,
+GH #17816 <https://github.com/Perl/perl5/issues/17816>]
+.IP \(bu 4
+Fixed a bug in which some regexps with recursive subpatterns matched
+incorrectly.
+.Sp
+[GH #18096 <https://github.com/Perl/perl5/issues/18096>]
+.IP \(bu 4
+Fixed a deadlock that hung the build when Perl is compiled for debugging memory
+problems and has PERL_MEM_LOG enabled.
+.Sp
+[GH #18341 <https://github.com/Perl/perl5/issues/18341>]
+.IP \(bu 4
+Fixed a crash in the use of chained comparison operators when run under "no
+warnings 'uninitialized'".
+.Sp
+[GH #17917 <https://github.com/Perl/perl5/issues/17917>,
+GH #18380 <https://github.com/Perl/perl5/issues/18380>]
+.IP \(bu 4
+Exceptions thrown from destructors during global destruction are no longer
+swallowed.
+.Sp
+[GH #18063 <https://github.com/Perl/perl5/issues/18063>]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.32.1 represents approximately 7 months of development since Perl 5.32.0
+and contains approximately 7,000 lines of changes across 80 files from 23
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,300 lines of changes to 23 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.32.1:
+.PP
+Adam Hartley, Andy Dougherty, Dagfinn Ilmari Mannsåker, Dan Book, David
+Mitchell, Graham Knop, Graham Ollis, Hauke D, H.Merijn Brand, Hugo van der
+Sanden, John Lightsey, Karen Etheridge, Karl Williamson, Leon Timmermans, Max
+Maischein, Nicolas R., Ricardo Signes, Richard Leach, Sawyer X, Sevan Janiyan,
+Steve Hay, Tom Hukins, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5340delta.1 b/upstream/mageia-cauldron/man1/perl5340delta.1
new file mode 100644
index 00000000..d692e6e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5340delta.1
@@ -0,0 +1,1052 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5340DELTA 1"
+.TH PERL5340DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5340delta \- what is new for perl v5.34.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.32.0 release and the 5.34.0
+release.
+.PP
+If you are upgrading from an earlier release such as 5.30.0, first read
+perl5320delta, which describes differences between 5.30.0 and 5.32.0.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Experimental Try/Catch Syntax"
+.IX Subsection "Experimental Try/Catch Syntax"
+An initial experimental attempt at providing \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR notation has
+been added.
+.PP
+.Vb 1
+\&    use feature \*(Aqtry\*(Aq;
+\&
+\&    try {
+\&        a_function();
+\&    }
+\&    catch ($e) {
+\&        warn "An error occurred: $e";
+\&    }
+.Ve
+.PP
+For more information, see "Try Catch Exception Handling" in perlsyn.
+.ie n .SS """qr/{,n}/"" is now accepted"
+.el .SS "\f(CWqr/{,n}/\fP is now accepted"
+.IX Subsection "qr/{,n}/ is now accepted"
+An empty lower bound is now accepted for regular expression quantifiers,
+like \f(CW\*(C`m/x{,3}/\*(C'\fR meaning \f(CW\*(C`m/x{0,3}/\*(C'\fR
+.SS "Blanks freely allowed within but adjacent to curly braces"
+.IX Subsection "Blanks freely allowed within but adjacent to curly braces"
+(in double-quotish contexts and regular expression patterns)
+.PP
+This means you can write things like \f(CW\*(C`\ex{\ FFFC\ }\*(C'\fR if you like.  This
+applies to all such constructs, namely \f(CW\*(C`\eb{}\*(C'\fR, \f(CW\*(C`\eg{}\*(C'\fR, \f(CW\*(C`\ek{}\*(C'\fR,
+\&\f(CW\*(C`\eN{}\*(C'\fR, \f(CW\*(C`\eo{}\*(C'\fR, and \f(CW\*(C`\ex{}\*(C'\fR; as well as the regular expression
+quantifier \f(CW\*(C`{\fR\f(CIm\fR\f(CW,\fR\f(CIn\fR\f(CW}\*(C'\fR.  \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR retain their
+already-existing, even looser, rules mandated by the Unicode standard
+(see "Properties accessible through \ep{} and \eP{}" in perluniprops).
+.PP
+This ability is in effect regardless of the presence of the \f(CW\*(C`/x\*(C'\fR
+regular expression pattern modifier.
+.PP
+Additionally, the comma in a regular expression braced quantifier may
+have blanks (tabs or spaces) before and/or after the comma, like
+\&\f(CW\*(C`qr/a{\ 5,\ 7\ }/\*(C'\fR.
+.ie n .SS "New octal syntax ""0o\fIddddd\fP"""
+.el .SS "New octal syntax \f(CW0o\fP\f(CIddddd\fP\f(CW\fP"
+.IX Subsection "New octal syntax 0oddddd"
+It is now possible to specify octal literals with \f(CW\*(C`0o\*(C'\fR prefixes,
+as in \f(CW\*(C`0o123_456\*(C'\fR, parallel to the existing construct to specify
+hexadecimal literal \f(CW\*(C`0x\fR\f(CIddddd\fR\f(CW\*(C'\fR and binary literal \f(CW\*(C`0b\fR\f(CIddddd\fR\f(CW\*(C'\fR.
+Also, the builtin \f(CWoct()\fR function now accepts this new syntax.
+.PP
+See "Scalar value constructors" in perldata and "oct EXPR" in perlfunc.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Fix a memory leak in RegEx
+[GH #18604 <https://github.com/Perl/perl5/issues/18604>]
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+ExtUtils::PL2Bat 0.004 has been added to the Perl core.
+.Sp
+This module is a generalization of the \f(CW\*(C`pl2bat\*(C'\fR script. It being a script has
+led to at least two forks of this code; this module will unify them under one
+implementation with tests.
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.36 to 2.38.
+.IP \(bu 4
+autodie has been upgraded from version 2.32 to 2.34.
+.IP \(bu 4
+B has been upgraded from version 1.80 to 1.82.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.54 to 1.56.
+.IP \(bu 4
+bytes has been upgraded from version 1.07 to 1.08.
+.IP \(bu 4
+Carp has been upgraded from version 1.50 to 1.52.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.093 to 2.101.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.093 to 2.101.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.32 to 0.33.
+.IP \(bu 4
+CPAN has been upgraded from version 2.27 to 2.28.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.174 to 2.179.
+.IP \(bu 4
+DB has been upgraded from version 1.58 to 1.59.
+.IP \(bu 4
+DB_File has been upgraded from version 1.853 to 1.855.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.28 to 1.30.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.57 to 3.62.
+.Sp
+New \f(CW\*(C`PERL_VERSION_*\*(C'\fR comparison macros are now available.
+.Sp
+\&\f(CW\*(C`ppport.h \-\-api\-info\*(C'\fR no longer includes non-API info unless that is the only
+match
+.IP \(bu 4
+Digest has been upgraded from version 1.17_01 to 1.19.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.55_01 to 2.58.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.47 to 1.50.
+.IP \(bu 4
+Encode has been upgraded from version 3.06 to 3.08.
+.IP \(bu 4
+Env has been upgraded from version 1.04 to 1.05.
+.IP \(bu 4
+Errno has been upgraded from version 1.30 to 1.33.
+.IP \(bu 4
+experimental has been upgraded from version 0.020 to 0.024.
+.IP \(bu 4
+Exporter has been upgraded from version 5.74 to 5.76.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280234 to 0.280236.
+.IP \(bu 4
+ExtUtils::Install has been upgraded from version 2.14 to 2.20.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.44 to 7.62.
+.IP \(bu 4
+ExtUtils::Manifest has been upgraded from version 1.72 to 1.73.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.40 to 3.43.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.38 to 3.43.
+.IP \(bu 4
+Fcntl has been upgraded from version 1.13 to 1.14.
+.IP \(bu 4
+feature has been upgraded from version 1.58 to 1.64.
+.Sp
+Added the default enabled \f(CW\*(C`bareword_filehandles\*(C'\fR feature.
+.Sp
+A new multidimensional
+feature has been added, which is enabled by
+default but allows turning off multi-dimensional array
+emulation.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.34 to 2.35.
+.IP \(bu 4
+File::Fetch has been upgraded from version 0.56 to 1.00.
+.IP \(bu 4
+File::Find has been upgraded from version 1.37 to 1.39.
+.IP \(bu 4
+File::Path has been upgraded from version 2.16 to 2.18.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.78 to 3.80.
+.IP \(bu 4
+File::Temp has been upgraded from version 0.2309 to 0.2311.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.59 to 1.60.
+.IP \(bu 4
+FindBin has been upgraded from version 1.51 to 1.52.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.18 to 1.19.
+.Sp
+New functions and compatibility for newer versions of GDBM.
+[GH #18435 <https://github.com/Perl/perl5/pull/18435>]
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.51 to 2.52.
+.IP \(bu 4
+Getopt::Std has been upgraded from version 1.12 to 1.13.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.23 to 0.25.
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.20 to 1.21.
+.IP \(bu 4
+I18N::LangTags has been upgraded from version 0.44 to 0.45.
+.IP \(bu 4
+if has been upgraded from version 0.0608 to 0.0609.
+.IP \(bu 4
+IO has been upgraded from version 1.43 to 1.46.
+.Sp
+IO::Socket now stores error messages in \f(CW$IO::Socket::errstr\fR, in
+addition to in \f(CW$@\fR.
+.Sp
+The \f(CW\*(C`error\*(C'\fR method now reports the error state for both the input and
+output streams for sockets and character devices.  Similarly
+\&\f(CW\*(C`clearerr\*(C'\fR now clears the error state for both streams.
+.Sp
+A spurious error reported for regular file handles has been
+fixed in IO::Handle.
+[GH #18019 <https://github.com/Perl/perl5/issues/18019>]
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.093 to 2.102.
+.Sp
+bin/zipdetails version 2.02
+.IP \(bu 4
+IO::Socket::IP has been upgraded from version 0.39 to 0.41.
+.IP \(bu 4
+IO::Zlib has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+IPC::SysV has been upgraded from version 2.07 to 2.09.
+.IP \(bu 4
+JSON::PP has been upgraded from version 4.04 to 4.06.
+.IP \(bu 4
+The libnet distribution has been upgraded from version 3.11 to 3.13.
+.IP \(bu 4
+locale has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+Math::Complex has been upgraded from version 1.5901 to 1.5902.
+.IP \(bu 4
+MIME::Base64 has been upgraded from version 3.15 to 3.16.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20200620 to 5.20210520.
+.IP \(bu 4
+Module::Load has been upgraded from version 0.34 to 0.36.
+.IP \(bu 4
+Module::Load::Conditional has been upgraded from version 0.70 to 0.74.
+.IP \(bu 4
+mro has been upgraded from version 1.23 to 1.25_001.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.72 to 2.74.
+.IP \(bu 4
+NEXT has been upgraded from version 0.67_01 to 0.68.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.16 to 1.17.
+.IP \(bu 4
+Opcode has been upgraded from version 1.47 to 1.50.
+.IP \(bu 4
+overload has been upgraded from version 1.31 to 1.33.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.20200523 to 5.20210411.
+.IP \(bu 4
+PerlIO::encoding has been upgraded from version 0.28 to 0.30.
+.IP \(bu 4
+PerlIO::mmap has been upgraded from version 0.016 to 0.017.
+.IP \(bu 4
+PerlIO::scalar has been upgraded from version 0.30 to 0.31.
+.IP \(bu 4
+PerlIO::via::QuotedPrint has been upgraded from version 0.08 to 0.09.
+.IP \(bu 4
+Pod::Checker has been upgraded from version 1.73 to 1.74.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.25 to 1.27.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.40 to 3.42.
+.IP \(bu 4
+Pod::Usage has been upgraded from version 1.69 to 2.01.
+.IP \(bu 4
+POSIX has been upgraded from version 1.94 to 1.97.
+.Sp
+\&\fBPOSIX::signbit()\fR behaviour has been improved.
+[GH #18441 <https://github.com/Perl/perl5/pull/18441>]
+.Sp
+Documentation for \f(CW\*(C`asctime\*(C'\fR clarifies that the result is always in English.
+(Use \f(CW\*(C`strftime\*(C'\fR for a localized result.)
+.IP \(bu 4
+re has been upgraded from version 0.40 to 0.41.
+.Sp
+(See under "Internal Changes" for more information.)
+.IP \(bu 4
+Safe has been upgraded from version 2.41 to 2.43.
+.IP \(bu 4
+Socket has been upgraded from version 2.029 to 2.031.
+.IP \(bu 4
+Storable has been upgraded from version 3.21 to 3.23.
+.IP \(bu 4
+strict has been upgraded from version 1.11 to 1.12.
+.IP \(bu 4
+subs has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+Symbol has been upgraded from version 1.08 to 1.09.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.42 to 3.43.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302175 to 1.302183.
+.IP \(bu 4
+Text::Balanced has been upgraded from version 2.03 to 2.04.
+.IP \(bu 4
+threads has been upgraded from version 2.25 to 2.26.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.61 to 1.62.
+.IP \(bu 4
+Tie::RefHash has been upgraded from version 1.39 to 1.40.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9764 to 1.9767.
+.IP \(bu 4
+Time::Local has been upgraded from version 1.28 to 1.30.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.27 to 1.29.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.27 to 1.28.
+.IP \(bu 4
+utf8 has been upgraded from version 1.22 to 1.24.
+.IP \(bu 4
+version has been upgraded from version 0.9924 to 0.9928.
+.IP \(bu 4
+warnings has been upgraded from version 1.47 to 1.51.
+.IP \(bu 4
+Win32 has been upgraded from version 0.53 to 0.57.
+.Sp
+Fix calling convention for \f(CW\*(C`PFNRegGetValueA\*(C'\fR.
+.Sp
+Added \f(CWWin32::IsSymlinkCreationAllowed()\fR,
+\&\f(CWWin32::IsDeveloperModeEnabled()\fR, and \f(CWWin32::GetProcessPrivileges()\fR.
+.Sp
+Removed old code for versions before Windows 2000.
+.IP \(bu 4
+XS::APItest has been upgraded from version 1.09 to 1.16.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.17 to 0.18.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperldocstyle\fR
+.IX Subsection "perldocstyle"
+.PP
+This document is a guide for the authorship and maintenance of the
+documentation that ships with Perl.
+.PP
+\fIperlgov\fR
+.IX Subsection "perlgov"
+.PP
+This document describes the goals, scope, system, and rules for Perl's new
+governance model.
+.PP
+Other pod files, most notably perlpolicy, were amended to reflect
+its adoption.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, open an issue
+at <https://github.com/Perl/perl5/issues>.
+.PP
+Additionally, the following selected changes have been made:
+.IP \(bu 4
+perlapi, perlguts, perlxs, and perlxstut now prefer \f(CW\*(C`SvPVbyte\*(C'\fR
+over \f(CW\*(C`SvPV\*(C'\fR.
+.IP \(bu 4
+References to \fBPumpking\fR have been replaced with a more accurate term or
+\&\fBSteering Council\fR where appropriate.
+.IP \(bu 4
+\&\fBThe Perl Steering Council\fR is now the fallback contact for security issues.
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+Efforts continue in improving the presentation of this document, and to
+document more API elements.
+.PP
+\fIperlcommunity\fR
+.IX Subsection "perlcommunity"
+.IP \(bu 4
+The freenode IRC URL has been updated.
+.PP
+\fIperldebguts\fR
+.IX Subsection "perldebguts"
+.IP \(bu 4
+Corrected the description of the scalar \f(CW\*(C`${"_<$filename"}\*(C'\fR
+variables.
+.PP
+\fIperldiag\fR
+.IX Subsection "perldiag"
+.IP \(bu 4
+Now documents additional examples of "not imported" warnings.
+.PP
+\fIperlfaq\fR
+.IX Subsection "perlfaq"
+.IP \(bu 4
+The Perl FAQ was updated to CPAN version 5.20201107 with minor
+improvements.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+\&\fBmy()\fR and \fBstate()\fR now explicitly warn
+the reader that lexical variables should typically not be redeclared
+within the same scope or statement.
+[GH #18389 <https://github.com/Perl/perl5/issues/18389>]
+.IP \(bu 4
+The localtime entry has been improved and now
+also states that the result of the function is always in English.
+.IP \(bu 4
+\&\fBmsgsnd()\fR documented a length field included in the
+packed \f(CW\*(C`MSG\*(C'\fR parameter to \f(CWmsgsnd()\fR, but there was no such field.
+\&\f(CW\*(C`MSG\*(C'\fR contains only the type and the message content.
+.IP \(bu 4
+Better explanation of what happens when \f(CW\*(C`sleep\*(C'\fR is called with a zero or
+negative value.
+.IP \(bu 4
+Simplify the \f(CWsplit()\fR documentation by removing the \f(CWjoin()\fRs from the
+examples
+[GH #18676 <https://github.com/Perl/perl5/issues/18676>]
+.PP
+\fIperlgit\fR
+.IX Subsection "perlgit"
+.IP \(bu 4
+document how to create a remote-tracking branch for every PR
+.IP \(bu 4
+document how to get a PR as a local branch
+.PP
+\fIperlguts\fR
+.IX Subsection "perlguts"
+.IP \(bu 4
+perlguts now explains in greater detail the need to consult \f(CW\*(C`SvUTF8\*(C'\fR
+when calling \f(CW\*(C`SvPV\*(C'\fR (or variants). A new "How do I pass a Perl string to a C
+library?" section in the same document discusses when to use which style of
+macro to read an SV's string value.
+.IP \(bu 4
+Corrected \f(CW\*(C`my_rpeep\*(C'\fR example in perlguts.
+.IP \(bu 4
+A section has been added on the formatted printing of special sizes.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+The \f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`<<>>\*(C'\fR operators are commonly referred to as
+the diamond and double diamond operators respectively, but that wasn't
+mentioned previously in their documentation.
+.IP \(bu 4
+Document range op behavior change.
+.PP
+\fIperlpacktut\fR
+.IX Subsection "perlpacktut"
+.IP \(bu 4
+Incorrect variables used in an example have been fixed.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP \(bu 4
+Document that \fBcaller()\fR does not see try{} blocks
+.IP \(bu 4
+A new example shows how a lexical \f(CW\*(C`my\*(C'\fR variable can be declared
+during the initialization of a \f(CW\*(C`for\*(C'\fR loop.
+.PP
+\fIperlunifaq\fR
+.IX Subsection "perlunifaq"
+.IP \(bu 4
+Fix description of what Perl does with unencoded strings
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Bareword filehandle "%s" not allowed under 'no feature "bareword_filehandles"'
+.Sp
+This accompanies the new
+bareword_filehandles feature.
+.IP \(bu 4
+Multidimensional hash lookup is disabled
+.Sp
+This accompanies the new
+multidimensional feature.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Wide character in setenv key (encoding to utf8)
+.Sp
+Attempts to put wide characters into environment variable keys via \f(CW%ENV\fR now
+provoke this warning.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+Error \f(CW%s\fR in expansion of \f(CW%s\fR
+.Sp
+An error was encountered in handling a user-defined property
+("User-Defined Character Properties" in perlunicode).  These are
+programmer written subroutines, hence subject to errors that may
+prevent them from compiling or running.
+.IP \(bu 4
+Infinite recursion in user-defined property
+.Sp
+A user-defined property ("User-Defined Character Properties" in perlunicode)
+can depend on the definitions of other user-defined
+properties.  If the chain of dependencies leads back to this property,
+infinite recursion would occur, were it not for the check that raised
+this error.
+.IP \(bu 4
+Timeout waiting for another thread to define \ep{%s}
+.Sp
+The first time a user-defined property
+("User-Defined Character Properties" in perlunicode) is used, its
+definition is looked up and converted into an internal form for more
+efficient handling in subsequent uses.  There could be a race if two or
+more threads tried to do this processing nearly simultaneously.
+.IP \(bu 4
+Unknown user-defined property name \ep{%s}
+.Sp
+You specified to use a property within the \f(CW\*(C`\ep{...}\*(C'\fR which was a
+syntactically valid user-defined property, but no definition was found
+for it
+.IP \(bu 4
+Too few arguments for subroutine '%s' (got \f(CW%d\fR; expected \f(CW%d\fR)
+.Sp
+Subroutine argument-count mismatch errors now include the number of
+given and expected arguments.
+.IP \(bu 4
+Too many arguments for subroutine '%s' (got \f(CW%d\fR; expected \f(CW%d\fR)
+.Sp
+Subroutine argument-count mismatch errors now include the number of
+given and expected arguments.
+.IP \(bu 4
+Lost precision when \f(CW%s\fR \f(CW%f\fR by 1
+.Sp
+This warning was only issued for positive too-large values when
+incrementing, and only for negative ones when decrementing.
+It is now issued for both positive or negative too-large values.
+[GH #18333 <https://github.com/Perl/perl5/issues/18333>]
+.IP \(bu 4
+\&\eK not permitted in lookahead/lookbehind in regex; marked by <\-\- HERE in m/%s/
+.Sp
+This error was incorrectly produced in some cases involving nested
+lookarounds.  This has been fixed.
+[GH #18123 <https://github.com/Perl/perl5/issues/18123>]
+.IP \(bu 4
+Use of uninitialized value%s
+.Sp
+This warning may now include the array or hash index when the
+uninitialized value is the result of an element not found.  This will
+only happen if the index is a simple non-magical variable.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "perl5db.pl (the debugger)"
+.IX Subsection "perl5db.pl (the debugger)"
+.IP \(bu 4
+New option: \f(CW\*(C`HistItemMinLength\*(C'\fR
+.Sp
+This option controls the minimum length a command must be to get stored in
+history.  Traditionally, this has been fixed at 2.  Changes to the debugger
+are often perilous, and new bugs should be reported so the debugger can be
+debugged.
+.IP \(bu 4
+Fix to \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`l\*(C'\fR commands
+.Sp
+The \f(CW\*(C`i $var\*(C'\fR and \f(CW\*(C`l $var\*(C'\fR commands work again with lexical variables.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+Prevented incpath to spill into libpth
+.IP \(bu 4
+Use realpath if available. (This might catch more duplicate paths.)
+.IP \(bu 4
+Only include real existing paths.
+.IP \(bu 4
+Filter inc paths out of libpth.
+.IP \(bu 4
+stadtx hash support has been removed
+.Sp
+stadtx support has been entirely removed.  Previously, it could be requested
+with \f(CW\*(C`PERL_HASH_FUNC_STADTX\*(C'\fR, and was default in 64\-bit builds.  It has been
+replaced with SipHash.  SipHash has been more rigorously reviewed than stadtx.
+.IP \(bu 4
+Configure
+.Sp
+A new probe checks for buggy libc implementations of the \f(CW\*(C`gcvt\*(C'\fR/\f(CW\*(C`qgcvt\*(C'\fR
+functions.
+[GH #18170 <https://github.com/Perl/perl5/issues/18170>]
+.IP \(bu 4
+\&\f(CW\*(C`\-Dusedefaultstrict\*(C'\fR
+.Sp
+Perl can now be built with strict on by default (using the configuration
+option \f(CW\*(C`\-Dusedefaultstrict\*(C'\fR.
+.Sp
+These strict defaults do not apply when \f(CW\*(C`perl\*(C'\fR is run via \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR.
+.Sp
+This setting provides a diagnostic mechanism intended for development
+purposes only and is thus undefined by default.
+.IP \(bu 4
+The minimum supported Bison version is now 2.4, and the maximum is 3.7.
+.IP \(bu 4
+Newer 64\-bit versions of the Intel C/C++ compiler are now recognised
+and have the correct flags set.
+.IP \(bu 4
+We now trap SIGBUS when \fIConfigure\fR checks for \f(CW\*(C`va_copy\*(C'\fR.
+.Sp
+On several systems the attempt to determine if we need \f(CW\*(C`va_copy\*(C'\fR or similar
+results in a SIGBUS instead of the expected SIGSEGV, which previously caused a
+core dump.
+.Sp
+[GH #18148 <https://github.com/Perl/perl5/issues/18148>]
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and
+changes in this release.  Furthermore, these significant changes were
+made:
+.IP \(bu 4
+Split Config-dependent tests in \fIt/opbasic/arith.t\fR to \fIt/op/arith2.t\fR
+.IP \(bu 4
+\&\fIt/re/opt.t\fR was added, providing a test harness for regexp optimization.
+[GH #18213 <https://github.com/Perl/perl5/pull/18213>]
+.IP \(bu 4
+A workaround for CPAN distributions needing dot in \f(CW@INC\fR has been removed
+[GH #18394 <https://github.com/Perl/perl5/pull/18394>].
+All distributions that previously required the workaround have now been
+adapted.
+.IP \(bu 4
+When testing in parallel on many-core platforms, you can now cause the
+test suite to finish somewhat earlier, but with less logical ordering of
+the tests, by setting
+.Sp
+.Vb 1
+\& PERL_TEST_HARNESS_ASAP=1
+.Ve
+.Sp
+while running the test suite.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "New Platforms"
+.IX Subsection "New Platforms"
+.IP 9front 4
+.IX Item "9front"
+Allow building Perl on i386 9front systems (a fork of plan9).
+.SS "Updated Platforms"
+.IX Subsection "Updated Platforms"
+.IP Plan9 4
+.IX Item "Plan9"
+Improve support for Plan9 on i386 platforms.
+.IP "MacOS (Darwin)" 4
+.IX Item "MacOS (Darwin)"
+The hints file for darwin has been updated to handle future MacOS versions
+beyond 10. [GH #17946 <https://github.com/Perl/perl5/issues/17946>]
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP Symbian 4
+.IX Item "Symbian"
+Support code relating to Symbian has been removed.  Symbian was an
+operating system for mobile devices.  The port was last updated in July
+2009, and the platform itself in October 2012.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP DragonFlyBSD 4
+.IX Item "DragonFlyBSD"
+Tests were updated to workaround DragonFlyBSD bugs in tc*()
+functions <https://bugs.dragonflybsd.org/issues/3252> and ctime
+updates <https://bugs.dragonflybsd.org/issues/3251>.
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+A number of system libraries no longer exist as actual files on Big Sur,
+even though \f(CW\*(C`dlopen\*(C'\fR will pretend they do, so now we fall back to \f(CW\*(C`dlopen\*(C'\fR
+if a library file can not be found.
+[GH #18407 <https://github.com/Perl/perl5/issues/18407>]
+.IP Windows 4
+.IX Item "Windows"
+Reading non-ASCII characters from the console when its codepage was set to
+65001 (UTF\-8) was broken due to a bug in Windows. A workaround for this
+problem has been implemented.
+[GH #18701 <https://github.com/Perl/perl5/issues/18701>]
+.Sp
+Building with mingw.org compilers (version 3.4.5 or later) using mingw runtime
+versions < 3.22 now works again.  This was broken in Perl 5.31.4.
+.Sp
+Building with mingw.org compilers (version 3.4.5 or later) using mingw runtime
+versions >= 3.21 now works (for compilers up to version 5.3.0).
+.Sp
+\&\fIMakefile.mk\fR, and thus support for dmake, has been removed. It is still
+possible to build Perl on Windows using nmake (Makefile) and GNU make
+(GNUmakefile).
+[GH #18511 <https://github.com/Perl/perl5/pull/18511>]
+.Sp
+perl can now be built with \f(CW\*(C`USE_QUADMATH\*(C'\fR on MS Windows using
+(32\-bit and 64\-bit) mingw\-w64 ports of gcc.
+[GH #18465 <https://github.com/Perl/perl5/pull/18465>]
+.Sp
+The \fIpl2bat.pl\fR utility now needs to \f(CW\*(C`use ExtUtils::PL2Bat\*(C'\fR. This could
+cause failures in parallel builds.
+.Sp
+Windows now supports \fBsymlink()\fR and
+\&\fBreadlink()\fR, and \fBlstat()\fR is no
+longer an alias for \fBstat()\fR.
+[GH #18005 <https://github.com/Perl/perl5/issues/18005>].
+.Sp
+Unlike POSIX systems, creating a symbolic link on Windows requires
+either elevated privileges or Windows 10 1703 or later with Developer
+Mode enabled.
+.Sp
+\&\fBstat()\fR, including \f(CW\*(C`stat FILEHANDLE\*(C'\fR, and \fBlstat()\fR now uses our own
+implementation that populates the device \f(CW\*(C`dev\*(C'\fR and inode numbers
+\&\f(CW\*(C`ino\*(C'\fR returned rather than always returning zero.  The number of
+links \f(CW\*(C`nlink\*(C'\fR field is now always populated.
+.Sp
+\&\f(CW\*(C`${^WIN32_SLOPPY_STAT}\*(C'\fR  previously
+controlled whether the \f(CW\*(C`nlink\*(C'\fR field was populated requiring a
+separate Windows API call to fetch, since \f(CW\*(C`nlink\*(C'\fR and the other
+information required for \f(CWstat()\fR is now retrieved in a single API call.
+.Sp
+The \f(CW\*(C`\-r\*(C'\fR and \f(CW\*(C`\-w\*(C'\fR operators now return true for the \f(CW\*(C`STDIN\*(C'\fR,
+\&\f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR handles.  Unfortunately it still won't return
+true for duplicates of those handles.
+[GH #8502 <https://github.com/Perl/perl5/issues/8502>].
+.Sp
+The times returned by \fBstat()\fR and \fBlstat()\fR are no longer incorrect
+across Daylight Savings Time adjustments.
+[GH #6080 <https://github.com/Perl/perl5/issues/6080>].
+.Sp
+\&\f(CW\*(C`\-x\*(C'\fR on a filehandle should now match \f(CW\*(C`\-x\*(C'\fR on the corresponding
+filename on Vista or later.
+[GH #4145 <https://github.com/Perl/perl5/issues/4145>].
+.Sp
+\&\f(CW\*(C`\-e \*(Aq"\*(Aq\*(C'\fR no longer incorrectly returns true.
+[GH #12431 <https://github.com/Perl/perl5/issues/12431>].
+.Sp
+The same manifest is now used for Visual C++ and gcc builds.
+.Sp
+Previously, MSVC builds were using the \fB/manifestdependency\fR flag instead of
+embedding \fIperlexe.manifest\fR, which caused issues such as \f(CWGetVersionEx()\fR
+returning the wrong version number on Windows 10.
+.IP z/OS 4
+.IX Item "z/OS"
+The locale categories \f(CW\*(C`LC_SYNTAX\*(C'\fR and \f(CW\*(C`LC_TOD\*(C'\fR are now recognized.
+Perl doesn't do anything with these, except it now allows you to specify
+them.  They are included in \f(CW\*(C`LC_ALL\*(C'\fR.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Corrected handling of double and long double parameters for perl's
+implementation of formatted output for \f(CW\*(C`\-Dusequadmath\*(C'\fR builds.
+.Sp
+This applies to \f(CWPerlIO_printf()\fR, \f(CWcroak()\fR, \f(CWwarn()\fR, \f(CWsv_catpvf()\fR and
+their variants.
+.Sp
+Previously in \f(CW\*(C`quadmath\*(C'\fR builds, code like:
+.Sp
+.Vb 1
+\&  PerlIO_printf(PerlIO_stderr(), "%g", somedouble);
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&  PerlIO_printf(PerlIO_stderr(), "%Lg", somelongdouble);
+.Ve
+.Sp
+would erroneously throw an exception "panic: quadmath invalid format
+\&...", since the code added for quadmath builds assumed \f(CW\*(C`NV\*(C'\fRs were the
+only floating point format passed into these functions.
+.Sp
+This code would also process the standard C long double specifier \f(CW\*(C`L\*(C'\fR
+as if it expected an \f(CW\*(C`NV\*(C'\fR (\f(CW\*(C`_\|_float128\*(C'\fR for quadmath builds),
+resulting in undefined behaviour.
+.Sp
+These functions now correctly accept doubles, long doubles and NVs.
+.IP \(bu 4
+Previously the right operand of bitwise shift operators (shift amount)
+was implicitly cast from IV to int, but it might lead wrong results
+if IV does not fit in int.
+.Sp
+And also, shifting INT_MIN bits used to yield the shiftee unchanged
+(treated as 0\-bit shift instead of negative shift).
+.IP \(bu 4
+A set of \f(CW\*(C`cop_hints_exists_{pv,pvn,pvs,sv}\*(C'\fR functions was added,
+to support checking for the existence of keys in the hints hash of a
+specific cop without needing to create a mortal copy of said value.
+.IP \(bu 4
+An aid has been added for using the \f(CW\*(C`DEBUG\*(C'\fR macros when debugging XS or
+C code. The comments in \fIperl.h\fR describe \f(CW\*(C`DEBUG_PRE_STMTS\*(C'\fR and
+\&\f(CW\*(C`DEBUG_POST_STMTS\*(C'\fR. which you can \f(CW\*(C`#define\*(C'\fR to do things like save and
+restore \f(CW\*(C`errno\*(C'\fR, in case the \f(CW\*(C`DEBUG\*(C'\fR calls are interfering with that,
+or to display timestamps, or which thread it's coming from, or the
+location of the call, or whatever.  You can make a quick hack to help
+you track something down without having to edit individual \f(CW\*(C`DEBUG\*(C'\fR
+calls.
+.IP \(bu 4
+Make \f(CW\*(C`REFCOUNTED_HE_EXISTS\*(C'\fR available outside of core
+.IP \(bu 4
+All \f(CW\*(C`SvTRUE\*(C'\fR\-ish functions now evaluate their arguments exactly once.
+In 5.32, plain "\f(CW\*(C`SvTRUE\*(C'\fR" in perlapi was changed to do that; now the rest
+do as well.
+.IP \(bu 4
+Unicode is now a first class citizen when considering the pattern /A*B/ where
+A and B are arbitrary.  The pattern matching code tries to make a tight loop
+to match the span of A's.  The logic of this was now really updated with
+support for UTF\-8.
+.IP \(bu 4
+The re module has a new function \f(CW\*(C`optimization\*(C'\fR, which can return a
+hashref of optimization data discovered about a compiled regexp.
+.IP \(bu 4
+The \f(CW\*(C`PERL_GLOBAL_STRUCT\*(C'\fR compilation option has been removed, and
+with it the need or the \f(CW\*(C`dVAR\*(C'\fR macro.  \f(CW\*(C`dVAR\*(C'\fR remains defined as a
+no-op outside \f(CW\*(C`PERL_CORE\*(C'\fR for backwards compatiblity with XS modules.
+.IP \(bu 4
+A new savestack type \f(CW\*(C`SAVEt_HINTS_HH\*(C'\fR has been added, which neatens the
+previous behaviour of \f(CW\*(C`SAVEt_HINTS\*(C'\fR.  On previous versions the types and
+values pushed to the save stack would depend on whether the hints included the
+\&\f(CW\*(C`HINT_LOCALIZE_HH\*(C'\fR bit, which complicates external code that inspects the
+save stack. The new version uses a different savestack type to indicate the
+difference.
+.IP \(bu 4
+A new API function "av_count" in perlapi has been added which gives a
+clearly named way to find how many elements are in an array.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Setting \f(CW%ENV\fR now properly handles upgraded strings in the key. Previously
+Perl sent the SV's internal PV directly to the OS; now it will handle keys
+as it has handled values since 5.18: attempt to downgrade the string first;
+if that fails then warn and use the utf8 form.
+.IP \(bu 4
+Fix a memory leak in regcomp.c
+[GH #18604 <https://github.com/Perl/perl5/issues/18604>]
+.IP \(bu 4
+pack/unpack format 'D' now works on all systems that could support it
+.Sp
+Previously if \f(CW\*(C`NV == long double\*(C'\fR, now it is supported on all platforms that
+have long doubles. In particular that means it is now also supported on
+quadmath platforms.
+.IP \(bu 4
+Skip trying to constant fold an incomplete op tree
+[GH #18380 <https://github.com/Perl/perl5/issues/18380>]
+.Sp
+Constant folding of chained comparison op trees could fail under certain
+conditions, causing perl to crash. As a quick fix, constant folding is
+now skipped for such op trees. This also addresses
+[GH #17917 <https://github.com/Perl/perl5/issues/17917>].
+.IP \(bu 4
+\&\f(CW%g\fR formatting broken on Ubuntu\-18.04, \f(CW\*(C`NVSIZE == 8\*(C'\fR
+[GH #18170 <https://github.com/Perl/perl5/issues/18170>]
+.Sp
+Buggy libc implementations of the \f(CW\*(C`gcvt\*(C'\fR and \f(CW\*(C`qgcvt\*(C'\fR functions
+caused \f(CW\*(C`(s)printf\*(C'\fR to incorrectly truncate \f(CW%g\fR formatted numbers.
+A new Configure probe now checks for this, with the result that the libc
+\&\f(CW\*(C`sprintf\*(C'\fR will be used in place of \f(CW\*(C`gcvt\*(C'\fR and \f(CW\*(C`qgcvt\*(C'\fR.
+.Sp
+Tests added as part of this fix also revealed related problems in
+some Windows builds. The makefiles for MINGW builds on Windows have
+thus been adjusted to use \f(CW\*(C`USE_MINGW_ANSI_STDIO\*(C'\fR by default, ensuring
+that they also provide correct \f(CW\*(C`(s)printf\*(C'\fR formatting of numbers.
+.IP \(bu 4
+\&\fIop.c\fR: croak on \f(CW\*(C`my $_\*(C'\fR when \f(CW\*(C`use utf8\*(C'\fR is in effect
+[GH #18449 <https://github.com/Perl/perl5/issues/18449>]
+.Sp
+The lexical topic feature experiment was removed in Perl v5.24 and
+declaring \f(CW\*(C`my $_\*(C'\fR became a compile time error. However, it was previously
+still possible to make this declaration if \f(CW\*(C`use utf8\*(C'\fR was in effect.
+.IP \(bu 4
+\&\fIregexec.c\fR: Fix assertion failure
+[GH #18451 <https://github.com/Perl/perl5/issues/18451>]
+.Sp
+Fuzzing triggered an assertion failure in the regexp engine when too many
+characters were copied into a buffer.
+.IP \(bu 4
+\&\fBsemctl()\fR, \fBmsgctl()\fR, and
+\&\fBshmctl()\fR now properly reset the UTF\-8 flag on the
+\&\f(CW\*(C`ARG\*(C'\fR parameter if it's modified for \f(CW\*(C`IPC_STAT\*(C'\fR or \f(CW\*(C`GETALL\*(C'\fR
+operations.
+.IP \(bu 4
+\&\f(CWsemctl()\fR, \f(CWmsgctl()\fR, and \f(CWshmctl()\fR now attempt to downgrade the \f(CW\*(C`ARG\*(C'\fR
+parameter if its value is being used as input to \f(CW\*(C`IPC_SET\*(C'\fR or
+\&\f(CW\*(C`SETALL\*(C'\fR calls.  A failed downgrade will thrown an exception.
+.IP \(bu 4
+In cases where \f(CWsemctl()\fR, \f(CWmsgctl()\fR or \f(CWshmctl()\fR would treat the \f(CW\*(C`ARG\*(C'\fR
+parameter as a pointer, an undefined value no longer generates a
+warning.  In most such calls the pointer isn't used anyway and this
+allows you to supply \f(CW\*(C`undef\*(C'\fR for a value not used by the underlying
+function.
+.IP \(bu 4
+\&\fBsemop()\fR now downgrades the \f(CW\*(C`OPSTRING\*(C'\fR parameter,
+\&\fBmsgsnd()\fR now downgrades the \f(CW\*(C`MSG\*(C'\fR parameter and
+shmwrite now downgrades the \f(CW\*(C`STRING\*(C'\fR parameter
+to treat them as bytes.  Previously they would be left upgraded,
+providing a corrupted structure to the underlying function call.
+.IP \(bu 4
+\&\fBmsgrcv()\fR now properly resets the UTF\-8 flag the
+\&\f(CW\*(C`VAR\*(C'\fR parameter when it is modified.  Previously the UTF\-8 flag could
+be left on, resulting in a possibly corrupt result in \f(CW\*(C`VAR\*(C'\fR.
+.IP \(bu 4
+Magic is now called correctly for stacked file test operators.
+[GH #18293 <https://github.com/Perl/perl5/issues/18293>]
+.IP \(bu 4
+The \f(CW\*(C`@ary = split(...)\*(C'\fR optimization no longer switches in the target
+array as the value stack.
+[GH #18232 <https://github.com/Perl/perl5/issues/18232>]
+Also see discussion at
+<https://github.com/Perl/perl5/pull/18014#issuecomment\-671299506>.
+.IP \(bu 4
+Fixed a bug in which some regexps with recursive subpatterns matched
+incorrectly.
+.Sp
+[GH #18096 <https://github.com/Perl/perl5/issues/18096>]
+.IP \(bu 4
+On Win32, \f(CW\*(C`waitpid(\-1, WNOHANG)\*(C'\fR could sometimes have a very large
+timeout.  [GH #16529 <https://github.com/Perl/perl5/issues/16529>]
+.IP \(bu 4
+\&\f(CW\*(C`MARK\*(C'\fR and hence \f(CW\*(C`items\*(C'\fR are now correctly initialized in \f(CW\*(C`BOOT\*(C'\fR XSUBs.
+.IP \(bu 4
+Some list assignments involving \f(CW\*(C`undef\*(C'\fR on the left-hand side were
+over-optimized and produced incorrect results.
+[GH #16685 <https://github.com/Perl/perl5/issues/16685>],
+[GH #17816 <https://github.com/Perl/perl5/issues/17816>]
+.SH "Known Problems"
+.IX Header "Known Problems"
+None
+.SH "Errata From Previous Releases"
+.IX Header "Errata From Previous Releases"
+None
+.SH Obituary
+.IX Header "Obituary"
+Kent Fredric (KENTNL) passed away in February 2021.  A native of New Zealand
+and a self-described "huge geek," Kent was the author or maintainer of 178
+CPAN distributions, the Perl maintainer for the Gentoo Linux distribution and
+a contributor to the Perl core distribution.  He is mourned by his family,
+friends and open source software communities worldwide.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.34.0 represents approximately 11 months of development since Perl
+5.32.0 and contains approximately 280,000 lines of changes across 2,100
+files from 78 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 150,000 lines of changes to 1,300 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.34.0:
+.PP
+Aaron Crane, Adam Hartley, Andy Dougherty, Ben Cornett, Branislav
+Zahradník, brian d foy, Chris 'BinGOs' Williams, Christian Walde
+(Mithaldu), Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Book, Daniel
+Böhmer, Daniel Laügt, Dan Kogai, David Cantrell, David Mitchell, Dominic
+Hamon, E. Choroba, Ed J, Eric Herman, Eugene Alvin Villar,
+Felipe Gasper, Giovanni Tataranni, Graham Knop, Graham Ollis, Hauke D,
+H.Merijn Brand, Hugo van der Sanden, Ichinose Shogo, Ivan Baidakou, Jae
+Bradley, James E Keenan, Jason McIntosh, jkahrman, John Karr, John Lightsey,
+Kang-min Liu, Karen Etheridge, Karl Williamson, Keith Thompson, Leon
+Timmermans, Marc Reisner, Marcus Holland-Moritz, Max Maischein, Michael G
+Schwern, Nicholas Clark, Nicolas R., Paul Evans, Petr Písař, raiph, Renee
+Baecker, Ricardo Signes, Richard Leach, Romano, Ryan Voots, Samanta Navarro,
+Samuel Thibault, Sawyer X, Scott Baker, Sergey Poznyakoff, Sevan Janiyan,
+Shirakata Kentaro, Shlomi Fish, Sisyphus, Sizhe Zhao, Steve Hay, TAKAI
+Kousuke, Thibault Duponchelle, Todd Rinaldo, Tomasz Konojacki, Tom Hukins,
+Tom Stellard, Tony Cook, vividsnow, Yves Orton, Zakariyya Mughal,
+Михаил Козачков.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5341delta.1 b/upstream/mageia-cauldron/man1/perl5341delta.1
new file mode 100644
index 00000000..917b4651
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5341delta.1
@@ -0,0 +1,179 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5341DELTA 1"
+.TH PERL5341DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5341delta \- what is new for perl v5.34.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.34.0 release and the 5.34.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.33.0, first read
+perl5340delta, which describes differences between 5.33.0 and 5.34.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.34.0.  If any exist,
+they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.56 to 1.57.
+.IP \(bu 4
+Encode has been upgraded from version 3.08 to 3.08_01.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.19 to 1.19_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20210520 to 5.20220313.
+.IP \(bu 4
+perl5db.pl has been upgraded from version 1.60 to 1.60_01.
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP Windows 4
+.IX Item "Windows"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+Support for compiling perl on Windows using Microsoft Visual Studio 2022
+(containing Visual C++ 14.3) has been added.
+.RE
+.RS 4
+.RE
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+B::Deparse now correctly handles try/catch blocks with more complex scopes.
+[GH #18874 <https://github.com/Perl/perl5/issues/18874>]
+.IP \(bu 4
+try/catch now correctly returns the last evaluated expression when the catch
+block has more than one statement. [GH #18855 <https://github.com/Perl/perl5/issues/18855>]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.34.1 represents approximately 10 months of development since Perl 5.34.0
+and contains approximately 4,600 lines of changes across 60 files from 23
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,100 lines of changes to 18 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.34.1:
+.PP
+Andrew Fresh, Atsushi Sugawara, Chris 'BinGOs' Williams, Dan Book, Hugo van der
+Sanden, James E Keenan, Karen Etheridge, Leon Timmermans, Matthew Horsfall, Max
+Maischein, Michiel Beijen, Neil Bowers, Nicolas R., Paul Evans, Renee Baecker,
+Ricardo Signes, Richard Leach, Sawyer X, Sergey Poznyakoff, Steve Hay, Tomasz
+Konojacki, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5342delta.1 b/upstream/mageia-cauldron/man1/perl5342delta.1
new file mode 100644
index 00000000..1ae01e0c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5342delta.1
@@ -0,0 +1,160 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5342DELTA 1"
+.TH PERL5342DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5342delta \- what is new for perl v5.34.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.34.1 release and the 5.34.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.34.0, first read
+perl5341delta, which describes differences between 5.34.0 and 5.34.1.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.34.2 represents approximately 20 months of development since Perl
+5.34.1 and contains approximately 3,700 lines of changes across 40 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 2,800 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.34.2:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5343delta.1 b/upstream/mageia-cauldron/man1/perl5343delta.1
new file mode 100644
index 00000000..45dd53f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5343delta.1
@@ -0,0 +1,161 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5343DELTA 1"
+.TH PERL5343DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5343delta \- what is new for perl v5.34.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.34.1 release and the 5.34.3
+release.  \fBPlease note:\fR This document ignores Perl 5.34.2, a broken release
+which existed for a couple of days only.
+.PP
+If you are upgrading from an earlier release such as 5.34.0, first read
+perl5341delta, which describes differences between 5.34.0 and 5.34.1.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.34.3 represents approximately 1 month of development since Perl
+5.34.1 and contains approximately 3,700 lines of changes across 40 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 2,800 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.34.3:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5360delta.1 b/upstream/mageia-cauldron/man1/perl5360delta.1
new file mode 100644
index 00000000..9fa6762d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5360delta.1
@@ -0,0 +1,1254 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5360DELTA 1"
+.TH PERL5360DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5360delta \- what is new for perl v5.36.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.34.0 release and the 5.36.0
+release.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS """use v5.36"""
+.el .SS "\f(CWuse v5.36\fP"
+.IX Subsection "use v5.36"
+As always, \f(CW\*(C`use v5.36\*(C'\fR turns on the feature bundle for that version of Perl.
+.PP
+The 5.36 bundle enables the \f(CW\*(C`signatures\*(C'\fR feature.  Introduced in Perl version
+5.20.0, and modified several times since, the subroutine signatures feature is
+now no longer considered experimental. It is now considered a stable language
+feature and no longer prints a warning.
+.PP
+.Vb 1
+\&    use v5.36;
+\&
+\&    sub add ($x, $y) {
+\&      return $x + $y;
+\&    }
+.Ve
+.PP
+Despite this, certain elements of signatured subroutines remain experimental;
+see below.
+.PP
+The 5.36 bundle enables the \f(CW\*(C`isa\*(C'\fR feature.  Introduced in Perl version 5.32.0,
+this operator has remained unchanged since then. The operator is now considered
+a stable language feature.  For more detail see "Class Instance
+Operator" in perlop.
+.PP
+The 5.36 bundle also \fIdisables\fR the features \f(CW\*(C`indirect\*(C'\fR, and
+\&\f(CW\*(C`multidimensional\*(C'\fR.  These will forbid, respectively: the use of "indirect"
+method calls (like \f(CW\*(C`$x = new Class;\*(C'\fR); the use of a list expression as a hash
+key to simulate sparse multidimensional arrays.  The specifics of these changes
+can be found in feature, but the short version is: this is a bit like having
+more \f(CW\*(C`use strict\*(C'\fR turned on, disabling features that cause more trouble than
+they're worth.
+.PP
+Furthermore, \f(CW\*(C`use v5.36\*(C'\fR will also enable warnings as if you'd written \f(CW\*(C`use
+warnings\*(C'\fR.
+.PP
+Finally, with this release, the experimental \f(CW\*(C`switch\*(C'\fR feature, present in
+every feature bundle since they were introduced in v5.10, has been removed from
+the v5.36 bundle.  If you want to use it (against our advice), you'll have to
+enable it explicitly.
+.SS "\-g command-line flag"
+.IX Subsection "-g command-line flag"
+A new command-line flag, \-g, is available. It is a simpler alias for \-0777.
+.PP
+For more information, see "\-g" in perlrun.
+.SS "Unicode 14.0 is supported"
+.IX Subsection "Unicode 14.0 is supported"
+See <https://www.unicode.org/versions/Unicode14.0.0/> for details.
+.SS "regex sets are no longer considered experimental"
+.IX Subsection "regex sets are no longer considered experimental"
+Prior to this release, the regex sets feature (officially named
+"Extended Bracketed Character Classes") was considered experimental.
+Introduced in Perl version 5.18.0, and modified several times since,
+this is now considered a stable language feature and its use no longer
+prints a warning.  See "Extended Bracketed Character
+Classes" in perlrecharclass.
+.SS "Variable length lookbehind is mostly no longer considered experimental"
+.IX Subsection "Variable length lookbehind is mostly no longer considered experimental"
+Prior to this release, any form of variable length lookbehind was
+considered experimental. With this release the experimental status has
+been reduced to cover only lookbehind that contains capturing parenthesis.
+This is because it is not clear if
+.PP
+.Vb 1
+\&    "aaz"=~/(?=z)(?<=(a|aa))/
+.Ve
+.PP
+should match and leave \f(CW$1\fR equaling "a" or "aa". Currently it will match
+the longest possible alternative, "aa". While we are confident that the overall
+construct will now match only when it should, we are not confident that we
+will keep the current "longest match" behavior.
+.SS "SIGFPE no longer deferred"
+.IX Subsection "SIGFPE no longer deferred"
+Floating-point exceptions are now delivered immediately, in the same way
+as other "fault"\-like signals such as SIGSEGV. This means one has at
+least a chance to catch such a signal with a \f(CW$SIG{FPE}\fR handler, e.g.
+so that \f(CW\*(C`die\*(C'\fR can report the line in perl that triggered it.
+.SS "Stable boolean tracking"
+.IX Subsection "Stable boolean tracking"
+The "true" and "false" boolean values, often accessed by constructions like
+\&\f(CW\*(C`!!0\*(C'\fR and \f(CW\*(C`!!1\*(C'\fR, as well as being returned from many core functions and
+operators, now remember their boolean nature even through assignment into
+variables. The new function \f(CWis_bool()\fR in builtin can check whether
+a value has boolean nature.
+.PP
+This is likely to be useful when interoperating with other languages or
+data-type serialisation, among other places.
+.SS "iterating over multiple values at a time (experimental)"
+.IX Subsection "iterating over multiple values at a time (experimental)"
+You can now iterate over multiple values at a time by specifying a list of
+lexicals within parentheses. For example,
+.PP
+.Vb 2
+\&    for my ($key, $value) (%hash) { ... }
+\&    for my ($left, $right, $gripping) (@moties) { ... }
+.Ve
+.PP
+Prior to perl v5.36, attempting to specify a list after \f(CW\*(C`for my\*(C'\fR was a syntax
+error.
+.PP
+This feature is currently experimental and will cause a warning of category
+\&\f(CW\*(C`experimental::for_list\*(C'\fR.  For more detail see "Compound Statements" in perlsyn.
+See also "builtin::indexed" in this document, which is a handy companion to
+n\-at-a-time foreach.
+.SS "builtin functions (experimental)"
+.IX Subsection "builtin functions (experimental)"
+A new core module builtin has been added, which provides documentation for
+new always-present functions that are built into the interpreter.
+.PP
+.Vb 1
+\&    say "Reference type of arrays is ", builtin::reftype([]);
+.Ve
+.PP
+It also provides a lexical import mechanism for providing short name versions
+of these functions.
+.PP
+.Vb 2
+\&    use builtin \*(Aqreftype\*(Aq;
+\&    say "Reference type of arrays is ", reftype([]);
+.Ve
+.PP
+This builtin function mechanism and the functions it provides are all
+currently \fBexperimental\fR.  We expect that \f(CW\*(C`builtin\*(C'\fR itself will cease to be
+experimental in the near future, but that individual functions in it may become
+stable on an ongoing basis.  Other functions will be added to \f(CW\*(C`builtin\*(C'\fR over
+time.
+.PP
+For details, see builtin, but here's a summary of builtin functions in
+v5.36:
+.IP builtin::trim 4
+.IX Item "builtin::trim"
+This function treats its argument as a string, returning the result of removing
+all white space at its beginning and ending.
+.IP builtin::indexed 4
+.IX Item "builtin::indexed"
+This function returns a list twice as big as its argument list, where each item
+is preceded by its index within that list. This is primarily useful for using
+the new \f(CW\*(C`foreach\*(C'\fR syntax with multiple iterator variables to iterate over an
+array or list, while also tracking the index of each item:
+.Sp
+.Vb 1
+\&    use builtin \*(Aqindexed\*(Aq;
+\&
+\&    foreach my ($index, $val) (indexed @array) {
+\&        ...
+\&    }
+.Ve
+.IP "builtin::true, builtin::false, builtin::is_bool" 4
+.IX Item "builtin::true, builtin::false, builtin::is_bool"
+\&\f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR return boolean true and false values.  Perl is still perl,
+and doesn't have strict typing of booleans, but these values will be known to
+have been created as booleans.  \f(CW\*(C`is_bool\*(C'\fR will tell you whether a value was
+known to have been created as a boolean.
+.IP "builtin::weaken, builtin::unweaken, builtin::is_weak" 4
+.IX Item "builtin::weaken, builtin::unweaken, builtin::is_weak"
+These functions will, respectively: weaken a reference; strengthen a reference;
+and return whether a reference is weak.  (A weak reference is not counted for
+garbage collection purposes.  See perlref.)  These can take the place of
+some similar routines in Scalar::Util.
+.IP "builtin::blessed, builtin::refaddr, builtin::reftype" 4
+.IX Item "builtin::blessed, builtin::refaddr, builtin::reftype"
+These functions provide more data about references (or non-references,
+actually!) and can take the place of similar routines found in Scalar::Util.
+.IP "builtin::ceil, builtin::floor" 4
+.IX Item "builtin::ceil, builtin::floor"
+\&\f(CW\*(C`ceil\*(C'\fR returns the smallest integer greater than or equal to its argument.
+\&\f(CW\*(C`floor\*(C'\fR returns the largest integer less than or equal to its argument.  These
+can take the place of similar routines found in POSIX.
+.ie n .SS """defer"" blocks (experimental)"
+.el .SS "\f(CWdefer\fP blocks (experimental)"
+.IX Subsection "defer blocks (experimental)"
+This release adds support for \f(CW\*(C`defer\*(C'\fR blocks, which are blocks of code
+prefixed by the \f(CW\*(C`defer\*(C'\fR modifier. They provide a section of code which runs
+at a later time, during scope exit.
+.PP
+In brief, when a \f(CW\*(C`defer\*(C'\fR block is reached at runtime, its body is set aside to
+be run when the enclosing scope is exited.  It is unlike a UNITCHECK (among
+other reasons) in that if the block \fIcontaining\fR the \f(CW\*(C`defer\*(C'\fR block is exited
+before the block is reached, it will not be run.
+.PP
+\&\f(CW\*(C`defer\*(C'\fR blocks can be used to take the place of "scope guard" objects where an
+object is passed a code block to be run by its destructor.
+.PP
+For more information, see "defer blocks" in perlsyn.
+.ie n .SS "try/catch can now have a ""finally"" block (experimental)"
+.el .SS "try/catch can now have a \f(CWfinally\fP block (experimental)"
+.IX Subsection "try/catch can now have a finally block (experimental)"
+The experimental \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR syntax has been extended to support an
+optional third block introduced by the \f(CW\*(C`finally\*(C'\fR keyword.
+.PP
+.Vb 10
+\&    try {
+\&        attempt();
+\&        print "Success\en";
+\&    }
+\&    catch ($e) {
+\&        print "Failure\en";
+\&    }
+\&    finally {
+\&        print "This happens regardless\en";
+\&    }
+.Ve
+.PP
+This provides code which runs at the end of the \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR construct,
+even if aborted by an exception or control-flow keyword. They are similar
+to \f(CW\*(C`defer\*(C'\fR blocks.
+.PP
+For more information, see "Try Catch Exception Handling" in perlsyn.
+.SS "non-ASCII delimiters for quote-like operators (experimental)"
+.IX Subsection "non-ASCII delimiters for quote-like operators (experimental)"
+Perl traditionally has allowed just four pairs of string/pattern
+delimiters: \f(CW\*(C`(\ )\*(C'\fR \f(CW\*(C`{\ }\*(C'\fR \f(CW\*(C`[\ ]\*(C'\fR and \f(CW\*(C`<\ >\*(C'\fR, all in the
+ASCII range.  Unicode has hundreds more possibilities, and using this
+feature enables many of them.  When enabled, you can say \f(CW\*(C`qr«\ »\*(C'\fR for
+example, or \f(CW\*(C`use\ utf8;\ q�string�\*(C'\fR.  See "The
+\&'extra_paired_delimiters' feature" in feature for details.
+.ie n .SS "@_ is now experimental within signatured subs"
+.el .SS "\f(CW@_\fP is now experimental within signatured subs"
+.IX Subsection "@_ is now experimental within signatured subs"
+Even though subroutine signatures are now stable, use of the legacy arguments
+array (\f(CW@_\fR) with a subroutine that has a signature \fIremains\fR experimental,
+with its own warning category.  Silencing the \f(CW\*(C`experimental::signatures\*(C'\fR
+warning category is not sufficient to dismiss this.  The new warning is emitted
+with the category name \f(CW\*(C`experimental::args_array_with_signatures\*(C'\fR.
+.PP
+Any subroutine that has a signature and tries to make use of the defaults
+argument array or an element thereof (\f(CW@_\fR or \f(CW$_[INDEX]\fR), either
+explicitly or implicitly (such as \f(CW\*(C`shift\*(C'\fR or \f(CW\*(C`pop\*(C'\fR with no argument) will
+provoke a warning at compile-time:
+.PP
+.Vb 1
+\&    use v5.36;
+\&
+\&    sub f ($x, $y = 123) {
+\&      say "The first argument is $_[0]";
+\&    }
+.Ve
+.PP
+
+.PP
+.Vb 2
+\&    Use of @_ in array element with signatured subroutine is experimental
+\&    at file.pl line 4.
+.Ve
+.PP
+The behaviour of code which attempts to do this is no longer specified, and
+may be subject to change in a future version.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "A physically empty sort is now a compile-time error"
+.IX Subsection "A physically empty sort is now a compile-time error"
+.Vb 3
+\&    @a = sort @empty; # unaffected
+\&    @a = sort;        # now a compile\-time error
+\&    @a = sort ();     # also a compile\-time error
+.Ve
+.PP
+A bare sort used to be a weird way to create an empty list; now it croaks
+at compile time. This change is intended to free up some of the syntax space
+for possible future enhancements to \f(CW\*(C`sort\*(C'\fR.
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS """use VERSION"" (where VERSION is below v5.11) after ""use v5.11"" is deprecated"
+.el .SS "\f(CWuse VERSION\fP (where VERSION is below v5.11) after \f(CWuse v5.11\fP is deprecated"
+.IX Subsection "use VERSION (where VERSION is below v5.11) after use v5.11 is deprecated"
+When in the scope of \f(CW\*(C`use v5.11\*(C'\fR or later, a \f(CW\*(C`use vX\*(C'\fR line where \fIX\fR is
+lower than v5.11 will now issue a warning:
+.PP
+.Vb 1
+\&    Downgrading a use VERSION declaration to below v5.11 is deprecated
+.Ve
+.PP
+For example:
+.PP
+.Vb 4
+\&    use v5.14;
+\&    say "The say statement is permitted";
+\&    use v5.8;                               # This will print a warning
+\&    print "We must use print\en";
+.Ve
+.PP
+This is because the Perl team plans to change the behavior in this case.  Since
+Perl v5.12 (and parts of v5.11), strict is enabled \fIunless it had previously
+been disabled\fR.  In other words:
+.PP
+.Vb 3
+\&    no strict;
+\&    use v5.12;  # will not enable strict, because "no strict" preceded it
+\&    $x = 1;     # permitted, despite no "my" declaration
+.Ve
+.PP
+In the future, this behavior will be eliminated and \f(CW\*(C`use VERSION\*(C'\fR will
+\&\fIalways\fR enable strict for versions v5.12 and later.
+.PP
+Code which wishes to mix versions in this manner should use lexical scoping
+with block syntax to ensure that the differently versioned regions remain
+lexically isolated.
+.PP
+.Vb 4
+\&    {
+\&        use v5.14;
+\&        say "The say statement is permitted";
+\&    }
+\&
+\&    {
+\&        use v5.8;                           # No warning is emitted
+\&        print "We must use print\en";
+\&    }
+.Ve
+.PP
+Of course, this is probably not something you ever need to do!  If the first
+block compiles, it means you're using perl v5.14.0 or later.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+We now probe for compiler support for C11 thread local storage, and where
+available use this for "implicit context" for XS extensions making API calls for
+a threaded Perl build.  This requires fewer function calls at the C level than
+POSIX thread specific storage. We continue to use the pthreads approach if
+the C11 approach is not available.
+.Sp
+\&\fIConfigure\fR run with the defaults will build an unthreaded Perl (which is
+slightly faster), but most operating systems ship a threaded Perl.
+.IP \(bu 4
+Perl can now be configured to no longer allocate keys for large hashes
+from the shared string table.
+.Sp
+The same internal datatype (\f(CW\*(C`PVHV\*(C'\fR) is used for all of
+.RS 4
+.IP \(bu 4
+Symbol tables
+.IP \(bu 4
+Objects (by default)
+.IP \(bu 4
+Associative arrays
+.RE
+.RS 4
+.Sp
+The shared string table was originally added to improve performance for blessed
+hashes used as objects, because every object instance has the same keys, so it
+is an optimisation to share memory between them. It also makes sense for symbol
+tables, where derived classes will have the same keys (typically method names),
+and the OP trees built for method calls can also share memory. The shared
+string table behaves roughly like a cache for hash keys.
+.Sp
+But for hashes actually used as associative arrays \- mapping keys to values \-
+typically the keys are not re-used in other hashes. For example, "seen" hashes
+are keyed by object IDs (or addresses), and logically these keys won't repeat
+in other hashes.
+.Sp
+Storing these "used just once" keys in the shared string table increases CPU
+and RAM use for no gain. For such keys the shared string table behaves as a
+cache with a 0% hit rate. Storing all the keys there increases the total size
+of the shared string table, as well as increasing the number of times it is
+resized as it grows. \fBWorse\fR \- in any environment that has "copy on write"
+memory for child process (such as a pre-forking server), the memory pages used
+for the shared string table rapidly need to be copied as the child process
+manipulates hashes. Hence if most of the shared string table is such that keys
+are used only in one place, there is no benefit from re-use within the perl
+interpreter, but a high cost due to more pages for the OS to copy.
+.Sp
+The perl interpreter can now be Configured to disable shared hash keys
+for "large" hashes (that are neither objects nor symbol tables).  To do
+so, add \f(CW\*(C`\-Accflags=\*(Aq\-DPERL_USE_UNSHARED_KEYS_IN_LARGE_HASHES\*(Aq\*(C'\fR to
+your \fIConfigure\fR options.  "Large" is a heuristic \-\- currently the
+heuristic is that sharing is disabled when adding a key to a hash
+triggers allocation of more storage, and the hash has more than 42 keys.
+.Sp
+This \fBmight\fR cause slightly increased memory usage for programs that create
+(unblessed) data structures that contain multiple large hashes that share the
+same keys. But generally our testing suggests that for the specific cases
+described it is a win, and other code is unaffected.
+.RE
+.IP \(bu 4
+In certain scenarios, creation of new scalars is now noticeably faster.
+.Sp
+For example, the following code is now executing ~30% faster:
+.Sp
+.Vb 4
+\&    $str = "A" x 64;
+\&    for (0..1_000_000) {
+\&        @svs = split //, $str
+\&    }
+.Ve
+.Sp
+(You can read more about this one in [perl
+#19414] <https://github.com/Perl/perl5/pull/19414>.)
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Archive::Tar has been upgraded from version 2.38 to 2.40.
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+attributes has been upgraded from version 0.33 to 0.34.
+.IP \(bu 4
+B has been upgraded from version 1.82 to 1.83.
+.IP \(bu 4
+B::Concise has been upgraded from version 1.004 to 1.006.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.56 to 1.64.
+.IP \(bu 4
+bignum has been upgraded from version 0.51 to 0.65.
+.IP \(bu 4
+charnames has been upgraded from version 1.48 to 1.50.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.101 to 2.103.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.101 to 2.105.
+.IP \(bu 4
+CPAN has been upgraded from version 2.28 to 2.33.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.179 to 2.184.
+.IP \(bu 4
+DB_File has been upgraded from version 1.855 to 1.857.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.30 to 1.32.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.62 to 3.68.
+.IP \(bu 4
+diagnostics has been upgraded from version 1.37 to 1.39.
+.IP \(bu 4
+Digest has been upgraded from version 1.19 to 1.20.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.50 to 1.52.
+.IP \(bu 4
+Encode has been upgraded from version 3.08 to 3.17.
+.IP \(bu 4
+Errno has been upgraded from version 1.33 to 1.36.
+.IP \(bu 4
+experimental has been upgraded from version 0.024 to 0.028.
+.IP \(bu 4
+Exporter has been upgraded from version 5.76 to 5.77.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.62 to 7.64.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.10 to 1.11.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.43 to 3.45.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.43 to 3.45.
+.IP \(bu 4
+Fcntl has been upgraded from version 1.14 to 1.15.
+.IP \(bu 4
+feature has been upgraded from version 1.64 to 1.72.
+.IP \(bu 4
+File::Compare has been upgraded from version 1.1006 to 1.1007.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.35 to 2.39.
+.IP \(bu 4
+File::Fetch has been upgraded from version 1.00 to 1.04.
+.IP \(bu 4
+File::Find has been upgraded from version 1.39 to 1.40.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.33 to 1.37.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.80 to 3.84.
+.IP \(bu 4
+File::stat has been upgraded from version 1.09 to 1.12.
+.IP \(bu 4
+FindBin has been upgraded from version 1.52 to 1.53.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.19 to 1.23.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.25 to 0.28.
+.IP \(bu 4
+Hash::Util::FieldHash has been upgraded from version 1.21 to 1.26.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.076 to 0.080.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.19 to 0.21.
+.IP \(bu 4
+if has been upgraded from version 0.0609 to 0.0610.
+.IP \(bu 4
+IO has been upgraded from version 1.46 to 1.50.
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.102 to 2.106.
+.IP \(bu 4
+IPC::Open3 has been upgraded from version 1.21 to 1.22.
+.IP \(bu 4
+JSON::PP has been upgraded from version 4.06 to 4.07.
+.IP \(bu 4
+libnet has been upgraded from version 3.13 to 3.14.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.29 to 1.31.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999818 to 1.999830.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.5009 to 0.5012.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2614 to 0.2621.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20210520 to 5.20220520.
+.IP \(bu 4
+mro has been upgraded from version 1.25_001 to 1.26.
+.IP \(bu 4
+NEXT has been upgraded from version 0.68 to 0.69.
+.IP \(bu 4
+Opcode has been upgraded from version 1.50 to 1.57.
+.IP \(bu 4
+open has been upgraded from version 1.12 to 1.13.
+.IP \(bu 4
+overload has been upgraded from version 1.33 to 1.35.
+.IP \(bu 4
+perlfaq has been upgraded from version 5.20210411 to 5.20210520.
+.IP \(bu 4
+PerlIO has been upgraded from version 1.11 to 1.12.
+.IP \(bu 4
+Pod::Functions has been upgraded from version 1.13 to 1.14.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.27 to 1.33.
+.IP \(bu 4
+Pod::Simple has been upgraded from version 3.42 to 3.43.
+.IP \(bu 4
+POSIX has been upgraded from version 1.97 to 2.03.
+.IP \(bu 4
+re has been upgraded from version 0.41 to 0.43.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.55 to 1.62.
+.IP \(bu 4
+sigtrap has been upgraded from version 1.09 to 1.10.
+.IP \(bu 4
+Socket has been upgraded from version 2.031 to 2.033.
+.IP \(bu 4
+sort has been upgraded from version 2.04 to 2.05.
+.IP \(bu 4
+Storable has been upgraded from version 3.23 to 3.26.
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.23 to 1.24.
+.IP \(bu 4
+Test::Harness has been upgraded from version 3.43 to 3.44.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302183 to 1.302190.
+.IP \(bu 4
+Text::ParseWords has been upgraded from version 3.30 to 3.31.
+.IP \(bu 4
+Text::Tabs has been upgraded from version 2013.0523 to 2021.0814.
+.IP \(bu 4
+Text::Wrap has been upgraded from version 2013.0523 to 2021.0814.
+.IP \(bu 4
+threads has been upgraded from version 2.26 to 2.27.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.62 to 1.64.
+.IP \(bu 4
+Tie::Handle has been upgraded from version 4.2 to 4.3.
+.IP \(bu 4
+Tie::Hash has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+Tie::Scalar has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+Tie::SubstrHash has been upgraded from version 1.00 to 1.01.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9767 to 1.9770.
+.IP \(bu 4
+Unicode::Collate has been upgraded from version 1.29 to 1.31.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.28 to 1.31.
+.IP \(bu 4
+Unicode::UCD has been upgraded from version 0.75 to 0.78.
+.IP \(bu 4
+UNIVERSAL has been upgraded from version 1.13 to 1.14.
+.IP \(bu 4
+version has been upgraded from version 0.9928 to 0.9929.
+.IP \(bu 4
+VMS::Filespec has been upgraded from version 1.12 to 1.13.
+.IP \(bu 4
+VMS::Stdio has been upgraded from version 2.45 to 2.46.
+.IP \(bu 4
+warnings has been upgraded from version 1.51 to 1.58.
+.IP \(bu 4
+Win32 has been upgraded from version 0.57 to 0.59.
+.IP \(bu 4
+XS::APItest has been upgraded from version 1.16 to 1.22.
+.IP \(bu 4
+XS::Typemap has been upgraded from version 0.18 to 0.19.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.30 to 0.31.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIPorting/vote_admin_guide.pod\fR
+.IX Subsection "Porting/vote_admin_guide.pod"
+.PP
+This document provides the process for administering an election or vote
+within the Perl Core Team.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, open an issue
+at <https://github.com/Perl/perl5/issues>.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+This has been cleaned up some, and more than 80% of the (previously
+many) undocumented functions have now either been documented or deemed
+to have been inappropriately marked as API.
+.Sp
+As always, Patches Welcome!
+.PP
+\fIperldeprecation\fR
+.IX Subsection "perldeprecation"
+.IP \(bu 4
+notes the new location for functions moved from Pod::Html to
+Pod::Html::Util that are no longer intended to be used outside of core.
+.PP
+\fIperlexperiment\fR
+.IX Subsection "perlexperiment"
+.IP \(bu 4
+notes the \f(CW\*(C`:win32\*(C'\fR IO pseudolayer is removed (this happened in 5.35.2).
+.PP
+\fIperlgov\fR
+.IX Subsection "perlgov"
+.IP \(bu 4
+The election process has been finetuned to allow the vote to be skipped if there
+are no more candidates than open seats.
+.IP \(bu 4
+A special election is now allowed to be postponed for up to twelve weeks, for
+example until a normal election.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+now notes that an invocant only needs to be an object or class name
+for method calls, not for subroutine references.
+.PP
+\fIperlre\fR
+.IX Subsection "perlre"
+.IP \(bu 4
+Updated to discourage the use of the /d regexp modifier.
+.PP
+\fIperlrun\fR
+.IX Subsection "perlrun"
+.IP \(bu 4
+\&\fB\-?\fR is now a synonym for \fB\-h\fR
+.IP \(bu 4
+\&\fB\-g\fR is now a synonym for \fB\-0777\fR
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+Can't "%s" out of a "defer" block
+.Sp
+(F) An attempt was made to jump out of the scope of a defer block by using
+a control-flow statement such as \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`goto\*(C'\fR or a loop control. This is
+not permitted.
+.IP \(bu 4
+Can't modify \f(CW%s\fR in \f(CW%s\fR (for scalar
+assignment to \f(CW\*(C`undef\*(C'\fR)
+.Sp
+Attempting to perform a scalar assignment to \f(CW\*(C`undef\*(C'\fR, for example via
+\&\f(CW\*(C`undef = $foo;\*(C'\fR, previously triggered a fatal runtime error with the
+message "Modification of a read-only value attempted."
+It is more helpful to detect such attempted assignments prior to runtime, so
+they are now compile time errors, resulting in the message "Can't modify undef
+operator in scalar assignment".
+.IP \(bu 4
+panic: newFORLOOP, \f(CW%s\fR
+.Sp
+The parser failed an internal consistency check while trying to parse
+a \f(CW\*(C`foreach\*(C'\fR loop.
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Built-in function '%s' is experimental
+.Sp
+A call is being made to a function in the \f(CW\*(C`builtin::\*(C'\fR namespace, which is
+currently experimental.
+.IP \(bu 4
+defer is experimental
+.Sp
+The \f(CW\*(C`defer\*(C'\fR block modifier is experimental. If you want to use the feature,
+disable the warning with \f(CW\*(C`no warnings \*(Aqexperimental::defer\*(Aq\*(C'\fR, but know that in
+doing so you are taking the risk that your code may break in a future Perl
+version.
+.IP \(bu 4
+Downgrading a use VERSION declaration to below v5.11 is deprecated
+.Sp
+This warning is emitted on a \f(CW\*(C`use VERSION\*(C'\fR statement that
+requests a version below v5.11 (when the effects of \f(CW\*(C`use strict\*(C'\fR would be
+disabled), after a previous declaration of one having a larger number (which
+would have enabled these effects)
+.IP \(bu 4
+for my (...) is experimental
+.Sp
+This warning is emitted if you use \f(CW\*(C`for\*(C'\fR to iterate multiple values at
+a time. This syntax is currently experimental and its behaviour may
+change in future releases of Perl.
+.IP \(bu 4
+Implicit use of \f(CW@_\fR in \f(CW%s\fR with signatured subroutine is experimental
+.Sp
+An expression that implicitly involves the \f(CW@_\fR arguments array was found in
+a subroutine that uses a signature.
+.IP \(bu 4
+Use of \f(CW@_\fR in \f(CW%s\fR with signatured subroutine is experimental
+.Sp
+An expression involving the \f(CW@_\fR arguments array was found in a subroutine that uses a signature.
+.IP \(bu 4
+Wide character in \f(CW$0\fR
+.Sp
+Attempts to put wide characters into the program name (\f(CW$0\fR) now provoke this
+warning.
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+\&'/' does not take a repeat count in \f(CW%s\fR
+.Sp
+This warning used to not include the \f(CW\*(C`in %s\*(C'\fR.
+.IP \(bu 4
+Subroutine \f(CW%s\fR redefined
+.Sp
+Localized subroutine redefinitions no longer trigger this warning.
+.IP \(bu 4
+unexpected constant lvalue entersub entry via type/targ \f(CW%d:\fR%d" now has a panic prefix
+.Sp
+This makes it consistent with other checks of internal consistency when
+compiling a subroutine.
+.IP \(bu 4
+Useless use of sort in scalar context is now in the new \f(CW\*(C`scalar\*(C'\fR category.
+.Sp
+When \f(CW\*(C`sort\*(C'\fR is used in scalar context, it provokes a warning that doing this
+is not useful. This warning used to be in the \f(CW\*(C`void\*(C'\fR category. A new category
+for warnings about scalar context has now been added, called \f(CW\*(C`scalar\*(C'\fR.
+.IP \(bu 4
+Removed a number of diagnostics
+.Sp
+Many diagnostics that have been removed from the perl core across many years
+have now \fIalso\fR been removed from the documentation.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+The Perl C source code now uses some C99 features, which we have verified are
+supported by all compilers we target. This means that Perl's headers now
+contain some code that is legal in C99 but not C89.
+.Sp
+This may cause problems for some XS modules that unconditionally add
+\&\f(CW\*(C`\-Werror=declaration\-after\-statement\*(C'\fR to their C compiler flags if compiling
+with gcc or clang. Earlier versions of Perl support long obsolete compilers
+that are strict in rejecting certain C99 features, particularly mixed
+declarations and code, and hence it makes sense for XS module authors to audit
+that their code does not violate this. However, doing this is now only
+possible on these earlier versions of Perl, hence these modules need to be
+changed to only add this flag for \f(CW\*(C`$] < 5.035005\*(C'\fR.
+.IP \(bu 4
+The makedepend step is now run in parallel by using make
+.Sp
+When using MAKEFLAGS=\-j8, this significantly reduces the time required for:
+.Sp
+.Vb 1
+\&    sh ./makedepend MAKE=make cflags
+.Ve
+.IP \(bu 4
+\&\fIConfigure\fR now tests whether \f(CW\*(C`#include <xlocale.h>\*(C'\fR is required
+to use the POSIX 1003 thread-safe locale functions or some related
+extensions.  This prevents problems where a non-public \fIxlocale.h\fR is
+removed in a library update, or \fIxlocale.h\fR isn't intended for public
+use. (github #18936 <https://github.com/Perl/perl5/pull/18936>)
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes
+in this release.
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS Windows
+.IX Subsection "Windows"
+.IP \(bu 4
+Support for old MSVC++ (pre\-VC12) has been removed
+.Sp
+These did not support C99 and hence can no longer be used to compile perl.
+.IP \(bu 4
+Support for compiling perl on Windows using Microsoft Visual Studio 2022
+(containing Visual C++ 14.3) has been added.
+.IP \(bu 4
+The :win32 IO layer has been removed. This experimental replacement for the
+:unix layer never reached maturity in its nearly two decades of existence.
+.SS VMS
+.IX Subsection "VMS"
+.ie n .IP """keys %ENV"" on VMS returns consistent results" 4
+.el .IP "\f(CWkeys %ENV\fR on VMS returns consistent results" 4
+.IX Item "keys %ENV on VMS returns consistent results"
+On VMS entries in the \f(CW%ENV\fR hash are loaded from the OS environment on
+first access, hence the first iteration of \f(CW%ENV\fR requires the entire
+environment to be scanned to find all possible keys. This initialisation had
+always been done correctly for full iteration, but previously was not
+happening for \f(CW%ENV\fR in scalar context, meaning that \f(CW\*(C`scalar %ENV\*(C'\fR would
+return 0 if called before any other \f(CW%ENV\fR access, or would only return the
+count of keys accessed if there had been no iteration.
+.Sp
+These bugs are now fixed \- \f(CW%ENV\fR and \f(CW\*(C`keys %ENV\*(C'\fR in scalar context now
+return the correct result \- the count of all keys in the environment.
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP "AT&T UWIN" 4
+.IX Item "AT&T UWIN"
+UWIN is a UNIX compatibility layer for Windows.  It was last released
+in 2012 and has been superseded by Cygwin these days.
+.IP DOS/DJGPP 4
+.IX Item "DOS/DJGPP"
+DJGPP is a port of the GNU toolchain to 32\-bit x86 systems running
+DOS.  The last known attempt to build Perl on it was on 5.20, which
+only got as far as building miniperl.
+.IP NetWare 4
+.IX Item "NetWare"
+Support code for Novell NetWare has been removed.  NetWare was a
+server operating system by Novell.  The port was last updated in July
+2002, and the platform itself in May 2009.
+.Sp
+Unrelated changes accidentally broke the build for the NetWare port in
+September 2009, and in 12 years no-one has reported this.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP z/OS 4
+.IX Item "z/OS"
+This update enables us to build EBCDIC static/dynamic and 31\-bit/64\-bit
+addressing mode Perl. The number of tests that pass is consistent with the
+baseline before these updates.
+.Sp
+These changes also provide the base support to be able to provide ASCII
+static/dynamic and 31\-bit/64\-bit addressing mode Perl.
+.Sp
+The z/OS (previously called OS/390) README was updated to describe ASCII and
+EBCDIC builds.
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Since the removal of PERL_OBJECT in Perl 5.8, PERL_IMPLICIT_CONTEXT and
+MULTIPLICITY have been synonymous and they were being used interchangeably.
+To simplify the code, all instances of PERL_IMPLICIT_CONTEXT have been
+replaced with MULTIPLICITY.
+.Sp
+PERL_IMPLICIT_CONTEXT will remain defined for compatibility with XS modules.
+.IP \(bu 4
+The API constant formerly named \f(CW\*(C`G_ARRAY\*(C'\fR, indicating list context, has now
+been renamed to a more accurate \f(CW\*(C`G_LIST\*(C'\fR.  A compatibilty macro \f(CW\*(C`G_ARRAY\*(C'\fR has
+been added to allow existing code to work unaffected.  New code should be
+written using the new constant instead.  This is supported by \f(CW\*(C`Devel::PPPort\*(C'\fR
+version 3.63.
+.IP \(bu 4
+Macros have been added to \fIperl.h\fR to facilitate version comparisons:
+\&\f(CW\*(C`PERL_GCC_VERSION_GE\*(C'\fR, \f(CW\*(C`PERL_GCC_VERSION_GT\*(C'\fR, \f(CW\*(C`PERL_GCC_VERSION_LE\*(C'\fR and
+\&\f(CW\*(C`PERL_GCC_VERSION_LT\*(C'\fR.
+.Sp
+Inline functions have been added to \fIembed.h\fR to determine the position of
+the least significant 1 bit in a word: \f(CW\*(C`lsbit_pos32\*(C'\fR and \f(CW\*(C`lsbit_pos64\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Perl_ptr_table_clear\*(C'\fR has been deleted. This has been marked as deprecated
+since v5.14.0 (released in 2011), and is not used by any code on CPAN.
+.IP \(bu 4
+Added new boolean macros and functions. See "Stable boolean tracking" for
+related information and perlapi for documentation.
+.RS 4
+.IP \(bu 4
+sv_setbool
+.IP \(bu 4
+sv_setbool_mg
+.IP \(bu 4
+SvIsBOOL
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Added 4 missing functions for dealing with RVs:
+.RS 4
+.IP \(bu 4
+sv_setrv_noinc
+.IP \(bu 4
+sv_setrv_noinc_mg
+.IP \(bu 4
+sv_setrv_inc
+.IP \(bu 4
+sv_setrv_inc_mg
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CWxs_handshake()\fR's two failure modes now provide distinct messages.
+.IP \(bu 4
+Memory for hash iterator state (\f(CW\*(C`struct xpvhv_aux\*(C'\fR) is now allocated as part
+of the hash body, instead of as part of the block of memory allocated for the
+main hash array.
+.IP \(bu 4
+A new \fBphase_name()\fR interface provides access to the name for each interpreter
+phase (i.e., PL_phase value).
+.IP \(bu 4
+The \f(CW\*(C`pack\*(C'\fR behavior of \f(CW\*(C`U\*(C'\fR has changed for EBCDIC.
+.IP \(bu 4
+New equality-test functions \f(CW\*(C`sv_numeq\*(C'\fR and \f(CW\*(C`sv_streq\*(C'\fR have been added, along
+with \f(CW\*(C`..._flags\*(C'\fR\-suffixed variants.  These expose a simple and consistent API
+to perform numerical or string comparison which is aware of operator
+overloading.
+.IP \(bu 4
+Reading the string form of an integer value no longer sets the flag \f(CW\*(C`SVf_POK\*(C'\fR.
+The string form is still cached internally, and still re-read directly by the
+macros \f(CWSvPV(sv)\fR \fIetc\fR (inline, without calling a C function). XS code that
+already calls the APIs to get values will not be affected by this change. XS
+code that accesses flags directly instead of using API calls to express its
+intent \fImight\fR break, but such code likely is already buggy if passed some
+other values, such as floating point values or objects with string overloading.
+.Sp
+This small change permits code (such as JSON serializers) to reliably determine
+between
+.RS 4
+.IP \(bu 4
+a value that was initially \fBwritten\fR as an integer, but then \fBread\fR as a string
+.Sp
+.Vb 2
+\&    my $answer = 42;
+\&    print "The answer is $answer\en";
+.Ve
+.IP \(bu 4
+that same value that was initially \fBwritten\fR as a string, but then \fBread\fR as an integer
+.Sp
+.Vb 3
+\&    my $answer = "42";
+\&    print "That doesn\*(Aqt look right\en"
+\&        unless $answer == 6 * 9;
+.Ve
+.RE
+.RS 4
+.Sp
+For the first case (originally written as an integer), we now have:
+.Sp
+.Vb 6
+\&    use Devel::Peek;
+\&    my $answer = 42;
+\&    Dump ($answer);
+\&    my $void = "$answer";
+\&    print STDERR "\en";
+\&    Dump($answer)
+\&
+\&
+\&    SV = IV(0x562538925778) at 0x562538925788
+\&      REFCNT = 1
+\&      FLAGS = (IOK,pIOK)
+\&      IV = 42
+\&
+\&    SV = PVIV(0x5625389263c0) at 0x562538925788
+\&      REFCNT = 1
+\&      FLAGS = (IOK,pIOK,pPOK)
+\&      IV = 42
+\&      PV = 0x562538919b50 "42"\e0
+\&      CUR = 2
+\&      LEN = 10
+.Ve
+.Sp
+For the second (originally written as a string), we now have:
+.Sp
+.Vb 6
+\&    use Devel::Peek;
+\&    my $answer = "42";
+\&    Dump ($answer);
+\&    my $void = $answer == 6 * 9;
+\&    print STDERR "\en";
+\&    Dump($answer)\*(Aq
+\&
+\&
+\&    SV = PV(0x5586ffe9bfb0) at 0x5586ffec0788
+\&      REFCNT = 1
+\&      FLAGS = (POK,IsCOW,pPOK)
+\&      PV = 0x5586ffee7fd0 "42"\e0
+\&      CUR = 2
+\&      LEN = 10
+\&      COW_REFCNT = 1
+\&
+\&    SV = PVIV(0x5586ffec13c0) at 0x5586ffec0788
+\&      REFCNT = 1
+\&      FLAGS = (IOK,POK,IsCOW,pIOK,pPOK)
+\&      IV = 42
+\&      PV = 0x5586ffee7fd0 "42"\e0
+\&      CUR = 2
+\&      LEN = 10
+\&      COW_REFCNT = 1
+.Ve
+.Sp
+(One can't rely on the presence or absence of the flag \f(CW\*(C`SVf_IsCOW\*(C'\fR to
+determine the history of operations on a scalar.)
+.Sp
+Previously both cases would be indistinguishable, with all 4 flags set:
+.Sp
+.Vb 7
+\&    SV = PVIV(0x55d4d62edaf0) at 0x55d4d62f0930
+\&      REFCNT = 1
+\&      FLAGS = (IOK,POK,pIOK,pPOK)
+\&      IV = 42
+\&      PV = 0x55d4d62e1740 "42"\e0
+\&      CUR = 2
+\&      LEN = 10
+.Ve
+.Sp
+(and possibly \f(CW\*(C`SVf_IsCOW\*(C'\fR, but not always)
+.Sp
+This now means that if XS code \fIreally\fR needs to determine which form a value
+was first written as, it should implement logic roughly
+.Sp
+.Vb 6
+\&    if (flags & SVf_IOK|SVf_NOK) && !(flags & SVf_POK)
+\&        serialize as number
+\&    else if (flags & SVf_POK)
+\&        serialize as string
+\&    else
+\&        the existing guesswork ...
+.Ve
+.Sp
+Note that this doesn't cover "dualvars" \- scalars that report different
+values when asked for their string form or number form (such as \f(CW$!\fR).
+Most serialization formats cannot represent such duplicity.
+.Sp
+\&\fIThe existing guesswork\fR remains because as well as dualvars, values might
+be \f(CW\*(C`undef\*(C'\fR, references, overloaded references, typeglobs and other things that
+Perl itself can represent but do not map one-to-one into external formats, so
+need some amount of approximation or encapsulation.
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`sv_dump\*(C'\fR (and Devel::Peek’s \f(CW\*(C`Dump\*(C'\fR function) now escapes high-bit
+octets in the PV as hex rather than octal. Since most folks understand hex
+more readily than octal, this should make these dumps a bit more legible.
+This does \fBnot\fR affect any other diagnostic interfaces like \f(CW\*(C`pv_display\*(C'\fR.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+\&\fButime()\fR now correctly sets errno/\f(CW$!\fR when called on a closed handle.
+.IP \(bu 4
+The flags on the OPTVAL parameter to \fBsetsockopt()\fR were previously
+checked before magic was called, possibly treating a numeric value as
+a packed buffer or vice versa.  It also ignored the UTF\-8 flag,
+potentially treating the internal representation of an upgraded SV as
+the bytes to supply to the \fBsetsockopt()\fR system call.  (github #18660 <https://github.com/Perl/perl5/issues/18660>)
+.IP \(bu 4
+Only set IOKp, not IOK on $) and $(.
+This was issue #18955 <https://github.com/Perl/perl5/issues/18955>: This will prevent serializers from serializing these
+variables as numbers (which loses the additional groups).
+This restores behaviour from 5.16
+.IP \(bu 4
+Use of the \f(CW\*(C`mktables\*(C'\fR debugging facility would cause perl to croak since
+v5.31.10; this problem has now been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`makedepend\*(C'\fR logic is now compatible with BSD make (fixes
+GH #19046 <https://github.com/Perl/perl5/issues/19046>).
+.IP \(bu 4
+Calling \f(CW\*(C`untie\*(C'\fR on a tied hash that is partway through iteration now frees the
+iteration state immediately.
+.Sp
+Iterating a tied hash causes perl to store a copy of the current hash key to
+track the iteration state, with this stored copy passed as the second parameter
+to \f(CW\*(C`NEXTKEY\*(C'\fR. This internal state is freed immediately when tie hash iteration
+completes, or if the hash is destroyed, but due to an implementation oversight,
+it was not freed if the hash was untied. In that case, the internal copy of the
+key would persist until the earliest of
+.RS 4
+.IP 1. 4
+\&\f(CW\*(C`tie\*(C'\fR was called again on the same hash
+.IP 2. 4
+The (now untied) hash was iterated (ie passed to any of \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR or
+\&\f(CW\*(C`each\*(C'\fR)
+.IP 3. 4
+The hash was destroyed.
+.RE
+.RS 4
+.Sp
+This inconsistency is now fixed \- the internal state is now freed immediately by
+\&\f(CW\*(C`untie\*(C'\fR.
+.Sp
+As the precise timing of this behaviour can be observed with pure Perl code
+(the timing of \f(CW\*(C`DESTROY\*(C'\fR on objects returned from \f(CW\*(C`FIRSTKEY\*(C'\fR and \f(CW\*(C`NEXTKEY\*(C'\fR)
+it's just possible that some code is sensitive to it.
+.RE
+.IP \(bu 4
+The \f(CWInternals::getcwd()\fR function added for bootstrapping miniperl
+in perl 5.30.0 is now only available in miniperl. [github #19122]
+.IP \(bu 4
+Setting a breakpoint on a BEGIN or equivalently a \f(CW\*(C`use\*(C'\fR statement
+could cause a memory write to a freed \f(CW\*(C`dbstate\*(C'\fR op.
+[GH #19198 <https://github.com/Perl/perl5/issues/19198>]
+.IP \(bu 4
+When bareword filehandles are disabled, the parser was interpreting
+any bareword as a filehandle, even when immediatey followed by parens.
+.SH "Errata From Previous Releases"
+.IX Header "Errata From Previous Releases"
+.IP \(bu 4
+perl5300delta mistakenly identified a CVE whose correct identification is
+CVE\-2015\-1592.
+.SH Obituaries
+.IX Header "Obituaries"
+Raun "Spider" Boardman (SPIDB on CPAN), author of at least 66 commits to the
+Perl 5 core distribution between 1996 and 2002, passed away May 24, 2021 from
+complications of COVID.  He will be missed.
+.PP
+David H. Adler (DHA) passed away on November 16, 2021.  In 1997, David
+co-founded NY.pm, the first Perl user group, and in 1998 co-founded Perl
+Mongers to help establish other user groups across the globe.  He was a
+frequent attendee at Perl conferences in both North America and Europe and well
+known for his role in organizing \fIBad Movie Night\fR celebrations at those
+conferences.  He also contributed to the work of the Perl Foundation, including
+administering the White Camel awards for community service.  He will be missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.36.0 represents approximately a year of development since Perl
+5.34.0 and contains approximately 250,000 lines of changes across 2,000
+files from 82 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 190,000 lines of changes to 1,300 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.36.0:
+.PP
+Alyssa Ross, Andrew Fresh, Aristotle Pagaltzis, Asher Mancinelli, Atsushi
+Sugawara, Ben Cornett, Bernd, Biswapriyo Nath, Brad Barden, Bram, Branislav
+Zahradník, brian d foy, Chad Granum, Chris 'BinGOs' Williams, Christian
+Walde (Mithaldu), Christopher Yeleighton, Craig A. Berry, cuishuang, Curtis
+Poe, Dagfinn Ilmari Mannsåker, Dan Book, Daniel Laügt, Dan Jacobson, Dan
+Kogai, Dave Cross, Dave Lambley, David Cantrell, David Golden, David
+Marshall, David Mitchell, E. Choroba, Eugen Konkov, Felipe Gasper, François
+Perrad, Graham Knop, H.Merijn Brand, Hugo van der Sanden, Ilya Sashcheka,
+Ivan Panchenko, Jakub Wilk, James E Keenan, James Raspass, Karen Etheridge,
+Karl Williamson, Leam Hall, Leon Timmermans, Magnus Woldrich, Matthew
+Horsfall, Max Maischein, Michael G Schwern, Michiel Beijen, Mike Fulton,
+Neil Bowers, Nicholas Clark, Nicolas R, Niyas Sait, Olaf Alders, Paul Evans,
+Paul Marquess, Petar-Kaleychev, Pete Houston, Renee Baecker, Ricardo Signes,
+Richard Leach, Robert Rothenberg, Sawyer X, Scott Baker, Sergey Poznyakoff,
+Sergey Zhmylove, Sisyphus, Slaven Rezic, Steve Hay, Sven Kirmess, TAKAI
+Kousuke, Thibault Duponchelle, Todd Rinaldo, Tomasz Konojacki, Tomoyuki
+Sadahiro, Tony Cook, Unicode Consortium, Yves Orton, Михаил
+Козачков.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the AUTHORS file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5361delta.1 b/upstream/mageia-cauldron/man1/perl5361delta.1
new file mode 100644
index 00000000..b9181585
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5361delta.1
@@ -0,0 +1,181 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5361DELTA 1"
+.TH PERL5361DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5361delta \- what is new for perl v5.36.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.36.0 release and the 5.36.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.35.0, first read
+perl5360delta, which describes differences between 5.35.0 and 5.36.0.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.36.0.  If any exist,
+they are bugs, and we request that you submit a report.  See
+"Reporting Bugs" below.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20220520 to 5.20230423.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\f(CW\*(C`Configure\*(C'\fR probed for the return type of \fBmalloc()\fR and \fBfree()\fR by testing
+whether declarations for those functions produced a function type mismatch with
+the implementation.  On Solaris, with a C++ compiler, this check always failed,
+since Solaris instead imports \fBmalloc()\fR and \fBfree()\fR from \f(CW\*(C`std::\*(C'\fR with \f(CW\*(C`using\*(C'\fR
+for C++ builds.  Since the return types of \fBmalloc()\fR and \fBfree()\fR are well defined
+by the C standard, skip probing for them.  \f(CW\*(C`Configure\*(C'\fR command-line arguments
+and hints can still override these type in the unlikely case that is needed.
+[GH #20806 <https://github.com/Perl/perl5/issues/20806>]
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and changes in this
+release.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+An \fBeval()\fR as the last statement in a regex code block could trigger an
+interpreter panic; e.g.
+.Sp
+.Vb 1
+\&    /(?{ ...; eval {....}; })/
+.Ve
+.Sp
+[GH #19680 <https://github.com/Perl/perl5/issues/19680>]
+.IP \(bu 4
+An \f(CW\*(C`eval EXPR\*(C'\fR referring to a lexical sub defined in grandparent scope no
+longer produces an assertion failures.
+[GH #19857 <https://github.com/Perl/perl5/issues/19857>]
+.IP \(bu 4
+Writing to a magic variables associated with the selected output handle, \f(CW$^\fR,
+\&\f(CW$~\fR, \f(CW$=\fR, \f(CW\*(C`$\-\*(C'\fR and \f(CW$%\fR, no longer crashes perl if the IO object has been
+cleared from the selected output handle.
+[GH #20733 <https://github.com/Perl/perl5/issues/20733>]
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.36.1 represents approximately 11 months of development since Perl 5.36.0
+and contains approximately 5,500 lines of changes across 62 files from 24
+authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,600 lines of changes to 23 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant community
+of users and developers.  The following people are known to have contributed
+the improvements that became Perl 5.36.1:
+.PP
+Andreas König, Bram, Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari
+Mannsåker, David Mitchell, Elvin Aslanov, Florian Weimer, Graham Knop, Hugo
+van der Sanden, Karen Etheridge, Karl Williamson, Leon Timmermans, Matthew
+Horsfall, Max Maischein, Neil Bowers, Nicolas R, Renee Baecker, Ricardo Signes,
+Richard Leach, Steve Hay, Todd Rinaldo, Tony Cook, Yves Orton.
+.PP
+The list above is almost certainly incomplete as it is automatically generated
+from version control history.  In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core.  We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please see
+the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database at
+<https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec for details of how to
+report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5, you
+can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5362delta.1 b/upstream/mageia-cauldron/man1/perl5362delta.1
new file mode 100644
index 00000000..9cceb1b5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5362delta.1
@@ -0,0 +1,160 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5362DELTA 1"
+.TH PERL5362DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5362delta \- what is new for perl v5.36.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.36.1 release and the 5.36.2
+release.
+.PP
+If you are upgrading from an earlier release such as 5.36.0, first read
+perl5361delta, which describes differences between 5.36.0 and 5.36.1.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.36.2 represents approximately 7 months of development since Perl
+5.36.1 and contains approximately 2,300 lines of changes across 38 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,400 lines of changes to 8 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.36.2:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5363delta.1 b/upstream/mageia-cauldron/man1/perl5363delta.1
new file mode 100644
index 00000000..8aced22a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5363delta.1
@@ -0,0 +1,161 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5363DELTA 1"
+.TH PERL5363DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5363delta \- what is new for perl v5.36.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.36.1 release and the 5.36.3
+release.  \fBPlease note:\fR This document ignores Perl 5.36.2, a broken release
+which existed for a couple of days only.
+.PP
+If you are upgrading from an earlier release such as 5.36.0, first read
+perl5361delta, which describes differences between 5.36.0 and 5.36.1.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.36.3 represents approximately 1 month of development since Perl
+5.36.1 and contains approximately 2,300 lines of changes across 38 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,400 lines of changes to 8 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.36.3:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5380delta.1 b/upstream/mageia-cauldron/man1/perl5380delta.1
new file mode 100644
index 00000000..5cd86e4b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5380delta.1
@@ -0,0 +1,1750 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5380DELTA 1"
+.TH PERL5380DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5380delta \- what is new for perl v5.38.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.36.0 release and the 5.38.0
+release.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.ie n .SS "New ""class"" Feature"
+.el .SS "New \f(CWclass\fP Feature"
+.IX Subsection "New class Feature"
+A new \fBexperimental\fR syntax is now available for defining object classes,
+where per-instance data is stored in "field" variables that behave like
+lexicals.
+.PP
+.Vb 1
+\&    use feature \*(Aqclass\*(Aq;
+\&
+\&    class Point
+\&    {
+\&        field $x;
+\&        field $y;
+\&
+\&        method zero { $x = $y = 0; }
+\&    }
+.Ve
+.PP
+This is described in more detail in perlclass.  Notes on the internals of
+its implementation and other related details can be found in perlclassguts.
+.PP
+This remains a new and experimental feature, and is very much still under
+development. It will be the subject of much further addition, refinement and
+alteration in future releases.  As it is experimental, it yields warnings in
+the \f(CW\*(C`experimental::class\*(C'\fR category.  These can be silenced by a
+\&\f(CW\*(C`no warnings\*(C'\fR statement.
+.PP
+.Vb 2
+\&    use feature \*(Aqclass\*(Aq;
+\&    no warnings \*(Aqexperimental::class\*(Aq;
+.Ve
+.SS "Unicode 15.0 is supported"
+.IX Subsection "Unicode 15.0 is supported"
+See <https://www.unicode.org/versions/Unicode15.0.0/> for details.
+.SS "Deprecation warnings now have specific subcategories"
+.IX Subsection "Deprecation warnings now have specific subcategories"
+All deprecation warnings now have their own specific deprecation category which
+can be disabled individually. You can see a list of all deprecated features in
+perldeprecation, and in warnings. The following list is from warnings:
+.PP
+.Vb 10
+\&         +\- deprecated \-\-\-\-+
+\&         |                 |
+\&         |                 +\- deprecated::apostrophe_as_package_separator
+\&         |                 |
+\&         |                 +\- deprecated::delimiter_will_be_paired
+\&         |                 |
+\&         |                 +\- deprecated::dot_in_inc
+\&         |                 |
+\&         |                 +\- deprecated::goto_construct
+\&         |                 |
+\&         |                 +\- deprecated::smartmatch
+\&         |                 |
+\&         |                 +\- deprecated::unicode_property_name
+\&         |                 |
+\&         |                 +\- deprecated::version_downgrade
+.Ve
+.PP
+It is still possible to disable all deprecation warnings in a single
+statement with
+.PP
+.Vb 1
+\&    no warnings \*(Aqdeprecated\*(Aq;
+.Ve
+.PP
+but now is possible to have a finer grained control. As has historically been
+the case these warnings are automatically enabled with
+.PP
+.Vb 1
+\&    use warnings;
+.Ve
+.SS "%{^HOOK} API introduced"
+.IX Subsection "%{^HOOK} API introduced"
+For various reasons it can be difficult to create subroutine wrappers
+for some of perls keywords. Any keyword which has an undefined
+prototype simply cannot be wrapped with a subroutine, and some keywords
+which perl permits to be wrapped are in practice very tricky to wrap.
+For example \f(CW\*(C`require\*(C'\fR is tricky to wrap, it is possible but doing so
+changes the stack depth, and the standard methods of exporting assume
+that they will be exporting to a package at certain stack depth up the
+stack, and the wrapper will thus change where functions are exported to
+unless implemented with a great deal of care. This can be very awkward
+to deal with.
+.PP
+Accordingly we have introduced a new hash called \f(CW\*(C`%{^HOOK}\*(C'\fR which is
+intended to facilitate such cases. When a keyword supports any kind of
+special hook then the hook will live in this new hash. Hooks in this
+hash will be named after the function they are called by, followed by
+two underbars and then the phase they are executed in, currently either
+before or after the keyword is executed.
+.PP
+In this initial release we support two hooks \f(CW\*(C`require_\|_before\*(C'\fR and
+\&\f(CW\*(C`require_\|_after\*(C'\fR. These are provided to make it easier to perform tasks
+before and after a require statement.
+.PP
+See perlvar for more details.
+.SS PERL_RAND_SEED
+.IX Subsection "PERL_RAND_SEED"
+Added a new environment variable \f(CW\*(C`PERL_RAND_SEED\*(C'\fR which can be used to
+cause a perl program which uses \f(CW\*(C`rand\*(C'\fR without using \f(CWsrand()\fR
+explicitly or which uses \f(CWsrand()\fR with no arguments to be repeatable.
+See perlrun. This feature can be disabled at compile time by passing
+.PP
+.Vb 1
+\&    \-Accflags=\-DNO_PERL_RAND_SEED
+.Ve
+.PP
+to \fIConfigure\fR during the build process.
+.SS "Defined-or and logical-or assignment default expressions in signatures"
+.IX Subsection "Defined-or and logical-or assignment default expressions in signatures"
+The default expression for a subroutine signature parameter can now be
+assigned using the \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR operators, to apply the defaults whenever
+the caller provided an undefined or false value (respectively), rather than
+simply when the parameter is missing entirely.  For more detail see the
+documentation in perlsub.
+.ie n .SS "@INC Hook Enhancements and $INC and INCDIR"
+.el .SS "\f(CW@INC\fP Hook Enhancements and \f(CW$INC\fP and INCDIR"
+.IX Subsection "@INC Hook Enhancements and $INC and INCDIR"
+The internals for \f(CW@INC\fR hooks have been hardened to handle various
+edge cases and should no longer segfault or throw assert failures when
+hooks modify \f(CW@INC\fR during a require operation.  As part of this we
+now ensure that any given hook is executed at most once during a require
+call, and that any duplicate directories do not trigger additional
+directory probes.
+.PP
+To provide developers more control over dynamic module lookup, a new hook
+method \f(CW\*(C`INCDIR\*(C'\fR is now supported. An object supporting this method may be
+injected into the \f(CW@INC\fR array, and when it is encountered in the module
+search process it will be executed, just like how INC hooks are executed,
+and its return value used as a list of directories to search for the
+module. Returning an empty list acts as a no-op. Note that since any
+references returned by this hook will be stringified and used as strings,
+you may not return a hook to be executed later via this API.
+.PP
+When an \f(CW@INC\fR hook (either \f(CW\*(C`INC\*(C'\fR or \f(CW\*(C`INCDIR\*(C'\fR) is called during
+require, the \f(CW$INC\fR variable will be localized to be the value of the
+index of \f(CW@INC\fR that the hook came from. If the hook wishes to override
+what the "next" index in \f(CW@INC\fR should be it may update \f(CW$INC\fR to be one
+less than the desired index (\f(CW\*(C`undef\*(C'\fR is equivalent to \f(CW\-1\fR). This
+allows an \f(CW@INC\fR hook to completely rewrite the \f(CW@INC\fR array and have
+perl restart its directory probes from the beginning of \f(CW@INC\fR.
+.PP
+Blessed CODE references in \f(CW@INC\fR that do not support the \f(CW\*(C`INC\*(C'\fR or
+\&\f(CW\*(C`INCDIR\*(C'\fR methods will no longer trigger an exception, and instead will
+be treated the same as unblessed coderefs are, and executed as though
+they were an \f(CW\*(C`INC\*(C'\fR hook.
+.ie n .SS "Forbidden control flow out of ""defer"" or ""finally"" now detected at compile-time"
+.el .SS "Forbidden control flow out of \f(CWdefer\fP or \f(CWfinally\fP now detected at compile-time"
+.IX Subsection "Forbidden control flow out of defer or finally now detected at compile-time"
+It is forbidden to attempt to leave a \f(CW\*(C`defer\*(C'\fR or \f(CW\*(C`finally\*(C'\fR block by means
+of control flow such as \f(CW\*(C`return\*(C'\fR or \f(CW\*(C`goto\*(C'\fR. Previous versions of perl could
+only detect this when actually attempted at runtime.
+.PP
+This version of perl adds compile-time detection for many cases that can be
+statically determined. This may mean that code which compiled successfully on
+a previous version of perl is now reported as a compile-time error with this
+one. This only happens in cases where it would have been an error to actually
+execute the code anyway; the error simply happens at an earlier time.
+.SS "Optimistic Eval in Patterns"
+.IX Subsection "Optimistic Eval in Patterns"
+The use of \f(CW\*(C`(?{ ... })\*(C'\fR and \f(CW\*(C`(??{ ... })\*(C'\fR in a pattern disables various
+optimisations globally in that pattern. This may or may not be desired by the
+programmer. This release adds the \f(CW\*(C`(*{ ... })\*(C'\fR
+equivalent. The only difference is that it does not and will never disable
+any optimisations in the regex engine. This may make it more unstable in the
+sense that it may be called more or less times in the future, however the
+number of times it executes will truly match how the regex engine functions.
+For example, certain types of optimisation are disabled when \f(CW\*(C`(?{ ... })\*(C'\fR is
+included in a pattern, so that patterns which are O(N) in normal use become
+O(N*N) with a \f(CW\*(C`(?{ ... })\*(C'\fR pattern in them. Switching to \f(CW\*(C`(*{ ... })\*(C'\fR means
+the pattern will stay O(N).
+.SS "REG_INF has been raised from 65,536 to 2,147,483,647"
+.IX Subsection "REG_INF has been raised from 65,536 to 2,147,483,647"
+Many regex quantifiers used to be limited to \f(CW\*(C`U16_MAX\*(C'\fR in the past, but are
+now limited to \f(CW\*(C`I32_MAX\*(C'\fR, thus it is now possible to write
+\&\f(CW\*(C`/(?:word){1000000}/\*(C'\fR for example.  Note that doing so may cause the regex
+engine to run longer and use more memory.
+.SS "New API functions optimize_optree and finalize_optree"
+.IX Subsection "New API functions optimize_optree and finalize_optree"
+There are two new API functions for operating on optree fragments, ensuring
+you can invoke the required parts of the optree-generation process that might
+otherwise not get invoked (e.g. when creating a custom LOGOP).  To get access
+to these functions, you first need to set a \f(CW\*(C`#define\*(C'\fR to opt-in to using
+these functions.
+.PP
+.Vb 1
+\&  #define PERL_USE_VOLATILE_API
+.Ve
+.PP
+These functions are closely tied to the internals of how the interpreter
+works, and could be altered or removed at any time if other internal changes
+make that necessary.
+.ie n .SS "Some ""goto""s are now permitted in ""defer"" and ""finally"" blocks"
+.el .SS "Some \f(CWgoto\fPs are now permitted in \f(CWdefer\fP and \f(CWfinally\fP blocks"
+.IX Subsection "Some gotos are now permitted in defer and finally blocks"
+Perl version 5.36.0 added \f(CW\*(C`defer\*(C'\fR blocks and permitted the \f(CW\*(C`finally\*(C'\fR keyword
+to also add similar behaviour to \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR syntax.  These did not permit
+any \f(CW\*(C`goto\*(C'\fR expression within the body, as it could have caused control flow
+to jump out of the block.  Now, some \f(CW\*(C`goto\*(C'\fR expressions are allowed, if they
+have a constant target label, and that label is found within the block.
+.PP
+.Vb 1
+\&  use feature \*(Aqdefer\*(Aq;
+\&
+\&  defer {
+\&    goto LABEL;
+\&    print "This does not execute\en";
+\&    LABEL: print "This does\en";
+\&  }
+.Ve
+.SS "New regexp variable ${^LAST_SUCCESSFUL_PATTERN}"
+.IX Subsection "New regexp variable ${^LAST_SUCCESSFUL_PATTERN}"
+This allows access to the last succesful pattern that matched in the current
+scope.  Many aspects of the regex engine refer to the "last successful
+pattern". The empty pattern reuses it, and all of the magic regex vars relate
+to it. This allows access to its pattern. The following code
+.PP
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s//PQR/;
+\&    }
+.Ve
+.PP
+can be rewritten as follows
+.PP
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s/${^LAST_SUCCESSFUL_PATTERN}/PQR/;
+\&    }
+.Ve
+.PP
+and it will do the exactly same thing.
+.SS "Locale category LC_NAME now supported on participating platforms"
+.IX Subsection "Locale category LC_NAME now supported on participating platforms"
+On platforms that have the GNU extension \f(CW\*(C`LC_NAME\*(C'\fR category, you may now use
+it as the category parameter to "setlocale" in POSIX to set and query its locale.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "\fBreadline()\fP no longer clears the stream error and eof flags"
+.IX Subsection "readline() no longer clears the stream error and eof flags"
+\&\f(CWreadline()\fR, also spelled \f(CW\*(C`<>\*(C'\fR, would clear the handle's error
+and eof flags after an error occurred on the stream.
+.PP
+In nearly all cases this clear is no longer done, so the error and
+eof flags now properly reflect the status of the stream after
+\&\fBreadline()\fR.
+.PP
+Since the error flag is no longer cleared calling \fBclose()\fR on the
+stream may fail and if the stream was not explicitly closed, the
+implicit close of the stream may produce a warning.
+.PP
+This has resulted in two main types of problems in downstream CPAN
+modules, and these may also occur in your code:
+.IP \(bu 4
+If your code reads to end of file, and then rebinds the handle to a
+new file descriptor, previously since the eof flag wasn't set you
+could continue to read from the stream.  You now need to clear the eof
+flag yourself with \f(CW\*(C`$handle\->clearerr()\*(C'\fR to continue reading.
+.IP \(bu 4
+If your code encounters an error on the stream while reading with
+\&\fBreadline()\fR you will need to call \f(CW\*(C`$handle\->clearerr\*(C'\fR to continue
+reading.  The one case this occurred the underlying file descriptor was
+marked non-blocking, so the \fBread()\fR system call was failing with
+\&\f(CW\*(C`EAGAIN\*(C'\fR, which resulted in the error flag being set on the stream.
+.PP
+The only case where error and eof flags continue to cleared on
+error is when reading from the child process for \fBglob()\fR in
+\&\fIminiperl\fR.  This allows it to correctly report errors from the child
+process on \fBclose()\fR.  This is unlikely to be an issue during normal
+perl development.
+.PP
+[GH #20060 <https://github.com/Perl/perl5/issues/20060>]
+.ie n .SS """INIT"" blocks no longer run after an exit() in ""BEGIN"""
+.el .SS "\f(CWINIT\fP blocks no longer run after an \f(CWexit()\fP in \f(CWBEGIN\fP"
+.IX Subsection "INIT blocks no longer run after an exit() in BEGIN"
+\&\f(CW\*(C`INIT\*(C'\fR blocks will no longer run after an \f(CWexit()\fR performed inside of
+a \f(CW\*(C`BEGIN\*(C'\fR. This means that the combination of the \f(CW\*(C`\-v\*(C'\fR option and the
+\&\f(CW\*(C`\-c\*(C'\fR option no longer executes a compile check as well as showing the
+perl version. The \f(CW\*(C`\-v\*(C'\fR option executes an \fBexit\fR\|(0) after printing the
+version information inside of a \f(CW\*(C`BEGIN\*(C'\fR block, and the \f(CW\*(C`\-c\*(C'\fR check is
+implemented by using \f(CW\*(C`INIT\*(C'\fR hooks, resulting in the \f(CW\*(C`\-v\*(C'\fR option taking
+precedence.
+.PP
+[GH #1537 <https://github.com/Perl/perl5/issues/1537>]
+[GH #20181 <https://github.com/Perl/perl5/issues/20181>]
+.SS "Syntax errors no longer produce ""phantom error messages"""
+.IX Subsection "Syntax errors no longer produce ""phantom error messages"""
+Generally perl will continue parsing the source code even after
+encountering a compile error. In many cases this is helpful, for
+instance with misspelled variable names it is helpful to show as many
+examples of the error as possible. But in the case of syntax errors
+continuing often produces bizarre error messages and may even cause
+segmentation faults during the compile process. In this release the
+compiler will halt at the first syntax error encountered. This means
+that any code expecting to see the specific error messages we used to
+produce will be broken. The error that is emitted will be one of the
+diagnostics that used to be produced, but in some cases some messages
+that used to be produced will no longer be displayed.
+.PP
+See "Changes to Existing Diagnostics" for more details.
+.ie n .SS utf8::upgrade()
+.el .SS \f(CWutf8::upgrade()\fP
+.IX Subsection "utf8::upgrade()"
+Starting in this release, if the input string is \f(CW\*(C`undef\*(C'\fR, it remains
+\&\f(CW\*(C`undef\*(C'\fR.  Previously it would be changed into a defined, zero-length
+string.
+.SS "Changes to ""thread-safe"" locales"
+.IX Subsection "Changes to ""thread-safe"" locales"
+Perl 5.28 introduced "thread-safe" locales on systems that supported
+them, namely modern Windows, and systems supporting POSIX 2008 locale
+operations.  These systems accomplish this by having per-thread locales,
+while continuing to support the older global locale operations for code
+that doesn't take the steps necessary to use the newer per-thread ones.
+.PP
+It turns out that some POSIX 2008 platforms have or have had buggy
+implementations, which forced perl to not use them.  The
+\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR scalar variable contains 0 or 1 to indicate whether
+or not the current platform is considered by perl to have a working
+thread-safe implementation.  Some implementations have been fixed
+already, but FreeBSD and Cygwin have been newly discovered to be
+sufficiently buggy that the thread-safe operations are no longer used by
+perl, starting in this release.  Hence, \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is now 0 for
+them.  Older versions of perl can be configured to avoid these buggy
+implementations by adding the \fIConfigure\fR option
+\&\f(CW\*(C`\-DNO_POSIX_2008_LOCALE\*(C'\fR.
+.PP
+And v5.38 fixes a bug in all previous perls that led to locales not
+being fully thread-safe.  The first thread that finishes caused
+the main thread (named \f(CW\*(C`thread0\*(C'\fR) to revert to the global locale in
+effect at startup, discarding whatever the thread's locale had been
+previously set to.  If any other thread had switched to the global
+locale by calling \f(CWswitch_to_global_locale()\fR in XS code, those threads
+would all share the global locale, and \f(CW\*(C`thread0\*(C'\fR would not be
+thread-safe.
+.SH Deprecations
+.IX Header "Deprecations"
+.ie n .SS "Use of ""\*(Aq"" as a package name separator is deprecated"
+.el .SS "Use of \f(CW\*(Aq\fP as a package name separator is deprecated"
+.IX Subsection "Use of as a package name separator is deprecated"
+Using \f(CW\*(C`\*(Aq\*(C'\fR as package separator in a variable named in a double-quoted
+string has warned since 5.28.  It is now deprecated in both string
+interpolation and non-interpolated contexts, and will be removed in
+Perl 5.42.
+.SS "Switch and Smart Match operator"
+.IX Subsection "Switch and Smart Match operator"
+The "switch" feature and the smartmatch operator, \f(CW\*(C`~~\*(C'\fR, were introduced in
+v5.10.  Their behavior was significantly changed in v5.10.1.  When the
+"experiment" system was added in v5.18.0, switch and smartmatch were
+retroactively declared experimental.  Over the years, proposals to fix or
+supplement the features have come and gone.
+.PP
+In v5.38.0, we are declaring the experiment a failure.  Some future system may
+take the conceptual place of smartmatch, but it has not yet been designed or
+built.
+.PP
+These features will be entirely removed from perl in v5.42.0.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Additional optree optimizations for common OP patterns. For example, multiple
+simple OPs replaced by a single streamlined OP, so as to be more efficient at
+runtime. [GH #19943 <https://github.com/Perl/perl5/pull/19943>],
+[GH #20063 <https://github.com/Perl/perl5/pull/20063>],
+[GH #20077 <https://github.com/Perl/perl5/pull/20077>].
+.IP \(bu 4
+Creating an anonymous sub no longer generates an \f(CW\*(C`srefgen\*(C'\fR op, the
+reference generation is now done in the \f(CW\*(C`anoncode\*(C'\fR or \f(CW\*(C`anonconst\*(C'\fR
+op, saving runtime. [GH #20290 <https://github.com/Perl/perl5/pull/20290>]
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules and Pragmata"
+.IX Subsection "Updated Modules and Pragmata"
+.IP \(bu 4
+Added the \f(CWis_tainted()\fR builtin function. [GH #19854 <https://github.com/Perl/perl5/issues/19854>]
+.IP \(bu 4
+Added the \f(CWexport_lexically()\fR builtin function as per PPC 0020 <https://github.com/Perl/PPCs/blob/main/ppcs/ppc0020-lexical-export.md>. [GH #19895 <https://github.com/Perl/perl5/issues/19895>]
+.IP \(bu 4
+Support for PPC 0018 <https://github.com/Perl/PPCs/blob/main/ppcs/ppc0018-module-true.md>, \f(CW\*(C`use feature "module_true";\*(C'\fR has been added to
+the default feature bundle for v5.38 and later. It may also be used
+explicitly. When enabled inside of a module the module does not need
+to return true explicitly, and in fact the return will be forced to
+a simple true value regardless of what it originally was.
+.IP \(bu 4
+Attribute::Handlers has been upgraded from version 1.02 to 1.03.
+.IP \(bu 4
+attributes has been upgraded from version 0.34 to 0.35.
+.IP \(bu 4
+autodie has been upgraded from version 2.34 to 2.36.
+.IP \(bu 4
+B has been upgraded from version 1.83 to 1.88.
+.IP \(bu 4
+B::Concise has been upgraded from version 1.006 to 1.007.
+.IP \(bu 4
+B::Deparse has been upgraded from version 1.64 to 1.74.
+.IP \(bu 4
+Benchmark has been upgraded from version 1.23 to 1.24.
+.IP \(bu 4
+bignum has been upgraded from version 0.65 to 0.66.
+.IP \(bu 4
+Carp has been upgraded from version 1.52 to 1.54.
+.IP \(bu 4
+Class::Struct has been upgraded from version 0.66 to 0.68.
+.IP \(bu 4
+Compress::Raw::Bzip2 has been upgraded from version 2.103 to 2.204_001.
+.IP \(bu 4
+Compress::Raw::Zlib has been upgraded from version 2.105 to 2.204_001.
+.IP \(bu 4
+Config::Perl::V has been upgraded from version 0.33 to 0.36.
+.IP \(bu 4
+CPAN has been upgraded from version 2.33 to 2.36.
+.IP \(bu 4
+Data::Dumper has been upgraded from version 2.184 to 2.188.
+.IP \(bu 4
+DB_File has been upgraded from version 1.857 to 1.858.
+.IP \(bu 4
+Devel::Peek has been upgraded from version 1.32 to 1.33.
+.IP \(bu 4
+Devel::PPPort has been upgraded from version 3.68 to 3.71.
+.IP \(bu 4
+Digest::MD5 has been upgraded from version 2.58 to 2.58_01.
+.IP \(bu 4
+Digest::SHA has been upgraded from version 6.02 to 6.04.
+.IP \(bu 4
+DynaLoader has been upgraded from version 1.52 to 1.54.
+.IP \(bu 4
+Encode has been upgraded from version 3.17 to 3.19.
+.IP \(bu 4
+encoding::warnings has been upgraded from version 0.13 to 0.14.
+.IP \(bu 4
+Env has been upgraded from version 1.05 to 1.06.
+.IP \(bu 4
+Errno has been upgraded from version 1.36 to 1.37.
+.IP \(bu 4
+experimental has been upgraded from version 0.028 to 0.031.
+.IP \(bu 4
+ExtUtils::CBuilder has been upgraded from version 0.280236 to 0.280238.
+.IP \(bu 4
+ExtUtils::Install has been upgraded from version 2.20 to 2.22.
+.IP \(bu 4
+ExtUtils::MakeMaker has been upgraded from version 7.64 to 7.70.
+.IP \(bu 4
+ExtUtils::Miniperl has been upgraded from version 1.11 to 1.13.
+.IP \(bu 4
+ExtUtils::ParseXS has been upgraded from version 3.45 to 3.51.
+.IP \(bu 4
+ExtUtils::PL2Bat has been upgraded from version 0.004 to 0.005.
+.IP \(bu 4
+ExtUtils::Typemaps has been upgraded from version 3.45 to 3.51.
+.IP \(bu 4
+feature has been upgraded from version 1.72 to 1.82.
+.IP \(bu 4
+File::Basename has been upgraded from version 2.85 to 2.86.
+.IP \(bu 4
+File::Copy has been upgraded from version 2.39 to 2.41.
+.IP \(bu 4
+File::Find has been upgraded from version 1.40 to 1.43.
+.IP \(bu 4
+File::Glob has been upgraded from version 1.37 to 1.40.
+.IP \(bu 4
+File::Spec has been upgraded from version 3.84 to 3.89.
+.IP \(bu 4
+File::stat has been upgraded from version 1.12 to 1.13.
+.IP \(bu 4
+FileHandle has been upgraded from version 2.03 to 2.05.
+.IP \(bu 4
+Filter::Util::Call has been upgraded from version 1.60 to 1.64.
+.IP \(bu 4
+GDBM_File has been upgraded from version 1.23 to 1.24.
+.IP \(bu 4
+Getopt::Long has been upgraded from version 2.52 to 2.54.
+.IP \(bu 4
+Hash::Util has been upgraded from version 0.28 to 0.30.
+.IP \(bu 4
+HTTP::Tiny has been upgraded from version 0.080 to 0.083.
+.IP \(bu 4
+I18N::Langinfo has been upgraded from version 0.21 to 0.22.
+.IP \(bu 4
+IO has been upgraded from version 1.50 to 1.52.
+.IP \(bu 4
+IO-Compress has been upgraded from version 2.106 to 2.204.
+.IP \(bu 4
+IO::Socket::IP has been upgraded from version 0.41 to 0.41_01.
+.Sp
+On DragonflyBSD, detect \fBsetsockopt()\fR not actually clearing
+\&\f(CW\*(C`IPV6_V6ONLY\*(C'\fR even when \fBsetsockopt()\fR returns success.  [cpan
+#148293 <https://rt.cpan.org/Ticket/Display.html?id=148293>]
+.IP \(bu 4
+IO::Zlib has been upgraded from version 1.11 to 1.14.
+.IP \(bu 4
+JSON::PP has been upgraded from version 4.07 to 4.16.
+.IP \(bu 4
+libnet has been upgraded from version 3.14 to 3.15.
+.IP \(bu 4
+Locale::Maketext has been upgraded from version 1.31 to 1.33.
+.IP \(bu 4
+Math::BigInt has been upgraded from version 1.999830 to 1.999837.
+.IP \(bu 4
+Math::BigInt::FastCalc has been upgraded from version 0.5012 to 0.5013.
+.IP \(bu 4
+Math::BigRat has been upgraded from version 0.2621 to 0.2624.
+.IP \(bu 4
+Math::Complex has been upgraded from version 1.5902 to 1.62.
+.IP \(bu 4
+Memoize has been upgraded from version 1.03_01 to 1.16.
+.IP \(bu 4
+MIME::Base64 has been upgraded from version 3.16 to 3.16_01.
+.IP \(bu 4
+Module::CoreList has been upgraded from version 5.20220520 to 5.20230520.
+.IP \(bu 4
+mro has been upgraded from version 1.26 to 1.28.
+.IP \(bu 4
+NDBM_File has been upgraded from version 1.15 to 1.16.
+.IP \(bu 4
+Net::Ping has been upgraded from version 2.74 to 2.76.
+.IP \(bu 4
+ODBM_File has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+Opcode has been upgraded from version 1.57 to 1.64.
+.IP \(bu 4
+overload has been upgraded from version 1.35 to 1.37.
+.IP \(bu 4
+parent has been upgraded from version 0.238 to 0.241.
+.IP \(bu 4
+PerlIO::via::QuotedPrint has been upgraded from version 0.09 to 0.10.
+.IP \(bu 4
+Pod::Checker has been upgraded from version 1.74 to 1.75.
+.IP \(bu 4
+Pod::Html has been upgraded from version 1.33 to 1.34.
+.IP \(bu 4
+Pod::Usage has been upgraded from version 2.01 to 2.03.
+.IP \(bu 4
+podlators has been upgraded from version 4.14 to 5.01.
+.IP \(bu 4
+POSIX has been upgraded from version 2.03 to 2.13.
+.IP \(bu 4
+re has been upgraded from version 0.43 to 0.44.
+.IP \(bu 4
+Safe has been upgraded from version 2.43 to 2.44.
+.IP \(bu 4
+Scalar::Util has been upgraded from version 1.62 to 1.63.
+.IP \(bu 4
+SDBM_File has been upgraded from version 1.15 to 1.17.
+.IP \(bu 4
+Socket has been upgraded from version 2.033 to 2.036.
+.IP \(bu 4
+Storable has been upgraded from version 3.26 to 3.32.
+.IP \(bu 4
+Sys::Hostname has been upgraded from version 1.24 to 1.25.
+.IP \(bu 4
+Term::Cap has been upgraded from version 1.17 to 1.18.
+.IP \(bu 4
+Test::Simple has been upgraded from version 1.302190 to 1.302194.
+.IP \(bu 4
+Text::Balanced has been upgraded from version 2.04 to 2.06.
+.IP \(bu 4
+threads has been upgraded from version 2.27 to 2.36.
+.IP \(bu 4
+threads::shared has been upgraded from version 1.64 to 1.68.
+.IP \(bu 4
+Tie::File has been upgraded from version 1.06 to 1.07.
+.IP \(bu 4
+Time::HiRes has been upgraded from version 1.9770 to 1.9775.
+.IP \(bu 4
+Time::Piece has been upgraded from version 1.3401 to 1.3401_01.
+.IP \(bu 4
+Unicode::Normalize has been upgraded from version 1.31 to 1.32.
+.IP \(bu 4
+UNIVERSAL has been upgraded from version 1.14 to 1.15.
+.IP \(bu 4
+User::grent has been upgraded from version 1.03 to 1.04.
+.IP \(bu 4
+User::pwent has been upgraded from version 1.01 to 1.02.
+.IP \(bu 4
+utf8 has been upgraded from version 1.24 to 1.25.
+.IP \(bu 4
+warnings has been upgraded from version 1.58 to 1.65.
+.IP \(bu 4
+XS::APItest has been upgraded from version 1.22 to 1.32.
+.IP \(bu 4
+XSLoader has been upgraded from version 0.31 to 0.32.
+.SH Documentation
+.IX Header "Documentation"
+.SS "New Documentation"
+.IX Subsection "New Documentation"
+\fIperlclass\fR
+.IX Subsection "perlclass"
+.PP
+Describes the new \f(CW\*(C`class\*(C'\fR feature.
+.PP
+\fIperlclassguts\fR
+.IX Subsection "perlclassguts"
+.PP
+Describes the internals of the new \f(CW\*(C`class\*(C'\fR feature.
+.SS "Changes to Existing Documentation"
+.IX Subsection "Changes to Existing Documentation"
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, open an issue
+at <https://github.com/Perl/perl5/issues>.
+.PP
+Additionally, the following selected changes have been made:
+.PP
+\fIperlapi\fR
+.IX Subsection "perlapi"
+.IP \(bu 4
+Documented \f(CW\*(C`hv_ksplit\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`hv_name_set\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_stores\*(C'\fR
+documentation have been greatly improved.
+.IP \(bu 4
+Documented \f(CW\*(C`gv_autoload_pv\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`gv_autoload_pvn\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`gv_autoload_sv\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`gv_name_set\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`start_subparse\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`SvPV_shrink_to_cur\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`save_aelem\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`save_aelem_flags\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`save_helem\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`save_helem_flags\*(C'\fR
+.PP
+\fIperldeprecation\fR
+.IX Subsection "perldeprecation"
+.IP \(bu 4
+Added information about unscheduled deprecations and their categories.
+.IP \(bu 4
+Added category information for existing scheduled deprecations.
+.IP \(bu 4
+Added smartmatch and apostrophe as a package separator deprecation data.
+.PP
+\fIperlintern\fR
+.IX Subsection "perlintern"
+.IP \(bu 4
+Documented \f(CW\*(C`save_pushptr\*(C'\fR
+.IP \(bu 4
+Documented \f(CW\*(C`save_scalar_at\*(C'\fR
+.IP \(bu 4
+Entries have been added to perlguts for the new \f(CW\*(C`newAV_alloc_x\*(C'\fR, \f(CW\*(C`newAV_alloc_xz\*(C'\fR and
+\&\f(CW*_simple\fR functions.
+.IP \(bu 4
+References to the now-defunct PrePAN service have been removed from
+perlcommunity and perlmodstyle.
+.IP \(bu 4
+A section on symbol naming has been added to perlhacktips.
+.IP \(bu 4
+perlexperiment has been edited to properly reference the warning categories
+for the defer block modifier and extra paired delimiters for quote-like
+operators.
+.PP
+\fIperlexperiment\fR
+.IX Subsection "perlexperiment"
+.IP \(bu 4
+Smartmatch has been moved from experimental status to deprecated status.
+Unfortunately the experiment did not work out.
+.PP
+\fIperlfunc\fR
+.IX Subsection "perlfunc"
+.IP \(bu 4
+Some wording improvements have been made for the \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`push\*(C'\fR,
+\&\f(CW\*(C`unshift\*(C'\fR and \f(CW\*(C`bless\*(C'\fR functions, as well as additional examples added.
+.PP
+\fIperlhacktips\fR
+.IX Subsection "perlhacktips"
+.IP \(bu 4
+A new section, "Writing safer macros" in perlhacktips has been added to discuss
+pitfalls and solutions to using C macros in C and XS code.
+.IP \(bu 4
+A new section, "Choosing good symbol names" in perlhacktips, has been added to
+discuss unexpected gotchas with names.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP \(bu 4
+Document the behavior of matching the empty pattern better and specify
+its relationship to the new \f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR properly.
+.PP
+\fIperlvar\fR
+.IX Subsection "perlvar"
+.IP \(bu 4
+Added a section on "Scoping Rules of Regex Variables", and other wording
+improvements made throughout.
+.IP \(bu 4
+Added information on the new \f(CW\*(C`%{^HOOK}\*(C'\fR interface, and the new
+\&\f(CW\*(C`require_\|_before\*(C'\fR and \f(CW\*(C`require_\|_after\*(C'\fR hooks which it exposes.
+.IP \(bu 4
+Correct information on the regex variables \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR
+and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, all of which were incorrectly documented due to an
+oversight. Specifically they only work properly after a regex operation
+that used the /p modifier to enable them.
+.IP \(bu 4
+Added information on the new regex variable \f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR,
+which represents the pattern of the last successful regex match in scope.
+.SH Diagnostics
+.IX Header "Diagnostics"
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see perldiag.
+.SS "New Diagnostics"
+.IX Subsection "New Diagnostics"
+\fINew Errors\fR
+.IX Subsection "New Errors"
+.IP \(bu 4
+A new syntax error has been added for the error that a \f(CW\*(C`catch\*(C'\fR block does
+not have its required variable declaration. See
+catch block requires a (VAR)
+.IP \(bu 4
+Too many nested BEGIN blocks, maximum of \f(CW%d\fR allowed
+.IP \(bu 4
+Execution of \f(CW%s\fR aborted due to compilation errors.
+.IP \(bu 4
+Can't locate object method "INC", nor "INCDIR" nor string overload via
+package "%s" \f(CW%s\fR in \f(CW@INC\fR
+.IP \(bu 4
+Attempt to bless into a class
+.Sp
+(F) You are attempting to call \f(CW\*(C`bless\*(C'\fR with a package name that is a
+new-style \f(CW\*(C`class\*(C'\fR.  This is not necessary, as instances created by the
+constructor are already in the correct class.  Instances cannot be created
+by other means, such as \f(CW\*(C`bless\*(C'\fR.
+.IP \(bu 4
+Cannot assign :param(%s) to field \f(CW%s\fR because that name is already in use
+.Sp
+(F) An attempt was made to apply a parameter name to a field, when the name
+is already being used by another field in the same class, or one of its
+parent classes. This would cause a name clash so is not allowed.
+.IP \(bu 4
+Cannot create class \f(CW%s\fR as it already has a non-empty \f(CW@ISA\fR
+.Sp
+(F) An attempt was made to create a class out of a package that already has
+an \f(CW@ISA\fR array, and the array is not empty.  This is not permitted, as it
+would lead to a class with inconsistent inheritance.
+.IP \(bu 4
+Cannot invoke a method of "%s" on an instance of "%s"
+.Sp
+(F) You tried to directly call a \f(CW\*(C`method\*(C'\fR subroutine of one class by passing
+in a value that is an instance of a different class.  This is not permitted,
+as the method would not have access to the correct instance fields.
+.IP \(bu 4
+Cannot invoke method on a non-instance
+.Sp
+(F) You tried to directly call a \f(CW\*(C`method\*(C'\fR subroutine of a class by passing
+in a value that is not an instance of that class.  This is not permitted, as
+the method would not then have access to its instance fields.
+.IP \(bu 4
+Cannot '%s' outside of a 'class'
+.Sp
+(F) You attempted to use one of the keywords that only makes sense inside
+a \f(CW\*(C`class\*(C'\fR definition, at a location that is not inside such a class.
+.IP \(bu 4
+Cannot reopen existing class "%s"
+.Sp
+(F) You tried to begin a \f(CW\*(C`class\*(C'\fR definition for a class that already exists.
+A class may only have one definition block.
+.IP \(bu 4
+Can't bless an object reference
+.Sp
+(F) You attempted to call \f(CW\*(C`bless\*(C'\fR on a value that already refers to a real
+object instance.
+.IP \(bu 4
+can't convert empty path
+.Sp
+(F) On Cygwin, you called a path conversion function with an empty path.
+Only non-empty paths are legal.
+.IP \(bu 4
+Class already has a superclass, cannot add another
+.Sp
+(F) You attempted to specify a second superclass for a \f(CW\*(C`class\*(C'\fR by using
+the \f(CW\*(C`:isa\*(C'\fR attribute, when one is already specified.  Unlike classes
+whose instances are created with \f(CW\*(C`bless\*(C'\fR, classes created via the
+\&\f(CW\*(C`class\*(C'\fR keyword cannot have more than one superclass.
+.IP \(bu 4
+Class attribute \f(CW%s\fR requires a value
+.Sp
+(F) You specified an attribute for a class that would require a value to
+be passed in parentheses, but did not provide one.  Remember that
+whitespace is \fBnot\fR permitted between the attribute name and its value;
+you must write this as
+.Sp
+.Vb 1
+\&    class Example::Class :attr(VALUE) ...
+.Ve
+.IP \(bu 4
+Class :isa attribute requires a class but "%s" is not one
+.Sp
+(F) When creating a subclass using the \f(CW\*(C`class\*(C'\fR \f(CW\*(C`:isa\*(C'\fR attribute, the
+named superclass must also be a real class created using the \f(CW\*(C`class\*(C'\fR
+keyword.
+.IP \(bu 4
+Field already has a parameter name, cannot add another
+.Sp
+(F) A field may have at most one application of the \f(CW\*(C`:param\*(C'\fR attribute to
+assign a parameter name to it; once applied a second one is not allowed.
+.IP \(bu 4
+Field attribute \f(CW%s\fR requires a value
+.Sp
+(F) You specified an attribute for a field that would require a value to
+be passed in parentheses, but did not provide one.  Remember that
+whitespace is \fBnot\fR permitted between the attribute name and its value;
+you must write this as
+.Sp
+.Vb 1
+\&    field $var :attr(VALUE) ...
+.Ve
+.IP \(bu 4
+Field \f(CW%s\fR is not accessible outside a method
+.Sp
+(F) An attempt was made to access a field variable of a class from code
+that does not appear inside the body of a \f(CW\*(C`method\*(C'\fR subroutine.  This is not
+permitted, as only methods will have access to the fields of an instance.
+.IP \(bu 4
+Field \f(CW%s\fR of "%s" is not accessible in a method of "%s"
+.Sp
+(F) An attempt was made to access a field variable of a class, from a
+method of another class nested inside the one that actually defined it.
+This is not permitted, as only methods defined by a given class are
+permitted to access fields of that class.
+.IP \(bu 4
+Only scalar fields can take a :param attribute
+.Sp
+(F) You tried to apply the \f(CW\*(C`:param\*(C'\fR attribute to an array or hash field.
+Currently this is not permitted.
+.IP \(bu 4
+Required parameter '%s' is missing for \f(CW%s\fR constructor
+.Sp
+(F) You called the constructor for a class that has a required named
+parameter, but did not pass that parameter at all.
+.IP \(bu 4
+Unexpected characters while parsing class :isa attribute: \f(CW%s\fR
+.Sp
+(F) You tried to specify something other than a single class name with an
+optional trailing version number as the value for a \f(CW\*(C`class\*(C'\fR \f(CW\*(C`:isa\*(C'\fR
+attribute.  This confused the parser.
+.IP \(bu 4
+Unrecognized class attribute \f(CW%s\fR
+.Sp
+(F) You attempted to add a named attribute to a \f(CW\*(C`class\*(C'\fR definition, but
+perl does not recognise the name of the requested attribute.
+.IP \(bu 4
+Unrecognized field attribute \f(CW%s\fR
+.Sp
+(F) You attempted to add a named attribute to a \f(CW\*(C`field\*(C'\fR definition, but
+perl does not recognise the name of the requested attribute.
+.IP \(bu 4
+${^HOOK}{%s} may only be a CODE reference or undef
+.IP \(bu 4
+Attempt to set unknown hook '%s' in %{^HOOK}
+.IP \(bu 4
+Missing or undefined argument to \f(CW%s\fR via %{^HOOK}{require_\|_before}
+.IP \(bu 4
+Too many capture groups (limit is \f(CW%d\fR) in regex m/%s/
+.PP
+\fINew Warnings\fR
+.IX Subsection "New Warnings"
+.IP \(bu 4
+Unknown locale category \f(CW%d\fR
+.Sp
+This is a shortened form of an already existing diagnostic, for use when
+there is no new locale being switched to.  The previous diagnostic was
+misleading in such circumstances.
+.IP \(bu 4
+Locale '%s' is unsupported, and may crash the interpreter.
+.IP \(bu 4
+Treating \f(CW%s::INIT\fR block as BEGIN block as workaround
+.IP \(bu 4
+Filehandle STD%s reopened as \f(CW%s\fR only for input
+.IP \(bu 4
+\&\f(CW%s\fR on BEGIN block ignored
+.IP \(bu 4
+ADJUST is experimental
+.Sp
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`ADJUST\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP \(bu 4
+class is experimental
+.Sp
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`class\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP \(bu 4
+Method \f(CW%s\fR redefined
+.Sp
+(W redefine) You redefined a method.  To suppress this warning, say
+.Sp
+.Vb 4
+\&    {
+\&       no warnings \*(Aqredefine\*(Aq;
+\&       *name = method { ... };
+\&    }
+.Ve
+.IP \(bu 4
+Odd number of elements in hash field initialization
+.Sp
+(W misc) You specified an odd number of elements to initialise a hash
+field of an object.  Hashes are initialised from a list of key/value
+pairs so there must be a corresponding value to every key.  The final
+missing value will be filled in with undef instead.
+.IP \(bu 4
+Old package separator "'" deprecated
+.Sp
+(W deprecated, syntax) You used the old package separator "'" in a
+variable, subroutine or package name.  Support for the old package
+separator will be removed in Perl 5.40.
+.IP \(bu 4
+field is experimental
+.Sp
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`field\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP \(bu 4
+method is experimental
+.Sp
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`method\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP \(bu 4
+Can't call destructor for 0x%p in global destruction
+.SS "Changes to Existing Diagnostics"
+.IX Subsection "Changes to Existing Diagnostics"
+.IP \(bu 4
+The compiler will now stop parsing on the first syntax error it
+encounters. Historically the compiler would attempt to "skip past" the
+error and continue parsing so that it could list multiple errors. For
+things like undeclared variables under strict this makes sense. For
+syntax errors however it has been found that continuing tends to result
+in a storm of unrelated or bizarre errors that mostly just obscure the
+true error. In extreme cases it can even lead to segfaults and other
+incorrect behavior.
+.Sp
+Therefore we have reformed the continuation logic so that the parse will
+stop after the first seen syntax error. Semantic errors like undeclared
+variables will not stop the parse, so you may still see multiple errors
+when compiling code. However if there is a syntax error it will be the
+last error message reported by perl and all of the errors that you see
+will be something that actually needs to be fixed.
+.IP \(bu 4
+Error messages that output class or package names have been modified to
+output double quoted strings with various characters escaped so as to
+make the exact value clear to a reader. The exact rules on which
+characters are escaped may change over time but currently are that
+printable ASCII codepoints, with the exception of \f(CW\*(C`"\*(C'\fR and \f(CW\*(C`\e\*(C'\fR, and
+unicode word characters whose codepoint is over 255 are output raw, and
+any other symbols are escaped much as Data::Dumper might escape them,
+using \f(CW\*(C`\en\*(C'\fR for newline and \f(CW\*(C`\e"\*(C'\fR for double quotes, etc. Codepoints in
+the range 128\-255 are always escaped as they can cause trouble on
+unicode terminals when output raw.
+.Sp
+In older versions of perl the one liner
+.Sp
+.Vb 1
+\&    $ perl \-le\*(Aq"thing\en"\->foo()\*(Aq
+.Ve
+.Sp
+would output the following error message exactly as shown here, with
+text spread over multiple lines because the "\en" would be emitted as
+a raw newline character:
+.Sp
+.Vb 3
+\&    Can\*(Aqt locate object method "foo" via package "thing
+\&    " (perhaps you forgot to load "thing
+\&    "?) at \-e line 1.
+.Ve
+.Sp
+As of this release we would output this instead (as one line):
+.Sp
+.Vb 2
+\&    Can\*(Aqt locate object method "foo" via package "thing\en"
+\&      (perhaps you forgot to load "thing\en"?) at \-e line 1.
+.Ve
+.Sp
+Notice the newline in the package name has been quoted and escaped, and
+thus the error message is a single line. The text is shown here wrapped
+to two lines only for readability.
+.IP \(bu 4
+When package or class names in errors are very large the middle excess
+portion will be elided from the message. As of this release error messages
+will show only up to the first 128 characters and the last 128 characters
+in a package or class name in error messages. For example
+.Sp
+.Vb 1
+\& $ perl \-le\*(Aq("Foo" x 1000)\->new()\*(Aq
+.Ve
+.Sp
+will output the following as one line:
+.Sp
+.Vb 10
+\& Can\*(Aqt locate object method "new" via package "FooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFooFo"..."oFooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFoo" (perhaps you forgot to load
+\& "FooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFo"...
+\& "oFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFoo
+\& FooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFooFoo"?)
+\& at \-e line 1.
+.Ve
+.Sp
+Notice the \f(CW "prefix"..."suffix" \fR form of the package name in this case.
+In previous versions of perl the complete string would have been shown
+making the error message over 6k long and there was no upper limit on the
+length of the error message at all. If you accidentally used a 1MB string
+as a class name then the error message would be over 2MB long. In this perl
+the upper limit should be around 2k when eliding and escaping are taken into
+account.
+.IP \(bu 4
+Removed \f(CW\*(C`Complex regular subexpression recursion limit (%d) exceeded\*(C'\fR
+.Sp
+The regular expresion engine has not used recursion in some time. This
+warning no longer makes sense.
+.Sp
+See [GH #19636 <https://github.com/Perl/perl5/pull/19636>].
+.IP \(bu 4
+Various warnings that used to produce parenthesized hints underneath the
+main warning message and after its "location data" were chanaged to put
+the hint inline with the main message. For instance:
+.Sp
+.Vb 2
+\& Bareword found where operator expected at \-e line 1, near "foo bar"
+\&     (Do you need to predeclare foo?)
+.Ve
+.Sp
+will now look like this but as one line:
+.Sp
+.Vb 2
+\& Bareword found where operator expected (Do you need to predeclare
+\& foo?) at \-e line 1, near "foo bar"
+.Ve
+.Sp
+as a result such warnings will no longer trigger \f(CW$SIG{_\|_WARN_\|_}\fR
+twice, and the hint will be visible when fatal warnings is in effect.
+.IP \(bu 4
+The error message that is produced when a \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR statement
+fails has been changed. It used to contain the words \f(CW\*(C`@INC contains:\*(C'\fR,
+and it used to show the state of \f(CW@INC\fR *after* the require had
+completed and failed. The error message has been changed to say \f(CW\*(C`@INC
+entries checked:\*(C'\fR and to reflect the actual directories or hooks that
+were executed during the require statement. For example:
+.Sp
+.Vb 4
+\&    perl \-e\*(Aqpush @INC, sub {@INC=()}; eval "require Frobnitz"
+\&        or die $@\*(Aq
+\&    Can\*(Aqt locate Frobnitz.pm in @INC (you may need to install the
+\&    Frobnitz module) (@INC contains:) at (eval 1) line 1.
+.Ve
+.Sp
+Will change to (with some output elided for clarity):
+.Sp
+.Vb 7
+\&    perl \-e\*(Aqpush @INC, sub {@INC=()}; eval "require Frobnitz"
+\&        or die $@\*(Aq
+\&    Can\*(Aqt locate Frobnitz.pm in @INC (you may need to install the
+\&    Frobnitz module) (@INC entries checked:
+\&    .../site_perl/5.38.0/x86_64\-linux .../site_perl/5.38.0
+\&    .../5.38.0/x86_64\-linux .../5.38.0 CODE(0x562745e684b8))
+\&    at (eval 1) line 1.
+.Ve
+.Sp
+thus showing the actual directories checked. Code that checks for
+\&\f(CW\*(C`@INC contains:\*(C'\fR in error messages should be hardened against any future
+wording changes between the \f(CW@INC\fR and \f(CW\*(C`:\*(C'\fR, for instance use
+\&\f(CW\*(C`qr/\e@INC[ \ew]+:/\*(C'\fR instead of using \f(CW\*(C`qr/\e@INC contains:/\*(C'\fR or
+\&\f(CW\*(C`qr/\e@INC entries checked:/\*(C'\fR in tests as this will ensure both forward
+and backward compatibility.
+.IP \(bu 4
+Old package separator used in string
+.Sp
+This diagnostic is now also part of the \f(CW\*(C`deprecated\*(C'\fR category.
+.IP \(bu 4
+given is deprecated replaces \f(CW\*(C`given is experimental\*(C'\fR.
+.IP \(bu 4
+when is deprecated replaces \f(CW\*(C`when is experimental\*(C'\fR.
+.IP \(bu 4
+Smartmatch is deprecated replaces \f(CW\*(C`Smartmatch is experimental\*(C'\fR.
+.SH "Configuration and Compilation"
+.IX Header "Configuration and Compilation"
+.IP \(bu 4
+\&\f(CW\*(C`make \-j6 minitest\*(C'\fR could fail due to a build conflict in building
+\&\f(CW\*(C`$(MINIPERL_EXE)\*(C'\fR between the main make process and a child process.
+[GH #19829 <https://github.com/Perl/perl5/issues/19829>]
+.IP \(bu 4
+Properly populate osvers on Dragonfly BSD when the hostname isn't set.
+.IP \(bu 4
+Fix typos for C99 macro name \f(CW\*(C`PRIX64\*(C'\fR.
+.IP \(bu 4
+Remove ancient and broken GCC for VMS support
+.IP \(bu 4
+Remove vestigial reference to \f(CW\*(C`/VAXC\*(C'\fR qualifier
+.IP \(bu 4
+Remove sharedperl option on VMS
+.IP \(bu 4
+VMS now has mkostemp
+.IP \(bu 4
+\&\f(CW\*(C`Configure\*(C'\fR now properly handles quoted elements outputted by gcc.
+[GH #20606 <https://github.com/Perl/perl5/issues/20606>]
+.IP \(bu 4
+\&\f(CW\*(C`Configure\*(C'\fR probed for the return type of \fBmalloc()\fR and \fBfree()\fR by
+testing whether declarations for those functions produced a function
+type mismatch with the implementation.  On Solaris, with a C++
+compiler, this check always failed, since Solaris instead imports
+\&\fBmalloc()\fR and \fBfree()\fR from \f(CW\*(C`std::\*(C'\fR with \f(CW\*(C`using\*(C'\fR for C++ builds.  Since
+the return types of \fBmalloc()\fR and \fBfree()\fR are well defined by the C
+standard, skip probing for them.  \f(CW\*(C`Configure\*(C'\fR command-line arguments
+and hints can still override these type in the unlikely case that is
+needed.  [GH #20806 <https://github.com/Perl/perl5/issues/20806>]
+.SH Testing
+.IX Header "Testing"
+Tests were added and changed to reflect the other additions and
+changes in this release.  Furthermore, these significant changes were
+made:
+.IP \(bu 4
+Unicode normalization tests have been added.
+.IP \(bu 4
+t/test.pl: Add ability to cancel an watchdog timer
+.SH "Platform Support"
+.IX Header "Platform Support"
+.SS "Discontinued Platforms"
+.IX Subsection "Discontinued Platforms"
+.IP Ultrix 4
+.IX Item "Ultrix"
+Support code for DEC Ultrix has been removed.  Ultrix was the native
+Unix-like operating system for various Digital Equipment Corporation
+machines.  Its final release was in 1995.
+.SS "Platform-Specific Notes"
+.IX Subsection "Platform-Specific Notes"
+.IP DragonflyBSD 4
+.IX Item "DragonflyBSD"
+Skip tests to workaround an apparent bug in \f(CWsetproctitle()\fR.
+[GH #19894 <https://github.com/Perl/perl5/issues/19894>]
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+FreeBSD no longer uses thread-safe locale operations, to avoid a bug in
+FreeBSD <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=265950>
+.Sp
+Replace the first part of archname with \f(CW\*(C`uname \-p\*(C'\fR
+[GH #19791 <https://github.com/Perl/perl5/issues/19791>]
+.IP Solaris 4
+.IX Item "Solaris"
+Avoid some compiler and compilation issues on NetBSD/Solaris from regexec.c and regcomp.c.
+.IP Synology 4
+.IX Item "Synology"
+Update Synology Readme for DSM 7.
+.IP Windows 4
+.IX Item "Windows"
+Fix win32 memory alignment needed for gcc\-12 from vmem.h.
+.Sp
+\&\fButimes()\fR on Win32 would print a message to stderr if it failed to
+convert a supplied \f(CW\*(C`time_t\*(C'\fR to to a \f(CW\*(C`FILETIME\*(C'\fR.
+[GH #19668 <https://github.com/Perl/perl5/issues/19668>]
+.Sp
+In some cases, timestamps returned by \fBstat()\fR and
+\&\fBlstat()\fR failed to take daylight saving time into account.
+[GH #20018 <https://github.com/Perl/perl5/issues/20018>]
+[GH #20061 <https://github.com/Perl/perl5/issues/20061>]
+.Sp
+\&\fBstat()\fR now works on \f(CW\*(C`AF_UNIX\*(C'\fR socket files.
+[GH #20204 <https://github.com/Perl/perl5/issues/20204>]
+.Sp
+\&\fBreadlink()\fR now returns the \f(CW\*(C`PrintName\*(C'\fR from a symbolic link reparse
+point instead of the \f(CW\*(C`SubstituteName\*(C'\fR, which should make it better
+match the name the link was created with.
+[GH #20271 <https://github.com/Perl/perl5/pull/20271>]
+.Sp
+\&\fBlstat()\fR on Windows now returns the length of the link target as the
+size of the file, as it does on POSIX systems.
+[GH #20476 <https://github.com/Perl/perl5/issues/20476>]
+.Sp
+\&\fBsymlink()\fR on Windows now replaces any \f(CW\*(C`/\*(C'\fR in the target with \f(CW\*(C`\e\*(C'\fR,
+since Windows does not recognise \f(CW\*(C`/\*(C'\fR in symbolic links.  The reverse
+translation is \fBnot\fR done by \fBreadlink()\fR.
+[GH #20506 <https://github.com/Perl/perl5/issues/20506>]
+.Sp
+\&\fBsymlink()\fR where the target was an absolute path to a directory was
+incorrectly created as a file symbolic link.
+[GH #20533 <https://github.com/Perl/perl5/issues/20533>]
+.Sp
+\&\f(CW\*(C`POSIX::dup2\*(C'\fR no longer creates broken sockets. [GH
+#20920 <https://github.com/Perl/perl5/issues/20920>]
+.Sp
+Closing a busy pipe could cause Perl to hang. [GH
+#19963 <https://github.com/Perl/perl5/issues/19963>]
+.SH "Internal Changes"
+.IX Header "Internal Changes"
+.IP \(bu 4
+Removed many deprecated C functions.
+.Sp
+These have been deprecated for a long time. See
+<https://github.com/perl/perl5/commit/7008caa915ad99e650acf2aea40612b5e48b7ba2>
+for a full list.
+.IP \(bu 4
+\&\f(CW\*(C`get_op_descs\*(C'\fR, \f(CW\*(C`get_op_names\*(C'\fR, \f(CW\*(C`get_opargs\*(C'\fR, \f(CW\*(C`get_no_modify\*(C'\fR and
+\&\f(CW\*(C`get_ppaddr\*(C'\fR have been marked deprecated.
+.IP \(bu 4
+\&\f(CW\*(C`hv_free_ent\*(C'\fR has been marked as internal API.
+.IP \(bu 4
+\&\f(CW\*(C`save_pushptr\*(C'\fR, \f(CW\*(C`save_pushptrptr\*(C'\fR, and \f(CW\*(C`save_pushi32ptr\*(C'\fR have been marked
+as internal API.
+.IP \(bu 4
+New bool related functions and macros have been added to complement the new
+bool type introduced in 5.36:
+.Sp
+The functions are:
+.RS 4
+.ie n .IP """newSVbool(const bool bool_val)""" 4
+.el .IP "\f(CWnewSVbool(const bool bool_val)\fR" 4
+.IX Item "newSVbool(const bool bool_val)"
+.PD 0
+.ie n .IP newSV_true() 4
+.el .IP \f(CWnewSV_true()\fR 4
+.IX Item "newSV_true()"
+.ie n .IP newSV_false() 4
+.el .IP \f(CWnewSV_false()\fR 4
+.IX Item "newSV_false()"
+.ie n .IP """sv_set_true(SV *sv)""" 4
+.el .IP "\f(CWsv_set_true(SV *sv)\fR" 4
+.IX Item "sv_set_true(SV *sv)"
+.ie n .IP """sv_set_false(SV *sv)""" 4
+.el .IP "\f(CWsv_set_false(SV *sv)\fR" 4
+.IX Item "sv_set_false(SV *sv)"
+.ie n .IP """sv_set_bool(SV *sv, const bool bool_val)""" 4
+.el .IP "\f(CWsv_set_bool(SV *sv, const bool bool_val)\fR" 4
+.IX Item "sv_set_bool(SV *sv, const bool bool_val)"
+.RE
+.RS 4
+.PD
+.Sp
+The macros are:
+.ie n .IP SvIandPOK(sv) 4
+.el .IP \f(CWSvIandPOK(sv)\fR 4
+.IX Item "SvIandPOK(sv)"
+.PD 0
+.ie n .IP SvIandPOK_off(sv) 4
+.el .IP \f(CWSvIandPOK_off(sv)\fR 4
+.IX Item "SvIandPOK_off(sv)"
+.ie n .IP """SvIandPOK_on""" 4
+.el .IP \f(CWSvIandPOK_on\fR 4
+.IX Item "SvIandPOK_on"
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+.PD
+Perl is no longer manipulating the \f(CW\*(C`environ\*(C'\fR array directly. The variable
+\&\f(CW\*(C`PL_use_safe_putenv\*(C'\fR has been removed and \f(CW\*(C`PERL_USE_SAFE_PUTENV\*(C'\fR is always
+defined. This means XS modules can now call \f(CW\*(C`setenv\*(C'\fR and \f(CW\*(C`putenv\*(C'\fR without
+causing segfaults. [perl #19399 <https://github.com/Perl/perl5/issues/19399>]
+.IP \(bu 4
+Internal C API functions are now hidden with \f(CW\*(C`_\|_attribute_\|_((hidden))\*(C'\fR on the
+platforms that support it. This means they are no longer callable from XS
+modules on those platforms.
+.Sp
+It should be noted that those functions have always been hidden on Windows. This
+change merely brings that to the other platforms.
+[perl #19655 <https://github.com/Perl/perl5/pull/19655>]
+.IP \(bu 4
+New formatting symbols were added for printing values declared as \f(CW\*(C`U32\*(C'\fR or
+\&\f(CW\*(C`I32\*(C'\fR:
+.RS 4
+.ie n .IP "I32df \-\- Like %d" 4
+.el .IP "I32df \-\- Like \f(CW%d\fR" 4
+.IX Item "I32df -- Like %d"
+.PD 0
+.ie n .IP "U32of \-\- Like %o" 4
+.el .IP "U32of \-\- Like \f(CW%o\fR" 4
+.IX Item "U32of -- Like %o"
+.ie n .IP "U32uf \-\- Like %u" 4
+.el .IP "U32uf \-\- Like \f(CW%u\fR" 4
+.IX Item "U32uf -- Like %u"
+.ie n .IP "U32xf \-\- Like %x" 4
+.el .IP "U32xf \-\- Like \f(CW%x\fR" 4
+.IX Item "U32xf -- Like %x"
+.ie n .IP "U32Xf \-\- Like %X" 4
+.el .IP "U32Xf \-\- Like \f(CW%X\fR" 4
+.IX Item "U32Xf -- Like %X"
+.RE
+.RS 4
+.PD
+.Sp
+These are used in the same way already existing similar symbols, such as
+\&\f(CW\*(C`IVdf\*(C'\fR, are used.  See "I/O Formats" in perlapi.
+.RE
+.IP \(bu 4
+new 'HvHasAUX' macro
+.IP \(bu 4
+regexec.c: Add some branch predictions reorder conds
+.IP \(bu 4
+locale: Change macro name to be C conformant
+.IP \(bu 4
+Rename the \f(CW\*(C`PADNAMEt_*\*(C'\fR constants to \f(CW\*(C`PADNAMEf_*\*(C'\fR
+.IP \(bu 4
+Changes all the API macros that retrieve a PV into a call to an
+inline function so as to evaluate the parameter just once.
+.IP \(bu 4
+regexec.c: multiple code refactor to make the code more readable
+.IP \(bu 4
+perl.h: Change macro name to be C conformant
+(remove leading _ from NOT_IN_NUMERIC macros)
+.IP \(bu 4
+regcomp.h: add new \f(CW\*(C`BITMAP_BIT\*(C'\fR macro in addition to the existing \f(CW\*(C`BITMAP_BYTE\*(C'\fR
+and \f(CW\*(C`BITMAP_TEST\*(C'\fR ones.
+.IP \(bu 4
+Create new regnode type ANYOFH.
+populate_ANYOF_from_invlist was renamed to populate_bitmap_from_invlist
+.IP \(bu 4
+regex: Refactor bitmap vs non-bitmap of qr/[]/
+.IP \(bu 4
+regcomp.c: add new functions to convert from an inversion list to a bitmap (and vice versa)
+\&\f(CW\*(C`populate_bitmap_from_invlist\*(C'\fR and \f(CW\*(C`populate_invlist_from_bitmap\*(C'\fR.
+.IP \(bu 4
+Add \f(CWnewAVav()\fR to create an AV from an existing AV.
+Add \f(CWnewAVhv()\fR to create an AV using keys and values from an existing HV.
+.IP \(bu 4
+Fix definition of \f(CW\*(C`Perl_atof\*(C'\fR.
+.IP \(bu 4
+Fix undefined behavior with overflow related \f(CW\*(C`OPTIMIZE_INFTY\*(C'\fR and delta
+in \fIregcomp.c\fR.
+.IP \(bu 4
+Fix regnode pointer alignment issue in \fIregcomp.h\fR.
+.IP \(bu 4
+The \f(CW\*(C`CVf_METHOD\*(C'\fR CV flag and associated \f(CW\*(C`CvMETHOD\*(C'\fR macro has been renamed to
+\&\f(CW\*(C`CVf_NOWARN_AMBIGUOUS\*(C'\fR and \f(CW\*(C`CvNOWARN_AMBIGUOUS\*(C'\fR. This closer reflects its
+actual behaviour (it suppresses a warning that would otherwise be generated
+about ambiguous names), in order to be less confusing with \f(CW\*(C`CvIsMETHOD\*(C'\fR,
+which indicates that a CV is a \f(CW\*(C`method\*(C'\fR subroutine relating to the \f(CW\*(C`class\*(C'\fR
+feature.
+.IP \(bu 4
+The \f(CW\*(C`OPf_SPECIAL\*(C'\fR flag is no longer set on the \f(CW\*(C`OP_ENTERSUB\*(C'\fR op
+constructed to call the \f(CW\*(C`VERSION\*(C'\fR, \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`unimport\*(C'\fR methods
+as part of a \f(CW\*(C`use\*(C'\fR statement and attribute application, nor when
+assigning to an \f(CW\*(C`:lvalue\*(C'\fR subroutine.
+.IP \(bu 4
+A new CV flag \f(CW\*(C`CVf_REFCOUNTED_ANYSV\*(C'\fR has been added, which indicates that the
+CV is an XSUB and stores an SV pointer in the \f(CW\*(C`CvXSUBANY.any_sv\*(C'\fR union field.
+Perl core operations such as cloning or destroying the CV will maintain the
+reference count of the pointed-to SV, destroying it when required.
+.IP \(bu 4
+A new API function "\f(CW\*(C`Perl_localeconv\*(C'\fR" in perlapi is added.  This is the
+same as \f(CW\*(C`POSIX::localeconv\*(C'\fR (returning a hash of
+the \f(CWlocaleconv()\fR fields), but directly callable from XS code.
+.IP \(bu 4
+A new API function, "\f(CW\*(C`Perl_langinfo8\*(C'\fR" in perlapi is added.  This is the
+same as plain "\f(CW\*(C`Perl_langinfo\*(C'\fR" in perlapi, but with an extra parameter
+that allows the caller to simply and reliably know if the returned
+string is UTF\-8.
+.IP \(bu 4
+We have introduced a limit on the number of nested \f(CW\*(C`eval EXPR\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR
+blocks and \f(CW\*(C`require\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR (and thus \f(CW\*(C`use\*(C'\fR statements as well) to
+prevent C stack overflows. This variable can also be used to forbid
+\&\f(CW\*(C`BEGIN\*(C'\fR blocks from executing during \f(CW\*(C`eval EXPR\*(C'\fR compilation. The
+limit defaults to \f(CW1000\fR but can be overridden by setting the
+\&\f(CW\*(C`${^MAX_NESTED_EVAL_BEGIN_BLOCKS}\*(C'\fR variable. The default itself can be
+changed at compile time with
+.Sp
+.Vb 1
+\&    \-Accflags=\*(Aq\-DPERL_MAX_NESTED_EVAL_BEGIN_BLOCKS_DEFAULT=12345\*(Aq
+.Ve
+.Sp
+Note that this value relates to the size of your C stack and if you
+choose an inappropriately large value Perl may segfault, be conservative
+about what you choose.
+.IP \(bu 4
+A new magic type \f(CW\*(C`PERL_MAGIC_extvalue\*(C'\fR has been added. This is available for
+use like \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR, but is a value magic: upon localization the new
+value will not be magical.
+.IP \(bu 4
+The \f(CWSSNEW()\fR, \f(CWSSNEWt()\fR, \f(CWSSNEWa()\fR and \f(CWSSNEWat()\fR APIs now
+return a \f(CW\*(C`SSize_t\*(C'\fR value.  The \f(CWSSPTR()\fR and \f(CWSSPTRt()\fR macros now
+expect a \f(CW\*(C`SSize_t\*(C'\fR parameter, and enforce that on debugging builds.
+[GH #20411 <https://github.com/Perl/perl5/issues/20411>]
+.IP \(bu 4
+Filenames in cops are now refcounted under threads.
+Under threads we were copying the filenames into each opcode. This is because in
+theory opcodes created in one thread can be destroyed in another.
+The change adds a new struct/type \f(CW\*(C`RCPV\*(C'\fR, which is a refcounted
+string using shared memory. This is implemented in such a way that code
+that previously used a char * can continue to do so, as the refcounting
+data is located a specific offset before the char * pointer itself.
+.IP \(bu 4
+Added \f(CW\*(C`HvNAMEf\*(C'\fR and \f(CW\*(C`HvNAMEf_QUOTEDPREFIX\*(C'\fR special formats. They take an
+\&\f(CW\*(C`HV *\*(C'\fR as an argument and use \f(CWHvNAME()\fR and related macros to determine the
+string, its length, and whether it is utf8.
+.IP \(bu 4
+The underlying \f(CW\*(C`Perl_dowantarray\*(C'\fR function implementing the
+long-deprecated \f(CW\*(C`GIMME\*(C'\fR macro has been marked as
+deprecated, so that use of the macro emits a compile-time warning.
+\&\f(CW\*(C`GIMME\*(C'\fR has been documented as deprecated in favour of
+\&\f(CW\*(C`GIMME_V\*(C'\fR since Perl v5.6.0, but had not
+previously issued a warning.
+.IP \(bu 4
+The API function "utf8_length" in perlapi is now more efficient.
+.IP \(bu 4
+Added \f(CWSAVERCPV()\fR and \f(CWSAVEFREERCPV()\fR for better support for working
+with \f(CW\*(C`RCPV\*(C'\fR (reference counted string/pointer value) structures which
+currently are used in opcodes to share filename and warning bit data in
+a memory efficient manner.
+.IP \(bu 4
+Added \f(CWMORTALSVFUNC_SV()\fR and \f(CWMORTALDESTRUCTOR_SV()\fR macros, which
+make it possible to create a destructor which is fired at the end of
+the current statement. This uses the \f(CW\*(C`PERL_MAGIC_destruct\*(C'\fR magic to
+use "free" magic to trigger an action when a variable is freed. The
+action can be specified as a C function or as a Perl code reference.
+.IP \(bu 4
+Added the \f(CW\*(C`%{^HOOK}\*(C'\fR api and related \f(CW\*(C`PERL_MAGIC_hook\*(C'\fR and
+\&\f(CW\*(C`PERL_MAGIC_hookelem\*(C'\fR for providing ways to hook selected perl functions
+which for one reason or another are problematic to wrap with a customized
+subroutine.
+.IP \(bu 4
+Added support for \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR which can be used to
+rewrite the filename that \f(CW\*(C`require\*(C'\fR will try to load, and also to block
+\&\f(CW\*(C`require\*(C'\fR from loading a specific module, even via fully qualified
+filename. The hook can also be used to perform "pre-require" and
+"post-require" actions.
+.IP \(bu 4
+Added support for \f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR which can be used to
+track what modules have been required after the fact.
+.IP \(bu 4
+Regular expression opcodes (regops) now use a standardized structure
+layout that uses unions to expose data in different format. This means
+it should be much easier to extend or modify regops to use more memory.
+This has been used to make a number of regops track how many parens
+they contain.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+Avoid recursion and stack overflow parsing 'pack' template
+.Sp
+[GH #16319 <https://github.com/Perl/perl5/issues/16319>]
+.IP \(bu 4
+An \fBeval()\fR as the last statement in a regex code block could trigger an
+interpreter panic; e.g.
+.Sp
+.Vb 1
+\&    /(?{ ...; eval {....}; })/
+.Ve
+.Sp
+[GH #19680 <https://github.com/Perl/perl5/issues/19680>]
+.IP \(bu 4
+Disabling the \f(CW\*(C`bareword_filehandles\*(C'\fR feature no longer treats \f(CW\*(C`print
+Class\->method\*(C'\fR as an error.  [GH #19704 <https://github.com/Perl/perl5/issues/19704>]
+.IP \(bu 4
+When a Perl subroutine tail-calls an XS subroutine using \f(CW\*(C`goto &xs_sub\*(C'\fR,
+the XS subroutine can now correctly determine its calling context.
+Previously it was always reported as scalar.
+.Sp
+In addition, where the Perl subroutine is freed at the same time:
+.Sp
+.Vb 1
+\&    sub foo { *foo = sub {}; goto &xs_sub }
+.Ve
+.Sp
+this formerly could lead to crashes if the XS subroutine tried to use the
+value of \f(CW\*(C`PL_op\*(C'\fR, since this was being set to NULL. This is now fixed.
+.Sp
+[GH #19936 <https://github.com/Perl/perl5/issues/19936>]
+.IP \(bu 4
+\&\fBsetsockopt()\fR now uses the mechanism added in 5.36 to better
+distinguish between numeric and string values supplied as the
+\&\f(CW\*(C`OPTVAL\*(C'\fR parameter.  [GH #18761 <https://github.com/Perl/perl5/issues/18761>]
+.IP \(bu 4
+4\-argument \f(CWselect()\fR now rejects strings with code points above
+255. Additionally, for code points 128\-255, this operator will now always
+give the corresponding octet to the OS, regardless of how Perl stores
+such code points in memory. (Previously Perl leaked its internal string
+storage to the OS.) [GH #19882 <https://github.com/Perl/perl5/issues/19882>]
+.IP \(bu 4
+Fix panic issue from \f(CW\*(C`val {} inside /(?{...})/\*(C'\fR [GH #19390 <https://github.com/Perl/perl5/issues/19390>]
+.IP \(bu 4
+Fix multiple compiler warnings from \fIregexp.c\fR, \fIlocale.c\fR
+[GH #19915 <https://github.com/Perl/perl5/issues/19915>]
+.IP \(bu 4
+Fix a bug with querying locales on platforms that don't have \f(CW\*(C`LC_NUMERIC\*(C'\fR
+[GH #19890 <https://github.com/Perl/perl5/issues/19890>]
+.IP \(bu 4
+Prevent undefined behaviour in \f(CWS_maybe_multideref()\fR.
+.IP \(bu 4
+Avoid signed integer overflow in \f(CW\*(C`use integer\*(C'\fR ops.
+.IP \(bu 4
+Avoid adding an offset to a NULL pointer in \f(CW\*(C`hv_delete_common\*(C'\fR.
+.IP \(bu 4
+PerlIO::get_layers will now accept IO references too
+.Sp
+Previously it would only take glob references or names of globs. Now it will
+also accept IO references.
+.IP \(bu 4
+Fixes to memory handling for \f(CW\*(C`PL_splitstr\*(C'\fR:
+.RS 4
+.IP \(bu 4
+If a thread was created the allocated string would be freed twice.
+.IP \(bu 4
+If two \f(CW\*(C`\-F\*(C'\fR switches were supplied the memory allocated for the first
+switch wouldn't be freed.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Correctly handle \f(CW\*(C`OP_ANONCODE\*(C'\fR ops generated by CPAN modules that
+don't include the OPf_REF flag when propagating lvalue context.
+[GH #20532 <https://github.com/Perl/perl5/pull/20532>]
+.IP \(bu 4
+POSIX::strxfrm now uses the \f(CW\*(C`LC_CTYPE\*(C'\fR locale category
+to specify its collation, ignoring any differing \f(CW\*(C`LC_COLLATE\*(C'\fR.  It
+doesn't make sense for a string to be encoded in one locale (say,
+ISO\-8859\-6, Arabic) and to collate it based on another (like ISO\-8859\-7,
+Greek).  Perl assumes that the current \f(CW\*(C`LC_CTYPE\*(C'\fR locale correctly
+represents the encoding, and collates accordingly.
+.Sp
+Also, embedded \f(CW\*(C`NUL\*(C'\fR characters are now allowed in the input.
+.Sp
+If locale collation is not enabled on the platform (\f(CW\*(C`LC_COLLATE\*(C'\fR), the
+input is returned unchanged.
+.IP \(bu 4
+Double FETCH during stringification of tied scalars returning an
+overloaded object have been fixed. The FETCH method should only be
+called once, but prior to this release was actually called twice.
+[GH #20574 <https://github.com/Perl/perl5/pull/20574>]
+.IP \(bu 4
+Writing to a magic variables associated with the selected output
+handle, \f(CW$^\fR, \f(CW$~\fR, \f(CW$=\fR, \f(CW\*(C`$\-\*(C'\fR and \f(CW$%\fR, no longer crashes perl
+if the IO object has been cleared from the selected output
+handle. [GH #20733 <https://github.com/Perl/perl5/issues/20733>]
+.IP \(bu 4
+Redefining a \f(CW\*(C`use constant\*(C'\fR list constant with \f(CW\*(C`use constant\*(C'\fR now
+properly warns.  This changes the behaviour of \f(CW\*(C`use constant\*(C'\fR but is
+a core change, not a change to \fIconstant.pm\fR.  [GH #20742 <https://github.com/Perl/perl5/issues/20742>]
+.IP \(bu 4
+Redefining a \f(CW\*(C`use constant\*(C'\fR list constant with an empty prototype
+constant sub would result in an assertion failure.  [GH #20742 <https://github.com/Perl/perl5/issues/20742>]
+.IP \(bu 4
+Fixed a regression where the \f(CW\*(C`INC\*(C'\fR method for objects in \f(CW@INC\fR
+would not be resolved by \f(CW\*(C`AUTOLOAD\*(C'\fR, while it was in 5.36.  The
+\&\f(CW\*(C`INCDIR\*(C'\fR method for objects in \f(CW@INC\fR cannot be resolved by
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR as \f(CW\*(C`INC\*(C'\fR would have been resolved first.  [GH #20665 <https://github.com/Perl/perl5/issues/20665>]
+.IP \(bu 4
+\&\f(CW$SIG{_\|_DIE_\|_}\fR will now be called from eval when the code dies during
+compilation regardless of how it dies. This means that code expecting to
+be able to upgrade \f(CW$@\fR into an object will be called consistently. In
+earlier versions of perl \f(CW$SIG{_\|_DIE_\|_}\fR would not be called for
+certain compilation errors, for instance undeclared variables. For other
+errors it might be called if there were more than a certain number of
+errors, but not if there were less. Now you can expect that it will be
+called in every case.
+.IP \(bu 4
+Compilation of code with errors used to inconsistently stop depending on
+the count and type of errors encountered. The intent was that after 10
+errors compilation would halt, but bugs in this logic meant that certain
+types of error would be counted, but would not trigger the threshold
+check to stop compilation. Other errors would. With this release after
+at most 10 errors compilation will terminate, regardless of what type of
+error they were.
+.Sp
+Note that you can change the maximum count by defining
+\&\f(CW\*(C`PERL_STOP_PARSING_AFTER_N_ERRORS\*(C'\fR to be something else during the
+configuration process. For instance
+.Sp
+.Vb 1
+\&    ./Configure ... \-Accflags=\*(Aq\-DPERL_STOP_PARSING_AFTER_N_ERRORS=100\*(Aq
+.Ve
+.Sp
+would allow up to 100 errors.
+.IP \(bu 4
+The API function "my_snprintf" in perlapi now prints a non-dot decimal
+point if the perl code it ultimately is called from is in the scope of
+\&\f(CW\*(C`use locale\*(C'\fR and the locale in effect calls for that.
+.IP \(bu 4
+A number of bugs related to capture groups in quantified groups in regular
+expression have been fixed, especially in alternations. For example in
+a pattern like:
+.Sp
+.Vb 1
+\&        "foobazfoobar" =~ /((foo)baz|foo(bar))+/
+.Ve
+.Sp
+the regex variable \f(CW$2\fR will not be "foo" as it once was, it will be undef.
+.IP \(bu 4
+Bugs with regex backreference operators that are inside of a capture
+group have been fixed. For instance:
+.Sp
+.Vb 1
+\&    "xa=xaaa" =~ /^(xa|=?\e1a){2}\ez/
+.Ve
+.Sp
+will now correctly not match. [GH #10073 <https://github.com/Perl/perl5/issues/10073>]
+.IP \(bu 4
+\&\f(CWSSGROW()\fR and \f(CWSSCHECK()\fR have been reworked to ensure that the requested
+space is actually allocated. \f(CWSSCHECK()\fR is now an alias for \f(CWSSGROW()\fR.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.38.0 represents approximately 12 months of development since Perl
+5.36.0 and contains approximately 290,000 lines of changes across 1,500
+files from 100 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 190,000 lines of changes to 970 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.38.0:
+.PP
+Alex, Alexander Nikolov, Alex Davies, Andreas König, Andrew Fresh, Andrew
+Ruthven, Andy Lester, Aristotle Pagaltzis, Arne Johannessen, A. Sinan Unur,
+Bartosz Jarzyna, Bart Van Assche, Benjamin Smith, Bram, Branislav
+Zahradník, Brian Greenfield, Bruce Gray, Chad Granum, Chris 'BinGOs'
+Williams, chromatic, Clemens Wasser, Craig A. Berry, Dagfinn Ilmari
+Mannsåker, Dan Book, danielnachun, Dan Jacobson, Dan Kogai, David Cantrell,
+David Golden, David Mitchell, E. Choroba, Ed J, Ed Sabol, Elvin Aslanov,
+Eric Herman, Felipe Gasper, Ferenc Erki, Firas Khalil Khana, Florian Weimer,
+Graham Knop, Håkon Hægland, Harald Jörg, H.Merijn Brand, Hugo van der
+Sanden, James E Keenan, James Raspass, jkahrman, Joe McMahon, Johan Vromans,
+Jonathan Stowe, Jon Gentle, Karen Etheridge, Karl Williamson, Kenichi
+Ishigaki, Kenneth Ölwing, Kurt Fitzner, Leon Timmermans, Li Linjie, Loren
+Merritt, Lukas Mai, Marcel Telka, Mark Jason Dominus, Mark Shelor, Matthew
+Horsfall, Matthew O. Persico, Mattia Barbon, Max Maischein, Mohammad S
+Anwar, Nathan Mills, Neil Bowers, Nicholas Clark, Nicolas Mendoza, Nicolas
+R, Paul Evans, Paul Marquess, Peter John Acklam, Peter Levine, Philippe
+Bruhat (BooK), Reini Urban, Renee Baecker, Ricardo Signes, Richard Leach,
+Russ Allbery, Scott Baker, Sevan Janiyan, Sidney Markowitz, Sisyphus, Steve
+Hay, TAKAI Kousuke, Todd Rinaldo, Tomasz Konojacki, Tom Stellard, Tony Cook,
+Tsuyoshi Watanabe, Unicode Consortium, vsfos, Yves Orton, Zakariyya Mughal,
+Zefram, �鸡.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5381delta.1 b/upstream/mageia-cauldron/man1/perl5381delta.1
new file mode 100644
index 00000000..295e2242
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5381delta.1
@@ -0,0 +1,160 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5381DELTA 1"
+.TH PERL5381DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl5381delta \- what is new for perl v5.38.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.38.0 release and the 5.38.1
+release.
+.PP
+If you are upgrading from an earlier release such as 5.37.0, first read
+perl5380delta, which describes differences between 5.37.0 and 5.38.0.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.38.1 represents approximately 5 months of development since Perl
+5.38.0 and contains approximately 6,100 lines of changes across 34 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,300 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.38.1:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl5382delta.1 b/upstream/mageia-cauldron/man1/perl5382delta.1
new file mode 100644
index 00000000..77420258
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl5382delta.1
@@ -0,0 +1,161 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5382DELTA 1"
+.TH PERL5382DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldelta \- what is new for perl v5.38.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.38.0 release and the 5.38.2
+release.  \fBPlease note:\fR This document ignores Perl 5.38.1, a broken release
+which existed for a couple of days only.
+.PP
+If you are upgrading from an earlier release such as 5.37.0, first read
+perl5380delta, which describes differences between 5.37.0 and 5.38.0.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.38.2 represents approximately 5 months of development since Perl
+5.38.0 and contains approximately 6,100 lines of changes across 34 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,300 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.38.2:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl561delta.1 b/upstream/mageia-cauldron/man1/perl561delta.1
new file mode 100644
index 00000000..445d5d87
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl561delta.1
@@ -0,0 +1,3386 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL561DELTA 1"
+.TH PERL561DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl561delta \- what's new for perl v5.6.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.005 release and the 5.6.1
+release.
+.SH "Summary of changes between 5.6.0 and 5.6.1"
+.IX Header "Summary of changes between 5.6.0 and 5.6.1"
+This section contains a summary of the changes between the 5.6.0 release
+and the 5.6.1 release.  More details about the changes mentioned here
+may be found in the \fIChanges\fR files that accompany the Perl source
+distribution.  See perlhack for pointers to online resources where you
+can inspect the individual patches described by these changes.
+.SS "Security Issues"
+.IX Subsection "Security Issues"
+suidperl will not run /bin/mail anymore, because some platforms have
+a /bin/mail that is vulnerable to buffer overflow attacks.
+.PP
+Note that suidperl is neither built nor installed by default in
+any recent version of perl.  Use of suidperl is highly discouraged.
+If you think you need it, try alternatives such as sudo first.
+See http://www.courtesan.com/sudo/ .
+.SS "Core bug fixes"
+.IX Subsection "Core bug fixes"
+This is not an exhaustive list.  It is intended to cover only the
+significant user-visible changes.
+.ie n .IP UNIVERSAL::isa() 4
+.el .IP \f(CWUNIVERSAL::isa()\fR 4
+.IX Item "UNIVERSAL::isa()"
+A bug in the caching mechanism used by \f(CWUNIVERSAL::isa()\fR that affected
+base.pm has been fixed.  The bug has existed since the 5.005 releases,
+but wasn't tickled by base.pm in those releases.
+.IP "Memory leaks" 4
+.IX Item "Memory leaks"
+Various cases of memory leaks and attempts to access uninitialized memory
+have been cured.  See "Known Problems" below for further issues.
+.IP "Numeric conversions" 4
+.IX Item "Numeric conversions"
+Numeric conversions did not recognize changes in the string value
+properly in certain circumstances.
+.Sp
+In other situations, large unsigned numbers (those above 2**31) could
+sometimes lose their unsignedness, causing bogus results in arithmetic
+operations.
+.Sp
+Integer modulus on large unsigned integers sometimes returned
+incorrect values.
+.Sp
+Perl 5.6.0 generated "not a number" warnings on certain conversions where
+previous versions didn't.
+.Sp
+These problems have all been rectified.
+.Sp
+Infinity is now recognized as a number.
+.IP qw(a\e\eb) 4
+.IX Item "qw(ab)"
+In Perl 5.6.0, qw(a\e\eb) produced a string with two backslashes instead
+of one, in a departure from the behavior in previous versions.  The
+older behavior has been reinstated.
+.IP \fBcaller()\fR 4
+.IX Item "caller()"
+\&\fBcaller()\fR could cause core dumps in certain situations.  Carp was sometimes
+affected by this problem.
+.IP "Bugs in regular expressions" 4
+.IX Item "Bugs in regular expressions"
+Pattern matches on overloaded values are now handled correctly.
+.Sp
+Perl 5.6.0 parsed m/\ex{ab}/ incorrectly, leading to spurious warnings.
+This has been corrected.
+.Sp
+The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds
+of simple pattern matches.  These are now handled better.
+.Sp
+Regular expression debug output (whether through \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR
+or via \f(CW\*(C`\-Dr\*(C'\fR) now looks better.
+.Sp
+Multi-line matches like \f(CW\*(C`"a\enxb\en" =~ /(?!\eA)x/m\*(C'\fR were flawed.  The
+bug has been fixed.
+.Sp
+Use of $& could trigger a core dump under some situations.  This
+is now avoided.
+.Sp
+Match variables \f(CW$1\fR et al., weren't being unset when a pattern match
+was backtracking, and the anomaly showed up inside \f(CW\*(C`/...(?{ ... }).../\*(C'\fR
+etc.  These variables are now tracked correctly.
+.Sp
+\&\fBpos()\fR did not return the correct value within s///ge in earlier
+versions.  This is now handled correctly.
+.IP """slurp"" mode" 4
+.IX Item """slurp"" mode"
+\&\fBreadline()\fR on files opened in "slurp" mode could return an extra "" at
+the end in certain situations.  This has been corrected.
+.IP "Autovivification of symbolic references to special variables" 4
+.IX Item "Autovivification of symbolic references to special variables"
+Autovivification of symbolic references of special variables described
+in perlvar (as in \f(CW\*(C`${$num}\*(C'\fR) was accidentally disabled.  This works
+again now.
+.IP "Lexical warnings" 4
+.IX Item "Lexical warnings"
+Lexical warnings now propagate correctly into \f(CW\*(C`eval "..."\*(C'\fR.
+.Sp
+\&\f(CW\*(C`use warnings qw(FATAL all)\*(C'\fR did not work as intended.  This has been
+corrected.
+.Sp
+Lexical warnings could leak into other scopes in some situations.
+This is now fixed.
+.Sp
+\&\fBwarnings::enabled()\fR now reports the state of $^W correctly if the caller
+isn't using lexical warnings.
+.IP "Spurious warnings and errors" 4
+.IX Item "Spurious warnings and errors"
+Perl 5.6.0 could emit spurious warnings about redefinition of \fBdl_error()\fR
+when statically building extensions into perl.  This has been corrected.
+.Sp
+"our" variables could result in bogus "Variable will not stay shared"
+warnings.  This is now fixed.
+.Sp
+"our" variables of the same name declared in two sibling blocks
+resulted in bogus warnings about "redeclaration" of the variables.
+The problem has been corrected.
+.IP \fBglob()\fR 4
+.IX Item "glob()"
+Compatibility of the builtin \fBglob()\fR with old csh-based glob has been
+improved with the addition of GLOB_ALPHASORT option.  See \f(CW\*(C`File::Glob\*(C'\fR.
+.Sp
+\&\fBFile::Glob::glob()\fR has been renamed to \fBFile::Glob::bsd_glob()\fR
+because the name clashes with the builtin \fBglob()\fR.  The older
+name is still available for compatibility, but is deprecated.
+.Sp
+Spurious syntax errors generated in certain situations, when \fBglob()\fR
+caused File::Glob to be loaded for the first time, have been fixed.
+.IP Tainting 4
+.IX Item "Tainting"
+Some cases of inconsistent taint propagation (such as within hash
+values) have been fixed.
+.Sp
+The tainting behavior of \fBsprintf()\fR has been rationalized.  It does
+not taint the result of floating point formats anymore, making the
+behavior consistent with that of string interpolation.
+.IP \fBsort()\fR 4
+.IX Item "sort()"
+Arguments to \fBsort()\fR weren't being provided the right \fBwantarray()\fR context.
+The comparison block is now run in scalar context, and the arguments to
+be sorted are always provided list context.
+.Sp
+\&\fBsort()\fR is also fully reentrant, in the sense that the sort function
+can itself call \fBsort()\fR.  This did not work reliably in previous releases.
+.IP "#line directives" 4
+.IX Item "#line directives"
+#line directives now work correctly when they appear at the very
+beginning of \f(CW\*(C`eval "..."\*(C'\fR.
+.IP "Subroutine prototypes" 4
+.IX Item "Subroutine prototypes"
+The (\e&) prototype now works properly.
+.IP \fBmap()\fR 4
+.IX Item "map()"
+\&\fBmap()\fR could get pathologically slow when the result list it generates
+is larger than the source list.  The performance has been improved for
+common scenarios.
+.IP Debugger 4
+.IX Item "Debugger"
+Debugger exit code now reflects the script exit code.
+.Sp
+Condition \f(CW"0"\fR in breakpoints is now treated correctly.
+.Sp
+The \f(CW\*(C`d\*(C'\fR command now checks the line number.
+.Sp
+\&\f(CW$.\fR is no longer corrupted by the debugger.
+.Sp
+All debugger output now correctly goes to the socket if RemotePort
+is set.
+.IP PERL5OPT 4
+.IX Item "PERL5OPT"
+PERL5OPT can be set to more than one switch group.  Previously,
+it used to be limited to one group of options only.
+.IP \fBchop()\fR 4
+.IX Item "chop()"
+chop(@list) in list context returned the characters chopped in reverse
+order.  This has been reversed to be in the right order.
+.IP "Unicode support" 4
+.IX Item "Unicode support"
+Unicode support has seen a large number of incremental improvements,
+but continues to be highly experimental.  It is not expected to be
+fully supported in the 5.6.x maintenance releases.
+.Sp
+\&\fBsubstr()\fR, \fBjoin()\fR, \fBrepeat()\fR, \fBreverse()\fR, \fBquotemeta()\fR and string
+concatenation were all handling Unicode strings incorrectly in
+Perl 5.6.0.  This has been corrected.
+.Sp
+Support for \f(CW\*(C`tr///CU\*(C'\fR and \f(CW\*(C`tr///UC\*(C'\fR etc., have been removed since
+we realized the interface is broken.  For similar functionality,
+see "pack" in perlfunc.
+.Sp
+The Unicode Character Database has been updated to version 3.0.1
+with additions made available to the public as of August 30, 2000.
+.Sp
+The Unicode character classes \ep{Blank} and \ep{SpacePerl} have been
+added.  "Blank" is like C \fBisblank()\fR, that is, it contains only
+"horizontal whitespace" (the space character is, the newline isn't),
+and the "SpacePerl" is the Unicode equivalent of \f(CW\*(C`\es\*(C'\fR (\ep{Space}
+isn't, since that includes the vertical tabulator character, whereas
+\&\f(CW\*(C`\es\*(C'\fR doesn't.)
+.Sp
+If you are experimenting with Unicode support in perl, the development
+versions of Perl may have more to offer.  In particular, I/O layers
+are now available in the development track, but not in the maintenance
+track, primarily to do backward compatibility issues.  Unicode support
+is also evolving rapidly on a daily basis in the development track\-\-the
+maintenance track only reflects the most conservative of these changes.
+.IP "64\-bit support" 4
+.IX Item "64-bit support"
+Support for 64\-bit platforms has been improved, but continues to be
+experimental.  The level of support varies greatly among platforms.
+.IP Compiler 4
+.IX Item "Compiler"
+The B Compiler and its various backends have had many incremental
+improvements, but they continue to remain highly experimental.  Use in
+production environments is discouraged.
+.Sp
+The perlcc tool has been rewritten so that the user interface is much
+more like that of a C compiler.
+.Sp
+The perlbc tools has been removed.  Use \f(CW\*(C`perlcc \-B\*(C'\fR instead.
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+There have been various bugfixes to support lvalue subroutines better.
+However, the feature still remains experimental.
+.IP IO::Socket 4
+.IX Item "IO::Socket"
+IO::Socket::INET failed to open the specified port if the service
+name was not known.  It now correctly uses the supplied port number
+as is.
+.IP File::Find 4
+.IX Item "File::Find"
+File::Find now \fBchdir()\fRs correctly when chasing symbolic links.
+.IP xsubpp 4
+.IX Item "xsubpp"
+xsubpp now tolerates embedded POD sections.
+.ie n .IP """no Module;""" 4
+.el .IP "\f(CWno Module;\fR" 4
+.IX Item "no Module;"
+\&\f(CW\*(C`no Module;\*(C'\fR does not produce an error even if Module does not have an
+\&\fBunimport()\fR method.  This parallels the behavior of \f(CW\*(C`use\*(C'\fR vis-a-vis
+\&\f(CW\*(C`import\*(C'\fR.
+.IP Tests 4
+.IX Item "Tests"
+A large number of tests have been added.
+.SS "Core features"
+.IX Subsection "Core features"
+\&\fBuntie()\fR will now call an \fBUNTIE()\fR hook if it exists.  See perltie
+for details.
+.PP
+The \f(CW\*(C`\-DT\*(C'\fR command line switch outputs copious tokenizing information.
+See perlrun.
+.PP
+Arrays are now always interpolated in double-quotish strings.  Previously,
+\&\f(CW"foo@bar.com"\fR used to be a fatal error at compile time, if an array
+\&\f(CW@bar\fR was not used or declared.  This transitional behavior was
+intended to help migrate perl4 code, and is deemed to be no longer useful.
+See "Arrays now always interpolate into double-quoted strings".
+.PP
+\&\fBkeys()\fR, \fBeach()\fR, \fBpop()\fR, \fBpush()\fR, \fBshift()\fR, \fBsplice()\fR and \fBunshift()\fR
+can all be overridden now.
+.PP
+\&\f(CW\*(C`my _\|_PACKAGE_\|_ $obj\*(C'\fR now does the expected thing.
+.SS "Configuration issues"
+.IX Subsection "Configuration issues"
+On some systems (IRIX and Solaris among them) the system malloc is demonstrably
+better.  While the defaults haven't been changed in order to retain binary
+compatibility with earlier releases, you may be better off building perl
+with \f(CW\*(C`Configure \-Uusemymalloc ...\*(C'\fR as discussed in the \fIINSTALL\fR file.
+.PP
+\&\f(CW\*(C`Configure\*(C'\fR has been enhanced in various ways:
+.IP \(bu 4
+Minimizes use of temporary files.
+.IP \(bu 4
+By default, does not link perl with libraries not used by it, such as
+the various dbm libraries.  SunOS 4.x hints preserve behavior on that
+platform.
+.IP \(bu 4
+Support for pdp11\-style memory models has been removed due to obsolescence.
+.IP \(bu 4
+Building outside the source tree is supported on systems that have
+symbolic links. This is done by running
+.Sp
+.Vb 2
+\&    sh /path/to/source/Configure \-Dmksymlinks ...
+\&    make all test install
+.Ve
+.Sp
+in a directory other than the perl source directory.  See \fIINSTALL\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Configure \-S\*(C'\fR can be run non-interactively.
+.SS Documentation
+.IX Subsection "Documentation"
+README.aix, README.solaris and README.macos have been added.
+README.posix\-bc has been renamed to README.bs2000.  These are
+installed as perlaix, perlsolaris, perlmacos, and
+perlbs2000 respectively.
+.PP
+The following pod documents are brand new:
+.PP
+.Vb 7
+\&    perlclib    Internal replacements for standard C library functions
+\&    perldebtut  Perl debugging tutorial
+\&    perlebcdic  Considerations for running Perl on EBCDIC platforms
+\&    perlnewmod  Perl modules: preparing a new module for distribution
+\&    perlrequick Perl regular expressions quick start
+\&    perlretut   Perl regular expressions tutorial
+\&    perlutil    utilities packaged with the Perl distribution
+.Ve
+.PP
+The \fIINSTALL\fR file has been expanded to cover various issues, such as
+64\-bit support.
+.PP
+A longer list of contributors has been added to the source distribution.
+See the file \f(CW\*(C`AUTHORS\*(C'\fR.
+.PP
+Numerous other changes have been made to the included documentation and FAQs.
+.SS "Bundled modules"
+.IX Subsection "Bundled modules"
+The following modules have been added.
+.IP B::Concise 4
+.IX Item "B::Concise"
+Walks Perl syntax tree, printing concise info about ops.  See B::Concise.
+.IP File::Temp 4
+.IX Item "File::Temp"
+Returns name and handle of a temporary file safely.  See File::Temp.
+.IP Pod::LaTeX 4
+.IX Item "Pod::LaTeX"
+Converts Pod data to formatted LaTeX.  See Pod::LaTeX.
+.IP Pod::Text::Overstrike 4
+.IX Item "Pod::Text::Overstrike"
+Converts POD data to formatted overstrike text.  See Pod::Text::Overstrike.
+.PP
+The following modules have been upgraded.
+.IP CGI 4
+.IX Item "CGI"
+CGI v2.752 is now included.
+.IP CPAN 4
+.IX Item "CPAN"
+CPAN v1.59_54 is now included.
+.IP Class::Struct 4
+.IX Item "Class::Struct"
+Various bugfixes have been added.
+.IP DB_File 4
+.IX Item "DB_File"
+DB_File v1.75 supports newer Berkeley DB versions, among other
+improvements.
+.IP Devel::Peek 4
+.IX Item "Devel::Peek"
+Devel::Peek has been enhanced to support dumping of memory statistics,
+when perl is built with the included \fBmalloc()\fR.
+.IP File::Find 4
+.IX Item "File::Find"
+File::Find now supports pre and post-processing of the files in order
+to \fBsort()\fR them, etc.
+.IP Getopt::Long 4
+.IX Item "Getopt::Long"
+Getopt::Long v2.25 is included.
+.IP IO::Poll 4
+.IX Item "IO::Poll"
+Various bug fixes have been included.
+.IP IPC::Open3 4
+.IX Item "IPC::Open3"
+IPC::Open3 allows use of numeric file descriptors.
+.IP Math::BigFloat 4
+.IX Item "Math::BigFloat"
+The \fBfmod()\fR function supports modulus operations.  Various bug fixes
+have also been included.
+.IP Math::Complex 4
+.IX Item "Math::Complex"
+Math::Complex handles inf, NaN etc., better.
+.IP Net::Ping 4
+.IX Item "Net::Ping"
+\&\fBping()\fR could fail on odd number of data bytes, and when the echo service
+isn't running.  This has been corrected.
+.IP Opcode 4
+.IX Item "Opcode"
+A memory leak has been fixed.
+.IP Pod::Parser 4
+.IX Item "Pod::Parser"
+Version 1.13 of the Pod::Parser suite is included.
+.IP Pod::Text 4
+.IX Item "Pod::Text"
+Pod::Text and related modules have been upgraded to the versions
+in podlators suite v2.08.
+.IP SDBM_File 4
+.IX Item "SDBM_File"
+On dosish platforms, some keys went missing because of lack of support for
+files with "holes".  A workaround for the problem has been added.
+.IP Sys::Syslog 4
+.IX Item "Sys::Syslog"
+Various bug fixes have been included.
+.IP Tie::RefHash 4
+.IX Item "Tie::RefHash"
+Now supports Tie::RefHash::Nestable to automagically tie hashref values.
+.IP Tie::SubstrHash 4
+.IX Item "Tie::SubstrHash"
+Various bug fixes have been included.
+.SS "Platform-specific improvements"
+.IX Subsection "Platform-specific improvements"
+The following new ports are now available.
+.IP "NCR MP-RAS" 4
+.IX Item "NCR MP-RAS"
+.PD 0
+.IP NonStop-UX 4
+.IX Item "NonStop-UX"
+.PD
+.PP
+Perl now builds under Amdahl UTS.
+.PP
+Perl has also been verified to build under Amiga OS.
+.PP
+Support for EPOC has been much improved.  See README.epoc.
+.PP
+Building perl with \-Duseithreads or \-Duse5005threads now works
+under HP-UX 10.20 (previously it only worked under 10.30 or later).
+You will need a thread library package installed.  See README.hpux.
+.PP
+Long doubles should now work under Linux.
+.PP
+Mac OS Classic is now supported in the mainstream source package.
+See README.macos.
+.PP
+Support for MPE/iX has been updated.  See README.mpeix.
+.PP
+Support for OS/2 has been improved.  See \f(CW\*(C`os2/Changes\*(C'\fR and README.os2.
+.PP
+Dynamic loading on z/OS (formerly OS/390) has been improved.  See
+README.os390.
+.PP
+Support for VMS has seen many incremental improvements, including
+better support for operators like backticks and \fBsystem()\fR, and better
+\&\f(CW%ENV\fR handling.  See \f(CW\*(C`README.vms\*(C'\fR and perlvms.
+.PP
+Support for Stratus VOS has been improved.  See \f(CW\*(C`vos/Changes\*(C'\fR and README.vos.
+.PP
+Support for Windows has been improved.
+.IP \(bu 4
+\&\fBfork()\fR emulation has been improved in various ways, but still continues
+to be experimental.  See perlfork for known bugs and caveats.
+.IP \(bu 4
+\&\f(CW%SIG\fR has been enabled under USE_ITHREADS, but its use is completely
+unsupported under all configurations.
+.IP \(bu 4
+Borland C++ v5.5 is now a supported compiler that can build Perl.
+However, the generated binaries continue to be incompatible with those
+generated by the other supported compilers (GCC and Visual C++).
+.IP \(bu 4
+Non-blocking waits for child processes (or pseudo-processes) are
+supported via \f(CW\*(C`waitpid($pid, &POSIX::WNOHANG)\*(C'\fR.
+.IP \(bu 4
+A memory leak in \fBaccept()\fR has been fixed.
+.IP \(bu 4
+\&\fBwait()\fR, \fBwaitpid()\fR and backticks now return the correct exit status under
+Windows 9x.
+.IP \(bu 4
+Trailing new \f(CW%ENV\fR entries weren't propagated to child processes.  This
+is now fixed.
+.IP \(bu 4
+Current directory entries in \f(CW%ENV\fR are now correctly propagated to child
+processes.
+.IP \(bu 4
+Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.
+.IP \(bu 4
+The makefiles now provide a single switch to bulk-enable all the features
+enabled in ActiveState ActivePerl (a popular binary distribution).
+.IP \(bu 4
+\&\fBWin32::GetCwd()\fR correctly returns C:\e instead of C: when at the drive root.
+Other bugs in \fBchdir()\fR and \fBCwd::cwd()\fR have also been fixed.
+.IP \(bu 4
+\&\fBfork()\fR correctly returns undef and sets EAGAIN when it runs out of
+pseudo-process handles.
+.IP \(bu 4
+ExtUtils::MakeMaker now uses \f(CW$ENV\fR{LIB} to search for libraries.
+.IP \(bu 4
+UNC path handling is better when perl is built to support \fBfork()\fR.
+.IP \(bu 4
+A handle leak in socket handling has been fixed.
+.IP \(bu 4
+\&\fBsend()\fR works from within a pseudo-process.
+.PP
+Unless specifically qualified otherwise, the remainder of this document
+covers changes between the 5.005 and 5.6.0 releases.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Interpreter cloning, threads, and concurrency"
+.IX Subsection "Interpreter cloning, threads, and concurrency"
+Perl 5.6.0 introduces the beginnings of support for running multiple
+interpreters concurrently in different threads.  In conjunction with
+the \fBperl_clone()\fR API call, which can be used to selectively duplicate
+the state of any given interpreter, it is possible to compile a
+piece of code once in an interpreter, clone that interpreter
+one or more times, and run all the resulting interpreters in distinct
+threads.
+.PP
+On the Windows platform, this feature is used to emulate \fBfork()\fR at the
+interpreter level.  See perlfork for details about that.
+.PP
+This feature is still in evolution.  It is eventually meant to be used
+to selectively clone a subroutine and data reachable from that
+subroutine in a separate interpreter and run the cloned subroutine
+in a separate thread.  Since there is no shared data between the
+interpreters, little or no locking will be needed (unless parts of
+the symbol table are explicitly shared).  This is obviously intended
+to be an easy-to-use replacement for the existing threads support.
+.PP
+Support for cloning interpreters and interpreter concurrency can be
+enabled using the \-Dusethreads Configure option (see win32/Makefile for
+how to enable it on Windows.)  The resulting perl executable will be
+functionally identical to one that was built with \-Dmultiplicity, but
+the \fBperl_clone()\fR API call will only be available in the former.
+.PP
+\&\-Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn
+enables Perl source code changes that provide a clear separation between
+the op tree and the data it operates with.  The former is immutable, and
+can therefore be shared between an interpreter and all of its clones,
+while the latter is considered local to each interpreter, and is therefore
+copied for each clone.
+.PP
+Note that building Perl with the \-Dusemultiplicity Configure option
+is adequate if you wish to run multiple \fBindependent\fR interpreters
+concurrently in different threads.  \-Dusethreads only provides the
+additional functionality of the \fBperl_clone()\fR API call and other
+support for running \fBcloned\fR interpreters concurrently.
+.PP
+.Vb 2
+\&    NOTE: This is an experimental feature.  Implementation details are
+\&    subject to change.
+.Ve
+.SS "Lexically scoped warning categories"
+.IX Subsection "Lexically scoped warning categories"
+You can now control the granularity of warnings emitted by perl at a finer
+level using the \f(CW\*(C`use warnings\*(C'\fR pragma.  warnings and perllexwarn
+have copious documentation on this feature.
+.SS "Unicode and UTF\-8 support"
+.IX Subsection "Unicode and UTF-8 support"
+Perl now uses UTF\-8 as its internal representation for character
+strings.  The \f(CW\*(C`utf8\*(C'\fR and \f(CW\*(C`bytes\*(C'\fR pragmas are used to control this support
+in the current lexical scope.  See perlunicode, utf8 and bytes for
+more information.
+.PP
+This feature is expected to evolve quickly to support some form of I/O
+disciplines that can be used to specify the kind of input and output data
+(bytes or characters).  Until that happens, additional modules from CPAN
+will be needed to complete the toolkit for dealing with Unicode.
+.PP
+.Vb 2
+\&    NOTE: This should be considered an experimental feature.  Implementation
+\&    details are subject to change.
+.Ve
+.SS "Support for interpolating named characters"
+.IX Subsection "Support for interpolating named characters"
+The new \f(CW\*(C`\eN\*(C'\fR escape interpolates named characters within strings.
+For example, \f(CW"Hi! \eN{WHITE SMILING FACE}"\fR evaluates to a string
+with a Unicode smiley face at the end.
+.SS """our"" declarations"
+.IX Subsection """our"" declarations"
+An "our" declaration introduces a value that can be best understood
+as a lexically scoped symbolic alias to a global variable in the
+package that was current where the variable was declared.  This is
+mostly useful as an alternative to the \f(CW\*(C`vars\*(C'\fR pragma, but also provides
+the opportunity to introduce typing and other attributes for such
+variables.  See "our" in perlfunc.
+.SS "Support for strings represented as a vector of ordinals"
+.IX Subsection "Support for strings represented as a vector of ordinals"
+Literals of the form \f(CW\*(C`v1.2.3.4\*(C'\fR are now parsed as a string composed
+of characters with the specified ordinals.  This is an alternative, more
+readable way to construct (possibly Unicode) strings instead of
+interpolating characters, as in \f(CW"\ex{1}\ex{2}\ex{3}\ex{4}"\fR.  The leading
+\&\f(CW\*(C`v\*(C'\fR may be omitted if there are more than two ordinals, so \f(CW1.2.3\fR is
+parsed the same as \f(CW\*(C`v1.2.3\*(C'\fR.
+.PP
+Strings written in this form are also useful to represent version "numbers".
+It is easy to compare such version "numbers" (which are really just plain
+strings) using any of the usual string comparison operators \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR,
+\&\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, etc., or perform bitwise string operations on them using \f(CW\*(C`|\*(C'\fR,
+\&\f(CW\*(C`&\*(C'\fR, etc.
+.PP
+In conjunction with the new \f(CW$^V\fR magic variable (which contains
+the perl version as a string), such literals can be used as a readable way
+to check if you're running a particular version of Perl:
+.PP
+.Vb 4
+\&    # this will parse in older versions of Perl also
+\&    if ($^V and $^V gt v5.6.0) {
+\&        # new features supported
+\&    }
+.Ve
+.PP
+\&\f(CW\*(C`require\*(C'\fR and \f(CW\*(C`use\*(C'\fR also have some special magic to support such literals.
+They will be interpreted as a version rather than as a module name:
+.PP
+.Vb 2
+\&    require v5.6.0;             # croak if $^V lt v5.6.0
+\&    use v5.6.0;                 # same, but croaks at compile\-time
+.Ve
+.PP
+Alternatively, the \f(CW\*(C`v\*(C'\fR may be omitted if there is more than one dot:
+.PP
+.Vb 2
+\&    require 5.6.0;
+\&    use 5.6.0;
+.Ve
+.PP
+Also, \f(CW\*(C`sprintf\*(C'\fR and \f(CW\*(C`printf\*(C'\fR support the Perl-specific format flag \f(CW%v\fR
+to print ordinals of characters in arbitrary strings:
+.PP
+.Vb 3
+\&    printf "v%vd", $^V;         # prints current version, such as "v5.5.650"
+\&    printf "%*vX", ":", $addr;  # formats IPv6 address
+\&    printf "%*vb", " ", $bits;  # displays bitstring
+.Ve
+.PP
+See "Scalar value constructors" in perldata for additional information.
+.SS "Improved Perl version numbering system"
+.IX Subsection "Improved Perl version numbering system"
+Beginning with Perl version 5.6.0, the version number convention has been
+changed to a "dotted integer" scheme that is more commonly found in open
+source projects.
+.PP
+Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
+The next development series following v5.6.0 will be numbered v5.7.x,
+beginning with v5.7.0, and the next major production release following
+v5.6.0 will be v5.8.0.
+.PP
+The English module now sets \f(CW$PERL_VERSION\fR to $^V (a string value) rather
+than \f(CW$]\fR (a numeric value).  (This is a potential incompatibility.
+Send us a report via perlbug if you are affected by this.)
+.PP
+The v1.2.3 syntax is also now legal in Perl.
+See "Support for strings represented as a vector of ordinals" for more on that.
+.PP
+To cope with the new versioning system's use of at least three significant
+digits for each version component, the method used for incrementing the
+subversion number has also changed slightly.  We assume that versions older
+than v5.6.0 have been incrementing the subversion component in multiples of
+10.  Versions after v5.6.0 will increment them by 1.  Thus, using the new
+notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance
+version following v5.6.0 will be v5.6.1 (which should be read as being
+equivalent to a floating point value of 5.006_001 in the older format,
+stored in \f(CW$]\fR).
+.SS "New syntax for declaring subroutine attributes"
+.IX Subsection "New syntax for declaring subroutine attributes"
+Formerly, if you wanted to mark a subroutine as being a method call or
+as requiring an automatic \fBlock()\fR when it is entered, you had to declare
+that with a \f(CW\*(C`use attrs\*(C'\fR pragma in the body of the subroutine.
+That can now be accomplished with declaration syntax, like this:
+.PP
+.Vb 5
+\&    sub mymethod : locked method;
+\&    ...
+\&    sub mymethod : locked method {
+\&        ...
+\&    }
+\&
+\&    sub othermethod :locked :method;
+\&    ...
+\&    sub othermethod :locked :method {
+\&        ...
+\&    }
+.Ve
+.PP
+(Note how only the first \f(CW\*(C`:\*(C'\fR is mandatory, and whitespace surrounding
+the \f(CW\*(C`:\*(C'\fR is optional.)
+.PP
+\&\fIAutoSplit.pm\fR and \fISelfLoader.pm\fR have been updated to keep the attributes
+with the stubs they provide.  See attributes.
+.SS "File and directory handles can be autovivified"
+.IX Subsection "File and directory handles can be autovivified"
+Similar to how constructs such as \f(CW\*(C`$x\->[0]\*(C'\fR autovivify a reference,
+handle constructors (\fBopen()\fR, \fBopendir()\fR, \fBpipe()\fR, \fBsocketpair()\fR, \fBsysopen()\fR,
+\&\fBsocket()\fR, and \fBaccept()\fR) now autovivify a file or directory handle
+if the handle passed to them is an uninitialized scalar variable.  This
+allows the constructs such as \f(CW\*(C`open(my $fh, ...)\*(C'\fR and \f(CW\*(C`open(local $fh,...)\*(C'\fR
+to be used to create filehandles that will conveniently be closed
+automatically when the scope ends, provided there are no other references
+to them.  This largely eliminates the need for typeglobs when opening
+filehandles that must be passed around, as in the following example:
+.PP
+.Vb 5
+\&    sub myopen {
+\&        open my $fh, "@_"
+\&             or die "Can\*(Aqt open \*(Aq@_\*(Aq: $!";
+\&        return $fh;
+\&    }
+\&
+\&    {
+\&        my $f = myopen("</etc/motd");
+\&        print <$f>;
+\&        # $f implicitly closed here
+\&    }
+.Ve
+.SS "\fBopen()\fP with more than two arguments"
+.IX Subsection "open() with more than two arguments"
+If \fBopen()\fR is passed three arguments instead of two, the second argument
+is used as the mode and the third argument is taken to be the file name.
+This is primarily useful for protecting against unintended magic behavior
+of the traditional two-argument form.  See "open" in perlfunc.
+.SS "64\-bit support"
+.IX Subsection "64-bit support"
+Any platform that has 64\-bit integers either
+.PP
+.Vb 3
+\&        (1) natively as longs or ints
+\&        (2) via special compiler flags
+\&        (3) using long long or int64_t
+.Ve
+.PP
+is able to use "quads" (64\-bit integers) as follows:
+.IP \(bu 4
+constants (decimal, hexadecimal, octal, binary) in the code
+.IP \(bu 4
+arguments to \fBoct()\fR and \fBhex()\fR
+.IP \(bu 4
+arguments to \fBprint()\fR, \fBprintf()\fR and \fBsprintf()\fR (flag prefixes ll, L, q)
+.IP \(bu 4
+printed as such
+.IP \(bu 4
+\&\fBpack()\fR and \fBunpack()\fR "q" and "Q" formats
+.IP \(bu 4
+in basic arithmetics: + \- * / % (NOTE: operating close to the limits
+of the integer values may produce surprising results)
+.IP \(bu 4
+in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced 
+to be 32 bits wide but now operate on the full native width.)
+.IP \(bu 4
+\&\fBvec()\fR
+.PP
+Note that unless you have the case (a) you will have to configure
+and compile Perl using the \-Duse64bitint Configure flag.
+.PP
+.Vb 2
+\&    NOTE: The Configure flags \-Duselonglong and \-Duse64bits have been
+\&    deprecated.  Use \-Duse64bitint instead.
+.Ve
+.PP
+There are actually two modes of 64\-bitness: the first one is achieved
+using Configure \-Duse64bitint and the second one using Configure
+\&\-Duse64bitall.  The difference is that the first one is minimal and
+the second one maximal.  The first works in more places than the second.
+.PP
+The \f(CW\*(C`use64bitint\*(C'\fR does only as much as is required to get 64\-bit
+integers into Perl (this may mean, for example, using "long longs")
+while your memory may still be limited to 2 gigabytes (because your
+pointers could still be 32\-bit).  Note that the name \f(CW\*(C`64bitint\*(C'\fR does
+not imply that your C compiler will be using 64\-bit \f(CW\*(C`int\*(C'\fRs (it might,
+but it doesn't have to): the \f(CW\*(C`use64bitint\*(C'\fR means that you will be
+able to have 64 bits wide scalar values.
+.PP
+The \f(CW\*(C`use64bitall\*(C'\fR goes all the way by attempting to switch also
+integers (if it can), longs (and pointers) to being 64\-bit.  This may
+create an even more binary incompatible Perl than \-Duse64bitint: the
+resulting executable may not run at all in a 32\-bit box, or you may
+have to reboot/reconfigure/rebuild your operating system to be 64\-bit
+aware.
+.PP
+Natively 64\-bit systems like Alpha and Cray need neither \-Duse64bitint
+nor \-Duse64bitall.
+.PP
+Last but not least: note that due to Perl's habit of always using
+floating point numbers, the quads are still not true integers.
+When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned,
+\&\-9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they
+are silently promoted to floating point numbers, after which they will
+start losing precision (in their lower digits).
+.PP
+.Vb 4
+\&    NOTE: 64\-bit support is still experimental on most platforms.
+\&    Existing support only covers the LP64 data model.  In particular, the
+\&    LLP64 data model is not yet supported.  64\-bit libraries and system
+\&    APIs on many platforms have not stabilized\-\-your mileage may vary.
+.Ve
+.SS "Large file support"
+.IX Subsection "Large file support"
+If you have filesystems that support "large files" (files larger than
+2 gigabytes), you may now also be able to create and access them from
+Perl.
+.PP
+.Vb 2
+\&    NOTE: The default action is to enable large file support, if
+\&    available on the platform.
+.Ve
+.PP
+If the large file support is on, and you have a Fcntl constant
+O_LARGEFILE, the O_LARGEFILE is automatically added to the flags
+of \fBsysopen()\fR.
+.PP
+Beware that unless your filesystem also supports "sparse files" seeking
+to umpteen petabytes may be inadvisable.
+.PP
+Note that in addition to requiring a proper file system to do large
+files you may also need to adjust your per-process (or your
+per-system, or per-process-group, or per-user-group) maximum filesize
+limits before running Perl scripts that try to handle large files,
+especially if you intend to write such files.
+.PP
+Finally, in addition to your process/process group maximum filesize
+limits, you may have quota limits on your filesystems that stop you
+(your user id or your user group id) from using large files.
+.PP
+Adjusting your process/user/group/file system/operating system limits
+is outside the scope of Perl core language.  For process limits, you
+may try increasing the limits using your shell's limits/limit/ulimit
+command before running Perl.  The BSD::Resource extension (not
+included with the standard Perl distribution) may also be of use, it
+offers the getrlimit/setrlimit interface that can be used to adjust
+process resource usage limits, including the maximum filesize limit.
+.SS "Long doubles"
+.IX Subsection "Long doubles"
+In some systems you may be able to use long doubles to enhance the
+range and precision of your double precision floating point numbers
+(that is, Perl's numbers).  Use Configure \-Duselongdouble to enable
+this support (if it is available).
+.SS """more bits"""
+.IX Subsection """more bits"""
+You can "Configure \-Dusemorebits" to turn on both the 64\-bit support
+and the long double support.
+.SS "Enhanced support for \fBsort()\fP subroutines"
+.IX Subsection "Enhanced support for sort() subroutines"
+Perl subroutines with a prototype of \f(CW\*(C`($$)\*(C'\fR, and XSUBs in general, can
+now be used as sort subroutines.  In either case, the two elements to
+be compared are passed as normal parameters in \f(CW@_\fR.  See "sort" in perlfunc.
+.PP
+For unprototyped sort subroutines, the historical behavior of passing 
+the elements to be compared as the global variables \f(CW$a\fR and \f(CW$b\fR remains
+unchanged.
+.ie n .SS """sort $coderef @foo"" allowed"
+.el .SS "\f(CWsort $coderef @foo\fP allowed"
+.IX Subsection "sort $coderef @foo allowed"
+\&\fBsort()\fR did not accept a subroutine reference as the comparison
+function in earlier versions.  This is now permitted.
+.SS "File globbing implemented internally"
+.IX Subsection "File globbing implemented internally"
+Perl now uses the File::Glob implementation of the \fBglob()\fR operator
+automatically.  This avoids using an external csh process and the
+problems associated with it.
+.PP
+.Vb 2
+\&    NOTE: This is currently an experimental feature.  Interfaces and
+\&    implementation are subject to change.
+.Ve
+.SS "Support for CHECK blocks"
+.IX Subsection "Support for CHECK blocks"
+In addition to \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, \f(CW\*(C`END\*(C'\fR, \f(CW\*(C`DESTROY\*(C'\fR and \f(CW\*(C`AUTOLOAD\*(C'\fR,
+subroutines named \f(CW\*(C`CHECK\*(C'\fR are now special.  These are queued up during
+compilation and behave similar to END blocks, except they are called at
+the end of compilation rather than at the end of execution.  They cannot
+be called directly.
+.SS "POSIX character class syntax [: :] supported"
+.IX Subsection "POSIX character class syntax [: :] supported"
+For example to match alphabetic characters use /[[:alpha:]]/.
+See perlre for details.
+.SS "Better pseudo-random number generator"
+.IX Subsection "Better pseudo-random number generator"
+In 5.005_0x and earlier, perl's \fBrand()\fR function used the C library
+\&\fBrand\fR\|(3) function.  As of 5.005_52, Configure tests for \fBdrand48()\fR,
+\&\fBrandom()\fR, and \fBrand()\fR (in that order) and picks the first one it finds.
+.PP
+These changes should result in better random numbers from \fBrand()\fR.
+.ie n .SS "Improved ""qw//"" operator"
+.el .SS "Improved \f(CWqw//\fP operator"
+.IX Subsection "Improved qw// operator"
+The \f(CW\*(C`qw//\*(C'\fR operator is now evaluated at compile time into a true list
+instead of being replaced with a run time call to \f(CWsplit()\fR.  This
+removes the confusing misbehaviour of \f(CW\*(C`qw//\*(C'\fR in scalar context, which
+had inherited that behaviour from \fBsplit()\fR.
+.PP
+Thus:
+.PP
+.Vb 1
+\&    $foo = ($bar) = qw(a b c); print "$foo|$bar\en";
+.Ve
+.PP
+now correctly prints "3|a", instead of "2|a".
+.SS "Better worst-case behavior of hashes"
+.IX Subsection "Better worst-case behavior of hashes"
+Small changes in the hashing algorithm have been implemented in
+order to improve the distribution of lower order bits in the
+hashed value.  This is expected to yield better performance on
+keys that are repeated sequences.
+.SS "\fBpack()\fP format 'Z' supported"
+.IX Subsection "pack() format 'Z' supported"
+The new format type 'Z' is useful for packing and unpacking null-terminated
+strings.  See "pack" in perlfunc.
+.SS "\fBpack()\fP format modifier '!' supported"
+.IX Subsection "pack() format modifier '!' supported"
+The new format type modifier '!' is useful for packing and unpacking
+native shorts, ints, and longs.  See "pack" in perlfunc.
+.SS "\fBpack()\fP and \fBunpack()\fP support counted strings"
+.IX Subsection "pack() and unpack() support counted strings"
+The template character '/' can be used to specify a counted string
+type to be packed or unpacked.  See "pack" in perlfunc.
+.SS "Comments in \fBpack()\fP templates"
+.IX Subsection "Comments in pack() templates"
+The '#' character in a template introduces a comment up to
+end of the line.  This facilitates documentation of \fBpack()\fR
+templates.
+.SS "Weak references"
+.IX Subsection "Weak references"
+In previous versions of Perl, you couldn't cache objects so as
+to allow them to be deleted if the last reference from outside 
+the cache is deleted.  The reference in the cache would hold a
+reference count on the object and the objects would never be
+destroyed.
+.PP
+Another familiar problem is with circular references.  When an
+object references itself, its reference count would never go
+down to zero, and it would not get destroyed until the program
+is about to exit.
+.PP
+Weak references solve this by allowing you to "weaken" any
+reference, that is, make it not count towards the reference count.
+When the last non-weak reference to an object is deleted, the object
+is destroyed and all the weak references to the object are
+automatically undef-ed.
+.PP
+To use this feature, you need the Devel::WeakRef package from CPAN, which
+contains additional documentation.
+.PP
+.Vb 1
+\&    NOTE: This is an experimental feature.  Details are subject to change.
+.Ve
+.SS "Binary numbers supported"
+.IX Subsection "Binary numbers supported"
+Binary numbers are now supported as literals, in s?printf formats, and
+\&\f(CWoct()\fR:
+.PP
+.Vb 2
+\&    $answer = 0b101010;
+\&    printf "The answer is: %b\en", oct("0b101010");
+.Ve
+.SS "Lvalue subroutines"
+.IX Subsection "Lvalue subroutines"
+Subroutines can now return modifiable lvalues.
+See "Lvalue subroutines" in perlsub.
+.PP
+.Vb 1
+\&    NOTE: This is an experimental feature.  Details are subject to change.
+.Ve
+.SS "Some arrows may be omitted in calls through references"
+.IX Subsection "Some arrows may be omitted in calls through references"
+Perl now allows the arrow to be omitted in many constructs
+involving subroutine calls through references.  For example,
+\&\f(CW\*(C`$foo[10]\->(\*(Aqfoo\*(Aq)\*(C'\fR may now be written \f(CW\*(C`$foo[10](\*(Aqfoo\*(Aq)\*(C'\fR.
+This is rather similar to how the arrow may be omitted from
+\&\f(CW\*(C`$foo[10]\->{\*(Aqfoo\*(Aq}\*(C'\fR.  Note however, that the arrow is still
+required for \f(CW\*(C`foo(10)\->(\*(Aqbar\*(Aq)\*(C'\fR.
+.SS "Boolean assignment operators are legal lvalues"
+.IX Subsection "Boolean assignment operators are legal lvalues"
+Constructs such as \f(CW\*(C`($a ||= 2) += 1\*(C'\fR are now allowed.
+.SS "\fBexists()\fP is supported on subroutine names"
+.IX Subsection "exists() is supported on subroutine names"
+The \fBexists()\fR builtin now works on subroutine names.  A subroutine
+is considered to exist if it has been declared (even if implicitly).
+See "exists" in perlfunc for examples.
+.SS "\fBexists()\fP and \fBdelete()\fP are supported on array elements"
+.IX Subsection "exists() and delete() are supported on array elements"
+The \fBexists()\fR and \fBdelete()\fR builtins now work on simple arrays as well.
+The behavior is similar to that on hash elements.
+.PP
+\&\fBexists()\fR can be used to check whether an array element has been
+initialized.  This avoids autovivifying array elements that don't exist.
+If the array is tied, the \fBEXISTS()\fR method in the corresponding tied
+package will be invoked.
+.PP
+\&\fBdelete()\fR may be used to remove an element from the array and return
+it.  The array element at that position returns to its uninitialized
+state, so that testing for the same element with \fBexists()\fR will return
+false.  If the element happens to be the one at the end, the size of
+the array also shrinks up to the highest element that tests true for
+\&\fBexists()\fR, or 0 if none such is found.  If the array is tied, the \fBDELETE()\fR 
+method in the corresponding tied package will be invoked.
+.PP
+See "exists" in perlfunc and "delete" in perlfunc for examples.
+.SS "Pseudo-hashes work better"
+.IX Subsection "Pseudo-hashes work better"
+Dereferencing some types of reference values in a pseudo-hash,
+such as \f(CW\*(C`$ph\->{foo}[1]\*(C'\fR, was accidentally disallowed.  This has
+been corrected.
+.PP
+When applied to a pseudo-hash element, \fBexists()\fR now reports whether
+the specified value exists, not merely if the key is valid.
+.PP
+\&\fBdelete()\fR now works on pseudo-hashes.  When given a pseudo-hash element
+or slice it deletes the values corresponding to the keys (but not the keys
+themselves).  See "Pseudo-hashes: Using an array as a hash" in perlref.
+.PP
+Pseudo-hash slices with constant keys are now optimized to array lookups
+at compile-time.
+.PP
+List assignments to pseudo-hash slices are now supported.
+.PP
+The \f(CW\*(C`fields\*(C'\fR pragma now provides ways to create pseudo-hashes, via
+\&\fBfields::new()\fR and \fBfields::phash()\fR.  See fields.
+.PP
+.Vb 3
+\&    NOTE: The pseudo\-hash data type continues to be experimental.
+\&    Limiting oneself to the interface elements provided by the
+\&    fields pragma will provide protection from any future changes.
+.Ve
+.SS "Automatic flushing of output buffers"
+.IX Subsection "Automatic flushing of output buffers"
+\&\fBfork()\fR, \fBexec()\fR, \fBsystem()\fR, qx//, and pipe \fBopen()\fRs now flush buffers
+of all files opened for output when the operation was attempted.  This
+mostly eliminates confusing buffering mishaps suffered by users unaware
+of how Perl internally handles I/O.
+.PP
+This is not supported on some platforms like Solaris where a suitably
+correct implementation of fflush(NULL) isn't available.
+.SS "Better diagnostics on meaningless filehandle operations"
+.IX Subsection "Better diagnostics on meaningless filehandle operations"
+Constructs such as \f(CWopen(<FH>)\fR and \f(CWclose(<FH>)\fR
+are compile time errors.  Attempting to read from filehandles that
+were opened only for writing will now produce warnings (just as
+writing to read-only filehandles does).
+.SS "Where possible, buffered data discarded from duped input filehandle"
+.IX Subsection "Where possible, buffered data discarded from duped input filehandle"
+\&\f(CW\*(C`open(NEW, "<&OLD")\*(C'\fR now attempts to discard any data that
+was previously read and buffered in \f(CW\*(C`OLD\*(C'\fR before duping the handle.
+On platforms where doing this is allowed, the next read operation
+on \f(CW\*(C`NEW\*(C'\fR will return the same data as the corresponding operation
+on \f(CW\*(C`OLD\*(C'\fR.  Formerly, it would have returned the data from the start
+of the following disk block instead.
+.SS "\fBeof()\fP has the same old magic as <>"
+.IX Subsection "eof() has the same old magic as <>"
+\&\f(CWeof()\fR would return true if no attempt to read from \f(CW\*(C`<>\*(C'\fR had
+yet been made.  \f(CWeof()\fR has been changed to have a little magic of its
+own, it now opens the \f(CW\*(C`<>\*(C'\fR files.
+.SS "\fBbinmode()\fP can be used to set :crlf and :raw modes"
+.IX Subsection "binmode() can be used to set :crlf and :raw modes"
+\&\fBbinmode()\fR now accepts a second argument that specifies a discipline
+for the handle in question.  The two pseudo-disciplines ":raw" and
+":crlf" are currently supported on DOS-derivative platforms.
+See "binmode" in perlfunc and open.
+.ie n .SS """\-T"" filetest recognizes UTF\-8 encoded files as ""text"""
+.el .SS "\f(CW\-T\fP filetest recognizes UTF\-8 encoded files as ""text"""
+.IX Subsection "-T filetest recognizes UTF-8 encoded files as ""text"""
+The algorithm used for the \f(CW\*(C`\-T\*(C'\fR filetest has been enhanced to
+correctly identify UTF\-8 content as "text".
+.SS "\fBsystem()\fP, backticks and pipe open now reflect \fBexec()\fP failure"
+.IX Subsection "system(), backticks and pipe open now reflect exec() failure"
+On Unix and similar platforms, \fBsystem()\fR, \fBqx()\fR and open(FOO, "cmd |")
+etc., are implemented via \fBfork()\fR and \fBexec()\fR.  When the underlying
+\&\fBexec()\fR fails, earlier versions did not report the error properly,
+since the \fBexec()\fR happened to be in a different process.
+.PP
+The child process now communicates with the parent about the
+error in launching the external command, which allows these
+constructs to return with their usual error value and set $!.
+.SS "Improved diagnostics"
+.IX Subsection "Improved diagnostics"
+Line numbers are no longer suppressed (under most likely circumstances)
+during the global destruction phase.
+.PP
+Diagnostics emitted from code running in threads other than the main
+thread are now accompanied by the thread ID.
+.PP
+Embedded null characters in diagnostics now actually show up.  They
+used to truncate the message in prior versions.
+.PP
+\&\f(CW$foo::a\fR and \f(CW$foo::b\fR are now exempt from "possible typo" warnings only
+if \fBsort()\fR is encountered in package \f(CW\*(C`foo\*(C'\fR.
+.PP
+Unrecognized alphabetic escapes encountered when parsing quote
+constructs now generate a warning, since they may take on new
+semantics in later versions of Perl.
+.PP
+Many diagnostics now report the internal operation in which the warning
+was provoked, like so:
+.PP
+.Vb 2
+\&    Use of uninitialized value in concatenation (.) at (eval 1) line 1.
+\&    Use of uninitialized value in print at (eval 1) line 1.
+.Ve
+.PP
+Diagnostics  that occur within eval may also report the file and line
+number where the eval is located, in addition to the eval sequence
+number and the line number within the evaluated text itself.  For
+example:
+.PP
+.Vb 1
+\&    Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF
+.Ve
+.SS "Diagnostics follow STDERR"
+.IX Subsection "Diagnostics follow STDERR"
+Diagnostic output now goes to whichever file the \f(CW\*(C`STDERR\*(C'\fR handle
+is pointing at, instead of always going to the underlying C runtime
+library's \f(CW\*(C`stderr\*(C'\fR.
+.SS "More consistent close-on-exec behavior"
+.IX Subsection "More consistent close-on-exec behavior"
+On systems that support a close-on-exec flag on filehandles, the
+flag is now set for any handles created by \fBpipe()\fR, \fBsocketpair()\fR,
+\&\fBsocket()\fR, and \fBaccept()\fR, if that is warranted by the value of $^F
+that may be in effect.  Earlier versions neglected to set the flag
+for handles created with these operators.  See "pipe" in perlfunc,
+"socketpair" in perlfunc, "socket" in perlfunc, "accept" in perlfunc,
+and "$^F" in perlvar.
+.SS "\fBsyswrite()\fP ease-of-use"
+.IX Subsection "syswrite() ease-of-use"
+The length argument of \f(CWsyswrite()\fR has become optional.
+.SS "Better syntax checks on parenthesized unary operators"
+.IX Subsection "Better syntax checks on parenthesized unary operators"
+Expressions such as:
+.PP
+.Vb 3
+\&    print defined(&foo,&bar,&baz);
+\&    print uc("foo","bar","baz");
+\&    undef($foo,&bar);
+.Ve
+.PP
+used to be accidentally allowed in earlier versions, and produced
+unpredictable behaviour.  Some produced ancillary warnings
+when used in this way; others silently did the wrong thing.
+.PP
+The parenthesized forms of most unary operators that expect a single
+argument now ensure that they are not called with more than one
+argument, making the cases shown above syntax errors.  The usual
+behaviour of:
+.PP
+.Vb 3
+\&    print defined &foo, &bar, &baz;
+\&    print uc "foo", "bar", "baz";
+\&    undef $foo, &bar;
+.Ve
+.PP
+remains unchanged.  See perlop.
+.SS "Bit operators support full native integer width"
+.IX Subsection "Bit operators support full native integer width"
+The bit operators (& | ^ ~ << >>) now operate on the full native
+integral width (the exact size of which is available in \f(CW$Config\fR{ivsize}).
+For example, if your platform is either natively 64\-bit or if Perl
+has been configured to use 64\-bit integers, these operations apply
+to 8 bytes (as opposed to 4 bytes on 32\-bit platforms).
+For portability, be sure to mask off the excess bits in the result of
+unary \f(CW\*(C`~\*(C'\fR, e.g., \f(CW\*(C`~$x & 0xffffffff\*(C'\fR.
+.SS "Improved security features"
+.IX Subsection "Improved security features"
+More potentially unsafe operations taint their results for improved
+security.
+.PP
+The \f(CW\*(C`passwd\*(C'\fR and \f(CW\*(C`shell\*(C'\fR fields returned by the \fBgetpwent()\fR, \fBgetpwnam()\fR,
+and \fBgetpwuid()\fR are now tainted, because the user can affect their own
+encrypted password and login shell.
+.PP
+The variable modified by \fBshmread()\fR, and messages returned by \fBmsgrcv()\fR
+(and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted,
+because other untrusted processes can modify messages and shared memory
+segments for their own nefarious purposes.
+.SS "More functional bareword prototype (*)"
+.IX Subsection "More functional bareword prototype (*)"
+Bareword prototypes have been rationalized to enable them to be used
+to override builtins that accept barewords and interpret them in
+a special way, such as \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR.
+.PP
+Arguments prototyped as \f(CW\*(C`*\*(C'\fR will now be visible within the subroutine
+as either a simple scalar or as a reference to a typeglob.
+See "Prototypes" in perlsub.
+.ie n .SS """require"" and ""do"" may be overridden"
+.el .SS "\f(CWrequire\fP and \f(CWdo\fP may be overridden"
+.IX Subsection "require and do may be overridden"
+\&\f(CW\*(C`require\*(C'\fR and \f(CW\*(C`do \*(Aqfile\*(Aq\*(C'\fR operations may be overridden locally
+by importing subroutines of the same name into the current package 
+(or globally by importing them into the CORE::GLOBAL:: namespace).
+Overriding \f(CW\*(C`require\*(C'\fR will also affect \f(CW\*(C`use\*(C'\fR, provided the override
+is visible at compile-time.
+See "Overriding Built-in Functions" in perlsub.
+.SS "$^X variables may now have names longer than one character"
+.IX Subsection "$^X variables may now have names longer than one character"
+Formerly, $^X was synonymous with ${"\ecX"}, but $^XY was a syntax
+error.  Now variable names that begin with a control character may be
+arbitrarily long.  However, for compatibility reasons, these variables
+\&\fImust\fR be written with explicit braces, as \f(CW\*(C`${^XY}\*(C'\fR for example.
+\&\f(CW\*(C`${^XYZ}\*(C'\fR is synonymous with ${"\ecXYZ"}.  Variable names with more
+than one control character, such as \f(CW\*(C`${^XY^Z}\*(C'\fR, are illegal.
+.PP
+The old syntax has not changed.  As before, `^X' may be either a
+literal control-X character or the two-character sequence `caret' plus
+`X'.  When braces are omitted, the variable name stops after the
+control character.  Thus \f(CW"$^XYZ"\fR continues to be synonymous with
+\&\f(CW\*(C`$^X . "YZ"\*(C'\fR as before.
+.PP
+As before, lexical variables may not have names beginning with control
+characters.  As before, variables whose names begin with a control
+character are always forced to be in package `main'.  All such variables
+are reserved for future extensions, except those that begin with
+\&\f(CW\*(C`^_\*(C'\fR, which may be used by user programs and are guaranteed not to
+acquire special meaning in any future version of Perl.
+.ie n .SS "New variable $^C reflects ""\-c"" switch"
+.el .SS "New variable $^C reflects \f(CW\-c\fP switch"
+.IX Subsection "New variable $^C reflects -c switch"
+\&\f(CW$^C\fR has a boolean value that reflects whether perl is being run
+in compile-only mode (i.e. via the \f(CW\*(C`\-c\*(C'\fR switch).  Since
+BEGIN blocks are executed under such conditions, this variable
+enables perl code to determine whether actions that make sense
+only during normal running are warranted.  See perlvar.
+.SS "New variable $^V contains Perl version as a string"
+.IX Subsection "New variable $^V contains Perl version as a string"
+\&\f(CW$^V\fR contains the Perl version number as a string composed of
+characters whose ordinals match the version numbers, i.e. v5.6.0.
+This may be used in string comparisons.
+.PP
+See \f(CW\*(C`Support for strings represented as a vector of ordinals\*(C'\fR for an
+example.
+.SS "Optional Y2K warnings"
+.IX Subsection "Optional Y2K warnings"
+If Perl is built with the cpp macro \f(CW\*(C`PERL_Y2KWARN\*(C'\fR defined,
+it emits optional warnings when concatenating the number 19
+with another number.
+.PP
+This behavior must be specifically enabled when running Configure.
+See \fIINSTALL\fR and \fIREADME.Y2K\fR.
+.SS "Arrays now always interpolate into double-quoted strings"
+.IX Subsection "Arrays now always interpolate into double-quoted strings"
+In double-quoted strings, arrays now interpolate, no matter what.  The
+behavior in earlier versions of perl 5 was that arrays would interpolate
+into strings if the array had been mentioned before the string was
+compiled, and otherwise Perl would raise a fatal compile-time error.
+In versions 5.000 through 5.003, the error was
+.PP
+.Vb 1
+\&        Literal @example now requires backslash
+.Ve
+.PP
+In versions 5.004_01 through 5.6.0, the error was
+.PP
+.Vb 1
+\&        In string, @example now must be written as \e@example
+.Ve
+.PP
+The idea here was to get people into the habit of writing
+\&\f(CW"fred\e@example.com"\fR when they wanted a literal \f(CW\*(C`@\*(C'\fR sign, just as
+they have always written \f(CW"Give me back my \e$5"\fR when they wanted a
+literal \f(CW\*(C`$\*(C'\fR sign.
+.PP
+Starting with 5.6.1, when Perl now sees an \f(CW\*(C`@\*(C'\fR sign in a
+double-quoted string, it \fIalways\fR attempts to interpolate an array,
+regardless of whether or not the array has been used or declared
+already.  The fatal error has been downgraded to an optional warning:
+.PP
+.Vb 1
+\&        Possible unintended interpolation of @example in string
+.Ve
+.PP
+This warns you that \f(CW"fred@example.com"\fR is going to turn into
+\&\f(CW\*(C`fred.com\*(C'\fR if you don't backslash the \f(CW\*(C`@\*(C'\fR.
+See http://perl.plover.com/at\-error.html for more details
+about the history here.
+.SS "@\- and @+ provide starting/ending offsets of regex submatches"
+.IX Subsection "@- and @+ provide starting/ending offsets of regex submatches"
+The new magic variables @\- and @+ provide the starting and ending
+offsets, respectively, of $&, \f(CW$1\fR, \f(CW$2\fR, etc.  See perlvar for
+details.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS Modules
+.IX Subsection "Modules"
+.IP attributes 4
+.IX Item "attributes"
+While used internally by Perl as a pragma, this module also
+provides a way to fetch subroutine and variable attributes.
+See attributes.
+.IP B 4
+.IX Item "B"
+The Perl Compiler suite has been extensively reworked for this
+release.  More of the standard Perl test suite passes when run
+under the Compiler, but there is still a significant way to
+go to achieve production quality compiled executables.
+.Sp
+.Vb 3
+\&    NOTE: The Compiler suite remains highly experimental.  The
+\&    generated code may not be correct, even when it manages to execute
+\&    without errors.
+.Ve
+.IP Benchmark 4
+.IX Item "Benchmark"
+Overall, Benchmark results exhibit lower average error and better timing
+accuracy.
+.Sp
+You can now run tests for \fIn\fR seconds instead of guessing the right
+number of tests to run: e.g., timethese(\-5, ...) will run each 
+code for at least 5 CPU seconds.  Zero as the "number of repetitions"
+means "for at least 3 CPU seconds".  The output format has also
+changed.  For example:
+.Sp
+.Vb 1
+\&   use Benchmark;$x=3;timethese(\-5,{a=>sub{$x*$x},b=>sub{$x**2}})
+.Ve
+.Sp
+will now output something like this:
+.Sp
+.Vb 3
+\&   Benchmark: running a, b, each for at least 5 CPU seconds...
+\&            a:  5 wallclock secs ( 5.77 usr +  0.00 sys =  5.77 CPU) @ 200551.91/s (n=1156516)
+\&            b:  4 wallclock secs ( 5.00 usr +  0.02 sys =  5.02 CPU) @ 159605.18/s (n=800686)
+.Ve
+.Sp
+New features: "each for at least N CPU seconds...", "wallclock secs",
+and the "@ operations/CPU second (n=operations)".
+.Sp
+\&\fBtimethese()\fR now returns a reference to a hash of Benchmark objects containing
+the test results, keyed on the names of the tests.
+.Sp
+\&\fBtimethis()\fR now returns the iterations field in the Benchmark result object
+instead of 0.
+.Sp
+\&\fBtimethese()\fR, \fBtimethis()\fR, and the new \fBcmpthese()\fR (see below) can also take
+a format specifier of 'none' to suppress output.
+.Sp
+A new function \fBcountit()\fR is just like \fBtimeit()\fR except that it takes a
+TIME instead of a COUNT.
+.Sp
+A new function \fBcmpthese()\fR prints a chart comparing the results of each test
+returned from a \fBtimethese()\fR call.  For each possible pair of tests, the
+percentage speed difference (iters/sec or seconds/iter) is shown.
+.Sp
+For other details, see Benchmark.
+.IP ByteLoader 4
+.IX Item "ByteLoader"
+The ByteLoader is a dedicated extension to generate and run
+Perl bytecode.  See ByteLoader.
+.IP constant 4
+.IX Item "constant"
+References can now be used.
+.Sp
+The new version also allows a leading underscore in constant names, but
+disallows a double leading underscore (as in "_\|_LINE_\|_").  Some other names
+are disallowed or warned against, including BEGIN, END, etc.  Some names
+which were forced into main:: used to fail silently in some cases; now they're
+fatal (outside of main::) and an optional warning (inside of main::).
+The ability to detect whether a constant had been set with a given name has
+been added.
+.Sp
+See constant.
+.IP charnames 4
+.IX Item "charnames"
+This pragma implements the \f(CW\*(C`\eN\*(C'\fR string escape.  See charnames.
+.IP Data::Dumper 4
+.IX Item "Data::Dumper"
+A \f(CW\*(C`Maxdepth\*(C'\fR setting can be specified to avoid venturing
+too deeply into deep data structures.  See Data::Dumper.
+.Sp
+The XSUB implementation of \fBDump()\fR is now automatically called if the
+\&\f(CW\*(C`Useqq\*(C'\fR setting is not in use.
+.Sp
+Dumping \f(CW\*(C`qr//\*(C'\fR objects works correctly.
+.IP DB 4
+.IX Item "DB"
+\&\f(CW\*(C`DB\*(C'\fR is an experimental module that exposes a clean abstraction
+to Perl's debugging API.
+.IP DB_File 4
+.IX Item "DB_File"
+DB_File can now be built with Berkeley DB versions 1, 2 or 3.
+See \f(CW\*(C`ext/DB_File/Changes\*(C'\fR.
+.IP Devel::DProf 4
+.IX Item "Devel::DProf"
+Devel::DProf, a Perl source code profiler has been added.  See
+Devel::DProf and dprofpp.
+.IP Devel::Peek 4
+.IX Item "Devel::Peek"
+The Devel::Peek module provides access to the internal representation
+of Perl variables and data.  It is a data debugging tool for the XS programmer.
+.IP Dumpvalue 4
+.IX Item "Dumpvalue"
+The Dumpvalue module provides screen dumps of Perl data.
+.IP DynaLoader 4
+.IX Item "DynaLoader"
+DynaLoader now supports a \fBdl_unload_file()\fR function on platforms that
+support unloading shared objects using \fBdlclose()\fR.
+.Sp
+Perl can also optionally arrange to unload all extension shared objects
+loaded by Perl.  To enable this, build Perl with the Configure option
+\&\f(CW\*(C`\-Accflags=\-DDL_UNLOAD_ALL_AT_EXIT\*(C'\fR.  (This maybe useful if you are
+using Apache with mod_perl.)
+.IP English 4
+.IX Item "English"
+\&\f(CW$PERL_VERSION\fR now stands for \f(CW$^V\fR (a string value) rather than for \f(CW$]\fR
+(a numeric value).
+.IP Env 4
+.IX Item "Env"
+Env now supports accessing environment variables like PATH as array
+variables.
+.IP Fcntl 4
+.IX Item "Fcntl"
+More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
+large file (more than 4GB) access (NOTE: the O_LARGEFILE is
+automatically added to \fBsysopen()\fR flags if large file support has been
+configured, as is the default), Free/Net/OpenBSD locking behaviour
+flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined
+mask of O_RDONLY, O_WRONLY, and O_RDWR.  The \fBseek()\fR/\fBsysseek()\fR
+constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the
+\&\f(CW\*(C`:seek\*(C'\fR tag.  The \fBchmod()\fR/\fBstat()\fR S_IF* constants and S_IS* functions
+are available via the \f(CW\*(C`:mode\*(C'\fR tag.
+.IP File::Compare 4
+.IX Item "File::Compare"
+A \fBcompare_text()\fR function has been added, which allows custom
+comparison functions.  See File::Compare.
+.IP File::Find 4
+.IX Item "File::Find"
+File::Find now works correctly when the \fBwanted()\fR function is either
+autoloaded or is a symbolic reference.
+.Sp
+A bug that caused File::Find to lose track of the working directory
+when pruning top-level directories has been fixed.
+.Sp
+File::Find now also supports several other options to control its
+behavior.  It can follow symbolic links if the \f(CW\*(C`follow\*(C'\fR option is
+specified.  Enabling the \f(CW\*(C`no_chdir\*(C'\fR option will make File::Find skip
+changing the current directory when walking directories.  The \f(CW\*(C`untaint\*(C'\fR
+flag can be useful when running with taint checks enabled.
+.Sp
+See File::Find.
+.IP File::Glob 4
+.IX Item "File::Glob"
+This extension implements BSD-style file globbing.  By default,
+it will also be used for the internal implementation of the \fBglob()\fR
+operator.  See File::Glob.
+.IP File::Spec 4
+.IX Item "File::Spec"
+New methods have been added to the File::Spec module: \fBdevnull()\fR returns
+the name of the null device (/dev/null on Unix) and \fBtmpdir()\fR the name of
+the temp directory (normally /tmp on Unix).  There are now also methods
+to convert between absolute and relative filenames: \fBabs2rel()\fR and
+\&\fBrel2abs()\fR.  For compatibility with operating systems that specify volume
+names in file paths, the \fBsplitpath()\fR, \fBsplitdir()\fR, and \fBcatdir()\fR methods
+have been added.
+.IP File::Spec::Functions 4
+.IX Item "File::Spec::Functions"
+The new File::Spec::Functions modules provides a function interface
+to the File::Spec module.  Allows shorthand
+.Sp
+.Vb 1
+\&    $fullname = catfile($dir1, $dir2, $file);
+.Ve
+.Sp
+instead of
+.Sp
+.Vb 1
+\&    $fullname = File::Spec\->catfile($dir1, $dir2, $file);
+.Ve
+.IP Getopt::Long 4
+.IX Item "Getopt::Long"
+Getopt::Long licensing has changed to allow the Perl Artistic License
+as well as the GPL. It used to be GPL only, which got in the way of
+non-GPL applications that wanted to use Getopt::Long.
+.Sp
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
+.Sp
+.Vb 7
+\&    use Getopt::Long;
+\&    use Pod::Usage;
+\&    my $man = 0;
+\&    my $help = 0;
+\&    GetOptions(\*(Aqhelp|?\*(Aq => \e$help, man => \e$man) or pod2usage(2);
+\&    pod2usage(1) if $help;
+\&    pod2usage(\-exitstatus => 0, \-verbose => 2) if $man;
+\&
+\&    _\|_END_\|_
+\&
+\&    =head1 NAME
+\&
+\&    sample \- Using Getopt::Long and Pod::Usage
+\&
+\&    =head1 SYNOPSIS
+\&
+\&    sample [options] [file ...]
+\&
+\&     Options:
+\&       \-help            brief help message
+\&       \-man             full documentation
+\&
+\&    =head1 OPTIONS
+\&
+\&    =over 8
+\&
+\&    =item B<\-help>
+\&
+\&    Print a brief help message and exits.
+\&
+\&    =item B<\-man>
+\&
+\&    Prints the manual page and exits.
+\&
+\&    =back
+\&
+\&    =head1 DESCRIPTION
+\&
+\&    B<This program> will read the given input file(s) and do something
+\&    useful with the contents thereof.
+\&
+\&    =cut
+.Ve
+.Sp
+See Pod::Usage for details.
+.Sp
+A bug that prevented the non-option call-back <> from being
+specified as the first argument has been fixed.
+.Sp
+To specify the characters < and > as option starters, use ><. Note,
+however, that changing option starters is strongly deprecated.
+.IP IO 4
+.IX Item "IO"
+\&\fBwrite()\fR and \fBsyswrite()\fR will now accept a single-argument
+form of the call, for consistency with Perl's \fBsyswrite()\fR.
+.Sp
+You can now create a TCP-based IO::Socket::INET without forcing
+a connect attempt.  This allows you to configure its options
+(like making it non-blocking) and then call \fBconnect()\fR manually.
+.Sp
+A bug that prevented the \fBIO::Socket::protocol()\fR accessor
+from ever returning the correct value has been corrected.
+.Sp
+IO::Socket::connect now uses non-blocking IO instead of \fBalarm()\fR
+to do connect timeouts.
+.Sp
+IO::Socket::accept now uses \fBselect()\fR instead of \fBalarm()\fR for doing
+timeouts.
+.Sp
+IO::Socket::INET\->new now sets $! correctly on failure. $@ is
+still set for backwards compatibility.
+.IP JPL 4
+.IX Item "JPL"
+Java Perl Lingo is now distributed with Perl.  See jpl/README
+for more information.
+.IP lib 4
+.IX Item "lib"
+\&\f(CW\*(C`use lib\*(C'\fR now weeds out any trailing duplicate entries.
+\&\f(CW\*(C`no lib\*(C'\fR removes all named entries.
+.IP Math::BigInt 4
+.IX Item "Math::BigInt"
+The bitwise operations \f(CW\*(C`<<\*(C'\fR, \f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR,
+and \f(CW\*(C`~\*(C'\fR are now supported on bigints.
+.IP Math::Complex 4
+.IX Item "Math::Complex"
+The accessor methods Re, Im, arg, abs, rho, and theta can now also
+act as mutators (accessor \f(CW$z\fR\->\fBRe()\fR, mutator \f(CW$z\fR\->\fBRe\fR\|(3)).
+.Sp
+The class method \f(CW\*(C`display_format\*(C'\fR and the corresponding object method
+\&\f(CW\*(C`display_format\*(C'\fR, in addition to accepting just one argument, now can
+also accept a parameter hash.  Recognized keys of a parameter hash are
+\&\f(CW"style"\fR, which corresponds to the old one parameter case, and two
+new parameters: \f(CW"format"\fR, which is a \fBprintf()\fR\-style format string
+(defaults usually to \f(CW"%.15g"\fR, you can revert to the default by
+setting the format string to \f(CW\*(C`undef\*(C'\fR) used for both parts of a
+complex number, and \f(CW"polar_pretty_print"\fR (defaults to true),
+which controls whether an attempt is made to try to recognize small
+multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a
+polar complex number.
+.Sp
+The potentially disruptive change is that in list context both methods
+now \fIreturn the parameter hash\fR, instead of only the value of the
+\&\f(CW"style"\fR parameter.
+.IP Math::Trig 4
+.IX Item "Math::Trig"
+A little bit of radial trigonometry (cylindrical and spherical),
+radial coordinate conversions, and the great circle distance were added.
+.IP "Pod::Parser, Pod::InputObjects" 4
+.IX Item "Pod::Parser, Pod::InputObjects"
+Pod::Parser is a base class for parsing and selecting sections of
+pod documentation from an input stream.  This module takes care of
+identifying pod paragraphs and commands in the input and hands off the
+parsed paragraphs and commands to user-defined methods which are free
+to interpret or translate them as they see fit.
+.Sp
+Pod::InputObjects defines some input objects needed by Pod::Parser, and
+for advanced users of Pod::Parser that need more about a command besides
+its name and text.
+.Sp
+As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned
+"base parser code" recommended for use by all pod2xxx translators.
+Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted
+to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already
+underway.  For any questions or comments about pod parsing and translating
+issues and utilities, please use the pod\-people@perl.org mailing list.
+.Sp
+For further information, please see Pod::Parser and Pod::InputObjects.
+.IP "Pod::Checker, podchecker" 4
+.IX Item "Pod::Checker, podchecker"
+This utility checks pod files for correct syntax, according to
+perlpod.  Obvious errors are flagged as such, while warnings are
+printed for mistakes that can be handled gracefully.  The checklist is
+not complete yet.  See Pod::Checker.
+.IP "Pod::ParseUtils, Pod::Find" 4
+.IX Item "Pod::ParseUtils, Pod::Find"
+These modules provide a set of gizmos that are useful mainly for pod
+translators.  Pod::Find traverses directory structures and
+returns found pod files, along with their canonical names (like
+\&\f(CW\*(C`File::Spec::Unix\*(C'\fR).  Pod::ParseUtils contains
+\&\fBPod::List\fR (useful for storing pod list information), \fBPod::Hyperlink\fR
+(for parsing the contents of \f(CW\*(C`L<>\*(C'\fR sequences) and \fBPod::Cache\fR
+(for caching information about pod files, e.g., link nodes).
+.IP "Pod::Select, podselect" 4
+.IX Item "Pod::Select, podselect"
+Pod::Select is a subclass of Pod::Parser which provides a function
+named "\fBpodselect()\fR" to filter out user-specified sections of raw pod
+documentation from an input stream. podselect is a script that provides
+access to Pod::Select from other scripts to be used as a filter.
+See Pod::Select.
+.IP "Pod::Usage, pod2usage" 4
+.IX Item "Pod::Usage, pod2usage"
+Pod::Usage provides the function "\fBpod2usage()\fR" to print usage messages for
+a Perl script based on its embedded pod documentation.  The \fBpod2usage()\fR
+function is generally useful to all script authors since it lets them
+write and maintain a single source (the pods) for documentation, thus
+removing the need to create and maintain redundant usage message text
+consisting of information already in the pods.
+.Sp
+There is also a pod2usage script which can be used from other kinds of
+scripts to print usage messages from pods (even for non-Perl scripts
+with pods embedded in comments).
+.Sp
+For details and examples, please see Pod::Usage.
+.IP "Pod::Text and Pod::Man" 4
+.IX Item "Pod::Text and Pod::Man"
+Pod::Text has been rewritten to use Pod::Parser.  While \fBpod2text()\fR is
+still available for backwards compatibility, the module now has a new
+preferred interface.  See Pod::Text for the details.  The new Pod::Text
+module is easily subclassed for tweaks to the output, and two such
+subclasses (Pod::Text::Termcap for man-page-style bold and underlining
+using termcap information, and Pod::Text::Color for markup with ANSI color
+sequences) are now standard.
+.Sp
+pod2man has been turned into a module, Pod::Man, which also uses
+Pod::Parser.  In the process, several outstanding bugs related to quotes
+in section headers, quoting of code escapes, and nested lists have been
+fixed.  pod2man is now a wrapper script around this module.
+.IP SDBM_File 4
+.IX Item "SDBM_File"
+An EXISTS method has been added to this module (and \fBsdbm_exists()\fR has
+been added to the underlying sdbm library), so one can now call exists
+on an SDBM_File tied hash and get the correct result, rather than a
+runtime error.
+.Sp
+A bug that may have caused data loss when more than one disk block
+happens to be read from the database in a single \fBFETCH()\fR has been
+fixed.
+.IP Sys::Syslog 4
+.IX Item "Sys::Syslog"
+Sys::Syslog now uses XSUBs to access facilities from syslog.h so it
+no longer requires syslog.ph to exist.
+.IP Sys::Hostname 4
+.IX Item "Sys::Hostname"
+Sys::Hostname now uses XSUBs to call the C library's \fBgethostname()\fR or
+\&\fBuname()\fR if they exist.
+.IP Term::ANSIColor 4
+.IX Item "Term::ANSIColor"
+Term::ANSIColor is a very simple module to provide easy and readable
+access to the ANSI color and highlighting escape sequences, supported by
+most ANSI terminal emulators.  It is now included standard.
+.IP Time::Local 4
+.IX Item "Time::Local"
+The \fBtimelocal()\fR and \fBtimegm()\fR functions used to silently return bogus
+results when the date fell outside the machine's integer range.  They
+now consistently \fBcroak()\fR if the date falls in an unsupported range.
+.IP Win32 4
+.IX Item "Win32"
+The error return value in list context has been changed for all functions
+that return a list of values.  Previously these functions returned a list
+with a single element \f(CW\*(C`undef\*(C'\fR if an error occurred.  Now these functions
+return the empty list in these situations.  This applies to the following
+functions:
+.Sp
+.Vb 2
+\&    Win32::FsType
+\&    Win32::GetOSVersion
+.Ve
+.Sp
+The remaining functions are unchanged and continue to return \f(CW\*(C`undef\*(C'\fR on
+error even in list context.
+.Sp
+The Win32::SetLastError(ERROR) function has been added as a complement
+to the \fBWin32::GetLastError()\fR function.
+.Sp
+The new Win32::GetFullPathName(FILENAME) returns the full absolute
+pathname for FILENAME in scalar context.  In list context it returns
+a two-element list containing the fully qualified directory name and
+the filename.  See Win32.
+.IP XSLoader 4
+.IX Item "XSLoader"
+The XSLoader extension is a simpler alternative to DynaLoader.
+See XSLoader.
+.IP "DBM Filters" 4
+.IX Item "DBM Filters"
+A new feature called "DBM Filters" has been added to all the
+DBM modules\-\-DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File.
+DBM Filters add four new methods to each DBM module:
+.Sp
+.Vb 4
+\&    filter_store_key
+\&    filter_store_value
+\&    filter_fetch_key
+\&    filter_fetch_value
+.Ve
+.Sp
+These can be used to filter key-value pairs before the pairs are
+written to the database or just after they are read from the database.
+See perldbmfilter for further information.
+.SS Pragmata
+.IX Subsection "Pragmata"
+\&\f(CW\*(C`use attrs\*(C'\fR is now obsolete, and is only provided for
+backward-compatibility.  It's been replaced by the \f(CW\*(C`sub : attributes\*(C'\fR
+syntax.  See "Subroutine Attributes" in perlsub and attributes.
+.PP
+Lexical warnings pragma, \f(CW\*(C`use warnings;\*(C'\fR, to control optional warnings.
+See perllexwarn.
+.PP
+\&\f(CW\*(C`use filetest\*(C'\fR to control the behaviour of filetests (\f(CW\*(C`\-r\*(C'\fR \f(CW\*(C`\-w\*(C'\fR
+\&...).  Currently only one subpragma implemented, "use filetest
+\&'access';", that uses \fBaccess\fR\|(2) or equivalent to check permissions
+instead of using \fBstat\fR\|(2) as usual.  This matters in filesystems
+where there are ACLs (access control lists): the \fBstat\fR\|(2) might lie,
+but \fBaccess\fR\|(2) knows better.
+.PP
+The \f(CW\*(C`open\*(C'\fR pragma can be used to specify default disciplines for
+handle constructors (e.g. \fBopen()\fR) and for qx//.  The two
+pseudo-disciplines \f(CW\*(C`:raw\*(C'\fR and \f(CW\*(C`:crlf\*(C'\fR are currently supported on
+DOS-derivative platforms (i.e. where binmode is not a no-op).
+See also "\fBbinmode()\fR can be used to set :crlf and :raw modes".
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS dprofpp
+.IX Subsection "dprofpp"
+\&\f(CW\*(C`dprofpp\*(C'\fR is used to display profile data generated using \f(CW\*(C`Devel::DProf\*(C'\fR.
+See dprofpp.
+.SS find2perl
+.IX Subsection "find2perl"
+The \f(CW\*(C`find2perl\*(C'\fR utility now uses the enhanced features of the File::Find
+module.  The \-depth and \-follow options are supported.  Pod documentation
+is also included in the script.
+.SS h2xs
+.IX Subsection "h2xs"
+The \f(CW\*(C`h2xs\*(C'\fR tool can now work in conjunction with \f(CW\*(C`C::Scan\*(C'\fR (available
+from CPAN) to automatically parse real-life header files.  The \f(CW\*(C`\-M\*(C'\fR,
+\&\f(CW\*(C`\-a\*(C'\fR, \f(CW\*(C`\-k\*(C'\fR, and \f(CW\*(C`\-o\*(C'\fR options are new.
+.SS perlcc
+.IX Subsection "perlcc"
+\&\f(CW\*(C`perlcc\*(C'\fR now supports the C and Bytecode backends.  By default,
+it generates output from the simple C backend rather than the
+optimized C backend.
+.PP
+Support for non-Unix platforms has been improved.
+.SS perldoc
+.IX Subsection "perldoc"
+\&\f(CW\*(C`perldoc\*(C'\fR has been reworked to avoid possible security holes.
+It will not by default let itself be run as the superuser, but you
+may still use the \fB\-U\fR switch to try to make it drop privileges
+first.
+.SS "The Perl Debugger"
+.IX Subsection "The Perl Debugger"
+Many bug fixes and enhancements were added to \fIperl5db.pl\fR, the
+Perl debugger.  The help documentation was rearranged.  New commands
+include \f(CW\*(C`< ?\*(C'\fR, \f(CW\*(C`> ?\*(C'\fR, and \f(CW\*(C`{ ?\*(C'\fR to list out current
+actions, \f(CW\*(C`man \fR\f(CIdocpage\fR\f(CW\*(C'\fR to run your doc viewer on some perl
+docset, and support for quoted options.  The help information was
+rearranged, and should be viewable once again if you're using \fBless\fR
+as your pager.  A serious security hole was plugged\-\-you should
+immediately remove all older versions of the Perl debugger as
+installed in previous releases, all the way back to perl3, from
+your system to avoid being bitten by this.
+.SH "Improved Documentation"
+.IX Header "Improved Documentation"
+Many of the platform-specific README files are now part of the perl
+installation.  See perl for the complete list.
+.IP perlapi.pod 4
+.IX Item "perlapi.pod"
+The official list of public Perl API functions.
+.IP perlboot.pod 4
+.IX Item "perlboot.pod"
+A tutorial for beginners on object-oriented Perl.
+.IP perlcompile.pod 4
+.IX Item "perlcompile.pod"
+An introduction to using the Perl Compiler suite.
+.IP perldbmfilter.pod 4
+.IX Item "perldbmfilter.pod"
+A howto document on using the DBM filter facility.
+.IP perldebug.pod 4
+.IX Item "perldebug.pod"
+All material unrelated to running the Perl debugger, plus all
+low-level guts-like details that risked crushing the casual user
+of the debugger, have been relocated from the old manpage to the
+next entry below.
+.IP perldebguts.pod 4
+.IX Item "perldebguts.pod"
+This new manpage contains excessively low-level material not related
+to the Perl debugger, but slightly related to debugging Perl itself.
+It also contains some arcane internal details of how the debugging
+process works that may only be of interest to developers of Perl
+debuggers.
+.IP perlfork.pod 4
+.IX Item "perlfork.pod"
+Notes on the \fBfork()\fR emulation currently available for the Windows platform.
+.IP perlfilter.pod 4
+.IX Item "perlfilter.pod"
+An introduction to writing Perl source filters.
+.IP perlhack.pod 4
+.IX Item "perlhack.pod"
+Some guidelines for hacking the Perl source code.
+.IP perlintern.pod 4
+.IX Item "perlintern.pod"
+A list of internal functions in the Perl source code.
+(List is currently empty.)
+.IP perllexwarn.pod 4
+.IX Item "perllexwarn.pod"
+Introduction and reference information about lexically scoped
+warning categories.
+.IP perlnumber.pod 4
+.IX Item "perlnumber.pod"
+Detailed information about numbers as they are represented in Perl.
+.IP perlopentut.pod 4
+.IX Item "perlopentut.pod"
+A tutorial on using \fBopen()\fR effectively.
+.IP perlreftut.pod 4
+.IX Item "perlreftut.pod"
+A tutorial that introduces the essentials of references.
+.IP perltootc.pod 4
+.IX Item "perltootc.pod"
+A tutorial on managing class data for object modules.
+.IP perltodo.pod 4
+.IX Item "perltodo.pod"
+Discussion of the most often wanted features that may someday be
+supported in Perl.
+.IP perlunicode.pod 4
+.IX Item "perlunicode.pod"
+An introduction to Unicode support features in Perl.
+.SH "Performance enhancements"
+.IX Header "Performance enhancements"
+.ie n .SS "Simple \fBsort()\fP using { $a <=> $b } and the like are optimized"
+.el .SS "Simple \fBsort()\fP using { \f(CW$a\fP <=> \f(CW$b\fP } and the like are optimized"
+.IX Subsection "Simple sort() using { $a <=> $b } and the like are optimized"
+Many common \fBsort()\fR operations using a simple inlined block are now
+optimized for faster performance.
+.SS "Optimized assignments to lexical variables"
+.IX Subsection "Optimized assignments to lexical variables"
+Certain operations in the RHS of assignment statements have been
+optimized to directly set the lexical variable on the LHS,
+eliminating redundant copying overheads.
+.SS "Faster subroutine calls"
+.IX Subsection "Faster subroutine calls"
+Minor changes in how subroutine calls are handled internally
+provide marginal improvements in performance.
+.SS "\fBdelete()\fP, \fBeach()\fP, \fBvalues()\fP and hash iteration are faster"
+.IX Subsection "delete(), each(), values() and hash iteration are faster"
+The hash values returned by \fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hashes in a
+list context are the actual values in the hash, instead of copies.
+This results in significantly better performance, because it eliminates
+needless copying in most situations.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "\-Dusethreads means something different"
+.IX Subsection "-Dusethreads means something different"
+The \-Dusethreads flag now enables the experimental interpreter-based thread
+support by default.  To get the flavor of experimental threads that was in
+5.005 instead, you need to run Configure with "\-Dusethreads \-Duse5005threads".
+.PP
+As of v5.6.0, interpreter-threads support is still lacking a way to
+create new threads from Perl (i.e., \f(CW\*(C`use Thread;\*(C'\fR will not work with
+interpreter threads).  \f(CW\*(C`use Thread;\*(C'\fR continues to be available when you
+specify the \-Duse5005threads option to Configure, bugs and all.
+.PP
+.Vb 2
+\&    NOTE: Support for threads continues to be an experimental feature.
+\&    Interfaces and implementation are subject to sudden and drastic changes.
+.Ve
+.SS "New Configure flags"
+.IX Subsection "New Configure flags"
+The following new flags may be enabled on the Configure command line
+by running Configure with \f(CW\*(C`\-Dflag\*(C'\fR.
+.PP
+.Vb 3
+\&    usemultiplicity
+\&    usethreads useithreads      (new interpreter threads: no Perl API yet)
+\&    usethreads use5005threads   (threads as they were in 5.005)
+\&
+\&    use64bitint                 (equal to now deprecated \*(Aquse64bits\*(Aq)
+\&    use64bitall
+\&
+\&    uselongdouble
+\&    usemorebits
+\&    uselargefiles
+\&    usesocks                    (only SOCKS v5 supported)
+.Ve
+.SS "Threadedness and 64\-bitness now more daring"
+.IX Subsection "Threadedness and 64-bitness now more daring"
+The Configure options enabling the use of threads and the use of
+64\-bitness are now more daring in the sense that they no more have an
+explicit list of operating systems of known threads/64\-bit
+capabilities.  In other words: if your operating system has the
+necessary APIs and datatypes, you should be able just to go ahead and
+use them, for threads by Configure \-Dusethreads, and for 64 bits
+either explicitly by Configure \-Duse64bitint or implicitly if your
+system has 64\-bit wide datatypes.  See also "64\-bit support".
+.SS "Long Doubles"
+.IX Subsection "Long Doubles"
+Some platforms have "long doubles", floating point numbers of even
+larger range than ordinary "doubles".  To enable using long doubles for
+Perl's scalars, use \-Duselongdouble.
+.SS \-Dusemorebits
+.IX Subsection "-Dusemorebits"
+You can enable both \-Duse64bitint and \-Duselongdouble with \-Dusemorebits.
+See also "64\-bit support".
+.SS \-Duselargefiles
+.IX Subsection "-Duselargefiles"
+Some platforms support system APIs that are capable of handling large files
+(typically, files larger than two gigabytes).  Perl will try to use these
+APIs if you ask for \-Duselargefiles.
+.PP
+See "Large file support" for more information.
+.SS installusrbinperl
+.IX Subsection "installusrbinperl"
+You can use "Configure \-Uinstallusrbinperl" which causes installperl
+to skip installing perl also as /usr/bin/perl.  This is useful if you
+prefer not to modify /usr/bin for some reason or another but harmful
+because many scripts assume to find Perl in /usr/bin/perl.
+.SS "SOCKS support"
+.IX Subsection "SOCKS support"
+You can use "Configure \-Dusesocks" which causes Perl to probe
+for the SOCKS proxy protocol library (v5, not v4).  For more information
+on SOCKS, see:
+.PP
+.Vb 1
+\&    http://www.socks.nec.com/
+.Ve
+.ie n .SS """\-A"" flag"
+.el .SS "\f(CW\-A\fP flag"
+.IX Subsection "-A flag"
+You can "post-edit" the Configure variables using the Configure \f(CW\*(C`\-A\*(C'\fR
+switch.  The editing happens immediately after the platform specific
+hints files have been processed but before the actual configuration
+process starts.  Run \f(CW\*(C`Configure \-h\*(C'\fR to find out the full \f(CW\*(C`\-A\*(C'\fR syntax.
+.SS "Enhanced Installation Directories"
+.IX Subsection "Enhanced Installation Directories"
+The installation structure has been enriched to improve the support
+for maintaining multiple versions of perl, to provide locations for
+vendor-supplied modules, scripts, and manpages, and to ease maintenance
+of locally-added modules, scripts, and manpages.  See the section on
+Installation Directories in the INSTALL file for complete details.
+For most users building and installing from source, the defaults should
+be fine.
+.PP
+If you previously used \f(CW\*(C`Configure \-Dsitelib\*(C'\fR or \f(CW\*(C`\-Dsitearch\*(C'\fR to set
+special values for library directories, you might wish to consider using
+the new \f(CW\*(C`\-Dsiteprefix\*(C'\fR setting instead.  Also, if you wish to re-use a
+config.sh file from an earlier version of perl, you should be sure to
+check that Configure makes sensible choices for the new directories.
+See INSTALL for complete details.
+.SS "gcc automatically tried if 'cc' does not seem to be working"
+.IX Subsection "gcc automatically tried if 'cc' does not seem to be working"
+In many platforms the vendor-supplied 'cc' is too stripped-down to
+build Perl (basically, the 'cc' doesn't do ANSI C).  If this seems
+to be the case and the 'cc' does not seem to be the GNU C compiler
+\&'gcc', an automatic attempt is made to find and use 'gcc' instead.
+.SH "Platform specific changes"
+.IX Header "Platform specific changes"
+.SS "Supported platforms"
+.IX Subsection "Supported platforms"
+.IP \(bu 4
+The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread
+extension.
+.IP \(bu 4
+GNU/Hurd is now supported.
+.IP \(bu 4
+Rhapsody/Darwin is now supported.
+.IP \(bu 4
+EPOC is now supported (on Psion 5).
+.IP \(bu 4
+The cygwin port (formerly cygwin32) has been greatly improved.
+.SS DOS
+.IX Subsection "DOS"
+.IP \(bu 4
+Perl now works with djgpp 2.02 (and 2.03 alpha).
+.IP \(bu 4
+Environment variable names are not converted to uppercase any more.
+.IP \(bu 4
+Incorrect exit codes from backticks have been fixed.
+.IP \(bu 4
+This port continues to use its own builtin globbing (not File::Glob).
+.SS "OS390 (OpenEdition MVS)"
+.IX Subsection "OS390 (OpenEdition MVS)"
+Support for this EBCDIC platform has not been renewed in this release.
+There are difficulties in reconciling Perl's standardization on UTF\-8
+as its internal representation for characters with the EBCDIC character
+set, because the two are incompatible.
+.PP
+It is unclear whether future versions will renew support for this
+platform, but the possibility exists.
+.SS VMS
+.IX Subsection "VMS"
+Numerous revisions and extensions to configuration, build, testing, and
+installation process to accommodate core changes and VMS-specific options.
+.PP
+Expand \f(CW%ENV\fR\-handling code to allow runtime mapping to logical names,
+CLI symbols, and CRTL environ array.
+.PP
+Extension of subprocess invocation code to accept filespecs as command
+"verbs".
+.PP
+Add to Perl command line processing the ability to use default file types and
+to recognize Unix-style \f(CW\*(C`2>&1\*(C'\fR.
+.PP
+Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.
+.PP
+Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.
+.PP
+Barewords at start of Unix-syntax paths may be treated as text rather than
+only as logical names.
+.PP
+Optional secure translation of several logical names used internally by Perl.
+.PP
+Miscellaneous bugfixing and porting of new core code to VMS.
+.PP
+Thanks are gladly extended to the many people who have contributed VMS
+patches, testing, and ideas.
+.SS Win32
+.IX Subsection "Win32"
+Perl can now emulate \fBfork()\fR internally, using multiple interpreters running
+in different concurrent threads.  This support must be enabled at build
+time.  See perlfork for detailed information.
+.PP
+When given a pathname that consists only of a drivename, such as \f(CW\*(C`A:\*(C'\fR,
+\&\fBopendir()\fR and \fBstat()\fR now use the current working directory for the drive
+rather than the drive root.
+.PP
+The builtin XSUB functions in the Win32:: namespace are documented.  See
+Win32.
+.PP
+$^X now contains the full path name of the running executable.
+.PP
+A \fBWin32::GetLongPathName()\fR function is provided to complement
+\&\fBWin32::GetFullPathName()\fR and \fBWin32::GetShortPathName()\fR.  See Win32.
+.PP
+\&\fBPOSIX::uname()\fR is supported.
+.PP
+system(1,...) now returns true process IDs rather than process
+handles.  \fBkill()\fR accepts any real process id, rather than strictly
+return values from system(1,...).
+.PP
+For better compatibility with Unix, \f(CW\*(C`kill(0, $pid)\*(C'\fR can now be used to
+test whether a process exists.
+.PP
+The \f(CW\*(C`Shell\*(C'\fR module is supported.
+.PP
+Better support for building Perl under command.com in Windows 95
+has been added.
+.PP
+Scripts are read in binary mode by default to allow ByteLoader (and
+the filter mechanism in general) to work properly.  For compatibility,
+the DATA filehandle will be set to text mode if a carriage return is
+detected at the end of the line containing the _\|_END_\|_ or _\|_DATA_\|_
+token; if not, the DATA filehandle will be left open in binary mode.
+Earlier versions always opened the DATA filehandle in text mode.
+.PP
+The \fBglob()\fR operator is implemented via the \f(CW\*(C`File::Glob\*(C'\fR extension,
+which supports glob syntax of the C shell.  This increases the flexibility
+of the \fBglob()\fR operator, but there may be compatibility issues for
+programs that relied on the older globbing syntax.  If you want to
+preserve compatibility with the older syntax, you might want to run
+perl with \f(CW\*(C`\-MFile::DosGlob\*(C'\fR.  For details and compatibility information,
+see File::Glob.
+.SH "Significant bug fixes"
+.IX Header "Significant bug fixes"
+.SS "<HANDLE> on empty files"
+.IX Subsection "<HANDLE> on empty files"
+With \f(CW$/\fR set to \f(CW\*(C`undef\*(C'\fR, "slurping" an empty file returns a string of
+zero length (instead of \f(CW\*(C`undef\*(C'\fR, as it used to) the first time the
+HANDLE is read after \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR.  Further reads yield
+\&\f(CW\*(C`undef\*(C'\fR.
+.PP
+This means that the following will append "foo" to an empty file (it used
+to do nothing):
+.PP
+.Vb 1
+\&    perl \-0777 \-pi \-e \*(Aqs/^/foo/\*(Aq empty_file
+.Ve
+.PP
+The behaviour of:
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqs/^/foo/\*(Aq empty_file
+.Ve
+.PP
+is unchanged (it continues to leave the file empty).
+.ie n .SS """eval \*(Aq...\*(Aq"" improvements"
+.el .SS "\f(CWeval \*(Aq...\*(Aq\fP improvements"
+.IX Subsection "eval ... improvements"
+Line numbers (as reflected by \fBcaller()\fR and most diagnostics) within
+\&\f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR were often incorrect where here documents were involved.
+This has been corrected.
+.PP
+Lexical lookups for variables appearing in \f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR within
+functions that were themselves called within an \f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR were
+searching the wrong place for lexicals.  The lexical search now
+correctly ends at the subroutine's block boundary.
+.PP
+The use of \f(CW\*(C`return\*(C'\fR within \f(CW\*(C`eval {...}\*(C'\fR caused $@ not to be reset
+correctly when no exception occurred within the eval.  This has
+been fixed.
+.PP
+Parsing of here documents used to be flawed when they appeared as
+the replacement expression in \f(CW\*(C`eval \*(Aqs/.../.../e\*(Aq\*(C'\fR.  This has
+been fixed.
+.SS "All compilation errors are true errors"
+.IX Subsection "All compilation errors are true errors"
+Some "errors" encountered at compile time were by necessity 
+generated as warnings followed by eventual termination of the
+program.  This enabled more such errors to be reported in a
+single run, rather than causing a hard stop at the first error
+that was encountered.
+.PP
+The mechanism for reporting such errors has been reimplemented
+to queue compile-time errors and report them at the end of the
+compilation as true errors rather than as warnings.  This fixes
+cases where error messages leaked through in the form of warnings
+when code was compiled at run time using \f(CW\*(C`eval STRING\*(C'\fR, and
+also allows such errors to be reliably trapped using \f(CW\*(C`eval "..."\*(C'\fR.
+.SS "Implicitly closed filehandles are safer"
+.IX Subsection "Implicitly closed filehandles are safer"
+Sometimes implicitly closed filehandles (as when they are localized,
+and Perl automatically closes them on exiting the scope) could
+inadvertently set $? or $!.  This has been corrected.
+.SS "Behavior of list slices is more consistent"
+.IX Subsection "Behavior of list slices is more consistent"
+When taking a slice of a literal list (as opposed to a slice of
+an array or hash), Perl used to return an empty list if the
+result happened to be composed of all undef values.
+.PP
+The new behavior is to produce an empty list if (and only if)
+the original list was empty.  Consider the following example:
+.PP
+.Vb 1
+\&    @a = (1,undef,undef,2)[2,1,2];
+.Ve
+.PP
+The old behavior would have resulted in \f(CW@a\fR having no elements.
+The new behavior ensures it has three undefined elements.
+.PP
+Note in particular that the behavior of slices of the following
+cases remains unchanged:
+.PP
+.Vb 5
+\&    @a = ()[1,2];
+\&    @a = (getpwent)[7,0];
+\&    @a = (anything_returning_empty_list())[2,1,2];
+\&    @a = @b[2,1,2];
+\&    @a = @c{\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq};
+.Ve
+.PP
+See perldata.
+.ie n .SS """(\e$)"" prototype and $foo{a}"
+.el .SS "\f(CW(\e$)\fP prototype and \f(CW$foo{a}\fP"
+.IX Subsection "($) prototype and $foo{a}"
+A scalar reference prototype now correctly allows a hash or
+array element in that slot.
+.ie n .SS """goto &sub"" and AUTOLOAD"
+.el .SS "\f(CWgoto &sub\fP and AUTOLOAD"
+.IX Subsection "goto &sub and AUTOLOAD"
+The \f(CW\*(C`goto &sub\*(C'\fR construct works correctly when \f(CW&sub\fR happens
+to be autoloaded.
+.ie n .SS """\-bareword"" allowed under ""use integer"""
+.el .SS "\f(CW\-bareword\fP allowed under \f(CWuse integer\fP"
+.IX Subsection "-bareword allowed under use integer"
+The autoquoting of barewords preceded by \f(CW\*(C`\-\*(C'\fR did not work
+in prior versions when the \f(CW\*(C`integer\*(C'\fR pragma was enabled.
+This has been fixed.
+.SS "Failures in \fBDESTROY()\fP"
+.IX Subsection "Failures in DESTROY()"
+When code in a destructor threw an exception, it went unnoticed
+in earlier versions of Perl, unless someone happened to be
+looking in $@ just after the point the destructor happened to
+run.  Such failures are now visible as warnings when warnings are
+enabled.
+.SS "Locale bugs fixed"
+.IX Subsection "Locale bugs fixed"
+\&\fBprintf()\fR and \fBsprintf()\fR previously reset the numeric locale
+back to the default "C" locale.  This has been fixed.
+.PP
+Numbers formatted according to the local numeric locale
+(such as using a decimal comma instead of a decimal dot) caused
+"isn't numeric" warnings, even while the operations accessing
+those numbers produced correct results.  These warnings have been
+discontinued.
+.SS "Memory leaks"
+.IX Subsection "Memory leaks"
+The \f(CW\*(C`eval \*(Aqreturn sub {...}\*(Aq\*(C'\fR construct could sometimes leak
+memory.  This has been fixed.
+.PP
+Operations that aren't filehandle constructors used to leak memory
+when used on invalid filehandles.  This has been fixed.
+.PP
+Constructs that modified \f(CW@_\fR could fail to deallocate values
+in \f(CW@_\fR and thus leak memory.  This has been corrected.
+.SS "Spurious subroutine stubs after failed subroutine calls"
+.IX Subsection "Spurious subroutine stubs after failed subroutine calls"
+Perl could sometimes create empty subroutine stubs when a
+subroutine was not found in the package.  Such cases stopped
+later method lookups from progressing into base packages.
+This has been corrected.
+.ie n .SS "Taint failures under ""\-U"""
+.el .SS "Taint failures under \f(CW\-U\fP"
+.IX Subsection "Taint failures under -U"
+When running in unsafe mode, taint violations could sometimes
+cause silent failures.  This has been fixed.
+.ie n .SS "END blocks and the ""\-c"" switch"
+.el .SS "END blocks and the \f(CW\-c\fP switch"
+.IX Subsection "END blocks and the -c switch"
+Prior versions used to run BEGIN \fBand\fR END blocks when Perl was
+run in compile-only mode.  Since this is typically not the expected
+behavior, END blocks are not executed anymore when the \f(CW\*(C`\-c\*(C'\fR switch
+is used, or if compilation fails.
+.PP
+See "Support for CHECK blocks" for how to run things when the compile 
+phase ends.
+.SS "Potential to leak DATA filehandles"
+.IX Subsection "Potential to leak DATA filehandles"
+Using the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR token creates an implicit filehandle to
+the file that contains the token.  It is the program's
+responsibility to close it when it is done reading from it.
+.PP
+This caveat is now better explained in the documentation.
+See perldata.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.ie n .IP """%s"" variable %s masks earlier declaration in same %s" 4
+.el .IP """%s"" variable \f(CW%s\fR masks earlier declaration in same \f(CW%s\fR" 4
+.IX Item """%s"" variable %s masks earlier declaration in same %s"
+(W misc) A "my" or "our" variable has been redeclared in the current scope or statement,
+effectively eliminating all access to the previous instance.  This is almost
+always a typographical error.  Note that the earlier variable will still exist
+until the end of the scope or until all closure referents to it are
+destroyed.
+.IP """my sub"" not yet implemented" 4
+.IX Item """my sub"" not yet implemented"
+(F) Lexically scoped subroutines are not yet implemented.  Don't try that
+yet.
+.ie n .IP """our"" variable %s redeclared" 4
+.el .IP """our"" variable \f(CW%s\fR redeclared" 4
+.IX Item """our"" variable %s redeclared"
+(W misc) You seem to have already declared the same global once before in the
+current lexical scope.
+.ie n .IP "'!' allowed only after types %s" 4
+.el .IP "'!' allowed only after types \f(CW%s\fR" 4
+.IX Item "'!' allowed only after types %s"
+(F) The '!' is allowed in \fBpack()\fR and \fBunpack()\fR only after certain types.
+See "pack" in perlfunc.
+.IP "/ cannot take a count" 4
+.IX Item "/ cannot take a count"
+(F) You had an unpack template indicating a counted-length string,
+but you have also specified an explicit size for the string.
+See "pack" in perlfunc.
+.IP "/ must be followed by a, A or Z" 4
+.IX Item "/ must be followed by a, A or Z"
+(F) You had an unpack template indicating a counted-length string,
+which must be followed by one of the letters a, A or Z
+to indicate what sort of string is to be unpacked.
+See "pack" in perlfunc.
+.IP "/ must be followed by a*, A* or Z*" 4
+.IX Item "/ must be followed by a*, A* or Z*"
+(F) You had a pack template indicating a counted-length string,
+Currently the only things that can have their length counted are a*, A* or Z*.
+See "pack" in perlfunc.
+.IP "/ must follow a numeric type" 4
+.IX Item "/ must follow a numeric type"
+(F) You had an unpack template that contained a '#',
+but this did not follow some numeric unpack specification.
+See "pack" in perlfunc.
+.IP "/%s/: Unrecognized escape \e\e%c passed through" 4
+.IX Item "/%s/: Unrecognized escape %c passed through"
+(W regexp) You used a backslash-character combination which is not recognized
+by Perl.  This combination appears in an interpolated variable or a
+\&\f(CW\*(C`\*(Aq\*(C'\fR\-delimited regular expression.  The character was understood literally.
+.IP "/%s/: Unrecognized escape \e\e%c in character class passed through" 4
+.IX Item "/%s/: Unrecognized escape %c in character class passed through"
+(W regexp) You used a backslash-character combination which is not recognized
+by Perl inside character classes.  The character was understood literally.
+.IP "/%s/ should probably be written as ""%s""" 4
+.IX Item "/%s/ should probably be written as ""%s"""
+(W syntax) You have used a pattern where Perl expected to find a string,
+as in the first argument to \f(CW\*(C`join\*(C'\fR.  Perl will treat the true
+or false result of matching the pattern against \f(CW$_\fR as the string,
+which is probably not what you had in mind.
+.IP "%s() called too early to check prototype" 4
+.IX Item "%s() called too early to check prototype"
+(W prototype) You've called a function that has a prototype before the parser saw a
+definition or declaration for it, and Perl could not check that the call
+conforms to the prototype.  You need to either add an early prototype
+declaration for the subroutine in question, or move the subroutine
+definition ahead of the call to get proper prototype checking.  Alternatively,
+if you are certain that you're calling the function correctly, you may put
+an ampersand before the name to avoid the warning.  See perlsub.
+.ie n .IP "%s argument is not a HASH or ARRAY element" 4
+.el .IP "\f(CW%s\fR argument is not a HASH or ARRAY element" 4
+.IX Item "%s argument is not a HASH or ARRAY element"
+(F) The argument to \fBexists()\fR must be a hash or array element, such as:
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+.Ve
+.ie n .IP "%s argument is not a HASH or ARRAY element or slice" 4
+.el .IP "\f(CW%s\fR argument is not a HASH or ARRAY element or slice" 4
+.IX Item "%s argument is not a HASH or ARRAY element or slice"
+(F) The argument to \fBdelete()\fR must be either a hash or array element, such as:
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+.Ve
+.Sp
+or a hash or array slice, such as:
+.Sp
+.Vb 2
+\&    @foo[$bar, $baz, $xyzzy]
+\&    @{$ref\->[12]}{"susie", "queue"}
+.Ve
+.ie n .IP "%s argument is not a subroutine name" 4
+.el .IP "\f(CW%s\fR argument is not a subroutine name" 4
+.IX Item "%s argument is not a subroutine name"
+(F) The argument to \fBexists()\fR for \f(CW\*(C`exists &sub\*(C'\fR must be a subroutine
+name, and not a subroutine call.  \f(CW\*(C`exists &sub()\*(C'\fR will generate this error.
+.ie n .IP "%s package attribute may clash with future reserved word: %s" 4
+.el .IP "\f(CW%s\fR package attribute may clash with future reserved word: \f(CW%s\fR" 4
+.IX Item "%s package attribute may clash with future reserved word: %s"
+(W reserved) A lowercase attribute name was used that had a package-specific handler.
+That name might have a meaning to Perl itself some day, even though it
+doesn't yet.  Perhaps you should use a mixed-case attribute name, instead.
+See attributes.
+.ie n .IP "(in cleanup) %s" 4
+.el .IP "(in cleanup) \f(CW%s\fR" 4
+.IX Item "(in cleanup) %s"
+(W misc) This prefix usually indicates that a \fBDESTROY()\fR method raised
+the indicated exception.  Since destructors are usually called by
+the system at arbitrary points during execution, and often a vast
+number of times, the warning is issued only once for any number
+of failures that would otherwise result in the same message being
+repeated.
+.Sp
+Failure of user callbacks dispatched using the \f(CW\*(C`G_KEEPERR\*(C'\fR flag
+could also result in this warning.  See "G_KEEPERR" in perlcall.
+.IP "<> should be quotes" 4
+.IX Item "<> should be quotes"
+(F) You wrote \f(CW\*(C`require <file>\*(C'\fR when you should have written
+\&\f(CW\*(C`require \*(Aqfile\*(Aq\*(C'\fR.
+.IP "Attempt to join self" 4
+.IX Item "Attempt to join self"
+(F) You tried to join a thread from within itself, which is an
+impossible task.  You may be joining the wrong thread, or you may
+need to move the \fBjoin()\fR to some other thread.
+.IP "Bad evalled substitution pattern" 4
+.IX Item "Bad evalled substitution pattern"
+(F) You've used the /e switch to evaluate the replacement for a
+substitution, but perl found a syntax error in the code to evaluate,
+most likely an unexpected right brace '}'.
+.IP "Bad \fBrealloc()\fR ignored" 4
+.IX Item "Bad realloc() ignored"
+(S) An internal routine called \fBrealloc()\fR on something that had never been
+\&\fBmalloc()\fRed in the first place. Mandatory, but can be disabled by
+setting environment variable \f(CW\*(C`PERL_BADFREE\*(C'\fR to 1.
+.IP "Bareword found in conditional" 4
+.IX Item "Bareword found in conditional"
+(W bareword) The compiler found a bareword where it expected a conditional,
+which often indicates that an || or && was parsed as part of the
+last argument of the previous construct, for example:
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.Sp
+It may also indicate a misspelled constant that has been interpreted
+as a bareword:
+.Sp
+.Vb 2
+\&    use constant TYPO => 1;
+\&    if (TYOP) { print "foo" }
+.Ve
+.Sp
+The \f(CW\*(C`strict\*(C'\fR pragma is useful in avoiding such errors.
+.IP "Binary number > 0b11111111111111111111111111111111 non-portable" 4
+.IX Item "Binary number > 0b11111111111111111111111111111111 non-portable"
+(W portable) The binary number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Bit vector size > 32 non-portable" 4
+.IX Item "Bit vector size > 32 non-portable"
+(W portable) Using bit vector sizes larger than 32 is non-portable.
+.ie n .IP "Buffer overflow in prime_env_iter: %s" 4
+.el .IP "Buffer overflow in prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Buffer overflow in prime_env_iter: %s"
+(W internal) A warning peculiar to VMS.  While Perl was preparing to iterate over
+\&\f(CW%ENV\fR, it encountered a logical name or symbol definition which was too long,
+so it was truncated to the string shown.
+.IP "Can't check filesystem of script ""%s""" 4
+.IX Item "Can't check filesystem of script ""%s"""
+(P) For some reason you can't check the filesystem of the script for nosuid.
+.ie n .IP "Can't declare class for non-scalar %s in ""%s""" 4
+.el .IP "Can't declare class for non-scalar \f(CW%s\fR in ""%s""" 4
+.IX Item "Can't declare class for non-scalar %s in ""%s"""
+(S) Currently, only scalar variables can declared with a specific class
+qualifier in a "my" or "our" declaration.  The semantics may be extended
+for other types of variables in future.
+.ie n .IP "Can't declare %s in ""%s""" 4
+.el .IP "Can't declare \f(CW%s\fR in ""%s""" 4
+.IX Item "Can't declare %s in ""%s"""
+(F) Only scalar, array, and hash variables may be declared as "my" or
+"our" variables.  They must have ordinary identifiers as names.
+.IP "Can't ignore signal CHLD, forcing to default" 4
+.IX Item "Can't ignore signal CHLD, forcing to default"
+(W signal) Perl has detected that it is being run with the SIGCHLD signal
+(sometimes known as SIGCLD) disabled.  Since disabling this signal
+will interfere with proper determination of exit status of child
+processes, Perl has reset the signal to its default value.
+This situation typically indicates that the parent program under
+which Perl may be running (e.g., cron) is being very careless.
+.IP "Can't modify non-lvalue subroutine call" 4
+.IX Item "Can't modify non-lvalue subroutine call"
+(F) Subroutines meant to be used in lvalue context should be declared as
+such, see "Lvalue subroutines" in perlsub.
+.IP "Can't read CRTL environ" 4
+.IX Item "Can't read CRTL environ"
+(S) A warning peculiar to VMS.  Perl tried to read an element of \f(CW%ENV\fR
+from the CRTL's internal environment array and discovered the array was
+missing.  You need to figure out where your CRTL misplaced its environ
+or define \fIPERL_ENV_TABLES\fR (see perlvms) so that environ is not searched.
+.ie n .IP "Can't remove %s: %s, skipping file" 4
+.el .IP "Can't remove \f(CW%s:\fR \f(CW%s\fR, skipping file" 4
+.IX Item "Can't remove %s: %s, skipping file"
+(S) You requested an inplace edit without creating a backup file.  Perl
+was unable to remove the original file to replace it with the modified
+file.  The file was left unmodified.
+.ie n .IP "Can't return %s from lvalue subroutine" 4
+.el .IP "Can't return \f(CW%s\fR from lvalue subroutine" 4
+.IX Item "Can't return %s from lvalue subroutine"
+(F) Perl detected an attempt to return illegal lvalues (such
+as temporary or readonly values) from a subroutine used as an lvalue.
+This is not allowed.
+.IP "Can't weaken a nonreference" 4
+.IX Item "Can't weaken a nonreference"
+(F) You attempted to weaken something that was not a reference.  Only
+references can be weakened.
+.IP "Character class [:%s:] unknown" 4
+.IX Item "Character class [:%s:] unknown"
+(F) The class in the character class [: :] syntax is unknown.
+See perlre.
+.IP "Character class syntax [%s] belongs inside character classes" 4
+.IX Item "Character class syntax [%s] belongs inside character classes"
+(W unsafe) The character class constructs [: :], [= =], and [. .]  go
+\&\fIinside\fR character classes, the [] are part of the construct,
+for example: /[012[:alpha:]345]/.  Note that [= =] and [. .]
+are not currently implemented; they are simply placeholders for
+future extensions.
+.ie n .IP "Constant is not %s reference" 4
+.el .IP "Constant is not \f(CW%s\fR reference" 4
+.IX Item "Constant is not %s reference"
+(F) A constant value (perhaps declared using the \f(CW\*(C`use constant\*(C'\fR pragma)
+is being dereferenced, but it amounts to the wrong type of reference.  The
+message indicates the type of reference that was expected. This usually
+indicates a syntax error in dereferencing the constant value.
+See "Constant Functions" in perlsub and constant.
+.ie n .IP "constant(%s): %s" 4
+.el .IP "constant(%s): \f(CW%s\fR" 4
+.IX Item "constant(%s): %s"
+(F) The parser found inconsistencies either while attempting to define an
+overloaded constant, or when trying to find the character name specified
+in the \f(CW\*(C`\eN{...}\*(C'\fR escape.  Perhaps you forgot to load the corresponding
+\&\f(CW\*(C`overload\*(C'\fR or \f(CW\*(C`charnames\*(C'\fR pragma?  See charnames and overload.
+.IP "CORE::%s is not a keyword" 4
+.IX Item "CORE::%s is not a keyword"
+(F) The CORE:: namespace is reserved for Perl keywords.
+.IP "defined(@array) is deprecated" 4
+.IX Item "defined(@array) is deprecated"
+(D) \fBdefined()\fR is not usually useful on arrays because it checks for an
+undefined \fIscalar\fR value.  If you want to see if the array is empty,
+just use \f(CW\*(C`if (@array) { # not empty }\*(C'\fR for example.
+.IP "defined(%hash) is deprecated" 4
+.IX Item "defined(%hash) is deprecated"
+(D) \fBdefined()\fR is not usually useful on hashes because it checks for an
+undefined \fIscalar\fR value.  If you want to see if the hash is empty,
+just use \f(CW\*(C`if (%hash) { # not empty }\*(C'\fR for example.
+.IP "Did not produce a valid header" 4
+.IX Item "Did not produce a valid header"
+See Server error.
+.IP "(Did you mean ""local"" instead of ""our""?)" 4
+.IX Item "(Did you mean ""local"" instead of ""our""?)"
+(W misc) Remember that "our" does not localize the declared global variable.
+You have declared it again in the same lexical scope, which seems superfluous.
+.IP "Document contains no data" 4
+.IX Item "Document contains no data"
+See Server error.
+.ie n .IP "entering effective %s failed" 4
+.el .IP "entering effective \f(CW%s\fR failed" 4
+.IX Item "entering effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.IP "false [] range ""%s"" in regexp" 4
+.IX Item "false [] range ""%s"" in regexp"
+(W regexp) A character class range must start and end at a literal character, not
+another character class like \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`[:alpha:]\*(C'\fR.  The "\-" in your false
+range is interpreted as a literal "\-".  Consider quoting the "\-",  "\e\-".
+See perlre.
+.ie n .IP "Filehandle %s opened only for output" 4
+.el .IP "Filehandle \f(CW%s\fR opened only for output" 4
+.IX Item "Filehandle %s opened only for output"
+(W io) You tried to read from a filehandle opened only for writing.  If you
+intended it to be a read/write filehandle, you needed to open it with
+"+<" or "+>" or "+>>" instead of with "<" or nothing.  If
+you intended only to read from the file, use "<".  See
+"open" in perlfunc.
+.ie n .IP "\fBflock()\fR on closed filehandle %s" 4
+.el .IP "\fBflock()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "flock() on closed filehandle %s"
+(W closed) The filehandle you're attempting to \fBflock()\fR got itself closed some
+time before now.  Check your logic flow.  \fBflock()\fR operates on filehandles.
+Are you attempting to call \fBflock()\fR on a dirhandle by the same name?
+.IP "Global symbol ""%s"" requires explicit package name" 4
+.IX Item "Global symbol ""%s"" requires explicit package name"
+(F) You've said "use strict vars", which indicates that all variables
+must either be lexically scoped (using "my"), declared beforehand using
+"our", or explicitly qualified to say which package the global variable
+is in (using "::").
+.IP "Hexadecimal number > 0xffffffff non-portable" 4
+.IX Item "Hexadecimal number > 0xffffffff non-portable"
+(W portable) The hexadecimal number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Ill-formed CRTL environ value ""%s""" 4
+.IX Item "Ill-formed CRTL environ value ""%s"""
+(W internal) A warning peculiar to VMS.  Perl tried to read the CRTL's internal
+environ array, and encountered an element without the \f(CW\*(C`=\*(C'\fR delimiter
+used to separate keys from values.  The element is ignored.
+.IP "Ill-formed message in prime_env_iter: |%s|" 4
+.IX Item "Ill-formed message in prime_env_iter: |%s|"
+(W internal) A warning peculiar to VMS.  Perl tried to read a logical name
+or CLI symbol definition when preparing to iterate over \f(CW%ENV\fR, and
+didn't see the expected delimiter between key and value, so the
+line was ignored.
+.ie n .IP "Illegal binary digit %s" 4
+.el .IP "Illegal binary digit \f(CW%s\fR" 4
+.IX Item "Illegal binary digit %s"
+(F) You used a digit other than 0 or 1 in a binary number.
+.ie n .IP "Illegal binary digit %s ignored" 4
+.el .IP "Illegal binary digit \f(CW%s\fR ignored" 4
+.IX Item "Illegal binary digit %s ignored"
+(W digit) You may have tried to use a digit other than 0 or 1 in a binary number.
+Interpretation of the binary number stopped before the offending digit.
+.IP "Illegal number of bits in vec" 4
+.IX Item "Illegal number of bits in vec"
+(F) The number of bits in \fBvec()\fR (the third argument) must be a power of
+two from 1 to 32 (or 64, if your platform supports that).
+.ie n .IP "Integer overflow in %s number" 4
+.el .IP "Integer overflow in \f(CW%s\fR number" 4
+.IX Item "Integer overflow in %s number"
+(W overflow) The hexadecimal, octal or binary number you have specified either
+as a literal or as an argument to \fBhex()\fR or \fBoct()\fR is too big for your
+architecture, and has been converted to a floating point number.  On a
+32\-bit architecture the largest hexadecimal, octal or binary number
+representable without overflow is 0xFFFFFFFF, 037777777777, or
+0b11111111111111111111111111111111 respectively.  Note that Perl
+transparently promotes all numbers to a floating point representation
+internally\-\-subject to loss of precision errors in subsequent
+operations.
+.ie n .IP "Invalid %s attribute: %s" 4
+.el .IP "Invalid \f(CW%s\fR attribute: \f(CW%s\fR" 4
+.IX Item "Invalid %s attribute: %s"
+The indicated attribute for a subroutine or variable was not recognized
+by Perl or by a user-supplied handler.  See attributes.
+.ie n .IP "Invalid %s attributes: %s" 4
+.el .IP "Invalid \f(CW%s\fR attributes: \f(CW%s\fR" 4
+.IX Item "Invalid %s attributes: %s"
+The indicated attributes for a subroutine or variable were not recognized
+by Perl or by a user-supplied handler.  See attributes.
+.IP "invalid [] range ""%s"" in regexp" 4
+.IX Item "invalid [] range ""%s"" in regexp"
+The offending range is now explicitly displayed.
+.ie n .IP "Invalid separator character %s in attribute list" 4
+.el .IP "Invalid separator character \f(CW%s\fR in attribute list" 4
+.IX Item "Invalid separator character %s in attribute list"
+(F) Something other than a colon or whitespace was seen between the
+elements of an attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.  See attributes.
+.ie n .IP "Invalid separator character %s in subroutine attribute list" 4
+.el .IP "Invalid separator character \f(CW%s\fR in subroutine attribute list" 4
+.IX Item "Invalid separator character %s in subroutine attribute list"
+(F) Something other than a colon or whitespace was seen between the
+elements of a subroutine attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.
+.ie n .IP "leaving effective %s failed" 4
+.el .IP "leaving effective \f(CW%s\fR failed" 4
+.IX Item "leaving effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.ie n .IP "Lvalue subs returning %s not implemented yet" 4
+.el .IP "Lvalue subs returning \f(CW%s\fR not implemented yet" 4
+.IX Item "Lvalue subs returning %s not implemented yet"
+(F) Due to limitations in the current implementation, array and hash
+values cannot be returned in subroutines used in lvalue context.
+See "Lvalue subroutines" in perlsub.
+.ie n .IP "Method %s not permitted" 4
+.el .IP "Method \f(CW%s\fR not permitted" 4
+.IX Item "Method %s not permitted"
+See Server error.
+.ie n .IP "Missing %sbrace%s on \eN{}" 4
+.el .IP "Missing \f(CW%sbrace\fR%s on \eN{}" 4
+.IX Item "Missing %sbrace%s on N{}"
+(F) Wrong syntax of character name literal \f(CW\*(C`\eN{charname}\*(C'\fR within
+double-quotish context.
+.IP "Missing command in piped open" 4
+.IX Item "Missing command in piped open"
+(W pipe) You used the \f(CW\*(C`open(FH, "| command")\*(C'\fR or \f(CW\*(C`open(FH, "command |")\*(C'\fR
+construction, but the command was missing or blank.
+.IP "Missing name in ""my sub""" 4
+.IX Item "Missing name in ""my sub"""
+(F) The reserved syntax for lexically scoped subroutines requires that they
+have a name with which they can be found.
+.ie n .IP "No %s specified for \-%c" 4
+.el .IP "No \f(CW%s\fR specified for \-%c" 4
+.IX Item "No %s specified for -%c"
+(F) The indicated command line switch needs a mandatory argument, but
+you haven't specified one.
+.ie n .IP "No package name allowed for variable %s in ""our""" 4
+.el .IP "No package name allowed for variable \f(CW%s\fR in ""our""" 4
+.IX Item "No package name allowed for variable %s in ""our"""
+(F) Fully qualified variable names are not allowed in "our" declarations,
+because that doesn't make much sense under existing semantics.  Such
+syntax is reserved for future extensions.
+.IP "No space allowed after \-%c" 4
+.IX Item "No space allowed after -%c"
+(F) The argument to the indicated command line switch must follow immediately
+after the switch, without intervening spaces.
+.IP "no UTC offset information; assuming local time is UTC" 4
+.IX Item "no UTC offset information; assuming local time is UTC"
+(S) A warning peculiar to VMS.  Perl was unable to find the local
+timezone offset, so it's assuming that local system time is equivalent
+to UTC.  If it's not, define the logical name \fISYS$TIMEZONE_DIFFERENTIAL\fR
+to translate to the number of seconds which need to be added to UTC to
+get local time.
+.IP "Octal number > 037777777777 non-portable" 4
+.IX Item "Octal number > 037777777777 non-portable"
+(W portable) The octal number you specified is larger than 2**32\-1 (4294967295)
+and therefore non-portable between systems.  See perlport for more
+on portability concerns.
+.Sp
+See also perlport for writing portable code.
+.IP "panic: del_backref" 4
+.IX Item "panic: del_backref"
+(P) Failed an internal consistency check while trying to reset a weak
+reference.
+.IP "panic: kid popen errno read" 4
+.IX Item "panic: kid popen errno read"
+(F) forked child returned an incomprehensible message about its errno.
+.IP "panic: magic_killbackrefs" 4
+.IX Item "panic: magic_killbackrefs"
+(P) Failed an internal consistency check while trying to reset all weak
+references to an object.
+.IP "Parentheses missing around ""%s"" list" 4
+.IX Item "Parentheses missing around ""%s"" list"
+(W parenthesis) You said something like
+.Sp
+.Vb 1
+\&    my $foo, $bar = @_;
+.Ve
+.Sp
+when you meant
+.Sp
+.Vb 1
+\&    my ($foo, $bar) = @_;
+.Ve
+.Sp
+Remember that "my", "our", and "local" bind tighter than comma.
+.ie n .IP "Possible unintended interpolation of %s in string" 4
+.el .IP "Possible unintended interpolation of \f(CW%s\fR in string" 4
+.IX Item "Possible unintended interpolation of %s in string"
+(W ambiguous) It used to be that Perl would try to guess whether you
+wanted an array interpolated or a literal @.  It no longer does this;
+arrays are now \fIalways\fR interpolated into strings.  This means that 
+if you try something like:
+.Sp
+.Vb 1
+\&        print "fred@example.com";
+.Ve
+.Sp
+and the array \f(CW@example\fR doesn't exist, Perl is going to print
+\&\f(CW\*(C`fred.com\*(C'\fR, which is probably not what you wanted.  To get a literal
+\&\f(CW\*(C`@\*(C'\fR sign in a string, put a backslash before it, just as you would
+to get a literal \f(CW\*(C`$\*(C'\fR sign.
+.ie n .IP "Possible Y2K bug: %s" 4
+.el .IP "Possible Y2K bug: \f(CW%s\fR" 4
+.IX Item "Possible Y2K bug: %s"
+(W y2k) You are concatenating the number 19 with another number, which
+could be a potential Year 2000 problem.
+.IP "pragma ""attrs"" is deprecated, use ""sub NAME : ATTRS"" instead" 4
+.IX Item "pragma ""attrs"" is deprecated, use ""sub NAME : ATTRS"" instead"
+(W deprecated) You have written something like this:
+.Sp
+.Vb 4
+\&    sub doit
+\&    {
+\&        use attrs qw(locked);
+\&    }
+.Ve
+.Sp
+You should use the new declaration syntax instead.
+.Sp
+.Vb 3
+\&    sub doit : locked
+\&    {
+\&        ...
+.Ve
+.Sp
+The \f(CW\*(C`use attrs\*(C'\fR pragma is now obsolete, and is only provided for
+backward-compatibility. See "Subroutine Attributes" in perlsub.
+.IP "Premature end of script headers" 4
+.IX Item "Premature end of script headers"
+See Server error.
+.IP "Repeat count in pack overflows" 4
+.IX Item "Repeat count in pack overflows"
+(F) You can't specify a repeat count so large that it overflows
+your signed integers.  See "pack" in perlfunc.
+.IP "Repeat count in unpack overflows" 4
+.IX Item "Repeat count in unpack overflows"
+(F) You can't specify a repeat count so large that it overflows
+your signed integers.  See "unpack" in perlfunc.
+.IP "\fBrealloc()\fR of freed memory ignored" 4
+.IX Item "realloc() of freed memory ignored"
+(S) An internal routine called \fBrealloc()\fR on something that had already
+been freed.
+.IP "Reference is already weak" 4
+.IX Item "Reference is already weak"
+(W misc) You have attempted to weaken a reference that is already weak.
+Doing so has no effect.
+.IP "setpgrp can't take arguments" 4
+.IX Item "setpgrp can't take arguments"
+(F) Your system has the \fBsetpgrp()\fR from BSD 4.2, which takes no arguments,
+unlike POSIX \fBsetpgid()\fR, which takes a process ID and process group ID.
+.IP "Strange *+?{} on zero-length expression" 4
+.IX Item "Strange *+?{} on zero-length expression"
+(W regexp) You applied a regular expression quantifier in a place where it
+makes no sense, such as on a zero-width assertion.
+Try putting the quantifier inside the assertion instead.  For example,
+the way to match "abc" provided that it is followed by three
+repetitions of "xyz" is \f(CW\*(C`/abc(?=(?:xyz){3})/\*(C'\fR, not \f(CW\*(C`/abc(?=xyz){3}/\*(C'\fR.
+.ie n .IP "switching effective %s is not implemented" 4
+.el .IP "switching effective \f(CW%s\fR is not implemented" 4
+.IX Item "switching effective %s is not implemented"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, we cannot switch the
+real and effective uids or gids.
+.IP "This Perl can't reset CRTL environ elements (%s)" 4
+.IX Item "This Perl can't reset CRTL environ elements (%s)"
+.PD 0
+.IP "This Perl can't set CRTL environ elements (%s=%s)" 4
+.IX Item "This Perl can't set CRTL environ elements (%s=%s)"
+.PD
+(W internal) Warnings peculiar to VMS.  You tried to change or delete an element
+of the CRTL's internal environ array, but your copy of Perl wasn't
+built with a CRTL that contained the \fBsetenv()\fR function.  You'll need to
+rebuild Perl with a CRTL that does, or redefine \fIPERL_ENV_TABLES\fR (see
+perlvms) so that the environ array isn't the target of the change to
+\&\f(CW%ENV\fR which produced the warning.
+.ie n .IP "Too late to run %s block" 4
+.el .IP "Too late to run \f(CW%s\fR block" 4
+.IX Item "Too late to run %s block"
+(W void) A CHECK or INIT block is being defined during run time proper,
+when the opportunity to run them has already passed.  Perhaps you are
+loading a file with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR when you should be using
+\&\f(CW\*(C`use\*(C'\fR instead.  Or perhaps you should put the \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR
+inside a BEGIN block.
+.IP "Unknown \fBopen()\fR mode '%s'" 4
+.IX Item "Unknown open() mode '%s'"
+(F) The second argument of 3\-argument \fBopen()\fR is not among the list
+of valid modes: \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`+<\*(C'\fR,
+\&\f(CW\*(C`+>\*(C'\fR, \f(CW\*(C`+>>\*(C'\fR, \f(CW\*(C`\-|\*(C'\fR, \f(CW\*(C`|\-\*(C'\fR.
+.ie n .IP "Unknown process %x sent message to prime_env_iter: %s" 4
+.el .IP "Unknown process \f(CW%x\fR sent message to prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Unknown process %x sent message to prime_env_iter: %s"
+(P) An error peculiar to VMS.  Perl was reading values for \f(CW%ENV\fR before
+iterating over it, and someone else stuck a message in the stream of
+data Perl expected.  Someone's very confused, or perhaps trying to
+subvert Perl's population of \f(CW%ENV\fR for nefarious purposes.
+.IP "Unrecognized escape \e\e%c passed through" 4
+.IX Item "Unrecognized escape %c passed through"
+(W misc) You used a backslash-character combination which is not recognized
+by Perl.  The character was understood literally.
+.IP "Unterminated attribute parameter in attribute list" 4
+.IX Item "Unterminated attribute parameter in attribute list"
+(F) The lexer saw an opening (left) parenthesis character while parsing an
+attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.  See attributes.
+.IP "Unterminated attribute list" 4
+.IX Item "Unterminated attribute list"
+(F) The lexer found something other than a simple identifier at the start
+of an attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.  See attributes.
+.IP "Unterminated attribute parameter in subroutine attribute list" 4
+.IX Item "Unterminated attribute parameter in subroutine attribute list"
+(F) The lexer saw an opening (left) parenthesis character while parsing a
+subroutine attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.
+.IP "Unterminated subroutine attribute list" 4
+.IX Item "Unterminated subroutine attribute list"
+(F) The lexer found something other than a simple identifier at the start
+of a subroutine attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.
+.IP "Value of CLI symbol ""%s"" too long" 4
+.IX Item "Value of CLI symbol ""%s"" too long"
+(W misc) A warning peculiar to VMS.  Perl tried to read the value of an \f(CW%ENV\fR
+element from a CLI symbol table, and found a resultant string longer
+than 1024 characters.  The return value has been truncated to 1024
+characters.
+.IP "Version number must be a constant number" 4
+.IX Item "Version number must be a constant number"
+(P) The attempt to translate a \f(CW\*(C`use Module n.n LIST\*(C'\fR statement into
+its equivalent \f(CW\*(C`BEGIN\*(C'\fR block found an internal inconsistency with
+the version number.
+.SH "New tests"
+.IX Header "New tests"
+.IP lib/attrs 4
+.IX Item "lib/attrs"
+Compatibility tests for \f(CW\*(C`sub : attrs\*(C'\fR vs the older \f(CW\*(C`use attrs\*(C'\fR.
+.IP lib/env 4
+.IX Item "lib/env"
+Tests for new environment scalar capability (e.g., \f(CW\*(C`use Env qw($BAR);\*(C'\fR).
+.IP lib/env\-array 4
+.IX Item "lib/env-array"
+Tests for new environment array capability (e.g., \f(CW\*(C`use Env qw(@PATH);\*(C'\fR).
+.IP lib/io_const 4
+.IX Item "lib/io_const"
+IO constants (SEEK_*, _IO*).
+.IP lib/io_dir 4
+.IX Item "lib/io_dir"
+Directory-related IO methods (new, read, close, rewind, tied delete).
+.IP lib/io_multihomed 4
+.IX Item "lib/io_multihomed"
+INET sockets with multi-homed hosts.
+.IP lib/io_poll 4
+.IX Item "lib/io_poll"
+IO \fBpoll()\fR.
+.IP lib/io_unix 4
+.IX Item "lib/io_unix"
+UNIX sockets.
+.IP op/attrs 4
+.IX Item "op/attrs"
+Regression tests for \f(CW\*(C`my ($x,@y,%z) : attrs\*(C'\fR and <sub : attrs>.
+.IP op/filetest 4
+.IX Item "op/filetest"
+File test operators.
+.IP op/lex_assign 4
+.IX Item "op/lex_assign"
+Verify operations that access pad objects (lexicals and temporaries).
+.IP op/exists_sub 4
+.IX Item "op/exists_sub"
+Verify \f(CW\*(C`exists &sub\*(C'\fR operations.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Perl Source Incompatibilities"
+.IX Subsection "Perl Source Incompatibilities"
+Beware that any new warnings that have been added or old ones
+that have been enhanced are \fBnot\fR considered incompatible changes.
+.PP
+Since all new warnings must be explicitly requested via the \f(CW\*(C`\-w\*(C'\fR
+switch or the \f(CW\*(C`warnings\*(C'\fR pragma, it is ultimately the programmer's
+responsibility to ensure that warnings are enabled judiciously.
+.IP "CHECK is a new keyword" 4
+.IX Item "CHECK is a new keyword"
+All subroutine definitions named CHECK are now special.  See
+\&\f(CW\*(C`/"Support for CHECK blocks"\*(C'\fR for more information.
+.IP "Treatment of list slices of undef has changed" 4
+.IX Item "Treatment of list slices of undef has changed"
+There is a potential incompatibility in the behavior of list slices
+that are comprised entirely of undefined values.
+See "Behavior of list slices is more consistent".
+.ie n .IP "Format of $English::PERL_VERSION is different" 4
+.el .IP "Format of \f(CW$English::PERL_VERSION\fR is different" 4
+.IX Item "Format of $English::PERL_VERSION is different"
+The English module now sets \f(CW$PERL_VERSION\fR to $^V (a string value) rather
+than \f(CW$]\fR (a numeric value).  This is a potential incompatibility.
+Send us a report via perlbug if you are affected by this.
+.Sp
+See "Improved Perl version numbering system" for the reasons for
+this change.
+.ie n .IP "Literals of the form 1.2.3 parse differently" 4
+.el .IP "Literals of the form \f(CW1.2.3\fR parse differently" 4
+.IX Item "Literals of the form 1.2.3 parse differently"
+Previously, numeric literals with more than one dot in them were
+interpreted as a floating point number concatenated with one or more
+numbers.  Such "numbers" are now parsed as strings composed of the
+specified ordinals.
+.Sp
+For example, \f(CW\*(C`print 97.98.99\*(C'\fR used to output \f(CW97.9899\fR in earlier
+versions, but now prints \f(CW\*(C`abc\*(C'\fR.
+.Sp
+See "Support for strings represented as a vector of ordinals".
+.IP "Possibly changed pseudo-random number generator" 4
+.IX Item "Possibly changed pseudo-random number generator"
+Perl programs that depend on reproducing a specific set of pseudo-random
+numbers may now produce different output due to improvements made to the
+\&\fBrand()\fR builtin.  You can use \f(CW\*(C`sh Configure \-Drandfunc=rand\*(C'\fR to obtain
+the old behavior.
+.Sp
+See "Better pseudo-random number generator".
+.IP "Hashing function for hash keys has changed" 4
+.IX Item "Hashing function for hash keys has changed"
+Even though Perl hashes are not order preserving, the apparently
+random order encountered when iterating on the contents of a hash
+is actually determined by the hashing algorithm used.  Improvements
+in the algorithm may yield a random order that is \fBdifferent\fR from
+that of previous versions, especially when iterating on hashes.
+.Sp
+See "Better worst-case behavior of hashes" for additional
+information.
+.ie n .IP """undef"" fails on read only values" 4
+.el .IP "\f(CWundef\fR fails on read only values" 4
+.IX Item "undef fails on read only values"
+Using the \f(CW\*(C`undef\*(C'\fR operator on a readonly value (such as \f(CW$1\fR) has
+the same effect as assigning \f(CW\*(C`undef\*(C'\fR to the readonly value\-\-it
+throws an exception.
+.IP "Close-on-exec bit may be set on pipe and socket handles" 4
+.IX Item "Close-on-exec bit may be set on pipe and socket handles"
+Pipe and socket handles are also now subject to the close-on-exec
+behavior determined by the special variable $^F.
+.Sp
+See "More consistent close-on-exec behavior".
+.ie n .IP "Writing ""$$1"" to mean ""${$}1"" is unsupported" 4
+.el .IP "Writing \f(CW""$$1""\fR to mean \f(CW""${$}1""\fR is unsupported" 4
+.IX Item "Writing ""$$1"" to mean ""${$}1"" is unsupported"
+Perl 5.004 deprecated the interpretation of \f(CW$$1\fR and
+similar within interpolated strings to mean \f(CW\*(C`$$ . "1"\*(C'\fR,
+but still allowed it.
+.Sp
+In Perl 5.6.0 and later, \f(CW"$$1"\fR always means \f(CW"${$1}"\fR.
+.ie n .IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and ""\e(%h)""" 4
+.el .IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and \f(CW\e(%h)\fR" 4
+.IX Item "delete(), each(), values() and )"
+operate on aliases to values, not copies
+.Sp
+\&\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hashes (e.g. \f(CW\*(C`\e(%h)\*(C'\fR)
+in a list context return the actual
+values in the hash, instead of copies (as they used to in earlier
+versions).  Typical idioms for using these constructs copy the
+returned values, but this can make a significant difference when
+creating references to the returned values.  Keys in the hash are still
+returned as copies when iterating on a hash.
+.Sp
+See also "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hash iteration are faster".
+.IP "vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS" 4
+.IX Item "vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS"
+\&\fBvec()\fR generates a run-time error if the BITS argument is not
+a valid power-of-two integer.
+.IP "Text of some diagnostic output has changed" 4
+.IX Item "Text of some diagnostic output has changed"
+Most references to internal Perl operations in diagnostics
+have been changed to be more descriptive.  This may be an
+issue for programs that may incorrectly rely on the exact
+text of diagnostics for proper functioning.
+.ie n .IP """%@"" has been removed" 4
+.el .IP "\f(CW%@\fR has been removed" 4
+.IX Item "%@ has been removed"
+The undocumented special variable \f(CW\*(C`%@\*(C'\fR that used to accumulate
+"background" errors (such as those that happen in \fBDESTROY()\fR)
+has been removed, because it could potentially result in memory
+leaks.
+.IP "Parenthesized \fBnot()\fR behaves like a list operator" 4
+.IX Item "Parenthesized not() behaves like a list operator"
+The \f(CW\*(C`not\*(C'\fR operator now falls under the "if it looks like a function,
+it behaves like a function" rule.
+.Sp
+As a result, the parenthesized form can be used with \f(CW\*(C`grep\*(C'\fR and \f(CW\*(C`map\*(C'\fR.
+The following construct used to be a syntax error before, but it works
+as expected now:
+.Sp
+.Vb 1
+\&    grep not($_), @things;
+.Ve
+.Sp
+On the other hand, using \f(CW\*(C`not\*(C'\fR with a literal list slice may not
+work.  The following previously allowed construct:
+.Sp
+.Vb 1
+\&    print not (1,2,3)[0];
+.Ve
+.Sp
+needs to be written with additional parentheses now:
+.Sp
+.Vb 1
+\&    print not((1,2,3)[0]);
+.Ve
+.Sp
+The behavior remains unaffected when \f(CW\*(C`not\*(C'\fR is not followed by parentheses.
+.ie n .IP "Semantics of bareword prototype ""(*)"" have changed" 4
+.el .IP "Semantics of bareword prototype \f(CW(*)\fR have changed" 4
+.IX Item "Semantics of bareword prototype (*) have changed"
+The semantics of the bareword prototype \f(CW\*(C`*\*(C'\fR have changed.  Perl 5.005
+always coerced simple scalar arguments to a typeglob, which wasn't useful
+in situations where the subroutine must distinguish between a simple
+scalar and a typeglob.  The new behavior is to not coerce bareword
+arguments to a typeglob.  The value will always be visible as either
+a simple scalar or as a reference to a typeglob.
+.Sp
+See "More functional bareword prototype (*)".
+.IP "Semantics of bit operators may have changed on 64\-bit platforms" 4
+.IX Item "Semantics of bit operators may have changed on 64-bit platforms"
+If your platform is either natively 64\-bit or if Perl has been
+configured to used 64\-bit integers, i.e., \f(CW$Config\fR{ivsize} is 8, 
+there may be a potential incompatibility in the behavior of bitwise
+numeric operators (& | ^ ~ << >>).  These operators used to strictly
+operate on the lower 32 bits of integers in previous versions, but now
+operate over the entire native integral width.  In particular, note
+that unary \f(CW\*(C`~\*(C'\fR will produce different results on platforms that have
+different \f(CW$Config\fR{ivsize}.  For portability, be sure to mask off
+the excess bits in the result of unary \f(CW\*(C`~\*(C'\fR, e.g., \f(CW\*(C`~$x & 0xffffffff\*(C'\fR.
+.Sp
+See "Bit operators support full native integer width".
+.IP "More builtins taint their results" 4
+.IX Item "More builtins taint their results"
+As described in "Improved security features", there may be more
+sources of taint in a Perl program.
+.Sp
+To avoid these new tainting behaviors, you can build Perl with the
+Configure option \f(CW\*(C`\-Accflags=\-DINCOMPLETE_TAINTS\*(C'\fR.  Beware that the
+ensuing perl binary may be insecure.
+.SS "C Source Incompatibilities"
+.IX Subsection "C Source Incompatibilities"
+.ie n .IP """PERL_POLLUTE""" 4
+.el .IP \f(CWPERL_POLLUTE\fR 4
+.IX Item "PERL_POLLUTE"
+Release 5.005 grandfathered old global symbol names by providing preprocessor
+macros for extension source compatibility.  As of release 5.6.0, these
+preprocessor definitions are not available by default.  You need to explicitly
+compile perl with \f(CW\*(C`\-DPERL_POLLUTE\*(C'\fR to get these definitions.  For
+extensions still using the old symbols, this option can be
+specified via MakeMaker:
+.Sp
+.Vb 1
+\&    perl Makefile.PL POLLUTE=1
+.Ve
+.ie n .IP """PERL_IMPLICIT_CONTEXT""" 4
+.el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4
+.IX Item "PERL_IMPLICIT_CONTEXT"
+This new build option provides a set of macros for all API functions
+such that an implicit interpreter/thread context argument is passed to
+every API function.  As a result of this, something like \f(CW\*(C`sv_setsv(foo,bar)\*(C'\fR
+amounts to a macro invocation that actually translates to something like
+\&\f(CW\*(C`Perl_sv_setsv(my_perl,foo,bar)\*(C'\fR.  While this is generally expected
+to not have any significant source compatibility issues, the difference
+between a macro and a real function call will need to be considered.
+.Sp
+This means that there \fBis\fR a source compatibility issue as a result of
+this if your extensions attempt to use pointers to any of the Perl API
+functions.
+.Sp
+Note that the above issue is not relevant to the default build of
+Perl, whose interfaces continue to match those of prior versions
+(but subject to the other options described here).
+.Sp
+See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for detailed information
+on the ramifications of building Perl with this option.
+.Sp
+.Vb 3
+\&    NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
+\&    with one of \-Dusethreads, \-Dusemultiplicity, or both.  It is not
+\&    intended to be enabled by users at this time.
+.Ve
+.ie n .IP """PERL_POLLUTE_MALLOC""" 4
+.el .IP \f(CWPERL_POLLUTE_MALLOC\fR 4
+.IX Item "PERL_POLLUTE_MALLOC"
+Enabling Perl's malloc in release 5.005 and earlier caused the namespace of
+the system's malloc family of functions to be usurped by the Perl versions,
+since by default they used the same names.  Besides causing problems on
+platforms that do not allow these functions to be cleanly replaced, this
+also meant that the system versions could not be called in programs that
+used Perl's malloc.  Previous versions of Perl have allowed this behaviour
+to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor
+definitions.
+.Sp
+As of release 5.6.0, Perl's malloc family of functions have default names
+distinct from the system versions.  You need to explicitly compile perl with
+\&\f(CW\*(C`\-DPERL_POLLUTE_MALLOC\*(C'\fR to get the older behaviour.  HIDEMYMALLOC
+and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now
+the default.
+.Sp
+Note that these functions do \fBnot\fR constitute Perl's memory allocation API.
+See "Memory Allocation" in perlguts for further information about that.
+.SS "Compatible C Source API Changes"
+.IX Subsection "Compatible C Source API Changes"
+.ie n .IP """PATCHLEVEL"" is now ""PERL_VERSION""" 4
+.el .IP "\f(CWPATCHLEVEL\fR is now \f(CWPERL_VERSION\fR" 4
+.IX Item "PATCHLEVEL is now PERL_VERSION"
+The cpp macros \f(CW\*(C`PERL_REVISION\*(C'\fR, \f(CW\*(C`PERL_VERSION\*(C'\fR, and \f(CW\*(C`PERL_SUBVERSION\*(C'\fR
+are now available by default from perl.h, and reflect the base revision,
+patchlevel, and subversion respectively.  \f(CW\*(C`PERL_REVISION\*(C'\fR had no
+prior equivalent, while \f(CW\*(C`PERL_VERSION\*(C'\fR and \f(CW\*(C`PERL_SUBVERSION\*(C'\fR were
+previously available as \f(CW\*(C`PATCHLEVEL\*(C'\fR and \f(CW\*(C`SUBVERSION\*(C'\fR.
+.Sp
+The new names cause less pollution of the \fBcpp\fR namespace and reflect what
+the numbers have come to stand for in common practice.  For compatibility,
+the old names are still supported when \fIpatchlevel.h\fR is explicitly
+included (as required before), so there is no source incompatibility
+from the change.
+.SS "Binary Incompatibilities"
+.IX Subsection "Binary Incompatibilities"
+In general, the default build of this release is expected to be binary
+compatible for extensions built with the 5.005 release or its maintenance
+versions.  However, specific platforms may have broken binary compatibility
+due to changes in the defaults used in hints files.  Therefore, please be
+sure to always check the platform-specific README files for any notes to
+the contrary.
+.PP
+The usethreads or usemultiplicity builds are \fBnot\fR binary compatible
+with the corresponding builds in 5.005.
+.PP
+On platforms that require an explicit list of exports (AIX, OS/2 and Windows,
+among others), purely internal symbols such as parser functions and the
+run time opcodes are not exported by default.  Perl 5.005 used to export
+all functions irrespective of whether they were considered part of the
+public API or not.
+.PP
+For the full list of public API functions, see perlapi.
+.SH "Known Problems"
+.IX Header "Known Problems"
+.SS "Localizing a tied hash element may leak memory"
+.IX Subsection "Localizing a tied hash element may leak memory"
+As of the 5.6.1 release, there is a known leak when code such as this
+is executed:
+.PP
+.Vb 2
+\&    use Tie::Hash;
+\&    tie my %tie_hash => \*(AqTie::StdHash\*(Aq;
+\&
+\&    ...
+\&
+\&    local($tie_hash{Foo}) = 1; # leaks
+.Ve
+.SS "Known test failures"
+.IX Subsection "Known test failures"
+.IP \(bu 4
+64\-bit builds
+.Sp
+Subtest #15 of lib/b.t may fail under 64\-bit builds on platforms such
+as HP-UX PA64 and Linux IA64.  The issue is still being investigated.
+.Sp
+The lib/io_multihomed test may hang in HP-UX if Perl has been
+configured to be 64\-bit.  Because other 64\-bit platforms do not
+hang in this test, HP-UX is suspect.  All other tests pass
+in 64\-bit HP-UX.  The test attempts to create and connect to
+"multihomed" sockets (sockets which have multiple IP addresses).
+.Sp
+Note that 64\-bit support is still experimental.
+.IP \(bu 4
+Failure of Thread tests
+.Sp
+The subtests 19 and 20 of lib/thr5005.t test are known to fail due to
+fundamental problems in the 5.005 threading implementation.  These are
+not new failures\-\-Perl 5.005_0x has the same bugs, but didn't have these
+tests.  (Note that support for 5.005\-style threading remains experimental.)
+.IP \(bu 4
+NEXTSTEP 3.3 POSIX test failure
+.Sp
+In NEXTSTEP 3.3p2 the implementation of the \fBstrftime\fR\|(3) in the
+operating system libraries is buggy: the \f(CW%j\fR format numbers the days of
+a month starting from zero, which, while being logical to programmers,
+will cause the subtests 19 to 27 of the lib/posix test may fail.
+.IP \(bu 4
+Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
+.Sp
+If compiled with gcc 2.95 the lib/sdbm test will fail (dump core).
+The cure is to use the vendor cc, it comes with the operating system
+and produces good code.
+.SS "EBCDIC platforms not fully supported"
+.IX Subsection "EBCDIC platforms not fully supported"
+In earlier releases of Perl, EBCDIC environments like OS390 (also
+known as Open Edition MVS) and VM-ESA were supported.  Due to changes
+required by the UTF\-8 (Unicode) support, the EBCDIC platforms are not
+supported in Perl 5.6.0.
+.PP
+The 5.6.1 release improves support for EBCDIC platforms, but they
+are not fully supported yet.
+.SS "UNICOS/mk CC failures during Configure run"
+.IX Subsection "UNICOS/mk CC failures during Configure run"
+In UNICOS/mk the following errors may appear during the Configure run:
+.PP
+.Vb 6
+\&        Guessing which symbols your C compiler and preprocessor define...
+\&        CC\-20 cc: ERROR File = try.c, Line = 3
+\&        ...
+\&          bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
+\&        ...
+\&        4 errors detected in the compilation of "try.c".
+.Ve
+.PP
+The culprit is the broken awk of UNICOS/mk.  The effect is fortunately
+rather mild: Perl itself is not adversely affected by the error, only
+the h2ph utility coming with Perl, and that is rather rarely needed
+these days.
+.SS "Arrow operator and arrays"
+.IX Subsection "Arrow operator and arrays"
+When the left argument to the arrow operator \f(CW\*(C`\->\*(C'\fR is an array, or
+the \f(CW\*(C`scalar\*(C'\fR operator operating on an array, the result of the
+operation must be considered erroneous. For example:
+.PP
+.Vb 2
+\&    @x\->[2]
+\&    scalar(@x)\->[2]
+.Ve
+.PP
+These expressions will get run-time errors in some future release of
+Perl.
+.SS "Experimental features"
+.IX Subsection "Experimental features"
+As discussed above, many features are still experimental.  Interfaces and
+implementation of these features are subject to change, and in extreme cases,
+even subject to removal in some future release of Perl.  These features
+include the following:
+.IP Threads 4
+.IX Item "Threads"
+.PD 0
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "64\-bit support" 4
+.IX Item "64-bit support"
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+.IP "Weak references" 4
+.IX Item "Weak references"
+.IP "The pseudo-hash data type" 4
+.IX Item "The pseudo-hash data type"
+.IP "The Compiler suite" 4
+.IX Item "The Compiler suite"
+.IP "Internal implementation of file globbing" 4
+.IX Item "Internal implementation of file globbing"
+.IP "The DB module" 4
+.IX Item "The DB module"
+.IP "The regular expression code constructs:" 4
+.IX Item "The regular expression code constructs:"
+.PD
+\&\f(CW\*(C`(?{ code })\*(C'\fR and \f(CW\*(C`(??{ code })\*(C'\fR
+.SH "Obsolete Diagnostics"
+.IX Header "Obsolete Diagnostics"
+.IP "Character class syntax [: :] is reserved for future extensions" 4
+.IX Item "Character class syntax [: :] is reserved for future extensions"
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\e[:" and ":\e]".
+.IP "Ill-formed logical name |%s| in prime_env_iter" 4
+.IX Item "Ill-formed logical name |%s| in prime_env_iter"
+(W) A warning peculiar to VMS.  A logical name was encountered when preparing
+to iterate over \f(CW%ENV\fR which violates the syntactic rules governing logical
+names.  Because it cannot be translated normally, it is skipped, and will not
+appear in \f(CW%ENV\fR.  This may be a benign occurrence, as some software packages
+might directly modify logical name tables and introduce nonstandard names,
+or it may indicate that a logical name table has been corrupted.
+.IP "In string, @%s now must be written as \e@%s" 4
+.IX Item "In string, @%s now must be written as @%s"
+The description of this error used to say:
+.Sp
+.Vb 2
+\&        (Someday it will simply assume that an unbackslashed @
+\&         interpolates an array.)
+.Ve
+.Sp
+That day has come, and this fatal error has been removed.  It has been
+replaced by a non-fatal warning instead.
+See "Arrays now always interpolate into double-quoted strings" for
+details.
+.ie n .IP "Probable precedence problem on %s" 4
+.el .IP "Probable precedence problem on \f(CW%s\fR" 4
+.IX Item "Probable precedence problem on %s"
+(W) The compiler found a bareword where it expected a conditional,
+which often indicates that an || or && was parsed as part of the
+last argument of the previous construct, for example:
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.IP "regexp too big" 4
+.IX Item "regexp too big"
+(F) The current implementation of regular expressions uses shorts as
+address offsets within a string.  Unfortunately this means that if
+the regular expression compiles to longer than 32767, it'll blow up.
+Usually when you want a regular expression this big, there is a better
+way to do it with multiple statements.  See perlre.
+.IP "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated" 4
+.IX Item "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated"
+(D) Perl versions before 5.004 misinterpreted any type marker followed
+by "$" and a digit.  For example, "$$0" was incorrectly taken to mean
+"${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
+.Sp
+However, the developers of Perl 5.004 could not fix this bug completely,
+because at least two widely-used modules depend on the old meaning of
+"$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
+old (broken) way inside strings; but it generates this message as a
+warning.  And in Perl 5.005, this special treatment will cease.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the
+articles recently posted to the comp.lang.perl.misc newsgroup.
+There may also be information at http://www.perl.com/ , the Perl
+Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Written by Gurusamy Sarathy <\fIgsar@ActiveState.com\fR>, with many
+contributions from The Perl Porters.
+.PP
+Send omissions or corrections to <\fIperlbug@perl.org\fR>.
diff --git a/upstream/mageia-cauldron/man1/perl56delta.1 b/upstream/mageia-cauldron/man1/perl56delta.1
new file mode 100644
index 00000000..90865067
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl56delta.1
@@ -0,0 +1,2870 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL56DELTA 1"
+.TH PERL56DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl56delta \- what's new for perl v5.6.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.005 release and the 5.6.0
+release.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Interpreter cloning, threads, and concurrency"
+.IX Subsection "Interpreter cloning, threads, and concurrency"
+Perl 5.6.0 introduces the beginnings of support for running multiple
+interpreters concurrently in different threads.  In conjunction with
+the \fBperl_clone()\fR API call, which can be used to selectively duplicate
+the state of any given interpreter, it is possible to compile a
+piece of code once in an interpreter, clone that interpreter
+one or more times, and run all the resulting interpreters in distinct
+threads.
+.PP
+On the Windows platform, this feature is used to emulate \fBfork()\fR at the
+interpreter level.  See perlfork for details about that.
+.PP
+This feature is still in evolution.  It is eventually meant to be used
+to selectively clone a subroutine and data reachable from that
+subroutine in a separate interpreter and run the cloned subroutine
+in a separate thread.  Since there is no shared data between the
+interpreters, little or no locking will be needed (unless parts of
+the symbol table are explicitly shared).  This is obviously intended
+to be an easy-to-use replacement for the existing threads support.
+.PP
+Support for cloning interpreters and interpreter concurrency can be
+enabled using the \-Dusethreads Configure option (see win32/Makefile for
+how to enable it on Windows.)  The resulting perl executable will be
+functionally identical to one that was built with \-Dmultiplicity, but
+the \fBperl_clone()\fR API call will only be available in the former.
+.PP
+\&\-Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn
+enables Perl source code changes that provide a clear separation between
+the op tree and the data it operates with.  The former is immutable, and
+can therefore be shared between an interpreter and all of its clones,
+while the latter is considered local to each interpreter, and is therefore
+copied for each clone.
+.PP
+Note that building Perl with the \-Dusemultiplicity Configure option
+is adequate if you wish to run multiple \fBindependent\fR interpreters
+concurrently in different threads.  \-Dusethreads only provides the
+additional functionality of the \fBperl_clone()\fR API call and other
+support for running \fBcloned\fR interpreters concurrently.
+.PP
+.Vb 2
+\&    NOTE: This is an experimental feature.  Implementation details are
+\&    subject to change.
+.Ve
+.SS "Lexically scoped warning categories"
+.IX Subsection "Lexically scoped warning categories"
+You can now control the granularity of warnings emitted by perl at a finer
+level using the \f(CW\*(C`use warnings\*(C'\fR pragma.  warnings and perllexwarn
+have copious documentation on this feature.
+.SS "Unicode and UTF\-8 support"
+.IX Subsection "Unicode and UTF-8 support"
+Perl now uses UTF\-8 as its internal representation for character
+strings.  The \f(CW\*(C`utf8\*(C'\fR and \f(CW\*(C`bytes\*(C'\fR pragmas are used to control this support
+in the current lexical scope.  See perlunicode, utf8 and bytes for
+more information.
+.PP
+This feature is expected to evolve quickly to support some form of I/O
+disciplines that can be used to specify the kind of input and output data
+(bytes or characters).  Until that happens, additional modules from CPAN
+will be needed to complete the toolkit for dealing with Unicode.
+.PP
+.Vb 2
+\&    NOTE: This should be considered an experimental feature.  Implementation
+\&    details are subject to change.
+.Ve
+.SS "Support for interpolating named characters"
+.IX Subsection "Support for interpolating named characters"
+The new \f(CW\*(C`\eN\*(C'\fR escape interpolates named characters within strings.
+For example, \f(CW"Hi! \eN{WHITE SMILING FACE}"\fR evaluates to a string
+with a unicode smiley face at the end.
+.SS """our"" declarations"
+.IX Subsection """our"" declarations"
+An "our" declaration introduces a value that can be best understood
+as a lexically scoped symbolic alias to a global variable in the
+package that was current where the variable was declared.  This is
+mostly useful as an alternative to the \f(CW\*(C`vars\*(C'\fR pragma, but also provides
+the opportunity to introduce typing and other attributes for such
+variables.  See "our" in perlfunc.
+.SS "Support for strings represented as a vector of ordinals"
+.IX Subsection "Support for strings represented as a vector of ordinals"
+Literals of the form \f(CW\*(C`v1.2.3.4\*(C'\fR are now parsed as a string composed
+of characters with the specified ordinals.  This is an alternative, more
+readable way to construct (possibly unicode) strings instead of
+interpolating characters, as in \f(CW"\ex{1}\ex{2}\ex{3}\ex{4}"\fR.  The leading
+\&\f(CW\*(C`v\*(C'\fR may be omitted if there are more than two ordinals, so \f(CW1.2.3\fR is
+parsed the same as \f(CW\*(C`v1.2.3\*(C'\fR.
+.PP
+Strings written in this form are also useful to represent version "numbers".
+It is easy to compare such version "numbers" (which are really just plain
+strings) using any of the usual string comparison operators \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR,
+\&\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, etc., or perform bitwise string operations on them using \f(CW\*(C`|\*(C'\fR,
+\&\f(CW\*(C`&\*(C'\fR, etc.
+.PP
+In conjunction with the new \f(CW$^V\fR magic variable (which contains
+the perl version as a string), such literals can be used as a readable way
+to check if you're running a particular version of Perl:
+.PP
+.Vb 4
+\&    # this will parse in older versions of Perl also
+\&    if ($^V and $^V gt v5.6.0) {
+\&        # new features supported
+\&    }
+.Ve
+.PP
+\&\f(CW\*(C`require\*(C'\fR and \f(CW\*(C`use\*(C'\fR also have some special magic to support such
+literals, but this particular usage should be avoided because it leads to
+misleading error messages under versions of Perl which don't support vector
+strings.  Using a true version number will ensure correct behavior in all
+versions of Perl:
+.PP
+.Vb 2
+\&    require 5.006;    # run time check for v5.6
+\&    use 5.006_001;    # compile time check for v5.6.1
+.Ve
+.PP
+Also, \f(CW\*(C`sprintf\*(C'\fR and \f(CW\*(C`printf\*(C'\fR support the Perl-specific format flag \f(CW%v\fR
+to print ordinals of characters in arbitrary strings:
+.PP
+.Vb 3
+\&    printf "v%vd", $^V;         # prints current version, such as "v5.5.650"
+\&    printf "%*vX", ":", $addr;  # formats IPv6 address
+\&    printf "%*vb", " ", $bits;  # displays bitstring
+.Ve
+.PP
+See "Scalar value constructors" in perldata for additional information.
+.SS "Improved Perl version numbering system"
+.IX Subsection "Improved Perl version numbering system"
+Beginning with Perl version 5.6.0, the version number convention has been
+changed to a "dotted integer" scheme that is more commonly found in open
+source projects.
+.PP
+Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
+The next development series following v5.6.0 will be numbered v5.7.x,
+beginning with v5.7.0, and the next major production release following
+v5.6.0 will be v5.8.0.
+.PP
+The English module now sets \f(CW$PERL_VERSION\fR to $^V (a string value) rather
+than \f(CW$]\fR (a numeric value).  (This is a potential incompatibility.
+Send us a report via perlbug if you are affected by this.)
+.PP
+The v1.2.3 syntax is also now legal in Perl.
+See "Support for strings represented as a vector of ordinals" for more on that.
+.PP
+To cope with the new versioning system's use of at least three significant
+digits for each version component, the method used for incrementing the
+subversion number has also changed slightly.  We assume that versions older
+than v5.6.0 have been incrementing the subversion component in multiples of
+10.  Versions after v5.6.0 will increment them by 1.  Thus, using the new
+notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance
+version following v5.6.0 will be v5.6.1 (which should be read as being
+equivalent to a floating point value of 5.006_001 in the older format,
+stored in \f(CW$]\fR).
+.SS "New syntax for declaring subroutine attributes"
+.IX Subsection "New syntax for declaring subroutine attributes"
+Formerly, if you wanted to mark a subroutine as being a method call or
+as requiring an automatic \fBlock()\fR when it is entered, you had to declare
+that with a \f(CW\*(C`use attrs\*(C'\fR pragma in the body of the subroutine.
+That can now be accomplished with declaration syntax, like this:
+.PP
+.Vb 5
+\&    sub mymethod : locked method;
+\&    ...
+\&    sub mymethod : locked method {
+\&        ...
+\&    }
+\&
+\&    sub othermethod :locked :method;
+\&    ...
+\&    sub othermethod :locked :method {
+\&        ...
+\&    }
+.Ve
+.PP
+(Note how only the first \f(CW\*(C`:\*(C'\fR is mandatory, and whitespace surrounding
+the \f(CW\*(C`:\*(C'\fR is optional.)
+.PP
+\&\fIAutoSplit.pm\fR and \fISelfLoader.pm\fR have been updated to keep the attributes
+with the stubs they provide.  See attributes.
+.SS "File and directory handles can be autovivified"
+.IX Subsection "File and directory handles can be autovivified"
+Similar to how constructs such as \f(CW\*(C`$x\->[0]\*(C'\fR autovivify a reference,
+handle constructors (\fBopen()\fR, \fBopendir()\fR, \fBpipe()\fR, \fBsocketpair()\fR, \fBsysopen()\fR,
+\&\fBsocket()\fR, and \fBaccept()\fR) now autovivify a file or directory handle
+if the handle passed to them is an uninitialized scalar variable.  This
+allows the constructs such as \f(CW\*(C`open(my $fh, ...)\*(C'\fR and \f(CW\*(C`open(local $fh,...)\*(C'\fR
+to be used to create filehandles that will conveniently be closed
+automatically when the scope ends, provided there are no other references
+to them.  This largely eliminates the need for typeglobs when opening
+filehandles that must be passed around, as in the following example:
+.PP
+.Vb 5
+\&    sub myopen {
+\&        open my $fh, "@_"
+\&             or die "Can\*(Aqt open \*(Aq@_\*(Aq: $!";
+\&        return $fh;
+\&    }
+\&
+\&    {
+\&        my $f = myopen("</etc/motd");
+\&        print <$f>;
+\&        # $f implicitly closed here
+\&    }
+.Ve
+.SS "\fBopen()\fP with more than two arguments"
+.IX Subsection "open() with more than two arguments"
+If \fBopen()\fR is passed three arguments instead of two, the second argument
+is used as the mode and the third argument is taken to be the file name.
+This is primarily useful for protecting against unintended magic behavior
+of the traditional two-argument form.  See "open" in perlfunc.
+.SS "64\-bit support"
+.IX Subsection "64-bit support"
+Any platform that has 64\-bit integers either
+.PP
+.Vb 3
+\&        (1) natively as longs or ints
+\&        (2) via special compiler flags
+\&        (3) using long long or int64_t
+.Ve
+.PP
+is able to use "quads" (64\-bit integers) as follows:
+.IP \(bu 4
+constants (decimal, hexadecimal, octal, binary) in the code
+.IP \(bu 4
+arguments to \fBoct()\fR and \fBhex()\fR
+.IP \(bu 4
+arguments to \fBprint()\fR, \fBprintf()\fR and \fBsprintf()\fR (flag prefixes ll, L, q)
+.IP \(bu 4
+printed as such
+.IP \(bu 4
+\&\fBpack()\fR and \fBunpack()\fR "q" and "Q" formats
+.IP \(bu 4
+in basic arithmetics: + \- * / % (NOTE: operating close to the limits
+of the integer values may produce surprising results)
+.IP \(bu 4
+in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced 
+to be 32 bits wide but now operate on the full native width.)
+.IP \(bu 4
+\&\fBvec()\fR
+.PP
+Note that unless you have the case (a) you will have to configure
+and compile Perl using the \-Duse64bitint Configure flag.
+.PP
+.Vb 2
+\&    NOTE: The Configure flags \-Duselonglong and \-Duse64bits have been
+\&    deprecated.  Use \-Duse64bitint instead.
+.Ve
+.PP
+There are actually two modes of 64\-bitness: the first one is achieved
+using Configure \-Duse64bitint and the second one using Configure
+\&\-Duse64bitall.  The difference is that the first one is minimal and
+the second one maximal.  The first works in more places than the second.
+.PP
+The \f(CW\*(C`use64bitint\*(C'\fR does only as much as is required to get 64\-bit
+integers into Perl (this may mean, for example, using "long longs")
+while your memory may still be limited to 2 gigabytes (because your
+pointers could still be 32\-bit).  Note that the name \f(CW\*(C`64bitint\*(C'\fR does
+not imply that your C compiler will be using 64\-bit \f(CW\*(C`int\*(C'\fRs (it might,
+but it doesn't have to): the \f(CW\*(C`use64bitint\*(C'\fR means that you will be
+able to have 64 bits wide scalar values.
+.PP
+The \f(CW\*(C`use64bitall\*(C'\fR goes all the way by attempting to switch also
+integers (if it can), longs (and pointers) to being 64\-bit.  This may
+create an even more binary incompatible Perl than \-Duse64bitint: the
+resulting executable may not run at all in a 32\-bit box, or you may
+have to reboot/reconfigure/rebuild your operating system to be 64\-bit
+aware.
+.PP
+Natively 64\-bit systems like Alpha and Cray need neither \-Duse64bitint
+nor \-Duse64bitall.
+.PP
+Last but not least: note that due to Perl's habit of always using
+floating point numbers, the quads are still not true integers.
+When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned,
+\&\-9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they
+are silently promoted to floating point numbers, after which they will
+start losing precision (in their lower digits).
+.PP
+.Vb 4
+\&    NOTE: 64\-bit support is still experimental on most platforms.
+\&    Existing support only covers the LP64 data model.  In particular, the
+\&    LLP64 data model is not yet supported.  64\-bit libraries and system
+\&    APIs on many platforms have not stabilized\-\-your mileage may vary.
+.Ve
+.SS "Large file support"
+.IX Subsection "Large file support"
+If you have filesystems that support "large files" (files larger than
+2 gigabytes), you may now also be able to create and access them from
+Perl.
+.PP
+.Vb 2
+\&    NOTE: The default action is to enable large file support, if
+\&    available on the platform.
+.Ve
+.PP
+If the large file support is on, and you have a Fcntl constant
+O_LARGEFILE, the O_LARGEFILE is automatically added to the flags
+of \fBsysopen()\fR.
+.PP
+Beware that unless your filesystem also supports "sparse files" seeking
+to umpteen petabytes may be inadvisable.
+.PP
+Note that in addition to requiring a proper file system to do large
+files you may also need to adjust your per-process (or your
+per-system, or per-process-group, or per-user-group) maximum filesize
+limits before running Perl scripts that try to handle large files,
+especially if you intend to write such files.
+.PP
+Finally, in addition to your process/process group maximum filesize
+limits, you may have quota limits on your filesystems that stop you
+(your user id or your user group id) from using large files.
+.PP
+Adjusting your process/user/group/file system/operating system limits
+is outside the scope of Perl core language.  For process limits, you
+may try increasing the limits using your shell's limits/limit/ulimit
+command before running Perl.  The BSD::Resource extension (not
+included with the standard Perl distribution) may also be of use, it
+offers the getrlimit/setrlimit interface that can be used to adjust
+process resource usage limits, including the maximum filesize limit.
+.SS "Long doubles"
+.IX Subsection "Long doubles"
+In some systems you may be able to use long doubles to enhance the
+range and precision of your double precision floating point numbers
+(that is, Perl's numbers).  Use Configure \-Duselongdouble to enable
+this support (if it is available).
+.SS """more bits"""
+.IX Subsection """more bits"""
+You can "Configure \-Dusemorebits" to turn on both the 64\-bit support
+and the long double support.
+.SS "Enhanced support for \fBsort()\fP subroutines"
+.IX Subsection "Enhanced support for sort() subroutines"
+Perl subroutines with a prototype of \f(CW\*(C`($$)\*(C'\fR, and XSUBs in general, can
+now be used as sort subroutines.  In either case, the two elements to
+be compared are passed as normal parameters in \f(CW@_\fR.  See "sort" in perlfunc.
+.PP
+For unprototyped sort subroutines, the historical behavior of passing 
+the elements to be compared as the global variables \f(CW$a\fR and \f(CW$b\fR remains
+unchanged.
+.ie n .SS """sort $coderef @foo"" allowed"
+.el .SS "\f(CWsort $coderef @foo\fP allowed"
+.IX Subsection "sort $coderef @foo allowed"
+\&\fBsort()\fR did not accept a subroutine reference as the comparison
+function in earlier versions.  This is now permitted.
+.SS "File globbing implemented internally"
+.IX Subsection "File globbing implemented internally"
+Perl now uses the File::Glob implementation of the \fBglob()\fR operator
+automatically.  This avoids using an external csh process and the
+problems associated with it.
+.PP
+.Vb 2
+\&    NOTE: This is currently an experimental feature.  Interfaces and
+\&    implementation are subject to change.
+.Ve
+.SS "Support for CHECK blocks"
+.IX Subsection "Support for CHECK blocks"
+In addition to \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, \f(CW\*(C`END\*(C'\fR, \f(CW\*(C`DESTROY\*(C'\fR and \f(CW\*(C`AUTOLOAD\*(C'\fR,
+subroutines named \f(CW\*(C`CHECK\*(C'\fR are now special.  These are queued up during
+compilation and behave similar to END blocks, except they are called at
+the end of compilation rather than at the end of execution.  They cannot
+be called directly.
+.SS "POSIX character class syntax [: :] supported"
+.IX Subsection "POSIX character class syntax [: :] supported"
+For example to match alphabetic characters use /[[:alpha:]]/.
+See perlre for details.
+.SS "Better pseudo-random number generator"
+.IX Subsection "Better pseudo-random number generator"
+In 5.005_0x and earlier, perl's \fBrand()\fR function used the C library
+\&\fBrand\fR\|(3) function.  As of 5.005_52, Configure tests for \fBdrand48()\fR,
+\&\fBrandom()\fR, and \fBrand()\fR (in that order) and picks the first one it finds.
+.PP
+These changes should result in better random numbers from \fBrand()\fR.
+.ie n .SS "Improved ""qw//"" operator"
+.el .SS "Improved \f(CWqw//\fP operator"
+.IX Subsection "Improved qw// operator"
+The \f(CW\*(C`qw//\*(C'\fR operator is now evaluated at compile time into a true list
+instead of being replaced with a run time call to \f(CWsplit()\fR.  This
+removes the confusing misbehaviour of \f(CW\*(C`qw//\*(C'\fR in scalar context, which
+had inherited that behaviour from \fBsplit()\fR.
+.PP
+Thus:
+.PP
+.Vb 1
+\&    $foo = ($bar) = qw(a b c); print "$foo|$bar\en";
+.Ve
+.PP
+now correctly prints "3|a", instead of "2|a".
+.SS "Better worst-case behavior of hashes"
+.IX Subsection "Better worst-case behavior of hashes"
+Small changes in the hashing algorithm have been implemented in
+order to improve the distribution of lower order bits in the
+hashed value.  This is expected to yield better performance on
+keys that are repeated sequences.
+.SS "\fBpack()\fP format 'Z' supported"
+.IX Subsection "pack() format 'Z' supported"
+The new format type 'Z' is useful for packing and unpacking null-terminated
+strings.  See "pack" in perlfunc.
+.SS "\fBpack()\fP format modifier '!' supported"
+.IX Subsection "pack() format modifier '!' supported"
+The new format type modifier '!' is useful for packing and unpacking
+native shorts, ints, and longs.  See "pack" in perlfunc.
+.SS "\fBpack()\fP and \fBunpack()\fP support counted strings"
+.IX Subsection "pack() and unpack() support counted strings"
+The template character '/' can be used to specify a counted string
+type to be packed or unpacked.  See "pack" in perlfunc.
+.SS "Comments in \fBpack()\fP templates"
+.IX Subsection "Comments in pack() templates"
+The '#' character in a template introduces a comment up to
+end of the line.  This facilitates documentation of \fBpack()\fR
+templates.
+.SS "Weak references"
+.IX Subsection "Weak references"
+In previous versions of Perl, you couldn't cache objects so as
+to allow them to be deleted if the last reference from outside 
+the cache is deleted.  The reference in the cache would hold a
+reference count on the object and the objects would never be
+destroyed.
+.PP
+Another familiar problem is with circular references.  When an
+object references itself, its reference count would never go
+down to zero, and it would not get destroyed until the program
+is about to exit.
+.PP
+Weak references solve this by allowing you to "weaken" any
+reference, that is, make it not count towards the reference count.
+When the last non-weak reference to an object is deleted, the object
+is destroyed and all the weak references to the object are
+automatically undef-ed.
+.PP
+To use this feature, you need the Devel::WeakRef package from CPAN, which
+contains additional documentation.
+.PP
+.Vb 1
+\&    NOTE: This is an experimental feature.  Details are subject to change.
+.Ve
+.SS "Binary numbers supported"
+.IX Subsection "Binary numbers supported"
+Binary numbers are now supported as literals, in s?printf formats, and
+\&\f(CWoct()\fR:
+.PP
+.Vb 2
+\&    $answer = 0b101010;
+\&    printf "The answer is: %b\en", oct("0b101010");
+.Ve
+.SS "Lvalue subroutines"
+.IX Subsection "Lvalue subroutines"
+Subroutines can now return modifiable lvalues.
+See "Lvalue subroutines" in perlsub.
+.PP
+.Vb 1
+\&    NOTE: This is an experimental feature.  Details are subject to change.
+.Ve
+.SS "Some arrows may be omitted in calls through references"
+.IX Subsection "Some arrows may be omitted in calls through references"
+Perl now allows the arrow to be omitted in many constructs
+involving subroutine calls through references.  For example,
+\&\f(CW\*(C`$foo[10]\->(\*(Aqfoo\*(Aq)\*(C'\fR may now be written \f(CW\*(C`$foo[10](\*(Aqfoo\*(Aq)\*(C'\fR.
+This is rather similar to how the arrow may be omitted from
+\&\f(CW\*(C`$foo[10]\->{\*(Aqfoo\*(Aq}\*(C'\fR.  Note however, that the arrow is still
+required for \f(CW\*(C`foo(10)\->(\*(Aqbar\*(Aq)\*(C'\fR.
+.SS "Boolean assignment operators are legal lvalues"
+.IX Subsection "Boolean assignment operators are legal lvalues"
+Constructs such as \f(CW\*(C`($a ||= 2) += 1\*(C'\fR are now allowed.
+.SS "\fBexists()\fP is supported on subroutine names"
+.IX Subsection "exists() is supported on subroutine names"
+The \fBexists()\fR builtin now works on subroutine names.  A subroutine
+is considered to exist if it has been declared (even if implicitly).
+See "exists" in perlfunc for examples.
+.SS "\fBexists()\fP and \fBdelete()\fP are supported on array elements"
+.IX Subsection "exists() and delete() are supported on array elements"
+The \fBexists()\fR and \fBdelete()\fR builtins now work on simple arrays as well.
+The behavior is similar to that on hash elements.
+.PP
+\&\fBexists()\fR can be used to check whether an array element has been
+initialized.  This avoids autovivifying array elements that don't exist.
+If the array is tied, the \fBEXISTS()\fR method in the corresponding tied
+package will be invoked.
+.PP
+\&\fBdelete()\fR may be used to remove an element from the array and return
+it.  The array element at that position returns to its uninitialized
+state, so that testing for the same element with \fBexists()\fR will return
+false.  If the element happens to be the one at the end, the size of
+the array also shrinks up to the highest element that tests true for
+\&\fBexists()\fR, or 0 if none such is found.  If the array is tied, the \fBDELETE()\fR 
+method in the corresponding tied package will be invoked.
+.PP
+See "exists" in perlfunc and "delete" in perlfunc for examples.
+.SS "Pseudo-hashes work better"
+.IX Subsection "Pseudo-hashes work better"
+Dereferencing some types of reference values in a pseudo-hash,
+such as \f(CW\*(C`$ph\->{foo}[1]\*(C'\fR, was accidentally disallowed.  This has
+been corrected.
+.PP
+When applied to a pseudo-hash element, \fBexists()\fR now reports whether
+the specified value exists, not merely if the key is valid.
+.PP
+\&\fBdelete()\fR now works on pseudo-hashes.  When given a pseudo-hash element
+or slice it deletes the values corresponding to the keys (but not the keys
+themselves).  See "Pseudo-hashes: Using an array as a hash" in perlref.
+.PP
+Pseudo-hash slices with constant keys are now optimized to array lookups
+at compile-time.
+.PP
+List assignments to pseudo-hash slices are now supported.
+.PP
+The \f(CW\*(C`fields\*(C'\fR pragma now provides ways to create pseudo-hashes, via
+\&\fBfields::new()\fR and \fBfields::phash()\fR.  See fields.
+.PP
+.Vb 3
+\&    NOTE: The pseudo\-hash data type continues to be experimental.
+\&    Limiting oneself to the interface elements provided by the
+\&    fields pragma will provide protection from any future changes.
+.Ve
+.SS "Automatic flushing of output buffers"
+.IX Subsection "Automatic flushing of output buffers"
+\&\fBfork()\fR, \fBexec()\fR, \fBsystem()\fR, qx//, and pipe \fBopen()\fRs now flush buffers
+of all files opened for output when the operation was attempted.  This
+mostly eliminates confusing buffering mishaps suffered by users unaware
+of how Perl internally handles I/O.
+.PP
+This is not supported on some platforms like Solaris where a suitably
+correct implementation of fflush(NULL) isn't available.
+.SS "Better diagnostics on meaningless filehandle operations"
+.IX Subsection "Better diagnostics on meaningless filehandle operations"
+Constructs such as \f(CWopen(<FH>)\fR and \f(CWclose(<FH>)\fR
+are compile time errors.  Attempting to read from filehandles that
+were opened only for writing will now produce warnings (just as
+writing to read-only filehandles does).
+.SS "Where possible, buffered data discarded from duped input filehandle"
+.IX Subsection "Where possible, buffered data discarded from duped input filehandle"
+\&\f(CW\*(C`open(NEW, "<&OLD")\*(C'\fR now attempts to discard any data that
+was previously read and buffered in \f(CW\*(C`OLD\*(C'\fR before duping the handle.
+On platforms where doing this is allowed, the next read operation
+on \f(CW\*(C`NEW\*(C'\fR will return the same data as the corresponding operation
+on \f(CW\*(C`OLD\*(C'\fR.  Formerly, it would have returned the data from the start
+of the following disk block instead.
+.SS "\fBeof()\fP has the same old magic as <>"
+.IX Subsection "eof() has the same old magic as <>"
+\&\f(CWeof()\fR would return true if no attempt to read from \f(CW\*(C`<>\*(C'\fR had
+yet been made.  \f(CWeof()\fR has been changed to have a little magic of its
+own, it now opens the \f(CW\*(C`<>\*(C'\fR files.
+.SS "\fBbinmode()\fP can be used to set :crlf and :raw modes"
+.IX Subsection "binmode() can be used to set :crlf and :raw modes"
+\&\fBbinmode()\fR now accepts a second argument that specifies a discipline
+for the handle in question.  The two pseudo-disciplines ":raw" and
+":crlf" are currently supported on DOS-derivative platforms.
+See "binmode" in perlfunc and open.
+.ie n .SS """\-T"" filetest recognizes UTF\-8 encoded files as ""text"""
+.el .SS "\f(CW\-T\fP filetest recognizes UTF\-8 encoded files as ""text"""
+.IX Subsection "-T filetest recognizes UTF-8 encoded files as ""text"""
+The algorithm used for the \f(CW\*(C`\-T\*(C'\fR filetest has been enhanced to
+correctly identify UTF\-8 content as "text".
+.SS "\fBsystem()\fP, backticks and pipe open now reflect \fBexec()\fP failure"
+.IX Subsection "system(), backticks and pipe open now reflect exec() failure"
+On Unix and similar platforms, \fBsystem()\fR, \fBqx()\fR and open(FOO, "cmd |")
+etc., are implemented via \fBfork()\fR and \fBexec()\fR.  When the underlying
+\&\fBexec()\fR fails, earlier versions did not report the error properly,
+since the \fBexec()\fR happened to be in a different process.
+.PP
+The child process now communicates with the parent about the
+error in launching the external command, which allows these
+constructs to return with their usual error value and set $!.
+.SS "Improved diagnostics"
+.IX Subsection "Improved diagnostics"
+Line numbers are no longer suppressed (under most likely circumstances)
+during the global destruction phase.
+.PP
+Diagnostics emitted from code running in threads other than the main
+thread are now accompanied by the thread ID.
+.PP
+Embedded null characters in diagnostics now actually show up.  They
+used to truncate the message in prior versions.
+.PP
+\&\f(CW$foo::a\fR and \f(CW$foo::b\fR are now exempt from "possible typo" warnings only
+if \fBsort()\fR is encountered in package \f(CW\*(C`foo\*(C'\fR.
+.PP
+Unrecognized alphabetic escapes encountered when parsing quote
+constructs now generate a warning, since they may take on new
+semantics in later versions of Perl.
+.PP
+Many diagnostics now report the internal operation in which the warning
+was provoked, like so:
+.PP
+.Vb 2
+\&    Use of uninitialized value in concatenation (.) at (eval 1) line 1.
+\&    Use of uninitialized value in print at (eval 1) line 1.
+.Ve
+.PP
+Diagnostics  that occur within eval may also report the file and line
+number where the eval is located, in addition to the eval sequence
+number and the line number within the evaluated text itself.  For
+example:
+.PP
+.Vb 1
+\&    Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF
+.Ve
+.SS "Diagnostics follow STDERR"
+.IX Subsection "Diagnostics follow STDERR"
+Diagnostic output now goes to whichever file the \f(CW\*(C`STDERR\*(C'\fR handle
+is pointing at, instead of always going to the underlying C runtime
+library's \f(CW\*(C`stderr\*(C'\fR.
+.SS "More consistent close-on-exec behavior"
+.IX Subsection "More consistent close-on-exec behavior"
+On systems that support a close-on-exec flag on filehandles, the
+flag is now set for any handles created by \fBpipe()\fR, \fBsocketpair()\fR,
+\&\fBsocket()\fR, and \fBaccept()\fR, if that is warranted by the value of $^F
+that may be in effect.  Earlier versions neglected to set the flag
+for handles created with these operators.  See "pipe" in perlfunc,
+"socketpair" in perlfunc, "socket" in perlfunc, "accept" in perlfunc,
+and "$^F" in perlvar.
+.SS "\fBsyswrite()\fP ease-of-use"
+.IX Subsection "syswrite() ease-of-use"
+The length argument of \f(CWsyswrite()\fR has become optional.
+.SS "Better syntax checks on parenthesized unary operators"
+.IX Subsection "Better syntax checks on parenthesized unary operators"
+Expressions such as:
+.PP
+.Vb 3
+\&    print defined(&foo,&bar,&baz);
+\&    print uc("foo","bar","baz");
+\&    undef($foo,&bar);
+.Ve
+.PP
+used to be accidentally allowed in earlier versions, and produced
+unpredictable behaviour.  Some produced ancillary warnings
+when used in this way; others silently did the wrong thing.
+.PP
+The parenthesized forms of most unary operators that expect a single
+argument now ensure that they are not called with more than one
+argument, making the cases shown above syntax errors.  The usual
+behaviour of:
+.PP
+.Vb 3
+\&    print defined &foo, &bar, &baz;
+\&    print uc "foo", "bar", "baz";
+\&    undef $foo, &bar;
+.Ve
+.PP
+remains unchanged.  See perlop.
+.SS "Bit operators support full native integer width"
+.IX Subsection "Bit operators support full native integer width"
+The bit operators (& | ^ ~ << >>) now operate on the full native
+integral width (the exact size of which is available in \f(CW$Config\fR{ivsize}).
+For example, if your platform is either natively 64\-bit or if Perl
+has been configured to use 64\-bit integers, these operations apply
+to 8 bytes (as opposed to 4 bytes on 32\-bit platforms).
+For portability, be sure to mask off the excess bits in the result of
+unary \f(CW\*(C`~\*(C'\fR, e.g., \f(CW\*(C`~$x & 0xffffffff\*(C'\fR.
+.SS "Improved security features"
+.IX Subsection "Improved security features"
+More potentially unsafe operations taint their results for improved
+security.
+.PP
+The \f(CW\*(C`passwd\*(C'\fR and \f(CW\*(C`shell\*(C'\fR fields returned by the \fBgetpwent()\fR, \fBgetpwnam()\fR,
+and \fBgetpwuid()\fR are now tainted, because the user can affect their own
+encrypted password and login shell.
+.PP
+The variable modified by \fBshmread()\fR, and messages returned by \fBmsgrcv()\fR
+(and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted,
+because other untrusted processes can modify messages and shared memory
+segments for their own nefarious purposes.
+.SS "More functional bareword prototype (*)"
+.IX Subsection "More functional bareword prototype (*)"
+Bareword prototypes have been rationalized to enable them to be used
+to override builtins that accept barewords and interpret them in
+a special way, such as \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR.
+.PP
+Arguments prototyped as \f(CW\*(C`*\*(C'\fR will now be visible within the subroutine
+as either a simple scalar or as a reference to a typeglob.
+See "Prototypes" in perlsub.
+.ie n .SS """require"" and ""do"" may be overridden"
+.el .SS "\f(CWrequire\fP and \f(CWdo\fP may be overridden"
+.IX Subsection "require and do may be overridden"
+\&\f(CW\*(C`require\*(C'\fR and \f(CW\*(C`do \*(Aqfile\*(Aq\*(C'\fR operations may be overridden locally
+by importing subroutines of the same name into the current package 
+(or globally by importing them into the CORE::GLOBAL:: namespace).
+Overriding \f(CW\*(C`require\*(C'\fR will also affect \f(CW\*(C`use\*(C'\fR, provided the override
+is visible at compile-time.
+See "Overriding Built-in Functions" in perlsub.
+.SS "$^X variables may now have names longer than one character"
+.IX Subsection "$^X variables may now have names longer than one character"
+Formerly, $^X was synonymous with ${"\ecX"}, but $^XY was a syntax
+error.  Now variable names that begin with a control character may be
+arbitrarily long.  However, for compatibility reasons, these variables
+\&\fImust\fR be written with explicit braces, as \f(CW\*(C`${^XY}\*(C'\fR for example.
+\&\f(CW\*(C`${^XYZ}\*(C'\fR is synonymous with ${"\ecXYZ"}.  Variable names with more
+than one control character, such as \f(CW\*(C`${^XY^Z}\*(C'\fR, are illegal.
+.PP
+The old syntax has not changed.  As before, `^X' may be either a
+literal control-X character or the two-character sequence `caret' plus
+`X'.  When braces are omitted, the variable name stops after the
+control character.  Thus \f(CW"$^XYZ"\fR continues to be synonymous with
+\&\f(CW\*(C`$^X . "YZ"\*(C'\fR as before.
+.PP
+As before, lexical variables may not have names beginning with control
+characters.  As before, variables whose names begin with a control
+character are always forced to be in package `main'.  All such variables
+are reserved for future extensions, except those that begin with
+\&\f(CW\*(C`^_\*(C'\fR, which may be used by user programs and are guaranteed not to
+acquire special meaning in any future version of Perl.
+.ie n .SS "New variable $^C reflects ""\-c"" switch"
+.el .SS "New variable $^C reflects \f(CW\-c\fP switch"
+.IX Subsection "New variable $^C reflects -c switch"
+\&\f(CW$^C\fR has a boolean value that reflects whether perl is being run
+in compile-only mode (i.e. via the \f(CW\*(C`\-c\*(C'\fR switch).  Since
+BEGIN blocks are executed under such conditions, this variable
+enables perl code to determine whether actions that make sense
+only during normal running are warranted.  See perlvar.
+.SS "New variable $^V contains Perl version as a string"
+.IX Subsection "New variable $^V contains Perl version as a string"
+\&\f(CW$^V\fR contains the Perl version number as a string composed of
+characters whose ordinals match the version numbers, i.e. v5.6.0.
+This may be used in string comparisons.
+.PP
+See \f(CW\*(C`Support for strings represented as a vector of ordinals\*(C'\fR for an
+example.
+.SS "Optional Y2K warnings"
+.IX Subsection "Optional Y2K warnings"
+If Perl is built with the cpp macro \f(CW\*(C`PERL_Y2KWARN\*(C'\fR defined,
+it emits optional warnings when concatenating the number 19
+with another number.
+.PP
+This behavior must be specifically enabled when running Configure.
+See \fIINSTALL\fR and \fIREADME.Y2K\fR.
+.SS "Arrays now always interpolate into double-quoted strings"
+.IX Subsection "Arrays now always interpolate into double-quoted strings"
+In double-quoted strings, arrays now interpolate, no matter what.  The
+behavior in earlier versions of perl 5 was that arrays would interpolate
+into strings if the array had been mentioned before the string was
+compiled, and otherwise Perl would raise a fatal compile-time error.
+In versions 5.000 through 5.003, the error was
+.PP
+.Vb 1
+\&        Literal @example now requires backslash
+.Ve
+.PP
+In versions 5.004_01 through 5.6.0, the error was
+.PP
+.Vb 1
+\&        In string, @example now must be written as \e@example
+.Ve
+.PP
+The idea here was to get people into the habit of writing
+\&\f(CW"fred\e@example.com"\fR when they wanted a literal \f(CW\*(C`@\*(C'\fR sign, just as
+they have always written \f(CW"Give me back my \e$5"\fR when they wanted a
+literal \f(CW\*(C`$\*(C'\fR sign.
+.PP
+Starting with 5.6.1, when Perl now sees an \f(CW\*(C`@\*(C'\fR sign in a
+double-quoted string, it \fIalways\fR attempts to interpolate an array,
+regardless of whether or not the array has been used or declared
+already.  The fatal error has been downgraded to an optional warning:
+.PP
+.Vb 1
+\&        Possible unintended interpolation of @example in string
+.Ve
+.PP
+This warns you that \f(CW"fred@example.com"\fR is going to turn into
+\&\f(CW\*(C`fred.com\*(C'\fR if you don't backslash the \f(CW\*(C`@\*(C'\fR.
+See http://perl.plover.com/at\-error.html for more details
+about the history here.
+.SS "@\- and @+ provide starting/ending offsets of regex matches"
+.IX Subsection "@- and @+ provide starting/ending offsets of regex matches"
+The new magic variables @\- and @+ provide the starting and ending
+offsets, respectively, of $&, \f(CW$1\fR, \f(CW$2\fR, etc.  See perlvar for
+details.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS Modules
+.IX Subsection "Modules"
+.IP attributes 4
+.IX Item "attributes"
+While used internally by Perl as a pragma, this module also
+provides a way to fetch subroutine and variable attributes.
+See attributes.
+.IP B 4
+.IX Item "B"
+The Perl Compiler suite has been extensively reworked for this
+release.  More of the standard Perl test suite passes when run
+under the Compiler, but there is still a significant way to
+go to achieve production quality compiled executables.
+.Sp
+.Vb 3
+\&    NOTE: The Compiler suite remains highly experimental.  The
+\&    generated code may not be correct, even when it manages to execute
+\&    without errors.
+.Ve
+.IP Benchmark 4
+.IX Item "Benchmark"
+Overall, Benchmark results exhibit lower average error and better timing
+accuracy.
+.Sp
+You can now run tests for \fIn\fR seconds instead of guessing the right
+number of tests to run: e.g., timethese(\-5, ...) will run each 
+code for at least 5 CPU seconds.  Zero as the "number of repetitions"
+means "for at least 3 CPU seconds".  The output format has also
+changed.  For example:
+.Sp
+.Vb 1
+\&   use Benchmark;$x=3;timethese(\-5,{a=>sub{$x*$x},b=>sub{$x**2}})
+.Ve
+.Sp
+will now output something like this:
+.Sp
+.Vb 3
+\&   Benchmark: running a, b, each for at least 5 CPU seconds...
+\&            a:  5 wallclock secs ( 5.77 usr +  0.00 sys =  5.77 CPU) @ 200551.91/s (n=1156516)
+\&            b:  4 wallclock secs ( 5.00 usr +  0.02 sys =  5.02 CPU) @ 159605.18/s (n=800686)
+.Ve
+.Sp
+New features: "each for at least N CPU seconds...", "wallclock secs",
+and the "@ operations/CPU second (n=operations)".
+.Sp
+\&\fBtimethese()\fR now returns a reference to a hash of Benchmark objects containing
+the test results, keyed on the names of the tests.
+.Sp
+\&\fBtimethis()\fR now returns the iterations field in the Benchmark result object
+instead of 0.
+.Sp
+\&\fBtimethese()\fR, \fBtimethis()\fR, and the new \fBcmpthese()\fR (see below) can also take
+a format specifier of 'none' to suppress output.
+.Sp
+A new function \fBcountit()\fR is just like \fBtimeit()\fR except that it takes a
+TIME instead of a COUNT.
+.Sp
+A new function \fBcmpthese()\fR prints a chart comparing the results of each test
+returned from a \fBtimethese()\fR call.  For each possible pair of tests, the
+percentage speed difference (iters/sec or seconds/iter) is shown.
+.Sp
+For other details, see Benchmark.
+.IP ByteLoader 4
+.IX Item "ByteLoader"
+The ByteLoader is a dedicated extension to generate and run
+Perl bytecode.  See ByteLoader.
+.IP constant 4
+.IX Item "constant"
+References can now be used.
+.Sp
+The new version also allows a leading underscore in constant names, but
+disallows a double leading underscore (as in "_\|_LINE_\|_").  Some other names
+are disallowed or warned against, including BEGIN, END, etc.  Some names
+which were forced into main:: used to fail silently in some cases; now they're
+fatal (outside of main::) and an optional warning (inside of main::).
+The ability to detect whether a constant had been set with a given name has
+been added.
+.Sp
+See constant.
+.IP charnames 4
+.IX Item "charnames"
+This pragma implements the \f(CW\*(C`\eN\*(C'\fR string escape.  See charnames.
+.IP Data::Dumper 4
+.IX Item "Data::Dumper"
+A \f(CW\*(C`Maxdepth\*(C'\fR setting can be specified to avoid venturing
+too deeply into deep data structures.  See Data::Dumper.
+.Sp
+The XSUB implementation of \fBDump()\fR is now automatically called if the
+\&\f(CW\*(C`Useqq\*(C'\fR setting is not in use.
+.Sp
+Dumping \f(CW\*(C`qr//\*(C'\fR objects works correctly.
+.IP DB 4
+.IX Item "DB"
+\&\f(CW\*(C`DB\*(C'\fR is an experimental module that exposes a clean abstraction
+to Perl's debugging API.
+.IP DB_File 4
+.IX Item "DB_File"
+DB_File can now be built with Berkeley DB versions 1, 2 or 3.
+See \f(CW\*(C`ext/DB_File/Changes\*(C'\fR.
+.IP Devel::DProf 4
+.IX Item "Devel::DProf"
+Devel::DProf, a Perl source code profiler has been added.  See
+Devel::DProf and dprofpp.
+.IP Devel::Peek 4
+.IX Item "Devel::Peek"
+The Devel::Peek module provides access to the internal representation
+of Perl variables and data.  It is a data debugging tool for the XS programmer.
+.IP Dumpvalue 4
+.IX Item "Dumpvalue"
+The Dumpvalue module provides screen dumps of Perl data.
+.IP DynaLoader 4
+.IX Item "DynaLoader"
+DynaLoader now supports a \fBdl_unload_file()\fR function on platforms that
+support unloading shared objects using \fBdlclose()\fR.
+.Sp
+Perl can also optionally arrange to unload all extension shared objects
+loaded by Perl.  To enable this, build Perl with the Configure option
+\&\f(CW\*(C`\-Accflags=\-DDL_UNLOAD_ALL_AT_EXIT\*(C'\fR.  (This maybe useful if you are
+using Apache with mod_perl.)
+.IP English 4
+.IX Item "English"
+\&\f(CW$PERL_VERSION\fR now stands for \f(CW$^V\fR (a string value) rather than for \f(CW$]\fR
+(a numeric value).
+.IP Env 4
+.IX Item "Env"
+Env now supports accessing environment variables like PATH as array
+variables.
+.IP Fcntl 4
+.IX Item "Fcntl"
+More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
+large file (more than 4GB) access (NOTE: the O_LARGEFILE is
+automatically added to \fBsysopen()\fR flags if large file support has been
+configured, as is the default), Free/Net/OpenBSD locking behaviour
+flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined
+mask of O_RDONLY, O_WRONLY, and O_RDWR.  The \fBseek()\fR/\fBsysseek()\fR
+constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the
+\&\f(CW\*(C`:seek\*(C'\fR tag.  The \fBchmod()\fR/\fBstat()\fR S_IF* constants and S_IS* functions
+are available via the \f(CW\*(C`:mode\*(C'\fR tag.
+.IP File::Compare 4
+.IX Item "File::Compare"
+A \fBcompare_text()\fR function has been added, which allows custom
+comparison functions.  See File::Compare.
+.IP File::Find 4
+.IX Item "File::Find"
+File::Find now works correctly when the \fBwanted()\fR function is either
+autoloaded or is a symbolic reference.
+.Sp
+A bug that caused File::Find to lose track of the working directory
+when pruning top-level directories has been fixed.
+.Sp
+File::Find now also supports several other options to control its
+behavior.  It can follow symbolic links if the \f(CW\*(C`follow\*(C'\fR option is
+specified.  Enabling the \f(CW\*(C`no_chdir\*(C'\fR option will make File::Find skip
+changing the current directory when walking directories.  The \f(CW\*(C`untaint\*(C'\fR
+flag can be useful when running with taint checks enabled.
+.Sp
+See File::Find.
+.IP File::Glob 4
+.IX Item "File::Glob"
+This extension implements BSD-style file globbing.  By default,
+it will also be used for the internal implementation of the \fBglob()\fR
+operator.  See File::Glob.
+.IP File::Spec 4
+.IX Item "File::Spec"
+New methods have been added to the File::Spec module: \fBdevnull()\fR returns
+the name of the null device (/dev/null on Unix) and \fBtmpdir()\fR the name of
+the temp directory (normally /tmp on Unix).  There are now also methods
+to convert between absolute and relative filenames: \fBabs2rel()\fR and
+\&\fBrel2abs()\fR.  For compatibility with operating systems that specify volume
+names in file paths, the \fBsplitpath()\fR, \fBsplitdir()\fR, and \fBcatdir()\fR methods
+have been added.
+.IP File::Spec::Functions 4
+.IX Item "File::Spec::Functions"
+The new File::Spec::Functions modules provides a function interface
+to the File::Spec module.  Allows shorthand
+.Sp
+.Vb 1
+\&    $fullname = catfile($dir1, $dir2, $file);
+.Ve
+.Sp
+instead of
+.Sp
+.Vb 1
+\&    $fullname = File::Spec\->catfile($dir1, $dir2, $file);
+.Ve
+.IP Getopt::Long 4
+.IX Item "Getopt::Long"
+Getopt::Long licensing has changed to allow the Perl Artistic License
+as well as the GPL. It used to be GPL only, which got in the way of
+non-GPL applications that wanted to use Getopt::Long.
+.Sp
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
+.Sp
+.Vb 7
+\&    use Getopt::Long;
+\&    use Pod::Usage;
+\&    my $man = 0;
+\&    my $help = 0;
+\&    GetOptions(\*(Aqhelp|?\*(Aq => \e$help, man => \e$man) or pod2usage(2);
+\&    pod2usage(1) if $help;
+\&    pod2usage(\-exitstatus => 0, \-verbose => 2) if $man;
+\&
+\&    _\|_END_\|_
+\&
+\&    =head1 NAME
+\&
+\&    sample \- Using Getopt::Long and Pod::Usage
+\&
+\&    =head1 SYNOPSIS
+\&
+\&    sample [options] [file ...]
+\&
+\&     Options:
+\&       \-help            brief help message
+\&       \-man             full documentation
+\&
+\&    =head1 OPTIONS
+\&
+\&    =over 8
+\&
+\&    =item B<\-help>
+\&
+\&    Print a brief help message and exits.
+\&
+\&    =item B<\-man>
+\&
+\&    Prints the manual page and exits.
+\&
+\&    =back
+\&
+\&    =head1 DESCRIPTION
+\&
+\&    B<This program> will read the given input file(s) and do something
+\&    useful with the contents thereof.
+\&
+\&    =cut
+.Ve
+.Sp
+See Pod::Usage for details.
+.Sp
+A bug that prevented the non-option call-back <> from being
+specified as the first argument has been fixed.
+.Sp
+To specify the characters < and > as option starters, use ><. Note,
+however, that changing option starters is strongly deprecated.
+.IP IO 4
+.IX Item "IO"
+\&\fBwrite()\fR and \fBsyswrite()\fR will now accept a single-argument
+form of the call, for consistency with Perl's \fBsyswrite()\fR.
+.Sp
+You can now create a TCP-based IO::Socket::INET without forcing
+a connect attempt.  This allows you to configure its options
+(like making it non-blocking) and then call \fBconnect()\fR manually.
+.Sp
+A bug that prevented the \fBIO::Socket::protocol()\fR accessor
+from ever returning the correct value has been corrected.
+.Sp
+IO::Socket::connect now uses non-blocking IO instead of \fBalarm()\fR
+to do connect timeouts.
+.Sp
+IO::Socket::accept now uses \fBselect()\fR instead of \fBalarm()\fR for doing
+timeouts.
+.Sp
+IO::Socket::INET\->new now sets $! correctly on failure. $@ is
+still set for backwards compatibility.
+.IP JPL 4
+.IX Item "JPL"
+Java Perl Lingo is now distributed with Perl.  See jpl/README
+for more information.
+.IP lib 4
+.IX Item "lib"
+\&\f(CW\*(C`use lib\*(C'\fR now weeds out any trailing duplicate entries.
+\&\f(CW\*(C`no lib\*(C'\fR removes all named entries.
+.IP Math::BigInt 4
+.IX Item "Math::BigInt"
+The bitwise operations \f(CW\*(C`<<\*(C'\fR, \f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR,
+and \f(CW\*(C`~\*(C'\fR are now supported on bigints.
+.IP Math::Complex 4
+.IX Item "Math::Complex"
+The accessor methods Re, Im, arg, abs, rho, and theta can now also
+act as mutators (accessor \f(CW$z\fR\->\fBRe()\fR, mutator \f(CW$z\fR\->\fBRe\fR\|(3)).
+.Sp
+The class method \f(CW\*(C`display_format\*(C'\fR and the corresponding object method
+\&\f(CW\*(C`display_format\*(C'\fR, in addition to accepting just one argument, now can
+also accept a parameter hash.  Recognized keys of a parameter hash are
+\&\f(CW"style"\fR, which corresponds to the old one parameter case, and two
+new parameters: \f(CW"format"\fR, which is a \fBprintf()\fR\-style format string
+(defaults usually to \f(CW"%.15g"\fR, you can revert to the default by
+setting the format string to \f(CW\*(C`undef\*(C'\fR) used for both parts of a
+complex number, and \f(CW"polar_pretty_print"\fR (defaults to true),
+which controls whether an attempt is made to try to recognize small
+multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a
+polar complex number.
+.Sp
+The potentially disruptive change is that in list context both methods
+now \fIreturn the parameter hash\fR, instead of only the value of the
+\&\f(CW"style"\fR parameter.
+.IP Math::Trig 4
+.IX Item "Math::Trig"
+A little bit of radial trigonometry (cylindrical and spherical),
+radial coordinate conversions, and the great circle distance were added.
+.IP "Pod::Parser, Pod::InputObjects" 4
+.IX Item "Pod::Parser, Pod::InputObjects"
+Pod::Parser is a base class for parsing and selecting sections of
+pod documentation from an input stream.  This module takes care of
+identifying pod paragraphs and commands in the input and hands off the
+parsed paragraphs and commands to user-defined methods which are free
+to interpret or translate them as they see fit.
+.Sp
+Pod::InputObjects defines some input objects needed by Pod::Parser, and
+for advanced users of Pod::Parser that need more about a command besides
+its name and text.
+.Sp
+As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned
+"base parser code" recommended for use by all pod2xxx translators.
+Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted
+to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already
+underway.  For any questions or comments about pod parsing and translating
+issues and utilities, please use the pod\-people@perl.org mailing list.
+.Sp
+For further information, please see Pod::Parser and Pod::InputObjects.
+.IP "Pod::Checker, podchecker" 4
+.IX Item "Pod::Checker, podchecker"
+This utility checks pod files for correct syntax, according to
+perlpod.  Obvious errors are flagged as such, while warnings are
+printed for mistakes that can be handled gracefully.  The checklist is
+not complete yet.  See Pod::Checker.
+.IP "Pod::ParseUtils, Pod::Find" 4
+.IX Item "Pod::ParseUtils, Pod::Find"
+These modules provide a set of gizmos that are useful mainly for pod
+translators.  Pod::Find traverses directory structures and
+returns found pod files, along with their canonical names (like
+\&\f(CW\*(C`File::Spec::Unix\*(C'\fR).  Pod::ParseUtils contains
+\&\fBPod::List\fR (useful for storing pod list information), \fBPod::Hyperlink\fR
+(for parsing the contents of \f(CW\*(C`L<>\*(C'\fR sequences) and \fBPod::Cache\fR
+(for caching information about pod files, e.g., link nodes).
+.IP "Pod::Select, podselect" 4
+.IX Item "Pod::Select, podselect"
+Pod::Select is a subclass of Pod::Parser which provides a function
+named "\fBpodselect()\fR" to filter out user-specified sections of raw pod
+documentation from an input stream. podselect is a script that provides
+access to Pod::Select from other scripts to be used as a filter.
+See Pod::Select.
+.IP "Pod::Usage, pod2usage" 4
+.IX Item "Pod::Usage, pod2usage"
+Pod::Usage provides the function "\fBpod2usage()\fR" to print usage messages for
+a Perl script based on its embedded pod documentation.  The \fBpod2usage()\fR
+function is generally useful to all script authors since it lets them
+write and maintain a single source (the pods) for documentation, thus
+removing the need to create and maintain redundant usage message text
+consisting of information already in the pods.
+.Sp
+There is also a pod2usage script which can be used from other kinds of
+scripts to print usage messages from pods (even for non-Perl scripts
+with pods embedded in comments).
+.Sp
+For details and examples, please see Pod::Usage.
+.IP "Pod::Text and Pod::Man" 4
+.IX Item "Pod::Text and Pod::Man"
+Pod::Text has been rewritten to use Pod::Parser.  While \fBpod2text()\fR is
+still available for backwards compatibility, the module now has a new
+preferred interface.  See Pod::Text for the details.  The new Pod::Text
+module is easily subclassed for tweaks to the output, and two such
+subclasses (Pod::Text::Termcap for man-page-style bold and underlining
+using termcap information, and Pod::Text::Color for markup with ANSI color
+sequences) are now standard.
+.Sp
+pod2man has been turned into a module, Pod::Man, which also uses
+Pod::Parser.  In the process, several outstanding bugs related to quotes
+in section headers, quoting of code escapes, and nested lists have been
+fixed.  pod2man is now a wrapper script around this module.
+.IP SDBM_File 4
+.IX Item "SDBM_File"
+An EXISTS method has been added to this module (and \fBsdbm_exists()\fR has
+been added to the underlying sdbm library), so one can now call exists
+on an SDBM_File tied hash and get the correct result, rather than a
+runtime error.
+.Sp
+A bug that may have caused data loss when more than one disk block
+happens to be read from the database in a single \fBFETCH()\fR has been
+fixed.
+.IP Sys::Syslog 4
+.IX Item "Sys::Syslog"
+Sys::Syslog now uses XSUBs to access facilities from syslog.h so it
+no longer requires syslog.ph to exist.
+.IP Sys::Hostname 4
+.IX Item "Sys::Hostname"
+Sys::Hostname now uses XSUBs to call the C library's \fBgethostname()\fR or
+\&\fBuname()\fR if they exist.
+.IP Term::ANSIColor 4
+.IX Item "Term::ANSIColor"
+Term::ANSIColor is a very simple module to provide easy and readable
+access to the ANSI color and highlighting escape sequences, supported by
+most ANSI terminal emulators.  It is now included standard.
+.IP Time::Local 4
+.IX Item "Time::Local"
+The \fBtimelocal()\fR and \fBtimegm()\fR functions used to silently return bogus
+results when the date fell outside the machine's integer range.  They
+now consistently \fBcroak()\fR if the date falls in an unsupported range.
+.IP Win32 4
+.IX Item "Win32"
+The error return value in list context has been changed for all functions
+that return a list of values.  Previously these functions returned a list
+with a single element \f(CW\*(C`undef\*(C'\fR if an error occurred.  Now these functions
+return the empty list in these situations.  This applies to the following
+functions:
+.Sp
+.Vb 2
+\&    Win32::FsType
+\&    Win32::GetOSVersion
+.Ve
+.Sp
+The remaining functions are unchanged and continue to return \f(CW\*(C`undef\*(C'\fR on
+error even in list context.
+.Sp
+The Win32::SetLastError(ERROR) function has been added as a complement
+to the \fBWin32::GetLastError()\fR function.
+.Sp
+The new Win32::GetFullPathName(FILENAME) returns the full absolute
+pathname for FILENAME in scalar context.  In list context it returns
+a two-element list containing the fully qualified directory name and
+the filename.  See Win32.
+.IP XSLoader 4
+.IX Item "XSLoader"
+The XSLoader extension is a simpler alternative to DynaLoader.
+See XSLoader.
+.IP "DBM Filters" 4
+.IX Item "DBM Filters"
+A new feature called "DBM Filters" has been added to all the
+DBM modules\-\-DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File.
+DBM Filters add four new methods to each DBM module:
+.Sp
+.Vb 4
+\&    filter_store_key
+\&    filter_store_value
+\&    filter_fetch_key
+\&    filter_fetch_value
+.Ve
+.Sp
+These can be used to filter key-value pairs before the pairs are
+written to the database or just after they are read from the database.
+See perldbmfilter for further information.
+.SS Pragmata
+.IX Subsection "Pragmata"
+\&\f(CW\*(C`use attrs\*(C'\fR is now obsolete, and is only provided for
+backward-compatibility.  It's been replaced by the \f(CW\*(C`sub : attributes\*(C'\fR
+syntax.  See "Subroutine Attributes" in perlsub and attributes.
+.PP
+Lexical warnings pragma, \f(CW\*(C`use warnings;\*(C'\fR, to control optional warnings.
+See perllexwarn.
+.PP
+\&\f(CW\*(C`use filetest\*(C'\fR to control the behaviour of filetests (\f(CW\*(C`\-r\*(C'\fR \f(CW\*(C`\-w\*(C'\fR
+\&...).  Currently only one subpragma implemented, "use filetest
+\&'access';", that uses \fBaccess\fR\|(2) or equivalent to check permissions
+instead of using \fBstat\fR\|(2) as usual.  This matters in filesystems
+where there are ACLs (access control lists): the \fBstat\fR\|(2) might lie,
+but \fBaccess\fR\|(2) knows better.
+.PP
+The \f(CW\*(C`open\*(C'\fR pragma can be used to specify default disciplines for
+handle constructors (e.g. \fBopen()\fR) and for qx//.  The two
+pseudo-disciplines \f(CW\*(C`:raw\*(C'\fR and \f(CW\*(C`:crlf\*(C'\fR are currently supported on
+DOS-derivative platforms (i.e. where binmode is not a no-op).
+See also "\fBbinmode()\fR can be used to set :crlf and :raw modes".
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS dprofpp
+.IX Subsection "dprofpp"
+\&\f(CW\*(C`dprofpp\*(C'\fR is used to display profile data generated using \f(CW\*(C`Devel::DProf\*(C'\fR.
+See dprofpp.
+.SS find2perl
+.IX Subsection "find2perl"
+The \f(CW\*(C`find2perl\*(C'\fR utility now uses the enhanced features of the File::Find
+module.  The \-depth and \-follow options are supported.  Pod documentation
+is also included in the script.
+.SS h2xs
+.IX Subsection "h2xs"
+The \f(CW\*(C`h2xs\*(C'\fR tool can now work in conjunction with \f(CW\*(C`C::Scan\*(C'\fR (available
+from CPAN) to automatically parse real-life header files.  The \f(CW\*(C`\-M\*(C'\fR,
+\&\f(CW\*(C`\-a\*(C'\fR, \f(CW\*(C`\-k\*(C'\fR, and \f(CW\*(C`\-o\*(C'\fR options are new.
+.SS perlcc
+.IX Subsection "perlcc"
+\&\f(CW\*(C`perlcc\*(C'\fR now supports the C and Bytecode backends.  By default,
+it generates output from the simple C backend rather than the
+optimized C backend.
+.PP
+Support for non-Unix platforms has been improved.
+.SS perldoc
+.IX Subsection "perldoc"
+\&\f(CW\*(C`perldoc\*(C'\fR has been reworked to avoid possible security holes.
+It will not by default let itself be run as the superuser, but you
+may still use the \fB\-U\fR switch to try to make it drop privileges
+first.
+.SS "The Perl Debugger"
+.IX Subsection "The Perl Debugger"
+Many bug fixes and enhancements were added to \fIperl5db.pl\fR, the
+Perl debugger.  The help documentation was rearranged.  New commands
+include \f(CW\*(C`< ?\*(C'\fR, \f(CW\*(C`> ?\*(C'\fR, and \f(CW\*(C`{ ?\*(C'\fR to list out current
+actions, \f(CW\*(C`man \fR\f(CIdocpage\fR\f(CW\*(C'\fR to run your doc viewer on some perl
+docset, and support for quoted options.  The help information was
+rearranged, and should be viewable once again if you're using \fBless\fR
+as your pager.  A serious security hole was plugged\-\-you should
+immediately remove all older versions of the Perl debugger as
+installed in previous releases, all the way back to perl3, from
+your system to avoid being bitten by this.
+.SH "Improved Documentation"
+.IX Header "Improved Documentation"
+Many of the platform-specific README files are now part of the perl
+installation.  See perl for the complete list.
+.IP perlapi.pod 4
+.IX Item "perlapi.pod"
+The official list of public Perl API functions.
+.IP perlboot.pod 4
+.IX Item "perlboot.pod"
+A tutorial for beginners on object-oriented Perl.
+.IP perlcompile.pod 4
+.IX Item "perlcompile.pod"
+An introduction to using the Perl Compiler suite.
+.IP perldbmfilter.pod 4
+.IX Item "perldbmfilter.pod"
+A howto document on using the DBM filter facility.
+.IP perldebug.pod 4
+.IX Item "perldebug.pod"
+All material unrelated to running the Perl debugger, plus all
+low-level guts-like details that risked crushing the casual user
+of the debugger, have been relocated from the old manpage to the
+next entry below.
+.IP perldebguts.pod 4
+.IX Item "perldebguts.pod"
+This new manpage contains excessively low-level material not related
+to the Perl debugger, but slightly related to debugging Perl itself.
+It also contains some arcane internal details of how the debugging
+process works that may only be of interest to developers of Perl
+debuggers.
+.IP perlfork.pod 4
+.IX Item "perlfork.pod"
+Notes on the \fBfork()\fR emulation currently available for the Windows platform.
+.IP perlfilter.pod 4
+.IX Item "perlfilter.pod"
+An introduction to writing Perl source filters.
+.IP perlhack.pod 4
+.IX Item "perlhack.pod"
+Some guidelines for hacking the Perl source code.
+.IP perlintern.pod 4
+.IX Item "perlintern.pod"
+A list of internal functions in the Perl source code.
+(List is currently empty.)
+.IP perllexwarn.pod 4
+.IX Item "perllexwarn.pod"
+Introduction and reference information about lexically scoped
+warning categories.
+.IP perlnumber.pod 4
+.IX Item "perlnumber.pod"
+Detailed information about numbers as they are represented in Perl.
+.IP perlopentut.pod 4
+.IX Item "perlopentut.pod"
+A tutorial on using \fBopen()\fR effectively.
+.IP perlreftut.pod 4
+.IX Item "perlreftut.pod"
+A tutorial that introduces the essentials of references.
+.IP perltootc.pod 4
+.IX Item "perltootc.pod"
+A tutorial on managing class data for object modules.
+.IP perltodo.pod 4
+.IX Item "perltodo.pod"
+Discussion of the most often wanted features that may someday be
+supported in Perl.
+.IP perlunicode.pod 4
+.IX Item "perlunicode.pod"
+An introduction to Unicode support features in Perl.
+.SH "Performance enhancements"
+.IX Header "Performance enhancements"
+.ie n .SS "Simple \fBsort()\fP using { $a <=> $b } and the like are optimized"
+.el .SS "Simple \fBsort()\fP using { \f(CW$a\fP <=> \f(CW$b\fP } and the like are optimized"
+.IX Subsection "Simple sort() using { $a <=> $b } and the like are optimized"
+Many common \fBsort()\fR operations using a simple inlined block are now
+optimized for faster performance.
+.SS "Optimized assignments to lexical variables"
+.IX Subsection "Optimized assignments to lexical variables"
+Certain operations in the RHS of assignment statements have been
+optimized to directly set the lexical variable on the LHS,
+eliminating redundant copying overheads.
+.SS "Faster subroutine calls"
+.IX Subsection "Faster subroutine calls"
+Minor changes in how subroutine calls are handled internally
+provide marginal improvements in performance.
+.SS "\fBdelete()\fP, \fBeach()\fP, \fBvalues()\fP and hash iteration are faster"
+.IX Subsection "delete(), each(), values() and hash iteration are faster"
+The hash values returned by \fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hashes in a
+list context are the actual values in the hash, instead of copies.
+This results in significantly better performance, because it eliminates
+needless copying in most situations.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "\-Dusethreads means something different"
+.IX Subsection "-Dusethreads means something different"
+The \-Dusethreads flag now enables the experimental interpreter-based thread
+support by default.  To get the flavor of experimental threads that was in
+5.005 instead, you need to run Configure with "\-Dusethreads \-Duse5005threads".
+.PP
+As of v5.6.0, interpreter-threads support is still lacking a way to
+create new threads from Perl (i.e., \f(CW\*(C`use Thread;\*(C'\fR will not work with
+interpreter threads).  \f(CW\*(C`use Thread;\*(C'\fR continues to be available when you
+specify the \-Duse5005threads option to Configure, bugs and all.
+.PP
+.Vb 2
+\&    NOTE: Support for threads continues to be an experimental feature.
+\&    Interfaces and implementation are subject to sudden and drastic changes.
+.Ve
+.SS "New Configure flags"
+.IX Subsection "New Configure flags"
+The following new flags may be enabled on the Configure command line
+by running Configure with \f(CW\*(C`\-Dflag\*(C'\fR.
+.PP
+.Vb 3
+\&    usemultiplicity
+\&    usethreads useithreads      (new interpreter threads: no Perl API yet)
+\&    usethreads use5005threads   (threads as they were in 5.005)
+\&
+\&    use64bitint                 (equal to now deprecated \*(Aquse64bits\*(Aq)
+\&    use64bitall
+\&
+\&    uselongdouble
+\&    usemorebits
+\&    uselargefiles
+\&    usesocks                    (only SOCKS v5 supported)
+.Ve
+.SS "Threadedness and 64\-bitness now more daring"
+.IX Subsection "Threadedness and 64-bitness now more daring"
+The Configure options enabling the use of threads and the use of
+64\-bitness are now more daring in the sense that they no more have an
+explicit list of operating systems of known threads/64\-bit
+capabilities.  In other words: if your operating system has the
+necessary APIs and datatypes, you should be able just to go ahead and
+use them, for threads by Configure \-Dusethreads, and for 64 bits
+either explicitly by Configure \-Duse64bitint or implicitly if your
+system has 64\-bit wide datatypes.  See also "64\-bit support".
+.SS "Long Doubles"
+.IX Subsection "Long Doubles"
+Some platforms have "long doubles", floating point numbers of even
+larger range than ordinary "doubles".  To enable using long doubles for
+Perl's scalars, use \-Duselongdouble.
+.SS \-Dusemorebits
+.IX Subsection "-Dusemorebits"
+You can enable both \-Duse64bitint and \-Duselongdouble with \-Dusemorebits.
+See also "64\-bit support".
+.SS \-Duselargefiles
+.IX Subsection "-Duselargefiles"
+Some platforms support system APIs that are capable of handling large files
+(typically, files larger than two gigabytes).  Perl will try to use these
+APIs if you ask for \-Duselargefiles.
+.PP
+See "Large file support" for more information.
+.SS installusrbinperl
+.IX Subsection "installusrbinperl"
+You can use "Configure \-Uinstallusrbinperl" which causes installperl
+to skip installing perl also as /usr/bin/perl.  This is useful if you
+prefer not to modify /usr/bin for some reason or another but harmful
+because many scripts assume to find Perl in /usr/bin/perl.
+.SS "SOCKS support"
+.IX Subsection "SOCKS support"
+You can use "Configure \-Dusesocks" which causes Perl to probe
+for the SOCKS proxy protocol library (v5, not v4).  For more information
+on SOCKS, see:
+.PP
+.Vb 1
+\&    http://www.socks.nec.com/
+.Ve
+.ie n .SS """\-A"" flag"
+.el .SS "\f(CW\-A\fP flag"
+.IX Subsection "-A flag"
+You can "post-edit" the Configure variables using the Configure \f(CW\*(C`\-A\*(C'\fR
+switch.  The editing happens immediately after the platform specific
+hints files have been processed but before the actual configuration
+process starts.  Run \f(CW\*(C`Configure \-h\*(C'\fR to find out the full \f(CW\*(C`\-A\*(C'\fR syntax.
+.SS "Enhanced Installation Directories"
+.IX Subsection "Enhanced Installation Directories"
+The installation structure has been enriched to improve the support
+for maintaining multiple versions of perl, to provide locations for
+vendor-supplied modules, scripts, and manpages, and to ease maintenance
+of locally-added modules, scripts, and manpages.  See the section on
+Installation Directories in the INSTALL file for complete details.
+For most users building and installing from source, the defaults should
+be fine.
+.PP
+If you previously used \f(CW\*(C`Configure \-Dsitelib\*(C'\fR or \f(CW\*(C`\-Dsitearch\*(C'\fR to set
+special values for library directories, you might wish to consider using
+the new \f(CW\*(C`\-Dsiteprefix\*(C'\fR setting instead.  Also, if you wish to re-use a
+config.sh file from an earlier version of perl, you should be sure to
+check that Configure makes sensible choices for the new directories.
+See INSTALL for complete details.
+.SH "Platform specific changes"
+.IX Header "Platform specific changes"
+.SS "Supported platforms"
+.IX Subsection "Supported platforms"
+.IP \(bu 4
+The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread
+extension.
+.IP \(bu 4
+GNU/Hurd is now supported.
+.IP \(bu 4
+Rhapsody/Darwin is now supported.
+.IP \(bu 4
+EPOC is now supported (on Psion 5).
+.IP \(bu 4
+The cygwin port (formerly cygwin32) has been greatly improved.
+.SS DOS
+.IX Subsection "DOS"
+.IP \(bu 4
+Perl now works with djgpp 2.02 (and 2.03 alpha).
+.IP \(bu 4
+Environment variable names are not converted to uppercase any more.
+.IP \(bu 4
+Incorrect exit codes from backticks have been fixed.
+.IP \(bu 4
+This port continues to use its own builtin globbing (not File::Glob).
+.SS "OS390 (OpenEdition MVS)"
+.IX Subsection "OS390 (OpenEdition MVS)"
+Support for this EBCDIC platform has not been renewed in this release.
+There are difficulties in reconciling Perl's standardization on UTF\-8
+as its internal representation for characters with the EBCDIC character
+set, because the two are incompatible.
+.PP
+It is unclear whether future versions will renew support for this
+platform, but the possibility exists.
+.SS VMS
+.IX Subsection "VMS"
+Numerous revisions and extensions to configuration, build, testing, and
+installation process to accommodate core changes and VMS-specific options.
+.PP
+Expand \f(CW%ENV\fR\-handling code to allow runtime mapping to logical names,
+CLI symbols, and CRTL environ array.
+.PP
+Extension of subprocess invocation code to accept filespecs as command
+"verbs".
+.PP
+Add to Perl command line processing the ability to use default file types and
+to recognize Unix-style \f(CW\*(C`2>&1\*(C'\fR.
+.PP
+Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.
+.PP
+Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.
+.PP
+Barewords at start of Unix-syntax paths may be treated as text rather than
+only as logical names.
+.PP
+Optional secure translation of several logical names used internally by Perl.
+.PP
+Miscellaneous bugfixing and porting of new core code to VMS.
+.PP
+Thanks are gladly extended to the many people who have contributed VMS
+patches, testing, and ideas.
+.SS Win32
+.IX Subsection "Win32"
+Perl can now emulate \fBfork()\fR internally, using multiple interpreters running
+in different concurrent threads.  This support must be enabled at build
+time.  See perlfork for detailed information.
+.PP
+When given a pathname that consists only of a drivename, such as \f(CW\*(C`A:\*(C'\fR,
+\&\fBopendir()\fR and \fBstat()\fR now use the current working directory for the drive
+rather than the drive root.
+.PP
+The builtin XSUB functions in the Win32:: namespace are documented.  See
+Win32.
+.PP
+$^X now contains the full path name of the running executable.
+.PP
+A \fBWin32::GetLongPathName()\fR function is provided to complement
+\&\fBWin32::GetFullPathName()\fR and \fBWin32::GetShortPathName()\fR.  See Win32.
+.PP
+\&\fBPOSIX::uname()\fR is supported.
+.PP
+system(1,...) now returns true process IDs rather than process
+handles.  \fBkill()\fR accepts any real process id, rather than strictly
+return values from system(1,...).
+.PP
+For better compatibility with Unix, \f(CW\*(C`kill(0, $pid)\*(C'\fR can now be used to
+test whether a process exists.
+.PP
+The \f(CW\*(C`Shell\*(C'\fR module is supported.
+.PP
+Better support for building Perl under command.com in Windows 95
+has been added.
+.PP
+Scripts are read in binary mode by default to allow ByteLoader (and
+the filter mechanism in general) to work properly.  For compatibility,
+the DATA filehandle will be set to text mode if a carriage return is
+detected at the end of the line containing the _\|_END_\|_ or _\|_DATA_\|_
+token; if not, the DATA filehandle will be left open in binary mode.
+Earlier versions always opened the DATA filehandle in text mode.
+.PP
+The \fBglob()\fR operator is implemented via the \f(CW\*(C`File::Glob\*(C'\fR extension,
+which supports glob syntax of the C shell.  This increases the flexibility
+of the \fBglob()\fR operator, but there may be compatibility issues for
+programs that relied on the older globbing syntax.  If you want to
+preserve compatibility with the older syntax, you might want to run
+perl with \f(CW\*(C`\-MFile::DosGlob\*(C'\fR.  For details and compatibility information,
+see File::Glob.
+.SH "Significant bug fixes"
+.IX Header "Significant bug fixes"
+.SS "<HANDLE> on empty files"
+.IX Subsection "<HANDLE> on empty files"
+With \f(CW$/\fR set to \f(CW\*(C`undef\*(C'\fR, "slurping" an empty file returns a string of
+zero length (instead of \f(CW\*(C`undef\*(C'\fR, as it used to) the first time the
+HANDLE is read after \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR.  Further reads yield
+\&\f(CW\*(C`undef\*(C'\fR.
+.PP
+This means that the following will append "foo" to an empty file (it used
+to do nothing):
+.PP
+.Vb 1
+\&    perl \-0777 \-pi \-e \*(Aqs/^/foo/\*(Aq empty_file
+.Ve
+.PP
+The behaviour of:
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqs/^/foo/\*(Aq empty_file
+.Ve
+.PP
+is unchanged (it continues to leave the file empty).
+.ie n .SS """eval \*(Aq...\*(Aq"" improvements"
+.el .SS "\f(CWeval \*(Aq...\*(Aq\fP improvements"
+.IX Subsection "eval ... improvements"
+Line numbers (as reflected by \fBcaller()\fR and most diagnostics) within
+\&\f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR were often incorrect where here documents were involved.
+This has been corrected.
+.PP
+Lexical lookups for variables appearing in \f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR within
+functions that were themselves called within an \f(CW\*(C`eval \*(Aq...\*(Aq\*(C'\fR were
+searching the wrong place for lexicals.  The lexical search now
+correctly ends at the subroutine's block boundary.
+.PP
+The use of \f(CW\*(C`return\*(C'\fR within \f(CW\*(C`eval {...}\*(C'\fR caused $@ not to be reset
+correctly when no exception occurred within the eval.  This has
+been fixed.
+.PP
+Parsing of here documents used to be flawed when they appeared as
+the replacement expression in \f(CW\*(C`eval \*(Aqs/.../.../e\*(Aq\*(C'\fR.  This has
+been fixed.
+.SS "All compilation errors are true errors"
+.IX Subsection "All compilation errors are true errors"
+Some "errors" encountered at compile time were by necessity 
+generated as warnings followed by eventual termination of the
+program.  This enabled more such errors to be reported in a
+single run, rather than causing a hard stop at the first error
+that was encountered.
+.PP
+The mechanism for reporting such errors has been reimplemented
+to queue compile-time errors and report them at the end of the
+compilation as true errors rather than as warnings.  This fixes
+cases where error messages leaked through in the form of warnings
+when code was compiled at run time using \f(CW\*(C`eval STRING\*(C'\fR, and
+also allows such errors to be reliably trapped using \f(CW\*(C`eval "..."\*(C'\fR.
+.SS "Implicitly closed filehandles are safer"
+.IX Subsection "Implicitly closed filehandles are safer"
+Sometimes implicitly closed filehandles (as when they are localized,
+and Perl automatically closes them on exiting the scope) could
+inadvertently set $? or $!.  This has been corrected.
+.SS "Behavior of list slices is more consistent"
+.IX Subsection "Behavior of list slices is more consistent"
+When taking a slice of a literal list (as opposed to a slice of
+an array or hash), Perl used to return an empty list if the
+result happened to be composed of all undef values.
+.PP
+The new behavior is to produce an empty list if (and only if)
+the original list was empty.  Consider the following example:
+.PP
+.Vb 1
+\&    @a = (1,undef,undef,2)[2,1,2];
+.Ve
+.PP
+The old behavior would have resulted in \f(CW@a\fR having no elements.
+The new behavior ensures it has three undefined elements.
+.PP
+Note in particular that the behavior of slices of the following
+cases remains unchanged:
+.PP
+.Vb 5
+\&    @a = ()[1,2];
+\&    @a = (getpwent)[7,0];
+\&    @a = (anything_returning_empty_list())[2,1,2];
+\&    @a = @b[2,1,2];
+\&    @a = @c{\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq};
+.Ve
+.PP
+See perldata.
+.ie n .SS """(\e$)"" prototype and $foo{a}"
+.el .SS "\f(CW(\e$)\fP prototype and \f(CW$foo{a}\fP"
+.IX Subsection "($) prototype and $foo{a}"
+A scalar reference prototype now correctly allows a hash or
+array element in that slot.
+.ie n .SS """goto &sub"" and AUTOLOAD"
+.el .SS "\f(CWgoto &sub\fP and AUTOLOAD"
+.IX Subsection "goto &sub and AUTOLOAD"
+The \f(CW\*(C`goto &sub\*(C'\fR construct works correctly when \f(CW&sub\fR happens
+to be autoloaded.
+.ie n .SS """\-bareword"" allowed under ""use integer"""
+.el .SS "\f(CW\-bareword\fP allowed under \f(CWuse integer\fP"
+.IX Subsection "-bareword allowed under use integer"
+The autoquoting of barewords preceded by \f(CW\*(C`\-\*(C'\fR did not work
+in prior versions when the \f(CW\*(C`integer\*(C'\fR pragma was enabled.
+This has been fixed.
+.SS "Failures in \fBDESTROY()\fP"
+.IX Subsection "Failures in DESTROY()"
+When code in a destructor threw an exception, it went unnoticed
+in earlier versions of Perl, unless someone happened to be
+looking in $@ just after the point the destructor happened to
+run.  Such failures are now visible as warnings when warnings are
+enabled.
+.SS "Locale bugs fixed"
+.IX Subsection "Locale bugs fixed"
+\&\fBprintf()\fR and \fBsprintf()\fR previously reset the numeric locale
+back to the default "C" locale.  This has been fixed.
+.PP
+Numbers formatted according to the local numeric locale
+(such as using a decimal comma instead of a decimal dot) caused
+"isn't numeric" warnings, even while the operations accessing
+those numbers produced correct results.  These warnings have been
+discontinued.
+.SS "Memory leaks"
+.IX Subsection "Memory leaks"
+The \f(CW\*(C`eval \*(Aqreturn sub {...}\*(Aq\*(C'\fR construct could sometimes leak
+memory.  This has been fixed.
+.PP
+Operations that aren't filehandle constructors used to leak memory
+when used on invalid filehandles.  This has been fixed.
+.PP
+Constructs that modified \f(CW@_\fR could fail to deallocate values
+in \f(CW@_\fR and thus leak memory.  This has been corrected.
+.SS "Spurious subroutine stubs after failed subroutine calls"
+.IX Subsection "Spurious subroutine stubs after failed subroutine calls"
+Perl could sometimes create empty subroutine stubs when a
+subroutine was not found in the package.  Such cases stopped
+later method lookups from progressing into base packages.
+This has been corrected.
+.ie n .SS "Taint failures under ""\-U"""
+.el .SS "Taint failures under \f(CW\-U\fP"
+.IX Subsection "Taint failures under -U"
+When running in unsafe mode, taint violations could sometimes
+cause silent failures.  This has been fixed.
+.ie n .SS "END blocks and the ""\-c"" switch"
+.el .SS "END blocks and the \f(CW\-c\fP switch"
+.IX Subsection "END blocks and the -c switch"
+Prior versions used to run BEGIN \fBand\fR END blocks when Perl was
+run in compile-only mode.  Since this is typically not the expected
+behavior, END blocks are not executed anymore when the \f(CW\*(C`\-c\*(C'\fR switch
+is used, or if compilation fails.
+.PP
+See "Support for CHECK blocks" for how to run things when the compile 
+phase ends.
+.SS "Potential to leak DATA filehandles"
+.IX Subsection "Potential to leak DATA filehandles"
+Using the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR token creates an implicit filehandle to
+the file that contains the token.  It is the program's
+responsibility to close it when it is done reading from it.
+.PP
+This caveat is now better explained in the documentation.
+See perldata.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.ie n .IP """%s"" variable %s masks earlier declaration in same %s" 4
+.el .IP """%s"" variable \f(CW%s\fR masks earlier declaration in same \f(CW%s\fR" 4
+.IX Item """%s"" variable %s masks earlier declaration in same %s"
+(W misc) A "my" or "our" variable has been redeclared in the current scope or statement,
+effectively eliminating all access to the previous instance.  This is almost
+always a typographical error.  Note that the earlier variable will still exist
+until the end of the scope or until all closure referents to it are
+destroyed.
+.IP """my sub"" not yet implemented" 4
+.IX Item """my sub"" not yet implemented"
+(F) Lexically scoped subroutines are not yet implemented.  Don't try that
+yet.
+.ie n .IP """our"" variable %s redeclared" 4
+.el .IP """our"" variable \f(CW%s\fR redeclared" 4
+.IX Item """our"" variable %s redeclared"
+(W misc) You seem to have already declared the same global once before in the
+current lexical scope.
+.ie n .IP "'!' allowed only after types %s" 4
+.el .IP "'!' allowed only after types \f(CW%s\fR" 4
+.IX Item "'!' allowed only after types %s"
+(F) The '!' is allowed in \fBpack()\fR and \fBunpack()\fR only after certain types.
+See "pack" in perlfunc.
+.IP "/ cannot take a count" 4
+.IX Item "/ cannot take a count"
+(F) You had an unpack template indicating a counted-length string,
+but you have also specified an explicit size for the string.
+See "pack" in perlfunc.
+.IP "/ must be followed by a, A or Z" 4
+.IX Item "/ must be followed by a, A or Z"
+(F) You had an unpack template indicating a counted-length string,
+which must be followed by one of the letters a, A or Z
+to indicate what sort of string is to be unpacked.
+See "pack" in perlfunc.
+.IP "/ must be followed by a*, A* or Z*" 4
+.IX Item "/ must be followed by a*, A* or Z*"
+(F) You had a pack template indicating a counted-length string,
+Currently the only things that can have their length counted are a*, A* or Z*.
+See "pack" in perlfunc.
+.IP "/ must follow a numeric type" 4
+.IX Item "/ must follow a numeric type"
+(F) You had an unpack template that contained a '#',
+but this did not follow some numeric unpack specification.
+See "pack" in perlfunc.
+.IP "/%s/: Unrecognized escape \e\e%c passed through" 4
+.IX Item "/%s/: Unrecognized escape %c passed through"
+(W regexp) You used a backslash-character combination which is not recognized
+by Perl.  This combination appears in an interpolated variable or a
+\&\f(CW\*(C`\*(Aq\*(C'\fR\-delimited regular expression.  The character was understood literally.
+.IP "/%s/: Unrecognized escape \e\e%c in character class passed through" 4
+.IX Item "/%s/: Unrecognized escape %c in character class passed through"
+(W regexp) You used a backslash-character combination which is not recognized
+by Perl inside character classes.  The character was understood literally.
+.IP "/%s/ should probably be written as ""%s""" 4
+.IX Item "/%s/ should probably be written as ""%s"""
+(W syntax) You have used a pattern where Perl expected to find a string,
+as in the first argument to \f(CW\*(C`join\*(C'\fR.  Perl will treat the true
+or false result of matching the pattern against \f(CW$_\fR as the string,
+which is probably not what you had in mind.
+.IP "%s() called too early to check prototype" 4
+.IX Item "%s() called too early to check prototype"
+(W prototype) You've called a function that has a prototype before the parser saw a
+definition or declaration for it, and Perl could not check that the call
+conforms to the prototype.  You need to either add an early prototype
+declaration for the subroutine in question, or move the subroutine
+definition ahead of the call to get proper prototype checking.  Alternatively,
+if you are certain that you're calling the function correctly, you may put
+an ampersand before the name to avoid the warning.  See perlsub.
+.ie n .IP "%s argument is not a HASH or ARRAY element" 4
+.el .IP "\f(CW%s\fR argument is not a HASH or ARRAY element" 4
+.IX Item "%s argument is not a HASH or ARRAY element"
+(F) The argument to \fBexists()\fR must be a hash or array element, such as:
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+.Ve
+.ie n .IP "%s argument is not a HASH or ARRAY element or slice" 4
+.el .IP "\f(CW%s\fR argument is not a HASH or ARRAY element or slice" 4
+.IX Item "%s argument is not a HASH or ARRAY element or slice"
+(F) The argument to \fBdelete()\fR must be either a hash or array element, such as:
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+.Ve
+.Sp
+or a hash or array slice, such as:
+.Sp
+.Vb 2
+\&    @foo[$bar, $baz, $xyzzy]
+\&    @{$ref\->[12]}{"susie", "queue"}
+.Ve
+.ie n .IP "%s argument is not a subroutine name" 4
+.el .IP "\f(CW%s\fR argument is not a subroutine name" 4
+.IX Item "%s argument is not a subroutine name"
+(F) The argument to \fBexists()\fR for \f(CW\*(C`exists &sub\*(C'\fR must be a subroutine
+name, and not a subroutine call.  \f(CW\*(C`exists &sub()\*(C'\fR will generate this error.
+.ie n .IP "%s package attribute may clash with future reserved word: %s" 4
+.el .IP "\f(CW%s\fR package attribute may clash with future reserved word: \f(CW%s\fR" 4
+.IX Item "%s package attribute may clash with future reserved word: %s"
+(W reserved) A lowercase attribute name was used that had a package-specific handler.
+That name might have a meaning to Perl itself some day, even though it
+doesn't yet.  Perhaps you should use a mixed-case attribute name, instead.
+See attributes.
+.ie n .IP "(in cleanup) %s" 4
+.el .IP "(in cleanup) \f(CW%s\fR" 4
+.IX Item "(in cleanup) %s"
+(W misc) This prefix usually indicates that a \fBDESTROY()\fR method raised
+the indicated exception.  Since destructors are usually called by
+the system at arbitrary points during execution, and often a vast
+number of times, the warning is issued only once for any number
+of failures that would otherwise result in the same message being
+repeated.
+.Sp
+Failure of user callbacks dispatched using the \f(CW\*(C`G_KEEPERR\*(C'\fR flag
+could also result in this warning.  See "G_KEEPERR" in perlcall.
+.IP "<> should be quotes" 4
+.IX Item "<> should be quotes"
+(F) You wrote \f(CW\*(C`require <file>\*(C'\fR when you should have written
+\&\f(CW\*(C`require \*(Aqfile\*(Aq\*(C'\fR.
+.IP "Attempt to join self" 4
+.IX Item "Attempt to join self"
+(F) You tried to join a thread from within itself, which is an
+impossible task.  You may be joining the wrong thread, or you may
+need to move the \fBjoin()\fR to some other thread.
+.IP "Bad evalled substitution pattern" 4
+.IX Item "Bad evalled substitution pattern"
+(F) You've used the /e switch to evaluate the replacement for a
+substitution, but perl found a syntax error in the code to evaluate,
+most likely an unexpected right brace '}'.
+.IP "Bad \fBrealloc()\fR ignored" 4
+.IX Item "Bad realloc() ignored"
+(S) An internal routine called \fBrealloc()\fR on something that had never been
+\&\fBmalloc()\fRed in the first place. Mandatory, but can be disabled by
+setting environment variable \f(CW\*(C`PERL_BADFREE\*(C'\fR to 1.
+.IP "Bareword found in conditional" 4
+.IX Item "Bareword found in conditional"
+(W bareword) The compiler found a bareword where it expected a conditional,
+which often indicates that an || or && was parsed as part of the
+last argument of the previous construct, for example:
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.Sp
+It may also indicate a misspelled constant that has been interpreted
+as a bareword:
+.Sp
+.Vb 2
+\&    use constant TYPO => 1;
+\&    if (TYOP) { print "foo" }
+.Ve
+.Sp
+The \f(CW\*(C`strict\*(C'\fR pragma is useful in avoiding such errors.
+.IP "Binary number > 0b11111111111111111111111111111111 non-portable" 4
+.IX Item "Binary number > 0b11111111111111111111111111111111 non-portable"
+(W portable) The binary number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Bit vector size > 32 non-portable" 4
+.IX Item "Bit vector size > 32 non-portable"
+(W portable) Using bit vector sizes larger than 32 is non-portable.
+.ie n .IP "Buffer overflow in prime_env_iter: %s" 4
+.el .IP "Buffer overflow in prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Buffer overflow in prime_env_iter: %s"
+(W internal) A warning peculiar to VMS.  While Perl was preparing to iterate over
+\&\f(CW%ENV\fR, it encountered a logical name or symbol definition which was too long,
+so it was truncated to the string shown.
+.IP "Can't check filesystem of script ""%s""" 4
+.IX Item "Can't check filesystem of script ""%s"""
+(P) For some reason you can't check the filesystem of the script for nosuid.
+.ie n .IP "Can't declare class for non-scalar %s in ""%s""" 4
+.el .IP "Can't declare class for non-scalar \f(CW%s\fR in ""%s""" 4
+.IX Item "Can't declare class for non-scalar %s in ""%s"""
+(S) Currently, only scalar variables can declared with a specific class
+qualifier in a "my" or "our" declaration.  The semantics may be extended
+for other types of variables in future.
+.ie n .IP "Can't declare %s in ""%s""" 4
+.el .IP "Can't declare \f(CW%s\fR in ""%s""" 4
+.IX Item "Can't declare %s in ""%s"""
+(F) Only scalar, array, and hash variables may be declared as "my" or
+"our" variables.  They must have ordinary identifiers as names.
+.IP "Can't ignore signal CHLD, forcing to default" 4
+.IX Item "Can't ignore signal CHLD, forcing to default"
+(W signal) Perl has detected that it is being run with the SIGCHLD signal
+(sometimes known as SIGCLD) disabled.  Since disabling this signal
+will interfere with proper determination of exit status of child
+processes, Perl has reset the signal to its default value.
+This situation typically indicates that the parent program under
+which Perl may be running (e.g., cron) is being very careless.
+.IP "Can't modify non-lvalue subroutine call" 4
+.IX Item "Can't modify non-lvalue subroutine call"
+(F) Subroutines meant to be used in lvalue context should be declared as
+such, see "Lvalue subroutines" in perlsub.
+.IP "Can't read CRTL environ" 4
+.IX Item "Can't read CRTL environ"
+(S) A warning peculiar to VMS.  Perl tried to read an element of \f(CW%ENV\fR
+from the CRTL's internal environment array and discovered the array was
+missing.  You need to figure out where your CRTL misplaced its environ
+or define \fIPERL_ENV_TABLES\fR (see perlvms) so that environ is not searched.
+.ie n .IP "Can't remove %s: %s, skipping file" 4
+.el .IP "Can't remove \f(CW%s:\fR \f(CW%s\fR, skipping file" 4
+.IX Item "Can't remove %s: %s, skipping file"
+(S) You requested an inplace edit without creating a backup file.  Perl
+was unable to remove the original file to replace it with the modified
+file.  The file was left unmodified.
+.ie n .IP "Can't return %s from lvalue subroutine" 4
+.el .IP "Can't return \f(CW%s\fR from lvalue subroutine" 4
+.IX Item "Can't return %s from lvalue subroutine"
+(F) Perl detected an attempt to return illegal lvalues (such
+as temporary or readonly values) from a subroutine used as an lvalue.
+This is not allowed.
+.IP "Can't weaken a nonreference" 4
+.IX Item "Can't weaken a nonreference"
+(F) You attempted to weaken something that was not a reference.  Only
+references can be weakened.
+.IP "Character class [:%s:] unknown" 4
+.IX Item "Character class [:%s:] unknown"
+(F) The class in the character class [: :] syntax is unknown.
+See perlre.
+.IP "Character class syntax [%s] belongs inside character classes" 4
+.IX Item "Character class syntax [%s] belongs inside character classes"
+(W unsafe) The character class constructs [: :], [= =], and [. .]  go
+\&\fIinside\fR character classes, the [] are part of the construct,
+for example: /[012[:alpha:]345]/.  Note that [= =] and [. .]
+are not currently implemented; they are simply placeholders for
+future extensions.
+.ie n .IP "Constant is not %s reference" 4
+.el .IP "Constant is not \f(CW%s\fR reference" 4
+.IX Item "Constant is not %s reference"
+(F) A constant value (perhaps declared using the \f(CW\*(C`use constant\*(C'\fR pragma)
+is being dereferenced, but it amounts to the wrong type of reference.  The
+message indicates the type of reference that was expected. This usually
+indicates a syntax error in dereferencing the constant value.
+See "Constant Functions" in perlsub and constant.
+.ie n .IP "constant(%s): %s" 4
+.el .IP "constant(%s): \f(CW%s\fR" 4
+.IX Item "constant(%s): %s"
+(F) The parser found inconsistencies either while attempting to define an
+overloaded constant, or when trying to find the character name specified
+in the \f(CW\*(C`\eN{...}\*(C'\fR escape.  Perhaps you forgot to load the corresponding
+\&\f(CW\*(C`overload\*(C'\fR or \f(CW\*(C`charnames\*(C'\fR pragma?  See charnames and overload.
+.IP "CORE::%s is not a keyword" 4
+.IX Item "CORE::%s is not a keyword"
+(F) The CORE:: namespace is reserved for Perl keywords.
+.IP "defined(@array) is deprecated" 4
+.IX Item "defined(@array) is deprecated"
+(D) \fBdefined()\fR is not usually useful on arrays because it checks for an
+undefined \fIscalar\fR value.  If you want to see if the array is empty,
+just use \f(CW\*(C`if (@array) { # not empty }\*(C'\fR for example.
+.IP "defined(%hash) is deprecated" 4
+.IX Item "defined(%hash) is deprecated"
+(D) \fBdefined()\fR is not usually useful on hashes because it checks for an
+undefined \fIscalar\fR value.  If you want to see if the hash is empty,
+just use \f(CW\*(C`if (%hash) { # not empty }\*(C'\fR for example.
+.IP "Did not produce a valid header" 4
+.IX Item "Did not produce a valid header"
+See Server error.
+.IP "(Did you mean ""local"" instead of ""our""?)" 4
+.IX Item "(Did you mean ""local"" instead of ""our""?)"
+(W misc) Remember that "our" does not localize the declared global variable.
+You have declared it again in the same lexical scope, which seems superfluous.
+.IP "Document contains no data" 4
+.IX Item "Document contains no data"
+See Server error.
+.ie n .IP "entering effective %s failed" 4
+.el .IP "entering effective \f(CW%s\fR failed" 4
+.IX Item "entering effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.IP "false [] range ""%s"" in regexp" 4
+.IX Item "false [] range ""%s"" in regexp"
+(W regexp) A character class range must start and end at a literal character, not
+another character class like \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`[:alpha:]\*(C'\fR.  The "\-" in your false
+range is interpreted as a literal "\-".  Consider quoting the "\-",  "\e\-".
+See perlre.
+.ie n .IP "Filehandle %s opened only for output" 4
+.el .IP "Filehandle \f(CW%s\fR opened only for output" 4
+.IX Item "Filehandle %s opened only for output"
+(W io) You tried to read from a filehandle opened only for writing.  If you
+intended it to be a read/write filehandle, you needed to open it with
+"+<" or "+>" or "+>>" instead of with "<" or nothing.  If
+you intended only to read from the file, use "<".  See
+"open" in perlfunc.
+.ie n .IP "\fBflock()\fR on closed filehandle %s" 4
+.el .IP "\fBflock()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "flock() on closed filehandle %s"
+(W closed) The filehandle you're attempting to \fBflock()\fR got itself closed some
+time before now.  Check your logic flow.  \fBflock()\fR operates on filehandles.
+Are you attempting to call \fBflock()\fR on a dirhandle by the same name?
+.IP "Global symbol ""%s"" requires explicit package name" 4
+.IX Item "Global symbol ""%s"" requires explicit package name"
+(F) You've said "use strict vars", which indicates that all variables
+must either be lexically scoped (using "my"), declared beforehand using
+"our", or explicitly qualified to say which package the global variable
+is in (using "::").
+.IP "Hexadecimal number > 0xffffffff non-portable" 4
+.IX Item "Hexadecimal number > 0xffffffff non-portable"
+(W portable) The hexadecimal number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Ill-formed CRTL environ value ""%s""" 4
+.IX Item "Ill-formed CRTL environ value ""%s"""
+(W internal) A warning peculiar to VMS.  Perl tried to read the CRTL's internal
+environ array, and encountered an element without the \f(CW\*(C`=\*(C'\fR delimiter
+used to separate keys from values.  The element is ignored.
+.IP "Ill-formed message in prime_env_iter: |%s|" 4
+.IX Item "Ill-formed message in prime_env_iter: |%s|"
+(W internal) A warning peculiar to VMS.  Perl tried to read a logical name
+or CLI symbol definition when preparing to iterate over \f(CW%ENV\fR, and
+didn't see the expected delimiter between key and value, so the
+line was ignored.
+.ie n .IP "Illegal binary digit %s" 4
+.el .IP "Illegal binary digit \f(CW%s\fR" 4
+.IX Item "Illegal binary digit %s"
+(F) You used a digit other than 0 or 1 in a binary number.
+.ie n .IP "Illegal binary digit %s ignored" 4
+.el .IP "Illegal binary digit \f(CW%s\fR ignored" 4
+.IX Item "Illegal binary digit %s ignored"
+(W digit) You may have tried to use a digit other than 0 or 1 in a binary number.
+Interpretation of the binary number stopped before the offending digit.
+.IP "Illegal number of bits in vec" 4
+.IX Item "Illegal number of bits in vec"
+(F) The number of bits in \fBvec()\fR (the third argument) must be a power of
+two from 1 to 32 (or 64, if your platform supports that).
+.ie n .IP "Integer overflow in %s number" 4
+.el .IP "Integer overflow in \f(CW%s\fR number" 4
+.IX Item "Integer overflow in %s number"
+(W overflow) The hexadecimal, octal or binary number you have specified either
+as a literal or as an argument to \fBhex()\fR or \fBoct()\fR is too big for your
+architecture, and has been converted to a floating point number.  On a
+32\-bit architecture the largest hexadecimal, octal or binary number
+representable without overflow is 0xFFFFFFFF, 037777777777, or
+0b11111111111111111111111111111111 respectively.  Note that Perl
+transparently promotes all numbers to a floating point representation
+internally\-\-subject to loss of precision errors in subsequent
+operations.
+.ie n .IP "Invalid %s attribute: %s" 4
+.el .IP "Invalid \f(CW%s\fR attribute: \f(CW%s\fR" 4
+.IX Item "Invalid %s attribute: %s"
+The indicated attribute for a subroutine or variable was not recognized
+by Perl or by a user-supplied handler.  See attributes.
+.ie n .IP "Invalid %s attributes: %s" 4
+.el .IP "Invalid \f(CW%s\fR attributes: \f(CW%s\fR" 4
+.IX Item "Invalid %s attributes: %s"
+The indicated attributes for a subroutine or variable were not recognized
+by Perl or by a user-supplied handler.  See attributes.
+.IP "invalid [] range ""%s"" in regexp" 4
+.IX Item "invalid [] range ""%s"" in regexp"
+The offending range is now explicitly displayed.
+.ie n .IP "Invalid separator character %s in attribute list" 4
+.el .IP "Invalid separator character \f(CW%s\fR in attribute list" 4
+.IX Item "Invalid separator character %s in attribute list"
+(F) Something other than a colon or whitespace was seen between the
+elements of an attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.  See attributes.
+.ie n .IP "Invalid separator character %s in subroutine attribute list" 4
+.el .IP "Invalid separator character \f(CW%s\fR in subroutine attribute list" 4
+.IX Item "Invalid separator character %s in subroutine attribute list"
+(F) Something other than a colon or whitespace was seen between the
+elements of a subroutine attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.
+.ie n .IP "leaving effective %s failed" 4
+.el .IP "leaving effective \f(CW%s\fR failed" 4
+.IX Item "leaving effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.ie n .IP "Lvalue subs returning %s not implemented yet" 4
+.el .IP "Lvalue subs returning \f(CW%s\fR not implemented yet" 4
+.IX Item "Lvalue subs returning %s not implemented yet"
+(F) Due to limitations in the current implementation, array and hash
+values cannot be returned in subroutines used in lvalue context.
+See "Lvalue subroutines" in perlsub.
+.ie n .IP "Method %s not permitted" 4
+.el .IP "Method \f(CW%s\fR not permitted" 4
+.IX Item "Method %s not permitted"
+See Server error.
+.ie n .IP "Missing %sbrace%s on \eN{}" 4
+.el .IP "Missing \f(CW%sbrace\fR%s on \eN{}" 4
+.IX Item "Missing %sbrace%s on N{}"
+(F) Wrong syntax of character name literal \f(CW\*(C`\eN{charname}\*(C'\fR within
+double-quotish context.
+.IP "Missing command in piped open" 4
+.IX Item "Missing command in piped open"
+(W pipe) You used the \f(CW\*(C`open(FH, "| command")\*(C'\fR or \f(CW\*(C`open(FH, "command |")\*(C'\fR
+construction, but the command was missing or blank.
+.IP "Missing name in ""my sub""" 4
+.IX Item "Missing name in ""my sub"""
+(F) The reserved syntax for lexically scoped subroutines requires that they
+have a name with which they can be found.
+.ie n .IP "No %s specified for \-%c" 4
+.el .IP "No \f(CW%s\fR specified for \-%c" 4
+.IX Item "No %s specified for -%c"
+(F) The indicated command line switch needs a mandatory argument, but
+you haven't specified one.
+.ie n .IP "No package name allowed for variable %s in ""our""" 4
+.el .IP "No package name allowed for variable \f(CW%s\fR in ""our""" 4
+.IX Item "No package name allowed for variable %s in ""our"""
+(F) Fully qualified variable names are not allowed in "our" declarations,
+because that doesn't make much sense under existing semantics.  Such
+syntax is reserved for future extensions.
+.IP "No space allowed after \-%c" 4
+.IX Item "No space allowed after -%c"
+(F) The argument to the indicated command line switch must follow immediately
+after the switch, without intervening spaces.
+.IP "no UTC offset information; assuming local time is UTC" 4
+.IX Item "no UTC offset information; assuming local time is UTC"
+(S) A warning peculiar to VMS.  Perl was unable to find the local
+timezone offset, so it's assuming that local system time is equivalent
+to UTC.  If it's not, define the logical name \fISYS$TIMEZONE_DIFFERENTIAL\fR
+to translate to the number of seconds which need to be added to UTC to
+get local time.
+.IP "Octal number > 037777777777 non-portable" 4
+.IX Item "Octal number > 037777777777 non-portable"
+(W portable) The octal number you specified is larger than 2**32\-1 (4294967295)
+and therefore non-portable between systems.  See perlport for more
+on portability concerns.
+.Sp
+See also perlport for writing portable code.
+.IP "panic: del_backref" 4
+.IX Item "panic: del_backref"
+(P) Failed an internal consistency check while trying to reset a weak
+reference.
+.IP "panic: kid popen errno read" 4
+.IX Item "panic: kid popen errno read"
+(F) forked child returned an incomprehensible message about its errno.
+.IP "panic: magic_killbackrefs" 4
+.IX Item "panic: magic_killbackrefs"
+(P) Failed an internal consistency check while trying to reset all weak
+references to an object.
+.IP "Parentheses missing around ""%s"" list" 4
+.IX Item "Parentheses missing around ""%s"" list"
+(W parenthesis) You said something like
+.Sp
+.Vb 1
+\&    my $foo, $bar = @_;
+.Ve
+.Sp
+when you meant
+.Sp
+.Vb 1
+\&    my ($foo, $bar) = @_;
+.Ve
+.Sp
+Remember that "my", "our", and "local" bind tighter than comma.
+.ie n .IP "Possible unintended interpolation of %s in string" 4
+.el .IP "Possible unintended interpolation of \f(CW%s\fR in string" 4
+.IX Item "Possible unintended interpolation of %s in string"
+(W ambiguous) It used to be that Perl would try to guess whether you
+wanted an array interpolated or a literal @.  It no longer does this;
+arrays are now \fIalways\fR interpolated into strings.  This means that 
+if you try something like:
+.Sp
+.Vb 1
+\&        print "fred@example.com";
+.Ve
+.Sp
+and the array \f(CW@example\fR doesn't exist, Perl is going to print
+\&\f(CW\*(C`fred.com\*(C'\fR, which is probably not what you wanted.  To get a literal
+\&\f(CW\*(C`@\*(C'\fR sign in a string, put a backslash before it, just as you would
+to get a literal \f(CW\*(C`$\*(C'\fR sign.
+.ie n .IP "Possible Y2K bug: %s" 4
+.el .IP "Possible Y2K bug: \f(CW%s\fR" 4
+.IX Item "Possible Y2K bug: %s"
+(W y2k) You are concatenating the number 19 with another number, which
+could be a potential Year 2000 problem.
+.IP "pragma ""attrs"" is deprecated, use ""sub NAME : ATTRS"" instead" 4
+.IX Item "pragma ""attrs"" is deprecated, use ""sub NAME : ATTRS"" instead"
+(W deprecated) You have written something like this:
+.Sp
+.Vb 4
+\&    sub doit
+\&    {
+\&        use attrs qw(locked);
+\&    }
+.Ve
+.Sp
+You should use the new declaration syntax instead.
+.Sp
+.Vb 3
+\&    sub doit : locked
+\&    {
+\&        ...
+.Ve
+.Sp
+The \f(CW\*(C`use attrs\*(C'\fR pragma is now obsolete, and is only provided for
+backward-compatibility. See "Subroutine Attributes" in perlsub.
+.IP "Premature end of script headers" 4
+.IX Item "Premature end of script headers"
+See Server error.
+.IP "Repeat count in pack overflows" 4
+.IX Item "Repeat count in pack overflows"
+(F) You can't specify a repeat count so large that it overflows
+your signed integers.  See "pack" in perlfunc.
+.IP "Repeat count in unpack overflows" 4
+.IX Item "Repeat count in unpack overflows"
+(F) You can't specify a repeat count so large that it overflows
+your signed integers.  See "unpack" in perlfunc.
+.IP "\fBrealloc()\fR of freed memory ignored" 4
+.IX Item "realloc() of freed memory ignored"
+(S) An internal routine called \fBrealloc()\fR on something that had already
+been freed.
+.IP "Reference is already weak" 4
+.IX Item "Reference is already weak"
+(W misc) You have attempted to weaken a reference that is already weak.
+Doing so has no effect.
+.IP "setpgrp can't take arguments" 4
+.IX Item "setpgrp can't take arguments"
+(F) Your system has the \fBsetpgrp()\fR from BSD 4.2, which takes no arguments,
+unlike POSIX \fBsetpgid()\fR, which takes a process ID and process group ID.
+.IP "Strange *+?{} on zero-length expression" 4
+.IX Item "Strange *+?{} on zero-length expression"
+(W regexp) You applied a regular expression quantifier in a place where it
+makes no sense, such as on a zero-width assertion.
+Try putting the quantifier inside the assertion instead.  For example,
+the way to match "abc" provided that it is followed by three
+repetitions of "xyz" is \f(CW\*(C`/abc(?=(?:xyz){3})/\*(C'\fR, not \f(CW\*(C`/abc(?=xyz){3}/\*(C'\fR.
+.ie n .IP "switching effective %s is not implemented" 4
+.el .IP "switching effective \f(CW%s\fR is not implemented" 4
+.IX Item "switching effective %s is not implemented"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, we cannot switch the
+real and effective uids or gids.
+.IP "This Perl can't reset CRTL environ elements (%s)" 4
+.IX Item "This Perl can't reset CRTL environ elements (%s)"
+.PD 0
+.IP "This Perl can't set CRTL environ elements (%s=%s)" 4
+.IX Item "This Perl can't set CRTL environ elements (%s=%s)"
+.PD
+(W internal) Warnings peculiar to VMS.  You tried to change or delete an element
+of the CRTL's internal environ array, but your copy of Perl wasn't
+built with a CRTL that contained the \fBsetenv()\fR function.  You'll need to
+rebuild Perl with a CRTL that does, or redefine \fIPERL_ENV_TABLES\fR (see
+perlvms) so that the environ array isn't the target of the change to
+\&\f(CW%ENV\fR which produced the warning.
+.ie n .IP "Too late to run %s block" 4
+.el .IP "Too late to run \f(CW%s\fR block" 4
+.IX Item "Too late to run %s block"
+(W void) A CHECK or INIT block is being defined during run time proper,
+when the opportunity to run them has already passed.  Perhaps you are
+loading a file with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR when you should be using
+\&\f(CW\*(C`use\*(C'\fR instead.  Or perhaps you should put the \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR
+inside a BEGIN block.
+.IP "Unknown \fBopen()\fR mode '%s'" 4
+.IX Item "Unknown open() mode '%s'"
+(F) The second argument of 3\-argument \fBopen()\fR is not among the list
+of valid modes: \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`+<\*(C'\fR,
+\&\f(CW\*(C`+>\*(C'\fR, \f(CW\*(C`+>>\*(C'\fR, \f(CW\*(C`\-|\*(C'\fR, \f(CW\*(C`|\-\*(C'\fR.
+.ie n .IP "Unknown process %x sent message to prime_env_iter: %s" 4
+.el .IP "Unknown process \f(CW%x\fR sent message to prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Unknown process %x sent message to prime_env_iter: %s"
+(P) An error peculiar to VMS.  Perl was reading values for \f(CW%ENV\fR before
+iterating over it, and someone else stuck a message in the stream of
+data Perl expected.  Someone's very confused, or perhaps trying to
+subvert Perl's population of \f(CW%ENV\fR for nefarious purposes.
+.IP "Unrecognized escape \e\e%c passed through" 4
+.IX Item "Unrecognized escape %c passed through"
+(W misc) You used a backslash-character combination which is not recognized
+by Perl.  The character was understood literally.
+.IP "Unterminated attribute parameter in attribute list" 4
+.IX Item "Unterminated attribute parameter in attribute list"
+(F) The lexer saw an opening (left) parenthesis character while parsing an
+attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.  See attributes.
+.IP "Unterminated attribute list" 4
+.IX Item "Unterminated attribute list"
+(F) The lexer found something other than a simple identifier at the start
+of an attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.  See attributes.
+.IP "Unterminated attribute parameter in subroutine attribute list" 4
+.IX Item "Unterminated attribute parameter in subroutine attribute list"
+(F) The lexer saw an opening (left) parenthesis character while parsing a
+subroutine attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.
+.IP "Unterminated subroutine attribute list" 4
+.IX Item "Unterminated subroutine attribute list"
+(F) The lexer found something other than a simple identifier at the start
+of a subroutine attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.
+.IP "Value of CLI symbol ""%s"" too long" 4
+.IX Item "Value of CLI symbol ""%s"" too long"
+(W misc) A warning peculiar to VMS.  Perl tried to read the value of an \f(CW%ENV\fR
+element from a CLI symbol table, and found a resultant string longer
+than 1024 characters.  The return value has been truncated to 1024
+characters.
+.IP "Version number must be a constant number" 4
+.IX Item "Version number must be a constant number"
+(P) The attempt to translate a \f(CW\*(C`use Module n.n LIST\*(C'\fR statement into
+its equivalent \f(CW\*(C`BEGIN\*(C'\fR block found an internal inconsistency with
+the version number.
+.SH "New tests"
+.IX Header "New tests"
+.IP lib/attrs 4
+.IX Item "lib/attrs"
+Compatibility tests for \f(CW\*(C`sub : attrs\*(C'\fR vs the older \f(CW\*(C`use attrs\*(C'\fR.
+.IP lib/env 4
+.IX Item "lib/env"
+Tests for new environment scalar capability (e.g., \f(CW\*(C`use Env qw($BAR);\*(C'\fR).
+.IP lib/env\-array 4
+.IX Item "lib/env-array"
+Tests for new environment array capability (e.g., \f(CW\*(C`use Env qw(@PATH);\*(C'\fR).
+.IP lib/io_const 4
+.IX Item "lib/io_const"
+IO constants (SEEK_*, _IO*).
+.IP lib/io_dir 4
+.IX Item "lib/io_dir"
+Directory-related IO methods (new, read, close, rewind, tied delete).
+.IP lib/io_multihomed 4
+.IX Item "lib/io_multihomed"
+INET sockets with multi-homed hosts.
+.IP lib/io_poll 4
+.IX Item "lib/io_poll"
+IO \fBpoll()\fR.
+.IP lib/io_unix 4
+.IX Item "lib/io_unix"
+UNIX sockets.
+.IP op/attrs 4
+.IX Item "op/attrs"
+Regression tests for \f(CW\*(C`my ($x,@y,%z) : attrs\*(C'\fR and <sub : attrs>.
+.IP op/filetest 4
+.IX Item "op/filetest"
+File test operators.
+.IP op/lex_assign 4
+.IX Item "op/lex_assign"
+Verify operations that access pad objects (lexicals and temporaries).
+.IP op/exists_sub 4
+.IX Item "op/exists_sub"
+Verify \f(CW\*(C`exists &sub\*(C'\fR operations.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Perl Source Incompatibilities"
+.IX Subsection "Perl Source Incompatibilities"
+Beware that any new warnings that have been added or old ones
+that have been enhanced are \fBnot\fR considered incompatible changes.
+.PP
+Since all new warnings must be explicitly requested via the \f(CW\*(C`\-w\*(C'\fR
+switch or the \f(CW\*(C`warnings\*(C'\fR pragma, it is ultimately the programmer's
+responsibility to ensure that warnings are enabled judiciously.
+.IP "CHECK is a new keyword" 4
+.IX Item "CHECK is a new keyword"
+All subroutine definitions named CHECK are now special.  See
+\&\f(CW\*(C`/"Support for CHECK blocks"\*(C'\fR for more information.
+.IP "Treatment of list slices of undef has changed" 4
+.IX Item "Treatment of list slices of undef has changed"
+There is a potential incompatibility in the behavior of list slices
+that are comprised entirely of undefined values.
+See "Behavior of list slices is more consistent".
+.ie n .IP "Format of $English::PERL_VERSION is different" 4
+.el .IP "Format of \f(CW$English::PERL_VERSION\fR is different" 4
+.IX Item "Format of $English::PERL_VERSION is different"
+The English module now sets \f(CW$PERL_VERSION\fR to $^V (a string value) rather
+than \f(CW$]\fR (a numeric value).  This is a potential incompatibility.
+Send us a report via perlbug if you are affected by this.
+.Sp
+See "Improved Perl version numbering system" for the reasons for
+this change.
+.ie n .IP "Literals of the form 1.2.3 parse differently" 4
+.el .IP "Literals of the form \f(CW1.2.3\fR parse differently" 4
+.IX Item "Literals of the form 1.2.3 parse differently"
+Previously, numeric literals with more than one dot in them were
+interpreted as a floating point number concatenated with one or more
+numbers.  Such "numbers" are now parsed as strings composed of the
+specified ordinals.
+.Sp
+For example, \f(CW\*(C`print 97.98.99\*(C'\fR used to output \f(CW97.9899\fR in earlier
+versions, but now prints \f(CW\*(C`abc\*(C'\fR.
+.Sp
+See "Support for strings represented as a vector of ordinals".
+.IP "Possibly changed pseudo-random number generator" 4
+.IX Item "Possibly changed pseudo-random number generator"
+Perl programs that depend on reproducing a specific set of pseudo-random
+numbers may now produce different output due to improvements made to the
+\&\fBrand()\fR builtin.  You can use \f(CW\*(C`sh Configure \-Drandfunc=rand\*(C'\fR to obtain
+the old behavior.
+.Sp
+See "Better pseudo-random number generator".
+.IP "Hashing function for hash keys has changed" 4
+.IX Item "Hashing function for hash keys has changed"
+Even though Perl hashes are not order preserving, the apparently
+random order encountered when iterating on the contents of a hash
+is actually determined by the hashing algorithm used.  Improvements
+in the algorithm may yield a random order that is \fBdifferent\fR from
+that of previous versions, especially when iterating on hashes.
+.Sp
+See "Better worst-case behavior of hashes" for additional
+information.
+.ie n .IP """undef"" fails on read only values" 4
+.el .IP "\f(CWundef\fR fails on read only values" 4
+.IX Item "undef fails on read only values"
+Using the \f(CW\*(C`undef\*(C'\fR operator on a readonly value (such as \f(CW$1\fR) has
+the same effect as assigning \f(CW\*(C`undef\*(C'\fR to the readonly value\-\-it
+throws an exception.
+.IP "Close-on-exec bit may be set on pipe and socket handles" 4
+.IX Item "Close-on-exec bit may be set on pipe and socket handles"
+Pipe and socket handles are also now subject to the close-on-exec
+behavior determined by the special variable $^F.
+.Sp
+See "More consistent close-on-exec behavior".
+.ie n .IP "Writing ""$$1"" to mean ""${$}1"" is unsupported" 4
+.el .IP "Writing \f(CW""$$1""\fR to mean \f(CW""${$}1""\fR is unsupported" 4
+.IX Item "Writing ""$$1"" to mean ""${$}1"" is unsupported"
+Perl 5.004 deprecated the interpretation of \f(CW$$1\fR and
+similar within interpolated strings to mean \f(CW\*(C`$$ . "1"\*(C'\fR,
+but still allowed it.
+.Sp
+In Perl 5.6.0 and later, \f(CW"$$1"\fR always means \f(CW"${$1}"\fR.
+.ie n .IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and ""\e(%h)""" 4
+.el .IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and \f(CW\e(%h)\fR" 4
+.IX Item "delete(), each(), values() and )"
+operate on aliases to values, not copies
+.Sp
+\&\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hashes (e.g. \f(CW\*(C`\e(%h)\*(C'\fR)
+in a list context return the actual
+values in the hash, instead of copies (as they used to in earlier
+versions).  Typical idioms for using these constructs copy the
+returned values, but this can make a significant difference when
+creating references to the returned values.  Keys in the hash are still
+returned as copies when iterating on a hash.
+.Sp
+See also "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hash iteration are faster".
+.IP "vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS" 4
+.IX Item "vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS"
+\&\fBvec()\fR generates a run-time error if the BITS argument is not
+a valid power-of-two integer.
+.IP "Text of some diagnostic output has changed" 4
+.IX Item "Text of some diagnostic output has changed"
+Most references to internal Perl operations in diagnostics
+have been changed to be more descriptive.  This may be an
+issue for programs that may incorrectly rely on the exact
+text of diagnostics for proper functioning.
+.ie n .IP """%@"" has been removed" 4
+.el .IP "\f(CW%@\fR has been removed" 4
+.IX Item "%@ has been removed"
+The undocumented special variable \f(CW\*(C`%@\*(C'\fR that used to accumulate
+"background" errors (such as those that happen in \fBDESTROY()\fR)
+has been removed, because it could potentially result in memory
+leaks.
+.IP "Parenthesized \fBnot()\fR behaves like a list operator" 4
+.IX Item "Parenthesized not() behaves like a list operator"
+The \f(CW\*(C`not\*(C'\fR operator now falls under the "if it looks like a function,
+it behaves like a function" rule.
+.Sp
+As a result, the parenthesized form can be used with \f(CW\*(C`grep\*(C'\fR and \f(CW\*(C`map\*(C'\fR.
+The following construct used to be a syntax error before, but it works
+as expected now:
+.Sp
+.Vb 1
+\&    grep not($_), @things;
+.Ve
+.Sp
+On the other hand, using \f(CW\*(C`not\*(C'\fR with a literal list slice may not
+work.  The following previously allowed construct:
+.Sp
+.Vb 1
+\&    print not (1,2,3)[0];
+.Ve
+.Sp
+needs to be written with additional parentheses now:
+.Sp
+.Vb 1
+\&    print not((1,2,3)[0]);
+.Ve
+.Sp
+The behavior remains unaffected when \f(CW\*(C`not\*(C'\fR is not followed by parentheses.
+.ie n .IP "Semantics of bareword prototype ""(*)"" have changed" 4
+.el .IP "Semantics of bareword prototype \f(CW(*)\fR have changed" 4
+.IX Item "Semantics of bareword prototype (*) have changed"
+The semantics of the bareword prototype \f(CW\*(C`*\*(C'\fR have changed.  Perl 5.005
+always coerced simple scalar arguments to a typeglob, which wasn't useful
+in situations where the subroutine must distinguish between a simple
+scalar and a typeglob.  The new behavior is to not coerce bareword
+arguments to a typeglob.  The value will always be visible as either
+a simple scalar or as a reference to a typeglob.
+.Sp
+See "More functional bareword prototype (*)".
+.IP "Semantics of bit operators may have changed on 64\-bit platforms" 4
+.IX Item "Semantics of bit operators may have changed on 64-bit platforms"
+If your platform is either natively 64\-bit or if Perl has been
+configured to used 64\-bit integers, i.e., \f(CW$Config\fR{ivsize} is 8, 
+there may be a potential incompatibility in the behavior of bitwise
+numeric operators (& | ^ ~ << >>).  These operators used to strictly
+operate on the lower 32 bits of integers in previous versions, but now
+operate over the entire native integral width.  In particular, note
+that unary \f(CW\*(C`~\*(C'\fR will produce different results on platforms that have
+different \f(CW$Config\fR{ivsize}.  For portability, be sure to mask off
+the excess bits in the result of unary \f(CW\*(C`~\*(C'\fR, e.g., \f(CW\*(C`~$x & 0xffffffff\*(C'\fR.
+.Sp
+See "Bit operators support full native integer width".
+.IP "More builtins taint their results" 4
+.IX Item "More builtins taint their results"
+As described in "Improved security features", there may be more
+sources of taint in a Perl program.
+.Sp
+To avoid these new tainting behaviors, you can build Perl with the
+Configure option \f(CW\*(C`\-Accflags=\-DINCOMPLETE_TAINTS\*(C'\fR.  Beware that the
+ensuing perl binary may be insecure.
+.SS "C Source Incompatibilities"
+.IX Subsection "C Source Incompatibilities"
+.ie n .IP """PERL_POLLUTE""" 4
+.el .IP \f(CWPERL_POLLUTE\fR 4
+.IX Item "PERL_POLLUTE"
+Release 5.005 grandfathered old global symbol names by providing preprocessor
+macros for extension source compatibility.  As of release 5.6.0, these
+preprocessor definitions are not available by default.  You need to explicitly
+compile perl with \f(CW\*(C`\-DPERL_POLLUTE\*(C'\fR to get these definitions.  For
+extensions still using the old symbols, this option can be
+specified via MakeMaker:
+.Sp
+.Vb 1
+\&    perl Makefile.PL POLLUTE=1
+.Ve
+.ie n .IP """PERL_IMPLICIT_CONTEXT""" 4
+.el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4
+.IX Item "PERL_IMPLICIT_CONTEXT"
+This new build option provides a set of macros for all API functions
+such that an implicit interpreter/thread context argument is passed to
+every API function.  As a result of this, something like \f(CW\*(C`sv_setsv(foo,bar)\*(C'\fR
+amounts to a macro invocation that actually translates to something like
+\&\f(CW\*(C`Perl_sv_setsv(my_perl,foo,bar)\*(C'\fR.  While this is generally expected
+to not have any significant source compatibility issues, the difference
+between a macro and a real function call will need to be considered.
+.Sp
+This means that there \fBis\fR a source compatibility issue as a result of
+this if your extensions attempt to use pointers to any of the Perl API
+functions.
+.Sp
+Note that the above issue is not relevant to the default build of
+Perl, whose interfaces continue to match those of prior versions
+(but subject to the other options described here).
+.Sp
+See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for detailed information on the
+ramifications of building Perl with this option.
+.Sp
+.Vb 3
+\&    NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
+\&    with one of \-Dusethreads, \-Dusemultiplicity, or both.  It is not
+\&    intended to be enabled by users at this time.
+.Ve
+.ie n .IP """PERL_POLLUTE_MALLOC""" 4
+.el .IP \f(CWPERL_POLLUTE_MALLOC\fR 4
+.IX Item "PERL_POLLUTE_MALLOC"
+Enabling Perl's malloc in release 5.005 and earlier caused the namespace of
+the system's malloc family of functions to be usurped by the Perl versions,
+since by default they used the same names.  Besides causing problems on
+platforms that do not allow these functions to be cleanly replaced, this
+also meant that the system versions could not be called in programs that
+used Perl's malloc.  Previous versions of Perl have allowed this behaviour
+to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor
+definitions.
+.Sp
+As of release 5.6.0, Perl's malloc family of functions have default names
+distinct from the system versions.  You need to explicitly compile perl with
+\&\f(CW\*(C`\-DPERL_POLLUTE_MALLOC\*(C'\fR to get the older behaviour.  HIDEMYMALLOC
+and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now
+the default.
+.Sp
+Note that these functions do \fBnot\fR constitute Perl's memory allocation API.
+See "Memory Allocation" in perlguts for further information about that.
+.SS "Compatible C Source API Changes"
+.IX Subsection "Compatible C Source API Changes"
+.ie n .IP """PATCHLEVEL"" is now ""PERL_VERSION""" 4
+.el .IP "\f(CWPATCHLEVEL\fR is now \f(CWPERL_VERSION\fR" 4
+.IX Item "PATCHLEVEL is now PERL_VERSION"
+The cpp macros \f(CW\*(C`PERL_REVISION\*(C'\fR, \f(CW\*(C`PERL_VERSION\*(C'\fR, and \f(CW\*(C`PERL_SUBVERSION\*(C'\fR
+are now available by default from perl.h, and reflect the base revision,
+patchlevel, and subversion respectively.  \f(CW\*(C`PERL_REVISION\*(C'\fR had no
+prior equivalent, while \f(CW\*(C`PERL_VERSION\*(C'\fR and \f(CW\*(C`PERL_SUBVERSION\*(C'\fR were
+previously available as \f(CW\*(C`PATCHLEVEL\*(C'\fR and \f(CW\*(C`SUBVERSION\*(C'\fR.
+.Sp
+The new names cause less pollution of the \fBcpp\fR namespace and reflect what
+the numbers have come to stand for in common practice.  For compatibility,
+the old names are still supported when \fIpatchlevel.h\fR is explicitly
+included (as required before), so there is no source incompatibility
+from the change.
+.SS "Binary Incompatibilities"
+.IX Subsection "Binary Incompatibilities"
+In general, the default build of this release is expected to be binary
+compatible for extensions built with the 5.005 release or its maintenance
+versions.  However, specific platforms may have broken binary compatibility
+due to changes in the defaults used in hints files.  Therefore, please be
+sure to always check the platform-specific README files for any notes to
+the contrary.
+.PP
+The usethreads or usemultiplicity builds are \fBnot\fR binary compatible
+with the corresponding builds in 5.005.
+.PP
+On platforms that require an explicit list of exports (AIX, OS/2 and Windows,
+among others), purely internal symbols such as parser functions and the
+run time opcodes are not exported by default.  Perl 5.005 used to export
+all functions irrespective of whether they were considered part of the
+public API or not.
+.PP
+For the full list of public API functions, see perlapi.
+.SH "Known Problems"
+.IX Header "Known Problems"
+.SS "Thread test failures"
+.IX Subsection "Thread test failures"
+The subtests 19 and 20 of lib/thr5005.t test are known to fail due to
+fundamental problems in the 5.005 threading implementation.  These are
+not new failures\-\-Perl 5.005_0x has the same bugs, but didn't have these
+tests.
+.SS "EBCDIC platforms not supported"
+.IX Subsection "EBCDIC platforms not supported"
+In earlier releases of Perl, EBCDIC environments like OS390 (also
+known as Open Edition MVS) and VM-ESA were supported.  Due to changes
+required by the UTF\-8 (Unicode) support, the EBCDIC platforms are not
+supported in Perl 5.6.0.
+.SS "In 64\-bit HP-UX the lib/io_multihomed test may hang"
+.IX Subsection "In 64-bit HP-UX the lib/io_multihomed test may hang"
+The lib/io_multihomed test may hang in HP-UX if Perl has been
+configured to be 64\-bit.  Because other 64\-bit platforms do not
+hang in this test, HP-UX is suspect.  All other tests pass
+in 64\-bit HP-UX.  The test attempts to create and connect to
+"multihomed" sockets (sockets which have multiple IP addresses).
+.SS "NEXTSTEP 3.3 POSIX test failure"
+.IX Subsection "NEXTSTEP 3.3 POSIX test failure"
+In NEXTSTEP 3.3p2 the implementation of the \fBstrftime\fR\|(3) in the
+operating system libraries is buggy: the \f(CW%j\fR format numbers the days of
+a month starting from zero, which, while being logical to programmers,
+will cause the subtests 19 to 27 of the lib/posix test may fail.
+.SS "Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc"
+.IX Subsection "Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc"
+If compiled with gcc 2.95 the lib/sdbm test will fail (dump core).
+The cure is to use the vendor cc, it comes with the operating system
+and produces good code.
+.SS "UNICOS/mk CC failures during Configure run"
+.IX Subsection "UNICOS/mk CC failures during Configure run"
+In UNICOS/mk the following errors may appear during the Configure run:
+.PP
+.Vb 6
+\&        Guessing which symbols your C compiler and preprocessor define...
+\&        CC\-20 cc: ERROR File = try.c, Line = 3
+\&        ...
+\&          bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
+\&        ...
+\&        4 errors detected in the compilation of "try.c".
+.Ve
+.PP
+The culprit is the broken awk of UNICOS/mk.  The effect is fortunately
+rather mild: Perl itself is not adversely affected by the error, only
+the h2ph utility coming with Perl, and that is rather rarely needed
+these days.
+.SS "Arrow operator and arrays"
+.IX Subsection "Arrow operator and arrays"
+When the left argument to the arrow operator \f(CW\*(C`\->\*(C'\fR is an array, or
+the \f(CW\*(C`scalar\*(C'\fR operator operating on an array, the result of the
+operation must be considered erroneous. For example:
+.PP
+.Vb 2
+\&    @x\->[2]
+\&    scalar(@x)\->[2]
+.Ve
+.PP
+These expressions will get run-time errors in some future release of
+Perl.
+.SS "Experimental features"
+.IX Subsection "Experimental features"
+As discussed above, many features are still experimental.  Interfaces and
+implementation of these features are subject to change, and in extreme cases,
+even subject to removal in some future release of Perl.  These features
+include the following:
+.IP Threads 4
+.IX Item "Threads"
+.PD 0
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "64\-bit support" 4
+.IX Item "64-bit support"
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+.IP "Weak references" 4
+.IX Item "Weak references"
+.IP "The pseudo-hash data type" 4
+.IX Item "The pseudo-hash data type"
+.IP "The Compiler suite" 4
+.IX Item "The Compiler suite"
+.IP "Internal implementation of file globbing" 4
+.IX Item "Internal implementation of file globbing"
+.IP "The DB module" 4
+.IX Item "The DB module"
+.IP "The regular expression code constructs:" 4
+.IX Item "The regular expression code constructs:"
+.PD
+\&\f(CW\*(C`(?{ code })\*(C'\fR and \f(CW\*(C`(??{ code })\*(C'\fR
+.SH "Obsolete Diagnostics"
+.IX Header "Obsolete Diagnostics"
+.IP "Character class syntax [: :] is reserved for future extensions" 4
+.IX Item "Character class syntax [: :] is reserved for future extensions"
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\e[:" and ":\e]".
+.IP "Ill-formed logical name |%s| in prime_env_iter" 4
+.IX Item "Ill-formed logical name |%s| in prime_env_iter"
+(W) A warning peculiar to VMS.  A logical name was encountered when preparing
+to iterate over \f(CW%ENV\fR which violates the syntactic rules governing logical
+names.  Because it cannot be translated normally, it is skipped, and will not
+appear in \f(CW%ENV\fR.  This may be a benign occurrence, as some software packages
+might directly modify logical name tables and introduce nonstandard names,
+or it may indicate that a logical name table has been corrupted.
+.IP "In string, @%s now must be written as \e@%s" 4
+.IX Item "In string, @%s now must be written as @%s"
+The description of this error used to say:
+.Sp
+.Vb 2
+\&        (Someday it will simply assume that an unbackslashed @
+\&         interpolates an array.)
+.Ve
+.Sp
+That day has come, and this fatal error has been removed.  It has been
+replaced by a non-fatal warning instead.
+See "Arrays now always interpolate into double-quoted strings" for
+details.
+.ie n .IP "Probable precedence problem on %s" 4
+.el .IP "Probable precedence problem on \f(CW%s\fR" 4
+.IX Item "Probable precedence problem on %s"
+(W) The compiler found a bareword where it expected a conditional,
+which often indicates that an || or && was parsed as part of the
+last argument of the previous construct, for example:
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.IP "regexp too big" 4
+.IX Item "regexp too big"
+(F) The current implementation of regular expressions uses shorts as
+address offsets within a string.  Unfortunately this means that if
+the regular expression compiles to longer than 32767, it'll blow up.
+Usually when you want a regular expression this big, there is a better
+way to do it with multiple statements.  See perlre.
+.IP "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated" 4
+.IX Item "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated"
+(D) Perl versions before 5.004 misinterpreted any type marker followed
+by "$" and a digit.  For example, "$$0" was incorrectly taken to mean
+"${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
+.Sp
+However, the developers of Perl 5.004 could not fix this bug completely,
+because at least two widely-used modules depend on the old meaning of
+"$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
+old (broken) way inside strings; but it generates this message as a
+warning.  And in Perl 5.005, this special treatment will cease.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the
+articles recently posted to the comp.lang.perl.misc newsgroup.
+There may also be information at http://www.perl.com/perl/ , the Perl
+Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Written by Gurusamy Sarathy <\fIgsar@activestate.com\fR>, with many
+contributions from The Perl Porters.
+.PP
+Send omissions or corrections to <\fIperlbug@perl.org\fR>.
diff --git a/upstream/mageia-cauldron/man1/perl581delta.1 b/upstream/mageia-cauldron/man1/perl581delta.1
new file mode 100644
index 00000000..4abd32e4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl581delta.1
@@ -0,0 +1,1089 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL581DELTA 1"
+.TH PERL581DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl581delta \- what is new for perl v5.8.1
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.0 release and
+the 5.8.1 release.
+.PP
+If you are upgrading from an earlier release such as 5.6.1, first read
+the perl58delta, which describes differences between 5.6.0 and
+5.8.0.
+.PP
+In case you are wondering about 5.6.1, it was bug-fix-wise rather
+identical to the development release 5.7.1.  Confused?  This timeline
+hopefully helps a bit: it lists the new major releases, their maintenance
+releases, and the development releases.
+.PP
+.Vb 1
+\&          New     Maintenance  Development
+\&
+\&          5.6.0                             2000\-Mar\-22
+\&                               5.7.0        2000\-Sep\-02
+\&                  5.6.1                     2001\-Apr\-08
+\&                               5.7.1        2001\-Apr\-09
+\&                               5.7.2        2001\-Jul\-13
+\&                               5.7.3        2002\-Mar\-05
+\&          5.8.0                             2002\-Jul\-18
+\&                  5.8.1                     2003\-Sep\-25
+.Ve
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Hash Randomisation"
+.IX Subsection "Hash Randomisation"
+Mainly due to security reasons, the "random ordering" of hashes
+has been made even more random.  Previously while the order of hash
+elements from \fBkeys()\fR, \fBvalues()\fR, and \fBeach()\fR was essentially random,
+it was still repeatable.  Now, however, the order varies between
+different runs of Perl.
+.PP
+\&\fBPerl has never guaranteed any ordering of the hash keys\fR, and the
+ordering has already changed several times during the lifetime of
+Perl 5.  Also, the ordering of hash keys has always been, and
+continues to be, affected by the insertion order.
+.PP
+The added randomness may affect applications.
+.PP
+One possible scenario is when output of an application has included
+hash data.  For example, if you have used the Data::Dumper module to
+dump data into different files, and then compared the files to see
+whether the data has changed, now you will have false positives since
+the order in which hashes are dumped will vary.  In general the cure
+is to sort the keys (or the values); in particular for Data::Dumper to
+use the \f(CW\*(C`Sortkeys\*(C'\fR option.  If some particular order is really
+important, use tied hashes: for example the Tie::IxHash module
+which by default preserves the order in which the hash elements
+were added.
+.PP
+More subtle problem is reliance on the order of "global destruction".
+That is what happens at the end of execution: Perl destroys all data
+structures, including user data.  If your destructors (the DESTROY
+subroutines) have assumed any particular ordering to the global
+destruction, there might be problems ahead.  For example, in a
+destructor of one object you cannot assume that objects of any other
+class are still available, unless you hold a reference to them.
+If the environment variable PERL_DESTRUCT_LEVEL is set to a non-zero
+value, or if Perl is exiting a spawned thread, it will also destruct
+the ordinary references and the symbol tables that are no longer in use.
+You can't call a class method or an ordinary function on a class that
+has been collected that way.
+.PP
+The hash randomisation is certain to reveal hidden assumptions about
+some particular ordering of hash elements, and outright bugs: it
+revealed a few bugs in the Perl core and core modules.
+.PP
+To disable the hash randomisation in runtime, set the environment
+variable PERL_HASH_SEED to 0 (zero) before running Perl (for more
+information see "PERL_HASH_SEED" in perlrun), or to disable the feature
+completely in compile time, compile with \f(CW\*(C`\-DNO_HASH_SEED\*(C'\fR (see \fIINSTALL\fR).
+.PP
+See "Algorithmic Complexity Attacks" in perlsec for the original
+rationale behind this change.
+.SS "UTF\-8 On Filehandles No Longer Activated By Locale"
+.IX Subsection "UTF-8 On Filehandles No Longer Activated By Locale"
+In Perl 5.8.0 all filehandles, including the standard filehandles,
+were implicitly set to be in Unicode UTF\-8 if the locale settings
+indicated the use of UTF\-8.  This feature caused too many problems,
+so the feature was turned off and redesigned: see "Core Enhancements".
+.SS "Single-number v\-strings are no longer v\-strings before ""=>"""
+.IX Subsection "Single-number v-strings are no longer v-strings before ""=>"""
+The version strings or v\-strings (see "Version Strings" in perldata)
+feature introduced in Perl 5.6.0 has been a source of some confusion\-\-
+especially when the user did not want to use it, but Perl thought it
+knew better.  Especially troublesome has been the feature that before
+a "=>" a version string (a "v" followed by digits) has been interpreted
+as a v\-string instead of a string literal.  In other words:
+.PP
+.Vb 1
+\&        %h = ( v65 => 42 );
+.Ve
+.PP
+has meant since Perl 5.6.0
+.PP
+.Vb 1
+\&        %h = ( \*(AqA\*(Aq => 42 );
+.Ve
+.PP
+(at least in platforms of ASCII progeny)  Perl 5.8.1 restores the
+more natural interpretation
+.PP
+.Vb 1
+\&        %h = ( \*(Aqv65\*(Aq => 42 );
+.Ve
+.PP
+The multi-number v\-strings like v65.66 and 65.66.67 still continue to
+be v\-strings in Perl 5.8.
+.SS "(Win32) The \-C Switch Has Been Repurposed"
+.IX Subsection "(Win32) The -C Switch Has Been Repurposed"
+The \-C switch has changed in an incompatible way.  The old semantics
+of this switch only made sense in Win32 and only in the "use utf8"
+universe in 5.6.x releases, and do not make sense for the Unicode
+implementation in 5.8.0.  Since this switch could not have been used
+by anyone, it has been repurposed.  The behavior that this switch
+enabled in 5.6.x releases may be supported in a transparent,
+data-dependent fashion in a future release.
+.PP
+For the new life of this switch, see "UTF\-8 no longer default under
+UTF\-8 locales", and "\-C" in perlrun.
+.SS "(Win32) The /d Switch Of cmd.exe"
+.IX Subsection "(Win32) The /d Switch Of cmd.exe"
+Perl 5.8.1 uses the /d switch when running the cmd.exe shell
+internally for \fBsystem()\fR, backticks, and when opening pipes to external
+programs.  The extra switch disables the execution of AutoRun commands
+from the registry, which is generally considered undesirable when
+running external programs.  If you wish to retain compatibility with
+the older behavior, set PERL5SHELL in your environment to \f(CW\*(C`cmd /x/c\*(C'\fR.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "UTF\-8 no longer default under UTF\-8 locales"
+.IX Subsection "UTF-8 no longer default under UTF-8 locales"
+In Perl 5.8.0 many Unicode features were introduced.   One of them
+was found to be of more nuisance than benefit: the automagic
+(and silent) "UTF\-8\-ification" of filehandles, including the
+standard filehandles, if the user's locale settings indicated
+use of UTF\-8.
+.PP
+For example, if you had \f(CW\*(C`en_US.UTF\-8\*(C'\fR as your locale, your STDIN and
+STDOUT were automatically "UTF\-8", in other words an implicit
+binmode(..., ":utf8") was made.  This meant that trying to print, say,
+\&\fBchr\fR\|(0xff), ended up printing the bytes 0xc3 0xbf.  Hardly what
+you had in mind unless you were aware of this feature of Perl 5.8.0.
+The problem is that the vast majority of people weren't: for example
+in RedHat releases 8 and 9 the \fBdefault\fR locale setting is UTF\-8, so
+all RedHat users got UTF\-8 filehandles, whether they wanted it or not.
+The pain was intensified by the Unicode implementation of Perl 5.8.0
+(still) having nasty bugs, especially related to the use of s/// and
+tr///.  (Bugs that have been fixed in 5.8.1)
+.PP
+Therefore a decision was made to backtrack the feature and change it
+from implicit silent default to explicit conscious option.  The new
+Perl command line option \f(CW\*(C`\-C\*(C'\fR and its counterpart environment
+variable PERL_UNICODE can now be used to control how Perl and Unicode
+interact at interfaces like I/O and for example the command line
+arguments.  See "\-C" in perlrun and "PERL_UNICODE" in perlrun for more
+information.
+.SS "Unsafe signals again available"
+.IX Subsection "Unsafe signals again available"
+In Perl 5.8.0 the so-called "safe signals" were introduced.  This
+means that Perl no longer handles signals immediately but instead
+"between opcodes", when it is safe to do so.  The earlier immediate
+handling easily could corrupt the internal state of Perl, resulting
+in mysterious crashes.
+.PP
+However, the new safer model has its problems too.  Because now an
+opcode, a basic unit of Perl execution, is never interrupted but
+instead let to run to completion, certain operations that can take a
+long time now really do take a long time.  For example, certain
+network operations have their own blocking and timeout mechanisms, and
+being able to interrupt them immediately would be nice.
+.PP
+Therefore perl 5.8.1 introduces a "backdoor" to restore the pre\-5.8.0
+(pre\-5.7.3, really) signal behaviour.  Just set the environment variable
+PERL_SIGNALS to \f(CW\*(C`unsafe\*(C'\fR, and the old immediate (and unsafe)
+signal handling behaviour returns.  See "PERL_SIGNALS" in perlrun
+and "Deferred Signals (Safe Signals)" in perlipc.
+.PP
+In completely unrelated news, you can now use safe signals with
+POSIX::SigAction.  See "POSIX::SigAction" in POSIX.
+.SS "Tied Arrays with Negative Array Indices"
+.IX Subsection "Tied Arrays with Negative Array Indices"
+Formerly, the indices passed to \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR, \f(CW\*(C`EXISTS\*(C'\fR, and
+\&\f(CW\*(C`DELETE\*(C'\fR methods in tied array class were always non-negative.  If
+the actual argument was negative, Perl would call FETCHSIZE implicitly
+and add the result to the index before passing the result to the tied
+array method.  This behaviour is now optional.  If the tied array class
+contains a package variable named \f(CW$NEGATIVE_INDICES\fR which is set to
+a true value, negative values will be passed to \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR,
+\&\f(CW\*(C`EXISTS\*(C'\fR, and \f(CW\*(C`DELETE\*(C'\fR unchanged.
+.SS "local ${$x}"
+.IX Subsection "local ${$x}"
+The syntaxes
+.PP
+.Vb 3
+\&        local ${$x}
+\&        local @{$x}
+\&        local %{$x}
+.Ve
+.PP
+now do localise variables, given that the \f(CW$x\fR is a valid variable name.
+.SS "Unicode Character Database 4.0.0"
+.IX Subsection "Unicode Character Database 4.0.0"
+The copy of the Unicode Character Database included in Perl 5.8 has
+been updated to 4.0.0 from 3.2.0.  This means for example that the
+Unicode character properties are as in Unicode 4.0.0.
+.SS "Deprecation Warnings"
+.IX Subsection "Deprecation Warnings"
+There is one new feature deprecation.  Perl 5.8.0 forgot to add
+some deprecation warnings, these warnings have now been added.
+Finally, a reminder of an impending feature removal.
+.PP
+\fI(Reminder) Pseudo-hashes are deprecated (really)\fR
+.IX Subsection "(Reminder) Pseudo-hashes are deprecated (really)"
+.PP
+Pseudo-hashes were deprecated in Perl 5.8.0 and will be removed in
+Perl 5.10.0, see perl58delta for details.  Each attempt to access
+pseudo-hashes will trigger the warning \f(CW\*(C`Pseudo\-hashes are deprecated\*(C'\fR.
+If you really want to continue using pseudo-hashes but not to see the
+deprecation warnings, use:
+.PP
+.Vb 1
+\&    no warnings \*(Aqdeprecated\*(Aq;
+.Ve
+.PP
+Or you can continue to use the fields pragma, but please don't
+expect the data structures to be pseudohashes any more.
+.PP
+\fI(Reminder) 5.005\-style threads are deprecated (really)\fR
+.IX Subsection "(Reminder) 5.005-style threads are deprecated (really)"
+.PP
+5.005\-style threads (activated by \f(CW\*(C`use Thread;\*(C'\fR) were deprecated in
+Perl 5.8.0 and will be removed after Perl 5.8, see perl58delta for
+details.  Each 5.005\-style thread creation will trigger the warning
+\&\f(CW\*(C`5.005 threads are deprecated\*(C'\fR.  If you really want to continue
+using the 5.005 threads but not to see the deprecation warnings, use:
+.PP
+.Vb 1
+\&    no warnings \*(Aqdeprecated\*(Aq;
+.Ve
+.PP
+\fI(Reminder) The $* variable is deprecated (really)\fR
+.IX Subsection "(Reminder) The $* variable is deprecated (really)"
+.PP
+The \f(CW$*\fR variable controlling multi-line matching has been deprecated
+and will be removed after 5.8.  The variable has been deprecated for a
+long time, and a deprecation warning \f(CW\*(C`Use of $* is deprecated\*(C'\fR is given,
+now the variable will just finally be removed.  The functionality has
+been supplanted by the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR modifiers on pattern matching.
+If you really want to continue using the \f(CW$*\fR\-variable but not to see
+the deprecation warnings, use:
+.PP
+.Vb 1
+\&    no warnings \*(Aqdeprecated\*(Aq;
+.Ve
+.SS "Miscellaneous Enhancements"
+.IX Subsection "Miscellaneous Enhancements"
+\&\f(CW\*(C`map\*(C'\fR in void context is no longer expensive. \f(CW\*(C`map\*(C'\fR is now context
+aware, and will not construct a list if called in void context.
+.PP
+If a socket gets closed by the server while printing to it, the client
+now gets a SIGPIPE.  While this new feature was not planned, it fell
+naturally out of PerlIO changes, and is to be considered an accidental
+feature.
+.PP
+PerlIO::get_layers(FH) returns the names of the PerlIO layers
+active on a filehandle.
+.PP
+PerlIO::via layers can now have an optional UTF8 method to
+indicate whether the layer wants to "auto\-:utf8" the stream.
+.PP
+\&\fButf8::is_utf8()\fR has been added as a quick way to test whether
+a scalar is encoded internally in UTF\-8 (Unicode).
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules And Pragmata"
+.IX Subsection "Updated Modules And Pragmata"
+The following modules and pragmata have been updated since Perl 5.8.0:
+.IP base 4
+.IX Item "base"
+.PD 0
+.IP B::Bytecode 4
+.IX Item "B::Bytecode"
+.PD
+In much better shape than it used to be.  Still far from perfect, but
+maybe worth a try.
+.IP B::Concise 4
+.IX Item "B::Concise"
+.PD 0
+.IP B::Deparse 4
+.IX Item "B::Deparse"
+.IP Benchmark 4
+.IX Item "Benchmark"
+.PD
+An optional feature, \f(CW\*(C`:hireswallclock\*(C'\fR, now allows for high
+resolution wall clock times (uses Time::HiRes).
+.IP ByteLoader 4
+.IX Item "ByteLoader"
+See B::Bytecode.
+.IP bytes 4
+.IX Item "bytes"
+Now has bytes::substr.
+.IP CGI 4
+.IX Item "CGI"
+.PD 0
+.IP charnames 4
+.IX Item "charnames"
+.PD
+One can now have custom character name aliases.
+.IP CPAN 4
+.IX Item "CPAN"
+There is now a simple command line frontend to the CPAN.pm
+module called \fIcpan\fR.
+.IP Data::Dumper 4
+.IX Item "Data::Dumper"
+A new option, Pair, allows choosing the separator between hash keys
+and values.
+.IP DB_File 4
+.IX Item "DB_File"
+.PD 0
+.IP Devel::PPPort 4
+.IX Item "Devel::PPPort"
+.IP Digest::MD5 4
+.IX Item "Digest::MD5"
+.IP Encode 4
+.IX Item "Encode"
+.PD
+Significant updates on the encoding pragma functionality
+(tr/// and the DATA filehandle, formats).
+.Sp
+If a filehandle has been marked as to have an encoding, unmappable
+characters are detected already during input, not later (when the
+corrupted data is being used).
+.Sp
+The ISO 8859\-6 conversion table has been corrected (the 0x30..0x39
+erroneously mapped to U+0660..U+0669, instead of U+0030..U+0039).  The
+GSM 03.38 conversion did not handle escape sequences correctly.  The
+UTF\-7 encoding has been added (making Encode feature-complete with
+Unicode::String).
+.IP fields 4
+.IX Item "fields"
+.PD 0
+.IP libnet 4
+.IX Item "libnet"
+.IP Math::BigInt 4
+.IX Item "Math::BigInt"
+.PD
+A lot of bugs have been fixed since v1.60, the version included in Perl
+v5.8.0. Especially noteworthy are the bug in Calc that caused div and mod to
+fail for some large values, and the fixes to the handling of bad inputs.
+.Sp
+Some new features were added, e.g. the \fBbroot()\fR method, you can now pass
+parameters to \fBconfig()\fR to change some settings at runtime, and it is now
+possible to trap the creation of NaN and infinity.
+.Sp
+As usual, some optimizations took place and made the math overall a tad
+faster. In some cases, quite a lot faster, actually. Especially alternative
+libraries like Math::BigInt::GMP benefit from this. In addition, a lot of the
+quite clunky routines like \fBfsqrt()\fR and \fBflog()\fR are now much much faster.
+.IP MIME::Base64 4
+.IX Item "MIME::Base64"
+.PD 0
+.IP NEXT 4
+.IX Item "NEXT"
+.PD
+Diamond inheritance now works.
+.IP Net::Ping 4
+.IX Item "Net::Ping"
+.PD 0
+.IP PerlIO::scalar 4
+.IX Item "PerlIO::scalar"
+.PD
+Reading from non-string scalars (like the special variables, see
+perlvar) now works.
+.IP podlators 4
+.IX Item "podlators"
+.PD 0
+.IP Pod::LaTeX 4
+.IX Item "Pod::LaTeX"
+.IP PodParsers 4
+.IX Item "PodParsers"
+.IP Pod::Perldoc 4
+.IX Item "Pod::Perldoc"
+.PD
+Complete rewrite.  As a side-effect, no longer refuses to startup when
+run by root.
+.IP Scalar::Util 4
+.IX Item "Scalar::Util"
+New utilities: refaddr, isvstring, looks_like_number, set_prototype.
+.IP Storable 4
+.IX Item "Storable"
+Can now store code references (via B::Deparse, so not foolproof).
+.IP strict 4
+.IX Item "strict"
+Earlier versions of the strict pragma did not check the parameters
+implicitly passed to its "import" (use) and "unimport" (no) routine.
+This caused the false idiom such as:
+.Sp
+.Vb 2
+\&        use strict qw(@ISA);
+\&        @ISA = qw(Foo);
+.Ve
+.Sp
+This however (probably) raised the false expectation that the strict
+refs, vars and subs were being enforced (and that \f(CW@ISA\fR was somehow
+"declared").  But the strict refs, vars, and subs are \fBnot\fR enforced
+when using this false idiom.
+.Sp
+Starting from Perl 5.8.1, the above \fBwill\fR cause an error to be
+raised.  This may cause programs which used to execute seemingly
+correctly without warnings and errors to fail when run under 5.8.1.
+This happens because
+.Sp
+.Vb 1
+\&        use strict qw(@ISA);
+.Ve
+.Sp
+will now fail with the error:
+.Sp
+.Vb 1
+\&        Unknown \*(Aqstrict\*(Aq tag(s) \*(Aq@ISA\*(Aq
+.Ve
+.Sp
+The remedy to this problem is to replace this code with the correct idiom:
+.Sp
+.Vb 3
+\&        use strict;
+\&        use vars qw(@ISA);
+\&        @ISA = qw(Foo);
+.Ve
+.IP Term::ANSIcolor 4
+.IX Item "Term::ANSIcolor"
+.PD 0
+.IP Test::Harness 4
+.IX Item "Test::Harness"
+.PD
+Now much more picky about extra or missing output from test scripts.
+.IP Test::More 4
+.IX Item "Test::More"
+.PD 0
+.IP Test::Simple 4
+.IX Item "Test::Simple"
+.IP Text::Balanced 4
+.IX Item "Text::Balanced"
+.IP Time::HiRes 4
+.IX Item "Time::HiRes"
+.PD
+Use of \fBnanosleep()\fR, if available, allows mixing subsecond sleeps with
+alarms.
+.IP threads 4
+.IX Item "threads"
+Several fixes, for example for \fBjoin()\fR problems and memory
+leaks.  In some platforms (like Linux) that use glibc the minimum memory
+footprint of one ithread has been reduced by several hundred kilobytes.
+.IP threads::shared 4
+.IX Item "threads::shared"
+Many memory leaks have been fixed.
+.IP Unicode::Collate 4
+.IX Item "Unicode::Collate"
+.PD 0
+.IP Unicode::Normalize 4
+.IX Item "Unicode::Normalize"
+.IP Win32::GetFolderPath 4
+.IX Item "Win32::GetFolderPath"
+.IP Win32::GetOSVersion 4
+.IX Item "Win32::GetOSVersion"
+.PD
+Now returns extra information.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+The \f(CW\*(C`h2xs\*(C'\fR utility now produces a more modern layout:
+\&\fIFoo\-Bar/lib/Foo/Bar.pm\fR instead of \fIFoo/Bar/Bar.pm\fR.
+Also, the boilerplate test is now called \fIt/Foo\-Bar.t\fR
+instead of \fIt/1.t\fR.
+.PP
+The Perl debugger (\fIlib/perl5db.pl\fR) has now been extensively
+documented and bugs found while documenting have been fixed.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR has been rewritten from scratch to be more robust and
+feature rich.
+.PP
+\&\f(CW\*(C`perlcc \-B\*(C'\fR works now at least somewhat better, while \f(CW\*(C`perlcc \-c\*(C'\fR
+is rather more broken.  (The Perl compiler suite as a whole continues
+to be experimental.)
+.SH "New Documentation"
+.IX Header "New Documentation"
+perl573delta has been added to list the differences between the
+(now quite obsolete) development releases 5.7.2 and 5.7.3.
+.PP
+perl58delta has been added: it is the perldelta of 5.8.0, detailing
+the differences between 5.6.0 and 5.8.0.
+.PP
+perlartistic has been added: it is the Artistic License in pod format,
+making it easier for modules to refer to it.
+.PP
+perlcheat has been added: it is a Perl cheat sheet.
+.PP
+perlgpl has been added: it is the GNU General Public License in pod
+format, making it easier for modules to refer to it.
+.PP
+perlmacosx has been added to tell about the installation and use
+of Perl in Mac OS X.
+.PP
+perlos400 has been added to tell about the installation and use
+of Perl in OS/400 PASE.
+.PP
+perlreref has been added: it is a regular expressions quick reference.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+The Unix standard Perl location, \fI/usr/bin/perl\fR, is no longer
+overwritten by default if it exists.  This change was very prudent
+because so many Unix vendors already provide a \fI/usr/bin/perl\fR,
+but simultaneously many system utilities may depend on that
+exact version of Perl, so better not to overwrite it.
+.PP
+One can now specify installation directories for site and vendor man
+and HTML pages, and site and vendor scripts.  See \fIINSTALL\fR.
+.PP
+One can now specify a destination directory for Perl installation
+by specifying the DESTDIR variable for \f(CW\*(C`make install\*(C'\fR.  (This feature
+is slightly different from the previous \f(CW\*(C`Configure \-Dinstallprefix=...\*(C'\fR.)
+See \fIINSTALL\fR.
+.PP
+gcc versions 3.x introduced a new warning that caused a lot of noise
+during Perl compilation: \f(CW\*(C`gcc \-Ialreadyknowndirectory (warning:
+changing search order)\*(C'\fR.  This warning has now been avoided by
+Configure weeding out such directories before the compilation.
+.PP
+One can now build subsets of Perl core modules by using the
+Configure flags \f(CW\*(C`\-Dnoextensions=...\*(C'\fR and \f(CW\*(C`\-Donlyextensions=...\*(C'\fR,
+see \fIINSTALL\fR.
+.SS "Platform-specific enhancements"
+.IX Subsection "Platform-specific enhancements"
+In Cygwin Perl can now be built with threads (\f(CW\*(C`Configure \-Duseithreads\*(C'\fR).
+This works with both Cygwin 1.3.22 and Cygwin 1.5.3.
+.PP
+In newer FreeBSD releases Perl 5.8.0 compilation failed because of
+trying to use \fImalloc.h\fR, which in FreeBSD is just a dummy file, and
+a fatal error to even try to use.  Now \fImalloc.h\fR is not used.
+.PP
+Perl is now known to build also in Hitachi HI-UXMPP.
+.PP
+Perl is now known to build again in LynxOS.
+.PP
+Mac OS X now installs with Perl version number embedded in
+installation directory names for easier upgrading of user-compiled
+Perl, and the installation directories in general are more standard.
+In other words, the default installation no longer breaks the
+Apple-provided Perl.  On the other hand, with \f(CW\*(C`Configure \-Dprefix=/usr\*(C'\fR
+you can now really replace the Apple-supplied Perl (\fBplease be careful\fR).
+.PP
+Mac OS X now builds Perl statically by default.  This change was done
+mainly for faster startup times.  The Apple-provided Perl is still
+dynamically linked and shared, and you can enable the sharedness for
+your own Perl builds by \f(CW\*(C`Configure \-Duseshrplib\*(C'\fR.
+.PP
+Perl has been ported to IBM's OS/400 PASE environment.  The best way
+to build a Perl for PASE is to use an AIX host as a cross-compilation
+environment.  See README.os400.
+.PP
+Yet another cross-compilation option has been added: now Perl builds
+on OpenZaurus, a Linux distribution based on Mandrake + Embedix for
+the Sharp Zaurus PDA.  See the Cross/README file.
+.PP
+Tru64 when using gcc 3 drops the optimisation for \fItoke.c\fR to \f(CW\*(C`\-O2\*(C'\fR
+because of gigantic memory use with the default \f(CW\*(C`\-O3\*(C'\fR.
+.PP
+Tru64 can now build Perl with the newer Berkeley DBs.
+.PP
+Building Perl on WinCE has been much enhanced, see \fIREADME.ce\fR
+and \fIREADME.perlce\fR.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS "Closures, eval and lexicals"
+.IX Subsection "Closures, eval and lexicals"
+There have been many fixes in the area of anonymous subs, lexicals and
+closures.  Although this means that Perl is now more "correct", it is
+possible that some existing code will break that happens to rely on
+the faulty behaviour.  In practice this is unlikely unless your code
+contains a very complex nesting of anonymous subs, evals and lexicals.
+.SS "Generic fixes"
+.IX Subsection "Generic fixes"
+If an input filehandle is marked \f(CW\*(C`:utf8\*(C'\fR and Perl sees illegal UTF\-8
+coming in when doing \f(CW\*(C`<FH>\*(C'\fR, if warnings are enabled a warning is
+immediately given \- instead of being silent about it and Perl being
+unhappy about the broken data later.  (The \f(CW:encoding(utf8)\fR layer
+also works the same way.)
+.PP
+binmode(SOCKET, ":utf8") only worked on the input side, not on the
+output side of the socket.  Now it works both ways.
+.PP
+For threaded Perls certain system database functions like \fBgetpwent()\fR
+and \fBgetgrent()\fR now grow their result buffer dynamically, instead of
+failing.  This means that at sites with lots of users and groups the
+functions no longer fail by returning only partial results.
+.PP
+Perl 5.8.0 had accidentally broken the capability for users
+to define their own uppercase<\->lowercase Unicode mappings
+(as advertised by the Camel).  This feature has been fixed and
+is also documented better.
+.PP
+In 5.8.0 this
+.PP
+.Vb 1
+\&        $some_unicode .= <FH>;
+.Ve
+.PP
+didn't work correctly but instead corrupted the data.  This has now
+been fixed.
+.PP
+Tied methods like FETCH etc. may now safely access tied values, i.e.
+resulting in a recursive call to FETCH etc.  Remember to break the
+recursion, though.
+.PP
+At startup Perl blocks the SIGFPE signal away since there isn't much
+Perl can do about it.  Previously this blocking was in effect also for
+programs executed from within Perl.  Now Perl restores the original
+SIGFPE handling routine, whatever it was, before running external
+programs.
+.PP
+Linenumbers in Perl scripts may now be greater than 65536, or 2**16.
+(Perl scripts have always been able to be larger than that, it's just
+that the linenumber for reported errors and warnings have "wrapped
+around".)  While scripts that large usually indicate a need to rethink
+your code a bit, such Perl scripts do exist, for example as results
+from generated code.  Now linenumbers can go all the way to
+4294967296, or 2**32.
+.SS "Platform-specific fixes"
+.IX Subsection "Platform-specific fixes"
+Linux
+.IP \(bu 4
+Setting \f(CW$0\fR works again (with certain limitations that
+Perl cannot do much about: see "$0" in perlvar)
+.PP
+HP-UX
+.IP \(bu 4
+Setting \f(CW$0\fR now works.
+.PP
+VMS
+.IP \(bu 4
+Configuration now tests for the presence of \f(CWpoll()\fR, and IO::Poll
+now uses the vendor-supplied function if detected.
+.IP \(bu 4
+A rare access violation at Perl start-up could occur if the Perl image was
+installed with privileges or if there was an identifier with the
+subsystem attribute set in the process's rightslist.  Either of these
+circumstances triggered tainting code that contained a pointer bug. 
+The faulty pointer arithmetic has been fixed.
+.IP \(bu 4
+The length limit on values (not keys) in the \f(CW%ENV\fR hash has been raised
+from 255 bytes to 32640 bytes (except when the PERL_ENV_TABLES setting
+overrides the default use of logical names for \f(CW%ENV\fR).  If it is
+necessary to access these long values from outside Perl, be aware that
+they are implemented using search list logical names that store the
+value in pieces, each 255\-byte piece (up to 128 of them) being an
+element in the search list. When doing a lookup in \f(CW%ENV\fR from within
+Perl, the elements are combined into a single value.  The existing
+VMS-specific ability to access individual elements of a search list
+logical name via the \f(CW$ENV\fR{'foo;N'} syntax (where N is the search list
+index) is unimpaired.
+.IP \(bu 4
+The piping implementation now uses local rather than global DCL
+symbols for inter-process communication.
+.IP \(bu 4
+File::Find could become confused when navigating to a relative
+directory whose name collided with a logical name.  This problem has
+been corrected by adding directory syntax to relative path names, thus
+preventing logical name translation.
+.PP
+Win32
+.IP \(bu 4
+A memory leak in the \fBfork()\fR emulation has been fixed.
+.IP \(bu 4
+The return value of the \fBioctl()\fR built-in function was accidentally
+broken in 5.8.0.  This has been corrected.
+.IP \(bu 4
+The internal message loop executed by perl during blocking operations
+sometimes interfered with messages that were external to Perl.
+This often resulted in blocking operations terminating prematurely or
+returning incorrect results, when Perl was executing under environments
+that could generate Windows messages.  This has been corrected.
+.IP \(bu 4
+Pipes and sockets are now automatically in binary mode.
+.IP \(bu 4
+The four-argument form of \fBselect()\fR did not preserve $! (errno) properly
+when there were errors in the underlying call.  This is now fixed.
+.IP \(bu 4
+The "CR CR LF" problem of has been fixed, binmode(FH, ":crlf")
+is now effectively a no-op.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+All the warnings related to \fBpack()\fR and \fBunpack()\fR were made more
+informative and consistent.
+.ie n .SS "Changed ""A thread exited while %d threads were running"""
+.el .SS "Changed ""A thread exited while \f(CW%d\fP threads were running"""
+.IX Subsection "Changed ""A thread exited while %d threads were running"""
+The old version
+.PP
+.Vb 1
+\&    A thread exited while %d other threads were still running
+.Ve
+.PP
+was misleading because the "other" included also the thread giving
+the warning.
+.SS "Removed ""Attempt to clear a restricted hash"""
+.IX Subsection "Removed ""Attempt to clear a restricted hash"""
+It is not illegal to clear a restricted hash, so the warning
+was removed.
+.SS "New ""Illegal declaration of anonymous subroutine"""
+.IX Subsection "New ""Illegal declaration of anonymous subroutine"""
+You must specify the block of code for \f(CW\*(C`sub\*(C'\fR.
+.SS "Changed ""Invalid range ""%s"" in transliteration operator"""
+.IX Subsection "Changed ""Invalid range ""%s"" in transliteration operator"""
+The old version
+.PP
+.Vb 1
+\&    Invalid [] range "%s" in transliteration operator
+.Ve
+.PP
+was simply wrong because there are no "[] ranges" in tr///.
+.SS "New ""Missing control char name in \ec"""
+.IX Subsection "New ""Missing control char name in c"""
+Self-explanatory.
+.ie n .SS "New ""Newline in left-justified string for %s"""
+.el .SS "New ""Newline in left-justified string for \f(CW%s\fP"""
+.IX Subsection "New ""Newline in left-justified string for %s"""
+The padding spaces would appear after the newline, which is
+probably not what you had in mind.
+.ie n .SS "New ""Possible precedence problem on bitwise %c operator"""
+.el .SS "New ""Possible precedence problem on bitwise \f(CW%c\fP operator"""
+.IX Subsection "New ""Possible precedence problem on bitwise %c operator"""
+If you think this
+.PP
+.Vb 1
+\&    $x & $y == 0
+.Ve
+.PP
+tests whether the bitwise AND of \f(CW$x\fR and \f(CW$y\fR is zero,
+you will like this warning.
+.SS "New ""Pseudo-hashes are deprecated"""
+.IX Subsection "New ""Pseudo-hashes are deprecated"""
+This warning should have been already in 5.8.0, since they are.
+.ie n .SS "New ""\fBread()\fP on %s filehandle %s"""
+.el .SS "New ""\fBread()\fP on \f(CW%s\fP filehandle \f(CW%s\fP"""
+.IX Subsection "New ""read() on %s filehandle %s"""
+You cannot \fBread()\fR (or \fBsysread()\fR) from a closed or unopened filehandle.
+.SS "New ""5.005 threads are deprecated"""
+.IX Subsection "New ""5.005 threads are deprecated"""
+This warning should have been already in 5.8.0, since they are.
+.SS "New ""Tied variable freed while still in use"""
+.IX Subsection "New ""Tied variable freed while still in use"""
+Something pulled the plug on a live tied variable, Perl plays
+safe by bailing out.
+.SS "New ""To%s: illegal mapping '%s'"""
+.IX Subsection "New ""To%s: illegal mapping '%s'"""
+An illegal user-defined Unicode casemapping was specified.
+.SS "New ""Use of freed value in iteration"""
+.IX Subsection "New ""Use of freed value in iteration"""
+Something modified the values being iterated over.  This is not good.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+These news matter to you only if you either write XS code or like to
+know about or hack Perl internals (using Devel::Peek or any of the
+\&\f(CW\*(C`B::\*(C'\fR modules counts), or like to run Perl with the \f(CW\*(C`\-D\*(C'\fR option.
+.PP
+The embedding examples of perlembed have been reviewed to be
+up to date and consistent: for example, the correct use of
+\&\fBPERL_SYS_INIT3()\fR and \fBPERL_SYS_TERM()\fR.
+.PP
+Extensive reworking of the pad code (the code responsible
+for lexical variables) has been conducted by Dave Mitchell.
+.PP
+Extensive work on the v\-strings by John Peacock.
+.PP
+UTF\-8 length and position cache: to speed up the handling of Unicode
+(UTF\-8) scalars, a cache was introduced.  Potential problems exist if
+an extension bypasses the official APIs and directly modifies the PV
+of an SV: the UTF\-8 cache does not get cleared as it should.
+.PP
+APIs obsoleted in Perl 5.8.0, like sv_2pv, sv_catpvn, sv_catsv,
+sv_setsv, are again available.
+.PP
+Certain Perl core C APIs like cxinc and regatom are no longer
+available at all to code outside the Perl core of the Perl core
+extensions.  This is intentional.  They never should have been
+available with the shorter names, and if you application depends on
+them, you should (be ashamed and) contact perl5\-porters to discuss
+what are the proper APIs.
+.PP
+Certain Perl core C APIs like \f(CW\*(C`Perl_list\*(C'\fR are no longer available
+without their \f(CW\*(C`Perl_\*(C'\fR prefix.  If your XS module stops working
+because some functions cannot be found, in many cases a simple fix is
+to add the \f(CW\*(C`Perl_\*(C'\fR prefix to the function and the thread context
+\&\f(CW\*(C`aTHX_\*(C'\fR as the first argument of the function call.  This is also how
+it should always have been done: letting the Perl_\-less forms to leak
+from the core was an accident.  For cleaner embedding you can also
+force this for all APIs by defining at compile time the cpp define
+PERL_NO_SHORT_NAMES.
+.PP
+\&\fBPerl_save_bool()\fR has been added.
+.PP
+Regexp objects (those created with \f(CW\*(C`qr\*(C'\fR) now have S\-magic rather than
+R\-magic.  This fixed regexps of the form /...(??{...;$x})/ to no
+longer ignore changes made to \f(CW$x\fR.  The S\-magic avoids dropping
+the caching optimization and making (??{...}) constructs obscenely
+slow (and consequently useless).  See also "Magic Variables" in perlguts.
+Regexp::Copy was affected by this change.
+.PP
+The Perl internal debugging macros \fBDEBUG()\fR and \fBDEB()\fR have been renamed
+to \fBPERL_DEBUG()\fR and \fBPERL_DEB()\fR to avoid namespace conflicts.
+.PP
+\&\f(CW\*(C`\-DL\*(C'\fR removed (the leaktest had been broken and unsupported for years,
+use alternative debugging mallocs or tools like valgrind and Purify).
+.PP
+Verbose modifier \f(CW\*(C`v\*(C'\fR added for \f(CW\*(C`\-DXv\*(C'\fR and \f(CW\*(C`\-Dsv\*(C'\fR, see perlrun.
+.SH "New Tests"
+.IX Header "New Tests"
+In Perl 5.8.0 there were about 69000 separate tests in about 700 test files,
+in Perl 5.8.1 there are about 77000 separate tests in about 780 test files.
+The exact numbers depend on the Perl configuration and on the operating
+system platform.
+.SH "Known Problems"
+.IX Header "Known Problems"
+The hash randomisation mentioned in "Incompatible Changes" is definitely
+problematic: it will wake dormant bugs and shake out bad assumptions.
+.PP
+If you want to use mod_perl 2.x with Perl 5.8.1, you will need
+mod_perl\-1.99_10 or higher.  Earlier versions of mod_perl 2.x
+do not work with the randomised hashes.  (mod_perl 1.x works fine.)
+You will also need Apache::Test 1.04 or higher.
+.PP
+Many of the rarer platforms that worked 100% or pretty close to it
+with perl 5.8.0 have been left a little bit untended since their
+maintainers have been otherwise busy lately, and therefore there will
+be more failures on those platforms.  Such platforms include Mac OS
+Classic, IBM z/OS (and other EBCDIC platforms), and NetWare.  The most
+common Perl platforms (Unix and Unix-like, Microsoft platforms, and
+VMS) have large enough testing and expert population that they are
+doing well.
+.SS "Tied hashes in scalar context"
+.IX Subsection "Tied hashes in scalar context"
+Tied hashes do not currently return anything useful in scalar context,
+for example when used as boolean tests:
+.PP
+.Vb 1
+\&        if (%tied_hash) { ... }
+.Ve
+.PP
+The current nonsensical behaviour is always to return false,
+regardless of whether the hash is empty or has elements.
+.PP
+The root cause is that there is no interface for the implementors of
+tied hashes to implement the behaviour of a hash in scalar context.
+.SS "Net::Ping 450_service and 510_ping_udp failures"
+.IX Subsection "Net::Ping 450_service and 510_ping_udp failures"
+The subtests 9 and 18 of lib/Net/Ping/t/450_service.t, and the
+subtest 2 of lib/Net/Ping/t/510_ping_udp.t might fail if you have
+an unusual networking setup.  For example in the latter case the
+test is trying to send a UDP ping to the IP address 127.0.0.1.
+.SS B::C
+.IX Subsection "B::C"
+The C\-generating compiler backend B::C (the frontend being
+\&\f(CW\*(C`perlcc \-c\*(C'\fR) is even more broken than it used to be because of
+the extensive lexical variable changes.  (The good news is that
+B::Bytecode and ByteLoader are better than they used to be.)
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+.SS "EBCDIC Platforms"
+.IX Subsection "EBCDIC Platforms"
+IBM z/OS and other EBCDIC platforms continue to be problematic
+regarding Unicode support.  Many Unicode tests are skipped when
+they really should be fixed.
+.SS "Cygwin 1.5 problems"
+.IX Subsection "Cygwin 1.5 problems"
+In Cygwin 1.5 the \fIio/tell\fR and \fIop/sysio\fR tests have failures for
+some yet unknown reason.  In 1.5.5 the threads tests stress_cv,
+stress_re, and stress_string are failing unless the environment
+variable PERLIO is set to "perlio" (which makes also the io/tell
+failure go away).
+.PP
+Perl 5.8.1 does build and work well with Cygwin 1.3: with (uname \-a)
+\&\f(CW\*(C`CYGWIN_NT\-5.0 ... 1.3.22(0.78/3/2) 2003\-03\-18 09:20 i686 ...\*(C'\fR
+a 100% "make test"  was achieved with \f(CW\*(C`Configure \-des \-Duseithreads\*(C'\fR.
+.SS "HP-UX: HP cc warnings about sendfile and sendpath"
+.IX Subsection "HP-UX: HP cc warnings about sendfile and sendpath"
+With certain HP C compiler releases (e.g. B.11.11.02) you will
+get many warnings like this (lines wrapped for easier reading):
+.PP
+.Vb 6
+\&  cc: "/usr/include/sys/socket.h", line 504: warning 562:
+\&    Redeclaration of "sendfile" with a different storage class specifier:
+\&      "sendfile" will have internal linkage.
+\&  cc: "/usr/include/sys/socket.h", line 505: warning 562:
+\&    Redeclaration of "sendpath" with a different storage class specifier:
+\&      "sendpath" will have internal linkage.
+.Ve
+.PP
+The warnings show up both during the build of Perl and during certain
+lib/ExtUtils tests that invoke the C compiler.  The warning, however,
+is not serious and can be ignored.
+.SS "IRIX: t/uni/tr_7jis.t falsely failing"
+.IX Subsection "IRIX: t/uni/tr_7jis.t falsely failing"
+The test t/uni/tr_7jis.t is known to report failure under 'make test'
+or the test harness with certain releases of IRIX (at least IRIX 6.5
+and MIPSpro Compilers Version 7.3.1.1m), but if run manually the test
+fully passes.
+.SS "Mac OS X: no usemymalloc"
+.IX Subsection "Mac OS X: no usemymalloc"
+The Perl malloc (\f(CW\*(C`\-Dusemymalloc\*(C'\fR) does not work at all in Mac OS X.
+This is not that serious, though, since the native malloc works just
+fine.
+.SS "Tru64: No threaded builds with GNU cc (gcc)"
+.IX Subsection "Tru64: No threaded builds with GNU cc (gcc)"
+In the latest Tru64 releases (e.g. v5.1B or later) gcc cannot be used
+to compile a threaded Perl (\-Duseithreads) because the system
+\&\f(CW\*(C`<pthread.h>\*(C'\fR file doesn't know about gcc.
+.SS "Win32: sysopen, sysread, syswrite"
+.IX Subsection "Win32: sysopen, sysread, syswrite"
+As of the 5.8.0 release, \fBsysopen()\fR/\fBsysread()\fR/\fBsyswrite()\fR do not behave
+like they used to in 5.6.1 and earlier with respect to "text" mode.
+These built-ins now always operate in "binary" mode (even if \fBsysopen()\fR
+was passed the O_TEXT flag, or if \fBbinmode()\fR was used on the file
+handle).  Note that this issue should only make a difference for disk
+files, as sockets and pipes have always been in "binary" mode in the
+Windows port.  As this behavior is currently considered a bug,
+compatible behavior may be re-introduced in a future release.  Until
+then, the use of \fBsysopen()\fR, \fBsysread()\fR and \fBsyswrite()\fR is not supported
+for "text" mode operations.
+.SH "Future Directions"
+.IX Header "Future Directions"
+The following things \fBmight\fR happen in future.  The first publicly
+available releases having these characteristics will be the developer
+releases Perl 5.9.x, culminating in the Perl 5.10.0 release.  These
+are our best guesses at the moment: we reserve the right to rethink.
+.IP \(bu 4
+PerlIO will become The Default.  Currently (in Perl 5.8.x) the stdio
+library is still used if Perl thinks it can use certain tricks to
+make stdio go \fBreally\fR fast.  For future releases our goal is to
+make PerlIO go even faster.
+.IP \(bu 4
+A new feature called \fIassertions\fR will be available.  This means that
+one can have code called assertions sprinkled in the code: usually
+they are optimised away, but they can be enabled with the \f(CW\*(C`\-A\*(C'\fR option.
+.IP \(bu 4
+A new operator \f(CW\*(C`//\*(C'\fR (defined-or) will be available.  This means that
+one will be able to say
+.Sp
+.Vb 1
+\&    $a // $b
+.Ve
+.Sp
+instead of
+.Sp
+.Vb 1
+\&   defined $a ? $a : $b
+.Ve
+.Sp
+and
+.Sp
+.Vb 1
+\&   $c //= $d;
+.Ve
+.Sp
+instead of
+.Sp
+.Vb 1
+\&   $c = $d unless defined $c;
+.Ve
+.Sp
+The operator will have the same precedence and associativity as \f(CW\*(C`||\*(C'\fR.
+A source code patch against the Perl 5.8.1 sources will be available
+in CPAN as \fIauthors/id/H/HM/HMBRAND/dor\-5.8.1.diff\fR.
+.IP \(bu 4
+\&\f(CWunpack()\fR will default to unpacking the \f(CW$_\fR.
+.IP \(bu 4
+Various Copy-On-Write techniques will be investigated in hopes
+of speeding up Perl.
+.IP \(bu 4
+CPANPLUS, Inline, and Module::Build will become core modules.
+.IP \(bu 4
+The ability to write true lexically scoped pragmas will be introduced.
+.IP \(bu 4
+Work will continue on the bytecompiler and byteloader.
+.IP \(bu 4
+v\-strings as they currently exist are scheduled to be deprecated.  The
+v\-less form (1.2.3) will become a "version object" when used with \f(CW\*(C`use\*(C'\fR,
+\&\f(CW\*(C`require\*(C'\fR, and \f(CW$VERSION\fR.  $^V will also be a "version object" so the
+printf("%vd",...) construct will no longer be needed.  The v\-ful version
+(v1.2.3) will become obsolete.  The equivalence of strings and v\-strings (e.g.
+that currently 5.8.0 is equal to "\e5\e8\e0") will go away.  \fBThere may be no
+deprecation warning for v\-strings\fR, though: it is quite hard to detect when
+v\-strings are being used safely, and when they are not.
+.IP \(bu 4
+5.005 Threads Will Be Removed
+.IP \(bu 4
+The \f(CW$*\fR Variable Will Be Removed
+(it was deprecated a long time ago)
+.IP \(bu 4
+Pseudohashes Will Be Removed
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org/ .  There may also be
+information at http://www.perl.com/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl582delta.1 b/upstream/mageia-cauldron/man1/perl582delta.1
new file mode 100644
index 00000000..9a68c77d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl582delta.1
@@ -0,0 +1,197 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL582DELTA 1"
+.TH PERL582DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl582delta \- what is new for perl v5.8.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.1 release and
+the 5.8.2 release.
+.PP
+If you are upgrading from an earlier release such as 5.6.1, first read
+the perl58delta, which describes differences between 5.6.0 and
+5.8.0, and the perl581delta, which describes differences between
+5.8.0 and 5.8.1.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+For threaded builds for modules calling certain re-entrant system calls,
+binary compatibility was accidentally lost between 5.8.0 and 5.8.1.
+Binary compatibility with 5.8.0 has been restored in 5.8.2, which
+necessitates breaking compatibility with 5.8.1. We see this as the
+lesser of two evils.
+.PP
+This will only affect people who have a threaded perl 5.8.1, and compiled
+modules which use these calls, and now attempt to run the compiled modules
+with 5.8.2. The fix is to re-compile and re-install the modules using 5.8.2.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Hash Randomisation"
+.IX Subsection "Hash Randomisation"
+The hash randomisation introduced with 5.8.1 has been amended. It
+transpired that although the implementation introduced in 5.8.1 was source
+compatible with 5.8.0, it was not binary compatible in certain cases. 5.8.2
+contains an improved implementation which is both source and binary
+compatible with both 5.8.0 and 5.8.1, and remains robust against the form of
+attack which prompted the change for 5.8.1.
+.PP
+We are grateful to the Debian project for their input in this area.
+See "Algorithmic Complexity Attacks" in perlsec for the original
+rationale behind this change.
+.SS Threading
+.IX Subsection "Threading"
+Several memory leaks associated with variables shared between threads
+have been fixed.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "Updated Modules And Pragmata"
+.IX Subsection "Updated Modules And Pragmata"
+The following modules and pragmata have been updated since Perl 5.8.1:
+.IP Devel::PPPort 4
+.IX Item "Devel::PPPort"
+.PD 0
+.IP Digest::MD5 4
+.IX Item "Digest::MD5"
+.IP I18N::LangTags 4
+.IX Item "I18N::LangTags"
+.IP libnet 4
+.IX Item "libnet"
+.IP MIME::Base64 4
+.IX Item "MIME::Base64"
+.IP Pod::Perldoc 4
+.IX Item "Pod::Perldoc"
+.IP strict 4
+.IX Item "strict"
+.PD
+Documentation improved
+.IP Tie::Hash 4
+.IX Item "Tie::Hash"
+Documentation improved
+.IP Time::HiRes 4
+.IX Item "Time::HiRes"
+.PD 0
+.IP Unicode::Collate 4
+.IX Item "Unicode::Collate"
+.IP Unicode::Normalize 4
+.IX Item "Unicode::Normalize"
+.IP UNIVERSAL 4
+.IX Item "UNIVERSAL"
+.PD
+Documentation improved
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+Some syntax errors involving unrecognized filetest operators are now handled
+correctly by the parser.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+Interpreter initialization is more complete when \-DMULTIPLICITY is off.
+This should resolve problems with initializing and destroying the Perl
+interpreter more than once in a single process.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+Dynamic linker flags have been tweaked for Solaris and OS X, which should
+solve problems seen while building some XS modules.
+.PP
+Bugs in OS/2 sockets and tmpfile have been fixed.
+.PP
+In OS X \f(CW\*(C`setreuid\*(C'\fR and friends are troublesome \- perl will now work
+around their problems as best possible.
+.SH "Future Directions"
+.IX Header "Future Directions"
+Starting with 5.8.3 we intend to make more frequent maintenance releases,
+with a smaller number of changes in each. The intent is to propagate
+bug fixes out to stable releases more rapidly and make upgrading stable
+releases less of an upheaval. This should give end users more
+flexibility in their choice of upgrade timing, and allow them easier
+assessment of the impact of upgrades. The current plan is for code freezes
+as follows
+.IP \(bu 4
+5.8.3 23:59:59 GMT, Wednesday December 31st 2003
+.IP \(bu 4
+5.8.4 23:59:59 GMT, Wednesday March 31st 2004
+.IP \(bu 4
+5.8.5 23:59:59 GMT, Wednesday June 30th 2004
+.PP
+with the release following soon after, when testing is complete.
+.PP
+See "Future Directions" in perl581delta for more soothsaying.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org/.  There may also be
+information at http://www.perl.com/, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl583delta.1 b/upstream/mageia-cauldron/man1/perl583delta.1
new file mode 100644
index 00000000..59dae691
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl583delta.1
@@ -0,0 +1,251 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL583DELTA 1"
+.TH PERL583DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl583delta \- what is new for perl v5.8.3
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.2 release and
+the 5.8.3 release.
+.PP
+If you are upgrading from an earlier release such as 5.6.1, first read
+the perl58delta, which describes differences between 5.6.0 and
+5.8.0, and the perl581delta and perl582delta, which describe differences
+between 5.8.0, 5.8.1 and 5.8.2
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes incompatible with 5.8.2.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+A \f(CW\*(C`SCALAR\*(C'\fR method is now available for tied hashes. This is called when
+a tied hash is used in scalar context, such as
+.PP
+.Vb 3
+\&    if (%tied_hash) {
+\&        ...
+\&    }
+.Ve
+.PP
+The old behaviour was that \f(CW%tied_hash\fR would return whatever would have been
+returned for that hash before the hash was tied (so usually 0). The new
+behaviour in the absence of a SCALAR method is to return TRUE if in the
+middle of an \f(CW\*(C`each\*(C'\fR iteration, and otherwise call FIRSTKEY to check if the
+hash is empty (making sure that a subsequent \f(CW\*(C`each\*(C'\fR will also begin by
+calling FIRSTKEY). Please see "SCALAR" in perltie for the full details and
+caveats.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.IP CGI 4
+.IX Item "CGI"
+.PD 0
+.IP Cwd 4
+.IX Item "Cwd"
+.IP Digest 4
+.IX Item "Digest"
+.IP Digest::MD5 4
+.IX Item "Digest::MD5"
+.IP Encode 4
+.IX Item "Encode"
+.IP File::Spec 4
+.IX Item "File::Spec"
+.IP FindBin 4
+.IX Item "FindBin"
+.PD
+A function \f(CW\*(C`again\*(C'\fR is provided to resolve problems where modules in different
+directories wish to use FindBin.
+.IP List::Util 4
+.IX Item "List::Util"
+You can now weaken references to read only values.
+.IP Math::BigInt 4
+.IX Item "Math::BigInt"
+.PD 0
+.IP PodParser 4
+.IX Item "PodParser"
+.IP Pod::Perldoc 4
+.IX Item "Pod::Perldoc"
+.IP POSIX 4
+.IX Item "POSIX"
+.IP Unicode::Collate 4
+.IX Item "Unicode::Collate"
+.IP Unicode::Normalize 4
+.IX Item "Unicode::Normalize"
+.IP Test::Harness 4
+.IX Item "Test::Harness"
+.IP threads::shared 4
+.IX Item "threads::shared"
+.PD
+\&\f(CW\*(C`cond_wait\*(C'\fR has a new two argument form. \f(CW\*(C`cond_timedwait\*(C'\fR has been added.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+\&\f(CW\*(C`find2perl\*(C'\fR now assumes \f(CW\*(C`\-print\*(C'\fR as a default action. Previously, it
+needed to be specified explicitly.
+.PP
+A new utility, \f(CW\*(C`prove\*(C'\fR, makes it easy to run an individual regression test
+at the command line. \f(CW\*(C`prove\*(C'\fR is part of Test::Harness, which users of earlier
+Perl versions can install from CPAN.
+.SH "New Documentation"
+.IX Header "New Documentation"
+The documentation has been revised in places to produce more standard manpages.
+.PP
+The documentation for the special code blocks (BEGIN, CHECK, INIT, END)
+has been improved.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+Perl now builds on OpenVMS I64
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+Using \fBsubstr()\fR on a UTF8 string could cause subsequent accesses on that
+string to return garbage. This was due to incorrect UTF8 offsets being
+cached, and is now fixed.
+.PP
+\&\fBjoin()\fR could return garbage when the same \fBjoin()\fR statement was used to
+process 8 bit data having earlier processed UTF8 data, due to the flags
+on that statement's temporary workspace not being reset correctly. This
+is now fixed.
+.PP
+\&\f(CW\*(C`$a .. $b\*(C'\fR will now work as expected when either \f(CW$a\fR or \f(CW$b\fR is \f(CW\*(C`undef\*(C'\fR
+.PP
+Using Unicode keys with tied hashes should now work correctly.
+.PP
+Reading $^E now preserves $!. Previously, the C code implementing $^E
+did not preserve \f(CW\*(C`errno\*(C'\fR, so reading $^E could cause \f(CW\*(C`errno\*(C'\fR and therefore
+\&\f(CW$!\fR to change unexpectedly.
+.PP
+Reentrant functions will (once more) work with C++. 5.8.2 introduced a bugfix
+which accidentally broke the compilation of Perl extensions written in C++
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+The fatal error "DESTROY created new reference to dead object" is now
+documented in perldiag.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+The hash code has been refactored to reduce source duplication. The
+external interface is unchanged, and aside from the bug fixes described
+above, there should be no change in behaviour.
+.PP
+\&\f(CW\*(C`hv_clear_placeholders\*(C'\fR is now part of the perl API
+.PP
+Some C macros have been tidied. In particular macros which create temporary
+local variables now name these variables more defensively, which should
+avoid bugs where names clash.
+.PP
+<signal.h> is now always included.
+.SH "Configuration and Building"
+.IX Header "Configuration and Building"
+\&\f(CW\*(C`Configure\*(C'\fR now invokes callbacks regardless of the value of the variable
+they are called for. Previously callbacks were only invoked in the
+\&\f(CW\*(C`case $variable $define)\*(C'\fR branch. This change should only affect platform
+maintainers writing configuration hints files.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+The regression test ext/threads/shared/t/wait.t fails on early RedHat 9
+and HP-UX 10.20 due to bugs in their threading implementations.
+RedHat users should see https://rhn.redhat.com/errata/RHBA\-2003\-136.html
+and consider upgrading their glibc.
+.SH "Known Problems"
+.IX Header "Known Problems"
+Detached threads aren't supported on Windows yet, as they may lead to 
+memory access violation problems.
+.PP
+There is a known race condition opening scripts in \f(CW\*(C`suidperl\*(C'\fR. \f(CW\*(C`suidperl\*(C'\fR
+is neither built nor installed by default, and has been deprecated since
+perl 5.8.0. You are advised to replace use of suidperl with tools such
+as sudo ( http://www.courtesan.com/sudo/ )
+.PP
+We have a backlog of unresolved bugs. Dealing with bugs and bug reports
+is unglamorous work; not something ideally suited to volunteer labour,
+but that is all that we have.
+.PP
+The perl5 development team are implementing changes to help address this
+problem, which should go live in early 2004.
+.SH "Future Directions"
+.IX Header "Future Directions"
+Code freeze for the next maintenance release (5.8.4) is on March 31st 2004,
+with release expected by mid April. Similarly 5.8.5's freeze will be at
+the end of June, with release by mid July.
+.SH Obituary
+.IX Header "Obituary"
+Iain 'Spoon' Truskett, Perl hacker, author of perlreref and
+contributor to CPAN, died suddenly on 29th December 2003, aged 24.
+He will be missed.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl584delta.1 b/upstream/mageia-cauldron/man1/perl584delta.1
new file mode 100644
index 00000000..b24bcdeb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl584delta.1
@@ -0,0 +1,299 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL584DELTA 1"
+.TH PERL584DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl584delta \- what is new for perl v5.8.4
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.3 release and
+the 5.8.4 release.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+Many minor bugs have been fixed. Scripts which happen to rely on previously
+erroneous behaviour will consider these fixes as incompatible changes :\-)
+You are advised to perform sufficient acceptance testing on this release
+to satisfy yourself that this does not affect you, before putting this
+release into production.
+.PP
+The diagnostic output of Carp has been changed slightly, to add a space after
+the comma between arguments. This makes it much easier for tools such as
+web browsers to wrap it, but might confuse any automatic tools which perform
+detailed parsing of Carp output.
+.PP
+The internal dump output has been improved, so that non-printable characters
+such as newline and backspace are output in \f(CW\*(C`\ex\*(C'\fR notation, rather than
+octal. This might just confuse non-robust tools which parse the output of
+modules such as Devel::Peek.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Malloc wrapping"
+.IX Subsection "Malloc wrapping"
+Perl can now be built to detect attempts to assign pathologically large chunks
+of memory.  Previously such assignments would suffer from integer wrap-around
+during size calculations causing a misallocation, which would crash perl, and
+could theoretically be used for "stack smashing" attacks.  The wrapping
+defaults to enabled on platforms where we know it works (most AIX
+configurations, BSDi, Darwin, DEC OSF/1, FreeBSD, HP/UX, GNU Linux, OpenBSD,
+Solaris, VMS and most Win32 compilers) and defaults to disabled on other
+platforms.
+.SS "Unicode Character Database 4.0.1"
+.IX Subsection "Unicode Character Database 4.0.1"
+The copy of the Unicode Character Database included in Perl 5.8 has
+been updated to 4.0.1 from 4.0.0.
+.SS "suidperl less insecure"
+.IX Subsection "suidperl less insecure"
+Paul Szabo has analysed and patched \f(CW\*(C`suidperl\*(C'\fR to remove existing known
+insecurities. Currently there are no known holes in \f(CW\*(C`suidperl\*(C'\fR, but previous
+experience shows that we cannot be confident that these were the last. You may
+no longer invoke the set uid perl directly, so to preserve backwards
+compatibility with scripts that invoke #!/usr/bin/suidperl the only set uid
+binary is now \f(CW\*(C`sperl5.8.\*(C'\fR\fIn\fR (\f(CW\*(C`sperl5.8.4\*(C'\fR for this release). \f(CW\*(C`suidperl\*(C'\fR
+is installed as a hard link to \f(CW\*(C`perl\*(C'\fR; both \f(CW\*(C`suidperl\*(C'\fR and \f(CW\*(C`perl\*(C'\fR will
+invoke \f(CW\*(C`sperl5.8.4\*(C'\fR automatically the set uid binary, so this change should
+be completely transparent.
+.PP
+For new projects the core perl team would strongly recommend that you use
+dedicated, single purpose security tools such as \f(CW\*(C`sudo\*(C'\fR in preference to
+\&\f(CW\*(C`suidperl\*(C'\fR.
+.SS format
+.IX Subsection "format"
+In addition to bug fixes, \f(CW\*(C`format\*(C'\fR's features have been enhanced. See
+perlform
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+The (mis)use of \f(CW\*(C`/tmp\*(C'\fR in core modules and documentation has been tidied up.
+Some modules available both within the perl core and independently from CPAN
+("dual-life modules") have not yet had these changes applied; the changes
+will be integrated into future stable perl releases as the modules are
+updated on CPAN.
+.SS "Updated modules"
+.IX Subsection "Updated modules"
+.IP Attribute::Handlers 4
+.IX Item "Attribute::Handlers"
+.PD 0
+.IP B 4
+.IX Item "B"
+.IP Benchmark 4
+.IX Item "Benchmark"
+.IP CGI 4
+.IX Item "CGI"
+.IP Carp 4
+.IX Item "Carp"
+.IP Cwd 4
+.IX Item "Cwd"
+.IP Exporter 4
+.IX Item "Exporter"
+.IP File::Find 4
+.IX Item "File::Find"
+.IP IO 4
+.IX Item "IO"
+.IP IPC::Open3 4
+.IX Item "IPC::Open3"
+.IP Local::Maketext 4
+.IX Item "Local::Maketext"
+.IP Math::BigFloat 4
+.IX Item "Math::BigFloat"
+.IP Math::BigInt 4
+.IX Item "Math::BigInt"
+.IP Math::BigRat 4
+.IX Item "Math::BigRat"
+.IP MIME::Base64 4
+.IX Item "MIME::Base64"
+.IP ODBM_File 4
+.IX Item "ODBM_File"
+.IP POSIX 4
+.IX Item "POSIX"
+.IP Shell 4
+.IX Item "Shell"
+.IP Socket 4
+.IX Item "Socket"
+.PD
+There is experimental support for Linux abstract Unix domain sockets.
+.IP Storable 4
+.IX Item "Storable"
+.PD 0
+.IP Switch 4
+.IX Item "Switch"
+.PD
+Synced with its CPAN version 2.10
+.IP Sys::Syslog 4
+.IX Item "Sys::Syslog"
+\&\f(CWsyslog()\fR can now use numeric constants for facility names and priorities,
+in addition to strings.
+.IP Term::ANSIColor 4
+.IX Item "Term::ANSIColor"
+.PD 0
+.IP Time::HiRes 4
+.IX Item "Time::HiRes"
+.IP Unicode::UCD 4
+.IX Item "Unicode::UCD"
+.IP Win32 4
+.IX Item "Win32"
+.PD
+Win32.pm/Win32.xs has moved from the libwin32 module to core Perl
+.IP base 4
+.IX Item "base"
+.PD 0
+.IP open 4
+.IX Item "open"
+.IP threads 4
+.IX Item "threads"
+.PD
+Detached threads are now also supported on Windows.
+.IP utf8 4
+.IX Item "utf8"
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.PD 0
+.IP \(bu 4
+.PD
+Accelerated Unicode case mappings (\f(CW\*(C`/i\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, etc).
+.IP \(bu 4
+In place sort optimised (eg \f(CW\*(C`@a = sort @a\*(C'\fR)
+.IP \(bu 4
+Unnecessary assignment optimised away in
+.Sp
+.Vb 3
+\&  my $s = undef;
+\&  my @a = ();
+\&  my %h = ();
+.Ve
+.IP \(bu 4
+Optimised \f(CW\*(C`map\*(C'\fR in scalar context
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+The Perl debugger (\fIlib/perl5db.pl\fR) can now save all debugger commands for
+sourcing later, and can display the parent inheritance tree of a given class.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+The build process on both VMS and Windows has had several minor improvements
+made. On Windows Borland's C compiler can now compile perl with PerlIO and/or
+USE_LARGE_FILES enabled.
+.PP
+\&\f(CW\*(C`perl.exe\*(C'\fR on Windows now has a "Camel" logo icon. The use of a camel with
+the topic of Perl is a trademark of O'Reilly and Associates Inc., and is used
+with their permission (ie distribution of the source, compiling a Windows
+executable from it, and using that executable locally). Use of the supplied
+camel for anything other than a perl executable's icon is specifically not
+covered, and anyone wishing to redistribute perl binaries \fIwith\fR the icon
+should check directly with O'Reilly beforehand.
+.PP
+Perl should build cleanly on Stratus VOS once more.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+More utf8 bugs fixed, notably in how \f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chop\*(C'\fR, \f(CW\*(C`send\*(C'\fR, and
+\&\f(CW\*(C`syswrite\*(C'\fR and interact with utf8 data. Concatenation now works correctly
+when \f(CW\*(C`use bytes;\*(C'\fR is in scope.
+.PP
+Pragmata are now correctly propagated into (?{...}) constructions in regexps.
+Code such as
+.PP
+.Vb 1
+\&   my $x = qr{ ... (??{ $x }) ... };
+.Ve
+.PP
+will now (correctly) fail under use strict. (As the inner \f(CW$x\fR is and
+has always referred to \f(CW$::x\fR)
+.PP
+The "const in void context" warning has been suppressed for a constant in an
+optimised-away boolean expression such as \f(CW\*(C`5 || print;\*(C'\fR
+.PP
+\&\f(CW\*(C`perl \-i\*(C'\fR could \f(CWfchmod(stdin)\fR by mistake. This is serious if stdin is
+attached to a terminal, and perl is running as root. Now fixed.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+\&\f(CW\*(C`Carp\*(C'\fR and the internal diagnostic routines used by \f(CW\*(C`Devel::Peek\*(C'\fR have been
+made clearer, as described in "Incompatible Changes"
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+Some bugs have been fixed in the hash internals. Restricted hashes and
+their place holders are now allocated and deleted at slightly different times,
+but this should not be visible to user code.
+.SH "Future Directions"
+.IX Header "Future Directions"
+Code freeze for the next maintenance release (5.8.5) will be on 30th June
+2004, with release by mid July.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+This release is known not to build on Windows 95.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl585delta.1 b/upstream/mageia-cauldron/man1/perl585delta.1
new file mode 100644
index 00000000..ff22ce60
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl585delta.1
@@ -0,0 +1,233 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL585DELTA 1"
+.TH PERL585DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl585delta \- what is new for perl v5.8.5
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.4 release and
+the 5.8.5 release.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes incompatible with 5.8.4.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+Perl's regular expression engine now contains support for matching on the
+intersection of two Unicode character classes. You can also now refer to
+user-defined character classes from within other user defined character
+classes.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.IP \(bu 4
+Carp improved to work nicely with Safe. Carp's message reporting should now
+be anomaly free \- it will always print out line number information.
+.IP \(bu 4
+CGI upgraded to version 3.05
+.IP \(bu 4
+charnames now avoids clobbering \f(CW$_\fR
+.IP \(bu 4
+Digest upgraded to version 1.08
+.IP \(bu 4
+Encode upgraded to version 2.01
+.IP \(bu 4
+FileCache upgraded to version 1.04
+.IP \(bu 4
+libnet upgraded to version 1.19
+.IP \(bu 4
+Pod::Parser upgraded to version 1.28
+.IP \(bu 4
+Pod::Perldoc upgraded to version 3.13
+.IP \(bu 4
+Pod::LaTeX upgraded to version 0.57
+.IP \(bu 4
+Safe now works properly with Carp
+.IP \(bu 4
+Scalar-List-Utils upgraded to version 1.14
+.IP \(bu 4
+Shell's documentation has been re-written, and its historical partial
+auto-quoting of command arguments can now be disabled.
+.IP \(bu 4
+Test upgraded to version 1.25
+.IP \(bu 4
+Test::Harness upgraded to version 2.42
+.IP \(bu 4
+Time::Local upgraded to version 1.10
+.IP \(bu 4
+Unicode::Collate upgraded to version 0.40
+.IP \(bu 4
+Unicode::Normalize upgraded to version 0.30
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "Perl's debugger"
+.IX Subsection "Perl's debugger"
+The debugger can now emulate stepping backwards, by restarting and rerunning
+all bar the last command from a saved command history.
+.SS h2ph
+.IX Subsection "h2ph"
+\&\fIh2ph\fR is now able to understand a very limited set of C inline functions
+\&\-\- basically, the inline functions that look like CPP macros. This has
+been introduced to deal with some of the headers of the newest versions of
+the glibc. The standard warning still applies; to quote \fIh2ph\fR's
+documentation, \fIyou may need to dicker with the files produced\fR.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+Perl 5.8.5 should build cleanly from source on LynxOS.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The in-place sort optimisation introduced in 5.8.4 had a bug. For example,
+in code such as
+.Sp
+.Vb 1
+\&    @a = sort ($b, @a)
+.Ve
+.Sp
+the result would omit the value \f(CW$b\fR. This is now fixed.
+.IP \(bu 4
+The optimisation for unnecessary assignments introduced in 5.8.4 could give
+spurious warnings. This has been fixed.
+.IP \(bu 4
+Perl should now correctly detect and read BOM-marked and (BOMless) UTF\-16
+scripts of either endianness.
+.IP \(bu 4
+Creating a new thread when weak references exist was buggy, and would often
+cause warnings at interpreter destruction time. The known bug is now fixed.
+.IP \(bu 4
+Several obscure bugs involving manipulating Unicode strings with \f(CW\*(C`substr\*(C'\fR have
+been fixed.
+.IP \(bu 4
+Previously if Perl's file globbing function encountered a directory that it
+did not have permission to open it would return immediately, leading to
+unexpected truncation of the list of results. This has been fixed, to be
+consistent with Unix shells' globbing behaviour.
+.IP \(bu 4
+Thread creation time could vary wildly between identical runs. This was caused
+by a poor hashing algorithm in the thread cloning routines, which has now
+been fixed.
+.IP \(bu 4
+The internals of the ithreads implementation were not checking if OS-level
+thread creation had failed. threads\->\fBcreate()\fR now returns \f(CW\*(C`undef\*(C'\fR in if
+thread creation fails instead of crashing perl.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.IP \(bu 4
+Perl \-V has several improvements
+.RS 4
+.IP \(bu 4
+correctly outputs local patch names that contain embedded code snippets
+or other characters that used to confuse it.
+.IP \(bu 4
+arguments to \-V that look like regexps will give multiple lines of output.
+.IP \(bu 4
+a trailing colon suppresses the linefeed and ';'  terminator, allowing
+embedding of queries into shell commands.
+.IP \(bu 4
+a leading colon removes the 'name=' part of the response, allowing mapping to
+any name.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+When perl fails to find the specified script, it now outputs a second line
+suggesting that the user use the \f(CW\*(C`\-S\*(C'\fR flag:
+.Sp
+.Vb 3
+\&    $ perl5.8.5 missing.pl
+\&    Can\*(Aqt open perl script "missing.pl": No such file or directory.
+\&    Use \-S to search $PATH for it.
+.Ve
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+The Unicode character class files used by the regular expression engine are
+now built at build time from the supplied Unicode consortium data files,
+instead of being shipped prebuilt. This makes the compressed Perl source
+tarball about 200K smaller. A side effect is that the layout of files inside
+lib/unicore has changed.
+.SH "Known Problems"
+.IX Header "Known Problems"
+The regression test \fIt/uni/class.t\fR is now performing considerably more
+tests, and can take several minutes to run even on a fast machine.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+This release is known not to build on Windows 95.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl586delta.1 b/upstream/mageia-cauldron/man1/perl586delta.1
new file mode 100644
index 00000000..da306b0b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl586delta.1
@@ -0,0 +1,190 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL586DELTA 1"
+.TH PERL586DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl586delta \- what is new for perl v5.8.6
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.5 release and
+the 5.8.6 release.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes incompatible with 5.8.5.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+The perl interpreter is now more tolerant of UTF\-16\-encoded scripts.
+.PP
+On Win32, Perl can now use non-IFS compatible LSPs, which allows Perl to
+work in conjunction with firewalls such as McAfee Guardian. For full details
+see the file \fIREADME.win32\fR, particularly if you're running Win95.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.IP \(bu 4
+With the \f(CW\*(C`base\*(C'\fR pragma, an intermediate class with no fields used to messes
+up private fields in the base class. This has been fixed.
+.IP \(bu 4
+Cwd upgraded to version 3.01 (as part of the new PathTools distribution)
+.IP \(bu 4
+Devel::PPPort upgraded to version 3.03
+.IP \(bu 4
+File::Spec upgraded to version 3.01 (as part of the new PathTools distribution)
+.IP \(bu 4
+Encode upgraded to version 2.08
+.IP \(bu 4
+ExtUtils::MakeMaker remains at version 6.17, as later stable releases currently
+available on CPAN have some issues with core modules on some core platforms.
+.IP \(bu 4
+I18N::LangTags upgraded to version 0.35
+.IP \(bu 4
+Math::BigInt upgraded to version 1.73
+.IP \(bu 4
+Math::BigRat upgraded to version 0.13
+.IP \(bu 4
+MIME::Base64 upgraded to version 3.05
+.IP \(bu 4
+POSIX::sigprocmask function can now retrieve the current signal mask without
+also setting it.
+.IP \(bu 4
+Time::HiRes upgraded to version 1.65
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+Perl has a new \-dt command-line flag, which enables threads support in the
+debugger.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+\&\f(CW\*(C`reverse sort ...\*(C'\fR is now optimized to sort in reverse, avoiding the
+generation of a temporary intermediate list.
+.PP
+\&\f(CW\*(C`for (reverse @foo)\*(C'\fR now iterates in reverse, avoiding the generation of a
+temporary reversed list.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+The regexp engine is now more robust when given invalid utf8 input, as is
+sometimes generated by buggy XS modules.
+.PP
+\&\f(CW\*(C`foreach\*(C'\fR on threads::shared array used to be able to crash Perl. This bug
+has now been fixed.
+.PP
+A regexp in \f(CW\*(C`STDOUT\*(C'\fR's destructor used to coredump, because the regexp pad
+was already freed. This has been fixed.
+.PP
+\&\f(CW\*(C`goto &\*(C'\fR is now more robust \- bugs in deep recursion and chained \f(CW\*(C`goto &\*(C'\fR
+have been fixed.
+.PP
+Using \f(CW\*(C`delete\*(C'\fR on an array no longer leaks memory. A \f(CW\*(C`pop\*(C'\fR of an item from a
+shared array reference no longer causes a leak.
+.PP
+\&\f(CWeval_sv()\fR failing a taint test could corrupt the stack \- this has been
+fixed.
+.PP
+On platforms with 64 bit pointers numeric comparison operators used to
+erroneously compare the addresses of references that are overloaded, rather
+than using the overloaded values. This has been fixed.
+.PP
+\&\f(CW\*(C`read\*(C'\fR into a UTF8\-encoded buffer with an offset off the end of the buffer
+no longer mis-calculates buffer lengths.
+.PP
+Although Perl has promised since version 5.8 that \f(CWsort()\fR would be
+stable, the two cases \f(CW\*(C`sort {$b cmp $a}\*(C'\fR and \f(CW\*(C`sort {$b <=> $a}\*(C'\fR could
+produce non-stable sorts.   This is corrected in perl5.8.6.
+.PP
+Localising \f(CW$^D\fR no longer generates a diagnostic message about valid \-D
+flags.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+For \-t and \-T,
+   Too late for "\-T" option
+has been changed to the more informative
+   "\-T" is on the #! line, it must also be used on the command line
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+From now on all applications embedding perl will behave as if perl
+were compiled with \-DPERL_USE_SAFE_PUTENV.  See "Environment access" in
+the \fIINSTALL\fR file for details.
+.PP
+Most \f(CW\*(C`C\*(C'\fR source files now have comments at the top explaining their purpose,
+which should help anyone wishing to get an overview of the implementation.
+.SH "New Tests"
+.IX Header "New Tests"
+There are significantly more tests for the \f(CW\*(C`B\*(C'\fR suite of modules.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl587delta.1 b/upstream/mageia-cauldron/man1/perl587delta.1
new file mode 100644
index 00000000..6dd21073
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl587delta.1
@@ -0,0 +1,303 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL587DELTA 1"
+.TH PERL587DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl587delta \- what is new for perl v5.8.7
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.6 release and
+the 5.8.7 release.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes incompatible with 5.8.6.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Unicode Character Database 4.1.0"
+.IX Subsection "Unicode Character Database 4.1.0"
+The copy of the Unicode Character Database included in Perl 5.8 has
+been updated to 4.1.0 from 4.0.1. See
+<http://www.unicode.org/versions/Unicode4.1.0/#NotableChanges> for the
+notable changes.
+.SS "suidperl less insecure"
+.IX Subsection "suidperl less insecure"
+A pair of exploits in \f(CW\*(C`suidperl\*(C'\fR involving debugging code have been closed.
+.PP
+For new projects the core perl team strongly recommends that you use
+dedicated, single purpose security tools such as \f(CW\*(C`sudo\*(C'\fR in preference to
+\&\f(CW\*(C`suidperl\*(C'\fR.
+.SS "Optional site customization script"
+.IX Subsection "Optional site customization script"
+The perl interpreter can be built to allow the use of a site customization
+script. By default this is not enabled, to be consistent with previous perl
+releases. To use this, add \f(CW\*(C`\-Dusesitecustomize\*(C'\fR to the command line flags
+when running the \f(CW\*(C`Configure\*(C'\fR script. See also "\-f" in perlrun.
+.ie n .SS """Config.pm"" is now much smaller."
+.el .SS "\f(CWConfig.pm\fP is now much smaller."
+.IX Subsection "Config.pm is now much smaller."
+\&\f(CW\*(C`Config.pm\*(C'\fR is now about 3K rather than 32K, with the infrequently used
+code and \f(CW%Config\fR values loaded on demand. This is transparent to the
+programmer, but means that most code will save parsing and loading 29K of
+script (for example, code that uses \f(CW\*(C`File::Find\*(C'\fR).
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.IP \(bu 4
+B upgraded to version 1.09
+.IP \(bu 4
+base upgraded to version 2.07
+.IP \(bu 4
+bignum upgraded to version 0.17
+.IP \(bu 4
+bytes upgraded to version 1.02
+.IP \(bu 4
+Carp upgraded to version 1.04
+.IP \(bu 4
+CGI upgraded to version 3.10
+.IP \(bu 4
+Class::ISA upgraded to version 0.33
+.IP \(bu 4
+Data::Dumper upgraded to version 2.121_02
+.IP \(bu 4
+DB_File upgraded to version 1.811
+.IP \(bu 4
+Devel::PPPort upgraded to version 3.06
+.IP \(bu 4
+Digest upgraded to version 1.10
+.IP \(bu 4
+Encode upgraded to version 2.10
+.IP \(bu 4
+FileCache upgraded to version 1.05
+.IP \(bu 4
+File::Path upgraded to version 1.07
+.IP \(bu 4
+File::Temp upgraded to version 0.16
+.IP \(bu 4
+IO::File upgraded to version 1.11
+.IP \(bu 4
+IO::Socket upgraded to version 1.28
+.IP \(bu 4
+Math::BigInt upgraded to version 1.77
+.IP \(bu 4
+Math::BigRat upgraded to version 0.15
+.IP \(bu 4
+overload upgraded to version 1.03
+.IP \(bu 4
+PathTools upgraded to version 3.05
+.IP \(bu 4
+Pod::HTML upgraded to version 1.0503
+.IP \(bu 4
+Pod::Perldoc upgraded to version 3.14
+.IP \(bu 4
+Pod::LaTeX upgraded to version 0.58
+.IP \(bu 4
+Pod::Parser upgraded to version 1.30
+.IP \(bu 4
+Symbol upgraded to version 1.06
+.IP \(bu 4
+Term::ANSIColor upgraded to version 1.09
+.IP \(bu 4
+Test::Harness upgraded to version 2.48
+.IP \(bu 4
+Test::Simple upgraded to version 0.54
+.IP \(bu 4
+Text::Wrap upgraded to version 2001.09293, to fix a bug when \fBwrap()\fR was
+called with a non-space separator.
+.IP \(bu 4
+threads::shared upgraded to version 0.93
+.IP \(bu 4
+Time::HiRes upgraded to version 1.66
+.IP \(bu 4
+Time::Local upgraded to version 1.11
+.IP \(bu 4
+Unicode::Normalize upgraded to version 0.32
+.IP \(bu 4
+utf8 upgraded to version 1.05
+.IP \(bu 4
+Win32 upgraded to version 0.24, which provides Win32::GetFileVersion
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "find2perl enhancements"
+.IX Subsection "find2perl enhancements"
+\&\f(CW\*(C`find2perl\*(C'\fR has new options \f(CW\*(C`\-iname\*(C'\fR, \f(CW\*(C`\-path\*(C'\fR and \f(CW\*(C`\-ipath\*(C'\fR.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+The internal pointer mapping hash used during ithreads cloning now uses an
+arena for memory allocation. In tests this reduced ithreads cloning time by
+about 10%.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.IP \(bu 4
+The Win32 "dmake" makefile.mk has been updated to make it compatible
+with the latest versions of dmake.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_MALLOC\*(C'\fR, \f(CW\*(C`DEBUG_MSTATS\*(C'\fR, \f(CW\*(C`PERL_HASH_SEED_EXPLICIT\*(C'\fR and \f(CW\*(C`NO_HASH_SEED\*(C'\fR
+should now work in Win32 makefiles.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.IP \(bu 4
+The \fBsocket()\fR function on Win32 has been fixed so that it is able to use
+transport providers which specify a protocol of 0 (meaning any protocol
+is allowed) once more.  (This was broken in 5.8.6, and typically caused
+the use of ICMP sockets to fail.)
+.IP \(bu 4
+Another obscure bug involving \f(CW\*(C`substr\*(C'\fR and UTF\-8 caused by bad internal
+offset caching has been identified and fixed.
+.IP \(bu 4
+A bug involving the loading of UTF\-8 tables by the regexp engine has been
+fixed \- code such as \f(CW\*(C`"\ex{100}" =~ /[[:print:]]/\*(C'\fR will no longer give
+corrupt results.
+.IP \(bu 4
+Case conversion operations such as \f(CW\*(C`uc\*(C'\fR on a long Unicode string could
+exhaust memory. This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`index\*(C'\fR/\f(CW\*(C`rindex\*(C'\fR were buggy for some combinations of Unicode and
+non-Unicode data. This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`read\*(C'\fR (and presumably \f(CW\*(C`sysread\*(C'\fR) would expose the UTF\-8 internals when
+reading from a byte oriented file handle into a UTF\-8 scalar. This has
+been fixed.
+.IP \(bu 4
+Several \f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR bug fixes:
+.RS 4
+.IP \(bu 4
+Checksums with \f(CW\*(C`b\*(C'\fR or \f(CW\*(C`B\*(C'\fR formats were broken.
+.IP \(bu 4
+\&\f(CW\*(C`unpack\*(C'\fR checksums could overflow with the \f(CW\*(C`C\*(C'\fR format.
+.IP \(bu 4
+\&\f(CW\*(C`U0\*(C'\fR and \f(CW\*(C`C0\*(C'\fR are now scoped to \f(CW\*(C`()\*(C'\fR \f(CW\*(C`pack\*(C'\fR sub-templates.
+.IP \(bu 4
+Counted length prefixes now don't change \f(CW\*(C`C0\*(C'\fR/\f(CW\*(C`U0\*(C'\fR mode.
+.IP \(bu 4
+\&\f(CW\*(C`pack\*(C'\fR \f(CW\*(C`Z0\*(C'\fR used to destroy the preceding character.
+.IP \(bu 4
+\&\f(CW\*(C`P\*(C'\fR/\f(CW\*(C`p\*(C'\fR \f(CW\*(C`pack\*(C'\fR formats used to only recognise literal \f(CW\*(C`undef\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Using closures with ithreads could cause perl to crash. This was due to
+failure to correctly lock internal OP structures, and has been fixed.
+.IP \(bu 4
+The return value of \f(CW\*(C`close\*(C'\fR now correctly reflects any file errors that
+occur while flushing the handle's data, instead of just giving failure if
+the actual underlying file close operation failed.
+.IP \(bu 4
+\&\f(CW\*(C`not() || 1\*(C'\fR used to segfault. \f(CWnot()\fR now behaves like \f(CWnot(0)\fR, which was
+the pre 5.6.0 behaviour.
+.IP \(bu 4
+\&\f(CW\*(C`h2ph\*(C'\fR has various enhancements to cope with constructs in header files that
+used to result in incorrect or invalid output.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+There is a new taint error, "%ENV is aliased to \f(CW%s\fR". This error is thrown
+when taint checks are enabled and when \f(CW*ENV\fR has been aliased, so that
+\&\f(CW%ENV\fR has no env-magic anymore and hence the environment cannot be verified
+as taint-free.
+.PP
+The internals of \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR have been updated. All legitimate
+templates should work as before, but there may be some changes in the error
+reported for complex failure cases. Any behaviour changes for non-error cases
+are bugs, and should be reported.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+There has been a fair amount of refactoring of the \f(CW\*(C`C\*(C'\fR source code, partly to
+make it tidier and more maintainable. The resulting object code and the
+\&\f(CW\*(C`perl\*(C'\fR binary may well be smaller than 5.8.6, and hopefully faster in some
+cases, but apart from this there should be no user-detectable changes.
+.PP
+\&\f(CW\*(C`${^UTF8LOCALE}\*(C'\fR has been added to give perl space access to \f(CW\*(C`PL_utf8locale\*(C'\fR.
+.PP
+The size of the arenas used to allocate SV heads and most SV bodies can now
+be changed at compile time. The old size was 1008 bytes, the new default size
+is 4080 bytes.
+.SH "Known Problems"
+.IX Header "Known Problems"
+Unicode strings returned from overloaded operators can be buggy. This is a
+long standing bug reported since 5.8.6 was released, but we do not yet have
+a suitable fix for it.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+On UNICOS, lib/Math/BigInt/t/bigintc.t hangs burning CPU.
+ext/B/t/bytecode.t and ext/Socket/t/socketpair.t both fail tests.
+These are unlikely to be resolved, as our valiant UNICOS porter's last
+Cray is being decommissioned.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl588delta.1 b/upstream/mageia-cauldron/man1/perl588delta.1
new file mode 100644
index 00000000..fc22ae1d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl588delta.1
@@ -0,0 +1,1142 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL588DELTA 1"
+.TH PERL588DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl588delta \- what is new for perl v5.8.8
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.7 release and
+the 5.8.8 release.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+There are no changes intentionally incompatible with 5.8.7. If any exist,
+they are bugs and reports are welcome.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.IP \(bu 4
+\&\f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR and \f(CW\*(C`chown\*(C'\fR can now work on filehandles as well as
+filenames, if the system supports respectively \f(CW\*(C`fchdir\*(C'\fR, \f(CW\*(C`fchmod\*(C'\fR and
+\&\f(CW\*(C`fchown\*(C'\fR, thanks to a patch provided by Gisle Aas.
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.IP \(bu 4
+\&\f(CW\*(C`Attribute::Handlers\*(C'\fR upgraded to version 0.78_02
+.RS 4
+.IP \(bu 4
+Documentation typo fix
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`attrs\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Internal cleanup only
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`autouse\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+Simplified implementation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`B\*(C'\fR upgraded to version 1.09_01
+.RS 4
+.IP \(bu 4
+The inheritance hierarchy of the \f(CW\*(C`B::\*(C'\fR modules has been corrected;
+\&\f(CW\*(C`B::NV\*(C'\fR now inherits from \f(CW\*(C`B::SV\*(C'\fR (instead of \f(CW\*(C`B::IV\*(C'\fR).
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`blib\*(C'\fR upgraded to version 1.03
+.RS 4
+.IP \(bu 4
+Documentation typo fix
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ByteLoader\*(C'\fR upgraded to version 0.06
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`CGI\*(C'\fR upgraded to version 3.15
+.RS 4
+.IP \(bu 4
+Extraneous "?" from \f(CWself_url()\fR removed
+.IP \(bu 4
+\&\f(CWscrolling_list()\fR select attribute fixed
+.IP \(bu 4
+\&\f(CW\*(C`virtual_port\*(C'\fR now works properly with the https protocol
+.IP \(bu 4
+\&\f(CWupload_hook()\fR and \f(CWappend()\fR now works in function-oriented mode
+.IP \(bu 4
+\&\f(CW\*(C`POST_MAX\*(C'\fR doesn't cause the client to hang any more
+.IP \(bu 4
+Automatic tab indexes are now disabled and new \f(CW\*(C`\-tabindex\*(C'\fR pragma has
+been added to turn automatic indexes back on
+.IP \(bu 4
+\&\f(CWend_form()\fR doesn't emit empty (and non-validating) \f(CW\*(C`<div>\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`CGI::Carp\*(C'\fR works better in certain mod_perl configurations
+.IP \(bu 4
+Setting \f(CW$CGI::TMPDIRECTORY\fR is now effective
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`charnames\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+\&\f(CWviacode()\fR now accept hex strings and has been optimized.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`CPAN\*(C'\fR upgraded to version 1.76_02
+.RS 4
+.IP \(bu 4
+1 minor bug fix for Win32
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Cwd\*(C'\fR upgraded to version 3.12
+.RS 4
+.IP \(bu 4
+\&\f(CWcanonpath()\fR on Win32 now collapses \fIfoo\e..\fR sections correctly.
+.IP \(bu 4
+Improved behaviour on Symbian OS.
+.IP \(bu 4
+Enhanced documentation and typo fixes
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Data::Dumper\*(C'\fR upgraded to version 2.121_08
+.RS 4
+.IP \(bu 4
+A problem where \f(CW\*(C`Data::Dumper\*(C'\fR would sometimes update the iterator state
+of hashes has been fixed
+.IP \(bu 4
+Numeric labels now work
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`DB\*(C'\fR upgraded to version 1.01
+.RS 4
+.IP \(bu 4
+A problem where the state of the regexp engine would sometimes get clobbered when running
+under the debugger has been fixed.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`DB_File\*(C'\fR upgraded to version 1.814
+.RS 4
+.IP \(bu 4
+Adds support for Berkeley DB 4.4.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Devel::DProf\*(C'\fR upgraded to version 20050603.00
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Devel::Peek\*(C'\fR upgraded to version 1.03
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Devel::PPPort\*(C'\fR upgraded to version 3.06_01
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`\-\-compat\-version\*(C'\fR argument checking has been improved
+.IP \(bu 4
+Files passed on the command line are filtered by default
+.IP \(bu 4
+\&\f(CW\*(C`\-\-nofilter\*(C'\fR option to override the filtering has been added
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`diagnostics\*(C'\fR upgraded to version 1.15
+.RS 4
+.IP \(bu 4
+Documentation typo fix
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Digest\*(C'\fR upgraded to version 1.14
+.RS 4
+.IP \(bu 4
+The constructor now knows which module implements SHA\-224
+.IP \(bu 4
+Documentation tweaks and typo fixes
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Digest::MD5\*(C'\fR upgraded to version 2.36
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`XSLoader\*(C'\fR is now used for faster loading
+.IP \(bu 4
+Enhanced documentation including MD5 weaknesses discovered lately
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Dumpvalue\*(C'\fR upgraded to version 1.12
+.RS 4
+.IP \(bu 4
+Documentation fix
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`DynaLoader\*(C'\fR upgraded but unfortunately we're not able to increment its version number :\-(
+.RS 4
+.IP \(bu 4
+Implements \f(CW\*(C`dl_unload_file\*(C'\fR on Win32
+.IP \(bu 4
+Internal cleanup
+.IP \(bu 4
+\&\f(CW\*(C`XSLoader\*(C'\fR 0.06 incorporated; small optimisation for calling
+\&\f(CWbootstrap_inherit()\fR and documentation enhancements.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Encode\*(C'\fR upgraded to version 2.12
+.RS 4
+.IP \(bu 4
+A coderef is now acceptable for \f(CW\*(C`CHECK\*(C'\fR!
+.IP \(bu 4
+3 new characters added to the ISO\-8859\-7 encoding
+.IP \(bu 4
+New encoding \f(CW\*(C`MIME\-Header\-ISO_2022_JP\*(C'\fR added
+.IP \(bu 4
+Problem with partial characters and \f(CWencoding(utf\-8\-strict)\fR fixed.
+.IP \(bu 4
+Documentation enhancements and typo fixes
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`English\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+the \f(CW$COMPILING\fR variable has been added
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Constant\*(C'\fR upgraded to version 0.17
+.RS 4
+.IP \(bu 4
+Improved compatibility with older versions of perl
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR upgraded to version 6.30 (was 6.17)
+.RS 4
+.IP \(bu 4
+Too much to list here;  see <http://search.cpan.org/dist/ExtUtils\-MakeMaker/Changes>
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Basename\*(C'\fR upgraded to version 2.74, with changes contributed by Michael Schwern.
+.RS 4
+.IP \(bu 4
+Documentation clarified and errors corrected.
+.IP \(bu 4
+\&\f(CW\*(C`basename\*(C'\fR now strips trailing path separators before processing the name.
+.IP \(bu 4
+\&\f(CW\*(C`basename\*(C'\fR now returns \f(CW\*(C`/\*(C'\fR for parameter \f(CW\*(C`/\*(C'\fR, to make \f(CW\*(C`basename\*(C'\fR
+consistent with the shell utility of the same name.
+.IP \(bu 4
+The suffix is no longer stripped if it is identical to the remaining characters
+in the name, again for consistency with the shell utility.
+.IP \(bu 4
+Some internal code cleanup.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Copy\*(C'\fR upgraded to version 2.09
+.RS 4
+.IP \(bu 4
+Copying a file onto itself used to fail.
+.IP \(bu 4
+Moving a file between file systems now preserves the access and
+modification time stamps
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Find\*(C'\fR upgraded to version 1.10
+.RS 4
+.IP \(bu 4
+Win32 portability fixes
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Glob\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Path\*(C'\fR upgraded to version 1.08
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`mkpath\*(C'\fR now preserves \f(CW\*(C`errno\*(C'\fR when \f(CW\*(C`mkdir\*(C'\fR fails
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Spec\*(C'\fR upgraded to version 3.12
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`File::Spec\->rootdir()\*(C'\fR now returns \f(CW\*(C`\e\*(C'\fR on Win32, instead of \f(CW\*(C`/\*(C'\fR
+.IP \(bu 4
+\&\f(CW$^O\fR could sometimes become tainted. This has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`canonpath\*(C'\fR on Win32 now collapses \f(CW\*(C`foo/..\*(C'\fR (or \f(CW\*(C`foo\e..\*(C'\fR) sections
+correctly, rather than doing the "misguided" work it was previously doing.
+Note that \f(CW\*(C`canonpath\*(C'\fR on Unix still does \fBnot\fR collapse these sections, as
+doing so would be incorrect.
+.IP \(bu 4
+Some documentation improvements
+.IP \(bu 4
+Some internal code cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`FileCache\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+POD formatting errors in the documentation fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Filter::Simple\*(C'\fR upgraded to version 0.82
+.IP \(bu 4
+\&\f(CW\*(C`FindBin\*(C'\fR upgraded to version 1.47
+.RS 4
+.IP \(bu 4
+Now works better with directories where access rights are more
+restrictive than usual.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`GDBM_File\*(C'\fR upgraded to version 1.08
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Getopt::Long\*(C'\fR upgraded to version 2.35
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`prefix_pattern\*(C'\fR has now been complemented by a new configuration
+option \f(CW\*(C`long_prefix_pattern\*(C'\fR that allows the user to specify what
+prefix patterns should have long option style semantics applied.
+.IP \(bu 4
+Options can now take multiple values at once (experimental)
+.IP \(bu 4
+Various bug fixes
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`if\*(C'\fR upgraded to version 0.05
+.RS 4
+.IP \(bu 4
+Give more meaningful error messages from \f(CW\*(C`if\*(C'\fR when invoked with a
+condition in list context.
+.IP \(bu 4
+Restore backwards compatibility with earlier versions of perl
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`IO\*(C'\fR upgraded to version 1.22
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`IPC::Open2\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`IPC::Open3\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`List::Util\*(C'\fR upgraded to version 1.18 (was 1.14)
+.RS 4
+.IP \(bu 4
+Fix pure-perl version of \f(CW\*(C`refaddr\*(C'\fR to avoid blessing an un-blessed reference
+.IP \(bu 4
+Use \f(CW\*(C`XSLoader\*(C'\fR for faster loading
+.IP \(bu 4
+Fixed various memory leaks
+.IP \(bu 4
+Internal cleanup and portability fixes
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Math::Complex\*(C'\fR upgraded to version 1.35
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`atan2(0, i)\*(C'\fR now works, as do all the (computable) complex argument cases
+.IP \(bu 4
+Fixes for certain bugs in \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`emake\*(C'\fR
+.IP \(bu 4
+Support returning the \fIk\fRth root directly
+.IP \(bu 4
+Support \f(CW\*(C`[2,\-3pi/8]\*(C'\fR in \f(CW\*(C`emake\*(C'\fR
+.IP \(bu 4
+Support \f(CW\*(C`inf\*(C'\fR for \f(CW\*(C`make\*(C'\fR/\f(CW\*(C`emake\*(C'\fR
+.IP \(bu 4
+Document \f(CW\*(C`make\*(C'\fR/\f(CW\*(C`emake\*(C'\fR more visibly
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Math::Trig\*(C'\fR upgraded to version 1.03
+.RS 4
+.IP \(bu 4
+Add more great circle routines: \f(CW\*(C`great_circle_waypoint\*(C'\fR and
+\&\f(CW\*(C`great_circle_destination\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`MIME::Base64\*(C'\fR upgraded to version 3.07
+.RS 4
+.IP \(bu 4
+Use \f(CW\*(C`XSLoader\*(C'\fR for faster loading
+.IP \(bu 4
+Enhanced documentation
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`NDBM_File\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ODBM_File\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+Documentation typo fixed
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Opcode\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`overload\*(C'\fR upgraded to version 1.04
+.RS 4
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO\*(C'\fR upgraded to version 1.04
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::via\*(C'\fR iterate over layers properly now
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR understands \f(CW\*(C`$/ = ""\*(C'\fR now
+.IP \(bu 4
+\&\f(CWencoding(utf\-8\-strict)\fR with partial characters now works
+.IP \(bu 4
+Enhanced documentation
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Functions\*(C'\fR upgraded to version 1.03
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Html\*(C'\fR upgraded to version 1.0504
+.RS 4
+.IP \(bu 4
+HTML output will now correctly link
+to \f(CW\*(C`=item\*(C'\fRs on the same page, and should be valid XHTML.
+.IP \(bu 4
+Variable names are recognized as intended
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Parser\*(C'\fR upgraded to version 1.32
+.RS 4
+.IP \(bu 4
+Allow files that start with \f(CW\*(C`=head\*(C'\fR on the first line
+.IP \(bu 4
+Win32 portability fix
+.IP \(bu 4
+Exit status of \f(CW\*(C`pod2usage\*(C'\fR fixed
+.IP \(bu 4
+New \f(CW\*(C`\-noperldoc\*(C'\fR switch for \f(CW\*(C`pod2usage\*(C'\fR
+.IP \(bu 4
+Arbitrary URL schemes now allowed
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`POSIX\*(C'\fR upgraded to version 1.09
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`re\*(C'\fR upgraded to version 0.05
+.RS 4
+.IP \(bu 4
+Documentation typo fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Safe\*(C'\fR upgraded to version 2.12
+.RS 4
+.IP \(bu 4
+Minor documentation enhancement
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`SDBM_File\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+Documentation typo fixed
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Socket\*(C'\fR upgraded to version 1.78
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Storable\*(C'\fR upgraded to version 2.15
+.RS 4
+.IP \(bu 4
+This includes the \f(CW\*(C`STORABLE_attach\*(C'\fR hook functionality added by
+Adam Kennedy, and more frugal memory requirements when storing under \f(CW\*(C`ithreads\*(C'\fR, by
+using the \f(CW\*(C`ithreads\*(C'\fR cloning tracking code.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Switch\*(C'\fR upgraded to version 2.10_01
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Sys::Syslog\*(C'\fR upgraded to version 0.13
+.RS 4
+.IP \(bu 4
+Now provides numeric macros and meaningful \f(CW\*(C`Exporter\*(C'\fR tags.
+.IP \(bu 4
+No longer uses \f(CW\*(C`Sys::Hostname\*(C'\fR as it may provide useless values in
+unconfigured network environments, so instead uses \f(CW\*(C`INADDR_LOOPBACK\*(C'\fR directly.
+.IP \(bu 4
+\&\f(CWsyslog()\fR now uses local timestamp.
+.IP \(bu 4
+\&\f(CWsetlogmask()\fR now behaves like its C counterpart.
+.IP \(bu 4
+\&\f(CWsetlogsock()\fR will now \f(CWcroak()\fR as documented.
+.IP \(bu 4
+Improved error and warnings messages.
+.IP \(bu 4
+Improved documentation.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Term::ANSIColor\*(C'\fR upgraded to version 1.10
+.RS 4
+.IP \(bu 4
+Fixes a bug in \f(CW\*(C`colored\*(C'\fR when \f(CW$EACHLINE\fR is set that caused it to not color
+lines consisting solely of 0 (literal zero).
+.IP \(bu 4
+Improved tests.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Term::ReadLine\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Documentation tweaks
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Test::Harness\*(C'\fR upgraded to version 2.56 (was 2.48)
+.RS 4
+.IP \(bu 4
+The \f(CW\*(C`Test::Harness\*(C'\fR timer is now off by default.
+.IP \(bu 4
+Now shows elapsed time in milliseconds.
+.IP \(bu 4
+Various bug fixes
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Test::Simple\*(C'\fR upgraded to version 0.62 (was 0.54)
+.RS 4
+.IP \(bu 4
+\&\f(CWis_deeply()\fR no longer fails to work for many cases
+.IP \(bu 4
+Various minor bug fixes
+.IP \(bu 4
+Documentation enhancements
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Text::Tabs\*(C'\fR upgraded to version 2005.0824
+.RS 4
+.IP \(bu 4
+Provides a faster implementation of \f(CW\*(C`expand\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Text::Wrap\*(C'\fR upgraded to version 2005.082401
+.RS 4
+.IP \(bu 4
+Adds \f(CW$Text::Wrap::separator2\fR, which allows you to preserve existing newlines
+but add line-breaks with some other string.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`threads\*(C'\fR upgraded to version 1.07
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`threads\*(C'\fR will now honour \f(CW\*(C`no warnings \*(Aqthreads\*(Aq\*(C'\fR
+.IP \(bu 4
+A thread's interpreter is now freed after \f(CW\*(C`$t\->join()\*(C'\fR rather than after
+\&\f(CW\*(C`undef $t\*(C'\fR, which should fix some \f(CW\*(C`ithreads\*(C'\fR memory leaks. (Fixed by Dave
+Mitchell)
+.IP \(bu 4
+Some documentation typo fixes.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`threads::shared\*(C'\fR upgraded to version 0.94
+.RS 4
+.IP \(bu 4
+Documentation changes only
+.IP \(bu 4
+Note: An improved implementation of \f(CW\*(C`threads::shared\*(C'\fR is available on
+CPAN \- this will be merged into 5.8.9 if it proves stable.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Hash\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Documentation typo fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Time::HiRes\*(C'\fR upgraded to version 1.86 (was 1.66)
+.RS 4
+.IP \(bu 4
+\&\f(CWclock_nanosleep()\fR and \f(CWclock()\fR functions added
+.IP \(bu 4
+Support for the POSIX \f(CWclock_gettime()\fR and \f(CWclock_getres()\fR has been added
+.IP \(bu 4
+Return \f(CW\*(C`undef\*(C'\fR or an empty list if the C \f(CWgettimeofday()\fR function fails
+.IP \(bu 4
+Improved \f(CW\*(C`nanosleep\*(C'\fR detection
+.IP \(bu 4
+Internal cleanup
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::Collate\*(C'\fR upgraded to version 0.52
+.RS 4
+.IP \(bu 4
+Now implements UCA Revision 14 (based on Unicode 4.1.0).
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::Collate\->new\*(C'\fR method no longer overwrites user's \f(CW$_\fR
+.IP \(bu 4
+Enhanced documentation
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::UCD\*(C'\fR upgraded to version 0.24
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`User::grent\*(C'\fR upgraded to version 1.01
+.RS 4
+.IP \(bu 4
+Documentation typo fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`utf8\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`vmsish\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+Documentation typos fixed
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`warnings\*(C'\fR upgraded to version 1.05
+.RS 4
+.IP \(bu 4
+Gentler messing with \f(CW\*(C`Carp::\*(C'\fR internals
+.IP \(bu 4
+Internal cleanup
+.IP \(bu 4
+Documentation update
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Win32\*(C'\fR upgraded to version 0.2601
+.RS 4
+.IP \(bu 4
+Provides Windows Vista support to \f(CW\*(C`Win32::GetOSName\*(C'\fR
+.IP \(bu 4
+Documentation enhancements
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`XS::Typemap\*(C'\fR upgraded to version 0.02
+.RS 4
+.IP \(bu 4
+Internal cleanup
+.RE
+.RS 4
+.RE
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.ie n .SS """h2xs"" enhancements"
+.el .SS "\f(CWh2xs\fP enhancements"
+.IX Subsection "h2xs enhancements"
+\&\f(CW\*(C`h2xs\*(C'\fR implements new option \f(CW\*(C`\-\-use\-xsloader\*(C'\fR to force use of
+\&\f(CW\*(C`XSLoader\*(C'\fR even in backwards compatible modules.
+.PP
+The handling of authors' names that had apostrophes has been fixed.
+.PP
+Any enums with negative values are now skipped.
+.ie n .SS """perlivp"" enhancements"
+.el .SS "\f(CWperlivp\fP enhancements"
+.IX Subsection "perlivp enhancements"
+\&\f(CW\*(C`perlivp\*(C'\fR implements new option \f(CW\*(C`\-a\*(C'\fR and will not check for \fI*.ph\fR
+files by default any more.  Use the \f(CW\*(C`\-a\*(C'\fR option to run \fIall\fR tests.
+.SH "New Documentation"
+.IX Header "New Documentation"
+The perlglossary manpage is a glossary of terms used in the Perl
+documentation, technical and otherwise, kindly provided by O'Reilly Media,
+inc.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+Weak reference creation is now \fIO(1)\fR rather than \fIO(n)\fR, courtesy of
+Nicholas Clark. Weak reference deletion remains \fIO(n)\fR, but if deletion only
+happens at program exit, it may be skipped completely.
+.IP \(bu 4
+Salvador Fandiño provided improvements to reduce the memory usage of \f(CW\*(C`sort\*(C'\fR
+and to speed up some cases.
+.IP \(bu 4
+Jarkko Hietaniemi and Andy Lester worked to mark as much data as possible in
+the C source files as \f(CW\*(C`static\*(C'\fR, to increase the proportion of the executable
+file that the operating system can share between process, and thus reduce
+real memory usage on multi-user systems.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+Parallel makes should work properly now, although there may still be problems
+if \f(CW\*(C`make test\*(C'\fR is instructed to run in parallel.
+.PP
+Building with Borland's compilers on Win32 should work more smoothly. In
+particular Steve Hay has worked to side step many warnings emitted by their
+compilers and at least one C compiler internal error.
+.PP
+\&\f(CW\*(C`Configure\*(C'\fR will now detect \f(CW\*(C`clearenv\*(C'\fR and \f(CW\*(C`unsetenv\*(C'\fR, thanks to a patch
+from Alan Burlison. It will also probe for \f(CW\*(C`futimes\*(C'\fR and whether \f(CW\*(C`sprintf\*(C'\fR
+correctly returns the length of the formatted string, which will both be used
+in perl 5.8.9.
+.PP
+There are improved hints for next\-3.0, vmesa, IX, Darwin, Solaris, Linux,
+DEC/OSF, HP-UX and MPE/iX
+.PP
+Perl extensions on Windows now can be statically built into the Perl DLL,
+thanks to a work by Vadim Konovalov. (This improvement was actually in 5.8.7,
+but was accidentally omitted from perl587delta).
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS "no warnings 'category' works correctly with \-w"
+.IX Subsection "no warnings 'category' works correctly with -w"
+Previously when running with warnings enabled globally via \f(CW\*(C`\-w\*(C'\fR, selective
+disabling of specific warning categories would actually turn off all warnings.
+This is now fixed; now \f(CW\*(C`no warnings \*(Aqio\*(Aq;\*(C'\fR will only turn off warnings in the
+\&\f(CW\*(C`io\*(C'\fR class. Previously it would erroneously turn off all warnings.
+.PP
+This bug fix may cause some programs to start correctly issuing warnings.
+.SS "Remove over-optimisation"
+.IX Subsection "Remove over-optimisation"
+Perl 5.8.4 introduced a change so that assignments of \f(CW\*(C`undef\*(C'\fR to a
+scalar, or of an empty list to an array or a hash, were optimised away. As
+this could cause problems when \f(CW\*(C`goto\*(C'\fR jumps were involved, this change
+has been backed out.
+.SS "\fBsprintf()\fP fixes"
+.IX Subsection "sprintf() fixes"
+Using the \fBsprintf()\fR function with some formats could lead to a buffer
+overflow in some specific cases. This has been fixed, along with several
+other bugs, notably in bounds checking.
+.PP
+In related fixes, it was possible for badly written code that did not follow
+the documentation of \f(CW\*(C`Sys::Syslog\*(C'\fR to have formatting vulnerabilities.
+\&\f(CW\*(C`Sys::Syslog\*(C'\fR has been changed to protect people from poor quality third
+party code.
+.SS "Debugger and Unicode slowdown"
+.IX Subsection "Debugger and Unicode slowdown"
+It had been reported that running under perl's debugger when processing
+Unicode data could cause unexpectedly large slowdowns. The most likely cause
+of this was identified and fixed by Nicholas Clark.
+.SS "Smaller fixes"
+.IX Subsection "Smaller fixes"
+.IP \(bu 4
+\&\f(CW\*(C`FindBin\*(C'\fR now works better with directories where access rights are more
+restrictive than usual.
+.IP \(bu 4
+Several memory leaks in ithreads were closed. An improved implementation of
+\&\f(CW\*(C`threads::shared\*(C'\fR is available on CPAN \- this will be merged into 5.8.9 if
+it proves stable.
+.IP \(bu 4
+Trailing spaces are now trimmed from \f(CW$!\fR and \f(CW$^E\fR.
+.IP \(bu 4
+Operations that require perl to read a process's list of groups, such as reads
+of \f(CW$(\fR and \f(CW$)\fR, now dynamically allocate memory rather than using a
+fixed sized array. The fixed size array could cause C stack exhaustion on
+systems configured to use large numbers of groups.
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR now works better with non-default \f(CW$/\fR settings.
+.IP \(bu 4
+You can now use the \f(CW\*(C`x\*(C'\fR operator to repeat a \f(CW\*(C`qw//\*(C'\fR list. This used
+to raise a syntax error.
+.IP \(bu 4
+The debugger now traces correctly execution in eval("")uated code that
+contains #line directives.
+.IP \(bu 4
+The value of the \f(CW\*(C`open\*(C'\fR pragma is no longer ignored for three-argument
+opens.
+.IP \(bu 4
+The optimisation of \f(CW\*(C`for (reverse @a)\*(C'\fR introduced in perl 5.8.6 could
+misbehave when the array had undefined elements and was used in LVALUE
+context. Dave Mitchell provided a fix.
+.IP \(bu 4
+Some case insensitive matches between UTF\-8 encoded data and 8 bit regexps,
+and vice versa, could give malformed character warnings. These have been
+fixed by Dave Mitchell and Yves Orton.
+.IP \(bu 4
+\&\f(CW\*(C`lcfirst\*(C'\fR and \f(CW\*(C`ucfirst\*(C'\fR could corrupt the string for certain cases where
+the length UTF\-8 encoding of the string in lower case, upper case or title
+case differed. This was fixed by Nicholas Clark.
+.IP \(bu 4
+Perl will now use the C library calls \f(CW\*(C`unsetenv\*(C'\fR and \f(CW\*(C`clearenv\*(C'\fR if present
+to delete keys from \f(CW%ENV\fR and delete \f(CW%ENV\fR entirely, thanks to a patch
+from Alan Burlison.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.SS "Attempt to set length of freed array"
+.IX Subsection "Attempt to set length of freed array"
+This is a new warning, produced in situations such as this:
+.PP
+.Vb 2
+\&    $r = do {my @a; \e$#a};
+\&    $$r = 503;
+.Ve
+.SS "Non-string passed as bitmask"
+.IX Subsection "Non-string passed as bitmask"
+This is a new warning, produced when number has been passed as an argument to
+\&\fBselect()\fR, instead of a bitmask.
+.PP
+.Vb 3
+\&    # Wrong, will now warn
+\&    $rin = fileno(STDIN);
+\&    ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);
+\&    
+\&    # Should be
+\&    $rin = \*(Aq\*(Aq;
+\&    vec($rin,fileno(STDIN),1) = 1;
+\&    ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);
+.Ve
+.SS "Search pattern not terminated or ternary operator parsed as search pattern"
+.IX Subsection "Search pattern not terminated or ternary operator parsed as search pattern"
+This syntax error indicates that the lexer couldn't find the final
+delimiter of a \f(CW\*(C`?PATTERN?\*(C'\fR construct. Mentioning the ternary operator in
+this error message makes it easier to diagnose syntax errors.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+There has been a fair amount of refactoring of the \f(CW\*(C`C\*(C'\fR source code, partly to
+make it tidier and more maintainable. The resulting object code and the
+\&\f(CW\*(C`perl\*(C'\fR binary may well be smaller than 5.8.7, in particular due to a change
+contributed by Dave Mitchell which reworked the warnings code to be
+significantly smaller. Apart from being smaller and possibly faster, there
+should be no user-detectable changes.
+.PP
+Andy Lester supplied many improvements to determine which function
+parameters and local variables could actually be declared \f(CW\*(C`const\*(C'\fR to the C
+compiler. Steve Peters provided new \f(CW*_set\fR macros and reworked the core to
+use these rather than assigning to macros in LVALUE context.
+.PP
+Dave Mitchell improved the lexer debugging output under \f(CW\*(C`\-DT\*(C'\fR
+.PP
+Nicholas Clark changed the string buffer allocation so that it is now rounded
+up to the next multiple of 4 (or 8 on platforms with 64 bit pointers). This
+should reduce the number of calls to \f(CW\*(C`realloc\*(C'\fR without actually using any
+extra memory.
+.PP
+The \f(CW\*(C`HV\*(C'\fR's array of \f(CW\*(C`HE*\*(C'\fRs is now allocated at the correct (minimal) size,
+thanks to another change by Nicholas Clark. Compile with
+\&\f(CW\*(C`\-DPERL_USE_LARGE_HV_ALLOC\*(C'\fR to use the old, sloppier, default.
+.PP
+For XS or embedding debugging purposes, if perl is compiled with
+\&\f(CW\*(C`\-DDEBUG_LEAKING_SCALARS_FORK_DUMP\*(C'\fR in addition to
+\&\f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR then a child process is \f(CW\*(C`fork\*(C'\fRed just before
+global destruction, which is used to display the values of any scalars
+found to have leaked at the end of global destruction. Without this, the
+scalars have already been freed sufficiently at the point of detection that
+it is impossible to produce any meaningful dump of their contents.  This
+feature was implemented by the indefatigable Nicholas Clark, based on an idea
+by Mike Giroux.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+The optimiser on HP-UX 11.23 (Itanium 2) is currently partly disabled (scaled
+down to +O1) when using HP C\-ANSI-C; the cause of problems at higher
+optimisation levels is still unclear.
+.PP
+There are a handful of remaining test failures on VMS, mostly due to
+test fixes and minor module tweaks with too many dependencies to
+integrate into this release from the development stream, where they have
+all been corrected.  The following is a list of expected failures with
+the patch number of the fix where that is known:
+.PP
+.Vb 6
+\&    ext/Devel/PPPort/t/ppphtest.t  #26913
+\&    ext/List/Util/t/p_tainted.t    #26912
+\&    lib/ExtUtils/t/PL_FILES.t      #26813
+\&    lib/ExtUtils/t/basic.t         #26813
+\&    t/io/fs.t
+\&    t/op/cmp.t
+.Ve
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl589delta.1 b/upstream/mageia-cauldron/man1/perl589delta.1
new file mode 100644
index 00000000..67c2bade
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl589delta.1
@@ -0,0 +1,1656 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL589DELTA 1"
+.TH PERL589DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl589delta \- what is new for perl v5.8.9
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.8.8 release and
+the 5.8.9 release.
+.SH Notice
+.IX Header "Notice"
+The 5.8.9 release will be the last significant release of the 5.8.x
+series. Any future releases of 5.8.x will likely only be to deal with
+security issues, and platform build failures. Hence you should look to
+migrating to 5.10.x, if you have not started already.
+See "Known Problems" for more information.
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+A particular construction in the source code of extensions written in C++
+may need changing. See "Changed Internals" for more details. All
+extensions written in C, most written in C++, and all existing compiled
+extensions are unaffected. This was necessary to improve C++ support.
+.PP
+Other than this, there are no changes intentionally incompatible with 5.8.8.
+If any exist, they are bugs and reports are welcome.
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Unicode Character Database 5.1.0."
+.IX Subsection "Unicode Character Database 5.1.0."
+The copy of the Unicode Character Database included in Perl 5.8 has
+been updated to 5.1.0 from 4.1.0. See
+<http://www.unicode.org/versions/Unicode5.1.0/#NotableChanges> for the
+notable changes.
+.SS "stat and \-X on directory handles"
+.IX Subsection "stat and -X on directory handles"
+It is now possible to call \f(CW\*(C`stat\*(C'\fR and the \f(CW\*(C`\-X\*(C'\fR filestat operators on
+directory handles. As both directory and file handles are barewords, there
+can be ambiguities over which was intended. In these situations the file
+handle semantics are preferred. Both also treat \f(CW*FILE{IO}\fR filehandles
+like \f(CW*FILE\fR filehandles.
+.ie n .SS "Source filters in @INC"
+.el .SS "Source filters in \f(CW@INC\fP"
+.IX Subsection "Source filters in @INC"
+It's possible to enhance the mechanism of subroutine hooks in \f(CW@INC\fR by
+adding a source filter on top of the filehandle opened and returned by the
+hook. This feature was planned a long time ago, but wasn't quite working
+until now. See "require" in perlfunc for details. (Nicholas Clark)
+.SS "Exceptions in constant folding"
+.IX Subsection "Exceptions in constant folding"
+The constant folding routine is now wrapped in an exception handler, and
+if folding throws an exception (such as attempting to evaluate 0/0), perl
+now retains the current optree, rather than aborting the whole program.
+Without this change, programs would not compile if they had expressions that
+happened to generate exceptions, even though those expressions were in code
+that could never be reached at runtime. (Nicholas Clark, Dave Mitchell)
+.ie n .SS """no VERSION"""
+.el .SS "\f(CWno VERSION\fP"
+.IX Subsection "no VERSION"
+You can now use \f(CW\*(C`no\*(C'\fR followed by a version number to specify that you
+want to use a version of perl older than the specified one.
+.SS "Improved internal UTF\-8 caching code"
+.IX Subsection "Improved internal UTF-8 caching code"
+The code that caches calculated UTF\-8 byte offsets for character offsets for
+a string has been re-written. Several bugs have been located and eliminated,
+and the code now makes better use of the information it has, so should be
+faster. In particular, it doesn't scan to the end of a string before
+calculating an offset within the string, which should speed up some operations
+on long strings. It is now possible to disable the caching code at run time,
+to verify that it is not the cause of suspected problems.
+.SS "Runtime relocatable installations"
+.IX Subsection "Runtime relocatable installations"
+There is now \fIConfigure\fR support for creating a perl tree that is relocatable
+at run time. see "Relocatable installations".
+.SS "New internal variables"
+.IX Subsection "New internal variables"
+.ie n .IP """${^CHILD_ERROR_NATIVE}""" 4
+.el .IP \f(CW${^CHILD_ERROR_NATIVE}\fR 4
+.IX Item "${^CHILD_ERROR_NATIVE}"
+This variable gives the native status returned by the last pipe close,
+backtick command, successful call to \f(CW\*(C`wait\*(C'\fR or \f(CW\*(C`waitpid\*(C'\fR, or from the
+\&\f(CW\*(C`system\*(C'\fR operator. See perlvar for details. (Contributed by Gisle Aas.)
+.ie n .IP """${^UTF8CACHE}""" 4
+.el .IP \f(CW${^UTF8CACHE}\fR 4
+.IX Item "${^UTF8CACHE}"
+This variable controls the state of the internal UTF\-8 offset caching code.
+1 for on (the default), 0 for off, \-1 to debug the caching code by checking
+all its results against linear scans, and panicking on any discrepancy.
+.ie n .SS """readpipe"" is now overridable"
+.el .SS "\f(CWreadpipe\fP is now overridable"
+.IX Subsection "readpipe is now overridable"
+The built-in function \f(CW\*(C`readpipe\*(C'\fR is now overridable. Overriding it permits
+also to override its operator counterpart, \f(CW\*(C`qx//\*(C'\fR (also known as \f(CW\`\`\fR).
+.SS "simple exception handling macros"
+.IX Subsection "simple exception handling macros"
+Perl 5.8.9 (and 5.10.0 onwards) now provides a couple of macros to do very
+basic exception handling in XS modules. You can use these macros if you call
+code that may \f(CW\*(C`croak\*(C'\fR, but you need to do some cleanup before giving control
+back to Perl. See "Exception Handling" in perlguts for more details.
+.SS "\-D option enhancements"
+.IX Subsection "-D option enhancements"
+.IP \(bu 4
+\&\f(CW\*(C`\-Dq\*(C'\fR suppresses the \fIEXECUTING...\fR message when running under \f(CW\*(C`\-D\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Dl\*(C'\fR logs runops loop entry and exit, and jump level popping.
+.IP \(bu 4
+\&\f(CW\*(C`\-Dv\*(C'\fR displays the process id as part of the trace output.
+.SS "XS-assisted SWASHGET"
+.IX Subsection "XS-assisted SWASHGET"
+Some pure-perl code that the regexp engine was using to retrieve Unicode
+properties and transliteration mappings has been reimplemented in XS
+for faster execution.
+(SADAHIRO Tomoyuki)
+.SS "Constant subroutines"
+.IX Subsection "Constant subroutines"
+The interpreter internals now support a far more memory efficient form of
+inlineable constants. Storing a reference to a constant value in a symbol
+table is equivalent to a full typeglob referencing a constant subroutine,
+but using about 400 bytes less memory. This proxy constant subroutine is
+automatically upgraded to a real typeglob with subroutine if necessary.
+The approach taken is analogous to the existing space optimisation for
+subroutine stub declarations, which are stored as plain scalars in place
+of the full typeglob.
+.PP
+However, to aid backwards compatibility of existing code, which (wrongly)
+does not expect anything other than typeglobs in symbol tables, nothing in
+core uses this feature, other than the regression tests.
+.PP
+Stubs for prototyped subroutines have been stored in symbol tables as plain
+strings, and stubs for unprototyped subroutines as the number \-1, since 5.005,
+so code which assumes that the core only places typeglobs in symbol tables
+has been making incorrect assumptions for over 10 years.
+.SH "New Platforms"
+.IX Header "New Platforms"
+Compile support added for:
+.IP \(bu 4
+DragonFlyBSD
+.IP \(bu 4
+MidnightBSD
+.IP \(bu 4
+MirOS BSD
+.IP \(bu 4
+RISC OS
+.IP \(bu 4
+Cray XT4/Catamount
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules"
+.IX Subsection "New Modules"
+.IP \(bu 4
+\&\f(CW\*(C`Module::Pluggable\*(C'\fR is a simple framework to create modules that accept
+pluggable sub-modules. The bundled version is 3.8
+.IP \(bu 4
+\&\f(CW\*(C`Module::CoreList\*(C'\fR is a hash of hashes that is keyed on perl version as
+indicated in \f(CW$]\fR. The bundled version is 2.17
+.IP \(bu 4
+\&\f(CW\*(C`Win32API::File\*(C'\fR now available in core on Microsoft Windows. The bundled
+version is 0.1001_01
+.IP \(bu 4
+\&\f(CW\*(C`Devel::InnerPackage\*(C'\fR finds all the packages defined by a single file. It is
+part of the \f(CW\*(C`Module::Pluggable\*(C'\fR distribution. The bundled version is 0.3
+.SS "Updated Modules"
+.IX Subsection "Updated Modules"
+.IP \(bu 4
+\&\f(CW\*(C`attributes\*(C'\fR upgraded to version 0.09
+.IP \(bu 4
+\&\f(CW\*(C`AutoLoader\*(C'\fR upgraded to version 5.67
+.IP \(bu 4
+\&\f(CW\*(C`AutoSplit\*(C'\fR upgraded to 1.06
+.IP \(bu 4
+\&\f(CW\*(C`autouse\*(C'\fR upgraded to version 1.06
+.IP \(bu 4
+\&\f(CW\*(C`B\*(C'\fR upgraded from 1.09_01 to 1.19
+.RS 4
+.IP \(bu 4
+provides new pad related abstraction macros \f(CW\*(C`B::NV::COP_SEQ_RANGE_LOW\*(C'\fR,
+\&\f(CW\*(C`B::NV::COP_SEQ_RANGE_HIGH\*(C'\fR, \f(CW\*(C`B::NV::PARENT_PAD_INDEX\*(C'\fR,
+\&\f(CW\*(C`B::NV::PARENT_FAKELEX_FLAGS\*(C'\fR, which hides the difference in storage in
+5.10.0 and later.
+.IP \(bu 4
+provides \f(CW\*(C`B::sub_generation\*(C'\fR, which exposes \f(CW\*(C`PL_sub_generation\*(C'\fR
+.IP \(bu 4
+provides \f(CW\*(C`B::GV::isGV_with_GP\*(C'\fR, which on pre\-5.10 perls always returns true.
+.IP \(bu 4
+New type \f(CW\*(C`B::HE\*(C'\fR added with methods \f(CW\*(C`VAL\*(C'\fR, \f(CW\*(C`HASH\*(C'\fR and \f(CW\*(C`SVKEY_force\*(C'\fR
+.IP \(bu 4
+The \f(CW\*(C`B::GVf_IMPORTED_CV\*(C'\fR flag is now set correctly when a proxy
+constant subroutine is imported.
+.IP \(bu 4
+bugs fixed in the handling of \f(CW\*(C`PMOP\*(C'\fRs.
+.IP \(bu 4
+\&\f(CW\*(C`B::BM::PREVIOUS\*(C'\fR returns now \f(CW\*(C`U32\*(C'\fR, not \f(CW\*(C`U16\*(C'\fR.
+\&\f(CW\*(C`B::CV::START\*(C'\fR and \f(CW\*(C`B:CV::ROOT\*(C'\fR return now \f(CW\*(C`NULL\*(C'\fR on an XSUB,
+\&\f(CW\*(C`B::CV::XSUB\*(C'\fR and \f(CW\*(C`B::CV::XSUBANY\*(C'\fR return 0 on a non-XSUB.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`B::C\*(C'\fR upgraded to 1.05
+.IP \(bu 4
+\&\f(CW\*(C`B::Concise\*(C'\fR upgraded to 0.76
+.RS 4
+.IP \(bu 4
+new option \f(CW\*(C`\-src\*(C'\fR causes the rendering of each statement (starting with
+the nextstate OP) to be preceded by the first line of source code that
+generates it.
+.IP \(bu 4
+new option \f(CW\*(C`\-stash="somepackage"\*(C'\fR, \f(CW\*(C`require\*(C'\fRs "somepackage", and then renders
+each function defined in its namespace.
+.IP \(bu 4
+now has documentation of detailed hint symbols.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`B::Debug\*(C'\fR upgraded to version 1.05
+.IP \(bu 4
+\&\f(CW\*(C`B::Deparse\*(C'\fR upgraded to version 0.87
+.RS 4
+.IP \(bu 4
+properly deparse \f(CW\*(C`print readpipe $x, $y\*(C'\fR.
+.IP \(bu 4
+now handles \f(CW\*(C`\*(Aq\*(Aq\->()\*(C'\fR, \f(CW::()\fR, \f(CW\*(C`sub :: {}\*(C'\fR, \fIetc.\fR correctly [RT #43010].
+All bugs in parsing these kinds of syntax are now fixed:
+.Sp
+.Vb 5
+\&    perl \-MO=Deparse \-e \*(Aq"my %h = "\->()\*(Aq
+\&    perl \-MO=Deparse \-e \*(Aq::\->()\*(Aq
+\&    perl \-MO=Deparse \-e \*(Aqsub :: {}\*(Aq
+\&    perl \-MO=Deparse \-e \*(Aqpackage a; sub a::b::c {}\*(Aq
+\&    perl \-MO=Deparse \-e \*(Aqsub the::main::road {}\*(Aq
+.Ve
+.IP \(bu 4
+does \fBnot\fR deparse \f(CW$^H{v_string}\fR, which is automatically set by the
+internals.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`B::Lint\*(C'\fR upgraded to version 1.11
+.IP \(bu 4
+\&\f(CW\*(C`B::Terse\*(C'\fR upgraded to version 1.05
+.IP \(bu 4
+\&\f(CW\*(C`base\*(C'\fR upgraded to version 2.13
+.RS 4
+.IP \(bu 4
+loading a module via base.pm would mask a global \f(CW$SIG{_\|_DIE_\|_}\fR in that
+module.
+.IP \(bu 4
+push all classes at once in \f(CW@ISA\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Benchmark\*(C'\fR upgraded to version 1.10
+.IP \(bu 4
+\&\f(CW\*(C`bigint\*(C'\fR upgraded to 0.23
+.IP \(bu 4
+\&\f(CW\*(C`bignum\*(C'\fR upgraded to 0.23
+.IP \(bu 4
+\&\f(CW\*(C`bigrat\*(C'\fR upgraded to 0.23
+.IP \(bu 4
+\&\f(CW\*(C`blib\*(C'\fR upgraded to 0.04
+.IP \(bu 4
+\&\f(CW\*(C`Carp\*(C'\fR upgraded to version 1.10
+.Sp
+The argument backtrace code now shows \f(CW\*(C`undef\*(C'\fR as \f(CW\*(C`undef\*(C'\fR,
+instead of a string \fI"undef"\fR.
+.IP \(bu 4
+\&\f(CW\*(C`CGI\*(C'\fR upgraded to version 3.42
+.IP \(bu 4
+\&\f(CW\*(C`charnames\*(C'\fR upgraded to 1.06
+.IP \(bu 4
+\&\f(CW\*(C`constant\*(C'\fR upgraded to version 1.17
+.IP \(bu 4
+\&\f(CW\*(C`CPAN\*(C'\fR upgraded to version 1.9301
+.IP \(bu 4
+\&\f(CW\*(C`Cwd\*(C'\fR upgraded to version 3.29 with some platform specific
+improvements (including for VMS).
+.IP \(bu 4
+\&\f(CW\*(C`Data::Dumper\*(C'\fR upgraded to version 2.121_17
+.RS 4
+.IP \(bu 4
+Fixes hash iterator current position with the pure Perl version [RT #40668]
+.IP \(bu 4
+Performance enhancements, which will be most evident on platforms where
+repeated calls to C's \f(CWrealloc()\fR are slow, such as Win32.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`DB_File\*(C'\fR upgraded to version 1.817
+.IP \(bu 4
+\&\f(CW\*(C`DB_Filter\*(C'\fR upgraded to version 0.02
+.IP \(bu 4
+\&\f(CW\*(C`Devel::DProf\*(C'\fR upgraded to version 20080331.00
+.IP \(bu 4
+\&\f(CW\*(C`Devel::Peek\*(C'\fR upgraded to version 1.04
+.IP \(bu 4
+\&\f(CW\*(C`Devel::PPPort\*(C'\fR upgraded to version 3.14
+.IP \(bu 4
+\&\f(CW\*(C`diagnostics\*(C'\fR upgraded to version 1.16
+.IP \(bu 4
+\&\f(CW\*(C`Digest\*(C'\fR upgraded to version 1.15
+.IP \(bu 4
+\&\f(CW\*(C`Digest::MD5\*(C'\fR upgraded to version 2.37
+.IP \(bu 4
+\&\f(CW\*(C`DirHandle\*(C'\fR upgraded to version 1.02
+.RS 4
+.IP \(bu 4
+now localises \f(CW$.\fR, \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, and \f(CW$?\fR before closing the
+directory handle to suppress leaking any side effects of warnings about it
+already being closed.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`DynaLoader\*(C'\fR upgraded to version 1.09
+.Sp
+\&\f(CW\*(C`DynaLoader\*(C'\fR can now dynamically load a loadable object from a file with a
+non-default file extension.
+.IP \(bu 4
+\&\f(CW\*(C`Encode\*(C'\fR upgraded to version 2.26
+.Sp
+\&\f(CW\*(C`Encode::Alias\*(C'\fR includes a fix for encoding "646" on Solaris (better known as
+ASCII).
+.IP \(bu 4
+\&\f(CW\*(C`English\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`Errno\*(C'\fR upgraded to version 1.10
+.IP \(bu 4
+\&\f(CW\*(C`Exporter\*(C'\fR upgraded to version 5.63
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Command\*(C'\fR upgraded to version 1.15
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Constant\*(C'\fR upgraded to version 0.21
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Embed\*(C'\fR upgraded to version 1.28
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Install\*(C'\fR upgraded to version 1.50_01
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Installed\*(C'\fR upgraded to version 1.43
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR upgraded to version 6.48
+.RS 4
+.IP \(bu 4
+support for \f(CW\*(C`INSTALLSITESCRIPT\*(C'\fR and \f(CW\*(C`INSTALLVENDORSCRIPT\*(C'\fR
+configuration.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Manifest\*(C'\fR upgraded to version 1.55
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR upgraded to version 2.19
+.IP \(bu 4
+\&\f(CW\*(C`Fatal\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+allows built-ins in \f(CW\*(C`CORE::GLOBAL\*(C'\fR to be made fatal.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Fcntl\*(C'\fR upgraded to version 1.06
+.IP \(bu 4
+\&\f(CW\*(C`fields\*(C'\fR upgraded to version 2.12
+.IP \(bu 4
+\&\f(CW\*(C`File::Basename\*(C'\fR upgraded to version 2.77
+.IP \(bu 4
+\&\f(CW\*(C`FileCache\*(C'\fR upgraded to version 1.07
+.IP \(bu 4
+\&\f(CW\*(C`File::Compare\*(C'\fR upgraded to 1.1005
+.IP \(bu 4
+\&\f(CW\*(C`File::Copy\*(C'\fR upgraded to 2.13
+.RS 4
+.IP \(bu 4
+now uses 3\-arg open.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::DosGlob\*(C'\fR upgraded to 1.01
+.IP \(bu 4
+\&\f(CW\*(C`File::Find\*(C'\fR upgraded to version 1.13
+.IP \(bu 4
+\&\f(CW\*(C`File::Glob\*(C'\fR upgraded to version 1.06
+.RS 4
+.IP \(bu 4
+fixes spurious results with brackets inside braces.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::Path\*(C'\fR upgraded to version 2.07_02
+.IP \(bu 4
+\&\f(CW\*(C`File::Spec\*(C'\fR upgraded to version 3.29
+.RS 4
+.IP \(bu 4
+improved handling of bad arguments.
+.IP \(bu 4
+some platform specific improvements (including for VMS and Cygwin), with
+an optimisation on \f(CW\*(C`abs2rel\*(C'\fR when handling both relative arguments.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`File::stat\*(C'\fR upgraded to version 1.01
+.IP \(bu 4
+\&\f(CW\*(C`File::Temp\*(C'\fR upgraded to version 0.20
+.IP \(bu 4
+\&\f(CW\*(C`filetest\*(C'\fR upgraded to version 1.02
+.IP \(bu 4
+\&\f(CW\*(C`Filter::Util::Call\*(C'\fR upgraded to version 1.07
+.IP \(bu 4
+\&\f(CW\*(C`Filter::Simple\*(C'\fR upgraded to version 0.83
+.IP \(bu 4
+\&\f(CW\*(C`FindBin\*(C'\fR upgraded to version 1.49
+.IP \(bu 4
+\&\f(CW\*(C`GDBM_File\*(C'\fR upgraded to version 1.09
+.IP \(bu 4
+\&\f(CW\*(C`Getopt::Long\*(C'\fR upgraded to version 2.37
+.IP \(bu 4
+\&\f(CW\*(C`Getopt::Std\*(C'\fR upgraded to version 1.06
+.IP \(bu 4
+\&\f(CW\*(C`Hash::Util\*(C'\fR upgraded to version 0.06
+.IP \(bu 4
+\&\f(CW\*(C`if\*(C'\fR upgraded to version 0.05
+.IP \(bu 4
+\&\f(CW\*(C`IO\*(C'\fR upgraded to version 1.23
+.Sp
+Reduced number of calls to \f(CW\*(C`getpeername\*(C'\fR in \f(CW\*(C`IO::Socket\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`IPC::Open\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`IPC::Open3\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`IPC::SysV\*(C'\fR upgraded to version 2.00
+.IP \(bu 4
+\&\f(CW\*(C`lib\*(C'\fR upgraded to version 0.61
+.RS 4
+.IP \(bu 4
+avoid warning about loading \fI.par\fR files.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`libnet\*(C'\fR upgraded to version 1.22
+.IP \(bu 4
+\&\f(CW\*(C`List::Util\*(C'\fR upgraded to 1.19
+.IP \(bu 4
+\&\f(CW\*(C`Locale::Maketext\*(C'\fR upgraded to 1.13
+.IP \(bu 4
+\&\f(CW\*(C`Math::BigFloat\*(C'\fR upgraded to version 1.60
+.IP \(bu 4
+\&\f(CW\*(C`Math::BigInt\*(C'\fR upgraded to version 1.89
+.IP \(bu 4
+\&\f(CW\*(C`Math::BigRat\*(C'\fR upgraded to version 0.22
+.RS 4
+.IP \(bu 4
+implements new \f(CW\*(C`as_float\*(C'\fR method.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Math::Complex\*(C'\fR upgraded to version 1.54.
+.IP \(bu 4
+\&\f(CW\*(C`Math::Trig\*(C'\fR upgraded to version 1.18.
+.IP \(bu 4
+\&\f(CW\*(C`NDBM_File\*(C'\fR upgraded to version 1.07
+.RS 4
+.IP \(bu 4
+improve \fIg++\fR handling for systems using GDBM compatibility headers.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Net::Ping\*(C'\fR upgraded to version 2.35
+.IP \(bu 4
+\&\f(CW\*(C`NEXT\*(C'\fR upgraded to version 0.61
+.RS 4
+.IP \(bu 4
+fix several bugs with \f(CW\*(C`NEXT\*(C'\fR when working with \f(CW\*(C`AUTOLOAD\*(C'\fR, \f(CW\*(C`eval\*(C'\fR block, and
+within overloaded stringification.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`ODBM_File\*(C'\fR upgraded to 1.07
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR upgraded to 1.06
+.IP \(bu 4
+\&\f(CW\*(C`ops\*(C'\fR upgraded to 1.02
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::encoding\*(C'\fR upgraded to version 0.11
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR upgraded to version 0.06
+.RS 4
+.IP \(bu 4
+[RT #40267] \f(CW\*(C`PerlIO::scalar\*(C'\fR doesn't respect readonly-ness.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::via\*(C'\fR upgraded to version 0.05
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Html\*(C'\fR upgraded to version 1.09
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Parser\*(C'\fR upgraded to version 1.35
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Usage\*(C'\fR upgraded to version 1.35
+.IP \(bu 4
+\&\f(CW\*(C`POSIX\*(C'\fR upgraded to version 1.15
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`POSIX\*(C'\fR constants that duplicate those in \f(CW\*(C`Fcntl\*(C'\fR are now imported from
+\&\f(CW\*(C`Fcntl\*(C'\fR and re-exported, rather than being duplicated by \f(CW\*(C`POSIX\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`POSIX::remove\*(C'\fR can remove empty directories.
+.IP \(bu 4
+\&\f(CW\*(C`POSIX::setlocale\*(C'\fR safer to call multiple times.
+.IP \(bu 4
+\&\f(CW\*(C`POSIX::SigRt\*(C'\fR added, which provides access to POSIX realtime signal
+functionality on systems that support it.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`re\*(C'\fR upgraded to version 0.06_01
+.IP \(bu 4
+\&\f(CW\*(C`Safe\*(C'\fR upgraded to version 2.16
+.IP \(bu 4
+\&\f(CW\*(C`Scalar::Util\*(C'\fR upgraded to 1.19
+.IP \(bu 4
+\&\f(CW\*(C`SDBM_File\*(C'\fR upgraded to version 1.06
+.IP \(bu 4
+\&\f(CW\*(C`SelfLoader\*(C'\fR upgraded to version 1.17
+.IP \(bu 4
+\&\f(CW\*(C`Shell\*(C'\fR upgraded to version 0.72
+.IP \(bu 4
+\&\f(CW\*(C`sigtrap\*(C'\fR upgraded to version 1.04
+.IP \(bu 4
+\&\f(CW\*(C`Socket\*(C'\fR upgraded to version 1.81
+.RS 4
+.IP \(bu 4
+this fixes an optimistic use of \f(CW\*(C`gethostbyname\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Storable\*(C'\fR upgraded to 2.19
+.IP \(bu 4
+\&\f(CW\*(C`Switch\*(C'\fR upgraded to version 2.13
+.IP \(bu 4
+\&\f(CW\*(C`Sys::Syslog\*(C'\fR upgraded to version 0.27
+.IP \(bu 4
+\&\f(CW\*(C`Term::ANSIColor\*(C'\fR upgraded to version 1.12
+.IP \(bu 4
+\&\f(CW\*(C`Term::Cap\*(C'\fR upgraded to version 1.12
+.IP \(bu 4
+\&\f(CW\*(C`Term::ReadLine\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`Test::Builder\*(C'\fR upgraded to version 0.80
+.IP \(bu 4
+\&\f(CW\*(C`Test::Harness\*(C'\fR upgraded version to 2.64
+.RS 4
+.IP \(bu 4
+this makes it able to handle newlines.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Test::More\*(C'\fR upgraded to version 0.80
+.IP \(bu 4
+\&\f(CW\*(C`Test::Simple\*(C'\fR upgraded to version 0.80
+.IP \(bu 4
+\&\f(CW\*(C`Text::Balanced\*(C'\fR upgraded to version 1.98
+.IP \(bu 4
+\&\f(CW\*(C`Text::ParseWords\*(C'\fR upgraded to version 3.27
+.IP \(bu 4
+\&\f(CW\*(C`Text::Soundex\*(C'\fR upgraded to version 3.03
+.IP \(bu 4
+\&\f(CW\*(C`Text::Tabs\*(C'\fR upgraded to version 2007.1117
+.IP \(bu 4
+\&\f(CW\*(C`Text::Wrap\*(C'\fR upgraded to version 2006.1117
+.IP \(bu 4
+\&\f(CW\*(C`Thread\*(C'\fR upgraded to version 2.01
+.IP \(bu 4
+\&\f(CW\*(C`Thread::Semaphore\*(C'\fR upgraded to version 2.09
+.IP \(bu 4
+\&\f(CW\*(C`Thread::Queue\*(C'\fR upgraded to version 2.11
+.RS 4
+.IP \(bu 4
+added capability to add complex structures (e.g., hash of hashes) to queues.
+.IP \(bu 4
+added capability to dequeue multiple items at once.
+.IP \(bu 4
+added new methods to inspect and manipulate queues:  \f(CW\*(C`peek\*(C'\fR, \f(CW\*(C`insert\*(C'\fR and
+\&\f(CW\*(C`extract\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Handle\*(C'\fR upgraded to version 4.2
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Hash\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Memoize\*(C'\fR upgraded to version 1.1
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Memoize::EXISTS\*(C'\fR now correctly caches its results.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Tie::RefHash\*(C'\fR upgraded to version 1.38
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Scalar\*(C'\fR upgraded to version 1.01
+.IP \(bu 4
+\&\f(CW\*(C`Tie::StdHandle\*(C'\fR upgraded to version 4.2
+.IP \(bu 4
+\&\f(CW\*(C`Time::gmtime\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`Time::Local\*(C'\fR upgraded to version 1.1901
+.IP \(bu 4
+\&\f(CW\*(C`Time::HiRes\*(C'\fR upgraded to version 1.9715 with various build improvements 
+(including VMS) and minor platform-specific bug fixes (including
+for HP-UX 11 ia64).
+.IP \(bu 4
+\&\f(CW\*(C`threads\*(C'\fR upgraded to 1.71
+.RS 4
+.IP \(bu 4
+new thread state information methods: \f(CW\*(C`is_running\*(C'\fR, \f(CW\*(C`is_detached\*(C'\fR
+and \f(CW\*(C`is_joinable\*(C'\fR.  \f(CW\*(C`list\*(C'\fR method enhanced to return running or joinable
+threads.
+.IP \(bu 4
+new thread signal method: \f(CW\*(C`kill\*(C'\fR
+.IP \(bu 4
+added capability to specify thread stack size.
+.IP \(bu 4
+added capability to control thread exiting behavior.  Added a new \f(CW\*(C`exit\*(C'\fR
+method.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`threads::shared\*(C'\fR upgraded to version 1.27
+.RS 4
+.IP \(bu 4
+smaller and faster implementation that eliminates one internal structure and
+the consequent level of indirection.
+.IP \(bu 4
+user locks are now stored in a safer manner.
+.IP \(bu 4
+new function \f(CW\*(C`shared_clone\*(C'\fR creates a copy of an object leaving
+shared elements as-is and deep-cloning non-shared elements.
+.IP \(bu 4
+added new \f(CW\*(C`is_shared\*(C'\fR method.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::Normalize\*(C'\fR upgraded to version 1.02
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::UCD\*(C'\fR upgraded to version 0.25
+.IP \(bu 4
+\&\f(CW\*(C`warnings\*(C'\fR upgraded to version 1.05_01
+.IP \(bu 4
+\&\f(CW\*(C`Win32\*(C'\fR upgraded to version 0.38
+.RS 4
+.IP \(bu 4
+added new function \f(CW\*(C`GetCurrentProcessId\*(C'\fR which returns the regular Windows
+process identifier of the current process, even when called from within a fork.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+\&\f(CW\*(C`XSLoader\*(C'\fR upgraded to version 0.10
+.IP \(bu 4
+\&\f(CW\*(C`XS::APItest\*(C'\fR and \f(CW\*(C`XS::Typemap\*(C'\fR are for internal use only and hence
+no longer installed. Many more tests have been added to \f(CW\*(C`XS::APItest\*(C'\fR.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS "debugger upgraded to version 1.31"
+.IX Subsection "debugger upgraded to version 1.31"
+.IP \(bu 4
+Andreas König contributed two functions to save and load the debugger
+history.
+.IP \(bu 4
+\&\f(CW\*(C`NEXT::AUTOLOAD\*(C'\fR no longer emits warnings under the debugger.
+.IP \(bu 4
+The debugger should now correctly find tty the device on OS X 10.5 and VMS
+when the program \f(CW\*(C`fork\*(C'\fRs.
+.IP \(bu 4
+LVALUE subs now work inside the debugger.
+.SS \fIperlthanks\fP
+.IX Subsection "perlthanks"
+Perl 5.8.9 adds a new utility \fIperlthanks\fR, which is a variant of \fIperlbug\fR,
+but for sending non-bug-reports to the authors and maintainers of Perl.
+Getting nothing but bug reports can become a bit demoralising \- we'll see if
+this changes things.
+.SS \fIperlbug\fP
+.IX Subsection "perlbug"
+\&\fIperlbug\fR now checks if you're reporting about a non-core module and suggests
+you report it to the CPAN author instead.
+.SS \fIh2xs\fP
+.IX Subsection "h2xs"
+.IP \(bu 4
+won't define an empty string as a constant [RT #25366]
+.IP \(bu 4
+has examples for \f(CW\*(C`h2xs \-X\*(C'\fR
+.SS \fIh2ph\fP
+.IX Subsection "h2ph"
+.IP \(bu 4
+now attempts to deal sensibly with the difference in path implications
+between \f(CW""\fR and \f(CW\*(C`<>\*(C'\fR quoting in \f(CW\*(C`#include\*(C'\fR statements.
+.IP \(bu 4
+now generates correct code for \f(CW\*(C`#if defined A || defined B\*(C'\fR
+[RT #39130]
+.SH "New Documentation"
+.IX Header "New Documentation"
+As usual, the documentation received its share of corrections, clarifications
+and other nitfixes. More \f(CW\*(C`\*(C'\fR tags were added for indexing.
+.IX Xref "..."
+.PP
+perlunitut is a tutorial written by Juerd Waalboer on Unicode-related
+terminology and how to correctly handle Unicode in Perl scripts.
+.PP
+perlunicode is updated in section user defined properties.
+.PP
+perluniintro has been updated in the example of detecting data that is not
+valid in particular encoding.
+.PP
+perlcommunity provides an overview of the Perl Community along with further
+resources.
+.PP
+CORE documents the pseudo-namespace for Perl's core routines.
+.SH "Changes to Existing Documentation"
+.IX Header "Changes to Existing Documentation"
+perlglossary adds \fIdeprecated modules and features\fR and \fIto be dropped modules\fR.
+.PP
+perlhack has been updated and added resources on smoke testing.
+.PP
+The Perl FAQs (\fIperlfaq1\fR..\fIperlfaq9\fR) have been updated.
+.PP
+perlcheat is updated with better details on \f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\ed\*(C'\fR, and \f(CW\*(C`\es\*(C'\fR.
+.PP
+perldebug is updated with information on how to call the debugger.
+.PP
+perldiag documentation updated with \fIsubroutine with an ampersand\fR on the
+argument to \f(CW\*(C`exists\*(C'\fR and \f(CW\*(C`delete\*(C'\fR and also several terminology updates on
+warnings.
+.PP
+perlfork documents the limitation of \f(CW\*(C`exec\*(C'\fR inside pseudo-processes.
+.PP
+perlfunc:
+.IP \(bu 4
+Documentation is fixed in section \f(CW\*(C`caller\*(C'\fR and \f(CW\*(C`pop\*(C'\fR.
+.IP \(bu 4
+Function \f(CW\*(C`alarm\*(C'\fR now mentions \f(CW\*(C`Time::HiRes::ualarm\*(C'\fR in preference
+to \f(CW\*(C`select\*(C'\fR.
+.IP \(bu 4
+Regarding precedence in \f(CW\*(C`\-X\*(C'\fR, filetest operators are the same as unary
+operators, but not regarding parsing and parentheses (spotted by Eirik Berg
+Hanssen).
+.IP \(bu 4
+\&\f(CW\*(C`reverse\*(C'\fR function documentation received scalar context examples.
+.PP
+perllocale documentation is adjusted for number localization and
+\&\f(CW\*(C`POSIX::setlocale\*(C'\fR to fix Debian bug #379463.
+.PP
+perlmodlib is updated with \f(CW\*(C`CPAN::API::HOWTO\*(C'\fR and
+\&\f(CW\*(C`Sys::Syslog::win32::Win32\*(C'\fR
+.PP
+perlre documentation updated to reflect the differences between
+\&\f(CW\*(C`[[:xxxxx:]]\*(C'\fR and \f(CW\*(C`\ep{IsXxxxx}\*(C'\fR matches. Also added section on \f(CW\*(C`/g\*(C'\fR and
+\&\f(CW\*(C`/c\*(C'\fR modifiers.
+.PP
+perlreguts describe the internals of the regular expressions engine. It has
+been contributed by Yves Orton.
+.PP
+perlrebackslash describes all perl regular expression backslash and escape
+sequences.
+.PP
+perlrecharclass describes the syntax and use of character classes in
+Perl Regular Expressions.
+.PP
+perlrun is updated to clarify on the hash seed \fIPERL_HASH_SEED\fR. Also more
+information in options \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-u\*(C'\fR.
+.PP
+perlsub example is updated to use a lexical variable for \f(CW\*(C`opendir\*(C'\fR syntax.
+.PP
+perlvar fixes confusion about real GID \f(CW$(\fR and effective GID \f(CW$)\fR.
+.PP
+Perl thread tutorial example is fixed in section
+"Queues: Passing Data Around" in perlthrtut and perlthrtut.
+.PP
+perlhack documentation extensively improved by Jarkko Hietaniemi and others.
+.PP
+perltoot provides information on modifying \f(CW@UNIVERSAL::ISA\fR.
+.PP
+perlport documentation extended to include different \f(CW\*(C`kill(\-9, ...)\*(C'\fR
+semantics on Windows. It also clearly states \f(CW\*(C`dump\*(C'\fR is not supported on Win32
+and cygwin.
+.PP
+\&\fIINSTALL\fR has been updated and modernised.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+The default since perl 5.000 has been for perl to create an empty scalar
+with every new typeglob. The increased use of lexical variables means that
+most are now unused. Thanks to Nicholas Clark's efforts, Perl can now be
+compiled with \f(CW\*(C`\-DPERL_DONT_CREATE_GVSV\*(C'\fR to avoid creating these empty scalars.
+This will significantly decrease the number of scalars allocated for all
+configurations, and the number of scalars that need to be copied for ithread
+creation. Whilst this option is binary compatible with existing perl
+installations, it does change a long-standing assumption about the
+internals, hence it is not enabled by default, as some third party code may
+rely on the old behaviour.
+.Sp
+We would recommend testing with this configuration on new deployments of
+perl, particularly for multi-threaded servers, to see whether all third party
+code is compatible with it, as this configuration may give useful performance
+improvements. For existing installations we would not recommend changing to
+this configuration unless thorough testing is performed before deployment.
+.IP \(bu 4
+\&\f(CW\*(C`diagnostics\*(C'\fR no longer uses \f(CW$&\fR, which results in large speedups
+for regexp matching in all code using it.
+.IP \(bu 4
+Regular expressions classes of a single character are now treated the same as
+if the character had been used as a literal, meaning that code that uses
+char-classes as an escaping mechanism will see a speedup. (Yves Orton)
+.IP \(bu 4
+Creating anonymous array and hash references (ie. \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR) now incurs
+no more overhead than creating an anonymous list or hash. Nicholas Clark
+provided changes with a saving of two ops and one stack push, which was measured
+as a slightly better than 5% improvement for these operations.
+.IP \(bu 4
+Many calls to \f(CWstrlen()\fR have been eliminated, either because the length was
+already known, or by adopting or enhancing APIs that pass lengths. This has
+been aided by the adoption of a \f(CWmy_sprintf()\fR wrapper, which returns the
+correct C89 value \- the length of the formatted string. Previously we could
+not rely on the return value of \f(CWsprintf()\fR, because on some ancient but
+extant platforms it still returns \f(CW\*(C`char *\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`index\*(C'\fR is now faster if the search string is stored in UTF\-8 but only contains
+characters in the Latin\-1 range.
+.IP \(bu 4
+The Unicode swatch cache inside the regexp engine is now used. (the lookup had
+a key mismatch, present since the initial implementation). [RT #42839]
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Relocatable installations"
+.IX Subsection "Relocatable installations"
+There is now \fIConfigure\fR support for creating a relocatable perl tree. If
+you \fIConfigure\fR with \f(CW\*(C`\-Duserelocatableinc\*(C'\fR, then the paths in \f(CW@INC\fR (and
+everything else in \f(CW%Config\fR) can be optionally located via the path of the
+\&\fIperl\fR executable.
+.PP
+At start time, if any paths in \f(CW@INC\fR or \f(CW\*(C`Config\*(C'\fR that \fIConfigure\fR marked
+as relocatable (by starting them with \f(CW".../"\fR), then they are prefixed the
+directory of \f(CW$^X\fR. This allows the relocation can be configured on a
+per-directory basis, although the default with \f(CW\*(C`\-Duserelocatableinc\*(C'\fR is that
+everything is relocated. The initial install is done to the original configured
+prefix.
+.SS "Configuration improvements"
+.IX Subsection "Configuration improvements"
+\&\fIConfigure\fR is now better at removing temporary files. Tom Callaway
+(from RedHat) also contributed patches that complete the set of flags
+passed to the compiler and the linker, in particular that \f(CW\*(C`\-fPIC\*(C'\fR is now
+enabled on Linux. It will also croak when your \fI/dev/null\fR isn't a device.
+.PP
+A new configuration variable \f(CW\*(C`d_pseudofork\*(C'\fR has been to \fIConfigure\fR, and is
+available as  \f(CW$Config{d_pseudofork}\fR in the \f(CW\*(C`Config\*(C'\fR module. This
+distinguishes real \f(CW\*(C`fork\*(C'\fR support from the pseudofork emulation used on
+Windows platforms.
+.PP
+\&\fIConfig.pod\fR and \fIconfig.sh\fR are now placed correctly for cross-compilation.
+.PP
+\&\f(CW$Config{useshrplib}\fR is now 'true' rather than 'yes' when using a shared perl
+library.
+.SS "Compilation improvements"
+.IX Subsection "Compilation improvements"
+Parallel makes should work properly now, although there may still be problems
+if \f(CW\*(C`make test\*(C'\fR is instructed to run in parallel.
+.PP
+Many compilation warnings have been cleaned up. A very stubborn compiler
+warning in \f(CWS_emulate_eaccess()\fR was killed after six attempts.
+\&\fIg++\fR support has been tuned, especially for FreeBSD.
+.PP
+\&\fImkppport\fR has been integrated, and all \fIppport.h\fR files in the core will now
+be autogenerated at build time (and removed during cleanup).
+.SS "Installation improvements."
+.IX Subsection "Installation improvements."
+\&\fIinstallman\fR now works with \f(CW\*(C`\-Duserelocatableinc\*(C'\fR and \f(CW\*(C`DESTDIR\*(C'\fR.
+.PP
+\&\fIinstallperl\fR no longer installs:
+.IP \(bu 4
+static library files of statically linked extensions when a shared perl library
+is being used. (They are not needed. See "Windows" below).
+.IP \(bu 4
+\&\fISIGNATURE\fR and \fIPAUSE*.pub\fR (CPAN files)
+.IP \(bu 4
+\&\fINOTES\fR and \fIPATCHING\fR (ExtUtils files)
+.IP \(bu 4
+\&\fIperlld\fR and \fIld2\fR (Cygwin files)
+.SS "Platform Specific Changes"
+.IX Subsection "Platform Specific Changes"
+There are improved hints for AIX, Cygwin, DEC/OSF, FreeBSD, HP/UX, Irix 6
+Linux, MachTen, NetBSD, OS/390, QNX, SCO, Solaris, SunOS, System V Release 5.x
+(UnixWare 7, OpenUNIX 8), Ultrix, UMIPS, uts and VOS.
+.PP
+\fIFreeBSD\fR
+.IX Subsection "FreeBSD"
+.IP \(bu 4
+Drop \f(CW\*(C`\-std=c89\*(C'\fR and \f(CW\*(C`\-ansi\*(C'\fR if using \f(CW\*(C`long long\*(C'\fR as the main integral type,
+else in FreeBSD 6.2 (and perhaps other releases), system headers do not
+declare some functions required by perl.
+.PP
+\fISolaris\fR
+.IX Subsection "Solaris"
+.IP \(bu 4
+Starting with Solaris 10, we do not want versioned shared libraries, because
+those often indicate a private use only library. These problems could often
+be triggered when SUNWbdb (Berkeley DB) was installed. Hence if Solaris 10
+is detected set \f(CW\*(C`ignore_versioned_solibs=y\*(C'\fR.
+.PP
+\fIVMS\fR
+.IX Subsection "VMS"
+.IP \(bu 4
+Allow IEEE math to be deselected on OpenVMS I64 (but it remains the default).
+.IP \(bu 4
+Record IEEE usage in \f(CW\*(C`config.h\*(C'\fR
+.IP \(bu 4
+Help older VMS compilers by using \f(CW\*(C`ccflags\*(C'\fR when building \f(CW\*(C`munchconfig.exe\*(C'\fR.
+.IP \(bu 4
+Don't try to build old \f(CW\*(C`Thread\*(C'\fR extension on VMS when \f(CW\*(C`\-Duseithreads\*(C'\fR has
+been chosen.
+.IP \(bu 4
+Passing a raw string of "NaN" to \fInawk\fR causes a core dump \- so the string
+has been changed to "*NaN*"
+.IP \(bu 4
+\&\fIt/op/stat.t\fR tests will now test hard links on VMS if they are supported.
+.PP
+\fIWindows\fR
+.IX Subsection "Windows"
+.IP \(bu 4
+When using a shared perl library \fIinstallperl\fR no longer installs static
+library files, import library files and export library files (of statically
+linked extensions) and empty bootstrap files (of dynamically linked
+extensions). This fixes a problem building PAR-Packer on Win32 with a debug
+build of perl.
+.IP \(bu 4
+Various improvements to the win32 build process, including support for Visual
+C++ 2005 Express Edition (aka Visual C++ 8.x).
+.IP \(bu 4
+\&\fIperl.exe\fR will now have an icon if built with MinGW or Borland.
+.IP \(bu 4
+Improvements to the perl\-static.exe build process.
+.IP \(bu 4
+Add Win32 makefile option to link all extensions statically.
+.IP \(bu 4
+The \fIWinCE\fR directory has been merged into the \fIWin32\fR directory.
+.IP \(bu 4
+\&\f(CW\*(C`setlocale\*(C'\fR tests have been re-enabled for Windows XP onwards.
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+.SS Unicode
+.IX Subsection "Unicode"
+Many many bugs related to the internal Unicode implementation (UTF\-8) have
+been fixed. In particular, long standing bugs related to returning Unicode
+via \f(CW\*(C`tie\*(C'\fR, overloading or \f(CW$@\fR are now gone, some of which were never
+reported.
+.PP
+\&\f(CW\*(C`unpack\*(C'\fR will internally convert the string back from UTF\-8 on numeric types.
+This is a compromise between the full consistency now in 5.10, and the current
+behaviour, which is often used as a "feature" on string types.
+.PP
+Using \f(CW\*(C`:crlf\*(C'\fR and \f(CW\*(C`UTF\-16\*(C'\fR IO layers together will now work.
+.PP
+Fixed problems with \f(CW\*(C`split\*(C'\fR, Unicode \f(CW\*(C`/\es+/\*(C'\fR and \f(CW\*(C`/ \e0/\*(C'\fR.
+.PP
+Fixed bug RT #40641 \- encoding of Unicode characters in regular expressions.
+.PP
+Fixed a bug where using certain patterns in a regexp led to a panic.
+[RT #45337]
+.PP
+Perl no longer segfaults (due to infinite internal recursion) if the locale's
+character is not UTF\-8 [RT #41442]:
+.PP
+.Vb 2
+\&    use open \*(Aq:locale\*(Aq;
+\&    print STDERR "\ex{201e}"; # &bdquo;
+.Ve
+.SS PerlIO
+.IX Subsection "PerlIO"
+Inconsistencies have been fixed in the reference counting PerlIO uses to keep
+track of Unix file descriptors, and the API used by XS code to manage getting
+and releasing \f(CW\*(C`FILE *\*(C'\fRs
+.SS Magic
+.IX Subsection "Magic"
+Several bugs have been fixed in Magic, the internal system used to implement
+features such as \f(CW\*(C`tie\*(C'\fR, tainting and threads sharing.
+.PP
+\&\f(CW\*(C`undef @array\*(C'\fR on a tied array now correctly calls the \f(CW\*(C`CLEAR\*(C'\fR method.
+.PP
+Some of the bitwise ops were not checking whether their arguments were magical
+before using them. [RT #24816]
+.PP
+Magic is no longer invoked twice by the expression \f(CW\*(C`\e&$x\*(C'\fR
+.PP
+A bug with assigning large numbers and tainting has been resolved.
+[RT #40708]
+.PP
+A new entry has been added to the MAGIC vtable \- \f(CW\*(C`svt_local\*(C'\fR. This is used
+when copying magic to the new value during \f(CW\*(C`local\*(C'\fR, allowing certain problems
+with localising shared variables to be resolved.
+.PP
+For the implementation details, see "Magic Virtual Tables" in perlguts.
+.SS "Reblessing overloaded objects now works"
+.IX Subsection "Reblessing overloaded objects now works"
+Internally, perl object-ness is on the referent, not the reference, even
+though methods can only be called via a reference. However, the original
+implementation of overloading stored flags related to overloading on the
+reference, relying on the flags being copied when the reference was copied,
+or set at the creation of a new reference. This manifests in a bug \- if you
+rebless an object from a class that has overloading, into one that does not,
+then any other existing references think that they (still) point to an
+overloaded object, choose these C code paths, and then throw errors.
+Analogously, blessing into an overloaded class when other references exist will
+result in them not using overloading.
+.PP
+The implementation has been fixed for 5.10, but this fix changes the semantics
+of flag bits, so is not binary compatible, so can't be applied to 5.8.9.
+However, 5.8.9 has a work-around that implements the same bug fix. If the
+referent has multiple references, then all the other references are located and
+corrected. A full search is avoided whenever possible by scanning lexicals
+outwards from the current subroutine, and the argument stack.
+.PP
+A certain well known Linux vendor applied incomplete versions of this bug fix
+to their \fI/usr/bin/perl\fR and then prematurely closed bug reports about
+performance issues without consulting back upstream. This not being enough,
+they then proceeded to ignore the necessary fixes to these unreleased changes
+for 11 months, until massive pressure was applied by their long-suffering
+paying customers, catalysed by the failings being featured on a prominent blog
+and Slashdot.
+.ie n .SS """strict"" now propagates correctly into string evals"
+.el .SS "\f(CWstrict\fP now propagates correctly into string evals"
+.IX Subsection "strict now propagates correctly into string evals"
+Under 5.8.8 and earlier:
+.PP
+.Vb 3
+\&    $ perl5.8.8 \-e \*(Aquse strict; eval "use foo bar" or die $@\*(Aq
+\&    Can\*(Aqt locate foo.pm in @INC (@INC contains: ... .) at (eval 1) line 2.
+\&    BEGIN failed\-\-compilation aborted at (eval 1) line 2.
+.Ve
+.PP
+Under 5.8.9 and later:
+.PP
+.Vb 2
+\&    $ perl5.8.9 \-e \*(Aquse strict; eval "use foo bar" or die $@\*(Aq
+\&    Bareword "bar" not allowed while "strict subs" in use at (eval 1) line 1.
+.Ve
+.PP
+This may cause problems with programs that parse the error message and rely
+on the buggy behaviour.
+.SS "Other fixes"
+.IX Subsection "Other fixes"
+.IP \(bu 4
+The tokenizer no longer treats \f(CW\*(C`=cute\*(C'\fR (and other words beginning
+with \f(CW\*(C`=cut\*(C'\fR) as a synonym for \f(CW\*(C`=cut\*(C'\fR.
+.IP \(bu 4
+Calling \f(CW\*(C`CORE::require\*(C'\fR
+.Sp
+\&\f(CW\*(C`CORE::require\*(C'\fR and \f(CW\*(C`CORE::do\*(C'\fR were always parsed as \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`do\*(C'\fR
+when they were overridden. This is now fixed.
+.IP \(bu 4
+Stopped memory leak on long \fI/etc/groups\fR entries.
+.IP \(bu 4
+\&\f(CW\*(C`while (my $x ...) { ...; redo }\*(C'\fR shouldn't \f(CW\*(C`undef $x\*(C'\fR.
+.Sp
+In the presence of \f(CW\*(C`my\*(C'\fR in the conditional of a \f(CWwhile()\fR, \f(CWuntil()\fR,
+or \f(CWfor(;;)\fR loop, we now add an extra scope to the body so that \f(CW\*(C`redo\*(C'\fR
+doesn't \f(CW\*(C`undef\*(C'\fR the lexical.
+.IP \(bu 4
+The \f(CW\*(C`encoding\*(C'\fR pragma now correctly ignores anything following an \f(CW\*(C`@\*(C'\fR 
+character in the \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LANG\*(C'\fR environment variables. [RT # 49646]
+.IP \(bu 4
+A segfault observed with some \fIgcc\fR 3.3 optimisations is resolved.
+.IP \(bu 4
+A possible segfault when \f(CW\*(C`unpack\*(C'\fR used in scalar context with \f(CW\*(C`()\*(C'\fR groups
+is resolved. [RT #50256]
+.IP \(bu 4
+Resolved issue where \f(CW$!\fR could be changed by a signal handler interrupting
+a \f(CW\*(C`system\*(C'\fR call.
+.IP \(bu 4
+Fixed bug RT #37886, symbolic dereferencing was allowed in the argument of
+\&\f(CW\*(C`defined\*(C'\fR even under the influence of \f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR.
+.IP \(bu 4
+Fixed bug RT #43207, where \f(CW\*(C`lc\*(C'\fR/\f(CW\*(C`uc\*(C'\fR inside \f(CW\*(C`sort\*(C'\fR affected the return
+value.
+.IP \(bu 4
+Fixed bug RT #45607, where \f(CW\*(C`*{"BONK"} = \e&{"BONK"}\*(C'\fR didn't work correctly.
+.IP \(bu 4
+Fixed bug RT #35878, croaking from a XSUB called via \f(CW\*(C`goto &xsub\*(C'\fR corrupts perl
+internals.
+.IP \(bu 4
+Fixed bug RT #32539, \fIDynaLoader.o\fR is moved into \fIlibperl.so\fR to avoid the
+need to statically link DynaLoader into the stub perl executable. With this
+\&\fIlibperl.so\fR provides everything needed to get a functional embedded perl
+interpreter to run.
+.IP \(bu 4
+Fix bug RT #36267 so that assigning to a tied hash doesn't change the
+underlying hash.
+.IP \(bu 4
+Fix bug RT #6006, regexp replaces using large replacement variables
+fail some of the time, \fIi.e.\fR when substitution contains something
+like \f(CW\*(C`${10}\*(C'\fR (note the bracket) instead of just \f(CW$10\fR.
+.IP \(bu 4
+Fix bug RT #45053, \f(CWPerl_newCONSTSUB()\fR is now thread safe.
+.SS "Platform Specific Fixes"
+.IX Subsection "Platform Specific Fixes"
+\fIDarwin / MacOS X\fR
+.IX Subsection "Darwin / MacOS X"
+.IP \(bu 4
+Various improvements to 64 bit builds.
+.IP \(bu 4
+Mutex protection added in \f(CWPerlIOStdio_close()\fR to avoid race conditions.
+Hopefully this fixes failures in the threads tests \fIfree.t\fR and \fIblocks.t\fR.
+.IP \(bu 4
+Added forked terminal support to the debugger, with the ability to update the
+window title.
+.PP
+\fIOS/2\fR
+.IX Subsection "OS/2"
+.IP \(bu 4
+A build problem with specifying \f(CW\*(C`USE_MULTI\*(C'\fR and \f(CW\*(C`USE_ITHREADS\*(C'\fR but without
+\&\f(CW\*(C`USE_IMP_SYS\*(C'\fR has been fixed.
+.IP \(bu 4
+\&\f(CW\*(C`OS2::REXX\*(C'\fR upgraded to version 1.04
+.PP
+\fITru64\fR
+.IX Subsection "Tru64"
+.IP \(bu 4
+Aligned floating point build policies for \fIcc\fR and \fIgcc\fR.
+.PP
+\fIRedHat Linux\fR
+.IX Subsection "RedHat Linux"
+.IP \(bu 4
+Revisited a patch from 5.6.1 for RH7.2 for Intel's \fIicc\fR [RT #7916], added an
+additional check for \f(CW$Config{gccversion}\fR.
+.PP
+\fISolaris/i386\fR
+.IX Subsection "Solaris/i386"
+.IP \(bu 4
+Use \f(CW\*(C`\-DPTR_IS_LONG\*(C'\fR when using 64 bit integers
+.PP
+\fIVMS\fR
+.IX Subsection "VMS"
+.IP \(bu 4
+Fixed \f(CW\*(C`PerlIO::Scalar\*(C'\fR in-memory file record-style reads.
+.IP \(bu 4
+pipe shutdown at process exit should now be more robust.
+.IP \(bu 4
+Bugs in VMS exit handling tickled by \f(CW\*(C`Test::Harness\*(C'\fR 2.64 have been fixed.
+.IP \(bu 4
+Fix \f(CWfcntl()\fR locking capability test in \fIconfigure.com\fR.
+.IP \(bu 4
+Replaced \f(CW\*(C`shrplib=\*(Aqdefine\*(Aq\*(C'\fR with \f(CW\*(C`useshrplib=\*(Aqtrue\*(Aq\*(C'\fR on VMS.
+.PP
+\fIWindows\fR
+.IX Subsection "Windows"
+.IP \(bu 4
+\&\f(CW\*(C`File::Find\*(C'\fR used to fail when the target directory is a bare drive letter and
+\&\f(CW\*(C`no_chdir\*(C'\fR is 1 (the default is 0). [RT #41555]
+.IP \(bu 4
+A build problem with specifying \f(CW\*(C`USE_MULTI\*(C'\fR and \f(CW\*(C`USE_ITHREADS\*(C'\fR but without
+\&\f(CW\*(C`USE_IMP_SYS\*(C'\fR has been fixed.
+.IP \(bu 4
+The process id is no longer truncated to 16 bits on some Windows platforms
+( http://bugs.activestate.com/show_bug.cgi?id=72443 )
+.IP \(bu 4
+Fixed bug RT #54828 in \fIperlio.c\fR where calling \f(CW\*(C`binmode\*(C'\fR on Win32 and Cygwin
+may cause a segmentation fault.
+.SS "Smaller fixes"
+.IX Subsection "Smaller fixes"
+.IP \(bu 4
+It is now possible to overload \f(CW\*(C`eq\*(C'\fR when using \f(CW\*(C`nomethod\*(C'\fR.
+.IP \(bu 4
+Various problems using \f(CW\*(C`overload\*(C'\fR with 64 bit integers corrected.
+.IP \(bu 4
+The reference count of \f(CW\*(C`PerlIO\*(C'\fR file descriptors is now correctly handled.
+.IP \(bu 4
+On VMS, escaped dots will be preserved when converted to Unix syntax.
+.IP \(bu 4
+\&\f(CW\*(C`keys %+\*(C'\fR no longer throws an \f(CW\*(Aqambiguous\*(Aq\fR warning.
+.IP \(bu 4
+Using \f(CW\*(C`#!perl \-d\*(C'\fR could trigger an assertion, which has been fixed.
+.IP \(bu 4
+Don't stringify tied code references in \f(CW@INC\fR when calling \f(CW\*(C`require\*(C'\fR.
+.IP \(bu 4
+Code references in \f(CW@INC\fR report the correct file name when \f(CW\*(C`_\|_FILE_\|_\*(C'\fR is
+used.
+.IP \(bu 4
+Width and precision in sprintf didn't handle characters above 255 correctly.
+[RT #40473]
+.IP \(bu 4
+List slices with indices out of range now work more consistently.
+[RT #39882]
+.IP \(bu 4
+A change introduced with perl 5.8.1 broke the parsing of arguments of the form
+\&\f(CW\*(C`\-foo=bar\*(C'\fR with the \f(CW\*(C`\-s\*(C'\fR on the <#!> line. This has been fixed. See
+http://bugs.activestate.com/show_bug.cgi?id=43483
+.IP \(bu 4
+\&\f(CW\*(C`tr///\*(C'\fR is now threadsafe. Previously it was storing a swash inside its OP,
+rather than in a pad.
+.IP \(bu 4
+\&\fIpod2html\fR labels anchors more consistently and handles nested definition
+lists better.
+.IP \(bu 4
+\&\f(CW\*(C`threads\*(C'\fR cleanup veto has been extended to include \f(CWperl_free()\fR and
+\&\f(CWperl_destruct()\fR
+.IP \(bu 4
+On some systems, changes to \f(CW$ENV{TZ}\fR would not always be
+respected by the underlying calls to \f(CWlocaltime_r()\fR.  Perl now
+forces the inspection of the environment on these systems.
+.IP \(bu 4
+The special variable \f(CW$^R\fR is now more consistently set when executing
+regexps using the \f(CW\*(C`(?{...})\*(C'\fR construct.  In particular, it will still
+be set even if backreferences or optional sub-patterns \f(CW\*(C`(?:...)?\*(C'\fR are
+used.
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+.ie n .SS "panic: sv_chop %s"
+.el .SS "panic: sv_chop \f(CW%s\fP"
+.IX Subsection "panic: sv_chop %s"
+This new fatal error occurs when the C routine \f(CWPerl_sv_chop()\fR was passed a
+position that is not within the scalar's string buffer. This is caused by
+buggy XS code, and at this point recovery is not possible.
+.SS "Maximal count of pending signals (%s) exceeded"
+.IX Subsection "Maximal count of pending signals (%s) exceeded"
+This new fatal error occurs when the perl process has to abort due to
+too many pending signals, which is bound to prevent perl from being
+able to handle further incoming signals safely.
+.ie n .SS "panic: attempt to call %s in %s"
+.el .SS "panic: attempt to call \f(CW%s\fP in \f(CW%s\fP"
+.IX Subsection "panic: attempt to call %s in %s"
+This new fatal error occurs when the ACL version file test operator is used
+where it is not available on the current platform. Earlier checks mean that
+it should never be possible to get this.
+.SS "FETCHSIZE returned a negative value"
+.IX Subsection "FETCHSIZE returned a negative value"
+New error indicating that a tied array has claimed to have a negative
+number of elements.
+.ie n .SS "Can't upgrade %s (%d) to %d"
+.el .SS "Can't upgrade \f(CW%s\fP (%d) to \f(CW%d\fP"
+.IX Subsection "Can't upgrade %s (%d) to %d"
+Previously the internal error from the SV upgrade code was the less informative
+\&\fICan't upgrade that kind of scalar\fR. It now reports the current internal type,
+and the new type requested.
+.ie n .SS "%s argument is not a HASH or ARRAY element or a subroutine"
+.el .SS "\f(CW%s\fP argument is not a HASH or ARRAY element or a subroutine"
+.IX Subsection "%s argument is not a HASH or ARRAY element or a subroutine"
+This error, thrown if an invalid argument is provided to \f(CW\*(C`exists\*(C'\fR now
+correctly includes "or a subroutine". [RT #38955]
+.ie n .SS "Cannot make the non-overridable builtin %s fatal"
+.el .SS "Cannot make the non-overridable builtin \f(CW%s\fP fatal"
+.IX Subsection "Cannot make the non-overridable builtin %s fatal"
+This error in \f(CW\*(C`Fatal\*(C'\fR previously did not show the name of the builtin in
+question (now represented by \f(CW%s\fR above).
+.ie n .SS "Unrecognized character '%s' in column %d"
+.el .SS "Unrecognized character '%s' in column \f(CW%d\fP"
+.IX Subsection "Unrecognized character '%s' in column %d"
+This error previously did not state the column.
+.SS "Offset outside string"
+.IX Subsection "Offset outside string"
+This can now also be generated by a \f(CW\*(C`seek\*(C'\fR on a file handle using
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR.
+.SS "Invalid escape in the specified encoding in regexp; marked by <\-\- HERE in m/%s/"
+.IX Subsection "Invalid escape in the specified encoding in regexp; marked by <-- HERE in m/%s/"
+New error, introduced as part of the fix to RT #40641 to handle encoding
+of Unicode characters in regular expression comments.
+.SS "Your machine doesn't support dump/undump."
+.IX Subsection "Your machine doesn't support dump/undump."
+A more informative fatal error issued when calling \f(CW\*(C`dump\*(C'\fR on Win32 and
+Cygwin. (Given that the purpose of \f(CW\*(C`dump\*(C'\fR is to abort with a core dump,
+and core dumps can't be produced on these platforms, this is more useful than
+silently exiting.)
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+The perl sources can now be compiled with a C++ compiler instead of a C
+compiler. A necessary implementation details is that under C++, the macro
+\&\f(CW\*(C`XS\*(C'\fR used to define XSUBs now includes an \f(CW\*(C`extern "C"\*(C'\fR definition. A side
+effect of this is that \fBC++\fR code that used the construction
+.PP
+.Vb 1
+\&    typedef XS(SwigPerlWrapper);
+.Ve
+.PP
+now needs to be written
+.PP
+.Vb 1
+\&    typedef XSPROTO(SwigPerlWrapper);
+.Ve
+.PP
+using the new \f(CW\*(C`XSPROTO\*(C'\fR macro, in order to compile. C extensions are
+unaffected, although C extensions are encouraged to use \f(CW\*(C`XSPROTO\*(C'\fR too.
+This change was present in the 5.10.0 release of perl, so any actively
+maintained code that happened to use this construction should already have
+been adapted. Code that needs changing will fail with a compilation error.
+.PP
+\&\f(CW\*(C`set\*(C'\fR magic on localizing/assigning to a magic variable will now only
+trigger for \fIcontainer magics\fR, i.e. it will for \f(CW%ENV\fR or \f(CW%SIG\fR
+but not for \f(CW$#array\fR.
+.PP
+The new API macro \f(CWnewSVpvs()\fR can be used in place of constructions such as
+\&\f(CW\*(C`newSVpvn("ISA", 3)\*(C'\fR. It takes a single string constant, and at C compile
+time determines its length.
+.PP
+The new API function \f(CWPerl_newSV_type()\fR can be used as a more efficient
+replacement of the common idiom
+.PP
+.Vb 2
+\&    sv = newSV(0);
+\&    sv_upgrade(sv, type);
+.Ve
+.PP
+Similarly \f(CWPerl_newSVpvn_flags()\fR can be used to combine
+\&\f(CWPerl_newSVpv()\fR with \f(CWPerl_sv_2mortal()\fR or the equivalent
+\&\f(CWPerl_sv_newmortal()\fR with \f(CWPerl_sv_setpvn()\fR
+.PP
+Two new macros \f(CWmPUSHs()\fR and \f(CWmXPUSHs()\fR are added, to make it easier to
+push mortal SVs onto the stack. They were then used to fix several bugs where
+values on the stack had not been mortalised.
+.PP
+A \f(CWPerl_signbit()\fR function was added to test the sign of an \f(CW\*(C`NV\*(C'\fR. It 
+maps to the system one when available.
+.PP
+\&\f(CWPerl_av_reify()\fR, \f(CWPerl_lex_end()\fR, \f(CWPerl_mod()\fR, \f(CWPerl_op_clear()\fR,
+\&\f(CWPerl_pop_return()\fR, \f(CWPerl_qerror()\fR, \f(CWPerl_setdefout()\fR,
+\&\f(CWPerl_vivify_defelem()\fR and \f(CWPerl_yylex()\fR are now visible to extensions.
+This was required to allow \f(CW\*(C`Data::Alias\*(C'\fR to work on Windows.
+.PP
+\&\f(CWPerl_find_runcv()\fR is now visible to perl core extensions. This was required
+to allow \f(CW\*(C`Sub::Current\*(C'\fR to work on Windows.
+.PP
+\&\f(CW\*(C`ptr_table*\*(C'\fR functions are now available in unthreaded perl. \f(CW\*(C`Storable\*(C'\fR
+takes advantage of this.
+.PP
+There have been many small cleanups made to the internals. In particular,
+\&\f(CWPerl_sv_upgrade()\fR has been simplified considerably, with a straight-through
+code path that uses \f(CWmemset()\fR and \f(CWmemcpy()\fR to initialise the new body,
+rather than assignment via multiple temporary variables. It has also
+benefited from simplification and de-duplication of the arena management
+code.
+.PP
+A lot of small improvements in the code base were made due to reports from
+the Coverity static code analyzer.
+.PP
+Corrected use and documentation of \f(CWPerl_gv_stashpv()\fR, \f(CWPerl_gv_stashpvn()\fR,
+\&\f(CWPerl_gv_stashsv()\fR functions (last parameter is a bitmask, not boolean).
+.PP
+\&\f(CW\*(C`PERL_SYS_INIT\*(C'\fR, \f(CW\*(C`PERL_SYS_INIT3\*(C'\fR and \f(CW\*(C`PERL_SYS_TERM\*(C'\fR macros have been
+changed into functions.
+.PP
+\&\f(CW\*(C`PERLSYS_TERM\*(C'\fR no longer requires a context. \f(CWPerlIO_teardown()\fR
+is now called without a context, and debugging output in this function has
+been disabled because that required that an interpreter was present, an invalid
+assumption at termination time.
+.PP
+All compile time options which affect binary compatibility have been grouped
+together into a global variable (\f(CW\*(C`PL_bincompat_options\*(C'\fR).
+.PP
+The values of \f(CW\*(C`PERL_REVISION\*(C'\fR, \f(CW\*(C`PERL_VERSION\*(C'\fR and \f(CW\*(C`PERL_SUBVERSION\*(C'\fR are
+now baked into global variables (and hence into any shared perl library).
+Additionally under \f(CW\*(C`MULTIPLICITY\*(C'\fR, the perl executable now records the size of
+the interpreter structure (total, and for this version). Coupled with
+\&\f(CW\*(C`PL_bincompat_options\*(C'\fR this will allow 5.8.10 (and later), when compiled with a
+shared perl library, to perform sanity checks in \f(CWmain()\fR to verify that the
+shared library is indeed binary compatible.
+.PP
+Symbolic references can now have embedded NULs. The new public function
+\&\f(CWPerl_get_cvn_flags()\fR can be used in extensions if you have to handle them.
+.SS "Macro cleanups"
+.IX Subsection "Macro cleanups"
+The core code, and XS code in \fIext\fR that is not dual-lived on CPAN, no longer
+uses the macros \f(CW\*(C`PL_na\*(C'\fR, \f(CWNEWSV()\fR, \f(CWNull()\fR, \f(CW\*(C`Nullav\*(C'\fR, \f(CW\*(C`Nullcv\*(C'\fR,
+\&\f(CW\*(C`Nullhv\*(C'\fR, \f(CW\*(C`Nullhv\*(C'\fR \fIetc\fR. Their use is discouraged in new code,
+particularly \f(CW\*(C`PL_na\*(C'\fR, which is a small performance hit.
+.SH "New Tests"
+.IX Header "New Tests"
+Many modules updated from CPAN incorporate new tests. Some core specific
+tests have been added:
+.IP ext/DynaLoader/t/DynaLoader.t 4
+.IX Item "ext/DynaLoader/t/DynaLoader.t"
+Tests for the \f(CW\*(C`DynaLoader\*(C'\fR module.
+.IP t/comp/fold.t 4
+.IX Item "t/comp/fold.t"
+Tests for compile-time constant folding.
+.IP t/io/pvbm.t 4
+.IX Item "t/io/pvbm.t"
+Tests incorporated from 5.10.0 which check that there is no unexpected
+interaction between the internal types \f(CW\*(C`PVBM\*(C'\fR and \f(CW\*(C`PVGV\*(C'\fR.
+.IP t/lib/proxy_constant_subs.t 4
+.IX Item "t/lib/proxy_constant_subs.t"
+Tests for the new form of constant subroutines.
+.IP t/op/attrhand.t 4
+.IX Item "t/op/attrhand.t"
+Tests for \f(CW\*(C`Attribute::Handlers\*(C'\fR.
+.IP t/op/dbm.t 4
+.IX Item "t/op/dbm.t"
+Tests for \f(CW\*(C`dbmopen\*(C'\fR.
+.IP t/op/inccode\-tie.t 4
+.IX Item "t/op/inccode-tie.t"
+Calls all tests in \fIt/op/inccode.t\fR after first tying \f(CW@INC\fR.
+.IP t/op/incfilter.t 4
+.IX Item "t/op/incfilter.t"
+Tests for source filters returned from code references in \f(CW@INC\fR.
+.IP t/op/kill0.t 4
+.IX Item "t/op/kill0.t"
+Tests for RT #30970.
+.IP t/op/qrstack.t 4
+.IX Item "t/op/qrstack.t"
+Tests for RT #41484.
+.IP t/op/qr.t 4
+.IX Item "t/op/qr.t"
+Tests for the \f(CW\*(C`qr//\*(C'\fR construct.
+.IP t/op/regexp_qr_embed.t 4
+.IX Item "t/op/regexp_qr_embed.t"
+Tests for the \f(CW\*(C`qr//\*(C'\fR construct within another regexp.
+.IP t/op/regexp_qr.t 4
+.IX Item "t/op/regexp_qr.t"
+Tests for the \f(CW\*(C`qr//\*(C'\fR construct.
+.IP t/op/rxcode.t 4
+.IX Item "t/op/rxcode.t"
+Tests for RT #32840.
+.IP t/op/studytied.t 4
+.IX Item "t/op/studytied.t"
+Tests for \f(CW\*(C`study\*(C'\fR on tied scalars.
+.IP t/op/substT.t 4
+.IX Item "t/op/substT.t"
+Tests for \f(CW\*(C`subst\*(C'\fR run under \f(CW\*(C`\-T\*(C'\fR mode.
+.IP t/op/symbolcache.t 4
+.IX Item "t/op/symbolcache.t"
+Tests for \f(CW\*(C`undef\*(C'\fR and \f(CW\*(C`delete\*(C'\fR on stash entries that are bound to
+subroutines or methods.
+.IP t/op/upgrade.t 4
+.IX Item "t/op/upgrade.t"
+Tests for \f(CWPerl_sv_upgrade()\fR.
+.IP t/mro/package_aliases.t 4
+.IX Item "t/mro/package_aliases.t"
+MRO tests for \f(CW\*(C`isa\*(C'\fR and package aliases.
+.IP t/pod/twice.t 4
+.IX Item "t/pod/twice.t"
+Tests for calling \f(CW\*(C`Pod::Parser\*(C'\fR twice.
+.IP t/run/cloexec.t 4
+.IX Item "t/run/cloexec.t"
+Tests for inheriting file descriptors across \f(CW\*(C`exec\*(C'\fR (close-on-exec).
+.IP t/uni/cache.t 4
+.IX Item "t/uni/cache.t"
+Tests for the UTF\-8 caching code.
+.IP t/uni/chr.t 4
+.IX Item "t/uni/chr.t"
+Test that strange encodings do not upset \f(CWPerl_pp_chr()\fR.
+.IP t/uni/greek.t 4
+.IX Item "t/uni/greek.t"
+Tests for RT #40641.
+.IP t/uni/latin2.t 4
+.IX Item "t/uni/latin2.t"
+Tests for RT #40641.
+.IP t/uni/overload.t 4
+.IX Item "t/uni/overload.t"
+Tests for returning Unicode from overloaded values.
+.IP t/uni/tie.t 4
+.IX Item "t/uni/tie.t"
+Tests for returning Unicode from tied variables.
+.SH "Known Problems"
+.IX Header "Known Problems"
+There are no known new bugs.
+.PP
+However, programs that rely on bugs that have been fixed will have problems.
+Also, many bug fixes present in 5.10.0 can't be back-ported to the 5.8.x
+branch, because they require changes that are binary incompatible, or because
+the code changes are too large and hence too risky to incorporate.
+.PP
+We have only limited volunteer labour, and the maintenance burden is
+getting increasingly complex. Hence this will be the last significant
+release of the 5.8.x series. Any future releases of 5.8.x will likely
+only be to deal with security issues, and platform build
+failures. Hence you should look to migrating to 5.10.x, if you have
+not started already. Alternatively, if business requirements constrain
+you to continue to use 5.8.x, you may wish to consider commercial
+support from firms such as ActiveState.
+.SH "Platform Specific Notes"
+.IX Header "Platform Specific Notes"
+.SS Win32
+.IX Subsection "Win32"
+\&\f(CWreaddir()\fR, \f(CWcwd()\fR, \f(CW$^X\fR and \f(CW@INC\fR now use the alternate (short)
+filename if the long name is outside the current codepage (Jan Dubois).
+.PP
+\fIUpdated Modules\fR
+.IX Subsection "Updated Modules"
+.IP \(bu 4
+\&\f(CW\*(C`Win32\*(C'\fR upgraded to version 0.38. Now has a documented 'WinVista' response
+from \f(CW\*(C`GetOSName\*(C'\fR and support for Vista's privilege elevation in \f(CW\*(C`IsAdminUser\*(C'\fR.
+Support for Unicode characters in path names. Improved cygwin and Win64
+compatibility.
+.IP \(bu 4
+\&\f(CW\*(C`Win32API\*(C'\fR updated to 0.1001_01
+.IP \(bu 4
+\&\f(CWkillpg()\fR support added to \f(CW\*(C`MSWin32\*(C'\fR (Jan Dubois).
+.IP \(bu 4
+\&\f(CW\*(C`File::Spec::Win32\*(C'\fR upgraded to version 3.2701
+.SS OS/2
+.IX Subsection "OS/2"
+\fIUpdated Modules\fR
+.IX Subsection "Updated Modules"
+.IP \(bu 4
+\&\f(CW\*(C`OS2::Process\*(C'\fR upgraded to 1.03
+.Sp
+Ilya Zakharevich has added and documented several \f(CW\*(C`Window*\*(C'\fR and \f(CW\*(C`Clipbrd*\*(C'\fR
+functions.
+.IP \(bu 4
+\&\f(CW\*(C`OS2::REXX::DLL\*(C'\fR, \f(CW\*(C`OS2::REXX\*(C'\fR updated to version 1.03
+.SS VMS
+.IX Subsection "VMS"
+\fIUpdated Modules\fR
+.IX Subsection "Updated Modules"
+.IP \(bu 4
+\&\f(CW\*(C`DCLsym\*(C'\fR upgraded to version 1.03
+.IP \(bu 4
+\&\f(CW\*(C`Stdio\*(C'\fR upgraded to version 2.4
+.IP \(bu 4
+\&\f(CW\*(C`VMS::XSSymSet\*(C'\fR upgraded to 1.1.
+.SH Obituary
+.IX Header "Obituary"
+Nick Ing-Simmons, long time Perl hacker, author of the \f(CW\*(C`Tk\*(C'\fR and \f(CW\*(C`Encode\*(C'\fR
+modules, \fIperlio.c\fR in the core, and 5.003_02 pumpking, died of a heart
+attack on 25th September 2006. He will be missed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Some of the work in this release was funded by a TPF grant.
+.PP
+Steve Hay worked behind the scenes working out the causes of the differences
+between core modules, their CPAN releases, and previous core releases, and
+the best way to rectify them. He doesn't want to do it again. I know this
+feeling, and I'm very glad he did it this time, instead of me.
+.PP
+Paul Fenwick assembled a team of 18 volunteers, who broke the back of writing
+this document. In particular, Bradley Dean, Eddy Tan, and Vincent Pit
+provided half the team's contribution.
+.PP
+Schwern verified the list of updated module versions, correcting quite a few
+errors that I (and everyone else) had missed, both wrongly stated module
+versions, and changed modules that had not been listed.
+.PP
+The crack Berlin-based QA team of Andreas König and Slaven Rezic
+tirelessly re-built snapshots, tested most everything CPAN against
+them, and then identified the changes responsible for any module regressions,
+ensuring that several show-stopper bugs were stomped before the first release
+candidate was cut.
+.PP
+The other core committers contributed most of the changes, and applied most
+of the patches sent in by the hundreds of contributors listed in \fIAUTHORS\fR.
+.PP
+And obviously, Larry Wall, without whom we wouldn't have Perl.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org.  There may also be
+information at http://www.perl.org, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.  You can browse and search
+the Perl 5 bugs at http://bugs.perl.org/
+.PP
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5\-security\-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes
+all the core committers, who will be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for security
+issues in the Perl core, not for modules independently distributed on CPAN.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perl58delta.1 b/upstream/mageia-cauldron/man1/perl58delta.1
new file mode 100644
index 00000000..7cd96abc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perl58delta.1
@@ -0,0 +1,2906 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL58DELTA 1"
+.TH PERL58DELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perl58delta \- what is new for perl v5.8.0
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.6.0 release and
+the 5.8.0 release.
+.PP
+Many of the bug fixes in 5.8.0 were already seen in the 5.6.1
+maintenance release since the two releases were kept closely
+coordinated (while 5.8.0 was still called 5.7.something).
+.PP
+Changes that were integrated into the 5.6.1 release are marked \f(CW\*(C`[561]\*(C'\fR.
+Many of these changes have been further developed since 5.6.1 was released,
+those are marked \f(CW\*(C`[561+]\*(C'\fR.
+.PP
+You can see the list of changes in the 5.6.1 release (both from the
+5.005_03 release and the 5.6.0 release) by reading perl561delta.
+.SH "Highlights In 5.8.0"
+.IX Header "Highlights In 5.8.0"
+.IP \(bu 4
+Better Unicode support
+.IP \(bu 4
+New IO Implementation
+.IP \(bu 4
+New Thread Implementation
+.IP \(bu 4
+Better Numeric Accuracy
+.IP \(bu 4
+Safe Signals
+.IP \(bu 4
+Many New Modules
+.IP \(bu 4
+More Extensive Regression Testing
+.SH "Incompatible Changes"
+.IX Header "Incompatible Changes"
+.SS "Binary Incompatibility"
+.IX Subsection "Binary Incompatibility"
+\&\fBPerl 5.8 is not binary compatible with earlier releases of Perl.\fR
+.PP
+\&\fBYou have to recompile your XS modules.\fR
+.PP
+(Pure Perl modules should continue to work.)
+.PP
+The major reason for the discontinuity is the new IO architecture
+called PerlIO.  PerlIO is the default configuration because without
+it many new features of Perl 5.8 cannot be used.  In other words:
+you just have to recompile your modules containing XS code, sorry
+about that.
+.PP
+In future releases of Perl, non-PerlIO aware XS modules may become
+completely unsupported.  This shouldn't be too difficult for module
+authors, however: PerlIO has been designed as a drop-in replacement
+(at the source code level) for the stdio interface.
+.PP
+Depending on your platform, there are also other reasons why
+we decided to break binary compatibility, please read on.
+.SS "64\-bit platforms and malloc"
+.IX Subsection "64-bit platforms and malloc"
+If your pointers are 64 bits wide, the Perl malloc is no longer being
+used because it does not work well with 8\-byte pointers.  Also,
+usually the system mallocs on such platforms are much better optimized
+for such large memory models than the Perl malloc.  Some memory-hungry
+Perl applications like the PDL don't work well with Perl's malloc.
+Finally, other applications than Perl (such as mod_perl) tend to prefer
+the system malloc.  Such platforms include Alpha and 64\-bit HPPA,
+MIPS, PPC, and Sparc.
+.SS "AIX Dynaloading"
+.IX Subsection "AIX Dynaloading"
+The AIX dynaloading now uses in AIX releases 4.3 and newer the native
+dlopen interface of AIX instead of the old emulated interface.  This
+change will probably break backward compatibility with compiled
+modules.  The change was made to make Perl more compliant with other
+applications like mod_perl which are using the AIX native interface.
+.ie n .SS "Attributes for ""my"" variables now handled at run-time"
+.el .SS "Attributes for \f(CWmy\fP variables now handled at run-time"
+.IX Subsection "Attributes for my variables now handled at run-time"
+The \f(CW\*(C`my EXPR : ATTRS\*(C'\fR syntax now applies variable attributes at
+run-time.  (Subroutine and \f(CW\*(C`our\*(C'\fR variables still get attributes applied
+at compile-time.)  See attributes for additional details.  In particular,
+however, this allows variable attributes to be useful for \f(CW\*(C`tie\*(C'\fR interfaces,
+which was a deficiency of earlier releases.  Note that the new semantics
+doesn't work with the Attribute::Handlers module (as of version 0.76).
+.SS "Socket Extension Dynamic in VMS"
+.IX Subsection "Socket Extension Dynamic in VMS"
+The Socket extension is now dynamically loaded instead of being
+statically built in.  This may or may not be a problem with ancient
+TCP/IP stacks of VMS: we do not know since we weren't able to test
+Perl in such configurations.
+.SS "IEEE-format Floating Point Default on OpenVMS Alpha"
+.IX Subsection "IEEE-format Floating Point Default on OpenVMS Alpha"
+Perl now uses IEEE format (T_FLOAT) as the default internal floating
+point format on OpenVMS Alpha, potentially breaking binary compatibility
+with external libraries or existing data.  G_FLOAT is still available as
+a configuration option.  The default on VAX (D_FLOAT) has not changed.
+.ie n .SS "New Unicode Semantics (no more ""use utf8"", almost)"
+.el .SS "New Unicode Semantics (no more \f(CWuse utf8\fP, almost)"
+.IX Subsection "New Unicode Semantics (no more use utf8, almost)"
+Previously in Perl 5.6 to use Unicode one would say "use utf8" and
+then the operations (like string concatenation) were Unicode-aware
+in that lexical scope.
+.PP
+This was found to be an inconvenient interface, and in Perl 5.8 the
+Unicode model has completely changed: now the "Unicodeness" is bound
+to the data itself, and for most of the time "use utf8" is not needed
+at all.  The only remaining use of "use utf8" is when the Perl script
+itself has been written in the UTF\-8 encoding of Unicode.  (UTF\-8 has
+not been made the default since there are many Perl scripts out there
+that are using various national eight-bit character sets, which would
+be illegal in UTF\-8.)
+.PP
+See perluniintro for the explanation of the current model,
+and utf8 for the current use of the utf8 pragma.
+.SS "New Unicode Properties"
+.IX Subsection "New Unicode Properties"
+Unicode \fIscripts\fR are now supported. Scripts are similar to (and superior
+to) Unicode \fIblocks\fR. The difference between scripts and blocks is that
+scripts are the glyphs used by a language or a group of languages, while
+the blocks are more artificial groupings of (mostly) 256 characters based
+on the Unicode numbering.
+.PP
+In general, scripts are more inclusive, but not universally so. For
+example, while the script \f(CW\*(C`Latin\*(C'\fR includes all the Latin characters and
+their various diacritic-adorned versions, it does not include the various
+punctuation or digits (since they are not solely \f(CW\*(C`Latin\*(C'\fR).
+.PP
+A number of other properties are now supported, including \f(CW\*(C`\ep{L&}\*(C'\fR,
+\&\f(CW\*(C`\ep{Any}\*(C'\fR \f(CW\*(C`\ep{Assigned}\*(C'\fR, \f(CW\*(C`\ep{Unassigned}\*(C'\fR, \f(CW\*(C`\ep{Blank}\*(C'\fR [561] and
+\&\f(CW\*(C`\ep{SpacePerl}\*(C'\fR [561] (along with their \f(CW\*(C`\eP{...}\*(C'\fR versions, of course).
+See perlunicode for details, and more additions.
+.PP
+The \f(CW\*(C`In\*(C'\fR or \f(CW\*(C`Is\*(C'\fR prefix to names used with the \f(CW\*(C`\ep{...}\*(C'\fR and \f(CW\*(C`\eP{...}\*(C'\fR
+are now almost always optional. The only exception is that a \f(CW\*(C`In\*(C'\fR prefix
+is required to signify a Unicode block when a block name conflicts with a
+script name. For example, \f(CW\*(C`\ep{Tibetan}\*(C'\fR refers to the script, while
+\&\f(CW\*(C`\ep{InTibetan}\*(C'\fR refers to the block. When there is no name conflict, you
+can omit the \f(CW\*(C`In\*(C'\fR from the block name (e.g. \f(CW\*(C`\ep{BraillePatterns}\*(C'\fR), but
+to be safe, it's probably best to always use the \f(CW\*(C`In\*(C'\fR).
+.SS "REF(...) Instead Of SCALAR(...)"
+.IX Subsection "REF(...) Instead Of SCALAR(...)"
+A reference to a reference now stringifies as "REF(0x81485ec)" instead
+of "SCALAR(0x81485ec)" in order to be more consistent with the return
+value of \fBref()\fR.
+.SS "pack/unpack D/F recycled"
+.IX Subsection "pack/unpack D/F recycled"
+The undocumented pack/unpack template letters D/F have been recycled
+for better use: now they stand for long double (if supported by the
+platform) and NV (Perl internal floating point type).  (They used
+to be aliases for d/f, but you never knew that.)
+.SS "\fBglob()\fP now returns filenames in alphabetical order"
+.IX Subsection "glob() now returns filenames in alphabetical order"
+The list of filenames from \fBglob()\fR (or <...>) is now by default sorted
+alphabetically to be csh-compliant (which is what happened before
+in most Unix platforms).  (\fBbsd_glob()\fR does still sort platform
+natively, ASCII or EBCDIC, unless GLOB_ALPHASORT is specified.) [561]
+.SS Deprecations
+.IX Subsection "Deprecations"
+.IP \(bu 4
+The semantics of bless(REF, REF) were unclear and until someone proves
+it to make some sense, it is forbidden.
+.IP \(bu 4
+The obsolete chat2 library that should never have been allowed
+to escape the laboratory has been decommissioned.
+.IP \(bu 4
+Using chdir("") or chdir(undef) instead of explicit \fBchdir()\fR is
+doubtful.  A failure (think chdir(\fBsome_function()\fR) can lead into
+unintended \fBchdir()\fR to the home directory, therefore this behaviour
+is deprecated.
+.IP \(bu 4
+The builtin \fBdump()\fR function has probably outlived most of its
+usefulness.  The core-dumping functionality will remain in future
+available as an explicit call to \f(CWCORE::dump()\fR, but in future
+releases the behaviour of an unqualified \f(CWdump()\fR call may change.
+.IP \(bu 4
+The very dusty examples in the eg/ directory have been removed.
+Suggestions for new shiny examples welcome but the main issue is that
+the examples need to be documented, tested and (most importantly)
+maintained.
+.IP \(bu 4
+The (bogus) escape sequences \e8 and \e9 now give an optional warning
+("Unrecognized escape passed through").  There is no need to \e\-escape
+any \f(CW\*(C`\ew\*(C'\fR character.
+.IP \(bu 4
+The *glob{FILEHANDLE} is deprecated, use *glob{IO} instead.
+.IP \(bu 4
+The \f(CW\*(C`package;\*(C'\fR syntax (\f(CW\*(C`package\*(C'\fR without an argument) has been
+deprecated.  Its semantics were never that clear and its
+implementation even less so.  If you have used that feature to
+disallow all but fully qualified variables, \f(CW\*(C`use strict;\*(C'\fR instead.
+.IP \(bu 4
+The unimplemented POSIX regex features [[.cc.]] and [[=c=]] are still
+recognised but now cause fatal errors.  The previous behaviour of
+ignoring them by default and warning if requested was unacceptable
+since it, in a way, falsely promised that the features could be used.
+.IP \(bu 4
+In future releases, non-PerlIO aware XS modules may become completely
+unsupported.  Since PerlIO is a drop-in replacement for stdio at the
+source code level, this shouldn't be that drastic a change.
+.IP \(bu 4
+Previous versions of perl and some readings of some sections of Camel
+III implied that the \f(CW\*(C`:raw\*(C'\fR "discipline" was the inverse of \f(CW\*(C`:crlf\*(C'\fR.
+Turning off "clrfness" is no longer enough to make a stream truly
+binary. So the PerlIO \f(CW\*(C`:raw\*(C'\fR layer (or "discipline", to use the Camel
+book's older terminology) is now formally defined as being equivalent
+to binmode(FH) \- which is in turn defined as doing whatever is
+necessary to pass each byte as-is without any translation.  In
+particular binmode(FH) \- and hence \f(CW\*(C`:raw\*(C'\fR \- will now turn off both
+CRLF and UTF\-8 translation and remove other layers (e.g. :\fBencoding()\fR)
+which would modify byte stream.
+.IP \(bu 4
+The current user-visible implementation of pseudo-hashes (the weird
+use of the first array element) is deprecated starting from Perl 5.8.0
+and will be removed in Perl 5.10.0, and the feature will be
+implemented differently.  Not only is the current interface rather
+ugly, but the current implementation slows down normal array and hash
+use quite noticeably. The \f(CW\*(C`fields\*(C'\fR pragma interface will remain
+available.  The \fIrestricted hashes\fR interface is expected to
+be the replacement interface (see Hash::Util).  If your existing
+programs depends on the underlying implementation, consider using
+Class::PseudoHash from CPAN.
+.IP \(bu 4
+The syntaxes \f(CW\*(C`@a\->[...]\*(C'\fR and  \f(CW\*(C`%h\->{...}\*(C'\fR have now been deprecated.
+.IP \(bu 4
+After years of trying, suidperl is considered to be too complex to
+ever be considered truly secure.  The suidperl functionality is likely
+to be removed in a future release.
+.IP \(bu 4
+The 5.005 threads model (module \f(CW\*(C`Thread\*(C'\fR) is deprecated and expected
+to be removed in Perl 5.10.  Multithreaded code should be migrated to
+the new ithreads model (see threads, threads::shared and
+perlthrtut).
+.IP \(bu 4
+The long deprecated uppercase aliases for the string comparison
+operators (EQ, NE, LT, LE, GE, GT) have now been removed.
+.IP \(bu 4
+The tr///C and tr///U features have been removed and will not return;
+the interface was a mistake.  Sorry about that.  For similar
+functionality, see pack('U0', ...) and pack('C0', ...). [561]
+.IP \(bu 4
+Earlier Perls treated "sub foo (@bar)" as equivalent to "sub foo (@)".
+The prototypes are now checked better at compile-time for invalid
+syntax.  An optional warning is generated ("Illegal character in
+prototype...")  but this may be upgraded to a fatal error in a future
+release.
+.IP \(bu 4
+The \f(CW\*(C`exec LIST\*(C'\fR and \f(CW\*(C`system LIST\*(C'\fR operations now produce warnings on
+tainted data and in some future release they will produce fatal errors.
+.IP \(bu 4
+The existing behaviour when localising tied arrays and hashes is wrong,
+and will be changed in a future release, so do not rely on the existing
+behaviour. See "Localising Tied Arrays and Hashes Is Broken".
+.SH "Core Enhancements"
+.IX Header "Core Enhancements"
+.SS "Unicode Overhaul"
+.IX Subsection "Unicode Overhaul"
+Unicode in general should be now much more usable than in Perl 5.6.0
+(or even in 5.6.1).  Unicode can be used in hash keys, Unicode in
+regular expressions should work now, Unicode in tr/// should work now,
+Unicode in I/O should work now.  See perluniintro for introduction
+and perlunicode for details.
+.IP \(bu 4
+The Unicode Character Database coming with Perl has been upgraded
+to Unicode 3.2.0.  For more information, see http://www.unicode.org/ .
+[561+] (5.6.1 has UCD 3.0.1.)
+.IP \(bu 4
+For developers interested in enhancing Perl's Unicode capabilities:
+almost all the UCD files are included with the Perl distribution in
+the \fIlib/unicore\fR subdirectory.  The most notable omission, for space
+considerations, is the Unihan database.
+.IP \(bu 4
+The properties \ep{Blank} and \ep{SpacePerl} have been added. "Blank" is like
+C \fBisblank()\fR, that is, it contains only "horizontal whitespace" (the space
+character is, the newline isn't), and the "SpacePerl" is the Unicode
+equivalent of \f(CW\*(C`\es\*(C'\fR (\ep{Space} isn't, since that includes the vertical
+tabulator character, whereas \f(CW\*(C`\es\*(C'\fR doesn't.)
+.Sp
+See "New Unicode Properties" earlier in this document for additional
+information on changes with Unicode properties.
+.SS "PerlIO is Now The Default"
+.IX Subsection "PerlIO is Now The Default"
+.IP \(bu 4
+IO is now by default done via PerlIO rather than system's "stdio".
+PerlIO allows "layers" to be "pushed" onto a file handle to alter the
+handle's behaviour.  Layers can be specified at open time via 3\-arg
+form of open:
+.Sp
+.Vb 1
+\&   open($fh,\*(Aq>:crlf :utf8\*(Aq, $path) || ...
+.Ve
+.Sp
+or on already opened handles via extended \f(CW\*(C`binmode\*(C'\fR:
+.Sp
+.Vb 1
+\&   binmode($fh,\*(Aq:encoding(iso\-8859\-7)\*(Aq);
+.Ve
+.Sp
+The built-in layers are: unix (low level read/write), stdio (as in
+previous Perls), perlio (re-implementation of stdio buffering in a
+portable manner), crlf (does CRLF <=> "\en" translation as on Win32,
+but available on any platform).  A mmap layer may be available if
+platform supports it (mostly Unixes).
+.Sp
+Layers to be applied by default may be specified via the 'open' pragma.
+.Sp
+See "Installation and Configuration Improvements" for the effects
+of PerlIO on your architecture name.
+.IP \(bu 4
+If your platform supports \fBfork()\fR, you can use the list form of \f(CW\*(C`open\*(C'\fR
+for pipes.  For example:
+.Sp
+.Vb 1
+\&    open KID_PS, "\-|", "ps", "aux" or die $!;
+.Ve
+.Sp
+forks the \fBps\fR\|(1) command (without spawning a shell, as there are more
+than three arguments to \fBopen()\fR), and reads its standard output via the
+\&\f(CW\*(C`KID_PS\*(C'\fR filehandle.  See perlipc.
+.IP \(bu 4
+File handles can be marked as accepting Perl's internal encoding of Unicode
+(UTF\-8 or UTF-EBCDIC depending on platform) by a pseudo layer ":utf8" :
+.Sp
+.Vb 1
+\&   open($fh,">:utf8","Uni.txt");
+.Ve
+.Sp
+Note for EBCDIC users: the pseudo layer ":utf8" is erroneously named
+for you since it's not UTF\-8 what you will be getting but instead
+UTF-EBCDIC.  See perlunicode, utf8, and
+http://www.unicode.org/reports/tr16/ for more information.
+In future releases this naming may change.  See perluniintro
+for more information about UTF\-8.
+.IP \(bu 4
+If your environment variables (LC_ALL, LC_CTYPE, LANG) look like you
+want to use UTF\-8 (any of the variables match \f(CW\*(C`/utf\-?8/i\*(C'\fR), your
+STDIN, STDOUT, STDERR handles and the default open layer (see open)
+are marked as UTF\-8.  (This feature, like other new features that
+combine Unicode and I/O, work only if you are using PerlIO, but that's
+the default.)
+.Sp
+Note that after this Perl really does assume that everything is UTF\-8:
+for example if some input handle is not, Perl will probably very soon
+complain about the input data like this "Malformed UTF\-8 ..." since
+any old eight-bit data is not legal UTF\-8.
+.Sp
+Note for code authors: if you want to enable your users to use UTF\-8
+as their default encoding  but in your code still have eight-bit I/O streams
+(such as images or zip files), you need to explicitly \fBopen()\fR or \fBbinmode()\fR
+with \f(CW\*(C`:bytes\*(C'\fR (see "open" in perlfunc and "binmode" in perlfunc), or you
+can just use \f(CWbinmode(FH)\fR (nice for pre\-5.8.0 backward compatibility).
+.IP \(bu 4
+File handles can translate character encodings from/to Perl's internal
+Unicode form on read/write via the ":\fBencoding()\fR" layer.
+.IP \(bu 4
+File handles can be opened to "in memory" files held in Perl scalars via:
+.Sp
+.Vb 1
+\&   open($fh,\*(Aq>\*(Aq, \e$variable) || ...
+.Ve
+.IP \(bu 4
+Anonymous temporary files are available without need to
+\&'use FileHandle' or other module via
+.Sp
+.Vb 1
+\&   open($fh,"+>", undef) || ...
+.Ve
+.Sp
+That is a literal undef, not an undefined value.
+.SS ithreads
+.IX Subsection "ithreads"
+The new interpreter threads ("ithreads" for short) implementation of
+multithreading, by Arthur Bergman, replaces the old "5.005 threads"
+implementation.  In the ithreads model any data sharing between
+threads must be explicit, as opposed to the model where data sharing
+was implicit.  See threads and threads::shared, and
+perlthrtut.
+.PP
+As a part of the ithreads implementation Perl will also use
+any necessary and detectable reentrant libc interfaces.
+.SS "Restricted Hashes"
+.IX Subsection "Restricted Hashes"
+A restricted hash is restricted to a certain set of keys, no keys
+outside the set can be added.  Also individual keys can be restricted
+so that the key cannot be deleted and the value cannot be changed.
+No new syntax is involved: the Hash::Util module is the interface.
+.SS "Safe Signals"
+.IX Subsection "Safe Signals"
+Perl used to be fragile in that signals arriving at inopportune moments
+could corrupt Perl's internal state.  Now Perl postpones handling of
+signals until it's safe (between opcodes).
+.PP
+This change may have surprising side effects because signals no longer
+interrupt Perl instantly.  Perl will now first finish whatever it was
+doing, like finishing an internal operation (like \fBsort()\fR) or an
+external operation (like an I/O operation), and only then look at any
+arrived signals (and before starting the next operation).  No more corrupt
+internal state since the current operation is always finished first,
+but the signal may take more time to get heard.  Note that breaking
+out from potentially blocking operations should still work, though.
+.SS "Understanding of Numbers"
+.IX Subsection "Understanding of Numbers"
+In general a lot of fixing has happened in the area of Perl's
+understanding of numbers, both integer and floating point.  Since in
+many systems the standard number parsing functions like \f(CWstrtoul()\fR
+and \f(CWatof()\fR seem to have bugs, Perl tries to work around their
+deficiencies.  This results hopefully in more accurate numbers.
+.PP
+Perl now tries internally to use integer values in numeric conversions
+and basic arithmetics (+ \- * /) if the arguments are integers, and
+tries also to keep the results stored internally as integers.
+This change leads to often slightly faster and always less lossy
+arithmetics. (Previously Perl always preferred floating point numbers
+in its math.)
+.SS "Arrays now always interpolate into double-quoted strings [561]"
+.IX Subsection "Arrays now always interpolate into double-quoted strings [561]"
+In double-quoted strings, arrays now interpolate, no matter what.  The
+behavior in earlier versions of perl 5 was that arrays would interpolate
+into strings if the array had been mentioned before the string was
+compiled, and otherwise Perl would raise a fatal compile-time error.
+In versions 5.000 through 5.003, the error was
+.PP
+.Vb 1
+\&        Literal @example now requires backslash
+.Ve
+.PP
+In versions 5.004_01 through 5.6.0, the error was
+.PP
+.Vb 1
+\&        In string, @example now must be written as \e@example
+.Ve
+.PP
+The idea here was to get people into the habit of writing
+\&\f(CW"fred\e@example.com"\fR when they wanted a literal \f(CW\*(C`@\*(C'\fR sign, just as
+they have always written \f(CW"Give me back my \e$5"\fR when they wanted a
+literal \f(CW\*(C`$\*(C'\fR sign.
+.PP
+Starting with 5.6.1, when Perl now sees an \f(CW\*(C`@\*(C'\fR sign in a
+double-quoted string, it \fIalways\fR attempts to interpolate an array,
+regardless of whether or not the array has been used or declared
+already.  The fatal error has been downgraded to an optional warning:
+.PP
+.Vb 1
+\&        Possible unintended interpolation of @example in string
+.Ve
+.PP
+This warns you that \f(CW"fred@example.com"\fR is going to turn into
+\&\f(CW\*(C`fred.com\*(C'\fR if you don't backslash the \f(CW\*(C`@\*(C'\fR.
+See http://perl.plover.com/at\-error.html for more details
+about the history here.
+.SS "Miscellaneous Changes"
+.IX Subsection "Miscellaneous Changes"
+.IP \(bu 4
+AUTOLOAD is now lvaluable, meaning that you can add the :lvalue attribute
+to AUTOLOAD subroutines and you can assign to the AUTOLOAD return value.
+.IP \(bu 4
+The \f(CW$Config\fR{byteorder} (and corresponding BYTEORDER in config.h) was
+previously wrong in platforms if sizeof(long) was 4, but sizeof(IV)
+was 8.  The byteorder was only sizeof(long) bytes long (1234 or 4321),
+but now it is correctly sizeof(IV) bytes long, (12345678 or 87654321).
+(This problem didn't affect Windows platforms.)
+.Sp
+Also, \f(CW$Config\fR{byteorder} is now computed dynamically\-\-this is more
+robust with "fat binaries" where an executable image contains binaries
+for more than one binary platform, and when cross-compiling.
+.IP \(bu 4
+\&\f(CW\*(C`perl \-d:Module=arg,arg,arg\*(C'\fR now works (previously one couldn't pass
+in multiple arguments.)
+.IP \(bu 4
+\&\f(CW\*(C`do\*(C'\fR followed by a bareword now ensures that this bareword isn't
+a keyword (to avoid a bug where \f(CW\*(C`do q(foo.pl)\*(C'\fR tried to call a
+subroutine called \f(CW\*(C`q\*(C'\fR).  This means that for example instead of
+\&\f(CW\*(C`do format()\*(C'\fR you must write \f(CW\*(C`do &format()\*(C'\fR.
+.IP \(bu 4
+The builtin \fBdump()\fR now gives an optional warning
+\&\f(CW\*(C`dump() better written as CORE::dump()\*(C'\fR,
+meaning that by default \f(CWdump(...)\fR is resolved as the builtin
+\&\fBdump()\fR which dumps core and aborts, not as (possibly) user-defined
+\&\f(CW\*(C`sub dump\*(C'\fR.  To call the latter, qualify the call as \f(CW&dump(...)\fR.
+(The whole \fBdump()\fR feature is to considered deprecated, and possibly
+removed/changed in future releases.)
+.IP \(bu 4
+\&\fBchomp()\fR and \fBchop()\fR are now overridable.  Note, however, that their
+prototype (as given by \f(CWprototype("CORE::chomp")\fR is undefined,
+because it cannot be expressed and therefore one cannot really write
+replacements to override these builtins.
+.IP \(bu 4
+END blocks are now run even if you exit/die in a BEGIN block.
+Internally, the execution of END blocks is now controlled by
+PL_exit_flags & PERL_EXIT_DESTRUCT_END. This enables the new
+behaviour for Perl embedders. This will default in 5.10. See
+perlembed.
+.IP \(bu 4
+Formats now support zero-padded decimal fields.
+.IP \(bu 4
+Although "you shouldn't do that", it was possible to write code that
+depends on Perl's hashed key order (Data::Dumper does this).  The new
+algorithm "One-at-a-Time" produces a different hashed key order.
+More details are in "Performance Enhancements".
+.IP \(bu 4
+lstat(FILEHANDLE) now gives a warning because the operation makes no sense.
+In future releases this may become a fatal error.
+.IP \(bu 4
+Spurious syntax errors generated in certain situations, when \fBglob()\fR
+caused File::Glob to be loaded for the first time, have been fixed. [561]
+.IP \(bu 4
+Lvalue subroutines can now return \f(CW\*(C`undef\*(C'\fR in list context.  However,
+the lvalue subroutine feature still remains experimental.  [561+]
+.IP \(bu 4
+A lost warning "Can't declare ... dereference in my" has been
+restored (Perl had it earlier but it became lost in later releases.)
+.IP \(bu 4
+A new special regular expression variable has been introduced:
+\&\f(CW$^N\fR, which contains the most-recently closed group (submatch).
+.IP \(bu 4
+\&\f(CW\*(C`no Module;\*(C'\fR does not produce an error even if Module does not have an
+\&\fBunimport()\fR method.  This parallels the behavior of \f(CW\*(C`use\*(C'\fR vis-a-vis
+\&\f(CW\*(C`import\*(C'\fR. [561]
+.IP \(bu 4
+The numerical comparison operators return \f(CW\*(C`undef\*(C'\fR if either operand
+is a NaN.  Previously the behaviour was unspecified.
+.IP \(bu 4
+\&\f(CW\*(C`our\*(C'\fR can now have an experimental optional attribute \f(CW\*(C`unique\*(C'\fR that
+affects how global variables are shared among multiple interpreters,
+see "our" in perlfunc.
+.IP \(bu 4
+The following builtin functions are now overridable: \fBeach()\fR, \fBkeys()\fR,
+\&\fBpop()\fR, \fBpush()\fR, \fBshift()\fR, \fBsplice()\fR, \fBunshift()\fR. [561]
+.IP \(bu 4
+\&\f(CW\*(C`pack() / unpack()\*(C'\fR can now group template letters with \f(CW\*(C`()\*(C'\fR and then
+apply repetition/count modifiers on the groups.
+.IP \(bu 4
+\&\f(CW\*(C`pack() / unpack()\*(C'\fR can now process the Perl internal numeric types:
+IVs, UVs, NVs\-\- and also long doubles, if supported by the platform.
+The template letters are \f(CW\*(C`j\*(C'\fR, \f(CW\*(C`J\*(C'\fR, \f(CW\*(C`F\*(C'\fR, and \f(CW\*(C`D\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`pack(\*(AqU0a*\*(Aq, ...)\*(C'\fR can now be used to force a string to UTF\-8.
+.IP \(bu 4
+my _\|_PACKAGE_\|_ \f(CW$obj\fR now works. [561]
+.IP \(bu 4
+\&\fBPOSIX::sleep()\fR now returns the number of \fIunslept\fR seconds
+(as the POSIX standard says), as opposed to \fBCORE::sleep()\fR which
+returns the number of slept seconds.
+.IP \(bu 4
+\&\fBprintf()\fR and \fBsprintf()\fR now support parameter reordering using the
+\&\f(CW\*(C`%\ed+\e$\*(C'\fR and \f(CW\*(C`*\ed+\e$\*(C'\fR syntaxes.  For example
+.Sp
+.Vb 1
+\&    printf "%2\e$s %1\e$s\en", "foo", "bar";
+.Ve
+.Sp
+will print "bar foo\en".  This feature helps in writing
+internationalised software, and in general when the order
+of the parameters can vary.
+.IP \(bu 4
+The (\e&) prototype now works properly. [561]
+.IP \(bu 4
+prototype(\e[$@%&]) is now available to implicitly create references
+(useful for example if you want to emulate the \fBtie()\fR interface).
+.IP \(bu 4
+A new command-line option, \f(CW\*(C`\-t\*(C'\fR is available.  It is the
+little brother of \f(CW\*(C`\-T\*(C'\fR: instead of dying on taint violations,
+lexical warnings are given.  \fBThis is only meant as a temporary
+debugging aid while securing the code of old legacy applications.
+This is not a substitute for \-T.\fR
+.IP \(bu 4
+In other taint news, the \f(CW\*(C`exec LIST\*(C'\fR and \f(CW\*(C`system LIST\*(C'\fR have now been
+considered too risky (think \f(CW\*(C`exec @ARGV\*(C'\fR: it can start any program
+with any arguments), and now the said forms cause a warning under
+lexical warnings.  You should carefully launder the arguments to
+guarantee their validity.  In future releases of Perl the forms will
+become fatal errors so consider starting laundering now.
+.IP \(bu 4
+Tied hash interfaces are now required to have the EXISTS and DELETE
+methods (either own or inherited).
+.IP \(bu 4
+If tr/// is just counting characters, it doesn't attempt to
+modify its target.
+.IP \(bu 4
+\&\fBuntie()\fR will now call an \fBUNTIE()\fR hook if it exists.  See perltie
+for details. [561]
+.IP \(bu 4
+"utime" in perlfunc now supports \f(CW\*(C`utime undef, undef, @files\*(C'\fR to change the
+file timestamps to the current time.
+.IP \(bu 4
+The rules for allowing underscores (underbars) in numeric constants
+have been relaxed and simplified: now you can have an underscore
+simply \fBbetween digits\fR.
+.IP \(bu 4
+Rather than relying on C's argv[0] (which may not contain a full pathname)
+where possible $^X is now set by asking the operating system.
+(eg by reading \fI/proc/self/exe\fR on Linux, \fI/proc/curproc/file\fR on FreeBSD)
+.IP \(bu 4
+A new variable, \f(CW\*(C`${^TAINT}\*(C'\fR, indicates whether taint mode is enabled.
+.IP \(bu 4
+You can now override the \fBreadline()\fR builtin, and this overrides also
+the <FILEHANDLE> angle bracket operator.
+.IP \(bu 4
+The command-line options \-s and \-F are now recognized on the shebang
+(#!) line.
+.IP \(bu 4
+Use of the \f(CW\*(C`/c\*(C'\fR match modifier without an accompanying \f(CW\*(C`/g\*(C'\fR modifier
+elicits a new warning: \f(CW\*(C`Use of /c modifier is meaningless without /g\*(C'\fR.
+.Sp
+Use of \f(CW\*(C`/c\*(C'\fR in substitutions, even with \f(CW\*(C`/g\*(C'\fR, elicits
+\&\f(CW\*(C`Use of /c modifier is meaningless in s///\*(C'\fR.
+.Sp
+Use of \f(CW\*(C`/g\*(C'\fR with \f(CW\*(C`split\*(C'\fR elicits \f(CW\*(C`Use of /g modifier is meaningless
+in split\*(C'\fR.
+.IP \(bu 4
+Support for the \f(CW\*(C`CLONE\*(C'\fR special subroutine had been added.
+With ithreads, when a new thread is created, all Perl data is cloned,
+however non-Perl data cannot be cloned automatically.  In \f(CW\*(C`CLONE\*(C'\fR you
+can do whatever you need to do, like for example handle the cloning of
+non-Perl data, if necessary.  \f(CW\*(C`CLONE\*(C'\fR will be executed once for every
+package that has it defined or inherited.  It will be called in the
+context of the new thread, so all modifications are made in the new area.
+.Sp
+See perlmod
+.SH "Modules and Pragmata"
+.IX Header "Modules and Pragmata"
+.SS "New Modules and Pragmata"
+.IX Subsection "New Modules and Pragmata"
+.IP \(bu 4
+\&\f(CW\*(C`Attribute::Handlers\*(C'\fR, originally by Damian Conway and now maintained
+by Arthur Bergman, allows a class to define attribute handlers.
+.Sp
+.Vb 3
+\&    package MyPack;
+\&    use Attribute::Handlers;
+\&    sub Wolf :ATTR(SCALAR) { print "howl!\en" }
+\&
+\&    # later, in some package using or inheriting from MyPack...
+\&
+\&    my MyPack $Fluffy : Wolf; # the attribute handler Wolf will be called
+.Ve
+.Sp
+Both variables and routines can have attribute handlers.  Handlers can
+be specific to type (SCALAR, ARRAY, HASH, or CODE), or specific to the
+exact compilation phase (BEGIN, CHECK, INIT, or END).
+See Attribute::Handlers.
+.IP \(bu 4
+\&\f(CW\*(C`B::Concise\*(C'\fR, by Stephen McCamant, is a new compiler backend for
+walking the Perl syntax tree, printing concise info about ops.
+The output is highly customisable.  See B::Concise. [561+]
+.IP \(bu 4
+The new bignum, bigint, and bigrat pragmas, by Tels, implement
+transparent bignum support (using the Math::BigInt, Math::BigFloat,
+and Math::BigRat backends).
+.IP \(bu 4
+\&\f(CW\*(C`Class::ISA\*(C'\fR, by Sean Burke, is a module for reporting the search
+path for a class's ISA tree.  See Class::ISA.
+.IP \(bu 4
+\&\f(CW\*(C`Cwd\*(C'\fR now has a split personality: if possible, an XS extension is
+used, (this will hopefully be faster, more secure, and more robust)
+but if not possible, the familiar Perl implementation is used.
+.IP \(bu 4
+\&\f(CW\*(C`Devel::PPPort\*(C'\fR, originally by Kenneth Albanowski and now
+maintained by Paul Marquess, has been added.  It is primarily used
+by \f(CW\*(C`h2xs\*(C'\fR to enhance portability of XS modules between different
+versions of Perl.  See Devel::PPPort.
+.IP \(bu 4
+\&\f(CW\*(C`Digest\*(C'\fR, frontend module for calculating digests (checksums), from
+Gisle Aas, has been added.  See Digest.
+.IP \(bu 4
+\&\f(CW\*(C`Digest::MD5\*(C'\fR for calculating MD5 digests (checksums) as defined in
+RFC 1321, from Gisle Aas, has been added.  See Digest::MD5.
+.Sp
+.Vb 1
+\&    use Digest::MD5 \*(Aqmd5_hex\*(Aq;
+\&
+\&    $digest = md5_hex("Thirsty Camel");
+\&
+\&    print $digest, "\en"; # 01d19d9d2045e005c3f1b80e8b164de1
+.Ve
+.Sp
+NOTE: the \f(CW\*(C`MD5\*(C'\fR backward compatibility module is deliberately not
+included since its further use is discouraged.
+.Sp
+See also PerlIO::via::QuotedPrint.
+.IP \(bu 4
+\&\f(CW\*(C`Encode\*(C'\fR, originally by Nick Ing-Simmons and now maintained by Dan
+Kogai, provides a mechanism to translate between different character
+encodings.  Support for Unicode, ISO\-8859\-1, and ASCII are compiled in
+to the module.  Several other encodings (like the rest of the
+ISO\-8859, CP*/Win*, Mac, KOI8\-R, three variants EBCDIC, Chinese,
+Japanese, and Korean encodings) are included and can be loaded at
+runtime.  (For space considerations, the largest Chinese encodings
+have been separated into their own CPAN module, Encode::HanExtra,
+which Encode will use if available).  See Encode.
+.Sp
+Any encoding supported by Encode module is also available to the
+":\fBencoding()\fR" layer if PerlIO is used.
+.IP \(bu 4
+\&\f(CW\*(C`Hash::Util\*(C'\fR is the interface to the new \fIrestricted hashes\fR
+feature.  (Implemented by Jeffrey Friedl, Nick Ing-Simmons, and
+Michael Schwern.)  See Hash::Util.
+.IP \(bu 4
+\&\f(CW\*(C`I18N::Langinfo\*(C'\fR can be used to query locale information.
+See I18N::Langinfo.
+.IP \(bu 4
+\&\f(CW\*(C`I18N::LangTags\*(C'\fR, by Sean Burke, has functions for dealing with
+RFC3066\-style language tags.  See I18N::LangTags.
+.IP \(bu 4
+\&\f(CW\*(C`ExtUtils::Constant\*(C'\fR, by Nicholas Clark, is a new tool for extension
+writers for generating XS code to import C header constants.
+See ExtUtils::Constant.
+.IP \(bu 4
+\&\f(CW\*(C`Filter::Simple\*(C'\fR, by Damian Conway, is an easy-to-use frontend to
+Filter::Util::Call.  See Filter::Simple.
+.Sp
+.Vb 1
+\&    # in MyFilter.pm:
+\&
+\&    package MyFilter;
+\&
+\&    use Filter::Simple sub {
+\&        while (my ($from, $to) = splice @_, 0, 2) {
+\&                s/$from/$to/g;
+\&        }
+\&    };
+\&
+\&    1;
+\&
+\&    # in user\*(Aqs code:
+\&
+\&    use MyFilter qr/red/ => \*(Aqgreen\*(Aq;
+\&
+\&    print "red\en";   # this code is filtered, will print "green\en"
+\&    print "bored\en"; # this code is filtered, will print "bogreen\en"
+\&
+\&    no MyFilter;
+\&
+\&    print "red\en";   # this code is not filtered, will print "red\en"
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`File::Temp\*(C'\fR, by Tim Jenness, allows one to create temporary files
+and directories in an easy, portable, and secure way.  See File::Temp.
+[561+]
+.IP \(bu 4
+\&\f(CW\*(C`Filter::Util::Call\*(C'\fR, by Paul Marquess, provides you with the
+framework to write \fIsource filters\fR in Perl.  For most uses, the
+frontend Filter::Simple is to be preferred.  See Filter::Util::Call.
+.IP \(bu 4
+\&\f(CW\*(C`if\*(C'\fR, by Ilya Zakharevich, is a new pragma for conditional inclusion
+of modules.
+.IP \(bu 4
+libnet, by Graham Barr, is a collection of perl5 modules related
+to network programming.  See Net::FTP, Net::NNTP, Net::Ping
+(not part of libnet, but related), Net::POP3, Net::SMTP,
+and Net::Time.
+.Sp
+Perl installation leaves libnet unconfigured; use \fIlibnetcfg\fR
+to configure it.
+.IP \(bu 4
+\&\f(CW\*(C`List::Util\*(C'\fR, by Graham Barr, is a selection of general-utility
+list subroutines, such as \fBsum()\fR, \fBmin()\fR, \fBfirst()\fR, and \fBshuffle()\fR.
+See List::Util.
+.IP \(bu 4
+\&\f(CW\*(C`Locale::Constants\*(C'\fR, \f(CW\*(C`Locale::Country\*(C'\fR, \f(CW\*(C`Locale::Currency\*(C'\fR
+\&\f(CW\*(C`Locale::Language\*(C'\fR, and Locale::Script, by Neil Bowers, have
+been added.  They provide the codes for various locale standards, such
+as "fr" for France, "usd" for US Dollar, and "ja" for Japanese.
+.Sp
+.Vb 1
+\&    use Locale::Country;
+\&
+\&    $country = code2country(\*(Aqjp\*(Aq);               # $country gets \*(AqJapan\*(Aq
+\&    $code    = country2code(\*(AqNorway\*(Aq);           # $code gets \*(Aqno\*(Aq
+.Ve
+.Sp
+See Locale::Constants, Locale::Country, Locale::Currency,
+and Locale::Language.
+.IP \(bu 4
+\&\f(CW\*(C`Locale::Maketext\*(C'\fR, by Sean Burke, is a localization framework.  See
+Locale::Maketext, and Locale::Maketext::TPJ13.  The latter is an
+article about software localization, originally published in The Perl
+Journal #13, and republished here with kind permission.
+.IP \(bu 4
+\&\f(CW\*(C`Math::BigRat\*(C'\fR for big rational numbers, to accompany Math::BigInt and
+Math::BigFloat, from Tels.  See Math::BigRat.
+.IP \(bu 4
+\&\f(CW\*(C`Memoize\*(C'\fR can make your functions faster by trading space for time,
+from Mark-Jason Dominus.  See Memoize.
+.IP \(bu 4
+\&\f(CW\*(C`MIME::Base64\*(C'\fR, by Gisle Aas, allows you to encode data in base64,
+as defined in RFC 2045 \- \fIMIME (Multipurpose Internet Mail
+Extensions)\fR.
+.Sp
+.Vb 1
+\&    use MIME::Base64;
+\&
+\&    $encoded = encode_base64(\*(AqAladdin:open sesame\*(Aq);
+\&    $decoded = decode_base64($encoded);
+\&
+\&    print $encoded, "\en"; # "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+.Ve
+.Sp
+See MIME::Base64.
+.IP \(bu 4
+\&\f(CW\*(C`MIME::QuotedPrint\*(C'\fR, by Gisle Aas, allows you to encode data
+in quoted-printable encoding, as defined in RFC 2045 \- \fIMIME
+(Multipurpose Internet Mail Extensions)\fR.
+.Sp
+.Vb 1
+\&    use MIME::QuotedPrint;
+\&
+\&    $encoded = encode_qp("\exDE\exAD\exBE\exEF");
+\&    $decoded = decode_qp($encoded);
+\&
+\&    print $encoded, "\en"; # "=DE=AD=BE=EF\en"
+\&    print $decoded, "\en"; # "\exDE\exAD\exBE\exEF\en"
+.Ve
+.Sp
+See also PerlIO::via::QuotedPrint.
+.IP \(bu 4
+\&\f(CW\*(C`NEXT\*(C'\fR, by Damian Conway, is a pseudo-class for method redispatch.
+See NEXT.
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR is a new pragma for setting the default I/O layers
+for \fBopen()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR, by Nick Ing-Simmons, provides the implementation
+of IO to "in memory" Perl scalars as discussed above.  It also serves
+as an example of a loadable PerlIO layer.  Other future possibilities
+include PerlIO::Array and PerlIO::Code.  See PerlIO::scalar.
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::via\*(C'\fR, by Nick Ing-Simmons, acts as a PerlIO layer and wraps
+PerlIO layer functionality provided by a class (typically implemented
+in Perl code).
+.IP \(bu 4
+\&\f(CW\*(C`PerlIO::via::QuotedPrint\*(C'\fR, by Elizabeth Mattijsen, is an example
+of a \f(CW\*(C`PerlIO::via\*(C'\fR class:
+.Sp
+.Vb 2
+\&    use PerlIO::via::QuotedPrint;
+\&    open($fh,">:via(QuotedPrint)",$path);
+.Ve
+.Sp
+This will automatically convert everything output to \f(CW$fh\fR to
+Quoted-Printable.  See PerlIO::via and PerlIO::via::QuotedPrint.
+.IP \(bu 4
+\&\f(CW\*(C`Pod::ParseLink\*(C'\fR, by Russ Allbery, has been added,
+to parse L<> links in pods as described in the new
+perlpodspec.
+.IP \(bu 4
+\&\f(CW\*(C`Pod::Text::Overstrike\*(C'\fR, by Joe Smith, has been added.
+It converts POD data to formatted overstrike text.
+See Pod::Text::Overstrike. [561+]
+.IP \(bu 4
+\&\f(CW\*(C`Scalar::Util\*(C'\fR is a selection of general-utility scalar subroutines,
+such as \fBblessed()\fR, \fBreftype()\fR, and \fBtainted()\fR.  See Scalar::Util.
+.IP \(bu 4
+\&\f(CW\*(C`sort\*(C'\fR is a new pragma for controlling the behaviour of \fBsort()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`Storable\*(C'\fR gives persistence to Perl data structures by allowing the
+storage and retrieval of Perl data to and from files in a fast and
+compact binary format.  Because in effect Storable does serialisation
+of Perl data structures, with it you can also clone deep, hierarchical
+datastructures.  Storable was originally created by Raphael Manfredi,
+but it is now maintained by Abhijit Menon-Sen.  Storable has been
+enhanced to understand the two new hash features, Unicode keys and
+restricted hashes.  See Storable.
+.IP \(bu 4
+\&\f(CW\*(C`Switch\*(C'\fR, by Damian Conway, has been added.  Just by saying
+.Sp
+.Vb 1
+\&    use Switch;
+.Ve
+.Sp
+you have \f(CW\*(C`switch\*(C'\fR and \f(CW\*(C`case\*(C'\fR available in Perl.
+.Sp
+.Vb 1
+\&    use Switch;
+\&
+\&    switch ($val) {
+\&
+\&                case 1          { print "number 1" }
+\&                case "a"        { print "string a" }
+\&                case [1..10,42] { print "number in list" }
+\&                case (@array)   { print "number in list" }
+\&                case /\ew+/      { print "pattern" }
+\&                case qr/\ew+/    { print "pattern" }
+\&                case (%hash)    { print "entry in hash" }
+\&                case (\e%hash)   { print "entry in hash" }
+\&                case (\e&sub)    { print "arg to subroutine" }
+\&                else            { print "previous case not true" }
+\&    }
+.Ve
+.Sp
+See Switch.
+.IP \(bu 4
+\&\f(CW\*(C`Test::More\*(C'\fR, by Michael Schwern, is yet another framework for writing
+test scripts, more extensive than Test::Simple.  See Test::More.
+.IP \(bu 4
+\&\f(CW\*(C`Test::Simple\*(C'\fR, by Michael Schwern, has basic utilities for writing
+tests.   See Test::Simple.
+.IP \(bu 4
+\&\f(CW\*(C`Text::Balanced\*(C'\fR, by Damian Conway, has been added, for extracting
+delimited text sequences from strings.
+.Sp
+.Vb 1
+\&    use Text::Balanced \*(Aqextract_delimited\*(Aq;
+\&
+\&    ($a, $b) = extract_delimited("\*(Aqnever say never\*(Aq, he never said", "\*(Aq", \*(Aq\*(Aq);
+.Ve
+.Sp
+\&\f(CW$a\fR will be "'never say never'", \f(CW$b\fR will be ', he never said'.
+.Sp
+In addition to \fBextract_delimited()\fR, there are also \fBextract_bracketed()\fR,
+\&\fBextract_quotelike()\fR, \fBextract_codeblock()\fR, \fBextract_variable()\fR,
+\&\fBextract_tagged()\fR, \fBextract_multiple()\fR, \fBgen_delimited_pat()\fR, and
+\&\fBgen_extract_tagged()\fR.  With these, you can implement rather advanced
+parsing algorithms.  See Text::Balanced.
+.IP \(bu 4
+\&\f(CW\*(C`threads\*(C'\fR, by Arthur Bergman, is an interface to interpreter threads.
+Interpreter threads (ithreads) is the new thread model introduced in
+Perl 5.6 but only available as an internal interface for extension
+writers (and for Win32 Perl for \f(CWfork()\fR emulation).  See threads,
+threads::shared, and perlthrtut.
+.IP \(bu 4
+\&\f(CW\*(C`threads::shared\*(C'\fR, by Arthur Bergman, allows data sharing for
+interpreter threads.  See threads::shared.
+.IP \(bu 4
+\&\f(CW\*(C`Tie::File\*(C'\fR, by Mark-Jason Dominus, associates a Perl array with the
+lines of a file.  See Tie::File.
+.IP \(bu 4
+\&\f(CW\*(C`Tie::Memoize\*(C'\fR, by Ilya Zakharevich, provides on-demand loaded hashes.
+See Tie::Memoize.
+.IP \(bu 4
+\&\f(CW\*(C`Tie::RefHash::Nestable\*(C'\fR, by Edward Avis, allows storing hash
+references (unlike the standard Tie::RefHash)  The module is contained
+within Tie::RefHash.  See Tie::RefHash.
+.IP \(bu 4
+\&\f(CW\*(C`Time::HiRes\*(C'\fR, by Douglas E. Wegscheid, provides high resolution
+timing (ualarm, usleep, and gettimeofday).  See Time::HiRes.
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::UCD\*(C'\fR offers a querying interface to the Unicode Character
+Database.  See Unicode::UCD.
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::Collate\*(C'\fR, by SADAHIRO Tomoyuki, implements the UCA
+(Unicode Collation Algorithm) for sorting Unicode strings.
+See Unicode::Collate.
+.IP \(bu 4
+\&\f(CW\*(C`Unicode::Normalize\*(C'\fR, by SADAHIRO Tomoyuki, implements the various
+Unicode normalization forms.  See Unicode::Normalize.
+.IP \(bu 4
+\&\f(CW\*(C`XS::APItest\*(C'\fR, by Tim Jenness, is a test extension that exercises XS
+APIs.  Currently only \f(CWprintf()\fR is tested: how to output various
+basic data types from XS.
+.IP \(bu 4
+\&\f(CW\*(C`XS::Typemap\*(C'\fR, by Tim Jenness, is a test extension that exercises
+XS typemaps.  Nothing gets installed, but the code is worth studying
+for extension writers.
+.SS "Updated And Improved Modules and Pragmata"
+.IX Subsection "Updated And Improved Modules and Pragmata"
+.IP \(bu 4
+The following independently supported modules have been updated to the
+newest versions from CPAN: CGI, CPAN, DB_File, File::Spec, File::Temp,
+Getopt::Long, Math::BigFloat, Math::BigInt, the podlators bundle
+(Pod::Man, Pod::Text), Pod::LaTeX [561+], Pod::Parser, Storable,
+Term::ANSIColor, Test, Text\-Tabs+Wrap.
+.IP \(bu 4
+\&\fBattributes::reftype()\fR now works on tied arguments.
+.IP \(bu 4
+AutoLoader can now be disabled with \f(CW\*(C`no AutoLoader;\*(C'\fR.
+.IP \(bu 4
+B::Deparse has been significantly enhanced by Robin Houston.  It can
+now deparse almost all of the standard test suite (so that the tests
+still succeed).  There is a make target "test.deparse" for trying this
+out.
+.IP \(bu 4
+Carp now has better interface documentation, and the \f(CW@CARP_NOT\fR
+interface has been added to get optional control over where errors
+are reported independently of \f(CW@ISA\fR, by Ben Tilly.
+.IP \(bu 4
+Class::Struct can now define the classes in compile time.
+.IP \(bu 4
+Class::Struct now assigns the array/hash element if the accessor
+is called with an array/hash element as the \fBsole\fR argument.
+.IP \(bu 4
+The return value of \fBCwd::fastcwd()\fR is now tainted.
+.IP \(bu 4
+Data::Dumper now has an option to sort hashes.
+.IP \(bu 4
+Data::Dumper now has an option to dump code references
+using B::Deparse.
+.IP \(bu 4
+DB_File now supports newer Berkeley DB versions, among
+other improvements.
+.IP \(bu 4
+Devel::Peek now has an interface for the Perl memory statistics
+(this works only if you are using perl's malloc, and if you have
+compiled with debugging).
+.IP \(bu 4
+The English module can now be used without the infamous performance
+hit by saying
+.Sp
+.Vb 1
+\&        use English \*(Aq\-no_match_vars\*(Aq;
+.Ve
+.Sp
+(Assuming, of course, that you don't need the troublesome variables
+\&\f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR, or \f(CW\*(C`$\*(Aq\*(C'\fR.)  Also, introduced \f(CW@LAST_MATCH_START\fR and
+\&\f(CW@LAST_MATCH_END\fR English aliases for \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR.
+.IP \(bu 4
+ExtUtils::MakeMaker has been significantly cleaned up and fixed.
+The enhanced version has also been backported to earlier releases
+of Perl and submitted to CPAN so that the earlier releases can
+enjoy the fixes.
+.IP \(bu 4
+The arguments of \fBWriteMakefile()\fR in Makefile.PL are now checked
+for sanity much more carefully than before.  This may cause new
+warnings when modules are being installed.  See ExtUtils::MakeMaker
+for more details.
+.IP \(bu 4
+ExtUtils::MakeMaker now uses File::Spec internally, which hopefully
+leads to better portability.
+.IP \(bu 4
+Fcntl, Socket, and Sys::Syslog have been rewritten by Nicholas Clark
+to use the new-style constant dispatch section (see ExtUtils::Constant).
+This means that they will be more robust and hopefully faster.
+.IP \(bu 4
+File::Find now \fBchdir()\fRs correctly when chasing symbolic links. [561]
+.IP \(bu 4
+File::Find now has pre\- and post-processing callbacks.  It also
+correctly changes directories when chasing symbolic links.  Callbacks
+(naughtily) exiting with "next;" instead of "return;" now work.
+.IP \(bu 4
+File::Find is now (again) reentrant.  It also has been made
+more portable.
+.IP \(bu 4
+The warnings issued by File::Find now belong to their own category.
+You can enable/disable them with \f(CW\*(C`use/no warnings \*(AqFile::Find\*(Aq;\*(C'\fR.
+.IP \(bu 4
+\&\fBFile::Glob::glob()\fR has been renamed to \fBFile::Glob::bsd_glob()\fR
+because the name clashes with the builtin \fBglob()\fR.  The older
+name is still available for compatibility, but is deprecated. [561]
+.IP \(bu 4
+File::Glob now supports \f(CW\*(C`GLOB_LIMIT\*(C'\fR constant to limit the size of
+the returned list of filenames.
+.IP \(bu 4
+IPC::Open3 now allows the use of numeric file descriptors.
+.IP \(bu 4
+IO::Socket now has an \fBatmark()\fR method, which returns true if the socket
+is positioned at the out-of-band mark.  The method is also exportable
+as a \fBsockatmark()\fR function.
+.IP \(bu 4
+IO::Socket::INET failed to open the specified port if the service name
+was not known.  It now correctly uses the supplied port number as is. [561]
+.IP \(bu 4
+IO::Socket::INET has support for the ReusePort option (if your
+platform supports it).  The Reuse option now has an alias, ReuseAddr.
+For clarity, you may want to prefer ReuseAddr.
+.IP \(bu 4
+IO::Socket::INET now supports a value of zero for \f(CW\*(C`LocalPort\*(C'\fR
+(usually meaning that the operating system will make one up.)
+.IP \(bu 4
+\&'use lib' now works identically to \f(CW@INC\fR.  Removing directories
+with 'no lib' now works.
+.IP \(bu 4
+Math::BigFloat and Math::BigInt have undergone a full rewrite by Tels.
+They are now magnitudes faster, and they support various bignum
+libraries such as GMP and PARI as their backends.
+.IP \(bu 4
+Math::Complex handles inf, NaN etc., better.
+.IP \(bu 4
+Net::Ping has been considerably enhanced by Rob Brown: multihoming is
+now supported, Win32 functionality is better, there is now time
+measuring functionality (optionally high-resolution using
+Time::HiRes), and there is now "external" protocol which uses
+Net::Ping::External module which runs your external ping utility and
+parses the output.  A version of Net::Ping::External is available in
+CPAN.
+.Sp
+Note that some of the Net::Ping tests are disabled when running
+under the Perl distribution since one cannot assume one or more
+of the following: enabled echo port at localhost, full Internet
+connectivity, or sympathetic firewalls.  You can set the environment
+variable PERL_TEST_Net_Ping to "1" (one) before running the Perl test
+suite to enable all the Net::Ping tests.
+.IP \(bu 4
+\&\fBPOSIX::sigaction()\fR is now much more flexible and robust.
+You can now install coderef handlers, 'DEFAULT', and 'IGNORE'
+handlers, installing new handlers was not atomic.
+.IP \(bu 4
+In Safe, \f(CW%INC\fR is now localised in a Safe compartment so that
+use/require work.
+.IP \(bu 4
+In SDBM_File on DOSish platforms, some keys went missing because of
+lack of support for files with "holes".  A workaround for the problem
+has been added.
+.IP \(bu 4
+In Search::Dict one can now have a pre-processing hook for the
+lines being searched.
+.IP \(bu 4
+The Shell module now has an OO interface.
+.IP \(bu 4
+In Sys::Syslog there is now a failover mechanism that will go
+through alternative connection mechanisms until the message
+is successfully logged.
+.IP \(bu 4
+The Test module has been significantly enhanced.
+.IP \(bu 4
+\&\fBTime::Local::timelocal()\fR does not handle fractional seconds anymore.
+The rationale is that neither does \fBlocaltime()\fR, and \fBtimelocal()\fR and
+\&\fBlocaltime()\fR are supposed to be inverses of each other.
+.IP \(bu 4
+The vars pragma now supports declaring fully qualified variables.
+(Something that \f(CWour()\fR does not and will not support.)
+.IP \(bu 4
+The \f(CW\*(C`utf8::\*(C'\fR name space (as in the pragma) provides various
+Perl-callable functions to provide low level access to Perl's
+internal Unicode representation.  At the moment only \fBlength()\fR
+has been implemented.
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.IP \(bu 4
+Emacs perl mode (emacs/cperl\-mode.el) has been updated to version
+4.31.
+.IP \(bu 4
+\&\fIemacs/e2ctags.pl\fR is now much faster.
+.IP \(bu 4
+\&\f(CW\*(C`enc2xs\*(C'\fR is a tool for people adding their own encodings to the
+Encode module.
+.IP \(bu 4
+\&\f(CW\*(C`h2ph\*(C'\fR now supports C trigraphs.
+.IP \(bu 4
+\&\f(CW\*(C`h2xs\*(C'\fR now produces a template README.
+.IP \(bu 4
+\&\f(CW\*(C`h2xs\*(C'\fR now uses \f(CW\*(C`Devel::PPPort\*(C'\fR for better portability between
+different versions of Perl.
+.IP \(bu 4
+\&\f(CW\*(C`h2xs\*(C'\fR uses the new ExtUtils::Constant module
+which will affect newly created extensions that define constants.
+Since the new code is more correct (if you have two constants where the
+first one is a prefix of the second one, the first constant \fBnever\fR
+got defined), less lossy (it uses integers for integer constant,
+as opposed to the old code that used floating point numbers even for
+integer constants), and slightly faster, you might want to consider
+regenerating your extension code (the new scheme makes regenerating
+easy).  h2xs now also supports C trigraphs.
+.IP \(bu 4
+\&\f(CW\*(C`libnetcfg\*(C'\fR has been added to configure libnet.
+.IP \(bu 4
+\&\f(CW\*(C`perlbug\*(C'\fR is now much more robust.  It also sends the bug report to
+perl.org, not perl.com.
+.IP \(bu 4
+\&\f(CW\*(C`perlcc\*(C'\fR has been rewritten and its user interface (that is,
+command line) is much more like that of the Unix C compiler, cc.
+(The perlbc tools has been removed.  Use \f(CW\*(C`perlcc \-B\*(C'\fR instead.)
+\&\fBNote that perlcc is still considered very experimental and
+unsupported.\fR [561]
+.IP \(bu 4
+\&\f(CW\*(C`perlivp\*(C'\fR is a new Installation Verification Procedure utility
+for running any time after installing Perl.
+.IP \(bu 4
+\&\f(CW\*(C`piconv\*(C'\fR is an implementation of the character conversion utility
+\&\f(CW\*(C`iconv\*(C'\fR, demonstrating the new Encode module.
+.IP \(bu 4
+\&\f(CW\*(C`pod2html\*(C'\fR now allows specifying a cache directory.
+.IP \(bu 4
+\&\f(CW\*(C`pod2html\*(C'\fR now produces XHTML 1.0.
+.IP \(bu 4
+\&\f(CW\*(C`pod2html\*(C'\fR now understands POD written using different line endings
+(PC-like CRLF versus Unix-like LF versus MacClassic-like CR).
+.IP \(bu 4
+\&\f(CW\*(C`s2p\*(C'\fR has been completely rewritten in Perl.  (It is in fact a full
+implementation of sed in Perl: you can use the sed functionality by
+using the \f(CW\*(C`psed\*(C'\fR utility.)
+.IP \(bu 4
+\&\f(CW\*(C`xsubpp\*(C'\fR now understands POD documentation embedded in the *.xs
+files. [561]
+.IP \(bu 4
+\&\f(CW\*(C`xsubpp\*(C'\fR now supports the OUT keyword.
+.SH "New Documentation"
+.IX Header "New Documentation"
+.IP \(bu 4
+perl56delta details the changes between the 5.005 release and the
+5.6.0 release.
+.IP \(bu 4
+perlclib documents the internal replacements for standard C library
+functions.  (Interesting only for extension writers and Perl core
+hackers.) [561+]
+.IP \(bu 4
+perldebtut is a Perl debugging tutorial. [561+]
+.IP \(bu 4
+perlebcdic contains considerations for running Perl on EBCDIC
+platforms. [561+]
+.IP \(bu 4
+perlintro is a gentle introduction to Perl.
+.IP \(bu 4
+perliol documents the internals of PerlIO with layers.
+.IP \(bu 4
+perlmodstyle is a style guide for writing modules.
+.IP \(bu 4
+perlnewmod tells about writing and submitting a new module. [561+]
+.IP \(bu 4
+perlpacktut is a \fBpack()\fR tutorial.
+.IP \(bu 4
+perlpod has been rewritten to be clearer and to record the best
+practices gathered over the years.
+.IP \(bu 4
+perlpodspec is a more formal specification of the pod format,
+mainly of interest for writers of pod applications, not to
+people writing in pod.
+.IP \(bu 4
+perlretut is a regular expression tutorial. [561+]
+.IP \(bu 4
+perlrequick is a regular expressions quick-start guide.
+Yes, much quicker than perlretut. [561]
+.IP \(bu 4
+perltodo has been updated.
+.IP \(bu 4
+perltootc has been renamed as perltooc (to not to conflict
+with perltoot in filesystems restricted to "8.3" names).
+.IP \(bu 4
+perluniintro is an introduction to using Unicode in Perl.
+(perlunicode is more of a detailed reference and background
+information)
+.IP \(bu 4
+perlutil explains the command line utilities packaged with the Perl
+distribution. [561+]
+.PP
+The following platform-specific documents are available before
+the installation as README.\fIplatform\fR, and after the installation
+as perl\fIplatform\fR:
+.PP
+.Vb 5
+\&    perlaix perlamiga perlapollo perlbeos perlbs2000
+\&    perlce perlcygwin perldgux perldos perlepoc perlfreebsd perlhpux
+\&    perlhurd perlirix perlmachten perlmacos perlmint perlmpeix
+\&    perlnetware perlos2 perlos390 perlplan9 perlqnx perlsolaris
+\&    perltru64 perluts perlvmesa perlvms perlvos perlwin32
+.Ve
+.PP
+These documents usually detail one or more of the following subjects:
+configuring, building, testing, installing, and sometimes also using
+Perl on the said platform.
+.PP
+Eastern Asian Perl users are now welcomed in their own languages:
+README.jp (Japanese), README.ko (Korean), README.cn (simplified
+Chinese) and README.tw (traditional Chinese), which are written in
+normal pod but encoded in EUC-JP, EUC-KR, EUC-CN and Big5.  These
+will get installed as
+.PP
+.Vb 1
+\&   perljp perlko perlcn perltw
+.Ve
+.IP \(bu 4
+The documentation for the POSIX-BC platform is called "BS2000", to avoid
+confusion with the Perl POSIX module.
+.IP \(bu 4
+The documentation for the WinCE platform is called perlce (README.ce
+in the source code kit), to avoid confusion with the perlwin32
+documentation on 8.3\-restricted filesystems.
+.SH "Performance Enhancements"
+.IX Header "Performance Enhancements"
+.IP \(bu 4
+\&\fBmap()\fR could get pathologically slow when the result list it generates
+is larger than the source list.  The performance has been improved for
+common scenarios. [561]
+.IP \(bu 4
+\&\fBsort()\fR is also fully reentrant, in the sense that the sort function
+can itself call \fBsort()\fR.  This did not work reliably in previous
+releases. [561]
+.IP \(bu 4
+\&\fBsort()\fR has been changed to use primarily mergesort internally as
+opposed to the earlier quicksort.  For very small lists this may
+result in slightly slower sorting times, but in general the speedup
+should be at least 20%.  Additional bonuses are that the worst case
+behaviour of \fBsort()\fR is now better (in computer science terms it now
+runs in time O(N log N), as opposed to quicksort's Theta(N**2)
+worst-case run time behaviour), and that \fBsort()\fR is now stable
+(meaning that elements with identical keys will stay ordered as they
+were before the sort).  See the \f(CW\*(C`sort\*(C'\fR pragma for information.
+.Sp
+The story in more detail: suppose you want to serve yourself a little
+slice of Pi.
+.Sp
+.Vb 1
+\&    @digits = ( 3,1,4,1,5,9 );
+.Ve
+.Sp
+A numerical sort of the digits will yield (1,1,3,4,5,9), as expected.
+Which \f(CW1\fR comes first is hard to know, since one \f(CW1\fR looks pretty
+much like any other.  You can regard this as totally trivial,
+or somewhat profound.  However, if you just want to sort the even
+digits ahead of the odd ones, then what will
+.Sp
+.Vb 1
+\&    sort { ($a % 2) <=> ($b % 2) } @digits;
+.Ve
+.Sp
+yield?  The only even digit, \f(CW4\fR, will come first.  But how about
+the odd numbers, which all compare equal?  With the quicksort algorithm
+used to implement Perl 5.6 and earlier, the order of ties is left up
+to the sort.  So, as you add more and more digits of Pi, the order
+in which the sorted even and odd digits appear will change.
+and, for sufficiently large slices of Pi, the quicksort algorithm
+in Perl 5.8 won't return the same results even if reinvoked with the
+same input.  The justification for this rests with quicksort's
+worst case behavior.  If you run
+.Sp
+.Vb 1
+\&   sort { $a <=> $b } ( 1 .. $N , 1 .. $N );
+.Ve
+.Sp
+(something you might approximate if you wanted to merge two sorted
+arrays using sort), doubling \f(CW$N\fR doesn't just double the quicksort time,
+it \fIquadruples\fR it.  Quicksort has a worst case run time that can
+grow like N**2, so-called \fIquadratic\fR behaviour, and it can happen
+on patterns that may well arise in normal use.  You won't notice this
+for small arrays, but you \fIwill\fR notice it with larger arrays,
+and you may not live long enough for the sort to complete on arrays
+of a million elements.  So the 5.8 quicksort scrambles large arrays
+before sorting them, as a statistical defence against quadratic behaviour.
+But that means if you sort the same large array twice, ties may be
+broken in different ways.
+.Sp
+Because of the unpredictability of tie-breaking order, and the quadratic
+worst-case behaviour, quicksort was \fIalmost\fR replaced completely with
+a stable mergesort.  \fIStable\fR means that ties are broken to preserve
+the original order of appearance in the input array.  So
+.Sp
+.Vb 1
+\&    sort { ($a % 2) <=> ($b % 2) } (3,1,4,1,5,9);
+.Ve
+.Sp
+will yield (4,3,1,1,5,9), guaranteed.  The even and odd numbers
+appear in the output in the same order they appeared in the input.
+Mergesort has worst case O(N log N) behaviour, the best value
+attainable.  And, ironically, this mergesort does particularly
+well where quicksort goes quadratic:  mergesort sorts (1..$N, 1..$N)
+in O(N) time.  But quicksort was rescued at the last moment because
+it is faster than mergesort on certain inputs and platforms.
+For example, if you really \fIdon't\fR care about the order of even
+and odd digits, quicksort will run in O(N) time; it's very good
+at sorting many repetitions of a small number of distinct elements.
+The quicksort divide and conquer strategy works well on platforms
+with relatively small, very fast, caches.  Eventually, the problem gets
+whittled down to one that fits in the cache, from which point it
+benefits from the increased memory speed.
+.Sp
+Quicksort was rescued by implementing a sort pragma to control aspects
+of the sort.  The \fBstable\fR subpragma forces stable behaviour,
+regardless of algorithm.  The \fB_quicksort\fR and \fB_mergesort\fR
+subpragmas are heavy-handed ways to select the underlying implementation.
+The leading \f(CW\*(C`_\*(C'\fR is a reminder that these subpragmas may not survive
+beyond 5.8.  More appropriate mechanisms for selecting the implementation
+exist, but they wouldn't have arrived in time to save quicksort.
+.IP \(bu 4
+Hashes now use Bob Jenkins "One-at-a-Time" hashing key algorithm
+( http://burtleburtle.net/bob/hash/doobs.html ).  This algorithm is
+reasonably fast while producing a much better spread of values than
+the old hashing algorithm (originally by Chris Torek, later tweaked by
+Ilya Zakharevich).  Hash values output from the algorithm on a hash of
+all 3\-char printable ASCII keys comes much closer to passing the
+DIEHARD random number generation tests.  According to perlbench, this
+change has not affected the overall speed of Perl.
+.IP \(bu 4
+\&\fBunshift()\fR should now be noticeably faster.
+.SH "Installation and Configuration Improvements"
+.IX Header "Installation and Configuration Improvements"
+.SS "Generic Improvements"
+.IX Subsection "Generic Improvements"
+.IP \(bu 4
+INSTALL now explains how you can configure Perl to use 64\-bit
+integers even on non\-64\-bit platforms.
+.IP \(bu 4
+Policy.sh policy change: if you are reusing a Policy.sh file
+(see INSTALL) and you use Configure \-Dprefix=/foo/bar and in the old
+Policy \f(CW$prefix\fR eq \f(CW$siteprefix\fR and \f(CW$prefix\fR eq \f(CW$vendorprefix\fR, all of
+them will now be changed to the new prefix, /foo/bar.  (Previously
+only \f(CW$prefix\fR changed.)  If you do not like this new behaviour,
+specify prefix, siteprefix, and vendorprefix explicitly.
+.IP \(bu 4
+A new optional location for Perl libraries, otherlibdirs, is available.
+It can be used for example for vendor add-ons without disturbing Perl's
+own library directories.
+.IP \(bu 4
+In many platforms, the vendor-supplied 'cc' is too stripped-down to
+build Perl (basically, 'cc' doesn't do ANSI C).  If this seems
+to be the case and 'cc' does not seem to be the GNU C compiler
+\&'gcc', an automatic attempt is made to find and use 'gcc' instead.
+.IP \(bu 4
+gcc needs to closely track the operating system release to avoid
+build problems. If Configure finds that gcc was built for a different
+operating system release than is running, it now gives a clearly visible
+warning that there may be trouble ahead.
+.IP \(bu 4
+Since Perl 5.8 is not binary-compatible with previous releases
+of Perl, Configure no longer suggests including the 5.005
+modules in \f(CW@INC\fR.
+.IP \(bu 4
+Configure \f(CW\*(C`\-S\*(C'\fR can now run non-interactively. [561]
+.IP \(bu 4
+Configure support for pdp11\-style memory models has been removed due
+to obsolescence. [561]
+.IP \(bu 4
+configure.gnu now works with options with whitespace in them.
+.IP \(bu 4
+installperl now outputs everything to STDERR.
+.IP \(bu 4
+Because PerlIO is now the default on most platforms, "\-perlio" doesn't
+get appended to the \f(CW$Config\fR{archname} (also known as $^O) anymore.
+Instead, if you explicitly choose not to use perlio (Configure command
+line option \-Uuseperlio), you will get "\-stdio" appended.
+.IP \(bu 4
+Another change related to the architecture name is that "\-64all"
+(\-Duse64bitall, or "maximally 64\-bit") is appended only if your
+pointers are 64 bits wide.  (To be exact, the use64bitall is ignored.)
+.IP \(bu 4
+In AFS installations, one can configure the root of the AFS to be
+somewhere else than the default \fI/afs\fR by using the Configure
+parameter \f(CW\*(C`\-Dafsroot=/some/where/else\*(C'\fR.
+.IP \(bu 4
+APPLLIB_EXP, a lesser-known configuration-time definition, has been
+documented.  It can be used to prepend site-specific directories
+to Perl's default search path (@INC); see INSTALL for information.
+.IP \(bu 4
+The version of Berkeley DB used when the Perl (and, presumably, the
+DB_File extension) was built is now available as
+\&\f(CW@Config{qw(db_version_major db_version_minor db_version_patch)}\fR
+from Perl and as \f(CW\*(C`DB_VERSION_MAJOR_CFG DB_VERSION_MINOR_CFG
+DB_VERSION_PATCH_CFG\*(C'\fR from C.
+.IP \(bu 4
+Building Berkeley DB3 for compatibility modes for DB, NDBM, and ODBM
+has been documented in INSTALL.
+.IP \(bu 4
+If you have CPAN access (either network or a local copy such as a
+CD-ROM) you can during specify extra modules to Configure to build and
+install with Perl using the \-Dextras=...  option.  See INSTALL for
+more details.
+.IP \(bu 4
+In addition to config.over, a new override file, config.arch, is
+available.  This file is supposed to be used by hints file writers
+for architecture-wide changes (as opposed to config.over which is
+for site-wide changes).
+.IP \(bu 4
+If your file system supports symbolic links, you can build Perl outside
+of the source directory by
+.Sp
+.Vb 3
+\&        mkdir perl/build/directory
+\&        cd perl/build/directory
+\&        sh /path/to/perl/source/Configure \-Dmksymlinks ...
+.Ve
+.Sp
+This will create in perl/build/directory a tree of symbolic links
+pointing to files in /path/to/perl/source.  The original files are left
+unaffected.  After Configure has finished, you can just say
+.Sp
+.Vb 1
+\&        make all test
+.Ve
+.Sp
+and Perl will be built and tested, all in perl/build/directory.
+[561]
+.IP \(bu 4
+For Perl developers, several new make targets for profiling
+and debugging have been added; see perlhack.
+.RS 4
+.IP \(bu 8
+Use of the \fIgprof\fR tool to profile Perl has been documented in
+perlhack.  There is a make target called "perl.gprof" for
+generating a gprofiled Perl executable.
+.IP \(bu 8
+If you have GCC 3, there is a make target called "perl.gcov" for
+creating a gcoved Perl executable for coverage analysis.  See
+perlhack.
+.IP \(bu 8
+If you are on IRIX or Tru64 platforms, new profiling/debugging options
+have been added; see perlhack for more information about pixie and
+Third Degree.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Guidelines of how to construct minimal Perl installations have
+been added to INSTALL.
+.IP \(bu 4
+The Thread extension is now not built at all under ithreads
+(\f(CW\*(C`Configure \-Duseithreads\*(C'\fR) because it wouldn't work anyway (the
+Thread extension requires being Configured with \f(CW\*(C`\-Duse5005threads\*(C'\fR).
+.Sp
+\&\fBNote that the 5.005 threads are unsupported and deprecated: if you
+have code written for the old threads you should migrate it to the
+new ithreads model.\fR
+.IP \(bu 4
+The Gconvert macro ($Config{d_Gconvert}) used by perl for stringifying
+floating-point numbers is now more picky about using sprintf %.*g
+rules for the conversion.  Some platforms that used to use gcvt may
+now resort to the slower sprintf.
+.IP \(bu 4
+The obsolete method of making a special (e.g., debugging) flavor
+of perl by saying
+.Sp
+.Vb 1
+\&        make LIBPERL=libperld.a
+.Ve
+.Sp
+has been removed. Use \-DDEBUGGING instead.
+.SS "New Or Improved Platforms"
+.IX Subsection "New Or Improved Platforms"
+For the list of platforms known to support Perl,
+see "Supported Platforms" in perlport.
+.IP \(bu 4
+AIX dynamic loading should be now better supported.
+.IP \(bu 4
+AIX should now work better with gcc, threads, and 64\-bitness.  Also the
+long doubles support in AIX should be better now.  See perlaix.
+.IP \(bu 4
+AtheOS ( http://www.atheos.cx/ ) is a new platform.
+.IP \(bu 4
+BeOS has been reclaimed.
+.IP \(bu 4
+The DG/UX platform now supports 5.005\-style threads.
+See perldgux.
+.IP \(bu 4
+The DYNIX/ptx platform (also known as dynixptx) is supported at or
+near osvers 4.5.2.
+.IP \(bu 4
+EBCDIC platforms (z/OS (also known as OS/390), POSIX-BC, and VM/ESA)
+have been regained.  Many test suite tests still fail and the
+co-existence of Unicode and EBCDIC isn't quite settled, but the
+situation is much better than with Perl 5.6.  See perlos390,
+perlbs2000 (for POSIX-BC), and perlvmesa for more information.
+(\fBNote:\fR support for VM/ESA was removed in Perl v5.18.0. The relevant
+information was in \fIREADME.vmesa\fR)
+.IP \(bu 4
+Building perl with \-Duseithreads or \-Duse5005threads now works under
+HP-UX 10.20 (previously it only worked under 10.30 or later). You will
+need a thread library package installed. See README.hpux. [561]
+.IP \(bu 4
+Mac OS Classic is now supported in the mainstream source package
+(MacPerl has of course been available since perl 5.004 but now the
+source code bases of standard Perl and MacPerl have been synchronised)
+[561]
+.IP \(bu 4
+Mac OS X (or Darwin) should now be able to build Perl even on HFS+
+filesystems.  (The case-insensitivity used to confuse the Perl build
+process.)
+.IP \(bu 4
+NCR MP-RAS is now supported. [561]
+.IP \(bu 4
+All the NetBSD specific patches (except for the installation
+specific ones) have been merged back to the main distribution.
+.IP \(bu 4
+NetWare from Novell is now supported.  See perlnetware.
+.IP \(bu 4
+NonStop-UX is now supported. [561]
+.IP \(bu 4
+NEC SUPER-UX is now supported.
+.IP \(bu 4
+All the OpenBSD specific patches (except for the installation
+specific ones) have been merged back to the main distribution.
+.IP \(bu 4
+Perl has been tested with the GNU pth userlevel thread package
+( http://www.gnu.org/software/pth/pth.html ).  All thread tests
+of Perl now work, but not without adding some \fByield()\fRs to the tests,
+so while pth (and other userlevel thread implementations) can be
+considered to be "working" with Perl ithreads, keep in mind the
+possible non-preemptability of the underlying thread implementation.
+.IP \(bu 4
+Stratus VOS is now supported using Perl's native build method
+(Configure).  This is the recommended method to build Perl on
+VOS.  The older methods, which build miniperl, are still
+available.  See perlvos. [561+]
+.IP \(bu 4
+The Amdahl UTS Unix mainframe platform is now supported. [561]
+.IP \(bu 4
+WinCE is now supported.  See perlce.
+.IP \(bu 4
+z/OS (formerly known as OS/390, formerly known as MVS OE) now has
+support for dynamic loading.  This is not selected by default,
+however, you must specify \-Dusedl in the arguments of Configure. [561]
+.SH "Selected Bug Fixes"
+.IX Header "Selected Bug Fixes"
+Numerous memory leaks and uninitialized memory accesses have been
+hunted down.  Most importantly, anonymous subs used to leak quite
+a bit. [561]
+.IP \(bu 4
+The autouse pragma didn't work for Multi::Part::Function::Names.
+.IP \(bu 4
+\&\fBcaller()\fR could cause core dumps in certain situations.  Carp was
+sometimes affected by this problem.  In particular, \fBcaller()\fR now
+returns a subroutine name of \f(CW\*(C`(unknown)\*(C'\fR for subroutines that have
+been removed from the symbol table.
+.IP \(bu 4
+chop(@list) in list context returned the characters chopped in
+reverse order.  This has been reversed to be in the right order. [561]
+.IP \(bu 4
+Configure no longer includes the DBM libraries (dbm, gdbm, db, ndbm)
+when building the Perl binary.  The only exception to this is SunOS 4.x,
+which needs them. [561]
+.IP \(bu 4
+The behaviour of non-decimal but numeric string constants such as
+"0x23" was platform-dependent: in some platforms that was seen as 35,
+in some as 0, in some as a floating point number (don't ask).  This
+was caused by Perl's using the operating system libraries in a situation
+where the result of the string to number conversion is undefined: now
+Perl consistently handles such strings as zero in numeric contexts.
+.IP \(bu 4
+Several debugger fixes: exit code now reflects the script exit code,
+condition \f(CW"0"\fR now treated correctly, the \f(CW\*(C`d\*(C'\fR command now checks
+line number, \f(CW$.\fR no longer gets corrupted, and all debugger output
+now goes correctly to the socket if RemotePort is set. [561]
+.IP \(bu 4
+The debugger (perl5db.pl) has been modified to present a more
+consistent commands interface, via (CommandSet=580).  perl5db.t was
+also added to test the changes, and as a placeholder for further tests.
+.Sp
+See perldebug.
+.IP \(bu 4
+The debugger has a new \f(CW\*(C`dumpDepth\*(C'\fR option to control the maximum
+depth to which nested structures are dumped.  The \f(CW\*(C`x\*(C'\fR command has
+been extended so that \f(CW\*(C`x N EXPR\*(C'\fR dumps out the value of \fIEXPR\fR to a
+depth of at most \fIN\fR levels.
+.IP \(bu 4
+The debugger can now show lexical variables if you have the CPAN
+module PadWalker installed.
+.IP \(bu 4
+The order of DESTROYs has been made more predictable.
+.IP \(bu 4
+Perl 5.6.0 could emit spurious warnings about redefinition of
+\&\fBdl_error()\fR when statically building extensions into perl.
+This has been corrected. [561]
+.IP \(bu 4
+dprofpp \-R didn't work.
+.IP \(bu 4
+\&\f(CW*foo{FORMAT}\fR now works.
+.IP \(bu 4
+Infinity is now recognized as a number.
+.IP \(bu 4
+UNIVERSAL::isa no longer caches methods incorrectly.  (This broke
+the Tk extension with 5.6.0.) [561]
+.IP \(bu 4
+Lexicals I: lexicals outside an eval "" weren't resolved
+correctly inside a subroutine definition inside the eval "" if they
+were not already referenced in the top level of the eval""ed code.
+.IP \(bu 4
+Lexicals II: lexicals leaked at file scope into subroutines that
+were declared before the lexicals.
+.IP \(bu 4
+Lexical warnings now propagating correctly between scopes
+and into \f(CW\*(C`eval "..."\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`use warnings qw(FATAL all)\*(C'\fR did not work as intended.  This has been
+corrected. [561]
+.IP \(bu 4
+\&\fBwarnings::enabled()\fR now reports the state of $^W correctly if the caller
+isn't using lexical warnings. [561]
+.IP \(bu 4
+Line renumbering with eval and \f(CW\*(C`#line\*(C'\fR now works. [561]
+.IP \(bu 4
+Fixed numerous memory leaks, especially in eval "".
+.IP \(bu 4
+Localised tied variables no longer leak memory
+.Sp
+.Vb 2
+\&    use Tie::Hash;
+\&    tie my %tied_hash => \*(AqTie::StdHash\*(Aq;
+\&
+\&    ...
+\&
+\&    # Used to leak memory every time local() was called;
+\&    # in a loop, this added up.
+\&    local($tied_hash{Foo}) = 1;
+.Ve
+.IP \(bu 4
+Localised hash elements (and \f(CW%ENV\fR) are correctly unlocalised to not
+exist, if they didn't before they were localised.
+.Sp
+.Vb 2
+\&    use Tie::Hash;
+\&    tie my %tied_hash => \*(AqTie::StdHash\*(Aq;
+\&
+\&    ...
+\&
+\&    # Nothing has set the FOO element so far
+\&
+\&    { local $tied_hash{FOO} = \*(AqBar\*(Aq }
+\&
+\&    # This used to print, but not now.
+\&    print "exists!\en" if exists $tied_hash{FOO};
+.Ve
+.Sp
+As a side effect of this fix, tied hash interfaces \fBmust\fR define
+the EXISTS and DELETE methods.
+.IP \(bu 4
+\&\fBmkdir()\fR now ignores trailing slashes in the directory name,
+as mandated by POSIX.
+.IP \(bu 4
+Some versions of glibc have a broken \fBmodfl()\fR.  This affects builds
+with \f(CW\*(C`\-Duselongdouble\*(C'\fR.  This version of Perl detects this brokenness
+and has a workaround for it.  The glibc release 2.2.2 is known to have
+fixed the \fBmodfl()\fR bug.
+.IP \(bu 4
+Modulus of unsigned numbers now works (4063328477 % 65535 used to
+return 27406, instead of 27047). [561]
+.IP \(bu 4
+Some "not a number" warnings introduced in 5.6.0 eliminated to be
+more compatible with 5.005.  Infinity is now recognised as a number. [561]
+.IP \(bu 4
+Numeric conversions did not recognize changes in the string value
+properly in certain circumstances. [561]
+.IP \(bu 4
+Attributes (such as :shared) didn't work with \fBour()\fR.
+.IP \(bu 4
+\&\fBour()\fR variables will not cause bogus "Variable will not stay shared"
+warnings. [561]
+.IP \(bu 4
+"our" variables of the same name declared in two sibling blocks
+resulted in bogus warnings about "redeclaration" of the variables.
+The problem has been corrected. [561]
+.IP \(bu 4
+pack "Z" now correctly terminates the string with "\e0".
+.IP \(bu 4
+Fix password routines which in some shadow password platforms
+(e.g. HP-UX) caused \fBgetpwent()\fR to return every other entry.
+.IP \(bu 4
+The PERL5OPT environment variable (for passing command line arguments
+to Perl) didn't work for more than a single group of options. [561]
+.IP \(bu 4
+PERL5OPT with embedded spaces didn't work.
+.IP \(bu 4
+\&\fBprintf()\fR no longer resets the numeric locale to "C".
+.IP \(bu 4
+\&\f(CWqw(a\e\eb)\fR now parses correctly as \f(CW\*(Aqa\e\eb\*(Aq\fR: that is, as three
+characters, not four. [561]
+.IP \(bu 4
+\&\fBpos()\fR did not return the correct value within s///ge in earlier
+versions.  This is now handled correctly. [561]
+.IP \(bu 4
+Printing quads (64\-bit integers) with printf/sprintf now works
+without the q L ll prefixes (assuming you are on a quad-capable platform).
+.IP \(bu 4
+Regular expressions on references and overloaded scalars now work. [561+]
+.IP \(bu 4
+Right-hand side magic (GMAGIC) could in many cases such as string
+concatenation be invoked too many times.
+.IP \(bu 4
+\&\fBscalar()\fR now forces scalar context even when used in void context.
+.IP \(bu 4
+SOCKS support is now much more robust.
+.IP \(bu 4
+\&\fBsort()\fR arguments are now compiled in the right wantarray context
+(they were accidentally using the context of the \fBsort()\fR itself).
+The comparison block is now run in scalar context, and the arguments
+to be sorted are always provided list context. [561]
+.IP \(bu 4
+Changed the POSIX character class \f(CW\*(C`[[:space:]]\*(C'\fR to include the (very
+rarely used) vertical tab character.  Added a new POSIX-ish character
+class \f(CW\*(C`[[:blank:]]\*(C'\fR which stands for horizontal whitespace
+(currently, the space and the tab).
+.IP \(bu 4
+The tainting behaviour of \fBsprintf()\fR has been rationalized.  It does
+not taint the result of floating point formats anymore, making the
+behaviour consistent with that of string interpolation. [561]
+.IP \(bu 4
+Some cases of inconsistent taint propagation (such as within hash
+values) have been fixed.
+.IP \(bu 4
+The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds
+of simple pattern matches.  These are now handled better. [561]
+.IP \(bu 4
+Regular expression debug output (whether through \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR
+or via \f(CW\*(C`\-Dr\*(C'\fR) now looks better. [561]
+.IP \(bu 4
+Multi-line matches like \f(CW\*(C`"a\enxb\en" =~ /(?!\eA)x/m\*(C'\fR were flawed.  The
+bug has been fixed. [561]
+.IP \(bu 4
+Use of $& could trigger a core dump under some situations.  This
+is now avoided. [561]
+.IP \(bu 4
+The regular expression captured submatches ($1, \f(CW$2\fR, ...) are now
+more consistently unset if the match fails, instead of leaving false
+data lying around in them. [561]
+.IP \(bu 4
+\&\fBreadline()\fR on files opened in "slurp" mode could return an extra
+"" (blank line) at the end in certain situations.  This has been
+corrected. [561]
+.IP \(bu 4
+Autovivification of symbolic references of special variables described
+in perlvar (as in \f(CW\*(C`${$num}\*(C'\fR) was accidentally disabled.  This works
+again now. [561]
+.IP \(bu 4
+Sys::Syslog ignored the \f(CW\*(C`LOG_AUTH\*(C'\fR constant.
+.IP \(bu 4
+\&\f(CW$AUTOLOAD\fR, \fBsort()\fR, \fBlock()\fR, and spawning subprocesses
+in multiple threads simultaneously are now thread-safe.
+.IP \(bu 4
+Tie::Array's SPLICE method was broken.
+.IP \(bu 4
+Allow a read-only string on the left-hand side of a non-modifying tr///.
+.IP \(bu 4
+If \f(CW\*(C`STDERR\*(C'\fR is tied, warnings caused by \f(CW\*(C`warn\*(C'\fR and \f(CW\*(C`die\*(C'\fR now
+correctly pass to it.
+.IP \(bu 4
+Several Unicode fixes.
+.RS 4
+.IP \(bu 8
+BOMs (byte order marks) at the beginning of Perl files
+(scripts, modules) should now be transparently skipped.
+UTF\-16 and UCS\-2 encoded Perl files should now be read correctly.
+.IP \(bu 8
+The character tables have been updated to Unicode 3.2.0.
+.IP \(bu 8
+Comparing with utf8 data does not magically upgrade non\-utf8 data
+into utf8.  (This was a problem for example if you were mixing data
+from I/O and Unicode data: your output might have got magically encoded
+as UTF\-8.)
+.IP \(bu 8
+Generating illegal Unicode code points such as U+FFFE, or the UTF\-16
+surrogates, now also generates an optional warning.
+.IP \(bu 8
+\&\f(CW\*(C`IsAlnum\*(C'\fR, \f(CW\*(C`IsAlpha\*(C'\fR, and \f(CW\*(C`IsWord\*(C'\fR now match titlecase.
+.IP \(bu 8
+Concatenation with the \f(CW\*(C`.\*(C'\fR operator or via variable interpolation,
+\&\f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, \f(CW\*(C`quotemeta\*(C'\fR, the \f(CW\*(C`x\*(C'\fR operator,
+substitution with \f(CW\*(C`s///\*(C'\fR, single-quoted UTF\-8, should now work.
+.IP \(bu 8
+The \f(CW\*(C`tr///\*(C'\fR operator now works.  Note that the \f(CW\*(C`tr///CU\*(C'\fR
+functionality has been removed (but see pack('U0', ...)).
+.IP \(bu 8
+\&\f(CW\*(C`eval "v200"\*(C'\fR now works.
+.IP \(bu 8
+Perl 5.6.0 parsed m/\ex{ab}/ incorrectly, leading to spurious warnings.
+This has been corrected. [561]
+.IP \(bu 8
+Zero entries were missing from the Unicode classes such as \f(CW\*(C`IsDigit\*(C'\fR.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Large unsigned numbers (those above 2**31) could sometimes lose their
+unsignedness, causing bogus results in arithmetic operations. [561]
+.IP \(bu 4
+The Perl parser has been stress tested using both random input and
+Markov chain input and the few found crashes and lockups have been
+fixed.
+.SS "Platform Specific Changes and Fixes"
+.IX Subsection "Platform Specific Changes and Fixes"
+.IP \(bu 4
+BSDI 4.*
+.Sp
+Perl now works on post\-4.0 BSD/OSes.
+.IP \(bu 4
+All BSDs
+.Sp
+Setting \f(CW$0\fR now works (as much as possible; see perlvar for details).
+.IP \(bu 4
+Cygwin
+.Sp
+Numerous updates; currently synchronised with Cygwin 1.3.10.
+.IP \(bu 4
+Previously DYNIX/ptx had problems in its Configure probe for non-blocking I/O.
+.IP \(bu 4
+EPOC
+.Sp
+EPOC now better supported.  See README.epoc. [561]
+.IP \(bu 4
+FreeBSD 3.*
+.Sp
+Perl now works on post\-3.0 FreeBSDs.
+.IP \(bu 4
+HP-UX
+.Sp
+README.hpux updated; \f(CW\*(C`Configure \-Duse64bitall\*(C'\fR now works;
+now uses HP-UX malloc instead of Perl malloc.
+.IP \(bu 4
+IRIX
+.Sp
+Numerous compilation flag and hint enhancements; accidental mixing
+of 32\-bit and 64\-bit libraries (a doomed attempt) made much harder.
+.IP \(bu 4
+Linux
+.RS 4
+.IP \(bu 8
+Long doubles should now work (see INSTALL). [561]
+.IP \(bu 8
+Linux previously had problems related to sockaddrlen when using
+\&\fBaccept()\fR, \fBrecvfrom()\fR (in Perl: \fBrecv()\fR), \fBgetpeername()\fR, and
+\&\fBgetsockname()\fR.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Mac OS Classic
+.Sp
+Compilation of the standard Perl distribution in Mac OS Classic should
+now work if you have the Metrowerks development environment and the
+missing Mac-specific toolkit bits.  Contact the macperl mailing list
+for details.
+.IP \(bu 4
+MPE/iX
+.Sp
+MPE/iX update after Perl 5.6.0.  See README.mpeix. [561]
+.IP \(bu 4
+NetBSD/threads: try installing the GNU pth (should be in the
+packages collection, or http://www.gnu.org/software/pth/),
+and Configure with \-Duseithreads.
+.IP \(bu 4
+NetBSD/sparc
+.Sp
+Perl now works on NetBSD/sparc.
+.IP \(bu 4
+OS/2
+.Sp
+Now works with usethreads (see INSTALL). [561]
+.IP \(bu 4
+Solaris
+.Sp
+64\-bitness using the Sun Workshop compiler now works.
+.IP \(bu 4
+Stratus VOS
+.Sp
+The native build method requires at least VOS Release 14.5.0
+and GNU C++/GNU Tools 2.0.1 or later.  The Perl pack function
+now maps overflowed values to +infinity and underflowed values
+to \-infinity.
+.IP \(bu 4
+Tru64 (aka Digital UNIX, aka DEC OSF/1)
+.Sp
+The operating system version letter now recorded in \f(CW$Config\fR{osvers}.
+Allow compiling with gcc (previously explicitly forbidden).  Compiling
+with gcc still not recommended because buggy code results, even with
+gcc 2.95.2.
+.IP \(bu 4
+Unicos
+.Sp
+Fixed various alignment problems that lead into core dumps either
+during build or later; no longer dies on math errors at runtime;
+now using full quad integers (64 bits), previously was using
+only 46 bit integers for speed.
+.IP \(bu 4
+VMS
+.Sp
+See "Socket Extension Dynamic in VMS" and "IEEE-format Floating Point
+Default on OpenVMS Alpha" for important changes not otherwise listed here.
+.Sp
+\&\fBchdir()\fR now works better despite a CRT bug; now works with MULTIPLICITY
+(see INSTALL); now works with Perl's malloc.
+.Sp
+The tainting of \f(CW%ENV\fR elements via \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`values\*(C'\fR was previously
+unimplemented.  It now works as documented.
+.Sp
+The \f(CW\*(C`waitpid\*(C'\fR emulation has been improved.  The worst bug (now fixed)
+was that a pid of \-1 would cause a wildcard search of all processes on
+the system.
+.Sp
+POSIX-style signals are now emulated much better on VMS versions prior
+to 7.0.
+.Sp
+The \f(CW\*(C`system\*(C'\fR function and backticks operator have improved
+functionality and better error handling. [561]
+.Sp
+File access tests now use current process privileges rather than the
+user's default privileges, which could sometimes result in a mismatch
+between reported access and actual access.  This improvement is only
+available on VMS v6.0 and later.
+.Sp
+There is a new \f(CW\*(C`kill\*(C'\fR implementation based on \f(CW\*(C`sys$sigprc\*(C'\fR that allows
+older VMS systems (pre\-7.0) to use \f(CW\*(C`kill\*(C'\fR to send signals rather than
+simply force exit.  This implementation also allows later systems to
+call \f(CW\*(C`kill\*(C'\fR from within a signal handler.
+.Sp
+Iterative logical name translations are now limited to 10 iterations in
+imitation of SHOW LOGICAL and other OpenVMS facilities.
+.IP \(bu 4
+Windows
+.RS 4
+.IP \(bu 8
+Signal handling now works better than it used to.  It is now implemented
+using a Windows message loop, and is therefore less prone to random
+crashes.
+.IP \(bu 8
+\&\fBfork()\fR emulation is now more robust, but still continues to have a few
+esoteric bugs and caveats.  See perlfork for details. [561+]
+.IP \(bu 8
+A failed (pseudo)fork now returns undef and sets errno to EAGAIN. [561]
+.IP \(bu 8
+The following modules now work on Windows:
+.Sp
+.Vb 4
+\&    ExtUtils::Embed         [561]
+\&    IO::Pipe
+\&    IO::Poll
+\&    Net::Ping
+.Ve
+.IP \(bu 8
+\&\fBIO::File::new_tmpfile()\fR is no longer limited to 32767 invocations
+per-process.
+.IP \(bu 8
+Better \fBchdir()\fR return value for a non-existent directory.
+.IP \(bu 8
+Compiling perl using the 64\-bit Platform SDK tools is now supported.
+.IP \(bu 8
+The \fBWin32::SetChildShowWindow()\fR builtin can be used to control the
+visibility of windows created by child processes.  See Win32 for
+details.
+.IP \(bu 8
+Non-blocking waits for child processes (or pseudo-processes) are
+supported via \f(CW\*(C`waitpid($pid, &POSIX::WNOHANG)\*(C'\fR.
+.IP \(bu 8
+The behavior of \fBsystem()\fR with multiple arguments has been rationalized.
+Each unquoted argument will be automatically quoted to protect whitespace,
+and any existing whitespace in the arguments will be preserved.  This
+improves the portability of system(@args) by avoiding the need for
+Windows \f(CW\*(C`cmd\*(C'\fR shell specific quoting in perl programs.
+.Sp
+Note that this means that some scripts that may have relied on earlier
+buggy behavior may no longer work correctly.  For example,
+\&\f(CW\*(C`system("nmake /nologo", @args)\*(C'\fR will now attempt to run the file
+\&\f(CW\*(C`nmake /nologo\*(C'\fR and will fail when such a file isn't found.
+On the other hand, perl will now execute code such as
+\&\f(CW\*(C`system("c:/Program Files/MyApp/foo.exe", @args)\*(C'\fR correctly.
+.IP \(bu 8
+The perl header files no longer suppress common warnings from the
+Microsoft Visual C++ compiler.  This means that additional warnings may
+now show up when compiling XS code.
+.IP \(bu 8
+Borland C++ v5.5 is now a supported compiler that can build Perl.
+However, the generated binaries continue to be incompatible with those
+generated by the other supported compilers (GCC and Visual C++). [561]
+.IP \(bu 8
+Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.
+[561]
+.IP \(bu 8
+Current directory entries in \f(CW%ENV\fR are now correctly propagated to child
+processes. [561]
+.IP \(bu 8
+New \f(CW%ENV\fR entries now propagate to subprocesses. [561]
+.IP \(bu 8
+\&\fBWin32::GetCwd()\fR correctly returns C:\e instead of C: when at the drive root.
+Other bugs in \fBchdir()\fR and \fBCwd::cwd()\fR have also been fixed. [561]
+.IP \(bu 8
+The makefiles now default to the features enabled in ActiveState ActivePerl
+(a popular Win32 binary distribution). [561]
+.IP \(bu 8
+HTML files will now be installed in c:\eperl\ehtml instead of
+c:\eperl\elib\epod\ehtml
+.IP \(bu 8
+REG_EXPAND_SZ keys are now allowed in registry settings used by perl. [561]
+.IP \(bu 8
+Can now \fBsend()\fR from all threads, not just the first one. [561]
+.IP \(bu 8
+ExtUtils::MakeMaker now uses \f(CW$ENV\fR{LIB} to search for libraries. [561]
+.IP \(bu 8
+Less stack reserved per thread so that more threads can run
+concurrently. (Still 16M per thread.) [561]
+.IP \(bu 8
+\&\f(CW\*(C`File::Spec\->tmpdir()\*(C'\fR now prefers C:/temp over /tmp
+(works better when perl is running as service).
+.IP \(bu 8
+Better UNC path handling under ithreads. [561]
+.IP \(bu 8
+\&\fBwait()\fR, \fBwaitpid()\fR, and backticks now return the correct exit status
+under Windows 9x. [561]
+.IP \(bu 8
+A socket handle leak in \fBaccept()\fR has been fixed. [561]
+.RE
+.RS 4
+.RE
+.SH "New or Changed Diagnostics"
+.IX Header "New or Changed Diagnostics"
+Please see perldiag for more details.
+.IP \(bu 4
+Ambiguous range in the transliteration operator (like a\-z\-9) now
+gives a warning.
+.IP \(bu 4
+chdir("") and chdir(undef) now give a deprecation warning because they
+cause a possible unintentional chdir to the home directory.
+Say \fBchdir()\fR if you really mean that.
+.IP \(bu 4
+Two new debugging options have been added: if you have compiled your
+Perl with debugging, you can use the \-DT [561] and \-DR options to trace
+tokenising and to add reference counts to displaying variables,
+respectively.
+.IP \(bu 4
+The lexical warnings category "deprecated" is no longer a sub-category
+of the "syntax" category. It is now a top-level category in its own
+right.
+.IP \(bu 4
+Unadorned \fBdump()\fR will now give a warning suggesting to
+use explicit \fBCORE::dump()\fR if that's what really is meant.
+.IP \(bu 4
+The "Unrecognized escape" warning has been extended to include \f(CW\*(C`\e8\*(C'\fR,
+\&\f(CW\*(C`\e9\*(C'\fR, and \f(CW\*(C`\e_\*(C'\fR.  There is no need to escape any of the \f(CW\*(C`\ew\*(C'\fR characters.
+.IP \(bu 4
+All regular expression compilation error messages are now hopefully
+easier to understand both because the error message now comes before
+the failed regex and because the point of failure is now clearly
+marked by a \f(CW\*(C`<\-\- HERE\*(C'\fR marker.
+.IP \(bu 4
+Various I/O (and socket) functions like \fBbinmode()\fR, \fBclose()\fR, and so
+forth now more consistently warn if they are used illogically either
+on a yet unopened or on an already closed filehandle (or socket).
+.IP \(bu 4
+Using \fBlstat()\fR on a filehandle now gives a warning.  (It's a non-sensical
+thing to do.)
+.IP \(bu 4
+The \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-m\*(C'\fR options now warn if you didn't supply the module name.
+.IP \(bu 4
+If you in \f(CW\*(C`use\*(C'\fR specify a required minimum version, modules matching
+the name and but not defining a \f(CW$VERSION\fR will cause a fatal failure.
+.IP \(bu 4
+Using negative offset for \fBvec()\fR in lvalue context is now a warnable offense.
+.IP \(bu 4
+Odd number of arguments to overload::constant now elicits a warning.
+.IP \(bu 4
+Odd number of elements in anonymous hash now elicits a warning.
+.IP \(bu 4
+The various "opened only for", "on closed", "never opened" warnings
+drop the \f(CW\*(C`main::\*(C'\fR prefix for filehandles in the \f(CW\*(C`main\*(C'\fR package,
+for example \f(CW\*(C`STDIN\*(C'\fR instead of \f(CW\*(C`main::STDIN\*(C'\fR.
+.IP \(bu 4
+Subroutine prototypes are now checked more carefully, you may
+get warnings for example if you have used non-prototype characters.
+.IP \(bu 4
+If an attempt to use a (non-blessed) reference as an array index
+is made, a warning is given.
+.IP \(bu 4
+\&\f(CW\*(C`push @a;\*(C'\fR and \f(CW\*(C`unshift @a;\*(C'\fR (with no values to push or unshift)
+now give a warning.  This may be a problem for generated and eval'ed
+code.
+.IP \(bu 4
+If you try to "pack" in perlfunc a number less than 0 or larger than 255
+using the \f(CW"C"\fR format you will get an optional warning.  Similarly
+for the \f(CW"c"\fR format and a number less than \-128 or more than 127.
+.IP \(bu 4
+pack \f(CW\*(C`P\*(C'\fR format now demands an explicit size.
+.IP \(bu 4
+unpack \f(CW\*(C`w\*(C'\fR now warns of unterminated compressed integers.
+.IP \(bu 4
+Warnings relating to the use of PerlIO have been added.
+.IP \(bu 4
+Certain regex modifiers such as \f(CW\*(C`(?o)\*(C'\fR make sense only if applied to
+the entire regex.  You will get an optional warning if you try to do
+otherwise.
+.IP \(bu 4
+Variable length lookbehind has not yet been implemented, trying to
+use it will tell that.
+.IP \(bu 4
+Using arrays or hashes as references (e.g. \f(CW\*(C`%foo\->{bar}\*(C'\fR
+has been deprecated for a while.  Now you will get an optional warning.
+.IP \(bu 4
+Warnings relating to the use of the new restricted hashes feature
+have been added.
+.IP \(bu 4
+Self-ties of arrays and hashes are not supported and fatal errors
+will happen even at an attempt to do so.
+.IP \(bu 4
+Using \f(CW\*(C`sort\*(C'\fR in scalar context now issues an optional warning.
+This didn't do anything useful, as the sort was not performed.
+.IP \(bu 4
+Using the /g modifier in \fBsplit()\fR is meaningless and will cause a warning.
+.IP \(bu 4
+Using \fBsplice()\fR past the end of an array now causes a warning.
+.IP \(bu 4
+Malformed Unicode encodings (UTF\-8 and UTF\-16) cause a lot of warnings,
+as does trying to use UTF\-16 surrogates (which are unimplemented).
+.IP \(bu 4
+Trying to use Unicode characters on an I/O stream without marking the
+stream's encoding (using \fBopen()\fR or \fBbinmode()\fR) will cause "Wide character"
+warnings.
+.IP \(bu 4
+Use of v\-strings in use/require causes a (backward) portability warning.
+.IP \(bu 4
+Warnings relating to the use interpreter threads and their shared data
+have been added.
+.SH "Changed Internals"
+.IX Header "Changed Internals"
+.IP \(bu 4
+PerlIO is now the default.
+.IP \(bu 4
+perlapi.pod (a companion to perlguts) now attempts to document the
+internal API.
+.IP \(bu 4
+You can now build a really minimal perl called microperl.
+Building microperl does not require even running Configure;
+\&\f(CW\*(C`make \-f Makefile.micro\*(C'\fR should be enough.  Beware: microperl makes
+many assumptions, some of which may be too bold; the resulting
+executable may crash or otherwise misbehave in wondrous ways.
+For careful hackers only.
+.IP \(bu 4
+Added \fBrsignal()\fR, \fBwhichsig()\fR, \fBdo_join()\fR, op_clear, op_null,
+\&\fBptr_table_clear()\fR, \fBptr_table_free()\fR, \fBsv_setref_uv()\fR, and several UTF\-8
+interfaces to the publicised API.  For the full list of the available
+APIs see perlapi.
+.IP \(bu 4
+Made possible to propagate customised exceptions via \fBcroak()\fRing.
+.IP \(bu 4
+Now xsubs can have attributes just like subs.  (Well, at least the
+built-in attributes.)
+.IP \(bu 4
+dTHR and djSP have been obsoleted; the former removed (because it's
+a no-op) and the latter replaced with dSP.
+.IP \(bu 4
+PERL_OBJECT has been completely removed.
+.IP \(bu 4
+The MAGIC constants (e.g. \f(CW\*(AqP\*(Aq\fR) have been macrofied
+(e.g. \f(CW\*(C`PERL_MAGIC_TIED\*(C'\fR) for better source code readability
+and maintainability.
+.IP \(bu 4
+The regex compiler now maintains a structure that identifies nodes in
+the compiled bytecode with the corresponding syntactic features of the
+original regex expression.  The information is attached to the new
+\&\f(CW\*(C`offsets\*(C'\fR member of the \f(CW\*(C`struct regexp\*(C'\fR. See perldebguts for more
+complete information.
+.IP \(bu 4
+The C code has been made much more \f(CW\*(C`gcc \-Wall\*(C'\fR clean.  Some warning
+messages still remain in some platforms, so if you are compiling with
+gcc you may see some warnings about dubious practices.  The warnings
+are being worked on.
+.IP \(bu 4
+\&\fIperly.c\fR, \fIsv.c\fR, and \fIsv.h\fR have now been extensively commented.
+.IP \(bu 4
+Documentation on how to use the Perl source repository has been added
+to \fIPorting/repository.pod\fR.
+.IP \(bu 4
+There are now several profiling make targets.
+.SH "Security Vulnerability Closed [561]"
+.IX Header "Security Vulnerability Closed [561]"
+(This change was already made in 5.7.0 but bears repeating here.)
+(5.7.0 came out before 5.6.1: the development branch 5.7 released
+earlier than the maintenance branch 5.6)
+.PP
+A potential security vulnerability in the optional suidperl component
+of Perl was identified in August 2000.  suidperl is neither built nor
+installed by default.  As of November 2001 the only known vulnerable
+platform is Linux, most likely all Linux distributions.  CERT and
+various vendors and distributors have been alerted about the vulnerability.
+See http://www.cpan.org/src/5.0/sperl\-2000\-08\-05/sperl\-2000\-08\-05.txt
+for more information.
+.PP
+The problem was caused by Perl trying to report a suspected security
+exploit attempt using an external program, /bin/mail.  On Linux
+platforms the /bin/mail program had an undocumented feature which
+when combined with suidperl gave access to a root shell, resulting in
+a serious compromise instead of reporting the exploit attempt.  If you
+don't have /bin/mail, or if you have 'safe setuid scripts', or if
+suidperl is not installed, you are safe.
+.PP
+The exploit attempt reporting feature has been completely removed from
+Perl 5.8.0 (and the maintenance release 5.6.1, and it was removed also
+from all the Perl 5.7 releases), so that particular vulnerability
+isn't there anymore.  However, further security vulnerabilities are,
+unfortunately, always possible.  The suidperl functionality is most
+probably going to be removed in Perl 5.10.  In any case, suidperl
+should only be used by security experts who know exactly what they are
+doing and why they are using suidperl instead of some other solution
+such as sudo ( see http://www.courtesan.com/sudo/ ).
+.SH "New Tests"
+.IX Header "New Tests"
+Several new tests have been added, especially for the \fIlib\fR and
+\&\fIext\fR subsections.  There are now about 69 000 individual tests
+(spread over about 700 test scripts), in the regression suite (5.6.1
+has about 11 700 tests, in 258 test scripts)  The exact numbers depend
+on the platform and Perl configuration used.  Many of the new tests
+are of course introduced by the new modules, but still in general Perl
+is now more thoroughly tested.
+.PP
+Because of the large number of tests, running the regression suite
+will take considerably longer time than it used to: expect the suite
+to take up to 4\-5 times longer to run than in perl 5.6.  On a really
+fast machine you can hope to finish the suite in about 6\-8 minutes
+(wallclock time).
+.PP
+The tests are now reported in a different order than in earlier Perls.
+(This happens because the test scripts from under t/lib have been moved
+to be closer to the library/extension they are testing.)
+.SH "Known Problems"
+.IX Header "Known Problems"
+.SS "The Compiler Suite Is Still Very Experimental"
+.IX Subsection "The Compiler Suite Is Still Very Experimental"
+The compiler suite is slowly getting better but it continues to be
+highly experimental.  Use in production environments is discouraged.
+.SS "Localising Tied Arrays and Hashes Is Broken"
+.IX Subsection "Localising Tied Arrays and Hashes Is Broken"
+.Vb 1
+\&    local %tied_array;
+.Ve
+.PP
+doesn't work as one would expect: the old value is restored
+incorrectly.  This will be changed in a future release, but we don't
+know yet what the new semantics will exactly be.  In any case, the
+change will break existing code that relies on the current
+(ill-defined) semantics, so just avoid doing this in general.
+.SS "Building Extensions Can Fail Because Of Largefiles"
+.IX Subsection "Building Extensions Can Fail Because Of Largefiles"
+Some extensions like mod_perl are known to have issues with
+`largefiles', a change brought by Perl 5.6.0 in which file offsets
+default to 64 bits wide, where supported.  Modules may fail to compile
+at all, or they may compile and work incorrectly.  Currently, there
+is no good solution for the problem, but Configure now provides
+appropriate non-largefile ccflags, ldflags, libswanted, and libs
+in the \f(CW%Config\fR hash (e.g., \f(CW$Config\fR{ccflags_nolargefiles}) so the
+extensions that are having problems can try configuring themselves
+without the largefileness.  This is admittedly not a clean solution,
+and the solution may not even work at all.  One potential failure is
+whether one can (or, if one can, whether it's a good idea to) link
+together at all binaries with different ideas about file offsets;
+all this is platform-dependent.
+.ie n .SS "Modifying $_ Inside for(..)"
+.el .SS "Modifying \f(CW$_\fP Inside for(..)"
+.IX Subsection "Modifying $_ Inside for(..)"
+.Vb 1
+\&   for (1..5) { $_++ }
+.Ve
+.PP
+works without complaint.  It shouldn't.  (You should be able to
+modify only lvalue elements inside the loops.)  You can see the
+correct behaviour by replacing the 1..5 with 1, 2, 3, 4, 5.
+.SS "mod_perl 1.26 Doesn't Build With Threaded Perl"
+.IX Subsection "mod_perl 1.26 Doesn't Build With Threaded Perl"
+Use mod_perl 1.27 or higher.
+.SS "lib/ftmp\-security tests warn 'system possibly insecure'"
+.IX Subsection "lib/ftmp-security tests warn 'system possibly insecure'"
+Don't panic.  Read the 'make test' section of INSTALL instead.
+.SS "libwww-perl (LWP) fails base/date #51"
+.IX Subsection "libwww-perl (LWP) fails base/date #51"
+Use libwww-perl 5.65 or later.
+.SS "PDL failing some tests"
+.IX Subsection "PDL failing some tests"
+Use PDL 2.3.4 or later.
+.SS Perl_get_sv
+.IX Subsection "Perl_get_sv"
+You may get errors like 'Undefined symbol "Perl_get_sv"' or "can't
+resolve symbol 'Perl_get_sv'", or the symbol may be "Perl_sv_2pv".
+This probably means that you are trying to use an older shared Perl
+library (or extensions linked with such) with Perl 5.8.0 executable.
+Perl used to have such a subroutine, but that is no more the case.
+Check your shared library path, and any shared Perl libraries in those
+directories.
+.PP
+Sometimes this problem may also indicate a partial Perl 5.8.0
+installation, see "Mac OS X dyld undefined symbols" for an
+example and how to deal with it.
+.SS "Self-tying Problems"
+.IX Subsection "Self-tying Problems"
+Self-tying of arrays and hashes is broken in rather deep and
+hard-to-fix ways.  As a stop-gap measure to avoid people from getting
+frustrated at the mysterious results (core dumps, most often), it is
+forbidden for now (you will get a fatal error even from an attempt).
+.PP
+A change to self-tying of globs has caused them to be recursively
+referenced (see: "Two-Phased Garbage Collection" in perlobj).  You
+will now need an explicit untie to destroy a self-tied glob.  This
+behaviour may be fixed at a later date.
+.PP
+Self-tying of scalars and IO thingies works.
+.SS ext/threads/t/libc
+.IX Subsection "ext/threads/t/libc"
+If this test fails, it indicates that your libc (C library) is not
+threadsafe.  This particular test stress tests the \fBlocaltime()\fR call to
+find out whether it is threadsafe.  See perlthrtut for more information.
+.SS "Failure of Thread (5.005\-style) tests"
+.IX Subsection "Failure of Thread (5.005-style) tests"
+\&\fBNote that support for 5.005\-style threading is deprecated,
+experimental and practically unsupported.  In 5.10, it is expected
+to be removed.  You should migrate your code to ithreads.\fR
+.PP
+The following tests are known to fail due to fundamental problems in
+the 5.005 threading implementation. These are not new failures\-\-Perl
+5.005_0x has the same bugs, but didn't have these tests.
+.PP
+.Vb 10
+\& ../ext/B/t/xref.t                    255 65280    14   12  85.71%  3\-14
+\& ../ext/List/Util/t/first.t           255 65280     7    4  57.14%  2 5\-7
+\& ../lib/English.t                       2   512    54    2   3.70%  2\-3
+\& ../lib/FileCache.t                                 5    1  20.00%  5
+\& ../lib/Filter/Simple/t/data.t                      6    3  50.00%  1\-3
+\& ../lib/Filter/Simple/t/filter_only.                9    3  33.33%  1\-2 5
+\& ../lib/Math/BigInt/t/bare_mbf.t                 1627    4   0.25%  8 11 1626\-1627
+\& ../lib/Math/BigInt/t/bigfltpm.t                 1629    4   0.25%  10 13 1628\-
+\&                                                                    1629
+\& ../lib/Math/BigInt/t/sub_mbf.t                  1633    4   0.24%  8 11 1632\-1633
+\& ../lib/Math/BigInt/t/with_sub.t                 1628    4   0.25%  9 12 1627\-1628
+\& ../lib/Tie/File/t/31_autodefer.t     255 65280    65   32  49.23%  34\-65
+\& ../lib/autouse.t                                  10    1  10.00%  4
+\& op/flip.t                                         15    1   6.67%  15
+.Ve
+.PP
+These failures are unlikely to get fixed as 5.005\-style threads
+are considered fundamentally broken.  (Basically what happens is that
+competing threads can corrupt shared global state, one good example
+being regular expression engine's state.)
+.SS "Timing problems"
+.IX Subsection "Timing problems"
+The following tests may fail intermittently because of timing
+problems, for example if the system is heavily loaded.
+.PP
+.Vb 5
+\&    t/op/alarm.t
+\&    ext/Time/HiRes/HiRes.t
+\&    lib/Benchmark.t
+\&    lib/Memoize/t/expmod_t.t
+\&    lib/Memoize/t/speed.t
+.Ve
+.PP
+In case of failure please try running them manually, for example
+.PP
+.Vb 1
+\&    ./perl \-Ilib ext/Time/HiRes/HiRes.t
+.Ve
+.SS "Tied/Magical Array/Hash Elements Do Not Autovivify"
+.IX Subsection "Tied/Magical Array/Hash Elements Do Not Autovivify"
+For normal arrays \f(CW\*(C`$foo = \e$bar[1]\*(C'\fR will assign \f(CW\*(C`undef\*(C'\fR to
+\&\f(CW$bar[1]\fR (assuming that it didn't exist before), but for
+tied/magical arrays and hashes such autovivification does not happen
+because there is currently no way to catch the reference creation.
+The same problem affects slicing over non-existent indices/keys of
+a tied/magical array/hash.
+.SS "Unicode in package/class and subroutine names does not work"
+.IX Subsection "Unicode in package/class and subroutine names does not work"
+One can have Unicode in identifier names, but not in package/class or
+subroutine names.  While some limited functionality towards this does
+exist as of Perl 5.8.0, that is more accidental than designed; use of
+Unicode for the said purposes is unsupported.
+.PP
+One reason of this unfinishedness is its (currently) inherent
+unportability: since both package names and subroutine names may
+need to be mapped to file and directory names, the Unicode capability
+of the filesystem becomes important\-\- and there unfortunately aren't
+portable answers.
+.SH "Platform Specific Problems"
+.IX Header "Platform Specific Problems"
+.SS AIX
+.IX Subsection "AIX"
+.IP \(bu 4
+If using the AIX native make command, instead of just "make" issue
+"make all".  In some setups the former has been known to spuriously
+also try to run "make install".  Alternatively, you may want to use
+GNU make.
+.IP \(bu 4
+In AIX 4.2, Perl extensions that use C++ functions that use statics
+may have problems in that the statics are not getting initialized.
+In newer AIX releases, this has been solved by linking Perl with
+the libC_r library, but unfortunately in AIX 4.2 the said library
+has an obscure bug where the various functions related to time
+(such as \fBtime()\fR and \fBgettimeofday()\fR) return broken values, and
+therefore in AIX 4.2 Perl is not linked against libC_r.
+.IP \(bu 4
+vac 5.0.0.0 May Produce Buggy Code For Perl
+.Sp
+The AIX C compiler vac version 5.0.0.0 may produce buggy code,
+resulting in a few random tests failing when run as part of "make
+test", but when the failing tests are run by hand, they succeed.
+We suggest upgrading to at least vac version 5.0.1.0, that has been
+known to compile Perl correctly.  "lslpp \-L|grep vac.C" will tell
+you the vac version.  See README.aix.
+.IP \(bu 4
+If building threaded Perl, you may get compilation warning from pp_sys.c:
+.Sp
+.Vb 1
+\&  "pp_sys.c", line 4651.39: 1506\-280 (W) Function argument assignment between types "unsigned char*" and "const void*" is not allowed.
+.Ve
+.Sp
+This is harmless; it is caused by the \fBgetnetbyaddr()\fR and \fBgetnetbyaddr_r()\fR
+having slightly different types for their first argument.
+.SS "Alpha systems with old gccs fail several tests"
+.IX Subsection "Alpha systems with old gccs fail several tests"
+If you see op/pack, op/pat, op/regexp, or ext/Storable tests failing
+in a Linux/alpha or *BSD/Alpha, it's probably time to upgrade your gcc.
+gccs prior to 2.95.3 are definitely not good enough, and gcc 3.1 may
+be even better.  (RedHat Linux/alpha with gcc 3.1 reported no problems,
+as did Linux 2.4.18 with gcc 2.95.4.)  (In Tru64, it is preferable to
+use the bundled C compiler.)
+.SS AmigaOS
+.IX Subsection "AmigaOS"
+Perl 5.8.0 doesn't build in AmigaOS.  It broke at some point during
+the ithreads work and we could not find Amiga experts to unbreak the
+problems.  Perl 5.6.1 still works for AmigaOS (as does the 5.7.2
+development release).
+.SS BeOS
+.IX Subsection "BeOS"
+The following tests fail on 5.8.0 Perl in BeOS Personal 5.03:
+.PP
+.Vb 6
+\& t/op/lfs............................FAILED at test 17
+\& t/op/magic..........................FAILED at test 24
+\& ext/Fcntl/t/syslfs..................FAILED at test 17
+\& ext/File/Glob/t/basic...............FAILED at test 3
+\& ext/POSIX/t/sigaction...............FAILED at test 13
+\& ext/POSIX/t/waitpid.................FAILED at test 1
+.Ve
+.PP
+(\fBNote:\fR more information was available in \fIREADME.beos\fR until support for
+BeOS was removed in Perl v5.18.0)
+.SS "Cygwin ""unable to remap"""
+.IX Subsection "Cygwin ""unable to remap"""
+For example when building the Tk extension for Cygwin,
+you may get an error message saying "unable to remap".
+This is known problem with Cygwin, and a workaround is
+detailed in here: http://sources.redhat.com/ml/cygwin/2001\-12/msg00894.html
+.SS "Cygwin ndbm tests fail on FAT"
+.IX Subsection "Cygwin ndbm tests fail on FAT"
+One can build but not install (or test the build of) the NDBM_File
+on FAT filesystems.  Installation (or build) on NTFS works fine.
+If one attempts the test on a FAT install (or build) the following
+failures are expected:
+.PP
+.Vb 6
+\& ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1\-2 4 16\-71
+\& ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
+\& ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
+\& ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7\-11
+\& ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1\-4
+\& run/fresh_perl.t                          97    1   1.03%  91
+.Ve
+.PP
+NDBM_File fails and ODBM_File just coredumps.
+.PP
+If you intend to run only on FAT (or if using AnyDBM_File on FAT),
+run Configure with the \-Ui_ndbm and \-Ui_dbm options to prevent
+NDBM_File and ODBM_File being built.
+.SS "DJGPP Failures"
+.IX Subsection "DJGPP Failures"
+.Vb 8
+\& t/op/stat............................FAILED at test 29
+\& lib/File/Find/t/find.................FAILED at test 1
+\& lib/File/Find/t/taint................FAILED at test 1
+\& lib/h2xs.............................FAILED at test 15
+\& lib/Pod/t/eol........................FAILED at test 1
+\& lib/Test/Harness/t/strap\-analyze.....FAILED at test 8
+\& lib/Test/Harness/t/test\-harness......FAILED at test 23
+\& lib/Test/Simple/t/exit...............FAILED at test 1
+.Ve
+.PP
+The above failures are known as of 5.8.0 with native builds with long
+filenames, but there are a few more if running under dosemu because of
+limitations (and maybe bugs) of dosemu:
+.PP
+.Vb 2
+\& t/comp/cpp...........................FAILED at test 3
+\& t/op/inccode.........................(crash)
+.Ve
+.PP
+and a few lib/ExtUtils tests, and several hundred Encode/t/Aliases.t
+failures that work fine with long filenames.  So you really might
+prefer native builds and long filenames.
+.SS "FreeBSD built with ithreads coredumps reading large directories"
+.IX Subsection "FreeBSD built with ithreads coredumps reading large directories"
+This is a known bug in FreeBSD 4.5's \fBreaddir_r()\fR, it has been fixed in
+FreeBSD 4.6 (see perlfreebsd (README.freebsd)).
+.SS "FreeBSD Failing locale Test 117 For ISO 8859\-15 Locales"
+.IX Subsection "FreeBSD Failing locale Test 117 For ISO 8859-15 Locales"
+The ISO 8859\-15 locales may fail the locale test 117 in FreeBSD.
+This is caused by the characters \exFF (y with diaeresis) and \exBE
+(Y with diaeresis) not behaving correctly when being matched
+case-insensitively.  Apparently this problem has been fixed in
+the latest FreeBSD releases.
+( http://www.freebsd.org/cgi/query\-pr.cgi?pr=34308 )
+.SS "IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5"
+.IX Subsection "IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5"
+IRIX with MIPSpro 7.3.1.2m or 7.3.1.3m compiler may fail the List::Util
+test ext/List/Util/t/shuffle.t by dumping core.  This seems to be
+a compiler error since if compiled with gcc no core dump ensues, and
+no failures have been seen on the said test on any other platform.
+.PP
+Similarly, building the Digest::MD5 extension has been
+known to fail with "*** Termination code 139 (bu21)".
+.PP
+The cure is to drop optimization level (Configure \-Doptimize=\-O2).
+.SS "HP-UX lib/posix Subtest 9 Fails When LP64\-Configured"
+.IX Subsection "HP-UX lib/posix Subtest 9 Fails When LP64-Configured"
+If perl is configured with \-Duse64bitall, the successful result of the
+subtest 10 of lib/posix may arrive before the successful result of the
+subtest 9, which confuses the test harness so much that it thinks the
+subtest 9 failed.
+.SS "Linux with glibc 2.2.5 fails t/op/int subtest #6 with \-Duse64bitint"
+.IX Subsection "Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint"
+This is a known bug in the glibc 2.2.5 with long long integers.
+( http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=65612 )
+.SS "Linux With Sfio Fails op/misc Test 48"
+.IX Subsection "Linux With Sfio Fails op/misc Test 48"
+No known fix.
+.SS "Mac OS X"
+.IX Subsection "Mac OS X"
+Please remember to set your environment variable LC_ALL to "C"
+(setenv LC_ALL C) before running "make test" to avoid a lot of
+warnings about the broken locales of Mac OS X.
+.PP
+The following tests are known to fail in Mac OS X 10.1.5 because of
+buggy (old) implementations of Berkeley DB included in Mac OS X:
+.PP
+.Vb 4
+\& Failed Test                 Stat Wstat Total Fail  Failed  List of Failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& ../ext/DB_File/t/db\-btree.t    0    11    ??   ??       %  ??
+\& ../ext/DB_File/t/db\-recno.t              149    3   2.01%  61 63 65
+.Ve
+.PP
+If you are building on a UFS partition, you will also probably see
+t/op/stat.t subtest #9 fail.  This is caused by Darwin's UFS not
+supporting inode change time.
+.PP
+Also the ext/POSIX/t/posix.t subtest #10 fails but it is skipped for
+now because the failure is Apple's fault, not Perl's (blocked signals
+are lost).
+.PP
+If you Configure with ithreads, ext/threads/t/libc.t will fail. Again,
+this is not Perl's fault\-\- the libc of Mac OS X is not threadsafe
+(in this particular test, the \fBlocaltime()\fR call is found to be
+threadunsafe.)
+.SS "Mac OS X dyld undefined symbols"
+.IX Subsection "Mac OS X dyld undefined symbols"
+If after installing Perl 5.8.0 you are getting warnings about missing
+symbols, for example
+.PP
+.Vb 3
+\&    dyld: perl Undefined symbols
+\&    _perl_sv_2pv
+\&    _perl_get_sv
+.Ve
+.PP
+you probably have an old pre\-Perl\-5.8.0 installation (or parts of one)
+in /Library/Perl (the undefined symbols used to exist in pre\-5.8.0 Perls).
+It seems that for some reason "make install" doesn't always completely
+overwrite the files in /Library/Perl.  You can move the old Perl
+shared library out of the way like this:
+.PP
+.Vb 2
+\&    cd /Library/Perl/darwin/CORE
+\&    mv libperl.dylib libperlold.dylib
+.Ve
+.PP
+and then reissue "make install".  Note that the above of course is
+extremely disruptive for anything using the /usr/local/bin/perl.
+If that doesn't help, you may have to try removing all the .bundle
+files from beneath /Library/Perl, and again "make install"\-ing.
+.SS "OS/2 Test Failures"
+.IX Subsection "OS/2 Test Failures"
+The following tests are known to fail on OS/2 (for clarity
+only the failures are shown, not the full error messages):
+.PP
+.Vb 6
+\& ../lib/ExtUtils/t/Mkbootstrap.t    1   256    18    1   5.56%  8
+\& ../lib/ExtUtils/t/Packlist.t       1   256    34    1   2.94%  17
+\& ../lib/ExtUtils/t/basic.t          1   256    17    1   5.88%  14
+\& lib/os2_process.t                  2   512   227    2   0.88%  174 209
+\& lib/os2_process_kid.t                        227    2   0.88%  174 209
+\& lib/rx_cmprt.t                   255 65280    18    3  16.67%  16\-18
+.Ve
+.SS "op/sprintf tests 91, 129, and 130"
+.IX Subsection "op/sprintf tests 91, 129, and 130"
+The op/sprintf tests 91, 129, and 130 are known to fail on some platforms.
+Examples include any platform using sfio, and Compaq/Tandem's NonStop-UX.
+.PP
+Test 91 is known to fail on QNX6 (nto), because \f(CW\*(C`sprintf \*(Aq%e\*(Aq,0\*(C'\fR
+incorrectly produces \f(CW0.000000e+0\fR instead of \f(CW0.000000e+00\fR.
+.PP
+For tests 129 and 130, the failing platforms do not comply with
+the ANSI C Standard: lines 19ff on page 134 of ANSI X3.159 1989, to
+be exact.  (They produce something other than "1" and "\-1" when
+formatting 0.6 and \-0.6 using the printf format "%.0f"; most often,
+they produce "0" and "\-0".)
+.SS SCO
+.IX Subsection "SCO"
+The socketpair tests are known to be unhappy in SCO 3.2v5.0.4:
+.PP
+.Vb 1
+\& ext/Socket/socketpair.t...............FAILED tests 15\-45
+.Ve
+.SS "Solaris 2.5"
+.IX Subsection "Solaris 2.5"
+In case you are still using Solaris 2.5 (aka SunOS 5.5), you may
+experience failures (the test core dumping) in lib/locale.t.
+The suggested cure is to upgrade your Solaris.
+.SS "Solaris x86 Fails Tests With \-Duse64bitint"
+.IX Subsection "Solaris x86 Fails Tests With -Duse64bitint"
+The following tests are known to fail in Solaris x86 with Perl
+configured to use 64 bit integers:
+.PP
+.Vb 2
+\& ext/Data/Dumper/t/dumper.............FAILED at test 268
+\& ext/Devel/Peek/Peek..................FAILED at test 7
+.Ve
+.SS "SUPER-UX (NEC SX)"
+.IX Subsection "SUPER-UX (NEC SX)"
+The following tests are known to fail on SUPER-UX:
+.PP
+.Vb 11
+\& op/64bitint...........................FAILED tests 29\-30, 32\-33, 35\-36
+\& op/arith..............................FAILED tests 128\-130
+\& op/pack...............................FAILED tests 25\-5625
+\& op/pow................................
+\& op/taint..............................# msgsnd failed
+\& ../ext/IO/lib/IO/t/io_poll............FAILED tests 3\-4
+\& ../ext/IPC/SysV/ipcsysv...............FAILED tests 2, 5\-6
+\& ../ext/IPC/SysV/t/msg.................FAILED tests 2, 4\-6
+\& ../ext/Socket/socketpair..............FAILED tests 12
+\& ../lib/IPC/SysV.......................FAILED tests 2, 5\-6
+\& ../lib/warnings.......................FAILED tests 115\-116, 118\-119
+.Ve
+.PP
+The op/pack failure ("Cannot compress negative numbers at op/pack.t line 126")
+is serious but as of yet unsolved.  It points at some problems with the
+signedness handling of the C compiler, as do the 64bitint, arith, and pow
+failures.  Most of the rest point at problems with SysV IPC.
+.SS "Term::ReadKey not working on Win32"
+.IX Subsection "Term::ReadKey not working on Win32"
+Use Term::ReadKey 2.20 or later.
+.SS UNICOS/mk
+.IX Subsection "UNICOS/mk"
+.IP \(bu 4
+During Configure, the test
+.Sp
+.Vb 1
+\&    Guessing which symbols your C compiler and preprocessor define...
+.Ve
+.Sp
+will probably fail with error messages like
+.Sp
+.Vb 2
+\&    CC\-20 cc: ERROR File = try.c, Line = 3
+\&      The identifier "bad" is undefined.
+\&
+\&      bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
+\&      ^
+\&
+\&    CC\-65 cc: ERROR File = try.c, Line = 3
+\&      A semicolon is expected at this point.
+.Ve
+.Sp
+This is caused by a bug in the awk utility of UNICOS/mk.  You can ignore
+the error, but it does cause a slight problem: you cannot fully
+benefit from the h2ph utility (see h2ph) that can be used to
+convert C headers to Perl libraries, mainly used to be able to access
+from Perl the constants defined using C preprocessor, cpp.  Because of
+the above error, parts of the converted headers will be invisible.
+Luckily, these days the need for h2ph is rare.
+.IP \(bu 4
+If building Perl with interpreter threads (ithreads), the
+\&\fBgetgrent()\fR, \fBgetgrnam()\fR, and \fBgetgrgid()\fR functions cannot return the
+list of the group members due to a bug in the multithreaded support of
+UNICOS/mk.  What this means is that in list context the functions will
+return only three values, not four.
+.SS UTS
+.IX Subsection "UTS"
+There are a few known test failures.  (\fBNote:\fR the relevant information was
+available in \fIREADME.uts\fR until support for UTS was removed in Perl
+v5.18.0)
+.SS "VOS (Stratus)"
+.IX Subsection "VOS (Stratus)"
+When Perl is built using the native build process on VOS Release
+14.5.0 and GNU C++/GNU Tools 2.0.1, all attempted tests either
+pass or result in TODO (ignored) failures.
+.SS VMS
+.IX Subsection "VMS"
+There should be no reported test failures with a default configuration,
+though there are a number of tests marked TODO that point to areas
+needing further debugging and/or porting work.
+.SS Win32
+.IX Subsection "Win32"
+In multi-CPU boxes, there are some problems with the I/O buffering:
+some output may appear twice.
+.SS "XML::Parser not working"
+.IX Subsection "XML::Parser not working"
+Use XML::Parser 2.31 or later.
+.SS "z/OS (OS/390)"
+.IX Subsection "z/OS (OS/390)"
+z/OS has rather many test failures but the situation is actually much
+better than it was in 5.6.0; it's just that so many new modules and
+tests have been added.
+.PP
+.Vb 10
+\& Failed Test                   Stat Wstat Total Fail  Failed  List of Failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& ../ext/Data/Dumper/t/dumper.t              357    8   2.24%  311 314 325 327
+\&                                                              331 333 337 339
+\& ../ext/IO/lib/IO/t/io_unix.t                 5    4  80.00%  2\-5
+\& ../ext/Storable/t/downgrade.t   12  3072   169   12   7.10%  14\-15 46\-47 78\-79
+\&                                                              110\-111 150 161
+\& ../lib/ExtUtils/t/Constant.t   121 30976    48   48 100.00%  1\-48
+\& ../lib/ExtUtils/t/Embed.t                    9    9 100.00%  1\-9
+\& op/pat.t                                   922    7   0.76%  665 776 785 832\-
+\&                                                              834 845
+\& op/sprintf.t                               224    3   1.34%  98 100 136
+\& op/tr.t                                     97    5   5.15%  63 71\-74
+\& uni/fold.t                                 780    6   0.77%  61 169 196 661
+\&                                                              710\-711
+.Ve
+.PP
+The failures in dumper.t and downgrade.t are problems in the tests,
+those in io_unix and sprintf are problems in the USS (UDP sockets and
+printf formats).  The pat, tr, and fold failures are genuine Perl
+problems caused by EBCDIC (and in the pat and fold cases, combining
+that with Unicode).  The Constant and Embed are probably problems in
+the tests (since they test Perl's ability to build extensions, and
+that seems to be working reasonably well.)
+.SS "Unicode Support on EBCDIC Still Spotty"
+.IX Subsection "Unicode Support on EBCDIC Still Spotty"
+Though mostly working, Unicode support still has problem spots on
+EBCDIC platforms.  One such known spot are the \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR
+regular expression constructs for code points less than 256: the
+\&\f(CW\*(C`pP\*(C'\fR are testing for Unicode code points, not knowing about EBCDIC.
+.SS "Seen In Perl 5.7 But Gone Now"
+.IX Subsection "Seen In Perl 5.7 But Gone Now"
+\&\f(CW\*(C`Time::Piece\*(C'\fR (previously known as \f(CW\*(C`Time::Object\*(C'\fR) was removed
+because it was felt that it didn't have enough value in it to be a
+core module.  It is still a useful module, though, and is available
+from the CPAN.
+.PP
+Perl 5.8 unfortunately does not build anymore on AmigaOS; this broke
+accidentally at some point.  Since there are not that many Amiga
+developers available, we could not get this fixed and tested in time
+for 5.8.0.  Perl 5.6.1 still works for AmigaOS (as does the 5.7.2
+development release).
+.PP
+The \f(CW\*(C`PerlIO::Scalar\*(C'\fR and \f(CW\*(C`PerlIO::Via\*(C'\fR (capitalised) were renamed as
+\&\f(CW\*(C`PerlIO::scalar\*(C'\fR and \f(CW\*(C`PerlIO::via\*(C'\fR (all lowercase) just before 5.8.0.
+The main rationale was to have all core PerlIO layers to have all
+lowercase names.  The "plugins" are named as usual, for example
+\&\f(CW\*(C`PerlIO::via::QuotedPrint\*(C'\fR.
+.PP
+The \f(CW\*(C`threads::shared::queue\*(C'\fR and \f(CW\*(C`threads::shared::semaphore\*(C'\fR were
+renamed as \f(CW\*(C`Thread::Queue\*(C'\fR and \f(CW\*(C`Thread::Semaphore\*(C'\fR just before 5.8.0.
+The main rationale was to have thread modules to obey normal naming,
+\&\f(CW\*(C`Thread::\*(C'\fR (the \f(CW\*(C`threads\*(C'\fR and \f(CW\*(C`threads::shared\*(C'\fR themselves are
+more pragma-like, they affect compile-time, so they stay lowercase).
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://bugs.perl.org/ .  There may also be
+information at http://www.perl.com/ , the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Written by Jarkko Hietaniemi <\fIjhi@iki.fi\fR>.
diff --git a/upstream/mageia-cauldron/man1/perlaix.1 b/upstream/mageia-cauldron/man1/perlaix.1
new file mode 100644
index 00000000..2bd841a2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlaix.1
@@ -0,0 +1,587 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLAIX 1"
+.TH PERLAIX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlaix \- Perl version 5 on IBM AIX (UNIX) systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of IBM's UNIX operating
+system AIX that will affect how Perl version 5 (hereafter just Perl)
+is compiled and/or runs.
+.SS "Compiling Perl 5 on AIX"
+.IX Subsection "Compiling Perl 5 on AIX"
+For information on compilers on older versions of AIX, see "Compiling
+Perl 5 on older AIX versions up to 4.3.3".
+.PP
+When compiling Perl, you must use an ANSI C compiler. AIX does not ship
+an ANSI compliant C compiler with AIX by default, but binary builds of
+gcc for AIX are widely available. A version of gcc is also included in
+the AIX Toolbox which is shipped with AIX.
+.SS "Supported Compilers"
+.IX Subsection "Supported Compilers"
+Currently all versions of IBM's "xlc", "xlc_r", "cc", "cc_r" or
+"vac" ANSI/C compiler will work for building Perl if that compiler
+works on your system.
+.PP
+If you plan to link Perl to any module that requires thread-support,
+like DBD::Oracle, it is better to use the _r version of the compiler.
+This will not build a threaded Perl, but a thread-enabled Perl. See
+also "Threaded Perl" later on.
+.PP
+As of writing (2010\-09) only the \fIIBM XL C for AIX\fR or \fIIBM XL C/C++
+for AIX\fR compiler is supported by IBM on AIX 5L/6.1/7.1.
+.PP
+The following compiler versions are currently supported by IBM:
+.PP
+.Vb 1
+\&    IBM XL C and IBM XL C/C++ V8, V9, V10, V11
+.Ve
+.PP
+The XL C for AIX is integrated in the XL C/C++ for AIX compiler and
+therefore also supported.
+.PP
+If you choose XL C/C++ V9 you need APAR IZ35785 installed
+otherwise the integrated SDBM_File do not compile correctly due
+to an optimization bug. You can circumvent this problem by
+adding \-qipa to the optimization flags (\-Doptimize='\-O \-qipa').
+The PTF for APAR IZ35785 which solves this problem is available
+from IBM (April 2009 PTF for XL C/C++ Enterprise Edition for AIX, V9.0).
+.PP
+If you choose XL C/C++ V11 you need the April 2010 PTF (or newer)
+installed otherwise you will not get a working Perl version.
+.PP
+Perl can be compiled with either IBM's ANSI C compiler or with gcc.
+The former is recommended, as not only it can compile Perl with no
+difficulty, but also can take advantage of features listed later
+that require the use of IBM compiler-specific command-line flags.
+.PP
+If you decide to use gcc, make sure your installation is recent and
+complete, and be sure to read the Perl INSTALL file for more gcc-specific
+details. Please report any hoops you had to jump through to the
+development team.
+.SS "Incompatibility with AIX Toolbox lib gdbm"
+.IX Subsection "Incompatibility with AIX Toolbox lib gdbm"
+If the AIX Toolbox version of lib gdbm < 1.8.3\-5 is installed on your
+system then Perl will not work. This library contains the header files
+/opt/freeware/include/gdbm/dbm.h|ndbm.h which conflict with the AIX
+system versions. The lib gdbm will be automatically removed from the
+wanted libraries if the presence of one of these two header files is
+detected. If you want to build Perl with GDBM support then please install
+at least gdbm\-devel\-1.8.3\-5 (or higher).
+.SS "Perl 5 was successfully compiled and tested on:"
+.IX Subsection "Perl 5 was successfully compiled and tested on:"
+.Vb 10
+\& Perl   | AIX Level           | Compiler Level          | w th | w/o th
+\& \-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-
+\& 5.12.2 |5.1 TL9 32 bit       | XL C/C++ V7             | OK   | OK
+\& 5.12.2 |5.1 TL9 64 bit       | XL C/C++ V7             | OK   | OK
+\& 5.12.2 |5.2 TL10 SP8 32 bit  | XL C/C++ V8             | OK   | OK
+\& 5.12.2 |5.2 TL10 SP8 32 bit  | gcc 3.2.2               | OK   | OK
+\& 5.12.2 |5.2 TL10 SP8 64 bit  | XL C/C++ V8             | OK   | OK
+\& 5.12.2 |5.3 TL8 SP8 32 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
+\& 5.12.2 |5.3 TL8 SP8 32 bit   | gcc 4.2.4               | OK   | OK
+\& 5.12.2 |5.3 TL8 SP8 64 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
+\& 5.12.2 |5.3 TL10 SP3 32 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
+\& 5.12.2 |5.3 TL10 SP3 64 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
+\& 5.12.2 |6.1 TL1 SP7 32 bit   | XL C/C++ V10            | OK   | OK
+\& 5.12.2 |6.1 TL1 SP7 64 bit   | XL C/C++ V10            | OK   | OK
+\& 5.13   |7.1 TL0 SP1 32 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
+\& 5.13   |7.1 TL0 SP1 64 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
+\&
+\& w th   = with thread support
+\& w/o th = without thread support
+\& OK     = tested
+.Ve
+.PP
+Successfully tested means that all "make test" runs finish with a
+result of 100% OK. All tests were conducted with \-Duseshrplib set.
+.PP
+All tests were conducted on the oldest supported AIX technology level
+with the latest support package applied. If the tested AIX version is
+out of support (AIX 4.3.3, 5.1, 5.2) then the last available support
+level was used.
+.SS "Building Dynamic Extensions on AIX"
+.IX Subsection "Building Dynamic Extensions on AIX"
+Starting from Perl 5.7.2 (and consequently 5.8.x / 5.10.x / 5.12.x)
+and AIX 4.3 or newer Perl uses the AIX native dynamic loading interface
+in the so called runtime linking mode instead of the emulated interface
+that was used in Perl releases 5.6.1 and earlier or, for AIX releases
+4.2 and earlier. This change does break backward compatibility with
+compiled modules from earlier Perl releases. The change was made to make
+Perl more compliant with other applications like Apache/mod_perl which are
+using the AIX native interface. This change also enables the use of
+C++ code with static constructors and destructors in Perl extensions,
+which was not possible using the emulated interface.
+.PP
+It is highly recommended to use the new interface.
+.SS "Using Large Files with Perl"
+.IX Subsection "Using Large Files with Perl"
+Should yield no problems.
+.SS "Threaded Perl"
+.IX Subsection "Threaded Perl"
+Should yield no problems with AIX 5.1 / 5.2 / 5.3 / 6.1 / 7.1.
+.PP
+IBM uses the AIX system Perl (V5.6.0 on AIX 5.1 and V5.8.2 on
+AIX 5.2 / 5.3 and 6.1; V5.8.8 on AIX 5.3 TL11 and AIX 6.1 TL4; V5.10.1
+on AIX 7.1) for some AIX system scripts. If you switch the links in
+/usr/bin from the AIX system Perl (/usr/opt/perl5) to the newly build
+Perl then you get the same features as with the IBM AIX system Perl if
+the threaded options are used.
+.PP
+The threaded Perl build works also on AIX 5.1 but the IBM Perl
+build (Perl v5.6.0) is not threaded on AIX 5.1.
+.PP
+Perl 5.12 an newer is not compatible with the IBM fileset perl.libext.
+.SS "64\-bit Perl"
+.IX Subsection "64-bit Perl"
+If your AIX system is installed with 64\-bit support, you can expect 64\-bit
+configurations to work. If you want to use 64\-bit Perl on AIX 6.1
+you need an APAR for a libc.a bug which affects (n)dbm_XXX functions.
+The APAR number for this problem is IZ39077.
+.PP
+If you need more memory (larger data segment) for your Perl programs you
+can set:
+.PP
+.Vb 3
+\&    /etc/security/limits
+\&    default:                    (or your user)
+\&        data = \-1               (default is 262144 * 512 byte)
+.Ve
+.PP
+With the default setting the size is limited to 128MB.
+The \-1 removes this limit. If the "make test" fails please change
+your /etc/security/limits as stated above.
+.SS "Long doubles"
+.IX Subsection "Long doubles"
+IBM calls its implementation of long doubles 128\-bit, but it is not
+the IEEE 128\-bit ("quadruple precision") which would give 116 bit of
+mantissa (nor it is implemented in hardware), instead it's a special
+software implementation called "double-double", which gives 106 bits
+of mantissa.
+.PP
+There seem to be various problems in this long double implementation.
+If Configure detects this brokenness, it will disable the long double support.
+This can be overridden with explicit \f(CW\*(C`\-Duselongdouble\*(C'\fR (or \f(CW\*(C`\-Dusemorebits\*(C'\fR,
+which enables both long doubles and 64 bit integers).  If you decide to
+enable long doubles, for most of the broken things Perl has implemented
+workarounds, but the handling of the special values infinity and NaN
+remains badly broken: for example infinity plus zero results in NaN.
+.SS "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32\-bit)"
+.IX Subsection "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)"
+With the following options you get a threaded Perl version which
+passes all make tests in threaded 32\-bit mode, which is the default
+configuration for the Perl builds that AIX ships with.
+.PP
+.Vb 7
+\&    rm config.sh
+\&    ./Configure \e
+\&    \-d \e
+\&    \-Dcc=cc_r \e
+\&    \-Duseshrplib \e
+\&    \-Dusethreads \e
+\&    \-Dprefix=/usr/opt/perl5_32
+.Ve
+.PP
+The \-Dprefix option will install Perl in a directory parallel to the 
+IBM AIX system Perl installation.
+.SS "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32\-bit)"
+.IX Subsection "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)"
+With the following options you get a Perl version which passes 
+all make tests in 32\-bit mode.
+.PP
+.Vb 6
+\&    rm config.sh
+\&    ./Configure \e
+\&    \-d \e
+\&    \-Dcc=cc_r \e
+\&    \-Duseshrplib \e
+\&    \-Dprefix=/usr/opt/perl5_32
+.Ve
+.PP
+The \-Dprefix option will install Perl in a directory parallel to the
+IBM AIX system Perl installation.
+.SS "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64\-bit)"
+.IX Subsection "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)"
+With the following options you get a threaded Perl version which
+passes all make tests in 64\-bit mode.
+.PP
+.Vb 1
+\& export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
+\&
+\& rm config.sh
+\& ./Configure \e
+\& \-d \e
+\& \-Dcc=cc_r \e
+\& \-Duseshrplib \e
+\& \-Dusethreads \e
+\& \-Duse64bitall \e
+\& \-Dprefix=/usr/opt/perl5_64
+.Ve
+.SS "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64\-bit)"
+.IX Subsection "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)"
+With the following options you get a Perl version which passes all
+make tests in 64\-bit mode.
+.PP
+.Vb 1
+\& export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
+\&
+\& rm config.sh
+\& ./Configure \e
+\& \-d \e
+\& \-Dcc=cc_r \e
+\& \-Duseshrplib \e
+\& \-Duse64bitall \e
+\& \-Dprefix=/usr/opt/perl5_64
+.Ve
+.PP
+The \-Dprefix option will install Perl in a directory parallel to the
+IBM AIX system Perl installation.
+.PP
+If you choose gcc to compile 64\-bit Perl then you need to add the
+following option:
+.PP
+.Vb 1
+\&    \-Dcc=\*(Aqgcc \-maix64\*(Aq
+.Ve
+.SS "Compiling Perl 5 on AIX 7.1.0"
+.IX Subsection "Compiling Perl 5 on AIX 7.1.0"
+A regression in AIX 7 causes a failure in make test in Time::Piece during
+daylight savings time.  APAR IV16514 provides the fix for this.  A quick
+test to see if it's required, assuming it is currently daylight savings
+in Eastern Time, would be to run \f(CW\*(C` TZ=EST5 date +%Z \*(C'\fR.  This will come
+back with \f(CW\*(C`EST\*(C'\fR normally, but nothing if you have the problem.
+.SS "Compiling Perl 5 on older AIX versions up to 4.3.3"
+.IX Subsection "Compiling Perl 5 on older AIX versions up to 4.3.3"
+Due to the fact that AIX 4.3.3 reached end-of-service in December 31,
+2003 this information is provided as is. The Perl versions prior to
+Perl 5.8.9 could be compiled on AIX up to 4.3.3 with the following
+settings (your mileage may vary):
+.PP
+When compiling Perl, you must use an ANSI C compiler. AIX does not ship
+an ANSI compliant C\-compiler with AIX by default, but binary builds of
+gcc for AIX are widely available.
+.PP
+At the moment of writing, AIX supports two different native C compilers,
+for which you have to pay: \fBxlC\fR and \fBvac\fR. If you decide to use either
+of these two (which is quite a lot easier than using gcc), be sure to
+upgrade to the latest available patch level. Currently:
+.PP
+.Vb 2
+\&    xlC.C     3.1.4.10 or 3.6.6.0 or 4.0.2.2 or 5.0.2.9 or 6.0.0.3
+\&    vac.C     4.4.0.3  or 5.0.2.6 or 6.0.0.1
+.Ve
+.PP
+note that xlC has the OS version in the name as of version 4.0.2.0, so
+you will find xlC.C for AIX\-5.0 as package
+.PP
+.Vb 1
+\&    xlC.aix50.rte   5.0.2.0 or 6.0.0.3
+.Ve
+.PP
+subversions are not the same "latest" on all OS versions. For example,
+the latest xlC\-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.
+.PP
+Perl can be compiled with either IBM's ANSI C compiler or with gcc.
+The former is recommended, as not only can it compile Perl with no
+difficulty, but also can take advantage of features listed later that
+require the use of IBM compiler-specific command-line flags.
+.PP
+The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler
+optimization bugs that affect compiling perl.c and regcomp.c,
+respectively.  If Perl's configuration detects those compiler patch
+levels, optimization is turned off for the said source code files.
+Upgrading to at least 5.0.2.0 is recommended.
+.PP
+If you decide to use gcc, make sure your installation is recent and
+complete, and be sure to read the Perl INSTALL file for more gcc-specific
+details. Please report any hoops you had to jump through to the development
+team.
+.SS "OS level"
+.IX Subsection "OS level"
+Before installing the patches to the IBM C\-compiler you need to know the
+level of patching for the Operating System. IBM's command 'oslevel' will
+show the base, but is not always complete (in this example oslevel shows
+4.3.NULL, whereas the system might run most of 4.3.THREE):
+.PP
+.Vb 6
+\&    # oslevel
+\&    4.3.0.0
+\&    # lslpp \-l | grep \*(Aqbos.rte \*(Aq
+\&    bos.rte           4.3.3.75  COMMITTED  Base Operating System Runtime
+\&    bos.rte            4.3.2.0  COMMITTED  Base Operating System Runtime
+\&    #
+.Ve
+.PP
+The same might happen to AIX 5.1 or other OS levels. As a side note, Perl
+cannot be built without bos.adt.syscalls and bos.adt.libm installed
+.PP
+.Vb 4
+\&    # lslpp \-l | egrep "syscalls|libm"
+\&    bos.adt.libm      5.1.0.25  COMMITTED  Base Application Development
+\&    bos.adt.syscalls  5.1.0.36  COMMITTED  System Calls Application
+\&    #
+.Ve
+.SS "Building Dynamic Extensions on AIX < 5L"
+.IX Subsection "Building Dynamic Extensions on AIX < 5L"
+AIX supports dynamically loadable objects as well as shared libraries.
+Shared libraries by convention end with the suffix .a, which is a bit
+misleading, as an archive can contain static as well as dynamic members.
+For Perl dynamically loaded objects we use the .so suffix also used on
+many other platforms.
+.PP
+Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3
+or newer Perl uses the AIX native dynamic loading interface in the so
+called runtime linking mode instead of the emulated interface that was
+used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and
+earlier.  This change does break backward compatibility with compiled
+modules from earlier Perl releases.  The change was made to make Perl
+more compliant with other applications like Apache/mod_perl which are
+using the AIX native interface. This change also enables the use of C++
+code with static constructors and destructors in Perl extensions, which
+was not possible using the emulated interface.
+.SS "The IBM ANSI C Compiler"
+.IX Subsection "The IBM ANSI C Compiler"
+All defaults for Configure can be used.
+.PP
+If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions
+will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0,
+but vac 5.0.2.6 or up is highly recommended. Note that since IBM has
+removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these
+versions should be considered obsolete.
+.PP
+Here's a brief lead of how to upgrade the compiler to the latest
+level.  Of course this is subject to changes.  You can only upgrade
+versions from ftp-available updates if the first three digit groups
+are the same (in where you can skip intermediate unlike the patches
+in the developer snapshots of Perl), or to one version up where the
+"base" is available.  In other words, the AIX compiler patches are
+cumulative.
+.PP
+.Vb 3
+\& vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
+\& xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not
+\&                                                              available)
+\&
+\& # ftp ftp.software.ibm.com
+\& Connected to service.boulder.ibm.com.
+\& : welcome message ...
+\& Name (ftp.software.ibm.com:merijn): anonymous
+\& 331 Guest login ok, send your complete e\-mail address as password.
+\& Password:
+\& ... accepted login stuff
+\& ftp> cd /aix/fixes/v4/
+\& ftp> dir other other.ll
+\& output to local\-file: other.ll? y
+\& 200 PORT command successful.
+\& 150 Opening ASCII mode data connection for /bin/ls.
+\& 226 Transfer complete.
+\& ftp> dir xlc xlc.ll
+\& output to local\-file: xlc.ll? y
+\& 200 PORT command successful.
+\& 150 Opening ASCII mode data connection for /bin/ls.
+\& 226 Transfer complete.
+\& ftp> bye
+\& ... goodbye messages
+\& # ls \-l *.ll
+\& \-rw\-rw\-rw\-   1 merijn   system    1169432 Nov  2 17:29 other.ll
+\& \-rw\-rw\-rw\-   1 merijn   system      29170 Nov  2 17:29 xlc.ll
+.Ve
+.PP
+On AIX 4.2 using xlC, we continue:
+.PP
+.Vb 10
+\& # lslpp \-l | fgrep \*(AqxlC.C \*(Aq
+\&   xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
+\&   xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
+\& # grep \*(AqxlC.C.3.1.4.*.bff\*(Aq xlc.ll
+\& \-rw\-r\-\-r\-\-   1 45776101 1       6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
+\& \-rw\-r\-\-r\-\-   1 45776101 1       6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
+\& \-rw\-r\-\-r\-\-   1 45776101 1       6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
+\& \-rw\-r\-\-r\-\-   1 45776101 1       6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6188032 May 22 1997  xlC.C.3.1.4.6.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       6169600 May 27 1998  xlC.C.3.1.4.9.bff
+\& # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
+\& #
+.Ve
+.PP
+On AIX 4.3 using vac, we continue:
+.PP
+.Vb 10
+\& # lslpp \-l | grep \*(Aqvac.C \*(Aq
+\&  vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
+\&  vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
+\& # grep \*(Aqvac.C.5.0.2.*.bff\*(Aq other.ll
+\& \-rw\-rw\-r\-\-   1 45776101 1       13592576 Apr 16 2001  vac.C.5.0.2.0.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       14133248 Apr  9 2002  vac.C.5.0.2.3.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       14173184 May 20 2002  vac.C.5.0.2.4.bff
+\& \-rw\-rw\-r\-\-   1 45776101 1       14192640 Nov 22 2002  vac.C.5.0.2.6.bff
+\& # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
+\& #
+.Ve
+.PP
+Likewise on all other OS levels. Then execute the following command, and
+fill in its choices
+.PP
+.Vb 5
+\& # smit install_update
+\&  \-> Install and Update from LATEST Available Software
+\&  * INPUT device / directory for software [ vac.C.5.0.2.6.bff    ]
+\&  [ OK ]
+\&  [ OK ]
+.Ve
+.PP
+Follow the messages ... and you're done.
+.PP
+If you like a more web-like approach, a good start point can be
+<http://www14.software.ibm.com/webapp/download/downloadaz.jsp> and click
+"C for AIX", and follow the instructions.
+.SS "The usenm option"
+.IX Subsection "The usenm option"
+If linking miniperl
+.PP
+.Vb 1
+\& cc \-o miniperl ... miniperlmain.o opmini.o perl.o ... \-lm \-lc ...
+.Ve
+.PP
+causes error like this
+.PP
+.Vb 9
+\& ld: 0711\-317 ERROR: Undefined symbol: .aintl
+\& ld: 0711\-317 ERROR: Undefined symbol: .copysignl
+\& ld: 0711\-317 ERROR: Undefined symbol: .syscall
+\& ld: 0711\-317 ERROR: Undefined symbol: .eaccess
+\& ld: 0711\-317 ERROR: Undefined symbol: .setresuid
+\& ld: 0711\-317 ERROR: Undefined symbol: .setresgid
+\& ld: 0711\-317 ERROR: Undefined symbol: .setproctitle
+\& ld: 0711\-345 Use the \-bloadmap or \-bnoquiet option to obtain more
+\&                                                            information.
+.Ve
+.PP
+you could retry with
+.PP
+.Vb 3
+\& make realclean
+\& rm config.sh
+\& ./Configure \-Dusenm ...
+.Ve
+.PP
+which makes Configure to use the \f(CW\*(C`nm\*(C'\fR tool when scanning for library
+symbols, which usually is not done in AIX.
+.PP
+Related to this, you probably should not use the \f(CW\*(C`\-r\*(C'\fR option of
+Configure in AIX, because that affects of how the \f(CW\*(C`nm\*(C'\fR tool is used.
+.SS "Using GNU's gcc for building Perl"
+.IX Subsection "Using GNU's gcc for building Perl"
+Using gcc\-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box,
+as do recent gcc\-2.9 builds available directly from IBM as part of their
+Linux compatibility packages, available here:
+.PP
+.Vb 1
+\&  http://www.ibm.com/servers/aix/products/aixos/linux/
+.Ve
+.SS "Using Large Files with Perl < 5L"
+.IX Subsection "Using Large Files with Perl < 5L"
+Should yield no problems.
+.SS "Threaded Perl < 5L"
+.IX Subsection "Threaded Perl < 5L"
+Threads seem to work OK, though at the moment not all tests pass when
+threads are used in combination with 64\-bit configurations.
+.PP
+You may get a warning when doing a threaded build:
+.PP
+.Vb 2
+\&  "pp_sys.c", line 4640.39: 1506\-280 (W) Function argument assignment 
+\&  between types "unsigned char*" and "const void*" is not allowed.
+.Ve
+.PP
+The exact line number may vary, but if the warning (W) comes from a line
+line this
+.PP
+.Vb 1
+\&  hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);
+.Ve
+.PP
+in the "pp_ghostent" function, you may ignore it safely.  The warning
+is caused by the reentrant variant of \fBgethostbyaddr()\fR having a slightly
+different prototype than its non-reentrant variant, but the difference
+is not really significant here.
+.SS "64\-bit Perl < 5L"
+.IX Subsection "64-bit Perl < 5L"
+If your AIX is installed with 64\-bit support, you can expect 64\-bit
+configurations to work. In combination with threads some tests might
+still fail.
+.SS "AIX 4.2 and extensions using C++ with statics"
+.IX Subsection "AIX 4.2 and extensions using C++ with statics"
+In AIX 4.2 Perl extensions that use C++ functions that use statics
+may have problems in that the statics are not getting initialized.
+In newer AIX releases this has been solved by linking Perl with
+the libC_r library, but unfortunately in AIX 4.2 the said library
+has an obscure bug where the various functions related to time
+(such as \fBtime()\fR and \fBgettimeofday()\fR) return broken values, and
+therefore in AIX 4.2 Perl is not linked against the libC_r.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Rainer Tammer <tammer@tammer.net>
diff --git a/upstream/mageia-cauldron/man1/perlamiga.1 b/upstream/mageia-cauldron/man1/perlamiga.1
new file mode 100644
index 00000000..a5bd7f07
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlamiga.1
@@ -0,0 +1,250 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLAMIGA 1"
+.TH PERLAMIGA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlamiga \- Perl under AmigaOS 4.1
+.SH NOTE
+.IX Header "NOTE"
+This is a port of Perl 5.22.1, it is a fresh port and not in any way
+compatible with my previous ports of Perl 5.8 and 5.16.3. This means
+you will need to reinstall / rebuild any third party modules you have
+installed.
+.PP
+newlib.library version 53.28 or greater is required.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+Once perl is installed you can read this document in the following way
+.PP
+.Vb 1
+\&        sh \-c "perldoc perlamiga"
+.Ve
+.PP
+or you may read \fIas is\fR: either as \fIREADME.amiga\fR, or \fIpod/perlamiga.pod\fR.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1"
+.IX Subsection "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1"
+.IP "\fBAmigaOS 4.1 update 6 with all updates applied as of 9th October 2013\fR" 6
+.IX Item "AmigaOS 4.1 update 6 with all updates applied as of 9th October 2013"
+The most important of which is:
+.IP "\fBnewlib.library version 53.28 or greater\fR" 6
+.IX Item "newlib.library version 53.28 or greater"
+.PD 0
+.IP "\fBAmigaOS SDK\fR" 6
+.IX Item "AmigaOS SDK"
+.PD
+Perl installs into the SDK directory structure and expects many of the
+build tools present in the SDK to be available. So for the best results
+install the SDK first.
+.IP \fBabc-shell\fR 6
+.IX Item "abc-shell"
+If you do not have the SDK installed you must at least have abc-shell
+installed or some other suitable sh port. This is required to run
+external commands and should be available as 'sh' in your path.
+.SS "Starting Perl programs under AmigaOS 4.1"
+.IX Subsection "Starting Perl programs under AmigaOS 4.1"
+Perl may be run from the AmigaOS shell but for best results should be
+run under abc-shell.  (abc-shell handles file globbing, pattern
+expansion, and sets up environment variables in the UN*Xy way that
+Perl expects.)
+.PP
+For example:
+.PP
+.Vb 3
+\&        New Shell process 10
+\&        10.AmigaOS4:> sh
+\&        /AmigaOS4>perl path:to/myprog arg1 arrg2 arg3
+.Ve
+.PP
+Abc-shell can also launch programs via the #! syntax at the start of
+the program file, it's best use the form #!SDK:Local/C/perl so that
+the AmigaOS shell may also find perl in the same way. AmigaOS requires
+the script bit to be set for this to work
+.PP
+.Vb 2
+\&        10.AmigaOS4:> sh
+\&        /AmigaOS4>myprog arg1 arrg2 arg3
+.Ve
+.SS "Limitations of Perl under AmigaOS 4.1"
+.IX Subsection "Limitations of Perl under AmigaOS 4.1"
+.IP "\fBNested Piped programs can crash when run from older abc-shells\fR" 6
+.IX Item "Nested Piped programs can crash when run from older abc-shells"
+abc-shell version 53.2 has a bug that can cause crashes in the
+subprocesses used to run piped programs, if a later version is
+available you should install it instead.
+.IP "\fBIncorrect or unexpected command line unescaping\fR" 6
+.IX Item "Incorrect or unexpected command line unescaping"
+newlib.library 53.30 and earlier incorrectly unescape slashed escape
+sequences e.g. \e" \en \et etc requiring unusual extra escaping.
+.IP "\fBStarting subprocesses via open has limitations\fR" 6
+.IX Item "Starting subprocesses via open has limitations"
+.Vb 1
+\&        open FH, "command |"
+.Ve
+.Sp
+Subprocesses started with open use a minimal \fBpopen()\fR routine and
+therefore they do not return pids usable with waitpid etc.
+.IP "If you find any other limitations or bugs then let me know." 6
+.IX Item "If you find any other limitations or bugs then let me know."
+Please report bugs in this version of perl to andy@broad.ology.org.uk
+in the first instance.
+.SH INSTALLATION
+.IX Header "INSTALLATION"
+This guide assumes you have obtained a prebuilt archive from os4depot.net.
+.PP
+Unpack the main archive to a temporary location (RAM: is fine).
+.PP
+Execute the provided install script from shell or via its icon.
+.PP
+You \fBmust not\fR attempt to install by hand.
+.PP
+Once installed you may delete the temporary archive.
+.PP
+This approach will preserve links in the installation without creating
+duplicate binaries.
+.PP
+If you have the earlier ports perl 5.16 or 5.8 installed you may like
+to rename your perl executable to perl516 or perl58 or something
+similar before the installation of 5.22.1, this will allow you to use
+both versions at the same time.
+.SH "Amiga Specific Modules"
+.IX Header "Amiga Specific Modules"
+.SS Amiga::ARexx
+.IX Subsection "Amiga::ARexx"
+The Amiga::ARexx module allows you to easily create a perl based ARexx
+host or to send ARexx commands to other programs.
+.PP
+Try \f(CW\*(C`perldoc Amiga::ARexx\*(C'\fR for more info.
+.SS Amiga::Exec
+.IX Subsection "Amiga::Exec"
+The Amiga::Exec module introduces support for \fBWait()\fR.
+.PP
+Try \f(CW\*(C`perldoc Amiga::Exec\*(C'\fR for more info.
+.SH BUILDING
+.IX Header "BUILDING"
+To build perl under AmigaOS from the patched sources you will need to
+have a recent version of the SDK. Version 53.29 is recommended,
+earlier versions will probably work too.
+.PP
+With the help of Jarkko Hietaniemi the Configure system has been tweaked to
+run under abc-shell so the recommend build process is as follows.
+.PP
+.Vb 3
+\&        stack 2000000
+\&        sh Configure \-de
+\&        gmake
+.Ve
+.PP
+This will build the default setup that installs under SDK:local/newlib/lib/
+.SH CHANGES
+.IX Header "CHANGES"
+.IP "\fBAugust 2015\fR" 6
+.IX Item "August 2015"
+.RS 6
+.PD 0
+.IP "Port to Perl 5.22" 2
+.IX Item "Port to Perl 5.22"
+.IP "Add handling of NIL: to \fBafstat()\fR" 2
+.IX Item "Add handling of NIL: to afstat()"
+.IP "Fix inheritance of environment variables by subprocesses." 2
+.IX Item "Fix inheritance of environment variables by subprocesses."
+.IP "Fix exec, and exit in ""forked"" subprocesses." 2
+.IX Item "Fix exec, and exit in ""forked"" subprocesses."
+.IP "Fix issue with newlib's unlink, which could cause infinite loops." 2
+.IX Item "Fix issue with newlib's unlink, which could cause infinite loops."
+.IP "Add \fBflock()\fR emulation using IDOS\->LockRecord thanks to Tony Cook for the suggestion." 2
+.IX Item "Add flock() emulation using IDOS->LockRecord thanks to Tony Cook for the suggestion."
+.IP "Fix issue where kill was using the wrong kind of process ID" 2
+.IX Item "Fix issue where kill was using the wrong kind of process ID"
+.RE
+.RS 6
+.RE
+.IP "\fB27th November 2013\fR" 6
+.IX Item "27th November 2013"
+.RS 6
+.IP "Create new installation system based on installperl links and Amiga protection bits now set correctly." 2
+.IX Item "Create new installation system based on installperl links and Amiga protection bits now set correctly."
+.IP "Pod now defaults to text." 2
+.IX Item "Pod now defaults to text."
+.IP "File::Spec should now recognise an Amiga style absolute path as well as an Unix style one. Relative paths must always be Unix style." 2
+.IX Item "File::Spec should now recognise an Amiga style absolute path as well as an Unix style one. Relative paths must always be Unix style."
+.RE
+.RS 6
+.RE
+.IP "\fB20th November 2013\fR" 6
+.IX Item "20th November 2013"
+.RS 6
+.IP "Configured to use SDK:Local/C/perl to start standard scripts" 2
+.IX Item "Configured to use SDK:Local/C/perl to start standard scripts"
+.IP "Added Amiga::Exec module with support for \fBWait()\fR and AmigaOS signal numbers." 2
+.IX Item "Added Amiga::Exec module with support for Wait() and AmigaOS signal numbers."
+.RE
+.RS 6
+.RE
+.IP "\fB10th October 13\fR" 6
+.IX Item "10th October 13"
+.PD
+First release of port to 5.16.3.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+You like this port?  See <http://www.broad.ology.org.uk/amiga/>
+for how you can help.
diff --git a/upstream/mageia-cauldron/man1/perlandroid.1 b/upstream/mageia-cauldron/man1/perlandroid.1
new file mode 100644
index 00000000..deb4c4a3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlandroid.1
@@ -0,0 +1,274 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLANDROID 1"
+.TH PERLANDROID 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlandroid \- Perl under Android
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+The first portions of this document contains instructions
+to cross-compile Perl for Android 2.0 and later, using the
+binaries provided by Google.  The latter portions describe how to build
+perl native using one of the toolchains available on the Play Store.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes how to set up your host environment when
+attempting to build Perl for Android.
+.SH Cross-compilation
+.IX Header "Cross-compilation"
+These instructions assume an Unixish build environment on your host system;
+they've been tested on Linux and OS X, and may work on Cygwin and MSYS.
+While Google also provides an NDK for Windows, these steps won't work
+native there, although it may be possible to cross-compile through different
+means.
+.PP
+If your host system's architecture is 32 bits, remember to change the
+\&\f(CW\*(C`x86_64\*(C'\fR's below to \f(CW\*(C`x86\*(C'\fR's.  On a similar vein, the examples below
+use the 4.8 toolchain; if you want to use something older or newer (for
+example, the 4.4.3 toolchain included in the 8th revision of the NDK), just
+change those to the relevant version.
+.SS "Get the Android Native Development Kit (NDK)"
+.IX Subsection "Get the Android Native Development Kit (NDK)"
+You can download the NDK from <https://developer.android.com/tools/sdk/ndk/index.html>.
+You'll want the normal, non-legacy version.
+.SS "Determine the architecture you'll be cross-compiling for"
+.IX Subsection "Determine the architecture you'll be cross-compiling for"
+There's three possible options: arm-linux-androideabi for ARM,
+mipsel-linux-android for MIPS, and simply x86 for x86.
+As of 2014, most Android devices run on ARM, so that is generally a safe bet.
+.PP
+With those two in hand, you should add
+.PP
+.Vb 1
+\&  $ANDROID_NDK/toolchains/$TARGETARCH\-4.8/prebuilt/\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64/bin
+.Ve
+.PP
+to your \f(CW\*(C`PATH\*(C'\fR, where \f(CW$ANDROID_NDK\fR is the location where you unpacked the
+NDK, and \f(CW$TARGETARCH\fR is your target's architecture.
+.SS "Set up a standalone toolchain"
+.IX Subsection "Set up a standalone toolchain"
+This creates a working sysroot that we can feed to Configure later.
+.PP
+.Vb 7
+\&    $ export ANDROID_TOOLCHAIN=/tmp/my\-toolchain\-$TARGETARCH
+\&    $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
+\&    $ $ANDROID_NDK/build/tools/make\-standalone\-toolchain.sh \e
+\&            \-\-platform=android\-9 \e
+\&            \-\-install\-dir=$ANDROID_TOOLCHAIN \e
+\&            \-\-system=\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64 \e
+\&            \-\-toolchain=$TARGETARCH\-4.8
+.Ve
+.SS "adb or ssh?"
+.IX Subsection "adb or ssh?"
+adb is the Android Debug Bridge.  For our purposes, it's basically a way
+of establishing an ssh connection to an Android device without having to
+install anything on the device itself, as long as the device is either on
+the same local network as the host, or it is connected to the host through
+USB.
+.PP
+Perl can be cross-compiled using either adb or a normal ssh connection;
+in general, if you can connect your device to the host using a USB port,
+or if you don't feel like installing an sshd app on your device,
+you may want to use adb, although you may be forced to switch to ssh if
+your device is not rooted and you're unlucky \-\- more on that later.
+Alternatively, if you're cross-compiling to an emulator, you'll have to
+use adb.
+.PP
+\fIadb\fR
+.IX Subsection "adb"
+.PP
+To use adb, download the Android SDK from <https://developer.android.com/sdk/index.html>.
+The "SDK Tools Only" version should suffice \-\- if you downloaded the ADT
+Bundle, you can find the sdk under \fR\f(CI$ADT_BUNDLE\fR\fI/sdk/\fR.
+.PP
+Add \fR\f(CI$ANDROID_SDK\fR\fI/platform\-tools\fR to your \f(CW\*(C`PATH\*(C'\fR, which should give you access
+to adb.  You'll now have to find your device's name using \f(CW\*(C`adb devices\*(C'\fR,
+and later pass that to Configure through \f(CW\*(C`\-Dtargethost=$DEVICE\*(C'\fR.
+.PP
+However, before calling Configure, you need to check if using adb is a
+viable choice in the first place.  Because Android doesn't have a \fI/tmp\fR,
+nor does it allow executables in the sdcard, we need to find somewhere in
+the device for Configure to put some files in, as well as for the tests
+to run in. If your device is rooted, then you're good.  Try running these:
+.PP
+.Vb 2
+\&    $ export TARGETDIR=/mnt/asec/perl
+\&    $ adb \-s $DEVICE shell "echo sh \-c \*(Aq\e"mkdir $TARGETDIR\e"\*(Aq | su \-\-"
+.Ve
+.PP
+Which will create the directory we need, and you can move on to the next
+step.  \fI/mnt/asec\fR is mounted as a tmpfs in Android, but it's only
+accessible to root.
+.PP
+If your device is not rooted, you may still be in luck. Try running this:
+.PP
+.Vb 2
+\&    $ export TARGETDIR=/data/local/tmp/perl
+\&    $ adb \-s $DEVICE shell "mkdir $TARGETDIR"
+.Ve
+.PP
+If the command works, you can move to the next step, but beware:
+\&\fBYou'll have to remove the directory from the device once you are done!
+Unlike \fR\f(BI/mnt/asec\fR\fB, \fR\f(BI/data/local/tmp\fR\fB may not get automatically garbage
+collected once you shut off the phone\fR.
+.PP
+If neither of those work, then you can't use adb to cross-compile to your
+device.  Either try rooting it, or go for the ssh route.
+.PP
+\fIssh\fR
+.IX Subsection "ssh"
+.PP
+To use ssh, you'll need to install and run a sshd app and set it up
+properly.  There are several paid and free apps that do this rather
+easily, so you should be able to spot one on the store.
+Remember that Perl requires a passwordless connection, so set up a 
+public key.
+.PP
+Note that several apps spew crap to stderr every time you
+connect, which can throw off Configure.  You may need to monkeypatch
+the part of Configure that creates \f(CW\*(C`run\-ssh\*(C'\fR to have it discard stderr.
+.PP
+Since you're using ssh, you'll have to pass some extra arguments to
+Configure:
+.PP
+.Vb 1
+\&  \-Dtargetrun=ssh \-Dtargethost=$TARGETHOST \-Dtargetuser=$TARGETUSER \-Dtargetport=$TARGETPORT
+.Ve
+.SS "Configure and beyond"
+.IX Subsection "Configure and beyond"
+With all of the previous done, you're now ready to call Configure.
+.PP
+If using adb, a "basic" Configure line will look like this:
+.PP
+.Vb 5
+\&  $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=adb \e
+\&      \-Dcc=$TARGETARCH\-gcc   \e
+\&      \-Dsysroot=$SYSROOT     \e
+\&      \-Dtargetdir=$TARGETDIR \e
+\&      \-Dtargethost=$DEVICE
+.Ve
+.PP
+If using ssh, it's not too different \-\- we just change targetrun to ssh,
+and pass in targetuser and targetport.  It ends up looking like this:
+.PP
+.Vb 7
+\&  $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=ssh \e
+\&      \-Dcc=$TARGETARCH\-gcc        \e
+\&      \-Dsysroot=$SYSROOT          \e
+\&      \-Dtargetdir=$TARGETDIR      \e
+\&      \-Dtargethost="$TARGETHOST"  \e
+\&      \-Dtargetuser=$TARGETUSER    \e
+\&      \-Dtargetport=$TARGETPORT
+.Ve
+.PP
+Now you're ready to run \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`make test\*(C'\fR!
+.PP
+As a final word of warning, if you're using adb, \f(CW\*(C`make test\*(C'\fR may appear to
+hang; this is because it doesn't output anything until it finishes
+running all tests.  You can check its progress by logging into the
+device, moving to \fR\f(CI$TARGETDIR\fR\fI\fR, and looking at the file \fIoutput.stdout\fR.
+.PP
+\fINotes\fR
+.IX Subsection "Notes"
+.IP \(bu 4
+If you are targetting x86 Android, you will have to change \f(CW\*(C`$TARGETARCH\-gcc\*(C'\fR
+to \f(CW\*(C`i686\-linux\-android\-gcc\*(C'\fR.
+.IP \(bu 4
+On some older low-end devices \-\- think early 2.2 era \-\- some tests,
+particularly \fIt/re/uniprops.t\fR, may crash the phone, causing it to turn
+itself off once, and then back on again.
+.SH "Native Builds"
+.IX Header "Native Builds"
+While Google doesn't provide a native toolchain for Android,
+you can still get one from the Play Store.
+.SS CCTools
+.IX Subsection "CCTools"
+You may be able to get the CCTools app, which is free.
+Keep in mind that you want a full toolchain;
+some apps tend to default to installing only a barebones
+version without some important utilities, like ar or nm.
+.PP
+Once you have the toolchain set up properly, the only
+remaining hurdle is actually locating where in the device it was installed
+in.  For example, CCTools installs its toolchain in 
+\&\fI/data/data/com.pdaxrom.cctools/root/cctools\fR.  With the path in hand,
+compiling perl is little more than:
+.PP
+.Vb 3
+\& export SYSROOT=<location of the native toolchain>
+\& export LD_LIBRARY_PATH="$SYSROOT/lib:\`pwd\`:\`pwd\`/lib:\`pwd\`/lib/auto:$LD_LIBRARY_PATH"
+\& sh Configure \-des \-Dsysroot=$SYSROOT \-Alibpth="/system/lib /vendor/lib"
+.Ve
+.SS Termux
+.IX Subsection "Termux"
+Termux <https://termux.com/> provides an Android terminal emulator and Linux environment.
+It comes with a cross-compiled perl already installed.
+.PP
+Natively compiling perl 5.30 or later should be as straightforward as:
+.PP
+.Vb 1
+\& sh Configure \-des \-Alibpth="/system/lib /vendor/lib"
+.Ve
+.PP
+This certainly works on Android 8.1 (Oreo) at least...
+.SH AUTHOR
+.IX Header "AUTHOR"
+Brian Fraser <fraserbn@gmail.com>
diff --git a/upstream/mageia-cauldron/man1/perlapi.1 b/upstream/mageia-cauldron/man1/perlapi.1
new file mode 100644
index 00000000..309a8313
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlapi.1
@@ -0,0 +1,29981 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLAPI 1"
+.TH PERLAPI 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlapi \- autogenerated documentation for the perl public API
+.SH DESCRIPTION
+.IX Xref "Perl API API api"
+.IX Header "DESCRIPTION"
+This file contains most of the documentation of the perl public API, as
+generated by \fIembed.pl\fR.  Specifically, it is a listing of functions,
+macros, flags, and variables that may be used by extension writers.  Besides
+perlintern and \fIconfig.h\fR, some items are listed here as being actually
+documented in another pod.
+.PP
+At the end is a list of functions which have yet
+to be documented.  Patches welcome!  The interfaces of these are subject to
+change without notice.
+.PP
+Some of the functions documented here are consolidated so that a single entry
+serves for multiple functions which all do basically the same thing, but have
+some slight differences.  For example, one form might process magic, while
+another doesn't.  The name of each variation is listed at the top of the
+single entry.  But if all have the same signature (arguments and return type)
+except for their names, only the usage for the base form is shown.  If any
+one of the forms has a different signature (such as returning \f(CW\*(C`const\*(C'\fR or
+not) every function's signature is explicitly displayed.
+.PP
+Anything not listed here or in the other mentioned pods is not part of the
+public API, and should not be used by extension writers at all.  For these
+reasons, blindly using functions listed in \fIproto.h\fR is to be avoided when
+writing extensions.
+.PP
+In Perl, unlike C, a string of characters may generally contain embedded
+\&\f(CW\*(C`NUL\*(C'\fR characters.  Sometimes in the documentation a Perl string is referred
+to as a "buffer" to distinguish it from a C string, but sometimes they are
+both just referred to as strings.
+.PP
+Note that all Perl API global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR
+prefix.  Again, those not listed here are not to be used by extension writers,
+and may be changed or removed without notice; same with macros.
+Some macros are provided for compatibility with the older,
+unadorned names, but this support may be disabled in a future release.
+.PP
+Perl was originally written to handle US-ASCII only (that is characters
+whose ordinal numbers are in the range 0 \- 127).
+And documentation and comments may still use the term ASCII, when
+sometimes in fact the entire range from 0 \- 255 is meant.
+.PP
+The non-ASCII characters below 256 can have various meanings, depending on
+various things.  (See, most notably, perllocale.)  But usually the whole
+range can be referred to as ISO\-8859\-1.  Often, the term "Latin\-1" (or
+"Latin1") is used as an equivalent for ISO\-8859\-1.  But some people treat
+"Latin1" as referring just to the characters in the range 128 through 255, or
+sometimes from 160 through 255.
+This documentation uses "Latin1" and "Latin\-1" to refer to all 256 characters.
+.PP
+Note that Perl can be compiled and run under either ASCII or EBCDIC (See
+perlebcdic).  Most of the documentation (and even comments in the code)
+ignore the EBCDIC possibility.
+For almost all purposes the differences are transparent.
+As an example, under EBCDIC,
+instead of UTF\-8, UTF-EBCDIC is used to encode Unicode strings, and so
+whenever this documentation refers to \f(CW\*(C`utf8\*(C'\fR
+(and variants of that name, including in function names),
+it also (essentially transparently) means \f(CW\*(C`UTF\-EBCDIC\*(C'\fR.
+But the ordinals of characters differ between ASCII, EBCDIC, and
+the UTF\- encodings, and a string encoded in UTF-EBCDIC may occupy a different
+number of bytes than in UTF\-8.
+.PP
+The organization of this document is tentative and subject to change.
+Suggestions and patches welcome
+perl5\-porters@perl.org <mailto:perl5-porters@perl.org>.
+.PP
+The sections in this document currently are
+.IP """AV Handling""" 4
+.IX Item """AV Handling"""
+.PD 0
+.IP """Callback Functions""" 4
+.IX Item """Callback Functions"""
+.IP """Casting""" 4
+.IX Item """Casting"""
+.IP """Character case changing""" 4
+.IX Item """Character case changing"""
+.IP """Character classification""" 4
+.IX Item """Character classification"""
+.IP """Compiler and Preprocessor information""" 4
+.IX Item """Compiler and Preprocessor information"""
+.IP """Compiler directives""" 4
+.IX Item """Compiler directives"""
+.IP """Compile-time scope hooks""" 4
+.IX Item """Compile-time scope hooks"""
+.IP """Concurrency""" 4
+.IX Item """Concurrency"""
+.IP """COPs and Hint Hashes""" 4
+.IX Item """COPs and Hint Hashes"""
+.IP """Custom Operators""" 4
+.IX Item """Custom Operators"""
+.IP """CV Handling""" 4
+.IX Item """CV Handling"""
+.IP """Debugging""" 4
+.IX Item """Debugging"""
+.IP """Display functions""" 4
+.IX Item """Display functions"""
+.IP """Embedding, Threads, and Interpreter Cloning""" 4
+.IX Item """Embedding, Threads, and Interpreter Cloning"""
+.IP """Errno""" 4
+.IX Item """Errno"""
+.IP """Exception Handling (simple) Macros""" 4
+.IX Item """Exception Handling (simple) Macros"""
+.IP """Filesystem configuration values""" 4
+.IX Item """Filesystem configuration values"""
+.IP """Floating point""" 4
+.IX Item """Floating point"""
+.IP """General Configuration""" 4
+.IX Item """General Configuration"""
+.IP """Global Variables""" 4
+.IX Item """Global Variables"""
+.IP """GV Handling and Stashes""" 4
+.IX Item """GV Handling and Stashes"""
+.IP """Hook manipulation""" 4
+.IX Item """Hook manipulation"""
+.IP """HV Handling""" 4
+.IX Item """HV Handling"""
+.IP """Input/Output""" 4
+.IX Item """Input/Output"""
+.IP """Integer""" 4
+.IX Item """Integer"""
+.IP """I/O Formats""" 4
+.IX Item """I/O Formats"""
+.IP """Lexer interface""" 4
+.IX Item """Lexer interface"""
+.IP """Locales""" 4
+.IX Item """Locales"""
+.IP """Magic""" 4
+.IX Item """Magic"""
+.IP """Memory Management""" 4
+.IX Item """Memory Management"""
+.IP """MRO""" 4
+.IX Item """MRO"""
+.IP """Multicall Functions""" 4
+.IX Item """Multicall Functions"""
+.IP """Numeric Functions""" 4
+.IX Item """Numeric Functions"""
+.IP """Optrees""" 4
+.IX Item """Optrees"""
+.IP """Pack and Unpack""" 4
+.IX Item """Pack and Unpack"""
+.IP """Pad Data Structures""" 4
+.IX Item """Pad Data Structures"""
+.IP """Password and Group access""" 4
+.IX Item """Password and Group access"""
+.IP """Paths to system commands""" 4
+.IX Item """Paths to system commands"""
+.IP """Prototype information""" 4
+.IX Item """Prototype information"""
+.IP """REGEXP Functions""" 4
+.IX Item """REGEXP Functions"""
+.IP """Reports and Formats""" 4
+.IX Item """Reports and Formats"""
+.IP """Signals""" 4
+.IX Item """Signals"""
+.IP """Site configuration""" 4
+.IX Item """Site configuration"""
+.IP """Sockets configuration values""" 4
+.IX Item """Sockets configuration values"""
+.IP """Source Filters""" 4
+.IX Item """Source Filters"""
+.IP """Stack Manipulation Macros""" 4
+.IX Item """Stack Manipulation Macros"""
+.IP """String Handling""" 4
+.IX Item """String Handling"""
+.IP """SV Flags""" 4
+.IX Item """SV Flags"""
+.IP """SV Handling""" 4
+.IX Item """SV Handling"""
+.IP """Tainting""" 4
+.IX Item """Tainting"""
+.IP """Time""" 4
+.IX Item """Time"""
+.IP """Typedef names""" 4
+.IX Item """Typedef names"""
+.IP """Unicode Support""" 4
+.IX Item """Unicode Support"""
+.IP """Utility Functions""" 4
+.IX Item """Utility Functions"""
+.IP """Versioning""" 4
+.IX Item """Versioning"""
+.IP """Warning and Dieing""" 4
+.IX Item """Warning and Dieing"""
+.IP """XS""" 4
+.IX Item """XS"""
+.IP """Undocumented elements""" 4
+.IX Item """Undocumented elements"""
+.PD
+.PP
+The listing below is alphabetical, case insensitive.
+.SH "AV Handling"
+.IX Header "AV Handling"
+.ie n .IP """AV""" 4
+.el .IP \f(CWAV\fR 4
+.IX Item "AV"
+Described in perlguts.
+.ie n .IP """AvALLOC""" 4
+.el .IP \f(CWAvALLOC\fR 4
+.IX Item "AvALLOC"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   AvALLOC(AV* av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """AvARRAY""" 4
+.el .IP \f(CWAvARRAY\fR 4
+.IX Xref "AvARRAY"
+.IX Item "AvARRAY"
+Returns a pointer to the AV's internal SV* array.
+.Sp
+This is useful for doing pointer arithmetic on the array.
+If all you need is to look up an array element, then prefer \f(CW\*(C`av_fetch\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV**  AvARRAY(AV* av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_clear""" 4
+.el .IP \f(CWav_clear\fR 4
+.IX Xref "av_clear"
+.IX Item "av_clear"
+Frees all the elements of an array, leaving it empty.
+The XS equivalent of \f(CW\*(C`@array = ()\*(C'\fR.  See also "av_undef".
+.Sp
+Note that it is possible that the actions of a destructor called directly
+or indirectly by freeing an element of the array could cause the reference
+count of the array itself to be reduced (e.g. by deleting an entry in the
+symbol table). So it is a possibility that the AV could have been freed
+(or even reallocated) on return from the call unless you hold a reference
+to it.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_clear(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_count""" 4
+.el .IP \f(CWav_count\fR 4
+.IX Xref "av_count"
+.IX Item "av_count"
+Returns the number of elements in the array \f(CW\*(C`av\*(C'\fR.  This is the true length of
+the array, including any undefined elements.  It is always the same as
+\&\f(CW\*(C`av_top_index(av)\ +\ 1\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  av_count(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_create_and_push""" 4
+.el .IP \f(CWav_create_and_push\fR 4
+.IX Xref "av_create_and_push"
+.IX Item "av_create_and_push"
+Push an SV onto the end of the array, creating the array if necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+.Sp
+NOTE: \f(CW\*(C`av_create_and_push\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_av_create_and_push\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_av_create_and_push(pTHX_ AV ** const avp,
+\&                               SV * const val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_create_and_unshift_one""" 4
+.el .IP \f(CWav_create_and_unshift_one\fR 4
+.IX Xref "av_create_and_unshift_one"
+.IX Item "av_create_and_unshift_one"
+Unshifts an SV onto the beginning of the array, creating the array if
+necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+.Sp
+NOTE: \f(CW\*(C`av_create_and_unshift_one\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_av_create_and_unshift_one\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& SV **  Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
+\&                                       SV * const val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_delete""" 4
+.el .IP \f(CWav_delete\fR 4
+.IX Xref "av_delete"
+.IX Item "av_delete"
+Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array, makes the element
+mortal, and returns it.  If \f(CW\*(C`flags\*(C'\fR equals \f(CW\*(C`G_DISCARD\*(C'\fR, the element is
+freed and NULL is returned. NULL is also returned if \f(CW\*(C`key\*(C'\fR is out of
+range.
+.Sp
+Perl equivalent: \f(CW\*(C`splice(@myarray,\ $key,\ 1,\ undef)\*(C'\fR (with the
+\&\f(CW\*(C`splice\*(C'\fR in void context if \f(CW\*(C`G_DISCARD\*(C'\fR is present).
+.RS 4
+.Sp
+.Vb 1
+\& SV *  av_delete(AV *av, SSize_t key, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_exists""" 4
+.el .IP \f(CWav_exists\fR 4
+.IX Xref "av_exists"
+.IX Item "av_exists"
+Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized.
+.Sp
+This relies on the fact that uninitialized array elements are set to
+\&\f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Perl equivalent: \f(CWexists($myarray[$key])\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  av_exists(AV *av, SSize_t key)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_extend""" 4
+.el .IP \f(CWav_extend\fR 4
+.IX Xref "av_extend"
+.IX Item "av_extend"
+Pre-extend an array so that it is capable of storing values at indexes
+\&\f(CW\*(C`0..key\*(C'\fR. Thus \f(CW\*(C`av_extend(av,99)\*(C'\fR guarantees that the array can store 100
+elements, i.e. that \f(CW\*(C`av_store(av, 0, sv)\*(C'\fR through \f(CW\*(C`av_store(av, 99, sv)\*(C'\fR
+on a plain array will work without any further memory allocation.
+.Sp
+If the av argument is a tied array then will call the \f(CW\*(C`EXTEND\*(C'\fR tied
+array method with an argument of \f(CW\*(C`(key+1)\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_extend(AV *av, SSize_t key)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_fetch""" 4
+.el .IP \f(CWav_fetch\fR 4
+.IX Xref "av_fetch"
+.IX Item "av_fetch"
+Returns the SV at the specified index in the array.  The \f(CW\*(C`key\*(C'\fR is the
+index.  If \f(CW\*(C`lval\*(C'\fR is true, you are guaranteed to get a real SV back (in case
+it wasn't real before), which you can then modify.  Check that the return
+value is non-NULL before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
+more information on how to use this function on tied arrays.
+.Sp
+The rough perl equivalent is \f(CW$myarray[$key]\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  av_fetch(AV *av, SSize_t key, I32 lval)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """AvFILL""" 4
+.el .IP \f(CWAvFILL\fR 4
+.IX Xref "AvFILL"
+.IX Item "AvFILL"
+Same as \f(CW"av_top_index"\fR or \f(CW"av_tindex"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  AvFILL(AV* av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_fill""" 4
+.el .IP \f(CWav_fill\fR 4
+.IX Xref "av_fill"
+.IX Item "av_fill"
+Set the highest index in the array to the given number, equivalent to
+Perl's \f(CW\*(C`$#array\ =\ $fill;\*(C'\fR.
+.Sp
+The number of elements in the array will be \f(CW\*(C`fill\ +\ 1\*(C'\fR after
+\&\f(CWav_fill()\fR returns.  If the array was previously shorter, then the
+additional elements appended are set to NULL.  If the array
+was longer, then the excess elements are freed.  \f(CW\*(C`av_fill(av,\ \-1)\*(C'\fR is
+the same as \f(CWav_clear(av)\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_fill(AV *av, SSize_t fill)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_len""" 4
+.el .IP \f(CWav_len\fR 4
+.IX Xref "av_len"
+.IX Item "av_len"
+Same as "av_top_index".  Note that, unlike what the name implies, it returns
+the maximum index in the array.  This is unlike "sv_len", which returns what
+you would expect.
+.Sp
+\&\fBTo get the true number of elements in the array, instead use \fR\f(CB"av_count"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  av_len(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_make""" 4
+.el .IP \f(CWav_make\fR 4
+.IX Xref "av_make"
+.IX Item "av_make"
+Creates a new AV and populates it with a list (\f(CW**strp\fR, length \f(CW\*(C`size\*(C'\fR) of
+SVs.  A copy is made of each SV, so their refcounts are not changed.  The new
+AV will have a reference count of 1.
+.Sp
+Perl equivalent: \f(CW\*(C`my @new_array = ($scalar1, $scalar2, $scalar3...);\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& AV *  av_make(SSize_t size, SV **strp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_pop""" 4
+.el .IP \f(CWav_pop\fR 4
+.IX Xref "av_pop"
+.IX Item "av_pop"
+Removes one SV from the end of the array, reducing its size by one and
+returning the SV (transferring control of one reference count) to the
+caller.  Returns \f(CW&PL_sv_undef\fR if the array is empty.
+.Sp
+Perl equivalent: \f(CW\*(C`pop(@myarray);\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  av_pop(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_push""" 4
+.el .IP \f(CWav_push\fR 4
+.IX Xref "av_push"
+.IX Item "av_push"
+Pushes an SV (transferring control of one reference count) onto the end of the
+array.  The array will grow automatically to accommodate the addition.
+.Sp
+Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_push(AV *av, SV *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_push_simple""" 4
+.el .IP \f(CWav_push_simple\fR 4
+.IX Xref "av_push_simple"
+.IX Item "av_push_simple"
+This is a cut-down version of av_push that assumes that the array is very
+straightforward \- no magic, not readonly, and AvREAL \- and that \f(CW\*(C`key\*(C'\fR is
+not less than \-1. This function MUST NOT be used in situations where any
+of those assumptions may not hold.
+.Sp
+Pushes an SV (transferring control of one reference count) onto the end of the
+array.  The array will grow automatically to accommodate the addition.
+.Sp
+Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_push_simple(AV *av, SV *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_shift""" 4
+.el .IP \f(CWav_shift\fR 4
+.IX Xref "av_shift"
+.IX Item "av_shift"
+Removes one SV from the start of the array, reducing its size by one and
+returning the SV (transferring control of one reference count) to the
+caller.  Returns \f(CW&PL_sv_undef\fR if the array is empty.
+.Sp
+Perl equivalent: \f(CW\*(C`shift(@myarray);\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  av_shift(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_store""" 4
+.el .IP \f(CWav_store\fR 4
+.IX Xref "av_store"
+.IX Item "av_store"
+Stores an SV in an array.  The array index is specified as \f(CW\*(C`key\*(C'\fR.  The
+return value will be \f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not
+need to be actually stored within the array (as in the case of tied
+arrays).  Otherwise, it can be dereferenced
+to get the \f(CW\*(C`SV*\*(C'\fR that was stored
+there (= \f(CW\*(C`val\*(C'\fR)).
+.Sp
+Note that the caller is responsible for suitably incrementing the reference
+count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function
+returned \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
+more information on how to use this function on tied arrays.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  av_store(AV *av, SSize_t key, SV *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_tindex""" 4
+.el .IP \f(CWav_tindex\fR 4
+.IX Item "av_tindex"
+.PD 0
+.ie n .IP """av_top_index""" 4
+.el .IP \f(CWav_top_index\fR 4
+.IX Xref "av_tindex av_top_index"
+.IX Item "av_top_index"
+.PD
+These behave identically.
+If the array \f(CW\*(C`av\*(C'\fR is empty, these return \-1; otherwise they return the maximum
+value of the indices of all the array elements which are currently defined in
+\&\f(CW\*(C`av\*(C'\fR.
+.Sp
+They process 'get' magic.
+.Sp
+The Perl equivalent for these is \f(CW$#av\fR.
+.Sp
+Use \f(CW"av_count"\fR to get the number of elements in an array.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  av_tindex(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_undef""" 4
+.el .IP \f(CWav_undef\fR 4
+.IX Xref "av_undef"
+.IX Item "av_undef"
+Undefines the array. The XS equivalent of \f(CWundef(@array)\fR.
+.Sp
+As well as freeing all the elements of the array (like \f(CWav_clear()\fR), this
+also frees the memory used by the av to store its list of scalars.
+.Sp
+See "av_clear" for a note about the array possibly being invalid on
+return.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_undef(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_unshift""" 4
+.el .IP \f(CWav_unshift\fR 4
+.IX Xref "av_unshift"
+.IX Item "av_unshift"
+Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the
+array.  The array will grow automatically to accommodate the addition.
+.Sp
+Perl equivalent: \f(CW\*(C`unshift\ @myarray,\ ((undef)\ x\ $num);\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  av_unshift(AV *av, SSize_t num)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_av""" 4
+.el .IP \f(CWget_av\fR 4
+.IX Xref "get_av"
+.IX Item "get_av"
+Returns the AV of the specified Perl global or package array with the given
+name (so it won't work on lexical variables).  \f(CW\*(C`flags\*(C'\fR are passed
+to \f(CW\*(C`gv_fetchpv\*(C'\fR.  If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
+Perl variable does not exist then it will be created.  If \f(CW\*(C`flags\*(C'\fR is zero
+(ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
+returned.
+.Sp
+Perl equivalent: \f(CW\*(C`@{"$name"}\*(C'\fR.
+.Sp
+NOTE: the \f(CWperl_get_av()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& AV *  get_av(const char *name, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newAV""" 4
+.el .IP \f(CWnewAV\fR 4
+.IX Item "newAV"
+.PD 0
+.ie n .IP """newAV_alloc_x""" 4
+.el .IP \f(CWnewAV_alloc_x\fR 4
+.IX Item "newAV_alloc_x"
+.ie n .IP """newAV_alloc_xz""" 4
+.el .IP \f(CWnewAV_alloc_xz\fR 4
+.IX Xref "newAV newAV_alloc_x newAV_alloc_xz"
+.IX Item "newAV_alloc_xz"
+.PD
+These all create a new AV, setting the reference count to 1.  If you also know
+the initial elements of the array with, see "\f(CW\*(C`av_make\*(C'\fR".
+.Sp
+As background, an array consists of three things:
+.RS 4
+.IP 1. 4
+A data structure containing information about the array as a whole, such as its
+size and reference count.
+.IP 2. 4
+A C language array of pointers to the individual elements.  These are treated
+as pointers to SVs, so all must be castable to SV*.
+.IP 3. 4
+The individual elements themselves.  These could be, for instance, SVs and/or
+AVs and/or HVs, etc.
+.RE
+.RS 4
+.Sp
+An empty array need only have the first data structure, and all these functions
+create that.  They differ in what else they do, as follows:
+.ie n .IP """newAV"" form" 4
+.el .IP "\f(CWnewAV\fR form" 4
+.IX Item "newAV form"
+This does nothing beyond creating the whole-array data structure.
+The Perl equivalent is approximately \f(CW\*(C`my\ @array;\*(C'\fR
+.Sp
+This is useful when the minimum size of the array could be zero (perhaps there
+are likely code paths that will entirely skip using it).
+.Sp
+If the array does get used, the pointers data structure will need to be
+allocated at that time.  This will end up being done by "av_extend">,
+either explicitly:
+.Sp
+.Vb 1
+\&    av_extend(av, len);
+.Ve
+.Sp
+or implicitly when the first element is stored:
+.Sp
+.Vb 1
+\&    (void)av_store(av, 0, sv);
+.Ve
+.Sp
+Unused array elements are typically initialized by \f(CW\*(C`av_extend\*(C'\fR.
+.ie n .IP """newAV_alloc_x"" form" 4
+.el .IP "\f(CWnewAV_alloc_x\fR form" 4
+.IX Item "newAV_alloc_x form"
+This effectively does a \f(CW\*(C`newAV\*(C'\fR followed by also allocating (uninitialized)
+space for the pointers array.  This is used when you know ahead of time the
+likely minimum size of the array.  It is more efficient to do this than doing a
+plain \f(CW\*(C`newAV\*(C'\fR followed by an \f(CW\*(C`av_extend\*(C'\fR.
+.Sp
+Of course the array can be extended later should it become necessary.
+.Sp
+\&\f(CW\*(C`size\*(C'\fR must be at least 1.
+.ie n .IP """newAV_alloc_xz"" form" 4
+.el .IP "\f(CWnewAV_alloc_xz\fR form" 4
+.IX Item "newAV_alloc_xz form"
+This is \f(CW\*(C`newAV_alloc_x\*(C'\fR, but initializes each pointer in it to NULL.  This
+gives added safety to guard against them being read before being set.
+.Sp
+\&\f(CW\*(C`size\*(C'\fR must be at least 1.
+.RE
+.RS 4
+.Sp
+The following examples all result in an array that can fit four elements
+(indexes 0 .. 3):
+.Sp
+.Vb 2
+\&    AV *av = newAV();
+\&    av_extend(av, 3);
+\&
+\&    AV *av = newAV_alloc_x(4);
+\&
+\&    AV *av = newAV_alloc_xz(4);
+.Ve
+.Sp
+In contrast, the following examples allocate an array that is only guaranteed
+to fit one element without extending:
+.Sp
+.Vb 2
+\&    AV *av = newAV_alloc_x(1);
+\&    AV *av = newAV_alloc_xz(1);
+.Ve
+.Sp
+.Vb 3
+\& AV *  newAV         ()
+\& AV *  newAV_alloc_x (SSize_t size)
+\& AV *  newAV_alloc_xz(SSize_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newAVav""" 4
+.el .IP \f(CWnewAVav\fR 4
+.IX Xref "newAVav"
+.IX Item "newAVav"
+Creates a new AV and populates it with values copied from an existing AV.  The
+new AV will have a reference count of 1, and will contain newly created SVs
+copied from the original SV.  The original source will remain unchanged.
+.Sp
+Perl equivalent: \f(CW\*(C`my @new_array = @existing_array;\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& AV *  newAVav(AV *oav)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newAVhv""" 4
+.el .IP \f(CWnewAVhv\fR 4
+.IX Xref "newAVhv"
+.IX Item "newAVhv"
+Creates a new AV and populates it with keys and values copied from an existing
+HV.  The new AV will have a reference count of 1, and will contain newly
+created SVs copied from the original HV.  The original source will remain
+unchanged.
+.Sp
+Perl equivalent: \f(CW\*(C`my @new_array = %existing_hash;\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& AV *  newAVhv(HV *ohv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Nullav""" 4
+.el .IP \f(CWNullav\fR 4
+.IX Xref "Nullav"
+.IX Item "Nullav"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`Nullav\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Null AV pointer.
+.Sp
+(deprecated \- use \f(CW\*(C`(AV *)NULL\*(C'\fR instead)
+.SH "Callback Functions"
+.IX Xref "G_METHOD G_METHOD_NAMED G_RETHROW SAVEf_KEEPOLDELEM SAVEf_SETMAGIC"
+.IX Header "Callback Functions"
+.ie n .IP """call_argv""" 4
+.el .IP \f(CWcall_argv\fR 4
+.IX Xref "call_argv"
+.IX Item "call_argv"
+Performs a callback to the specified named and package-scoped Perl subroutine
+with \f(CW\*(C`argv\*(C'\fR (a \f(CW\*(C`NULL\*(C'\fR\-terminated array of strings) as arguments.  See
+perlcall.
+.Sp
+Approximate Perl equivalent: \f(CW\*(C`&{"$sub_name"}(@$argv)\*(C'\fR.
+.Sp
+NOTE: the \f(CWperl_call_argv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  call_argv(const char *sub_name, I32 flags, char **argv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """call_method""" 4
+.el .IP \f(CWcall_method\fR 4
+.IX Xref "call_method"
+.IX Item "call_method"
+Performs a callback to the specified Perl method.  The blessed object must
+be on the stack.  See perlcall.
+.Sp
+NOTE: the \f(CWperl_call_method()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  call_method(const char *methname, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """call_pv""" 4
+.el .IP \f(CWcall_pv\fR 4
+.IX Xref "call_pv"
+.IX Item "call_pv"
+Performs a callback to the specified Perl sub.  See perlcall.
+.Sp
+NOTE: the \f(CWperl_call_pv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  call_pv(const char *sub_name, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """call_sv""" 4
+.el .IP \f(CWcall_sv\fR 4
+.IX Xref "call_sv"
+.IX Item "call_sv"
+Performs a callback to the Perl sub specified by the SV.
+.Sp
+If neither the \f(CW\*(C`G_METHOD\*(C'\fR nor \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, the
+SV may be any of a CV, a GV, a reference to a CV, a reference to a GV
+or \f(CWSvPV(sv)\fR will be used as the name of the sub to call.
+.Sp
+If the \f(CW\*(C`G_METHOD\*(C'\fR flag is supplied, the SV may be a reference to a CV or
+\&\f(CWSvPV(sv)\fR will be used as the name of the method to call.
+.Sp
+If the \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, \f(CWSvPV(sv)\fR will be used as
+the name of the method to call.
+.Sp
+Some other values are treated specially for internal use and should
+not be depended on.
+.Sp
+See perlcall.
+.Sp
+NOTE: the \f(CWperl_call_sv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  call_sv(SV *sv, volatile I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """DESTRUCTORFUNC_NOCONTEXT_t""" 4
+.el .IP \f(CWDESTRUCTORFUNC_NOCONTEXT_t\fR 4
+.IX Item "DESTRUCTORFUNC_NOCONTEXT_t"
+Described in perlguts.
+.ie n .IP """DESTRUCTORFUNC_t""" 4
+.el .IP \f(CWDESTRUCTORFUNC_t\fR 4
+.IX Item "DESTRUCTORFUNC_t"
+Described in perlguts.
+.ie n .IP """ENTER""" 4
+.el .IP \f(CWENTER\fR 4
+.IX Xref "ENTER"
+.IX Item "ENTER"
+Opening bracket on a callback.  See \f(CW"LEAVE"\fR and perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   ENTER;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ENTER_with_name""" 4
+.el .IP \f(CWENTER_with_name\fR 4
+.IX Xref "ENTER_with_name"
+.IX Item "ENTER_with_name"
+Same as \f(CW"ENTER"\fR, but when debugging is enabled it also associates the
+given literal string with the new scope.
+.RS 4
+.Sp
+.Vb 1
+\&   ENTER_with_name("name");
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """eval_pv""" 4
+.el .IP \f(CWeval_pv\fR 4
+.IX Xref "eval_pv"
+.IX Item "eval_pv"
+Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string in scalar context and return an SV* result.
+.Sp
+NOTE: the \f(CWperl_eval_pv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  eval_pv(const char *p, I32 croak_on_error)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """eval_sv""" 4
+.el .IP \f(CWeval_sv\fR 4
+.IX Xref "eval_sv"
+.IX Item "eval_sv"
+Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the SV.  It supports the same flags
+as \f(CW\*(C`call_sv\*(C'\fR, with the obvious exception of \f(CW\*(C`G_EVAL\*(C'\fR.  See perlcall.
+.Sp
+The \f(CW\*(C`G_RETHROW\*(C'\fR flag can be used if you only need \fBeval_sv()\fR to
+execute code specified by a string, but not catch any errors.
+.Sp
+NOTE: the \f(CWperl_eval_sv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  eval_sv(SV *sv, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """FREETMPS""" 4
+.el .IP \f(CWFREETMPS\fR 4
+.IX Xref "FREETMPS"
+.IX Item "FREETMPS"
+Closing bracket for temporaries on a callback.  See \f(CW"SAVETMPS"\fR and
+perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   FREETMPS;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """G_DISCARD""" 4
+.el .IP \f(CWG_DISCARD\fR 4
+.IX Item "G_DISCARD"
+Described in perlcall.
+.ie n .IP """G_EVAL""" 4
+.el .IP \f(CWG_EVAL\fR 4
+.IX Item "G_EVAL"
+Described in perlcall.
+.ie n .IP """GIMME""" 4
+.el .IP \f(CWGIMME\fR 4
+.IX Xref "GIMME"
+.IX Item "GIMME"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`GIMME\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+A backward-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return
+\&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR; in a void context, it returns \f(CW\*(C`G_SCALAR\*(C'\fR.
+Deprecated.  Use \f(CW\*(C`GIMME_V\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  GIMME
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GIMME_V""" 4
+.el .IP \f(CWGIMME_V\fR 4
+.IX Xref "GIMME_V"
+.IX Item "GIMME_V"
+The XSUB-writer's equivalent to Perl's \f(CW\*(C`wantarray\*(C'\fR.  Returns \f(CW\*(C`G_VOID\*(C'\fR,
+\&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR for void, scalar or list context,
+respectively.  See perlcall for a usage example.
+.RS 4
+.Sp
+.Vb 1
+\& U32  GIMME_V
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """G_KEEPERR""" 4
+.el .IP \f(CWG_KEEPERR\fR 4
+.IX Item "G_KEEPERR"
+Described in perlcall.
+.ie n .IP """G_LIST""" 4
+.el .IP \f(CWG_LIST\fR 4
+.IX Item "G_LIST"
+Described in perlcall.
+.ie n .IP """G_NOARGS""" 4
+.el .IP \f(CWG_NOARGS\fR 4
+.IX Item "G_NOARGS"
+Described in perlcall.
+.ie n .IP """G_SCALAR""" 4
+.el .IP \f(CWG_SCALAR\fR 4
+.IX Item "G_SCALAR"
+Described in perlcall.
+.ie n .IP """G_VOID""" 4
+.el .IP \f(CWG_VOID\fR 4
+.IX Item "G_VOID"
+Described in perlcall.
+.ie n .IP """is_lvalue_sub""" 4
+.el .IP \f(CWis_lvalue_sub\fR 4
+.IX Xref "is_lvalue_sub"
+.IX Item "is_lvalue_sub"
+Returns non-zero if the sub calling this function is being called in an lvalue
+context.  Returns 0 otherwise.
+.RS 4
+.Sp
+.Vb 1
+\& I32  is_lvalue_sub()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LEAVE""" 4
+.el .IP \f(CWLEAVE\fR 4
+.IX Xref "LEAVE"
+.IX Item "LEAVE"
+Closing bracket on a callback.  See \f(CW"ENTER"\fR and perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   LEAVE;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LEAVE_with_name""" 4
+.el .IP \f(CWLEAVE_with_name\fR 4
+.IX Xref "LEAVE_with_name"
+.IX Item "LEAVE_with_name"
+Same as \f(CW"LEAVE"\fR, but when debugging is enabled it first checks that the
+scope has the given name. \f(CW\*(C`name\*(C'\fR must be a literal string.
+.RS 4
+.Sp
+.Vb 1
+\&   LEAVE_with_name("name");
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MORTALDESTRUCTOR_SV""" 4
+.el .IP \f(CWMORTALDESTRUCTOR_SV\fR 4
+.IX Item "MORTALDESTRUCTOR_SV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mortal_destructor_sv""" 4
+.el .IP \f(CWmortal_destructor_sv\fR 4
+.IX Xref "mortal_destructor_sv"
+.IX Item "mortal_destructor_sv"
+This function arranges for either a Perl code reference, or a C function
+reference to be called at the \fBend of the current statement\fR.
+.Sp
+The \f(CW\*(C`coderef\*(C'\fR argument determines the type of function that will be
+called. If it is \f(CWSvROK()\fR it is assumed to be a reference to a CV and
+will arrange for the coderef to be called. If it is not \fBSvROK()\fR then it
+is assumed to be a \f(CWSvIV()\fR which is \f(CWSvIOK()\fR whose value is a pointer
+to a C function of type \f(CW\*(C`DESTRUCTORFUNC_t\*(C'\fR created using \f(CWPTR2INT()\fR.
+Either way the \f(CW\*(C`args\*(C'\fR parameter will be provided to the callback as a
+parameter, although the rules for doing so differ between the Perl and
+C mode. Normally this function is only used directly for the Perl case
+and the wrapper \f(CWmortal_destructor_x()\fR is used for the C function case.
+.Sp
+When operating in Perl callback mode the \f(CW\*(C`args\*(C'\fR parameter may be NULL
+in which case the code reference is called with no arguments, otherwise
+if it is an AV (SvTYPE(args) == SVt_PVAV) then the contents of the AV
+will be used as the arguments to the code reference, and if it is any
+other type then the \f(CW\*(C`args\*(C'\fR SV will be provided as a single argument to
+the code reference.
+.Sp
+When operating in a C callback mode the \f(CW\*(C`args\*(C'\fR parameter will be passed
+directly to the C function as a \f(CW\*(C`void *\*(C'\fR pointer. No additional
+processing of the argument will be peformed, and it is the callers
+responsibility to free the \f(CW\*(C`args\*(C'\fR parameter if necessary.
+.Sp
+Be aware that there is a signficant difference in timing between the
+\&\fIend of the current statement\fR and the \fIend of the current pseudo
+block\fR. If you are looking for a mechanism to trigger a function at the
+end of the \fBcurrent pseudo block\fR you should look at
+\&\f(CWSAVEDESTRUCTORX()\fR instead of this function.
+.RS 4
+.Sp
+.Vb 1
+\& void  mortal_destructor_sv(SV *coderef, SV *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MORTALDESTRUCTOR_X""" 4
+.el .IP \f(CWMORTALDESTRUCTOR_X\fR 4
+.IX Item "MORTALDESTRUCTOR_X"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   MORTALDESTRUCTOR_X(DESTRUCTORFUNC_t f, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_errgv""" 4
+.el .IP \f(CWPL_errgv\fR 4
+.IX Item "PL_errgv"
+Described in perlcall.
+.ie n .IP """save_aelem""" 4
+.el .IP \f(CWsave_aelem\fR 4
+.IX Item "save_aelem"
+.PD 0
+.ie n .IP """save_aelem_flags""" 4
+.el .IP \f(CWsave_aelem_flags\fR 4
+.IX Xref "save_aelem save_aelem_flags"
+.IX Item "save_aelem_flags"
+.PD
+These each arrange for the value of the array element \f(CW\*(C`av[idx]\*(C'\fR to be restored
+at the end of the enclosing \fIpseudo-block\fR.
+.Sp
+In \f(CW\*(C`save_aelem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR
+scalar.  That scalar will inherit any magic from the original \f(CW**sptr\fR,
+and any 'set' magic will be processed.
+.Sp
+In \f(CW\*(C`save_aelem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes
+the function to forgo all that:  the scalar at \f(CW**sptr\fR is untouched.
+If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
+new \f(CW\*(C`undef\*(C'\fR scalar.  That scalar will inherit any magic from the original
+\&\f(CW**sptr\fR.  Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
+is set in in \f(CW\*(C`flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& void  save_aelem      (AV *av, SSize_t idx, SV **sptr)
+\& void  save_aelem_flags(AV *av, SSize_t idx, SV **sptr,
+\&                        const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_aptr""" 4
+.el .IP \f(CWsave_aptr\fR 4
+.IX Item "save_aptr"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_aptr(AV **aptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_ary""" 4
+.el .IP \f(CWsave_ary\fR 4
+.IX Item "save_ary"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& AV *  save_ary(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEBOOL""" 4
+.el .IP \f(CWSAVEBOOL\fR 4
+.IX Item "SAVEBOOL"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEBOOL(bool i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEDELETE""" 4
+.el .IP \f(CWSAVEDELETE\fR 4
+.IX Item "SAVEDELETE"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEDELETE(HV * hv, char * key, I32 length)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEDESTRUCTOR""" 4
+.el .IP \f(CWSAVEDESTRUCTOR\fR 4
+.IX Item "SAVEDESTRUCTOR"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEDESTRUCTOR_X""" 4
+.el .IP \f(CWSAVEDESTRUCTOR_X\fR 4
+.IX Item "SAVEDESTRUCTOR_X"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEFREEOP""" 4
+.el .IP \f(CWSAVEFREEOP\fR 4
+.IX Item "SAVEFREEOP"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEFREEOP(OP *op)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEFREEPV""" 4
+.el .IP \f(CWSAVEFREEPV\fR 4
+.IX Item "SAVEFREEPV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEFREEPV(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEFREERCPV""" 4
+.el .IP \f(CWSAVEFREERCPV\fR 4
+.IX Item "SAVEFREERCPV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEFREERCPV(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEFREESV""" 4
+.el .IP \f(CWSAVEFREESV\fR 4
+.IX Item "SAVEFREESV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEFREESV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEGENERICSV""" 4
+.el .IP \f(CWSAVEGENERICSV\fR 4
+.IX Item "SAVEGENERICSV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEGENERICSV(char **psv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_hash""" 4
+.el .IP \f(CWsave_hash\fR 4
+.IX Item "save_hash"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  save_hash(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_helem""" 4
+.el .IP \f(CWsave_helem\fR 4
+.IX Item "save_helem"
+.PD 0
+.ie n .IP """save_helem_flags""" 4
+.el .IP \f(CWsave_helem_flags\fR 4
+.IX Xref "save_helem save_helem_flags"
+.IX Item "save_helem_flags"
+.PD
+These each arrange for the value of the hash element (in Perlish terms)
+\&\f(CW\*(C`$hv{key}]\*(C'\fR to be restored at the end of the enclosing \fIpseudo-block\fR.
+.Sp
+In \f(CW\*(C`save_helem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR
+scalar.  That scalar will inherit any magic from the original \f(CW**sptr\fR,
+and any 'set' magic will be processed.
+.Sp
+In \f(CW\*(C`save_helem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes
+the function to forgo all that:  the scalar at \f(CW**sptr\fR is untouched.
+If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
+new \f(CW\*(C`undef\*(C'\fR scalar.  That scalar will inherit any magic from the original
+\&\f(CW**sptr\fR.  Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
+is set in in \f(CW\*(C`flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& void  save_helem      (HV *hv, SV *key, SV **sptr)
+\& void  save_helem_flags(HV *hv, SV *key, SV **sptr,
+\&                        const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_hptr""" 4
+.el .IP \f(CWsave_hptr\fR 4
+.IX Item "save_hptr"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_hptr(HV **hptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEINT""" 4
+.el .IP \f(CWSAVEINT\fR 4
+.IX Item "SAVEINT"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEINT(int i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_item""" 4
+.el .IP \f(CWsave_item\fR 4
+.IX Item "save_item"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_item(SV *item)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEIV""" 4
+.el .IP \f(CWSAVEIV\fR 4
+.IX Item "SAVEIV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEIV(IV i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEI8""" 4
+.el .IP \f(CWSAVEI8\fR 4
+.IX Item "SAVEI8"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEI8(I8 i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEI16""" 4
+.el .IP \f(CWSAVEI16\fR 4
+.IX Item "SAVEI16"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEI16(I16 i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEI32""" 4
+.el .IP \f(CWSAVEI32\fR 4
+.IX Item "SAVEI32"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEI32(I32 i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVELONG""" 4
+.el .IP \f(CWSAVELONG\fR 4
+.IX Item "SAVELONG"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVELONG(long i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEMORTALIZESV""" 4
+.el .IP \f(CWSAVEMORTALIZESV\fR 4
+.IX Item "SAVEMORTALIZESV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEMORTALIZESV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEPPTR""" 4
+.el .IP \f(CWSAVEPPTR\fR 4
+.IX Item "SAVEPPTR"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVEPPTR(char * p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVERCPV""" 4
+.el .IP \f(CWSAVERCPV\fR 4
+.IX Item "SAVERCPV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVERCPV(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_scalar""" 4
+.el .IP \f(CWsave_scalar\fR 4
+.IX Item "save_scalar"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  save_scalar(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVESPTR""" 4
+.el .IP \f(CWSAVESPTR\fR 4
+.IX Item "SAVESPTR"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVESPTR(SV * s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVESTACK_POS""" 4
+.el .IP \f(CWSAVESTACK_POS\fR 4
+.IX Item "SAVESTACK_POS"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVESTACK_POS()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVESTRLEN""" 4
+.el .IP \f(CWSAVESTRLEN\fR 4
+.IX Item "SAVESTRLEN"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVESTRLEN(STRLEN i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_svref""" 4
+.el .IP \f(CWsave_svref\fR 4
+.IX Item "save_svref"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  save_svref(SV **sptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVETMPS""" 4
+.el .IP \f(CWSAVETMPS\fR 4
+.IX Xref "SAVETMPS"
+.IX Item "SAVETMPS"
+Opening bracket for temporaries on a callback.  See \f(CW"FREETMPS"\fR and
+perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   SAVETMPS;
+.Ve
+.RE
+.RS 4
+.RE
+.SH Casting
+.IX Header "Casting"
+.ie n .IP """Atof""" 4
+.el .IP \f(CWAtof\fR 4
+.IX Xref "Atof"
+.IX Item "Atof"
+This is a synonym for "\f(CW\*(C`my_atof\*(C'\fR".
+.RS 4
+.Sp
+.Vb 1
+\& NV  Atof(NN const char * const s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cBOOL""" 4
+.el .IP \f(CWcBOOL\fR 4
+.IX Xref "cBOOL"
+.IX Item "cBOOL"
+Cast-to-bool.  When Perl was able to be compiled on pre\-C99 compilers, a
+\&\f(CW\*(C`(bool)\*(C'\fR cast didn't necessarily do the right thing, so this macro was
+created (and made somewhat complicated to work around bugs in old
+compilers).  Now, many years later, and C99 is used, this is no longer
+required, but is kept for backwards compatibility.
+.RS 4
+.Sp
+.Vb 1
+\& bool  cBOOL(bool expr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """INT2PTR""" 4
+.el .IP \f(CWINT2PTR\fR 4
+.IX Item "INT2PTR"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& type  INT2PTR(type, int value)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_V""" 4
+.el .IP \f(CWI_V\fR 4
+.IX Xref "I_V"
+.IX Item "I_V"
+Cast an NV to IV while avoiding undefined C behavior
+.RS 4
+.Sp
+.Vb 1
+\& IV  I_V(NV what)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_32""" 4
+.el .IP \f(CWI_32\fR 4
+.IX Xref "I_32"
+.IX Item "I_32"
+Cast an NV to I32 while avoiding undefined C behavior
+.RS 4
+.Sp
+.Vb 1
+\& I32  I_32(NV what)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTR2IV""" 4
+.el .IP \f(CWPTR2IV\fR 4
+.IX Item "PTR2IV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  PTR2IV(void * ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTR2nat""" 4
+.el .IP \f(CWPTR2nat\fR 4
+.IX Item "PTR2nat"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  PTR2nat(void *)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTR2NV""" 4
+.el .IP \f(CWPTR2NV\fR 4
+.IX Item "PTR2NV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& NV  PTR2NV(void * ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTR2ul""" 4
+.el .IP \f(CWPTR2ul\fR 4
+.IX Item "PTR2ul"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& unsigned long  PTR2ul(void *)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTR2UV""" 4
+.el .IP \f(CWPTR2UV\fR 4
+.IX Item "PTR2UV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& UV  PTR2UV(void * ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PTRV""" 4
+.el .IP \f(CWPTRV\fR 4
+.IX Item "PTRV"
+Described in perlguts.
+.ie n .IP """U_V""" 4
+.el .IP \f(CWU_V\fR 4
+.IX Xref "U_V"
+.IX Item "U_V"
+Cast an NV to UV while avoiding undefined C behavior
+.RS 4
+.Sp
+.Vb 1
+\& UV  U_V(NV what)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """U_32""" 4
+.el .IP \f(CWU_32\fR 4
+.IX Xref "U_32"
+.IX Item "U_32"
+Cast an NV to U32 while avoiding undefined C behavior
+.RS 4
+.Sp
+.Vb 1
+\& U32  U_32(NV what)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Character case changing"
+.IX Header "Character case changing"
+Perl uses "full" Unicode case mappings.  This means that converting a single
+character to another case may result in a sequence of more than one character.
+For example, the uppercase of \f(CW\*(C`ß\*(C'\fR (LATIN SMALL LETTER SHARP S) is the two
+character sequence \f(CW\*(C`SS\*(C'\fR.  This presents some complications   The lowercase of
+all characters in the range 0..255 is a single character, and thus
+\&\f(CW"toLOWER_L1"\fR is furnished.  But, \f(CW\*(C`toUPPER_L1\*(C'\fR can't exist, as it couldn't
+return a valid result for all legal inputs.  Instead \f(CW"toUPPER_uvchr"\fR has
+an API that does allow every possible legal result to be returned.)  Likewise
+no other function that is crippled by not being able to give the correct
+results for the full range of possible inputs has been implemented here.
+.ie n .IP """toFOLD""" 4
+.el .IP \f(CWtoFOLD\fR 4
+.IX Item "toFOLD"
+.PD 0
+.ie n .IP """toFOLD_A""" 4
+.el .IP \f(CWtoFOLD_A\fR 4
+.IX Item "toFOLD_A"
+.ie n .IP """toFOLD_utf8""" 4
+.el .IP \f(CWtoFOLD_utf8\fR 4
+.IX Item "toFOLD_utf8"
+.ie n .IP """toFOLD_utf8_safe""" 4
+.el .IP \f(CWtoFOLD_utf8_safe\fR 4
+.IX Item "toFOLD_utf8_safe"
+.ie n .IP """toFOLD_uvchr""" 4
+.el .IP \f(CWtoFOLD_uvchr\fR 4
+.IX Xref "toFOLD toFOLD_A toFOLD_utf8 toFOLD_utf8_safe toFOLD_uvchr"
+.IX Item "toFOLD_uvchr"
+.PD
+These all return the foldcase of a character.  "foldcase" is an internal case
+for \f(CW\*(C`/i\*(C'\fR pattern matching. If the foldcase of character A and the foldcase of
+character B are the same, they match caselessly; otherwise they don't.
+.Sp
+The differences in the forms are what domain they operate on, and whether the
+input is specified as a code point (those forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a
+UTF\-8 string (the others).  In the latter case, the code point to use is the
+first one in the buffer of UTF\-8 encoded code points, delineated by the
+arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toFOLD\*(C'\fR and \f(CW\*(C`toFOLD_A\*(C'\fR are synonyms of each other.  They return the
+foldcase of any ASCII-range code point.  In this range, the foldcase is
+identical to the lowercase.  All other inputs are returned unchanged.  Since
+these are macros, the input type may be any integral one, and the output will
+occupy the same number of bits as the input.
+.Sp
+There is no \f(CW\*(C`toFOLD_L1\*(C'\fR nor \f(CW\*(C`toFOLD_LATIN1\*(C'\fR as the foldcase of some code
+points in the 0..255 range is above that range or consists of multiple
+characters.  Instead use \f(CW\*(C`toFOLD_uvchr\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toFOLD_uvchr\*(C'\fR returns the foldcase of any Unicode code point.  The return
+value is identical to that of \f(CW\*(C`toFOLD_A\*(C'\fR for input code points in the ASCII
+range.  The foldcase of the vast majority of Unicode code points is the same
+as the code point itself.  For these, and for code points above the legal
+Unicode maximum, this returns the input code point unchanged.  It additionally
+stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
+length in bytes into \f(CW*lenp\fR.  The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
+contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
+.Sp
+NOTE: the foldcase of a code point may be more than one code point.  The
+return value of this function is only the first of these.  The entire foldcase
+is returned in \f(CW\*(C`s\*(C'\fR.  To determine if the result is more than a single code
+point, you can do something like this:
+.Sp
+.Vb 3
+\& uc = toFOLD_uvchr(cp, s, &len);
+\& if (len > UTF8SKIP(s)) { is multiple code points }
+\& else { is a single code point }
+.Ve
+.Sp
+\&\f(CW\*(C`toFOLD_utf8\*(C'\fR and \f(CW\*(C`toFOLD_utf8_safe\*(C'\fR are synonyms of each other.  The only
+difference between these and \f(CW\*(C`toFOLD_uvchr\*(C'\fR is that the source for these is
+encoded in UTF\-8, instead of being a code point.  It is passed as a buffer
+starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end.  The \f(CW\*(C`p\*(C'\fR
+buffer may certainly contain more than one code point; but only the first one
+(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined.  If the UTF\-8 for the input character is
+malformed in some way, the program may croak, or the function may return the
+REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
+change in future releases.
+.RS 4
+.Sp
+.Vb 5
+\& UV  toFOLD          (UV cp)
+\& UV  toFOLD_A        (UV cp)
+\& UV  toFOLD_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toFOLD_uvchr    (UV cp, U8* s, STRLEN* lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """toLOWER""" 4
+.el .IP \f(CWtoLOWER\fR 4
+.IX Item "toLOWER"
+.PD 0
+.ie n .IP """toLOWER_A""" 4
+.el .IP \f(CWtoLOWER_A\fR 4
+.IX Item "toLOWER_A"
+.ie n .IP """toLOWER_LATIN1""" 4
+.el .IP \f(CWtoLOWER_LATIN1\fR 4
+.IX Item "toLOWER_LATIN1"
+.ie n .IP """toLOWER_LC""" 4
+.el .IP \f(CWtoLOWER_LC\fR 4
+.IX Item "toLOWER_LC"
+.ie n .IP """toLOWER_L1""" 4
+.el .IP \f(CWtoLOWER_L1\fR 4
+.IX Item "toLOWER_L1"
+.ie n .IP """toLOWER_utf8""" 4
+.el .IP \f(CWtoLOWER_utf8\fR 4
+.IX Item "toLOWER_utf8"
+.ie n .IP """toLOWER_utf8_safe""" 4
+.el .IP \f(CWtoLOWER_utf8_safe\fR 4
+.IX Item "toLOWER_utf8_safe"
+.ie n .IP """toLOWER_uvchr""" 4
+.el .IP \f(CWtoLOWER_uvchr\fR 4
+.IX Xref "toLOWER toLOWER_A toLOWER_LATIN1 toLOWER_LC toLOWER_L1 toLOWER_utf8 toLOWER_utf8_safe toLOWER_uvchr"
+.IX Item "toLOWER_uvchr"
+.PD
+These all return the lowercase of a character.  The differences are what domain
+they operate on, and whether the input is specified as a code point (those
+forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others).  In the latter
+case, the code point to use is the first one in the buffer of UTF\-8 encoded
+code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toLOWER\*(C'\fR and \f(CW\*(C`toLOWER_A\*(C'\fR are synonyms of each other.  They return the
+lowercase of any uppercase ASCII-range code point.  All other inputs are
+returned unchanged.  Since these are macros, the input type may be any integral
+one, and the output will occupy the same number of bits as the input.
+.Sp
+\&\f(CW\*(C`toLOWER_L1\*(C'\fR and \f(CW\*(C`toLOWER_LATIN1\*(C'\fR are synonyms of each other.  They behave
+identically as \f(CW\*(C`toLOWER\*(C'\fR for ASCII-range input.  But additionally will return
+the lowercase of any uppercase code point in the entire 0..255 range, assuming
+a Latin\-1 encoding (or the EBCDIC equivalent on such platforms).
+.Sp
+\&\f(CW\*(C`toLOWER_LC\*(C'\fR returns the lowercase of the input code point according to the
+rules of the current POSIX locale.  Input code points outside the range 0..255
+are returned unchanged.
+.Sp
+\&\f(CW\*(C`toLOWER_uvchr\*(C'\fR returns the lowercase of any Unicode code point.  The return
+value is identical to that of \f(CW\*(C`toLOWER_L1\*(C'\fR for input code points in the 0..255
+range.  The lowercase of the vast majority of Unicode code points is the same
+as the code point itself.  For these, and for code points above the legal
+Unicode maximum, this returns the input code point unchanged.  It additionally
+stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
+length in bytes into \f(CW*lenp\fR.  The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
+contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
+.Sp
+NOTE: the lowercase of a code point may be more than one code point.  The
+return value of this function is only the first of these.  The entire lowercase
+is returned in \f(CW\*(C`s\*(C'\fR.  To determine if the result is more than a single code
+point, you can do something like this:
+.Sp
+.Vb 3
+\& uc = toLOWER_uvchr(cp, s, &len);
+\& if (len > UTF8SKIP(s)) { is multiple code points }
+\& else { is a single code point }
+.Ve
+.Sp
+\&\f(CW\*(C`toLOWER_utf8\*(C'\fR and \f(CW\*(C`toLOWER_utf8_safe\*(C'\fR are synonyms of each other.  The only
+difference between these and \f(CW\*(C`toLOWER_uvchr\*(C'\fR is that the source for these is
+encoded in UTF\-8, instead of being a code point.  It is passed as a buffer
+starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end.  The \f(CW\*(C`p\*(C'\fR
+buffer may certainly contain more than one code point; but only the first one
+(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined.  If the UTF\-8 for the input character is
+malformed in some way, the program may croak, or the function may return the
+REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
+change in future releases.
+.RS 4
+.Sp
+.Vb 8
+\& UV  toLOWER          (UV cp)
+\& UV  toLOWER_A        (UV cp)
+\& UV  toLOWER_LATIN1   (UV cp)
+\& UV  toLOWER_LC       (UV cp)
+\& UV  toLOWER_L1       (UV cp)
+\& UV  toLOWER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toLOWER_uvchr    (UV cp, U8* s, STRLEN* lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """toTITLE""" 4
+.el .IP \f(CWtoTITLE\fR 4
+.IX Item "toTITLE"
+.PD 0
+.ie n .IP """toTITLE_A""" 4
+.el .IP \f(CWtoTITLE_A\fR 4
+.IX Item "toTITLE_A"
+.ie n .IP """toTITLE_utf8""" 4
+.el .IP \f(CWtoTITLE_utf8\fR 4
+.IX Item "toTITLE_utf8"
+.ie n .IP """toTITLE_utf8_safe""" 4
+.el .IP \f(CWtoTITLE_utf8_safe\fR 4
+.IX Item "toTITLE_utf8_safe"
+.ie n .IP """toTITLE_uvchr""" 4
+.el .IP \f(CWtoTITLE_uvchr\fR 4
+.IX Xref "toTITLE toTITLE_A toTITLE_utf8 toTITLE_utf8_safe toTITLE_uvchr"
+.IX Item "toTITLE_uvchr"
+.PD
+These all return the titlecase of a character.  The differences are what domain
+they operate on, and whether the input is specified as a code point (those
+forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others).  In the latter
+case, the code point to use is the first one in the buffer of UTF\-8 encoded
+code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toTITLE\*(C'\fR and \f(CW\*(C`toTITLE_A\*(C'\fR are synonyms of each other.  They return the
+titlecase of any lowercase ASCII-range code point.  In this range, the
+titlecase is identical to the uppercase.  All other inputs are returned
+unchanged.  Since these are macros, the input type may be any integral one, and
+the output will occupy the same number of bits as the input.
+.Sp
+There is no \f(CW\*(C`toTITLE_L1\*(C'\fR nor \f(CW\*(C`toTITLE_LATIN1\*(C'\fR as the titlecase of some code
+points in the 0..255 range is above that range or consists of multiple
+characters.  Instead use \f(CW\*(C`toTITLE_uvchr\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toTITLE_uvchr\*(C'\fR returns the titlecase of any Unicode code point.  The return
+value is identical to that of \f(CW\*(C`toTITLE_A\*(C'\fR for input code points in the ASCII
+range.  The titlecase of the vast majority of Unicode code points is the same
+as the code point itself.  For these, and for code points above the legal
+Unicode maximum, this returns the input code point unchanged.  It additionally
+stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
+length in bytes into \f(CW*lenp\fR.  The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
+contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
+.Sp
+NOTE: the titlecase of a code point may be more than one code point.  The
+return value of this function is only the first of these.  The entire titlecase
+is returned in \f(CW\*(C`s\*(C'\fR.  To determine if the result is more than a single code
+point, you can do something like this:
+.Sp
+.Vb 3
+\& uc = toTITLE_uvchr(cp, s, &len);
+\& if (len > UTF8SKIP(s)) { is multiple code points }
+\& else { is a single code point }
+.Ve
+.Sp
+\&\f(CW\*(C`toTITLE_utf8\*(C'\fR and \f(CW\*(C`toTITLE_utf8_safe\*(C'\fR are synonyms of each other.  The only
+difference between these and \f(CW\*(C`toTITLE_uvchr\*(C'\fR is that the source for these is
+encoded in UTF\-8, instead of being a code point.  It is passed as a buffer
+starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end.  The \f(CW\*(C`p\*(C'\fR
+buffer may certainly contain more than one code point; but only the first one
+(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined.  If the UTF\-8 for the input character is
+malformed in some way, the program may croak, or the function may return the
+REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
+change in future releases.
+.RS 4
+.Sp
+.Vb 5
+\& UV  toTITLE          (UV cp)
+\& UV  toTITLE_A        (UV cp)
+\& UV  toTITLE_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toTITLE_uvchr    (UV cp, U8* s, STRLEN* lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """toUPPER""" 4
+.el .IP \f(CWtoUPPER\fR 4
+.IX Item "toUPPER"
+.PD 0
+.ie n .IP """toUPPER_A""" 4
+.el .IP \f(CWtoUPPER_A\fR 4
+.IX Item "toUPPER_A"
+.ie n .IP """toUPPER_utf8""" 4
+.el .IP \f(CWtoUPPER_utf8\fR 4
+.IX Item "toUPPER_utf8"
+.ie n .IP """toUPPER_utf8_safe""" 4
+.el .IP \f(CWtoUPPER_utf8_safe\fR 4
+.IX Item "toUPPER_utf8_safe"
+.ie n .IP """toUPPER_uvchr""" 4
+.el .IP \f(CWtoUPPER_uvchr\fR 4
+.IX Xref "toUPPER toUPPER_A toUPPER_utf8 toUPPER_utf8_safe toUPPER_uvchr"
+.IX Item "toUPPER_uvchr"
+.PD
+These all return the uppercase of a character.  The differences are what domain
+they operate on, and whether the input is specified as a code point (those
+forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others).  In the latter
+case, the code point to use is the first one in the buffer of UTF\-8 encoded
+code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toUPPER\*(C'\fR and \f(CW\*(C`toUPPER_A\*(C'\fR are synonyms of each other.  They return the
+uppercase of any lowercase ASCII-range code point.  All other inputs are
+returned unchanged.  Since these are macros, the input type may be any integral
+one, and the output will occupy the same number of bits as the input.
+.Sp
+There is no \f(CW\*(C`toUPPER_L1\*(C'\fR nor \f(CW\*(C`toUPPER_LATIN1\*(C'\fR as the uppercase of some code
+points in the 0..255 range is above that range or consists of multiple
+characters.  Instead use \f(CW\*(C`toUPPER_uvchr\*(C'\fR.
+.Sp
+\&\f(CW\*(C`toUPPER_uvchr\*(C'\fR returns the uppercase of any Unicode code point.  The return
+value is identical to that of \f(CW\*(C`toUPPER_A\*(C'\fR for input code points in the ASCII
+range.  The uppercase of the vast majority of Unicode code points is the same
+as the code point itself.  For these, and for code points above the legal
+Unicode maximum, this returns the input code point unchanged.  It additionally
+stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
+length in bytes into \f(CW*lenp\fR.  The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
+contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
+.Sp
+NOTE: the uppercase of a code point may be more than one code point.  The
+return value of this function is only the first of these.  The entire uppercase
+is returned in \f(CW\*(C`s\*(C'\fR.  To determine if the result is more than a single code
+point, you can do something like this:
+.Sp
+.Vb 3
+\& uc = toUPPER_uvchr(cp, s, &len);
+\& if (len > UTF8SKIP(s)) { is multiple code points }
+\& else { is a single code point }
+.Ve
+.Sp
+\&\f(CW\*(C`toUPPER_utf8\*(C'\fR and \f(CW\*(C`toUPPER_utf8_safe\*(C'\fR are synonyms of each other.  The only
+difference between these and \f(CW\*(C`toUPPER_uvchr\*(C'\fR is that the source for these is
+encoded in UTF\-8, instead of being a code point.  It is passed as a buffer
+starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end.  The \f(CW\*(C`p\*(C'\fR
+buffer may certainly contain more than one code point; but only the first one
+(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined.  If the UTF\-8 for the input character is
+malformed in some way, the program may croak, or the function may return the
+REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
+change in future releases.
+.RS 4
+.Sp
+.Vb 5
+\& UV  toUPPER          (UV cp)
+\& UV  toUPPER_A        (UV cp)
+\& UV  toUPPER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
+\& UV  toUPPER_uvchr    (UV cp, U8* s, STRLEN* lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Character classification"
+.IX Header "Character classification"
+This section is about functions (really macros) that classify characters
+into types, such as punctuation versus alphabetic, etc.  Most of these are
+analogous to regular expression character classes.  (See
+"POSIX Character Classes" in perlrecharclass.)  There are several variants for
+each class.  (Not all macros have all variants; each item below lists the
+ones valid for it.)  None are affected by \f(CW\*(C`use bytes\*(C'\fR, and only the ones
+with \f(CW\*(C`LC\*(C'\fR in the name are affected by the current locale.
+.PP
+The base function, e.g., \f(CWisALPHA()\fR, takes any signed or unsigned value,
+treating it as a code point, and returns a boolean as to whether or not the
+character represented by it is (or on non-ASCII platforms, corresponds to) an
+ASCII character in the named class based on platform, Unicode, and Perl rules.
+If the input is a number that doesn't fit in an octet, FALSE is returned.
+.PP
+Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR (e.g., \f(CWisALPHA_A()\fR) is identical to the base function
+with no suffix \f(CW"_A"\fR.  This variant is used to emphasize by its name that
+only ASCII-range characters can return TRUE.
+.PP
+Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR imposes the Latin\-1 (or EBCDIC equivalent) character set
+onto the platform.  That is, the code points that are ASCII are unaffected,
+since ASCII is a subset of Latin\-1.  But the non-ASCII code points are treated
+as if they are Latin\-1 characters.  For example, \f(CWisWORDCHAR_L1()\fR will return
+true when called with the code point 0xDF, which is a word character in both
+ASCII and EBCDIC (though it represents different characters in each).
+If the input is a number that doesn't fit in an octet, FALSE is returned.
+(Perl's documentation uses a colloquial definition of Latin\-1, to include all
+code points below 256.)
+.PP
+Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR is exactly like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variant, for
+inputs below 256, but if the code point is larger than 255, Unicode rules are
+used to determine if it is in the character class.  For example,
+\&\f(CWisWORDCHAR_uvchr(0x100)\fR returns TRUE, since 0x100 is LATIN CAPITAL LETTER A
+WITH MACRON in Unicode, and is a word character.
+.PP
+Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8_safe\*(C'\fR are like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR,
+but are used for UTF\-8 encoded strings.  The two forms are different names for
+the same thing.  Each call to one of these classifies the first character of
+the string starting at \f(CW\*(C`p\*(C'\fR.  The second parameter, \f(CW\*(C`e\*(C'\fR, points to anywhere in
+the string beyond the first character, up to one byte past the end of the
+entire string.  Although both variants are identical, the suffix \f(CW\*(C`_safe\*(C'\fR in
+one name emphasizes that it will not attempt to read beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR,
+provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this is asserted for in
+\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR builds).  If the UTF\-8 for the input character is malformed in
+some way, the program may croak, or the function may return FALSE, at the
+discretion of the implementation, and subject to change in future releases.
+.PP
+Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR is like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variants,
+but the result is based on the current locale, which is what \f(CW\*(C`LC\*(C'\fR in the name
+stands for.  If Perl can determine that the current locale is a UTF\-8 locale,
+it uses the published Unicode rules; otherwise, it uses the C library function
+that gives the named classification.  For example, \f(CWisDIGIT_LC()\fR when not in
+a UTF\-8 locale returns the result of calling \f(CWisdigit()\fR.  FALSE is always
+returned if the input won't fit into an octet.  On some platforms where the C
+library function is known to be defective, Perl changes its result to follow
+the POSIX standard's rules.
+.PP
+Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR acts exactly like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR for inputs less
+than 256, but for larger ones it returns the Unicode classification of the code
+point.
+.PP
+Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8_safe\*(C'\fR are like
+\&\f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR, but are used for UTF\-8 encoded strings.  The two forms
+are different names for the same thing.  Each call to one of these classifies
+the first character of the string starting at \f(CW\*(C`p\*(C'\fR.  The second parameter,
+\&\f(CW\*(C`e\*(C'\fR, points to anywhere in the string beyond the first character, up to one
+byte past the end of the entire string.  Although both variants are identical,
+the suffix \f(CW\*(C`_safe\*(C'\fR in one name emphasizes that it will not attempt to read
+beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR, provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this
+is asserted for in \f(CW\*(C`\-DDEBUGGING\*(C'\fR builds).  If the UTF\-8 for the input
+character is malformed in some way, the program may croak, or the function may
+return FALSE, at the discretion of the implementation, and subject to change in
+future releases.
+.ie n .IP """isALNUM""" 4
+.el .IP \f(CWisALNUM\fR 4
+.IX Item "isALNUM"
+.PD 0
+.ie n .IP """isALNUM_A""" 4
+.el .IP \f(CWisALNUM_A\fR 4
+.IX Item "isALNUM_A"
+.ie n .IP """isALNUM_LC""" 4
+.el .IP \f(CWisALNUM_LC\fR 4
+.IX Item "isALNUM_LC"
+.ie n .IP """isALNUM_LC_uvchr""" 4
+.el .IP \f(CWisALNUM_LC_uvchr\fR 4
+.IX Xref "isALNUM isALNUM_A isALNUM_LC isALNUM_LC_uvchr"
+.IX Item "isALNUM_LC_uvchr"
+.PD
+These are each a synonym for their respectively named "\f(CW\*(C`isWORDCHAR\*(C'\fR"
+variant.
+.Sp
+They are provided for backward compatibility, even though a word character
+includes more than the standard C language meaning of alphanumeric.
+To get the C language definition, use the corresponding "\f(CW\*(C`isALPHANUMERIC\*(C'\fR"
+variant.
+.RS 4
+.Sp
+.Vb 1
+\& bool  isALNUM(UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isALNUMC""" 4
+.el .IP \f(CWisALNUMC\fR 4
+.IX Item "isALNUMC"
+.PD 0
+.ie n .IP """isALNUMC_A""" 4
+.el .IP \f(CWisALNUMC_A\fR 4
+.IX Item "isALNUMC_A"
+.ie n .IP """isALNUMC_LC""" 4
+.el .IP \f(CWisALNUMC_LC\fR 4
+.IX Item "isALNUMC_LC"
+.ie n .IP """isALNUMC_LC_uvchr""" 4
+.el .IP \f(CWisALNUMC_LC_uvchr\fR 4
+.IX Item "isALNUMC_LC_uvchr"
+.ie n .IP """isALNUMC_L1""" 4
+.el .IP \f(CWisALNUMC_L1\fR 4
+.IX Xref "isALNUMC isALNUMC_A isALNUMC_LC isALNUMC_LC_uvchr isALNUMC_L1"
+.IX Item "isALNUMC_L1"
+.PD
+These are discouraged, backward compatibility macros for "\f(CW\*(C`isALPHANUMERIC\*(C'\fR".
+That is, each returns a boolean indicating whether the specified character is
+one of \f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
+.Sp
+The \f(CW\*(C`C\*(C'\fR suffix in the names was meant to indicate that they correspond to the
+C language \f(CWisalnum(3)\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  isALNUMC(UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isALPHA""" 4
+.el .IP \f(CWisALPHA\fR 4
+.IX Item "isALPHA"
+.PD 0
+.ie n .IP """isALPHA_A""" 4
+.el .IP \f(CWisALPHA_A\fR 4
+.IX Item "isALPHA_A"
+.ie n .IP """isALPHA_LC""" 4
+.el .IP \f(CWisALPHA_LC\fR 4
+.IX Item "isALPHA_LC"
+.ie n .IP """isALPHA_LC_utf8_safe""" 4
+.el .IP \f(CWisALPHA_LC_utf8_safe\fR 4
+.IX Item "isALPHA_LC_utf8_safe"
+.ie n .IP """isALPHA_LC_uvchr""" 4
+.el .IP \f(CWisALPHA_LC_uvchr\fR 4
+.IX Item "isALPHA_LC_uvchr"
+.ie n .IP """isALPHA_L1""" 4
+.el .IP \f(CWisALPHA_L1\fR 4
+.IX Item "isALPHA_L1"
+.ie n .IP """isALPHA_utf8""" 4
+.el .IP \f(CWisALPHA_utf8\fR 4
+.IX Item "isALPHA_utf8"
+.ie n .IP """isALPHA_utf8_safe""" 4
+.el .IP \f(CWisALPHA_utf8_safe\fR 4
+.IX Item "isALPHA_utf8_safe"
+.ie n .IP """isALPHA_uvchr""" 4
+.el .IP \f(CWisALPHA_uvchr\fR 4
+.IX Xref "isALPHA isALPHA_A isALPHA_LC isALPHA_LC_utf8_safe isALPHA_LC_uvchr isALPHA_L1 isALPHA_utf8 isALPHA_utf8_safe isALPHA_uvchr"
+.IX Item "isALPHA_uvchr"
+.PD
+Returns a boolean indicating whether the specified input is one of \f(CW\*(C`[A\-Za\-z]\*(C'\fR,
+analogous to \f(CW\*(C`m/[[:alpha:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isALPHA             (UV ch)
+\& bool  isALPHA_A           (UV ch)
+\& bool  isALPHA_LC          (UV ch)
+\& bool  isALPHA_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isALPHA_LC_uvchr    (UV ch)
+\& bool  isALPHA_L1          (UV ch)
+\& bool  isALPHA_utf8        (U8 * s, U8 * end)
+\& bool  isALPHA_utf8_safe   (U8 * s, U8 * end)
+\& bool  isALPHA_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isALPHANUMERIC""" 4
+.el .IP \f(CWisALPHANUMERIC\fR 4
+.IX Item "isALPHANUMERIC"
+.PD 0
+.ie n .IP """isALPHANUMERIC_A""" 4
+.el .IP \f(CWisALPHANUMERIC_A\fR 4
+.IX Item "isALPHANUMERIC_A"
+.ie n .IP """isALPHANUMERIC_LC""" 4
+.el .IP \f(CWisALPHANUMERIC_LC\fR 4
+.IX Item "isALPHANUMERIC_LC"
+.ie n .IP """isALPHANUMERIC_LC_utf8_safe""" 4
+.el .IP \f(CWisALPHANUMERIC_LC_utf8_safe\fR 4
+.IX Item "isALPHANUMERIC_LC_utf8_safe"
+.ie n .IP """isALPHANUMERIC_LC_uvchr""" 4
+.el .IP \f(CWisALPHANUMERIC_LC_uvchr\fR 4
+.IX Item "isALPHANUMERIC_LC_uvchr"
+.ie n .IP """isALPHANUMERIC_L1""" 4
+.el .IP \f(CWisALPHANUMERIC_L1\fR 4
+.IX Item "isALPHANUMERIC_L1"
+.ie n .IP """isALPHANUMERIC_utf8""" 4
+.el .IP \f(CWisALPHANUMERIC_utf8\fR 4
+.IX Item "isALPHANUMERIC_utf8"
+.ie n .IP """isALPHANUMERIC_utf8_safe""" 4
+.el .IP \f(CWisALPHANUMERIC_utf8_safe\fR 4
+.IX Item "isALPHANUMERIC_utf8_safe"
+.ie n .IP """isALPHANUMERIC_uvchr""" 4
+.el .IP \f(CWisALPHANUMERIC_uvchr\fR 4
+.IX Xref "isALPHANUMERIC isALPHANUMERIC_A isALPHANUMERIC_LC isALPHANUMERIC_LC_utf8_safe isALPHANUMERIC_LC_uvchr isALPHANUMERIC_L1 isALPHANUMERIC_utf8 isALPHANUMERIC_utf8_safe isALPHANUMERIC_uvchr"
+.IX Item "isALPHANUMERIC_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is one of
+\&\f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isALPHANUMERIC             (UV ch)
+\& bool  isALPHANUMERIC_A           (UV ch)
+\& bool  isALPHANUMERIC_LC          (UV ch)
+\& bool  isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isALPHANUMERIC_LC_uvchr    (UV ch)
+\& bool  isALPHANUMERIC_L1          (UV ch)
+\& bool  isALPHANUMERIC_utf8        (U8 * s, U8 * end)
+\& bool  isALPHANUMERIC_utf8_safe   (U8 * s, U8 * end)
+\& bool  isALPHANUMERIC_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isASCII""" 4
+.el .IP \f(CWisASCII\fR 4
+.IX Item "isASCII"
+.PD 0
+.ie n .IP """isASCII_A""" 4
+.el .IP \f(CWisASCII_A\fR 4
+.IX Item "isASCII_A"
+.ie n .IP """isASCII_LC""" 4
+.el .IP \f(CWisASCII_LC\fR 4
+.IX Item "isASCII_LC"
+.ie n .IP """isASCII_LC_utf8_safe""" 4
+.el .IP \f(CWisASCII_LC_utf8_safe\fR 4
+.IX Item "isASCII_LC_utf8_safe"
+.ie n .IP """isASCII_LC_uvchr""" 4
+.el .IP \f(CWisASCII_LC_uvchr\fR 4
+.IX Item "isASCII_LC_uvchr"
+.ie n .IP """isASCII_L1""" 4
+.el .IP \f(CWisASCII_L1\fR 4
+.IX Item "isASCII_L1"
+.ie n .IP """isASCII_utf8""" 4
+.el .IP \f(CWisASCII_utf8\fR 4
+.IX Item "isASCII_utf8"
+.ie n .IP """isASCII_utf8_safe""" 4
+.el .IP \f(CWisASCII_utf8_safe\fR 4
+.IX Item "isASCII_utf8_safe"
+.ie n .IP """isASCII_uvchr""" 4
+.el .IP \f(CWisASCII_uvchr\fR 4
+.IX Xref "isASCII isASCII_A isASCII_LC isASCII_LC_utf8_safe isASCII_LC_uvchr isASCII_L1 isASCII_utf8 isASCII_utf8_safe isASCII_uvchr"
+.IX Item "isASCII_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is one of the 128
+characters in the ASCII character set, analogous to \f(CW\*(C`m/[[:ascii:]]/\*(C'\fR.
+On non-ASCII platforms, it returns TRUE iff this
+character corresponds to an ASCII character.  Variants \f(CWisASCII_A()\fR and
+\&\f(CWisASCII_L1()\fR are identical to \f(CWisASCII()\fR.
+See the top of this section for an explanation of
+the variants.
+Note, however, that some platforms do not have the C library routine
+\&\f(CWisascii()\fR.  In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are the
+same as the corresponding ones without.
+.Sp
+Also note, that because all ASCII characters are UTF\-8 invariant (meaning they
+have the exact same representation (always a single byte) whether encoded in
+UTF\-8 or not), \f(CW\*(C`isASCII\*(C'\fR will give the correct results when called with any
+byte in any string encoded or not in UTF\-8.  And similarly \f(CW\*(C`isASCII_utf8\*(C'\fR and
+\&\f(CW\*(C`isASCII_utf8_safe\*(C'\fR will work properly on any string encoded or not in UTF\-8.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isASCII             (UV ch)
+\& bool  isASCII_A           (UV ch)
+\& bool  isASCII_LC          (UV ch)
+\& bool  isASCII_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isASCII_LC_uvchr    (UV ch)
+\& bool  isASCII_L1          (UV ch)
+\& bool  isASCII_utf8        (U8 * s, U8 * end)
+\& bool  isASCII_utf8_safe   (U8 * s, U8 * end)
+\& bool  isASCII_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isBLANK""" 4
+.el .IP \f(CWisBLANK\fR 4
+.IX Item "isBLANK"
+.PD 0
+.ie n .IP """isBLANK_A""" 4
+.el .IP \f(CWisBLANK_A\fR 4
+.IX Item "isBLANK_A"
+.ie n .IP """isBLANK_LC""" 4
+.el .IP \f(CWisBLANK_LC\fR 4
+.IX Item "isBLANK_LC"
+.ie n .IP """isBLANK_LC_utf8_safe""" 4
+.el .IP \f(CWisBLANK_LC_utf8_safe\fR 4
+.IX Item "isBLANK_LC_utf8_safe"
+.ie n .IP """isBLANK_LC_uvchr""" 4
+.el .IP \f(CWisBLANK_LC_uvchr\fR 4
+.IX Item "isBLANK_LC_uvchr"
+.ie n .IP """isBLANK_L1""" 4
+.el .IP \f(CWisBLANK_L1\fR 4
+.IX Item "isBLANK_L1"
+.ie n .IP """isBLANK_utf8""" 4
+.el .IP \f(CWisBLANK_utf8\fR 4
+.IX Item "isBLANK_utf8"
+.ie n .IP """isBLANK_utf8_safe""" 4
+.el .IP \f(CWisBLANK_utf8_safe\fR 4
+.IX Item "isBLANK_utf8_safe"
+.ie n .IP """isBLANK_uvchr""" 4
+.el .IP \f(CWisBLANK_uvchr\fR 4
+.IX Xref "isBLANK isBLANK_A isBLANK_LC isBLANK_LC_utf8_safe isBLANK_LC_uvchr isBLANK_L1 isBLANK_utf8 isBLANK_utf8_safe isBLANK_uvchr"
+.IX Item "isBLANK_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+character considered to be a blank, analogous to \f(CW\*(C`m/[[:blank:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+Note,
+however, that some platforms do not have the C library routine
+\&\f(CWisblank()\fR.  In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are
+the same as the corresponding ones without.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isBLANK             (UV ch)
+\& bool  isBLANK_A           (UV ch)
+\& bool  isBLANK_LC          (UV ch)
+\& bool  isBLANK_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isBLANK_LC_uvchr    (UV ch)
+\& bool  isBLANK_L1          (UV ch)
+\& bool  isBLANK_utf8        (U8 * s, U8 * end)
+\& bool  isBLANK_utf8_safe   (U8 * s, U8 * end)
+\& bool  isBLANK_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isCNTRL""" 4
+.el .IP \f(CWisCNTRL\fR 4
+.IX Item "isCNTRL"
+.PD 0
+.ie n .IP """isCNTRL_A""" 4
+.el .IP \f(CWisCNTRL_A\fR 4
+.IX Item "isCNTRL_A"
+.ie n .IP """isCNTRL_LC""" 4
+.el .IP \f(CWisCNTRL_LC\fR 4
+.IX Item "isCNTRL_LC"
+.ie n .IP """isCNTRL_LC_utf8_safe""" 4
+.el .IP \f(CWisCNTRL_LC_utf8_safe\fR 4
+.IX Item "isCNTRL_LC_utf8_safe"
+.ie n .IP """isCNTRL_LC_uvchr""" 4
+.el .IP \f(CWisCNTRL_LC_uvchr\fR 4
+.IX Item "isCNTRL_LC_uvchr"
+.ie n .IP """isCNTRL_L1""" 4
+.el .IP \f(CWisCNTRL_L1\fR 4
+.IX Item "isCNTRL_L1"
+.ie n .IP """isCNTRL_utf8""" 4
+.el .IP \f(CWisCNTRL_utf8\fR 4
+.IX Item "isCNTRL_utf8"
+.ie n .IP """isCNTRL_utf8_safe""" 4
+.el .IP \f(CWisCNTRL_utf8_safe\fR 4
+.IX Item "isCNTRL_utf8_safe"
+.ie n .IP """isCNTRL_uvchr""" 4
+.el .IP \f(CWisCNTRL_uvchr\fR 4
+.IX Xref "isCNTRL isCNTRL_A isCNTRL_LC isCNTRL_LC_utf8_safe isCNTRL_LC_uvchr isCNTRL_L1 isCNTRL_utf8 isCNTRL_utf8_safe isCNTRL_uvchr"
+.IX Item "isCNTRL_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+control character, analogous to \f(CW\*(C`m/[[:cntrl:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+On EBCDIC platforms, you almost always want to use the \f(CW\*(C`isCNTRL_L1\*(C'\fR variant.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isCNTRL             (UV ch)
+\& bool  isCNTRL_A           (UV ch)
+\& bool  isCNTRL_LC          (UV ch)
+\& bool  isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isCNTRL_LC_uvchr    (UV ch)
+\& bool  isCNTRL_L1          (UV ch)
+\& bool  isCNTRL_utf8        (U8 * s, U8 * end)
+\& bool  isCNTRL_utf8_safe   (U8 * s, U8 * end)
+\& bool  isCNTRL_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isDIGIT""" 4
+.el .IP \f(CWisDIGIT\fR 4
+.IX Item "isDIGIT"
+.PD 0
+.ie n .IP """isDIGIT_A""" 4
+.el .IP \f(CWisDIGIT_A\fR 4
+.IX Item "isDIGIT_A"
+.ie n .IP """isDIGIT_LC""" 4
+.el .IP \f(CWisDIGIT_LC\fR 4
+.IX Item "isDIGIT_LC"
+.ie n .IP """isDIGIT_LC_utf8_safe""" 4
+.el .IP \f(CWisDIGIT_LC_utf8_safe\fR 4
+.IX Item "isDIGIT_LC_utf8_safe"
+.ie n .IP """isDIGIT_LC_uvchr""" 4
+.el .IP \f(CWisDIGIT_LC_uvchr\fR 4
+.IX Item "isDIGIT_LC_uvchr"
+.ie n .IP """isDIGIT_L1""" 4
+.el .IP \f(CWisDIGIT_L1\fR 4
+.IX Item "isDIGIT_L1"
+.ie n .IP """isDIGIT_utf8""" 4
+.el .IP \f(CWisDIGIT_utf8\fR 4
+.IX Item "isDIGIT_utf8"
+.ie n .IP """isDIGIT_utf8_safe""" 4
+.el .IP \f(CWisDIGIT_utf8_safe\fR 4
+.IX Item "isDIGIT_utf8_safe"
+.ie n .IP """isDIGIT_uvchr""" 4
+.el .IP \f(CWisDIGIT_uvchr\fR 4
+.IX Xref "isDIGIT isDIGIT_A isDIGIT_LC isDIGIT_LC_utf8_safe isDIGIT_LC_uvchr isDIGIT_L1 isDIGIT_utf8 isDIGIT_utf8_safe isDIGIT_uvchr"
+.IX Item "isDIGIT_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+digit, analogous to \f(CW\*(C`m/[[:digit:]]/\*(C'\fR.
+Variants \f(CW\*(C`isDIGIT_A\*(C'\fR and \f(CW\*(C`isDIGIT_L1\*(C'\fR are identical to \f(CW\*(C`isDIGIT\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isDIGIT             (UV ch)
+\& bool  isDIGIT_A           (UV ch)
+\& bool  isDIGIT_LC          (UV ch)
+\& bool  isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isDIGIT_LC_uvchr    (UV ch)
+\& bool  isDIGIT_L1          (UV ch)
+\& bool  isDIGIT_utf8        (U8 * s, U8 * end)
+\& bool  isDIGIT_utf8_safe   (U8 * s, U8 * end)
+\& bool  isDIGIT_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isGRAPH""" 4
+.el .IP \f(CWisGRAPH\fR 4
+.IX Item "isGRAPH"
+.PD 0
+.ie n .IP """isGRAPH_A""" 4
+.el .IP \f(CWisGRAPH_A\fR 4
+.IX Item "isGRAPH_A"
+.ie n .IP """isGRAPH_LC""" 4
+.el .IP \f(CWisGRAPH_LC\fR 4
+.IX Item "isGRAPH_LC"
+.ie n .IP """isGRAPH_LC_utf8_safe""" 4
+.el .IP \f(CWisGRAPH_LC_utf8_safe\fR 4
+.IX Item "isGRAPH_LC_utf8_safe"
+.ie n .IP """isGRAPH_LC_uvchr""" 4
+.el .IP \f(CWisGRAPH_LC_uvchr\fR 4
+.IX Item "isGRAPH_LC_uvchr"
+.ie n .IP """isGRAPH_L1""" 4
+.el .IP \f(CWisGRAPH_L1\fR 4
+.IX Item "isGRAPH_L1"
+.ie n .IP """isGRAPH_utf8""" 4
+.el .IP \f(CWisGRAPH_utf8\fR 4
+.IX Item "isGRAPH_utf8"
+.ie n .IP """isGRAPH_utf8_safe""" 4
+.el .IP \f(CWisGRAPH_utf8_safe\fR 4
+.IX Item "isGRAPH_utf8_safe"
+.ie n .IP """isGRAPH_uvchr""" 4
+.el .IP \f(CWisGRAPH_uvchr\fR 4
+.IX Xref "isGRAPH isGRAPH_A isGRAPH_LC isGRAPH_LC_utf8_safe isGRAPH_LC_uvchr isGRAPH_L1 isGRAPH_utf8 isGRAPH_utf8_safe isGRAPH_uvchr"
+.IX Item "isGRAPH_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+graphic character, analogous to \f(CW\*(C`m/[[:graph:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isGRAPH             (UV ch)
+\& bool  isGRAPH_A           (UV ch)
+\& bool  isGRAPH_LC          (UV ch)
+\& bool  isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isGRAPH_LC_uvchr    (UV ch)
+\& bool  isGRAPH_L1          (UV ch)
+\& bool  isGRAPH_utf8        (U8 * s, U8 * end)
+\& bool  isGRAPH_utf8_safe   (U8 * s, U8 * end)
+\& bool  isGRAPH_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isIDCONT""" 4
+.el .IP \f(CWisIDCONT\fR 4
+.IX Item "isIDCONT"
+.PD 0
+.ie n .IP """isIDCONT_A""" 4
+.el .IP \f(CWisIDCONT_A\fR 4
+.IX Item "isIDCONT_A"
+.ie n .IP """isIDCONT_LC""" 4
+.el .IP \f(CWisIDCONT_LC\fR 4
+.IX Item "isIDCONT_LC"
+.ie n .IP """isIDCONT_LC_utf8_safe""" 4
+.el .IP \f(CWisIDCONT_LC_utf8_safe\fR 4
+.IX Item "isIDCONT_LC_utf8_safe"
+.ie n .IP """isIDCONT_LC_uvchr""" 4
+.el .IP \f(CWisIDCONT_LC_uvchr\fR 4
+.IX Item "isIDCONT_LC_uvchr"
+.ie n .IP """isIDCONT_L1""" 4
+.el .IP \f(CWisIDCONT_L1\fR 4
+.IX Item "isIDCONT_L1"
+.ie n .IP """isIDCONT_utf8""" 4
+.el .IP \f(CWisIDCONT_utf8\fR 4
+.IX Item "isIDCONT_utf8"
+.ie n .IP """isIDCONT_utf8_safe""" 4
+.el .IP \f(CWisIDCONT_utf8_safe\fR 4
+.IX Item "isIDCONT_utf8_safe"
+.ie n .IP """isIDCONT_uvchr""" 4
+.el .IP \f(CWisIDCONT_uvchr\fR 4
+.IX Xref "isIDCONT isIDCONT_A isIDCONT_LC isIDCONT_LC_utf8_safe isIDCONT_LC_uvchr isIDCONT_L1 isIDCONT_utf8 isIDCONT_utf8_safe isIDCONT_uvchr"
+.IX Item "isIDCONT_uvchr"
+.PD
+Returns a boolean indicating whether the specified character can be the
+second or succeeding character of an identifier.  This is very close to, but
+not quite the same as the official Unicode property \f(CW\*(C`XID_Continue\*(C'\fR.  The
+difference is that this returns true only if the input character also matches
+"isWORDCHAR".  See the top of this section for
+an explanation of the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isIDCONT             (UV ch)
+\& bool  isIDCONT_A           (UV ch)
+\& bool  isIDCONT_LC          (UV ch)
+\& bool  isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isIDCONT_LC_uvchr    (UV ch)
+\& bool  isIDCONT_L1          (UV ch)
+\& bool  isIDCONT_utf8        (U8 * s, U8 * end)
+\& bool  isIDCONT_utf8_safe   (U8 * s, U8 * end)
+\& bool  isIDCONT_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isIDFIRST""" 4
+.el .IP \f(CWisIDFIRST\fR 4
+.IX Item "isIDFIRST"
+.PD 0
+.ie n .IP """isIDFIRST_A""" 4
+.el .IP \f(CWisIDFIRST_A\fR 4
+.IX Item "isIDFIRST_A"
+.ie n .IP """isIDFIRST_LC""" 4
+.el .IP \f(CWisIDFIRST_LC\fR 4
+.IX Item "isIDFIRST_LC"
+.ie n .IP """isIDFIRST_LC_utf8_safe""" 4
+.el .IP \f(CWisIDFIRST_LC_utf8_safe\fR 4
+.IX Item "isIDFIRST_LC_utf8_safe"
+.ie n .IP """isIDFIRST_LC_uvchr""" 4
+.el .IP \f(CWisIDFIRST_LC_uvchr\fR 4
+.IX Item "isIDFIRST_LC_uvchr"
+.ie n .IP """isIDFIRST_L1""" 4
+.el .IP \f(CWisIDFIRST_L1\fR 4
+.IX Item "isIDFIRST_L1"
+.ie n .IP """isIDFIRST_utf8""" 4
+.el .IP \f(CWisIDFIRST_utf8\fR 4
+.IX Item "isIDFIRST_utf8"
+.ie n .IP """isIDFIRST_utf8_safe""" 4
+.el .IP \f(CWisIDFIRST_utf8_safe\fR 4
+.IX Item "isIDFIRST_utf8_safe"
+.ie n .IP """isIDFIRST_uvchr""" 4
+.el .IP \f(CWisIDFIRST_uvchr\fR 4
+.IX Xref "isIDFIRST isIDFIRST_A isIDFIRST_LC isIDFIRST_LC_utf8_safe isIDFIRST_LC_uvchr isIDFIRST_L1 isIDFIRST_utf8 isIDFIRST_utf8_safe isIDFIRST_uvchr"
+.IX Item "isIDFIRST_uvchr"
+.PD
+Returns a boolean indicating whether the specified character can be the first
+character of an identifier.  This is very close to, but not quite the same as
+the official Unicode property \f(CW\*(C`XID_Start\*(C'\fR.  The difference is that this
+returns true only if the input character also matches "isWORDCHAR".
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isIDFIRST             (UV ch)
+\& bool  isIDFIRST_A           (UV ch)
+\& bool  isIDFIRST_LC          (UV ch)
+\& bool  isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isIDFIRST_LC_uvchr    (UV ch)
+\& bool  isIDFIRST_L1          (UV ch)
+\& bool  isIDFIRST_utf8        (U8 * s, U8 * end)
+\& bool  isIDFIRST_utf8_safe   (U8 * s, U8 * end)
+\& bool  isIDFIRST_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isLOWER""" 4
+.el .IP \f(CWisLOWER\fR 4
+.IX Item "isLOWER"
+.PD 0
+.ie n .IP """isLOWER_A""" 4
+.el .IP \f(CWisLOWER_A\fR 4
+.IX Item "isLOWER_A"
+.ie n .IP """isLOWER_LC""" 4
+.el .IP \f(CWisLOWER_LC\fR 4
+.IX Item "isLOWER_LC"
+.ie n .IP """isLOWER_LC_utf8_safe""" 4
+.el .IP \f(CWisLOWER_LC_utf8_safe\fR 4
+.IX Item "isLOWER_LC_utf8_safe"
+.ie n .IP """isLOWER_LC_uvchr""" 4
+.el .IP \f(CWisLOWER_LC_uvchr\fR 4
+.IX Item "isLOWER_LC_uvchr"
+.ie n .IP """isLOWER_L1""" 4
+.el .IP \f(CWisLOWER_L1\fR 4
+.IX Item "isLOWER_L1"
+.ie n .IP """isLOWER_utf8""" 4
+.el .IP \f(CWisLOWER_utf8\fR 4
+.IX Item "isLOWER_utf8"
+.ie n .IP """isLOWER_utf8_safe""" 4
+.el .IP \f(CWisLOWER_utf8_safe\fR 4
+.IX Item "isLOWER_utf8_safe"
+.ie n .IP """isLOWER_uvchr""" 4
+.el .IP \f(CWisLOWER_uvchr\fR 4
+.IX Xref "isLOWER isLOWER_A isLOWER_LC isLOWER_LC_utf8_safe isLOWER_LC_uvchr isLOWER_L1 isLOWER_utf8 isLOWER_utf8_safe isLOWER_uvchr"
+.IX Item "isLOWER_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+lowercase character, analogous to \f(CW\*(C`m/[[:lower:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants
+.RS 4
+.Sp
+.Vb 9
+\& bool  isLOWER             (UV ch)
+\& bool  isLOWER_A           (UV ch)
+\& bool  isLOWER_LC          (UV ch)
+\& bool  isLOWER_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isLOWER_LC_uvchr    (UV ch)
+\& bool  isLOWER_L1          (UV ch)
+\& bool  isLOWER_utf8        (U8 * s, U8 * end)
+\& bool  isLOWER_utf8_safe   (U8 * s, U8 * end)
+\& bool  isLOWER_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isOCTAL""" 4
+.el .IP \f(CWisOCTAL\fR 4
+.IX Item "isOCTAL"
+.PD 0
+.ie n .IP """isOCTAL_A""" 4
+.el .IP \f(CWisOCTAL_A\fR 4
+.IX Item "isOCTAL_A"
+.ie n .IP """isOCTAL_L1""" 4
+.el .IP \f(CWisOCTAL_L1\fR 4
+.IX Xref "isOCTAL isOCTAL_A isOCTAL_L1"
+.IX Item "isOCTAL_L1"
+.PD
+Returns a boolean indicating whether the specified character is an
+octal digit, [0\-7].
+The only two variants are \f(CW\*(C`isOCTAL_A\*(C'\fR and \f(CW\*(C`isOCTAL_L1\*(C'\fR; each is identical to
+\&\f(CW\*(C`isOCTAL\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  isOCTAL(UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isPRINT""" 4
+.el .IP \f(CWisPRINT\fR 4
+.IX Item "isPRINT"
+.PD 0
+.ie n .IP """isPRINT_A""" 4
+.el .IP \f(CWisPRINT_A\fR 4
+.IX Item "isPRINT_A"
+.ie n .IP """isPRINT_LC""" 4
+.el .IP \f(CWisPRINT_LC\fR 4
+.IX Item "isPRINT_LC"
+.ie n .IP """isPRINT_LC_utf8_safe""" 4
+.el .IP \f(CWisPRINT_LC_utf8_safe\fR 4
+.IX Item "isPRINT_LC_utf8_safe"
+.ie n .IP """isPRINT_LC_uvchr""" 4
+.el .IP \f(CWisPRINT_LC_uvchr\fR 4
+.IX Item "isPRINT_LC_uvchr"
+.ie n .IP """isPRINT_L1""" 4
+.el .IP \f(CWisPRINT_L1\fR 4
+.IX Item "isPRINT_L1"
+.ie n .IP """isPRINT_utf8""" 4
+.el .IP \f(CWisPRINT_utf8\fR 4
+.IX Item "isPRINT_utf8"
+.ie n .IP """isPRINT_utf8_safe""" 4
+.el .IP \f(CWisPRINT_utf8_safe\fR 4
+.IX Item "isPRINT_utf8_safe"
+.ie n .IP """isPRINT_uvchr""" 4
+.el .IP \f(CWisPRINT_uvchr\fR 4
+.IX Xref "isPRINT isPRINT_A isPRINT_LC isPRINT_LC_utf8_safe isPRINT_LC_uvchr isPRINT_L1 isPRINT_utf8 isPRINT_utf8_safe isPRINT_uvchr"
+.IX Item "isPRINT_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+printable character, analogous to \f(CW\*(C`m/[[:print:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isPRINT             (UV ch)
+\& bool  isPRINT_A           (UV ch)
+\& bool  isPRINT_LC          (UV ch)
+\& bool  isPRINT_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isPRINT_LC_uvchr    (UV ch)
+\& bool  isPRINT_L1          (UV ch)
+\& bool  isPRINT_utf8        (U8 * s, U8 * end)
+\& bool  isPRINT_utf8_safe   (U8 * s, U8 * end)
+\& bool  isPRINT_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isPSXSPC""" 4
+.el .IP \f(CWisPSXSPC\fR 4
+.IX Item "isPSXSPC"
+.PD 0
+.ie n .IP """isPSXSPC_A""" 4
+.el .IP \f(CWisPSXSPC_A\fR 4
+.IX Item "isPSXSPC_A"
+.ie n .IP """isPSXSPC_LC""" 4
+.el .IP \f(CWisPSXSPC_LC\fR 4
+.IX Item "isPSXSPC_LC"
+.ie n .IP """isPSXSPC_LC_utf8_safe""" 4
+.el .IP \f(CWisPSXSPC_LC_utf8_safe\fR 4
+.IX Item "isPSXSPC_LC_utf8_safe"
+.ie n .IP """isPSXSPC_LC_uvchr""" 4
+.el .IP \f(CWisPSXSPC_LC_uvchr\fR 4
+.IX Item "isPSXSPC_LC_uvchr"
+.ie n .IP """isPSXSPC_L1""" 4
+.el .IP \f(CWisPSXSPC_L1\fR 4
+.IX Item "isPSXSPC_L1"
+.ie n .IP """isPSXSPC_utf8""" 4
+.el .IP \f(CWisPSXSPC_utf8\fR 4
+.IX Item "isPSXSPC_utf8"
+.ie n .IP """isPSXSPC_utf8_safe""" 4
+.el .IP \f(CWisPSXSPC_utf8_safe\fR 4
+.IX Item "isPSXSPC_utf8_safe"
+.ie n .IP """isPSXSPC_uvchr""" 4
+.el .IP \f(CWisPSXSPC_uvchr\fR 4
+.IX Xref "isPSXSPC isPSXSPC_A isPSXSPC_LC isPSXSPC_LC_utf8_safe isPSXSPC_LC_uvchr isPSXSPC_L1 isPSXSPC_utf8 isPSXSPC_utf8_safe isPSXSPC_uvchr"
+.IX Item "isPSXSPC_uvchr"
+.PD
+(short for Posix Space)
+Starting in 5.18, this is identical in all its forms to the
+corresponding \f(CWisSPACE()\fR macros.
+The locale forms of this macro are identical to their corresponding
+\&\f(CWisSPACE()\fR forms in all Perl releases.  In releases prior to 5.18, the
+non-locale forms differ from their \f(CWisSPACE()\fR forms only in that the
+\&\f(CWisSPACE()\fR forms don't match a Vertical Tab, and the \f(CWisPSXSPC()\fR forms do.
+Otherwise they are identical.  Thus this macro is analogous to what
+\&\f(CW\*(C`m/[[:space:]]/\*(C'\fR matches in a regular expression.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isPSXSPC             (UV ch)
+\& bool  isPSXSPC_A           (UV ch)
+\& bool  isPSXSPC_LC          (UV ch)
+\& bool  isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isPSXSPC_LC_uvchr    (UV ch)
+\& bool  isPSXSPC_L1          (UV ch)
+\& bool  isPSXSPC_utf8        (U8 * s, U8 * end)
+\& bool  isPSXSPC_utf8_safe   (U8 * s, U8 * end)
+\& bool  isPSXSPC_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isPUNCT""" 4
+.el .IP \f(CWisPUNCT\fR 4
+.IX Item "isPUNCT"
+.PD 0
+.ie n .IP """isPUNCT_A""" 4
+.el .IP \f(CWisPUNCT_A\fR 4
+.IX Item "isPUNCT_A"
+.ie n .IP """isPUNCT_LC""" 4
+.el .IP \f(CWisPUNCT_LC\fR 4
+.IX Item "isPUNCT_LC"
+.ie n .IP """isPUNCT_LC_utf8_safe""" 4
+.el .IP \f(CWisPUNCT_LC_utf8_safe\fR 4
+.IX Item "isPUNCT_LC_utf8_safe"
+.ie n .IP """isPUNCT_LC_uvchr""" 4
+.el .IP \f(CWisPUNCT_LC_uvchr\fR 4
+.IX Item "isPUNCT_LC_uvchr"
+.ie n .IP """isPUNCT_L1""" 4
+.el .IP \f(CWisPUNCT_L1\fR 4
+.IX Item "isPUNCT_L1"
+.ie n .IP """isPUNCT_utf8""" 4
+.el .IP \f(CWisPUNCT_utf8\fR 4
+.IX Item "isPUNCT_utf8"
+.ie n .IP """isPUNCT_utf8_safe""" 4
+.el .IP \f(CWisPUNCT_utf8_safe\fR 4
+.IX Item "isPUNCT_utf8_safe"
+.ie n .IP """isPUNCT_uvchr""" 4
+.el .IP \f(CWisPUNCT_uvchr\fR 4
+.IX Xref "isPUNCT isPUNCT_A isPUNCT_LC isPUNCT_LC_utf8_safe isPUNCT_LC_uvchr isPUNCT_L1 isPUNCT_utf8 isPUNCT_utf8_safe isPUNCT_uvchr"
+.IX Item "isPUNCT_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+punctuation character, analogous to \f(CW\*(C`m/[[:punct:]]/\*(C'\fR.
+Note that the definition of what is punctuation isn't as
+straightforward as one might desire.  See "POSIX Character
+Classes" in perlrecharclass for details.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isPUNCT             (UV ch)
+\& bool  isPUNCT_A           (UV ch)
+\& bool  isPUNCT_LC          (UV ch)
+\& bool  isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isPUNCT_LC_uvchr    (UV ch)
+\& bool  isPUNCT_L1          (UV ch)
+\& bool  isPUNCT_utf8        (U8 * s, U8 * end)
+\& bool  isPUNCT_utf8_safe   (U8 * s, U8 * end)
+\& bool  isPUNCT_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isSPACE""" 4
+.el .IP \f(CWisSPACE\fR 4
+.IX Item "isSPACE"
+.PD 0
+.ie n .IP """isSPACE_A""" 4
+.el .IP \f(CWisSPACE_A\fR 4
+.IX Item "isSPACE_A"
+.ie n .IP """isSPACE_LC""" 4
+.el .IP \f(CWisSPACE_LC\fR 4
+.IX Item "isSPACE_LC"
+.ie n .IP """isSPACE_LC_utf8_safe""" 4
+.el .IP \f(CWisSPACE_LC_utf8_safe\fR 4
+.IX Item "isSPACE_LC_utf8_safe"
+.ie n .IP """isSPACE_LC_uvchr""" 4
+.el .IP \f(CWisSPACE_LC_uvchr\fR 4
+.IX Item "isSPACE_LC_uvchr"
+.ie n .IP """isSPACE_L1""" 4
+.el .IP \f(CWisSPACE_L1\fR 4
+.IX Item "isSPACE_L1"
+.ie n .IP """isSPACE_utf8""" 4
+.el .IP \f(CWisSPACE_utf8\fR 4
+.IX Item "isSPACE_utf8"
+.ie n .IP """isSPACE_utf8_safe""" 4
+.el .IP \f(CWisSPACE_utf8_safe\fR 4
+.IX Item "isSPACE_utf8_safe"
+.ie n .IP """isSPACE_uvchr""" 4
+.el .IP \f(CWisSPACE_uvchr\fR 4
+.IX Xref "isSPACE isSPACE_A isSPACE_LC isSPACE_LC_utf8_safe isSPACE_LC_uvchr isSPACE_L1 isSPACE_utf8 isSPACE_utf8_safe isSPACE_uvchr"
+.IX Item "isSPACE_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a
+whitespace character.  This is analogous
+to what \f(CW\*(C`m/\es/\*(C'\fR matches in a regular expression.  Starting in Perl 5.18
+this also matches what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does.  Prior to 5.18, only the
+locale forms of this macro (the ones with \f(CW\*(C`LC\*(C'\fR in their names) matched
+precisely what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does.  In those releases, the only difference,
+in the non-locale variants, was that \f(CWisSPACE()\fR did not match a vertical tab.
+(See "isPSXSPC" for a macro that matches a vertical tab in all releases.)
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isSPACE             (UV ch)
+\& bool  isSPACE_A           (UV ch)
+\& bool  isSPACE_LC          (UV ch)
+\& bool  isSPACE_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isSPACE_LC_uvchr    (UV ch)
+\& bool  isSPACE_L1          (UV ch)
+\& bool  isSPACE_utf8        (U8 * s, U8 * end)
+\& bool  isSPACE_utf8_safe   (U8 * s, U8 * end)
+\& bool  isSPACE_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isUPPER""" 4
+.el .IP \f(CWisUPPER\fR 4
+.IX Item "isUPPER"
+.PD 0
+.ie n .IP """isUPPER_A""" 4
+.el .IP \f(CWisUPPER_A\fR 4
+.IX Item "isUPPER_A"
+.ie n .IP """isUPPER_LC""" 4
+.el .IP \f(CWisUPPER_LC\fR 4
+.IX Item "isUPPER_LC"
+.ie n .IP """isUPPER_LC_utf8_safe""" 4
+.el .IP \f(CWisUPPER_LC_utf8_safe\fR 4
+.IX Item "isUPPER_LC_utf8_safe"
+.ie n .IP """isUPPER_LC_uvchr""" 4
+.el .IP \f(CWisUPPER_LC_uvchr\fR 4
+.IX Item "isUPPER_LC_uvchr"
+.ie n .IP """isUPPER_L1""" 4
+.el .IP \f(CWisUPPER_L1\fR 4
+.IX Item "isUPPER_L1"
+.ie n .IP """isUPPER_utf8""" 4
+.el .IP \f(CWisUPPER_utf8\fR 4
+.IX Item "isUPPER_utf8"
+.ie n .IP """isUPPER_utf8_safe""" 4
+.el .IP \f(CWisUPPER_utf8_safe\fR 4
+.IX Item "isUPPER_utf8_safe"
+.ie n .IP """isUPPER_uvchr""" 4
+.el .IP \f(CWisUPPER_uvchr\fR 4
+.IX Xref "isUPPER isUPPER_A isUPPER_LC isUPPER_LC_utf8_safe isUPPER_LC_uvchr isUPPER_L1 isUPPER_utf8 isUPPER_utf8_safe isUPPER_uvchr"
+.IX Item "isUPPER_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is an
+uppercase character, analogous to \f(CW\*(C`m/[[:upper:]]/\*(C'\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isUPPER             (UV ch)
+\& bool  isUPPER_A           (UV ch)
+\& bool  isUPPER_LC          (UV ch)
+\& bool  isUPPER_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isUPPER_LC_uvchr    (UV ch)
+\& bool  isUPPER_L1          (UV ch)
+\& bool  isUPPER_utf8        (U8 * s, U8 * end)
+\& bool  isUPPER_utf8_safe   (U8 * s, U8 * end)
+\& bool  isUPPER_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isWORDCHAR""" 4
+.el .IP \f(CWisWORDCHAR\fR 4
+.IX Item "isWORDCHAR"
+.PD 0
+.ie n .IP """isWORDCHAR_A""" 4
+.el .IP \f(CWisWORDCHAR_A\fR 4
+.IX Item "isWORDCHAR_A"
+.ie n .IP """isWORDCHAR_LC""" 4
+.el .IP \f(CWisWORDCHAR_LC\fR 4
+.IX Item "isWORDCHAR_LC"
+.ie n .IP """isWORDCHAR_LC_utf8_safe""" 4
+.el .IP \f(CWisWORDCHAR_LC_utf8_safe\fR 4
+.IX Item "isWORDCHAR_LC_utf8_safe"
+.ie n .IP """isWORDCHAR_LC_uvchr""" 4
+.el .IP \f(CWisWORDCHAR_LC_uvchr\fR 4
+.IX Item "isWORDCHAR_LC_uvchr"
+.ie n .IP """isWORDCHAR_L1""" 4
+.el .IP \f(CWisWORDCHAR_L1\fR 4
+.IX Item "isWORDCHAR_L1"
+.ie n .IP """isWORDCHAR_utf8""" 4
+.el .IP \f(CWisWORDCHAR_utf8\fR 4
+.IX Item "isWORDCHAR_utf8"
+.ie n .IP """isWORDCHAR_utf8_safe""" 4
+.el .IP \f(CWisWORDCHAR_utf8_safe\fR 4
+.IX Item "isWORDCHAR_utf8_safe"
+.ie n .IP """isWORDCHAR_uvchr""" 4
+.el .IP \f(CWisWORDCHAR_uvchr\fR 4
+.IX Xref "isWORDCHAR isWORDCHAR_A isWORDCHAR_LC isWORDCHAR_LC_utf8_safe isWORDCHAR_LC_uvchr isWORDCHAR_L1 isWORDCHAR_utf8 isWORDCHAR_utf8_safe isWORDCHAR_uvchr"
+.IX Item "isWORDCHAR_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a character
+that is a word character, analogous to what \f(CW\*(C`m/\ew/\*(C'\fR and \f(CW\*(C`m/[[:word:]]/\*(C'\fR match
+in a regular expression.  A word character is an alphabetic character, a
+decimal digit, a connecting punctuation character (such as an underscore), or
+a "mark" character that attaches to one of those (like some sort of accent).
+.Sp
+See the top of this section for an explanation of
+the variants.
+.Sp
+\&\f(CW\*(C`isWORDCHAR_A\*(C'\fR, \f(CW\*(C`isWORDCHAR_L1\*(C'\fR, \f(CW\*(C`isWORDCHAR_uvchr\*(C'\fR,
+\&\f(CW\*(C`isWORDCHAR_LC\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_uvchr\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_utf8\*(C'\fR, and
+\&\f(CW\*(C`isWORDCHAR_LC_utf8_safe\*(C'\fR are also as described there, but additionally
+include the platform's native underscore.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isWORDCHAR             (UV ch)
+\& bool  isWORDCHAR_A           (UV ch)
+\& bool  isWORDCHAR_LC          (UV ch)
+\& bool  isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isWORDCHAR_LC_uvchr    (UV ch)
+\& bool  isWORDCHAR_L1          (UV ch)
+\& bool  isWORDCHAR_utf8        (U8 * s, U8 * end)
+\& bool  isWORDCHAR_utf8_safe   (U8 * s, U8 * end)
+\& bool  isWORDCHAR_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isXDIGIT""" 4
+.el .IP \f(CWisXDIGIT\fR 4
+.IX Item "isXDIGIT"
+.PD 0
+.ie n .IP """isXDIGIT_A""" 4
+.el .IP \f(CWisXDIGIT_A\fR 4
+.IX Item "isXDIGIT_A"
+.ie n .IP """isXDIGIT_LC""" 4
+.el .IP \f(CWisXDIGIT_LC\fR 4
+.IX Item "isXDIGIT_LC"
+.ie n .IP """isXDIGIT_LC_utf8_safe""" 4
+.el .IP \f(CWisXDIGIT_LC_utf8_safe\fR 4
+.IX Item "isXDIGIT_LC_utf8_safe"
+.ie n .IP """isXDIGIT_LC_uvchr""" 4
+.el .IP \f(CWisXDIGIT_LC_uvchr\fR 4
+.IX Item "isXDIGIT_LC_uvchr"
+.ie n .IP """isXDIGIT_L1""" 4
+.el .IP \f(CWisXDIGIT_L1\fR 4
+.IX Item "isXDIGIT_L1"
+.ie n .IP """isXDIGIT_utf8""" 4
+.el .IP \f(CWisXDIGIT_utf8\fR 4
+.IX Item "isXDIGIT_utf8"
+.ie n .IP """isXDIGIT_utf8_safe""" 4
+.el .IP \f(CWisXDIGIT_utf8_safe\fR 4
+.IX Item "isXDIGIT_utf8_safe"
+.ie n .IP """isXDIGIT_uvchr""" 4
+.el .IP \f(CWisXDIGIT_uvchr\fR 4
+.IX Xref "isXDIGIT isXDIGIT_A isXDIGIT_LC isXDIGIT_LC_utf8_safe isXDIGIT_LC_uvchr isXDIGIT_L1 isXDIGIT_utf8 isXDIGIT_utf8_safe isXDIGIT_uvchr"
+.IX Item "isXDIGIT_uvchr"
+.PD
+Returns a boolean indicating whether the specified character is a hexadecimal
+digit.  In the ASCII range these are \f(CW\*(C`[0\-9A\-Fa\-f]\*(C'\fR.  Variants \f(CWisXDIGIT_A()\fR
+and \f(CWisXDIGIT_L1()\fR are identical to \f(CWisXDIGIT()\fR.
+See the top of this section for an explanation of
+the variants.
+.RS 4
+.Sp
+.Vb 9
+\& bool  isXDIGIT             (UV ch)
+\& bool  isXDIGIT_A           (UV ch)
+\& bool  isXDIGIT_LC          (UV ch)
+\& bool  isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
+\& bool  isXDIGIT_LC_uvchr    (UV ch)
+\& bool  isXDIGIT_L1          (UV ch)
+\& bool  isXDIGIT_utf8        (U8 * s, U8 * end)
+\& bool  isXDIGIT_utf8_safe   (U8 * s, U8 * end)
+\& bool  isXDIGIT_uvchr       (UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Compiler and Preprocessor information"
+.IX Header "Compiler and Preprocessor information"
+.ie n .IP """CPPLAST""" 4
+.el .IP \f(CWCPPLAST\fR 4
+.IX Xref "CPPLAST"
+.IX Item "CPPLAST"
+This symbol is intended to be used along with \f(CW\*(C`CPPRUN\*(C'\fR in the same manner
+symbol \f(CW\*(C`CPPMINUS\*(C'\fR is used with \f(CW\*(C`CPPSTDIN\*(C'\fR. It contains either "\-" or "".
+.ie n .IP """CPPMINUS""" 4
+.el .IP \f(CWCPPMINUS\fR 4
+.IX Xref "CPPMINUS"
+.IX Item "CPPMINUS"
+This symbol contains the second part of the string which will invoke
+the C preprocessor on the standard input and produce to standard
+output.  This symbol will have the value "\-" if \f(CW\*(C`CPPSTDIN\*(C'\fR needs a minus
+to specify standard input, otherwise the value is "".
+.ie n .IP """CPPRUN""" 4
+.el .IP \f(CWCPPRUN\fR 4
+.IX Xref "CPPRUN"
+.IX Item "CPPRUN"
+This symbol contains the string which will invoke a C preprocessor on
+the standard input and produce to standard output. It needs to end
+with \f(CW\*(C`CPPLAST\*(C'\fR, after all other preprocessor flags have been specified.
+The main difference with \f(CW\*(C`CPPSTDIN\*(C'\fR is that this program will never be a
+pointer to a shell wrapper, i.e. it will be empty if no preprocessor is
+available directly to the user. Note that it may well be different from
+the preprocessor used to compile the C program.
+.ie n .IP """CPPSTDIN""" 4
+.el .IP \f(CWCPPSTDIN\fR 4
+.IX Xref "CPPSTDIN"
+.IX Item "CPPSTDIN"
+This symbol contains the first part of the string which will invoke
+the C preprocessor on the standard input and produce to standard
+output.  Typical value of "cc \-E" or "\fI/lib/cpp\fR", but it can also
+call a wrapper. See \f(CW"CPPRUN"\fR.
+.ie n .IP """HASATTRIBUTE_ALWAYS_INLINE""" 4
+.el .IP \f(CWHASATTRIBUTE_ALWAYS_INLINE\fR 4
+.IX Xref "HASATTRIBUTE_ALWAYS_INLINE"
+.IX Item "HASATTRIBUTE_ALWAYS_INLINE"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should always be
+inlined.
+.ie n .IP """HASATTRIBUTE_DEPRECATED""" 4
+.el .IP \f(CWHASATTRIBUTE_DEPRECATED\fR 4
+.IX Xref "HASATTRIBUTE_DEPRECATED"
+.IX Item "HASATTRIBUTE_DEPRECATED"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for marking deprecated \f(CW\*(C`APIs\*(C'\fR
+.ie n .IP """HASATTRIBUTE_FORMAT""" 4
+.el .IP \f(CWHASATTRIBUTE_FORMAT\fR 4
+.IX Xref "HASATTRIBUTE_FORMAT"
+.IX Item "HASATTRIBUTE_FORMAT"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for checking printf-style formats
+.ie n .IP """HASATTRIBUTE_NONNULL""" 4
+.el .IP \f(CWHASATTRIBUTE_NONNULL\fR 4
+.IX Xref "HASATTRIBUTE_NONNULL"
+.IX Item "HASATTRIBUTE_NONNULL"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for nonnull function parms.
+.ie n .IP """HASATTRIBUTE_NORETURN""" 4
+.el .IP \f(CWHASATTRIBUTE_NORETURN\fR 4
+.IX Xref "HASATTRIBUTE_NORETURN"
+.IX Item "HASATTRIBUTE_NORETURN"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that do not return
+.ie n .IP """HASATTRIBUTE_PURE""" 4
+.el .IP \f(CWHASATTRIBUTE_PURE\fR 4
+.IX Xref "HASATTRIBUTE_PURE"
+.IX Item "HASATTRIBUTE_PURE"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for pure functions
+.ie n .IP """HASATTRIBUTE_UNUSED""" 4
+.el .IP \f(CWHASATTRIBUTE_UNUSED\fR 4
+.IX Xref "HASATTRIBUTE_UNUSED"
+.IX Item "HASATTRIBUTE_UNUSED"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for unused variables and arguments
+.ie n .IP """HASATTRIBUTE_VISIBILITY""" 4
+.el .IP \f(CWHASATTRIBUTE_VISIBILITY\fR 4
+.IX Xref "HASATTRIBUTE_VISIBILITY"
+.IX Item "HASATTRIBUTE_VISIBILITY"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should have a
+different visibility.
+.ie n .IP """HASATTRIBUTE_WARN_UNUSED_RESULT""" 4
+.el .IP \f(CWHASATTRIBUTE_WARN_UNUSED_RESULT\fR 4
+.IX Xref "HASATTRIBUTE_WARN_UNUSED_RESULT"
+.IX Item "HASATTRIBUTE_WARN_UNUSED_RESULT"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for warning on unused results
+.ie n .IP """HAS_BUILTIN_ADD_OVERFLOW""" 4
+.el .IP \f(CWHAS_BUILTIN_ADD_OVERFLOW\fR 4
+.IX Xref "HAS_BUILTIN_ADD_OVERFLOW"
+.IX Item "HAS_BUILTIN_ADD_OVERFLOW"
+This symbol, if defined, indicates that the compiler supports
+\&\f(CW\*(C`_\|_builtin_add_overflow\*(C'\fR for adding integers with overflow checks.
+.ie n .IP """HAS_BUILTIN_CHOOSE_EXPR""" 4
+.el .IP \f(CWHAS_BUILTIN_CHOOSE_EXPR\fR 4
+.IX Xref "HAS_BUILTIN_CHOOSE_EXPR"
+.IX Item "HAS_BUILTIN_CHOOSE_EXPR"
+Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for compile-time ternary-like expressions
+.ie n .IP """HAS_BUILTIN_EXPECT""" 4
+.el .IP \f(CWHAS_BUILTIN_EXPECT\fR 4
+.IX Xref "HAS_BUILTIN_EXPECT"
+.IX Item "HAS_BUILTIN_EXPECT"
+Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for telling that certain values are more
+likely
+.ie n .IP """HAS_BUILTIN_MUL_OVERFLOW""" 4
+.el .IP \f(CWHAS_BUILTIN_MUL_OVERFLOW\fR 4
+.IX Xref "HAS_BUILTIN_MUL_OVERFLOW"
+.IX Item "HAS_BUILTIN_MUL_OVERFLOW"
+This symbol, if defined, indicates that the compiler supports
+\&\f(CW\*(C`_\|_builtin_mul_overflow\*(C'\fR for multiplying integers with overflow checks.
+.ie n .IP """HAS_BUILTIN_SUB_OVERFLOW""" 4
+.el .IP \f(CWHAS_BUILTIN_SUB_OVERFLOW\fR 4
+.IX Xref "HAS_BUILTIN_SUB_OVERFLOW"
+.IX Item "HAS_BUILTIN_SUB_OVERFLOW"
+This symbol, if defined, indicates that the compiler supports
+\&\f(CW\*(C`_\|_builtin_sub_overflow\*(C'\fR for subtracting integers with overflow checks.
+.ie n .IP """HAS_C99_VARIADIC_MACROS""" 4
+.el .IP \f(CWHAS_C99_VARIADIC_MACROS\fR 4
+.IX Xref "HAS_C99_VARIADIC_MACROS"
+.IX Item "HAS_C99_VARIADIC_MACROS"
+If defined, the compiler supports C99 variadic macros.
+.ie n .IP """HAS_STATIC_INLINE""" 4
+.el .IP \f(CWHAS_STATIC_INLINE\fR 4
+.IX Xref "HAS_STATIC_INLINE"
+.IX Item "HAS_STATIC_INLINE"
+This symbol, if defined, indicates that the C compiler supports
+C99\-style static inline.  That is, the function can't be called
+from another translation unit.
+.ie n .IP """MEM_ALIGNBYTES""" 4
+.el .IP \f(CWMEM_ALIGNBYTES\fR 4
+.IX Xref "MEM_ALIGNBYTES"
+.IX Item "MEM_ALIGNBYTES"
+This symbol contains the number of bytes required to align a
+double, or a long double when applicable. Usual values are 2,
+4 and 8. The default is eight, for safety.  For cross-compiling
+or multiarch support, Configure will set a minimum of 8.
+.ie n .IP """PERL_STATIC_INLINE""" 4
+.el .IP \f(CWPERL_STATIC_INLINE\fR 4
+.IX Xref "PERL_STATIC_INLINE"
+.IX Item "PERL_STATIC_INLINE"
+This symbol gives the best-guess incantation to use for static
+inline functions.  If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is defined, this will
+give C99\-style inline.  If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is not defined,
+this will give a plain 'static'.  It will always be defined
+to something that gives static linkage.
+Possibilities include
+.Sp
+.Vb 5
+\& static inline       (c99)
+\& static _\|_inline_\|_   (gcc \-ansi)
+\& static _\|_inline     (MSVC)
+\& static _inline      (older MSVC)
+\& static              (c89 compilers)
+.Ve
+.ie n .IP """PERL_THREAD_LOCAL""" 4
+.el .IP \f(CWPERL_THREAD_LOCAL\fR 4
+.IX Xref "PERL_THREAD_LOCAL"
+.IX Item "PERL_THREAD_LOCAL"
+This symbol, if defined, gives a linkage specification for thread-local
+storage. For example, for a C11 compiler this will be \f(CW\*(C`_Thread_local\*(C'\fR.
+Beware, some compilers are sensitive to the C language standard they are
+told to parse. For example, suncc defaults to C11, so our probe will
+report that \f(CW\*(C`_Thread_local\*(C'\fR can be used. However, if the \-std=c99 is later
+added to the compiler flags, then \f(CW\*(C`_Thread_local\*(C'\fR will become a syntax
+error. Hence it is important for these flags to be consistent between
+probing and use.
+.ie n .IP """U32_ALIGNMENT_REQUIRED""" 4
+.el .IP \f(CWU32_ALIGNMENT_REQUIRED\fR 4
+.IX Xref "U32_ALIGNMENT_REQUIRED"
+.IX Item "U32_ALIGNMENT_REQUIRED"
+This symbol, if defined, indicates that you must access
+character data through U32\-aligned pointers.
+.SH "Compiler directives"
+.IX Header "Compiler directives"
+.ie n .IP """_\|_ASSERT_""" 4
+.el .IP \f(CW_\|_ASSERT_\fR 4
+.IX Xref "__ASSERT_"
+.IX Item "__ASSERT_"
+This is a helper macro to avoid preprocessor issues, replaced by nothing
+unless under DEBUGGING, where it expands to an assert of its argument,
+followed by a comma (hence the comma operator).  If we just used a straight
+\&\fBassert()\fR, we would get a comma with nothing before it when not DEBUGGING.
+.RS 4
+.Sp
+.Vb 1
+\&   _\|_ASSERT_(bool expr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ASSUME""" 4
+.el .IP \f(CWASSUME\fR 4
+.IX Xref "ASSUME"
+.IX Item "ASSUME"
+\&\f(CW\*(C`ASSUME\*(C'\fR is like \f(CWassert()\fR, but it has a benefit in a release build. It is a
+hint to a compiler about a statement of fact in a function call free
+expression, which allows the compiler to generate better machine code.  In a
+debug build, \f(CWASSUME(x)\fR is a synonym for \f(CWassert(x)\fR. \f(CWASSUME(0)\fR means the
+control path is unreachable. In a for loop, \f(CW\*(C`ASSUME\*(C'\fR can be used to hint that
+a loop will run at least X times. \f(CW\*(C`ASSUME\*(C'\fR is based off MSVC's \f(CW\*(C`_\|_assume\*(C'\fR
+intrinsic function, see its documents for more details.
+.RS 4
+.Sp
+.Vb 1
+\&   ASSUME(bool expr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dNOOP""" 4
+.el .IP \f(CWdNOOP\fR 4
+.IX Xref "dNOOP"
+.IX Item "dNOOP"
+Declare nothing; typically used as a placeholder to replace something that used
+to declare something.  Works on compilers that require declarations before any
+code.
+.RS 4
+.Sp
+.Vb 1
+\&   dNOOP;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """END_EXTERN_C""" 4
+.el .IP \f(CWEND_EXTERN_C\fR 4
+.IX Xref "END_EXTERN_C"
+.IX Item "END_EXTERN_C"
+When not compiling using C++, expands to nothing.
+Otherwise ends a section of code already begun by a \f(CW"START_EXTERN_C"\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   END_EXTERN_C
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """EXTERN_C""" 4
+.el .IP \f(CWEXTERN_C\fR 4
+.IX Xref "EXTERN_C"
+.IX Item "EXTERN_C"
+When not compiling using C++, expands to nothing.
+Otherwise is used in a declaration of a function to indicate the function
+should have external C linkage.  This is required for things to work for just
+about all functions with external linkage compiled into perl.
+Often, you can use \f(CW"START_EXTERN_C"\fR ... \f(CW"END_EXTERN_C"\fR blocks
+surrounding all your code that you need to have this linkage.
+.Sp
+Example usage:
+.Sp
+.Vb 1
+\& EXTERN_C int flock(int fd, int op);
+.Ve
+.ie n .IP """LIKELY""" 4
+.el .IP \f(CWLIKELY\fR 4
+.IX Xref "LIKELY"
+.IX Item "LIKELY"
+Returns the input unchanged, but at the same time it gives a branch prediction
+hint to the compiler that this condition is likely to be true.
+.RS 4
+.Sp
+.Vb 1
+\&   LIKELY(bool expr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """NOOP""" 4
+.el .IP \f(CWNOOP\fR 4
+.IX Xref "NOOP"
+.IX Item "NOOP"
+Do nothing; typically used as a placeholder to replace something that used to
+do something.
+.RS 4
+.Sp
+.Vb 1
+\&   NOOP;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_UNUSED_ARG""" 4
+.el .IP \f(CWPERL_UNUSED_ARG\fR 4
+.IX Xref "PERL_UNUSED_ARG"
+.IX Item "PERL_UNUSED_ARG"
+This is used to suppress compiler warnings that a parameter to a function is
+not used.  This situation can arise, for example, when a parameter is needed
+under some configuration conditions, but not others, so that C preprocessor
+conditional compilation causes it be used just sometimes.
+.RS 4
+.Sp
+.Vb 1
+\&   PERL_UNUSED_ARG(void x);
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_UNUSED_CONTEXT""" 4
+.el .IP \f(CWPERL_UNUSED_CONTEXT\fR 4
+.IX Xref "PERL_UNUSED_CONTEXT"
+.IX Item "PERL_UNUSED_CONTEXT"
+This is used to suppress compiler warnings that the thread context parameter to
+a function is not used.  This situation can arise, for example, when a
+C preprocessor conditional compilation causes it be used just some times.
+.RS 4
+.Sp
+.Vb 1
+\&   PERL_UNUSED_CONTEXT;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_UNUSED_DECL""" 4
+.el .IP \f(CWPERL_UNUSED_DECL\fR 4
+.IX Xref "PERL_UNUSED_DECL"
+.IX Item "PERL_UNUSED_DECL"
+Tells the compiler that the parameter in the function prototype just before it
+is not necessarily expected to be used in the function.  Not that many
+compilers understand this, so this should only be used in cases where
+\&\f(CW"PERL_UNUSED_ARG"\fR can't conveniently be used.
+.Sp
+Example usage:
+.RS 4
+.Sp
+.Vb 3
+\& Signal_t
+\& Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
+\&                       void *uap PERL_UNUSED_DECL, bool safe)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_UNUSED_RESULT""" 4
+.el .IP \f(CWPERL_UNUSED_RESULT\fR 4
+.IX Xref "PERL_UNUSED_RESULT"
+.IX Item "PERL_UNUSED_RESULT"
+This macro indicates to discard the return value of the function call inside
+it, \fIe.g.\fR,
+.Sp
+.Vb 1
+\& PERL_UNUSED_RESULT(foo(a, b))
+.Ve
+.Sp
+The main reason for this is that the combination of \f(CW\*(C`gcc \-Wunused\-result\*(C'\fR
+(part of \f(CW\*(C`\-Wall\*(C'\fR) and the \f(CW\*(C`_\|_attribute_\|_((warn_unused_result))\*(C'\fR cannot
+be silenced with casting to \f(CW\*(C`void\*(C'\fR.  This causes trouble when the system
+header files use the attribute.
+.Sp
+Use \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR sparingly, though, since usually the warning
+is there for a good reason: you might lose success/failure information,
+or leak resources, or changes in resources.
+.Sp
+But sometimes you just want to ignore the return value, \fIe.g.\fR, on
+codepaths soon ending up in abort, or in "best effort" attempts,
+or in situations where there is no good way to handle failures.
+.Sp
+Sometimes \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR might not be the most natural way:
+another possibility is that you can capture the return value
+and use \f(CW"PERL_UNUSED_VAR"\fR on that.
+.RS 4
+.Sp
+.Vb 1
+\&   PERL_UNUSED_RESULT(void x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_UNUSED_VAR""" 4
+.el .IP \f(CWPERL_UNUSED_VAR\fR 4
+.IX Xref "PERL_UNUSED_VAR"
+.IX Item "PERL_UNUSED_VAR"
+This is used to suppress compiler warnings that the variable \fIx\fR is not used.
+This situation can arise, for example, when a C preprocessor conditional
+compilation causes it be used just some times.
+.RS 4
+.Sp
+.Vb 1
+\&   PERL_UNUSED_VAR(void x);
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """START_EXTERN_C""" 4
+.el .IP \f(CWSTART_EXTERN_C\fR 4
+.IX Xref "START_EXTERN_C"
+.IX Item "START_EXTERN_C"
+When not compiling using C++, expands to nothing.
+Otherwise begins a section of code in which every function will effectively
+have \f(CW"EXTERN_C"\fR applied to it, that is to have external C linkage.  The
+section is ended by a \f(CW"END_EXTERN_C"\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   START_EXTERN_C
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STATIC""" 4
+.el .IP \f(CWSTATIC\fR 4
+.IX Item "STATIC"
+Described in perlguts.
+.ie n .IP """STMT_END""" 4
+.el .IP \f(CWSTMT_END\fR 4
+.IX Item "STMT_END"
+.PD 0
+.ie n .IP """STMT_START""" 4
+.el .IP \f(CWSTMT_START\fR 4
+.IX Xref "STMT_END STMT_START"
+.IX Item "STMT_START"
+.PD
+These allow a series of statements in a macro to be used as a single statement,
+as in
+.Sp
+.Vb 1
+\& if (x) STMT_START { ... } STMT_END else ...
+.Ve
+.Sp
+Note that you can't return a value out of this construct and cannot use it as
+an operand to the comma operator.  These limit its utility.
+.Sp
+But, a value could be returned by constructing the API so that a pointer is
+passed and the macro dereferences this to set the return.  If the value can be
+any of various types, depending on context, you can handle that situation in
+some situations by adding the type of the return as an extra accompanying
+parameter:
+.Sp
+.Vb 3
+\& #define foo(param, type)  STMT_START {
+\&                              type * param; *param = do_calc; ...
+\&                           } STMT_END
+.Ve
+.Sp
+This could be awkward, so consider instead using a C language \f(CW\*(C`static inline\*(C'\fR
+function.
+.Sp
+If you do use this construct, it is easy to forget that it is a macro and not a
+function, and hence fall into traps that might not show up until someone
+someday writes code which contains names that clash with the ones you chose
+here, or calls it with a parameter which is an expression with side effects,
+the consequences of which you didn't think about.  See "Writing
+safer macros" in perlhacktips for how to avoid these.
+.ie n .IP """UNLIKELY""" 4
+.el .IP \f(CWUNLIKELY\fR 4
+.IX Xref "UNLIKELY"
+.IX Item "UNLIKELY"
+Returns the input unchanged, but at the same time it gives a branch prediction
+hint to the compiler that this condition is likely to be false.
+.RS 4
+.Sp
+.Vb 1
+\&   UNLIKELY(bool expr)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Compile-time scope hooks"
+.IX Header "Compile-time scope hooks"
+.ie n .IP """BhkDISABLE""" 4
+.el .IP \f(CWBhkDISABLE\fR 4
+.IX Xref "BhkDISABLE"
+.IX Item "BhkDISABLE"
+NOTE: \f(CW\*(C`BhkDISABLE\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Temporarily disable an entry in this BHK structure, by clearing the
+appropriate flag.  \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which
+entry to disable.
+.RS 4
+.Sp
+.Vb 1
+\& void  BhkDISABLE(BHK *hk, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BhkENABLE""" 4
+.el .IP \f(CWBhkENABLE\fR 4
+.IX Xref "BhkENABLE"
+.IX Item "BhkENABLE"
+NOTE: \f(CW\*(C`BhkENABLE\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Re-enable an entry in this BHK structure, by setting the appropriate
+flag.  \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which entry to enable.
+This will assert (under \-DDEBUGGING) if the entry doesn't contain a valid
+pointer.
+.RS 4
+.Sp
+.Vb 1
+\& void  BhkENABLE(BHK *hk, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BhkENTRY_set""" 4
+.el .IP \f(CWBhkENTRY_set\fR 4
+.IX Xref "BhkENTRY_set"
+.IX Item "BhkENTRY_set"
+NOTE: \f(CW\*(C`BhkENTRY_set\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Set an entry in the BHK structure, and set the flags to indicate it is
+valid.  \f(CW\*(C`which\*(C'\fR is a preprocessing token indicating which entry to set.
+The type of \f(CW\*(C`ptr\*(C'\fR depends on the entry.
+.RS 4
+.Sp
+.Vb 1
+\& void  BhkENTRY_set(BHK *hk, token which, void *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """blockhook_register""" 4
+.el .IP \f(CWblockhook_register\fR 4
+.IX Xref "blockhook_register"
+.IX Item "blockhook_register"
+NOTE: \f(CW\*(C`blockhook_register\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Register a set of hooks to be called when the Perl lexical scope changes
+at compile time.  See "Compile-time scope hooks" in perlguts.
+.Sp
+NOTE: \f(CW\*(C`blockhook_register\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_blockhook_register\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_blockhook_register(pTHX_ BHK *hk)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Concurrency
+.IX Header "Concurrency"
+.ie n .IP """aTHX""" 4
+.el .IP \f(CWaTHX\fR 4
+.IX Item "aTHX"
+Described in perlguts.
+.ie n .IP """aTHX_""" 4
+.el .IP \f(CWaTHX_\fR 4
+.IX Item "aTHX_"
+Described in perlguts.
+.ie n .IP """CPERLscope""" 4
+.el .IP \f(CWCPERLscope\fR 4
+.IX Xref "CPERLscope"
+.IX Item "CPERLscope"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`CPERLscope\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Now a no-op.
+.RS 4
+.Sp
+.Vb 1
+\& void  CPERLscope(void x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dTHR""" 4
+.el .IP \f(CWdTHR\fR 4
+.IX Item "dTHR"
+Described in perlguts.
+.ie n .IP """dTHX""" 4
+.el .IP \f(CWdTHX\fR 4
+.IX Item "dTHX"
+Described in perlguts.
+.ie n .IP """dTHXa""" 4
+.el .IP \f(CWdTHXa\fR 4
+.IX Xref "dTHXa"
+.IX Item "dTHXa"
+On threaded perls, set \f(CW\*(C`pTHX\*(C'\fR to \f(CW\*(C`a\*(C'\fR; on unthreaded perls, do nothing
+.ie n .IP """dTHXoa""" 4
+.el .IP \f(CWdTHXoa\fR 4
+.IX Xref "dTHXoa"
+.IX Item "dTHXoa"
+Now a synonym for \f(CW"dTHXa"\fR.
+.ie n .IP """dVAR""" 4
+.el .IP \f(CWdVAR\fR 4
+.IX Xref "dVAR"
+.IX Item "dVAR"
+This is now a synonym for dNOOP: declare nothing
+.ie n .IP """GETENV_PRESERVES_OTHER_THREAD""" 4
+.el .IP \f(CWGETENV_PRESERVES_OTHER_THREAD\fR 4
+.IX Xref "GETENV_PRESERVES_OTHER_THREAD"
+.IX Item "GETENV_PRESERVES_OTHER_THREAD"
+This symbol, if defined, indicates that the getenv system call doesn't
+zap the static buffer of \f(CWgetenv()\fR in a different thread.
+The typical \f(CWgetenv()\fR implementation will return a pointer to the proper
+position in **environ.  But some may instead copy them to a static
+buffer in \f(CWgetenv()\fR.  If there is a per-thread instance of that buffer,
+or the return points to **environ, then a many\-reader/1\-writer mutex
+will work; otherwise an exclusive locking mutex is required to prevent
+races.
+.ie n .IP """HAS_PTHREAD_ATFORK""" 4
+.el .IP \f(CWHAS_PTHREAD_ATFORK\fR 4
+.IX Xref "HAS_PTHREAD_ATFORK"
+.IX Item "HAS_PTHREAD_ATFORK"
+This symbol, if defined, indicates that the \f(CW\*(C`pthread_atfork\*(C'\fR routine
+is available to setup fork handlers.
+.ie n .IP """HAS_PTHREAD_ATTR_SETSCOPE""" 4
+.el .IP \f(CWHAS_PTHREAD_ATTR_SETSCOPE\fR 4
+.IX Xref "HAS_PTHREAD_ATTR_SETSCOPE"
+.IX Item "HAS_PTHREAD_ATTR_SETSCOPE"
+This symbol, if defined, indicates that the \f(CW\*(C`pthread_attr_setscope\*(C'\fR
+system call is available to set the contention scope attribute of
+a thread attribute object.
+.ie n .IP """HAS_PTHREAD_YIELD""" 4
+.el .IP \f(CWHAS_PTHREAD_YIELD\fR 4
+.IX Xref "HAS_PTHREAD_YIELD"
+.IX Item "HAS_PTHREAD_YIELD"
+This symbol, if defined, indicates that the \f(CW\*(C`pthread_yield\*(C'\fR
+routine is available to yield the execution of the current
+thread.  \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
+.ie n .IP """HAS_SCHED_YIELD""" 4
+.el .IP \f(CWHAS_SCHED_YIELD\fR 4
+.IX Xref "HAS_SCHED_YIELD"
+.IX Item "HAS_SCHED_YIELD"
+This symbol, if defined, indicates that the \f(CW\*(C`sched_yield\*(C'\fR
+routine is available to yield the execution of the current
+thread.  \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
+.ie n .IP """I_MACH_CTHREADS""" 4
+.el .IP \f(CWI_MACH_CTHREADS\fR 4
+.IX Xref "I_MACH_CTHREADS"
+.IX Item "I_MACH_CTHREADS"
+This symbol, if defined, indicates to the C program that it should
+include \fImach/cthreads.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_MACH_CTHREADS
+\&     #include <mach_cthreads.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_PTHREAD""" 4
+.el .IP \f(CWI_PTHREAD\fR 4
+.IX Xref "I_PTHREAD"
+.IX Item "I_PTHREAD"
+This symbol, if defined, indicates to the C program that it should
+include \fIpthread.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_PTHREAD
+\&     #include <pthread.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MULTIPLICITY""" 4
+.el .IP \f(CWMULTIPLICITY\fR 4
+.IX Item "MULTIPLICITY"
+This symbol, if defined, indicates that Perl should
+be built to use multiplicity.
+.ie n .IP """OLD_PTHREAD_CREATE_JOINABLE""" 4
+.el .IP \f(CWOLD_PTHREAD_CREATE_JOINABLE\fR 4
+.IX Xref "OLD_PTHREAD_CREATE_JOINABLE"
+.IX Item "OLD_PTHREAD_CREATE_JOINABLE"
+This symbol, if defined, indicates how to create pthread
+in joinable (aka undetached) state.  \f(CW\*(C`NOTE\*(C'\fR: not defined
+if \fIpthread.h\fR already has defined \f(CW\*(C`PTHREAD_CREATE_JOINABLE\*(C'\fR
+(the new version of the constant).
+If defined, known values are \f(CW\*(C`PTHREAD_CREATE_UNDETACHED\*(C'\fR
+and \f(CW\*(C`_\|_UNDETACHED\*(C'\fR.
+.ie n .IP """OLD_PTHREADS_API""" 4
+.el .IP \f(CWOLD_PTHREADS_API\fR 4
+.IX Xref "OLD_PTHREADS_API"
+.IX Item "OLD_PTHREADS_API"
+This symbol, if defined, indicates that Perl should
+be built to use the old draft \f(CW\*(C`POSIX\*(C'\fR threads \f(CW\*(C`API\*(C'\fR.
+.ie n .IP """PERL_IMPLICIT_CONTEXT""" 4
+.el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4
+.IX Item "PERL_IMPLICIT_CONTEXT"
+Described in perlguts.
+.ie n .IP """PERL_NO_GET_CONTEXT""" 4
+.el .IP \f(CWPERL_NO_GET_CONTEXT\fR 4
+.IX Item "PERL_NO_GET_CONTEXT"
+Described in perlguts.
+.ie n .IP """pTHX""" 4
+.el .IP \f(CWpTHX\fR 4
+.IX Item "pTHX"
+Described in perlguts.
+.ie n .IP """pTHX_""" 4
+.el .IP \f(CWpTHX_\fR 4
+.IX Item "pTHX_"
+Described in perlguts.
+.ie n .IP """SCHED_YIELD""" 4
+.el .IP \f(CWSCHED_YIELD\fR 4
+.IX Xref "SCHED_YIELD"
+.IX Item "SCHED_YIELD"
+This symbol defines the way to yield the execution of
+the current thread.  Known ways are \f(CW\*(C`sched_yield\*(C'\fR,
+\&\f(CW\*(C`pthread_yield\*(C'\fR, and \f(CW\*(C`pthread_yield\*(C'\fR with \f(CW\*(C`NULL\*(C'\fR.
+.SH "COPs and Hint Hashes"
+.IX Xref "COPHH_KEY_UTF8"
+.IX Header "COPs and Hint Hashes"
+.ie n .IP """cop_fetch_label""" 4
+.el .IP \f(CWcop_fetch_label\fR 4
+.IX Xref "cop_fetch_label"
+.IX Item "cop_fetch_label"
+NOTE: \f(CW\*(C`cop_fetch_label\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Returns the label attached to a cop, and stores its length in bytes into
+\&\f(CW*len\fR.
+Upon return, \f(CW*flags\fR will be set to either \f(CW\*(C`SVf_UTF8\*(C'\fR or 0.
+.Sp
+Alternatively, use the macro \f(CW"CopLABEL_len_flags"\fR;
+or if you don't need to know if the label is UTF\-8 or not, the macro
+\&\f(CW"CopLABEL_len"\fR;
+or if you additionally don't need to know the length, \f(CW"CopLABEL"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& const char *  cop_fetch_label(COP * const cop, STRLEN *len,
+\&                               U32 *flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE""" 4
+.el .IP \f(CWCopFILE\fR 4
+.IX Xref "CopFILE"
+.IX Item "CopFILE"
+Returns the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& const char *  CopFILE(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILEAV""" 4
+.el .IP \f(CWCopFILEAV\fR 4
+.IX Xref "CopFILEAV"
+.IX Item "CopFILEAV"
+Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, creating it if necessary.
+.RS 4
+.Sp
+.Vb 1
+\& AV *  CopFILEAV(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILEAVn""" 4
+.el .IP \f(CWCopFILEAVn\fR 4
+.IX Xref "CopFILEAVn"
+.IX Item "CopFILEAVn"
+Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, returning NULL if it
+doesn't already exist.
+.RS 4
+.Sp
+.Vb 1
+\& AV *  CopFILEAVn(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE_copy""" 4
+.el .IP \f(CWCopFILE_copy\fR 4
+.IX Xref "CopFILE_copy"
+.IX Item "CopFILE_copy"
+Efficiently copies the cop file name from one COP to another. Wraps
+the required logic to do a refcounted copy under threads or not.
+.RS 4
+.Sp
+.Vb 1
+\& void  CopFILE_copy(COP * dst, COP * src)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE_free""" 4
+.el .IP \f(CWCopFILE_free\fR 4
+.IX Xref "CopFILE_free"
+.IX Item "CopFILE_free"
+Frees the file data in a cop. Under the hood this is a refcounting
+operation.
+.RS 4
+.Sp
+.Vb 1
+\& void  CopFILE_free(COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILEGV""" 4
+.el .IP \f(CWCopFILEGV\fR 4
+.IX Xref "CopFILEGV"
+.IX Item "CopFILEGV"
+Returns the GV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& GV *  CopFILEGV(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILEGV_set""" 4
+.el .IP \f(CWCopFILEGV_set\fR 4
+.IX Xref "CopFILEGV_set"
+.IX Item "CopFILEGV_set"
+Available only on unthreaded perls.  Makes \f(CW\*(C`pv\*(C'\fR the name of the file
+associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  CopFILEGV_set(COP *c, GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE_LEN""" 4
+.el .IP \f(CWCopFILE_LEN\fR 4
+.IX Xref "CopFILE_LEN"
+.IX Item "CopFILE_LEN"
+Returns the length of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& const char *  CopFILE_LEN(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE_set""" 4
+.el .IP \f(CWCopFILE_set\fR 4
+.IX Xref "CopFILE_set"
+.IX Item "CopFILE_set"
+Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  CopFILE_set(COP * c, const char * pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILE_setn""" 4
+.el .IP \f(CWCopFILE_setn\fR 4
+.IX Xref "CopFILE_setn"
+.IX Item "CopFILE_setn"
+Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  CopFILE_setn(COP * c, const char * pv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopFILESV""" 4
+.el .IP \f(CWCopFILESV\fR 4
+.IX Xref "CopFILESV"
+.IX Item "CopFILESV"
+Returns the SV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  CopFILESV(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_copy""" 4
+.el .IP \f(CWcophh_copy\fR 4
+.IX Xref "cophh_copy"
+.IX Item "cophh_copy"
+NOTE: \f(CW\*(C`cophh_copy\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Make and return a complete copy of the cop hints hash \f(CW\*(C`cophh\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& COPHH *  cophh_copy(COPHH *cophh)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_delete_pv""" 4
+.el .IP \f(CWcophh_delete_pv\fR 4
+.IX Item "cophh_delete_pv"
+.PD 0
+.ie n .IP """cophh_delete_pvn""" 4
+.el .IP \f(CWcophh_delete_pvn\fR 4
+.IX Item "cophh_delete_pvn"
+.ie n .IP """cophh_delete_pvs""" 4
+.el .IP \f(CWcophh_delete_pvs\fR 4
+.IX Item "cophh_delete_pvs"
+.ie n .IP """cophh_delete_sv""" 4
+.el .IP \f(CWcophh_delete_sv\fR 4
+.IX Xref "cophh_delete_pv cophh_delete_pvn cophh_delete_pvs cophh_delete_sv"
+.IX Item "cophh_delete_sv"
+.PD
+NOTE: all these forms are \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+These delete a key and its associated value from the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
+and return the modified hash.  The returned hash pointer is in general
+not the same as the hash pointer that was passed in.  The input hash is
+consumed by the function, and the pointer to it must not be subsequently
+used.  Use "cophh_copy" if you need both hashes.
+.Sp
+The forms differ in how the key is specified.  In all forms, the key is pointed
+to by \f(CW\*(C`key\*(C'\fR.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 7
+\& COPHH *  cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
+\&                           U32 flags)
+\& COPHH *  cophh_delete_pvn(COPHH *cophh, const char *key,
+\&                           STRLEN keylen, U32 hash, U32 flags)
+\& COPHH *  cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
+\& COPHH *  cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
+\&                           U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_exists_pvn""" 4
+.el .IP \f(CWcophh_exists_pvn\fR 4
+.IX Xref "cophh_exists_pvn"
+.IX Item "cophh_exists_pvn"
+NOTE: \f(CW\*(C`cophh_exists_pvn\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
+\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists,
+and false otherwise.
+.Sp
+The forms differ in how the key is specified.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 2
+\& bool  cophh_exists_pvn(const COPHH *cophh, const char *key,
+\&                        STRLEN keylen, U32 hash, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_fetch_pv""" 4
+.el .IP \f(CWcophh_fetch_pv\fR 4
+.IX Item "cophh_fetch_pv"
+.PD 0
+.ie n .IP """cophh_fetch_pvn""" 4
+.el .IP \f(CWcophh_fetch_pvn\fR 4
+.IX Item "cophh_fetch_pvn"
+.ie n .IP """cophh_fetch_pvs""" 4
+.el .IP \f(CWcophh_fetch_pvs\fR 4
+.IX Item "cophh_fetch_pvs"
+.ie n .IP """cophh_fetch_sv""" 4
+.el .IP \f(CWcophh_fetch_sv\fR 4
+.IX Xref "cophh_fetch_pv cophh_fetch_pvn cophh_fetch_pvs cophh_fetch_sv"
+.IX Item "cophh_fetch_sv"
+.PD
+NOTE: all these forms are \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+These look up the entry in the cop hints hash \f(CW\*(C`cophh\*(C'\fR with the key specified by
+\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal
+scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
+key.
+.Sp
+The forms differ in how the key is specified.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 7
+\& SV *  cophh_fetch_pv (const COPHH *cophh, const char *key,
+\&                       U32 hash, U32 flags)
+\& SV *  cophh_fetch_pvn(const COPHH *cophh, const char *key,
+\&                       STRLEN keylen, U32 hash, U32 flags)
+\& SV *  cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
+\& SV *  cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
+\&                       U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_free""" 4
+.el .IP \f(CWcophh_free\fR 4
+.IX Xref "cophh_free"
+.IX Item "cophh_free"
+NOTE: \f(CW\*(C`cophh_free\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Discard the cop hints hash \f(CW\*(C`cophh\*(C'\fR, freeing all resources associated
+with it.
+.RS 4
+.Sp
+.Vb 1
+\& void  cophh_free(COPHH *cophh)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_2hv""" 4
+.el .IP \f(CWcophh_2hv\fR 4
+.IX Xref "cophh_2hv"
+.IX Item "cophh_2hv"
+NOTE: \f(CW\*(C`cophh_2hv\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Generates and returns a standard Perl hash representing the full set of
+key/value pairs in the cop hints hash \f(CW\*(C`cophh\*(C'\fR.  \f(CW\*(C`flags\*(C'\fR is currently
+unused and must be zero.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  cophh_2hv(const COPHH *cophh, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_new_empty""" 4
+.el .IP \f(CWcophh_new_empty\fR 4
+.IX Xref "cophh_new_empty"
+.IX Item "cophh_new_empty"
+NOTE: \f(CW\*(C`cophh_new_empty\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Generate and return a fresh cop hints hash containing no entries.
+.RS 4
+.Sp
+.Vb 1
+\& COPHH *  cophh_new_empty()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cophh_store_pv""" 4
+.el .IP \f(CWcophh_store_pv\fR 4
+.IX Item "cophh_store_pv"
+.PD 0
+.ie n .IP """cophh_store_pvn""" 4
+.el .IP \f(CWcophh_store_pvn\fR 4
+.IX Item "cophh_store_pvn"
+.ie n .IP """cophh_store_pvs""" 4
+.el .IP \f(CWcophh_store_pvs\fR 4
+.IX Item "cophh_store_pvs"
+.ie n .IP """cophh_store_sv""" 4
+.el .IP \f(CWcophh_store_sv\fR 4
+.IX Xref "cophh_store_pv cophh_store_pvn cophh_store_pvs cophh_store_sv"
+.IX Item "cophh_store_sv"
+.PD
+NOTE: all these forms are \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+These store a value, associated with a key, in the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
+and return the modified hash.  The returned hash pointer is in general
+not the same as the hash pointer that was passed in.  The input hash is
+consumed by the function, and the pointer to it must not be subsequently
+used.  Use "cophh_copy" if you need both hashes.
+.Sp
+\&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key.  \f(CW\*(C`value\*(C'\fR is copied
+by these functions, which thus do not take ownership of any reference
+to it, and hence later changes to the scalar will not be reflected in the value
+visible in the cop hints hash.  Complex types of scalar will not be stored with
+referential integrity, but will be coerced to strings.
+.Sp
+The forms differ in how the key is specified.  In all forms, the key is pointed
+to by \f(CW\*(C`key\*(C'\fR.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 9
+\& COPHH *  cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
+\&                          SV *value, U32 flags)
+\& COPHH *  cophh_store_pvn(COPHH *cophh, const char *key,
+\&                          STRLEN keylen, U32 hash, SV *value,
+\&                          U32 flags)
+\& COPHH *  cophh_store_pvs(COPHH *cophh, "key", SV *value,
+\&                          U32 flags)
+\& COPHH *  cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
+\&                          SV *value, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cop_hints_exists_pv""" 4
+.el .IP \f(CWcop_hints_exists_pv\fR 4
+.IX Item "cop_hints_exists_pv"
+.PD 0
+.ie n .IP """cop_hints_exists_pvn""" 4
+.el .IP \f(CWcop_hints_exists_pvn\fR 4
+.IX Item "cop_hints_exists_pvn"
+.ie n .IP """cop_hints_exists_pvs""" 4
+.el .IP \f(CWcop_hints_exists_pvs\fR 4
+.IX Item "cop_hints_exists_pvs"
+.ie n .IP """cop_hints_exists_sv""" 4
+.el .IP \f(CWcop_hints_exists_sv\fR 4
+.IX Xref "cop_hints_exists_pv cop_hints_exists_pvn cop_hints_exists_pvs cop_hints_exists_sv"
+.IX Item "cop_hints_exists_sv"
+.PD
+These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
+\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists,
+and false otherwise.
+.Sp
+The forms differ in how the key is specified.  In all forms, the key is pointed
+to by \f(CW\*(C`key\*(C'\fR.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 7
+\& bool  cop_hints_exists_pv (const COP *cop, const char *key,
+\&                            U32 hash, U32 flags)
+\& bool  cop_hints_exists_pvn(const COP *cop, const char *key,
+\&                            STRLEN keylen, U32 hash, U32 flags)
+\& bool  cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
+\& bool  cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
+\&                            U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cop_hints_fetch_pv""" 4
+.el .IP \f(CWcop_hints_fetch_pv\fR 4
+.IX Item "cop_hints_fetch_pv"
+.PD 0
+.ie n .IP """cop_hints_fetch_pvn""" 4
+.el .IP \f(CWcop_hints_fetch_pvn\fR 4
+.IX Item "cop_hints_fetch_pvn"
+.ie n .IP """cop_hints_fetch_pvs""" 4
+.el .IP \f(CWcop_hints_fetch_pvs\fR 4
+.IX Item "cop_hints_fetch_pvs"
+.ie n .IP """cop_hints_fetch_sv""" 4
+.el .IP \f(CWcop_hints_fetch_sv\fR 4
+.IX Xref "cop_hints_fetch_pv cop_hints_fetch_pvn cop_hints_fetch_pvs cop_hints_fetch_sv"
+.IX Item "cop_hints_fetch_sv"
+.PD
+These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
+\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal
+scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
+key.
+.Sp
+The forms differ in how the key is specified.
+In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
+In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
+In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
+using \f(CW"SvPV_const"\fR.
+.Sp
+\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
+automatically at compile time.
+.Sp
+The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
+It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form.  In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
+whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
+cleared).  The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
+the octets.
+.RS 4
+.Sp
+.Vb 7
+\& SV *  cop_hints_fetch_pv (const COP *cop, const char *key,
+\&                           U32 hash, U32 flags)
+\& SV *  cop_hints_fetch_pvn(const COP *cop, const char *key,
+\&                           STRLEN keylen, U32 hash, U32 flags)
+\& SV *  cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
+\& SV *  cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
+\&                           U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cop_hints_2hv""" 4
+.el .IP \f(CWcop_hints_2hv\fR 4
+.IX Xref "cop_hints_2hv"
+.IX Item "cop_hints_2hv"
+Generates and returns a standard Perl hash representing the full set of
+hint entries in the cop \f(CW\*(C`cop\*(C'\fR.  \f(CW\*(C`flags\*(C'\fR is currently unused and must
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  cop_hints_2hv(const COP *cop, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopLABEL""" 4
+.el .IP \f(CWCopLABEL\fR 4
+.IX Item "CopLABEL"
+.PD 0
+.ie n .IP """CopLABEL_len""" 4
+.el .IP \f(CWCopLABEL_len\fR 4
+.IX Item "CopLABEL_len"
+.ie n .IP """CopLABEL_len_flags""" 4
+.el .IP \f(CWCopLABEL_len_flags\fR 4
+.IX Xref "CopLABEL CopLABEL_len CopLABEL_len_flags"
+.IX Item "CopLABEL_len_flags"
+.PD
+These return the label attached to a cop.
+.Sp
+\&\f(CW\*(C`CopLABEL_len\*(C'\fR and \f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally store the number of
+bytes comprising the returned label into \f(CW*len\fR.
+.Sp
+\&\f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally returns the UTF\-8ness of the returned label,
+by setting \f(CW*flags\fR to 0 or \f(CW\*(C`SVf_UTF8\*(C'\fR.
+.RS 4
+.Sp
+.Vb 4
+\& const char *  CopLABEL          (COP *const cop)
+\& const char *  CopLABEL_len      (COP *const cop, STRLEN *len)
+\& const char *  CopLABEL_len_flags(COP *const cop, STRLEN *len,
+\&                                  U32 *flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopLINE""" 4
+.el .IP \f(CWCopLINE\fR 4
+.IX Xref "CopLINE"
+.IX Item "CopLINE"
+Returns the line number in the source code associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& line_t  CopLINE(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopSTASH""" 4
+.el .IP \f(CWCopSTASH\fR 4
+.IX Xref "CopSTASH"
+.IX Item "CopSTASH"
+Returns the stash associated with \f(CW\*(C`c\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  CopSTASH(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopSTASH_eq""" 4
+.el .IP \f(CWCopSTASH_eq\fR 4
+.IX Xref "CopSTASH_eq"
+.IX Item "CopSTASH_eq"
+Returns a boolean as to whether or not \f(CW\*(C`hv\*(C'\fR is the stash associated with \f(CW\*(C`c\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  CopSTASH_eq(const COP * c, const HV * hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopSTASHPV""" 4
+.el .IP \f(CWCopSTASHPV\fR 4
+.IX Xref "CopSTASHPV"
+.IX Item "CopSTASHPV"
+Returns the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if no
+associated stash
+.RS 4
+.Sp
+.Vb 1
+\& char *  CopSTASHPV(const COP * c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopSTASHPV_set""" 4
+.el .IP \f(CWCopSTASHPV_set\fR 4
+.IX Xref "CopSTASHPV_set"
+.IX Item "CopSTASHPV_set"
+Set the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, to the NUL-terminated C
+string \f(CW\*(C`p\*(C'\fR, creating the package if necessary.
+.RS 4
+.Sp
+.Vb 1
+\& void  CopSTASHPV_set(COP * c, const char * pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CopSTASH_set""" 4
+.el .IP \f(CWCopSTASH_set\fR 4
+.IX Xref "CopSTASH_set"
+.IX Item "CopSTASH_set"
+Set the stash associated with \f(CW\*(C`c\*(C'\fR to \f(CW\*(C`hv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  CopSTASH_set(COP * c, HV * hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cop_store_label""" 4
+.el .IP \f(CWcop_store_label\fR 4
+.IX Xref "cop_store_label"
+.IX Item "cop_store_label"
+NOTE: \f(CW\*(C`cop_store_label\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Save a label into a \f(CW\*(C`cop_hints_hash\*(C'\fR.
+You need to set flags to \f(CW\*(C`SVf_UTF8\*(C'\fR
+for a UTF\-8 label.  Any other flag is ignored.
+.RS 4
+.Sp
+.Vb 2
+\& void  cop_store_label(COP * const cop, const char *label,
+\&                       STRLEN len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_SI""" 4
+.el .IP \f(CWPERL_SI\fR 4
+.IX Xref "PERL_SI"
+.IX Item "PERL_SI"
+Use this typedef to declare variables that are to hold \f(CW\*(C`struct stackinfo\*(C'\fR.
+.ie n .IP """PL_curcop""" 4
+.el .IP \f(CWPL_curcop\fR 4
+.IX Xref "PL_curcop"
+.IX Item "PL_curcop"
+The currently active COP (control op) roughly representing the current
+statement in the source.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& COP*  PL_curcop
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RCPV_LEN""" 4
+.el .IP \f(CWRCPV_LEN\fR 4
+.IX Xref "RCPV_LEN"
+.IX Item "RCPV_LEN"
+Returns the length of a pv created with \f(CWrcpv_new()\fR.
+Note that this reflects the length of the string from the callers
+point of view, it does not include the mandatory null which is
+always injected at the end of the string by \fBrcpv_new()\fR.
+No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
+with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
+this is the case.
+.RS 4
+.Sp
+.Vb 1
+\& RCPV *  RCPV_LEN(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RCPV_REFCNT_dec""" 4
+.el .IP \f(CWRCPV_REFCNT_dec\fR 4
+.IX Xref "RCPV_REFCNT_dec"
+.IX Item "RCPV_REFCNT_dec"
+Decrements the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
+with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_free()\fR.
+No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
+with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
+this is the case.
+.RS 4
+.Sp
+.Vb 1
+\& RCPV *  RCPV_REFCNT_dec(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RCPV_REFCNT_inc""" 4
+.el .IP \f(CWRCPV_REFCNT_inc\fR 4
+.IX Xref "RCPV_REFCNT_inc"
+.IX Item "RCPV_REFCNT_inc"
+Increments the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
+with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_copy()\fR.
+No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
+with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
+this is the case.
+.RS 4
+.Sp
+.Vb 1
+\& RCPV *  RCPV_REFCNT_inc(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RCPV_REFCOUNT""" 4
+.el .IP \f(CWRCPV_REFCOUNT\fR 4
+.IX Xref "RCPV_REFCOUNT"
+.IX Item "RCPV_REFCOUNT"
+Returns the refcount for a pv created with \f(CWrcpv_new()\fR. 
+No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
+with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
+this is the case.
+.RS 4
+.Sp
+.Vb 1
+\& RCPV *  RCPV_REFCOUNT(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RCPVx""" 4
+.el .IP \f(CWRCPVx\fR 4
+.IX Xref "RCPVx"
+.IX Item "RCPVx"
+Returns the RCPV structure (struct rcpv) for a refcounted
+string pv created with \f(CWrcpv_new()\fR.
+No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
+with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
+this is the case.
+.RS 4
+.Sp
+.Vb 1
+\& RCPV *  RCPVx(char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Custom Operators"
+.IX Header "Custom Operators"
+.ie n .IP """custom_op_register""" 4
+.el .IP \f(CWcustom_op_register\fR 4
+.IX Xref "custom_op_register"
+.IX Item "custom_op_register"
+Register a custom op.  See "Custom Operators" in perlguts.
+.Sp
+NOTE: \f(CW\*(C`custom_op_register\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_custom_op_register\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
+\&                               const XOP *xop)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Perl_custom_op_xop""" 4
+.el .IP \f(CWPerl_custom_op_xop\fR 4
+.IX Xref "Perl_custom_op_xop"
+.IX Item "Perl_custom_op_xop"
+Return the XOP structure for a given custom op.  This macro should be
+considered internal to \f(CW\*(C`OP_NAME\*(C'\fR and the other access macros: use them instead.
+This macro does call a function.  Prior
+to 5.19.6, this was implemented as a
+function.
+.RS 4
+.Sp
+.Vb 1
+\& const XOP *  Perl_custom_op_xop(pTHX_ const OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopDISABLE""" 4
+.el .IP \f(CWXopDISABLE\fR 4
+.IX Xref "XopDISABLE"
+.IX Item "XopDISABLE"
+Temporarily disable a member of the XOP, by clearing the appropriate flag.
+.RS 4
+.Sp
+.Vb 1
+\& void  XopDISABLE(XOP *xop, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopENABLE""" 4
+.el .IP \f(CWXopENABLE\fR 4
+.IX Xref "XopENABLE"
+.IX Item "XopENABLE"
+Reenable a member of the XOP which has been disabled.
+.RS 4
+.Sp
+.Vb 1
+\& void  XopENABLE(XOP *xop, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopENTRY""" 4
+.el .IP \f(CWXopENTRY\fR 4
+.IX Xref "XopENTRY"
+.IX Item "XopENTRY"
+Return a member of the XOP structure.  \f(CW\*(C`which\*(C'\fR is a cpp token
+indicating which entry to return.  If the member is not set
+this will return a default value.  The return type depends
+on \f(CW\*(C`which\*(C'\fR.  This macro evaluates its arguments more than
+once.  If you are using \f(CW\*(C`Perl_custom_op_xop\*(C'\fR to retrieve a
+\&\f(CW\*(C`XOP *\*(C'\fR from a \f(CW\*(C`OP *\*(C'\fR, use the more efficient "XopENTRYCUSTOM" instead.
+.RS 4
+.Sp
+.Vb 1
+\&   XopENTRY(XOP *xop, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopENTRYCUSTOM""" 4
+.el .IP \f(CWXopENTRYCUSTOM\fR 4
+.IX Xref "XopENTRYCUSTOM"
+.IX Item "XopENTRYCUSTOM"
+Exactly like \f(CW\*(C`XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)\*(C'\fR but more
+efficient.  The \f(CW\*(C`which\*(C'\fR parameter is identical to "XopENTRY".
+.RS 4
+.Sp
+.Vb 1
+\&   XopENTRYCUSTOM(const OP *o, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopENTRY_set""" 4
+.el .IP \f(CWXopENTRY_set\fR 4
+.IX Xref "XopENTRY_set"
+.IX Item "XopENTRY_set"
+Set a member of the XOP structure.  \f(CW\*(C`which\*(C'\fR is a cpp token
+indicating which entry to set.  See "Custom Operators" in perlguts
+for details about the available members and how
+they are used.  This macro evaluates its argument
+more than once.
+.RS 4
+.Sp
+.Vb 1
+\& void  XopENTRY_set(XOP *xop, token which, value)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XopFLAGS""" 4
+.el .IP \f(CWXopFLAGS\fR 4
+.IX Xref "XopFLAGS"
+.IX Item "XopFLAGS"
+Return the XOP's flags.
+.RS 4
+.Sp
+.Vb 1
+\& U32  XopFLAGS(XOP *xop)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "CV Handling"
+.IX Xref "CV GV_ADD"
+.IX Header "CV Handling"
+This section documents functions to manipulate CVs which are
+code-values, meaning subroutines.  For more information, see
+perlguts.
+.ie n .IP """caller_cx""" 4
+.el .IP \f(CWcaller_cx\fR 4
+.IX Xref "caller_cx"
+.IX Item "caller_cx"
+The XSUB-writer's equivalent of \fBcaller()\fR.  The
+returned \f(CW\*(C`PERL_CONTEXT\*(C'\fR structure can be interrogated to find all the
+information returned to Perl by \f(CW\*(C`caller\*(C'\fR.  Note that XSUBs don't get a
+stack frame, so \f(CW\*(C`caller_cx(0, NULL)\*(C'\fR will return information for the
+immediately-surrounding Perl code.
+.Sp
+This function skips over the automatic calls to \f(CW&DB::sub\fR made on the
+behalf of the debugger.  If the stack frame requested was a sub called by
+\&\f(CW\*(C`DB::sub\*(C'\fR, the return value will be the frame for the call to
+\&\f(CW\*(C`DB::sub\*(C'\fR, since that has the correct line number/etc. for the call
+site.  If \fIdbcxp\fR is non\-\f(CW\*(C`NULL\*(C'\fR, it will be set to a pointer to the
+frame for the sub call itself.
+.RS 4
+.Sp
+.Vb 2
+\& const PERL_CONTEXT *  caller_cx(I32 level,
+\&                                 const PERL_CONTEXT **dbcxp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvDEPTH""" 4
+.el .IP \f(CWCvDEPTH\fR 4
+.IX Xref "CvDEPTH"
+.IX Item "CvDEPTH"
+Returns the recursion level of the CV \f(CW\*(C`sv\*(C'\fR.  Hence >= 2 indicates we are in a
+recursive call.
+.RS 4
+.Sp
+.Vb 1
+\& I32 *  CvDEPTH(const CV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvGV""" 4
+.el .IP \f(CWCvGV\fR 4
+.IX Xref "CvGV"
+.IX Item "CvGV"
+Returns the GV associated with the CV \f(CW\*(C`sv\*(C'\fR, reifying it if necessary.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  CvGV(CV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvSTASH""" 4
+.el .IP \f(CWCvSTASH\fR 4
+.IX Xref "CvSTASH"
+.IX Item "CvSTASH"
+Returns the stash of the CV.  A stash is the symbol table hash, containing
+the package-scoped variables in the package where the subroutine was defined.
+For more information, see perlguts.
+.Sp
+This also has a special use with XS AUTOLOAD subs.
+See "Autoloading with XSUBs" in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  CvSTASH(CV* cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """find_runcv""" 4
+.el .IP \f(CWfind_runcv\fR 4
+.IX Xref "find_runcv"
+.IX Item "find_runcv"
+Locate the CV corresponding to the currently executing sub or eval.
+If \f(CW\*(C`db_seqp\*(C'\fR is non_null, skip CVs that are in the DB package and populate
+\&\f(CW*db_seqp\fR with the cop sequence number at the point that the DB:: code was
+entered.  (This allows debuggers to eval in the scope of the breakpoint
+rather than in the scope of the debugger itself.)
+.RS 4
+.Sp
+.Vb 1
+\& CV *  find_runcv(U32 *db_seqp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_cv""" 4
+.el .IP \f(CWget_cv\fR 4
+.IX Item "get_cv"
+.PD 0
+.ie n .IP """get_cvn_flags""" 4
+.el .IP \f(CWget_cvn_flags\fR 4
+.IX Item "get_cvn_flags"
+.ie n .IP """get_cvs""" 4
+.el .IP \f(CWget_cvs\fR 4
+.IX Xref "get_cv get_cvn_flags get_cvs"
+.IX Item "get_cvs"
+.PD
+These return the CV of the specified Perl subroutine.  \f(CW\*(C`flags\*(C'\fR are passed to
+\&\f(CW\*(C`gv_fetchpvn_flags\*(C'\fR.  If \f(CW\*(C`GV_ADD\*(C'\fR is set and the Perl subroutine does not
+exist then it will be declared (which has the same effect as saying
+\&\f(CW\*(C`sub name;\*(C'\fR).  If \f(CW\*(C`GV_ADD\*(C'\fR is not set and the subroutine does not exist,
+then NULL is returned.
+.Sp
+The forms differ only in how the subroutine is specified..  With \f(CW\*(C`get_cvs\*(C'\fR,
+the name is a literal C string, enclosed in double quotes.  With \f(CW\*(C`get_cv\*(C'\fR, the
+name is given by the \f(CW\*(C`name\*(C'\fR parameter, which must be a NUL-terminated C
+string.  With \f(CW\*(C`get_cvn_flags\*(C'\fR, the name is also given by the \f(CW\*(C`name\*(C'\fR
+parameter, but it is a Perl string (possibly containing embedded NUL bytes),
+and its length in bytes is contained in the \f(CW\*(C`len\*(C'\fR parameter.
+.Sp
+NOTE: the \f(CWperl_get_cv()\fR form is \fBdeprecated\fR.
+.Sp
+NOTE: the \f(CWperl_get_cvn_flags()\fR form is \fBdeprecated\fR.
+.Sp
+NOTE: the \f(CWperl_get_cvs()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 3
+\& CV *  get_cv       (const char *name, I32 flags)
+\& CV *  get_cvn_flags(const char *name, STRLEN len, I32 flags)
+\& CV *  get_cvs      ("string", I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Nullcv""" 4
+.el .IP \f(CWNullcv\fR 4
+.IX Xref "Nullcv"
+.IX Item "Nullcv"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`Nullcv\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Null CV pointer.
+.Sp
+(deprecated \- use \f(CW\*(C`(CV *)NULL\*(C'\fR instead)
+.SH Debugging
+.IX Header "Debugging"
+.ie n .IP """av_dump""" 4
+.el .IP \f(CWav_dump\fR 4
+.IX Xref "av_dump"
+.IX Item "av_dump"
+Dumps the contents of an AV to the \f(CW\*(C`STDERR\*(C'\fR filehandle,
+Similar to using Devel::Peek on an arrayref but does not
+expect an RV wrapper. Dumps contents to a depth of 3 levels
+deep.
+.RS 4
+.Sp
+.Vb 1
+\& void  av_dump(AV *av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """deb""" 4
+.el .IP \f(CWdeb\fR 4
+.IX Item "deb"
+.PD 0
+.ie n .IP """deb_nocontext""" 4
+.el .IP \f(CWdeb_nocontext\fR 4
+.IX Xref "deb deb_nocontext"
+.IX Item "deb_nocontext"
+.PD
+When perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, this prints to STDERR the
+information given by the arguments, prefaced by the name of the file containing
+the script causing the call, and the line number within that file.
+.Sp
+If the \f(CW\*(C`v\*(C'\fR (verbose) debugging option is in effect, the process id is also
+printed.
+.Sp
+The two forms differ only in that \f(CW\*(C`deb_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`deb\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_deb\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_deb     (pTHX_ const char *pat, ...)
+\& void  deb_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """debstack""" 4
+.el .IP \f(CWdebstack\fR 4
+.IX Xref "debstack"
+.IX Item "debstack"
+Dump the current stack
+.RS 4
+.Sp
+.Vb 1
+\& I32  debstack()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_all""" 4
+.el .IP \f(CWdump_all\fR 4
+.IX Xref "dump_all"
+.IX Item "dump_all"
+Dumps the entire optree of the current program starting at \f(CW\*(C`PL_main_root\*(C'\fR to 
+\&\f(CW\*(C`STDERR\*(C'\fR.  Also dumps the optrees for all visible subroutines in
+\&\f(CW\*(C`PL_defstash\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_all()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_c_backtrace""" 4
+.el .IP \f(CWdump_c_backtrace\fR 4
+.IX Xref "dump_c_backtrace"
+.IX Item "dump_c_backtrace"
+Dumps the C backtrace to the given \f(CW\*(C`fp\*(C'\fR.
+.Sp
+Returns true if a backtrace could be retrieved, false if not.
+.RS 4
+.Sp
+.Vb 1
+\& bool  dump_c_backtrace(PerlIO *fp, int max_depth, int skip)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_eval""" 4
+.el .IP \f(CWdump_eval\fR 4
+.IX Item "dump_eval"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_eval()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_form""" 4
+.el .IP \f(CWdump_form\fR 4
+.IX Xref "dump_form"
+.IX Item "dump_form"
+Dumps the contents of the format contained in the GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR, or a
+message that one doesn't exist.
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_form(const GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_packsubs""" 4
+.el .IP \f(CWdump_packsubs\fR 4
+.IX Xref "dump_packsubs"
+.IX Item "dump_packsubs"
+Dumps the optrees for all visible subroutines in \f(CW\*(C`stash\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_packsubs(const HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dump_sub""" 4
+.el .IP \f(CWdump_sub\fR 4
+.IX Item "dump_sub"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_sub(const GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_c_backtrace_dump""" 4
+.el .IP \f(CWget_c_backtrace_dump\fR 4
+.IX Xref "get_c_backtrace_dump"
+.IX Item "get_c_backtrace_dump"
+Returns a SV containing a dump of \f(CW\*(C`depth\*(C'\fR frames of the call stack, skipping
+the \f(CW\*(C`skip\*(C'\fR innermost ones.  \f(CW\*(C`depth\*(C'\fR of 20 is usually enough.
+.Sp
+The appended output looks like:
+.Sp
+.Vb 4
+\& ...
+\& 1   10e004812:0082   Perl_croak   util.c:1716    /usr/bin/perl
+\& 2   10df8d6d2:1d72   perl_parse   perl.c:3975    /usr/bin/perl
+\& ...
+.Ve
+.Sp
+The fields are tab-separated.  The first column is the depth (zero
+being the innermost non-skipped frame).  In the hex:offset, the hex is
+where the program counter was in \f(CW\*(C`S_parse_body\*(C'\fR, and the :offset (might
+be missing) tells how much inside the \f(CW\*(C`S_parse_body\*(C'\fR the program counter was.
+.Sp
+The \f(CW\*(C`util.c:1716\*(C'\fR is the source code file and line number.
+.Sp
+The \fI/usr/bin/perl\fR is obvious (hopefully).
+.Sp
+Unknowns are \f(CW"\-"\fR.  Unknowns can happen unfortunately quite easily:
+if the platform doesn't support retrieving the information;
+if the binary is missing the debug information;
+if the optimizer has transformed the code by for example inlining.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  get_c_backtrace_dump(int max_depth, int skip)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_dump""" 4
+.el .IP \f(CWgv_dump\fR 4
+.IX Xref "gv_dump"
+.IX Item "gv_dump"
+Dump the name and, if they differ, the effective name of the GV \f(CW\*(C`gv\*(C'\fR to
+\&\f(CW\*(C`STDERR\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  gv_dump(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HAS_BACKTRACE""" 4
+.el .IP \f(CWHAS_BACKTRACE\fR 4
+.IX Xref "HAS_BACKTRACE"
+.IX Item "HAS_BACKTRACE"
+This symbol, if defined, indicates that the \f(CWbacktrace()\fR routine is
+available to get a stack trace.  The \fIexecinfo.h\fR header must be
+included to use this routine.
+.ie n .IP """hv_dump""" 4
+.el .IP \f(CWhv_dump\fR 4
+.IX Xref "hv_dump"
+.IX Item "hv_dump"
+Dumps the contents of an HV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
+Similar to using Devel::Peek on an hashref but does not
+expect an RV wrapper. Dumps contents to a depth of 3 levels
+deep.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_dump(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """magic_dump""" 4
+.el .IP \f(CWmagic_dump\fR 4
+.IX Xref "magic_dump"
+.IX Item "magic_dump"
+Dumps the contents of the MAGIC \f(CW\*(C`mg\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  magic_dump(const MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_class""" 4
+.el .IP \f(CWop_class\fR 4
+.IX Xref "op_class"
+.IX Item "op_class"
+Given an op, determine what type of struct it has been allocated as.
+Returns one of the OPclass enums, such as OPclass_LISTOP.
+.RS 4
+.Sp
+.Vb 1
+\& OPclass  op_class(const OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_dump""" 4
+.el .IP \f(CWop_dump\fR 4
+.IX Xref "op_dump"
+.IX Item "op_dump"
+Dumps the optree starting at OP \f(CW\*(C`o\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  op_dump(const OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_op""" 4
+.el .IP \f(CWPL_op\fR 4
+.IX Item "PL_op"
+Described in perlhacktips.
+.ie n .IP """PL_runops""" 4
+.el .IP \f(CWPL_runops\fR 4
+.IX Item "PL_runops"
+Described in perlguts.
+.ie n .IP """PL_sv_serial""" 4
+.el .IP \f(CWPL_sv_serial\fR 4
+.IX Item "PL_sv_serial"
+Described in perlhacktips.
+.ie n .IP """pmop_dump""" 4
+.el .IP \f(CWpmop_dump\fR 4
+.IX Xref "pmop_dump"
+.IX Item "pmop_dump"
+Dump an OP that is related to Pattern Matching, such as \f(CW\*(C`s/foo/bar/\*(C'\fR; these require
+special handling.
+.RS 4
+.Sp
+.Vb 1
+\& void  pmop_dump(PMOP *pm)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_dump""" 4
+.el .IP \f(CWsv_dump\fR 4
+.IX Xref "sv_dump"
+.IX Item "sv_dump"
+Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
+.Sp
+For an example of its output, see Devel::Peek. If
+the item is an SvROK it will dump items to a depth of 4,
+otherwise it will dump only the top level item, which
+means that it will not dump the contents of an AV * or
+HV *. For that use \f(CWav_dump()\fR or \f(CWhv_dump()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_dump(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_dump_depth""" 4
+.el .IP \f(CWsv_dump_depth\fR 4
+.IX Xref "sv_dump_depth"
+.IX Item "sv_dump_depth"
+Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle
+to the depth requested. This function can be used on any
+SV derived type (GV, HV, AV) with an appropriate cast.
+This is a more flexible variant of \fBsv_dump()\fR. For example
+.Sp
+.Vb 2
+\&    HV *hv = ...;
+\&    sv_dump_depth((SV*)hv, 2);
+.Ve
+.Sp
+would dump the hv, its keys and values, but would not recurse
+into any RV values.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_dump_depth(SV *sv, I32 depth)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vdeb""" 4
+.el .IP \f(CWvdeb\fR 4
+.IX Xref "vdeb"
+.IX Item "vdeb"
+This is like \f(CW"deb"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
+.RS 4
+.Sp
+.Vb 1
+\& void  vdeb(const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Display functions"
+.IX Xref "PERL_PV_ESCAPE_ALL PERL_PV_ESCAPE_FIRSTCHAR PERL_PV_ESCAPE_NOBACKSLASH PERL_PV_ESCAPE_NOCLEAR PERL_PV_ESCAPE_NONASCII PERL_PV_ESCAPE_NON_WC PERL_PV_ESCAPE_QUOTE PERL_PV_ESCAPE_RE PERL_PV_ESCAPE_UNI PERL_PV_ESCAPE_UNI_DETECT PERL_PV_PRETTY_ELLIPSES PERL_PV_PRETTY_LTGT PERL_PV_PRETTY_QUOTE"
+.IX Header "Display functions"
+.ie n .IP """form""" 4
+.el .IP \f(CWform\fR 4
+.IX Item "form"
+.PD 0
+.ie n .IP """form_nocontext""" 4
+.el .IP \f(CWform_nocontext\fR 4
+.IX Xref "form form_nocontext"
+.IX Item "form_nocontext"
+.PD
+These take a sprintf-style format pattern and conventional
+(non-SV) arguments and return the formatted string.
+.Sp
+.Vb 1
+\&    (char *) Perl_form(pTHX_ const char* pat, ...)
+.Ve
+.Sp
+can be used any place a string (char *) is required:
+.Sp
+.Vb 1
+\&    char * s = Perl_form("%d.%d",major,minor);
+.Ve
+.Sp
+They use a single (per-thread) private buffer so if you want to format several
+strings you must explicitly copy the earlier strings away (and free the copies
+when you are done).
+.Sp
+The two forms differ only in that \f(CW\*(C`form_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`form\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_form\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& char *  Perl_form     (pTHX_ const char *pat, ...)
+\& char *  form_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mess""" 4
+.el .IP \f(CWmess\fR 4
+.IX Item "mess"
+.PD 0
+.ie n .IP """mess_nocontext""" 4
+.el .IP \f(CWmess_nocontext\fR 4
+.IX Xref "mess mess_nocontext"
+.IX Item "mess_nocontext"
+.PD
+These take a sprintf-style format pattern and argument list, which are used to
+generate a string message.  If the message does not end with a newline, then it
+will be extended with some indication of the current location in the code, as
+described for \f(CW"mess_sv"\fR.
+.Sp
+Normally, the resulting message is returned in a new mortal SV.
+But during global destruction a single SV may be shared between uses of
+this function.
+.Sp
+The two forms differ only in that \f(CW\*(C`mess_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`mess\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mess\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  Perl_mess     (pTHX_ const char *pat, ...)
+\& SV *  mess_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mess_sv""" 4
+.el .IP \f(CWmess_sv\fR 4
+.IX Xref "mess_sv"
+.IX Item "mess_sv"
+Expands a message, intended for the user, to include an indication of
+the current location in the code, if the message does not already appear
+to be complete.
+.Sp
+\&\f(CW\*(C`basemsg\*(C'\fR is the initial message or object.  If it is a reference, it
+will be used as-is and will be the result of this function.  Otherwise it
+is used as a string, and if it already ends with a newline, it is taken
+to be complete, and the result of this function will be the same string.
+If the message does not end with a newline, then a segment such as \f(CW\*(C`at
+foo.pl line 37\*(C'\fR will be appended, and possibly other clauses indicating
+the current state of execution.  The resulting message will end with a
+dot and a newline.
+.Sp
+Normally, the resulting message is returned in a new mortal SV.
+During global destruction a single SV may be shared between uses of this
+function.  If \f(CW\*(C`consume\*(C'\fR is true, then the function is permitted (but not
+required) to modify and return \f(CW\*(C`basemsg\*(C'\fR instead of allocating a new SV.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  mess_sv(SV *basemsg, bool consume)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pv_display""" 4
+.el .IP \f(CWpv_display\fR 4
+.IX Xref "pv_display"
+.IX Item "pv_display"
+Similar to
+.Sp
+.Vb 1
+\&  pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
+.Ve
+.Sp
+except that an additional "\e0" will be appended to the string when
+len > cur and pv[cur] is "\e0".
+.Sp
+Note that the final string may be up to 7 chars longer than pvlim.
+.RS 4
+.Sp
+.Vb 2
+\& char *  pv_display(SV *dsv, const char *pv, STRLEN cur,
+\&                    STRLEN len, STRLEN pvlim)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pv_escape""" 4
+.el .IP \f(CWpv_escape\fR 4
+.IX Xref "pv_escape"
+.IX Item "pv_escape"
+Escapes at most the first \f(CW\*(C`count\*(C'\fR chars of \f(CW\*(C`pv\*(C'\fR and puts the results into
+\&\f(CW\*(C`dsv\*(C'\fR such that the size of the escaped string will not exceed \f(CW\*(C`max\*(C'\fR chars
+and will not contain any incomplete escape sequences.  The number of bytes
+escaped will be returned in the \f(CW\*(C`STRLEN *escaped\*(C'\fR parameter if it is not null.
+When the \f(CW\*(C`dsv\*(C'\fR parameter is null no escaping actually occurs, but the number
+of bytes that would be escaped were it not null will be calculated.
+.Sp
+If flags contains \f(CW\*(C`PERL_PV_ESCAPE_QUOTE\*(C'\fR then any double quotes in the string
+will also be escaped.
+.Sp
+Normally the SV will be cleared before the escaped string is prepared,
+but when \f(CW\*(C`PERL_PV_ESCAPE_NOCLEAR\*(C'\fR is set this will not occur.
+.Sp
+If \f(CW\*(C`PERL_PV_ESCAPE_UNI\*(C'\fR is set then the input string is treated as UTF\-8.
+If \f(CW\*(C`PERL_PV_ESCAPE_UNI_DETECT\*(C'\fR is set then the input string is scanned
+using \f(CWis_utf8_string()\fR to determine if it is UTF\-8.
+.Sp
+If \f(CW\*(C`PERL_PV_ESCAPE_ALL\*(C'\fR is set then all input chars will be output
+using \f(CW\*(C`\ex01F1\*(C'\fR style escapes, otherwise if \f(CW\*(C`PERL_PV_ESCAPE_NONASCII\*(C'\fR
+is set, only non-ASCII chars will be escaped using this style;
+otherwise, only chars above 255 will be so escaped; other non printable
+chars will use octal or common escaped patterns like \f(CW\*(C`\en\*(C'\fR. Otherwise,
+if \f(CW\*(C`PERL_PV_ESCAPE_NOBACKSLASH\*(C'\fR then all chars below 255 will be
+treated as printable and will be output as literals. The
+\&\f(CW\*(C`PERL_PV_ESCAPE_NON_WC\*(C'\fR modifies the previous rules to cause word
+chars, unicode or otherwise, to be output as literals, note this uses
+the *unicode* rules for deciding on word characters.
+.Sp
+If \f(CW\*(C`PERL_PV_ESCAPE_FIRSTCHAR\*(C'\fR is set then only the first char of the
+string will be escaped, regardless of max. If the output is to be in
+hex, then it will be returned as a plain hex sequence. Thus the output
+will either be a single char, an octal escape sequence, a special escape
+like \f(CW\*(C`\en\*(C'\fR or a hex value.
+.Sp
+If \f(CW\*(C`PERL_PV_ESCAPE_RE\*(C'\fR is set then the escape char used will be a
+\&\f(CW"%"\fR and not a \f(CW"\e\e"\fR. This is because regexes very often contain
+backslashed sequences, whereas \f(CW"%"\fR is not a particularly common
+character in patterns.
+.Sp
+Returns a pointer to the escaped text as held by \f(CW\*(C`dsv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& char *  pv_escape(SV *dsv, char const * const str,
+\&                   const STRLEN count, STRLEN max,
+\&                   STRLEN * const escaped, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pv_pretty""" 4
+.el .IP \f(CWpv_pretty\fR 4
+.IX Xref "pv_pretty"
+.IX Item "pv_pretty"
+Converts a string into something presentable, handling escaping via
+\&\f(CWpv_escape()\fR and supporting quoting and ellipses.
+.Sp
+If the \f(CW\*(C`PERL_PV_PRETTY_QUOTE\*(C'\fR flag is set then the result will be
+double quoted with any double quotes in the string escaped.  Otherwise
+if the \f(CW\*(C`PERL_PV_PRETTY_LTGT\*(C'\fR flag is set then the result be wrapped in
+angle brackets.
+.Sp
+If the \f(CW\*(C`PERL_PV_PRETTY_ELLIPSES\*(C'\fR flag is set and not all characters in
+string were output then an ellipsis \f(CW\*(C`...\*(C'\fR will be appended to the
+string.  Note that this happens AFTER it has been quoted.
+.Sp
+If \f(CW\*(C`start_color\*(C'\fR is non-null then it will be inserted after the opening
+quote (if there is one) but before the escaped text.  If \f(CW\*(C`end_color\*(C'\fR
+is non-null then it will be inserted after the escaped text but before
+any quotes or ellipses.
+.Sp
+Returns a pointer to the prettified text as held by \f(CW\*(C`dsv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 4
+\& char *  pv_pretty(SV *dsv, char const * const str,
+\&                   const STRLEN count, const STRLEN max,
+\&                   char const * const start_color,
+\&                   char const * const end_color, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vform""" 4
+.el .IP \f(CWvform\fR 4
+.IX Xref "vform"
+.IX Item "vform"
+Like \f(CW"form"\fR but but the arguments are an encapsulated argument list.
+.RS 4
+.Sp
+.Vb 1
+\& char *  vform(const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vmess""" 4
+.el .IP \f(CWvmess\fR 4
+.IX Xref "vmess"
+.IX Item "vmess"
+\&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated
+argument list, respectively.  These are used to generate a string message.  If
+the
+message does not end with a newline, then it will be extended with
+some indication of the current location in the code, as described for
+"mess_sv".
+.Sp
+Normally, the resulting message is returned in a new mortal SV.
+During global destruction a single SV may be shared between uses of
+this function.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vmess(const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Embedding, Threads, and Interpreter Cloning"
+.IX Xref "CV_NAME_NOTQUAL PADNAMEf_OUTER PERL_EXIT_ABORT PERL_EXIT_DESTRUCT_END PERL_EXIT_EXPECTED PERL_EXIT_WARN PERL_LOADMOD_DENY PERL_LOADMOD_IMPORT_OPS PERL_LOADMOD_NOIMPORT"
+.IX Header "Embedding, Threads, and Interpreter Cloning"
+.ie n .IP """call_atexit""" 4
+.el .IP \f(CWcall_atexit\fR 4
+.IX Xref "call_atexit"
+.IX Item "call_atexit"
+Add a function \f(CW\*(C`fn\*(C'\fR to the list of functions to be called at global
+destruction.  \f(CW\*(C`ptr\*(C'\fR will be passed as an argument to \f(CW\*(C`fn\*(C'\fR; it can point to a
+\&\f(CW\*(C`struct\*(C'\fR so that you can pass anything you want.
+.Sp
+Note that under threads, \f(CW\*(C`fn\*(C'\fR may run multiple times.  This is because the
+list is executed each time the current or any descendent thread terminates.
+.RS 4
+.Sp
+.Vb 1
+\& void  call_atexit(ATEXIT_t fn, void *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_clone""" 4
+.el .IP \f(CWcv_clone\fR 4
+.IX Xref "cv_clone"
+.IX Item "cv_clone"
+Clone a CV, making a lexical closure.  \f(CW\*(C`proto\*(C'\fR supplies the prototype
+of the function: its code, pad structure, and other attributes.
+The prototype is combined with a capture of outer lexicals to which the
+code refers, which are taken from the currently-executing instance of
+the immediately surrounding code.
+.RS 4
+.Sp
+.Vb 1
+\& CV *  cv_clone(CV *proto)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_name""" 4
+.el .IP \f(CWcv_name\fR 4
+.IX Xref "cv_name"
+.IX Item "cv_name"
+Returns an SV containing the name of the CV, mainly for use in error
+reporting.  The CV may actually be a GV instead, in which case the returned
+SV holds the GV's name.  Anything other than a GV or CV is treated as a
+string already holding the sub name, but this could change in the future.
+.Sp
+An SV may be passed as a second argument.  If so, the name will be assigned
+to it and it will be returned.  Otherwise the returned SV will be a new
+mortal.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`CV_NAME_NOTQUAL\*(C'\fR bit set, then the package name will not be
+included.  If the first argument is neither a CV nor a GV, this flag is
+ignored (subject to change).
+.RS 4
+.Sp
+.Vb 1
+\& SV *  cv_name(CV *cv, SV *sv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_undef""" 4
+.el .IP \f(CWcv_undef\fR 4
+.IX Xref "cv_undef"
+.IX Item "cv_undef"
+Clear out all the active components of a CV.  This can happen either
+by an explicit \f(CW\*(C`undef &foo\*(C'\fR, or by the reference count going to zero.
+In the former case, we keep the \f(CW\*(C`CvOUTSIDE\*(C'\fR pointer, so that any anonymous
+children can still follow the full lexical scope chain.
+.RS 4
+.Sp
+.Vb 1
+\& void  cv_undef(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """find_rundefsv""" 4
+.el .IP \f(CWfind_rundefsv\fR 4
+.IX Xref "find_rundefsv"
+.IX Item "find_rundefsv"
+Returns the global variable \f(CW$_\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  find_rundefsv()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_op_descs""" 4
+.el .IP \f(CWget_op_descs\fR 4
+.IX Xref "get_op_descs"
+.IX Item "get_op_descs"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`get_op_descs\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Return a pointer to the array of all the descriptions of the various OPs
+Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_desc[opcode]\*(C'\fR returns a
+pointer to a C language string giving its description.
+.RS 4
+.Sp
+.Vb 1
+\& char **  get_op_descs()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_op_names""" 4
+.el .IP \f(CWget_op_names\fR 4
+.IX Xref "get_op_names"
+.IX Item "get_op_names"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`get_op_names\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Return a pointer to the array of all the names of the various OPs
+Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_name[opcode]\*(C'\fR returns a
+pointer to a C language string giving its name.
+.RS 4
+.Sp
+.Vb 1
+\& char **  get_op_names()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HAS_SKIP_LOCALE_INIT""" 4
+.el .IP \f(CWHAS_SKIP_LOCALE_INIT\fR 4
+.IX Item "HAS_SKIP_LOCALE_INIT"
+Described in perlembed.
+.ie n .IP """intro_my""" 4
+.el .IP \f(CWintro_my\fR 4
+.IX Xref "intro_my"
+.IX Item "intro_my"
+"Introduce" \f(CW\*(C`my\*(C'\fR variables to visible status.  This is called during parsing
+at the end of each statement to make lexical variables visible to subsequent
+statements.
+.RS 4
+.Sp
+.Vb 1
+\& U32  intro_my()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """load_module""" 4
+.el .IP \f(CWload_module\fR 4
+.IX Item "load_module"
+.PD 0
+.ie n .IP """load_module_nocontext""" 4
+.el .IP \f(CWload_module_nocontext\fR 4
+.IX Xref "load_module load_module_nocontext"
+.IX Item "load_module_nocontext"
+.PD
+These load the module whose name is pointed to by the string part of \f(CW\*(C`name\*(C'\fR.
+Note that the actual module name, not its filename, should be given.
+Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if specified and not NULL,
+provides version semantics similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional
+trailing arguments can be used to specify arguments to the module's \f(CWimport()\fR
+method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR; their precise handling depends
+on the flags. The flags argument is a bitwise-ORed collection of any of
+\&\f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR, \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR, or \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR
+(or 0 for no flags).
+.Sp
+If \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR is set, the module is loaded as if with an empty
+import list, as in \f(CW\*(C`use Foo::Bar ()\*(C'\fR; this is the only circumstance in which
+the trailing optional arguments may be omitted entirely. Otherwise, if
+\&\f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is set, the trailing arguments must consist of
+exactly one \f(CW\*(C`OP*\*(C'\fR, containing the op tree that produces the relevant import
+arguments. Otherwise, the trailing arguments must all be \f(CW\*(C`SV*\*(C'\fR values that
+will be used as import arguments; and the list must be terminated with \f(CW\*(C`(SV*)
+NULL\*(C'\fR. If neither \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR nor \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is
+set, the trailing \f(CW\*(C`NULL\*(C'\fR pointer is needed even if no import arguments are
+desired. The reference count for each specified \f(CW\*(C`SV*\*(C'\fR argument is
+decremented. In addition, the \f(CW\*(C`name\*(C'\fR argument is modified.
+.Sp
+If \f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR is set, the module is loaded as if with \f(CW\*(C`no\*(C'\fR rather
+than \f(CW\*(C`use\*(C'\fR.
+.Sp
+\&\f(CW\*(C`load_module\*(C'\fR and \f(CW\*(C`load_module_nocontext\*(C'\fR have the same apparent signature,
+but the former hides the fact that it is accessing a thread context parameter.
+So use the latter when you get a compilation error about \f(CW\*(C`pTHX\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  load_module          (U32 flags, SV *name, SV *ver, ...)
+\& void  load_module_nocontext(U32 flags, SV *name, SV *ver, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_exit""" 4
+.el .IP \f(CWmy_exit\fR 4
+.IX Xref "my_exit"
+.IX Item "my_exit"
+A wrapper for the C library \fBexit\fR\|(3), honoring what "PL_exit_flags" in perlapi
+say to do.
+.RS 4
+.Sp
+.Vb 1
+\& void  my_exit(U32 status)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_failure_exit""" 4
+.el .IP \f(CWmy_failure_exit\fR 4
+.IX Xref "my_failure_exit"
+.IX Item "my_failure_exit"
+Exit the running Perl process with an error.
+.Sp
+On non-VMS platforms, this is essentially equivalent to "\f(CW\*(C`my_exit\*(C'\fR", using
+\&\f(CW\*(C`errno\*(C'\fR, but forces an en error code of 255 if \f(CW\*(C`errno\*(C'\fR is 0.
+.Sp
+On VMS, it takes care to set the appropriate severity bits in the exit status.
+.RS 4
+.Sp
+.Vb 1
+\& void  my_failure_exit()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_strlcat""" 4
+.el .IP \f(CWmy_strlcat\fR 4
+.IX Xref "my_strlcat"
+.IX Item "my_strlcat"
+The C library \f(CW\*(C`strlcat\*(C'\fR if available, or a Perl implementation of it.
+This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
+.Sp
+\&\f(CWmy_strlcat()\fR appends string \f(CW\*(C`src\*(C'\fR to the end of \f(CW\*(C`dst\*(C'\fR.  It will append at
+most \f(CW\*(C`size\ \-\ strlen(dst)\ \-\ 1\*(C'\fR characters.  It will then \f(CW\*(C`NUL\*(C'\fR\-terminate,
+unless \f(CW\*(C`size\*(C'\fR is 0 or the original \f(CW\*(C`dst\*(C'\fR string was longer than \f(CW\*(C`size\*(C'\fR (in
+practice this should not happen as it means that either \f(CW\*(C`size\*(C'\fR is incorrect or
+that \f(CW\*(C`dst\*(C'\fR is not a proper \f(CW\*(C`NUL\*(C'\fR\-terminated string).
+.Sp
+Note that \f(CW\*(C`size\*(C'\fR is the full size of the destination buffer and
+the result is guaranteed to be \f(CW\*(C`NUL\*(C'\fR\-terminated if there is room.  Note that
+room for the \f(CW\*(C`NUL\*(C'\fR should be included in \f(CW\*(C`size\*(C'\fR.
+.Sp
+The return value is the total length that \f(CW\*(C`dst\*(C'\fR would have if \f(CW\*(C`size\*(C'\fR is
+sufficiently large.  Thus it is the initial length of \f(CW\*(C`dst\*(C'\fR plus the length of
+\&\f(CW\*(C`src\*(C'\fR.  If \f(CW\*(C`size\*(C'\fR is smaller than the return, the excess was not appended.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  my_strlcat(char *dst, const char *src, Size_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_strlcpy""" 4
+.el .IP \f(CWmy_strlcpy\fR 4
+.IX Xref "my_strlcpy"
+.IX Item "my_strlcpy"
+The C library \f(CW\*(C`strlcpy\*(C'\fR if available, or a Perl implementation of it.
+This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
+.Sp
+\&\f(CWmy_strlcpy()\fR copies up to \f(CW\*(C`size\ \-\ 1\*(C'\fR characters from the string \f(CW\*(C`src\*(C'\fR
+to \f(CW\*(C`dst\*(C'\fR, \f(CW\*(C`NUL\*(C'\fR\-terminating the result if \f(CW\*(C`size\*(C'\fR is not 0.
+.Sp
+The return value is the total length \f(CW\*(C`src\*(C'\fR would be if the copy completely
+succeeded.  If it is larger than \f(CW\*(C`size\*(C'\fR, the excess was not copied.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  my_strlcpy(char *dst, const char *src, Size_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPADNAMELIST""" 4
+.el .IP \f(CWnewPADNAMELIST\fR 4
+.IX Xref "newPADNAMELIST"
+.IX Item "newPADNAMELIST"
+NOTE: \f(CW\*(C`newPADNAMELIST\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Creates a new pad name list.  \f(CW\*(C`max\*(C'\fR is the highest index for which space
+is allocated.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAMELIST *  newPADNAMELIST(size_t max)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPADNAMEouter""" 4
+.el .IP \f(CWnewPADNAMEouter\fR 4
+.IX Xref "newPADNAMEouter"
+.IX Item "newPADNAMEouter"
+NOTE: \f(CW\*(C`newPADNAMEouter\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Constructs and returns a new pad name.  Only use this function for names
+that refer to outer lexicals.  (See also "newPADNAMEpvn".)  \f(CW\*(C`outer\*(C'\fR is
+the outer pad name that this one mirrors.  The returned pad name has the
+\&\f(CW\*(C`PADNAMEf_OUTER\*(C'\fR flag already set.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME *  newPADNAMEouter(PADNAME *outer)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPADNAMEpvn""" 4
+.el .IP \f(CWnewPADNAMEpvn\fR 4
+.IX Xref "newPADNAMEpvn"
+.IX Item "newPADNAMEpvn"
+NOTE: \f(CW\*(C`newPADNAMEpvn\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Constructs and returns a new pad name.  \f(CW\*(C`s\*(C'\fR must be a UTF\-8 string.  Do not
+use this for pad names that point to outer lexicals.  See
+\&\f(CW"newPADNAMEouter"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME *  newPADNAMEpvn(const char *s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """nothreadhook""" 4
+.el .IP \f(CWnothreadhook\fR 4
+.IX Xref "nothreadhook"
+.IX Item "nothreadhook"
+Stub that provides thread hook for perl_destruct when there are
+no threads.
+.RS 4
+.Sp
+.Vb 1
+\& int  nothreadhook()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_add_anon""" 4
+.el .IP \f(CWpad_add_anon\fR 4
+.IX Xref "pad_add_anon"
+.IX Item "pad_add_anon"
+Allocates a place in the currently-compiling pad (via "pad_alloc")
+for an anonymous function that is lexically scoped inside the
+currently-compiling function.
+The function \f(CW\*(C`func\*(C'\fR is linked into the pad, and its \f(CW\*(C`CvOUTSIDE\*(C'\fR link
+to the outer scope is weakened to avoid a reference loop.
+.Sp
+One reference count is stolen, so you may need to do \f(CWSvREFCNT_inc(func)\fR.
+.Sp
+\&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
+pad entry is to support.  This doesn't affect operational semantics,
+but is used for debugging.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  pad_add_anon(CV *func, I32 optype)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_add_name_pv""" 4
+.el .IP \f(CWpad_add_name_pv\fR 4
+.IX Xref "pad_add_name_pv"
+.IX Item "pad_add_name_pv"
+Exactly like "pad_add_name_pvn", but takes a nul-terminated string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& PADOFFSET  pad_add_name_pv(const char *name, const U32 flags,
+\&                            HV *typestash, HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_add_name_pvn""" 4
+.el .IP \f(CWpad_add_name_pvn\fR 4
+.IX Xref "pad_add_name_pvn"
+.IX Item "pad_add_name_pvn"
+Allocates a place in the currently-compiling pad for a named lexical
+variable.  Stores the name and other metadata in the name part of the
+pad, and makes preparations to manage the variable's lexical scoping.
+Returns the offset of the allocated pad slot.
+.Sp
+\&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name, including leading sigil.
+If \f(CW\*(C`typestash\*(C'\fR is non-null, the name is for a typed lexical, and this
+identifies the type.  If \f(CW\*(C`ourstash\*(C'\fR is non-null, it's a lexical reference
+to a package variable, and this identifies the package.  The following
+flags can be OR'ed together:
+.Sp
+.Vb 4
+\& padadd_OUR          redundantly specifies if it\*(Aqs a package var
+\& padadd_STATE        variable will retain value persistently
+\& padadd_NO_DUP_CHECK skip check for lexical shadowing
+\& padadd_FIELD        specifies that the lexical is a field for a class
+.Ve
+.RS 4
+.Sp
+.Vb 3
+\& PADOFFSET  pad_add_name_pvn(const char *namepv, STRLEN namelen,
+\&                             U32 flags, HV *typestash,
+\&                             HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_add_name_sv""" 4
+.el .IP \f(CWpad_add_name_sv\fR 4
+.IX Xref "pad_add_name_sv"
+.IX Item "pad_add_name_sv"
+Exactly like "pad_add_name_pvn", but takes the name string in the form
+of an SV instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& PADOFFSET  pad_add_name_sv(SV *name, U32 flags, HV *typestash,
+\&                            HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_alloc""" 4
+.el .IP \f(CWpad_alloc\fR 4
+.IX Xref "pad_alloc"
+.IX Item "pad_alloc"
+NOTE: \f(CW\*(C`pad_alloc\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Allocates a place in the currently-compiling pad,
+returning the offset of the allocated pad slot.
+No name is initially attached to the pad slot.
+\&\f(CW\*(C`tmptype\*(C'\fR is a set of flags indicating the kind of pad entry required,
+which will be set in the value SV for the allocated pad entry:
+.Sp
+.Vb 3
+\&    SVs_PADMY    named lexical variable ("my", "our", "state")
+\&    SVs_PADTMP   unnamed temporary store
+\&    SVf_READONLY constant shared between recursion levels
+.Ve
+.Sp
+\&\f(CW\*(C`SVf_READONLY\*(C'\fR has been supported here only since perl 5.20.  To work with
+earlier versions as well, use \f(CW\*(C`SVf_READONLY|SVs_PADTMP\*(C'\fR.  \f(CW\*(C`SVf_READONLY\*(C'\fR
+does not cause the SV in the pad slot to be marked read-only, but simply
+tells \f(CW\*(C`pad_alloc\*(C'\fR that it \fIwill\fR be made read-only (by the caller), or at
+least should be treated as such.
+.Sp
+\&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
+pad entry is to support.  This doesn't affect operational semantics,
+but is used for debugging.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  pad_alloc(I32 optype, U32 tmptype)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_findmy_pv""" 4
+.el .IP \f(CWpad_findmy_pv\fR 4
+.IX Xref "pad_findmy_pv"
+.IX Item "pad_findmy_pv"
+Exactly like "pad_findmy_pvn", but takes a nul-terminated string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  pad_findmy_pv(const char *name, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_findmy_pvn""" 4
+.el .IP \f(CWpad_findmy_pvn\fR 4
+.IX Xref "pad_findmy_pvn"
+.IX Item "pad_findmy_pvn"
+Given the name of a lexical variable, find its position in the
+currently-compiling pad.
+\&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name, including leading sigil.
+\&\f(CW\*(C`flags\*(C'\fR is reserved and must be zero.
+If it is not in the current pad but appears in the pad of any lexically
+enclosing scope, then a pseudo-entry for it is added in the current pad.
+Returns the offset in the current pad,
+or \f(CW\*(C`NOT_IN_PAD\*(C'\fR if no such lexical is in scope.
+.RS 4
+.Sp
+.Vb 2
+\& PADOFFSET  pad_findmy_pvn(const char *namepv, STRLEN namelen,
+\&                           U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_findmy_sv""" 4
+.el .IP \f(CWpad_findmy_sv\fR 4
+.IX Xref "pad_findmy_sv"
+.IX Item "pad_findmy_sv"
+Exactly like "pad_findmy_pvn", but takes the name string in the form
+of an SV instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  pad_findmy_sv(SV *name, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """padnamelist_fetch""" 4
+.el .IP \f(CWpadnamelist_fetch\fR 4
+.IX Xref "padnamelist_fetch"
+.IX Item "padnamelist_fetch"
+NOTE: \f(CW\*(C`padnamelist_fetch\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Fetches the pad name from the given index.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME *  padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """padnamelist_store""" 4
+.el .IP \f(CWpadnamelist_store\fR 4
+.IX Xref "padnamelist_store"
+.IX Item "padnamelist_store"
+NOTE: \f(CW\*(C`padnamelist_store\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Stores the pad name (which may be null) at the given index, freeing any
+existing pad name in that slot.
+.RS 4
+.Sp
+.Vb 2
+\& PADNAME **  padnamelist_store(PADNAMELIST *pnl, SSize_t key,
+\&                               PADNAME *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_tidy""" 4
+.el .IP \f(CWpad_tidy\fR 4
+.IX Xref "pad_tidy"
+.IX Item "pad_tidy"
+NOTE: \f(CW\*(C`pad_tidy\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Tidy up a pad at the end of compilation of the code to which it belongs.
+Jobs performed here are: remove most stuff from the pads of anonsub
+prototypes; give it a \f(CW@_\fR; mark temporaries as such.  \f(CW\*(C`type\*(C'\fR indicates
+the kind of subroutine:
+.Sp
+.Vb 3
+\&    padtidy_SUB        ordinary subroutine
+\&    padtidy_SUBCLONE   prototype for lexical closure
+\&    padtidy_FORMAT     format
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_tidy(padtidy_type type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_alloc""" 4
+.el .IP \f(CWperl_alloc\fR 4
+.IX Xref "perl_alloc"
+.IX Item "perl_alloc"
+Allocates a new Perl interpreter.  See perlembed.
+.RS 4
+.Sp
+.Vb 1
+\& PerlInterpreter *  perl_alloc()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_ASYNC_CHECK""" 4
+.el .IP \f(CWPERL_ASYNC_CHECK\fR 4
+.IX Item "PERL_ASYNC_CHECK"
+Described in perlinterp.
+.RS 4
+.Sp
+.Vb 1
+\& void  PERL_ASYNC_CHECK()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_clone""" 4
+.el .IP \f(CWperl_clone\fR 4
+.IX Xref "perl_clone"
+.IX Item "perl_clone"
+Create and return a new interpreter by cloning the current one.
+.Sp
+\&\f(CW\*(C`perl_clone\*(C'\fR takes these flags as parameters:
+.Sp
+\&\f(CW\*(C`CLONEf_COPY_STACKS\*(C'\fR \- is used to, well, copy the stacks also,
+without it we only clone the data and zero the stacks,
+with it we copy the stacks and the new perl interpreter is
+ready to run at the exact same point as the previous one.
+The pseudo-fork code uses \f(CW\*(C`COPY_STACKS\*(C'\fR while the
+threads\->create doesn't.
+.Sp
+\&\f(CW\*(C`CLONEf_KEEP_PTR_TABLE\*(C'\fR \-
+\&\f(CW\*(C`perl_clone\*(C'\fR keeps a ptr_table with the pointer of the old
+variable as a key and the new variable as a value,
+this allows it to check if something has been cloned and not
+clone it again, but rather just use the value and increase the
+refcount.
+If \f(CW\*(C`KEEP_PTR_TABLE\*(C'\fR is not set then \f(CW\*(C`perl_clone\*(C'\fR will kill the ptr_table
+using the function \f(CW\*(C`ptr_table_free(PL_ptr_table);\ PL_ptr_table\ =\ NULL;\*(C'\fR.
+A reason to keep it around is if you want to dup some of your own
+variables which are outside the graph that perl scans.
+.Sp
+\&\f(CW\*(C`CLONEf_CLONE_HOST\*(C'\fR \-
+This is a win32 thing, it is ignored on unix, it tells perl's
+win32host code (which is c++) to clone itself, this is needed on
+win32 if you want to run two threads at the same time,
+if you just want to do some stuff in a separate perl interpreter
+and then throw it away and return to the original one,
+you don't need to do anything.
+.RS 4
+.Sp
+.Vb 2
+\& PerlInterpreter *  perl_clone(PerlInterpreter *proto_perl,
+\&                               UV flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_construct""" 4
+.el .IP \f(CWperl_construct\fR 4
+.IX Xref "perl_construct"
+.IX Item "perl_construct"
+Initializes a new Perl interpreter.  See perlembed.
+.RS 4
+.Sp
+.Vb 1
+\& void  perl_construct(PerlInterpreter *my_perl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_destruct""" 4
+.el .IP \f(CWperl_destruct\fR 4
+.IX Xref "perl_destruct"
+.IX Item "perl_destruct"
+Shuts down a Perl interpreter.  See perlembed for a tutorial.
+.Sp
+\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter.  It must have been previously
+created through the use of "perl_alloc" and "perl_construct".  It may
+have been initialised through "perl_parse", and may have been used
+through "perl_run" and other means.  This function should be called for
+any Perl interpreter that has been constructed with "perl_construct",
+even if subsequent operations on it failed, for example if "perl_parse"
+returned a non-zero value.
+.Sp
+If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word has the
+\&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function will execute code
+in \f(CW\*(C`END\*(C'\fR blocks before performing the rest of destruction.  If it is
+desired to make any use of the interpreter between "perl_parse" and
+"perl_destruct" other than just calling "perl_run", then this flag
+should be set early on.  This matters if "perl_run" will not be called,
+or if anything else will be done in addition to calling "perl_run".
+.Sp
+Returns a value be a suitable value to pass to the C library function
+\&\f(CW\*(C`exit\*(C'\fR (or to return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating
+the nature of the way the interpreter terminated.  This takes into account
+any failure of "perl_parse" and any early exit from "perl_run".
+The exit code is of the type required by the host operating system,
+so because of differing exit code conventions it is not portable to
+interpret specific numeric values as having specific meanings.
+.RS 4
+.Sp
+.Vb 1
+\& int  perl_destruct(PerlInterpreter *my_perl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_free""" 4
+.el .IP \f(CWperl_free\fR 4
+.IX Xref "perl_free"
+.IX Item "perl_free"
+Releases a Perl interpreter.  See perlembed.
+.RS 4
+.Sp
+.Vb 1
+\& void  perl_free(PerlInterpreter *my_perl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_GET_CONTEXT""" 4
+.el .IP \f(CWPERL_GET_CONTEXT\fR 4
+.IX Item "PERL_GET_CONTEXT"
+Described in perlguts.
+.ie n .IP """PerlInterpreter""" 4
+.el .IP \f(CWPerlInterpreter\fR 4
+.IX Item "PerlInterpreter"
+Described in perlembed.
+.ie n .IP """perl_parse""" 4
+.el .IP \f(CWperl_parse\fR 4
+.IX Xref "perl_parse"
+.IX Item "perl_parse"
+Tells a Perl interpreter to parse a Perl script.  This performs most
+of the initialisation of a Perl interpreter.  See perlembed for
+a tutorial.
+.Sp
+\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter that is to parse the script.
+It must have been previously created through the use of "perl_alloc"
+and "perl_construct".  \f(CW\*(C`xsinit\*(C'\fR points to a callback function that
+will be called to set up the ability for this Perl interpreter to load
+XS extensions, or may be null to perform no such setup.
+.Sp
+\&\f(CW\*(C`argc\*(C'\fR and \f(CW\*(C`argv\*(C'\fR supply a set of command-line arguments to the Perl
+interpreter, as would normally be passed to the \f(CW\*(C`main\*(C'\fR function of
+a C program.  \f(CW\*(C`argv[argc]\*(C'\fR must be null.  These arguments are where
+the script to parse is specified, either by naming a script file or by
+providing a script in a \f(CW\*(C`\-e\*(C'\fR option.
+If \f(CW$0\fR will be written to in the Perl interpreter, then
+the argument strings must be in writable memory, and so mustn't just be
+string constants.
+.Sp
+\&\f(CW\*(C`env\*(C'\fR specifies a set of environment variables that will be used by
+this Perl interpreter.  If non-null, it must point to a null-terminated
+array of environment strings.  If null, the Perl interpreter will use
+the environment supplied by the \f(CW\*(C`environ\*(C'\fR global variable.
+.Sp
+This function initialises the interpreter, and parses and compiles the
+script specified by the command-line arguments.  This includes executing
+code in \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, and \f(CW\*(C`CHECK\*(C'\fR blocks.  It does not execute
+\&\f(CW\*(C`INIT\*(C'\fR blocks or the main program.
+.Sp
+Returns an integer of slightly tricky interpretation.  The correct
+use of the return value is as a truth value indicating whether there
+was a failure in initialisation.  If zero is returned, this indicates
+that initialisation was successful, and it is safe to proceed to call
+"perl_run" and make other use of it.  If a non-zero value is returned,
+this indicates some problem that means the interpreter wants to terminate.
+The interpreter should not be just abandoned upon such failure; the caller
+should proceed to shut the interpreter down cleanly with "perl_destruct"
+and free it with "perl_free".
+.Sp
+For historical reasons, the non-zero return value also attempts to
+be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
+return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature
+of the way initialisation terminated.  However, this isn't portable,
+due to differing exit code conventions.  An attempt is made to return
+an exit code of the type required by the host operating system, but
+because it is constrained to be non-zero, it is not necessarily possible
+to indicate every type of exit.  It is only reliable on Unix, where a
+zero exit code can be augmented with a set bit that will be ignored.
+In any case, this function is not the correct place to acquire an exit
+code: one should get that from "perl_destruct".
+.RS 4
+.Sp
+.Vb 2
+\& int  perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
+\&                 int argc, char **argv, char **env)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """perl_run""" 4
+.el .IP \f(CWperl_run\fR 4
+.IX Xref "perl_run"
+.IX Item "perl_run"
+Tells a Perl interpreter to run its main program.  See perlembed
+for a tutorial.
+.Sp
+\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter.  It must have been previously
+created through the use of "perl_alloc" and "perl_construct", and
+initialised through "perl_parse".  This function should not be called
+if "perl_parse" returned a non-zero value, indicating a failure in
+initialisation or compilation.
+.Sp
+This function executes code in \f(CW\*(C`INIT\*(C'\fR blocks, and then executes the
+main program.  The code to be executed is that established by the prior
+call to "perl_parse".  If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word
+does not have the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function
+will also execute code in \f(CW\*(C`END\*(C'\fR blocks.  If it is desired to make any
+further use of the interpreter after calling this function, then \f(CW\*(C`END\*(C'\fR
+blocks should be postponed to "perl_destruct" time by setting that flag.
+.Sp
+Returns an integer of slightly tricky interpretation.  The correct use
+of the return value is as a truth value indicating whether the program
+terminated non-locally.  If zero is returned, this indicates that
+the program ran to completion, and it is safe to make other use of the
+interpreter (provided that the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag was set as
+described above).  If a non-zero value is returned, this indicates that
+the interpreter wants to terminate early.  The interpreter should not be
+just abandoned because of this desire to terminate; the caller should
+proceed to shut the interpreter down cleanly with "perl_destruct"
+and free it with "perl_free".
+.Sp
+For historical reasons, the non-zero return value also attempts to
+be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
+return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature of
+the way the program terminated.  However, this isn't portable, due to
+differing exit code conventions.  An attempt is made to return an exit
+code of the type required by the host operating system, but because
+it is constrained to be non-zero, it is not necessarily possible to
+indicate every type of exit.  It is only reliable on Unix, where a zero
+exit code can be augmented with a set bit that will be ignored.  In any
+case, this function is not the correct place to acquire an exit code:
+one should get that from "perl_destruct".
+.RS 4
+.Sp
+.Vb 1
+\& int  perl_run(PerlInterpreter *my_perl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_SET_CONTEXT""" 4
+.el .IP \f(CWPERL_SET_CONTEXT\fR 4
+.IX Item "PERL_SET_CONTEXT"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  PERL_SET_CONTEXT(PerlInterpreter* i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_SYS_INIT""" 4
+.el .IP \f(CWPERL_SYS_INIT\fR 4
+.IX Item "PERL_SYS_INIT"
+.PD 0
+.ie n .IP """PERL_SYS_INIT3""" 4
+.el .IP \f(CWPERL_SYS_INIT3\fR 4
+.IX Xref "PERL_SYS_INIT PERL_SYS_INIT3"
+.IX Item "PERL_SYS_INIT3"
+.PD
+These provide system-specific tune up of the C runtime environment necessary to
+run Perl interpreters.  Only one should be used, and it should be called only
+once, before creating any Perl interpreters.
+.Sp
+They differ in that \f(CW\*(C`PERL_SYS_INIT3\*(C'\fR also initializes \f(CW\*(C`env\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  PERL_SYS_INIT (int *argc, char*** argv)
+\& void  PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_SYS_TERM""" 4
+.el .IP \f(CWPERL_SYS_TERM\fR 4
+.IX Xref "PERL_SYS_TERM"
+.IX Item "PERL_SYS_TERM"
+Provides system-specific clean up of the C runtime environment after
+running Perl interpreters.  This should be called only once, after
+freeing any remaining Perl interpreters.
+.RS 4
+.Sp
+.Vb 1
+\& void  PERL_SYS_TERM()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_exit_flags""" 4
+.el .IP \f(CWPL_exit_flags\fR 4
+.IX Xref "PL_exit_flags"
+.IX Item "PL_exit_flags"
+Contains flags controlling perl's behaviour on \fBexit()\fR:
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR
+.Sp
+If set, END blocks are executed when the interpreter is destroyed.
+This is normally set by perl itself after the interpreter is
+constructed.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_EXIT_ABORT\*(C'\fR
+.Sp
+Call \f(CWabort()\fR on exit.  This is used internally by perl itself to
+abort if exit is called while processing exit.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR
+.Sp
+Warn on exit.
+.IP \(bu 4
+\&\f(CW\*(C`PERL_EXIT_EXPECTED\*(C'\fR
+.Sp
+Set by the "exit" in perlfunc operator.
+.RE
+.RS 4
+.Sp
+.Vb 1
+\& U8  PL_exit_flags
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_origalen""" 4
+.el .IP \f(CWPL_origalen\fR 4
+.IX Item "PL_origalen"
+Described in perlembed.
+.ie n .IP """PL_perl_destruct_level""" 4
+.el .IP \f(CWPL_perl_destruct_level\fR 4
+.IX Xref "PL_perl_destruct_level"
+.IX Item "PL_perl_destruct_level"
+This value may be set when embedding for full cleanup.
+.Sp
+Possible values:
+.RS 4
+.IP \(bu 4
+0 \- none
+.IP \(bu 4
+1 \- full
+.IP \(bu 4
+2 or greater \- full with checks.
+.RE
+.RS 4
+.Sp
+If \f(CW$ENV{PERL_DESTRUCT_LEVEL}\fR is set to an integer greater than the
+value of \f(CW\*(C`PL_perl_destruct_level\*(C'\fR its value is used instead.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.Sp
+.Vb 1
+\& signed char  PL_perl_destruct_level
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ptr_table_fetch""" 4
+.el .IP \f(CWptr_table_fetch\fR 4
+.IX Xref "ptr_table_fetch"
+.IX Item "ptr_table_fetch"
+Look for \f(CW\*(C`sv\*(C'\fR in the pointer-mapping table \f(CW\*(C`tbl\*(C'\fR, returning its value, or
+NULL if not found.
+.RS 4
+.Sp
+.Vb 2
+\& void *  ptr_table_fetch(PTR_TBL_t * const tbl,
+\&                         const void * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ptr_table_free""" 4
+.el .IP \f(CWptr_table_free\fR 4
+.IX Xref "ptr_table_free"
+.IX Item "ptr_table_free"
+Clear and free a ptr table
+.RS 4
+.Sp
+.Vb 1
+\& void  ptr_table_free(PTR_TBL_t * const tbl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ptr_table_new""" 4
+.el .IP \f(CWptr_table_new\fR 4
+.IX Xref "ptr_table_new"
+.IX Item "ptr_table_new"
+Create a new pointer-mapping table
+.RS 4
+.Sp
+.Vb 1
+\& PTR_TBL_t *  ptr_table_new()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ptr_table_split""" 4
+.el .IP \f(CWptr_table_split\fR 4
+.IX Xref "ptr_table_split"
+.IX Item "ptr_table_split"
+Double the hash bucket size of an existing ptr table
+.RS 4
+.Sp
+.Vb 1
+\& void  ptr_table_split(PTR_TBL_t * const tbl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ptr_table_store""" 4
+.el .IP \f(CWptr_table_store\fR 4
+.IX Xref "ptr_table_store"
+.IX Item "ptr_table_store"
+Add a new entry to a pointer-mapping table \f(CW\*(C`tbl\*(C'\fR.
+In hash terms, \f(CW\*(C`oldsv\*(C'\fR is the key; Cnewsv> is the value.
+.Sp
+The names "old" and "new" are specific to the core's typical use of ptr_tables
+in thread cloning.
+.RS 4
+.Sp
+.Vb 3
+\& void  ptr_table_store(PTR_TBL_t * const tbl,
+\&                       const void * const oldsv,
+\&                       void * const newsv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """require_pv""" 4
+.el .IP \f(CWrequire_pv\fR 4
+.IX Xref "require_pv"
+.IX Item "require_pv"
+Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument.  It is
+analogous to the Perl code \f(CW\*(C`eval "require \*(Aq$file\*(Aq"\*(C'\fR.  It's even
+implemented that way; consider using load_module instead.
+.Sp
+NOTE: the \f(CWperl_require_pv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  require_pv(const char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vload_module""" 4
+.el .IP \f(CWvload_module\fR 4
+.IX Xref "vload_module"
+.IX Item "vload_module"
+Like \f(CW"load_module"\fR but the arguments are an encapsulated argument list.
+.RS 4
+.Sp
+.Vb 1
+\& void  vload_module(U32 flags, SV *name, SV *ver, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Errno
+.IX Header "Errno"
+.ie n .IP """sv_string_from_errnum""" 4
+.el .IP \f(CWsv_string_from_errnum\fR 4
+.IX Xref "sv_string_from_errnum"
+.IX Item "sv_string_from_errnum"
+Generates the message string describing an OS error and returns it as
+an SV.  \f(CW\*(C`errnum\*(C'\fR must be a value that \f(CW\*(C`errno\*(C'\fR could take, identifying
+the type of error.
+.Sp
+If \f(CW\*(C`tgtsv\*(C'\fR is non-null then the string will be written into that SV
+(overwriting existing content) and it will be returned.  If \f(CW\*(C`tgtsv\*(C'\fR
+is a null pointer then the string will be written into a new mortal SV
+which will be returned.
+.Sp
+The message will be taken from whatever locale would be used by \f(CW$!\fR,
+and will be encoded in the SV in whatever manner would be used by \f(CW$!\fR.
+The details of this process are subject to future change.  Currently,
+the message is taken from the C locale by default (usually producing an
+English message), and from the currently selected locale when in the scope
+of the \f(CW\*(C`use locale\*(C'\fR pragma.  A heuristic attempt is made to decode the
+message from the locale's character encoding, but it will only be decoded
+as either UTF\-8 or ISO\-8859\-1.  It is always correctly decoded in a UTF\-8
+locale, usually in an ISO\-8859\-1 locale, and never in any other locale.
+.Sp
+The SV is always returned containing an actual string, and with no other
+OK bits set.  Unlike \f(CW$!\fR, a message is even yielded for \f(CW\*(C`errnum\*(C'\fR zero
+(meaning success), and if no useful message is available then a useless
+string (currently empty) is returned.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_string_from_errnum(int errnum, SV *tgtsv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Exception Handling (simple) Macros"
+.IX Header "Exception Handling (simple) Macros"
+.ie n .IP """dXCPT""" 4
+.el .IP \f(CWdXCPT\fR 4
+.IX Xref "dXCPT"
+.IX Item "dXCPT"
+Set up necessary local variables for exception handling.
+See "Exception Handling" in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   dXCPT;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """JMPENV_JUMP""" 4
+.el .IP \f(CWJMPENV_JUMP\fR 4
+.IX Item "JMPENV_JUMP"
+Described in perlinterp.
+.RS 4
+.Sp
+.Vb 1
+\& void  JMPENV_JUMP(int v)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """JMPENV_PUSH""" 4
+.el .IP \f(CWJMPENV_PUSH\fR 4
+.IX Item "JMPENV_PUSH"
+Described in perlinterp.
+.RS 4
+.Sp
+.Vb 1
+\& void  JMPENV_PUSH(int v)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_restartop""" 4
+.el .IP \f(CWPL_restartop\fR 4
+.IX Item "PL_restartop"
+Described in perlinterp.
+.ie n .IP """XCPT_CATCH""" 4
+.el .IP \f(CWXCPT_CATCH\fR 4
+.IX Xref "XCPT_CATCH"
+.IX Item "XCPT_CATCH"
+Introduces a catch block.  See "Exception Handling" in perlguts.
+.ie n .IP """XCPT_RETHROW""" 4
+.el .IP \f(CWXCPT_RETHROW\fR 4
+.IX Xref "XCPT_RETHROW"
+.IX Item "XCPT_RETHROW"
+Rethrows a previously caught exception.  See "Exception Handling" in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   XCPT_RETHROW;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XCPT_TRY_END""" 4
+.el .IP \f(CWXCPT_TRY_END\fR 4
+.IX Xref "XCPT_TRY_END"
+.IX Item "XCPT_TRY_END"
+Ends a try block.  See "Exception Handling" in perlguts.
+.ie n .IP """XCPT_TRY_START""" 4
+.el .IP \f(CWXCPT_TRY_START\fR 4
+.IX Xref "XCPT_TRY_START"
+.IX Item "XCPT_TRY_START"
+Starts a try block.  See "Exception Handling" in perlguts.
+.SH "Filesystem configuration values"
+.IX Header "Filesystem configuration values"
+Also see "List of capability HAS_foo symbols".
+.ie n .IP """DIRNAMLEN""" 4
+.el .IP \f(CWDIRNAMLEN\fR 4
+.IX Xref "DIRNAMLEN"
+.IX Item "DIRNAMLEN"
+This symbol, if defined, indicates to the C program that the length
+of directory entry names is provided by a \f(CW\*(C`d_namlen\*(C'\fR field.  Otherwise
+you need to do \f(CWstrlen()\fR on the \f(CW\*(C`d_name\*(C'\fR field.
+.ie n .IP """DOSUID""" 4
+.el .IP \f(CWDOSUID\fR 4
+.IX Xref "DOSUID"
+.IX Item "DOSUID"
+This symbol, if defined, indicates that the C program should
+check the script that it is executing for setuid/setgid bits, and
+attempt to emulate setuid/setgid on systems that have disabled
+setuid #! scripts because the kernel can't do it securely.
+It is up to the package designer to make sure that this emulation
+is done securely.  Among other things, it should do an fstat on
+the script it just opened to make sure it really is a setuid/setgid
+script, it should make sure the arguments passed correspond exactly
+to the argument on the #! line, and it should not trust any
+subprocesses to which it must pass the filename rather than the
+file descriptor of the script to be executed.
+.ie n .IP """EOF_NONBLOCK""" 4
+.el .IP \f(CWEOF_NONBLOCK\fR 4
+.IX Xref "EOF_NONBLOCK"
+.IX Item "EOF_NONBLOCK"
+This symbol, if defined, indicates to the C program that a \f(CWread()\fR on
+a non-blocking file descriptor will return 0 on \f(CW\*(C`EOF\*(C'\fR, and not the value
+held in \f(CW\*(C`RD_NODATA\*(C'\fR (\-1 usually, in that case!).
+.ie n .IP """FCNTL_CAN_LOCK""" 4
+.el .IP \f(CWFCNTL_CAN_LOCK\fR 4
+.IX Xref "FCNTL_CAN_LOCK"
+.IX Item "FCNTL_CAN_LOCK"
+This symbol, if defined, indicates that \f(CWfcntl()\fR can be used
+for file locking.  Normally on Unix systems this is defined.
+It may be undefined on \f(CW\*(C`VMS\*(C'\fR.
+.ie n .IP """FFLUSH_ALL""" 4
+.el .IP \f(CWFFLUSH_ALL\fR 4
+.IX Xref "FFLUSH_ALL"
+.IX Item "FFLUSH_ALL"
+This symbol, if defined, tells that to flush
+all pending stdio output one must loop through all
+the stdio file handles stored in an array and fflush them.
+Note that if \f(CW\*(C`fflushNULL\*(C'\fR is defined, fflushall will not
+even be probed for and will be left undefined.
+.ie n .IP """FFLUSH_NULL""" 4
+.el .IP \f(CWFFLUSH_NULL\fR 4
+.IX Xref "FFLUSH_NULL"
+.IX Item "FFLUSH_NULL"
+This symbol, if defined, tells that \f(CWfflush(NULL)\fR correctly
+flushes all pending stdio output without side effects. In
+particular, on some platforms calling \f(CWfflush(NULL)\fR *still*
+corrupts \f(CW\*(C`STDIN\*(C'\fR if it is a pipe.
+.ie n .IP """FILE_base""" 4
+.el .IP \f(CWFILE_base\fR 4
+.IX Xref "FILE_base"
+.IX Item "FILE_base"
+This macro is used to access the \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the
+\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
+defined if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
+.RS 4
+.Sp
+.Vb 1
+\& void *  FILE_base(FILE * f)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """FILE_bufsiz""" 4
+.el .IP \f(CWFILE_bufsiz\fR 4
+.IX Xref "FILE_bufsiz"
+.IX Item "FILE_bufsiz"
+This macro is used to determine the number of bytes in the I/O
+buffer pointed to by \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the \f(CW\*(C`FILE\*(C'\fR
+structure pointed to its argument. This macro will always be defined
+if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  FILE_bufsiz(FILE *f)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """FILE_cnt""" 4
+.el .IP \f(CWFILE_cnt\fR 4
+.IX Xref "FILE_cnt"
+.IX Item "FILE_cnt"
+This macro is used to access the \f(CW\*(C`_cnt\*(C'\fR field (or equivalent) of the
+\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
+defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  FILE_cnt(FILE * f)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """FILE_ptr""" 4
+.el .IP \f(CWFILE_ptr\fR 4
+.IX Xref "FILE_ptr"
+.IX Item "FILE_ptr"
+This macro is used to access the \f(CW\*(C`_ptr\*(C'\fR field (or equivalent) of the
+\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
+defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
+.RS 4
+.Sp
+.Vb 1
+\& void *  FILE_ptr(FILE * f)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """FLEXFILENAMES""" 4
+.el .IP \f(CWFLEXFILENAMES\fR 4
+.IX Xref "FLEXFILENAMES"
+.IX Item "FLEXFILENAMES"
+This symbol, if defined, indicates that the system supports filenames
+longer than 14 characters.
+.ie n .IP """HAS_DIR_DD_FD""" 4
+.el .IP \f(CWHAS_DIR_DD_FD\fR 4
+.IX Xref "HAS_DIR_DD_FD"
+.IX Item "HAS_DIR_DD_FD"
+This symbol, if defined, indicates that the \f(CW\*(C`DIR\*(C'\fR* dirstream
+structure contains a member variable named \f(CW\*(C`dd_fd\*(C'\fR.
+.ie n .IP """HAS_DUP2""" 4
+.el .IP \f(CWHAS_DUP2\fR 4
+.IX Xref "HAS_DUP2"
+.IX Item "HAS_DUP2"
+This symbol, if defined, indicates that the \f(CW\*(C`dup2\*(C'\fR routine is
+available to duplicate file descriptors.
+.ie n .IP """HAS_DUP3""" 4
+.el .IP \f(CWHAS_DUP3\fR 4
+.IX Xref "HAS_DUP3"
+.IX Item "HAS_DUP3"
+This symbol, if defined, indicates that the \f(CW\*(C`dup3\*(C'\fR routine is
+available to duplicate file descriptors.
+.ie n .IP """HAS_FAST_STDIO""" 4
+.el .IP \f(CWHAS_FAST_STDIO\fR 4
+.IX Xref "HAS_FAST_STDIO"
+.IX Item "HAS_FAST_STDIO"
+This symbol, if defined, indicates that the "fast stdio"
+is available to manipulate the stdio buffers directly.
+.ie n .IP """HAS_FCHDIR""" 4
+.el .IP \f(CWHAS_FCHDIR\fR 4
+.IX Xref "HAS_FCHDIR"
+.IX Item "HAS_FCHDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`fchdir\*(C'\fR routine is
+available to change directory using a file descriptor.
+.ie n .IP """HAS_FCNTL""" 4
+.el .IP \f(CWHAS_FCNTL\fR 4
+.IX Xref "HAS_FCNTL"
+.IX Item "HAS_FCNTL"
+This symbol, if defined, indicates to the C program that
+the \f(CWfcntl()\fR function exists.
+.ie n .IP """HAS_FDCLOSE""" 4
+.el .IP \f(CWHAS_FDCLOSE\fR 4
+.IX Xref "HAS_FDCLOSE"
+.IX Item "HAS_FDCLOSE"
+This symbol, if defined, indicates that the \f(CW\*(C`fdclose\*(C'\fR routine is
+available to free a \f(CW\*(C`FILE\*(C'\fR structure without closing the underlying
+file descriptor.  This function appeared in \f(CW\*(C`FreeBSD\*(C'\fR 10.2.
+.ie n .IP """HAS_FPATHCONF""" 4
+.el .IP \f(CWHAS_FPATHCONF\fR 4
+.IX Xref "HAS_FPATHCONF"
+.IX Item "HAS_FPATHCONF"
+This symbol, if defined, indicates that \f(CWpathconf()\fR is available
+to determine file-system related limits and options associated
+with a given open file descriptor.
+.ie n .IP """HAS_FPOS64_T""" 4
+.el .IP \f(CWHAS_FPOS64_T\fR 4
+.IX Xref "HAS_FPOS64_T"
+.IX Item "HAS_FPOS64_T"
+This symbol will be defined if the C compiler supports \f(CW\*(C`fpos64_t\*(C'\fR.
+.ie n .IP """HAS_FSTATFS""" 4
+.el .IP \f(CWHAS_FSTATFS\fR 4
+.IX Xref "HAS_FSTATFS"
+.IX Item "HAS_FSTATFS"
+This symbol, if defined, indicates that the \f(CW\*(C`fstatfs\*(C'\fR routine is
+available to stat filesystems by file descriptors.
+.ie n .IP """HAS_FSTATVFS""" 4
+.el .IP \f(CWHAS_FSTATVFS\fR 4
+.IX Xref "HAS_FSTATVFS"
+.IX Item "HAS_FSTATVFS"
+This symbol, if defined, indicates that the \f(CW\*(C`fstatvfs\*(C'\fR routine is
+available to stat filesystems by file descriptors.
+.ie n .IP """HAS_GETFSSTAT""" 4
+.el .IP \f(CWHAS_GETFSSTAT\fR 4
+.IX Xref "HAS_GETFSSTAT"
+.IX Item "HAS_GETFSSTAT"
+This symbol, if defined, indicates that the \f(CW\*(C`getfsstat\*(C'\fR routine is
+available to stat filesystems in bulk.
+.ie n .IP """HAS_GETMNT""" 4
+.el .IP \f(CWHAS_GETMNT\fR 4
+.IX Xref "HAS_GETMNT"
+.IX Item "HAS_GETMNT"
+This symbol, if defined, indicates that the \f(CW\*(C`getmnt\*(C'\fR routine is
+available to get filesystem mount info by filename.
+.ie n .IP """HAS_GETMNTENT""" 4
+.el .IP \f(CWHAS_GETMNTENT\fR 4
+.IX Xref "HAS_GETMNTENT"
+.IX Item "HAS_GETMNTENT"
+This symbol, if defined, indicates that the \f(CW\*(C`getmntent\*(C'\fR routine is
+available to iterate through mounted file systems to get their info.
+.ie n .IP """HAS_HASMNTOPT""" 4
+.el .IP \f(CWHAS_HASMNTOPT\fR 4
+.IX Xref "HAS_HASMNTOPT"
+.IX Item "HAS_HASMNTOPT"
+This symbol, if defined, indicates that the \f(CW\*(C`hasmntopt\*(C'\fR routine is
+available to query the mount options of file systems.
+.ie n .IP """HAS_LSEEK_PROTO""" 4
+.el .IP \f(CWHAS_LSEEK_PROTO\fR 4
+.IX Xref "HAS_LSEEK_PROTO"
+.IX Item "HAS_LSEEK_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWlseek()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern off_t lseek(int, off_t, int);
+.Ve
+.ie n .IP """HAS_MKDIR""" 4
+.el .IP \f(CWHAS_MKDIR\fR 4
+.IX Xref "HAS_MKDIR"
+.IX Item "HAS_MKDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`mkdir\*(C'\fR routine is available
+to create directories.  Otherwise you should fork off a new process to
+exec \fI/bin/mkdir\fR.
+.ie n .IP """HAS_OFF64_T""" 4
+.el .IP \f(CWHAS_OFF64_T\fR 4
+.IX Xref "HAS_OFF64_T"
+.IX Item "HAS_OFF64_T"
+This symbol will be defined if the C compiler supports \f(CW\*(C`off64_t\*(C'\fR.
+.ie n .IP """HAS_OPENAT""" 4
+.el .IP \f(CWHAS_OPENAT\fR 4
+.IX Xref "HAS_OPENAT"
+.IX Item "HAS_OPENAT"
+This symbol is defined if the \f(CWopenat()\fR routine is available.
+.ie n .IP """HAS_OPEN3""" 4
+.el .IP \f(CWHAS_OPEN3\fR 4
+.IX Xref "HAS_OPEN3"
+.IX Item "HAS_OPEN3"
+This manifest constant lets the C program know that the three
+argument form of \f(CWopen(2)\fR is available.
+.ie n .IP """HAS_POLL""" 4
+.el .IP \f(CWHAS_POLL\fR 4
+.IX Xref "HAS_POLL"
+.IX Item "HAS_POLL"
+This symbol, if defined, indicates that the \f(CW\*(C`poll\*(C'\fR routine is
+available to \f(CW\*(C`poll\*(C'\fR active file descriptors.  Please check \f(CW\*(C`I_POLL\*(C'\fR and
+\&\f(CW\*(C`I_SYS_POLL\*(C'\fR to know which header should be included as well.
+.ie n .IP """HAS_READDIR""" 4
+.el .IP \f(CWHAS_READDIR\fR 4
+.IX Xref "HAS_READDIR"
+.IX Item "HAS_READDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`readdir\*(C'\fR routine is
+available to read directory entries. You may have to include
+\&\fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
+.ie n .IP """HAS_READDIR64_R""" 4
+.el .IP \f(CWHAS_READDIR64_R\fR 4
+.IX Xref "HAS_READDIR64_R"
+.IX Item "HAS_READDIR64_R"
+This symbol, if defined, indicates that the \f(CW\*(C`readdir64_r\*(C'\fR routine
+is available to readdir64 re-entrantly.
+.ie n .IP """HAS_REWINDDIR""" 4
+.el .IP \f(CWHAS_REWINDDIR\fR 4
+.IX Xref "HAS_REWINDDIR"
+.IX Item "HAS_REWINDDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`rewinddir\*(C'\fR routine is
+available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
+.ie n .IP """HAS_RMDIR""" 4
+.el .IP \f(CWHAS_RMDIR\fR 4
+.IX Xref "HAS_RMDIR"
+.IX Item "HAS_RMDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`rmdir\*(C'\fR routine is
+available to remove directories. Otherwise you should fork off a
+new process to exec \fI/bin/rmdir\fR.
+.ie n .IP """HAS_SEEKDIR""" 4
+.el .IP \f(CWHAS_SEEKDIR\fR 4
+.IX Xref "HAS_SEEKDIR"
+.IX Item "HAS_SEEKDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`seekdir\*(C'\fR routine is
+available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
+.ie n .IP """HAS_SELECT""" 4
+.el .IP \f(CWHAS_SELECT\fR 4
+.IX Xref "HAS_SELECT"
+.IX Item "HAS_SELECT"
+This symbol, if defined, indicates that the \f(CW\*(C`select\*(C'\fR routine is
+available to \f(CW\*(C`select\*(C'\fR active file descriptors. If the timeout field
+is used, \fIsys/time.h\fR may need to be included.
+.ie n .IP """HAS_SETVBUF""" 4
+.el .IP \f(CWHAS_SETVBUF\fR 4
+.IX Xref "HAS_SETVBUF"
+.IX Item "HAS_SETVBUF"
+This symbol, if defined, indicates that the \f(CW\*(C`setvbuf\*(C'\fR routine is
+available to change buffering on an open stdio stream.
+to a line-buffered mode.
+.ie n .IP """HAS_STDIO_STREAM_ARRAY""" 4
+.el .IP \f(CWHAS_STDIO_STREAM_ARRAY\fR 4
+.IX Xref "HAS_STDIO_STREAM_ARRAY"
+.IX Item "HAS_STDIO_STREAM_ARRAY"
+This symbol, if defined, tells that there is an array
+holding the stdio streams.
+.ie n .IP """HAS_STRUCT_FS_DATA""" 4
+.el .IP \f(CWHAS_STRUCT_FS_DATA\fR 4
+.IX Xref "HAS_STRUCT_FS_DATA"
+.IX Item "HAS_STRUCT_FS_DATA"
+This symbol, if defined, indicates that the \f(CW\*(C`struct fs_data\*(C'\fR
+to do \f(CWstatfs()\fR is supported.
+.ie n .IP """HAS_STRUCT_STATFS""" 4
+.el .IP \f(CWHAS_STRUCT_STATFS\fR 4
+.IX Xref "HAS_STRUCT_STATFS"
+.IX Item "HAS_STRUCT_STATFS"
+This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
+to do \f(CWstatfs()\fR is supported.
+.ie n .IP """HAS_STRUCT_STATFS_F_FLAGS""" 4
+.el .IP \f(CWHAS_STRUCT_STATFS_F_FLAGS\fR 4
+.IX Xref "HAS_STRUCT_STATFS_F_FLAGS"
+.IX Item "HAS_STRUCT_STATFS_F_FLAGS"
+This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
+does have the \f(CW\*(C`f_flags\*(C'\fR member containing the mount flags of
+the filesystem containing the file.
+This kind of \f(CW\*(C`struct statfs\*(C'\fR is coming from \fIsys/mount.h\fR (\f(CW\*(C`BSD\*(C'\fR 4.3),
+not from \fIsys/statfs.h\fR (\f(CW\*(C`SYSV\*(C'\fR).  Older \f(CW\*(C`BSDs\*(C'\fR (like Ultrix) do not
+have \f(CWstatfs()\fR and \f(CW\*(C`struct statfs\*(C'\fR, they have \f(CWustat()\fR and \f(CWgetmnt()\fR
+with \f(CW\*(C`struct ustat\*(C'\fR and \f(CW\*(C`struct fs_data\*(C'\fR.
+.ie n .IP """HAS_TELLDIR""" 4
+.el .IP \f(CWHAS_TELLDIR\fR 4
+.IX Xref "HAS_TELLDIR"
+.IX Item "HAS_TELLDIR"
+This symbol, if defined, indicates that the \f(CW\*(C`telldir\*(C'\fR routine is
+available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
+.ie n .IP """HAS_USTAT""" 4
+.el .IP \f(CWHAS_USTAT\fR 4
+.IX Xref "HAS_USTAT"
+.IX Item "HAS_USTAT"
+This symbol, if defined, indicates that the \f(CW\*(C`ustat\*(C'\fR system call is
+available to query file system statistics by \f(CW\*(C`dev_t\*(C'\fR.
+.ie n .IP """I_FCNTL""" 4
+.el .IP \f(CWI_FCNTL\fR 4
+.IX Xref "I_FCNTL"
+.IX Item "I_FCNTL"
+This manifest constant tells the C program to include \fIfcntl.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_FCNTL
+\&     #include <fcntl.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_DIR""" 4
+.el .IP \f(CWI_SYS_DIR\fR 4
+.IX Xref "I_SYS_DIR"
+.IX Item "I_SYS_DIR"
+This symbol, if defined, indicates to the C program that it should
+include \fIsys/dir.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_DIR
+\&     #include <sys_dir.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_FILE""" 4
+.el .IP \f(CWI_SYS_FILE\fR 4
+.IX Xref "I_SYS_FILE"
+.IX Item "I_SYS_FILE"
+This symbol, if defined, indicates to the C program that it should
+include \fIsys/file.h\fR to get definition of \f(CW\*(C`R_OK\*(C'\fR and friends.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_FILE
+\&     #include <sys_file.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_NDIR""" 4
+.el .IP \f(CWI_SYS_NDIR\fR 4
+.IX Xref "I_SYS_NDIR"
+.IX Item "I_SYS_NDIR"
+This symbol, if defined, indicates to the C program that it should
+include \fIsys/ndir.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_NDIR
+\&     #include <sys_ndir.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_STATFS""" 4
+.el .IP \f(CWI_SYS_STATFS\fR 4
+.IX Xref "I_SYS_STATFS"
+.IX Item "I_SYS_STATFS"
+This symbol, if defined, indicates that \fIsys/statfs.h\fR exists.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_STATFS
+\&     #include <sys_statfs.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LSEEKSIZE""" 4
+.el .IP \f(CWLSEEKSIZE\fR 4
+.IX Xref "LSEEKSIZE"
+.IX Item "LSEEKSIZE"
+This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
+.ie n .IP """RD_NODATA""" 4
+.el .IP \f(CWRD_NODATA\fR 4
+.IX Xref "RD_NODATA"
+.IX Item "RD_NODATA"
+This symbol holds the return code from \f(CWread()\fR when no data is present
+on the non-blocking file descriptor. Be careful! If \f(CW\*(C`EOF_NONBLOCK\*(C'\fR is
+not defined, then you can't distinguish between no data and \f(CW\*(C`EOF\*(C'\fR by
+issuing a \f(CWread()\fR. You'll have to find another way to tell for sure!
+.ie n .IP """READDIR64_R_PROTO""" 4
+.el .IP \f(CWREADDIR64_R_PROTO\fR 4
+.IX Xref "READDIR64_R_PROTO"
+.IX Item "READDIR64_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`readdir64_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_readdir64_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir64_r\*(C'\fR
+is defined.
+.ie n .IP """STDCHAR""" 4
+.el .IP \f(CWSTDCHAR\fR 4
+.IX Xref "STDCHAR"
+.IX Item "STDCHAR"
+This symbol is defined to be the type of char used in \fIstdio.h\fR.
+It has the values "unsigned char" or "char".
+.ie n .IP """STDIO_CNT_LVALUE""" 4
+.el .IP \f(CWSTDIO_CNT_LVALUE\fR 4
+.IX Xref "STDIO_CNT_LVALUE"
+.IX Item "STDIO_CNT_LVALUE"
+This symbol is defined if the \f(CW\*(C`FILE_cnt\*(C'\fR macro can be used as an
+lvalue.
+.ie n .IP """STDIO_PTR_LVAL_NOCHANGE_CNT""" 4
+.el .IP \f(CWSTDIO_PTR_LVAL_NOCHANGE_CNT\fR 4
+.IX Xref "STDIO_PTR_LVAL_NOCHANGE_CNT"
+.IX Item "STDIO_PTR_LVAL_NOCHANGE_CNT"
+This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
+to increase the pointer by n leaves \f(CWFile_cnt(fp)\fR unchanged.
+.ie n .IP """STDIO_PTR_LVAL_SETS_CNT""" 4
+.el .IP \f(CWSTDIO_PTR_LVAL_SETS_CNT\fR 4
+.IX Xref "STDIO_PTR_LVAL_SETS_CNT"
+.IX Item "STDIO_PTR_LVAL_SETS_CNT"
+This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
+to increase the pointer by n has the side effect of decreasing the
+value of \f(CWFile_cnt(fp)\fR by n.
+.ie n .IP """STDIO_PTR_LVALUE""" 4
+.el .IP \f(CWSTDIO_PTR_LVALUE\fR 4
+.IX Xref "STDIO_PTR_LVALUE"
+.IX Item "STDIO_PTR_LVALUE"
+This symbol is defined if the \f(CW\*(C`FILE_ptr\*(C'\fR macro can be used as an
+lvalue.
+.ie n .IP """STDIO_STREAM_ARRAY""" 4
+.el .IP \f(CWSTDIO_STREAM_ARRAY\fR 4
+.IX Xref "STDIO_STREAM_ARRAY"
+.IX Item "STDIO_STREAM_ARRAY"
+This symbol tells the name of the array holding the stdio streams.
+Usual values include \f(CW\*(C`_iob\*(C'\fR, \f(CW\*(C`_\|_iob\*(C'\fR, and \f(CW\*(C`_\|_sF\*(C'\fR.
+.ie n .IP """ST_INO_SIGN""" 4
+.el .IP \f(CWST_INO_SIGN\fR 4
+.IX Xref "ST_INO_SIGN"
+.IX Item "ST_INO_SIGN"
+This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR.
+1 for unsigned, \-1 for signed.
+.ie n .IP """ST_INO_SIZE""" 4
+.el .IP \f(CWST_INO_SIZE\fR 4
+.IX Xref "ST_INO_SIZE"
+.IX Item "ST_INO_SIZE"
+This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR in bytes.
+.ie n .IP """VAL_EAGAIN""" 4
+.el .IP \f(CWVAL_EAGAIN\fR 4
+.IX Xref "VAL_EAGAIN"
+.IX Item "VAL_EAGAIN"
+This symbol holds the errno error code set by \f(CWread()\fR when no data was
+present on the non-blocking file descriptor.
+.ie n .IP """VAL_O_NONBLOCK""" 4
+.el .IP \f(CWVAL_O_NONBLOCK\fR 4
+.IX Xref "VAL_O_NONBLOCK"
+.IX Item "VAL_O_NONBLOCK"
+This symbol is to be used during \f(CWopen()\fR or \f(CWfcntl(F_SETFL)\fR to turn on
+non-blocking I/O for the file descriptor. Note that there is no way
+back, i.e. you cannot turn it blocking again this way. If you wish to
+alternatively switch between blocking and non-blocking, use the
+\&\f(CWioctl(FIOSNBIO)\fR call instead, but that is not supported by all devices.
+.ie n .IP """VOID_CLOSEDIR""" 4
+.el .IP \f(CWVOID_CLOSEDIR\fR 4
+.IX Xref "VOID_CLOSEDIR"
+.IX Item "VOID_CLOSEDIR"
+This symbol, if defined, indicates that the \f(CWclosedir()\fR routine
+does not return a value.
+.SH "Floating point"
+.IX Header "Floating point"
+Also "List of capability HAS_foo symbols" lists capabilities
+that arent in this section.  For example \f(CW\*(C`HAS_ASINH\*(C'\fR, for the
+hyperbolic sine function.
+.ie n .IP """CASTFLAGS""" 4
+.el .IP \f(CWCASTFLAGS\fR 4
+.IX Xref "CASTFLAGS"
+.IX Item "CASTFLAGS"
+This symbol contains flags that say what difficulties the compiler
+has casting odd floating values to unsigned long:
+.Sp
+.Vb 4
+\& 0 = ok
+\& 1 = couldn\*(Aqt cast < 0
+\& 2 = couldn\*(Aqt cast >= 0x80000000
+\& 4 = couldn\*(Aqt cast in argument expression list
+.Ve
+.ie n .IP """CASTNEGFLOAT""" 4
+.el .IP \f(CWCASTNEGFLOAT\fR 4
+.IX Xref "CASTNEGFLOAT"
+.IX Item "CASTNEGFLOAT"
+This symbol is defined if the C compiler can cast negative
+numbers to unsigned longs, ints and shorts.
+.ie n .IP """DOUBLE_HAS_INF""" 4
+.el .IP \f(CWDOUBLE_HAS_INF\fR 4
+.IX Xref "DOUBLE_HAS_INF"
+.IX Item "DOUBLE_HAS_INF"
+This symbol, if defined, indicates that the double has
+the infinity.
+.ie n .IP """DOUBLE_HAS_NAN""" 4
+.el .IP \f(CWDOUBLE_HAS_NAN\fR 4
+.IX Xref "DOUBLE_HAS_NAN"
+.IX Item "DOUBLE_HAS_NAN"
+This symbol, if defined, indicates that the double has
+the not-a-number.
+.ie n .IP """DOUBLE_HAS_NEGATIVE_ZERO""" 4
+.el .IP \f(CWDOUBLE_HAS_NEGATIVE_ZERO\fR 4
+.IX Xref "DOUBLE_HAS_NEGATIVE_ZERO"
+.IX Item "DOUBLE_HAS_NEGATIVE_ZERO"
+This symbol, if defined, indicates that the double has
+the \f(CW\*(C`negative_zero\*(C'\fR.
+.ie n .IP """DOUBLE_HAS_SUBNORMALS""" 4
+.el .IP \f(CWDOUBLE_HAS_SUBNORMALS\fR 4
+.IX Xref "DOUBLE_HAS_SUBNORMALS"
+.IX Item "DOUBLE_HAS_SUBNORMALS"
+This symbol, if defined, indicates that the double has
+the subnormals (denormals).
+.ie n .IP """DOUBLEINFBYTES""" 4
+.el .IP \f(CWDOUBLEINFBYTES\fR 4
+.IX Xref "DOUBLEINFBYTES"
+.IX Item "DOUBLEINFBYTES"
+This symbol, if defined, is a comma-separated list of
+hexadecimal bytes for the double precision infinity.
+.ie n .IP """DOUBLEKIND""" 4
+.el .IP \f(CWDOUBLEKIND\fR 4
+.IX Xref "DOUBLEKIND"
+.IX Item "DOUBLEKIND"
+\&\f(CW\*(C`DOUBLEKIND\*(C'\fR will be one of
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_VAX_F_FLOAT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_VAX_D_FLOAT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_VAX_G_FLOAT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IBM_SINGLE_32_BIT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_IBM_DOUBLE_64_BIT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_CRAY_SINGLE_64_BIT\*(C'\fR
+\&\f(CW\*(C`DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
+.ie n .IP """DOUBLEMANTBITS""" 4
+.el .IP \f(CWDOUBLEMANTBITS\fR 4
+.IX Xref "DOUBLEMANTBITS"
+.IX Item "DOUBLEMANTBITS"
+This symbol, if defined, tells how many mantissa bits
+there are in double precision floating point format.
+Note that this is usually \f(CW\*(C`DBL_MANT_DIG\*(C'\fR minus one, since
+with the standard \f(CW\*(C`IEEE\*(C'\fR 754 formats \f(CW\*(C`DBL_MANT_DIG\*(C'\fR includes
+the implicit bit, which doesn't really exist.
+.ie n .IP """DOUBLENANBYTES""" 4
+.el .IP \f(CWDOUBLENANBYTES\fR 4
+.IX Xref "DOUBLENANBYTES"
+.IX Item "DOUBLENANBYTES"
+This symbol, if defined, is a comma-separated list of
+hexadecimal bytes (0xHH) for the double precision not-a-number.
+.ie n .IP """DOUBLESIZE""" 4
+.el .IP \f(CWDOUBLESIZE\fR 4
+.IX Xref "DOUBLESIZE"
+.IX Item "DOUBLESIZE"
+This symbol contains the size of a double, so that the C preprocessor
+can make decisions based on it.
+.ie n .IP """DOUBLE_STYLE_CRAY""" 4
+.el .IP \f(CWDOUBLE_STYLE_CRAY\fR 4
+.IX Xref "DOUBLE_STYLE_CRAY"
+.IX Item "DOUBLE_STYLE_CRAY"
+This symbol, if defined, indicates that the double is
+the 64\-bit \f(CW\*(C`CRAY\*(C'\fR mainframe format.
+.ie n .IP """DOUBLE_STYLE_IBM""" 4
+.el .IP \f(CWDOUBLE_STYLE_IBM\fR 4
+.IX Xref "DOUBLE_STYLE_IBM"
+.IX Item "DOUBLE_STYLE_IBM"
+This symbol, if defined, indicates that the double is
+the 64\-bit \f(CW\*(C`IBM\*(C'\fR mainframe format.
+.ie n .IP """DOUBLE_STYLE_IEEE""" 4
+.el .IP \f(CWDOUBLE_STYLE_IEEE\fR 4
+.IX Xref "DOUBLE_STYLE_IEEE"
+.IX Item "DOUBLE_STYLE_IEEE"
+This symbol, if defined, indicates that the double is
+the 64\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
+.ie n .IP """DOUBLE_STYLE_VAX""" 4
+.el .IP \f(CWDOUBLE_STYLE_VAX\fR 4
+.IX Xref "DOUBLE_STYLE_VAX"
+.IX Item "DOUBLE_STYLE_VAX"
+This symbol, if defined, indicates that the double is
+the 64\-bit \f(CW\*(C`VAX\*(C'\fR format D or G.
+.ie n .IP """HAS_ATOLF""" 4
+.el .IP \f(CWHAS_ATOLF\fR 4
+.IX Xref "HAS_ATOLF"
+.IX Item "HAS_ATOLF"
+This symbol, if defined, indicates that the \f(CW\*(C`atolf\*(C'\fR routine is
+available to convert strings into long doubles.
+.ie n .IP """HAS_CLASS""" 4
+.el .IP \f(CWHAS_CLASS\fR 4
+.IX Xref "HAS_CLASS"
+.IX Item "HAS_CLASS"
+This symbol, if defined, indicates that the \f(CW\*(C`class\*(C'\fR routine is
+available to classify doubles.  Available for example in \f(CW\*(C`AIX\*(C'\fR.
+The returned values are defined in \fIfloat.h\fR and are:
+.Sp
+.Vb 10
+\& FP_PLUS_NORM    Positive normalized, nonzero
+\& FP_MINUS_NORM   Negative normalized, nonzero
+\& FP_PLUS_DENORM  Positive denormalized, nonzero
+\& FP_MINUS_DENORM Negative denormalized, nonzero
+\& FP_PLUS_ZERO    +0.0
+\& FP_MINUS_ZERO   \-0.0
+\& FP_PLUS_INF     +INF
+\& FP_MINUS_INF    \-INF
+\& FP_NANS         Signaling Not a Number (NaNS)
+\& FP_NANQ         Quiet Not a Number (NaNQ)
+.Ve
+.ie n .IP """HAS_FINITE""" 4
+.el .IP \f(CWHAS_FINITE\fR 4
+.IX Xref "HAS_FINITE"
+.IX Item "HAS_FINITE"
+This symbol, if defined, indicates that the \f(CW\*(C`finite\*(C'\fR routine is
+available to check whether a double is \f(CW\*(C`finite\*(C'\fR (non-infinity non-NaN).
+.ie n .IP """HAS_FINITEL""" 4
+.el .IP \f(CWHAS_FINITEL\fR 4
+.IX Xref "HAS_FINITEL"
+.IX Item "HAS_FINITEL"
+This symbol, if defined, indicates that the \f(CW\*(C`finitel\*(C'\fR routine is
+available to check whether a long double is finite
+(non-infinity non-NaN).
+.ie n .IP """HAS_FPCLASS""" 4
+.el .IP \f(CWHAS_FPCLASS\fR 4
+.IX Xref "HAS_FPCLASS"
+.IX Item "HAS_FPCLASS"
+This symbol, if defined, indicates that the \f(CW\*(C`fpclass\*(C'\fR routine is
+available to classify doubles.  Available for example in Solaris/\f(CW\*(C`SVR4\*(C'\fR.
+The returned values are defined in \fIieeefp.h\fR and are:
+.Sp
+.Vb 10
+\& FP_SNAN         signaling NaN
+\& FP_QNAN         quiet NaN
+\& FP_NINF         negative infinity
+\& FP_PINF         positive infinity
+\& FP_NDENORM      negative denormalized non\-zero
+\& FP_PDENORM      positive denormalized non\-zero
+\& FP_NZERO        negative zero
+\& FP_PZERO        positive zero
+\& FP_NNORM        negative normalized non\-zero
+\& FP_PNORM        positive normalized non\-zero
+.Ve
+.ie n .IP """HAS_FP_CLASS""" 4
+.el .IP \f(CWHAS_FP_CLASS\fR 4
+.IX Xref "HAS_FP_CLASS"
+.IX Item "HAS_FP_CLASS"
+This symbol, if defined, indicates that the \f(CW\*(C`fp_class\*(C'\fR routine is
+available to classify doubles.  Available for example in Digital \f(CW\*(C`UNIX\*(C'\fR.
+The returned values are defined in \fImath.h\fR and are:
+.Sp
+.Vb 10
+\& FP_SNAN           Signaling NaN (Not\-a\-Number)
+\& FP_QNAN           Quiet NaN (Not\-a\-Number)
+\& FP_POS_INF        +infinity
+\& FP_NEG_INF        \-infinity
+\& FP_POS_NORM       Positive normalized
+\& FP_NEG_NORM       Negative normalized
+\& FP_POS_DENORM     Positive denormalized
+\& FP_NEG_DENORM     Negative denormalized
+\& FP_POS_ZERO       +0.0 (positive zero)
+\& FP_NEG_ZERO       \-0.0 (negative zero)
+.Ve
+.ie n .IP """HAS_FPCLASSIFY""" 4
+.el .IP \f(CWHAS_FPCLASSIFY\fR 4
+.IX Xref "HAS_FPCLASSIFY"
+.IX Item "HAS_FPCLASSIFY"
+This symbol, if defined, indicates that the \f(CW\*(C`fpclassify\*(C'\fR routine is
+available to classify doubles.  Available for example in HP-UX.
+The returned values are defined in \fImath.h\fR and are
+.Sp
+.Vb 5
+\& FP_NORMAL     Normalized
+\& FP_ZERO       Zero
+\& FP_INFINITE   Infinity
+\& FP_SUBNORMAL  Denormalized
+\& FP_NAN        NaN
+.Ve
+.ie n .IP """HAS_FP_CLASSIFY""" 4
+.el .IP \f(CWHAS_FP_CLASSIFY\fR 4
+.IX Xref "HAS_FP_CLASSIFY"
+.IX Item "HAS_FP_CLASSIFY"
+This symbol, if defined, indicates that the \f(CW\*(C`fp_classify\*(C'\fR routine is
+available to classify doubles. The values are defined in \fImath.h\fR
+.Sp
+.Vb 5
+\& FP_NORMAL     Normalized
+\& FP_ZERO       Zero
+\& FP_INFINITE   Infinity
+\& FP_SUBNORMAL  Denormalized
+\& FP_NAN        NaN
+.Ve
+.ie n .IP """HAS_FPCLASSL""" 4
+.el .IP \f(CWHAS_FPCLASSL\fR 4
+.IX Xref "HAS_FPCLASSL"
+.IX Item "HAS_FPCLASSL"
+This symbol, if defined, indicates that the \f(CW\*(C`fpclassl\*(C'\fR routine is
+available to classify long doubles.  Available for example in \f(CW\*(C`IRIX\*(C'\fR.
+The returned values are defined in \fIieeefp.h\fR and are:
+.Sp
+.Vb 10
+\& FP_SNAN         signaling NaN
+\& FP_QNAN         quiet NaN
+\& FP_NINF         negative infinity
+\& FP_PINF         positive infinity
+\& FP_NDENORM      negative denormalized non\-zero
+\& FP_PDENORM      positive denormalized non\-zero
+\& FP_NZERO        negative zero
+\& FP_PZERO        positive zero
+\& FP_NNORM        negative normalized non\-zero
+\& FP_PNORM        positive normalized non\-zero
+.Ve
+.ie n .IP """HAS_FP_CLASSL""" 4
+.el .IP \f(CWHAS_FP_CLASSL\fR 4
+.IX Xref "HAS_FP_CLASSL"
+.IX Item "HAS_FP_CLASSL"
+This symbol, if defined, indicates that the \f(CW\*(C`fp_classl\*(C'\fR routine is
+available to classify long doubles.  Available for example in
+Digital \f(CW\*(C`UNIX\*(C'\fR.  See for possible values \f(CW\*(C`HAS_FP_CLASS\*(C'\fR.
+.ie n .IP """HAS_FPGETROUND""" 4
+.el .IP \f(CWHAS_FPGETROUND\fR 4
+.IX Xref "HAS_FPGETROUND"
+.IX Item "HAS_FPGETROUND"
+This symbol, if defined, indicates that the \f(CW\*(C`fpgetround\*(C'\fR routine is
+available to get the floating point rounding mode.
+.ie n .IP """HAS_FREXPL""" 4
+.el .IP \f(CWHAS_FREXPL\fR 4
+.IX Xref "HAS_FREXPL"
+.IX Item "HAS_FREXPL"
+This symbol, if defined, indicates that the \f(CW\*(C`frexpl\*(C'\fR routine is
+available to break a long double floating-point number into
+a normalized fraction and an integral power of 2.
+.ie n .IP """HAS_ILOGB""" 4
+.el .IP \f(CWHAS_ILOGB\fR 4
+.IX Xref "HAS_ILOGB"
+.IX Item "HAS_ILOGB"
+This symbol, if defined, indicates that the \f(CW\*(C`ilogb\*(C'\fR routine is
+available to get integer exponent of a floating-point value.
+.ie n .IP """HAS_ISFINITE""" 4
+.el .IP \f(CWHAS_ISFINITE\fR 4
+.IX Xref "HAS_ISFINITE"
+.IX Item "HAS_ISFINITE"
+This symbol, if defined, indicates that the \f(CW\*(C`isfinite\*(C'\fR routine is
+available to check whether a double is finite (non-infinity non-NaN).
+.ie n .IP """HAS_ISFINITEL""" 4
+.el .IP \f(CWHAS_ISFINITEL\fR 4
+.IX Xref "HAS_ISFINITEL"
+.IX Item "HAS_ISFINITEL"
+This symbol, if defined, indicates that the \f(CW\*(C`isfinitel\*(C'\fR routine is
+available to check whether a long double is finite.
+(non-infinity non-NaN).
+.ie n .IP """HAS_ISINF""" 4
+.el .IP \f(CWHAS_ISINF\fR 4
+.IX Xref "HAS_ISINF"
+.IX Item "HAS_ISINF"
+This symbol, if defined, indicates that the \f(CW\*(C`isinf\*(C'\fR routine is
+available to check whether a double is an infinity.
+.ie n .IP """HAS_ISINFL""" 4
+.el .IP \f(CWHAS_ISINFL\fR 4
+.IX Xref "HAS_ISINFL"
+.IX Item "HAS_ISINFL"
+This symbol, if defined, indicates that the \f(CW\*(C`isinfl\*(C'\fR routine is
+available to check whether a long double is an infinity.
+.ie n .IP """HAS_ISNAN""" 4
+.el .IP \f(CWHAS_ISNAN\fR 4
+.IX Xref "HAS_ISNAN"
+.IX Item "HAS_ISNAN"
+This symbol, if defined, indicates that the \f(CW\*(C`isnan\*(C'\fR routine is
+available to check whether a double is a NaN.
+.ie n .IP """HAS_ISNANL""" 4
+.el .IP \f(CWHAS_ISNANL\fR 4
+.IX Xref "HAS_ISNANL"
+.IX Item "HAS_ISNANL"
+This symbol, if defined, indicates that the \f(CW\*(C`isnanl\*(C'\fR routine is
+available to check whether a long double is a NaN.
+.ie n .IP """HAS_ISNORMAL""" 4
+.el .IP \f(CWHAS_ISNORMAL\fR 4
+.IX Xref "HAS_ISNORMAL"
+.IX Item "HAS_ISNORMAL"
+This symbol, if defined, indicates that the \f(CW\*(C`isnormal\*(C'\fR routine is
+available to check whether a double is normal (non-zero normalized).
+.ie n .IP """HAS_J0L""" 4
+.el .IP \f(CWHAS_J0L\fR 4
+.IX Xref "HAS_J0L"
+.IX Item "HAS_J0L"
+This symbol, if defined, indicates to the C program that the
+\&\f(CWj0l()\fR function is available for Bessel functions of the first
+kind of the order zero, for long doubles.
+.ie n .IP """HAS_J0""" 4
+.el .IP \f(CWHAS_J0\fR 4
+.IX Xref "HAS_J0"
+.IX Item "HAS_J0"
+This symbol, if defined, indicates to the C program that the
+\&\f(CWj0()\fR function is available for Bessel functions of the first
+kind of the order zero, for doubles.
+.ie n .IP """HAS_LDBL_DIG""" 4
+.el .IP \f(CWHAS_LDBL_DIG\fR 4
+.IX Xref "HAS_LDBL_DIG"
+.IX Item "HAS_LDBL_DIG"
+This symbol, if defined, indicates that this system's \fIfloat.h\fR
+or \fIlimits.h\fR defines the symbol \f(CW\*(C`LDBL_DIG\*(C'\fR, which is the number
+of significant digits in a long double precision number. Unlike
+for \f(CW\*(C`DBL_DIG\*(C'\fR, there's no good guess for \f(CW\*(C`LDBL_DIG\*(C'\fR if it is undefined.
+.ie n .IP """HAS_LDEXPL""" 4
+.el .IP \f(CWHAS_LDEXPL\fR 4
+.IX Xref "HAS_LDEXPL"
+.IX Item "HAS_LDEXPL"
+This symbol, if defined, indicates that the \f(CW\*(C`ldexpl\*(C'\fR routine is
+available to shift a long double floating-point number
+by an integral power of 2.
+.ie n .IP """HAS_LLRINT""" 4
+.el .IP \f(CWHAS_LLRINT\fR 4
+.IX Xref "HAS_LLRINT"
+.IX Item "HAS_LLRINT"
+This symbol, if defined, indicates that the \f(CW\*(C`llrint\*(C'\fR routine is
+available to return the long long value closest to a double
+(according to the current rounding mode).
+.ie n .IP """HAS_LLRINTL""" 4
+.el .IP \f(CWHAS_LLRINTL\fR 4
+.IX Xref "HAS_LLRINTL"
+.IX Item "HAS_LLRINTL"
+This symbol, if defined, indicates that the \f(CW\*(C`llrintl\*(C'\fR routine is
+available to return the long long value closest to a long double
+(according to the current rounding mode).
+.ie n .IP """HAS_LLROUNDL""" 4
+.el .IP \f(CWHAS_LLROUNDL\fR 4
+.IX Xref "HAS_LLROUNDL"
+.IX Item "HAS_LLROUNDL"
+This symbol, if defined, indicates that the \f(CW\*(C`llroundl\*(C'\fR routine is
+available to return the nearest long long value away from zero of
+the long double argument value.
+.ie n .IP """HAS_LONG_DOUBLE""" 4
+.el .IP \f(CWHAS_LONG_DOUBLE\fR 4
+.IX Xref "HAS_LONG_DOUBLE"
+.IX Item "HAS_LONG_DOUBLE"
+This symbol will be defined if the C compiler supports long
+doubles.
+.ie n .IP """HAS_LRINT""" 4
+.el .IP \f(CWHAS_LRINT\fR 4
+.IX Xref "HAS_LRINT"
+.IX Item "HAS_LRINT"
+This symbol, if defined, indicates that the \f(CW\*(C`lrint\*(C'\fR routine is
+available to return the integral value closest to a double
+(according to the current rounding mode).
+.ie n .IP """HAS_LRINTL""" 4
+.el .IP \f(CWHAS_LRINTL\fR 4
+.IX Xref "HAS_LRINTL"
+.IX Item "HAS_LRINTL"
+This symbol, if defined, indicates that the \f(CW\*(C`lrintl\*(C'\fR routine is
+available to return the integral value closest to a long double
+(according to the current rounding mode).
+.ie n .IP """HAS_LROUNDL""" 4
+.el .IP \f(CWHAS_LROUNDL\fR 4
+.IX Xref "HAS_LROUNDL"
+.IX Item "HAS_LROUNDL"
+This symbol, if defined, indicates that the \f(CW\*(C`lroundl\*(C'\fR routine is
+available to return the nearest integral value away from zero of
+the long double argument value.
+.ie n .IP """HAS_MODFL""" 4
+.el .IP \f(CWHAS_MODFL\fR 4
+.IX Xref "HAS_MODFL"
+.IX Item "HAS_MODFL"
+This symbol, if defined, indicates that the \f(CW\*(C`modfl\*(C'\fR routine is
+available to split a long double x into a fractional part f and
+an integer part i such that |f| < 1.0 and (f + i) = x.
+.ie n .IP """HAS_NAN""" 4
+.el .IP \f(CWHAS_NAN\fR 4
+.IX Xref "HAS_NAN"
+.IX Item "HAS_NAN"
+This symbol, if defined, indicates that the \f(CW\*(C`nan\*(C'\fR routine is
+available to generate NaN.
+.ie n .IP """HAS_NEXTTOWARD""" 4
+.el .IP \f(CWHAS_NEXTTOWARD\fR 4
+.IX Xref "HAS_NEXTTOWARD"
+.IX Item "HAS_NEXTTOWARD"
+This symbol, if defined, indicates that the \f(CW\*(C`nexttoward\*(C'\fR routine is
+available to return the next machine representable long double from
+x in direction y.
+.ie n .IP """HAS_REMAINDER""" 4
+.el .IP \f(CWHAS_REMAINDER\fR 4
+.IX Xref "HAS_REMAINDER"
+.IX Item "HAS_REMAINDER"
+This symbol, if defined, indicates that the \f(CW\*(C`remainder\*(C'\fR routine is
+available to return the floating-point \f(CW\*(C`remainder\*(C'\fR.
+.ie n .IP """HAS_SCALBN""" 4
+.el .IP \f(CWHAS_SCALBN\fR 4
+.IX Xref "HAS_SCALBN"
+.IX Item "HAS_SCALBN"
+This symbol, if defined, indicates that the \f(CW\*(C`scalbn\*(C'\fR routine is
+available to multiply floating-point number by integral power
+of radix.
+.ie n .IP """HAS_SIGNBIT""" 4
+.el .IP \f(CWHAS_SIGNBIT\fR 4
+.IX Xref "HAS_SIGNBIT"
+.IX Item "HAS_SIGNBIT"
+This symbol, if defined, indicates that the \f(CW\*(C`signbit\*(C'\fR routine is
+available to check if the given number has the sign bit set.
+This should include correct testing of \-0.0.  This will only be set
+if the \f(CWsignbit()\fR routine is safe to use with the NV type used internally
+in perl.  Users should call \f(CWPerl_signbit()\fR, which will be #defined to
+the system's \f(CWsignbit()\fR function or macro if this symbol is defined.
+.ie n .IP """HAS_SQRTL""" 4
+.el .IP \f(CWHAS_SQRTL\fR 4
+.IX Xref "HAS_SQRTL"
+.IX Item "HAS_SQRTL"
+This symbol, if defined, indicates that the \f(CW\*(C`sqrtl\*(C'\fR routine is
+available to do long double square roots.
+.ie n .IP """HAS_STRTOD_L""" 4
+.el .IP \f(CWHAS_STRTOD_L\fR 4
+.IX Xref "HAS_STRTOD_L"
+.IX Item "HAS_STRTOD_L"
+This symbol, if defined, indicates that the \f(CW\*(C`strtod_l\*(C'\fR routine is
+available to convert strings to long doubles.
+.ie n .IP """HAS_STRTOLD""" 4
+.el .IP \f(CWHAS_STRTOLD\fR 4
+.IX Xref "HAS_STRTOLD"
+.IX Item "HAS_STRTOLD"
+This symbol, if defined, indicates that the \f(CW\*(C`strtold\*(C'\fR routine is
+available to convert strings to long doubles.
+.ie n .IP """HAS_STRTOLD_L""" 4
+.el .IP \f(CWHAS_STRTOLD_L\fR 4
+.IX Xref "HAS_STRTOLD_L"
+.IX Item "HAS_STRTOLD_L"
+This symbol, if defined, indicates that the \f(CW\*(C`strtold_l\*(C'\fR routine is
+available to convert strings to long doubles.
+.ie n .IP """HAS_TRUNC""" 4
+.el .IP \f(CWHAS_TRUNC\fR 4
+.IX Xref "HAS_TRUNC"
+.IX Item "HAS_TRUNC"
+This symbol, if defined, indicates that the \f(CW\*(C`trunc\*(C'\fR routine is
+available to round doubles towards zero.
+.ie n .IP """HAS_UNORDERED""" 4
+.el .IP \f(CWHAS_UNORDERED\fR 4
+.IX Xref "HAS_UNORDERED"
+.IX Item "HAS_UNORDERED"
+This symbol, if defined, indicates that the \f(CW\*(C`unordered\*(C'\fR routine is
+available to check whether two doubles are \f(CW\*(C`unordered\*(C'\fR
+(effectively: whether either of them is NaN)
+.ie n .IP """I_FENV""" 4
+.el .IP \f(CWI_FENV\fR 4
+.IX Xref "I_FENV"
+.IX Item "I_FENV"
+This symbol, if defined, indicates to the C program that it should
+include \fIfenv.h\fR to get the floating point environment definitions.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_FENV
+\&     #include <fenv.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_QUADMATH""" 4
+.el .IP \f(CWI_QUADMATH\fR 4
+.IX Xref "I_QUADMATH"
+.IX Item "I_QUADMATH"
+This symbol, if defined, indicates that \fIquadmath.h\fR exists and
+should be included.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_QUADMATH
+\&     #include <quadmath.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LONGDBLINFBYTES""" 4
+.el .IP \f(CWLONGDBLINFBYTES\fR 4
+.IX Xref "LONGDBLINFBYTES"
+.IX Item "LONGDBLINFBYTES"
+This symbol, if defined, is a comma-separated list of
+hexadecimal bytes for the long double precision infinity.
+.ie n .IP """LONGDBLMANTBITS""" 4
+.el .IP \f(CWLONGDBLMANTBITS\fR 4
+.IX Xref "LONGDBLMANTBITS"
+.IX Item "LONGDBLMANTBITS"
+This symbol, if defined, tells how many mantissa bits
+there are in long double precision floating point format.
+Note that this can be \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR minus one,
+since \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR can include the \f(CW\*(C`IEEE\*(C'\fR 754 implicit bit.
+The common x86\-style 80\-bit long double does not have
+an implicit bit.
+.ie n .IP """LONGDBLNANBYTES""" 4
+.el .IP \f(CWLONGDBLNANBYTES\fR 4
+.IX Xref "LONGDBLNANBYTES"
+.IX Item "LONGDBLNANBYTES"
+This symbol, if defined, is a comma-separated list of
+hexadecimal bytes (0xHH) for the long double precision not-a-number.
+.ie n .IP """LONG_DOUBLEKIND""" 4
+.el .IP \f(CWLONG_DOUBLEKIND\fR 4
+.IX Xref "LONG_DOUBLEKIND"
+.IX Item "LONG_DOUBLEKIND"
+\&\f(CW\*(C`LONG_DOUBLEKIND\*(C'\fR will be one of
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLE\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_VAX_H_FLOAT\*(C'\fR
+\&\f(CW\*(C`LONG_DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
+It is only defined if the system supports long doubles.
+.ie n .IP """LONG_DOUBLESIZE""" 4
+.el .IP \f(CWLONG_DOUBLESIZE\fR 4
+.IX Xref "LONG_DOUBLESIZE"
+.IX Item "LONG_DOUBLESIZE"
+This symbol contains the size of a long double, so that the
+C preprocessor can make decisions based on it.  It is only
+defined if the system supports long doubles.  Note that this
+is \f(CW\*(C`sizeof(long double)\*(C'\fR, which may include unused bytes.
+.ie n .IP """LONG_DOUBLE_STYLE_IEEE""" 4
+.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE\fR 4
+.IX Xref "LONG_DOUBLE_STYLE_IEEE"
+.IX Item "LONG_DOUBLE_STYLE_IEEE"
+This symbol, if defined, indicates that the long double
+is any of the \f(CW\*(C`IEEE\*(C'\fR 754 style long doubles:
+\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_STD\*(C'\fR, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_EXTENDED\*(C'\fR,
+\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\*(C'\fR.
+.ie n .IP """LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE""" 4
+.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\fR 4
+.IX Xref "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
+.IX Item "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
+This symbol, if defined, indicates that the long double is
+the 128\-bit double-double.
+.ie n .IP """LONG_DOUBLE_STYLE_IEEE_EXTENDED""" 4
+.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_EXTENDED\fR 4
+.IX Xref "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
+.IX Item "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
+This symbol, if defined, indicates that the long double is
+the 80\-bit \f(CW\*(C`IEEE\*(C'\fR 754. Note that despite the 'extended' this
+is less than the 'std', since this is an extension of
+the double precision.
+.ie n .IP """LONG_DOUBLE_STYLE_IEEE_STD""" 4
+.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_STD\fR 4
+.IX Xref "LONG_DOUBLE_STYLE_IEEE_STD"
+.IX Item "LONG_DOUBLE_STYLE_IEEE_STD"
+This symbol, if defined, indicates that the long double is
+the 128\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
+.ie n .IP """LONG_DOUBLE_STYLE_VAX""" 4
+.el .IP \f(CWLONG_DOUBLE_STYLE_VAX\fR 4
+.IX Xref "LONG_DOUBLE_STYLE_VAX"
+.IX Item "LONG_DOUBLE_STYLE_VAX"
+This symbol, if defined, indicates that the long double is
+the 128\-bit \f(CW\*(C`VAX\*(C'\fR format H.
+.ie n .IP """NV""" 4
+.el .IP \f(CWNV\fR 4
+.IX Item "NV"
+Described in perlguts.
+.ie n .IP """NVMANTBITS""" 4
+.el .IP \f(CWNVMANTBITS\fR 4
+.IX Xref "NVMANTBITS"
+.IX Item "NVMANTBITS"
+This symbol, if defined, tells how many mantissa bits
+(not including implicit bit) there are in a Perl NV.
+This depends on which floating point type was chosen.
+.ie n .IP """NV_OVERFLOWS_INTEGERS_AT""" 4
+.el .IP \f(CWNV_OVERFLOWS_INTEGERS_AT\fR 4
+.IX Xref "NV_OVERFLOWS_INTEGERS_AT"
+.IX Item "NV_OVERFLOWS_INTEGERS_AT"
+This symbol gives the largest integer value that NVs can hold. This
+value + 1.0 cannot be stored accurately. It is expressed as constant
+floating point expression to reduce the chance of decimal/binary
+conversion issues. If it can not be determined, the value 0 is given.
+.ie n .IP """NV_PRESERVES_UV""" 4
+.el .IP \f(CWNV_PRESERVES_UV\fR 4
+.IX Xref "NV_PRESERVES_UV"
+.IX Item "NV_PRESERVES_UV"
+This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
+can preserve all the bits of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
+.ie n .IP """NV_PRESERVES_UV_BITS""" 4
+.el .IP \f(CWNV_PRESERVES_UV_BITS\fR 4
+.IX Xref "NV_PRESERVES_UV_BITS"
+.IX Item "NV_PRESERVES_UV_BITS"
+This symbol contains the number of bits a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
+can preserve of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
+.ie n .IP """NVSIZE""" 4
+.el .IP \f(CWNVSIZE\fR 4
+.IX Xref "NVSIZE"
+.IX Item "NVSIZE"
+This symbol contains the \f(CWsizeof(NV)\fR.
+Note that some floating point formats have unused bytes.
+The most notable example is the x86* 80\-bit extended precision
+which comes in byte sizes of 12 and 16 (for 32 and 64 bit
+platforms, respectively), but which only uses 10 bytes.
+Perl compiled with \f(CW\*(C`\-Duselongdouble\*(C'\fR on x86* is like this.
+.ie n .IP """NVTYPE""" 4
+.el .IP \f(CWNVTYPE\fR 4
+.IX Xref "NVTYPE"
+.IX Item "NVTYPE"
+This symbol defines the C type used for Perl's NV.
+.ie n .IP """NV_ZERO_IS_ALLBITS_ZERO""" 4
+.el .IP \f(CWNV_ZERO_IS_ALLBITS_ZERO\fR 4
+.IX Xref "NV_ZERO_IS_ALLBITS_ZERO"
+.IX Item "NV_ZERO_IS_ALLBITS_ZERO"
+This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
+stores 0.0 in memory as all bits zero.
+.SH "General Configuration"
+.IX Xref "PERL_GCC_BRACE_GROUPS_FORBIDDEN"
+.IX Header "General Configuration"
+This section contains configuration information not otherwise
+found in the more specialized sections of this document.  At the
+end is a list of \f(CW\*(C`#defines\*(C'\fR whose name should be enough to tell
+you what they do, and a list of #defines which tell you if you
+need to \f(CW\*(C`#include\*(C'\fR files to get the corresponding functionality.
+.ie n .IP """ASCIIish""" 4
+.el .IP \f(CWASCIIish\fR 4
+.IX Xref "ASCIIish"
+.IX Item "ASCIIish"
+A preprocessor symbol that is defined iff the system is an ASCII platform; this
+symbol would not be defined on \f(CW"EBCDIC"\fR platforms.
+.RS 4
+.Sp
+.Vb 1
+\& #ifdef  ASCIIish
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BYTEORDER""" 4
+.el .IP \f(CWBYTEORDER\fR 4
+.IX Xref "BYTEORDER"
+.IX Item "BYTEORDER"
+This symbol holds the hexadecimal constant defined in byteorder,
+in a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc...
+If the compiler supports cross-compiling or multiple-architecture
+binaries, use compiler-defined macros to
+determine the byte order.
+.ie n .IP """CHARBITS""" 4
+.el .IP \f(CWCHARBITS\fR 4
+.IX Xref "CHARBITS"
+.IX Item "CHARBITS"
+This symbol contains the size of a char, so that the C preprocessor
+can make decisions based on it.
+.ie n .IP """DB_VERSION_MAJOR_CFG""" 4
+.el .IP \f(CWDB_VERSION_MAJOR_CFG\fR 4
+.IX Xref "DB_VERSION_MAJOR_CFG"
+.IX Item "DB_VERSION_MAJOR_CFG"
+This symbol, if defined, defines the major version number of
+Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
+.ie n .IP """DB_VERSION_MINOR_CFG""" 4
+.el .IP \f(CWDB_VERSION_MINOR_CFG\fR 4
+.IX Xref "DB_VERSION_MINOR_CFG"
+.IX Item "DB_VERSION_MINOR_CFG"
+This symbol, if defined, defines the minor version number of
+Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
+For DB version 1 this is always 0.
+.ie n .IP """DB_VERSION_PATCH_CFG""" 4
+.el .IP \f(CWDB_VERSION_PATCH_CFG\fR 4
+.IX Xref "DB_VERSION_PATCH_CFG"
+.IX Item "DB_VERSION_PATCH_CFG"
+This symbol, if defined, defines the patch version number of
+Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
+For DB version 1 this is always 0.
+.ie n .IP """DEFAULT_INC_EXCLUDES_DOT""" 4
+.el .IP \f(CWDEFAULT_INC_EXCLUDES_DOT\fR 4
+.IX Xref "DEFAULT_INC_EXCLUDES_DOT"
+.IX Item "DEFAULT_INC_EXCLUDES_DOT"
+This symbol, if defined, removes the legacy default behavior of
+including '.' at the end of @\f(CW\*(C`INC\*(C'\fR.
+.ie n .IP """DLSYM_NEEDS_UNDERSCORE""" 4
+.el .IP \f(CWDLSYM_NEEDS_UNDERSCORE\fR 4
+.IX Xref "DLSYM_NEEDS_UNDERSCORE"
+.IX Item "DLSYM_NEEDS_UNDERSCORE"
+This symbol, if defined, indicates that we need to prepend an
+underscore to the symbol name before calling \f(CWdlsym()\fR.  This only
+makes sense if you *have* dlsym, which we will presume is the
+case if you're using \fIdl_dlopen.xs\fR.
+.ie n .IP """EBCDIC""" 4
+.el .IP \f(CWEBCDIC\fR 4
+.IX Xref "EBCDIC"
+.IX Item "EBCDIC"
+This symbol, if defined, indicates that this system uses
+\&\f(CW\*(C`EBCDIC\*(C'\fR encoding.
+.ie n .IP """HAS_CSH""" 4
+.el .IP \f(CWHAS_CSH\fR 4
+.IX Xref "HAS_CSH"
+.IX Item "HAS_CSH"
+This symbol, if defined, indicates that the C\-shell exists.
+.ie n .IP """HAS_GETHOSTNAME""" 4
+.el .IP \f(CWHAS_GETHOSTNAME\fR 4
+.IX Xref "HAS_GETHOSTNAME"
+.IX Item "HAS_GETHOSTNAME"
+This symbol, if defined, indicates that the C program may use the
+\&\f(CWgethostname()\fR routine to derive the host name.  See also \f(CW"HAS_UNAME"\fR
+and \f(CW"PHOSTNAME"\fR.
+.ie n .IP """HAS_GNULIBC""" 4
+.el .IP \f(CWHAS_GNULIBC\fR 4
+.IX Xref "HAS_GNULIBC"
+.IX Item "HAS_GNULIBC"
+This symbol, if defined, indicates to the C program that
+the \f(CW\*(C`GNU\*(C'\fR C library is being used.  A better check is to use
+the \f(CW\*(C`_\|_GLIBC_\|_\*(C'\fR and \f(CW\*(C`_\|_GLIBC_MINOR_\|_\*(C'\fR symbols supplied with glibc.
+.ie n .IP """HAS_LGAMMA""" 4
+.el .IP \f(CWHAS_LGAMMA\fR 4
+.IX Xref "HAS_LGAMMA"
+.IX Item "HAS_LGAMMA"
+This symbol, if defined, indicates that the \f(CW\*(C`lgamma\*(C'\fR routine is
+available to do the log gamma function.  See also \f(CW"HAS_TGAMMA"\fR and
+\&\f(CW"HAS_LGAMMA_R"\fR.
+.ie n .IP """HAS_LGAMMA_R""" 4
+.el .IP \f(CWHAS_LGAMMA_R\fR 4
+.IX Xref "HAS_LGAMMA_R"
+.IX Item "HAS_LGAMMA_R"
+This symbol, if defined, indicates that the \f(CW\*(C`lgamma_r\*(C'\fR routine is
+available to do the log gamma function without using the global
+signgam variable.
+.ie n .IP """HAS_NON_INT_BITFIELDS""" 4
+.el .IP \f(CWHAS_NON_INT_BITFIELDS\fR 4
+.IX Xref "HAS_NON_INT_BITFIELDS"
+.IX Item "HAS_NON_INT_BITFIELDS"
+This symbol, if defined, indicates that the C compiler accepts, without
+error or warning, \f(CW\*(C`struct bitfields\*(C'\fR that are declared with sizes other
+than plain 'int'; for example 'unsigned char' is accepted.
+.ie n .IP """HAS_PRCTL_SET_NAME""" 4
+.el .IP \f(CWHAS_PRCTL_SET_NAME\fR 4
+.IX Xref "HAS_PRCTL_SET_NAME"
+.IX Item "HAS_PRCTL_SET_NAME"
+This symbol, if defined, indicates that the prctl routine is
+available to set process title and supports \f(CW\*(C`PR_SET_NAME\*(C'\fR.
+.ie n .IP """HAS_PROCSELFEXE""" 4
+.el .IP \f(CWHAS_PROCSELFEXE\fR 4
+.IX Xref "HAS_PROCSELFEXE"
+.IX Item "HAS_PROCSELFEXE"
+This symbol is defined if \f(CW\*(C`PROCSELFEXE_PATH\*(C'\fR is a symlink
+to the absolute pathname of the executing program.
+.ie n .IP """HAS_PSEUDOFORK""" 4
+.el .IP \f(CWHAS_PSEUDOFORK\fR 4
+.IX Xref "HAS_PSEUDOFORK"
+.IX Item "HAS_PSEUDOFORK"
+This symbol, if defined, indicates that an emulation of the
+fork routine is available.
+.ie n .IP """HAS_REGCOMP""" 4
+.el .IP \f(CWHAS_REGCOMP\fR 4
+.IX Xref "HAS_REGCOMP"
+.IX Item "HAS_REGCOMP"
+This symbol, if defined, indicates that the \f(CWregcomp()\fR routine is
+available to do some regular pattern matching (usually on \f(CW\*(C`POSIX\*(C'\fR.2
+conforming systems).
+.ie n .IP """HAS_SETPGID""" 4
+.el .IP \f(CWHAS_SETPGID\fR 4
+.IX Xref "HAS_SETPGID"
+.IX Item "HAS_SETPGID"
+This symbol, if defined, indicates that the \f(CW\*(C`setpgid(pid, gpid)\*(C'\fR
+routine is available to set process group ID.
+.ie n .IP """HAS_SIGSETJMP""" 4
+.el .IP \f(CWHAS_SIGSETJMP\fR 4
+.IX Xref "HAS_SIGSETJMP"
+.IX Item "HAS_SIGSETJMP"
+This variable indicates to the C program that the \f(CWsigsetjmp()\fR
+routine is available to save the calling process's registers
+and stack environment for later use by \f(CWsiglongjmp()\fR, and
+to optionally save the process's signal mask.  See
+\&\f(CW"Sigjmp_buf"\fR, \f(CW"Sigsetjmp"\fR, and \f(CW"Siglongjmp"\fR.
+.ie n .IP """HAS_STRUCT_CMSGHDR""" 4
+.el .IP \f(CWHAS_STRUCT_CMSGHDR\fR 4
+.IX Xref "HAS_STRUCT_CMSGHDR"
+.IX Item "HAS_STRUCT_CMSGHDR"
+This symbol, if defined, indicates that the \f(CW\*(C`struct cmsghdr\*(C'\fR
+is supported.
+.ie n .IP """HAS_STRUCT_MSGHDR""" 4
+.el .IP \f(CWHAS_STRUCT_MSGHDR\fR 4
+.IX Xref "HAS_STRUCT_MSGHDR"
+.IX Item "HAS_STRUCT_MSGHDR"
+This symbol, if defined, indicates that the \f(CW\*(C`struct msghdr\*(C'\fR
+is supported.
+.ie n .IP """HAS_TGAMMA""" 4
+.el .IP \f(CWHAS_TGAMMA\fR 4
+.IX Xref "HAS_TGAMMA"
+.IX Item "HAS_TGAMMA"
+This symbol, if defined, indicates that the \f(CW\*(C`tgamma\*(C'\fR routine is
+available to do the gamma function. See also \f(CW"HAS_LGAMMA"\fR.
+.ie n .IP """HAS_UNAME""" 4
+.el .IP \f(CWHAS_UNAME\fR 4
+.IX Xref "HAS_UNAME"
+.IX Item "HAS_UNAME"
+This symbol, if defined, indicates that the C program may use the
+\&\f(CWuname()\fR routine to derive the host name.  See also \f(CW"HAS_GETHOSTNAME"\fR
+and \f(CW"PHOSTNAME"\fR.
+.ie n .IP """HAS_UNION_SEMUN""" 4
+.el .IP \f(CWHAS_UNION_SEMUN\fR 4
+.IX Xref "HAS_UNION_SEMUN"
+.IX Item "HAS_UNION_SEMUN"
+This symbol, if defined, indicates that the \f(CW\*(C`union semun\*(C'\fR is
+defined by including \fIsys/sem.h\fR.  If not, the user code
+probably needs to define it as:
+.Sp
+.Vb 5
+\& union semun {
+\& int val;
+\& struct semid_ds *buf;
+\& unsigned short *array;
+\& }
+.Ve
+.ie n .IP """I_DIRENT""" 4
+.el .IP \f(CWI_DIRENT\fR 4
+.IX Xref "I_DIRENT"
+.IX Item "I_DIRENT"
+This symbol, if defined, indicates to the C program that it should
+include \fIdirent.h\fR. Using this symbol also triggers the definition
+of the \f(CW\*(C`Direntry_t\*(C'\fR define which ends up being '\f(CW\*(C`struct dirent\*(C'\fR' or
+\&'\f(CW\*(C`struct direct\*(C'\fR' depending on the availability of \fIdirent.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_DIRENT
+\&     #include <dirent.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_POLL""" 4
+.el .IP \f(CWI_POLL\fR 4
+.IX Xref "I_POLL"
+.IX Item "I_POLL"
+This symbol, if defined, indicates that \fIpoll.h\fR exists and
+should be included. (see also \f(CW"HAS_POLL"\fR)
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_POLL
+\&     #include <poll.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_RESOURCE""" 4
+.el .IP \f(CWI_SYS_RESOURCE\fR 4
+.IX Xref "I_SYS_RESOURCE"
+.IX Item "I_SYS_RESOURCE"
+This symbol, if defined, indicates to the C program that it should
+include \fIsys/resource.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_RESOURCE
+\&     #include <sys_resource.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LIBM_LIB_VERSION""" 4
+.el .IP \f(CWLIBM_LIB_VERSION\fR 4
+.IX Xref "LIBM_LIB_VERSION"
+.IX Item "LIBM_LIB_VERSION"
+This symbol, if defined, indicates that libm exports \f(CW\*(C`_LIB_VERSION\*(C'\fR
+and that \fImath.h\fR defines the enum to manipulate it.
+.ie n .IP """NEED_VA_COPY""" 4
+.el .IP \f(CWNEED_VA_COPY\fR 4
+.IX Item "NEED_VA_COPY"
+This symbol, if defined, indicates that the system stores
+the variable argument list datatype, \f(CW\*(C`va_list\*(C'\fR, in a format
+that cannot be copied by simple assignment, so that some
+other means must be used when copying is required.
+As such systems vary in their provision (or non-provision)
+of copying mechanisms, \fIhandy.h\fR defines a platform\-
+independent macro, \f(CW\*(C`Perl_va_copy(src, dst)\*(C'\fR, to do the job.
+.ie n .IP """OSNAME""" 4
+.el .IP \f(CWOSNAME\fR 4
+.IX Xref "OSNAME"
+.IX Item "OSNAME"
+This symbol contains the name of the operating system, as determined
+by Configure.  You shouldn't rely on it too much; the specific
+feature tests from Configure are generally more reliable.
+.ie n .IP """OSVERS""" 4
+.el .IP \f(CWOSVERS\fR 4
+.IX Xref "OSVERS"
+.IX Item "OSVERS"
+This symbol contains the version of the operating system, as determined
+by Configure.  You shouldn't rely on it too much; the specific
+feature tests from Configure are generally more reliable.
+.ie n .IP """PERL_USE_GCC_BRACE_GROUPS""" 4
+.el .IP \f(CWPERL_USE_GCC_BRACE_GROUPS\fR 4
+.IX Xref "PERL_USE_GCC_BRACE_GROUPS"
+.IX Item "PERL_USE_GCC_BRACE_GROUPS"
+This C pre-processor value, if defined, indicates that it is permissible to use
+the GCC brace groups extension.  However, use of this extension is DISCOURAGED.
+Use a \f(CW\*(C`static inline\*(C'\fR function instead.
+.Sp
+The extension, of the form
+.Sp
+.Vb 1
+\& ({ statement ... })
+.Ve
+.Sp
+turns the block consisting of \fIstatement ...\fR into an expression with a
+value, unlike plain C language blocks.  This can present optimization
+possibilities, \fBBUT\fR, unless you know for sure that this will never be
+compiled without this extension being available and not forbidden, you need to
+specify an alternative.  Thus two code paths have to be maintained, which can
+get out-of-sync.  All these issues are solved by using a \f(CW\*(C`static inline\*(C'\fR
+function instead.
+.Sp
+Perl can be configured to not use this feature by passing the parameter
+\&\f(CW\*(C`\-Accflags=\-DPERL_GCC_BRACE_GROUPS_FORBIDDEN\*(C'\fR to \fIConfigure\fR.
+.RS 4
+.Sp
+.Vb 1
+\& #ifdef  PERL_USE_GCC_BRACE_GROUPS
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PHOSTNAME""" 4
+.el .IP \f(CWPHOSTNAME\fR 4
+.IX Xref "PHOSTNAME"
+.IX Item "PHOSTNAME"
+This symbol, if defined, indicates the command to feed to the
+\&\f(CWpopen()\fR routine to derive the host name.  See also \f(CW"HAS_GETHOSTNAME"\fR
+and \f(CW"HAS_UNAME"\fR.  Note that the command uses a fully qualified path,
+so that it is safe even if used by a process with super-user
+privileges.
+.ie n .IP """PROCSELFEXE_PATH""" 4
+.el .IP \f(CWPROCSELFEXE_PATH\fR 4
+.IX Xref "PROCSELFEXE_PATH"
+.IX Item "PROCSELFEXE_PATH"
+If \f(CW\*(C`HAS_PROCSELFEXE\*(C'\fR is defined this symbol is the filename
+of the symbolic link pointing to the absolute pathname of
+the executing program.
+.ie n .IP """PTRSIZE""" 4
+.el .IP \f(CWPTRSIZE\fR 4
+.IX Xref "PTRSIZE"
+.IX Item "PTRSIZE"
+This symbol contains the size of a pointer, so that the C preprocessor
+can make decisions based on it.  It will be \f(CW\*(C`sizeof(void *)\*(C'\fR if
+the compiler supports (void *); otherwise it will be
+\&\f(CW\*(C`sizeof(char *)\*(C'\fR.
+.ie n .IP """RANDBITS""" 4
+.el .IP \f(CWRANDBITS\fR 4
+.IX Xref "RANDBITS"
+.IX Item "RANDBITS"
+This symbol indicates how many bits are produced by the
+function used to generate normalized random numbers.
+Values include 15, 16, 31, and 48.
+.ie n .IP """SELECT_MIN_BITS""" 4
+.el .IP \f(CWSELECT_MIN_BITS\fR 4
+.IX Xref "SELECT_MIN_BITS"
+.IX Item "SELECT_MIN_BITS"
+This symbol holds the minimum number of bits operated by select.
+That is, if you do \f(CW\*(C`select(n, ...)\*(C'\fR, how many bits at least will be
+cleared in the masks if some activity is detected.  Usually this
+is either n or 32*\f(CWceil(n/32)\fR, especially many little-endians do
+the latter.  This is only useful if you have \f(CWselect()\fR, naturally.
+.ie n .IP """SETUID_SCRIPTS_ARE_SECURE_NOW""" 4
+.el .IP \f(CWSETUID_SCRIPTS_ARE_SECURE_NOW\fR 4
+.IX Xref "SETUID_SCRIPTS_ARE_SECURE_NOW"
+.IX Item "SETUID_SCRIPTS_ARE_SECURE_NOW"
+This symbol, if defined, indicates that the bug that prevents
+setuid scripts from being secure is not present in this kernel.
+.ie n .IP """ST_DEV_SIGN""" 4
+.el .IP \f(CWST_DEV_SIGN\fR 4
+.IX Xref "ST_DEV_SIGN"
+.IX Item "ST_DEV_SIGN"
+This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR.
+1 for unsigned, \-1 for signed.
+.ie n .IP """ST_DEV_SIZE""" 4
+.el .IP \f(CWST_DEV_SIZE\fR 4
+.IX Xref "ST_DEV_SIZE"
+.IX Item "ST_DEV_SIZE"
+This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR in bytes.
+.ie n .SS "List of capability ""HAS_\fIfoo\fP"" symbols"
+.el .SS "List of capability \f(CWHAS_\fP\f(CIfoo\fP\f(CW\fP symbols"
+.IX Subsection "List of capability HAS_foo symbols"
+This is a list of those symbols that dont appear elsewhere in ths
+document that indicate if the current platform has a certain
+capability.  Their names all begin with \f(CW\*(C`HAS_\*(C'\fR.  Only those
+symbols whose capability is directly derived from the name are
+listed here.  All others have their meaning expanded out elsewhere
+in this document.  This (relatively) compact list is because we
+think that the expansion would add little or no value and take up
+a lot of space (because there are so many).  If you think certain
+ones should be expanded, send email to
+perl5\-porters@perl.org <mailto:perl5-porters@perl.org>.
+.PP
+Each symbol here will be \f(CW\*(C`#define\*(C'\fRd if and only if the platform
+has the capability.  If you need more detail, see the
+corresponding entry in \fIconfig.h\fR.  For convenience, the list is
+split so that the ones that indicate there is a reentrant version
+of a capability are listed separately
+.PP
+\&\f(CW\*(C`HAS_ACCEPT4\*(C'\fR,\  \f(CW\*(C`HAS_ACCESS\*(C'\fR,\  \f(CW\*(C`HAS_ACCESSX\*(C'\fR,\  \f(CW\*(C`HAS_ACOSH\*(C'\fR,\  \f(CW\*(C`HAS_AINTL\*(C'\fR,\  \f(CW\*(C`HAS_ALARM\*(C'\fR,\  \f(CW\*(C`HAS_ASINH\*(C'\fR,\  \f(CW\*(C`HAS_ATANH\*(C'\fR,\  \f(CW\*(C`HAS_ATOLL\*(C'\fR,\  \f(CW\*(C`HAS_CBRT\*(C'\fR,\  \f(CW\*(C`HAS_CHOWN\*(C'\fR,\  \f(CW\*(C`HAS_CHROOT\*(C'\fR,\  \f(CW\*(C`HAS_CHSIZE\*(C'\fR,\  \f(CW\*(C`HAS_CLEARENV\*(C'\fR,\  \f(CW\*(C`HAS_COPYSIGN\*(C'\fR,\  \f(CW\*(C`HAS_COPYSIGNL\*(C'\fR,\  \f(CW\*(C`HAS_CRYPT\*(C'\fR,\  \f(CW\*(C`HAS_CTERMID\*(C'\fR,\  \f(CW\*(C`HAS_CUSERID\*(C'\fR,\  \f(CW\*(C`HAS_DIRFD\*(C'\fR,\  \f(CW\*(C`HAS_DLADDR\*(C'\fR,\  \f(CW\*(C`HAS_DLERROR\*(C'\fR,\  \f(CW\*(C`HAS_EACCESS\*(C'\fR,\  \f(CW\*(C`HAS_ENDHOSTENT\*(C'\fR,\  \f(CW\*(C`HAS_ENDNETENT\*(C'\fR,\  \f(CW\*(C`HAS_ENDPROTOENT\*(C'\fR,\  \f(CW\*(C`HAS_ENDSERVENT\*(C'\fR,\  \f(CW\*(C`HAS_ERF\*(C'\fR,\  \f(CW\*(C`HAS_ERFC\*(C'\fR,\  \f(CW\*(C`HAS_EXPM1\*(C'\fR,\  \f(CW\*(C`HAS_EXP2\*(C'\fR,\  \f(CW\*(C`HAS_FCHMOD\*(C'\fR,\  \f(CW\*(C`HAS_FCHMODAT\*(C'\fR,\  \f(CW\*(C`HAS_FCHOWN\*(C'\fR,\  \f(CW\*(C`HAS_FDIM\*(C'\fR,\  \f(CW\*(C`HAS_FD_SET\*(C'\fR,\  \f(CW\*(C`HAS_FEGETROUND\*(C'\fR,\  \f(CW\*(C`HAS_FFS\*(C'\fR,\  \f(CW\*(C`HAS_FFSL\*(C'\fR,\  \f(CW\*(C`HAS_FGETPOS\*(C'\fR,\  \f(CW\*(C`HAS_FLOCK\*(C'\fR,\  \f(CW\*(C`HAS_FMA\*(C'\fR,\  \f(CW\*(C`HAS_FMAX\*(C'\fR,\  \f(CW\*(C`HAS_FMIN\*(C'\fR,\  \f(CW\*(C`HAS_FORK\*(C'\fR,\  \f(CW\*(C`HAS_FSEEKO\*(C'\fR,\  \f(CW\*(C`HAS_FSETPOS\*(C'\fR,\  \f(CW\*(C`HAS_FSYNC\*(C'\fR,\  \f(CW\*(C`HAS_FTELLO\*(C'\fR,\  \f(CW\*(C`HAS_\|_FWALK\*(C'\fR,\  \f(CW\*(C`HAS_GAI_STRERROR\*(C'\fR,\  \f(CW\*(C`HAS_GETADDRINFO\*(C'\fR,\  \f(CW\*(C`HAS_GETCWD\*(C'\fR,\  \f(CW\*(C`HAS_GETESPWNAM\*(C'\fR,\  \f(CW\*(C`HAS_GETGROUPS\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTBYADDR\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTBYNAME\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTENT\*(C'\fR,\  \f(CW\*(C`HAS_GETLOGIN\*(C'\fR,\  \f(CW\*(C`HAS_GETNAMEINFO\*(C'\fR,\  \f(CW\*(C`HAS_GETNETBYADDR\*(C'\fR,\  \f(CW\*(C`HAS_GETNETBYNAME\*(C'\fR,\  \f(CW\*(C`HAS_GETNETENT\*(C'\fR,\  \f(CW\*(C`HAS_GETPAGESIZE\*(C'\fR,\  \f(CW\*(C`HAS_GETPGID\*(C'\fR,\  \f(CW\*(C`HAS_GETPGRP\*(C'\fR,\  \f(CW\*(C`HAS_GETPGRP2\*(C'\fR,\  \f(CW\*(C`HAS_GETPPID\*(C'\fR,\  \f(CW\*(C`HAS_GETPRIORITY\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOBYNAME\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOBYNUMBER\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOENT\*(C'\fR,\  \f(CW\*(C`HAS_GETPRPWNAM\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVBYNAME\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVBYPORT\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVENT\*(C'\fR,\  \f(CW\*(C`HAS_GETSPNAM\*(C'\fR,\  \f(CW\*(C`HAS_HTONL\*(C'\fR,\  \f(CW\*(C`HAS_HTONS\*(C'\fR,\  \f(CW\*(C`HAS_HYPOT\*(C'\fR,\  \f(CW\*(C`HAS_ILOGBL\*(C'\fR,\  \f(CW\*(C`HAS_INET_ATON\*(C'\fR,\  \f(CW\*(C`HAS_INETNTOP\*(C'\fR,\  \f(CW\*(C`HAS_INETPTON\*(C'\fR,\  \f(CW\*(C`HAS_IP_MREQ\*(C'\fR,\  \f(CW\*(C`HAS_IP_MREQ_SOURCE\*(C'\fR,\  \f(CW\*(C`HAS_IPV6_MREQ\*(C'\fR,\  \f(CW\*(C`HAS_IPV6_MREQ_SOURCE\*(C'\fR,\  \f(CW\*(C`HAS_ISASCII\*(C'\fR,\  \f(CW\*(C`HAS_ISBLANK\*(C'\fR,\  \f(CW\*(C`HAS_ISLESS\*(C'\fR,\  \f(CW\*(C`HAS_KILLPG\*(C'\fR,\  \f(CW\*(C`HAS_LCHOWN\*(C'\fR,\  \f(CW\*(C`HAS_LINK\*(C'\fR,\  \f(CW\*(C`HAS_LINKAT\*(C'\fR,\  \f(CW\*(C`HAS_LLROUND\*(C'\fR,\  \f(CW\*(C`HAS_LOCKF\*(C'\fR,\  \f(CW\*(C`HAS_LOGB\*(C'\fR,\  \f(CW\*(C`HAS_LOG1P\*(C'\fR,\  \f(CW\*(C`HAS_LOG2\*(C'\fR,\  \f(CW\*(C`HAS_LROUND\*(C'\fR,\  \f(CW\*(C`HAS_LSTAT\*(C'\fR,\  \f(CW\*(C`HAS_MADVISE\*(C'\fR,\  \f(CW\*(C`HAS_MBLEN\*(C'\fR,\  \f(CW\*(C`HAS_MBRLEN\*(C'\fR,\  \f(CW\*(C`HAS_MBRTOWC\*(C'\fR,\  \f(CW\*(C`HAS_MBSTOWCS\*(C'\fR,\  \f(CW\*(C`HAS_MBTOWC\*(C'\fR,\  \f(CW\*(C`HAS_MEMMEM\*(C'\fR,\  \f(CW\*(C`HAS_MEMRCHR\*(C'\fR,\  \f(CW\*(C`HAS_MKDTEMP\*(C'\fR,\  \f(CW\*(C`HAS_MKFIFO\*(C'\fR,\  \f(CW\*(C`HAS_MKOSTEMP\*(C'\fR,\  \f(CW\*(C`HAS_MKSTEMP\*(C'\fR,\  \f(CW\*(C`HAS_MKSTEMPS\*(C'\fR,\  \f(CW\*(C`HAS_MMAP\*(C'\fR,\  \f(CW\*(C`HAS_MPROTECT\*(C'\fR,\  \f(CW\*(C`HAS_MSG\*(C'\fR,\  \f(CW\*(C`HAS_MSYNC\*(C'\fR,\  \f(CW\*(C`HAS_MUNMAP\*(C'\fR,\  \f(CW\*(C`HAS_NEARBYINT\*(C'\fR,\  \f(CW\*(C`HAS_NEXTAFTER\*(C'\fR,\  \f(CW\*(C`HAS_NICE\*(C'\fR,\  \f(CW\*(C`HAS_NTOHL\*(C'\fR,\  \f(CW\*(C`HAS_NTOHS\*(C'\fR,\  \f(CW\*(C`HAS_PATHCONF\*(C'\fR,\  \f(CW\*(C`HAS_PAUSE\*(C'\fR,\  \f(CW\*(C`HAS_PHOSTNAME\*(C'\fR,\  \f(CW\*(C`HAS_PIPE\*(C'\fR,\  \f(CW\*(C`HAS_PIPE2\*(C'\fR,\  \f(CW\*(C`HAS_PRCTL\*(C'\fR,\  \f(CW\*(C`HAS_PTRDIFF_T\*(C'\fR,\  \f(CW\*(C`HAS_READLINK\*(C'\fR,\  \f(CW\*(C`HAS_READV\*(C'\fR,\  \f(CW\*(C`HAS_RECVMSG\*(C'\fR,\  \f(CW\*(C`HAS_REMQUO\*(C'\fR,\  \f(CW\*(C`HAS_RENAME\*(C'\fR,\  \f(CW\*(C`HAS_RENAMEAT\*(C'\fR,\  \f(CW\*(C`HAS_RINT\*(C'\fR,\  \f(CW\*(C`HAS_ROUND\*(C'\fR,\  \f(CW\*(C`HAS_SCALBNL\*(C'\fR,\  \f(CW\*(C`HAS_SEM\*(C'\fR,\  \f(CW\*(C`HAS_SENDMSG\*(C'\fR,\  \f(CW\*(C`HAS_SETEGID\*(C'\fR,\  \f(CW\*(C`HAS_SETENV\*(C'\fR,\  \f(CW\*(C`HAS_SETEUID\*(C'\fR,\  \f(CW\*(C`HAS_SETGROUPS\*(C'\fR,\  \f(CW\*(C`HAS_SETHOSTENT\*(C'\fR,\  \f(CW\*(C`HAS_SETLINEBUF\*(C'\fR,\  \f(CW\*(C`HAS_SETNETENT\*(C'\fR,\  \f(CW\*(C`HAS_SETPGRP\*(C'\fR,\  \f(CW\*(C`HAS_SETPGRP2\*(C'\fR,\  \f(CW\*(C`HAS_SETPRIORITY\*(C'\fR,\  \f(CW\*(C`HAS_SETPROCTITLE\*(C'\fR,\  \f(CW\*(C`HAS_SETPROTOENT\*(C'\fR,\  \f(CW\*(C`HAS_SETREGID\*(C'\fR,\  \f(CW\*(C`HAS_SETRESGID\*(C'\fR,\  \f(CW\*(C`HAS_SETRESUID\*(C'\fR,\  \f(CW\*(C`HAS_SETREUID\*(C'\fR,\  \f(CW\*(C`HAS_SETRGID\*(C'\fR,\  \f(CW\*(C`HAS_SETRUID\*(C'\fR,\  \f(CW\*(C`HAS_SETSERVENT\*(C'\fR,\  \f(CW\*(C`HAS_SETSID\*(C'\fR,\  \f(CW\*(C`HAS_SHM\*(C'\fR,\  \f(CW\*(C`HAS_SIGACTION\*(C'\fR,\  \f(CW\*(C`HAS_SIGPROCMASK\*(C'\fR,\  \f(CW\*(C`HAS_SIN6_SCOPE_ID\*(C'\fR,\  \f(CW\*(C`HAS_SNPRINTF\*(C'\fR,\  \f(CW\*(C`HAS_STAT\*(C'\fR,\  \f(CW\*(C`HAS_STRCOLL\*(C'\fR,\  \f(CW\*(C`HAS_STRERROR_L\*(C'\fR,\  \f(CW\*(C`HAS_STRLCAT\*(C'\fR,\  \f(CW\*(C`HAS_STRLCPY\*(C'\fR,\  \f(CW\*(C`HAS_STRNLEN\*(C'\fR,\  \f(CW\*(C`HAS_STRTOD\*(C'\fR,\  \f(CW\*(C`HAS_STRTOL\*(C'\fR,\  \f(CW\*(C`HAS_STRTOLL\*(C'\fR,\  \f(CW\*(C`HAS_STRTOQ\*(C'\fR,\  \f(CW\*(C`HAS_STRTOUL\*(C'\fR,\  \f(CW\*(C`HAS_STRTOULL\*(C'\fR,\  \f(CW\*(C`HAS_STRTOUQ\*(C'\fR,\  \f(CW\*(C`HAS_STRXFRM\*(C'\fR,\  \f(CW\*(C`HAS_STRXFRM_L\*(C'\fR,\  \f(CW\*(C`HAS_SYMLINK\*(C'\fR,\  \f(CW\*(C`HAS_SYSCALL\*(C'\fR,\  \f(CW\*(C`HAS_SYSCONF\*(C'\fR,\  \f(CW\*(C`HAS_SYS_ERRLIST\*(C'\fR,\  \f(CW\*(C`HAS_SYSTEM\*(C'\fR,\  \f(CW\*(C`HAS_TCGETPGRP\*(C'\fR,\  \f(CW\*(C`HAS_TCSETPGRP\*(C'\fR,\  \f(CW\*(C`HAS_TOWLOWER\*(C'\fR,\  \f(CW\*(C`HAS_TOWUPPER\*(C'\fR,\  \f(CW\*(C`HAS_TRUNCATE\*(C'\fR,\  \f(CW\*(C`HAS_TRUNCL\*(C'\fR,\  \f(CW\*(C`HAS_UALARM\*(C'\fR,\  \f(CW\*(C`HAS_UMASK\*(C'\fR,\  \f(CW\*(C`HAS_UNLINKAT\*(C'\fR,\  \f(CW\*(C`HAS_UNSETENV\*(C'\fR,\  \f(CW\*(C`HAS_VFORK\*(C'\fR,\  \f(CW\*(C`HAS_VSNPRINTF\*(C'\fR,\  \f(CW\*(C`HAS_WAITPID\*(C'\fR,\  \f(CW\*(C`HAS_WAIT4\*(C'\fR,\  \f(CW\*(C`HAS_WCRTOMB\*(C'\fR,\  \f(CW\*(C`HAS_WCSCMP\*(C'\fR,\  \f(CW\*(C`HAS_WCSTOMBS\*(C'\fR,\  \f(CW\*(C`HAS_WCSXFRM\*(C'\fR,\  \f(CW\*(C`HAS_WCTOMB\*(C'\fR,\  \f(CW\*(C`HAS_WRITEV\*(C'\fR
+.PP
+And, the reentrant capabilities:
+.PP
+\&\f(CW\*(C`HAS_CRYPT_R\*(C'\fR,\  \f(CW\*(C`HAS_CTERMID_R\*(C'\fR,\  \f(CW\*(C`HAS_DRAND48_R\*(C'\fR,\  \f(CW\*(C`HAS_ENDHOSTENT_R\*(C'\fR,\  \f(CW\*(C`HAS_ENDNETENT_R\*(C'\fR,\  \f(CW\*(C`HAS_ENDPROTOENT_R\*(C'\fR,\  \f(CW\*(C`HAS_ENDSERVENT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETGRGID_R\*(C'\fR,\  \f(CW\*(C`HAS_GETGRNAM_R\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTBYADDR_R\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTBYNAME_R\*(C'\fR,\  \f(CW\*(C`HAS_GETHOSTENT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETLOGIN_R\*(C'\fR,\  \f(CW\*(C`HAS_GETNETBYADDR_R\*(C'\fR,\  \f(CW\*(C`HAS_GETNETBYNAME_R\*(C'\fR,\  \f(CW\*(C`HAS_GETNETENT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOBYNAME_R\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOBYNUMBER_R\*(C'\fR,\  \f(CW\*(C`HAS_GETPROTOENT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETPWNAM_R\*(C'\fR,\  \f(CW\*(C`HAS_GETPWUID_R\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVBYNAME_R\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVBYPORT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETSERVENT_R\*(C'\fR,\  \f(CW\*(C`HAS_GETSPNAM_R\*(C'\fR,\  \f(CW\*(C`HAS_RANDOM_R\*(C'\fR,\  \f(CW\*(C`HAS_READDIR_R\*(C'\fR,\  \f(CW\*(C`HAS_SETHOSTENT_R\*(C'\fR,\  \f(CW\*(C`HAS_SETNETENT_R\*(C'\fR,\  \f(CW\*(C`HAS_SETPROTOENT_R\*(C'\fR,\  \f(CW\*(C`HAS_SETSERVENT_R\*(C'\fR,\  \f(CW\*(C`HAS_SRANDOM_R\*(C'\fR,\  \f(CW\*(C`HAS_SRAND48_R\*(C'\fR,\  \f(CW\*(C`HAS_STRERROR_R\*(C'\fR,\  \f(CW\*(C`HAS_TMPNAM_R\*(C'\fR,\  \f(CW\*(C`HAS_TTYNAME_R\*(C'\fR
+.PP
+Example usage:
+.Sp
+.Vb 5
+\& #ifdef HAS_STRNLEN
+\&   use strnlen()
+\& #else
+\&   use an alternative implementation
+\& #endif
+.Ve
+.ie n .SS "List of ""#include"" needed symbols"
+.el .SS "List of \f(CW#include\fP needed symbols"
+.IX Subsection "List of #include needed symbols"
+This list contains symbols that indicate if certain \f(CW\*(C`#include\*(C'\fR
+files are present on the platform.  If your code accesses the
+functionality that one of these is for, you will need to
+\&\f(CW\*(C`#include\*(C'\fR it if the symbol on this list is \f(CW\*(C`#define\*(C'\fRd.  For
+more detail, see the corresponding entry in \fIconfig.h\fR.
+.PP
+\&\f(CW\*(C`I_ARPA_INET\*(C'\fR,\  \f(CW\*(C`I_BFD\*(C'\fR,\  \f(CW\*(C`I_CRYPT\*(C'\fR,\  \f(CW\*(C`I_DBM\*(C'\fR,\  \f(CW\*(C`I_DLFCN\*(C'\fR,\  \f(CW\*(C`I_EXECINFO\*(C'\fR,\  \f(CW\*(C`I_FP\*(C'\fR,\  \f(CW\*(C`I_FP_CLASS\*(C'\fR,\  \f(CW\*(C`I_GDBM\*(C'\fR,\  \f(CW\*(C`I_GDBMNDBM\*(C'\fR,\  \f(CW\*(C`I_GDBM_NDBM\*(C'\fR,\  \f(CW\*(C`I_GRP\*(C'\fR,\  \f(CW\*(C`I_IEEEFP\*(C'\fR,\  \f(CW\*(C`I_INTTYPES\*(C'\fR,\  \f(CW\*(C`I_LIBUTIL\*(C'\fR,\  \f(CW\*(C`I_MNTENT\*(C'\fR,\  \f(CW\*(C`I_NDBM\*(C'\fR,\  \f(CW\*(C`I_NETDB\*(C'\fR,\  \f(CW\*(C`I_NET_ERRNO\*(C'\fR,\  \f(CW\*(C`I_NETINET_IN\*(C'\fR,\  \f(CW\*(C`I_NETINET_TCP\*(C'\fR,\  \f(CW\*(C`I_PROT\*(C'\fR,\  \f(CW\*(C`I_PWD\*(C'\fR,\  \f(CW\*(C`I_RPCSVC_DBM\*(C'\fR,\  \f(CW\*(C`I_SGTTY\*(C'\fR,\  \f(CW\*(C`I_SHADOW\*(C'\fR,\  \f(CW\*(C`I_STDBOOL\*(C'\fR,\  \f(CW\*(C`I_STDINT\*(C'\fR,\  \f(CW\*(C`I_SUNMATH\*(C'\fR,\  \f(CW\*(C`I_SYS_ACCESS\*(C'\fR,\  \f(CW\*(C`I_SYS_IOCTL\*(C'\fR,\  \f(CW\*(C`I_SYSLOG\*(C'\fR,\  \f(CW\*(C`I_SYSMODE\*(C'\fR,\  \f(CW\*(C`I_SYS_MOUNT\*(C'\fR,\  \f(CW\*(C`I_SYS_PARAM\*(C'\fR,\  \f(CW\*(C`I_SYS_POLL\*(C'\fR,\  \f(CW\*(C`I_SYS_SECURITY\*(C'\fR,\  \f(CW\*(C`I_SYS_SELECT\*(C'\fR,\  \f(CW\*(C`I_SYS_STAT\*(C'\fR,\  \f(CW\*(C`I_SYS_STATVFS\*(C'\fR,\  \f(CW\*(C`I_SYS_SYSCALL\*(C'\fR,\  \f(CW\*(C`I_SYS_TIME\*(C'\fR,\  \f(CW\*(C`I_SYS_TIME_KERNEL\*(C'\fR,\  \f(CW\*(C`I_SYS_TIMES\*(C'\fR,\  \f(CW\*(C`I_SYS_TYPES\*(C'\fR,\  \f(CW\*(C`I_SYSUIO\*(C'\fR,\  \f(CW\*(C`I_SYS_UN\*(C'\fR,\  \f(CW\*(C`I_SYSUTSNAME\*(C'\fR,\  \f(CW\*(C`I_SYS_VFS\*(C'\fR,\  \f(CW\*(C`I_SYS_WAIT\*(C'\fR,\  \f(CW\*(C`I_TERMIO\*(C'\fR,\  \f(CW\*(C`I_TERMIOS\*(C'\fR,\  \f(CW\*(C`I_UNISTD\*(C'\fR,\  \f(CW\*(C`I_USTAT\*(C'\fR,\  \f(CW\*(C`I_VFORK\*(C'\fR,\  \f(CW\*(C`I_WCHAR\*(C'\fR,\  \f(CW\*(C`I_WCTYPE\*(C'\fR
+.PP
+Example usage:
+.Sp
+.Vb 3
+\& #ifdef I_WCHAR
+\&   #include <wchar.h>
+\& #endif
+.Ve
+.SH "Global Variables"
+.IX Header "Global Variables"
+These variables are global to an entire process.  They are shared between
+all interpreters and all threads in a process.  Any variables not documented
+here may be changed or removed without notice, so don't use them!
+If you feel you really do need to use an unlisted variable, first send email to
+perl5\-porters@perl.org <mailto:perl5-porters@perl.org>.  It may be that
+someone there will point out a way to accomplish what you need without using an
+internal variable.  But if not, you should get a go-ahead to document and then
+use the variable.
+.ie n .IP """PL_check""" 4
+.el .IP \f(CWPL_check\fR 4
+.IX Xref "PL_check"
+.IX Item "PL_check"
+Array, indexed by opcode, of functions that will be called for the "check"
+phase of optree building during compilation of Perl code.  For most (but
+not all) types of op, once the op has been initially built and populated
+with child ops it will be filtered through the check function referenced
+by the appropriate element of this array.  The new op is passed in as the
+sole argument to the check function, and the check function returns the
+completed op.  The check function may (as the name suggests) check the op
+for validity and signal errors.  It may also initialise or modify parts of
+the ops, or perform more radical surgery such as adding or removing child
+ops, or even throw the op away and return a different op in its place.
+.Sp
+This array of function pointers is a convenient place to hook into the
+compilation process.  An XS module can put its own custom check function
+in place of any of the standard ones, to influence the compilation of a
+particular type of op.  However, a custom check function must never fully
+replace a standard check function (or even a custom check function from
+another module).  A module modifying checking must instead \fBwrap\fR the
+preexisting check function.  A custom check function must be selective
+about when to apply its custom behaviour.  In the usual case where
+it decides not to do anything special with an op, it must chain the
+preexisting op function.  Check functions are thus linked in a chain,
+with the core's base checker at the end.
+.Sp
+For thread safety, modules should not write directly to this array.
+Instead, use the function "wrap_op_checker".
+.ie n .IP """PL_infix_plugin""" 4
+.el .IP \f(CWPL_infix_plugin\fR 4
+.IX Xref "PL_infix_plugin"
+.IX Item "PL_infix_plugin"
+NOTE: \f(CW\*(C`PL_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+\&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
+\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
+use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
+of new infix operators.
+.Sp
+Function pointer, pointing at a function used to handle extended infix
+operators. The function should be declared as
+.Sp
+.Vb 3
+\&        int infix_plugin_function(pTHX_
+\&                char *opname, STRLEN oplen,
+\&                struct Perl_custom_infix **infix_ptr)
+.Ve
+.Sp
+The function is called from the tokenizer whenever a possible infix operator
+is seen. \f(CW\*(C`opname\*(C'\fR points to the operator name in the parser's input buffer,
+and \f(CW\*(C`oplen\*(C'\fR gives the \fImaximum\fR number of bytes of it that should be
+consumed; it is not null-terminated. The function is expected to examine the
+operator name and possibly other state such as %^H, to
+determine whether it wants to handle the operator name.
+.Sp
+As compared to the single stage of \f(CW\*(C`PL_keyword_plugin\*(C'\fR, parsing of additional
+infix operators occurs in three separate stages. This is because of the more
+complex interactions it has with the parser, to ensure that operator
+precedence rules work correctly. These stages are co-ordinated by the use of
+an additional information structure.
+.Sp
+If the function wants to handle the infix operator, it must set the variable
+pointed to by \f(CW\*(C`infix_ptr\*(C'\fR to the address of a structure that provides this
+additional information about the subsequent parsing stages. If it does not,
+it should make a call to the next function in the chain.
+.Sp
+This structure has the following definition:
+.Sp
+.Vb 7
+\&        struct Perl_custom_infix {
+\&            enum Perl_custom_infix_precedence prec;
+\&            void (*parse)(pTHX_ SV **opdata,
+\&                struct Perl_custom_infix *);
+\&            OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
+\&                struct Perl_custom_infix *);
+\&        };
+.Ve
+.Sp
+The function must then return an integer giving the number of bytes consumed
+by the name of this operator. In the case of an operator whose name is
+composed of identifier characters, this must be equal to \f(CW\*(C`oplen\*(C'\fR. In the case
+of an operator named by non-identifier characters, this is permitted to be
+shorter than \f(CW\*(C`oplen\*(C'\fR, and any additional characters after it will not be
+claimed by the infix operator but instead will be consumed by the tokenizer
+and parser as normal.
+.Sp
+If the optional \f(CW\*(C`parse\*(C'\fR function is provided, it is called immediately by the
+parser to let the operator's definition consume any additional syntax from the
+source code. This should \fInot\fR be used for normal operand parsing, but it may
+be useful when implementing things like parametric operators or meta-operators
+that consume more syntax themselves. This function may use the variable
+pointed to by \f(CW\*(C`opdata\*(C'\fR to provide an SV containing additional data to be
+passed into the \f(CW\*(C`build_op\*(C'\fR function later on.
+.Sp
+The information structure gives the operator precedence level in the \f(CW\*(C`prec\*(C'\fR
+field. This is used to tell the parser how much of the surrounding syntax
+before and after should be considered as operands to the operator.
+.Sp
+The tokenizer and parser will then continue to operate as normal until enough
+additional input has been parsed to form both the left\- and right-hand side
+operands to the operator, according to the precedence level. At this point the
+\&\f(CW\*(C`build_op\*(C'\fR function is called, being passed the left\- and right-hand operands
+as optree fragments. It is expected to combine them into the resulting optree
+fragment, which it should return.
+.Sp
+After the \f(CW\*(C`build_op\*(C'\fR function has returned, if the variable pointed to by
+\&\f(CW\*(C`opdata\*(C'\fR was set to a non\-\f(CW\*(C`NULL\*(C'\fR value, it will then be destroyed by calling
+\&\f(CWSvREFCNT_dec()\fR.
+.Sp
+For thread safety, modules should not set this variable directly.
+Instead, use the function "wrap_infix_plugin".
+.Sp
+However, that all said, the introductory note above still applies. This
+variable is provided in core perl only for the benefit of the
+\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR module. That module acts as a central registry for infix
+operators, automatically handling things like deparse support and
+discovery/reflection, and these abilities only work because it knows all the
+registered operators. Other modules should not use this interpreter variable
+directly to implement them because then those central features would no longer
+work properly.
+.Sp
+Furthermore, it is likely that this (experimental) API will be replaced in a
+future Perl version by a more complete API that fully implements the central
+registry and other semantics currently provided by \f(CW\*(C`XS::Parse::Infix\*(C'\fR, once
+the module has had sufficient experimental testing time. This current
+mechanism exists only as an interim measure to get to that stage.
+.ie n .IP """PL_keyword_plugin""" 4
+.el .IP \f(CWPL_keyword_plugin\fR 4
+.IX Xref "PL_keyword_plugin"
+.IX Item "PL_keyword_plugin"
+NOTE: \f(CW\*(C`PL_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Function pointer, pointing at a function used to handle extended keywords.
+The function should be declared as
+.Sp
+.Vb 3
+\&        int keyword_plugin_function(pTHX_
+\&                char *keyword_ptr, STRLEN keyword_len,
+\&                OP **op_ptr)
+.Ve
+.Sp
+The function is called from the tokeniser, whenever a possible keyword
+is seen.  \f(CW\*(C`keyword_ptr\*(C'\fR points at the word in the parser's input
+buffer, and \f(CW\*(C`keyword_len\*(C'\fR gives its length; it is not null-terminated.
+The function is expected to examine the word, and possibly other state
+such as %^H, to decide whether it wants to handle it
+as an extended keyword.  If it does not, the function should return
+\&\f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR, and the normal parser process will continue.
+.Sp
+If the function wants to handle the keyword, it first must
+parse anything following the keyword that is part of the syntax
+introduced by the keyword.  See "Lexer interface" for details.
+.Sp
+When a keyword is being handled, the plugin function must build
+a tree of \f(CW\*(C`OP\*(C'\fR structures, representing the code that was parsed.
+The root of the tree must be stored in \f(CW*op_ptr\fR.  The function then
+returns a constant indicating the syntactic role of the construct that
+it has parsed: \f(CW\*(C`KEYWORD_PLUGIN_STMT\*(C'\fR if it is a complete statement, or
+\&\f(CW\*(C`KEYWORD_PLUGIN_EXPR\*(C'\fR if it is an expression.  Note that a statement
+construct cannot be used inside an expression (except via \f(CW\*(C`do BLOCK\*(C'\fR
+and similar), and an expression is not a complete statement (it requires
+at least a terminating semicolon).
+.Sp
+When a keyword is handled, the plugin function may also have
+(compile-time) side effects.  It may modify \f(CW\*(C`%^H\*(C'\fR, define functions, and
+so on.  Typically, if side effects are the main purpose of a handler,
+it does not wish to generate any ops to be included in the normal
+compilation.  In this case it is still required to supply an op tree,
+but it suffices to generate a single null op.
+.Sp
+That's how the \f(CW*PL_keyword_plugin\fR function needs to behave overall.
+Conventionally, however, one does not completely replace the existing
+handler function.  Instead, take a copy of \f(CW\*(C`PL_keyword_plugin\*(C'\fR before
+assigning your own function pointer to it.  Your handler function should
+look for keywords that it is interested in and handle those.  Where it
+is not interested, it should call the saved plugin function, passing on
+the arguments it received.  Thus \f(CW\*(C`PL_keyword_plugin\*(C'\fR actually points
+at a chain of handler functions, all of which have an opportunity to
+handle keywords, and only the last function in the chain (built into
+the Perl core) will normally return \f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR.
+.Sp
+For thread safety, modules should not set this variable directly.
+Instead, use the function "wrap_keyword_plugin".
+.ie n .IP """PL_phase""" 4
+.el .IP \f(CWPL_phase\fR 4
+.IX Xref "PL_phase"
+.IX Item "PL_phase"
+A value that indicates the current Perl interpreter's phase. Possible values
+include \f(CW\*(C`PERL_PHASE_CONSTRUCT\*(C'\fR, \f(CW\*(C`PERL_PHASE_START\*(C'\fR, \f(CW\*(C`PERL_PHASE_CHECK\*(C'\fR,
+\&\f(CW\*(C`PERL_PHASE_INIT\*(C'\fR, \f(CW\*(C`PERL_PHASE_RUN\*(C'\fR, \f(CW\*(C`PERL_PHASE_END\*(C'\fR, and
+\&\f(CW\*(C`PERL_PHASE_DESTRUCT\*(C'\fR.
+.Sp
+For example, the following determines whether the interpreter is in
+global destruction:
+.Sp
+.Vb 3
+\&    if (PL_phase == PERL_PHASE_DESTRUCT) {
+\&        // we are in global destruction
+\&    }
+.Ve
+.Sp
+\&\f(CW\*(C`PL_phase\*(C'\fR was introduced in Perl 5.14; in prior perls you can use
+\&\f(CW\*(C`PL_dirty\*(C'\fR (boolean) to determine whether the interpreter is in global
+destruction. (Use of \f(CW\*(C`PL_dirty\*(C'\fR is discouraged since 5.14.)
+.RS 4
+.Sp
+.Vb 1
+\& enum perl_phase  PL_phase
+.Ve
+.RE
+.RS 4
+.RE
+.SH "GV Handling and Stashes"
+.IX Xref "GV GV_ADD GV_ADDMG GV_ADDMULTI GV_ADDWARN GV_NOADD_NOINIT GV_NOEXPAND GV_NOINIT GV_NOTQUAL GV_NO_SVGMAGIC GV_SUPER SVf_UTF8"
+.IX Header "GV Handling and Stashes"
+A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
+It is a structure that holds a pointer to a scalar, an array, a hash etc,
+corresponding to \f(CW$foo\fR, \f(CW@foo\fR, \f(CW%foo\fR.
+.PP
+GVs are usually found as values in stashes (symbol table hashes) where
+Perl stores its global variables.
+.PP
+A \fBstash\fR is a hash that contains all variables that are defined
+within a package.  See "Stashes and Globs" in perlguts
+.ie n .IP """amagic_call""" 4
+.el .IP \f(CWamagic_call\fR 4
+.IX Xref "amagic_call"
+.IX Item "amagic_call"
+Perform the overloaded (active magic) operation given by \f(CW\*(C`method\*(C'\fR.
+\&\f(CW\*(C`method\*(C'\fR is one of the values found in \fIoverload.h\fR.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR affects how the operation is performed, as follows:
+.RS 4
+.ie n .IP """AMGf_noleft""" 4
+.el .IP \f(CWAMGf_noleft\fR 4
+.IX Item "AMGf_noleft"
+\&\f(CW\*(C`left\*(C'\fR is not to be used in this operation.
+.ie n .IP """AMGf_noright""" 4
+.el .IP \f(CWAMGf_noright\fR 4
+.IX Item "AMGf_noright"
+\&\f(CW\*(C`right\*(C'\fR is not to be used in this operation.
+.ie n .IP """AMGf_unary""" 4
+.el .IP \f(CWAMGf_unary\fR 4
+.IX Item "AMGf_unary"
+The operation is done only on just one operand.
+.ie n .IP """AMGf_assign""" 4
+.el .IP \f(CWAMGf_assign\fR 4
+.IX Item "AMGf_assign"
+The operation changes one of the operands, e.g., \f(CW$x\fR += 1
+.RE
+.RS 4
+.Sp
+.Vb 1
+\& SV *  amagic_call(SV *left, SV *right, int method, int dir)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """amagic_deref_call""" 4
+.el .IP \f(CWamagic_deref_call\fR 4
+.IX Xref "amagic_deref_call"
+.IX Item "amagic_deref_call"
+Perform \f(CW\*(C`method\*(C'\fR overloading dereferencing on \f(CW\*(C`ref\*(C'\fR, returning the
+dereferenced result.  \f(CW\*(C`method\*(C'\fR must be one of the dereference operations given
+in \fIoverload.h\fR.
+.Sp
+If overloading is inactive on \f(CW\*(C`ref\*(C'\fR, returns \f(CW\*(C`ref\*(C'\fR itself.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  amagic_deref_call(SV *ref, int method)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_add_by_type""" 4
+.el .IP \f(CWgv_add_by_type\fR 4
+.IX Xref "gv_add_by_type"
+.IX Item "gv_add_by_type"
+Make sure there is a slot of type \f(CW\*(C`type\*(C'\fR in the GV \f(CW\*(C`gv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  gv_add_by_type(GV *gv, svtype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Gv_AMupdate""" 4
+.el .IP \f(CWGv_AMupdate\fR 4
+.IX Xref "Gv_AMupdate"
+.IX Item "Gv_AMupdate"
+Recalculates overload magic in the package given by \f(CW\*(C`stash\*(C'\fR.
+.Sp
+Returns:
+.RS 4
+.IP "1 on success and there is some overload" 4
+.IX Item "1 on success and there is some overload"
+.PD 0
+.IP "0 if there is no overload" 4
+.IX Item "0 if there is no overload"
+.ie n .IP "\-1 if some error occurred and it couldn't croak (because ""destructing"" is true)." 4
+.el .IP "\-1 if some error occurred and it couldn't croak (because \f(CWdestructing\fR is true)." 4
+.IX Item "-1 if some error occurred and it couldn't croak (because destructing is true)."
+.RE
+.RS 4
+.PD
+.Sp
+.Vb 1
+\& int  Gv_AMupdate(HV *stash, bool destructing)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_autoload_pv""" 4
+.el .IP \f(CWgv_autoload_pv\fR 4
+.IX Item "gv_autoload_pv"
+.PD 0
+.ie n .IP """gv_autoload_pvn""" 4
+.el .IP \f(CWgv_autoload_pvn\fR 4
+.IX Item "gv_autoload_pvn"
+.ie n .IP """gv_autoload_sv""" 4
+.el .IP \f(CWgv_autoload_sv\fR 4
+.IX Xref "gv_autoload_pv gv_autoload_pvn gv_autoload_sv"
+.IX Item "gv_autoload_sv"
+.PD
+These each search for an \f(CW\*(C`AUTOLOAD\*(C'\fR method, returning NULL if not found, or
+else returning a pointer to its GV, while setting the package
+\&\f(CW$AUTOLOAD\fR variable to \f(CW\*(C`name\*(C'\fR (fully qualified).  Also,
+if found and the GV's CV is an XSUB, the CV's PV will be set to \f(CW\*(C`name\*(C'\fR, and
+its stash will be set to the stash of the GV.
+.Sp
+Searching is done in \f(CW\*(C`MRO\*(C'\fR order, as specified in
+"\f(CW\*(C`gv_fetchmeth\*(C'\fR", beginning with \f(CW\*(C`stash\*(C'\fR if it isn't NULL.
+.Sp
+The forms differ only in how \f(CW\*(C`name\*(C'\fR is specified.
+.Sp
+In \f(CW\*(C`gv_autoload_pv\*(C'\fR, \f(CW\*(C`namepv\*(C'\fR is a C language NUL-terminated string.
+.Sp
+In \f(CW\*(C`gv_autoload_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
+additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes.  Hence, \f(CW*name\fR
+may contain embedded-NUL characters.
+.Sp
+In \f(CW\*(C`gv_autoload_sv\*(C'\fR, \f(CW*namesv\fR is an SV, and the name is the PV extracted
+from that using "\f(CW\*(C`SvPV\*(C'\fR".  If the SV is marked as being in UTF\-8, the
+extracted PV will also be.
+.RS 4
+.Sp
+.Vb 4
+\& GV *  gv_autoload_pv (HV *stash, const char *namepv, U32 flags)
+\& GV *  gv_autoload_pvn(HV *stash, const char *name, STRLEN len,
+\&                       U32 flags)
+\& GV *  gv_autoload_sv (HV *stash, SV *namesv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_autoload4""" 4
+.el .IP \f(CWgv_autoload4\fR 4
+.IX Xref "gv_autoload4"
+.IX Item "gv_autoload4"
+Equivalent to \f(CW"gv_autoload_pvn"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_autoload4(HV *stash, const char *name, STRLEN len,
+\&                    I32 method)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GvAV""" 4
+.el .IP \f(CWGvAV\fR 4
+.IX Xref "GvAV"
+.IX Item "GvAV"
+Return the AV from the GV.
+.RS 4
+.Sp
+.Vb 1
+\& AV*  GvAV(GV* gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_AVadd""" 4
+.el .IP \f(CWgv_AVadd\fR 4
+.IX Item "gv_AVadd"
+.PD 0
+.ie n .IP """gv_HVadd""" 4
+.el .IP \f(CWgv_HVadd\fR 4
+.IX Item "gv_HVadd"
+.ie n .IP """gv_IOadd""" 4
+.el .IP \f(CWgv_IOadd\fR 4
+.IX Item "gv_IOadd"
+.ie n .IP """gv_SVadd""" 4
+.el .IP \f(CWgv_SVadd\fR 4
+.IX Xref "gv_AVadd gv_HVadd gv_IOadd gv_SVadd"
+.IX Item "gv_SVadd"
+.PD
+Make sure there is a slot of the given type (AV, HV, IO, SV) in the GV \f(CW\*(C`gv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  gv_AVadd(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_const_sv""" 4
+.el .IP \f(CWgv_const_sv\fR 4
+.IX Xref "gv_const_sv"
+.IX Item "gv_const_sv"
+If \f(CW\*(C`gv\*(C'\fR is a typeglob whose subroutine entry is a constant sub eligible for
+inlining, or \f(CW\*(C`gv\*(C'\fR is a placeholder reference that would be promoted to such
+a typeglob, then returns the value returned by the sub.  Otherwise, returns
+\&\f(CW\*(C`NULL\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  gv_const_sv(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GvCV""" 4
+.el .IP \f(CWGvCV\fR 4
+.IX Xref "GvCV"
+.IX Item "GvCV"
+Return the CV from the GV.
+.RS 4
+.Sp
+.Vb 1
+\& CV*  GvCV(GV* gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_efullname3""" 4
+.el .IP \f(CWgv_efullname3\fR 4
+.IX Item "gv_efullname3"
+.PD 0
+.ie n .IP """gv_efullname4""" 4
+.el .IP \f(CWgv_efullname4\fR 4
+.IX Item "gv_efullname4"
+.ie n .IP """gv_fullname3""" 4
+.el .IP \f(CWgv_fullname3\fR 4
+.IX Item "gv_fullname3"
+.ie n .IP """gv_fullname4""" 4
+.el .IP \f(CWgv_fullname4\fR 4
+.IX Xref "gv_efullname3 gv_efullname4 gv_fullname3 gv_fullname4"
+.IX Item "gv_fullname4"
+.PD
+Place the full package name of \f(CW\*(C`gv\*(C'\fR into \f(CW\*(C`sv\*(C'\fR.  The \f(CW\*(C`gv_e*\*(C'\fR forms return
+instead the effective package name (see "HvENAME").
+.Sp
+If \f(CW\*(C`prefix\*(C'\fR is non-NULL, it is considered to be a C language NUL-terminated
+string, and the stored name will be prefaced with it.
+.Sp
+The other difference between the functions is that the \f(CW*4\fR forms have an
+extra parameter, \f(CW\*(C`keepmain\*(C'\fR.  If \f(CW\*(C`true\*(C'\fR an initial \f(CW\*(C`main::\*(C'\fR in the name is
+kept; if \f(CW\*(C`false\*(C'\fR it is stripped.  With the \f(CW*3\fR forms, it is always kept.
+.RS 4
+.Sp
+.Vb 6
+\& void  gv_efullname3(SV *sv, const GV *gv, const char *prefix)
+\& void  gv_efullname4(SV *sv, const GV *gv, const char *prefix,
+\&                     bool keepmain)
+\& void  gv_fullname3 (SV *sv, const GV *gv, const char *prefix)
+\& void  gv_fullname4 (SV *sv, const GV *gv, const char *prefix,
+\&                     bool keepmain)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchfile""" 4
+.el .IP \f(CWgv_fetchfile\fR 4
+.IX Item "gv_fetchfile"
+.PD 0
+.ie n .IP """gv_fetchfile_flags""" 4
+.el .IP \f(CWgv_fetchfile_flags\fR 4
+.IX Xref "gv_fetchfile gv_fetchfile_flags"
+.IX Item "gv_fetchfile_flags"
+.PD
+These return the debugger glob for the file (compiled by Perl) whose name is
+given by the \f(CW\*(C`name\*(C'\fR parameter.
+.Sp
+There are currently exactly two differences between these functions.
+.Sp
+The \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile\*(C'\fR is a C string, meaning it is
+\&\f(CW\*(C`NUL\*(C'\fR\-terminated; whereas the \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile_flags\*(C'\fR is a
+Perl string, whose length (in bytes) is passed in via the \f(CW\*(C`namelen\*(C'\fR parameter
+This means the name may contain embedded \f(CW\*(C`NUL\*(C'\fR characters.
+\&\f(CW\*(C`namelen\*(C'\fR doesn't exist in plain \f(CW\*(C`gv_fetchfile\*(C'\fR).
+.Sp
+The other difference is that \f(CW\*(C`gv_fetchfile_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR
+parameter, which is currently completely ignored, but allows for possible
+future extensions.
+.RS 4
+.Sp
+.Vb 3
+\& GV *  gv_fetchfile      (const char *name)
+\& GV *  gv_fetchfile_flags(const char * const name,
+\&                          const STRLEN len, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmeth""" 4
+.el .IP \f(CWgv_fetchmeth\fR 4
+.IX Item "gv_fetchmeth"
+.PD 0
+.ie n .IP """gv_fetchmeth_pv""" 4
+.el .IP \f(CWgv_fetchmeth_pv\fR 4
+.IX Item "gv_fetchmeth_pv"
+.ie n .IP """gv_fetchmeth_pvn""" 4
+.el .IP \f(CWgv_fetchmeth_pvn\fR 4
+.IX Item "gv_fetchmeth_pvn"
+.ie n .IP """gv_fetchmeth_sv""" 4
+.el .IP \f(CWgv_fetchmeth_sv\fR 4
+.IX Xref "gv_fetchmeth gv_fetchmeth_pv gv_fetchmeth_pvn gv_fetchmeth_sv"
+.IX Item "gv_fetchmeth_sv"
+.PD
+These each look for a glob with name \f(CW\*(C`name\*(C'\fR, containing a defined subroutine,
+returning the GV of that glob if found, or \f(CW\*(C`NULL\*(C'\fR if not.
+.Sp
+\&\f(CW\*(C`stash\*(C'\fR is always searched (first), unless it is \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+If \f(CW\*(C`stash\*(C'\fR is NULL, or was searched but nothing was found in it, and the
+\&\f(CW\*(C`GV_SUPER\*(C'\fR bit is set in \f(CW\*(C`flags\*(C'\fR, stashes accessible via \f(CW@ISA\fR are searched
+next.  Searching is conducted according to \f(CW\*(C`MRO\*(C'\fR order.
+.Sp
+Finally, if no matches were found so far, and the \f(CW\*(C`GV_NOUNIVERSAL\*(C'\fR flag in
+\&\f(CW\*(C`flags\*(C'\fR is not set,  \f(CW\*(C`UNIVERSAL::\*(C'\fR is searched.
+.Sp
+The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1.  If \-1, the function will
+return without any side effects or caching.  If 0, the function makes sure
+there is a glob named \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`stash\*(C'\fR, creating one if necessary.
+The subroutine slot in the glob will be set to any subroutine found in the
+\&\f(CW\*(C`stash\*(C'\fR and \f(CW\*(C`SUPER::\*(C'\fR search, hence caching any \f(CW\*(C`SUPER::\*(C'\fR result.  Note that
+subroutines found in \f(CW\*(C`UNIVERSAL::\*(C'\fR are not cached.
+.Sp
+The GV returned from these may be a method cache entry, which is not visible to
+Perl code.  So when calling \f(CW\*(C`call_sv\*(C'\fR, you should not use the GV directly;
+instead, you should use the method's CV, which can be obtained from the GV with
+the \f(CW\*(C`GvCV\*(C'\fR macro.
+.Sp
+The only other significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR, indicating that
+\&\f(CW\*(C`name\*(C'\fR is to be treated as being encoded in UTF\-8.
+.Sp
+Plain \f(CW\*(C`gv_fetchmeth\*(C'\fR lacks a \f(CW\*(C`flags\*(C'\fR parameter, hence always searches in
+\&\f(CW\*(C`stash\*(C'\fR, then \f(CW\*(C`UNIVERSAL::\*(C'\fR, and \f(CW\*(C`name\*(C'\fR is never UTF\-8.  Otherwise it is
+exactly like \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR.
+.Sp
+The other forms do have a \f(CW\*(C`flags\*(C'\fR parameter, and differ only in how the glob
+name is specified.
+.Sp
+In \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a C language NUL-terminated string.
+.Sp
+In \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
+additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes.  Hence, the name
+may contain embedded-NUL characters.
+.Sp
+In \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR, \f(CW*name\fR is an SV, and the name is the PV extracted from
+that, using "\f(CW\*(C`SvPV\*(C'\fR".  If the SV is marked as being in UTF\-8, the extracted
+PV will also be.
+.RS 4
+.Sp
+.Vb 8
+\& GV *  gv_fetchmeth    (HV *stash, const char *name, STRLEN len,
+\&                        I32 level)
+\& GV *  gv_fetchmeth_pv (HV *stash, const char *name, I32 level,
+\&                        U32 flags)
+\& GV *  gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len,
+\&                        I32 level, U32 flags)
+\& GV *  gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level,
+\&                        U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmeth_autoload""" 4
+.el .IP \f(CWgv_fetchmeth_autoload\fR 4
+.IX Xref "gv_fetchmeth_autoload"
+.IX Item "gv_fetchmeth_autoload"
+This is the old form of "gv_fetchmeth_pvn_autoload", which has no flags
+parameter.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_fetchmeth_autoload(HV *stash, const char *name,
+\&                             STRLEN len, I32 level)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmethod""" 4
+.el .IP \f(CWgv_fetchmethod\fR 4
+.IX Xref "gv_fetchmethod"
+.IX Item "gv_fetchmethod"
+See "gv_fetchmethod_autoload".
+.RS 4
+.Sp
+.Vb 1
+\& GV *  gv_fetchmethod(HV *stash, const char *name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmethod_autoload""" 4
+.el .IP \f(CWgv_fetchmethod_autoload\fR 4
+.IX Xref "gv_fetchmethod_autoload"
+.IX Item "gv_fetchmethod_autoload"
+Returns the glob which contains the subroutine to call to invoke the method
+on the \f(CW\*(C`stash\*(C'\fR.  In fact in the presence of autoloading this may be the
+glob for "AUTOLOAD".  In this case the corresponding variable \f(CW$AUTOLOAD\fR is
+already setup.
+.Sp
+The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether
+AUTOLOAD lookup is performed if the given method is not present: non-zero
+means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
+Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR
+with a non-zero \f(CW\*(C`autoload\*(C'\fR parameter.
+.Sp
+These functions grant \f(CW"SUPER"\fR token
+as a prefix of the method name.  Note
+that if you want to keep the returned glob for a long time, you need to
+check for it being "AUTOLOAD", since at the later time the call may load a
+different subroutine due to \f(CW$AUTOLOAD\fR changing its value.  Use the glob
+created as a side effect to do this.
+.Sp
+These functions have the same side-effects as \f(CW\*(C`gv_fetchmeth\*(C'\fR with
+\&\f(CW\*(C`level==0\*(C'\fR.  The warning against passing the GV returned by
+\&\f(CW\*(C`gv_fetchmeth\*(C'\fR to \f(CW\*(C`call_sv\*(C'\fR applies equally to these functions.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_fetchmethod_autoload(HV *stash, const char *name,
+\&                               I32 autoload)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmeth_pv_autoload""" 4
+.el .IP \f(CWgv_fetchmeth_pv_autoload\fR 4
+.IX Xref "gv_fetchmeth_pv_autoload"
+.IX Item "gv_fetchmeth_pv_autoload"
+Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-terminated string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_fetchmeth_pv_autoload(HV *stash, const char *name,
+\&                                I32 level, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmeth_pvn_autoload""" 4
+.el .IP \f(CWgv_fetchmeth_pvn_autoload\fR 4
+.IX Xref "gv_fetchmeth_pvn_autoload"
+.IX Item "gv_fetchmeth_pvn_autoload"
+Same as \f(CWgv_fetchmeth_pvn()\fR, but looks for autoloaded subroutines too.
+Returns a glob for the subroutine.
+.Sp
+For an autoloaded subroutine without a GV, will create a GV even
+if \f(CW\*(C`level < 0\*(C'\fR.  For an autoloaded subroutine without a stub, \f(CWGvCV()\fR
+of the result may be zero.
+.Sp
+Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_fetchmeth_pvn_autoload(HV *stash, const char *name,
+\&                                 STRLEN len, I32 level, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchmeth_sv_autoload""" 4
+.el .IP \f(CWgv_fetchmeth_sv_autoload\fR 4
+.IX Xref "gv_fetchmeth_sv_autoload"
+.IX Item "gv_fetchmeth_sv_autoload"
+Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string in the form
+of an SV instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level,
+\&                                U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_fetchpv""" 4
+.el .IP \f(CWgv_fetchpv\fR 4
+.IX Item "gv_fetchpv"
+.PD 0
+.ie n .IP """gv_fetchpvn""" 4
+.el .IP \f(CWgv_fetchpvn\fR 4
+.IX Item "gv_fetchpvn"
+.ie n .IP """gv_fetchpvn_flags""" 4
+.el .IP \f(CWgv_fetchpvn_flags\fR 4
+.IX Item "gv_fetchpvn_flags"
+.ie n .IP """gv_fetchpvs""" 4
+.el .IP \f(CWgv_fetchpvs\fR 4
+.IX Item "gv_fetchpvs"
+.ie n .IP """gv_fetchsv""" 4
+.el .IP \f(CWgv_fetchsv\fR 4
+.IX Item "gv_fetchsv"
+.ie n .IP """gv_fetchsv_nomg""" 4
+.el .IP \f(CWgv_fetchsv_nomg\fR 4
+.IX Xref "gv_fetchpv gv_fetchpvn gv_fetchpvn_flags gv_fetchpvs gv_fetchsv gv_fetchsv_nomg"
+.IX Item "gv_fetchsv_nomg"
+.PD
+These all return the GV of type \f(CW\*(C`sv_type\*(C'\fR whose name is given by the inputs,
+or NULL if no GV of that name and type could be found.  See "Stashes
+and Globs" in perlguts.
+.Sp
+The only differences are how the input name is specified, and if 'get' magic is
+normally used in getting that name.
+.Sp
+Don't be fooled by the fact that only one form has \f(CW\*(C`flags\*(C'\fR in its name.  They
+all have a \f(CW\*(C`flags\*(C'\fR parameter in fact, and all the flag bits have the same
+meanings for all
+.Sp
+If any of the flags \f(CW\*(C`GV_ADD\*(C'\fR, \f(CW\*(C`GV_ADDMG\*(C'\fR, \f(CW\*(C`GV_ADDWARN\*(C'\fR, \f(CW\*(C`GV_ADDMULTI\*(C'\fR, or
+\&\f(CW\*(C`GV_NOINIT\*(C'\fR is set, a GV is created if none already exists for the input name
+and type.  However, \f(CW\*(C`GV_ADDMG\*(C'\fR will only do the creation for magical GV's.
+For all of these flags except \f(CW\*(C`GV_NOINIT\*(C'\fR, \f(CW"gv_init_pvn"\fR is called after
+the addition.  \f(CW\*(C`GV_ADDWARN\*(C'\fR is used when the caller expects that adding won't
+be necessary because the symbol should already exist; but if not, add it
+anyway, with a warning that it was unexpectedly absent.  The \f(CW\*(C`GV_ADDMULTI\*(C'\fR
+flag means to pretend that the GV has been seen before (\fIi.e.\fR, suppress "Used
+once" warnings).
+.Sp
+The flag \f(CW\*(C`GV_NOADD_NOINIT\*(C'\fR causes \f(CW"gv_init_pvn"\fR not be to called if the
+GV existed but isn't PVGV.
+.Sp
+If the \f(CW\*(C`SVf_UTF8\*(C'\fR bit is set, the name is treated as being encoded in UTF\-8;
+otherwise the name won't be considered to be UTF\-8 in the \f(CW\*(C`pv\*(C'\fR\-named forms,
+and the UTF\-8ness of the underlying SVs will be used in the \f(CW\*(C`sv\*(C'\fR forms.
+.Sp
+If the flag \f(CW\*(C`GV_NOTQUAL\*(C'\fR is set, the caller warrants that the input name is a
+plain symbol name, not qualified with a package, otherwise the name is checked
+for being a qualified one.
+.Sp
+In \f(CW\*(C`gv_fetchpv\*(C'\fR, \f(CW\*(C`nambeg\*(C'\fR is a C string, NUL-terminated with no intermediate
+NULs.
+.Sp
+In \f(CW\*(C`gv_fetchpvs\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a literal C string, hence is enclosed in
+double quotes.
+.Sp
+\&\f(CW\*(C`gv_fetchpvn\*(C'\fR and \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR are identical.  In these, <nambeg> is
+a Perl string whose byte length is given by \f(CW\*(C`full_len\*(C'\fR, and may contain
+embedded NULs.
+.Sp
+In \f(CW\*(C`gv_fetchsv\*(C'\fR and \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR, the name is extracted from the PV of
+the input \f(CW\*(C`name\*(C'\fR SV.  The only difference between these two forms is that
+\&'get' magic is normally done on \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`gv_fetchsv\*(C'\fR, and always skipped
+with \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR.  Including \f(CW\*(C`GV_NO_SVGMAGIC\*(C'\fR in the \f(CW\*(C`flags\*(C'\fR parameter
+to \f(CW\*(C`gv_fetchsv\*(C'\fR makes it behave identically to \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR.
+.RS 4
+.Sp
+.Vb 9
+\& GV *  gv_fetchpv       (const char *nambeg, I32 flags,
+\&                         const svtype sv_type)
+\& GV *  gv_fetchpvn      (const char * nambeg, STRLEN full_len,
+\&                         I32 flags, const svtype sv_type)
+\& GV *  gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags,
+\&                         const svtype sv_type)
+\& GV *  gv_fetchpvs      ("name", I32 flags, const svtype sv_type)
+\& GV *  gv_fetchsv       (SV *name, I32 flags, const svtype sv_type)
+\& GV *  gv_fetchsv_nomg  (SV *name, I32 flags, const svtype sv_type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GvHV""" 4
+.el .IP \f(CWGvHV\fR 4
+.IX Xref "GvHV"
+.IX Item "GvHV"
+Return the HV from the GV.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  GvHV(GV* gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_init""" 4
+.el .IP \f(CWgv_init\fR 4
+.IX Xref "gv_init"
+.IX Item "gv_init"
+The old form of \f(CWgv_init_pvn()\fR.  It does not work with UTF\-8 strings, as it
+has no flags parameter.  If the \f(CW\*(C`multi\*(C'\fR parameter is set, the
+\&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag will be passed to \f(CWgv_init_pvn()\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  gv_init(GV *gv, HV *stash, const char *name, STRLEN len,
+\&               int multi)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_init_pv""" 4
+.el .IP \f(CWgv_init_pv\fR 4
+.IX Xref "gv_init_pv"
+.IX Item "gv_init_pv"
+Same as \f(CWgv_init_pvn()\fR, but takes a nul-terminated string for the name
+instead of separate char * and length parameters.
+.RS 4
+.Sp
+.Vb 1
+\& void  gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_init_pvn""" 4
+.el .IP \f(CWgv_init_pvn\fR 4
+.IX Xref "gv_init_pvn"
+.IX Item "gv_init_pvn"
+Converts a scalar into a typeglob.  This is an incoercible typeglob;
+assigning a reference to it will assign to one of its slots, instead of
+overwriting it as happens with typeglobs created by \f(CW\*(C`SvSetSV\*(C'\fR.  Converting
+any scalar that is \f(CWSvOK()\fR may produce unpredictable results and is reserved
+for perl's internal use.
+.Sp
+\&\f(CW\*(C`gv\*(C'\fR is the scalar to be converted.
+.Sp
+\&\f(CW\*(C`stash\*(C'\fR is the parent stash/package, if any.
+.Sp
+\&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`len\*(C'\fR give the name.  The name must be unqualified;
+that is, it must not include the package name.  If \f(CW\*(C`gv\*(C'\fR is a
+stash element, it is the caller's responsibility to ensure that the name
+passed to this function matches the name of the element.  If it does not
+match, perl's internal bookkeeping will get out of sync.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR can be set to \f(CW\*(C`SVf_UTF8\*(C'\fR if \f(CW\*(C`name\*(C'\fR is a UTF\-8 string, or
+the return value of SvUTF8(sv).  It can also take the
+\&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag, which means to pretend that the GV has been
+seen before (i.e., suppress "Used once" warnings).
+.RS 4
+.Sp
+.Vb 2
+\& void  gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
+\&                   U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_init_sv""" 4
+.el .IP \f(CWgv_init_sv\fR 4
+.IX Xref "gv_init_sv"
+.IX Item "gv_init_sv"
+Same as \f(CWgv_init_pvn()\fR, but takes an SV * for the name instead of separate
+char * and length parameters.  \f(CW\*(C`flags\*(C'\fR is currently unused.
+.RS 4
+.Sp
+.Vb 1
+\& void  gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_name_set""" 4
+.el .IP \f(CWgv_name_set\fR 4
+.IX Xref "gv_name_set"
+.IX Item "gv_name_set"
+Set the name for GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`name\*(C'\fR which is \f(CW\*(C`len\*(C'\fR bytes long.  Thus it may
+contain embedded NUL characters.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SVf_UTF8\*(C'\fR, the name is treated as being encoded in
+UTF\-8; otherwise not.
+.RS 4
+.Sp
+.Vb 1
+\& void  gv_name_set(GV *gv, const char *name, U32 len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_stashpv""" 4
+.el .IP \f(CWgv_stashpv\fR 4
+.IX Xref "gv_stashpv"
+.IX Item "gv_stashpv"
+Returns a pointer to the stash for a specified package.  Uses \f(CW\*(C`strlen\*(C'\fR to
+determine the length of \f(CW\*(C`name\*(C'\fR, then calls \f(CWgv_stashpvn()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  gv_stashpv(const char *name, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_stashpvn""" 4
+.el .IP \f(CWgv_stashpvn\fR 4
+.IX Xref "gv_stashpvn"
+.IX Item "gv_stashpvn"
+Returns a pointer to the stash for a specified package.  The \f(CW\*(C`namelen\*(C'\fR
+parameter indicates the length of the \f(CW\*(C`name\*(C'\fR, in bytes.  \f(CW\*(C`flags\*(C'\fR is passed
+to \f(CWgv_fetchpvn_flags()\fR, so if set to \f(CW\*(C`GV_ADD\*(C'\fR then the package will be
+created if it does not already exist.  If the package does not exist and
+\&\f(CW\*(C`flags\*(C'\fR is 0 (or any other setting that does not create packages) then \f(CW\*(C`NULL\*(C'\fR
+is returned.
+.Sp
+Flags may be one of:
+.Sp
+.Vb 7
+\& GV_ADD           Create and initialize the package if doesn\*(Aqt
+\&                  already exist
+\& GV_NOADD_NOINIT  Don\*(Aqt create the package,
+\& GV_ADDMG         GV_ADD iff the GV is magical
+\& GV_NOINIT        GV_ADD, but don\*(Aqt initialize
+\& GV_NOEXPAND      Don\*(Aqt expand SvOK() entries to PVGV
+\& SVf_UTF8         The name is in UTF\-8
+.Ve
+.Sp
+The most important of which are probably \f(CW\*(C`GV_ADD\*(C'\fR and \f(CW\*(C`SVf_UTF8\*(C'\fR.
+.Sp
+Note, use of \f(CW\*(C`gv_stashsv\*(C'\fR instead of \f(CW\*(C`gv_stashpvn\*(C'\fR where possible is strongly
+recommended for performance reasons.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  gv_stashpvn(const char *name, U32 namelen, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_stashpvs""" 4
+.el .IP \f(CWgv_stashpvs\fR 4
+.IX Xref "gv_stashpvs"
+.IX Item "gv_stashpvs"
+Like \f(CW\*(C`gv_stashpvn\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  gv_stashpvs("name", I32 create)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_stashsv""" 4
+.el .IP \f(CWgv_stashsv\fR 4
+.IX Xref "gv_stashsv"
+.IX Item "gv_stashsv"
+Returns a pointer to the stash for a specified package.  See
+\&\f(CW"gv_stashpvn"\fR.
+.Sp
+Note this interface is strongly preferred over \f(CW\*(C`gv_stashpvn\*(C'\fR for performance
+reasons.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  gv_stashsv(SV *sv, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GvSV""" 4
+.el .IP \f(CWGvSV\fR 4
+.IX Xref "GvSV"
+.IX Item "GvSV"
+Return the SV from the GV.
+.Sp
+Prior to Perl v5.9.3, this would add a scalar if none existed.  Nowadays, use
+\&\f(CW"GvSVn"\fR for that, or compile perl with \f(CW\*(C`\-DPERL_CREATE_GVSV\*(C'\fR.  See
+perl5100delta.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  GvSV(GV* gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GvSVn""" 4
+.el .IP \f(CWGvSVn\fR 4
+.IX Xref "GvSVn"
+.IX Item "GvSVn"
+Like \f(CW"GvSV"\fR, but creates an empty scalar if none already exists.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  GvSVn(GV* gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newGVgen""" 4
+.el .IP \f(CWnewGVgen\fR 4
+.IX Item "newGVgen"
+.PD 0
+.ie n .IP """newGVgen_flags""" 4
+.el .IP \f(CWnewGVgen_flags\fR 4
+.IX Xref "newGVgen newGVgen_flags"
+.IX Item "newGVgen_flags"
+.PD
+Create a new, guaranteed to be unique, GV in the package given by the
+NUL-terminated C language string \f(CW\*(C`pack\*(C'\fR, and return a pointer to it.
+.Sp
+For \f(CW\*(C`newGVgen\*(C'\fR or if \f(CW\*(C`flags\*(C'\fR in \f(CW\*(C`newGVgen_flags\*(C'\fR is 0, \f(CW\*(C`pack\*(C'\fR is to be
+considered to be encoded in Latin\-1.  The only other legal \f(CW\*(C`flags\*(C'\fR value is
+\&\f(CW\*(C`SVf_UTF8\*(C'\fR, which indicates \f(CW\*(C`pack\*(C'\fR is to be considered to be encoded in
+UTF\-8.
+.RS 4
+.Sp
+.Vb 2
+\& GV *  newGVgen      (const char *pack)
+\& GV *  newGVgen_flags(const char *pack, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_curstash""" 4
+.el .IP \f(CWPL_curstash\fR 4
+.IX Xref "PL_curstash"
+.IX Item "PL_curstash"
+The stash for the package code will be compiled into.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  PL_curstash
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_defgv""" 4
+.el .IP \f(CWPL_defgv\fR 4
+.IX Xref "PL_defgv"
+.IX Item "PL_defgv"
+The GV representing \f(CW*_\fR.  Useful for access to \f(CW$_\fR.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  PL_defgv
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_defoutgv""" 4
+.el .IP \f(CWPL_defoutgv\fR 4
+.IX Xref "PL_defoutgv"
+.IX Item "PL_defoutgv"
+See \f(CW"setdefout"\fR.
+.ie n .IP """PL_defstash""" 4
+.el .IP \f(CWPL_defstash\fR 4
+.IX Item "PL_defstash"
+Described in perlguts.
+.ie n .IP """save_gp""" 4
+.el .IP \f(CWsave_gp\fR 4
+.IX Xref "save_gp"
+.IX Item "save_gp"
+Saves the current GP of gv on the save stack to be restored on scope exit.
+.Sp
+If \f(CW\*(C`empty\*(C'\fR is true, replace the GP with a new GP.
+.Sp
+If \f(CW\*(C`empty\*(C'\fR is false, mark \f(CW\*(C`gv\*(C'\fR with \f(CW\*(C`GVf_INTRO\*(C'\fR so the next reference
+assigned is localized, which is how \f(CW\*(C`\ local\ *foo\ =\ $someref;\ \*(C'\fR works.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_gp(GV *gv, I32 empty)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """setdefout""" 4
+.el .IP \f(CWsetdefout\fR 4
+.IX Xref "setdefout"
+.IX Item "setdefout"
+Sets \f(CW\*(C`PL_defoutgv\*(C'\fR, the default file handle for output, to the passed in
+typeglob.  As \f(CW\*(C`PL_defoutgv\*(C'\fR "owns" a reference on its typeglob, the reference
+count of the passed in typeglob is increased by one, and the reference count
+of the typeglob that \f(CW\*(C`PL_defoutgv\*(C'\fR points to is decreased by one.
+.RS 4
+.Sp
+.Vb 1
+\& void  setdefout(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Hook manipulation"
+.IX Header "Hook manipulation"
+These functions provide convenient and thread-safe means of manipulating
+hook variables.
+.ie n .IP """rcpv_copy""" 4
+.el .IP \f(CWrcpv_copy\fR 4
+.IX Xref "rcpv_copy"
+.IX Item "rcpv_copy"
+refcount increment a shared memory refcounted string, and when
+the refcount goes to 0 free it using \fBPerlMemShared_free()\fR.
+.Sp
+It is the callers responsibility to ensure that the pv is the
+result of a \fBrcpv_new()\fR call.
+.Sp
+Returns the same pointer that was passed in.
+.Sp
+.Vb 1
+\&    new = rcpv_copy(pv);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& char *  rcpv_copy(char * const pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """rcpv_free""" 4
+.el .IP \f(CWrcpv_free\fR 4
+.IX Xref "rcpv_free"
+.IX Item "rcpv_free"
+refcount decrement a shared memory refcounted string, and when
+the refcount goes to 0 free it using \fBperlmemshared_free()\fR.
+.Sp
+it is the callers responsibility to ensure that the pv is the
+result of a \fBrcpv_new()\fR call.
+.Sp
+Always returns NULL so it can be used like this:
+.Sp
+.Vb 1
+\&    thing = rcpv_free(thing);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& char *  rcpv_free(char * const pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """rcpv_new""" 4
+.el .IP \f(CWrcpv_new\fR 4
+.IX Xref "rcpv_new"
+.IX Item "rcpv_new"
+Create a new shared memory refcounted string with the requested size, and
+with the requested initialization and a refcount of 1. The actual space
+allocated will be 1 byte more than requested and \fBrcpv_new()\fR will ensure that
+the extra byte is a null regardless of any flags settings.
+.Sp
+If the RCPVf_NO_COPY flag is set then the pv argument will be
+ignored, otherwise the contents of the pv pointer will be copied into
+the new buffer or if it is NULL the function will do nothing and return NULL.
+.Sp
+If the RCPVf_USE_STRLEN flag is set then the len argument is ignored and
+recomputed using \f(CWstrlen(pv)\fR. It is an error to combine RCPVf_USE_STRLEN
+and RCPVf_NO_COPY at the same time.
+.Sp
+Under DEBUGGING \fBrcpv_new()\fR will \fBassert()\fR if it is asked to create a 0 length
+shared string unless the RCPVf_ALLOW_EMPTY flag is set.
+.Sp
+The return value from the function is suitable for passing into \fBrcpv_copy()\fR and
+\&\fBrcpv_free()\fR. To access the RCPV * from the returned value use the \fBRCPVx()\fR macro.
+The 'len' member of the RCPV struct stores the allocated length (including the
+extra byte), but the \fBRCPV_LEN()\fR macro returns the requested length (not
+including the extra byte).
+.Sp
+Note that \fBrcpv_new()\fR does NOT use a hash table or anything like that to
+dedupe inputs given the same text content. Each call with a non-null pv
+parameter will produce a distinct pointer with its own refcount regardless of
+the input content.
+.RS 4
+.Sp
+.Vb 1
+\& char *  rcpv_new(const char * const pv, STRLEN len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """wrap_op_checker""" 4
+.el .IP \f(CWwrap_op_checker\fR 4
+.IX Xref "wrap_op_checker"
+.IX Item "wrap_op_checker"
+Puts a C function into the chain of check functions for a specified op
+type.  This is the preferred way to manipulate the "PL_check" array.
+\&\f(CW\*(C`opcode\*(C'\fR specifies which type of op is to be affected.  \f(CW\*(C`new_checker\*(C'\fR
+is a pointer to the C function that is to be added to that opcode's
+check chain, and \f(CW\*(C`old_checker_p\*(C'\fR points to the storage location where a
+pointer to the next function in the chain will be stored.  The value of
+\&\f(CW\*(C`new_checker\*(C'\fR is written into the "PL_check" array, while the value
+previously stored there is written to \f(CW*old_checker_p\fR.
+.Sp
+"PL_check" is global to an entire process, and a module wishing to
+hook op checking may find itself invoked more than once per process,
+typically in different threads.  To handle that situation, this function
+is idempotent.  The location \f(CW*old_checker_p\fR must initially (once
+per process) contain a null pointer.  A C variable of static duration
+(declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
+it internal linkage) will be implicitly initialised appropriately,
+if it does not have an explicit initialiser.  This function will only
+actually modify the check chain if it finds \f(CW*old_checker_p\fR to be null.
+This function is also thread safe on the small scale.  It uses appropriate
+locking to avoid race conditions in accessing "PL_check".
+.Sp
+When this function is called, the function referenced by \f(CW\*(C`new_checker\*(C'\fR
+must be ready to be called, except for \f(CW*old_checker_p\fR being unfilled.
+In a threading situation, \f(CW\*(C`new_checker\*(C'\fR may be called immediately,
+even before this function has returned.  \f(CW*old_checker_p\fR will always
+be appropriately set before \f(CW\*(C`new_checker\*(C'\fR is called.  If \f(CW\*(C`new_checker\*(C'\fR
+decides not to do anything special with an op that it is given (which
+is the usual case for most uses of op check hooking), it must chain the
+check function referenced by \f(CW*old_checker_p\fR.
+.Sp
+Taken all together, XS code to hook an op checker should typically look
+something like this:
+.Sp
+.Vb 9
+\&    static Perl_check_t nxck_frob;
+\&    static OP *myck_frob(pTHX_ OP *op) {
+\&        ...
+\&        op = nxck_frob(aTHX_ op);
+\&        ...
+\&        return op;
+\&    }
+\&    BOOT:
+\&        wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
+.Ve
+.Sp
+If you want to influence compilation of calls to a specific subroutine,
+then use "cv_set_call_checker_flags" rather than hooking checking of
+all \f(CW\*(C`entersub\*(C'\fR ops.
+.RS 4
+.Sp
+.Vb 2
+\& void  wrap_op_checker(Optype opcode, Perl_check_t new_checker,
+\&                       Perl_check_t *old_checker_p)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "HV Handling"
+.IX Xref "HV_ITERNEXT_WANTPLACEHOLDERS HV_NAME_SETALL HvNAMELEN_get"
+.IX Header "HV Handling"
+A HV structure represents a Perl hash.  It consists mainly of an array
+of pointers, each of which points to a linked list of HE structures.  The
+array is indexed by the hash function of the key, so each linked list
+represents all the hash entries with the same hash value.  Each HE contains
+a pointer to the actual value, plus a pointer to a HEK structure which
+holds the key and hash value.
+.ie n .IP """get_hv""" 4
+.el .IP \f(CWget_hv\fR 4
+.IX Xref "get_hv"
+.IX Item "get_hv"
+Returns the HV of the specified Perl hash.  \f(CW\*(C`flags\*(C'\fR are passed to
+\&\f(CW\*(C`gv_fetchpv\*(C'\fR.  If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
+Perl variable does not exist then it will be created.  If \f(CW\*(C`flags\*(C'\fR is zero
+(ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
+returned.
+.Sp
+NOTE: the \f(CWperl_get_hv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  get_hv(const char *name, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HE""" 4
+.el .IP \f(CWHE\fR 4
+.IX Item "HE"
+Described in perlguts.
+.ie n .IP """HEf_SVKEY""" 4
+.el .IP \f(CWHEf_SVKEY\fR 4
+.IX Xref "HEf_SVKEY"
+.IX Item "HEf_SVKEY"
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer
+is to be expected.  (For information only\-\-not to be used).
+.ie n .IP """HeHASH""" 4
+.el .IP \f(CWHeHASH\fR 4
+.IX Xref "HeHASH"
+.IX Item "HeHASH"
+Returns the computed hash stored in the hash entry.
+.RS 4
+.Sp
+.Vb 1
+\& U32  HeHASH(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeKEY""" 4
+.el .IP \f(CWHeKEY\fR 4
+.IX Xref "HeKEY"
+.IX Item "HeKEY"
+Returns the actual pointer stored in the key slot of the hash entry.  The
+pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of
+\&\f(CWHeKLEN()\fR.  Can be assigned to.  The \f(CWHePV()\fR or \f(CWHeSVKEY()\fR macros are
+usually preferable for finding the value of a key.
+.RS 4
+.Sp
+.Vb 1
+\& void*  HeKEY(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeKLEN""" 4
+.el .IP \f(CWHeKLEN\fR 4
+.IX Xref "HeKLEN"
+.IX Item "HeKLEN"
+If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry
+holds an \f(CW\*(C`SV*\*(C'\fR key.  Otherwise, holds the actual length of the key.  Can
+be assigned to.  The \f(CWHePV()\fR macro is usually preferable for finding key
+lengths.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  HeKLEN(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HePV""" 4
+.el .IP \f(CWHePV\fR 4
+.IX Xref "HePV"
+.IX Item "HePV"
+Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any
+necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys.  The length of the string
+is placed in \f(CW\*(C`len\*(C'\fR (this is a macro, so do \fInot\fR use \f(CW&len\fR).  If you do
+not care about what the length of the key is, you may use the global
+variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local
+variable.  Remember though, that hash keys in perl are free to contain
+embedded nulls, so using \f(CWstrlen()\fR or similar is not a good way to find
+the length of hash keys.  This is very similar to the \f(CWSvPV()\fR macro
+described elsewhere in this document.  See also \f(CW"HeUTF8"\fR.
+.Sp
+If you are using \f(CW\*(C`HePV\*(C'\fR to get values to pass to \f(CWnewSVpvn()\fR to create a
+new SV, you should consider using \f(CW\*(C`newSVhek(HeKEY_hek(he))\*(C'\fR as it is more
+efficient.
+.RS 4
+.Sp
+.Vb 1
+\& char*  HePV(HE* he, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeSVKEY""" 4
+.el .IP \f(CWHeSVKEY\fR 4
+.IX Xref "HeSVKEY"
+.IX Item "HeSVKEY"
+Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if the hash entry does not
+contain an \f(CW\*(C`SV*\*(C'\fR key.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  HeSVKEY(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeSVKEY_force""" 4
+.el .IP \f(CWHeSVKEY_force\fR 4
+.IX Xref "HeSVKEY_force"
+.IX Item "HeSVKEY_force"
+Returns the key as an \f(CW\*(C`SV*\*(C'\fR.  Will create and return a temporary mortal
+\&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  HeSVKEY_force(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeSVKEY_set""" 4
+.el .IP \f(CWHeSVKEY_set\fR 4
+.IX Xref "HeSVKEY_set"
+.IX Item "HeSVKEY_set"
+Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to
+indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same
+\&\f(CW\*(C`SV*\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  HeSVKEY_set(HE* he, SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeUTF8""" 4
+.el .IP \f(CWHeUTF8\fR 4
+.IX Xref "HeUTF8"
+.IX Item "HeUTF8"
+Returns whether the \f(CW\*(C`char *\*(C'\fR value returned by \f(CW\*(C`HePV\*(C'\fR is encoded in UTF\-8,
+doing any necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys.  The value returned
+will be 0 or non\-0, not necessarily 1 (or even a value with any low bits set),
+so \fBdo not\fR blindly assign this to a \f(CW\*(C`bool\*(C'\fR variable, as \f(CW\*(C`bool\*(C'\fR may be a
+typedef for \f(CW\*(C`char\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  HeUTF8(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HeVAL""" 4
+.el .IP \f(CWHeVAL\fR 4
+.IX Xref "HeVAL"
+.IX Item "HeVAL"
+Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR)
+stored in the hash entry.  Can be assigned
+to.
+.Sp
+.Vb 2
+\&  SV *foo= HeVAL(hv);
+\&  HeVAL(hv)= sv;
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& SV*  HeVAL(HE* he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HV""" 4
+.el .IP \f(CWHV\fR 4
+.IX Item "HV"
+Described in perlguts.
+.ie n .IP """hv_assert""" 4
+.el .IP \f(CWhv_assert\fR 4
+.IX Xref "hv_assert"
+.IX Item "hv_assert"
+Check that a hash is in an internally consistent state.
+.Sp
+NOTE: \f(CW\*(C`hv_assert\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_assert\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_hv_assert(pTHX_ HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_bucket_ratio""" 4
+.el .IP \f(CWhv_bucket_ratio\fR 4
+.IX Xref "hv_bucket_ratio"
+.IX Item "hv_bucket_ratio"
+NOTE: \f(CW\*(C`hv_bucket_ratio\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+If the hash is tied dispatches through to the SCALAR tied method,
+otherwise if the hash contains no keys returns 0, otherwise returns
+a mortal sv containing a string specifying the number of used buckets,
+followed by a slash, followed by the number of available buckets.
+.Sp
+This function is expensive, it must scan all of the buckets
+to determine which are used, and the count is NOT cached.
+In a large hash this could be a lot of buckets.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_bucket_ratio(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_clear""" 4
+.el .IP \f(CWhv_clear\fR 4
+.IX Xref "hv_clear"
+.IX Item "hv_clear"
+Frees all the elements of a hash, leaving it empty.
+The XS equivalent of \f(CW\*(C`%hash = ()\*(C'\fR.  See also "hv_undef".
+.Sp
+See "av_clear" for a note about the hash possibly being invalid on
+return.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_clear(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_clear_placeholders""" 4
+.el .IP \f(CWhv_clear_placeholders\fR 4
+.IX Xref "hv_clear_placeholders"
+.IX Item "hv_clear_placeholders"
+Clears any placeholders from a hash.  If a restricted hash has any of its keys
+marked as readonly and the key is subsequently deleted, the key is not actually
+deleted but is marked by assigning it a value of \f(CW&PL_sv_placeholder\fR.  This tags
+it so it will be ignored by future operations such as iterating over the hash,
+but will still allow the hash to have a value reassigned to the key at some
+future point.  This function clears any such placeholder keys from the hash.
+See \f(CWHash::Util::lock_keys()\fR for an example of its
+use.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_clear_placeholders(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_copy_hints_hv""" 4
+.el .IP \f(CWhv_copy_hints_hv\fR 4
+.IX Xref "hv_copy_hints_hv"
+.IX Item "hv_copy_hints_hv"
+A specialised version of "newHVhv" for copying \f(CW\*(C`%^H\*(C'\fR.  \f(CW\*(C`ohv\*(C'\fR must be
+a pointer to a hash (which may have \f(CW\*(C`%^H\*(C'\fR magic, but should be generally
+non-magical), or \f(CW\*(C`NULL\*(C'\fR (interpreted as an empty hash).  The content
+of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash, which has the \f(CW\*(C`%^H\*(C'\fR\-specific magic
+added to it.  A pointer to the new hash is returned.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  hv_copy_hints_hv(HV * const ohv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_delete""" 4
+.el .IP \f(CWhv_delete\fR 4
+.IX Xref "hv_delete"
+.IX Item "hv_delete"
+Deletes a key/value pair in the hash.  The value's SV is removed from
+the hash, made mortal, and returned to the caller.  The absolute
+value of \f(CW\*(C`klen\*(C'\fR is the length of the key.  If \f(CW\*(C`klen\*(C'\fR is negative the
+key is assumed to be in UTF\-8\-encoded Unicode.  The \f(CW\*(C`flags\*(C'\fR value
+will normally be zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then \f(CW\*(C`NULL\*(C'\fR will be returned.
+\&\f(CW\*(C`NULL\*(C'\fR will also be returned if the key is not found.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_delete_ent""" 4
+.el .IP \f(CWhv_delete_ent\fR 4
+.IX Xref "hv_delete_ent"
+.IX Item "hv_delete_ent"
+Deletes a key/value pair in the hash.  The value SV is removed from the hash,
+made mortal, and returned to the caller.  The \f(CW\*(C`flags\*(C'\fR value will normally be
+zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then \f(CW\*(C`NULL\*(C'\fR will be returned.  \f(CW\*(C`NULL\*(C'\fR will also
+be returned if the key is not found.  \f(CW\*(C`hash\*(C'\fR can be a valid precomputed hash
+value, or 0 to ask for it to be computed.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvENAME""" 4
+.el .IP \f(CWHvENAME\fR 4
+.IX Xref "HvENAME"
+.IX Item "HvENAME"
+Returns the effective name of a stash, or NULL if there is none.  The
+effective name represents a location in the symbol table where this stash
+resides.  It is updated automatically when packages are aliased or deleted.
+A stash that is no longer in the symbol table has no effective name.  This
+name is preferable to \f(CW\*(C`HvNAME\*(C'\fR for use in MRO linearisations and isa
+caches.
+.RS 4
+.Sp
+.Vb 1
+\& char*  HvENAME(HV* stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvENAMELEN""" 4
+.el .IP \f(CWHvENAMELEN\fR 4
+.IX Xref "HvENAMELEN"
+.IX Item "HvENAMELEN"
+Returns the length of the stash's effective name.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  HvENAMELEN(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvENAMEUTF8""" 4
+.el .IP \f(CWHvENAMEUTF8\fR 4
+.IX Xref "HvENAMEUTF8"
+.IX Item "HvENAMEUTF8"
+Returns true if the effective name is in UTF\-8 encoding.
+.RS 4
+.Sp
+.Vb 1
+\& unsigned char  HvENAMEUTF8(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_exists""" 4
+.el .IP \f(CWhv_exists\fR 4
+.IX Xref "hv_exists"
+.IX Item "hv_exists"
+Returns a boolean indicating whether the specified hash key exists.  The
+absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key.  If \f(CW\*(C`klen\*(C'\fR is
+negative the key is assumed to be in UTF\-8\-encoded Unicode.
+.RS 4
+.Sp
+.Vb 1
+\& bool  hv_exists(HV *hv, const char *key, I32 klen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_exists_ent""" 4
+.el .IP \f(CWhv_exists_ent\fR 4
+.IX Xref "hv_exists_ent"
+.IX Item "hv_exists_ent"
+Returns a boolean indicating whether
+the specified hash key exists.  \f(CW\*(C`hash\*(C'\fR
+can be a valid precomputed hash value, or 0 to ask for it to be
+computed.
+.RS 4
+.Sp
+.Vb 1
+\& bool  hv_exists_ent(HV *hv, SV *keysv, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_fetch""" 4
+.el .IP \f(CWhv_fetch\fR 4
+.IX Xref "hv_fetch"
+.IX Item "hv_fetch"
+Returns the SV which corresponds to the specified key in the hash.
+The absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key.  If \f(CW\*(C`klen\*(C'\fR is
+negative the key is assumed to be in UTF\-8\-encoded Unicode.  If
+\&\f(CW\*(C`lval\*(C'\fR is set then the fetch will be part of a store.  This means that if
+there is no value in the hash associated with the given key, then one is
+created and a pointer to it is returned.  The \f(CW\*(C`SV*\*(C'\fR it points to can be
+assigned to.  But always check that the
+return value is non-null before dereferencing it to an \f(CW\*(C`SV*\*(C'\fR.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
+information on how to use this function on tied hashes.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_fetch_ent""" 4
+.el .IP \f(CWhv_fetch_ent\fR 4
+.IX Xref "hv_fetch_ent"
+.IX Item "hv_fetch_ent"
+Returns the hash entry which corresponds to the specified key in the hash.
+\&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0
+if you want the function to compute it.  IF \f(CW\*(C`lval\*(C'\fR is set then the fetch
+will be part of a store.  Make sure the return value is non-null before
+accessing it.  The return value when \f(CW\*(C`hv\*(C'\fR is a tied hash is a pointer to a
+static location, so be sure to make a copy of the structure if you need to
+store it somewhere.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
+information on how to use this function on tied hashes.
+.RS 4
+.Sp
+.Vb 1
+\& HE *  hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_fetchs""" 4
+.el .IP \f(CWhv_fetchs\fR 4
+.IX Xref "hv_fetchs"
+.IX Item "hv_fetchs"
+Like \f(CW\*(C`hv_fetch\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& SV**  hv_fetchs(HV* tb, "key", I32 lval)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvFILL""" 4
+.el .IP \f(CWHvFILL\fR 4
+.IX Xref "HvFILL"
+.IX Item "HvFILL"
+Returns the number of hash buckets that happen to be in use.
+.Sp
+As of perl 5.25 this function is used only for debugging
+purposes, and the number of used hash buckets is not
+in any way cached, thus this function can be costly
+to execute as it must iterate over all the buckets in the
+hash.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  HvFILL(HV *const hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvHasAUX""" 4
+.el .IP \f(CWHvHasAUX\fR 4
+.IX Xref "HvHasAUX"
+.IX Item "HvHasAUX"
+Returns true if the HV has a \f(CW\*(C`struct xpvhv_aux\*(C'\fR extension. Use this to check
+whether it is valid to call \f(CWHvAUX()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  HvHasAUX(HV *const hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iterinit""" 4
+.el .IP \f(CWhv_iterinit\fR 4
+.IX Xref "hv_iterinit"
+.IX Item "hv_iterinit"
+Prepares a starting point to traverse a hash table.  Returns the number of
+keys in the hash, including placeholders (i.e. the same as \f(CWHvTOTALKEYS(hv)\fR).
+The return value is currently only meaningful for hashes without tie magic.
+.Sp
+NOTE: Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of
+hash buckets that happen to be in use.  If you still need that esoteric
+value, you can get it through the macro \f(CWHvFILL(hv)\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  hv_iterinit(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iterkey""" 4
+.el .IP \f(CWhv_iterkey\fR 4
+.IX Xref "hv_iterkey"
+.IX Item "hv_iterkey"
+Returns the key from the current position of the hash iterator.  See
+\&\f(CW"hv_iterinit"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char *  hv_iterkey(HE *entry, I32 *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iterkeysv""" 4
+.el .IP \f(CWhv_iterkeysv\fR 4
+.IX Xref "hv_iterkeysv"
+.IX Item "hv_iterkeysv"
+Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash
+iterator.  The return value will always be a mortal copy of the key.  Also
+see \f(CW"hv_iterinit"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_iterkeysv(HE *entry)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iternext""" 4
+.el .IP \f(CWhv_iternext\fR 4
+.IX Xref "hv_iternext"
+.IX Item "hv_iternext"
+Returns entries from a hash iterator.  See \f(CW"hv_iterinit"\fR.
+.Sp
+You may call \f(CW\*(C`hv_delete\*(C'\fR or \f(CW\*(C`hv_delete_ent\*(C'\fR on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator.  Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it.  Your iterator is flagged
+to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard
+your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to
+trigger the resource deallocation.
+.RS 4
+.Sp
+.Vb 1
+\& HE *  hv_iternext(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iternext_flags""" 4
+.el .IP \f(CWhv_iternext_flags\fR 4
+.IX Xref "hv_iternext_flags"
+.IX Item "hv_iternext_flags"
+NOTE: \f(CW\*(C`hv_iternext_flags\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Returns entries from a hash iterator.  See \f(CW"hv_iterinit"\fR and
+\&\f(CW"hv_iternext"\fR.
+The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \f(CW\*(C`HV_ITERNEXT_WANTPLACEHOLDERS\*(C'\fR is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys.  By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is
+\&\f(CW&PL_sv_placeholder\fR.  Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+.RS 4
+.Sp
+.Vb 1
+\& HE *  hv_iternext_flags(HV *hv, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iternextsv""" 4
+.el .IP \f(CWhv_iternextsv\fR 4
+.IX Xref "hv_iternextsv"
+.IX Item "hv_iternextsv"
+Performs an \f(CW\*(C`hv_iternext\*(C'\fR, \f(CW\*(C`hv_iterkey\*(C'\fR, and \f(CW\*(C`hv_iterval\*(C'\fR in one
+operation.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_iternextsv(HV *hv, char **key, I32 *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_iterval""" 4
+.el .IP \f(CWhv_iterval\fR 4
+.IX Xref "hv_iterval"
+.IX Item "hv_iterval"
+Returns the value from the current position of the hash iterator.  See
+\&\f(CW"hv_iterkey"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_iterval(HV *hv, HE *entry)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_ksplit""" 4
+.el .IP \f(CWhv_ksplit\fR 4
+.IX Xref "hv_ksplit"
+.IX Item "hv_ksplit"
+Attempt to grow the hash \f(CW\*(C`hv\*(C'\fR so it has at least \f(CW\*(C`newmax\*(C'\fR buckets available.
+Perl chooses the actual number for its convenience.
+.Sp
+This is the same as doing the following in Perl code:
+.Sp
+.Vb 1
+\& keys %hv = newmax;
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_ksplit(HV *hv, IV newmax)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_magic""" 4
+.el .IP \f(CWhv_magic\fR 4
+.IX Xref "hv_magic"
+.IX Item "hv_magic"
+Adds magic to a hash.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_magic(HV *hv, GV *gv, int how)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvNAME""" 4
+.el .IP \f(CWHvNAME\fR 4
+.IX Xref "HvNAME"
+.IX Item "HvNAME"
+Returns the package name of a stash, or \f(CW\*(C`NULL\*(C'\fR if \f(CW\*(C`stash\*(C'\fR isn't a stash.
+See \f(CW"SvSTASH"\fR, \f(CW"CvSTASH"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char*  HvNAME(HV* stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvNAMELEN""" 4
+.el .IP \f(CWHvNAMELEN\fR 4
+.IX Xref "HvNAMELEN"
+.IX Item "HvNAMELEN"
+Returns the length of the stash's name.
+.Sp
+Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  HvNAMELEN(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_name_set""" 4
+.el .IP \f(CWhv_name_set\fR 4
+.IX Item "hv_name_set"
+.PD 0
+.ie n .IP """hv_name_sets""" 4
+.el .IP \f(CWhv_name_sets\fR 4
+.IX Xref "hv_name_set hv_name_sets"
+.IX Item "hv_name_sets"
+.PD
+These each set the name of stash \f(CW\*(C`hv\*(C'\fR to the specified name.
+.Sp
+They differ only in how the name is specified.
+.Sp
+In \f(CW\*(C`hv_name_sets\*(C'\fR, the name is a literal C string, enclosed in double quotes.
+.Sp
+In \f(CW\*(C`hv_name_set\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
+additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes.  Hence, the name
+may contain embedded-NUL characters.
+.Sp
+If \f(CW\*(C`SVf_UTF8\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, the name is treated as being in UTF\-8;
+otherwise not.
+.Sp
+If \f(CW\*(C`HV_NAME_SETALL\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, both the name and the effective name
+are set.
+.RS 4
+.Sp
+.Vb 2
+\& void  hv_name_set (HV *hv, const char *name, U32 len, U32 flags)
+\& void  hv_name_sets(HV *hv, "name", U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HvNAMEUTF8""" 4
+.el .IP \f(CWHvNAMEUTF8\fR 4
+.IX Xref "HvNAMEUTF8"
+.IX Item "HvNAMEUTF8"
+Returns true if the name is in UTF\-8 encoding.
+.RS 4
+.Sp
+.Vb 1
+\& unsigned char  HvNAMEUTF8(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_scalar""" 4
+.el .IP \f(CWhv_scalar\fR 4
+.IX Xref "hv_scalar"
+.IX Item "hv_scalar"
+Evaluates the hash in scalar context and returns the result.
+.Sp
+When the hash is tied dispatches through to the SCALAR method,
+otherwise returns a mortal SV containing the number of keys
+in the hash.
+.Sp
+Note, prior to 5.25 this function returned what is now
+returned by the \fBhv_bucket_ratio()\fR function.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  hv_scalar(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_store""" 4
+.el .IP \f(CWhv_store\fR 4
+.IX Item "hv_store"
+.PD 0
+.ie n .IP """hv_stores""" 4
+.el .IP \f(CWhv_stores\fR 4
+.IX Xref "hv_store hv_stores"
+.IX Item "hv_stores"
+.PD
+These each store SV \f(CW\*(C`val\*(C'\fR with the specified key in hash \f(CW\*(C`hv\*(C'\fR, returning NULL
+if the operation failed or if the value did not need to be actually stored
+within the hash (as in the case of tied hashes).  Otherwise it can be
+dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR.
+.Sp
+They differ only in how the hash key is specified.
+.Sp
+In \f(CW\*(C`hv_stores\*(C'\fR, the key is a C language string literal, enclosed in double
+quotes.  It is never treated as being in UTF\-8.
+.Sp
+In \f(CW\*(C`hv_store\*(C'\fR, \f(CW\*(C`key\*(C'\fR is either NULL or points to the first byte of the string
+specifying the key, and its length in bytes is given by the absolute value of
+an additional parameter, \f(CW\*(C`klen\*(C'\fR.  A NULL key indicates the key is to be
+treated as \f(CW\*(C`undef\*(C'\fR, and \f(CW\*(C`klen\*(C'\fR is ignored; otherwise the key string may
+contain embedded-NUL bytes.  If \f(CW\*(C`klen\*(C'\fR is negative, the string is treated as
+being encoded in UTF\-8; otherwise not.
+.Sp
+\&\f(CW\*(C`hv_store\*(C'\fR has another extra parameter, \f(CW\*(C`hash\*(C'\fR, a precomputed hash of the key
+string, or zero if it has not been precomputed.  This parameter is omitted from
+\&\f(CW\*(C`hv_stores\*(C'\fR, as it is computed automatically at compile time.
+.Sp
+If <hv> is NULL, NULL is returned and no action is taken.
+.Sp
+If \f(CW\*(C`val\*(C'\fR is NULL, it is treated as being \f(CW\*(C`undef\*(C'\fR; otherwise the caller is
+responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before
+the call, and decrementing it if the function returned \f(CW\*(C`NULL\*(C'\fR.  Effectively
+a successful \f(CW\*(C`hv_store\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR.  This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up.
+.Sp
+\&\f(CW\*(C`hv_store\*(C'\fR is not implemented as a call to "\f(CW\*(C`hv_store_ent\*(C'\fR", and does not
+create a temporary SV for the key, so if your key data is not already in SV
+form then use \f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
+information on how to use this function on tied hashes.
+.RS 4
+.Sp
+.Vb 3
+\& SV **  hv_store (HV *hv, const char *key, I32 klen, SV *val,
+\&                  U32 hash)
+\& SV **  hv_stores(HV *hv, "key", SV *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_store_ent""" 4
+.el .IP \f(CWhv_store_ent\fR 4
+.IX Xref "hv_store_ent"
+.IX Item "hv_store_ent"
+Stores \f(CW\*(C`val\*(C'\fR in a hash.  The hash key is specified as \f(CW\*(C`key\*(C'\fR.  The \f(CW\*(C`hash\*(C'\fR
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it.  The return value is the new hash entry so created.  It will be
+\&\f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes).  Otherwise the
+contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros
+described here.  Note that the caller is responsible for suitably
+incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and
+decrementing it if the function returned NULL.  Effectively a successful
+\&\f(CW\*(C`hv_store_ent\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR.  This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up.  Note that \f(CW\*(C`hv_store_ent\*(C'\fR only reads the \f(CW\*(C`key\*(C'\fR;
+unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct
+reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller's responsibility.  The reason
+it does not take ownership, is that \f(CW\*(C`key\*(C'\fR is not used after this function
+returns, and so can be freed immediately.  \f(CW\*(C`hv_store\*(C'\fR
+is not implemented as a call to \f(CW\*(C`hv_store_ent\*(C'\fR, and does not create a temporary
+SV for the key, so if your key data is not already in SV form then use
+\&\f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
+.Sp
+See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
+information on how to use this function on tied hashes.
+.RS 4
+.Sp
+.Vb 1
+\& HE *  hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_undef""" 4
+.el .IP \f(CWhv_undef\fR 4
+.IX Xref "hv_undef"
+.IX Item "hv_undef"
+Undefines the hash.  The XS equivalent of \f(CWundef(%hash)\fR.
+.Sp
+As well as freeing all the elements of the hash (like \f(CWhv_clear()\fR), this
+also frees any auxiliary data and storage associated with the hash.
+.Sp
+See "av_clear" for a note about the hash possibly being invalid on
+return.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_undef(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newHV""" 4
+.el .IP \f(CWnewHV\fR 4
+.IX Xref "newHV"
+.IX Item "newHV"
+Creates a new HV.  The reference count is set to 1.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  newHV()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newHVhv""" 4
+.el .IP \f(CWnewHVhv\fR 4
+.IX Xref "newHVhv"
+.IX Item "newHVhv"
+The content of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash.  A pointer to the new hash is
+returned.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  newHVhv(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Nullhv""" 4
+.el .IP \f(CWNullhv\fR 4
+.IX Xref "Nullhv"
+.IX Item "Nullhv"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`Nullhv\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Null HV pointer.
+.Sp
+(deprecated \- use \f(CW\*(C`(HV *)NULL\*(C'\fR instead)
+.ie n .IP """PERL_HASH""" 4
+.el .IP \f(CWPERL_HASH\fR 4
+.IX Item "PERL_HASH"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  PERL_HASH(U32 hash, char *key, STRLEN klen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_modglobal""" 4
+.el .IP \f(CWPL_modglobal\fR 4
+.IX Xref "PL_modglobal"
+.IX Item "PL_modglobal"
+\&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other.  It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  PL_modglobal
+.Ve
+.RE
+.RS 4
+.RE
+.SH Input/Output
+.IX Header "Input/Output"
+.ie n .IP """do_close""" 4
+.el .IP \f(CWdo_close\fR 4
+.IX Xref "do_close"
+.IX Item "do_close"
+Close an I/O stream.  This implements Perl "\f(CW\*(C`close\*(C'\fR" in perlfunc.
+.Sp
+\&\f(CW\*(C`gv\*(C'\fR is the glob associated with the stream.
+.Sp
+\&\f(CW\*(C`is_explict\*(C'\fR is \f(CW\*(C`true\*(C'\fR if this is an explicit close of the stream; \f(CW\*(C`false\*(C'\fR
+if it is part of another operation, such as closing a pipe (which involves
+implicitly closing both ends).
+.Sp
+Returns \f(CW\*(C`true\*(C'\fR if successful; otherwise returns \f(CW\*(C`false\*(C'\fR and sets \f(CW\*(C`errno\*(C'\fR to
+indicate the cause.
+.RS 4
+.Sp
+.Vb 1
+\& bool  do_close(GV *gv, bool is_explicit)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoDIRP""" 4
+.el .IP \f(CWIoDIRP\fR 4
+.IX Item "IoDIRP"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& DIR *  IoDIRP(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IOf_FLUSH""" 4
+.el .IP \f(CWIOf_FLUSH\fR 4
+.IX Item "IOf_FLUSH"
+Described in perlguts.
+.ie n .IP """IoFLAGS""" 4
+.el .IP \f(CWIoFLAGS\fR 4
+.IX Item "IoFLAGS"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& U8  IoFLAGS(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IOf_UNTAINT""" 4
+.el .IP \f(CWIOf_UNTAINT\fR 4
+.IX Item "IOf_UNTAINT"
+Described in perlguts.
+.ie n .IP """IoIFP""" 4
+.el .IP \f(CWIoIFP\fR 4
+.IX Item "IoIFP"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& PerlIO *  IoIFP(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoOFP""" 4
+.el .IP \f(CWIoOFP\fR 4
+.IX Item "IoOFP"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& PerlIO *  IoOFP(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoTYPE""" 4
+.el .IP \f(CWIoTYPE\fR 4
+.IX Item "IoTYPE"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& char  IoTYPE(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_chsize""" 4
+.el .IP \f(CWmy_chsize\fR 4
+.IX Xref "my_chsize"
+.IX Item "my_chsize"
+The C library \fBchsize\fR\|(3) if available, or a Perl implementation of it.
+.RS 4
+.Sp
+.Vb 1
+\& I32  my_chsize(int fd, Off_t length)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_dirfd""" 4
+.el .IP \f(CWmy_dirfd\fR 4
+.IX Xref "my_dirfd"
+.IX Item "my_dirfd"
+The C library \f(CWdirfd(3)\fR if available, or a Perl implementation of it, or die
+if not easily emulatable.
+.RS 4
+.Sp
+.Vb 1
+\& int  my_dirfd(DIR *dir)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_pclose""" 4
+.el .IP \f(CWmy_pclose\fR 4
+.IX Xref "my_pclose"
+.IX Item "my_pclose"
+A wrapper for the C library \fBpclose\fR\|(3).  Don't use the latter, as the Perl
+version knows things that interact with the rest of the perl interpreter.
+.RS 4
+.Sp
+.Vb 1
+\& I32  my_pclose(PerlIO *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_popen""" 4
+.el .IP \f(CWmy_popen\fR 4
+.IX Xref "my_popen"
+.IX Item "my_popen"
+A wrapper for the C library \fBpopen\fR\|(3).  Don't use the latter, as the Perl
+version knows things that interact with the rest of the perl interpreter.
+.RS 4
+.Sp
+.Vb 1
+\& PerlIO *  my_popen(const char *cmd, const char *mode)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newIO""" 4
+.el .IP \f(CWnewIO\fR 4
+.IX Xref "newIO"
+.IX Item "newIO"
+Create a new IO, setting the reference count to 1.
+.RS 4
+.Sp
+.Vb 1
+\& IO *  newIO()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_FLUSHALL_FOR_CHILD""" 4
+.el .IP \f(CWPERL_FLUSHALL_FOR_CHILD\fR 4
+.IX Xref "PERL_FLUSHALL_FOR_CHILD"
+.IX Item "PERL_FLUSHALL_FOR_CHILD"
+This defines a way to flush all output buffers.  This may be a
+performance issue, so we allow people to disable it.  Also, if
+we are using stdio, there are broken implementations of fflush(NULL)
+out there, Solaris being the most prominent.
+.RS 4
+.Sp
+.Vb 1
+\& void  PERL_FLUSHALL_FOR_CHILD
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PerlIO_apply_layers""" 4
+.el .IP \f(CWPerlIO_apply_layers\fR 4
+.IX Item "PerlIO_apply_layers"
+.PD 0
+.ie n .IP """PerlIO_binmode""" 4
+.el .IP \f(CWPerlIO_binmode\fR 4
+.IX Item "PerlIO_binmode"
+.ie n .IP """PerlIO_canset_cnt""" 4
+.el .IP \f(CWPerlIO_canset_cnt\fR 4
+.IX Item "PerlIO_canset_cnt"
+.ie n .IP """PerlIO_clearerr""" 4
+.el .IP \f(CWPerlIO_clearerr\fR 4
+.IX Item "PerlIO_clearerr"
+.ie n .IP """PerlIO_close""" 4
+.el .IP \f(CWPerlIO_close\fR 4
+.IX Item "PerlIO_close"
+.ie n .IP """PerlIO_debug""" 4
+.el .IP \f(CWPerlIO_debug\fR 4
+.IX Item "PerlIO_debug"
+.ie n .IP """PerlIO_eof""" 4
+.el .IP \f(CWPerlIO_eof\fR 4
+.IX Item "PerlIO_eof"
+.ie n .IP """PerlIO_error""" 4
+.el .IP \f(CWPerlIO_error\fR 4
+.IX Item "PerlIO_error"
+.ie n .IP """PerlIO_exportFILE""" 4
+.el .IP \f(CWPerlIO_exportFILE\fR 4
+.IX Item "PerlIO_exportFILE"
+.ie n .IP """PerlIO_fast_gets""" 4
+.el .IP \f(CWPerlIO_fast_gets\fR 4
+.IX Item "PerlIO_fast_gets"
+.ie n .IP """PerlIO_fdopen""" 4
+.el .IP \f(CWPerlIO_fdopen\fR 4
+.IX Item "PerlIO_fdopen"
+.ie n .IP """PerlIO_fileno""" 4
+.el .IP \f(CWPerlIO_fileno\fR 4
+.IX Item "PerlIO_fileno"
+.ie n .IP """PerlIO_fill""" 4
+.el .IP \f(CWPerlIO_fill\fR 4
+.IX Item "PerlIO_fill"
+.ie n .IP """PerlIO_findFILE""" 4
+.el .IP \f(CWPerlIO_findFILE\fR 4
+.IX Item "PerlIO_findFILE"
+.ie n .IP """PerlIO_flush""" 4
+.el .IP \f(CWPerlIO_flush\fR 4
+.IX Item "PerlIO_flush"
+.ie n .IP """PerlIO_get_base""" 4
+.el .IP \f(CWPerlIO_get_base\fR 4
+.IX Item "PerlIO_get_base"
+.ie n .IP """PerlIO_get_bufsiz""" 4
+.el .IP \f(CWPerlIO_get_bufsiz\fR 4
+.IX Item "PerlIO_get_bufsiz"
+.ie n .IP """PerlIO_get_cnt""" 4
+.el .IP \f(CWPerlIO_get_cnt\fR 4
+.IX Item "PerlIO_get_cnt"
+.ie n .IP """PerlIO_get_ptr""" 4
+.el .IP \f(CWPerlIO_get_ptr\fR 4
+.IX Item "PerlIO_get_ptr"
+.ie n .IP """PerlIO_getc""" 4
+.el .IP \f(CWPerlIO_getc\fR 4
+.IX Item "PerlIO_getc"
+.ie n .IP """PerlIO_getpos""" 4
+.el .IP \f(CWPerlIO_getpos\fR 4
+.IX Item "PerlIO_getpos"
+.ie n .IP """PerlIO_has_base""" 4
+.el .IP \f(CWPerlIO_has_base\fR 4
+.IX Item "PerlIO_has_base"
+.ie n .IP """PerlIO_has_cntptr""" 4
+.el .IP \f(CWPerlIO_has_cntptr\fR 4
+.IX Item "PerlIO_has_cntptr"
+.ie n .IP """PerlIO_importFILE""" 4
+.el .IP \f(CWPerlIO_importFILE\fR 4
+.IX Item "PerlIO_importFILE"
+.ie n .IP """PerlIO_open""" 4
+.el .IP \f(CWPerlIO_open\fR 4
+.IX Item "PerlIO_open"
+.ie n .IP """PerlIO_printf""" 4
+.el .IP \f(CWPerlIO_printf\fR 4
+.IX Item "PerlIO_printf"
+.ie n .IP """PerlIO_putc""" 4
+.el .IP \f(CWPerlIO_putc\fR 4
+.IX Item "PerlIO_putc"
+.ie n .IP """PerlIO_puts""" 4
+.el .IP \f(CWPerlIO_puts\fR 4
+.IX Item "PerlIO_puts"
+.ie n .IP """PerlIO_read""" 4
+.el .IP \f(CWPerlIO_read\fR 4
+.IX Item "PerlIO_read"
+.ie n .IP """PerlIO_releaseFILE""" 4
+.el .IP \f(CWPerlIO_releaseFILE\fR 4
+.IX Item "PerlIO_releaseFILE"
+.ie n .IP """PerlIO_reopen""" 4
+.el .IP \f(CWPerlIO_reopen\fR 4
+.IX Item "PerlIO_reopen"
+.ie n .IP """PerlIO_rewind""" 4
+.el .IP \f(CWPerlIO_rewind\fR 4
+.IX Item "PerlIO_rewind"
+.ie n .IP """PerlIO_seek""" 4
+.el .IP \f(CWPerlIO_seek\fR 4
+.IX Item "PerlIO_seek"
+.ie n .IP """PerlIO_set_cnt""" 4
+.el .IP \f(CWPerlIO_set_cnt\fR 4
+.IX Item "PerlIO_set_cnt"
+.ie n .IP """PerlIO_set_ptrcnt""" 4
+.el .IP \f(CWPerlIO_set_ptrcnt\fR 4
+.IX Item "PerlIO_set_ptrcnt"
+.ie n .IP """PerlIO_setlinebuf""" 4
+.el .IP \f(CWPerlIO_setlinebuf\fR 4
+.IX Item "PerlIO_setlinebuf"
+.ie n .IP """PerlIO_setpos""" 4
+.el .IP \f(CWPerlIO_setpos\fR 4
+.IX Item "PerlIO_setpos"
+.ie n .IP """PerlIO_stderr""" 4
+.el .IP \f(CWPerlIO_stderr\fR 4
+.IX Item "PerlIO_stderr"
+.ie n .IP """PerlIO_stdin""" 4
+.el .IP \f(CWPerlIO_stdin\fR 4
+.IX Item "PerlIO_stdin"
+.ie n .IP """PerlIO_stdout""" 4
+.el .IP \f(CWPerlIO_stdout\fR 4
+.IX Item "PerlIO_stdout"
+.ie n .IP """PerlIO_stdoutf""" 4
+.el .IP \f(CWPerlIO_stdoutf\fR 4
+.IX Item "PerlIO_stdoutf"
+.ie n .IP """PerlIO_tell""" 4
+.el .IP \f(CWPerlIO_tell\fR 4
+.IX Item "PerlIO_tell"
+.ie n .IP """PerlIO_ungetc""" 4
+.el .IP \f(CWPerlIO_ungetc\fR 4
+.IX Item "PerlIO_ungetc"
+.ie n .IP """PerlIO_unread""" 4
+.el .IP \f(CWPerlIO_unread\fR 4
+.IX Item "PerlIO_unread"
+.ie n .IP """PerlIO_vprintf""" 4
+.el .IP \f(CWPerlIO_vprintf\fR 4
+.IX Item "PerlIO_vprintf"
+.ie n .IP """PerlIO_write""" 4
+.el .IP \f(CWPerlIO_write\fR 4
+.IX Item "PerlIO_write"
+.PD
+Described in perlapio.
+.RS 4
+.Sp
+.Vb 10
+\& int        PerlIO_apply_layers(PerlIO *f, const char *mode,
+\&                                const char *layers)
+\& int        PerlIO_binmode     (PerlIO *f, int ptype, int imode,
+\&                                const char *layers)
+\& int        PerlIO_canset_cnt  (PerlIO *f)
+\& void       PerlIO_clearerr    (PerlIO *f)
+\& int        PerlIO_close       (PerlIO *f)
+\& void       PerlIO_debug       (const char *fmt, ...)
+\& int        PerlIO_eof         (PerlIO *f)
+\& int        PerlIO_error       (PerlIO *f)
+\& FILE *     PerlIO_exportFILE  (PerlIO *f, const char *mode)
+\& int        PerlIO_fast_gets   (PerlIO *f)
+\& PerlIO *   PerlIO_fdopen      (int fd, const char *mode)
+\& int        PerlIO_fileno      (PerlIO *f)
+\& int        PerlIO_fill        (PerlIO *f)
+\& FILE *     PerlIO_findFILE    (PerlIO *f)
+\& int        PerlIO_flush       (PerlIO *f)
+\& STDCHAR *  PerlIO_get_base    (PerlIO *f)
+\& SSize_t    PerlIO_get_bufsiz  (PerlIO *f)
+\& SSize_t    PerlIO_get_cnt     (PerlIO *f)
+\& STDCHAR *  PerlIO_get_ptr     (PerlIO *f)
+\& int        PerlIO_getc        (PerlIO *d)
+\& int        PerlIO_getpos      (PerlIO *f, SV *save)
+\& int        PerlIO_has_base    (PerlIO *f)
+\& int        PerlIO_has_cntptr  (PerlIO *f)
+\& PerlIO *   PerlIO_importFILE  (FILE *stdio, const char *mode)
+\& PerlIO *   PerlIO_open        (const char *path, const char *mode)
+\& int        PerlIO_printf      (PerlIO *f, const char *fmt, ...)
+\& int        PerlIO_putc        (PerlIO *f, int ch)
+\& int        PerlIO_puts        (PerlIO *f, const char *string)
+\& SSize_t    PerlIO_read        (PerlIO *f, void *vbuf,
+\&                                Size_t count)
+\& void       PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
+\& PerlIO *   PerlIO_reopen      (const char *path, const char *mode,
+\&                                PerlIO *old)
+\& void       PerlIO_rewind      (PerlIO *f)
+\& int        PerlIO_seek        (PerlIO *f, Off_t offset,
+\&                                int whence)
+\& void       PerlIO_set_cnt     (PerlIO *f, SSize_t cnt)
+\& void       PerlIO_set_ptrcnt  (PerlIO *f, STDCHAR *ptr,
+\&                                SSize_t cnt)
+\& void       PerlIO_setlinebuf  (PerlIO *f)
+\& int        PerlIO_setpos      (PerlIO *f, SV *saved)
+\& PerlIO *   PerlIO_stderr      (PerlIO *f, const char *mode,
+\&                                const char *layers)
+\& PerlIO *   PerlIO_stdin       (PerlIO *f, const char *mode,
+\&                                const char *layers)
+\& PerlIO *   PerlIO_stdout      (PerlIO *f, const char *mode,
+\&                                const char *layers)
+\& int        PerlIO_stdoutf     (const char *fmt, ...)
+\& Off_t      PerlIO_tell        (PerlIO *f)
+\& int        PerlIO_ungetc      (PerlIO *f, int ch)
+\& SSize_t    PerlIO_unread      (PerlIO *f, const void *vbuf,
+\&                                Size_t count)
+\& int        PerlIO_vprintf     (PerlIO *f, const char *fmt,
+\&                                va_list args)
+\& SSize_t    PerlIO_write       (PerlIO *f, const void *vbuf,
+\&                                Size_t count)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERLIO_F_APPEND""" 4
+.el .IP \f(CWPERLIO_F_APPEND\fR 4
+.IX Item "PERLIO_F_APPEND"
+.PD 0
+.ie n .IP """PERLIO_F_CANREAD""" 4
+.el .IP \f(CWPERLIO_F_CANREAD\fR 4
+.IX Item "PERLIO_F_CANREAD"
+.ie n .IP """PERLIO_F_CANWRITE""" 4
+.el .IP \f(CWPERLIO_F_CANWRITE\fR 4
+.IX Item "PERLIO_F_CANWRITE"
+.ie n .IP """PERLIO_F_CRLF""" 4
+.el .IP \f(CWPERLIO_F_CRLF\fR 4
+.IX Item "PERLIO_F_CRLF"
+.ie n .IP """PERLIO_F_EOF""" 4
+.el .IP \f(CWPERLIO_F_EOF\fR 4
+.IX Item "PERLIO_F_EOF"
+.ie n .IP """PERLIO_F_ERROR""" 4
+.el .IP \f(CWPERLIO_F_ERROR\fR 4
+.IX Item "PERLIO_F_ERROR"
+.ie n .IP """PERLIO_F_FASTGETS""" 4
+.el .IP \f(CWPERLIO_F_FASTGETS\fR 4
+.IX Item "PERLIO_F_FASTGETS"
+.ie n .IP """PERLIO_F_LINEBUF""" 4
+.el .IP \f(CWPERLIO_F_LINEBUF\fR 4
+.IX Item "PERLIO_F_LINEBUF"
+.ie n .IP """PERLIO_F_OPEN""" 4
+.el .IP \f(CWPERLIO_F_OPEN\fR 4
+.IX Item "PERLIO_F_OPEN"
+.ie n .IP """PERLIO_F_RDBUF""" 4
+.el .IP \f(CWPERLIO_F_RDBUF\fR 4
+.IX Item "PERLIO_F_RDBUF"
+.ie n .IP """PERLIO_F_TEMP""" 4
+.el .IP \f(CWPERLIO_F_TEMP\fR 4
+.IX Item "PERLIO_F_TEMP"
+.ie n .IP """PERLIO_F_TRUNCATE""" 4
+.el .IP \f(CWPERLIO_F_TRUNCATE\fR 4
+.IX Item "PERLIO_F_TRUNCATE"
+.ie n .IP """PERLIO_F_UNBUF""" 4
+.el .IP \f(CWPERLIO_F_UNBUF\fR 4
+.IX Item "PERLIO_F_UNBUF"
+.ie n .IP """PERLIO_F_UTF8""" 4
+.el .IP \f(CWPERLIO_F_UTF8\fR 4
+.IX Item "PERLIO_F_UTF8"
+.ie n .IP """PERLIO_F_WRBUF""" 4
+.el .IP \f(CWPERLIO_F_WRBUF\fR 4
+.IX Item "PERLIO_F_WRBUF"
+.PD
+Described in perliol.
+.ie n .IP """PERLIO_FUNCS_CAST""" 4
+.el .IP \f(CWPERLIO_FUNCS_CAST\fR 4
+.IX Xref "PERLIO_FUNCS_CAST"
+.IX Item "PERLIO_FUNCS_CAST"
+Cast the pointer \f(CW\*(C`func\*(C'\fR to be of type \f(CW\*(C`PerlIO_funcs\ *\*(C'\fR.
+.ie n .IP """PERLIO_FUNCS_DECL""" 4
+.el .IP \f(CWPERLIO_FUNCS_DECL\fR 4
+.IX Xref "PERLIO_FUNCS_DECL"
+.IX Item "PERLIO_FUNCS_DECL"
+Declare \f(CW\*(C`ftab\*(C'\fR to be a PerlIO function table, that is, of type
+\&\f(CW\*(C`PerlIO_funcs\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   PERLIO_FUNCS_DECL(PerlIO * ftab)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERLIO_K_BUFFERED""" 4
+.el .IP \f(CWPERLIO_K_BUFFERED\fR 4
+.IX Item "PERLIO_K_BUFFERED"
+.PD 0
+.ie n .IP """PERLIO_K_CANCRLF""" 4
+.el .IP \f(CWPERLIO_K_CANCRLF\fR 4
+.IX Item "PERLIO_K_CANCRLF"
+.ie n .IP """PERLIO_K_FASTGETS""" 4
+.el .IP \f(CWPERLIO_K_FASTGETS\fR 4
+.IX Item "PERLIO_K_FASTGETS"
+.ie n .IP """PERLIO_K_MULTIARG""" 4
+.el .IP \f(CWPERLIO_K_MULTIARG\fR 4
+.IX Item "PERLIO_K_MULTIARG"
+.ie n .IP """PERLIO_K_RAW""" 4
+.el .IP \f(CWPERLIO_K_RAW\fR 4
+.IX Item "PERLIO_K_RAW"
+.PD
+Described in perliol.
+.ie n .IP """PERLIO_NOT_STDIO""" 4
+.el .IP \f(CWPERLIO_NOT_STDIO\fR 4
+.IX Item "PERLIO_NOT_STDIO"
+Described in perlapio.
+.ie n .IP """PL_maxsysfd""" 4
+.el .IP \f(CWPL_maxsysfd\fR 4
+.IX Item "PL_maxsysfd"
+Described in perliol.
+.ie n .IP """repeatcpy""" 4
+.el .IP \f(CWrepeatcpy\fR 4
+.IX Xref "repeatcpy"
+.IX Item "repeatcpy"
+Make \f(CW\*(C`count\*(C'\fR copies of the \f(CW\*(C`len\*(C'\fR bytes beginning at \f(CW\*(C`from\*(C'\fR, placing them
+into memory beginning at \f(CW\*(C`to\*(C'\fR, which must be big enough to accommodate them
+all.
+.RS 4
+.Sp
+.Vb 1
+\& void  repeatcpy(char *to, const char *from, I32 len, IV count)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """USE_STDIO""" 4
+.el .IP \f(CWUSE_STDIO\fR 4
+.IX Item "USE_STDIO"
+Described in perlapio.
+.SH Integer
+.IX Header "Integer"
+.ie n .IP """CASTI32""" 4
+.el .IP \f(CWCASTI32\fR 4
+.IX Xref "CASTI32"
+.IX Item "CASTI32"
+This symbol is defined if the C compiler can cast negative
+or large floating point numbers to 32\-bit ints.
+.ie n .IP """HAS_INT64_T""" 4
+.el .IP \f(CWHAS_INT64_T\fR 4
+.IX Xref "HAS_INT64_T"
+.IX Item "HAS_INT64_T"
+This symbol will defined if the C compiler supports \f(CW\*(C`int64_t\*(C'\fR.
+Usually the \fIinttypes.h\fR needs to be included, but sometimes
+\&\fIsys/types.h\fR is enough.
+.ie n .IP """HAS_LONG_LONG""" 4
+.el .IP \f(CWHAS_LONG_LONG\fR 4
+.IX Xref "HAS_LONG_LONG"
+.IX Item "HAS_LONG_LONG"
+This symbol will be defined if the C compiler supports long long.
+.ie n .IP """HAS_QUAD""" 4
+.el .IP \f(CWHAS_QUAD\fR 4
+.IX Xref "HAS_QUAD"
+.IX Item "HAS_QUAD"
+This symbol, if defined, tells that there's a 64\-bit integer type,
+\&\f(CW\*(C`Quad_t\*(C'\fR, and its unsigned counterpart, \f(CW\*(C`Uquad_t\*(C'\fR. \f(CW\*(C`QUADKIND\*(C'\fR will be one
+of \f(CW\*(C`QUAD_IS_INT\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_INT64_T\*(C'\fR,
+or \f(CW\*(C`QUAD_IS_\|_\|_INT64\*(C'\fR.
+.ie n .IP """I32df""" 4
+.el .IP \f(CWI32df\fR 4
+.IX Xref "I32df"
+.IX Item "I32df"
+This symbol defines the format string used for printing a Perl I32
+as a signed decimal integer.
+.ie n .IP """INT16_C""" 4
+.el .IP \f(CWINT16_C\fR 4
+.IX Item "INT16_C"
+.PD 0
+.ie n .IP """INT32_C""" 4
+.el .IP \f(CWINT32_C\fR 4
+.IX Item "INT32_C"
+.ie n .IP """INT64_C""" 4
+.el .IP \f(CWINT64_C\fR 4
+.IX Xref "INT16_C INT32_C INT64_C"
+.IX Item "INT64_C"
+.PD
+Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
+corresponding integer type on the machine.
+.Sp
+If the machine does not have a 64\-bit type, \f(CW\*(C`INT64_C\*(C'\fR is undefined.
+Use \f(CW"INTMAX_C"\fR to get the largest type available on the platform.
+.RS 4
+.Sp
+.Vb 3
+\& I16  INT16_C(number)
+\& I32  INT32_C(number)
+\& I64  INT64_C(number)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """INTMAX_C""" 4
+.el .IP \f(CWINTMAX_C\fR 4
+.IX Xref "INTMAX_C"
+.IX Item "INTMAX_C"
+Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
+widest integer type on the machine.  For example, if the machine has \f(CW\*(C`long
+long\*(C'\fRs, \f(CWINTMAX_C(\-1)\fR would yield
+.Sp
+.Vb 1
+\& \-1LL
+.Ve
+.Sp
+See also, for example, \f(CW"INT32_C"\fR.
+.Sp
+Use "IV" to declare variables of the maximum usable size on this platform.
+.RS 4
+.Sp
+.Vb 1
+\&   INTMAX_C(number)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """INTSIZE""" 4
+.el .IP \f(CWINTSIZE\fR 4
+.IX Xref "INTSIZE"
+.IX Item "INTSIZE"
+This symbol contains the value of \f(CWsizeof(int)\fR so that the C
+preprocessor can make decisions based on it.
+.ie n .IP """I8SIZE""" 4
+.el .IP \f(CWI8SIZE\fR 4
+.IX Xref "I8SIZE"
+.IX Item "I8SIZE"
+This symbol contains the \f(CWsizeof(I8)\fR.
+.ie n .IP """I16SIZE""" 4
+.el .IP \f(CWI16SIZE\fR 4
+.IX Xref "I16SIZE"
+.IX Item "I16SIZE"
+This symbol contains the \f(CWsizeof(I16)\fR.
+.ie n .IP """I32SIZE""" 4
+.el .IP \f(CWI32SIZE\fR 4
+.IX Xref "I32SIZE"
+.IX Item "I32SIZE"
+This symbol contains the \f(CWsizeof(I32)\fR.
+.ie n .IP """I64SIZE""" 4
+.el .IP \f(CWI64SIZE\fR 4
+.IX Xref "I64SIZE"
+.IX Item "I64SIZE"
+This symbol contains the \f(CWsizeof(I64)\fR.
+.ie n .IP """I8TYPE""" 4
+.el .IP \f(CWI8TYPE\fR 4
+.IX Xref "I8TYPE"
+.IX Item "I8TYPE"
+This symbol defines the C type used for Perl's I8.
+.ie n .IP """I16TYPE""" 4
+.el .IP \f(CWI16TYPE\fR 4
+.IX Xref "I16TYPE"
+.IX Item "I16TYPE"
+This symbol defines the C type used for Perl's I16.
+.ie n .IP """I32TYPE""" 4
+.el .IP \f(CWI32TYPE\fR 4
+.IX Xref "I32TYPE"
+.IX Item "I32TYPE"
+This symbol defines the C type used for Perl's I32.
+.ie n .IP """I64TYPE""" 4
+.el .IP \f(CWI64TYPE\fR 4
+.IX Xref "I64TYPE"
+.IX Item "I64TYPE"
+This symbol defines the C type used for Perl's I64.
+.ie n .IP """IV""" 4
+.el .IP \f(CWIV\fR 4
+.IX Item "IV"
+.PD 0
+.ie n .IP """I8""" 4
+.el .IP \f(CWI8\fR 4
+.IX Item "I8"
+.ie n .IP """I16""" 4
+.el .IP \f(CWI16\fR 4
+.IX Item "I16"
+.ie n .IP """I32""" 4
+.el .IP \f(CWI32\fR 4
+.IX Item "I32"
+.ie n .IP """I64""" 4
+.el .IP \f(CWI64\fR 4
+.IX Item "I64"
+.PD
+Described in perlguts.
+.ie n .IP """IV_MAX""" 4
+.el .IP \f(CWIV_MAX\fR 4
+.IX Xref "IV_MAX"
+.IX Item "IV_MAX"
+The largest signed integer that fits in an IV on this platform.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IV_MAX
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IV_MIN""" 4
+.el .IP \f(CWIV_MIN\fR 4
+.IX Xref "IV_MIN"
+.IX Item "IV_MIN"
+The negative signed integer furthest away from 0 that fits in an IV on this
+platform.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IV_MIN
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IVSIZE""" 4
+.el .IP \f(CWIVSIZE\fR 4
+.IX Xref "IVSIZE"
+.IX Item "IVSIZE"
+This symbol contains the \f(CWsizeof(IV)\fR.
+.ie n .IP """IVTYPE""" 4
+.el .IP \f(CWIVTYPE\fR 4
+.IX Xref "IVTYPE"
+.IX Item "IVTYPE"
+This symbol defines the C type used for Perl's IV.
+.ie n .IP """line_t""" 4
+.el .IP \f(CWline_t\fR 4
+.IX Xref "line_t"
+.IX Item "line_t"
+The typedef to use to declare variables that are to hold line numbers.
+.ie n .IP """LONGLONGSIZE""" 4
+.el .IP \f(CWLONGLONGSIZE\fR 4
+.IX Xref "LONGLONGSIZE"
+.IX Item "LONGLONGSIZE"
+This symbol contains the size of a long long, so that the
+C preprocessor can make decisions based on it.  It is only
+defined if the system supports long long.
+.ie n .IP """LONGSIZE""" 4
+.el .IP \f(CWLONGSIZE\fR 4
+.IX Xref "LONGSIZE"
+.IX Item "LONGSIZE"
+This symbol contains the value of \f(CWsizeof(long)\fR so that the C
+preprocessor can make decisions based on it.
+.ie n .IP """memzero""" 4
+.el .IP \f(CWmemzero\fR 4
+.IX Xref "memzero"
+.IX Item "memzero"
+Set the \f(CW\*(C`l\*(C'\fR bytes starting at \f(CW*d\fR to all zeroes.
+.RS 4
+.Sp
+.Vb 1
+\& void  memzero(void * d, Size_t l)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_INT_FAST8_T""" 4
+.el .IP \f(CWPERL_INT_FAST8_T\fR 4
+.IX Item "PERL_INT_FAST8_T"
+.PD 0
+.ie n .IP """PERL_INT_FAST16_T""" 4
+.el .IP \f(CWPERL_INT_FAST16_T\fR 4
+.IX Item "PERL_INT_FAST16_T"
+.ie n .IP """PERL_UINT_FAST8_T""" 4
+.el .IP \f(CWPERL_UINT_FAST8_T\fR 4
+.IX Item "PERL_UINT_FAST8_T"
+.ie n .IP """PERL_UINT_FAST16_T""" 4
+.el .IP \f(CWPERL_UINT_FAST16_T\fR 4
+.IX Xref "PERL_INT_FAST8_T PERL_INT_FAST16_T PERL_UINT_FAST8_T PERL_UINT_FAST16_T"
+.IX Item "PERL_UINT_FAST16_T"
+.PD
+These are equivalent to the correspondingly-named C99 typedefs on platforms
+that have those; they evaluate to \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`unsigned int\*(C'\fR on platforms that
+don't, so that you can portably take advantage of this C99 feature.
+.ie n .IP """PERL_INT_MAX""" 4
+.el .IP \f(CWPERL_INT_MAX\fR 4
+.IX Item "PERL_INT_MAX"
+.PD 0
+.ie n .IP """PERL_INT_MIN""" 4
+.el .IP \f(CWPERL_INT_MIN\fR 4
+.IX Item "PERL_INT_MIN"
+.ie n .IP """PERL_LONG_MAX""" 4
+.el .IP \f(CWPERL_LONG_MAX\fR 4
+.IX Item "PERL_LONG_MAX"
+.ie n .IP """PERL_LONG_MIN""" 4
+.el .IP \f(CWPERL_LONG_MIN\fR 4
+.IX Item "PERL_LONG_MIN"
+.ie n .IP """PERL_QUAD_MAX""" 4
+.el .IP \f(CWPERL_QUAD_MAX\fR 4
+.IX Item "PERL_QUAD_MAX"
+.ie n .IP """PERL_QUAD_MIN""" 4
+.el .IP \f(CWPERL_QUAD_MIN\fR 4
+.IX Item "PERL_QUAD_MIN"
+.ie n .IP """PERL_SHORT_MAX""" 4
+.el .IP \f(CWPERL_SHORT_MAX\fR 4
+.IX Item "PERL_SHORT_MAX"
+.ie n .IP """PERL_SHORT_MIN""" 4
+.el .IP \f(CWPERL_SHORT_MIN\fR 4
+.IX Item "PERL_SHORT_MIN"
+.ie n .IP """PERL_UCHAR_MAX""" 4
+.el .IP \f(CWPERL_UCHAR_MAX\fR 4
+.IX Item "PERL_UCHAR_MAX"
+.ie n .IP """PERL_UCHAR_MIN""" 4
+.el .IP \f(CWPERL_UCHAR_MIN\fR 4
+.IX Item "PERL_UCHAR_MIN"
+.ie n .IP """PERL_UINT_MAX""" 4
+.el .IP \f(CWPERL_UINT_MAX\fR 4
+.IX Item "PERL_UINT_MAX"
+.ie n .IP """PERL_UINT_MIN""" 4
+.el .IP \f(CWPERL_UINT_MIN\fR 4
+.IX Item "PERL_UINT_MIN"
+.ie n .IP """PERL_ULONG_MAX""" 4
+.el .IP \f(CWPERL_ULONG_MAX\fR 4
+.IX Item "PERL_ULONG_MAX"
+.ie n .IP """PERL_ULONG_MIN""" 4
+.el .IP \f(CWPERL_ULONG_MIN\fR 4
+.IX Item "PERL_ULONG_MIN"
+.ie n .IP """PERL_UQUAD_MAX""" 4
+.el .IP \f(CWPERL_UQUAD_MAX\fR 4
+.IX Item "PERL_UQUAD_MAX"
+.ie n .IP """PERL_UQUAD_MIN""" 4
+.el .IP \f(CWPERL_UQUAD_MIN\fR 4
+.IX Item "PERL_UQUAD_MIN"
+.ie n .IP """PERL_USHORT_MAX""" 4
+.el .IP \f(CWPERL_USHORT_MAX\fR 4
+.IX Item "PERL_USHORT_MAX"
+.ie n .IP """PERL_USHORT_MIN""" 4
+.el .IP \f(CWPERL_USHORT_MIN\fR 4
+.IX Xref "PERL_INT_MAX PERL_INT_MIN PERL_LONG_MAX PERL_LONG_MIN PERL_QUAD_MAX PERL_QUAD_MIN PERL_SHORT_MAX PERL_SHORT_MIN PERL_UCHAR_MAX PERL_UCHAR_MIN PERL_UINT_MAX PERL_UINT_MIN PERL_ULONG_MAX PERL_ULONG_MIN PERL_UQUAD_MAX PERL_UQUAD_MIN PERL_USHORT_MAX PERL_USHORT_MIN"
+.IX Item "PERL_USHORT_MIN"
+.PD
+These give the largest and smallest number representable in the current
+platform in variables of the corresponding types.
+.Sp
+For signed types, the smallest representable number is the most negative
+number, the one furthest away from zero.
+.Sp
+For C99 and later compilers, these correspond to things like \f(CW\*(C`INT_MAX\*(C'\fR, which
+are available to the C code.  But these constants, furnished by Perl,
+allow code compiled on earlier compilers to portably have access to the same
+constants.
+.RS 4
+.Sp
+.Vb 10
+\& int             PERL_INT_MAX
+\& int             PERL_INT_MIN
+\& long            PERL_LONG_MAX
+\& long            PERL_LONG_MIN
+\& IV              PERL_QUAD_MAX
+\& IV              PERL_QUAD_MIN
+\& short           PERL_SHORT_MAX
+\& short           PERL_SHORT_MIN
+\& U8              PERL_UCHAR_MAX
+\& U8              PERL_UCHAR_MIN
+\& unsigned int    PERL_UINT_MAX
+\& unsigned int    PERL_UINT_MIN
+\& unsigned long   PERL_ULONG_MAX
+\& unsigned long   PERL_ULONG_MIN
+\& UV              PERL_UQUAD_MAX
+\& UV              PERL_UQUAD_MIN
+\& unsigned short  PERL_USHORT_MAX
+\& unsigned short  PERL_USHORT_MIN
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SHORTSIZE""" 4
+.el .IP \f(CWSHORTSIZE\fR 4
+.IX Xref "SHORTSIZE"
+.IX Item "SHORTSIZE"
+This symbol contains the value of \f(CWsizeof(short)\fR so that the C
+preprocessor can make decisions based on it.
+.ie n .IP """UINT16_C""" 4
+.el .IP \f(CWUINT16_C\fR 4
+.IX Item "UINT16_C"
+.PD 0
+.ie n .IP """UINT32_C""" 4
+.el .IP \f(CWUINT32_C\fR 4
+.IX Item "UINT32_C"
+.ie n .IP """UINT64_C""" 4
+.el .IP \f(CWUINT64_C\fR 4
+.IX Xref "UINT16_C UINT32_C UINT64_C"
+.IX Item "UINT64_C"
+.PD
+Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
+corresponding unsigned integer type on the machine.
+.Sp
+If the machine does not have a 64\-bit type, \f(CW\*(C`UINT64_C\*(C'\fR is undefined.
+Use \f(CW"UINTMAX_C"\fR to get the largest type available on the platform.
+.RS 4
+.Sp
+.Vb 3
+\& U16  UINT16_C(number)
+\& U32  UINT32_C(number)
+\& U64  UINT64_C(number)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UINTMAX_C""" 4
+.el .IP \f(CWUINTMAX_C\fR 4
+.IX Xref "UINTMAX_C"
+.IX Item "UINTMAX_C"
+Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
+widest unsigned integer type on the machine.  For example, if the machine has
+\&\f(CW\*(C`long\*(C'\fRs, \f(CWUINTMAX_C(1)\fR would yield
+.Sp
+.Vb 1
+\& 1UL
+.Ve
+.Sp
+See also, for example, \f(CW"UINT32_C"\fR.
+.Sp
+Use "UV" to declare variables of the maximum usable size on this platform.
+.RS 4
+.Sp
+.Vb 1
+\&   UINTMAX_C(number)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """U32of""" 4
+.el .IP \f(CWU32of\fR 4
+.IX Xref "U32of"
+.IX Item "U32of"
+This symbol defines the format string used for printing a Perl U32
+as an unsigned octal integer.
+.ie n .IP """U8SIZE""" 4
+.el .IP \f(CWU8SIZE\fR 4
+.IX Xref "U8SIZE"
+.IX Item "U8SIZE"
+This symbol contains the \f(CWsizeof(U8)\fR.
+.ie n .IP """U16SIZE""" 4
+.el .IP \f(CWU16SIZE\fR 4
+.IX Xref "U16SIZE"
+.IX Item "U16SIZE"
+This symbol contains the \f(CWsizeof(U16)\fR.
+.ie n .IP """U32SIZE""" 4
+.el .IP \f(CWU32SIZE\fR 4
+.IX Xref "U32SIZE"
+.IX Item "U32SIZE"
+This symbol contains the \f(CWsizeof(U32)\fR.
+.ie n .IP """U64SIZE""" 4
+.el .IP \f(CWU64SIZE\fR 4
+.IX Xref "U64SIZE"
+.IX Item "U64SIZE"
+This symbol contains the \f(CWsizeof(U64)\fR.
+.ie n .IP """U8TYPE""" 4
+.el .IP \f(CWU8TYPE\fR 4
+.IX Xref "U8TYPE"
+.IX Item "U8TYPE"
+This symbol defines the C type used for Perl's U8.
+.ie n .IP """U16TYPE""" 4
+.el .IP \f(CWU16TYPE\fR 4
+.IX Xref "U16TYPE"
+.IX Item "U16TYPE"
+This symbol defines the C type used for Perl's U16.
+.ie n .IP """U32TYPE""" 4
+.el .IP \f(CWU32TYPE\fR 4
+.IX Xref "U32TYPE"
+.IX Item "U32TYPE"
+This symbol defines the C type used for Perl's U32.
+.ie n .IP """U64TYPE""" 4
+.el .IP \f(CWU64TYPE\fR 4
+.IX Xref "U64TYPE"
+.IX Item "U64TYPE"
+This symbol defines the C type used for Perl's U64.
+.ie n .IP """U32uf""" 4
+.el .IP \f(CWU32uf\fR 4
+.IX Xref "U32uf"
+.IX Item "U32uf"
+This symbol defines the format string used for printing a Perl U32
+as an unsigned decimal integer.
+.ie n .IP """UV""" 4
+.el .IP \f(CWUV\fR 4
+.IX Item "UV"
+.PD 0
+.ie n .IP """U8""" 4
+.el .IP \f(CWU8\fR 4
+.IX Item "U8"
+.ie n .IP """U16""" 4
+.el .IP \f(CWU16\fR 4
+.IX Item "U16"
+.ie n .IP """U32""" 4
+.el .IP \f(CWU32\fR 4
+.IX Item "U32"
+.ie n .IP """U64""" 4
+.el .IP \f(CWU64\fR 4
+.IX Item "U64"
+.PD
+Described in perlguts.
+.ie n .IP """UV_MAX""" 4
+.el .IP \f(CWUV_MAX\fR 4
+.IX Xref "UV_MAX"
+.IX Item "UV_MAX"
+The largest unsigned integer that fits in a UV on this platform.
+.RS 4
+.Sp
+.Vb 1
+\& UV  UV_MAX
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UV_MIN""" 4
+.el .IP \f(CWUV_MIN\fR 4
+.IX Xref "UV_MIN"
+.IX Item "UV_MIN"
+The smallest unsigned integer that fits in a UV on this platform.  It should
+equal zero.
+.RS 4
+.Sp
+.Vb 1
+\& UV  UV_MIN
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UVSIZE""" 4
+.el .IP \f(CWUVSIZE\fR 4
+.IX Xref "UVSIZE"
+.IX Item "UVSIZE"
+This symbol contains the \f(CWsizeof(UV)\fR.
+.ie n .IP """UVTYPE""" 4
+.el .IP \f(CWUVTYPE\fR 4
+.IX Xref "UVTYPE"
+.IX Item "UVTYPE"
+This symbol defines the C type used for Perl's UV.
+.ie n .IP """U32Xf""" 4
+.el .IP \f(CWU32Xf\fR 4
+.IX Xref "U32Xf"
+.IX Item "U32Xf"
+This symbol defines the format string used for printing a Perl U32
+as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
+.ie n .IP """U32xf""" 4
+.el .IP \f(CWU32xf\fR 4
+.IX Xref "U32xf"
+.IX Item "U32xf"
+This symbol defines the format string used for printing a Perl U32
+as an unsigned hexadecimal integer in lowercase abcdef.
+.ie n .IP """WIDEST_UTYPE""" 4
+.el .IP \f(CWWIDEST_UTYPE\fR 4
+.IX Xref "WIDEST_UTYPE"
+.IX Item "WIDEST_UTYPE"
+Yields the widest unsigned integer type on the platform, currently either
+\&\f(CW\*(C`U32\*(C'\fR or \f(CW\*(C`U64\*(C'\fR.  This can be used in declarations such as
+.Sp
+.Vb 1
+\& WIDEST_UTYPE my_uv;
+.Ve
+.Sp
+or casts
+.Sp
+.Vb 1
+\& my_uv = (WIDEST_UTYPE) val;
+.Ve
+.SH "I/O Formats"
+.IX Header "I/O Formats"
+These are used for formatting the corresponding type For example,
+instead of saying
+.PP
+.Vb 1
+\& Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\en", iv);
+.Ve
+.PP
+use
+.PP
+.Vb 1
+\& Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\en", iv);
+.Ve
+.PP
+This keeps you from having to know if, say an IV, needs to be
+printed as \f(CW%d\fR, \f(CW%ld\fR, or something else.
+.ie n .IP """HvNAMEf""" 4
+.el .IP \f(CWHvNAMEf\fR 4
+.IX Item "HvNAMEf"
+Described in perlguts.
+.ie n .IP """HvNAMEf_QUOTEDPREFIX""" 4
+.el .IP \f(CWHvNAMEf_QUOTEDPREFIX\fR 4
+.IX Item "HvNAMEf_QUOTEDPREFIX"
+Described in perlguts.
+.ie n .IP """IVdf""" 4
+.el .IP \f(CWIVdf\fR 4
+.IX Xref "IVdf"
+.IX Item "IVdf"
+This symbol defines the format string used for printing a Perl IV
+as a signed decimal integer.
+.ie n .IP """NVef""" 4
+.el .IP \f(CWNVef\fR 4
+.IX Xref "NVef"
+.IX Item "NVef"
+This symbol defines the format string used for printing a Perl NV
+using \f(CW%e\fR\-ish floating point format.
+.ie n .IP """NVff""" 4
+.el .IP \f(CWNVff\fR 4
+.IX Xref "NVff"
+.IX Item "NVff"
+This symbol defines the format string used for printing a Perl NV
+using \f(CW%f\fR\-ish floating point format.
+.ie n .IP """NVgf""" 4
+.el .IP \f(CWNVgf\fR 4
+.IX Xref "NVgf"
+.IX Item "NVgf"
+This symbol defines the format string used for printing a Perl NV
+using \f(CW%g\fR\-ish floating point format.
+.ie n .IP """PERL_PRIeldbl""" 4
+.el .IP \f(CWPERL_PRIeldbl\fR 4
+.IX Xref "PERL_PRIeldbl"
+.IX Item "PERL_PRIeldbl"
+This symbol, if defined, contains the string used by stdio to
+format long doubles (format 'e') for output.
+.ie n .IP """PERL_PRIfldbl""" 4
+.el .IP \f(CWPERL_PRIfldbl\fR 4
+.IX Xref "PERL_PRIfldbl"
+.IX Item "PERL_PRIfldbl"
+This symbol, if defined, contains the string used by stdio to
+format long doubles (format 'f') for output.
+.ie n .IP """PERL_PRIgldbl""" 4
+.el .IP \f(CWPERL_PRIgldbl\fR 4
+.IX Xref "PERL_PRIgldbl"
+.IX Item "PERL_PRIgldbl"
+This symbol, if defined, contains the string used by stdio to
+format long doubles (format 'g') for output.
+.ie n .IP """PERL_SCNfldbl""" 4
+.el .IP \f(CWPERL_SCNfldbl\fR 4
+.IX Xref "PERL_SCNfldbl"
+.IX Item "PERL_SCNfldbl"
+This symbol, if defined, contains the string used by stdio to
+format long doubles (format 'f') for input.
+.ie n .IP """PRINTF_FORMAT_NULL_OK""" 4
+.el .IP \f(CWPRINTF_FORMAT_NULL_OK\fR 4
+.IX Xref "PRINTF_FORMAT_NULL_OK"
+.IX Item "PRINTF_FORMAT_NULL_OK"
+Allows \f(CW\*(C`_\|_printf_\|_\*(C'\fR format to be null when checking printf-style
+.ie n .IP """SVf""" 4
+.el .IP \f(CWSVf\fR 4
+.IX Item "SVf"
+Described in perlguts.
+.ie n .IP """SVfARG""" 4
+.el .IP \f(CWSVfARG\fR 4
+.IX Item "SVfARG"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   SVfARG(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SVf_QUOTEDPREFIX""" 4
+.el .IP \f(CWSVf_QUOTEDPREFIX\fR 4
+.IX Item "SVf_QUOTEDPREFIX"
+Described in perlguts.
+.ie n .IP """UTF8f""" 4
+.el .IP \f(CWUTF8f\fR 4
+.IX Item "UTF8f"
+Described in perlguts.
+.ie n .IP """UTF8fARG""" 4
+.el .IP \f(CWUTF8fARG\fR 4
+.IX Item "UTF8fARG"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8f_QUOTEDPREFIX""" 4
+.el .IP \f(CWUTF8f_QUOTEDPREFIX\fR 4
+.IX Item "UTF8f_QUOTEDPREFIX"
+Described in perlguts.
+.ie n .IP """UVf""" 4
+.el .IP \f(CWUVf\fR 4
+.IX Xref "UVf"
+.IX Item "UVf"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`UVf\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Obsolete form of \f(CW\*(C`UVuf\*(C'\fR, which you should convert to instead use
+.RS 4
+.Sp
+.Vb 1
+\& const char *  UVf
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UVof""" 4
+.el .IP \f(CWUVof\fR 4
+.IX Xref "UVof"
+.IX Item "UVof"
+This symbol defines the format string used for printing a Perl UV
+as an unsigned octal integer.
+.ie n .IP """UVuf""" 4
+.el .IP \f(CWUVuf\fR 4
+.IX Xref "UVuf"
+.IX Item "UVuf"
+This symbol defines the format string used for printing a Perl UV
+as an unsigned decimal integer.
+.ie n .IP """UVXf""" 4
+.el .IP \f(CWUVXf\fR 4
+.IX Xref "UVXf"
+.IX Item "UVXf"
+This symbol defines the format string used for printing a Perl UV
+as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
+.ie n .IP """UVxf""" 4
+.el .IP \f(CWUVxf\fR 4
+.IX Xref "UVxf"
+.IX Item "UVxf"
+This symbol defines the format string used for printing a Perl UV
+as an unsigned hexadecimal integer in lowercase abcdef.
+.SH "Lexer interface"
+.IX Xref "LEX_KEEP_PREVIOUS LEX_STUFF_UTF8 PARSE_OPTIONAL"
+.IX Header "Lexer interface"
+This is the lower layer of the Perl parser, managing characters and tokens.
+.ie n .IP """BHK""" 4
+.el .IP \f(CWBHK\fR 4
+.IX Item "BHK"
+Described in perlguts.
+.ie n .IP """lex_bufutf8""" 4
+.el .IP \f(CWlex_bufutf8\fR 4
+.IX Xref "lex_bufutf8"
+.IX Item "lex_bufutf8"
+NOTE: \f(CW\*(C`lex_bufutf8\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Indicates whether the octets in the lexer buffer
+("PL_parser\->linestr") should be interpreted as the UTF\-8 encoding
+of Unicode characters.  If not, they should be interpreted as Latin\-1
+characters.  This is analogous to the \f(CW\*(C`SvUTF8\*(C'\fR flag for scalars.
+.Sp
+In UTF\-8 mode, it is not guaranteed that the lexer buffer actually
+contains valid UTF\-8.  Lexing code must be robust in the face of invalid
+encoding.
+.Sp
+The actual \f(CW\*(C`SvUTF8\*(C'\fR flag of the "PL_parser\->linestr" scalar
+is significant, but not the whole story regarding the input character
+encoding.  Normally, when a file is being read, the scalar contains octets
+and its \f(CW\*(C`SvUTF8\*(C'\fR flag is off, but the octets should be interpreted as
+UTF\-8 if the \f(CW\*(C`use utf8\*(C'\fR pragma is in effect.  During a string eval,
+however, the scalar may have the \f(CW\*(C`SvUTF8\*(C'\fR flag on, and in this case its
+octets should be interpreted as UTF\-8 unless the \f(CW\*(C`use bytes\*(C'\fR pragma
+is in effect.  This logic may change in the future; use this function
+instead of implementing the logic yourself.
+.RS 4
+.Sp
+.Vb 1
+\& bool  lex_bufutf8()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_discard_to""" 4
+.el .IP \f(CWlex_discard_to\fR 4
+.IX Xref "lex_discard_to"
+.IX Item "lex_discard_to"
+NOTE: \f(CW\*(C`lex_discard_to\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Discards the first part of the "PL_parser\->linestr" buffer,
+up to \f(CW\*(C`ptr\*(C'\fR.  The remaining content of the buffer will be moved, and
+all pointers into the buffer updated appropriately.  \f(CW\*(C`ptr\*(C'\fR must not
+be later in the buffer than the position of "PL_parser\->bufptr":
+it is not permitted to discard text that has yet to be lexed.
+.Sp
+Normally it is not necessarily to do this directly, because it suffices to
+use the implicit discarding behaviour of "lex_next_chunk" and things
+based on it.  However, if a token stretches across multiple lines,
+and the lexing code has kept multiple lines of text in the buffer for
+that purpose, then after completion of the token it would be wise to
+explicitly discard the now-unneeded earlier lines, to avoid future
+multi-line tokens growing the buffer without bound.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_discard_to(char *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_grow_linestr""" 4
+.el .IP \f(CWlex_grow_linestr\fR 4
+.IX Xref "lex_grow_linestr"
+.IX Item "lex_grow_linestr"
+NOTE: \f(CW\*(C`lex_grow_linestr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Reallocates the lexer buffer ("PL_parser\->linestr") to accommodate
+at least \f(CW\*(C`len\*(C'\fR octets (including terminating \f(CW\*(C`NUL\*(C'\fR).  Returns a
+pointer to the reallocated buffer.  This is necessary before making
+any direct modification of the buffer that would increase its length.
+"lex_stuff_pvn" provides a more convenient way to insert text into
+the buffer.
+.Sp
+Do not use \f(CW\*(C`SvGROW\*(C'\fR or \f(CW\*(C`sv_grow\*(C'\fR directly on \f(CW\*(C`PL_parser\->linestr\*(C'\fR;
+this function updates all of the lexer's variables that point directly
+into the buffer.
+.RS 4
+.Sp
+.Vb 1
+\& char *  lex_grow_linestr(STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_next_chunk""" 4
+.el .IP \f(CWlex_next_chunk\fR 4
+.IX Xref "lex_next_chunk"
+.IX Item "lex_next_chunk"
+NOTE: \f(CW\*(C`lex_next_chunk\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Reads in the next chunk of text to be lexed, appending it to
+"PL_parser\->linestr".  This should be called when lexing code has
+looked to the end of the current chunk and wants to know more.  It is
+usual, but not necessary, for lexing to have consumed the entirety of
+the current chunk at this time.
+.Sp
+If "PL_parser\->bufptr" is pointing to the very end of the current
+chunk (i.e., the current chunk has been entirely consumed), normally the
+current chunk will be discarded at the same time that the new chunk is
+read in.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, the current chunk
+will not be discarded.  If the current chunk has not been entirely
+consumed, then it will not be discarded regardless of the flag.
+.Sp
+Returns true if some new text was added to the buffer, or false if the
+buffer has reached the end of the input text.
+.RS 4
+.Sp
+.Vb 1
+\& bool  lex_next_chunk(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_peek_unichar""" 4
+.el .IP \f(CWlex_peek_unichar\fR 4
+.IX Xref "lex_peek_unichar"
+.IX Item "lex_peek_unichar"
+NOTE: \f(CW\*(C`lex_peek_unichar\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Looks ahead one (Unicode) character in the text currently being lexed.
+Returns the codepoint (unsigned integer value) of the next character,
+or \-1 if lexing has reached the end of the input text.  To consume the
+peeked character, use "lex_read_unichar".
+.Sp
+If the next character is in (or extends into) the next chunk of input
+text, the next chunk will be read in.  Normally the current chunk will be
+discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
+bit set, then the current chunk will not be discarded.
+.Sp
+If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
+is encountered, an exception is generated.
+.RS 4
+.Sp
+.Vb 1
+\& I32  lex_peek_unichar(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_read_space""" 4
+.el .IP \f(CWlex_read_space\fR 4
+.IX Xref "lex_read_space"
+.IX Item "lex_read_space"
+NOTE: \f(CW\*(C`lex_read_space\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Reads optional spaces, in Perl style, in the text currently being
+lexed.  The spaces may include ordinary whitespace characters and
+Perl-style comments.  \f(CW\*(C`#line\*(C'\fR directives are processed if encountered.
+"PL_parser\->bufptr" is moved past the spaces, so that it points
+at a non-space character (or the end of the input text).
+.Sp
+If spaces extend into the next chunk of input text, the next chunk will
+be read in.  Normally the current chunk will be discarded at the same
+time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, then the current
+chunk will not be discarded.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_read_space(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_read_to""" 4
+.el .IP \f(CWlex_read_to\fR 4
+.IX Xref "lex_read_to"
+.IX Item "lex_read_to"
+NOTE: \f(CW\*(C`lex_read_to\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Consume text in the lexer buffer, from "PL_parser\->bufptr" up
+to \f(CW\*(C`ptr\*(C'\fR.  This advances "PL_parser\->bufptr" to match \f(CW\*(C`ptr\*(C'\fR,
+performing the correct bookkeeping whenever a newline character is passed.
+This is the normal way to consume lexed text.
+.Sp
+Interpretation of the buffer's octets can be abstracted out by
+using the slightly higher-level functions "lex_peek_unichar" and
+"lex_read_unichar".
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_read_to(char *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_read_unichar""" 4
+.el .IP \f(CWlex_read_unichar\fR 4
+.IX Xref "lex_read_unichar"
+.IX Item "lex_read_unichar"
+NOTE: \f(CW\*(C`lex_read_unichar\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Reads the next (Unicode) character in the text currently being lexed.
+Returns the codepoint (unsigned integer value) of the character read,
+and moves "PL_parser\->bufptr" past the character, or returns \-1
+if lexing has reached the end of the input text.  To non-destructively
+examine the next character, use "lex_peek_unichar" instead.
+.Sp
+If the next character is in (or extends into) the next chunk of input
+text, the next chunk will be read in.  Normally the current chunk will be
+discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
+bit set, then the current chunk will not be discarded.
+.Sp
+If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
+is encountered, an exception is generated.
+.RS 4
+.Sp
+.Vb 1
+\& I32  lex_read_unichar(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_start""" 4
+.el .IP \f(CWlex_start\fR 4
+.IX Xref "lex_start"
+.IX Item "lex_start"
+NOTE: \f(CW\*(C`lex_start\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Creates and initialises a new lexer/parser state object, supplying
+a context in which to lex and parse from a new source of Perl code.
+A pointer to the new state object is placed in "PL_parser".  An entry
+is made on the save stack so that upon unwinding, the new state object
+will be destroyed and the former value of "PL_parser" will be restored.
+Nothing else need be done to clean up the parsing context.
+.Sp
+The code to be parsed comes from \f(CW\*(C`line\*(C'\fR and \f(CW\*(C`rsfp\*(C'\fR.  \f(CW\*(C`line\*(C'\fR, if
+non-null, provides a string (in SV form) containing code to be parsed.
+A copy of the string is made, so subsequent modification of \f(CW\*(C`line\*(C'\fR
+does not affect parsing.  \f(CW\*(C`rsfp\*(C'\fR, if non-null, provides an input stream
+from which code will be read to be parsed.  If both are non-null, the
+code in \f(CW\*(C`line\*(C'\fR comes first and must consist of complete lines of input,
+and \f(CW\*(C`rsfp\*(C'\fR supplies the remainder of the source.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use.  Currently it is only
+used by perl internally, so extensions should always pass zero.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_start(SV *line, PerlIO *rsfp, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_stuff_pv""" 4
+.el .IP \f(CWlex_stuff_pv\fR 4
+.IX Xref "lex_stuff_pv"
+.IX Item "lex_stuff_pv"
+NOTE: \f(CW\*(C`lex_stuff_pv\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Insert characters into the lexer buffer ("PL_parser\->linestr"),
+immediately after the current lexing point ("PL_parser\->bufptr"),
+reallocating the buffer if necessary.  This means that lexing code that
+runs later will see the characters as if they had appeared in the input.
+It is not recommended to do this as part of normal parsing, and most
+uses of this facility run the risk of the inserted characters being
+interpreted in an unintended manner.
+.Sp
+The string to be inserted is represented by octets starting at \f(CW\*(C`pv\*(C'\fR
+and continuing to the first nul.  These octets are interpreted as either
+UTF\-8 or Latin\-1, according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set
+in \f(CW\*(C`flags\*(C'\fR.  The characters are recoded for the lexer buffer, according
+to how the buffer is currently being interpreted ("lex_bufutf8").
+If it is not convenient to nul-terminate a string to be inserted, the
+"lex_stuff_pvn" function is more appropriate.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_stuff_pv(const char *pv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_stuff_pvn""" 4
+.el .IP \f(CWlex_stuff_pvn\fR 4
+.IX Xref "lex_stuff_pvn"
+.IX Item "lex_stuff_pvn"
+NOTE: \f(CW\*(C`lex_stuff_pvn\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Insert characters into the lexer buffer ("PL_parser\->linestr"),
+immediately after the current lexing point ("PL_parser\->bufptr"),
+reallocating the buffer if necessary.  This means that lexing code that
+runs later will see the characters as if they had appeared in the input.
+It is not recommended to do this as part of normal parsing, and most
+uses of this facility run the risk of the inserted characters being
+interpreted in an unintended manner.
+.Sp
+The string to be inserted is represented by \f(CW\*(C`len\*(C'\fR octets starting
+at \f(CW\*(C`pv\*(C'\fR.  These octets are interpreted as either UTF\-8 or Latin\-1,
+according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set in \f(CW\*(C`flags\*(C'\fR.
+The characters are recoded for the lexer buffer, according to how the
+buffer is currently being interpreted ("lex_bufutf8").  If a string
+to be inserted is available as a Perl scalar, the "lex_stuff_sv"
+function is more convenient.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_stuff_pvn(const char *pv, STRLEN len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_stuff_pvs""" 4
+.el .IP \f(CWlex_stuff_pvs\fR 4
+.IX Xref "lex_stuff_pvs"
+.IX Item "lex_stuff_pvs"
+NOTE: \f(CW\*(C`lex_stuff_pvs\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Like "lex_stuff_pvn", but takes a literal string instead of
+a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_stuff_pvs("pv", U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_stuff_sv""" 4
+.el .IP \f(CWlex_stuff_sv\fR 4
+.IX Xref "lex_stuff_sv"
+.IX Item "lex_stuff_sv"
+NOTE: \f(CW\*(C`lex_stuff_sv\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Insert characters into the lexer buffer ("PL_parser\->linestr"),
+immediately after the current lexing point ("PL_parser\->bufptr"),
+reallocating the buffer if necessary.  This means that lexing code that
+runs later will see the characters as if they had appeared in the input.
+It is not recommended to do this as part of normal parsing, and most
+uses of this facility run the risk of the inserted characters being
+interpreted in an unintended manner.
+.Sp
+The string to be inserted is the string value of \f(CW\*(C`sv\*(C'\fR.  The characters
+are recoded for the lexer buffer, according to how the buffer is currently
+being interpreted ("lex_bufutf8").  If a string to be inserted is
+not already a Perl scalar, the "lex_stuff_pvn" function avoids the
+need to construct a scalar.
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_stuff_sv(SV *sv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """lex_unstuff""" 4
+.el .IP \f(CWlex_unstuff\fR 4
+.IX Xref "lex_unstuff"
+.IX Item "lex_unstuff"
+NOTE: \f(CW\*(C`lex_unstuff\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Discards text about to be lexed, from "PL_parser\->bufptr" up to
+\&\f(CW\*(C`ptr\*(C'\fR.  Text following \f(CW\*(C`ptr\*(C'\fR will be moved, and the buffer shortened.
+This hides the discarded text from any lexing code that runs later,
+as if the text had never appeared.
+.Sp
+This is not the normal way to consume lexed text.  For that, use
+"lex_read_to".
+.RS 4
+.Sp
+.Vb 1
+\& void  lex_unstuff(char *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_arithexpr""" 4
+.el .IP \f(CWparse_arithexpr\fR 4
+.IX Xref "parse_arithexpr"
+.IX Item "parse_arithexpr"
+NOTE: \f(CW\*(C`parse_arithexpr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a Perl arithmetic expression.  This may contain operators of precedence
+down to the bit shift operators.  The expression must be followed (and thus
+terminated) either by a comparison or lower-precedence operator or by
+something that would normally terminate an expression such as semicolon.
+If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
+otherwise it is mandatory.  It is up to the caller to ensure that the
+dynamic parser state ("PL_parser" et al) is correctly set to reflect
+the source of the code to be parsed and the lexical context for the
+expression.
+.Sp
+The op tree representing the expression is returned.  If an optional
+expression is absent, a null pointer is returned, otherwise the pointer
+will be non-null.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree is returned anyway.  The error is reflected in the parser state,
+normally resulting in a single exception at the top level of parsing
+which covers all the compilation errors that occurred.  Some compilation
+errors, however, will throw an exception immediately.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_arithexpr(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_barestmt""" 4
+.el .IP \f(CWparse_barestmt\fR 4
+.IX Xref "parse_barestmt"
+.IX Item "parse_barestmt"
+NOTE: \f(CW\*(C`parse_barestmt\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a single unadorned Perl statement.  This may be a normal imperative
+statement or a declaration that has compile-time effect.  It does not
+include any label or other affixture.  It is up to the caller to ensure
+that the dynamic parser state ("PL_parser" et al) is correctly set to
+reflect the source of the code to be parsed and the lexical context for
+the statement.
+.Sp
+The op tree representing the statement is returned.  This may be a
+null pointer if the statement is null, for example if it was actually
+a subroutine definition (which has compile-time side effects).  If not
+null, it will be ops directly implementing the statement, suitable to
+pass to "newSTATEOP".  It will not normally include a \f(CW\*(C`nextstate\*(C'\fR or
+equivalent op (except for those embedded in a scope contained entirely
+within the statement).
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree (most likely null) is returned anyway.  The error is reflected in
+the parser state, normally resulting in a single exception at the top
+level of parsing which covers all the compilation errors that occurred.
+Some compilation errors, however, will throw an exception immediately.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_barestmt(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_block""" 4
+.el .IP \f(CWparse_block\fR 4
+.IX Xref "parse_block"
+.IX Item "parse_block"
+NOTE: \f(CW\*(C`parse_block\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a single complete Perl code block.  This consists of an opening
+brace, a sequence of statements, and a closing brace.  The block
+constitutes a lexical scope, so \f(CW\*(C`my\*(C'\fR variables and various compile-time
+effects can be contained within it.  It is up to the caller to ensure
+that the dynamic parser state ("PL_parser" et al) is correctly set to
+reflect the source of the code to be parsed and the lexical context for
+the statement.
+.Sp
+The op tree representing the code block is returned.  This is always a
+real op, never a null pointer.  It will normally be a \f(CW\*(C`lineseq\*(C'\fR list,
+including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops.  No ops to construct any kind
+of runtime scope are included by virtue of it being a block.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree (most likely null) is returned anyway.  The error is reflected in
+the parser state, normally resulting in a single exception at the top
+level of parsing which covers all the compilation errors that occurred.
+Some compilation errors, however, will throw an exception immediately.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_block(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_fullexpr""" 4
+.el .IP \f(CWparse_fullexpr\fR 4
+.IX Xref "parse_fullexpr"
+.IX Item "parse_fullexpr"
+NOTE: \f(CW\*(C`parse_fullexpr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a single complete Perl expression.  This allows the full
+expression grammar, including the lowest-precedence operators such
+as \f(CW\*(C`or\*(C'\fR.  The expression must be followed (and thus terminated) by a
+token that an expression would normally be terminated by: end-of-file,
+closing bracketing punctuation, semicolon, or one of the keywords that
+signals a postfix expression-statement modifier.  If \f(CW\*(C`flags\*(C'\fR has the
+\&\f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, otherwise it is
+mandatory.  It is up to the caller to ensure that the dynamic parser
+state ("PL_parser" et al) is correctly set to reflect the source of
+the code to be parsed and the lexical context for the expression.
+.Sp
+The op tree representing the expression is returned.  If an optional
+expression is absent, a null pointer is returned, otherwise the pointer
+will be non-null.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree is returned anyway.  The error is reflected in the parser state,
+normally resulting in a single exception at the top level of parsing
+which covers all the compilation errors that occurred.  Some compilation
+errors, however, will throw an exception immediately.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_fullexpr(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_fullstmt""" 4
+.el .IP \f(CWparse_fullstmt\fR 4
+.IX Xref "parse_fullstmt"
+.IX Item "parse_fullstmt"
+NOTE: \f(CW\*(C`parse_fullstmt\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a single complete Perl statement.  This may be a normal imperative
+statement or a declaration that has compile-time effect, and may include
+optional labels.  It is up to the caller to ensure that the dynamic
+parser state ("PL_parser" et al) is correctly set to reflect the source
+of the code to be parsed and the lexical context for the statement.
+.Sp
+The op tree representing the statement is returned.  This may be a
+null pointer if the statement is null, for example if it was actually
+a subroutine definition (which has compile-time side effects).  If not
+null, it will be the result of a "newSTATEOP" call, normally including
+a \f(CW\*(C`nextstate\*(C'\fR or equivalent op.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree (most likely null) is returned anyway.  The error is reflected in
+the parser state, normally resulting in a single exception at the top
+level of parsing which covers all the compilation errors that occurred.
+Some compilation errors, however, will throw an exception immediately.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_fullstmt(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_label""" 4
+.el .IP \f(CWparse_label\fR 4
+.IX Xref "parse_label"
+.IX Item "parse_label"
+NOTE: \f(CW\*(C`parse_label\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a single label, possibly optional, of the type that may prefix a
+Perl statement.  It is up to the caller to ensure that the dynamic parser
+state ("PL_parser" et al) is correctly set to reflect the source of
+the code to be parsed.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the
+label is optional, otherwise it is mandatory.
+.Sp
+The name of the label is returned in the form of a fresh scalar.  If an
+optional label is absent, a null pointer is returned.
+.Sp
+If an error occurs in parsing, which can only occur if the label is
+mandatory, a valid label is returned anyway.  The error is reflected in
+the parser state, normally resulting in a single exception at the top
+level of parsing which covers all the compilation errors that occurred.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  parse_label(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_listexpr""" 4
+.el .IP \f(CWparse_listexpr\fR 4
+.IX Xref "parse_listexpr"
+.IX Item "parse_listexpr"
+NOTE: \f(CW\*(C`parse_listexpr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a Perl list expression.  This may contain operators of precedence
+down to the comma operator.  The expression must be followed (and thus
+terminated) either by a low-precedence logic operator such as \f(CW\*(C`or\*(C'\fR or by
+something that would normally terminate an expression such as semicolon.
+If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
+otherwise it is mandatory.  It is up to the caller to ensure that the
+dynamic parser state ("PL_parser" et al) is correctly set to reflect
+the source of the code to be parsed and the lexical context for the
+expression.
+.Sp
+The op tree representing the expression is returned.  If an optional
+expression is absent, a null pointer is returned, otherwise the pointer
+will be non-null.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree is returned anyway.  The error is reflected in the parser state,
+normally resulting in a single exception at the top level of parsing
+which covers all the compilation errors that occurred.  Some compilation
+errors, however, will throw an exception immediately.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_listexpr(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_stmtseq""" 4
+.el .IP \f(CWparse_stmtseq\fR 4
+.IX Xref "parse_stmtseq"
+.IX Item "parse_stmtseq"
+NOTE: \f(CW\*(C`parse_stmtseq\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a sequence of zero or more Perl statements.  These may be normal
+imperative statements, including optional labels, or declarations
+that have compile-time effect, or any mixture thereof.  The statement
+sequence ends when a closing brace or end-of-file is encountered in a
+place where a new statement could have validly started.  It is up to
+the caller to ensure that the dynamic parser state ("PL_parser" et al)
+is correctly set to reflect the source of the code to be parsed and the
+lexical context for the statements.
+.Sp
+The op tree representing the statement sequence is returned.  This may
+be a null pointer if the statements were all null, for example if there
+were no statements or if there were only subroutine definitions (which
+have compile-time side effects).  If not null, it will be a \f(CW\*(C`lineseq\*(C'\fR
+list, normally including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree is returned anyway.  The error is reflected in the parser state,
+normally resulting in a single exception at the top level of parsing
+which covers all the compilation errors that occurred.  Some compilation
+errors, however, will throw an exception immediately.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_stmtseq(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_subsignature""" 4
+.el .IP \f(CWparse_subsignature\fR 4
+.IX Xref "parse_subsignature"
+.IX Item "parse_subsignature"
+NOTE: \f(CW\*(C`parse_subsignature\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a subroutine signature declaration. This is the contents of the
+parentheses following a named or anonymous subroutine declaration when the
+\&\f(CW\*(C`signatures\*(C'\fR feature is enabled. Note that this function neither expects
+nor consumes the opening and closing parentheses around the signature; it
+is the caller's job to handle these.
+.Sp
+This function must only be called during parsing of a subroutine; after
+"start_subparse" has been called. It might allocate lexical variables on
+the pad for the current subroutine.
+.Sp
+The op tree to unpack the arguments from the stack at runtime is returned.
+This op tree should appear at the beginning of the compiled function. The
+caller may wish to use "op_append_list" to build their function body
+after it, or splice it together with the body before calling "newATTRSUB".
+.Sp
+The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
+be zero.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_subsignature(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """parse_termexpr""" 4
+.el .IP \f(CWparse_termexpr\fR 4
+.IX Xref "parse_termexpr"
+.IX Item "parse_termexpr"
+NOTE: \f(CW\*(C`parse_termexpr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Parse a Perl term expression.  This may contain operators of precedence
+down to the assignment operators.  The expression must be followed (and thus
+terminated) either by a comma or lower-precedence operator or by
+something that would normally terminate an expression such as semicolon.
+If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
+otherwise it is mandatory.  It is up to the caller to ensure that the
+dynamic parser state ("PL_parser" et al) is correctly set to reflect
+the source of the code to be parsed and the lexical context for the
+expression.
+.Sp
+The op tree representing the expression is returned.  If an optional
+expression is absent, a null pointer is returned, otherwise the pointer
+will be non-null.
+.Sp
+If an error occurs in parsing or compilation, in most cases a valid op
+tree is returned anyway.  The error is reflected in the parser state,
+normally resulting in a single exception at the top level of parsing
+which covers all the compilation errors that occurred.  Some compilation
+errors, however, will throw an exception immediately.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  parse_termexpr(U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_parser""" 4
+.el .IP \f(CWPL_parser\fR 4
+.IX Xref "PL_parser"
+.IX Item "PL_parser"
+Pointer to a structure encapsulating the state of the parsing operation
+currently in progress.  The pointer can be locally changed to perform
+a nested parse without interfering with the state of an outer parse.
+Individual members of \f(CW\*(C`PL_parser\*(C'\fR have their own documentation.
+.ie n .IP """PL_parser\->bufend""" 4
+.el .IP \f(CWPL_parser\->bufend\fR 4
+.IX Xref "PL_parser->bufend"
+.IX Item "PL_parser->bufend"
+NOTE: \f(CW\*(C`PL_parser\->bufend\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Direct pointer to the end of the chunk of text currently being lexed, the
+end of the lexer buffer.  This is equal to \f(CW\*(C`SvPVX(PL_parser\->linestr)
++ SvCUR(PL_parser\->linestr)\*(C'\fR.  A \f(CW\*(C`NUL\*(C'\fR character (zero octet) is
+always located at the end of the buffer, and does not count as part of
+the buffer's contents.
+.ie n .IP """PL_parser\->bufptr""" 4
+.el .IP \f(CWPL_parser\->bufptr\fR 4
+.IX Xref "PL_parser->bufptr"
+.IX Item "PL_parser->bufptr"
+NOTE: \f(CW\*(C`PL_parser\->bufptr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Points to the current position of lexing inside the lexer buffer.
+Characters around this point may be freely examined, within
+the range delimited by \f(CWSvPVX("PL_parser\->linestr")\fR and
+"PL_parser\->bufend".  The octets of the buffer may be intended to be
+interpreted as either UTF\-8 or Latin\-1, as indicated by "lex_bufutf8".
+.Sp
+Lexing code (whether in the Perl core or not) moves this pointer past
+the characters that it consumes.  It is also expected to perform some
+bookkeeping whenever a newline character is consumed.  This movement
+can be more conveniently performed by the function "lex_read_to",
+which handles newlines appropriately.
+.Sp
+Interpretation of the buffer's octets can be abstracted out by
+using the slightly higher-level functions "lex_peek_unichar" and
+"lex_read_unichar".
+.ie n .IP """PL_parser\->linestart""" 4
+.el .IP \f(CWPL_parser\->linestart\fR 4
+.IX Xref "PL_parser->linestart"
+.IX Item "PL_parser->linestart"
+NOTE: \f(CW\*(C`PL_parser\->linestart\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Points to the start of the current line inside the lexer buffer.
+This is useful for indicating at which column an error occurred, and
+not much else.  This must be updated by any lexing code that consumes
+a newline; the function "lex_read_to" handles this detail.
+.ie n .IP """PL_parser\->linestr""" 4
+.el .IP \f(CWPL_parser\->linestr\fR 4
+.IX Xref "PL_parser->linestr"
+.IX Item "PL_parser->linestr"
+NOTE: \f(CW\*(C`PL_parser\->linestr\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Buffer scalar containing the chunk currently under consideration of the
+text currently being lexed.  This is always a plain string scalar (for
+which \f(CW\*(C`SvPOK\*(C'\fR is true).  It is not intended to be used as a scalar by
+normal scalar means; instead refer to the buffer directly by the pointer
+variables described below.
+.Sp
+The lexer maintains various \f(CW\*(C`char*\*(C'\fR pointers to things in the
+\&\f(CW\*(C`PL_parser\->linestr\*(C'\fR buffer.  If \f(CW\*(C`PL_parser\->linestr\*(C'\fR is ever
+reallocated, all of these pointers must be updated.  Don't attempt to
+do this manually, but rather use "lex_grow_linestr" if you need to
+reallocate the buffer.
+.Sp
+The content of the text chunk in the buffer is commonly exactly one
+complete line of input, up to and including a newline terminator,
+but there are situations where it is otherwise.  The octets of the
+buffer may be intended to be interpreted as either UTF\-8 or Latin\-1.
+The function "lex_bufutf8" tells you which.  Do not use the \f(CW\*(C`SvUTF8\*(C'\fR
+flag on this scalar, which may disagree with it.
+.Sp
+For direct examination of the buffer, the variable
+"PL_parser\->bufend" points to the end of the buffer.  The current
+lexing position is pointed to by "PL_parser\->bufptr".  Direct use
+of these pointers is usually preferable to examination of the scalar
+through normal scalar means.
+.ie n .IP """suspend_compcv""" 4
+.el .IP \f(CWsuspend_compcv\fR 4
+.IX Xref "suspend_compcv"
+.IX Item "suspend_compcv"
+Implements part of the concept of a "suspended compilation CV", which can be
+used to pause the parser and compiler during parsing a CV in order to come
+back to it later on.
+.Sp
+This function saves the current state of the subroutine under compilation
+(\f(CW\*(C`PL_compcv\*(C'\fR) into the supplied buffer.  This should be used initially to
+create the state in the buffer, as the final thing before a \f(CW\*(C`LEAVE\*(C'\fR within a
+block.
+.Sp
+.Vb 3
+\&    ENTER;
+\&    start_subparse(0);
+\&    ...
+\&
+\&    suspend_compcv(&buffer);
+\&    LEAVE;
+.Ve
+.Sp
+Once suspended, the \f(CW\*(C`resume_compcv\*(C'\fR or \f(CW\*(C`resume_compcv_and_save\*(C'\fR function can
+later be used to continue the parsing from the point this stopped.
+.RS 4
+.Sp
+.Vb 1
+\& void  suspend_compcv(struct suspended_compcv *buffer)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """wrap_infix_plugin""" 4
+.el .IP \f(CWwrap_infix_plugin\fR 4
+.IX Xref "wrap_infix_plugin"
+.IX Item "wrap_infix_plugin"
+NOTE: \f(CW\*(C`wrap_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+\&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
+\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
+use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
+of new infix operators.
+.Sp
+Puts a C function into the chain of infix plugins.  This is the preferred
+way to manipulate the "PL_infix_plugin" variable.  \f(CW\*(C`new_plugin\*(C'\fR is a
+pointer to the C function that is to be added to the infix plugin chain, and
+\&\f(CW\*(C`old_plugin_p\*(C'\fR points to a storage location where a pointer to the next
+function in the chain will be stored.  The value of \f(CW\*(C`new_plugin\*(C'\fR is written
+into the "PL_infix_plugin" variable, while the value previously stored there
+is written to \f(CW*old_plugin_p\fR.
+.Sp
+Direct access to "PL_infix_plugin" should be avoided.
+.RS 4
+.Sp
+.Vb 2
+\& void  wrap_infix_plugin(Perl_infix_plugin_t new_plugin,
+\&                         Perl_infix_plugin_t *old_plugin_p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """wrap_keyword_plugin""" 4
+.el .IP \f(CWwrap_keyword_plugin\fR 4
+.IX Xref "wrap_keyword_plugin"
+.IX Item "wrap_keyword_plugin"
+NOTE: \f(CW\*(C`wrap_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Puts a C function into the chain of keyword plugins.  This is the
+preferred way to manipulate the "PL_keyword_plugin" variable.
+\&\f(CW\*(C`new_plugin\*(C'\fR is a pointer to the C function that is to be added to the
+keyword plugin chain, and \f(CW\*(C`old_plugin_p\*(C'\fR points to the storage location
+where a pointer to the next function in the chain will be stored.  The
+value of \f(CW\*(C`new_plugin\*(C'\fR is written into the "PL_keyword_plugin" variable,
+while the value previously stored there is written to \f(CW*old_plugin_p\fR.
+.Sp
+"PL_keyword_plugin" is global to an entire process, and a module wishing
+to hook keyword parsing may find itself invoked more than once per
+process, typically in different threads.  To handle that situation, this
+function is idempotent.  The location \f(CW*old_plugin_p\fR must initially
+(once per process) contain a null pointer.  A C variable of static
+duration (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
+it internal linkage) will be implicitly initialised appropriately, if it
+does not have an explicit initialiser.  This function will only actually
+modify the plugin chain if it finds \f(CW*old_plugin_p\fR to be null.  This
+function is also thread safe on the small scale.  It uses appropriate
+locking to avoid race conditions in accessing "PL_keyword_plugin".
+.Sp
+When this function is called, the function referenced by \f(CW\*(C`new_plugin\*(C'\fR
+must be ready to be called, except for \f(CW*old_plugin_p\fR being unfilled.
+In a threading situation, \f(CW\*(C`new_plugin\*(C'\fR may be called immediately, even
+before this function has returned.  \f(CW*old_plugin_p\fR will always be
+appropriately set before \f(CW\*(C`new_plugin\*(C'\fR is called.  If \f(CW\*(C`new_plugin\*(C'\fR
+decides not to do anything special with the identifier that it is given
+(which is the usual case for most calls to a keyword plugin), it must
+chain the plugin function referenced by \f(CW*old_plugin_p\fR.
+.Sp
+Taken all together, XS code to install a keyword plugin should typically
+look something like this:
+.Sp
+.Vb 10
+\&    static Perl_keyword_plugin_t next_keyword_plugin;
+\&    static OP *my_keyword_plugin(pTHX_
+\&        char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
+\&    {
+\&        if (memEQs(keyword_ptr, keyword_len,
+\&                   "my_new_keyword")) {
+\&            ...
+\&        } else {
+\&            return next_keyword_plugin(aTHX_
+\&                keyword_ptr, keyword_len, op_ptr);
+\&        }
+\&    }
+\&    BOOT:
+\&        wrap_keyword_plugin(my_keyword_plugin,
+\&                            &next_keyword_plugin);
+.Ve
+.Sp
+Direct access to "PL_keyword_plugin" should be avoided.
+.RS 4
+.Sp
+.Vb 2
+\& void  wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
+\&                           Perl_keyword_plugin_t *old_plugin_p)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Locales
+.IX Header "Locales"
+.ie n .IP """DECLARATION_FOR_LC_NUMERIC_MANIPULATION""" 4
+.el .IP \f(CWDECLARATION_FOR_LC_NUMERIC_MANIPULATION\fR 4
+.IX Xref "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
+.IX Item "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
+This macro should be used as a statement.  It declares a private variable
+(whose name begins with an underscore) that is needed by the other macros in
+this section.  Failing to include this correctly should lead to a syntax error.
+For compatibility with C89 C compilers it should be placed in a block before
+any executable statements.
+.RS 4
+.Sp
+.Vb 1
+\& void  DECLARATION_FOR_LC_NUMERIC_MANIPULATION
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """foldEQ_locale""" 4
+.el .IP \f(CWfoldEQ_locale\fR 4
+.IX Xref "foldEQ_locale"
+.IX Item "foldEQ_locale"
+Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the
+same case-insensitively in the current locale; false otherwise.
+.RS 4
+.Sp
+.Vb 1
+\& I32  foldEQ_locale(const char *a, const char *b, I32 len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HAS_DUPLOCALE""" 4
+.el .IP \f(CWHAS_DUPLOCALE\fR 4
+.IX Xref "HAS_DUPLOCALE"
+.IX Item "HAS_DUPLOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`duplocale\*(C'\fR routine is
+available to duplicate a locale object.
+.ie n .IP """HAS_FREELOCALE""" 4
+.el .IP \f(CWHAS_FREELOCALE\fR 4
+.IX Xref "HAS_FREELOCALE"
+.IX Item "HAS_FREELOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`freelocale\*(C'\fR routine is
+available to deallocates the resources associated with a locale object.
+.ie n .IP """HAS_LC_MONETARY_2008""" 4
+.el .IP \f(CWHAS_LC_MONETARY_2008\fR 4
+.IX Xref "HAS_LC_MONETARY_2008"
+.IX Item "HAS_LC_MONETARY_2008"
+This symbol, if defined, indicates that the localeconv routine is
+available and has the additional members added in \f(CW\*(C`POSIX\*(C'\fR 1003.1\-2008.
+.ie n .IP """HAS_LOCALECONV""" 4
+.el .IP \f(CWHAS_LOCALECONV\fR 4
+.IX Xref "HAS_LOCALECONV"
+.IX Item "HAS_LOCALECONV"
+This symbol, if defined, indicates that the \f(CW\*(C`localeconv\*(C'\fR routine is
+available for numeric and monetary formatting conventions.
+.ie n .IP """HAS_LOCALECONV_L""" 4
+.el .IP \f(CWHAS_LOCALECONV_L\fR 4
+.IX Xref "HAS_LOCALECONV_L"
+.IX Item "HAS_LOCALECONV_L"
+This symbol, if defined, indicates that the \f(CW\*(C`localeconv_l\*(C'\fR routine is
+available to query certain information about a locale.
+.ie n .IP """HAS_NEWLOCALE""" 4
+.el .IP \f(CWHAS_NEWLOCALE\fR 4
+.IX Xref "HAS_NEWLOCALE"
+.IX Item "HAS_NEWLOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`newlocale\*(C'\fR routine is
+available to return a new locale object or modify an existing
+locale object.
+.ie n .IP """HAS_NL_LANGINFO""" 4
+.el .IP \f(CWHAS_NL_LANGINFO\fR 4
+.IX Xref "HAS_NL_LANGINFO"
+.IX Item "HAS_NL_LANGINFO"
+This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo\*(C'\fR routine is
+available to return local data.  You will also need \fIlanginfo.h\fR
+and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR.
+.ie n .IP """HAS_NL_LANGINFO_L""" 4
+.el .IP \f(CWHAS_NL_LANGINFO_L\fR 4
+.IX Xref "HAS_NL_LANGINFO_L"
+.IX Item "HAS_NL_LANGINFO_L"
+This symbol, when defined, indicates presence of the \f(CWnl_langinfo_l()\fR
+function
+.ie n .IP """HAS_QUERYLOCALE""" 4
+.el .IP \f(CWHAS_QUERYLOCALE\fR 4
+.IX Xref "HAS_QUERYLOCALE"
+.IX Item "HAS_QUERYLOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`querylocale\*(C'\fR routine is
+available to return the name of the locale for a category mask.
+.ie n .IP """HAS_SETLOCALE""" 4
+.el .IP \f(CWHAS_SETLOCALE\fR 4
+.IX Xref "HAS_SETLOCALE"
+.IX Item "HAS_SETLOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`setlocale\*(C'\fR routine is
+available to handle locale-specific ctype implementations.
+.ie n .IP """HAS_SETLOCALE_R""" 4
+.el .IP \f(CWHAS_SETLOCALE_R\fR 4
+.IX Xref "HAS_SETLOCALE_R"
+.IX Item "HAS_SETLOCALE_R"
+This symbol, if defined, indicates that the \f(CW\*(C`setlocale_r\*(C'\fR routine
+is available to setlocale re-entrantly.
+.ie n .IP """HAS_THREAD_SAFE_NL_LANGINFO_L""" 4
+.el .IP \f(CWHAS_THREAD_SAFE_NL_LANGINFO_L\fR 4
+.IX Xref "HAS_THREAD_SAFE_NL_LANGINFO_L"
+.IX Item "HAS_THREAD_SAFE_NL_LANGINFO_L"
+This symbol, when defined, indicates presence of the \f(CWnl_langinfo_l()\fR
+function, and that it is thread-safe.
+.ie n .IP """HAS_USELOCALE""" 4
+.el .IP \f(CWHAS_USELOCALE\fR 4
+.IX Xref "HAS_USELOCALE"
+.IX Item "HAS_USELOCALE"
+This symbol, if defined, indicates that the \f(CW\*(C`uselocale\*(C'\fR routine is
+available to set the current locale for the calling thread.
+.ie n .IP """I_LANGINFO""" 4
+.el .IP \f(CWI_LANGINFO\fR 4
+.IX Xref "I_LANGINFO"
+.IX Item "I_LANGINFO"
+This symbol, if defined, indicates that \fIlanginfo.h\fR exists and
+should be included.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_LANGINFO
+\&     #include <langinfo.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_LOCALE""" 4
+.el .IP \f(CWI_LOCALE\fR 4
+.IX Xref "I_LOCALE"
+.IX Item "I_LOCALE"
+This symbol, if defined, indicates to the C program that it should
+include \fIlocale.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_LOCALE
+\&     #include <locale.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IN_LOCALE""" 4
+.el .IP \f(CWIN_LOCALE\fR 4
+.IX Xref "IN_LOCALE"
+.IX Item "IN_LOCALE"
+Evaluates to TRUE if the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
+.RS 4
+.Sp
+.Vb 1
+\& bool  IN_LOCALE
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IN_LOCALE_COMPILETIME""" 4
+.el .IP \f(CWIN_LOCALE_COMPILETIME\fR 4
+.IX Xref "IN_LOCALE_COMPILETIME"
+.IX Item "IN_LOCALE_COMPILETIME"
+Evaluates to TRUE if, when compiling a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
+the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
+.RS 4
+.Sp
+.Vb 1
+\& bool  IN_LOCALE_COMPILETIME
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IN_LOCALE_RUNTIME""" 4
+.el .IP \f(CWIN_LOCALE_RUNTIME\fR 4
+.IX Xref "IN_LOCALE_RUNTIME"
+.IX Item "IN_LOCALE_RUNTIME"
+Evaluates to TRUE if, when executing a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
+the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
+.RS 4
+.Sp
+.Vb 1
+\& bool  IN_LOCALE_RUNTIME
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_XLOCALE""" 4
+.el .IP \f(CWI_XLOCALE\fR 4
+.IX Xref "I_XLOCALE"
+.IX Item "I_XLOCALE"
+This symbol, if defined, indicates to the C program that the
+header \fIxlocale.h\fR is available.  See also \f(CW"NEED_XLOCALE_H"\fR
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_XLOCALE
+\&     #include <xlocale.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """NEED_XLOCALE_H""" 4
+.el .IP \f(CWNEED_XLOCALE_H\fR 4
+.IX Xref "NEED_XLOCALE_H"
+.IX Item "NEED_XLOCALE_H"
+This symbol, if defined, indicates that the C program should
+include \fIxlocale.h\fR to get \f(CWnewlocale()\fR and its friends.
+.ie n .IP """Perl_langinfo""" 4
+.el .IP \f(CWPerl_langinfo\fR 4
+.IX Item "Perl_langinfo"
+.PD 0
+.ie n .IP """Perl_langinfo8""" 4
+.el .IP \f(CWPerl_langinfo8\fR 4
+.IX Xref "Perl_langinfo Perl_langinfo8"
+.IX Item "Perl_langinfo8"
+.PD
+\&\f(CW\*(C`Perl_langinfo\*(C'\fR is an (almost) drop-in replacement for the system
+\&\f(CWnl_langinfo(3)\fR, taking the same \f(CW\*(C`item\*(C'\fR parameter values, and returning
+the same information.  But it is more thread-safe than regular
+\&\f(CWnl_langinfo()\fR, and hides the quirks of Perl's locale handling from your
+code, and can be used on systems that lack a native \f(CW\*(C`nl_langinfo\*(C'\fR.
+.Sp
+However, you should instead use the improved version of this:
+"Perl_langinfo8", which behaves identically except for an additional
+parameter, a pointer to a variable declared as "\f(CW\*(C`utf8ness_t\*(C'\fR", into which it
+returns to you how you should treat the returned string with regards to it
+being encoded in UTF\-8 or not.
+.Sp
+Concerning the differences between these and plain \f(CWnl_langinfo()\fR:
+.RS 4
+.IP a. 4
+.IX Item "a."
+\&\f(CW\*(C`Perl_langinfo8\*(C'\fR has an extra parameter, described above.  Besides this, the
+other reason they aren't quite a drop-in replacement is actually an advantage.
+The \f(CW\*(C`const\*(C'\fRness of the return allows the compiler to catch attempts to write
+into the returned buffer, which is illegal and could cause run-time crashes.
+.IP b. 4
+.IX Item "b."
+They deliver the correct results for the \f(CW\*(C`RADIXCHAR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR items,
+without you having to write extra code.  The reason for the extra code would be
+because these are from the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale category, which is normally
+kept set by Perl so that the radix is a dot, and the separator is the empty
+string, no matter what the underlying locale is supposed to be, and so to get
+the expected results, you have to temporarily toggle into the underlying
+locale, and later toggle back.  (You could use plain \f(CW\*(C`nl_langinfo\*(C'\fR and
+\&\f(CW"STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"\fR for this but then you wouldn't get
+the other advantages of \f(CWPerl_langinfo()\fR; not keeping \f(CW\*(C`LC_NUMERIC\*(C'\fR in the C
+(or equivalent) locale would break a lot of CPAN, which is expecting the radix
+(decimal point) character to be a dot.)
+.IP c. 4
+.IX Item "c."
+The system function they replace can have its static return buffer trashed,
+not only by a subsequent call to that function, but by a \f(CW\*(C`freelocale\*(C'\fR,
+\&\f(CW\*(C`setlocale\*(C'\fR, or other locale change.  The returned buffer of these functions
+is not changed until the next call to one or the other, so the buffer is never
+in a trashed state.
+.IP d. 4
+.IX Item "d."
+The return buffer is per-thread, so it also is never overwritten by a call to
+these functions from another thread;  unlike the function it replaces.
+.IP e. 4
+.IX Item "e."
+But most importantly, they work on systems that don't have \f(CW\*(C`nl_langinfo\*(C'\fR, such
+as Windows, hence making your code more portable.  Of the fifty-some possible
+items specified by the POSIX 2008 standard,
+<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
+only one is completely unimplemented, though on non-Windows platforms, another
+significant one is not fully implemented).  They use various techniques to
+recover the other items, including calling \f(CWlocaleconv(3)\fR, and
+\&\f(CWstrftime(3)\fR, both of which are specified in C89, so should be always be
+available.  Later \f(CWstrftime()\fR versions have additional capabilities; What the
+C locale yields or \f(CW""\fR is returned for any item not available on your system.
+.Sp
+It is important to note that, when called with an item that is recovered by
+using \f(CW\*(C`localeconv\*(C'\fR, the buffer from any previous explicit call to
+\&\f(CWlocaleconv(3)\fR will be overwritten.  But you shouldn't be using
+\&\f(CW\*(C`localeconv\*(C'\fR anyway because it is is very much not thread-safe, and suffers
+from the same problems outlined in item 'b.' above for the fields it returns that
+are controlled by the LC_NUMERIC locale category.  Instead, avoid all of those
+problems by calling "Perl_localeconv", which is thread-safe; or by using the
+methods given in perlcall  to call
+\&\f(CWPOSIX::localeconv()\fR, which is also thread-safe.
+.RE
+.RS 4
+.Sp
+The details for those items which may deviate from what this emulation returns
+and what a native \f(CWnl_langinfo()\fR would return are specified in
+I18N::Langinfo.
+.Sp
+When using \f(CW\*(C`Perl_langinfo8\*(C'\fR (or plain \f(CW\*(C`Perl_langinfo\*(C'\fR) on systems that don't
+have a native \f(CWnl_langinfo()\fR, you must
+.Sp
+.Vb 1
+\& #include "perl_langinfo.h"
+.Ve
+.Sp
+before the \f(CW\*(C`perl.h\*(C'\fR \f(CW\*(C`#include\*(C'\fR.  You can replace your \fIlanginfo.h\fR
+\&\f(CW\*(C`#include\*(C'\fR with this one.  (Doing it this way keeps out the symbols that plain
+\&\fIlanginfo.h\fR would try to import into the namespace for code that doesn't need
+it.)
+.Sp
+.Vb 2
+\& const char *  Perl_langinfo (const int item)
+\& const char *  Perl_langinfo8(const int item, utf8ness_t *utf8ness)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Perl_localeconv""" 4
+.el .IP \f(CWPerl_localeconv\fR 4
+.IX Xref "Perl_localeconv"
+.IX Item "Perl_localeconv"
+This is a thread-safe version of the libc \fBlocaleconv\fR\|(3).  It is the same as
+POSIX::localeconv (returning a hash of the \f(CWlocaleconv()\fR
+fields), but directly callable from XS code.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  Perl_localeconv(pTHX)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Perl_setlocale""" 4
+.el .IP \f(CWPerl_setlocale\fR 4
+.IX Xref "Perl_setlocale"
+.IX Item "Perl_setlocale"
+This is an (almost) drop-in replacement for the system \f(CWsetlocale(3)\fR,
+taking the same parameters, and returning the same information, except that it
+returns the correct underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR locale.  Regular \f(CW\*(C`setlocale\*(C'\fR will
+instead return \f(CW\*(C`C\*(C'\fR if the underlying locale has a non-dot decimal point
+character, or a non-empty thousands separator for displaying floating point
+numbers.  This is because perl keeps that locale category such that it has a
+dot and empty separator, changing the locale briefly during the operations
+where the underlying one is required. \f(CW\*(C`Perl_setlocale\*(C'\fR knows about this, and
+compensates; regular \f(CW\*(C`setlocale\*(C'\fR doesn't.
+.Sp
+Another reason it isn't completely a drop-in replacement is that it is
+declared to return \f(CW\*(C`const\ char\ *\*(C'\fR, whereas the system setlocale omits the
+\&\f(CW\*(C`const\*(C'\fR (presumably because its API was specified long ago, and can't be
+updated; it is illegal to change the information \f(CW\*(C`setlocale\*(C'\fR returns; doing
+so leads to segfaults.)
+.Sp
+Finally, \f(CW\*(C`Perl_setlocale\*(C'\fR works under all circumstances, whereas plain
+\&\f(CW\*(C`setlocale\*(C'\fR can be completely ineffective on some platforms under some
+configurations.
+.Sp
+Changing the locale is not a good idea when more than one thread is running,
+except on systems where the predefined variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is 1.
+This is because on such systems the locale is global to the whole process and
+not local to just the thread calling the function.  So changing it in one
+thread instantaneously changes it in all.  On some such systems, the system
+\&\f(CWsetlocale()\fR is ineffective, returning the wrong information, and failing to
+actually change the locale.  z/OS refuses to try to change the locale once a
+second thread is created.  \f(CW\*(C`Perl_setlocale\*(C'\fR, should give you accurate results
+of what actually happened on these problematic platforms, returning NULL if the
+system forbade the locale change.
+.Sp
+The return points to a per-thread static buffer, which is overwritten the next
+time \f(CW\*(C`Perl_setlocale\*(C'\fR is called from the same thread.
+.RS 4
+.Sp
+.Vb 2
+\& const char *  Perl_setlocale(const int category,
+\&                              const char *locale)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RESTORE_LC_NUMERIC""" 4
+.el .IP \f(CWRESTORE_LC_NUMERIC\fR 4
+.IX Xref "RESTORE_LC_NUMERIC"
+.IX Item "RESTORE_LC_NUMERIC"
+This is used in conjunction with one of the macros
+"STORE_LC_NUMERIC_SET_TO_NEEDED"
+and "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR state.
+.Sp
+A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
+declare at compile time a private variable used by this macro and the two
+\&\f(CW\*(C`STORE\*(C'\fR ones.  This macro should be called as a single statement, not an
+expression, but with an empty argument list, like this:
+.Sp
+.Vb 6
+\& {
+\&    DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
+\&     ...
+\&    RESTORE_LC_NUMERIC();
+\&     ...
+\& }
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  RESTORE_LC_NUMERIC()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SETLOCALE_ACCEPTS_ANY_LOCALE_NAME""" 4
+.el .IP \f(CWSETLOCALE_ACCEPTS_ANY_LOCALE_NAME\fR 4
+.IX Xref "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
+.IX Item "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
+This symbol, if defined, indicates that the setlocale routine is
+available and it accepts any input locale name as valid.
+.ie n .IP """STORE_LC_NUMERIC_FORCE_TO_UNDERLYING""" 4
+.el .IP \f(CWSTORE_LC_NUMERIC_FORCE_TO_UNDERLYING\fR 4
+.IX Xref "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
+.IX Item "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
+This is used by XS code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware to force the
+locale for category \f(CW\*(C`LC_NUMERIC\*(C'\fR to be what perl thinks is the current
+underlying locale.  (The perl interpreter could be wrong about what the
+underlying locale actually is if some C or XS code has called the C library
+function \fBsetlocale\fR\|(3) behind its back; calling "sync_locale" before calling
+this macro will update perl's records.)
+.Sp
+A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
+declare at compile time a private variable used by this macro.  This macro
+should be called as a single statement, not an expression, but with an empty
+argument list, like this:
+.Sp
+.Vb 8
+\& {
+\&    DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
+\&     ...
+\&    STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
+\&     ...
+\&    RESTORE_LC_NUMERIC();
+\&     ...
+\& }
+.Ve
+.Sp
+The private variable is used to save the current locale state, so
+that the requisite matching call to "RESTORE_LC_NUMERIC" can restore it.
+.Sp
+On threaded perls not operating with thread-safe functionality, this macro uses
+a mutex to force a critical section.  Therefore the matching RESTORE should be
+close by, and guaranteed to be called.
+.RS 4
+.Sp
+.Vb 1
+\& void  STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED""" 4
+.el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED\fR 4
+.IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED"
+.IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED"
+This is used to help wrap XS or C code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware.
+This locale category is generally kept set to a locale where the decimal radix
+character is a dot, and the separator between groups of digits is empty.  This
+is because most XS code that reads floating point numbers is expecting them to
+have this syntax.
+.Sp
+This macro makes sure the current \f(CW\*(C`LC_NUMERIC\*(C'\fR state is set properly, to be
+aware of locale if the call to the XS or C code from the Perl program is
+from within the scope of a \f(CW\*(C`use\ locale\*(C'\fR; or to ignore locale if the call is
+instead from outside such scope.
+.Sp
+This macro is the start of wrapping the C or XS code; the wrap ending is done
+by calling the "RESTORE_LC_NUMERIC" macro after the operation.  Otherwise
+the state can be changed that will adversely affect other XS code.
+.Sp
+A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
+declare at compile time a private variable used by this macro.  This macro
+should be called as a single statement, not an expression, but with an empty
+argument list, like this:
+.Sp
+.Vb 8
+\& {
+\&    DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
+\&     ...
+\&    STORE_LC_NUMERIC_SET_TO_NEEDED();
+\&     ...
+\&    RESTORE_LC_NUMERIC();
+\&     ...
+\& }
+.Ve
+.Sp
+On threaded perls not operating with thread-safe functionality, this macro uses
+a mutex to force a critical section.  Therefore the matching RESTORE should be
+close by, and guaranteed to be called; see "WITH_LC_NUMERIC_SET_TO_NEEDED"
+for a more contained way to ensure that.
+.RS 4
+.Sp
+.Vb 1
+\& void  STORE_LC_NUMERIC_SET_TO_NEEDED()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
+.el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
+.IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
+.IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
+Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
+as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's
+responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
+cannot have changed since the precalculation.
+.RS 4
+.Sp
+.Vb 1
+\& void  STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED""" 4
+.el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED\fR 4
+.IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED"
+.IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED"
+This macro invokes the supplied statement or block within the context
+of a "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC" pair
+if required, so eg:
+.Sp
+.Vb 3
+\&  WITH_LC_NUMERIC_SET_TO_NEEDED(
+\&    SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
+\&  );
+.Ve
+.Sp
+is equivalent to:
+.Sp
+.Vb 10
+\&  {
+\&#ifdef USE_LOCALE_NUMERIC
+\&    DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
+\&    STORE_LC_NUMERIC_SET_TO_NEEDED();
+\&#endif
+\&    SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
+\&#ifdef USE_LOCALE_NUMERIC
+\&    RESTORE_LC_NUMERIC();
+\&#endif
+\&  }
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  WITH_LC_NUMERIC_SET_TO_NEEDED(block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
+.el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
+.IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
+.IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
+Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
+as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's
+responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
+cannot have changed since the precalculation.
+.RS 4
+.Sp
+.Vb 1
+\& void  WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Magic
+.IX Xref "MAGIC"
+.IX Header "Magic"
+"Magic" is special data attached to SV structures in order to give them
+"magical" properties.  When any Perl code tries to read from, or assign to,
+an SV marked as magical, it calls the 'get' or 'set' function associated
+with that SV's magic.  A get is called prior to reading an SV, in order to
+give it a chance to update its internal value (get on $. writes the line
+number of the last read filehandle into the SV's IV slot), while
+set is called after an SV has been written to, in order to allow it to make
+use of its changed value (set on $/ copies the SV's new value to the
+PL_rs global variable).
+.PP
+Magic is implemented as a linked list of MAGIC structures attached to the
+SV.  Each MAGIC struct holds the type of the magic, a pointer to an array
+of functions that implement the \fBget()\fR, \fBset()\fR, \fBlength()\fR etc functions,
+plus space for some flags and pointers.  For example, a tied variable has
+a MAGIC structure that contains a pointer to the object associated with the
+tie.
+.ie n .IP """mg_clear""" 4
+.el .IP \f(CWmg_clear\fR 4
+.IX Xref "mg_clear"
+.IX Item "mg_clear"
+Clear something magical that the SV represents.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  mg_clear(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_copy""" 4
+.el .IP \f(CWmg_copy\fR 4
+.IX Xref "mg_copy"
+.IX Item "mg_copy"
+Copies the magic from one SV to another.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MGf_COPY""" 4
+.el .IP \f(CWMGf_COPY\fR 4
+.IX Item "MGf_COPY"
+.PD 0
+.ie n .IP """MGf_DUP""" 4
+.el .IP \f(CWMGf_DUP\fR 4
+.IX Item "MGf_DUP"
+.ie n .IP """MGf_LOCAL""" 4
+.el .IP \f(CWMGf_LOCAL\fR 4
+.IX Item "MGf_LOCAL"
+.PD
+Described in perlguts.
+.ie n .IP """mg_find""" 4
+.el .IP \f(CWmg_find\fR 4
+.IX Xref "mg_find"
+.IX Item "mg_find"
+Finds the magic pointer for \f(CW\*(C`type\*(C'\fR matching the SV.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& MAGIC *  mg_find(const SV *sv, int type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_findext""" 4
+.el .IP \f(CWmg_findext\fR 4
+.IX Xref "mg_findext"
+.IX Item "mg_findext"
+Finds the magic pointer of \f(CW\*(C`type\*(C'\fR with the given \f(CW\*(C`vtbl\*(C'\fR for the \f(CW\*(C`SV\*(C'\fR.  See
+\&\f(CW"sv_magicext"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& MAGIC *  mg_findext(const SV *sv, int type, const MGVTBL *vtbl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_free""" 4
+.el .IP \f(CWmg_free\fR 4
+.IX Xref "mg_free"
+.IX Item "mg_free"
+Free any magic storage used by the SV.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  mg_free(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_freeext""" 4
+.el .IP \f(CWmg_freeext\fR 4
+.IX Xref "mg_freeext"
+.IX Item "mg_freeext"
+Remove any magic of type \f(CW\*(C`how\*(C'\fR using virtual table \f(CW\*(C`vtbl\*(C'\fR from the
+SV \f(CW\*(C`sv\*(C'\fR.  See "sv_magic".
+.Sp
+\&\f(CW\*(C`mg_freeext(sv, how, NULL)\*(C'\fR is equivalent to \f(CW\*(C`mg_free_type(sv, how)\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mg_freeext(SV *sv, int how, const MGVTBL *vtbl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_free_type""" 4
+.el .IP \f(CWmg_free_type\fR 4
+.IX Xref "mg_free_type"
+.IX Item "mg_free_type"
+Remove any magic of type \f(CW\*(C`how\*(C'\fR from the SV \f(CW\*(C`sv\*(C'\fR.  See "sv_magic".
+.RS 4
+.Sp
+.Vb 1
+\& void  mg_free_type(SV *sv, int how)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_get""" 4
+.el .IP \f(CWmg_get\fR 4
+.IX Xref "mg_get"
+.IX Item "mg_get"
+Do magic before a value is retrieved from the SV.  The type of SV must
+be >= \f(CW\*(C`SVt_PVMG\*(C'\fR.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  mg_get(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_magical""" 4
+.el .IP \f(CWmg_magical\fR 4
+.IX Xref "mg_magical"
+.IX Item "mg_magical"
+Turns on the magical status of an SV.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mg_magical(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_set""" 4
+.el .IP \f(CWmg_set\fR 4
+.IX Xref "mg_set"
+.IX Item "mg_set"
+Do magic after a value is assigned to the SV.  See \f(CW"sv_magic"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  mg_set(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MGVTBL""" 4
+.el .IP \f(CWMGVTBL\fR 4
+.IX Item "MGVTBL"
+Described in perlguts.
+.ie n .IP """PERL_MAGIC_arylen""" 4
+.el .IP \f(CWPERL_MAGIC_arylen\fR 4
+.IX Item "PERL_MAGIC_arylen"
+.PD 0
+.ie n .IP """PERL_MAGIC_arylen_p""" 4
+.el .IP \f(CWPERL_MAGIC_arylen_p\fR 4
+.IX Item "PERL_MAGIC_arylen_p"
+.ie n .IP """PERL_MAGIC_backref""" 4
+.el .IP \f(CWPERL_MAGIC_backref\fR 4
+.IX Item "PERL_MAGIC_backref"
+.ie n .IP """PERL_MAGIC_bm""" 4
+.el .IP \f(CWPERL_MAGIC_bm\fR 4
+.IX Item "PERL_MAGIC_bm"
+.ie n .IP """PERL_MAGIC_checkcall""" 4
+.el .IP \f(CWPERL_MAGIC_checkcall\fR 4
+.IX Item "PERL_MAGIC_checkcall"
+.ie n .IP """PERL_MAGIC_collxfrm""" 4
+.el .IP \f(CWPERL_MAGIC_collxfrm\fR 4
+.IX Item "PERL_MAGIC_collxfrm"
+.ie n .IP """PERL_MAGIC_dbfile""" 4
+.el .IP \f(CWPERL_MAGIC_dbfile\fR 4
+.IX Item "PERL_MAGIC_dbfile"
+.ie n .IP """PERL_MAGIC_dbline""" 4
+.el .IP \f(CWPERL_MAGIC_dbline\fR 4
+.IX Item "PERL_MAGIC_dbline"
+.ie n .IP """PERL_MAGIC_debugvar""" 4
+.el .IP \f(CWPERL_MAGIC_debugvar\fR 4
+.IX Item "PERL_MAGIC_debugvar"
+.ie n .IP """PERL_MAGIC_defelem""" 4
+.el .IP \f(CWPERL_MAGIC_defelem\fR 4
+.IX Item "PERL_MAGIC_defelem"
+.ie n .IP """PERL_MAGIC_destruct""" 4
+.el .IP \f(CWPERL_MAGIC_destruct\fR 4
+.IX Item "PERL_MAGIC_destruct"
+.ie n .IP """PERL_MAGIC_env""" 4
+.el .IP \f(CWPERL_MAGIC_env\fR 4
+.IX Item "PERL_MAGIC_env"
+.ie n .IP """PERL_MAGIC_envelem""" 4
+.el .IP \f(CWPERL_MAGIC_envelem\fR 4
+.IX Item "PERL_MAGIC_envelem"
+.ie n .IP """PERL_MAGIC_ext""" 4
+.el .IP \f(CWPERL_MAGIC_ext\fR 4
+.IX Item "PERL_MAGIC_ext"
+.ie n .IP """PERL_MAGIC_extvalue""" 4
+.el .IP \f(CWPERL_MAGIC_extvalue\fR 4
+.IX Item "PERL_MAGIC_extvalue"
+.ie n .IP """PERL_MAGIC_fm""" 4
+.el .IP \f(CWPERL_MAGIC_fm\fR 4
+.IX Item "PERL_MAGIC_fm"
+.ie n .IP """PERL_MAGIC_hints""" 4
+.el .IP \f(CWPERL_MAGIC_hints\fR 4
+.IX Item "PERL_MAGIC_hints"
+.ie n .IP """PERL_MAGIC_hintselem""" 4
+.el .IP \f(CWPERL_MAGIC_hintselem\fR 4
+.IX Item "PERL_MAGIC_hintselem"
+.ie n .IP """PERL_MAGIC_hook""" 4
+.el .IP \f(CWPERL_MAGIC_hook\fR 4
+.IX Item "PERL_MAGIC_hook"
+.ie n .IP """PERL_MAGIC_hookelem""" 4
+.el .IP \f(CWPERL_MAGIC_hookelem\fR 4
+.IX Item "PERL_MAGIC_hookelem"
+.ie n .IP """PERL_MAGIC_isa""" 4
+.el .IP \f(CWPERL_MAGIC_isa\fR 4
+.IX Item "PERL_MAGIC_isa"
+.ie n .IP """PERL_MAGIC_isaelem""" 4
+.el .IP \f(CWPERL_MAGIC_isaelem\fR 4
+.IX Item "PERL_MAGIC_isaelem"
+.ie n .IP """PERL_MAGIC_lvref""" 4
+.el .IP \f(CWPERL_MAGIC_lvref\fR 4
+.IX Item "PERL_MAGIC_lvref"
+.ie n .IP """PERL_MAGIC_nkeys""" 4
+.el .IP \f(CWPERL_MAGIC_nkeys\fR 4
+.IX Item "PERL_MAGIC_nkeys"
+.ie n .IP """PERL_MAGIC_nonelem""" 4
+.el .IP \f(CWPERL_MAGIC_nonelem\fR 4
+.IX Item "PERL_MAGIC_nonelem"
+.ie n .IP """PERL_MAGIC_overload_table""" 4
+.el .IP \f(CWPERL_MAGIC_overload_table\fR 4
+.IX Item "PERL_MAGIC_overload_table"
+.ie n .IP """PERL_MAGIC_pos""" 4
+.el .IP \f(CWPERL_MAGIC_pos\fR 4
+.IX Item "PERL_MAGIC_pos"
+.ie n .IP """PERL_MAGIC_qr""" 4
+.el .IP \f(CWPERL_MAGIC_qr\fR 4
+.IX Item "PERL_MAGIC_qr"
+.ie n .IP """PERL_MAGIC_regdata""" 4
+.el .IP \f(CWPERL_MAGIC_regdata\fR 4
+.IX Item "PERL_MAGIC_regdata"
+.ie n .IP """PERL_MAGIC_regdatum""" 4
+.el .IP \f(CWPERL_MAGIC_regdatum\fR 4
+.IX Item "PERL_MAGIC_regdatum"
+.ie n .IP """PERL_MAGIC_regex_global""" 4
+.el .IP \f(CWPERL_MAGIC_regex_global\fR 4
+.IX Item "PERL_MAGIC_regex_global"
+.ie n .IP """PERL_MAGIC_rhash""" 4
+.el .IP \f(CWPERL_MAGIC_rhash\fR 4
+.IX Item "PERL_MAGIC_rhash"
+.ie n .IP """PERL_MAGIC_shared""" 4
+.el .IP \f(CWPERL_MAGIC_shared\fR 4
+.IX Item "PERL_MAGIC_shared"
+.ie n .IP """PERL_MAGIC_shared_scalar""" 4
+.el .IP \f(CWPERL_MAGIC_shared_scalar\fR 4
+.IX Item "PERL_MAGIC_shared_scalar"
+.ie n .IP """PERL_MAGIC_sig""" 4
+.el .IP \f(CWPERL_MAGIC_sig\fR 4
+.IX Item "PERL_MAGIC_sig"
+.ie n .IP """PERL_MAGIC_sigelem""" 4
+.el .IP \f(CWPERL_MAGIC_sigelem\fR 4
+.IX Item "PERL_MAGIC_sigelem"
+.ie n .IP """PERL_MAGIC_substr""" 4
+.el .IP \f(CWPERL_MAGIC_substr\fR 4
+.IX Item "PERL_MAGIC_substr"
+.ie n .IP """PERL_MAGIC_sv""" 4
+.el .IP \f(CWPERL_MAGIC_sv\fR 4
+.IX Item "PERL_MAGIC_sv"
+.ie n .IP """PERL_MAGIC_symtab""" 4
+.el .IP \f(CWPERL_MAGIC_symtab\fR 4
+.IX Item "PERL_MAGIC_symtab"
+.ie n .IP """PERL_MAGIC_taint""" 4
+.el .IP \f(CWPERL_MAGIC_taint\fR 4
+.IX Item "PERL_MAGIC_taint"
+.ie n .IP """PERL_MAGIC_tied""" 4
+.el .IP \f(CWPERL_MAGIC_tied\fR 4
+.IX Item "PERL_MAGIC_tied"
+.ie n .IP """PERL_MAGIC_tiedelem""" 4
+.el .IP \f(CWPERL_MAGIC_tiedelem\fR 4
+.IX Item "PERL_MAGIC_tiedelem"
+.ie n .IP """PERL_MAGIC_tiedscalar""" 4
+.el .IP \f(CWPERL_MAGIC_tiedscalar\fR 4
+.IX Item "PERL_MAGIC_tiedscalar"
+.ie n .IP """PERL_MAGIC_utf8""" 4
+.el .IP \f(CWPERL_MAGIC_utf8\fR 4
+.IX Item "PERL_MAGIC_utf8"
+.ie n .IP """PERL_MAGIC_uvar""" 4
+.el .IP \f(CWPERL_MAGIC_uvar\fR 4
+.IX Item "PERL_MAGIC_uvar"
+.ie n .IP """PERL_MAGIC_uvar_elem""" 4
+.el .IP \f(CWPERL_MAGIC_uvar_elem\fR 4
+.IX Item "PERL_MAGIC_uvar_elem"
+.ie n .IP """PERL_MAGIC_vec""" 4
+.el .IP \f(CWPERL_MAGIC_vec\fR 4
+.IX Item "PERL_MAGIC_vec"
+.ie n .IP """PERL_MAGIC_vstring""" 4
+.el .IP \f(CWPERL_MAGIC_vstring\fR 4
+.IX Item "PERL_MAGIC_vstring"
+.PD
+Described in perlguts.
+.ie n .IP """SvTIED_obj""" 4
+.el .IP \f(CWSvTIED_obj\fR 4
+.IX Item "SvTIED_obj"
+Described in perlinterp.
+.RS 4
+.Sp
+.Vb 1
+\&   SvTIED_obj(SV *sv, MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Memory Management"
+.IX Header "Memory Management"
+.ie n .IP """dump_mstats""" 4
+.el .IP \f(CWdump_mstats\fR 4
+.IX Xref "dump_mstats"
+.IX Item "dump_mstats"
+When enabled by compiling with \f(CW\*(C`\-DDEBUGGING_MSTATS\*(C'\fR, print out statistics
+about malloc as two lines of numbers, one showing the length of the free list
+for each size category, the second showing the number of mallocs\ \-\ frees for
+each size category.
+.Sp
+\&\f(CW\*(C`s\*(C'\fR, if not NULL, is used as a phrase to include in the output, such as
+"after\ compilation".
+.RS 4
+.Sp
+.Vb 1
+\& void  dump_mstats(const char *s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """HASATTRIBUTE_MALLOC""" 4
+.el .IP \f(CWHASATTRIBUTE_MALLOC\fR 4
+.IX Xref "HASATTRIBUTE_MALLOC"
+.IX Item "HASATTRIBUTE_MALLOC"
+Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for malloc-style functions.
+.ie n .IP """HAS_MALLOC_GOOD_SIZE""" 4
+.el .IP \f(CWHAS_MALLOC_GOOD_SIZE\fR 4
+.IX Xref "HAS_MALLOC_GOOD_SIZE"
+.IX Item "HAS_MALLOC_GOOD_SIZE"
+This symbol, if defined, indicates that the \f(CW\*(C`malloc_good_size\*(C'\fR
+routine is available for use.
+.ie n .IP """HAS_MALLOC_SIZE""" 4
+.el .IP \f(CWHAS_MALLOC_SIZE\fR 4
+.IX Xref "HAS_MALLOC_SIZE"
+.IX Item "HAS_MALLOC_SIZE"
+This symbol, if defined, indicates that the \f(CW\*(C`malloc_size\*(C'\fR
+routine is available for use.
+.ie n .IP """I_MALLOCMALLOC""" 4
+.el .IP \f(CWI_MALLOCMALLOC\fR 4
+.IX Xref "I_MALLOCMALLOC"
+.IX Item "I_MALLOCMALLOC"
+This symbol, if defined, indicates to the C program that it should
+include \fImalloc/malloc.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_MALLOCMALLOC
+\&     #include <mallocmalloc.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MYMALLOC""" 4
+.el .IP \f(CWMYMALLOC\fR 4
+.IX Xref "MYMALLOC"
+.IX Item "MYMALLOC"
+This symbol, if defined, indicates that we're using our own malloc.
+.ie n .IP """Newx""" 4
+.el .IP \f(CWNewx\fR 4
+.IX Item "Newx"
+.PD 0
+.ie n .IP """safemalloc""" 4
+.el .IP \f(CWsafemalloc\fR 4
+.IX Xref "Newx safemalloc"
+.IX Item "safemalloc"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function.
+.Sp
+Memory obtained by this should \fBONLY\fR be freed with "Safefree".
+.Sp
+In 5.9.3, \fBNewx()\fR and friends replace the older \fBNew()\fR API, and drops
+the first parameter, \fIx\fR, a debug aid which allowed callers to identify
+themselves.  This aid has been superseded by a new build option,
+PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips).  The older API is still
+there for use in XS modules supporting older perls.
+.RS 4
+.Sp
+.Vb 2
+\& void   Newx      (void* ptr, int nitems, type)
+\& void*  safemalloc(size_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Newxc""" 4
+.el .IP \f(CWNewxc\fR 4
+.IX Xref "Newxc"
+.IX Item "Newxc"
+The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with
+cast.  See also \f(CW"Newx"\fR.
+.Sp
+Memory obtained by this should \fBONLY\fR be freed with "Safefree".
+.RS 4
+.Sp
+.Vb 1
+\& void  Newxc(void* ptr, int nitems, type, cast)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Newxz""" 4
+.el .IP \f(CWNewxz\fR 4
+.IX Item "Newxz"
+.PD 0
+.ie n .IP """safecalloc""" 4
+.el .IP \f(CWsafecalloc\fR 4
+.IX Xref "Newxz safecalloc"
+.IX Item "safecalloc"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function.  The allocated
+memory is zeroed with \f(CW\*(C`memzero\*(C'\fR.  See also \f(CW"Newx"\fR.
+.Sp
+Memory obtained by this should \fBONLY\fR be freed with "Safefree".
+.RS 4
+.Sp
+.Vb 2
+\& void   Newxz     (void* ptr, int nitems, type)
+\& void*  safecalloc(size_t nitems, size_t item_size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_MALLOC_WRAP""" 4
+.el .IP \f(CWPERL_MALLOC_WRAP\fR 4
+.IX Xref "PERL_MALLOC_WRAP"
+.IX Item "PERL_MALLOC_WRAP"
+This symbol, if defined, indicates that we'd like malloc wrap checks.
+.ie n .IP """Renew""" 4
+.el .IP \f(CWRenew\fR 4
+.IX Item "Renew"
+.PD 0
+.ie n .IP """saferealloc""" 4
+.el .IP \f(CWsaferealloc\fR 4
+.IX Xref "Renew saferealloc"
+.IX Item "saferealloc"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function.
+.Sp
+Memory obtained by this should \fBONLY\fR be freed with "Safefree".
+.RS 4
+.Sp
+.Vb 2
+\& void   Renew      (void* ptr, int nitems, type)
+\& void*  saferealloc(void *ptr, size_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Renewc""" 4
+.el .IP \f(CWRenewc\fR 4
+.IX Xref "Renewc"
+.IX Item "Renewc"
+The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with
+cast.
+.Sp
+Memory obtained by this should \fBONLY\fR be freed with "Safefree".
+.RS 4
+.Sp
+.Vb 1
+\& void  Renewc(void* ptr, int nitems, type, cast)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Safefree""" 4
+.el .IP \f(CWSafefree\fR 4
+.IX Xref "Safefree"
+.IX Item "Safefree"
+The XSUB-writer's interface to the C \f(CW\*(C`free\*(C'\fR function.
+.Sp
+This should \fBONLY\fR be used on memory obtained using "Newx" and friends.
+.RS 4
+.Sp
+.Vb 1
+\& void  Safefree(void* ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """safesyscalloc""" 4
+.el .IP \f(CWsafesyscalloc\fR 4
+.IX Xref "safesyscalloc"
+.IX Item "safesyscalloc"
+Safe version of system's \fBcalloc()\fR
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """safesysfree""" 4
+.el .IP \f(CWsafesysfree\fR 4
+.IX Xref "safesysfree"
+.IX Item "safesysfree"
+Safe version of system's \fBfree()\fR
+.RS 4
+.Sp
+.Vb 1
+\& Free_t  safesysfree(Malloc_t where)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """safesysmalloc""" 4
+.el .IP \f(CWsafesysmalloc\fR 4
+.IX Xref "safesysmalloc"
+.IX Item "safesysmalloc"
+Paranoid version of system's \fBmalloc()\fR
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  safesysmalloc(MEM_SIZE nbytes)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """safesysrealloc""" 4
+.el .IP \f(CWsafesysrealloc\fR 4
+.IX Xref "safesysrealloc"
+.IX Item "safesysrealloc"
+Paranoid version of system's \fBrealloc()\fR
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
+.Ve
+.RE
+.RS 4
+.RE
+.SH MRO
+.IX Header "MRO"
+These functions are related to the method resolution order of perl classes
+Also see perlmroapi.
+.ie n .IP """HvMROMETA""" 4
+.el .IP \f(CWHvMROMETA\fR 4
+.IX Item "HvMROMETA"
+Described in perlmroapi.
+.RS 4
+.Sp
+.Vb 1
+\& struct mro_meta *  HvMROMETA(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_get_from_name""" 4
+.el .IP \f(CWmro_get_from_name\fR 4
+.IX Xref "mro_get_from_name"
+.IX Item "mro_get_from_name"
+Returns the previously registered mro with the given \f(CW\*(C`name\*(C'\fR, or NULL if not
+registered.  See "\f(CW\*(C`mro_register\*(C'\fR".
+.Sp
+NOTE: \f(CW\*(C`mro_get_from_name\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mro_get_from_name\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& const struct mro_alg *  Perl_mro_get_from_name(pTHX_ SV *name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_get_linear_isa""" 4
+.el .IP \f(CWmro_get_linear_isa\fR 4
+.IX Xref "mro_get_linear_isa"
+.IX Item "mro_get_linear_isa"
+Returns the mro linearisation for the given stash.  By default, this
+will be whatever \f(CW\*(C`mro_get_linear_isa_dfs\*(C'\fR returns unless some
+other MRO is in effect for the stash.  The return value is a
+read-only AV* whose values are string SVs giving class names.
+.Sp
+You are responsible for \f(CWSvREFCNT_inc()\fR on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+.RS 4
+.Sp
+.Vb 1
+\& AV *  mro_get_linear_isa(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MRO_GET_PRIVATE_DATA""" 4
+.el .IP \f(CWMRO_GET_PRIVATE_DATA\fR 4
+.IX Item "MRO_GET_PRIVATE_DATA"
+Described in perlmroapi.
+.RS 4
+.Sp
+.Vb 2
+\& SV*  MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
+\&                           const struct mro_alg *const which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_method_changed_in""" 4
+.el .IP \f(CWmro_method_changed_in\fR 4
+.IX Xref "mro_method_changed_in"
+.IX Item "mro_method_changed_in"
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
+.Sp
+Ideally, all instances of \f(CW\*(C`PL_sub_generation++\*(C'\fR in
+perl source outside of \fImro.c\fR should be
+replaced by calls to this.
+.Sp
+Perl automatically handles most of the common
+ways a method might be redefined.  However, there
+are a few ways you could change a method in a stash
+without the cache code noticing, in which case you
+need to call this method afterwards:
+.Sp
+1) Directly manipulating the stash HV entries from
+XS code.
+.Sp
+2) Assigning a reference to a readonly scalar
+constant into a stash entry in order to create
+a constant subroutine (like \fIconstant.pm\fR
+does).
+.Sp
+This same method is available from pure perl
+via, \f(CWmro::method_changed_in(classname)\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mro_method_changed_in(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_register""" 4
+.el .IP \f(CWmro_register\fR 4
+.IX Xref "mro_register"
+.IX Item "mro_register"
+Registers a custom mro plugin.  See perlmroapi for details on this and other
+mro functions.
+.Sp
+NOTE: \f(CW\*(C`mro_register\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mro_register\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_mro_register(pTHX_ const struct mro_alg *mro)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_set_mro""" 4
+.el .IP \f(CWmro_set_mro\fR 4
+.IX Xref "mro_set_mro"
+.IX Item "mro_set_mro"
+Set \f(CW\*(C`meta\*(C'\fR to the value contained in the registered mro plugin whose name is
+\&\f(CW\*(C`name\*(C'\fR.
+.Sp
+Croaks if \f(CW\*(C`name\*(C'\fR hasn't been registered
+.Sp
+NOTE: \f(CW\*(C`mro_set_mro\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mro_set_mro\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
+\&                        SV * const name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_set_private_data""" 4
+.el .IP \f(CWmro_set_private_data\fR 4
+.IX Item "mro_set_private_data"
+Described in perlmroapi.
+.Sp
+NOTE: \f(CW\*(C`mro_set_private_data\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mro_set_private_data\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 4
+\& SV *  Perl_mro_set_private_data(pTHX_
+\&                                struct mro_meta * const smeta,
+\&                                const struct mro_alg * const which,
+\&                                SV * const data)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Multicall Functions"
+.IX Header "Multicall Functions"
+.ie n .IP """dMULTICALL""" 4
+.el .IP \f(CWdMULTICALL\fR 4
+.IX Xref "dMULTICALL"
+.IX Item "dMULTICALL"
+Declare local variables for a multicall.  See "LIGHTWEIGHT CALLBACKS" in perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   dMULTICALL;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MULTICALL""" 4
+.el .IP \f(CWMULTICALL\fR 4
+.IX Xref "MULTICALL"
+.IX Item "MULTICALL"
+Make a lightweight callback.  See "LIGHTWEIGHT CALLBACKS" in perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   MULTICALL;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POP_MULTICALL""" 4
+.el .IP \f(CWPOP_MULTICALL\fR 4
+.IX Xref "POP_MULTICALL"
+.IX Item "POP_MULTICALL"
+Closing bracket for a lightweight callback.
+See "LIGHTWEIGHT CALLBACKS" in perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   POP_MULTICALL;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSH_MULTICALL""" 4
+.el .IP \f(CWPUSH_MULTICALL\fR 4
+.IX Xref "PUSH_MULTICALL"
+.IX Item "PUSH_MULTICALL"
+Opening bracket for a lightweight callback.
+See "LIGHTWEIGHT CALLBACKS" in perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   PUSH_MULTICALL(CV* the_cv);
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Numeric Functions"
+.IX Xref "IS_NUMBER_GREATER_THAN_UV_MAX IS_NUMBER_INFINITY IS_NUMBER_IN_UV IS_NUMBER_NAN IS_NUMBER_NEG IS_NUMBER_NOT_INT PERL_SCAN_ALLOW_UNDERSCORES PERL_SCAN_DISALLOW_PREFIX PERL_SCAN_GREATER_THAN_UV_MAX PERL_SCAN_SILENT_ILLDIGIT PERL_SCAN_TRAILING"
+.IX Header "Numeric Functions"
+.ie n .IP """Atol""" 4
+.el .IP \f(CWAtol\fR 4
+.IX Item "Atol"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`Atol\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Described in perlhacktips.
+.RS 4
+.Sp
+.Vb 1
+\&   Atol(const char * nptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Atoul""" 4
+.el .IP \f(CWAtoul\fR 4
+.IX Item "Atoul"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`Atoul\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Described in perlhacktips.
+.RS 4
+.Sp
+.Vb 1
+\&   Atoul(const char * nptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Drand01""" 4
+.el .IP \f(CWDrand01\fR 4
+.IX Xref "Drand01"
+.IX Item "Drand01"
+This macro is to be used to generate uniformly distributed
+random numbers over the range [0., 1.[.  You may have to supply
+an 'extern double \f(CWdrand48()\fR;' in your program since SunOS 4.1.3
+doesn't provide you with anything relevant in its headers.
+See \f(CW"HAS_DRAND48_PROTO"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& double  Drand01()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Gconvert""" 4
+.el .IP \f(CWGconvert\fR 4
+.IX Xref "Gconvert"
+.IX Item "Gconvert"
+This preprocessor macro is defined to convert a floating point
+number to a string without a trailing decimal point.  This
+emulates the behavior of \f(CWsprintf("%g")\fR, but is sometimes much more
+efficient.  If \f(CWgconvert()\fR is not available, but \f(CWgcvt()\fR drops the
+trailing decimal point, then \f(CWgcvt()\fR is used.  If all else fails,
+a macro using \f(CWsprintf("%g")\fR is used. Arguments for the Gconvert
+macro are: value, number of digits, whether trailing zeros should
+be retained, and the output buffer.
+The usual values are:
+.Sp
+.Vb 3
+\& d_Gconvert=\*(Aqgconvert((x),(n),(t),(b))\*(Aq
+\& d_Gconvert=\*(Aqgcvt((x),(n),(b))\*(Aq
+\& d_Gconvert=\*(Aqsprintf((b),"%.*g",(n),(x))\*(Aq
+.Ve
+.Sp
+The last two assume trailing zeros should not be kept.
+.RS 4
+.Sp
+.Vb 1
+\& char *  Gconvert(double x, Size_t n, bool t, char * b)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_atoUV""" 4
+.el .IP \f(CWgrok_atoUV\fR 4
+.IX Xref "grok_atoUV"
+.IX Item "grok_atoUV"
+parse a string, looking for a decimal unsigned integer.
+.Sp
+On entry, \f(CW\*(C`pv\*(C'\fR points to the beginning of the string;
+\&\f(CW\*(C`valptr\*(C'\fR points to a UV that will receive the converted value, if found;
+\&\f(CW\*(C`endptr\*(C'\fR is either NULL or points to a variable that points to one byte
+beyond the point in \f(CW\*(C`pv\*(C'\fR that this routine should examine.
+If \f(CW\*(C`endptr\*(C'\fR is NULL, \f(CW\*(C`pv\*(C'\fR is assumed to be NUL-terminated.
+.Sp
+Returns FALSE if \f(CW\*(C`pv\*(C'\fR doesn't represent a valid unsigned integer value (with
+no leading zeros).  Otherwise it returns TRUE, and sets \f(CW*valptr\fR to that
+value.
+.Sp
+If you constrain the portion of \f(CW\*(C`pv\*(C'\fR that is looked at by this function (by
+passing a non-NULL \f(CW\*(C`endptr\*(C'\fR), and if the initial bytes of that portion form a
+valid value, it will return TRUE, setting \f(CW*endptr\fR to the byte following the
+final digit of the value.  But if there is no constraint at what's looked at,
+all of \f(CW\*(C`pv\*(C'\fR must be valid in order for TRUE to be returned.  \f(CW*endptr\fR is
+unchanged from its value on input if FALSE is returned;
+.Sp
+The only characters this accepts are the decimal digits '0'..'9'.
+.Sp
+As opposed to \fBatoi\fR\|(3) or \fBstrtol\fR\|(3), \f(CW\*(C`grok_atoUV\*(C'\fR does NOT allow optional
+leading whitespace, nor negative inputs.  If such features are required, the
+calling code needs to explicitly implement those.
+.Sp
+Note that this function returns FALSE for inputs that would overflow a UV,
+or have leading zeros.  Thus a single \f(CW0\fR is accepted, but not \f(CW00\fR nor
+\&\f(CW01\fR, \f(CW002\fR, \fIetc\fR.
+.Sp
+Background: \f(CW\*(C`atoi\*(C'\fR has severe problems with illegal inputs, it cannot be
+used for incremental parsing, and therefore should be avoided
+\&\f(CW\*(C`atoi\*(C'\fR and \f(CW\*(C`strtol\*(C'\fR are also affected by locale settings, which can also be
+seen as a bug (global state controlled by user environment).
+.RS 4
+.Sp
+.Vb 1
+\& bool  grok_atoUV(const char *pv, UV *valptr, const char **endptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_bin""" 4
+.el .IP \f(CWgrok_bin\fR 4
+.IX Xref "grok_bin"
+.IX Item "grok_bin"
+converts a string representing a binary number to numeric form.
+.Sp
+On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
+conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV.  The
+scan stops at the end of the string, or at just before the first invalid
+character.  Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
+encountering an invalid character (except NUL) will also trigger a warning.  On
+return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
+gives output flags.
+.Sp
+If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
+and nothing is written to \f(CW*result\fR.  If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_bin\*(C'\fR
+returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
+and writes an approximation of the correct value into \f(CW*result\fR (which is an
+NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
+.Sp
+The binary number may optionally be prefixed with \f(CW"0b"\fR or \f(CW"b"\fR unless
+\&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
+.Sp
+If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
+digits may be separated from each other by a single underscore; also a single
+leading underscore is accepted.
+.RS 4
+.Sp
+.Vb 2
+\& UV  grok_bin(const char *start, STRLEN *len_p, I32 *flags,
+\&              NV *result)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_hex""" 4
+.el .IP \f(CWgrok_hex\fR 4
+.IX Xref "grok_hex"
+.IX Item "grok_hex"
+converts a string representing a hex number to numeric form.
+.Sp
+On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
+conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV.  The
+scan stops at the end of the string, or at just before the first invalid
+character.  Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
+encountering an invalid character (except NUL) will also trigger a warning.  On
+return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
+gives output flags.
+.Sp
+If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
+and nothing is written to \f(CW*result\fR.  If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR
+returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
+and writes an approximation of the correct value into \f(CW*result\fR (which is an
+NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
+.Sp
+The hex number may optionally be prefixed with \f(CW"0x"\fR or \f(CW"x"\fR unless
+\&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
+.Sp
+If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
+digits may be separated from each other by a single underscore; also a single
+leading underscore is accepted.
+.RS 4
+.Sp
+.Vb 2
+\& UV  grok_hex(const char *start, STRLEN *len_p, I32 *flags,
+\&              NV *result)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_infnan""" 4
+.el .IP \f(CWgrok_infnan\fR 4
+.IX Xref "grok_infnan"
+.IX Item "grok_infnan"
+Helper for \f(CWgrok_number()\fR, accepts various ways of spelling "infinity"
+or "not a number", and returns one of the following flag combinations:
+.Sp
+.Vb 5
+\&  IS_NUMBER_INFINITY
+\&  IS_NUMBER_NAN
+\&  IS_NUMBER_INFINITY | IS_NUMBER_NEG
+\&  IS_NUMBER_NAN | IS_NUMBER_NEG
+\&  0
+.Ve
+.Sp
+possibly |\-ed with \f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR.
+.Sp
+If an infinity or a not-a-number is recognized, \f(CW*sp\fR will point to
+one byte past the end of the recognized string.  If the recognition fails,
+zero is returned, and \f(CW*sp\fR will not move.
+.RS 4
+.Sp
+.Vb 1
+\& int  grok_infnan(const char **sp, const char *send)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_number""" 4
+.el .IP \f(CWgrok_number\fR 4
+.IX Xref "grok_number"
+.IX Item "grok_number"
+Identical to \f(CWgrok_number_flags()\fR with \f(CW\*(C`flags\*(C'\fR set to zero.
+.RS 4
+.Sp
+.Vb 1
+\& int  grok_number(const char *pv, STRLEN len, UV *valuep)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_number_flags""" 4
+.el .IP \f(CWgrok_number_flags\fR 4
+.IX Xref "grok_number_flags"
+.IX Item "grok_number_flags"
+Recognise (or not) a number.  The type of the number is returned
+(0 if unrecognised), otherwise it is a bit-ORed combination of
+\&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR, \f(CW\*(C`IS_NUMBER_GREATER_THAN_UV_MAX\*(C'\fR, \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR,
+\&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR, \f(CW\*(C`IS_NUMBER_INFINITY\*(C'\fR, \f(CW\*(C`IS_NUMBER_NAN\*(C'\fR (defined in perl.h).
+.Sp
+If the value of the number can fit in a UV, it is returned in \f(CW*valuep\fR.
+\&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set to indicate that \f(CW*valuep\fR is valid, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR
+will never be set unless \f(CW*valuep\fR is valid, but \f(CW*valuep\fR may have been assigned
+to during processing even though \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set on return.
+If \f(CW\*(C`valuep\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set for the same cases as when
+\&\f(CW\*(C`valuep\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR, but no actual assignment (or SEGV) will occur.
+.Sp
+\&\f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR will be set with \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR if trailing decimals were
+seen (in which case \f(CW*valuep\fR gives the true value truncated to an integer), and
+\&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR if the number is negative (in which case \f(CW*valuep\fR holds the
+absolute value).  \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set if \f(CW\*(C`e\*(C'\fR notation was used or the
+number is larger than a UV.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR allows only \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR, which allows for trailing
+non-numeric text on an otherwise successful \fIgrok\fR, setting
+\&\f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR on the result.
+.RS 4
+.Sp
+.Vb 2
+\& int  grok_number_flags(const char *pv, STRLEN len, UV *valuep,
+\&                        U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """GROK_NUMERIC_RADIX""" 4
+.el .IP \f(CWGROK_NUMERIC_RADIX\fR 4
+.IX Xref "GROK_NUMERIC_RADIX"
+.IX Item "GROK_NUMERIC_RADIX"
+A synonym for "grok_numeric_radix"
+.RS 4
+.Sp
+.Vb 1
+\& bool  GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_numeric_radix""" 4
+.el .IP \f(CWgrok_numeric_radix\fR 4
+.IX Xref "grok_numeric_radix"
+.IX Item "grok_numeric_radix"
+Scan and skip for a numeric decimal separator (radix).
+.RS 4
+.Sp
+.Vb 1
+\& bool  grok_numeric_radix(const char **sp, const char *send)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """grok_oct""" 4
+.el .IP \f(CWgrok_oct\fR 4
+.IX Xref "grok_oct"
+.IX Item "grok_oct"
+converts a string representing an octal number to numeric form.
+.Sp
+On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
+conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV.  The
+scan stops at the end of the string, or at just before the first invalid
+character.  Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
+encountering an invalid character (except NUL) will also trigger a warning.  On
+return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
+gives output flags.
+.Sp
+If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
+and nothing is written to \f(CW*result\fR.  If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_oct\*(C'\fR
+returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
+and writes an approximation of the correct value into \f(CW*result\fR (which is an
+NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
+.Sp
+If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
+digits may be separated from each other by a single underscore; also a single
+leading underscore is accepted.
+.Sp
+The \f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR flag is always treated as being set for
+this function.
+.RS 4
+.Sp
+.Vb 2
+\& UV  grok_oct(const char *start, STRLEN *len_p, I32 *flags,
+\&              NV *result)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isinfnan""" 4
+.el .IP \f(CWisinfnan\fR 4
+.IX Xref "isinfnan"
+.IX Item "isinfnan"
+\&\f(CWPerl_isinfnan()\fR is a utility function that returns true if the NV
+argument is either an infinity or a \f(CW\*(C`NaN\*(C'\fR, false otherwise.  To test
+in more detail, use \f(CWPerl_isinf()\fR and \f(CWPerl_isnan()\fR.
+.Sp
+This is also the logical inverse of \fBPerl_isfinite()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  isinfnan(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_atof""" 4
+.el .IP \f(CWmy_atof\fR 4
+.IX Xref "my_atof"
+.IX Item "my_atof"
+\&\f(CW\*(C`atof\*(C'\fR(3), but properly works with Perl locale handling, accepting a dot
+radix character always, but also the current locale's radix character if and
+only if called from within the lexical scope of a Perl \f(CW\*(C`use locale\*(C'\fR statement.
+.Sp
+N.B. \f(CW\*(C`s\*(C'\fR must be NUL terminated.
+.RS 4
+.Sp
+.Vb 1
+\& NV  my_atof(const char *s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_strtod""" 4
+.el .IP \f(CWmy_strtod\fR 4
+.IX Xref "my_strtod"
+.IX Item "my_strtod"
+This function is equivalent to the libc \fBstrtod()\fR function, and is available
+even on platforms that lack plain \fBstrtod()\fR.  Its return value is the best
+available precision depending on platform capabilities and \fIConfigure\fR
+options.
+.Sp
+It properly handles the locale radix character, meaning it expects a dot except
+when called from within the scope of \f(CW\*(C`use\ locale\*(C'\fR, in which case the radix
+character should be that specified by the current locale.
+.Sp
+The synonym \fBStrtod()\fR may be used instead.
+.RS 4
+.Sp
+.Vb 1
+\& NV  my_strtod(const char * const s, char **e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_ABS""" 4
+.el .IP \f(CWPERL_ABS\fR 4
+.IX Xref "PERL_ABS"
+.IX Item "PERL_ABS"
+Typeless \f(CW\*(C`abs\*(C'\fR or \f(CW\*(C`fabs\*(C'\fR, \fIetc\fR.  (The usage below indicates it is for
+integers, but it works for any type.)  Use instead of these, since the C
+library ones force their argument to be what it is expecting, potentially
+leading to disaster.  But also beware that this evaluates its argument twice,
+so no \f(CW\*(C`x++\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  PERL_ABS(int x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Perl_acos""" 4
+.el .IP \f(CWPerl_acos\fR 4
+.IX Item "Perl_acos"
+.PD 0
+.ie n .IP """Perl_asin""" 4
+.el .IP \f(CWPerl_asin\fR 4
+.IX Item "Perl_asin"
+.ie n .IP """Perl_atan""" 4
+.el .IP \f(CWPerl_atan\fR 4
+.IX Item "Perl_atan"
+.ie n .IP """Perl_atan2""" 4
+.el .IP \f(CWPerl_atan2\fR 4
+.IX Item "Perl_atan2"
+.ie n .IP """Perl_ceil""" 4
+.el .IP \f(CWPerl_ceil\fR 4
+.IX Item "Perl_ceil"
+.ie n .IP """Perl_cos""" 4
+.el .IP \f(CWPerl_cos\fR 4
+.IX Item "Perl_cos"
+.ie n .IP """Perl_cosh""" 4
+.el .IP \f(CWPerl_cosh\fR 4
+.IX Item "Perl_cosh"
+.ie n .IP """Perl_exp""" 4
+.el .IP \f(CWPerl_exp\fR 4
+.IX Item "Perl_exp"
+.ie n .IP """Perl_floor""" 4
+.el .IP \f(CWPerl_floor\fR 4
+.IX Item "Perl_floor"
+.ie n .IP """Perl_fmod""" 4
+.el .IP \f(CWPerl_fmod\fR 4
+.IX Item "Perl_fmod"
+.ie n .IP """Perl_frexp""" 4
+.el .IP \f(CWPerl_frexp\fR 4
+.IX Item "Perl_frexp"
+.ie n .IP """Perl_isfinite""" 4
+.el .IP \f(CWPerl_isfinite\fR 4
+.IX Item "Perl_isfinite"
+.ie n .IP """Perl_isinf""" 4
+.el .IP \f(CWPerl_isinf\fR 4
+.IX Item "Perl_isinf"
+.ie n .IP """Perl_isnan""" 4
+.el .IP \f(CWPerl_isnan\fR 4
+.IX Item "Perl_isnan"
+.ie n .IP """Perl_ldexp""" 4
+.el .IP \f(CWPerl_ldexp\fR 4
+.IX Item "Perl_ldexp"
+.ie n .IP """Perl_log""" 4
+.el .IP \f(CWPerl_log\fR 4
+.IX Item "Perl_log"
+.ie n .IP """Perl_log10""" 4
+.el .IP \f(CWPerl_log10\fR 4
+.IX Item "Perl_log10"
+.ie n .IP """Perl_modf""" 4
+.el .IP \f(CWPerl_modf\fR 4
+.IX Item "Perl_modf"
+.ie n .IP """Perl_pow""" 4
+.el .IP \f(CWPerl_pow\fR 4
+.IX Item "Perl_pow"
+.ie n .IP """Perl_sin""" 4
+.el .IP \f(CWPerl_sin\fR 4
+.IX Item "Perl_sin"
+.ie n .IP """Perl_sinh""" 4
+.el .IP \f(CWPerl_sinh\fR 4
+.IX Item "Perl_sinh"
+.ie n .IP """Perl_sqrt""" 4
+.el .IP \f(CWPerl_sqrt\fR 4
+.IX Item "Perl_sqrt"
+.ie n .IP """Perl_tan""" 4
+.el .IP \f(CWPerl_tan\fR 4
+.IX Item "Perl_tan"
+.ie n .IP """Perl_tanh""" 4
+.el .IP \f(CWPerl_tanh\fR 4
+.IX Xref "Perl_acos Perl_asin Perl_atan Perl_atan2 Perl_ceil Perl_cos Perl_cosh Perl_exp Perl_floor Perl_fmod Perl_frexp Perl_isfinite Perl_isinf Perl_isnan Perl_ldexp Perl_log Perl_log10 Perl_modf Perl_pow Perl_sin Perl_sinh Perl_sqrt Perl_tan Perl_tanh"
+.IX Item "Perl_tanh"
+.PD
+These perform the corresponding mathematical operation on the operand(s), using
+the libc function designed for the task that has just enough precision for an
+NV on this platform.  If no such function with sufficient precision exists,
+the highest precision one available is used.
+.RS 4
+.Sp
+.Vb 10
+\& NV  Perl_acos    (NV x)
+\& NV  Perl_asin    (NV x)
+\& NV  Perl_atan    (NV x)
+\& NV  Perl_atan2   (NV x, NV y)
+\& NV  Perl_ceil    (NV x)
+\& NV  Perl_cos     (NV x)
+\& NV  Perl_cosh    (NV x)
+\& NV  Perl_exp     (NV x)
+\& NV  Perl_floor   (NV x)
+\& NV  Perl_fmod    (NV x, NV y)
+\& NV  Perl_frexp   (NV x, int *exp)
+\& IV  Perl_isfinite(NV x)
+\& IV  Perl_isinf   (NV x)
+\& IV  Perl_isnan   (NV x)
+\& NV  Perl_ldexp   (NV x, int exp)
+\& NV  Perl_log     (NV x)
+\& NV  Perl_log10   (NV x)
+\& NV  Perl_modf    (NV x, NV *iptr)
+\& NV  Perl_pow     (NV x, NV y)
+\& NV  Perl_sin     (NV x)
+\& NV  Perl_sinh    (NV x)
+\& NV  Perl_sqrt    (NV x)
+\& NV  Perl_tan     (NV x)
+\& NV  Perl_tanh    (NV x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Perl_signbit""" 4
+.el .IP \f(CWPerl_signbit\fR 4
+.IX Xref "Perl_signbit"
+.IX Item "Perl_signbit"
+NOTE: \f(CW\*(C`Perl_signbit\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Return a non-zero integer if the sign bit on an NV is set, and 0 if
+it is not.
+.Sp
+If \fIConfigure\fR detects this system has a \f(CWsignbit()\fR that will work with
+our NVs, then we just use it via the \f(CW\*(C`#define\*(C'\fR in \fIperl.h\fR.  Otherwise,
+fall back on this implementation.  The main use of this function
+is catching \f(CW\-0.0\fR.
+.Sp
+\&\f(CW\*(C`Configure\*(C'\fR notes:  This function is called \f(CW\*(AqPerl_signbit\*(Aq\fR instead of a
+plain \f(CW\*(Aqsignbit\*(Aq\fR because it is easy to imagine a system having a \f(CWsignbit()\fR
+function or macro that doesn't happen to work with our particular choice
+of NVs.  We shouldn't just re\-\f(CW\*(C`#define\*(C'\fR \f(CW\*(C`signbit\*(C'\fR as \f(CW\*(C`Perl_signbit\*(C'\fR and expect
+the standard system headers to be happy.  Also, this is a no-context
+function (no \f(CW\*(C`pTHX_\*(C'\fR) because \f(CWPerl_signbit()\fR is usually re\-\f(CW\*(C`#defined\*(C'\fR in
+\&\fIperl.h\fR as a simple macro call to the system's \f(CWsignbit()\fR.
+Users should just always call \f(CWPerl_signbit()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  Perl_signbit(NV f)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_hexdigit""" 4
+.el .IP \f(CWPL_hexdigit\fR 4
+.IX Xref "PL_hexdigit"
+.IX Item "PL_hexdigit"
+This array, indexed by an integer, converts that value into the character that
+represents it.  For example, if the input is 8, the return will be a string
+whose first character is '8'.  What is actually returned is a pointer into a
+string.  All you are interested in is the first character of that string.  To
+get uppercase letters (for the values 10..15), add 16 to the index.  Hence,
+\&\f(CW\*(C`PL_hexdigit[11]\*(C'\fR is \f(CW\*(Aqb\*(Aq\fR, and \f(CW\*(C`PL_hexdigit[11+16]\*(C'\fR is \f(CW\*(AqB\*(Aq\fR.  Adding 16
+to an index whose representation is '0'..'9' yields the same as not adding 16.
+Indices outside the range 0..31 result in (bad) undedefined behavior.
+.ie n .IP """READ_XDIGIT""" 4
+.el .IP \f(CWREAD_XDIGIT\fR 4
+.IX Xref "READ_XDIGIT"
+.IX Item "READ_XDIGIT"
+Returns the value of an ASCII-range hex digit and advances the string pointer.
+Behaviour is only well defined when isXDIGIT(*str) is true.
+.RS 4
+.Sp
+.Vb 1
+\& U8  READ_XDIGIT(char str*)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """scan_bin""" 4
+.el .IP \f(CWscan_bin\fR 4
+.IX Xref "scan_bin"
+.IX Item "scan_bin"
+For backwards compatibility.  Use \f(CW\*(C`grok_bin\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& NV  scan_bin(const char *start, STRLEN len, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """scan_hex""" 4
+.el .IP \f(CWscan_hex\fR 4
+.IX Xref "scan_hex"
+.IX Item "scan_hex"
+For backwards compatibility.  Use \f(CW\*(C`grok_hex\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& NV  scan_hex(const char *start, STRLEN len, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """scan_oct""" 4
+.el .IP \f(CWscan_oct\fR 4
+.IX Xref "scan_oct"
+.IX Item "scan_oct"
+For backwards compatibility.  Use \f(CW\*(C`grok_oct\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& NV  scan_oct(const char *start, STRLEN len, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """seedDrand01""" 4
+.el .IP \f(CWseedDrand01\fR 4
+.IX Xref "seedDrand01"
+.IX Item "seedDrand01"
+This symbol defines the macro to be used in seeding the
+random number generator (see \f(CW"Drand01"\fR).
+.RS 4
+.Sp
+.Vb 1
+\& void  seedDrand01(Rand_seed_t x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Strtod""" 4
+.el .IP \f(CWStrtod\fR 4
+.IX Xref "Strtod"
+.IX Item "Strtod"
+This is a synonym for "my_strtod".
+.RS 4
+.Sp
+.Vb 1
+\& NV  Strtod(NN const char * const s, NULLOK char ** e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Strtol""" 4
+.el .IP \f(CWStrtol\fR 4
+.IX Xref "Strtol"
+.IX Item "Strtol"
+Platform and configuration independent \f(CW\*(C`strtol\*(C'\fR.  This expands to the
+appropriate \f(CW\*(C`strotol\*(C'\fR\-like function based on the platform and \fIConfigure\fR
+options>.  For example it could expand to \f(CW\*(C`strtoll\*(C'\fR or \f(CW\*(C`strtoq\*(C'\fR instead of
+\&\f(CW\*(C`strtol\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& NV  Strtol(NN const char * const s, NULLOK char ** e, int base)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Strtoul""" 4
+.el .IP \f(CWStrtoul\fR 4
+.IX Xref "Strtoul"
+.IX Item "Strtoul"
+Platform and configuration independent \f(CW\*(C`strtoul\*(C'\fR.  This expands to the
+appropriate \f(CW\*(C`strotoul\*(C'\fR\-like function based on the platform and \fIConfigure\fR
+options>.  For example it could expand to \f(CW\*(C`strtoull\*(C'\fR or \f(CW\*(C`strtouq\*(C'\fR instead of
+\&\f(CW\*(C`strtoul\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& NV  Strtoul(NN const char * const s, NULLOK char ** e, int base)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Optrees
+.IX Xref "CALL_CHECKER_REQUIRE_GV OPf_KIDS OPpEARLY_CV OPpENTERSUB_AMPER RV2CVOPCV_MARK_EARLY RV2CVOPCV_RETURN_NAME_GV"
+.IX Header "Optrees"
+.ie n .IP """alloccopstash""" 4
+.el .IP \f(CWalloccopstash\fR 4
+.IX Xref "alloccopstash"
+.IX Item "alloccopstash"
+NOTE: \f(CW\*(C`alloccopstash\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Available only under threaded builds, this function allocates an entry in
+\&\f(CW\*(C`PL_stashpad\*(C'\fR for the stash passed to it.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  alloccopstash(HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BINOP""" 4
+.el .IP \f(CWBINOP\fR 4
+.IX Item "BINOP"
+Described in perlguts.
+.ie n .IP """block_end""" 4
+.el .IP \f(CWblock_end\fR 4
+.IX Xref "block_end"
+.IX Item "block_end"
+Handles compile-time scope exit.  \f(CW\*(C`floor\*(C'\fR
+is the savestack index returned by
+\&\f(CW\*(C`block_start\*(C'\fR, and \f(CW\*(C`seq\*(C'\fR is the body of the block.  Returns the block,
+possibly modified.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  block_end(I32 floor, OP *seq)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """block_start""" 4
+.el .IP \f(CWblock_start\fR 4
+.IX Xref "block_start"
+.IX Item "block_start"
+Handles compile-time scope entry.
+Arranges for hints to be restored on block
+exit and also handles pad sequence numbers to make lexical variables scope
+right.  Returns a savestack index for use with \f(CW\*(C`block_end\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  block_start(int full)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ck_entersub_args_list""" 4
+.el .IP \f(CWck_entersub_args_list\fR 4
+.IX Xref "ck_entersub_args_list"
+.IX Item "ck_entersub_args_list"
+Performs the default fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR
+op tree.  This consists of applying list context to each of the
+argument ops.  This is the standard treatment used on a call marked
+with \f(CW\*(C`&\*(C'\fR, or a method call, or a call through a subroutine reference,
+or any other call where the callee can't be identified at compile time,
+or a call where the callee has no prototype.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  ck_entersub_args_list(OP *entersubop)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ck_entersub_args_proto""" 4
+.el .IP \f(CWck_entersub_args_proto\fR 4
+.IX Xref "ck_entersub_args_proto"
+.IX Item "ck_entersub_args_proto"
+Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree
+based on a subroutine prototype.  This makes various modifications to
+the argument ops, from applying context up to inserting \f(CW\*(C`refgen\*(C'\fR ops,
+and checking the number and syntactic types of arguments, as directed by
+the prototype.  This is the standard treatment used on a subroutine call,
+not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time
+and has a prototype.
+.Sp
+\&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call.
+It may be a normal defined scalar, of which the string value will be used.
+Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
+that has been cast to \f(CW\*(C`SV*\*(C'\fR) which has a prototype.  The prototype
+supplied, in whichever form, does not need to match the actual callee
+referenced by the op tree.
+.Sp
+If the argument ops disagree with the prototype, for example by having
+an unacceptable number of arguments, a valid op tree is returned anyway.
+The error is reflected in the parser state, normally resulting in a single
+exception at the top level of parsing which covers all the compilation
+errors that occurred.  In the error message, the callee is referred to
+by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  ck_entersub_args_proto(OP *entersubop, GV *namegv,
+\&                              SV *protosv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ck_entersub_args_proto_or_list""" 4
+.el .IP \f(CWck_entersub_args_proto_or_list\fR 4
+.IX Xref "ck_entersub_args_proto_or_list"
+.IX Item "ck_entersub_args_proto_or_list"
+Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree either
+based on a subroutine prototype or using default list-context processing.
+This is the standard treatment used on a subroutine call, not marked
+with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time.
+.Sp
+\&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call,
+or indicates that there is no prototype.  It may be a normal scalar,
+in which case if it is defined then the string value will be used
+as a prototype, and if it is undefined then there is no prototype.
+Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
+that has been cast to \f(CW\*(C`SV*\*(C'\fR), of which the prototype will be used if it
+has one.  The prototype (or lack thereof) supplied, in whichever form,
+does not need to match the actual callee referenced by the op tree.
+.Sp
+If the argument ops disagree with the prototype, for example by having
+an unacceptable number of arguments, a valid op tree is returned anyway.
+The error is reflected in the parser state, normally resulting in a single
+exception at the top level of parsing which covers all the compilation
+errors that occurred.  In the error message, the callee is referred to
+by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
+\&                                      SV *protosv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_const_sv""" 4
+.el .IP \f(CWcv_const_sv\fR 4
+.IX Xref "cv_const_sv"
+.IX Item "cv_const_sv"
+If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining, returns the constant
+value returned by the sub.  Otherwise, returns \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in
+"Constant Functions" in perlsub.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  cv_const_sv(const CV * const cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_get_call_checker""" 4
+.el .IP \f(CWcv_get_call_checker\fR 4
+.IX Xref "cv_get_call_checker"
+.IX Item "cv_get_call_checker"
+The original form of "cv_get_call_checker_flags", which does not return
+checker flags.  When using a checker function returned by this function,
+it is only safe to call it with a genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
+.RS 4
+.Sp
+.Vb 2
+\& void  cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
+\&                           SV **ckobj_p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_get_call_checker_flags""" 4
+.el .IP \f(CWcv_get_call_checker_flags\fR 4
+.IX Xref "cv_get_call_checker_flags"
+.IX Item "cv_get_call_checker_flags"
+Retrieves the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
+Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
+subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
+at compile time as \f(CW\*(C`cv\*(C'\fR.
+.Sp
+The C\-level function pointer is returned in \f(CW*ckfun_p\fR, an SV argument
+for it is returned in \f(CW*ckobj_p\fR, and control flags are returned in
+\&\f(CW*ckflags_p\fR.  The function is intended to be called in this manner:
+.Sp
+.Vb 1
+\& entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
+.Ve
+.Sp
+In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
+which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
+the name that should be used by the check function to refer
+to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
+It is permitted to apply the check function in non-standard situations,
+such as to a call to a different subroutine or to a method call.
+.Sp
+\&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV.  If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
+bit is clear in \f(CW*ckflags_p\fR, it is permitted to pass a CV or other SV
+instead, anything that can be used as the first argument to "cv_name".
+If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW*ckflags_p\fR then the
+check function requires \f(CW\*(C`namegv\*(C'\fR to be a genuine GV.
+.Sp
+By default, the check function is
+Perl_ck_entersub_args_proto_or_list,
+the SV parameter is \f(CW\*(C`cv\*(C'\fR itself, and the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
+flag is clear.  This implements standard prototype processing.  It can
+be changed, for a particular subroutine, by "cv_set_call_checker_flags".
+.Sp
+If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW\*(C`gflags\*(C'\fR then it
+indicates that the caller only knows about the genuine GV version of
+\&\f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit will always be set in
+\&\f(CW*ckflags_p\fR, regardless of the check function's recorded requirements.
+If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is clear in \f(CW\*(C`gflags\*(C'\fR then it
+indicates the caller knows about the possibility of passing something
+other than a GV as \f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit may
+be either set or clear in \f(CW*ckflags_p\fR, indicating the check function's
+recorded requirements.
+.Sp
+\&\f(CW\*(C`gflags\*(C'\fR is a bitset passed into \f(CW\*(C`cv_get_call_checker_flags\*(C'\fR, in which
+only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit currently has a defined meaning
+(for which see above).  All other bits should be clear.
+.RS 4
+.Sp
+.Vb 3
+\& void  cv_get_call_checker_flags(CV *cv, U32 gflags,
+\&                                 Perl_call_checker *ckfun_p,
+\&                                 SV **ckobj_p, U32 *ckflags_p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_set_call_checker""" 4
+.el .IP \f(CWcv_set_call_checker\fR 4
+.IX Xref "cv_set_call_checker"
+.IX Item "cv_set_call_checker"
+The original form of "cv_set_call_checker_flags", which passes it the
+\&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR flag for backward-compatibility.  The effect
+of that flag setting is that the check function is guaranteed to get a
+genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
+.RS 4
+.Sp
+.Vb 2
+\& void  cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
+\&                           SV *ckobj)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_set_call_checker_flags""" 4
+.el .IP \f(CWcv_set_call_checker_flags\fR 4
+.IX Xref "cv_set_call_checker_flags"
+.IX Item "cv_set_call_checker_flags"
+Sets the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
+Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
+subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
+at compile time as \f(CW\*(C`cv\*(C'\fR.
+.Sp
+The C\-level function pointer is supplied in \f(CW\*(C`ckfun\*(C'\fR, an SV argument for
+it is supplied in \f(CW\*(C`ckobj\*(C'\fR, and control flags are supplied in \f(CW\*(C`ckflags\*(C'\fR.
+The function should be defined like this:
+.Sp
+.Vb 1
+\&    STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
+.Ve
+.Sp
+It is intended to be called in this manner:
+.Sp
+.Vb 1
+\&    entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
+.Ve
+.Sp
+In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
+which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
+the name that should be used by the check function to refer
+to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
+It is permitted to apply the check function in non-standard situations,
+such as to a call to a different subroutine or to a method call.
+.Sp
+\&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV.  For efficiency, perl may pass a
+CV or other SV instead.  Whatever is passed can be used as the first
+argument to "cv_name".  You can force perl to pass a GV by including
+\&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR in the \f(CW\*(C`ckflags\*(C'\fR.
+.Sp
+\&\f(CW\*(C`ckflags\*(C'\fR is a bitset, in which only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
+bit currently has a defined meaning (for which see above).  All other
+bits should be clear.
+.Sp
+The current setting for a particular CV can be retrieved by
+"cv_get_call_checker_flags".
+.RS 4
+.Sp
+.Vb 2
+\& void  cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
+\&                                 SV *ckobj, U32 ckflags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """finalize_optree""" 4
+.el .IP \f(CWfinalize_optree\fR 4
+.IX Xref "finalize_optree"
+.IX Item "finalize_optree"
+This function finalizes the optree.  Should be called directly after
+the complete optree is built.  It does some additional
+checking which can't be done in the normal \f(CW\*(C`ck_\*(C'\fRxxx functions and makes
+the tree thread-safe.
+.RS 4
+.Sp
+.Vb 1
+\& void  finalize_optree(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """forbid_outofblock_ops""" 4
+.el .IP \f(CWforbid_outofblock_ops\fR 4
+.IX Xref "forbid_outofblock_ops"
+.IX Item "forbid_outofblock_ops"
+NOTE: \f(CW\*(C`forbid_outofblock_ops\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Checks an optree that implements a block, to ensure there are no control-flow
+ops that attempt to leave the block.  Any \f(CW\*(C`OP_RETURN\*(C'\fR is forbidden, as is any
+\&\f(CW\*(C`OP_GOTO\*(C'\fR. Loops are analysed, so any LOOPEX op (\f(CW\*(C`OP_NEXT\*(C'\fR, \f(CW\*(C`OP_LAST\*(C'\fR or
+\&\f(CW\*(C`OP_REDO\*(C'\fR) that affects a loop that contains it within the block are
+permitted, but those that do not are forbidden.
+.Sp
+If any of these forbidden constructions are detected, an exception is thrown
+by using the op name and the blockname argument to construct a suitable
+message.
+.Sp
+This function alone is not sufficient to ensure the optree does not perform
+any of these forbidden activities during runtime, as it might call a different
+function that performs a non-local LOOPEX, or a string\-\fBeval()\fR that performs a
+\&\f(CW\*(C`goto\*(C'\fR, or various other things. It is intended purely as a compile-time
+check for those that could be detected statically. Additional runtime checks
+may be required depending on the circumstance it is used for.
+.Sp
+Note currently that \fIall\fR \f(CW\*(C`OP_GOTO\*(C'\fR ops are forbidden, even in cases where
+they might otherwise be safe to execute.  This may be permitted in a later
+version.
+.RS 4
+.Sp
+.Vb 1
+\& void  forbid_outofblock_ops(OP *o, const char *blockname)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LINKLIST""" 4
+.el .IP \f(CWLINKLIST\fR 4
+.IX Xref "LINKLIST"
+.IX Item "LINKLIST"
+Given the root of an optree, link the tree in execution order using the
+\&\f(CW\*(C`op_next\*(C'\fR pointers and return the first op executed.  If this has
+already been done, it will not be redone, and \f(CW\*(C`o\->op_next\*(C'\fR will be
+returned.  If \f(CW\*(C`o\->op_next\*(C'\fR is not already set, \f(CW\*(C`o\*(C'\fR should be at
+least an \f(CW\*(C`UNOP\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP*  LINKLIST(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LISTOP""" 4
+.el .IP \f(CWLISTOP\fR 4
+.IX Item "LISTOP"
+Described in perlguts.
+.ie n .IP """LOGOP""" 4
+.el .IP \f(CWLOGOP\fR 4
+.IX Item "LOGOP"
+Described in perlguts.
+.ie n .IP """LOOP""" 4
+.el .IP \f(CWLOOP\fR 4
+.IX Item "LOOP"
+Described in perlguts.
+.ie n .IP """newARGDEFELEMOP""" 4
+.el .IP \f(CWnewARGDEFELEMOP\fR 4
+.IX Xref "newARGDEFELEMOP"
+.IX Item "newARGDEFELEMOP"
+Constructs and returns a new \f(CW\*(C`OP_ARGDEFELEM\*(C'\fR op which provides a defaulting
+expression given by \f(CW\*(C`expr\*(C'\fR for the signature parameter at the index given
+by \f(CW\*(C`argindex\*(C'\fR. The expression optree is consumed by this function and
+becomes part of the returned optree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newASSIGNOP""" 4
+.el .IP \f(CWnewASSIGNOP\fR 4
+.IX Xref "newASSIGNOP"
+.IX Item "newASSIGNOP"
+Constructs, checks, and returns an assignment op.  \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR
+supply the parameters of the assignment; they are consumed by this
+function and become part of the constructed op tree.
+.Sp
+If \f(CW\*(C`optype\*(C'\fR is \f(CW\*(C`OP_ANDASSIGN\*(C'\fR, \f(CW\*(C`OP_ORASSIGN\*(C'\fR, or \f(CW\*(C`OP_DORASSIGN\*(C'\fR, then
+a suitable conditional optree is constructed.  If \f(CW\*(C`optype\*(C'\fR is the opcode
+of a binary operator, such as \f(CW\*(C`OP_BIT_OR\*(C'\fR, then an op is constructed that
+performs the binary operation and assigns the result to the left argument.
+Either way, if \f(CW\*(C`optype\*(C'\fR is non-zero then \f(CW\*(C`flags\*(C'\fR has no effect.
+.Sp
+If \f(CW\*(C`optype\*(C'\fR is zero, then a plain scalar or list assignment is
+constructed.  Which type of assignment it is is automatically determined.
+\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR
+will be set automatically, and, shifted up eight bits, the eight bits
+of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
+set as required.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newATTRSUB""" 4
+.el .IP \f(CWnewATTRSUB\fR 4
+.IX Xref "newATTRSUB"
+.IX Item "newATTRSUB"
+Construct a Perl subroutine, also performing some surrounding jobs.
+.Sp
+This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter set to
+FALSE.  This means that if \f(CW\*(C`o\*(C'\fR is null, the new sub will be anonymous; otherwise
+the name will be derived from \f(CW\*(C`o\*(C'\fR in the way described (as with all other
+details) in "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
+.RS 4
+.Sp
+.Vb 2
+\& CV *  newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,
+\&                  OP *block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newBINOP""" 4
+.el .IP \f(CWnewBINOP\fR 4
+.IX Xref "newBINOP"
+.IX Item "newBINOP"
+Constructs, checks, and returns an op of any binary type.  \f(CW\*(C`type\*(C'\fR
+is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
+that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
+the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or
+2 is automatically set as required.  \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR supply up to
+two ops to be the direct children of the binary op; they are consumed
+by this function and become part of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newBINOP(I32 type, I32 flags, OP *first, OP *last)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newCONDOP""" 4
+.el .IP \f(CWnewCONDOP\fR 4
+.IX Xref "newCONDOP"
+.IX Item "newCONDOP"
+Constructs, checks, and returns a conditional-expression (\f(CW\*(C`cond_expr\*(C'\fR)
+op.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR
+will be set automatically, and, shifted up eight bits, the eight bits of
+\&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is automatically set.
+\&\f(CW\*(C`first\*(C'\fR supplies the expression selecting between the two branches,
+and \f(CW\*(C`trueop\*(C'\fR and \f(CW\*(C`falseop\*(C'\fR supply the branches; they are consumed by
+this function and become part of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newCONSTSUB""" 4
+.el .IP \f(CWnewCONSTSUB\fR 4
+.IX Xref "newCONSTSUB"
+.IX Item "newCONSTSUB"
+Behaves like "newCONSTSUB_flags", except that \f(CW\*(C`name\*(C'\fR is nul-terminated
+rather than of counted length, and no flags are set.  (This means that
+\&\f(CW\*(C`name\*(C'\fR is always interpreted as Latin\-1.)
+.RS 4
+.Sp
+.Vb 1
+\& CV *  newCONSTSUB(HV *stash, const char *name, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newCONSTSUB_flags""" 4
+.el .IP \f(CWnewCONSTSUB_flags\fR 4
+.IX Xref "newCONSTSUB_flags"
+.IX Item "newCONSTSUB_flags"
+Construct a constant subroutine, also performing some surrounding
+jobs.  A scalar constant-valued subroutine is eligible for inlining
+at compile-time, and in Perl code can be created by \f(CW\*(C`sub\ FOO\ ()\ {\ 123\ }\*(C'\fR.  Other kinds of constant subroutine have other treatment.
+.Sp
+The subroutine will have an empty prototype and will ignore any arguments
+when called.  Its constant behaviour is determined by \f(CW\*(C`sv\*(C'\fR.  If \f(CW\*(C`sv\*(C'\fR
+is null, the subroutine will yield an empty list.  If \f(CW\*(C`sv\*(C'\fR points to a
+scalar, the subroutine will always yield that scalar.  If \f(CW\*(C`sv\*(C'\fR points
+to an array, the subroutine will always yield a list of the elements of
+that array in list context, or the number of elements in the array in
+scalar context.  This function takes ownership of one counted reference
+to the scalar or array, and will arrange for the object to live as long
+as the subroutine does.  If \f(CW\*(C`sv\*(C'\fR points to a scalar then the inlining
+assumes that the value of the scalar will never change, so the caller
+must ensure that the scalar is not subsequently written to.  If \f(CW\*(C`sv\*(C'\fR
+points to an array then no such assumption is made, so it is ostensibly
+safe to mutate the array or its elements, but whether this is really
+supported has not been determined.
+.Sp
+The subroutine will have \f(CW\*(C`CvFILE\*(C'\fR set according to \f(CW\*(C`PL_curcop\*(C'\fR.
+Other aspects of the subroutine will be left in their default state.
+The caller is free to mutate the subroutine beyond its initial state
+after this function has returned.
+.Sp
+If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its
+\&\f(CW\*(C`CvGV\*(C'\fR referring to an \f(CW\*(C`_\|_ANON_\|_\*(C'\fR glob.  If \f(CW\*(C`name\*(C'\fR is non-null then the
+subroutine will be named accordingly, referenced by the appropriate glob.
+\&\f(CW\*(C`name\*(C'\fR is a string of length \f(CW\*(C`len\*(C'\fR bytes giving a sigilless symbol
+name, in UTF\-8 if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SVf_UTF8\*(C'\fR bit set and in Latin\-1
+otherwise.  The name may be either qualified or unqualified.  If the
+name is unqualified then it defaults to being in the stash specified by
+\&\f(CW\*(C`stash\*(C'\fR if that is non-null, or to \f(CW\*(C`PL_curstash\*(C'\fR if \f(CW\*(C`stash\*(C'\fR is null.
+The symbol is always added to the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR
+semantics.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR should not have bits set other than \f(CW\*(C`SVf_UTF8\*(C'\fR.
+.Sp
+If there is already a subroutine of the specified name, then the new sub
+will replace the existing one in the glob.  A warning may be generated
+about the redefinition.
+.Sp
+If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
+\&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
+running of phase-related subroutines.  In this case the relevant glob will
+be left not containing any subroutine, even if it did contain one before.
+Execution of the subroutine will likely be a no-op, unless \f(CW\*(C`sv\*(C'\fR was
+a tied array or the caller modified the subroutine in some interesting
+way before it was executed.  In the case of \f(CW\*(C`BEGIN\*(C'\fR, the treatment is
+buggy: the sub will be executed when only half built, and may be deleted
+prematurely, possibly causing a crash.
+.Sp
+The function returns a pointer to the constructed subroutine.  If the sub
+is anonymous then ownership of one counted reference to the subroutine
+is transferred to the caller.  If the sub is named then the caller does
+not get ownership of a reference.  In most such cases, where the sub
+has a non-phase name, the sub will be alive at the point it is returned
+by virtue of being contained in the glob that names it.  A phase-named
+subroutine will usually be alive by virtue of the reference owned by
+the phase's automatic run queue.  A \f(CW\*(C`BEGIN\*(C'\fR subroutine may have been
+destroyed already by the time this function returns, but currently bugs
+occur in that case before the caller gets control.  It is the caller's
+responsibility to ensure that it knows which of these situations applies.
+.RS 4
+.Sp
+.Vb 2
+\& CV *  newCONSTSUB_flags(HV *stash, const char *name, STRLEN len,
+\&                         U32 flags, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newDEFEROP""" 4
+.el .IP \f(CWnewDEFEROP\fR 4
+.IX Xref "newDEFEROP"
+.IX Item "newDEFEROP"
+NOTE: \f(CW\*(C`newDEFEROP\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Constructs and returns a deferred-block statement that implements the
+\&\f(CW\*(C`defer\*(C'\fR semantics.  The \f(CW\*(C`block\*(C'\fR optree is consumed by this function and
+becomes part of the returned optree.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR argument carries additional flags to set on the returned op,
+including the \f(CW\*(C`op_private\*(C'\fR field.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newDEFEROP(I32 flags, OP *block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newDEFSVOP""" 4
+.el .IP \f(CWnewDEFSVOP\fR 4
+.IX Xref "newDEFSVOP"
+.IX Item "newDEFSVOP"
+Constructs and returns an op to access \f(CW$_\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newDEFSVOP()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newFOROP""" 4
+.el .IP \f(CWnewFOROP\fR 4
+.IX Xref "newFOROP"
+.IX Item "newFOROP"
+Constructs, checks, and returns an op tree expressing a \f(CW\*(C`foreach\*(C'\fR
+loop (iteration through a list of values).  This is a heavyweight loop,
+with structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR and suchlike.
+.Sp
+\&\f(CW\*(C`sv\*(C'\fR optionally supplies the variable(s) that will be aliased to each
+item in turn; if null, it defaults to \f(CW$_\fR.
+\&\f(CW\*(C`expr\*(C'\fR supplies the list of values to iterate over.  \f(CW\*(C`block\*(C'\fR supplies
+the main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR
+block that operates as a second half of the body.  All of these optree
+inputs are consumed by this function and become part of the constructed
+op tree.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR
+op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
+the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
+automatically.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newGIVENOP""" 4
+.el .IP \f(CWnewGIVENOP\fR 4
+.IX Xref "newGIVENOP"
+.IX Item "newGIVENOP"
+Constructs, checks, and returns an op tree expressing a \f(CW\*(C`given\*(C'\fR block.
+\&\f(CW\*(C`cond\*(C'\fR supplies the expression to whose value \f(CW$_\fR will be locally
+aliased, and \f(CW\*(C`block\*(C'\fR supplies the body of the \f(CW\*(C`given\*(C'\fR construct; they
+are consumed by this function and become part of the constructed op tree.
+\&\f(CW\*(C`defsv_off\*(C'\fR must be zero (it used to identity the pad slot of lexical \f(CW$_\fR).
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newGVOP""" 4
+.el .IP \f(CWnewGVOP\fR 4
+.IX Xref "newGVOP"
+.IX Item "newGVOP"
+Constructs, checks, and returns an op of any type that involves an
+embedded reference to a GV.  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the
+eight bits of \f(CW\*(C`op_flags\*(C'\fR.  \f(CW\*(C`gv\*(C'\fR identifies the GV that the op should
+reference; calling this function does not transfer ownership of any
+reference to it.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newGVOP(I32 type, I32 flags, GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newLISTOP""" 4
+.el .IP \f(CWnewLISTOP\fR 4
+.IX Xref "newLISTOP"
+.IX Item "newLISTOP"
+Constructs, checks, and returns an op of any list type.  \f(CW\*(C`type\*(C'\fR is
+the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
+\&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required.  \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR
+supply up to two ops to be direct children of the list op; they are
+consumed by this function and become part of the constructed op tree.
+.Sp
+For most list operators, the check function expects all the kid ops to be
+present already, so calling \f(CW\*(C`newLISTOP(OP_JOIN, ...)\*(C'\fR (e.g.) is not
+appropriate.  What you want to do in that case is create an op of type
+\&\f(CW\*(C`OP_LIST\*(C'\fR, append more children to it, and then call "op_convert_list".
+See "op_convert_list" for more information.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newLISTOP(I32 type, I32 flags, OP *first, OP *last)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newLOGOP""" 4
+.el .IP \f(CWnewLOGOP\fR 4
+.IX Xref "newLOGOP"
+.IX Item "newLOGOP"
+Constructs, checks, and returns a logical (flow control) op.  \f(CW\*(C`type\*(C'\fR
+is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
+that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
+the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is
+automatically set.  \f(CW\*(C`first\*(C'\fR supplies the expression controlling the
+flow, and \f(CW\*(C`other\*(C'\fR supplies the side (alternate) chain of ops; they are
+consumed by this function and become part of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newLOOPEX""" 4
+.el .IP \f(CWnewLOOPEX\fR 4
+.IX Xref "newLOOPEX"
+.IX Item "newLOOPEX"
+Constructs, checks, and returns a loop-exiting op (such as \f(CW\*(C`goto\*(C'\fR
+or \f(CW\*(C`last\*(C'\fR).  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`label\*(C'\fR supplies the parameter
+determining the target of the op; it is consumed by this function and
+becomes part of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newLOOPEX(I32 type, OP *label)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newLOOPOP""" 4
+.el .IP \f(CWnewLOOPOP\fR 4
+.IX Xref "newLOOPOP"
+.IX Item "newLOOPOP"
+Constructs, checks, and returns an op tree expressing a loop.  This is
+only a loop in the control flow through the op tree; it does not have
+the heavyweight loop structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR
+and suchlike.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the
+top-level op, except that some bits will be set automatically as required.
+\&\f(CW\*(C`expr\*(C'\fR supplies the expression controlling loop iteration, and \f(CW\*(C`block\*(C'\fR
+supplies the body of the loop; they are consumed by this function and
+become part of the constructed op tree.  \f(CW\*(C`debuggable\*(C'\fR is currently
+unused and should always be 1.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newMETHOP""" 4
+.el .IP \f(CWnewMETHOP\fR 4
+.IX Xref "newMETHOP"
+.IX Item "newMETHOP"
+Constructs, checks, and returns an op of method type with a method name
+evaluated at runtime.  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight
+bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically,
+and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that
+the bit with value 1 is automatically set.  \f(CW\*(C`dynamic_meth\*(C'\fR supplies an
+op which evaluates method name; it is consumed by this function and
+become part of the constructed op tree.
+Supported optypes: \f(CW\*(C`OP_METHOD\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newMETHOP(I32 type, I32 flags, OP *dynamic_meth)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newMETHOP_named""" 4
+.el .IP \f(CWnewMETHOP_named\fR 4
+.IX Xref "newMETHOP_named"
+.IX Item "newMETHOP_named"
+Constructs, checks, and returns an op of method type with a constant
+method name.  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of
+\&\f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits of
+\&\f(CW\*(C`op_private\*(C'\fR.  \f(CW\*(C`const_meth\*(C'\fR supplies a constant method name;
+it must be a shared COW string.
+Supported optypes: \f(CW\*(C`OP_METHOD_NAMED\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newMETHOP_named(I32 type, I32 flags, SV * const_meth)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newNULLLIST""" 4
+.el .IP \f(CWnewNULLLIST\fR 4
+.IX Xref "newNULLLIST"
+.IX Item "newNULLLIST"
+Constructs, checks, and returns a new \f(CW\*(C`stub\*(C'\fR op, which represents an
+empty list expression.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newNULLLIST()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newOP""" 4
+.el .IP \f(CWnewOP\fR 4
+.IX Xref "newOP"
+.IX Item "newOP"
+Constructs, checks, and returns an op of any base type (any type that
+has no extra fields).  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the
+eight bits of \f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits
+of \f(CW\*(C`op_private\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newOP(I32 optype, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPADOP""" 4
+.el .IP \f(CWnewPADOP\fR 4
+.IX Xref "newPADOP"
+.IX Item "newPADOP"
+Constructs, checks, and returns an op of any type that involves a
+reference to a pad element.  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the
+eight bits of \f(CW\*(C`op_flags\*(C'\fR.  A pad slot is automatically allocated, and
+is populated with \f(CW\*(C`sv\*(C'\fR; this function takes ownership of one reference
+to it.
+.Sp
+This function only exists if Perl has been compiled to use ithreads.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newPADOP(I32 type, I32 flags, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPMOP""" 4
+.el .IP \f(CWnewPMOP\fR 4
+.IX Xref "newPMOP"
+.IX Item "newPMOP"
+Constructs, checks, and returns an op of any pattern matching type.
+\&\f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR
+and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newPMOP(I32 type, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPVOP""" 4
+.el .IP \f(CWnewPVOP\fR 4
+.IX Xref "newPVOP"
+.IX Item "newPVOP"
+Constructs, checks, and returns an op of any type that involves an
+embedded C\-level pointer (PV).  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives
+the eight bits of \f(CW\*(C`op_flags\*(C'\fR.  \f(CW\*(C`pv\*(C'\fR supplies the C\-level pointer.
+Depending on the op type, the memory referenced by \f(CW\*(C`pv\*(C'\fR may be freed
+when the op is destroyed.  If the op is of a freeing type, \f(CW\*(C`pv\*(C'\fR must
+have been allocated using \f(CW\*(C`PerlMemShared_malloc\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newPVOP(I32 type, I32 flags, char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newRANGE""" 4
+.el .IP \f(CWnewRANGE\fR 4
+.IX Xref "newRANGE"
+.IX Item "newRANGE"
+Constructs and returns a \f(CW\*(C`range\*(C'\fR op, with subordinate \f(CW\*(C`flip\*(C'\fR and
+\&\f(CW\*(C`flop\*(C'\fR ops.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the
+\&\f(CW\*(C`flip\*(C'\fR op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR
+for both the \f(CW\*(C`flip\*(C'\fR and \f(CW\*(C`range\*(C'\fR ops, except that the bit with value
+1 is automatically set.  \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR supply the expressions
+controlling the endpoints of the range; they are consumed by this function
+and become part of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newRANGE(I32 flags, OP *left, OP *right)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSLICEOP""" 4
+.el .IP \f(CWnewSLICEOP\fR 4
+.IX Xref "newSLICEOP"
+.IX Item "newSLICEOP"
+Constructs, checks, and returns an \f(CW\*(C`lslice\*(C'\fR (list slice) op.  \f(CW\*(C`flags\*(C'\fR
+gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will
+be set automatically, and, shifted up eight bits, the eight bits of
+\&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
+set as required.  \f(CW\*(C`listval\*(C'\fR and \f(CW\*(C`subscript\*(C'\fR supply the parameters of
+the slice; they are consumed by this function and become part of the
+constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newSLICEOP(I32 flags, OP *subscript, OP *listop)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSTATEOP""" 4
+.el .IP \f(CWnewSTATEOP\fR 4
+.IX Xref "newSTATEOP"
+.IX Item "newSTATEOP"
+Constructs a state op (COP).  The state op is normally a \f(CW\*(C`nextstate\*(C'\fR op,
+but will be a \f(CW\*(C`dbstate\*(C'\fR op if debugging is enabled for currently-compiled
+code.  The state op is populated from \f(CW\*(C`PL_curcop\*(C'\fR (or \f(CW\*(C`PL_compiling\*(C'\fR).
+If \f(CW\*(C`label\*(C'\fR is non-null, it supplies the name of a label to attach to
+the state op; this function takes ownership of the memory pointed at by
+\&\f(CW\*(C`label\*(C'\fR, and will free it.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR
+for the state op.
+.Sp
+If \f(CW\*(C`o\*(C'\fR is null, the state op is returned.  Otherwise the state op is
+combined with \f(CW\*(C`o\*(C'\fR into a \f(CW\*(C`lineseq\*(C'\fR list op, which is returned.  \f(CW\*(C`o\*(C'\fR
+is consumed by this function and becomes part of the returned op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newSTATEOP(I32 flags, char *label, OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSUB""" 4
+.el .IP \f(CWnewSUB\fR 4
+.IX Xref "newSUB"
+.IX Item "newSUB"
+Like \f(CW"newATTRSUB"\fR, but without attributes.
+.RS 4
+.Sp
+.Vb 1
+\& CV *  newSUB(I32 floor, OP *o, OP *proto, OP *block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVOP""" 4
+.el .IP \f(CWnewSVOP\fR 4
+.IX Xref "newSVOP"
+.IX Item "newSVOP"
+Constructs, checks, and returns an op of any type that involves an
+embedded SV.  \f(CW\*(C`type\*(C'\fR is the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits
+of \f(CW\*(C`op_flags\*(C'\fR.  \f(CW\*(C`sv\*(C'\fR gives the SV to embed in the op; this function
+takes ownership of one reference to it.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newSVOP(I32 type, I32 flags, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newTRYCATCHOP""" 4
+.el .IP \f(CWnewTRYCATCHOP\fR 4
+.IX Xref "newTRYCATCHOP"
+.IX Item "newTRYCATCHOP"
+NOTE: \f(CW\*(C`newTRYCATCHOP\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Constructs and returns a conditional execution statement that implements
+the \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR semantics.  First the op tree in \f(CW\*(C`tryblock\*(C'\fR is executed,
+inside a context that traps exceptions.  If an exception occurs then the
+optree in \f(CW\*(C`catchblock\*(C'\fR is executed, with the trapped exception set into the
+lexical variable given by \f(CW\*(C`catchvar\*(C'\fR (which must be an op of type
+\&\f(CW\*(C`OP_PADSV\*(C'\fR).  All the optrees are consumed by this function and become part
+of the returned op tree.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR argument is currently ignored.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar,
+\&                     OP *catchblock)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newUNOP""" 4
+.el .IP \f(CWnewUNOP\fR 4
+.IX Xref "newUNOP"
+.IX Item "newUNOP"
+Constructs, checks, and returns an op of any unary type.  \f(CW\*(C`type\*(C'\fR is
+the opcode.  \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
+\&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required, and, shifted up eight
+bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1
+is automatically set.  \f(CW\*(C`first\*(C'\fR supplies an optional op to be the direct
+child of the unary op; it is consumed by this function and become part
+of the constructed op tree.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newUNOP(I32 type, I32 flags, OP *first)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newUNOP_AUX""" 4
+.el .IP \f(CWnewUNOP_AUX\fR 4
+.IX Xref "newUNOP_AUX"
+.IX Item "newUNOP_AUX"
+Similar to \f(CW\*(C`newUNOP\*(C'\fR, but creates an \f(CW\*(C`UNOP_AUX\*(C'\fR struct instead, with \f(CW\*(C`op_aux\*(C'\fR
+initialised to \f(CW\*(C`aux\*(C'\fR
+.RS 4
+.Sp
+.Vb 2
+\& OP *  newUNOP_AUX(I32 type, I32 flags, OP *first,
+\&                   UNOP_AUX_item *aux)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newWHENOP""" 4
+.el .IP \f(CWnewWHENOP\fR 4
+.IX Xref "newWHENOP"
+.IX Item "newWHENOP"
+Constructs, checks, and returns an op tree expressing a \f(CW\*(C`when\*(C'\fR block.
+\&\f(CW\*(C`cond\*(C'\fR supplies the test expression, and \f(CW\*(C`block\*(C'\fR supplies the block
+that will be executed if the test evaluates to true; they are consumed
+by this function and become part of the constructed op tree.  \f(CW\*(C`cond\*(C'\fR
+will be interpreted DWIMically, often as a comparison against \f(CW$_\fR,
+and may be null to generate a \f(CW\*(C`default\*(C'\fR block.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newWHENOP(OP *cond, OP *block)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newWHILEOP""" 4
+.el .IP \f(CWnewWHILEOP\fR 4
+.IX Xref "newWHILEOP"
+.IX Item "newWHILEOP"
+Constructs, checks, and returns an op tree expressing a \f(CW\*(C`while\*(C'\fR loop.
+This is a heavyweight loop, with structure that allows exiting the loop
+by \f(CW\*(C`last\*(C'\fR and suchlike.
+.Sp
+\&\f(CW\*(C`loop\*(C'\fR is an optional preconstructed \f(CW\*(C`enterloop\*(C'\fR op to use in the
+loop; if it is null then a suitable op will be constructed automatically.
+\&\f(CW\*(C`expr\*(C'\fR supplies the loop's controlling expression.  \f(CW\*(C`block\*(C'\fR supplies the
+main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR block
+that operates as a second half of the body.  All of these optree inputs
+are consumed by this function and become part of the constructed op tree.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR
+op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
+the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
+automatically.  \f(CW\*(C`debuggable\*(C'\fR is currently unused and should always be 1.
+\&\f(CW\*(C`has_my\*(C'\fR can be supplied as true to force the
+loop body to be enclosed in its own scope.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr,
+\&                  OP *block, OP *cont, I32 has_my)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newXS""" 4
+.el .IP \f(CWnewXS\fR 4
+.IX Xref "newXS"
+.IX Item "newXS"
+Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs.  \f(CW\*(C`filename\*(C'\fR needs to be
+static storage, as it is used directly as \fBCvFILE()\fR, without a copy being made.
+.ie n .IP """OA_BASEOP""" 4
+.el .IP \f(CWOA_BASEOP\fR 4
+.IX Item "OA_BASEOP"
+.PD 0
+.ie n .IP """OA_BINOP""" 4
+.el .IP \f(CWOA_BINOP\fR 4
+.IX Item "OA_BINOP"
+.ie n .IP """OA_COP""" 4
+.el .IP \f(CWOA_COP\fR 4
+.IX Item "OA_COP"
+.ie n .IP """OA_LISTOP""" 4
+.el .IP \f(CWOA_LISTOP\fR 4
+.IX Item "OA_LISTOP"
+.ie n .IP """OA_LOGOP""" 4
+.el .IP \f(CWOA_LOGOP\fR 4
+.IX Item "OA_LOGOP"
+.ie n .IP """OA_LOOP""" 4
+.el .IP \f(CWOA_LOOP\fR 4
+.IX Item "OA_LOOP"
+.ie n .IP """OA_PADOP""" 4
+.el .IP \f(CWOA_PADOP\fR 4
+.IX Item "OA_PADOP"
+.ie n .IP """OA_PMOP""" 4
+.el .IP \f(CWOA_PMOP\fR 4
+.IX Item "OA_PMOP"
+.ie n .IP """OA_PVOP_OR_SVOP""" 4
+.el .IP \f(CWOA_PVOP_OR_SVOP\fR 4
+.IX Item "OA_PVOP_OR_SVOP"
+.ie n .IP """OA_SVOP""" 4
+.el .IP \f(CWOA_SVOP\fR 4
+.IX Item "OA_SVOP"
+.ie n .IP """OA_UNOP""" 4
+.el .IP \f(CWOA_UNOP\fR 4
+.IX Item "OA_UNOP"
+.PD
+Described in perlguts.
+.ie n .IP """OP""" 4
+.el .IP \f(CWOP\fR 4
+.IX Item "OP"
+Described in perlguts.
+.ie n .IP """op_append_elem""" 4
+.el .IP \f(CWop_append_elem\fR 4
+.IX Xref "op_append_elem"
+.IX Item "op_append_elem"
+Append an item to the list of ops contained directly within a list-type
+op, returning the lengthened list.  \f(CW\*(C`first\*(C'\fR is the list-type op,
+and \f(CW\*(C`last\*(C'\fR is the op to append to the list.  \f(CW\*(C`optype\*(C'\fR specifies the
+intended opcode for the list.  If \f(CW\*(C`first\*(C'\fR is not already a list of the
+right type, it will be upgraded into one.  If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR
+is null, the other is returned unchanged.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_append_elem(I32 optype, OP *first, OP *last)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_append_list""" 4
+.el .IP \f(CWop_append_list\fR 4
+.IX Xref "op_append_list"
+.IX Item "op_append_list"
+Concatenate the lists of ops contained directly within two list-type ops,
+returning the combined list.  \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR are the list-type ops
+to concatenate.  \f(CW\*(C`optype\*(C'\fR specifies the intended opcode for the list.
+If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
+it will be upgraded into one.  If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
+the other is returned unchanged.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_append_list(I32 optype, OP *first, OP *last)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OP_CLASS""" 4
+.el .IP \f(CWOP_CLASS\fR 4
+.IX Xref "OP_CLASS"
+.IX Item "OP_CLASS"
+Return the class of the provided OP: that is, which of the *OP
+structures it uses.  For core ops this currently gets the information out
+of \f(CW\*(C`PL_opargs\*(C'\fR, which does not always accurately reflect the type used;
+in v5.26 onwards, see also the function \f(CW"op_class"\fR which can do a better
+job of determining the used type.
+.Sp
+For custom ops the type is returned from the registration, and it is up
+to the registree to ensure it is accurate.  The value returned will be
+one of the \f(CW\*(C`OA_\*(C'\fR* constants from \fIop.h\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  OP_CLASS(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_contextualize""" 4
+.el .IP \f(CWop_contextualize\fR 4
+.IX Xref "op_contextualize"
+.IX Item "op_contextualize"
+Applies a syntactic context to an op tree representing an expression.
+\&\f(CW\*(C`o\*(C'\fR is the op tree, and \f(CW\*(C`context\*(C'\fR must be \f(CW\*(C`G_SCALAR\*(C'\fR, \f(CW\*(C`G_LIST\*(C'\fR,
+or \f(CW\*(C`G_VOID\*(C'\fR to specify the context to apply.  The modified op tree
+is returned.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_contextualize(OP *o, I32 context)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_convert_list""" 4
+.el .IP \f(CWop_convert_list\fR 4
+.IX Xref "op_convert_list"
+.IX Item "op_convert_list"
+Converts \f(CW\*(C`o\*(C'\fR into a list op if it is not one already, and then converts it
+into the specified \f(CW\*(C`type\*(C'\fR, calling its check function, allocating a target if
+it needs one, and folding constants.
+.Sp
+A list-type op is usually constructed one kid at a time via \f(CW\*(C`newLISTOP\*(C'\fR,
+\&\f(CW\*(C`op_prepend_elem\*(C'\fR and \f(CW\*(C`op_append_elem\*(C'\fR.  Then finally it is passed to
+\&\f(CW\*(C`op_convert_list\*(C'\fR to make it the right type.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_convert_list(I32 optype, I32 flags, OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OP_DESC""" 4
+.el .IP \f(CWOP_DESC\fR 4
+.IX Xref "OP_DESC"
+.IX Item "OP_DESC"
+Return a short description of the provided OP.
+.RS 4
+.Sp
+.Vb 1
+\& const char *  OP_DESC(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_force_list""" 4
+.el .IP \f(CWop_force_list\fR 4
+.IX Xref "op_force_list"
+.IX Item "op_force_list"
+Promotes o and any siblings to be an \f(CW\*(C`OP_LIST\*(C'\fR if it is not already. If
+a new \f(CW\*(C`OP_LIST\*(C'\fR op was created, its first child will be \f(CW\*(C`OP_PUSHMARK\*(C'\fR.
+The returned node itself will be nulled, leaving only its children.
+.Sp
+This is often what you want to do before putting the optree into list
+context; as
+.Sp
+.Vb 1
+\&    o = op_contextualize(op_force_list(o), G_LIST);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_force_list(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_free""" 4
+.el .IP \f(CWop_free\fR 4
+.IX Xref "op_free"
+.IX Item "op_free"
+Free an op and its children. Only use this when an op is no longer linked
+to from any optree.
+.Sp
+Remember that any op with \f(CW\*(C`OPf_KIDS\*(C'\fR set is expected to have a valid
+\&\f(CW\*(C`op_first\*(C'\fR pointer.  If you are attempting to free an op but preserve its
+child op, make sure to clear that flag before calling \f(CWop_free()\fR.  For
+example:
+.Sp
+.Vb 3
+\&    OP *kid = o\->op_first; o\->op_first = NULL;
+\&    o\->op_flags &= ~OPf_KIDS;
+\&    op_free(o);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  op_free(OP *arg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OpHAS_SIBLING""" 4
+.el .IP \f(CWOpHAS_SIBLING\fR 4
+.IX Xref "OpHAS_SIBLING"
+.IX Item "OpHAS_SIBLING"
+Returns true if \f(CW\*(C`o\*(C'\fR has a sibling
+.RS 4
+.Sp
+.Vb 1
+\& bool  OpHAS_SIBLING(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OpLASTSIB_set""" 4
+.el .IP \f(CWOpLASTSIB_set\fR 4
+.IX Xref "OpLASTSIB_set"
+.IX Item "OpLASTSIB_set"
+Marks \f(CW\*(C`o\*(C'\fR as having no further siblings and marks
+o as having the specified parent. See also \f(CW"OpMORESIB_set"\fR and
+\&\f(CW\*(C`OpMAYBESIB_set\*(C'\fR. For a higher-level interface, see
+\&\f(CW"op_sibling_splice"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  OpLASTSIB_set(OP *o, OP *parent)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_linklist""" 4
+.el .IP \f(CWop_linklist\fR 4
+.IX Xref "op_linklist"
+.IX Item "op_linklist"
+This function is the implementation of the "LINKLIST" macro.  It should
+not be called directly.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_linklist(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_lvalue""" 4
+.el .IP \f(CWop_lvalue\fR 4
+.IX Xref "op_lvalue"
+.IX Item "op_lvalue"
+NOTE: \f(CW\*(C`op_lvalue\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Propagate lvalue ("modifiable") context to an op and its children.
+\&\f(CW\*(C`type\*(C'\fR represents the context type, roughly based on the type of op that
+would do the modifying, although \f(CWlocal()\fR is represented by \f(CW\*(C`OP_NULL\*(C'\fR,
+because it has no op type of its own (it is signalled by a flag on
+the lvalue op).
+.Sp
+This function detects things that can't be modified, such as \f(CW\*(C`$x+1\*(C'\fR, and
+generates errors for them.  For example, \f(CW\*(C`$x+1 = 2\*(C'\fR would cause it to be
+called with an op of type \f(CW\*(C`OP_ADD\*(C'\fR and a \f(CW\*(C`type\*(C'\fR argument of \f(CW\*(C`OP_SASSIGN\*(C'\fR.
+.Sp
+It also flags things that need to behave specially in an lvalue context,
+such as \f(CW\*(C`$$x = 5\*(C'\fR which might have to vivify a reference in \f(CW$x\fR.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_lvalue(OP *o, I32 type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OpMAYBESIB_set""" 4
+.el .IP \f(CWOpMAYBESIB_set\fR 4
+.IX Xref "OpMAYBESIB_set"
+.IX Item "OpMAYBESIB_set"
+Conditionally does \f(CW\*(C`OpMORESIB_set\*(C'\fR or \f(CW\*(C`OpLASTSIB_set\*(C'\fR depending on whether
+\&\f(CW\*(C`sib\*(C'\fR is non-null. For a higher-level interface, see \f(CW"op_sibling_splice"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OpMORESIB_set""" 4
+.el .IP \f(CWOpMORESIB_set\fR 4
+.IX Xref "OpMORESIB_set"
+.IX Item "OpMORESIB_set"
+Sets the sibling of \f(CW\*(C`o\*(C'\fR to the non-zero value \f(CW\*(C`sib\*(C'\fR. See also \f(CW"OpLASTSIB_set"\fR
+and \f(CW"OpMAYBESIB_set"\fR. For a higher-level interface, see
+\&\f(CW"op_sibling_splice"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  OpMORESIB_set(OP *o, OP *sib)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OP_NAME""" 4
+.el .IP \f(CWOP_NAME\fR 4
+.IX Xref "OP_NAME"
+.IX Item "OP_NAME"
+Return the name of the provided OP.  For core ops this looks up the name
+from the op_type; for custom ops from the op_ppaddr.
+.RS 4
+.Sp
+.Vb 1
+\& const char *  OP_NAME(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_null""" 4
+.el .IP \f(CWop_null\fR 4
+.IX Xref "op_null"
+.IX Item "op_null"
+Neutralizes an op when it is no longer needed, but is still linked to from
+other ops.
+.RS 4
+.Sp
+.Vb 1
+\& void  op_null(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_parent""" 4
+.el .IP \f(CWop_parent\fR 4
+.IX Xref "op_parent"
+.IX Item "op_parent"
+Returns the parent OP of \f(CW\*(C`o\*(C'\fR, if it has a parent. Returns \f(CW\*(C`NULL\*(C'\fR otherwise.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_parent(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_prepend_elem""" 4
+.el .IP \f(CWop_prepend_elem\fR 4
+.IX Xref "op_prepend_elem"
+.IX Item "op_prepend_elem"
+Prepend an item to the list of ops contained directly within a list-type
+op, returning the lengthened list.  \f(CW\*(C`first\*(C'\fR is the op to prepend to the
+list, and \f(CW\*(C`last\*(C'\fR is the list-type op.  \f(CW\*(C`optype\*(C'\fR specifies the intended
+opcode for the list.  If \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
+it will be upgraded into one.  If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
+the other is returned unchanged.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_prepend_elem(I32 optype, OP *first, OP *last)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_scope""" 4
+.el .IP \f(CWop_scope\fR 4
+.IX Xref "op_scope"
+.IX Item "op_scope"
+NOTE: \f(CW\*(C`op_scope\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Wraps up an op tree with some additional ops so that at runtime a dynamic
+scope will be created.  The original ops run in the new dynamic scope,
+and then, provided that they exit normally, the scope will be unwound.
+The additional ops used to create and unwind the dynamic scope will
+normally be an \f(CW\*(C`enter\*(C'\fR/\f(CW\*(C`leave\*(C'\fR pair, but a \f(CW\*(C`scope\*(C'\fR op may be used
+instead if the ops are simple enough to not need the full dynamic scope
+structure.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_scope(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OpSIBLING""" 4
+.el .IP \f(CWOpSIBLING\fR 4
+.IX Xref "OpSIBLING"
+.IX Item "OpSIBLING"
+Returns the sibling of \f(CW\*(C`o\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if there is no sibling
+.RS 4
+.Sp
+.Vb 1
+\& OP*  OpSIBLING(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_sibling_splice""" 4
+.el .IP \f(CWop_sibling_splice\fR 4
+.IX Xref "op_sibling_splice"
+.IX Item "op_sibling_splice"
+A general function for editing the structure of an existing chain of
+op_sibling nodes.  By analogy with the perl-level \f(CWsplice()\fR function, allows
+you to delete zero or more sequential nodes, replacing them with zero or
+more different nodes.  Performs the necessary op_first/op_last
+housekeeping on the parent node and op_sibling manipulation on the
+children.  The last deleted node will be marked as the last node by
+updating the op_sibling/op_sibparent or op_moresib field as appropriate.
+.Sp
+Note that op_next is not manipulated, and nodes are not freed; that is the
+responsibility of the caller.  It also won't create a new list op for an
+empty list etc; use higher-level functions like \fBop_append_elem()\fR for that.
+.Sp
+\&\f(CW\*(C`parent\*(C'\fR is the parent node of the sibling chain. It may passed as \f(CW\*(C`NULL\*(C'\fR if
+the splicing doesn't affect the first or last op in the chain.
+.Sp
+\&\f(CW\*(C`start\*(C'\fR is the node preceding the first node to be spliced.  Node(s)
+following it will be deleted, and ops will be inserted after it.  If it is
+\&\f(CW\*(C`NULL\*(C'\fR, the first node onwards is deleted, and nodes are inserted at the
+beginning.
+.Sp
+\&\f(CW\*(C`del_count\*(C'\fR is the number of nodes to delete.  If zero, no nodes are deleted.
+If \-1 or greater than or equal to the number of remaining kids, all
+remaining kids are deleted.
+.Sp
+\&\f(CW\*(C`insert\*(C'\fR is the first of a chain of nodes to be inserted in place of the nodes.
+If \f(CW\*(C`NULL\*(C'\fR, no nodes are inserted.
+.Sp
+The head of the chain of deleted ops is returned, or \f(CW\*(C`NULL\*(C'\fR if no ops were
+deleted.
+.Sp
+For example:
+.Sp
+.Vb 2
+\&    action                    before      after         returns
+\&    \-\-\-\-\-\-                    \-\-\-\-\-       \-\-\-\-\-         \-\-\-\-\-\-\-
+\&
+\&                              P           P
+\&    splice(P, A, 2, X\-Y\-Z)    |           |             B\-C
+\&                              A\-B\-C\-D     A\-X\-Y\-Z\-D
+\&
+\&                              P           P
+\&    splice(P, NULL, 1, X\-Y)   |           |             A
+\&                              A\-B\-C\-D     X\-Y\-B\-C\-D
+\&
+\&                              P           P
+\&    splice(P, NULL, 3, NULL)  |           |             A\-B\-C
+\&                              A\-B\-C\-D     D
+\&
+\&                              P           P
+\&    splice(P, B, 0, X\-Y)      |           |             NULL
+\&                              A\-B\-C\-D     A\-B\-X\-Y\-C\-D
+.Ve
+.Sp
+For lower-level direct manipulation of \f(CW\*(C`op_sibparent\*(C'\fR and \f(CW\*(C`op_moresib\*(C'\fR,
+see \f(CW"OpMORESIB_set"\fR, \f(CW"OpLASTSIB_set"\fR, \f(CW"OpMAYBESIB_set"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  op_sibling_splice(OP *parent, OP *start, int del_count,
+\&                         OP *insert)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """optimize_optree""" 4
+.el .IP \f(CWoptimize_optree\fR 4
+.IX Xref "optimize_optree"
+.IX Item "optimize_optree"
+This function applies some optimisations to the optree in top-down order.
+It is called before the peephole optimizer, which processes ops in
+execution order. Note that \fBfinalize_optree()\fR also does a top-down scan,
+but is called *after* the peephole optimizer.
+.RS 4
+.Sp
+.Vb 1
+\& void  optimize_optree(OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OP_TYPE_IS""" 4
+.el .IP \f(CWOP_TYPE_IS\fR 4
+.IX Xref "OP_TYPE_IS"
+.IX Item "OP_TYPE_IS"
+Returns true if the given OP is not a \f(CW\*(C`NULL\*(C'\fR pointer
+and if it is of the given type.
+.Sp
+The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT\*(C'\fR is also available
+as well as \f(CW\*(C`OP_TYPE_IS_NN\*(C'\fR and \f(CW\*(C`OP_TYPE_ISNT_NN\*(C'\fR which elide
+the NULL pointer check.
+.RS 4
+.Sp
+.Vb 1
+\& bool  OP_TYPE_IS(OP *o, Optype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """OP_TYPE_IS_OR_WAS""" 4
+.el .IP \f(CWOP_TYPE_IS_OR_WAS\fR 4
+.IX Xref "OP_TYPE_IS_OR_WAS"
+.IX Item "OP_TYPE_IS_OR_WAS"
+Returns true if the given OP is not a NULL pointer and
+if it is of the given type or used to be before being
+replaced by an OP of type OP_NULL.
+.Sp
+The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT\*(C'\fR
+is also available as well as \f(CW\*(C`OP_TYPE_IS_OR_WAS_NN\*(C'\fR
+and \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT_NN\*(C'\fR which elide
+the \f(CW\*(C`NULL\*(C'\fR pointer check.
+.RS 4
+.Sp
+.Vb 1
+\& bool  OP_TYPE_IS_OR_WAS(OP *o, Optype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_wrap_finally""" 4
+.el .IP \f(CWop_wrap_finally\fR 4
+.IX Xref "op_wrap_finally"
+.IX Item "op_wrap_finally"
+NOTE: \f(CW\*(C`op_wrap_finally\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Wraps the given \f(CW\*(C`block\*(C'\fR optree fragment in its own scoped block, arranging
+for the \f(CW\*(C`finally\*(C'\fR optree fragment to be invoked when leaving that block for
+any reason. Both optree fragments are consumed and the combined result is
+returned.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  op_wrap_finally(OP *block, OP *finally)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """peep_t""" 4
+.el .IP \f(CWpeep_t\fR 4
+.IX Item "peep_t"
+Described in perlguts.
+.ie n .IP """Perl_cpeep_t""" 4
+.el .IP \f(CWPerl_cpeep_t\fR 4
+.IX Item "Perl_cpeep_t"
+Described in perlguts.
+.ie n .IP """PL_opfreehook""" 4
+.el .IP \f(CWPL_opfreehook\fR 4
+.IX Xref "PL_opfreehook"
+.IX Item "PL_opfreehook"
+When non\-\f(CW\*(C`NULL\*(C'\fR, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument.
+This allows extensions to free any extra attribute they have locally attached to an OP.
+It is also assured to first fire for the parent OP and then for its kids.
+.Sp
+When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& Perl_ophook_t  PL_opfreehook
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_peepp""" 4
+.el .IP \f(CWPL_peepp\fR 4
+.IX Xref "PL_peepp"
+.IX Item "PL_peepp"
+Pointer to the per-subroutine peephole optimiser.  This is a function
+that gets called at the end of compilation of a Perl subroutine (or
+equivalently independent piece of Perl code) to perform fixups of
+some ops and to perform small-scale optimisations.  The function is
+called once for each subroutine that is compiled, and is passed, as sole
+parameter, a pointer to the op that is the entry point to the subroutine.
+It modifies the op tree in place.
+.Sp
+The peephole optimiser should never be completely replaced.  Rather,
+add code to it by wrapping the existing optimiser.  The basic way to do
+this can be seen in "Compile pass 3: peephole optimization" in perlguts.
+If the new code wishes to operate on ops throughout the subroutine's
+structure, rather than just at the top level, it is likely to be more
+convenient to wrap the "PL_rpeepp" hook.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& peep_t  PL_peepp
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_rpeepp""" 4
+.el .IP \f(CWPL_rpeepp\fR 4
+.IX Xref "PL_rpeepp"
+.IX Item "PL_rpeepp"
+Pointer to the recursive peephole optimiser.  This is a function
+that gets called at the end of compilation of a Perl subroutine (or
+equivalently independent piece of Perl code) to perform fixups of some
+ops and to perform small-scale optimisations.  The function is called
+once for each chain of ops linked through their \f(CW\*(C`op_next\*(C'\fR fields;
+it is recursively called to handle each side chain.  It is passed, as
+sole parameter, a pointer to the op that is at the head of the chain.
+It modifies the op tree in place.
+.Sp
+The peephole optimiser should never be completely replaced.  Rather,
+add code to it by wrapping the existing optimiser.  The basic way to do
+this can be seen in "Compile pass 3: peephole optimization" in perlguts.
+If the new code wishes to operate only on ops at a subroutine's top level,
+rather than throughout the structure, it is likely to be more convenient
+to wrap the "PL_peepp" hook.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& peep_t  PL_rpeepp
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PMOP""" 4
+.el .IP \f(CWPMOP\fR 4
+.IX Item "PMOP"
+Described in perlguts.
+.ie n .IP """rv2cv_op_cv""" 4
+.el .IP \f(CWrv2cv_op_cv\fR 4
+.IX Xref "rv2cv_op_cv"
+.IX Item "rv2cv_op_cv"
+Examines an op, which is expected to identify a subroutine at runtime,
+and attempts to determine at compile time which subroutine it identifies.
+This is normally used during Perl compilation to determine whether
+a prototype can be applied to a function call.  \f(CW\*(C`cvop\*(C'\fR is the op
+being considered, normally an \f(CW\*(C`rv2cv\*(C'\fR op.  A pointer to the identified
+subroutine is returned, if it could be determined statically, and a null
+pointer is returned if it was not possible to determine statically.
+.Sp
+Currently, the subroutine can be identified statically if the RV that the
+\&\f(CW\*(C`rv2cv\*(C'\fR is to operate on is provided by a suitable \f(CW\*(C`gv\*(C'\fR or \f(CW\*(C`const\*(C'\fR op.
+A \f(CW\*(C`gv\*(C'\fR op is suitable if the GV's CV slot is populated.  A \f(CW\*(C`const\*(C'\fR op is
+suitable if the constant value must be an RV pointing to a CV.  Details of
+this process may change in future versions of Perl.  If the \f(CW\*(C`rv2cv\*(C'\fR op
+has the \f(CW\*(C`OPpENTERSUB_AMPER\*(C'\fR flag set then no attempt is made to identify
+the subroutine statically: this flag is used to suppress compile-time
+magic on a subroutine call, forcing it to use default runtime behaviour.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_MARK_EARLY\*(C'\fR set, then the handling
+of a GV reference is modified.  If a GV was examined and its CV slot was
+found to be empty, then the \f(CW\*(C`gv\*(C'\fR op has the \f(CW\*(C`OPpEARLY_CV\*(C'\fR flag set.
+If the op is not optimised away, and the CV slot is later populated with
+a subroutine having a prototype, that flag eventually triggers the warning
+"called too early to check prototype".
+.Sp
+If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_RETURN_NAME_GV\*(C'\fR set, then instead
+of returning a pointer to the subroutine it returns a pointer to the
+GV giving the most appropriate name for the subroutine in this context.
+Normally this is just the \f(CW\*(C`CvGV\*(C'\fR of the subroutine, but for an anonymous
+(\f(CW\*(C`CvANON\*(C'\fR) subroutine that is referenced through a GV it will be the
+referencing GV.  The resulting \f(CW\*(C`GV*\*(C'\fR is cast to \f(CW\*(C`CV*\*(C'\fR to be returned.
+A null pointer is returned as usual if there is no statically-determinable
+subroutine.
+.RS 4
+.Sp
+.Vb 1
+\& CV *  rv2cv_op_cv(OP *cvop, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNOP""" 4
+.el .IP \f(CWUNOP\fR 4
+.IX Item "UNOP"
+Described in perlguts.
+.ie n .IP """XOP""" 4
+.el .IP \f(CWXOP\fR 4
+.IX Item "XOP"
+Described in perlguts.
+.SH "Pack and Unpack"
+.IX Header "Pack and Unpack"
+.ie n .IP """packlist""" 4
+.el .IP \f(CWpacklist\fR 4
+.IX Xref "packlist"
+.IX Item "packlist"
+The engine implementing \f(CWpack()\fR Perl function.
+.RS 4
+.Sp
+.Vb 2
+\& void  packlist(SV *cat, const char *pat, const char *patend,
+\&                SV **beglist, SV **endlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """unpackstring""" 4
+.el .IP \f(CWunpackstring\fR 4
+.IX Xref "unpackstring"
+.IX Item "unpackstring"
+The engine implementing the \f(CWunpack()\fR Perl function.
+.Sp
+Using the template \f(CW\*(C`pat..patend\*(C'\fR, this function unpacks the string
+\&\f(CW\*(C`s..strend\*(C'\fR into a number of mortal SVs, which it pushes onto the perl
+argument (\f(CW@_\fR) stack (so you will need to issue a \f(CW\*(C`PUTBACK\*(C'\fR before and
+\&\f(CW\*(C`SPAGAIN\*(C'\fR after the call to this function).  It returns the number of
+pushed elements.
+.Sp
+The \f(CW\*(C`strend\*(C'\fR and \f(CW\*(C`patend\*(C'\fR pointers should point to the byte following the
+last character of each string.
+.Sp
+Although this function returns its values on the perl argument stack, it
+doesn't take any parameters from that stack (and thus in particular
+there's no need to do a \f(CW\*(C`PUSHMARK\*(C'\fR before calling it, unlike "call_pv" for
+example).
+.RS 4
+.Sp
+.Vb 3
+\& SSize_t  unpackstring(const char *pat, const char *patend,
+\&                       const char *s, const char *strend,
+\&                       U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Pad Data Structures"
+.IX Xref "SVs_PADSTALE"
+.IX Header "Pad Data Structures"
+.ie n .IP """CvPADLIST""" 4
+.el .IP \f(CWCvPADLIST\fR 4
+.IX Xref "CvPADLIST"
+.IX Item "CvPADLIST"
+NOTE: \f(CW\*(C`CvPADLIST\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+CV's can have CvPADLIST(cv) set to point to a PADLIST.  This is the CV's
+scratchpad, which stores lexical variables and opcode temporary and
+per-thread values.
+.Sp
+For these purposes "formats" are a kind-of CV; eval""s are too (except they're
+not callable at will and are always thrown away after the eval"" is done
+executing).  Require'd files are simply evals without any outer lexical
+scope.
+.Sp
+XSUBs do not have a \f(CW\*(C`CvPADLIST\*(C'\fR.  \f(CW\*(C`dXSTARG\*(C'\fR fetches values from \f(CW\*(C`PL_curpad\*(C'\fR,
+but that is really the callers pad (a slot of which is allocated by
+every entersub). Do not get or set \f(CW\*(C`CvPADLIST\*(C'\fR if a CV is an XSUB (as
+determined by \f(CWCvISXSUB()\fR), \f(CW\*(C`CvPADLIST\*(C'\fR slot is reused for a different
+internal purpose in XSUBs.
+.Sp
+The PADLIST has a C array where pads are stored.
+.Sp
+The 0th entry of the PADLIST is a PADNAMELIST
+which represents the "names" or rather
+the "static type information" for lexicals.  The individual elements of a
+PADNAMELIST are PADNAMEs.  Future
+refactorings might stop the PADNAMELIST from being stored in the PADLIST's
+array, so don't rely on it.  See "PadlistNAMES".
+.Sp
+The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the stack frame
+at that depth of recursion into the CV.  The 0th slot of a frame AV is an
+AV which is \f(CW@_\fR.  Other entries are storage for variables and op targets.
+.Sp
+Iterating over the PADNAMELIST iterates over all possible pad
+items.  Pad slots for targets (\f(CW\*(C`SVs_PADTMP\*(C'\fR)
+and GVs end up having &PL_padname_undef "names", while slots for constants 
+have \f(CW&PL_padname_const\fR "names" (see \f(CW"pad_alloc"\fR).  That
+\&\f(CW&PL_padname_undef\fR
+and \f(CW&PL_padname_const\fR are used is an implementation detail subject to
+change.  To test for them, use \f(CW\*(C`!PadnamePV(name)\*(C'\fR and
+\&\f(CW\*(C`PadnamePV(name)\ &&\ !PadnameLEN(name)\*(C'\fR, respectively.
+.Sp
+Only \f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variable slots get valid names.
+The rest are op targets/GVs/constants which are statically allocated
+or resolved at compile time.  These don't have names by which they
+can be looked up from Perl code at run time through eval"" the way
+\&\f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variables can be.  Since they can't be looked up by "name"
+but only by their index allocated at compile time (which is usually
+in \f(CW\*(C`PL_op\->op_targ\*(C'\fR), wasting a name SV for them doesn't make sense.
+.Sp
+The pad names in the PADNAMELIST have their PV holding the name of
+the variable.  The \f(CW\*(C`COP_SEQ_RANGE_LOW\*(C'\fR and \f(CW\*(C`_HIGH\*(C'\fR fields form a range
+(low+1..high inclusive) of cop_seq numbers for which the name is
+valid.  During compilation, these fields may hold the special value
+PERL_PADSEQ_INTRO to indicate various stages:
+.Sp
+.Vb 8
+\& COP_SEQ_RANGE_LOW        _HIGH
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-        \-\-\-\-\-
+\& PERL_PADSEQ_INTRO            0   variable not yet introduced:
+\&                                  { my ($x
+\& valid\-seq#   PERL_PADSEQ_INTRO   variable in scope:
+\&                                  { my ($x);
+\& valid\-seq#          valid\-seq#   compilation of scope complete:
+\&                                  { my ($x); .... }
+.Ve
+.Sp
+When a lexical var hasn't yet been introduced, it already exists from the
+perspective of duplicate declarations, but not for variable lookups, e.g.
+.Sp
+.Vb 2
+\&    my ($x, $x); # \*(Aq"my" variable $x masks earlier declaration\*(Aq
+\&    my $x = $x;  # equal to my $x = $::x;
+.Ve
+.Sp
+For typed lexicals \f(CW\*(C`PadnameTYPE\*(C'\fR points at the type stash.  For \f(CW\*(C`our\*(C'\fR
+lexicals, \f(CW\*(C`PadnameOURSTASH\*(C'\fR points at the stash of the associated global (so
+that duplicate \f(CW\*(C`our\*(C'\fR declarations in the same package can be detected).
+\&\f(CW\*(C`PadnameGEN\*(C'\fR is sometimes used to store the generation number during
+compilation.
+.Sp
+If \f(CW\*(C`PadnameOUTER\*(C'\fR is set on the pad name, then that slot in the frame AV
+is a REFCNT'ed reference to a lexical from "outside".  Such entries
+are sometimes referred to as 'fake'.  In this case, the name does not
+use 'low' and 'high' to store a cop_seq range, since it is in scope
+throughout.  Instead 'high' stores some flags containing info about
+the real lexical (is it declared in an anon, and is it capable of being
+instantiated multiple times?), and for fake ANONs, 'low' contains the index
+within the parent's pad where the lexical's value is stored, to make
+cloning quicker.
+.Sp
+If the 'name' is \f(CW\*(C`&\*(C'\fR the corresponding entry in the PAD
+is a CV representing a possible closure.
+.Sp
+Note that formats are treated as anon subs, and are cloned each time
+write is called (if necessary).
+.Sp
+The flag \f(CW\*(C`SVs_PADSTALE\*(C'\fR is cleared on lexicals each time the \f(CWmy()\fR is executed,
+and set on scope exit.  This allows the
+\&\f(CW"Variable $x is not available"\fR warning
+to be generated in evals, such as
+.Sp
+.Vb 1
+\&    { my $x = 1; sub f { eval \*(Aq$x\*(Aq} } f();
+.Ve
+.Sp
+For state vars, \f(CW\*(C`SVs_PADSTALE\*(C'\fR is overloaded to mean 'not yet initialised',
+but this internal state is stored in a separate pad entry.
+.RS 4
+.Sp
+.Vb 1
+\& PADLIST *  CvPADLIST(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_add_name_pvs""" 4
+.el .IP \f(CWpad_add_name_pvs\fR 4
+.IX Xref "pad_add_name_pvs"
+.IX Item "pad_add_name_pvs"
+Exactly like "pad_add_name_pvn", but takes a literal string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& PADOFFSET  pad_add_name_pvs("name", U32 flags, HV *typestash,
+\&                             HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadARRAY""" 4
+.el .IP \f(CWPadARRAY\fR 4
+.IX Xref "PadARRAY"
+.IX Item "PadARRAY"
+NOTE: \f(CW\*(C`PadARRAY\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The C array of pad entries.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  PadARRAY(PAD * pad)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_findmy_pvs""" 4
+.el .IP \f(CWpad_findmy_pvs\fR 4
+.IX Xref "pad_findmy_pvs"
+.IX Item "pad_findmy_pvs"
+Exactly like "pad_findmy_pvn", but takes a literal string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& PADOFFSET  pad_findmy_pvs("name", U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistARRAY""" 4
+.el .IP \f(CWPadlistARRAY\fR 4
+.IX Xref "PadlistARRAY"
+.IX Item "PadlistARRAY"
+NOTE: \f(CW\*(C`PadlistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The C array of a padlist, containing the pads.  Only subscript it with
+numbers >= 1, as the 0th entry is not guaranteed to remain usable.
+.RS 4
+.Sp
+.Vb 1
+\& PAD **  PadlistARRAY(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistMAX""" 4
+.el .IP \f(CWPadlistMAX\fR 4
+.IX Xref "PadlistMAX"
+.IX Item "PadlistMAX"
+NOTE: \f(CW\*(C`PadlistMAX\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The index of the last allocated space in the padlist.  Note that the last
+pad may be in an earlier slot.  Any entries following it will be \f(CW\*(C`NULL\*(C'\fR in
+that case.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadlistMAX(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistNAMES""" 4
+.el .IP \f(CWPadlistNAMES\fR 4
+.IX Xref "PadlistNAMES"
+.IX Item "PadlistNAMES"
+NOTE: \f(CW\*(C`PadlistNAMES\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The names associated with pad entries.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAMELIST *  PadlistNAMES(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistNAMESARRAY""" 4
+.el .IP \f(CWPadlistNAMESARRAY\fR 4
+.IX Xref "PadlistNAMESARRAY"
+.IX Item "PadlistNAMESARRAY"
+NOTE: \f(CW\*(C`PadlistNAMESARRAY\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The C array of pad names.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME **  PadlistNAMESARRAY(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistNAMESMAX""" 4
+.el .IP \f(CWPadlistNAMESMAX\fR 4
+.IX Xref "PadlistNAMESMAX"
+.IX Item "PadlistNAMESMAX"
+NOTE: \f(CW\*(C`PadlistNAMESMAX\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The index of the last pad name.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadlistNAMESMAX(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadlistREFCNT""" 4
+.el .IP \f(CWPadlistREFCNT\fR 4
+.IX Xref "PadlistREFCNT"
+.IX Item "PadlistREFCNT"
+NOTE: \f(CW\*(C`PadlistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The reference count of the padlist.  Currently this is always 1.
+.RS 4
+.Sp
+.Vb 1
+\& U32  PadlistREFCNT(PADLIST * padlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadMAX""" 4
+.el .IP \f(CWPadMAX\fR 4
+.IX Xref "PadMAX"
+.IX Item "PadMAX"
+NOTE: \f(CW\*(C`PadMAX\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The index of the last pad entry.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadMAX(PAD * pad)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameLEN""" 4
+.el .IP \f(CWPadnameLEN\fR 4
+.IX Xref "PadnameLEN"
+.IX Item "PadnameLEN"
+NOTE: \f(CW\*(C`PadnameLEN\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The length of the name.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  PadnameLEN(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnamelistARRAY""" 4
+.el .IP \f(CWPadnamelistARRAY\fR 4
+.IX Xref "PadnamelistARRAY"
+.IX Item "PadnamelistARRAY"
+NOTE: \f(CW\*(C`PadnamelistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The C array of pad names.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME **  PadnamelistARRAY(PADNAMELIST * pnl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnamelistMAX""" 4
+.el .IP \f(CWPadnamelistMAX\fR 4
+.IX Xref "PadnamelistMAX"
+.IX Item "PadnamelistMAX"
+NOTE: \f(CW\*(C`PadnamelistMAX\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The index of the last pad name.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadnamelistMAX(PADNAMELIST * pnl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnamelistREFCNT""" 4
+.el .IP \f(CWPadnamelistREFCNT\fR 4
+.IX Xref "PadnamelistREFCNT"
+.IX Item "PadnamelistREFCNT"
+NOTE: \f(CW\*(C`PadnamelistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The reference count of the pad name list.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadnamelistREFCNT(PADNAMELIST * pnl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnamelistREFCNT_dec""" 4
+.el .IP \f(CWPadnamelistREFCNT_dec\fR 4
+.IX Xref "PadnamelistREFCNT_dec"
+.IX Item "PadnamelistREFCNT_dec"
+NOTE: \f(CW\*(C`PadnamelistREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Lowers the reference count of the pad name list.
+.RS 4
+.Sp
+.Vb 1
+\& void  PadnamelistREFCNT_dec(PADNAMELIST * pnl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnamePV""" 4
+.el .IP \f(CWPadnamePV\fR 4
+.IX Xref "PadnamePV"
+.IX Item "PadnamePV"
+NOTE: \f(CW\*(C`PadnamePV\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The name stored in the pad name struct.  This returns \f(CW\*(C`NULL\*(C'\fR for a target
+slot.
+.RS 4
+.Sp
+.Vb 1
+\& char *  PadnamePV(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameREFCNT""" 4
+.el .IP \f(CWPadnameREFCNT\fR 4
+.IX Xref "PadnameREFCNT"
+.IX Item "PadnameREFCNT"
+NOTE: \f(CW\*(C`PadnameREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+The reference count of the pad name.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  PadnameREFCNT(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameREFCNT_dec""" 4
+.el .IP \f(CWPadnameREFCNT_dec\fR 4
+.IX Xref "PadnameREFCNT_dec"
+.IX Item "PadnameREFCNT_dec"
+NOTE: \f(CW\*(C`PadnameREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Lowers the reference count of the pad name.
+.RS 4
+.Sp
+.Vb 1
+\& void  PadnameREFCNT_dec(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameREFCNT_inc""" 4
+.el .IP \f(CWPadnameREFCNT_inc\fR 4
+.IX Xref "PadnameREFCNT_inc"
+.IX Item "PadnameREFCNT_inc"
+NOTE: \f(CW\*(C`PadnameREFCNT_inc\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Increases the reference count of the pad name.  Returns the pad name itself.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME *  PadnameREFCNT_inc(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameSV""" 4
+.el .IP \f(CWPadnameSV\fR 4
+.IX Xref "PadnameSV"
+.IX Item "PadnameSV"
+NOTE: \f(CW\*(C`PadnameSV\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Returns the pad name as a mortal SV.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PadnameSV(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameUTF8""" 4
+.el .IP \f(CWPadnameUTF8\fR 4
+.IX Xref "PadnameUTF8"
+.IX Item "PadnameUTF8"
+NOTE: \f(CW\*(C`PadnameUTF8\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Whether PadnamePV is in UTF\-8.  Currently, this is always true.
+.RS 4
+.Sp
+.Vb 1
+\& bool  PadnameUTF8(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_new""" 4
+.el .IP \f(CWpad_new\fR 4
+.IX Xref "pad_new"
+.IX Item "pad_new"
+Create a new padlist, updating the global variables for the
+currently-compiling padlist to point to the new padlist.  The following
+flags can be OR'ed together:
+.Sp
+.Vb 3
+\&    padnew_CLONE        this pad is for a cloned CV
+\&    padnew_SAVE         save old globals on the save stack
+\&    padnew_SAVESUB      also save extra stuff for start of sub
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& PADLIST *  pad_new(int flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_comppad""" 4
+.el .IP \f(CWPL_comppad\fR 4
+.IX Xref "PL_comppad"
+.IX Item "PL_comppad"
+NOTE: \f(CW\*(C`PL_comppad\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+During compilation, this points to the array containing the values
+part of the pad for the currently-compiling code.  (At runtime a CV may
+have many such value arrays; at compile time just one is constructed.)
+At runtime, this points to the array containing the currently-relevant
+values for the pad for the currently-executing code.
+.ie n .IP """PL_comppad_name""" 4
+.el .IP \f(CWPL_comppad_name\fR 4
+.IX Xref "PL_comppad_name"
+.IX Item "PL_comppad_name"
+NOTE: \f(CW\*(C`PL_comppad_name\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+During compilation, this points to the array containing the names part
+of the pad for the currently-compiling code.
+.ie n .IP """PL_curpad""" 4
+.el .IP \f(CWPL_curpad\fR 4
+.IX Xref "PL_curpad"
+.IX Item "PL_curpad"
+NOTE: \f(CW\*(C`PL_curpad\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Points directly to the body of the "PL_comppad" array.
+(I.e., this is \f(CWPadARRAY(PL_comppad)\fR.)
+.ie n .IP """SVs_PADMY""" 4
+.el .IP \f(CWSVs_PADMY\fR 4
+.IX Item "SVs_PADMY"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`SVs_PADMY\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Described in perlguts.
+.ie n .IP """SVs_PADTMP""" 4
+.el .IP \f(CWSVs_PADTMP\fR 4
+.IX Item "SVs_PADTMP"
+Described in perlguts.
+.SH "Password and Group access"
+.IX Header "Password and Group access"
+.ie n .IP """GRPASSWD""" 4
+.el .IP \f(CWGRPASSWD\fR 4
+.IX Xref "GRPASSWD"
+.IX Item "GRPASSWD"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct group\*(C'\fR
+in \fIgrp.h\fR contains \f(CW\*(C`gr_passwd\*(C'\fR.
+.ie n .IP """HAS_ENDGRENT""" 4
+.el .IP \f(CWHAS_ENDGRENT\fR 4
+.IX Xref "HAS_ENDGRENT"
+.IX Item "HAS_ENDGRENT"
+This symbol, if defined, indicates that the getgrent routine is
+available for finalizing sequential access of the group database.
+.ie n .IP """HAS_ENDGRENT_R""" 4
+.el .IP \f(CWHAS_ENDGRENT_R\fR 4
+.IX Xref "HAS_ENDGRENT_R"
+.IX Item "HAS_ENDGRENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`endgrent_r\*(C'\fR routine
+is available to endgrent re-entrantly.
+.ie n .IP """HAS_ENDPWENT""" 4
+.el .IP \f(CWHAS_ENDPWENT\fR 4
+.IX Xref "HAS_ENDPWENT"
+.IX Item "HAS_ENDPWENT"
+This symbol, if defined, indicates that the \f(CW\*(C`endpwent\*(C'\fR routine is
+available for finalizing sequential access of the passwd database.
+.ie n .IP """HAS_ENDPWENT_R""" 4
+.el .IP \f(CWHAS_ENDPWENT_R\fR 4
+.IX Xref "HAS_ENDPWENT_R"
+.IX Item "HAS_ENDPWENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`endpwent_r\*(C'\fR routine
+is available to endpwent re-entrantly.
+.ie n .IP """HAS_GETGRENT""" 4
+.el .IP \f(CWHAS_GETGRENT\fR 4
+.IX Xref "HAS_GETGRENT"
+.IX Item "HAS_GETGRENT"
+This symbol, if defined, indicates that the \f(CW\*(C`getgrent\*(C'\fR routine is
+available for sequential access of the group database.
+.ie n .IP """HAS_GETGRENT_R""" 4
+.el .IP \f(CWHAS_GETGRENT_R\fR 4
+.IX Xref "HAS_GETGRENT_R"
+.IX Item "HAS_GETGRENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`getgrent_r\*(C'\fR routine
+is available to getgrent re-entrantly.
+.ie n .IP """HAS_GETPWENT""" 4
+.el .IP \f(CWHAS_GETPWENT\fR 4
+.IX Xref "HAS_GETPWENT"
+.IX Item "HAS_GETPWENT"
+This symbol, if defined, indicates that the \f(CW\*(C`getpwent\*(C'\fR routine is
+available for sequential access of the passwd database.
+If this is not available, the older \f(CWgetpw()\fR function may be available.
+.ie n .IP """HAS_GETPWENT_R""" 4
+.el .IP \f(CWHAS_GETPWENT_R\fR 4
+.IX Xref "HAS_GETPWENT_R"
+.IX Item "HAS_GETPWENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`getpwent_r\*(C'\fR routine
+is available to getpwent re-entrantly.
+.ie n .IP """HAS_SETGRENT""" 4
+.el .IP \f(CWHAS_SETGRENT\fR 4
+.IX Xref "HAS_SETGRENT"
+.IX Item "HAS_SETGRENT"
+This symbol, if defined, indicates that the \f(CW\*(C`setgrent\*(C'\fR routine is
+available for initializing sequential access of the group database.
+.ie n .IP """HAS_SETGRENT_R""" 4
+.el .IP \f(CWHAS_SETGRENT_R\fR 4
+.IX Xref "HAS_SETGRENT_R"
+.IX Item "HAS_SETGRENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`setgrent_r\*(C'\fR routine
+is available to setgrent re-entrantly.
+.ie n .IP """HAS_SETPWENT""" 4
+.el .IP \f(CWHAS_SETPWENT\fR 4
+.IX Xref "HAS_SETPWENT"
+.IX Item "HAS_SETPWENT"
+This symbol, if defined, indicates that the \f(CW\*(C`setpwent\*(C'\fR routine is
+available for initializing sequential access of the passwd database.
+.ie n .IP """HAS_SETPWENT_R""" 4
+.el .IP \f(CWHAS_SETPWENT_R\fR 4
+.IX Xref "HAS_SETPWENT_R"
+.IX Item "HAS_SETPWENT_R"
+This symbol, if defined, indicates that the \f(CW\*(C`setpwent_r\*(C'\fR routine
+is available to setpwent re-entrantly.
+.ie n .IP """PWAGE""" 4
+.el .IP \f(CWPWAGE\fR 4
+.IX Xref "PWAGE"
+.IX Item "PWAGE"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_age\*(C'\fR.
+.ie n .IP """PWCHANGE""" 4
+.el .IP \f(CWPWCHANGE\fR 4
+.IX Xref "PWCHANGE"
+.IX Item "PWCHANGE"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_change\*(C'\fR.
+.ie n .IP """PWCLASS""" 4
+.el .IP \f(CWPWCLASS\fR 4
+.IX Xref "PWCLASS"
+.IX Item "PWCLASS"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_class\*(C'\fR.
+.ie n .IP """PWCOMMENT""" 4
+.el .IP \f(CWPWCOMMENT\fR 4
+.IX Xref "PWCOMMENT"
+.IX Item "PWCOMMENT"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_comment\*(C'\fR.
+.ie n .IP """PWEXPIRE""" 4
+.el .IP \f(CWPWEXPIRE\fR 4
+.IX Xref "PWEXPIRE"
+.IX Item "PWEXPIRE"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_expire\*(C'\fR.
+.ie n .IP """PWGECOS""" 4
+.el .IP \f(CWPWGECOS\fR 4
+.IX Xref "PWGECOS"
+.IX Item "PWGECOS"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_gecos\*(C'\fR.
+.ie n .IP """PWPASSWD""" 4
+.el .IP \f(CWPWPASSWD\fR 4
+.IX Xref "PWPASSWD"
+.IX Item "PWPASSWD"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_passwd\*(C'\fR.
+.ie n .IP """PWQUOTA""" 4
+.el .IP \f(CWPWQUOTA\fR 4
+.IX Xref "PWQUOTA"
+.IX Item "PWQUOTA"
+This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
+contains \f(CW\*(C`pw_quota\*(C'\fR.
+.SH "Paths to system commands"
+.IX Header "Paths to system commands"
+.ie n .IP """CSH""" 4
+.el .IP \f(CWCSH\fR 4
+.IX Xref "CSH"
+.IX Item "CSH"
+This symbol, if defined, contains the full pathname of csh.
+.ie n .IP """LOC_SED""" 4
+.el .IP \f(CWLOC_SED\fR 4
+.IX Xref "LOC_SED"
+.IX Item "LOC_SED"
+This symbol holds the complete pathname to the sed program.
+.ie n .IP """SH_PATH""" 4
+.el .IP \f(CWSH_PATH\fR 4
+.IX Xref "SH_PATH"
+.IX Item "SH_PATH"
+This symbol contains the full pathname to the shell used on this
+on this system to execute Bourne shell scripts.  Usually, this will be
+\&\fI/bin/sh\fR, though it's possible that some systems will have \fI/bin/ksh\fR,
+\&\fI/bin/pdksh\fR, \fI/bin/ash\fR, \fI/bin/bash\fR, or even something such as
+D:\fI/bin/sh.exe\fR.
+.SH "Prototype information"
+.IX Header "Prototype information"
+.ie n .IP """CRYPT_R_PROTO""" 4
+.el .IP \f(CWCRYPT_R_PROTO\fR 4
+.IX Xref "CRYPT_R_PROTO"
+.IX Item "CRYPT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`crypt_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_crypt_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_crypt_r\*(C'\fR
+is defined.
+.ie n .IP """CTERMID_R_PROTO""" 4
+.el .IP \f(CWCTERMID_R_PROTO\fR 4
+.IX Xref "CTERMID_R_PROTO"
+.IX Item "CTERMID_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`ctermid_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_ctermid_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctermid_r\*(C'\fR
+is defined.
+.ie n .IP """DRAND48_R_PROTO""" 4
+.el .IP \f(CWDRAND48_R_PROTO\fR 4
+.IX Xref "DRAND48_R_PROTO"
+.IX Item "DRAND48_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`drand48_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_drand48_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_drand48_r\*(C'\fR
+is defined.
+.ie n .IP """ENDGRENT_R_PROTO""" 4
+.el .IP \f(CWENDGRENT_R_PROTO\fR 4
+.IX Xref "ENDGRENT_R_PROTO"
+.IX Item "ENDGRENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endgrent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endgrent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endgrent_r\*(C'\fR
+is defined.
+.ie n .IP """ENDHOSTENT_R_PROTO""" 4
+.el .IP \f(CWENDHOSTENT_R_PROTO\fR 4
+.IX Xref "ENDHOSTENT_R_PROTO"
+.IX Item "ENDHOSTENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endhostent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endhostent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endhostent_r\*(C'\fR
+is defined.
+.ie n .IP """ENDNETENT_R_PROTO""" 4
+.el .IP \f(CWENDNETENT_R_PROTO\fR 4
+.IX Xref "ENDNETENT_R_PROTO"
+.IX Item "ENDNETENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endnetent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endnetent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endnetent_r\*(C'\fR
+is defined.
+.ie n .IP """ENDPROTOENT_R_PROTO""" 4
+.el .IP \f(CWENDPROTOENT_R_PROTO\fR 4
+.IX Xref "ENDPROTOENT_R_PROTO"
+.IX Item "ENDPROTOENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endprotoent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endprotoent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endprotoent_r\*(C'\fR
+is defined.
+.ie n .IP """ENDPWENT_R_PROTO""" 4
+.el .IP \f(CWENDPWENT_R_PROTO\fR 4
+.IX Xref "ENDPWENT_R_PROTO"
+.IX Item "ENDPWENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endpwent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endpwent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endpwent_r\*(C'\fR
+is defined.
+.ie n .IP """ENDSERVENT_R_PROTO""" 4
+.el .IP \f(CWENDSERVENT_R_PROTO\fR 4
+.IX Xref "ENDSERVENT_R_PROTO"
+.IX Item "ENDSERVENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`endservent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_endservent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endservent_r\*(C'\fR
+is defined.
+.ie n .IP """GDBMNDBM_H_USES_PROTOTYPES""" 4
+.el .IP \f(CWGDBMNDBM_H_USES_PROTOTYPES\fR 4
+.IX Xref "GDBMNDBM_H_USES_PROTOTYPES"
+.IX Item "GDBMNDBM_H_USES_PROTOTYPES"
+This symbol, if defined, indicates that \fIgdbm/ndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
+prototypes instead of K&R style function declarations without any
+parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
+K&R style function declarations will yield errors.
+.ie n .IP """GDBM_NDBM_H_USES_PROTOTYPES""" 4
+.el .IP \f(CWGDBM_NDBM_H_USES_PROTOTYPES\fR 4
+.IX Xref "GDBM_NDBM_H_USES_PROTOTYPES"
+.IX Item "GDBM_NDBM_H_USES_PROTOTYPES"
+This symbol, if defined, indicates that <gdbm\-\fIndbm.h\fR> uses real \f(CW\*(C`ANSI\*(C'\fR C
+prototypes instead of K&R style function declarations without any
+parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
+K&R style function declarations will yield errors.
+.ie n .IP """GETGRENT_R_PROTO""" 4
+.el .IP \f(CWGETGRENT_R_PROTO\fR 4
+.IX Xref "GETGRENT_R_PROTO"
+.IX Item "GETGRENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getgrent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getgrent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrent_r\*(C'\fR
+is defined.
+.ie n .IP """GETGRGID_R_PROTO""" 4
+.el .IP \f(CWGETGRGID_R_PROTO\fR 4
+.IX Xref "GETGRGID_R_PROTO"
+.IX Item "GETGRGID_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getgrgid_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getgrgid_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrgid_r\*(C'\fR
+is defined.
+.ie n .IP """GETGRNAM_R_PROTO""" 4
+.el .IP \f(CWGETGRNAM_R_PROTO\fR 4
+.IX Xref "GETGRNAM_R_PROTO"
+.IX Item "GETGRNAM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getgrnam_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getgrnam_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrnam_r\*(C'\fR
+is defined.
+.ie n .IP """GETHOSTBYADDR_R_PROTO""" 4
+.el .IP \f(CWGETHOSTBYADDR_R_PROTO\fR 4
+.IX Xref "GETHOSTBYADDR_R_PROTO"
+.IX Item "GETHOSTBYADDR_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`gethostbyaddr_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR
+is defined.
+.ie n .IP """GETHOSTBYNAME_R_PROTO""" 4
+.el .IP \f(CWGETHOSTBYNAME_R_PROTO\fR 4
+.IX Xref "GETHOSTBYNAME_R_PROTO"
+.IX Item "GETHOSTBYNAME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`gethostbyname_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_gethostbyname_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyname_r\*(C'\fR
+is defined.
+.ie n .IP """GETHOSTENT_R_PROTO""" 4
+.el .IP \f(CWGETHOSTENT_R_PROTO\fR 4
+.IX Xref "GETHOSTENT_R_PROTO"
+.IX Item "GETHOSTENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`gethostent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_gethostent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostent_r\*(C'\fR
+is defined.
+.ie n .IP """GETLOGIN_R_PROTO""" 4
+.el .IP \f(CWGETLOGIN_R_PROTO\fR 4
+.IX Xref "GETLOGIN_R_PROTO"
+.IX Item "GETLOGIN_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getlogin_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getlogin_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getlogin_r\*(C'\fR
+is defined.
+.ie n .IP """GETNETBYADDR_R_PROTO""" 4
+.el .IP \f(CWGETNETBYADDR_R_PROTO\fR 4
+.IX Xref "GETNETBYADDR_R_PROTO"
+.IX Item "GETNETBYADDR_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getnetbyaddr_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR
+is defined.
+.ie n .IP """GETNETBYNAME_R_PROTO""" 4
+.el .IP \f(CWGETNETBYNAME_R_PROTO\fR 4
+.IX Xref "GETNETBYNAME_R_PROTO"
+.IX Item "GETNETBYNAME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getnetbyname_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getnetbyname_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyname_r\*(C'\fR
+is defined.
+.ie n .IP """GETNETENT_R_PROTO""" 4
+.el .IP \f(CWGETNETENT_R_PROTO\fR 4
+.IX Xref "GETNETENT_R_PROTO"
+.IX Item "GETNETENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getnetent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getnetent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetent_r\*(C'\fR
+is defined.
+.ie n .IP """GETPROTOBYNAME_R_PROTO""" 4
+.el .IP \f(CWGETPROTOBYNAME_R_PROTO\fR 4
+.IX Xref "GETPROTOBYNAME_R_PROTO"
+.IX Item "GETPROTOBYNAME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getprotobyname_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getprotobyname_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobyname_r\*(C'\fR
+is defined.
+.ie n .IP """GETPROTOBYNUMBER_R_PROTO""" 4
+.el .IP \f(CWGETPROTOBYNUMBER_R_PROTO\fR 4
+.IX Xref "GETPROTOBYNUMBER_R_PROTO"
+.IX Item "GETPROTOBYNUMBER_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getprotobynumber_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR
+is defined.
+.ie n .IP """GETPROTOENT_R_PROTO""" 4
+.el .IP \f(CWGETPROTOENT_R_PROTO\fR 4
+.IX Xref "GETPROTOENT_R_PROTO"
+.IX Item "GETPROTOENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getprotoent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getprotoent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotoent_r\*(C'\fR
+is defined.
+.ie n .IP """GETPWENT_R_PROTO""" 4
+.el .IP \f(CWGETPWENT_R_PROTO\fR 4
+.IX Xref "GETPWENT_R_PROTO"
+.IX Item "GETPWENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getpwent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getpwent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwent_r\*(C'\fR
+is defined.
+.ie n .IP """GETPWNAM_R_PROTO""" 4
+.el .IP \f(CWGETPWNAM_R_PROTO\fR 4
+.IX Xref "GETPWNAM_R_PROTO"
+.IX Item "GETPWNAM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getpwnam_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getpwnam_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwnam_r\*(C'\fR
+is defined.
+.ie n .IP """GETPWUID_R_PROTO""" 4
+.el .IP \f(CWGETPWUID_R_PROTO\fR 4
+.IX Xref "GETPWUID_R_PROTO"
+.IX Item "GETPWUID_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getpwuid_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getpwuid_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwuid_r\*(C'\fR
+is defined.
+.ie n .IP """GETSERVBYNAME_R_PROTO""" 4
+.el .IP \f(CWGETSERVBYNAME_R_PROTO\fR 4
+.IX Xref "GETSERVBYNAME_R_PROTO"
+.IX Item "GETSERVBYNAME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getservbyname_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getservbyname_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyname_r\*(C'\fR
+is defined.
+.ie n .IP """GETSERVBYPORT_R_PROTO""" 4
+.el .IP \f(CWGETSERVBYPORT_R_PROTO\fR 4
+.IX Xref "GETSERVBYPORT_R_PROTO"
+.IX Item "GETSERVBYPORT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getservbyport_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getservbyport_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyport_r\*(C'\fR
+is defined.
+.ie n .IP """GETSERVENT_R_PROTO""" 4
+.el .IP \f(CWGETSERVENT_R_PROTO\fR 4
+.IX Xref "GETSERVENT_R_PROTO"
+.IX Item "GETSERVENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getservent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getservent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservent_r\*(C'\fR
+is defined.
+.ie n .IP """GETSPNAM_R_PROTO""" 4
+.el .IP \f(CWGETSPNAM_R_PROTO\fR 4
+.IX Xref "GETSPNAM_R_PROTO"
+.IX Item "GETSPNAM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`getspnam_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_getspnam_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getspnam_r\*(C'\fR
+is defined.
+.ie n .IP """HAS_DBMINIT_PROTO""" 4
+.el .IP \f(CWHAS_DBMINIT_PROTO\fR 4
+.IX Xref "HAS_DBMINIT_PROTO"
+.IX Item "HAS_DBMINIT_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWdbminit()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern int dbminit(char *);
+.Ve
+.ie n .IP """HAS_DRAND48_PROTO""" 4
+.el .IP \f(CWHAS_DRAND48_PROTO\fR 4
+.IX Xref "HAS_DRAND48_PROTO"
+.IX Item "HAS_DRAND48_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWdrand48()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern double drand48(void);
+.Ve
+.ie n .IP """HAS_FLOCK_PROTO""" 4
+.el .IP \f(CWHAS_FLOCK_PROTO\fR 4
+.IX Xref "HAS_FLOCK_PROTO"
+.IX Item "HAS_FLOCK_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWflock()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern int flock(int, int);
+.Ve
+.ie n .IP """HAS_GETHOST_PROTOS""" 4
+.el .IP \f(CWHAS_GETHOST_PROTOS\fR 4
+.IX Xref "HAS_GETHOST_PROTOS"
+.IX Item "HAS_GETHOST_PROTOS"
+This symbol, if defined, indicates that \fInetdb.h\fR includes
+prototypes for \f(CWgethostent()\fR, \f(CWgethostbyname()\fR, and
+\&\f(CWgethostbyaddr()\fR.  Otherwise, it is up to the program to guess
+them.  See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
+.ie n .IP """HAS_GETNET_PROTOS""" 4
+.el .IP \f(CWHAS_GETNET_PROTOS\fR 4
+.IX Xref "HAS_GETNET_PROTOS"
+.IX Item "HAS_GETNET_PROTOS"
+This symbol, if defined, indicates that \fInetdb.h\fR includes
+prototypes for \f(CWgetnetent()\fR, \f(CWgetnetbyname()\fR, and
+\&\f(CWgetnetbyaddr()\fR.  Otherwise, it is up to the program to guess
+them.  See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
+.ie n .IP """HAS_GETPROTO_PROTOS""" 4
+.el .IP \f(CWHAS_GETPROTO_PROTOS\fR 4
+.IX Xref "HAS_GETPROTO_PROTOS"
+.IX Item "HAS_GETPROTO_PROTOS"
+This symbol, if defined, indicates that \fInetdb.h\fR includes
+prototypes for \f(CWgetprotoent()\fR, \f(CWgetprotobyname()\fR, and
+\&\f(CWgetprotobyaddr()\fR.  Otherwise, it is up to the program to guess
+them.  See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
+.ie n .IP """HAS_GETSERV_PROTOS""" 4
+.el .IP \f(CWHAS_GETSERV_PROTOS\fR 4
+.IX Xref "HAS_GETSERV_PROTOS"
+.IX Item "HAS_GETSERV_PROTOS"
+This symbol, if defined, indicates that \fInetdb.h\fR includes
+prototypes for \f(CWgetservent()\fR, \f(CWgetservbyname()\fR, and
+\&\f(CWgetservbyaddr()\fR.  Otherwise, it is up to the program to guess
+them.  See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
+.ie n .IP """HAS_MODFL_PROTO""" 4
+.el .IP \f(CWHAS_MODFL_PROTO\fR 4
+.IX Xref "HAS_MODFL_PROTO"
+.IX Item "HAS_MODFL_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWmodfl()\fR function.  Otherwise, it is up
+to the program to supply one.
+.ie n .IP """HAS_SBRK_PROTO""" 4
+.el .IP \f(CWHAS_SBRK_PROTO\fR 4
+.IX Xref "HAS_SBRK_PROTO"
+.IX Item "HAS_SBRK_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWsbrk()\fR function.  Otherwise, it is up
+to the program to supply one.  Good guesses are
+.Sp
+.Vb 2
+\& extern void* sbrk(int);
+\& extern void* sbrk(size_t);
+.Ve
+.ie n .IP """HAS_SETRESGID_PROTO""" 4
+.el .IP \f(CWHAS_SETRESGID_PROTO\fR 4
+.IX Xref "HAS_SETRESGID_PROTO"
+.IX Item "HAS_SETRESGID_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWsetresgid()\fR function.  Otherwise, it is up
+to the program to supply one.  Good guesses are
+.Sp
+.Vb 1
+\& extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
+.Ve
+.ie n .IP """HAS_SETRESUID_PROTO""" 4
+.el .IP \f(CWHAS_SETRESUID_PROTO\fR 4
+.IX Xref "HAS_SETRESUID_PROTO"
+.IX Item "HAS_SETRESUID_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWsetresuid()\fR function.  Otherwise, it is up
+to the program to supply one.  Good guesses are
+.Sp
+.Vb 1
+\& extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
+.Ve
+.ie n .IP """HAS_SHMAT_PROTOTYPE""" 4
+.el .IP \f(CWHAS_SHMAT_PROTOTYPE\fR 4
+.IX Xref "HAS_SHMAT_PROTOTYPE"
+.IX Item "HAS_SHMAT_PROTOTYPE"
+This symbol, if defined, indicates that the \fIsys/shm.h\fR includes
+a prototype for \f(CWshmat()\fR.  Otherwise, it is up to the program to
+guess one.  \f(CW\*(C`Shmat_t\*(C'\fR \f(CW\*(C`shmat(int, Shmat_t, int)\*(C'\fR is a good guess,
+but not always right so it should be emitted by the program only
+when \f(CW\*(C`HAS_SHMAT_PROTOTYPE\*(C'\fR is not defined to avoid conflicting defs.
+.ie n .IP """HAS_SOCKATMARK_PROTO""" 4
+.el .IP \f(CWHAS_SOCKATMARK_PROTO\fR 4
+.IX Xref "HAS_SOCKATMARK_PROTO"
+.IX Item "HAS_SOCKATMARK_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWsockatmark()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern int sockatmark(int);
+.Ve
+.ie n .IP """HAS_SYSCALL_PROTO""" 4
+.el .IP \f(CWHAS_SYSCALL_PROTO\fR 4
+.IX Xref "HAS_SYSCALL_PROTO"
+.IX Item "HAS_SYSCALL_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWsyscall()\fR function.  Otherwise, it is up
+to the program to supply one.  Good guesses are
+.Sp
+.Vb 2
+\& extern int syscall(int,  ...);
+\& extern int syscall(long, ...);
+.Ve
+.ie n .IP """HAS_TELLDIR_PROTO""" 4
+.el .IP \f(CWHAS_TELLDIR_PROTO\fR 4
+.IX Xref "HAS_TELLDIR_PROTO"
+.IX Item "HAS_TELLDIR_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWtelldir()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern long telldir(DIR*);
+.Ve
+.ie n .IP """NDBM_H_USES_PROTOTYPES""" 4
+.el .IP \f(CWNDBM_H_USES_PROTOTYPES\fR 4
+.IX Xref "NDBM_H_USES_PROTOTYPES"
+.IX Item "NDBM_H_USES_PROTOTYPES"
+This symbol, if defined, indicates that \fIndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
+prototypes instead of K&R style function declarations without any
+parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
+K&R style function declarations will yield errors.
+.ie n .IP """RANDOM_R_PROTO""" 4
+.el .IP \f(CWRANDOM_R_PROTO\fR 4
+.IX Xref "RANDOM_R_PROTO"
+.IX Item "RANDOM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`random_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_random_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_random_r\*(C'\fR
+is defined.
+.ie n .IP """READDIR_R_PROTO""" 4
+.el .IP \f(CWREADDIR_R_PROTO\fR 4
+.IX Xref "READDIR_R_PROTO"
+.IX Item "READDIR_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`readdir_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_readdir_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir_r\*(C'\fR
+is defined.
+.ie n .IP """SETGRENT_R_PROTO""" 4
+.el .IP \f(CWSETGRENT_R_PROTO\fR 4
+.IX Xref "SETGRENT_R_PROTO"
+.IX Item "SETGRENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setgrent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setgrent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setgrent_r\*(C'\fR
+is defined.
+.ie n .IP """SETHOSTENT_R_PROTO""" 4
+.el .IP \f(CWSETHOSTENT_R_PROTO\fR 4
+.IX Xref "SETHOSTENT_R_PROTO"
+.IX Item "SETHOSTENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`sethostent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_sethostent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_sethostent_r\*(C'\fR
+is defined.
+.ie n .IP """SETLOCALE_R_PROTO""" 4
+.el .IP \f(CWSETLOCALE_R_PROTO\fR 4
+.IX Xref "SETLOCALE_R_PROTO"
+.IX Item "SETLOCALE_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setlocale_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setlocale_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setlocale_r\*(C'\fR
+is defined.
+.ie n .IP """SETNETENT_R_PROTO""" 4
+.el .IP \f(CWSETNETENT_R_PROTO\fR 4
+.IX Xref "SETNETENT_R_PROTO"
+.IX Item "SETNETENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setnetent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setnetent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setnetent_r\*(C'\fR
+is defined.
+.ie n .IP """SETPROTOENT_R_PROTO""" 4
+.el .IP \f(CWSETPROTOENT_R_PROTO\fR 4
+.IX Xref "SETPROTOENT_R_PROTO"
+.IX Item "SETPROTOENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setprotoent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setprotoent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setprotoent_r\*(C'\fR
+is defined.
+.ie n .IP """SETPWENT_R_PROTO""" 4
+.el .IP \f(CWSETPWENT_R_PROTO\fR 4
+.IX Xref "SETPWENT_R_PROTO"
+.IX Item "SETPWENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setpwent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setpwent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setpwent_r\*(C'\fR
+is defined.
+.ie n .IP """SETSERVENT_R_PROTO""" 4
+.el .IP \f(CWSETSERVENT_R_PROTO\fR 4
+.IX Xref "SETSERVENT_R_PROTO"
+.IX Item "SETSERVENT_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`setservent_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_setservent_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setservent_r\*(C'\fR
+is defined.
+.ie n .IP """SRANDOM_R_PROTO""" 4
+.el .IP \f(CWSRANDOM_R_PROTO\fR 4
+.IX Xref "SRANDOM_R_PROTO"
+.IX Item "SRANDOM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`srandom_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_srandom_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srandom_r\*(C'\fR
+is defined.
+.ie n .IP """SRAND48_R_PROTO""" 4
+.el .IP \f(CWSRAND48_R_PROTO\fR 4
+.IX Xref "SRAND48_R_PROTO"
+.IX Item "SRAND48_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`srand48_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_srand48_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srand48_r\*(C'\fR
+is defined.
+.ie n .IP """STRERROR_R_PROTO""" 4
+.el .IP \f(CWSTRERROR_R_PROTO\fR 4
+.IX Xref "STRERROR_R_PROTO"
+.IX Item "STRERROR_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`strerror_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_strerror_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_strerror_r\*(C'\fR
+is defined.
+.ie n .IP """TMPNAM_R_PROTO""" 4
+.el .IP \f(CWTMPNAM_R_PROTO\fR 4
+.IX Xref "TMPNAM_R_PROTO"
+.IX Item "TMPNAM_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`tmpnam_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_tmpnam_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_tmpnam_r\*(C'\fR
+is defined.
+.ie n .IP """TTYNAME_R_PROTO""" 4
+.el .IP \f(CWTTYNAME_R_PROTO\fR 4
+.IX Xref "TTYNAME_R_PROTO"
+.IX Item "TTYNAME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`ttyname_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_ttyname_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ttyname_r\*(C'\fR
+is defined.
+.SH "REGEXP Functions"
+.IX Header "REGEXP Functions"
+.ie n .IP """pregcomp""" 4
+.el .IP \f(CWpregcomp\fR 4
+.IX Item "pregcomp"
+Described in perlreguts.
+.RS 4
+.Sp
+.Vb 1
+\& REGEXP *  pregcomp(SV * const pattern, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pregexec""" 4
+.el .IP \f(CWpregexec\fR 4
+.IX Item "pregexec"
+Described in perlreguts.
+.RS 4
+.Sp
+.Vb 3
+\& I32  pregexec(REGEXP * const prog, char *stringarg, char *strend,
+\&               char *strbeg, SSize_t minend, SV *screamer,
+\&               U32 nosave)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """re_compile""" 4
+.el .IP \f(CWre_compile\fR 4
+.IX Xref "re_compile"
+.IX Item "re_compile"
+Compile the regular expression pattern \f(CW\*(C`pattern\*(C'\fR, returning a pointer to the
+compiled object for later matching with the internal regex engine.
+.Sp
+This function is typically used by a custom regexp engine \f(CW\*(C`.comp()\*(C'\fR function
+to hand off to the core regexp engine those patterns it doesn't want to handle
+itself (typically passing through the same flags it was called with).  In
+almost all other cases, a regexp should be compiled by calling "\f(CW\*(C`pregcomp\*(C'\fR"
+to compile using the currently active regexp engine.
+.Sp
+If \f(CW\*(C`pattern\*(C'\fR is already a \f(CW\*(C`REGEXP\*(C'\fR, this function does nothing but return a
+pointer to the input.  Otherwise the PV is extracted and treated like a string
+representing a pattern.  See perlre.
+.Sp
+The possible flags for \f(CW\*(C`rx_flags\*(C'\fR are documented in perlreapi.  Their names
+all begin with \f(CW\*(C`RXf_\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& REGEXP *  re_compile(SV * const pattern, U32 orig_rx_flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """re_dup_guts""" 4
+.el .IP \f(CWre_dup_guts\fR 4
+.IX Xref "re_dup_guts"
+.IX Item "re_dup_guts"
+Duplicate a regexp.
+.Sp
+This routine is expected to clone a given regexp structure. It is only
+compiled under USE_ITHREADS.
+.Sp
+After all of the core data stored in struct regexp is duplicated
+the \f(CW\*(C`regexp_engine.dupe\*(C'\fR method is used to copy any private data
+stored in the *pprivate pointer. This allows extensions to handle
+any duplication they need to do.
+.RS 4
+.Sp
+.Vb 2
+\& void  re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
+\&                   CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """REGEX_LOCALE_CHARSET""" 4
+.el .IP \f(CWREGEX_LOCALE_CHARSET\fR 4
+.IX Item "REGEX_LOCALE_CHARSET"
+Described in perlreapi.
+.ie n .IP """REGEXP""" 4
+.el .IP \f(CWREGEXP\fR 4
+.IX Item "REGEXP"
+Described in perlreapi.
+.ie n .IP """regexp_engine""" 4
+.el .IP \f(CWregexp_engine\fR 4
+.IX Xref "regexp_engine"
+.IX Item "regexp_engine"
+When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at
+the appropriate structure, so that when it needs to be used Perl can find
+the right routines to do so.
+.Sp
+In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set
+to an integer which (when casted appropriately) resolves to one of these
+structures.  When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the
+resulting \f(CW\*(C`regexp\*(C'\fR structure's engine field is expected to point back at
+the same structure.
+.Sp
+The pTHX_ symbol in the definition is a macro used by Perl under threading
+to provide an extra argument to the routine holding a pointer back to
+the interpreter that is executing the regexp. So under threading all
+routines get an extra argument.
+.ie n .IP """regexp_paren_pair""" 4
+.el .IP \f(CWregexp_paren_pair\fR 4
+.IX Item "regexp_paren_pair"
+Described in perlreapi.
+.ie n .IP """regmatch_info""" 4
+.el .IP \f(CWregmatch_info\fR 4
+.IX Xref "regmatch_info"
+.IX Item "regmatch_info"
+Some basic information about the current match that is created by
+Perl_regexec_flags and then passed to \fBregtry()\fR, \fBregmatch()\fR etc.
+It is allocated as a local var on the stack, so nothing should be
+stored in it that needs preserving or clearing up on \fBcroak()\fR.
+For that, see the aux_info and aux_info_eval members of the
+regmatch_state union.
+.ie n .IP """REXEC_COPY_SKIP_POST""" 4
+.el .IP \f(CWREXEC_COPY_SKIP_POST\fR 4
+.IX Item "REXEC_COPY_SKIP_POST"
+.PD 0
+.ie n .IP """REXEC_COPY_SKIP_PRE""" 4
+.el .IP \f(CWREXEC_COPY_SKIP_PRE\fR 4
+.IX Item "REXEC_COPY_SKIP_PRE"
+.ie n .IP """REXEC_COPY_STR""" 4
+.el .IP \f(CWREXEC_COPY_STR\fR 4
+.IX Item "REXEC_COPY_STR"
+.PD
+Described in perlreapi.
+.ie n .IP """RXapif_ALL""" 4
+.el .IP \f(CWRXapif_ALL\fR 4
+.IX Item "RXapif_ALL"
+.PD 0
+.ie n .IP """RXapif_CLEAR""" 4
+.el .IP \f(CWRXapif_CLEAR\fR 4
+.IX Item "RXapif_CLEAR"
+.ie n .IP """RXapif_DELETE""" 4
+.el .IP \f(CWRXapif_DELETE\fR 4
+.IX Item "RXapif_DELETE"
+.ie n .IP """RXapif_EXISTS""" 4
+.el .IP \f(CWRXapif_EXISTS\fR 4
+.IX Item "RXapif_EXISTS"
+.ie n .IP """RXapif_FETCH""" 4
+.el .IP \f(CWRXapif_FETCH\fR 4
+.IX Item "RXapif_FETCH"
+.ie n .IP """RXapif_FIRSTKEY""" 4
+.el .IP \f(CWRXapif_FIRSTKEY\fR 4
+.IX Item "RXapif_FIRSTKEY"
+.ie n .IP """RXapif_NEXTKEY""" 4
+.el .IP \f(CWRXapif_NEXTKEY\fR 4
+.IX Item "RXapif_NEXTKEY"
+.ie n .IP """RXapif_ONE""" 4
+.el .IP \f(CWRXapif_ONE\fR 4
+.IX Item "RXapif_ONE"
+.ie n .IP """RXapif_REGNAME""" 4
+.el .IP \f(CWRXapif_REGNAME\fR 4
+.IX Item "RXapif_REGNAME"
+.ie n .IP """RXapif_REGNAMES""" 4
+.el .IP \f(CWRXapif_REGNAMES\fR 4
+.IX Item "RXapif_REGNAMES"
+.ie n .IP """RXapif_REGNAMES_COUNT""" 4
+.el .IP \f(CWRXapif_REGNAMES_COUNT\fR 4
+.IX Item "RXapif_REGNAMES_COUNT"
+.ie n .IP """RXapif_SCALAR""" 4
+.el .IP \f(CWRXapif_SCALAR\fR 4
+.IX Item "RXapif_SCALAR"
+.ie n .IP """RXapif_STORE""" 4
+.el .IP \f(CWRXapif_STORE\fR 4
+.IX Item "RXapif_STORE"
+.PD
+Described in perlreapi.
+.ie n .IP """RX_BUFF_IDX_CARET_FULLMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_CARET_FULLMATCH\fR 4
+.IX Item "RX_BUFF_IDX_CARET_FULLMATCH"
+.PD 0
+.ie n .IP """RX_BUFF_IDX_CARET_POSTMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_CARET_POSTMATCH\fR 4
+.IX Item "RX_BUFF_IDX_CARET_POSTMATCH"
+.ie n .IP """RX_BUFF_IDX_CARET_PREMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_CARET_PREMATCH\fR 4
+.IX Item "RX_BUFF_IDX_CARET_PREMATCH"
+.ie n .IP """RX_BUFF_IDX_FULLMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_FULLMATCH\fR 4
+.IX Item "RX_BUFF_IDX_FULLMATCH"
+.ie n .IP """RX_BUFF_IDX_POSTMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_POSTMATCH\fR 4
+.IX Item "RX_BUFF_IDX_POSTMATCH"
+.ie n .IP """RX_BUFF_IDX_PREMATCH""" 4
+.el .IP \f(CWRX_BUFF_IDX_PREMATCH\fR 4
+.IX Item "RX_BUFF_IDX_PREMATCH"
+.PD
+Described in perlreapi.
+.ie n .IP """RXf_NO_INPLACE_SUBST""" 4
+.el .IP \f(CWRXf_NO_INPLACE_SUBST\fR 4
+.IX Item "RXf_NO_INPLACE_SUBST"
+.PD 0
+.ie n .IP """RXf_NULL""" 4
+.el .IP \f(CWRXf_NULL\fR 4
+.IX Item "RXf_NULL"
+.ie n .IP """RXf_SKIPWHITE""" 4
+.el .IP \f(CWRXf_SKIPWHITE\fR 4
+.IX Item "RXf_SKIPWHITE"
+.ie n .IP """RXf_SPLIT""" 4
+.el .IP \f(CWRXf_SPLIT\fR 4
+.IX Item "RXf_SPLIT"
+.ie n .IP """RXf_START_ONLY""" 4
+.el .IP \f(CWRXf_START_ONLY\fR 4
+.IX Item "RXf_START_ONLY"
+.ie n .IP """RXf_WHITE""" 4
+.el .IP \f(CWRXf_WHITE\fR 4
+.IX Item "RXf_WHITE"
+.PD
+Described in perlreapi.
+.ie n .IP """RXf_PMf_EXTENDED""" 4
+.el .IP \f(CWRXf_PMf_EXTENDED\fR 4
+.IX Item "RXf_PMf_EXTENDED"
+.PD 0
+.ie n .IP """RXf_PMf_FOLD""" 4
+.el .IP \f(CWRXf_PMf_FOLD\fR 4
+.IX Item "RXf_PMf_FOLD"
+.ie n .IP """RXf_PMf_KEEPCOPY""" 4
+.el .IP \f(CWRXf_PMf_KEEPCOPY\fR 4
+.IX Item "RXf_PMf_KEEPCOPY"
+.ie n .IP """RXf_PMf_MULTILINE""" 4
+.el .IP \f(CWRXf_PMf_MULTILINE\fR 4
+.IX Item "RXf_PMf_MULTILINE"
+.ie n .IP """RXf_PMf_SINGLELINE""" 4
+.el .IP \f(CWRXf_PMf_SINGLELINE\fR 4
+.IX Item "RXf_PMf_SINGLELINE"
+.PD
+Described in perlreapi.
+.ie n .IP """RX_MATCH_COPIED""" 4
+.el .IP \f(CWRX_MATCH_COPIED\fR 4
+.IX Item "RX_MATCH_COPIED"
+Described in perlreapi.
+.RS 4
+.Sp
+.Vb 1
+\&   RX_MATCH_COPIED(const REGEXP * rx)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RX_OFFS""" 4
+.el .IP \f(CWRX_OFFS\fR 4
+.IX Item "RX_OFFS"
+Described in perlreapi.
+.RS 4
+.Sp
+.Vb 1
+\&   RX_OFFS(const REGEXP * rx_sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvRX""" 4
+.el .IP \f(CWSvRX\fR 4
+.IX Xref "SvRX"
+.IX Item "SvRX"
+Convenience macro to get the REGEXP from a SV.  This is approximately
+equivalent to the following snippet:
+.Sp
+.Vb 6
+\&    if (SvMAGICAL(sv))
+\&        mg_get(sv);
+\&    if (SvROK(sv))
+\&        sv = MUTABLE_SV(SvRV(sv));
+\&    if (SvTYPE(sv) == SVt_REGEXP)
+\&        return (REGEXP*) sv;
+.Ve
+.Sp
+\&\f(CW\*(C`NULL\*(C'\fR will be returned if a REGEXP* is not found.
+.RS 4
+.Sp
+.Vb 1
+\& REGEXP *  SvRX(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvRXOK""" 4
+.el .IP \f(CWSvRXOK\fR 4
+.IX Xref "SvRXOK"
+.IX Item "SvRXOK"
+Returns a boolean indicating whether the SV (or the one it references)
+is a REGEXP.
+.Sp
+If you want to do something with the REGEXP* later use SvRX instead
+and check for NULL.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvRXOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SV_SAVED_COPY""" 4
+.el .IP \f(CWSV_SAVED_COPY\fR 4
+.IX Item "SV_SAVED_COPY"
+Described in perlreapi.
+.SH "Reports and Formats"
+.IX Header "Reports and Formats"
+These are used in the simple report generation feature of Perl.
+See perlform.
+.ie n .IP """IoBOTTOM_GV""" 4
+.el .IP \f(CWIoBOTTOM_GV\fR 4
+.IX Item "IoBOTTOM_GV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  IoBOTTOM_GV(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoBOTTOM_NAME""" 4
+.el .IP \f(CWIoBOTTOM_NAME\fR 4
+.IX Item "IoBOTTOM_NAME"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& char *  IoBOTTOM_NAME(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoFMT_GV""" 4
+.el .IP \f(CWIoFMT_GV\fR 4
+.IX Item "IoFMT_GV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  IoFMT_GV(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoFMT_NAME""" 4
+.el .IP \f(CWIoFMT_NAME\fR 4
+.IX Item "IoFMT_NAME"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& char *  IoFMT_NAME(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoLINES""" 4
+.el .IP \f(CWIoLINES\fR 4
+.IX Item "IoLINES"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IoLINES(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoLINES_LEFT""" 4
+.el .IP \f(CWIoLINES_LEFT\fR 4
+.IX Item "IoLINES_LEFT"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IoLINES_LEFT(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoPAGE""" 4
+.el .IP \f(CWIoPAGE\fR 4
+.IX Item "IoPAGE"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IoPAGE(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoPAGE_LEN""" 4
+.el .IP \f(CWIoPAGE_LEN\fR 4
+.IX Item "IoPAGE_LEN"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& IV  IoPAGE_LEN(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoTOP_GV""" 4
+.el .IP \f(CWIoTOP_GV\fR 4
+.IX Item "IoTOP_GV"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  IoTOP_GV(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IoTOP_NAME""" 4
+.el .IP \f(CWIoTOP_NAME\fR 4
+.IX Item "IoTOP_NAME"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& char *  IoTOP_NAME(IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Signals
+.IX Header "Signals"
+.ie n .IP """HAS_SIGINFO_SI_ADDR""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_ADDR\fR 4
+.IX Xref "HAS_SIGINFO_SI_ADDR"
+.IX Item "HAS_SIGINFO_SI_ADDR"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_addr\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_BAND""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_BAND\fR 4
+.IX Xref "HAS_SIGINFO_SI_BAND"
+.IX Item "HAS_SIGINFO_SI_BAND"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_band\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_ERRNO""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_ERRNO\fR 4
+.IX Xref "HAS_SIGINFO_SI_ERRNO"
+.IX Item "HAS_SIGINFO_SI_ERRNO"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_errno\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_PID""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_PID\fR 4
+.IX Xref "HAS_SIGINFO_SI_PID"
+.IX Item "HAS_SIGINFO_SI_PID"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_pid\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_STATUS""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_STATUS\fR 4
+.IX Xref "HAS_SIGINFO_SI_STATUS"
+.IX Item "HAS_SIGINFO_SI_STATUS"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_status\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_UID""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_UID\fR 4
+.IX Xref "HAS_SIGINFO_SI_UID"
+.IX Item "HAS_SIGINFO_SI_UID"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_uid\*(C'\fR member
+.ie n .IP """HAS_SIGINFO_SI_VALUE""" 4
+.el .IP \f(CWHAS_SIGINFO_SI_VALUE\fR 4
+.IX Xref "HAS_SIGINFO_SI_VALUE"
+.IX Item "HAS_SIGINFO_SI_VALUE"
+This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
+\&\f(CW\*(C`si_value\*(C'\fR member
+.ie n .IP """PERL_SIGNALS_UNSAFE_FLAG""" 4
+.el .IP \f(CWPERL_SIGNALS_UNSAFE_FLAG\fR 4
+.IX Xref "PERL_SIGNALS_UNSAFE_FLAG"
+.IX Item "PERL_SIGNALS_UNSAFE_FLAG"
+If this bit in \f(CW\*(C`PL_signals\*(C'\fR is set, the system is uing the pre-Perl 5.8
+unsafe signals.  See "PERL_SIGNALS" in perlrun and "Deferred Signals
+(Safe Signals)" in perlipc.
+.RS 4
+.Sp
+.Vb 1
+\& U32  PERL_SIGNALS_UNSAFE_FLAG
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """rsignal""" 4
+.el .IP \f(CWrsignal\fR 4
+.IX Xref "rsignal"
+.IX Item "rsignal"
+A wrapper for the C library functions \fBsigaction\fR\|(2) or \fBsignal\fR\|(2).
+Use this instead of those libc functions, as the Perl version gives the
+safest available implementation, and knows things that interact with the
+rest of the perl interpreter.
+.RS 4
+.Sp
+.Vb 1
+\& Sighandler_t  rsignal(int i, Sighandler_t t)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """rsignal_state""" 4
+.el .IP \f(CWrsignal_state\fR 4
+.IX Xref "rsignal_state"
+.IX Item "rsignal_state"
+Returns a the current signal handler for signal \f(CW\*(C`signo\*(C'\fR.
+See "\f(CW\*(C`rsignal\*(C'\fR".
+.RS 4
+.Sp
+.Vb 1
+\& Sighandler_t  rsignal_state(int i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Sigjmp_buf""" 4
+.el .IP \f(CWSigjmp_buf\fR 4
+.IX Xref "Sigjmp_buf"
+.IX Item "Sigjmp_buf"
+This is the buffer type to be used with Sigsetjmp and Siglongjmp.
+.ie n .IP """Siglongjmp""" 4
+.el .IP \f(CWSiglongjmp\fR 4
+.IX Xref "Siglongjmp"
+.IX Item "Siglongjmp"
+This macro is used in the same way as \f(CWsiglongjmp()\fR, but will invoke
+traditional \f(CWlongjmp()\fR if siglongjmp isn't available.
+See \f(CW"HAS_SIGSETJMP"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  Siglongjmp(jmp_buf env, int val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SIG_NAME""" 4
+.el .IP \f(CWSIG_NAME\fR 4
+.IX Xref "SIG_NAME"
+.IX Item "SIG_NAME"
+This symbol contains a list of signal names in order of
+signal number. This is intended
+to be used as a static array initialization, like this:
+.Sp
+.Vb 1
+\& char *sig_name[] = { SIG_NAME };
+.Ve
+.Sp
+The signals in the list are separated with commas, and each signal
+is surrounded by double quotes. There is no leading \f(CW\*(C`SIG\*(C'\fR in the signal
+name, i.e. \f(CW\*(C`SIGQUIT\*(C'\fR is known as "\f(CW\*(C`QUIT\*(C'\fR".
+Gaps in the signal numbers (up to \f(CW\*(C`NSIG\*(C'\fR) are filled in with \f(CW\*(C`NUMnn\*(C'\fR,
+etc., where nn is the actual signal number (e.g. \f(CW\*(C`NUM37\*(C'\fR).
+The signal number for \f(CW\*(C`sig_name[i]\*(C'\fR is stored in \f(CW\*(C`sig_num[i]\*(C'\fR.
+The last element is 0 to terminate the list with a \f(CW\*(C`NULL\*(C'\fR.  This
+corresponds to the 0 at the end of the \f(CW\*(C`sig_name_init\*(C'\fR list.
+Note that this variable is initialized from the \f(CW\*(C`sig_name_init\*(C'\fR,
+not from \f(CW\*(C`sig_name\*(C'\fR (which is unused).
+.ie n .IP """SIG_NUM""" 4
+.el .IP \f(CWSIG_NUM\fR 4
+.IX Xref "SIG_NUM"
+.IX Item "SIG_NUM"
+This symbol contains a list of signal numbers, in the same order as the
+\&\f(CW\*(C`SIG_NAME\*(C'\fR list. It is suitable for static array initialization, as in:
+.Sp
+.Vb 1
+\& int sig_num[] = { SIG_NUM };
+.Ve
+.Sp
+The signals in the list are separated with commas, and the indices
+within that list and the \f(CW\*(C`SIG_NAME\*(C'\fR list match, so it's easy to compute
+the signal name from a number or vice versa at the price of a small
+dynamic linear lookup.
+Duplicates are allowed, but are moved to the end of the list.
+The signal number corresponding to \f(CW\*(C`sig_name[i]\*(C'\fR is \f(CW\*(C`sig_number[i]\*(C'\fR.
+if (i < \f(CW\*(C`NSIG\*(C'\fR) then \f(CW\*(C`sig_number[i]\*(C'\fR == i.
+The last element is 0, corresponding to the 0 at the end of
+the \f(CW\*(C`sig_name_init\*(C'\fR list.
+Note that this variable is initialized from the \f(CW\*(C`sig_num_init\*(C'\fR,
+not from \f(CW\*(C`sig_num\*(C'\fR (which is unused).
+.ie n .IP """Sigsetjmp""" 4
+.el .IP \f(CWSigsetjmp\fR 4
+.IX Xref "Sigsetjmp"
+.IX Item "Sigsetjmp"
+This macro is used in the same way as \f(CWsigsetjmp()\fR, but will invoke
+traditional \f(CWsetjmp()\fR if sigsetjmp isn't available.
+See \f(CW"HAS_SIGSETJMP"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  Sigsetjmp(jmp_buf env, int savesigs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SIG_SIZE""" 4
+.el .IP \f(CWSIG_SIZE\fR 4
+.IX Xref "SIG_SIZE"
+.IX Item "SIG_SIZE"
+This variable contains the number of elements of the \f(CW\*(C`SIG_NAME\*(C'\fR
+and \f(CW\*(C`SIG_NUM\*(C'\fR arrays, excluding the final \f(CW\*(C`NULL\*(C'\fR entry.
+.ie n .IP """whichsig""" 4
+.el .IP \f(CWwhichsig\fR 4
+.IX Item "whichsig"
+.PD 0
+.ie n .IP """whichsig_pv""" 4
+.el .IP \f(CWwhichsig_pv\fR 4
+.IX Item "whichsig_pv"
+.ie n .IP """whichsig_pvn""" 4
+.el .IP \f(CWwhichsig_pvn\fR 4
+.IX Item "whichsig_pvn"
+.ie n .IP """whichsig_sv""" 4
+.el .IP \f(CWwhichsig_sv\fR 4
+.IX Xref "whichsig whichsig_pv whichsig_pvn whichsig_sv"
+.IX Item "whichsig_sv"
+.PD
+These all convert a signal name into its corresponding signal number;
+returning \-1 if no corresponding number was found.
+.Sp
+They differ only in the source of the signal name:
+.Sp
+\&\f(CW\*(C`whichsig_pv\*(C'\fR takes the name from the \f(CW\*(C`NUL\*(C'\fR\-terminated string starting at
+\&\f(CW\*(C`sig\*(C'\fR.
+.Sp
+\&\f(CW\*(C`whichsig\*(C'\fR is merely a different spelling, a synonym, of \f(CW\*(C`whichsig_pv\*(C'\fR.
+.Sp
+\&\f(CW\*(C`whichsig_pvn\*(C'\fR takes the name from the string starting at \f(CW\*(C`sig\*(C'\fR, with length
+\&\f(CW\*(C`len\*(C'\fR bytes.
+.Sp
+\&\f(CW\*(C`whichsig_sv\*(C'\fR takes the name from the PV stored in the SV \f(CW\*(C`sigsv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 4
+\& I32  whichsig    (const char *sig)
+\& I32  whichsig_pv (const char *sig)
+\& I32  whichsig_pvn(const char *sig, STRLEN len)
+\& I32  whichsig_sv (SV *sigsv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Site configuration"
+.IX Header "Site configuration"
+These variables give details as to where various libraries,
+installation destinations, \fIetc.\fR, go, as well as what various
+installation options were selected
+.ie n .IP """ARCHLIB""" 4
+.el .IP \f(CWARCHLIB\fR 4
+.IX Xref "ARCHLIB"
+.IX Item "ARCHLIB"
+This variable, if defined, holds the name of the directory in
+which the user wants to put architecture-dependent public
+library files for perl5.  It is most often a local directory
+such as \fI/usr/local/lib\fR.  Programs using this variable must be
+prepared to deal with filename expansion.  If \f(CW\*(C`ARCHLIB\*(C'\fR is the
+same as \f(CW\*(C`PRIVLIB\*(C'\fR, it is not defined, since presumably the
+program already searches \f(CW\*(C`PRIVLIB\*(C'\fR.
+.ie n .IP """ARCHLIB_EXP""" 4
+.el .IP \f(CWARCHLIB_EXP\fR 4
+.IX Xref "ARCHLIB_EXP"
+.IX Item "ARCHLIB_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`ARCHLIB\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """ARCHNAME""" 4
+.el .IP \f(CWARCHNAME\fR 4
+.IX Xref "ARCHNAME"
+.IX Item "ARCHNAME"
+This symbol holds a string representing the architecture name.
+It may be used to construct an architecture-dependant pathname
+where library files may be held under a private library, for
+instance.
+.ie n .IP """BIN""" 4
+.el .IP \f(CWBIN\fR 4
+.IX Xref "BIN"
+.IX Item "BIN"
+This symbol holds the path of the bin directory where the package will
+be installed. Program must be prepared to deal with ~name substitution.
+.ie n .IP """BIN_EXP""" 4
+.el .IP \f(CWBIN_EXP\fR 4
+.IX Xref "BIN_EXP"
+.IX Item "BIN_EXP"
+This symbol is the filename expanded version of the \f(CW\*(C`BIN\*(C'\fR symbol, for
+programs that do not want to deal with that at run-time.
+.ie n .IP """INSTALL_USR_BIN_PERL""" 4
+.el .IP \f(CWINSTALL_USR_BIN_PERL\fR 4
+.IX Xref "INSTALL_USR_BIN_PERL"
+.IX Item "INSTALL_USR_BIN_PERL"
+This symbol, if defined, indicates that Perl is to be installed
+also as \fI/usr/bin/perl\fR.
+.ie n .IP """MULTIARCH""" 4
+.el .IP \f(CWMULTIARCH\fR 4
+.IX Xref "MULTIARCH"
+.IX Item "MULTIARCH"
+This symbol, if defined, signifies that the build
+process will produce some binary files that are going to be
+used in a cross-platform environment.  This is the case for
+example with the NeXT "fat" binaries that contain executables
+for several \f(CW\*(C`CPUs\*(C'\fR.
+.ie n .IP """PERL_INC_VERSION_LIST""" 4
+.el .IP \f(CWPERL_INC_VERSION_LIST\fR 4
+.IX Xref "PERL_INC_VERSION_LIST"
+.IX Item "PERL_INC_VERSION_LIST"
+This variable specifies the list of subdirectories in over
+which \fIperl.c\fR:\f(CWincpush()\fR and \fIlib/lib.pm\fR will automatically
+search when adding directories to @\f(CW\*(C`INC\*(C'\fR, in a format suitable
+for a C initialization string.  See the \f(CW\*(C`inc_version_list\*(C'\fR entry
+in Porting/Glossary for more details.
+.ie n .IP """PERL_OTHERLIBDIRS""" 4
+.el .IP \f(CWPERL_OTHERLIBDIRS\fR 4
+.IX Xref "PERL_OTHERLIBDIRS"
+.IX Item "PERL_OTHERLIBDIRS"
+This variable contains a colon-separated set of paths for the perl
+binary to search for additional library files or modules.
+These directories will be tacked to the end of @\f(CW\*(C`INC\*(C'\fR.
+Perl will automatically search below each path for version\-
+and architecture-specific directories.  See \f(CW"PERL_INC_VERSION_LIST"\fR
+for more details.
+.ie n .IP """PERL_RELOCATABLE_INC""" 4
+.el .IP \f(CWPERL_RELOCATABLE_INC\fR 4
+.IX Xref "PERL_RELOCATABLE_INC"
+.IX Item "PERL_RELOCATABLE_INC"
+This symbol, if defined, indicates that we'd like to relocate entries
+in @\f(CW\*(C`INC\*(C'\fR at run time based on the location of the perl binary.
+.ie n .IP """PERL_TARGETARCH""" 4
+.el .IP \f(CWPERL_TARGETARCH\fR 4
+.IX Xref "PERL_TARGETARCH"
+.IX Item "PERL_TARGETARCH"
+This symbol, if defined, indicates the target architecture
+Perl has been cross-compiled to.  Undefined if not a cross-compile.
+.ie n .IP """PERL_USE_DEVEL""" 4
+.el .IP \f(CWPERL_USE_DEVEL\fR 4
+.IX Xref "PERL_USE_DEVEL"
+.IX Item "PERL_USE_DEVEL"
+This symbol, if defined, indicates that Perl was configured with
+\&\f(CW\*(C`\-Dusedevel\*(C'\fR, to enable development features.  This should not be
+done for production builds.
+.ie n .IP """PERL_VENDORARCH""" 4
+.el .IP \f(CWPERL_VENDORARCH\fR 4
+.IX Xref "PERL_VENDORARCH"
+.IX Item "PERL_VENDORARCH"
+If defined, this symbol contains the name of a private library.
+The library is private in the sense that it needn't be in anyone's
+execution path, but it should be accessible by the world.
+It may have a ~ on the front.
+The standard distribution will put nothing in this directory.
+Vendors who distribute perl may wish to place their own
+architecture-dependent modules and extensions in this directory with
+.Sp
+.Vb 1
+\& MakeMaker Makefile.PL INSTALLDIRS=vendor
+.Ve
+.Sp
+or equivalent.  See \f(CW\*(C`INSTALL\*(C'\fR for details.
+.ie n .IP """PERL_VENDORARCH_EXP""" 4
+.el .IP \f(CWPERL_VENDORARCH_EXP\fR 4
+.IX Xref "PERL_VENDORARCH_EXP"
+.IX Item "PERL_VENDORARCH_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`PERL_VENDORARCH\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """PERL_VENDORLIB_EXP""" 4
+.el .IP \f(CWPERL_VENDORLIB_EXP\fR 4
+.IX Xref "PERL_VENDORLIB_EXP"
+.IX Item "PERL_VENDORLIB_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`VENDORLIB\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """PERL_VENDORLIB_STEM""" 4
+.el .IP \f(CWPERL_VENDORLIB_STEM\fR 4
+.IX Xref "PERL_VENDORLIB_STEM"
+.IX Item "PERL_VENDORLIB_STEM"
+This define is \f(CW\*(C`PERL_VENDORLIB_EXP\*(C'\fR with any trailing version-specific component
+removed.  The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can
+be tacked onto this variable to generate a list of directories to search.
+.ie n .IP """PRIVLIB""" 4
+.el .IP \f(CWPRIVLIB\fR 4
+.IX Xref "PRIVLIB"
+.IX Item "PRIVLIB"
+This symbol contains the name of the private library for this package.
+The library is private in the sense that it needn't be in anyone's
+execution path, but it should be accessible by the world.  The program
+should be prepared to do ~ expansion.
+.ie n .IP """PRIVLIB_EXP""" 4
+.el .IP \f(CWPRIVLIB_EXP\fR 4
+.IX Xref "PRIVLIB_EXP"
+.IX Item "PRIVLIB_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`PRIVLIB\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """SITEARCH""" 4
+.el .IP \f(CWSITEARCH\fR 4
+.IX Xref "SITEARCH"
+.IX Item "SITEARCH"
+This symbol contains the name of the private library for this package.
+The library is private in the sense that it needn't be in anyone's
+execution path, but it should be accessible by the world.  The program
+should be prepared to do ~ expansion.
+The standard distribution will put nothing in this directory.
+After perl has been installed, users may install their own local
+architecture-dependent modules in this directory with
+.Sp
+.Vb 1
+\& MakeMaker Makefile.PL
+.Ve
+.Sp
+or equivalent.  See \f(CW\*(C`INSTALL\*(C'\fR for details.
+.ie n .IP """SITEARCH_EXP""" 4
+.el .IP \f(CWSITEARCH_EXP\fR 4
+.IX Xref "SITEARCH_EXP"
+.IX Item "SITEARCH_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`SITEARCH\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """SITELIB""" 4
+.el .IP \f(CWSITELIB\fR 4
+.IX Xref "SITELIB"
+.IX Item "SITELIB"
+This symbol contains the name of the private library for this package.
+The library is private in the sense that it needn't be in anyone's
+execution path, but it should be accessible by the world.  The program
+should be prepared to do ~ expansion.
+The standard distribution will put nothing in this directory.
+After perl has been installed, users may install their own local
+architecture-independent modules in this directory with
+.Sp
+.Vb 1
+\& MakeMaker Makefile.PL
+.Ve
+.Sp
+or equivalent.  See \f(CW\*(C`INSTALL\*(C'\fR for details.
+.ie n .IP """SITELIB_EXP""" 4
+.el .IP \f(CWSITELIB_EXP\fR 4
+.IX Xref "SITELIB_EXP"
+.IX Item "SITELIB_EXP"
+This symbol contains the ~name expanded version of \f(CW\*(C`SITELIB\*(C'\fR, to be used
+in programs that are not prepared to deal with ~ expansion at run-time.
+.ie n .IP """SITELIB_STEM""" 4
+.el .IP \f(CWSITELIB_STEM\fR 4
+.IX Xref "SITELIB_STEM"
+.IX Item "SITELIB_STEM"
+This define is \f(CW\*(C`SITELIB_EXP\*(C'\fR with any trailing version-specific component
+removed.  The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can
+be tacked onto this variable to generate a list of directories to search.
+.ie n .IP """STARTPERL""" 4
+.el .IP \f(CWSTARTPERL\fR 4
+.IX Xref "STARTPERL"
+.IX Item "STARTPERL"
+This variable contains the string to put in front of a perl
+script to make sure (one hopes) that it runs with perl and not
+some shell.
+.ie n .IP """USE_64_BIT_ALL""" 4
+.el .IP \f(CWUSE_64_BIT_ALL\fR 4
+.IX Xref "USE_64_BIT_ALL"
+.IX Item "USE_64_BIT_ALL"
+This symbol, if defined, indicates that 64\-bit integers should
+be used when available.  If not defined, the native integers
+will be used (be they 32 or 64 bits).  The maximal possible
+64\-bitness is employed: LP64 or \f(CW\*(C`ILP64\*(C'\fR, meaning that you will
+be able to use more than 2 gigabytes of memory.  This mode is
+even more binary incompatible than \f(CW\*(C`USE_64_BIT_INT\*(C'\fR. You may not
+be able to run the resulting executable in a 32\-bit \f(CW\*(C`CPU\*(C'\fR at all or
+you may need at least to reboot your OS to 64\-bit mode.
+.ie n .IP """USE_64_BIT_INT""" 4
+.el .IP \f(CWUSE_64_BIT_INT\fR 4
+.IX Xref "USE_64_BIT_INT"
+.IX Item "USE_64_BIT_INT"
+This symbol, if defined, indicates that 64\-bit integers should
+be used when available.  If not defined, the native integers
+will be employed (be they 32 or 64 bits).  The minimal possible
+64\-bitness is used, just enough to get 64\-bit integers into Perl.
+This may mean using for example "long longs", while your memory
+may still be limited to 2 gigabytes.
+.ie n .IP """USE_BSD_GETPGRP""" 4
+.el .IP \f(CWUSE_BSD_GETPGRP\fR 4
+.IX Xref "USE_BSD_GETPGRP"
+.IX Item "USE_BSD_GETPGRP"
+This symbol, if defined, indicates that getpgrp needs one
+arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none.
+.ie n .IP """USE_BSD_SETPGRP""" 4
+.el .IP \f(CWUSE_BSD_SETPGRP\fR 4
+.IX Xref "USE_BSD_SETPGRP"
+.IX Item "USE_BSD_SETPGRP"
+This symbol, if defined, indicates that setpgrp needs two
+arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none.  See also \f(CW"HAS_SETPGID"\fR
+for a \f(CW\*(C`POSIX\*(C'\fR interface.
+.ie n .IP """USE_C_BACKTRACE""" 4
+.el .IP \f(CWUSE_C_BACKTRACE\fR 4
+.IX Xref "USE_C_BACKTRACE"
+.IX Item "USE_C_BACKTRACE"
+This symbol, if defined, indicates that Perl should
+be built with support for backtrace.
+.ie n .IP """USE_CPLUSPLUS""" 4
+.el .IP \f(CWUSE_CPLUSPLUS\fR 4
+.IX Xref "USE_CPLUSPLUS"
+.IX Item "USE_CPLUSPLUS"
+This symbol, if defined, indicates that a C++ compiler was
+used to compiled Perl and will be used to compile extensions.
+.ie n .IP """USE_CROSS_COMPILE""" 4
+.el .IP \f(CWUSE_CROSS_COMPILE\fR 4
+.IX Xref "USE_CROSS_COMPILE"
+.IX Item "USE_CROSS_COMPILE"
+This symbol, if defined, indicates that Perl is being cross-compiled.
+.ie n .IP """USE_DTRACE""" 4
+.el .IP \f(CWUSE_DTRACE\fR 4
+.IX Xref "USE_DTRACE"
+.IX Item "USE_DTRACE"
+This symbol, if defined, indicates that Perl should
+be built with support for DTrace.
+.ie n .IP """USE_DYNAMIC_LOADING""" 4
+.el .IP \f(CWUSE_DYNAMIC_LOADING\fR 4
+.IX Xref "USE_DYNAMIC_LOADING"
+.IX Item "USE_DYNAMIC_LOADING"
+This symbol, if defined, indicates that dynamic loading of
+some sort is available.
+.ie n .IP """USE_FAST_STDIO""" 4
+.el .IP \f(CWUSE_FAST_STDIO\fR 4
+.IX Xref "USE_FAST_STDIO"
+.IX Item "USE_FAST_STDIO"
+This symbol, if defined, indicates that Perl should
+be built to use 'fast stdio'.
+Defaults to define in Perls 5.8 and earlier, to undef later.
+.ie n .IP """USE_ITHREADS""" 4
+.el .IP \f(CWUSE_ITHREADS\fR 4
+.IX Xref "USE_ITHREADS"
+.IX Item "USE_ITHREADS"
+This symbol, if defined, indicates that Perl should be built to
+use the interpreter-based threading implementation.
+.ie n .IP """USE_KERN_PROC_PATHNAME""" 4
+.el .IP \f(CWUSE_KERN_PROC_PATHNAME\fR 4
+.IX Xref "USE_KERN_PROC_PATHNAME"
+.IX Item "USE_KERN_PROC_PATHNAME"
+This symbol, if defined, indicates that we can use sysctl with
+\&\f(CW\*(C`KERN_PROC_PATHNAME\*(C'\fR to get a full path for the executable, and hence
+convert $^X to an absolute path.
+.ie n .IP """USE_LARGE_FILES""" 4
+.el .IP \f(CWUSE_LARGE_FILES\fR 4
+.IX Xref "USE_LARGE_FILES"
+.IX Item "USE_LARGE_FILES"
+This symbol, if defined, indicates that large file support
+should be used when available.
+.ie n .IP """USE_LONG_DOUBLE""" 4
+.el .IP \f(CWUSE_LONG_DOUBLE\fR 4
+.IX Xref "USE_LONG_DOUBLE"
+.IX Item "USE_LONG_DOUBLE"
+This symbol, if defined, indicates that long doubles should
+be used when available.
+.ie n .IP """USE_MORE_BITS""" 4
+.el .IP \f(CWUSE_MORE_BITS\fR 4
+.IX Xref "USE_MORE_BITS"
+.IX Item "USE_MORE_BITS"
+This symbol, if defined, indicates that 64\-bit interfaces and
+long doubles should be used when available.
+.ie n .IP """USE_NSGETEXECUTABLEPATH""" 4
+.el .IP \f(CWUSE_NSGETEXECUTABLEPATH\fR 4
+.IX Xref "USE_NSGETEXECUTABLEPATH"
+.IX Item "USE_NSGETEXECUTABLEPATH"
+This symbol, if defined, indicates that we can use \f(CW\*(C`_NSGetExecutablePath\*(C'\fR
+and realpath to get a full path for the executable, and hence convert
+$^X to an absolute path.
+.ie n .IP """USE_PERLIO""" 4
+.el .IP \f(CWUSE_PERLIO\fR 4
+.IX Xref "USE_PERLIO"
+.IX Item "USE_PERLIO"
+This symbol, if defined, indicates that the PerlIO abstraction should
+be used throughout.  If not defined, stdio should be
+used in a fully backward compatible manner.
+.ie n .IP """USE_QUADMATH""" 4
+.el .IP \f(CWUSE_QUADMATH\fR 4
+.IX Xref "USE_QUADMATH"
+.IX Item "USE_QUADMATH"
+This symbol, if defined, indicates that the quadmath library should
+be used when available.
+.ie n .IP """USE_REENTRANT_API""" 4
+.el .IP \f(CWUSE_REENTRANT_API\fR 4
+.IX Xref "USE_REENTRANT_API"
+.IX Item "USE_REENTRANT_API"
+This symbol, if defined, indicates that Perl should
+try to use the various \f(CW\*(C`_r\*(C'\fR versions of library functions.
+This is extremely experimental.
+.ie n .IP """USE_SEMCTL_SEMID_DS""" 4
+.el .IP \f(CWUSE_SEMCTL_SEMID_DS\fR 4
+.IX Xref "USE_SEMCTL_SEMID_DS"
+.IX Item "USE_SEMCTL_SEMID_DS"
+This symbol, if defined, indicates that \f(CW\*(C`struct semid_ds\*(C'\fR * is
+used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
+.ie n .IP """USE_SEMCTL_SEMUN""" 4
+.el .IP \f(CWUSE_SEMCTL_SEMUN\fR 4
+.IX Xref "USE_SEMCTL_SEMUN"
+.IX Item "USE_SEMCTL_SEMUN"
+This symbol, if defined, indicates that \f(CW\*(C`union semun\*(C'\fR is
+used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
+.ie n .IP """USE_SITECUSTOMIZE""" 4
+.el .IP \f(CWUSE_SITECUSTOMIZE\fR 4
+.IX Xref "USE_SITECUSTOMIZE"
+.IX Item "USE_SITECUSTOMIZE"
+This symbol, if defined, indicates that sitecustomize should
+be used.
+.ie n .IP """USE_SOCKS""" 4
+.el .IP \f(CWUSE_SOCKS\fR 4
+.IX Xref "USE_SOCKS"
+.IX Item "USE_SOCKS"
+This symbol, if defined, indicates that Perl should
+be built to use socks.
+.ie n .IP """USE_STAT_BLOCKS""" 4
+.el .IP \f(CWUSE_STAT_BLOCKS\fR 4
+.IX Xref "USE_STAT_BLOCKS"
+.IX Item "USE_STAT_BLOCKS"
+This symbol is defined if this system has a stat structure declaring
+\&\f(CW\*(C`st_blksize\*(C'\fR and \f(CW\*(C`st_blocks\*(C'\fR.
+.ie n .IP """USE_STDIO_BASE""" 4
+.el .IP \f(CWUSE_STDIO_BASE\fR 4
+.IX Xref "USE_STDIO_BASE"
+.IX Item "USE_STDIO_BASE"
+This symbol is defined if the \f(CW\*(C`_base\*(C'\fR field (or similar) of the
+stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer for
+a file handle.  If this is defined, then the \f(CWFILE_base(fp)\fR macro
+will also be defined and should be used to access this field.
+Also, the \f(CWFILE_bufsiz(fp)\fR macro will be defined and should be used
+to determine the number of bytes in the buffer.  \f(CW\*(C`USE_STDIO_BASE\*(C'\fR
+will never be defined unless \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is.
+.ie n .IP """USE_STDIO_PTR""" 4
+.el .IP \f(CWUSE_STDIO_PTR\fR 4
+.IX Xref "USE_STDIO_PTR"
+.IX Item "USE_STDIO_PTR"
+This symbol is defined if the \f(CW\*(C`_ptr\*(C'\fR and \f(CW\*(C`_cnt\*(C'\fR fields (or similar)
+of the stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer
+for a file handle.  If this is defined, then the \f(CWFILE_ptr(fp)\fR
+and \f(CWFILE_cnt(fp)\fR macros will also be defined and should be used
+to access these fields.
+.ie n .IP """USE_STRICT_BY_DEFAULT""" 4
+.el .IP \f(CWUSE_STRICT_BY_DEFAULT\fR 4
+.IX Xref "USE_STRICT_BY_DEFAULT"
+.IX Item "USE_STRICT_BY_DEFAULT"
+This symbol, if defined, enables additional defaults.
+At this time it only enables implicit strict by default.
+.ie n .IP """USE_THREADS""" 4
+.el .IP \f(CWUSE_THREADS\fR 4
+.IX Xref "USE_THREADS"
+.IX Item "USE_THREADS"
+This symbol, if defined, indicates that Perl should
+be built to use threads.  At present, it is a synonym for
+and \f(CW\*(C`USE_ITHREADS\*(C'\fR, but eventually the source ought to be
+changed to use this to mean \f(CW\*(C`_any_\*(C'\fR threading implementation.
+.SH "Sockets configuration values"
+.IX Header "Sockets configuration values"
+.ie n .IP """HAS_SOCKADDR_IN6""" 4
+.el .IP \f(CWHAS_SOCKADDR_IN6\fR 4
+.IX Xref "HAS_SOCKADDR_IN6"
+.IX Item "HAS_SOCKADDR_IN6"
+This symbol, if defined, indicates the availability of
+\&\f(CW\*(C`struct sockaddr_in6\*(C'\fR;
+.ie n .IP """HAS_SOCKADDR_SA_LEN""" 4
+.el .IP \f(CWHAS_SOCKADDR_SA_LEN\fR 4
+.IX Xref "HAS_SOCKADDR_SA_LEN"
+.IX Item "HAS_SOCKADDR_SA_LEN"
+This symbol, if defined, indicates that the \f(CW\*(C`struct sockaddr\*(C'\fR
+structure has a member called \f(CW\*(C`sa_len\*(C'\fR, indicating the length of
+the structure.
+.ie n .IP """HAS_SOCKADDR_STORAGE""" 4
+.el .IP \f(CWHAS_SOCKADDR_STORAGE\fR 4
+.IX Xref "HAS_SOCKADDR_STORAGE"
+.IX Item "HAS_SOCKADDR_STORAGE"
+This symbol, if defined, indicates the availability of
+\&\f(CW\*(C`struct sockaddr_storage\*(C'\fR;
+.ie n .IP """HAS_SOCKATMARK""" 4
+.el .IP \f(CWHAS_SOCKATMARK\fR 4
+.IX Xref "HAS_SOCKATMARK"
+.IX Item "HAS_SOCKATMARK"
+This symbol, if defined, indicates that the \f(CW\*(C`sockatmark\*(C'\fR routine is
+available to test whether a socket is at the out-of-band mark.
+.ie n .IP """HAS_SOCKET""" 4
+.el .IP \f(CWHAS_SOCKET\fR 4
+.IX Xref "HAS_SOCKET"
+.IX Item "HAS_SOCKET"
+This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CW\*(C`socket\*(C'\fR interface is
+supported.
+.ie n .IP """HAS_SOCKETPAIR""" 4
+.el .IP \f(CWHAS_SOCKETPAIR\fR 4
+.IX Xref "HAS_SOCKETPAIR"
+.IX Item "HAS_SOCKETPAIR"
+This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CWsocketpair()\fR call is
+supported.
+.ie n .IP """HAS_SOCKS5_INIT""" 4
+.el .IP \f(CWHAS_SOCKS5_INIT\fR 4
+.IX Xref "HAS_SOCKS5_INIT"
+.IX Item "HAS_SOCKS5_INIT"
+This symbol, if defined, indicates that the \f(CW\*(C`socks5_init\*(C'\fR routine is
+available to initialize \f(CW\*(C`SOCKS\*(C'\fR 5.
+.ie n .IP """I_SOCKS""" 4
+.el .IP \f(CWI_SOCKS\fR 4
+.IX Xref "I_SOCKS"
+.IX Item "I_SOCKS"
+This symbol, if defined, indicates that \fIsocks.h\fR exists and
+should be included.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SOCKS
+\&     #include <socks.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_SYS_SOCKIO""" 4
+.el .IP \f(CWI_SYS_SOCKIO\fR 4
+.IX Xref "I_SYS_SOCKIO"
+.IX Item "I_SYS_SOCKIO"
+This symbol, if defined, indicates the \fIsys/sockio.h\fR should be included
+to get socket ioctl options, like \f(CW\*(C`SIOCATMARK\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_SYS_SOCKIO
+\&     #include <sys_sockio.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Source Filters"
+.IX Header "Source Filters"
+.ie n .IP """apply_builtin_cv_attributes""" 4
+.el .IP \f(CWapply_builtin_cv_attributes\fR 4
+.IX Xref "apply_builtin_cv_attributes"
+.IX Item "apply_builtin_cv_attributes"
+Given an OP_LIST containing attribute definitions, filter it for known builtin
+attributes to apply to the cv, returning a possibly-smaller list containing
+just the remaining ones.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  apply_builtin_cv_attributes(CV *cv, OP *attrlist)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """filter_add""" 4
+.el .IP \f(CWfilter_add\fR 4
+.IX Item "filter_add"
+Described in perlfilter.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  filter_add(filter_t funcp, SV *datasv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """filter_del""" 4
+.el .IP \f(CWfilter_del\fR 4
+.IX Xref "filter_del"
+.IX Item "filter_del"
+Delete most recently added instance of the filter function argument
+.RS 4
+.Sp
+.Vb 1
+\& void  filter_del(filter_t funcp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """filter_read""" 4
+.el .IP \f(CWfilter_read\fR 4
+.IX Item "filter_read"
+Described in perlfilter.
+.RS 4
+.Sp
+.Vb 1
+\& I32  filter_read(int idx, SV *buf_sv, int maxlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """scan_vstring""" 4
+.el .IP \f(CWscan_vstring\fR 4
+.IX Xref "scan_vstring"
+.IX Item "scan_vstring"
+Returns a pointer to the next character after the parsed
+vstring, as well as updating the passed in sv.
+.Sp
+Function must be called like
+.Sp
+.Vb 2
+\&        sv = sv_2mortal(newSV(5));
+\&        s = scan_vstring(s,e,sv);
+.Ve
+.Sp
+where s and e are the start and end of the string.
+The sv should already be large enough to store the vstring
+passed in, for performance reasons.
+.Sp
+This function may croak if fatal warnings are enabled in the
+calling scope, hence the sv_2mortal in the example (to prevent
+a leak).  Make sure to do SvREFCNT_inc afterwards if you use
+sv_2mortal.
+.RS 4
+.Sp
+.Vb 1
+\& char *  scan_vstring(const char *s, const char * const e, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """start_subparse""" 4
+.el .IP \f(CWstart_subparse\fR 4
+.IX Xref "start_subparse"
+.IX Item "start_subparse"
+Set things up for parsing a subroutine.
+.Sp
+If \f(CW\*(C`is_format\*(C'\fR is non-zero, the input is to be considered a format sub
+(a specialised sub used to implement perl's \f(CW\*(C`format\*(C'\fR feature); else a
+normal \f(CW\*(C`sub\*(C'\fR.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR are added to the flags for \f(CW\*(C`PL_compcv\*(C'\fR.  \f(CW\*(C`flags\*(C'\fR may include the
+\&\f(CW\*(C`CVf_IsMETHOD\*(C'\fR bit, which causes the new subroutine to be a method.
+.Sp
+This returns the value of \f(CW\*(C`PL_savestack_ix\*(C'\fR that was in effect upon entry to
+the function;
+.RS 4
+.Sp
+.Vb 1
+\& I32  start_subparse(I32 is_format, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Stack Manipulation Macros"
+.IX Header "Stack Manipulation Macros"
+.ie n .IP """dMARK""" 4
+.el .IP \f(CWdMARK\fR 4
+.IX Xref "dMARK"
+.IX Item "dMARK"
+Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the XSUB.  See \f(CW"MARK"\fR and
+\&\f(CW"dORIGMARK"\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dMARK;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dORIGMARK""" 4
+.el .IP \f(CWdORIGMARK\fR 4
+.IX Xref "dORIGMARK"
+.IX Item "dORIGMARK"
+Saves the original stack mark for the XSUB.  See \f(CW"ORIGMARK"\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dORIGMARK;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dSP""" 4
+.el .IP \f(CWdSP\fR 4
+.IX Xref "dSP"
+.IX Item "dSP"
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the \f(CW\*(C`SP\*(C'\fR macro.  See \f(CW"SP"\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dSP;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dTARGET""" 4
+.el .IP \f(CWdTARGET\fR 4
+.IX Xref "dTARGET"
+.IX Item "dTARGET"
+Declare that this function uses \f(CW\*(C`TARG\*(C'\fR, and initializes it
+.RS 4
+.Sp
+.Vb 1
+\&   dTARGET;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """EXTEND""" 4
+.el .IP \f(CWEXTEND\fR 4
+.IX Xref "EXTEND"
+.IX Item "EXTEND"
+Used to extend the argument stack for an XSUB's return values.  Once
+used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed
+onto the stack.
+.RS 4
+.Sp
+.Vb 1
+\& void  EXTEND(SP, SSize_t nitems)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MARK""" 4
+.el .IP \f(CWMARK\fR 4
+.IX Xref "MARK"
+.IX Item "MARK"
+Stack marker variable for the XSUB.  See \f(CW"dMARK"\fR.
+.ie n .IP """mPUSHi""" 4
+.el .IP \f(CWmPUSHi\fR 4
+.IX Xref "mPUSHi"
+.IX Item "mPUSHi"
+Push an integer onto the stack.  The stack must have room for this element.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"PUSHi"\fR, \f(CW"mXPUSHi"\fR and \f(CW"XPUSHi"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHi(IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mPUSHn""" 4
+.el .IP \f(CWmPUSHn\fR 4
+.IX Xref "mPUSHn"
+.IX Item "mPUSHn"
+Push a double onto the stack.  The stack must have room for this element.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"PUSHn"\fR, \f(CW"mXPUSHn"\fR and \f(CW"XPUSHn"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHn(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mPUSHp""" 4
+.el .IP \f(CWmPUSHp\fR 4
+.IX Xref "mPUSHp"
+.IX Item "mPUSHp"
+Push a string onto the stack.  The stack must have room for this element.
+The \f(CW\*(C`len\*(C'\fR indicates the length of the string.  Does not use \f(CW\*(C`TARG\*(C'\fR.
+See also \f(CW"PUSHp"\fR, \f(CW"mXPUSHp"\fR and \f(CW"XPUSHp"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHp(char* str, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mPUSHpvs""" 4
+.el .IP \f(CWmPUSHpvs\fR 4
+.IX Xref "mPUSHpvs"
+.IX Item "mPUSHpvs"
+A variation on \f(CW\*(C`mPUSHp\*(C'\fR that takes a literal string and calculates its size
+directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mPUSHs""" 4
+.el .IP \f(CWmPUSHs\fR 4
+.IX Xref "mPUSHs"
+.IX Item "mPUSHs"
+Push an SV onto the stack and mortalizes the SV.  The stack must have room
+for this element.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"PUSHs"\fR and
+\&\f(CW"mXPUSHs"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHs(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mPUSHu""" 4
+.el .IP \f(CWmPUSHu\fR 4
+.IX Xref "mPUSHu"
+.IX Item "mPUSHu"
+Push an unsigned integer onto the stack.  The stack must have room for this
+element.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"PUSHu"\fR, \f(CW"mXPUSHu"\fR and
+\&\f(CW"XPUSHu"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mPUSHu(UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHi""" 4
+.el .IP \f(CWmXPUSHi\fR 4
+.IX Xref "mXPUSHi"
+.IX Item "mXPUSHi"
+Push an integer onto the stack, extending the stack if necessary.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHi"\fR, \f(CW"mPUSHi"\fR and \f(CW"PUSHi"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHi(IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHn""" 4
+.el .IP \f(CWmXPUSHn\fR 4
+.IX Xref "mXPUSHn"
+.IX Item "mXPUSHn"
+Push a double onto the stack, extending the stack if necessary.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHn"\fR, \f(CW"mPUSHn"\fR and \f(CW"PUSHn"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHn(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHp""" 4
+.el .IP \f(CWmXPUSHp\fR 4
+.IX Xref "mXPUSHp"
+.IX Item "mXPUSHp"
+Push a string onto the stack, extending the stack if necessary.  The \f(CW\*(C`len\*(C'\fR
+indicates the length of the string.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also
+\&\f(CW"XPUSHp"\fR, \f(CW\*(C`mPUSHp\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHp(char* str, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHpvs""" 4
+.el .IP \f(CWmXPUSHpvs\fR 4
+.IX Xref "mXPUSHpvs"
+.IX Item "mXPUSHpvs"
+A variation on \f(CW\*(C`mXPUSHp\*(C'\fR that takes a literal string and calculates its size
+directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHs""" 4
+.el .IP \f(CWmXPUSHs\fR 4
+.IX Xref "mXPUSHs"
+.IX Item "mXPUSHs"
+Push an SV onto the stack, extending the stack if necessary and mortalizes
+the SV.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHs"\fR and \f(CW"mPUSHs"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHs(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mXPUSHu""" 4
+.el .IP \f(CWmXPUSHu\fR 4
+.IX Xref "mXPUSHu"
+.IX Item "mXPUSHu"
+Push an unsigned integer onto the stack, extending the stack if necessary.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHu"\fR, \f(CW"mPUSHu"\fR and \f(CW"PUSHu"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mXPUSHu(UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newXSproto""" 4
+.el .IP \f(CWnewXSproto\fR 4
+.IX Xref "newXSproto"
+.IX Item "newXSproto"
+Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs.  Adds Perl prototypes to
+the subs.
+.ie n .IP """ORIGMARK""" 4
+.el .IP \f(CWORIGMARK\fR 4
+.IX Xref "ORIGMARK"
+.IX Item "ORIGMARK"
+The original stack mark for the XSUB.  See \f(CW"dORIGMARK"\fR.
+.ie n .IP """PL_markstack""" 4
+.el .IP \f(CWPL_markstack\fR 4
+.IX Item "PL_markstack"
+Described in perlguts.
+.ie n .IP """PL_markstack_ptr""" 4
+.el .IP \f(CWPL_markstack_ptr\fR 4
+.IX Item "PL_markstack_ptr"
+Described in perlguts.
+.ie n .IP """PL_savestack""" 4
+.el .IP \f(CWPL_savestack\fR 4
+.IX Item "PL_savestack"
+Described in perlguts.
+.ie n .IP """PL_savestack_ix""" 4
+.el .IP \f(CWPL_savestack_ix\fR 4
+.IX Item "PL_savestack_ix"
+Described in perlguts.
+.ie n .IP """PL_scopestack""" 4
+.el .IP \f(CWPL_scopestack\fR 4
+.IX Item "PL_scopestack"
+Described in perlguts.
+.ie n .IP """PL_scopestack_ix""" 4
+.el .IP \f(CWPL_scopestack_ix\fR 4
+.IX Item "PL_scopestack_ix"
+Described in perlguts.
+.ie n .IP """PL_scopestack_name""" 4
+.el .IP \f(CWPL_scopestack_name\fR 4
+.IX Item "PL_scopestack_name"
+Described in perlguts.
+.ie n .IP """PL_stack_base""" 4
+.el .IP \f(CWPL_stack_base\fR 4
+.IX Item "PL_stack_base"
+Described in perlguts.
+.ie n .IP """PL_stack_sp""" 4
+.el .IP \f(CWPL_stack_sp\fR 4
+.IX Item "PL_stack_sp"
+Described in perlguts.
+.ie n .IP """PL_tmps_floor""" 4
+.el .IP \f(CWPL_tmps_floor\fR 4
+.IX Item "PL_tmps_floor"
+Described in perlguts.
+.ie n .IP """PL_tmps_ix""" 4
+.el .IP \f(CWPL_tmps_ix\fR 4
+.IX Item "PL_tmps_ix"
+Described in perlguts.
+.ie n .IP """PL_tmps_stack""" 4
+.el .IP \f(CWPL_tmps_stack\fR 4
+.IX Item "PL_tmps_stack"
+Described in perlguts.
+.ie n .IP """POPi""" 4
+.el .IP \f(CWPOPi\fR 4
+.IX Xref "POPi"
+.IX Item "POPi"
+Pops an integer off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& IV  POPi
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPl""" 4
+.el .IP \f(CWPOPl\fR 4
+.IX Xref "POPl"
+.IX Item "POPl"
+Pops a long off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& long  POPl
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPn""" 4
+.el .IP \f(CWPOPn\fR 4
+.IX Xref "POPn"
+.IX Item "POPn"
+Pops a double off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& NV  POPn
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPp""" 4
+.el .IP \f(CWPOPp\fR 4
+.IX Xref "POPp"
+.IX Item "POPp"
+Pops a string off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& char*  POPp
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPpbytex""" 4
+.el .IP \f(CWPOPpbytex\fR 4
+.IX Xref "POPpbytex"
+.IX Item "POPpbytex"
+Pops a string off the stack which must consist of bytes i.e. characters < 256.
+.RS 4
+.Sp
+.Vb 1
+\& char*  POPpbytex
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPpx""" 4
+.el .IP \f(CWPOPpx\fR 4
+.IX Xref "POPpx"
+.IX Item "POPpx"
+Pops a string off the stack.  Identical to POPp.  There are two names for
+historical reasons.
+.RS 4
+.Sp
+.Vb 1
+\& char*  POPpx
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPs""" 4
+.el .IP \f(CWPOPs\fR 4
+.IX Xref "POPs"
+.IX Item "POPs"
+Pops an SV off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  POPs
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPu""" 4
+.el .IP \f(CWPOPu\fR 4
+.IX Xref "POPu"
+.IX Item "POPu"
+Pops an unsigned integer off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& UV  POPu
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """POPul""" 4
+.el .IP \f(CWPOPul\fR 4
+.IX Xref "POPul"
+.IX Item "POPul"
+Pops an unsigned long off the stack.
+.RS 4
+.Sp
+.Vb 1
+\& long  POPul
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHi""" 4
+.el .IP \f(CWPUSHi\fR 4
+.IX Xref "PUSHi"
+.IX Item "PUSHi"
+Push an integer onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
+called to declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to 
+return lists from XSUB's \- see \f(CW"mPUSHi"\fR instead.  See also \f(CW"XPUSHi"\fR
+and \f(CW"mXPUSHi"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHi(IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHMARK""" 4
+.el .IP \f(CWPUSHMARK\fR 4
+.IX Xref "PUSHMARK"
+.IX Item "PUSHMARK"
+Opening bracket for arguments on a callback.  See \f(CW"PUTBACK"\fR and
+perlcall.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHMARK(SP)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHmortal""" 4
+.el .IP \f(CWPUSHmortal\fR 4
+.IX Xref "PUSHmortal"
+.IX Item "PUSHmortal"
+Push a new mortal SV onto the stack.  The stack must have room for this
+element.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"PUSHs"\fR, \f(CW"XPUSHmortal"\fR and
+\&\f(CW"XPUSHs"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHmortal
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHn""" 4
+.el .IP \f(CWPUSHn\fR 4
+.IX Xref "PUSHn"
+.IX Item "PUSHn"
+Push a double onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
+called to declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
+return lists from XSUB's \- see \f(CW"mPUSHn"\fR instead.  See also \f(CW"XPUSHn"\fR
+and \f(CW"mXPUSHn"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHn(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHp""" 4
+.el .IP \f(CWPUSHp\fR 4
+.IX Xref "PUSHp"
+.IX Item "PUSHp"
+Push a string onto the stack.  The stack must have room for this element.
+The \f(CW\*(C`len\*(C'\fR indicates the length of the string.  Handles 'set' magic.  Uses
+\&\f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it.  Do not
+call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see
+\&\f(CW"mPUSHp"\fR instead.  See also \f(CW"XPUSHp"\fR and \f(CW"mXPUSHp"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHp(char* str, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHpvs""" 4
+.el .IP \f(CWPUSHpvs\fR 4
+.IX Xref "PUSHpvs"
+.IX Item "PUSHpvs"
+A variation on \f(CW\*(C`PUSHp\*(C'\fR that takes a literal string and calculates its size
+directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHs""" 4
+.el .IP \f(CWPUSHs\fR 4
+.IX Xref "PUSHs"
+.IX Item "PUSHs"
+Push an SV onto the stack.  The stack must have room for this element.
+Does not handle 'set' magic.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also
+\&\f(CW"PUSHmortal"\fR, \f(CW"XPUSHs"\fR, and \f(CW"XPUSHmortal"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHs(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUSHu""" 4
+.el .IP \f(CWPUSHu\fR 4
+.IX Xref "PUSHu"
+.IX Item "PUSHu"
+Push an unsigned integer onto the stack.  The stack must have room for this
+element.  Handles 'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR
+should be called to declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented
+macros to return lists from XSUB's \- see \f(CW"mPUSHu"\fR instead.  See also
+\&\f(CW"XPUSHu"\fR and \f(CW"mXPUSHu"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  PUSHu(UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PUTBACK""" 4
+.el .IP \f(CWPUTBACK\fR 4
+.IX Xref "PUTBACK"
+.IX Item "PUTBACK"
+Closing bracket for XSUB arguments.  This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR.
+See \f(CW"PUSHMARK"\fR and perlcall for other uses.
+.RS 4
+.Sp
+.Vb 1
+\&   PUTBACK;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEt_INT""" 4
+.el .IP \f(CWSAVEt_INT\fR 4
+.IX Item "SAVEt_INT"
+Described in perlguts.
+.ie n .IP """SP""" 4
+.el .IP \f(CWSP\fR 4
+.IX Xref "SP"
+.IX Item "SP"
+Stack pointer.  This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR.  See \f(CW"dSP"\fR and
+\&\f(CW\*(C`SPAGAIN\*(C'\fR.
+.ie n .IP """SPAGAIN""" 4
+.el .IP \f(CWSPAGAIN\fR 4
+.IX Xref "SPAGAIN"
+.IX Item "SPAGAIN"
+Refetch the stack pointer.  Used after a callback.  See perlcall.
+.RS 4
+.Sp
+.Vb 1
+\&   SPAGAIN;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SSNEW""" 4
+.el .IP \f(CWSSNEW\fR 4
+.IX Item "SSNEW"
+.PD 0
+.ie n .IP """SSNEWa""" 4
+.el .IP \f(CWSSNEWa\fR 4
+.IX Item "SSNEWa"
+.ie n .IP """SSNEWat""" 4
+.el .IP \f(CWSSNEWat\fR 4
+.IX Item "SSNEWat"
+.ie n .IP """SSNEWt""" 4
+.el .IP \f(CWSSNEWt\fR 4
+.IX Xref "SSNEW SSNEWa SSNEWat SSNEWt"
+.IX Item "SSNEWt"
+.PD
+These temporarily allocates data on the savestack, returning an SSize_t index into
+the savestack, because a pointer would get broken if the savestack is moved on
+reallocation.  Use "\f(CW\*(C`SSPTR\*(C'\fR" to convert the returned index into a pointer.
+.Sp
+The forms differ in that plain \f(CW\*(C`SSNEW\*(C'\fR allocates \f(CW\*(C`size\*(C'\fR bytes;
+\&\f(CW\*(C`SSNEWt\*(C'\fR and \f(CW\*(C`SSNEWat\*(C'\fR allocate \f(CW\*(C`size\*(C'\fR objects, each of which is type
+\&\f(CW\*(C`type\*(C'\fR;
+and <SSNEWa> and \f(CW\*(C`SSNEWat\*(C'\fR make sure to align the new data to an \f(CW\*(C`align\*(C'\fR
+boundary.  The most useful value for the alignment is likely to be
+"\f(CW\*(C`MEM_ALIGNBYTES\*(C'\fR".  The alignment will be preserved through savestack
+reallocation \fBonly\fR if realloc returns data aligned to a size divisible by
+"align"!
+.RS 4
+.Sp
+.Vb 4
+\& SSize_t  SSNEW  (Size_t size)
+\& SSize_t  SSNEWa (Size_t_size, Size_t align)
+\& SSize_t  SSNEWat(Size_t_size, type, Size_t align)
+\& SSize_t  SSNEWt (Size_t size, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SSPTR""" 4
+.el .IP \f(CWSSPTR\fR 4
+.IX Item "SSPTR"
+.PD 0
+.ie n .IP """SSPTRt""" 4
+.el .IP \f(CWSSPTRt\fR 4
+.IX Xref "SSPTR SSPTRt"
+.IX Item "SSPTRt"
+.PD
+These convert the \f(CW\*(C`index\*(C'\fR returned by L/<\f(CW\*(C`SSNEW\*(C'\fR> and kin into actual pointers.
+.Sp
+The difference is that \f(CW\*(C`SSPTR\*(C'\fR casts the result to \f(CW\*(C`type\*(C'\fR, and \f(CW\*(C`SSPTRt\*(C'\fR
+casts it to a pointer of that \f(CW\*(C`type\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& type    SSPTR (SSize_t index, type)
+\& type *  SSPTRt(SSize_t index, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TARG""" 4
+.el .IP \f(CWTARG\fR 4
+.IX Xref "TARG"
+.IX Item "TARG"
+\&\f(CW\*(C`TARG\*(C'\fR is short for "target".  It is an entry in the pad that an OPs
+\&\f(CW\*(C`op_targ\*(C'\fR refers to.  It is scratchpad space, often used as a return
+value for the OP, but some use it for other purposes.
+.RS 4
+.Sp
+.Vb 1
+\&   TARG;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TOPs""" 4
+.el .IP \f(CWTOPs\fR 4
+.IX Item "TOPs"
+Described in perlguts.
+.ie n .IP """XPUSHi""" 4
+.el .IP \f(CWXPUSHi\fR 4
+.IX Xref "XPUSHi"
+.IX Item "XPUSHi"
+Push an integer onto the stack, extending the stack if necessary.  Handles
+\&'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to
+declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
+from XSUB's \- see \f(CW"mXPUSHi"\fR instead.  See also \f(CW"PUSHi"\fR and
+\&\f(CW"mPUSHi"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHi(IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHmortal""" 4
+.el .IP \f(CWXPUSHmortal\fR 4
+.IX Xref "XPUSHmortal"
+.IX Item "XPUSHmortal"
+Push a new mortal SV onto the stack, extending the stack if necessary.
+Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHs"\fR, \f(CW"PUSHmortal"\fR and
+\&\f(CW"PUSHs"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHmortal
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHn""" 4
+.el .IP \f(CWXPUSHn\fR 4
+.IX Xref "XPUSHn"
+.IX Item "XPUSHn"
+Push a double onto the stack, extending the stack if necessary.  Handles
+\&'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to
+declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
+from XSUB's \- see \f(CW"mXPUSHn"\fR instead.  See also \f(CW"PUSHn"\fR and
+\&\f(CW"mPUSHn"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHn(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHp""" 4
+.el .IP \f(CWXPUSHp\fR 4
+.IX Xref "XPUSHp"
+.IX Item "XPUSHp"
+Push a string onto the stack, extending the stack if necessary.  The \f(CW\*(C`len\*(C'\fR
+indicates the length of the string.  Handles 'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so
+\&\f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it.  Do not call
+multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see
+\&\f(CW"mXPUSHp"\fR instead.  See also \f(CW"PUSHp"\fR and \f(CW"mPUSHp"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHp(char* str, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHpvs""" 4
+.el .IP \f(CWXPUSHpvs\fR 4
+.IX Xref "XPUSHpvs"
+.IX Item "XPUSHpvs"
+A variation on \f(CW\*(C`XPUSHp\*(C'\fR that takes a literal string and calculates its size
+directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHs""" 4
+.el .IP \f(CWXPUSHs\fR 4
+.IX Xref "XPUSHs"
+.IX Item "XPUSHs"
+Push an SV onto the stack, extending the stack if necessary.  Does not
+handle 'set' magic.  Does not use \f(CW\*(C`TARG\*(C'\fR.  See also \f(CW"XPUSHmortal"\fR,
+\&\f(CW\*(C`PUSHs\*(C'\fR and \f(CW\*(C`PUSHmortal\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHs(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XPUSHu""" 4
+.el .IP \f(CWXPUSHu\fR 4
+.IX Xref "XPUSHu"
+.IX Item "XPUSHu"
+Push an unsigned integer onto the stack, extending the stack if necessary.
+Handles 'set' magic.  Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
+called to declare it.  Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
+return lists from XSUB's \- see \f(CW"mXPUSHu"\fR instead.  See also \f(CW"PUSHu"\fR and
+\&\f(CW"mPUSHu"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XPUSHu(UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XS_APIVERSION_BOOTCHECK""" 4
+.el .IP \f(CWXS_APIVERSION_BOOTCHECK\fR 4
+.IX Xref "XS_APIVERSION_BOOTCHECK"
+.IX Item "XS_APIVERSION_BOOTCHECK"
+Macro to verify that the perl api version an XS module has been compiled against
+matches the api version of the perl interpreter it's being loaded into.
+.RS 4
+.Sp
+.Vb 1
+\&   XS_APIVERSION_BOOTCHECK;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN""" 4
+.el .IP \f(CWXSRETURN\fR 4
+.IX Xref "XSRETURN"
+.IX Item "XSRETURN"
+Return from XSUB, indicating number of items on the stack.  This is usually
+handled by \f(CW\*(C`xsubpp\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XSRETURN(int nitems)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_EMPTY""" 4
+.el .IP \f(CWXSRETURN_EMPTY\fR 4
+.IX Xref "XSRETURN_EMPTY"
+.IX Item "XSRETURN_EMPTY"
+Return an empty list from an XSUB immediately.
+.RS 4
+.Sp
+.Vb 1
+\&   XSRETURN_EMPTY;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_IV""" 4
+.el .IP \f(CWXSRETURN_IV\fR 4
+.IX Xref "XSRETURN_IV"
+.IX Item "XSRETURN_IV"
+Return an integer from an XSUB immediately.  Uses \f(CW\*(C`XST_mIV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XSRETURN_IV(IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_NO""" 4
+.el .IP \f(CWXSRETURN_NO\fR 4
+.IX Xref "XSRETURN_NO"
+.IX Item "XSRETURN_NO"
+Return \f(CW&PL_sv_no\fR from an XSUB immediately.  Uses \f(CW\*(C`XST_mNO\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   XSRETURN_NO;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_NV""" 4
+.el .IP \f(CWXSRETURN_NV\fR 4
+.IX Xref "XSRETURN_NV"
+.IX Item "XSRETURN_NV"
+Return a double from an XSUB immediately.  Uses \f(CW\*(C`XST_mNV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XSRETURN_NV(NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_PV""" 4
+.el .IP \f(CWXSRETURN_PV\fR 4
+.IX Xref "XSRETURN_PV"
+.IX Item "XSRETURN_PV"
+Return a copy of a string from an XSUB immediately.  Uses \f(CW\*(C`XST_mPV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XSRETURN_PV(char* str)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_UNDEF""" 4
+.el .IP \f(CWXSRETURN_UNDEF\fR 4
+.IX Xref "XSRETURN_UNDEF"
+.IX Item "XSRETURN_UNDEF"
+Return \f(CW&PL_sv_undef\fR from an XSUB immediately.  Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   XSRETURN_UNDEF;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_UV""" 4
+.el .IP \f(CWXSRETURN_UV\fR 4
+.IX Xref "XSRETURN_UV"
+.IX Item "XSRETURN_UV"
+Return an integer from an XSUB immediately.  Uses \f(CW\*(C`XST_mUV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  XSRETURN_UV(IV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XSRETURN_YES""" 4
+.el .IP \f(CWXSRETURN_YES\fR 4
+.IX Xref "XSRETURN_YES"
+.IX Item "XSRETURN_YES"
+Return \f(CW&PL_sv_yes\fR from an XSUB immediately.  Uses \f(CW\*(C`XST_mYES\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   XSRETURN_YES;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mIV""" 4
+.el .IP \f(CWXST_mIV\fR 4
+.IX Xref "XST_mIV"
+.IX Item "XST_mIV"
+Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.  The
+value is stored in a new mortal SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mIV(int pos, IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mNO""" 4
+.el .IP \f(CWXST_mNO\fR 4
+.IX Xref "XST_mNO"
+.IX Item "XST_mNO"
+Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
+stack.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mNO(int pos)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mNV""" 4
+.el .IP \f(CWXST_mNV\fR 4
+.IX Xref "XST_mNV"
+.IX Item "XST_mNV"
+Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.  The value
+is stored in a new mortal SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mNV(int pos, NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mPV""" 4
+.el .IP \f(CWXST_mPV\fR 4
+.IX Xref "XST_mPV"
+.IX Item "XST_mPV"
+Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.
+The value is stored in a new mortal SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mPV(int pos, char* str)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mUNDEF""" 4
+.el .IP \f(CWXST_mUNDEF\fR 4
+.IX Xref "XST_mUNDEF"
+.IX Item "XST_mUNDEF"
+Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
+stack.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mUNDEF(int pos)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mUV""" 4
+.el .IP \f(CWXST_mUV\fR 4
+.IX Xref "XST_mUV"
+.IX Item "XST_mUV"
+Place an unsigned integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.  The
+value is stored in a new mortal SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mUV(int pos, UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XST_mYES""" 4
+.el .IP \f(CWXST_mYES\fR 4
+.IX Xref "XST_mYES"
+.IX Item "XST_mYES"
+Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
+stack.
+.RS 4
+.Sp
+.Vb 1
+\& void  XST_mYES(int pos)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """XS_VERSION""" 4
+.el .IP \f(CWXS_VERSION\fR 4
+.IX Xref "XS_VERSION"
+.IX Item "XS_VERSION"
+The version identifier for an XS module.  This is usually
+handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR.  See
+\&\f(CW"XS_VERSION_BOOTCHECK"\fR.
+.ie n .IP """XS_VERSION_BOOTCHECK""" 4
+.el .IP \f(CWXS_VERSION_BOOTCHECK\fR 4
+.IX Xref "XS_VERSION_BOOTCHECK"
+.IX Item "XS_VERSION_BOOTCHECK"
+Macro to verify that a PM module's \f(CW$VERSION\fR variable matches the XS
+module's \f(CW\*(C`XS_VERSION\*(C'\fR variable.  This is usually handled automatically by
+\&\f(CW\*(C`xsubpp\*(C'\fR.  See "The VERSIONCHECK: Keyword" in perlxs.
+.RS 4
+.Sp
+.Vb 1
+\&   XS_VERSION_BOOTCHECK;
+.Ve
+.RE
+.RS 4
+.RE
+.SH "String Handling"
+.IX Header "String Handling"
+See also \f(CW"Unicode Support"\fR.
+.ie n .IP """CAT2""" 4
+.el .IP \f(CWCAT2\fR 4
+.IX Xref "CAT2"
+.IX Item "CAT2"
+This macro concatenates 2 tokens together.
+.RS 4
+.Sp
+.Vb 1
+\& token  CAT2(token x, token y)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Copy""" 4
+.el .IP \f(CWCopy\fR 4
+.IX Item "Copy"
+.PD 0
+.ie n .IP """CopyD""" 4
+.el .IP \f(CWCopyD\fR 4
+.IX Xref "Copy CopyD"
+.IX Item "CopyD"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function.  The \f(CW\*(C`src\*(C'\fR is the
+source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
+\&\f(CW\*(C`type\*(C'\fR is the type.  May fail on overlapping copies.  See also \f(CW"Move"\fR.
+.Sp
+\&\f(CW\*(C`CopyD\*(C'\fR is like \f(CW\*(C`Copy\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR.  Useful
+for encouraging compilers to tail-call
+optimise.
+.RS 4
+.Sp
+.Vb 2
+\& void    Copy (void* src, void* dest, int nitems, type)
+\& void *  CopyD(void* src, void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """delimcpy""" 4
+.el .IP \f(CWdelimcpy\fR 4
+.IX Xref "delimcpy"
+.IX Item "delimcpy"
+Copy a source buffer to a destination buffer, stopping at (but not including)
+the first occurrence in the source of an unescaped (defined below) delimiter
+byte, \f(CW\*(C`delim\*(C'\fR.  The source is the bytes between \f(CW\*(C`from\*(C'\fR\ and\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1.  Similarly, the dest is \f(CW\*(C`to\*(C'\fR up to \f(CW\*(C`to_end\*(C'\fR.
+.Sp
+The number of bytes copied is written to \f(CW*retlen\fR.
+.Sp
+Returns the position of the first uncopied \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but
+if there is no such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned,
+and the entire buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied.
+.Sp
+If there is room in the destination available after the copy, an extra
+terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned
+length).
+.Sp
+The error case is if the destination buffer is not large enough to accommodate
+everything that should be copied.  In this situation, a value larger than
+\&\f(CW\*(C`to_end\*(C'\fR\ \-\ \f(CW\*(C`to\*(C'\fR is written to \f(CW*retlen\fR, and as much of the source as
+fits will be written to the destination.  Not having room for the safety \f(CW\*(C`NUL\*(C'\fR
+is not considered an error.
+.Sp
+In the following examples, let \f(CW\*(C`x\*(C'\fR be the delimiter, and \f(CW0\fR represent a \f(CW\*(C`NUL\*(C'\fR
+byte (\fBNOT\fR the digit \f(CW0\fR).  Then we would have
+.Sp
+.Vb 2
+\&  Source     Destination
+\& abcxdef        abc0
+.Ve
+.Sp
+provided the destination buffer is at least 4 bytes long.
+.Sp
+An escaped delimiter is one which is immediately preceded by a single
+backslash.  Escaped delimiters are copied, and the copy continues past the
+delimiter; the backslash is not copied:
+.Sp
+.Vb 2
+\&  Source       Destination
+\& abc\exdef       abcxdef0
+.Ve
+.Sp
+(provided the destination buffer is at least 8 bytes long).
+.Sp
+It's actually somewhat more complicated than that. A sequence of any odd number
+of backslashes escapes the following delimiter, and the copy continues with
+exactly one of the backslashes stripped.
+.Sp
+.Vb 4
+\&     Source         Destination
+\&     abc\exdef          abcxdef0
+\&   abc\e\e\exdef        abc\e\exdef0
+\& abc\e\e\e\e\exdef      abc\e\e\e\exdef0
+.Ve
+.Sp
+(as always, if the destination is large enough)
+.Sp
+An even number of preceding backslashes does not escape the delimiter, so that
+the copy stops just before it, and includes all the backslashes (no stripping;
+zero is considered even):
+.Sp
+.Vb 4
+\&      Source         Destination
+\&      abcxdef          abc0
+\&    abc\e\exdef          abc\e\e0
+\&  abc\e\e\e\exdef          abc\e\e\e\e0
+.Ve
+.RS 4
+.Sp
+.Vb 3
+\& char *  delimcpy(char *to, const char *to_end, const char *from,
+\&                  const char *from_end, const int delim,
+\&                  I32 *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """do_join""" 4
+.el .IP \f(CWdo_join\fR 4
+.IX Xref "do_join"
+.IX Item "do_join"
+This performs a Perl \f(CW\*(C`join\*(C'\fR, placing the joined output
+into \f(CW\*(C`sv\*(C'\fR.
+.Sp
+The elements to join are in SVs, stored in a C array of pointers to SVs, from
+\&\f(CW**mark\fR to \f(CW\*(C`**sp\ \-\ 1\*(C'\fR.  Hence \f(CW*mark\fR is a reference to the first SV.
+Each SV will be coerced into a PV if not one already.
+.Sp
+\&\f(CW\*(C`delim\*(C'\fR contains the string (or coerced into a string) that is to separate
+each of the joined elements.
+.Sp
+If any component is in UTF\-8, the result will be as well, and all non\-UTF\-8
+components will be converted to UTF\-8 as necessary.
+.Sp
+Magic and tainting are handled.
+.RS 4
+.Sp
+.Vb 1
+\& void  do_join(SV *sv, SV *delim, SV **mark, SV **sp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """do_sprintf""" 4
+.el .IP \f(CWdo_sprintf\fR 4
+.IX Xref "do_sprintf"
+.IX Item "do_sprintf"
+This performs a Perl \f(CW\*(C`sprintf\*(C'\fR placing the string output
+into \f(CW\*(C`sv\*(C'\fR.
+.Sp
+The elements to format are in SVs, stored in a C array of pointers to SVs of
+length \f(CW\*(C`len\*(C'\fR> and beginning at \f(CW**sarg\fR.  The element referenced by \f(CW*sarg\fR
+is the format.
+.Sp
+Magic and tainting are handled.
+.RS 4
+.Sp
+.Vb 1
+\& void  do_sprintf(SV *sv, SSize_t len, SV **sarg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """fbm_compile""" 4
+.el .IP \f(CWfbm_compile\fR 4
+.IX Xref "fbm_compile"
+.IX Item "fbm_compile"
+Analyzes the string in order to make fast searches on it using \f(CWfbm_instr()\fR
+\&\-\- the Boyer-Moore algorithm.
+.RS 4
+.Sp
+.Vb 1
+\& void  fbm_compile(SV *sv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """fbm_instr""" 4
+.el .IP \f(CWfbm_instr\fR 4
+.IX Xref "fbm_instr"
+.IX Item "fbm_instr"
+Returns the location of the SV in the string delimited by \f(CW\*(C`big\*(C'\fR and
+\&\f(CW\*(C`bigend\*(C'\fR (\f(CW\*(C`bigend\*(C'\fR) is the char following the last char).
+It returns \f(CW\*(C`NULL\*(C'\fR if the string can't be found.  The \f(CW\*(C`sv\*(C'\fR
+does not have to be \f(CW\*(C`fbm_compiled\*(C'\fR, but the search will not be as fast
+then.
+.RS 4
+.Sp
+.Vb 2
+\& char *  fbm_instr(unsigned char *big, unsigned char *bigend,
+\&                   SV *littlestr, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """foldEQ""" 4
+.el .IP \f(CWfoldEQ\fR 4
+.IX Xref "foldEQ"
+.IX Item "foldEQ"
+Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the
+same
+case-insensitively; false otherwise.  Uppercase and lowercase ASCII range bytes
+match themselves and their opposite case counterparts.  Non-cased and non-ASCII
+range bytes match only themselves.
+.RS 4
+.Sp
+.Vb 1
+\& I32  foldEQ(const char *a, const char *b, I32 len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ibcmp""" 4
+.el .IP \f(CWibcmp\fR 4
+.IX Xref "ibcmp"
+.IX Item "ibcmp"
+This is a synonym for \f(CW\*(C`(!\ foldEQ())\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& I32  ibcmp(const char *a, const char *b, I32 len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ibcmp_locale""" 4
+.el .IP \f(CWibcmp_locale\fR 4
+.IX Xref "ibcmp_locale"
+.IX Item "ibcmp_locale"
+This is a synonym for \f(CW\*(C`(!\ foldEQ_locale())\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& I32  ibcmp_locale(const char *a, const char *b, I32 len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ibcmp_utf8""" 4
+.el .IP \f(CWibcmp_utf8\fR 4
+.IX Xref "ibcmp_utf8"
+.IX Item "ibcmp_utf8"
+This is a synonym for \f(CW\*(C`(!\ foldEQ_utf8())\*(C'\fR
+.RS 4
+.Sp
+.Vb 2
+\& I32  ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
+\&                 const char *s2, char **pe2, UV l2, bool u2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """instr""" 4
+.el .IP \f(CWinstr\fR 4
+.IX Xref "instr"
+.IX Item "instr"
+Same as \fBstrstr\fR\|(3), which finds and returns a pointer to the first occurrence
+of the NUL-terminated substring \f(CW\*(C`little\*(C'\fR in the NUL-terminated string \f(CW\*(C`big\*(C'\fR,
+returning NULL if not found.  The terminating NUL bytes are not compared.
+.RS 4
+.Sp
+.Vb 1
+\& char *  instr(const char *big, const char *little)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """memCHRs""" 4
+.el .IP \f(CWmemCHRs\fR 4
+.IX Xref "memCHRs"
+.IX Item "memCHRs"
+Returns the position of the first occurrence of the byte \f(CW\*(C`c\*(C'\fR in the literal
+string \f(CW"list"\fR, or NULL if \f(CW\*(C`c\*(C'\fR doesn't appear in \f(CW"list"\fR.  All bytes are
+treated as unsigned char.  Thus this macro can be used to determine if \f(CW\*(C`c\*(C'\fR is
+in a set of particular characters.  Unlike \fBstrchr\fR\|(3), it works even if \f(CW\*(C`c\*(C'\fR
+is \f(CW\*(C`NUL\*(C'\fR (and the set doesn't include \f(CW\*(C`NUL\*(C'\fR).
+.RS 4
+.Sp
+.Vb 1
+\& bool  memCHRs("list", char c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """memEQ""" 4
+.el .IP \f(CWmemEQ\fR 4
+.IX Xref "memEQ"
+.IX Item "memEQ"
+Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
+are equal.  The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
+Returns true or false.  It is undefined behavior if either of the buffers
+doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes.
+.RS 4
+.Sp
+.Vb 1
+\& bool  memEQ(char* s1, char* s2, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """memEQs""" 4
+.el .IP \f(CWmemEQs\fR 4
+.IX Xref "memEQs"
+.IX Item "memEQs"
+Like "memEQ", but the second string is a literal enclosed in double quotes,
+\&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
+Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  memEQs(char* s1, STRLEN l1, "s2")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """memNE""" 4
+.el .IP \f(CWmemNE\fR 4
+.IX Xref "memNE"
+.IX Item "memNE"
+Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
+are not equal.  The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
+Returns true or false.  It is undefined behavior if either of the buffers
+doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes.
+.RS 4
+.Sp
+.Vb 1
+\& bool  memNE(char* s1, char* s2, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """memNEs""" 4
+.el .IP \f(CWmemNEs\fR 4
+.IX Xref "memNEs"
+.IX Item "memNEs"
+Like "memNE", but the second string is a literal enclosed in double quotes,
+\&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
+Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  memNEs(char* s1, STRLEN l1, "s2")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Move""" 4
+.el .IP \f(CWMove\fR 4
+.IX Item "Move"
+.PD 0
+.ie n .IP """MoveD""" 4
+.el .IP \f(CWMoveD\fR 4
+.IX Xref "Move MoveD"
+.IX Item "MoveD"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function.  The \f(CW\*(C`src\*(C'\fR is the
+source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
+\&\f(CW\*(C`type\*(C'\fR is the type.  Can do overlapping moves.  See also \f(CW"Copy"\fR.
+.Sp
+\&\f(CW\*(C`MoveD\*(C'\fR is like \f(CW\*(C`Move\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR.  Useful
+for encouraging compilers to tail-call
+optimise.
+.RS 4
+.Sp
+.Vb 2
+\& void    Move (void* src, void* dest, int nitems, type)
+\& void *  MoveD(void* src, void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_snprintf""" 4
+.el .IP \f(CWmy_snprintf\fR 4
+.IX Xref "my_snprintf"
+.IX Item "my_snprintf"
+The C library \f(CW\*(C`snprintf\*(C'\fR functionality, if available and
+standards-compliant (uses \f(CW\*(C`vsnprintf\*(C'\fR, actually).  However, if the
+\&\f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately use the unsafe
+\&\f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an overrun check,
+but that may be too late).  Consider using \f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or
+getting \f(CW\*(C`vsnprintf\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& int  my_snprintf(char *buffer, const Size_t len,
+\&                  const char *format, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_sprintf""" 4
+.el .IP \f(CWmy_sprintf\fR 4
+.IX Xref "my_sprintf"
+.IX Item "my_sprintf"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`my_sprintf\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Do NOT use this due to the possibility of overflowing \f(CW\*(C`buffer\*(C'\fR.  Instead use
+\&\fBmy_snprintf()\fR
+.RS 4
+.Sp
+.Vb 1
+\& int  my_sprintf(NN char *buffer, NN const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_strnlen""" 4
+.el .IP \f(CWmy_strnlen\fR 4
+.IX Xref "my_strnlen"
+.IX Item "my_strnlen"
+The C library \f(CW\*(C`strnlen\*(C'\fR if available, or a Perl implementation of it.
+.Sp
+\&\f(CWmy_strnlen()\fR computes the length of the string, up to \f(CW\*(C`maxlen\*(C'\fR
+characters.  It will never attempt to address more than \f(CW\*(C`maxlen\*(C'\fR
+characters, making it suitable for use with strings that are not
+guaranteed to be NUL-terminated.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  my_strnlen(const char *str, Size_t maxlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_vsnprintf""" 4
+.el .IP \f(CWmy_vsnprintf\fR 4
+.IX Xref "my_vsnprintf"
+.IX Item "my_vsnprintf"
+The C library \f(CW\*(C`vsnprintf\*(C'\fR if available and standards-compliant.
+However, if the \f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately
+use the unsafe \f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an
+overrun check, but that may be too late).  Consider using
+\&\f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or getting \f(CW\*(C`vsnprintf\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& int  my_vsnprintf(char *buffer, const Size_t len,
+\&                   const char *format, va_list ap)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """NewCopy""" 4
+.el .IP \f(CWNewCopy\fR 4
+.IX Xref "NewCopy"
+.IX Item "NewCopy"
+Combines \fBNewx()\fR and \fBCopy()\fR into a single macro. Dest will be allocated
+using \fBNewx()\fR and then src will be copied into it.
+.RS 4
+.Sp
+.Vb 1
+\& void  NewCopy(void* src, void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ninstr""" 4
+.el .IP \f(CWninstr\fR 4
+.IX Xref "ninstr"
+.IX Item "ninstr"
+Find the first (leftmost) occurrence of a sequence of bytes within another
+sequence.  This is the Perl version of \f(CWstrstr()\fR, extended to handle
+arbitrary sequences, potentially containing embedded \f(CW\*(C`NUL\*(C'\fR characters (\f(CW\*(C`NUL\*(C'\fR
+is what the initial \f(CW\*(C`n\*(C'\fR in the function name stands for; some systems have an
+equivalent, \f(CWmemmem()\fR, but with a somewhat different API).
+.Sp
+Another way of thinking about this function is finding a needle in a haystack.
+\&\f(CW\*(C`big\*(C'\fR points to the first byte in the haystack.  \f(CW\*(C`big_end\*(C'\fR points to one byte
+beyond the final byte in the haystack.  \f(CW\*(C`little\*(C'\fR points to the first byte in
+the needle.  \f(CW\*(C`little_end\*(C'\fR points to one byte beyond the final byte in the
+needle.  All the parameters must be non\-\f(CW\*(C`NULL\*(C'\fR.
+.Sp
+The function returns \f(CW\*(C`NULL\*(C'\fR if there is no occurrence of \f(CW\*(C`little\*(C'\fR within
+\&\f(CW\*(C`big\*(C'\fR.  If \f(CW\*(C`little\*(C'\fR is the empty string, \f(CW\*(C`big\*(C'\fR is returned.
+.Sp
+Because this function operates at the byte level, and because of the inherent
+characteristics of UTF\-8 (or UTF-EBCDIC), it will work properly if both the
+needle and the haystack are strings with the same UTF\-8ness, but not if the
+UTF\-8ness differs.
+.RS 4
+.Sp
+.Vb 2
+\& char *  ninstr(const char *big, const char *bigend,
+\&                const char *little, const char *lend)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Nullch""" 4
+.el .IP \f(CWNullch\fR 4
+.IX Xref "Nullch"
+.IX Item "Nullch"
+Null character pointer.  (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is
+defined.)
+.ie n .IP """PL_na""" 4
+.el .IP \f(CWPL_na\fR 4
+.IX Xref "PL_na"
+.IX Item "PL_na"
+A scratch pad variable in which to store a \f(CW\*(C`STRLEN\*(C'\fR value.  If would have been
+better named something like \f(CW\*(C`PL_temp_strlen\*(C'\fR.
+.Sp
+It is is typically used with \f(CW\*(C`SvPV\*(C'\fR when one is actually planning to discard
+the returned length, (hence the length is "Not Applicable", which is how this
+variable got its name).
+.Sp
+\&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it
+is in a call stack with something else that is using it, this variable would
+get zapped, leading to hard-to-diagnose errors.
+.Sp
+It is usually more efficient to either declare a local variable and use that
+instead, or to use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  PL_na
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """rninstr""" 4
+.el .IP \f(CWrninstr\fR 4
+.IX Xref "rninstr"
+.IX Item "rninstr"
+Like \f(CW"ninstr"\fR, but instead finds the final (rightmost) occurrence of a
+sequence of bytes within another sequence, returning \f(CW\*(C`NULL\*(C'\fR if there is no
+such occurrence.
+.RS 4
+.Sp
+.Vb 2
+\& char *  rninstr(const char *big, const char *bigend,
+\&                 const char *little, const char *lend)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savepv""" 4
+.el .IP \f(CWsavepv\fR 4
+.IX Xref "savepv"
+.IX Item "savepv"
+Perl's version of \f(CWstrdup()\fR.  Returns a pointer to a newly allocated
+string which is a duplicate of \f(CW\*(C`pv\*(C'\fR.  The size of the string is
+determined by \f(CWstrlen()\fR, which means it may not contain embedded \f(CW\*(C`NUL\*(C'\fR
+characters and must have a trailing \f(CW\*(C`NUL\*(C'\fR.  To prevent memory leaks, the
+memory allocated for the new string needs to be freed when no longer needed.
+This can be done with the \f(CW"Safefree"\fR function, or
+\&\f(CW\*(C`SAVEFREEPV\*(C'\fR.
+.Sp
+On some platforms, Windows for example, all allocated memory owned by a thread
+is deallocated when that thread ends.  So if you need that not to happen, you
+need to use the shared memory functions, such as \f(CW"savesharedpv"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char *  savepv(const char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savepvn""" 4
+.el .IP \f(CWsavepvn\fR 4
+.IX Xref "savepvn"
+.IX Item "savepvn"
+Perl's version of what \f(CWstrndup()\fR would be if it existed.  Returns a
+pointer to a newly allocated string which is a duplicate of the first
+\&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR, plus a trailing
+\&\f(CW\*(C`NUL\*(C'\fR byte.  The memory allocated for
+the new string can be freed with the \f(CWSafefree()\fR function.
+.Sp
+On some platforms, Windows for example, all allocated memory owned by a thread
+is deallocated when that thread ends.  So if you need that not to happen, you
+need to use the shared memory functions, such as \f(CW"savesharedpvn"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char *  savepvn(const char *pv, Size_t len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savepvs""" 4
+.el .IP \f(CWsavepvs\fR 4
+.IX Xref "savepvs"
+.IX Item "savepvs"
+Like \f(CW\*(C`savepvn\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& char*  savepvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savesharedpv""" 4
+.el .IP \f(CWsavesharedpv\fR 4
+.IX Xref "savesharedpv"
+.IX Item "savesharedpv"
+A version of \f(CWsavepv()\fR which allocates the duplicate string in memory
+which is shared between threads.
+.RS 4
+.Sp
+.Vb 1
+\& char *  savesharedpv(const char *pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savesharedpvn""" 4
+.el .IP \f(CWsavesharedpvn\fR 4
+.IX Xref "savesharedpvn"
+.IX Item "savesharedpvn"
+A version of \f(CWsavepvn()\fR which allocates the duplicate string in memory
+which is shared between threads.  (With the specific difference that a \f(CW\*(C`NULL\*(C'\fR
+pointer is not acceptable)
+.RS 4
+.Sp
+.Vb 1
+\& char *  savesharedpvn(const char * const pv, const STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savesharedpvs""" 4
+.el .IP \f(CWsavesharedpvs\fR 4
+.IX Xref "savesharedpvs"
+.IX Item "savesharedpvs"
+A version of \f(CWsavepvs()\fR which allocates the duplicate string in memory
+which is shared between threads.
+.RS 4
+.Sp
+.Vb 1
+\& char*  savesharedpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savesharedsvpv""" 4
+.el .IP \f(CWsavesharedsvpv\fR 4
+.IX Xref "savesharedsvpv"
+.IX Item "savesharedsvpv"
+A version of \f(CWsavesharedpv()\fR which allocates the duplicate string in
+memory which is shared between threads.
+.RS 4
+.Sp
+.Vb 1
+\& char *  savesharedsvpv(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """savesvpv""" 4
+.el .IP \f(CWsavesvpv\fR 4
+.IX Xref "savesvpv"
+.IX Item "savesvpv"
+A version of \f(CWsavepv()\fR/\f(CWsavepvn()\fR which gets the string to duplicate from
+the passed in SV using \f(CWSvPV()\fR
+.Sp
+On some platforms, Windows for example, all allocated memory owned by a thread
+is deallocated when that thread ends.  So if you need that not to happen, you
+need to use the shared memory functions, such as \f(CW"savesharedsvpv"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char *  savesvpv(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strEQ""" 4
+.el .IP \f(CWstrEQ\fR 4
+.IX Xref "strEQ"
+.IX Item "strEQ"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal.  Returns true or
+false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strEQ(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strGE""" 4
+.el .IP \f(CWstrGE\fR 4
+.IX Xref "strGE"
+.IX Item "strGE"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
+or equal to the second, \f(CW\*(C`s2\*(C'\fR.  Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strGE(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strGT""" 4
+.el .IP \f(CWstrGT\fR 4
+.IX Xref "strGT"
+.IX Item "strGT"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
+the second, \f(CW\*(C`s2\*(C'\fR.  Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strGT(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STRINGIFY""" 4
+.el .IP \f(CWSTRINGIFY\fR 4
+.IX Xref "STRINGIFY"
+.IX Item "STRINGIFY"
+This macro surrounds its token with double quotes.
+.RS 4
+.Sp
+.Vb 1
+\& string  STRINGIFY(token x)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strLE""" 4
+.el .IP \f(CWstrLE\fR 4
+.IX Xref "strLE"
+.IX Item "strLE"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than or
+equal to the second, \f(CW\*(C`s2\*(C'\fR.  Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strLE(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STRLEN""" 4
+.el .IP \f(CWSTRLEN\fR 4
+.IX Item "STRLEN"
+Described in perlguts.
+.ie n .IP """strLT""" 4
+.el .IP \f(CWstrLT\fR 4
+.IX Xref "strLT"
+.IX Item "strLT"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than the
+second, \f(CW\*(C`s2\*(C'\fR.  Returns true or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strLT(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strNE""" 4
+.el .IP \f(CWstrNE\fR 4
+.IX Xref "strNE"
+.IX Item "strNE"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different.  Returns true
+or false.
+.RS 4
+.Sp
+.Vb 1
+\& bool  strNE(char* s1, char* s2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strnEQ""" 4
+.el .IP \f(CWstrnEQ\fR 4
+.IX Xref "strnEQ"
+.IX Item "strnEQ"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal.  The \f(CW\*(C`len\*(C'\fR
+parameter indicates the number of bytes to compare.  Returns true or false.  (A
+wrapper for \f(CW\*(C`strncmp\*(C'\fR).
+.RS 4
+.Sp
+.Vb 1
+\& bool  strnEQ(char* s1, char* s2, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """strnNE""" 4
+.el .IP \f(CWstrnNE\fR 4
+.IX Xref "strnNE"
+.IX Item "strnNE"
+Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different.  The \f(CW\*(C`len\*(C'\fR
+parameter indicates the number of bytes to compare.  Returns true or false.  (A
+wrapper for \f(CW\*(C`strncmp\*(C'\fR).
+.RS 4
+.Sp
+.Vb 1
+\& bool  strnNE(char* s1, char* s2, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """STR_WITH_LEN""" 4
+.el .IP \f(CWSTR_WITH_LEN\fR 4
+.IX Xref "STR_WITH_LEN"
+.IX Item "STR_WITH_LEN"
+Returns two comma separated tokens of the input literal string, and its length.
+This is convenience macro which helps out in some API calls.
+Note that it can't be used as an argument to macros or functions that under
+some configurations might be macros, which means that it requires the full
+Perl_xxx(aTHX_ ...) form for any API calls where it's used.
+.RS 4
+.Sp
+.Vb 1
+\& pair  STR_WITH_LEN("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Zero""" 4
+.el .IP \f(CWZero\fR 4
+.IX Item "Zero"
+.PD 0
+.ie n .IP """ZeroD""" 4
+.el .IP \f(CWZeroD\fR 4
+.IX Xref "Zero ZeroD"
+.IX Item "ZeroD"
+.PD
+The XSUB-writer's interface to the C \f(CW\*(C`memzero\*(C'\fR function.  The \f(CW\*(C`dest\*(C'\fR is the
+destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type.
+.Sp
+\&\f(CW\*(C`ZeroD\*(C'\fR is like \f(CW\*(C`Zero\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR.  Useful
+for encouraging compilers to tail-call
+optimise.
+.RS 4
+.Sp
+.Vb 2
+\& void    Zero (void* dest, int nitems, type)
+\& void *  ZeroD(void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "SV Flags"
+.IX Header "SV Flags"
+.ie n .IP """SVt_IV""" 4
+.el .IP \f(CWSVt_IV\fR 4
+.IX Xref "SVt_IV"
+.IX Item "SVt_IV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_NULL""" 4
+.el .IP \f(CWSVt_NULL\fR 4
+.IX Xref "SVt_NULL"
+.IX Item "SVt_NULL"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_NV""" 4
+.el .IP \f(CWSVt_NV\fR 4
+.IX Xref "SVt_NV"
+.IX Item "SVt_NV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PV""" 4
+.el .IP \f(CWSVt_PV\fR 4
+.IX Xref "SVt_PV"
+.IX Item "SVt_PV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PVAV""" 4
+.el .IP \f(CWSVt_PVAV\fR 4
+.IX Xref "SVt_PVAV"
+.IX Item "SVt_PVAV"
+Type flag for arrays.  See "svtype".
+.ie n .IP """SVt_PVCV""" 4
+.el .IP \f(CWSVt_PVCV\fR 4
+.IX Xref "SVt_PVCV"
+.IX Item "SVt_PVCV"
+Type flag for subroutines.  See "svtype".
+.ie n .IP """SVt_PVFM""" 4
+.el .IP \f(CWSVt_PVFM\fR 4
+.IX Xref "SVt_PVFM"
+.IX Item "SVt_PVFM"
+Type flag for formats.  See "svtype".
+.ie n .IP """SVt_PVGV""" 4
+.el .IP \f(CWSVt_PVGV\fR 4
+.IX Xref "SVt_PVGV"
+.IX Item "SVt_PVGV"
+Type flag for typeglobs.  See "svtype".
+.ie n .IP """SVt_PVHV""" 4
+.el .IP \f(CWSVt_PVHV\fR 4
+.IX Xref "SVt_PVHV"
+.IX Item "SVt_PVHV"
+Type flag for hashes.  See "svtype".
+.ie n .IP """SVt_PVIO""" 4
+.el .IP \f(CWSVt_PVIO\fR 4
+.IX Xref "SVt_PVIO"
+.IX Item "SVt_PVIO"
+Type flag for I/O objects.  See "svtype".
+.ie n .IP """SVt_PVIV""" 4
+.el .IP \f(CWSVt_PVIV\fR 4
+.IX Xref "SVt_PVIV"
+.IX Item "SVt_PVIV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PVLV""" 4
+.el .IP \f(CWSVt_PVLV\fR 4
+.IX Xref "SVt_PVLV"
+.IX Item "SVt_PVLV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PVMG""" 4
+.el .IP \f(CWSVt_PVMG\fR 4
+.IX Xref "SVt_PVMG"
+.IX Item "SVt_PVMG"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PVNV""" 4
+.el .IP \f(CWSVt_PVNV\fR 4
+.IX Xref "SVt_PVNV"
+.IX Item "SVt_PVNV"
+Type flag for scalars.  See "svtype".
+.ie n .IP """SVt_PVOBJ""" 4
+.el .IP \f(CWSVt_PVOBJ\fR 4
+.IX Xref "SVt_PVOBJ"
+.IX Item "SVt_PVOBJ"
+NOTE: \f(CW\*(C`SVt_PVOBJ\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Type flag for object instances.  See "svtype".
+.ie n .IP """SVt_REGEXP""" 4
+.el .IP \f(CWSVt_REGEXP\fR 4
+.IX Xref "SVt_REGEXP"
+.IX Item "SVt_REGEXP"
+Type flag for regular expressions.  See "svtype".
+.ie n .IP """svtype""" 4
+.el .IP \f(CWsvtype\fR 4
+.IX Xref "svtype"
+.IX Item "svtype"
+An enum of flags for Perl types.  These are found in the file \fIsv.h\fR
+in the \f(CW\*(C`svtype\*(C'\fR enum.  Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro.
+.Sp
+The types are:
+.Sp
+.Vb 10
+\&    SVt_NULL
+\&    SVt_IV
+\&    SVt_NV
+\&    SVt_RV
+\&    SVt_PV
+\&    SVt_PVIV
+\&    SVt_PVNV
+\&    SVt_PVMG
+\&    SVt_INVLIST
+\&    SVt_REGEXP
+\&    SVt_PVGV
+\&    SVt_PVLV
+\&    SVt_PVAV
+\&    SVt_PVHV
+\&    SVt_PVCV
+\&    SVt_PVFM
+\&    SVt_PVIO
+\&    SVt_PVOBJ
+.Ve
+.Sp
+These are most easily explained from the bottom up.
+.Sp
+\&\f(CW\*(C`SVt_PVOBJ\*(C'\fR is for object instances of the new `use feature 'class'` kind.
+\&\f(CW\*(C`SVt_PVIO\*(C'\fR is for I/O objects, \f(CW\*(C`SVt_PVFM\*(C'\fR for formats, \f(CW\*(C`SVt_PVCV\*(C'\fR for
+subroutines, \f(CW\*(C`SVt_PVHV\*(C'\fR for hashes and \f(CW\*(C`SVt_PVAV\*(C'\fR for arrays.
+.Sp
+All the others are scalar types, that is, things that can be bound to a
+\&\f(CW\*(C`$\*(C'\fR variable.  For these, the internal types are mostly orthogonal to
+types in the Perl language.
+.Sp
+Hence, checking \f(CW\*(C`SvTYPE(sv) < SVt_PVAV\*(C'\fR is the best way to see whether
+something is a scalar.
+.Sp
+\&\f(CW\*(C`SVt_PVGV\*(C'\fR represents a typeglob.  If \f(CW\*(C`!SvFAKE(sv)\*(C'\fR, then it is a real,
+incoercible typeglob.  If \f(CWSvFAKE(sv)\fR, then it is a scalar to which a
+typeglob has been assigned.  Assigning to it again will stop it from being
+a typeglob.  \f(CW\*(C`SVt_PVLV\*(C'\fR represents a scalar that delegates to another scalar
+behind the scenes.  It is used, e.g., for the return value of \f(CW\*(C`substr\*(C'\fR and
+for tied hash and array elements.  It can hold any scalar value, including
+a typeglob.  \f(CW\*(C`SVt_REGEXP\*(C'\fR is for regular
+expressions.  \f(CW\*(C`SVt_INVLIST\*(C'\fR is for Perl
+core internal use only.
+.Sp
+\&\f(CW\*(C`SVt_PVMG\*(C'\fR represents a "normal" scalar (not a typeglob, regular expression,
+or delegate).  Since most scalars do not need all the internal fields of a
+PVMG, we save memory by allocating smaller structs when possible.  All the
+other types are just simpler forms of \f(CW\*(C`SVt_PVMG\*(C'\fR, with fewer internal fields.
+\&\f(CW\*(C`SVt_NULL\*(C'\fR can only hold undef.  \f(CW\*(C`SVt_IV\*(C'\fR can hold undef, an integer, or a
+reference.  (\f(CW\*(C`SVt_RV\*(C'\fR is an alias for \f(CW\*(C`SVt_IV\*(C'\fR, which exists for backward
+compatibility.)  \f(CW\*(C`SVt_NV\*(C'\fR can hold undef or a double. (In builds that support
+headless NVs, these could also hold a reference via a suitable offset, in the
+same way that SVt_IV does, but this is not currently supported and seems to
+be a rare use case.) \f(CW\*(C`SVt_PV\*(C'\fR can hold \f(CW\*(C`undef\*(C'\fR, a string, or a reference.
+\&\f(CW\*(C`SVt_PVIV\*(C'\fR is a superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_IV\*(C'\fR. \f(CW\*(C`SVt_PVNV\*(C'\fR is a
+superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_NV\*(C'\fR. \f(CW\*(C`SVt_PVMG\*(C'\fR can hold anything \f(CW\*(C`SVt_PVNV\*(C'\fR
+can hold, but it may also be blessed or magical.
+.SH "SV Handling"
+.IX Xref "SV_CATBYTES SV_CATUTF8 SV_COW_DROP_PV SV_FORCE_UTF8_UPGRADE SV_GMAGIC SV_HAS_TRAILING_NUL SV_IMMEDIATE_UNREF SV_NOSTEAL SV_SMAGIC SV_UTF8_NO_ENCODING SVs_TEMP"
+.IX Header "SV Handling"
+.ie n .IP """AV_FROM_REF""" 4
+.el .IP \f(CWAV_FROM_REF\fR 4
+.IX Item "AV_FROM_REF"
+.PD 0
+.ie n .IP """CV_FROM_REF""" 4
+.el .IP \f(CWCV_FROM_REF\fR 4
+.IX Item "CV_FROM_REF"
+.ie n .IP """HV_FROM_REF""" 4
+.el .IP \f(CWHV_FROM_REF\fR 4
+.IX Xref "AV_FROM_REF CV_FROM_REF HV_FROM_REF"
+.IX Item "HV_FROM_REF"
+.PD
+The \f(CW\*(C`\fR\f(CI*\fR\f(CWV_FROM_REF\*(C'\fR macros extract the \f(CWSvRV()\fR from a given reference SV
+and return a suitably-cast to pointer to the referenced SV. When running
+under \f(CW\*(C`\-DDEBUGGING\*(C'\fR, assertions are also applied that check that \fIref\fR is
+definitely a reference SV that refers to an SV of the right type.
+.RS 4
+.Sp
+.Vb 3
+\& AV *  AV_FROM_REF(SV * ref)
+\& CV *  CV_FROM_REF(SV * ref)
+\& HV *  HV_FROM_REF(SV * ref)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BOOL_INTERNALS_sv_isbool""" 4
+.el .IP \f(CWBOOL_INTERNALS_sv_isbool\fR 4
+.IX Xref "BOOL_INTERNALS_sv_isbool"
+.IX Item "BOOL_INTERNALS_sv_isbool"
+Checks if a \f(CWSvBoolFlagsOK()\fR sv is a bool. \fBNote\fR that it is the
+caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR before
+calling this. This is only useful in specialized logic like
+serialization code where performance is critical and the flags have
+already been checked to be correct. Almost always you should be using
+\&\f(CWsv_isbool(sv)\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  BOOL_INTERNALS_sv_isbool(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BOOL_INTERNALS_sv_isbool_false""" 4
+.el .IP \f(CWBOOL_INTERNALS_sv_isbool_false\fR 4
+.IX Xref "BOOL_INTERNALS_sv_isbool_false"
+.IX Item "BOOL_INTERNALS_sv_isbool_false"
+Checks if a \f(CWSvBoolFlagsOK()\fR sv is a false bool. \fBNote\fR that it is
+the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
+before calling this. This is only useful in specialized logic like
+serialization code where performance is critical and the flags have
+already been checked to be correct. This is \fBNOT\fR what you should use
+to check if an SV is "false", for that you should be using
+\&\f(CW\*(C`!SvTRUE(sv)\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  BOOL_INTERNALS_sv_isbool_false(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BOOL_INTERNALS_sv_isbool_true""" 4
+.el .IP \f(CWBOOL_INTERNALS_sv_isbool_true\fR 4
+.IX Xref "BOOL_INTERNALS_sv_isbool_true"
+.IX Item "BOOL_INTERNALS_sv_isbool_true"
+Checks if a \f(CWSvBoolFlagsOK()\fR sv is a true bool. \fBNote\fR that it is
+the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
+before calling this. This is only useful in specialized logic like
+serialization code where performance is critical and the flags have
+already been checked to be correct. This is \fBNOT\fR what you should use
+to check if an SV is "true", for that you should be using
+\&\f(CWSvTRUE(sv)\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  BOOL_INTERNALS_sv_isbool_true(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """boolSV""" 4
+.el .IP \f(CWboolSV\fR 4
+.IX Xref "boolSV"
+.IX Item "boolSV"
+Returns a true SV if \f(CW\*(C`b\*(C'\fR is a true value, or a false SV if \f(CW\*(C`b\*(C'\fR is 0.
+.Sp
+See also \f(CW"PL_sv_yes"\fR and \f(CW"PL_sv_no"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  boolSV(bool b)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """croak_xs_usage""" 4
+.el .IP \f(CWcroak_xs_usage\fR 4
+.IX Xref "croak_xs_usage"
+.IX Item "croak_xs_usage"
+A specialised variant of \f(CWcroak()\fR for emitting the usage message for xsubs
+.Sp
+.Vb 1
+\&    croak_xs_usage(cv, "eee_yow");
+.Ve
+.Sp
+works out the package name and subroutine name from \f(CW\*(C`cv\*(C'\fR, and then calls
+\&\f(CWcroak()\fR.  Hence if \f(CW\*(C`cv\*(C'\fR is \f(CW&ouch::awk\fR, it would call \f(CW\*(C`croak\*(C'\fR as:
+.Sp
+.Vb 2
+\& Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
+\&                                                     "eee_yow");
+.Ve
+.RS 4
+.Sp
+.Vb 2
+\& void  croak_xs_usage(const CV * const cv,
+\&                      const char * const params)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """DEFSV""" 4
+.el .IP \f(CWDEFSV\fR 4
+.IX Xref "DEFSV"
+.IX Item "DEFSV"
+Returns the SV associated with \f(CW$_\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  DEFSV
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """DEFSV_set""" 4
+.el .IP \f(CWDEFSV_set\fR 4
+.IX Xref "DEFSV_set"
+.IX Item "DEFSV_set"
+Associate \f(CW\*(C`sv\*(C'\fR with \f(CW$_\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  DEFSV_set(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_sv""" 4
+.el .IP \f(CWget_sv\fR 4
+.IX Xref "get_sv"
+.IX Item "get_sv"
+Returns the SV of the specified Perl scalar.  \f(CW\*(C`flags\*(C'\fR are passed to
+"\f(CW\*(C`gv_fetchpv\*(C'\fR".  If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
+Perl variable does not exist then it will be created.  If \f(CW\*(C`flags\*(C'\fR is zero
+and the variable does not exist then NULL is returned.
+.Sp
+NOTE: the \f(CWperl_get_sv()\fR form is \fBdeprecated\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  get_sv(const char *name, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isGV_with_GP""" 4
+.el .IP \f(CWisGV_with_GP\fR 4
+.IX Xref "isGV_with_GP"
+.IX Item "isGV_with_GP"
+Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR is a GV with a pointer to a GP
+(glob pointer).
+.RS 4
+.Sp
+.Vb 1
+\& bool  isGV_with_GP(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """looks_like_number""" 4
+.el .IP \f(CWlooks_like_number\fR 4
+.IX Xref "looks_like_number"
+.IX Item "looks_like_number"
+Test if the content of an SV looks like a number (or is a number).
+\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a
+non-numeric warning), even if your \f(CWatof()\fR doesn't grok them.  Get-magic is
+ignored.
+.RS 4
+.Sp
+.Vb 1
+\& I32  looks_like_number(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MUTABLE_AV""" 4
+.el .IP \f(CWMUTABLE_AV\fR 4
+.IX Item "MUTABLE_AV"
+.PD 0
+.ie n .IP """MUTABLE_CV""" 4
+.el .IP \f(CWMUTABLE_CV\fR 4
+.IX Item "MUTABLE_CV"
+.ie n .IP """MUTABLE_GV""" 4
+.el .IP \f(CWMUTABLE_GV\fR 4
+.IX Item "MUTABLE_GV"
+.ie n .IP """MUTABLE_HV""" 4
+.el .IP \f(CWMUTABLE_HV\fR 4
+.IX Item "MUTABLE_HV"
+.ie n .IP """MUTABLE_IO""" 4
+.el .IP \f(CWMUTABLE_IO\fR 4
+.IX Item "MUTABLE_IO"
+.ie n .IP """MUTABLE_PTR""" 4
+.el .IP \f(CWMUTABLE_PTR\fR 4
+.IX Item "MUTABLE_PTR"
+.ie n .IP """MUTABLE_SV""" 4
+.el .IP \f(CWMUTABLE_SV\fR 4
+.IX Xref "MUTABLE_AV MUTABLE_CV MUTABLE_GV MUTABLE_HV MUTABLE_IO MUTABLE_PTR MUTABLE_SV"
+.IX Item "MUTABLE_SV"
+.PD
+The \f(CW\*(C`MUTABLE_\fR\f(CI*\fR\f(CW\*(C'\fR() macros cast pointers to the types shown, in such a way
+(compiler permitting) that casting away const-ness will give a warning;
+e.g.:
+.Sp
+.Vb 4
+\& const SV *sv = ...;
+\& AV *av1 = (AV*)sv;        <== BAD:  the const has been silently
+\&                                     cast away
+\& AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
+.Ve
+.Sp
+\&\f(CW\*(C`MUTABLE_PTR\*(C'\fR is the base macro used to derive new casts.  The other
+already-built-in ones return pointers to what their names indicate.
+.RS 4
+.Sp
+.Vb 7
+\& AV *    MUTABLE_AV (AV * p)
+\& CV *    MUTABLE_CV (CV * p)
+\& GV *    MUTABLE_GV (GV * p)
+\& HV *    MUTABLE_HV (HV * p)
+\& IO *    MUTABLE_IO (IO * p)
+\& void *  MUTABLE_PTR(void * p)
+\& SV *    MUTABLE_SV (SV * p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newRV""" 4
+.el .IP \f(CWnewRV\fR 4
+.IX Item "newRV"
+.PD 0
+.ie n .IP """newRV_inc""" 4
+.el .IP \f(CWnewRV_inc\fR 4
+.IX Xref "newRV newRV_inc"
+.IX Item "newRV_inc"
+.PD
+These are identical.  They create an RV wrapper for an SV.  The reference count
+for the original SV is incremented.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newRV(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newRV_noinc""" 4
+.el .IP \f(CWnewRV_noinc\fR 4
+.IX Xref "newRV_noinc"
+.IX Item "newRV_noinc"
+Creates an RV wrapper for an SV.  The reference count for the original
+SV is \fBnot\fR incremented.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newRV_noinc(SV * const tmpRef)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSV""" 4
+.el .IP \f(CWnewSV\fR 4
+.IX Xref "newSV"
+.IX Item "newSV"
+Creates a new SV.  A non-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of
+bytes of preallocated string space the SV should have.  An extra byte for a
+trailing \f(CW\*(C`NUL\*(C'\fR is also reserved.  (\f(CW\*(C`SvPOK\*(C'\fR is not set for the SV even if string
+space is allocated.)  The reference count for the new SV is set to 1.
+.Sp
+In 5.9.3, \f(CWnewSV()\fR replaces the older \f(CWNEWSV()\fR API, and drops the first
+parameter, \fIx\fR, a debug aid which allowed callers to identify themselves.
+This aid has been superseded by a new build option, \f(CW\*(C`PERL_MEM_LOG\*(C'\fR (see
+"PERL_MEM_LOG" in perlhacktips).  The older API is still there for use in XS
+modules supporting older perls.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSV(const STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVbool""" 4
+.el .IP \f(CWnewSVbool\fR 4
+.IX Xref "newSVbool"
+.IX Item "newSVbool"
+Creates a new SV boolean.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVbool(const bool bool_val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSV_false""" 4
+.el .IP \f(CWnewSV_false\fR 4
+.IX Xref "newSV_false"
+.IX Item "newSV_false"
+Creates a new SV that is a boolean false.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSV_false()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVhek""" 4
+.el .IP \f(CWnewSVhek\fR 4
+.IX Xref "newSVhek"
+.IX Item "newSVhek"
+Creates a new SV from the hash key structure.  It will generate scalars that
+point to the shared string table where possible.  Returns a new (undefined)
+SV if \f(CW\*(C`hek\*(C'\fR is NULL.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVhek(const HEK * const hek)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVhek_mortal""" 4
+.el .IP \f(CWnewSVhek_mortal\fR 4
+.IX Xref "newSVhek_mortal"
+.IX Item "newSVhek_mortal"
+Creates a new mortal SV from the hash key structure.  It will generate
+scalars that point to the shared string table where possible.  Returns
+a new (undefined) SV if \f(CW\*(C`hek\*(C'\fR is NULL.
+.Sp
+This is more efficient than using sv_2mortal(newSVhek( ... ))
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVhek_mortal(const HEK * const hek)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSViv""" 4
+.el .IP \f(CWnewSViv\fR 4
+.IX Xref "newSViv"
+.IX Item "newSViv"
+Creates a new SV and copies an integer into it.  The reference count for the
+SV is set to 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSViv(const IV i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVnv""" 4
+.el .IP \f(CWnewSVnv\fR 4
+.IX Xref "newSVnv"
+.IX Item "newSVnv"
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVnv(const NV n)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpadname""" 4
+.el .IP \f(CWnewSVpadname\fR 4
+.IX Xref "newSVpadname"
+.IX Item "newSVpadname"
+NOTE: \f(CW\*(C`newSVpadname\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Creates a new SV containing the pad name.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  newSVpadname(PADNAME *pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpv""" 4
+.el .IP \f(CWnewSVpv\fR 4
+.IX Xref "newSVpv"
+.IX Item "newSVpv"
+Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
+characters) into it.  The reference count for the
+SV is set to 1.  If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using
+\&\f(CWstrlen()\fR, (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded
+\&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
+.Sp
+This function can cause reliability issues if you are likely to pass in
+empty strings that are not null terminated, because it will run
+strlen on the string and potentially run past valid memory.
+.Sp
+Using "newSVpvn" is a safer alternative for non \f(CW\*(C`NUL\*(C'\fR terminated strings.
+For string literals use "newSVpvs" instead.  This function will work fine for
+\&\f(CW\*(C`NUL\*(C'\fR terminated strings, but if you want to avoid the if statement on whether
+to call \f(CW\*(C`strlen\*(C'\fR use \f(CW\*(C`newSVpvn\*(C'\fR instead (calling \f(CW\*(C`strlen\*(C'\fR yourself).
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVpv(const char * const s, const STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvf""" 4
+.el .IP \f(CWnewSVpvf\fR 4
+.IX Xref "newSVpvf"
+.IX Item "newSVpvf"
+Creates a new SV and initializes it with the string formatted like
+\&\f(CW\*(C`sv_catpvf\*(C'\fR.
+.Sp
+NOTE: \f(CW\*(C`newSVpvf\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_newSVpvf\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  Perl_newSVpvf(pTHX_ const char * const pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvf_nocontext""" 4
+.el .IP \f(CWnewSVpvf_nocontext\fR 4
+.IX Xref "newSVpvf_nocontext"
+.IX Item "newSVpvf_nocontext"
+Like \f(CW"newSVpvf"\fR but does not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter,
+so is used in situations where the caller doesn't already have the thread
+context.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVpvf_nocontext(const char * const pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvn""" 4
+.el .IP \f(CWnewSVpvn\fR 4
+.IX Xref "newSVpvn"
+.IX Item "newSVpvn"
+Creates a new SV and copies a string into it, which may contain \f(CW\*(C`NUL\*(C'\fR characters
+(\f(CW\*(C`\e0\*(C'\fR) and other binary data.  The reference count for the SV is set to 1.
+Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length (Perl) string.  You
+are responsible for ensuring that the source buffer is at least
+\&\f(CW\*(C`len\*(C'\fR bytes long.  If the \f(CW\*(C`buffer\*(C'\fR argument is NULL the new SV will be
+undefined.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVpvn(const char * const buffer, const STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvn_flags""" 4
+.el .IP \f(CWnewSVpvn_flags\fR 4
+.IX Xref "newSVpvn_flags"
+.IX Item "newSVpvn_flags"
+Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
+characters) into it.  The reference count for the
+SV is set to 1.  Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length
+string.  You are responsible for ensuring that the source string is at least
+\&\f(CW\*(C`len\*(C'\fR bytes long.  If the \f(CW\*(C`s\*(C'\fR argument is NULL the new SV will be undefined.
+Currently the only flag bits accepted are \f(CW\*(C`SVf_UTF8\*(C'\fR and \f(CW\*(C`SVs_TEMP\*(C'\fR.
+If \f(CW\*(C`SVs_TEMP\*(C'\fR is set, then \f(CWsv_2mortal()\fR is called on the result before
+returning.  If \f(CW\*(C`SVf_UTF8\*(C'\fR is set, \f(CW\*(C`s\*(C'\fR
+is considered to be in UTF\-8 and the
+\&\f(CW\*(C`SVf_UTF8\*(C'\fR flag will be set on the new SV.
+\&\f(CWnewSVpvn_utf8()\fR is a convenience wrapper for this function, defined as
+.Sp
+.Vb 2
+\&    #define newSVpvn_utf8(s, len, u)                    \e
+\&        newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
+.Ve
+.RS 4
+.Sp
+.Vb 2
+\& SV *  newSVpvn_flags(const char * const s, const STRLEN len,
+\&                      const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvn_share""" 4
+.el .IP \f(CWnewSVpvn_share\fR 4
+.IX Xref "newSVpvn_share"
+.IX Item "newSVpvn_share"
+Creates a new SV with its \f(CW\*(C`SvPVX_const\*(C'\fR pointing to a shared string in the string
+table.  If the string does not already exist in the table, it is
+created first.  Turns on the \f(CW\*(C`SvIsCOW\*(C'\fR flag (or \f(CW\*(C`READONLY\*(C'\fR
+and \f(CW\*(C`FAKE\*(C'\fR in 5.16 and earlier).  If the \f(CW\*(C`hash\*(C'\fR parameter
+is non-zero, that value is used; otherwise the hash is computed.
+The string's hash can later be retrieved from the SV
+with the \f(CW"SvSHARED_HASH"\fR macro.  The idea here is
+that as the string table is used for shared hash keys these strings will have
+\&\f(CW\*(C`SvPVX_const == HeKEY\*(C'\fR and hash lookup will avoid string compare.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVpvn_share(const char *s, I32 len, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvn_utf8""" 4
+.el .IP \f(CWnewSVpvn_utf8\fR 4
+.IX Xref "newSVpvn_utf8"
+.IX Item "newSVpvn_utf8"
+Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
+characters) into it.  If \f(CW\*(C`utf8\*(C'\fR is true, calls
+\&\f(CW\*(C`SvUTF8_on\*(C'\fR on the new SV.  Implemented as a wrapper around \f(CW\*(C`newSVpvn_flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvs""" 4
+.el .IP \f(CWnewSVpvs\fR 4
+.IX Xref "newSVpvs"
+.IX Item "newSVpvs"
+Like \f(CW\*(C`newSVpvn\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  newSVpvs("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvs_flags""" 4
+.el .IP \f(CWnewSVpvs_flags\fR 4
+.IX Xref "newSVpvs_flags"
+.IX Item "newSVpvs_flags"
+Like \f(CW\*(C`newSVpvn_flags\*(C'\fR, but takes a literal string instead of
+a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  newSVpvs_flags("literal string", U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpv_share""" 4
+.el .IP \f(CWnewSVpv_share\fR 4
+.IX Xref "newSVpv_share"
+.IX Item "newSVpv_share"
+Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a \f(CW\*(C`NUL\*(C'\fR\-terminated string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVpv_share(const char *s, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVpvs_share""" 4
+.el .IP \f(CWnewSVpvs_share\fR 4
+.IX Xref "newSVpvs_share"
+.IX Item "newSVpvs_share"
+Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a literal string instead of
+a string/length pair and omits the hash parameter.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  newSVpvs_share("literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVrv""" 4
+.el .IP \f(CWnewSVrv\fR 4
+.IX Xref "newSVrv"
+.IX Item "newSVrv"
+Creates a new SV for the existing RV, \f(CW\*(C`rv\*(C'\fR, to point to.  If \f(CW\*(C`rv\*(C'\fR is not an
+RV then it will be upgraded to one.  If \f(CW\*(C`classname\*(C'\fR is non-null then the new
+SV will be blessed in the specified package.  The new SV is returned and its
+reference count is 1.  The reference count 1 is owned by \f(CW\*(C`rv\*(C'\fR. See also
+\&\fBnewRV_inc()\fR and \fBnewRV_noinc()\fR for creating a new RV properly.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVrv(SV * const rv, const char * const classname)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVsv""" 4
+.el .IP \f(CWnewSVsv\fR 4
+.IX Item "newSVsv"
+.PD 0
+.ie n .IP """newSVsv_flags""" 4
+.el .IP \f(CWnewSVsv_flags\fR 4
+.IX Item "newSVsv_flags"
+.ie n .IP """newSVsv_nomg""" 4
+.el .IP \f(CWnewSVsv_nomg\fR 4
+.IX Xref "newSVsv newSVsv_flags newSVsv_nomg"
+.IX Item "newSVsv_nomg"
+.PD
+These create a new SV which is an exact duplicate of the original SV
+(using \f(CW\*(C`sv_setsv\*(C'\fR.)
+.Sp
+They differ only in that \f(CW\*(C`newSVsv\*(C'\fR performs 'get' magic; \f(CW\*(C`newSVsv_nomg\*(C'\fR skips
+any magic; and \f(CW\*(C`newSVsv_flags\*(C'\fR allows you to explicitly set a \f(CW\*(C`flags\*(C'\fR
+parameter.
+.RS 4
+.Sp
+.Vb 3
+\& SV *  newSVsv      (SV * const old)
+\& SV *  newSVsv_flags(SV * const old, I32 flags)
+\& SV *  newSVsv_nomg (SV * const old)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSV_true""" 4
+.el .IP \f(CWnewSV_true\fR 4
+.IX Xref "newSV_true"
+.IX Item "newSV_true"
+Creates a new SV that is a boolean true.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSV_true()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSV_type""" 4
+.el .IP \f(CWnewSV_type\fR 4
+.IX Xref "newSV_type"
+.IX Item "newSV_type"
+Creates a new SV, of the type specified.  The reference count for the new SV
+is set to 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSV_type(const svtype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSV_type_mortal""" 4
+.el .IP \f(CWnewSV_type_mortal\fR 4
+.IX Xref "newSV_type_mortal"
+.IX Item "newSV_type_mortal"
+Creates a new mortal SV, of the type specified.  The reference count for the
+new SV is set to 1.
+.Sp
+This is equivalent to
+    SV* sv = sv_2mortal(newSV_type(<some type>))
+and
+    SV* sv = \fBsv_newmortal()\fR;
+    sv_upgrade(sv, <some_type>)
+but should be more efficient than both of them. (Unless sv_2mortal is inlined
+at some point in the future.)
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSV_type_mortal(const svtype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newSVuv""" 4
+.el .IP \f(CWnewSVuv\fR 4
+.IX Xref "newSVuv"
+.IX Item "newSVuv"
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  newSVuv(const UV u)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Nullsv""" 4
+.el .IP \f(CWNullsv\fR 4
+.IX Xref "Nullsv"
+.IX Item "Nullsv"
+Null SV pointer.  (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is defined.)
+.ie n .IP """PL_sv_no""" 4
+.el .IP \f(CWPL_sv_no\fR 4
+.IX Xref "PL_sv_no"
+.IX Item "PL_sv_no"
+This is the \f(CW\*(C`false\*(C'\fR SV.  It is readonly.  See \f(CW"PL_sv_yes"\fR.  Always refer
+to this as \f(CW&PL_sv_no\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV  PL_sv_no
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_sv_undef""" 4
+.el .IP \f(CWPL_sv_undef\fR 4
+.IX Xref "PL_sv_undef"
+.IX Item "PL_sv_undef"
+This is the \f(CW\*(C`undef\*(C'\fR SV.  It is readonly.  Always refer to this as
+\&\f(CW&PL_sv_undef\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV  PL_sv_undef
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_sv_yes""" 4
+.el .IP \f(CWPL_sv_yes\fR 4
+.IX Xref "PL_sv_yes"
+.IX Item "PL_sv_yes"
+This is the \f(CW\*(C`true\*(C'\fR SV.  It is readonly.  See \f(CW"PL_sv_no"\fR.  Always refer to
+this as \f(CW&PL_sv_yes\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV  PL_sv_yes
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_sv_zero""" 4
+.el .IP \f(CWPL_sv_zero\fR 4
+.IX Xref "PL_sv_zero"
+.IX Item "PL_sv_zero"
+This readonly SV has a zero numeric value and a \f(CW"0"\fR string value. It's
+similar to \f(CW"PL_sv_no"\fR except for its string value. Can be used as a
+cheap alternative to \f(CWmXPUSHi(0)\fR for example.  Always refer to this as
+\&\f(CW&PL_sv_zero\fR. Introduced in 5.28.
+.RS 4
+.Sp
+.Vb 1
+\& SV  PL_sv_zero
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVE_DEFSV""" 4
+.el .IP \f(CWSAVE_DEFSV\fR 4
+.IX Xref "SAVE_DEFSV"
+.IX Item "SAVE_DEFSV"
+Localize \f(CW$_\fR.  See "Localizing changes" in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  SAVE_DEFSV
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sortsv""" 4
+.el .IP \f(CWsortsv\fR 4
+.IX Xref "sortsv"
+.IX Item "sortsv"
+In-place sort an array of SV pointers with the given comparison routine.
+.Sp
+Currently this always uses mergesort.  See \f(CW"sortsv_flags"\fR for a more
+flexible routine.
+.RS 4
+.Sp
+.Vb 1
+\& void  sortsv(SV **array, size_t num_elts, SVCOMPARE_t cmp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sortsv_flags""" 4
+.el .IP \f(CWsortsv_flags\fR 4
+.IX Xref "sortsv_flags"
+.IX Item "sortsv_flags"
+In-place sort an array of SV pointers with the given comparison routine,
+with various SORTf_* flag options.
+.RS 4
+.Sp
+.Vb 2
+\& void  sortsv_flags(SV **array, size_t num_elts, SVCOMPARE_t cmp,
+\&                    U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SV""" 4
+.el .IP \f(CWSV\fR 4
+.IX Item "SV"
+Described in perlguts.
+.ie n .IP """SvAMAGIC""" 4
+.el .IP \f(CWSvAMAGIC\fR 4
+.IX Xref "SvAMAGIC"
+.IX Item "SvAMAGIC"
+Returns a boolean as to whether \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled or
+not.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvAMAGIC(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvAMAGIC_off""" 4
+.el .IP \f(CWSvAMAGIC_off\fR 4
+.IX Xref "SvAMAGIC_off"
+.IX Item "SvAMAGIC_off"
+Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) disabled.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvAMAGIC_off(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvAMAGIC_on""" 4
+.el .IP \f(CWSvAMAGIC_on\fR 4
+.IX Xref "SvAMAGIC_on"
+.IX Item "SvAMAGIC_on"
+Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvAMAGIC_on(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_backoff""" 4
+.el .IP \f(CWsv_backoff\fR 4
+.IX Xref "sv_backoff"
+.IX Item "sv_backoff"
+Remove any string offset.  You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro
+wrapper instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_backoff(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_bless""" 4
+.el .IP \f(CWsv_bless\fR 4
+.IX Xref "sv_bless"
+.IX Item "sv_bless"
+Blesses an SV into a specified package.  The SV must be an RV.  The package
+must be designated by its stash (see \f(CW"gv_stashpv"\fR).  The reference count
+of the SV is unaffected.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_bless(SV * const sv, HV * const stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvBoolFlagsOK""" 4
+.el .IP \f(CWSvBoolFlagsOK\fR 4
+.IX Xref "SvBoolFlagsOK"
+.IX Item "SvBoolFlagsOK"
+Returns a bool indicating whether the SV has the right flags set such
+that it is safe to call \f(CWBOOL_INTERNALS_sv_isbool()\fR or
+\&\f(CWBOOL_INTERNALS_sv_isbool_true()\fR or
+\&\f(CWBOOL_INTERNALS_sv_isbool_false()\fR. Currently equivalent to
+\&\f(CWSvIandPOK(sv)\fR or \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR. Serialization may want to
+unroll this check. If so you are strongly recommended to add code like
+\&\f(CW\*(C`assert(SvBoolFlagsOK(sv));\*(C'\fR \fBbefore\fR calling using any of the
+BOOL_INTERNALS macros.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvBoolFlagsOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpv""" 4
+.el .IP \f(CWsv_catpv\fR 4
+.IX Item "sv_catpv"
+.PD 0
+.ie n .IP """sv_catpv_flags""" 4
+.el .IP \f(CWsv_catpv_flags\fR 4
+.IX Item "sv_catpv_flags"
+.ie n .IP """sv_catpv_mg""" 4
+.el .IP \f(CWsv_catpv_mg\fR 4
+.IX Item "sv_catpv_mg"
+.ie n .IP """sv_catpv_nomg""" 4
+.el .IP \f(CWsv_catpv_nomg\fR 4
+.IX Xref "sv_catpv sv_catpv_flags sv_catpv_mg sv_catpv_nomg"
+.IX Item "sv_catpv_nomg"
+.PD
+These concatenate the \f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`sstr\*(C'\fR onto the end of the
+string which is in the SV.
+If the SV has the UTF\-8 status set, then the bytes appended should be
+valid UTF\-8.
+.Sp
+They differ only in how they handle magic:
+.Sp
+\&\f(CW\*(C`sv_catpv_mg\*(C'\fR performs both 'get' and 'set' magic.
+.Sp
+\&\f(CW\*(C`sv_catpv\*(C'\fR performs only 'get' magic.
+.Sp
+\&\f(CW\*(C`sv_catpv_nomg\*(C'\fR skips all magic.
+.Sp
+\&\f(CW\*(C`sv_catpv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify
+any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR), and
+to also override the UTF\-8 handling.  By supplying the \f(CW\*(C`SV_CATUTF8\*(C'\fR flag, the
+appended string is forced to be interpreted as UTF\-8; by supplying instead the
+\&\f(CW\*(C`SV_CATBYTES\*(C'\fR flag, it will be interpreted as just bytes.  Either the SV or
+the string appended will be upgraded to UTF\-8 if necessary.
+.RS 4
+.Sp
+.Vb 4
+\& void  sv_catpv      (SV * const dsv, const char *sstr)
+\& void  sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
+\& void  sv_catpv_mg   (SV * const dsv, const char * const sstr)
+\& void  sv_catpv_nomg (SV * const dsv, const char *sstr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvf""" 4
+.el .IP \f(CWsv_catpvf\fR 4
+.IX Item "sv_catpvf"
+.PD 0
+.ie n .IP """sv_catpvf_mg""" 4
+.el .IP \f(CWsv_catpvf_mg\fR 4
+.IX Item "sv_catpvf_mg"
+.ie n .IP """sv_catpvf_mg_nocontext""" 4
+.el .IP \f(CWsv_catpvf_mg_nocontext\fR 4
+.IX Item "sv_catpvf_mg_nocontext"
+.ie n .IP """sv_catpvf_nocontext""" 4
+.el .IP \f(CWsv_catpvf_nocontext\fR 4
+.IX Xref "sv_catpvf sv_catpvf_mg sv_catpvf_mg_nocontext sv_catpvf_nocontext"
+.IX Item "sv_catpvf_nocontext"
+.PD
+These process their arguments like \f(CW\*(C`sprintf\*(C'\fR, and append the formatted
+output to an SV.  As with \f(CW\*(C`sv_vcatpvfn\*(C'\fR, argument reordering is not supporte
+when called with a non-null C\-style variable argument list.
+.Sp
+If the appended data contains "wide" characters
+(including, but not limited to, SVs with a UTF\-8 PV formatted with \f(CW%s\fR,
+and characters >255 formatted with \f(CW%c\fR), the original SV might get
+upgraded to UTF\-8.
+.Sp
+If the original SV was UTF\-8, the pattern should be
+valid UTF\-8; if the original SV was bytes, the pattern should be too.
+.Sp
+All perform 'get' magic, but only \f(CW\*(C`sv_catpvf_mg\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR
+perform 'set' magic.
+.Sp
+\&\f(CW\*(C`sv_catpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR do not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
+doesn't already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`sv_catpvf\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_sv_catpvf\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.Sp
+NOTE: \f(CW\*(C`sv_catpvf_mg\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_sv_catpvf_mg\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 8
+\& void  Perl_sv_catpvf        (pTHX_ SV * const sv,
+\&                              const char * const pat, ...)
+\& void  Perl_sv_catpvf_mg     (pTHX_ SV * const sv,
+\&                              const char * const pat, ...)
+\& void  sv_catpvf_mg_nocontext(SV * const sv,
+\&                              const char * const pat, ...)
+\& void  sv_catpvf_nocontext   (SV * const sv,
+\&                              const char * const pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvn""" 4
+.el .IP \f(CWsv_catpvn\fR 4
+.IX Item "sv_catpvn"
+.PD 0
+.ie n .IP """sv_catpvn_flags""" 4
+.el .IP \f(CWsv_catpvn_flags\fR 4
+.IX Item "sv_catpvn_flags"
+.ie n .IP """sv_catpvn_mg""" 4
+.el .IP \f(CWsv_catpvn_mg\fR 4
+.IX Item "sv_catpvn_mg"
+.ie n .IP """sv_catpvn_nomg""" 4
+.el .IP \f(CWsv_catpvn_nomg\fR 4
+.IX Xref "sv_catpvn sv_catpvn_flags sv_catpvn_mg sv_catpvn_nomg"
+.IX Item "sv_catpvn_nomg"
+.PD
+These concatenate the \f(CW\*(C`len\*(C'\fR bytes of the string beginning at \f(CW\*(C`ptr\*(C'\fR onto the
+end of the string which is in \f(CW\*(C`dsv\*(C'\fR.  The caller must make sure \f(CW\*(C`ptr\*(C'\fR
+contains at least \f(CW\*(C`len\*(C'\fR bytes.
+.Sp
+For all but \f(CW\*(C`sv_catpvn_flags\*(C'\fR, the string appended is assumed to be valid
+UTF\-8 if the SV has the UTF\-8 status set, and a string of bytes otherwise.
+.Sp
+They differ in that:
+.Sp
+\&\f(CW\*(C`sv_catpvn_mg\*(C'\fR performs both 'get' and 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
+.Sp
+\&\f(CW\*(C`sv_catpvn\*(C'\fR performs only 'get' magic.
+.Sp
+\&\f(CW\*(C`sv_catpvn_nomg\*(C'\fR skips all magic.
+.Sp
+\&\f(CW\*(C`sv_catpvn_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify
+any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR) and
+to also override the UTF\-8 handling.  By supplying the \f(CW\*(C`SV_CATBYTES\*(C'\fR flag, the
+appended string is interpreted as plain bytes; by supplying instead the
+\&\f(CW\*(C`SV_CATUTF8\*(C'\fR flag, it will be interpreted as UTF\-8, and the \f(CW\*(C`dsv\*(C'\fR will be
+upgraded to UTF\-8 if necessary.
+.Sp
+\&\f(CW\*(C`sv_catpvn\*(C'\fR, \f(CW\*(C`sv_catpvn_mg\*(C'\fR, and \f(CW\*(C`sv_catpvn_nomg\*(C'\fR are implemented
+in terms of \f(CW\*(C`sv_catpvn_flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 5
+\& void  sv_catpvn      (SV *dsv, const char *sstr, STRLEN len)
+\& void  sv_catpvn_flags(SV * const dsv, const char *sstr,
+\&                       const STRLEN len, const I32 flags)
+\& void  sv_catpvn_mg   (SV *dsv, const char *sstr, STRLEN len)
+\& void  sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvs""" 4
+.el .IP \f(CWsv_catpvs\fR 4
+.IX Xref "sv_catpvs"
+.IX Item "sv_catpvs"
+Like \f(CW\*(C`sv_catpvn\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_catpvs(SV* sv, "literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvs_flags""" 4
+.el .IP \f(CWsv_catpvs_flags\fR 4
+.IX Xref "sv_catpvs_flags"
+.IX Item "sv_catpvs_flags"
+Like \f(CW\*(C`sv_catpvn_flags\*(C'\fR, but takes a literal string instead
+of a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_catpvs_flags(SV* sv, "literal string", I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvs_mg""" 4
+.el .IP \f(CWsv_catpvs_mg\fR 4
+.IX Xref "sv_catpvs_mg"
+.IX Item "sv_catpvs_mg"
+Like \f(CW\*(C`sv_catpvn_mg\*(C'\fR, but takes a literal string instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_catpvs_mg(SV* sv, "literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catpvs_nomg""" 4
+.el .IP \f(CWsv_catpvs_nomg\fR 4
+.IX Xref "sv_catpvs_nomg"
+.IX Item "sv_catpvs_nomg"
+Like \f(CW\*(C`sv_catpvn_nomg\*(C'\fR, but takes a literal string instead of
+a string/length pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_catpvs_nomg(SV* sv, "literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_catsv""" 4
+.el .IP \f(CWsv_catsv\fR 4
+.IX Item "sv_catsv"
+.PD 0
+.ie n .IP """sv_catsv_flags""" 4
+.el .IP \f(CWsv_catsv_flags\fR 4
+.IX Item "sv_catsv_flags"
+.ie n .IP """sv_catsv_mg""" 4
+.el .IP \f(CWsv_catsv_mg\fR 4
+.IX Item "sv_catsv_mg"
+.ie n .IP """sv_catsv_nomg""" 4
+.el .IP \f(CWsv_catsv_nomg\fR 4
+.IX Xref "sv_catsv sv_catsv_flags sv_catsv_mg sv_catsv_nomg"
+.IX Item "sv_catsv_nomg"
+.PD
+These concatenate the string from SV \f(CW\*(C`sstr\*(C'\fR onto the end of the string in SV
+\&\f(CW\*(C`dsv\*(C'\fR.  If \f(CW\*(C`sstr\*(C'\fR is null, these are no-ops; otherwise only \f(CW\*(C`dsv\*(C'\fR is
+modified.
+.Sp
+They differ only in what magic they perform:
+.Sp
+\&\f(CW\*(C`sv_catsv_mg\*(C'\fR performs 'get' magic on both SVs before the copy, and 'set' magic
+on \f(CW\*(C`dsv\*(C'\fR afterwards.
+.Sp
+\&\f(CW\*(C`sv_catsv\*(C'\fR performs just 'get' magic, on both SVs.
+.Sp
+\&\f(CW\*(C`sv_catsv_nomg\*(C'\fR skips all magic.
+.Sp
+\&\f(CW\*(C`sv_catsv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to use
+\&\f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR to specify any combination of magic handling
+(although either both or neither SV will have 'get' magic applied to it.)
+.Sp
+\&\f(CW\*(C`sv_catsv\*(C'\fR, \f(CW\*(C`sv_catsv_mg\*(C'\fR, and \f(CW\*(C`sv_catsv_nomg\*(C'\fR are implemented
+in terms of \f(CW\*(C`sv_catsv_flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 5
+\& void  sv_catsv      (SV *dsv, SV *sstr)
+\& void  sv_catsv_flags(SV * const dsv, SV * const sstr,
+\&                      const I32 flags)
+\& void  sv_catsv_mg   (SV *dsv, SV *sstr)
+\& void  sv_catsv_nomg (SV *dsv, SV *sstr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SV_CHECK_THINKFIRST""" 4
+.el .IP \f(CWSV_CHECK_THINKFIRST\fR 4
+.IX Xref "SV_CHECK_THINKFIRST"
+.IX Item "SV_CHECK_THINKFIRST"
+Remove any encumbrances from \f(CW\*(C`sv\*(C'\fR, that need to be taken care of before it
+is modifiable.  For example if it is Copy on Write (COW), now is the time to
+make that copy.
+.Sp
+If you know that you are about to change the PV value of \f(CW\*(C`sv\*(C'\fR, instead use
+"\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" to avoid the write that would be
+immediately written again.
+.RS 4
+.Sp
+.Vb 1
+\& void  SV_CHECK_THINKFIRST(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SV_CHECK_THINKFIRST_COW_DROP""" 4
+.el .IP \f(CWSV_CHECK_THINKFIRST_COW_DROP\fR 4
+.IX Xref "SV_CHECK_THINKFIRST_COW_DROP"
+.IX Item "SV_CHECK_THINKFIRST_COW_DROP"
+Call this when you are about to replace the PV value in \f(CW\*(C`sv\*(C'\fR, which is
+potentially copy-on-write.  It stops any sharing with other SVs, so that no
+Copy on Write (COW) actually happens.  This COW would be useless, as it would
+immediately get changed to something else.  This function also removes any
+other encumbrances that would be problematic when changing \f(CW\*(C`sv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SV_CHECK_THINKFIRST_COW_DROP(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_chop""" 4
+.el .IP \f(CWsv_chop\fR 4
+.IX Xref "sv_chop"
+.IX Item "sv_chop"
+Efficient removal of characters from the beginning of the string buffer.
+\&\f(CWSvPOK(sv)\fR, or at least \f(CWSvPOKp(sv)\fR, must be true and \f(CW\*(C`ptr\*(C'\fR must be a
+pointer to somewhere inside the string buffer.  \f(CW\*(C`ptr\*(C'\fR becomes the first
+character of the adjusted string.  Uses the \f(CW\*(C`OOK\*(C'\fR hack.  On return, only
+\&\f(CWSvPOK(sv)\fR and \f(CWSvPOKp(sv)\fR among the \f(CW\*(C`OK\*(C'\fR flags will be true.
+.Sp
+Beware: after this function returns, \f(CW\*(C`ptr\*(C'\fR and SvPVX_const(sv) may no longer
+refer to the same chunk of data.
+.Sp
+The unfortunate similarity of this function's name to that of Perl's \f(CW\*(C`chop\*(C'\fR
+operator is strictly coincidental.  This function works from the left;
+\&\f(CW\*(C`chop\*(C'\fR works from the right.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_chop(SV * const sv, const char * const ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_clear""" 4
+.el .IP \f(CWsv_clear\fR 4
+.IX Xref "sv_clear"
+.IX Item "sv_clear"
+Clear an SV: call any destructors, free up any memory used by the body,
+and free the body itself.  The SV's head is \fInot\fR freed, although
+its type is set to all 1's so that it won't inadvertently be assumed
+to be live during global destruction etc.
+This function should only be called when \f(CW\*(C`REFCNT\*(C'\fR is zero.  Most of the time
+you'll want to call \f(CW\*(C`SvREFCNT_dec\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_clear(SV * const orig_sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_cmp""" 4
+.el .IP \f(CWsv_cmp\fR 4
+.IX Xref "sv_cmp"
+.IX Item "sv_cmp"
+Compares the strings in two SVs.  Returns \-1, 0, or 1 indicating whether the
+string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in
+\&\f(CW\*(C`sv2\*(C'\fR.  Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will
+coerce its args to strings if necessary.  See also \f(CW"sv_cmp_locale"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_cmp(SV * const sv1, SV * const sv2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_cmp_flags""" 4
+.el .IP \f(CWsv_cmp_flags\fR 4
+.IX Xref "sv_cmp_flags"
+.IX Item "sv_cmp_flags"
+Compares the strings in two SVs.  Returns \-1, 0, or 1 indicating whether the
+string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in
+\&\f(CW\*(C`sv2\*(C'\fR.  Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings
+if necessary.  If the flags has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles get magic.  See
+also \f(CW"sv_cmp_locale_flags"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_cmp_locale""" 4
+.el .IP \f(CWsv_cmp_locale\fR 4
+.IX Xref "sv_cmp_locale"
+.IX Item "sv_cmp_locale"
+Compares the strings in two SVs in a locale-aware manner.  Is UTF\-8 and
+\&\f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will coerce its args to strings
+if necessary.  See also \f(CW"sv_cmp"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_cmp_locale(SV * const sv1, SV * const sv2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_cmp_locale_flags""" 4
+.el .IP \f(CWsv_cmp_locale_flags\fR 4
+.IX Xref "sv_cmp_locale_flags"
+.IX Item "sv_cmp_locale_flags"
+Compares the strings in two SVs in a locale-aware manner.  Is UTF\-8 and
+\&\f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings if necessary.  If
+the flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get magic.  See also
+\&\f(CW"sv_cmp_flags"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& I32  sv_cmp_locale_flags(SV * const sv1, SV * const sv2,
+\&                          const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_collxfrm""" 4
+.el .IP \f(CWsv_collxfrm\fR 4
+.IX Xref "sv_collxfrm"
+.IX Item "sv_collxfrm"
+This calls \f(CW\*(C`sv_collxfrm_flags\*(C'\fR with the SV_GMAGIC flag.  See
+\&\f(CW"sv_collxfrm_flags"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_collxfrm(SV * const sv, STRLEN * const nxp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_collxfrm_flags""" 4
+.el .IP \f(CWsv_collxfrm_flags\fR 4
+.IX Xref "sv_collxfrm_flags"
+.IX Item "sv_collxfrm_flags"
+Add Collate Transform magic to an SV if it doesn't already have it.  If the
+flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get-magic.
+.Sp
+Any scalar variable may carry \f(CW\*(C`PERL_MAGIC_collxfrm\*(C'\fR magic that contains the
+scalar data of the variable, but transformed to such a format that a normal
+memory comparison can be used to compare the data according to the locale
+settings.
+.RS 4
+.Sp
+.Vb 2
+\& char *  sv_collxfrm_flags(SV * const sv, STRLEN * const nxp,
+\&                           I32 const flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_copypv""" 4
+.el .IP \f(CWsv_copypv\fR 4
+.IX Item "sv_copypv"
+.PD 0
+.ie n .IP """sv_copypv_flags""" 4
+.el .IP \f(CWsv_copypv_flags\fR 4
+.IX Item "sv_copypv_flags"
+.ie n .IP """sv_copypv_nomg""" 4
+.el .IP \f(CWsv_copypv_nomg\fR 4
+.IX Xref "sv_copypv sv_copypv_flags sv_copypv_nomg"
+.IX Item "sv_copypv_nomg"
+.PD
+These copy a stringified representation of the source SV into the
+destination SV.  They automatically perform coercion of numeric values into
+strings.  Guaranteed to preserve the \f(CW\*(C`UTF8\*(C'\fR flag even from overloaded objects.
+Similar in nature to \f(CW\*(C`sv_2pv[_flags]\*(C'\fR but they operate directly on an SV
+instead of just the string.  Mostly they use "\f(CW\*(C`sv_2pv_flags\*(C'\fR" to
+do the work, except when that would lose the UTF\-8'ness of the PV.
+.Sp
+The three forms differ only in whether or not they perform 'get magic' on
+\&\f(CW\*(C`sv\*(C'\fR.  \f(CW\*(C`sv_copypv_nomg\*(C'\fR skips 'get magic'; \f(CW\*(C`sv_copypv\*(C'\fR performs it; and
+\&\f(CW\*(C`sv_copypv_flags\*(C'\fR either performs it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set in
+\&\f(CW\*(C`flags\*(C'\fR) or doesn't (if that bit is cleared).
+.RS 4
+.Sp
+.Vb 4
+\& void  sv_copypv      (SV * const dsv, SV * const ssv)
+\& void  sv_copypv_flags(SV * const dsv, SV * const ssv,
+\&                       const I32 flags)
+\& void  sv_copypv_nomg (SV * const dsv, SV * const ssv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvCUR""" 4
+.el .IP \f(CWSvCUR\fR 4
+.IX Xref "SvCUR"
+.IX Item "SvCUR"
+Returns the length, in bytes, of the PV inside the SV.
+Note that this may not match Perl's \f(CW\*(C`length\*(C'\fR; for that, use
+\&\f(CWsv_len_utf8(sv)\fR. See \f(CW"SvLEN"\fR also.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  SvCUR(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvCUR_set""" 4
+.el .IP \f(CWSvCUR_set\fR 4
+.IX Xref "SvCUR_set"
+.IX Item "SvCUR_set"
+Sets the current length, in bytes, of the C string which is in the SV.
+See \f(CW"SvCUR"\fR and \f(CW\*(C`SvIV_set\*(C'\fR>.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvCUR_set(SV* sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2cv""" 4
+.el .IP \f(CWsv_2cv\fR 4
+.IX Xref "sv_2cv"
+.IX Item "sv_2cv"
+Using various gambits, try to get a CV from an SV; in addition, try if
+possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and GV associated with it.
+The flags in \f(CW\*(C`lref\*(C'\fR are passed to \f(CW\*(C`gv_fetchsv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& CV *  sv_2cv(SV *sv, HV ** const st, GV ** const gvp,
+\&              const I32 lref)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_dec""" 4
+.el .IP \f(CWsv_dec\fR 4
+.IX Item "sv_dec"
+.PD 0
+.ie n .IP """sv_dec_nomg""" 4
+.el .IP \f(CWsv_dec_nomg\fR 4
+.IX Xref "sv_dec sv_dec_nomg"
+.IX Item "sv_dec_nomg"
+.PD
+These auto-decrement the value in the SV, doing string to numeric conversion
+if necessary.  They both handle operator overloading.
+.Sp
+They differ only in that:
+.Sp
+\&\f(CW\*(C`sv_dec\*(C'\fR handles 'get' magic; \f(CW\*(C`sv_dec_nomg\*(C'\fR skips 'get' magic.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_dec(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_derived_from""" 4
+.el .IP \f(CWsv_derived_from\fR 4
+.IX Xref "sv_derived_from"
+.IX Item "sv_derived_from"
+Exactly like "sv_derived_from_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_derived_from(SV *sv, const char * const name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_derived_from_hv""" 4
+.el .IP \f(CWsv_derived_from_hv\fR 4
+.IX Xref "sv_derived_from_hv"
+.IX Item "sv_derived_from_hv"
+Exactly like "sv_derived_from_pvn", but takes the name string as the
+\&\f(CW\*(C`HvNAME\*(C'\fR of the given HV (which would presumably represent a stash).
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_derived_from_hv(SV *sv, HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_derived_from_pv""" 4
+.el .IP \f(CWsv_derived_from_pv\fR 4
+.IX Xref "sv_derived_from_pv"
+.IX Item "sv_derived_from_pv"
+Exactly like "sv_derived_from_pvn", but takes a nul-terminated string 
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& bool  sv_derived_from_pv(SV *sv, const char * const name,
+\&                          U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_derived_from_pvn""" 4
+.el .IP \f(CWsv_derived_from_pvn\fR 4
+.IX Xref "sv_derived_from_pvn"
+.IX Item "sv_derived_from_pvn"
+Returns a boolean indicating whether the SV is derived from the specified class
+\&\fIat the C level\fR.  To check derivation at the Perl level, call \f(CWisa()\fR as a
+normal Perl method.
+.Sp
+Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is SVf_UTF8.
+.RS 4
+.Sp
+.Vb 2
+\& bool  sv_derived_from_pvn(SV *sv, const char * const name,
+\&                           const STRLEN len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_derived_from_sv""" 4
+.el .IP \f(CWsv_derived_from_sv\fR 4
+.IX Xref "sv_derived_from_sv"
+.IX Item "sv_derived_from_sv"
+Exactly like "sv_derived_from_pvn", but takes the name string in the form
+of an SV instead of a string/length pair. This is the advised form.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_derived_from_sv(SV *sv, SV *namesv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_does""" 4
+.el .IP \f(CWsv_does\fR 4
+.IX Xref "sv_does"
+.IX Item "sv_does"
+Like "sv_does_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_does(SV *sv, const char * const name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_does_pv""" 4
+.el .IP \f(CWsv_does_pv\fR 4
+.IX Xref "sv_does_pv"
+.IX Item "sv_does_pv"
+Like "sv_does_sv", but takes a nul-terminated string instead of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_does_pv(SV *sv, const char * const name, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_does_pvn""" 4
+.el .IP \f(CWsv_does_pvn\fR 4
+.IX Xref "sv_does_pvn"
+.IX Item "sv_does_pvn"
+Like "sv_does_sv", but takes a string/length pair instead of an SV.
+.RS 4
+.Sp
+.Vb 2
+\& bool  sv_does_pvn(SV *sv, const char * const name,
+\&                   const STRLEN len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_does_sv""" 4
+.el .IP \f(CWsv_does_sv\fR 4
+.IX Xref "sv_does_sv"
+.IX Item "sv_does_sv"
+Returns a boolean indicating whether the SV performs a specific, named role.
+The SV can be a Perl object or the name of a Perl class.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_does_sv(SV *sv, SV *namesv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvEND""" 4
+.el .IP \f(CWSvEND\fR 4
+.IX Xref "SvEND"
+.IX Item "SvEND"
+Returns a pointer to the spot just after the last character in
+the string which is in the SV, where there is usually a trailing
+\&\f(CW\*(C`NUL\*(C'\fR character (even though Perl scalars do not strictly require it).
+See \f(CW"SvCUR"\fR.  Access the character as \f(CW\*(C`*(SvEND(sv))\*(C'\fR.
+.Sp
+Warning: If \f(CW\*(C`SvCUR\*(C'\fR is equal to \f(CW\*(C`SvLEN\*(C'\fR, then \f(CW\*(C`SvEND\*(C'\fR points to
+unallocated memory.
+.RS 4
+.Sp
+.Vb 1
+\& char*  SvEND(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_eq""" 4
+.el .IP \f(CWsv_eq\fR 4
+.IX Xref "sv_eq"
+.IX Item "sv_eq"
+Returns a boolean indicating whether the strings in the two SVs are
+identical.  Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will
+coerce its args to strings if necessary.
+.Sp
+This function does not handle operator overloading. For a version that does,
+see instead \f(CW\*(C`sv_streq\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_eq(SV *sv1, SV *sv2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_eq_flags""" 4
+.el .IP \f(CWsv_eq_flags\fR 4
+.IX Xref "sv_eq_flags"
+.IX Item "sv_eq_flags"
+Returns a boolean indicating whether the strings in the two SVs are
+identical.  Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware and coerces its args to strings
+if necessary.  If the flags has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles get-magic, too.
+.Sp
+This function does not handle operator overloading. For a version that does,
+see instead \f(CW\*(C`sv_streq_flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_eq_flags(SV *sv1, SV *sv2, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_force_normal""" 4
+.el .IP \f(CWsv_force_normal\fR 4
+.IX Xref "sv_force_normal"
+.IX Item "sv_force_normal"
+Undo various types of fakery on an SV: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an \f(CW\*(C`xpvmg\*(C'\fR.  See also \f(CW"sv_force_normal_flags"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_force_normal(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_force_normal_flags""" 4
+.el .IP \f(CWsv_force_normal_flags\fR 4
+.IX Xref "sv_force_normal_flags"
+.IX Item "sv_force_normal_flags"
+Undo various types of fakery on an SV, where fakery means
+"more than" a string: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an \f(CW\*(C`xpvmg\*(C'\fR; if we're a copy-on-write scalar, this is the on-write time when
+we do the copy, and is also used locally; if this is a
+vstring, drop the vstring magic.  If \f(CW\*(C`SV_COW_DROP_PV\*(C'\fR is set
+then a copy-on-write scalar drops its PV buffer (if any) and becomes
+\&\f(CW\*(C`SvPOK_off\*(C'\fR rather than making a copy.  (Used where this
+scalar is about to be set to some other value.)  In addition,
+the \f(CW\*(C`flags\*(C'\fR parameter gets passed to \f(CWsv_unref_flags()\fR
+when unreffing.  \f(CW\*(C`sv_force_normal\*(C'\fR calls this function
+with flags set to 0.
+.Sp
+This function is expected to be used to signal to perl that this SV is
+about to be written to, and any extra book-keeping needs to be taken care
+of.  Hence, it croaks on read-only values.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_force_normal_flags(SV * const sv, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_free""" 4
+.el .IP \f(CWsv_free\fR 4
+.IX Xref "sv_free"
+.IX Item "sv_free"
+Decrement an SV's reference count, and if it drops to zero, call
+\&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by
+the body; finally, deallocating the SV's head itself.
+Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_free(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvGAMAGIC""" 4
+.el .IP \f(CWSvGAMAGIC\fR 4
+.IX Xref "SvGAMAGIC"
+.IX Item "SvGAMAGIC"
+Returns true if the SV has get magic or
+overloading.  If either is true then
+the scalar is active data, and has the potential to return a new value every
+time it is accessed.  Hence you must be careful to
+only read it once per user logical operation and work
+with that returned value.  If neither is true then
+the scalar's value cannot change unless written to.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvGAMAGIC(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_get_backrefs""" 4
+.el .IP \f(CWsv_get_backrefs\fR 4
+.IX Xref "sv_get_backrefs"
+.IX Item "sv_get_backrefs"
+NOTE: \f(CW\*(C`sv_get_backrefs\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+If \f(CW\*(C`sv\*(C'\fR is the target of a weak reference then it returns the back
+references structure associated with the sv; otherwise return \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+When returning a non-null result the type of the return is relevant. If it
+is an AV then the elements of the AV are the weak reference RVs which
+point at this item. If it is any other type then the item itself is the
+weak reference.
+.Sp
+See also \f(CWPerl_sv_add_backref()\fR, \f(CWPerl_sv_del_backref()\fR,
+\&\f(CWPerl_sv_kill_backrefs()\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_get_backrefs(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvGETMAGIC""" 4
+.el .IP \f(CWSvGETMAGIC\fR 4
+.IX Xref "SvGETMAGIC"
+.IX Item "SvGETMAGIC"
+Invokes \f(CW"mg_get"\fR on an SV if it has 'get' magic.  For example, this
+will call \f(CW\*(C`FETCH\*(C'\fR on a tied variable.  As of 5.37.1, this function is
+guaranteed to evaluate its argument exactly once.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvGETMAGIC(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_gets""" 4
+.el .IP \f(CWsv_gets\fR 4
+.IX Xref "sv_gets"
+.IX Item "sv_gets"
+Get a line from the filehandle and store it into the SV, optionally
+appending to the currently-stored string.  If \f(CW\*(C`append\*(C'\fR is not 0, the
+line is appended to the SV instead of overwriting it.  \f(CW\*(C`append\*(C'\fR should
+be set to the byte offset that the appended string should start at
+in the SV (typically, \f(CWSvCUR(sv)\fR is a suitable choice).
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_gets(SV * const sv, PerlIO * const fp, I32 append)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvGROW""" 4
+.el .IP \f(CWSvGROW\fR 4
+.IX Xref "SvGROW"
+.IX Item "SvGROW"
+Expands the character buffer in the SV so that it has room for the
+indicated number of bytes (remember to reserve space for an extra trailing
+\&\f(CW\*(C`NUL\*(C'\fR character).  Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary.
+Returns a pointer to the character
+buffer.  SV must be of type >= \f(CW\*(C`SVt_PV\*(C'\fR.  One
+alternative is to call \f(CW\*(C`sv_grow\*(C'\fR if you are not sure of the type of SV.
+.Sp
+You might mistakenly think that \f(CW\*(C`len\*(C'\fR is the number of bytes to add to the
+existing size, but instead it is the total size \f(CW\*(C`sv\*(C'\fR should be.
+.RS 4
+.Sp
+.Vb 1
+\& char *  SvGROW(SV* sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIandPOK""" 4
+.el .IP \f(CWSvIandPOK\fR 4
+.IX Xref "SvIandPOK"
+.IX Item "SvIandPOK"
+Returns a bool indicating whether the SV is both \f(CWSvPOK()\fR and
+\&\f(CWSvIOK()\fR at the same time. Equivalent to \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR but
+more efficient.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvIandPOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIandPOK_off""" 4
+.el .IP \f(CWSvIandPOK_off\fR 4
+.IX Xref "SvIandPOK_off"
+.IX Item "SvIandPOK_off"
+Unsets the PV and IV status of an SV in one operation. Equivalent to
+\&\f(CW\*(C`SvIOK_off(sv); SvPK_off(v);\*(C'\fR but more efficient.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIandPOK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIandPOK_on""" 4
+.el .IP \f(CWSvIandPOK_on\fR 4
+.IX Xref "SvIandPOK_on"
+.IX Item "SvIandPOK_on"
+Tells an SV that is a string and a number in one operation. Equivalent
+to \f(CW\*(C`SvIOK_on(sv); SvPOK_on(sv);\*(C'\fR but more efficient.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIandPOK_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_inc""" 4
+.el .IP \f(CWsv_inc\fR 4
+.IX Item "sv_inc"
+.PD 0
+.ie n .IP """sv_inc_nomg""" 4
+.el .IP \f(CWsv_inc_nomg\fR 4
+.IX Xref "sv_inc sv_inc_nomg"
+.IX Item "sv_inc_nomg"
+.PD
+These auto-increment the value in the SV, doing string to numeric conversion
+if necessary.  They both handle operator overloading.
+.Sp
+They differ only in that \f(CW\*(C`sv_inc\*(C'\fR performs 'get' magic; \f(CW\*(C`sv_inc_nomg\*(C'\fR skips
+any magic.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_inc(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_insert""" 4
+.el .IP \f(CWsv_insert\fR 4
+.IX Xref "sv_insert"
+.IX Item "sv_insert"
+Inserts and/or replaces a string at the specified offset/length within the SV.
+Similar to the Perl \f(CWsubstr()\fR function, with \f(CW\*(C`littlelen\*(C'\fR bytes starting at
+\&\f(CW\*(C`little\*(C'\fR replacing \f(CW\*(C`len\*(C'\fR bytes of the string in \f(CW\*(C`bigstr\*(C'\fR starting at
+\&\f(CW\*(C`offset\*(C'\fR.  Handles get magic.
+.RS 4
+.Sp
+.Vb 3
+\& void  sv_insert(SV * const bigstr, const STRLEN offset,
+\&                 const STRLEN len, const char * const little,
+\&                 const STRLEN littlelen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_insert_flags""" 4
+.el .IP \f(CWsv_insert_flags\fR 4
+.IX Xref "sv_insert_flags"
+.IX Item "sv_insert_flags"
+Same as \f(CW\*(C`sv_insert\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR are passed to the
+\&\f(CW\*(C`SvPV_force_flags\*(C'\fR that applies to \f(CW\*(C`bigstr\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& void  sv_insert_flags(SV * const bigstr, const STRLEN offset,
+\&                       const STRLEN len, const char *little,
+\&                       const STRLEN littlelen, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2io""" 4
+.el .IP \f(CWsv_2io\fR 4
+.IX Xref "sv_2io"
+.IX Item "sv_2io"
+Using various gambits, try to get an IO from an SV: the IO slot if its a
+GV; or the recursive result if we're an RV; or the IO slot of the symbol
+named after the PV if we're a string.
+.Sp
+\&'Get' magic is ignored on the \f(CW\*(C`sv\*(C'\fR passed in, but will be called on
+\&\f(CWSvRV(sv)\fR if \f(CW\*(C`sv\*(C'\fR is an RV.
+.RS 4
+.Sp
+.Vb 1
+\& IO *  sv_2io(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK""" 4
+.el .IP \f(CWSvIOK\fR 4
+.IX Xref "SvIOK"
+.IX Item "SvIOK"
+Returns a U32 value indicating whether the SV contains an integer.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvIOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_notUV""" 4
+.el .IP \f(CWSvIOK_notUV\fR 4
+.IX Xref "SvIOK_notUV"
+.IX Item "SvIOK_notUV"
+Returns a boolean indicating whether the SV contains a signed integer.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvIOK_notUV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_off""" 4
+.el .IP \f(CWSvIOK_off\fR 4
+.IX Xref "SvIOK_off"
+.IX Item "SvIOK_off"
+Unsets the IV status of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIOK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_on""" 4
+.el .IP \f(CWSvIOK_on\fR 4
+.IX Xref "SvIOK_on"
+.IX Item "SvIOK_on"
+Tells an SV that it is an integer.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIOK_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_only""" 4
+.el .IP \f(CWSvIOK_only\fR 4
+.IX Xref "SvIOK_only"
+.IX Item "SvIOK_only"
+Tells an SV that it is an integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIOK_only(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_only_UV""" 4
+.el .IP \f(CWSvIOK_only_UV\fR 4
+.IX Xref "SvIOK_only_UV"
+.IX Item "SvIOK_only_UV"
+Tells an SV that it is an unsigned integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIOK_only_UV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOKp""" 4
+.el .IP \f(CWSvIOKp\fR 4
+.IX Xref "SvIOKp"
+.IX Item "SvIOKp"
+Returns a U32 value indicating whether the SV contains an integer.  Checks
+the \fBprivate\fR setting.  Use \f(CW\*(C`SvIOK\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvIOKp(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIOK_UV""" 4
+.el .IP \f(CWSvIOK_UV\fR 4
+.IX Xref "SvIOK_UV"
+.IX Item "SvIOK_UV"
+Returns a boolean indicating whether the SV contains an integer that must be
+interpreted as unsigned.  A non-negative integer whose value is within the
+range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvIOK_UV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_isa""" 4
+.el .IP \f(CWsv_isa\fR 4
+.IX Xref "sv_isa"
+.IX Item "sv_isa"
+Returns a boolean indicating whether the SV is blessed into the specified
+class.
+.Sp
+This does not check for subtypes or method overloading. Use \f(CW\*(C`sv_isa_sv\*(C'\fR to
+verify an inheritance relationship in the same way as the \f(CW\*(C`isa\*(C'\fR operator by
+respecting any \f(CWisa()\fR method overloading; or \f(CW\*(C`sv_derived_from_sv\*(C'\fR to test
+directly on the actual object type.
+.RS 4
+.Sp
+.Vb 1
+\& int  sv_isa(SV *sv, const char * const name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_isa_sv""" 4
+.el .IP \f(CWsv_isa_sv\fR 4
+.IX Xref "sv_isa_sv"
+.IX Item "sv_isa_sv"
+NOTE: \f(CW\*(C`sv_isa_sv\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Returns a boolean indicating whether the SV is an object reference and is
+derived from the specified class, respecting any \f(CWisa()\fR method overloading
+it may have. Returns false if \f(CW\*(C`sv\*(C'\fR is not a reference to an object, or is
+not derived from the specified class.
+.Sp
+This is the function used to implement the behaviour of the \f(CW\*(C`isa\*(C'\fR operator.
+.Sp
+Does not invoke magic on \f(CW\*(C`sv\*(C'\fR.
+.Sp
+Not to be confused with the older \f(CW\*(C`sv_isa\*(C'\fR function, which does not use an
+overloaded \f(CWisa()\fR method, nor will check subclassing.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_isa_sv(SV *sv, SV *namesv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIsBOOL""" 4
+.el .IP \f(CWSvIsBOOL\fR 4
+.IX Xref "SvIsBOOL"
+.IX Item "SvIsBOOL"
+Returns true if the SV is one of the special boolean constants (PL_sv_yes or
+PL_sv_no), or is a regular SV whose last assignment stored a copy of one.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvIsBOOL(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIsCOW""" 4
+.el .IP \f(CWSvIsCOW\fR 4
+.IX Xref "SvIsCOW"
+.IX Item "SvIsCOW"
+Returns a U32 value indicating whether the SV is Copy-On-Write (either shared
+hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
+COW).
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvIsCOW(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIsCOW_shared_hash""" 4
+.el .IP \f(CWSvIsCOW_shared_hash\fR 4
+.IX Xref "SvIsCOW_shared_hash"
+.IX Item "SvIsCOW_shared_hash"
+Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
+scalar.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvIsCOW_shared_hash(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_isobject""" 4
+.el .IP \f(CWsv_isobject\fR 4
+.IX Xref "sv_isobject"
+.IX Item "sv_isobject"
+Returns a boolean indicating whether the SV is an RV pointing to a blessed
+object.  If the SV is not an RV, or if the object is not blessed, then this
+will return false.
+.RS 4
+.Sp
+.Vb 1
+\& int  sv_isobject(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIV""" 4
+.el .IP \f(CWSvIV\fR 4
+.IX Item "SvIV"
+.PD 0
+.ie n .IP """SvIV_nomg""" 4
+.el .IP \f(CWSvIV_nomg\fR 4
+.IX Item "SvIV_nomg"
+.ie n .IP """SvIVx""" 4
+.el .IP \f(CWSvIVx\fR 4
+.IX Xref "SvIV SvIV_nomg SvIVx"
+.IX Item "SvIVx"
+.PD
+These each coerce the given SV to IV and return it.  The returned value in many
+circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's IV slot, but not in all cases.  (Use
+\&\f(CW"sv_setiv"\fR to make sure it does).
+.Sp
+As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.Sp
+\&\f(CW\*(C`SvIVx\*(C'\fR is now identical to \f(CW\*(C`SvIV\*(C'\fR, but prior to 5.37.1, it was the only form
+guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.Sp
+\&\f(CW\*(C`SvIV_nomg\*(C'\fR is the same as \f(CW\*(C`SvIV\*(C'\fR, but does not perform 'get' magic.
+.RS 4
+.Sp
+.Vb 1
+\& IV  SvIV(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2iv_flags""" 4
+.el .IP \f(CWsv_2iv_flags\fR 4
+.IX Xref "sv_2iv_flags"
+.IX Item "sv_2iv_flags"
+Return the integer value of an SV, doing any necessary string
+conversion.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
+Normally used via the \f(CWSvIV(sv)\fR and \f(CWSvIVx(sv)\fR macros.
+.RS 4
+.Sp
+.Vb 1
+\& IV  sv_2iv_flags(SV * const sv, const I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIV_set""" 4
+.el .IP \f(CWSvIV_set\fR 4
+.IX Xref "SvIV_set"
+.IX Item "SvIV_set"
+Set the value of the IV pointer in sv to val.  It is possible to perform
+the same function of this macro with an lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
+With future Perls, however, it will be more efficient to use
+\&\f(CW\*(C`SvIV_set\*(C'\fR instead of the lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvIV_set(SV* sv, IV val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvIVX""" 4
+.el .IP \f(CWSvIVX\fR 4
+.IX Xref "SvIVX"
+.IX Item "SvIVX"
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true.  See also \f(CW"SvIV"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& IV  SvIVX(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvLEN""" 4
+.el .IP \f(CWSvLEN\fR 4
+.IX Xref "SvLEN"
+.IX Item "SvLEN"
+Returns the size of the string buffer in the SV, not including any part
+attributable to \f(CW\*(C`SvOOK\*(C'\fR.  See \f(CW"SvCUR"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  SvLEN(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_len""" 4
+.el .IP \f(CWsv_len\fR 4
+.IX Xref "sv_len"
+.IX Item "sv_len"
+Returns the length of the string in the SV.  Handles magic and type
+coercion and sets the UTF8 flag appropriately.  See also \f(CW"SvCUR"\fR, which
+gives raw access to the \f(CW\*(C`xpv_cur\*(C'\fR slot.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  sv_len(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvLEN_set""" 4
+.el .IP \f(CWSvLEN_set\fR 4
+.IX Xref "SvLEN_set"
+.IX Item "SvLEN_set"
+Set the size of the string buffer for the SV. See \f(CW"SvLEN"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvLEN_set(SV* sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_len_utf8""" 4
+.el .IP \f(CWsv_len_utf8\fR 4
+.IX Item "sv_len_utf8"
+.PD 0
+.ie n .IP """sv_len_utf8_nomg""" 4
+.el .IP \f(CWsv_len_utf8_nomg\fR 4
+.IX Xref "sv_len_utf8 sv_len_utf8_nomg"
+.IX Item "sv_len_utf8_nomg"
+.PD
+These return the number of characters in the string in an SV, counting wide
+UTF\-8 bytes as a single character.  Both handle type coercion.
+They differ only in that \f(CW\*(C`sv_len_utf8\*(C'\fR performs 'get' magic;
+\&\f(CW\*(C`sv_len_utf8_nomg\*(C'\fR skips any magic.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  sv_len_utf8(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvLOCK""" 4
+.el .IP \f(CWSvLOCK\fR 4
+.IX Xref "SvLOCK"
+.IX Item "SvLOCK"
+Arranges for a mutual exclusion lock to be obtained on \f(CW\*(C`sv\*(C'\fR if a suitable module
+has been loaded.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvLOCK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_magic""" 4
+.el .IP \f(CWsv_magic\fR 4
+.IX Xref "sv_magic"
+.IX Item "sv_magic"
+Adds magic to an SV.  First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if
+necessary, then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the
+magic list.
+.Sp
+See \f(CW"sv_magicext"\fR (which \f(CW\*(C`sv_magic\*(C'\fR now calls) for a description of the
+handling of the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments.
+.Sp
+You need to use \f(CW\*(C`sv_magicext\*(C'\fR to add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs and also
+to add more than one instance of the same \f(CW\*(C`how\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_magic(SV * const sv, SV * const obj, const int how,
+\&                const char * const name, const I32 namlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_magicext""" 4
+.el .IP \f(CWsv_magicext\fR 4
+.IX Xref "sv_magicext"
+.IX Item "sv_magicext"
+Adds magic to an SV, upgrading it if necessary.  Applies the
+supplied \f(CW\*(C`vtable\*(C'\fR and returns a pointer to the magic added.
+.Sp
+Note that \f(CW\*(C`sv_magicext\*(C'\fR will allow things that \f(CW\*(C`sv_magic\*(C'\fR will not.
+In particular, you can add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs, and add more than
+one instance of the same \f(CW\*(C`how\*(C'\fR.
+.Sp
+If \f(CW\*(C`namlen\*(C'\fR is greater than zero then a \f(CW\*(C`savepvn\*(C'\fR \fIcopy\fR of \f(CW\*(C`name\*(C'\fR is
+stored, if \f(CW\*(C`namlen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as-is and \- as another
+special case \- if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed
+to contain an SV* and is stored as-is with its \f(CW\*(C`REFCNT\*(C'\fR incremented.
+.Sp
+(This is now used as a subroutine by \f(CW\*(C`sv_magic\*(C'\fR.)
+.RS 4
+.Sp
+.Vb 3
+\& MAGIC *  sv_magicext(SV * const sv, SV * const obj, const int how,
+\&                      const MGVTBL * const vtbl,
+\&                      const char * const name, const I32 namlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvMAGIC_set""" 4
+.el .IP \f(CWSvMAGIC_set\fR 4
+.IX Xref "SvMAGIC_set"
+.IX Item "SvMAGIC_set"
+Set the value of the MAGIC pointer in \f(CW\*(C`sv\*(C'\fR to val.  See \f(CW"SvIV_set"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvMAGIC_set(SV* sv, MAGIC* val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2mortal""" 4
+.el .IP \f(CWsv_2mortal\fR 4
+.IX Xref "sv_2mortal"
+.IX Item "sv_2mortal"
+Marks an existing SV as mortal.  The SV will be destroyed "soon", either
+by an explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
+statement boundaries.  \f(CWSvTEMP()\fR is turned on which means that the SV's
+string buffer can be "stolen" if this SV is copied.  See also
+\&\f(CW"sv_newmortal"\fR and \f(CW"sv_mortalcopy"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_2mortal(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_mortalcopy""" 4
+.el .IP \f(CWsv_mortalcopy\fR 4
+.IX Xref "sv_mortalcopy"
+.IX Item "sv_mortalcopy"
+Creates a new SV which is a copy of the original SV (using \f(CW\*(C`sv_setsv\*(C'\fR).
+The new SV is marked as mortal.  It will be destroyed "soon", either by an
+explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
+statement boundaries.  See also \f(CW"sv_newmortal"\fR and \f(CW"sv_2mortal"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_mortalcopy(SV * const oldsv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_mortalcopy_flags""" 4
+.el .IP \f(CWsv_mortalcopy_flags\fR 4
+.IX Xref "sv_mortalcopy_flags"
+.IX Item "sv_mortalcopy_flags"
+Like \f(CW\*(C`sv_mortalcopy\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR are passed to the
+\&\f(CW\*(C`sv_setsv_flags\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_mortalcopy_flags(SV * const oldsv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_newmortal""" 4
+.el .IP \f(CWsv_newmortal\fR 4
+.IX Xref "sv_newmortal"
+.IX Item "sv_newmortal"
+Creates a new null SV which is mortal.  The reference count of the SV is
+set to 1.  It will be destroyed "soon", either by an explicit call to
+\&\f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as statement boundaries.
+See also \f(CW"sv_mortalcopy"\fR and \f(CW"sv_2mortal"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_newmortal()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNIOK""" 4
+.el .IP \f(CWSvNIOK\fR 4
+.IX Xref "SvNIOK"
+.IX Item "SvNIOK"
+Returns a U32 value indicating whether the SV contains a number, integer or
+double.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvNIOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNIOK_off""" 4
+.el .IP \f(CWSvNIOK_off\fR 4
+.IX Xref "SvNIOK_off"
+.IX Item "SvNIOK_off"
+Unsets the NV/IV status of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvNIOK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNIOKp""" 4
+.el .IP \f(CWSvNIOKp\fR 4
+.IX Xref "SvNIOKp"
+.IX Item "SvNIOKp"
+Returns a U32 value indicating whether the SV contains a number, integer or
+double.  Checks the \fBprivate\fR setting.  Use \f(CW\*(C`SvNIOK\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvNIOKp(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNOK""" 4
+.el .IP \f(CWSvNOK\fR 4
+.IX Xref "SvNOK"
+.IX Item "SvNOK"
+Returns a U32 value indicating whether the SV contains a double.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvNOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNOK_off""" 4
+.el .IP \f(CWSvNOK_off\fR 4
+.IX Xref "SvNOK_off"
+.IX Item "SvNOK_off"
+Unsets the NV status of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvNOK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNOK_on""" 4
+.el .IP \f(CWSvNOK_on\fR 4
+.IX Xref "SvNOK_on"
+.IX Item "SvNOK_on"
+Tells an SV that it is a double.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvNOK_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNOK_only""" 4
+.el .IP \f(CWSvNOK_only\fR 4
+.IX Xref "SvNOK_only"
+.IX Item "SvNOK_only"
+Tells an SV that it is a double and disables all other OK bits.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvNOK_only(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNOKp""" 4
+.el .IP \f(CWSvNOKp\fR 4
+.IX Xref "SvNOKp"
+.IX Item "SvNOKp"
+Returns a U32 value indicating whether the SV contains a double.  Checks the
+\&\fBprivate\fR setting.  Use \f(CW\*(C`SvNOK\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvNOKp(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_nolocking""" 4
+.el .IP \f(CWsv_nolocking\fR 4
+.IX Xref "sv_nolocking"
+.IX Item "sv_nolocking"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`sv_nolocking\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Dummy routine which "locks" an SV when there is no locking module present.
+Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
+potentially warn under some level of strict-ness.
+.Sp
+"Superseded" by \f(CWsv_nosharing()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_nolocking(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_nounlocking""" 4
+.el .IP \f(CWsv_nounlocking\fR 4
+.IX Xref "sv_nounlocking"
+.IX Item "sv_nounlocking"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`sv_nounlocking\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Dummy routine which "unlocks" an SV when there is no locking module present.
+Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
+potentially warn under some level of strict-ness.
+.Sp
+"Superseded" by \f(CWsv_nosharing()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_nounlocking(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_numeq""" 4
+.el .IP \f(CWsv_numeq\fR 4
+.IX Xref "sv_numeq"
+.IX Item "sv_numeq"
+A convenient shortcut for calling \f(CW\*(C`sv_numeq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR
+flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 == $sv2\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_numeq(SV *sv1, SV *sv2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_numeq_flags""" 4
+.el .IP \f(CWsv_numeq_flags\fR 4
+.IX Xref "sv_numeq_flags"
+.IX Item "sv_numeq_flags"
+Returns a boolean indicating whether the numbers in the two SVs are
+identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles
+get-magic too. Will coerce its args to numbers if necessary. Treats
+\&\f(CW\*(C`NULL\*(C'\fR as undef.
+.Sp
+If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
+\&\f(CW\*(C`==\*(C'\fR overloading will be made. If such overloading does not exist or the
+flag is set, then regular numerical comparison will be used instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_numeq_flags(SV *sv1, SV *sv2, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNV""" 4
+.el .IP \f(CWSvNV\fR 4
+.IX Item "SvNV"
+.PD 0
+.ie n .IP """SvNV_nomg""" 4
+.el .IP \f(CWSvNV_nomg\fR 4
+.IX Item "SvNV_nomg"
+.ie n .IP """SvNVx""" 4
+.el .IP \f(CWSvNVx\fR 4
+.IX Xref "SvNV SvNV_nomg SvNVx"
+.IX Item "SvNVx"
+.PD
+These each coerce the given SV to NV and return it.  The returned value in many
+circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's NV slot, but not in all cases.  (Use
+\&\f(CW"sv_setnv"\fR to make sure it does).
+.Sp
+As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.Sp
+\&\f(CW\*(C`SvNVx\*(C'\fR is now identical to \f(CW\*(C`SvNV\*(C'\fR, but prior to 5.37.1, it was the only form
+guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.Sp
+\&\f(CW\*(C`SvNV_nomg\*(C'\fR is the same as \f(CW\*(C`SvNV\*(C'\fR, but does not perform 'get' magic.
+.RS 4
+.Sp
+.Vb 1
+\& NV  SvNV(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2nv_flags""" 4
+.el .IP \f(CWsv_2nv_flags\fR 4
+.IX Xref "sv_2nv_flags"
+.IX Item "sv_2nv_flags"
+Return the num value of an SV, doing any necessary string or integer
+conversion.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
+Normally used via the \f(CWSvNV(sv)\fR and \f(CWSvNVx(sv)\fR macros.
+.RS 4
+.Sp
+.Vb 1
+\& NV  sv_2nv_flags(SV * const sv, const I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNV_set""" 4
+.el .IP \f(CWSvNV_set\fR 4
+.IX Xref "SvNV_set"
+.IX Item "SvNV_set"
+Set the value of the NV pointer in \f(CW\*(C`sv\*(C'\fR to val.  See \f(CW"SvIV_set"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvNV_set(SV* sv, NV val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvNVX""" 4
+.el .IP \f(CWSvNVX\fR 4
+.IX Xref "SvNVX"
+.IX Item "SvNVX"
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure \f(CW\*(C`SvNOK\*(C'\fR is true.  See also \f(CW"SvNV"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& NV  SvNVX(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvOK""" 4
+.el .IP \f(CWSvOK\fR 4
+.IX Xref "SvOK"
+.IX Item "SvOK"
+Returns a U32 value indicating whether the value is defined.  This is
+only meaningful for scalars.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvOOK""" 4
+.el .IP \f(CWSvOOK\fR 4
+.IX Xref "SvOOK"
+.IX Item "SvOOK"
+Returns a U32 indicating whether the pointer to the string buffer is offset.
+This hack is used internally to speed up removal of characters from the
+beginning of a \f(CW"SvPV"\fR.  When \f(CW\*(C`SvOOK\*(C'\fR is true, then the start of the
+allocated string buffer is actually \f(CWSvOOK_offset()\fR bytes before \f(CW\*(C`SvPVX\*(C'\fR.
+This offset used to be stored in \f(CW\*(C`SvIVX\*(C'\fR, but is now stored within the spare
+part of the buffer.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvOOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvOOK_off""" 4
+.el .IP \f(CWSvOOK_off\fR 4
+.IX Xref "SvOOK_off"
+.IX Item "SvOOK_off"
+Remove any string offset.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvOOK_off(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvOOK_offset""" 4
+.el .IP \f(CWSvOOK_offset\fR 4
+.IX Xref "SvOOK_offset"
+.IX Item "SvOOK_offset"
+Reads into \f(CW\*(C`len\*(C'\fR the offset from \f(CW\*(C`SvPVX\*(C'\fR back to the true start of the
+allocated buffer, which will be non-zero if \f(CW\*(C`sv_chop\*(C'\fR has been used to
+efficiently remove characters from start of the buffer.  Implemented as a
+macro, which takes the address of \f(CW\*(C`len\*(C'\fR, which must be of type \f(CW\*(C`STRLEN\*(C'\fR.
+Evaluates \f(CW\*(C`sv\*(C'\fR more than once.  Sets \f(CW\*(C`len\*(C'\fR to 0 if \f(CWSvOOK(sv)\fR is false.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvOOK_offset(SV*sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOK""" 4
+.el .IP \f(CWSvPOK\fR 4
+.IX Xref "SvPOK"
+.IX Item "SvPOK"
+Returns a U32 value indicating whether the SV contains a character
+string.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvPOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOK_off""" 4
+.el .IP \f(CWSvPOK_off\fR 4
+.IX Xref "SvPOK_off"
+.IX Item "SvPOK_off"
+Unsets the PV status of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPOK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOK_on""" 4
+.el .IP \f(CWSvPOK_on\fR 4
+.IX Xref "SvPOK_on"
+.IX Item "SvPOK_on"
+Tells an SV that it is a string.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPOK_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOK_only""" 4
+.el .IP \f(CWSvPOK_only\fR 4
+.IX Xref "SvPOK_only"
+.IX Item "SvPOK_only"
+Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits.
+Will also turn off the UTF\-8 status.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPOK_only(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOK_only_UTF8""" 4
+.el .IP \f(CWSvPOK_only_UTF8\fR 4
+.IX Xref "SvPOK_only_UTF8"
+.IX Item "SvPOK_only_UTF8"
+Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits,
+and leaves the UTF\-8 status as it was.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPOK_only_UTF8(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPOKp""" 4
+.el .IP \f(CWSvPOKp\fR 4
+.IX Xref "SvPOKp"
+.IX Item "SvPOKp"
+Returns a U32 value indicating whether the SV contains a character string.
+Checks the \fBprivate\fR setting.  Use \f(CW\*(C`SvPOK\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvPOKp(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pos_b2u""" 4
+.el .IP \f(CWsv_pos_b2u\fR 4
+.IX Xref "sv_pos_b2u"
+.IX Item "sv_pos_b2u"
+Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of bytes from the
+start of the string, to a count of the equivalent number of UTF\-8 chars.
+Handles magic and type coercion.
+.Sp
+Use \f(CW\*(C`sv_pos_b2u_flags\*(C'\fR in preference, which correctly handles strings
+longer than 2Gb.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_pos_b2u(SV * const sv, I32 * const offsetp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pos_b2u_flags""" 4
+.el .IP \f(CWsv_pos_b2u_flags\fR 4
+.IX Xref "sv_pos_b2u_flags"
+.IX Item "sv_pos_b2u_flags"
+Converts \f(CW\*(C`offset\*(C'\fR from a count of bytes from the start of the string, to
+a count of the equivalent number of UTF\-8 chars.  Handles type coercion.
+\&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be
+\&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic.
+.RS 4
+.Sp
+.Vb 2
+\& STRLEN  sv_pos_b2u_flags(SV * const sv, STRLEN const offset,
+\&                          U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pos_u2b""" 4
+.el .IP \f(CWsv_pos_u2b\fR 4
+.IX Xref "sv_pos_u2b"
+.IX Item "sv_pos_u2b"
+Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of UTF\-8 chars from
+the start of the string, to a count of the equivalent number of bytes; if
+\&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from
+the offset, rather than from the start of the string.  Handles magic and
+type coercion.
+.Sp
+Use \f(CW\*(C`sv_pos_u2b_flags\*(C'\fR in preference, which correctly handles strings longer
+than 2Gb.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_pos_u2b(SV * const sv, I32 * const offsetp,
+\&                  I32 * const lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pos_u2b_flags""" 4
+.el .IP \f(CWsv_pos_u2b_flags\fR 4
+.IX Xref "sv_pos_u2b_flags"
+.IX Item "sv_pos_u2b_flags"
+Converts the offset from a count of UTF\-8 chars from
+the start of the string, to a count of the equivalent number of bytes; if
+\&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from
+\&\f(CW\*(C`offset\*(C'\fR, rather than from the start
+of the string.  Handles type coercion.
+\&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be
+\&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic.
+.RS 4
+.Sp
+.Vb 2
+\& STRLEN  sv_pos_u2b_flags(SV * const sv, STRLEN uoffset,
+\&                          STRLEN * const lenp, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV""" 4
+.el .IP \f(CWSvPV\fR 4
+.IX Item "SvPV"
+.PD 0
+.ie n .IP """SvPV_const""" 4
+.el .IP \f(CWSvPV_const\fR 4
+.IX Item "SvPV_const"
+.ie n .IP """SvPV_flags""" 4
+.el .IP \f(CWSvPV_flags\fR 4
+.IX Item "SvPV_flags"
+.ie n .IP """SvPV_flags_const""" 4
+.el .IP \f(CWSvPV_flags_const\fR 4
+.IX Item "SvPV_flags_const"
+.ie n .IP """SvPV_flags_mutable""" 4
+.el .IP \f(CWSvPV_flags_mutable\fR 4
+.IX Item "SvPV_flags_mutable"
+.ie n .IP """SvPV_mutable""" 4
+.el .IP \f(CWSvPV_mutable\fR 4
+.IX Item "SvPV_mutable"
+.ie n .IP """SvPV_nolen""" 4
+.el .IP \f(CWSvPV_nolen\fR 4
+.IX Item "SvPV_nolen"
+.ie n .IP """SvPV_nolen_const""" 4
+.el .IP \f(CWSvPV_nolen_const\fR 4
+.IX Item "SvPV_nolen_const"
+.ie n .IP """SvPV_nomg""" 4
+.el .IP \f(CWSvPV_nomg\fR 4
+.IX Item "SvPV_nomg"
+.ie n .IP """SvPV_nomg_const""" 4
+.el .IP \f(CWSvPV_nomg_const\fR 4
+.IX Item "SvPV_nomg_const"
+.ie n .IP """SvPV_nomg_const_nolen""" 4
+.el .IP \f(CWSvPV_nomg_const_nolen\fR 4
+.IX Item "SvPV_nomg_const_nolen"
+.ie n .IP """SvPV_nomg_nolen""" 4
+.el .IP \f(CWSvPV_nomg_nolen\fR 4
+.IX Item "SvPV_nomg_nolen"
+.ie n .IP """SvPVbyte""" 4
+.el .IP \f(CWSvPVbyte\fR 4
+.IX Item "SvPVbyte"
+.ie n .IP """SvPVbyte_nolen""" 4
+.el .IP \f(CWSvPVbyte_nolen\fR 4
+.IX Item "SvPVbyte_nolen"
+.ie n .IP """SvPVbyte_nomg""" 4
+.el .IP \f(CWSvPVbyte_nomg\fR 4
+.IX Item "SvPVbyte_nomg"
+.ie n .IP """SvPVbyte_or_null""" 4
+.el .IP \f(CWSvPVbyte_or_null\fR 4
+.IX Item "SvPVbyte_or_null"
+.ie n .IP """SvPVbyte_or_null_nomg""" 4
+.el .IP \f(CWSvPVbyte_or_null_nomg\fR 4
+.IX Item "SvPVbyte_or_null_nomg"
+.ie n .IP """SvPVbytex""" 4
+.el .IP \f(CWSvPVbytex\fR 4
+.IX Item "SvPVbytex"
+.ie n .IP """SvPVbytex_nolen""" 4
+.el .IP \f(CWSvPVbytex_nolen\fR 4
+.IX Item "SvPVbytex_nolen"
+.ie n .IP """SvPVutf8""" 4
+.el .IP \f(CWSvPVutf8\fR 4
+.IX Item "SvPVutf8"
+.ie n .IP """SvPVutf8_nolen""" 4
+.el .IP \f(CWSvPVutf8_nolen\fR 4
+.IX Item "SvPVutf8_nolen"
+.ie n .IP """SvPVutf8_nomg""" 4
+.el .IP \f(CWSvPVutf8_nomg\fR 4
+.IX Item "SvPVutf8_nomg"
+.ie n .IP """SvPVutf8_or_null""" 4
+.el .IP \f(CWSvPVutf8_or_null\fR 4
+.IX Item "SvPVutf8_or_null"
+.ie n .IP """SvPVutf8_or_null_nomg""" 4
+.el .IP \f(CWSvPVutf8_or_null_nomg\fR 4
+.IX Item "SvPVutf8_or_null_nomg"
+.ie n .IP """SvPVutf8x""" 4
+.el .IP \f(CWSvPVutf8x\fR 4
+.IX Item "SvPVutf8x"
+.ie n .IP """SvPVx""" 4
+.el .IP \f(CWSvPVx\fR 4
+.IX Item "SvPVx"
+.ie n .IP """SvPVx_const""" 4
+.el .IP \f(CWSvPVx_const\fR 4
+.IX Item "SvPVx_const"
+.ie n .IP """SvPVx_nolen""" 4
+.el .IP \f(CWSvPVx_nolen\fR 4
+.IX Item "SvPVx_nolen"
+.ie n .IP """SvPVx_nolen_const""" 4
+.el .IP \f(CWSvPVx_nolen_const\fR 4
+.IX Xref "SvPV SvPV_const SvPV_flags SvPV_flags_const SvPV_flags_mutable SvPV_mutable SvPV_nolen SvPV_nolen_const SvPV_nomg SvPV_nomg_const SvPV_nomg_const_nolen SvPV_nomg_nolen SvPVbyte SvPVbyte_nolen SvPVbyte_nomg SvPVbyte_or_null SvPVbyte_or_null_nomg SvPVbytex SvPVbytex_nolen SvPVutf8 SvPVutf8_nolen SvPVutf8_nomg SvPVutf8_or_null SvPVutf8_or_null_nomg SvPVutf8x SvPVx SvPVx_const SvPVx_nolen SvPVx_nolen_const"
+.IX Item "SvPVx_nolen_const"
+.PD
+These each return a pointer to the string in \f(CW\*(C`sv\*(C'\fR, or a stringified form of
+\&\f(CW\*(C`sv\*(C'\fR if it does not contain a string.  The SV may cache the stringified
+version becoming \f(CW\*(C`SvPOK\*(C'\fR.
+.Sp
+This is a very basic and common operation, so there are lots of slightly
+different versions of it.
+.Sp
+Note that there is no guarantee that the return value of \f(CWSvPV(sv)\fR, for
+example, is equal to \f(CWSvPVX(sv)\fR, or that \f(CWSvPVX(sv)\fR contains valid data, or
+that successive calls to \f(CWSvPV(sv)\fR (or another of these forms) will return
+the same pointer value each time.  This is due to the way that things like
+overloading and Copy-On-Write are handled.  In these cases, the return value
+may point to a temporary buffer or similar.  If you absolutely need the
+\&\f(CW\*(C`SvPVX\*(C'\fR field to be valid (for example, if you intend to write to it), then
+see \f(CW"SvPV_force"\fR.
+.Sp
+The differences between the forms are:
+.Sp
+The forms with neither \f(CW\*(C`byte\*(C'\fR nor \f(CW\*(C`utf8\*(C'\fR in their names (e.g., \f(CW\*(C`SvPV\*(C'\fR or
+\&\f(CW\*(C`SvPV_nolen\*(C'\fR) can expose the SV's internal string buffer. If
+that buffer consists entirely of bytes 0\-255 and includes any bytes above
+127, then you \fBMUST\fR consult \f(CW\*(C`SvUTF8\*(C'\fR to determine the actual code points
+the string is meant to contain. Generally speaking, it is probably safer to
+prefer \f(CW\*(C`SvPVbyte\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR, and the like. See
+"How do I pass a Perl string to a C library?" in perlguts for more details.
+.Sp
+The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
+to specify to process 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
+\&'get' magic (by clearing it).  The other forms process 'get' magic, except for
+the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic.
+.Sp
+The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
+length of the resultant string (these are macros, so don't use \f(CW&len\fR).
+.Sp
+The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR
+parameter.  They should be used only when it is known that the PV is a C
+string, terminated by a NUL byte, and without intermediate NUL characters; or
+when you don't care about its length.
+.Sp
+The forms with \f(CW\*(C`const\*(C'\fR in their names return \f(CW\*(C`const\ char\ *\*(C'\fR so that the
+compiler will hopefully complain if you were to try to modify the contents of
+the string (unless you cast away const yourself).
+.Sp
+The other forms return a mutable pointer so that the string is modifiable by
+the caller; this is emphasized for the ones with \f(CW\*(C`mutable\*(C'\fR in their names.
+.Sp
+As of 5.38, all forms are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR exactly once.  For
+earlier Perls, use a form whose name ends with \f(CW\*(C`x\*(C'\fR for single evaluation.
+.Sp
+\&\f(CW\*(C`SvPVutf8\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if not already
+UTF\-8.  Similarly, the other forms with \f(CW\*(C`utf8\*(C'\fR in their names correspond to
+their respective forms without.
+.Sp
+\&\f(CW\*(C`SvPVutf8_or_null\*(C'\fR and \f(CW\*(C`SvPVutf8_or_null_nomg\*(C'\fR don't have corresponding
+non\-\f(CW\*(C`utf8\*(C'\fR forms.  Instead they are like \f(CW\*(C`SvPVutf8_nomg\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is
+undef, they return \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+\&\f(CW\*(C`SvPVbyte\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte representation first if
+currently encoded as UTF\-8.  If \f(CW\*(C`sv\*(C'\fR cannot be downgraded from UTF\-8, it
+croaks.  Similarly, the other forms with \f(CW\*(C`byte\*(C'\fR in their names correspond to
+their respective forms without.
+.Sp
+\&\f(CW\*(C`SvPVbyte_or_null\*(C'\fR doesn't have a corresponding non\-\f(CW\*(C`byte\*(C'\fR form.  Instead it
+is like \f(CW\*(C`SvPVbyte\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is undef, it returns \f(CW\*(C`NULL\*(C'\fR.
+.RS 4
+.Sp
+.Vb 10
+\& char*        SvPV                 (SV* sv, STRLEN len)
+\& const char*  SvPV_const           (SV* sv, STRLEN len)
+\& char*        SvPV_flags           (SV* sv, STRLEN len, U32 flags)
+\& const char*  SvPV_flags_const     (SV* sv, STRLEN len, U32 flags)
+\& char*        SvPV_flags_mutable   (SV* sv, STRLEN len, U32 flags)
+\& char*        SvPV_mutable         (SV* sv, STRLEN len)
+\& char*        SvPV_nolen           (SV* sv)
+\& const char*  SvPV_nolen_const     (SV* sv)
+\& char*        SvPV_nomg            (SV* sv, STRLEN len)
+\& const char*  SvPV_nomg_const      (SV* sv, STRLEN len)
+\& const char*  SvPV_nomg_const_nolen(SV* sv)
+\& char*        SvPV_nomg_nolen      (SV* sv)
+\& char*        SvPVbyte             (SV* sv, STRLEN len)
+\& char*        SvPVbyte_nolen       (SV* sv)
+\& char*        SvPVbyte_nomg        (SV* sv, STRLEN len)
+\& char*        SvPVbyte_or_null     (SV* sv, STRLEN len)
+\& char*        SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
+\& char*        SvPVbytex            (SV* sv, STRLEN len)
+\& char*        SvPVbytex_nolen      (SV* sv)
+\& char*        SvPVutf8             (SV* sv, STRLEN len)
+\& char*        SvPVutf8_nolen       (SV* sv)
+\& char*        SvPVutf8_nomg        (SV* sv, STRLEN len)
+\& char*        SvPVutf8_or_null     (SV* sv, STRLEN len)
+\& char*        SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
+\& char*        SvPVutf8x            (SV* sv, STRLEN len)
+\& char*        SvPVx                (SV* sv, STRLEN len)
+\& const char*  SvPVx_const          (SV* sv, STRLEN len)
+\& char*        SvPVx_nolen          (SV* sv)
+\& const char*  SvPVx_nolen_const    (SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pv""" 4
+.el .IP \f(CWsv_2pv\fR 4
+.IX Item "sv_2pv"
+.PD 0
+.ie n .IP """sv_2pv_flags""" 4
+.el .IP \f(CWsv_2pv_flags\fR 4
+.IX Xref "sv_2pv sv_2pv_flags"
+.IX Item "sv_2pv_flags"
+.PD
+These implement the various forms of the "\f(CW\*(C`SvPV\*(C'\fR" in perlapi macros.
+The macros are the preferred interface.
+.Sp
+These return a pointer to the string value of an SV (coercing it to a string if
+necessary), and set \f(CW*lp\fR to its length in bytes.
+.Sp
+The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and
+\&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
+\&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& char *  sv_2pv      (SV *sv, STRLEN *lp)
+\& char *  sv_2pv_flags(SV * const sv, STRLEN * const lp,
+\&                      const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pvbyte""" 4
+.el .IP \f(CWsv_2pvbyte\fR 4
+.IX Item "sv_2pvbyte"
+.PD 0
+.ie n .IP """sv_2pvbyte_flags""" 4
+.el .IP \f(CWsv_2pvbyte_flags\fR 4
+.IX Xref "sv_2pvbyte sv_2pvbyte_flags"
+.IX Item "sv_2pvbyte_flags"
+.PD
+These implement the various forms of the "\f(CW\*(C`SvPVbyte\*(C'\fR" in perlapi macros.
+The macros are the preferred interface.
+.Sp
+These return a pointer to the byte-encoded representation of the SV, and set
+\&\f(CW*lp\fR to its length.  If the SV is marked as being encoded as UTF\-8, it will
+be downgraded, if possible, to a byte string.  If the SV cannot be downgraded,
+they croak.
+.Sp
+The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and
+\&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
+\&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& char *  sv_2pvbyte      (SV *sv, STRLEN * const lp)
+\& char *  sv_2pvbyte_flags(SV *sv, STRLEN * const lp,
+\&                          const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPVCLEAR""" 4
+.el .IP \f(CWSvPVCLEAR\fR 4
+.IX Xref "SvPVCLEAR"
+.IX Item "SvPVCLEAR"
+Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
+properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
+.RS 4
+.Sp
+.Vb 1
+\& char *  SvPVCLEAR(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPVCLEAR_FRESH""" 4
+.el .IP \f(CWSvPVCLEAR_FRESH\fR 4
+.IX Xref "SvPVCLEAR_FRESH"
+.IX Item "SvPVCLEAR_FRESH"
+Like SvPVCLEAR, but optimized for newly-minted SVt_PV/PVIV/PVNV/PVMG
+that already have a PV buffer allocated, but no SvTHINKFIRST.
+.RS 4
+.Sp
+.Vb 1
+\& char *  SvPVCLEAR_FRESH(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV_force""" 4
+.el .IP \f(CWSvPV_force\fR 4
+.IX Item "SvPV_force"
+.PD 0
+.ie n .IP """SvPV_force_flags""" 4
+.el .IP \f(CWSvPV_force_flags\fR 4
+.IX Item "SvPV_force_flags"
+.ie n .IP """SvPV_force_flags_mutable""" 4
+.el .IP \f(CWSvPV_force_flags_mutable\fR 4
+.IX Item "SvPV_force_flags_mutable"
+.ie n .IP """SvPV_force_flags_nolen""" 4
+.el .IP \f(CWSvPV_force_flags_nolen\fR 4
+.IX Item "SvPV_force_flags_nolen"
+.ie n .IP """SvPV_force_mutable""" 4
+.el .IP \f(CWSvPV_force_mutable\fR 4
+.IX Item "SvPV_force_mutable"
+.ie n .IP """SvPV_force_nolen""" 4
+.el .IP \f(CWSvPV_force_nolen\fR 4
+.IX Item "SvPV_force_nolen"
+.ie n .IP """SvPV_force_nomg""" 4
+.el .IP \f(CWSvPV_force_nomg\fR 4
+.IX Item "SvPV_force_nomg"
+.ie n .IP """SvPV_force_nomg_nolen""" 4
+.el .IP \f(CWSvPV_force_nomg_nolen\fR 4
+.IX Item "SvPV_force_nomg_nolen"
+.ie n .IP """SvPVbyte_force""" 4
+.el .IP \f(CWSvPVbyte_force\fR 4
+.IX Item "SvPVbyte_force"
+.ie n .IP """SvPVbytex_force""" 4
+.el .IP \f(CWSvPVbytex_force\fR 4
+.IX Item "SvPVbytex_force"
+.ie n .IP """SvPVutf8_force""" 4
+.el .IP \f(CWSvPVutf8_force\fR 4
+.IX Item "SvPVutf8_force"
+.ie n .IP """SvPVutf8x_force""" 4
+.el .IP \f(CWSvPVutf8x_force\fR 4
+.IX Item "SvPVutf8x_force"
+.ie n .IP """SvPVx_force""" 4
+.el .IP \f(CWSvPVx_force\fR 4
+.IX Xref "SvPV_force SvPV_force_flags SvPV_force_flags_mutable SvPV_force_flags_nolen SvPV_force_mutable SvPV_force_nolen SvPV_force_nomg SvPV_force_nomg_nolen SvPVbyte_force SvPVbytex_force SvPVutf8_force SvPVutf8x_force SvPVx_force"
+.IX Item "SvPVx_force"
+.PD
+These are like \f(CW"SvPV"\fR, returning the string in the SV, but will force the
+SV into containing a string (\f(CW"SvPOK"\fR), and only a string
+(\f(CW"SvPOK_only"\fR), by hook or by crook.  You need to use one of these
+\&\f(CW\*(C`force\*(C'\fR routines if you are going to update the \f(CW"SvPVX"\fR directly.
+.Sp
+Note that coercing an arbitrary scalar into a plain PV will potentially
+strip useful data from it.  For example if the SV was \f(CW\*(C`SvROK\*(C'\fR, then the
+referent will have its reference count decremented, and the SV itself may
+be converted to an \f(CW\*(C`SvPOK\*(C'\fR scalar with a string buffer containing a value
+such as \f(CW"ARRAY(0x1234)"\fR.
+.Sp
+The differences between the forms are:
+.Sp
+The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
+to specify to perform 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
+\&'get' magic (by clearing it).  The other forms do perform 'get' magic, except
+for the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic.
+.Sp
+The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
+length of the resultant string (these are macros, so don't use \f(CW&len\fR).
+.Sp
+The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR
+parameter.  They should be used only when it is known that the PV is a C
+string, terminated by a NUL byte, and without intermediate NUL characters; or
+when you don't care about its length.
+.Sp
+The forms with \f(CW\*(C`mutable\*(C'\fR in their names are effectively the same as those without,
+but the name emphasizes that the string is modifiable by the caller, which it is
+in all the forms.
+.Sp
+\&\f(CW\*(C`SvPVutf8_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if
+not already UTF\-8.
+.Sp
+\&\f(CW\*(C`SvPVutf8x_force\*(C'\fR is like \f(CW\*(C`SvPVutf8_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR
+only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR otherwise.
+.Sp
+\&\f(CW\*(C`SvPVbyte_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte
+representation first if currently encoded as UTF\-8.  If the SV cannot be
+downgraded from UTF\-8, this croaks.
+.Sp
+\&\f(CW\*(C`SvPVbytex_force\*(C'\fR is like \f(CW\*(C`SvPVbyte_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR
+only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR otherwise.
+.RS 4
+.Sp
+.Vb 10
+\& char*  SvPV_force              (SV* sv, STRLEN len)
+\& char*  SvPV_force_flags        (SV * sv, STRLEN len, U32 flags)
+\& char*  SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
+\& char*  SvPV_force_flags_nolen  (SV * sv, U32 flags)
+\& char*  SvPV_force_mutable      (SV * sv, STRLEN len)
+\& char*  SvPV_force_nolen        (SV* sv)
+\& char*  SvPV_force_nomg         (SV* sv, STRLEN len)
+\& char*  SvPV_force_nomg_nolen   (SV * sv)
+\& char*  SvPVbyte_force          (SV * sv, STRLEN len)
+\& char*  SvPVbytex_force         (SV * sv, STRLEN len)
+\& char*  SvPVutf8_force          (SV * sv, STRLEN len)
+\& char*  SvPVutf8x_force         (SV * sv, STRLEN len)
+\& char*  SvPVx_force             (SV* sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV_free""" 4
+.el .IP \f(CWSvPV_free\fR 4
+.IX Xref "SvPV_free"
+.IX Item "SvPV_free"
+Frees the PV buffer in \f(CW\*(C`sv\*(C'\fR, leaving things in a precarious state, so should
+only be used as part of a larger operation
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPV_free(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvn_force_flags""" 4
+.el .IP \f(CWsv_pvn_force_flags\fR 4
+.IX Xref "sv_pvn_force_flags"
+.IX Item "sv_pvn_force_flags"
+Get a sensible string out of the SV somehow.
+If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW"mg_get"\fR on \f(CW\*(C`sv\*(C'\fR if
+appropriate, else not.  \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are
+implemented in terms of this function.
+You normally want to use the various wrapper macros instead: see
+\&\f(CW"SvPV_force"\fR and \f(CW"SvPV_force_nomg"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& char *  sv_pvn_force_flags(SV * const sv, STRLEN * const lp,
+\&                            const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV_renew""" 4
+.el .IP \f(CWSvPV_renew\fR 4
+.IX Xref "SvPV_renew"
+.IX Item "SvPV_renew"
+Low level micro optimization of \f(CW"SvGROW"\fR.  It is generally better to use
+\&\f(CW\*(C`SvGROW\*(C'\fR instead.  This is because \f(CW\*(C`SvPV_renew\*(C'\fR ignores potential issues that
+\&\f(CW\*(C`SvGROW\*(C'\fR handles.  \f(CW\*(C`sv\*(C'\fR needs to have a real \f(CW\*(C`PV\*(C'\fR that is unencumbered by
+things like COW.  Using \f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR or
+\&\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR before calling this should clean it up, but
+why not just use \f(CW\*(C`SvGROW\*(C'\fR if you're not sure about the provenance?
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPV_renew(SV* sv, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV_set""" 4
+.el .IP \f(CWSvPV_set\fR 4
+.IX Xref "SvPV_set"
+.IX Item "SvPV_set"
+This is probably not what you want to use, you probably wanted
+"sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
+.Sp
+Set the value of the PV pointer in \f(CW\*(C`sv\*(C'\fR to the Perl allocated
+\&\f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`val\*(C'\fR.  See also \f(CW"SvIV_set"\fR.
+.Sp
+Remember to free the previous PV buffer. There are many things to check.
+Beware that the existing pointer may be involved in copy-on-write or other
+mischief, so do \f(CWSvOOK_off(sv)\fR and use \f(CW\*(C`sv_force_normal\*(C'\fR or
+\&\f(CW\*(C`SvPV_force\*(C'\fR (or check the \f(CW\*(C`SvIsCOW\*(C'\fR flag) first to make sure this
+modification is safe. Then finally, if it is not a COW, call
+\&\f(CW"SvPV_free"\fR to free the previous PV buffer.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPV_set(SV* sv, char* val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPV_shrink_to_cur""" 4
+.el .IP \f(CWSvPV_shrink_to_cur\fR 4
+.IX Xref "SvPV_shrink_to_cur"
+.IX Item "SvPV_shrink_to_cur"
+Trim any trailing unused memory in the PV of \f(CW\*(C`sv\*(C'\fR, which needs to have a real
+\&\f(CW\*(C`PV\*(C'\fR that is unencumbered by things like COW.  Think first before using this
+functionality.  Is the space saving really worth giving up COW?  Will the
+needed size of \f(CW\*(C`sv\*(C'\fR stay the same?
+.Sp
+If the answers are both yes, then use "\f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR" or
+"\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" before calling this.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvPV_shrink_to_cur(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pvutf8""" 4
+.el .IP \f(CWsv_2pvutf8\fR 4
+.IX Item "sv_2pvutf8"
+.PD 0
+.ie n .IP """sv_2pvutf8_flags""" 4
+.el .IP \f(CWsv_2pvutf8_flags\fR 4
+.IX Xref "sv_2pvutf8 sv_2pvutf8_flags"
+.IX Item "sv_2pvutf8_flags"
+.PD
+These implement the various forms of the "\f(CW\*(C`SvPVutf8\*(C'\fR" in perlapi macros.
+The macros are the preferred interface.
+.Sp
+These return a pointer to the UTF\-8\-encoded representation of the SV, and set
+\&\f(CW*lp\fR to its length in bytes.  They may cause the SV to be upgraded to UTF\-8
+as a side-effect.
+.Sp
+The forms differ in that plain \f(CW\*(C`sv_2pvutf8\*(C'\fR always processes 'get' magic; and
+\&\f(CW\*(C`sv_2pvutf8_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
+\&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
+.RS 4
+.Sp
+.Vb 3
+\& char *  sv_2pvutf8      (SV *sv, STRLEN * const lp)
+\& char *  sv_2pvutf8_flags(SV *sv, STRLEN * const lp,
+\&                          const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPVX""" 4
+.el .IP \f(CWSvPVX\fR 4
+.IX Item "SvPVX"
+.PD 0
+.ie n .IP """SvPVX_const""" 4
+.el .IP \f(CWSvPVX_const\fR 4
+.IX Item "SvPVX_const"
+.ie n .IP """SvPVX_mutable""" 4
+.el .IP \f(CWSvPVX_mutable\fR 4
+.IX Item "SvPVX_mutable"
+.ie n .IP """SvPVXx""" 4
+.el .IP \f(CWSvPVXx\fR 4
+.IX Xref "SvPVX SvPVX_const SvPVX_mutable SvPVXx"
+.IX Item "SvPVXx"
+.PD
+These return a pointer to the physical string in the SV.  The SV must contain a
+string.  Prior to 5.9.3 it is not safe to execute these unless the SV's
+type >= \f(CW\*(C`SVt_PV\*(C'\fR.
+.Sp
+These are also used to store the name of an autoloaded subroutine in an XS
+AUTOLOAD routine.  See "Autoloading with XSUBs" in perlguts.
+.Sp
+\&\f(CW\*(C`SvPVXx\*(C'\fR is identical to \f(CW\*(C`SvPVX\*(C'\fR.
+.Sp
+\&\f(CW\*(C`SvPVX_mutable\*(C'\fR is merely a synonym for \f(CW\*(C`SvPVX\*(C'\fR, but its name emphasizes that
+the string is modifiable by the caller.
+.Sp
+\&\f(CW\*(C`SvPVX_const\*(C'\fR differs in that the return value has been cast so that the
+compiler will complain if you were to try to modify the contents of the string,
+(unless you cast away const yourself).
+.RS 4
+.Sp
+.Vb 4
+\& char*        SvPVX        (SV* sv)
+\& const char*  SvPVX_const  (SV* sv)
+\& char*        SvPVX_mutable(SV* sv)
+\& char*        SvPVXx       (SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvPVXtrue""" 4
+.el .IP \f(CWSvPVXtrue\fR 4
+.IX Xref "SvPVXtrue"
+.IX Item "SvPVXtrue"
+Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR contains a PV that is considered
+TRUE.  FALSE is returned if \f(CW\*(C`sv\*(C'\fR doesn't contain a PV, or if the PV it does
+contain is zero length, or consists of just the single character '0'.  Every
+other PV value is considered TRUE.
+.Sp
+As of Perl v5.37.1, \f(CW\*(C`sv\*(C'\fR is evaluated exactly once; in earlier releases, it
+could be evaluated more than once.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvPVXtrue(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREADONLY""" 4
+.el .IP \f(CWSvREADONLY\fR 4
+.IX Xref "SvREADONLY"
+.IX Item "SvREADONLY"
+Returns true if the argument is readonly, otherwise returns false.
+Exposed to perl code via \fBInternals::SvREADONLY()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvREADONLY(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREADONLY_off""" 4
+.el .IP \f(CWSvREADONLY_off\fR 4
+.IX Xref "SvREADONLY_off"
+.IX Item "SvREADONLY_off"
+Mark an object as not-readonly. Exactly what this mean depends on the
+object type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvREADONLY_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREADONLY_on""" 4
+.el .IP \f(CWSvREADONLY_on\fR 4
+.IX Xref "SvREADONLY_on"
+.IX Item "SvREADONLY_on"
+Mark an object as readonly. Exactly what this means depends on the object
+type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvREADONLY_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_ref""" 4
+.el .IP \f(CWsv_ref\fR 4
+.IX Xref "sv_ref"
+.IX Item "sv_ref"
+Returns a SV describing what the SV passed in is a reference to.
+.Sp
+dst can be a SV to be set to the description or NULL, in which case a
+mortal SV is returned.
+.Sp
+If ob is true and the SV is blessed, the description is the class
+name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_ref(SV *dst, const SV * const sv, const int ob)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREFCNT""" 4
+.el .IP \f(CWSvREFCNT\fR 4
+.IX Xref "SvREFCNT"
+.IX Item "SvREFCNT"
+Returns the value of the object's reference count. Exposed
+to perl code via \fBInternals::SvREFCNT()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvREFCNT(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREFCNT_dec""" 4
+.el .IP \f(CWSvREFCNT_dec\fR 4
+.IX Item "SvREFCNT_dec"
+.PD 0
+.ie n .IP """SvREFCNT_dec_set_NULL""" 4
+.el .IP \f(CWSvREFCNT_dec_set_NULL\fR 4
+.IX Item "SvREFCNT_dec_set_NULL"
+.ie n .IP """SvREFCNT_dec_ret_NULL""" 4
+.el .IP \f(CWSvREFCNT_dec_ret_NULL\fR 4
+.IX Item "SvREFCNT_dec_ret_NULL"
+.ie n .IP """SvREFCNT_dec_NN""" 4
+.el .IP \f(CWSvREFCNT_dec_NN\fR 4
+.IX Xref "SvREFCNT_dec SvREFCNT_dec_set_NULL SvREFCNT_dec_ret_NULL SvREFCNT_dec_NN"
+.IX Item "SvREFCNT_dec_NN"
+.PD
+These decrement the reference count of the given SV.
+.Sp
+\&\f(CW\*(C`SvREFCNT_dec_NN\*(C'\fR may only be used when \f(CW\*(C`sv\*(C'\fR is known to not be \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+The function \f(CWSvREFCNT_dec_ret_NULL()\fR is identical to the
+\&\f(CWSvREFCNT_dec()\fR except it returns a NULL \f(CW\*(C`SV *\*(C'\fR.  It is used by
+\&\f(CWSvREFCNT_dec_set_NULL()\fR which is a macro which will, when passed a
+non-NULL argument, decrement the reference count of its argument and
+then set it to NULL. You can replace code of the following form:
+.Sp
+.Vb 4
+\&    if (sv) {
+\&       SvREFCNT_dec_NN(sv);
+\&       sv = NULL;
+\&    }
+.Ve
+.Sp
+with
+.Sp
+.Vb 1
+\&    SvREFCNT_dec_set_NULL(sv);
+.Ve
+.RS 4
+.Sp
+.Vb 4
+\& void  SvREFCNT_dec         (SV *sv)
+\& void  SvREFCNT_dec_set_NULL(SV *sv)
+\& SV *  SvREFCNT_dec_ret_NULL(SV *sv)
+\& void  SvREFCNT_dec_NN      (SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvREFCNT_inc""" 4
+.el .IP \f(CWSvREFCNT_inc\fR 4
+.IX Item "SvREFCNT_inc"
+.PD 0
+.ie n .IP """SvREFCNT_inc_NN""" 4
+.el .IP \f(CWSvREFCNT_inc_NN\fR 4
+.IX Item "SvREFCNT_inc_NN"
+.ie n .IP """SvREFCNT_inc_simple""" 4
+.el .IP \f(CWSvREFCNT_inc_simple\fR 4
+.IX Item "SvREFCNT_inc_simple"
+.ie n .IP """SvREFCNT_inc_simple_NN""" 4
+.el .IP \f(CWSvREFCNT_inc_simple_NN\fR 4
+.IX Item "SvREFCNT_inc_simple_NN"
+.ie n .IP """SvREFCNT_inc_simple_void""" 4
+.el .IP \f(CWSvREFCNT_inc_simple_void\fR 4
+.IX Item "SvREFCNT_inc_simple_void"
+.ie n .IP """SvREFCNT_inc_simple_void_NN""" 4
+.el .IP \f(CWSvREFCNT_inc_simple_void_NN\fR 4
+.IX Item "SvREFCNT_inc_simple_void_NN"
+.ie n .IP """SvREFCNT_inc_void""" 4
+.el .IP \f(CWSvREFCNT_inc_void\fR 4
+.IX Item "SvREFCNT_inc_void"
+.ie n .IP """SvREFCNT_inc_void_NN""" 4
+.el .IP \f(CWSvREFCNT_inc_void_NN\fR 4
+.IX Xref "SvREFCNT_inc SvREFCNT_inc_NN SvREFCNT_inc_simple SvREFCNT_inc_simple_NN SvREFCNT_inc_simple_void SvREFCNT_inc_simple_void_NN SvREFCNT_inc_void SvREFCNT_inc_void_NN"
+.IX Item "SvREFCNT_inc_void_NN"
+.PD
+These all increment the reference count of the given SV.
+The ones without \f(CW\*(C`void\*(C'\fR in their names return the SV.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc\*(C'\fR is the base operation; the rest are optimizations if various
+input constraints are known to be true; hence, all can be replaced with
+\&\f(CW\*(C`SvREFCNT_inc\*(C'\fR.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_NN\*(C'\fR can only be used if you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.  Since we
+don't have to check the NULLness, it's faster and smaller.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_void\*(C'\fR can only be used if you don't need the
+return value.  The macro doesn't need to return a meaningful value.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_void_NN\*(C'\fR can only be used if you both don't need the return
+value, and you know that \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.  The macro doesn't need to
+return a meaningful value, or check for NULLness, so it's smaller and faster.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_simple\*(C'\fR can only be used with expressions without side
+effects.  Since we don't have to store a temporary value, it's faster.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_simple_NN\*(C'\fR can only be used with expressions without side
+effects and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.  Since we don't have to store a
+temporary value, nor check for NULLness, it's faster and smaller.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_simple_void\*(C'\fR can only be used with expressions without side
+effects and you don't need the return value.
+.Sp
+\&\f(CW\*(C`SvREFCNT_inc_simple_void_NN\*(C'\fR can only be used with expressions without side
+effects, you don't need the return value, and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.
+.RS 4
+.Sp
+.Vb 8
+\& SV *  SvREFCNT_inc               (SV *sv)
+\& SV *  SvREFCNT_inc_NN            (SV *sv)
+\& SV*   SvREFCNT_inc_simple        (SV* sv)
+\& SV*   SvREFCNT_inc_simple_NN     (SV* sv)
+\& void  SvREFCNT_inc_simple_void   (SV* sv)
+\& void  SvREFCNT_inc_simple_void_NN(SV* sv)
+\& void  SvREFCNT_inc_void          (SV *sv)
+\& void  SvREFCNT_inc_void_NN       (SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_reftype""" 4
+.el .IP \f(CWsv_reftype\fR 4
+.IX Xref "sv_reftype"
+.IX Item "sv_reftype"
+Returns a string describing what the SV is a reference to.
+.Sp
+If ob is true and the SV is blessed, the string is the class name,
+otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
+.RS 4
+.Sp
+.Vb 1
+\& const char *  sv_reftype(const SV * const sv, const int ob)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_replace""" 4
+.el .IP \f(CWsv_replace\fR 4
+.IX Xref "sv_replace"
+.IX Item "sv_replace"
+Make the first argument a copy of the second, then delete the original.
+The target SV physically takes over ownership of the body of the source SV
+and inherits its flags; however, the target keeps any magic it owns,
+and any magic in the source is discarded.
+Note that this is a rather specialist SV copying operation; most of the
+time you'll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front-ends.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_replace(SV * const sv, SV * const nsv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_report_used""" 4
+.el .IP \f(CWsv_report_used\fR 4
+.IX Xref "sv_report_used"
+.IX Item "sv_report_used"
+Dump the contents of all SVs not yet freed (debugging aid).
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_report_used()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_reset""" 4
+.el .IP \f(CWsv_reset\fR 4
+.IX Xref "sv_reset"
+.IX Item "sv_reset"
+Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function.
+Note that the perl-level function is vaguely deprecated.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_reset(const char *s, HV * const stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvROK""" 4
+.el .IP \f(CWSvROK\fR 4
+.IX Xref "SvROK"
+.IX Item "SvROK"
+Tests if the SV is an RV.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvROK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvROK_off""" 4
+.el .IP \f(CWSvROK_off\fR 4
+.IX Xref "SvROK_off"
+.IX Item "SvROK_off"
+Unsets the RV status of an SV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvROK_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvROK_on""" 4
+.el .IP \f(CWSvROK_on\fR 4
+.IX Xref "SvROK_on"
+.IX Item "SvROK_on"
+Tells an SV that it is an RV.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvROK_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvRV""" 4
+.el .IP \f(CWSvRV\fR 4
+.IX Xref "SvRV"
+.IX Item "SvRV"
+Dereferences an RV to return the SV.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  SvRV(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvRV_set""" 4
+.el .IP \f(CWSvRV_set\fR 4
+.IX Xref "SvRV_set"
+.IX Item "SvRV_set"
+Set the value of the RV pointer in \f(CW\*(C`sv\*(C'\fR to val.  See \f(CW"SvIV_set"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvRV_set(SV* sv, SV* val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_rvunweaken""" 4
+.el .IP \f(CWsv_rvunweaken\fR 4
+.IX Xref "sv_rvunweaken"
+.IX Item "sv_rvunweaken"
+Unweaken a reference: Clear the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; remove
+the backreference to this RV from the array of backreferences
+associated with the target SV, increment the refcount of the target.
+Silently ignores \f(CW\*(C`undef\*(C'\fR and warns on non-weak references.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_rvunweaken(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_rvweaken""" 4
+.el .IP \f(CWsv_rvweaken\fR 4
+.IX Xref "sv_rvweaken"
+.IX Item "sv_rvweaken"
+Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; give the
+referred-to SV \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn't already; and
+push a back-reference to this RV onto the array of backreferences
+associated with that magic.  If the RV is magical, set magic will be
+called after the RV is cleared.  Silently ignores \f(CW\*(C`undef\*(C'\fR and warns
+on already-weak references.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_rvweaken(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setbool""" 4
+.el .IP \f(CWsv_setbool\fR 4
+.IX Item "sv_setbool"
+.PD 0
+.ie n .IP """sv_setbool_mg""" 4
+.el .IP \f(CWsv_setbool_mg\fR 4
+.IX Xref "sv_setbool sv_setbool_mg"
+.IX Item "sv_setbool_mg"
+.PD
+These set an SV to a true or false boolean value, upgrading first if necessary.
+.Sp
+They differ only in that \f(CW\*(C`sv_setbool_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setbool\*(C'\fR
+does not.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_setbool(SV *sv, bool b)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_set_bool""" 4
+.el .IP \f(CWsv_set_bool\fR 4
+.IX Xref "sv_set_bool"
+.IX Item "sv_set_bool"
+Equivalent to \f(CW\*(C`sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no)\*(C'\fR, but
+may be made more efficient in the future. Doesn't handle set magic.
+.Sp
+The perl equivalent is \f(CW\*(C`$sv = !!$expr;\*(C'\fR.
+.Sp
+Introduced in perl 5.35.11.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_set_bool(SV *sv, const bool bool_val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_set_false""" 4
+.el .IP \f(CWsv_set_false\fR 4
+.IX Xref "sv_set_false"
+.IX Item "sv_set_false"
+Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_no)\*(C'\fR, but may be made more
+efficient in the future. Doesn't handle set magic.
+.Sp
+The perl equivalent is \f(CW\*(C`$sv = !1;\*(C'\fR.
+.Sp
+Introduced in perl 5.35.11.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_set_false(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setiv""" 4
+.el .IP \f(CWsv_setiv\fR 4
+.IX Item "sv_setiv"
+.PD 0
+.ie n .IP """sv_setiv_mg""" 4
+.el .IP \f(CWsv_setiv_mg\fR 4
+.IX Xref "sv_setiv sv_setiv_mg"
+.IX Item "sv_setiv_mg"
+.PD
+These copy an integer into the given SV, upgrading first if necessary.
+.Sp
+They differ only in that \f(CW\*(C`sv_setiv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setiv\*(C'\fR does
+not.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_setiv   (SV * const sv, const IV num)
+\& void  sv_setiv_mg(SV * const sv, const IV i)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSETMAGIC""" 4
+.el .IP \f(CWSvSETMAGIC\fR 4
+.IX Xref "SvSETMAGIC"
+.IX Item "SvSETMAGIC"
+Invokes \f(CW"mg_set"\fR on an SV if it has 'set' magic.  This is necessary
+after modifying a scalar, in case it is a magical variable like \f(CW$|\fR
+or a tied variable (it calls \f(CW\*(C`STORE\*(C'\fR).  This macro evaluates its
+argument more than once.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvSETMAGIC(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSetMagicSV""" 4
+.el .IP \f(CWSvSetMagicSV\fR 4
+.IX Item "SvSetMagicSV"
+.PD 0
+.ie n .IP """SvSetMagicSV_nosteal""" 4
+.el .IP \f(CWSvSetMagicSV_nosteal\fR 4
+.IX Item "SvSetMagicSV_nosteal"
+.ie n .IP """SvSetSV""" 4
+.el .IP \f(CWSvSetSV\fR 4
+.IX Item "SvSetSV"
+.ie n .IP """SvSetSV_nosteal""" 4
+.el .IP \f(CWSvSetSV_nosteal\fR 4
+.IX Xref "SvSetMagicSV SvSetMagicSV_nosteal SvSetSV SvSetSV_nosteal"
+.IX Item "SvSetSV_nosteal"
+.PD
+if \f(CW\*(C`dsv\*(C'\fR is the same as \f(CW\*(C`ssv\*(C'\fR, these do nothing.  Otherwise they all call
+some form of \f(CW"sv_setsv"\fR.  They may evaluate their arguments more than
+once.
+.Sp
+The only differences are:
+.Sp
+\&\f(CW\*(C`SvSetMagicSV\*(C'\fR and \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR perform any required 'set' magic
+afterwards on the destination SV; \f(CW\*(C`SvSetSV\*(C'\fR and \f(CW\*(C`SvSetSV_nosteal\*(C'\fR do not.
+.Sp
+\&\f(CW\*(C`SvSetSV_nosteal\*(C'\fR \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR call a non-destructive version of
+\&\f(CW\*(C`sv_setsv\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvSetMagicSV(SV* dsv, SV* ssv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setnv""" 4
+.el .IP \f(CWsv_setnv\fR 4
+.IX Item "sv_setnv"
+.PD 0
+.ie n .IP """sv_setnv_mg""" 4
+.el .IP \f(CWsv_setnv_mg\fR 4
+.IX Xref "sv_setnv sv_setnv_mg"
+.IX Item "sv_setnv_mg"
+.PD
+These copy a double into the given SV, upgrading first if necessary.
+.Sp
+They differ only in that \f(CW\*(C`sv_setnv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setnv\*(C'\fR does
+not.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_setnv(SV * const sv, const NV num)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setpv""" 4
+.el .IP \f(CWsv_setpv\fR 4
+.IX Item "sv_setpv"
+.PD 0
+.ie n .IP """sv_setpv_mg""" 4
+.el .IP \f(CWsv_setpv_mg\fR 4
+.IX Item "sv_setpv_mg"
+.ie n .IP """sv_setpvn""" 4
+.el .IP \f(CWsv_setpvn\fR 4
+.IX Item "sv_setpvn"
+.ie n .IP """sv_setpvn_fresh""" 4
+.el .IP \f(CWsv_setpvn_fresh\fR 4
+.IX Item "sv_setpvn_fresh"
+.ie n .IP """sv_setpvn_mg""" 4
+.el .IP \f(CWsv_setpvn_mg\fR 4
+.IX Item "sv_setpvn_mg"
+.ie n .IP """sv_setpvs""" 4
+.el .IP \f(CWsv_setpvs\fR 4
+.IX Item "sv_setpvs"
+.ie n .IP """sv_setpvs_mg""" 4
+.el .IP \f(CWsv_setpvs_mg\fR 4
+.IX Xref "sv_setpv sv_setpv_mg sv_setpvn sv_setpvn_fresh sv_setpvn_mg sv_setpvs sv_setpvs_mg"
+.IX Item "sv_setpvs_mg"
+.PD
+These copy a string into the SV \f(CW\*(C`sv\*(C'\fR, making sure it is \f(CW"SvPOK_only"\fR.
+.Sp
+In the \f(CW\*(C`pvs\*(C'\fR forms, the string must be a C literal string, enclosed in double
+quotes.
+.Sp
+In the \f(CW\*(C`pvn\*(C'\fR forms, the first byte of the string is pointed to by \f(CW\*(C`ptr\*(C'\fR, and
+\&\f(CW\*(C`len\*(C'\fR indicates the number of bytes to be copied, potentially including
+embedded \f(CW\*(C`NUL\*(C'\fR characters.
+.Sp
+In the plain \f(CW\*(C`pv\*(C'\fR forms, \f(CW\*(C`ptr\*(C'\fR points to a NUL-terminated C string.  That is,
+it points to the first byte of the string, and the copy proceeds up through the
+first encountered \f(CW\*(C`NUL\*(C'\fR byte.
+.Sp
+In the forms that take a \f(CW\*(C`ptr\*(C'\fR argument, if it is NULL, the SV will become
+undefined.
+.Sp
+The UTF\-8 flag is not changed by these functions.  A terminating NUL byte is
+guaranteed in the result.
+.Sp
+The \f(CW\*(C`_mg\*(C'\fR forms handle 'set' magic; the other forms skip all magic.
+.Sp
+\&\f(CW\*(C`sv_setpvn_fresh\*(C'\fR is a cut-down alternative to \f(CW\*(C`sv_setpvn\*(C'\fR, intended ONLY
+to be used with a fresh sv that has been upgraded to a SVt_PV, SVt_PVIV,
+SVt_PVNV, or SVt_PVMG.
+.RS 4
+.Sp
+.Vb 10
+\& void  sv_setpv       (SV * const sv, const char * const ptr)
+\& void  sv_setpv_mg    (SV * const sv, const char * const ptr)
+\& void  sv_setpvn      (SV * const sv, const char * const ptr,
+\&                       const STRLEN len)
+\& void  sv_setpvn_fresh(SV * const sv, const char * const ptr,
+\&                       const STRLEN len)
+\& void  sv_setpvn_mg   (SV * const sv, const char * const ptr,
+\&                       const STRLEN len)
+\& void  sv_setpvs      (SV* sv, "literal string")
+\& void  sv_setpvs_mg   (SV* sv, "literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setpv_bufsize""" 4
+.el .IP \f(CWsv_setpv_bufsize\fR 4
+.IX Xref "sv_setpv_bufsize"
+.IX Item "sv_setpv_bufsize"
+Sets the SV to be a string of cur bytes length, with at least
+len bytes available. Ensures that there is a null byte at SvEND.
+Returns a char * pointer to the SvPV buffer.
+.RS 4
+.Sp
+.Vb 2
+\& char  *  sv_setpv_bufsize(SV * const sv, const STRLEN cur,
+\&                           const STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setpvf""" 4
+.el .IP \f(CWsv_setpvf\fR 4
+.IX Item "sv_setpvf"
+.PD 0
+.ie n .IP """sv_setpvf_mg""" 4
+.el .IP \f(CWsv_setpvf_mg\fR 4
+.IX Item "sv_setpvf_mg"
+.ie n .IP """sv_setpvf_mg_nocontext""" 4
+.el .IP \f(CWsv_setpvf_mg_nocontext\fR 4
+.IX Item "sv_setpvf_mg_nocontext"
+.ie n .IP """sv_setpvf_nocontext""" 4
+.el .IP \f(CWsv_setpvf_nocontext\fR 4
+.IX Xref "sv_setpvf sv_setpvf_mg sv_setpvf_mg_nocontext sv_setpvf_nocontext"
+.IX Item "sv_setpvf_nocontext"
+.PD
+These work like \f(CW"sv_catpvf"\fR but copy the text into the SV instead of
+appending it.
+.Sp
+The differences between these are:
+.Sp
+\&\f(CW\*(C`sv_setpvf_mg\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR perform 'set' magic; \f(CW\*(C`sv_setpvf\*(C'\fR
+and \f(CW\*(C`sv_setpvf_nocontext\*(C'\fR skip all magic.
+.Sp
+\&\f(CW\*(C`sv_setpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR do not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
+doesn't already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`sv_setpvf\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_sv_setpvf\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.Sp
+NOTE: \f(CW\*(C`sv_setpvf_mg\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_sv_setpvf_mg\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 8
+\& void  Perl_sv_setpvf        (pTHX_ SV * const sv,
+\&                              const char * const pat, ...)
+\& void  Perl_sv_setpvf_mg     (pTHX_ SV * const sv,
+\&                              const char * const pat, ...)
+\& void  sv_setpvf_mg_nocontext(SV * const sv,
+\&                              const char * const pat, ...)
+\& void  sv_setpvf_nocontext   (SV * const sv,
+\&                              const char * const pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_iv""" 4
+.el .IP \f(CWsv_setref_iv\fR 4
+.IX Xref "sv_setref_iv"
+.IX Item "sv_setref_iv"
+Copies an integer into a new SV, optionally blessing the SV.  The \f(CW\*(C`rv\*(C'\fR
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
+blessing.  Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing.  The new SV
+will have a reference count of 1, and the RV will be returned.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_iv(SV * const rv, const char * const classname,
+\&                    const IV iv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_nv""" 4
+.el .IP \f(CWsv_setref_nv\fR 4
+.IX Xref "sv_setref_nv"
+.IX Item "sv_setref_nv"
+Copies a double into a new SV, optionally blessing the SV.  The \f(CW\*(C`rv\*(C'\fR
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
+blessing.  Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing.  The new SV
+will have a reference count of 1, and the RV will be returned.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_nv(SV * const rv, const char * const classname,
+\&                    const NV nv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_pv""" 4
+.el .IP \f(CWsv_setref_pv\fR 4
+.IX Xref "sv_setref_pv"
+.IX Item "sv_setref_pv"
+Copies a pointer into a new SV, optionally blessing the SV.  The \f(CW\*(C`rv\*(C'\fR
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  If the \f(CW\*(C`pv\*(C'\fR argument is \f(CW\*(C`NULL\*(C'\fR, then \f(CW\*(C`PL_sv_undef\*(C'\fR will be placed
+into the SV.  The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
+blessing.  Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing.  The new SV
+will have a reference count of 1, and the RV will be returned.
+.Sp
+Do not use with other Perl types such as HV, AV, SV, CV, because those
+objects will become corrupted by the pointer copy process.
+.Sp
+Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_pv(SV * const rv, const char * const classname,
+\&                    void * const pv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_pvn""" 4
+.el .IP \f(CWsv_setref_pvn\fR 4
+.IX Xref "sv_setref_pvn"
+.IX Item "sv_setref_pvn"
+Copies a string into a new SV, optionally blessing the SV.  The length of the
+string must be specified with \f(CW\*(C`n\*(C'\fR.  The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to
+an RV.  That RV will be modified to point to the new SV.  The \f(CW\*(C`classname\*(C'\fR
+argument indicates the package for the blessing.  Set \f(CW\*(C`classname\*(C'\fR to
+\&\f(CW\*(C`NULL\*(C'\fR to avoid the blessing.  The new SV will have a reference count
+of 1, and the RV will be returned.
+.Sp
+Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_pvn(SV * const rv, const char * const classname,
+\&                     const char * const pv, const STRLEN n)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_pvs""" 4
+.el .IP \f(CWsv_setref_pvs\fR 4
+.IX Xref "sv_setref_pvs"
+.IX Item "sv_setref_pvs"
+Like \f(CW\*(C`sv_setref_pvn\*(C'\fR, but takes a literal string instead of
+a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_pvs(SV *const rv, const char *const classname,
+\&                     "literal string")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setref_uv""" 4
+.el .IP \f(CWsv_setref_uv\fR 4
+.IX Xref "sv_setref_uv"
+.IX Item "sv_setref_uv"
+Copies an unsigned integer into a new SV, optionally blessing the SV.  The \f(CW\*(C`rv\*(C'\fR
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
+blessing.  Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing.  The new SV
+will have a reference count of 1, and the RV will be returned.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  sv_setref_uv(SV * const rv, const char * const classname,
+\&                    const UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setrv_inc""" 4
+.el .IP \f(CWsv_setrv_inc\fR 4
+.IX Item "sv_setrv_inc"
+.PD 0
+.ie n .IP """sv_setrv_inc_mg""" 4
+.el .IP \f(CWsv_setrv_inc_mg\fR 4
+.IX Xref "sv_setrv_inc sv_setrv_inc_mg"
+.IX Item "sv_setrv_inc_mg"
+.PD
+As \f(CW\*(C`sv_setrv_noinc\*(C'\fR but increments the reference count of \fIref\fR.
+.Sp
+\&\f(CW\*(C`sv_setrv_inc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_inc\*(C'\fR will
+not.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_setrv_inc(SV * const sv, SV * const ref)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setrv_noinc""" 4
+.el .IP \f(CWsv_setrv_noinc\fR 4
+.IX Item "sv_setrv_noinc"
+.PD 0
+.ie n .IP """sv_setrv_noinc_mg""" 4
+.el .IP \f(CWsv_setrv_noinc_mg\fR 4
+.IX Xref "sv_setrv_noinc sv_setrv_noinc_mg"
+.IX Item "sv_setrv_noinc_mg"
+.PD
+Copies an SV pointer into the given SV as an SV reference, upgrading it if
+necessary. After this, \f(CWSvRV(sv)\fR is equal to \fIref\fR. This does not adjust
+the reference count of \fIref\fR. The reference \fIref\fR must not be NULL.
+.Sp
+\&\f(CW\*(C`sv_setrv_noinc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_noinc\*(C'\fR will
+not.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_setrv_noinc(SV * const sv, SV * const ref)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setsv""" 4
+.el .IP \f(CWsv_setsv\fR 4
+.IX Item "sv_setsv"
+.PD 0
+.ie n .IP """sv_setsv_flags""" 4
+.el .IP \f(CWsv_setsv_flags\fR 4
+.IX Item "sv_setsv_flags"
+.ie n .IP """sv_setsv_mg""" 4
+.el .IP \f(CWsv_setsv_mg\fR 4
+.IX Item "sv_setsv_mg"
+.ie n .IP """sv_setsv_nomg""" 4
+.el .IP \f(CWsv_setsv_nomg\fR 4
+.IX Xref "sv_setsv sv_setsv_flags sv_setsv_mg sv_setsv_nomg"
+.IX Item "sv_setsv_nomg"
+.PD
+These copy the contents of the source SV \f(CW\*(C`ssv\*(C'\fR into the destination SV \f(CW\*(C`dsv\*(C'\fR.
+\&\f(CW\*(C`ssv\*(C'\fR may be destroyed if it is mortal, so don't use these functions if
+the source SV needs to be reused.
+Loosely speaking, they perform a copy-by-value, obliterating any previous
+content of the destination.
+.Sp
+They differ only in that:
+.Sp
+\&\f(CW\*(C`sv_setsv\*(C'\fR calls 'get' magic on \f(CW\*(C`ssv\*(C'\fR, but skips 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
+.Sp
+\&\f(CW\*(C`sv_setsv_mg\*(C'\fR calls both 'get' magic on \f(CW\*(C`ssv\*(C'\fR and 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
+.Sp
+\&\f(CW\*(C`sv_setsv_nomg\*(C'\fR skips all magic.
+.Sp
+\&\f(CW\*(C`sv_setsv_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter which you can use to specify any
+combination of magic handling, and also you can specify \f(CW\*(C`SV_NOSTEAL\*(C'\fR so that
+the buffers of temps will not be stolen.
+.Sp
+You probably want to instead use one of the assortment of wrappers, such as
+\&\f(CW"SvSetSV"\fR, \f(CW"SvSetSV_nosteal"\fR, \f(CW"SvSetMagicSV"\fR and
+\&\f(CW"SvSetMagicSV_nosteal"\fR.
+.Sp
+\&\f(CW\*(C`sv_setsv_flags\*(C'\fR is the primary function for copying scalars, and most other
+copy-ish functions and macros use it underneath.
+.RS 4
+.Sp
+.Vb 4
+\& void  sv_setsv      (SV *dsv, SV *ssv)
+\& void  sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
+\& void  sv_setsv_mg   (SV * const dsv, SV * const ssv)
+\& void  sv_setsv_nomg (SV *dsv, SV *ssv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_set_true""" 4
+.el .IP \f(CWsv_set_true\fR 4
+.IX Xref "sv_set_true"
+.IX Item "sv_set_true"
+Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_yes)\*(C'\fR, but may be made more
+efficient in the future. Doesn't handle set magic.
+.Sp
+The perl equivalent is \f(CW\*(C`$sv = !0;\*(C'\fR.
+.Sp
+Introduced in perl 5.35.11.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_set_true(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_set_undef""" 4
+.el .IP \f(CWsv_set_undef\fR 4
+.IX Xref "sv_set_undef"
+.IX Item "sv_set_undef"
+Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_undef)\*(C'\fR, but more efficient.
+Doesn't handle set magic.
+.Sp
+The perl equivalent is \f(CW\*(C`$sv = undef;\*(C'\fR. Note that it doesn't free any string
+buffer, unlike \f(CW\*(C`undef $sv\*(C'\fR.
+.Sp
+Introduced in perl 5.25.12.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_set_undef(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_setuv""" 4
+.el .IP \f(CWsv_setuv\fR 4
+.IX Item "sv_setuv"
+.PD 0
+.ie n .IP """sv_setuv_mg""" 4
+.el .IP \f(CWsv_setuv_mg\fR 4
+.IX Xref "sv_setuv sv_setuv_mg"
+.IX Item "sv_setuv_mg"
+.PD
+These copy an unsigned integer into the given SV, upgrading first if necessary.
+.Sp
+They differ only in that \f(CW\*(C`sv_setuv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setuv\*(C'\fR does
+not.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_setuv   (SV * const sv, const UV num)
+\& void  sv_setuv_mg(SV * const sv, const UV u)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSHARE""" 4
+.el .IP \f(CWSvSHARE\fR 4
+.IX Xref "SvSHARE"
+.IX Item "SvSHARE"
+Arranges for \f(CW\*(C`sv\*(C'\fR to be shared between threads if a suitable module
+has been loaded.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvSHARE(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSHARED_HASH""" 4
+.el .IP \f(CWSvSHARED_HASH\fR 4
+.IX Xref "SvSHARED_HASH"
+.IX Item "SvSHARED_HASH"
+Returns the hash for \f(CW\*(C`sv\*(C'\fR created by \f(CW"newSVpvn_share"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& struct hek*  SvSHARED_HASH(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSTASH""" 4
+.el .IP \f(CWSvSTASH\fR 4
+.IX Xref "SvSTASH"
+.IX Item "SvSTASH"
+Returns the stash of the SV.
+.RS 4
+.Sp
+.Vb 1
+\& HV*  SvSTASH(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvSTASH_set""" 4
+.el .IP \f(CWSvSTASH_set\fR 4
+.IX Xref "SvSTASH_set"
+.IX Item "SvSTASH_set"
+Set the value of the STASH pointer in \f(CW\*(C`sv\*(C'\fR to val.  See \f(CW"SvIV_set"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvSTASH_set(SV* sv, HV* val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_streq""" 4
+.el .IP \f(CWsv_streq\fR 4
+.IX Xref "sv_streq"
+.IX Item "sv_streq"
+A convenient shortcut for calling \f(CW\*(C`sv_streq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR
+flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 eq $sv2\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_streq(SV *sv1, SV *sv2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_streq_flags""" 4
+.el .IP \f(CWsv_streq_flags\fR 4
+.IX Xref "sv_streq_flags"
+.IX Item "sv_streq_flags"
+Returns a boolean indicating whether the strings in the two SVs are
+identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles
+get-magic too. Will coerce its args to strings if necessary. Treats
+\&\f(CW\*(C`NULL\*(C'\fR as undef. Correctly handles the UTF8 flag.
+.Sp
+If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
+\&\f(CW\*(C`eq\*(C'\fR overloading will be made. If such overloading does not exist or the
+flag is set, then regular string comparison will be used instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_streq_flags(SV *sv1, SV *sv2, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTRUE""" 4
+.el .IP \f(CWSvTRUE\fR 4
+.IX Item "SvTRUE"
+.PD 0
+.ie n .IP """SvTRUE_NN""" 4
+.el .IP \f(CWSvTRUE_NN\fR 4
+.IX Item "SvTRUE_NN"
+.ie n .IP """SvTRUE_nomg""" 4
+.el .IP \f(CWSvTRUE_nomg\fR 4
+.IX Item "SvTRUE_nomg"
+.ie n .IP """SvTRUE_nomg_NN""" 4
+.el .IP \f(CWSvTRUE_nomg_NN\fR 4
+.IX Item "SvTRUE_nomg_NN"
+.ie n .IP """SvTRUEx""" 4
+.el .IP \f(CWSvTRUEx\fR 4
+.IX Xref "SvTRUE SvTRUE_NN SvTRUE_nomg SvTRUE_nomg_NN SvTRUEx"
+.IX Item "SvTRUEx"
+.PD
+These return a boolean indicating whether Perl would evaluate the SV as true or
+false.  See \f(CW"SvOK"\fR for a defined/undefined test.
+.Sp
+As of Perl 5.32, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.  Prior to that
+release, only \f(CW\*(C`SvTRUEx\*(C'\fR guaranteed single evaluation; now \f(CW\*(C`SvTRUEx\*(C'\fR is
+identical to \f(CW\*(C`SvTRUE\*(C'\fR.
+.Sp
+\&\f(CW\*(C`SvTRUE_nomg\*(C'\fR and \f(CW\*(C`TRUE_nomg_NN\*(C'\fR do not perform 'get' magic; the others do
+unless the scalar is already \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR, or \f(CW\*(C`SvNOK\*(C'\fR (the public, not
+the private flags).
+.Sp
+\&\f(CW\*(C`SvTRUE_NN\*(C'\fR is like \f(CW"SvTRUE"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be
+non-null (NN).  If there is a possibility that it is NULL, use plain
+\&\f(CW\*(C`SvTRUE\*(C'\fR.
+.Sp
+\&\f(CW\*(C`SvTRUE_nomg_NN\*(C'\fR is like \f(CW"SvTRUE_nomg"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be
+non-null (NN).  If there is a possibility that it is NULL, use plain
+\&\f(CW\*(C`SvTRUE_nomg\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvTRUE(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTYPE""" 4
+.el .IP \f(CWSvTYPE\fR 4
+.IX Xref "SvTYPE"
+.IX Item "SvTYPE"
+Returns the type of the SV.  See \f(CW"svtype"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& svtype  SvTYPE(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUNLOCK""" 4
+.el .IP \f(CWSvUNLOCK\fR 4
+.IX Xref "SvUNLOCK"
+.IX Item "SvUNLOCK"
+Releases a mutual exclusion lock on \f(CW\*(C`sv\*(C'\fR if a suitable module
+has been loaded.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvUNLOCK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_unmagic""" 4
+.el .IP \f(CWsv_unmagic\fR 4
+.IX Xref "sv_unmagic"
+.IX Item "sv_unmagic"
+Removes all magic of type \f(CW\*(C`type\*(C'\fR from an SV.
+.RS 4
+.Sp
+.Vb 1
+\& int  sv_unmagic(SV * const sv, const int type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_unmagicext""" 4
+.el .IP \f(CWsv_unmagicext\fR 4
+.IX Xref "sv_unmagicext"
+.IX Item "sv_unmagicext"
+Removes all magic of type \f(CW\*(C`type\*(C'\fR with the specified \f(CW\*(C`vtbl\*(C'\fR from an SV.
+.RS 4
+.Sp
+.Vb 2
+\& int  sv_unmagicext(SV * const sv, const int type,
+\&                    const MGVTBL *vtbl)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_unref""" 4
+.el .IP \f(CWsv_unref\fR 4
+.IX Xref "sv_unref"
+.IX Item "sv_unref"
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV.  This can almost be thought of
+as a reversal of \f(CW\*(C`newSVrv\*(C'\fR.  This is \f(CW\*(C`sv_unref_flags\*(C'\fR with the \f(CW\*(C`flag\*(C'\fR
+being zero.  See \f(CW"SvROK_off"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_unref(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_unref_flags""" 4
+.el .IP \f(CWsv_unref_flags\fR 4
+.IX Xref "sv_unref_flags"
+.IX Item "sv_unref_flags"
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV.  This can almost be thought of
+as a reversal of \f(CW\*(C`newSVrv\*(C'\fR.  The \f(CW\*(C`cflags\*(C'\fR argument can contain
+\&\f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR to force the reference count to be decremented
+(otherwise the decrementing is conditional on the reference count being
+different from one or the reference being a readonly SV).
+See \f(CW"SvROK_off"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_unref_flags(SV * const ref, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUOK""" 4
+.el .IP \f(CWSvUOK\fR 4
+.IX Xref "SvUOK"
+.IX Item "SvUOK"
+Returns a boolean indicating whether the SV contains an integer that must be
+interpreted as unsigned.  A non-negative integer whose value is within the
+range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvUOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUPGRADE""" 4
+.el .IP \f(CWSvUPGRADE\fR 4
+.IX Xref "SvUPGRADE"
+.IX Item "SvUPGRADE"
+Used to upgrade an SV to a more complex form.  Uses \f(CW\*(C`sv_upgrade\*(C'\fR to
+perform the upgrade if necessary.  See \f(CW"svtype"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvUPGRADE(SV* sv, svtype type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_upgrade""" 4
+.el .IP \f(CWsv_upgrade\fR 4
+.IX Xref "sv_upgrade"
+.IX Item "sv_upgrade"
+Upgrade an SV to a more complex form.  Generally adds a new body type to the
+SV, then copies across as much information as possible from the old body.
+It croaks if the SV is already in a more complex form than requested.  You
+generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper, which checks the type
+before calling \f(CW\*(C`sv_upgrade\*(C'\fR, and hence does not croak.  See also
+\&\f(CW"svtype"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_upgrade(SV * const sv, svtype new_type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_usepvn""" 4
+.el .IP \f(CWsv_usepvn\fR 4
+.IX Item "sv_usepvn"
+.PD 0
+.ie n .IP """sv_usepvn_flags""" 4
+.el .IP \f(CWsv_usepvn_flags\fR 4
+.IX Item "sv_usepvn_flags"
+.ie n .IP """sv_usepvn_mg""" 4
+.el .IP \f(CWsv_usepvn_mg\fR 4
+.IX Xref "sv_usepvn sv_usepvn_flags sv_usepvn_mg"
+.IX Item "sv_usepvn_mg"
+.PD
+These tell an SV to use \f(CW\*(C`ptr\*(C'\fR for its string value.  Normally SVs have
+their string stored inside the SV, but these tell the SV to use an
+external string instead.
+.Sp
+\&\f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated
+by "\f(CW\*(C`Newx\*(C'\fR".  It must be
+the start of a \f(CW\*(C`Newx\*(C'\fR\-ed block of memory, and not a pointer to the
+middle of it (beware of \f(CW\*(C`OOK\*(C'\fR and copy-on-write),
+and not be from a non\-\f(CW\*(C`Newx\*(C'\fR memory allocator like \f(CW\*(C`malloc\*(C'\fR.  The
+string length, \f(CW\*(C`len\*(C'\fR, must be supplied.  By default this function
+will "\f(CW\*(C`Renew\*(C'\fR" (i.e. realloc, move) the memory pointed to by \f(CW\*(C`ptr\*(C'\fR,
+so that the pointer should not be freed or used by the programmer after giving
+it to \f(CW\*(C`sv_usepvn\*(C'\fR, and neither should any pointers from "behind" that pointer
+(\fIe.g.\fR, \f(CW\*(C`ptr\*(C'\fR\ +\ 1) be used.
+.Sp
+In the \f(CW\*(C`sv_usepvn_flags\*(C'\fR form, if \f(CW\*(C`flags\ &\ SV_SMAGIC\*(C'\fR is true,
+\&\f(CW\*(C`SvSETMAGIC\*(C'\fR is called before returning.
+And if \f(CW\*(C`flags\ &\ SV_HAS_TRAILING_NUL\*(C'\fR is true, then \f(CW\*(C`ptr[len]\*(C'\fR must be
+\&\f(CW\*(C`NUL\*(C'\fR, and the realloc will be skipped (\fIi.e.\fR, the buffer is actually at
+least 1 byte longer than \f(CW\*(C`len\*(C'\fR, and already meets the requirements for storing
+in \f(CW\*(C`SvPVX\*(C'\fR).
+.Sp
+\&\f(CW\*(C`sv_usepvn\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to 0, so 'set'
+magic is skipped.
+.Sp
+\&\f(CW\*(C`sv_usepvn_mg\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to \f(CW\*(C`SV_SMAGIC\*(C'\fR,
+so 'set' magic is performed.
+.RS 4
+.Sp
+.Vb 4
+\& void  sv_usepvn      (SV *sv, char *ptr, STRLEN len)
+\& void  sv_usepvn_flags(SV * const sv, char *ptr, const STRLEN len,
+\&                       const U32 flags)
+\& void  sv_usepvn_mg   (SV *sv, char *ptr, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_utf8_decode""" 4
+.el .IP \f(CWsv_utf8_decode\fR 4
+.IX Xref "sv_utf8_decode"
+.IX Item "sv_utf8_decode"
+If the PV of the SV is an octet sequence in Perl's extended UTF\-8
+and contains a multiple-byte character, the \f(CW\*(C`SvUTF8\*(C'\fR flag is turned on
+so that it looks like a character.  If the PV contains only single-byte
+characters, the \f(CW\*(C`SvUTF8\*(C'\fR flag stays off.
+Scans PV for validity and returns FALSE if the PV is invalid UTF\-8.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_utf8_decode(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_utf8_downgrade""" 4
+.el .IP \f(CWsv_utf8_downgrade\fR 4
+.IX Item "sv_utf8_downgrade"
+.PD 0
+.ie n .IP """sv_utf8_downgrade_flags""" 4
+.el .IP \f(CWsv_utf8_downgrade_flags\fR 4
+.IX Item "sv_utf8_downgrade_flags"
+.ie n .IP """sv_utf8_downgrade_nomg""" 4
+.el .IP \f(CWsv_utf8_downgrade_nomg\fR 4
+.IX Xref "sv_utf8_downgrade sv_utf8_downgrade_flags sv_utf8_downgrade_nomg"
+.IX Item "sv_utf8_downgrade_nomg"
+.PD
+These attempt to convert the PV of an SV from characters to bytes.  If the PV
+contains a character that cannot fit in a byte, this conversion will fail; in
+this case, \f(CW\*(C`FALSE\*(C'\fR is returned if \f(CW\*(C`fail_ok\*(C'\fR is true; otherwise they croak.
+.Sp
+They are not a general purpose Unicode to byte encoding interface:
+use the \f(CW\*(C`Encode\*(C'\fR extension for that.
+.Sp
+They differ only in that:
+.Sp
+\&\f(CW\*(C`sv_utf8_downgrade\*(C'\fR processes 'get' magic on \f(CW\*(C`sv\*(C'\fR.
+.Sp
+\&\f(CW\*(C`sv_utf8_downgrade_nomg\*(C'\fR does not.
+.Sp
+\&\f(CW\*(C`sv_utf8_downgrade_flags\*(C'\fR has an additional \f(CW\*(C`flags\*(C'\fR parameter in which you can specify
+\&\f(CW\*(C`SV_GMAGIC\*(C'\fR to process 'get' magic, or leave it cleared to not process 'get' magic.
+.RS 4
+.Sp
+.Vb 4
+\& bool  sv_utf8_downgrade      (SV * const sv, const bool fail_ok)
+\& bool  sv_utf8_downgrade_flags(SV * const sv, const bool fail_ok,
+\&                               const U32 flags)
+\& bool  sv_utf8_downgrade_nomg (SV * const sv, const bool fail_ok)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_utf8_encode""" 4
+.el .IP \f(CWsv_utf8_encode\fR 4
+.IX Xref "sv_utf8_encode"
+.IX Item "sv_utf8_encode"
+Converts the PV of an SV to UTF\-8, but then turns the \f(CW\*(C`SvUTF8\*(C'\fR
+flag off so that it looks like octets again.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_utf8_encode(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUTF8_off""" 4
+.el .IP \f(CWSvUTF8_off\fR 4
+.IX Xref "SvUTF8_off"
+.IX Item "SvUTF8_off"
+Unsets the UTF\-8 status of an SV (the data is not changed, just the flag).
+Do not use frivolously.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvUTF8_off(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUTF8_on""" 4
+.el .IP \f(CWSvUTF8_on\fR 4
+.IX Xref "SvUTF8_on"
+.IX Item "SvUTF8_on"
+Turn on the UTF\-8 status of an SV (the data is not changed, just the flag).
+Do not use frivolously.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvUTF8_on(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_utf8_upgrade""" 4
+.el .IP \f(CWsv_utf8_upgrade\fR 4
+.IX Item "sv_utf8_upgrade"
+.PD 0
+.ie n .IP """sv_utf8_upgrade_flags""" 4
+.el .IP \f(CWsv_utf8_upgrade_flags\fR 4
+.IX Item "sv_utf8_upgrade_flags"
+.ie n .IP """sv_utf8_upgrade_flags_grow""" 4
+.el .IP \f(CWsv_utf8_upgrade_flags_grow\fR 4
+.IX Item "sv_utf8_upgrade_flags_grow"
+.ie n .IP """sv_utf8_upgrade_nomg""" 4
+.el .IP \f(CWsv_utf8_upgrade_nomg\fR 4
+.IX Xref "sv_utf8_upgrade sv_utf8_upgrade_flags sv_utf8_upgrade_flags_grow sv_utf8_upgrade_nomg"
+.IX Item "sv_utf8_upgrade_nomg"
+.PD
+These convert the PV of an SV to its UTF\-8\-encoded form.
+The SV is forced to string form if it is not already.
+They always set the \f(CW\*(C`SvUTF8\*(C'\fR flag to avoid future validity checks even if the
+whole string is the same in UTF\-8 as not.
+They return the number of bytes in the converted string
+.Sp
+The forms differ in just two ways.  The main difference is whether or not they
+perform 'get magic' on \f(CW\*(C`sv\*(C'\fR.  \f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR skips 'get magic';
+\&\f(CW\*(C`sv_utf8_upgrade\*(C'\fR performs it; and \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR and
+\&\f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR either perform it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set
+in \f(CW\*(C`flags\*(C'\fR) or don't (if that bit is cleared).
+.Sp
+The other difference is that \f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR has an additional
+parameter, \f(CW\*(C`extra\*(C'\fR, which allows the caller to specify an amount of space to
+be reserved as spare beyond what is needed for the actual conversion.  This is
+used when the caller knows it will soon be needing yet more space, and it is
+more efficient to request space from the system in a single call.
+This form is otherwise identical to \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR.
+.Sp
+These are not a general purpose byte encoding to Unicode interface: use the
+Encode extension for that.
+.Sp
+The \f(CW\*(C`SV_FORCE_UTF8_UPGRADE\*(C'\fR flag is now ignored.
+.RS 4
+.Sp
+.Vb 5
+\& STRLEN  sv_utf8_upgrade           (SV *sv)
+\& STRLEN  sv_utf8_upgrade_flags     (SV * const sv, const I32 flags)
+\& STRLEN  sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags,
+\&                                    STRLEN extra)
+\& STRLEN  sv_utf8_upgrade_nomg      (SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUTF8""" 4
+.el .IP \f(CWSvUTF8\fR 4
+.IX Xref "SvUTF8"
+.IX Item "SvUTF8"
+Returns a U32 value indicating the UTF\-8 status of an SV.  If things are set-up
+properly, this indicates whether or not the SV contains UTF\-8 encoded data.
+You should use this \fIafter\fR a call to \f(CW"SvPV"\fR or one of its variants, in
+case any call to string overloading updates the internal flag.
+.Sp
+If you want to take into account the bytes pragma, use \f(CW"DO_UTF8"\fR
+instead.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvUTF8(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUV""" 4
+.el .IP \f(CWSvUV\fR 4
+.IX Item "SvUV"
+.PD 0
+.ie n .IP """SvUV_nomg""" 4
+.el .IP \f(CWSvUV_nomg\fR 4
+.IX Item "SvUV_nomg"
+.ie n .IP """SvUVx""" 4
+.el .IP \f(CWSvUVx\fR 4
+.IX Xref "SvUV SvUV_nomg SvUVx"
+.IX Item "SvUVx"
+.PD
+These each coerce the given SV to UV and return it.  The returned value in many
+circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's UV slot, but not in all cases.  (Use
+\&\f(CW"sv_setuv"\fR to make sure it does).
+.Sp
+As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.Sp
+\&\f(CW\*(C`SvUVx\*(C'\fR is now identical to \f(CW\*(C`SvUV\*(C'\fR, but prior to 5.37.1, it was the only form
+guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
+.RS 4
+.Sp
+.Vb 1
+\& UV  SvUV(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2uv_flags""" 4
+.el .IP \f(CWsv_2uv_flags\fR 4
+.IX Xref "sv_2uv_flags"
+.IX Item "sv_2uv_flags"
+Return the unsigned integer value of an SV, doing any necessary string
+conversion.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
+Normally used via the \f(CWSvUV(sv)\fR and \f(CWSvUVx(sv)\fR macros.
+.RS 4
+.Sp
+.Vb 1
+\& UV  sv_2uv_flags(SV * const sv, const I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUV_set""" 4
+.el .IP \f(CWSvUV_set\fR 4
+.IX Xref "SvUV_set"
+.IX Item "SvUV_set"
+Set the value of the UV pointer in \f(CW\*(C`sv\*(C'\fR to val.  See \f(CW"SvIV_set"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvUV_set(SV* sv, UV val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUVX""" 4
+.el .IP \f(CWSvUVX\fR 4
+.IX Xref "SvUVX"
+.IX Item "SvUVX"
+Returns the raw value in the SV's UV slot, without checks or conversions.
+Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true.  See also \f(CW"SvUV"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& UV  SvUVX(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvUVXx""" 4
+.el .IP \f(CWSvUVXx\fR 4
+.IX Xref "SvUVXx"
+.IX Item "SvUVXx"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`SvUVXx\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+This is an unnecessary synonym for "SvUVX"
+.RS 4
+.Sp
+.Vb 1
+\& UV  SvUVXx(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_vcatpvf""" 4
+.el .IP \f(CWsv_vcatpvf\fR 4
+.IX Item "sv_vcatpvf"
+.PD 0
+.ie n .IP """sv_vcatpvf_mg""" 4
+.el .IP \f(CWsv_vcatpvf_mg\fR 4
+.IX Xref "sv_vcatpvf sv_vcatpvf_mg"
+.IX Item "sv_vcatpvf_mg"
+.PD
+These process their arguments like \f(CW\*(C`sv_vcatpvfn\*(C'\fR called with a non-null
+C\-style variable argument list, and append the formatted output to \f(CW\*(C`sv\*(C'\fR.
+.Sp
+They differ only in that \f(CW\*(C`sv_vcatpvf_mg\*(C'\fR performs 'set' magic;
+\&\f(CW\*(C`sv_vcatpvf\*(C'\fR skips 'set' magic.
+.Sp
+Both perform 'get' magic.
+.Sp
+They are usually accessed via their frontends \f(CW"sv_catpvf"\fR and
+\&\f(CW"sv_catpvf_mg"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_vcatpvf(SV * const sv, const char * const pat,
+\&                  va_list * const args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_vcatpvfn""" 4
+.el .IP \f(CWsv_vcatpvfn\fR 4
+.IX Item "sv_vcatpvfn"
+.PD 0
+.ie n .IP """sv_vcatpvfn_flags""" 4
+.el .IP \f(CWsv_vcatpvfn_flags\fR 4
+.IX Xref "sv_vcatpvfn sv_vcatpvfn_flags"
+.IX Item "sv_vcatpvfn_flags"
+.PD
+These process their arguments like \f(CWvsprintf(3)\fR and append the formatted output
+to an SV.  They use an array of SVs if the C\-style variable argument list is
+missing (\f(CW\*(C`NULL\*(C'\fR). Argument reordering (using format specifiers like \f(CW\*(C`%2$d\*(C'\fR or
+\&\f(CW\*(C`%*2$d\*(C'\fR) is supported only when using an array of SVs; using a C\-style
+\&\f(CW\*(C`va_list\*(C'\fR argument list with a format string that uses argument reordering
+will yield an exception.
+.Sp
+When running with taint checks enabled, they indicate via \f(CW\*(C`maybe_tainted\*(C'\fR if
+results are untrustworthy (often due to the use of locales).
+.Sp
+They assume that \f(CW\*(C`pat\*(C'\fR has the same utf8\-ness as \f(CW\*(C`sv\*(C'\fR.  It's the caller's
+responsibility to ensure that this is so.
+.Sp
+They differ in that \f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter in which you
+can set or clear the \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or SV_SMAGIC flags, to specify which
+magic to handle or not handle; whereas plain \f(CW\*(C`sv_vcatpvfn\*(C'\fR always specifies
+both 'get' and 'set' magic.
+.Sp
+They are usually used via one of the frontends "\f(CW\*(C`sv_vcatpvf\*(C'\fR" and
+"\f(CW\*(C`sv_vcatpvf_mg\*(C'\fR".
+.RS 4
+.Sp
+.Vb 9
+\& void  sv_vcatpvfn      (SV * const sv, const char * const pat,
+\&                         const STRLEN patlen, va_list * const args,
+\&                         SV ** const svargs, const Size_t sv_count,
+\&                         bool * const maybe_tainted)
+\& void  sv_vcatpvfn_flags(SV * const sv, const char * const pat,
+\&                         const STRLEN patlen, va_list * const args,
+\&                         SV ** const svargs, const Size_t sv_count,
+\&                         bool * const maybe_tainted,
+\&                         const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvVOK""" 4
+.el .IP \f(CWSvVOK\fR 4
+.IX Xref "SvVOK"
+.IX Item "SvVOK"
+Returns a boolean indicating whether the SV contains a v\-string.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvVOK(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_vsetpvf""" 4
+.el .IP \f(CWsv_vsetpvf\fR 4
+.IX Item "sv_vsetpvf"
+.PD 0
+.ie n .IP """sv_vsetpvf_mg""" 4
+.el .IP \f(CWsv_vsetpvf_mg\fR 4
+.IX Xref "sv_vsetpvf sv_vsetpvf_mg"
+.IX Item "sv_vsetpvf_mg"
+.PD
+These work like \f(CW"sv_vcatpvf"\fR but copy the text into the SV instead of
+appending it.
+.Sp
+They differ only in that \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR performs 'set' magic;
+\&\f(CW\*(C`sv_vsetpvf\*(C'\fR skips all magic.
+.Sp
+They are usually used via their frontends, \f(CW"sv_setpvf"\fR and
+\&\f(CW"sv_setpvf_mg"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_vsetpvf(SV * const sv, const char * const pat,
+\&                  va_list * const args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_vsetpvfn""" 4
+.el .IP \f(CWsv_vsetpvfn\fR 4
+.IX Xref "sv_vsetpvfn"
+.IX Item "sv_vsetpvfn"
+Works like \f(CW\*(C`sv_vcatpvfn\*(C'\fR but copies the text into the SV instead of
+appending it.
+.Sp
+Usually used via one of its frontends "\f(CW\*(C`sv_vsetpvf\*(C'\fR" and
+"\f(CW\*(C`sv_vsetpvf_mg\*(C'\fR".
+.RS 4
+.Sp
+.Vb 4
+\& void  sv_vsetpvfn(SV * const sv, const char * const pat,
+\&                   const STRLEN patlen, va_list * const args,
+\&                   SV ** const svargs, const Size_t sv_count,
+\&                   bool * const maybe_tainted)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvVSTRING_mg""" 4
+.el .IP \f(CWSvVSTRING_mg\fR 4
+.IX Xref "SvVSTRING_mg"
+.IX Item "SvVSTRING_mg"
+Returns the vstring magic, or NULL if none
+.RS 4
+.Sp
+.Vb 1
+\& MAGIC*  SvVSTRING_mg(SV * sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vnewSVpvf""" 4
+.el .IP \f(CWvnewSVpvf\fR 4
+.IX Xref "vnewSVpvf"
+.IX Item "vnewSVpvf"
+Like \f(CW"newSVpvf"\fR but the arguments are an encapsulated argument list.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vnewSVpvf(const char * const pat, va_list * const args)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Tainting
+.IX Header "Tainting"
+.ie n .IP """SvTAINT""" 4
+.el .IP \f(CWSvTAINT\fR 4
+.IX Xref "SvTAINT"
+.IX Item "SvTAINT"
+Taints an SV if tainting is enabled, and if some input to the current
+expression is tainted\-\-usually a variable, but possibly also implicit
+inputs such as locale settings.  \f(CW\*(C`SvTAINT\*(C'\fR propagates that taintedness to
+the outputs of an expression in a pessimistic fashion; i.e., without paying
+attention to precisely which outputs are influenced by which inputs.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvTAINT(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTAINTED""" 4
+.el .IP \f(CWSvTAINTED\fR 4
+.IX Xref "SvTAINTED"
+.IX Item "SvTAINTED"
+Checks to see if an SV is tainted.  Returns TRUE if it is, FALSE if
+not.
+.RS 4
+.Sp
+.Vb 1
+\& bool  SvTAINTED(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTAINTED_off""" 4
+.el .IP \f(CWSvTAINTED_off\fR 4
+.IX Xref "SvTAINTED_off"
+.IX Item "SvTAINTED_off"
+Untaints an SV.  Be \fIvery\fR careful with this routine, as it short-circuits
+some of Perl's fundamental security features.  XS module authors should not
+use this function unless they fully understand all the implications of
+unconditionally untainting the value.  Untainting should be done in the
+standard perl fashion, via a carefully crafted regexp, rather than directly
+untainting variables.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvTAINTED_off(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTAINTED_on""" 4
+.el .IP \f(CWSvTAINTED_on\fR 4
+.IX Xref "SvTAINTED_on"
+.IX Item "SvTAINTED_on"
+Marks an SV as tainted if tainting is enabled.
+.RS 4
+.Sp
+.Vb 1
+\& void  SvTAINTED_on(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Time
+.IX Header "Time"
+.ie n .IP """ASCTIME_R_PROTO""" 4
+.el .IP \f(CWASCTIME_R_PROTO\fR 4
+.IX Xref "ASCTIME_R_PROTO"
+.IX Item "ASCTIME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`asctime_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_asctime_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_asctime_r\*(C'\fR
+is defined.
+.ie n .IP """CTIME_R_PROTO""" 4
+.el .IP \f(CWCTIME_R_PROTO\fR 4
+.IX Xref "CTIME_R_PROTO"
+.IX Item "CTIME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`ctime_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_ctime_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctime_r\*(C'\fR
+is defined.
+.ie n .IP """GMTIME_MAX""" 4
+.el .IP \f(CWGMTIME_MAX\fR 4
+.IX Xref "GMTIME_MAX"
+.IX Item "GMTIME_MAX"
+This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
+the system function gmtime () accepts, and defaults to 0
+.ie n .IP """GMTIME_MIN""" 4
+.el .IP \f(CWGMTIME_MIN\fR 4
+.IX Xref "GMTIME_MIN"
+.IX Item "GMTIME_MIN"
+This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
+the system function gmtime () accepts, and defaults to 0
+.ie n .IP """GMTIME_R_PROTO""" 4
+.el .IP \f(CWGMTIME_R_PROTO\fR 4
+.IX Xref "GMTIME_R_PROTO"
+.IX Item "GMTIME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`gmtime_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_gmtime_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gmtime_r\*(C'\fR
+is defined.
+.ie n .IP """HAS_ASCTIME_R""" 4
+.el .IP \f(CWHAS_ASCTIME_R\fR 4
+.IX Xref "HAS_ASCTIME_R"
+.IX Item "HAS_ASCTIME_R"
+This symbol, if defined, indicates that the \f(CW\*(C`asctime_r\*(C'\fR routine
+is available to asctime re-entrantly.
+.ie n .IP """HAS_ASCTIME64""" 4
+.el .IP \f(CWHAS_ASCTIME64\fR 4
+.IX Xref "HAS_ASCTIME64"
+.IX Item "HAS_ASCTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`asctime64\*(C'\fR () routine is
+available to do the 64bit variant of asctime ()
+.ie n .IP """HAS_CTIME_R""" 4
+.el .IP \f(CWHAS_CTIME_R\fR 4
+.IX Xref "HAS_CTIME_R"
+.IX Item "HAS_CTIME_R"
+This symbol, if defined, indicates that the \f(CW\*(C`ctime_r\*(C'\fR routine
+is available to ctime re-entrantly.
+.ie n .IP """HAS_CTIME64""" 4
+.el .IP \f(CWHAS_CTIME64\fR 4
+.IX Xref "HAS_CTIME64"
+.IX Item "HAS_CTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`ctime64\*(C'\fR () routine is
+available to do the 64bit variant of ctime ()
+.ie n .IP """HAS_DIFFTIME""" 4
+.el .IP \f(CWHAS_DIFFTIME\fR 4
+.IX Xref "HAS_DIFFTIME"
+.IX Item "HAS_DIFFTIME"
+This symbol, if defined, indicates that the \f(CW\*(C`difftime\*(C'\fR routine is
+available.
+.ie n .IP """HAS_DIFFTIME64""" 4
+.el .IP \f(CWHAS_DIFFTIME64\fR 4
+.IX Xref "HAS_DIFFTIME64"
+.IX Item "HAS_DIFFTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`difftime64\*(C'\fR () routine is
+available to do the 64bit variant of difftime ()
+.ie n .IP """HAS_FUTIMES""" 4
+.el .IP \f(CWHAS_FUTIMES\fR 4
+.IX Xref "HAS_FUTIMES"
+.IX Item "HAS_FUTIMES"
+This symbol, if defined, indicates that the \f(CW\*(C`futimes\*(C'\fR routine is
+available to change file descriptor time stamps with \f(CW\*(C`struct timevals\*(C'\fR.
+.ie n .IP """HAS_GETITIMER""" 4
+.el .IP \f(CWHAS_GETITIMER\fR 4
+.IX Xref "HAS_GETITIMER"
+.IX Item "HAS_GETITIMER"
+This symbol, if defined, indicates that the \f(CW\*(C`getitimer\*(C'\fR routine is
+available to return interval timers.
+.ie n .IP """HAS_GETTIMEOFDAY""" 4
+.el .IP \f(CWHAS_GETTIMEOFDAY\fR 4
+.IX Xref "HAS_GETTIMEOFDAY"
+.IX Item "HAS_GETTIMEOFDAY"
+This symbol, if defined, indicates that the \f(CWgettimeofday()\fR system
+call is available for a sub-second accuracy clock. Usually, the file
+\&\fIsys/resource.h\fR needs to be included (see \f(CW"I_SYS_RESOURCE"\fR).
+The type "Timeval" should be used to refer to "\f(CW\*(C`struct timeval\*(C'\fR".
+.ie n .IP """HAS_GMTIME_R""" 4
+.el .IP \f(CWHAS_GMTIME_R\fR 4
+.IX Xref "HAS_GMTIME_R"
+.IX Item "HAS_GMTIME_R"
+This symbol, if defined, indicates that the \f(CW\*(C`gmtime_r\*(C'\fR routine
+is available to gmtime re-entrantly.
+.ie n .IP """HAS_GMTIME64""" 4
+.el .IP \f(CWHAS_GMTIME64\fR 4
+.IX Xref "HAS_GMTIME64"
+.IX Item "HAS_GMTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`gmtime64\*(C'\fR () routine is
+available to do the 64bit variant of gmtime ()
+.ie n .IP """HAS_LOCALTIME_R""" 4
+.el .IP \f(CWHAS_LOCALTIME_R\fR 4
+.IX Xref "HAS_LOCALTIME_R"
+.IX Item "HAS_LOCALTIME_R"
+This symbol, if defined, indicates that the \f(CW\*(C`localtime_r\*(C'\fR routine
+is available to localtime re-entrantly.
+.ie n .IP """HAS_LOCALTIME64""" 4
+.el .IP \f(CWHAS_LOCALTIME64\fR 4
+.IX Xref "HAS_LOCALTIME64"
+.IX Item "HAS_LOCALTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`localtime64\*(C'\fR () routine is
+available to do the 64bit variant of localtime ()
+.ie n .IP """HAS_MKTIME""" 4
+.el .IP \f(CWHAS_MKTIME\fR 4
+.IX Xref "HAS_MKTIME"
+.IX Item "HAS_MKTIME"
+This symbol, if defined, indicates that the \f(CW\*(C`mktime\*(C'\fR routine is
+available.
+.ie n .IP """HAS_MKTIME64""" 4
+.el .IP \f(CWHAS_MKTIME64\fR 4
+.IX Xref "HAS_MKTIME64"
+.IX Item "HAS_MKTIME64"
+This symbol, if defined, indicates that the \f(CW\*(C`mktime64\*(C'\fR () routine is
+available to do the 64bit variant of mktime ()
+.ie n .IP """HAS_NANOSLEEP""" 4
+.el .IP \f(CWHAS_NANOSLEEP\fR 4
+.IX Xref "HAS_NANOSLEEP"
+.IX Item "HAS_NANOSLEEP"
+This symbol, if defined, indicates that the \f(CW\*(C`nanosleep\*(C'\fR
+system call is available to sleep with 1E\-9 sec accuracy.
+.ie n .IP """HAS_SETITIMER""" 4
+.el .IP \f(CWHAS_SETITIMER\fR 4
+.IX Xref "HAS_SETITIMER"
+.IX Item "HAS_SETITIMER"
+This symbol, if defined, indicates that the \f(CW\*(C`setitimer\*(C'\fR routine is
+available to set interval timers.
+.ie n .IP """HAS_STRFTIME""" 4
+.el .IP \f(CWHAS_STRFTIME\fR 4
+.IX Xref "HAS_STRFTIME"
+.IX Item "HAS_STRFTIME"
+This symbol, if defined, indicates that the \f(CW\*(C`strftime\*(C'\fR routine is
+available to do time formatting.
+.ie n .IP """HAS_TIME""" 4
+.el .IP \f(CWHAS_TIME\fR 4
+.IX Xref "HAS_TIME"
+.IX Item "HAS_TIME"
+This symbol, if defined, indicates that the \f(CWtime()\fR routine exists.
+.ie n .IP """HAS_TIMEGM""" 4
+.el .IP \f(CWHAS_TIMEGM\fR 4
+.IX Xref "HAS_TIMEGM"
+.IX Item "HAS_TIMEGM"
+This symbol, if defined, indicates that the \f(CW\*(C`timegm\*(C'\fR routine is
+available to do the opposite of gmtime ()
+.ie n .IP """HAS_TIMES""" 4
+.el .IP \f(CWHAS_TIMES\fR 4
+.IX Xref "HAS_TIMES"
+.IX Item "HAS_TIMES"
+This symbol, if defined, indicates that the \f(CWtimes()\fR routine exists.
+Note that this became obsolete on some systems (\f(CW\*(C`SUNOS\*(C'\fR), which now
+use \f(CWgetrusage()\fR. It may be necessary to include \fIsys/times.h\fR.
+.ie n .IP """HAS_TM_TM_GMTOFF""" 4
+.el .IP \f(CWHAS_TM_TM_GMTOFF\fR 4
+.IX Xref "HAS_TM_TM_GMTOFF"
+.IX Item "HAS_TM_TM_GMTOFF"
+This symbol, if defined, indicates to the C program that
+the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_gmtoff\*(C'\fR field.
+.ie n .IP """HAS_TM_TM_ZONE""" 4
+.el .IP \f(CWHAS_TM_TM_ZONE\fR 4
+.IX Xref "HAS_TM_TM_ZONE"
+.IX Item "HAS_TM_TM_ZONE"
+This symbol, if defined, indicates to the C program that
+the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_zone\*(C'\fR field.
+.ie n .IP """HAS_TZNAME""" 4
+.el .IP \f(CWHAS_TZNAME\fR 4
+.IX Xref "HAS_TZNAME"
+.IX Item "HAS_TZNAME"
+This symbol, if defined, indicates that the \f(CW\*(C`tzname[]\*(C'\fR array is
+available to access timezone names.
+.ie n .IP """HAS_USLEEP""" 4
+.el .IP \f(CWHAS_USLEEP\fR 4
+.IX Xref "HAS_USLEEP"
+.IX Item "HAS_USLEEP"
+This symbol, if defined, indicates that the \f(CW\*(C`usleep\*(C'\fR routine is
+available to let the process sleep on a sub-second accuracy.
+.ie n .IP """HAS_USLEEP_PROTO""" 4
+.el .IP \f(CWHAS_USLEEP_PROTO\fR 4
+.IX Xref "HAS_USLEEP_PROTO"
+.IX Item "HAS_USLEEP_PROTO"
+This symbol, if defined, indicates that the system provides
+a prototype for the \f(CWusleep()\fR function.  Otherwise, it is up
+to the program to supply one.  A good guess is
+.Sp
+.Vb 1
+\& extern int usleep(useconds_t);
+.Ve
+.ie n .IP """I_TIME""" 4
+.el .IP \f(CWI_TIME\fR 4
+.IX Xref "I_TIME"
+.IX Item "I_TIME"
+This symbol is always defined, and indicates to the C program that
+it should include \fItime.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_TIME
+\&     #include <time.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """I_UTIME""" 4
+.el .IP \f(CWI_UTIME\fR 4
+.IX Xref "I_UTIME"
+.IX Item "I_UTIME"
+This symbol, if defined, indicates to the C program that it should
+include \fIutime.h\fR.
+.RS 4
+.Sp
+.Vb 3
+\& #ifdef I_UTIME
+\&     #include <utime.h>
+\& #endif
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LOCALTIME_MAX""" 4
+.el .IP \f(CWLOCALTIME_MAX\fR 4
+.IX Xref "LOCALTIME_MAX"
+.IX Item "LOCALTIME_MAX"
+This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
+the system function localtime () accepts, and defaults to 0
+.ie n .IP """LOCALTIME_MIN""" 4
+.el .IP \f(CWLOCALTIME_MIN\fR 4
+.IX Xref "LOCALTIME_MIN"
+.IX Item "LOCALTIME_MIN"
+This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
+the system function localtime () accepts, and defaults to 0
+.ie n .IP """LOCALTIME_R_NEEDS_TZSET""" 4
+.el .IP \f(CWLOCALTIME_R_NEEDS_TZSET\fR 4
+.IX Xref "LOCALTIME_R_NEEDS_TZSET"
+.IX Item "LOCALTIME_R_NEEDS_TZSET"
+Many libc's \f(CW\*(C`localtime_r\*(C'\fR implementations do not call tzset,
+making them differ from \f(CWlocaltime()\fR, and making timezone
+changes using $\f(CW\*(C`ENV\*(C'\fR{TZ} without explicitly calling tzset
+impossible. This symbol makes us call tzset before \f(CW\*(C`localtime_r\*(C'\fR
+.ie n .IP """LOCALTIME_R_PROTO""" 4
+.el .IP \f(CWLOCALTIME_R_PROTO\fR 4
+.IX Xref "LOCALTIME_R_PROTO"
+.IX Item "LOCALTIME_R_PROTO"
+This symbol encodes the prototype of \f(CW\*(C`localtime_r\*(C'\fR.
+It is zero if \f(CW\*(C`d_localtime_r\*(C'\fR is undef, and one of the
+\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_localtime_r\*(C'\fR
+is defined.
+.ie n .IP """L_R_TZSET""" 4
+.el .IP \f(CWL_R_TZSET\fR 4
+.IX Xref "L_R_TZSET"
+.IX Item "L_R_TZSET"
+If \f(CWlocaltime_r()\fR needs tzset, it is defined in this define
+.ie n .IP """mini_mktime""" 4
+.el .IP \f(CWmini_mktime\fR 4
+.IX Xref "mini_mktime"
+.IX Item "mini_mktime"
+normalise \f(CW\*(C`struct\ tm\*(C'\fR values without the \fBlocaltime()\fR semantics (and
+overhead) of \fBmktime()\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  mini_mktime(struct tm *ptm)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_strftime""" 4
+.el .IP \f(CWmy_strftime\fR 4
+.IX Xref "my_strftime"
+.IX Item "my_strftime"
+\&\fBstrftime()\fR, but with a different API so that the return value is a pointer
+to the formatted result (which MUST be arranged to be FREED BY THE
+CALLER).  This allows this function to increase the buffer size as needed,
+so that the caller doesn't have to worry about that.
+.Sp
+On failure it returns NULL.
+.Sp
+Note that yday and wday effectively are ignored by this function, as
+\&\fBmini_mktime()\fR overwrites them.
+.Sp
+Also note that it is always executed in the underlying \f(CW\*(C`LC_TIME\*(C'\fR locale of
+the program, giving results based on that locale.
+.RS 4
+.Sp
+.Vb 3
+\& char *  my_strftime(const char *fmt, int sec, int min, int hour,
+\&                     int mday, int mon, int year, int wday,
+\&                     int yday, int isdst)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """switch_to_global_locale""" 4
+.el .IP \f(CWswitch_to_global_locale\fR 4
+.IX Xref "switch_to_global_locale"
+.IX Item "switch_to_global_locale"
+This function copies the locale state of the calling thread into the program's
+global locale, and converts the thread to use that global locale.
+.Sp
+It is intended so that Perl can safely be used with C libraries that access the
+global locale and which can't be converted to not access it.  Effectively, this
+means libraries that call \f(CWsetlocale(3)\fR on non-Windows systems.  (For
+portability, it is a good idea to use it on Windows as well.)
+.Sp
+A downside of using it is that it disables the services that Perl provides to
+hide locale gotchas from your code.  The service you most likely will miss
+regards the radix character (decimal point) in floating point numbers.  Code
+executed after this function is called can no longer just assume that this
+character is correct for the current circumstances.
+.Sp
+To return to Perl control, and restart the gotcha prevention services, call
+\&\f(CW"sync_locale"\fR.  Behavior is undefined for any pure Perl code that executes
+while the switch is in effect.
+.Sp
+The global locale and the per-thread locales are independent.  As long as just
+one thread converts to the global locale, everything works smoothly.  But if
+more than one does, they can easily interfere with each other, and races are
+likely.  On Windows systems prior to Visual Studio 15 (at which point Microsoft
+fixed a bug), races can occur (even if only one thread has been converted to
+the global locale), but only if you use the following operations:
+.RS 4
+.IP POSIX::localeconv 4
+.IX Item "POSIX::localeconv"
+.PD 0
+.ie n .IP "I18N::Langinfo, items ""CRNCYSTR"" and ""THOUSEP""" 4
+.el .IP "I18N::Langinfo, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
+.IX Item "I18N::Langinfo, items CRNCYSTR and THOUSEP"
+.ie n .IP """Perl_langinfo"" in perlapi, items ""CRNCYSTR"" and ""THOUSEP""" 4
+.el .IP """Perl_langinfo"" in perlapi, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
+.IX Item """Perl_langinfo"" in perlapi, items CRNCYSTR and THOUSEP"
+.RE
+.RS 4
+.PD
+.Sp
+The first item is not fixable (except by upgrading to a later Visual Studio
+release), but it would be possible to work around the latter two items by
+having Perl change its algorithm for calculating these to use Windows API
+functions (likely \f(CW\*(C`GetNumberFormat\*(C'\fR and \f(CW\*(C`GetCurrencyFormat\*(C'\fR); patches
+welcome.
+.Sp
+XS code should never call plain \f(CW\*(C`setlocale\*(C'\fR, but should instead be converted
+to either call \f(CW\*(C`Perl_setlocale\*(C'\fR (which is a drop-in
+for the system \f(CW\*(C`setlocale\*(C'\fR) or use the methods given in perlcall to call
+\&\f(CW\*(C`POSIX::setlocale\*(C'\fR.  Either one will transparently properly
+handle all cases of single\- vs multi-thread, POSIX 2008\-supported or not.
+.Sp
+.Vb 1
+\& void  switch_to_global_locale()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sync_locale""" 4
+.el .IP \f(CWsync_locale\fR 4
+.IX Xref "sync_locale"
+.IX Item "sync_locale"
+This function copies the state of the program global locale into the calling
+thread, and converts that thread to using per-thread locales, if it wasn't
+already, and the platform supports them.  The LC_NUMERIC locale is toggled into
+the standard state (using the C locale's conventions), if not within the
+lexical scope of \f(CW\*(C`use\ locale\*(C'\fR.
+.Sp
+Perl will now consider itself to have control of the locale.
+.Sp
+Since unthreaded perls have only a global locale, this function is a no-op
+without threads.
+.Sp
+This function is intended for use with C libraries that do locale manipulation.
+It allows Perl to accommodate the use of them.  Call this function before
+transferring back to Perl space so that it knows what state the C code has left
+things in.
+.Sp
+XS code should not manipulate the locale on its own.  Instead,
+\&\f(CW\*(C`Perl_setlocale\*(C'\fR can be used at any time to query or
+change the locale (though changing the locale is antisocial and dangerous on
+multi-threaded systems that don't have multi-thread safe locale operations.
+(See "Multi-threaded operation" in perllocale).
+.Sp
+Using the libc \f(CWsetlocale(3)\fR function should be avoided.  Nevertheless,
+certain non-Perl libraries called from XS, do call it, and their behavior may
+not be able to be changed.  This function, along with
+\&\f(CW"switch_to_global_locale"\fR, can be used to get seamless behavior in these
+circumstances, as long as only one thread is involved.
+.Sp
+If the library has an option to turn off its locale manipulation, doing that is
+preferable to using this mechanism.  \f(CW\*(C`Gtk\*(C'\fR is such a library.
+.Sp
+The return value is a boolean: TRUE if the global locale at the time of call
+was in effect for the caller; and FALSE if a per-thread locale was in effect.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sync_locale()
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Typedef names"
+.IX Header "Typedef names"
+.ie n .IP """DB_Hash_t""" 4
+.el .IP \f(CWDB_Hash_t\fR 4
+.IX Xref "DB_Hash_t"
+.IX Item "DB_Hash_t"
+This symbol contains the type of the prefix structure element
+in the \fIdb.h\fR header file.  In older versions of DB, it was
+int, while in newer ones it is \f(CW\*(C`size_t\*(C'\fR.
+.ie n .IP """DB_Prefix_t""" 4
+.el .IP \f(CWDB_Prefix_t\fR 4
+.IX Xref "DB_Prefix_t"
+.IX Item "DB_Prefix_t"
+This symbol contains the type of the prefix structure element
+in the \fIdb.h\fR header file.  In older versions of DB, it was
+int, while in newer ones it is \f(CW\*(C`u_int32_t\*(C'\fR.
+.ie n .IP """Direntry_t""" 4
+.el .IP \f(CWDirentry_t\fR 4
+.IX Xref "Direntry_t"
+.IX Item "Direntry_t"
+This symbol is set to '\f(CW\*(C`struct direct\*(C'\fR' or '\f(CW\*(C`struct dirent\*(C'\fR' depending on
+whether dirent is available or not. You should use this pseudo type to
+portably declare your directory entries.
+.ie n .IP """Fpos_t""" 4
+.el .IP \f(CWFpos_t\fR 4
+.IX Xref "Fpos_t"
+.IX Item "Fpos_t"
+This symbol holds the type used to declare file positions in libc.
+It can be \f(CW\*(C`fpos_t\*(C'\fR, long, uint, etc... It may be necessary to include
+\&\fIsys/types.h\fR to get any typedef'ed information.
+.ie n .IP """Free_t""" 4
+.el .IP \f(CWFree_t\fR 4
+.IX Xref "Free_t"
+.IX Item "Free_t"
+This variable contains the return type of \f(CWfree()\fR.  It is usually
+void, but occasionally int.
+.ie n .IP """Gid_t""" 4
+.el .IP \f(CWGid_t\fR 4
+.IX Xref "Gid_t"
+.IX Item "Gid_t"
+This symbol holds the return type of \f(CWgetgid()\fR and the type of
+argument to \f(CWsetrgid()\fR and related functions.  Typically,
+it is the type of group ids in the kernel. It can be int, ushort,
+\&\f(CW\*(C`gid_t\*(C'\fR, etc... It may be necessary to include \fIsys/types.h\fR to get
+any typedef'ed information.
+.ie n .IP """Gid_t_f""" 4
+.el .IP \f(CWGid_t_f\fR 4
+.IX Xref "Gid_t_f"
+.IX Item "Gid_t_f"
+This symbol defines the format string used for printing a \f(CW\*(C`Gid_t\*(C'\fR.
+.ie n .IP """Gid_t_sign""" 4
+.el .IP \f(CWGid_t_sign\fR 4
+.IX Xref "Gid_t_sign"
+.IX Item "Gid_t_sign"
+This symbol holds the signedness of a \f(CW\*(C`Gid_t\*(C'\fR.
+1 for unsigned, \-1 for signed.
+.ie n .IP """Gid_t_size""" 4
+.el .IP \f(CWGid_t_size\fR 4
+.IX Xref "Gid_t_size"
+.IX Item "Gid_t_size"
+This symbol holds the size of a \f(CW\*(C`Gid_t\*(C'\fR in bytes.
+.ie n .IP """Groups_t""" 4
+.el .IP \f(CWGroups_t\fR 4
+.IX Xref "Groups_t"
+.IX Item "Groups_t"
+This symbol holds the type used for the second argument to
+\&\f(CWgetgroups()\fR and \f(CWsetgroups()\fR.  Usually, this is the same as
+gidtype (\f(CW\*(C`gid_t\*(C'\fR) , but sometimes it isn't.
+It can be int, ushort, \f(CW\*(C`gid_t\*(C'\fR, etc...
+It may be necessary to include \fIsys/types.h\fR to get any
+typedef'ed information.  This is only required if you have
+\&\f(CWgetgroups()\fR or \f(CWsetgroups()\fR..
+.ie n .IP """Malloc_t""" 4
+.el .IP \f(CWMalloc_t\fR 4
+.IX Xref "Malloc_t"
+.IX Item "Malloc_t"
+This symbol is the type of pointer returned by malloc and realloc.
+.ie n .IP """Mmap_t""" 4
+.el .IP \f(CWMmap_t\fR 4
+.IX Xref "Mmap_t"
+.IX Item "Mmap_t"
+This symbol holds the return type of the \f(CWmmap()\fR system call
+(and simultaneously the type of the first argument).
+Usually set to 'void *' or '\f(CW\*(C`caddr_t\*(C'\fR'.
+.ie n .IP """Mode_t""" 4
+.el .IP \f(CWMode_t\fR 4
+.IX Xref "Mode_t"
+.IX Item "Mode_t"
+This symbol holds the type used to declare file modes
+for systems calls.  It is usually \f(CW\*(C`mode_t\*(C'\fR, but may be
+int or unsigned short.  It may be necessary to include \fIsys/types.h\fR
+to get any typedef'ed information.
+.ie n .IP """Netdb_hlen_t""" 4
+.el .IP \f(CWNetdb_hlen_t\fR 4
+.IX Xref "Netdb_hlen_t"
+.IX Item "Netdb_hlen_t"
+This symbol holds the type used for the 2nd argument
+to \f(CWgethostbyaddr()\fR.
+.ie n .IP """Netdb_host_t""" 4
+.el .IP \f(CWNetdb_host_t\fR 4
+.IX Xref "Netdb_host_t"
+.IX Item "Netdb_host_t"
+This symbol holds the type used for the 1st argument
+to \f(CWgethostbyaddr()\fR.
+.ie n .IP """Netdb_name_t""" 4
+.el .IP \f(CWNetdb_name_t\fR 4
+.IX Xref "Netdb_name_t"
+.IX Item "Netdb_name_t"
+This symbol holds the type used for the argument to
+\&\f(CWgethostbyname()\fR.
+.ie n .IP """Netdb_net_t""" 4
+.el .IP \f(CWNetdb_net_t\fR 4
+.IX Xref "Netdb_net_t"
+.IX Item "Netdb_net_t"
+This symbol holds the type used for the 1st argument to
+\&\f(CWgetnetbyaddr()\fR.
+.ie n .IP """Off_t""" 4
+.el .IP \f(CWOff_t\fR 4
+.IX Xref "Off_t"
+.IX Item "Off_t"
+This symbol holds the type used to declare offsets in the kernel.
+It can be int, long, \f(CW\*(C`off_t\*(C'\fR, etc... It may be necessary to include
+\&\fIsys/types.h\fR to get any typedef'ed information.
+.ie n .IP """Off_t_size""" 4
+.el .IP \f(CWOff_t_size\fR 4
+.IX Xref "Off_t_size"
+.IX Item "Off_t_size"
+This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
+.ie n .IP """Pid_t""" 4
+.el .IP \f(CWPid_t\fR 4
+.IX Xref "Pid_t"
+.IX Item "Pid_t"
+This symbol holds the type used to declare process ids in the kernel.
+It can be int, uint, \f(CW\*(C`pid_t\*(C'\fR, etc... It may be necessary to include
+\&\fIsys/types.h\fR to get any typedef'ed information.
+.ie n .IP """Rand_seed_t""" 4
+.el .IP \f(CWRand_seed_t\fR 4
+.IX Xref "Rand_seed_t"
+.IX Item "Rand_seed_t"
+This symbol defines the type of the argument of the
+random seed function.
+.ie n .IP """Select_fd_set_t""" 4
+.el .IP \f(CWSelect_fd_set_t\fR 4
+.IX Xref "Select_fd_set_t"
+.IX Item "Select_fd_set_t"
+This symbol holds the type used for the 2nd, 3rd, and 4th
+arguments to select.  Usually, this is '\f(CW\*(C`fd_set\*(C'\fR *', if \f(CW\*(C`HAS_FD_SET\*(C'\fR
+is defined, and 'int *' otherwise.  This is only useful if you
+have \f(CWselect()\fR, of course.
+.ie n .IP """Shmat_t""" 4
+.el .IP \f(CWShmat_t\fR 4
+.IX Xref "Shmat_t"
+.IX Item "Shmat_t"
+This symbol holds the return type of the \f(CWshmat()\fR system call.
+Usually set to 'void *' or 'char *'.
+.ie n .IP """Signal_t""" 4
+.el .IP \f(CWSignal_t\fR 4
+.IX Xref "Signal_t"
+.IX Item "Signal_t"
+This symbol's value is either "void" or "int", corresponding to the
+appropriate return type of a signal handler.  Thus, you can declare
+a signal handler using "\f(CW\*(C`Signal_t\*(C'\fR (*handler)()", and define the
+handler using "\f(CW\*(C`Signal_t\*(C'\fR \f(CWhandler(sig)\fR".
+.ie n .IP """Size_t""" 4
+.el .IP \f(CWSize_t\fR 4
+.IX Xref "Size_t"
+.IX Item "Size_t"
+This symbol holds the type used to declare length parameters
+for string functions.  It is usually \f(CW\*(C`size_t\*(C'\fR, but may be
+unsigned long, int, etc.  It may be necessary to include
+\&\fIsys/types.h\fR to get any typedef'ed information.
+.ie n .IP """Size_t_size""" 4
+.el .IP \f(CWSize_t_size\fR 4
+.IX Xref "Size_t_size"
+.IX Item "Size_t_size"
+This symbol holds the size of a \f(CW\*(C`Size_t\*(C'\fR in bytes.
+.ie n .IP """Sock_size_t""" 4
+.el .IP \f(CWSock_size_t\fR 4
+.IX Xref "Sock_size_t"
+.IX Item "Sock_size_t"
+This symbol holds the type used for the size argument of
+various socket calls (just the base type, not the pointer-to).
+.ie n .IP """SSize_t""" 4
+.el .IP \f(CWSSize_t\fR 4
+.IX Xref "SSize_t"
+.IX Item "SSize_t"
+This symbol holds the type used by functions that return
+a count of bytes or an error condition.  It must be a signed type.
+It is usually \f(CW\*(C`ssize_t\*(C'\fR, but may be long or int, etc.
+It may be necessary to include \fIsys/types.h\fR or \fIunistd.h\fR
+to get any typedef'ed information.
+We will pick a type such that \f(CWsizeof(SSize_t)\fR == \f(CWsizeof(Size_t)\fR.
+.ie n .IP """Time_t""" 4
+.el .IP \f(CWTime_t\fR 4
+.IX Xref "Time_t"
+.IX Item "Time_t"
+This symbol holds the type returned by \f(CWtime()\fR. It can be long,
+or \f(CW\*(C`time_t\*(C'\fR on \f(CW\*(C`BSD\*(C'\fR sites (in which case \fIsys/types.h\fR should be
+included).
+.ie n .IP """Uid_t""" 4
+.el .IP \f(CWUid_t\fR 4
+.IX Xref "Uid_t"
+.IX Item "Uid_t"
+This symbol holds the type used to declare user ids in the kernel.
+It can be int, ushort, \f(CW\*(C`uid_t\*(C'\fR, etc... It may be necessary to include
+\&\fIsys/types.h\fR to get any typedef'ed information.
+.ie n .IP """Uid_t_f""" 4
+.el .IP \f(CWUid_t_f\fR 4
+.IX Xref "Uid_t_f"
+.IX Item "Uid_t_f"
+This symbol defines the format string used for printing a \f(CW\*(C`Uid_t\*(C'\fR.
+.ie n .IP """Uid_t_sign""" 4
+.el .IP \f(CWUid_t_sign\fR 4
+.IX Xref "Uid_t_sign"
+.IX Item "Uid_t_sign"
+This symbol holds the signedness of a \f(CW\*(C`Uid_t\*(C'\fR.
+1 for unsigned, \-1 for signed.
+.ie n .IP """Uid_t_size""" 4
+.el .IP \f(CWUid_t_size\fR 4
+.IX Xref "Uid_t_size"
+.IX Item "Uid_t_size"
+This symbol holds the size of a \f(CW\*(C`Uid_t\*(C'\fR in bytes.
+.SH "Unicode Support"
+.IX Xref "UNICODE_DISALLOW_ABOVE_31_BIT UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE UNICODE_DISALLOW_ILLEGAL_INTERCHANGE UNICODE_DISALLOW_NONCHAR UNICODE_DISALLOW_PERL_EXTENDED UNICODE_DISALLOW_SUPER UNICODE_DISALLOW_SURROGATE UNICODE_WARN_ABOVE_31_BIT UNICODE_WARN_ILLEGAL_C9_INTERCHANGE UNICODE_WARN_ILLEGAL_INTERCHANGE UNICODE_WARN_NONCHAR UNICODE_WARN_PERL_EXTENDED UNICODE_WARN_SUPER UNICODE_WARN_SURROGATE UNI_DISPLAY_BACKSLASH UNI_DISPLAY_BACKSPACE UNI_DISPLAY_ISPRINT UNI_DISPLAY_QQ UNI_DISPLAY_REGEX UTF8_CHECK_ONLY UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE UTF8_DISALLOW_ILLEGAL_INTERCHANGE UTF8_DISALLOW_NONCHAR UTF8_DISALLOW_PERL_EXTENDED UTF8_DISALLOW_SUPER UTF8_DISALLOW_SURROGATE UTF8_GOT_CONTINUATION UTF8_GOT_EMPTY UTF8_GOT_LONG UTF8_GOT_NONCHAR UTF8_GOT_NON_CONTINUATION UTF8_GOT_OVERFLOW UTF8_GOT_PERL_EXTENDED UTF8_GOT_SHORT UTF8_GOT_SUPER UTF8_GOT_SURROGATE UTF8_WARN_ILLEGAL_C9_INTERCHANGE UTF8_WARN_ILLEGAL_INTERCHANGE UTF8_WARN_NONCHAR UTF8_WARN_PERL_EXTENDED UTF8_WARN_SUPER UTF8_WARN_SURROGATE"
+.IX Header "Unicode Support"
+"Unicode Support" in perlguts has an introduction to this API.
+.PP
+See also \f(CW"Character classification"\fR,
+\&\f(CW"Character case changing"\fR,
+and \f(CW"String Handling"\fR.
+Various functions outside this section also work specially with
+Unicode.  Search for the string "utf8" in this document.
+.ie n .IP """BOM_UTF8""" 4
+.el .IP \f(CWBOM_UTF8\fR 4
+.IX Xref "BOM_UTF8"
+.IX Item "BOM_UTF8"
+This is a macro that evaluates to a string constant of the  UTF\-8 bytes that
+define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl
+is compiled on.  This allows code to use a mnemonic for this character that
+works on both ASCII and EBCDIC platforms.
+\&\f(CW\*(C`sizeof(BOM_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
+bytes.
+.ie n .IP """bytes_cmp_utf8""" 4
+.el .IP \f(CWbytes_cmp_utf8\fR 4
+.IX Xref "bytes_cmp_utf8"
+.IX Item "bytes_cmp_utf8"
+Compares the sequence of characters (stored as octets) in \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`blen\*(C'\fR with the
+sequence of characters (stored as UTF\-8)
+in \f(CW\*(C`u\*(C'\fR, \f(CW\*(C`ulen\*(C'\fR.  Returns 0 if they are
+equal, \-1 or \-2 if the first string is less than the second string, +1 or +2
+if the first string is greater than the second string.
+.Sp
+\&\-1 or +1 is returned if the shorter string was identical to the start of the
+longer string.  \-2 or +2 is returned if
+there was a difference between characters
+within the strings.
+.RS 4
+.Sp
+.Vb 2
+\& int  bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
+\&                     STRLEN ulen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """bytes_from_utf8""" 4
+.el .IP \f(CWbytes_from_utf8\fR 4
+.IX Xref "bytes_from_utf8"
+.IX Item "bytes_from_utf8"
+NOTE: \f(CW\*(C`bytes_from_utf8\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Converts a potentially UTF\-8 encoded string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR into native
+byte encoding.  On input, the boolean \f(CW*is_utf8p\fR gives whether or not \f(CW\*(C`s\*(C'\fR is
+actually encoded in UTF\-8.
+.Sp
+Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-destructive of
+the input string.
+.Sp
+Do nothing if \f(CW*is_utf8p\fR is 0, or if there are code points in the string
+not expressible in native byte encoding.  In these cases, \f(CW*is_utf8p\fR and
+\&\f(CW*lenp\fR are unchanged, and the return value is the original \f(CW\*(C`s\*(C'\fR.
+.Sp
+Otherwise, \f(CW*is_utf8p\fR is set to 0, and the return value is a pointer to a
+newly created string containing a downgraded copy of \f(CW\*(C`s\*(C'\fR, and whose length is
+returned in \f(CW*lenp\fR, updated.  The new string is \f(CW\*(C`NUL\*(C'\fR\-terminated.  The
+caller is responsible for arranging for the memory used by this string to get
+freed.
+.Sp
+Upon successful return, the number of variants in the string can be computed by
+having saved the value of \f(CW*lenp\fR before the call, and subtracting the
+after-call value of \f(CW*lenp\fR from it.
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """bytes_to_utf8""" 4
+.el .IP \f(CWbytes_to_utf8\fR 4
+.IX Xref "bytes_to_utf8"
+.IX Item "bytes_to_utf8"
+NOTE: \f(CW\*(C`bytes_to_utf8\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR bytes from the native encoding into
+UTF\-8.
+Returns a pointer to the newly-created string, and sets \f(CW*lenp\fR to
+reflect the new length in bytes.  The caller is responsible for arranging for
+the memory used by this string to get freed.
+.Sp
+Upon successful return, the number of variants in the string can be computed by
+having saved the value of \f(CW*lenp\fR before the call, and subtracting it from the
+after-call value of \f(CW*lenp\fR.
+.Sp
+A \f(CW\*(C`NUL\*(C'\fR character will be written after the end of the string.
+.Sp
+If you want to convert to UTF\-8 from encodings other than
+the native (Latin1 or EBCDIC),
+see "sv_recode_to_utf8"().
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  bytes_to_utf8(const U8 *s, STRLEN *lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """DO_UTF8""" 4
+.el .IP \f(CWDO_UTF8\fR 4
+.IX Xref "DO_UTF8"
+.IX Item "DO_UTF8"
+Returns a bool giving whether or not the PV in \f(CW\*(C`sv\*(C'\fR is to be treated as being
+encoded in UTF\-8.
+.Sp
+You should use this \fIafter\fR a call to \f(CWSvPV()\fR or one of its variants, in
+case any call to string overloading updates the internal UTF\-8 encoding flag.
+.RS 4
+.Sp
+.Vb 1
+\& bool  DO_UTF8(SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """foldEQ_utf8""" 4
+.el .IP \f(CWfoldEQ_utf8\fR 4
+.IX Xref "foldEQ_utf8"
+.IX Item "foldEQ_utf8"
+Returns true if the leading portions of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR (either or
+both of which may be in UTF\-8) are the same case-insensitively; false
+otherwise.  How far into the strings to compare is determined by other input
+parameters.
+.Sp
+If \f(CW\*(C`u1\*(C'\fR is true, the string \f(CW\*(C`s1\*(C'\fR is assumed to be in UTF\-8\-encoded Unicode;
+otherwise it is assumed to be in native 8\-bit encoding.  Correspondingly for
+\&\f(CW\*(C`u2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
+.Sp
+If the byte length \f(CW\*(C`l1\*(C'\fR is non-zero, it says how far into \f(CW\*(C`s1\*(C'\fR to check for
+fold equality.  In other words, \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR will be used as a goal to reach.
+The scan will not be considered to be a match unless the goal is reached, and
+scanning won't continue past that goal.  Correspondingly for \f(CW\*(C`l2\*(C'\fR with respect
+to \f(CW\*(C`s2\*(C'\fR.
+.Sp
+If \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR and the pointer it points to is not \f(CW\*(C`NULL\*(C'\fR, that
+pointer is considered an end pointer to the position 1 byte past the maximum
+point in \f(CW\*(C`s1\*(C'\fR beyond which scanning will not continue under any circumstances.
+(This routine assumes that UTF\-8 encoded input strings are not malformed;
+malformed input can cause it to read past \f(CW\*(C`pe1\*(C'\fR).  This means that if both
+\&\f(CW\*(C`l1\*(C'\fR and \f(CW\*(C`pe1\*(C'\fR are specified, and \f(CW\*(C`pe1\*(C'\fR is less than \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR, the match
+will never be successful because it can never
+get as far as its goal (and in fact is asserted against).  Correspondingly for
+\&\f(CW\*(C`pe2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
+.Sp
+At least one of \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR must have a goal (at least one of \f(CW\*(C`l1\*(C'\fR and
+\&\f(CW\*(C`l2\*(C'\fR must be non-zero), and if both do, both have to be
+reached for a successful match.   Also, if the fold of a character is multiple
+characters, all of them must be matched (see tr21 reference below for
+\&'folding').
+.Sp
+Upon a successful match, if \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR,
+it will be set to point to the beginning of the \fInext\fR character of \f(CW\*(C`s1\*(C'\fR
+beyond what was matched.  Correspondingly for \f(CW\*(C`pe2\*(C'\fR and \f(CW\*(C`s2\*(C'\fR.
+.Sp
+For case-insensitiveness, the "casefolding" of Unicode is used
+instead of upper/lowercasing both the characters, see
+<https://www.unicode.org/reports/tr21/> (Case Mappings).
+.RS 4
+.Sp
+.Vb 2
+\& I32  foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
+\&                  const char *s2, char **pe2, UV l2, bool u2)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_ascii_string""" 4
+.el .IP \f(CWis_ascii_string\fR 4
+.IX Xref "is_ascii_string"
+.IX Item "is_ascii_string"
+This is a misleadingly-named synonym for "is_utf8_invariant_string".
+On ASCII-ish platforms, the name isn't misleading: the ASCII-range characters
+are exactly the UTF\-8 invariants.  But EBCDIC machines have more invariants
+than just the ASCII characters, so \f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred.
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_ascii_string(const U8 * const s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isC9_STRICT_UTF8_CHAR""" 4
+.el .IP \f(CWisC9_STRICT_UTF8_CHAR\fR 4
+.IX Xref "isC9_STRICT_UTF8_CHAR"
+.IX Item "isC9_STRICT_UTF8_CHAR"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some
+Unicode non-surrogate code point; otherwise it evaluates to 0.  If non-zero,
+the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
+representation.  Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to
+form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined.
+.Sp
+The largest acceptable code point is the Unicode maximum 0x10FFFF.  This
+differs from \f(CW"isSTRICT_UTF8_CHAR"\fR only in that it accepts non-character
+code points.  This corresponds to
+Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>.
+which said that non-character code points are merely discouraged rather than
+completely forbidden in open interchange.  See
+"Noncharacter code points" in perlunicode.
+.Sp
+Use \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8; and
+\&\f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
+.Sp
+Use \f(CW"is_c9strict_utf8_string"\fR, \f(CW"is_c9strict_utf8_string_loc"\fR, and
+\&\f(CW"is_c9strict_utf8_string_loclen"\fR to check entire strings.
+.RS 4
+.Sp
+.Vb 2
+\& Size_t  isC9_STRICT_UTF8_CHAR(const U8 * const s0,
+\&                               const U8 * const e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_c9strict_utf8_string""" 4
+.el .IP \f(CWis_c9strict_utf8_string\fR 4
+.IX Xref "is_c9strict_utf8_string"
+.IX Item "is_c9strict_utf8_string"
+Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
+UTF\-8\-encoded string that conforms to
+Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>;
+otherwise it returns FALSE.  If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using
+\&\f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded
+\&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte).  Note that all
+characters being ASCII constitute 'a valid UTF\-8 string'.
+.Sp
+This function returns FALSE for strings containing any code points above the
+Unicode max of 0x10FFFF or surrogate code points, but accepts non-character
+code points per
+Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>.
+.Sp
+See also
+\&\f(CW"is_utf8_invariant_string"\fR,
+\&\f(CW"is_utf8_invariant_string_loc"\fR,
+\&\f(CW"is_utf8_string"\fR,
+\&\f(CW"is_utf8_string_flags"\fR,
+\&\f(CW"is_utf8_string_loc"\fR,
+\&\f(CW"is_utf8_string_loc_flags"\fR,
+\&\f(CW"is_utf8_string_loclen"\fR,
+\&\f(CW"is_utf8_string_loclen_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
+\&\f(CW"is_strict_utf8_string"\fR,
+\&\f(CW"is_strict_utf8_string_loc"\fR,
+\&\f(CW"is_strict_utf8_string_loclen"\fR,
+\&\f(CW"is_c9strict_utf8_string_loc"\fR,
+and
+\&\f(CW"is_c9strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_c9strict_utf8_string(const U8 *s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_c9strict_utf8_string_loc""" 4
+.el .IP \f(CWis_c9strict_utf8_string_loc\fR 4
+.IX Xref "is_c9strict_utf8_string_loc"
+.IX Item "is_c9strict_utf8_string_loc"
+Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in
+the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_c9strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
+\&                                   const U8 **ep)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_c9strict_utf8_string_loclen""" 4
+.el .IP \f(CWis_c9strict_utf8_string_loclen\fR 4
+.IX Xref "is_c9strict_utf8_string_loclen"
+.IX Item "is_c9strict_utf8_string_loclen"
+Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in
+the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 encoded
+characters in the \f(CW\*(C`el\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_c9strict_utf8_string_loc"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
+\&                                      const U8 **ep, STRLEN *el)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_invariant_string""" 4
+.el .IP \f(CWis_invariant_string\fR 4
+.IX Xref "is_invariant_string"
+.IX Item "is_invariant_string"
+This is a somewhat misleadingly-named synonym for "is_utf8_invariant_string".
+\&\f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred, as it indicates under what conditions
+the string is invariant.
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_invariant_string(const U8 * const s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isSTRICT_UTF8_CHAR""" 4
+.el .IP \f(CWisSTRICT_UTF8_CHAR\fR 4
+.IX Xref "isSTRICT_UTF8_CHAR"
+.IX Item "isSTRICT_UTF8_CHAR"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some
+Unicode code point completely acceptable for open interchange between all
+applications; otherwise it evaluates to 0.  If non-zero, the value gives how
+many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation.  Any
+bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code
+point in \f(CW\*(C`s\*(C'\fR, are not examined.
+.Sp
+The largest acceptable code point is the Unicode maximum 0x10FFFF, and must not
+be a surrogate nor a non-character code point.  Thus this excludes any code
+point from Perl's extended UTF\-8.
+.Sp
+This is used to efficiently decide if the next few bytes in \f(CW\*(C`s\*(C'\fR is
+legal Unicode-acceptable UTF\-8 for a single character.
+.Sp
+Use \f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum
+#9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable
+code points; \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8;
+and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
+.Sp
+Use \f(CW"is_strict_utf8_string"\fR, \f(CW"is_strict_utf8_string_loc"\fR, and
+\&\f(CW"is_strict_utf8_string_loclen"\fR to check entire strings.
+.RS 4
+.Sp
+.Vb 2
+\& Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
+\&                            const U8 * const e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_strict_utf8_string""" 4
+.el .IP \f(CWis_strict_utf8_string\fR 4
+.IX Xref "is_strict_utf8_string"
+.IX Item "is_strict_utf8_string"
+Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
+UTF\-8\-encoded string that is fully interchangeable by any application using
+Unicode rules; otherwise it returns FALSE.  If \f(CW\*(C`len\*(C'\fR is 0, it will be
+calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR
+can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR
+byte).  Note that all characters being ASCII constitute 'a valid UTF\-8 string'.
+.Sp
+This function returns FALSE for strings containing any
+code points above the Unicode max of 0x10FFFF, surrogate code points, or
+non-character code points.
+.Sp
+See also
+\&\f(CW"is_utf8_invariant_string"\fR,
+\&\f(CW"is_utf8_invariant_string_loc"\fR,
+\&\f(CW"is_utf8_string"\fR,
+\&\f(CW"is_utf8_string_flags"\fR,
+\&\f(CW"is_utf8_string_loc"\fR,
+\&\f(CW"is_utf8_string_loc_flags"\fR,
+\&\f(CW"is_utf8_string_loclen"\fR,
+\&\f(CW"is_utf8_string_loclen_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
+\&\f(CW"is_strict_utf8_string_loc"\fR,
+\&\f(CW"is_strict_utf8_string_loclen"\fR,
+\&\f(CW"is_c9strict_utf8_string"\fR,
+\&\f(CW"is_c9strict_utf8_string_loc"\fR,
+and
+\&\f(CW"is_c9strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_strict_utf8_string(const U8 *s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_strict_utf8_string_loc""" 4
+.el .IP \f(CWis_strict_utf8_string_loc\fR 4
+.IX Xref "is_strict_utf8_string_loc"
+.IX Item "is_strict_utf8_string_loc"
+Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_strict_utf8_string_loc(const U8 *s, STRLEN len,
+\&                                 const U8 **ep)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_strict_utf8_string_loclen""" 4
+.el .IP \f(CWis_strict_utf8_string_loclen\fR 4
+.IX Xref "is_strict_utf8_string_loclen"
+.IX Item "is_strict_utf8_string_loclen"
+Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
+encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_strict_utf8_string_loc"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
+\&                                    const U8 **ep, STRLEN *el)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isUTF8_CHAR""" 4
+.el .IP \f(CWisUTF8_CHAR\fR 4
+.IX Xref "isUTF8_CHAR"
+.IX Item "isUTF8_CHAR"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl,
+that represents some code point; otherwise it evaluates to 0.  If non-zero, the
+value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
+representation.  Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to
+form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined.
+.Sp
+The code point can be any that will fit in an IV on this machine, using Perl's
+extension to official UTF\-8 to represent those higher than the Unicode maximum
+of 0x10FFFF.  That means that this macro is used to efficiently decide if the
+next few bytes in \f(CW\*(C`s\*(C'\fR is legal UTF\-8 for a single character.
+.Sp
+Use \f(CW"isSTRICT_UTF8_CHAR"\fR to restrict the acceptable code points to those
+defined by Unicode to be fully interchangeable across applications;
+\&\f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum
+#9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable
+code points; and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
+.Sp
+Use \f(CW"is_utf8_string"\fR, \f(CW"is_utf8_string_loc"\fR, and
+\&\f(CW"is_utf8_string_loclen"\fR to check entire strings.
+.Sp
+Note also that a UTF\-8 "invariant" character (i.e. ASCII on non-EBCDIC
+machines) is a valid UTF\-8 character.
+.RS 4
+.Sp
+.Vb 1
+\& Size_t  isUTF8_CHAR(const U8 * const s0, const U8 * const e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_char_buf""" 4
+.el .IP \f(CWis_utf8_char_buf\fR 4
+.IX Xref "is_utf8_char_buf"
+.IX Item "is_utf8_char_buf"
+This is identical to the macro "isUTF8_CHAR" in perlapi.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isUTF8_CHAR_flags""" 4
+.el .IP \f(CWisUTF8_CHAR_flags\fR 4
+.IX Xref "isUTF8_CHAR_flags"
+.IX Item "isUTF8_CHAR_flags"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl,
+that represents some code point, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR;
+otherwise it evaluates to 0.  If non-zero, the value gives how many bytes
+starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation.  Any bytes remaining
+before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code point in \f(CW\*(C`s\*(C'\fR,
+are not examined.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"isUTF8_CHAR"\fR;
+if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results
+as \f(CW"isSTRICT_UTF8_CHAR"\fR;
+and if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives
+the same results as \f(CW"isC9_STRICT_UTF8_CHAR"\fR.
+Otherwise \f(CW\*(C`flags\*(C'\fR may be any combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags
+understood by \f(CW"utf8n_to_uvchr"\fR, with the same meanings.
+.Sp
+The three alternative macros are for the most commonly needed validations; they
+are likely to run somewhat faster than this more general one, as they can be
+inlined into your code.
+.Sp
+Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
+"is_utf8_string_loclen_flags" to check entire strings.
+.RS 4
+.Sp
+.Vb 2
+\& Size_t  isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e,
+\&                           const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_fixed_width_buf_flags""" 4
+.el .IP \f(CWis_utf8_fixed_width_buf_flags\fR 4
+.IX Xref "is_utf8_fixed_width_buf_flags"
+.IX Item "is_utf8_fixed_width_buf_flags"
+Returns TRUE if the fixed-width buffer starting at \f(CW\*(C`s\*(C'\fR with length \f(CW\*(C`len\*(C'\fR
+is entirely valid UTF\-8, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR;
+otherwise it returns FALSE.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR is 0, any well-formed UTF\-8, as extended by Perl, is accepted
+without restriction.  If the final few bytes of the buffer do not form a
+complete code point, this will return TRUE anyway, provided that
+\&\f(CW"is_utf8_valid_partial_char_flags"\fR returns TRUE for them.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR in non-zero, it can be any combination of the
+\&\f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR, and with the
+same meanings.
+.Sp
+This function differs from \f(CW"is_utf8_string_flags"\fR only in that the latter
+returns FALSE if the final few bytes of the string don't form a complete code
+point.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_fixed_width_buf_flags(const U8 * const s,
+\&                                     STRLEN len, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_fixed_width_buf_loc_flags""" 4
+.el .IP \f(CWis_utf8_fixed_width_buf_loc_flags\fR 4
+.IX Xref "is_utf8_fixed_width_buf_loc_flags"
+.IX Item "is_utf8_fixed_width_buf_loc_flags"
+Like \f(CW"is_utf8_fixed_width_buf_flags"\fR but stores the location of the
+failure in the \f(CW\*(C`ep\*(C'\fR pointer.  If the function returns TRUE, \f(CW*ep\fR will point
+to the beginning of any partial character at the end of the buffer; if there is
+no partial character \f(CW*ep\fR will contain \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR.
+.Sp
+See also \f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR.
+.RS 4
+.Sp
+.Vb 3
+\& bool  is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
+\&                                         STRLEN len, const U8 **ep,
+\&                                         const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_fixed_width_buf_loclen_flags""" 4
+.el .IP \f(CWis_utf8_fixed_width_buf_loclen_flags\fR 4
+.IX Xref "is_utf8_fixed_width_buf_loclen_flags"
+.IX Item "is_utf8_fixed_width_buf_loclen_flags"
+Like \f(CW"is_utf8_fixed_width_buf_loc_flags"\fR but stores the number of
+complete, valid characters found in the \f(CW\*(C`el\*(C'\fR pointer.
+.RS 4
+.Sp
+.Vb 5
+\& bool  is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
+\&                                            STRLEN len,
+\&                                            const U8 **ep,
+\&                                            STRLEN *el,
+\&                                            const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_invariant_string""" 4
+.el .IP \f(CWis_utf8_invariant_string\fR 4
+.IX Xref "is_utf8_invariant_string"
+.IX Item "is_utf8_invariant_string"
+Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR are the same
+regardless of the UTF\-8 encoding of the string (or UTF-EBCDIC encoding on
+EBCDIC machines); otherwise it returns FALSE.  That is, it returns TRUE if they
+are UTF\-8 invariant.  On ASCII-ish machines, all the ASCII characters and only
+the ASCII characters fit this definition.  On EBCDIC machines, the ASCII-range
+characters are invariant, but so also are the C1 controls.
+.Sp
+If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using \f(CWstrlen(s)\fR, (which means if you
+use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to
+have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
+.Sp
+See also
+\&\f(CW"is_utf8_string"\fR,
+\&\f(CW"is_utf8_string_flags"\fR,
+\&\f(CW"is_utf8_string_loc"\fR,
+\&\f(CW"is_utf8_string_loc_flags"\fR,
+\&\f(CW"is_utf8_string_loclen"\fR,
+\&\f(CW"is_utf8_string_loclen_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
+\&\f(CW"is_strict_utf8_string"\fR,
+\&\f(CW"is_strict_utf8_string_loc"\fR,
+\&\f(CW"is_strict_utf8_string_loclen"\fR,
+\&\f(CW"is_c9strict_utf8_string"\fR,
+\&\f(CW"is_c9strict_utf8_string_loc"\fR,
+and
+\&\f(CW"is_c9strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_utf8_invariant_string(const U8 * const s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_invariant_string_loc""" 4
+.el .IP \f(CWis_utf8_invariant_string_loc\fR 4
+.IX Xref "is_utf8_invariant_string_loc"
+.IX Item "is_utf8_invariant_string_loc"
+Like \f(CW"is_utf8_invariant_string"\fR but upon failure, stores the location of
+the first UTF\-8 variant character in the \f(CW\*(C`ep\*(C'\fR pointer; if all characters are
+UTF\-8 invariant, this function does not change the contents of \f(CW*ep\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_invariant_string_loc(const U8 * const s, STRLEN len,
+\&                                    const U8 **ep)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string""" 4
+.el .IP \f(CWis_utf8_string\fR 4
+.IX Xref "is_utf8_string"
+.IX Item "is_utf8_string"
+Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
+Perl\-extended\-UTF\-8 string; returns FALSE otherwise.  If \f(CW\*(C`len\*(C'\fR is 0, it will
+be calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR
+can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR
+byte).  Note that all characters being ASCII constitute 'a valid UTF\-8 string'.
+.Sp
+This function considers Perl's extended UTF\-8 to be valid.  That means that
+code points above Unicode, surrogates, and non-character code points are
+considered valid by this function.  Use \f(CW"is_strict_utf8_string"\fR,
+\&\f(CW"is_c9strict_utf8_string"\fR, or \f(CW"is_utf8_string_flags"\fR to restrict what
+code points are considered valid.
+.Sp
+See also
+\&\f(CW"is_utf8_invariant_string"\fR,
+\&\f(CW"is_utf8_invariant_string_loc"\fR,
+\&\f(CW"is_utf8_string_loc"\fR,
+\&\f(CW"is_utf8_string_loclen"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_utf8_string(const U8 *s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string_flags""" 4
+.el .IP \f(CWis_utf8_string_flags\fR 4
+.IX Xref "is_utf8_string_flags"
+.IX Item "is_utf8_string_flags"
+Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
+UTF\-8 string, subject to the restrictions imposed by \f(CW\*(C`flags\*(C'\fR;
+returns FALSE otherwise.  If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated
+using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have
+embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte).  Note
+that all characters being ASCII constitute 'a valid UTF\-8 string'.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"is_utf8_string"\fR; if
+\&\f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results
+as \f(CW"is_strict_utf8_string"\fR; and if \f(CW\*(C`flags\*(C'\fR is
+\&\f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives the same results as
+\&\f(CW"is_c9strict_utf8_string"\fR.  Otherwise \f(CW\*(C`flags\*(C'\fR may be any
+combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags understood by
+\&\f(CW"utf8n_to_uvchr"\fR, with the same meanings.
+.Sp
+See also
+\&\f(CW"is_utf8_invariant_string"\fR,
+\&\f(CW"is_utf8_invariant_string_loc"\fR,
+\&\f(CW"is_utf8_string"\fR,
+\&\f(CW"is_utf8_string_loc"\fR,
+\&\f(CW"is_utf8_string_loc_flags"\fR,
+\&\f(CW"is_utf8_string_loclen"\fR,
+\&\f(CW"is_utf8_string_loclen_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
+\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
+\&\f(CW"is_strict_utf8_string"\fR,
+\&\f(CW"is_strict_utf8_string_loc"\fR,
+\&\f(CW"is_strict_utf8_string_loclen"\fR,
+\&\f(CW"is_c9strict_utf8_string"\fR,
+\&\f(CW"is_c9strict_utf8_string_loc"\fR,
+and
+\&\f(CW"is_c9strict_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_string_flags(const U8 *s, STRLEN len,
+\&                            const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string_loc""" 4
+.el .IP \f(CWis_utf8_string_loc\fR 4
+.IX Xref "is_utf8_string_loc"
+.IX Item "is_utf8_string_loc"
+Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_utf8_string_loclen"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_string_loc(const U8 *s, const STRLEN len,
+\&                          const U8 **ep)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string_loc_flags""" 4
+.el .IP \f(CWis_utf8_string_loc_flags\fR 4
+.IX Xref "is_utf8_string_loc_flags"
+.IX Item "is_utf8_string_loc_flags"
+Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_utf8_string_loclen_flags"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_string_loc_flags(const U8 *s, STRLEN len,
+\&                                const U8 **ep, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string_loclen""" 4
+.el .IP \f(CWis_utf8_string_loclen\fR 4
+.IX Xref "is_utf8_string_loclen"
+.IX Item "is_utf8_string_loclen"
+Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
+encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_utf8_string_loc"\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_string_loclen(const U8 *s, STRLEN len,
+\&                             const U8 **ep, STRLEN *el)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_string_loclen_flags""" 4
+.el .IP \f(CWis_utf8_string_loclen_flags\fR 4
+.IX Xref "is_utf8_string_loclen_flags"
+.IX Item "is_utf8_string_loclen_flags"
+Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the
+case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
+"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
+encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
+.Sp
+See also \f(CW"is_utf8_string_loc_flags"\fR.
+.RS 4
+.Sp
+.Vb 3
+\& bool  is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
+\&                                   const U8 **ep, STRLEN *el,
+\&                                   const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_valid_partial_char""" 4
+.el .IP \f(CWis_utf8_valid_partial_char\fR 4
+.IX Xref "is_utf8_valid_partial_char"
+.IX Item "is_utf8_valid_partial_char"
+Returns 0 if the sequence of bytes starting at \f(CW\*(C`s\*(C'\fR and looking no further than
+\&\f(CW\*(C`e\ \-\ 1\*(C'\fR is the UTF\-8 encoding, as extended by Perl, for one or more code
+points.  Otherwise, it returns 1 if there exists at least one non-empty
+sequence of bytes that when appended to sequence \f(CW\*(C`s\*(C'\fR, starting at position
+\&\f(CW\*(C`e\*(C'\fR causes the entire sequence to be the well-formed UTF\-8 of some code point;
+otherwise returns 0.
+.Sp
+In other words this returns TRUE if \f(CW\*(C`s\*(C'\fR points to a partial UTF\-8\-encoded code
+point.
+.Sp
+This is useful when a fixed-length buffer is being tested for being well-formed
+UTF\-8, but the final few bytes in it don't comprise a full character; that is,
+it is split somewhere in the middle of the final code point's UTF\-8
+representation.  (Presumably when the buffer is refreshed with the next chunk
+of data, the new first bytes will complete the partial code point.)   This
+function is used to verify that the final bytes in the current buffer are in
+fact the legal beginning of some code point, so that if they aren't, the
+failure can be signalled without having to wait for the next read.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_utf8_valid_partial_char(const U8 * const s0,
+\&                                  const U8 * const e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_valid_partial_char_flags""" 4
+.el .IP \f(CWis_utf8_valid_partial_char_flags\fR 4
+.IX Xref "is_utf8_valid_partial_char_flags"
+.IX Item "is_utf8_valid_partial_char_flags"
+Like \f(CW"is_utf8_valid_partial_char"\fR, it returns a boolean giving whether
+or not the input is a valid UTF\-8 encoded partial character, but it takes an
+extra parameter, \f(CW\*(C`flags\*(C'\fR, which can further restrict which code points are
+considered valid.
+.Sp
+If \f(CW\*(C`flags\*(C'\fR is 0, this behaves identically to
+\&\f(CW"is_utf8_valid_partial_char"\fR.  Otherwise \f(CW\*(C`flags\*(C'\fR can be any combination
+of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR.  If
+there is any sequence of bytes that can complete the input partial character in
+such a way that a non-prohibited character is formed, the function returns
+TRUE; otherwise FALSE.  Non character code points cannot be determined based on
+partial character input.  But many  of the other possible excluded types can be
+determined from just the first one or two bytes.
+.RS 4
+.Sp
+.Vb 3
+\& bool  is_utf8_valid_partial_char_flags(const U8 * const s0,
+\&                                        const U8 * const e,
+\&                                        const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LATIN1_TO_NATIVE""" 4
+.el .IP \f(CWLATIN1_TO_NATIVE\fR 4
+.IX Xref "LATIN1_TO_NATIVE"
+.IX Item "LATIN1_TO_NATIVE"
+Returns the native  equivalent of the input Latin\-1 code point (including ASCII
+and control characters) given by \f(CW\*(C`ch\*(C'\fR.  Thus, \f(CWLATIN1_TO_NATIVE(66)\fR on
+EBCDIC platforms returns 194.  These each represent the character \f(CW"B"\fR on
+their respective platforms.  On ASCII platforms no conversion is needed, so
+this macro expands to just its input, adding no time nor space requirements to
+the implementation.
+.Sp
+For conversion of code points potentially larger than will fit in a character,
+use "UNI_TO_NATIVE".
+.RS 4
+.Sp
+.Vb 1
+\& U8  LATIN1_TO_NATIVE(U8 ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """NATIVE_TO_LATIN1""" 4
+.el .IP \f(CWNATIVE_TO_LATIN1\fR 4
+.IX Xref "NATIVE_TO_LATIN1"
+.IX Item "NATIVE_TO_LATIN1"
+Returns the Latin\-1 (including ASCII and control characters) equivalent of the
+input native code point given by \f(CW\*(C`ch\*(C'\fR.  Thus, \f(CWNATIVE_TO_LATIN1(193)\fR on
+EBCDIC platforms returns 65.  These each represent the character \f(CW"A"\fR on
+their respective platforms.  On ASCII platforms no conversion is needed, so
+this macro expands to just its input, adding no time nor space requirements to
+the implementation.
+.Sp
+For conversion of code points potentially larger than will fit in a character,
+use "NATIVE_TO_UNI".
+.RS 4
+.Sp
+.Vb 1
+\& U8  NATIVE_TO_LATIN1(U8 ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """NATIVE_TO_UNI""" 4
+.el .IP \f(CWNATIVE_TO_UNI\fR 4
+.IX Xref "NATIVE_TO_UNI"
+.IX Item "NATIVE_TO_UNI"
+Returns the Unicode  equivalent of the input native code point given by \f(CW\*(C`ch\*(C'\fR.
+Thus, \f(CWNATIVE_TO_UNI(195)\fR on EBCDIC platforms returns 67.  These each
+represent the character \f(CW"C"\fR on their respective platforms.  On ASCII
+platforms no conversion is needed, so this macro expands to just its input,
+adding no time nor space requirements to the implementation.
+.RS 4
+.Sp
+.Vb 1
+\& UV  NATIVE_TO_UNI(UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pv_uni_display""" 4
+.el .IP \f(CWpv_uni_display\fR 4
+.IX Xref "pv_uni_display"
+.IX Item "pv_uni_display"
+Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the UTF\-8 encoded string
+\&\f(CW\*(C`spv\*(C'\fR, length \f(CW\*(C`len\*(C'\fR, the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes
+long (if longer, the rest is truncated and \f(CW"..."\fR will be appended).
+.Sp
+The \f(CW\*(C`flags\*(C'\fR argument can have \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR set to display
+\&\f(CWisPRINT()\fRable characters as themselves, \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR
+to display the \f(CW\*(C`\e\e[nrfta\e\e]\*(C'\fR as the backslashed versions (like \f(CW"\en"\fR)
+(\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR is preferred over \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR for \f(CW"\e\e"\fR).
+\&\f(CW\*(C`UNI_DISPLAY_QQ\*(C'\fR (and its alias \f(CW\*(C`UNI_DISPLAY_REGEX\*(C'\fR) have both
+\&\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR and \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR turned on.
+.Sp
+Additionally, there is now \f(CW\*(C`UNI_DISPLAY_BACKSPACE\*(C'\fR which allows \f(CW\*(C`\eb\*(C'\fR for a
+backspace, but only when \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR also is set.
+.Sp
+The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
+.Sp
+See also "sv_uni_display".
+.RS 4
+.Sp
+.Vb 2
+\& char *  pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
+\&                        STRLEN pvlim, UV flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """REPLACEMENT_CHARACTER_UTF8""" 4
+.el .IP \f(CWREPLACEMENT_CHARACTER_UTF8\fR 4
+.IX Xref "REPLACEMENT_CHARACTER_UTF8"
+.IX Item "REPLACEMENT_CHARACTER_UTF8"
+This is a macro that evaluates to a string constant of the  UTF\-8 bytes that
+define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl
+is compiled on.  This allows code to use a mnemonic for this character that
+works on both ASCII and EBCDIC platforms.
+\&\f(CW\*(C`sizeof(REPLACEMENT_CHARACTER_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
+bytes.
+.ie n .IP """sv_cat_decode""" 4
+.el .IP \f(CWsv_cat_decode\fR 4
+.IX Xref "sv_cat_decode"
+.IX Item "sv_cat_decode"
+\&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, the PV of \f(CW\*(C`ssv\*(C'\fR is
+assumed to be octets in that encoding and decoding the input starts
+from the position which \f(CW\*(C`(PV\ +\ *offset)\*(C'\fR pointed to.  \f(CW\*(C`dsv\*(C'\fR will be
+concatenated with the decoded UTF\-8 string from \f(CW\*(C`ssv\*(C'\fR.  Decoding will terminate
+when the string \f(CW\*(C`tstr\*(C'\fR appears in decoding output or the input ends on
+the PV of \f(CW\*(C`ssv\*(C'\fR.  The value which \f(CW\*(C`offset\*(C'\fR points will be modified
+to the last input position on \f(CW\*(C`ssv\*(C'\fR.
+.Sp
+Returns TRUE if the terminator was found, else returns FALSE.
+.RS 4
+.Sp
+.Vb 2
+\& bool  sv_cat_decode(SV *dsv, SV *encoding, SV *ssv, int *offset,
+\&                     char *tstr, int tlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_recode_to_utf8""" 4
+.el .IP \f(CWsv_recode_to_utf8\fR 4
+.IX Xref "sv_recode_to_utf8"
+.IX Item "sv_recode_to_utf8"
+\&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, on entry the PV
+of \f(CW\*(C`sv\*(C'\fR is assumed to be octets in that encoding, and \f(CW\*(C`sv\*(C'\fR
+will be converted into Unicode (and UTF\-8).
+.Sp
+If \f(CW\*(C`sv\*(C'\fR already is UTF\-8 (or if it is not \f(CW\*(C`POK\*(C'\fR), or if \f(CW\*(C`encoding\*(C'\fR
+is not a reference, nothing is done to \f(CW\*(C`sv\*(C'\fR.  If \f(CW\*(C`encoding\*(C'\fR is not
+an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen.
+(See encoding and Encode.)
+.Sp
+The PV of \f(CW\*(C`sv\*(C'\fR is returned.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_recode_to_utf8(SV *sv, SV *encoding)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_uni_display""" 4
+.el .IP \f(CWsv_uni_display\fR 4
+.IX Xref "sv_uni_display"
+.IX Item "sv_uni_display"
+Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the scalar \f(CW\*(C`sv\*(C'\fR,
+the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes long
+(if longer, the rest is truncated and "..." will be appended).
+.Sp
+The \f(CW\*(C`flags\*(C'\fR argument is as in "pv_uni_display"().
+.Sp
+The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNICODE_IS_NONCHAR""" 4
+.el .IP \f(CWUNICODE_IS_NONCHAR\fR 4
+.IX Xref "UNICODE_IS_NONCHAR"
+.IX Item "UNICODE_IS_NONCHAR"
+Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode
+non-character code points
+.RS 4
+.Sp
+.Vb 1
+\& bool  UNICODE_IS_NONCHAR(const UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNICODE_IS_REPLACEMENT""" 4
+.el .IP \f(CWUNICODE_IS_REPLACEMENT\fR 4
+.IX Xref "UNICODE_IS_REPLACEMENT"
+.IX Item "UNICODE_IS_REPLACEMENT"
+Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is the Unicode REPLACEMENT
+CHARACTER
+.RS 4
+.Sp
+.Vb 1
+\& bool  UNICODE_IS_REPLACEMENT(const UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNICODE_IS_SUPER""" 4
+.el .IP \f(CWUNICODE_IS_SUPER\fR 4
+.IX Xref "UNICODE_IS_SUPER"
+.IX Item "UNICODE_IS_SUPER"
+Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is above the maximum legal Unicode
+code point of U+10FFFF.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UNICODE_IS_SUPER(const UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNICODE_IS_SURROGATE""" 4
+.el .IP \f(CWUNICODE_IS_SURROGATE\fR 4
+.IX Xref "UNICODE_IS_SURROGATE"
+.IX Item "UNICODE_IS_SURROGATE"
+Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode surrogate
+code points
+.RS 4
+.Sp
+.Vb 1
+\& bool  UNICODE_IS_SURROGATE(const UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNICODE_REPLACEMENT""" 4
+.el .IP \f(CWUNICODE_REPLACEMENT\fR 4
+.IX Xref "UNICODE_REPLACEMENT"
+.IX Item "UNICODE_REPLACEMENT"
+Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT CHARACTER
+.ie n .IP """UNI_TO_NATIVE""" 4
+.el .IP \f(CWUNI_TO_NATIVE\fR 4
+.IX Xref "UNI_TO_NATIVE"
+.IX Item "UNI_TO_NATIVE"
+Returns the native  equivalent of the input Unicode code point  given by \f(CW\*(C`ch\*(C'\fR.
+Thus, \f(CWUNI_TO_NATIVE(68)\fR on EBCDIC platforms returns 196.  These each
+represent the character \f(CW"D"\fR on their respective platforms.  On ASCII
+platforms no conversion is needed, so this macro expands to just its input,
+adding no time nor space requirements to the implementation.
+.RS 4
+.Sp
+.Vb 1
+\& UV  UNI_TO_NATIVE(UV ch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_CHK_SKIP""" 4
+.el .IP \f(CWUTF8_CHK_SKIP\fR 4
+.IX Xref "UTF8_CHK_SKIP"
+.IX Item "UTF8_CHK_SKIP"
+This is a safer version of \f(CW"UTF8SKIP"\fR, but still not as safe as
+\&\f(CW"UTF8_SAFE_SKIP"\fR.  This version doesn't blindly assume that the input
+string pointed to by \f(CW\*(C`s\*(C'\fR is well-formed, but verifies that there isn't a NUL
+terminating character before the expected end of the next character in \f(CW\*(C`s\*(C'\fR.
+The length \f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR returns stops just before any such NUL.
+.Sp
+Perl tends to add NULs, as an insurance policy, after the end of strings in
+SV's, so it is likely that using this macro will prevent inadvertent reading
+beyond the end of the input buffer, even if it is malformed UTF\-8.
+.Sp
+This macro is intended to be used by XS modules where the inputs could be
+malformed, and it isn't feasible to restructure to use the safer
+\&\f(CW"UTF8_SAFE_SKIP"\fR, for example when interfacing with a C library.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  UTF8_CHK_SKIP(char* s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_distance""" 4
+.el .IP \f(CWutf8_distance\fR 4
+.IX Xref "utf8_distance"
+.IX Item "utf8_distance"
+Returns the number of UTF\-8 characters between the UTF\-8 pointers \f(CW\*(C`a\*(C'\fR
+and \f(CW\*(C`b\*(C'\fR.
+.Sp
+WARNING: use only if you *know* that the pointers point inside the
+same UTF\-8 buffer.
+.RS 4
+.Sp
+.Vb 1
+\& IV  utf8_distance(const U8 *a, const U8 *b)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_hop""" 4
+.el .IP \f(CWutf8_hop\fR 4
+.IX Xref "utf8_hop"
+.IX Item "utf8_hop"
+Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either
+forward (if \f(CW\*(C`off\*(C'\fR is positive) or backward (if negative).  \f(CW\*(C`s\*(C'\fR does not need
+to be pointing to the starting byte of a character.  If it isn't, one count of
+\&\f(CW\*(C`off\*(C'\fR will be used up to get to the start of the next character for forward
+hops, and to the start of the current character for negative ones.
+.Sp
+WARNING: Prefer "utf8_hop_safe" to this one.
+.Sp
+Do NOT use this function unless you \fBknow\fR \f(CW\*(C`off\*(C'\fR is within
+the UTF\-8 data pointed to by \f(CW\*(C`s\*(C'\fR \fBand\fR that on entry \f(CW\*(C`s\*(C'\fR is aligned
+on the first byte of a character or just after the last byte of a character.
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  utf8_hop(const U8 *s, SSize_t off)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_hop_back""" 4
+.el .IP \f(CWutf8_hop_back\fR 4
+.IX Xref "utf8_hop_back"
+.IX Item "utf8_hop_back"
+Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
+backward.  \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a
+character.  If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that
+start.
+.Sp
+\&\f(CW\*(C`off\*(C'\fR must be non-positive.
+.Sp
+\&\f(CW\*(C`s\*(C'\fR must be after or equal to \f(CW\*(C`start\*(C'\fR.
+.Sp
+When moving backward it will not move before \f(CW\*(C`start\*(C'\fR.
+.Sp
+Will not exceed this limit even if the string is not valid "UTF\-8".
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_hop_forward""" 4
+.el .IP \f(CWutf8_hop_forward\fR 4
+.IX Xref "utf8_hop_forward"
+.IX Item "utf8_hop_forward"
+Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
+forward.  \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a
+character.  If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to the
+start of the next character.
+.Sp
+\&\f(CW\*(C`off\*(C'\fR must be non-negative.
+.Sp
+\&\f(CW\*(C`s\*(C'\fR must be before or equal to \f(CW\*(C`end\*(C'\fR.
+.Sp
+When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR.
+.Sp
+Will not exceed this limit even if the string is not valid "UTF\-8".
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_hop_safe""" 4
+.el .IP \f(CWutf8_hop_safe\fR 4
+.IX Xref "utf8_hop_safe"
+.IX Item "utf8_hop_safe"
+Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
+either forward or backward.  \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting
+byte of a character.  If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get
+to the start of the next character for forward hops, and to the start of the
+current character for negative ones.
+.Sp
+When moving backward it will not move before \f(CW\*(C`start\*(C'\fR.
+.Sp
+When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR.
+.Sp
+Will not exceed those limits even if the string is not valid "UTF\-8".
+.RS 4
+.Sp
+.Vb 2
+\& U8 *  utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
+\&                     const U8 *end)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_IS_INVARIANT""" 4
+.el .IP \f(CWUTF8_IS_INVARIANT\fR 4
+.IX Xref "UTF8_IS_INVARIANT"
+.IX Item "UTF8_IS_INVARIANT"
+Evaluates to 1 if the byte \f(CW\*(C`c\*(C'\fR represents the same character when encoded in
+UTF\-8 as when not; otherwise evaluates to 0.  UTF\-8 invariant characters can be
+copied as-is when converting to/from UTF\-8, saving time.
+.Sp
+In spite of the name, this macro gives the correct result if the input string
+from which \f(CW\*(C`c\*(C'\fR comes is not encoded in UTF\-8.
+.Sp
+See \f(CW"UVCHR_IS_INVARIANT"\fR for checking if a UV is invariant.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UTF8_IS_INVARIANT(char c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_IS_NONCHAR""" 4
+.el .IP \f(CWUTF8_IS_NONCHAR\fR 4
+.IX Xref "UTF8_IS_NONCHAR"
+.IX Item "UTF8_IS_NONCHAR"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one
+of the Unicode non-character code points; otherwise it evaluates to 0.  If
+non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
+point's representation.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_IS_REPLACEMENT""" 4
+.el .IP \f(CWUTF8_IS_REPLACEMENT\fR 4
+.IX Xref "UTF8_IS_REPLACEMENT"
+.IX Item "UTF8_IS_REPLACEMENT"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents the
+Unicode REPLACEMENT CHARACTER; otherwise it evaluates to 0.  If non-zero, the
+value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
+representation.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_IS_SUPER""" 4
+.el .IP \f(CWUTF8_IS_SUPER\fR 4
+.IX Xref "UTF8_IS_SUPER"
+.IX Item "UTF8_IS_SUPER"
+Recall that Perl recognizes an extension to UTF\-8 that can encode code
+points larger than the ones defined by Unicode, which are 0..0x10FFFF.
+.Sp
+This macro evaluates to non-zero if the first few bytes of the string starting
+at \f(CW\*(C`s\*(C'\fR and looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are from this UTF\-8 extension;
+otherwise it evaluates to 0.  If non-zero, the return is how many bytes
+starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation.
+.Sp
+0 is returned if the bytes are not well-formed extended UTF\-8, or if they
+represent a code point that cannot fit in a UV on the current platform.  Hence
+this macro can give different results when run on a 64\-bit word machine than on
+one with a 32\-bit word size.
+.Sp
+Note that it is illegal in Perl to have code points that are larger than what can
+fit in an IV on the current machine; and illegal in Unicode to have any that
+this macro matches
+.RS 4
+.Sp
+.Vb 1
+\& bool  UTF8_IS_SUPER(const U8 *s, const U8 *e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_IS_SURROGATE""" 4
+.el .IP \f(CWUTF8_IS_SURROGATE\fR 4
+.IX Xref "UTF8_IS_SURROGATE"
+.IX Item "UTF8_IS_SURROGATE"
+Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
+looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one
+of the Unicode surrogate code points; otherwise it evaluates to 0.  If
+non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
+point's representation.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_length""" 4
+.el .IP \f(CWutf8_length\fR 4
+.IX Xref "utf8_length"
+.IX Item "utf8_length"
+Returns the number of characters in the sequence of UTF\-8\-encoded bytes starting
+at \f(CW\*(C`s\*(C'\fR and ending at the byte just before \f(CW\*(C`e\*(C'\fR.  If <s> and <e> point to the
+same place, it returns 0 with no warning raised.
+.Sp
+If \f(CW\*(C`e < s\*(C'\fR or if the scan would end up past \f(CW\*(C`e\*(C'\fR, it raises a UTF8 warning
+and returns the number of valid characters.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  utf8_length(const U8 *s0, const U8 *e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_MAXBYTES""" 4
+.el .IP \f(CWUTF8_MAXBYTES\fR 4
+.IX Xref "UTF8_MAXBYTES"
+.IX Item "UTF8_MAXBYTES"
+The maximum width of a single UTF\-8 encoded character, in bytes.
+.Sp
+NOTE: Strictly speaking Perl's UTF\-8 should not be called UTF\-8 since UTF\-8
+is an encoding of Unicode, and Unicode's upper limit, 0x10FFFF, can be
+expressed with 4 bytes.  However, Perl thinks of UTF\-8 as a way to encode
+non-negative integers in a binary format, even those above Unicode.
+.ie n .IP """UTF8_MAXBYTES_CASE""" 4
+.el .IP \f(CWUTF8_MAXBYTES_CASE\fR 4
+.IX Xref "UTF8_MAXBYTES_CASE"
+.IX Item "UTF8_MAXBYTES_CASE"
+The maximum number of UTF\-8 bytes a single Unicode character can
+uppercase/lowercase/titlecase/fold into.
+.ie n .IP """utf8ness_t""" 4
+.el .IP \f(CWutf8ness_t\fR 4
+.IX Xref "utf8ness_t"
+.IX Item "utf8ness_t"
+This typedef is used by several core functions that return PV strings, to
+indicate the UTF\-8ness of those strings.
+.Sp
+(If you write a new function, you probably should instead return the PV in an
+SV with the UTF\-8 flag of the SV properly set, rather than use this mechanism.)
+.Sp
+The possible values this can be are:
+.RS 4
+.ie n .IP """UTF8NESS_YES""" 4
+.el .IP \f(CWUTF8NESS_YES\fR 4
+.IX Item "UTF8NESS_YES"
+This means the string definitely should be treated as a sequence of
+UTF\-8\-encoded characters.
+.Sp
+Most code that needs to handle this typedef should be of the form:
+.Sp
+.Vb 3
+\& if (utf8ness_flag == UTF8NESS_YES) {
+\&     treat as utf8;  // like turning on an SV UTF\-8 flag
+\& }
+.Ve
+.ie n .IP """UTF8NESS_NO""" 4
+.el .IP \f(CWUTF8NESS_NO\fR 4
+.IX Item "UTF8NESS_NO"
+This means the string definitely should be treated as a sequence of bytes, not
+encoded as UTF\-8.
+.ie n .IP """UTF8NESS_IMMATERIAL""" 4
+.el .IP \f(CWUTF8NESS_IMMATERIAL\fR 4
+.IX Item "UTF8NESS_IMMATERIAL"
+This means it is equally valid to treat the string as bytes, or as UTF\-8
+characters; use whichever way you want.  This happens when the string consists
+entirely of characters which have the same representation whether encoded in
+UTF\-8 or not.
+.ie n .IP """UTF8NESS_UNKNOWN""" 4
+.el .IP \f(CWUTF8NESS_UNKNOWN\fR 4
+.IX Item "UTF8NESS_UNKNOWN"
+This means it is unknown how the string should be treated.  No core function
+will ever return this value to a non-core caller.  Instead, it is used by the
+caller to initialize a variable to a non-legal value.  A typical call will look like:
+.Sp
+.Vb 5
+\& utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN
+\& const char * string = foo(arg1, arg2, ..., &string_is_utf8);
+\& if (string_is_utf8 == UTF8NESS_YES) {
+\&    do something for UTF\-8;
+\& }
+.Ve
+.RE
+.RS 4
+.Sp
+The following relationships hold between the enum values:
+.ie n .IP """0\ <=\ \fIenum\ value\fR\ <=\ UTF8NESS_IMMATERIAL""" 4
+.el .IP "\f(CW0\ <=\ \fR\f(CIenum\ value\fR\f(CW\ <=\ UTF8NESS_IMMATERIAL\fR" 4
+.IX Item "0 <= enum value <= UTF8NESS_IMMATERIAL"
+the string may be treated in code as non\-UTF8
+.ie n .IP """UTF8NESS_IMMATERIAL\ <=\ <\fIenum\ value\fR""" 4
+.el .IP "\f(CWUTF8NESS_IMMATERIAL\ <=\ <\fR\f(CIenum\ value\fR\f(CW\fR" 4
+.IX Item "UTF8NESS_IMMATERIAL <= <enum value"
+the string may be treated in code as encoded in UTF\-8
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8n_to_uvchr""" 4
+.el .IP \f(CWutf8n_to_uvchr\fR 4
+.IX Xref "utf8n_to_uvchr"
+.IX Item "utf8n_to_uvchr"
+THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
+Most code should use "utf8_to_uvchr_buf"() rather than call this
+directly.
+.Sp
+Bottom level UTF\-8 decode routine.
+Returns the native code point value of the first character in the string \f(CW\*(C`s\*(C'\fR,
+which is assumed to be in UTF\-8 (or UTF-EBCDIC) encoding, and no longer than
+\&\f(CW\*(C`curlen\*(C'\fR bytes; \f(CW*retlen\fR (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) will be set to
+the length, in bytes, of that character.
+.Sp
+The value of \f(CW\*(C`flags\*(C'\fR determines the behavior when \f(CW\*(C`s\*(C'\fR does not point to a
+well-formed UTF\-8 character.  If \f(CW\*(C`flags\*(C'\fR is 0, encountering a malformation
+causes zero to be returned and \f(CW*retlen\fR is set so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR)
+is the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed
+character.  Also, if UTF\-8 warnings haven't been lexically disabled, a warning
+is raised.  Some UTF\-8 input sequences may contain multiple malformations.
+This function tries to find every possible one in each call, so multiple
+warnings can be raised for the same sequence.
+.Sp
+Various ALLOW flags can be set in \f(CW\*(C`flags\*(C'\fR to allow (and not warn on)
+individual types of malformations, such as the sequence being overlong (that
+is, when there is a shorter sequence that can express the same code point;
+overlong sequences are expressly forbidden in the UTF\-8 standard due to
+potential security issues).  Another malformation example is the first byte of
+a character not being a legal first byte.  See \fIutf8.h\fR for the list of such
+flags.  Even if allowed, this function generally returns the Unicode
+REPLACEMENT CHARACTER when it encounters a malformation.  There are flags in
+\&\fIutf8.h\fR to override this behavior for the overlong malformations, but don't
+do that except for very specialized purposes.
+.Sp
+The \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag overrides the behavior when a non-allowed (by other
+flags) malformation is found.  If this flag is set, the routine assumes that
+the caller will raise a warning, and this function will silently just set
+\&\f(CW\*(C`retlen\*(C'\fR to \f(CW\-1\fR (cast to \f(CW\*(C`STRLEN\*(C'\fR) and return zero.
+.Sp
+Note that this API requires disambiguation between successful decoding a \f(CW\*(C`NUL\*(C'\fR
+character, and an error return (unless the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag is set), as
+in both cases, 0 is returned, and, depending on the malformation, \f(CW\*(C`retlen\*(C'\fR may
+be set to 1.  To disambiguate, upon a zero return, see if the first byte of
+\&\f(CW\*(C`s\*(C'\fR is 0 as well.  If so, the input was a \f(CW\*(C`NUL\*(C'\fR; if not, the input had an
+error.  Or you can use \f(CW"utf8n_to_uvchr_error"\fR.
+.Sp
+Certain code points are considered problematic.  These are Unicode surrogates,
+Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF.
+By default these are considered regular code points, but certain situations
+warrant special handling for them, which can be specified using the \f(CW\*(C`flags\*(C'\fR
+parameter.  If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, all
+three classes are treated as malformations and handled as such.  The flags
+\&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR, \f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR, and
+\&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR (meaning above the legal Unicode maximum) can be set to
+disallow these categories individually.  \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR
+restricts the allowed inputs to the strict UTF\-8 traditionally defined by
+Unicode.  Use \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR to use the strictness
+definition given by
+Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>.
+The difference between traditional strictness and C9 strictness is that the
+latter does not forbid non-character code points.  (They are still discouraged,
+however.)  For more discussion see "Noncharacter code points" in perlunicode.
+.Sp
+The flags \f(CW\*(C`UTF8_WARN_ILLEGAL_INTERCHANGE\*(C'\fR,
+\&\f(CW\*(C`UTF8_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR, \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR,
+\&\f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR, and \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR will cause warning messages to be
+raised for their respective categories, but otherwise the code points are
+considered valid (not malformations).  To get a category to both be treated as
+a malformation and raise a warning, specify both the WARN and DISALLOW flags.
+(But note that warnings are not raised if lexically disabled nor if
+\&\f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is also specified.)
+.Sp
+Extremely high code points were never specified in any standard, and require an
+extension to UTF\-8 to express, which Perl does.  It is likely that programs
+written in something other than Perl would not be able to read files that
+contain these; nor would Perl understand files written by something that uses a
+different extension.  For these reasons, there is a separate set of flags that
+can warn and/or disallow these extremely high code points, even if other
+above-Unicode ones are accepted.  They are the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR and
+\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR flags.  For more information see
+\&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR.  Of course \f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR will treat all
+above-Unicode code points, including these, as malformations.
+(Note that the Unicode standard considers anything above 0x10FFFF to be
+illegal, but there are standards predating it that allow up to 0x7FFF_FFFF
+(2**31 \-1))
+.Sp
+A somewhat misleadingly named synonym for \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR is
+retained for backward compatibility: \f(CW\*(C`UTF8_WARN_ABOVE_31_BIT\*(C'\fR.  Similarly,
+\&\f(CW\*(C`UTF8_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named
+\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR.  The names are misleading because these flags
+can apply to code points that actually do fit in 31 bits.  This happens on
+EBCDIC platforms, and sometimes when the overlong
+malformation is also present.  The new names accurately
+describe the situation in all cases.
+.Sp
+All other code points corresponding to Unicode characters, including private
+use and those yet to be assigned, are never considered malformed and never
+warn.
+.RS 4
+.Sp
+.Vb 2
+\& UV  utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
+\&                    const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8n_to_uvchr_error""" 4
+.el .IP \f(CWutf8n_to_uvchr_error\fR 4
+.IX Xref "utf8n_to_uvchr_error"
+.IX Item "utf8n_to_uvchr_error"
+THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
+Most code should use "utf8_to_uvchr_buf"() rather than call this
+directly.
+.Sp
+This function is for code that needs to know what the precise malformation(s)
+are when an error is found.  If you also need to know the generated warning
+messages, use "utf8n_to_uvchr_msgs"() instead.
+.Sp
+It is like \f(CW"utf8n_to_uvchr"\fR but it takes an extra parameter placed after
+all the others, \f(CW\*(C`errors\*(C'\fR.  If this parameter is 0, this function behaves
+identically to \f(CW"utf8n_to_uvchr"\fR.  Otherwise, \f(CW\*(C`errors\*(C'\fR should be a pointer
+to a \f(CW\*(C`U32\*(C'\fR variable, which this function sets to indicate any errors found.
+Upon return, if \f(CW*errors\fR is 0, there were no errors found.  Otherwise,
+\&\f(CW*errors\fR is the bit-wise \f(CW\*(C`OR\*(C'\fR of the bits described in the list below.  Some
+of these bits will be set if a malformation is found, even if the input
+\&\f(CW\*(C`flags\*(C'\fR parameter indicates that the given malformation is allowed; those
+exceptions are noted:
+.RS 4
+.ie n .IP """UTF8_GOT_PERL_EXTENDED""" 4
+.el .IP \f(CWUTF8_GOT_PERL_EXTENDED\fR 4
+.IX Item "UTF8_GOT_PERL_EXTENDED"
+The input sequence is not standard UTF\-8, but a Perl extension.  This bit is
+set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
+\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR or the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR flags.
+.Sp
+Code points above 0x7FFF_FFFF (2**31 \- 1) were never specified in any standard,
+and so some extension must be used to express them.  Perl uses a natural
+extension to UTF\-8 to represent the ones up to 2**36\-1, and invented a further
+extension to represent even higher ones, so that any code point that fits in a
+64\-bit word can be represented.  Text using these extensions is not likely to
+be portable to non-Perl code.  We lump both of these extensions together and
+refer to them as Perl extended UTF\-8.  There exist other extensions that people
+have invented, incompatible with Perl's.
+.Sp
+On EBCDIC platforms starting in Perl v5.24, the Perl extension for representing
+extremely high code points kicks in at 0x3FFF_FFFF (2**30 \-1), which is lower
+than on ASCII.  Prior to that, code points 2**31 and higher were simply
+unrepresentable, and a different, incompatible method was used to represent
+code points between 2**30 and 2**31 \- 1.
+.Sp
+On both platforms, ASCII and EBCDIC, \f(CW\*(C`UTF8_GOT_PERL_EXTENDED\*(C'\fR is set if
+Perl extended UTF\-8 is used.
+.Sp
+In earlier Perls, this bit was named \f(CW\*(C`UTF8_GOT_ABOVE_31_BIT\*(C'\fR, which you still
+may use for backward compatibility.  That name is misleading, as this flag may
+be set when the code point actually does fit in 31 bits.  This happens on
+EBCDIC platforms, and sometimes when the overlong
+malformation is also present.  The new name accurately
+describes the situation in all cases.
+.ie n .IP """UTF8_GOT_CONTINUATION""" 4
+.el .IP \f(CWUTF8_GOT_CONTINUATION\fR 4
+.IX Item "UTF8_GOT_CONTINUATION"
+The input sequence was malformed in that the first byte was a UTF\-8
+continuation byte.
+.ie n .IP """UTF8_GOT_EMPTY""" 4
+.el .IP \f(CWUTF8_GOT_EMPTY\fR 4
+.IX Item "UTF8_GOT_EMPTY"
+The input \f(CW\*(C`curlen\*(C'\fR parameter was 0.
+.ie n .IP """UTF8_GOT_LONG""" 4
+.el .IP \f(CWUTF8_GOT_LONG\fR 4
+.IX Item "UTF8_GOT_LONG"
+The input sequence was malformed in that there is some other sequence that
+evaluates to the same code point, but that sequence is shorter than this one.
+.Sp
+Until Unicode 3.1, it was legal for programs to accept this malformation, but
+it was discovered that this created security issues.
+.ie n .IP """UTF8_GOT_NONCHAR""" 4
+.el .IP \f(CWUTF8_GOT_NONCHAR\fR 4
+.IX Item "UTF8_GOT_NONCHAR"
+The code point represented by the input UTF\-8 sequence is for a Unicode
+non-character code point.
+This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
+\&\f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR or the \f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR flags.
+.ie n .IP """UTF8_GOT_NON_CONTINUATION""" 4
+.el .IP \f(CWUTF8_GOT_NON_CONTINUATION\fR 4
+.IX Item "UTF8_GOT_NON_CONTINUATION"
+The input sequence was malformed in that a non-continuation type byte was found
+in a position where only a continuation type one should be.  See also
+\&\f(CW"UTF8_GOT_SHORT"\fR.
+.ie n .IP """UTF8_GOT_OVERFLOW""" 4
+.el .IP \f(CWUTF8_GOT_OVERFLOW\fR 4
+.IX Item "UTF8_GOT_OVERFLOW"
+The input sequence was malformed in that it is for a code point that is not
+representable in the number of bits available in an IV on the current platform.
+.ie n .IP """UTF8_GOT_SHORT""" 4
+.el .IP \f(CWUTF8_GOT_SHORT\fR 4
+.IX Item "UTF8_GOT_SHORT"
+The input sequence was malformed in that \f(CW\*(C`curlen\*(C'\fR is smaller than required for
+a complete sequence.  In other words, the input is for a partial character
+sequence.
+.Sp
+\&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR and \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR both indicate a too short
+sequence.  The difference is that \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR indicates always
+that there is an error, while \f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR means that an incomplete
+sequence was looked at.   If no other flags are present, it means that the
+sequence was valid as far as it went.  Depending on the application, this could
+mean one of three things:
+.RS 4
+.IP \(bu 4
+The \f(CW\*(C`curlen\*(C'\fR length parameter passed in was too small, and the function was
+prevented from examining all the necessary bytes.
+.IP \(bu 4
+The buffer being looked at is based on reading data, and the data received so
+far stopped in the middle of a character, so that the next read will
+read the remainder of this character.  (It is up to the caller to deal with the
+split bytes somehow.)
+.IP \(bu 4
+This is a real error, and the partial sequence is all we're going to get.
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_GOT_SUPER""" 4
+.el .IP \f(CWUTF8_GOT_SUPER\fR 4
+.IX Item "UTF8_GOT_SUPER"
+The input sequence was malformed in that it is for a non-Unicode code point;
+that is, one above the legal Unicode maximum.
+This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
+\&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR flags.
+.ie n .IP """UTF8_GOT_SURROGATE""" 4
+.el .IP \f(CWUTF8_GOT_SURROGATE\fR 4
+.IX Item "UTF8_GOT_SURROGATE"
+The input sequence was malformed in that it is for a \-Unicode UTF\-16 surrogate
+code point.
+This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
+\&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR flags.
+.RE
+.RS 4
+.Sp
+To do your own error handling, call this function with the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR
+flag to suppress any warnings, and then examine the \f(CW*errors\fR return.
+.Sp
+.Vb 3
+\& UV  utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
+\&                          STRLEN *retlen, const U32 flags,
+\&                          U32 *errors)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8n_to_uvchr_msgs""" 4
+.el .IP \f(CWutf8n_to_uvchr_msgs\fR 4
+.IX Xref "utf8n_to_uvchr_msgs"
+.IX Item "utf8n_to_uvchr_msgs"
+THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
+Most code should use "utf8_to_uvchr_buf"() rather than call this
+directly.
+.Sp
+This function is for code that needs to know what the precise malformation(s)
+are when an error is found, and wants the corresponding warning and/or error
+messages to be returned to the caller rather than be displayed.  All messages
+that would have been displayed if all lexical warnings are enabled will be
+returned.
+.Sp
+It is just like \f(CW"utf8n_to_uvchr_error"\fR but it takes an extra parameter
+placed after all the others, \f(CW\*(C`msgs\*(C'\fR.  If this parameter is 0, this function
+behaves identically to \f(CW"utf8n_to_uvchr_error"\fR.  Otherwise, \f(CW\*(C`msgs\*(C'\fR should
+be a pointer to an \f(CW\*(C`AV *\*(C'\fR variable, in which this function creates a new AV to
+contain any appropriate messages.  The elements of the array are ordered so
+that the first message that would have been displayed is in the 0th element,
+and so on.  Each element is a hash with three key-value pairs, as follows:
+.RS 4
+.ie n .IP """text""" 4
+.el .IP \f(CWtext\fR 4
+.IX Item "text"
+The text of the message as a \f(CW\*(C`SVpv\*(C'\fR.
+.ie n .IP """warn_categories""" 4
+.el .IP \f(CWwarn_categories\fR 4
+.IX Item "warn_categories"
+The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR.
+.ie n .IP """flag""" 4
+.el .IP \f(CWflag\fR 4
+.IX Item "flag"
+A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR.
+The bit corresponds to some bit in the \f(CW*errors\fR return value,
+such as \f(CW\*(C`UTF8_GOT_LONG\*(C'\fR.
+.RE
+.RS 4
+.Sp
+It's important to note that specifying this parameter as non-null will cause
+any warnings this function would otherwise generate to be suppressed, and
+instead be placed in \f(CW*msgs\fR.  The caller can check the lexical warnings state
+(or not) when choosing what to do with the returned messages.
+.Sp
+If the flag \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is passed, no warnings are generated, and hence
+no AV is created.
+.Sp
+The caller, of course, is responsible for freeing any returned AV.
+.Sp
+.Vb 3
+\& UV  utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
+\&                         STRLEN *retlen, const U32 flags,
+\&                         U32 *errors, AV **msgs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_SAFE_SKIP""" 4
+.el .IP \f(CWUTF8_SAFE_SKIP\fR 4
+.IX Xref "UTF8_SAFE_SKIP"
+.IX Item "UTF8_SAFE_SKIP"
+returns 0 if \f(CW\*(C`s\ >=\ e\*(C'\fR; otherwise returns the number of bytes in the
+UTF\-8 encoded character whose first  byte is pointed to by \f(CW\*(C`s\*(C'\fR.  But it never
+returns beyond \f(CW\*(C`e\*(C'\fR.  On DEBUGGING builds, it asserts that \f(CW\*(C`s\ <=\ e\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  UTF8_SAFE_SKIP(char* s, char* e)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8SKIP""" 4
+.el .IP \f(CWUTF8SKIP\fR 4
+.IX Xref "UTF8SKIP"
+.IX Item "UTF8SKIP"
+returns the number of bytes a non-malformed UTF\-8 encoded character whose first
+(perhaps only) byte is pointed to by \f(CW\*(C`s\*(C'\fR.
+.Sp
+If there is a possibility of malformed input, use instead:
+.RS 4
+.ie n .IP """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by ""s""; or" 4
+.el .IP "\f(CW""UTF8_SAFE_SKIP""\fR if you know the maximum ending pointer in the buffer pointed to by \f(CWs\fR; or" 4
+.IX Item """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by s; or"
+.PD 0
+.ie n .IP """UTF8_CHK_SKIP"" if you don't know it." 4
+.el .IP "\f(CW""UTF8_CHK_SKIP""\fR if you don't know it." 4
+.IX Item """UTF8_CHK_SKIP"" if you don't know it."
+.RE
+.RS 4
+.PD
+.Sp
+It is better to restructure your code so the end pointer is passed down so that
+you know what it actually is at the point of this call, but if that isn't
+possible, \f(CW"UTF8_CHK_SKIP"\fR can minimize the chance of accessing beyond the end
+of the input buffer.
+.Sp
+.Vb 1
+\& STRLEN  UTF8SKIP(char* s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UTF8_SKIP""" 4
+.el .IP \f(CWUTF8_SKIP\fR 4
+.IX Xref "UTF8_SKIP"
+.IX Item "UTF8_SKIP"
+This is a synonym for \f(CW"UTF8SKIP"\fR
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  UTF8_SKIP(char* s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_to_bytes""" 4
+.el .IP \f(CWutf8_to_bytes\fR 4
+.IX Xref "utf8_to_bytes"
+.IX Item "utf8_to_bytes"
+NOTE: \f(CW\*(C`utf8_to_bytes\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Converts a string \f(CW"s"\fR of length \f(CW*lenp\fR from UTF\-8 into native byte encoding.
+Unlike "bytes_to_utf8", this over-writes the original string, and
+updates \f(CW*lenp\fR to contain the new length.
+Returns zero on failure (leaving \f(CW"s"\fR unchanged) setting \f(CW*lenp\fR to \-1.
+.Sp
+Upon successful return, the number of variants in the string can be computed by
+having saved the value of \f(CW*lenp\fR before the call, and subtracting the
+after-call value of \f(CW*lenp\fR from it.
+.Sp
+If you need a copy of the string, see "bytes_from_utf8".
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  utf8_to_bytes(U8 *s, STRLEN *lenp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_to_uvchr""" 4
+.el .IP \f(CWutf8_to_uvchr\fR 4
+.IX Xref "utf8_to_uvchr"
+.IX Item "utf8_to_uvchr"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`utf8_to_uvchr\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR
+which is assumed to be in UTF\-8 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the
+length, in bytes, of that character.
+.Sp
+Some, but not all, UTF\-8 malformations are detected, and in fact, some
+malformed input could cause reading beyond the end of the input buffer, which
+is why this function is deprecated.  Use "utf8_to_uvchr_buf" instead.
+.Sp
+If \f(CW\*(C`s\*(C'\fR points to one of the detected malformations, and UTF8 warnings are
+enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't
+\&\f(CW\*(C`NULL\*(C'\fR) to \-1.  If those warnings are off, the computed value if well-defined (or
+the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and \f(CW*retlen\fR
+is set (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the
+next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
+See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is returned.
+.RS 4
+.Sp
+.Vb 1
+\& UV  utf8_to_uvchr(const U8 *s, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_to_uvchr_buf""" 4
+.el .IP \f(CWutf8_to_uvchr_buf\fR 4
+.IX Xref "utf8_to_uvchr_buf"
+.IX Item "utf8_to_uvchr_buf"
+Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR which
+is assumed to be in UTF\-8 encoding; \f(CW\*(C`send\*(C'\fR points to 1 beyond the end of \f(CW\*(C`s\*(C'\fR.
+\&\f(CW*retlen\fR will be set to the length, in bytes, of that character.
+.Sp
+If \f(CW\*(C`s\*(C'\fR does not point to a well-formed UTF\-8 character and UTF8 warnings are
+enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't
+\&\f(CW\*(C`NULL\*(C'\fR) to \-1.  If those warnings are off, the computed value, if well-defined
+(or the Unicode REPLACEMENT CHARACTER if not), is silently returned, and
+\&\f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't \f(CW\*(C`NULL\*(C'\fR) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is
+the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
+See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
+returned.
+.RS 4
+.Sp
+.Vb 1
+\& UV  utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UVCHR_IS_INVARIANT""" 4
+.el .IP \f(CWUVCHR_IS_INVARIANT\fR 4
+.IX Xref "UVCHR_IS_INVARIANT"
+.IX Item "UVCHR_IS_INVARIANT"
+Evaluates to 1 if the representation of code point \f(CW\*(C`cp\*(C'\fR is the same whether or
+not it is encoded in UTF\-8; otherwise evaluates to 0.  UTF\-8 invariant
+characters can be copied as-is when converting to/from UTF\-8, saving time.
+\&\f(CW\*(C`cp\*(C'\fR is Unicode if above 255; otherwise is platform-native.
+.RS 4
+.Sp
+.Vb 1
+\& bool  UVCHR_IS_INVARIANT(UV cp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UVCHR_SKIP""" 4
+.el .IP \f(CWUVCHR_SKIP\fR 4
+.IX Xref "UVCHR_SKIP"
+.IX Item "UVCHR_SKIP"
+returns the number of bytes required to represent the code point \f(CW\*(C`cp\*(C'\fR when
+encoded as UTF\-8.  \f(CW\*(C`cp\*(C'\fR is a native (ASCII or EBCDIC) code point if less than
+255; a Unicode code point otherwise.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  UVCHR_SKIP(UV cp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """uvchr_to_utf8_flags""" 4
+.el .IP \f(CWuvchr_to_utf8_flags\fR 4
+.IX Xref "uvchr_to_utf8_flags"
+.IX Item "uvchr_to_utf8_flags"
+Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end
+of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to
+\&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available.  The return value is the pointer to
+the byte after the end of the new character.  In other words,
+.Sp
+.Vb 1
+\&    d = uvchr_to_utf8_flags(d, uv, flags);
+.Ve
+.Sp
+or, in most cases,
+.Sp
+.Vb 1
+\&    d = uvchr_to_utf8_flags(d, uv, 0);
+.Ve
+.Sp
+This is the Unicode-aware way of saying
+.Sp
+.Vb 1
+\&    *(d++) = uv;
+.Ve
+.Sp
+If \f(CW\*(C`flags\*(C'\fR is 0, this function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as
+input.  \f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word.
+.Sp
+Specifying \f(CW\*(C`flags\*(C'\fR can further restrict what is allowed and not warned on, as
+follows:
+.Sp
+If \f(CW\*(C`uv\*(C'\fR is a Unicode surrogate code point and \f(CW\*(C`UNICODE_WARN_SURROGATE\*(C'\fR is set,
+the function will raise a warning, provided UTF8 warnings are enabled.  If
+instead \f(CW\*(C`UNICODE_DISALLOW_SURROGATE\*(C'\fR is set, the function will fail and return
+NULL.  If both flags are set, the function will both warn and return NULL.
+.Sp
+Similarly, the \f(CW\*(C`UNICODE_WARN_NONCHAR\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_NONCHAR\*(C'\fR flags
+affect how the function handles a Unicode non-character.
+.Sp
+And likewise, the \f(CW\*(C`UNICODE_WARN_SUPER\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR flags
+affect the handling of code points that are above the Unicode maximum of
+0x10FFFF.  Languages other than Perl may not be able to accept files that
+contain these.
+.Sp
+The flag \f(CW\*(C`UNICODE_WARN_ILLEGAL_INTERCHANGE\*(C'\fR selects all three of
+the above WARN flags; and \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR selects all
+three DISALLOW flags.  \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR restricts the
+allowed inputs to the strict UTF\-8 traditionally defined by Unicode.
+Similarly, \f(CW\*(C`UNICODE_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR and
+\&\f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR are shortcuts to select the
+above-Unicode and surrogate flags, but not the non-character ones, as
+defined in
+Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>.
+See "Noncharacter code points" in perlunicode.
+.Sp
+Extremely high code points were never specified in any standard, and require an
+extension to UTF\-8 to express, which Perl does.  It is likely that programs
+written in something other than Perl would not be able to read files that
+contain these; nor would Perl understand files written by something that uses a
+different extension.  For these reasons, there is a separate set of flags that
+can warn and/or disallow these extremely high code points, even if other
+above-Unicode ones are accepted.  They are the \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR
+and \f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR flags.  For more information see
+\&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR.  Of course \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR will
+treat all above-Unicode code points, including these, as malformations.  (Note
+that the Unicode standard considers anything above 0x10FFFF to be illegal, but
+there are standards predating it that allow up to 0x7FFF_FFFF (2**31 \-1))
+.Sp
+A somewhat misleadingly named synonym for \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR is
+retained for backward compatibility: \f(CW\*(C`UNICODE_WARN_ABOVE_31_BIT\*(C'\fR.  Similarly,
+\&\f(CW\*(C`UNICODE_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named
+\&\f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR.  The names are misleading because on EBCDIC
+platforms,these flags can apply to code points that actually do fit in 31 bits.
+The new names accurately describe the situation in all cases.
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """uvchr_to_utf8_flags_msgs""" 4
+.el .IP \f(CWuvchr_to_utf8_flags_msgs\fR 4
+.IX Xref "uvchr_to_utf8_flags_msgs"
+.IX Item "uvchr_to_utf8_flags_msgs"
+THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
+.Sp
+Most code should use \f(CW\*(C`"uvchr_to_utf8_flags"()\*(C'\fR rather than call this directly.
+.Sp
+This function is for code that wants any warning and/or error messages to be
+returned to the caller rather than be displayed.  All messages that would have
+been displayed if all lexical warnings are enabled will be returned.
+.Sp
+It is just like \f(CW"uvchr_to_utf8_flags"\fR but it takes an extra parameter
+placed after all the others, \f(CW\*(C`msgs\*(C'\fR.  If this parameter is 0, this function
+behaves identically to \f(CW"uvchr_to_utf8_flags"\fR.  Otherwise, \f(CW\*(C`msgs\*(C'\fR should
+be a pointer to an \f(CW\*(C`HV *\*(C'\fR variable, in which this function creates a new HV to
+contain any appropriate messages.  The hash has three key-value pairs, as
+follows:
+.RS 4
+.ie n .IP """text""" 4
+.el .IP \f(CWtext\fR 4
+.IX Item "text"
+The text of the message as a \f(CW\*(C`SVpv\*(C'\fR.
+.ie n .IP """warn_categories""" 4
+.el .IP \f(CWwarn_categories\fR 4
+.IX Item "warn_categories"
+The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR.
+.ie n .IP """flag""" 4
+.el .IP \f(CWflag\fR 4
+.IX Item "flag"
+A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR.
+The bit corresponds to some bit in the \f(CW*errors\fR return value,
+such as \f(CW\*(C`UNICODE_GOT_SURROGATE\*(C'\fR.
+.RE
+.RS 4
+.Sp
+It's important to note that specifying this parameter as non-null will cause
+any warnings this function would otherwise generate to be suppressed, and
+instead be placed in \f(CW*msgs\fR.  The caller can check the lexical warnings state
+(or not) when choosing what to do with the returned messages.
+.Sp
+The caller, of course, is responsible for freeing any returned HV.
+.Sp
+.Vb 1
+\& U8 *  uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV **msgs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """uvchr_to_utf8""" 4
+.el .IP \f(CWuvchr_to_utf8\fR 4
+.IX Xref "uvchr_to_utf8"
+.IX Item "uvchr_to_utf8"
+Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end
+of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to
+\&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available.  The return value is the pointer to
+the byte after the end of the new character.  In other words,
+.Sp
+.Vb 1
+\&    d = uvchr_to_utf8(d, uv);
+.Ve
+.Sp
+is the recommended wide native character-aware way of saying
+.Sp
+.Vb 1
+\&    *(d++) = uv;
+.Ve
+.Sp
+This function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as input.
+\&\f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word.
+.Sp
+It is possible to forbid or warn on non-Unicode code points, or those that may
+be problematic by using "uvchr_to_utf8_flags".
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  uvchr_to_utf8(U8 *d, UV uv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Utility Functions"
+.IX Header "Utility Functions"
+.ie n .IP """C_ARRAY_END""" 4
+.el .IP \f(CWC_ARRAY_END\fR 4
+.IX Xref "C_ARRAY_END"
+.IX Item "C_ARRAY_END"
+Returns a pointer to one element past the final element of the input C array.
+.RS 4
+.Sp
+.Vb 1
+\& void *  C_ARRAY_END(void *a)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """C_ARRAY_LENGTH""" 4
+.el .IP \f(CWC_ARRAY_LENGTH\fR 4
+.IX Xref "C_ARRAY_LENGTH"
+.IX Item "C_ARRAY_LENGTH"
+Returns the number of elements in the input C array (so you want your
+zero-based indices to be less than but not equal to).
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  C_ARRAY_LENGTH(void *a)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """getcwd_sv""" 4
+.el .IP \f(CWgetcwd_sv\fR 4
+.IX Xref "getcwd_sv"
+.IX Item "getcwd_sv"
+Fill \f(CW\*(C`sv\*(C'\fR with current working directory
+.RS 4
+.Sp
+.Vb 1
+\& int  getcwd_sv(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IN_PERL_COMPILETIME""" 4
+.el .IP \f(CWIN_PERL_COMPILETIME\fR 4
+.IX Xref "IN_PERL_COMPILETIME"
+.IX Item "IN_PERL_COMPILETIME"
+Returns 1 if this macro is being called during the compilation phase of the
+program; otherwise 0;
+.RS 4
+.Sp
+.Vb 1
+\& bool  IN_PERL_COMPILETIME
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IN_PERL_RUNTIME""" 4
+.el .IP \f(CWIN_PERL_RUNTIME\fR 4
+.IX Xref "IN_PERL_RUNTIME"
+.IX Item "IN_PERL_RUNTIME"
+Returns 1 if this macro is being called during the execution phase of the
+program; otherwise 0;
+.RS 4
+.Sp
+.Vb 1
+\& bool  IN_PERL_RUNTIME
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """IS_SAFE_SYSCALL""" 4
+.el .IP \f(CWIS_SAFE_SYSCALL\fR 4
+.IX Xref "IS_SAFE_SYSCALL"
+.IX Item "IS_SAFE_SYSCALL"
+Same as "is_safe_syscall".
+.RS 4
+.Sp
+.Vb 2
+\& bool  IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
+\&                       NN const char *what, NN const char *op_name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_safe_syscall""" 4
+.el .IP \f(CWis_safe_syscall\fR 4
+.IX Xref "is_safe_syscall"
+.IX Item "is_safe_syscall"
+Test that the given \f(CW\*(C`pv\*(C'\fR (with length \f(CW\*(C`len\*(C'\fR) doesn't contain any internal
+\&\f(CW\*(C`NUL\*(C'\fR characters.
+If it does, set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`ENOENT\*(C'\fR, optionally warn using the \f(CW\*(C`syscalls\*(C'\fR
+category, and return FALSE.
+.Sp
+Return TRUE if the name is safe.
+.Sp
+\&\f(CW\*(C`what\*(C'\fR and \f(CW\*(C`op_name\*(C'\fR are used in any warning.
+.Sp
+Used by the \f(CWIS_SAFE_SYSCALL()\fR macro.
+.RS 4
+.Sp
+.Vb 2
+\& bool  is_safe_syscall(const char *pv, STRLEN len,
+\&                       const char *what, const char *op_name)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_setenv""" 4
+.el .IP \f(CWmy_setenv\fR 4
+.IX Xref "my_setenv"
+.IX Item "my_setenv"
+A wrapper for the C library \fBsetenv\fR\|(3).  Don't use the latter, as the perl
+version has desirable safeguards
+.RS 4
+.Sp
+.Vb 1
+\& void  my_setenv(const char *nam, const char *val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newPADxVOP""" 4
+.el .IP \f(CWnewPADxVOP\fR 4
+.IX Xref "newPADxVOP"
+.IX Item "newPADxVOP"
+Constructs, checks and returns an op containing a pad offset.  \f(CW\*(C`type\*(C'\fR is
+the opcode, which should be one of \f(CW\*(C`OP_PADSV\*(C'\fR, \f(CW\*(C`OP_PADAV\*(C'\fR, \f(CW\*(C`OP_PADHV\*(C'\fR
+or \f(CW\*(C`OP_PADCV\*(C'\fR.  The returned op will have the \f(CW\*(C`op_targ\*(C'\fR field set by
+the \f(CW\*(C`padix\*(C'\fR argument.
+.Sp
+This is convenient when constructing a large optree in nested function
+calls, as it avoids needing to store the pad op directly to set the
+\&\f(CW\*(C`op_targ\*(C'\fR field as a side-effect. For example
+.Sp
+.Vb 2
+\&    o = op_append_elem(OP_LINESEQ, o,
+\&        newPADxVOP(OP_PADSV, 0, padix));
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& OP *  newPADxVOP(I32 type, I32 flags, PADOFFSET padix)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """phase_name""" 4
+.el .IP \f(CWphase_name\fR 4
+.IX Xref "phase_name"
+.IX Item "phase_name"
+Returns the given phase's name as a NUL-terminated string.
+.Sp
+For example, to print a stack trace that includes the current
+interpreter phase you might do:
+.Sp
+.Vb 2
+\&    const char* phase_name = phase_name(PL_phase);
+\&    mess("This is weird. (Perl phase: %s)", phase_name);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& const char * const  phase_name(enum perl_phase)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """Poison""" 4
+.el .IP \f(CWPoison\fR 4
+.IX Xref "Poison"
+.IX Item "Poison"
+PoisonWith(0xEF) for catching access to freed memory.
+.RS 4
+.Sp
+.Vb 1
+\& void  Poison(void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PoisonFree""" 4
+.el .IP \f(CWPoisonFree\fR 4
+.IX Xref "PoisonFree"
+.IX Item "PoisonFree"
+PoisonWith(0xEF) for catching access to freed memory.
+.RS 4
+.Sp
+.Vb 1
+\& void  PoisonFree(void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PoisonNew""" 4
+.el .IP \f(CWPoisonNew\fR 4
+.IX Xref "PoisonNew"
+.IX Item "PoisonNew"
+PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
+.RS 4
+.Sp
+.Vb 1
+\& void  PoisonNew(void* dest, int nitems, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PoisonWith""" 4
+.el .IP \f(CWPoisonWith\fR 4
+.IX Xref "PoisonWith"
+.IX Item "PoisonWith"
+Fill up memory with a byte pattern (a byte repeated over and over
+again) that hopefully catches attempts to access uninitialized memory.
+.RS 4
+.Sp
+.Vb 1
+\& void  PoisonWith(void* dest, int nitems, type, U8 byte)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """StructCopy""" 4
+.el .IP \f(CWStructCopy\fR 4
+.IX Xref "StructCopy"
+.IX Item "StructCopy"
+This is an architecture-independent macro to copy one structure to another.
+.RS 4
+.Sp
+.Vb 1
+\& void  StructCopy(type *src, type *dest, type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_destroyable""" 4
+.el .IP \f(CWsv_destroyable\fR 4
+.IX Xref "sv_destroyable"
+.IX Item "sv_destroyable"
+Dummy routine which reports that object can be destroyed when there is no
+sharing module present.  It ignores its single SV argument, and returns
+\&'true'.  Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it
+could potentially warn under some level of strict-ness.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_destroyable(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_nosharing""" 4
+.el .IP \f(CWsv_nosharing\fR 4
+.IX Xref "sv_nosharing"
+.IX Item "sv_nosharing"
+Dummy routine which "shares" an SV when there is no sharing module present.
+Or "locks" it.  Or "unlocks" it.  In other
+words, ignores its single SV argument.
+Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
+potentially warn under some level of strict-ness.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_nosharing(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Versioning
+.IX Header "Versioning"
+.ie n .IP """new_version""" 4
+.el .IP \f(CWnew_version\fR 4
+.IX Xref "new_version"
+.IX Item "new_version"
+Returns a new version object based on the passed in SV:
+.Sp
+.Vb 1
+\&    SV *sv = new_version(SV *ver);
+.Ve
+.Sp
+Does not alter the passed in ver SV.  See "upg_version" if you
+want to upgrade the SV.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  new_version(SV *ver)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_REVISION""" 4
+.el .IP \f(CWPERL_REVISION\fR 4
+.IX Xref "PERL_REVISION"
+.IX Item "PERL_REVISION"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`PERL_REVISION\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+The major number component of the perl interpreter currently being compiled or
+executing.  This has been \f(CW5\fR from 1993 into 2020.
+.Sp
+Instead use one of the version comparison macros.  See \f(CW"PERL_VERSION_EQ"\fR.
+.ie n .IP """PERL_SUBVERSION""" 4
+.el .IP \f(CWPERL_SUBVERSION\fR 4
+.IX Xref "PERL_SUBVERSION"
+.IX Item "PERL_SUBVERSION"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`PERL_SUBVERSION\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+The micro number component of the perl interpreter currently being compiled or
+executing.  In stable releases this gives the dot release number for
+maintenance updates.  In development releases this gives a tag for a snapshot
+of the status at various points in the development cycle.
+.Sp
+Instead use one of the version comparison macros.  See \f(CW"PERL_VERSION_EQ"\fR.
+.ie n .IP """PERL_VERSION""" 4
+.el .IP \f(CWPERL_VERSION\fR 4
+.IX Xref "PERL_VERSION"
+.IX Item "PERL_VERSION"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`PERL_VERSION\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+The minor number component of the perl interpreter currently being compiled or
+executing.  Between 1993 into 2020, this has ranged from 0 to 33.
+.Sp
+Instead use one of the version comparison macros.  See \f(CW"PERL_VERSION_EQ"\fR.
+.ie n .IP """PERL_VERSION_EQ""" 4
+.el .IP \f(CWPERL_VERSION_EQ\fR 4
+.IX Item "PERL_VERSION_EQ"
+.PD 0
+.ie n .IP """PERL_VERSION_GE""" 4
+.el .IP \f(CWPERL_VERSION_GE\fR 4
+.IX Item "PERL_VERSION_GE"
+.ie n .IP """PERL_VERSION_GT""" 4
+.el .IP \f(CWPERL_VERSION_GT\fR 4
+.IX Item "PERL_VERSION_GT"
+.ie n .IP """PERL_VERSION_LE""" 4
+.el .IP \f(CWPERL_VERSION_LE\fR 4
+.IX Item "PERL_VERSION_LE"
+.ie n .IP """PERL_VERSION_LT""" 4
+.el .IP \f(CWPERL_VERSION_LT\fR 4
+.IX Item "PERL_VERSION_LT"
+.ie n .IP """PERL_VERSION_NE""" 4
+.el .IP \f(CWPERL_VERSION_NE\fR 4
+.IX Xref "PERL_VERSION_EQ PERL_VERSION_GE PERL_VERSION_GT PERL_VERSION_LE PERL_VERSION_LT PERL_VERSION_NE"
+.IX Item "PERL_VERSION_NE"
+.PD
+Returns whether or not the perl currently being compiled has the specified
+relationship to the perl given by the parameters.  For example,
+.Sp
+.Vb 5
+\& #if PERL_VERSION_GT(5,24,2)
+\&   code that will only be compiled on perls after v5.24.2
+\& #else
+\&   fallback code
+\& #endif
+.Ve
+.Sp
+Note that this is usable in making compile-time decisions
+.Sp
+You may use the special value '*' for the final number to mean ALL possible
+values for it.  Thus,
+.Sp
+.Vb 1
+\& #if PERL_VERSION_EQ(5,31,\*(Aq*\*(Aq)
+.Ve
+.Sp
+means all perls in the 5.31 series.  And
+.Sp
+.Vb 1
+\& #if PERL_VERSION_NE(5,24,\*(Aq*\*(Aq)
+.Ve
+.Sp
+means all perls EXCEPT 5.24 ones.  And
+.Sp
+.Vb 1
+\& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
+.Ve
+.Sp
+is effectively
+.Sp
+.Vb 1
+\& #if PERL_VERSION_LT(5,10,0)
+.Ve
+.Sp
+This means you don't have to think so much when converting from the existing
+deprecated \f(CW\*(C`PERL_VERSION\*(C'\fR to using this macro:
+.Sp
+.Vb 1
+\& #if PERL_VERSION <= 9
+.Ve
+.Sp
+becomes
+.Sp
+.Vb 1
+\& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
+.Ve
+.RS 4
+.Sp
+.Vb 2
+\& bool  PERL_VERSION_EQ(const U8 major, const U8 minor,
+\&                       const U8 patch)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """prescan_version""" 4
+.el .IP \f(CWprescan_version\fR 4
+.IX Xref "prescan_version"
+.IX Item "prescan_version"
+Validate that a given string can be parsed as a version object, but doesn't
+actually perform the parsing.  Can use either strict or lax validation rules.
+Can optionally set a number of hint variables to save the parsing code
+some time when tokenizing.
+.RS 4
+.Sp
+.Vb 4
+\& const char *  prescan_version(const char *s, bool strict,
+\&                               const char **errstr, bool *sqv,
+\&                               int *ssaw_decimal, int *swidth,
+\&                               bool *salpha)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """scan_version""" 4
+.el .IP \f(CWscan_version\fR 4
+.IX Xref "scan_version"
+.IX Item "scan_version"
+Returns a pointer to the next character after the parsed
+version string, as well as upgrading the passed in SV to
+an RV.
+.Sp
+Function must be called with an already existing SV like
+.Sp
+.Vb 2
+\&    sv = newSV(0);
+\&    s = scan_version(s, SV *sv, bool qv);
+.Ve
+.Sp
+Performs some preprocessing to the string to ensure that
+it has the correct characteristics of a version.  Flags the
+object if it contains an underscore (which denotes this
+is an alpha version).  The boolean qv denotes that the version
+should be interpreted as if it had multiple decimals, even if
+it doesn't.
+.RS 4
+.Sp
+.Vb 1
+\& const char *  scan_version(const char *s, SV *rv, bool qv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """upg_version""" 4
+.el .IP \f(CWupg_version\fR 4
+.IX Xref "upg_version"
+.IX Item "upg_version"
+In-place upgrade of the supplied SV to a version object.
+.Sp
+.Vb 1
+\&    SV *sv = upg_version(SV *sv, bool qv);
+.Ve
+.Sp
+Returns a pointer to the upgraded SV.  Set the boolean qv if you want
+to force this SV to be interpreted as an "extended" version.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  upg_version(SV *ver, bool qv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vcmp""" 4
+.el .IP \f(CWvcmp\fR 4
+.IX Xref "vcmp"
+.IX Item "vcmp"
+Version object aware cmp.  Both operands must already have been 
+converted into version objects.
+.RS 4
+.Sp
+.Vb 1
+\& int  vcmp(SV *lhv, SV *rhv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vnormal""" 4
+.el .IP \f(CWvnormal\fR 4
+.IX Xref "vnormal"
+.IX Item "vnormal"
+Accepts a version object and returns the normalized string
+representation.  Call like:
+.Sp
+.Vb 1
+\&    sv = vnormal(rv);
+.Ve
+.Sp
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+.Sp
+The SV returned has a refcount of 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vnormal(SV *vs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vnumify""" 4
+.el .IP \f(CWvnumify\fR 4
+.IX Xref "vnumify"
+.IX Item "vnumify"
+Accepts a version object and returns the normalized floating
+point representation.  Call like:
+.Sp
+.Vb 1
+\&    sv = vnumify(rv);
+.Ve
+.Sp
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+.Sp
+The SV returned has a refcount of 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vnumify(SV *vs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vstringify""" 4
+.el .IP \f(CWvstringify\fR 4
+.IX Xref "vstringify"
+.IX Item "vstringify"
+In order to maintain maximum compatibility with earlier versions
+of Perl, this function will return either the floating point
+notation or the multiple dotted notation, depending on whether
+the original version contained 1 or more dots, respectively.
+.Sp
+The SV returned has a refcount of 1.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vstringify(SV *vs)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vverify""" 4
+.el .IP \f(CWvverify\fR 4
+.IX Xref "vverify"
+.IX Item "vverify"
+Validates that the SV contains valid internal structure for a version object.
+It may be passed either the version object (RV) or the hash itself (HV).  If
+the structure is valid, it returns the HV.  If the structure is invalid,
+it returns NULL.
+.Sp
+.Vb 1
+\&    SV *hv = vverify(sv);
+.Ve
+.Sp
+Note that it only confirms the bare minimum structure (so as not to get
+confused by derived classes which may contain additional hash entries):
+.RS 4
+.IP \(bu 4
+The SV is an HV or a reference to an HV
+.IP \(bu 4
+The hash contains a "version" key
+.IP \(bu 4
+The "version" key has a reference to an AV as its value
+.RE
+.RS 4
+.Sp
+.Vb 1
+\& SV *  vverify(SV *vs)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Warning and Dieing"
+.IX Xref "WARN_ALL WARN_AMBIGUOUS WARN_BAREWORD WARN_CLOSED WARN_CLOSURE WARN_DEBUGGING WARN_DEPRECATED WARN_DEPRECATED__APOSTROPHE_AS_PACKAGE_SEPARATOR WARN_DEPRECATED__DELIMITER_WILL_BE_PAIRED WARN_DEPRECATED__DOT_IN_INC WARN_DEPRECATED__GOTO_CONSTRUCT WARN_DEPRECATED__SMARTMATCH WARN_DEPRECATED__UNICODE_PROPERTY_NAME WARN_DEPRECATED__VERSION_DOWNGRADE WARN_DIGIT WARN_EXEC WARN_EXITING WARN_EXPERIMENTAL WARN_EXPERIMENTAL__ARGS_ARRAY_WITH_SIGNATURES WARN_EXPERIMENTAL__BUILTIN WARN_EXPERIMENTAL__CLASS WARN_EXPERIMENTAL__CONST_ATTR WARN_EXPERIMENTAL__DECLARED_REFS WARN_EXPERIMENTAL__DEFER WARN_EXPERIMENTAL__EXTRA_PAIRED_DELIMITERS WARN_EXPERIMENTAL__FOR_LIST WARN_EXPERIMENTAL__PRIVATE_USE WARN_EXPERIMENTAL__REFALIASING WARN_EXPERIMENTAL__REGEX_SETS WARN_EXPERIMENTAL__RE_STRICT WARN_EXPERIMENTAL__TRY WARN_EXPERIMENTAL__UNIPROP_WILDCARDS WARN_EXPERIMENTAL__VLB WARN_GLOB WARN_ILLEGALPROTO WARN_IMPRECISION WARN_INPLACE WARN_INTERNAL WARN_IO WARN_LAYER WARN_LOCALE WARN_MALLOC WARN_MISC WARN_MISSING WARN_NEWLINE WARN_NONCHAR WARN_NON_UNICODE WARN_NUMERIC WARN_ONCE WARN_OVERFLOW WARN_PACK WARN_PARENTHESIS WARN_PIPE WARN_PORTABLE WARN_PRECEDENCE WARN_PRINTF WARN_PROTOTYPE WARN_QW WARN_RECURSION WARN_REDEFINE WARN_REDUNDANT WARN_REGEXP WARN_RESERVED WARN_SCALAR WARN_SEMICOLON WARN_SEVERE WARN_SHADOW WARN_SIGNAL WARN_SUBSTR WARN_SURROGATE WARN_SYNTAX WARN_SYSCALLS WARN_TAINT WARN_THREADS WARN_UNINITIALIZED WARN_UNOPENED WARN_UNPACK WARN_UNTIE WARN_UTF8 WARN_VOID"
+.IX Header "Warning and Dieing"
+In all these calls, the \f(CW\*(C`U32 w\fR\f(CIn\fR\f(CW\*(C'\fR parameters are warning category
+constants.  You can see the ones currently available in
+"Category Hierarchy" in warnings, just capitalize all letters in the names
+and prefix them by \f(CW\*(C`WARN_\*(C'\fR.  So, for example, the category \f(CW\*(C`void\*(C'\fR used in a
+perl program becomes \f(CW\*(C`WARN_VOID\*(C'\fR when used in XS code and passed to one of
+the calls below.
+.ie n .IP """ckWARN""" 4
+.el .IP \f(CWckWARN\fR 4
+.IX Item "ckWARN"
+.PD 0
+.ie n .IP """ckWARN2""" 4
+.el .IP \f(CWckWARN2\fR 4
+.IX Item "ckWARN2"
+.ie n .IP """ckWARN3""" 4
+.el .IP \f(CWckWARN3\fR 4
+.IX Item "ckWARN3"
+.ie n .IP """ckWARN4""" 4
+.el .IP \f(CWckWARN4\fR 4
+.IX Xref "ckWARN ckWARN2 ckWARN3 ckWARN4"
+.IX Item "ckWARN4"
+.PD
+These return a boolean as to whether or not warnings are enabled for any of
+the warning category(ies) parameters:  \f(CW\*(C`w\*(C'\fR, \f(CW\*(C`w1\*(C'\fR, ....
+.Sp
+Should any of the categories by default be enabled even if not within the
+scope of \f(CW\*(C`use\ warnings\*(C'\fR, instead use the \f(CW"ckWARN_d"\fR macros.
+.Sp
+The categories must be completely independent, one may not be subclassed from
+the other.
+.RS 4
+.Sp
+.Vb 4
+\& bool  ckWARN (U32 w)
+\& bool  ckWARN2(U32 w1, U32 w2)
+\& bool  ckWARN3(U32 w1, U32 w2, U32 w3)
+\& bool  ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ckWARN_d""" 4
+.el .IP \f(CWckWARN_d\fR 4
+.IX Item "ckWARN_d"
+.PD 0
+.ie n .IP """ckWARN2_d""" 4
+.el .IP \f(CWckWARN2_d\fR 4
+.IX Item "ckWARN2_d"
+.ie n .IP """ckWARN3_d""" 4
+.el .IP \f(CWckWARN3_d\fR 4
+.IX Item "ckWARN3_d"
+.ie n .IP """ckWARN4_d""" 4
+.el .IP \f(CWckWARN4_d\fR 4
+.IX Xref "ckWARN_d ckWARN2_d ckWARN3_d ckWARN4_d"
+.IX Item "ckWARN4_d"
+.PD
+Like \f(CW"ckWARN"\fR, but for use if and only if the warning category(ies) is by
+default enabled even if not within the scope of \f(CW\*(C`use\ warnings\*(C'\fR.
+.RS 4
+.Sp
+.Vb 4
+\& bool  ckWARN_d (U32 w)
+\& bool  ckWARN2_d(U32 w1, U32 w2)
+\& bool  ckWARN3_d(U32 w1, U32 w2, U32 w3)
+\& bool  ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ck_warner""" 4
+.el .IP \f(CWck_warner\fR 4
+.IX Item "ck_warner"
+.PD 0
+.ie n .IP """ck_warner_d""" 4
+.el .IP \f(CWck_warner_d\fR 4
+.IX Xref "ck_warner ck_warner_d"
+.IX Item "ck_warner_d"
+.PD
+If none of the warning categories given by \f(CW\*(C`err\*(C'\fR are enabled, do nothing;
+otherwise call \f(CW"warner"\fR  or \f(CW"warner_nocontext"\fR with the passed-in
+parameters;.
+.Sp
+\&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR,
+\&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
+categories.
+.Sp
+The two forms differ only in that \f(CW\*(C`ck_warner_d\*(C'\fR should be used if warnings for
+any of the categories are by default enabled.
+.Sp
+NOTE: \f(CW\*(C`ck_warner\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_ck_warner\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.Sp
+NOTE: \f(CW\*(C`ck_warner_d\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_ck_warner_d\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_ck_warner(pTHX_ U32 err, const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CLEAR_ERRSV""" 4
+.el .IP \f(CWCLEAR_ERRSV\fR 4
+.IX Xref "CLEAR_ERRSV"
+.IX Item "CLEAR_ERRSV"
+Clear the contents of \f(CW$@\fR, setting it to the empty string.
+.Sp
+This replaces any read-only SV with a fresh SV and removes any magic.
+.RS 4
+.Sp
+.Vb 1
+\& void  CLEAR_ERRSV()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """croak""" 4
+.el .IP \f(CWcroak\fR 4
+.IX Item "croak"
+.PD 0
+.ie n .IP """croak_nocontext""" 4
+.el .IP \f(CWcroak_nocontext\fR 4
+.IX Xref "croak croak_nocontext"
+.IX Item "croak_nocontext"
+.PD
+These are XS interfaces to Perl's \f(CW\*(C`die\*(C'\fR function.
+.Sp
+They take a sprintf-style format pattern and argument list, which are used to
+generate a string message.  If the message does not end with a newline, then it
+will be extended with some indication of the current location in the code, as
+described for \f(CW"mess_sv"\fR.
+.Sp
+The error message will be used as an exception, by default
+returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
+modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler.  In any case, these croak
+functions never return normally.
+.Sp
+For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
+(\f(CW$@\fR) will be used as an error message or object instead of building an
+error message from arguments.  If you want to throw a non-string object,
+or build an error message in an SV yourself, it is preferable to use
+the \f(CW"croak_sv"\fR function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
+.Sp
+The two forms differ only in that \f(CW\*(C`croak_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter.  It is usually preferred as it takes up fewer
+bytes of code than plain \f(CW\*(C`Perl_croak\*(C'\fR, and time is rarely a critical resource
+when you are about to throw an exception.
+.Sp
+NOTE: \f(CW\*(C`croak\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_croak\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_croak     (pTHX_ const char *pat, ...)
+\& void  croak_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """croak_no_modify""" 4
+.el .IP \f(CWcroak_no_modify\fR 4
+.IX Xref "croak_no_modify"
+.IX Item "croak_no_modify"
+This encapsulates a common reason for dying, generating terser object code than
+using the generic \f(CW\*(C`Perl_croak\*(C'\fR.  It is exactly equivalent to
+\&\f(CW\*(C`Perl_croak(aTHX_ "%s", PL_no_modify)\*(C'\fR (which expands to something like
+"Modification of a read-only value attempted").
+.Sp
+Less code used on exception code paths reduces CPU cache pressure.
+.RS 4
+.Sp
+.Vb 1
+\& void  croak_no_modify()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """croak_sv""" 4
+.el .IP \f(CWcroak_sv\fR 4
+.IX Xref "croak_sv"
+.IX Item "croak_sv"
+This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function.
+.Sp
+\&\f(CW\*(C`baseex\*(C'\fR is the error message or object.  If it is a reference, it
+will be used as-is.  Otherwise it is used as a string, and if it does
+not end with a newline then it will be extended with some indication of
+the current location in the code, as described for "mess_sv".
+.Sp
+The error message or object will be used as an exception, by default
+returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
+modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler.  In any case, the \f(CW\*(C`croak_sv\*(C'\fR
+function never returns normally.
+.Sp
+To die with a simple string message, the "croak" function may be
+more convenient.
+.RS 4
+.Sp
+.Vb 1
+\& void  croak_sv(SV *baseex)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """die""" 4
+.el .IP \f(CWdie\fR 4
+.IX Item "die"
+.PD 0
+.ie n .IP """die_nocontext""" 4
+.el .IP \f(CWdie_nocontext\fR 4
+.IX Xref "die die_nocontext"
+.IX Item "die_nocontext"
+.PD
+These behave the same as "croak", except for the return type.
+They should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
+They never actually return.
+.Sp
+The two forms differ only in that \f(CW\*(C`die_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`die\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_die\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& OP *  Perl_die     (pTHX_ const char *pat, ...)
+\& OP *  die_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """die_sv""" 4
+.el .IP \f(CWdie_sv\fR 4
+.IX Xref "die_sv"
+.IX Item "die_sv"
+This behaves the same as "croak_sv", except for the return type.
+It should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
+The function never actually returns.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  die_sv(SV *baseex)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ERRSV""" 4
+.el .IP \f(CWERRSV\fR 4
+.IX Xref "ERRSV"
+.IX Item "ERRSV"
+Returns the SV for \f(CW$@\fR, creating it if needed.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  ERRSV
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """packWARN""" 4
+.el .IP \f(CWpackWARN\fR 4
+.IX Item "packWARN"
+.PD 0
+.ie n .IP """packWARN2""" 4
+.el .IP \f(CWpackWARN2\fR 4
+.IX Item "packWARN2"
+.ie n .IP """packWARN3""" 4
+.el .IP \f(CWpackWARN3\fR 4
+.IX Item "packWARN3"
+.ie n .IP """packWARN4""" 4
+.el .IP \f(CWpackWARN4\fR 4
+.IX Xref "packWARN packWARN2 packWARN3 packWARN4"
+.IX Item "packWARN4"
+.PD
+These macros are used to pack warning categories into a single U32 to pass to
+macros and functions that take a warning category parameter.  The number of
+categories to pack is given by the name, with a corresponding number of
+category parameters passed.
+.RS 4
+.Sp
+.Vb 4
+\& U32  packWARN (U32 w1)
+\& U32  packWARN2(U32 w1, U32 w2)
+\& U32  packWARN3(U32 w1, U32 w2, U32 w3)
+\& U32  packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SANE_ERRSV""" 4
+.el .IP \f(CWSANE_ERRSV\fR 4
+.IX Xref "SANE_ERRSV"
+.IX Item "SANE_ERRSV"
+Clean up ERRSV so we can safely set it.
+.Sp
+This replaces any read-only SV with a fresh writable copy and removes
+any magic.
+.RS 4
+.Sp
+.Vb 1
+\& void  SANE_ERRSV()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vcroak""" 4
+.el .IP \f(CWvcroak\fR 4
+.IX Xref "vcroak"
+.IX Item "vcroak"
+This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function.
+.Sp
+\&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated
+argument list.  These are used to generate a string message.  If the
+message does not end with a newline, then it will be extended with
+some indication of the current location in the code, as described for
+"mess_sv".
+.Sp
+The error message will be used as an exception, by default
+returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
+modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler.  In any case, the \f(CW\*(C`croak\*(C'\fR
+function never returns normally.
+.Sp
+For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
+(\f(CW$@\fR) will be used as an error message or object instead of building an
+error message from arguments.  If you want to throw a non-string object,
+or build an error message in an SV yourself, it is preferable to use
+the "croak_sv" function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  vcroak(const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vwarn""" 4
+.el .IP \f(CWvwarn\fR 4
+.IX Xref "vwarn"
+.IX Item "vwarn"
+This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function.
+.Sp
+This is like \f(CW"warn"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated
+argument list.
+.Sp
+Unlike with "vcroak", \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
+.RS 4
+.Sp
+.Vb 1
+\& void  vwarn(const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """vwarner""" 4
+.el .IP \f(CWvwarner\fR 4
+.IX Xref "vwarner"
+.IX Item "vwarner"
+This is like \f(CW"warner"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
+.RS 4
+.Sp
+.Vb 1
+\& void  vwarner(U32 err, const char *pat, va_list *args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """warn""" 4
+.el .IP \f(CWwarn\fR 4
+.IX Item "warn"
+.PD 0
+.ie n .IP """warn_nocontext""" 4
+.el .IP \f(CWwarn_nocontext\fR 4
+.IX Xref "warn warn_nocontext"
+.IX Item "warn_nocontext"
+.PD
+These are XS interfaces to Perl's \f(CW\*(C`warn\*(C'\fR function.
+.Sp
+They take a sprintf-style format pattern and argument list, which  are used to
+generate a string message.  If the message does not end with a newline, then it
+will be extended with some indication of the current location in the code, as
+described for \f(CW"mess_sv"\fR.
+.Sp
+The error message or object will by default be written to standard error,
+but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
+.Sp
+Unlike with \f(CW"croak"\fR, \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
+.Sp
+The two forms differ only in that \f(CW\*(C`warn_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+NOTE: \f(CW\*(C`warn\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_warn\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_warn     (pTHX_ const char *pat, ...)
+\& void  warn_nocontext(const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """warner""" 4
+.el .IP \f(CWwarner\fR 4
+.IX Item "warner"
+.PD 0
+.ie n .IP """warner_nocontext""" 4
+.el .IP \f(CWwarner_nocontext\fR 4
+.IX Xref "warner warner_nocontext"
+.IX Item "warner_nocontext"
+.PD
+These output a warning of the specified category (or categories) given by
+\&\f(CW\*(C`err\*(C'\fR, using the sprintf-style format pattern \f(CW\*(C`pat\*(C'\fR, and argument list.
+.Sp
+\&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR,
+\&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
+categories.  If any of the warning categories they specify is fatal, a fatal
+exception is thrown.
+.Sp
+In any event a message is generated by the pattern and arguments.  If the
+message does not end with a newline, then it will be extended with some
+indication of the current location in the code, as described for "mess_sv".
+.Sp
+The error message or object will by default be written to standard error,
+but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
+.Sp
+\&\f(CW\*(C`pat\*(C'\fR is not permitted to be null.
+.Sp
+The two forms differ only in that \f(CW\*(C`warner_nocontext\*(C'\fR does not take a thread
+context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+.Sp
+These functions differ from the similarly named \f(CW"warn"\fR functions, in that
+the latter are for XS code to unconditionally display a warning, whereas these
+are for code that may be compiling a perl program, and does extra checking to
+see if the warning should be fatal.
+.Sp
+NOTE: \f(CW\*(C`warner\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_warner\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& void  Perl_warner     (pTHX_ U32 err, const char *pat, ...)
+\& void  warner_nocontext(U32 err, const char *pat, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """warn_sv""" 4
+.el .IP \f(CWwarn_sv\fR 4
+.IX Xref "warn_sv"
+.IX Item "warn_sv"
+This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function.
+.Sp
+\&\f(CW\*(C`baseex\*(C'\fR is the error message or object.  If it is a reference, it
+will be used as-is.  Otherwise it is used as a string, and if it does
+not end with a newline then it will be extended with some indication of
+the current location in the code, as described for "mess_sv".
+.Sp
+The error message or object will by default be written to standard error,
+but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
+.Sp
+To warn with a simple string message, the "warn" function may be
+more convenient.
+.RS 4
+.Sp
+.Vb 1
+\& void  warn_sv(SV *baseex)
+.Ve
+.RE
+.RS 4
+.RE
+.SH XS
+.IX Header "XS"
+\&\fIxsubpp\fR compiles XS code into C.  See "xsubpp" in perlutil.
+.ie n .IP """aMY_CXT""" 4
+.el .IP \f(CWaMY_CXT\fR 4
+.IX Item "aMY_CXT"
+Described in perlxs.
+.ie n .IP """_aMY_CXT""" 4
+.el .IP \f(CW_aMY_CXT\fR 4
+.IX Item "_aMY_CXT"
+Described in perlxs.
+.ie n .IP """aMY_CXT_""" 4
+.el .IP \f(CWaMY_CXT_\fR 4
+.IX Item "aMY_CXT_"
+Described in perlxs.
+.ie n .IP """ax""" 4
+.el .IP \f(CWax\fR 4
+.IX Xref "ax"
+.IX Item "ax"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset,
+used by the \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`XSprePUSH\*(C'\fR and \f(CW\*(C`XSRETURN\*(C'\fR macros.  The \f(CW\*(C`dMARK\*(C'\fR macro
+must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable.
+.RS 4
+.Sp
+.Vb 1
+\& I32  ax
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CLASS""" 4
+.el .IP \f(CWCLASS\fR 4
+.IX Xref "CLASS"
+.IX Item "CLASS"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the
+class name for a C++ XS constructor.  This is always a \f(CW\*(C`char*\*(C'\fR.  See
+\&\f(CW"THIS"\fR.
+.RS 4
+.Sp
+.Vb 1
+\& char*  CLASS
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dAX""" 4
+.el .IP \f(CWdAX\fR 4
+.IX Xref "dAX"
+.IX Item "dAX"
+Sets up the \f(CW\*(C`ax\*(C'\fR variable.
+This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dAX;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dAXMARK""" 4
+.el .IP \f(CWdAXMARK\fR 4
+.IX Xref "dAXMARK"
+.IX Item "dAXMARK"
+Sets up the \f(CW\*(C`ax\*(C'\fR variable and stack marker variable \f(CW\*(C`mark\*(C'\fR.
+This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dAXMARK;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dITEMS""" 4
+.el .IP \f(CWdITEMS\fR 4
+.IX Xref "dITEMS"
+.IX Item "dITEMS"
+Sets up the \f(CW\*(C`items\*(C'\fR variable.
+This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dITEMS;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dMY_CXT""" 4
+.el .IP \f(CWdMY_CXT\fR 4
+.IX Item "dMY_CXT"
+Described in perlxs.
+.ie n .IP """dMY_CXT_SV""" 4
+.el .IP \f(CWdMY_CXT_SV\fR 4
+.IX Xref "dMY_CXT_SV"
+.IX Item "dMY_CXT_SV"
+Now a placeholder that declares nothing
+.RS 4
+.Sp
+.Vb 1
+\&   dMY_CXT_SV;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dUNDERBAR""" 4
+.el .IP \f(CWdUNDERBAR\fR 4
+.IX Xref "dUNDERBAR"
+.IX Item "dUNDERBAR"
+Sets up any variable needed by the \f(CW\*(C`UNDERBAR\*(C'\fR macro.  It used to define
+\&\f(CW\*(C`padoff_du\*(C'\fR, but it is currently a noop.  However, it is strongly advised
+to still use it for ensuring past and future compatibility.
+.RS 4
+.Sp
+.Vb 1
+\&   dUNDERBAR;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dXSARGS""" 4
+.el .IP \f(CWdXSARGS\fR 4
+.IX Xref "dXSARGS"
+.IX Item "dXSARGS"
+Sets up stack and mark pointers for an XSUB, calling \f(CW\*(C`dSP\*(C'\fR and \f(CW\*(C`dMARK\*(C'\fR.
+Sets up the \f(CW\*(C`ax\*(C'\fR and \f(CW\*(C`items\*(C'\fR variables by calling \f(CW\*(C`dAX\*(C'\fR and \f(CW\*(C`dITEMS\*(C'\fR.
+This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dXSARGS;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dXSI32""" 4
+.el .IP \f(CWdXSI32\fR 4
+.IX Xref "dXSI32"
+.IX Item "dXSI32"
+Sets up the \f(CW\*(C`ix\*(C'\fR variable for an XSUB which has aliases.  This is usually
+handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   dXSI32;
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """items""" 4
+.el .IP \f(CWitems\fR 4
+.IX Xref "items"
+.IX Item "items"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of
+items on the stack.  See "Variable-length Parameter Lists" in perlxs.
+.RS 4
+.Sp
+.Vb 1
+\& I32  items
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ix""" 4
+.el .IP \f(CWix\fR 4
+.IX Xref "ix"
+.IX Item "ix"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an
+XSUB's aliases was used to invoke it.  See "The ALIAS: Keyword" in perlxs.
+.RS 4
+.Sp
+.Vb 1
+\& I32  ix
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """MY_CXT""" 4
+.el .IP \f(CWMY_CXT\fR 4
+.IX Item "MY_CXT"
+Described in perlxs.
+.ie n .IP """MY_CXT_CLONE""" 4
+.el .IP \f(CWMY_CXT_CLONE\fR 4
+.IX Item "MY_CXT_CLONE"
+Described in perlxs.
+.ie n .IP """MY_CXT_INIT""" 4
+.el .IP \f(CWMY_CXT_INIT\fR 4
+.IX Item "MY_CXT_INIT"
+Described in perlxs.
+.ie n .IP """pMY_CXT""" 4
+.el .IP \f(CWpMY_CXT\fR 4
+.IX Item "pMY_CXT"
+Described in perlxs.
+.ie n .IP """_pMY_CXT""" 4
+.el .IP \f(CW_pMY_CXT\fR 4
+.IX Item "_pMY_CXT"
+Described in perlxs.
+.ie n .IP """pMY_CXT_""" 4
+.el .IP \f(CWpMY_CXT_\fR 4
+.IX Item "pMY_CXT_"
+Described in perlxs.
+.ie n .IP """RETVAL""" 4
+.el .IP \f(CWRETVAL\fR 4
+.IX Xref "RETVAL"
+.IX Item "RETVAL"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an
+XSUB.  This is always the proper type for the XSUB.  See
+"The RETVAL Variable" in perlxs.
+.RS 4
+.Sp
+.Vb 1
+\& type  RETVAL
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ST""" 4
+.el .IP \f(CWST\fR 4
+.IX Xref "ST"
+.IX Item "ST"
+Used to access elements on the XSUB's stack.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  ST(int ix)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """START_MY_CXT""" 4
+.el .IP \f(CWSTART_MY_CXT\fR 4
+.IX Item "START_MY_CXT"
+Described in perlxs.
+.ie n .IP """THIS""" 4
+.el .IP \f(CWTHIS\fR 4
+.IX Xref "THIS"
+.IX Item "THIS"
+Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a C++
+XSUB.  This is always the proper type for the C++ object.  See \f(CW"CLASS"\fR and
+"Using XS With C++" in perlxs.
+.RS 4
+.Sp
+.Vb 1
+\& type  THIS
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """UNDERBAR""" 4
+.el .IP \f(CWUNDERBAR\fR 4
+.IX Xref "UNDERBAR"
+.IX Item "UNDERBAR"
+The SV* corresponding to the \f(CW$_\fR variable.  Works even if there
+is a lexical \f(CW$_\fR in scope.
+.ie n .IP """XS""" 4
+.el .IP \f(CWXS\fR 4
+.IX Xref "XS"
+.IX Item "XS"
+Macro to declare an XSUB and its C parameter list.  This is handled by
+\&\f(CW\*(C`xsubpp\*(C'\fR.  It is the same as using the more explicit \f(CW\*(C`XS_EXTERNAL\*(C'\fR macro; the
+latter is preferred.
+.ie n .IP """XS_EXTERNAL""" 4
+.el .IP \f(CWXS_EXTERNAL\fR 4
+.IX Xref "XS_EXTERNAL"
+.IX Item "XS_EXTERNAL"
+Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.
+.ie n .IP """XS_INTERNAL""" 4
+.el .IP \f(CWXS_INTERNAL\fR 4
+.IX Xref "XS_INTERNAL"
+.IX Item "XS_INTERNAL"
+Macro to declare an XSUB and its C parameter list without exporting the symbols.
+This is handled by \f(CW\*(C`xsubpp\*(C'\fR and generally preferable over exporting the XSUB
+symbols unnecessarily.
+.ie n .IP """XSPROTO""" 4
+.el .IP \f(CWXSPROTO\fR 4
+.IX Xref "XSPROTO"
+.IX Item "XSPROTO"
+Macro used by \f(CW"XS_INTERNAL"\fR and \f(CW"XS_EXTERNAL"\fR to declare a function
+prototype.  You probably shouldn't be using this directly yourself.
+.SH "Undocumented elements"
+.IX Header "Undocumented elements"
+The following functions have been flagged as part of the public
+API, but are currently undocumented.  Use them at your own risk,
+as the interfaces are subject to change.  Functions that are not
+listed in this document are not intended for public use, and
+should NOT be used under any circumstances.
+.PP
+If you feel you need to use one of these functions, first send
+email to perl5\-porters@perl.org <mailto:perl5-porters@perl.org>.
+It may be that there is a good reason for the function not being
+documented, and it should be removed from this list; or it may
+just be that no one has gotten around to documenting it.  In the
+latter case, you will be asked to submit a patch to document the
+function.  Once your patch is accepted, it will indicate that the
+interface is stable (unless it is explicitly marked otherwise) and
+usable by you.
+.PP
+
+.IX Xref "clone_params_del clone_params_new do_open do_openn newANONATTRSUB newANONHASH newANONLIST newANONSUB newAVREF newCVREF newGVREF newHVREF newSVREF resume_compcv sv_dup sv_dup_inc"
+.PP
+.Vb 4
+\& clone_params_del  newANONATTRSUB  newAVREF  newSVREF       
+\& clone_params_new  newANONHASH     newCVREF  resume_compcv  
+\& do_open           newANONLIST     newGVREF  sv_dup         
+\& do_openn          newANONSUB      newHVREF  sv_dup_inc
+.Ve
+.PP
+Next are the API-flagged elements that are considered experimental.  Using one
+of these is even more risky than plain undocumented ones.  They are listed
+here because they should be listed somewhere (so their existence doesn't get
+lost) and this is the best place for them.
+.PP
+
+.IX Xref "apply_attrs_string gv_fetchmethod_pv_flags gv_fetchmethod_pvn_flags gv_fetchmethod_sv_flags hv_store_flags leave_adjust_stacks newXS_flags savetmps thread_locale_init thread_locale_term"
+.PP
+.Vb 4
+\& apply_attrs_string        hv_store_flags       thread_locale_init
+\& gv_fetchmethod_pv_flags   leave_adjust_stacks  thread_locale_term
+\& gv_fetchmethod_pvn_flags  newXS_flags          
+\& gv_fetchmethod_sv_flags   savetmps
+.Ve
+.PP
+Finally are deprecated undocumented API elements.
+Do not use any for new code; remove all occurrences of all of these from
+existing code.
+.PP
+There are currently no items of this type
+.SH AUTHORS
+.IX Header "AUTHORS"
+Until May 1997, this document was maintained by Jeff Okamoto
+<okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
+.PP
+With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
+Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
+Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
+Stephen McCamant, and Gurusamy Sarathy.
+.PP
+API Listing originally by Dean Roehrich <roehrich@cray.com>.
+.PP
+Updated to be autogenerated from comments in the source by Benjamin Stuhl.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIconfig.h\fR, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs
diff --git a/upstream/mageia-cauldron/man1/perlapio.1 b/upstream/mageia-cauldron/man1/perlapio.1
new file mode 100644
index 00000000..591416c4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlapio.1
@@ -0,0 +1,548 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLAPIO 1"
+.TH PERLAPIO 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlapio \- perl's IO abstraction interface.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  #define PERLIO_NOT_STDIO 0    /* For co\-existence with stdio only */
+\&  #include <perlio.h>           /* Usually via #include <perl.h> */
+\&
+\&  PerlIO *PerlIO_stdin(void);
+\&  PerlIO *PerlIO_stdout(void);
+\&  PerlIO *PerlIO_stderr(void);
+\&
+\&  PerlIO *PerlIO_open(const char *path,const char *mode);
+\&  PerlIO *PerlIO_fdopen(int fd, const char *mode);
+\&  PerlIO *PerlIO_reopen(const char *path, /* deprecated */
+\&          const char *mode, PerlIO *old);
+\&  int     PerlIO_close(PerlIO *f);
+\&
+\&  int     PerlIO_stdoutf(const char *fmt,...)
+\&  int     PerlIO_puts(PerlIO *f,const char *string);
+\&  int     PerlIO_putc(PerlIO *f,int ch);
+\&  SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
+\&  int     PerlIO_printf(PerlIO *f, const char *fmt,...);
+\&  int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
+\&  int     PerlIO_flush(PerlIO *f);
+\&
+\&  int     PerlIO_fill(PerlIO *f);
+\&  int     PerlIO_eof(PerlIO *f);
+\&  int     PerlIO_error(PerlIO *f);
+\&  void    PerlIO_clearerr(PerlIO *f);
+\&
+\&  int     PerlIO_getc(PerlIO *d);
+\&  int     PerlIO_ungetc(PerlIO *f,int ch);
+\&  SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
+\&  Size_t  PerlIO_unread(PerlIO *f,const void *vbuf, size_t count
+\&
+\&  int     PerlIO_fileno(PerlIO *f);
+\&
+\&  void    PerlIO_setlinebuf(PerlIO *f);
+\&
+\&  Off_t   PerlIO_tell(PerlIO *f);
+\&  int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
+\&  void    PerlIO_rewind(PerlIO *f);
+\&
+\&  int     PerlIO_getpos(PerlIO *f, SV *save);    /* prototype changed */
+\&  int     PerlIO_setpos(PerlIO *f, SV *saved);   /* prototype changed */
+\&
+\&  int     PerlIO_fast_gets(PerlIO *f);
+\&  int     PerlIO_has_cntptr(PerlIO *f);
+\&  SSize_t PerlIO_get_cnt(PerlIO *f);
+\&  char   *PerlIO_get_ptr(PerlIO *f);
+\&  void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
+\&
+\&  int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
+\&  void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */
+\&
+\&  int     PerlIO_has_base(PerlIO *f);
+\&  char   *PerlIO_get_base(PerlIO *f);
+\&  SSize_t PerlIO_get_bufsiz(PerlIO *f);
+\&
+\&  PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
+\&  FILE   *PerlIO_exportFILE(PerlIO *f, const char *mode);
+\&  FILE   *PerlIO_findFILE(PerlIO *f);
+\&  void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
+\&
+\&  int     PerlIO_apply_layers(pTHX_ PerlIO *f, const char *mode,
+\&                                                    const char *layers);
+\&  int     PerlIO_binmode(pTHX_ PerlIO *f, int ptype, int imode,
+\&                                                    const char *layers);
+\&  void    PerlIO_debug(const char *fmt,...);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl's source code, and extensions that want maximum portability,
+should use the above functions instead of those defined in ANSI C's
+\&\fIstdio.h\fR.  The perl headers (in particular "perlio.h") will
+\&\f(CW\*(C`#define\*(C'\fR them to the I/O mechanism selected at Configure time.
+.PP
+The functions are modeled on those in \fIstdio.h\fR, but parameter order
+has been "tidied up a little".
+.PP
+\&\f(CW\*(C`PerlIO *\*(C'\fR takes the place of FILE *. Like FILE * it should be
+treated as opaque (it is probably safe to assume it is a pointer to
+something).
+.PP
+There are currently two implementations:
+.IP "1. USE_STDIO" 4
+.IX Item "1. USE_STDIO"
+All above are #define'd to stdio functions or are trivial wrapper
+functions which call stdio. In this case \fIonly\fR PerlIO * is a FILE *.
+This has been the default implementation since the abstraction was
+introduced in perl5.003_02.
+.IP "2. USE_PERLIO" 4
+.IX Item "2. USE_PERLIO"
+Introduced just after perl5.7.0, this is a re-implementation of the
+above abstraction which allows perl more control over how IO is done
+as it decouples IO from the way the operating system and C library
+choose to do things. For USE_PERLIO PerlIO * has an extra layer of
+indirection \- it is a pointer-to-a-pointer.  This allows the PerlIO *
+to remain with a known value while swapping the implementation around
+underneath \fIat run time\fR. In this case all the above are true (but
+very simple) functions which call the underlying implementation.
+.Sp
+This is the only implementation for which \f(CWPerlIO_apply_layers()\fR
+does anything "interesting".
+.Sp
+The USE_PERLIO implementation is described in perliol.
+.PP
+Because "perlio.h" is a thin layer (for efficiency) the semantics of
+these functions are somewhat dependent on the underlying implementation.
+Where these variations are understood they are noted below.
+.PP
+Unless otherwise noted, functions return 0 on success, or a negative
+value (usually \f(CW\*(C`EOF\*(C'\fR which is usually \-1) and set \f(CW\*(C`errno\*(C'\fR on error.
+.IP "\fBPerlIO_stdin()\fR, \fBPerlIO_stdout()\fR, \fBPerlIO_stderr()\fR" 4
+.IX Item "PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()"
+Use these rather than \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`stderr\*(C'\fR. They are written
+to look like "function calls" rather than variables because this makes
+it easier to \fImake them\fR function calls if platform cannot export data
+to loaded modules, or if (say) different "threads" might have different
+values.
+.IP "\fBPerlIO_open(path, mode)\fR, \fBPerlIO_fdopen(fd,mode)\fR" 4
+.IX Item "PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)"
+These correspond to \fBfopen()\fR/\fBfdopen()\fR and the arguments are the same.
+Return \f(CW\*(C`NULL\*(C'\fR and set \f(CW\*(C`errno\*(C'\fR if there is an error.  There may be an
+implementation limit on the number of open handles, which may be lower
+than the limit on the number of open files \- \f(CW\*(C`errno\*(C'\fR may not be set
+when \f(CW\*(C`NULL\*(C'\fR is returned if this limit is exceeded.
+.IP \fBPerlIO_reopen(path,mode,f)\fR 4
+.IX Item "PerlIO_reopen(path,mode,f)"
+While this currently exists in both implementations, perl itself
+does not use it. \fIAs perl does not use it, it is not well tested.\fR
+.Sp
+Perl prefers to \f(CW\*(C`dup\*(C'\fR the new low-level descriptor to the descriptor
+used by the existing PerlIO. This may become the behaviour of this
+function in the future.
+.IP "\fBPerlIO_printf(f,fmt,...)\fR, \fBPerlIO_vprintf(f,fmt,a)\fR" 4
+.IX Item "PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)"
+These are \fBfprintf()\fR/\fBvfprintf()\fR equivalents.
+.IP \fBPerlIO_stdoutf(fmt,...)\fR 4
+.IX Item "PerlIO_stdoutf(fmt,...)"
+This is \fBprintf()\fR equivalent. printf is #defined to this function,
+so it is (currently) legal to use \f(CW\*(C`printf(fmt,...)\*(C'\fR in perl sources.
+.IP "\fBPerlIO_read(f,buf,count)\fR, \fBPerlIO_write(f,buf,count)\fR" 4
+.IX Item "PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)"
+These correspond functionally to \fBfread()\fR and \fBfwrite()\fR but the
+arguments and return values are different.  The \fBPerlIO_read()\fR and
+\&\fBPerlIO_write()\fR signatures have been modeled on the more sane low level
+\&\fBread()\fR and \fBwrite()\fR functions instead: The "file" argument is passed
+first, there is only one "count", and the return value can distinguish
+between error and \f(CW\*(C`EOF\*(C'\fR.
+.Sp
+Returns a byte count if successful (which may be zero or
+positive), returns negative value and sets \f(CW\*(C`errno\*(C'\fR on error.
+Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was
+interrupted by a signal.
+.IP \fBPerlIO_fill(f)\fR 4
+.IX Item "PerlIO_fill(f)"
+Fills the buffer associated with \f(CW\*(C`f\*(C'\fR with data from the layer below.
+\&\f(CW\*(C`PerlIO_read\*(C'\fR calls this as part of its normal operation.  Returns 0
+upon success; \-1 on failure.
+.IP \fBPerlIO_close(f)\fR 4
+.IX Item "PerlIO_close(f)"
+Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was
+interrupted by a signal.
+.IP "\fBPerlIO_puts(f,s)\fR, \fBPerlIO_putc(f,c)\fR" 4
+.IX Item "PerlIO_puts(f,s), PerlIO_putc(f,c)"
+These correspond to \fBfputs()\fR and \fBfputc()\fR.
+Note that arguments have been revised to have "file" first.
+.IP \fBPerlIO_ungetc(f,c)\fR 4
+.IX Item "PerlIO_ungetc(f,c)"
+This corresponds to \fBungetc()\fR.  Note that arguments have been revised
+to have "file" first.  Arranges that next read operation will return
+the byte \fBc\fR.  Despite the implied "character" in the name only
+values in the range 0..0xFF are defined. Returns the byte \fBc\fR on
+success or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error.  The number of bytes that can be
+"pushed back" may vary, only 1 character is certain, and then only if
+it is the last character that was read from the handle.
+.IP \fBPerlIO_unread(f,buf,count)\fR 4
+.IX Item "PerlIO_unread(f,buf,count)"
+This allows one to unget more than a single byte.
+It effectively unshifts \f(CW\*(C`count\*(C'\fR bytes onto the beginning of the buffer 
+\&\f(CW\*(C`buf\*(C'\fR, so that the next read operation(s) will return them before
+anything else that was in the buffer.
+.Sp
+Returns the number of unread bytes.
+.IP \fBPerlIO_getc(f)\fR 4
+.IX Item "PerlIO_getc(f)"
+This corresponds to \fBgetc()\fR.
+Despite the c in the name only byte range 0..0xFF is supported.
+Returns the character read or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error.
+.IP \fBPerlIO_eof(f)\fR 4
+.IX Item "PerlIO_eof(f)"
+This corresponds to \fBfeof()\fR.  Returns a true/false indication of
+whether the handle is at end of file.  For terminal devices this may
+or may not be "sticky" depending on the implementation.  The flag is
+cleared by \fBPerlIO_seek()\fR, or \fBPerlIO_rewind()\fR.
+.IP \fBPerlIO_error(f)\fR 4
+.IX Item "PerlIO_error(f)"
+This corresponds to \fBferror()\fR.  Returns a true/false indication of
+whether there has been an IO error on the handle.
+.IP \fBPerlIO_fileno(f)\fR 4
+.IX Item "PerlIO_fileno(f)"
+This corresponds to \fBfileno()\fR, note that on some platforms, the meaning
+of "fileno" may not match Unix. Returns \-1 if the handle has no open
+descriptor associated with it.
+.IP \fBPerlIO_clearerr(f)\fR 4
+.IX Item "PerlIO_clearerr(f)"
+This corresponds to \fBclearerr()\fR, i.e., clears 'error' and (usually)
+\&'eof' flags for the "stream". Does not return a value.
+.IP \fBPerlIO_flush(f)\fR 4
+.IX Item "PerlIO_flush(f)"
+This corresponds to \fBfflush()\fR.  Sends any buffered write data to the
+underlying file.  If called with \f(CW\*(C`NULL\*(C'\fR this may flush all open
+streams (or core dump with some USE_STDIO implementations).  Calling
+on a handle open for read only, or on which last operation was a read
+of some kind may lead to undefined behaviour on some USE_STDIO
+implementations.  The USE_PERLIO (layers) implementation tries to
+behave better: it flushes all open streams when passed \f(CW\*(C`NULL\*(C'\fR, and
+attempts to retain data on read streams either in the buffer or by
+seeking the handle to the current logical position.
+.IP \fBPerlIO_seek(f,offset,whence)\fR 4
+.IX Item "PerlIO_seek(f,offset,whence)"
+This corresponds to \fBfseek()\fR.  Sends buffered write data to the
+underlying file, or discards any buffered read data, then positions
+the file descriptor as specified by \fBoffset\fR and \fBwhence\fR (sic).
+This is the correct thing to do when switching between read and write
+on the same handle (see issues with \fBPerlIO_flush()\fR above).  Offset is
+of type \f(CW\*(C`Off_t\*(C'\fR which is a perl Configure value which may not be same
+as stdio's \f(CW\*(C`off_t\*(C'\fR.
+.IP \fBPerlIO_tell(f)\fR 4
+.IX Item "PerlIO_tell(f)"
+This corresponds to \fBftell()\fR.  Returns the current file position, or
+(Off_t) \-1 on error.  May just return value system "knows" without
+making a system call or checking the underlying file descriptor (so
+use on shared file descriptors is not safe without a
+\&\fBPerlIO_seek()\fR). Return value is of type \f(CW\*(C`Off_t\*(C'\fR which is a perl
+Configure value which may not be same as stdio's \f(CW\*(C`off_t\*(C'\fR.
+.IP "\fBPerlIO_getpos(f,p)\fR, \fBPerlIO_setpos(f,p)\fR" 4
+.IX Item "PerlIO_getpos(f,p), PerlIO_setpos(f,p)"
+These correspond (loosely) to \fBfgetpos()\fR and \fBfsetpos()\fR. Rather than
+stdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is
+stored there should be considered opaque. The layout of the data may
+vary from handle to handle.  When not using stdio or if platform does
+not have the stdio calls then they are implemented in terms of
+\&\fBPerlIO_tell()\fR and \fBPerlIO_seek()\fR.
+.IP \fBPerlIO_rewind(f)\fR 4
+.IX Item "PerlIO_rewind(f)"
+This corresponds to \fBrewind()\fR. It is usually defined as being
+.Sp
+.Vb 2
+\&    PerlIO_seek(f,(Off_t)0L, SEEK_SET);
+\&    PerlIO_clearerr(f);
+.Ve
+.IP \fBPerlIO_tmpfile()\fR 4
+.IX Item "PerlIO_tmpfile()"
+This corresponds to \fBtmpfile()\fR, i.e., returns an anonymous PerlIO or
+NULL on error.  The system will attempt to automatically delete the
+file when closed.  On Unix the file is usually \f(CW\*(C`unlink\*(C'\fR\-ed just after
+it is created so it does not matter how it gets closed. On other
+systems the file may only be deleted if closed via \fBPerlIO_close()\fR
+and/or the program exits via \f(CW\*(C`exit\*(C'\fR.  Depending on the implementation
+there may be "race conditions" which allow other processes access to
+the file, though in general it will be safer in this regard than
+ad. hoc. schemes.
+.IP \fBPerlIO_setlinebuf(f)\fR 4
+.IX Item "PerlIO_setlinebuf(f)"
+This corresponds to \fBsetlinebuf()\fR.  Does not return a value. What
+constitutes a "line" is implementation dependent but usually means
+that writing "\en" flushes the buffer.  What happens with things like
+"this\enthat" is uncertain.  (Perl core uses it \fIonly\fR when "dumping";
+it has nothing to do with $| auto-flush.)
+.SS "Co-existence with stdio"
+.IX Subsection "Co-existence with stdio"
+There is outline support for co-existence of PerlIO with stdio.
+Obviously if PerlIO is implemented in terms of stdio there is no
+problem. However in other cases then mechanisms must exist to create a
+FILE * which can be passed to library code which is going to use stdio
+calls.
+.PP
+The first step is to add this line:
+.PP
+.Vb 1
+\&   #define PERLIO_NOT_STDIO 0
+.Ve
+.PP
+\&\fIbefore\fR including any perl header files. (This will probably become
+the default at some point).  That prevents "perlio.h" from attempting
+to #define stdio functions onto PerlIO functions.
+.PP
+XS code is probably better using "typemap" if it expects FILE *
+arguments.  The standard typemap will be adjusted to comprehend any
+changes in this area.
+.IP \fBPerlIO_importFILE(f,mode)\fR 4
+.IX Item "PerlIO_importFILE(f,mode)"
+Used to get a PerlIO * from a FILE *.
+.Sp
+The mode argument should be a string as would be passed to
+fopen/PerlIO_open.  If it is NULL then \- for legacy support \- the code
+will (depending upon the platform and the implementation) either
+attempt to empirically determine the mode in which \fIf\fR is open, or
+use "r+" to indicate a read/write stream.
+.Sp
+Once called the FILE * should \fIONLY\fR be closed by calling
+\&\f(CWPerlIO_close()\fR on the returned PerlIO *.
+.Sp
+The PerlIO is set to textmode. Use PerlIO_binmode if this is
+not the desired mode.
+.Sp
+This is \fBnot\fR the reverse of \fBPerlIO_exportFILE()\fR.
+.IP \fBPerlIO_exportFILE(f,mode)\fR 4
+.IX Item "PerlIO_exportFILE(f,mode)"
+Given a PerlIO * create a 'native' FILE * suitable for passing to code
+expecting to be compiled and linked with ANSI C \fIstdio.h\fR.  The mode
+argument should be a string as would be passed to fopen/PerlIO_open.
+If it is NULL then \- for legacy support \- the FILE * is opened in same
+mode as the PerlIO *.
+.Sp
+The fact that such a FILE * has been 'exported' is recorded, (normally
+by pushing a new :stdio "layer" onto the PerlIO *), which may affect
+future PerlIO operations on the original PerlIO *.  You should not
+call \f(CWfclose()\fR on the file unless you call \f(CWPerlIO_releaseFILE()\fR
+to disassociate it from the PerlIO *.  (Do not use \fBPerlIO_importFILE()\fR
+for doing the disassociation.)
+.Sp
+Calling this function repeatedly will create a FILE * on each call
+(and will push an :stdio layer each time as well).
+.IP \fBPerlIO_releaseFILE(p,f)\fR 4
+.IX Item "PerlIO_releaseFILE(p,f)"
+Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
+complete. It is removed from the list of 'exported' FILE *s, and the
+associated PerlIO * should revert to its original behaviour.
+.Sp
+Use this to disassociate a file from a PerlIO * that was associated
+using \fBPerlIO_exportFILE()\fR.
+.IP \fBPerlIO_findFILE(f)\fR 4
+.IX Item "PerlIO_findFILE(f)"
+Returns a native FILE * used by a stdio layer. If there is none, it
+will create one with PerlIO_exportFILE. In either case the FILE *
+should be considered as belonging to PerlIO subsystem and should
+only be closed by calling \f(CWPerlIO_close()\fR.
+.SS """Fast gets"" Functions"
+.IX Subsection """Fast gets"" Functions"
+In addition to standard-like API defined so far above there is an
+"implementation" interface which allows perl to get at internals of
+PerlIO.  The following calls correspond to the various FILE_xxx macros
+determined by Configure \- or their equivalent in other
+implementations. This section is really of interest to only those
+concerned with detailed perl-core behaviour, implementing a PerlIO
+mapping or writing code which can make use of the "read ahead" that
+has been done by the IO system in the same way perl does. Note that
+any code that uses these interfaces must be prepared to do things the
+traditional way if a handle does not support them.
+.IP \fBPerlIO_fast_gets(f)\fR 4
+.IX Item "PerlIO_fast_gets(f)"
+Returns true if implementation has all the interfaces required to
+allow perl's \f(CW\*(C`sv_gets\*(C'\fR to "bypass" normal IO mechanism.  This can
+vary from handle to handle.
+.Sp
+.Vb 3
+\&  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \e
+\&                        PerlIO_canset_cnt(f) && \e
+\&                        \*(AqCan set pointer into buffer\*(Aq
+.Ve
+.IP \fBPerlIO_has_cntptr(f)\fR 4
+.IX Item "PerlIO_has_cntptr(f)"
+Implementation can return pointer to current position in the "buffer"
+and a count of bytes available in the buffer.  Do not use this \- use
+PerlIO_fast_gets.
+.IP \fBPerlIO_get_cnt(f)\fR 4
+.IX Item "PerlIO_get_cnt(f)"
+Return count of readable bytes in the buffer. Zero or negative return
+means no more bytes available.
+.IP \fBPerlIO_get_ptr(f)\fR 4
+.IX Item "PerlIO_get_ptr(f)"
+Return pointer to next readable byte in buffer, accessing via the
+pointer (dereferencing) is only safe if \fBPerlIO_get_cnt()\fR has returned
+a positive value.  Only positive offsets up to value returned by
+\&\fBPerlIO_get_cnt()\fR are allowed.
+.IP \fBPerlIO_set_ptrcnt(f,p,c)\fR 4
+.IX Item "PerlIO_set_ptrcnt(f,p,c)"
+Set pointer into buffer, and a count of bytes still in the
+buffer. Should be used only to set pointer to within range implied by
+previous calls to \f(CW\*(C`PerlIO_get_ptr\*(C'\fR and \f(CW\*(C`PerlIO_get_cnt\*(C'\fR. The two
+values \fImust\fR be consistent with each other (implementation may only
+use one or the other or may require both).
+.IP \fBPerlIO_canset_cnt(f)\fR 4
+.IX Item "PerlIO_canset_cnt(f)"
+Implementation can adjust its idea of number of bytes in the buffer.
+Do not use this \- use PerlIO_fast_gets.
+.IP \fBPerlIO_set_cnt(f,c)\fR 4
+.IX Item "PerlIO_set_cnt(f,c)"
+Obscure \- set count of bytes in the buffer. Deprecated.  Only usable
+if \fBPerlIO_canset_cnt()\fR returns true.  Currently used in only doio.c to
+force count less than \-1 to \-1.  Perhaps should be PerlIO_set_empty or
+similar.  This call may actually do nothing if "count" is deduced from
+pointer and a "limit".  Do not use this \- use \fBPerlIO_set_ptrcnt()\fR.
+.IP \fBPerlIO_has_base(f)\fR 4
+.IX Item "PerlIO_has_base(f)"
+Returns true if implementation has a buffer, and can return pointer
+to whole buffer and its size. Used by perl for \fB\-T\fR / \fB\-B\fR tests.
+Other uses would be very obscure...
+.IP \fBPerlIO_get_base(f)\fR 4
+.IX Item "PerlIO_get_base(f)"
+Return \fIstart\fR of buffer. Access only positive offsets in the buffer
+up to the value returned by \fBPerlIO_get_bufsiz()\fR.
+.IP \fBPerlIO_get_bufsiz(f)\fR 4
+.IX Item "PerlIO_get_bufsiz(f)"
+Return the \fItotal number of bytes\fR in the buffer, this is neither the
+number that can be read, nor the amount of memory allocated to the
+buffer. Rather it is what the operating system and/or implementation
+happened to \f(CWread()\fR (or whatever) last time IO was requested.
+.SS "Other Functions"
+.IX Subsection "Other Functions"
+.IP "PerlIO_apply_layers(aTHX_ f,mode,layers)" 4
+.IX Item "PerlIO_apply_layers(aTHX_ f,mode,layers)"
+The new interface to the USE_PERLIO implementation. The layers ":crlf"
+and ":raw" are the only ones allowed for other implementations and those
+are silently ignored. (As of perl5.8 ":raw" is deprecated.)  Use
+\&\fBPerlIO_binmode()\fR below for the portable case.
+.IP "PerlIO_binmode(aTHX_ f,ptype,imode,layers)" 4
+.IX Item "PerlIO_binmode(aTHX_ f,ptype,imode,layers)"
+The hook used by perl's \f(CW\*(C`binmode\*(C'\fR operator.
+\&\fBptype\fR is perl's character for the kind of IO:
+.RS 4
+.IP "'<' read" 8
+.IX Item "'<' read"
+.PD 0
+.IP "'>' write" 8
+.IX Item "'>' write"
+.IP "'+' read/write" 8
+.IX Item "'+' read/write"
+.RE
+.RS 4
+.PD
+.Sp
+\&\fBimode\fR is \f(CW\*(C`O_BINARY\*(C'\fR or \f(CW\*(C`O_TEXT\*(C'\fR.
+.Sp
+\&\fBlayers\fR is a string of layers to apply; only ":crlf" makes sense in
+the non\-USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour
+of passing NULL.)
+.Sp
+Portable cases are:
+.Sp
+.Vb 3
+\&    PerlIO_binmode(aTHX_ f,ptype,O_BINARY,NULL);
+\&and
+\&    PerlIO_binmode(aTHX_ f,ptype,O_TEXT,":crlf");
+.Ve
+.Sp
+On Unix these calls probably have no effect whatsoever.  Elsewhere
+they alter "\en" to CR,LF translation and possibly cause a special text
+"end of file" indicator to be written or honoured on read. The effect
+of making the call after doing any IO to the handle depends on the
+implementation. (It may be ignored, affect any data which is already
+buffered as well, or only apply to subsequent data.)
+.RE
+.IP PerlIO_debug(fmt,...) 4
+.IX Item "PerlIO_debug(fmt,...)"
+PerlIO_debug is a \fBprintf()\fR\-like function which can be used for
+debugging.  No return value. Its main use is inside PerlIO where using
+real printf, \fBwarn()\fR etc. would recursively call PerlIO and be a
+problem.
+.Sp
+PerlIO_debug writes to the file named by \f(CW$ENV\fR{'PERLIO_DEBUG'} or defaults
+to stderr if the environment variable is not defined. Typical
+use might be
+.Sp
+.Vb 2
+\&  Bourne shells (sh, ksh, bash, zsh, ash, ...):
+\&   PERLIO_DEBUG=/tmp/perliodebug.log ./perl \-Di somescript some args
+\&
+\&  Csh/Tcsh:
+\&   setenv PERLIO_DEBUG /tmp/perliodebug.log
+\&   ./perl \-Di somescript some args
+\&
+\&  If you have the "env" utility:
+\&   env PERLIO_DEBUG=/tmp/perliodebug.log ./perl \-Di somescript args
+\&
+\&  Win32:
+\&   set PERLIO_DEBUG=perliodebug.log
+\&   perl \-Di somescript some args
+.Ve
+.Sp
+On a Perl built without \f(CW\*(C`\-DDEBUGGING\*(C'\fR, or when the \f(CW\*(C`\-Di\*(C'\fR command-line switch
+is not specified, or under taint, \fBPerlIO_debug()\fR is a no-op.
diff --git a/upstream/mageia-cauldron/man1/perlartistic.1 b/upstream/mageia-cauldron/man1/perlartistic.1
new file mode 100644
index 00000000..5cde6d55
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlartistic.1
@@ -0,0 +1,238 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLARTISTIC 1"
+.TH PERLARTISTIC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlartistic \- the Perl Artistic License
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\& You can refer to this document in Pod via "L<perlartistic>"
+\& Or you can see this document by entering "perldoc perlartistic"
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl is free software; you can redistribute it and/or modify
+it under the terms of either:
+.PP
+.Vb 3
+\&        a) the GNU General Public License as published by the Free
+\&        Software Foundation; either version 1, or (at your option) any
+\&        later version, or
+\&
+\&        b) the "Artistic License" which comes with this Kit.
+.Ve
+.PP
+This is \fB"The Artistic License"\fR.
+It's here so that modules, programs, etc., that want to declare
+this as their distribution license can link to it.
+.PP
+For the GNU General Public License, see perlgpl.
+.SH "The ""Artistic License"""
+.IX Header "The ""Artistic License"""
+.SS Preamble
+.IX Subsection "Preamble"
+The intent of this document is to state the conditions under which a
+Package may be copied, such that the Copyright Holder maintains some
+semblance of artistic control over the development of the package,
+while giving the users of the package the right to use and distribute
+the Package in a more-or-less customary fashion, plus the right to make
+reasonable modifications.
+.SS Definitions
+.IX Subsection "Definitions"
+.IP """Package""" 4
+.IX Item """Package"""
+refers to the collection of files distributed by the
+Copyright Holder, and derivatives of that collection of files created
+through textual modification.
+.IP """Standard Version""" 4
+.IX Item """Standard Version"""
+refers to such a Package if it has not been
+modified, or has been modified in accordance with the wishes of the
+Copyright Holder as specified below.
+.IP """Copyright Holder""" 4
+.IX Item """Copyright Holder"""
+is whoever is named in the copyright or
+copyrights for the package.
+.IP """You""" 4
+.IX Item """You"""
+is you, if you're thinking about copying or distributing this Package.
+.IP """Reasonable copying fee""" 4
+.IX Item """Reasonable copying fee"""
+is whatever you can justify on the basis
+of media cost, duplication charges, time of people involved, and so on.
+(You will not be required to justify it to the Copyright Holder, but
+only to the computing community at large as a market that must bear the
+fee.)
+.IP """Freely Available""" 4
+.IX Item """Freely Available"""
+means that no fee is charged for the item
+itself, though there may be fees involved in handling the item. It also
+means that recipients of the item may redistribute it under the same
+conditions they received it.
+.SS Conditions
+.IX Subsection "Conditions"
+.IP 1. 4
+You may make and give away verbatim copies of the source form of the
+Standard Version of this Package without restriction, provided that you
+duplicate all of the original copyright notices and associated disclaimers.
+.IP 2. 4
+You may apply bug fixes, portability fixes and other modifications
+derived from the Public Domain or from the Copyright Holder.  A Package
+modified in such a way shall still be considered the Standard Version.
+.IP 3. 4
+You may otherwise modify your copy of this Package in any way, provided
+that you insert a prominent notice in each changed file stating how and
+when you changed that file, and provided that you do at least ONE of the
+following:
+.RS 4
+.IP a) 4
+.IX Item "a)"
+place your modifications in the Public Domain or otherwise make them
+Freely Available, such as by posting said modifications to Usenet or an
+equivalent medium, or placing the modifications on a major archive site
+such as uunet.uu.net, or by allowing the Copyright Holder to include
+your modifications in the Standard Version of the Package.
+.IP b) 4
+.IX Item "b)"
+use the modified Package only within your corporation or organization.
+.IP c) 4
+.IX Item "c)"
+rename any non-standard executables so the names do not conflict with
+standard executables, which must also be provided, and provide a
+separate manual page for each non-standard executable that clearly
+documents how it differs from the Standard Version.
+.IP d) 4
+.IX Item "d)"
+make other distribution arrangements with the Copyright Holder.
+.RE
+.RS 4
+.RE
+.IP 4. 4
+You may distribute the programs of this Package in object code or
+executable form, provided that you do at least ONE of the following:
+.RS 4
+.IP a) 4
+.IX Item "a)"
+distribute a Standard Version of the executables and library files,
+together with instructions (in the manual page or equivalent) on where
+to get the Standard Version.
+.IP b) 4
+.IX Item "b)"
+accompany the distribution with the machine-readable source of the
+Package with your modifications.
+.IP c) 4
+.IX Item "c)"
+give non-standard executables non-standard names, and clearly
+document the differences in manual pages (or equivalent), together with
+instructions on where to get the Standard Version.
+.IP d) 4
+.IX Item "d)"
+make other distribution arrangements with the Copyright Holder.
+.RE
+.RS 4
+.RE
+.IP 5. 4
+You may charge a reasonable copying fee for any distribution of this
+Package.  You may charge any fee you choose for support of this
+Package.  You may not charge a fee for this Package itself.  However,
+you may distribute this Package in aggregate with other (possibly
+commercial) programs as part of a larger (possibly commercial) software
+distribution provided that you do not advertise this Package as a
+product of your own.  You may embed this Package's interpreter within
+an executable of yours (by linking); this shall be construed as a mere
+form of aggregation, provided that the complete Standard Version of the
+interpreter is so embedded.
+.IP 6. 4
+The scripts and library files supplied as input to or produced as
+output from the programs of this Package do not automatically fall
+under the copyright of this Package, but belong to whoever generated
+them, and may be sold commercially, and may be aggregated with this
+Package.  If such scripts or library files are aggregated with this
+Package via the so-called "undump" or "unexec" methods of producing a
+binary executable image, then distribution of such an image shall
+neither be construed as a distribution of this Package nor shall it
+fall under the restrictions of Paragraphs 3 and 4, provided that you do
+not represent such an executable image as a Standard Version of this
+Package.
+.IP 7. 4
+C subroutines (or comparably compiled subroutines in other
+languages) supplied by you and linked into this Package in order to
+emulate subroutines and variables of the language defined by this
+Package shall not be considered part of this Package, but are the
+equivalent of input as in Paragraph 6, provided these subroutines do
+not change the language in any way that would cause it to fail the
+regression tests for the language.
+.IP 8. 4
+Aggregation of this Package with a commercial distribution is always
+permitted provided that the use of this Package is embedded; that is,
+when no overt attempt is made to make this Package's interfaces visible
+to the end user of the commercial distribution.  Such use shall not be
+construed as a distribution of this Package.
+.IP 9. 4
+The name of the Copyright Holder may not be used to endorse or promote
+products derived from this software without specific prior written permission.
+.IP 10. 4
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.PP
+The End
diff --git a/upstream/mageia-cauldron/man1/perlbook.1 b/upstream/mageia-cauldron/man1/perlbook.1
new file mode 100644
index 00000000..5da6c151
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlbook.1
@@ -0,0 +1,367 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBOOK 1"
+.TH PERLBOOK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlbook \- Books about and related to Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+There are many books on Perl and Perl-related. A few of these are
+good, some are OK, but many aren't worth your money. There is a list
+of these books, some with extensive reviews, at
+<https://www.perl.org/books/library.html> . We list some of the books here, and while
+listing a book implies our
+endorsement, don't think that not including a book means anything.
+.PP
+Most of these books are available online through Safari Books Online
+( <http://safaribooksonline.com/> ).
+.SS "The most popular books"
+.IX Subsection "The most popular books"
+The major reference book on Perl, written by the creator of Perl, is
+\&\fIProgramming Perl\fR:
+.IP "\fIProgramming Perl\fR (the ""Camel Book""):" 4
+.IX Item "Programming Perl (the ""Camel Book""):"
+.Vb 4
+\& by Tom Christiansen, brian d foy, Larry Wall with Jon Orwant
+\& ISBN 978\-0\-596\-00492\-7 [4th edition February 2012]
+\& ISBN 978\-1\-4493\-9890\-3 [ebook]
+\& https://oreilly.com/catalog/9780596004927
+.Ve
+.PP
+The Ram is a cookbook with hundreds of examples of using Perl to
+accomplish specific tasks:
+.IP "\fIThe Perl Cookbook\fR (the ""Ram Book""):" 4
+.IX Item "The Perl Cookbook (the ""Ram Book""):"
+.Vb 5
+\& by Tom Christiansen and Nathan Torkington,
+\& with Foreword by Larry Wall
+\& ISBN 978\-0\-596\-00313\-5 [2nd Edition August 2003]
+\& ISBN 978\-0\-596\-15888\-0 [ebook]
+\& https://oreilly.com/catalog/9780596003135/
+.Ve
+.PP
+If you want to learn the basics of Perl, you might start with the
+Llama book, which assumes that you already know a little about
+programming:
+.IP "\fILearning Perl\fR  (the ""Llama Book"")" 4
+.IX Item "Learning Perl (the ""Llama Book"")"
+.Vb 4
+\& by Randal L. Schwartz, Tom Phoenix, and brian d foy
+\& ISBN 978\-1\-4493\-0358\-7 [6th edition June 2011]
+\& ISBN 978\-1\-4493\-0458\-4 [ebook]
+\& https://www.learning\-perl.com/
+.Ve
+.PP
+The tutorial started in the Llama continues in the Alpaca, which
+introduces the intermediate features of references, data structures,
+object-oriented programming, and modules:
+.IP "\fIIntermediate Perl\fR (the ""Alpaca Book"")" 4
+.IX Item "Intermediate Perl (the ""Alpaca Book"")"
+.Vb 5
+\& by Randal L. Schwartz and brian d foy, with Tom Phoenix
+\&         foreword by Damian Conway
+\& ISBN 978\-1\-4493\-9309\-0 [2nd edition August 2012]
+\& ISBN 978\-1\-4493\-0459\-1 [ebook]
+\& https://www.intermediateperl.com/
+.Ve
+.SS References
+.IX Subsection "References"
+You might want to keep these desktop references close by your keyboard:
+.IP "\fIPerl 5 Pocket Reference\fR" 4
+.IX Item "Perl 5 Pocket Reference"
+.Vb 4
+\& by Johan Vromans
+\& ISBN 978\-1\-4493\-0370\-9 [5th edition July 2011]
+\& ISBN 978\-1\-4493\-0813\-1 [ebook]
+\& https://oreilly.com/catalog/0636920018476/
+.Ve
+.IP "\fIPerl Debugger Pocket Reference\fR" 4
+.IX Item "Perl Debugger Pocket Reference"
+.Vb 4
+\& by Richard Foley
+\& ISBN 978\-0\-596\-00503\-0 [1st edition January 2004]
+\& ISBN 978\-0\-596\-55625\-9 [ebook]
+\& https://oreilly.com/catalog/9780596005030/
+.Ve
+.IP "\fIRegular Expression Pocket Reference\fR" 4
+.IX Item "Regular Expression Pocket Reference"
+.Vb 4
+\& by Tony Stubblebine
+\& ISBN 978\-0\-596\-51427\-3 [2nd edition July 2007]
+\& ISBN 978\-0\-596\-55782\-9 [ebook]
+\& https://oreilly.com/catalog/9780596514273/
+.Ve
+.SS Tutorials
+.IX Subsection "Tutorials"
+.IP "\fIBeginning Perl\fR" 4
+.IX Item "Beginning Perl"
+(There are 2 books with this title)
+.Sp
+.Vb 3
+\& by Curtis \*(AqOvid\*(Aq Poe
+\& ISBN 978\-1\-118\-01384\-7
+\& http://www.wrox.com/WileyCDA/WroxTitle/productCd\-1118013840.html
+\&
+\& by James Lee
+\& ISBN 1\-59059\-391\-X [3rd edition April 2010 & ebook]
+\& https://www.apress.com/9781430227939
+.Ve
+.IP "\fILearning Perl\fR (the ""Llama Book"")" 4
+.IX Item "Learning Perl (the ""Llama Book"")"
+.Vb 4
+\& by Randal L. Schwartz, Tom Phoenix, and brian d foy
+\& ISBN 978\-1\-4493\-0358\-7 [6th edition June 2011]
+\& ISBN 978\-1\-4493\-0458\-4 [ebook]
+\& https://www.learning\-perl.com/
+.Ve
+.IP "\fIIntermediate Perl\fR (the ""Alpaca Book"")" 4
+.IX Item "Intermediate Perl (the ""Alpaca Book"")"
+.Vb 5
+\& by Randal L. Schwartz and brian d foy, with Tom Phoenix
+\&         foreword by Damian Conway
+\& ISBN 978\-1\-4493\-9309\-0 [2nd edition August 2012]
+\& ISBN 978\-1\-4493\-0459\-1 [ebook]
+\& https://www.intermediateperl.com/
+.Ve
+.IP "\fIMastering Perl\fR" 4
+.IX Item "Mastering Perl"
+.Vb 4
+\&    by brian d foy
+\& ISBN 9978\-1\-4493\-9311\-3 [2st edition January 2014]
+\& ISBN 978\-1\-4493\-6487\-8 [ebook]
+\& https://www.masteringperl.org/
+.Ve
+.IP "\fIEffective Perl Programming\fR" 4
+.IX Item "Effective Perl Programming"
+.Vb 3
+\& by Joseph N. Hall, Joshua A. McAdams, brian d foy
+\& ISBN 0\-321\-49694\-9 [2nd edition 2010]
+\& https://www.effectiveperlprogramming.com/
+.Ve
+.SS Task-Oriented
+.IX Subsection "Task-Oriented"
+.IP "\fIWriting Perl Modules for CPAN\fR" 4
+.IX Item "Writing Perl Modules for CPAN"
+.Vb 3
+\& by Sam Tregar
+\& ISBN 1\-59059\-018\-X [1st edition August 2002 & ebook]
+\& https://www.apress.com/9781590590188
+.Ve
+.IP "\fIThe Perl Cookbook\fR" 4
+.IX Item "The Perl Cookbook"
+.Vb 5
+\& by Tom Christiansen and Nathan Torkington,
+\&     with Foreword by Larry Wall
+\& ISBN 978\-0\-596\-00313\-5 [2nd Edition August 2003]
+\& ISBN 978\-0\-596\-15888\-0 [ebook]
+\& https://oreilly.com/catalog/9780596003135/
+.Ve
+.IP "\fIAutomating System Administration with Perl\fR" 4
+.IX Item "Automating System Administration with Perl"
+.Vb 4
+\& by David N. Blank\-Edelman
+\& ISBN 978\-0\-596\-00639\-6 [2nd edition May 2009]
+\& ISBN 978\-0\-596\-80251\-6 [ebook]
+\& https://oreilly.com/catalog/9780596006396
+.Ve
+.IP "\fIReal World SQL Server Administration with Perl\fR" 4
+.IX Item "Real World SQL Server Administration with Perl"
+.Vb 3
+\& by Linchi Shea
+\& ISBN 1\-59059\-097\-X [1st edition July 2003 & ebook]
+\& https://www.apress.com/9781590590973
+.Ve
+.SS "Special Topics"
+.IX Subsection "Special Topics"
+.IP "\fIRegular Expressions Cookbook\fR" 4
+.IX Item "Regular Expressions Cookbook"
+.Vb 4
+\& by Jan Goyvaerts and Steven Levithan
+\& ISBN 978\-1\-4493\-1943\-4 [2nd edition August 2012]
+\& ISBN 978\-1\-4493\-2747\-7 [ebook]
+\& https://shop.oreilly.com/product/0636920023630.do
+.Ve
+.IP "\fIProgramming the Perl DBI\fR" 4
+.IX Item "Programming the Perl DBI"
+.Vb 4
+\& by Tim Bunce and Alligator Descartes
+\& ISBN 978\-1\-56592\-699\-8 [February 2000]
+\& ISBN 978\-1\-4493\-8670\-2 [ebook]
+\& https://oreilly.com/catalog/9781565926998
+.Ve
+.IP "\fIPerl Best Practices\fR" 4
+.IX Item "Perl Best Practices"
+.Vb 4
+\& by Damian Conway
+\& ISBN 978\-0\-596\-00173\-5 [1st edition July 2005]
+\& ISBN 978\-0\-596\-15900\-9 [ebook]
+\& https://oreilly.com/catalog/9780596001735
+.Ve
+.IP "\fIHigher-Order Perl\fR" 4
+.IX Item "Higher-Order Perl"
+.Vb 4
+\& by Mark\-Jason Dominus
+\& ISBN 1\-55860\-701\-3 [1st edition March 2005]
+\& free ebook https://hop.perl.plover.com/book/
+\& https://hop.perl.plover.com/
+.Ve
+.IP "\fIMastering Regular Expressions\fR" 4
+.IX Item "Mastering Regular Expressions"
+.Vb 4
+\& by Jeffrey E. F. Friedl
+\& ISBN 978\-0\-596\-52812\-6 [3rd edition August 2006]
+\& ISBN 978\-0\-596\-55899\-4 [ebook]
+\& https://oreilly.com/catalog/9780596528126
+.Ve
+.IP "\fINetwork Programming with Perl\fR" 4
+.IX Item "Network Programming with Perl"
+.Vb 3
+\& by Lincoln Stein
+\& ISBN 0\-201\-61571\-1 [1st edition 2001]
+\& https://www.pearsonhighered.com/educator/product/Network\-Programming\-with\-Perl/9780201615715.page
+.Ve
+.IP "\fIPerl Template Toolkit\fR" 4
+.IX Item "Perl Template Toolkit"
+.Vb 4
+\& by Darren Chamberlain, Dave Cross, and Andy Wardley
+\& ISBN 978\-0\-596\-00476\-7 [December 2003]
+\& ISBN 978\-1\-4493\-8647\-4 [ebook]
+\& https://oreilly.com/catalog/9780596004767
+.Ve
+.IP "\fIObject Oriented Perl\fR" 4
+.IX Item "Object Oriented Perl"
+.Vb 4
+\& by Damian Conway
+\&     with foreword by Randal L. Schwartz
+\& ISBN 1\-884777\-79\-1 [1st edition August 1999 & ebook]
+\& https://www.manning.com/conway/
+.Ve
+.IP "\fIData Munging with Perl\fR" 4
+.IX Item "Data Munging with Perl"
+.Vb 3
+\& by Dave Cross
+\& ISBN 1\-930110\-00\-6 [1st edition 2001 & ebook]
+\& https://www.manning.com/cross
+.Ve
+.IP "\fIMastering Perl/Tk\fR" 4
+.IX Item "Mastering Perl/Tk"
+.Vb 4
+\& by Steve Lidie and Nancy Walsh
+\& ISBN 978\-1\-56592\-716\-2 [1st edition January 2002]
+\& ISBN 978\-0\-596\-10344\-6 [ebook]
+\& https://oreilly.com/catalog/9781565927162
+.Ve
+.IP "\fIExtending and Embedding Perl\fR" 4
+.IX Item "Extending and Embedding Perl"
+.Vb 3
+\& by Tim Jenness and Simon Cozens
+\& ISBN 1\-930110\-82\-0 [1st edition August 2002 & ebook]
+\& https://www.manning.com/jenness
+.Ve
+.IP "\fIPro Perl Debugging\fR" 4
+.IX Item "Pro Perl Debugging"
+.Vb 3
+\& by Richard Foley with Andy Lester
+\& ISBN 1\-59059\-454\-1 [1st edition July 2005 & ebook]
+\& https://www.apress.com/9781590594544
+.Ve
+.SS "Free (as in beer) books"
+.IX Subsection "Free (as in beer) books"
+Some of these books are available as free downloads.
+.PP
+\&\fIHigher-Order Perl\fR: <https://hop.perl.plover.com/>
+.PP
+\&\fIModern Perl\fR: <http://onyxneon.com/books/modern_perl/>
+.SS "Other interesting, non-Perl books"
+.IX Subsection "Other interesting, non-Perl books"
+You might notice several familiar Perl concepts in this collection of
+ACM columns from Jon Bentley. The similarity to the title of the major
+Perl book (which came later) is not completely accidental:
+.IP "\fIProgramming Pearls\fR" 4
+.IX Item "Programming Pearls"
+.Vb 2
+\& by Jon Bentley
+\& ISBN 978\-0\-201\-65788\-3 [2 edition, October 1999]
+.Ve
+.IP "\fIMore Programming Pearls\fR" 4
+.IX Item "More Programming Pearls"
+.Vb 2
+\& by Jon Bentley
+\& ISBN 0\-201\-11889\-0 [January 1988]
+.Ve
+.SS "A note on freshness"
+.IX Subsection "A note on freshness"
+Each version of Perl comes with the documentation that was current at
+the time of release. This poses a problem for content such as book
+lists. There are probably very nice books published after this list
+was included in your Perl release, and you can check the latest
+released version at <https://perldoc.perl.org/perlbook.html> .
+.PP
+Some of the books we've listed appear almost ancient in internet
+scale, but we've included those books because they still describe the
+current way of doing things. Not everything in Perl changes every day.
+Many of the beginner-level books, too, go over basic features and
+techniques that are still valid today. In general though, we try to
+limit this list to books published in the past five years.
+.SS "Get your book listed"
+.IX Subsection "Get your book listed"
+If your Perl book isn't listed and you think it should be, let us know.
+<mailto:perl5\-porters@perl.org>
diff --git a/upstream/mageia-cauldron/man1/perlboot.1 b/upstream/mageia-cauldron/man1/perlboot.1
new file mode 100644
index 00000000..80eaf6c7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlboot.1
@@ -0,0 +1,71 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBOOT 1"
+.TH PERLBOOT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlboot \- Links to information on object\-oriented programming in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+For information on OO programming with Perl, please see perlootut
+and perlobj.
+.PP
+(The above documents supersede the tutorial that was formerly here in
+perlboot.)
diff --git a/upstream/mageia-cauldron/man1/perlbot.1 b/upstream/mageia-cauldron/man1/perlbot.1
new file mode 100644
index 00000000..9bfe32b7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlbot.1
@@ -0,0 +1,71 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBOT 1"
+.TH PERLBOT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlbot \- Links to information on object\-oriented programming in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+For information on OO programming with Perl, please see perlootut
+and perlobj.
+.PP
+(The above documents supersede the collection of tricks that was formerly here
+in perlbot.)
diff --git a/upstream/mageia-cauldron/man1/perlbs2000.1 b/upstream/mageia-cauldron/man1/perlbs2000.1
new file mode 100644
index 00000000..894f4937
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlbs2000.1
@@ -0,0 +1,290 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBS2000 1"
+.TH PERLBS2000 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlbs2000 \- building and installing Perl for BS2000.
+.PP
+This document needs to be updated, but we don't know what it should say.
+Please submit comments to <https://github.com/Perl/perl5/issues>.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+This document will help you Configure, build, test and install Perl
+on BS2000 in the POSIX subsystem.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
+V3.1A or later.  It may work on other versions, but we started porting
+and testing it with 3.1A and are currently using Version V4.0A.
+.PP
+You may need the following GNU programs in order to install perl:
+.SS "gzip on BS2000"
+.IX Subsection "gzip on BS2000"
+We used version 1.2.4, which could be installed out of the box with
+one failure during 'make check'.
+.SS "bison on BS2000"
+.IX Subsection "bison on BS2000"
+The yacc coming with BS2000 POSIX didn't work for us.  So we had to
+use bison.  We had to make a few changes to perl in order to use the
+pure (reentrant) parser of bison.  We used version 1.25, but we had to
+add a few changes due to EBCDIC.  See below for more details
+concerning yacc.
+.SS "Unpacking Perl Distribution on BS2000"
+.IX Subsection "Unpacking Perl Distribution on BS2000"
+To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
+filesystem (we used the mountpoint /usr/local/ascii for this).  Now
+you extract the archive in the ASCII filesystem without
+I/O\-conversion:
+.PP
+cd /usr/local/ascii
+export IO_CONVERSION=NO
+gunzip < /usr/local/src/perl.tar.gz | pax \-r
+.PP
+You may ignore the error message for the first element of the archive
+(this doesn't look like a tar archive / skipping to next file...),
+it's only the directory which will be created automatically anyway.
+.PP
+After extracting the archive you copy the whole directory tree to your
+EBCDIC filesystem.  \fBThis time you use I/O\-conversion\fR:
+.PP
+cd /usr/local/src
+IO_CONVERSION=YES
+cp \-r /usr/local/ascii/perl5.005_02 ./
+.SS "Compiling Perl on BS2000"
+.IX Subsection "Compiling Perl on BS2000"
+There is a "hints" file for BS2000 called hints.posix\-bc (because
+posix-bc is the OS name given by `uname`) that specifies the correct
+values for most things.  The major problem is (of course) the EBCDIC
+character set.  We have german EBCDIC version.
+.PP
+Because of our problems with the native yacc we used GNU bison to
+generate a pure (=reentrant) parser for perly.y.  So our yacc is
+really the following script:
+.PP
+\&\-\-\-\-\-8<\-\-\-\-\-/usr/local/bin/yacc\-\-\-\-\-8<\-\-\-\-\-
+#! /usr/bin/sh
+.PP
+# Bison as a reentrant yacc:
+.PP
+# save parameters:
+params=""
+while [[ $# \-gt 1 ]]; do
+    params="$params \f(CW$1\fR"
+    shift
+done
+.PP
+# add flag \f(CW%pure_parser:\fR
+.PP
+tmpfile=/tmp/bison.$$.y
+echo \f(CW%pure_parser\fR > \f(CW$tmpfile\fR
+cat \f(CW$1\fR >> \f(CW$tmpfile\fR
+.PP
+# call bison:
+.PP
+echo "/usr/local/bin/bison \-\-yacc \f(CW$params\fR \f(CW$1\fR\et\et\et(Pure Parser)"
+/usr/local/bin/bison \-\-yacc \f(CW$params\fR \f(CW$tmpfile\fR
+.PP
+# cleanup:
+.PP
+rm \-f \f(CW$tmpfile\fR
+\&\-\-\-\-\-8<\-\-\-\-\-\-\-\-\-\-8<\-\-\-\-\-
+.PP
+We still use the normal yacc for a2p.y though!!!  We made a softlink
+called byacc to distinguish between the two versions:
+.PP
+ln \-s /usr/bin/yacc /usr/local/bin/byacc
+.PP
+We build perl using GNU make.  We tried the native make once and it
+worked too.
+.SS "Testing Perl on BS2000"
+.IX Subsection "Testing Perl on BS2000"
+We still got a few errors during \f(CW\*(C`make test\*(C'\fR.  Some of them are the
+result of using bison.  Bison prints \fIparser error\fR instead of \fIsyntax
+error\fR, so we may ignore them.  The following list shows
+our errors, your results may differ:
+.PP
+op/numconvert.......FAILED tests 1409\-1440
+op/regexp...........FAILED tests 483, 496
+op/regexp_noamp.....FAILED tests 483, 496
+pragma/overload.....FAILED tests 152\-153, 170\-171
+pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
+lib/bigfloat........FAILED tests 351\-352, 355
+lib/bigfltpm........FAILED tests 354\-355, 358
+lib/complex.........FAILED tests 267, 487
+lib/dumper..........FAILED tests 43, 45
+Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
+.SS "Installing Perl on BS2000"
+.IX Subsection "Installing Perl on BS2000"
+We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
+installing the documentation.
+.SS "Using Perl in the Posix-Shell of BS2000"
+.IX Subsection "Using Perl in the Posix-Shell of BS2000"
+BS2000 POSIX doesn't support the shebang notation
+(\f(CW\*(C`#!/usr/local/bin/perl\*(C'\fR), so you have to use the following lines
+instead:
+.PP
+: # use perl
+    eval 'exec /usr/local/bin/perl \-S \f(CW$0\fR ${1+"$@"}'
+        if 0; # ^ Run only under a shell
+.SS "Using Perl in ""native"" BS2000"
+.IX Subsection "Using Perl in ""native"" BS2000"
+We don't have much experience with this yet, but try the following:
+.PP
+Copy your Perl executable to a BS2000 LLM using bs2cp:
+.PP
+\&\f(CW\*(C`bs2cp /usr/local/bin/perl \*(Aqbs2:perl(perl,l)\*(Aq\*(C'\fR
+.PP
+Now you can start it with the following (SDF) command:
+.PP
+\&\f(CW\*(C`/START\-PROG FROM\-FILE=*MODULE(PERL,PERL),PROG\-MODE=*ANY,RUN\-MODE=*ADV\*(C'\fR
+.PP
+First you get the BS2000 commandline prompt ('*').  Here you may enter
+your parameters, e.g. \f(CW\*(C`\-e \*(Aqprint "Hello World!\e\en";\*(Aq\*(C'\fR (note the
+double backslash!) or \f(CW\*(C`\-w\*(C'\fR and the name of your Perl script.
+Filenames starting with \f(CW\*(C`/\*(C'\fR are searched in the Posix filesystem,
+others are searched in the BS2000 filesystem.  You may even use
+wildcards if you put a \f(CW\*(C`%\*(C'\fR in front of your filename (e.g. \f(CW\*(C`\-w
+checkfiles.pl %*.c\*(C'\fR).  Read your C/C++ manual for additional
+possibilities of the commandline prompt (look for
+PARAMETER-PROMPTING).
+.SS "Floating point anomalies on BS2000"
+.IX Subsection "Floating point anomalies on BS2000"
+There appears to be a bug in the floating point implementation on BS2000 POSIX
+systems such that calling \fBint()\fR on the product of a number and a small
+magnitude number is not the same as calling \fBint()\fR on the quotient of
+that number and a large magnitude number.  For example, in the following
+Perl code:
+.PP
+.Vb 4
+\&    my $x = 100000.0;
+\&    my $y = int($x * 1e\-5) * 1e5; # \*(Aq0\*(Aq
+\&    my $z = int($x / 1e+5) * 1e5;  # \*(Aq100000\*(Aq
+\&    print "\e$y is $y and \e$z is $z\en"; # $y is 0 and $z is 100000
+.Ve
+.PP
+Although one would expect the quantities \f(CW$y\fR and \f(CW$z\fR to be the same and equal
+to 100000 they will differ and instead will be 0 and 100000 respectively.
+.SS "Using PerlIO and different encodings on ASCII and EBCDIC partitions"
+.IX Subsection "Using PerlIO and different encodings on ASCII and EBCDIC partitions"
+Since version 5.8 Perl uses the new PerlIO on BS2000.  This enables
+you using different encodings per IO channel.  For example you may use
+.PP
+.Vb 9
+\&    use Encode;
+\&    open($f, ">:encoding(ascii)", "test.ascii");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(posix\-bc)", "test.ebcdic");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(latin1)", "test.latin1");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(utf8)", "test.utf8");
+\&    print $f "Hello World!\en";
+.Ve
+.PP
+to get two files containing "Hello World!\en" in ASCII, EBCDIC, ISO
+Latin\-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
+this example identical to normal EBCDIC).  See the documentation of
+Encode::PerlIO for details.
+.PP
+As the PerlIO layer uses raw IO internally, all this totally ignores
+the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
+environment variable.  If you want to get the old behavior, that the
+BS2000 IO functions determine conversion depending on the filesystem
+PerlIO still is your friend.  You use IO_CONVERSION as usual and tell
+Perl, that it should use the native IO layer:
+.PP
+.Vb 2
+\&    export IO_CONVERSION=YES
+\&    export PERLIO=stdio
+.Ve
+.PP
+Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
+partitions.  See the documentation of PerlIO (without \f(CW\*(C`Encode::\*(C'\fR!)
+for further possibilities.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Thomas Dorner
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+INSTALL, perlport.
+.SS "Mailing list"
+.IX Subsection "Mailing list"
+If you are interested in the z/OS (formerly known as OS/390)
+and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
+To subscribe, send an empty message to perl\-mvs\-subscribe@perl.org.
+.PP
+See also:
+.PP
+.Vb 1
+\&    https://lists.perl.org/list/perl\-mvs.html
+.Ve
+.PP
+There are web archives of the mailing list at:
+.PP
+.Vb 1
+\&    https://www.nntp.perl.org/group/perl.mvs/
+.Ve
+.SH HISTORY
+.IX Header "HISTORY"
+This document was originally written by Thomas Dorner for the 5.005
+release of Perl.
+.PP
+This document was podified for the 5.6 release of perl 11 July 2000.
diff --git a/upstream/mageia-cauldron/man1/perlbug.1 b/upstream/mageia-cauldron/man1/perlbug.1
new file mode 100644
index 00000000..2999f89a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlbug.1
@@ -0,0 +1,331 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBUG 1"
+.TH PERLBUG 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlbug \- how to submit bug reports on Perl
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBperlbug\fR
+.PP
+\&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-a\fR\ \fIaddress\fR\ ] [\ \fB\-s\fR\ \fIsubject\fR\ ]
+[\ \fB\-b\fR\ \fIbody\fR\ |\ \fB\-f\fR\ \fIinputfile\fR\ ] [\ \fB\-F\fR\ \fIoutputfile\fR\ ]
+[\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
+[\ \fB\-e\fR\ \fIeditor\fR\ ] [\ \fB\-c\fR\ \fIadminaddress\fR\ |\ \fB\-C\fR\ ]
+[\ \fB\-S\fR\ ] [\ \fB\-t\fR\ ]  [\ \fB\-d\fR\ ]  [\ \fB\-h\fR\ ] [\ \fB\-T\fR\ ]
+.PP
+\&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
+ [\ \fB\-ok\fR\ |\ \fB\-okay\fR\ |\ \fB\-nok\fR\ |\ \fB\-nokay\fR\ ]
+.PP
+\&\fBperlthanks\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This program is designed to help you generate bug reports
+(and thank-you notes) about perl5 and the modules which ship with it.
+.PP
+In most cases, you can just run it interactively from a command
+line without any special arguments and follow the prompts.
+.PP
+If you have found a bug with a non-standard port (one that was not
+part of the \fIstandard distribution\fR), a binary distribution, or a
+non-core module (such as Tk, DBI, etc), then please see the
+documentation that came with that distribution to determine the
+correct place to report bugs.
+.PP
+Bug reports should be submitted to the GitHub issue tracker at
+<https://github.com/Perl/perl5/issues>. The \fBperlbug@perl.org\fR
+address no longer automatically opens tickets. You can use this tool
+to compose your report and save it to a file which you can then submit
+to the issue tracker.
+.PP
+In extreme cases, \fBperlbug\fR may not work well enough on your system
+to guide you through composing a bug report. In those cases, you
+may be able to use \fBperlbug \-d\fR or \fBperl \-V\fR to get system
+configuration information to include in your issue report.
+.PP
+When reporting a bug, please run through this checklist:
+.IP "What version of Perl you are running?" 4
+.IX Item "What version of Perl you are running?"
+Type \f(CW\*(C`perl \-v\*(C'\fR at the command line to find out.
+.IP "Are you running the latest released version of perl?" 4
+.IX Item "Are you running the latest released version of perl?"
+Look at <http://www.perl.org/> to find out.  If you are not using the
+latest released version, please try to replicate your bug on the
+latest stable release.
+.Sp
+Note that reports about bugs in old versions of Perl, especially
+those which indicate you haven't also tested the current stable
+release of Perl, are likely to receive less attention from the
+volunteers who build and maintain Perl than reports about bugs in
+the current release.
+.IP "Are you sure what you have is a bug?" 4
+.IX Item "Are you sure what you have is a bug?"
+A significant number of the bug reports we get turn out to be
+documented features in Perl.  Make sure the issue you've run into
+isn't intentional by glancing through the documentation that comes
+with the Perl distribution.
+.Sp
+Given the sheer volume of Perl documentation, this isn't a trivial
+undertaking, but if you can point to documentation that suggests
+the behaviour you're seeing is \fIwrong\fR, your issue is likely to
+receive more attention. You may want to start with \fBperldoc\fR
+perltrap for pointers to common traps that new (and experienced)
+Perl programmers run into.
+.Sp
+If you're unsure of the meaning of an error message you've run
+across, \fBperldoc\fR perldiag for an explanation.  If the message
+isn't in perldiag, it probably isn't generated by Perl.  You may
+have luck consulting your operating system documentation instead.
+.Sp
+If you are on a non-UNIX platform \fBperldoc\fR perlport, as some
+features may be unimplemented or work differently.
+.Sp
+You may be able to figure out what's going wrong using the Perl
+debugger.  For information about how to use the debugger \fBperldoc\fR
+perldebug.
+.IP "Do you have a proper test case?" 4
+.IX Item "Do you have a proper test case?"
+The easier it is to reproduce your bug, the more likely it will be
+fixed \-\- if nobody can duplicate your problem, it probably won't be 
+addressed.
+.Sp
+A good test case has most of these attributes: short, simple code;
+few dependencies on external commands, modules, or libraries; no
+platform-dependent code (unless it's a platform-specific bug);
+clear, simple documentation.
+.Sp
+A good test case is almost always a good candidate to be included in
+Perl's test suite.  If you have the time, consider writing your test case so
+that it can be easily included into the standard test suite.
+.IP "Have you included all relevant information?" 4
+.IX Item "Have you included all relevant information?"
+Be sure to include the \fBexact\fR error messages, if any.
+"Perl gave an error" is not an exact error message.
+.Sp
+If you get a core dump (or equivalent), you may use a debugger
+(\fBdbx\fR, \fBgdb\fR, etc) to produce a stack trace to include in the bug
+report.
+.Sp
+NOTE: unless your Perl has been compiled with debug info
+(often \fB\-g\fR), the stack trace is likely to be somewhat hard to use
+because it will most probably contain only the function names and not
+their arguments.  If possible, recompile your Perl with debug info and
+reproduce the crash and the stack trace.
+.IP "Can you describe the bug in plain English?" 4
+.IX Item "Can you describe the bug in plain English?"
+The easier it is to understand a reproducible bug, the more likely
+it will be fixed.  Any insight you can provide into the problem
+will help a great deal.  In other words, try to analyze the problem
+(to the extent you can) and report your discoveries.
+.IP "Can you fix the bug yourself?" 4
+.IX Item "Can you fix the bug yourself?"
+If so, that's great news; bug reports with patches are likely to
+receive significantly more attention and interest than those without
+patches.  Please submit your patch via the GitHub Pull Request workflow
+as described in \fBperldoc\fR perlhack.  You may also send patches to
+\&\fBperl5\-porters@perl.org\fR.  When sending a patch, create it using
+\&\f(CW\*(C`git format\-patch\*(C'\fR if possible, though a unified diff created with
+\&\f(CW\*(C`diff \-pu\*(C'\fR will do nearly as well.
+.Sp
+Your patch may be returned with requests for changes, or requests for more
+detailed explanations about your fix.
+.Sp
+Here are a few hints for creating high-quality patches:
+.Sp
+Make sure the patch is not reversed (the first argument to diff is
+typically the original file, the second argument your changed file).
+Make sure you test your patch by applying it with \f(CW\*(C`git am\*(C'\fR or the
+\&\f(CW\*(C`patch\*(C'\fR program before you send it on its way.  Try to follow the
+same style as the code you are trying to patch.  Make sure your patch
+really does work (\f(CW\*(C`make test\*(C'\fR, if the thing you're patching is covered
+by Perl's test suite).
+.ie n .IP "Can you use ""perlbug"" to submit a thank-you note?" 4
+.el .IP "Can you use \f(CWperlbug\fR to submit a thank-you note?" 4
+.IX Item "Can you use perlbug to submit a thank-you note?"
+Yes, you can do this by either using the \f(CW\*(C`\-T\*(C'\fR option, or by invoking
+the program as \f(CW\*(C`perlthanks\*(C'\fR. Thank-you notes are good. It makes people
+smile.
+.PP
+Please make your issue title informative.  "a bug" is not informative.
+Neither is "perl crashes" nor is "HELP!!!".  These don't help.  A compact
+description of what's wrong is fine.
+.PP
+Having done your bit, please be prepared to wait, to be told the
+bug is in your code, or possibly to get no reply at all.  The
+volunteers who maintain Perl are busy folks, so if your problem is
+an obvious bug in your own code, is difficult to understand or is
+a duplicate of an existing report, you may not receive a personal
+reply.
+.PP
+If it is important to you that your bug be fixed, do monitor the
+issue tracker (you will be subscribed to notifications for issues you
+submit or comment on) and the commit logs to development
+versions of Perl, and encourage the maintainers with kind words or
+offers of frosty beverages.  (Please do be kind to the maintainers.
+Harassing or flaming them is likely to have the opposite effect of the
+one you want.)
+.PP
+Feel free to update the ticket about your bug on
+<https://github.com/Perl/perl5/issues>
+if a new version of Perl is released and your bug is still present.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \fB\-a\fR 8
+.IX Item "-a"
+Address to send the report to instead of saving to a file.
+.IP \fB\-b\fR 8
+.IX Item "-b"
+Body of the report.  If not included on the command line, or
+in a file with \fB\-f\fR, you will get a chance to edit the report.
+.IP \fB\-C\fR 8
+.IX Item "-C"
+Don't send copy to administrator when sending report by mail.
+.IP \fB\-c\fR 8
+.IX Item "-c"
+Address to send copy of report to when sending report by mail.
+Defaults to the address of the
+local perl administrator (recorded when perl was built).
+.IP \fB\-d\fR 8
+.IX Item "-d"
+Data mode (the default if you redirect or pipe output).  This prints out
+your configuration data, without saving or mailing anything.  You can use
+this with \fB\-v\fR to get more complete data.
+.IP \fB\-e\fR 8
+.IX Item "-e"
+Editor to use.
+.IP \fB\-f\fR 8
+.IX Item "-f"
+File containing the body of the report.  Use this to quickly send a
+prepared report.
+.IP \fB\-F\fR 8
+.IX Item "-F"
+File to output the results to.  Defaults to \fBperlbug.rep\fR.
+.IP \fB\-h\fR 8
+.IX Item "-h"
+Prints a brief summary of the options.
+.IP \fB\-ok\fR 8
+.IX Item "-ok"
+Report successful build on this system to perl porters. Forces \fB\-S\fR
+and \fB\-C\fR. Forces and supplies values for \fB\-s\fR and \fB\-b\fR. Only
+prompts for a return address if it cannot guess it (for use with
+\&\fBmake\fR). Honors return address specified with \fB\-r\fR.  You can use this
+with \fB\-v\fR to get more complete data.   Only makes a report if this
+system is less than 60 days old.
+.IP \fB\-okay\fR 8
+.IX Item "-okay"
+As \fB\-ok\fR except it will report on older systems.
+.IP \fB\-nok\fR 8
+.IX Item "-nok"
+Report unsuccessful build on this system.  Forces \fB\-C\fR.  Forces and
+supplies a value for \fB\-s\fR, then requires you to edit the report
+and say what went wrong.  Alternatively, a prepared report may be
+supplied using \fB\-f\fR.  Only prompts for a return address if it
+cannot guess it (for use with \fBmake\fR). Honors return address
+specified with \fB\-r\fR.  You can use this with \fB\-v\fR to get more
+complete data.  Only makes a report if this system is less than 60
+days old.
+.IP \fB\-nokay\fR 8
+.IX Item "-nokay"
+As \fB\-nok\fR except it will report on older systems.
+.IP \fB\-p\fR 8
+.IX Item "-p"
+The names of one or more patch files or other text attachments to be
+included with the report.  Multiple files must be separated with commas.
+.IP \fB\-r\fR 8
+.IX Item "-r"
+Your return address.  The program will ask you to confirm its default
+if you don't use this option.
+.IP \fB\-S\fR 8
+.IX Item "-S"
+Save or send the report without asking for confirmation.
+.IP \fB\-s\fR 8
+.IX Item "-s"
+Subject to include with the report.  You will be prompted if you don't
+supply one on the command line.
+.IP \fB\-t\fR 8
+.IX Item "-t"
+Test mode.  Makes it possible to command perlbug from a pipe or file, for
+testing purposes.
+.IP \fB\-T\fR 8
+.IX Item "-T"
+Send a thank-you note instead of a bug report.
+.IP \fB\-v\fR 8
+.IX Item "-v"
+Include verbose configuration data in the report.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Kenneth Albanowski (<kjahds@kjahds.com>), subsequently
+\&\fIdoc\fRtored by Gurusamy Sarathy (<gsar@activestate.com>),
+Tom Christiansen (<tchrist@perl.com>), Nathan Torkington
+(<gnat@frii.com>), Charles F. Randall (<cfr@pobox.com>),
+Mike Guy (<mjtg@cam.ac.uk>), Dominic Dunlop
+(<domo@computer.org>), Hugo van der Sanden (<hv@crypt.org>),
+Jarkko Hietaniemi (<jhi@iki.fi>), Chris Nandor
+(<pudge@pobox.com>), Jon Orwant (<orwant@media.mit.edu>,
+Richard Foley (<richard.foley@rfi.net>), Jesse Vincent
+(<jesse@bestpractical.com>), and Craig A. Berry (<craigberry@mac.com>).
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1), \fBperldebug\fR\|(1), \fBperldiag\fR\|(1), \fBperlport\fR\|(1), \fBperltrap\fR\|(1),
+\&\fBdiff\fR\|(1), \fBpatch\fR\|(1), \fBdbx\fR\|(1), \fBgdb\fR\|(1)
+.SH BUGS
+.IX Header "BUGS"
+None known (guess what must have been used to report them?)
diff --git a/upstream/mageia-cauldron/man1/perlcall.1 b/upstream/mageia-cauldron/man1/perlcall.1
new file mode 100644
index 00000000..8c1da949
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcall.1
@@ -0,0 +1,2001 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCALL 1"
+.TH PERLCALL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlcall \- Perl calling conventions from C
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The purpose of this document is to show you how to call Perl subroutines
+directly from C, i.e., how to write \fIcallbacks\fR.
+.PP
+Apart from discussing the C interface provided by Perl for writing
+callbacks the document uses a series of examples to show how the
+interface actually works in practice.  In addition some techniques for
+coding callbacks are covered.
+.PP
+Examples where callbacks are necessary include
+.IP \(bu 5
+An Error Handler
+.Sp
+You have created an XSUB interface to an application's C API.
+.Sp
+A fairly common feature in applications is to allow you to define a C
+function that will be called whenever something nasty occurs. What we
+would like is to be able to specify a Perl subroutine that will be
+called instead.
+.IP \(bu 5
+An Event-Driven Program
+.Sp
+The classic example of where callbacks are used is when writing an
+event driven program, such as for an X11 application.  In this case
+you register functions to be called whenever specific events occur,
+e.g., a mouse button is pressed, the cursor moves into a window or a
+menu item is selected.
+.PP
+Although the techniques described here are applicable when embedding
+Perl in a C program, this is not the primary goal of this document.
+There are other details that must be considered and are specific to
+embedding Perl. For details on embedding Perl in C refer to
+perlembed.
+.PP
+Before you launch yourself head first into the rest of this document,
+it would be a good idea to have read the following two documents\-\-perlxs
+and perlguts.
+.SH "THE CALL_ FUNCTIONS"
+.IX Header "THE CALL_ FUNCTIONS"
+Although this stuff is easier to explain using examples, you first need
+be aware of a few important definitions.
+.PP
+Perl has a number of C functions that allow you to call Perl
+subroutines.  They are
+.PP
+.Vb 4
+\&    I32 call_sv(SV* sv, I32 flags);
+\&    I32 call_pv(char *subname, I32 flags);
+\&    I32 call_method(char *methname, I32 flags);
+\&    I32 call_argv(char *subname, I32 flags, char **argv);
+.Ve
+.PP
+The key function is \fIcall_sv\fR.  All the other functions are
+fairly simple wrappers which make it easier to call Perl subroutines in
+special cases. At the end of the day they will all call \fIcall_sv\fR
+to invoke the Perl subroutine.
+.PP
+All the \fIcall_*\fR functions have a \f(CW\*(C`flags\*(C'\fR parameter which is
+used to pass a bit mask of options to Perl.  This bit mask operates
+identically for each of the functions.  The settings available in the
+bit mask are discussed in "FLAG VALUES".
+.PP
+Each of the functions will now be discussed in turn.
+.IP call_sv 5
+.IX Item "call_sv"
+\&\fIcall_sv\fR takes two parameters. The first, \f(CW\*(C`sv\*(C'\fR, is an SV*.
+This allows you to specify the Perl subroutine to be called either as a
+C string (which has first been converted to an SV) or a reference to a
+subroutine. The section, "Using call_sv", shows how you can make
+use of \fIcall_sv\fR.
+.IP call_pv 5
+.IX Item "call_pv"
+The function, \fIcall_pv\fR, is similar to \fIcall_sv\fR except it
+expects its first parameter to be a C char* which identifies the Perl
+subroutine you want to call, e.g., \f(CW\*(C`call_pv("fred", 0)\*(C'\fR.  If the
+subroutine you want to call is in another package, just include the
+package name in the string, e.g., \f(CW"pkg::fred"\fR.
+.IP call_method 5
+.IX Item "call_method"
+The function \fIcall_method\fR is used to call a method from a Perl
+class.  The parameter \f(CW\*(C`methname\*(C'\fR corresponds to the name of the method
+to be called.  Note that the class that the method belongs to is passed
+on the Perl stack rather than in the parameter list. This class can be
+either the name of the class (for a static method) or a reference to an
+object (for a virtual method).  See perlobj for more information on
+static and virtual methods and "Using call_method" for an example
+of using \fIcall_method\fR.
+.IP call_argv 5
+.IX Item "call_argv"
+\&\fIcall_argv\fR calls the Perl subroutine specified by the C string
+stored in the \f(CW\*(C`subname\*(C'\fR parameter. It also takes the usual \f(CW\*(C`flags\*(C'\fR
+parameter.  The final parameter, \f(CW\*(C`argv\*(C'\fR, consists of a NULL-terminated
+list of C strings to be passed as parameters to the Perl subroutine.
+See "Using call_argv".
+.PP
+All the functions return an integer. This is a count of the number of
+items returned by the Perl subroutine. The actual items returned by the
+subroutine are stored on the Perl stack.
+.PP
+As a general rule you should \fIalways\fR check the return value from
+these functions.  Even if you are expecting only a particular number of
+values to be returned from the Perl subroutine, there is nothing to
+stop someone from doing something unexpected\-\-don't say you haven't
+been warned.
+.SH "FLAG VALUES"
+.IX Header "FLAG VALUES"
+The \f(CW\*(C`flags\*(C'\fR parameter in all the \fIcall_*\fR functions is one of \f(CW\*(C`G_VOID\*(C'\fR,
+\&\f(CW\*(C`G_SCALAR\*(C'\fR, or \f(CW\*(C`G_LIST\*(C'\fR, which indicate the call context, OR'ed together
+with a bit mask of any combination of the other G_* symbols defined below.
+.SS G_VOID
+.IX Subsection "G_VOID"
+Calls the Perl subroutine in a void context.
+.PP
+This flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in
+a void context (if it executes \fIwantarray\fR the result will be the
+undefined value).
+.IP 2. 5
+It ensures that nothing is actually returned from the subroutine.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine\-\-in this case it will
+be 0.
+.SS G_SCALAR
+.IX Subsection "G_SCALAR"
+Calls the Perl subroutine in a scalar context.  This is the default
+context flag setting for all the \fIcall_*\fR functions.
+.PP
+This flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in a
+scalar context (if it executes \fIwantarray\fR the result will be false).
+.IP 2. 5
+It ensures that only a scalar is actually returned from the subroutine.
+The subroutine can, of course,  ignore the \fIwantarray\fR and return a
+list anyway. If so, then only the last element of the list will be
+returned.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine \- in this case it will
+be either 0 or 1.
+.PP
+If 0, then you have specified the G_DISCARD flag.
+.PP
+If 1, then the item actually returned by the Perl subroutine will be
+stored on the Perl stack \- the section "Returning a Scalar" shows how
+to access this value on the stack.  Remember that regardless of how
+many items the Perl subroutine returns, only the last one will be
+accessible from the stack \- think of the case where only one value is
+returned as being a list with only one element.  Any other items that
+were returned will not exist by the time control returns from the
+\&\fIcall_*\fR function.  The section "Returning a List in Scalar
+Context" shows an example of this behavior.
+.SS G_LIST
+.IX Subsection "G_LIST"
+Calls the Perl subroutine in a list context. Prior to Perl version
+5.35.1 this was called \f(CW\*(C`G_ARRAY\*(C'\fR.
+.PP
+As with G_SCALAR, this flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in a
+list context (if it executes \fIwantarray\fR the result will be true).
+.IP 2. 5
+It ensures that all items returned from the subroutine will be
+accessible when control returns from the \fIcall_*\fR function.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine.
+.PP
+If 0, then you have specified the G_DISCARD flag.
+.PP
+If not 0, then it will be a count of the number of items returned by
+the subroutine. These items will be stored on the Perl stack.  The
+section "Returning a List of Values" gives an example of using the
+G_LIST flag and the mechanics of accessing the returned items from the
+Perl stack.
+.SS G_DISCARD
+.IX Subsection "G_DISCARD"
+By default, the \fIcall_*\fR functions place the items returned from
+by the Perl subroutine on the stack.  If you are not interested in
+these items, then setting this flag will make Perl get rid of them
+automatically for you.  Note that it is still possible to indicate a
+context to the Perl subroutine by using either G_SCALAR or G_LIST.
+.PP
+If you do not set this flag then it is \fIvery\fR important that you make
+sure that any temporaries (i.e., parameters passed to the Perl
+subroutine and values returned from the subroutine) are disposed of
+yourself.  The section "Returning a Scalar" gives details of how to
+dispose of these temporaries explicitly and the section "Using Perl to
+Dispose of Temporaries" discusses the specific circumstances where you
+can ignore the problem and let Perl deal with it for you.
+.SS G_NOARGS
+.IX Subsection "G_NOARGS"
+Whenever a Perl subroutine is called using one of the \fIcall_*\fR
+functions, it is assumed by default that parameters are to be passed to
+the subroutine.  If you are not passing any parameters to the Perl
+subroutine, you can save a bit of time by setting this flag.  It has
+the effect of not creating the \f(CW@_\fR array for the Perl subroutine.
+.PP
+Although the functionality provided by this flag may seem
+straightforward, it should be used only if there is a good reason to do
+so.  The reason for being cautious is that, even if you have specified
+the G_NOARGS flag, it is still possible for the Perl subroutine that
+has been called to think that you have passed it parameters.
+.PP
+In fact, what can happen is that the Perl subroutine you have called
+can access the \f(CW@_\fR array from a previous Perl subroutine.  This will
+occur when the code that is executing the \fIcall_*\fR function has
+itself been called from another Perl subroutine. The code below
+illustrates this
+.PP
+.Vb 2
+\&    sub fred
+\&      { print "@_\en"  }
+\&
+\&    sub joe
+\&      { &fred }
+\&
+\&    &joe(1,2,3);
+.Ve
+.PP
+This will print
+.PP
+.Vb 1
+\&    1 2 3
+.Ve
+.PP
+What has happened is that \f(CW\*(C`fred\*(C'\fR accesses the \f(CW@_\fR array which
+belongs to \f(CW\*(C`joe\*(C'\fR.
+.SS G_EVAL
+.IX Subsection "G_EVAL"
+It is possible for the Perl subroutine you are calling to terminate
+abnormally, e.g., by calling \fIdie\fR explicitly or by not actually
+existing.  By default, when either of these events occurs, the
+process will terminate immediately.  If you want to trap this
+type of event, specify the G_EVAL flag.  It will put an \fIeval { }\fR
+around the subroutine call.
+.PP
+Whenever control returns from the \fIcall_*\fR function you need to
+check the \f(CW$@\fR variable as you would in a normal Perl script.
+.PP
+The value returned from the \fIcall_*\fR function is dependent on
+what other flags have been specified and whether an error has
+occurred.  Here are all the different cases that can occur:
+.IP \(bu 5
+If the \fIcall_*\fR function returns normally, then the value
+returned is as specified in the previous sections.
+.IP \(bu 5
+If G_DISCARD is specified, the return value will always be 0.
+.IP \(bu 5
+If G_LIST is specified \fIand\fR an error has occurred, the return value
+will always be 0.
+.IP \(bu 5
+If G_SCALAR is specified \fIand\fR an error has occurred, the return value
+will be 1 and the value on the top of the stack will be \fIundef\fR. This
+means that if you have already detected the error by checking \f(CW$@\fR and
+you want the program to continue, you must remember to pop the \fIundef\fR
+from the stack.
+.PP
+See "Using G_EVAL" for details on using G_EVAL.
+.SS G_KEEPERR
+.IX Subsection "G_KEEPERR"
+Using the G_EVAL flag described above will always set \f(CW$@\fR: clearing
+it if there was no error, and setting it to describe the error if there
+was an error in the called code.  This is what you want if your intention
+is to handle possible errors, but sometimes you just want to trap errors
+and stop them interfering with the rest of the program.
+.PP
+This scenario will mostly be applicable to code that is meant to be called
+from within destructors, asynchronous callbacks, and signal handlers.
+In such situations, where the code being called has little relation to the
+surrounding dynamic context, the main program needs to be insulated from
+errors in the called code, even if they can't be handled intelligently.
+It may also be useful to do this with code for \f(CW\*(C`_\|_DIE_\|_\*(C'\fR or \f(CW\*(C`_\|_WARN_\|_\*(C'\fR
+hooks, and \f(CW\*(C`tie\*(C'\fR functions.
+.PP
+The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
+\&\fIcall_*\fR functions that are used to implement such code, or with
+\&\f(CW\*(C`eval_sv\*(C'\fR.  This flag has no effect on the \f(CW\*(C`call_*\*(C'\fR functions when
+G_EVAL is not used.
+.PP
+When G_KEEPERR is used, any error in the called code will terminate the
+call as usual, and the error will not propagate beyond the call (as usual
+for G_EVAL), but it will not go into \f(CW$@\fR.  Instead the error will be
+converted into a warning, prefixed with the string "\et(in cleanup)".
+This can be disabled using \f(CW\*(C`no warnings \*(Aqmisc\*(Aq\*(C'\fR.  If there is no error,
+\&\f(CW$@\fR will not be cleared.
+.PP
+Note that the G_KEEPERR flag does not propagate into inner evals; these
+may still set \f(CW$@\fR.
+.PP
+The G_KEEPERR flag was introduced in Perl version 5.002.
+.PP
+See "Using G_KEEPERR" for an example of a situation that warrants the
+use of this flag.
+.SS "Determining the Context"
+.IX Subsection "Determining the Context"
+As mentioned above, you can determine the context of the currently
+executing subroutine in Perl with \fIwantarray\fR.  The equivalent test
+can be made in C by using the \f(CW\*(C`GIMME_V\*(C'\fR macro, which returns
+\&\f(CW\*(C`G_LIST\*(C'\fR if you have been called in a list context, \f(CW\*(C`G_SCALAR\*(C'\fR if
+in a scalar context, or \f(CW\*(C`G_VOID\*(C'\fR if in a void context (i.e., the
+return value will not be used).  An older version of this macro is
+called \f(CW\*(C`GIMME\*(C'\fR; in a void context it returns \f(CW\*(C`G_SCALAR\*(C'\fR instead of
+\&\f(CW\*(C`G_VOID\*(C'\fR.  An example of using the \f(CW\*(C`GIMME_V\*(C'\fR macro is shown in
+section "Using GIMME_V".
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+Enough of the definition talk! Let's have a few examples.
+.PP
+Perl provides many macros to assist in accessing the Perl stack.
+Wherever possible, these macros should always be used when interfacing
+to Perl internals.  We hope this should make the code less vulnerable
+to any changes made to Perl in the future.
+.PP
+Another point worth noting is that in the first series of examples I
+have made use of only the \fIcall_pv\fR function.  This has been done
+to keep the code simpler and ease you into the topic.  Wherever
+possible, if the choice is between using \fIcall_pv\fR and
+\&\fIcall_sv\fR, you should always try to use \fIcall_sv\fR.  See
+"Using call_sv" for details.
+.SS "No Parameters, Nothing Returned"
+.IX Subsection "No Parameters, Nothing Returned"
+This first trivial example will call a Perl subroutine, \fIPrintUID\fR, to
+print out the UID of the process.
+.PP
+.Vb 4
+\&    sub PrintUID
+\&    {
+\&        print "UID is $<\en";
+\&    }
+.Ve
+.PP
+and here is a C function to call it
+.PP
+.Vb 4
+\&    static void
+\&    call_PrintUID()
+\&    {
+\&        dSP;
+\&
+\&        PUSHMARK(SP);
+\&        call_pv("PrintUID", G_DISCARD|G_NOARGS);
+\&    }
+.Ve
+.PP
+Simple, eh?
+.PP
+A few points to note about this example:
+.IP 1. 5
+Ignore \f(CW\*(C`dSP\*(C'\fR and \f(CWPUSHMARK(SP)\fR for now. They will be discussed in
+the next example.
+.IP 2. 5
+We aren't passing any parameters to \fIPrintUID\fR so G_NOARGS can be
+specified.
+.IP 3. 5
+We aren't interested in anything returned from \fIPrintUID\fR, so
+G_DISCARD is specified. Even if \fIPrintUID\fR was changed to
+return some value(s), having specified G_DISCARD will mean that they
+will be wiped by the time control returns from \fIcall_pv\fR.
+.IP 4. 5
+As \fIcall_pv\fR is being used, the Perl subroutine is specified as a
+C string. In this case the subroutine name has been 'hard\-wired' into the
+code.
+.IP 5. 5
+Because we specified G_DISCARD, it is not necessary to check the value
+returned from \fIcall_pv\fR. It will always be 0.
+.SS "Passing Parameters"
+.IX Subsection "Passing Parameters"
+Now let's make a slightly more complex example. This time we want to
+call a Perl subroutine, \f(CW\*(C`LeftString\*(C'\fR, which will take 2 parameters\-\-a
+string ($s) and an integer ($n).  The subroutine will simply
+print the first \f(CW$n\fR characters of the string.
+.PP
+So the Perl subroutine would look like this:
+.PP
+.Vb 5
+\&    sub LeftString
+\&    {
+\&        my($s, $n) = @_;
+\&        print substr($s, 0, $n), "\en";
+\&    }
+.Ve
+.PP
+The C function required to call \fILeftString\fR would look like this:
+.PP
+.Vb 6
+\&    static void
+\&    call_LeftString(a, b)
+\&    char * a;
+\&    int b;
+\&    {
+\&        dSP;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSVpv(a, 0)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        call_pv("LeftString", G_DISCARD);
+\&
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Here are a few notes on the C function \fIcall_LeftString\fR.
+.IP 1. 5
+Parameters are passed to the Perl subroutine using the Perl stack.
+This is the purpose of the code beginning with the line \f(CW\*(C`dSP\*(C'\fR and
+ending with the line \f(CW\*(C`PUTBACK\*(C'\fR.  The \f(CW\*(C`dSP\*(C'\fR declares a local copy
+of the stack pointer.  This local copy should \fBalways\fR be accessed
+as \f(CW\*(C`SP\*(C'\fR.
+.IP 2. 5
+If you are going to put something onto the Perl stack, you need to know
+where to put it. This is the purpose of the macro \f(CW\*(C`dSP\*(C'\fR\-\-it declares
+and initializes a \fIlocal\fR copy of the Perl stack pointer.
+.Sp
+All the other macros which will be used in this example require you to
+have used this macro.
+.Sp
+The exception to this rule is if you are calling a Perl subroutine
+directly from an XSUB function. In this case it is not necessary to
+use the \f(CW\*(C`dSP\*(C'\fR macro explicitly\-\-it will be declared for you
+automatically.
+.IP 3. 5
+Any parameters to be pushed onto the stack should be bracketed by the
+\&\f(CW\*(C`PUSHMARK\*(C'\fR and \f(CW\*(C`PUTBACK\*(C'\fR macros.  The purpose of these two macros, in
+this context, is to count the number of parameters you are
+pushing automatically.  Then whenever Perl is creating the \f(CW@_\fR array for the
+subroutine, it knows how big to make it.
+.Sp
+The \f(CW\*(C`PUSHMARK\*(C'\fR macro tells Perl to make a mental note of the current
+stack pointer. Even if you aren't passing any parameters (like the
+example shown in the section "No Parameters, Nothing Returned") you
+must still call the \f(CW\*(C`PUSHMARK\*(C'\fR macro before you can call any of the
+\&\fIcall_*\fR functions\-\-Perl still needs to know that there are no
+parameters.
+.Sp
+The \f(CW\*(C`PUTBACK\*(C'\fR macro sets the global copy of the stack pointer to be
+the same as our local copy. If we didn't do this, \fIcall_pv\fR
+wouldn't know where the two parameters we pushed were\-\-remember that
+up to now all the stack pointer manipulation we have done is with our
+local copy, \fInot\fR the global copy.
+.IP 4. 5
+Next, we come to EXTEND and PUSHs. This is where the parameters
+actually get pushed onto the stack. In this case we are pushing a
+string and an integer.
+.Sp
+Alternatively you can use the \fBXPUSHs()\fR macro, which combines a
+\&\f(CW\*(C`EXTEND(SP, 1)\*(C'\fR and \f(CWPUSHs()\fR.  This is less efficient if you're
+pushing multiple values.
+.Sp
+See "XSUBs and the Argument Stack" in perlguts for details
+on how the PUSH macros work.
+.IP 5. 5
+Because we created temporary values (by means of \fBsv_2mortal()\fR calls)
+we will have to tidy up the Perl stack and dispose of mortal SVs.
+.Sp
+This is the purpose of
+.Sp
+.Vb 2
+\&    ENTER;
+\&    SAVETMPS;
+.Ve
+.Sp
+at the start of the function, and
+.Sp
+.Vb 2
+\&    FREETMPS;
+\&    LEAVE;
+.Ve
+.Sp
+at the end. The \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR pair creates a boundary for any
+temporaries we create.  This means that the temporaries we get rid of
+will be limited to those which were created after these calls.
+.Sp
+The \f(CW\*(C`FREETMPS\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair will get rid of any values returned by
+the Perl subroutine (see next example), plus it will also dump the
+mortal SVs we have created.  Having \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR at the
+beginning of the code makes sure that no other mortals are destroyed.
+.Sp
+Think of these macros as working a bit like \f(CW\*(C`{\*(C'\fR and \f(CW\*(C`}\*(C'\fR in Perl
+to limit the scope of local variables.
+.Sp
+See the section "Using Perl to Dispose of Temporaries" for details of
+an alternative to using these macros.
+.IP 6. 5
+Finally, \fILeftString\fR can now be called via the \fIcall_pv\fR function.
+The only flag specified this time is G_DISCARD. Because we are passing
+2 parameters to the Perl subroutine this time, we have not specified
+G_NOARGS.
+.SS "Returning a Scalar"
+.IX Subsection "Returning a Scalar"
+Now for an example of dealing with the items returned from a Perl
+subroutine.
+.PP
+Here is a Perl subroutine, \fIAdder\fR, that takes 2 integer parameters
+and simply returns their sum.
+.PP
+.Vb 5
+\&    sub Adder
+\&    {
+\&        my($a, $b) = @_;
+\&        $a + $b;
+\&    }
+.Ve
+.PP
+Because we are now concerned with the return value from \fIAdder\fR, the C
+function required to call it is now a bit more complex.
+.PP
+.Vb 7
+\&    static void
+\&    call_Adder(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("Adder", G_SCALAR);
+\&
+\&        SPAGAIN;
+\&
+\&        if (count != 1)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("The sum of %d and %d is %d\en", a, b, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Points to note this time are
+.IP 1. 5
+The only flag specified this time was G_SCALAR. That means that the \f(CW@_\fR
+array will be created and that the value returned by \fIAdder\fR will
+still exist after the call to \fIcall_pv\fR.
+.IP 2. 5
+The purpose of the macro \f(CW\*(C`SPAGAIN\*(C'\fR is to refresh the local copy of the
+stack pointer. This is necessary because it is possible that the memory
+allocated to the Perl stack has been reallocated during the
+\&\fIcall_pv\fR call.
+.Sp
+If you are making use of the Perl stack pointer in your code you must
+always refresh the local copy using SPAGAIN whenever you make use
+of the \fIcall_*\fR functions or any other Perl internal function.
+.IP 3. 5
+Although only a single value was expected to be returned from \fIAdder\fR,
+it is still good practice to check the return code from \fIcall_pv\fR
+anyway.
+.Sp
+Expecting a single value is not quite the same as knowing that there
+will be one. If someone modified \fIAdder\fR to return a list and we
+didn't check for that possibility and take appropriate action the Perl
+stack would end up in an inconsistent state. That is something you
+\&\fIreally\fR don't want to happen ever.
+.IP 4. 5
+The \f(CW\*(C`POPi\*(C'\fR macro is used here to pop the return value from the stack.
+In this case we wanted an integer, so \f(CW\*(C`POPi\*(C'\fR was used.
+.Sp
+Here is the complete list of POP macros available, along with the types
+they return.
+.Sp
+.Vb 8
+\&    POPs        SV
+\&    POPp        pointer (PV)
+\&    POPpbytex   pointer to bytes (PV)
+\&    POPn        double (NV)
+\&    POPi        integer (IV)
+\&    POPu        unsigned integer (UV)
+\&    POPl        long
+\&    POPul       unsigned long
+.Ve
+.Sp
+Since these macros have side-effects don't use them as arguments to
+macros that may evaluate their argument several times, for example:
+.Sp
+.Vb 3
+\&  /* Bad idea, don\*(Aqt do this */
+\&  STRLEN len;
+\&  const char *s = SvPV(POPs, len);
+.Ve
+.Sp
+Instead, use a temporary:
+.Sp
+.Vb 3
+\&  STRLEN len;
+\&  SV *sv = POPs;
+\&  const char *s = SvPV(sv, len);
+.Ve
+.Sp
+or a macro that guarantees it will evaluate its arguments only once:
+.Sp
+.Vb 2
+\&  STRLEN len;
+\&  const char *s = SvPVx(POPs, len);
+.Ve
+.IP 5. 5
+The final \f(CW\*(C`PUTBACK\*(C'\fR is used to leave the Perl stack in a consistent
+state before exiting the function.  This is necessary because when we
+popped the return value from the stack with \f(CW\*(C`POPi\*(C'\fR it updated only our
+local copy of the stack pointer.  Remember, \f(CW\*(C`PUTBACK\*(C'\fR sets the global
+stack pointer to be the same as our local copy.
+.SS "Returning a List of Values"
+.IX Subsection "Returning a List of Values"
+Now, let's extend the previous example to return both the sum of the
+parameters and the difference.
+.PP
+Here is the Perl subroutine
+.PP
+.Vb 5
+\&    sub AddSubtract
+\&    {
+\&       my($a, $b) = @_;
+\&       ($a+$b, $a\-$b);
+\&    }
+.Ve
+.PP
+and this is the C function
+.PP
+.Vb 7
+\&    static void
+\&    call_AddSubtract(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_LIST);
+\&
+\&        SPAGAIN;
+\&
+\&        if (count != 2)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("%d \- %d = %d\en", a, b, POPi);
+\&        printf ("%d + %d = %d\en", a, b, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+If \fIcall_AddSubtract\fR is called like this
+.PP
+.Vb 1
+\&    call_AddSubtract(7, 4);
+.Ve
+.PP
+then here is the output
+.PP
+.Vb 2
+\&    7 \- 4 = 3
+\&    7 + 4 = 11
+.Ve
+.PP
+Notes
+.IP 1. 5
+We wanted list context, so G_LIST was used.
+.IP 2. 5
+Not surprisingly \f(CW\*(C`POPi\*(C'\fR is used twice this time because we were
+retrieving 2 values from the stack. The important thing to note is that
+when using the \f(CW\*(C`POP*\*(C'\fR macros they come off the stack in \fIreverse\fR
+order.
+.SS "Returning a List in Scalar Context"
+.IX Subsection "Returning a List in Scalar Context"
+Say the Perl subroutine in the previous section was called in a scalar
+context, like this
+.PP
+.Vb 8
+\&    static void
+\&    call_AddSubScalar(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&        int i;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_SCALAR);
+\&
+\&        SPAGAIN;
+\&
+\&        printf ("Items Returned = %d\en", count);
+\&
+\&        for (i = 1; i <= count; ++i)
+\&            printf ("Value %d = %d\en", i, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+The other modification made is that \fIcall_AddSubScalar\fR will print the
+number of items returned from the Perl subroutine and their value (for
+simplicity it assumes that they are integer).  So if
+\&\fIcall_AddSubScalar\fR is called
+.PP
+.Vb 1
+\&    call_AddSubScalar(7, 4);
+.Ve
+.PP
+then the output will be
+.PP
+.Vb 2
+\&    Items Returned = 1
+\&    Value 1 = 3
+.Ve
+.PP
+In this case the main point to note is that only the last item in the
+list is returned from the subroutine. \fIAddSubtract\fR actually made it back to
+\&\fIcall_AddSubScalar\fR.
+.SS "Returning Data from Perl via the Parameter List"
+.IX Subsection "Returning Data from Perl via the Parameter List"
+It is also possible to return values directly via the parameter
+list\-\-whether it is actually desirable to do it is another matter entirely.
+.PP
+The Perl subroutine, \fIInc\fR, below takes 2 parameters and increments
+each directly.
+.PP
+.Vb 5
+\&    sub Inc
+\&    {
+\&        ++ $_[0];
+\&        ++ $_[1];
+\&    }
+.Ve
+.PP
+and here is a C function to call it.
+.PP
+.Vb 9
+\&    static void
+\&    call_Inc(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&        SV * sva;
+\&        SV * svb;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        sva = sv_2mortal(newSViv(a));
+\&        svb = sv_2mortal(newSViv(b));
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sva);
+\&        PUSHs(svb);
+\&        PUTBACK;
+\&
+\&        count = call_pv("Inc", G_DISCARD);
+\&
+\&        if (count != 0)
+\&            croak ("call_Inc: expected 0 values from \*(AqInc\*(Aq, got %d\en",
+\&                   count);
+\&
+\&        printf ("%d + 1 = %d\en", a, SvIV(sva));
+\&        printf ("%d + 1 = %d\en", b, SvIV(svb));
+\&
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+To be able to access the two parameters that were pushed onto the stack
+after they return from \fIcall_pv\fR it is necessary to make a note
+of their addresses\-\-thus the two variables \f(CW\*(C`sva\*(C'\fR and \f(CW\*(C`svb\*(C'\fR.
+.PP
+The reason this is necessary is that the area of the Perl stack which
+held them will very likely have been overwritten by something else by
+the time control returns from \fIcall_pv\fR.
+.SS "Using G_EVAL"
+.IX Subsection "Using G_EVAL"
+Now an example using G_EVAL. Below is a Perl subroutine which computes
+the difference of its 2 parameters. If this would result in a negative
+result, the subroutine calls \fIdie\fR.
+.PP
+.Vb 3
+\&    sub Subtract
+\&    {
+\&        my ($a, $b) = @_;
+\&
+\&        die "death can be fatal\en" if $a < $b;
+\&
+\&        $a \- $b;
+\&    }
+.Ve
+.PP
+and some C to call it
+.PP
+.Vb 8
+\& static void
+\& call_Subtract(a, b)
+\& int a;
+\& int b;
+\& {
+\&     dSP;
+\&     int count;
+\&     SV *err_tmp;
+\&
+\&     ENTER;
+\&     SAVETMPS;
+\&
+\&     PUSHMARK(SP);
+\&     EXTEND(SP, 2);
+\&     PUSHs(sv_2mortal(newSViv(a)));
+\&     PUSHs(sv_2mortal(newSViv(b)));
+\&     PUTBACK;
+\&
+\&     count = call_pv("Subtract", G_EVAL|G_SCALAR);
+\&
+\&     SPAGAIN;
+\&
+\&     /* Check the eval first */
+\&     err_tmp = ERRSV;
+\&     if (SvTRUE(err_tmp))
+\&     {
+\&         printf ("Uh oh \- %s\en", SvPV_nolen(err_tmp));
+\&         POPs;
+\&     }
+\&     else
+\&     {
+\&       if (count != 1)
+\&        croak("call_Subtract: wanted 1 value from \*(AqSubtract\*(Aq, got %d\en",
+\&              count);
+\&
+\&         printf ("%d \- %d = %d\en", a, b, POPi);
+\&     }
+\&
+\&     PUTBACK;
+\&     FREETMPS;
+\&     LEAVE;
+\& }
+.Ve
+.PP
+If \fIcall_Subtract\fR is called thus
+.PP
+.Vb 1
+\&    call_Subtract(4, 5)
+.Ve
+.PP
+the following will be printed
+.PP
+.Vb 1
+\&    Uh oh \- death can be fatal
+.Ve
+.PP
+Notes
+.IP 1. 5
+We want to be able to catch the \fIdie\fR so we have used the G_EVAL
+flag.  Not specifying this flag would mean that the program would
+terminate immediately at the \fIdie\fR statement in the subroutine
+\&\fISubtract\fR.
+.IP 2. 5
+The code
+.Sp
+.Vb 6
+\&    err_tmp = ERRSV;
+\&    if (SvTRUE(err_tmp))
+\&    {
+\&        printf ("Uh oh \- %s\en", SvPV_nolen(err_tmp));
+\&        POPs;
+\&    }
+.Ve
+.Sp
+is the direct equivalent of this bit of Perl
+.Sp
+.Vb 1
+\&    print "Uh oh \- $@\en" if $@;
+.Ve
+.Sp
+\&\f(CW\*(C`PL_errgv\*(C'\fR is a perl global of type \f(CW\*(C`GV *\*(C'\fR that points to the symbol
+table entry containing the error.  \f(CW\*(C`ERRSV\*(C'\fR therefore refers to the C
+equivalent of \f(CW$@\fR.  We use a local temporary, \f(CW\*(C`err_tmp\*(C'\fR, since
+\&\f(CW\*(C`ERRSV\*(C'\fR is a macro that calls a function, and \f(CWSvTRUE(ERRSV)\fR would
+end up calling that function multiple times.
+.IP 3. 5
+Note that the stack is popped using \f(CW\*(C`POPs\*(C'\fR in the block where
+\&\f(CWSvTRUE(err_tmp)\fR is true.  This is necessary because whenever a
+\&\fIcall_*\fR function invoked with G_EVAL|G_SCALAR returns an error,
+the top of the stack holds the value \fIundef\fR. Because we want the
+program to continue after detecting this error, it is essential that
+the stack be tidied up by removing the \fIundef\fR.
+.SS "Using G_KEEPERR"
+.IX Subsection "Using G_KEEPERR"
+Consider this rather facetious example, where we have used an XS
+version of the call_Subtract example above inside a destructor:
+.PP
+.Vb 9
+\&    package Foo;
+\&    sub new { bless {}, $_[0] }
+\&    sub Subtract {
+\&        my($a,$b) = @_;
+\&        die "death can be fatal" if $a < $b;
+\&        $a \- $b;
+\&    }
+\&    sub DESTROY { call_Subtract(5, 4); }
+\&    sub foo { die "foo dies"; }
+\&
+\&    package main;
+\&    {
+\&        my $foo = Foo\->new;
+\&        eval { $foo\->foo };
+\&    }
+\&    print "Saw: $@" if $@;             # should be, but isn\*(Aqt
+.Ve
+.PP
+This example will fail to recognize that an error occurred inside the
+\&\f(CW\*(C`eval {}\*(C'\fR.  Here's why: the call_Subtract code got executed while perl
+was cleaning up temporaries when exiting the outer braced block, and because
+call_Subtract is implemented with \fIcall_pv\fR using the G_EVAL
+flag, it promptly reset \f(CW$@\fR.  This results in the failure of the
+outermost test for \f(CW$@\fR, and thereby the failure of the error trap.
+.PP
+Appending the G_KEEPERR flag, so that the \fIcall_pv\fR call in
+call_Subtract reads:
+.PP
+.Vb 1
+\&        count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
+.Ve
+.PP
+will preserve the error and restore reliable error handling.
+.SS "Using call_sv"
+.IX Subsection "Using call_sv"
+In all the previous examples I have 'hard\-wired' the name of the Perl
+subroutine to be called from C.  Most of the time though, it is more
+convenient to be able to specify the name of the Perl subroutine from
+within the Perl script, and you'll want to use
+call_sv.
+.PP
+Consider the Perl code below
+.PP
+.Vb 4
+\&    sub fred
+\&    {
+\&        print "Hello there\en";
+\&    }
+\&
+\&    CallSubPV("fred");
+.Ve
+.PP
+Here is a snippet of XSUB which defines \fICallSubPV\fR.
+.PP
+.Vb 6
+\&    void
+\&    CallSubPV(name)
+\&        char *  name
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_pv(name, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+That is fine as far as it goes. The thing is, the Perl subroutine
+can be specified as only a string, however, Perl allows references
+to subroutines and anonymous subroutines.
+This is where \fIcall_sv\fR is useful.
+.PP
+The code below for \fICallSubSV\fR is identical to \fICallSubPV\fR except
+that the \f(CW\*(C`name\*(C'\fR parameter is now defined as an SV* and we use
+\&\fIcall_sv\fR instead of \fIcall_pv\fR.
+.PP
+.Vb 6
+\&    void
+\&    CallSubSV(name)
+\&        SV *    name
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_sv(name, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+Because we are using an SV to call \fIfred\fR the following can all be used:
+.PP
+.Vb 5
+\&    CallSubSV("fred");
+\&    CallSubSV(\e&fred);
+\&    $ref = \e&fred;
+\&    CallSubSV($ref);
+\&    CallSubSV( sub { print "Hello there\en" } );
+.Ve
+.PP
+As you can see, \fIcall_sv\fR gives you much greater flexibility in
+how you can specify the Perl subroutine.
+.PP
+You should note that, if it is necessary to store the SV (\f(CW\*(C`name\*(C'\fR in the
+example above) which corresponds to the Perl subroutine so that it can
+be used later in the program, it not enough just to store a copy of the
+pointer to the SV. Say the code above had been like this:
+.PP
+.Vb 1
+\&    static SV * rememberSub;
+\&
+\&    void
+\&    SaveSub1(name)
+\&        SV *    name
+\&        CODE:
+\&        rememberSub = name;
+\&
+\&    void
+\&    CallSavedSub1()
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_sv(rememberSub, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+The reason this is wrong is that, by the time you come to use the
+pointer \f(CW\*(C`rememberSub\*(C'\fR in \f(CW\*(C`CallSavedSub1\*(C'\fR, it may or may not still refer
+to the Perl subroutine that was recorded in \f(CW\*(C`SaveSub1\*(C'\fR.  This is
+particularly true for these cases:
+.PP
+.Vb 2
+\&    SaveSub1(\e&fred);
+\&    CallSavedSub1();
+\&
+\&    SaveSub1( sub { print "Hello there\en" } );
+\&    CallSavedSub1();
+.Ve
+.PP
+By the time each of the \f(CW\*(C`SaveSub1\*(C'\fR statements above has been executed,
+the SV*s which corresponded to the parameters will no longer exist.
+Expect an error message from Perl of the form
+.PP
+.Vb 1
+\&    Can\*(Aqt use an undefined value as a subroutine reference at ...
+.Ve
+.PP
+for each of the \f(CW\*(C`CallSavedSub1\*(C'\fR lines.
+.PP
+Similarly, with this code
+.PP
+.Vb 4
+\&    $ref = \e&fred;
+\&    SaveSub1($ref);
+\&    $ref = 47;
+\&    CallSavedSub1();
+.Ve
+.PP
+you can expect one of these messages (which you actually get is dependent on
+the version of Perl you are using)
+.PP
+.Vb 2
+\&    Not a CODE reference at ...
+\&    Undefined subroutine &main::47 called ...
+.Ve
+.PP
+The variable \f(CW$ref\fR may have referred to the subroutine \f(CW\*(C`fred\*(C'\fR
+whenever the call to \f(CW\*(C`SaveSub1\*(C'\fR was made but by the time
+\&\f(CW\*(C`CallSavedSub1\*(C'\fR gets called it now holds the number \f(CW47\fR. Because we
+saved only a pointer to the original SV in \f(CW\*(C`SaveSub1\*(C'\fR, any changes to
+\&\f(CW$ref\fR will be tracked by the pointer \f(CW\*(C`rememberSub\*(C'\fR. This means that
+whenever \f(CW\*(C`CallSavedSub1\*(C'\fR gets called, it will attempt to execute the
+code which is referenced by the SV* \f(CW\*(C`rememberSub\*(C'\fR.  In this case
+though, it now refers to the integer \f(CW47\fR, so expect Perl to complain
+loudly.
+.PP
+A similar but more subtle problem is illustrated with this code:
+.PP
+.Vb 4
+\&    $ref = \e&fred;
+\&    SaveSub1($ref);
+\&    $ref = \e&joe;
+\&    CallSavedSub1();
+.Ve
+.PP
+This time whenever \f(CW\*(C`CallSavedSub1\*(C'\fR gets called it will execute the Perl
+subroutine \f(CW\*(C`joe\*(C'\fR (assuming it exists) rather than \f(CW\*(C`fred\*(C'\fR as was
+originally requested in the call to \f(CW\*(C`SaveSub1\*(C'\fR.
+.PP
+To get around these problems it is necessary to take a full copy of the
+SV.  The code below shows \f(CW\*(C`SaveSub2\*(C'\fR modified to do that.
+.PP
+.Vb 2
+\&    /* this isn\*(Aqt thread\-safe */
+\&    static SV * keepSub = (SV*)NULL;
+\&
+\&    void
+\&    SaveSub2(name)
+\&        SV *    name
+\&        CODE:
+\&        /* Take a copy of the callback */
+\&        if (keepSub == (SV*)NULL)
+\&            /* First time, so create a new SV */
+\&            keepSub = newSVsv(name);
+\&        else
+\&            /* Been here before, so overwrite */
+\&            SvSetSV(keepSub, name);
+\&
+\&    void
+\&    CallSavedSub2()
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_sv(keepSub, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+To avoid creating a new SV every time \f(CW\*(C`SaveSub2\*(C'\fR is called,
+the function first checks to see if it has been called before.  If not,
+then space for a new SV is allocated and the reference to the Perl
+subroutine \f(CW\*(C`name\*(C'\fR is copied to the variable \f(CW\*(C`keepSub\*(C'\fR in one
+operation using \f(CW\*(C`newSVsv\*(C'\fR.  Thereafter, whenever \f(CW\*(C`SaveSub2\*(C'\fR is called,
+the existing SV, \f(CW\*(C`keepSub\*(C'\fR, is overwritten with the new value using
+\&\f(CW\*(C`SvSetSV\*(C'\fR.
+.PP
+Note: using a static or global variable to store the SV isn't
+thread-safe.  You can either use the \f(CW\*(C`MY_CXT\*(C'\fR mechanism documented in
+"Safely Storing Static Data in XS" in perlxs which is fast, or store the
+values in perl global variables, using \fBget_sv()\fR, which is much slower.
+.SS "Using call_argv"
+.IX Subsection "Using call_argv"
+Here is a Perl subroutine which prints whatever parameters are passed
+to it.
+.PP
+.Vb 3
+\&    sub PrintList
+\&    {
+\&        my(@list) = @_;
+\&
+\&        foreach (@list) { print "$_\en" }
+\&    }
+.Ve
+.PP
+And here is an example of \fIcall_argv\fR which will call
+\&\fIPrintList\fR.
+.PP
+.Vb 1
+\&    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
+\&
+\&    static void
+\&    call_PrintList()
+\&    {
+\&        call_argv("PrintList", G_DISCARD, words);
+\&    }
+.Ve
+.PP
+Note that it is not necessary to call \f(CW\*(C`PUSHMARK\*(C'\fR in this instance.
+This is because \fIcall_argv\fR will do it for you.
+.SS "Using call_method"
+.IX Subsection "Using call_method"
+Consider the following Perl code:
+.PP
+.Vb 2
+\&    {
+\&        package Mine;
+\&
+\&        sub new
+\&        {
+\&            my($type) = shift;
+\&            bless [@_]
+\&        }
+\&
+\&        sub Display
+\&        {
+\&            my ($self, $index) = @_;
+\&            print "$index: $$self[$index]\en";
+\&        }
+\&
+\&        sub PrintID
+\&        {
+\&            my($class) = @_;
+\&            print "This is Class $class version 1.0\en";
+\&        }
+\&    }
+.Ve
+.PP
+It implements just a very simple class to manage an array.  Apart from
+the constructor, \f(CW\*(C`new\*(C'\fR, it declares methods, one static and one
+virtual. The static method, \f(CW\*(C`PrintID\*(C'\fR, prints out simply the class
+name and a version number. The virtual method, \f(CW\*(C`Display\*(C'\fR, prints out a
+single element of the array.  Here is an all-Perl example of using it.
+.PP
+.Vb 3
+\&    $a = Mine\->new(\*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq);
+\&    $a\->Display(1);
+\&    Mine\->PrintID;
+.Ve
+.PP
+will print
+.PP
+.Vb 2
+\&    1: green
+\&    This is Class Mine version 1.0
+.Ve
+.PP
+Calling a Perl method from C is fairly straightforward. The following
+things are required:
+.IP \(bu 5
+A reference to the object for a virtual method or the name of the class
+for a static method
+.IP \(bu 5
+The name of the method
+.IP \(bu 5
+Any other parameters specific to the method
+.PP
+Here is a simple XSUB which illustrates the mechanics of calling both
+the \f(CW\*(C`PrintID\*(C'\fR and \f(CW\*(C`Display\*(C'\fR methods from C.
+.PP
+.Vb 11
+\&    void
+\&    call_Method(ref, method, index)
+\&        SV *    ref
+\&        char *  method
+\&        int             index
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(ref);
+\&        PUSHs(sv_2mortal(newSViv(index)));
+\&        PUTBACK;
+\&
+\&        call_method(method, G_DISCARD);
+\&
+\&    void
+\&    call_PrintID(class, method)
+\&        char *  class
+\&        char *  method
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        XPUSHs(sv_2mortal(newSVpv(class, 0)));
+\&        PUTBACK;
+\&
+\&        call_method(method, G_DISCARD);
+.Ve
+.PP
+So the methods \f(CW\*(C`PrintID\*(C'\fR and \f(CW\*(C`Display\*(C'\fR can be invoked like this:
+.PP
+.Vb 3
+\&    $a = Mine\->new(\*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq);
+\&    call_Method($a, \*(AqDisplay\*(Aq, 1);
+\&    call_PrintID(\*(AqMine\*(Aq, \*(AqPrintID\*(Aq);
+.Ve
+.PP
+The only thing to note is that, in both the static and virtual methods,
+the method name is not passed via the stack\-\-it is used as the first
+parameter to \fIcall_method\fR.
+.SS "Using GIMME_V"
+.IX Subsection "Using GIMME_V"
+Here is a trivial XSUB which prints the context in which it is
+currently executing.
+.PP
+.Vb 10
+\&    void
+\&    PrintContext()
+\&        CODE:
+\&        U8 gimme = GIMME_V;
+\&        if (gimme == G_VOID)
+\&            printf ("Context is Void\en");
+\&        else if (gimme == G_SCALAR)
+\&            printf ("Context is Scalar\en");
+\&        else
+\&            printf ("Context is Array\en");
+.Ve
+.PP
+And here is some Perl to test it.
+.PP
+.Vb 3
+\&    PrintContext;
+\&    $a = PrintContext;
+\&    @a = PrintContext;
+.Ve
+.PP
+The output from that will be
+.PP
+.Vb 3
+\&    Context is Void
+\&    Context is Scalar
+\&    Context is Array
+.Ve
+.SS "Using Perl to Dispose of Temporaries"
+.IX Subsection "Using Perl to Dispose of Temporaries"
+In the examples given to date, any temporaries created in the callback
+(i.e., parameters passed on the stack to the \fIcall_*\fR function or
+values returned via the stack) have been freed by one of these methods:
+.IP \(bu 5
+Specifying the G_DISCARD flag with \fIcall_*\fR
+.IP \(bu 5
+Explicitly using the \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR\-\-\f(CW\*(C`FREETMPS\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pairing
+.PP
+There is another method which can be used, namely letting Perl do it
+for you automatically whenever it regains control after the callback
+has terminated.  This is done by simply not using the
+.PP
+.Vb 5
+\&    ENTER;
+\&    SAVETMPS;
+\&    ...
+\&    FREETMPS;
+\&    LEAVE;
+.Ve
+.PP
+sequence in the callback (and not, of course, specifying the G_DISCARD
+flag).
+.PP
+If you are going to use this method you have to be aware of a possible
+memory leak which can arise under very specific circumstances.  To
+explain these circumstances you need to know a bit about the flow of
+control between Perl and the callback routine.
+.PP
+The examples given at the start of the document (an error handler and
+an event driven program) are typical of the two main sorts of flow
+control that you are likely to encounter with callbacks.  There is a
+very important distinction between them, so pay attention.
+.PP
+In the first example, an error handler, the flow of control could be as
+follows.  You have created an interface to an external library.
+Control can reach the external library like this
+.PP
+.Vb 1
+\&    perl \-\-> XSUB \-\-> external library
+.Ve
+.PP
+Whilst control is in the library, an error condition occurs. You have
+previously set up a Perl callback to handle this situation, so it will
+get executed. Once the callback has finished, control will drop back to
+Perl again.  Here is what the flow of control will be like in that
+situation
+.PP
+.Vb 7
+\&    perl \-\-> XSUB \-\-> external library
+\&                      ...
+\&                      error occurs
+\&                      ...
+\&                      external library \-\-> call_* \-\-> perl
+\&                                                          |
+\&    perl <\-\- XSUB <\-\- external library <\-\- call_* <\-\-\-\-+
+.Ve
+.PP
+After processing of the error using \fIcall_*\fR is completed,
+control reverts back to Perl more or less immediately.
+.PP
+In the diagram, the further right you go the more deeply nested the
+scope is.  It is only when control is back with perl on the extreme
+left of the diagram that you will have dropped back to the enclosing
+scope and any temporaries you have left hanging around will be freed.
+.PP
+In the second example, an event driven program, the flow of control
+will be more like this
+.PP
+.Vb 10
+\&    perl \-\-> XSUB \-\-> event handler
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+.Ve
+.PP
+In this case the flow of control can consist of only the repeated
+sequence
+.PP
+.Vb 1
+\&    event handler \-\-> call_* \-\-> perl
+.Ve
+.PP
+for practically the complete duration of the program.  This means that
+control may \fInever\fR drop back to the surrounding scope in Perl at the
+extreme left.
+.PP
+So what is the big problem? Well, if you are expecting Perl to tidy up
+those temporaries for you, you might be in for a long wait.  For Perl
+to dispose of your temporaries, control must drop back to the
+enclosing scope at some stage.  In the event driven scenario that may
+never happen.  This means that, as time goes on, your program will
+create more and more temporaries, none of which will ever be freed. As
+each of these temporaries consumes some memory your program will
+eventually consume all the available memory in your system\-\-kapow!
+.PP
+So here is the bottom line\-\-if you are sure that control will revert
+back to the enclosing Perl scope fairly quickly after the end of your
+callback, then it isn't absolutely necessary to dispose explicitly of
+any temporaries you may have created. Mind you, if you are at all
+uncertain about what to do, it doesn't do any harm to tidy up anyway.
+.SS "Strategies for Storing Callback Context Information"
+.IX Subsection "Strategies for Storing Callback Context Information"
+Potentially one of the trickiest problems to overcome when designing a
+callback interface can be figuring out how to store the mapping between
+the C callback function and the Perl equivalent.
+.PP
+To help understand why this can be a real problem first consider how a
+callback is set up in an all C environment.  Typically a C API will
+provide a function to register a callback.  This will expect a pointer
+to a function as one of its parameters.  Below is a call to a
+hypothetical function \f(CW\*(C`register_fatal\*(C'\fR which registers the C function
+to get called when a fatal error occurs.
+.PP
+.Vb 1
+\&    register_fatal(cb1);
+.Ve
+.PP
+The single parameter \f(CW\*(C`cb1\*(C'\fR is a pointer to a function, so you must
+have defined \f(CW\*(C`cb1\*(C'\fR in your code, say something like this
+.PP
+.Vb 6
+\&    static void
+\&    cb1()
+\&    {
+\&        printf ("Fatal Error\en");
+\&        exit(1);
+\&    }
+.Ve
+.PP
+Now change that to call a Perl subroutine instead
+.PP
+.Vb 1
+\&    static SV * callback = (SV*)NULL;
+\&
+\&    static void
+\&    cb1()
+\&    {
+\&        dSP;
+\&
+\&        PUSHMARK(SP);
+\&
+\&        /* Call the Perl sub to process the callback */
+\&        call_sv(callback, G_DISCARD);
+\&    }
+\&
+\&
+\&    void
+\&    register_fatal(fn)
+\&        SV *    fn
+\&        CODE:
+\&        /* Remember the Perl sub */
+\&        if (callback == (SV*)NULL)
+\&            callback = newSVsv(fn);
+\&        else
+\&            SvSetSV(callback, fn);
+\&
+\&        /* register the callback with the external library */
+\&        register_fatal(cb1);
+.Ve
+.PP
+where the Perl equivalent of \f(CW\*(C`register_fatal\*(C'\fR and the callback it
+registers, \f(CW\*(C`pcb1\*(C'\fR, might look like this
+.PP
+.Vb 2
+\&    # Register the sub pcb1
+\&    register_fatal(\e&pcb1);
+\&
+\&    sub pcb1
+\&    {
+\&        die "I\*(Aqm dying...\en";
+\&    }
+.Ve
+.PP
+The mapping between the C callback and the Perl equivalent is stored in
+the global variable \f(CW\*(C`callback\*(C'\fR.
+.PP
+This will be adequate if you ever need to have only one callback
+registered at any time. An example could be an error handler like the
+code sketched out above. Remember though, repeated calls to
+\&\f(CW\*(C`register_fatal\*(C'\fR will replace the previously registered callback
+function with the new one.
+.PP
+Say for example you want to interface to a library which allows asynchronous
+file i/o.  In this case you may be able to register a callback whenever
+a read operation has completed. To be of any use we want to be able to
+call separate Perl subroutines for each file that is opened.  As it
+stands, the error handler example above would not be adequate as it
+allows only a single callback to be defined at any time. What we
+require is a means of storing the mapping between the opened file and
+the Perl subroutine we want to be called for that file.
+.PP
+Say the i/o library has a function \f(CW\*(C`asynch_read\*(C'\fR which associates a C
+function \f(CW\*(C`ProcessRead\*(C'\fR with a file handle \f(CW\*(C`fh\*(C'\fR\-\-this assumes that it
+has also provided some routine to open the file and so obtain the file
+handle.
+.PP
+.Vb 1
+\&    asynch_read(fh, ProcessRead)
+.Ve
+.PP
+This may expect the C \fIProcessRead\fR function of this form
+.PP
+.Vb 7
+\&    void
+\&    ProcessRead(fh, buffer)
+\&    int fh;
+\&    char *      buffer;
+\&    {
+\&         ...
+\&    }
+.Ve
+.PP
+To provide a Perl interface to this library we need to be able to map
+between the \f(CW\*(C`fh\*(C'\fR parameter and the Perl subroutine we want called.  A
+hash is a convenient mechanism for storing this mapping.  The code
+below shows a possible implementation
+.PP
+.Vb 1
+\&    static HV * Mapping = (HV*)NULL;
+\&
+\&    void
+\&    asynch_read(fh, callback)
+\&        int     fh
+\&        SV *    callback
+\&        CODE:
+\&        /* If the hash doesn\*(Aqt already exist, create it */
+\&        if (Mapping == (HV*)NULL)
+\&            Mapping = newHV();
+\&
+\&        /* Save the fh \-> callback mapping */
+\&        hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
+\&
+\&        /* Register with the C Library */
+\&        asynch_read(fh, asynch_read_if);
+.Ve
+.PP
+and \f(CW\*(C`asynch_read_if\*(C'\fR could look like this
+.PP
+.Vb 7
+\&    static void
+\&    asynch_read_if(fh, buffer)
+\&    int fh;
+\&    char *      buffer;
+\&    {
+\&        dSP;
+\&        SV ** sv;
+\&
+\&        /* Get the callback associated with fh */
+\&        sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
+\&        if (sv == (SV**)NULL)
+\&            croak("Internal error...\en");
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(fh)));
+\&        PUSHs(sv_2mortal(newSVpv(buffer, 0)));
+\&        PUTBACK;
+\&
+\&        /* Call the Perl sub */
+\&        call_sv(*sv, G_DISCARD);
+\&    }
+.Ve
+.PP
+For completeness, here is \f(CW\*(C`asynch_close\*(C'\fR.  This shows how to remove
+the entry from the hash \f(CW\*(C`Mapping\*(C'\fR.
+.PP
+.Vb 6
+\&    void
+\&    asynch_close(fh)
+\&        int     fh
+\&        CODE:
+\&        /* Remove the entry from the hash */
+\&        (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
+\&
+\&        /* Now call the real asynch_close */
+\&        asynch_close(fh);
+.Ve
+.PP
+So the Perl interface would look like this
+.PP
+.Vb 4
+\&    sub callback1
+\&    {
+\&        my($handle, $buffer) = @_;
+\&    }
+\&
+\&    # Register the Perl callback
+\&    asynch_read($fh, \e&callback1);
+\&
+\&    asynch_close($fh);
+.Ve
+.PP
+The mapping between the C callback and Perl is stored in the global
+hash \f(CW\*(C`Mapping\*(C'\fR this time. Using a hash has the distinct advantage that
+it allows an unlimited number of callbacks to be registered.
+.PP
+What if the interface provided by the C callback doesn't contain a
+parameter which allows the file handle to Perl subroutine mapping?  Say
+in the asynchronous i/o package, the callback function gets passed only
+the \f(CW\*(C`buffer\*(C'\fR parameter like this
+.PP
+.Vb 6
+\&    void
+\&    ProcessRead(buffer)
+\&    char *      buffer;
+\&    {
+\&        ...
+\&    }
+.Ve
+.PP
+Without the file handle there is no straightforward way to map from the
+C callback to the Perl subroutine.
+.PP
+In this case a possible way around this problem is to predefine a
+series of C functions to act as the interface to Perl, thus
+.PP
+.Vb 3
+\&    #define MAX_CB              3
+\&    #define NULL_HANDLE \-1
+\&    typedef void (*FnMap)();
+\&
+\&    struct MapStruct {
+\&        FnMap    Function;
+\&        SV *     PerlSub;
+\&        int      Handle;
+\&      };
+\&
+\&    static void  fn1();
+\&    static void  fn2();
+\&    static void  fn3();
+\&
+\&    static struct MapStruct Map [MAX_CB] =
+\&        {
+\&            { fn1, NULL, NULL_HANDLE },
+\&            { fn2, NULL, NULL_HANDLE },
+\&            { fn3, NULL, NULL_HANDLE }
+\&        };
+\&
+\&    static void
+\&    Pcb(index, buffer)
+\&    int index;
+\&    char * buffer;
+\&    {
+\&        dSP;
+\&
+\&        PUSHMARK(SP);
+\&        XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
+\&        PUTBACK;
+\&
+\&        /* Call the Perl sub */
+\&        call_sv(Map[index].PerlSub, G_DISCARD);
+\&    }
+\&
+\&    static void
+\&    fn1(buffer)
+\&    char * buffer;
+\&    {
+\&        Pcb(0, buffer);
+\&    }
+\&
+\&    static void
+\&    fn2(buffer)
+\&    char * buffer;
+\&    {
+\&        Pcb(1, buffer);
+\&    }
+\&
+\&    static void
+\&    fn3(buffer)
+\&    char * buffer;
+\&    {
+\&        Pcb(2, buffer);
+\&    }
+\&
+\&    void
+\&    array_asynch_read(fh, callback)
+\&        int             fh
+\&        SV *    callback
+\&        CODE:
+\&        int index;
+\&        int null_index = MAX_CB;
+\&
+\&        /* Find the same handle or an empty entry */
+\&        for (index = 0; index < MAX_CB; ++index)
+\&        {
+\&            if (Map[index].Handle == fh)
+\&                break;
+\&
+\&            if (Map[index].Handle == NULL_HANDLE)
+\&                null_index = index;
+\&        }
+\&
+\&        if (index == MAX_CB && null_index == MAX_CB)
+\&            croak ("Too many callback functions registered\en");
+\&
+\&        if (index == MAX_CB)
+\&            index = null_index;
+\&
+\&        /* Save the file handle */
+\&        Map[index].Handle = fh;
+\&
+\&        /* Remember the Perl sub */
+\&        if (Map[index].PerlSub == (SV*)NULL)
+\&            Map[index].PerlSub = newSVsv(callback);
+\&        else
+\&            SvSetSV(Map[index].PerlSub, callback);
+\&
+\&        asynch_read(fh, Map[index].Function);
+\&
+\&    void
+\&    array_asynch_close(fh)
+\&        int     fh
+\&        CODE:
+\&        int index;
+\&
+\&        /* Find the file handle */
+\&        for (index = 0; index < MAX_CB; ++ index)
+\&            if (Map[index].Handle == fh)
+\&                break;
+\&
+\&        if (index == MAX_CB)
+\&            croak ("could not close fh %d\en", fh);
+\&
+\&        Map[index].Handle = NULL_HANDLE;
+\&        SvREFCNT_dec(Map[index].PerlSub);
+\&        Map[index].PerlSub = (SV*)NULL;
+\&
+\&        asynch_close(fh);
+.Ve
+.PP
+In this case the functions \f(CW\*(C`fn1\*(C'\fR, \f(CW\*(C`fn2\*(C'\fR, and \f(CW\*(C`fn3\*(C'\fR are used to
+remember the Perl subroutine to be called. Each of the functions holds
+a separate hard-wired index which is used in the function \f(CW\*(C`Pcb\*(C'\fR to
+access the \f(CW\*(C`Map\*(C'\fR array and actually call the Perl subroutine.
+.PP
+There are some obvious disadvantages with this technique.
+.PP
+Firstly, the code is considerably more complex than with the previous
+example.
+.PP
+Secondly, there is a hard-wired limit (in this case 3) to the number of
+callbacks that can exist simultaneously. The only way to increase the
+limit is by modifying the code to add more functions and then
+recompiling.  None the less, as long as the number of functions is
+chosen with some care, it is still a workable solution and in some
+cases is the only one available.
+.PP
+To summarize, here are a number of possible methods for you to consider
+for storing the mapping between C and the Perl callback
+.IP "1. Ignore the problem \- Allow only 1 callback" 5
+.IX Item "1. Ignore the problem - Allow only 1 callback"
+For a lot of situations, like interfacing to an error handler, this may
+be a perfectly adequate solution.
+.IP "2. Create a sequence of callbacks \- hard wired limit" 5
+.IX Item "2. Create a sequence of callbacks - hard wired limit"
+If it is impossible to tell from the parameters passed back from the C
+callback what the context is, then you may need to create a sequence of C
+callback interface functions, and store pointers to each in an array.
+.IP "3. Use a parameter to map to the Perl callback" 5
+.IX Item "3. Use a parameter to map to the Perl callback"
+A hash is an ideal mechanism to store the mapping between C and Perl.
+.SS "Alternate Stack Manipulation"
+.IX Subsection "Alternate Stack Manipulation"
+Although I have made use of only the \f(CW\*(C`POP*\*(C'\fR macros to access values
+returned from Perl subroutines, it is also possible to bypass these
+macros and read the stack using the \f(CW\*(C`ST\*(C'\fR macro (See perlxs for a
+full description of the \f(CW\*(C`ST\*(C'\fR macro).
+.PP
+Most of the time the \f(CW\*(C`POP*\*(C'\fR macros should be adequate; the main
+problem with them is that they force you to process the returned values
+in sequence. This may not be the most suitable way to process the
+values in some cases. What we want is to be able to access the stack in
+a random order. The \f(CW\*(C`ST\*(C'\fR macro as used when coding an XSUB is ideal
+for this purpose.
+.PP
+The code below is the example given in the section "Returning a List
+of Values" recoded to use \f(CW\*(C`ST\*(C'\fR instead of \f(CW\*(C`POP*\*(C'\fR.
+.PP
+.Vb 8
+\&    static void
+\&    call_AddSubtract2(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        I32 ax;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_LIST);
+\&
+\&        SPAGAIN;
+\&        SP \-= count;
+\&        ax = (SP \- PL_stack_base) + 1;
+\&
+\&        if (count != 2)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("%d + %d = %d\en", a, b, SvIV(ST(0)));
+\&        printf ("%d \- %d = %d\en", a, b, SvIV(ST(1)));
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Notes
+.IP 1. 5
+Notice that it was necessary to define the variable \f(CW\*(C`ax\*(C'\fR.  This is
+because the \f(CW\*(C`ST\*(C'\fR macro expects it to exist.  If we were in an XSUB it
+would not be necessary to define \f(CW\*(C`ax\*(C'\fR as it is already defined for
+us.
+.IP 2. 5
+The code
+.Sp
+.Vb 3
+\&        SPAGAIN;
+\&        SP \-= count;
+\&        ax = (SP \- PL_stack_base) + 1;
+.Ve
+.Sp
+sets the stack up so that we can use the \f(CW\*(C`ST\*(C'\fR macro.
+.IP 3. 5
+Unlike the original coding of this example, the returned
+values are not accessed in reverse order.  So \f(CWST(0)\fR refers to the
+first value returned by the Perl subroutine and \f(CWST(count\-1)\fR
+refers to the last.
+.SS "Creating and Calling an Anonymous Subroutine in C"
+.IX Subsection "Creating and Calling an Anonymous Subroutine in C"
+As we've already shown, \f(CW\*(C`call_sv\*(C'\fR can be used to invoke an
+anonymous subroutine.  However, our example showed a Perl script
+invoking an XSUB to perform this operation.  Let's see how it can be
+done inside our C code:
+.PP
+.Vb 1
+\& ...
+\&
+\& SV *cvrv
+\&    = eval_pv("sub {
+\&                print \*(AqYou will not find me cluttering any namespace!\*(Aq
+\&               }", TRUE);
+\&
+\& ...
+\&
+\& call_sv(cvrv, G_VOID|G_NOARGS);
+.Ve
+.PP
+\&\f(CW\*(C`eval_pv\*(C'\fR is used to compile the anonymous subroutine, which
+will be the return value as well (read more about \f(CW\*(C`eval_pv\*(C'\fR in
+"eval_pv" in perlapi).  Once this code reference is in hand, it
+can be mixed in with all the previous examples we've shown.
+.SH "LIGHTWEIGHT CALLBACKS"
+.IX Header "LIGHTWEIGHT CALLBACKS"
+Sometimes you need to invoke the same subroutine repeatedly.
+This usually happens with a function that acts on a list of
+values, such as Perl's built-in \fBsort()\fR. You can pass a
+comparison function to \fBsort()\fR, which will then be invoked
+for every pair of values that needs to be compared. The \fBfirst()\fR
+and \fBreduce()\fR functions from List::Util follow a similar
+pattern.
+.PP
+In this case it is possible to speed up the routine (often
+quite substantially) by using the lightweight callback API.
+The idea is that the calling context only needs to be
+created and destroyed once, and the sub can be called
+arbitrarily many times in between.
+.PP
+It is usual to pass parameters using global variables (typically
+\&\f(CW$_\fR for one parameter, or \f(CW$a\fR and \f(CW$b\fR for two parameters) rather
+than via \f(CW@_\fR. (It is possible to use the \f(CW@_\fR mechanism if you know
+what you're doing, though there is as yet no supported API for
+it. It's also inherently slower.)
+.PP
+The pattern of macro calls is like this:
+.PP
+.Vb 3
+\&    dMULTICALL;                 /* Declare local variables */
+\&    U8 gimme = G_SCALAR;        /* context of the call: G_SCALAR,
+\&                                 * G_LIST, or G_VOID */
+\&
+\&    PUSH_MULTICALL(cv);         /* Set up the context for calling cv,
+\&                                   and set local vars appropriately */
+\&
+\&    /* loop */ {
+\&        /* set the value(s) af your parameter variables */
+\&        MULTICALL;              /* Make the actual call */
+\&    } /* end of loop */
+\&
+\&    POP_MULTICALL;              /* Tear down the calling context */
+.Ve
+.PP
+For some concrete examples, see the implementation of the
+\&\fBfirst()\fR and \fBreduce()\fR functions of List::Util 1.18. There you
+will also find a header file that emulates the multicall API
+on older versions of perl.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlxs, perlguts, perlembed
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess
+.PP
+Special thanks to the following people who assisted in the creation of
+the document.
+.PP
+Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
+and Larry Wall.
+.SH DATE
+.IX Header "DATE"
+Last updated for perl 5.23.1.
diff --git a/upstream/mageia-cauldron/man1/perlcheat.1 b/upstream/mageia-cauldron/man1/perlcheat.1
new file mode 100644
index 00000000..17b3dca2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcheat.1
@@ -0,0 +1,157 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCHEAT 1"
+.TH PERLCHEAT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlcheat \- Perl 5 Cheat Sheet
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This 'cheat sheet' is a handy reference, meant for beginning Perl
+programmers. Not everything is mentioned, but 195 features may
+already be overwhelming.
+.SS "The sheet"
+.IX Subsection "The sheet"
+.Vb 10
+\&  CONTEXTS  SIGILS  ref        ARRAYS        HASHES
+\&  void      $scalar SCALAR     @array        %hash
+\&  scalar    @array  ARRAY      @array[0, 2]  @hash{\*(Aqa\*(Aq, \*(Aqb\*(Aq}
+\&  list      %hash   HASH       $array[0]     $hash{\*(Aqa\*(Aq}
+\&            &sub    CODE
+\&            *glob   GLOB       SCALAR VALUES
+\&                    FORMAT     number, string, ref, glob, undef
+\&  REFERENCES
+\&  \e      reference       $$foo[1]       aka $foo\->[1]
+\&  $@%&*  dereference     $$foo{bar}     aka $foo\->{bar}
+\&  []     anon. arrayref  ${$$foo[1]}[2] aka $foo\->[1]\->[2]
+\&  {}     anon. hashref   ${$$foo[1]}[2] aka $foo\->[1][2]
+\&  \e()    list of refs
+\&                         SYNTAX
+\&  OPERATOR PRECEDENCE    foreach (LIST) { }     for (a;b;c) { }
+\&  \->                     while   (e) { }        until (e)   { }
+\&  ++ \-\-                  if      (e) { } elsif (e) { } else { }
+\&  **                     unless  (e) { } elsif (e) { } else { }
+\&  ! ~ \e u+ u\-            given   (e) { when (e) {} default {} }
+\&  =~ !~
+\&  * / % x                 NUMBERS vs STRINGS  FALSE vs TRUE
+\&  + \- .                   =          =        undef, "", 0, "0"
+\&  << >>                   +          .        anything else
+\&  named uops              == !=      eq ne
+\&  < > <= >= lt gt le ge   < > <= >=  lt gt le ge
+\&  == != <=> eq ne cmp ~~  <=>        cmp
+\&  &
+\&  | ^             REGEX MODIFIERS       REGEX METACHARS
+\&  &&              /i case insensitive   ^      string begin
+\&  || //           /m line based ^$      $      str end (bfr \en)
+\&  .. ...          /s . includes \en      +      one or more
+\&  ?:              /x /xx ign. wh.space  *      zero or more
+\&  = += last goto  /p preserve           ?      zero or one
+\&  , =>            /a ASCII    /aa safe  {3,7}  repeat in range
+\&  list ops        /l locale   /d  dual  |      alternation
+\&  not             /u Unicode            []     character class
+\&  and             /e evaluate /ee rpts  \eb     boundary
+\&  or xor          /g global             \ez     string end
+\&                  /o compile pat once   ()     capture
+\&  DEBUG                                 (?:p)  no capture
+\&  \-MO=Deparse     REGEX CHARCLASSES     (?#t)  comment
+\&  \-MO=Terse       .   [^\en]             (?=p)  ZW pos ahead
+\&  \-D##            \es  whitespace        (?!p)  ZW neg ahead
+\&  \-d:Trace        \ew  word chars        (?<=p) ZW pos behind \eK
+\&                  \ed  digits            (?<!p) ZW neg behind
+\&  CONFIGURATION   \epP named property    (?>p)  no backtrack
+\&  perl \-V:ivsize  \eh  horiz.wh.space    (?|p|p)branch reset
+\&                  \eR  linebreak         (?<n>p)named capture
+\&                  \eS \eW \eD \eH negate    \eg{n}  ref to named cap
+\&                                        \eK     keep left part
+\&  FUNCTION RETURN LISTS
+\&  stat      localtime    caller         SPECIAL VARIABLES
+\&   0 dev    0 second      0 package     $_    default variable
+\&   1 ino    1 minute      1 filename    $0    program name
+\&   2 mode   2 hour        2 line        $/    input separator
+\&   3 nlink  3 day         3 subroutine  $\e    output separator
+\&   4 uid    4 month\-1     4 hasargs     $|    autoflush
+\&   5 gid    5 year\-1900   5 wantarray   $!    sys/libcall error
+\&   6 rdev   6 weekday     6 evaltext    $@    eval error
+\&   7 size   7 yearday     7 is_require  $$    process ID
+\&   8 atime  8 is_dst      8 hints       $.    line number
+\&   9 mtime                9 bitmask     @ARGV command line args
+\&  10 ctime               10 hinthash    @INC  include paths
+\&  11 blksz               3..10 only     @_    subroutine args
+\&  12 blcks               with EXPR      %ENV  environment
+.Ve
+.SH ACKNOWLEDGEMENTS
+.IX Header "ACKNOWLEDGEMENTS"
+The first version of this document appeared on Perl Monks, where several
+people had useful suggestions. Thank you, Perl Monks.
+.PP
+A special thanks to Damian Conway, who didn't only suggest important changes,
+but also took the time to count the number of listed features and make a
+Raku version to show that Perl will stay Perl.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Juerd Waalboer <#####@juerd.nl>, with the help of many Perl Monks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP \(bu 4
+<https://perlmonks.org/?node_id=216602> \- the original PM post
+.IP \(bu 4
+<https://perlmonks.org/?node_id=238031> \- Damian Conway's Raku version
+.IP \(bu 4
+<https://juerd.nl/site.plp/perlcheat> \- home of the Perl Cheat Sheet
diff --git a/upstream/mageia-cauldron/man1/perlclass.1 b/upstream/mageia-cauldron/man1/perlclass.1
new file mode 100644
index 00000000..1b6622bc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlclass.1
@@ -0,0 +1,382 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCLASS 1"
+.TH PERLCLASS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlclass \- Perl class syntax reference
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use v5.38;
+\&    use feature \*(Aqclass\*(Aq;
+\&
+\&    class My::Example 1.234 {
+\&        field $x;
+\&
+\&        ADJUST {
+\&            $x = "Hello, world";
+\&        }
+\&
+\&        method print_message {
+\&            say $x;
+\&        }
+\&    }
+\&
+\&    My::Example\->new\->print_message;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the syntax of the Perl's \f(CW\*(C`class\*(C'\fR feature, which
+provides native keywords supporting object-oriented programming paradigm.
+.SS History
+.IX Subsection "History"
+Since Perl 5, support for objects revolved around the concept of \fIblessing\fR
+references with a package name. Such reference could then be used to call
+subroutines from the package it was blessed with (or any of its parents). This
+system, while bare-bones, was flexible enough to allow creation of multiple
+more advanced, community-driven systems for object orientation.
+.PP
+Class feature is a core implementation of class syntax which is familiar to
+what one would find in other programming languages. It isn't a \f(CW\*(C`bless\*(C'\fR
+wrapper, but a completely new system built right into the perl interpreter.
+.SH KEYWORDS
+.IX Header "KEYWORDS"
+Enabling the \f(CW\*(C`class\*(C'\fR feature allows the usage of the following new keywords in
+the scope of current package:
+.SS class
+.IX Subsection "class"
+.Vb 1
+\&    class NAME BLOCK
+\&
+\&    class NAME VERSION BLOCK
+\&
+\&    class NAME;
+\&
+\&    class NAME VERSION;
+.Ve
+.PP
+The \f(CW\*(C`class\*(C'\fR keyword declares a new package which is intended to be a class.
+All other keywords from the \f(CW\*(C`class\*(C'\fR feature should be used in scope of this
+declaration.
+.PP
+.Vb 3
+\&    class WithVersion 1.000 {
+\&        # class definition goes here
+\&    }
+.Ve
+.PP
+Classes can be declared in either block or statement syntax. If a block is
+used, the body of the block contains the implementation of the class. If the
+statement form is used, the remainder of the file is used up until the next
+\&\f(CW\*(C`class\*(C'\fR or \f(CW\*(C`package\*(C'\fR statement.
+.PP
+\&\f(CW\*(C`class\*(C'\fR and \f(CW\*(C`package\*(C'\fR declarations are similar, but classes automatically get
+a constructor named \f(CW\*(C`new\*(C'\fR \- You don't have to (and should not) write one.
+Additionally, in the class BLOCK you are allowed to declare fields and methods.
+.SS field
+.IX Subsection "field"
+.Vb 1
+\&    field VARIABLE_NAME;
+\&
+\&    field VARIABLE_NAME = EXPR;
+\&
+\&    field VARIABLE_NAME : ATTRIBUTES;
+\&
+\&    field VARIABLE_NAME : ATTRIBUTES = EXPR;
+.Ve
+.PP
+Fields are variables which are visible in the scope of the class \- more
+specifically within "method" and \f(CW\*(C`ADJUST\*(C'\fR blocks. Each class instance get
+their own storage of fields, independent of each other.
+.PP
+A field behaves like a normal lexically scoped variable. It has a sigil and is
+private to the class (though creation of an accessor method will make it
+accessible from the outside). The main difference is that different instances
+access different values in the same scope.
+.PP
+.Vb 5
+\&    class WithFields {
+\&        field $scalar = 42;
+\&        field @array  = qw(this is just an array);
+\&        field %hash   = (species => \*(AqMartian\*(Aq, planet => \*(AqMars\*(Aq);
+\&    }
+.Ve
+.PP
+Fields may optionally have initializing expressions. If present, the expression
+will be evaluated within the constructor of each object instance. During each
+evaluation, the expression can use the value of any previously-set field, as
+well as see any other variables in scope.
+.PP
+.Vb 4
+\&    class WithACounter {
+\&        my $next_count = 1;
+\&        field $count = $next_count++;
+\&    }
+.Ve
+.PP
+When combined with the \f(CW\*(C`:param\*(C'\fR field attribute, the defaulting expression can
+use any of the \f(CW\*(C`=\*(C'\fR, \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR operators. Expressions using \f(CW\*(C`=\*(C'\fR will
+apply whenever the caller did not pass the corresponding parameter to the
+constructor at all. Expressions using \f(CW\*(C`//=\*(C'\fR will also apply if the caller did
+pass the parameter but the value was undefined, and expressions using \f(CW\*(C`||=\*(C'\fR
+will apply if the value was false.
+.SS method
+.IX Subsection "method"
+.Vb 1
+\&    method METHOD_NAME SIGNATURE BLOCK
+\&
+\&    method METHOD_NAME BLOCK
+\&
+\&    method SIGNATURE BLOCK
+\&
+\&    method BLOCK
+.Ve
+.PP
+Methods are subroutines intended to be called in the context of class objects.
+.PP
+A variable named \f(CW$self\fR populated with the current object instance will
+automatically be created in the lexical scope of \f(CW\*(C`method\*(C'\fR.
+.PP
+Methods always act as if \f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR is in effect, but \f(CW$self\fR
+will not appear in the arguments list as far as the signature is concerned.
+.PP
+.Vb 2
+\&    class WithMethods {
+\&        field $greetings;
+\&
+\&        ADJUST {
+\&            $greetings = "Hello";
+\&        }
+\&
+\&        method greet($name = "someone") {
+\&            say "$greetings, $name";
+\&        }
+\&    }
+.Ve
+.PP
+Just like regular subroutines, methods \fIcan\fR be anonymous:
+.PP
+.Vb 1
+\&    class AnonMethodFactory {
+\&
+\&        method get_anon_method {
+\&            return method {
+\&                return \*(Aqthis is an anonymous method\*(Aq;
+\&            };
+\&        }
+\&    }
+.Ve
+.SH ATTRIBUTES
+.IX Header "ATTRIBUTES"
+Specific aspects of the keywords mentioned above are managed using
+\&\fIattributes\fR. Attributes all start with a colon, and one or more of them can
+be appended after the item's name, separated by a space.
+.SS "Class attributes"
+.IX Subsection "Class attributes"
+\fI:isa\fR
+.IX Subsection ":isa"
+.PP
+Classes may inherit from \fBone\fR superclass, by using the \f(CW\*(C`:isa\*(C'\fR class
+attribute.
+.PP
+.Vb 1
+\&    class Example::Base { ... }
+\&
+\&    class Example::Subclass :isa(Example::Base) { ... }
+.Ve
+.PP
+Inherited methods are visible and may be invoked. Fields are always lexical
+and therefore not visible by inheritance.
+.PP
+The \f(CW\*(C`:isa\*(C'\fR attribute may request a minimum version of the base class; it is
+applied similar to \f(CW\*(C`use\*(C'\fR \- if the provided version is too low it will fail at
+compile time.
+.PP
+.Vb 1
+\&    class Example::Subclass :isa(Example::Base 2.345) { ... }
+.Ve
+.PP
+The \f(CW\*(C`:isa\*(C'\fR attribute will attempt to \f(CW\*(C`require\*(C'\fR the named module if it is not
+already loaded.
+.SS "Field attributes"
+.IX Subsection "Field attributes"
+\fI:param\fR
+.IX Subsection ":param"
+.PP
+A scalar field with a \f(CW\*(C`:param\*(C'\fR attribute will take its value from a named
+parameter passed to the constructor. By default the parameter will have the
+same name as the field (minus its leading \f(CW\*(C`$\*(C'\fR sigil), but a different name
+can be specified in the attribute.
+.PP
+.Vb 2
+\&    field $x :param;
+\&    field $y :param(the_y_value);
+.Ve
+.PP
+If there is no defaulting expression then the parameter is required by the
+constructor; the caller must pass it or an exception is thrown. With a
+defaulting expression this becomes optional.
+.SS "Method attributes"
+.IX Subsection "Method attributes"
+None yet.
+.SH "OBJECT LIFECYCLE"
+.IX Header "OBJECT LIFECYCLE"
+.SS Construction
+.IX Subsection "Construction"
+Each object begins its life with a constructor call. The constructor is always
+named \f(CW\*(C`new\*(C'\fR and is invoked like a method call on the class name:
+.PP
+.Vb 1
+\&    my $object = My::Class\->new(%arguments);
+.Ve
+.PP
+During the construction, class fields are compared to \f(CW%arguments\fR hash and
+populated where possible.
+.SS Adjustment
+.IX Subsection "Adjustment"
+Object adjustment can be performed during the construction to run user-defined
+code. It is done with the help of \f(CW\*(C`ADJUST\*(C'\fR blocks, which are called in order
+of declaration.
+.PP
+They are similar to \f(CW\*(C`BEGIN\*(C'\fR blocks, which run during the compilation of a
+package. However, they also have access to \f(CW$self\fR lexical (object instance)
+and all object fields created up to that point.
+.SS Lifetime
+.IX Subsection "Lifetime"
+After the construction phase, object is ready to be used.
+.PP
+Using \f(CW\*(C`blessed\*(C'\fR (\f(CW\*(C`Scalar::Util::blessed\*(C'\fR or \f(CW\*(C`builtin::blessed\*(C'\fR) on the
+object will return the name of the class, while \f(CW\*(C`reftype\*(C'\fR
+(\f(CW\*(C`Scalar::Util::reftype\*(C'\fR or \f(CW\*(C`builtin::reftype\*(C'\fR) will return the string
+\&\f(CW\*(AqOBJECT\*(Aq\fR.
+.SS Destruction
+.IX Subsection "Destruction"
+Just like with other references, when object reference count reaches zero it
+will automatically be destroyed.
+.SH TODO
+.IX Header "TODO"
+This feature is still experimental and very incomplete. The following list
+gives some overview of the kinds of work still to be added or changed:
+.IP \(bu 4
+Roles
+.Sp
+Some syntax for declaring a role (likely a \f(CW\*(C`role\*(C'\fR keyword), and for consuming
+a role into a class (likely a \f(CW:does()\fR attribute).
+.IP \(bu 4
+Parameters to ADJUST blocks
+.Sp
+Some syntax for declaring that an \f(CW\*(C`ADJUST\*(C'\fR block can consume named
+parameters, which become part of the class constructor's API. This might be
+inspired by a similar plan to add named arguments to subroutine signatures.
+.Sp
+.Vb 5
+\&    class X {
+\&        ADJUST (:$alpha, :$beta = 123) {
+\&           ...
+\&        }
+\&    }
+\&
+\&    my $obj = X\->new(alpha => 456);
+.Ve
+.IP \(bu 4
+ADJUST blocks as true blocks
+.Sp
+Currently, every ADJUST block is wrapped in its own CV that gets invoked with
+the full ENTERSUB overhead. It should be possible to use the same mechanism
+that makes all field initializer expressions appear within the same CV on
+ADJUST blocks as well, merging them all into a single CV per class. This will
+make it faster to invoke if a class has more than one of them.
+.IP \(bu 4
+Accessor generator attributes
+.Sp
+Attributes to request that accessor methods be generated for fields. Likely
+\&\f(CW\*(C`:reader\*(C'\fR and \f(CW\*(C`:writer\*(C'\fR.
+.Sp
+.Vb 3
+\&    class X {
+\&        field $name :reader;
+\&    }
+.Ve
+.Sp
+Equivalent to
+.Sp
+.Vb 4
+\&    class X {
+\&        field $name;
+\&        method name { return $name; }
+\&    }
+.Ve
+.IP \(bu 4
+Metaprogramming
+.Sp
+An extension of the metaprogramming API (currently proposed by
+RFC0022 <https://github.com/Perl/RFCs/pull/25>) which adds knowledge of
+classes, methods, fields, ADJUST blocks, and other such class-related details.
+.IP \(bu 4
+Extension Customisation
+.Sp
+Ways in which out-of-core modules can interact with the class system,
+including an ability for them to provide new class or field attributes.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Paul Evans
+.PP
+Bartosz Jarzyna
diff --git a/upstream/mageia-cauldron/man1/perlclassguts.1 b/upstream/mageia-cauldron/man1/perlclassguts.1
new file mode 100644
index 00000000..c166ea08
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlclassguts.1
@@ -0,0 +1,466 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCLASSGUTS 1"
+.TH PERLCLASSGUTS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlclassguts \- Internals of how "feature \*(Aqclass\*(Aq" and class syntax works
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides in-depth information about the way in which the perl
+interpreter implements the \f(CW\*(C`feature \*(Aqclass\*(Aq\*(C'\fR syntax and overall behaviour.
+It is not intended as an end-user guide on how to use the feature. For that,
+see perlclass.
+.PP
+The reader is assumed to be generally familiar with the perl interpreter
+internals overall. For a more general overview of these details, see also
+perlguts.
+.SH "DATA STORAGE"
+.IX Header "DATA STORAGE"
+.SS Classes
+.IX Subsection "Classes"
+A class is fundamentally a package, and exists in the symbol table as an HV
+with an aux structure in exactly the same way as a non-class package. It is
+distinguished from a non-class package by the fact that the
+\&\f(CWHvSTASH_IS_CLASS()\fR macro will return true on it.
+.PP
+Extra information relating to it being a class is stored in the
+\&\f(CW\*(C`struct xpvhv_aux\*(C'\fR structure attached to the stash, in the following fields:
+.PP
+.Vb 6
+\&    HV          *xhv_class_superclass;
+\&    CV          *xhv_class_initfields_cv;
+\&    AV          *xhv_class_adjust_blocks;
+\&    PADNAMELIST *xhv_class_fields;
+\&    PADOFFSET    xhv_class_next_fieldix;
+\&    HV          *xhv_class_param_map;
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_superclass\*(C'\fR will be \f(CW\*(C`NULL\*(C'\fR for a class with no superclass. It
+will point directly to the stash of the parent class if one has been set with
+the \f(CW:isa()\fR class attribute.
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_initfields_cv\*(C'\fR will contain a \f(CW\*(C`CV *\*(C'\fR pointing to a function to be
+invoked as part of the constructor of this class or any subclass thereof. This
+CV is responsible for initializing all the fields defined by this class for a
+new instance. This CV will be an anonymous real function \- i.e. while it has no
+name and no GV, it is \fInot\fR a protosub and may be directly invoked.
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_adjust_blocks\*(C'\fR may point to an AV containing CV pointers to each of
+the \f(CW\*(C`ADJUST\*(C'\fR blocks defined on the class. If the class has a superclass, this
+array will additionally contain duplicate pointers of the CVs of its parent
+class. The AV is created lazily the first time an element is pushed to it; it
+is valid for there not to be one, and this pointer will be \f(CW\*(C`NULL\*(C'\fR in that
+case.
+.Sp
+The CVs are stored directly, not via RVs. Each CV will be an anonymous real
+function.
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_fields\*(C'\fR will point to a \f(CW\*(C`PADNAMELIST\*(C'\fR containing \f(CW\*(C`PADNAME\*(C'\fRs,
+each being one defined field of the class. They are stored in order of
+declaration. Note however, that the index into this array will not necessarily
+be equal to the \f(CW\*(C`fieldix\*(C'\fR of each field, because in the case of a subclass,
+the array will begin at zero but the index of the first field in it will be
+non-zero if its parent class contains any fields at all.
+.Sp
+For more information on how individual fields are represented, see "Fields".
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_next_fieldix\*(C'\fR gives the field index that will be assigned to the
+next field to be added to the class. It is only useful at compile-time.
+.IP \(bu 4
+\&\f(CW\*(C`xhv_class_param_map\*(C'\fR may point to an HV which maps field \f(CW\*(C`:param\*(C'\fR attribute
+names to the field index of the field with that name. This mapping is copied
+from parent classes; each class will contain the sum total of all its parents
+in addition to its own.
+.SS Fields
+.IX Subsection "Fields"
+A field is still fundamentally a lexical variable declared in a scope, and
+exists in the \f(CW\*(C`PADNAMELIST\*(C'\fR of its corresponding CV. Methods and other
+method-like CVs can still capture them exactly as they can with regular
+lexicals. A field is distinguished from other kinds of pad entry in that the
+\&\f(CWPadnameIsFIELD()\fR macro will return true on it.
+.PP
+Extra information relating to it being a field is stored in an additional
+structure accessible via the \f(CWPadnameFIELDINFO()\fR macro on the padname. This
+structure has the following fields:
+.PP
+.Vb 6
+\&    PADOFFSET  fieldix;
+\&    HV        *fieldstash;
+\&    OP        *defop;
+\&    SV        *paramname;
+\&    bool       def_if_undef;
+\&    bool       def_if_false;
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`fieldix\*(C'\fR stores the "field index" of the field; that is, the index into the
+instance field array where this field's value will be stored. Note that the
+first index in the array is not specially reserved. The first field in a class
+will start from field index 0.
+.IP \(bu 4
+\&\f(CW\*(C`fieldstash\*(C'\fR stores a pointer to the stash of the class that defined this
+field. This is necessary in case there are multiple classes defined within the
+same scope; it is used to disambiguate the fields of each.
+.Sp
+.Vb 4
+\&    {
+\&        class C1; field $x;
+\&        class C2; field $x;
+\&    }
+.Ve
+.IP \(bu 4
+\&\f(CW\*(C`defop\*(C'\fR may store a pointer to a defaulting expression optree for this field.
+Defaulting expressions are optional; this field may be \f(CW\*(C`NULL\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`paramname\*(C'\fR may point to a regular string SV containing the \f(CW\*(C`:param\*(C'\fR name
+attribute given to the field. If none, it will be \f(CW\*(C`NULL\*(C'\fR.
+.IP \(bu 4
+One of \f(CW\*(C`def_if_undef\*(C'\fR and \f(CW\*(C`def_if_false\*(C'\fR will be true if the defaulting
+expression was set using the \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR operators respectively.
+.SS Methods
+.IX Subsection "Methods"
+A method is still fundamentally a CV, and has the same basic representation as
+one. It has an optree and a pad, and is stored via a GV in the stash of its
+containing package. It is distinguished from a non-method CV by the fact that
+the \f(CWCvIsMETHOD()\fR macro will return true on it.
+.PP
+(Note: This macro should not be confused with the one that was previously
+called \f(CWCvMETHOD()\fR. That one does not relate to the class system, and was
+renamed to \f(CWCvNOWARN_AMBIGUOUS()\fR to avoid this confusion.)
+.PP
+There is currently no extra information that needs to be stored about a method
+CV, so the structure does not add any new fields.
+.SS Instances
+.IX Subsection "Instances"
+Object instances are represented by an entirely new SV type, whose base type
+is \f(CW\*(C`SVt_PVOBJ\*(C'\fR. This should still be blessed into its class stash and wrapped
+in an RV in the usual manner for classical object.
+.PP
+As these are their own unique container type, distinct from hashes or arrays,
+the core \f(CW\*(C`builtin::reftype\*(C'\fR function returns a new value when asked about
+these. That value is \f(CW"OBJECT"\fR.
+.PP
+Internally, such an object is an array of SV pointers whose size is fixed at
+creation time (because the number of fields in a class is known after
+compilation). An object instance stores the max field index within it (for
+basic error-checking on access), and a fixed-size array of SV pointers storing
+the individual field values.
+.PP
+Fields of array and hash type directly store AV or HV pointers into the array;
+they are not stored via an intervening RV.
+.SH API
+.IX Header "API"
+The data structures described above are supported by the following API
+functions.
+.SS "Class Manipulation"
+.IX Subsection "Class Manipulation"
+\fIclass_setup_stash\fR
+.IX Subsection "class_setup_stash"
+.PP
+.Vb 1
+\&    void class_setup_stash(HV *stash);
+.Ve
+.PP
+Called by the parser on encountering the \f(CW\*(C`class\*(C'\fR keyword. It upgrades the
+stash into being a class and prepares it for receiving class-specific items
+like methods and fields.
+.PP
+\fIclass_seal_stash\fR
+.IX Subsection "class_seal_stash"
+.PP
+.Vb 1
+\&    void class_seal_stash(HV *stash);
+.Ve
+.PP
+Called by the parser at the end of a \f(CW\*(C`class\*(C'\fR block, or for unit classes its
+containing scope. This function performs various finalisation activities that
+are required before instances of the class can be constructed, but could not
+have been done until all the information about the members of the class is
+known.
+.PP
+Any additions to or modifications of the class under compilation must be
+performed between these two function calls. Classes cannot be modified once
+they have been sealed.
+.PP
+\fIclass_add_field\fR
+.IX Subsection "class_add_field"
+.PP
+.Vb 1
+\&    void class_add_field(HV *stash, PADNAME *pn);
+.Ve
+.PP
+Called by \fIpad.c\fR as part of defining a new field name in the current pad.
+Note that this function does \fInot\fR create the padname; that must already be
+done by \fIpad.c\fR. This API function simply informs the class that the new
+field name has been created and is now available for it.
+.PP
+\fIclass_add_ADJUST\fR
+.IX Subsection "class_add_ADJUST"
+.PP
+.Vb 1
+\&    void class_add_ADJUST(HV *stash, CV *cv);
+.Ve
+.PP
+Called by the parser once it has parsed and constructed a CV for a new
+\&\f(CW\*(C`ADJUST\*(C'\fR block. This gets added to the list stored by the class.
+.SS "Field Manipulation"
+.IX Subsection "Field Manipulation"
+\fIclass_prepare_initfield_parse\fR
+.IX Subsection "class_prepare_initfield_parse"
+.PP
+.Vb 1
+\&    void class_prepare_initfield_parse();
+.Ve
+.PP
+Called by the parser just before parsing an initializing expression for a
+field variable. This makes use of a suspended compcv to combine all the field
+initializing expressions into the same CV.
+.PP
+\fIclass_set_field_defop\fR
+.IX Subsection "class_set_field_defop"
+.PP
+.Vb 1
+\&    void class_set_field_defop(PADNAME *pn, OPCODE defmode, OP *defop);
+.Ve
+.PP
+Called by the parser after it has parsed an initializing expression for the
+field. Sets the defaulting expression and mode of application. \f(CW\*(C`defmode\*(C'\fR
+should either be zero, or one of \f(CW\*(C`OP_ORASSIGN\*(C'\fR or \f(CW\*(C`OP_DORASSIGN\*(C'\fR depending
+on the defaulting mode.
+.PP
+\fIpadadd_FIELD\fR
+.IX Subsection "padadd_FIELD"
+.PP
+.Vb 1
+\&    #define padadd_FIELD
+.Ve
+.PP
+This flag constant tells the \f(CW\*(C`pad_add_name_*\*(C'\fR family of functions that the
+new name should be added as a field. There is no need to call
+\&\f(CWclass_add_field()\fR; this will be done automatically.
+.SS "Method Manipulation"
+.IX Subsection "Method Manipulation"
+\fIclass_prepare_method_parse\fR
+.IX Subsection "class_prepare_method_parse"
+.PP
+.Vb 1
+\&    void class_prepare_method_parse(CV *cv);
+.Ve
+.PP
+Called by the parser after \f(CWstart_subparse()\fR but immediately before doing
+anything else. This prepares the \f(CW\*(C`PL_compcv\*(C'\fR for parsing a method; arranging
+for the \f(CW\*(C`CvIsMETHOD\*(C'\fR test to be true, adding the \f(CW$self\fR lexical, and any
+other activities that may be required.
+.PP
+\fIclass_wrap_method_body\fR
+.IX Subsection "class_wrap_method_body"
+.PP
+.Vb 1
+\&    OP *class_wrap_method_body(OP *o);
+.Ve
+.PP
+Called by the parser at the end of parsing a method body into an optree but
+just before wrapping it in the eventual CV. This function inserts extra ops
+into the optree to make the method work correctly.
+.SS "Object Instances"
+.IX Subsection "Object Instances"
+\fISVt_PVOBJ\fR
+.IX Subsection "SVt_PVOBJ"
+.PP
+.Vb 1
+\&    #define SVt_PVOBJ
+.Ve
+.PP
+An SV type constant used for comparison with the \f(CWSvTYPE()\fR macro.
+.PP
+\fIObjectMAXFIELD\fR
+.IX Subsection "ObjectMAXFIELD"
+.PP
+.Vb 1
+\&    SSize_t ObjectMAXFIELD(sv);
+.Ve
+.PP
+A function-like macro that obtains the maximum valid field index that can be
+accessed from the \f(CW\*(C`ObjectFIELDS\*(C'\fR array.
+.PP
+\fIObjectFIELDS\fR
+.IX Subsection "ObjectFIELDS"
+.PP
+.Vb 1
+\&    SV **ObjectFIELDS(sv);
+.Ve
+.PP
+A function-like macro that obtains the fields array directly out of an object
+instance. Fields can be accessed by their field index, from 0 up to the maximum
+valid index given by \f(CW\*(C`ObjectMAXFIELD\*(C'\fR.
+.SH OPCODES
+.IX Header "OPCODES"
+.SS OP_METHSTART
+.IX Subsection "OP_METHSTART"
+.Vb 1
+\&    newUNOP_AUX(OP_METHSTART, ...);
+.Ve
+.PP
+An \f(CW\*(C`OP_METHSTART\*(C'\fR is an \f(CW\*(C`UNOP_AUX\*(C'\fR which must be present at the start of a
+method CV in order to make it work properly. This is inserted by
+\&\f(CWclass_wrap_method_body()\fR, and even appears before any optree fragment
+associated with signature argument checking or extraction.
+.PP
+This op is responsible for shifting the value of \f(CW$self\fR out of the arguments
+list and binding any field variables that the method requires access to into
+the pad. The AUX vector will contain details of the field/pad index pairings
+required.
+.PP
+This op also performs sanity checking on the invocant value. It checks that it
+is definitely an object reference of a compatible class type. If not, an
+exception is thrown.
+.PP
+If the \f(CW\*(C`op_private\*(C'\fR field includes the \f(CW\*(C`OPpINITFIELDS\*(C'\fR flag, this indicates
+that the op begins the special \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR CV. In this case it
+should additionally take the second value from the arguments list, which
+should be a plain HV pointer (\fIdirectly\fR, not via RV). and bind it to the
+second pad slot, where the generated optree will expect to find it.
+.SS OP_INITFIELD
+.IX Subsection "OP_INITFIELD"
+An \f(CW\*(C`OP_INITFIELD\*(C'\fR is only invoked as part of the \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR
+CV during the construction phase of an instance. This is the time that the
+individual SVs that make up the mutable fields of the instance (including AVs
+and HVs) are actually assigned into the \f(CW\*(C`ObjectFIELDS\*(C'\fR array. The
+\&\f(CW\*(C`OPpINITFIELD_AV\*(C'\fR and \f(CW\*(C`OPpINITFIELD_HV\*(C'\fR private flags indicate whether it is
+creating an AV or HV; if neither is set then an SV is created.
+.PP
+If the op has the \f(CW\*(C`OPf_STACKED\*(C'\fR flag it expects to find an initializing value
+on the stack. For SVs this is the topmost SV on the data stack. For AVs and
+HVs it expects a marked list.
+.SH "COMPILE-TIME BEHAVIOUR"
+.IX Header "COMPILE-TIME BEHAVIOUR"
+.ie n .SS """ADJUST"" Phasers"
+.el .SS "\f(CWADJUST\fP Phasers"
+.IX Subsection "ADJUST Phasers"
+During compiletime, parsing of an \f(CW\*(C`ADJUST\*(C'\fR phaser is handled in a
+fundamentally different way to the existing perl phasers (\f(CW\*(C`BEGIN\*(C'\fR, etc...)
+.PP
+Rather than taking the usual route, the tokenizer recognises that the
+\&\f(CW\*(C`ADJUST\*(C'\fR keyword introduces a phaser block. The parser then parses the body
+of this block similarly to how it would parse an (anonymous) method body,
+creating a CV that has no name GV. This is then inserted directly into the
+class information by calling \f(CW\*(C`class_add_ADJUST\*(C'\fR, entirely bypassing the
+symbol table.
+.SS Attributes
+.IX Subsection "Attributes"
+During compilation, attributes of both classes and fields are handled in a
+different way to existing perl attributes on subroutines and lexical
+variables.
+.PP
+The parser still forms an \f(CW\*(C`OP_LIST\*(C'\fR optree of \f(CW\*(C`OP_CONST\*(C'\fR nodes, but these
+are passed to the \f(CW\*(C`class_apply_attributes\*(C'\fR or \f(CW\*(C`class_apply_field_attributes\*(C'\fR
+functions. Rather than using a class lookup for a method in the class being
+parsed, a fixed internal list of known attributes is used to find functions to
+apply the attribute to the class or field. In future this may support
+user-supplied extension attribute, though at present it only recognises ones
+defined by the core itself.
+.SS "Field Initializing Expressions"
+.IX Subsection "Field Initializing Expressions"
+During compilation, the parser makes use of a suspended compcv when parsing
+the defaulting expression for a field. All the expressions for all the fields
+in the class share the same suspended compcv, which is then compiled up into
+the same internal CV called by the constructor to initialize all the fields
+provided by that class.
+.SH "RUNTIME BEHAVIOUR"
+.IX Header "RUNTIME BEHAVIOUR"
+.SS Constructor
+.IX Subsection "Constructor"
+The generated constructor for a class itself is an XSUB which performs three
+tasks in order: it creates the instance SV itself, invokes the field
+initializers, then invokes the ADJUST block CVs. The constructor for any class
+is always the same basic shape, regardless of whether the class has a
+superclass or not.
+.PP
+The field initializers are collected into a generated optree-based CV called
+the field initializer CV. This is the CV which contains all the optree
+fragments for the field initializing expressions. When invoked, the field
+initializer CV might make a chained call to the superclass initializer if one
+exists, before invoking all of the individual field initialization ops. The
+field initializer CV is invoked with two items on the stack; being the
+instance SV and a direct HV containing the constructor parameters. Note
+carefully: this HV is passed \fIdirectly\fR, not via an RV reference. This is
+permitted because both the caller and the callee are directly generated code
+and not arbitrary pure-perl subroutines.
+.PP
+The ADJUST block CVs are all collected into a single flat list, merging all of
+the ones defined by the superclass as well. They are all invoked in order,
+after the field initializer CV.
+.ie n .SS "$self Access During Methods"
+.el .SS "\f(CW$self\fP Access During Methods"
+.IX Subsection "$self Access During Methods"
+When \f(CWclass_prepare_method_parse()\fR is called, it arranges that the pad of
+the new CV body will begin with a lexical called \f(CW$self\fR. Because the pad
+should be freshly-created at this point, this will have the pad index of 1.
+The function checks this and aborts if that is not true.
+.PP
+Because of this fact, code within the body of a method or method-like CV can
+reliably use pad index 1 to obtain the invocant reference. The \f(CW\*(C`OP_INITFIELD\*(C'\fR
+opcode also relies on this fact.
+.PP
+In similar fashion, during the \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR the next pad slot is
+relied on to store the constructor parameters HV, at pad index 2.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Paul Evans
diff --git a/upstream/mageia-cauldron/man1/perlclib.1 b/upstream/mageia-cauldron/man1/perlclib.1
new file mode 100644
index 00000000..6bcd8866
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlclib.1
@@ -0,0 +1,327 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCLIB 1"
+.TH PERLCLIB 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlclib \- Internal replacements for standard C library functions
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+One thing Perl porters should note is that \fIperl\fR doesn't tend to use that
+much of the C standard library internally; you'll see very little use of, 
+for example, the \fIctype.h\fR functions in there. This is because Perl
+tends to reimplement or abstract standard library functions, so that we
+know exactly how they're going to operate.
+.PP
+This is a reference card for people who are familiar with the C library
+and who want to do things the Perl way; to tell them which functions
+they ought to use instead of the more normal C functions.
+.SS Conventions
+.IX Subsection "Conventions"
+In the following tables:
+.ie n .IP """t""" 3
+.el .IP \f(CWt\fR 3
+.IX Item "t"
+is a type.
+.ie n .IP """p""" 3
+.el .IP \f(CWp\fR 3
+.IX Item "p"
+is a pointer.
+.ie n .IP """n""" 3
+.el .IP \f(CWn\fR 3
+.IX Item "n"
+is a number.
+.ie n .IP """s""" 3
+.el .IP \f(CWs\fR 3
+.IX Item "s"
+is a string.
+.PP
+\&\f(CW\*(C`sv\*(C'\fR, \f(CW\*(C`av\*(C'\fR, \f(CW\*(C`hv\*(C'\fR, etc. represent variables of their respective types.
+.SS "File Operations"
+.IX Subsection "File Operations"
+Instead of the \fIstdio.h\fR functions, you should use the Perl abstraction
+layer. Instead of \f(CW\*(C`FILE*\*(C'\fR types, you need to be handling \f(CW\*(C`PerlIO*\*(C'\fR
+types.  Don't forget that with the new PerlIO layered I/O abstraction 
+\&\f(CW\*(C`FILE*\*(C'\fR types may not even be available. See also the \f(CW\*(C`perlapio\*(C'\fR
+documentation for more information about the following functions:
+.PP
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& stdin                       PerlIO_stdin()
+\& stdout                      PerlIO_stdout()
+\& stderr                      PerlIO_stderr()
+\&
+\& fopen(fn, mode)             PerlIO_open(fn, mode)
+\& freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Dep\-
+\&                               recated)
+\& fflush(stream)              PerlIO_flush(perlio)
+\& fclose(stream)              PerlIO_close(perlio)
+.Ve
+.SS "File Input and Output"
+.IX Subsection "File Input and Output"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)
+\&
+\& [f]getc(stream)             PerlIO_getc(perlio)
+\& [f]putc(stream, n)          PerlIO_putc(perlio, n)
+\& ungetc(n, stream)           PerlIO_ungetc(perlio, n)
+.Ve
+.PP
+Note that the PerlIO equivalents of \f(CW\*(C`fread\*(C'\fR and \f(CW\*(C`fwrite\*(C'\fR are slightly
+different from their C library counterparts:
+.PP
+.Vb 2
+\& fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
+\& fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)
+\&
+\& fputs(s, stream)            PerlIO_puts(perlio, s)
+.Ve
+.PP
+There is no equivalent to \f(CW\*(C`fgets\*(C'\fR; one should use \f(CW\*(C`sv_gets\*(C'\fR instead:
+.PP
+.Vb 1
+\& fgets(s, n, stream)         sv_gets(sv, perlio, append)
+.Ve
+.SS "File Positioning"
+.IX Subsection "File Positioning"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& feof(stream)                PerlIO_eof(perlio)
+\& fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
+\& rewind(stream)              PerlIO_rewind(perlio)
+\&
+\& fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
+\& fsetpos(stream, p)          PerlIO_setpos(perlio, sv)
+\&
+\& ferror(stream)              PerlIO_error(perlio)
+\& clearerr(stream)            PerlIO_clearerr(perlio)
+.Ve
+.SS "Memory Management and String Handling"
+.IX Subsection "Memory Management and String Handling"
+.Vb 1
+\& Instead Of:                    Use:
+\&
+\& t* p = malloc(n)               Newx(p, n, t)
+\& t* p = calloc(n, s)            Newxz(p, n, t)
+\& p = realloc(p, n)              Renew(p, n, t)
+\& memcpy(dst, src, n)            Copy(src, dst, n, t)
+\& memmove(dst, src, n)           Move(src, dst, n, t)
+\& memcpy(dst, src, sizeof(t))    StructCopy(src, dst, t)
+\& memset(dst, 0, n * sizeof(t))  Zero(dst, n, t)
+\& memzero(dst, 0)                Zero(dst, n, char)
+\& free(p)                        Safefree(p)
+\&
+\& strdup(p)                      savepv(p)
+\& strndup(p, n)                  savepvn(p, n) (Hey, strndup doesn\*(Aqt
+\&                                               exist!)
+\&
+\& strstr(big, little)            instr(big, little)
+\& strcmp(s1, s2)                 strLE(s1, s2) / strEQ(s1, s2)
+\&                                              / strGT(s1,s2)
+\& strncmp(s1, s2, n)             strnNE(s1, s2, n) / strnEQ(s1, s2, n)
+\&
+\& memcmp(p1, p2, n)              memNE(p1, p2, n)
+\& !memcmp(p1, p2, n)             memEQ(p1, p2, n)
+.Ve
+.PP
+Notice the different order of arguments to \f(CW\*(C`Copy\*(C'\fR and \f(CW\*(C`Move\*(C'\fR than used
+in \f(CW\*(C`memcpy\*(C'\fR and \f(CW\*(C`memmove\*(C'\fR.
+.PP
+Most of the time, though, you'll want to be dealing with SVs internally
+instead of raw \f(CW\*(C`char *\*(C'\fR strings:
+.PP
+.Vb 6
+\& strlen(s)                   sv_len(sv)
+\& strcpy(dt, src)             sv_setpv(sv, s)
+\& strncpy(dt, src, n)         sv_setpvn(sv, s, n)
+\& strcat(dt, src)             sv_catpv(sv, s)
+\& strncat(dt, src)            sv_catpvn(sv, s)
+\& sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
+.Ve
+.PP
+Note also the existence of \f(CW\*(C`sv_catpvf\*(C'\fR and \f(CW\*(C`sv_vcatpvfn\*(C'\fR, combining
+concatenation with formatting.
+.PP
+Sometimes instead of zeroing the allocated heap by using \fBNewxz()\fR you
+should consider "poisoning" the data.  This means writing a bit
+pattern into it that should be illegal as pointers (and floating point
+numbers), and also hopefully surprising enough as integers, so that
+any code attempting to use the data without forethought will break
+sooner rather than later.  Poisoning can be done using the \fBPoison()\fR
+macros, which have similar arguments to \fBZero()\fR:
+.PP
+.Vb 4
+\& PoisonWith(dst, n, t, b)    scribble memory with byte b
+\& PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
+\& PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
+\& Poison(dst, n, t)           equal to PoisonFree(dst, n, t)
+.Ve
+.SS "Character Class Tests"
+.IX Subsection "Character Class Tests"
+There are several types of character class tests that Perl implements.
+The only ones described here are those that directly correspond to C
+library functions that operate on 8\-bit characters, but there are
+equivalents that operate on wide characters, and UTF\-8 encoded strings.
+All are more fully described in "Character classification" in perlapi and
+"Character case changing" in perlapi.
+.PP
+The C library routines listed in the table below return values based on
+the current locale.  Use the entries in the final column for that
+functionality.  The other two columns always assume a POSIX (or C)
+locale.  The entries in the ASCII column are only meaningful for ASCII
+inputs, returning FALSE for anything else.  Use these only when you
+\&\fBknow\fR that is what you want.  The entries in the Latin1 column assume
+that the non-ASCII 8\-bit characters are as Unicode defines, them, the
+same as ISO\-8859\-1, often called Latin 1.
+.PP
+.Vb 1
+\& Instead Of:  Use for ASCII:   Use for Latin1:      Use for locale:
+\&
+\& isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
+\& isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
+\& isascii(c)  isASCII(c)                             isASCII_LC(c)
+\& isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
+\& iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
+\& isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
+\& isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
+\& islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
+\& isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
+\& ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
+\& isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
+\& isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
+\& isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)
+\&
+\& tolower(c)  toLOWER(c)        toLOWER_L1(c)
+\& toupper(c)  toUPPER(c)
+.Ve
+.PP
+To emphasize that you are operating only on ASCII characters, you can
+append \f(CW\*(C`_A\*(C'\fR to each of the macros in the ASCII column: \f(CW\*(C`isALPHA_A\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_A\*(C'\fR, and so on.
+.PP
+(There is no entry in the Latin1 column for \f(CW\*(C`isascii\*(C'\fR even though there
+is an \f(CW\*(C`isASCII_L1\*(C'\fR, which is identical to \f(CW\*(C`isASCII\*(C'\fR;  the
+latter name is clearer.  There is no entry in the Latin1 column for
+\&\f(CW\*(C`toupper\*(C'\fR because the result can be non\-Latin1.  You have to use
+\&\f(CW\*(C`toUPPER_uvchr\*(C'\fR, as described in "Character case changing" in perlapi.)
+.SS "\fIstdlib.h\fP functions"
+.IX Subsection "stdlib.h functions"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& atof(s)                     Atof(s)
+\& atoi(s)                     grok_atoUV(s, &uv, &e)
+\& atol(s)                     grok_atoUV(s, &uv, &e)
+\& strtod(s, &p)               Strtod(s, &p)
+\& strtol(s, &p, n)            Strtol(s, &p, b)
+\& strtoul(s, &p, n)           Strtoul(s, &p, b)
+.Ve
+.PP
+Typical use is to do range checks on \f(CW\*(C`uv\*(C'\fR before casting:
+.PP
+.Vb 9
+\&  int i; UV uv;
+\&  char* end_ptr = input_end;
+\&  if (grok_atoUV(input, &uv, &end_ptr)
+\&      && uv <= INT_MAX)
+\&    i = (int)uv;
+\&    ... /* continue parsing from end_ptr */
+\&  } else {
+\&    ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
+\&  }
+.Ve
+.PP
+Notice also the \f(CW\*(C`grok_bin\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR, and \f(CW\*(C`grok_oct\*(C'\fR functions in
+\&\fInumeric.c\fR for converting strings representing numbers in the respective
+bases into \f(CW\*(C`NV\*(C'\fRs.  Note that \fBgrok_atoUV()\fR doesn't handle negative inputs,
+or leading whitespace (being purposefully strict).
+.PP
+Note that \fBstrtol()\fR and \fBstrtoul()\fR may be disguised as \fBStrtol()\fR, \fBStrtoul()\fR,
+\&\fBAtol()\fR, \fBAtoul()\fR.  Avoid those, too.
+.PP
+In theory \f(CW\*(C`Strtol\*(C'\fR and \f(CW\*(C`Strtoul\*(C'\fR may not be defined if the machine perl is
+built on doesn't actually have strtol and strtoul. But as those 2
+functions are part of the 1989 ANSI C spec we suspect you'll find them
+everywhere by now.
+.PP
+.Vb 3
+\& int rand()                  double Drand01()
+\& srand(n)                    { seedDrand01((Rand_seed_t)n);
+\&                               PL_srand_called = TRUE; }
+\&
+\& exit(n)                     my_exit(n)
+\& system(s)                   Don\*(Aqt. Look at pp_system or use my_popen.
+\&
+\& getenv(s)                   PerlEnv_getenv(s)
+\& setenv(s, val)              my_setenv(s, val)
+.Ve
+.SS "Miscellaneous functions"
+.IX Subsection "Miscellaneous functions"
+You should not even \fBwant\fR to use \fIsetjmp.h\fR functions, but if you
+think you do, use the \f(CW\*(C`JMPENV\*(C'\fR stack in \fIscope.h\fR instead.
+.PP
+For \f(CW\*(C`signal\*(C'\fR/\f(CW\*(C`sigaction\*(C'\fR, use \f(CW\*(C`rsignal(signo, handler)\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlapi, perlapio, perlguts
diff --git a/upstream/mageia-cauldron/man1/perlcn.1 b/upstream/mageia-cauldron/man1/perlcn.1
new file mode 100644
index 00000000..3180cf05
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcn.1
@@ -0,0 +1,189 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCN 1"
+.TH PERLCN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlcn \- 简体中文 Perl 指�
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+欢迎�到 Perl 的天地!
+.PP
+从 5.8.0 版开始, Perl 具备了完善的 Unicode (统一�) 支�,
+也连带支�了许多拉�语系以外的编�方�; CJK (中日韩) 便是其中的一部分.
+Unicode 是国际性的标准, 试图涵盖世界上所有的字符: 西方世界, 东方世界,
+以�两者间的一切 (希腊文, �利亚文, 阿拉伯文, 希伯�文, �度文,
+�地安文, 等等). 它也容纳了多��作系统与平� (如 PC �麦金塔).
+.PP
+Perl 本身以 Unicode 进行�作. 这表示 Perl 内部的字符串数��用 Unicode
+表示; Perl 的函数与�算符 (例如正则表达�匹�) 也能对 Unicode 进行�作.
+在输入�输出时, 为了处�以 Unicode 之�的编�方�储存的数�, Perl
+�供了 Encode 这个模�, �以让你轻易地读写使用旧有的编�格�的数�.
+.PP
+Encode 扩展模�支�下列简体中文的编�方� ('gb2312' 表示 'euc\-cn'):
+.PP
+.Vb 6
+\&    euc\-cn      Unix 扩展字符集, 也就是俗称的国标�
+\&    gb2312\-raw  未�处�的 (低比特) GB2312 字符表
+\&    gb12345     未�处�的中国用�体中文编�
+\&    iso\-ir\-165  GB2312 + GB6345 + GB8565 + 新增字符
+\&    cp936       字�页 936, 也�以用 \*(AqGBK\*(Aq (扩充国标�) 指明
+\&    hz          7 比特逸出� GB2312 编�
+.Ve
+.PP
+举例�说, 将 EUC-CN 编�的文件转� Unicode, �需输入以下命令:
+.PP
+.Vb 1
+\&    perl \-Mencoding=euc\-cn,STDOUT,utf8 \-pe1 < file.euc\-cn > file.utf8
+.Ve
+.PP
+Perl 也内附了 "piconv", 一个完全以 Perl 写�的字符转�工具程�, 用法如下:
+.PP
+.Vb 2
+\&    piconv \-f euc\-cn \-t utf8 < file.euc\-cn > file.utf8
+\&    piconv \-f utf8 \-t euc\-cn < file.utf8 > file.euc\-cn
+.Ve
+.PP
+�外, 利用 encoding 模�, 你�以轻易写出以字符为��的代�, 如下所示:
+.PP
+.Vb 7
+\&    #!/usr/bin/env perl
+\&    # �动 euc\-cn 字串解�; 标准输出入�标准错误都设为 euc\-cn 编�
+\&    use encoding \*(Aqeuc\-cn\*(Aq, STDIN => \*(Aqeuc\-cn\*(Aq, STDOUT => \*(Aqeuc\-cn\*(Aq;
+\&    print length("骆驼");      #  2 (�引�表示字符)
+\&    print length(\*(Aq骆驼\*(Aq);      #  4 (�引�表示字节)
+\&    print index("谆谆教诲", "蛔唤"); # \-1 (�包�此�字符串)
+\&    print index(\*(Aq谆谆教诲\*(Aq, \*(Aq蛔唤\*(Aq); #  1 (从第二个字节开始)
+.Ve
+.PP
+在最�一列例�里, "谆" 的第二个字节与 "谆" 的第一个字节结�� EUC-CN
+�的 "蛔"; "谆" 的第二个字节则与 "教" 的第一个字节结�� "唤".
+这解决了以� EUC-CN �匹�处�上常�的问题.
+.SS �外的中文编�
+.IX Subsection "�外的中文编�"
+如果需�更多的中文编�, �以从 CPAN (<https://www.cpan.org/>) 下载
+Encode::HanExtra 模�. 它目��供下列编�方�:
+.PP
+.Vb 1
+\&    gb18030     扩充过的国标�, 包��体中文
+.Ve
+.PP
+�外, Encode::HanConvert 模�则�供了简�转�用的两�编�:
+.PP
+.Vb 2
+\&    big5\-simp   Big5 �体中文与 Unicode 简体中文互转
+\&    gbk\-trad    GBK 简体中文与 Unicode �体中文互转
+.Ve
+.PP
+若想在 GBK 与 Big5 之间互转, 请�考该模�内附的 b2g.pl 与 g2b.pl 两个程�,
+或在程�内使用下列写法:
+.PP
+.Vb 3
+\&    use Encode::HanConvert;
+\&    $euc_cn = big5_to_gb($big5); # 从 Big5 转为 GBK
+\&    $big5 = gb_to_big5($euc_cn); # 从 GBK 转为 Big5
+.Ve
+.SS 进一步的信�
+.IX Subsection "进一步的信�"
+请�考 Perl 内附的大�说明文件 (�幸全是用英文写的), �学习更多关于
+Perl 的知识, 以� Unicode 的使用方�. �过, 外部的资�相当丰富:
+.SS "�供 Perl 资�的网�"
+.IX Subsection "�供 Perl 资�的网�"
+.IP <https://www.perl.org/> 4
+.IX Item "<https://www.perl.org/>"
+.PP
+Perl 的首页
+.IP <https://www.perl.com/> 4
+.IX Item "<https://www.perl.com/>"
+由 Perl 基金会��的文章辑录
+.IP <https://www.cpan.org/> 4
+.IX Item "<https://www.cpan.org/>"
+Perl 综�典�网 (Comprehensive Perl Archive Network)
+.IP <https://lists.perl.org/> 4
+.IX Item "<https://lists.perl.org/>"
+Perl 邮递论�一览
+.SS "学习 Perl 的网�"
+.IX Subsection "学习 Perl 的网�"
+.IP <http://www.oreilly.com.cn/index.php?func=booklist&cat=68> 4
+.IX Item "<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>"
+简体中文版的欧莱礼 Perl 书藉
+.SS "Perl 使用者集会"
+.IX Subsection "Perl 使用者集会"
+.IP <https://www.pm.org/groups/asia.html> 4
+.IX Item "<https://www.pm.org/groups/asia.html>"
+中国 Perl 推广组一览
+.SS "Unicode 相关网�"
+.IX Subsection "Unicode 相关网�"
+.IP <https://www.unicode.org/> 4
+.IX Item "<https://www.unicode.org/>"
+Unicode 学术学会 (Unicode 标准的制定者)
+.IP <https://www.cl.cam.ac.uk/%7Emgk25/unicode.html> 4
+.IX Item "<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>"
+Unix/Linux 上的 UTF\-8 � Unicode 常�问题解答
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode, Encode::CN, encoding, perluniintro, perlunicode
+.SH AUTHORS
+.IX Header "AUTHORS"
+Jarkko Hietaniemi <jhi@iki.fi>
+.PP
+Audrey Tang (�凤) <audreyt@audreyt.org>
+.PP
+Sizhe Zhao <prc.zhao@outlook.com>
diff --git a/upstream/mageia-cauldron/man1/perlcommunity.1 b/upstream/mageia-cauldron/man1/perlcommunity.1
new file mode 100644
index 00000000..d2b1ed19
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcommunity.1
@@ -0,0 +1,221 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCOMMUNITY 1"
+.TH PERLCOMMUNITY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlcommunity \- a brief overview of the Perl community
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document aims to provide an overview of the vast perl community, which is
+far too large and diverse to provide a detailed listing. If any specific niche
+has been forgotten, it is not meant as an insult but an omission for the sake
+of brevity.
+.PP
+The Perl community is as diverse as Perl, and there is a large amount of
+evidence that the Perl users apply TMTOWTDI to all endeavors, not just
+programming. From websites, to IRC, to mailing lists, there is more than one
+way to get involved in the community.
+.SS "Where to Find the Community"
+.IX Subsection "Where to Find the Community"
+There is a central directory for the Perl community: <https://perl.org>
+maintained by the Perl Foundation (<https://www.perlfoundation.org/>),
+which tracks and provides services for a variety of other community sites.
+.PP
+\fIRaku\fR
+.IX Subsection "Raku"
+.PP
+Perl's sister language, Raku (formerly known as Perl 6), maintains its own
+directory of community resources at <https://raku.org/community/>.
+.SS "Mailing Lists and Newsgroups"
+.IX Subsection "Mailing Lists and Newsgroups"
+Perl runs on e\-mail; there is no doubt about it. The Camel book was originally
+written mostly over e\-mail and today Perl's development is co-ordinated through
+mailing lists. The largest repository of Perl mailing lists is located at
+<https://lists.perl.org>.
+.PP
+Most Perl-related projects set up mailing lists for both users and
+contributors. If you don't see a certain project listed at
+<https://lists.perl.org>, check the particular website for that project.
+Most mailing lists are archived at <https://www.nntp.perl.org/>.
+.SS IRC
+.IX Subsection "IRC"
+The Perl community has a rather large IRC presence. For starters, it has its
+own IRC network, <irc://irc.perl.org>. General (not help-oriented) chat can be
+found at <irc://irc.perl.org/#perl>. Many other more specific chats are also
+hosted on the network. Information about irc.perl.org is located on the
+network's website: <https://www.irc.perl.org>. For a more help-oriented #perl,
+check out <irc://irc.libera.chat/#perl>
+(webchat <https://web.libera.chat/#perl>). Most Perl-related channels
+will be kind enough to point you in the right direction if you ask nicely.
+.PP
+Any large IRC network (Dalnet, EFnet) is also likely to have a #perl channel,
+with varying activity levels.
+.SS Websites
+.IX Subsection "Websites"
+Perl websites come in a variety of forms, but they fit into two large
+categories: forums and news websites. There are many Perl-related
+websites, so only a few of the community's largest are mentioned here.
+.PP
+\fINews sites\fR
+.IX Subsection "News sites"
+.IP <https://perl.com/> 4
+.IX Item "<https://perl.com/>"
+Originally run by O'Reilly Media (the publisher of the Camel Book,
+this site provides quality articles mostly about technical details of Perl.
+.IP <http://blogs.perl.org/> 4
+.IX Item "<http://blogs.perl.org/>"
+Many members of the community have a Perl-related blog on this site. If
+you'd like to join them, you can sign up for free.
+.IP <https://perl.theplanetarium.org/> 4
+.IX Item "<https://perl.theplanetarium.org/>"
+Planet Perl is one of several aggregators of Perl-related blog feeds.
+.IP <https://perlweekly.com/> 4
+.IX Item "<https://perlweekly.com/>"
+Perl Weekly is a weekly mailing list that keeps you up to date on conferences,
+releases and notable blog posts.
+.PP
+\fIForums\fR
+.IX Subsection "Forums"
+.IP <https://www.perlmonks.org/> 4
+.IX Item "<https://www.perlmonks.org/>"
+PerlMonks is one of the largest Perl forums, and describes itself as "A place
+for individuals to polish, improve, and showcase their Perl skills." and "A
+community which allows everyone to grow and learn from each other."
+.IP <https://stackoverflow.com/> 4
+.IX Item "<https://stackoverflow.com/>"
+Stack Overflow is a free question-and-answer site for programmers. It's not
+focussed solely on Perl, but it does have an active group of users who do
+their best to help people with their Perl programming questions.
+.SS "User Groups"
+.IX Subsection "User Groups"
+Many cities around the world have local Perl Mongers chapters. A Perl Mongers
+chapter is a local user group which typically holds regular in-person meetings,
+both social and technical; helps organize local conferences, workshops, and
+hackathons; and provides a mailing list or other continual contact method for
+its members to keep in touch.
+.PP
+To find your local Perl Mongers (or PM as they're commonly abbreviated) group
+check the international Perl Mongers directory at <https://www.pm.org/>.
+.SS Workshops
+.IX Subsection "Workshops"
+Perl workshops are, as the name might suggest, workshops where Perl is taught
+in a variety of ways. At the workshops, subjects range from a beginner's
+introduction (such as the Pittsburgh Perl Workshop's "Zero To Perl") to much
+more advanced subjects.
+.PP
+There are several great resources for locating workshops: the
+websites mentioned above, the
+calendar mentioned below, and the YAPC Europe
+website, <http://www.yapceurope.org/>, which is probably the best resource for
+European Perl events.
+.SS Hackathons
+.IX Subsection "Hackathons"
+Hackathons are a very different kind of gathering where Perl hackers gather to
+do just that, hack nonstop for an extended (several day) period on a specific
+project or projects. Information about hackathons can be located in the same
+place as information about workshops as well as in
+<irc://irc.perl.org/#perl>.
+.PP
+If you have never been to a hackathon, here are a few basic things you need to
+know before attending: have a working laptop and know how to use it; check out
+the involved projects beforehand; have the necessary version control client;
+and bring backup equipment (an extra LAN cable, additional power strips, etc.)
+because someone will forget.
+.SS Conventions
+.IX Subsection "Conventions"
+Perl had two major annual conventions: The Perl Conference (now part of OSCON),
+put on by O'Reilly, and Yet Another Perl Conference or YAPC (pronounced
+yap-see), which is localized into several regional YAPCs (North America,
+Europe, Asia) in a stunning grassroots display by the Perl community.
+.PP
+In 2016, YAPC was rebranded as The Perl Conference again. It is now referred
+to as The Perl and Raku Conference.
+.PP
+OSCON had been discontinued.
+.PP
+For more information about either conference, check out their respective web
+pages:
+.IP \(bu 4
+The Perl Conference
+.Sp
+<http://perlconference.us/>.
+.IP \(bu 4
+OSCON
+.Sp
+<https://www.oreilly.com/conferences/>
+.PP
+An additional conference franchise with a large Perl portion was the
+Open Source Developers Conference or OSDC. First held in Australia, it
+also spread to Israel and France. More information can be found at:
+<http://www.osdc.org.il> for Israel, and <http://www.osdc.fr/> for France.
+.SS "Calendar of Perl Events"
+.IX Subsection "Calendar of Perl Events"
+The Perl Review, <http://www.theperlreview.com> maintains a website
+and Google calendar for tracking
+workshops, hackathons, Perl Mongers meetings, and other events. A view
+of this calendar is available at <https://www.perl.org/events.html>.
+.PP
+Not every event or Perl Mongers group is on that calendar, so don't lose
+heart if you don't see yours posted. To have your event or group listed,
+contact brian d foy (brian@theperlreview.com).
+.SH AUTHOR
+.IX Header "AUTHOR"
+Edgar "Trizor" Bering <trizor@gmail.com>
diff --git a/upstream/mageia-cauldron/man1/perlcygwin.1 b/upstream/mageia-cauldron/man1/perlcygwin.1
new file mode 100644
index 00000000..43d060df
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcygwin.1
@@ -0,0 +1,797 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCYGWIN 1"
+.TH PERLCYGWIN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlcygwin \- Perl for Cygwin
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+This document will help you configure, make, test and install Perl
+on Cygwin.  This document also describes features of Cygwin that will
+affect how Perl behaves at runtime.
+.PP
+\&\fBNOTE:\fR There are pre-built Perl packages available for Cygwin and a
+version of Perl is provided in the normal Cygwin install.  If you do
+not need to customize the configuration, consider using one of those
+packages.
+.SH "PREREQUISITES FOR COMPILING PERL ON CYGWIN"
+.IX Header "PREREQUISITES FOR COMPILING PERL ON CYGWIN"
+.SS "Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)"
+.IX Subsection "Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)"
+The Cygwin tools are ports of the popular GNU development tools for Win32
+platforms.  They run thanks to the Cygwin library which provides the UNIX
+system calls and environment these programs expect.  More information
+about this project can be found at:
+.PP
+<https://www.cygwin.com/>
+.PP
+A recent net or commercial release of Cygwin is required.
+.PP
+At the time this document was last updated, Cygwin 3.0.7 was current.
+.SS "Cygwin Configuration"
+.IX Subsection "Cygwin Configuration"
+While building Perl some changes may be necessary to your Cygwin setup so
+that Perl builds cleanly.  These changes are \fBnot\fR required for normal
+Perl usage.
+.PP
+\&\fBNOTE:\fR The binaries that are built will run on all Win32 versions.
+They do not depend on your host system or your
+Cygwin configuration (binary/text mounts, cygserver).
+The only dependencies come from hard-coded pathnames like \fI/usr/local\fR.
+However, your host system and Cygwin configuration will affect Perl's
+runtime behavior (see "TEST").
+.IP \(bu 4
+\&\f(CW\*(C`PATH\*(C'\fR
+.Sp
+Set the \f(CW\*(C`PATH\*(C'\fR environment variable so that Configure finds the Cygwin
+versions of programs. Any not-needed Windows directories should be removed or
+moved to the end of your \f(CW\*(C`PATH\*(C'\fR.
+.IP \(bu 4
+\&\fInroff\fR
+.Sp
+If you do not have \fInroff\fR (which is part of the \fIgroff\fR package),
+Configure will \fBnot\fR prompt you to install \fIman\fR pages.
+.SH "CONFIGURE PERL ON CYGWIN"
+.IX Header "CONFIGURE PERL ON CYGWIN"
+The default options gathered by Configure with the assistance of
+\&\fIhints/cygwin.sh\fR will build a Perl that supports dynamic loading
+(which requires a shared \fIcygperl5_16.dll\fR).
+.PP
+This will run Configure and keep a record:
+.PP
+.Vb 1
+\&  ./Configure 2>&1 | tee log.configure
+.Ve
+.PP
+If you are willing to accept all the defaults run Configure with \fB\-de\fR.
+However, several useful customizations are available.
+.SS "Stripping Perl Binaries on Cygwin"
+.IX Subsection "Stripping Perl Binaries on Cygwin"
+It is possible to strip the EXEs and DLLs created by the build process.
+The resulting binaries will be significantly smaller.  If you want the
+binaries to be stripped, you can either add a \fB\-s\fR option when Configure
+prompts you,
+.PP
+.Vb 5
+\&  Any additional ld flags (NOT including libraries)? [none] \-s
+\&  Any special flags to pass to g++ to create a dynamically loaded
+\&  library?
+\&  [none] \-s
+\&  Any special flags to pass to gcc to use dynamic linking? [none] \-s
+.Ve
+.PP
+or you can edit \fIhints/cygwin.sh\fR and uncomment the relevant variables
+near the end of the file.
+.SS "Optional Libraries for Perl on Cygwin"
+.IX Subsection "Optional Libraries for Perl on Cygwin"
+Several Perl functions and modules depend on the existence of
+some optional libraries.  Configure will find them if they are
+installed in one of the directories listed as being used for library
+searches.  Pre-built packages for most of these are available from
+the Cygwin installer.
+.IP \(bu 4
+\&\f(CW\*(C`\-lcrypt\*(C'\fR
+.Sp
+The crypt package distributed with Cygwin is a Linux compatible 56\-bit
+DES crypt port by Corinna Vinschen.
+.Sp
+Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
+.Sp
+As of libcrypt 1.3 (March 2016), you will need to install the
+libcrypt-devel package for Configure to detect \fBcrypt()\fR.
+.IP \(bu 4
+\&\f(CW\*(C`\-lgdbm_compat\*(C'\fR (\f(CW\*(C`use GDBM_File\*(C'\fR)
+.Sp
+GDBM is available for Cygwin.
+.Sp
+NOTE: The GDBM library only works on NTFS partitions.
+.IP \(bu 4
+\&\f(CW\*(C`\-ldb\*(C'\fR (\f(CW\*(C`use DB_File\*(C'\fR)
+.Sp
+BerkeleyDB is available for Cygwin.
+.Sp
+NOTE: The BerkeleyDB library only completely works on NTFS partitions.
+.IP \(bu 4
+\&\f(CW\*(C`cygserver\*(C'\fR (\f(CW\*(C`use IPC::SysV\*(C'\fR)
+.Sp
+A port of SysV IPC is available for Cygwin.
+.Sp
+NOTE: This has \fBnot\fR been extensively tested.  In particular,
+\&\f(CW\*(C`d_semctl_semun\*(C'\fR is undefined because it fails a Configure test.  It
+also creates a compile time dependency because \fIperl.h\fR includes
+\&\fI<sys/ipc.h\fR> and \fI<sys/sem.h\fR> (which will be required in the
+future when compiling CPAN modules). CURRENTLY NOT SUPPORTED!
+.IP \(bu 4
+\&\f(CW\*(C`\-lutil\*(C'\fR
+.Sp
+Included with the standard Cygwin netrelease is the inetutils package
+which includes libutil.a.
+.SS "Configure-time Options for Perl on Cygwin"
+.IX Subsection "Configure-time Options for Perl on Cygwin"
+The \fIINSTALL\fR document describes several Configure-time options.  Some of
+these will work with Cygwin, others are not yet possible.  Also, some of
+these are experimental.  You can either select an option when Configure
+prompts you or you can define (undefine) symbols on the command line.
+.IP \(bu 4
+\&\f(CW\*(C`\-Uusedl\*(C'\fR
+.Sp
+Undefining this symbol forces Perl to be compiled statically.
+.IP \(bu 4
+\&\f(CW\*(C`\-Dusemymalloc\*(C'\fR
+.Sp
+By default Perl does not use the \f(CWmalloc()\fR included with the Perl source,
+because it was slower and not entirely thread-safe.  If you want to force
+Perl to build with the old \-Dusemymalloc define this.
+.IP \(bu 4
+\&\f(CW\*(C`\-Uuseperlio\*(C'\fR
+.Sp
+Undefining this symbol disables the PerlIO abstraction.  PerlIO is now the
+default; it is not recommended to disable PerlIO.
+.IP \(bu 4
+\&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR
+.Sp
+Multiplicity is required when embedding Perl in a C program and using
+more than one interpreter instance.  This is only required when you build
+a not-threaded perl with \f(CW\*(C`\-Uuseithreads\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`\-Uuse64bitint\*(C'\fR
+.Sp
+By default Perl uses 64 bit integers.  If you want to use smaller 32 bit
+integers, define this symbol.
+.IP \(bu 4
+\&\f(CW\*(C`\-Duselongdouble\*(C'\fR
+.Sp
+\&\fIgcc\fR supports long doubles (12 bytes).  However, several additional
+long double math functions are necessary to use them within Perl
+(\fI{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
+strtold\fR).
+These are \fBnot\fR yet available with newlib, the Cygwin libc.
+.IP \(bu 4
+\&\f(CW\*(C`\-Uuseithreads\*(C'\fR
+.Sp
+Define this symbol if you want not-threaded faster perl.
+.IP \(bu 4
+\&\f(CW\*(C`\-Duselargefiles\*(C'\fR
+.Sp
+Cygwin uses 64\-bit integers for internal size and position calculations,
+this will be correctly detected and defined by Configure.
+.IP \(bu 4
+\&\f(CW\*(C`\-Dmksymlinks\*(C'\fR
+.Sp
+Use this to build perl outside of the source tree.  Details can be
+found in the \fIINSTALL\fR document.  This is the recommended way to
+build perl from sources.
+.SH "MAKE ON CYGWIN"
+.IX Header "MAKE ON CYGWIN"
+Simply run \fImake\fR and wait:
+.PP
+.Vb 1
+\&  make \-jn 2>&1 | tee log.make
+.Ve
+.PP
+where \fIn\fR is the maximum number of simultaneous compilations you want;
+omitting this parameter is the same as specifying \f(CW\*(C`\-j1\*(C'\fR.
+.SH "TEST ON CYGWIN"
+.IX Header "TEST ON CYGWIN"
+There are two steps to running the test suite:
+.PP
+.Vb 1
+\&  make test 2>&1 | tee log.make\-test
+\&
+\&  cd t; ./perl harness 2>&1 | tee ../log.harness
+.Ve
+.PP
+The same tests are run both times, but more information is provided when
+running as \f(CW\*(C`./perl harness\*(C'\fR, and you can run the tests in parallel by
+instead specifying
+.PP
+.Vb 1
+\&  cd t; TEST_JOBS=n ./perl harness 2>&1 | tee ../log.harness
+.Ve
+.PP
+where \fIn\fR is the maximum number of tests to run simulataneously.
+.PP
+Test results vary depending on your host system and your Cygwin
+configuration.  If a test can pass in some Cygwin setup, it is always
+attempted and explainable test failures are documented.  It is possible
+for Perl to pass all the tests, but it is more likely that some tests
+will fail for one of the reasons listed below.
+.SS "File Permissions on Cygwin"
+.IX Subsection "File Permissions on Cygwin"
+UNIX file permissions are based on sets of mode bits for
+{read,write,execute} for each {user,group,other}.  By default Cygwin
+only tracks the Win32 read-only attribute represented as the UNIX file
+user write bit (files are always readable, files are executable if they
+have a \fI.{com,bat,exe}\fR extension or begin with \f(CW\*(C`#!\*(C'\fR, directories are
+always readable and executable).  On WinNT with the \fIntea\fR \f(CW\*(C`CYGWIN\*(C'\fR
+setting, the additional mode bits are stored as extended file attributes.
+On WinNT with the default \fIntsec\fR \f(CW\*(C`CYGWIN\*(C'\fR setting, permissions use the
+standard WinNT security descriptors and access control lists. Without one of
+these options, these tests will fail (listing not updated yet):
+.PP
+.Vb 12
+\&  Failed Test           List of failed
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  io/fs.t               5, 7, 9\-10
+\&  lib/anydbm.t          2
+\&  lib/db\-btree.t        20
+\&  lib/db\-hash.t         16
+\&  lib/db\-recno.t        18
+\&  lib/gdbm.t            2
+\&  lib/ndbm.t            2
+\&  lib/odbm.t            2
+\&  lib/sdbm.t            2
+\&  op/stat.t             9, 20 (.tmp not an executable extension)
+.Ve
+.SS "NDBM_File and ODBM_File do not work on FAT filesystems"
+.IX Subsection "NDBM_File and ODBM_File do not work on FAT filesystems"
+Do not use NDBM_File or ODBM_File on FAT filesystem.  They can be
+built on a FAT filesystem, but many tests will fail:
+.PP
+.Vb 6
+\& ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1\-2 4 16\-71
+\& ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
+\& ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
+\& ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7\-11
+\& ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1\-4
+\& run/fresh_perl.t                          97    1   1.03%  91
+.Ve
+.PP
+If you intend to run only on FAT (or if using AnyDBM_File on FAT),
+run Configure with the \-Ui_ndbm and \-Ui_dbm options to prevent
+NDBM_File and ODBM_File being built.
+.PP
+With NTFS (and no CYGWIN=nontsec), there should be no problems even if
+perl was built on FAT.
+.ie n .SS "fork() failures in io_* tests"
+.el .SS "\f(CWfork()\fP failures in io_* tests"
+.IX Subsection "fork() failures in io_* tests"
+A \f(CWfork()\fR failure may result in the following tests failing:
+.PP
+.Vb 3
+\&  ext/IO/lib/IO/t/io_multihomed.t
+\&  ext/IO/lib/IO/t/io_sock.t
+\&  ext/IO/lib/IO/t/io_unix.t
+.Ve
+.PP
+See comment on fork in "Miscellaneous" below.
+.SH "Specific features of the Cygwin port"
+.IX Header "Specific features of the Cygwin port"
+.SS "Script Portability on Cygwin"
+.IX Subsection "Script Portability on Cygwin"
+Cygwin does an outstanding job of providing UNIX-like semantics on top of
+Win32 systems.  However, in addition to the items noted above, there are
+some differences that you should know about.  This is a very brief guide
+to portability, more information can be found in the Cygwin documentation.
+.IP \(bu 4
+Pathnames
+.Sp
+Cygwin pathnames are separated by forward (\fI/\fR) slashes, Universal
+Naming Codes (\fI//UNC\fR) are also supported.  Since cygwin\-1.7 non-POSIX
+pathnames should not be used.  Names may contain all printable
+characters.
+.Sp
+File names are case insensitive, but case preserving.  A pathname that
+contains a backslash or drive letter is a Win32 pathname, and not
+subject to the translations applied to POSIX style pathnames, but
+cygwin will warn you, so better convert them to POSIX.
+.Sp
+For conversion we have \f(CWCygwin::win_to_posix_path()\fR and
+\&\f(CWCygwin::posix_to_win_path()\fR.
+.Sp
+Since cygwin\-1.7 pathnames are UTF\-8 encoded.
+.IP \(bu 4
+Text/Binary
+.Sp
+Since cygwin\-1.7 textmounts are deprecated and strongly discouraged.
+.Sp
+When a file is opened it is in either text or binary mode.  In text mode
+a file is subject to CR/LF/Ctrl\-Z translations.  With Cygwin, the default
+mode for an \f(CWopen()\fR is determined by the mode of the mount that underlies
+the file. See "Cygwin::is_binmount"(). Perl provides a \f(CWbinmode()\fR function
+to set binary mode on files that otherwise would be treated as text.
+\&\f(CWsysopen()\fR with the \f(CW\*(C`O_TEXT\*(C'\fR flag sets text mode on files that otherwise
+would be treated as binary:
+.Sp
+.Vb 1
+\&    sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
+.Ve
+.Sp
+\&\f(CWlseek()\fR, \f(CWtell()\fR and \f(CWsysseek()\fR only work with files opened in binary
+mode.
+.Sp
+The text/binary issue is covered at length in the Cygwin documentation.
+.IP \(bu 4
+PerlIO
+.Sp
+PerlIO overrides the default Cygwin Text/Binary behaviour.  A file will
+always be treated as binary, regardless of the mode of the mount it lives
+on, just like it is in UNIX.  So CR/LF translation needs to be requested in
+either the \f(CWopen()\fR call like this:
+.Sp
+.Vb 1
+\&  open(FH, ">:crlf", "out.txt");
+.Ve
+.Sp
+which will do conversion from LF to CR/LF on the output, or in the
+environment settings (add this to your .bashrc):
+.Sp
+.Vb 1
+\&  export PERLIO=crlf
+.Ve
+.Sp
+which will pull in the crlf PerlIO layer which does LF \-> CRLF conversion
+on every output generated by perl.
+.IP \(bu 4
+\&\fI.exe\fR
+.Sp
+The Cygwin \f(CWstat()\fR, \f(CWlstat()\fR and \f(CWreadlink()\fR functions make the \fI.exe\fR
+extension transparent by looking for \fIfoo.exe\fR when you ask for \fIfoo\fR
+(unless a \fIfoo\fR also exists).  Cygwin does not require a \fI.exe\fR
+extension, but \fIgcc\fR adds it automatically when building a program.
+However, when accessing an executable as a normal file (e.g., \fIcp\fR
+in a makefile) the \fI.exe\fR is not transparent.  The \fIinstall\fR program
+included with Cygwin automatically appends a \fI.exe\fR when necessary.
+.IP \(bu 4
+Cygwin vs. Windows process ids
+.Sp
+Cygwin processes have their own pid, which is different from the
+underlying windows pid.  Most posix compliant Proc functions expect
+the cygwin pid, but several Win32::Process functions expect the
+winpid. E.g. \f(CW$$\fR is the cygwin pid of \fI/usr/bin/perl\fR, which is not
+the winpid.  Use \f(CWCygwin::pid_to_winpid()\fR and \f(CWCygwin::winpid_to_pid()\fR
+to translate between them.
+.IP \(bu 4
+Cygwin vs. Windows errors
+.Sp
+Under Cygwin, $^E is the same as $!.  When using Win32 API Functions,
+use \f(CWWin32::GetLastError()\fR to get the last Windows error.
+.IP \(bu 4
+rebase errors on fork or system
+.Sp
+Using \f(CWfork()\fR or \f(CWsystem()\fR out to another perl after loading multiple dlls
+may result on a DLL baseaddress conflict. The internal cygwin error
+looks like like the following:
+.Sp
+.Vb 2
+\& 0 [main] perl 8916 child_info_fork::abort: data segment start:
+\& parent (0xC1A000) != child(0xA6A000)
+.Ve
+.Sp
+or:
+.Sp
+.Vb 4
+\& 183 [main] perl 3588 C:\ecygwin\ebin\eperl.exe: *** fatal error \-
+\& unable to remap C:\ecygwin\ebin\ecygsvn_subr\-1\-0.dll to same address
+\& as parent(0x6FB30000) != 0x6FE60000 46 [main] perl 3488 fork: child
+\& 3588 \- died waiting for dll loading, errno11
+.Ve
+.Sp
+See <https://cygwin.com/faq/faq.html#faq.using.fixing\-fork\-failures>
+It helps if not too many DLLs are loaded in memory so the available address space is larger,
+e.g. stopping the MS Internet Explorer might help.
+.Sp
++Use the rebase utilities to resolve the conflicting dll addresses.
+The rebase package is included in the Cygwin setup. Use \fIsetup.exe\fR
+from <https://cygwin.com/install.html> to install it.
+.Sp
+1. kill all perl processes and run
+   \f(CW\*(C`</bin/find <dir\*(C'\fR \-xdev \-name \e*.dll | /bin/rebase \-OT \->> or
+.Sp
+2. kill all cygwin processes and services, and run setup.exe.
+.IP \(bu 4
+Miscellaneous
+.Sp
+File locking using the \f(CW\*(C`F_GETLK\*(C'\fR command to \f(CWfcntl()\fR is a stub that
+returns \f(CW\*(C`ENOSYS\*(C'\fR.
+.Sp
+The Cygwin \f(CWchroot()\fR implementation has holes (it can not restrict file
+access by native Win32 programs).
+.Sp
+Inplace editing \f(CW\*(C`perl \-i\*(C'\fR of files doesn't work without doing a backup
+of the file being edited \f(CW\*(C`perl \-i.bak\*(C'\fR because of windowish restrictions,
+therefore Perl adds the suffix \f(CW\*(C`.bak\*(C'\fR automatically if you use \f(CW\*(C`perl \-i\*(C'\fR
+without specifying a backup extension.
+.SS "Prebuilt methods:"
+.IX Subsection "Prebuilt methods:"
+.ie n .IP """Cwd::cwd""" 4
+.el .IP \f(CWCwd::cwd\fR 4
+.IX Item "Cwd::cwd"
+Returns the current working directory.
+.ie n .IP """Cygwin::pid_to_winpid""" 4
+.el .IP \f(CWCygwin::pid_to_winpid\fR 4
+.IX Item "Cygwin::pid_to_winpid"
+Translates a cygwin pid to the corresponding Windows pid (which may or
+may not be the same).
+.ie n .IP """Cygwin::winpid_to_pid""" 4
+.el .IP \f(CWCygwin::winpid_to_pid\fR 4
+.IX Item "Cygwin::winpid_to_pid"
+Translates a Windows pid to the corresponding cygwin pid (if any).
+.ie n .IP """Cygwin::win_to_posix_path""" 4
+.el .IP \f(CWCygwin::win_to_posix_path\fR 4
+.IX Item "Cygwin::win_to_posix_path"
+Translates a Windows path to the corresponding cygwin path respecting
+the current mount points. With a second non-null argument returns an
+absolute path. Double-byte characters will not be translated.
+.ie n .IP """Cygwin::posix_to_win_path""" 4
+.el .IP \f(CWCygwin::posix_to_win_path\fR 4
+.IX Item "Cygwin::posix_to_win_path"
+Translates a cygwin path to the corresponding cygwin path respecting
+the current mount points. With a second non-null argument returns an
+absolute path. Double-byte characters will not be translated.
+.ie n .IP Cygwin::mount_table() 4
+.el .IP \f(CWCygwin::mount_table()\fR 4
+.IX Item "Cygwin::mount_table()"
+Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
+.Sp
+.Vb 8
+\&  perl \-e \*(Aqfor $i (Cygwin::mount_table) {print join(" ",@$i),"\en";}\*(Aq
+\&  /bin c:\ecygwin\ebin system binmode,cygexec
+\&  /usr/bin c:\ecygwin\ebin system binmode
+\&  /usr/lib c:\ecygwin\elib system binmode
+\&  / c:\ecygwin system binmode
+\&  /cygdrive/c c: system binmode,noumount
+\&  /cygdrive/d d: system binmode,noumount
+\&  /cygdrive/e e: system binmode,noumount
+.Ve
+.ie n .IP """Cygwin::mount_flags""" 4
+.el .IP \f(CWCygwin::mount_flags\fR 4
+.IX Item "Cygwin::mount_flags"
+Returns the mount type and flags for a specified mount point.
+A comma-separated string of mntent\->mnt_type (always
+"system" or "user"), then the mntent\->mnt_opts, where
+the first is always "binmode" or "textmode".
+.Sp
+.Vb 2
+\&  system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
+\&  notexec,managed,nosuid,devfs,proc,noumount
+.Ve
+.Sp
+If the argument is "/cygdrive", then just the volume mount settings,
+and the cygdrive mount prefix are returned.
+.Sp
+User mounts override system mounts.
+.Sp
+.Vb 4
+\&  $ perl \-e \*(Aqprint Cygwin::mount_flags "/usr/bin"\*(Aq
+\&  system,binmode,cygexec
+\&  $ perl \-e \*(Aqprint Cygwin::mount_flags "/cygdrive"\*(Aq
+\&  binmode,cygdrive,/cygdrive
+.Ve
+.ie n .IP """Cygwin::is_binmount""" 4
+.el .IP \f(CWCygwin::is_binmount\fR 4
+.IX Item "Cygwin::is_binmount"
+Returns true if the given cygwin path is binary mounted, false if the
+path is mounted in textmode.
+.ie n .IP """Cygwin::sync_winenv""" 4
+.el .IP \f(CWCygwin::sync_winenv\fR 4
+.IX Item "Cygwin::sync_winenv"
+Cygwin does not initialize all original Win32 environment variables.
+See the bottom of this page <https://cygwin.com/cygwin\-ug\-net/setup\-env.html>
+for "Restricted Win32 environment".
+.Sp
+Certain Win32 programs called from cygwin programs might need some environment
+variable, such as e.g. ADODB needs \f(CW%COMMONPROGRAMFILES\fR%.
+Call \fBCygwin::sync_winenv()\fR to copy all Win32 environment variables to your
+process and note that cygwin will warn on every encounter of non-POSIX paths.
+.SH "INSTALL PERL ON CYGWIN"
+.IX Header "INSTALL PERL ON CYGWIN"
+This will install Perl, including \fIman\fR pages.
+.PP
+.Vb 1
+\&  make install 2>&1 | tee log.make\-install
+.Ve
+.PP
+NOTE: If \f(CW\*(C`STDERR\*(C'\fR is redirected \f(CW\*(C`make install\*(C'\fR will \fBnot\fR prompt
+you to install \fIperl\fR into \fI/usr/bin\fR.
+.PP
+You may need to be \fIAdministrator\fR to run \f(CW\*(C`make install\*(C'\fR.  If you
+are not, you must have write access to the directories in question.
+.PP
+Information on installing the Perl documentation in HTML format can be
+found in the \fIINSTALL\fR document.
+.SH "MANIFEST ON CYGWIN"
+.IX Header "MANIFEST ON CYGWIN"
+These are the files in the Perl release that contain references to Cygwin.
+These very brief notes attempt to explain the reason for all conditional
+code.  Hopefully, keeping this up to date will allow the Cygwin port to
+be kept as clean as possible.
+.IP Documentation 4
+.IX Item "Documentation"
+.Vb 10
+\& INSTALL README.cygwin README.win32 MANIFEST
+\& pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
+\& pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
+\& pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
+\& pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
+\& pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
+\& pod/perltoc.pod Porting/Glossary pod/perlgit.pod
+\& Porting/updateAUTHORS.pl
+\& dist/Cwd/Changes ext/Compress\-Raw\-Zlib/Changes
+\& dist/Time\-HiRes/Changes
+\& ext/Compress\-Raw\-Zlib/README ext/Compress\-Zlib/Changes
+\& ext/DB_File/Changes ext/Encode/Changes ext/Sys\-Syslog/Changes
+\& ext/Win32API\-File/Changes
+\& lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes
+\& lib/ExtUtils/NOTES lib/ExtUtils/PATCHING lib/ExtUtils/README
+\& lib/Net/Ping/Changes lib/Test/Harness/Changes
+\& lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README
+.Ve
+.IP "Build, Configure, Make, Install" 4
+.IX Item "Build, Configure, Make, Install"
+.Vb 10
+\& cygwin/Makefile.SHs
+\& ext/IPC/SysV/hints/cygwin.pl
+\& ext/NDBM_File/hints/cygwin.pl
+\& ext/ODBM_File/hints/cygwin.pl
+\& hints/cygwin.sh
+\& Configure             \- help finding hints from uname,
+\&                         shared libperl required for dynamic loading
+\& Makefile.SH Cross/Makefile\-cross\-SH
+\&                       \- linklibperl
+\& Porting/patchls       \- cygwin in port list
+\& installman            \- man pages with :: translated to .
+\& installperl           \- install dll, install to \*(Aqpods\*(Aq
+\& makedepend.SH         \- uwinfix
+\& regen_lib.pl          \- file permissions
+\&
+\& plan9/mkfile
+\& vms/descrip_mms.template
+\& win32/Makefile
+.Ve
+.IP Tests 4
+.IX Item "Tests"
+.Vb 10
+\& t/io/fs.t             \- no file mode checks if not ntsec
+\&                         skip rename() check when not
+\&                         check_case:relaxed
+\& t/io/tell.t           \- binmode
+\& t/lib/cygwin.t        \- builtin cygwin function tests
+\& t/op/groups.t         \- basegroup has ID = 0
+\& t/op/magic.t          \- $^X/symlink WORKAROUND, s/.exe//
+\& t/op/stat.t           \- no /dev, skip Win32 ftCreationTime quirk
+\&                         (cache manager sometimes preserves ctime of
+\&                         file previously created and deleted), no \-u
+\&                         (setuid)
+\& t/op/taint.t          \- can\*(Aqt use empty path under Cygwin Perl
+\& t/op/time.t           \- no tzset()
+.Ve
+.IP "Compiled Perl Source" 4
+.IX Item "Compiled Perl Source"
+.Vb 10
+\& EXTERN.h              \- _\|_declspec(dllimport)
+\& XSUB.h                \- _\|_declspec(dllexport)
+\& cygwin/cygwin.c       \- os_extras (getcwd, spawn, and several
+\&                         Cygwin:: functions)
+\& perl.c                \- os_extras, \-i.bak
+\& perl.h                \- binmode
+\& doio.c                \- win9x can not rename a file when it is open
+\& pp_sys.c              \- do not define h_errno, init
+\&                         _pwent_struct.pw_comment
+\& util.c                \- use setenv
+\& util.h                \- PERL_FILE_IS_ABSOLUTE macro
+\& pp.c                  \- Comment about Posix vs IEEE math under
+\&                         Cygwin
+\& perlio.c              \- CR/LF mode
+\& perliol.c             \- Comment about EXTCONST under Cygwin
+.Ve
+.IP "Compiled Module Source" 4
+.IX Item "Compiled Module Source"
+.Vb 10
+\& ext/Compress\-Raw\-Zlib/Makefile.PL
+\&                       \- Can\*(Aqt install via CPAN shell under Cygwin
+\& ext/Compress\-Raw\-Zlib/zlib\-src/zutil.h
+\&                       \- Cygwin is Unix\-like and has vsnprintf
+\& ext/Errno/Errno_pm.PL \- Special handling for Win32 Perl under
+\&                         Cygwin
+\& ext/POSIX/POSIX.xs    \- tzname defined externally
+\& ext/SDBM_File/sdbm/pair.c
+\&                       \- EXTCONST needs to be redefined from
+\&                         EXTERN.h
+\& ext/SDBM_File/sdbm/sdbm.c
+\&                       \- binary open
+\& ext/Sys/Syslog/Syslog.xs
+\&                       \- Cygwin has syslog.h
+\& ext/Sys/Syslog/win32/compile.pl
+\&                       \- Convert paths to Windows paths
+\& ext/Time\-HiRes/HiRes.xs
+\&                       \- Various timers not available
+\& ext/Time\-HiRes/Makefile.PL
+\&                       \- Find w32api/windows.h
+\& ext/Win32/Makefile.PL \- Use various libraries under Cygwin
+\& ext/Win32/Win32.xs    \- Child dir and child env under Cygwin
+\& ext/Win32API\-File/File.xs
+\&                       \- _open_osfhandle not implemented under
+\&                         Cygwin
+\& ext/Win32CORE/Win32CORE.c
+\&                       \- _\|_declspec(dllexport)
+.Ve
+.IP "Perl Modules/Scripts" 4
+.IX Item "Perl Modules/Scripts"
+.Vb 10
+\& ext/B/t/OptreeCheck.pm \- Comment about stderr/stdout order under
+\&                          Cygwin
+\& ext/Digest\-SHA/bin/shasum
+\&                       \- Use binary mode under Cygwin
+\& ext/Sys/Syslog/win32/Win32.pm
+\&                       \- Convert paths to Windows paths
+\& ext/Time\-HiRes/HiRes.pm
+\&                       \- Comment about various timers not available
+\& ext/Win32API\-File/File.pm
+\&                       \- _open_osfhandle not implemented under
+\&                         Cygwin
+\& ext/Win32CORE/Win32CORE.pm
+\&                       \- History of Win32CORE under Cygwin
+\& lib/Cwd.pm            \- hook to internal Cwd::cwd
+\& lib/ExtUtils/CBuilder/Platform/cygwin.pm
+\&                       \- use gcc for ld, and link to libperl.dll.a
+\& lib/ExtUtils/CBuilder.pm
+\&                       \- Cygwin is Unix\-like
+\& lib/ExtUtils/Install.pm \- Install and rename issues under Cygwin
+\& lib/ExtUtils/MM.pm    \- OS classifications
+\& lib/ExtUtils/MM_Any.pm \- Example for Cygwin
+\& lib/ExtUtils/MakeMaker.pm
+\&                       \- require MM_Cygwin.pm
+\& lib/ExtUtils/MM_Cygwin.pm
+\&                       \- canonpath, cflags, manifypods, perl_archive
+\& lib/File/Fetch.pm     \- Comment about quotes using a Cygwin example
+\& lib/File/Find.pm      \- on remote drives stat() always sets
+\&                         st_nlink to 1
+\& lib/File/Spec/Cygwin.pm \- case_tolerant
+\& lib/File/Spec/Unix.pm \- preserve //unc
+\& lib/File/Spec/Win32.pm \- References a message on cygwin.com
+\& lib/File/Spec.pm      \- Pulls in lib/File/Spec/Cygwin.pm
+\& lib/File/Temp.pm      \- no directory sticky bit
+\& lib/Module/CoreList.pm \- List of all module files and versions
+\& lib/Net/Domain.pm     \- No domainname command under Cygwin
+\& lib/Net/Netrc.pm      \- Bypass using stat() under Cygwin
+\& lib/Net/Ping.pm       \- ECONREFUSED is EAGAIN under Cygwin
+\& lib/Pod/Find.pm       \- Set \*(Aqpods\*(Aq dir
+\& lib/Pod/Perldoc/ToMan.pm \- \*(Aq\-c\*(Aq switch for pod2man
+\& lib/Pod/Perldoc.pm    \- Use \*(Aqless\*(Aq pager, and use .exe extension
+\& lib/Term/ANSIColor.pm \- Cygwin terminal info
+\& lib/perl5db.pl        \- use stdin not /dev/tty
+\& utils/perlbug.PL      \- Add CYGWIN environment variable to report
+.Ve
+.IP "Perl Module Tests" 4
+.IX Item "Perl Module Tests"
+.Vb 10
+\& dist/Cwd/t/cwd.t
+\& ext/Compress\-Zlib/t/14gzopen.t
+\& ext/DB_File/t/db\-btree.t
+\& ext/DB_File/t/db\-hash.t
+\& ext/DB_File/t/db\-recno.t
+\& ext/DynaLoader/t/DynaLoader.t
+\& ext/File\-Glob/t/basic.t
+\& ext/GDBM_File/t/gdbm.t
+\& ext/POSIX/t/sysconf.t
+\& ext/POSIX/t/time.t
+\& ext/SDBM_File/t/sdbm.t
+\& ext/Sys/Syslog/t/syslog.t
+\& ext/Time\-HiRes/t/HiRes.t
+\& ext/Win32/t/Unicode.t
+\& ext/Win32API\-File/t/file.t
+\& ext/Win32CORE/t/win32core.t
+\& lib/AnyDBM_File.t
+\& lib/Archive/Extract/t/01_Archive\-Extract.t
+\& lib/Archive/Tar/t/02_methods.t
+\& lib/ExtUtils/t/Embed.t
+\& lib/ExtUtils/t/eu_command.t
+\& lib/ExtUtils/t/MM_Cygwin.t
+\& lib/ExtUtils/t/MM_Unix.t
+\& lib/File/Compare.t
+\& lib/File/Copy.t
+\& lib/File/Find/t/find.t
+\& lib/File/Path.t
+\& lib/File/Spec/t/crossplatform.t
+\& lib/File/Spec/t/Spec.t
+\& lib/Net/hostent.t
+\& lib/Net/Ping/t/110_icmp_inst.t
+\& lib/Net/Ping/t/500_ping_icmp.t
+\& lib/Net/t/netrc.t
+\& lib/Pod/Simple/t/perlcyg.pod
+\& lib/Pod/Simple/t/perlcygo.txt
+\& lib/Pod/Simple/t/perlfaq.pod
+\& lib/Pod/Simple/t/perlfaqo.txt
+\& lib/User/grent.t
+\& lib/User/pwent.t
+.Ve
+.SH "BUGS ON CYGWIN"
+.IX Header "BUGS ON CYGWIN"
+Support for swapping real and effective user and group IDs is incomplete.
+On WinNT Cygwin provides \f(CWsetuid()\fR, \f(CWseteuid()\fR, \f(CWsetgid()\fR and \f(CWsetegid()\fR.
+However, additional Cygwin calls for manipulating WinNT access tokens
+and security contexts are required.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Charles Wilson <cwilson@ece.gatech.edu>,
+Eric Fifer <egf7@columbia.edu>,
+alexander smishlajev <als@turnhere.com>,
+Steven Morlock <newspost@morlock.net>,
+Sebastien Barre <Sebastien.Barre@utc.fr>,
+Teun Burgers <burgers@ecn.nl>,
+Gerrit P. Haase <gp@familiehaase.de>,
+Reini Urban <rurban@cpan.org>,
+Jan Dubois <jand@activestate.com>,
+Jerry D. Hedden <jdhedden@cpan.org>.
+.SH HISTORY
+.IX Header "HISTORY"
+Last updated: 2019\-11\-14
diff --git a/upstream/mageia-cauldron/man1/perldata.1 b/upstream/mageia-cauldron/man1/perldata.1
new file mode 100644
index 00000000..ac0b9de6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldata.1
@@ -0,0 +1,1482 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDATA 1"
+.TH PERLDATA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldata \- Perl data types
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Variable names"
+.IX Xref "variable, name variable name data type type"
+.IX Subsection "Variable names"
+Perl has three built-in data types: scalars, arrays of scalars, and
+associative arrays of scalars, known as "hashes".  A scalar is a 
+single string (of any size, limited only by the available memory),
+number, or a reference to something (which will be discussed
+in perlref).  Normal arrays are ordered lists of scalars indexed
+by number, starting with 0.  Hashes are unordered collections of scalar 
+values indexed by their associated string key.
+.PP
+Values are usually referred to by name, or through a named reference.
+The first character of the name tells you to what sort of data
+structure it refers.  The rest of the name tells you the particular
+value to which it refers.  Usually this name is a single \fIidentifier\fR,
+that is, a string beginning with a letter or underscore, and
+containing letters, underscores, and digits.  In some cases, it may
+be a chain of identifiers, separated by \f(CW\*(C`::\*(C'\fR (or by the deprecated \f(CW\*(C`\*(Aq\*(C'\fR);
+all but the last are interpreted as names of packages,
+to locate the namespace in which to look up the final identifier
+(see "Packages" in perlmod for details).  For a more in-depth discussion
+on identifiers, see "Identifier parsing".  It's possible to
+substitute for a simple identifier, an expression that produces a reference
+to the value at runtime.   This is described in more detail below
+and in perlref.
+.IX Xref "identifier"
+.PP
+Perl also has its own built-in variables whose names don't follow
+these rules.  They have strange names so they don't accidentally
+collide with one of your normal variables.  Strings that match
+parenthesized parts of a regular expression are saved under names
+containing only digits after the \f(CW\*(C`$\*(C'\fR (see perlop and perlre).
+In addition, several special variables that provide windows into
+the inner working of Perl have names containing punctuation characters.
+These are documented in perlvar.
+.IX Xref "variable, built-in"
+.PP
+Scalar values are always named with '$', even when referring to a
+scalar that is part of an array or a hash.  The '$' symbol works
+semantically like the English word "the" in that it indicates a
+single value is expected.
+.IX Xref "scalar"
+.PP
+.Vb 4
+\&    $days               # the simple scalar value "days"
+\&    $days[28]           # the 29th element of array @days
+\&    $days{\*(AqFeb\*(Aq}        # the \*(AqFeb\*(Aq value from hash %days
+\&    $#days              # the last index of array @days
+.Ve
+.PP
+Entire arrays (and slices of arrays and hashes) are denoted by '@',
+which works much as the word "these" or "those" does in English,
+in that it indicates multiple values are expected.
+.IX Xref "array"
+.PP
+.Vb 3
+\&    @days               # ($days[0], $days[1],... $days[n])
+\&    @days[3,4,5]        # same as ($days[3],$days[4],$days[5])
+\&    @days{\*(Aqa\*(Aq,\*(Aqc\*(Aq}      # same as ($days{\*(Aqa\*(Aq},$days{\*(Aqc\*(Aq})
+.Ve
+.PP
+Entire hashes are denoted by '%':
+.IX Xref "hash"
+.PP
+.Vb 1
+\&    %days               # (key1, val1, key2, val2 ...)
+.Ve
+.PP
+In addition, subroutines are named with an initial '&', though this
+is optional when unambiguous, just as the word "do" is often redundant
+in English.  Symbol table entries can be named with an initial '*',
+but you don't really care about that yet (if ever :\-).
+.PP
+Every variable type has its own namespace, as do several
+non-variable identifiers.  This means that you can, without fear
+of conflict, use the same name for a scalar variable, an array, or
+a hash\-\-or, for that matter, for a filehandle, a directory handle, a
+subroutine name, a format name, or a label.  This means that \f(CW$foo\fR
+and \f(CW@foo\fR are two different variables.  It also means that \f(CW$foo[1]\fR
+is a part of \f(CW@foo\fR, not a part of \f(CW$foo\fR.  This may seem a bit weird,
+but that's okay, because it is weird.
+.IX Xref "namespace"
+.PP
+Because variable references always start with '$', '@', or '%', the
+"reserved" words aren't in fact reserved with respect to variable
+names.  They \fIare\fR reserved with respect to labels and filehandles,
+however, which don't have an initial special character.  You can't
+have a filehandle named "log", for instance.  Hint: you could say
+\&\f(CW\*(C`open(LOG,\*(Aqlogfile\*(Aq)\*(C'\fR rather than \f(CW\*(C`open(log,\*(Aqlogfile\*(Aq)\*(C'\fR.  Using
+uppercase filehandles also improves readability and protects you
+from conflict with future reserved words.  Case \fIis\fR significant\-\-"FOO",
+"Foo", and "foo" are all different names.  Names that start with a
+letter or underscore may also contain digits and underscores.
+.IX Xref "identifier, case sensitivity case"
+.PP
+It is possible to replace such an alphanumeric name with an expression
+that returns a reference to the appropriate type.  For a description
+of this, see perlref.
+.PP
+Names that start with a digit may contain only more digits.  Names
+that do not start with a letter, underscore, digit or a caret are
+limited to one character, e.g.,  \f(CW$%\fR or
+\&\f(CW$$\fR.  (Most of these one character names have a predefined
+significance to Perl.  For instance, \f(CW$$\fR is the current process
+id.  And all such names are reserved for Perl's possible use.)
+.SS "Identifier parsing"
+.IX Xref "identifiers"
+.IX Subsection "Identifier parsing"
+Up until Perl 5.18, the actual rules of what a valid identifier
+was were a bit fuzzy.  However, in general, anything defined here should
+work on previous versions of Perl, while the opposite \-\- edge cases
+that work in previous versions, but aren't defined here \-\- probably
+won't work on newer versions.
+As an important side note, please note that the following only applies
+to bareword identifiers as found in Perl source code, not identifiers
+introduced through symbolic references, which have much fewer
+restrictions.
+If working under the effect of the \f(CW\*(C`use utf8;\*(C'\fR pragma, the following
+rules apply:
+.PP
+.Vb 2
+\&    / (?[ ( \ep{Word} & \ep{XID_Start} ) + [_] ])
+\&      (?[ ( \ep{Word} & \ep{XID_Continue} ) ]) *    /x
+.Ve
+.PP
+That is, a "start" character followed by any number of "continue"
+characters.  Perl requires every character in an identifier to also
+match \f(CW\*(C`\ew\*(C'\fR (this prevents some problematic cases); and Perl
+additionally accepts identifier names beginning with an underscore.
+.PP
+If not under \f(CW\*(C`use utf8\*(C'\fR, the source is treated as ASCII + 128 extra
+generic characters, and identifiers should match
+.PP
+.Vb 1
+\&    / (?aa) (?!\ed) \ew+ /x
+.Ve
+.PP
+That is, any word character in the ASCII range, as long as the first
+character is not a digit.
+.PP
+There are two package separators in Perl: A double colon (\f(CW\*(C`::\*(C'\fR) and a single
+quote (\f(CW\*(C`\*(Aq\*(C'\fR).  Use of \f(CW\*(C`\*(Aq\*(C'\fR as the package separator is deprecated and will be
+removed in Perl 5.40.  Normal identifiers can start or end with a double
+colon, and can contain several parts delimited by double colons.  Single
+quotes have similar rules, but with the exception that they are not legal at
+the end of an identifier: That is, \f(CW\*(C`$\*(Aqfoo\*(C'\fR and \f(CW\*(C`$foo\*(Aqbar\*(C'\fR are legal, but
+\&\f(CW\*(C`$foo\*(Aqbar\*(Aq\*(C'\fR is not.
+.PP
+Additionally, if the identifier is preceded by a sigil \-\-
+that is, if the identifier is part of a variable name \-\- it
+may optionally be enclosed in braces.
+.PP
+While you can mix double colons with singles quotes, the quotes must come
+after the colons: \f(CW\*(C`$::::\*(Aqfoo\*(C'\fR and \f(CW\*(C`$foo::\*(Aqbar\*(C'\fR are legal, but \f(CW\*(C`$::\*(Aq::foo\*(C'\fR
+and \f(CW\*(C`$foo\*(Aq::bar\*(C'\fR are not.
+.PP
+Put together, a grammar to match a basic identifier becomes
+.PP
+.Vb 10
+\& /
+\&  (?(DEFINE)
+\&      (?<variable>
+\&          (?&sigil)
+\&          (?:
+\&                  (?&normal_identifier)
+\&              |   \e{ \es* (?&normal_identifier) \es* \e}
+\&          )
+\&      )
+\&      (?<normal_identifier>
+\&          (?: :: )* \*(Aq?
+\&           (?&basic_identifier)
+\&           (?: (?= (?: :: )+ \*(Aq? | (?: :: )* \*(Aq ) (?&normal_identifier) )?
+\&          (?: :: )*
+\&      )
+\&      (?<basic_identifier>
+\&        # is use utf8 on?
+\&          (?(?{ (caller(0))[8] & $utf8::hint_bits })
+\&              (?&Perl_XIDS) (?&Perl_XIDC)*
+\&            | (?aa) (?!\ed) \ew+
+\&          )
+\&      )
+\&      (?<sigil> [&*\e$\e@\e%])
+\&      (?<Perl_XIDS> (?[ ( \ep{Word} & \ep{XID_Start} ) + [_] ]) )
+\&      (?<Perl_XIDC> (?[ \ep{Word} & \ep{XID_Continue} ]) )
+\&  )
+\& /x
+.Ve
+.PP
+Meanwhile, special identifiers don't follow the above rules; For the most
+part, all of the identifiers in this category have a special meaning given
+by Perl.  Because they have special parsing rules, these generally can't be
+fully-qualified.  They come in six forms (but don't use forms 5 and 6):
+.IP 1. 4
+A sigil, followed solely by digits matching \f(CW\*(C`\ep{POSIX_Digit}\*(C'\fR, like
+\&\f(CW$0\fR, \f(CW$1\fR, or \f(CW$10000\fR.
+.IP 2. 4
+A sigil followed by a single character matching the \f(CW\*(C`\ep{POSIX_Punct}\*(C'\fR
+property, like \f(CW$!\fR or \f(CW\*(C`%+\*(C'\fR, except the character \f(CW"{"\fR doesn't work.
+.IP 3. 4
+A sigil, followed by a caret and any one of the characters
+\&\f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR, like \f(CW$^V\fR or \f(CW$^]\fR.
+.IP 4. 4
+Similar to the above, a sigil, followed by bareword text in braces,
+where the first character is a caret.  The next character is any one of
+the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR, followed by ASCII word characters.  An
+example is \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR.
+.IP 5. 4
+A sigil, followed by any single character in the range \f(CW\*(C`[\exA1\-\exAC\exAE\-\exFF]\*(C'\fR
+when not under \f(CW"use\ utf8"\fR.  (Under \f(CW"use\ utf8"\fR, the normal
+identifier rules given earlier in this section apply.)  Use of
+non-graphic characters (the C1 controls, the NO-BREAK SPACE, and the
+SOFT HYPHEN) has been disallowed since v5.26.0.
+The use of the other characters is unwise, as these are all
+reserved to have special meaning to Perl, and none of them currently
+do have special meaning, though this could change without notice.
+.Sp
+Note that an implication of this form is that there are identifiers only
+legal under \f(CW"use\ utf8"\fR, and vice-versa, for example the identifier
+\&\f(CW\*(C`$état\*(C'\fR is legal under \f(CW"use\ utf8"\fR, but is otherwise
+considered to be the single character variable \f(CW$é\fR followed by
+the bareword \f(CW"tat"\fR, the combination of which is a syntax error.
+.IP 6. 4
+This is a combination of the previous two forms.  It is valid only when
+not under \f(CW"use\ utf8"\fR (normal identifier rules apply when under
+\&\f(CW"use\ utf8"\fR).  The form is a sigil, followed by text in braces,
+where the first character is any one of the characters in the range
+\&\f(CW\*(C`[\ex80\-\exFF]\*(C'\fR followed by ASCII word characters up to the trailing
+brace.
+.Sp
+The same caveats as the previous form apply:  The non-graphic
+characters are no longer allowed with "use\ utf8", it is unwise
+to use this form at all, and utf8ness makes a big difference.
+.PP
+Prior to Perl v5.24, non-graphical ASCII control characters were also
+allowed in some situations; this had been deprecated since v5.20.
+.SS Context
+.IX Xref "context scalar context list context"
+.IX Subsection "Context"
+The interpretation of operations and values in Perl sometimes depends
+on the requirements of the context around the operation or value.
+There are two major contexts: list and scalar.  Certain operations
+return list values in contexts wanting a list, and scalar values
+otherwise.  If this is true of an operation it will be mentioned in
+the documentation for that operation.  In other words, Perl overloads
+certain operations based on whether the expected return value is
+singular or plural.  Some words in English work this way, like "fish"
+and "sheep".
+.PP
+In a reciprocal fashion, an operation provides either a scalar or a
+list context to each of its arguments.  For example, if you say
+.PP
+.Vb 1
+\&    int( <STDIN> )
+.Ve
+.PP
+the integer operation provides scalar context for the <>
+operator, which responds by reading one line from STDIN and passing it
+back to the integer operation, which will then find the integer value
+of that line and return that.  If, on the other hand, you say
+.PP
+.Vb 1
+\&    sort( <STDIN> )
+.Ve
+.PP
+then the sort operation provides list context for <>, which
+will proceed to read every line available up to the end of file, and
+pass that list of lines back to the sort routine, which will then
+sort those lines and return them as a list to whatever the context
+of the sort was.
+.PP
+Assignment is a little bit special in that it uses its left argument
+to determine the context for the right argument.  Assignment to a
+scalar evaluates the right-hand side in scalar context, while
+assignment to an array or hash evaluates the righthand side in list
+context.  Assignment to a list (or slice, which is just a list
+anyway) also evaluates the right-hand side in list context.
+.PP
+When you use the \f(CW\*(C`use warnings\*(C'\fR pragma or Perl's \fB\-w\fR command-line 
+option, you may see warnings
+about useless uses of constants or functions in "void context".
+Void context just means the value has been discarded, such as a
+statement containing only \f(CW\*(C`"fred";\*(C'\fR or \f(CW\*(C`getpwuid(0);\*(C'\fR.  It still
+counts as scalar context for functions that care whether or not
+they're being called in list context.
+.PP
+User-defined subroutines may choose to care whether they are being
+called in a void, scalar, or list context.  Most subroutines do not
+need to bother, though.  That's because both scalars and lists are
+automatically interpolated into lists.  See "wantarray" in perlfunc
+for how you would dynamically discern your function's calling
+context.
+.SS "Scalar values"
+.IX Xref "scalar number string reference"
+.IX Subsection "Scalar values"
+All data in Perl is a scalar, an array of scalars, or a hash of
+scalars.  A scalar may contain one single value in any of three
+different flavors: a number, a string, or a reference.  In general,
+conversion from one form to another is transparent.  Although a
+scalar may not directly hold multiple values, it may contain a
+reference to an array or hash which in turn contains multiple values.
+.PP
+Scalars aren't necessarily one thing or another.  There's no place
+to declare a scalar variable to be of type "string", type "number",
+type "reference", or anything else.  Because of the automatic
+conversion of scalars, operations that return scalars don't need
+to care (and in fact, cannot care) whether their caller is looking
+for a string, a number, or a reference.  Perl is a contextually
+polymorphic language whose scalars can be strings, numbers, or
+references (which includes objects).  Although strings and numbers
+are considered pretty much the same thing for nearly all purposes,
+references are strongly-typed, uncastable pointers with builtin
+reference-counting and destructor invocation.
+.PP
+       
+ 
+A scalar value is interpreted as FALSE in the Boolean sense
+if it is undefined, the null string or the number 0 (or its
+string equivalent, "0"), and TRUE if it is anything else.  The
+Boolean context is just a special kind of scalar context where no 
+conversion to a string or a number is ever performed.
+Negation of a true value by \f(CW\*(C`!\*(C'\fR or \f(CW\*(C`not\*(C'\fR returns a special false value.
+When evaluated as a string it is treated as \f(CW""\fR, but as a number, it
+is treated as 0.  Most Perl operators
+that return true or false behave this way.
+.IX Xref "truth falsehood true false ! not negation 0 boolean bool"
+.PP
+There are actually two varieties of null strings (sometimes referred
+to as "empty" strings), a defined one and an undefined one.  The
+defined version is just a string of length zero, such as \f(CW""\fR.
+The undefined version is the value that indicates that there is
+no real value for something, such as when there was an error, or
+at end of file, or when you refer to an uninitialized variable or
+element of an array or hash.  Although in early versions of Perl,
+an undefined scalar could become defined when first used in a
+place expecting a defined value, this no longer happens except for
+rare cases of autovivification as explained in perlref.  You can
+use the \fBdefined()\fR operator to determine whether a scalar value is
+defined (this has no meaning on arrays or hashes), and the \fBundef()\fR
+operator to produce an undefined value.
+.IX Xref "defined undefined undef null string, null"
+.PP
+To find out whether a given string is a valid non-zero number, it's
+sometimes enough to test it against both numeric 0 and also lexical
+"0" (although this will cause noises if warnings are on).  That's 
+because strings that aren't numbers count as 0, just as they do in \fBawk\fR:
+.PP
+.Vb 3
+\&    if ($str == 0 && $str ne "0")  {
+\&        warn "That doesn\*(Aqt look like a number";
+\&    }
+.Ve
+.PP
+That method may be best because otherwise you won't treat IEEE
+notations like \f(CW\*(C`NaN\*(C'\fR or \f(CW\*(C`Infinity\*(C'\fR properly.  At other times, you
+might prefer to determine whether string data can be used numerically
+by calling the \fBPOSIX::strtod()\fR function or by inspecting your string
+with a regular expression (as documented in perlre).
+.PP
+.Vb 8
+\&    warn "has nondigits"        if     /\eD/;
+\&    warn "not a natural number" unless /^\ed+$/;             # rejects \-3
+\&    warn "not an integer"       unless /^\-?\ed+$/;           # rejects +3
+\&    warn "not an integer"       unless /^[+\-]?\ed+$/;
+\&    warn "not a decimal number" unless /^\-?\ed+\e.?\ed*$/;     # rejects .2
+\&    warn "not a decimal number" unless /^\-?(?:\ed+(?:\e.\ed*)?|\e.\ed+)$/;
+\&    warn "not a C float"
+\&        unless /^([+\-]?)(?=\ed|\e.\ed)\ed*(\e.\ed*)?([Ee]([+\-]?\ed+))?$/;
+.Ve
+.PP
+The length of an array is a scalar value.  You may find the length
+of array \f(CW@days\fR by evaluating \f(CW$#days\fR, as in \fBcsh\fR.  However, this
+isn't the length of the array; it's the subscript of the last element,
+which is a different value since there is ordinarily a 0th element.
+Assigning to \f(CW$#days\fR actually changes the length of the array.
+Shortening an array this way destroys intervening values.  Lengthening
+an array that was previously shortened does not recover values
+that were in those elements.
+.IX Xref "$# array, length"
+.PP
+You can also gain some minuscule measure of efficiency by pre-extending
+an array that is going to get big.  You can also extend an array
+by assigning to an element that is off the end of the array.  You
+can truncate an array down to nothing by assigning the null list
+() to it.  The following are equivalent:
+.PP
+.Vb 2
+\&    @whatever = ();
+\&    $#whatever = \-1;
+.Ve
+.PP
+If you evaluate an array in scalar context, it returns the length
+of the array.  (Note that this is not true of lists, which return
+the last value, like the C comma operator, nor of built-in functions,
+which return whatever they feel like returning.)  The following is
+always true:
+.IX Xref "array, length"
+.PP
+.Vb 1
+\&    scalar(@whatever) == $#whatever + 1;
+.Ve
+.PP
+Some programmers choose to use an explicit conversion so as to 
+leave nothing to doubt:
+.PP
+.Vb 1
+\&    $element_count = scalar(@whatever);
+.Ve
+.PP
+If you evaluate a hash in scalar context, it returns a false value if
+the hash is empty.  If there are any key/value pairs, it returns a
+true value.  A more precise definition is version dependent.
+.PP
+Prior to Perl 5.25 the value returned was a string consisting of the
+number of used buckets and the number of allocated buckets, separated
+by a slash.  This is pretty much useful only to find out whether
+Perl's internal hashing algorithm is performing poorly on your data
+set.  For example, you stick 10,000 things in a hash, but evaluating
+\&\f(CW%HASH\fR in scalar context reveals \f(CW"1/16"\fR, which means only one out
+of sixteen buckets has been touched, and presumably contains all
+10,000 of your items.  This isn't supposed to happen.
+.PP
+As of Perl 5.25 the return was changed to be the count of keys in the
+hash. If you need access to the old behavior you can use
+\&\f(CWHash::Util::bucket_ratio()\fR instead.
+.PP
+If a tied hash is evaluated in scalar context, the \f(CW\*(C`SCALAR\*(C'\fR method is
+called (with a fallback to \f(CW\*(C`FIRSTKEY\*(C'\fR).
+.IX Xref "hash, scalar context hash, bucket bucket"
+.PP
+You can preallocate space for a hash by assigning to the \fBkeys()\fR function.
+This rounds up the allocated buckets to the next power of two:
+.PP
+.Vb 1
+\&    keys(%users) = 1000;                # allocate 1024 buckets
+.Ve
+.SS "Scalar value constructors"
+.IX Xref "scalar, literal scalar, constant"
+.IX Subsection "Scalar value constructors"
+Numeric literals are specified in any of the following floating point or
+integer formats:
+.PP
+.Vb 11
+\& 12345
+\& 12345.67
+\& .23E\-10             # a very small number
+\& 3.14_15_92          # a very important number
+\& 4_294_967_296       # underscore for legibility
+\& 0xff                # hex
+\& 0xdead_beef         # more hex
+\& 0377                # octal (only numbers, begins with 0)
+\& 0o12_345            # alternative octal (introduced in Perl 5.33.5)
+\& 0b011011            # binary
+\& 0x1.999ap\-4         # hexadecimal floating point (the \*(Aqp\*(Aq is required)
+.Ve
+.PP
+You are allowed to use underscores (underbars) in numeric literals
+between digits for legibility (but not multiple underscores in a row:
+\&\f(CW\*(C`23_\|_500\*(C'\fR is not legal; \f(CW\*(C`23_500\*(C'\fR is).
+You could, for example, group binary
+digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
+or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
+.IX Xref "number, literal"
+.PP
+String literals are usually delimited by either single or double
+quotes.  They work much like quotes in the standard Unix shells:
+double-quoted string literals are subject to backslash and variable
+substitution; single-quoted strings are not (except for \f(CW\*(C`\e\*(Aq\*(C'\fR and
+\&\f(CW\*(C`\e\e\*(C'\fR).  The usual C\-style backslash rules apply for making
+characters such as newline, tab, etc., as well as some more exotic
+forms.  See "Quote and Quote-like Operators" in perlop for a list.
+.IX Xref "string, literal"
+.PP
+Hexadecimal, octal, or binary, representations in string literals
+(e.g. '0xff') are not automatically converted to their integer
+representation.  The \fBhex()\fR and \fBoct()\fR functions make these conversions
+for you.  See "hex" in perlfunc and "oct" in perlfunc for more details.
+.PP
+Hexadecimal floating point can start just like a hexadecimal literal,
+and it can be followed by an optional fractional hexadecimal part,
+but it must be followed by \f(CW\*(C`p\*(C'\fR, an optional sign, and a power of two.
+The format is useful for accurately presenting floating point values,
+avoiding conversions to or from decimal floating point, and therefore
+avoiding possible loss in precision.  Notice that while most current
+platforms use the 64\-bit IEEE 754 floating point, not all do.  Another
+potential source of (low-order) differences are the floating point
+rounding modes, which can differ between CPUs, operating systems,
+and compilers, and which Perl doesn't control.
+.PP
+You can also embed newlines directly in your strings, i.e., they can end
+on a different line than they begin.  This is nice, but if you forget
+your trailing quote, the error will not be reported until Perl finds
+another line containing the quote character, which may be much further
+on in the script.  Variable substitution inside strings is limited to
+scalar variables, arrays, and array or hash slices.  (In other words,
+names beginning with $ or @, followed by an optional bracketed
+expression as a subscript.)  The following code segment prints out "The
+price is \f(CW$100\fR."
+.IX Xref "interpolation"
+.PP
+.Vb 2
+\&    $Price = \*(Aq$100\*(Aq;    # not interpolated
+\&    print "The price is $Price.\en";     # interpolated
+.Ve
+.PP
+There is no double interpolation in Perl, so the \f(CW$100\fR is left as is.
+.PP
+By default floating point numbers substituted inside strings use the
+dot (".")  as the decimal separator.  If \f(CW\*(C`use locale\*(C'\fR is in effect,
+and \fBPOSIX::setlocale()\fR has been called, the character used for the
+decimal separator is affected by the LC_NUMERIC locale.
+See perllocale and POSIX.
+.PP
+\fIDemarcated variable names using braces\fR
+.IX Subsection "Demarcated variable names using braces"
+.PP
+As in some shells, you can enclose the variable name in braces as a
+demarcator to disambiguate it from following alphanumerics and
+underscores or other text. You must also do this when interpolating a
+variable into a string to separate the variable name from a following
+double-colon or an apostrophe since these would be otherwise treated as
+a package separator:
+.IX Xref "interpolation"
+.PP
+.Vb 3
+\&    $who = "Larry";
+\&    print PASSWD "${who}::0:0:Superuser:/:/bin/perl\en";
+\&    print "We use ${who}speak when ${who}\*(Aqs here.\en";
+.Ve
+.PP
+Without the braces, Perl would have looked for a \f(CW$whospeak\fR, a
+\&\f(CW$who::0\fR, and a \f(CW\*(C`$who\*(Aqs\*(C'\fR variable.  The last two would be the
+\&\f(CW$0\fR and the \f(CW$s\fR variables in the (presumably) non-existent package
+\&\f(CW\*(C`who\*(C'\fR.
+.PP
+In fact, a simple identifier within such curly braces is forced to be a
+string, and likewise within a hash subscript. Neither need quoting. Our
+earlier example, \f(CW$days{\*(AqFeb\*(Aq}\fR can be written as \f(CW$days{Feb}\fR and the
+quotes will be assumed automatically. But anything more complicated in
+the subscript will be interpreted as an expression. This means for
+example that \f(CW\*(C`$version{2.0}++\*(C'\fR is equivalent to \f(CW\*(C`$version{2}++\*(C'\fR, not
+to \f(CW\*(C`$version{\*(Aq2.0\*(Aq}++\*(C'\fR.
+.PP
+There is a similar problem with interpolation with text that looks like
+array or hash access notation. Placing a simple variable like \f(CW$who\fR
+immediately in front of text like \f(CW"[1]"\fR or \f(CW"{foo}"\fR would cause the
+variable to be interpolated as accessing an element of \f(CW@who\fR or a
+value stored in \f(CW%who\fR:
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print "$who[1] is the father of Perl.\en";
+.Ve
+.PP
+would attempt to access index 1 of an array named \f(CW@who\fR. Again, using
+braces will prevent this from happening:
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print "${who}[1] is the father of Perl.\en";
+.Ve
+.PP
+will be treated the same as
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print $who . "[1] is the father of Perl.\en";
+.Ve
+.PP
+This notation also applies to more complex variable descriptions,
+such as array or hash access with subscripts. For instance
+.PP
+.Vb 2
+\&    @name = qw(Larry Curly Moe);
+\&    print "Also ${name[0]}[1] was a member\en";
+.Ve
+.PP
+Without the braces the above example would be parsed as a two level
+array subscript in the \f(CW@name\fR array, and under \f(CW\*(C`use strict\*(C'\fR would
+likely produce a fatal exception, as it would be parsed like this:
+.PP
+.Vb 1
+\&    print "Also " . $name[0][1] . " was a member\en";
+.Ve
+.PP
+and not as the intended:
+.PP
+.Vb 1
+\&    print "Also " . $name[0] . "[1] was a member\en";
+.Ve
+.PP
+A similar result may be derived by using a backslash on the first
+character of the subscript or package notation that is not part of
+the variable you want to access. Thus the above example could also
+be written:
+.PP
+.Vb 2
+\&    @name = qw(Larry Curly Moe);
+\&    print "Also $name[0]\e[1] was a member\en";
+.Ve
+.PP
+however for some special variables (multi character caret variables) the
+demarcated form using curly braces is the \fBonly\fR way you can reference
+the variable at all, and the only way you can access a subscript of the
+variable via interpolation.
+.PP
+Consider the magic array \f(CW\*(C`@{^CAPTURE}\*(C'\fR which is populated by the
+regex engine with the contents of all of the capture buffers in a
+pattern (see perlvar and perlre). The \fBonly\fR way you can
+access one of these members inside of a string is via the braced
+(demarcated) form:
+.PP
+.Vb 2
+\&    "abc"=~/(.)(.)(.)/
+\&        and print "Second buffer is ${^CAPTURE[1]}";
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 2
+\&    "abc"=~/(.)(.)(.)/
+\&        and print "Second buffer is " . ${^CAPTURE}[1];
+.Ve
+.PP
+Saying \f(CW\*(C`@^CAPTURE\*(C'\fR is a syntax error, so it \fBmust\fR be referenced as
+\&\f(CW\*(C`@{^CAPTURE}\*(C'\fR, and to access one of its elements in normal code you
+would write \f(CW\*(C` ${^CAPTURE}[1] \*(C'\fR. However when interpolating in a string
+\&\f(CW"${^CAPTURE}[1]"\fR would be equivalent to \f(CW\*(C`${^CAPTURE} . "[1]"\*(C'\fR,
+which does not even refer to the same variable! Thus the subscripts must
+\&\fBalso\fR be placed \fBinside\fR of the braces: \f(CW"${^CAPTURE[1]}"\fR.
+.PP
+The demarcated form using curly braces can be used with all the
+different types of variable access, including array and hash slices. For
+instance code like the following:
+.PP
+.Vb 3
+\&    @name = qw(Larry Curly Moe);
+\&    local $" = " and ";
+\&    print "My favorites were @{name[1,2]}.\en";
+.Ve
+.PP
+would output
+.PP
+.Vb 1
+\&    My favorites were Curly and Moe.
+.Ve
+.PP
+\fISpecial floating point: infinity (Inf) and not-a-number (NaN)\fR
+.IX Subsection "Special floating point: infinity (Inf) and not-a-number (NaN)"
+.PP
+Floating point values include the special values \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR,
+for infinity and not-a-number.  The infinity can be also negative.
+.PP
+The infinity is the result of certain math operations that overflow
+the floating point range, like 9**9**9.  The not-a-number is the
+result when the result is undefined or unrepresentable.  Though note
+that you cannot get \f(CW\*(C`NaN\*(C'\fR from some common "undefined" or
+"out-of-range" operations like dividing by zero, or square root of
+a negative number, since Perl generates fatal errors for those.
+.PP
+The infinity and not-a-number have their own special arithmetic rules.
+The general rule is that they are "contagious": \f(CW\*(C`Inf\*(C'\fR plus one is
+\&\f(CW\*(C`Inf\*(C'\fR, and \f(CW\*(C`NaN\*(C'\fR plus one is \f(CW\*(C`NaN\*(C'\fR.  Where things get interesting
+is when you combine infinities and not-a-numbers: \f(CW\*(C`Inf\*(C'\fR minus \f(CW\*(C`Inf\*(C'\fR
+and \f(CW\*(C`Inf\*(C'\fR divided by \f(CW\*(C`Inf\*(C'\fR are \f(CW\*(C`NaN\*(C'\fR (while \f(CW\*(C`Inf\*(C'\fR plus \f(CW\*(C`Inf\*(C'\fR is
+\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Inf\*(C'\fR times \f(CW\*(C`Inf\*(C'\fR is \f(CW\*(C`Inf\*(C'\fR).  \f(CW\*(C`NaN\*(C'\fR is also curious
+in that it does not equal any number, \fIincluding\fR itself:
+\&\f(CW\*(C`NaN\*(C'\fR != \f(CW\*(C`NaN\*(C'\fR.
+.PP
+Perl doesn't understand \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR as numeric literals, but
+you can have them as strings, and Perl will convert them as needed:
+"Inf" + 1.  (You can, however, import them from the POSIX extension;
+\&\f(CW\*(C`use POSIX qw(Inf NaN);\*(C'\fR and then use them as literals.)
+.PP
+Note that on input (string to number) Perl accepts \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR
+in many forms.   Case is ignored, and the Win32\-specific forms like
+\&\f(CW\*(C`1.#INF\*(C'\fR are understood, but on output the values are normalized to
+\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR.
+.PP
+\fIVersion Strings\fR
+.IX Xref "version string vstring v-string"
+.IX Subsection "Version Strings"
+.PP
+A literal of the form \f(CW\*(C`v1.20.300.4000\*(C'\fR is parsed as a string composed
+of characters with the specified ordinals.  This form, known as
+v\-strings, provides an alternative, more readable way to construct
+strings, rather than use the somewhat less readable interpolation form
+\&\f(CW"\ex{1}\ex{14}\ex{12c}\ex{fa0}"\fR.  This is useful for representing
+Unicode strings, and for comparing version "numbers" using the string
+comparison operators, \f(CW\*(C`cmp\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, \f(CW\*(C`lt\*(C'\fR etc.  If there are two or
+more dots in the literal, the leading \f(CW\*(C`v\*(C'\fR may be omitted.
+.PP
+.Vb 3
+\&    print v9786;              # prints SMILEY, "\ex{263a}"
+\&    print v102.111.111;       # prints "foo"
+\&    print 102.111.111;        # same
+.Ve
+.PP
+Such literals are accepted by both \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`use\*(C'\fR for
+doing a version check.  Note that using the v\-strings for IPv4
+addresses is not portable unless you also use the
+\&\fBinet_aton()\fR/\fBinet_ntoa()\fR routines of the Socket package.
+.PP
+Note that since Perl 5.8.1 the single-number v\-strings (like \f(CW\*(C`v65\*(C'\fR)
+are not v\-strings before the \f(CW\*(C`=>\*(C'\fR operator (which is usually used
+to separate a hash key from a hash value); instead they are interpreted
+as literal strings ('v65').  They were v\-strings from Perl 5.6.0 to
+Perl 5.8.0, but that caused more confusion and breakage than good.
+Multi-number v\-strings like \f(CW\*(C`v65.66\*(C'\fR and \f(CW65.66.67\fR continue to
+be v\-strings always.
+.PP
+\fISpecial Literals\fR
+.IX Xref "special literal __END__ __DATA__ END DATA end data ^D ^Z"
+.IX Subsection "Special Literals"
+.PP
+The special literals _\|_FILE_\|_, _\|_LINE_\|_, and _\|_PACKAGE_\|_
+represent the current filename, line number, and package name at that
+point in your program.  _\|_SUB_\|_ gives a reference to the current
+subroutine.  They may be used only as separate tokens; they
+will not be interpolated into strings.  If there is no current package
+(due to an empty \f(CW\*(C`package;\*(C'\fR directive), _\|_PACKAGE_\|_ is the undefined
+value.  (But the empty \f(CW\*(C`package;\*(C'\fR is no longer supported, as of version
+5.10.)  Outside of a subroutine, _\|_SUB_\|_ is the undefined value.  _\|_SUB_\|_
+is only available in 5.16 or higher, and only with a \f(CW\*(C`use v5.16\*(C'\fR or
+\&\f(CW\*(C`use feature "current_sub"\*(C'\fR declaration.
+.IX Xref "__FILE__ __LINE__ __PACKAGE__ __SUB__ line file package"
+.PP
+The two control characters ^D and ^Z, and the tokens _\|_END_\|_ and _\|_DATA_\|_
+may be used to indicate the logical end of the script before the actual
+end of file.  Any following text is ignored by the interpreter unless
+read by the program as described below.
+.PP
+Text after _\|_DATA_\|_ may be read via the filehandle \f(CW\*(C`PACKNAME::DATA\*(C'\fR,
+where \f(CW\*(C`PACKNAME\*(C'\fR is the package that was current when the _\|_DATA_\|_
+token was encountered.  The filehandle is left open pointing to the
+line after _\|_DATA_\|_.  The program should \f(CW\*(C`close DATA\*(C'\fR when it is done
+reading from it.  (Leaving it open leaks filehandles if the module is
+reloaded for any reason, so it's a safer practice to close it.)  For
+compatibility with older scripts written before _\|_DATA_\|_ was
+introduced, _\|_END_\|_ behaves like _\|_DATA_\|_ in the top level script (but
+not in files loaded with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR) and leaves the remaining
+contents of the file accessible via \f(CW\*(C`main::DATA\*(C'\fR.
+.PP
+.Vb 4
+\&  while (my $line = <DATA>) { print $line; }
+\&  close DATA;
+\&  _\|_DATA_\|_
+\&  Hello world.
+.Ve
+.PP
+The \f(CW\*(C`DATA\*(C'\fR file handle by default has whatever PerlIO layers were
+in place when Perl read the file to parse the source.  Normally that
+means that the file is being read bytewise, as if it were encoded in
+Latin\-1, but there are two major ways for it to be otherwise.  Firstly,
+if the \f(CW\*(C`_\|_END_\|_\*(C'\fR/\f(CW\*(C`_\|_DATA_\|_\*(C'\fR token is in the scope of a \f(CW\*(C`use utf8\*(C'\fR
+pragma then the \f(CW\*(C`DATA\*(C'\fR handle will be in UTF\-8 mode.  And secondly,
+if the source is being read from perl's standard input then the \f(CW\*(C`DATA\*(C'\fR
+file handle is actually aliased to the \f(CW\*(C`STDIN\*(C'\fR file handle, and may
+be in UTF\-8 mode because of the \f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable or
+perl's command-line switches.
+.PP
+See SelfLoader for more description of _\|_DATA_\|_, and
+an example of its use.  Note that you cannot read from the DATA
+filehandle in a BEGIN block: the BEGIN block is executed as soon
+as it is seen (during compilation), at which point the corresponding
+_\|_DATA_\|_ (or _\|_END_\|_) token has not yet been seen.
+.PP
+\fIBarewords\fR
+.IX Xref "bareword"
+.IX Subsection "Barewords"
+.PP
+A word that has no other interpretation in the grammar will
+be treated as if it were a quoted string.  These are known as
+"barewords".  As with filehandles and labels, a bareword that consists
+entirely of lowercase letters risks conflict with future reserved
+words, and if you use the \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR switch, 
+Perl will warn you about any such words.  Perl limits barewords (like
+identifiers) to about 250 characters.  Future versions of Perl are likely
+to eliminate these arbitrary limitations.
+.PP
+Some people may wish to outlaw barewords entirely.  If you
+say
+.PP
+.Vb 1
+\&    use strict \*(Aqsubs\*(Aq;
+.Ve
+.PP
+then any bareword that would NOT be interpreted as a subroutine call
+produces a compile-time error instead.  The restriction lasts to the
+end of the enclosing block.  An inner block may countermand this
+by saying \f(CW\*(C`no strict \*(Aqsubs\*(Aq\*(C'\fR.
+.PP
+\fIArray Interpolation\fR
+.IX Xref "array, interpolation interpolation, array $"""
+.IX Subsection "Array Interpolation"
+.PP
+Arrays and slices are interpolated into double-quoted strings
+by joining the elements with the delimiter specified in the \f(CW$"\fR
+variable (\f(CW$LIST_SEPARATOR\fR if "use English;" is specified), 
+space by default.  The following are equivalent:
+.PP
+.Vb 2
+\&    $temp = join($", @ARGV);
+\&    system "echo $temp";
+\&
+\&    system "echo @ARGV";
+.Ve
+.PP
+Within search patterns (which also undergo double-quotish substitution)
+there is an unfortunate ambiguity:  Is \f(CW\*(C`/$foo[bar]/\*(C'\fR to be interpreted as
+\&\f(CW\*(C`/${foo}[bar]/\*(C'\fR (where \f(CW\*(C`[bar]\*(C'\fR is a character class for the regular
+expression) or as \f(CW\*(C`/${foo[bar]}/\*(C'\fR (where \f(CW\*(C`[bar]\*(C'\fR is the subscript to array
+\&\f(CW@foo\fR)?  If \f(CW@foo\fR doesn't otherwise exist, then it's obviously a
+character class.  If \f(CW@foo\fR exists, Perl takes a good guess about \f(CW\*(C`[bar]\*(C'\fR,
+and is almost always right.  If it does guess wrong, or if you're just
+plain paranoid, you can force the correct interpretation with curly
+braces as above.
+.PP
+If you're looking for the information on how to use here-documents,
+which used to be here, that's been moved to
+"Quote and Quote-like Operators" in perlop.
+.SS "List value constructors"
+.IX Xref "list"
+.IX Subsection "List value constructors"
+List values are denoted by separating individual values by commas
+(and enclosing the list in parentheses where precedence requires it):
+.PP
+.Vb 1
+\&    (LIST)
+.Ve
+.PP
+In a context not requiring a list value, the value of what appears
+to be a list literal is simply the value of the final element, as
+with the C comma operator.  For example,
+.PP
+.Vb 1
+\&    @foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+.Ve
+.PP
+assigns the entire list value to array \f(CW@foo\fR, but
+.PP
+.Vb 1
+\&    $foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+.Ve
+.PP
+assigns the value of variable \f(CW$bar\fR to the scalar variable \f(CW$foo\fR.
+Note that the value of an actual array in scalar context is the
+length of the array; the following assigns the value 3 to \f(CW$foo:\fR
+.PP
+.Vb 2
+\&    @foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+\&    $foo = @foo;                # $foo gets 3
+.Ve
+.PP
+You may have an optional comma before the closing parenthesis of a
+list literal, so that you can say:
+.PP
+.Vb 5
+\&    @foo = (
+\&        1,
+\&        2,
+\&        3,
+\&    );
+.Ve
+.PP
+To use a here-document to assign an array, one line per element,
+you might use an approach like this:
+.PP
+.Vb 7
+\&    @sauces = <<End_Lines =~ m/(\eS.*\eS)/g;
+\&        normal tomato
+\&        spicy tomato
+\&        green chile
+\&        pesto
+\&        white wine
+\&    End_Lines
+.Ve
+.PP
+LISTs do automatic interpolation of sublists.  That is, when a LIST is
+evaluated, each element of the list is evaluated in list context, and
+the resulting list value is interpolated into LIST just as if each
+individual element were a member of LIST.  Thus arrays and hashes lose their
+identity in a LIST\-\-the list
+.PP
+.Vb 1
+\&    (@foo,@bar,&SomeSub,%glarch)
+.Ve
+.PP
+contains all the elements of \f(CW@foo\fR followed by all the elements of \f(CW@bar\fR,
+followed by all the elements returned by the subroutine named SomeSub 
+called in list context, followed by the key/value pairs of \f(CW%glarch\fR.
+To make a list reference that does \fINOT\fR interpolate, see perlref.
+.PP
+The null list is represented by ().  Interpolating it in a list
+has no effect.  Thus ((),(),()) is equivalent to ().  Similarly,
+interpolating an array with no elements is the same as if no
+array had been interpolated at that point.
+.PP
+This interpolation combines with the facts that the opening
+and closing parentheses are optional (except when necessary for
+precedence) and lists may end with an optional comma to mean that
+multiple commas within lists are legal syntax.  The list \f(CW\*(C`1,,3\*(C'\fR is a
+concatenation of two lists, \f(CW\*(C`1,\*(C'\fR and \f(CW3\fR, the first of which ends
+with that optional comma.  \f(CW\*(C`1,,3\*(C'\fR is \f(CW\*(C`(1,),(3)\*(C'\fR is \f(CW\*(C`1,3\*(C'\fR (And
+similarly for \f(CW\*(C`1,,,3\*(C'\fR is \f(CW\*(C`(1,),(,),3\*(C'\fR is \f(CW\*(C`1,3\*(C'\fR and so on.)  Not that
+we'd advise you to use this obfuscation.
+.PP
+A list value may also be subscripted like a normal array.  You must
+put the list in parentheses to avoid ambiguity.  For example:
+.PP
+.Vb 2
+\&    # Stat returns list value.
+\&    $time = (stat($file))[8];
+\&
+\&    # SYNTAX ERROR HERE.
+\&    $time = stat($file)[8];  # OOPS, FORGOT PARENTHESES
+\&
+\&    # Find a hex digit.
+\&    $hexdigit = (\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq,\*(Aqd\*(Aq,\*(Aqe\*(Aq,\*(Aqf\*(Aq)[$digit\-10];
+\&
+\&    # A "reverse comma operator".
+\&    return (pop(@foo),pop(@foo))[0];
+.Ve
+.PP
+Lists may be assigned to only when each element of the list
+is itself legal to assign to:
+.PP
+.Vb 1
+\&    ($x, $y, $z) = (1, 2, 3);
+\&
+\&    ($map{\*(Aqred\*(Aq}, $map{\*(Aqblue\*(Aq}, $map{\*(Aqgreen\*(Aq}) = (0x00f, 0x0f0, 0xf00);
+.Ve
+.PP
+An exception to this is that you may assign to \f(CW\*(C`undef\*(C'\fR in a list.
+This is useful for throwing away some of the return values of a
+function:
+.PP
+.Vb 1
+\&    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+.Ve
+.PP
+As of Perl 5.22, you can also use \f(CW\*(C`(undef)x2\*(C'\fR instead of \f(CW\*(C`undef, undef\*(C'\fR.
+(You can also do \f(CW\*(C`($x) x 2\*(C'\fR, which is less useful, because it assigns to
+the same variable twice, clobbering the first value assigned.)
+.PP
+When you assign a list of scalars to an array, all previous values in that
+array are wiped out and the number of elements in the array will now be equal to
+the number of elements in the right-hand list \-\- the list from which
+assignment was made.  The array will automatically resize itself to precisely
+accommodate each element in the right-hand list.
+.PP
+.Vb 2
+\&    use warnings;
+\&    my (@xyz, $x, $y, $z);
+\&
+\&    @xyz = (1, 2, 3);
+\&    print "@xyz\en";                             # 1 2 3
+\&
+\&    @xyz = (\*(Aqal\*(Aq, \*(Aqbe\*(Aq, \*(Aqga\*(Aq, \*(Aqde\*(Aq);
+\&    print "@xyz\en";                             # al be ga de
+\&
+\&    @xyz = (101, 102);
+\&    print "@xyz\en";                             # 101 102
+.Ve
+.PP
+When, however, you assign a list of scalars to another list of scalars, the
+results differ according to whether the left-hand list \-\- the list being
+assigned to \-\- has the same, more or fewer elements than the right-hand list.
+.PP
+.Vb 2
+\&    ($x, $y, $z) = (1, 2, 3);
+\&    print "$x $y $z\en";                         # 1 2 3
+\&
+\&    ($x, $y, $z) = (\*(Aqal\*(Aq, \*(Aqbe\*(Aq, \*(Aqga\*(Aq, \*(Aqde\*(Aq);
+\&    print "$x $y $z\en";                         # al be ga
+\&
+\&    ($x, $y, $z) = (101, 102);
+\&    print "$x $y $z\en";                         # 101 102
+\&    # Use of uninitialized value $z in concatenation (.)
+\&    # or string at [program] line [line number].
+.Ve
+.PP
+If the number of scalars in the left-hand list is less than that in the
+right-hand list, the "extra" scalars in the right-hand list will simply not be
+assigned.
+.PP
+If the number of scalars in the left-hand list is greater than that in the
+left-hand list, the "missing" scalars will become undefined.
+.PP
+.Vb 6
+\&    ($x, $y, $z) = (101, 102);
+\&    for my $el ($x, $y, $z) {
+\&        (defined $el) ? print "$el " : print "<undef>";
+\&    }
+\&    print "\en";
+\&                                                # 101 102 <undef>
+.Ve
+.PP
+List assignment in scalar context returns the number of elements
+produced by the expression on the right side of the assignment:
+.PP
+.Vb 2
+\&    $x = (($foo,$bar) = (3,2,1));       # set $x to 3, not 2
+\&    $x = (($foo,$bar) = f());           # set $x to f()\*(Aqs return count
+.Ve
+.PP
+This is handy when you want to do a list assignment in a Boolean
+context, because most list functions return a null list when finished,
+which when assigned produces a 0, which is interpreted as FALSE.
+.PP
+It's also the source of a useful idiom for executing a function or
+performing an operation in list context and then counting the number of
+return values, by assigning to an empty list and then using that
+assignment in scalar context.  For example, this code:
+.PP
+.Vb 1
+\&    $count = () = $string =~ /\ed+/g;
+.Ve
+.PP
+will place into \f(CW$count\fR the number of digit groups found in \f(CW$string\fR.
+This happens because the pattern match is in list context (since it
+is being assigned to the empty list), and will therefore return a list
+of all matching parts of the string.  The list assignment in scalar
+context will translate that into the number of elements (here, the
+number of times the pattern matched) and assign that to \f(CW$count\fR.  Note
+that simply using
+.PP
+.Vb 1
+\&    $count = $string =~ /\ed+/g;
+.Ve
+.PP
+would not have worked, since a pattern match in scalar context will
+only return true or false, rather than a count of matches.
+.PP
+The final element of a list assignment may be an array or a hash:
+.PP
+.Vb 2
+\&    ($x, $y, @rest) = split;
+\&    my($x, $y, %rest) = @_;
+.Ve
+.PP
+You can actually put an array or hash anywhere in the list, but the first one
+in the list will soak up all the values, and anything after it will become
+undefined.  This may be useful in a \fBmy()\fR or \fBlocal()\fR.
+.PP
+A hash can be initialized using a literal list holding pairs of
+items to be interpreted as a key and a value:
+.PP
+.Vb 2
+\&    # same as map assignment above
+\&    %map = (\*(Aqred\*(Aq,0x00f,\*(Aqblue\*(Aq,0x0f0,\*(Aqgreen\*(Aq,0xf00);
+.Ve
+.PP
+While literal lists and named arrays are often interchangeable, that's
+not the case for hashes.  Just because you can subscript a list value like
+a normal array does not mean that you can subscript a list value as a
+hash.  Likewise, hashes included as parts of other lists (including
+parameters lists and return lists from functions) always flatten out into
+key/value pairs.  That's why it's good to use references sometimes.
+.PP
+It is often more readable to use the \f(CW\*(C`=>\*(C'\fR operator between key/value
+pairs.  The \f(CW\*(C`=>\*(C'\fR operator is mostly just a more visually distinctive
+synonym for a comma, but it also arranges for its left-hand operand to be
+interpreted as a string if it's a bareword that would be a legal simple
+identifier.  \f(CW\*(C`=>\*(C'\fR doesn't quote compound identifiers, that contain
+double colons.  This makes it nice for initializing hashes:
+.PP
+.Vb 5
+\&    %map = (
+\&                 red   => 0x00f,
+\&                 blue  => 0x0f0,
+\&                 green => 0xf00,
+\&   );
+.Ve
+.PP
+or for initializing hash references to be used as records:
+.PP
+.Vb 5
+\&    $rec = {
+\&                witch => \*(AqMable the Merciless\*(Aq,
+\&                cat   => \*(AqFluffy the Ferocious\*(Aq,
+\&                date  => \*(Aq10/31/1776\*(Aq,
+\&    };
+.Ve
+.PP
+or for using call-by-named-parameter to complicated functions:
+.PP
+.Vb 7
+\&   $field = $query\->radio_group(
+\&               name      => \*(Aqgroup_name\*(Aq,
+\&               values    => [\*(Aqeenie\*(Aq,\*(Aqmeenie\*(Aq,\*(Aqminie\*(Aq],
+\&               default   => \*(Aqmeenie\*(Aq,
+\&               linebreak => \*(Aqtrue\*(Aq,
+\&               labels    => \e%labels
+\&   );
+.Ve
+.PP
+Note that just because a hash is initialized in that order doesn't
+mean that it comes out in that order.  See "sort" in perlfunc for examples
+of how to arrange for an output ordering.
+.PP
+If a key appears more than once in the initializer list of a hash, the last
+occurrence wins:
+.PP
+.Vb 7
+\&    %circle = (
+\&                  center => [5, 10],
+\&                  center => [27, 9],
+\&                  radius => 100,
+\&                  color => [0xDF, 0xFF, 0x00],
+\&                  radius => 54,
+\&    );
+\&
+\&    # same as
+\&    %circle = (
+\&                  center => [27, 9],
+\&                  color => [0xDF, 0xFF, 0x00],
+\&                  radius => 54,
+\&    );
+.Ve
+.PP
+This can be used to provide overridable configuration defaults:
+.PP
+.Vb 2
+\&    # values in %args take priority over %config_defaults
+\&    %config = (%config_defaults, %args);
+.Ve
+.SS Subscripts
+.IX Subsection "Subscripts"
+An array can be accessed one scalar at a
+time by specifying a dollar sign (\f(CW\*(C`$\*(C'\fR), then the
+name of the array (without the leading \f(CW\*(C`@\*(C'\fR), then the subscript inside
+square brackets.  For example:
+.PP
+.Vb 2
+\&    @myarray = (5, 50, 500, 5000);
+\&    print "The Third Element is", $myarray[2], "\en";
+.Ve
+.PP
+The array indices start with 0.  A negative subscript retrieves its 
+value from the end.  In our example, \f(CW$myarray[\-1]\fR would have been 
+5000, and \f(CW$myarray[\-2]\fR would have been 500.
+.PP
+Hash subscripts are similar, only instead of square brackets curly brackets
+are used.  For example:
+.PP
+.Vb 7
+\&    %scientists = 
+\&    (
+\&        "Newton" => "Isaac",
+\&        "Einstein" => "Albert",
+\&        "Darwin" => "Charles",
+\&        "Feynman" => "Richard",
+\&    );
+\&
+\&    print "Darwin\*(Aqs First Name is ", $scientists{"Darwin"}, "\en";
+.Ve
+.PP
+You can also subscript a list to get a single element from it:
+.PP
+.Vb 1
+\&    $dir = (getpwnam("daemon"))[7];
+.Ve
+.SS "Multi-dimensional array emulation"
+.IX Subsection "Multi-dimensional array emulation"
+Multidimensional arrays may be emulated by subscripting a hash with a
+list.  The elements of the list are joined with the subscript separator
+(see "$;" in perlvar).
+.PP
+.Vb 1
+\&    $foo{$x,$y,$z}
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\&    $foo{join($;, $x, $y, $z)}
+.Ve
+.PP
+The default subscript separator is "\e034", the same as SUBSEP in \fBawk\fR.
+.SS Slices
+.IX Xref "slice array, slice hash, slice"
+.IX Subsection "Slices"
+A slice accesses several elements of a list, an array, or a hash
+simultaneously using a list of subscripts.  It's more convenient
+than writing out the individual elements as a list of separate
+scalar values.
+.PP
+.Vb 4
+\&    ($him, $her)   = @folks[0,\-1];              # array slice
+\&    @them          = @folks[0 .. 3];            # array slice
+\&    ($who, $home)  = @ENV{"USER", "HOME"};      # hash slice
+\&    ($uid, $dir)   = (getpwnam("daemon"))[2,7]; # list slice
+.Ve
+.PP
+Since you can assign to a list of variables, you can also assign to
+an array or hash slice.
+.PP
+.Vb 4
+\&    @days[3..5]    = qw/Wed Thu Fri/;
+\&    @colors{\*(Aqred\*(Aq,\*(Aqblue\*(Aq,\*(Aqgreen\*(Aq} 
+\&                   = (0xff0000, 0x0000ff, 0x00ff00);
+\&    @folks[0, \-1]  = @folks[\-1, 0];
+.Ve
+.PP
+The previous assignments are exactly equivalent to
+.PP
+.Vb 4
+\&    ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
+\&    ($colors{\*(Aqred\*(Aq}, $colors{\*(Aqblue\*(Aq}, $colors{\*(Aqgreen\*(Aq})
+\&                   = (0xff0000, 0x0000ff, 0x00ff00);
+\&    ($folks[0], $folks[\-1]) = ($folks[\-1], $folks[0]);
+.Ve
+.PP
+Since changing a slice changes the original array or hash that it's
+slicing, a \f(CW\*(C`foreach\*(C'\fR construct will alter some\-\-or even all\-\-of the
+values of the array or hash.
+.PP
+.Vb 1
+\&    foreach (@array[ 4 .. 10 ]) { s/peter/paul/ } 
+\&
+\&    foreach (@hash{qw[key1 key2]}) {
+\&        s/^\es+//;                       # trim leading whitespace
+\&        s/\es+$//;                       # trim trailing whitespace
+\&        s/\eb(\ew)(\ew*)\eb/\eu$1\eL$2/g;     # "titlecase" words
+\&    }
+.Ve
+.PP
+As a special exception, when you slice a list (but not an array or a hash),
+if the list evaluates to empty, then taking a slice of that empty list will
+always yield the empty list in turn.  Thus:
+.PP
+.Vb 6
+\&    @a = ()[0,1];          # @a has no elements
+\&    @b = (@a)[0,1];        # @b has no elements
+\&    @c = (sub{}\->())[0,1]; # @c has no elements
+\&    @d = (\*(Aqa\*(Aq,\*(Aqb\*(Aq)[0,1];   # @d has two elements
+\&    @e = (@d)[0,1,8,9];    # @e has four elements
+\&    @f = (@d)[8,9];        # @f has two elements
+.Ve
+.PP
+This makes it easy to write loops that terminate when a null list
+is returned:
+.PP
+.Vb 3
+\&    while ( ($home, $user) = (getpwent)[7,0] ) {
+\&        printf "%\-8s %s\en", $user, $home;
+\&    }
+.Ve
+.PP
+As noted earlier in this document, the scalar sense of list assignment
+is the number of elements on the right-hand side of the assignment.
+The null list contains no elements, so when the password file is
+exhausted, the result is 0, not 2.
+.PP
+Slices in scalar context return the last item of the slice.
+.PP
+.Vb 4
+\&    @a = qw/first second third/;
+\&    %h = (first => \*(AqA\*(Aq, second => \*(AqB\*(Aq);
+\&    $t = @a[0, 1];                  # $t is now \*(Aqsecond\*(Aq
+\&    $u = @h{\*(Aqfirst\*(Aq, \*(Aqsecond\*(Aq};     # $u is now \*(AqB\*(Aq
+.Ve
+.PP
+If you're confused about why you use an '@' there on a hash slice
+instead of a '%', think of it like this.  The type of bracket (square
+or curly) governs whether it's an array or a hash being looked at.
+On the other hand, the leading symbol ('$' or '@') on the array or
+hash indicates whether you are getting back a singular value (a
+scalar) or a plural one (a list).
+.PP
+\fIKey/Value Hash Slices\fR
+.IX Subsection "Key/Value Hash Slices"
+.PP
+Starting in Perl 5.20, a hash slice operation
+with the % symbol is a variant of slice operation
+returning a list of key/value pairs rather than just values:
+.PP
+.Vb 6
+\&    %h = (blonk => 2, foo => 3, squink => 5, bar => 8);
+\&    %subset = %h{\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq}; # key/value hash slice
+\&    # %subset is now (foo => 3, bar => 8)
+\&    %removed = delete %h{\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq};
+\&    # %removed is now (foo => 3, bar => 8)
+\&    # %h is now (blonk => 2, squink => 5)
+.Ve
+.PP
+However, the result of such a slice cannot be localized or assigned to.
+These are otherwise very much consistent with hash slices
+using the @ symbol.
+.PP
+\fIIndex/Value Array Slices\fR
+.IX Subsection "Index/Value Array Slices"
+.PP
+Similar to key/value hash slices (and also introduced
+in Perl 5.20), the % array slice syntax returns a list
+of index/value pairs:
+.PP
+.Vb 6
+\&    @a = "a".."z";
+\&    @list = %a[3,4,6];
+\&    # @list is now (3, "d", 4, "e", 6, "g")
+\&    @removed = delete %a[3,4,6]
+\&    # @removed is now (3, "d", 4, "e", 6, "g")
+\&    # @list[3,4,6] are now undef
+.Ve
+.PP
+Note that calling \f(CW\*(C`delete\*(C'\fR on array values is
+strongly discouraged.
+.SS "Typeglobs and Filehandles"
+.IX Xref "typeglob filehandle *"
+.IX Subsection "Typeglobs and Filehandles"
+Perl uses an internal type called a \fItypeglob\fR to hold an entire
+symbol table entry.  The type prefix of a typeglob is a \f(CW\*(C`*\*(C'\fR, because
+it represents all types.  This used to be the preferred way to
+pass arrays and hashes by reference into a function, but now that
+we have real references, this is seldom needed.
+.PP
+The main use of typeglobs in modern Perl is create symbol table aliases.
+This assignment:
+.PP
+.Vb 1
+\&    *this = *that;
+.Ve
+.PP
+makes \f(CW$this\fR an alias for \f(CW$that\fR, \f(CW@this\fR an alias for \f(CW@that\fR, \f(CW%this\fR an alias
+for \f(CW%that\fR, &this an alias for &that, etc.  Much safer is to use a reference.
+This:
+.PP
+.Vb 1
+\&    local *Here::blue = \e$There::green;
+.Ve
+.PP
+temporarily makes \f(CW$Here::blue\fR an alias for \f(CW$There::green\fR, but doesn't
+make \f(CW@Here::blue\fR an alias for \f(CW@There::green\fR, or \f(CW%Here::blue\fR an alias for
+\&\f(CW%There::green\fR, etc.  See "Symbol Tables" in perlmod for more examples
+of this.  Strange though this may seem, this is the basis for the whole
+module import/export system.
+.PP
+Another use for typeglobs is to pass filehandles into a function or
+to create new filehandles.  If you need to use a typeglob to save away
+a filehandle, do it this way:
+.PP
+.Vb 1
+\&    $fh = *STDOUT;
+.Ve
+.PP
+or perhaps as a real reference, like this:
+.PP
+.Vb 1
+\&    $fh = \e*STDOUT;
+.Ve
+.PP
+See perlsub for examples of using these as indirect filehandles
+in functions.
+.PP
+Typeglobs are also a way to create a local filehandle using the \fBlocal()\fR
+operator.  These last until their block is exited, but may be passed back.
+For example:
+.PP
+.Vb 7
+\&    sub newopen {
+\&        my $path = shift;
+\&        local  *FH;  # not my!
+\&        open   (FH, $path)          or  return undef;
+\&        return *FH;
+\&    }
+\&    $fh = newopen(\*(Aq/etc/passwd\*(Aq);
+.Ve
+.PP
+Now that we have the \f(CW*foo{THING}\fR notation, typeglobs aren't used as much
+for filehandle manipulations, although they're still needed to pass brand
+new file and directory handles into or out of functions.  That's because
+\&\f(CW*HANDLE{IO}\fR only works if HANDLE has already been used as a handle.
+In other words, \f(CW*FH\fR must be used to create new symbol table entries;
+\&\f(CW*foo{THING}\fR cannot.  When in doubt, use \f(CW*FH\fR.
+.PP
+All functions that are capable of creating filehandles (\fBopen()\fR,
+\&\fBopendir()\fR, \fBpipe()\fR, \fBsocketpair()\fR, \fBsysopen()\fR, \fBsocket()\fR, and \fBaccept()\fR)
+automatically create an anonymous filehandle if the handle passed to
+them is an uninitialized scalar variable.  This allows the constructs
+such as \f(CW\*(C`open(my $fh, ...)\*(C'\fR and \f(CW\*(C`open(local $fh,...)\*(C'\fR to be used to
+create filehandles that will conveniently be closed automatically when
+the scope ends, provided there are no other references to them.  This
+largely eliminates the need for typeglobs when opening filehandles
+that must be passed around, as in the following example:
+.PP
+.Vb 5
+\&    sub myopen {
+\&        open my $fh, "@_"
+\&             or die "Can\*(Aqt open \*(Aq@_\*(Aq: $!";
+\&        return $fh;
+\&    }
+\&
+\&    {
+\&        my $f = myopen("</etc/motd");
+\&        print <$f>;
+\&        # $f implicitly closed here
+\&    }
+.Ve
+.PP
+Note that if an initialized scalar variable is used instead the
+result is different: \f(CW\*(C`my $fh=\*(Aqzzz\*(Aq; open($fh, ...)\*(C'\fR is equivalent
+to \f(CW\*(C`open( *{\*(Aqzzz\*(Aq}, ...)\*(C'\fR.
+\&\f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR forbids such practice.
+.PP
+Another way to create anonymous filehandles is with the Symbol
+module or with the IO::Handle module and its ilk.  These modules
+have the advantage of not hiding different types of the same name
+during the \fBlocal()\fR.  See the bottom of "open" in perlfunc for an
+example.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See perlvar for a description of Perl's built-in variables and
+a discussion of legal variable names.  See perlref, perlsub,
+and "Symbol Tables" in perlmod for more discussion on typeglobs and
+the \f(CW*foo{THING}\fR syntax.
diff --git a/upstream/mageia-cauldron/man1/perldbmfilter.1 b/upstream/mageia-cauldron/man1/perldbmfilter.1
new file mode 100644
index 00000000..783f0689
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldbmfilter.1
@@ -0,0 +1,219 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDBMFILTER 1"
+.TH PERLDBMFILTER 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldbmfilter \- Perl DBM Filters
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    $db = tie %hash, \*(AqDBM\*(Aq, ...
+\&
+\&    $old_filter = $db\->filter_store_key  ( sub { ... } );
+\&    $old_filter = $db\->filter_store_value( sub { ... } );
+\&    $old_filter = $db\->filter_fetch_key  ( sub { ... } );
+\&    $old_filter = $db\->filter_fetch_value( sub { ... } );
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The four \f(CW\*(C`filter_*\*(C'\fR methods shown above are available in all the DBM
+modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
+ODBM_File and SDBM_File.
+.PP
+Each of the methods works identically, and is used to install (or
+uninstall) a single DBM Filter. The only difference between them is the
+place that the filter is installed.
+.PP
+To summarise:
+.IP \fBfilter_store_key\fR 5
+.IX Item "filter_store_key"
+If a filter has been installed with this method, it will be invoked
+every time you write a key to a DBM database.
+.IP \fBfilter_store_value\fR 5
+.IX Item "filter_store_value"
+If a filter has been installed with this method, it will be invoked
+every time you write a value to a DBM database.
+.IP \fBfilter_fetch_key\fR 5
+.IX Item "filter_fetch_key"
+If a filter has been installed with this method, it will be invoked
+every time you read a key from a DBM database.
+.IP \fBfilter_fetch_value\fR 5
+.IX Item "filter_fetch_value"
+If a filter has been installed with this method, it will be invoked
+every time you read a value from a DBM database.
+.PP
+You can use any combination of the methods from none to all four.
+.PP
+All filter methods return the existing filter, if present, or \f(CW\*(C`undef\*(C'\fR
+if not.
+.PP
+To delete a filter pass \f(CW\*(C`undef\*(C'\fR to it.
+.SS "The Filter"
+.IX Subsection "The Filter"
+When each filter is called by Perl, a local copy of \f(CW$_\fR will contain
+the key or value to be filtered. Filtering is achieved by modifying
+the contents of \f(CW$_\fR. The return code from the filter is ignored.
+.SS "An Example: the NULL termination problem."
+.IX Subsection "An Example: the NULL termination problem."
+DBM Filters are useful for a class of problems where you \fIalways\fR
+want to make the same transformation to all keys, all values or both.
+.PP
+For example, consider the following scenario. You have a DBM database
+that you need to share with a third-party C application. The C application
+assumes that \fIall\fR keys and values are NULL terminated. Unfortunately
+when Perl writes to DBM databases it doesn't use NULL termination, so
+your Perl application will have to manage NULL termination itself. When
+you write to the database you will have to use something like this:
+.PP
+.Vb 1
+\&    $hash{"$key\e0"} = "$value\e0";
+.Ve
+.PP
+Similarly the NULL needs to be taken into account when you are considering
+the length of existing keys/values.
+.PP
+It would be much better if you could ignore the NULL terminations issue
+in the main application code and have a mechanism that automatically
+added the terminating NULL to all keys and values whenever you write to
+the database and have them removed when you read from the database. As I'm
+sure you have already guessed, this is a problem that DBM Filters can
+fix very easily.
+.PP
+.Vb 3
+\&    use v5.36;
+\&    use SDBM_File;
+\&    use Fcntl;
+\&
+\&    my %hash;
+\&    my $filename = "filt";
+\&    unlink $filename;
+\&
+\&    my $db = tie(%hash, \*(AqSDBM_File\*(Aq, $filename, O_RDWR|O_CREAT, 0640)
+\&      or die "Cannot open $filename: $!\en";
+\&
+\&    # Install DBM Filters
+\&    $db\->filter_fetch_key  ( sub { s/\e0$//    } );
+\&    $db\->filter_store_key  ( sub { $_ .= "\e0" } );
+\&    $db\->filter_fetch_value( 
+\&        sub { no warnings \*(Aquninitialized\*(Aq; s/\e0$// } );
+\&    $db\->filter_store_value( sub { $_ .= "\e0" } );
+\&
+\&    $hash{"abc"} = "def";
+\&    my $a = $hash{"ABC"};
+\&    # ...
+\&    undef $db;
+\&    untie %hash;
+.Ve
+.PP
+The code above uses SDBM_File, but it will work with any of the DBM
+modules.
+.PP
+Hopefully the contents of each of the filters should be
+self-explanatory. Both "fetch" filters remove the terminating NULL,
+and both "store" filters add a terminating NULL.
+.SS "Another Example: Key is a C int."
+.IX Subsection "Another Example: Key is a C int."
+Here is another real-life example. By default, whenever Perl writes to
+a DBM database it always writes the key and value as strings. So when
+you use this:
+.PP
+.Vb 1
+\&    $hash{12345} = "something";
+.Ve
+.PP
+the key 12345 will get stored in the DBM database as the 5 byte string
+"12345". If you actually want the key to be stored in the DBM database
+as a C int, you will have to use \f(CW\*(C`pack\*(C'\fR when writing, and \f(CW\*(C`unpack\*(C'\fR
+when reading.
+.PP
+Here is a DBM Filter that does it:
+.PP
+.Vb 5
+\&    use v5.36;
+\&    use DB_File;
+\&    my %hash;
+\&    my $filename = "filt";
+\&    unlink $filename;
+\&
+\&
+\&    my $db = tie %hash, \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666,
+\&        $DB_HASH or die "Cannot open $filename: $!\en";
+\&
+\&    $db\->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
+\&    $db\->filter_store_key  ( sub { $_ = pack ("i", $_) } );
+\&    $hash{123} = "def";
+\&    # ...
+\&    undef $db;
+\&    untie %hash;
+.Ve
+.PP
+The code above uses DB_File, but again it will work with any of the
+DBM modules.
+.PP
+This time only two filters have been used; we only need to manipulate
+the contents of the key, so it wasn't necessary to install any value
+filters.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess
diff --git a/upstream/mageia-cauldron/man1/perldebguts.1 b/upstream/mageia-cauldron/man1/perldebguts.1
new file mode 100644
index 00000000..b4b0878b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldebguts.1
@@ -0,0 +1,1131 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDEBGUTS 1"
+.TH PERLDEBGUTS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldebguts \- Guts of Perl debugging
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is not perldebug, which tells you how to use
+the debugger.  This manpage describes low-level details concerning
+the debugger's internals, which range from difficult to impossible
+to understand for anyone who isn't incredibly intimate with Perl's guts.
+Caveat lector.
+.SH "Debugger Internals"
+.IX Header "Debugger Internals"
+Perl has special debugging hooks at compile-time and run-time used
+to create debugging environments.  These hooks are not to be confused
+with the \fIperl \-Dxxx\fR command described in perlrun,
+which is usable only if a special Perl is built per the instructions in
+the \fIINSTALL\fR file in the Perl source tree.
+.PP
+For example, whenever you call Perl's built-in \f(CW\*(C`caller\*(C'\fR function
+from the package \f(CW\*(C`DB\*(C'\fR, the arguments that the corresponding stack
+frame was called with are copied to the \f(CW@DB::args\fR array.  These
+mechanisms are enabled by calling Perl with the \fB\-d\fR switch.
+Specifically, the following additional features are enabled
+(cf. "$^P" in perlvar):
+.IP \(bu 4
+Perl inserts the contents of \f(CW$ENV{PERL5DB}\fR (or \f(CW\*(C`BEGIN {require
+\&\*(Aqperl5db.pl\*(Aq}\*(C'\fR if not present) before the first line of your program.
+.IP \(bu 4
+Each array \f(CW\*(C`@{"_<$filename"}\*(C'\fR holds the lines of \f(CW$filename\fR for a
+file compiled by Perl.  The same is also true for \f(CW\*(C`eval\*(C'\fRed strings
+that contain subroutines, or which are currently being executed.
+The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed strings looks like \f(CW\*(C`(eval 34)\*(C'\fR.
+.Sp
+Values in this array are magical in numeric context: they compare
+equal to zero only if the line is not breakable.
+.IP \(bu 4
+Each hash \f(CW\*(C`%{"_<$filename"}\*(C'\fR contains breakpoints and actions keyed
+by line number.  Individual entries (as opposed to the whole hash)
+are settable.  Perl only cares about Boolean true here, although
+the values used by \fIperl5db.pl\fR have the form
+\&\f(CW"$break_condition\e0$action"\fR.
+.Sp
+The same holds for evaluated strings that contain subroutines, or
+which are currently being executed.  The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed strings
+looks like \f(CW\*(C`(eval 34)\*(C'\fR.
+.IP \(bu 4
+Each scalar \f(CW\*(C`${"_<$filename"}\*(C'\fR contains \f(CW$filename\fR.  This is
+also the case for evaluated strings that contain subroutines, or
+which are currently being executed.  The \f(CW$filename\fR for \f(CW\*(C`eval\*(C'\fRed
+strings looks like \f(CW\*(C`(eval 34)\*(C'\fR.
+.IP \(bu 4
+After each \f(CW\*(C`require\*(C'\fRd file is compiled, but before it is executed,
+\&\f(CWDB::postponed(*{"_<$filename"})\fR is called if the subroutine
+\&\f(CW\*(C`DB::postponed\*(C'\fR exists.  Here, the \f(CW$filename\fR is the expanded name of
+the \f(CW\*(C`require\*(C'\fRd file, as found in the values of \f(CW%INC\fR.
+.IP \(bu 4
+After each subroutine \f(CW\*(C`subname\*(C'\fR is compiled, the existence of
+\&\f(CW$DB::postponed{subname}\fR is checked.  If this key exists,
+\&\f(CWDB::postponed(subname)\fR is called if the \f(CW\*(C`DB::postponed\*(C'\fR subroutine
+also exists.
+.IP \(bu 4
+A hash \f(CW%DB::sub\fR is maintained, whose keys are subroutine names
+and whose values have the form \f(CW\*(C`filename:startline\-endline\*(C'\fR.
+\&\f(CW\*(C`filename\*(C'\fR has the form \f(CW\*(C`(eval 34)\*(C'\fR for subroutines defined inside
+\&\f(CW\*(C`eval\*(C'\fRs.
+.IP \(bu 4
+When the execution of your program reaches a point that can hold a
+breakpoint, the \f(CWDB::DB()\fR subroutine is called if any of the variables
+\&\f(CW$DB::trace\fR, \f(CW$DB::single\fR, or \f(CW$DB::signal\fR is true.  These variables
+are not \f(CW\*(C`local\*(C'\fRizable.  This feature is disabled when executing
+inside \f(CWDB::DB()\fR, including functions called from it 
+unless \f(CW\*(C`$^D & (1<<30)\*(C'\fR is true.
+.IP \(bu 4
+When execution of the program reaches a subroutine call, a call to
+\&\f(CW&DB::sub\fR(\fIargs\fR) is made instead, with \f(CW$DB::sub\fR set to identify
+the called subroutine.  (This doesn't happen if the calling subroutine
+was compiled in the \f(CW\*(C`DB\*(C'\fR package.)  \f(CW$DB::sub\fR normally holds the name
+of the called subroutine, if it has a name by which it can be looked up.
+Failing that, \f(CW$DB::sub\fR will hold a reference to the called subroutine.
+Either way, the \f(CW&DB::sub\fR subroutine can use \f(CW$DB::sub\fR as a reference
+by which to call the called subroutine, which it will normally want to do.
+.Sp
+If the call is to an lvalue subroutine, and \f(CW&DB::lsub\fR
+is defined \f(CW&DB::lsub\fR(\fIargs\fR) is called instead, otherwise falling
+back to \f(CW&DB::sub\fR(\fIargs\fR).
+.IX Xref "&DB::lsub"
+.IP \(bu 4
+When execution of the program uses \f(CW\*(C`goto\*(C'\fR to enter a non-XS subroutine
+and the 0x80 bit is set in \f(CW$^P\fR, a call to \f(CW&DB::goto\fR is made, with
+\&\f(CW$DB::sub\fR set to identify the subroutine being entered.  The call to
+\&\f(CW&DB::goto\fR does not replace the \f(CW\*(C`goto\*(C'\fR; the requested subroutine will
+still be entered once \f(CW&DB::goto\fR has returned.  \f(CW$DB::sub\fR normally
+holds the name of the subroutine being entered, if it has one.  Failing
+that, \f(CW$DB::sub\fR will hold a reference to the subroutine being entered.
+Unlike when \f(CW&DB::sub\fR is called, it is not guaranteed that \f(CW$DB::sub\fR
+can be used as a reference to operate on the subroutine being entered.
+.PP
+Note that if \f(CW&DB::sub\fR needs external data for it to work, no
+subroutine call is possible without it. As an example, the standard
+debugger's \f(CW&DB::sub\fR depends on the \f(CW$DB::deep\fR variable
+(it defines how many levels of recursion deep into the debugger you can go
+before a mandatory break).  If \f(CW$DB::deep\fR is not defined, subroutine
+calls are not possible, even though \f(CW&DB::sub\fR exists.
+.SS "Writing Your Own Debugger"
+.IX Subsection "Writing Your Own Debugger"
+\fIEnvironment Variables\fR
+.IX Subsection "Environment Variables"
+.PP
+The \f(CW\*(C`PERL5DB\*(C'\fR environment variable can be used to define a debugger.
+For example, the minimal "working" debugger (it actually doesn't do anything)
+consists of one line:
+.PP
+.Vb 1
+\&  sub DB::DB {}
+.Ve
+.PP
+It can easily be defined like this:
+.PP
+.Vb 1
+\&  $ PERL5DB="sub DB::DB {}" perl \-d your\-script
+.Ve
+.PP
+Another brief debugger, slightly more useful, can be created
+with only the line:
+.PP
+.Vb 1
+\&  sub DB::DB {print ++$i; scalar <STDIN>}
+.Ve
+.PP
+This debugger prints a number which increments for each statement
+encountered and waits for you to hit a newline before continuing
+to the next statement.
+.PP
+The following debugger is actually useful:
+.PP
+.Vb 5
+\&  {
+\&    package DB;
+\&    sub DB  {}
+\&    sub sub {print ++$i, " $sub\en"; &$sub}
+\&  }
+.Ve
+.PP
+It prints the sequence number of each subroutine call and the name of the
+called subroutine.  Note that \f(CW&DB::sub\fR is being compiled into the
+package \f(CW\*(C`DB\*(C'\fR through the use of the \f(CW\*(C`package\*(C'\fR directive.
+.PP
+When it starts, the debugger reads your rc file (\fI./.perldb\fR or
+\&\fI~/.perldb\fR under Unix), which can set important options.
+(A subroutine (\f(CW&afterinit\fR) can be defined here as well; it is executed
+after the debugger completes its own initialization.)
+.PP
+After the rc file is read, the debugger reads the PERLDB_OPTS
+environment variable and uses it to set debugger options. The
+contents of this variable are treated as if they were the argument
+of an \f(CW\*(C`o ...\*(C'\fR debugger command (q.v. in "Configurable Options" in perldebug).
+.PP
+\fIDebugger Internal Variables\fR
+.IX Subsection "Debugger Internal Variables"
+.PP
+In addition to the file and subroutine-related variables mentioned above,
+the debugger also maintains various magical internal variables.
+.IP \(bu 4
+\&\f(CW@DB::dbline\fR is an alias for \f(CW\*(C`@{"::_<current_file"}\*(C'\fR, which
+holds the lines of the currently-selected file (compiled by Perl), either
+explicitly chosen with the debugger's \f(CW\*(C`f\*(C'\fR command, or implicitly by flow
+of execution.
+.Sp
+Values in this array are magical in numeric context: they compare
+equal to zero only if the line is not breakable.
+.IP \(bu 4
+\&\f(CW%DB::dbline\fR is an alias for \f(CW\*(C`%{"::_<current_file"}\*(C'\fR, which
+contains breakpoints and actions keyed by line number in
+the currently-selected file, either explicitly chosen with the
+debugger's \f(CW\*(C`f\*(C'\fR command, or implicitly by flow of execution.
+.Sp
+As previously noted, individual entries (as opposed to the whole hash)
+are settable.  Perl only cares about Boolean true here, although
+the values used by \fIperl5db.pl\fR have the form
+\&\f(CW"$break_condition\e0$action"\fR.
+.PP
+\fIDebugger Customization Functions\fR
+.IX Subsection "Debugger Customization Functions"
+.PP
+Some functions are provided to simplify customization.
+.IP \(bu 4
+See "Configurable Options" in perldebug for a description of options parsed by
+\&\f(CWDB::parse_options(string)\fR.
+.IP \(bu 4
+\&\f(CW\*(C`DB::dump_trace(skip[,count])\*(C'\fR skips the specified number of frames
+and returns a list containing information about the calling frames (all
+of them, if \f(CW\*(C`count\*(C'\fR is missing).  Each entry is reference to a hash
+with keys \f(CW\*(C`context\*(C'\fR (either \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`$\*(C'\fR, or \f(CW\*(C`@\*(C'\fR), \f(CW\*(C`sub\*(C'\fR (subroutine
+name, or info about \f(CW\*(C`eval\*(C'\fR), \f(CW\*(C`args\*(C'\fR (\f(CW\*(C`undef\*(C'\fR or a reference to
+an array), \f(CW\*(C`file\*(C'\fR, and \f(CW\*(C`line\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`DB::print_trace(FH, skip[, count[, short]])\*(C'\fR prints
+formatted info about caller frames.  The last two functions may be
+convenient as arguments to \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`<<\*(C'\fR commands.
+.PP
+Note that any variables and functions that are not documented in
+this manpages (or in perldebug) are considered for internal   
+use only, and as such are subject to change without notice.
+.SH "Frame Listing Output Examples"
+.IX Header "Frame Listing Output Examples"
+The \f(CW\*(C`frame\*(C'\fR option can be used to control the output of frame 
+information.  For example, contrast this expression trace:
+.PP
+.Vb 2
+\& $ perl \-de 42
+\& Stack dump during die enabled outside of evals.
+\&
+\& Loading DB routines from perl5db.pl patch level 0.94
+\& Emacs support available.
+\&
+\& Enter h or \*(Aqh h\*(Aq for help.
+\&
+\& main::(\-e:1):   0
+\&   DB<1> sub foo { 14 }
+\&
+\&   DB<2> sub bar { 3 }
+\&
+\&   DB<3> t print foo() * bar()
+\& main::((eval 172):3):   print foo() + bar();
+\& main::foo((eval 168):2):
+\& main::bar((eval 170):2):
+\& 42
+.Ve
+.PP
+with this one, once the \f(CW\*(C`o\*(C'\fRption \f(CW\*(C`frame=2\*(C'\fR has been set:
+.PP
+.Vb 11
+\&   DB<4> o f=2
+\&                frame = \*(Aq2\*(Aq
+\&   DB<5> t print foo() * bar()
+\& 3:      foo() * bar()
+\& entering main::foo
+\&  2:     sub foo { 14 };
+\& exited main::foo
+\& entering main::bar
+\&  2:     sub bar { 3 };
+\& exited main::bar
+\& 42
+.Ve
+.PP
+By way of demonstration, we present below a laborious listing
+resulting from setting your \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable to
+the value \f(CW\*(C`f=n N\*(C'\fR, and running \fIperl \-d \-V\fR from the command line.
+Examples using various values of \f(CW\*(C`n\*(C'\fR are shown to give you a feel
+for the difference between settings.  Long though it may be, this
+is not a complete listing, but only excerpts.
+.IP 1. 4
+.Vb 10
+\& entering main::BEGIN
+\&  entering Config::BEGIN
+\&   Package lib/Exporter.pm.
+\&   Package lib/Carp.pm.
+\&  Package lib/Config.pm.
+\&  entering Config::TIEHASH
+\&  entering Exporter::import
+\&   entering Exporter::export
+\& entering Config::myconfig
+\&  entering Config::FETCH
+\&  entering Config::FETCH
+\&  entering Config::FETCH
+\&  entering Config::FETCH
+.Ve
+.IP 2. 4
+.Vb 10
+\& entering main::BEGIN
+\&  entering Config::BEGIN
+\&   Package lib/Exporter.pm.
+\&   Package lib/Carp.pm.
+\&  exited Config::BEGIN
+\&  Package lib/Config.pm.
+\&  entering Config::TIEHASH
+\&  exited Config::TIEHASH
+\&  entering Exporter::import
+\&   entering Exporter::export
+\&   exited Exporter::export
+\&  exited Exporter::import
+\& exited main::BEGIN
+\& entering Config::myconfig
+\&  entering Config::FETCH
+\&  exited Config::FETCH
+\&  entering Config::FETCH
+\&  exited Config::FETCH
+\&  entering Config::FETCH
+.Ve
+.IP 3. 4
+.Vb 10
+\& in  $=main::BEGIN() from /dev/null:0
+\&  in  $=Config::BEGIN() from lib/Config.pm:2
+\&   Package lib/Exporter.pm.
+\&   Package lib/Carp.pm.
+\&  Package lib/Config.pm.
+\&  in  $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:644
+\&  in  $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\&   in  $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from li
+\& in  @=Config::myconfig() from /dev/null:0
+\&  in  $=Config::FETCH(ref(Config), \*(Aqpackage\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(Aqbaserev\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(AqPERL_VERSION\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(AqPERL_SUBVERSION\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(Aqosname\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(Aqosvers\*(Aq) from lib/Config.pm:574
+.Ve
+.IP 4. 4
+.Vb 10
+\& in  $=main::BEGIN() from /dev/null:0
+\&  in  $=Config::BEGIN() from lib/Config.pm:2
+\&   Package lib/Exporter.pm.
+\&   Package lib/Carp.pm.
+\&  out $=Config::BEGIN() from lib/Config.pm:0
+\&  Package lib/Config.pm.
+\&  in  $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:644
+\&  out $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:644
+\&  in  $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\&   in  $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/
+\&   out $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/
+\&  out $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\& out $=main::BEGIN() from /dev/null:0
+\& in  @=Config::myconfig() from /dev/null:0
+\&  in  $=Config::FETCH(ref(Config), \*(Aqpackage\*(Aq) from lib/Config.pm:574
+\&  out $=Config::FETCH(ref(Config), \*(Aqpackage\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(Aqbaserev\*(Aq) from lib/Config.pm:574
+\&  out $=Config::FETCH(ref(Config), \*(Aqbaserev\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(AqPERL_VERSION\*(Aq) from lib/Config.pm:574
+\&  out $=Config::FETCH(ref(Config), \*(AqPERL_VERSION\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(ref(Config), \*(AqPERL_SUBVERSION\*(Aq) from lib/Config.pm:574
+.Ve
+.IP 5. 4
+.Vb 10
+\& in  $=main::BEGIN() from /dev/null:0
+\&  in  $=Config::BEGIN() from lib/Config.pm:2
+\&   Package lib/Exporter.pm.
+\&   Package lib/Carp.pm.
+\&  out $=Config::BEGIN() from lib/Config.pm:0
+\&  Package lib/Config.pm.
+\&  in  $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:644
+\&  out $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:644
+\&  in  $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\&   in  $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/E
+\&   out $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/E
+\&  out $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\& out $=main::BEGIN() from /dev/null:0
+\& in  @=Config::myconfig() from /dev/null:0
+\&  in  $=Config::FETCH(\*(AqConfig=HASH(0x1aa444)\*(Aq, \*(Aqpackage\*(Aq) from lib/Config.pm:574
+\&  out $=Config::FETCH(\*(AqConfig=HASH(0x1aa444)\*(Aq, \*(Aqpackage\*(Aq) from lib/Config.pm:574
+\&  in  $=Config::FETCH(\*(AqConfig=HASH(0x1aa444)\*(Aq, \*(Aqbaserev\*(Aq) from lib/Config.pm:574
+\&  out $=Config::FETCH(\*(AqConfig=HASH(0x1aa444)\*(Aq, \*(Aqbaserev\*(Aq) from lib/Config.pm:574
+.Ve
+.IP 6. 4
+.Vb 10
+\& in  $=CODE(0x15eca4)() from /dev/null:0
+\&  in  $=CODE(0x182528)() from lib/Config.pm:2
+\&   Package lib/Exporter.pm.
+\&  out $=CODE(0x182528)() from lib/Config.pm:0
+\&  scalar context return from CODE(0x182528): undef
+\&  Package lib/Config.pm.
+\&  in  $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:628
+\&  out $=Config::TIEHASH(\*(AqConfig\*(Aq) from lib/Config.pm:628
+\&  scalar context return from Config::TIEHASH:   empty hash
+\&  in  $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\&   in  $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/Exporter.pm:171
+\&   out $=Exporter::export(\*(AqConfig\*(Aq, \*(Aqmain\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from lib/Exporter.pm:171
+\&   scalar context return from Exporter::export: \*(Aq\*(Aq
+\&  out $=Exporter::import(\*(AqConfig\*(Aq, \*(Aqmyconfig\*(Aq, \*(Aqconfig_vars\*(Aq) from /dev/null:0
+\&  scalar context return from Exporter::import: \*(Aq\*(Aq
+.Ve
+.PP
+In all cases shown above, the line indentation shows the call tree.
+If bit 2 of \f(CW\*(C`frame\*(C'\fR is set, a line is printed on exit from a
+subroutine as well.  If bit 4 is set, the arguments are printed
+along with the caller info.  If bit 8 is set, the arguments are
+printed even if they are tied or references.  If bit 16 is set, the
+return value is printed, too.
+.PP
+When a package is compiled, a line like this
+.PP
+.Vb 1
+\&    Package lib/Carp.pm.
+.Ve
+.PP
+is printed with proper indentation.
+.SH "Debugging Regular Expressions"
+.IX Header "Debugging Regular Expressions"
+There are two ways to enable debugging output for regular expressions.
+.PP
+If your perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, you may use the
+\&\fB\-Dr\fR flag on the command line, and \f(CW\*(C`\-Drv\*(C'\fR for more verbose
+information.
+.PP
+Otherwise, one can \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR, which has effects at both
+compile time and run time.  Since Perl 5.9.5, this pragma is lexically
+scoped.
+.SS "Compile-time Output"
+.IX Subsection "Compile-time Output"
+The debugging output at compile time looks like this:
+.PP
+.Vb 10
+\&  Compiling REx \*(Aq[bc]d(ef*g)+h[ij]k$\*(Aq
+\&  size 45 Got 364 bytes for offset annotations.
+\&  first at 1
+\&  rarest char g at 0
+\&  rarest char d at 0
+\&     1: ANYOF[bc](12)
+\&    12: EXACT <d>(14)
+\&    14: CURLYX[0] {1,32767}(28)
+\&    16:   OPEN1(18)
+\&    18:     EXACT <e>(20)
+\&    20:     STAR(23)
+\&    21:       EXACT <f>(0)
+\&    23:     EXACT <g>(25)
+\&    25:   CLOSE1(27)
+\&    27:   WHILEM[1/1](0)
+\&    28: NOTHING(29)
+\&    29: EXACT <h>(31)
+\&    31: ANYOF[ij](42)
+\&    42: EXACT <k>(44)
+\&    44: EOL(45)
+\&    45: END(0)
+\&  anchored \*(Aqde\*(Aq at 1 floating \*(Aqgh\*(Aq at 3..2147483647 (checking floating) 
+\&        stclass \*(AqANYOF[bc]\*(Aq minlen 7 
+\&  Offsets: [45]
+\&        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
+\&        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
+\&        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
+\&        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]  
+\&  Omitting $\` $& $\*(Aq support.
+.Ve
+.PP
+The first line shows the pre-compiled form of the regex.  The second
+shows the size of the compiled form (in arbitrary units, usually
+4\-byte words) and the total number of bytes allocated for the
+offset/length table, usually 4+\f(CW\*(C`size\*(C'\fR*8.  The next line shows the
+label \fIid\fR of the first node that does a match.
+.PP
+The
+.PP
+.Vb 2
+\&  anchored \*(Aqde\*(Aq at 1 floating \*(Aqgh\*(Aq at 3..2147483647 (checking floating) 
+\&        stclass \*(AqANYOF[bc]\*(Aq minlen 7
+.Ve
+.PP
+line (split into two lines above) contains optimizer
+information.  In the example shown, the optimizer found that the match 
+should contain a substring \f(CW\*(C`de\*(C'\fR at offset 1, plus substring \f(CW\*(C`gh\*(C'\fR
+at some offset between 3 and infinity.  Moreover, when checking for
+these substrings (to abandon impossible matches quickly), Perl will check
+for the substring \f(CW\*(C`gh\*(C'\fR before checking for the substring \f(CW\*(C`de\*(C'\fR.  The
+optimizer may also use the knowledge that the match starts (at the
+\&\f(CW\*(C`first\*(C'\fR \fIid\fR) with a character class, and no string 
+shorter than 7 characters can possibly match.
+.PP
+The fields of interest which may appear in this line are
+.ie n .IP """anchored"" \fISTRING\fR ""at"" \fIPOS\fR" 4
+.el .IP "\f(CWanchored\fR \fISTRING\fR \f(CWat\fR \fIPOS\fR" 4
+.IX Item "anchored STRING at POS"
+.PD 0
+.ie n .IP """floating"" \fISTRING\fR ""at"" \fIPOS1..POS2\fR" 4
+.el .IP "\f(CWfloating\fR \fISTRING\fR \f(CWat\fR \fIPOS1..POS2\fR" 4
+.IX Item "floating STRING at POS1..POS2"
+.PD
+See above.
+.ie n .IP """matching floating/anchored""" 4
+.el .IP "\f(CWmatching floating/anchored\fR" 4
+.IX Item "matching floating/anchored"
+Which substring to check first.
+.ie n .IP """minlen""" 4
+.el .IP \f(CWminlen\fR 4
+.IX Item "minlen"
+The minimal length of the match.
+.ie n .IP """stclass"" \fITYPE\fR" 4
+.el .IP "\f(CWstclass\fR \fITYPE\fR" 4
+.IX Item "stclass TYPE"
+Type of first matching node.
+.ie n .IP """noscan""" 4
+.el .IP \f(CWnoscan\fR 4
+.IX Item "noscan"
+Don't scan for the found substrings.
+.ie n .IP """isall""" 4
+.el .IP \f(CWisall\fR 4
+.IX Item "isall"
+Means that the optimizer information is all that the regular
+expression contains, and thus one does not need to enter the regex engine at
+all.
+.ie n .IP """GPOS""" 4
+.el .IP \f(CWGPOS\fR 4
+.IX Item "GPOS"
+Set if the pattern contains \f(CW\*(C`\eG\*(C'\fR.
+.ie n .IP """plus""" 4
+.el .IP \f(CWplus\fR 4
+.IX Item "plus"
+Set if the pattern starts with a repeated char (as in \f(CW\*(C`x+y\*(C'\fR).
+.ie n .IP """implicit""" 4
+.el .IP \f(CWimplicit\fR 4
+.IX Item "implicit"
+Set if the pattern starts with \f(CW\*(C`.*\*(C'\fR.
+.ie n .IP """with eval""" 4
+.el .IP "\f(CWwith eval\fR" 4
+.IX Item "with eval"
+Set if the pattern contain eval-groups, such as \f(CW\*(C`(?{ code })\*(C'\fR and
+\&\f(CW\*(C`(??{ code })\*(C'\fR.
+.ie n .IP anchored(TYPE) 4
+.el .IP \f(CWanchored(TYPE)\fR 4
+.IX Item "anchored(TYPE)"
+If the pattern may match only at a handful of places, with \f(CW\*(C`TYPE\*(C'\fR
+being \f(CW\*(C`SBOL\*(C'\fR, \f(CW\*(C`MBOL\*(C'\fR, or \f(CW\*(C`GPOS\*(C'\fR.  See the table below.
+.PP
+If a substring is known to match at end-of-line only, it may be
+followed by \f(CW\*(C`$\*(C'\fR, as in \f(CW\*(C`floating \*(Aqk\*(Aq$\*(C'\fR.
+.PP
+The optimizer-specific information is used to avoid entering (a slow) regex
+engine on strings that will not definitely match.  If the \f(CW\*(C`isall\*(C'\fR flag
+is set, a call to the regex engine may be avoided even when the optimizer
+found an appropriate place for the match.
+.PP
+Above the optimizer section is the list of \fInodes\fR of the compiled
+form of the regex.  Each line has format
+.PP
+\&\f(CW\*(C`   \*(C'\fR\fIid\fR: \fITYPE\fR \fIOPTIONAL-INFO\fR (\fInext-id\fR)
+.SS "Types of Nodes"
+.IX Subsection "Types of Nodes"
+Here are the current possible types, with short descriptions:
+.PP
+.Vb 1
+\& # TYPE arg\-description [regnode\-struct\-suffix] [longjump\-len] DESCRIPTION
+\&
+\& # Exit points
+\&
+\& END              no         End of program.
+\& SUCCEED          no         Return from a subroutine, basically.
+\&
+\& # Line Start Anchors:
+\& SBOL             no         Match "" at beginning of line: /^/, /\eA/
+\& MBOL             no         Same, assuming multiline: /^/m
+\&
+\& # Line End Anchors:
+\& SEOL             no         Match "" at end of line: /$/
+\& MEOL             no         Same, assuming multiline: /$/m
+\& EOS              no         Match "" at end of string: /\ez/
+\&
+\& # Match Start Anchors:
+\& GPOS             no         Matches where last m//g left off.
+\&
+\& # Word Boundary Opcodes:
+\& BOUND            no         Like BOUNDA for non\-utf8, otherwise like
+\&                             BOUNDU
+\& BOUNDL           no         Like BOUND/BOUNDU, but \ew and \eW are
+\&                             defined by current locale
+\& BOUNDU           no         Match "" at any boundary of a given type
+\&                             using /u rules.
+\& BOUNDA           no         Match "" at any boundary between \ew\eW or
+\&                             \eW\ew, where \ew is [_a\-zA\-Z0\-9]
+\& NBOUND           no         Like NBOUNDA for non\-utf8, otherwise like
+\&                             BOUNDU
+\& NBOUNDL          no         Like NBOUND/NBOUNDU, but \ew and \eW are
+\&                             defined by current locale
+\& NBOUNDU          no         Match "" at any non\-boundary of a given
+\&                             type using using /u rules.
+\& NBOUNDA          no         Match "" betweeen any \ew\ew or \eW\eW, where
+\&                             \ew is [_a\-zA\-Z0\-9]
+\&
+\& # [Special] alternatives:
+\& REG_ANY          no         Match any one character (except newline).
+\& SANY             no         Match any one character.
+\& ANYOF            sv         Match character in (or not in) this class,
+\&                  charclass  single char match only
+\& ANYOFD           sv         Like ANYOF, but /d is in effect
+\&                  charclass
+\& ANYOFL           sv         Like ANYOF, but /l is in effect
+\&                  charclass
+\& ANYOFPOSIXL      sv         Like ANYOFL, but matches [[:posix:]]
+\&                  charclass_ classes
+\&                  posixl
+\&
+\& ANYOFH           sv 1       Like ANYOF, but only has "High" matches,
+\&                             none in the bitmap; the flags field
+\&                             contains the lowest matchable UTF\-8 start
+\&                             byte
+\& ANYOFHb          sv 1       Like ANYOFH, but all matches share the same
+\&                             UTF\-8 start byte, given in the flags field
+\& ANYOFHr          sv 1       Like ANYOFH, but the flags field contains
+\&                             packed bounds for all matchable UTF\-8 start
+\&                             bytes.
+\& ANYOFHs          sv:str 1   Like ANYOFHb, but has a string field that
+\&                             gives the leading matchable UTF\-8 bytes;
+\&                             flags field is len
+\& ANYOFR           packed 1   Matches any character in the range given by
+\&                             its packed args: upper 12 bits is the max
+\&                             delta from the base lower 20; the flags
+\&                             field contains the lowest matchable UTF\-8
+\&                             start byte
+\& ANYOFRb          packed 1   Like ANYOFR, but all matches share the same
+\&                             UTF\-8 start byte, given in the flags field
+\&
+\& ANYOFHbbm        none bbm   Like ANYOFHb, but only for 2\-byte UTF\-8
+\&                             characters; uses a bitmap to match the
+\&                             continuation byte
+\&
+\& ANYOFM           byte 1     Like ANYOF, but matches an invariant byte
+\&                             as determined by the mask and arg
+\& NANYOFM          byte 1     complement of ANYOFM
+\&
+\& # POSIX Character Classes:
+\& POSIXD           none       Some [[:class:]] under /d; the FLAGS field
+\&                             gives which one
+\& POSIXL           none       Some [[:class:]] under /l; the FLAGS field
+\&                             gives which one
+\& POSIXU           none       Some [[:class:]] under /u; the FLAGS field
+\&                             gives which one
+\& POSIXA           none       Some [[:class:]] under /a; the FLAGS field
+\&                             gives which one
+\& NPOSIXD          none       complement of POSIXD, [[:^class:]]
+\& NPOSIXL          none       complement of POSIXL, [[:^class:]]
+\& NPOSIXU          none       complement of POSIXU, [[:^class:]]
+\& NPOSIXA          none       complement of POSIXA, [[:^class:]]
+\&
+\& CLUMP            no         Match any extended grapheme cluster
+\&                             sequence
+\&
+\& # Alternation
+\&
+\& # BRANCH        The set of branches constituting a single choice are
+\& #               hooked together with their "next" pointers, since
+\& #               precedence prevents anything being concatenated to
+\& #               any individual branch.  The "next" pointer of the last
+\& #               BRANCH in a choice points to the thing following the
+\& #               whole choice.  This is also where the final "next"
+\& #               pointer of each individual branch points; each branch
+\& #               starts with the operand node of a BRANCH node.
+\& #
+\& BRANCH           node 1     Match this alternative, or the next...
+\&
+\& # Literals
+\&
+\& EXACT            str        Match this string (flags field is the
+\&                             length).
+\&
+\& # In a long string node, the U32 argument is the length, and is
+\& # immediately followed by the string.
+\& LEXACT           len:str 1  Match this long string (preceded by length;
+\&                             flags unused).
+\& EXACTL           str        Like EXACT, but /l is in effect (used so
+\&                             locale\-related warnings can be checked for)
+\& EXACTF           str        Like EXACT, but match using /id rules;
+\&                             (string not UTF\-8, ASCII folded; non\-ASCII
+\&                             not)
+\& EXACTFL          str        Like EXACT, but match using /il rules;
+\&                             (string not likely to be folded)
+\& EXACTFU          str        Like EXACT, but match using /iu rules;
+\&                             (string folded)
+\&
+\& EXACTFAA         str        Like EXACT, but match using /iaa rules;
+\&                             (string folded except MICRO in non\-UTF8
+\&                             patterns; doesn\*(Aqt contain SHARP S unless
+\&                             UTF\-8; folded length <= unfolded)
+\& EXACTFAA_NO_TRIE str        Like EXACTFAA, (string not UTF\-8, folded
+\&                             except: MICRO, SHARP S; folded length <=
+\&                             unfolded, not currently trie\-able)
+\&
+\& EXACTFUP         str        Like EXACT, but match using /iu rules;
+\&                             (string not UTF\-8, folded except MICRO:
+\&                             hence Problematic)
+\&
+\& EXACTFLU8        str        Like EXACTFU, but use /il, UTF\-8, (string
+\&                             is folded, and everything in it is above
+\&                             255
+\& EXACT_REQ8       str        Like EXACT, but only UTF\-8 encoded targets
+\&                             can match
+\& LEXACT_REQ8      len:str 1  Like LEXACT, but only UTF\-8 encoded targets
+\&                             can match
+\& EXACTFU_REQ8     str        Like EXACTFU, but only UTF\-8 encoded
+\&                             targets can match
+\&
+\& EXACTFU_S_EDGE   str        /di rules, but nothing in it precludes /ui,
+\&                             except begins and/or ends with [Ss];
+\&                             (string not UTF\-8; compile\-time only)
+\&
+\& # New charclass like patterns
+\& LNBREAK          none       generic newline pattern
+\&
+\& # Trie Related
+\&
+\& # Behave the same as A|LIST|OF|WORDS would. The \*(Aq..C\*(Aq variants
+\& # have inline charclass data (ascii only), the \*(AqC\*(Aq store it in the
+\& # structure.
+\&
+\& TRIE             trie 1     Match many EXACT(F[ALU]?)? at once.
+\&                             flags==type
+\& TRIEC            trie       Same as TRIE, but with embedded charclass
+\&                  charclass  data
+\&
+\& AHOCORASICK      trie 1     Aho Corasick stclass. flags==type
+\& AHOCORASICKC     trie       Same as AHOCORASICK, but with embedded
+\&                  charclass  charclass data
+\&
+\& # Do nothing types
+\&
+\& NOTHING          no         Match empty string.
+\& # A variant of above which delimits a group, thus stops optimizations
+\& TAIL             no         Match empty string. Can jump here from
+\&                             outside.
+\&
+\& # Loops
+\&
+\& # STAR,PLUS    \*(Aq?\*(Aq, and complex \*(Aq*\*(Aq and \*(Aq+\*(Aq, are implemented as
+\& #               circular BRANCH structures.  Simple cases
+\& #               (one character per match) are implemented with STAR
+\& #               and PLUS for speed and to minimize recursive plunges.
+\& #
+\& STAR             node       Match this (simple) thing 0 or more times:
+\&                             /A{0,}B/ where A is width 1 char
+\& PLUS             node       Match this (simple) thing 1 or more times:
+\&                             /A{1,}B/ where A is width 1 char
+\&
+\& CURLY            sv 3       Match this (simple) thing {n,m} times:
+\&                             /A{m,n}B/ where A is width 1 char
+\& CURLYN           no 3       Capture next\-after\-this simple thing:
+\&                             /(A){m,n}B/ where A is width 1 char
+\& CURLYM           no 3       Capture this medium\-complex thing {n,m}
+\&                             times: /(A){m,n}B/ where A is fixed\-length
+\& CURLYX           sv 3       Match/Capture this complex thing {n,m}
+\&                             times.
+\&
+\& # This terminator creates a loop structure for CURLYX
+\& WHILEM           no         Do curly processing and see if rest
+\&                             matches.
+\&
+\& # Buffer related
+\&
+\& # OPEN,CLOSE,GROUPP     ...are numbered at compile time.
+\& OPEN             num 1      Mark this point in input as start of #n.
+\& CLOSE            num 1      Close corresponding OPEN of #n.
+\& SROPEN           none       Same as OPEN, but for script run
+\& SRCLOSE          none       Close preceding SROPEN
+\&
+\& REF              num 2      Match some already matched string
+\& REFF             num 2      Match already matched string, using /di
+\&                             rules.
+\& REFFL            num 2      Match already matched string, using /li
+\&                             rules.
+\& REFFU            num 2      Match already matched string, usng /ui.
+\& REFFA            num 2      Match already matched string, using /aai
+\&                             rules.
+\&
+\& # Named references.  Code in regcomp.c assumes that these all are after
+\& # the numbered references
+\& REFN             no\-sv 2    Match some already matched string
+\& REFFN            no\-sv 2    Match already matched string, using /di
+\&                             rules.
+\& REFFLN           no\-sv 2    Match already matched string, using /li
+\&                             rules.
+\& REFFUN           num 2      Match already matched string, using /ui
+\&                             rules.
+\& REFFAN           num 2      Match already matched string, using /aai
+\&                             rules.
+\&
+\& # Support for long RE
+\& LONGJMP          off 1 1    Jump far away.
+\& BRANCHJ          off 2 1    BRANCH with long offset.
+\&
+\& # Special Case Regops
+\& IFMATCH          off 1 1    Succeeds if the following matches; non\-zero
+\&                             flags "f", next_off "o" means lookbehind
+\&                             assertion starting "f..(f\-o)" characters
+\&                             before current
+\& UNLESSM          off 1 1    Fails if the following matches; non\-zero
+\&                             flags "f", next_off "o" means lookbehind
+\&                             assertion starting "f..(f\-o)" characters
+\&                             before current
+\& SUSPEND          off 1 1    "Independent" sub\-RE.
+\& IFTHEN           off 1 1    Switch, should be preceded by switcher.
+\& GROUPP           num 1      Whether the group matched.
+\&
+\& # The heavy worker
+\&
+\& EVAL             evl/flags  Execute some Perl code.
+\&                  2
+\&
+\& # Modifiers
+\&
+\& MINMOD           no         Next operator is not greedy.
+\& LOGICAL          no         Next opcode should set the flag only.
+\&
+\& # This is not used yet
+\& RENUM            off 1 1    Group with independently numbered parens.
+\&
+\& # Regex Subroutines
+\& GOSUB            num/ofs 2  recurse to paren arg1 at (signed) ofs arg2
+\&
+\& # Special conditionals
+\& GROUPPN          no\-sv 1    Whether the group matched.
+\& INSUBP           num 1      Whether we are in a specific recurse.
+\& DEFINEP          none 1     Never execute directly.
+\&
+\& # Backtracking Verbs
+\& ENDLIKE          none       Used only for the type field of verbs
+\& OPFAIL           no\-sv 1    Same as (?!), but with verb arg
+\& ACCEPT           no\-sv/num  Accepts the current matched string, with
+\&                  2          verbar
+\&
+\& # Verbs With Arguments
+\& VERB             no\-sv 1    Used only for the type field of verbs
+\& PRUNE            no\-sv 1    Pattern fails at this startpoint if no\-
+\&                             backtracking through this
+\& MARKPOINT        no\-sv 1    Push the current location for rollback by
+\&                             cut.
+\& SKIP             no\-sv 1    On failure skip forward (to the mark)
+\&                             before retrying
+\& COMMIT           no\-sv 1    Pattern fails outright if backtracking
+\&                             through this
+\& CUTGROUP         no\-sv 1    On failure go to the next alternation in
+\&                             the group
+\&
+\& # Control what to keep in $&.
+\& KEEPS            no         $& begins here.
+\&
+\& # Validate that lookbehind IFMATCH and UNLESSM end at the right place
+\& LOOKBEHIND_END   no         Return from lookbehind (IFMATCH/UNLESSM)
+\&                             and validate position
+\&
+\& # SPECIAL  REGOPS
+\&
+\& # This is not really a node, but an optimized away piece of a "long"
+\& # node.  To simplify debugging output, we mark it as if it were a node
+\& OPTIMIZED        off        Placeholder for dump.
+\&
+\& # Special opcode with the property that no opcode in a compiled program
+\& # will ever be of this type. Thus it can be used as a flag value that
+\& # no other opcode has been seen. END is used similarly, in that an END
+\& # node cant be optimized. So END implies "unoptimizable" and PSEUDO
+\& # mean "not seen anything to optimize yet".
+\& PSEUDO           off        Pseudo opcode for internal use.
+\&
+\& REGEX_SET        depth p    Regex set, temporary node used in pre\-
+\&                             optimization compilation
+.Ve
+.PP
+Following the optimizer information is a dump of the offset/length
+table, here split across several lines:
+.PP
+.Vb 5
+\&  Offsets: [45]
+\&        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
+\&        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
+\&        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
+\&        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
+.Ve
+.PP
+The first line here indicates that the offset/length table contains 45
+entries.  Each entry is a pair of integers, denoted by \f(CW\*(C`offset[length]\*(C'\fR.
+Entries are numbered starting with 1, so entry #1 here is \f(CW\*(C`1[4]\*(C'\fR and
+entry #12 is \f(CW\*(C`5[1]\*(C'\fR.  \f(CW\*(C`1[4]\*(C'\fR indicates that the node labeled \f(CW\*(C`1:\*(C'\fR
+(the \f(CW\*(C`1: ANYOF[bc]\*(C'\fR) begins at character position 1 in the
+pre-compiled form of the regex, and has a length of 4 characters.
+\&\f(CW\*(C`5[1]\*(C'\fR in position 12 
+indicates that the node labeled \f(CW\*(C`12:\*(C'\fR
+(the \f(CW\*(C`12: EXACT <d>\*(C'\fR) begins at character position 5 in the
+pre-compiled form of the regex, and has a length of 1 character.
+\&\f(CW\*(C`12[1]\*(C'\fR in position 14 
+indicates that the node labeled \f(CW\*(C`14:\*(C'\fR
+(the \f(CW\*(C`14: CURLYX[0] {1,32767}\*(C'\fR) begins at character position 12 in the
+pre-compiled form of the regex, and has a length of 1 character\-\-\-that
+is, it corresponds to the \f(CW\*(C`+\*(C'\fR symbol in the precompiled regex.
+.PP
+\&\f(CW\*(C`0[0]\*(C'\fR items indicate that there is no corresponding node.
+.SS "Run-time Output"
+.IX Subsection "Run-time Output"
+First of all, when doing a match, one may get no run-time output even
+if debugging is enabled.  This means that the regex engine was never
+entered and that all of the job was therefore done by the optimizer.
+.PP
+If the regex engine was entered, the output may look like this:
+.PP
+.Vb 10
+\&  Matching \*(Aq[bc]d(ef*g)+h[ij]k$\*(Aq against \*(Aqabcdefg_\|_gh_\|_\*(Aq
+\&    Setting an EVAL scope, savestack=3
+\&     2 <ab> <cdefg_\|_gh_>    |  1: ANYOF
+\&     3 <abc> <defg_\|_gh_>    | 11: EXACT <d>
+\&     4 <abcd> <efg_\|_gh_>    | 13: CURLYX {1,32767}
+\&     4 <abcd> <efg_\|_gh_>    | 26:   WHILEM
+\&                                0 out of 1..32767  cc=effff31c
+\&     4 <abcd> <efg_\|_gh_>    | 15:     OPEN1
+\&     4 <abcd> <efg_\|_gh_>    | 17:     EXACT <e>
+\&     5 <abcde> <fg_\|_gh_>    | 19:     STAR
+\&                             EXACT <f> can match 1 times out of 32767...
+\&    Setting an EVAL scope, savestack=3
+\&     6 <bcdef> <g_\|_gh_\|_>    | 22:       EXACT <g>
+\&     7 <bcdefg> <_\|_gh_\|_>    | 24:       CLOSE1
+\&     7 <bcdefg> <_\|_gh_\|_>    | 26:       WHILEM
+\&                                    1 out of 1..32767  cc=effff31c
+\&    Setting an EVAL scope, savestack=12
+\&     7 <bcdefg> <_\|_gh_\|_>    | 15:         OPEN1
+\&     7 <bcdefg> <_\|_gh_\|_>    | 17:         EXACT <e>
+\&       restoring \e1 to 4(4)..7
+\&                                    failed, try continuation...
+\&     7 <bcdefg> <_\|_gh_\|_>    | 27:         NOTHING
+\&     7 <bcdefg> <_\|_gh_\|_>    | 28:         EXACT <h>
+\&                                    failed...
+\&                                failed...
+.Ve
+.PP
+The most significant information in the output is about the particular \fInode\fR
+of the compiled regex that is currently being tested against the target string.
+The format of these lines is
+.PP
+\&\f(CW\*(C`    \*(C'\fR\fISTRING-OFFSET\fR <\fIPRE-STRING\fR> <\fIPOST-STRING\fR>   |\fIID\fR:  \fITYPE\fR
+.PP
+The \fITYPE\fR info is indented with respect to the backtracking level.
+Other incidental information appears interspersed within.
+.SH "Debugging Perl Memory Usage"
+.IX Header "Debugging Perl Memory Usage"
+Perl is a profligate wastrel when it comes to memory use.  There
+is a saying that to estimate memory usage of Perl, assume a reasonable
+algorithm for memory allocation, multiply that estimate by 10, and
+while you still may miss the mark, at least you won't be quite so
+astonished.  This is not absolutely true, but may provide a good
+grasp of what happens.
+.PP
+Assume that an integer cannot take less than 20 bytes of memory, a
+float cannot take less than 24 bytes, a string cannot take less
+than 32 bytes (all these examples assume 32\-bit architectures, the
+result are quite a bit worse on 64\-bit architectures).  If a variable
+is accessed in two of three different ways (which require an integer,
+a float, or a string), the memory footprint may increase yet another
+20 bytes.  A sloppy \fBmalloc\fR\|(3) implementation can inflate these
+numbers dramatically.
+.PP
+On the opposite end of the scale, a declaration like
+.PP
+.Vb 1
+\&  sub foo;
+.Ve
+.PP
+may take up to 500 bytes of memory, depending on which release of Perl
+you're running.
+.PP
+Anecdotal estimates of source-to-compiled code bloat suggest an
+eightfold increase.  This means that the compiled form of reasonable
+(normally commented, properly indented etc.) code will take
+about eight times more space in memory than the code took
+on disk.
+.PP
+The \fB\-DL\fR command-line switch is obsolete since circa Perl 5.6.0
+(it was available only if Perl was built with \f(CW\*(C`\-DDEBUGGING\*(C'\fR).
+The switch was used to track Perl's memory allocations and possible
+memory leaks.  These days the use of malloc debugging tools like
+\&\fIPurify\fR or \fIvalgrind\fR is suggested instead.  See also
+"PERL_MEM_LOG" in perlhacktips.
+.PP
+One way to find out how much memory is being used by Perl data
+structures is to install the Devel::Size module from CPAN: it gives
+you the minimum number of bytes required to store a particular data
+structure.  Please be mindful of the difference between the \fBsize()\fR
+and \fBtotal_size()\fR.
+.PP
+If Perl has been compiled using Perl's malloc you can analyze Perl
+memory usage by setting \f(CW$ENV\fR{PERL_DEBUG_MSTATS}.
+.ie n .SS "Using $ENV{PERL_DEBUG_MSTATS}"
+.el .SS "Using \f(CW$ENV{PERL_DEBUG_MSTATS}\fP"
+.IX Subsection "Using $ENV{PERL_DEBUG_MSTATS}"
+If your perl is using Perl's \fBmalloc()\fR and was compiled with the
+necessary switches (this is the default), then it will print memory
+usage statistics after compiling your code when \f(CW\*(C`$ENV{PERL_DEBUG_MSTATS}
+> 1\*(C'\fR, and before termination of the program when \f(CW\*(C`$ENV{PERL_DEBUG_MSTATS} >= 1\*(C'\fR.  The report format is similar to
+the following example:
+.PP
+.Vb 10
+\& $ PERL_DEBUG_MSTATS=2 perl \-e "require Carp"
+\& Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
+\&    14216 free:   130   117    28     7     9   0   2     2   1 0 0
+\&                437    61    36     0     5
+\&    60924 used:   125   137   161    55     7   8   6    16   2 0 1
+\&                 74   109   304    84    20
+\& Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
+\& Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
+\&    30888 free:   245    78    85    13     6   2   1     3   2 0 1
+\&                315   162    39    42    11
+\&   175816 used:   265   176  1112   111    26  22  11    27   2 1 1
+\&                196   178  1066   798    39
+\& Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
+.Ve
+.PP
+It is possible to ask for such a statistic at arbitrary points in
+your execution using the \fBmstat()\fR function out of the standard
+Devel::Peek module.
+.PP
+Here is some explanation of that format:
+.ie n .IP """buckets SMALLEST(APPROX)..GREATEST(APPROX)""" 4
+.el .IP "\f(CWbuckets SMALLEST(APPROX)..GREATEST(APPROX)\fR" 4
+.IX Item "buckets SMALLEST(APPROX)..GREATEST(APPROX)"
+Perl's \fBmalloc()\fR uses bucketed allocations.  Every request is rounded
+up to the closest bucket size available, and a bucket is taken from
+the pool of buckets of that size.
+.Sp
+The line above describes the limits of buckets currently in use.
+Each bucket has two sizes: memory footprint and the maximal size
+of user data that can fit into this bucket.  Suppose in the above
+example that the smallest bucket were size 4.  The biggest bucket
+would have usable size 8188, and the memory footprint would be 8192.
+.Sp
+In a Perl built for debugging, some buckets may have negative usable
+size.  This means that these buckets cannot (and will not) be used.
+For larger buckets, the memory footprint may be one page greater
+than a power of 2.  If so, the corresponding power of two is
+printed in the \f(CW\*(C`APPROX\*(C'\fR field above.
+.IP Free/Used 4
+.IX Item "Free/Used"
+The 1 or 2 rows of numbers following that correspond to the number
+of buckets of each size between \f(CW\*(C`SMALLEST\*(C'\fR and \f(CW\*(C`GREATEST\*(C'\fR.  In
+the first row, the sizes (memory footprints) of buckets are powers
+of two\-\-or possibly one page greater.  In the second row, if present,
+the memory footprints of the buckets are between the memory footprints
+of two buckets "above".
+.Sp
+For example, suppose under the previous example, the memory footprints
+were
+.Sp
+.Vb 2
+\&   free:    8     16    32    64    128  256 512 1024 2048 4096 8192
+\&           4     12    24    48    80
+.Ve
+.Sp
+With a non\-\f(CW\*(C`DEBUGGING\*(C'\fR perl, the buckets starting from \f(CW128\fR have
+a 4\-byte overhead, and thus an 8192\-long bucket may take up to
+8188\-byte allocations.
+.ie n .IP """Total sbrk(): SBRKed/SBRKs:CONTINUOUS""" 4
+.el .IP "\f(CWTotal sbrk(): SBRKed/SBRKs:CONTINUOUS\fR" 4
+.IX Item "Total sbrk(): SBRKed/SBRKs:CONTINUOUS"
+The first two fields give the total amount of memory perl \fBsbrk\fR\|(2)ed
+(ess-broken? :\-) and number of \fBsbrk\fR\|(2)s used.  The third number is
+what perl thinks about continuity of returned chunks.  So long as
+this number is positive, \fBmalloc()\fR will assume that it is probable
+that \fBsbrk\fR\|(2) will provide continuous memory.
+.Sp
+Memory allocated by external libraries is not counted.
+.ie n .IP """pad: 0""" 4
+.el .IP "\f(CWpad: 0\fR" 4
+.IX Item "pad: 0"
+The amount of \fBsbrk\fR\|(2)ed memory needed to keep buckets aligned.
+.ie n .IP """heads: 2192""" 4
+.el .IP "\f(CWheads: 2192\fR" 4
+.IX Item "heads: 2192"
+Although memory overhead of bigger buckets is kept inside the bucket, for
+smaller buckets, it is kept in separate areas.  This field gives the
+total size of these areas.
+.ie n .IP """chain: 0""" 4
+.el .IP "\f(CWchain: 0\fR" 4
+.IX Item "chain: 0"
+\&\fBmalloc()\fR may want to subdivide a bigger bucket into smaller buckets.
+If only a part of the deceased bucket is left unsubdivided, the rest
+is kept as an element of a linked list.  This field gives the total
+size of these chunks.
+.ie n .IP """tail: 6144""" 4
+.el .IP "\f(CWtail: 6144\fR" 4
+.IX Item "tail: 6144"
+To minimize the number of \fBsbrk\fR\|(2)s, \fBmalloc()\fR asks for more memory.  This
+field gives the size of the yet unused part, which is \fBsbrk\fR\|(2)ed, but
+never touched.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perldebug,
+perl5db.pl,
+perlguts,
+perlrun,
+re,
+and
+Devel::DProf.
diff --git a/upstream/mageia-cauldron/man1/perldebtut.1 b/upstream/mageia-cauldron/man1/perldebtut.1
new file mode 100644
index 00000000..3b8ed54b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldebtut.1
@@ -0,0 +1,871 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDEBTUT 1"
+.TH PERLDEBTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldebtut \- Perl debugging tutorial
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A (very) lightweight introduction in the use of the perl debugger, and a
+pointer to existing, deeper sources of information on the subject of debugging
+perl programs.
+.PP
+There's an extraordinary number of people out there who don't appear to know
+anything about using the perl debugger, though they use the language every
+day.  
+This is for them.
+.SH "use strict"
+.IX Header "use strict"
+First of all, there's a few things you can do to make your life a lot more
+straightforward when it comes to debugging perl programs, without using the
+debugger at all.  To demonstrate, here's a simple script, named "hello", with
+a problem:
+.PP
+.Vb 1
+\&        #!/usr/bin/perl
+\&
+\&        $var1 = \*(AqHello World\*(Aq; # always wanted to do that :\-)
+\&        $var2 = "$varl\en";
+\&
+\&        print $var2; 
+\&        exit;
+.Ve
+.PP
+While this compiles and runs happily, it probably won't do what's expected,
+namely it doesn't print "Hello World\en" at all;  It will on the other hand do
+exactly what it was told to do, computers being a bit that way inclined.  That
+is, it will print out a newline character, and you'll get what looks like a
+blank line.  It looks like there's 2 variables when (because of the typo)
+there's really 3:
+.PP
+.Vb 3
+\&        $var1 = \*(AqHello World\*(Aq;
+\&        $varl = undef;
+\&        $var2 = "\en";
+.Ve
+.PP
+To catch this kind of problem, we can force each variable to be declared
+before use by pulling in the strict module, by putting 'use strict;' after the
+first line of the script.
+.PP
+Now when you run it, perl complains about the 3 undeclared variables and we
+get four error messages because one variable is referenced twice:
+.PP
+.Vb 5
+\& Global symbol "$var1" requires explicit package name at ./t1 line 4.
+\& Global symbol "$var2" requires explicit package name at ./t1 line 5.
+\& Global symbol "$varl" requires explicit package name at ./t1 line 5.
+\& Global symbol "$var2" requires explicit package name at ./t1 line 7.
+\& Execution of ./hello aborted due to compilation errors.
+.Ve
+.PP
+Luvverly! and to fix this we declare all variables explicitly and now our
+script looks like this:
+.PP
+.Vb 2
+\&        #!/usr/bin/perl
+\&        use strict;
+\&
+\&        my $var1 = \*(AqHello World\*(Aq;
+\&        my $varl = undef;
+\&        my $var2 = "$varl\en";
+\&
+\&        print $var2; 
+\&        exit;
+.Ve
+.PP
+We then do (always a good idea) a syntax check before we try to run it again:
+.PP
+.Vb 2
+\&        > perl \-c hello
+\&        hello syntax OK
+.Ve
+.PP
+And now when we run it, we get "\en" still, but at least we know why.  Just
+getting this script to compile has exposed the '$varl' (with the letter 'l')
+variable, and simply changing \f(CW$varl\fR to \f(CW$var1\fR solves the problem.
+.SH "Looking at data and \-w and v"
+.IX Header "Looking at data and -w and v"
+Ok, but how about when you want to really see your data, what's in that
+dynamic variable, just before using it?
+.PP
+.Vb 2
+\&        #!/usr/bin/perl 
+\&        use strict;
+\&
+\&        my $key = \*(Aqwelcome\*(Aq;
+\&        my %data = (
+\&                \*(Aqthis\*(Aq => qw(that), 
+\&                \*(Aqtom\*(Aq => qw(and jerry),
+\&                \*(Aqwelcome\*(Aq => q(Hello World),
+\&                \*(Aqzip\*(Aq => q(welcome),
+\&        );
+\&        my @data = keys %data;
+\&
+\&        print "$data{$key}\en";
+\&        exit;
+.Ve
+.PP
+Looks OK, after it's been through the syntax check (perl \-c scriptname), we
+run it and all we get is a blank line again!  Hmmmm.
+.PP
+One common debugging approach here, would be to liberally sprinkle a few print
+statements, to add a check just before we print out our data, and another just
+after:
+.PP
+.Vb 3
+\&        print "All OK\en" if grep($key, keys %data);
+\&        print "$data{$key}\en";
+\&        print "done: \*(Aq$data{$key}\*(Aq\en";
+.Ve
+.PP
+And try again:
+.PP
+.Vb 2
+\&        > perl data
+\&        All OK     
+\&
+\&        done: \*(Aq\*(Aq
+.Ve
+.PP
+After much staring at the same piece of code and not seeing the wood for the
+trees for some time, we get a cup of coffee and try another approach.  That
+is, we bring in the cavalry by giving perl the '\fB\-d\fR' switch on the command
+line:
+.PP
+.Vb 2
+\&        > perl \-d data 
+\&        Default die handler restored.
+\&
+\&        Loading DB routines from perl5db.pl version 1.07
+\&        Editor support available.
+\&
+\&        Enter h or \`h h\*(Aq for help, or \`man perldebug\*(Aq for more help.
+\&
+\&        main::(./data:4):     my $key = \*(Aqwelcome\*(Aq;
+.Ve
+.PP
+Now, what we've done here is to launch the built-in perl debugger on our
+script.  It's stopped at the first line of executable code and is waiting for
+input.
+.PP
+Before we go any further, you'll want to know how to quit the debugger: use
+just the letter '\fBq\fR', not the words 'quit' or 'exit':
+.PP
+.Vb 2
+\&        DB<1> q
+\&        >
+.Ve
+.PP
+That's it, you're back on home turf again.
+.SH help
+.IX Header "help"
+Fire the debugger up again on your script and we'll look at the help menu. 
+There's a couple of ways of calling help: a simple '\fBh\fR' will get the summary 
+help list, '\fB|h\fR' (pipe-h) will pipe the help through your pager (which is 
+(probably 'more' or 'less'), and finally, '\fBh h\fR' (h\-space-h) will give you 
+the entire help screen.  Here is the summary page:
+.PP
+D\fB1\fRh
+.PP
+.Vb 10
+\& List/search source lines:               Control script execution:
+\&  l [ln|sub]  List source code            T           Stack trace
+\&  \- or .      List previous/current line  s [expr]    Single step
+\&                                                               [in expr]
+\&  v [line]    View around line            n [expr]    Next, steps over
+\&                                                                    subs
+\&  f filename  View source in file         <CR/Enter>  Repeat last n or s
+\&  /pattern/ ?patt?   Search forw/backw    r           Return from
+\&                                                              subroutine
+\&  M           Show module versions        c [ln|sub]  Continue until
+\&                                                                position
+\& Debugger controls:                       L           List break/watch/
+\&                                                                 actions
+\&  o [...]     Set debugger options        t [expr]    Toggle trace
+\&                                                            [trace expr]
+\&  <[<]|{[{]|>[>] [cmd] Do pre/post\-prompt b [ln|event|sub] [cnd] Set
+\&                                                              breakpoint
+\&  ! [N|pat]   Redo a previous command     B ln|*      Delete a/all
+\&                                                             breakpoints
+\&  H [\-num]    Display last num commands   a [ln] cmd  Do cmd before line
+\&  = [a val]   Define/list an alias        A ln|*      Delete a/all
+\&                                                                 actions
+\&  h [db_cmd]  Get help on command         w expr      Add a watch
+\&                                                              expression
+\&  h h         Complete help page          W expr|*    Delete a/all watch
+\&                                                                   exprs
+\&  |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a
+\&                                                              subprocess
+\&  q or ^D     Quit                        R           Attempt a restart
+\& Data Examination:     expr     Execute perl code, also see: s,n,t expr
+\&  x|m expr       Evals expr in list context, dumps the result or lists
+\&                                                                methods.
+\&  p expr         Print expression (uses script\*(Aqs current package).
+\&  S [[!]pat]     List subroutine names [not] matching pattern
+\&  V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or
+\&                                                               !pattern.
+\&  X [Vars]       Same as "V current_package [Vars]".
+\&  y [n [Vars]]   List lexicals in higher scope <n>.  Vars same as V.
+\& For more help, type h cmd_letter, or run man perldebug for all docs.
+.Ve
+.PP
+More confusing options than you can shake a big stick at!  It's not as bad as
+it looks and it's very useful to know more about all of it, and fun too!
+.PP
+There's a couple of useful ones to know about straight away.  You wouldn't
+think we're using any libraries at all at the moment, but '\fBM\fR' will show
+which modules are currently loaded, and their version number, while '\fBm\fR' 
+will show the methods, and '\fBS\fR' shows all subroutines (by pattern) as 
+shown below.  '\fBV\fR' and '\fBX\fR' show variables in the program by package 
+scope and can be constrained by pattern.
+.PP
+.Vb 5
+\&        DB<2>S str 
+\&        dumpvar::stringify
+\&        strict::bits
+\&        strict::import
+\&        strict::unimport
+.Ve
+.PP
+Using 'X' and cousins requires you not to use the type identifiers ($@%), just
+the 'name':
+.PP
+.Vb 2
+\&        DM<3>X ~err
+\&        FileHandle(stderr) => fileno(2)
+.Ve
+.PP
+Remember we're in our tiny program with a problem, we should have a look at
+where we are, and what our data looks like. First of all let's view some code 
+at our present position (the first line of code in this case), via '\fBv\fR':
+.PP
+.Vb 11
+\&        DB<4> v
+\&        1       #!/usr/bin/perl
+\&        2:      use strict;
+\&        3
+\&        4==>    my $key = \*(Aqwelcome\*(Aq;
+\&        5:      my %data = (
+\&        6               \*(Aqthis\*(Aq => qw(that),
+\&        7               \*(Aqtom\*(Aq => qw(and jerry),
+\&        8               \*(Aqwelcome\*(Aq => q(Hello World),
+\&        9               \*(Aqzip\*(Aq => q(welcome),
+\&        10      );
+.Ve
+.PP
+At line number 4 is a helpful pointer, that tells you where you are now.  To
+see more code, type 'v' again:
+.PP
+.Vb 9
+\&        DB<4> v
+\&        8               \*(Aqwelcome\*(Aq => q(Hello World),
+\&        9               \*(Aqzip\*(Aq => q(welcome),
+\&        10      );
+\&        11:     my @data = keys %data;
+\&        12:     print "All OK\en" if grep($key, keys %data);
+\&        13:     print "$data{$key}\en";
+\&        14:     print "done: \*(Aq$data{$key}\*(Aq\en";
+\&        15:     exit;
+.Ve
+.PP
+And if you wanted to list line 5 again, type 'l 5', (note the space):
+.PP
+.Vb 2
+\&        DB<4> l 5
+\&        5:      my %data = (
+.Ve
+.PP
+In this case, there's not much to see, but of course normally there's pages of
+stuff to wade through, and 'l' can be very useful.  To reset your view to the
+line we're about to execute, type a lone period '.':
+.PP
+.Vb 2
+\&        DB<5> .
+\&        main::(./data_a:4):     my $key = \*(Aqwelcome\*(Aq;
+.Ve
+.PP
+The line shown is the one that is about to be executed \fBnext\fR, it hasn't
+happened yet.  So while we can print a variable with the letter '\fBp\fR', at
+this point all we'd get is an empty (undefined) value back.  What we need to
+do is to step through the next executable statement with an '\fBs\fR':
+.PP
+.Vb 7
+\&        DB<6> s
+\&        main::(./data_a:5):     my %data = (
+\&        main::(./data_a:6):             \*(Aqthis\*(Aq => qw(that),
+\&        main::(./data_a:7):             \*(Aqtom\*(Aq => qw(and jerry),
+\&        main::(./data_a:8):             \*(Aqwelcome\*(Aq => q(Hello World),
+\&        main::(./data_a:9):             \*(Aqzip\*(Aq => q(welcome),
+\&        main::(./data_a:10):    );
+.Ve
+.PP
+Now we can have a look at that first ($key) variable:
+.PP
+.Vb 2
+\&        DB<7> p $key 
+\&        welcome
+.Ve
+.PP
+line 13 is where the action is, so let's continue down to there via the letter
+\&'\fBc\fR', which by the way, inserts a 'one\-time\-only' breakpoint at the given
+line or sub routine:
+.PP
+.Vb 3
+\&        DB<8> c 13
+\&        All OK
+\&        main::(./data_a:13):    print "$data{$key}\en";
+.Ve
+.PP
+We've gone past our check (where 'All OK' was printed) and have stopped just
+before the meat of our task.  We could try to print out a couple of variables
+to see what is happening:
+.PP
+.Vb 1
+\&        DB<9> p $data{$key}
+.Ve
+.PP
+Not much in there, lets have a look at our hash:
+.PP
+.Vb 2
+\&        DB<10> p %data
+\&        Hello Worldziptomandwelcomejerrywelcomethisthat 
+\&
+\&        DB<11> p keys %data
+\&        Hello Worldtomwelcomejerrythis
+.Ve
+.PP
+Well, this isn't very easy to read, and using the helpful manual (\fBh h\fR), the
+\&'\fBx\fR' command looks promising:
+.PP
+.Vb 11
+\&        DB<12> x %data
+\&        0  \*(AqHello World\*(Aq
+\&        1  \*(Aqzip\*(Aq
+\&        2  \*(Aqtom\*(Aq
+\&        3  \*(Aqand\*(Aq
+\&        4  \*(Aqwelcome\*(Aq
+\&        5  undef
+\&        6  \*(Aqjerry\*(Aq
+\&        7  \*(Aqwelcome\*(Aq
+\&        8  \*(Aqthis\*(Aq
+\&        9  \*(Aqthat\*(Aq
+.Ve
+.PP
+That's not much help, a couple of welcomes in there, but no indication of
+which are keys, and which are values, it's just a listed array dump and, in
+this case, not particularly helpful.  The trick here, is to use a \fBreference\fR
+to the data structure:
+.PP
+.Vb 7
+\&        DB<13> x \e%data
+\&        0  HASH(0x8194bc4)
+\&           \*(AqHello World\*(Aq => \*(Aqzip\*(Aq
+\&           \*(Aqjerry\*(Aq => \*(Aqwelcome\*(Aq
+\&           \*(Aqthis\*(Aq => \*(Aqthat\*(Aq
+\&           \*(Aqtom\*(Aq => \*(Aqand\*(Aq
+\&           \*(Aqwelcome\*(Aq => undef
+.Ve
+.PP
+The reference is truly dumped and we can finally see what we're dealing with. 
+Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
+being treated as 2 separate words rather than a phrase, thus throwing the
+evenly paired hash structure out of alignment.
+.PP
+The '\fB\-w\fR' switch would have told us about this, had we used it at the start,
+and saved us a lot of trouble:
+.PP
+.Vb 2
+\&        > perl \-w data
+\&        Odd number of elements in hash assignment at ./data line 5.
+.Ve
+.PP
+We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
+our expected output:
+.PP
+.Vb 2
+\&        > perl \-w data
+\&        Hello World
+.Ve
+.PP
+While we're here, take a closer look at the '\fBx\fR' command, it's really useful
+and will merrily dump out nested references, complete objects, partial objects
+\&\- just about whatever you throw at it:
+.PP
+Let's make a quick object and x\-plode it, first we'll start the debugger:
+it wants some form of input from STDIN, so we give it something non-committal,
+a zero:
+.PP
+.Vb 2
+\& > perl \-de 0
+\& Default die handler restored.
+\&
+\& Loading DB routines from perl5db.pl version 1.07
+\& Editor support available.
+\&
+\& Enter h or \`h h\*(Aq for help, or \`man perldebug\*(Aq for more help.
+\&
+\& main::(\-e:1):   0
+.Ve
+.PP
+Now build an on-the-fly object over a couple of lines (note the backslash):
+.PP
+.Vb 2
+\& DB<1> $obj = bless({\*(Aqunique_id\*(Aq=>\*(Aq123\*(Aq, \*(Aqattr\*(Aq=> \e
+\& cont:  {\*(Aqcol\*(Aq => \*(Aqblack\*(Aq, \*(Aqthings\*(Aq => [qw(this that etc)]}}, \*(AqMY_class\*(Aq)
+.Ve
+.PP
+And let's have a look at it:
+.PP
+.Vb 10
+\&        DB<2> x $obj
+\& 0  MY_class=HASH(0x828ad98)
+\&                \*(Aqattr\*(Aq => HASH(0x828ad68)
+\&        \*(Aqcol\*(Aq => \*(Aqblack\*(Aq
+\&        \*(Aqthings\*(Aq => ARRAY(0x828abb8)
+\&                0  \*(Aqthis\*(Aq
+\&                1  \*(Aqthat\*(Aq
+\&                2  \*(Aqetc\*(Aq
+\&                \*(Aqunique_id\*(Aq => 123       
+\&        DB<3>
+.Ve
+.PP
+Useful, huh?  You can eval nearly anything in there, and experiment with bits
+of code or regexes until the cows come home:
+.PP
+.Vb 1
+\& DB<3> @data = qw(this that the other atheism leather theory scythe)
+\&
+\& DB<4> p \*(Aqsaw \-> \*(Aq.($cnt += map { print "\et:\et$_\en" } grep(/the/, sort @data))
+\& atheism
+\& leather
+\& other
+\& scythe
+\& the
+\& theory
+\& saw \-> 6
+.Ve
+.PP
+If you want to see the command History, type an '\fBH\fR':
+.PP
+.Vb 7
+\& DB<5> H
+\& 4: p \*(Aqsaw \-> \*(Aq.($cnt += map { print "\et:\et$_\en" } grep(/the/, sort @data))
+\& 3: @data = qw(this that the other atheism leather theory scythe)
+\& 2: x $obj
+\& 1: $obj = bless({\*(Aqunique_id\*(Aq=>\*(Aq123\*(Aq, \*(Aqattr\*(Aq=>
+\& {\*(Aqcol\*(Aq => \*(Aqblack\*(Aq, \*(Aqthings\*(Aq => [qw(this that etc)]}}, \*(AqMY_class\*(Aq)
+\& DB<5>
+.Ve
+.PP
+And if you want to repeat any previous command, use the exclamation: '\fB!\fR':
+.PP
+.Vb 9
+\& DB<5> !4
+\& p \*(Aqsaw \-> \*(Aq.($cnt += map { print "$_\en" } grep(/the/, sort @data))
+\& atheism
+\& leather
+\& other
+\& scythe
+\& the
+\& theory
+\& saw \-> 12
+.Ve
+.PP
+For more on references see perlref and perlreftut
+.SH "Stepping through code"
+.IX Header "Stepping through code"
+Here's a simple program which converts between Celsius and Fahrenheit, it too
+has a problem:
+.PP
+.Vb 2
+\& #!/usr/bin/perl
+\& use v5.36;
+\&
+\& my $arg = $ARGV[0] || \*(Aq\-c20\*(Aq;
+\&
+\& if ($arg =~ /^\e\-(c|f)((\e\-|\e+)*\ed+(\e.\ed+)*)$/) {
+\&        my ($deg, $num) = ($1, $2);
+\&        my ($in, $out) = ($num, $num);
+\&        if ($deg eq \*(Aqc\*(Aq) {
+\&                $deg = \*(Aqf\*(Aq;
+\&                $out = &c2f($num);
+\&        } else {
+\&                $deg = \*(Aqc\*(Aq;
+\&                $out = &f2c($num);
+\&        }
+\&        $out = sprintf(\*(Aq%0.2f\*(Aq, $out);
+\&        $out =~ s/^((\e\-|\e+)*\ed+)\e.0+$/$1/;
+\&        print "$out $deg\en";
+\& } else {
+\&        print "Usage: $0 \-[c|f] num\en";
+\& }
+\& exit;
+\&
+\& sub f2c {
+\&        my $f = shift;
+\&        my $c = 5 * $f \- 32 / 9;
+\&        return $c;
+\& }
+\&
+\& sub c2f {
+\&        my $c = shift;
+\&        my $f = 9 * $c / 5 + 32;
+\&        return $f;
+\& }
+.Ve
+.PP
+For some reason, the Fahrenheit to Celsius conversion fails to return the
+expected output.  This is what it does:
+.PP
+.Vb 2
+\& > temp \-c0.72
+\& 33.30 f
+\&
+\& > temp \-f33.3
+\& 162.94 c
+.Ve
+.PP
+Not very consistent!  We'll set a breakpoint in the code manually and run it
+under the debugger to see what's going on.  A breakpoint is a flag, to which
+the debugger will run without interruption, when it reaches the breakpoint, it
+will stop execution and offer a prompt for further interaction.  In normal
+use, these debugger commands are completely ignored, and they are safe \- if a
+little messy, to leave in production code.
+.PP
+.Vb 4
+\&        my ($in, $out) = ($num, $num);
+\&        $DB::single=2; # insert at line 9!
+\&        if ($deg eq \*(Aqc\*(Aq) 
+\&                ...
+\&
+\&        > perl \-d temp \-f33.3
+\&        Default die handler restored.
+\&
+\&        Loading DB routines from perl5db.pl version 1.07
+\&        Editor support available.
+\&
+\&        Enter h or \`h h\*(Aq for help, or \`man perldebug\*(Aq for more help.
+\&
+\&        main::(temp:4): my $arg = $ARGV[0] || \*(Aq\-c100\*(Aq;
+.Ve
+.PP
+We'll simply continue down to our pre-set breakpoint with a '\fBc\fR':
+.PP
+.Vb 2
+\&        DB<1> c
+\&        main::(temp:10):                if ($deg eq \*(Aqc\*(Aq) {
+.Ve
+.PP
+Followed by a view command to see where we are:
+.PP
+.Vb 11
+\&        DB<1> v
+\&        7:              my ($deg, $num) = ($1, $2);
+\&        8:              my ($in, $out) = ($num, $num);
+\&        9:              $DB::single=2;
+\&        10==>           if ($deg eq \*(Aqc\*(Aq) {
+\&        11:                     $deg = \*(Aqf\*(Aq;
+\&        12:                     $out = &c2f($num);
+\&        13              } else {
+\&        14:                     $deg = \*(Aqc\*(Aq;
+\&        15:                     $out = &f2c($num);
+\&        16              }
+.Ve
+.PP
+And a print to show what values we're currently using:
+.PP
+.Vb 2
+\&        DB<1> p $deg, $num
+\&        f33.3
+.Ve
+.PP
+We can put another break point on any line beginning with a colon, we'll use
+line 17 as that's just as we come out of the subroutine, and we'd like to
+pause there later on:
+.PP
+.Vb 1
+\&        DB<2> b 17
+.Ve
+.PP
+There's no feedback from this, but you can see what breakpoints are set by
+using the list 'L' command:
+.PP
+.Vb 4
+\&        DB<3> L
+\&        temp:
+\&                17:            print "$out $deg\en";
+\&                break if (1)
+.Ve
+.PP
+Note that to delete a breakpoint you use 'B'.
+.PP
+Now we'll continue down into our subroutine, this time rather than by line
+number, we'll use the subroutine name, followed by the now familiar 'v':
+.PP
+.Vb 2
+\&        DB<3> c f2c
+\&        main::f2c(temp:30):             my $f = shift;  
+\&
+\&        DB<4> v
+\&        24:     exit;
+\&        25
+\&        26      sub f2c {
+\&        27==>           my $f = shift;
+\&        28:             my $c = 5 * $f \- 32 / 9; 
+\&        29:             return $c;
+\&        30      }
+\&        31
+\&        32      sub c2f {
+\&        33:             my $c = shift;
+.Ve
+.PP
+Note that if there was a subroutine call between us and line 29, and we wanted
+to \fBsingle-step\fR through it, we could use the '\fBs\fR' command, and to step
+over it we would use '\fBn\fR' which would execute the sub, but not descend into
+it for inspection.  In this case though, we simply continue down to line 29:
+.PP
+.Vb 2
+\&        DB<4> c 29  
+\&        main::f2c(temp:29):             return $c;
+.Ve
+.PP
+And have a look at the return value:
+.PP
+.Vb 2
+\&        DB<5> p $c
+\&        162.944444444444
+.Ve
+.PP
+This is not the right answer at all, but the sum looks correct.  I wonder if
+it's anything to do with operator precedence?  We'll try a couple of other
+possibilities with our sum:
+.PP
+.Vb 2
+\&        DB<6> p (5 * $f \- 32 / 9)
+\&        162.944444444444
+\&
+\&        DB<7> p 5 * $f \- (32 / 9) 
+\&        162.944444444444
+\&
+\&        DB<8> p (5 * $f) \- 32 / 9
+\&        162.944444444444
+\&
+\&        DB<9> p 5 * ($f \- 32) / 9
+\&        0.722222222222221
+.Ve
+.PP
+:\-) that's more like it!  Ok, now we can set our return variable and we'll
+return out of the sub with an 'r':
+.PP
+.Vb 1
+\&        DB<10> $c = 5 * ($f \- 32) / 9
+\&
+\&        DB<11> r
+\&        scalar context return from main::f2c: 0.722222222222221
+.Ve
+.PP
+Looks good, let's just continue off the end of the script:
+.PP
+.Vb 5
+\&        DB<12> c
+\&        0.72 c 
+\&        Debugged program terminated.  Use q to quit or R to restart,
+\&        use O inhibit_exit to avoid stopping after program termination,
+\&        h q, h R or h O to get additional info.
+.Ve
+.PP
+A quick fix to the offending line (insert the missing parentheses) in the
+actual program and we're finished.
+.SH "Placeholder for a, w, t, T"
+.IX Header "Placeholder for a, w, t, T"
+Actions, watch variables, stack traces etc.: on the TODO list.
+.PP
+.Vb 1
+\&        a 
+\&
+\&        w 
+\&
+\&        t 
+\&
+\&        T
+.Ve
+.SH "REGULAR EXPRESSIONS"
+.IX Header "REGULAR EXPRESSIONS"
+Ever wanted to know what a regex looked like?  You'll need perl compiled with
+the DEBUGGING flag for this one:
+.PP
+.Vb 10
+\&  > perl \-Dr \-e \*(Aq/^pe(a)*rl$/i\*(Aq
+\&  Compiling REx \`^pe(a)*rl$\*(Aq
+\&  size 17 first at 2
+\&  rarest char
+\&   at 0
+\&     1: BOL(2)
+\&     2: EXACTF <pe>(4)
+\&     4: CURLYN[1] {0,32767}(14)
+\&     6:   NOTHING(8)
+\&     8:   EXACTF <a>(0)
+\&    12:   WHILEM(0)
+\&    13: NOTHING(14)
+\&    14: EXACTF <rl>(16)
+\&    16: EOL(17)
+\&    17: END(0)
+\&  floating \`\*(Aq$ at 4..2147483647 (checking floating) stclass
+\&    \`EXACTF <pe>\*(Aq anchored(BOL) minlen 4
+\&  Omitting $\` $& $\*(Aq support.
+\&
+\&  EXECUTING...
+\&
+\&  Freeing REx: \`^pe(a)*rl$\*(Aq
+.Ve
+.PP
+Did you really want to know? :\-)
+For more gory details on getting regular expressions to work, have a look at
+perlre, perlretut, and to decode the mysterious labels (BOL and CURLYN,
+etc. above), see perldebguts.
+.SH "OUTPUT TIPS"
+.IX Header "OUTPUT TIPS"
+To get all the output from your error log, and not miss any messages via
+helpful operating system buffering, insert a line like this, at the start of
+your script:
+.PP
+.Vb 1
+\&        $|=1;
+.Ve
+.PP
+To watch the tail of a dynamically growing logfile, (from the command line):
+.PP
+.Vb 1
+\&        tail \-f $error_log
+.Ve
+.PP
+Wrapping all die calls in a handler routine can be useful to see how, and from
+where, they're being called, perlvar has more information:
+.PP
+.Vb 1
+\&    BEGIN { $SIG{_\|_DIE_\|_} = sub { require Carp; Carp::confess(@_) } }
+.Ve
+.PP
+Various useful techniques for the redirection of STDOUT and STDERR filehandles
+are explained in perlopentut and perlfaq8.
+.SH CGI
+.IX Header "CGI"
+Just a quick hint here for all those CGI programmers who can't figure out how
+on earth to get past that 'waiting for input' prompt, when running their CGI
+script from the command-line, try something like this:
+.PP
+.Vb 1
+\&        > perl \-d my_cgi.pl \-nodebug
+.Ve
+.PP
+Of course CGI and perlfaq9 will tell you more.
+.SH GUIs
+.IX Header "GUIs"
+The command line interface is tightly integrated with an \fBemacs\fR extension
+and there's a \fBvi\fR interface too.
+.PP
+You don't have to do this all on the command line, though, there are a few GUI
+options out there.  The nice thing about these is you can wave a mouse over a
+variable and a dump of its data will appear in an appropriate window, or in a
+popup balloon, no more tiresome typing of 'x \f(CW$varname\fR' :\-)
+.PP
+In particular have a hunt around for the following:
+.PP
+\&\fBptkdb\fR perlTK based wrapper for the built-in debugger
+.PP
+\&\fBddd\fR data display debugger
+.PP
+\&\fBPerlDevKit\fR and \fBPerlBuilder\fR are NT specific
+.PP
+NB. (more info on these and others would be appreciated).
+.SH SUMMARY
+.IX Header "SUMMARY"
+We've seen how to encourage good coding practices with \fBuse strict\fR and
+\&\fB\-w\fR.  We can run the perl debugger \fBperl \-d scriptname\fR to inspect your
+data from within the perl debugger with the \fBp\fR and \fBx\fR commands.  You can
+walk through your code, set breakpoints with \fBb\fR and step through that code
+with \fBs\fR or \fBn\fR, continue with \fBc\fR and return from a sub with \fBr\fR.  Fairly
+intuitive stuff when you get down to it.
+.PP
+There is of course lots more to find out about, this has just scratched the
+surface.  The best way to learn more is to use perldoc to find out more about
+the language, to read the on-line help (perldebug is probably the next
+place to go), and of course, experiment.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perldebug, 
+perldebguts, 
+perl5db.pl,
+perldiag,
+perlrun
+.SH AUTHOR
+.IX Header "AUTHOR"
+Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
+.SH CONTRIBUTORS
+.IX Header "CONTRIBUTORS"
+Various people have made helpful suggestions and contributions, in particular:
+.PP
+Ronald J Kimball <rjk@linguist.dartmouth.edu>
+.PP
+Hugo van der Sanden <hv@crypt0.demon.co.uk>
+.PP
+Peter Scott <Peter@PSDT.com>
diff --git a/upstream/mageia-cauldron/man1/perldebug.1 b/upstream/mageia-cauldron/man1/perldebug.1
new file mode 100644
index 00000000..bdbb3cf2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldebug.1
@@ -0,0 +1,1213 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDEBUG 1"
+.TH PERLDEBUG 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldebug \- Perl debugging
+.IX Xref "debug debugger"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+First of all, have you tried using \f(CW\*(C`use strict;\*(C'\fR and
+\&\f(CW\*(C`use warnings;\*(C'\fR?
+.PP
+If you're new to the Perl debugger, you may prefer to read
+perldebtut, which is a tutorial introduction to the debugger.
+.PP
+If you're looking for the nitty gritty details of how the debugger is
+\&\fIimplemented\fR, you may prefer to read perldebguts.
+.PP
+For in-depth technical usage details, see perl5db.pl, the documentation
+of the debugger itself.
+.SH "The Perl Debugger"
+.IX Header "The Perl Debugger"
+If you invoke Perl with the \fB\-d\fR switch, your script runs under the
+Perl source debugger.  This works like an interactive Perl
+environment, prompting for debugger commands that let you examine
+source code, set breakpoints, get stack backtraces, change the values of
+variables, etc.  This is so convenient that you often fire up
+the debugger all by itself just to test out Perl constructs
+interactively to see what they do.  For example:
+.IX Xref "-d"
+.PP
+.Vb 1
+\&    $ perl \-d \-e 42
+.Ve
+.PP
+In Perl, the debugger is not a separate program the way it usually is in the
+typical compiled environment.  Instead, the \fB\-d\fR flag tells the compiler
+to insert source information into the parse trees it's about to hand off
+to the interpreter.  That means your code must first compile correctly
+for the debugger to work on it.  Then when the interpreter starts up, it
+preloads a special Perl library file containing the debugger.
+.PP
+The program will halt \fIright before\fR the first run-time executable
+statement (but see below regarding compile-time statements) and ask you
+to enter a debugger command.  Contrary to popular expectations, whenever
+the debugger halts and shows you a line of code, it always displays the
+line it's \fIabout\fR to execute, rather than the one it has just executed.
+.PP
+Any command not recognized by the debugger is directly executed
+(\f(CW\*(C`eval\*(C'\fR'd) as Perl code in the current package.  (The debugger
+uses the DB package for keeping its own state information.)
+.PP
+Note that the said \f(CW\*(C`eval\*(C'\fR is bound by an implicit scope. As a
+result any newly introduced lexical variable or any modified
+capture buffer content is lost after the eval. The debugger is a
+nice environment to learn Perl, but if you interactively experiment using
+material which should be in the same scope, stuff it in one line.
+.PP
+For any text entered at the debugger prompt, leading and trailing whitespace
+is first stripped before further processing.  If a debugger command
+coincides with some function in your own program, merely precede the
+function with something that doesn't look like a debugger command, such
+as a leading \f(CW\*(C`;\*(C'\fR or perhaps a \f(CW\*(C`+\*(C'\fR, or by wrapping it with parentheses
+or braces.
+.SS "Calling the Debugger"
+.IX Subsection "Calling the Debugger"
+There are several ways to call the debugger:
+.IP "perl \-d program_name" 4
+.IX Item "perl -d program_name"
+On the given program identified by \f(CW\*(C`program_name\*(C'\fR.
+.IP "perl \-d \-e 0" 4
+.IX Item "perl -d -e 0"
+Interactively supply an arbitrary \f(CW\*(C`expression\*(C'\fR using \f(CW\*(C`\-e\*(C'\fR.
+.IP "perl \-d:ptkdb program_name" 4
+.IX Item "perl -d:ptkdb program_name"
+Debug a given program via the Devel::ptkdb GUI.
+.IP "perl \-dt threaded_program_name" 4
+.IX Item "perl -dt threaded_program_name"
+Debug a given program using threads (experimental).
+.PP
+If Perl is called with the \f(CW\*(C`\-d\*(C'\fR switch, the variable \f(CW$^P\fR will hold a true
+value. This is useful if you need to know if your code is running under the
+debugger:
+.PP
+.Vb 3
+\&    if ( $^P ) {
+\&        # running under the debugger
+\&    }
+.Ve
+.PP
+See "$^P" in perlvar for more information on the variable.
+.SS "Debugger Commands"
+.IX Subsection "Debugger Commands"
+The interactive debugger understands the following commands:
+.IP h 12
+.IX Xref "debugger command, h"
+.IX Item "h"
+Prints out a summary help message
+.IP "h [command]" 12
+.IX Item "h [command]"
+Prints out a help message for the given debugger command.
+.IP "h h" 12
+.IX Item "h h"
+The special argument of \f(CW\*(C`h h\*(C'\fR produces the entire help page, which is quite long.
+.Sp
+If the output of the \f(CW\*(C`h h\*(C'\fR command (or any command, for that matter) scrolls
+past your screen, precede the command with a leading pipe symbol so
+that it's run through your pager, as in
+.Sp
+.Vb 1
+\&    DB> |h h
+.Ve
+.Sp
+You may change the pager which is used via \f(CW\*(C`o pager=...\*(C'\fR command.
+.IP "p expr" 12
+.IX Xref "debugger command, p"
+.IX Item "p expr"
+Same as \f(CW\*(C`print {$DB::OUT} expr\*(C'\fR in the current package.  In particular,
+because this is just Perl's own \f(CW\*(C`print\*(C'\fR function, this means that nested
+data structures and objects are not dumped, unlike with the \f(CW\*(C`x\*(C'\fR command.
+.Sp
+The \f(CW\*(C`DB::OUT\*(C'\fR filehandle is opened to \fI/dev/tty\fR, regardless of
+where STDOUT may be redirected to.
+.IP "x [maxdepth] expr" 12
+.IX Xref "debugger command, x"
+.IX Item "x [maxdepth] expr"
+Evaluates its expression in list context and dumps out the result in a
+pretty-printed fashion.  Nested data structures are printed out
+recursively, unlike the real \f(CW\*(C`print\*(C'\fR function in Perl.  When dumping
+hashes, you'll probably prefer 'x \e%h' rather than 'x \f(CW%h\fR'.
+See Dumpvalue if you'd like to do this yourself.
+.Sp
+The output format is governed by multiple options described under
+"Configurable Options".
+.Sp
+If the \f(CW\*(C`maxdepth\*(C'\fR is included, it must be a numeral \fIN\fR; the value is
+dumped only \fIN\fR levels deep, as if the \f(CW\*(C`dumpDepth\*(C'\fR option had been
+temporarily set to \fIN\fR.
+.IP "V [pkg [vars]]" 12
+.IX Xref "debugger command, V"
+.IX Item "V [pkg [vars]]"
+Display all (or some) variables in package (defaulting to \f(CW\*(C`main\*(C'\fR)
+using a data pretty-printer (hashes show their keys and values so
+you see what's what, control characters are made printable, etc.).
+Make sure you don't put the type specifier (like \f(CW\*(C`$\*(C'\fR) there, just
+the symbol names, like this:
+.Sp
+.Vb 1
+\&    V DB filename line
+.Ve
+.Sp
+Use \f(CW\*(C`~pattern\*(C'\fR and \f(CW\*(C`!pattern\*(C'\fR for positive and negative regexes.
+.Sp
+This is similar to calling the \f(CW\*(C`x\*(C'\fR command on each applicable var.
+.IP "X [vars]" 12
+.IX Xref "debugger command, X"
+.IX Item "X [vars]"
+Same as \f(CW\*(C`V currentpackage [vars]\*(C'\fR.
+.IP "y [level [vars]]" 12
+.IX Xref "debugger command, y"
+.IX Item "y [level [vars]]"
+Display all (or some) lexical variables (mnemonic: \f(CW\*(C`mY\*(C'\fR variables)
+in the current scope or \fIlevel\fR scopes higher.  You can limit the
+variables that you see with \fIvars\fR which works exactly as it does
+for the \f(CW\*(C`V\*(C'\fR and \f(CW\*(C`X\*(C'\fR commands.  Requires the PadWalker module
+version 0.08 or higher; will warn if this isn't installed.  Output
+is pretty-printed in the same style as for \f(CW\*(C`V\*(C'\fR and the format is
+controlled by the same options.
+.IP T 12
+.IX Xref "debugger command, T backtrace stack, backtrace"
+.IX Item "T"
+Produce a stack backtrace.  See below for details on its output.
+.IP "s [expr]" 12
+.IX Xref "debugger command, s step"
+.IX Item "s [expr]"
+Single step.  Executes until the beginning of another
+statement, descending into subroutine calls.  If an expression is
+supplied that includes function calls, it too will be single-stepped.
+.IP "n [expr]" 12
+.IX Xref "debugger command, n"
+.IX Item "n [expr]"
+Next.  Executes over subroutine calls, until the beginning
+of the next statement.  If an expression is supplied that includes
+function calls, those functions will be executed with stops before
+each statement.
+.IP r 12
+.IX Xref "debugger command, r"
+.IX Item "r"
+Continue until the return from the current subroutine.
+Dump the return value if the \f(CW\*(C`PrintRet\*(C'\fR option is set (default).
+.IP <CR> 12
+.IX Item "<CR>"
+Repeat last \f(CW\*(C`n\*(C'\fR or \f(CW\*(C`s\*(C'\fR command.
+.IP "c [line|sub]" 12
+.IX Xref "debugger command, c"
+.IX Item "c [line|sub]"
+Continue, optionally inserting a one-time-only breakpoint
+at the specified line or subroutine.
+.IP l 12
+.IX Xref "debugger command, l"
+.IX Item "l"
+List next window of lines.
+.IP "l min+incr" 12
+.IX Item "l min+incr"
+List \f(CW\*(C`incr+1\*(C'\fR lines starting at \f(CW\*(C`min\*(C'\fR.
+.IP "l min-max" 12
+.IX Item "l min-max"
+List lines \f(CW\*(C`min\*(C'\fR through \f(CW\*(C`max\*(C'\fR.  \f(CW\*(C`l \-\*(C'\fR is synonymous to \f(CW\*(C`\-\*(C'\fR.
+.IP "l line" 12
+.IX Item "l line"
+List a single line.
+.IP "l subname" 12
+.IX Item "l subname"
+List first window of lines from subroutine.  \fIsubname\fR may
+be a variable that contains a code reference.
+.IP \- 12
+.IX Xref "debugger command, -"
+List previous window of lines.
+.IP "v [line]" 12
+.IX Xref "debugger command, v"
+.IX Item "v [line]"
+View a few lines of code around the current line.
+.IP . 12
+.IX Xref "debugger command, ."
+Return the internal debugger pointer to the line last
+executed, and print out that line.
+.IP "f filename" 12
+.IX Xref "debugger command, f"
+.IX Item "f filename"
+Switch to viewing a different file or \f(CW\*(C`eval\*(C'\fR statement.  If \fIfilename\fR
+is not a full pathname found in the values of \f(CW%INC\fR, it is considered
+a regex.
+.Sp
+\&\f(CW\*(C`eval\*(C'\fRed strings (when accessible) are considered to be filenames:
+\&\f(CW\*(C`f (eval 7)\*(C'\fR and \f(CW\*(C`f eval 7\eb\*(C'\fR access the body of the 7th \f(CW\*(C`eval\*(C'\fRed string
+(in the order of execution).  The bodies of the currently executed \f(CW\*(C`eval\*(C'\fR
+and of \f(CW\*(C`eval\*(C'\fRed strings that define subroutines are saved and thus
+accessible.
+.IP /pattern/ 12
+.IX Item "/pattern/"
+Search forwards for pattern (a Perl regex); final / is optional.
+The search is case-insensitive by default.
+.IP ?pattern? 12
+.IX Item "?pattern?"
+Search backwards for pattern; final ? is optional.
+The search is case-insensitive by default.
+.IP "L [abw]" 12
+.IX Xref "debugger command, L"
+.IX Item "L [abw]"
+List (default all) actions, breakpoints and watch expressions
+.IP "S [[!]regex]" 12
+.IX Xref "debugger command, S"
+.IX Item "S [[!]regex]"
+List subroutine names [not] matching the regex.
+.IP "t [n]" 12
+.IX Xref "debugger command, t"
+.IX Item "t [n]"
+Toggle trace mode (see also the \f(CW\*(C`AutoTrace\*(C'\fR option).
+Optional argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
+.IP "t [n] expr" 12
+.IX Xref "debugger command, t"
+.IX Item "t [n] expr"
+Trace through execution of \f(CW\*(C`expr\*(C'\fR.
+Optional first argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
+See "Frame Listing Output Examples" in perldebguts for examples.
+.IP b 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b"
+Sets breakpoint on current line
+.IP "b [line] [condition]" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b [line] [condition]"
+Set a breakpoint before the given line.  If a condition
+is specified, it's evaluated each time the statement is reached: a
+breakpoint is taken only if the condition is true.  Breakpoints may
+only be set on lines that begin an executable statement.  Conditions
+don't use \f(CW\*(C`if\*(C'\fR:
+.Sp
+.Vb 3
+\&    b 237 $x > 30
+\&    b 237 ++$count237 < 11
+\&    b 33 /pattern/i
+.Ve
+.Sp
+If the line number is \f(CW\*(C`.\*(C'\fR, sets a breakpoint on the current line:
+.Sp
+.Vb 1
+\&    b . $n > 100
+.Ve
+.IP "b [file]:[line] [condition]" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b [file]:[line] [condition]"
+Set a breakpoint before the given line in a (possibly different) file.  If a
+condition is specified, it's evaluated each time the statement is reached: a
+breakpoint is taken only if the condition is true.  Breakpoints may only be set
+on lines that begin an executable statement.  Conditions don't use \f(CW\*(C`if\*(C'\fR:
+.Sp
+.Vb 2
+\&    b lib/MyModule.pm:237 $x > 30
+\&    b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
+.Ve
+.IP "b subname [condition]" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b subname [condition]"
+Set a breakpoint before the first line of the named subroutine.  \fIsubname\fR may
+be a variable containing a code reference (in this case \fIcondition\fR
+is not supported).
+.IP "b postpone subname [condition]" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b postpone subname [condition]"
+Set a breakpoint at first line of subroutine after it is compiled.
+.IP "b load filename" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b load filename"
+Set a breakpoint before the first executed line of the \fIfilename\fR,
+which should be a full pathname found amongst the \f(CW%INC\fR values.
+.IP "b compile subname" 12
+.IX Xref "breakpoint debugger command, b"
+.IX Item "b compile subname"
+Sets a breakpoint before the first statement executed after the specified
+subroutine is compiled.
+.IP "B line" 12
+.IX Xref "breakpoint debugger command, B"
+.IX Item "B line"
+Delete a breakpoint from the specified \fIline\fR.
+.IP "B *" 12
+.IX Xref "breakpoint debugger command, B"
+.IX Item "B *"
+Delete all installed breakpoints.
+.IP "disable [file]:[line]" 12
+.IX Xref "breakpoint debugger command, disable disable"
+.IX Item "disable [file]:[line]"
+Disable the breakpoint so it won't stop the execution of the program. 
+Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR
+command.
+.IP "disable [line]" 12
+.IX Xref "breakpoint debugger command, disable disable"
+.IX Item "disable [line]"
+Disable the breakpoint so it won't stop the execution of the program. 
+Breakpoints are enabled by default and can be re-enabled using the \f(CW\*(C`enable\*(C'\fR
+command.
+.Sp
+This is done for a breakpoint in the current file.
+.IP "enable [file]:[line]" 12
+.IX Xref "breakpoint debugger command, disable disable"
+.IX Item "enable [file]:[line]"
+Enable the breakpoint so it will stop the execution of the program.
+.IP "enable [line]" 12
+.IX Xref "breakpoint debugger command, disable disable"
+.IX Item "enable [line]"
+Enable the breakpoint so it will stop the execution of the program.
+.Sp
+This is done for a breakpoint in the current file.
+.IP "a [line] command" 12
+.IX Xref "debugger command, a"
+.IX Item "a [line] command"
+Set an action to be done before the line is executed.  If \fIline\fR is
+omitted, set an action on the line about to be executed.
+The sequence of steps taken by the debugger is
+.Sp
+.Vb 5
+\&  1. check for a breakpoint at this line
+\&  2. print the line if necessary (tracing)
+\&  3. do any actions associated with that line
+\&  4. prompt user if at a breakpoint or in single\-step
+\&  5. evaluate line
+.Ve
+.Sp
+For example, this will print out \f(CW$foo\fR every time line
+53 is passed:
+.Sp
+.Vb 1
+\&    a 53 print "DB FOUND $foo\en"
+.Ve
+.IP "A line" 12
+.IX Xref "debugger command, A"
+.IX Item "A line"
+Delete an action from the specified line.
+.IP "A *" 12
+.IX Xref "debugger command, A"
+.IX Item "A *"
+Delete all installed actions.
+.IP "w expr" 12
+.IX Xref "debugger command, w"
+.IX Item "w expr"
+Add a global watch-expression. Whenever a watched global changes the
+debugger will stop and display the old and new values.
+.IP "W expr" 12
+.IX Xref "debugger command, W"
+.IX Item "W expr"
+Delete watch-expression
+.IP "W *" 12
+.IX Xref "debugger command, W"
+.IX Item "W *"
+Delete all watch-expressions.
+.IP o 12
+.IX Xref "debugger command, o"
+.IX Item "o"
+Display all options.
+.IP "o booloption ..." 12
+.IX Xref "debugger command, o"
+.IX Item "o booloption ..."
+Set each listed Boolean option to the value \f(CW1\fR.
+.IP "o anyoption? ..." 12
+.IX Xref "debugger command, o"
+.IX Item "o anyoption? ..."
+Print out the value of one or more options.
+.IP "o option=value ..." 12
+.IX Xref "debugger command, o"
+.IX Item "o option=value ..."
+Set the value of one or more options.  If the value has internal
+whitespace, it should be quoted.  For example, you could set \f(CW\*(C`o
+pager="less \-MQeicsNfr"\*(C'\fR to call \fBless\fR with those specific options.
+You may use either single or double quotes, but if you do, you must
+escape any embedded instances of same sort of quote you began with,
+as well as any escaping any escapes that immediately precede that
+quote but which are not meant to escape the quote itself.  In other
+words, you follow single-quoting rules irrespective of the quote;
+eg: \f(CW\*(C`o option=\*(Aqthis isn\e\*(Aqt bad\*(Aq\*(C'\fR or \f(CW\*(C`o option="She said, \e"Isn\*(Aqt
+it?\e""\*(C'\fR.
+.Sp
+For historical reasons, the \f(CW\*(C`=value\*(C'\fR is optional, but defaults to
+1 only where it is safe to do so\-\-that is, mostly for Boolean
+options.  It is always better to assign a specific value using \f(CW\*(C`=\*(C'\fR.
+The \f(CW\*(C`option\*(C'\fR can be abbreviated, but for clarity probably should
+not be.  Several options can be set together.  See "Configurable Options"
+for a list of these.
+.IP "< ?" 12
+.IX Xref "debugger command, <"
+List out all pre-prompt Perl command actions.
+.IP "< [ command ]" 12
+.IX Xref "debugger command, <"
+.IX Item "< [ command ]"
+Set an action (Perl command) to happen before every debugger prompt.
+A multi-line command may be entered by backslashing the newlines.
+.IP "< *" 12
+.IX Xref "debugger command, <"
+Delete all pre-prompt Perl command actions.
+.IP "<< command" 12
+.IX Xref "debugger command, <<"
+.IX Item "<< command"
+Add an action (Perl command) to happen before every debugger prompt.
+A multi-line command may be entered by backwhacking the newlines.
+.IP "> ?" 12
+.IX Xref "debugger command, >"
+List out post-prompt Perl command actions.
+.IP "> command" 12
+.IX Xref "debugger command, >"
+.IX Item "> command"
+Set an action (Perl command) to happen after the prompt when you've
+just given a command to return to executing the script.  A multi-line
+command may be entered by backslashing the newlines (we bet you
+couldn't have guessed this by now).
+.IP "> *" 12
+.IX Xref "debugger command, >"
+Delete all post-prompt Perl command actions.
+.IP ">> command" 12
+.IX Xref "debugger command, >>"
+.IX Item ">> command"
+Adds an action (Perl command) to happen after the prompt when you've
+just given a command to return to executing the script.  A multi-line
+command may be entered by backslashing the newlines.
+.IP "{ ?" 12
+.IX Xref "debugger command, {"
+List out pre-prompt debugger commands.
+.IP "{ [ command ]" 12
+.IX Item "{ [ command ]"
+Set an action (debugger command) to happen before every debugger prompt.
+A multi-line command may be entered in the customary fashion.
+.Sp
+Because this command is in some senses new, a warning is issued if
+you appear to have accidentally entered a block instead.  If that's
+what you mean to do, write it as with \f(CW\*(C`;{ ... }\*(C'\fR or even
+\&\f(CW\*(C`do { ... }\*(C'\fR.
+.IP "{ *" 12
+.IX Xref "debugger command, {"
+Delete all pre-prompt debugger commands.
+.IP "{{ command" 12
+.IX Xref "debugger command, {{"
+.IX Item "{{ command"
+Add an action (debugger command) to happen before every debugger prompt.
+A multi-line command may be entered, if you can guess how: see above.
+.IP "! number" 12
+.IX Xref "debugger command, !"
+.IX Item "! number"
+Redo a previous command (defaults to the previous command).
+.IP "! \-number" 12
+.IX Xref "debugger command, !"
+.IX Item "! -number"
+Redo number'th previous command.
+.IP "! pattern" 12
+.IX Xref "debugger command, !"
+.IX Item "! pattern"
+Redo last command that started with pattern.
+See \f(CW\*(C`o\ recallCommand\*(C'\fR, too.
+.IP "!! cmd" 12
+.IX Xref "debugger command, !!"
+.IX Item "!! cmd"
+Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
+\&\f(CW\*(C`o\ shellBang\*(C'\fR, also.  Note that the user's current shell (well,
+their \f(CW$ENV{SHELL}\fR variable) will be used, which can interfere
+with proper interpretation of exit status or signal and coredump
+information.
+.IP "source file" 12
+.IX Xref "debugger command, source"
+.IX Item "source file"
+Read and execute debugger commands from \fIfile\fR.
+\&\fIfile\fR may itself contain \f(CW\*(C`source\*(C'\fR commands.
+.IP "H \-number" 12
+.IX Xref "debugger command, H"
+.IX Item "H -number"
+Display last n commands.  Only commands longer than one character are
+listed.  If \fInumber\fR is omitted, list them all.
+.IP "q or ^D" 12
+.IX Xref "debugger command, q debugger command, ^D"
+.IX Item "q or ^D"
+Quit.  ("quit" doesn't work for this, unless you've made an alias)
+This is the only supported way to exit the debugger, though typing
+\&\f(CW\*(C`exit\*(C'\fR twice might work.
+.Sp
+Set the \f(CW\*(C`inhibit_exit\*(C'\fR option to 0 if you want to be able to step
+off the end the script.  You may also need to set \f(CW$finished\fR to 0
+if you want to step through global destruction.
+.IP R 12
+.IX Xref "debugger command, R"
+.IX Item "R"
+Restart the debugger by \f(CWexec()\fRing a new session.  We try to maintain
+your history across this, but internal settings and command-line options
+may be lost.
+.Sp
+The following setting are currently preserved: history, breakpoints,
+actions, debugger options, and the Perl command-line
+options \fB\-w\fR, \fB\-I\fR, and \fB\-e\fR.
+.IP |dbcmd 12
+.IX Xref "debugger command, |"
+.IX Item "|dbcmd"
+Run the debugger command, piping DB::OUT into your current pager.
+.IP ||dbcmd 12
+.IX Xref "debugger command, ||"
+.IX Item "||dbcmd"
+Same as \f(CW\*(C`|dbcmd\*(C'\fR but DB::OUT is temporarily \f(CW\*(C`select\*(C'\fRed as well.
+.IP "= [alias value]" 12
+.IX Xref "debugger command, ="
+.IX Item "= [alias value]"
+Define a command alias, like
+.Sp
+.Vb 1
+\&    = quit q
+.Ve
+.Sp
+or list current aliases.
+.IP command 12
+.IX Item "command"
+Execute command as a Perl statement.  A trailing semicolon will be
+supplied.  If the Perl statement would otherwise be confused for a
+Perl debugger, use a leading semicolon, too.
+.IP "m expr" 12
+.IX Xref "debugger command, m"
+.IX Item "m expr"
+List which methods may be called on the result of the evaluated
+expression.  The expression may evaluated to a reference to a
+blessed object, or to a package name.
+.IP M 12
+.IX Xref "debugger command, M"
+.IX Item "M"
+Display all loaded modules and their versions.
+.IP "man [manpage]" 12
+.IX Xref "debugger command, man"
+.IX Item "man [manpage]"
+Despite its name, this calls your system's default documentation
+viewer on the given page, or on the viewer itself if \fImanpage\fR is
+omitted.  If that viewer is \fBman\fR, the current \f(CW\*(C`Config\*(C'\fR information
+is used to invoke \fBman\fR using the proper MANPATH or \fB\-M\fR\ \fImanpath\fR option.  Failed lookups of the form \f(CW\*(C`XXX\*(C'\fR that match
+known manpages of the form \fIperlXXX\fR will be retried.  This lets
+you type \f(CW\*(C`man debug\*(C'\fR or \f(CW\*(C`man op\*(C'\fR from the debugger.
+.Sp
+On systems traditionally bereft of a usable \fBman\fR command, the
+debugger invokes \fBperldoc\fR.  Occasionally this determination is
+incorrect due to recalcitrant vendors or rather more felicitously,
+to enterprising users.  If you fall into either category, just
+manually set the \f(CW$DB::doccmd\fR variable to whatever viewer to view
+the Perl documentation on your system.  This may be set in an rc
+file, or through direct assignment.  We're still waiting for a
+working example of something along the lines of:
+.Sp
+.Vb 1
+\&    $DB::doccmd = \*(Aqnetscape \-remote http://something.here/\*(Aq;
+.Ve
+.SS "Configurable Options"
+.IX Subsection "Configurable Options"
+The debugger has numerous options settable using the \f(CW\*(C`o\*(C'\fR command,
+either interactively or from the environment or an rc file. The file
+is named \fI./.perldb\fR or \fI~/.perldb\fR under Unix with \fI/dev/tty\fR,
+\&\fIperldb.ini\fR otherwise.
+.ie n .IP """recallCommand"", ""ShellBang""" 12
+.el .IP "\f(CWrecallCommand\fR, \f(CWShellBang\fR" 12
+.IX Xref "debugger option, recallCommand debugger option, ShellBang"
+.IX Item "recallCommand, ShellBang"
+The characters used to recall a command or spawn a shell.  By
+default, both are set to \f(CW\*(C`!\*(C'\fR, which is unfortunate.
+.ie n .IP """pager""" 12
+.el .IP \f(CWpager\fR 12
+.IX Xref "debugger option, pager"
+.IX Item "pager"
+Program to use for output of pager-piped commands (those beginning
+with a \f(CW\*(C`|\*(C'\fR character.)  By default, \f(CW$ENV{PAGER}\fR will be used.
+Because the debugger uses your current terminal characteristics
+for bold and underlining, if the chosen pager does not pass escape
+sequences through unchanged, the output of some debugger commands
+will not be readable when sent through the pager.
+.ie n .IP """tkRunning""" 12
+.el .IP \f(CWtkRunning\fR 12
+.IX Xref "debugger option, tkRunning"
+.IX Item "tkRunning"
+Run Tk while prompting (with ReadLine).
+.ie n .IP """signalLevel"", ""warnLevel"", ""dieLevel""" 12
+.el .IP "\f(CWsignalLevel\fR, \f(CWwarnLevel\fR, \f(CWdieLevel\fR" 12
+.IX Xref "debugger option, signalLevel debugger option, warnLevel debugger option, dieLevel"
+.IX Item "signalLevel, warnLevel, dieLevel"
+Level of verbosity.  By default, the debugger leaves your exceptions
+and warnings alone, because altering them can break correctly running
+programs.  It will attempt to print a message when uncaught INT, BUS, or
+SEGV signals arrive.  (But see the mention of signals in "BUGS" below.)
+.Sp
+To disable this default safe mode, set these values to something higher
+than 0.  At a level of 1, you get backtraces upon receiving any kind
+of warning (this is often annoying) or exception (this is
+often valuable).  Unfortunately, the debugger cannot discern fatal
+exceptions from non-fatal ones.  If \f(CW\*(C`dieLevel\*(C'\fR is even 1, then your
+non-fatal exceptions are also traced and unceremoniously altered if they
+came from \f(CW\*(C`eval\*(Aqed\*(C'\fR strings or from any kind of \f(CW\*(C`eval\*(C'\fR within modules
+you're attempting to load.  If \f(CW\*(C`dieLevel\*(C'\fR is 2, the debugger doesn't
+care where they came from:  It usurps your exception handler and prints
+out a trace, then modifies all exceptions with its own embellishments.
+This may perhaps be useful for some tracing purposes, but tends to hopelessly
+destroy any program that takes its exception handling seriously.
+.ie n .IP """AutoTrace""" 12
+.el .IP \f(CWAutoTrace\fR 12
+.IX Xref "debugger option, AutoTrace"
+.IX Item "AutoTrace"
+Trace mode (similar to \f(CW\*(C`t\*(C'\fR command, but can be put into
+\&\f(CW\*(C`PERLDB_OPTS\*(C'\fR).
+.ie n .IP """LineInfo""" 12
+.el .IP \f(CWLineInfo\fR 12
+.IX Xref "debugger option, LineInfo"
+.IX Item "LineInfo"
+File or pipe to print line number info to.  If it is a pipe (say,
+\&\f(CW\*(C`|visual_perl_db\*(C'\fR), then a short message is used.  This is the
+mechanism used to interact with a client editor or visual debugger,
+such as the special \f(CW\*(C`vi\*(C'\fR or \f(CW\*(C`emacs\*(C'\fR hooks, or the \f(CW\*(C`ddd\*(C'\fR graphical
+debugger.
+.ie n .IP """inhibit_exit""" 12
+.el .IP \f(CWinhibit_exit\fR 12
+.IX Xref "debugger option, inhibit_exit"
+.IX Item "inhibit_exit"
+If 0, allows \fIstepping off\fR the end of the script.
+.ie n .IP """PrintRet""" 12
+.el .IP \f(CWPrintRet\fR 12
+.IX Xref "debugger option, PrintRet"
+.IX Item "PrintRet"
+Print return value after \f(CW\*(C`r\*(C'\fR command if set (default).
+.ie n .IP """ornaments""" 12
+.el .IP \f(CWornaments\fR 12
+.IX Xref "debugger option, ornaments"
+.IX Item "ornaments"
+Affects screen appearance of the command line (see Term::ReadLine).
+There is currently no way to disable these, which can render
+some output illegible on some displays, or with some pagers.
+This is considered a bug.
+.ie n .IP """frame""" 12
+.el .IP \f(CWframe\fR 12
+.IX Xref "debugger option, frame"
+.IX Item "frame"
+Affects the printing of messages upon entry and exit from subroutines.  If
+\&\f(CW\*(C`frame & 2\*(C'\fR is false, messages are printed on entry only. (Printing
+on exit might be useful if interspersed with other messages.)
+.Sp
+If \f(CW\*(C`frame & 4\*(C'\fR, arguments to functions are printed, plus context
+and caller info.  If \f(CW\*(C`frame & 8\*(C'\fR, overloaded \f(CW\*(C`stringify\*(C'\fR and
+\&\f(CW\*(C`tie\*(C'\fRd \f(CW\*(C`FETCH\*(C'\fR is enabled on the printed arguments.  If \f(CW\*(C`frame
+& 16\*(C'\fR, the return value from the subroutine is printed.
+.Sp
+The length at which the argument list is truncated is governed by the
+next option:
+.ie n .IP """maxTraceLen""" 12
+.el .IP \f(CWmaxTraceLen\fR 12
+.IX Xref "debugger option, maxTraceLen"
+.IX Item "maxTraceLen"
+Length to truncate the argument list when the \f(CW\*(C`frame\*(C'\fR option's
+bit 4 is set.
+.ie n .IP """windowSize""" 12
+.el .IP \f(CWwindowSize\fR 12
+.IX Xref "debugger option, windowSize"
+.IX Item "windowSize"
+Change the size of code list window (default is 10 lines).
+.PP
+The following options affect what happens with \f(CW\*(C`V\*(C'\fR, \f(CW\*(C`X\*(C'\fR, and \f(CW\*(C`x\*(C'\fR
+commands:
+.ie n .IP """arrayDepth"", ""hashDepth""" 12
+.el .IP "\f(CWarrayDepth\fR, \f(CWhashDepth\fR" 12
+.IX Xref "debugger option, arrayDepth debugger option, hashDepth"
+.IX Item "arrayDepth, hashDepth"
+Print only first N elements ('' for all).
+.ie n .IP """dumpDepth""" 12
+.el .IP \f(CWdumpDepth\fR 12
+.IX Xref "debugger option, dumpDepth"
+.IX Item "dumpDepth"
+Limit recursion depth to N levels when dumping structures.
+Negative values are interpreted as infinity.  Default: infinity.
+.ie n .IP """compactDump"", ""veryCompact""" 12
+.el .IP "\f(CWcompactDump\fR, \f(CWveryCompact\fR" 12
+.IX Xref "debugger option, compactDump debugger option, veryCompact"
+.IX Item "compactDump, veryCompact"
+Change the style of array and hash output.  If \f(CW\*(C`compactDump\*(C'\fR, short array
+may be printed on one line.
+.ie n .IP """globPrint""" 12
+.el .IP \f(CWglobPrint\fR 12
+.IX Xref "debugger option, globPrint"
+.IX Item "globPrint"
+Whether to print contents of globs.
+.ie n .IP """DumpDBFiles""" 12
+.el .IP \f(CWDumpDBFiles\fR 12
+.IX Xref "debugger option, DumpDBFiles"
+.IX Item "DumpDBFiles"
+Dump arrays holding debugged files.
+.ie n .IP """DumpPackages""" 12
+.el .IP \f(CWDumpPackages\fR 12
+.IX Xref "debugger option, DumpPackages"
+.IX Item "DumpPackages"
+Dump symbol tables of packages.
+.ie n .IP """DumpReused""" 12
+.el .IP \f(CWDumpReused\fR 12
+.IX Xref "debugger option, DumpReused"
+.IX Item "DumpReused"
+Dump contents of "reused" addresses.
+.ie n .IP """quote"", ""HighBit"", ""undefPrint""" 12
+.el .IP "\f(CWquote\fR, \f(CWHighBit\fR, \f(CWundefPrint\fR" 12
+.IX Xref "debugger option, quote debugger option, HighBit debugger option, undefPrint"
+.IX Item "quote, HighBit, undefPrint"
+Change the style of string dump.  The default value for \f(CW\*(C`quote\*(C'\fR
+is \f(CW\*(C`auto\*(C'\fR; one can enable double-quotish or single-quotish format
+by setting it to \f(CW\*(C`"\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR, respectively.  By default, characters
+with their high bit set are printed verbatim.
+.ie n .IP """UsageOnly""" 12
+.el .IP \f(CWUsageOnly\fR 12
+.IX Xref "debugger option, UsageOnly"
+.IX Item "UsageOnly"
+Rudimentary per-package memory usage dump.  Calculates total
+size of strings found in variables in the package.  This does not
+include lexicals in a module's file scope, or lost in closures.
+.ie n .IP """HistFile""" 12
+.el .IP \f(CWHistFile\fR 12
+.IX Xref "debugger option, history, HistFile"
+.IX Item "HistFile"
+The path of the file from which the history (assuming a usable
+Term::ReadLine backend) will be read on the debugger's startup, and to which
+it will be saved on shutdown (for persistence across sessions). Similar in
+concept to Bash's \f(CW\*(C`.bash_history\*(C'\fR file.
+.ie n .IP """HistSize""" 12
+.el .IP \f(CWHistSize\fR 12
+.IX Xref "debugger option, history, HistSize"
+.IX Item "HistSize"
+The count of the saved lines in the history (assuming \f(CW\*(C`HistFile\*(C'\fR above).
+.PP
+After the rc file is read, the debugger reads the \f(CW$ENV{PERLDB_OPTS}\fR
+environment variable and parses this as the remainder of a "O ..."
+line as one might enter at the debugger prompt.  You may place the
+initialization options \f(CW\*(C`TTY\*(C'\fR, \f(CW\*(C`noTTY\*(C'\fR, \f(CW\*(C`ReadLine\*(C'\fR, and \f(CW\*(C`NonStop\*(C'\fR
+there.
+.PP
+If your rc file contains:
+.PP
+.Vb 1
+\&  parse_options("NonStop=1 LineInfo=db.out AutoTrace");
+.Ve
+.PP
+then your script will run without human intervention, putting trace
+information into the file \fIdb.out\fR.  (If you interrupt it, you'd
+better reset \f(CW\*(C`LineInfo\*(C'\fR to \fI/dev/tty\fR if you expect to see anything.)
+.ie n .IP """TTY""" 12
+.el .IP \f(CWTTY\fR 12
+.IX Xref "debugger option, TTY"
+.IX Item "TTY"
+The TTY to use for debugging I/O.
+.ie n .IP """noTTY""" 12
+.el .IP \f(CWnoTTY\fR 12
+.IX Xref "debugger option, noTTY"
+.IX Item "noTTY"
+If set, the debugger goes into \f(CW\*(C`NonStop\*(C'\fR mode and will not connect to a TTY.  If
+interrupted (or if control goes to the debugger via explicit setting of
+\&\f(CW$DB::signal\fR or \f(CW$DB::single\fR from the Perl script), it connects to a TTY
+specified in the \f(CW\*(C`TTY\*(C'\fR option at startup, or to a tty found at
+runtime using the \f(CW\*(C`Term::Rendezvous\*(C'\fR module of your choice.
+.Sp
+This module should implement a method named \f(CW\*(C`new\*(C'\fR that returns an object
+with two methods: \f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR.  These should return filehandles to use
+for debugging input and output correspondingly.  The \f(CW\*(C`new\*(C'\fR method should
+inspect an argument containing the value of \f(CW$ENV{PERLDB_NOTTY}\fR at
+startup, or \f(CW"$ENV{HOME}/.perldbtty$$"\fR otherwise.  This file is not
+inspected for proper ownership, so security hazards are theoretically
+possible.
+.ie n .IP """ReadLine""" 12
+.el .IP \f(CWReadLine\fR 12
+.IX Xref "debugger option, ReadLine"
+.IX Item "ReadLine"
+If false, readline support in the debugger is disabled in order
+to debug applications that themselves use ReadLine.
+.ie n .IP """NonStop""" 12
+.el .IP \f(CWNonStop\fR 12
+.IX Xref "debugger option, NonStop"
+.IX Item "NonStop"
+If set, the debugger goes into non-interactive mode until interrupted, or
+programmatically by setting \f(CW$DB::signal\fR or \f(CW$DB::single\fR.
+.PP
+Here's an example of using the \f(CW$ENV{PERLDB_OPTS}\fR variable:
+.PP
+.Vb 1
+\&    $ PERLDB_OPTS="NonStop frame=2" perl \-d myprogram
+.Ve
+.PP
+That will run the script \fBmyprogram\fR without human intervention,
+printing out the call tree with entry and exit points.  Note that
+\&\f(CW\*(C`NonStop=1 frame=2\*(C'\fR is equivalent to \f(CW\*(C`N f=2\*(C'\fR, and that originally,
+options could be uniquely abbreviated by the first letter (modulo
+the \f(CW\*(C`Dump*\*(C'\fR options).  It is nevertheless recommended that you
+always spell them out in full for legibility and future compatibility.
+.PP
+Other examples include
+.PP
+.Vb 1
+\&    $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl \-d myprogram
+.Ve
+.PP
+which runs script non-interactively, printing info on each entry
+into a subroutine and each executed line into the file named \fIlisting\fR.
+(If you interrupt it, you would better reset \f(CW\*(C`LineInfo\*(C'\fR to something
+"interactive"!)
+.PP
+Other examples include (using standard shell syntax to show environment
+variable settings):
+.PP
+.Vb 2
+\&  $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
+\&      perl \-d myprogram )
+.Ve
+.PP
+which may be useful for debugging a program that uses Term::ReadLine
+itself.  Do not forget to detach your shell from the TTY in the window that
+corresponds to \fI/dev/ttyXX\fR, say, by issuing a command like
+.PP
+.Vb 1
+\&  $ sleep 1000000
+.Ve
+.PP
+See "Debugger Internals" in perldebguts for details.
+.SS "Debugger Input/Output"
+.IX Subsection "Debugger Input/Output"
+.IP Prompt 8
+.IX Item "Prompt"
+The debugger prompt is something like
+.Sp
+.Vb 1
+\&    DB<8>
+.Ve
+.Sp
+or even
+.Sp
+.Vb 1
+\&    DB<<17>>
+.Ve
+.Sp
+where that number is the command number, and which you'd use to
+access with the built-in \fBcsh\fR\-like history mechanism.  For example,
+\&\f(CW\*(C`!17\*(C'\fR would repeat command number 17.  The depth of the angle
+brackets indicates the nesting depth of the debugger.  You could
+get more than one set of brackets, for example, if you'd already
+at a breakpoint and then printed the result of a function call that
+itself has a breakpoint, or you step into an expression via \f(CW\*(C`s/n/t
+expression\*(C'\fR command.
+.IP "Multiline commands" 8
+.IX Item "Multiline commands"
+If you want to enter a multi-line command, such as a subroutine
+definition with several statements or a format, escape the newline
+that would normally end the debugger command with a backslash.
+Here's an example:
+.Sp
+.Vb 7
+\&      DB<1> for (1..4) {         \e
+\&      cont:     print "ok\en";   \e
+\&      cont: }
+\&      ok
+\&      ok
+\&      ok
+\&      ok
+.Ve
+.Sp
+Note that this business of escaping a newline is specific to interactive
+commands typed into the debugger.
+.IP "Stack backtrace" 8
+.IX Xref "backtrace stack, backtrace"
+.IX Item "Stack backtrace"
+Here's an example of what a stack backtrace via \f(CW\*(C`T\*(C'\fR command might
+look like:
+.Sp
+.Vb 5
+\& $ = main::infested called from file \*(AqAmbulation.pm\*(Aq line 10
+\& @ = Ambulation::legs(1, 2, 3, 4) called from file \*(Aqcamel_flea\*(Aq
+\&                                                          line 7
+\& $ = main::pests(\*(Aqbactrian\*(Aq, 4) called from file \*(Aqcamel_flea\*(Aq
+\&                                                          line 4
+.Ve
+.Sp
+The left-hand character up there indicates the context in which the
+function was called, with \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR meaning scalar or list
+contexts respectively, and \f(CW\*(C`.\*(C'\fR meaning void context (which is
+actually a sort of scalar context).  The display above says
+that you were in the function \f(CW\*(C`main::infested\*(C'\fR when you ran the
+stack dump, and that it was called in scalar context from line
+10 of the file \fIAmbulation.pm\fR, but without any arguments at all,
+meaning it was called as \f(CW&infested\fR.  The next stack frame shows
+that the function \f(CW\*(C`Ambulation::legs\*(C'\fR was called in list context
+from the \fIcamel_flea\fR file with four arguments.  The last stack
+frame shows that \f(CW\*(C`main::pests\*(C'\fR was called in scalar context,
+also from \fIcamel_flea\fR, but from line 4.
+.Sp
+If you execute the \f(CW\*(C`T\*(C'\fR command from inside an active \f(CW\*(C`use\*(C'\fR
+statement, the backtrace will contain both a \f(CW\*(C`require\*(C'\fR frame and
+an \f(CW\*(C`eval\*(C'\fR frame.
+.IP "Line Listing Format" 8
+.IX Item "Line Listing Format"
+This shows the sorts of output the \f(CW\*(C`l\*(C'\fR command can produce:
+.Sp
+.Vb 11
+\&   DB<<13>> l
+\& 101:        @i{@i} = ();
+\& 102:b       @isa{@i,$pack} = ()
+\& 103             if(exists $i{$prevpack} || exists $isa{$pack});
+\& 104     }
+\& 105
+\& 106     next
+\& 107==>      if(exists $isa{$pack});
+\& 108
+\& 109:a   if ($extra\-\- > 0) {
+\& 110:        %isa = ($pack,1);
+.Ve
+.Sp
+Breakable lines are marked with \f(CW\*(C`:\*(C'\fR.  Lines with breakpoints are
+marked by \f(CW\*(C`b\*(C'\fR and those with actions by \f(CW\*(C`a\*(C'\fR.  The line that's
+about to be executed is marked by \f(CW\*(C`==>\*(C'\fR.
+.Sp
+Please be aware that code in debugger listings may not look the same
+as your original source code.  Line directives and external source
+filters can alter the code before Perl sees it, causing code to move
+from its original positions or take on entirely different forms.
+.IP "Frame listing" 8
+.IX Item "Frame listing"
+When the \f(CW\*(C`frame\*(C'\fR option is set, the debugger would print entered (and
+optionally exited) subroutines in different styles.  See perldebguts
+for incredibly long examples of these.
+.SS "Debugging Compile-Time Statements"
+.IX Subsection "Debugging Compile-Time Statements"
+If you have compile-time executable statements (such as code within
+BEGIN, UNITCHECK and CHECK blocks or \f(CW\*(C`use\*(C'\fR statements), these will
+\&\fInot\fR be stopped by debugger, although \f(CW\*(C`require\*(C'\fRs and INIT blocks
+will, and compile-time statements can be traced with the \f(CW\*(C`AutoTrace\*(C'\fR
+option set in \f(CW\*(C`PERLDB_OPTS\*(C'\fR).  From your own Perl code, however, you
+can transfer control back to the debugger using the following
+statement, which is harmless if the debugger is not running:
+.PP
+.Vb 1
+\&    $DB::single = 1;
+.Ve
+.PP
+If you set \f(CW$DB::single\fR to 2, it's equivalent to having
+just typed the \f(CW\*(C`n\*(C'\fR command, whereas a value of 1 means the \f(CW\*(C`s\*(C'\fR
+command.  The \f(CW$DB::trace\fR  variable should be set to 1 to simulate
+having typed the \f(CW\*(C`t\*(C'\fR command.
+.PP
+Another way to debug compile-time code is to start the debugger, set a
+breakpoint on the \fIload\fR of some module:
+.PP
+.Vb 2
+\&    DB<7> b load f:/perllib/lib/Carp.pm
+\&  Will stop on load of \*(Aqf:/perllib/lib/Carp.pm\*(Aq.
+.Ve
+.PP
+and then restart the debugger using the \f(CW\*(C`R\*(C'\fR command (if possible).  One can use \f(CW\*(C`b
+compile subname\*(C'\fR for the same purpose.
+.SS "Debugger Customization"
+.IX Subsection "Debugger Customization"
+The debugger probably contains enough configuration hooks that you
+won't ever have to modify it yourself.  You may change the behaviour
+of the debugger from within the debugger using its \f(CW\*(C`o\*(C'\fR command, from
+the command line via the \f(CW\*(C`PERLDB_OPTS\*(C'\fR environment variable, and
+from customization files.
+.PP
+You can do some customization by setting up a \fI.perldb\fR file, which
+contains initialization code.  For instance, you could make aliases
+like these (the last one is one people expect to be there):
+.PP
+.Vb 4
+\&    $DB::alias{\*(Aqlen\*(Aq}  = \*(Aqs/^len(.*)/p length($1)/\*(Aq;
+\&    $DB::alias{\*(Aqstop\*(Aq} = \*(Aqs/^stop (at|in)/b/\*(Aq;
+\&    $DB::alias{\*(Aqps\*(Aq}   = \*(Aqs/^ps\eb/p scalar /\*(Aq;
+\&    $DB::alias{\*(Aqquit\*(Aq} = \*(Aqs/^quit(\es*)/exit/\*(Aq;
+.Ve
+.PP
+You can change options from \fI.perldb\fR by using calls like this one;
+.PP
+.Vb 1
+\&    parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
+.Ve
+.PP
+The code is executed in the package \f(CW\*(C`DB\*(C'\fR.  Note that \fI.perldb\fR is
+processed before processing \f(CW\*(C`PERLDB_OPTS\*(C'\fR.  If \fI.perldb\fR defines the
+subroutine \f(CW\*(C`afterinit\*(C'\fR, that function is called after debugger
+initialization ends.  \fI.perldb\fR may be contained in the current
+directory, or in the home directory.  Because this file is sourced
+in by Perl and may contain arbitrary commands, for security reasons,
+it must be owned by the superuser or the current user, and writable
+by no one but its owner.
+.PP
+You can mock TTY input to debugger by adding arbitrary commands to
+\&\f(CW@DB::typeahead\fR. For example, your \fI.perldb\fR file might contain:
+.PP
+.Vb 1
+\&    sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
+.Ve
+.PP
+Which would attempt to set breakpoints on lines 4 and 6 immediately
+after debugger initialization. Note that \f(CW@DB::typeahead\fR is not a supported
+interface and is subject to change in future releases.
+.PP
+If you want to modify the debugger, copy \fIperl5db.pl\fR from the
+Perl library to another name and hack it to your heart's content.
+You'll then want to set your \f(CW\*(C`PERL5DB\*(C'\fR environment variable to say
+something like this:
+.PP
+.Vb 1
+\&    BEGIN { require "myperl5db.pl" }
+.Ve
+.PP
+As a last resort, you could also use \f(CW\*(C`PERL5DB\*(C'\fR to customize the debugger
+by directly setting internal variables or calling debugger functions.
+.PP
+Note that any variables and functions that are not documented in
+this document (or in perldebguts) are considered for internal
+use only, and as such are subject to change without notice.
+.SS "Readline Support / History in the Debugger"
+.IX Subsection "Readline Support / History in the Debugger"
+As shipped, the only command-line history supplied is a simplistic one
+that checks for leading exclamation points.  However, if you install
+the Term::ReadKey and Term::ReadLine modules from CPAN (such as
+Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
+have full editing capabilities much like those GNU \fIreadline\fR(3) provides.
+Look for these in the \fImodules/by\-module/Term\fR directory on CPAN.
+These do not support normal \fBvi\fR command-line editing, however.
+.PP
+A rudimentary command-line completion is also available, including
+lexical variables in the current scope if the PadWalker module
+is installed.
+.PP
+Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
+"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
+.SS "Editor Support for Debugging"
+.IX Subsection "Editor Support for Debugging"
+If you have the GNU's version of \fBemacs\fR installed on your system,
+it can interact with the Perl debugger to provide an integrated
+software development environment reminiscent of its interactions
+with C debuggers.
+.PP
+Recent versions of Emacs come with a
+start file for making \fBemacs\fR act like a
+syntax-directed editor that understands (some of) Perl's syntax.
+See perlfaq3.
+.PP
+Users of \fBvi\fR should also look into \fBvim\fR and \fBgvim\fR, the mousey
+and windy version, for coloring of Perl keywords.
+.PP
+Note that only perl can truly parse Perl, so all such CASE tools
+fall somewhat short of the mark, especially if you don't program
+your Perl as a C programmer might.
+.SS "The Perl Profiler"
+.IX Xref "profile profiling profiler"
+.IX Subsection "The Perl Profiler"
+If you wish to supply an alternative debugger for Perl to run,
+invoke your script with a colon and a package argument given to the
+\&\fB\-d\fR flag.  Perl's alternative debuggers include a Perl profiler,
+Devel::NYTProf, which is available separately as a CPAN
+distribution.  To profile your Perl program in the file \fImycode.pl\fR,
+just type:
+.PP
+.Vb 1
+\&    $ perl \-d:NYTProf mycode.pl
+.Ve
+.PP
+When the script terminates the profiler will create a database of the
+profile information that you can turn into reports using the profiler's
+tools. See <perlperf> for details.
+.SH "Debugging Regular Expressions"
+.IX Xref "regular expression, debugging regex, debugging regexp, debugging"
+.IX Header "Debugging Regular Expressions"
+\&\f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR enables you to see the gory details of how the Perl
+regular expression engine works. In order to understand this typically
+voluminous output, one must not only have some idea about how regular
+expression matching works in general, but also know how Perl's regular
+expressions are internally compiled into an automaton. These matters
+are explored in some detail in
+"Debugging Regular Expressions" in perldebguts.
+.SH "Debugging Memory Usage"
+.IX Xref "memory usage"
+.IX Header "Debugging Memory Usage"
+Perl contains internal support for reporting its own memory usage,
+but this is a fairly advanced concept that requires some understanding
+of how memory allocation works.
+See "Debugging Perl Memory Usage" in perldebguts for the details.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+You do have \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR enabled, don't you?
+.PP
+perldebtut,
+perldebguts,
+perl5db.pl,
+re,
+DB,
+Devel::NYTProf,
+Dumpvalue,
+and
+perlrun.
+.PP
+When debugging a script that uses #! and is thus normally found in
+\&\f(CW$PATH\fR, the \-S option causes perl to search \f(CW$PATH\fR for it, so you don't
+have to type the path or \f(CW\*(C`which $scriptname\*(C'\fR.
+.PP
+.Vb 1
+\&  $ perl \-Sd foo.pl
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+You cannot get stack frame information or in any fashion debug functions
+that were not compiled by Perl, such as those from C or C++ extensions.
+.PP
+If you alter your \f(CW@_\fR arguments in a subroutine (such as with \f(CW\*(C`shift\*(C'\fR
+or \f(CW\*(C`pop\*(C'\fR), the stack backtrace will not show the original values.
+.PP
+The debugger does not currently work in conjunction with the \fB\-W\fR
+command-line switch, because it itself is not free of warnings.
+.PP
+If you're in a slow syscall (like \f(CW\*(C`wait\*(C'\fRing, \f(CW\*(C`accept\*(C'\fRing, or \f(CW\*(C`read\*(C'\fRing
+from your keyboard or a socket) and haven't set up your own \f(CW$SIG{INT}\fR
+handler, then you won't be able to CTRL-C your way back to the debugger,
+because the debugger's own \f(CW$SIG{INT}\fR handler doesn't understand that
+it needs to raise an exception to \fBlongjmp\fR\|(3) out of slow syscalls.
diff --git a/upstream/mageia-cauldron/man1/perldelta.1 b/upstream/mageia-cauldron/man1/perldelta.1
new file mode 100644
index 00000000..0036fa2d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldelta.1
@@ -0,0 +1,161 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDELTA 1"
+.TH PERLDELTA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldelta \- what is new for perl v5.38.2
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.38.0 release and the 5.38.2
+release.  \fBPlease note:\fR This document ignores Perl 5.38.1, a broken release
+which existed for a couple of days only.
+.PP
+If you are upgrading from an earlier release such as 5.37.0, first read
+perl5380delta, which describes differences between 5.37.0 and 5.38.0.
+.SH Security
+.IX Header "Security"
+This release fixes the following security issues.
+.SS "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property"
+.IX Subsection "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+This vulnerability was reported directly to the Perl security team by
+Nathan Mills \f(CW\*(C`the.true.nathan.mills@gmail.com\*(C'\fR.
+.PP
+A crafted regular expression when compiled by perl 5.30.0 through
+5.38.0 can cause a one-byte attacker controlled buffer overflow in a
+heap allocated buffer.
+.SS "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability"
+.IX Subsection "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+This vulnerability was reported to the Intel Product Security Incident
+Response Team (PSIRT) by GitHub user ycdxsb
+<https://github.com/ycdxsb/WindowsPrivilegeEscalation>. PSIRT then
+reported it to the Perl security team.
+.PP
+Perl for Windows relies on the system path environment variable to
+find the shell (\f(CW\*(C`cmd.exe\*(C'\fR). When running an executable which uses
+Windows Perl interpreter, Perl attempts to find and execute \f(CW\*(C`cmd.exe\*(C'\fR
+within the operating system. However, due to path search order issues,
+Perl initially looks for cmd.exe in the current working directory.
+.PP
+An attacker with limited privileges can exploit this behavior by
+placing \f(CW\*(C`cmd.exe\*(C'\fR in locations with weak permissions, such as
+\&\f(CW\*(C`C:\eProgramData\*(C'\fR. By doing so, when an administrator attempts to use
+this executable from these compromised locations, arbitrary code can
+be executed.
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Perl 5.38.2 represents approximately 5 months of development since Perl
+5.38.0 and contains approximately 6,100 lines of changes across 34 files
+from 4 authors.
+.PP
+Excluding auto-generated files, documentation and release tools, there were
+approximately 1,300 lines of changes to 9 .pm, .t, .c and .h files.
+.PP
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.38.2:
+.PP
+Karl Williamson, Paul Evans, Steve Hay, Tony Cook.
+.PP
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+.PP
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+.PP
+For a more complete list of all of Perl's historical contributors, please
+see the \fIAUTHORS\fR file in the Perl source distribution.
+.SH "Reporting Bugs"
+.IX Header "Reporting Bugs"
+If you find what you think is a bug, you might check the perl bug database
+at <https://github.com/Perl/perl5/issues>.  There may also be information at
+<http://www.perl.org/>, the Perl Home Page.
+.PP
+If you believe you have an unreported bug, please open an issue at
+<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
+tiny but sufficient test case.
+.PP
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, then see
+"SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details of how to report the issue.
+.SH "Give Thanks"
+.IX Header "Give Thanks"
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the \f(CW\*(C`perlthanks\*(C'\fR program:
+.PP
+.Vb 1
+\&    perlthanks
+.Ve
+.PP
+This will send an email to the Perl 5 Porters list with your show of thanks.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for an explanation of how to view exhaustive details on
+what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fIArtistic\fR and \fICopying\fR files for copyright information.
diff --git a/upstream/mageia-cauldron/man1/perldeprecation.1 b/upstream/mageia-cauldron/man1/perldeprecation.1
new file mode 100644
index 00000000..cbb1cece
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldeprecation.1
@@ -0,0 +1,750 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDEPRECATION 1"
+.TH PERLDEPRECATION 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldeprecation \- list Perl deprecations
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The purpose of this document is to document what has been deprecated
+in Perl, and by which version the deprecated feature will disappear,
+or, for already removed features, when it was removed.
+.PP
+This document will try to discuss what alternatives for the deprecated
+features are available.
+.PP
+The deprecated features will be grouped by the version of Perl in
+which they will be removed.
+.SS "Unscheduled Deprecations"
+.IX Subsection "Unscheduled Deprecations"
+\fIUnicode Delimiter Will be Paired\fR
+.IX Subsection "Unicode Delimiter Will be Paired"
+.PP
+Some unicode delimiters used to be allowed as single characters but
+in the future will be part of a ballanced pair. This deprecation category
+is used to mark the ones that will change from being unpaired, to paired.
+.PP
+Category: "deprecated::delimiter_will_be_paired"
+.PP
+\fIDot In Inc\fR
+.IX Subsection "Dot In Inc"
+.PP
+The current working direct \f(CW"."\fR used to be automatically included in
+\&\f(CW@INC\fR, but in Perl 5.26 this was removed for security reasons. Ever
+since then we have produced a warning when a user uses \f(CW\*(C`do EXPR\*(C'\fR and
+\&\f(CW\*(C`EXPR\*(C'\fR does not include a path, and the file was not found in any
+directory in \f(CW@INC\fR but \fIwas\fR located \f(CW"."\fR. The file will not be loaded
+but a deprecated warning will be generated.
+.PP
+Category: "deprecated::dot_in_inc"
+.PP
+\fIGoto Block Construct\fR
+.IX Subsection "Goto Block Construct"
+.PP
+\&\f(CW\*(C`goto LABEL;\*(C'\fR will produce a deprecated warning when jumping into the body
+of a loop or other block construct from outside. For instance
+.PP
+.Vb 5
+\&    while (should_loop($x)) {
+\&        LABEL:
+\&            do_stuff();
+\&    }
+\&    goto LABEL;
+.Ve
+.PP
+will produce a warning that this behavior is deprecated. In general you should
+just avoid doing this, the people that maintain your code will be grateful for
+your restraint.
+.PP
+Category: "deprecated::goto_construct"
+.PP
+\fIUnicode Property Name\fR
+.IX Subsection "Unicode Property Name"
+.PP
+Various types of unicode property name will generate deprecated warnings
+when used in a regex pattern. For instance surrogate characters will result
+in deprecation warnings.
+.PP
+Category: "deprecated::unicode_property_name"
+.SS "Perl 5.42"
+.IX Subsection "Perl 5.42"
+\fISmartmatch\fR
+.IX Subsection "Smartmatch"
+.PP
+Smartmatch is now seen as a failed experiment and was marked as deprecated
+in Perl 5.37.10. This includes the \f(CW\*(C`when\*(C'\fR and \f(CW\*(C`given\*(C'\fR keywords, as well
+as the smartmatch operator \f(CW\*(C`~~\*(C'\fR. The feature will be removed entirely in the
+Perl 5.42.0 production release.
+.PP
+Category: "deprecated::smartmatch"
+.PP
+\fIUse of \fR\f(CI\*(C`\*(Aq\*(C'\fR\fI as a global name separator.\fR
+.IX Subsection "Use of as a global name separator."
+.PP
+Perl allows use of \f(CW\*(C`\*(Aq\*(C'\fR instead of \f(CW\*(C`::\*(C'\fR to replace the parts of a
+package or global variable name, for example \f(CW\*(C`A::B\*(C'\fR and \f(CW\*(C`A\*(AqB\*(C'\fR are
+equivalent.
+.PP
+\&\f(CW\*(C`\*(Aq\*(C'\fR will no longer be recognized as a name separator in Perl 5.42.
+.PP
+Category: "deprecated::apostrophe_as_package_separator"
+.SS "Perl 5.40"
+.IX Subsection "Perl 5.40"
+\fIDowngrading a \fR\f(CI\*(C`use VERSION\*(C'\fR\fI to below v5.11\fR
+.IX Subsection "Downgrading a use VERSION to below v5.11"
+.PP
+Once Perl has seen a \f(CW\*(C`use VERSION\*(C'\fR declaration that requests a version
+\&\f(CW\*(C`v5.11\*(C'\fR or above, a subsequent second declaration that requests an earlier
+version will print a deprecation warning. For example,
+.PP
+.Vb 2
+\&    use v5.14;
+\&    say "We can use v5.14\*(Aqs features here";
+\&
+\&    use v5.10;        # This prints a warning
+.Ve
+.PP
+This behaviour will be removed in Perl 5.40; such a subsequent request will
+become a compile-time error.
+.PP
+This is because of an intended related change to the interaction between
+\&\f(CW\*(C`use VERSION\*(C'\fR and \f(CW\*(C`use strict\*(C'\fR. If you specify a version >= 5.11, strict is
+enabled implicitly. If you request a version < 5.11, strict will become
+disabled \fIeven if you had previously written\fR \f(CW\*(C`use strict\*(C'\fR. This was not
+the previous behaviour of \f(CW\*(C`use VERSION\*(C'\fR, which at present will track
+explicitly-enabled strictness flags independently.
+.PP
+Category: "deprecated::version_downgrade"
+.SS "Perl 5.38"
+.IX Subsection "Perl 5.38"
+\fIPod::Html utility functions\fR
+.IX Subsection "Pod::Html utility functions"
+.PP
+The definition and documentation of three utility functions previously
+importable from Pod::Html were moved to new package Pod::Html::Util in
+Perl 5.36.  While they remain importable from Pod::Html in Perl 5.36, as of
+Perl 5.38 they will only be importable, on request, from Pod::Html::Util.
+.SS "Perl 5.34"
+.IX Subsection "Perl 5.34"
+There were no deprecations or fatalizations in Perl 5.34.
+.SS "Perl 5.32"
+.IX Subsection "Perl 5.32"
+\fIConstants from lexical variables potentially modified elsewhere\fR
+.IX Subsection "Constants from lexical variables potentially modified elsewhere"
+.PP
+You wrote something like
+.PP
+.Vb 2
+\&    my $var;
+\&    $sub = sub () { $var };
+.Ve
+.PP
+but \f(CW$var\fR is referenced elsewhere and could be modified after the \f(CW\*(C`sub\*(C'\fR
+expression is evaluated.  Either it is explicitly modified elsewhere
+(\f(CW\*(C`$var = 3\*(C'\fR) or it is passed to a subroutine or to an operator like
+\&\f(CW\*(C`printf\*(C'\fR or \f(CW\*(C`map\*(C'\fR, which may or may not modify the variable.
+.PP
+Traditionally, Perl has captured the value of the variable at that
+point and turned the subroutine into a constant eligible for inlining.
+In those cases where the variable can be modified elsewhere, this
+breaks the behavior of closures, in which the subroutine captures
+the variable itself, rather than its value, so future changes to the
+variable are reflected in the subroutine's return value.
+.PP
+If you intended for the subroutine to be eligible for inlining, then
+make sure the variable is not referenced elsewhere, possibly by
+copying it:
+.PP
+.Vb 2
+\&    my $var2 = $var;
+\&    $sub = sub () { $var2 };
+.Ve
+.PP
+If you do want this subroutine to be a closure that reflects future
+changes to the variable that it closes over, add an explicit \f(CW\*(C`return\*(C'\fR:
+.PP
+.Vb 2
+\&    my $var;
+\&    $sub = sub () { return $var };
+.Ve
+.PP
+This usage was deprecated and as of Perl 5.32 is no longer allowed.
+.PP
+\fIUse of strings with code points over 0xFF as arguments to \fR\f(CI\*(C`vec\*(C'\fR
+.IX Subsection "Use of strings with code points over 0xFF as arguments to vec"
+.PP
+\&\f(CW\*(C`vec\*(C'\fR views its string argument as a sequence of bits.  A string
+containing a code point over 0xFF is nonsensical.  This usage is
+deprecated in Perl 5.28, and was removed in Perl 5.32.
+.PP
+\fIUse of code points over 0xFF in string bitwise operators\fR
+.IX Subsection "Use of code points over 0xFF in string bitwise operators"
+.PP
+The string bitwise operators, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR, treat their
+operands as strings of bytes. As such, values above 0xFF are
+nonsensical. Some instances of these have been deprecated since Perl
+5.24, and were made fatal in 5.28, but it turns out that in cases where
+the wide characters did not affect the end result, no deprecation
+notice was raised, and so remain legal.  Now, all occurrences either are
+fatal or raise a deprecation warning, so that the remaining legal
+occurrences became fatal in 5.32.
+.PP
+An example of this is
+.PP
+.Vb 1
+\& "" & "\ex{100}"
+.Ve
+.PP
+The wide character is not used in the \f(CW\*(C`&\*(C'\fR operation because the left
+operand is shorter.  This now throws an exception.
+.PP
+\fR\f(BIhostname()\fR\fI doesn't accept any arguments\fR
+.IX Subsection "hostname() doesn't accept any arguments"
+.PP
+The function \f(CWhostname()\fR in the Sys::Hostname module has always
+been documented to be called with no arguments.  Historically it has not
+enforced this, and has actually accepted and ignored any arguments.  As a
+result, some users have got the mistaken impression that an argument does
+something useful.  To avoid these bugs, the function is being made strict.
+Passing arguments was deprecated in Perl 5.28 and became fatal in Perl 5.32.
+.PP
+\fIUnescaped left braces in regular expressions\fR
+.IX Subsection "Unescaped left braces in regular expressions"
+.PP
+The simple rule to remember, if you want to match a literal \f(CW\*(C`{\*(C'\fR
+character (U+007B \f(CW\*(C`LEFT CURLY BRACKET\*(C'\fR) in a regular expression
+pattern, is to escape each literal instance of it in some way.
+Generally easiest is to precede it with a backslash, like \f(CW\*(C`\e{\*(C'\fR
+or enclose it in square brackets (\f(CW\*(C`[{]\*(C'\fR).  If the pattern
+delimiters are also braces, any matching right brace (\f(CW\*(C`}\*(C'\fR) should
+also be escaped to avoid confusing the parser, for example,
+.PP
+.Vb 1
+\& qr{abc\e{def\e}ghi}
+.Ve
+.PP
+Forcing literal \f(CW\*(C`{\*(C'\fR characters to be escaped will enable the Perl
+language to be extended in various ways in future releases.  To avoid
+needlessly breaking existing code, the restriction is not enforced in
+contexts where there are unlikely to ever be extensions that could
+conflict with the use there of \f(CW\*(C`{\*(C'\fR as a literal.  A non-deprecation
+warning that the left brace is being taken literally is raised in
+contexts where there could be confusion about it.
+.PP
+Literal uses of \f(CW\*(C`{\*(C'\fR were deprecated in Perl 5.20, and some uses of it
+started to give deprecation warnings since. These cases were made fatal
+in Perl 5.26. Due to an oversight, not all cases of a use of a literal
+\&\f(CW\*(C`{\*(C'\fR got a deprecation warning.  Some cases started warning in Perl 5.26,
+and were made fatal in Perl 5.30.  Other cases started in Perl 5.28,
+and were made fatal in 5.32.
+.PP
+\fIIn XS code, use of various macros dealing with UTF\-8.\fR
+.IX Subsection "In XS code, use of various macros dealing with UTF-8."
+.PP
+The macros below now require an extra parameter than in versions prior
+to Perl 5.32.  The final parameter in each one is a pointer into the
+string supplied by the first parameter beyond which the input will not
+be read.  This prevents potential reading beyond the end of the buffer.
+\&\f(CW\*(C`isALPHANUMERIC_utf8\*(C'\fR,
+\&\f(CW\*(C`isASCII_utf8\*(C'\fR,
+\&\f(CW\*(C`isBLANK_utf8\*(C'\fR,
+\&\f(CW\*(C`isCNTRL_utf8\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_utf8\*(C'\fR,
+\&\f(CW\*(C`isIDFIRST_utf8\*(C'\fR,
+\&\f(CW\*(C`isPSXSPC_utf8\*(C'\fR,
+\&\f(CW\*(C`isSPACE_utf8\*(C'\fR,
+\&\f(CW\*(C`isVERTWS_utf8\*(C'\fR,
+\&\f(CW\*(C`isWORDCHAR_utf8\*(C'\fR,
+\&\f(CW\*(C`isXDIGIT_utf8\*(C'\fR,
+\&\f(CW\*(C`isALPHANUMERIC_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isALPHA_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isASCII_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isBLANK_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isCNTRL_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isGRAPH_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isIDCONT_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isIDFIRST_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isLOWER_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isPRINT_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isPSXSPC_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isPUNCT_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isSPACE_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isUPPER_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isWORDCHAR_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`isXDIGIT_LC_utf8\*(C'\fR,
+\&\f(CW\*(C`toFOLD_utf8\*(C'\fR,
+\&\f(CW\*(C`toLOWER_utf8\*(C'\fR,
+\&\f(CW\*(C`toTITLE_utf8\*(C'\fR,
+and
+\&\f(CW\*(C`toUPPER_utf8\*(C'\fR.
+.PP
+Since Perl 5.26, this functionality with the extra parameter has been
+available by using a corresponding macro to each one of these, and whose
+name is formed by appending \f(CW\*(C`_safe\*(C'\fR to the base name.  There is no
+change to the functionality of those.  For example, \f(CW\*(C`isDIGIT_utf8_safe\*(C'\fR
+corresponds to \f(CW\*(C`isDIGIT_utf8\*(C'\fR, and both now behave identically.  All
+are documented in "Character case changing" in perlapi and
+"Character classification" in perlapi.
+.PP
+This change was originally scheduled for 5.30, but was delayed until
+5.32.
+.PP
+\fR\f(CIFile::Glob::glob()\fR\fI was removed\fR
+.IX Subsection "File::Glob::glob() was removed"
+.PP
+\&\f(CW\*(C`File::Glob\*(C'\fR has a function called \f(CW\*(C`glob\*(C'\fR, which just calls
+\&\f(CW\*(C`bsd_glob\*(C'\fR.
+.PP
+\&\f(CWFile::Glob::glob()\fR was deprecated in Perl 5.8. A deprecation
+message was issued from Perl 5.26 onwards, the function became fatal
+in Perl 5.30, and was removed entirely in Perl 5.32.
+.PP
+Code using \f(CWFile::Glob::glob()\fR should call
+\&\f(CWFile::Glob::bsd_glob()\fR instead.
+.SS "Perl 5.30"
+.IX Subsection "Perl 5.30"
+\fR\f(CI$*\fR\fI is no longer supported\fR
+.IX Subsection "$* is no longer supported"
+.PP
+Before Perl 5.10, setting \f(CW$*\fR to a true value globally enabled
+multi-line matching within a string. This relique from the past lost
+its special meaning in 5.10. Use of this variable became a fatal error
+in Perl 5.30, freeing the variable up for a future special meaning.
+.PP
+To enable multiline matching one should use the \f(CW\*(C`/m\*(C'\fR regexp
+modifier (possibly in combination with \f(CW\*(C`/s\*(C'\fR). This can be set
+on a per match bases, or can be enabled per lexical scope (including
+a whole file) with \f(CW\*(C`use re \*(Aq/m\*(Aq\*(C'\fR.
+.PP
+\fR\f(CI$#\fR\fI is no longer supported\fR
+.IX Subsection "$# is no longer supported"
+.PP
+This variable used to have a special meaning \-\- it could be used
+to control how numbers were formatted when printed. This seldom
+used functionality was removed in Perl 5.10. In order to free up
+the variable for a future special meaning, its use became a fatal
+error in Perl 5.30.
+.PP
+To specify how numbers are formatted when printed, one is advised
+to use \f(CW\*(C`printf\*(C'\fR or \f(CW\*(C`sprintf\*(C'\fR instead.
+.PP
+\fIAssigning non-zero to \fR\f(CI$[\fR\fI is fatal\fR
+.IX Subsection "Assigning non-zero to $[ is fatal"
+.PP
+This variable (and the corresponding \f(CW\*(C`array_base\*(C'\fR feature and
+arybase module) allowed changing the base for array and string
+indexing operations.
+.PP
+Setting this to a non-zero value has been deprecated since Perl 5.12 and
+throws a fatal error as of Perl 5.30.
+.PP
+\fR\f(CIFile::Glob::glob()\fR\fI will disappear\fR
+.IX Subsection "File::Glob::glob() will disappear"
+.PP
+\&\f(CW\*(C`File::Glob\*(C'\fR has a function called \f(CW\*(C`glob\*(C'\fR, which just calls
+\&\f(CW\*(C`bsd_glob\*(C'\fR. However, its prototype is different from the prototype
+of \f(CW\*(C`CORE::glob\*(C'\fR, and hence, \f(CW\*(C`File::Glob::glob\*(C'\fR should not
+be used.
+.PP
+\&\f(CWFile::Glob::glob()\fR was deprecated in Perl 5.8. A deprecation
+message was issued from Perl 5.26 onwards, and in Perl 5.30 this was
+turned into a fatal error.
+.PP
+Code using \f(CWFile::Glob::glob()\fR should call
+\&\f(CWFile::Glob::bsd_glob()\fR instead.
+.PP
+\fIUnescaped left braces in regular expressions (for 5.30)\fR
+.IX Subsection "Unescaped left braces in regular expressions (for 5.30)"
+.PP
+See "Unescaped left braces in regular expressions" above.
+.PP
+\fIUnqualified \fR\f(CIdump()\fR
+.IX Subsection "Unqualified dump()"
+.PP
+Use of \f(CWdump()\fR instead of \f(CWCORE::dump()\fR was deprecated in Perl 5.8,
+and an unqualified \f(CWdump()\fR is no longer available as of Perl 5.30.
+.PP
+See "dump" in perlfunc.
+.PP
+\fIUsing \fR\f(BImy()\fR\fI in false conditional.\fR
+.IX Subsection "Using my() in false conditional."
+.PP
+There has been a long-standing bug in Perl that causes a lexical variable
+not to be cleared at scope exit when its declaration includes a false
+conditional.  Some people have exploited this bug to achieve a kind of
+static variable.  To allow us to fix this bug, people should not be
+relying on this behavior.
+.PP
+Instead, it's recommended one uses \f(CW\*(C`state\*(C'\fR variables to achieve the
+same effect:
+.PP
+.Vb 4
+\&    use 5.10.0;
+\&    sub count {state $counter; return ++ $counter}
+\&    say count ();    # Prints 1
+\&    say count ();    # Prints 2
+.Ve
+.PP
+\&\f(CW\*(C`state\*(C'\fR variables were introduced in Perl 5.10.
+.PP
+Alternatively, you can achieve a similar static effect by
+declaring the variable in a separate block outside the function, e.g.,
+.PP
+.Vb 1
+\&    sub f { my $x if 0; return $x++ }
+.Ve
+.PP
+becomes
+.PP
+.Vb 1
+\&    { my $x; sub f { return $x++ } }
+.Ve
+.PP
+The use of \f(CWmy()\fR in a false conditional has been deprecated in
+Perl 5.10, and became a fatal error in Perl 5.30.
+.PP
+\fIReading/writing bytes from/to :utf8 handles.\fR
+.IX Subsection "Reading/writing bytes from/to :utf8 handles."
+.PP
+The \fBsysread()\fR, \fBrecv()\fR, \fBsyswrite()\fR and \fBsend()\fR operators are
+deprecated on handles that have the \f(CW\*(C`:utf8\*(C'\fR layer, either explicitly, or
+implicitly, eg., with the \f(CW:encoding(UTF\-16LE)\fR layer.
+.PP
+Both \fBsysread()\fR and \fBrecv()\fR currently use only the \f(CW\*(C`:utf8\*(C'\fR flag for the stream,
+ignoring the actual layers.  Since \fBsysread()\fR and \fBrecv()\fR do no UTF\-8
+validation they can end up creating invalidly encoded scalars.
+.PP
+Similarly, \fBsyswrite()\fR and \fBsend()\fR use only the \f(CW\*(C`:utf8\*(C'\fR flag, otherwise ignoring
+any layers.  If the flag is set, both write the value UTF\-8 encoded, even if
+the layer is some different encoding, such as the example above.
+.PP
+Ideally, all of these operators would completely ignore the \f(CW\*(C`:utf8\*(C'\fR state,
+working only with bytes, but this would result in silently breaking existing
+code.  To avoid this a future version of perl will throw an exception when
+any of \fBsysread()\fR, \fBrecv()\fR, \fBsyswrite()\fR or \fBsend()\fR are called on handle with the
+\&\f(CW\*(C`:utf8\*(C'\fR layer.
+.PP
+As of Perl 5.30, it is no longer be possible to use \fBsysread()\fR, \fBrecv()\fR,
+\&\fBsyswrite()\fR or \fBsend()\fR to read or send bytes from/to :utf8 handles.
+.PP
+\fIUse of unassigned code point or non-standalone grapheme for a delimiter.\fR
+.IX Subsection "Use of unassigned code point or non-standalone grapheme for a delimiter."
+.PP
+A grapheme is what appears to a native-speaker of a language to be a
+character.  In Unicode (and hence Perl) a grapheme may actually be
+several adjacent characters that together form a complete grapheme.  For
+example, there can be a base character, like "R" and an accent, like a
+circumflex "^", that appear to be a single character when displayed,
+with the circumflex hovering over the "R".
+.PP
+As of Perl 5.30, use of delimiters which are non-standalone graphemes is
+fatal, in order to move the language to be able to accept
+multi-character graphemes as delimiters.
+.PP
+Also, as of Perl 5.30, delimiters which are unassigned code points
+but that may someday become assigned are prohibited.  Otherwise, code
+that works today would fail to compile if the currently unassigned
+delimiter ends up being something that isn't a stand-alone grapheme.
+Because Unicode is never going to assign non-character code
+points, nor code points that are
+above the legal Unicode maximum, those can be delimiters.
+.SS "Perl 5.28"
+.IX Subsection "Perl 5.28"
+\fIAttributes \fR\f(CI\*(C`:locked\*(C'\fR\fI and \fR\f(CI\*(C`:unique\*(C'\fR
+.IX Subsection "Attributes :locked and :unique"
+.PP
+The attributes \f(CW\*(C`:locked\*(C'\fR (on code references) and \f(CW\*(C`:unique\*(C'\fR
+(on array, hash and scalar references) have had no effect since 
+Perl 5.005 and Perl 5.8.8 respectively. Their use has been deprecated
+since.
+.PP
+As of Perl 5.28, these attributes are syntax errors. Since the
+attributes do not do anything, removing them from your code fixes
+the syntax error; and removing them will not influence the behaviour
+of your code.
+.PP
+\fIBare here-document terminators\fR
+.IX Subsection "Bare here-document terminators"
+.PP
+Perl has allowed you to use a bare here-document terminator to have the
+here-document end at the first empty line. This practise was deprecated
+in Perl 5.000; as of Perl 5.28, using a bare here-document terminator
+throws a fatal error.
+.PP
+You are encouraged to use the explicitly quoted form if you wish to
+use an empty line as the terminator of the here-document:
+.PP
+.Vb 2
+\&  print <<"";
+\&    Print this line.
+\&
+\&  # Previous blank line ends the here\-document.
+.Ve
+.PP
+\fISetting $/ to a reference to a non-positive integer\fR
+.IX Subsection "Setting $/ to a reference to a non-positive integer"
+.PP
+You assigned a reference to a scalar to \f(CW$/\fR where the
+referenced item is not a positive integer.  In older perls this \fBappeared\fR
+to work the same as setting it to \f(CW\*(C`undef\*(C'\fR but was in fact internally
+different, less efficient and with very bad luck could have resulted in
+your file being split by a stringified form of the reference.
+.PP
+In Perl 5.20.0 this was changed so that it would be \fBexactly\fR the same as
+setting \f(CW$/\fR to undef, with the exception that this warning would be
+thrown.
+.PP
+As of Perl 5.28, setting \f(CW$/\fR to a reference of a non-positive
+integer throws a fatal error.
+.PP
+You are recommended to change your code to set \f(CW$/\fR to \f(CW\*(C`undef\*(C'\fR explicitly
+if you wish to slurp the file.
+.PP
+\fILimit on the value of Unicode code points.\fR
+.IX Subsection "Limit on the value of Unicode code points."
+.PP
+Unicode only allows code points up to 0x10FFFF, but Perl allows
+much larger ones. Up till Perl 5.28, it was allowed to use code
+points exceeding the maximum value of an integer (\f(CW\*(C`IV_MAX\*(C'\fR).
+However, that did break the perl interpreter in some constructs,
+including causing it to hang in a few cases.  The known problem
+areas were in \f(CW\*(C`tr///\*(C'\fR, regular expression pattern matching using
+quantifiers, as quote delimiters in \f(CW\*(C`q\fR\f(CIX\fR\f(CW...\fR\f(CIX\fR\f(CW\*(C'\fR (where \fIX\fR is
+the \f(CWchr()\fR of a large code point), and as the upper limits in
+loops.
+.PP
+The use of out of range code points was deprecated in Perl 5.24; as of
+Perl 5.28 using a code point exceeding \f(CW\*(C`IV_MAX\*(C'\fR throws a fatal error.
+.PP
+If your code is to run on various platforms, keep in mind that the upper
+limit depends on the platform. It is much larger on 64\-bit word sizes
+than 32\-bit ones. For 32\-bit integers, \f(CW\*(C`IV_MAX\*(C'\fR equals \f(CW0x7FFFFFFF\fR,
+for 64\-bit integers, \f(CW\*(C`IV_MAX\*(C'\fR equals \f(CW0x7FFFFFFFFFFFFFFF\fR.
+.PP
+\fIUse of comma-less variable list in formats.\fR
+.IX Subsection "Use of comma-less variable list in formats."
+.PP
+It was allowed to use a list of variables in a format, without
+separating them with commas. This usage has been deprecated
+for a long time, and as of Perl 5.28, this throws a fatal error.
+.PP
+\fIUse of \fR\f(CI\*(C`\eN{}\*(C'\fR
+.IX Subsection "Use of N{}"
+.PP
+Use of \f(CW\*(C`\eN{}\*(C'\fR with nothing between the braces was deprecated in
+Perl 5.24, and throws a fatal error as of Perl 5.28.
+.PP
+Since such a construct is equivalent to using an empty string,
+you are recommended to remove such \f(CW\*(C`\eN{}\*(C'\fR constructs.
+.PP
+\fIUsing the same symbol to open a filehandle and a dirhandle\fR
+.IX Subsection "Using the same symbol to open a filehandle and a dirhandle"
+.PP
+It used to be legal to use \f(CWopen()\fR to associate both a
+filehandle and a dirhandle to the same symbol (glob or scalar).
+This idiom is likely to be confusing, and it was deprecated in
+Perl 5.10.
+.PP
+Using the same symbol to \f(CWopen()\fR a filehandle and a dirhandle
+throws a fatal error as of Perl 5.28.
+.PP
+You should be using two different symbols instead.
+.PP
+\fI${^ENCODING} is no longer supported.\fR
+.IX Subsection "${^ENCODING} is no longer supported."
+.PP
+The special variable \f(CW\*(C`${^ENCODING}\*(C'\fR was used to implement
+the \f(CW\*(C`encoding\*(C'\fR pragma. Setting this variable to anything other
+than \f(CW\*(C`undef\*(C'\fR was deprecated in Perl 5.22. Full deprecation
+of the variable happened in Perl 5.25.3.
+.PP
+Setting this variable to anything other than an undefined value
+throws a fatal error as of Perl 5.28.
+.PP
+\fR\f(CI\*(C`B::OP::terse\*(C'\fR\fI\fR
+.IX Subsection "B::OP::terse"
+.PP
+This method, which just calls \f(CW\*(C`B::Concise::b_terse\*(C'\fR, has been
+deprecated, and disappeared in Perl 5.28. Please use 
+\&\f(CW\*(C`B::Concise\*(C'\fR instead.
+.PP
+\fIUse of inherited AUTOLOAD for non-method \fR\f(CI%s::\fR\fI%s() is no longer allowed\fR
+.IX Subsection "Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed"
+.PP
+As an (ahem) accidental feature, \f(CW\*(C`AUTOLOAD\*(C'\fR subroutines were looked
+up as methods (using the \f(CW@ISA\fR hierarchy) even when the subroutines
+to be autoloaded were called as plain functions (e.g. \f(CWFoo::bar()\fR),
+not as methods (e.g. \f(CW\*(C`Foo\->bar()\*(C'\fR or \f(CW\*(C`$obj\->bar()\*(C'\fR).
+.PP
+This bug was deprecated in Perl 5.004, has been rectified in Perl 5.28
+by using method lookup only for methods' \f(CW\*(C`AUTOLOAD\*(C'\fRs.
+.PP
+The simple rule is:  Inheritance will not work when autoloading
+non-methods.  The simple fix for old code is:  In any module that used
+to depend on inheriting \f(CW\*(C`AUTOLOAD\*(C'\fR for non-methods from a base class
+named \f(CW\*(C`BaseClass\*(C'\fR, execute \f(CW\*(C`*AUTOLOAD = \e&BaseClass::AUTOLOAD\*(C'\fR during
+startup.
+.PP
+In code that currently says \f(CW\*(C`use AutoLoader; @ISA = qw(AutoLoader);\*(C'\fR
+you should remove AutoLoader from \f(CW@ISA\fR and change \f(CW\*(C`use AutoLoader;\*(C'\fR to
+\&\f(CW\*(C`use AutoLoader \*(AqAUTOLOAD\*(Aq;\*(C'\fR.
+.PP
+\fIUse of code points over 0xFF in string bitwise operators\fR
+.IX Subsection "Use of code points over 0xFF in string bitwise operators"
+.PP
+The string bitwise operators, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR, treat
+their operands as strings of bytes. As such, values above 0xFF 
+are nonsensical. Using such code points with these operators
+was deprecated in Perl 5.24, and is fatal as of Perl 5.28.
+.PP
+\fIIn XS code, use of \fR\f(CIto_utf8_case()\fR
+.IX Subsection "In XS code, use of to_utf8_case()"
+.PP
+This function has been removed as of Perl 5.28; instead convert to call
+the appropriate one of:
+\&\f(CW\*(C`toFOLD_utf8_safe\*(C'\fR.
+\&\f(CW\*(C`toLOWER_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`toTITLE_utf8_safe\*(C'\fR,
+or
+\&\f(CW\*(C`toUPPER_utf8_safe\*(C'\fR.
+.SS "Perl 5.26"
+.IX Subsection "Perl 5.26"
+\fR\f(CI\*(C`\-\-libpods\*(C'\fR\fI in \fR\f(CI\*(C`Pod::Html\*(C'\fR\fI\fR
+.IX Subsection "--libpods in Pod::Html"
+.PP
+Since Perl 5.18, the option \f(CW\*(C`\-\-libpods\*(C'\fR has been deprecated, and
+using this option did not do anything other than producing a warning.
+.PP
+The \f(CW\*(C`\-\-libpods\*(C'\fR option is no longer recognized as of Perl 5.26.
+.PP
+\fIThe utilities \fR\f(CI\*(C`c2ph\*(C'\fR\fI and \fR\f(CI\*(C`pstruct\*(C'\fR
+.IX Subsection "The utilities c2ph and pstruct"
+.PP
+These old, perl3\-era utilities have been deprecated in favour of
+\&\f(CW\*(C`h2xs\*(C'\fR for a long time. As of Perl 5.26, they have been removed.
+.PP
+\fITrapping \fR\f(CI\*(C`$SIG {_\|_DIE_\|_}\*(C'\fR\fI other than during program exit.\fR
+.IX Subsection "Trapping $SIG {__DIE__} other than during program exit."
+.PP
+The \f(CW$SIG{_\|_DIE_\|_}\fR hook is called even inside an \f(CWeval()\fR. It was
+never intended to happen this way, but an implementation glitch made
+this possible. This used to be deprecated, as it allowed strange action
+at a distance like rewriting a pending exception in \f(CW$@\fR. Plans to
+rectify this have been scrapped, as users found that rewriting a
+pending exception is actually a useful feature, and not a bug.
+.PP
+Perl never issued a deprecation warning for this; the deprecation
+was by documentation policy only. But this deprecation has been 
+lifted as of Perl 5.26.
+.PP
+\fIMalformed UTF\-8 string in "%s"\fR
+.IX Subsection "Malformed UTF-8 string in ""%s"""
+.PP
+This message indicates a bug either in the Perl core or in XS
+code. Such code was trying to find out if a character, allegedly
+stored internally encoded as UTF\-8, was of a given type, such as
+being punctuation or a digit.  But the character was not encoded
+in legal UTF\-8.  The \f(CW%s\fR is replaced by a string that can be used
+by knowledgeable people to determine what the type being checked
+against was.
+.PP
+Passing malformed strings was deprecated in Perl 5.18, and
+became fatal in Perl 5.26.
+.SS "Perl 5.24"
+.IX Subsection "Perl 5.24"
+\fIUse of \fR\f(CI*glob{FILEHANDLE}\fR
+.IX Subsection "Use of *glob{FILEHANDLE}"
+.PP
+The use of \f(CW*glob{FILEHANDLE}\fR was deprecated in Perl 5.8.
+The intention was to use \f(CW*glob{IO}\fR instead, for which 
+\&\f(CW*glob{FILEHANDLE}\fR is an alias.
+.PP
+However, this feature was undeprecated in Perl 5.24.
+.PP
+\fICalling POSIX::%s() is deprecated\fR
+.IX Subsection "Calling POSIX::%s() is deprecated"
+.PP
+The following functions in the \f(CW\*(C`POSIX\*(C'\fR module are no longer available:
+\&\f(CW\*(C`isalnum\*(C'\fR, \f(CW\*(C`isalpha\*(C'\fR, \f(CW\*(C`iscntrl\*(C'\fR, \f(CW\*(C`isdigit\*(C'\fR, \f(CW\*(C`isgraph\*(C'\fR, \f(CW\*(C`islower\*(C'\fR,  
+\&\f(CW\*(C`isprint\*(C'\fR, \f(CW\*(C`ispunct\*(C'\fR, \f(CW\*(C`isspace\*(C'\fR, \f(CW\*(C`isupper\*(C'\fR, and \f(CW\*(C`isxdigit\*(C'\fR.  The 
+functions are buggy and don't work on UTF\-8 encoded strings.  See their
+entries in POSIX for more information.
+.PP
+The functions were deprecated in Perl 5.20, and removed in Perl 5.24.
+.SS "Perl 5.16"
+.IX Subsection "Perl 5.16"
+\fIUse of \fR\f(CI%s\fR\fI on a handle without * is deprecated\fR
+.IX Subsection "Use of %s on a handle without * is deprecated"
+.PP
+It used to be possible to use \f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR or \f(CW\*(C`untie\*(C'\fR on a scalar
+while the scalar holds a typeglob. This caused its filehandle to be
+tied. It left no way to tie the scalar itself when it held a typeglob,
+and no way to untie a scalar that had had a typeglob assigned to it.
+.PP
+This was deprecated in Perl 5.14, and the bug was fixed in Perl 5.16.
+.PP
+So now \f(CW\*(C`tie $scalar\*(C'\fR will always tie the scalar, not the handle it holds.
+To tie the handle, use \f(CW\*(C`tie *$scalar\*(C'\fR (with an explicit asterisk).  The same
+applies to \f(CW\*(C`tied *$scalar\*(C'\fR and \f(CW\*(C`untie *$scalar\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+warnings, diagnostics.
diff --git a/upstream/mageia-cauldron/man1/perldiag.1 b/upstream/mageia-cauldron/man1/perldiag.1
new file mode 100644
index 00000000..897d7513
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldiag.1
@@ -0,0 +1,7817 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDIAG 1"
+.TH PERLDIAG 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldiag \- various Perl diagnostics
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+These messages are classified as follows (listed in increasing order of
+desperation):
+.PP
+.Vb 7
+\&    (W) A warning (optional).
+\&    (D) A deprecation (enabled by default).
+\&    (S) A severe warning (enabled by default).
+\&    (F) A fatal error (trappable).
+\&    (P) An internal error you should never see (trappable).
+\&    (X) A very fatal error (nontrappable).
+\&    (A) An alien error message (not generated by Perl).
+.Ve
+.PP
+The majority of messages from the first three classifications above
+(W, D & S) can be controlled using the \f(CW\*(C`warnings\*(C'\fR pragma.
+.PP
+If a message can be controlled by the \f(CW\*(C`warnings\*(C'\fR pragma, its warning
+category is included with the classification letter in the description
+below.  E.g. \f(CW\*(C`(W closed)\*(C'\fR means a warning in the \f(CW\*(C`closed\*(C'\fR category.
+.PP
+Optional warnings are enabled by using the \f(CW\*(C`warnings\*(C'\fR pragma or the \fB\-w\fR
+and \fB\-W\fR switches.  Warnings may be captured by setting \f(CW$SIG{_\|_WARN_\|_}\fR
+to a reference to a routine that will be called on each warning instead
+of printing it.  See perlvar.
+.PP
+Severe warnings are always enabled, unless they are explicitly disabled
+with the \f(CW\*(C`warnings\*(C'\fR pragma or the \fB\-X\fR switch.
+.PP
+Trappable errors may be trapped using the eval operator.  See
+"eval" in perlfunc.  In almost all cases, warnings may be selectively
+disabled or promoted to fatal errors using the \f(CW\*(C`warnings\*(C'\fR pragma.
+See warnings.
+.PP
+The messages are in alphabetical order, without regard to upper or
+lower-case.  Some of these messages are generic.  Spots that vary are
+denoted with a \f(CW%s\fR or other printf-style escape.  These escapes are
+ignored by the alphabetical order, as are all characters other than
+letters.  To look up your message, just ignore anything that is not a
+letter.
+.ie n .IP "\fBaccept()\fR on closed socket %s" 4
+.el .IP "\fBaccept()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "accept() on closed socket %s"
+(W closed) You tried to do an accept on a closed socket.  Did you forget
+to check the return value of your \fBsocket()\fR call?  See
+"accept" in perlfunc.
+.IP "ADJUST is experimental" 4
+.IX Item "ADJUST is experimental"
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`ADJUST\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP "Aliasing via reference is experimental" 4
+.IX Item "Aliasing via reference is experimental"
+(S experimental::refaliasing) This warning is emitted if you use
+a reference constructor on the left-hand side of an assignment to
+alias one variable to another.  Simply suppress the warning if you
+want to use the feature, but know that in doing so you are taking
+the risk of using an experimental feature which may change or be
+removed in a future Perl version:
+.Sp
+.Vb 3
+\&    no warnings "experimental::refaliasing";
+\&    use feature "refaliasing";
+\&    \e$x = \e$y;
+.Ve
+.ie n .IP "'%c' allowed only after types %s in %s" 4
+.el .IP "'%c' allowed only after types \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "'%c' allowed only after types %s in %s"
+(F) The modifiers '!', '<' and '>' are allowed in \fBpack()\fR or \fBunpack()\fR only
+after certain types.  See "pack" in perlfunc.
+.IP "alpha\->\fBnumify()\fR is lossy" 4
+.IX Item "alpha->numify() is lossy"
+(W numeric) An alpha version can not be numified without losing
+information.
+.IP "Ambiguous call resolved as CORE::%s(), qualify as such or use &" 4
+.IX Item "Ambiguous call resolved as CORE::%s(), qualify as such or use &"
+(W ambiguous) A subroutine you have declared has the same name as a Perl
+keyword, and you have used the name without qualification for calling
+one or the other.  Perl decided to call the builtin because the
+subroutine is not imported.
+.Sp
+To force interpretation as a subroutine call, either put an ampersand
+before the subroutine name, or qualify the name with its package.
+Alternatively, you can import the subroutine (or pretend that it's
+imported with the \f(CW\*(C`use subs\*(C'\fR pragma).
+.Sp
+To silently interpret it as the Perl operator, use the \f(CW\*(C`CORE::\*(C'\fR prefix
+on the operator (e.g. \f(CWCORE::log($x)\fR) or declare the subroutine
+to be an object method (see "Subroutine Attributes" in perlsub or
+attributes).
+.IP "Ambiguous range in transliteration operator" 4
+.IX Item "Ambiguous range in transliteration operator"
+(F) You wrote something like \f(CW\*(C`tr/a\-z\-0//\*(C'\fR which doesn't mean anything at
+all.  To include a \f(CW\*(C`\-\*(C'\fR character in a transliteration, put it either
+first or last.  (In the past, \f(CW\*(C`tr/a\-z\-0//\*(C'\fR was synonymous with
+\&\f(CW\*(C`tr/a\-y//\*(C'\fR, which was probably not what you would have expected.)
+.ie n .IP "Ambiguous use of %s resolved as %s" 4
+.el .IP "Ambiguous use of \f(CW%s\fR resolved as \f(CW%s\fR" 4
+.IX Item "Ambiguous use of %s resolved as %s"
+(S ambiguous) You said something that may not be interpreted the way
+you thought.  Normally it's pretty easy to disambiguate it by supplying
+a missing quote, operator, parenthesis pair or declaration.
+.IP "Ambiguous use of \-%s resolved as \-&%s()" 4
+.IX Item "Ambiguous use of -%s resolved as -&%s()"
+(S ambiguous) You wrote something like \f(CW\*(C`\-foo\*(C'\fR, which might be the
+string \f(CW"\-foo"\fR, or a call to the function \f(CW\*(C`foo\*(C'\fR, negated.  If you meant
+the string, just write \f(CW"\-foo"\fR.  If you meant the function call,
+write \f(CW\*(C`\-foo()\*(C'\fR.
+.ie n .IP "Ambiguous use of %c resolved as operator %c" 4
+.el .IP "Ambiguous use of \f(CW%c\fR resolved as operator \f(CW%c\fR" 4
+.IX Item "Ambiguous use of %c resolved as operator %c"
+(S ambiguous) \f(CW\*(C`%\*(C'\fR, \f(CW\*(C`&\*(C'\fR, and \f(CW\*(C`*\*(C'\fR are both infix operators (modulus,
+bitwise and, and multiplication) \fIand\fR initial special characters
+(denoting hashes, subroutines and typeglobs), and you said something
+like \f(CW\*(C`*foo * foo\*(C'\fR that might be interpreted as either of them.  We
+assumed you meant the infix operator, but please try to make it more
+clear \-\- in the example given, you might write \f(CW\*(C`*foo * foo()\*(C'\fR if you
+really meant to multiply a glob by the result of calling a function.
+.ie n .IP "Ambiguous use of %c{%s} resolved to %c%s" 4
+.el .IP "Ambiguous use of \f(CW%c\fR{%s} resolved to \f(CW%c\fR%s" 4
+.IX Item "Ambiguous use of %c{%s} resolved to %c%s"
+(W ambiguous) You wrote something like \f(CW\*(C`@{foo}\*(C'\fR, which might be
+asking for the variable \f(CW@foo\fR, or it might be calling a function
+named foo, and dereferencing it as an array reference.  If you wanted
+the variable, you can just write \f(CW@foo\fR.  If you wanted to call the
+function, write \f(CW\*(C`@{foo()}\*(C'\fR ... or you could just not have a variable
+and a function with the same name, and save yourself a lot of trouble.
+.ie n .IP "Ambiguous use of %c{%s[...]} resolved to %c%s[...]" 4
+.el .IP "Ambiguous use of \f(CW%c\fR{%s[...]} resolved to \f(CW%c\fR%s[...]" 4
+.IX Item "Ambiguous use of %c{%s[...]} resolved to %c%s[...]"
+.PD 0
+.ie n .IP "Ambiguous use of %c{%s{...}} resolved to %c%s{...}" 4
+.el .IP "Ambiguous use of \f(CW%c\fR{%s{...}} resolved to \f(CW%c\fR%s{...}" 4
+.IX Item "Ambiguous use of %c{%s{...}} resolved to %c%s{...}"
+.PD
+(W ambiguous) You wrote something like \f(CW\*(C`${foo[2]}\*(C'\fR (where foo represents
+the name of a Perl keyword), which might be looking for element number
+2 of the array named \f(CW@foo\fR, in which case please write \f(CW$foo[2]\fR, or you
+might have meant to pass an anonymous arrayref to the function named
+foo, and then do a scalar deref on the value it returns.  If you meant
+that, write \f(CW\*(C`${foo([2])}\*(C'\fR.
+.Sp
+In regular expressions, the \f(CW\*(C`${foo[2]}\*(C'\fR syntax is sometimes necessary
+to disambiguate between array subscripts and character classes.
+\&\f(CW\*(C`/$length[2345]/\*(C'\fR, for instance, will be interpreted as \f(CW$length\fR followed
+by the character class \f(CW\*(C`[2345]\*(C'\fR.  If an array subscript is what you
+want, you can avoid the warning by changing \f(CW\*(C`/${length[2345]}/\*(C'\fR to the
+unsightly \f(CW\*(C`/${\e$length[2345]}/\*(C'\fR, by renaming your array to something
+that does not coincide with a built-in keyword, or by simply turning
+off warnings with \f(CW\*(C`no warnings \*(Aqambiguous\*(Aq;\*(C'\fR.
+.IP "'|' and '<' may not both be specified on command line" 4
+.IX Item "'|' and '<' may not both be specified on command line"
+(F) An error peculiar to VMS.  Perl does its own command line
+redirection, and found that STDIN was a pipe, and that you also tried to
+redirect STDIN using '<'.  Only one STDIN stream to a customer, please.
+.IP "'|' and '>' may not both be specified on command line" 4
+.IX Item "'|' and '>' may not both be specified on command line"
+(F) An error peculiar to VMS.  Perl does its own command line
+redirection, and thinks you tried to redirect stdout both to a file and
+into a pipe to another command.  You need to choose one or the other,
+though nothing's stopping you from piping into a program or Perl script
+which 'splits' output into two streams, such as
+.Sp
+.Vb 6
+\&    open(OUT,">$ARGV[0]") or die "Can\*(Aqt write to $ARGV[0]: $!";
+\&    while (<STDIN>) {
+\&        print;
+\&        print OUT;
+\&    }
+\&    close OUT;
+.Ve
+.ie n .IP "Applying %s to %s will act on scalar(%s)" 4
+.el .IP "Applying \f(CW%s\fR to \f(CW%s\fR will act on scalar(%s)" 4
+.IX Item "Applying %s to %s will act on scalar(%s)"
+(W misc) The pattern match (\f(CW\*(C`//\*(C'\fR), substitution (\f(CW\*(C`s///\*(C'\fR), and
+transliteration (\f(CW\*(C`tr///\*(C'\fR) operators work on scalar values.  If you apply
+one of them to an array or a hash, it will convert the array or hash to
+a scalar value (the length of an array, or the population info of a
+hash) and then work on that scalar value.  This is probably not what
+you meant to do.  See "grep" in perlfunc and "map" in perlfunc for
+alternatives.
+.IP "Arg too short for msgsnd" 4
+.IX Item "Arg too short for msgsnd"
+(F) \fBmsgsnd()\fR requires a string at least as long as sizeof(long).
+.IP "Argument ""%s"" isn't numeric%s" 4
+.IX Item "Argument ""%s"" isn't numeric%s"
+(W numeric) The indicated string was fed as an argument to an operator
+that expected a numeric value instead.  If you're fortunate the message
+will identify which operator was so unfortunate.
+.Sp
+Note that for the \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR (infinity and not-a-number) the
+definition of "numeric" is somewhat unusual: the strings themselves
+(like "Inf") are considered numeric, and anything following them is
+considered non-numeric.
+.IP "Argument list not closed for PerlIO layer ""%s""" 4
+.IX Item "Argument list not closed for PerlIO layer ""%s"""
+(W layer) When pushing a layer with arguments onto the Perl I/O
+system you forgot the ) that closes the argument list.  (Layers
+take care of transforming data between external and internal
+representations.)  Perl stopped parsing the layer list at this
+point and did not attempt to push this layer.  If your program
+didn't explicitly request the failing operation, it may be the
+result of the value of the environment variable PERLIO.
+.IP "Argument ""%s"" treated as 0 in increment (++)" 4
+.IX Item "Argument ""%s"" treated as 0 in increment (++)"
+(W numeric) The indicated string was fed as an argument to the \f(CW\*(C`++\*(C'\fR
+operator which expects either a number or a string matching
+\&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR.  See "Auto-increment and
+Auto-decrement" in perlop for details.
+.IP "Array passed to stat will be coerced to a scalar%s" 4
+.IX Item "Array passed to stat will be coerced to a scalar%s"
+(W syntax) You called \fBstat()\fR on an array, but the array will be
+coerced to a scalar \- the number of elements in the array.
+.IP "A signature parameter must start with '$', '@' or '%'" 4
+.IX Item "A signature parameter must start with '$', '@' or '%'"
+(F) Each subroutine signature parameter declaration must start with a valid
+sigil; for example:
+.Sp
+.Vb 1
+\&    sub foo ($a, $, $b = 1, @c) {}
+.Ve
+.IP "A slurpy parameter may not have a default value" 4
+.IX Item "A slurpy parameter may not have a default value"
+(F) Only scalar subroutine signature parameters may have a default value;
+for example:
+.Sp
+.Vb 3
+\&    sub foo ($a = 1)        {} # legal
+\&    sub foo (@a = (1))      {} # invalid
+\&    sub foo (%a = (a => b)) {} # invalid
+.Ve
+.ie n .IP "assertion botched: %s" 4
+.el .IP "assertion botched: \f(CW%s\fR" 4
+.IX Item "assertion botched: %s"
+(X) The malloc package that comes with Perl had an internal failure.
+.ie n .IP "Assertion %s failed: file ""%s"", line %d" 4
+.el .IP "Assertion \f(CW%s\fR failed: file ""%s"", line \f(CW%d\fR" 4
+.IX Item "Assertion %s failed: file ""%s"", line %d"
+(X) A general assertion failed.  The file in question must be examined.
+.IP "Assigned value is not a reference" 4
+.IX Item "Assigned value is not a reference"
+(F) You tried to assign something that was not a reference to an lvalue
+reference (e.g., \f(CW\*(C`\e$x = $y\*(C'\fR).  If you meant to make \f(CW$x\fR an alias to \f(CW$y\fR, use
+\&\f(CW\*(C`\e$x = \e$y\*(C'\fR.
+.ie n .IP "Assigned value is not %s reference" 4
+.el .IP "Assigned value is not \f(CW%s\fR reference" 4
+.IX Item "Assigned value is not %s reference"
+(F) You tried to assign a reference to a reference constructor, but the
+two references were not of the same type.  You cannot alias a scalar to
+an array, or an array to a hash; the two types must match.
+.Sp
+.Vb 4
+\&    \e$x = \e@y;  # error
+\&    \e@x = \e%y;  # error
+\&     $y = [];
+\&    \e$x = $y;   # error; did you mean \e$y?
+.Ve
+.IP "Assigning non-zero to $[ is no longer possible" 4
+.IX Item "Assigning non-zero to $[ is no longer possible"
+(F) When the "array_base" feature is disabled
+(e.g., and under \f(CW\*(C`use v5.16;\*(C'\fR, and as of Perl 5.30)
+the special variable \f(CW$[\fR, which is deprecated, is now a fixed zero value.
+.IP "Assignment to both a list and a scalar" 4
+.IX Item "Assignment to both a list and a scalar"
+(F) If you assign to a conditional operator, the 2nd and 3rd arguments
+must either both be scalars or both be lists.  Otherwise Perl won't
+know which context to supply to the right side.
+.ie n .IP "Assuming NOT a POSIX class since %s in regex; marked by <\-\-\ HERE in m/%s/" 4
+.el .IP "Assuming NOT a POSIX class since \f(CW%s\fR in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Assuming NOT a POSIX class since %s in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You had something like these:
+.Sp
+.Vb 2
+\& [[:alnum]]
+\& [[:digit:xyz]
+.Ve
+.Sp
+They look like they might have been meant to be the POSIX classes
+\&\f(CW\*(C`[:alnum:]\*(C'\fR or \f(CW\*(C`[:digit:]\*(C'\fR.  If so, they should be written:
+.Sp
+.Vb 2
+\& [[:alnum:]]
+\& [[:digit:]xyz]
+.Ve
+.Sp
+Since these aren't legal POSIX class specifications, but are legal
+bracketed character classes, Perl treats them as the latter.  In the
+first example, it matches the characters \f(CW":"\fR, \f(CW"["\fR, \f(CW"a"\fR, \f(CW"l"\fR,
+\&\f(CW"m"\fR, \f(CW"n"\fR, and \f(CW"u"\fR.
+.Sp
+If these weren't meant to be POSIX classes, this warning message is
+spurious, and can be suppressed by reordering things, such as
+.Sp
+.Vb 1
+\& [[al:num]]
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\& [[:munla]]
+.Ve
+.IP "<> at require-statement should be quotes" 4
+.IX Item "<> at require-statement should be quotes"
+(F) You wrote \f(CW\*(C`require <file>\*(C'\fR when you should have written
+\&\f(CW\*(C`require \*(Aqfile\*(Aq\*(C'\fR.
+.IP "Attempt to access disallowed key '%s' in a restricted hash" 4
+.IX Item "Attempt to access disallowed key '%s' in a restricted hash"
+(F) The failing code has attempted to get or set a key which is not in
+the current set of allowed keys of a restricted hash.
+.IP "Attempt to bless into a freed package" 4
+.IX Item "Attempt to bless into a freed package"
+(F) You wrote \f(CW\*(C`bless $foo\*(C'\fR with one argument after somehow causing
+the current package to be freed.  Perl cannot figure out what to
+do, so it throws up its hands in despair.
+.IP "Attempt to bless into a class" 4
+.IX Item "Attempt to bless into a class"
+(F) You are attempting to call \f(CW\*(C`bless\*(C'\fR with a package name that is a
+new-style \f(CW\*(C`class\*(C'\fR.  This is not necessary, as instances created by the
+constructor are already in the correct class.  Instances cannot be created
+by other means, such as \f(CW\*(C`bless\*(C'\fR.
+.IP "Attempt to bless into a reference" 4
+.IX Item "Attempt to bless into a reference"
+(F) The CLASSNAME argument to the \fBbless()\fR operator is expected to be
+the name of the package to bless the resulting object into.  You've
+supplied instead a reference to something: perhaps you wrote
+.Sp
+.Vb 1
+\&    bless $self, $proto;
+.Ve
+.Sp
+when you intended
+.Sp
+.Vb 1
+\&    bless $self, ref($proto) || $proto;
+.Ve
+.Sp
+If you actually want to bless into the stringified version
+of the reference supplied, you need to stringify it yourself, for
+example by:
+.Sp
+.Vb 1
+\&    bless $self, "$proto";
+.Ve
+.IP "Attempt to clear deleted array" 4
+.IX Item "Attempt to clear deleted array"
+(S debugging) An array was assigned to when it was being freed.
+Freed values are not supposed to be visible to Perl code.  This
+can also happen if XS code calls \f(CW\*(C`av_clear\*(C'\fR from a custom magic
+callback on the array.
+.IP "Attempt to delete disallowed key '%s' from a restricted hash" 4
+.IX Item "Attempt to delete disallowed key '%s' from a restricted hash"
+(F) The failing code attempted to delete from a restricted hash a key
+which is not in its key set.
+.IP "Attempt to delete readonly key '%s' from a restricted hash" 4
+.IX Item "Attempt to delete readonly key '%s' from a restricted hash"
+(F) The failing code attempted to delete a key whose value has been
+declared readonly from a restricted hash.
+.IP "Attempt to free non-arena SV: 0x%x" 4
+.IX Item "Attempt to free non-arena SV: 0x%x"
+(S internal) All SV objects are supposed to be allocated from arenas
+that will be garbage collected on exit.  An SV was discovered to be
+outside any of those arenas.
+.IP "Attempt to free nonexistent shared string '%s'%s" 4
+.IX Item "Attempt to free nonexistent shared string '%s'%s"
+(S internal) Perl maintains a reference-counted internal table of
+strings to optimize the storage and access of hash keys and other
+strings.  This indicates someone tried to decrement the reference count
+of a string that can no longer be found in the table.
+.IP "Attempt to free temp prematurely: SV 0x%x" 4
+.IX Item "Attempt to free temp prematurely: SV 0x%x"
+(S debugging) Mortalized values are supposed to be freed by the
+\&\fBfree_tmps()\fR routine.  This indicates that something else is freeing the
+SV before the \fBfree_tmps()\fR routine gets a chance, which means that the
+\&\fBfree_tmps()\fR routine will be freeing an unreferenced scalar when it does
+try to free it.
+.IP "Attempt to free unreferenced glob pointers" 4
+.IX Item "Attempt to free unreferenced glob pointers"
+(S internal) The reference counts got screwed up on symbol aliases.
+.IP "Attempt to free unreferenced scalar: SV 0x%x" 4
+.IX Item "Attempt to free unreferenced scalar: SV 0x%x"
+(S internal) Perl went to decrement the reference count of a scalar to
+see if it would go to 0, and discovered that it had already gone to 0
+earlier, and should have been freed, and in fact, probably was freed.
+This could indicate that \fBSvREFCNT_dec()\fR was called too many times, or
+that \fBSvREFCNT_inc()\fR was called too few times, or that the SV was
+mortalized when it shouldn't have been, or that memory has been
+corrupted.
+.IP "Attempt to pack pointer to temporary value" 4
+.IX Item "Attempt to pack pointer to temporary value"
+(W pack) You tried to pass a temporary value (like the result of a
+function, or a computed expression) to the "p" \fBpack()\fR template.  This
+means the result contains a pointer to a location that could become
+invalid anytime, even before the end of the current statement.  Use
+literals or global values as arguments to the "p" \fBpack()\fR template to
+avoid this warning.
+.ie n .IP "Attempt to reload %s aborted." 4
+.el .IP "Attempt to reload \f(CW%s\fR aborted." 4
+.IX Item "Attempt to reload %s aborted."
+(F) You tried to load a file with \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR that failed to
+compile once already.  Perl will not try to compile this file again
+unless you delete its entry from \f(CW%INC\fR.  See "require" in perlfunc and
+"%INC" in perlvar.
+.IP "Attempt to set length of freed array" 4
+.IX Item "Attempt to set length of freed array"
+(W misc) You tried to set the length of an array which has
+been freed.  You can do this by storing a reference to the
+scalar representing the last index of an array and later
+assigning through that reference.  For example
+.Sp
+.Vb 2
+\&    $r = do {my @a; \e$#a};
+\&    $$r = 503
+.Ve
+.IP "Attempt to use reference as lvalue in substr" 4
+.IX Item "Attempt to use reference as lvalue in substr"
+(W substr) You supplied a reference as the first argument to \fBsubstr()\fR
+used as an lvalue, which is pretty strange.  Perhaps you forgot to
+dereference it first.  See "substr" in perlfunc.
+.IP "Attribute prototype(%s) discards earlier prototype attribute in same sub" 4
+.IX Item "Attribute prototype(%s) discards earlier prototype attribute in same sub"
+(W misc) A sub was declared as sub foo : prototype(A) : prototype(B) {}, for
+example.  Since each sub can only have one prototype, the earlier
+declaration(s) are discarded while the last one is applied.
+.IP "av_reify called on tied array" 4
+.IX Item "av_reify called on tied array"
+(S debugging) This indicates that something went wrong and Perl got \fIvery\fR
+confused about \f(CW@_\fR or \f(CW@DB::args\fR being tied.
+.ie n .IP "Bad arg length for %s, is %u, should be %d" 4
+.el .IP "Bad arg length for \f(CW%s\fR, is \f(CW%u\fR, should be \f(CW%d\fR" 4
+.IX Item "Bad arg length for %s, is %u, should be %d"
+(F) You passed a buffer of the wrong size to one of \fBmsgctl()\fR, \fBsemctl()\fR
+or \fBshmctl()\fR.  In C parlance, the correct sizes are, respectively,
+sizeof(struct\ msqid_ds\ *), sizeof(struct\ semid_ds\ *), and
+sizeof(struct\ shmid_ds\ *).
+.IP "Bad evalled substitution pattern" 4
+.IX Item "Bad evalled substitution pattern"
+(F) You've used the \f(CW\*(C`/e\*(C'\fR switch to evaluate the replacement for a
+substitution, but perl found a syntax error in the code to evaluate,
+most likely an unexpected right brace '}'.
+.ie n .IP "Bad filehandle: %s" 4
+.el .IP "Bad filehandle: \f(CW%s\fR" 4
+.IX Item "Bad filehandle: %s"
+(F) A symbol was passed to something wanting a filehandle, but the
+symbol has no filehandle associated with it.  Perhaps you didn't do an
+\&\fBopen()\fR, or did it in another package.
+.IP "Bad \fBfree()\fR ignored" 4
+.IX Item "Bad free() ignored"
+(S malloc) An internal routine called \fBfree()\fR on something that had never
+been \fBmalloc()\fRed in the first place.  Mandatory, but can be disabled by
+setting environment variable \f(CW\*(C`PERL_BADFREE\*(C'\fR to 0.
+.Sp
+This message can be seen quite often with DB_File on systems with "hard"
+dynamic linking, like \f(CW\*(C`AIX\*(C'\fR and \f(CW\*(C`OS/2\*(C'\fR.  It is a bug of \f(CW\*(C`Berkeley DB\*(C'\fR
+which is left unnoticed if \f(CW\*(C`DB\*(C'\fR uses \fIforgiving\fR system \fBmalloc()\fR.
+.IP "Bad infix plugin result (%zd) \- did not consume entire identifier <%s>" 4
+.IX Item "Bad infix plugin result (%zd) - did not consume entire identifier <%s>"
+(F) A plugin using the \f(CW\*(C`PL_infix_plugin\*(C'\fR mechanism to parse an infix
+keyword consumed part of a named identifier operator name but did not
+consume all of it.  This is not permitted as it leads to fragile parsing
+results.
+.IP "Badly placed ()'s" 4
+.IX Item "Badly placed ()'s"
+(A) You've accidentally run your script through \fBcsh\fR instead
+of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.
+.ie n .IP "Bad name after %s" 4
+.el .IP "Bad name after \f(CW%s\fR" 4
+.IX Item "Bad name after %s"
+(F) You started to name a symbol by using a package prefix, and then
+didn't finish the symbol.  In particular, you can't interpolate outside
+of quotes, so
+.Sp
+.Vb 2
+\&    $var = \*(Aqmyvar\*(Aq;
+\&    $sym = mypack::$var;
+.Ve
+.Sp
+is not the same as
+.Sp
+.Vb 2
+\&    $var = \*(Aqmyvar\*(Aq;
+\&    $sym = "mypack::$var";
+.Ve
+.IP "Bad plugin affecting keyword '%s'" 4
+.IX Item "Bad plugin affecting keyword '%s'"
+(F) An extension using the keyword plugin mechanism violated the
+plugin API.
+.IP "Bad \fBrealloc()\fR ignored" 4
+.IX Item "Bad realloc() ignored"
+(S malloc) An internal routine called \fBrealloc()\fR on something that
+had never been \fBmalloc()\fRed in the first place.  Mandatory, but can
+be disabled by setting the environment variable \f(CW\*(C`PERL_BADFREE\*(C'\fR to 1.
+.ie n .IP "Bad symbol for %s" 4
+.el .IP "Bad symbol for \f(CW%s\fR" 4
+.IX Item "Bad symbol for %s"
+(P) An internal request asked to add an entry of the named type to something that
+wasn't a symbol table entry.
+.IP "Bad symbol for scalar" 4
+.IX Item "Bad symbol for scalar"
+(P) An internal request asked to add a scalar entry to something that
+wasn't a symbol table entry.
+.IP "Bareword found in conditional" 4
+.IX Item "Bareword found in conditional"
+(W bareword) The compiler found a bareword where it expected a
+conditional, which often indicates that an || or && was parsed as part
+of the last argument of the previous construct, for example:
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.Sp
+It may also indicate a misspelled constant that has been interpreted as
+a bareword:
+.Sp
+.Vb 2
+\&    use constant TYPO => 1;
+\&    if (TYOP) { print "foo" }
+.Ve
+.Sp
+The \f(CW\*(C`strict\*(C'\fR pragma is useful in avoiding such errors.
+.IP "Bareword in require contains ""%s""" 4
+.IX Item "Bareword in require contains ""%s"""
+.PD 0
+.IP "Bareword in require maps to disallowed filename ""%s""" 4
+.IX Item "Bareword in require maps to disallowed filename ""%s"""
+.IP "Bareword in require maps to empty filename" 4
+.IX Item "Bareword in require maps to empty filename"
+.PD
+(F) The bareword form of require has been invoked with a filename which could
+not have been generated by a valid bareword permitted by the parser.  You
+shouldn't be able to get this error from Perl code, but XS code may throw it
+if it passes an invalid module name to \f(CW\*(C`Perl_load_module\*(C'\fR.
+.IP "Bareword in require must not start with a double-colon: ""%s""" 4
+.IX Item "Bareword in require must not start with a double-colon: ""%s"""
+(F) In \f(CW\*(C`require Bare::Word\*(C'\fR, the bareword is not allowed to start with a
+double-colon.  Write \f(CW\*(C`require ::Foo::Bar\*(C'\fR as  \f(CW\*(C`require Foo::Bar\*(C'\fR instead.
+.IP "Bareword ""%s"" not allowed while ""strict subs"" in use" 4
+.IX Item "Bareword ""%s"" not allowed while ""strict subs"" in use"
+(F) With "strict subs" in use, a bareword is only allowed as a
+subroutine identifier, in curly brackets or to the left of the "=>"
+symbol.  Perhaps you need to predeclare a subroutine?
+.IP "Bareword ""%s"" refers to nonexistent package" 4
+.IX Item "Bareword ""%s"" refers to nonexistent package"
+(W bareword) You used a qualified bareword of the form \f(CW\*(C`Foo::\*(C'\fR, but the
+compiler saw no other uses of that namespace before that point.  Perhaps
+you need to predeclare a package?
+.IP "Bareword filehandle ""%s"" not allowed under 'no feature ""bareword_filehandles""'" 4
+.IX Item "Bareword filehandle ""%s"" not allowed under 'no feature ""bareword_filehandles""'"
+(F) You attempted to use a bareword filehandle with the
+\&\f(CW\*(C`bareword_filehandles\*(C'\fR feature disabled.
+.Sp
+Only the built-in handles \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`STDERR\*(C'\fR, \f(CW\*(C`ARGV\*(C'\fR,
+\&\f(CW\*(C`ARGVOUT\*(C'\fR and \f(CW\*(C`DATA\*(C'\fR can be used with the \f(CW\*(C`bareword_filehandles\*(C'\fR
+feature disabled.
+.IP "BEGIN failed\-\-compilation aborted" 4
+.IX Item "BEGIN failed--compilation aborted"
+(F) An untrapped exception was raised while executing a BEGIN
+subroutine.  Compilation stops immediately and the interpreter is
+exited.
+.IP "BEGIN not safe after errors\-\-compilation aborted" 4
+.IX Item "BEGIN not safe after errors--compilation aborted"
+(F) Perl found a \f(CW\*(C`BEGIN {}\*(C'\fR subroutine (or a \f(CW\*(C`use\*(C'\fR directive, which
+implies a \f(CW\*(C`BEGIN {}\*(C'\fR) after one or more compilation errors had already
+occurred.  Since the intended environment for the \f(CW\*(C`BEGIN {}\*(C'\fR could not
+be guaranteed (due to the errors), and since subsequent code likely
+depends on its correct operation, Perl just gave up.
+.IP "\e%d better written as $%d" 4
+.IX Item "%d better written as $%d"
+(W syntax) Outside of patterns, backreferences live on as variables.
+The use of backslashes is grandfathered on the right-hand side of a
+substitution, but stylistically it's better to use the variable form
+because other Perl programmers will expect it, and it works better if
+there are more than 9 backreferences.
+.IP "Binary number > 0b11111111111111111111111111111111 non-portable" 4
+.IX Item "Binary number > 0b11111111111111111111111111111111 non-portable"
+(W portable) The binary number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.ie n .IP "\fBbind()\fR on closed socket %s" 4
+.el .IP "\fBbind()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "bind() on closed socket %s"
+(W closed) You tried to do a bind on a closed socket.  Did you forget to
+check the return value of your \fBsocket()\fR call?  See "bind" in perlfunc.
+.ie n .IP "\fBbinmode()\fR on closed filehandle %s" 4
+.el .IP "\fBbinmode()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "binmode() on closed filehandle %s"
+(W unopened) You tried \fBbinmode()\fR on a filehandle that was never opened.
+Check your control flow and number of arguments.
+.IP "Bit vector size > 32 non-portable" 4
+.IX Item "Bit vector size > 32 non-portable"
+(W portable) Using bit vector sizes larger than 32 is non-portable.
+.ie n .IP "Bizarre copy of %s" 4
+.el .IP "Bizarre copy of \f(CW%s\fR" 4
+.IX Item "Bizarre copy of %s"
+(P) Perl detected an attempt to copy an internal value that is not
+copiable.
+.IP "Bizarre SvTYPE [%d]" 4
+.IX Item "Bizarre SvTYPE [%d]"
+(P) When starting a new thread or returning values from a thread, Perl
+encountered an invalid data type.
+.IP "Both or neither range ends should be Unicode in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Both or neither range ends should be Unicode in regex; marked by <--\ HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+In a bracketed character class in a regular expression pattern, you
+had a range which has exactly one end of it specified using \f(CW\*(C`\eN{}\*(C'\fR, and
+the other end is specified using a non-portable mechanism.  Perl treats
+the range as a Unicode range, that is, all the characters in it are
+considered to be the Unicode characters, and which may be different code
+points on some platforms Perl runs on.  For example, \f(CW\*(C`[\eN{U+06}\-\ex08]\*(C'\fR
+is treated as if you had instead said \f(CW\*(C`[\eN{U+06}\-\eN{U+08}]\*(C'\fR, that is it
+matches the characters whose code points in Unicode are 6, 7, and 8.
+But that \f(CW\*(C`\ex08\*(C'\fR might indicate that you meant something different, so
+the warning gets raised.
+.ie n .IP "Buffer overflow in prime_env_iter: %s" 4
+.el .IP "Buffer overflow in prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Buffer overflow in prime_env_iter: %s"
+(W internal) A warning peculiar to VMS.  While Perl was preparing to
+iterate over \f(CW%ENV\fR, it encountered a logical name or symbol definition
+which was too long, so it was truncated to the string shown.
+.IP "Built-in function '%s' is experimental" 4
+.IX Item "Built-in function '%s' is experimental"
+(S experimental::builtin) A call is being made to a function in the
+\&\f(CW\*(C`builtin::\*(C'\fR namespace, which is currently experimental. The existence
+or nature of the function may be subject to change in a future version
+of Perl.
+.IP "builtin::import can only be called at compile time" 4
+.IX Item "builtin::import can only be called at compile time"
+(F) The \f(CW\*(C`import\*(C'\fR method of the \f(CW\*(C`builtin\*(C'\fR package was invoked when no code
+is currently being compiled. Since this method is used to introduce new
+lexical subroutines into the scope currently being compiled, this is not
+going to have any effect.
+.IP "Callback called exit" 4
+.IX Item "Callback called exit"
+(F) A subroutine invoked from an external package via \fBcall_sv()\fR
+exited by calling exit.
+.IP "%s() called too early to check prototype" 4
+.IX Item "%s() called too early to check prototype"
+(W prototype) You've called a function that has a prototype before the
+parser saw a definition or declaration for it, and Perl could not check
+that the call conforms to the prototype.  You need to either add an
+early prototype declaration for the subroutine in question, or move the
+subroutine definition ahead of the call to get proper prototype
+checking.  Alternatively, if you are certain that you're calling the
+function correctly, you may put an ampersand before the name to avoid
+the warning.  See perlsub.
+.ie n .IP "Cannot assign :param(%s) to field %s because that name is already in use" 4
+.el .IP "Cannot assign :param(%s) to field \f(CW%s\fR because that name is already in use" 4
+.IX Item "Cannot assign :param(%s) to field %s because that name is already in use"
+(F) An attempt was made to apply a parameter name to a field, when the name
+is already being used by another field in the same class, or one of its
+parent classes. This would cause a name clash so is not allowed.
+.ie n .IP "Cannot chr %f" 4
+.el .IP "Cannot chr \f(CW%f\fR" 4
+.IX Item "Cannot chr %f"
+(F) You passed an invalid number (like an infinity or not-a-number) to \f(CW\*(C`chr\*(C'\fR.
+.ie n .IP "Cannot complete in-place edit of %s: %s" 4
+.el .IP "Cannot complete in-place edit of \f(CW%s:\fR \f(CW%s\fR" 4
+.IX Item "Cannot complete in-place edit of %s: %s"
+(F) Your perl script appears to have changed directory while
+performing an in-place edit of a file specified by a relative path,
+and your system doesn't include the directory relative POSIX functions
+needed to handle that.
+.ie n .IP "Cannot compress %f in pack" 4
+.el .IP "Cannot compress \f(CW%f\fR in pack" 4
+.IX Item "Cannot compress %f in pack"
+(F) You tried compressing an infinity or not-a-number as an unsigned
+integer with BER, which makes no sense.
+.IP "Cannot compress integer in pack" 4
+.IX Item "Cannot compress integer in pack"
+(F) An argument to pack("w",...) was too large to compress.
+The BER compressed integer format can only be used with positive
+integers, and you attempted to compress a very large number (> 1e308).
+See "pack" in perlfunc.
+.IP "Cannot compress negative numbers in pack" 4
+.IX Item "Cannot compress negative numbers in pack"
+(F) An argument to pack("w",...) was negative.  The BER compressed integer
+format can only be used with positive integers.  See "pack" in perlfunc.
+.ie n .IP "Cannot convert a reference to %s to typeglob" 4
+.el .IP "Cannot convert a reference to \f(CW%s\fR to typeglob" 4
+.IX Item "Cannot convert a reference to %s to typeglob"
+(F) You manipulated Perl's symbol table directly, stored a reference
+in it, then tried to access that symbol via conventional Perl syntax.
+The access triggers Perl to autovivify that typeglob, but it there is
+no legal conversion from that type of reference to a typeglob.
+.ie n .IP "Cannot copy to %s" 4
+.el .IP "Cannot copy to \f(CW%s\fR" 4
+.IX Item "Cannot copy to %s"
+(P) Perl detected an attempt to copy a value to an internal type that cannot
+be directly assigned to.
+.ie n .IP "Cannot create class %s as it already has a non-empty @ISA" 4
+.el .IP "Cannot create class \f(CW%s\fR as it already has a non-empty \f(CW@ISA\fR" 4
+.IX Item "Cannot create class %s as it already has a non-empty @ISA"
+(F) An attempt was made to create a class out of a package that already has
+an \f(CW@ISA\fR array, and the array is not empty.  This is not permitted, as it
+would lead to a class with inconsistent inheritance.
+.IP "Cannot find encoding ""%s""" 4
+.IX Item "Cannot find encoding ""%s"""
+(S io) You tried to apply an encoding that did not exist to a filehandle,
+either with \fBopen()\fR or \fBbinmode()\fR.
+.IP "Cannot invoke a method of ""%s"" on an instance of ""%s""" 4
+.IX Item "Cannot invoke a method of ""%s"" on an instance of ""%s"""
+(F) You tried to directly call a \f(CW\*(C`method\*(C'\fR subroutine of one class by passing
+in a value that is an instance of a different class.  This is not permitted,
+as the method would not have access to the correct instance fields.
+.IP "Cannot invoke method on a non-instance" 4
+.IX Item "Cannot invoke method on a non-instance"
+(F) You tried to directly call a \f(CW\*(C`method\*(C'\fR subroutine of a class by passing
+in a value that is not an instance of that class.  This is not permitted, as
+the method would not then have access to its instance fields.
+.ie n .IP "Cannot open %s as a dirhandle: it is already open as a filehandle" 4
+.el .IP "Cannot open \f(CW%s\fR as a dirhandle: it is already open as a filehandle" 4
+.IX Item "Cannot open %s as a dirhandle: it is already open as a filehandle"
+(F) You tried to use \fBopendir()\fR to associate a dirhandle to a symbol (glob
+or scalar) that already holds a filehandle.  Since this idiom might render
+your code confusing, it was deprecated in Perl 5.10.  As of Perl 5.28, it
+is a fatal error.
+.ie n .IP "Cannot open %s as a filehandle: it is already open as a dirhandle" 4
+.el .IP "Cannot open \f(CW%s\fR as a filehandle: it is already open as a dirhandle" 4
+.IX Item "Cannot open %s as a filehandle: it is already open as a dirhandle"
+(F) You tried to use \fBopen()\fR to associate a filehandle to a symbol (glob
+or scalar) that already holds a dirhandle.  Since this idiom might render
+your code confusing, it was deprecated in Perl 5.10.  As of Perl 5.28, it
+is a fatal error.
+.IP "Cannot '%s' outside of a 'class'" 4
+.IX Item "Cannot '%s' outside of a 'class'"
+(F) You attempted to use one of the keywords that only makes sense inside
+a \f(CW\*(C`class\*(C'\fR definition, at a location that is not inside such a class.
+.ie n .IP "Cannot pack %f with '%c'" 4
+.el .IP "Cannot pack \f(CW%f\fR with '%c'" 4
+.IX Item "Cannot pack %f with '%c'"
+(F) You tried converting an infinity or not-a-number to an integer,
+which makes no sense.
+.ie n .IP "Cannot printf %f with '%c'" 4
+.el .IP "Cannot printf \f(CW%f\fR with '%c'" 4
+.IX Item "Cannot printf %f with '%c'"
+(F) You tried printing an infinity or not-a-number as a character (%c),
+which makes no sense.  Maybe you meant '%s', or just stringifying it?
+.IP "Cannot reopen existing class ""%s""" 4
+.IX Item "Cannot reopen existing class ""%s"""
+(F) You tried to begin a \f(CW\*(C`class\*(C'\fR definition for a class that already exists.
+A class may only have one definition block.
+.ie n .IP "Cannot set tied @DB::args" 4
+.el .IP "Cannot set tied \f(CW@DB::args\fR" 4
+.IX Item "Cannot set tied @DB::args"
+(F) \f(CW\*(C`caller\*(C'\fR tried to set \f(CW@DB::args\fR, but found it tied.  Tying \f(CW@DB::args\fR
+is not supported.  (Before this error was added, it used to crash.)
+.IP "Cannot tie unreifiable array" 4
+.IX Item "Cannot tie unreifiable array"
+(P) You somehow managed to call \f(CW\*(C`tie\*(C'\fR on an array that does not
+keep a reference count on its arguments and cannot be made to
+do so.  Such arrays are not even supposed to be accessible to
+Perl code, but are only used internally.
+.IP "Cannot yet reorder \fBsv_vcatpvfn()\fR arguments from va_list" 4
+.IX Item "Cannot yet reorder sv_vcatpvfn() arguments from va_list"
+(F) Some XS code tried to use \f(CWsv_vcatpvfn()\fR or a related function with a
+format string that specifies explicit indexes for some of the elements, and
+using a C\-style variable-argument list (a \f(CW\*(C`va_list\*(C'\fR).  This is not currently
+supported.  XS authors wanting to do this must instead construct a C array
+of \f(CW\*(C`SV*\*(C'\fR scalars containing the arguments.
+.IP "Can only compress unsigned integers in pack" 4
+.IX Item "Can only compress unsigned integers in pack"
+(F) An argument to pack("w",...) was not an integer.  The BER compressed
+integer format can only be used with positive integers, and you attempted
+to compress something else.  See "pack" in perlfunc.
+.IP "Can't ""%s"" out of a ""defer"" block" 4
+.IX Item "Can't ""%s"" out of a ""defer"" block"
+(F) An attempt was made to jump out of the scope of a \f(CW\*(C`defer\*(C'\fR block by using
+a control-flow statement such as \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`goto\*(C'\fR or a loop control. This is
+not permitted.
+.IP "Can't ""%s"" out of a ""finally"" block" 4
+.IX Item "Can't ""%s"" out of a ""finally"" block"
+(F) Similar to above, but involving a \f(CW\*(C`finally\*(C'\fR block at the end of a
+\&\f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR construction rather than a \f(CW\*(C`defer\*(C'\fR block.
+.IP "Can't bless an object reference" 4
+.IX Item "Can't bless an object reference"
+(F) You attempted to call \f(CW\*(C`bless\*(C'\fR on a value that already refers to a real
+object instance.
+.IP "Can't bless non-reference value" 4
+.IX Item "Can't bless non-reference value"
+(F) Only hard references may be blessed.  This is how Perl "enforces"
+encapsulation of objects.  See perlobj.
+.IP "Can't ""break"" in a loop topicalizer" 4
+.IX Item "Can't ""break"" in a loop topicalizer"
+(F) You called \f(CW\*(C`break\*(C'\fR, but you're in a \f(CW\*(C`foreach\*(C'\fR block rather than
+a \f(CW\*(C`given\*(C'\fR block.  You probably meant to use \f(CW\*(C`next\*(C'\fR or \f(CW\*(C`last\*(C'\fR.
+.IP "Can't ""break"" outside a given block" 4
+.IX Item "Can't ""break"" outside a given block"
+(F) You called \f(CW\*(C`break\*(C'\fR, but you're not inside a \f(CW\*(C`given\*(C'\fR block.
+.IP "Can't call destructor for 0x%p in global destruction" 4
+.IX Item "Can't call destructor for 0x%p in global destruction"
+(S) This should not happen. Internals code has set up a destructor
+using \f(CW\*(C`mortal_destructor_sv\*(C'\fR or \f(CW\*(C`mortal_destructor_x\*(C'\fR which is firing
+during global destruction. Please attempt to reduce the code that triggers
+this warning down to a small an example as possible and then report the
+problem to <https://github.com/Perl/perl5/issues/new/choose>
+.IP "Can't call method ""%s"" on an undefined value" 4
+.IX Item "Can't call method ""%s"" on an undefined value"
+(F) You used the syntax of a method call, but the slot filled by the
+object reference or package name contains an undefined value.  Something
+like this will reproduce the error:
+.Sp
+.Vb 3
+\&    $BADREF = undef;
+\&    process $BADREF 1,2,3;
+\&    $BADREF\->process(1,2,3);
+.Ve
+.IP "Can't call method ""%s"" on unblessed reference" 4
+.IX Item "Can't call method ""%s"" on unblessed reference"
+(F) A method call must know in what package it's supposed to run.  It
+ordinarily finds this out from the object reference you supply, but you
+didn't supply an object reference in this case.  A reference isn't an
+object reference until it has been blessed.  See perlobj.
+.IP "Can't call method ""%s"" without a package or object reference" 4
+.IX Item "Can't call method ""%s"" without a package or object reference"
+(F) You used the syntax of a method call, but the slot filled by the
+object reference or package name contains an expression that returns a
+defined value which is neither an object reference nor a package name.
+Something like this will reproduce the error:
+.Sp
+.Vb 3
+\&    $BADREF = 42;
+\&    process $BADREF 1,2,3;
+\&    $BADREF\->process(1,2,3);
+.Ve
+.IP "Can't call \fBmro_isa_changed_in()\fR on anonymous symbol table" 4
+.IX Item "Can't call mro_isa_changed_in() on anonymous symbol table"
+(P) Perl got confused as to whether a hash was a plain hash or a
+symbol table hash when trying to update \f(CW@ISA\fR caches.
+.IP "Can't call \fBmro_method_changed_in()\fR on anonymous symbol table" 4
+.IX Item "Can't call mro_method_changed_in() on anonymous symbol table"
+(F) An XS module tried to call \f(CW\*(C`mro_method_changed_in\*(C'\fR on a hash that was
+not attached to the symbol table.
+.ie n .IP "Can't chdir to %s" 4
+.el .IP "Can't chdir to \f(CW%s\fR" 4
+.IX Item "Can't chdir to %s"
+(F) You called \f(CW\*(C`perl \-x/foo/bar\*(C'\fR, but \fI/foo/bar\fR is not a directory
+that you can chdir to, possibly because it doesn't exist.
+.ie n .IP "Can't coerce %s to %s in %s" 4
+.el .IP "Can't coerce \f(CW%s\fR to \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "Can't coerce %s to %s in %s"
+(F) Certain types of SVs, in particular real symbol table entries
+(typeglobs), can't be forced to stop being what they are.  So you can't
+say things like:
+.Sp
+.Vb 1
+\&    *foo += 1;
+.Ve
+.Sp
+You CAN say
+.Sp
+.Vb 2
+\&    $foo = *foo;
+\&    $foo += 1;
+.Ve
+.Sp
+but then \f(CW$foo\fR no longer contains a glob.
+.IP "Can't ""continue"" outside a when block" 4
+.IX Item "Can't ""continue"" outside a when block"
+(F) You called \f(CW\*(C`continue\*(C'\fR, but you're not inside a \f(CW\*(C`when\*(C'\fR
+or \f(CW\*(C`default\*(C'\fR block.
+.IP "can't convert empty path" 4
+.IX Item "can't convert empty path"
+(F) On Cygwin, you called a path conversion function with an empty path.
+Only non-empty paths are legal.
+.IP "Can't create pipe mailbox" 4
+.IX Item "Can't create pipe mailbox"
+(P) An error peculiar to VMS.  The process is suffering from exhausted
+quotas or other plumbing problems.
+.ie n .IP "Can't declare %s in ""%s""" 4
+.el .IP "Can't declare \f(CW%s\fR in ""%s""" 4
+.IX Item "Can't declare %s in ""%s"""
+(F) Only scalar, array, and hash variables may be declared as "my", "our" or
+"state" variables.  They must have ordinary identifiers as names.
+.IP "Can't ""default"" outside a topicalizer" 4
+.IX Item "Can't ""default"" outside a topicalizer"
+(F) You have used a \f(CW\*(C`default\*(C'\fR block that is neither inside a
+\&\f(CW\*(C`foreach\*(C'\fR loop nor a \f(CW\*(C`given\*(C'\fR block.  (Note that this error is
+issued on exit from the \f(CW\*(C`default\*(C'\fR block, so you won't get the
+error if you use an explicit \f(CW\*(C`continue\*(C'\fR.)
+.ie n .IP "Can't determine class of operator %s, assuming BASEOP" 4
+.el .IP "Can't determine class of operator \f(CW%s\fR, assuming BASEOP" 4
+.IX Item "Can't determine class of operator %s, assuming BASEOP"
+(S) This warning indicates something wrong in the internals of perl.
+Perl was trying to find the class (e.g. LISTOP) of a particular OP,
+and was unable to do so. This is likely to be due to a bug in the perl
+internals, or due to a bug in XS code which manipulates perl optrees.
+.ie n .IP "Can't do inplace edit: %s is not a regular file" 4
+.el .IP "Can't do inplace edit: \f(CW%s\fR is not a regular file" 4
+.IX Item "Can't do inplace edit: %s is not a regular file"
+(S inplace) You tried to use the \fB\-i\fR switch on a special file, such as
+a file in /dev, a FIFO or an uneditable directory.  The file was ignored.
+.ie n .IP "Can't do inplace edit on %s: %s" 4
+.el .IP "Can't do inplace edit on \f(CW%s:\fR \f(CW%s\fR" 4
+.IX Item "Can't do inplace edit on %s: %s"
+(S inplace) The creation of the new file failed for the indicated
+reason.
+.ie n .IP "Can't do inplace edit: %s would not be unique" 4
+.el .IP "Can't do inplace edit: \f(CW%s\fR would not be unique" 4
+.IX Item "Can't do inplace edit: %s would not be unique"
+(S inplace) Your filesystem does not support filenames longer than 14
+characters and Perl was unable to create a unique filename during
+inplace editing with the \fB\-i\fR switch.  The file was ignored.
+.IP "Can't do %s(""%s"") on non\-UTF\-8 locale; resolved to ""%s""." 4
+.IX Item "Can't do %s(""%s"") on non-UTF-8 locale; resolved to ""%s""."
+(W locale) You are 1) running under "\f(CW\*(C`use locale\*(C'\fR"; 2) the current
+locale is not a UTF\-8 one; 3) you tried to do the designated case-change
+operation on the specified Unicode character; and 4) the result of this
+operation would mix Unicode and locale rules, which likely conflict.
+Mixing of different rule types is forbidden, so the operation was not
+done; instead the result is the indicated value, which is the best
+available that uses entirely Unicode rules.  That turns out to almost
+always be the original character, unchanged.
+.Sp
+It is generally a bad idea to mix non\-UTF\-8 locales and Unicode, and
+this issue is one of the reasons why.  This warning is raised when
+Unicode rules would normally cause the result of this operation to
+contain a character that is in the range specified by the locale,
+0..255, and hence is subject to the locale's rules, not Unicode's.
+.Sp
+If you are using locale purely for its characteristics related to things
+like its numeric and time formatting (and not \f(CW\*(C`LC_CTYPE\*(C'\fR), consider
+using a restricted form of the locale pragma (see "The "use
+locale" pragma" in perllocale) like "\f(CW\*(C`use\ locale\ \*(Aq:not_characters\*(Aq\*(C'\fR".
+.Sp
+Note that failed case-changing operations done as a result of
+case-insensitive \f(CW\*(C`/i\*(C'\fR regular expression matching will show up in this
+warning as having the \f(CW\*(C`fc\*(C'\fR operation (as that is what the regular
+expression engine calls behind the scenes.)
+.IP "Can't do waitpid with flags" 4
+.IX Item "Can't do waitpid with flags"
+(F) This machine doesn't have either \fBwaitpid()\fR or \fBwait4()\fR, so only
+\&\fBwaitpid()\fR without flags is emulated.
+.IP "Can't emulate \-%s on #! line" 4
+.IX Item "Can't emulate -%s on #! line"
+(F) The #! line specifies a switch that doesn't make sense at this
+point.  For example, it'd be kind of silly to put a \fB\-x\fR on the #!
+line.
+.ie n .IP "Can't %s %s\-endian %ss on this platform" 4
+.el .IP "Can't \f(CW%s\fR \f(CW%s\fR\-endian \f(CW%ss\fR on this platform" 4
+.IX Item "Can't %s %s-endian %ss on this platform"
+(F) Your platform's byte-order is neither big-endian nor little-endian,
+or it has a very strange pointer size.  Packing and unpacking big\- or
+little-endian floating point values and pointers may not be possible.
+See "pack" in perlfunc.
+.ie n .IP "Can't exec ""%s"": %s" 4
+.el .IP "Can't exec ""%s"": \f(CW%s\fR" 4
+.IX Item "Can't exec ""%s"": %s"
+(W exec) A \fBsystem()\fR, \fBexec()\fR, or piped open call could not execute the
+named program for the indicated reason.  Typical reasons include: the
+permissions were wrong on the file, the file wasn't found in
+\&\f(CW$ENV{PATH}\fR, the executable in question was compiled for another
+architecture, or the #! line in a script points to an interpreter that
+can't be run for similar reasons.  (Or maybe your system doesn't support
+#! at all.)
+.ie n .IP "Can't exec %s" 4
+.el .IP "Can't exec \f(CW%s\fR" 4
+.IX Item "Can't exec %s"
+(F) Perl was trying to execute the indicated program for you because
+that's what the #! line said.  If that's not what you wanted, you may
+need to mention "perl" on the #! line somewhere.
+.ie n .IP "Can't execute %s" 4
+.el .IP "Can't execute \f(CW%s\fR" 4
+.IX Item "Can't execute %s"
+(F) You used the \fB\-S\fR switch, but the copies of the script to execute
+found in the PATH did not have correct permissions.
+.IP "Can't find an opnumber for ""%s""" 4
+.IX Item "Can't find an opnumber for ""%s"""
+(F) A string of a form \f(CW\*(C`CORE::word\*(C'\fR was given to \fBprototype()\fR, but there
+is no builtin with the name \f(CW\*(C`word\*(C'\fR.
+.ie n .IP "Can't find label %s" 4
+.el .IP "Can't find label \f(CW%s\fR" 4
+.IX Item "Can't find label %s"
+(F) You said to goto a label that isn't mentioned anywhere that it's
+possible for us to go to.  See "goto" in perlfunc.
+.ie n .IP "Can't find %s on PATH" 4
+.el .IP "Can't find \f(CW%s\fR on PATH" 4
+.IX Item "Can't find %s on PATH"
+(F) You used the \fB\-S\fR switch, but the script to execute could not be
+found in the PATH.
+.ie n .IP "Can't find %s on PATH, '.' not in PATH" 4
+.el .IP "Can't find \f(CW%s\fR on PATH, '.' not in PATH" 4
+.IX Item "Can't find %s on PATH, '.' not in PATH"
+(F) You used the \fB\-S\fR switch, but the script to execute could not be
+found in the PATH, or at least not with the correct permissions.  The
+script exists in the current directory, but PATH prohibits running it.
+.ie n .IP "Can't find string terminator %s anywhere before EOF" 4
+.el .IP "Can't find string terminator \f(CW%s\fR anywhere before EOF" 4
+.IX Item "Can't find string terminator %s anywhere before EOF"
+(F) Perl strings can stretch over multiple lines.  This message means
+that the closing delimiter was omitted.  Because bracketed quotes count
+nesting levels, the following is missing its final parenthesis:
+.Sp
+.Vb 1
+\&    print q(The character \*(Aq(\*(Aq starts a side comment.);
+.Ve
+.Sp
+If you're getting this error from a here-document, you may have
+included unseen whitespace before or after your closing tag or there
+may not be a linebreak after it.  A good programmer's editor will have
+a way to help you find these characters (or lack of characters).  See
+perlop for the full details on here-documents.
+.IP "Can't find Unicode property definition ""%s""" 4
+.IX Item "Can't find Unicode property definition ""%s"""
+.PD 0
+.IP "Can't find Unicode property definition ""%s"" in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Can't find Unicode property definition ""%s"" in regex; marked by <-- HERE in m/%s/"
+.PD
+(F) The named property which you specified via \f(CW\*(C`\ep\*(C'\fR or \f(CW\*(C`\eP\*(C'\fR is not one
+known to Perl.  Perhaps you misspelled the name?  See
+"Properties accessible through \ep{} and \eP{}" in perluniprops
+for a complete list of available official
+properties.  If it is a
+user-defined property
+it must have been defined by the time the regular expression is
+matched.
+.Sp
+If you didn't mean to use a Unicode property, escape the \f(CW\*(C`\ep\*(C'\fR, either
+by \f(CW\*(C`\e\ep\*(C'\fR (just the \f(CW\*(C`\ep\*(C'\fR) or by \f(CW\*(C`\eQ\ep\*(C'\fR (the rest of the string, or
+until \f(CW\*(C`\eE\*(C'\fR).
+.ie n .IP "Can't fork: %s" 4
+.el .IP "Can't fork: \f(CW%s\fR" 4
+.IX Item "Can't fork: %s"
+(F) A fatal error occurred while trying to fork while opening a
+pipeline.
+.IP "Can't fork, trying again in 5 seconds" 4
+.IX Item "Can't fork, trying again in 5 seconds"
+(W pipe) A fork in a piped open failed with EAGAIN and will be retried
+after five seconds.
+.IP "Can't get filespec \- stale stat buffer?" 4
+.IX Item "Can't get filespec - stale stat buffer?"
+(S) A warning peculiar to VMS.  This arises because of the difference
+between access checks under VMS and under the Unix model Perl assumes.
+Under VMS, access checks are done by filename, rather than by bits in
+the stat buffer, so that ACLs and other protections can be taken into
+account.  Unfortunately, Perl assumes that the stat buffer contains all
+the necessary information, and passes it, instead of the filespec, to
+the access-checking routine.  It will try to retrieve the filespec using
+the device name and FID present in the stat buffer, but this works only
+if you haven't made a subsequent call to the CRTL \fBstat()\fR routine,
+because the device name is overwritten with each call.  If this warning
+appears, the name lookup failed, and the access-checking routine gave up
+and returned FALSE, just to be conservative.  (Note: The access-checking
+routine knows about the Perl \f(CW\*(C`stat\*(C'\fR operator and file tests, so you
+shouldn't ever see this warning in response to a Perl command; it arises
+only if some internal code takes stat buffers lightly.)
+.IP "Can't get pipe mailbox device name" 4
+.IX Item "Can't get pipe mailbox device name"
+(P) An error peculiar to VMS.  After creating a mailbox to act as a
+pipe, Perl can't retrieve its name for later use.
+.IP "Can't get SYSGEN parameter value for MAXBUF" 4
+.IX Item "Can't get SYSGEN parameter value for MAXBUF"
+(P) An error peculiar to VMS.  Perl asked \f(CW$GETSYI\fR how big you want your
+mailbox buffers to be, and didn't get an answer.
+.IP "Can't ""goto"" into a binary or list expression" 4
+.IX Item "Can't ""goto"" into a binary or list expression"
+(F) A "goto" statement was executed to jump into the middle of a binary
+or list expression.  You can't get there from here.  The reason for this
+restriction is that the interpreter would get confused as to how many
+arguments there are, resulting in stack corruption or crashes.  This
+error occurs in cases such as these:
+.Sp
+.Vb 2
+\&    goto F;
+\&    print do { F: }; # Can\*(Aqt jump into the arguments to print
+\&
+\&    goto G;
+\&    $x + do { G: $y }; # How is + supposed to get its first operand?
+.Ve
+.IP "Can't ""goto"" into a ""defer"" block" 4
+.IX Item "Can't ""goto"" into a ""defer"" block"
+(F) A \f(CW\*(C`goto\*(C'\fR statement was executed to jump into the scope of a \f(CW\*(C`defer\*(C'\fR
+block.  This is not permitted.
+.IP "Can't ""goto"" into a ""given"" block" 4
+.IX Item "Can't ""goto"" into a ""given"" block"
+(F) A "goto" statement was executed to jump into the middle of a \f(CW\*(C`given\*(C'\fR
+block.  You can't get there from here.  See "goto" in perlfunc.
+.IP "Can't ""goto"" into the middle of a foreach loop" 4
+.IX Item "Can't ""goto"" into the middle of a foreach loop"
+(F) A "goto" statement was executed to jump into the middle of a foreach
+loop.  You can't get there from here.  See "goto" in perlfunc.
+.IP "Can't ""goto"" out of a pseudo block" 4
+.IX Item "Can't ""goto"" out of a pseudo block"
+(F) A "goto" statement was executed to jump out of what might look like
+a block, except that it isn't a proper block.  This usually occurs if
+you tried to jump out of a \fBsort()\fR block or subroutine, which is a no-no.
+See "goto" in perlfunc.
+.IP "Can't goto subroutine from an eval\-%s" 4
+.IX Item "Can't goto subroutine from an eval-%s"
+(F) The "goto subroutine" call can't be used to jump out of an eval
+"string" or block.
+.IP "Can't goto subroutine from a sort sub (or similar callback)" 4
+.IX Item "Can't goto subroutine from a sort sub (or similar callback)"
+(F) The "goto subroutine" call can't be used to jump out of the
+comparison sub for a \fBsort()\fR, or from a similar callback (such
+as the \fBreduce()\fR function in List::Util).
+.IP "Can't goto subroutine outside a subroutine" 4
+.IX Item "Can't goto subroutine outside a subroutine"
+(F) The deeply magical "goto subroutine" call can only replace one
+subroutine call for another.  It can't manufacture one out of whole
+cloth.  In general you should be calling it out of only an AUTOLOAD
+routine anyway.  See "goto" in perlfunc.
+.IP "Can't ignore signal CHLD, forcing to default" 4
+.IX Item "Can't ignore signal CHLD, forcing to default"
+(W signal) Perl has detected that it is being run with the SIGCHLD
+signal (sometimes known as SIGCLD) disabled.  Since disabling this
+signal will interfere with proper determination of exit status of child
+processes, Perl has reset the signal to its default value.  This
+situation typically indicates that the parent program under which Perl
+may be running (e.g. cron) is being very careless.
+.IP "Can't kill a non-numeric process ID" 4
+.IX Item "Can't kill a non-numeric process ID"
+(F) Process identifiers must be (signed) integers.  It is a fatal error to
+attempt to \fBkill()\fR an undefined, empty-string or otherwise non-numeric
+process identifier.
+.IP "Can't ""last"" outside a loop block" 4
+.IX Item "Can't ""last"" outside a loop block"
+(F) A "last" statement was executed to break out of the current block,
+except that there's this itty bitty problem called there isn't a current
+block.  Note that an "if" or "else" block doesn't count as a "loopish"
+block, as doesn't a block given to \fBsort()\fR, \fBmap()\fR or \fBgrep()\fR.  You can
+usually double the curlies to get the same effect though, because the
+inner curlies will be considered a block that loops once.  See
+"last" in perlfunc.
+.IP "Can't linearize anonymous symbol table" 4
+.IX Item "Can't linearize anonymous symbol table"
+(F) Perl tried to calculate the method resolution order (MRO) of a
+package, but failed because the package stash has no name.
+.ie n .IP "Can't load '%s' for module %s" 4
+.el .IP "Can't load '%s' for module \f(CW%s\fR" 4
+.IX Item "Can't load '%s' for module %s"
+(F) The module you tried to load failed to load a dynamic extension.
+This may either mean that you upgraded your version of perl to one
+that is incompatible with your old dynamic extensions (which is known
+to happen between major versions of perl), or (more likely) that your
+dynamic extension was built against an older version of the library
+that is installed on your system.  You may need to rebuild your old
+dynamic extensions.
+.ie n .IP "Can't localize lexical variable %s" 4
+.el .IP "Can't localize lexical variable \f(CW%s\fR" 4
+.IX Item "Can't localize lexical variable %s"
+(F) You used local on a variable name that was previously declared as a
+lexical variable using "my" or "state".  This is not allowed.  If you
+want to localize a package variable of the same name, qualify it with
+the package name.
+.IP "Can't localize through a reference" 4
+.IX Item "Can't localize through a reference"
+(F) You said something like \f(CW\*(C`local $$ref\*(C'\fR, which Perl can't currently
+handle, because when it goes to restore the old value of whatever \f(CW$ref\fR
+pointed to after the scope of the \fBlocal()\fR is finished, it can't be sure
+that \f(CW$ref\fR will still be a reference.
+.ie n .IP "Can't locate %s" 4
+.el .IP "Can't locate \f(CW%s\fR" 4
+.IX Item "Can't locate %s"
+(F) You said to \f(CW\*(C`do\*(C'\fR (or \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR) a file that couldn't be found.
+Perl looks for the file in all the locations mentioned in \f(CW@INC\fR, unless
+the file name included the full path to the file.  Perhaps you need
+to set the PERL5LIB or PERL5OPT environment variable to say where the
+extra library is, or maybe the script needs to add the library name
+to \f(CW@INC\fR.  Or maybe you just misspelled the name of the file.  See
+"require" in perlfunc and lib.
+.ie n .IP "Can't locate auto/%s.al in @INC" 4
+.el .IP "Can't locate auto/%s.al in \f(CW@INC\fR" 4
+.IX Item "Can't locate auto/%s.al in @INC"
+(F) A function (or method) was called in a package which allows
+autoload, but there is no function to autoload.  Most probable causes
+are a misprint in a function/method name or a failure to \f(CW\*(C`AutoSplit\*(C'\fR
+the file, say, by doing \f(CW\*(C`make install\*(C'\fR.
+.ie n .IP "Can't locate loadable object for module %s in @INC" 4
+.el .IP "Can't locate loadable object for module \f(CW%s\fR in \f(CW@INC\fR" 4
+.IX Item "Can't locate loadable object for module %s in @INC"
+(F) The module you loaded is trying to load an external library, like
+for example, \fIfoo.so\fR or \fIbar.dll\fR, but the DynaLoader module was
+unable to locate this library.  See DynaLoader.
+.IP "Can't locate object method ""%s"" via package ""%s""" 4
+.IX Item "Can't locate object method ""%s"" via package ""%s"""
+(F) You called a method correctly, and it correctly indicated a package
+functioning as a class, but that package doesn't define that particular
+method, nor does any of its base classes.  See perlobj.
+.IP "Can't locate object method ""%s"" via package ""%s"" (perhaps you forgot to load ""%s""?)" 4
+.IX Item "Can't locate object method ""%s"" via package ""%s"" (perhaps you forgot to load ""%s""?)"
+(F) You called a method on a class that did not exist, and the method
+could not be found in UNIVERSAL.  This often means that a method
+requires a package that has not been loaded.
+.ie n .IP "Can't locate object method ""INC"", nor ""INCDIR"" nor string overload via package ""%s"" %s in @INC" 4
+.el .IP "Can't locate object method ""INC"", nor ""INCDIR"" nor string overload via package ""%s"" \f(CW%s\fR in \f(CW@INC\fR" 4
+.IX Item "Can't locate object method ""INC"", nor ""INCDIR"" nor string overload via package ""%s"" %s in @INC"
+(F) You pushed an object, either directly or via an array reference hook,
+into \f(CW@INC\fR, but the object doesn't support any known hook methods, nor
+a string overload and is also not a blessed CODE reference. In short the
+\&\f(CW\*(C`require\*(C'\fR function does not know what to do with the object.
+See also "require" in perlfunc.
+.ie n .IP "Can't locate package %s for @%s::ISA" 4
+.el .IP "Can't locate package \f(CW%s\fR for @%s::ISA" 4
+.IX Item "Can't locate package %s for @%s::ISA"
+(W syntax) The \f(CW@ISA\fR array contained the name of another package that
+doesn't seem to exist.
+.IP "Can't locate PerlIO%s" 4
+.IX Item "Can't locate PerlIO%s"
+(F) You tried to use in \fBopen()\fR a PerlIO layer that does not exist,
+e.g. open(FH, ">:nosuchlayer", "somefile").
+.ie n .IP "Can't make list assignment to %ENV on this system" 4
+.el .IP "Can't make list assignment to \f(CW%ENV\fR on this system" 4
+.IX Item "Can't make list assignment to %ENV on this system"
+(F) List assignment to \f(CW%ENV\fR is not supported on some systems, notably
+VMS.
+.ie n .IP "Can't make loaded symbols global on this platform while loading %s" 4
+.el .IP "Can't make loaded symbols global on this platform while loading \f(CW%s\fR" 4
+.IX Item "Can't make loaded symbols global on this platform while loading %s"
+(S) A module passed the flag 0x01 to \fBDynaLoader::dl_load_file()\fR to request
+that symbols from the stated file are made available globally within the
+process, but that functionality is not available on this platform.  Whilst
+the module likely will still work, this may prevent the perl interpreter
+from loading other XS-based extensions which need to link directly to
+functions defined in the C or XS code in the stated file.
+.ie n .IP "Can't modify %s in %s" 4
+.el .IP "Can't modify \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "Can't modify %s in %s"
+(F) You aren't allowed to assign to the item indicated, or otherwise try
+to change it, such as with an auto-increment.
+.IP "Can't modify non-lvalue subroutine call of &%s" 4
+.IX Item "Can't modify non-lvalue subroutine call of &%s"
+.PD 0
+.ie n .IP "Can't modify non-lvalue subroutine call of &%s in %s" 4
+.el .IP "Can't modify non-lvalue subroutine call of &%s in \f(CW%s\fR" 4
+.IX Item "Can't modify non-lvalue subroutine call of &%s in %s"
+.PD
+(F) Subroutines meant to be used in lvalue context should be declared as
+such.  See "Lvalue subroutines" in perlsub.
+.ie n .IP "Can't modify reference to %s in %s assignment" 4
+.el .IP "Can't modify reference to \f(CW%s\fR in \f(CW%s\fR assignment" 4
+.IX Item "Can't modify reference to %s in %s assignment"
+(F) Only a limited number of constructs can be used as the argument to a
+reference constructor on the left-hand side of an assignment, and what
+you used was not one of them.  See "Assigning to References" in perlref.
+.IP "Can't modify reference to localized parenthesized array in list assignment" 4
+.IX Item "Can't modify reference to localized parenthesized array in list assignment"
+(F) Assigning to \f(CW\*(C`\elocal(@array)\*(C'\fR or \f(CW\*(C`\e(local @array)\*(C'\fR is not supported, as
+it is not clear exactly what it should do.  If you meant to make \f(CW@array\fR
+refer to some other array, use \f(CW\*(C`\e@array = \e@other_array\*(C'\fR.  If you want to
+make the elements of \f(CW@array\fR aliases of the scalars referenced on the
+right-hand side, use \f(CW\*(C`\e(@array) = @scalar_refs\*(C'\fR.
+.IP "Can't modify reference to parenthesized hash in list assignment" 4
+.IX Item "Can't modify reference to parenthesized hash in list assignment"
+(F) Assigning to \f(CW\*(C`\e(%hash)\*(C'\fR is not supported.  If you meant to make \f(CW%hash\fR
+refer to some other hash, use \f(CW\*(C`\e%hash = \e%other_hash\*(C'\fR.  If you want to
+make the elements of \f(CW%hash\fR into aliases of the scalars referenced on the
+right-hand side, use a hash slice: \f(CW\*(C`\e@hash{@keys} = @those_scalar_refs\*(C'\fR.
+.IP "Can't msgrcv to read-only var" 4
+.IX Item "Can't msgrcv to read-only var"
+(F) The target of a msgrcv must be modifiable to be used as a receive
+buffer.
+.IP "Can't ""next"" outside a loop block" 4
+.IX Item "Can't ""next"" outside a loop block"
+(F) A "next" statement was executed to reiterate the current block, but
+there isn't a current block.  Note that an "if" or "else" block doesn't
+count as a "loopish" block, as doesn't a block given to \fBsort()\fR, \fBmap()\fR or
+\&\fBgrep()\fR.  You can usually double the curlies to get the same effect
+though, because the inner curlies will be considered a block that loops
+once.  See "next" in perlfunc.
+.ie n .IP "Can't open %s: %s" 4
+.el .IP "Can't open \f(CW%s:\fR \f(CW%s\fR" 4
+.IX Item "Can't open %s: %s"
+(S inplace) The implicit opening of a file through use of the \f(CW\*(C`<>\*(C'\fR
+filehandle, either implicitly under the \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR command-line
+switches, or explicitly, failed for the indicated reason.  Usually
+this is because you don't have read permission for a file which
+you named on the command line.
+.Sp
+(F) You tried to call perl with the \fB\-e\fR switch, but \fI/dev/null\fR (or
+your operating system's equivalent) could not be opened.
+.IP "Can't open a reference" 4
+.IX Item "Can't open a reference"
+(W io) You tried to open a scalar reference for reading or writing,
+using the 3\-arg \fBopen()\fR syntax:
+.Sp
+.Vb 1
+\&    open FH, \*(Aq>\*(Aq, $ref;
+.Ve
+.Sp
+but your version of perl is compiled without perlio, and this form of
+open is not supported.
+.IP "Can't open bidirectional pipe" 4
+.IX Item "Can't open bidirectional pipe"
+(W pipe) You tried to say \f(CW\*(C`open(CMD, "|cmd|")\*(C'\fR, which is not supported.
+You can try any of several modules in the Perl library to do this, such
+as IPC::Open2.  Alternately, direct the pipe's output to a file using
+">", and then read it in under a different file handle.
+.ie n .IP "Can't open error file %s as stderr" 4
+.el .IP "Can't open error file \f(CW%s\fR as stderr" 4
+.IX Item "Can't open error file %s as stderr"
+(F) An error peculiar to VMS.  Perl does its own command line
+redirection, and couldn't open the file specified after '2>' or '2>>' on
+the command line for writing.
+.ie n .IP "Can't open input file %s as stdin" 4
+.el .IP "Can't open input file \f(CW%s\fR as stdin" 4
+.IX Item "Can't open input file %s as stdin"
+(F) An error peculiar to VMS.  Perl does its own command line
+redirection, and couldn't open the file specified after '<' on the
+command line for reading.
+.ie n .IP "Can't open output file %s as stdout" 4
+.el .IP "Can't open output file \f(CW%s\fR as stdout" 4
+.IX Item "Can't open output file %s as stdout"
+(F) An error peculiar to VMS.  Perl does its own command line
+redirection, and couldn't open the file specified after '>' or '>>' on
+the command line for writing.
+.ie n .IP "Can't open output pipe (name: %s)" 4
+.el .IP "Can't open output pipe (name: \f(CW%s\fR)" 4
+.IX Item "Can't open output pipe (name: %s)"
+(P) An error peculiar to VMS.  Perl does its own command line
+redirection, and couldn't open the pipe into which to send data destined
+for stdout.
+.ie n .IP "Can't open perl script ""%s"": %s" 4
+.el .IP "Can't open perl script ""%s"": \f(CW%s\fR" 4
+.IX Item "Can't open perl script ""%s"": %s"
+(F) The script you specified can't be opened for the indicated reason.
+.Sp
+If you're debugging a script that uses #!, and normally relies on the
+shell's \f(CW$PATH\fR search, the \-S option causes perl to do that search, so
+you don't have to type the path or \f(CW\`which $scriptname\`\fR.
+.IP "Can't read CRTL environ" 4
+.IX Item "Can't read CRTL environ"
+(S) A warning peculiar to VMS.  Perl tried to read an element of \f(CW%ENV\fR
+from the CRTL's internal environment array and discovered the array was
+missing.  You need to figure out where your CRTL misplaced its environ
+or define \fIPERL_ENV_TABLES\fR (see perlvms) so that environ is not
+searched.
+.IP "Can't redeclare ""%s"" in ""%s""" 4
+.IX Item "Can't redeclare ""%s"" in ""%s"""
+(F) A "my", "our" or "state" declaration was found within another declaration,
+such as \f(CW\*(C`my ($x, my($y), $z)\*(C'\fR or \f(CW\*(C`our (my $x)\*(C'\fR.
+.IP "Can't ""redo"" outside a loop block" 4
+.IX Item "Can't ""redo"" outside a loop block"
+(F) A "redo" statement was executed to restart the current block, but
+there isn't a current block.  Note that an "if" or "else" block doesn't
+count as a "loopish" block, as doesn't a block given to \fBsort()\fR, \fBmap()\fR
+or \fBgrep()\fR.  You can usually double the curlies to get the same effect
+though, because the inner curlies will be considered a block that
+loops once.  See "redo" in perlfunc.
+.ie n .IP "Can't remove %s: %s, skipping file" 4
+.el .IP "Can't remove \f(CW%s:\fR \f(CW%s\fR, skipping file" 4
+.IX Item "Can't remove %s: %s, skipping file"
+(S inplace) You requested an inplace edit without creating a backup
+file.  Perl was unable to remove the original file to replace it with
+the modified file.  The file was left unmodified.
+.ie n .IP "Can't rename in-place work file '%s' to '%s': %s" 4
+.el .IP "Can't rename in-place work file '%s' to '%s': \f(CW%s\fR" 4
+.IX Item "Can't rename in-place work file '%s' to '%s': %s"
+(F) When closed implicitly, the temporary file for in-place editing
+couldn't be renamed to the original filename.
+.ie n .IP "Can't rename %s to %s: %s, skipping file" 4
+.el .IP "Can't rename \f(CW%s\fR to \f(CW%s:\fR \f(CW%s\fR, skipping file" 4
+.IX Item "Can't rename %s to %s: %s, skipping file"
+(F) The rename done by the \fB\-i\fR switch failed for some reason,
+probably because you don't have write permission to the directory.
+.ie n .IP "Can't reopen input pipe (name: %s) in binary mode" 4
+.el .IP "Can't reopen input pipe (name: \f(CW%s\fR) in binary mode" 4
+.IX Item "Can't reopen input pipe (name: %s) in binary mode"
+(P) An error peculiar to VMS.  Perl thought stdin was a pipe, and tried
+to reopen it to accept binary data.  Alas, it failed.
+.IP "Can't represent character for Ox%X on this platform" 4
+.IX Item "Can't represent character for Ox%X on this platform"
+(F) There is a hard limit to how big a character code point can be due
+to the fundamental properties of UTF\-8, especially on EBCDIC
+platforms.  The given code point exceeds that.  The only work-around is
+to not use such a large code point.
+.ie n .IP "Can't reset %ENV on this system" 4
+.el .IP "Can't reset \f(CW%ENV\fR on this system" 4
+.IX Item "Can't reset %ENV on this system"
+(F) You called \f(CWreset(\*(AqE\*(Aq)\fR or similar, which tried to reset
+all variables in the current package beginning with "E".  In
+the main package, that includes \f(CW%ENV\fR.  Resetting \f(CW%ENV\fR is not
+supported on some systems, notably VMS.
+.IP "Can't resolve method ""%s"" overloading ""%s"" in package ""%s""" 4
+.IX Item "Can't resolve method ""%s"" overloading ""%s"" in package ""%s"""
+(F)(P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package.  If the method name is \f(CW\*(C`???\*(C'\fR, this is an internal error.
+.ie n .IP "Can't return %s from lvalue subroutine" 4
+.el .IP "Can't return \f(CW%s\fR from lvalue subroutine" 4
+.IX Item "Can't return %s from lvalue subroutine"
+(F) Perl detected an attempt to return illegal lvalues (such as
+temporary or readonly values) from a subroutine used as an lvalue.  This
+is not allowed.
+.IP "Can't return outside a subroutine" 4
+.IX Item "Can't return outside a subroutine"
+(F) The return statement was executed in mainline code, that is, where
+there was no subroutine call to return out of.  See perlsub.
+.ie n .IP "Can't return %s to lvalue scalar context" 4
+.el .IP "Can't return \f(CW%s\fR to lvalue scalar context" 4
+.IX Item "Can't return %s to lvalue scalar context"
+(F) You tried to return a complete array or hash from an lvalue
+subroutine, but you called the subroutine in a way that made Perl
+think you meant to return only one value.  You probably meant to
+write parentheses around the call to the subroutine, which tell
+Perl that the call should be in list context.
+.ie n .IP "Can't take log of %g" 4
+.el .IP "Can't take log of \f(CW%g\fR" 4
+.IX Item "Can't take log of %g"
+(F) For ordinary real numbers, you can't take the logarithm of a
+negative number or zero.  There's a Math::Complex package that comes
+standard with Perl, though, if you really want to do that for the
+negative numbers.
+.ie n .IP "Can't take sqrt of %g" 4
+.el .IP "Can't take sqrt of \f(CW%g\fR" 4
+.IX Item "Can't take sqrt of %g"
+(F) For ordinary real numbers, you can't take the square root of a
+negative number.  There's a Math::Complex package that comes standard
+with Perl, though, if you really want to do that.
+.IP "Can't undef active subroutine" 4
+.IX Item "Can't undef active subroutine"
+(F) You can't undefine a routine that's currently running.  You can,
+however, redefine it while it's running, and you can even undef the
+redefined subroutine while the old routine is running.  Go figure.
+.IP "Can't unweaken a nonreference" 4
+.IX Item "Can't unweaken a nonreference"
+(F) You attempted to unweaken something that was not a reference.  Only
+references can be unweakened.
+.ie n .IP "Can't upgrade %s (%d) to %d" 4
+.el .IP "Can't upgrade \f(CW%s\fR (%d) to \f(CW%d\fR" 4
+.IX Item "Can't upgrade %s (%d) to %d"
+(P) The internal sv_upgrade routine adds "members" to an SV, making it
+into a more specialized kind of SV.  The top several SV types are so
+specialized, however, that they cannot be interconverted.  This message
+indicates that such a conversion was attempted.
+.IP "Can't use '%c' after \-mname" 4
+.IX Item "Can't use '%c' after -mname"
+(F) You tried to call perl with the \fB\-m\fR switch, but you put something
+other than "=" after the module name.
+.IP "Can't use a hash as a reference" 4
+.IX Item "Can't use a hash as a reference"
+(F) You tried to use a hash as a reference, as in
+\&\f(CW\*(C`%foo\->{"bar"}\*(C'\fR or \f(CW\*(C`%$ref\->{"hello"}\*(C'\fR.  Versions of perl
+<= 5.22.0 used to allow this syntax, but shouldn't
+have.  This was deprecated in perl 5.6.1.
+.IP "Can't use an array as a reference" 4
+.IX Item "Can't use an array as a reference"
+(F) You tried to use an array as a reference, as in
+\&\f(CW\*(C`@foo\->[23]\*(C'\fR or \f(CW\*(C`@$ref\->[99]\*(C'\fR.  Versions of perl <= 5.22.0
+used to allow this syntax, but shouldn't have.  This
+was deprecated in perl 5.6.1.
+.IP "Can't use anonymous symbol table for method lookup" 4
+.IX Item "Can't use anonymous symbol table for method lookup"
+(F) The internal routine that does method lookup was handed a symbol
+table that doesn't have a name.  Symbol tables can become anonymous
+for example by undefining stashes: \f(CW\*(C`undef %Some::Package::\*(C'\fR.
+.ie n .IP "Can't use an undefined value as %s reference" 4
+.el .IP "Can't use an undefined value as \f(CW%s\fR reference" 4
+.IX Item "Can't use an undefined value as %s reference"
+(F) A value used as either a hard reference or a symbolic reference must
+be a defined value.  This helps to delurk some insidious errors.
+.ie n .IP "Can't use bareword (""%s"") as %s ref while ""strict refs"" in use" 4
+.el .IP "Can't use bareword (""%s"") as \f(CW%s\fR ref while ""strict refs"" in use" 4
+.IX Item "Can't use bareword (""%s"") as %s ref while ""strict refs"" in use"
+(F) Only hard references are allowed by "strict refs".  Symbolic
+references are disallowed.  See perlref.
+.IP "Can't use %! because Errno.pm is not available" 4
+.IX Item "Can't use %! because Errno.pm is not available"
+(F) The first time the \f(CW\*(C`%!\*(C'\fR hash is used, perl automatically loads the
+Errno.pm module.  The Errno module is expected to tie the %! hash to
+provide symbolic names for \f(CW$!\fR errno values.
+.ie n .IP "Can't use both '<' and '>' after type '%c' in %s" 4
+.el .IP "Can't use both '<' and '>' after type '%c' in \f(CW%s\fR" 4
+.IX Item "Can't use both '<' and '>' after type '%c' in %s"
+(F) A type cannot be forced to have both big-endian and little-endian
+byte-order at the same time, so this combination of modifiers is not
+allowed.  See "pack" in perlfunc.
+.IP "Can't use 'defined(@array)' (Maybe you should just omit the \fBdefined()\fR?)" 4
+.IX Item "Can't use 'defined(@array)' (Maybe you should just omit the defined()?)"
+(F) \fBdefined()\fR is not useful on arrays because it
+checks for an undefined \fIscalar\fR value.  If you want to see if the
+array is empty, just use \f(CW\*(C`if (@array) { # not empty }\*(C'\fR for example.
+.IP "Can't use 'defined(%hash)' (Maybe you should just omit the \fBdefined()\fR?)" 4
+.IX Item "Can't use 'defined(%hash)' (Maybe you should just omit the defined()?)"
+(F) \f(CWdefined()\fR is not usually right on hashes.
+.Sp
+Although \f(CW\*(C`defined %hash\*(C'\fR is false on a plain not-yet-used hash, it
+becomes true in several non-obvious circumstances, including iterators,
+weak references, stash names, even remaining true after \f(CW\*(C`undef %hash\*(C'\fR.
+These things make \f(CW\*(C`defined %hash\*(C'\fR fairly useless in practice, so it now
+generates a fatal error.
+.Sp
+If a check for non-empty is what you wanted then just put it in boolean
+context (see "Scalar values" in perldata):
+.Sp
+.Vb 3
+\&    if (%hash) {
+\&       # not empty
+\&    }
+.Ve
+.Sp
+If you had \f(CW\*(C`defined %Foo::Bar::QUUX\*(C'\fR to check whether such a package
+variable exists then that's never really been reliable, and isn't
+a good way to enquire about the features of a package, or whether
+it's loaded, etc.
+.ie n .IP "Can't use %s for loop variable" 4
+.el .IP "Can't use \f(CW%s\fR for loop variable" 4
+.IX Item "Can't use %s for loop variable"
+(P) The parser got confused when trying to parse a \f(CW\*(C`foreach\*(C'\fR loop.
+.ie n .IP "Can't use global %s in %s" 4
+.el .IP "Can't use global \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "Can't use global %s in %s"
+(F) You tried to declare a magical variable as a lexical variable.  This
+is not allowed, because the magic can be tied to only one location
+(namely the global variable) and it would be incredibly confusing to
+have variables in your program that looked like magical variables but
+weren't.
+.ie n .IP "Can't use '%c' in a group with different byte-order in %s" 4
+.el .IP "Can't use '%c' in a group with different byte-order in \f(CW%s\fR" 4
+.IX Item "Can't use '%c' in a group with different byte-order in %s"
+(F) You attempted to force a different byte-order on a type
+that is already inside a group with a byte-order modifier.
+For example you cannot force little-endianness on a type that
+is inside a big-endian group.
+.ie n .IP "Can't use ""my %s"" in sort comparison" 4
+.el .IP "Can't use ""my \f(CW%s\fR"" in sort comparison" 4
+.IX Item "Can't use ""my %s"" in sort comparison"
+(F) The global variables \f(CW$a\fR and \f(CW$b\fR are reserved for sort comparisons.
+You mentioned \f(CW$a\fR or \f(CW$b\fR in the same line as the <=> or cmp operator,
+and the variable had earlier been declared as a lexical variable.
+Either qualify the sort variable with the package name, or rename the
+lexical variable.
+.ie n .IP "Can't use %s ref as %s ref" 4
+.el .IP "Can't use \f(CW%s\fR ref as \f(CW%s\fR ref" 4
+.IX Item "Can't use %s ref as %s ref"
+(F) You've mixed up your reference types.  You have to dereference a
+reference of the type needed.  You can use the \fBref()\fR function to
+test the type of the reference, if need be.
+.ie n .IP "Can't use string (""%s"") as %s ref while ""strict refs"" in use" 4
+.el .IP "Can't use string (""%s"") as \f(CW%s\fR ref while ""strict refs"" in use" 4
+.IX Item "Can't use string (""%s"") as %s ref while ""strict refs"" in use"
+.PD 0
+.ie n .IP "Can't use string (""%s""...) as %s ref while ""strict refs"" in use" 4
+.el .IP "Can't use string (""%s""...) as \f(CW%s\fR ref while ""strict refs"" in use" 4
+.IX Item "Can't use string (""%s""...) as %s ref while ""strict refs"" in use"
+.PD
+(F) You've told Perl to dereference a string, something which
+\&\f(CW\*(C`use strict\*(C'\fR blocks to prevent it happening accidentally.  See
+"Symbolic references" in perlref.  This can be triggered by an \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`$\*(C'\fR
+in a double-quoted string immediately before interpolating a variable,
+for example in \f(CW"user @$twitter_id"\fR, which says to treat the contents
+of \f(CW$twitter_id\fR as an array reference; use a \f(CW\*(C`\e\*(C'\fR to have a literal \f(CW\*(C`@\*(C'\fR
+symbol followed by the contents of \f(CW$twitter_id\fR: \f(CW"user \e@$twitter_id"\fR.
+.ie n .IP "Can't use subscript on %s" 4
+.el .IP "Can't use subscript on \f(CW%s\fR" 4
+.IX Item "Can't use subscript on %s"
+(F) The compiler tried to interpret a bracketed expression as a
+subscript.  But to the left of the brackets was an expression that
+didn't look like a hash or array reference, or anything else subscriptable.
+.IP "Can't use \e%c to mean $%c in expression" 4
+.IX Item "Can't use %c to mean $%c in expression"
+(W syntax) In an ordinary expression, backslash is a unary operator that
+creates a reference to its argument.  The use of backslash to indicate a
+backreference to a matched substring is valid only as part of a regular
+expression pattern.  Trying to do this in ordinary Perl code produces a
+value that prints out looking like \fBSCALAR\fR\|(0xdecaf).  Use the \f(CW$1\fR form
+instead.
+.IP "Can't weaken a nonreference" 4
+.IX Item "Can't weaken a nonreference"
+(F) You attempted to weaken something that was not a reference.  Only
+references can be weakened.
+.IP "Can't ""when"" outside a topicalizer" 4
+.IX Item "Can't ""when"" outside a topicalizer"
+(F) You have used a \fBwhen()\fR block that is neither inside a \f(CW\*(C`foreach\*(C'\fR
+loop nor a \f(CW\*(C`given\*(C'\fR block.  (Note that this error is issued on exit
+from the \f(CW\*(C`when\*(C'\fR block, so you won't get the error if the match fails,
+or if you use an explicit \f(CW\*(C`continue\*(C'\fR.)
+.IP "Can't x= to read-only value" 4
+.IX Item "Can't x= to read-only value"
+(F) You tried to repeat a constant value (often the undefined value)
+with an assignment operator, which implies modifying the value itself.
+Perhaps you need to copy the value to a temporary, and repeat that.
+.IP "catch block requires a (VAR)" 4
+.IX Item "catch block requires a (VAR)"
+(F) You tried to use the \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR syntax of \f(CW\*(C`use feature \*(Aqtry\*(Aq\*(C'\fR
+but did not include the error variable in the \f(CW\*(C`catch\*(C'\fR block. The
+parenthesized variable name is not optional, unlike in some other forms of
+syntax you may be familiar with from CPAN modules or other languages.
+.Sp
+The required syntax is
+.Sp
+.Vb 2
+\&    try { ... }
+\&    catch ($var) { ... }
+.Ve
+.IP "Character following ""\ec"" must be printable ASCII" 4
+.IX Item "Character following ""c"" must be printable ASCII"
+(F) In \f(CW\*(C`\ec\fR\f(CIX\fR\f(CW\*(C'\fR, \fIX\fR must be a printable (non-control) ASCII character.
+.Sp
+Note that ASCII characters that don't map to control characters are
+discouraged, and will generate the warning (when enabled)
+""\ec%c" is more clearly written simply as "%s"".
+.IP "Character following \e%c must be '{' or a single-character Unicode property name in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Character following %c must be '{' or a single-character Unicode property name in regex; marked by <-- HERE in m/%s/"
+(F) (In the above the \f(CW%c\fR is replaced by either \f(CW\*(C`p\*(C'\fR or \f(CW\*(C`P\*(C'\fR.)  You
+specified something that isn't a legal Unicode property name.  Most
+Unicode properties are specified by \f(CW\*(C`\ep{...}\*(C'\fR.  But if the name is a
+single character one, the braces may be omitted.
+.IP "Character in 'C' format wrapped in pack" 4
+.IX Item "Character in 'C' format wrapped in pack"
+(W pack) You said
+.Sp
+.Vb 1
+\&    pack("C", $x)
+.Ve
+.Sp
+where \f(CW$x\fR is either less than 0 or more than 255; the \f(CW"C"\fR format is
+only for encoding native operating system characters (ASCII, EBCDIC,
+and so on) and not for Unicode characters, so Perl behaved as if you meant
+.Sp
+.Vb 1
+\&    pack("C", $x & 255)
+.Ve
+.Sp
+If you actually want to pack Unicode codepoints, use the \f(CW"U"\fR format
+instead.
+.IP "Character in 'c' format wrapped in pack" 4
+.IX Item "Character in 'c' format wrapped in pack"
+(W pack) You said
+.Sp
+.Vb 1
+\&    pack("c", $x)
+.Ve
+.Sp
+where \f(CW$x\fR is either less than \-128 or more than 127; the \f(CW"c"\fR format
+is only for encoding native operating system characters (ASCII, EBCDIC,
+and so on) and not for Unicode characters, so Perl behaved as if you meant
+.Sp
+.Vb 1
+\&    pack("c", $x & 255);
+.Ve
+.Sp
+If you actually want to pack Unicode codepoints, use the \f(CW"U"\fR format
+instead.
+.IP "Character in '%c' format wrapped in unpack" 4
+.IX Item "Character in '%c' format wrapped in unpack"
+(W unpack) You tried something like
+.Sp
+.Vb 1
+\&   unpack("H", "\ex{2a1}")
+.Ve
+.Sp
+where the format expects to process a byte (a character with a value
+below 256), but a higher value was provided instead.  Perl uses the
+value modulus 256 instead, as if you had provided:
+.Sp
+.Vb 1
+\&   unpack("H", "\ex{a1}")
+.Ve
+.IP "Character in 'W' format wrapped in pack" 4
+.IX Item "Character in 'W' format wrapped in pack"
+(W pack) You said
+.Sp
+.Vb 1
+\&    pack("U0W", $x)
+.Ve
+.Sp
+where \f(CW$x\fR is either less than 0 or more than 255.  However, \f(CW\*(C`U0\*(C'\fR\-mode
+expects all values to fall in the interval [0, 255], so Perl behaved
+as if you meant:
+.Sp
+.Vb 1
+\&    pack("U0W", $x & 255)
+.Ve
+.IP "Character(s) in '%c' format wrapped in pack" 4
+.IX Item "Character(s) in '%c' format wrapped in pack"
+(W pack) You tried something like
+.Sp
+.Vb 1
+\&   pack("u", "\ex{1f3}b")
+.Ve
+.Sp
+where the format expects to process a sequence of bytes (character with a
+value below 256), but some of the characters had a higher value.  Perl
+uses the character values modulus 256 instead, as if you had provided:
+.Sp
+.Vb 1
+\&   pack("u", "\ex{f3}b")
+.Ve
+.IP "Character(s) in '%c' format wrapped in unpack" 4
+.IX Item "Character(s) in '%c' format wrapped in unpack"
+(W unpack) You tried something like
+.Sp
+.Vb 1
+\&   unpack("s", "\ex{1f3}b")
+.Ve
+.Sp
+where the format expects to process a sequence of bytes (character with a
+value below 256), but some of the characters had a higher value.  Perl
+uses the character values modulus 256 instead, as if you had provided:
+.Sp
+.Vb 1
+\&   unpack("s", "\ex{f3}b")
+.Ve
+.ie n .IP "charnames alias definitions may not contain a sequence of multiple spaces; marked by <\-\-\ HERE in %s" 4
+.el .IP "charnames alias definitions may not contain a sequence of multiple spaces; marked by <\-\-\ HERE in \f(CW%s\fR" 4
+.IX Item "charnames alias definitions may not contain a sequence of multiple spaces; marked by <--\ HERE in %s"
+(F) You defined a character name which had multiple space characters
+in a row.  Change them to single spaces.  Usually these names are
+defined in the \f(CW\*(C`:alias\*(C'\fR import argument to \f(CW\*(C`use charnames\*(C'\fR, but they
+could be defined by a translator installed into \f(CW$^H{charnames}\fR.  See
+"CUSTOM ALIASES" in charnames.
+.ie n .IP "\fBchdir()\fR on unopened filehandle %s" 4
+.el .IP "\fBchdir()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "chdir() on unopened filehandle %s"
+(W unopened) You tried \fBchdir()\fR on a filehandle that was never opened.
+.IP """\ec%c"" is more clearly written simply as ""%s""" 4
+.IX Item """c%c"" is more clearly written simply as ""%s"""
+(W syntax) The \f(CW\*(C`\ec\fR\f(CIX\fR\f(CW\*(C'\fR construct is intended to be a way to specify
+non-printable characters.  You used it for a printable one, which
+is better written as simply itself, perhaps preceded by a backslash
+for non-word characters.  Doing it the way you did is not portable
+between ASCII and EBCDIC platforms.
+.IP "Class already has a superclass, cannot add another" 4
+.IX Item "Class already has a superclass, cannot add another"
+(F) You attempted to specify a second superclass for a \f(CW\*(C`class\*(C'\fR by using
+the \f(CW\*(C`:isa\*(C'\fR attribute, when one is already specified.  Unlike classes
+whose instances are created with \f(CW\*(C`bless\*(C'\fR, classes created via the
+\&\f(CW\*(C`class\*(C'\fR keyword cannot have more than one superclass.
+.ie n .IP "Class attribute %s requires a value" 4
+.el .IP "Class attribute \f(CW%s\fR requires a value" 4
+.IX Item "Class attribute %s requires a value"
+(F) You specified an attribute for a class that would require a value to
+be passed in parentheses, but did not provide one.  Remember that
+whitespace is \fBnot\fR permitted between the attribute name and its value;
+you must write this as
+.Sp
+.Vb 1
+\&    class Example::Class :attr(VALUE) ...
+.Ve
+.IP "class is experimental" 4
+.IX Item "class is experimental"
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`class\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.IP "Class :isa attribute requires a class but ""%s"" is not one" 4
+.IX Item "Class :isa attribute requires a class but ""%s"" is not one"
+(F) When creating a subclass using the \f(CW\*(C`class\*(C'\fR \f(CW\*(C`:isa\*(C'\fR attribute, the
+named superclass must also be a real class created using the \f(CW\*(C`class\*(C'\fR
+keyword.
+.IP "Cloning substitution context is unimplemented" 4
+.IX Item "Cloning substitution context is unimplemented"
+(F) Creating a new thread inside the \f(CW\*(C`s///\*(C'\fR operator is not supported.
+.ie n .IP "\fBclosedir()\fR attempted on invalid dirhandle %s" 4
+.el .IP "\fBclosedir()\fR attempted on invalid dirhandle \f(CW%s\fR" 4
+.IX Item "closedir() attempted on invalid dirhandle %s"
+(W io) The dirhandle you tried to close is either closed or not really
+a dirhandle.  Check your control flow.
+.ie n .IP "\fBclose()\fR on unopened filehandle %s" 4
+.el .IP "\fBclose()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "close() on unopened filehandle %s"
+(W unopened) You tried to close a filehandle that was never opened.
+.IP "Closure prototype called" 4
+.IX Item "Closure prototype called"
+(F) If a closure has attributes, the subroutine passed to an attribute
+handler is the prototype that is cloned when a new closure is created.
+This subroutine cannot be called.
+.IP "\eC no longer supported in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "C no longer supported in regex; marked by <--\ HERE in m/%s/"
+(F) The \eC character class used to allow a match of single byte
+within a multi-byte utf\-8 character, but was removed in v5.24 as
+it broke encapsulation and its implementation was extremely buggy.
+If you really need to process the individual bytes, you probably
+want to convert your string to one where each underlying byte is
+stored as a character, with \fButf8::encode()\fR.
+.IP "Code missing after '/'" 4
+.IX Item "Code missing after '/'"
+(F) You had a (sub\-)template that ends with a '/'.  There must be
+another template code following the slash.  See "pack" in perlfunc.
+.IP "Code point 0x%X is not Unicode, and not portable" 4
+.IX Item "Code point 0x%X is not Unicode, and not portable"
+(S non_unicode portable) You had a code point that has never been in any
+standard, so it is likely that languages other than Perl will NOT
+understand it.  This code point also will not fit in a 32\-bit word on
+ASCII platforms and therefore is non-portable between systems.
+.Sp
+At one time, it was legal in some standards to have code points up to
+0x7FFF_FFFF, but not higher, and this code point is higher.
+.Sp
+Acceptance of these code points is a Perl extension, and you should
+expect that nothing other than Perl can handle them; Perl itself on
+EBCDIC platforms before v5.24 does not handle them.
+.Sp
+Perl also makes no guarantees that the representation of these code
+points won't change at some point in the future, say when machines
+become available that have larger than a 64\-bit word.  At that time,
+files containing any of these, written by an older Perl might require
+conversion before being readable by a newer Perl.
+.IP "Code point 0x%X is not Unicode, may not be portable" 4
+.IX Item "Code point 0x%X is not Unicode, may not be portable"
+(S non_unicode) You had a code point above the Unicode maximum
+of U+10FFFF.
+.Sp
+Perl allows strings to contain a superset of Unicode code points, but
+these may not be accepted by other languages/systems.  Further, even if
+these languages/systems accept these large code points, they may have
+chosen a different representation for them than the UTF\-8\-like one that
+Perl has, which would mean files are not exchangeable between them and
+Perl.
+.Sp
+On EBCDIC platforms, code points above 0x3FFF_FFFF have a different
+representation in Perl v5.24 than before, so any file containing these
+that was written before that version will require conversion before
+being readable by a later Perl.
+.ie n .IP "%s: Command not found" 4
+.el .IP "\f(CW%s:\fR Command not found" 4
+.IX Item "%s: Command not found"
+(A) You've accidentally run your script through \fBcsh\fR or another shell
+instead of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.  The #! line at the top of your file could look like
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl
+.Ve
+.ie n .IP "%s: command not found" 4
+.el .IP "\f(CW%s:\fR command not found" 4
+.IX Item "%s: command not found"
+(A) You've accidentally run your script through \fBbash\fR or another shell
+instead of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.  The #! line at the top of your file could look like
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl
+.Ve
+.ie n .IP "%s: command not found: %s" 4
+.el .IP "\f(CW%s:\fR command not found: \f(CW%s\fR" 4
+.IX Item "%s: command not found: %s"
+(A) You've accidentally run your script through \fBzsh\fR or another shell
+instead of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.  The #! line at the top of your file could look like
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl
+.Ve
+.IP "Compilation failed in require" 4
+.IX Item "Compilation failed in require"
+(F) Perl could not compile a file specified in a \f(CW\*(C`require\*(C'\fR statement.
+Perl uses this generic message when none of the errors that it
+encountered were severe enough to halt compilation immediately.
+.ie n .IP "\fBconnect()\fR on closed socket %s" 4
+.el .IP "\fBconnect()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "connect() on closed socket %s"
+(W closed) You tried to do a connect on a closed socket.  Did you forget
+to check the return value of your \fBsocket()\fR call?  See
+"connect" in perlfunc.
+.IP "Constant(%s): Call to &{$^H{%s}} did not return a defined value" 4
+.IX Item "Constant(%s): Call to &{$^H{%s}} did not return a defined value"
+(F) The subroutine registered to handle constant overloading
+(see overload) or a custom charnames handler (see
+"CUSTOM TRANSLATORS" in charnames) returned an undefined value.
+.IP "Constant(%s): $^H{%s} is not defined" 4
+.IX Item "Constant(%s): $^H{%s} is not defined"
+(F) The parser found inconsistencies while attempting to define an
+overloaded constant.  Perhaps you forgot to load the corresponding
+overload pragma?
+.ie n .IP "Constant is not %s reference" 4
+.el .IP "Constant is not \f(CW%s\fR reference" 4
+.IX Item "Constant is not %s reference"
+(F) A constant value (perhaps declared using the \f(CW\*(C`use constant\*(C'\fR pragma)
+is being dereferenced, but it amounts to the wrong type of reference.
+The message indicates the type of reference that was expected.  This
+usually indicates a syntax error in dereferencing the constant value.
+See "Constant Functions" in perlsub and constant.
+.IP "Constants from lexical variables potentially modified elsewhere are no longer permitted" 4
+.IX Item "Constants from lexical variables potentially modified elsewhere are no longer permitted"
+(F) You wrote something like
+.Sp
+.Vb 2
+\&    my $var;
+\&    $sub = sub () { $var };
+.Ve
+.Sp
+but \f(CW$var\fR is referenced elsewhere and could be modified after the \f(CW\*(C`sub\*(C'\fR
+expression is evaluated.  Either it is explicitly modified elsewhere
+(\f(CW\*(C`$var = 3\*(C'\fR) or it is passed to a subroutine or to an operator like
+\&\f(CW\*(C`printf\*(C'\fR or \f(CW\*(C`map\*(C'\fR, which may or may not modify the variable.
+.Sp
+Traditionally, Perl has captured the value of the variable at that
+point and turned the subroutine into a constant eligible for inlining.
+In those cases where the variable can be modified elsewhere, this
+breaks the behavior of closures, in which the subroutine captures
+the variable itself, rather than its value, so future changes to the
+variable are reflected in the subroutine's return value.
+.Sp
+This usage was deprecated, and as of Perl 5.32 is no longer allowed,
+making it possible to change the behavior in the future.
+.Sp
+If you intended for the subroutine to be eligible for inlining, then
+make sure the variable is not referenced elsewhere, possibly by
+copying it:
+.Sp
+.Vb 2
+\&    my $var2 = $var;
+\&    $sub = sub () { $var2 };
+.Ve
+.Sp
+If you do want this subroutine to be a closure that reflects future
+changes to the variable that it closes over, add an explicit \f(CW\*(C`return\*(C'\fR:
+.Sp
+.Vb 2
+\&    my $var;
+\&    $sub = sub () { return $var };
+.Ve
+.ie n .IP "Constant subroutine %s redefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR redefined" 4
+.IX Item "Constant subroutine %s redefined"
+(W redefine)(S) You redefined a subroutine which had previously
+been eligible for inlining.  See "Constant Functions" in perlsub
+for commentary and workarounds.
+.ie n .IP "Constant subroutine %s undefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR undefined" 4
+.IX Item "Constant subroutine %s undefined"
+(W misc) You undefined a subroutine which had previously been eligible
+for inlining.  See "Constant Functions" in perlsub for commentary and
+workarounds.
+.IP "Constant(%s) unknown" 4
+.IX Item "Constant(%s) unknown"
+(F) The parser found inconsistencies either while attempting
+to define an overloaded constant, or when trying to find the
+character name specified in the \f(CW\*(C`\eN{...}\*(C'\fR escape.  Perhaps you
+forgot to load the corresponding overload pragma?
+.IP ":const is experimental" 4
+.IX Item ":const is experimental"
+(S experimental::const_attr) The "const" attribute is experimental.
+If you want to use the feature, disable the warning with \f(CWno warnings
+\&\*(Aqexperimental::const_attr\*(Aq\fR, but know that in doing so you are taking
+the risk that your code may break in a future Perl version.
+.IP ":const is not permitted on named subroutines" 4
+.IX Item ":const is not permitted on named subroutines"
+(F) The "const" attribute causes an anonymous subroutine to be run and
+its value captured at the time that it is cloned.  Named subroutines are
+not cloned like this, so the attribute does not make sense on them.
+.IP "Copy method did not return a reference" 4
+.IX Item "Copy method did not return a reference"
+(F) The method which overloads "=" is buggy.  See
+"Copy Constructor" in overload.
+.IP "&CORE::%s cannot be called directly" 4
+.IX Item "&CORE::%s cannot be called directly"
+(F) You tried to call a subroutine in the \f(CW\*(C`CORE::\*(C'\fR namespace
+with \f(CW&foo\fR syntax or through a reference.  Some subroutines
+in this package cannot yet be called that way, but must be
+called as barewords.  Something like this will work:
+.Sp
+.Vb 2
+\&    BEGIN { *shove = \e&CORE::push; }
+\&    shove @array, 1,2,3; # pushes on to @array
+.Ve
+.IP "CORE::%s is not a keyword" 4
+.IX Item "CORE::%s is not a keyword"
+(F) The CORE:: namespace is reserved for Perl keywords.
+.ie n .IP "Corrupted regexp opcode %d > %d" 4
+.el .IP "Corrupted regexp opcode \f(CW%d\fR > \f(CW%d\fR" 4
+.IX Item "Corrupted regexp opcode %d > %d"
+(P) This is either an error in Perl, or, if you're using
+one, your custom regular expression engine.  If not the
+latter, report the problem to <https://github.com/Perl/perl5/issues/new/choose>.
+.IP "corrupted regexp pointers" 4
+.IX Item "corrupted regexp pointers"
+(P) The regular expression engine got confused by what the regular
+expression compiler gave it.
+.IP "corrupted regexp program" 4
+.IX Item "corrupted regexp program"
+(P) The regular expression engine got passed a regexp program without a
+valid magic number.
+.IP "Corrupt malloc ptr 0x%x at 0x%x" 4
+.IX Item "Corrupt malloc ptr 0x%x at 0x%x"
+(P) The malloc package that comes with Perl had an internal failure.
+.IP "Count after length/code in unpack" 4
+.IX Item "Count after length/code in unpack"
+(F) You had an unpack template indicating a counted-length string, but
+you have also specified an explicit size for the string.  See
+"pack" in perlfunc.
+.IP "Declaring references is experimental" 4
+.IX Item "Declaring references is experimental"
+(S experimental::declared_refs) This warning is emitted if you use
+a reference constructor on the right-hand side of \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`state\*(C'\fR, \f(CW\*(C`our\*(C'\fR, or
+\&\f(CW\*(C`local\*(C'\fR.  Simply suppress the warning if you want to use the feature, but
+know that in doing so you are taking the risk of using an experimental
+feature which may change or be removed in a future Perl version:
+.Sp
+.Vb 3
+\&    no warnings "experimental::declared_refs";
+\&    use feature "declared_refs";
+\&    $fooref = my \e$foo;
+.Ve
+.IP "Deep recursion on anonymous subroutine" 4
+.IX Item "Deep recursion on anonymous subroutine"
+.PD 0
+.IP "Deep recursion on subroutine ""%s""" 4
+.IX Item "Deep recursion on subroutine ""%s"""
+.PD
+(W recursion) This subroutine has called itself (directly or indirectly)
+100 times more than it has returned.  This probably indicates an
+infinite recursion, unless you're writing strange benchmark programs, in
+which case it indicates something else.
+.Sp
+This threshold can be changed from 100, by recompiling the \fIperl\fR binary,
+setting the C pre-processor macro \f(CW\*(C`PERL_SUB_DEPTH_WARN\*(C'\fR to the desired value.
+.IP "(?(DEFINE)....) does not allow branches in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "(?(DEFINE)....) does not allow branches in regex; marked by <--\ HERE in m/%s/"
+(F) You used something like \f(CW\*(C`(?(DEFINE)...|..)\*(C'\fR which is illegal.  The
+most likely cause of this error is that you left out a parenthesis inside
+of the \f(CW\*(C`....\*(C'\fR part.
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.ie n .IP "%s defines neither package nor VERSION\-\-version check failed" 4
+.el .IP "\f(CW%s\fR defines neither package nor VERSION\-\-version check failed" 4
+.IX Item "%s defines neither package nor VERSION--version check failed"
+(F) You said something like "use Module 42" but in the Module file
+there are neither package declarations nor a \f(CW$VERSION\fR.
+.IP "delete argument is not a HASH or ARRAY element or slice" 4
+.IX Item "delete argument is not a HASH or ARRAY element or slice"
+(F) The argument to \f(CW\*(C`delete\*(C'\fR must be either a hash or array element,
+such as:
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+.Ve
+.Sp
+or a hash or array slice, such as:
+.Sp
+.Vb 2
+\&    @foo[$bar, $baz, $xyzzy]
+\&    $ref\->[12]\->@{"susie", "queue"}
+.Ve
+.Sp
+or a hash key/value or array index/value slice, such as:
+.Sp
+.Vb 2
+\&    %foo[$bar, $baz, $xyzzy]
+\&    $ref\->[12]\->%{"susie", "queue"}
+.Ve
+.IP "Delimiter for here document is too long" 4
+.IX Item "Delimiter for here document is too long"
+(F) In a here document construct like \f(CW\*(C`<<FOO\*(C'\fR, the label \f(CW\*(C`FOO\*(C'\fR is too
+long for Perl to handle.  You have to be seriously twisted to write code
+that triggers this error.
+.IP "DESTROY created new reference to dead object '%s'" 4
+.IX Item "DESTROY created new reference to dead object '%s'"
+(F) A \fBDESTROY()\fR method created a new reference to the object which is
+just being DESTROYed.  Perl is confused, and prefers to abort rather
+than to create a dangling reference.
+.IP "Did not produce a valid header" 4
+.IX Item "Did not produce a valid header"
+See "500 Server error".
+.ie n .IP "%s did not return a true value" 4
+.el .IP "\f(CW%s\fR did not return a true value" 4
+.IX Item "%s did not return a true value"
+(F) A required (or used) file must return a true value to indicate that
+it compiled correctly and ran its initialization code correctly.  It's
+traditional to end such a file with a "1;", though any true value would
+do.  See "require" in perlfunc.
+.IP "(Did you mean &%s instead?)" 4
+.IX Item "(Did you mean &%s instead?)"
+(W misc) You probably referred to an imported subroutine &FOO as \f(CW$FOO\fR or
+some such.
+.IP "(Did you mean ""local"" instead of ""our""?)" 4
+.IX Item "(Did you mean ""local"" instead of ""our""?)"
+(W shadow) Remember that "our" does not localize the declared global
+variable.  You have declared it again in the same lexical scope, which
+seems superfluous.
+.IP "(Did you mean $ or @ instead of %?)" 4
+.IX Item "(Did you mean $ or @ instead of %?)"
+(W) You probably said \f(CW%hash\fR{$key} when you meant \f(CW$hash\fR{$key} or
+\&\f(CW@hash\fR{@keys}.  On the other hand, maybe you just meant \f(CW%hash\fR and got
+carried away.
+.IP Died 4
+.IX Item "Died"
+(F) You passed \fBdie()\fR an empty string (the equivalent of \f(CW\*(C`die ""\*(C'\fR) or
+you called it with no args and \f(CW$@\fR was empty.
+.IP "Document contains no data" 4
+.IX Item "Document contains no data"
+See "500 Server error".
+.ie n .IP "%s does not define %s::VERSION\-\-version check failed" 4
+.el .IP "\f(CW%s\fR does not define \f(CW%s::VERSION\fR\-\-version check failed" 4
+.IX Item "%s does not define %s::VERSION--version check failed"
+(F) You said something like "use Module 42" but the Module did not
+define a \f(CW$VERSION\fR.
+.ie n .IP "'/' does not take a repeat count in %s" 4
+.el .IP "'/' does not take a repeat count in \f(CW%s\fR" 4
+.IX Item "'/' does not take a repeat count in %s"
+(F) You cannot put a repeat count of any kind right after the '/' code.
+See "pack" in perlfunc.
+.ie n .IP "do ""%s"" failed, '.' is no longer in @INC; did you mean do ""./%s""?" 4
+.el .IP "do ""%s"" failed, '.' is no longer in \f(CW@INC\fR; did you mean do ""./%s""?" 4
+.IX Item "do ""%s"" failed, '.' is no longer in @INC; did you mean do ""./%s""?"
+(D deprecated::dot_in_inc) Previously \f(CW\*(C` do "somefile"; \*(C'\fR would search
+the current directory for the specified file. Since perl v5.26.0, \fI.\fR
+has been removed from \f(CW@INC\fR by default, so this is no longer true. To
+search the current directory (and only the current directory) you can
+write \f(CW\*(C` do "./somefile"; \*(C'\fR.
+.IP "Don't know how to get file name" 4
+.IX Item "Don't know how to get file name"
+(P) \f(CW\*(C`PerlIO_getname\*(C'\fR, a perl internal I/O function specific to VMS, was
+somehow called on another platform.  This should not happen.
+.IP "Don't know how to handle magic of type \e%o" 4
+.IX Item "Don't know how to handle magic of type %o"
+(P) The internal handling of magical variables has been cursed.
+.IP "Downgrading a use VERSION declaration to below v5.11 is deprecated" 4
+.IX Item "Downgrading a use VERSION declaration to below v5.11 is deprecated"
+(S deprecated::version_downgrade) This warning is emitted on a
+\&\f(CW\*(C`use VERSION\*(C'\fR statement that requests a version below v5.11 (when the
+effects of \f(CW\*(C`use strict\*(C'\fR would be disabled), after a previous
+declaration of one having a larger number (which would have enabled
+these effects). Because of a change to the way that \f(CW\*(C`use VERSION\*(C'\fR
+interacts with the strictness flags, this is no longer supported.
+.ie n .IP "(Do you need to predeclare %s?)" 4
+.el .IP "(Do you need to predeclare \f(CW%s\fR?)" 4
+.IX Item "(Do you need to predeclare %s?)"
+(S syntax) This is an educated guess made in conjunction with the message
+"%s found where operator expected".  It often means a subroutine or module
+name is being referenced that hasn't been declared yet.  This may be
+because of ordering problems in your file, or because of a missing
+"sub", "package", "require", or "use" statement.  If you're referencing
+something that isn't defined yet, you don't actually have to define the
+subroutine or package before the current location.  You can use an empty
+"sub foo;" or "package FOO;" to enter a "forward" declaration.
+.IP "\fBdump()\fR must be written as \fBCORE::dump()\fR as of Perl 5.30" 4
+.IX Item "dump() must be written as CORE::dump() as of Perl 5.30"
+(F) You used the obsolete \f(CWdump()\fR built-in function.  That was deprecated in
+Perl 5.8.0.  As of Perl 5.30 it must be written in fully qualified format:
+\&\f(CWCORE::dump()\fR.
+.Sp
+See "dump" in perlfunc.
+.IP "dump is not supported" 4
+.IX Item "dump is not supported"
+(F) Your machine doesn't support dump/undump.
+.IP "Duplicate \fBfree()\fR ignored" 4
+.IX Item "Duplicate free() ignored"
+(S malloc) An internal routine called \fBfree()\fR on something that had
+already been freed.
+.ie n .IP "Duplicate modifier '%c' after '%c' in %s" 4
+.el .IP "Duplicate modifier '%c' after '%c' in \f(CW%s\fR" 4
+.IX Item "Duplicate modifier '%c' after '%c' in %s"
+(W unpack) You have applied the same modifier more than once after a
+type in a pack template.  See "pack" in perlfunc.
+.ie n .IP "each on anonymous %s will always start from the beginning" 4
+.el .IP "each on anonymous \f(CW%s\fR will always start from the beginning" 4
+.IX Item "each on anonymous %s will always start from the beginning"
+(W syntax) You called each on an anonymous hash or
+array.  Since a new hash or array is created each time, \fBeach()\fR will
+restart iterating over your hash or array every time.
+.IP "elseif should be elsif" 4
+.IX Item "elseif should be elsif"
+(S syntax) There is no keyword "elseif" in Perl because Larry thinks
+it's ugly.  Your code will be interpreted as an attempt to call a method
+named "elseif" for the class returned by the following block.  This is
+unlikely to be what you want.
+.IP "Empty \e%c in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Empty %c in regex; marked by <--\ HERE in m/%s/"
+.PD 0
+.IP "Empty \e%c{}" 4
+.IX Item "Empty %c{}"
+.IP "Empty \e%c{} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Empty %c{} in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) You used something like \f(CW\*(C`\eb{}\*(C'\fR, \f(CW\*(C`\eB{}\*(C'\fR, \f(CW\*(C`\eo{}\*(C'\fR, \f(CW\*(C`\ep\*(C'\fR, \f(CW\*(C`\eP\*(C'\fR, or
+\&\f(CW\*(C`\ex\*(C'\fR without specifying anything for it to operate on.
+.Sp
+Unfortunately, for backwards compatibility reasons, an empty \f(CW\*(C`\ex\*(C'\fR is
+legal outside \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR and expands to a NUL character.
+.IP "Empty (?) without any modifiers in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Empty (?) without any modifiers in regex; marked by <-- HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR)
+\&\f(CW\*(C`(?)\*(C'\fR does nothing, so perhaps this is a typo.
+.IP "${^ENCODING} is no longer supported" 4
+.IX Item "${^ENCODING} is no longer supported"
+(F) The special variable \f(CW\*(C`${^ENCODING}\*(C'\fR, formerly used to implement
+the \f(CW\*(C`encoding\*(C'\fR pragma, is no longer supported as of Perl 5.26.0.
+.Sp
+Setting it to anything other than \f(CW\*(C`undef\*(C'\fR is a fatal error as of Perl
+5.28.
+.IP "${^HOOK}{%s} may only be a CODE reference or undef" 4
+.IX Item "${^HOOK}{%s} may only be a CODE reference or undef"
+(F) You attempted to assign something other than undef or a CODE ref to
+\&\f(CW\*(C`%{^HOOK}\*(C'\fR. Hooks may only be CODE refs. See "%{^HOOK}" in perlvar for
+details.
+.IP "Attempt to set unknown hook '%s' in %{^HOOK}" 4
+.IX Item "Attempt to set unknown hook '%s' in %{^HOOK}"
+(F) You attempted to assign something other than undef or a CODE ref to
+\&\f(CW\*(C`%{^HOOK}\*(C'\fR. Hooks may only be CODE refs. See "%{^HOOK}" in perlvar for
+details.
+.ie n .IP "entering effective %s failed" 4
+.el .IP "entering effective \f(CW%s\fR failed" 4
+.IX Item "entering effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.ie n .IP "%ENV is aliased to %s" 4
+.el .IP "\f(CW%ENV\fR is aliased to \f(CW%s\fR" 4
+.IX Item "%ENV is aliased to %s"
+(F) You're running under taint mode, and the \f(CW%ENV\fR variable has been
+aliased to another hash, so it doesn't reflect anymore the state of the
+program's environment.  This is potentially insecure.
+.ie n .IP "Error converting file specification %s" 4
+.el .IP "Error converting file specification \f(CW%s\fR" 4
+.IX Item "Error converting file specification %s"
+(F) An error peculiar to VMS.  Because Perl may have to deal with file
+specifications in either VMS or Unix syntax, it converts them to a
+single form when it must operate on them directly.  Either you've passed
+an invalid file specification to Perl, or you've found a case the
+conversion routines don't handle.  Drat.
+.ie n .IP "Error %s in expansion of %s" 4
+.el .IP "Error \f(CW%s\fR in expansion of \f(CW%s\fR" 4
+.IX Item "Error %s in expansion of %s"
+(F) An error was encountered in handling a user-defined property
+("User-Defined Character Properties" in perlunicode).  These are
+programmer written subroutines, hence subject to errors that may
+prevent them from compiling or running.  The calls to these subs are
+\&\f(CW\*(C`eval\*(C'\fR'd, and if there is a failure, this message is raised, using the
+contents of \f(CW$@\fR from the failed \f(CW\*(C`eval\*(C'\fR.
+.Sp
+Another possibility is that tainted data was encountered somewhere in
+the chain of expanding the property.  If so, the message wording will
+indicate that this is the problem.  See "Insecure user-defined
+property \f(CW%s\fR".
+.IP "Eval-group in insecure regular expression" 4
+.IX Item "Eval-group in insecure regular expression"
+(F) Perl detected tainted data when trying to compile a regular
+expression that contains the \f(CW\*(C`(?{ ... })\*(C'\fR zero-width assertion, which
+is unsafe.  See "(?{ code })" in perlre, and perlsec.
+.IP "Eval-group not allowed at runtime, use re 'eval' in regex m/%s/" 4
+.IX Item "Eval-group not allowed at runtime, use re 'eval' in regex m/%s/"
+(F) Perl tried to compile a regular expression containing the
+\&\f(CW\*(C`(?{ ... })\*(C'\fR zero-width assertion at run time, as it would when the
+pattern contains interpolated values.  Since that is a security risk,
+it is not allowed.  If you insist, you may still do this by using the
+\&\f(CW\*(C`re \*(Aqeval\*(Aq\*(C'\fR pragma or by explicitly building the pattern from an
+interpolated string at run time and using that in an \fBeval()\fR.  See
+"(?{ code })" in perlre.
+.IP "Eval-group not allowed, use re 'eval' in regex m/%s/" 4
+.IX Item "Eval-group not allowed, use re 'eval' in regex m/%s/"
+(F) A regular expression contained the \f(CW\*(C`(?{ ... })\*(C'\fR zero-width
+assertion, but that construct is only allowed when the \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR
+pragma is in effect.  See "(?{ code })" in perlre.
+.IP "EVAL without pos change exceeded limit in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "EVAL without pos change exceeded limit in regex; marked by <--\ HERE in m/%s/"
+(F) You used a pattern that nested too many EVAL calls without consuming
+any text.  Restructure the pattern so that text is consumed.
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Excessively long <> operator" 4
+.IX Item "Excessively long <> operator"
+(F) The contents of a <> operator may not exceed the maximum size of a
+Perl identifier.  If you're just trying to glob a long list of
+filenames, try using the \fBglob()\fR operator, or put the filenames into a
+variable and glob that.
+.IP "exec? I'm not *that* kind of operating system" 4
+.IX Item "exec? I'm not *that* kind of operating system"
+(F) The \f(CW\*(C`exec\*(C'\fR function is not implemented on some systems, e.g.
+Catamount. See perlport.
+.ie n .IP "%sExecution of %s aborted due to compilation errors." 4
+.el .IP "\f(CW%sExecution\fR of \f(CW%s\fR aborted due to compilation errors." 4
+.IX Item "%sExecution of %s aborted due to compilation errors."
+(F) The final summary message when a Perl compilation fails.
+.ie n .IP "Execution of %s aborted due to compilation errors." 4
+.el .IP "Execution of \f(CW%s\fR aborted due to compilation errors." 4
+.IX Item "Execution of %s aborted due to compilation errors."
+(F) The final summary message when a Perl compilation fails.
+.IP "exists argument is not a HASH or ARRAY element or a subroutine" 4
+.IX Item "exists argument is not a HASH or ARRAY element or a subroutine"
+(F) The argument to \f(CW\*(C`exists\*(C'\fR must be a hash or array element or a
+subroutine with an ampersand, such as:
+.Sp
+.Vb 3
+\&    $foo{$bar}
+\&    $ref\->{"susie"}[12]
+\&    &do_something
+.Ve
+.IP "exists argument is not a subroutine name" 4
+.IX Item "exists argument is not a subroutine name"
+(F) The argument to \f(CW\*(C`exists\*(C'\fR for \f(CW\*(C`exists &sub\*(C'\fR must be a subroutine name,
+and not a subroutine call.  \f(CW\*(C`exists &sub()\*(C'\fR will generate this error.
+.ie n .IP "Exiting eval via %s" 4
+.el .IP "Exiting eval via \f(CW%s\fR" 4
+.IX Item "Exiting eval via %s"
+(W exiting) You are exiting an eval by unconventional means, such as a
+goto, or a loop control statement.
+.ie n .IP "Exiting format via %s" 4
+.el .IP "Exiting format via \f(CW%s\fR" 4
+.IX Item "Exiting format via %s"
+(W exiting) You are exiting a format by unconventional means, such as a
+goto, or a loop control statement.
+.ie n .IP "Exiting pseudo-block via %s" 4
+.el .IP "Exiting pseudo-block via \f(CW%s\fR" 4
+.IX Item "Exiting pseudo-block via %s"
+(W exiting) You are exiting a rather special block construct (like a
+sort block or subroutine) by unconventional means, such as a goto, or a
+loop control statement.  See "sort" in perlfunc.
+.ie n .IP "Exiting subroutine via %s" 4
+.el .IP "Exiting subroutine via \f(CW%s\fR" 4
+.IX Item "Exiting subroutine via %s"
+(W exiting) You are exiting a subroutine by unconventional means, such
+as a goto, or a loop control statement.
+.ie n .IP "Exiting substitution via %s" 4
+.el .IP "Exiting substitution via \f(CW%s\fR" 4
+.IX Item "Exiting substitution via %s"
+(W exiting) You are exiting a substitution by unconventional means, such
+as a return, a goto, or a loop control statement.
+.ie n .IP "Expected %s reference in export_lexically" 4
+.el .IP "Expected \f(CW%s\fR reference in export_lexically" 4
+.IX Item "Expected %s reference in export_lexically"
+(F) The type of a reference given to "export_lexically" in builtin did not
+match the sigil of the preceding name, or the value was not a reference at
+all.
+.IP "Expecting close bracket in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Expecting close bracket in regex; marked by <--\ HERE in m/%s/"
+(F) You wrote something like
+.Sp
+.Vb 1
+\& (?13
+.Ve
+.Sp
+to denote a capturing group of the form
+\&\f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR,
+but omitted the \f(CW")"\fR.
+.IP "Expecting interpolated extended charclass in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Expecting interpolated extended charclass in regex; marked by <-- HERE in m/%s/"
+(F) It looked like you were attempting to interpolate an
+already-compiled extended character class, like so:
+.Sp
+.Vb 3
+\& my $thai_or_lao = qr/(?[ \ep{Thai} + \ep{Lao} ])/;
+\& ...
+\& qr/(?[ \ep{Digit} & $thai_or_lao ])/;
+.Ve
+.Sp
+But the marked code isn't syntactically correct to be such an
+interpolated class.
+.IP "Experimental aliasing via reference not enabled" 4
+.IX Item "Experimental aliasing via reference not enabled"
+(F) To do aliasing via references, you must first enable the feature:
+.Sp
+.Vb 3
+\&    no warnings "experimental::refaliasing";
+\&    use feature "refaliasing";
+\&    \e$x = \e$y;
+.Ve
+.ie n .IP "Experimental %s on scalar is now forbidden" 4
+.el .IP "Experimental \f(CW%s\fR on scalar is now forbidden" 4
+.IX Item "Experimental %s on scalar is now forbidden"
+(F) An experimental feature added in Perl 5.14 allowed \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR,
+\&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`splice\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR, and \f(CW\*(C`values\*(C'\fR to be called with a
+scalar argument.  This experiment is considered unsuccessful, and
+has been removed.  The \f(CW\*(C`postderef\*(C'\fR feature may meet your needs better.
+.IP "Experimental subroutine signatures not enabled" 4
+.IX Item "Experimental subroutine signatures not enabled"
+(F) To use subroutine signatures, you must first enable them:
+.Sp
+.Vb 2
+\&    use feature "signatures";
+\&    sub foo ($left, $right) { ... }
+.Ve
+.IP "Explicit blessing to '' (assuming package main)" 4
+.IX Item "Explicit blessing to '' (assuming package main)"
+(W misc) You are blessing a reference to a zero length string.  This has
+the effect of blessing the reference into the package main.  This is
+usually not what you want.  Consider providing a default target package,
+e.g. bless($ref, \f(CW$p\fR || 'MyPackage');
+.IP "export_lexically can only be called at compile time" 4
+.IX Item "export_lexically can only be called at compile time"
+(F) "export_lexically" in builtin was called at runtime.  Because it creates
+new names in the lexical scope currently being compiled, it can only be
+called from code inside \f(CW\*(C`BEGIN\*(C'\fR block in that scope.
+.ie n .IP "%s: Expression syntax" 4
+.el .IP "\f(CW%s:\fR Expression syntax" 4
+.IX Item "%s: Expression syntax"
+(A) You've accidentally run your script through \fBcsh\fR instead of Perl.
+Check the #! line, or manually feed your script into Perl yourself.
+.ie n .IP "%s failed\-\-call queue aborted" 4
+.el .IP "\f(CW%s\fR failed\-\-call queue aborted" 4
+.IX Item "%s failed--call queue aborted"
+(F) An untrapped exception was raised while executing a UNITCHECK,
+CHECK, INIT, or END subroutine.  Processing of the remainder of the
+queue of such routines has been prematurely ended.
+.ie n .IP "Failed to close in-place work file %s: %s" 4
+.el .IP "Failed to close in-place work file \f(CW%s:\fR \f(CW%s\fR" 4
+.IX Item "Failed to close in-place work file %s: %s"
+(F) Closing an output file from in-place editing, as with the \f(CW\*(C`\-i\*(C'\fR
+command-line switch, failed.
+.IP "False [] range ""%s"" in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "False [] range ""%s"" in regex; marked by <--\ HERE in m/%s/"
+(W regexp)(F) A character class range must start and end at a literal
+character, not another character class like \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`[:alpha:]\*(C'\fR.  The "\-"
+in your false range is interpreted as a literal "\-".  In a \f(CW\*(C`(?[...])\*(C'\fR
+construct, this is an error, rather than a warning.  Consider quoting
+the "\-", "\e\-".  The <\-\-\ HERE shows whereabouts in the regular expression
+the problem was discovered.  See perlre.
+.ie n .IP "Fatal VMS error (status=%d) at %s, line %d" 4
+.el .IP "Fatal VMS error (status=%d) at \f(CW%s\fR, line \f(CW%d\fR" 4
+.IX Item "Fatal VMS error (status=%d) at %s, line %d"
+(P) An error peculiar to VMS.  Something untoward happened in a VMS
+system service or RTL routine; Perl's exit status should provide more
+details.  The filename in "at \f(CW%s\fR" and the line number in "line \f(CW%d\fR" tell
+you which section of the Perl source code is distressed.
+.IP "fcntl is not implemented" 4
+.IX Item "fcntl is not implemented"
+(F) Your machine apparently doesn't implement \fBfcntl()\fR.  What is this, a
+PDP\-11 or something?
+.IP "FETCHSIZE returned a negative value" 4
+.IX Item "FETCHSIZE returned a negative value"
+(F) A tied array claimed to have a negative number of elements, which
+is not possible.
+.IP "Field already has a parameter name, cannot add another" 4
+.IX Item "Field already has a parameter name, cannot add another"
+(F) A field may have at most one application of the \f(CW\*(C`:param\*(C'\fR attribute to
+assign a parameter name to it; once applied a second one is not allowed.
+.ie n .IP "Field attribute %s requires a value" 4
+.el .IP "Field attribute \f(CW%s\fR requires a value" 4
+.IX Item "Field attribute %s requires a value"
+(F) You specified an attribute for a field that would require a value to
+be passed in parentheses, but did not provide one.  Remember that
+whitespace is \fBnot\fR permitted between the attribute name and its value;
+you must write this as
+.Sp
+.Vb 1
+\&    field $var :attr(VALUE) ...
+.Ve
+.IP "field is experimental" 4
+.IX Item "field is experimental"
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`field\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.ie n .IP "Field %s is not accessible outside a method" 4
+.el .IP "Field \f(CW%s\fR is not accessible outside a method" 4
+.IX Item "Field %s is not accessible outside a method"
+(F) An attempt was made to access a field variable of a class from code
+that does not appear inside the body of a \f(CW\*(C`method\*(C'\fR subroutine.  This is not
+permitted, as only methods will have access to the fields of an instance.
+.ie n .IP "Field %s of ""%s"" is not accessible in a method of ""%s""" 4
+.el .IP "Field \f(CW%s\fR of ""%s"" is not accessible in a method of ""%s""" 4
+.IX Item "Field %s of ""%s"" is not accessible in a method of ""%s"""
+(F) An attempt was made to access a field variable of a class, from a
+method of another class nested inside the one that actually defined it.
+This is not permitted, as only methods defined by a given class are
+permitted to access fields of that class.
+.IP "Field too wide in 'u' format in pack" 4
+.IX Item "Field too wide in 'u' format in pack"
+(W pack) Each line in an uuencoded string starts with a length indicator
+which can't encode values above 63.  So there is no point in asking for
+a line length bigger than that.  Perl will behave as if you specified
+\&\f(CW\*(C`u63\*(C'\fR as the format.
+.ie n .IP "Filehandle %s opened only for input" 4
+.el .IP "Filehandle \f(CW%s\fR opened only for input" 4
+.IX Item "Filehandle %s opened only for input"
+(W io) You tried to write on a read-only filehandle.  If you intended
+it to be a read-write filehandle, you needed to open it with "+<" or
+"+>" or "+>>" instead of with "<" or nothing.  If you intended only to
+write the file, use ">" or ">>".  See "open" in perlfunc.
+.ie n .IP "Filehandle %s opened only for output" 4
+.el .IP "Filehandle \f(CW%s\fR opened only for output" 4
+.IX Item "Filehandle %s opened only for output"
+(W io) You tried to read from a filehandle opened only for writing, If
+you intended it to be a read/write filehandle, you needed to open it
+with "+<" or "+>" or "+>>" instead of with ">".  If you intended only to
+read from the file, use "<".  See "open" in perlfunc.  Another possibility
+is that you attempted to open filedescriptor 0 (also known as STDIN) for
+output (maybe you closed STDIN earlier?).
+.ie n .IP "Filehandle %s reopened as %s only for input" 4
+.el .IP "Filehandle \f(CW%s\fR reopened as \f(CW%s\fR only for input" 4
+.IX Item "Filehandle %s reopened as %s only for input"
+(W io) You opened for reading a filehandle that got the same filehandle id
+as STDOUT or STDERR.  This occurred because you closed STDOUT or STDERR
+previously.
+.ie n .IP "Filehandle STDIN reopened as %s only for output" 4
+.el .IP "Filehandle STDIN reopened as \f(CW%s\fR only for output" 4
+.IX Item "Filehandle STDIN reopened as %s only for output"
+(W io) You opened for writing a filehandle that got the same filehandle id
+as STDIN.  This occurred because you closed STDIN previously.
+.ie n .IP "Filehandle STD%s reopened as %s only for input" 4
+.el .IP "Filehandle STD%s reopened as \f(CW%s\fR only for input" 4
+.IX Item "Filehandle STD%s reopened as %s only for input"
+(W io) You opened for reading a filehandle that got the same filehandle id
+as STDOUT or STDERR.  This occurred because you closed the handle previously.
+.ie n .IP "Final $ should be \e$ or $name" 4
+.el .IP "Final $ should be \e$ or \f(CW$name\fR" 4
+.IX Item "Final $ should be $ or $name"
+(F) You must now decide whether the final $ in a string was meant to be
+a literal dollar sign, or was meant to introduce a variable name that
+happens to be missing.  So you have to put either the backslash or the
+name.
+.IP "defer is experimental" 4
+.IX Item "defer is experimental"
+(S experimental::defer) The \f(CW\*(C`defer\*(C'\fR block modifier is experimental. If you
+want to use the feature, disable the warning with
+\&\f(CW\*(C`no warnings \*(Aqexperimental::defer\*(Aq\*(C'\fR, but know that in doing so you are taking
+the risk that your code may break in a future Perl version.
+.ie n .IP "\fBflock()\fR on closed filehandle %s" 4
+.el .IP "\fBflock()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "flock() on closed filehandle %s"
+(W closed) The filehandle you're attempting to \fBflock()\fR got itself closed
+some time before now.  Check your control flow.  \fBflock()\fR operates on
+filehandles.  Are you attempting to call \fBflock()\fR on a dirhandle by the
+same name?
+.IP "for my (...) is experimental" 4
+.IX Item "for my (...) is experimental"
+(S experimental::for_list) This warning is emitted if you use \f(CW\*(C`for\*(C'\fR to
+iterate multiple values at a time. This syntax is currently experimental
+and its behaviour may change in future releases of Perl.
+.IP "Format not terminated" 4
+.IX Item "Format not terminated"
+(F) A format must be terminated by a line with a solitary dot.  Perl got
+to the end of your file without finding such a line.
+.ie n .IP "Format %s redefined" 4
+.el .IP "Format \f(CW%s\fR redefined" 4
+.IX Item "Format %s redefined"
+(W redefine) You redefined a format.  To suppress this warning, say
+.Sp
+.Vb 4
+\&    {
+\&        no warnings \*(Aqredefine\*(Aq;
+\&        eval "format NAME =...";
+\&    }
+.Ve
+.IP "Found = in conditional, should be ==" 4
+.IX Item "Found = in conditional, should be =="
+(W syntax) You said
+.Sp
+.Vb 1
+\&    if ($foo = 123)
+.Ve
+.Sp
+when you meant
+.Sp
+.Vb 1
+\&    if ($foo == 123)
+.Ve
+.Sp
+(or something like that).
+.ie n .IP "%s found where operator expected" 4
+.el .IP "\f(CW%s\fR found where operator expected" 4
+.IX Item "%s found where operator expected"
+(S syntax) The Perl lexer knows whether to expect a term or an operator.
+If it sees what it knows to be a term when it was expecting to see an
+operator, it gives you this warning.  Usually it indicates that an
+operator or delimiter was omitted, such as a semicolon.
+.ie n .IP "gdbm store returned %d, errno %d, key ""%s""" 4
+.el .IP "gdbm store returned \f(CW%d\fR, errno \f(CW%d\fR, key ""%s""" 4
+.IX Item "gdbm store returned %d, errno %d, key ""%s"""
+(S) A warning from the GDBM_File extension that a store failed.
+.IP "gethostent not implemented" 4
+.IX Item "gethostent not implemented"
+(F) Your C library apparently doesn't implement \fBgethostent()\fR, probably
+because if it did, it'd feel morally obligated to return every hostname
+on the Internet.
+.ie n .IP "get%\fBsname()\fR on closed socket %s" 4
+.el .IP "get%\fBsname()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "get%sname() on closed socket %s"
+(W closed) You tried to get a socket or peer socket name on a closed
+socket.  Did you forget to check the return value of your \fBsocket()\fR call?
+.IP "getpwnam returned invalid UIC %#o for user ""%s""" 4
+.IX Item "getpwnam returned invalid UIC %#o for user ""%s"""
+(S) A warning peculiar to VMS.  The call to \f(CW\*(C`sys$getuai\*(C'\fR underlying the
+\&\f(CW\*(C`getpwnam\*(C'\fR operator returned an invalid UIC.
+.ie n .IP "\fBgetsockopt()\fR on closed socket %s" 4
+.el .IP "\fBgetsockopt()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "getsockopt() on closed socket %s"
+(W closed) You tried to get a socket option on a closed socket.  Did you
+forget to check the return value of your \fBsocket()\fR call?  See
+"getsockopt" in perlfunc.
+.IP "given is deprecated" 4
+.IX Item "given is deprecated"
+(D deprecated::smartmatch) \f(CW\*(C`given\*(C'\fR depends on smartmatch, which is
+deprecated. It will be removed in Perl 5.42. See the explanation under
+"Experimental Details on given and when" in perlsyn.
+.ie n .IP "Global symbol ""%s"" requires explicit package name (did you forget to declare ""my %s""?)" 4
+.el .IP "Global symbol ""%s"" requires explicit package name (did you forget to declare ""my \f(CW%s\fR""?)" 4
+.IX Item "Global symbol ""%s"" requires explicit package name (did you forget to declare ""my %s""?)"
+(F) You've said "use strict" or "use strict vars", which indicates 
+that all variables must either be lexically scoped (using "my" or "state"), 
+declared beforehand using "our", or explicitly qualified to say 
+which package the global variable is in (using "::").
+.IP "glob failed (%s)" 4
+.IX Item "glob failed (%s)"
+(S glob) Something went wrong with the external program(s) used
+for \f(CW\*(C`glob\*(C'\fR and \f(CW\*(C`<*.c>\*(C'\fR.  Usually, this means that you supplied a \f(CW\*(C`glob\*(C'\fR
+pattern that caused the external program to fail and exit with a
+nonzero status.  If the message indicates that the abnormal exit
+resulted in a coredump, this may also mean that your csh (C shell)
+is broken.  If so, you should change all of the csh-related variables
+in config.sh:  If you have tcsh, make the variables refer to it as
+if it were csh (e.g. \f(CW\*(C`full_csh=\*(Aq/usr/bin/tcsh\*(Aq\*(C'\fR); otherwise, make them
+all empty (except that \f(CW\*(C`d_csh\*(C'\fR should be \f(CW\*(Aqundef\*(Aq\fR) so that Perl will
+think csh is missing.  In either case, after editing config.sh, run
+\&\f(CW\*(C`./Configure \-S\*(C'\fR and rebuild Perl.
+.IP "Glob not terminated" 4
+.IX Item "Glob not terminated"
+(F) The lexer saw a left angle bracket in a place where it was expecting
+a term, so it's looking for the corresponding right angle bracket, and
+not finding it.  Chances are you left some needed parentheses out
+earlier in the line, and you really meant a "less than".
+.IP "gmtime(%f) failed" 4
+.IX Item "gmtime(%f) failed"
+(W overflow) You called \f(CW\*(C`gmtime\*(C'\fR with a number that it could not handle:
+too large, too small, or NaN.  The returned value is \f(CW\*(C`undef\*(C'\fR.
+.IP "gmtime(%f) too large" 4
+.IX Item "gmtime(%f) too large"
+(W overflow) You called \f(CW\*(C`gmtime\*(C'\fR with a number that was larger than
+it can reliably handle and \f(CW\*(C`gmtime\*(C'\fR probably returned the wrong
+date.  This warning is also triggered with NaN (the special
+not-a-number value).
+.IP "gmtime(%f) too small" 4
+.IX Item "gmtime(%f) too small"
+(W overflow) You called \f(CW\*(C`gmtime\*(C'\fR with a number that was smaller than
+it can reliably handle and \f(CW\*(C`gmtime\*(C'\fR probably returned the wrong date.
+.IP "Got an error from DosAllocMem" 4
+.IX Item "Got an error from DosAllocMem"
+(P) An error peculiar to OS/2.  Most probably you're using an obsolete
+version of Perl, and this should not happen anyway.
+.IP "goto must have label" 4
+.IX Item "goto must have label"
+(F) Unlike with "next" or "last", you're not allowed to goto an
+unspecified destination.  See "goto" in perlfunc.
+.IP "Goto undefined subroutine%s" 4
+.IX Item "Goto undefined subroutine%s"
+(F) You tried to call a subroutine with \f(CW\*(C`goto &sub\*(C'\fR syntax, but
+the indicated subroutine hasn't been defined, or if it was, it
+has since been undefined.
+.IP "Group name must start with a non-digit word character in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Group name must start with a non-digit word character in regex; marked by <--\ HERE in m/%s/"
+(F) Group names must follow the rules for perl identifiers, meaning
+they must start with a non-digit word character.  A common cause of
+this error is using (?&0) instead of (?0).  See perlre.
+.IP "()\-group starts with a count" 4
+.IX Item "()-group starts with a count"
+(F) A ()\-group started with a count.  A count is supposed to follow
+something: a template character or a ()\-group.  See "pack" in perlfunc.
+.ie n .IP "%s had compilation errors." 4
+.el .IP "\f(CW%s\fR had compilation errors." 4
+.IX Item "%s had compilation errors."
+(F) The final summary message when a \f(CW\*(C`perl \-c\*(C'\fR fails.
+.ie n .IP "Had to create %s unexpectedly" 4
+.el .IP "Had to create \f(CW%s\fR unexpectedly" 4
+.IX Item "Had to create %s unexpectedly"
+(S internal) A routine asked for a symbol from a symbol table that ought
+to have existed already, but for some reason it didn't, and had to be
+created on an emergency basis to prevent a core dump.
+.ie n .IP "%s has too many errors" 4
+.el .IP "\f(CW%s\fR has too many errors" 4
+.IX Item "%s has too many errors"
+(F) The parser has given up trying to parse the program after 10 errors.
+Further error messages would likely be uninformative.
+.IP "Hexadecimal float: exponent overflow" 4
+.IX Item "Hexadecimal float: exponent overflow"
+(W overflow) The hexadecimal floating point has a larger exponent
+than the floating point supports.
+.IP "Hexadecimal float: exponent underflow" 4
+.IX Item "Hexadecimal float: exponent underflow"
+(W overflow) The hexadecimal floating point has a smaller exponent
+than the floating point supports.  With the IEEE 754 floating point,
+this may also mean that the subnormals (formerly known as denormals)
+are being used, which may or may not be an error.
+.IP "Hexadecimal float: internal error (%s)" 4
+.IX Item "Hexadecimal float: internal error (%s)"
+(F) Something went horribly bad in hexadecimal float handling.
+.IP "Hexadecimal float: mantissa overflow" 4
+.IX Item "Hexadecimal float: mantissa overflow"
+(W overflow) The hexadecimal floating point literal had more bits in
+the mantissa (the part between the 0x and the exponent, also known as
+the fraction or the significand) than the floating point supports.
+.IP "Hexadecimal float: precision loss" 4
+.IX Item "Hexadecimal float: precision loss"
+(W overflow) The hexadecimal floating point had internally more
+digits than could be output.  This can be caused by unsupported
+long double formats, or by 64\-bit integers not being available
+(needed to retrieve the digits under some configurations).
+.IP "Hexadecimal float: unsupported long double format" 4
+.IX Item "Hexadecimal float: unsupported long double format"
+(F) You have configured Perl to use long doubles but
+the internals of the long double format are unknown;
+therefore the hexadecimal float output is impossible.
+.IP "Hexadecimal number > 0xffffffff non-portable" 4
+.IX Item "Hexadecimal number > 0xffffffff non-portable"
+(W portable) The hexadecimal number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Identifier too long" 4
+.IX Item "Identifier too long"
+(F) Perl limits identifiers (names for variables, functions, etc.) to
+about 250 characters for simple names, and somewhat more for compound
+names (like \f(CW$A::B\fR).  You've exceeded Perl's limits.  Future versions
+of Perl are likely to eliminate these arbitrary limitations.
+.IP "Ignoring zero length \eN{} in character class in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Ignoring zero length N{} in character class in regex; marked by <--\ HERE in m/%s/"
+(W regexp) Named Unicode character escapes (\f(CW\*(C`\eN{...}\*(C'\fR) may return a
+zero-length sequence.  When such an escape is used in a character
+class its behavior is not well defined.  Check that the correct
+escape has been used, and the correct charname handler is in scope.
+.ie n .IP "Illegal %s digit '%c' ignored" 4
+.el .IP "Illegal \f(CW%s\fR digit '%c' ignored" 4
+.IX Item "Illegal %s digit '%c' ignored"
+(W digit) Here \f(CW%s\fR is one of "binary", "octal", or "hex".
+You may have tried to use a digit other than one that is legal for the
+given type, such as only 0 and 1 for binary.  For octals, this is raised
+only if the illegal character is an '8' or '9'.  For hex, 'A' \- 'F' and
+\&'a' \- 'f' are legal.
+Interpretation of the number stopped just before the offending digit or
+character.
+.IP "Illegal binary digit '%c'" 4
+.IX Item "Illegal binary digit '%c'"
+(F) You used a digit other than 0 or 1 in a binary number.
+.ie n .IP "Illegal character after '_' in prototype for %s : %s" 4
+.el .IP "Illegal character after '_' in prototype for \f(CW%s\fR : \f(CW%s\fR" 4
+.IX Item "Illegal character after '_' in prototype for %s : %s"
+(W illegalproto) An illegal character was found in a prototype
+declaration.  The '_' in a prototype must be followed by a ';',
+indicating the rest of the parameters are optional, or one of '@'
+or '%', since those two will accept 0 or more final parameters.
+.IP "Illegal character \e%o (carriage return)" 4
+.IX Item "Illegal character %o (carriage return)"
+(F) Perl normally treats carriage returns in the program text as
+it would any other whitespace, which means you should never see
+this error when Perl was built using standard options.  For some
+reason, your version of Perl appears to have been built without
+this support.  Talk to your Perl administrator.
+.IP "Illegal character following sigil in a subroutine signature" 4
+.IX Item "Illegal character following sigil in a subroutine signature"
+(F) A parameter in a subroutine signature contained an unexpected character
+following the \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR sigil character.  Normally the sigil
+should be followed by the variable name or \f(CW\*(C`=\*(C'\fR etc.  Perhaps you are
+trying use a prototype while in the scope of \f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR?
+For example:
+.Sp
+.Vb 1
+\&    sub foo ($$) {}            # legal \- a prototype
+\&
+\&    use feature \*(Aqsignatures;
+\&    sub foo ($$) {}            # illegal \- was expecting a signature
+\&    sub foo ($a, $b)
+\&            :prototype($$) {}  # legal
+.Ve
+.ie n .IP "Illegal character in prototype for %s : %s" 4
+.el .IP "Illegal character in prototype for \f(CW%s\fR : \f(CW%s\fR" 4
+.IX Item "Illegal character in prototype for %s : %s"
+(W illegalproto) An illegal character was found in a prototype declaration.
+Legal characters in prototypes are $, @, %, *, ;, [, ], &, \e, and +.
+Perhaps you were trying to write a subroutine signature but didn't enable
+that feature first (\f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR), so your signature was
+instead interpreted as a bad prototype.
+.IP "Illegal declaration of anonymous subroutine" 4
+.IX Item "Illegal declaration of anonymous subroutine"
+(F) When using the \f(CW\*(C`sub\*(C'\fR keyword to construct an anonymous subroutine,
+you must always specify a block of code.  See perlsub.
+.ie n .IP "Illegal declaration of subroutine %s" 4
+.el .IP "Illegal declaration of subroutine \f(CW%s\fR" 4
+.IX Item "Illegal declaration of subroutine %s"
+(F) A subroutine was not declared correctly.  See perlsub.
+.IP "Illegal division by zero" 4
+.IX Item "Illegal division by zero"
+(F) You tried to divide a number by 0.  Either something was wrong in
+your logic, or you need to put a conditional in to guard against
+meaningless input.
+.IP "Illegal modulus zero" 4
+.IX Item "Illegal modulus zero"
+(F) You tried to divide a number by 0 to get the remainder.  Most
+numbers don't take to this kindly.
+.IP "Illegal number of bits in vec" 4
+.IX Item "Illegal number of bits in vec"
+(F) The number of bits in \fBvec()\fR (the third argument) must be a power of
+two from 1 to 32 (or 64, if your platform supports that).
+.IP "Illegal octal digit '%c'" 4
+.IX Item "Illegal octal digit '%c'"
+(F) You used an 8 or 9 in an octal number.
+.IP "Illegal operator following parameter in a subroutine signature" 4
+.IX Item "Illegal operator following parameter in a subroutine signature"
+(F) A parameter in a subroutine signature, was followed by something
+other than \f(CW\*(C`=\*(C'\fR introducing a default, \f(CW\*(C`,\*(C'\fR or \f(CW\*(C`)\*(C'\fR.
+.Sp
+.Vb 5
+\&    use feature \*(Aqsignatures\*(Aq;
+\&    sub foo ($=1) {}           # legal
+\&    sub foo ($a = 1) {}        # legal
+\&    sub foo ($a += 1) {}       # illegal
+\&    sub foo ($a == 1) {}       # illegal
+.Ve
+.IP "Illegal pattern in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Illegal pattern in regex; marked by <--\ HERE in m/%s/"
+(F) You wrote something like
+.Sp
+.Vb 1
+\& (?+foo)
+.Ve
+.Sp
+The \f(CW"+"\fR is valid only when followed by digits, indicating a
+capturing group.  See
+\&\f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR.
+.IP "Illegal suidscript" 4
+.IX Item "Illegal suidscript"
+(F) The script run under suidperl was somehow illegal.
+.IP "Illegal switch in PERL5OPT: \-%c" 4
+.IX Item "Illegal switch in PERL5OPT: -%c"
+(X) The PERL5OPT environment variable may only be used to set the
+following switches: \fB\-[CDIMUdmtw]\fR.
+.IP "Illegal user-defined property name" 4
+.IX Item "Illegal user-defined property name"
+(F) You specified a Unicode-like property name in a regular expression
+pattern (using \f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR) that Perl knows isn't an official
+Unicode property, and was likely meant to be a user-defined property
+name, but it can't be one of those, as they must begin with either \f(CW\*(C`In\*(C'\fR
+or \f(CW\*(C`Is\*(C'\fR.  Check the spelling.  See also
+"Can't find Unicode property definition "%s"".
+.IP "Ill-formed CRTL environ value ""%s""" 4
+.IX Item "Ill-formed CRTL environ value ""%s"""
+(W internal) A warning peculiar to VMS.  Perl tried to read the CRTL's
+internal environ array, and encountered an element without the \f(CW\*(C`=\*(C'\fR
+delimiter used to separate keys from values.  The element is ignored.
+.IP "Ill-formed message in prime_env_iter: |%s|" 4
+.IX Item "Ill-formed message in prime_env_iter: |%s|"
+(W internal) A warning peculiar to VMS.  Perl tried to read a logical
+name or CLI symbol definition when preparing to iterate over \f(CW%ENV\fR, and
+didn't see the expected delimiter between key and value, so the line was
+ignored.
+.ie n .IP "(in cleanup) %s" 4
+.el .IP "(in cleanup) \f(CW%s\fR" 4
+.IX Item "(in cleanup) %s"
+(W misc) This prefix usually indicates that a \fBDESTROY()\fR method raised
+the indicated exception.  Since destructors are usually called by the
+system at arbitrary points during execution, and often a vast number of
+times, the warning is issued only once for any number of failures that
+would otherwise result in the same message being repeated.
+.Sp
+Failure of user callbacks dispatched using the \f(CW\*(C`G_KEEPERR\*(C'\fR flag could
+also result in this warning.  See "G_KEEPERR" in perlcall.
+.ie n .IP "Implicit use of @_ in %s with signatured subroutine is experimental" 4
+.el .IP "Implicit use of \f(CW@_\fR in \f(CW%s\fR with signatured subroutine is experimental" 4
+.IX Item "Implicit use of @_ in %s with signatured subroutine is experimental"
+(S experimental::args_array_with_signatures) An expression that implicitly
+involves the \f(CW@_\fR arguments array was found in a subroutine that uses a
+signature.  This is experimental because the interaction between the
+arguments array and parameter handling via signatures is not guaranteed
+to remain stable in any future version of Perl, and such code should be
+avoided.
+.IP "Incomplete expression within '(?[ ])' in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Incomplete expression within '(?[ ])' in regex; marked by <--\ HERE in m/%s/"
+(F) There was a syntax error within the \f(CW\*(C`(?[ ])\*(C'\fR.  This can happen if the
+expression inside the construct was completely empty, or if there are
+too many or few operands for the number of operators.  Perl is not smart
+enough to give you a more precise indication as to what is wrong.
+.IP "Inconsistent hierarchy during C3 merge of class '%s': merging failed on parent '%s'" 4
+.IX Item "Inconsistent hierarchy during C3 merge of class '%s': merging failed on parent '%s'"
+(F) The method resolution order (MRO) of the given class is not
+C3\-consistent, and you have enabled the C3 MRO for this class.  See the C3
+documentation in mro for more information.
+.ie n .IP "Indentation on line %d of here-doc doesn't match delimiter" 4
+.el .IP "Indentation on line \f(CW%d\fR of here-doc doesn't match delimiter" 4
+.IX Item "Indentation on line %d of here-doc doesn't match delimiter"
+(F) You have an indented here-document where one or more of its lines
+have whitespace at the beginning that does not match the closing
+delimiter.
+.Sp
+For example, line 2 below is wrong because it does not have at least
+2 spaces, but lines 1 and 3 are fine because they have at least 2:
+.Sp
+.Vb 7
+\&    if ($something) {
+\&      print <<~EOF;
+\&        Line 1
+\&       Line 2 not
+\&          Line 3
+\&        EOF
+\&    }
+.Ve
+.Sp
+Note that tabs and spaces are compared strictly, meaning 1 tab will
+not match 8 spaces.
+.IP "Infinite recursion in regex" 4
+.IX Item "Infinite recursion in regex"
+(F) You used a pattern that references itself without consuming any input
+text.  You should check the pattern to ensure that recursive patterns
+either consume text or fail.
+.IP "Infinite recursion in user-defined property" 4
+.IX Item "Infinite recursion in user-defined property"
+(F) A user-defined property ("User-Defined Character
+Properties" in perlunicode) can depend on the definitions of other user-defined
+properties.  If the chain of dependencies leads back to this property,
+infinite recursion would occur, were it not for the check that raised
+this error.
+.Sp
+Restructure your property definitions to avoid this.
+.IP "Infinite recursion via empty pattern" 4
+.IX Item "Infinite recursion via empty pattern"
+(F) You tried to use the empty pattern inside of a regex code block,
+for instance \f(CW\*(C`/(?{ s!!! })/\*(C'\fR, which resulted in re-executing
+the same pattern, which is an infinite loop which is broken by
+throwing an exception.
+.IP "Initialization of state variables in list currently forbidden" 4
+.IX Item "Initialization of state variables in list currently forbidden"
+(F) \f(CW\*(C`state\*(C'\fR only permits initializing a single variable, specified
+without parentheses.  So \f(CW\*(C`state $a = 42\*(C'\fR and \f(CW\*(C`state @a = qw(a b c)\*(C'\fR are
+allowed, but not \f(CW\*(C`state ($a) = 42\*(C'\fR or \f(CW\*(C`(state $a) = 42\*(C'\fR.  To initialize
+more than one \f(CW\*(C`state\*(C'\fR variable, initialize them one at a time.
+.IP "%%s[%s] in scalar context better written as $%s[%s]" 4
+.IX Item "%%s[%s] in scalar context better written as $%s[%s]"
+(W syntax) In scalar context, you've used an array index/value slice
+(indicated by %) to select a single element of an array.  Generally
+it's better to ask for a scalar value (indicated by $).  The difference
+is that \f(CW$foo[&bar]\fR always behaves like a scalar, both in the value it
+returns and when evaluating its argument, while \f(CW%foo[&bar]\fR provides
+a list context to its subscript, which can do weird things if you're
+expecting only one subscript.  When called in list context, it also
+returns the index (what \f(CW&bar\fR returns) in addition to the value.
+.IP "%%s{%s} in scalar context better written as $%s{%s}" 4
+.IX Item "%%s{%s} in scalar context better written as $%s{%s}"
+(W syntax) In scalar context, you've used a hash key/value slice
+(indicated by %) to select a single element of a hash.  Generally it's
+better to ask for a scalar value (indicated by $).  The difference
+is that \f(CW$foo{&bar}\fR always behaves like a scalar, both in the value
+it returns and when evaluating its argument, while \f(CW@foo{&bar}\fR and
+provides a list context to its subscript, which can do weird things
+if you're expecting only one subscript.  When called in list context,
+it also returns the key in addition to the value.
+.ie n .IP "Insecure dependency in %s" 4
+.el .IP "Insecure dependency in \f(CW%s\fR" 4
+.IX Item "Insecure dependency in %s"
+(F) You tried to do something that the tainting mechanism didn't like.
+The tainting mechanism is turned on when you're running setuid or
+setgid, or when you specify \fB\-T\fR to turn it on explicitly.  The
+tainting mechanism labels all data that's derived directly or indirectly
+from the user, who is considered to be unworthy of your trust.  If any
+such data is used in a "dangerous" operation, you get this error.  See
+perlsec for more information.
+.ie n .IP "Insecure directory in %s" 4
+.el .IP "Insecure directory in \f(CW%s\fR" 4
+.IX Item "Insecure directory in %s"
+(F) You can't use \fBsystem()\fR, \fBexec()\fR, or a piped open in a setuid or
+setgid script if \f(CW$ENV{PATH}\fR contains a directory that is writable by
+the world.  Also, the PATH must not contain any relative directory.
+See perlsec.
+.ie n .IP "Insecure $ENV{%s} while running %s" 4
+.el .IP "Insecure \f(CW$ENV\fR{%s} while running \f(CW%s\fR" 4
+.IX Item "Insecure $ENV{%s} while running %s"
+(F) You can't use \fBsystem()\fR, \fBexec()\fR, or a piped open in a setuid or
+setgid script if any of \f(CW$ENV{PATH}\fR, \f(CW$ENV{IFS}\fR, \f(CW$ENV{CDPATH}\fR,
+\&\f(CW$ENV{ENV}\fR, \f(CW$ENV{BASH_ENV}\fR or \f(CW$ENV{TERM}\fR are derived from data
+supplied (or potentially supplied) by the user.  The script must set
+the path to a known value, using trustworthy data.  See perlsec.
+.ie n .IP "Insecure user-defined property %s" 4
+.el .IP "Insecure user-defined property \f(CW%s\fR" 4
+.IX Item "Insecure user-defined property %s"
+(F) Perl detected tainted data when trying to compile a regular
+expression that contains a call to a user-defined character property
+function, i.e. \f(CW\*(C`\ep{IsFoo}\*(C'\fR or \f(CW\*(C`\ep{InFoo}\*(C'\fR.
+See "User-Defined Character Properties" in perlunicode and perlsec.
+.ie n .IP "Integer overflow in format string for %s" 4
+.el .IP "Integer overflow in format string for \f(CW%s\fR" 4
+.IX Item "Integer overflow in format string for %s"
+(F) The indexes and widths specified in the format string of \f(CWprintf()\fR
+or \f(CWsprintf()\fR are too large.  The numbers must not overflow the size of
+integers for your architecture.
+.ie n .IP "Integer overflow in %s number" 4
+.el .IP "Integer overflow in \f(CW%s\fR number" 4
+.IX Item "Integer overflow in %s number"
+(S overflow) The hexadecimal, octal or binary number you have specified
+either as a literal or as an argument to \fBhex()\fR or \fBoct()\fR is too big for
+your architecture, and has been converted to a floating point number.
+On a 32\-bit architecture the largest hexadecimal, octal or binary number
+representable without overflow is 0xFFFFFFFF, 037777777777, or
+0b11111111111111111111111111111111 respectively.  Note that Perl
+transparently promotes all numbers to a floating point representation
+internally\-\-subject to loss of precision errors in subsequent
+operations.
+.IP "Integer overflow in srand" 4
+.IX Item "Integer overflow in srand"
+(S overflow) The number you have passed to srand is too big to fit
+in your architecture's integer representation.  The number has been
+replaced with the largest integer supported (0xFFFFFFFF on 32\-bit
+architectures).  This means you may be getting less randomness than
+you expect, because different random seeds above the maximum will
+return the same sequence of random numbers.
+.IP "Integer overflow in version" 4
+.IX Item "Integer overflow in version"
+.PD 0
+.ie n .IP "Integer overflow in version %d" 4
+.el .IP "Integer overflow in version \f(CW%d\fR" 4
+.IX Item "Integer overflow in version %d"
+.PD
+(W overflow) Some portion of a version initialization is too large for
+the size of integers for your architecture.  This is not a warning
+because there is no rational reason for a version to try and use an
+element larger than typically 2**32.  This is usually caused by trying
+to use some odd mathematical operation as a version, like 100/9.
+.IP "Internal disaster in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Internal disaster in regex; marked by <--\ HERE in m/%s/"
+(P) Something went badly wrong in the regular expression parser.
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Internal inconsistency in tracking vforks" 4
+.IX Item "Internal inconsistency in tracking vforks"
+(S) A warning peculiar to VMS.  Perl keeps track of the number of times
+you've called \f(CW\*(C`fork\*(C'\fR and \f(CW\*(C`exec\*(C'\fR, to determine whether the current call
+to \f(CW\*(C`exec\*(C'\fR should affect the current script or a subprocess (see
+"exec LIST" in perlvms).  Somehow, this count has become scrambled, so
+Perl is making a guess and treating this \f(CW\*(C`exec\*(C'\fR as a request to
+terminate the Perl script and execute the specified command.
+.IP "internal %<num>p might conflict with future printf extensions" 4
+.IX Item "internal %<num>p might conflict with future printf extensions"
+(S internal) Perl's internal routine that handles \f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR
+formatting follows a slightly different set of rules when called from
+C or XS code.  Specifically, formats consisting of digits followed
+by "p" (e.g., "%7p") are reserved for future use.  If you see this
+message, then an XS module tried to call that routine with one such
+reserved format.
+.IP "Internal urp in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Internal urp in regex; marked by <--\ HERE in m/%s/"
+(P) Something went badly awry in the regular expression parser.  The
+<\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.ie n .IP "%s (...) interpreted as function" 4
+.el .IP "\f(CW%s\fR (...) interpreted as function" 4
+.IX Item "%s (...) interpreted as function"
+(W syntax) You've run afoul of the rule that says that any list operator
+followed by parentheses turns into a function, with all the list
+operators arguments found inside the parentheses.  See
+"Terms and List Operators (Leftward)" in perlop.
+.IP "In '(?...)', the '(' and '?' must be adjacent in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "In '(?...)', the '(' and '?' must be adjacent in regex; marked by <--\ HERE in m/%s/"
+(F) The two-character sequence \f(CW"(?"\fR in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the \f(CW"("\fR and the \f(CW"?"\fR, but you separated them
+with whitespace.
+.IP "In '(*...)', the '(' and '*' must be adjacent in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "In '(*...)', the '(' and '*' must be adjacent in regex; marked by <--\ HERE in m/%s/"
+(F) The two-character sequence \f(CW"(*"\fR in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the \f(CW"("\fR and the \f(CW"*"\fR, but you separated them.
+Fix the pattern and retry.
+.ie n .IP "Invalid %s attribute: %s" 4
+.el .IP "Invalid \f(CW%s\fR attribute: \f(CW%s\fR" 4
+.IX Item "Invalid %s attribute: %s"
+(F) The indicated attribute for a subroutine or variable was not recognized
+by Perl or by a user-supplied handler.  See attributes.
+.ie n .IP "Invalid %s attributes: %s" 4
+.el .IP "Invalid \f(CW%s\fR attributes: \f(CW%s\fR" 4
+.IX Item "Invalid %s attributes: %s"
+(F) The indicated attributes for a subroutine or variable were not
+recognized by Perl or by a user-supplied handler.  See attributes.
+.IP "Invalid character in charnames alias definition; marked by <\-\-\ HERE in '%s" 4
+.IX Item "Invalid character in charnames alias definition; marked by <--\ HERE in '%s"
+(F) You tried to create a custom alias for a character name, with
+the \f(CW\*(C`:alias\*(C'\fR option to \f(CW\*(C`use charnames\*(C'\fR and the specified character in
+the indicated name isn't valid.  See "CUSTOM ALIASES" in charnames.
+.ie n .IP "Invalid \e0 character in %s for %s: %s\e0%s" 4
+.el .IP "Invalid \e0 character in \f(CW%s\fR for \f(CW%s:\fR \f(CW%s\fR\e0%s" 4
+.IX Item "Invalid 0 character in %s for %s: %s0%s"
+(W syscalls) Embedded \e0 characters in pathnames or other system call
+arguments produce a warning as of 5.20.  The parts after the \e0 were
+formerly ignored by system calls.
+.IP "Invalid character in \eN{...}; marked by <\-\-\ HERE in \eN{%s}" 4
+.IX Item "Invalid character in N{...}; marked by <--\ HERE in N{%s}"
+(F) Only certain characters are valid for character names.  The
+indicated one isn't.  See "CUSTOM ALIASES" in charnames.
+.ie n .IP "Invalid conversion in %s: ""%s""" 4
+.el .IP "Invalid conversion in \f(CW%s:\fR ""%s""" 4
+.IX Item "Invalid conversion in %s: ""%s"""
+(W printf) Perl does not understand the given format conversion.  See
+"sprintf" in perlfunc.
+.IP "Invalid escape in the specified encoding in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Invalid escape in the specified encoding in regex; marked by <--\ HERE in m/%s/"
+(W regexp)(F) The numeric escape (for example \f(CW\*(C`\exHH\*(C'\fR) of value < 256
+didn't correspond to a single character through the conversion
+from the encoding specified by the encoding pragma.
+The escape was replaced with REPLACEMENT CHARACTER (U+FFFD)
+instead, except within \f(CW\*(C`(?[\ \ \ ])\*(C'\fR, where it is a fatal error.
+The <\-\-\ HERE shows whereabouts in the regular expression the
+escape was discovered.
+.IP "Invalid hexadecimal number in \eN{U+...}" 4
+.IX Item "Invalid hexadecimal number in N{U+...}"
+.PD 0
+.IP "Invalid hexadecimal number in \eN{U+...} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Invalid hexadecimal number in N{U+...} in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) The character constant represented by \f(CW\*(C`...\*(C'\fR is not a valid hexadecimal
+number.  Either it is empty, or you tried to use a character other than
+0 \- 9 or A \- F, a \- f in a hexadecimal number.
+.ie n .IP "Invalid module name %s with \-%c option: contains single ':'" 4
+.el .IP "Invalid module name \f(CW%s\fR with \-%c option: contains single ':'" 4
+.IX Item "Invalid module name %s with -%c option: contains single ':'"
+(F) The module argument to perl's \fB\-m\fR and \fB\-M\fR command-line options
+cannot contain single colons in the module name, but only in the
+arguments after "=".  In other words, \fB\-MFoo::Bar=:baz\fR is ok, but
+\&\fB\-MFoo:Bar=baz\fR is not.
+.IP "Invalid mro name: '%s'" 4
+.IX Item "Invalid mro name: '%s'"
+(F) You tried to \f(CW\*(C`mro::set_mro("classname", "foo")\*(C'\fR or \f(CW\*(C`use mro \*(Aqfoo\*(Aq\*(C'\fR,
+where \f(CW\*(C`foo\*(C'\fR is not a valid method resolution order (MRO).  Currently,
+the only valid ones supported are \f(CW\*(C`dfs\*(C'\fR and \f(CW\*(C`c3\*(C'\fR, unless you have loaded
+a module that is a MRO plugin.  See mro and perlmroapi.
+.IP "Invalid negative number (%s) in chr" 4
+.IX Item "Invalid negative number (%s) in chr"
+(W utf8) You passed a negative number to \f(CW\*(C`chr\*(C'\fR.  Negative numbers are
+not valid character numbers, so it returns the Unicode replacement
+character (U+FFFD).
+.IP "Invalid number '%s' for \-C option." 4
+.IX Item "Invalid number '%s' for -C option."
+(F) You supplied a number to the \-C option that either has extra leading
+zeroes or overflows perl's unsigned integer representation.
+.IP "invalid option \-D%c, use \-D'' to see choices" 4
+.IX Item "invalid option -D%c, use -D'' to see choices"
+(S debugging) Perl was called with invalid debugger flags.  Call perl
+with the \fB\-D\fR option with no flags to see the list of acceptable values.
+See also "\-Dletters" in perlrun.
+.IP "Invalid quantifier in {,} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Invalid quantifier in {,} in regex; marked by <--\ HERE in m/%s/"
+(F) The pattern looks like a {min,max} quantifier, but the min or max
+could not be parsed as a valid number \- either it has leading zeroes,
+or it represents too big a number to cope with.  The <\-\-\ HERE shows
+where in the regular expression the problem was discovered.  See perlre.
+.IP "Invalid [] range ""%s"" in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Invalid [] range ""%s"" in regex; marked by <--\ HERE in m/%s/"
+(F) The range specified in a character class had a minimum character
+greater than the maximum character.  One possibility is that you forgot the
+\&\f(CW\*(C`{}\*(C'\fR from your ending \f(CW\*(C`\ex{}\*(C'\fR \- \f(CW\*(C`\ex\*(C'\fR without the curly braces can go only
+up to \f(CW\*(C`ff\*(C'\fR.  The <\-\-\ HERE shows whereabouts in the regular expression the
+problem was discovered.  See perlre.
+.IP "Invalid range ""%s"" in transliteration operator" 4
+.IX Item "Invalid range ""%s"" in transliteration operator"
+(F) The range specified in the tr/// or y/// operator had a minimum
+character greater than the maximum character.  See perlop.
+.IP "Invalid reference to group in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Invalid reference to group in regex; marked by <--\ HERE in m/%s/"
+(F) The capture group you specified can't possibly exist because the
+number you used is not within the legal range of possible values for
+this machine.
+.ie n .IP "Invalid separator character %s in attribute list" 4
+.el .IP "Invalid separator character \f(CW%s\fR in attribute list" 4
+.IX Item "Invalid separator character %s in attribute list"
+(F) Something other than a colon or whitespace was seen between the
+elements of an attribute list.  If the previous attribute had a
+parenthesised parameter list, perhaps that list was terminated too soon.
+See attributes.
+.ie n .IP "Invalid separator character %s in PerlIO layer specification %s" 4
+.el .IP "Invalid separator character \f(CW%s\fR in PerlIO layer specification \f(CW%s\fR" 4
+.IX Item "Invalid separator character %s in PerlIO layer specification %s"
+(W layer) When pushing layers onto the Perl I/O system, something other
+than a colon or whitespace was seen between the elements of a layer list.
+If the previous attribute had a parenthesised parameter list, perhaps that
+list was terminated too soon.
+.IP "Invalid strict version format (%s)" 4
+.IX Item "Invalid strict version format (%s)"
+(F) A version number did not meet the "strict" criteria for versions.
+A "strict" version number is a positive decimal number (integer or
+decimal-fraction) without exponentiation or else a dotted-decimal
+v\-string with a leading 'v' character and at least three components.
+The parenthesized text indicates which criteria were not met.
+See the version module for more details on allowed version formats.
+.ie n .IP "Invalid type '%s' in %s" 4
+.el .IP "Invalid type '%s' in \f(CW%s\fR" 4
+.IX Item "Invalid type '%s' in %s"
+(F) The given character is not a valid pack or unpack type.
+See "pack" in perlfunc.
+.Sp
+(W) The given character is not a valid pack or unpack type but used to be
+silently ignored.
+.IP "Invalid version format (%s)" 4
+.IX Item "Invalid version format (%s)"
+(F) A version number did not meet the "lax" criteria for versions.
+A "lax" version number is a positive decimal number (integer or
+decimal-fraction) without exponentiation or else a dotted-decimal
+v\-string.  If the v\-string has fewer than three components, it
+must have a leading 'v' character.  Otherwise, the leading 'v' is
+optional.  Both decimal and dotted-decimal versions may have a
+trailing "alpha" component separated by an underscore character
+after a fractional or dotted-decimal component.  The parenthesized
+text indicates which criteria were not met.  See the version module
+for more details on allowed version formats.
+.IP "Invalid version object" 4
+.IX Item "Invalid version object"
+(F) The internal structure of the version object was invalid.
+Perhaps the internals were modified directly in some way or
+an arbitrary reference was blessed into the "version" class.
+.IP "In '(*VERB...)', the '(' and '*' must be adjacent in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "In '(*VERB...)', the '(' and '*' must be adjacent in regex; marked by <--\ HERE in m/%s/"
+.PD 0
+.IP "Inverting a character class which contains a multi-character sequence is illegal in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Inverting a character class which contains a multi-character sequence is illegal in regex; marked by <-- HERE in m/%s/"
+.PD
+(F) You wrote something like
+.Sp
+.Vb 2
+\& qr/\eP{name=KATAKANA LETTER AINU P}/
+\& qr/[^\ep{name=KATAKANA LETTER AINU P}]/
+.Ve
+.Sp
+This name actually evaluates to a sequence of two Katakana characters,
+not just a single one, and it is illegal to try to take the complement
+of a sequence.  (Mathematically it would mean any sequence of characters
+from 0 to infinity in length that weren't these two in a row, and that
+is likely not of any real use.)
+.Sp
+(F) The two-character sequence \f(CW"(*"\fR in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the \f(CW"("\fR and the \f(CW"*"\fR, but you separated them.
+.IP "ioctl is not implemented" 4
+.IX Item "ioctl is not implemented"
+(F) Your machine apparently doesn't implement \fBioctl()\fR, which is pretty
+strange for a machine that supports C.
+.ie n .IP "\fBioctl()\fR on unopened %s" 4
+.el .IP "\fBioctl()\fR on unopened \f(CW%s\fR" 4
+.IX Item "ioctl() on unopened %s"
+(W unopened) You tried \fBioctl()\fR on a filehandle that was never opened.
+Check your control flow and number of arguments.
+.IP "IO layers (like '%s') unavailable" 4
+.IX Item "IO layers (like '%s') unavailable"
+(F) Your Perl has not been configured to have PerlIO, and therefore
+you cannot use IO layers.  To have PerlIO, Perl must be configured
+with 'useperlio'.
+.IP "IO::Socket::atmark not implemented on this architecture" 4
+.IX Item "IO::Socket::atmark not implemented on this architecture"
+(F) Your machine doesn't implement the \fBsockatmark()\fR functionality,
+neither as a system call nor an ioctl call (SIOCATMARK).
+.IP "'%s' is an unknown bound type in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "'%s' is an unknown bound type in regex; marked by <--\ HERE in m/%s/"
+(F) You used \f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR and the \f(CW\*(C`...\*(C'\fR is not known to
+Perl.  The current valid ones are given in
+"\eb{}, \eb, \eB{}, \eB" in perlrebackslash.
+.IP "%s() isn't allowed on :utf8 handles" 4
+.IX Item "%s() isn't allowed on :utf8 handles"
+(F) The \fBsysread()\fR, \fBrecv()\fR, \fBsyswrite()\fR and \fBsend()\fR operators are
+not allowed on handles that have the \f(CW\*(C`:utf8\*(C'\fR layer, either explicitly, or
+implicitly, eg., with the \f(CW:encoding(UTF\-16LE)\fR layer.
+.Sp
+Previously \fBsysread()\fR and \fBrecv()\fR currently use only the \f(CW\*(C`:utf8\*(C'\fR flag for the stream,
+ignoring the actual layers.  Since \fBsysread()\fR and \fBrecv()\fR did no UTF\-8
+validation they can end up creating invalidly encoded scalars.
+.Sp
+Similarly, \fBsyswrite()\fR and \fBsend()\fR used only the \f(CW\*(C`:utf8\*(C'\fR flag, otherwise ignoring
+any layers.  If the flag is set, both wrote the value UTF\-8 encoded, even if
+the layer is some different encoding, such as the example above.
+.Sp
+Ideally, all of these operators would completely ignore the \f(CW\*(C`:utf8\*(C'\fR state,
+working only with bytes, but this would result in silently breaking existing
+code.
+.IP """%s"" is more clearly written simply as ""%s"" in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item """%s"" is more clearly written simply as ""%s"" in regex; marked by <--\ HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+You specified a character that has the given plainer way of writing it, and
+which is also portable to platforms running with different character sets.
+.IP "$* is no longer supported as of Perl 5.30" 4
+.IX Item "$* is no longer supported as of Perl 5.30"
+(F) The special variable \f(CW$*\fR, deprecated in older perls, was removed in
+5.10.0, is no longer supported and is a fatal error as of Perl 5.30.  In
+previous versions of perl the use of \f(CW$*\fR enabled or disabled multi-line
+matching within a string.
+.Sp
+Instead of using \f(CW$*\fR you should use the \f(CW\*(C`/m\*(C'\fR (and maybe \f(CW\*(C`/s\*(C'\fR) regexp
+modifiers.  You can enable \f(CW\*(C`/m\*(C'\fR for a lexical scope (even a whole file)
+with \f(CW\*(C`use re \*(Aq/m\*(Aq\*(C'\fR.  (In older versions: when \f(CW$*\fR was set to a true value
+then all regular expressions behaved as if they were written using \f(CW\*(C`/m\*(C'\fR.)
+.Sp
+Use of this variable will be a fatal error in Perl 5.30.
+.IP "$# is no longer supported as of Perl 5.30" 4
+.IX Item "$# is no longer supported as of Perl 5.30"
+(F) The special variable \f(CW$#\fR, deprecated in older perls, was removed as of
+5.10.0, is no longer supported and is a fatal error as of Perl 5.30.  You
+should use the printf/sprintf functions instead.
+.IP "'%s' is not a code reference" 4
+.IX Item "'%s' is not a code reference"
+(W overload) The second (fourth, sixth, ...) argument of
+overload::constant needs to be a code reference.  Either
+an anonymous subroutine, or a reference to a subroutine.
+.IP "'%s' is not an overloadable type" 4
+.IX Item "'%s' is not an overloadable type"
+(W overload) You tried to overload a constant type the overload package is
+unaware of.
+.IP "'%s' is not recognised as a builtin function" 4
+.IX Item "'%s' is not recognised as a builtin function"
+(F) An attempt was made to \f(CW\*(C`use\*(C'\fR the builtin pragma module to create
+a lexical alias for an unknown function name.
+.IP "\-i used with no filenames on the command line, reading from STDIN" 4
+.IX Item "-i used with no filenames on the command line, reading from STDIN"
+(S inplace) The \f(CW\*(C`\-i\*(C'\fR option was passed on the command line, indicating
+that the script is intended to edit files in place, but no files were
+given.  This is usually a mistake, since editing STDIN in place doesn't
+make sense, and can be confusing because it can make perl look like
+it is hanging when it is really just trying to read from STDIN.  You
+should either pass a filename to edit, or remove \f(CW\*(C`\-i\*(C'\fR from the command
+line.  See perlrun for more details.
+.IP "Junk on end of regexp in regex m/%s/" 4
+.IX Item "Junk on end of regexp in regex m/%s/"
+(P) The regular expression parser is confused.
+.IP "\eK not permitted in lookahead/lookbehind in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "K not permitted in lookahead/lookbehind in regex; marked by <-- HERE in m/%s/"
+(F) Your regular expression used \f(CW\*(C`\eK\*(C'\fR in a lookahead or lookbehind
+assertion, which currently isn't permitted.
+.Sp
+This may change in the future, see Support \eK in
+lookarounds <https://github.com/Perl/perl5/issues/18134>.
+.ie n .IP "Label not found for ""last %s""" 4
+.el .IP "Label not found for ""last \f(CW%s\fR""" 4
+.IX Item "Label not found for ""last %s"""
+(F) You named a loop to break out of, but you're not currently in a loop
+of that name, not even if you count where you were called from.  See
+"last" in perlfunc.
+.ie n .IP "Label not found for ""next %s""" 4
+.el .IP "Label not found for ""next \f(CW%s\fR""" 4
+.IX Item "Label not found for ""next %s"""
+(F) You named a loop to continue, but you're not currently in a loop of
+that name, not even if you count where you were called from.  See
+"last" in perlfunc.
+.ie n .IP "Label not found for ""redo %s""" 4
+.el .IP "Label not found for ""redo \f(CW%s\fR""" 4
+.IX Item "Label not found for ""redo %s"""
+(F) You named a loop to restart, but you're not currently in a loop of
+that name, not even if you count where you were called from.  See
+"last" in perlfunc.
+.ie n .IP "leaving effective %s failed" 4
+.el .IP "leaving effective \f(CW%s\fR failed" 4
+.IX Item "leaving effective %s failed"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, switching the real and
+effective uids or gids failed.
+.IP "length/code after end of string in unpack" 4
+.IX Item "length/code after end of string in unpack"
+(F) While unpacking, the string buffer was already used up when an unpack
+length/code combination tried to obtain more data.  This results in
+an undefined value for the length.  See "pack" in perlfunc.
+.ie n .IP "\fBlength()\fR used on %s (did you mean ""scalar(%s)""?)" 4
+.el .IP "\fBlength()\fR used on \f(CW%s\fR (did you mean ""scalar(%s)""?)" 4
+.IX Item "length() used on %s (did you mean ""scalar(%s)""?)"
+(W syntax) You used \fBlength()\fR on either an array or a hash when you
+probably wanted a count of the items.
+.Sp
+Array size can be obtained by doing:
+.Sp
+.Vb 1
+\&    scalar(@array);
+.Ve
+.Sp
+The number of items in a hash can be obtained by doing:
+.Sp
+.Vb 1
+\&    scalar(keys %hash);
+.Ve
+.IP "Lexing code attempted to stuff non\-Latin\-1 character into Latin\-1 input" 4
+.IX Item "Lexing code attempted to stuff non-Latin-1 character into Latin-1 input"
+(F) An extension is attempting to insert text into the current parse
+(using lex_stuff_pvn or similar), but tried to insert a character that
+couldn't be part of the current input.  This is an inherent pitfall
+of the stuffing mechanism, and one of the reasons to avoid it.  Where
+it is necessary to stuff, stuffing only plain ASCII is recommended.
+.IP "Lexing code internal error (%s)" 4
+.IX Item "Lexing code internal error (%s)"
+(F) Lexing code supplied by an extension violated the lexer's API in a
+detectable way.
+.ie n .IP "\fBlisten()\fR on closed socket %s" 4
+.el .IP "\fBlisten()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "listen() on closed socket %s"
+(W closed) You tried to do a listen on a closed socket.  Did you forget
+to check the return value of your \fBsocket()\fR call?  See
+"listen" in perlfunc.
+.IP "List form of piped open not implemented" 4
+.IX Item "List form of piped open not implemented"
+(F) On some platforms, notably Windows, the three-or-more-arguments
+form of \f(CW\*(C`open\*(C'\fR does not support pipes, such as \f(CW\*(C`open($pipe, \*(Aq|\-\*(Aq, @args)\*(C'\fR.
+Use the two-argument \f(CW\*(C`open($pipe, \*(Aq|prog arg1 arg2...\*(Aq)\*(C'\fR form instead.
+.IP "Literal vertical space in [] is illegal except under /x in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Literal vertical space in [] is illegal except under /x in regex; marked by <--\ HERE in m/%s/"
+(F) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+Likely you forgot the \f(CW\*(C`/x\*(C'\fR modifier or there was a typo in the pattern.
+For example, did you really mean to match a form-feed?  If so, all the
+ASCII vertical space control characters are representable by escape
+sequences which won't present such a jarring appearance as your pattern
+does when displayed.
+.Sp
+.Vb 4
+\&  \er    carriage return
+\&  \ef    form feed
+\&  \en    line feed
+\&  \ecK   vertical tab
+.Ve
+.ie n .IP "%s: loadable library and perl binaries are mismatched (got %s handshake key %p, needed %p)" 4
+.el .IP "\f(CW%s:\fR loadable library and perl binaries are mismatched (got \f(CW%s\fR handshake key \f(CW%p\fR, needed \f(CW%p\fR)" 4
+.IX Item "%s: loadable library and perl binaries are mismatched (got %s handshake key %p, needed %p)"
+(P) A dynamic loading library \f(CW\*(C`.so\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR was being loaded into the
+process that was built against a different build of perl than the
+said library was compiled against.  Reinstalling the XS module will
+likely fix this error.
+.ie n .IP "Locale '%s' contains (at least) the following characters which have unexpected meanings: %s  The Perl program will use the expected meanings" 4
+.el .IP "Locale '%s' contains (at least) the following characters which have unexpected meanings: \f(CW%s\fR  The Perl program will use the expected meanings" 4
+.IX Item "Locale '%s' contains (at least) the following characters which have unexpected meanings: %s The Perl program will use the expected meanings"
+(W locale) You are using the named UTF\-8 locale.  UTF\-8 locales are
+expected to have very particular behavior, which most do.  This message
+arises when perl found some departures from the expectations, and is
+notifying you that the expected behavior overrides these differences.
+In some cases the differences are caused by the locale definition being
+defective, but the most common causes of this warning are when there are
+ambiguities and conflicts in following the Standard, and the locale has
+chosen an approach that differs from Perl's.
+.Sp
+One of these is because that, contrary to the claims, Unicode is not
+completely locale insensitive.  Turkish and some related languages
+have two types of \f(CW"I"\fR characters.  One is dotted in both upper\- and
+lowercase, and the other is dotless in both cases.  Unicode allows a
+locale to use either the Turkish rules, or the rules used in all other
+instances, where there is only one type of \f(CW"I"\fR, which is dotless in
+the uppercase, and dotted in the lower.  The perl core does not (yet)
+handle the Turkish case, and this message warns you of that.  Instead,
+the Unicode::Casing module allows you to mostly implement the Turkish
+casing rules.
+.Sp
+The other common cause is for the characters
+.Sp
+.Vb 1
+\& $ + < = > ^ \` | ~
+.Ve
+.Sp
+These are problematic.  The C standard says that these should be
+considered punctuation in the C locale (and the POSIX standard defers to
+the C standard), and Unicode is generally considered a superset of
+the C locale.  But Unicode has added an extra category, "Symbol", and
+classifies these particular characters as being symbols.  Most UTF\-8
+locales have them treated as punctuation, so that \fBispunct\fR\|(3) returns
+non-zero for them.  But a few locales have it return 0.   Perl takes
+the first approach, not using \f(CWispunct()\fR at all (see Note [5] in
+perlrecharclass), and this message is raised to notify you that you
+are getting Perl's approach, not the locale's.
+.IP "Locale '%s' is unsupported, and may crash the interpreter." 4
+.IX Item "Locale '%s' is unsupported, and may crash the interpreter."
+(S locale) The named locale is not supported by Perl, and using it leads
+to undefined behavior, including potentially crashing the computer.
+.Sp
+Currently the only locales that generate this severe warning are
+non\-UTF\-8 ones which have characters that require more than one byte to
+represent (common in older East Asian language locales).  See
+perllocale.
+.IP "Locale '%s' may not work well.%s" 4
+.IX Item "Locale '%s' may not work well.%s"
+(W locale) You are using the named locale, which is a non\-UTF\-8 one, and
+which perl has determined is not fully compatible with what it can
+handle.  The second \f(CW%s\fR gives a reason.
+.Sp
+By far the most common reason is that the locale has characters in it
+that are represented by more than one byte.  The only such locales that
+Perl can handle are the UTF\-8 locales.  Most likely the specified locale
+is a non\-UTF\-8 one for an East Asian language such as Chinese or
+Japanese.  If the locale is a superset of ASCII, the ASCII portion of it
+may work in Perl.
+.Sp
+Some essentially obsolete locales that aren't supersets of ASCII, mainly
+those in ISO 646 or other 7\-bit locales, such as ASMO 449, can also have
+problems, depending on what portions of the ASCII character set get
+changed by the locale and are also used by the program.
+The warning message lists the determinable conflicting characters.
+.Sp
+Note that not all incompatibilities are found.
+.Sp
+If this happens to you, there's not much you can do except switch to use a
+different locale or use Encode to translate from the locale into
+UTF\-8; if that's impracticable, you have been warned that some things
+may break.
+.Sp
+This message is output once each time a bad locale is switched into
+within the scope of \f(CW\*(C`use\ locale\*(C'\fR, or on the first possibly-affected
+operation if the \f(CW\*(C`use\ locale\*(C'\fR inherits a bad one.  It is not raised
+for any operations from the POSIX module.
+.IP "localtime(%f) failed" 4
+.IX Item "localtime(%f) failed"
+(W overflow) You called \f(CW\*(C`localtime\*(C'\fR with a number that it could not handle:
+too large, too small, or NaN.  The returned value is \f(CW\*(C`undef\*(C'\fR.
+.IP "localtime(%f) too large" 4
+.IX Item "localtime(%f) too large"
+(W overflow) You called \f(CW\*(C`localtime\*(C'\fR with a number that was larger
+than it can reliably handle and \f(CW\*(C`localtime\*(C'\fR probably returned the
+wrong date.  This warning is also triggered with NaN (the special
+not-a-number value).
+.IP "localtime(%f) too small" 4
+.IX Item "localtime(%f) too small"
+(W overflow) You called \f(CW\*(C`localtime\*(C'\fR with a number that was smaller
+than it can reliably handle and \f(CW\*(C`localtime\*(C'\fR probably returned the
+wrong date.
+.ie n .IP "Lookbehind longer than %d not implemented in regex m/%s/" 4
+.el .IP "Lookbehind longer than \f(CW%d\fR not implemented in regex m/%s/" 4
+.IX Item "Lookbehind longer than %d not implemented in regex m/%s/"
+(F) There is currently a limit on the length of string which lookbehind can
+handle.  This restriction may be eased in a future release.
+.ie n .IP "Lost precision when %s %f by 1" 4
+.el .IP "Lost precision when \f(CW%s\fR \f(CW%f\fR by 1" 4
+.IX Item "Lost precision when %s %f by 1"
+(W imprecision) You attempted to increment or decrement a value by one,
+but the result is too large for the underlying floating point
+representation to store accurately. Hence, the target of \f(CW\*(C`++\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR
+is increased or decreased by quite different value than one, such as
+zero (\fIi.e.\fR the target is unchanged) or two, due to rounding.
+Perl issues this
+warning because it has already switched from integers to floating point
+when values are too large for integers, and now even floating point is
+insufficient.  You may wish to switch to using Math::BigInt explicitly.
+.IP "\fBlstat()\fR on filehandle%s" 4
+.IX Item "lstat() on filehandle%s"
+(W io) You tried to do an lstat on a filehandle.  What did you mean
+by that?  \fBlstat()\fR makes sense only on filenames.  (Perl did a \fBfstat()\fR
+instead on the filehandle.)
+.ie n .IP "lvalue attribute %s already-defined subroutine" 4
+.el .IP "lvalue attribute \f(CW%s\fR already-defined subroutine" 4
+.IX Item "lvalue attribute %s already-defined subroutine"
+(W misc) Although attributes.pm allows this, turning the lvalue
+attribute on or off on a Perl subroutine that is already defined
+does not always work properly.  It may or may not do what you
+want, depending on what code is inside the subroutine, with exact
+details subject to change between Perl versions.  Only do this
+if you really know what you are doing.
+.IP "lvalue attribute ignored after the subroutine has been defined" 4
+.IX Item "lvalue attribute ignored after the subroutine has been defined"
+(W misc) Using the \f(CW\*(C`:lvalue\*(C'\fR declarative syntax to make a Perl
+subroutine an lvalue subroutine after it has been defined is
+not permitted.  To make the subroutine an lvalue subroutine,
+add the lvalue attribute to the definition, or put the \f(CW\*(C`sub
+foo :lvalue;\*(C'\fR declaration before the definition.
+.Sp
+See also attributes.pm.
+.IP "Magical list constants are not supported" 4
+.IX Item "Magical list constants are not supported"
+(F) You assigned a magical array to a stash element, and then tried
+to use the subroutine from the same slot.  You are asking Perl to do
+something it cannot do, details subject to change between Perl versions.
+.IP "Malformed integer in [] in pack" 4
+.IX Item "Malformed integer in [] in pack"
+(F) Between the brackets enclosing a numeric repeat count only digits
+are permitted.  See "pack" in perlfunc.
+.IP "Malformed integer in [] in unpack" 4
+.IX Item "Malformed integer in [] in unpack"
+(F) Between the brackets enclosing a numeric repeat count only digits
+are permitted.  See "pack" in perlfunc.
+.IP "Malformed PERLLIB_PREFIX" 4
+.IX Item "Malformed PERLLIB_PREFIX"
+(F) An error peculiar to OS/2.  PERLLIB_PREFIX should be of the form
+.Sp
+.Vb 1
+\&    prefix1;prefix2
+.Ve
+.Sp
+or
+    prefix1 prefix2
+.Sp
+with nonempty prefix1 and prefix2.  If \f(CW\*(C`prefix1\*(C'\fR is indeed a prefix of
+a builtin library search path, prefix2 is substituted.  The error may
+appear if components are not found, or are too long.  See
+"PERLLIB_PREFIX" in perlos2.
+.ie n .IP "Malformed prototype for %s: %s" 4
+.el .IP "Malformed prototype for \f(CW%s:\fR \f(CW%s\fR" 4
+.IX Item "Malformed prototype for %s: %s"
+(F) You tried to use a function with a malformed prototype.  The
+syntax of function prototypes is given a brief compile-time check for
+obvious errors like invalid characters.  A more rigorous check is run
+when the function is called.
+Perhaps the function's author was trying to write a subroutine signature
+but didn't enable that feature first (\f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR),
+so the signature was instead interpreted as a bad prototype.
+.IP "Malformed UTF\-8 character%s" 4
+.IX Item "Malformed UTF-8 character%s"
+(S utf8)(F) Perl detected a string that should be UTF\-8, but didn't
+comply with UTF\-8 encoding rules, or represents a code point whose
+ordinal integer value doesn't fit into the word size of the current
+platform (overflows).  Details as to the exact malformation are given in
+the variable, \f(CW%s\fR, part of the message.
+.Sp
+One possible cause is that you set the UTF8 flag yourself for data that
+you thought to be in UTF\-8 but it wasn't (it was for example legacy 8\-bit
+data).  To guard against this, you can use \f(CW\*(C`Encode::decode(\*(AqUTF\-8\*(Aq, ...)\*(C'\fR.
+.Sp
+If you use the \f(CW:encoding(UTF\-8)\fR PerlIO layer for input, invalid byte
+sequences are handled gracefully, but if you use \f(CW\*(C`:utf8\*(C'\fR, the flag is set
+without validating the data, possibly resulting in this error message.
+.Sp
+See also "Handling Malformed Data" in Encode.
+.IP "Malformed UTF\-8 returned by \eN{%s} immediately after '%s'" 4
+.IX Item "Malformed UTF-8 returned by N{%s} immediately after '%s'"
+(F) The charnames handler returned malformed UTF\-8.
+.IP "Malformed UTF\-8 string in ""%s""" 4
+.IX Item "Malformed UTF-8 string in ""%s"""
+(F) This message indicates a bug either in the Perl core or in XS
+code. Such code was trying to find out if a character, allegedly
+stored internally encoded as UTF\-8, was of a given type, such as
+being punctuation or a digit.  But the character was not encoded
+in legal UTF\-8.  The \f(CW%s\fR is replaced by a string that can be used
+by knowledgeable people to determine what the type being checked
+against was.
+.Sp
+Passing malformed strings was deprecated in Perl 5.18, and
+became fatal in Perl 5.26.
+.IP "Malformed UTF\-8 string in '%c' format in unpack" 4
+.IX Item "Malformed UTF-8 string in '%c' format in unpack"
+(F) You tried to unpack something that didn't comply with UTF\-8 encoding
+rules and perl was unable to guess how to make more progress.
+.IP "Malformed UTF\-8 string in pack" 4
+.IX Item "Malformed UTF-8 string in pack"
+(F) You tried to pack something that didn't comply with UTF\-8 encoding
+rules and perl was unable to guess how to make more progress.
+.IP "Malformed UTF\-8 string in unpack" 4
+.IX Item "Malformed UTF-8 string in unpack"
+(F) You tried to unpack something that didn't comply with UTF\-8 encoding
+rules and perl was unable to guess how to make more progress.
+.IP "Malformed UTF\-16 surrogate" 4
+.IX Item "Malformed UTF-16 surrogate"
+(F) Perl thought it was reading UTF\-16 encoded character data but while
+doing it Perl met a malformed Unicode surrogate.
+.IP "Mandatory parameter follows optional parameter" 4
+.IX Item "Mandatory parameter follows optional parameter"
+(F) In a subroutine signature, you wrote something like "$a = undef,
+\&\f(CW$b\fR", making an earlier parameter optional and a later one mandatory.
+Parameters are filled from left to right, so it's impossible for the
+caller to omit an earlier one and pass a later one.  If you want to act
+as if the parameters are filled from right to left, declare the rightmost
+optional and then shuffle the parameters around in the subroutine's body.
+.IP "Matched non-Unicode code point 0x%X against Unicode property; may not be portable" 4
+.IX Item "Matched non-Unicode code point 0x%X against Unicode property; may not be portable"
+(S non_unicode) Perl allows strings to contain a superset of
+Unicode code points; each code point may be as large as what is storable
+in a signed integer on your system, but these may not be accepted by
+other languages/systems.  This message occurs when you matched a string
+containing such a code point against a regular expression pattern, and
+the code point was matched against a Unicode property, \f(CW\*(C`\ep{...}\*(C'\fR or
+\&\f(CW\*(C`\eP{...}\*(C'\fR.  Unicode properties are only defined on Unicode code points,
+so the result of this match is undefined by Unicode, but Perl (starting
+in v5.20) treats non-Unicode code points as if they were typical
+unassigned Unicode ones, and matched this one accordingly.  Whether a
+given property matches these code points or not is specified in
+"Properties accessible through \ep{} and \eP{}" in perluniprops.
+.Sp
+This message is suppressed (unless it has been made fatal) if it is
+immaterial to the results of the match if the code point is Unicode or
+not.  For example, the property \f(CW\*(C`\ep{ASCII_Hex_Digit}\*(C'\fR only can match
+the 22 characters \f(CW\*(C`[0\-9A\-Fa\-f]\*(C'\fR, so obviously all other code points,
+Unicode or not, won't match it.  (And \f(CW\*(C`\eP{ASCII_Hex_Digit}\*(C'\fR will match
+every code point except these 22.)
+.Sp
+Getting this message indicates that the outcome of the match arguably
+should have been the opposite of what actually happened.  If you think
+that is the case, you may wish to make the \f(CW\*(C`non_unicode\*(C'\fR warnings
+category fatal; if you agree with Perl's decision, you may wish to turn
+off this category.
+.Sp
+See "Beyond Unicode code points" in perlunicode for more information.
+.ie n .IP "%s matches null string many times in regex; marked by <\-\-\ HERE in m/%s/" 4
+.el .IP "\f(CW%s\fR matches null string many times in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "%s matches null string many times in regex; marked by <--\ HERE in m/%s/"
+(W regexp) The pattern you've specified would be an infinite loop if the
+regular expression engine didn't specifically check for that.  The <\-\-\ HERE
+shows whereabouts in the regular expression the problem was discovered.
+See perlre.
+.IP "Maximal count of pending signals (%u) exceeded" 4
+.IX Item "Maximal count of pending signals (%u) exceeded"
+(F) Perl aborted due to too high a number of signals pending.  This
+usually indicates that your operating system tried to deliver signals
+too fast (with a very high priority), starving the perl process from
+resources it would need to reach a point where it can process signals
+safely.  (See "Deferred Signals (Safe Signals)" in perlipc.)
+.IP """%s"" may clash with future reserved word" 4
+.IX Item """%s"" may clash with future reserved word"
+(W) This warning may be due to running a perl5 script through a perl4
+interpreter, especially if the word that is being warned about is
+"use" or "my".
+.IP "'%' may not be used in pack" 4
+.IX Item "'%' may not be used in pack"
+(F) You can't pack a string by supplying a checksum, because the
+checksumming process loses information, and you can't go the other way.
+See "unpack" in perlfunc.
+.ie n .IP "Method for operation %s not found in package %s during blessing" 4
+.el .IP "Method for operation \f(CW%s\fR not found in package \f(CW%s\fR during blessing" 4
+.IX Item "Method for operation %s not found in package %s during blessing"
+(F) An attempt was made to specify an entry in an overloading table that
+doesn't resolve to a valid subroutine.  See overload.
+.IP "method is experimental" 4
+.IX Item "method is experimental"
+(S experimental::class) This warning is emitted if you use the \f(CW\*(C`method\*(C'\fR
+keyword of \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR.  This keyword is currently
+experimental and its behaviour may change in future releases of Perl.
+.ie n .IP "Method %s not permitted" 4
+.el .IP "Method \f(CW%s\fR not permitted" 4
+.IX Item "Method %s not permitted"
+See "500 Server error".
+.ie n .IP "Method %s redefined" 4
+.el .IP "Method \f(CW%s\fR redefined" 4
+.IX Item "Method %s redefined"
+(W redefine) You redefined a method.  To suppress this warning, say
+.Sp
+.Vb 4
+\&    {
+\&        no warnings \*(Aqredefine\*(Aq;
+\&        *name = method { ... };
+\&    }
+.Ve
+.ie n .IP "Might be a runaway multi-line %s string starting on line %d" 4
+.el .IP "Might be a runaway multi-line \f(CW%s\fR string starting on line \f(CW%d\fR" 4
+.IX Item "Might be a runaway multi-line %s string starting on line %d"
+(S) An advisory indicating that the previous error may have been caused
+by a missing delimiter on a string or pattern, because it eventually
+ended earlier on the current line.
+.IP "Mismatched brackets in template" 4
+.IX Item "Mismatched brackets in template"
+(F) A pack template could not be parsed because pairs of \f(CW\*(C`[...]\*(C'\fR or
+\&\f(CW\*(C`(...)\*(C'\fR could not be matched up. See "pack" in perlfunc.
+.IP "Misplaced _ in number" 4
+.IX Item "Misplaced _ in number"
+(W syntax) An underscore (underbar) in a numeric constant did not
+separate two digits.
+.ie n .IP "Missing argument for %n in %s" 4
+.el .IP "Missing argument for \f(CW%n\fR in \f(CW%s\fR" 4
+.IX Item "Missing argument for %n in %s"
+(F) A \f(CW%n\fR was used in a format string with no corresponding argument for
+perl to write the current string length to.
+.ie n .IP "Missing argument in %s" 4
+.el .IP "Missing argument in \f(CW%s\fR" 4
+.IX Item "Missing argument in %s"
+(W missing) You called a function with fewer arguments than other
+arguments you supplied indicated would be needed.
+.Sp
+Currently only emitted when a printf-type format required more
+arguments than were supplied, but might be used in the future for
+other cases where we can statically determine that arguments to
+functions are missing, e.g. for the "pack" in perlfunc function.
+.IP "Missing argument to \-%c" 4
+.IX Item "Missing argument to -%c"
+(F) The argument to the indicated command line switch must follow
+immediately after the switch, without intervening spaces.
+.IP "Missing braces on \eN{}" 4
+.IX Item "Missing braces on N{}"
+.PD 0
+.IP "Missing braces on \eN{} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Missing braces on N{} in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) Wrong syntax of character name literal \f(CW\*(C`\eN{charname}\*(C'\fR within
+double-quotish context.  This can also happen when there is a space
+(or comment) between the \f(CW\*(C`\eN\*(C'\fR and the \f(CW\*(C`{\*(C'\fR in a regex with the \f(CW\*(C`/x\*(C'\fR modifier.
+This modifier does not change the requirement that the brace immediately
+follow the \f(CW\*(C`\eN\*(C'\fR.
+.IP "Missing braces on \eo{}" 4
+.IX Item "Missing braces on o{}"
+(F) A \f(CW\*(C`\eo\*(C'\fR must be followed immediately by a \f(CW\*(C`{\*(C'\fR in double-quotish context.
+.ie n .IP "Missing comma after first argument to %s function" 4
+.el .IP "Missing comma after first argument to \f(CW%s\fR function" 4
+.IX Item "Missing comma after first argument to %s function"
+(F) While certain functions allow you to specify a filehandle or an
+"indirect object" before the argument list, this ain't one of them.
+.IP "Missing command in piped open" 4
+.IX Item "Missing command in piped open"
+(W pipe) You used the \f(CW\*(C`open(FH, "| command")\*(C'\fR or
+\&\f(CW\*(C`open(FH, "command |")\*(C'\fR construction, but the command was missing or
+blank.
+.IP "Missing control char name in \ec" 4
+.IX Item "Missing control char name in c"
+(F) A double-quoted string ended with "\ec", without the required control
+character name.
+.ie n .IP "Missing ']' in prototype for %s : %s" 4
+.el .IP "Missing ']' in prototype for \f(CW%s\fR : \f(CW%s\fR" 4
+.IX Item "Missing ']' in prototype for %s : %s"
+(W illegalproto) A grouping was started with \f(CW\*(C`[\*(C'\fR but never closed with \f(CW\*(C`]\*(C'\fR.
+.IP "Missing name in ""%s sub""" 4
+.IX Item "Missing name in ""%s sub"""
+(F) The syntax for lexically scoped subroutines requires that
+they have a name with which they can be found.
+.IP "Missing $ on loop variable" 4
+.IX Item "Missing $ on loop variable"
+(F) Apparently you've been programming in \fBcsh\fR too much.  Variables
+are always mentioned with the $ in Perl, unlike in the shells, where it
+can vary from one line to the next.
+.ie n .IP "(Missing operator before %s?)" 4
+.el .IP "(Missing operator before \f(CW%s\fR?)" 4
+.IX Item "(Missing operator before %s?)"
+(S syntax) This is an educated guess made in conjunction with the message
+"%s found where operator expected".  Often the missing operator is a comma.
+.ie n .IP "Missing or undefined argument to %s" 4
+.el .IP "Missing or undefined argument to \f(CW%s\fR" 4
+.IX Item "Missing or undefined argument to %s"
+(F) You tried to call \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR with no argument or with an
+undefined value as an argument.  Require expects either a package name or
+a file-specification as an argument; do expects a filename.  See
+"require EXPR" in perlfunc and "do EXPR" in perlfunc.
+.ie n .IP "Missing or undefined argument to %s via %{^HOOK}{require_\|_before}" 4
+.el .IP "Missing or undefined argument to \f(CW%s\fR via %{^HOOK}{require_\|_before}" 4
+.IX Item "Missing or undefined argument to %s via %{^HOOK}{require__before}"
+(F) A \f(CW\*(C`%{^HOOK}{require_\|_before}\*(C'\fR hook rewrote the name of the file being
+compiled with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR with an empty string an undefined value
+which is forbidden.  See "%{^HOOK}" in perlvar and "require EXPR" in perlfunc.
+.IP "Missing right brace on \e%c{} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Missing right brace on %c{} in regex; marked by <--\ HERE in m/%s/"
+(F) Missing right brace in \f(CW\*(C`\ex{...}\*(C'\fR, \f(CW\*(C`\ep{...}\*(C'\fR, \f(CW\*(C`\eP{...}\*(C'\fR, or \f(CW\*(C`\eN{...}\*(C'\fR.
+.IP "Missing right brace on \eN{}" 4
+.IX Item "Missing right brace on N{}"
+.PD 0
+.IP "Missing right brace on \eN{} or unescaped left brace after \eN" 4
+.IX Item "Missing right brace on N{} or unescaped left brace after N"
+.PD
+(F) \f(CW\*(C`\eN\*(C'\fR has two meanings.
+.Sp
+The traditional one has it followed by a name enclosed in braces,
+meaning the character (or sequence of characters) given by that
+name.  Thus \f(CW\*(C`\eN{ASTERISK}\*(C'\fR is another way of writing \f(CW\*(C`*\*(C'\fR, valid in both
+double-quoted strings and regular expression patterns.  In patterns,
+it doesn't have the meaning an unescaped \f(CW\*(C`*\*(C'\fR does.
+.Sp
+Starting in Perl 5.12.0, \f(CW\*(C`\eN\*(C'\fR also can have an additional meaning (only)
+in patterns, namely to match a non-newline character.  (This is short
+for \f(CW\*(C`[^\en]\*(C'\fR, and like \f(CW\*(C`.\*(C'\fR but is not affected by the \f(CW\*(C`/s\*(C'\fR regex modifier.)
+.Sp
+This can lead to some ambiguities.  When \f(CW\*(C`\eN\*(C'\fR is not followed immediately
+by a left brace, Perl assumes the \f(CW\*(C`[^\en]\*(C'\fR meaning.  Also, if the braces
+form a valid quantifier such as \f(CW\*(C`\eN{3}\*(C'\fR or \f(CW\*(C`\eN{5,}\*(C'\fR, Perl assumes that this
+means to match the given quantity of non-newlines (in these examples,
+3; and 5 or more, respectively).  In all other case, where there is a
+\&\f(CW\*(C`\eN{\*(C'\fR and a matching \f(CW\*(C`}\*(C'\fR, Perl assumes that a character name is desired.
+.Sp
+However, if there is no matching \f(CW\*(C`}\*(C'\fR, Perl doesn't know if it was
+mistakenly omitted, or if \f(CW\*(C`[^\en]{\*(C'\fR was desired, and raises this error.
+If you meant the former, add the right brace; if you meant the latter,
+escape the brace with a backslash, like so: \f(CW\*(C`\eN\e{\*(C'\fR
+.IP "Missing right curly or square bracket" 4
+.IX Item "Missing right curly or square bracket"
+(F) The lexer counted more opening curly or square brackets than closing
+ones.  As a general rule, you'll find it's missing near the place you
+were last editing.
+.IP "(Missing semicolon on previous line?)" 4
+.IX Item "(Missing semicolon on previous line?)"
+(S syntax) This is an educated guess made in conjunction with the message
+"%s found where operator expected".  Don't automatically put a semicolon on
+the previous line just because you saw this message.
+.IP "Modification of a read-only value attempted" 4
+.IX Item "Modification of a read-only value attempted"
+(F) You tried, directly or indirectly, to change the value of a
+constant.  You didn't, of course, try "2 = 1", because the compiler
+catches that.  But an easy way to do the same thing is:
+.Sp
+.Vb 2
+\&    sub mod { $_[0] = 1 }
+\&    mod(2);
+.Ve
+.Sp
+Another way is to assign to a \fBsubstr()\fR that's off the end of the string.
+.Sp
+Yet another way is to assign to a \f(CW\*(C`foreach\*(C'\fR loop \fIVAR\fR when \fIVAR\fR
+is aliased to a constant in the look \fILIST\fR:
+.Sp
+.Vb 4
+\&    $x = 1;
+\&    foreach my $n ($x, 2) {
+\&        $n *= 2; # modifies the $x, but fails on attempt to
+\&    }            # modify the 2
+.Ve
+.Sp
+PerlIO::scalar will also produce this message as a warning if you
+attempt to open a read-only scalar for writing.
+.ie n .IP "Modification of non-creatable array value attempted, %s" 4
+.el .IP "Modification of non-creatable array value attempted, \f(CW%s\fR" 4
+.IX Item "Modification of non-creatable array value attempted, %s"
+(F) You tried to make an array value spring into existence, and the
+subscript was probably negative, even counting from end of the array
+backwards.
+.ie n .IP "Modification of non-creatable hash value attempted, %s" 4
+.el .IP "Modification of non-creatable hash value attempted, \f(CW%s\fR" 4
+.IX Item "Modification of non-creatable hash value attempted, %s"
+(P) You tried to make a hash value spring into existence, and it
+couldn't be created for some peculiar reason.
+.IP "Module name must be constant" 4
+.IX Item "Module name must be constant"
+(F) Only a bare module name is allowed as the first argument to a "use".
+.IP "Module name required with \-%c option" 4
+.IX Item "Module name required with -%c option"
+(F) The \f(CW\*(C`\-M\*(C'\fR or \f(CW\*(C`\-m\*(C'\fR options say that Perl should load some module, but
+you omitted the name of the module.  Consult
+perlrun for full details about \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-m\*(C'\fR.
+.IP "More than one argument to '%s' open" 4
+.IX Item "More than one argument to '%s' open"
+(F) The \f(CW\*(C`open\*(C'\fR function has been asked to open multiple files.  This
+can happen if you are trying to open a pipe to a command that takes a
+list of arguments, but have forgotten to specify a piped open mode.
+See "open" in perlfunc for details.
+.ie n .IP "mprotect for COW string %p %u failed with %d" 4
+.el .IP "mprotect for COW string \f(CW%p\fR \f(CW%u\fR failed with \f(CW%d\fR" 4
+.IX Item "mprotect for COW string %p %u failed with %d"
+(S) You compiled perl with \fB\-D\fRPERL_DEBUG_READONLY_COW (see
+"Copy on Write" in perlguts), but a shared string buffer
+could not be made read-only.
+.ie n .IP "mprotect for %p %u failed with %d" 4
+.el .IP "mprotect for \f(CW%p\fR \f(CW%u\fR failed with \f(CW%d\fR" 4
+.IX Item "mprotect for %p %u failed with %d"
+(S) You compiled perl with \fB\-D\fRPERL_DEBUG_READONLY_OPS (see perlhacktips),
+but an op tree could not be made read-only.
+.ie n .IP "mprotect RW for COW string %p %u failed with %d" 4
+.el .IP "mprotect RW for COW string \f(CW%p\fR \f(CW%u\fR failed with \f(CW%d\fR" 4
+.IX Item "mprotect RW for COW string %p %u failed with %d"
+(S) You compiled perl with \fB\-D\fRPERL_DEBUG_READONLY_COW (see
+"Copy on Write" in perlguts), but a read-only shared string
+buffer could not be made mutable.
+.ie n .IP "mprotect RW for %p %u failed with %d" 4
+.el .IP "mprotect RW for \f(CW%p\fR \f(CW%u\fR failed with \f(CW%d\fR" 4
+.IX Item "mprotect RW for %p %u failed with %d"
+(S) You compiled perl with \fB\-D\fRPERL_DEBUG_READONLY_OPS (see
+perlhacktips), but a read-only op tree could not be made
+mutable before freeing the ops.
+.IP "msg%s not implemented" 4
+.IX Item "msg%s not implemented"
+(F) You don't have System V message IPC on your system.
+.IP "Multidimensional hash lookup is disabled" 4
+.IX Item "Multidimensional hash lookup is disabled"
+(F) You supplied a list of subscripts to a hash lookup under
+\&\f(CW\*(C`no feature "multidimensional";\*(C'\fR, eg:
+.Sp
+.Vb 1
+\&  $z = $foo{$x, $y};
+.Ve
+.Sp
+which by default acts like:
+.Sp
+.Vb 1
+\&  $z = $foo{join($;, $x, $y)};
+.Ve
+.ie n .IP "Multidimensional syntax %s not supported" 4
+.el .IP "Multidimensional syntax \f(CW%s\fR not supported" 4
+.IX Item "Multidimensional syntax %s not supported"
+(W syntax) Multidimensional arrays aren't written like \f(CW$foo[1,2,3]\fR.
+They're written like \f(CW\*(C`$foo[1][2][3]\*(C'\fR, as in C.
+.IP "Multiple slurpy parameters not allowed" 4
+.IX Item "Multiple slurpy parameters not allowed"
+(F) In subroutine signatures, a slurpy parameter (\f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR) must be
+the last parameter, and there must not be more than one of them; for
+example:
+.Sp
+.Vb 2
+\&    sub foo ($a, @b)    {} # legal
+\&    sub foo ($a, @b, %) {} # invalid
+.Ve
+.IP "'/' must follow a numeric type in unpack" 4
+.IX Item "'/' must follow a numeric type in unpack"
+(F) You had an unpack template that contained a '/', but this did not
+follow some unpack specification producing a numeric value.
+See "pack" in perlfunc.
+.ie n .IP "%s must not be a named sequence in transliteration operator" 4
+.el .IP "\f(CW%s\fR must not be a named sequence in transliteration operator" 4
+.IX Item "%s must not be a named sequence in transliteration operator"
+(F) Transliteration (\f(CW\*(C`tr///\*(C'\fR and \f(CW\*(C`y///\*(C'\fR) transliterates individual
+characters.  But a named sequence by definition is more than an
+individual character, and hence doing this operation on it doesn't make
+sense.
+.IP """my sub"" not yet implemented" 4
+.IX Item """my sub"" not yet implemented"
+(F) Lexically scoped subroutines are not yet implemented.  Don't try
+that yet.
+.ie n .IP """my"" subroutine %s can't be in a package" 4
+.el .IP """my"" subroutine \f(CW%s\fR can't be in a package" 4
+.IX Item """my"" subroutine %s can't be in a package"
+(F) Lexically scoped subroutines aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.
+.ie n .IP """my %s"" used in sort comparison" 4
+.el .IP """my \f(CW%s\fR"" used in sort comparison" 4
+.IX Item """my %s"" used in sort comparison"
+(W syntax) The package variables \f(CW$a\fR and \f(CW$b\fR are used for sort comparisons.
+You used \f(CW$a\fR or \f(CW$b\fR in as an operand to the \f(CW\*(C`<=>\*(C'\fR or \f(CW\*(C`cmp\*(C'\fR operator inside a
+sort comparison block, and the variable had earlier been declared as a
+lexical variable.  Either qualify the sort variable with the package
+name, or rename the lexical variable.
+.ie n .IP """my"" variable %s can't be in a package" 4
+.el .IP """my"" variable \f(CW%s\fR can't be in a package" 4
+.IX Item """my"" variable %s can't be in a package"
+(F) Lexically scoped variables aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.  Use
+\&\fBlocal()\fR if you want to localize a package variable.
+.IP "Name ""%s::%s"" used only once: possible typo" 4
+.IX Item "Name ""%s::%s"" used only once: possible typo"
+(W once) Typographical errors often show up as unique variable
+names.  If you had a good reason for having a unique name, then
+just mention it again somehow to suppress the message.  The \f(CW\*(C`our\*(C'\fR
+declaration is also provided for this purpose.
+.Sp
+NOTE: This warning detects package symbols that have been used
+only once.  This means lexical variables will never trigger this
+warning.  It also means that all of the package variables \f(CW$c\fR, \f(CW@c\fR,
+\&\f(CW%c\fR, as well as *c, &c, sub c{}, c(), and c (the filehandle or
+format) are considered the same; if a program uses \f(CW$c\fR only once
+but also uses any of the others it will not trigger this warning.
+Symbols beginning with an underscore and symbols using special
+identifiers (q.v. perldata) are exempt from this warning.
+.IP "Need exactly 3 octal digits in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Need exactly 3 octal digits in regex; marked by <--\ HERE in m/%s/"
+(F) Within \f(CW\*(C`(?[\ \ \ ])\*(C'\fR, all constants interpreted as octal need to be
+exactly 3 digits long.  This helps catch some ambiguities.  If your
+constant is too short, add leading zeros, like
+.Sp
+.Vb 3
+\& (?[ [ \e078 ] ])     # Syntax error!
+\& (?[ [ \e0078 ] ])    # Works
+\& (?[ [ \e007 8 ] ])   # Clearer
+.Ve
+.Sp
+The maximum number this construct can express is \f(CW\*(C`\e777\*(C'\fR.  If you
+need a larger one, you need to use \eo{} instead.  If you meant
+two separate things, you need to separate them:
+.Sp
+.Vb 4
+\& (?[ [ \e7776 ] ])        # Syntax error!
+\& (?[ [ \eo{7776} ] ])     # One meaning
+\& (?[ [ \e777 6 ] ])       # Another meaning
+\& (?[ [ \e777 \e006 ] ])    # Still another
+.Ve
+.IP "Negative '/' count in unpack" 4
+.IX Item "Negative '/' count in unpack"
+(F) The length count obtained from a length/code unpack operation was
+negative.  See "pack" in perlfunc.
+.IP "Negative length" 4
+.IX Item "Negative length"
+(F) You tried to do a read/write/send/recv operation with a buffer
+length that is less than 0.  This is difficult to imagine.
+.IP "Negative offset to vec in lvalue context" 4
+.IX Item "Negative offset to vec in lvalue context"
+(F) When \f(CW\*(C`vec\*(C'\fR is called in an lvalue context, the second argument must be
+greater than or equal to zero.
+.IP "Negative repeat count does nothing" 4
+.IX Item "Negative repeat count does nothing"
+(W numeric) You tried to execute the
+\&\f(CW\*(C`x\*(C'\fR repetition operator fewer than 0
+times, which doesn't make sense.
+.IP "Nested quantifiers in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Nested quantifiers in regex; marked by <--\ HERE in m/%s/"
+(F) You can't quantify a quantifier without intervening parentheses.
+So things like ** or +* or ?* are illegal.  The <\-\-\ HERE shows
+whereabouts in the regular expression the problem was discovered.
+.Sp
+Note that the minimal matching quantifiers, \f(CW\*(C`*?\*(C'\fR, \f(CW\*(C`+?\*(C'\fR, and
+\&\f(CW\*(C`??\*(C'\fR appear to be nested quantifiers, but aren't.  See perlre.
+.ie n .IP "%s never introduced" 4
+.el .IP "\f(CW%s\fR never introduced" 4
+.IX Item "%s never introduced"
+(S internal) The symbol in question was declared but somehow went out of
+scope before it could possibly have been used.
+.IP "next::method/next::can/maybe::next::method cannot find enclosing method" 4
+.IX Item "next::method/next::can/maybe::next::method cannot find enclosing method"
+(F) \f(CW\*(C`next::method\*(C'\fR needs to be called within the context of a
+real method in a real package, and it could not find such a context.
+See mro.
+.IP "\eN in a character class must be a named character: \eN{...} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "N in a character class must be a named character: N{...} in regex; marked by <--\ HERE in m/%s/"
+(F) The new (as of Perl 5.12) meaning of \f(CW\*(C`\eN\*(C'\fR as \f(CW\*(C`[^\en]\*(C'\fR is not valid in a
+bracketed character class, for the same reason that \f(CW\*(C`.\*(C'\fR in a character
+class loses its specialness: it matches almost everything, which is
+probably not what you want.
+.IP "\eN{} here is restricted to one character in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "N{} here is restricted to one character in regex; marked by <-- HERE in m/%s/"
+(F) Named Unicode character escapes (\f(CW\*(C`\eN{...}\*(C'\fR) may return a
+multi-character sequence.  Even though a character class is
+supposed to match just one character of input, perl will match the
+whole thing correctly, except under certain conditions.  These currently
+are
+.RS 4
+.ie n .IP "When the class is inverted (""[^...]"")" 4
+.el .IP "When the class is inverted (\f(CW[^...]\fR)" 4
+.IX Item "When the class is inverted ([^...])"
+The mathematically logical behavior for what matches when inverting
+is very different from what people expect, so we have decided to
+forbid it.
+.IP "The escape is the beginning or final end point of a range" 4
+.IX Item "The escape is the beginning or final end point of a range"
+Similarly unclear is what should be generated when the
+\&\f(CW\*(C`\eN{...}\*(C'\fR is used as one of the end points of the range, such as in
+.Sp
+.Vb 1
+\& [\ex{41}\-\eN{ARABIC SEQUENCE YEH WITH HAMZA ABOVE WITH AE}]
+.Ve
+.Sp
+What is meant here is unclear, as the \f(CW\*(C`\eN{...}\*(C'\fR escape is a sequence
+of code points, so this is made an error.
+.IP "In a regex set" 4
+.IX Item "In a regex set"
+The syntax \f(CW\*(C`(?[\ \ \ ])\*(C'\fR in a regular expression yields a list of
+single code points, none can be a sequence.
+.RE
+.RS 4
+.RE
+.ie n .IP "No %s allowed while running setuid" 4
+.el .IP "No \f(CW%s\fR allowed while running setuid" 4
+.IX Item "No %s allowed while running setuid"
+(F) Certain operations are deemed to be too insecure for a setuid or
+setgid script to even be allowed to attempt.  Generally speaking there
+will be another way to do what you want that is, if not secure, at least
+securable.  See perlsec.
+.IP "No code specified for \-%c" 4
+.IX Item "No code specified for -%c"
+(F) Perl's \fB\-e\fR and \fB\-E\fR command-line options require an argument.  If
+you want to run an empty program, pass the empty string as a separate
+argument or run a program consisting of a single 0 or 1:
+.Sp
+.Vb 3
+\&    perl \-e ""
+\&    perl \-e0
+\&    perl \-e1
+.Ve
+.ie n .IP "No comma allowed after %s" 4
+.el .IP "No comma allowed after \f(CW%s\fR" 4
+.IX Item "No comma allowed after %s"
+(F) A list operator that has a filehandle or "indirect object" is
+not allowed to have a comma between that and the following arguments.
+Otherwise it'd be just another one of the arguments.
+.Sp
+One possible cause for this is that you expected to have imported
+a constant to your name space with \fBuse\fR or \fBimport\fR while no such
+importing took place, it may for example be that your operating
+system does not support that particular constant.  Hopefully you did
+use an explicit import list for the constants you expect to see;
+please see "use" in perlfunc and "import" in perlfunc.  While an
+explicit import list would probably have caught this error earlier
+it naturally does not remedy the fact that your operating system
+still does not support that constant.  Maybe you have a typo in
+the constants of the symbol import list of \fBuse\fR or \fBimport\fR or in the
+constant name at the line where this error was triggered?
+.IP "No command into which to pipe on command line" 4
+.IX Item "No command into which to pipe on command line"
+(F) An error peculiar to VMS.  Perl handles its own command line
+redirection, and found a '|' at the end of the command line, so it
+doesn't know where you want to pipe the output from this command.
+.IP "No DB::DB routine defined" 4
+.IX Item "No DB::DB routine defined"
+(F) The currently executing code was compiled with the \fB\-d\fR switch, but
+for some reason the current debugger (e.g. \fIperl5db.pl\fR or a \f(CW\*(C`Devel::\*(C'\fR
+module) didn't define a routine to be called at the beginning of each
+statement.
+.IP "No dbm on this machine" 4
+.IX Item "No dbm on this machine"
+(P) This is counted as an internal error, because every machine should
+supply dbm nowadays, because Perl comes with SDBM.  See SDBM_File.
+.IP "No DB::sub routine defined" 4
+.IX Item "No DB::sub routine defined"
+(F) The currently executing code was compiled with the \fB\-d\fR switch, but
+for some reason the current debugger (e.g. \fIperl5db.pl\fR or a \f(CW\*(C`Devel::\*(C'\fR
+module) didn't define a \f(CW\*(C`DB::sub\*(C'\fR routine to be called at the beginning
+of each ordinary subroutine call.
+.ie n .IP "No digits found for %s literal" 4
+.el .IP "No digits found for \f(CW%s\fR literal" 4
+.IX Item "No digits found for %s literal"
+(F) No hexadecimal digits were found following \f(CW\*(C`0x\*(C'\fR or no binary digits
+were found following \f(CW\*(C`0b\*(C'\fR.
+.IP "No directory specified for \-I" 4
+.IX Item "No directory specified for -I"
+(F) The \fB\-I\fR command-line switch requires a directory name as part of the
+\&\fIsame\fR argument.  Use \fB\-Ilib\fR, for instance.  \fB\-I lib\fR won't work.
+.IP "No error file after 2> or 2>> on command line" 4
+.IX Item "No error file after 2> or 2>> on command line"
+(F) An error peculiar to VMS.  Perl handles its own command line
+redirection, and found a '2>' or a '2>>' on the command line, but can't
+find the name of the file to which to write data destined for stderr.
+.IP "No group ending character '%c' found in template" 4
+.IX Item "No group ending character '%c' found in template"
+(F) A pack or unpack template has an opening '(' or '[' without its
+matching counterpart.  See "pack" in perlfunc.
+.IP "No input file after < on command line" 4
+.IX Item "No input file after < on command line"
+(F) An error peculiar to VMS.  Perl handles its own command line
+redirection, and found a '<' on the command line, but can't find the
+name of the file from which to read data for stdin.
+.ie n .IP "No next::method '%s' found for %s" 4
+.el .IP "No next::method '%s' found for \f(CW%s\fR" 4
+.IX Item "No next::method '%s' found for %s"
+(F) \f(CW\*(C`next::method\*(C'\fR found no further instances of this method name
+in the remaining packages of the MRO of this class.  If you don't want
+it throwing an exception, use \f(CW\*(C`maybe::next::method\*(C'\fR
+or \f(CW\*(C`next::can\*(C'\fR.  See mro.
+.IP "Non-finite repeat count does nothing" 4
+.IX Item "Non-finite repeat count does nothing"
+(W numeric) You tried to execute the
+\&\f(CW\*(C`x\*(C'\fR repetition operator \f(CW\*(C`Inf\*(C'\fR (or
+\&\f(CW\*(C`\-Inf\*(C'\fR) or \f(CW\*(C`NaN\*(C'\fR times, which doesn't make sense.
+.IP "Non-hex character in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Non-hex character in regex; marked by <--\ HERE in m/%s/"
+(F) In a regular expression, there was a non-hexadecimal character where
+a hex one was expected, like
+.Sp
+.Vb 2
+\& (?[ [ \exDG ] ])
+\& (?[ [ \ex{DEKA} ] ])
+.Ve
+.IP "Non-hex character '%c' terminates \ex early.  Resolved as ""%s""" 4
+.IX Item "Non-hex character '%c' terminates x early. Resolved as ""%s"""
+(W digit) In parsing a hexadecimal numeric constant, a character was
+unexpectedly encountered that isn't hexadecimal.  The resulting value
+is as indicated.
+.Sp
+Note that, within braces, every character starting with the first
+non-hexadecimal up to the ending brace is ignored.
+.IP "Non-octal character in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Non-octal character in regex; marked by <--\ HERE in m/%s/"
+(F) In a regular expression, there was a non-octal character where
+an octal one was expected, like
+.Sp
+.Vb 1
+\& (?[ [ \eo{1278} ] ])
+.Ve
+.IP "Non-octal character '%c' terminates \eo early.  Resolved as ""%s""" 4
+.IX Item "Non-octal character '%c' terminates o early. Resolved as ""%s"""
+(W digit) In parsing an octal numeric constant, a character was
+unexpectedly encountered that isn't octal.  The resulting value
+is as indicated.
+.Sp
+When not using \f(CW\*(C`\eo{...}\*(C'\fR, you wrote something like \f(CW\*(C`\e08\*(C'\fR, or \f(CW\*(C`\e179\*(C'\fR
+in a double-quotish string.  The resolution is as indicated, with all
+but the last digit treated as a single character, specified in octal.
+The last digit is the next character in the string.  To tell Perl that
+this is indeed what you want, you can use the \f(CW\*(C`\eo{ }\*(C'\fR syntax, or use
+exactly three digits to specify the octal for the character.
+.Sp
+Note that, within braces, every character starting with the first
+non-octal up to the ending brace is ignored.
+.IP """no"" not allowed in expression" 4
+.IX Item """no"" not allowed in expression"
+(F) The "no" keyword is recognized and executed at compile time, and
+returns no useful value.  See perlmod.
+.IP "Non-string passed as bitmask" 4
+.IX Item "Non-string passed as bitmask"
+(W misc) A number has been passed as a bitmask argument to \fBselect()\fR.
+Use the \fBvec()\fR function to construct the file descriptor bitmasks for
+select.  See "select" in perlfunc.
+.IP "No output file after > on command line" 4
+.IX Item "No output file after > on command line"
+(F) An error peculiar to VMS.  Perl handles its own command line
+redirection, and found a lone '>' at the end of the command line, so it
+doesn't know where you wanted to redirect stdout.
+.IP "No output file after > or >> on command line" 4
+.IX Item "No output file after > or >> on command line"
+(F) An error peculiar to VMS.  Perl handles its own command line
+redirection, and found a '>' or a '>>' on the command line, but can't
+find the name of the file to which to write data destined for stdout.
+.ie n .IP "No package name allowed for subroutine %s in ""our""" 4
+.el .IP "No package name allowed for subroutine \f(CW%s\fR in ""our""" 4
+.IX Item "No package name allowed for subroutine %s in ""our"""
+.PD 0
+.ie n .IP "No package name allowed for variable %s in ""our""" 4
+.el .IP "No package name allowed for variable \f(CW%s\fR in ""our""" 4
+.IX Item "No package name allowed for variable %s in ""our"""
+.PD
+(F) Fully qualified subroutine and variable names are not allowed in "our"
+declarations, because that doesn't make much sense under existing rules.
+Such syntax is reserved for future extensions.
+.IP "No Perl script found in input" 4
+.IX Item "No Perl script found in input"
+(F) You called \f(CW\*(C`perl \-x\*(C'\fR, but no line was found in the file beginning
+with #! and containing the word "perl".
+.IP "No setregid available" 4
+.IX Item "No setregid available"
+(F) Configure didn't find anything resembling the \fBsetregid()\fR call for
+your system.
+.IP "No setreuid available" 4
+.IX Item "No setreuid available"
+(F) Configure didn't find anything resembling the \fBsetreuid()\fR call for
+your system.
+.ie n .IP "No such class %s" 4
+.el .IP "No such class \f(CW%s\fR" 4
+.IX Item "No such class %s"
+(F) You provided a class qualifier in a "my", "our" or "state"
+declaration, but this class doesn't exist at this point in your program.
+.ie n .IP "No such class field ""%s"" in variable %s of type %s" 4
+.el .IP "No such class field ""%s"" in variable \f(CW%s\fR of type \f(CW%s\fR" 4
+.IX Item "No such class field ""%s"" in variable %s of type %s"
+(F) You tried to access a key from a hash through the indicated typed
+variable but that key is not allowed by the package of the same type.
+The indicated package has restricted the set of allowed keys using the
+fields pragma.
+.ie n .IP "No such hook: %s" 4
+.el .IP "No such hook: \f(CW%s\fR" 4
+.IX Item "No such hook: %s"
+(F) You specified a signal hook that was not recognized by Perl.
+Currently, Perl accepts \f(CW\*(C`_\|_DIE_\|_\*(C'\fR and \f(CW\*(C`_\|_WARN_\|_\*(C'\fR as valid signal hooks.
+.IP "No such pipe open" 4
+.IX Item "No such pipe open"
+(P) An error peculiar to VMS.  The internal routine \fBmy_pclose()\fR tried to
+close a pipe which hadn't been opened.  This should have been caught
+earlier as an attempt to close an unopened filehandle.
+.IP "No such signal: SIG%s" 4
+.IX Item "No such signal: SIG%s"
+(W signal) You specified a signal name as a subscript to \f(CW%SIG\fR that was
+not recognized.  Say \f(CW\*(C`kill \-l\*(C'\fR in your shell to see the valid signal
+names on your system.
+.IP "No Unicode property value wildcard matches:" 4
+.IX Item "No Unicode property value wildcard matches:"
+(W regexp) You specified a wildcard for a Unicode property value, but
+there is no property value in the current Unicode release that matches
+it.  Check your spelling.
+.IP "Not a CODE reference" 4
+.IX Item "Not a CODE reference"
+(F) Perl was trying to evaluate a reference to a code value (that is, a
+subroutine), but found a reference to something else instead.  You can
+use the \fBref()\fR function to find out what kind of ref it really was.  See
+also perlref.
+.IP "Not a GLOB reference" 4
+.IX Item "Not a GLOB reference"
+(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a
+symbol table entry that looks like \f(CW*foo\fR), but found a reference to
+something else instead.  You can use the \fBref()\fR function to find out what
+kind of ref it really was.  See perlref.
+.IP "Not a HASH reference" 4
+.IX Item "Not a HASH reference"
+(F) Perl was trying to evaluate a reference to a hash value, but found a
+reference to something else instead.  You can use the \fBref()\fR function to
+find out what kind of ref it really was.  See perlref.
+.IP "'#' not allowed immediately following a sigil in a subroutine signature" 4
+.IX Item "'#' not allowed immediately following a sigil in a subroutine signature"
+(F) In a subroutine signature definition, a comment following a sigil
+(\f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR), needs to be separated by whitespace or a comma etc., in
+particular to avoid confusion with the \f(CW$#\fR variable.  For example:
+.Sp
+.Vb 6
+\&    # bad
+\&    sub f ($# ignore first arg
+\&           , $b) {}
+\&    # good
+\&    sub f ($, # ignore first arg
+\&           $b) {}
+.Ve
+.IP "Not an ARRAY reference" 4
+.IX Item "Not an ARRAY reference"
+(F) Perl was trying to evaluate a reference to an array value, but found
+a reference to something else instead.  You can use the \fBref()\fR function
+to find out what kind of ref it really was.  See perlref.
+.IP "Not a SCALAR reference" 4
+.IX Item "Not a SCALAR reference"
+(F) Perl was trying to evaluate a reference to a scalar value, but found
+a reference to something else instead.  You can use the \fBref()\fR function
+to find out what kind of ref it really was.  See perlref.
+.IP "Not a subroutine reference" 4
+.IX Item "Not a subroutine reference"
+(F) Perl was trying to evaluate a reference to a code value (that is, a
+subroutine), but found a reference to something else instead.  You can
+use the \fBref()\fR function to find out what kind of ref it really was.  See
+also perlref.
+.IP "Not a subroutine reference in overload table" 4
+.IX Item "Not a subroutine reference in overload table"
+(F) An attempt was made to specify an entry in an overloading table that
+doesn't somehow point to a valid subroutine.  See overload.
+.ie n .IP "Not enough arguments for %s" 4
+.el .IP "Not enough arguments for \f(CW%s\fR" 4
+.IX Item "Not enough arguments for %s"
+(F) The function requires more arguments than you specified.
+.IP "Not enough format arguments" 4
+.IX Item "Not enough format arguments"
+(W syntax) A format specified more picture fields than the next line
+supplied.  See perlform.
+.ie n .IP "%s: not found" 4
+.el .IP "\f(CW%s:\fR not found" 4
+.IX Item "%s: not found"
+(A) You've accidentally run your script through the Bourne shell instead
+of Perl.  Check the #! line, or manually feed your script into Perl
+yourself.
+.IP "no UTC offset information; assuming local time is UTC" 4
+.IX Item "no UTC offset information; assuming local time is UTC"
+(S) A warning peculiar to VMS.  Perl was unable to find the local
+timezone offset, so it's assuming that local system time is equivalent
+to UTC.  If it's not, define the logical name
+\&\fISYS$TIMEZONE_DIFFERENTIAL\fR to translate to the number of seconds which
+need to be added to UTC to get local time.
+.IP "NULL OP IN RUN" 4
+.IX Item "NULL OP IN RUN"
+(S debugging) Some internal routine called \fBrun()\fR with a null opcode
+pointer.
+.IP "Null picture in formline" 4
+.IX Item "Null picture in formline"
+(F) The first argument to formline must be a valid format picture
+specification.  It was found to be empty, which probably means you
+supplied it an uninitialized value.  See perlform.
+.IP "NULL regexp parameter" 4
+.IX Item "NULL regexp parameter"
+(P) The internal pattern matching routines are out of their gourd.
+.IP "Number too long" 4
+.IX Item "Number too long"
+(F) Perl limits the representation of decimal numbers in programs to
+about 250 characters.  You've exceeded that length.  Future
+versions of Perl are likely to eliminate this arbitrary limitation.  In
+the meantime, try using scientific notation (e.g. "1e6" instead of
+"1_000_000").
+.IP "Number with no digits" 4
+.IX Item "Number with no digits"
+(F) Perl was looking for a number but found nothing that looked like
+a number.  This happens, for example with \f(CW\*(C`\eo{}\*(C'\fR, with no number between
+the braces.
+.IP "Numeric format result too large" 4
+.IX Item "Numeric format result too large"
+(F) The length of the result of a numeric format supplied to \fBsprintf()\fR
+or \fBprintf()\fR would have been too large for the underlying C function to
+report.  This limit is typically 2GB.
+.IP "Numeric variables with more than one digit may not start with '0'" 4
+.IX Item "Numeric variables with more than one digit may not start with '0'"
+(F) The only numeric variable which is allowed to start with a 0 is \f(CW$0\fR,
+and you mentioned a variable that starts with 0 that has more than one
+digit. You probably want to remove the leading 0, or if the intent was
+to express a variable name in octal you should convert to decimal.
+.IP "Octal number > 037777777777 non-portable" 4
+.IX Item "Octal number > 037777777777 non-portable"
+(W portable) The octal number you specified is larger than 2**32\-1
+(4294967295) and therefore non-portable between systems.  See
+perlport for more on portability concerns.
+.IP "Odd name/value argument for subroutine '%s'" 4
+.IX Item "Odd name/value argument for subroutine '%s'"
+(F) A subroutine using a slurpy hash parameter in its signature
+received an odd number of arguments to populate the hash.  It requires
+the arguments to be paired, with the same number of keys as values.
+The caller of the subroutine is presumably at fault.
+.Sp
+The message attempts to include the name of the called subroutine. If the
+subroutine has been aliased, the subroutine's original name will be shown,
+regardless of what name the caller used.
+.IP "Odd number of arguments for overload::constant" 4
+.IX Item "Odd number of arguments for overload::constant"
+(W overload) The call to overload::constant contained an odd number of
+arguments.  The arguments should come in pairs.
+.IP "Odd number of elements in anonymous hash" 4
+.IX Item "Odd number of elements in anonymous hash"
+(W misc) You specified an odd number of elements to initialize a hash,
+which is odd, because hashes come in key/value pairs.
+.IP "Odd number of elements in export_lexically" 4
+.IX Item "Odd number of elements in export_lexically"
+(F) A call to "export_lexically" in builtin contained an odd number of
+arguments.  This is not permitted, because each name must be paired with a
+valid reference value.
+.IP "Odd number of elements in hash assignment" 4
+.IX Item "Odd number of elements in hash assignment"
+(W misc) You specified an odd number of elements to initialize a hash,
+which is odd, because hashes come in key/value pairs.
+.IP "Odd number of elements in hash field initialization" 4
+.IX Item "Odd number of elements in hash field initialization"
+(W misc) You specified an odd number of elements to initialise a hash
+field of an object.  Hashes are initialised from a list of key/value
+pairs so there must be a corresponding value to every key.  The final
+missing value will be filled in with undef instead.
+.IP "Offset outside string" 4
+.IX Item "Offset outside string"
+(F)(W layer) You tried to do a read/write/send/recv/seek operation
+with an offset pointing outside the buffer.  This is difficult to
+imagine.  The sole exceptions to this are that zero padding will
+take place when going past the end of the string when either
+\&\f(CWsysread()\fRing a file, or when seeking past the end of a scalar opened
+for I/O (in anticipation of future reads and to imitate the behavior
+with real files).
+.IP "Old package separator ""'"" deprecated" 4
+.IX Item "Old package separator ""'"" deprecated"
+(W deprecated::apostrophe_as_package_separator, syntax) You used the old package
+separator "'" in a variable, subroutine or package name. Support for the
+old package separator will be removed in Perl 5.42.
+.IP "Old package separator used in string" 4
+.IX Item "Old package separator used in string"
+(W deprecated::apostrophe_as_package_separator, syntax) You used the old package
+separator, "'", in a variable named inside a double-quoted string; e.g.,
+\&\f(CW"In $name\*(Aqs house"\fR. This is equivalent to \f(CW"In $name::s house"\fR. If
+you meant the former, put a backslash before the apostrophe
+(\f(CW"In $name\e\*(Aqs house"\fR).
+.Sp
+Support for the old package separator will be removed in Perl 5.42.
+.IP "Only scalar fields can take a :param attribute" 4
+.IX Item "Only scalar fields can take a :param attribute"
+(F) You tried to apply the \f(CW\*(C`:param\*(C'\fR attribute to an array or hash field.
+Currently this is not permitted.
+.ie n .IP "%s() on unopened %s" 4
+.el .IP "%s() on unopened \f(CW%s\fR" 4
+.IX Item "%s() on unopened %s"
+(W unopened) An I/O operation was attempted on a filehandle that was
+never initialized.  You need to do an \fBopen()\fR, a \fBsysopen()\fR, or a \fBsocket()\fR
+call, or call a constructor from the FileHandle package.
+.ie n .IP "\-%s on unopened filehandle %s" 4
+.el .IP "\-%s on unopened filehandle \f(CW%s\fR" 4
+.IX Item "-%s on unopened filehandle %s"
+(W unopened) You tried to invoke a file test operator on a filehandle
+that isn't open.  Check your control flow.  See also "\-X" in perlfunc.
+.IP "oops: oopsAV" 4
+.IX Item "oops: oopsAV"
+(S internal) An internal warning that the grammar is screwed up.
+.IP "oops: oopsHV" 4
+.IX Item "oops: oopsHV"
+(S internal) An internal warning that the grammar is screwed up.
+.IP "Operand with no preceding operator in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Operand with no preceding operator in regex; marked by <--\ HERE in m/%s/"
+(F) You wrote something like
+.Sp
+.Vb 1
+\& (?[ \ep{Digit} \ep{Thai} ])
+.Ve
+.Sp
+There are two operands, but no operator giving how you want to combine
+them.
+.ie n .IP "Operation ""%s"": no method found, %s" 4
+.el .IP "Operation ""%s"": no method found, \f(CW%s\fR" 4
+.IX Item "Operation ""%s"": no method found, %s"
+(F) An attempt was made to perform an overloaded operation for which no
+handler was defined.  While some handlers can be autogenerated in terms
+of other handlers, there is no default handler for any operation, unless
+the \f(CW\*(C`fallback\*(C'\fR overloading key is specified to be true.  See overload.
+.IP "Operation ""%s"" returns its argument for non-Unicode code point 0x%X" 4
+.IX Item "Operation ""%s"" returns its argument for non-Unicode code point 0x%X"
+(S non_unicode) You performed an operation requiring Unicode rules
+on a code point that is not in Unicode, so what it should do is not
+defined.  Perl has chosen to have it do nothing, and warn you.
+.Sp
+If the operation shown is "ToFold", it means that case-insensitive
+matching in a regular expression was done on the code point.
+.Sp
+If you know what you are doing you can turn off this warning by
+\&\f(CW\*(C`no warnings \*(Aqnon_unicode\*(Aq;\*(C'\fR.
+.IP "Operation ""%s"" returns its argument for UTF\-16 surrogate U+%X" 4
+.IX Item "Operation ""%s"" returns its argument for UTF-16 surrogate U+%X"
+(S surrogate) You performed an operation requiring Unicode
+rules on a Unicode surrogate.  Unicode frowns upon the use
+of surrogates for anything but storing strings in UTF\-16, but
+rules are (reluctantly) defined for the surrogates, and
+they are to do nothing for this operation.  Because the use of
+surrogates can be dangerous, Perl warns.
+.Sp
+If the operation shown is "ToFold", it means that case-insensitive
+matching in a regular expression was done on the code point.
+.Sp
+If you know what you are doing you can turn off this warning by
+\&\f(CW\*(C`no warnings \*(Aqsurrogate\*(Aq;\*(C'\fR.
+.ie n .IP "Operator or semicolon missing before %s" 4
+.el .IP "Operator or semicolon missing before \f(CW%s\fR" 4
+.IX Item "Operator or semicolon missing before %s"
+(S ambiguous) You used a variable or subroutine call where the parser
+was expecting an operator.  The parser has assumed you really meant to
+use an operator, but this is highly likely to be incorrect.  For
+example, if you say "*foo *foo" it will be interpreted as if you said
+"*foo * 'foo'".
+.IP "Optional parameter lacks default expression" 4
+.IX Item "Optional parameter lacks default expression"
+(F) In a subroutine signature, you wrote something like "$a =", making a
+named optional parameter without a default value.  A nameless optional
+parameter is permitted to have no default value, but a named one must
+have a specific default.  You probably want "$a = undef".
+.ie n .IP """our"" variable %s redeclared" 4
+.el .IP """our"" variable \f(CW%s\fR redeclared" 4
+.IX Item """our"" variable %s redeclared"
+(W shadow) You seem to have already declared the same global once before
+in the current lexical scope.
+.IP "Out of memory!" 4
+.IX Item "Out of memory!"
+(X) The \fBmalloc()\fR function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request.  Perl has
+no option but to exit immediately.
+.Sp
+At least in Unix you may be able to get past this by increasing your
+process datasize limits: in csh/tcsh use \f(CW\*(C`limit\*(C'\fR and
+\&\f(CW\*(C`limit datasize n\*(C'\fR (where \f(CW\*(C`n\*(C'\fR is the number of kilobytes) to check
+the current limits and change them, and in ksh/bash/zsh use \f(CW\*(C`ulimit \-a\*(C'\fR
+and \f(CW\*(C`ulimit \-d n\*(C'\fR, respectively.
+.ie n .IP "Out of memory during %s extend" 4
+.el .IP "Out of memory during \f(CW%s\fR extend" 4
+.IX Item "Out of memory during %s extend"
+(X) An attempt was made to extend an array, a list, or a string beyond
+the largest possible memory allocation.
+.ie n .IP "Out of memory during ""large"" request for %s" 4
+.el .IP "Out of memory during ""large"" request for \f(CW%s\fR" 4
+.IX Item "Out of memory during ""large"" request for %s"
+(F) The \fBmalloc()\fR function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request.  However,
+the request was judged large enough (compile-time default is 64K), so a
+possibility to shut down by trapping this error is granted.
+.ie n .IP "Out of memory during request for %s" 4
+.el .IP "Out of memory during request for \f(CW%s\fR" 4
+.IX Item "Out of memory during request for %s"
+(X)(F) The \fBmalloc()\fR function returned 0, indicating there was
+insufficient remaining memory (or virtual memory) to satisfy the
+request.
+.Sp
+The request was judged to be small, so the possibility to trap it
+depends on the way perl was compiled.  By default it is not trappable.
+However, if compiled for this, Perl may use the contents of \f(CW$^M\fR as an
+emergency pool after \fBdie()\fRing with this message.  In this case the error
+is trappable \fIonce\fR, and the error message will include the line and file
+where the failed request happened.
+.IP "Out of memory during ridiculously large request" 4
+.IX Item "Out of memory during ridiculously large request"
+(F) You can't allocate more than 2^31+"small amount" bytes.  This error
+is most likely to be caused by a typo in the Perl program. e.g.,
+\&\f(CW$arr[time]\fR instead of \f(CW$arr[$time]\fR.
+.IP "Out of memory for yacc stack" 4
+.IX Item "Out of memory for yacc stack"
+(F) The yacc parser wanted to grow its stack so it could continue
+parsing, but \fBrealloc()\fR wouldn't give it more memory, virtual or
+otherwise.
+.IP "'.' outside of string in pack" 4
+.IX Item "'.' outside of string in pack"
+(F) The argument to a '.' in your template tried to move the working
+position to before the start of the packed string being built.
+.IP "'@' outside of string in unpack" 4
+.IX Item "'@' outside of string in unpack"
+(F) You had a template that specified an absolute position outside
+the string being unpacked.  See "pack" in perlfunc.
+.IP "'@' outside of string with malformed UTF\-8 in unpack" 4
+.IX Item "'@' outside of string with malformed UTF-8 in unpack"
+(F) You had a template that specified an absolute position outside
+the string being unpacked.  The string being unpacked was also invalid
+UTF\-8.  See "pack" in perlfunc.
+.IP "overload arg '%s' is invalid" 4
+.IX Item "overload arg '%s' is invalid"
+(W overload) The overload pragma was passed an argument it did not
+recognize.  Did you mistype an operator?
+.IP "Overloaded dereference did not return a reference" 4
+.IX Item "Overloaded dereference did not return a reference"
+(F) An object with an overloaded dereference operator was dereferenced,
+but the overloaded operation did not return a reference.  See
+overload.
+.IP "Overloaded qr did not return a REGEXP" 4
+.IX Item "Overloaded qr did not return a REGEXP"
+(F) An object with a \f(CW\*(C`qr\*(C'\fR overload was used as part of a match, but the
+overloaded operation didn't return a compiled regexp.  See overload.
+.ie n .IP "%s package attribute may clash with future reserved word: %s" 4
+.el .IP "\f(CW%s\fR package attribute may clash with future reserved word: \f(CW%s\fR" 4
+.IX Item "%s package attribute may clash with future reserved word: %s"
+(W reserved) A lowercase attribute name was used that had a
+package-specific handler.  That name might have a meaning to Perl itself
+some day, even though it doesn't yet.  Perhaps you should use a
+mixed-case attribute name, instead.  See attributes.
+.IP "pack/unpack repeat count overflow" 4
+.IX Item "pack/unpack repeat count overflow"
+(F) You can't specify a repeat count so large that it overflows your
+signed integers.  See "pack" in perlfunc.
+.IP "page overflow" 4
+.IX Item "page overflow"
+(W io) A single call to \fBwrite()\fR produced more lines than can fit on a
+page.  See perlform.
+.ie n .IP "panic: %s" 4
+.el .IP "panic: \f(CW%s\fR" 4
+.IX Item "panic: %s"
+(P) An internal error.
+.ie n .IP "panic: attempt to call %s in %s" 4
+.el .IP "panic: attempt to call \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "panic: attempt to call %s in %s"
+(P) One of the file test operators entered a code branch that calls
+an ACL related-function, but that function is not available on this
+platform.  Earlier checks mean that it should not be possible to
+enter this branch on this platform.
+.IP "panic: child pseudo-process was never scheduled" 4
+.IX Item "panic: child pseudo-process was never scheduled"
+(P) A child pseudo-process in the ithreads implementation on Windows
+was not scheduled within the time period allowed and therefore was not
+able to initialize properly.
+.IP "panic: ck_grep, type=%u" 4
+.IX Item "panic: ck_grep, type=%u"
+(P) Failed an internal consistency check trying to compile a grep.
+.ie n .IP "panic: corrupt saved stack index %ld" 4
+.el .IP "panic: corrupt saved stack index \f(CW%ld\fR" 4
+.IX Item "panic: corrupt saved stack index %ld"
+(P) The savestack was requested to restore more localized values than
+there are in the savestack.
+.IP "panic: del_backref" 4
+.IX Item "panic: del_backref"
+(P) Failed an internal consistency check while trying to reset a weak
+reference.
+.ie n .IP "panic: fold_constants JMPENV_PUSH returned %d" 4
+.el .IP "panic: fold_constants JMPENV_PUSH returned \f(CW%d\fR" 4
+.IX Item "panic: fold_constants JMPENV_PUSH returned %d"
+(P) While attempting folding constants an exception other than an \f(CW\*(C`eval\*(C'\fR
+failure was caught.
+.ie n .IP "panic: frexp: %f" 4
+.el .IP "panic: frexp: \f(CW%f\fR" 4
+.IX Item "panic: frexp: %f"
+(P) The library function \fBfrexp()\fR failed, making printf("%f") impossible.
+.IP "panic: goto, type=%u, ix=%ld" 4
+.IX Item "panic: goto, type=%u, ix=%ld"
+(P) We popped the context stack to a context with the specified label,
+and then discovered it wasn't a context we know how to do a goto in.
+.IP "panic: gp_free failed to free glob pointer" 4
+.IX Item "panic: gp_free failed to free glob pointer"
+(P) The internal routine used to clear a typeglob's entries tried
+repeatedly, but each time something re-created entries in the glob.
+Most likely the glob contains an object with a reference back to
+the glob and a destructor that adds a new object to the glob.
+.ie n .IP "panic: INTERPCASEMOD, %s" 4
+.el .IP "panic: INTERPCASEMOD, \f(CW%s\fR" 4
+.IX Item "panic: INTERPCASEMOD, %s"
+(P) The lexer got into a bad state at a case modifier.
+.ie n .IP "panic: INTERPCONCAT, %s" 4
+.el .IP "panic: INTERPCONCAT, \f(CW%s\fR" 4
+.IX Item "panic: INTERPCONCAT, %s"
+(P) The lexer got into a bad state parsing a string with brackets.
+.IP "panic: kid popen errno read" 4
+.IX Item "panic: kid popen errno read"
+(F) A forked child returned an incomprehensible message about its errno.
+.ie n .IP "panic: leave_scope inconsistency %u" 4
+.el .IP "panic: leave_scope inconsistency \f(CW%u\fR" 4
+.IX Item "panic: leave_scope inconsistency %u"
+(P) The savestack probably got out of sync.  At least, there was an
+invalid enum on the top of it.
+.IP "panic: magic_killbackrefs" 4
+.IX Item "panic: magic_killbackrefs"
+(P) Failed an internal consistency check while trying to reset all weak
+references to an object.
+.ie n .IP "panic: malloc, %s" 4
+.el .IP "panic: malloc, \f(CW%s\fR" 4
+.IX Item "panic: malloc, %s"
+(P) Something requested a negative number of bytes of malloc.
+.IP "panic: memory wrap" 4
+.IX Item "panic: memory wrap"
+(P) Something tried to allocate either more memory than possible or a
+negative amount.
+.ie n .IP "panic: newFORLOOP, %s" 4
+.el .IP "panic: newFORLOOP, \f(CW%s\fR" 4
+.IX Item "panic: newFORLOOP, %s"
+(P) The parser failed an internal consistency check while trying to parse
+a \f(CW\*(C`foreach\*(C'\fR loop.
+.ie n .IP "panic: pad_alloc, %p!=%p" 4
+.el .IP "panic: pad_alloc, \f(CW%p\fR!=%p" 4
+.IX Item "panic: pad_alloc, %p!=%p"
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+.ie n .IP "panic: pad_free curpad, %p!=%p" 4
+.el .IP "panic: pad_free curpad, \f(CW%p\fR!=%p" 4
+.IX Item "panic: pad_free curpad, %p!=%p"
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+.IP "panic: pad_free po" 4
+.IX Item "panic: pad_free po"
+(P) A zero scratch pad offset was detected internally.  An attempt was
+made to free a target that had not been allocated to begin with.
+.ie n .IP "panic: pad_reset curpad, %p!=%p" 4
+.el .IP "panic: pad_reset curpad, \f(CW%p\fR!=%p" 4
+.IX Item "panic: pad_reset curpad, %p!=%p"
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+.IP "panic: pad_sv po" 4
+.IX Item "panic: pad_sv po"
+(P) A zero scratch pad offset was detected internally.  Most likely
+an operator needed a target but that target had not been allocated
+for whatever reason.
+.ie n .IP "panic: pad_swipe curpad, %p!=%p" 4
+.el .IP "panic: pad_swipe curpad, \f(CW%p\fR!=%p" 4
+.IX Item "panic: pad_swipe curpad, %p!=%p"
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+.IP "panic: pad_swipe po" 4
+.IX Item "panic: pad_swipe po"
+(P) An invalid scratch pad offset was detected internally.
+.IP "panic: pp_iter, type=%u" 4
+.IX Item "panic: pp_iter, type=%u"
+(P) The foreach iterator got called in a non-loop context frame.
+.IP "panic: pp_match%s" 4
+.IX Item "panic: pp_match%s"
+(P) The internal \fBpp_match()\fR routine was called with invalid operational
+data.
+.ie n .IP "panic: realloc, %s" 4
+.el .IP "panic: realloc, \f(CW%s\fR" 4
+.IX Item "panic: realloc, %s"
+(P) Something requested a negative number of bytes of realloc.
+.IP "panic: reference miscount on nsv in \fBsv_replace()\fR (%d != 1)" 4
+.IX Item "panic: reference miscount on nsv in sv_replace() (%d != 1)"
+(P) The internal \fBsv_replace()\fR function was handed a new SV with a
+reference count other than 1.
+.ie n .IP "panic: restartop in %s" 4
+.el .IP "panic: restartop in \f(CW%s\fR" 4
+.IX Item "panic: restartop in %s"
+(P) Some internal routine requested a goto (or something like it), and
+didn't supply the destination.
+.IP "panic: return, type=%u" 4
+.IX Item "panic: return, type=%u"
+(P) We popped the context stack to a subroutine or eval context, and
+then discovered it wasn't a subroutine or eval context.
+.ie n .IP "panic: scan_num, %s" 4
+.el .IP "panic: scan_num, \f(CW%s\fR" 4
+.IX Item "panic: scan_num, %s"
+(P) \fBscan_num()\fR got called on something that wasn't a number.
+.IP "panic: Sequence (?{...}): no code block found in regex m/%s/" 4
+.IX Item "panic: Sequence (?{...}): no code block found in regex m/%s/"
+(P) While compiling a pattern that has embedded (?{}) or (??{}) code
+blocks, perl couldn't locate the code block that should have already been
+seen and compiled by perl before control passed to the regex compiler.
+.ie n .IP "panic: sv_chop %s" 4
+.el .IP "panic: sv_chop \f(CW%s\fR" 4
+.IX Item "panic: sv_chop %s"
+(P) The \fBsv_chop()\fR routine was passed a position that is not within the
+scalar's string buffer.
+.IP "panic: sv_insert, midend=%p, bigend=%p" 4
+.IX Item "panic: sv_insert, midend=%p, bigend=%p"
+(P) The \fBsv_insert()\fR routine was told to remove more string than there
+was string.
+.IP "panic: top_env" 4
+.IX Item "panic: top_env"
+(P) The compiler attempted to do a goto, or something weird like that.
+.ie n .IP "panic: unexpected constant lvalue entersub entry via type/targ %d:%d" 4
+.el .IP "panic: unexpected constant lvalue entersub entry via type/targ \f(CW%d:\fR%d" 4
+.IX Item "panic: unexpected constant lvalue entersub entry via type/targ %d:%d"
+(P) When compiling a subroutine call in lvalue context, Perl failed an
+internal consistency check.  It encountered a malformed op tree.
+.ie n .IP "panic: unimplemented op %s (#%d) called" 4
+.el .IP "panic: unimplemented op \f(CW%s\fR (#%d) called" 4
+.IX Item "panic: unimplemented op %s (#%d) called"
+(P) The compiler is screwed up and attempted to use an op that isn't
+permitted at run time.
+.ie n .IP "panic: unknown OA_*: %x" 4
+.el .IP "panic: unknown OA_*: \f(CW%x\fR" 4
+.IX Item "panic: unknown OA_*: %x"
+(P) The internal routine that handles arguments to \f(CW&CORE::foo()\fR
+subroutine calls was unable to determine what type of arguments
+were expected.
+.IP "panic: utf16_to_utf8: odd bytelen" 4
+.IX Item "panic: utf16_to_utf8: odd bytelen"
+(P) Something tried to call utf16_to_utf8 with an odd (as opposed
+to even) byte length.
+.IP "panic: utf16_to_utf8_reversed: odd bytelen" 4
+.IX Item "panic: utf16_to_utf8_reversed: odd bytelen"
+(P) Something tried to call utf16_to_utf8_reversed with an odd (as opposed
+to even) byte length.
+.ie n .IP "panic: yylex, %s" 4
+.el .IP "panic: yylex, \f(CW%s\fR" 4
+.IX Item "panic: yylex, %s"
+(P) The lexer got into a bad state while processing a case modifier.
+.IP "Parentheses missing around ""%s"" list" 4
+.IX Item "Parentheses missing around ""%s"" list"
+(W parenthesis) You said something like
+.Sp
+.Vb 1
+\&    my $foo, $bar = @_;
+.Ve
+.Sp
+when you meant
+.Sp
+.Vb 1
+\&    my ($foo, $bar) = @_;
+.Ve
+.Sp
+Remember that "my", "our", "local" and "state" bind tighter than comma.
+.IP "Parsing code internal error (%s)" 4
+.IX Item "Parsing code internal error (%s)"
+(F) Parsing code supplied by an extension violated the parser's API in
+a detectable way.
+.IP "Pattern subroutine nesting without pos change exceeded limit in regex" 4
+.IX Item "Pattern subroutine nesting without pos change exceeded limit in regex"
+(F) You used a pattern that uses too many nested subpattern calls without
+consuming any text.  Restructure the pattern so text is consumed before
+the nesting limit is exceeded.
+.ie n .IP """\-p"" destination: %s" 4
+.el .IP "\f(CW\-p\fR destination: \f(CW%s\fR" 4
+.IX Item "-p destination: %s"
+(F) An error occurred during the implicit output invoked by the \f(CW\*(C`\-p\*(C'\fR
+command-line switch.  (This output goes to STDOUT unless you've
+redirected it with \fBselect()\fR.)
+.ie n .IP "Perl API version %s of %s does not match %s" 4
+.el .IP "Perl API version \f(CW%s\fR of \f(CW%s\fR does not match \f(CW%s\fR" 4
+.IX Item "Perl API version %s of %s does not match %s"
+(F) The XS module in question was compiled against a different incompatible
+version of Perl than the one that has loaded the XS module.
+.IP "Perl folding rules are not up-to-date for 0x%X; please use the perlbug utility to report; in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Perl folding rules are not up-to-date for 0x%X; please use the perlbug utility to report; in regex; marked by <--\ HERE in m/%s/"
+(S regexp) You used a regular expression with case-insensitive matching,
+and there is a bug in Perl in which the built-in regular expression
+folding rules are not accurate.  This may lead to incorrect results.
+Please report this as a bug to <https://github.com/Perl/perl5/issues/new/choose>.
+.IP "Perl_my_%s() not available" 4
+.IX Item "Perl_my_%s() not available"
+(F) Your platform has very uncommon byte-order and integer size,
+so it was not possible to set up some or all fixed-width byte-order
+conversion functions.  This is only a problem when you're using the
+\&'<' or '>' modifiers in (un)pack templates.  See "pack" in perlfunc.
+.ie n .IP "Perl %s required (did you mean %s?)\-\-this is only %s, stopped" 4
+.el .IP "Perl \f(CW%s\fR required (did you mean \f(CW%s\fR?)\-\-this is only \f(CW%s\fR, stopped" 4
+.IX Item "Perl %s required (did you mean %s?)--this is only %s, stopped"
+(F) The code you are trying to run has asked for a newer version of
+Perl than you are running.  Perhaps \f(CW\*(C`use 5.10\*(C'\fR was written instead
+of \f(CW\*(C`use 5.010\*(C'\fR or \f(CW\*(C`use v5.10\*(C'\fR.  Without the leading \f(CW\*(C`v\*(C'\fR, the number is
+interpreted as a decimal, with every three digits after the
+decimal point representing a part of the version number.  So 5.10
+is equivalent to v5.100.
+.ie n .IP "Perl %s required\-\-this is only %s, stopped" 4
+.el .IP "Perl \f(CW%s\fR required\-\-this is only \f(CW%s\fR, stopped" 4
+.IX Item "Perl %s required--this is only %s, stopped"
+(F) The module in question uses features of a version of Perl more
+recent than the currently running version.  How long has it been since
+you upgraded, anyway?  See "require" in perlfunc.
+.IP "PERL_SH_DIR too long" 4
+.IX Item "PERL_SH_DIR too long"
+(F) An error peculiar to OS/2.  PERL_SH_DIR is the directory to find the
+\&\f(CW\*(C`sh\*(C'\fR\-shell in.  See "PERL_SH_DIR" in perlos2.
+.IP "PERL_SIGNALS illegal: ""%s""" 4
+.IX Item "PERL_SIGNALS illegal: ""%s"""
+(X) See "PERL_SIGNALS" in perlrun for legal values.
+.ie n .IP "Perls since %s too modern\-\-this is %s, stopped" 4
+.el .IP "Perls since \f(CW%s\fR too modern\-\-this is \f(CW%s\fR, stopped" 4
+.IX Item "Perls since %s too modern--this is %s, stopped"
+(F) The code you are trying to run claims it will not run
+on the version of Perl you are using because it is too new.
+Maybe the code needs to be updated, or maybe it is simply
+wrong and the version check should just be removed.
+.IP "perl: warning: Non hex character in '$ENV{PERL_HASH_SEED}', seed only partially set" 4
+.IX Item "perl: warning: Non hex character in '$ENV{PERL_HASH_SEED}', seed only partially set"
+(S) PERL_HASH_SEED should match /^\es*(?:0x)?[0\-9a\-fA\-F]+\es*\ez/ but it
+contained a non hex character.  This could mean you are not using the
+hash seed you think you are.
+.IP "perl: warning: Setting locale failed." 4
+.IX Item "perl: warning: Setting locale failed."
+(S) The whole warning message will look something like:
+.Sp
+.Vb 6
+\&        perl: warning: Setting locale failed.
+\&        perl: warning: Please check that your locale settings:
+\&                LC_ALL = "En_US",
+\&                LANG = (unset)
+\&            are supported and installed on your system.
+\&        perl: warning: Falling back to the standard locale ("C").
+.Ve
+.Sp
+Exactly what were the failed locale settings varies.  In the above the
+settings were that the LC_ALL was "En_US" and the LANG had no value.
+This error means that Perl detected that you and/or your operating
+system supplier and/or system administrator have set up the so-called
+locale system but Perl could not use those settings.  This was not
+dead serious, fortunately: there is a "default locale" called "C" that
+Perl can and will use, and the script will be run.  Before you really
+fix the problem, however, you will get the same error message each
+time you run Perl.  How to really fix the problem can be found in
+perllocale section \fBLOCALE PROBLEMS\fR.
+.IP "perl: warning: strange setting in '$ENV{PERL_PERTURB_KEYS}': '%s'" 4
+.IX Item "perl: warning: strange setting in '$ENV{PERL_PERTURB_KEYS}': '%s'"
+(S) Perl was run with the environment variable PERL_PERTURB_KEYS defined
+but containing an unexpected value.  The legal values of this setting
+are as follows.
+.Sp
+.Vb 6
+\&  Numeric | String        | Result
+\&  \-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  0       | NO            | Disables key traversal randomization
+\&  1       | RANDOM        | Enables full key traversal randomization
+\&  2       | DETERMINISTIC | Enables repeatable key traversal
+\&          |               | randomization
+.Ve
+.Sp
+Both numeric and string values are accepted, but note that string values are
+case sensitive.  The default for this setting is "RANDOM" or 1.
+.ie n .IP "pid %x not a child" 4
+.el .IP "pid \f(CW%x\fR not a child" 4
+.IX Item "pid %x not a child"
+(W exec) A warning peculiar to VMS.  \fBWaitpid()\fR was asked to wait for a
+process which isn't a subprocess of the current process.  While this is
+fine from VMS' perspective, it's probably not what you intended.
+.IP "'P' must have an explicit size in unpack" 4
+.IX Item "'P' must have an explicit size in unpack"
+(F) The unpack format P must have an explicit size, not "*".
+.IP "POSIX class [:%s:] unknown in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "POSIX class [:%s:] unknown in regex; marked by <--\ HERE in m/%s/"
+(F) The class in the character class [: :] syntax is unknown.  The <\-\-\ HERE
+shows whereabouts in the regular expression the problem was discovered.
+Note that the POSIX character classes do \fBnot\fR have the \f(CW\*(C`is\*(C'\fR prefix
+the corresponding C interfaces have: in other words, it's \f(CW\*(C`[[:print:]]\*(C'\fR,
+not \f(CW\*(C`isprint\*(C'\fR.  See perlre.
+.IP "POSIX getpgrp can't take an argument" 4
+.IX Item "POSIX getpgrp can't take an argument"
+(F) Your system has POSIX \fBgetpgrp()\fR, which takes no argument, unlike
+the BSD version, which takes a pid.
+.ie n .IP "POSIX syntax [%c %c] belongs inside character classes%s in regex; marked by <\-\-\ HERE in m/%s/" 4
+.el .IP "POSIX syntax [%c \f(CW%c\fR] belongs inside character classes%s in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "POSIX syntax [%c %c] belongs inside character classes%s in regex; marked by <--\ HERE in m/%s/"
+(W regexp) Perl thinks that you intended to write a POSIX character
+class, but didn't use enough brackets.  These POSIX class constructs [:
+:], [= =], and [. .]  go \fIinside\fR character classes, the [] are part of
+the construct, for example: \f(CW\*(C`qr/[012[:alpha:]345]/\*(C'\fR.  What the regular
+expression pattern compiled to is probably not what you were intending.
+For example, \f(CW\*(C`qr/[:alpha:]/\*(C'\fR compiles to a regular bracketed character
+class consisting of the four characters \f(CW":"\fR,  \f(CW"a"\fR,  \f(CW"l"\fR,
+\&\f(CW"h"\fR, and \f(CW"p"\fR.  To specify the POSIX class, it should have been
+written \f(CW\*(C`qr/[[:alpha:]]/\*(C'\fR.
+.Sp
+Note that [= =] and [. .] are not currently
+implemented; they are simply placeholders for future extensions and
+will cause fatal errors.  The <\-\-\ HERE shows whereabouts in the regular
+expression the problem was discovered.  See perlre.
+.Sp
+If the specification of the class was not completely valid, the message
+indicates that.
+.IP "POSIX syntax [. .] is reserved for future extensions in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "POSIX syntax [. .] is reserved for future extensions in regex; marked by <--\ HERE in m/%s/"
+(F) Within regular expression character classes ([]) the syntax beginning
+with "[." and ending with ".]" is reserved for future extensions.  If you
+need to represent those character sequences inside a regular expression
+character class, just quote the square brackets with the backslash: "\e[."
+and ".\e]".  The <\-\-\ HERE shows whereabouts in the regular expression the
+problem was discovered.  See perlre.
+.IP "POSIX syntax [= =] is reserved for future extensions in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "POSIX syntax [= =] is reserved for future extensions in regex; marked by <--\ HERE in m/%s/"
+(F) Within regular expression character classes ([]) the syntax beginning
+with "[=" and ending with "=]" is reserved for future extensions.  If you
+need to represent those character sequences inside a regular expression
+character class, just quote the square brackets with the backslash: "\e[="
+and "=\e]".  The <\-\-\ HERE shows whereabouts in the regular expression the
+problem was discovered.  See perlre.
+.IP "Possible attempt to put comments in \fBqw()\fR list" 4
+.IX Item "Possible attempt to put comments in qw() list"
+(W qw) \fBqw()\fR lists contain items separated by whitespace; as with literal
+strings, comment characters are not ignored, but are instead treated as
+literal data.  (You may have used different delimiters than the
+parentheses shown here; braces are also frequently used.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a # a comment
+\&        b # another comment
+\&    );
+.Ve
+.Sp
+when you should have written this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a
+\&        b
+\&    );
+.Ve
+.Sp
+If you really want comments, build your list the
+old-fashioned way, with quotes and commas:
+.Sp
+.Vb 4
+\&    @list = (
+\&        \*(Aqa\*(Aq,    # a comment
+\&        \*(Aqb\*(Aq,    # another comment
+\&    );
+.Ve
+.IP "Possible attempt to separate words with commas" 4
+.IX Item "Possible attempt to separate words with commas"
+(W qw) \fBqw()\fR lists contain items separated by whitespace; therefore
+commas aren't needed to separate the items.  (You may have used
+different delimiters than the parentheses shown here; braces are also
+frequently used.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 1
+\&    qw! a, b, c !;
+.Ve
+.Sp
+which puts literal commas into some of the list items.  Write it without
+commas if you don't want them to appear in your data:
+.Sp
+.Vb 1
+\&    qw! a b c !;
+.Ve
+.ie n .IP "Possible memory corruption: %s overflowed 3rd argument" 4
+.el .IP "Possible memory corruption: \f(CW%s\fR overflowed 3rd argument" 4
+.IX Item "Possible memory corruption: %s overflowed 3rd argument"
+(F) An \fBioctl()\fR or \fBfcntl()\fR returned more than Perl was bargaining for.
+Perl guesses a reasonable buffer size, but puts a sentinel byte at the
+end of the buffer just in case.  This sentinel byte got clobbered, and
+Perl assumes that memory is now corrupted.  See "ioctl" in perlfunc.
+.IP "Possible precedence issue with control flow operator" 4
+.IX Item "Possible precedence issue with control flow operator"
+(W syntax) There is a possible problem with the mixing of a control
+flow operator (e.g. \f(CW\*(C`return\*(C'\fR) and a low-precedence operator like
+\&\f(CW\*(C`or\*(C'\fR.  Consider:
+.Sp
+.Vb 1
+\&    sub { return $a or $b; }
+.Ve
+.Sp
+This is parsed as:
+.Sp
+.Vb 1
+\&    sub { (return $a) or $b; }
+.Ve
+.Sp
+Which is effectively just:
+.Sp
+.Vb 1
+\&    sub { return $a; }
+.Ve
+.Sp
+Either use parentheses or the high-precedence variant of the operator.
+.Sp
+Note this may be also triggered for constructs like:
+.Sp
+.Vb 1
+\&    sub { 1 if die; }
+.Ve
+.ie n .IP "Possible precedence problem on bitwise %s operator" 4
+.el .IP "Possible precedence problem on bitwise \f(CW%s\fR operator" 4
+.IX Item "Possible precedence problem on bitwise %s operator"
+(W precedence) Your program uses a bitwise logical operator in conjunction
+with a numeric comparison operator, like this :
+.Sp
+.Vb 1
+\&    if ($x & $y == 0) { ... }
+.Ve
+.Sp
+This expression is actually equivalent to \f(CW\*(C`$x & ($y == 0)\*(C'\fR, due to the
+higher precedence of \f(CW\*(C`==\*(C'\fR.  This is probably not what you want.  (If you
+really meant to write this, disable the warning, or, better, put the
+parentheses explicitly and write \f(CW\*(C`$x & ($y == 0)\*(C'\fR).
+.IP "Possible unintended interpolation of $\e in regex" 4
+.IX Item "Possible unintended interpolation of $ in regex"
+(W ambiguous) You said something like \f(CW\*(C`m/$\e/\*(C'\fR in a regex.
+The regex \f(CW\*(C`m/foo$\es+bar/m\*(C'\fR translates to: match the word 'foo', the output
+record separator (see "$\e" in perlvar) and the letter 's' (one time or more)
+followed by the word 'bar'.
+.Sp
+If this is what you intended then you can silence the warning by using 
+\&\f(CW\*(C`m/${\e}/\*(C'\fR (for example: \f(CW\*(C`m/foo${\e}s+bar/\*(C'\fR).
+.Sp
+If instead you intended to match the word 'foo' at the end of the line
+followed by whitespace and the word 'bar' on the next line then you can use
+\&\f(CW\*(C`m/$(?)\e/\*(C'\fR (for example: \f(CW\*(C`m/foo$(?)\es+bar/\*(C'\fR).
+.ie n .IP "Possible unintended interpolation of %s in string" 4
+.el .IP "Possible unintended interpolation of \f(CW%s\fR in string" 4
+.IX Item "Possible unintended interpolation of %s in string"
+(W ambiguous) You said something like '@foo' in a double-quoted string
+but there was no array \f(CW@foo\fR in scope at the time.  If you wanted a
+literal \f(CW@foo\fR, then write it as \e@foo; otherwise find out what happened
+to the array you apparently lost track of.
+.ie n .IP "Precedence problem: open %s should be open(%s)" 4
+.el .IP "Precedence problem: open \f(CW%s\fR should be open(%s)" 4
+.IX Item "Precedence problem: open %s should be open(%s)"
+(S precedence) The old irregular construct
+.Sp
+.Vb 1
+\&    open FOO || die;
+.Ve
+.Sp
+is now misinterpreted as
+.Sp
+.Vb 1
+\&    open(FOO || die);
+.Ve
+.Sp
+because of the strict regularization of Perl 5's grammar into unary and
+list operators.  (The old open was a little of both.)  You must put
+parentheses around the filehandle, or use the new "or" operator instead
+of "||".
+.IP "Premature end of script headers" 4
+.IX Item "Premature end of script headers"
+See "500 Server error".
+.ie n .IP "\fBprintf()\fR on closed filehandle %s" 4
+.el .IP "\fBprintf()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "printf() on closed filehandle %s"
+(W closed) The filehandle you're writing to got itself closed sometime
+before now.  Check your control flow.
+.ie n .IP "\fBprint()\fR on closed filehandle %s" 4
+.el .IP "\fBprint()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "print() on closed filehandle %s"
+(W closed) The filehandle you're printing on got itself closed sometime
+before now.  Check your control flow.
+.IP "Process terminated by SIG%s" 4
+.IX Item "Process terminated by SIG%s"
+(W) This is a standard message issued by OS/2 applications, while *nix
+applications die in silence.  It is considered a feature of the OS/2
+port.  One can easily disable this by appropriate sighandlers, see
+"Signals" in perlipc.  See also "Process terminated by SIGTERM/SIGINT"
+in perlos2.
+.ie n .IP "Prototype after '%c' for %s : %s" 4
+.el .IP "Prototype after '%c' for \f(CW%s\fR : \f(CW%s\fR" 4
+.IX Item "Prototype after '%c' for %s : %s"
+(W illegalproto) A character follows % or @ in a prototype.  This is
+useless, since % and @ gobble the rest of the subroutine arguments.
+.ie n .IP "Prototype mismatch: %s vs %s" 4
+.el .IP "Prototype mismatch: \f(CW%s\fR vs \f(CW%s\fR" 4
+.IX Item "Prototype mismatch: %s vs %s"
+(S prototype) The subroutine being declared or defined had previously been
+declared or defined with a different function prototype.
+.IP "Prototype not terminated" 4
+.IX Item "Prototype not terminated"
+(F) You've omitted the closing parenthesis in a function prototype
+definition.
+.ie n .IP "Prototype '%s' overridden by attribute 'prototype(%s)' in %s" 4
+.el .IP "Prototype '%s' overridden by attribute 'prototype(%s)' in \f(CW%s\fR" 4
+.IX Item "Prototype '%s' overridden by attribute 'prototype(%s)' in %s"
+(W prototype) A prototype was declared in both the parentheses after
+the sub name and via the prototype attribute.  The prototype in
+parentheses is useless, since it will be replaced by the prototype
+from the attribute before it's ever used.
+.ie n .IP "%s on BEGIN block ignored" 4
+.el .IP "\f(CW%s\fR on BEGIN block ignored" 4
+.IX Item "%s on BEGIN block ignored"
+(W syntax) \f(CW\*(C`BEGIN\*(C'\fR blocks are executed immediately after they are parsed
+and then thrown away. Any prototypes or attributes are therefore
+meaningless and are ignored. You should remove them from the \f(CW\*(C`BEGIN\*(C'\fR block.
+Note this also means you cannot create a constant called \f(CW\*(C`BEGIN\*(C'\fR.
+.IP "Quantifier follows nothing in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Quantifier follows nothing in regex; marked by <--\ HERE in m/%s/"
+(F) You started a regular expression with a quantifier.  Backslash it if
+you meant it literally.  The <\-\-\ HERE shows whereabouts in the regular
+expression the problem was discovered.  See perlre.
+.ie n .IP "Quantifier in {,} bigger than %d in regex; marked by <\-\-\ HERE in m/%s/" 4
+.el .IP "Quantifier in {,} bigger than \f(CW%d\fR in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Quantifier in {,} bigger than %d in regex; marked by <--\ HERE in m/%s/"
+(F) There is currently a limit to the size of the min and max values of
+the {min,max} construct.  The <\-\-\ HERE shows whereabouts in the regular
+expression the problem was discovered.  See perlre.
+.IP "Quantifier {n,m} with n > m can't match in regex" 4
+.IX Item "Quantifier {n,m} with n > m can't match in regex"
+.PD 0
+.IP "Quantifier {n,m} with n > m can't match in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Quantifier {n,m} with n > m can't match in regex; marked by <--\ HERE in m/%s/"
+.PD
+(W regexp) Minima should be less than or equal to maxima.  If you really
+want your regexp to match something 0 times, just put {0}.
+.IP "Quantifier unexpected on zero-length expression in regex m/%s/" 4
+.IX Item "Quantifier unexpected on zero-length expression in regex m/%s/"
+(W regexp) You applied a regular expression quantifier in a place where
+it makes no sense, such as on a zero-width assertion.  Try putting the
+quantifier inside the assertion instead.  For example, the way to match
+"abc" provided that it is followed by three repetitions of "xyz" is
+\&\f(CW\*(C`/abc(?=(?:xyz){3})/\*(C'\fR, not \f(CW\*(C`/abc(?=xyz){3}/\*(C'\fR.
+.IP "Range iterator outside integer range" 4
+.IX Item "Range iterator outside integer range"
+(F) One (or both) of the numeric arguments to the range operator ".."
+are outside the range which can be represented by integers internally.
+One possible workaround is to force Perl to use magical string increment
+by prepending "0" to your numbers.
+.IP "Ranges of ASCII printables should be some subset of ""0\-9"", ""A\-Z"", or ""a\-z"" in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Ranges of ASCII printables should be some subset of ""0-9"", ""A-Z"", or ""a-z"" in regex; marked by <--\ HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+Stricter rules help to find typos and other errors.  Perhaps you didn't
+even intend a range here, if the \f(CW"\-"\fR was meant to be some other
+character, or should have been escaped (like \f(CW"\e\-"\fR).  If you did
+intend a range, the one that was used is not portable between ASCII and
+EBCDIC platforms, and doesn't have an obvious meaning to a casual
+reader.
+.Sp
+.Vb 7
+\& [3\-7]    # OK; Obvious and portable
+\& [d\-g]    # OK; Obvious and portable
+\& [A\-Y]    # OK; Obvious and portable
+\& [A\-z]    # WRONG; Not portable; not clear what is meant
+\& [a\-Z]    # WRONG; Not portable; not clear what is meant
+\& [%\-.]    # WRONG; Not portable; not clear what is meant
+\& [\ex41\-Z] # WRONG; Not portable; not obvious to non\-geek
+.Ve
+.Sp
+(You can force portability by specifying a Unicode range, which means that
+the endpoints are specified by
+\&\f(CW\*(C`\eN{...}\*(C'\fR, but the meaning may
+still not be obvious.)
+The stricter rules require that ranges that start or stop with an ASCII
+character that is not a control have all their endpoints be the literal
+character, and not some escape sequence (like \f(CW"\ex41"\fR), and the ranges
+must be all digits, or all uppercase letters, or all lowercase letters.
+.IP "Ranges of digits should be from the same group in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Ranges of digits should be from the same group in regex; marked by <--\ HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR or within \f(CW\*(C`(?[...])\*(C'\fR)
+.Sp
+Stricter rules help to find typos and other errors.  You included a
+range, and at least one of the end points is a decimal digit.  Under the
+stricter rules, when this happens, both end points should be digits in
+the same group of 10 consecutive digits.
+.ie n .IP "\fBreaddir()\fR attempted on invalid dirhandle %s" 4
+.el .IP "\fBreaddir()\fR attempted on invalid dirhandle \f(CW%s\fR" 4
+.IX Item "readdir() attempted on invalid dirhandle %s"
+(W io) The dirhandle you're reading from is either closed or not really
+a dirhandle.  Check your control flow.
+.ie n .IP "\fBreadline()\fR on closed filehandle %s" 4
+.el .IP "\fBreadline()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "readline() on closed filehandle %s"
+(W closed) The filehandle you're reading from got itself closed sometime
+before now.  Check your control flow.
+.ie n .IP "\fBreadline()\fR on unopened filehandle %s" 4
+.el .IP "\fBreadline()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "readline() on unopened filehandle %s"
+(W unopened) The filehandle you're reading from was never opened.  Check your
+control flow.
+.ie n .IP "\fBread()\fR on closed filehandle %s" 4
+.el .IP "\fBread()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "read() on closed filehandle %s"
+(W closed) You tried to read from a closed filehandle.
+.ie n .IP "\fBread()\fR on unopened filehandle %s" 4
+.el .IP "\fBread()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "read() on unopened filehandle %s"
+(W unopened) You tried to read from a filehandle that was never opened.
+.IP "\fBrealloc()\fR of freed memory ignored" 4
+.IX Item "realloc() of freed memory ignored"
+(S malloc) An internal routine called \fBrealloc()\fR on something that had
+already been freed.
+.IP "Recompile perl with \fB\-D\fRDEBUGGING to use \fB\-D\fR switch" 4
+.IX Item "Recompile perl with -DDEBUGGING to use -D switch"
+(S debugging) You can't use the \fB\-D\fR option unless the code to produce
+the desired output is compiled into Perl, which entails some overhead,
+which is why it's currently left out of your copy.
+.IP "Recursive call to Perl_load_module in PerlIO_find_layer" 4
+.IX Item "Recursive call to Perl_load_module in PerlIO_find_layer"
+(P) It is currently not permitted to load modules when creating
+a filehandle inside an \f(CW%INC\fR hook.  This can happen with \f(CW\*(C`open my
+$fh, \*(Aq<\*(Aq, \e$scalar\*(C'\fR, which implicitly loads PerlIO::scalar.  Try
+loading PerlIO::scalar explicitly first.
+.IP "Recursive inheritance detected in package '%s'" 4
+.IX Item "Recursive inheritance detected in package '%s'"
+(F) While calculating the method resolution order (MRO) of a package, Perl
+believes it found an infinite loop in the \f(CW@ISA\fR hierarchy.  This is a
+crude check that bails out after 100 levels of \f(CW@ISA\fR depth.
+.ie n .IP "Redundant argument in %s" 4
+.el .IP "Redundant argument in \f(CW%s\fR" 4
+.IX Item "Redundant argument in %s"
+(W redundant) You called a function with more arguments than other
+arguments you supplied indicated would be needed.  Currently only
+emitted when a printf-type format required fewer arguments than were
+supplied, but might be used in the future for e.g. "pack" in perlfunc.
+.ie n .IP "refcnt_dec: fd %d%s" 4
+.el .IP "refcnt_dec: fd \f(CW%d\fR%s" 4
+.IX Item "refcnt_dec: fd %d%s"
+.PD 0
+.ie n .IP "refcnt: fd %d%s" 4
+.el .IP "refcnt: fd \f(CW%d\fR%s" 4
+.IX Item "refcnt: fd %d%s"
+.ie n .IP "refcnt_inc: fd %d%s" 4
+.el .IP "refcnt_inc: fd \f(CW%d\fR%s" 4
+.IX Item "refcnt_inc: fd %d%s"
+.PD
+(P) Perl's I/O implementation failed an internal consistency check.  If
+you see this message, something is very wrong.
+.IP "Reference found where even-sized list expected" 4
+.IX Item "Reference found where even-sized list expected"
+(W misc) You gave a single reference where Perl was expecting a list
+with an even number of elements (for assignment to a hash).  This
+usually means that you used the anon hash constructor when you meant
+to use parens.  In any case, a hash requires key/value \fBpairs\fR.
+.Sp
+.Vb 4
+\&    %hash = { one => 1, two => 2, };    # WRONG
+\&    %hash = [ qw/ an anon array / ];    # WRONG
+\&    %hash = ( one => 1, two => 2, );    # right
+\&    %hash = qw( one 1 two 2 );                  # also fine
+.Ve
+.IP "Reference is already weak" 4
+.IX Item "Reference is already weak"
+(W misc) You have attempted to weaken a reference that is already weak.
+Doing so has no effect.
+.IP "Reference is not weak" 4
+.IX Item "Reference is not weak"
+(W misc) You have attempted to unweaken a reference that is not weak.
+Doing so has no effect.
+.IP "Reference to invalid group 0 in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Reference to invalid group 0 in regex; marked by <--\ HERE in m/%s/"
+(F) You used \f(CW\*(C`\eg0\*(C'\fR or similar in a regular expression.  You may refer
+to capturing parentheses only with strictly positive integers
+(normal backreferences) or with strictly negative integers (relative
+backreferences).  Using 0 does not make sense.
+.IP "Reference to nonexistent group in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Reference to nonexistent group in regex; marked by <--\ HERE in m/%s/"
+(F) You used something like \f(CW\*(C`\e7\*(C'\fR in your regular expression, but there are
+not at least seven sets of capturing parentheses in the expression.  If
+you wanted to have the character with ordinal 7 inserted into the regular
+expression, prepend zeroes to make it three digits long: \f(CW\*(C`\e007\*(C'\fR
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Reference to nonexistent named group in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Reference to nonexistent named group in regex; marked by <--\ HERE in m/%s/"
+(F) You used something like \f(CW\*(C`\ek\*(AqNAME\*(Aq\*(C'\fR or \f(CW\*(C`\ek<NAME>\*(C'\fR in your regular
+expression, but there is no corresponding named capturing parentheses
+such as \f(CW\*(C`(?\*(AqNAME\*(Aq...)\*(C'\fR or \f(CW\*(C`(?<NAME>...)\*(C'\fR.  Check if the name has been
+spelled correctly both in the backreference and the declaration.
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Reference to nonexistent or unclosed group in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Reference to nonexistent or unclosed group in regex; marked by <--\ HERE in m/%s/"
+(F) You used something like \f(CW\*(C`\eg{\-7}\*(C'\fR in your regular expression, but there
+are not at least seven sets of closed capturing parentheses in the
+expression before where the \f(CW\*(C`\eg{\-7}\*(C'\fR was located.
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "regexp memory corruption" 4
+.IX Item "regexp memory corruption"
+(P) The regular expression engine got confused by what the regular
+expression compiler gave it.
+.IP "Regexp modifier ""/%c"" may appear a maximum of twice" 4
+.IX Item "Regexp modifier ""/%c"" may appear a maximum of twice"
+.PD 0
+.IP "Regexp modifier ""%c"" may appear a maximum of twice in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Regexp modifier ""%c"" may appear a maximum of twice in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) The regular expression pattern had too many occurrences
+of the specified modifier.  Remove the extraneous ones.
+.IP "Regexp modifier ""%c"" may not appear after the ""\-"" in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Regexp modifier ""%c"" may not appear after the ""-"" in regex; marked by <-- HERE in m/%s/"
+(F) Turning off the given modifier has the side effect of turning on
+another one.  Perl currently doesn't allow this.  Reword the regular
+expression to use the modifier you want to turn on (and place it before
+the minus), instead of the one you want to turn off.
+.IP "Regexp modifier ""/%c"" may not appear twice" 4
+.IX Item "Regexp modifier ""/%c"" may not appear twice"
+.PD 0
+.IP "Regexp modifier ""%c"" may not appear twice in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Regexp modifier ""%c"" may not appear twice in regex; marked by <-- HERE in m/%s/"
+.PD
+(F) The regular expression pattern had too many occurrences
+of the specified modifier.  Remove the extraneous ones.
+.IP "Regexp modifiers ""/%c"" and ""/%c"" are mutually exclusive" 4
+.IX Item "Regexp modifiers ""/%c"" and ""/%c"" are mutually exclusive"
+.PD 0
+.IP "Regexp modifiers ""%c"" and ""%c"" are mutually exclusive in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Regexp modifiers ""%c"" and ""%c"" are mutually exclusive in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) The regular expression pattern had more than one of these
+mutually exclusive modifiers.  Retain only the modifier that is
+supposed to be there.
+.IP "Regexp out of space in regex m/%s/" 4
+.IX Item "Regexp out of space in regex m/%s/"
+(P) A "can't happen" error, because \fBsafemalloc()\fR should have caught it
+earlier.
+.IP "Repeated format line will never terminate (~~ and @#)" 4
+.IX Item "Repeated format line will never terminate (~~ and @#)"
+(F) Your format contains the ~~ repeat-until-blank sequence and a
+numeric field that will never go blank so that the repetition never
+terminates.  You might use ^# instead.  See perlform.
+.IP "Replacement list is longer than search list" 4
+.IX Item "Replacement list is longer than search list"
+(W misc) You have used a replacement list that is longer than the
+search list.  So the additional elements in the replacement list
+are meaningless.
+.ie n .IP "Required parameter '%s' is missing for %s constructor" 4
+.el .IP "Required parameter '%s' is missing for \f(CW%s\fR constructor" 4
+.IX Item "Required parameter '%s' is missing for %s constructor"
+(F) You called the constructor for a class that has a required named
+parameter, but did not pass that parameter at all.
+.IP "'(*%s' requires a terminating ':' in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "'(*%s' requires a terminating ':' in regex; marked by <-- HERE in m/%s/"
+(F) You used a construct that needs a colon and pattern argument.
+Supply these or check that you are using the right construct.
+.IP "'%s' resolved to '\eo{%s}%d'" 4
+.IX Item "'%s' resolved to 'o{%s}%d'"
+As of Perl 5.32, this message is no longer generated.  Instead, see
+"Non-octal character '%c' terminates \eo early.  Resolved as "%s"".
+(W misc, regexp)  You wrote something like \f(CW\*(C`\e08\*(C'\fR, or \f(CW\*(C`\e179\*(C'\fR in a
+double-quotish string.  All but the last digit is treated as a single
+character, specified in octal.  The last digit is the next character in
+the string.  To tell Perl that this is indeed what you want, you can use
+the \f(CW\*(C`\eo{ }\*(C'\fR syntax, or use exactly three digits to specify the octal
+for the character.
+.ie n .IP "Reversed %s= operator" 4
+.el .IP "Reversed \f(CW%s\fR= operator" 4
+.IX Item "Reversed %s= operator"
+(W syntax) You wrote your assignment operator backwards.  The = must
+always come last, to avoid ambiguity with subsequent unary operators.
+.ie n .IP "\fBrewinddir()\fR attempted on invalid dirhandle %s" 4
+.el .IP "\fBrewinddir()\fR attempted on invalid dirhandle \f(CW%s\fR" 4
+.IX Item "rewinddir() attempted on invalid dirhandle %s"
+(W io) The dirhandle you tried to do a \fBrewinddir()\fR on is either closed
+or not really a dirhandle.  Check your control flow.
+.ie n .IP "Scalars leaked: %d" 4
+.el .IP "Scalars leaked: \f(CW%d\fR" 4
+.IX Item "Scalars leaked: %d"
+(S internal) Something went wrong in Perl's internal bookkeeping
+of scalars: not all scalar variables were deallocated by the time
+Perl exited.  What this usually indicates is a memory leak, which
+is of course bad, especially if the Perl program is intended to be
+long-running.
+.IP "Scalar value @%s[%s] better written as $%s[%s]" 4
+.IX Item "Scalar value @%s[%s] better written as $%s[%s]"
+(W syntax) You've used an array slice (indicated by @) to select a
+single element of an array.  Generally it's better to ask for a scalar
+value (indicated by $).  The difference is that \f(CW$foo[&bar]\fR always
+behaves like a scalar, both when assigning to it and when evaluating its
+argument, while \f(CW@foo[&bar]\fR behaves like a list when you assign to it,
+and provides a list context to its subscript, which can do weird things
+if you're expecting only one subscript.
+.Sp
+On the other hand, if you were actually hoping to treat the array
+element as a list, you need to look into how references work, because
+Perl will not magically convert between scalars and lists for you.  See
+perlref.
+.IP "Scalar value @%s{%s} better written as $%s{%s}" 4
+.IX Item "Scalar value @%s{%s} better written as $%s{%s}"
+(W syntax) You've used a hash slice (indicated by @) to select a single
+element of a hash.  Generally it's better to ask for a scalar value
+(indicated by $).  The difference is that \f(CW$foo{&bar}\fR always behaves
+like a scalar, both when assigning to it and when evaluating its
+argument, while \f(CW@foo{&bar}\fR behaves like a list when you assign to it,
+and provides a list context to its subscript, which can do weird things
+if you're expecting only one subscript.
+.Sp
+On the other hand, if you were actually hoping to treat the hash element
+as a list, you need to look into how references work, because Perl will
+not magically convert between scalars and lists for you.  See
+perlref.
+.IP "Search pattern not terminated" 4
+.IX Item "Search pattern not terminated"
+(F) The lexer couldn't find the final delimiter of a // or m{}
+construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading \f(CW\*(C`$\*(C'\fR from a variable \f(CW$m\fR may cause this error.
+.Sp
+Note that since Perl 5.10.0 a // can also be the \fIdefined-or\fR
+construct, not just the empty search pattern.  Therefore code written
+in Perl 5.10.0 or later that uses the // as the \fIdefined-or\fR can be
+misparsed by pre\-5.10.0 Perls as a non-terminated search pattern.
+.ie n .IP "\fBseekdir()\fR attempted on invalid dirhandle %s" 4
+.el .IP "\fBseekdir()\fR attempted on invalid dirhandle \f(CW%s\fR" 4
+.IX Item "seekdir() attempted on invalid dirhandle %s"
+(W io) The dirhandle you are doing a \fBseekdir()\fR on is either closed or not
+really a dirhandle.  Check your control flow.
+.IP "%\fBsseek()\fR on unopened filehandle" 4
+.IX Item "%sseek() on unopened filehandle"
+(W unopened) You tried to use the \fBseek()\fR or \fBsysseek()\fR function on a
+filehandle that was either never opened or has since been closed.
+.IP "select not implemented" 4
+.IX Item "select not implemented"
+(F) This machine doesn't implement the \fBselect()\fR system call.
+.IP "Self-ties of arrays and hashes are not supported" 4
+.IX Item "Self-ties of arrays and hashes are not supported"
+(F) Self-ties are of arrays and hashes are not supported in
+the current implementation.
+.IP "Semicolon seems to be missing" 4
+.IX Item "Semicolon seems to be missing"
+(W semicolon) A nearby syntax error was probably caused by a missing
+semicolon, or possibly some other missing operator, such as a comma.
+.IP "semi-panic: attempt to dup freed string" 4
+.IX Item "semi-panic: attempt to dup freed string"
+(S internal) The internal \fBnewSVsv()\fR routine was called to duplicate a
+scalar that had previously been marked as free.
+.IP "sem%s not implemented" 4
+.IX Item "sem%s not implemented"
+(F) You don't have System V semaphore IPC on your system.
+.ie n .IP "\fBsend()\fR on closed socket %s" 4
+.el .IP "\fBsend()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "send() on closed socket %s"
+(W closed) The socket you're sending to got itself closed sometime
+before now.  Check your control flow.
+.IP "Sequence ""\ec{"" invalid" 4
+.IX Item "Sequence ""c{"" invalid"
+(F) These three characters may not appear in sequence in a
+double-quotish context.  This message is raised only on non-ASCII
+platforms (a different error message is output on ASCII ones).  If you
+were intending to specify a control character with this sequence, you'll
+have to use a different way to specify it.
+.IP "Sequence (? incomplete in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (? incomplete in regex; marked by <--\ HERE in m/%s/"
+(F) A regular expression ended with an incomplete extension (?.  The
+<\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  See perlre.
+.IP "Sequence (?%c...) not implemented in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?%c...) not implemented in regex; marked by <--\ HERE in m/%s/"
+(F) A proposed regular expression extension has the character reserved
+but has not yet been written.  The <\-\-\ HERE shows whereabouts in the
+regular expression the problem was discovered.  See perlre.
+.IP "Sequence (?%s...) not recognized in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?%s...) not recognized in regex; marked by <--\ HERE in m/%s/"
+(F) You used a regular expression extension that doesn't make sense.
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  This may happen when using the \f(CW\*(C`(?^...)\*(C'\fR construct to tell
+Perl to use the default regular expression modifiers, and you
+redundantly specify a default modifier.  For other
+causes, see perlre.
+.IP "Sequence (?#... not terminated in regex m/%s/" 4
+.IX Item "Sequence (?#... not terminated in regex m/%s/"
+(F) A regular expression comment must be terminated by a closing
+parenthesis.  Embedded parentheses aren't allowed.  See
+perlre.
+.IP "Sequence (?&... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?&... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named reference of the form \f(CW\*(C`(?&...)\*(C'\fR was missing the final
+closing parenthesis after the name.  The <\-\-\ HERE shows whereabouts
+in the regular expression the problem was discovered.
+.IP "Sequence (?%c... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?%c... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named group of the form \f(CW\*(C`(?\*(Aq...\*(Aq)\*(C'\fR or \f(CW\*(C`(?<...>)\*(C'\fR was missing the final
+closing quote or angle bracket.  The <\-\-\ HERE shows whereabouts in the
+regular expression the problem was discovered.
+.IP "Sequence (%s... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (%s... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A lookahead assertion \f(CW\*(C`(?=...)\*(C'\fR or \f(CW\*(C`(?!...)\*(C'\fR or lookbehind
+assertion \f(CW\*(C`(?<=...)\*(C'\fR or \f(CW\*(C`(?<!...)\*(C'\fR was missing the final
+closing parenthesis.  The <\-\-\ HERE shows whereabouts in the
+regular expression the problem was discovered.
+.IP "Sequence (?(%c... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?(%c... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named reference of the form \f(CW\*(C`(?(\*(Aq...\*(Aq)...)\*(C'\fR or \f(CW\*(C`(?(<...>)...)\*(C'\fR was
+missing the final closing quote or angle bracket after the name.  The
+<\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Sequence (?... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) There was no matching closing parenthesis for the '('.  The
+<\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.
+.IP "Sequence \e%s... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence %s... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) The regular expression expects a mandatory argument following the escape
+sequence and this has been omitted or incorrectly written.
+.IP "Sequence (?{...}) not terminated with ')'" 4
+.IX Item "Sequence (?{...}) not terminated with ')'"
+(F) The end of the perl code contained within the {...} must be
+followed immediately by a ')'.
+.IP "Sequence (?P>... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?P>... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named reference of the form \f(CW\*(C`(?P>...)\*(C'\fR was missing the final
+closing parenthesis after the name.  The <\-\-\ HERE shows whereabouts
+in the regular expression the problem was discovered.
+.IP "Sequence (?P<... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence (?P<... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named group of the form \f(CW\*(C`(?P<...>\*(Aq)\*(C'\fR was missing the final
+closing angle bracket.  The <\-\-\ HERE shows whereabouts in the
+regular expression the problem was discovered.
+.IP "Sequence ?P=... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Sequence ?P=... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) A named reference of the form \f(CW\*(C`(?P=...)\*(C'\fR was missing the final
+closing parenthesis after the name.  The <\-\-\ HERE shows whereabouts
+in the regular expression the problem was discovered.
+.IP "Sequence (?R) not terminated in regex m/%s/" 4
+.IX Item "Sequence (?R) not terminated in regex m/%s/"
+(F) An \f(CW\*(C`(?R)\*(C'\fR or \f(CW\*(C`(?0)\*(C'\fR sequence in a regular expression was missing the
+final parenthesis.
+.IP "500 Server error" 4
+.IX Item "500 Server error"
+(A) This is the error message generally seen in a browser window
+when trying to run a CGI program (including SSI) over the web.  The
+actual error text varies widely from server to server.  The most
+frequently-seen variants are "500 Server error", "Method (something)
+not permitted", "Document contains no data", "Premature end of script
+headers", and "Did not produce a valid header".
+.Sp
+\&\fBThis is a CGI error, not a Perl error\fR.
+.Sp
+You need to make sure your script is executable, is accessible by
+the user CGI is running the script under (which is probably not the
+user account you tested it under), does not rely on any environment
+variables (like PATH) from the user it isn't running under, and isn't
+in a location where the CGI server can't find it, basically, more or
+less.  Please see the following for more information:
+.Sp
+.Vb 3
+\&        https://www.perl.org/CGI_MetaFAQ.html
+\&        http://www.htmlhelp.org/faq/cgifaq.html
+\&        http://www.w3.org/Security/Faq/
+.Ve
+.Sp
+You should also look at perlfaq9.
+.IP "\fBsetegid()\fR not implemented" 4
+.IX Item "setegid() not implemented"
+(F) You tried to assign to \f(CW$)\fR, and your operating system doesn't
+support the \fBsetegid()\fR system call (or equivalent), or at least Configure
+didn't think so.
+.IP "\fBseteuid()\fR not implemented" 4
+.IX Item "seteuid() not implemented"
+(F) You tried to assign to \f(CW$>\fR, and your operating system doesn't
+support the \fBseteuid()\fR system call (or equivalent), or at least Configure
+didn't think so.
+.IP "setpgrp can't take arguments" 4
+.IX Item "setpgrp can't take arguments"
+(F) Your system has the \fBsetpgrp()\fR from BSD 4.2, which takes no
+arguments, unlike POSIX \fBsetpgid()\fR, which takes a process ID and process
+group ID.
+.IP "\fBsetrgid()\fR not implemented" 4
+.IX Item "setrgid() not implemented"
+(F) You tried to assign to \f(CW$(\fR, and your operating system doesn't
+support the \fBsetrgid()\fR system call (or equivalent), or at least Configure
+didn't think so.
+.IP "\fBsetruid()\fR not implemented" 4
+.IX Item "setruid() not implemented"
+(F) You tried to assign to \f(CW$<\fR, and your operating system doesn't
+support the \fBsetruid()\fR system call (or equivalent), or at least Configure
+didn't think so.
+.ie n .IP "\fBsetsockopt()\fR on closed socket %s" 4
+.el .IP "\fBsetsockopt()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "setsockopt() on closed socket %s"
+(W closed) You tried to set a socket option on a closed socket.  Did you
+forget to check the return value of your \fBsocket()\fR call?  See
+"setsockopt" in perlfunc.
+.ie n .IP "Setting $/ to a reference to %s is forbidden" 4
+.el .IP "Setting $/ to a reference to \f(CW%s\fR is forbidden" 4
+.IX Item "Setting $/ to a reference to %s is forbidden"
+(F) You assigned a reference to a scalar to \f(CW$/\fR where the referenced item is
+not a positive integer.  In older perls this \fBappeared\fR to work the same as
+setting it to \f(CW\*(C`undef\*(C'\fR but was in fact internally different, less efficient
+and with very bad luck could have resulted in your file being split by a
+stringified form of the reference.
+.Sp
+In Perl 5.20.0 this was changed so that it would be \fBexactly\fR the same as
+setting \f(CW$/\fR to undef, with the exception that this warning would be thrown.
+.Sp
+You are recommended to change your code to set \f(CW$/\fR to \f(CW\*(C`undef\*(C'\fR explicitly if
+you wish to slurp the file.  As of Perl 5.28 assigning \f(CW$/\fR to a reference
+to an integer which isn't positive is a fatal error.
+.ie n .IP "Setting $/ to %s reference is forbidden" 4
+.el .IP "Setting $/ to \f(CW%s\fR reference is forbidden" 4
+.IX Item "Setting $/ to %s reference is forbidden"
+(F) You tried to assign a reference to a non integer to \f(CW$/\fR.  In older
+Perls this would have behaved similarly to setting it to a reference to
+a positive integer, where the integer was the address of the reference.
+As of Perl 5.20.0 this is a fatal error, to allow future versions of Perl
+to use non-integer refs for more interesting purposes.
+.IP "shm%s not implemented" 4
+.IX Item "shm%s not implemented"
+(F) You don't have System V shared memory IPC on your system.
+.IP "!=~ should be !~" 4
+.IX Item "!=~ should be !~"
+(W syntax) The non-matching operator is !~, not !=~.  !=~ will be
+interpreted as the != (numeric not equal) and ~ (1's complement)
+operators: probably not what you intended.
+.IP "/%s/ should probably be written as ""%s""" 4
+.IX Item "/%s/ should probably be written as ""%s"""
+(W syntax) You have used a pattern where Perl expected to find a string,
+as in the first argument to \f(CW\*(C`join\*(C'\fR.  Perl will treat the true or false
+result of matching the pattern against \f(CW$_\fR as the string, which is
+probably not what you had in mind.
+.ie n .IP "\fBshutdown()\fR on closed socket %s" 4
+.el .IP "\fBshutdown()\fR on closed socket \f(CW%s\fR" 4
+.IX Item "shutdown() on closed socket %s"
+(W closed) You tried to do a shutdown on a closed socket.  Seems a bit
+superfluous.
+.IP "SIG%s handler ""%s"" not defined" 4
+.IX Item "SIG%s handler ""%s"" not defined"
+(W signal) The signal handler named in \f(CW%SIG\fR doesn't, in fact, exist.
+Perhaps you put it into the wrong package?
+.ie n .IP "Slab leaked from cv %p" 4
+.el .IP "Slab leaked from cv \f(CW%p\fR" 4
+.IX Item "Slab leaked from cv %p"
+(S) If you see this message, then something is seriously wrong with the
+internal bookkeeping of op trees.  An op tree needed to be freed after
+a compilation error, but could not be found, so it was leaked instead.
+.IP "sleep(%u) too large" 4
+.IX Item "sleep(%u) too large"
+(W overflow) You called \f(CW\*(C`sleep\*(C'\fR with a number that was larger than
+it can reliably handle and \f(CW\*(C`sleep\*(C'\fR probably slept for less time than
+requested.
+.IP "Slurpy parameter not last" 4
+.IX Item "Slurpy parameter not last"
+(F) In a subroutine signature, you put something after a slurpy (array or
+hash) parameter.  The slurpy parameter takes all the available arguments,
+so there can't be any left to fill later parameters.
+.IP "Smart matching a non-overloaded object breaks encapsulation" 4
+.IX Item "Smart matching a non-overloaded object breaks encapsulation"
+(F) You should not use the \f(CW\*(C`~~\*(C'\fR operator on an object that does not
+overload it: Perl refuses to use the object's underlying structure
+for the smart match.
+.IP "Smartmatch is deprecated" 4
+.IX Item "Smartmatch is deprecated"
+(D deprecated::smartmatch) This warning is emitted if you
+use the smartmatch (\f(CW\*(C`~~\*(C'\fR) operator.  This is a deprecated
+feature.  Particularly, its behavior is noticed for being
+unnecessarily complex and unintuitive, and it will be removed
+in Perl 5.42.
+.IP "Sorry, hash keys must be smaller than 2**31 bytes" 4
+.IX Item "Sorry, hash keys must be smaller than 2**31 bytes"
+(F) You tried to create a hash containing a very large key, where "very
+large" means that it needs at least 2 gigabytes to store. Unfortunately,
+Perl doesn't yet handle such large hash keys. You should
+reconsider your design to avoid hashing such a long string directly.
+.IP "sort is now a reserved word" 4
+.IX Item "sort is now a reserved word"
+(F) An ancient error message that almost nobody ever runs into anymore.
+But before sort was a keyword, people sometimes used it as a filehandle.
+.IP "Source filters apply only to byte streams" 4
+.IX Item "Source filters apply only to byte streams"
+(F) You tried to activate a source filter (usually by loading a
+source filter module) within a string passed to \f(CW\*(C`eval\*(C'\fR.  This is
+not permitted under the \f(CW\*(C`unicode_eval\*(C'\fR feature.  Consider using
+\&\f(CW\*(C`evalbytes\*(C'\fR instead.  See feature.
+.IP "\fBsplice()\fR offset past end of array" 4
+.IX Item "splice() offset past end of array"
+(W misc) You attempted to specify an offset that was past the end of
+the array passed to \fBsplice()\fR.  Splicing will instead commence at the
+end of the array, rather than past it.  If this isn't what you want,
+try explicitly pre-extending the array by assigning $#array = \f(CW$offset\fR.
+See "splice" in perlfunc.
+.IP "Split loop" 4
+.IX Item "Split loop"
+(P) The split was looping infinitely.  (Obviously, a split shouldn't
+iterate more times than there are characters of input, which is what
+happened.)  See "split" in perlfunc.
+.IP "Statement unlikely to be reached" 4
+.IX Item "Statement unlikely to be reached"
+(W exec) You did an \fBexec()\fR with some statement after it other than a
+\&\fBdie()\fR.  This is almost always an error, because \fBexec()\fR never returns
+unless there was a failure.  You probably wanted to use \fBsystem()\fR
+instead, which does return.  To suppress this warning, put the \fBexec()\fR in
+a block by itself.
+.ie n .IP """state"" subroutine %s can't be in a package" 4
+.el .IP """state"" subroutine \f(CW%s\fR can't be in a package" 4
+.IX Item """state"" subroutine %s can't be in a package"
+(F) Lexically scoped subroutines aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.
+.ie n .IP """state %s"" used in sort comparison" 4
+.el .IP """state \f(CW%s\fR"" used in sort comparison" 4
+.IX Item """state %s"" used in sort comparison"
+(W syntax) The package variables \f(CW$a\fR and \f(CW$b\fR are used for sort comparisons.
+You used \f(CW$a\fR or \f(CW$b\fR in as an operand to the \f(CW\*(C`<=>\*(C'\fR or \f(CW\*(C`cmp\*(C'\fR operator inside a
+sort comparison block, and the variable had earlier been declared as a
+lexical variable.  Either qualify the sort variable with the package
+name, or rename the lexical variable.
+.ie n .IP """state"" variable %s can't be in a package" 4
+.el .IP """state"" variable \f(CW%s\fR can't be in a package" 4
+.IX Item """state"" variable %s can't be in a package"
+(F) Lexically scoped variables aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.  Use
+\&\fBlocal()\fR if you want to localize a package variable.
+.ie n .IP "\fBstat()\fR on unopened filehandle %s" 4
+.el .IP "\fBstat()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "stat() on unopened filehandle %s"
+(W unopened) You tried to use the \fBstat()\fR function on a filehandle that
+was either never opened or has since been closed.
+.IP "Strings with code points over 0xFF may not be mapped into in-memory file handles" 4
+.IX Item "Strings with code points over 0xFF may not be mapped into in-memory file handles"
+(W utf8) You tried to open a reference to a scalar for read or append
+where the scalar contained code points over 0xFF.  In-memory files
+model on-disk files and can only contain bytes.
+.IP "Stub found while resolving method ""%s"" overloading ""%s"" in package ""%s""" 4
+.IX Item "Stub found while resolving method ""%s"" overloading ""%s"" in package ""%s"""
+(P) Overloading resolution over \f(CW@ISA\fR tree may be broken by importation
+stubs.  Stubs should never be implicitly created, but explicit calls to
+\&\f(CW\*(C`can\*(C'\fR may break this.
+.IP "Subroutine attributes must come before the signature" 4
+.IX Item "Subroutine attributes must come before the signature"
+(F) When subroutine signatures are enabled, any subroutine attributes must
+come before the signature. Note that this order was the opposite in
+versions 5.22..5.26. So:
+.Sp
+.Vb 2
+\&    sub foo :lvalue ($a, $b) { ... }  # 5.20 and 5.28 +
+\&    sub foo ($a, $b) :lvalue { ... }  # 5.22 .. 5.26
+.Ve
+.IP "Subroutine ""&%s"" is not available" 4
+.IX Item "Subroutine ""&%s"" is not available"
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical subroutine that is not currently
+available.  This can happen for one of two reasons.  First, the lexical
+subroutine may be declared in an outer anonymous subroutine that has
+not yet been created.  (Remember that named subs are created at compile
+time, while anonymous subs are created at run-time.)  For example,
+.Sp
+.Vb 1
+\&    sub { my sub a {...} sub f { \e&a } }
+.Ve
+.Sp
+At the time that f is created, it can't capture the current "a" sub,
+since the anonymous subroutine hasn't been created yet.  Conversely, the
+following won't give a warning since the anonymous subroutine has by now
+been created and is live:
+.Sp
+.Vb 1
+\&    sub { my sub a {...} eval \*(Aqsub f { \e&a }\*(Aq }\->();
+.Ve
+.Sp
+The second situation is caused by an eval accessing a lexical subroutine
+that has gone out of scope, for example,
+.Sp
+.Vb 5
+\&    sub f {
+\&        my sub a {...}
+\&        sub { eval \*(Aq\e&a\*(Aq }
+\&    }
+\&    f()\->();
+.Ve
+.Sp
+Here, when the '\e&a' in the eval is being compiled, f() is not currently
+being executed, so its &a is not available for capture.
+.ie n .IP """%s"" subroutine &%s masks earlier declaration in same %s" 4
+.el .IP """%s"" subroutine &%s masks earlier declaration in same \f(CW%s\fR" 4
+.IX Item """%s"" subroutine &%s masks earlier declaration in same %s"
+(W shadow) A "my" or "state" subroutine has been redeclared in the
+current scope or statement, effectively eliminating all access to
+the previous instance.  This is almost always a typographical error.
+Note that the earlier subroutine will still exist until the end of
+the scope or until all closure references to it are destroyed.
+.ie n .IP "Subroutine %s redefined" 4
+.el .IP "Subroutine \f(CW%s\fR redefined" 4
+.IX Item "Subroutine %s redefined"
+(W redefine) You redefined a subroutine.  To suppress this warning, say
+.Sp
+.Vb 4
+\&    {
+\&        no warnings \*(Aqredefine\*(Aq;
+\&        eval "sub name { ... }";
+\&    }
+.Ve
+.IP "Subroutine ""%s"" will not stay shared" 4
+.IX Item "Subroutine ""%s"" will not stay shared"
+(W closure) An inner (nested) \fInamed\fR subroutine is referencing a "my"
+subroutine defined in an outer named subroutine.
+.Sp
+When the inner subroutine is called, it will see the value of the outer
+subroutine's lexical subroutine as it was before and during the *first*
+call to the outer subroutine; in this case, after the first call to the
+outer subroutine is complete, the inner and outer subroutines will no
+longer share a common value for the lexical subroutine.  In other words,
+it will no longer be shared.  This will especially make a difference
+if the lexical subroutines accesses lexical variables declared in its
+surrounding scope.
+.Sp
+This problem can usually be solved by making the inner subroutine
+anonymous, using the \f(CW\*(C`sub {}\*(C'\fR syntax.  When inner anonymous subs that
+reference lexical subroutines in outer subroutines are created, they
+are automatically rebound to the current values of such lexical subs.
+.IP "Substitution loop" 4
+.IX Item "Substitution loop"
+(P) The substitution was looping infinitely.  (Obviously, a substitution
+shouldn't iterate more times than there are characters of input, which
+is what happened.)  See the discussion of substitution in
+"Regexp Quote-Like Operators" in perlop.
+.IP "Substitution pattern not terminated" 4
+.IX Item "Substitution pattern not terminated"
+(F) The lexer couldn't find the interior delimiter of an s/// or s{}{}
+construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading \f(CW\*(C`$\*(C'\fR from variable \f(CW$s\fR may cause this error.
+.IP "Substitution replacement not terminated" 4
+.IX Item "Substitution replacement not terminated"
+(F) The lexer couldn't find the final delimiter of an s/// or s{}{}
+construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading \f(CW\*(C`$\*(C'\fR from variable \f(CW$s\fR may cause this error.
+.IP "substr outside of string" 4
+.IX Item "substr outside of string"
+(W substr)(F) You tried to reference a \fBsubstr()\fR that pointed outside of
+a string.  That is, the absolute value of the offset was larger than the
+length of the string.  See "substr" in perlfunc.  This warning is fatal if
+substr is used in an lvalue context (as the left hand side of an
+assignment or as a subroutine argument for example).
+.ie n .IP "sv_upgrade from type %d down to type %d" 4
+.el .IP "sv_upgrade from type \f(CW%d\fR down to type \f(CW%d\fR" 4
+.IX Item "sv_upgrade from type %d down to type %d"
+(P) Perl tried to force the upgrade of an SV to a type which was actually
+inferior to its current type.
+.IP "Switch (?(condition)... contains too many branches in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Switch (?(condition)... contains too many branches in regex; marked by <--\ HERE in m/%s/"
+(F) A (?(condition)if\-clause|else\-clause) construct can have at most
+two branches (the if-clause and the else-clause).  If you want one or
+both to contain alternation, such as using \f(CW\*(C`this|that|other\*(C'\fR, enclose
+it in clustering parentheses:
+.Sp
+.Vb 1
+\&    (?(condition)(?:this|that|other)|else\-clause)
+.Ve
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem
+was discovered.  See perlre.
+.IP "Switch condition not recognized in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Switch condition not recognized in regex; marked by <--\ HERE in m/%s/"
+(F) The condition part of a (?(condition)if\-clause|else\-clause) construct
+is not known.  The condition must be one of the following:
+.Sp
+.Vb 9
+\& (1) (2) ...        true if 1st, 2nd, etc., capture matched
+\& (<NAME>) (\*(AqNAME\*(Aq)  true if named capture matched
+\& (?=...) (?<=...)   true if subpattern matches
+\& (?!...) (?<!...)   true if subpattern fails to match
+\& (?{ CODE })        true if code returns a true value
+\& (R)                true if evaluating inside recursion
+\& (R1) (R2) ...      true if directly inside capture group 1, 2, etc.
+\& (R&NAME)           true if directly inside named capture
+\& (DEFINE)           always false; for defining named subpatterns
+.Ve
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  See perlre.
+.IP "Switch (?(condition)... not terminated in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Switch (?(condition)... not terminated in regex; marked by <--\ HERE in m/%s/"
+(F) You omitted to close a (?(condition)...) block somewhere
+in the pattern.  Add a closing parenthesis in the appropriate
+position.  See perlre.
+.ie n .IP "switching effective %s is not implemented" 4
+.el .IP "switching effective \f(CW%s\fR is not implemented" 4
+.IX Item "switching effective %s is not implemented"
+(F) While under the \f(CW\*(C`use filetest\*(C'\fR pragma, we cannot switch the real
+and effective uids or gids.
+.IP "syntax error" 4
+.IX Item "syntax error"
+(F) Probably means you had a syntax error.  Common reasons include:
+.Sp
+.Vb 6
+\&    A keyword is misspelled.
+\&    A semicolon is missing.
+\&    A comma is missing.
+\&    An opening or closing parenthesis is missing.
+\&    An opening or closing brace is missing.
+\&    A closing quote is missing.
+.Ve
+.Sp
+Often there will be another error message associated with the syntax
+error giving more information.  (Sometimes it helps to turn on \fB\-w\fR.)
+The error message itself often tells you where it was in the line when
+it decided to give up.  Sometimes the actual error is several tokens
+before this, because Perl is good at understanding random input.
+Occasionally the line number may be misleading, and once in a blue moon
+the only way to figure out what's triggering the error is to call
+\&\f(CW\*(C`perl \-c\*(C'\fR repeatedly, chopping away half the program each time to see
+if the error went away.  Sort of the cybernetic version of 20\ questions.
+.ie n .IP "syntax error at line %d: '%s' unexpected" 4
+.el .IP "syntax error at line \f(CW%d:\fR '%s' unexpected" 4
+.IX Item "syntax error at line %d: '%s' unexpected"
+(A) You've accidentally run your script through the Bourne shell instead
+of Perl.  Check the #! line, or manually feed your script into Perl
+yourself.
+.ie n .IP "syntax error in file %s at line %d, next 2 tokens ""%s""" 4
+.el .IP "syntax error in file \f(CW%s\fR at line \f(CW%d\fR, next 2 tokens ""%s""" 4
+.IX Item "syntax error in file %s at line %d, next 2 tokens ""%s"""
+(F) This error is likely to occur if you run a perl5 script through
+a perl4 interpreter, especially if the next 2 tokens are "use strict"
+or "my \f(CW$var\fR" or "our \f(CW$var\fR".
+.IP "Syntax error in (?[...]) in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Syntax error in (?[...]) in regex; marked by <-- HERE in m/%s/"
+(F) Perl could not figure out what you meant inside this construct; this
+notifies you that it is giving up trying.
+.ie n .IP "%s syntax OK" 4
+.el .IP "\f(CW%s\fR syntax OK" 4
+.IX Item "%s syntax OK"
+(F) The final summary message when a \f(CW\*(C`perl \-c\*(C'\fR succeeds.
+.ie n .IP "\fBsysread()\fR on closed filehandle %s" 4
+.el .IP "\fBsysread()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "sysread() on closed filehandle %s"
+(W closed) You tried to read from a closed filehandle.
+.ie n .IP "\fBsysread()\fR on unopened filehandle %s" 4
+.el .IP "\fBsysread()\fR on unopened filehandle \f(CW%s\fR" 4
+.IX Item "sysread() on unopened filehandle %s"
+(W unopened) You tried to read from a filehandle that was never opened.
+.ie n .IP "System V %s is not implemented on this machine" 4
+.el .IP "System V \f(CW%s\fR is not implemented on this machine" 4
+.IX Item "System V %s is not implemented on this machine"
+(F) You tried to do something with a function beginning with "sem",
+"shm", or "msg" but that System V IPC is not implemented in your
+machine.  In some machines the functionality can exist but be
+unconfigured.  Consult your system support.
+.ie n .IP "\fBsyswrite()\fR on closed filehandle %s" 4
+.el .IP "\fBsyswrite()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "syswrite() on closed filehandle %s"
+(W closed) The filehandle you're writing to got itself closed sometime
+before now.  Check your control flow.
+.ie n .IP """\-T"" and ""\-B"" not implemented on filehandles" 4
+.el .IP "\f(CW\-T\fR and \f(CW\-B\fR not implemented on filehandles" 4
+.IX Item "-T and -B not implemented on filehandles"
+(F) Perl can't peek at the stdio buffer of filehandles when it doesn't
+know about your kind of stdio.  You'll have to use a filename instead.
+.IP "Target of goto is too deeply nested" 4
+.IX Item "Target of goto is too deeply nested"
+(F) You tried to use \f(CW\*(C`goto\*(C'\fR to reach a label that was too deeply nested
+for Perl to reach.  Perl is doing you a favor by refusing.
+.ie n .IP "\fBtelldir()\fR attempted on invalid dirhandle %s" 4
+.el .IP "\fBtelldir()\fR attempted on invalid dirhandle \f(CW%s\fR" 4
+.IX Item "telldir() attempted on invalid dirhandle %s"
+(W io) The dirhandle you tried to \fBtelldir()\fR is either closed or not really
+a dirhandle.  Check your control flow.
+.IP "\fBtell()\fR on unopened filehandle" 4
+.IX Item "tell() on unopened filehandle"
+(W unopened) You tried to use the \fBtell()\fR function on a filehandle that
+was either never opened or has since been closed.
+.IP "The \fBcrypt()\fR function is unimplemented due to excessive paranoia." 4
+.IX Item "The crypt() function is unimplemented due to excessive paranoia."
+(F) Configure couldn't find the \fBcrypt()\fR function on your machine,
+probably because your vendor didn't supply it, probably because they
+think the U.S. Government thinks it's a secret, or at least that they
+will continue to pretend that it is.  And if you quote me on that, I
+will deny it.
+.IP "The experimental declared_refs feature is not enabled" 4
+.IX Item "The experimental declared_refs feature is not enabled"
+(F) To declare references to variables, as in \f(CW\*(C`my \e%x\*(C'\fR, you must first enable
+the feature:
+.Sp
+.Vb 2
+\&    no warnings "experimental::declared_refs";
+\&    use feature "declared_refs";
+.Ve
+.ie n .IP "The %s function is unimplemented" 4
+.el .IP "The \f(CW%s\fR function is unimplemented" 4
+.IX Item "The %s function is unimplemented"
+(F) The function indicated isn't implemented on this architecture,
+according to the probings of Configure.
+.IP "The private_use feature is experimental" 4
+.IX Item "The private_use feature is experimental"
+(S experimental::private_use) This feature is actually a hook for future
+use.
+.ie n .IP "The stat preceding %s wasn't an lstat" 4
+.el .IP "The stat preceding \f(CW%s\fR wasn't an lstat" 4
+.IX Item "The stat preceding %s wasn't an lstat"
+(F) It makes no sense to test the current stat buffer for symbolic
+linkhood if the last stat that wrote to the stat buffer already went
+past the symlink to get to the real file.  Use an actual filename
+instead.
+.IP "The Unicode property wildcards feature is experimental" 4
+.IX Item "The Unicode property wildcards feature is experimental"
+(S experimental::uniprop_wildcards) This feature is experimental
+and its behavior may in any future release of perl.  See
+"Wildcards in Property Values" in perlunicode.
+.IP "The 'unique' attribute may only be applied to 'our' variables" 4
+.IX Item "The 'unique' attribute may only be applied to 'our' variables"
+(F) This attribute was never supported on \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`sub\*(C'\fR declarations.
+.IP "This Perl can't reset CRTL environ elements (%s)" 4
+.IX Item "This Perl can't reset CRTL environ elements (%s)"
+.PD 0
+.IP "This Perl can't set CRTL environ elements (%s=%s)" 4
+.IX Item "This Perl can't set CRTL environ elements (%s=%s)"
+.PD
+(W internal) Warnings peculiar to VMS.  You tried to change or delete an
+element of the CRTL's internal environ array, but your copy of Perl
+wasn't built with a CRTL that contained the \fBsetenv()\fR function.  You'll
+need to rebuild Perl with a CRTL that does, or redefine
+\&\fIPERL_ENV_TABLES\fR (see perlvms) so that the environ array isn't the
+target of the change to
+\&\f(CW%ENV\fR which produced the warning.
+.IP "This Perl has not been built with support for randomized hash key traversal but something called \fBPerl_hv_rand_set()\fR." 4
+.IX Item "This Perl has not been built with support for randomized hash key traversal but something called Perl_hv_rand_set()."
+(F) Something has attempted to use an internal API call which
+depends on Perl being compiled with the default support for randomized hash
+key traversal, but this Perl has been compiled without it.  You should
+report this warning to the relevant upstream party, or recompile perl
+with default options.
+.IP "This use of \fBmy()\fR in false conditional is no longer allowed" 4
+.IX Item "This use of my() in false conditional is no longer allowed"
+(F) You used a declaration similar to \f(CW\*(C`my $x if 0\*(C'\fR.  There
+has been a long-standing bug in Perl that causes a lexical variable
+not to be cleared at scope exit when its declaration includes a false
+conditional.  Some people have exploited this bug to achieve a kind of
+static variable.  Since we intend to fix this bug, we don't want people
+relying on this behavior.  You can achieve a similar static effect by
+declaring the variable in a separate block outside the function, eg
+.Sp
+.Vb 1
+\&    sub f { my $x if 0; return $x++ }
+.Ve
+.Sp
+becomes
+.Sp
+.Vb 1
+\&    { my $x; sub f { return $x++ } }
+.Ve
+.Sp
+Beginning with perl 5.10.0, you can also use \f(CW\*(C`state\*(C'\fR variables to have
+lexicals that are initialized only once (see feature):
+.Sp
+.Vb 1
+\&    sub f { state $x; return $x++ }
+.Ve
+.Sp
+This use of \f(CWmy()\fR in a false conditional was deprecated beginning in
+Perl 5.10 and became a fatal error in Perl 5.30.
+.IP "Timeout waiting for another thread to define \ep{%s}" 4
+.IX Item "Timeout waiting for another thread to define p{%s}"
+(F) The first time a user-defined property
+("User-Defined Character Properties" in perlunicode) is used, its
+definition is looked up and converted into an internal form for more
+efficient handling in subsequent uses.  There could be a race if two or
+more threads tried to do this processing nearly simultaneously.
+Instead, a critical section is created around this task, locking out all
+but one thread from doing it.  This message indicates that the thread
+that is doing the conversion is taking an unexpectedly long time.  The
+timeout exists solely to prevent deadlock; it's long enough that the
+system was likely thrashing and about to crash.  There is no real remedy but
+rebooting.
+.IP "times not implemented" 4
+.IX Item "times not implemented"
+(F) Your version of the C library apparently doesn't do \fBtimes()\fR.  I
+suspect you're not running on Unix.
+.IP """\-T"" is on the #! line, it must also be used on the command line" 4
+.IX Item """-T"" is on the #! line, it must also be used on the command line"
+(X) The #! line (or local equivalent) in a Perl script contains
+the \fB\-T\fR option (or the \fB\-t\fR option), but Perl was not invoked with
+\&\fB\-T\fR in its command line.  This is an error because, by the time
+Perl discovers a \fB\-T\fR in a script, it's too late to properly taint
+everything from the environment.  So Perl gives up.
+.Sp
+If the Perl script is being executed as a command using the #!
+mechanism (or its local equivalent), this error can usually be
+fixed by editing the #! line so that the \fB\-%c\fR option is a part of
+Perl's first argument: e.g. change \f(CW\*(C`perl \-n \-%c\*(C'\fR to \f(CW\*(C`perl \-%c \-n\*(C'\fR.
+.Sp
+If the Perl script is being executed as \f(CW\*(C`perl scriptname\*(C'\fR, then the
+\&\fB\-%c\fR option must appear on the command line: \f(CW\*(C`perl \-%c scriptname\*(C'\fR.
+.IP "To%s: illegal mapping '%s'" 4
+.IX Item "To%s: illegal mapping '%s'"
+(F) You tried to define a customized To-mapping for \fBlc()\fR, lcfirst,
+\&\fBuc()\fR, or \fBucfirst()\fR (or their string-inlined versions), but you
+specified an illegal mapping.
+See "User-Defined Character Properties" in perlunicode.
+.IP "Too deeply nested ()\-groups" 4
+.IX Item "Too deeply nested ()-groups"
+(F) Your template contains ()\-groups with a ridiculously deep nesting level.
+.IP "Too few args to syscall" 4
+.IX Item "Too few args to syscall"
+(F) There has to be at least one argument to \fBsyscall()\fR to specify the
+system call to call, silly dilly.
+.ie n .IP "Too few arguments for subroutine '%s' (got %d; expected %d)" 4
+.el .IP "Too few arguments for subroutine '%s' (got \f(CW%d\fR; expected \f(CW%d\fR)" 4
+.IX Item "Too few arguments for subroutine '%s' (got %d; expected %d)"
+(F) A subroutine using a signature fewer arguments than required by the
+signature.  The caller of the subroutine is presumably at fault.
+.Sp
+The message attempts to include the name of the called subroutine.  If
+the subroutine has been aliased, the subroutine's original name will be
+shown, regardless of what name the caller used. It will also indicate the
+number of arguments given and the number expected.
+.ie n .IP "Too few arguments for subroutine '%s' (got %d; expected at least %d)" 4
+.el .IP "Too few arguments for subroutine '%s' (got \f(CW%d\fR; expected at least \f(CW%d\fR)" 4
+.IX Item "Too few arguments for subroutine '%s' (got %d; expected at least %d)"
+Similar to the previous message but for subroutines that accept a variable
+number of arguments.
+.IP "Too late for ""\-%s"" option" 4
+.IX Item "Too late for ""-%s"" option"
+(X) The #! line (or local equivalent) in a Perl script contains the
+\&\fB\-M\fR, \fB\-m\fR or \fB\-C\fR option.
+.Sp
+In the case of \fB\-M\fR and \fB\-m\fR, this is an error because those options
+are not intended for use inside scripts.  Use the \f(CW\*(C`use\*(C'\fR pragma instead.
+.Sp
+The \fB\-C\fR option only works if it is specified on the command line as
+well (with the same sequence of letters or numbers following).  Either
+specify this option on the command line, or, if your system supports
+it, make your script executable and run it directly instead of passing
+it to perl.
+.ie n .IP "Too late to run %s block" 4
+.el .IP "Too late to run \f(CW%s\fR block" 4
+.IX Item "Too late to run %s block"
+(W void) A CHECK or INIT block is being defined during run time proper,
+when the opportunity to run them has already passed.  Perhaps you are
+loading a file with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR when you should be using \f(CW\*(C`use\*(C'\fR
+instead.  Or perhaps you should put the \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR inside a
+BEGIN block.
+.IP "Too many args to syscall" 4
+.IX Item "Too many args to syscall"
+(F) Perl supports a maximum of only 14 args to \fBsyscall()\fR.
+.ie n .IP "Too many arguments for %s" 4
+.el .IP "Too many arguments for \f(CW%s\fR" 4
+.IX Item "Too many arguments for %s"
+(F) The function requires fewer arguments than you specified.
+.ie n .IP "Too many arguments for subroutine '%s' (got %d; expected %d)" 4
+.el .IP "Too many arguments for subroutine '%s' (got \f(CW%d\fR; expected \f(CW%d\fR)" 4
+.IX Item "Too many arguments for subroutine '%s' (got %d; expected %d)"
+(F) A subroutine using a signature received more arguments than permitted
+by the signature.  The caller of the subroutine is presumably at fault.
+.Sp
+The message attempts to include the name of the called subroutine. If the
+subroutine has been aliased, the subroutine's original name will be shown,
+regardless of what name the caller used. It will also indicate the number
+of arguments given and the number expected.
+.ie n .IP "Too many arguments for subroutine '%s' (got %d; expected at most %d)" 4
+.el .IP "Too many arguments for subroutine '%s' (got \f(CW%d\fR; expected at most \f(CW%d\fR)" 4
+.IX Item "Too many arguments for subroutine '%s' (got %d; expected at most %d)"
+Similar to the previous message but for subroutines that accept a variable
+number of arguments.
+.IP "Too many nested open parens in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Too many nested open parens in regex; marked by <-- HERE in m/%s/"
+(F) You have exceeded the number of open \f(CW"("\fR parentheses that haven't
+been matched by corresponding closing ones.  This limit prevents eating
+up too much memory.  It is initially set to 1000, but may be changed by
+setting \f(CW\*(C`${^RE_COMPILE_RECURSION_LIMIT}\*(C'\fR to some other value.  This may
+need to be done in a BEGIN block before the regular expression pattern
+is compiled.
+.ie n .IP "Too many nested BEGIN blocks, maximum of %d allowed" 4
+.el .IP "Too many nested BEGIN blocks, maximum of \f(CW%d\fR allowed" 4
+.IX Item "Too many nested BEGIN blocks, maximum of %d allowed"
+(F) You have executed code that nests too many BEGIN blocks inside of
+each other, either explicitly as BEGIN{} or implicitly as use statements.
+This limit defaults to a rather high number which should not be exceeded
+in normal circumstances, and triggering likely indicates something is
+very wrong in your code. For instance infinite recursion of eval and
+BEGIN blocks is known to trigger this error.
+.Sp
+If you know that you have good reason to exceed the limit you can change
+it by setting \f(CW\*(C`${^MAX_NESTED_EVAL_BEGIN_BLOCKS}\*(C'\fR to a different value from
+the default of 1000.
+.ie n .IP "Too many capture groups (limit is %d) in regex m/%s/" 4
+.el .IP "Too many capture groups (limit is \f(CW%d\fR) in regex m/%s/" 4
+.IX Item "Too many capture groups (limit is %d) in regex m/%s/"
+(F) You have too many capture groups in your regex pattern. You need to rework
+your pattern to use less capture groups.
+.IP "Too many )'s" 4
+.IX Item "Too many )'s"
+(A) You've accidentally run your script through \fBcsh\fR instead of Perl.
+Check the #! line, or manually feed your script into Perl yourself.
+.IP "Too many ('s" 4
+.IX Item "Too many ('s"
+(A) You've accidentally run your script through \fBcsh\fR instead of Perl.
+Check the #! line, or manually feed your script into Perl yourself.
+.IP "Trailing \e in regex m/%s/" 4
+.IX Item "Trailing in regex m/%s/"
+(F) The regular expression ends with an unbackslashed backslash.
+Backslash it.   See perlre.
+.IP "Transliteration pattern not terminated" 4
+.IX Item "Transliteration pattern not terminated"
+(F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
+or y/// or y[][] construct.  Missing the leading \f(CW\*(C`$\*(C'\fR from variables
+\&\f(CW$tr\fR or \f(CW$y\fR may cause this error.
+.IP "Transliteration replacement not terminated" 4
+.IX Item "Transliteration replacement not terminated"
+(F) The lexer couldn't find the final delimiter of a tr///, tr[][],
+y/// or y[][] construct.
+.ie n .IP "Treating %s::INIT block as BEGIN block as workaround" 4
+.el .IP "Treating \f(CW%s::INIT\fR block as BEGIN block as workaround" 4
+.IX Item "Treating %s::INIT block as BEGIN block as workaround"
+(S) A package is using an old version of \f(CW\*(C`Module::Install::DSL\*(C'\fR to
+install, which makes unsafe assumptions about when INIT blocks will be
+called. Because \f(CW\*(C`Module::Install::DSL\*(C'\fR is used to install other modules
+and is difficult to upgrade we have a special workaround in place to
+deal with this. Unless you are a maintainer of an affected module you
+can ignore this warning. We emit it only as a sanity check.
+.IP "'%s' trapped by operation mask" 4
+.IX Item "'%s' trapped by operation mask"
+(F) You tried to use an operator from a Safe compartment in which it's
+disallowed.  See Safe.
+.IP "truncate not implemented" 4
+.IX Item "truncate not implemented"
+(F) Your machine doesn't implement a file truncation mechanism that
+Configure knows about.
+.IP "try/catch is experimental" 4
+.IX Item "try/catch is experimental"
+(S experimental::try) This warning is emitted if you use the \f(CW\*(C`try\*(C'\fR and
+\&\f(CW\*(C`catch\*(C'\fR syntax. This syntax is currently experimental and its behaviour may
+change in future releases of Perl.
+.IP "try/catch/finally is experimental" 4
+.IX Item "try/catch/finally is experimental"
+(S experimental::try) This warning is emitted if you use the \f(CW\*(C`try\*(C'\fR and
+\&\f(CW\*(C`catch\*(C'\fR syntax with a \f(CW\*(C`finally\*(C'\fR block. This syntax is currently experimental
+and its behaviour may change in future releases of Perl.
+.ie n .IP "Type of arg %d to &CORE::%s must be %s" 4
+.el .IP "Type of arg \f(CW%d\fR to &CORE::%s must be \f(CW%s\fR" 4
+.IX Item "Type of arg %d to &CORE::%s must be %s"
+(F) The subroutine in question in the CORE package requires its argument
+to be a hard reference to data of the specified type.  Overloading is
+ignored, so a reference to an object that is not the specified type, but
+nonetheless has overloading to handle it, will still not be accepted.
+.ie n .IP "Type of arg %d to %s must be %s (not %s)" 4
+.el .IP "Type of arg \f(CW%d\fR to \f(CW%s\fR must be \f(CW%s\fR (not \f(CW%s\fR)" 4
+.IX Item "Type of arg %d to %s must be %s (not %s)"
+(F) This function requires the argument in that position to be of a
+certain type.  Arrays must be \f(CW@NAME\fR or \f(CW\*(C`@{EXPR}\*(C'\fR.  Hashes must be
+\&\f(CW%NAME\fR or \f(CW\*(C`%{EXPR}\*(C'\fR.  No implicit dereferencing is allowed\-\-use the
+{EXPR} forms as an explicit dereference.  See perlref.
+.IP "umask not implemented" 4
+.IX Item "umask not implemented"
+(F) Your machine doesn't implement the umask function and you tried to
+use it to restrict permissions for yourself (EXPR & 0700).
+.ie n .IP "Unbalanced context: %d more PUSHes than POPs" 4
+.el .IP "Unbalanced context: \f(CW%d\fR more PUSHes than POPs" 4
+.IX Item "Unbalanced context: %d more PUSHes than POPs"
+(S internal) The exit code detected an internal inconsistency in how
+many execution contexts were entered and left.
+.ie n .IP "Unbalanced saves: %d more saves than restores" 4
+.el .IP "Unbalanced saves: \f(CW%d\fR more saves than restores" 4
+.IX Item "Unbalanced saves: %d more saves than restores"
+(S internal) The exit code detected an internal inconsistency in how
+many values were temporarily localized.
+.ie n .IP "Unbalanced scopes: %d more ENTERs than LEAVEs" 4
+.el .IP "Unbalanced scopes: \f(CW%d\fR more ENTERs than LEAVEs" 4
+.IX Item "Unbalanced scopes: %d more ENTERs than LEAVEs"
+(S internal) The exit code detected an internal inconsistency in how
+many blocks were entered and left.
+.IP "Unbalanced string table refcount: (%d) for ""%s""" 4
+.IX Item "Unbalanced string table refcount: (%d) for ""%s"""
+(S internal) On exit, Perl found some strings remaining in the shared
+string table used for copy on write and for hash keys.  The entries
+should have been freed, so this indicates a bug somewhere.
+.ie n .IP "Unbalanced tmps: %d more allocs than frees" 4
+.el .IP "Unbalanced tmps: \f(CW%d\fR more allocs than frees" 4
+.IX Item "Unbalanced tmps: %d more allocs than frees"
+(S internal) The exit code detected an internal inconsistency in how
+many mortal scalars were allocated and freed.
+.IP "Undefined format ""%s"" called" 4
+.IX Item "Undefined format ""%s"" called"
+(F) The format indicated doesn't seem to exist.  Perhaps it's really in
+another package?  See perlform.
+.IP "Undefined sort subroutine ""%s"" called" 4
+.IX Item "Undefined sort subroutine ""%s"" called"
+(F) The sort comparison routine specified doesn't seem to exist.
+Perhaps it's in a different package?  See "sort" in perlfunc.
+.IP "Undefined subroutine &%s called" 4
+.IX Item "Undefined subroutine &%s called"
+(F) The subroutine indicated hasn't been defined, or if it was, it has
+since been undefined.
+.IP "Undefined subroutine called" 4
+.IX Item "Undefined subroutine called"
+(F) The anonymous subroutine you're trying to call hasn't been defined,
+or if it was, it has since been undefined.
+.IP "Undefined subroutine in sort" 4
+.IX Item "Undefined subroutine in sort"
+(F) The sort comparison routine specified is declared but doesn't seem
+to have been defined yet.  See "sort" in perlfunc.
+.IP "Undefined top format ""%s"" called" 4
+.IX Item "Undefined top format ""%s"" called"
+(F) The format indicated doesn't seem to exist.  Perhaps it's really in
+another package?  See perlform.
+.IP "Undefined value assigned to typeglob" 4
+.IX Item "Undefined value assigned to typeglob"
+(W misc) An undefined value was assigned to a typeglob, a la
+\&\f(CW\*(C`*foo = undef\*(C'\fR.  This does nothing.  It's possible that you really mean
+\&\f(CW\*(C`undef *foo\*(C'\fR.
+.ie n .IP "%s: Undefined variable" 4
+.el .IP "\f(CW%s:\fR Undefined variable" 4
+.IX Item "%s: Undefined variable"
+(A) You've accidentally run your script through \fBcsh\fR instead of Perl.
+Check the #! line, or manually feed your script into Perl yourself.
+.IP "Unescaped left brace in regex is illegal here in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unescaped left brace in regex is illegal here in regex; marked by <--\ HERE in m/%s/"
+(F) The simple rule to remember, if you want to
+match a literal \f(CW"{"\fR character (U+007B \f(CW\*(C`LEFT CURLY BRACKET\*(C'\fR) in a
+regular expression pattern, is to escape each literal instance of it in
+some way.  Generally easiest is to precede it with a backslash, like
+\&\f(CW"\e{"\fR or enclose it in square brackets (\f(CW"[{]"\fR).  If the pattern
+delimiters are also braces, any matching right brace (\f(CW"}"\fR) should
+also be escaped to avoid confusing the parser, for example,
+.Sp
+.Vb 1
+\& qr{abc\e{def\e}ghi}
+.Ve
+.Sp
+Forcing literal \f(CW"{"\fR characters to be escaped enables the Perl
+language to be extended in various ways in future releases.  To avoid
+needlessly breaking existing code, the restriction is not enforced in
+contexts where there are unlikely to ever be extensions that could
+conflict with the use there of \f(CW"{"\fR as a literal.  Those that are
+not potentially ambiguous do not warn; those that are do raise a
+non-deprecation warning.
+.Sp
+The contexts where no warnings or errors are raised are:
+.RS 4
+.IP \(bu 4
+as the first character in a pattern, or following \f(CW"^"\fR indicating to
+anchor the match to the beginning of a line.
+.IP \(bu 4
+as the first character following a \f(CW"|"\fR indicating alternation.
+.IP \(bu 4
+as the first character in a parenthesized grouping like
+.Sp
+.Vb 2
+\& /foo({bar)/
+\& /foo(?:{bar)/
+.Ve
+.IP \(bu 4
+as the first character following a quantifier
+.Sp
+.Vb 1
+\& /\es*{/
+.Ve
+.RE
+.RS 4
+.RE
+.IP "Unescaped left brace in regex is passed through in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unescaped left brace in regex is passed through in regex; marked by <--\ HERE in m/%s/"
+(W regexp)  The simple rule to remember, if you want to
+match a literal \f(CW"{"\fR character (U+007B \f(CW\*(C`LEFT CURLY BRACKET\*(C'\fR) in a
+regular expression pattern, is to escape each literal instance of it in
+some way.  Generally easiest is to precede it with a backslash, like
+\&\f(CW"\e{"\fR or enclose it in square brackets (\f(CW"[{]"\fR).  If the pattern
+delimiters are also braces, any matching right brace (\f(CW"}"\fR) should
+also be escaped to avoid confusing the parser, for example,
+.Sp
+.Vb 1
+\& qr{abc\e{def\e}ghi}
+.Ve
+.Sp
+Forcing literal \f(CW"{"\fR characters to be escaped enables the Perl
+language to be extended in various ways in future releases.  To avoid
+needlessly breaking existing code, the restriction is not enforced in
+contexts where there are unlikely to ever be extensions that could
+conflict with the use there of \f(CW"{"\fR as a literal.  Those that are
+not potentially ambiguous do not warn; those that are raise this
+warning.  This makes sure that an inadvertent typo doesn't silently
+cause the pattern to compile to something unintended.
+.Sp
+The contexts where no warnings or errors are raised are:
+.RS 4
+.IP \(bu 4
+as the first character in a pattern, or following \f(CW"^"\fR indicating to
+anchor the match to the beginning of a line.
+.IP \(bu 4
+as the first character following a \f(CW"|"\fR indicating alternation.
+.IP \(bu 4
+as the first character in a parenthesized grouping like
+.Sp
+.Vb 2
+\& /foo({bar)/
+\& /foo(?:{bar)/
+.Ve
+.IP \(bu 4
+as the first character following a quantifier
+.Sp
+.Vb 1
+\& /\es*{/
+.Ve
+.RE
+.RS 4
+.RE
+.IP "Unescaped literal '%c' in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unescaped literal '%c' in regex; marked by <-- HERE in m/%s/"
+(W regexp) (only under \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR)
+.Sp
+Within the scope of \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR in a regular expression
+pattern, you included an unescaped \f(CW\*(C`}\*(C'\fR or \f(CW\*(C`]\*(C'\fR which was interpreted
+literally.  These two characters are sometimes metacharacters, and
+sometimes literals, depending on what precedes them in the
+pattern.  This is unlike the similar \f(CW\*(C`)\*(C'\fR which is always a
+metacharacter unless escaped.
+.Sp
+This action at a distance, perhaps a large distance, can lead to Perl
+silently misinterpreting what you meant, so when you specify that you
+want extra checking by \f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR, this warning is generated.
+If you meant the character as a literal, simply confirm that to Perl by
+preceding the character with a backslash, or make it into a bracketed
+character class (like \f(CW\*(C`[}]\*(C'\fR).  If you meant it as closing a
+corresponding \f(CW\*(C`[\*(C'\fR or \f(CW\*(C`{\*(C'\fR, you'll need to look back through the pattern
+to find out why that isn't happening.
+.ie n .IP "unexec of %s into %s failed!" 4
+.el .IP "unexec of \f(CW%s\fR into \f(CW%s\fR failed!" 4
+.IX Item "unexec of %s into %s failed!"
+(F) The \fBunexec()\fR routine failed for some reason.  See your local FSF
+representative, who probably put it there in the first place.
+.IP "Unexpected binary operator '%c' with no preceding operand in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unexpected binary operator '%c' with no preceding operand in regex; marked by <--\ HERE in m/%s/"
+(F) You had something like this:
+.Sp
+.Vb 1
+\& (?[ | \ep{Digit} ])
+.Ve
+.Sp
+where the \f(CW"|"\fR is a binary operator with an operand on the right, but
+no operand on the left.
+.IP "Unexpected character in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unexpected character in regex; marked by <--\ HERE in m/%s/"
+(F) You had something like this:
+.Sp
+.Vb 1
+\& (?[ z ])
+.Ve
+.Sp
+Within \f(CW\*(C`(?[ ])\*(C'\fR, no literal characters are allowed unless they are
+within an inner pair of square brackets, like
+.Sp
+.Vb 1
+\& (?[ [ z ] ])
+.Ve
+.Sp
+Another possibility is that you forgot a backslash.  Perl isn't smart
+enough to figure out what you really meant.
+.ie n .IP "Unexpected characters while parsing class :isa attribute: %s" 4
+.el .IP "Unexpected characters while parsing class :isa attribute: \f(CW%s\fR" 4
+.IX Item "Unexpected characters while parsing class :isa attribute: %s"
+(F) You tried to specify something other than a single class name with an
+optional trailing verison number as the value for a \f(CW\*(C`class\*(C'\fR \f(CW\*(C`:isa\*(C'\fR
+attribute.  This confused the parser.
+.ie n .IP "Unexpected exit %u" 4
+.el .IP "Unexpected exit \f(CW%u\fR" 4
+.IX Item "Unexpected exit %u"
+(S) \fBexit()\fR was called or the script otherwise finished gracefully when
+\&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR was set in \f(CW\*(C`PL_exit_flags\*(C'\fR.
+.ie n .IP "Unexpected exit failure %d" 4
+.el .IP "Unexpected exit failure \f(CW%d\fR" 4
+.IX Item "Unexpected exit failure %d"
+(S) An uncaught \fBdie()\fR was called when \f(CW\*(C`PERL_EXIT_WARN\*(C'\fR was set in
+\&\f(CW\*(C`PL_exit_flags\*(C'\fR.
+.IP "Unexpected ')' in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unexpected ')' in regex; marked by <--\ HERE in m/%s/"
+(F) You had something like this:
+.Sp
+.Vb 1
+\& (?[ ( \ep{Digit} + ) ])
+.Ve
+.Sp
+The \f(CW")"\fR is out-of-place.  Something apparently was supposed to
+be combined with the digits, or the \f(CW"+"\fR shouldn't be there, or
+something like that.  Perl can't figure out what was intended.
+.IP "Unexpected ']' with no following ')' in (?[... in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unexpected ']' with no following ')' in (?[... in regex; marked by <-- HERE in m/%s/"
+(F) While parsing an extended character class a ']' character was
+encountered at a point in the definition where the only legal use of
+\&']' is to close the character class definition as part of a '])', you
+may have forgotten the close paren, or otherwise confused the parser.
+.IP "Unexpected '(' with no preceding operator in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unexpected '(' with no preceding operator in regex; marked by <--\ HERE in m/%s/"
+(F) You had something like this:
+.Sp
+.Vb 1
+\& (?[ \ep{Digit} ( \ep{Lao} + \ep{Thai} ) ])
+.Ve
+.Sp
+There should be an operator before the \f(CW"("\fR, as there's
+no indication as to how the digits are to be combined
+with the characters in the Lao and Thai scripts.
+.IP "Unicode non-character U+%X is not recommended for open interchange" 4
+.IX Item "Unicode non-character U+%X is not recommended for open interchange"
+(S nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are
+defined by the Unicode standard to be non-characters.  Those
+are legal codepoints, but are reserved for internal use; so,
+applications shouldn't attempt to exchange them.  An application
+may not be expecting any of these characters at all, and receiving
+them may lead to bugs.  If you know what you are doing you can
+turn off this warning by \f(CW\*(C`no warnings \*(Aqnonchar\*(Aq;\*(C'\fR.
+.Sp
+This is not really a "severe" error, but it is supposed to be
+raised by default even if warnings are not enabled, and currently
+the only way to do that in Perl is to mark it as serious.
+.IP "Unicode property wildcard not terminated" 4
+.IX Item "Unicode property wildcard not terminated"
+(F) A Unicode property wildcard looks like a delimited regular
+expression pattern (all within the braces of the enclosing \f(CW\*(C`\ep{...}\*(C'\fR.
+The closing delimtter to match the opening one was not found.  If the
+opening one is escaped by preceding it with a backslash, the closing one
+must also be so escaped.
+.IP "Unicode string properties are not implemented in (?[...]) in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unicode string properties are not implemented in (?[...]) in regex; marked by <-- HERE in m/%s/"
+(F) A Unicode string property is one which expands to a sequence of
+multiple characters.  An example is \f(CW\*(C`\ep{name=KATAKANA LETTER AINU P}\*(C'\fR,
+which is comprised of the sequence \f(CW\*(C`\eN{KATAKANA LETTER SMALL H}\*(C'\fR
+followed by \f(CW\*(C`\eN{COMBINING KATAKANA\-HIRAGANA SEMI\-VOICED SOUND MARK}\*(C'\fR.
+Extended character classes, \f(CW\*(C`(?[...])\*(C'\fR currently cannot handle these.
+.IP "Unicode surrogate U+%X is illegal in UTF\-8" 4
+.IX Item "Unicode surrogate U+%X is illegal in UTF-8"
+(S surrogate) You had a UTF\-16 surrogate in a context where they are
+not considered acceptable.  These code points, between U+D800 and
+U+DFFF (inclusive), are used by Unicode only for UTF\-16.  However, Perl
+internally allows all unsigned integer code points (up to the size limit
+available on your platform), including surrogates.  But these can cause
+problems when being input or output, which is likely where this message
+came from.  If you really really know what you are doing you can turn
+off this warning by \f(CW\*(C`no warnings \*(Aqsurrogate\*(Aq;\*(C'\fR.
+.IP Unimplemented 4
+.IX Item "Unimplemented"
+(F) In Perl 5.12 and above, you have executed an
+ellipsis statement.  This is a
+bare \f(CW\*(C`...;\*(C'\fR, meant to be used to allow you to outline code that
+is to be written, but is not complete, similar to the following:
+.Sp
+.Vb 4
+\&    sub not_done_yet {
+\&      my($self, $arg1, $arg2) = @_;
+\&      ...
+\&    }
+.Ve
+.Sp
+If \f(CWnot_done_yet()\fR is called, Perl will die with an \f(CW\*(C`Unimplemented\*(C'\fR error
+at the line containing \f(CW\*(C`...\*(C'\fR.
+.IP "Unknown charname '%s'" 4
+.IX Item "Unknown charname '%s'"
+(F) The name you used inside \f(CW\*(C`\eN{}\*(C'\fR is unknown to Perl.  Check the
+spelling.  You can say \f(CW\*(C`use charnames ":loose"\*(C'\fR to not have to be
+so precise about spaces, hyphens, and capitalization on standard Unicode
+names.  (Any custom aliases that have been created must be specified
+exactly, regardless of whether \f(CW\*(C`:loose\*(C'\fR is used or not.)  This error may
+also happen if the \f(CW\*(C`\eN{}\*(C'\fR is not in the scope of the corresponding
+\&\f(CW\*(C`use\ charnames\*(C'\fR.
+.IP "Unknown '(*...)' construct '%s' in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unknown '(*...)' construct '%s' in regex; marked by <-- HERE in m/%s/"
+(F) The \f(CW\*(C`(*\*(C'\fR was followed by something that the regular expression
+compiler does not recognize.  Check your spelling.
+.IP "Unknown error" 4
+.IX Item "Unknown error"
+(P) Perl was about to print an error message in \f(CW$@\fR, but the \f(CW$@\fR variable
+did not exist, even after an attempt to create it.
+.ie n .IP "Unknown locale category %d" 4
+.el .IP "Unknown locale category \f(CW%d\fR" 4
+.IX Item "Unknown locale category %d"
+.PD 0
+.ie n .IP "Unknown locale category %d; can't set it to %s" 4
+.el .IP "Unknown locale category \f(CW%d\fR; can't set it to \f(CW%s\fR" 4
+.IX Item "Unknown locale category %d; can't set it to %s"
+.PD
+(W locale) You used a locale category that perl doesn't recognize, so it
+cannot carry out your request.  Check that you are using a valid
+category.  If so, see "Multi-threaded" in perllocale for advice on
+reporting this as a bug, and for modifying perl locally to accommodate
+your needs.
+.IP "Unknown \fBopen()\fR mode '%s'" 4
+.IX Item "Unknown open() mode '%s'"
+(F) The second argument of 3\-argument \fBopen()\fR is not among the list
+of valid modes: \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`+<\*(C'\fR,
+\&\f(CW\*(C`+>\*(C'\fR, \f(CW\*(C`+>>\*(C'\fR, \f(CW\*(C`\-|\*(C'\fR, \f(CW\*(C`|\-\*(C'\fR, \f(CW\*(C`<&\*(C'\fR, \f(CW\*(C`>&\*(C'\fR.
+.IP "Unknown PerlIO layer ""%s""" 4
+.IX Item "Unknown PerlIO layer ""%s"""
+(W layer) An attempt was made to push an unknown layer onto the Perl I/O
+system.  (Layers take care of transforming data between external and
+internal representations.)  Note that some layers, such as \f(CW\*(C`mmap\*(C'\fR,
+are not supported in all environments.  If your program didn't
+explicitly request the failing operation, it may be the result of the
+value of the environment variable PERLIO.
+.ie n .IP "Unknown process %x sent message to prime_env_iter: %s" 4
+.el .IP "Unknown process \f(CW%x\fR sent message to prime_env_iter: \f(CW%s\fR" 4
+.IX Item "Unknown process %x sent message to prime_env_iter: %s"
+(P) An error peculiar to VMS.  Perl was reading values for \f(CW%ENV\fR before
+iterating over it, and someone else stuck a message in the stream of
+data Perl expected.  Someone's very confused, or perhaps trying to
+subvert Perl's population of \f(CW%ENV\fR for nefarious purposes.
+.IP "Unknown regexp modifier ""/%s""" 4
+.IX Item "Unknown regexp modifier ""/%s"""
+(F) Alphanumerics immediately following the closing delimiter
+of a regular expression pattern are interpreted by Perl as modifier
+flags for the regex.  One of the ones you specified is invalid.  One way
+this can happen is if you didn't put in white space between the end of
+the regex and a following alphanumeric operator:
+.Sp
+.Vb 1
+\& if ($a =~ /foo/and $bar == 3) { ... }
+.Ve
+.Sp
+The \f(CW"a"\fR is a valid modifier flag, but the \f(CW"n"\fR is not, and raises
+this error.  Likely what was meant instead was:
+.Sp
+.Vb 1
+\& if ($a =~ /foo/ and $bar == 3) { ... }
+.Ve
+.ie n .IP "Unknown ""re"" subpragma '%s' (known ones are: %s)" 4
+.el .IP "Unknown ""re"" subpragma '%s' (known ones are: \f(CW%s\fR)" 4
+.IX Item "Unknown ""re"" subpragma '%s' (known ones are: %s)"
+(W) You tried to use an unknown subpragma of the "re" pragma.
+.IP "Unknown switch condition (?(...)) in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unknown switch condition (?(...)) in regex; marked by <--\ HERE in m/%s/"
+(F) The condition part of a (?(condition)if\-clause|else\-clause) construct
+is not known.  The condition must be one of the following:
+.Sp
+.Vb 10
+\& (1) (2) ...            true if 1st, 2nd, etc., capture matched
+\& (<NAME>) (\*(AqNAME\*(Aq)      true if named capture matched
+\& (?=...) (?<=...)       true if subpattern matches
+\& (*pla:...) (*plb:...)  true if subpattern matches; also
+\&                             (*positive_lookahead:...)
+\&                             (*positive_lookbehind:...)
+\& (*nla:...) (*nlb:...)  true if subpattern fails to match; also
+\&                             (*negative_lookahead:...)
+\&                             (*negative_lookbehind:...)
+\& (?{ CODE })            true if code returns a true value
+\& (R)                    true if evaluating inside recursion
+\& (R1) (R2) ...          true if directly inside capture group 1, 2,
+\&                             etc.
+\& (R&NAME)               true if directly inside named capture
+\& (DEFINE)               always false; for defining named subpatterns
+.Ve
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  See perlre.
+.IP "Unknown Unicode option letter '%c'" 4
+.IX Item "Unknown Unicode option letter '%c'"
+(F) You specified an unknown Unicode option.  See
+perlrun documentation of the \f(CW\*(C`\-C\*(C'\fR switch
+for the list of known options.
+.ie n .IP "Unknown Unicode option value %d" 4
+.el .IP "Unknown Unicode option value \f(CW%d\fR" 4
+.IX Item "Unknown Unicode option value %d"
+(F) You specified an unknown Unicode option.  See
+perlrun documentation of the \f(CW\*(C`\-C\*(C'\fR switch
+for the list of known options.
+.IP "Unknown user-defined property name \ep{%s}" 4
+.IX Item "Unknown user-defined property name p{%s}"
+(F) You specified to use a property within the \f(CW\*(C`\ep{...}\*(C'\fR which was a
+syntactically valid user-defined property, but no definition was found
+for it by the time one was required to proceed.  Check your spelling.
+See "User-Defined Character Properties" in perlunicode.
+.IP "Unknown verb pattern '%s' in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unknown verb pattern '%s' in regex; marked by <--\ HERE in m/%s/"
+(F) You either made a typo or have incorrectly put a \f(CW\*(C`*\*(C'\fR quantifier
+after an open brace in your pattern.  Check the pattern and review
+perlre for details on legal verb patterns.
+.IP "Unknown warnings category '%s'" 4
+.IX Item "Unknown warnings category '%s'"
+(F) An error issued by the \f(CW\*(C`warnings\*(C'\fR pragma.  You specified a warnings
+category that is unknown to perl at this point.
+.Sp
+Note that if you want to enable a warnings category registered by a
+module (e.g. \f(CW\*(C`use warnings \*(AqFile::Find\*(Aq\*(C'\fR), you must have loaded this
+module first.
+.IP "Unmatched [ in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unmatched [ in regex; marked by <--\ HERE in m/%s/"
+(F) The brackets around a character class must match.  If you wish to
+include a closing bracket in a character class, backslash it or put it
+first.  The <\-\-\ HERE shows whereabouts in the regular expression the
+problem was discovered.  See perlre.
+.IP "Unmatched ( in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unmatched ( in regex; marked by <--\ HERE in m/%s/"
+.PD 0
+.IP "Unmatched ) in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unmatched ) in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) Unbackslashed parentheses must always be balanced in regular
+expressions.  If you're a vi user, the % key is valuable for finding
+the matching parenthesis.  The <\-\-\ HERE shows whereabouts in the
+regular expression the problem was discovered.  See perlre.
+.ie n .IP "Unmatched right %s bracket" 4
+.el .IP "Unmatched right \f(CW%s\fR bracket" 4
+.IX Item "Unmatched right %s bracket"
+(F) The lexer counted more closing curly or square brackets than opening
+ones, so you're probably missing a matching opening bracket.  As a
+general rule, you'll find the missing one (so to speak) near the place
+you were last editing.
+.IP "Unquoted string ""%s"" may clash with future reserved word" 4
+.IX Item "Unquoted string ""%s"" may clash with future reserved word"
+(W reserved) You used a bareword that might someday be claimed as a
+reserved word.  It's best to put such a word in quotes, or capitalize it
+somehow, or insert an underbar into it.  You might also declare it as a
+subroutine.
+.ie n .IP "Unrecognized character %s; marked by <\-\-\ HERE after %s near column %d" 4
+.el .IP "Unrecognized character \f(CW%s\fR; marked by <\-\-\ HERE after \f(CW%s\fR near column \f(CW%d\fR" 4
+.IX Item "Unrecognized character %s; marked by <--\ HERE after %s near column %d"
+(F) The Perl parser has no idea what to do with the specified character
+in your Perl script (or eval) near the specified column.  Perhaps you
+tried  to run a compressed script, a binary program, or a directory as
+a Perl program.
+.ie n .IP "Unrecognized class attribute %s" 4
+.el .IP "Unrecognized class attribute \f(CW%s\fR" 4
+.IX Item "Unrecognized class attribute %s"
+(F) You attempted to add a named attribute to a \f(CW\*(C`class\*(C'\fR definition, but
+perl does not recognise the name of the requested attribute.
+.IP "Unrecognized escape \e%c in character class in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unrecognized escape %c in character class in regex; marked by <--\ HERE in m/%s/"
+(F) You used a backslash-character combination which is not
+recognized by Perl inside character classes.  This is a fatal
+error when the character class is used within \f(CW\*(C`(?[ ])\*(C'\fR.
+.IP "Unrecognized escape \e%c in character class passed through in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unrecognized escape %c in character class passed through in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You used a backslash-character combination which is not
+recognized by Perl inside character classes.  The character was
+understood literally, but this may change in a future version of Perl.
+The <\-\-\ HERE shows whereabouts in the regular expression the
+escape was discovered.
+.IP "Unrecognized escape \e%c passed through" 4
+.IX Item "Unrecognized escape %c passed through"
+(W misc) You used a backslash-character combination which is not
+recognized by Perl.  The character was understood literally, but this may
+change in a future version of Perl.
+.IP "Unrecognized escape \e%s passed through in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unrecognized escape %s passed through in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You used a backslash-character combination which is not
+recognized by Perl.  The character(s) were understood literally, but
+this may change in a future version of Perl.  The <\-\-\ HERE shows
+whereabouts in the regular expression the escape was discovered.
+.ie n .IP "Unrecognized field attribute %s" 4
+.el .IP "Unrecognized field attribute \f(CW%s\fR" 4
+.IX Item "Unrecognized field attribute %s"
+(F) You attempted to add a named attribute to a \f(CW\*(C`field\*(C'\fR definition, but
+perl does not recognise the name of the requested attribute.
+.IP "Unrecognized signal name ""%s""" 4
+.IX Item "Unrecognized signal name ""%s"""
+(F) You specified a signal name to the \fBkill()\fR function that was not
+recognized.  Say \f(CW\*(C`kill \-l\*(C'\fR in your shell to see the valid signal names
+on your system.
+.IP "Unrecognized switch: \-%s  (\-h will show valid options)" 4
+.IX Item "Unrecognized switch: -%s (-h will show valid options)"
+(F) You specified an illegal option to Perl.  Don't do that.  (If you
+think you didn't do that, check the #! line to see if it's supplying the
+bad switch on your behalf.)
+.ie n .IP "Unsuccessful %s on filename containing newline" 4
+.el .IP "Unsuccessful \f(CW%s\fR on filename containing newline" 4
+.IX Item "Unsuccessful %s on filename containing newline"
+(W newline) A file operation was attempted on a filename, and that
+operation failed, PROBABLY because the filename contained a newline,
+PROBABLY because you forgot to \fBchomp()\fR it off.  See "chomp" in perlfunc.
+.IP "Unsupported directory function ""%s"" called" 4
+.IX Item "Unsupported directory function ""%s"" called"
+(F) Your machine doesn't support \fBopendir()\fR and \fBreaddir()\fR.
+.ie n .IP "Unsupported function %s" 4
+.el .IP "Unsupported function \f(CW%s\fR" 4
+.IX Item "Unsupported function %s"
+(F) This machine doesn't implement the indicated function, apparently.
+At least, Configure doesn't think so.
+.IP "Unsupported function fork" 4
+.IX Item "Unsupported function fork"
+(F) Your version of executable does not support forking.
+.Sp
+Note that under some systems, like OS/2, there may be different flavors
+of Perl executables, some of which may support fork, some not.  Try
+changing the name you call Perl by to \f(CW\*(C`perl_\*(C'\fR, \f(CW\*(C`perl_\|_\*(C'\fR, and so on.
+.ie n .IP "Unsupported script encoding %s" 4
+.el .IP "Unsupported script encoding \f(CW%s\fR" 4
+.IX Item "Unsupported script encoding %s"
+(F) Your program file begins with a Unicode Byte Order Mark (BOM) which
+declares it to be in a Unicode encoding that Perl cannot read.
+.IP "Unsupported socket function ""%s"" called" 4
+.IX Item "Unsupported socket function ""%s"" called"
+(F) Your machine doesn't support the Berkeley socket mechanism, or at
+least that's what Configure thought.
+.IP "Unterminated '(*...' argument in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unterminated '(*...' argument in regex; marked by <-- HERE in m/%s/"
+(F) You used a pattern of the form \f(CW\*(C`(*...:...)\*(C'\fR but did not terminate
+the pattern with a \f(CW\*(C`)\*(C'\fR.  Fix the pattern and retry.
+.IP "Unterminated attribute list" 4
+.IX Item "Unterminated attribute list"
+(F) The lexer found something other than a simple identifier at the
+start of an attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous
+attribute too soon.  See attributes.
+.IP "Unterminated attribute parameter in attribute list" 4
+.IX Item "Unterminated attribute parameter in attribute list"
+(F) The lexer saw an opening (left) parenthesis character while parsing
+an attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.  See attributes.
+.IP "Unterminated compressed integer" 4
+.IX Item "Unterminated compressed integer"
+(F) An argument to unpack("w",...) was incompatible with the BER
+compressed integer format and could not be converted to an integer.
+See "pack" in perlfunc.
+.IP "Unterminated '(*...' construct in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Unterminated '(*...' construct in regex; marked by <-- HERE in m/%s/"
+(F) You used a pattern of the form \f(CW\*(C`(*...)\*(C'\fR but did not terminate
+the pattern with a \f(CW\*(C`)\*(C'\fR.  Fix the pattern and retry.
+.IP "Unterminated delimiter for here document" 4
+.IX Item "Unterminated delimiter for here document"
+(F) This message occurs when a here document label has an initial
+quotation mark but the final quotation mark is missing.  Perhaps
+you wrote:
+.Sp
+.Vb 1
+\&    <<"foo
+.Ve
+.Sp
+instead of:
+.Sp
+.Vb 1
+\&    <<"foo"
+.Ve
+.IP "Unterminated \eg... pattern in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unterminated g... pattern in regex; marked by <--\ HERE in m/%s/"
+.PD 0
+.IP "Unterminated \eg{...} pattern in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unterminated g{...} pattern in regex; marked by <--\ HERE in m/%s/"
+.PD
+(F) In a regular expression, you had a \f(CW\*(C`\eg\*(C'\fR that wasn't followed by a
+proper group reference.  In the case of \f(CW\*(C`\eg{\*(C'\fR, the closing brace is
+missing; otherwise the \f(CW\*(C`\eg\*(C'\fR must be followed by an integer.  Fix the
+pattern and retry.
+.IP "Unterminated <> operator" 4
+.IX Item "Unterminated <> operator"
+(F) The lexer saw a left angle bracket in a place where it was expecting
+a term, so it's looking for the corresponding right angle bracket, and
+not finding it.  Chances are you left some needed parentheses out
+earlier in the line, and you really meant a "less than".
+.IP "Unterminated verb pattern argument in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unterminated verb pattern argument in regex; marked by <--\ HERE in m/%s/"
+(F) You used a pattern of the form \f(CW\*(C`(*VERB:ARG)\*(C'\fR but did not terminate
+the pattern with a \f(CW\*(C`)\*(C'\fR.  Fix the pattern and retry.
+.IP "Unterminated verb pattern in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Unterminated verb pattern in regex; marked by <--\ HERE in m/%s/"
+(F) You used a pattern of the form \f(CW\*(C`(*VERB)\*(C'\fR but did not terminate
+the pattern with a \f(CW\*(C`)\*(C'\fR.  Fix the pattern and retry.
+.ie n .IP "untie attempted while %d inner references still exist" 4
+.el .IP "untie attempted while \f(CW%d\fR inner references still exist" 4
+.IX Item "untie attempted while %d inner references still exist"
+(W untie) A copy of the object returned from \f(CW\*(C`tie\*(C'\fR (or \f(CW\*(C`tied\*(C'\fR) was
+still valid when \f(CW\*(C`untie\*(C'\fR was called.
+.IP "Usage: POSIX::%s(%s)" 4
+.IX Item "Usage: POSIX::%s(%s)"
+(F) You called a POSIX function with incorrect arguments.
+See "FUNCTIONS" in POSIX for more information.
+.IP "Usage: Win32::%s(%s)" 4
+.IX Item "Usage: Win32::%s(%s)"
+(F) You called a Win32 function with incorrect arguments.
+See Win32 for more information.
+.ie n .IP "$[ used in %s (did you mean $] ?)" 4
+.el .IP "$[ used in \f(CW%s\fR (did you mean $] ?)" 4
+.IX Item "$[ used in %s (did you mean $] ?)"
+(W syntax) You used \f(CW$[\fR in a comparison, such as:
+.Sp
+.Vb 3
+\&    if ($[ > 5.006) {
+\&        ...
+\&    }
+.Ve
+.Sp
+You probably meant to use \f(CW$]\fR instead.  \f(CW$[\fR is the base for indexing
+arrays.  \f(CW$]\fR is the Perl version number in decimal.
+.IP "Use ""%s"" instead of ""%s""" 4
+.IX Item "Use ""%s"" instead of ""%s"""
+(F) The second listed construct is no longer legal.  Use the first one
+instead.
+.IP "Useless assignment to a temporary" 4
+.IX Item "Useless assignment to a temporary"
+(W misc) You assigned to an lvalue subroutine, but what
+the subroutine returned was a temporary scalar about to
+be discarded, so the assignment had no effect.
+.IP "Useless (?\-%s) \- don't use /%s modifier in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Useless (?-%s) - don't use /%s modifier in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You have used an internal modifier such as (?\-o) that has no
+meaning unless removed from the entire regexp:
+.Sp
+.Vb 1
+\&    if ($string =~ /(?\-o)$pattern/o) { ... }
+.Ve
+.Sp
+must be written as
+.Sp
+.Vb 1
+\&    if ($string =~ /$pattern/) { ... }
+.Ve
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  See perlre.
+.ie n .IP "Useless localization of %s" 4
+.el .IP "Useless localization of \f(CW%s\fR" 4
+.IX Item "Useless localization of %s"
+(W syntax) The localization of lvalues such as \f(CWlocal($x=10)\fR is legal,
+but in fact the \fBlocal()\fR currently has no effect.  This may change at
+some point in the future, but in the meantime such code is discouraged.
+.IP "Useless (?%s) \- use /%s modifier in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Useless (?%s) - use /%s modifier in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You have used an internal modifier such as (?o) that has no
+meaning unless applied to the entire regexp:
+.Sp
+.Vb 1
+\&    if ($string =~ /(?o)$pattern/) { ... }
+.Ve
+.Sp
+must be written as
+.Sp
+.Vb 1
+\&    if ($string =~ /$pattern/o) { ... }
+.Ve
+.Sp
+The <\-\-\ HERE shows whereabouts in the regular expression the problem was
+discovered.  See perlre.
+.IP "Useless use of attribute ""const""" 4
+.IX Item "Useless use of attribute ""const"""
+(W misc) The \f(CW\*(C`const\*(C'\fR attribute has no effect except
+on anonymous closure prototypes.  You applied it to
+a subroutine via attributes.pm.  This is only useful
+inside an attribute handler for an anonymous subroutine.
+.IP "Useless use of /d modifier in transliteration operator" 4
+.IX Item "Useless use of /d modifier in transliteration operator"
+(W misc) You have used the /d modifier where the searchlist has the
+same length as the replacelist.  See perlop for more information
+about the /d modifier.
+.IP "Useless use of \eE" 4
+.IX Item "Useless use of E"
+(W misc) You have a \eE in a double-quotish string without a \f(CW\*(C`\eU\*(C'\fR,
+\&\f(CW\*(C`\eL\*(C'\fR or \f(CW\*(C`\eQ\*(C'\fR preceding it.
+.IP "Useless use of greediness modifier '%c' in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Useless use of greediness modifier '%c' in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You specified something like these:
+.Sp
+.Vb 2
+\& qr/a{3}?/
+\& qr/b{1,1}+/
+.Ve
+.Sp
+The \f(CW"?"\fR and \f(CW"+"\fR don't have any effect, as they modify whether to
+match more or fewer when there is a choice, and by specifying to match
+exactly a given number, there is no room left for a choice.
+.ie n .IP "Useless use of %s in scalar context" 4
+.el .IP "Useless use of \f(CW%s\fR in scalar context" 4
+.IX Item "Useless use of %s in scalar context"
+(W scalar) You did something whose only interesting return value is a
+list without a side effect in scalar context, which does not accept a
+list.
+.Sp
+For example
+.Sp
+.Vb 1
+\&    my $x = sort @y;
+.Ve
+.Sp
+This is not very useful, and perl currently optimizes this away.
+.ie n .IP "Useless use of %s in void context" 4
+.el .IP "Useless use of \f(CW%s\fR in void context" 4
+.IX Item "Useless use of %s in void context"
+(W void) You did something without a side effect in a context that does
+nothing with the return value, such as a statement that doesn't return a
+value from a block, or the left side of a scalar comma operator.  Very
+often this points not to stupidity on your part, but a failure of Perl
+to parse your program the way you thought it would.  For example, you'd
+get this if you mixed up your C precedence with Python precedence and
+said
+.Sp
+.Vb 1
+\&    $one, $two = 1, 2;
+.Ve
+.Sp
+when you meant to say
+.Sp
+.Vb 1
+\&    ($one, $two) = (1, 2);
+.Ve
+.Sp
+Another common error is to use ordinary parentheses to construct a list
+reference when you should be using square or curly brackets, for
+example, if you say
+.Sp
+.Vb 1
+\&    $array = (1,2);
+.Ve
+.Sp
+when you should have said
+.Sp
+.Vb 1
+\&    $array = [1,2];
+.Ve
+.Sp
+The square brackets explicitly turn a list value into a scalar value,
+while parentheses do not.  So when a parenthesized list is evaluated in
+a scalar context, the comma is treated like C's comma operator, which
+throws away the left argument, which is not what you want.  See
+perlref for more on this.
+.Sp
+This warning will not be issued for numerical constants equal to 0 or 1
+since they are often used in statements like
+.Sp
+.Vb 1
+\&    1 while sub_with_side_effects();
+.Ve
+.Sp
+String constants that would normally evaluate to 0 or 1 are warned
+about.
+.IP "Useless use of (?\-p) in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Useless use of (?-p) in regex; marked by <--\ HERE in m/%s/"
+(W regexp) The \f(CW\*(C`p\*(C'\fR modifier cannot be turned off once set.  Trying to do
+so is futile.
+.IP "Useless use of ""re"" pragma" 4
+.IX Item "Useless use of ""re"" pragma"
+(W) You did \f(CW\*(C`use re;\*(C'\fR without any arguments.  That isn't very useful.
+.ie n .IP "Useless use of %s with no values" 4
+.el .IP "Useless use of \f(CW%s\fR with no values" 4
+.IX Item "Useless use of %s with no values"
+(W syntax) You used the \fBpush()\fR or \fBunshift()\fR function with no arguments
+apart from the array, like \f(CWpush(@x)\fR or \f(CWunshift(@foo)\fR.  That won't
+usually have any effect on the array, so is completely useless.  It's
+possible in principle that push(@tied_array) could have some effect
+if the array is tied to a class which implements a PUSH method.  If so,
+you can write it as \f(CW\*(C`push(@tied_array,())\*(C'\fR to avoid this warning.
+.IP """use"" not allowed in expression" 4
+.IX Item """use"" not allowed in expression"
+(F) The "use" keyword is recognized and executed at compile time, and
+returns no useful value.  See perlmod.
+.ie n .IP "Use of @_ in %s with signatured subroutine is experimental" 4
+.el .IP "Use of \f(CW@_\fR in \f(CW%s\fR with signatured subroutine is experimental" 4
+.IX Item "Use of @_ in %s with signatured subroutine is experimental"
+(S experimental::args_array_with_signatures) An expression involving the
+\&\f(CW@_\fR arguments array was found in a subroutine that uses a signature.
+This is experimental because the interaction between the arguments
+array and parameter handling via signatures is not guaranteed to remain
+stable in any future version of Perl, and such code should be avoided.
+.IP "Use of bare << to mean <<"""" is forbidden" 4
+.IX Item "Use of bare << to mean <<"""" is forbidden"
+(F) You are now required to use the explicitly quoted form if you wish
+to use an empty line as the terminator of the here-document.
+.Sp
+Use of a bare terminator was deprecated in Perl 5.000, and is a fatal
+error as of Perl 5.28.
+.IP "Use of /c modifier is meaningless in s///" 4
+.IX Item "Use of /c modifier is meaningless in s///"
+(W regexp) You used the /c modifier in a substitution.  The /c
+modifier is not presently meaningful in substitutions.
+.IP "Use of /c modifier is meaningless without /g" 4
+.IX Item "Use of /c modifier is meaningless without /g"
+(W regexp) You used the /c modifier with a regex operand, but didn't
+use the /g modifier.  Currently, /c is meaningful only when /g is
+used.  (This may change in the future.)
+.IP "Use of code point 0x%s is not allowed; the permissible max is 0x%X" 4
+.IX Item "Use of code point 0x%s is not allowed; the permissible max is 0x%X"
+.PD 0
+.IP "Use of code point 0x%s is not allowed; the permissible max is 0x%X in regex; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Use of code point 0x%s is not allowed; the permissible max is 0x%X in regex; marked by <-- HERE in m/%s/"
+.PD
+(F) You used a code point that is not allowed, because it is too large.
+Unicode only allows code points up to 0x10FFFF, but Perl allows much
+larger ones. Earlier versions of Perl allowed code points above IV_MAX
+(0x7FFFFFF on 32\-bit platforms, 0x7FFFFFFFFFFFFFFF on 64\-bit platforms),
+however, this could possibly break the perl interpreter in some constructs,
+including causing it to hang in a few cases.
+.Sp
+If your code is to run on various platforms, keep in mind that the upper
+limit depends on the platform.  It is much larger on 64\-bit word sizes
+than 32\-bit ones.
+.Sp
+The use of out of range code points was deprecated in Perl 5.24, and
+became a fatal error in Perl 5.28.
+.IP "Use of \fBeach()\fR on hash after insertion without resetting hash iterator results in undefined behavior" 4
+.IX Item "Use of each() on hash after insertion without resetting hash iterator results in undefined behavior"
+(S internal) The behavior of \f(CWeach()\fR after insertion is undefined;
+it may skip items, or visit items more than once.  Consider using
+\&\f(CWkeys()\fR instead of \f(CWeach()\fR.
+.IP "Use of := for an empty attribute list is not allowed" 4
+.IX Item "Use of := for an empty attribute list is not allowed"
+(F) The construction \f(CW\*(C`my $x := 42\*(C'\fR used to parse as equivalent to
+\&\f(CW\*(C`my $x : = 42\*(C'\fR (applying an empty attribute list to \f(CW$x\fR).
+This construct was deprecated in 5.12.0, and has now been made a syntax
+error, so \f(CW\*(C`:=\*(C'\fR can be reclaimed as a new operator in the future.
+.Sp
+If you need an empty attribute list, for example in a code generator, add
+a space before the \f(CW\*(C`=\*(C'\fR.
+.ie n .IP "Use of %s for non\-UTF\-8 locale is wrong.  Assuming a UTF\-8 locale" 4
+.el .IP "Use of \f(CW%s\fR for non\-UTF\-8 locale is wrong.  Assuming a UTF\-8 locale" 4
+.IX Item "Use of %s for non-UTF-8 locale is wrong. Assuming a UTF-8 locale"
+(W locale)  You are matching a regular expression using locale rules,
+and the specified construct was encountered.  This construct is only
+valid for UTF\-8 locales, which the current locale isn't.  This doesn't
+make sense.  Perl will continue, assuming a Unicode (UTF\-8) locale, but
+the results are likely to be wrong.
+.IP "Use of freed value in iteration" 4
+.IX Item "Use of freed value in iteration"
+(F) Perhaps you modified the iterated array within the loop?
+This error is typically caused by code like the following:
+.Sp
+.Vb 2
+\&    @a = (3,4);
+\&    @a = () for (1,2,@a);
+.Ve
+.Sp
+You are not supposed to modify arrays while they are being iterated over.
+For speed and efficiency reasons, Perl internally does not do full
+reference-counting of iterated items, hence deleting such an item in the
+middle of an iteration causes Perl to see a freed value.
+.IP "Use of /g modifier is meaningless in split" 4
+.IX Item "Use of /g modifier is meaningless in split"
+(W regexp) You used the /g modifier on the pattern for a \f(CW\*(C`split\*(C'\fR
+operator.  Since \f(CW\*(C`split\*(C'\fR always tries to match the pattern
+repeatedly, the \f(CW\*(C`/g\*(C'\fR has no effect.
+.IP "Use of ""goto"" to jump into a construct is deprecated" 4
+.IX Item "Use of ""goto"" to jump into a construct is deprecated"
+(D deprecated::goto_construct) Using \f(CW\*(C`goto\*(C'\fR to jump from an outer scope into an inner
+scope is deprecated and should be avoided.
+.Sp
+This was deprecated in Perl 5.12.
+.ie n .IP "Use of '%s' in \ep{} or \eP{} is deprecated because: %s" 4
+.el .IP "Use of '%s' in \ep{} or \eP{} is deprecated because: \f(CW%s\fR" 4
+.IX Item "Use of '%s' in p{} or P{} is deprecated because: %s"
+(D deprecated::unicode_property_name) Certain properties are deprecated
+by Unicode, and may eventually be removed from the Standard, at which
+time Perl will follow along. In the meantime, this message is raised to
+notify you.
+.ie n .IP "Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed" 4
+.el .IP "Use of inherited AUTOLOAD for non-method \f(CW%s::\fR%s() is no longer allowed" 4
+.IX Item "Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed"
+(F) As an accidental feature, \f(CW\*(C`AUTOLOAD\*(C'\fR subroutines were looked up as
+methods (using the \f(CW@ISA\fR hierarchy), even when the subroutines to be
+autoloaded were called as plain functions (e.g. \f(CWFoo::bar()\fR), not as
+methods (e.g. \f(CW\*(C`Foo\->bar()\*(C'\fR or \f(CW\*(C`$obj\->bar()\*(C'\fR).
+.Sp
+This was deprecated in Perl 5.004, and was made fatal in Perl 5.28.
+.ie n .IP "Use of %s in printf format not supported" 4
+.el .IP "Use of \f(CW%s\fR in printf format not supported" 4
+.IX Item "Use of %s in printf format not supported"
+(F) You attempted to use a feature of printf that is accessible from
+only C.  This usually means there's a better way to do it in Perl.
+.IP "Use of '%s' is deprecated as a string delimiter" 4
+.IX Item "Use of '%s' is deprecated as a string delimiter"
+(D deprecated::delimiter_will_be_paired) You used the given character as
+a starting delimiter of a string outside the scope of
+\&\f(CW\*(C`use\ feature\ \*(Aqextra_paired_delimiters\*(Aq\*(C'\fR. This character is the
+mirror image of another Unicode character; within the scope of that
+feature, the two are considered a pair for delimitting strings. It is
+planned to make that feature the default, at which point this usage
+would become illegal; hence this warning.
+.Sp
+For now, you may live with this warning, or turn it off, but this code
+will no longer compile in a future version of Perl.  Or you can turn on
+\&\f(CW\*(C`use\ feature\ \*(Aqextra_paired_delimiters\*(Aq\*(C'\fR and use the character that
+is the mirror image of this one for the closing string delimiter.
+.IP "Use of '%s' is experimental as a string delimiter" 4
+.IX Item "Use of '%s' is experimental as a string delimiter"
+(S experimental::extra_paired_delimiters)   This warning is emitted if
+you use as a string delimiter one of the non-ASCII mirror image ones
+enabled by \f(CW\*(C`use\ feature\ \*(Aqextra_paired_delimiters\*(Aq\*(C'\fR.  Simply suppress
+the warning if you want to use the feature, but know that in doing so
+you are taking the risk of using an experimental feature which may
+change or be removed in a future Perl version:
+.ie n .IP "Use of %s is not allowed in Unicode property wildcard subpatterns in regex; marked by <\-\-\ HERE in m/%s/" 4
+.el .IP "Use of \f(CW%s\fR is not allowed in Unicode property wildcard subpatterns in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Use of %s is not allowed in Unicode property wildcard subpatterns in regex; marked by <--\ HERE in m/%s/"
+(F) You were using a wildcard subpattern a Unicode property value, and
+the subpattern contained something that is illegal.  Not all regular
+expression capabilities are legal in such subpatterns, and this is one.
+Rewrite your subppattern to not use the offending construct.
+See "Wildcards in Property Values" in perlunicode.
+.IP "Use of \-l on filehandle%s" 4
+.IX Item "Use of -l on filehandle%s"
+(W io) A filehandle represents an opened file, and when you opened the file
+it already went past any symlink you are presumably trying to look for.
+The operation returned \f(CW\*(C`undef\*(C'\fR.  Use a filename instead.
+.IP "Use of reference ""%s"" as array index" 4
+.IX Item "Use of reference ""%s"" as array index"
+(W misc) You tried to use a reference as an array index; this probably
+isn't what you mean, because references in numerical context tend
+to be huge numbers, and so usually indicates programmer error.
+.Sp
+If you really do mean it, explicitly numify your reference, like so:
+\&\f(CW$array[0+$ref]\fR.  This warning is not given for overloaded objects,
+however, because you can overload the numification and stringification
+operators and then you presumably know what you are doing.
+.ie n .IP "Use of strings with code points over 0xFF as arguments to %s operator is not allowed" 4
+.el .IP "Use of strings with code points over 0xFF as arguments to \f(CW%s\fR operator is not allowed" 4
+.IX Item "Use of strings with code points over 0xFF as arguments to %s operator is not allowed"
+(F) You tried to use one of the string bitwise operators (\f(CW\*(C`&\*(C'\fR or \f(CW\*(C`|\*(C'\fR or \f(CW\*(C`^\*(C'\fR or
+\&\f(CW\*(C`~\*(C'\fR) on a string containing a code point over 0xFF.  The string bitwise
+operators treat their operands as strings of bytes, and values beyond
+0xFF are nonsensical in this context.
+.Sp
+Certain instances became fatal in Perl 5.28; others in perl 5.32.
+.IP "Use of strings with code points over 0xFF as arguments to vec is forbidden" 4
+.IX Item "Use of strings with code points over 0xFF as arguments to vec is forbidden"
+(F) You tried to use \f(CW\*(C`vec\*(C'\fR
+on a string containing a code point over 0xFF, which is nonsensical here.
+.Sp
+This became fatal in Perl 5.32.
+.ie n .IP "Use of tainted arguments in %s is deprecated" 4
+.el .IP "Use of tainted arguments in \f(CW%s\fR is deprecated" 4
+.IX Item "Use of tainted arguments in %s is deprecated"
+(W taint, deprecated) You have supplied \f(CWsystem()\fR or \f(CWexec()\fR with multiple
+arguments and at least one of them is tainted.  This used to be allowed
+but will become a fatal error in a future version of perl.  Untaint your
+arguments.  See perlsec.
+.IP "Use of unassigned code point or non-standalone grapheme for a delimiter is not allowed" 4
+.IX Item "Use of unassigned code point or non-standalone grapheme for a delimiter is not allowed"
+(F)
+A grapheme is what appears to a native-speaker of a language to be a
+character.  In Unicode (and hence Perl) a grapheme may actually be
+several adjacent characters that together form a complete grapheme.  For
+example, there can be a base character, like "R" and an accent, like a
+circumflex "^", that appear when displayed to be a single character with
+the circumflex hovering over the "R".  Perl currently allows things like
+that circumflex to be delimiters of strings, patterns, \fIetc\fR.  When
+displayed, the circumflex would look like it belongs to the character
+just to the left of it.  In order to move the language to be able to
+accept graphemes as delimiters, we cannot allow the use of
+delimiters which aren't graphemes by themselves.  Also, a delimiter must
+already be assigned (or known to be never going to be assigned) to try
+to future-proof code, for otherwise code that works today would fail to
+compile if the currently unassigned delimiter ends up being something
+that isn't a stand-alone grapheme.  Because Unicode is never going to
+assign
+non-character code points, nor
+code points that are above the legal Unicode maximum, those can be delimiters, and
+their use is legal.
+.IP "Use of uninitialized value%s" 4
+.IX Item "Use of uninitialized value%s"
+(W uninitialized) An undefined value was used as if it were already
+defined.  It was interpreted as a "" or a 0, but maybe it was a mistake.
+To suppress this warning assign a defined value to your variables.
+.Sp
+To help you figure out what was undefined, perl will try to tell you
+the name of the variable (if any) that was undefined.  In some cases
+it cannot do this, so it also tells you what operation you used the
+undefined value in.  Note, however, that perl optimizes your program
+and the operation displayed in the warning may not necessarily appear
+literally in your program.  For example, \f(CW"that $foo"\fR is usually
+optimized into \f(CW\*(C`"that " . $foo\*(C'\fR, and the warning will refer to the
+\&\f(CW\*(C`concatenation (.)\*(C'\fR operator, even though there is no \f(CW\*(C`.\*(C'\fR in
+your program.
+.IP """use re 'strict'"" is experimental" 4
+.IX Item """use re 'strict'"" is experimental"
+(S experimental::re_strict) The things that are different when a regular
+expression pattern is compiled under \f(CW\*(Aqstrict\*(Aq\fR are subject to change
+in future Perl releases in incompatible ways.  This means that a pattern
+that compiles today may not in a future Perl release.  This warning is
+to alert you to that risk.
+.IP "Use \ex{...} for more than two hex characters in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Use x{...} for more than two hex characters in regex; marked by <--\ HERE in m/%s/"
+(F) In a regular expression, you said something like
+.Sp
+.Vb 1
+\& (?[ [ \exBEEF ] ])
+.Ve
+.Sp
+Perl isn't sure if you meant this
+.Sp
+.Vb 1
+\& (?[ [ \ex{BEEF} ] ])
+.Ve
+.Sp
+or if you meant this
+.Sp
+.Vb 1
+\& (?[ [ \ex{BE} E F ] ])
+.Ve
+.Sp
+You need to add either braces or blanks to disambiguate.
+.IP "Using just the first character returned by \eN{} in character class in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Using just the first character returned by N{} in character class in regex; marked by <--\ HERE in m/%s/"
+(W regexp) Named Unicode character escapes \f(CW\*(C`(\eN{...})\*(C'\fR may return
+a multi-character sequence.  Even though a character class is
+supposed to match just one character of input, perl will match
+the whole thing correctly, except when the class is inverted
+(\f(CW\*(C`[^...]\*(C'\fR), or the escape is the beginning or final end point of
+a range.  For these, what should happen isn't clear at all.  In
+these circumstances, Perl discards all but the first character
+of the returned sequence, which is not likely what you want.
+.IP "Using just the single character results returned by \ep{} in (?[...]) in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Using just the single character results returned by p{} in (?[...]) in regex; marked by <--\ HERE in m/%s/"
+(W regexp) Extended character classes currently cannot handle operands
+that evaluate to more than one character.  These are removed from the
+results of the expansion of the \f(CW\*(C`\ep{}\*(C'\fR.
+.Sp
+This situation can happen, for example, in
+.Sp
+.Vb 1
+\& (?[ \ep{name=/KATAKANA/} ])
+.Ve
+.Sp
+"KATAKANA LETTER AINU P" is a legal Unicode name (technically a "named
+sequence"), but it is actually two characters.  The above expression
+with match only the Unicode names containing KATAKANA that represent
+single characters.
+.IP "Using /u for '%s' instead of /%s in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Using /u for '%s' instead of /%s in regex; marked by <--\ HERE in m/%s/"
+(W regexp) You used a Unicode boundary (\f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR) in a
+portion of a regular expression where the character set modifiers \f(CW\*(C`/a\*(C'\fR
+or \f(CW\*(C`/aa\*(C'\fR are in effect.  These two modifiers indicate an ASCII
+interpretation, and this doesn't make sense for a Unicode definition.
+The generated regular expression will compile so that the boundary uses
+all of Unicode.  No other portion of the regular expression is affected.
+.ie n .IP "Using !~ with %s doesn't make sense" 4
+.el .IP "Using !~ with \f(CW%s\fR doesn't make sense" 4
+.IX Item "Using !~ with %s doesn't make sense"
+(F) Using the \f(CW\*(C`!~\*(C'\fR operator with \f(CW\*(C`s///r\*(C'\fR, \f(CW\*(C`tr///r\*(C'\fR or \f(CW\*(C`y///r\*(C'\fR is
+currently reserved for future use, as the exact behavior has not
+been decided.  (Simply returning the boolean opposite of the
+modified string is usually not particularly useful.)
+.IP "UTF\-16 surrogate U+%X" 4
+.IX Item "UTF-16 surrogate U+%X"
+(S surrogate) You had a UTF\-16 surrogate in a context where they are
+not considered acceptable.  These code points, between U+D800 and
+U+DFFF (inclusive), are used by Unicode only for UTF\-16.  However, Perl
+internally allows all unsigned integer code points (up to the size limit
+available on your platform), including surrogates.  But these can cause
+problems when being input or output, which is likely where this message
+came from.  If you really really know what you are doing you can turn
+off this warning by \f(CW\*(C`no warnings \*(Aqsurrogate\*(Aq;\*(C'\fR.
+.ie n .IP "Value of %s can be ""0""; test with \fBdefined()\fR" 4
+.el .IP "Value of \f(CW%s\fR can be ""0""; test with \fBdefined()\fR" 4
+.IX Item "Value of %s can be ""0""; test with defined()"
+(W misc) In a conditional expression, you used <HANDLE>, <*> (glob),
+\&\f(CWeach()\fR, or \f(CWreaddir()\fR as a boolean value.  Each of these constructs
+can return a value of "0"; that would make the conditional expression
+false, which is probably not what you intended.  When using these
+constructs in conditional expressions, test their values with the
+\&\f(CW\*(C`defined\*(C'\fR operator.
+.IP "Value of CLI symbol ""%s"" too long" 4
+.IX Item "Value of CLI symbol ""%s"" too long"
+(W misc) A warning peculiar to VMS.  Perl tried to read the value of an
+\&\f(CW%ENV\fR element from a CLI symbol table, and found a resultant string
+longer than 1024 characters.  The return value has been truncated to
+1024 characters.
+.IP "Variable ""%s"" is not available" 4
+.IX Item "Variable ""%s"" is not available"
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical that is not currently available.
+This can happen for one of two reasons.  First, the outer lexical may be
+declared in an outer anonymous subroutine that has not yet been created.
+(Remember that named subs are created at compile time, while anonymous
+subs are created at run-time.)  For example,
+.Sp
+.Vb 1
+\&    sub { my $a; sub f { $a } }
+.Ve
+.Sp
+At the time that f is created, it can't capture the current value of \f(CW$a\fR,
+since the anonymous subroutine hasn't been created yet.  Conversely,
+the following won't give a warning since the anonymous subroutine has by
+now been created and is live:
+.Sp
+.Vb 1
+\&    sub { my $a; eval \*(Aqsub f { $a }\*(Aq }\->();
+.Ve
+.Sp
+The second situation is caused by an eval accessing a variable that has
+gone out of scope, for example,
+.Sp
+.Vb 5
+\&    sub f {
+\&        my $a;
+\&        sub { eval \*(Aq$a\*(Aq }
+\&    }
+\&    f()\->();
+.Ve
+.Sp
+Here, when the '$a' in the eval is being compiled, f() is not currently
+being executed, so its \f(CW$a\fR is not available for capture.
+.IP "Variable ""%s"" is not imported%s" 4
+.IX Item "Variable ""%s"" is not imported%s"
+(S misc) With "use strict" in effect, you referred to a global variable
+that you apparently thought was imported from another module, because
+something else of the same name (usually a subroutine) is exported by
+that module.  It usually means you put the wrong funny character on the
+front of your variable. It is also possible you used an "our" variable
+whose scope has ended.
+.IP "Variable length lookbehind not implemented in regex m/%s/" 4
+.IX Item "Variable length lookbehind not implemented in regex m/%s/"
+(F) \fBThis message no longer should be raised as of Perl 5.30.\fR  It is
+retained in this document as a convenience for people using an earlier
+Perl version.
+.Sp
+In Perl 5.30 and earlier, lookbehind is allowed
+only for subexpressions whose length is fixed and
+known at compile time.  For positive lookbehind, you can use the \f(CW\*(C`\eK\*(C'\fR
+regex construct as a way to get the equivalent functionality.  See
+(?<=pattern) and \eK in perlre.
+.Sp
+Starting in Perl 5.18, there are non-obvious Unicode rules under \f(CW\*(C`/i\*(C'\fR
+that can match variably, but which you might not think could.  For
+example, the substring \f(CW"ss"\fR can match the single character LATIN
+SMALL LETTER SHARP S.  Here's a complete list of the current ones
+affecting ASCII characters:
+.Sp
+.Vb 11
+\&   ASCII
+\&  sequence      Matches single letter under /i
+\&    FF          U+FB00 LATIN SMALL LIGATURE FF
+\&    FFI         U+FB03 LATIN SMALL LIGATURE FFI
+\&    FFL         U+FB04 LATIN SMALL LIGATURE FFL
+\&    FI          U+FB01 LATIN SMALL LIGATURE FI
+\&    FL          U+FB02 LATIN SMALL LIGATURE FL
+\&    SS          U+00DF LATIN SMALL LETTER SHARP S
+\&                U+1E9E LATIN CAPITAL LETTER SHARP S
+\&    ST          U+FB06 LATIN SMALL LIGATURE ST
+\&                U+FB05 LATIN SMALL LIGATURE LONG S T
+.Ve
+.Sp
+This list is subject to change, but is quite unlikely to.
+Each ASCII sequence can be any combination of upper\- and lowercase.
+.Sp
+You can avoid this by using a bracketed character class in the
+lookbehind assertion, like
+.Sp
+.Vb 2
+\& (?<![sS]t)
+\& (?<![fF]f[iI])
+.Ve
+.Sp
+This fools Perl into not matching the ligatures.
+.Sp
+Another option for Perls starting with 5.16, if you only care about
+ASCII matches, is to add the \f(CW\*(C`/aa\*(C'\fR modifier to the regex.  This will
+exclude all these non-obvious matches, thus getting rid of this message.
+You can also say
+.Sp
+.Vb 1
+\& use if $] ge 5.016, re => \*(Aq/aa\*(Aq;
+.Ve
+.Sp
+to apply \f(CW\*(C`/aa\*(C'\fR to all regular expressions compiled within its scope.
+See re.
+.IP "Variable length positive lookbehind with capturing is experimental in regex m/%s/" 4
+.IX Item "Variable length positive lookbehind with capturing is experimental in regex m/%s/"
+(W) Variable length positive lookbehind with capturing is not well defined. This
+warning alerts you to the fact that you are using a construct which may
+change in a future version of perl. See the
+documentation of Positive Lookbehind in perlre
+for details. You may silence this warning with the following:
+.Sp
+.Vb 1
+\&    no warnings \*(Aqexperimental::vlb\*(Aq;
+.Ve
+.IP "Variable length negative lookbehind with capturing is experimental in regex m/%s/" 4
+.IX Item "Variable length negative lookbehind with capturing is experimental in regex m/%s/"
+(W) Variable length negative lookbehind with capturing is not well defined. This
+warning alerts you to the fact that you are using a construct which may
+change in a future version of perl. See the
+documentation of Negative Lookbehind in perlre
+for details. You may silence this warning with the following:
+.Sp
+.Vb 1
+\&    no warnings \*(Aqexperimental::vlb\*(Aq;
+.Ve
+.ie n .IP """%s"" variable %s masks earlier declaration in same %s" 4
+.el .IP """%s"" variable \f(CW%s\fR masks earlier declaration in same \f(CW%s\fR" 4
+.IX Item """%s"" variable %s masks earlier declaration in same %s"
+(W shadow) A "my", "our" or "state" variable has been redeclared in the
+current scope or statement, effectively eliminating all access to the
+previous instance.  This is almost always a typographical error.  Note
+that the earlier variable will still exist until the end of the scope
+or until all closure references to it are destroyed.
+.IP "Variable syntax" 4
+.IX Item "Variable syntax"
+(A) You've accidentally run your script through \fBcsh\fR instead
+of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.
+.IP "Variable ""%s"" will not stay shared" 4
+.IX Item "Variable ""%s"" will not stay shared"
+(W closure) An inner (nested) \fInamed\fR subroutine is referencing a
+lexical variable defined in an outer named subroutine.
+.Sp
+When the inner subroutine is called, it will see the value of
+the outer subroutine's variable as it was before and during the *first*
+call to the outer subroutine; in this case, after the first call to the
+outer subroutine is complete, the inner and outer subroutines will no
+longer share a common value for the variable.  In other words, the
+variable will no longer be shared.
+.Sp
+This problem can usually be solved by making the inner subroutine
+anonymous, using the \f(CW\*(C`sub {}\*(C'\fR syntax.  When inner anonymous subs that
+reference variables in outer subroutines are created, they
+are automatically rebound to the current values of such variables.
+.IP "vector argument not supported with alpha versions" 4
+.IX Item "vector argument not supported with alpha versions"
+(S printf) The \f(CW%vd\fR (s)printf format does not support version objects
+with alpha parts.
+.IP "Verb pattern '%s' has a mandatory argument in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Verb pattern '%s' has a mandatory argument in regex; marked by <--\ HERE in m/%s/"
+(F) You used a verb pattern that requires an argument.  Supply an
+argument or check that you are using the right verb.
+.IP "Verb pattern '%s' may not have an argument in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Verb pattern '%s' may not have an argument in regex; marked by <--\ HERE in m/%s/"
+(F) You used a verb pattern that is not allowed an argument.  Remove the 
+argument or check that you are using the right verb.
+.IP "Version control conflict marker" 4
+.IX Item "Version control conflict marker"
+(F) The parser found a line starting with \f(CW\*(C`<<<<<<<\*(C'\fR,
+\&\f(CW\*(C`>>>>>>>\*(C'\fR, or \f(CW\*(C`=======\*(C'\fR.  These may be left by a
+version control system to mark conflicts after a failed merge operation.
+.IP "Version number must be a constant number" 4
+.IX Item "Version number must be a constant number"
+(P) The attempt to translate a \f(CW\*(C`use Module n.n LIST\*(C'\fR statement into
+its equivalent \f(CW\*(C`BEGIN\*(C'\fR block found an internal inconsistency with
+the version number.
+.IP "Version string '%s' contains invalid data; ignoring: '%s'" 4
+.IX Item "Version string '%s' contains invalid data; ignoring: '%s'"
+(W misc) The version string contains invalid characters at the end, which
+are being ignored.
+.IP "Warning: something's wrong" 4
+.IX Item "Warning: something's wrong"
+(W) You passed \fBwarn()\fR an empty string (the equivalent of \f(CW\*(C`warn ""\*(C'\fR) or
+you called it with no args and \f(CW$@\fR was empty.
+.ie n .IP "Warning: unable to close filehandle %s properly" 4
+.el .IP "Warning: unable to close filehandle \f(CW%s\fR properly" 4
+.IX Item "Warning: unable to close filehandle %s properly"
+(S) The implicit \fBclose()\fR done by an \fBopen()\fR got an error indication on
+the \fBclose()\fR.  This usually indicates your file system ran out of disk
+space.
+.ie n .IP "Warning: unable to close filehandle properly: %s" 4
+.el .IP "Warning: unable to close filehandle properly: \f(CW%s\fR" 4
+.IX Item "Warning: unable to close filehandle properly: %s"
+.PD 0
+.ie n .IP "Warning: unable to close filehandle %s properly: %s" 4
+.el .IP "Warning: unable to close filehandle \f(CW%s\fR properly: \f(CW%s\fR" 4
+.IX Item "Warning: unable to close filehandle %s properly: %s"
+.PD
+(S io) There were errors during the implicit \fBclose()\fR done on a filehandle
+when its reference count reached zero while it was still open, e.g.:
+.Sp
+.Vb 4
+\&    {
+\&        open my $fh, \*(Aq>\*(Aq, $file  or die "open: \*(Aq$file\*(Aq: $!\en";
+\&        print $fh $data or die "print: $!";
+\&    } # implicit close here
+.Ve
+.Sp
+Because various errors may only be detected by \fBclose()\fR (e.g. buffering could
+allow the \f(CW\*(C`print\*(C'\fR in this example to return true even when the disk is full),
+it is dangerous to ignore its result.  So when it happens implicitly, perl
+will signal errors by warning.
+.Sp
+\&\fBPrior to version 5.22.0, perl ignored such errors\fR, so the common idiom shown
+above was liable to cause \fBsilent data loss\fR.
+.IP "Warning: Use of ""%s"" without parentheses is ambiguous" 4
+.IX Item "Warning: Use of ""%s"" without parentheses is ambiguous"
+(S ambiguous) You wrote a unary operator followed by something that
+looks like a binary operator that could also have been interpreted as a
+term or unary operator.  For instance, if you know that the rand
+function has a default argument of 1.0, and you write
+.Sp
+.Vb 1
+\&    rand + 5;
+.Ve
+.Sp
+you may THINK you wrote the same thing as
+.Sp
+.Vb 1
+\&    rand() + 5;
+.Ve
+.Sp
+but in actual fact, you got
+.Sp
+.Vb 1
+\&    rand(+5);
+.Ve
+.Sp
+So put in parentheses to say what you really mean.
+.IP "when is deprecated" 4
+.IX Item "when is deprecated"
+(D deprecated::smartmatch) \f(CW\*(C`when\*(C'\fR depends on smartmatch, which is
+deprecated.  Additionally, it has several special cases that may
+not be immediately obvious, and it will be removed in Perl 5.42.
+See the explanation
+under "Experimental Details on given and when" in perlsyn.
+.ie n .IP "Wide character in %s" 4
+.el .IP "Wide character in \f(CW%s\fR" 4
+.IX Item "Wide character in %s"
+(S utf8) Perl met a wide character (ordinal >255) when it wasn't
+expecting one.  This warning is by default on for I/O (like print).
+.Sp
+If this warning does come from I/O, the easiest
+way to quiet it is simply to add the \f(CW\*(C`:utf8\*(C'\fR layer, \fIe.g.\fR,
+\&\f(CW\*(C`binmode\ STDOUT,\ \*(Aq:utf8\*(Aq\*(C'\fR.  Another way to turn off the warning is
+to add \f(CW\*(C`no\ warnings\ \*(Aqutf8\*(Aq;\*(C'\fR but that is often closer to
+cheating.  In general, you are supposed to explicitly mark the
+filehandle with an encoding, see open and "binmode" in perlfunc.
+.Sp
+If the warning comes from other than I/O, this diagnostic probably
+indicates that incorrect results are being obtained.  You should examine
+your code to determine how a wide character is getting to an operation
+that doesn't handle them.
+.ie n .IP "Wide character (U+%X) in %s" 4
+.el .IP "Wide character (U+%X) in \f(CW%s\fR" 4
+.IX Item "Wide character (U+%X) in %s"
+(W locale) While in a single-byte locale (\fIi.e.\fR, a non\-UTF\-8
+one), a multi-byte character was encountered.   Perl considers this
+character to be the specified Unicode code point.  Combining non\-UTF\-8
+locales and Unicode is dangerous.  Almost certainly some characters
+will have two different representations.  For example, in the ISO 8859\-7
+(Greek) locale, the code point 0xC3 represents a Capital Gamma.  But so
+also does 0x393.  This will make string comparisons unreliable.
+.Sp
+You likely need to figure out how this multi-byte character got mixed up
+with your single-byte locale (or perhaps you thought you had a UTF\-8
+locale, but Perl disagrees).
+.IP "Within []\-length '%c' not allowed" 4
+.IX Item "Within []-length '%c' not allowed"
+(F) The count in the (un)pack template may be replaced by \f(CW\*(C`[TEMPLATE]\*(C'\fR
+only if \f(CW\*(C`TEMPLATE\*(C'\fR always matches the same amount of packed bytes that
+can be determined from the template alone.  This is not possible if
+it contains any of the codes @, /, U, u, w or a *\-length.  Redesign
+the template.
+.ie n .IP "While trying to resolve method call %s\->%s() can not locate package ""%s"" yet it is mentioned in @%s::ISA (perhaps you forgot to load ""%s""?)" 4
+.el .IP "While trying to resolve method call \f(CW%s\fR\->%s() can not locate package ""%s"" yet it is mentioned in @%s::ISA (perhaps you forgot to load ""%s""?)" 4
+.IX Item "While trying to resolve method call %s->%s() can not locate package ""%s"" yet it is mentioned in @%s::ISA (perhaps you forgot to load ""%s""?)"
+(W syntax) It is possible that the \f(CW@ISA\fR contains a misspelled or never loaded
+package name, which can result in perl choosing an unexpected parent
+class's method to resolve the method call. If this is deliberate you
+can do something like
+.Sp
+.Vb 1
+\&  @Missing::Package::ISA = ();
+.Ve
+.Sp
+to silence the warnings, otherwise you should correct the package name, or
+ensure that the package is loaded prior to the method call.
+.IP "%s() with negative argument" 4
+.IX Item "%s() with negative argument"
+(S misc) Certain operations make no sense with negative arguments.
+Warning is given and the operation is not done.
+.ie n .IP "\fBwrite()\fR on closed filehandle %s" 4
+.el .IP "\fBwrite()\fR on closed filehandle \f(CW%s\fR" 4
+.IX Item "write() on closed filehandle %s"
+(W closed) The filehandle you're writing to got itself closed sometime
+before now.  Check your control flow.
+.ie n .IP "%s ""\ex%X"" does not map to Unicode" 4
+.el .IP "\f(CW%s\fR ""\ex%X"" does not map to Unicode" 4
+.IX Item "%s ""x%X"" does not map to Unicode"
+(S utf8) When reading in different encodings, Perl tries to
+map everything into Unicode characters.  The bytes you read
+in are not legal in this encoding.  For example
+.Sp
+.Vb 1
+\&    utf8 "\exE4" does not map to Unicode
+.Ve
+.Sp
+if you try to read in the a\-diaereses Latin\-1 as UTF\-8.
+.IP "'X' outside of string" 4
+.IX Item "'X' outside of string"
+(F) You had a (un)pack template that specified a relative position before
+the beginning of the string being (un)packed.  See "pack" in perlfunc.
+.IP "'x' outside of string in unpack" 4
+.IX Item "'x' outside of string in unpack"
+(F) You had an unpack template that specified a relative position after
+the end of the string being unpacked.  See "pack" in perlfunc.
+.IP "YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!" 4
+.IX Item "YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!"
+(F) And you probably never will, because you probably don't have the
+sources to your kernel, and your vendor probably doesn't give a rip
+about what you want.  There is a vulnerability anywhere that you have a
+set-id script, and to close it you need to remove the set-id bit from
+the script that you're attempting to run.  To actually run the script
+set-id, your best bet is to put a set-id C wrapper around your script.
+.IP "You need to quote ""%s""" 4
+.IX Item "You need to quote ""%s"""
+(W syntax) You assigned a bareword as a signal handler name.
+Unfortunately, you already have a subroutine of that name declared,
+which means that Perl 5 will try to call the subroutine when the
+assignment is executed, which is probably not what you want.  (If it IS
+what you want, put an & in front.)
+.IP "Your random numbers are not that random" 4
+.IX Item "Your random numbers are not that random"
+(F) When trying to initialize the random seed for hashes, Perl could
+not get any randomness out of your system.  This usually indicates
+Something Very Wrong.
+.IP "Zero length \eN{} in regex; marked by <\-\-\ HERE in m/%s/" 4
+.IX Item "Zero length N{} in regex; marked by <--\ HERE in m/%s/"
+(F) Named Unicode character escapes (\f(CW\*(C`\eN{...}\*(C'\fR) may return a zero-length
+sequence.  Such an escape was used in an extended character class, i.e.
+\&\f(CW\*(C`(?[...])\*(C'\fR, or under \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR, which is not permitted.  Check
+that the correct escape has been used, and the correct charnames handler
+is in scope.  The <\-\-\ HERE shows whereabouts in the regular
+expression the problem was discovered.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+warnings, diagnostics.
diff --git a/upstream/mageia-cauldron/man1/perldoc.1 b/upstream/mageia-cauldron/man1/perldoc.1
new file mode 100644
index 00000000..d5395f2b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldoc.1
@@ -0,0 +1,338 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDOC 1"
+.TH PERLDOC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldoc \- Look up Perl documentation in Pod format.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 10
+\&    perldoc [\-h] [\-D] [\-t] [\-u] [\-m] [\-l] [\-U] [\-F]
+\&        [\-i] [\-V] [\-T] [\-r]
+\&        [\-d destination_file]
+\&        [\-o formatname]
+\&        [\-M FormatterClassName]
+\&        [\-w formatteroption:value]
+\&        [\-n nroff\-replacement]
+\&        [\-X]
+\&        [\-L language_code]
+\&        PageName|ModuleName|ProgramName|URL
+.Ve
+.PP
+Examples:
+.PP
+.Vb 1
+\&    perldoc \-f BuiltinFunction
+\&
+\&    perldoc \-L it \-f BuiltinFunction
+\&
+\&    perldoc \-q FAQ Keyword
+\&
+\&    perldoc \-L fr \-q FAQ Keyword
+\&
+\&    perldoc \-v PerlVariable
+\&
+\&    perldoc \-a PerlAPI
+.Ve
+.PP
+See below for more description of the switches.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBperldoc\fR looks up documentation in .pod format that is embedded in the perl
+installation tree or in a perl script, and displays it using a variety of
+formatters.  This is primarily used for the documentation for the perl library
+modules.
+.PP
+Your system may also have man pages installed for those modules, in
+which case you can probably just use the \fBman\fR\|(1) command.
+.PP
+If you are looking for a table of contents to the Perl library modules
+documentation, see the perltoc page.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \fB\-h\fR 5
+.IX Item "-h"
+Prints out a brief \fBh\fRelp message.
+.IP \fB\-D\fR 5
+.IX Item "-D"
+\&\fBD\fRescribes search for the item in \fBd\fRetail.
+.IP \fB\-t\fR 5
+.IX Item "-t"
+Display docs using plain \fBt\fRext converter, instead of nroff. This may be faster,
+but it probably won't look as nice.
+.IP \fB\-u\fR 5
+.IX Item "-u"
+Skip the real Pod formatting, and just show the raw Pod source (\fBU\fRnformatted)
+.IP "\fB\-m\fR \fImodule\fR" 5
+.IX Item "-m module"
+Display the entire module: both code and unformatted pod documentation.
+This may be useful if the docs don't explain a function in the detail
+you need, and you'd like to inspect the code directly; perldoc will find
+the file for you and simply hand it off for display.
+.IP \fB\-l\fR 5
+.IX Item "-l"
+Display on\fBl\fRy the file name of the module found.
+.IP \fB\-U\fR 5
+.IX Item "-U"
+When running as the superuser, don't attempt drop privileges for security.
+This option is implied with \fB\-F\fR.
+.Sp
+\&\fBNOTE\fR: Please see the heading SECURITY below for more information.
+.IP \fB\-F\fR 5
+.IX Item "-F"
+Consider arguments as file names; no search in directories will be performed.
+Implies \fB\-U\fR if run as the superuser.
+.IP "\fB\-f\fR \fIperlfunc\fR" 5
+.IX Item "-f perlfunc"
+The \fB\-f\fR option followed by the name of a perl built-in function will
+extract the documentation of this function from perlfunc.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&      perldoc \-f sprintf
+.Ve
+.IP "\fB\-q\fR \fIperlfaq-search-regexp\fR" 5
+.IX Item "-q perlfaq-search-regexp"
+The \fB\-q\fR option takes a regular expression as an argument.  It will search
+the \fBq\fRuestion headings in perlfaq[1\-9] and print the entries matching
+the regular expression.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&     perldoc \-q shuffle
+.Ve
+.IP "\fB\-a\fR \fIperlapifunc\fR" 5
+.IX Item "-a perlapifunc"
+The \fB\-a\fR option followed by the name of a perl api function will
+extract the documentation of this function from perlapi.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&     perldoc \-a newHV
+.Ve
+.IP "\fB\-v\fR \fIperlvar\fR" 5
+.IX Item "-v perlvar"
+The \fB\-v\fR option followed by the name of a Perl predefined variable will
+extract the documentation of this variable from perlvar.
+.Sp
+Examples:
+.Sp
+.Vb 3
+\&     perldoc \-v \*(Aq$"\*(Aq
+\&     perldoc \-v @+
+\&     perldoc \-v DATA
+.Ve
+.IP \fB\-T\fR 5
+.IX Item "-T"
+This specifies that the output is not to be sent to a pager, but is to
+be sent directly to STDOUT.
+.IP "\fB\-d\fR \fIdestination-filename\fR" 5
+.IX Item "-d destination-filename"
+This specifies that the output is to be sent neither to a pager nor
+to STDOUT, but is to be saved to the specified filename.  Example:
+\&\f(CW\*(C`perldoc \-oLaTeX \-dtextwrapdocs.tex Text::Wrap\*(C'\fR
+.IP "\fB\-o\fR \fIoutput-formatname\fR" 5
+.IX Item "-o output-formatname"
+This specifies that you want Perldoc to try using a Pod-formatting
+class for the output format that you specify.  For example:
+\&\f(CW\*(C`\-oman\*(C'\fR.  This is actually just a wrapper around the \f(CW\*(C`\-M\*(C'\fR switch;
+using \f(CW\*(C`\-o\fR\f(CIformatname\fR\f(CW\*(C'\fR just looks for a loadable class by adding
+that format name (with different capitalizations) to the end of
+different classname prefixes.
+.Sp
+For example, \f(CW\*(C`\-oLaTeX\*(C'\fR currently tries all of the following classes:
+Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
+Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
+Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
+Pod::LATEX.
+.IP "\fB\-M\fR \fImodule-name\fR" 5
+.IX Item "-M module-name"
+This specifies the module that you want to try using for formatting the
+pod.  The class must at least provide a \f(CW\*(C`parse_from_file\*(C'\fR method.
+For example: \f(CW\*(C`perldoc \-MPod::Perldoc::ToChecker\*(C'\fR.
+.Sp
+You can specify several classes to try by joining them with commas
+or semicolons, as in \f(CW\*(C`\-MTk::SuperPod;Tk::Pod\*(C'\fR.
+.IP "\fB\-w\fR \fIoption:value\fR or \fB\-w\fR \fIoption\fR" 5
+.IX Item "-w option:value or -w option"
+This specifies an option to call the formatter \fBw\fRith.  For example,
+\&\f(CW\*(C`\-w textsize:15\*(C'\fR will call
+\&\f(CW\*(C`$formatter\->textsize(15)\*(C'\fR on the formatter object before it is
+used to format the object.  For this to be valid, the formatter class
+must provide such a method, and the value you pass should be valid.
+(So if \f(CW\*(C`textsize\*(C'\fR expects an integer, and you do \f(CW\*(C`\-w textsize:big\*(C'\fR,
+expect trouble.)
+.Sp
+You can use \f(CW\*(C`\-w optionname\*(C'\fR (without a value) as shorthand for
+\&\f(CW\*(C`\-w optionname:\fR\f(CITRUE\fR\f(CW\*(C'\fR.  This is presumably useful in cases of on/off
+features like: \f(CW\*(C`\-w page_numbering\*(C'\fR.
+.Sp
+You can use an "=" instead of the ":", as in: \f(CW\*(C`\-w textsize=15\*(C'\fR.  This
+might be more (or less) convenient, depending on what shell you use.
+.IP \fB\-X\fR 5
+.IX Item "-X"
+Use an index if it is present. The \fB\-X\fR option looks for an entry
+whose basename matches the name given on the command line in the file
+\&\f(CW\*(C`$Config{archlib}/pod.idx\*(C'\fR. The \fIpod.idx\fR file should contain fully
+qualified filenames, one per line.
+.IP "\fB\-L\fR \fIlanguage_code\fR" 5
+.IX Item "-L language_code"
+This allows one to specify the \fIlanguage code\fR for the desired language
+translation. If the \f(CW\*(C`POD2::<language_code>\*(C'\fR package isn't
+installed in your system, the switch is ignored.
+All available translation packages are to be found under the \f(CW\*(C`POD2::\*(C'\fR
+namespace. See POD2::IT (or POD2::FR) to see how to create new
+localized \f(CW\*(C`POD2::*\*(C'\fR documentation packages and integrate them into
+Pod::Perldoc.
+.IP \fBPageName|ModuleName|ProgramName|URL\fR 5
+.IX Item "PageName|ModuleName|ProgramName|URL"
+The item you want to look up.  Nested modules (such as \f(CW\*(C`File::Basename\*(C'\fR)
+are specified either as \f(CW\*(C`File::Basename\*(C'\fR or \f(CW\*(C`File/Basename\*(C'\fR.  You may also
+give a descriptive name of a page, such as \f(CW\*(C`perlfunc\*(C'\fR.  For URLs, HTTP and
+HTTPS are the only kind currently supported.
+.Sp
+For simple names like 'foo', when the normal search fails to find
+a matching page, a search with the "perl" prefix is tried as well.
+So "perldoc intro" is enough to find/render "perlintro.pod".
+.IP "\fB\-n\fR \fIsome-formatter\fR" 5
+.IX Item "-n some-formatter"
+Specify replacement for groff
+.IP \fB\-r\fR 5
+.IX Item "-r"
+Recursive search.
+.IP \fB\-i\fR 5
+.IX Item "-i"
+Ignore case.
+.IP \fB\-V\fR 5
+.IX Item "-V"
+Displays the version of perldoc you're running.
+.SH SECURITY
+.IX Header "SECURITY"
+Because \fBperldoc\fR does not run properly tainted, and is known to
+have security issues, when run as the superuser it will attempt to
+drop privileges by setting the effective and real IDs to nobody's
+or nouser's account, or \-2 if unavailable.  If it cannot relinquish
+its privileges, it will not run.
+.PP
+See the \f(CW\*(C`\-U\*(C'\fR option if you do not want this behavior but \fBbeware\fR
+that there are significant security risks if you choose to use \f(CW\*(C`\-U\*(C'\fR.
+.PP
+Since 3.26, using \f(CW\*(C`\-F\*(C'\fR as the superuser also implies \f(CW\*(C`\-U\*(C'\fR as opening
+most files and traversing directories requires privileges that are
+above the nobody/nogroup level.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+Any switches in the \f(CW\*(C`PERLDOC\*(C'\fR environment variable will be used before the
+command line arguments.
+.PP
+Useful values for \f(CW\*(C`PERLDOC\*(C'\fR include \f(CW\*(C`\-oterm\*(C'\fR, \f(CW\*(C`\-otext\*(C'\fR, \f(CW\*(C`\-ortf\*(C'\fR,
+\&\f(CW\*(C`\-oxml\*(C'\fR, and so on, depending on what modules you have on hand; or
+the formatter class may be specified exactly with \f(CW\*(C`\-MPod::Perldoc::ToTerm\*(C'\fR
+or the like.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR also searches directories
+specified by the \f(CW\*(C`PERL5LIB\*(C'\fR (or \f(CW\*(C`PERLLIB\*(C'\fR if \f(CW\*(C`PERL5LIB\*(C'\fR is not
+defined) and \f(CW\*(C`PATH\*(C'\fR environment variables.
+(The latter is so that embedded pods for executables, such as
+\&\f(CW\*(C`perldoc\*(C'\fR itself, are available.)
+.PP
+In directories where either \f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR exist, \f(CW\*(C`perldoc\*(C'\fR
+will add \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`lib\*(C'\fR first to its search path, and as long as you're not
+the superuser will add \f(CW\*(C`blib\*(C'\fR too.  This is really helpful if you're working
+inside of a build directory and want to read through the docs even if you
+have a version of a module previously installed.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR will use, in order of preference, the pager defined in
+\&\f(CW\*(C`PERLDOC_PAGER\*(C'\fR, \f(CW\*(C`MANPAGER\*(C'\fR, or \f(CW\*(C`PAGER\*(C'\fR before trying to find a pager
+on its own. (\f(CW\*(C`MANPAGER\*(C'\fR is not used if \f(CW\*(C`perldoc\*(C'\fR was told to display
+plain text or unformatted pod.)
+.PP
+When using perldoc in it's \f(CW\*(C`\-m\*(C'\fR mode (display module source code),
+\&\f(CW\*(C`perldoc\*(C'\fR will attempt to use the pager set in \f(CW\*(C`PERLDOC_SRC_PAGER\*(C'\fR.
+A useful setting for this command is your favorite editor as in
+\&\f(CW\*(C`/usr/bin/nano\*(C'\fR. (Don't judge me.)
+.PP
+One useful value for \f(CW\*(C`PERLDOC_PAGER\*(C'\fR is \f(CW\*(C`less \-+C \-E\*(C'\fR.
+.PP
+Having PERLDOCDEBUG set to a positive integer will make perldoc emit
+even more descriptive output than the \f(CW\*(C`\-D\*(C'\fR switch does; the higher the
+number, the more it emits.
+.SH CHANGES
+.IX Header "CHANGES"
+Up to 3.14_05, the switch \fB\-v\fR was used to produce verbose
+messages of \fBperldoc\fR operation, which is now enabled by \fB\-D\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlpod, Pod::Perldoc
+.SH AUTHOR
+.IX Header "AUTHOR"
+Current maintainer: Mark Allen \f(CW\*(C`<mallen@cpan.org>\*(C'\fR
+.PP
+Past contributors are:
+brian d foy \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR 
+Adriano R. Ferreira \f(CW\*(C`<ferreira@cpan.org>\*(C'\fR,
+Sean M. Burke \f(CW\*(C`<sburke@cpan.org>\*(C'\fR,
+Kenneth Albanowski \f(CW\*(C`<kjahds@kjahds.com>\*(C'\fR,
+Andy Dougherty  \f(CW\*(C`<doughera@lafcol.lafayette.edu>\*(C'\fR,
+and many others.
diff --git a/upstream/mageia-cauldron/man1/perldocstyle.1 b/upstream/mageia-cauldron/man1/perldocstyle.1
new file mode 100644
index 00000000..b4f19c95
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldocstyle.1
@@ -0,0 +1,1118 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDOCSTYLE 1"
+.TH PERLDOCSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldocstyle \- A style guide for writing Perl's documentation
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is a guide for the authorship and maintenance of the
+documentation that ships with Perl. This includes the following:
+.IP \(bu 4
+The several dozen manual sections whose filenames begin with "\f(CW\*(C`perl\*(C'\fR",
+such as \f(CW\*(C`perlobj\*(C'\fR, \f(CW\*(C`perlre\*(C'\fR, and \f(CW\*(C`perlintro\*(C'\fR. (And, yes, \f(CW\*(C`perl\*(C'\fR.)
+.IP \(bu 4
+The documentation for all the modules included with Perl (as listed by
+\&\f(CW\*(C`perlmodlib\*(C'\fR).
+.IP \(bu 4
+The hundreds of individually presented reference sections derived from
+the \f(CW\*(C`perlfunc\*(C'\fR file.
+.PP
+This guide will hereafter refer to user-manual section files as \fIman
+pages\fR, per Unix convention.
+.SS "Purpose of this guide"
+.IX Subsection "Purpose of this guide"
+This style guide aims to establish standards, procedures, and philosophies
+applicable to Perl's core documentation.
+.PP
+Adherence to these standards will help ensure that any one part of
+Perl's manual has a tone and style consistent with that of any other. As
+with the rest of the Perl project, the language's documentation
+collection is an open-source project authored over a long period of time
+by many people. Maintaining consistency across such a wide swath of work
+presents a challenge; this guide provides a foundation to help mitigate
+this difficulty.
+.PP
+This will help its readers\-\-especially those new to Perl\-\-to feel
+more welcome and engaged with Perl's documentation, and this in turn
+will help the Perl project itself grow stronger through having a larger,
+more diverse, and more confident population of knowledgeable users.
+.SS "Intended audience"
+.IX Subsection "Intended audience"
+Anyone interested in contributing to Perl's core documentation should
+familiarize themselves with the standards outlined by this guide.
+.PP
+Programmers documenting their own work apart from the Perl project
+itself may also find this guide worthwhile, especially if they wish
+their work to extend the tone and style of Perl's own manual.
+.SS "Status of this document"
+.IX Subsection "Status of this document"
+This guide was initially drafted in late 2020, drawing from the
+documentation style guides of several open-source technologies
+contemporary with Perl. This has included Python, Raku, Rust, and the
+Linux kernel.
+.PP
+The author intends to see this guide used as starting place from
+which to launch a review of Perl's reams of extant documentation, with
+the expectation that those conducting this review should grow and modify
+this guide as needed to account for the requirements and quirks
+particular to Perl's programming manual.
+.SH FUNDAMENTALS
+.IX Header "FUNDAMENTALS"
+.SS "Choice of markup: Pod"
+.IX Subsection "Choice of markup: Pod"
+All of Perl's core documentation uses Pod ("Plain Old Documentation"), a
+simple markup language, to format its source text. Pod is similar in
+spirit to other contemporary lightweight markup technologies, such as
+Markdown and reStructuredText, and has a decades-long shared history
+with Perl itself.
+.PP
+For a comprehensive reference to Pod syntax, see \f(CW\*(C`perlpod\*(C'\fR.
+For the sake of reading this guide, familiarity with the Pod syntax for
+section headers (\f(CW\*(C`=head2\*(C'\fR, et cetera) and for inline text formatting
+(\f(CW\*(C`C<like this>\*(C'\fR) should suffice.
+.PP
+Perl programmers also use Pod to document their own scripts, libraries,
+and modules. This use of Pod has its own style guide, outlined by
+\&\f(CW\*(C`perlpodstyle\*(C'\fR.
+.SS "Choice of language: American English"
+.IX Subsection "Choice of language: American English"
+Perl's core documentation is written in English, with a preference for
+American spelling of words and expression of phrases. That means "color"
+over "colour", "math" versus "maths", "the team has decided" and not
+"the team have decided", and so on.
+.PP
+We name one style of English for the sake of consistency across Perl's
+documentation, much as a software project might declare a four-space
+indentation standard\-\-even when that doesn't affect how well the code
+compiles. Both efforts result in an easier read by avoiding jarring,
+mid-document changes in format or style.
+.PP
+Contributors to Perl's documentation should note that this rule
+describes the ultimate, published output of the project, and does not
+prescribe the dialect used within community contributions. The
+documentation team enthusiastically welcomes any English-language
+contributions, and will actively assist in Americanizing spelling and
+style when warranted.
+.PP
+\fIOther languages and translations\fR
+.IX Subsection "Other languages and translations"
+.PP
+Community-authored translations of Perl's documentation do exist,
+covering a variety of languages. While the Perl project appreciates
+these translation efforts and promotes them when applicable, it does not
+officially support or maintain any of them.
+.PP
+That said, keeping Perl's documentation clear, simple, and short has a
+welcome side effect of aiding any such translation project.
+.PP
+(Note that the Chinese, Japanese, and Korean-language README files
+included with Perl's source distributions provide an exception to this
+choice of language\-\-but these documents fall outside the scope of this
+guide.)
+.SS "Choice of encoding: UTF\-8"
+.IX Subsection "Choice of encoding: UTF-8"
+Perl's core documentation files are encoded in UTF\-8, and can make use
+of the full range of characters this encoding allows.
+.PP
+As such, every core doc file (or the Pod section of every core module)
+should commence with an \f(CW\*(C`=encoding utf8\*(C'\fR declaration.
+.SS "Choice of underlying style guide: CMOS"
+.IX Subsection "Choice of underlying style guide: CMOS"
+Perl's documentation uses the Chicago Manual of
+Style <https://www.chicagomanualofstyle.org> (CMOS), 17th Edition, as
+its baseline guide for style and grammar. While the document you are
+currently reading endeavors to serve as an adequate stand-alone style guide
+for the purposes of documenting Perl, authors should consider CMOS the
+fallback authority for any pertinent topics not covered here.
+.PP
+Because CMOS is not a free resource, access to it is not a prerequisite
+for contributing to Perl's documentation; the doc team will help
+contributors learn about and apply its guidelines as needed. However, we
+do encourage anyone interested in significant doc contributions to
+obtain or at least read through CMOS. (Copies are likely available
+through most public libraries, and CMOS-derived fundamentals can be
+found online as well.)
+.SS "Contributing to Perl's documentation"
+.IX Subsection "Contributing to Perl's documentation"
+Perl, like any programming language, is only as good as its
+documentation. Perl depends upon clear, friendly, and thorough
+documentation in order to welcome brand-new users, teach and explain the
+language's various concepts and components, and serve as a lifelong
+reference for experienced Perl programmers. As such, the Perl project
+welcomes and values all community efforts to improve the language's
+documentation.
+.PP
+Perl accepts documentation contributions through the same open-source
+project pipeline as code contributions. See \f(CW\*(C`perlhack\*(C'\fR for
+more information.
+.SH "FORMATTING AND STRUCTURE"
+.IX Header "FORMATTING AND STRUCTURE"
+This section details specific Pod syntax and style that all core Perl
+documentation should adhere to, in the interest of consistency and
+readability.
+.SS "Document structure"
+.IX Subsection "Document structure"
+Each individual work of core Perl documentation, whether contained
+within a \f(CW\*(C`.pod\*(C'\fR file or in the Pod section of a standard code module,
+patterns its structure after a number of long-time Unix man page
+conventions. (Hence this guide's use of "man page" to refer to any one
+self-contained part of Perl's documentation.)
+.PP
+Adhering to these conventions helps Pod formatters present a Perl man
+page's content in different contexts\-\-whether a terminal, the web, or
+even print. Many of the following requirements originate with
+\&\f(CW\*(C`perlpodstyle\*(C'\fR, which derives its recommendations in
+turn from these well-established practices.
+.PP
+\fIName\fR
+.IX Subsection "Name"
+.PP
+After its \f(CW\*(C`=encoding utf8\*(C'\fR declaration, a
+Perl man page \fImust\fR present a level-one header named "NAME" (literally),
+followed by a paragraph containing the page's name and a very brief
+description.
+.PP
+The first few lines of a notional page named \f(CW\*(C`perlpodexample\*(C'\fR:
+.PP
+.Vb 1
+\&    =encoding utf8
+\&
+\&    =head1 NAME
+\&
+\&    perlpodexample \- An example of formatting a manual page\*(Aqs title line
+.Ve
+.PP
+\fIDescription and synopsis\fR
+.IX Subsection "Description and synopsis"
+.PP
+Most Perl man pages also contain a DESCRIPTION section featuring a
+summary of, or introduction to, the document's content and purpose.
+.PP
+This section should also, one way or another, clearly identify the
+audience that the page addresses, especially if it has expectations
+about the reader's prior knowledge. For example, a man page that dives
+deep into the inner workings of Perl's regular expression engine should
+state its assumptions up front\-\-and quickly redirect readers who are
+instead looking for a more basic reference or tutorial.
+.PP
+Reference pages, when appropriate, can precede the DESCRIPTION with a
+SYNOPSIS section that lists, within one or more code blocks, some very
+brief examples of the referenced feature's use. This section should show
+a handful of common-case and best-practice examples, rather than an
+exhaustive list of every obscure method or alternate syntax available.
+.PP
+\fIOther sections and subsections\fR
+.IX Subsection "Other sections and subsections"
+.PP
+Pages should conclude, when appropriate, with a SEE ALSO section
+containing hyperlinks to relevant sections of Perl's manual, other Unix
+man pages, or appropriate web pages. Hyperlink each such cross-reference via
+\&\f(CW\*(C`L<...>\*(C'\fR.
+.PP
+What other sections to include depends entirely upon the topic at hand.
+Authors should feel free to include further \f(CW\*(C`=head1\*(C'\fR\-level sections,
+whether other standard ones listed by \f(CW\*(C`perlpodstyle\*(C'\fR, or ones specific
+to the page's topic; in either case, render these top-level headings in
+all-capital letters.
+.PP
+You may then include as many subsections beneath them as needed to meet
+the standards of clarity, accessibility, and cross-reference affinity
+suggested elsewhere in this guide.
+.PP
+\fIAuthor and copyright\fR
+.IX Subsection "Author and copyright"
+.PP
+In most circumstances, Perl's stand-alone man pages\-\-those contained
+within \f(CW\*(C`.pod\*(C'\fR files\-\-do not need to include any copyright or license
+information about themselves. Their source Pod files are part of Perl's
+own core software repository, and that already covers them under the
+same copyright and license terms as Perl itself. You do not need to
+include additional "LICENSE" or "COPYRIGHT" sections of your own.
+.PP
+These man pages may optionally credit their primary author, or include a
+list of significant contributors, under "AUTHOR" or "CONTRIBUTORS"
+headings. Note that the presence of authors' names does not preclude a
+given page from writing in a voice consistent with the rest of Perl's
+documentation.
+.PP
+Note that these guidelines do not apply to the core software modules
+that ship with Perl. These have their own standards for authorship and
+copyright statements, as found in \f(CW\*(C`perlpodstyle\*(C'\fR.
+.SS "Formatting rules"
+.IX Subsection "Formatting rules"
+\fILine length and line wrap\fR
+.IX Subsection "Line length and line wrap"
+.PP
+Each line within a Perl man page's Pod source file should measure 72
+characters or fewer in length.
+.PP
+Please break paragraphs up into blocks of short lines, rather than
+"soft wrapping" paragraphs across hundreds of characters with no line
+breaks.
+.PP
+\fICode blocks\fR
+.IX Subsection "Code blocks"
+.PP
+Just like the text around them, all code examples should be as short and
+readable as possible, displaying no more complexity than absolutely
+necessary to illustrate the concept at hand.
+.PP
+For the sake of consistency within and across Perl's man pages, all
+examples must adhere to the code-layout principles set out by
+\&\f(CW\*(C`perlstyle\*(C'\fR.
+.PP
+Sample code should deviate from these standards only when necessary:
+during a demonstration of how Perl disregards whitespace, for example,
+or to temporarily switch to two-column indentation for an unavoidably
+verbose illustration.
+.PP
+You may include comments within example code to further clarify or label
+the code's behavior in-line. You may also use comments as placeholder
+for code normally present but not relevant to the current topic, like
+so:
+.PP
+.Vb 5
+\&    while (my $line = <$fh>) {
+\&        #
+\&        # (Do something interesting with $line here.)
+\&        #
+\&    }
+.Ve
+.PP
+Even the simplest code blocks often require the use of example
+variables and subroutines, whose names you should choose with
+care.
+.PP
+\fIInline code and literals\fR
+.IX Subsection "Inline code and literals"
+.PP
+Within a paragraph of text, use \f(CW\*(C`C<...>\*(C'\fR when quoting or
+referring to any bit of Perl code\-\-even if it is only one character
+long.
+.PP
+For instance, when referring within an explanatory paragraph to Perl's
+operator for adding two numbers together, you'd write "\f(CW\*(C`C<+>\*(C'\fR".
+.PP
+\fIFunction names\fR
+.IX Subsection "Function names"
+.PP
+Use \f(CW\*(C`C<...>\*(C'\fR to render all Perl function names in monospace,
+whenever they appear in text.
+.PP
+Unless you need to specifically quote a function call with a list of
+arguments, do not follow a function's name in text with a pair of empty
+parentheses. That is, when referring in general to Perl's \f(CW\*(C`print\*(C'\fR
+function, write it as "\f(CW\*(C`print\*(C'\fR", not "\f(CWprint()\fR".
+.PP
+\fIFunction arguments\fR
+.IX Subsection "Function arguments"
+.PP
+Represent functions' expected arguments in all-caps, with no sigils, and
+using \f(CW\*(C`C<...>\*(C'\fR to render them in monospace. These arguments
+should have short names making their nature and purpose clear.
+Convention specifies a few ones commonly seen throughout Perl's
+documentation:
+.IP \(bu 4
+EXPR
+.Sp
+The "generic" argument: any scalar value, or a Perl expression that
+evaluates to one.
+.IP \(bu 4
+ARRAY
+.Sp
+An array, stored in a named variable.
+.IP \(bu 4
+HASH
+.Sp
+A hash, stored in a named variable.
+.IP \(bu 4
+BLOCK
+.Sp
+A curly-braced code block, or a subroutine reference.
+.IP \(bu 4
+LIST
+.Sp
+Any number of values, stored across any number of variables or
+expressions, which the function will "flatten" and treat as a single
+list. (And because it can contain any number of variables, it must be
+the \fIlast\fR argument, when present.)
+.PP
+When possible, give scalar arguments names that suggest their purpose
+among the arguments. See, for example, \f(CW\*(C`substr\*(C'\fR's
+documentation, whose
+listed arguments include \f(CW\*(C`EXPR\*(C'\fR, \f(CW\*(C`OFFSET\*(C'\fR, \f(CW\*(C`LENGTH\*(C'\fR, and \f(CW\*(C`REPLACEMENT\*(C'\fR.
+.PP
+\fIApostrophes, quotes, and dashes\fR
+.IX Subsection "Apostrophes, quotes, and dashes"
+.PP
+In Pod source, use straight quotes, and not "curly quotes":  "Like
+ this", not “like this�. The same goes for apostrophes:  Here's a
+ positive example, and here’s a negative one.
+.PP
+Render em dashes as two hyphens\-\-like this:
+.PP
+.Vb 1
+\&    Render em dashes as two hyphens\-\-like this.
+.Ve
+.PP
+Leave it up to formatters to reformat and reshape these punctuation
+marks as best fits their respective target media.
+.PP
+\fIUnix programs and C functions\fR
+.IX Subsection "Unix programs and C functions"
+.PP
+When referring to a Unix program or C function with its own man page
+(outside of Perl's documentation), include its manual section number in
+parentheses. For example: \f(CWmalloc(3)\fR, or \f(CWmkdir(1)\fR.
+.PP
+If mentioning this program for the first time within a man page or
+section, make it a cross reference, e.g. \f(CW\*(C`L<malloc(3)>\*(C'\fR.
+.PP
+Do not otherwise style this text.
+.PP
+\fICross-references and hyperlinks\fR
+.IX Subsection "Cross-references and hyperlinks"
+.PP
+Make generous use of Pod's \f(CW\*(C`L<...>\*(C'\fR syntax to create hyperlinks
+to other parts of the current man page, or to other documents entirely
+\&\-\- whether elsewhere on the reader's computer, or somewhere on the
+internet, via URL.
+.PP
+Use \f(CW\*(C`L<...>\*(C'\fR to link to another section of the current man page
+when mentioning it, and make use of its page-and-section syntax to link to
+the most specific section of a separate page within Perl's
+documentation. Generally, the first time you refer to a specific
+function, program, or concept within a certain page or section, consider
+linking to its full documentation.
+.PP
+Hyperlinks do not supersede other formatting required by this guide; Pod
+allows nested text formats, and you should use this feature as needed.
+.PP
+Here is an example sentence that mentions Perl's \f(CW\*(C`say\*(C'\fR function, with a
+link to its documentation section within the \f(CW\*(C`perlfunc\*(C'\fR man page:
+.PP
+.Vb 2
+\&    In version 5.10, Perl added support for the 
+\&    L<C<say>|perlfunc/say FILEHANDLE LIST> function.
+.Ve
+.PP
+Note the use of the vertical pipe ("\f(CW\*(C`|\*(C'\fR") to separate how the link will
+appear to readers ("\f(CW\*(C`C<say>\*(C'\fR") from the full page-and-section specifier
+that the formatter links to.
+.PP
+\fITables and diagrams\fR
+.IX Subsection "Tables and diagrams"
+.PP
+Pod does not officially support tables. To best present tabular data,
+include the table as both HTML and plain-text representations\-\-the
+latter as an indented code block. Use \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR directives to
+target these tables at \f(CW\*(C`html\*(C'\fR and \f(CW\*(C`text\*(C'\fR Pod formatters, respectively.
+For example:
+.PP
+.Vb 1
+\&    =head2 Table of fruits
+\&
+\&    =begin text
+\&
+\&     Name           Shape           Color
+\&     =====================================
+\&     Apple          Round           Red
+\&     Banana         Long            Yellow
+\&     Pear           Pear\-shaped     Green
+\&
+\&    =end text
+\&
+\&    =begin html
+\&
+\&    <table>
+\&    <tr><th>Name</th><th>Shape</th><th>Color</th></tr>
+\&    <tr><td>Apple</td><td>Round</td><td>Red</td></tr>
+\&    <tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>
+\&    <tr><td>Pear</td><td>Pear\-shaped</td><td>Green</td></tr>
+\&    </table>
+\&
+\&    =end html
+.Ve
+.PP
+The same holds true for figures and graphical illustrations. Pod does
+not natively support inline graphics, but you can mix HTML \f(CW\*(C`<img>\*(C'\fR tags
+with monospaced text-art representations of those images' content.
+.PP
+Due in part to these limitations, most Perl man pages use neither tables
+nor diagrams. Like any other tool in your documentation toolkit,
+however, you may consider their inclusion when they would improve an
+explanation's clarity without adding to its complexity.
+.SS "Adding comments"
+.IX Subsection "Adding comments"
+Like any other kind of source code, Pod lets you insert comments visible
+only to other people reading the source directly, and ignored by the
+formatting programs that transform Pod into various human-friendly
+output formats (such as HTML or PDF).
+.PP
+To comment Pod text, use the \f(CW\*(C`=for\*(C'\fR and \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR Pod
+directives, aiming them at a (notional) formatter called "\f(CW\*(C`comment\*(C'\fR". A
+couple of examples:
+.PP
+.Vb 2
+\&    =for comment Using "=for comment" like this is good for short,
+\&    single\-paragraph comments.
+\&
+\&    =begin comment
+\&
+\&    If you need to comment out more than one paragraph, use a
+\&    =begin/=end block, like this.
+\&
+\&    None of the text or markup in this whole example would be visible to
+\&    someone reading the documentation through normal means, so it\*(Aqs
+\&    great for leaving notes, explanations, or suggestions for your
+\&    fellow documentation writers.
+\&
+\&    =end comment
+.Ve
+.PP
+In the tradition of any good open-source project, you should make free
+but judicious use of comments to leave in-line "meta-documentation" as
+needed for other Perl documentation writers (including your future
+self).
+.SS "Perlfunc has special rules"
+.IX Subsection "Perlfunc has special rules"
+The \f(CW\*(C`perlfunc\*(C'\fR man page, an exhaustive reference of every
+Perl built-in function, has a handful of formatting rules not seen
+elsewhere in Perl's documentation.
+.PP
+Software used during Perl's build process
+(Pod::Functions) parses this page according to certain
+rules, in order to build separate man pages for each of Perl's
+functions, as well as achieve other indexing effects. As such,
+contributors to perlfunc must know about and adhere to its particular
+rules.
+.PP
+Most of the perfunc man page comprises a single list, found under the
+header "Alphabetical Listing of Perl Functions". Each function reference is an entry on that
+list, made of three parts, in order:
+.IP 1. 4
+A list of \f(CW\*(C`=item\*(C'\fR lines which each demonstrate, in template format, a
+way to call this function. One line should exist for every combination
+of arguments that the function accepts (including no arguments at all,
+if applicable).
+.Sp
+If modern best practices prefer certain ways to invoke the function
+over others, then those ways should lead the list.
+.Sp
+The first item of the list should be immediately followed by one or
+more \f(CW\*(C`X<...>\*(C'\fR terms listing index-worthy topics; if nothing
+else, then the name of the function, with no arguments.
+.IP 2. 4
+A \f(CW\*(C`=for\*(C'\fR line, directed at \f(CW\*(C`Pod::Functions\*(C'\fR, containing a one-line
+description of what the function does. This is written as a phrase, led
+with an imperative verb, with neither leading capitalization nor ending
+punctuation. Examples include "quote a list of words" and "change a
+filename".
+.IP 3. 4
+The function's definition and reference material, including all
+explanatory text and code examples.
+.PP
+Complex functions that need their text divided into subsections (under
+the principles of "Apply section-breaks and examples
+generously") may do so by
+using sublists, with \f(CW\*(C`=item\*(C'\fR elements as header text.
+.PP
+A fictional function "\f(CW\*(C`myfunc\*(C'\fR", which takes a list as an optional
+argument, might have an entry in perlfunc shaped like this:
+.PP
+.Vb 2
+\&    =item myfunc LIST
+\&    X<myfunc>
+\&
+\&    =item myfunc
+\&
+\&    =for Pod::Functions demonstrate a function\*(Aqs perlfunc section 
+\&
+\&    [ Main part of function definition goes here, with examples ]
+\&
+\&    =over
+\&
+\&    =item Legacy uses
+\&
+\&    [ Examples of deprecated syntax still worth documenting ]
+\&
+\&    =item Security considerations
+\&
+\&    [ And so on... ]
+\&
+\&    =back
+.Ve
+.SH "TONE AND STYLE"
+.IX Header "TONE AND STYLE"
+.SS "Apply one of the four documentation modes"
+.IX Subsection "Apply one of the four documentation modes"
+Aside from "meta" documentation such as \f(CW\*(C`perlhist\*(C'\fR or \f(CW\*(C`perlartistic\*(C'\fR,
+each of Perl's man pages should conform to one of the four documentation
+"modes" suggested by \fIThe Documentation System\fR by Daniele
+Procida <https://documentation.divio.com>. These include tutorials,
+cookbooks, explainers, and references\-\-terms that we define in further
+detail below.
+.PP
+Each mode of documentation speaks to a different audience\-\-not just
+people of different backgrounds and skill levels, but individual readers
+whose needs from language documentation can shift depending upon
+context. For example, a programmer with plenty of time to learn a new
+concept about Perl can ease into a tutorial about it, and later expand
+their knowledge further by studying an explainer. Later, that same
+programmer, wading knee-deep in live code and needing only to look up
+some function's exact syntax, will want to reach for a reference page
+instead.
+.PP
+Perl's documentation must strive to meet these different situational
+expectations by limiting each man page to a single mode. This helps
+writers ensure they provide readers with the documentation needed or
+expected, despite ever-evolving situations.
+.PP
+\fITutorial\fR
+.IX Subsection "Tutorial"
+.PP
+A tutorial man page focuses on \fBlearning\fR, ideally by \fIdoing\fR. It
+presents the reader with small, interesting examples that allow them to
+follow along themselves using their own Perl interpreter. The tutorial
+inspires comprehension by letting its readers immediately experience
+(and experiment on) the concept in question. Examples include
+\&\f(CW\*(C`perlxstut\*(C'\fR, \f(CW\*(C`perlpacktut\*(C'\fR, and
+\&\f(CW\*(C`perlretut\*(C'\fR.
+.PP
+Tutorial man pages must strive for a welcoming and reassuring tone from
+their outset; they may very well be the first things that a newcomer to
+Perl reads, playing a significant role in whether they choose
+to stick around. Even an experienced programmer can benefit from the
+sense of courage imparted by a strong tutorial about a more advanced
+topic. After completing a tutorial, a reader should feel like they've
+been led from zero knowledge of its topic to having an invigorating
+spark of basic understanding, excited to learn more and experiment
+further.
+.PP
+Tutorials can certainly use real-world examples when that helps make for
+clear, relatable demonstrations, so long as they keep the focus on
+teaching\-\-more practical problem-solving should be left to the realm
+of cookbooks (as described below). Tutorials also needn't concern
+themselves with explanations into why or how things work beneath the
+surface, or explorations of alternate syntaxes and solutions; these are
+better handled by explainers and reference pages.
+.PP
+\fICookbook\fR
+.IX Subsection "Cookbook"
+.PP
+A cookbook man page focuses on \fBresults\fR. Just like its name suggests,
+it presents succinct, step-by-step solutions to a variety of real-world
+problems around some topic. A cookbook's code examples serve less to
+enlighten and more to provide quick, paste-ready solutions that the
+reader can apply immediately to the situation facing them.
+.PP
+A Perl cookbook demonstrates ways that all the tools and techniques
+explained elsewhere can work together in order to achieve practical
+results. Any explanation deeper than that belongs in explainers and
+reference pages, instead. (Certainly, a cookbook can cross-reference
+other man pages in order to satisfy the curiosity of readers who, with
+their immediate problems solved, wish to learn more.)
+.PP
+The most prominent cookbook pages that ship with Perl itself are its
+many FAQ pages, in particular \f(CW\*(C`perlfaq4\*(C'\fR and up, which provide short
+solutions to practical questions in question-and-answer style.
+\&\f(CW\*(C`perlunicook\*(C'\fR shows another example, containing a bevy of practical code
+snippets for a variety of internationally minded text manipulations.
+.PP
+(An aside: \fIThe Documentation System\fR calls this mode "how-to", but
+Perl's history of creative cuisine prefers the more kitchen-ready term
+that we employ here.)
+.PP
+\fIReference\fR
+.IX Subsection "Reference"
+.PP
+A reference page focuses on \fBdescription\fR. Austere, uniform, and
+succinct, reference pages\-\-often arranged into a whole section of
+mutually similar subpages\-\-lend themselves well to "random access" by
+a reader who knows precisely what knowledge they need, requiring only
+the minimum amount of information before returning to the task at hand.
+.PP
+Perl's own best example of a reference work is \f(CW\*(C`perlfunc\*(C'\fR, the
+sprawling man page that details the operation of every function built
+into Perl, with each function's documentation presenting the same kinds
+of information in the same order as every other. For an example of a
+shorter reference on a single topic, look at \f(CW\*(C`perlreref\*(C'\fR.
+.PP
+Module documentation\-\-including that of all the modules listed in
+\&\f(CW\*(C`perlmodlib\*(C'\fR\-\-also counts as reference. They follow
+precepts similar to those laid down by the \f(CW\*(C`perlpodstyle\*(C'\fR man page, such
+as opening with an example-laden "SYNOPSIS" section, or featuring a
+"METHODS" section that succinctly lists and defines an object-oriented
+module's public interface.
+.PP
+\fIExplainer\fR
+.IX Subsection "Explainer"
+.PP
+Explainer pages focus on \fBdiscussion\fR. Each explainer dives as deep as
+needed into some Perl-relevant topic, taking all the time and space
+needed to give the reader a thorough understanding of it. Explainers
+mean to impart knowledge through study. They don't assume that the
+student has a Perl interpreter fired up and hungry for immediate examples
+(as with a tutorial), or specific Perl problems that they need quick
+answers for (which cookbooks and reference pages can help with).
+.PP
+Outside of its reference pages, most of Perl's manual belongs to this
+mode. This includes the majority of the man pages whose names start with
+"\f(CW\*(C`perl\*(C'\fR". A fine example is \f(CW\*(C`perlsyn\*(C'\fR, the Perl Syntax page, which
+explores the whys and wherefores of Perl's unique syntax in a
+wide-ranging discussion laden with many references to the language's
+history, culture, and driving philosophies.
+.PP
+Perl's explainer pages give authors a chance to explore Perl's penchant
+for TMTOWTDI, illustrating alternate and even
+obscure ways to use the language feature under discussion. However, as
+the remainder of this guide discusses, the ideal Perl documentation
+manages to deliver its message clearly and concisely, and not confuse
+mere wordiness for completeness.
+.PP
+\fIFurther notes on documentation modes\fR
+.IX Subsection "Further notes on documentation modes"
+.PP
+Keep in mind that the purpose of this categorization is not to dictate
+content\-\-a very thorough explainer might contain short reference
+sections of its own, for example, or a reference page about a very
+complex function might resemble an explainer in places (e.g.
+\&\f(CW\*(C`open\*(C'\fR). Rather, it makes sure
+that the authors and contributors of any given man page agree on what
+sort of audience that page addresses.
+.PP
+If a new or otherwise uncategorized man page presents itself as
+resistant to fitting into only one of the four modes, consider breaking
+it up into separate pages. That may mean creating a new "\f(CW\*(C`perl[...]\*(C'\fR"
+man page, or (in the case of module documentation) making new packages
+underneath that module's namespace that serve only to hold additional
+documentation. For instance, \f(CW\*(C`Example::Module\*(C'\fR's reference documentation
+might include a see-also link to \f(CW\*(C`Example::Module::Cookbook\*(C'\fR.
+.PP
+Perl's several man pages about Unicode\-\-comprising a short tutorial, a
+thorough explainer, a cookbook, and a FAQ\-\-provide a fine example of
+spreading a complicated topic across several man pages with different
+and clearly indicated purposes.
+.SS "Assume readers' intelligence, but not their knowledge"
+.IX Subsection "Assume readers' intelligence, but not their knowledge"
+Perl has grown a great deal from its humble beginnings as a tool for
+people already well versed in C programming and various Unix utilities.
+Today, a person learning Perl might come from any social or
+technological background, with a range of possible motivations
+stretching far beyond system administration.
+.PP
+Perl's core documentation must recognize this by making as few
+assumptions as possible about the reader's prior knowledge. While you
+should assume that readers of Perl's documentation are smart, curious,
+and eager to learn, you should not confuse this for pre-existing
+knowledge about any other technology, or even programming in
+general\-\-especially in tutorial or introductory material.
+.PP
+\fIKeep Perl's documentation about Perl\fR
+.IX Subsection "Keep Perl's documentation about Perl"
+.PP
+Outside of pages tasked specifically with exploring Perl's relationship
+with other programming languages, the documentation should keep the
+focus on Perl. Avoid drawing analogies to other technologies that the
+reader may not have familiarity with.
+.PP
+For example, when documenting one of Perl's built-in functions, write as
+if the reader is now learning about that function for the first time, in
+any programming language.
+.PP
+Choosing to instead compare it to an equivalent or underlying C function
+will probably not illuminate much understanding in a contemporary
+reader. Worse, this can risk leaving readers unfamiliar with C feeling
+locked out from fully understanding of the topic\-\-to say nothing of
+readers new to computer programming altogether.
+.PP
+If, however, that function's ties to its C roots can lead to deeper
+understanding with practical applications for a Perl programmer, you may
+mention that link after its more immediately useful documentation.
+Otherwise, omit this information entirely, leaving it for other
+documentation or external articles more concerned with examining Perl's
+underlying implementation details.
+.PP
+\fIDeploy jargon when needed, but define it as well\fR
+.IX Subsection "Deploy jargon when needed, but define it as well"
+.PP
+Domain-specific jargon has its place, especially within documentation.
+However, if a man page makes use of jargon that a typical reader might
+not already know, then that page should make an effort to define the
+term in question early\-on\-\-either explicitly, or via cross reference.
+.PP
+For example, Perl loves working with filehandles, and as such that word
+appears throughout its documentation. A new Perl programmer arriving at
+a man page for the first time is quite likely to have no idea what a
+"filehandle" is, though. Any Perl man page mentioning filehandles
+should, at the very least, hyperlink that term to an explanation
+elsewhere in Perl's documentation. If appropriate\-\-for example, in the
+lead-in to \f(CW\*(C`open\*(C'\fR function's detailed reference\-\-it can also include a very short in-place
+definition of the concept for the reader's convenience.
+.SS "Use meaningful variable and symbol names in examples"
+.IX Subsection "Use meaningful variable and symbol names in examples"
+When quickly sketching out examples, English-speaking programmers have a
+long tradition of using short nonsense words as placeholders for
+variables and other symbols\-\-such as the venerable \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`bar\*(C'\fR, and
+\&\f(CW\*(C`baz\*(C'\fR. Example code found in a programming language's official,
+permanent documentation, however, can and should make an effort to
+provide a little more clarity through specificity.
+.PP
+Whenever possible, code examples should give variables, classes, and
+other programmer-defined symbols names that clearly demonstrate their
+function and their relationship to one another. For example, if an
+example requires that one class show an "is-a" relationship with
+another, consider naming them something like \f(CW\*(C`Apple\*(C'\fR and \f(CW\*(C`Fruit\*(C'\fR, rather
+than \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR. Similarly, sample code creating an instance of
+that class would do better to name it \f(CW$apple\fR, rather than \f(CW$baz\fR.
+.PP
+Even the simplest examples benefit from clear language using concrete
+words. Prefer a construct like \f(CW\*(C`for my $item (@items) { ... }\*(C'\fR over
+\&\f(CW\*(C`for my $blah (@blah) { ... }\*(C'\fR.
+.SS "Write in English, but not just for English-speakers"
+.IX Subsection "Write in English, but not just for English-speakers"
+While this style guide does specify American English as the
+documentation's language for the sake of internal consistency, authors
+should avoid cultural or idiomatic references available only to
+English-speaking Americans (or any other specific culture or society).
+As much as possible, the language employed by Perl's core documentation
+should strive towards cultural universality, if not neutrality. Regional
+turns of phrase, examples drawing on popular-culture knowledge, and
+other rhetorical techniques of that nature should appear sparingly, if
+at all.
+.PP
+Authors should feel free to let more freewheeling language flourish in
+"second-order" documentation about Perl, like books, blog entries, and
+magazine articles, published elsewhere and with a narrower readership in
+mind. But Perl's own docs should use language as accessible and
+welcoming to as wide an audience as possible.
+.SS "Omit placeholder text or commentary"
+.IX Subsection "Omit placeholder text or commentary"
+Placeholder text does not belong in the documentation that ships with
+Perl. No section header should be followed by text reading only "Watch
+this space", "To be included later", or the like. While Perl's source
+files may shift and alter as much as any other actively maintained
+technology, each released iteration of its technology should feel
+complete and self-contained, with no such future promises or other loose
+ends visible.
+.PP
+Take advantage of Perl's regular release cycle. Instead of cluttering
+the docs with flags promising more information later\-\-the presence of
+which do not help readers at all today\-\-the documentation's
+maintenance team should treat any known documentation absences as an
+issue to address like any other in the Perl project. Let Perl's
+contributors, testers, and release engineers address that need, and
+resist the temptation to insert apologies, which have all the utility in
+documentation as undeleted debug messages do in production code.
+.SS "Apply section-breaks and examples generously"
+.IX Subsection "Apply section-breaks and examples generously"
+No matter how accessible their tone, the sight of monolithic blocks of
+text in technical documentation can present a will-weakening challenge
+for the reader. Authors can improve this situation through breaking long
+passages up into subsections with short, meaningful headers.
+.PP
+Since every section-header in Pod also acts as a potential end-point for
+a cross-reference (made via Pod's \f(CW\*(C`L<...>\*(C'\fR syntax), putting
+plenty of subsections in your documentation lets other man pages more
+precisely link to a particular topic. This creates hyperlinks directly
+to the most appropriate section rather than to the whole page in
+general, and helps create a more cohesive sense of a rich, consistent,
+and interrelated manual for readers.
+.PP
+Among the four documentation modes, sections belong more naturally in
+tutorials and explainers. The step-by-step instructions of cookbooks, or
+the austere definitions of reference pages, usually have no room for
+them. But authors can always make exceptions for unusually complex
+concepts that require further breakdown for clarity's sake.
+.PP
+Example code, on the other hand, can be a welcome addition to any mode
+of documentation. Code blocks help break up a man page visually,
+reassuring the reader that no matter how deep the textual explanation
+gets, they are never far from another practical example showing how it
+all comes together using a small, easy-to-read snippet of tested Perl
+code.
+.SS "Lead with common cases and best practices"
+.IX Subsection "Lead with common cases and best practices"
+Perl famously gives programmers more than one way to do things. Like any
+other long-lived programming language, Perl has also built up a large,
+community-held notion of best practices, blessing some ways to do things
+as better than others, usually for the sake of more maintainable code.
+.PP
+\fIShow the better ways first\fR
+.IX Subsection "Show the better ways first"
+.PP
+Whenever it needs to show the rules for a technique which Perl provides
+many avenues for, the documentation should always lead with best
+practices. And when discussing some part of the Perl toolkit with many
+applications, the docs should begin with a demonstration of its
+application to the most common cases.
+.PP
+The \f(CW\*(C`open\*(C'\fR function, for example, has myriad potential uses within Perl
+programs, but \fImost of the time\fR programmers\-\-and especially those new
+to Perl\-\-turn to this reference because they simply wish to open a
+file for reading or writing. For this reason, \f(CW\*(C`open\*(C'\fR's documentation
+begins there, and only descends into the function's more obscure uses
+after thoroughly documenting and demonstrating how it works in the
+common case. Furthermore, while engaging in this demonstration, the
+\&\f(CW\*(C`open\*(C'\fR documentation does not burden the reader right away with detailed
+explanations about calling \f(CW\*(C`open\*(C'\fR via any route other than the
+best-practice, three-argument style.
+.PP
+\fIShow the lesser ways when needed\fR
+.IX Subsection "Show the lesser ways when needed"
+.PP
+Sometimes, thoroughness demands documentation of deprecated techniques.
+For example, a certain Perl function might have an alternate syntax now
+considered outmoded and no longer best-practice, but which a maintainer
+of a legacy project might quite reasonably encounter when exploring old
+code. In this case, these features deserve documentation, but couched in
+clarity that modern Perl avoids such structures, and does not recommend
+their use in new projects.
+.PP
+Another way to look at this philosophy (and one borrowed from our
+friends <https://devguide.python.org/documenting/#affirmative-tone> on
+Python's documentation team) involves writing while sympathizing with a
+programmer new to Perl, who may feel uncertain about learning a complex
+concept. By leading that concept's main documentation with clear,
+positive examples, we can immediately give these readers a simple and
+true picture of how it works in Perl, and boost their own confidence to
+start making use of this new knowledge. Certainly we should include
+alternate routes and admonitions as reasonably required, but we needn't
+emphasize them. Trust the reader to understand the basics quickly, and
+to keep reading for a deeper understanding if they feel so driven.
+.SS "Document Perl's present"
+.IX Subsection "Document Perl's present"
+Perl's documentation should stay focused on Perl's present behavior,
+with a nod to future directions.
+.PP
+\fIRecount the past only when necessary\fR
+.IX Subsection "Recount the past only when necessary"
+.PP
+When some Perl feature changes its behavior, documentation about
+that feature should change too, and just as definitively. The docs have
+no obligation to keep descriptions of past behavior hanging around, even if
+attaching clauses like "Prior to version 5.10, [...]".
+.PP
+Since Perl's core documentation is part of Perl's source distribution,
+it enjoys the same benefits of versioning and version-control as the
+source code of Perl itself. Take advantage of this, and update the text
+boldly when needed. Perl's history remains safe, even when you delete or
+replace outdated information from the current version's docs.
+.PP
+Perl's docs can acknowledge or discuss former behavior when warranted,
+including notes that some feature appeared in the language as of some
+specific version number. Authors should consider applying principles
+similar to those for deprecated techniques, as described above: make the information present, but not
+prominent.
+.PP
+Otherwise, keep the past in the past. A manual uncluttered with
+outdated instruction stays more succinct and relevant.
+.PP
+\fIDescribe the uncertain future with care\fR
+.IX Subsection "Describe the uncertain future with care"
+.PP
+Perl features marked as "experimental"\-\-those that generate warnings
+when used in code not invoking the \f(CW\*(C`experimental\*(C'\fR
+pragma\-\-deserve documentation, but only in certain contexts, and even
+then with caveats. These features represent possible new directions for
+Perl, but they have unstable interfaces and uncertain future presence.
+.PP
+The documentation should take both implications of "experimental"
+literally. It should not discourage these features' use by programmers
+who wish to try out new features in projects that can risk their
+inherent instability; this experimentation can help Perl grow and
+improve. By the same token, the docs should downplay these features' use
+in just about every other context.
+.PP
+Introductory or overview material should omit coverage of experimental
+features altogether.
+.PP
+More thorough reference materials or explanatory articles can include
+experimental features, but needs to clearly mark them as such, and not
+treat them with the same prominence as Perl's stable features. Using
+unstable features seldom coincides with best practices, and
+documentation that puts best practices first should reflect this.
+.SS "The documentation speaks with one voice"
+.IX Subsection "The documentation speaks with one voice"
+Even though it comes from many hands and minds, criss-crossing through
+the many years of Perl's lifetime, the language's documentation should
+speak with a single, consistent voice. With few exceptions, the docs
+should avoid explicit first-person-singular statements, or similar
+self-reference to any individual's contributor's philosophies or
+experiences.
+.PP
+Perl did begin life as a deeply personal expression by a single
+individual, and this famously carried through the first revisions of its
+documentation as well. Today, Perl's community understands that the
+language's continued development and support comes from many people
+working in concert, rather than any one person's vision or effort. Its
+documentation should not pretend otherwise.
+.PP
+The documentation should, however, carry forward the best tradition that
+Larry Wall set forth in the language's earliest days: Write both
+economically and with a humble, subtle wit, resulting in a technical
+manual that mixes concision with a friendly approachability. It avoids
+the dryness that one might expect from technical documentation, while
+not leaning so hard into overt comedy as to distract and confuse from
+the nonetheless-technical topics at hand.
+.PP
+Like the best written works, Perl's documentation has a soul. Get
+familiar with it as a reader to internalize its voice, and then find
+your own way to express it in your own contributions. Writing clearly,
+succinctly, and with knowledge of your audience's expectations will get
+you most of the way there, in the meantime.
+.PP
+Every line in the docs\-\-whether English sentence or Perl
+statement\-\-should serve the purpose of bringing understanding to the
+reader. Should a sentence exist mainly to make a wry joke that doesn't
+further the reader's knowledge of Perl, set it aside, and consider
+recasting it into a personal blog post or other article instead.
+.PP
+Write with a light heart, and a miserly hand.
+.SH "INDEX OF PREFERRED TERMS"
+.IX Header "INDEX OF PREFERRED TERMS"
+As noted above, this guide
+"inherits" all the preferred terms listed in the Chicago Manual of
+Style, 17th edition, and adds the following terms of particular interest
+to Perl documentation.
+.IP "built-in function" 4
+.IX Item "built-in function"
+Not "builtin".
+.IP Darwin 4
+.IX Item "Darwin"
+See macOS.
+.IP macOS 4
+.IX Item "macOS"
+Use this term for Apple's operating system instead of "Mac OS X" or
+variants thereof.
+.Sp
+This term is also preferable to "Darwin", unless one needs to refer
+to macOS's Unix layer specifically.
+.IP "man page" 4
+.IX Item "man page"
+One unit of Unix-style documentation. Not "manpage". Preferable to "manual page".
+.IP "Perl; perl" 4
+.IX Item "Perl; perl"
+The name of the programming language is Perl, with a leading capital
+"P", and the remainder in lowercase. (Never "PERL".)
+.Sp
+The interpreter program that reads and executes Perl code is named
+"\f(CW\*(C`perl\*(C'\fR", in lowercase and in monospace (as with any other command
+name).
+.Sp
+Generally, unless you are specifically writing about the
+command-line \f(CW\*(C`perl\*(C'\fR program (as, for example, \f(CW\*(C`perlrun\*(C'\fR
+does), use "Perl" instead.
+.IP "Perl 5" 4
+.IX Item "Perl 5"
+Documentation need not follow Perl's name with a "5", or any other
+number, except during discussions of Perl's history, future plans,
+or explicit comparisons between major Perl versions.
+.Sp
+Before 2019, specifying "Perl 5" was sometimes needed to distinguish
+the language from Perl 6. With the latter's renaming to "Raku", this
+practice became unnecessary.
+.IP "Perl 6" 4
+.IX Item "Perl 6"
+See Raku.
+.IP "Perl 5 Porters, the; porters, the; p5p" 4
+.IX Item "Perl 5 Porters, the; porters, the; p5p"
+The full name of the team responsible for Perl's ongoing maintenance
+and development is "the Perl 5 Porters", and this sobriquet should
+be spelled out in the first mention within any one document. It may
+thereafter call the team "the porters" or "p5p".
+.Sp
+Not "Perl5 Porters".
+.IP program 4
+.IX Item "program"
+The most general descriptor for a stand-alone work made out of
+executable Perl code. Synonymous with, and preferable to, "script".
+.IP Raku 4
+.IX Item "Raku"
+Perl's "sister language", whose homepage is <https://raku.org>.
+.Sp
+Previously known as "Perl 6". In 2019, its design team renamed the
+language to better reflect its identity as a project independent from
+Perl. As such, Perl's documentation should always refer to this language
+as "Raku" and not "Perl 6".
+.IP script 4
+.IX Item "script"
+See program.
+.IP semicolon 4
+.IX Item "semicolon"
+Perl code's frequently overlooked punctuation mark. Not "semi-colon".
+.IP Unix 4
+.IX Item "Unix"
+Not "UNIX", "*nix", or "Un*x". Applicable to both the original operating
+system from the 1970s as well as all its conceptual descendants. You may
+simply write "Unix" and not "a Unix-like operating system" when
+referring to a Unix-like operating system.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP \(bu 4
+perlpod
+.IP \(bu 4
+perlpodstyle
+.SH AUTHOR
+.IX Header "AUTHOR"
+This guide was initially drafted by Jason McIntosh
+(jmac@jmac.org), under a grant from The Perl Foundation.
diff --git a/upstream/mageia-cauldron/man1/perldsc.1 b/upstream/mageia-cauldron/man1/perldsc.1
new file mode 100644
index 00000000..eaf49b48
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldsc.1
@@ -0,0 +1,964 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDSC 1"
+.TH PERLDSC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldsc \- Perl Data Structures Cookbook
+.IX Xref "data structure complex data structure struct"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl lets us have complex data structures.  You can write something like
+this and all of a sudden, you'd have an array with three dimensions!
+.PP
+.Vb 8
+\&    for my $x (1 .. 10) {
+\&        for my $y (1 .. 10) {
+\&            for my $z (1 .. 10) {
+\&                $AoA[$x][$y][$z] =
+\&                    $x ** $y + $z;
+\&            }
+\&        }
+\&    }
+.Ve
+.PP
+Alas, however simple this may appear, underneath it's a much more
+elaborate construct than meets the eye!
+.PP
+How do you print it out?  Why can't you say just \f(CW\*(C`print @AoA\*(C'\fR?  How do
+you sort it?  How can you pass it to a function or get one of these back
+from a function?  Is it an object?  Can you save it to disk to read
+back later?  How do you access whole rows or columns of that matrix?  Do
+all the values have to be numeric?
+.PP
+As you see, it's quite easy to become confused.  While some small portion
+of the blame for this can be attributed to the reference-based
+implementation, it's really more due to a lack of existing documentation with
+examples designed for the beginner.
+.PP
+This document is meant to be a detailed but understandable treatment of the
+many different sorts of data structures you might want to develop.  It
+should also serve as a cookbook of examples.  That way, when you need to
+create one of these complex data structures, you can just pinch, pilfer, or
+purloin a drop-in example from here.
+.PP
+Let's look at each of these possible constructs in detail.  There are separate
+sections on each of the following:
+.IP \(bu 5
+arrays of arrays
+.IP \(bu 5
+hashes of arrays
+.IP \(bu 5
+arrays of hashes
+.IP \(bu 5
+hashes of hashes
+.IP \(bu 5
+more elaborate constructs
+.PP
+But for now, let's look at general issues common to all
+these types of data structures.
+.SH REFERENCES
+.IX Xref "reference dereference dereferencing pointer"
+.IX Header "REFERENCES"
+The most important thing to understand about all data structures in
+Perl\-\-including multidimensional arrays\-\-is that even though they might
+appear otherwise, Perl \f(CW@ARRAY\fRs and \f(CW%HASH\fRes are all internally
+one-dimensional.  They can hold only scalar values (meaning a string,
+number, or a reference).  They cannot directly contain other arrays or
+hashes, but instead contain \fIreferences\fR to other arrays or hashes.
+.IX Xref "multidimensional array array, multidimensional"
+.PP
+You can't use a reference to an array or hash in quite the same way that you
+would a real array or hash.  For C or C++ programmers unused to
+distinguishing between arrays and pointers to the same, this can be
+confusing.  If so, just think of it as the difference between a structure
+and a pointer to a structure.
+.PP
+You can (and should) read more about references in perlref.
+Briefly, references are rather like pointers that know what they
+point to.  (Objects are also a kind of reference, but we won't be needing
+them right away\-\-if ever.)  This means that when you have something which
+looks to you like an access to a two-or-more-dimensional array and/or hash,
+what's really going on is that the base type is
+merely a one-dimensional entity that contains references to the next
+level.  It's just that you can \fIuse\fR it as though it were a
+two-dimensional one.  This is actually the way almost all C
+multidimensional arrays work as well.
+.PP
+.Vb 4
+\&    $array[7][12]                       # array of arrays
+\&    $array[7]{string}                   # array of hashes
+\&    $hash{string}[7]                    # hash of arrays
+\&    $hash{string}{\*(Aqanother string\*(Aq}     # hash of hashes
+.Ve
+.PP
+Now, because the top level contains only references, if you try to print
+out your array in with a simple \fBprint()\fR function, you'll get something
+that doesn't look very nice, like this:
+.PP
+.Vb 5
+\&    my @AoA = ( [2, 3], [4, 5, 7], [0] );
+\&    print $AoA[1][2];
+\&  7
+\&    print @AoA;
+\&  ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)
+.Ve
+.PP
+That's because Perl doesn't (ever) implicitly dereference your variables.
+If you want to get at the thing a reference is referring to, then you have
+to do this yourself using either prefix typing indicators, like
+\&\f(CW\*(C`${$blah}\*(C'\fR, \f(CW\*(C`@{$blah}\*(C'\fR, \f(CW\*(C`@{$blah[$i]}\*(C'\fR, or else postfix pointer arrows,
+like \f(CW\*(C`$a\->[3]\*(C'\fR, \f(CW\*(C`$h\->{fred}\*(C'\fR, or even \f(CW\*(C`$ob\->method()\->[3]\*(C'\fR.
+.SH "COMMON MISTAKES"
+.IX Header "COMMON MISTAKES"
+The two most common mistakes made in constructing something like
+an array of arrays is either accidentally counting the number of
+elements or else taking a reference to the same memory location
+repeatedly.  Here's the case where you just get the count instead
+of a nested array:
+.PP
+.Vb 4
+\&    for my $i (1..10) {
+\&        my @array = somefunc($i);
+\&        $AoA[$i] = @array;      # WRONG!
+\&    }
+.Ve
+.PP
+That's just the simple case of assigning an array to a scalar and getting
+its element count.  If that's what you really and truly want, then you
+might do well to consider being a tad more explicit about it, like this:
+.PP
+.Vb 4
+\&    for my $i (1..10) {
+\&        my @array = somefunc($i);
+\&        $counts[$i] = scalar @array;
+\&    }
+.Ve
+.PP
+Here's the case of taking a reference to the same memory location
+again and again:
+.PP
+.Vb 2
+\&    # Either without strict or having an outer\-scope my @array;
+\&    # declaration.
+\&
+\&    for my $i (1..10) {
+\&        @array = somefunc($i);
+\&        $AoA[$i] = \e@array;     # WRONG!
+\&    }
+.Ve
+.PP
+So, what's the big problem with that?  It looks right, doesn't it?
+After all, I just told you that you need an array of references, so by
+golly, you've made me one!
+.PP
+Unfortunately, while this is true, it's still broken.  All the references
+in \f(CW@AoA\fR refer to the \fIvery same place\fR, and they will therefore all hold
+whatever was last in \f(CW@array\fR!  It's similar to the problem demonstrated in
+the following C program:
+.PP
+.Vb 5
+\&    #include <pwd.h>
+\&    main() {
+\&        struct passwd *getpwnam(), *rp, *dp;
+\&        rp = getpwnam("root");
+\&        dp = getpwnam("daemon");
+\&
+\&        printf("daemon name is %s\enroot name is %s\en",
+\&                dp\->pw_name, rp\->pw_name);
+\&    }
+.Ve
+.PP
+Which will print
+.PP
+.Vb 2
+\&    daemon name is daemon
+\&    root name is daemon
+.Ve
+.PP
+The problem is that both \f(CW\*(C`rp\*(C'\fR and \f(CW\*(C`dp\*(C'\fR are pointers to the same location
+in memory!  In C, you'd have to remember to \fBmalloc()\fR yourself some new
+memory.  In Perl, you'll want to use the array constructor \f(CW\*(C`[]\*(C'\fR or the
+hash constructor \f(CW\*(C`{}\*(C'\fR instead.   Here's the right way to do the preceding
+broken code fragments:
+.IX Xref "[] {}"
+.PP
+.Vb 2
+\&    # Either without strict or having an outer\-scope my @array;
+\&    # declaration.
+\&
+\&    for my $i (1..10) {
+\&        @array = somefunc($i);
+\&        $AoA[$i] = [ @array ];
+\&    }
+.Ve
+.PP
+The square brackets make a reference to a new array with a \fIcopy\fR
+of what's in \f(CW@array\fR at the time of the assignment.  This is what
+you want.
+.PP
+Note that this will produce something similar:
+.PP
+.Vb 6
+\&    # Either without strict or having an outer\-scope my @array;
+\&    # declaration.
+\&    for my $i (1..10) {
+\&        @array = 0 .. $i;
+\&        $AoA[$i]\->@* = @array;
+\&    }
+.Ve
+.PP
+Is it the same?  Well, maybe so\-\-and maybe not.  The subtle difference
+is that when you assign something in square brackets, you know for sure
+it's always a brand new reference with a new \fIcopy\fR of the data.
+Something else could be going on in this new case with the
+\&\f(CW\*(C`$AoA[$i]\->@*\*(C'\fR dereference on the left-hand-side of the assignment.
+It all depends on whether \f(CW$AoA[$i]\fR had been undefined to start with,
+or whether it already contained a reference.  If you had already
+populated \f(CW@AoA\fR with references, as in
+.PP
+.Vb 1
+\&    $AoA[3] = \e@another_array;
+.Ve
+.PP
+Then the assignment with the indirection on the left-hand-side would
+use the existing reference that was already there:
+.PP
+.Vb 1
+\&    $AoA[3]\->@* = @array;
+.Ve
+.PP
+Of course, this \fIwould\fR have the "interesting" effect of clobbering
+\&\f(CW@another_array\fR.  (Have you ever noticed how when a programmer says
+something is "interesting", that rather than meaning "intriguing",
+they're disturbingly more apt to mean that it's "annoying",
+"difficult", or both?  :\-)
+.PP
+So just remember always to use the array or hash constructors with \f(CW\*(C`[]\*(C'\fR
+or \f(CW\*(C`{}\*(C'\fR, and you'll be fine, although it's not always optimally
+efficient.
+.PP
+Surprisingly, the following dangerous-looking construct will
+actually work out fine:
+.PP
+.Vb 4
+\&    for my $i (1..10) {
+\&        my @array = somefunc($i);
+\&        $AoA[$i] = \e@array;
+\&    }
+.Ve
+.PP
+That's because \fBmy()\fR is more of a run-time statement than it is a
+compile-time declaration \fIper se\fR.  This means that the \fBmy()\fR variable is
+remade afresh each time through the loop.  So even though it \fIlooks\fR as
+though you stored the same variable reference each time, you actually did
+not!  This is a subtle distinction that can produce more efficient code at
+the risk of misleading all but the most experienced of programmers.  So I
+usually advise against teaching it to beginners.  In fact, except for
+passing arguments to functions, I seldom like to see the gimme-a-reference
+operator (backslash) used much at all in code.  Instead, I advise
+beginners that they (and most of the rest of us) should try to use the
+much more easily understood constructors \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR instead of
+relying upon lexical (or dynamic) scoping and hidden reference-counting to
+do the right thing behind the scenes.
+.PP
+Note also that there exists another way to write a dereference!  These
+two lines are equivalent:
+.PP
+.Vb 2
+\&    $AoA[$i]\->@* = @array;
+\&    @{ $AoA[$i] } = @array;
+.Ve
+.PP
+The first form, called \fIpostfix dereference\fR is generally easier to
+read, because the expression can be read from left to right, and there
+are no enclosing braces to balance.  On the other hand, it is also
+newer.  It was added to the language in 2014, so you will often
+encounter the other form, \fIcircumfix dereference\fR, in older code.
+.PP
+In summary:
+.PP
+.Vb 4
+\&    $AoA[$i] = [ @array ];     # usually best
+\&    $AoA[$i] = \e@array;        # perilous; just how my() was that array?
+\&    $AoA[$i]\->@*  = @array;    # way too tricky for most programmers
+\&    @{ $AoA[$i] } = @array;    # just as tricky, and also harder to read
+.Ve
+.SH "CAVEAT ON PRECEDENCE"
+.IX Xref "dereference, precedence dereferencing, precedence"
+.IX Header "CAVEAT ON PRECEDENCE"
+Speaking of things like \f(CW\*(C`@{$AoA[$i]}\*(C'\fR, the following are actually the
+same thing:
+.IX Xref "->"
+.PP
+.Vb 2
+\&    $aref\->[2][2]       # clear
+\&    $$aref[2][2]        # confusing
+.Ve
+.PP
+That's because Perl's precedence rules on its five prefix dereferencers
+(which look like someone swearing: \f(CW\*(C`$ @ * % &\*(C'\fR) make them bind more
+tightly than the postfix subscripting brackets or braces!  This will no
+doubt come as a great shock to the C or C++ programmer, who is quite
+accustomed to using \f(CW*a[i]\fR to mean what's pointed to by the \fIi'th\fR
+element of \f(CW\*(C`a\*(C'\fR.  That is, they first take the subscript, and only then
+dereference the thing at that subscript.  That's fine in C, but this isn't C.
+.PP
+The seemingly equivalent construct in Perl, \f(CW$$aref[$i]\fR first does
+the deref of \f(CW$aref\fR, making it take \f(CW$aref\fR as a reference to an
+array, and then dereference that, and finally tell you the \fIi'th\fR value
+of the array pointed to by \f(CW$AoA\fR. If you wanted the C notion, you could
+write \f(CW\*(C`$AoA[$i]\->$*\*(C'\fR to explicitly dereference the \fIi'th\fR item,
+reading left to right.
+.ie n .SH "WHY YOU SHOULD ALWAYS ""use VERSION"""
+.el .SH "WHY YOU SHOULD ALWAYS \f(CWuse VERSION\fP"
+.IX Header "WHY YOU SHOULD ALWAYS use VERSION"
+If this is starting to sound scarier than it's worth, relax.  Perl has
+some features to help you avoid its most common pitfalls.  One way to avoid
+getting confused is to start every program with:
+.PP
+.Vb 1
+\&    use strict;
+.Ve
+.PP
+This way, you'll be forced to declare all your variables with \fBmy()\fR and
+also disallow accidental "symbolic dereferencing".  Therefore if you'd done
+this:
+.PP
+.Vb 5
+\&    my $aref = [
+\&        [ "fred", "barney", "pebbles", "bambam", "dino", ],
+\&        [ "homer", "bart", "marge", "maggie", ],
+\&        [ "george", "jane", "elroy", "judy", ],
+\&    ];
+\&
+\&    print $aref[2][2];
+.Ve
+.PP
+The compiler would immediately flag that as an error \fIat compile time\fR,
+because you were accidentally accessing \f(CW@aref\fR, an undeclared
+variable, and it would thereby remind you to write instead:
+.PP
+.Vb 1
+\&    print $aref\->[2][2]
+.Ve
+.PP
+Since Perl version 5.12, a \f(CW\*(C`use VERSION\*(C'\fR declaration will also enable the
+\&\f(CW\*(C`strict\*(C'\fR pragma.  In addition, it will also enable a feature bundle,
+giving more useful features.  Since version 5.36 it will also enable the
+\&\f(CW\*(C`warnings\*(C'\fR pragma.  Often the best way to activate all these things at
+once is to start a file with:
+.PP
+.Vb 1
+\&    use v5.36;
+.Ve
+.PP
+In this way, every file will start with \f(CW\*(C`strict\*(C'\fR, \f(CW\*(C`warnings\*(C'\fR, and many
+useful named features all switched on, as well as several older features
+being switched off (such as \f(CW\*(C`indirect\*(C'\fR).
+For more information, see "use VERSION" in perlfunc.
+.SH DEBUGGING
+.IX Xref "data structure, debugging complex data structure, debugging AoA, debugging HoA, debugging AoH, debugging HoH, debugging array of arrays, debugging hash of arrays, debugging array of hashes, debugging hash of hashes, debugging"
+.IX Header "DEBUGGING"
+You can use the debugger's \f(CW\*(C`x\*(C'\fR command to dump out complex data structures.
+For example, given the assignment to \f(CW$AoA\fR above, here's the debugger output:
+.PP
+.Vb 10
+\&    DB<1> x $AoA
+\&    $AoA = ARRAY(0x13b5a0)
+\&       0  ARRAY(0x1f0a24)
+\&          0  \*(Aqfred\*(Aq
+\&          1  \*(Aqbarney\*(Aq
+\&          2  \*(Aqpebbles\*(Aq
+\&          3  \*(Aqbambam\*(Aq
+\&          4  \*(Aqdino\*(Aq
+\&       1  ARRAY(0x13b558)
+\&          0  \*(Aqhomer\*(Aq
+\&          1  \*(Aqbart\*(Aq
+\&          2  \*(Aqmarge\*(Aq
+\&          3  \*(Aqmaggie\*(Aq
+\&       2  ARRAY(0x13b540)
+\&          0  \*(Aqgeorge\*(Aq
+\&          1  \*(Aqjane\*(Aq
+\&          2  \*(Aqelroy\*(Aq
+\&          3  \*(Aqjudy\*(Aq
+.Ve
+.SH "CODE EXAMPLES"
+.IX Header "CODE EXAMPLES"
+Presented with little comment here are short code examples illustrating
+access of various types of data structures.
+.SH "ARRAYS OF ARRAYS"
+.IX Xref "array of arrays AoA"
+.IX Header "ARRAYS OF ARRAYS"
+.SS "Declaration of an ARRAY OF ARRAYS"
+.IX Subsection "Declaration of an ARRAY OF ARRAYS"
+.Vb 5
+\& my @AoA = (
+\&        [ "fred", "barney" ],
+\&        [ "george", "jane", "elroy" ],
+\&        [ "homer", "marge", "bart" ],
+\&      );
+.Ve
+.SS "Generation of an ARRAY OF ARRAYS"
+.IX Subsection "Generation of an ARRAY OF ARRAYS"
+.Vb 4
+\& # reading from file
+\& while ( <> ) {
+\&     push @AoA, [ split ];
+\& }
+\&
+\& # calling a function
+\& for my $i ( 1 .. 10 ) {
+\&     $AoA[$i] = [ somefunc($i) ];
+\& }
+\&
+\& # using temp vars
+\& for my $i ( 1 .. 10 ) {
+\&     my @tmp = somefunc($i);
+\&     $AoA[$i] = [ @tmp ];
+\& }
+\&
+\& # add to an existing row
+\& push $AoA[0]\->@*, "wilma", "betty";
+.Ve
+.SS "Access and Printing of an ARRAY OF ARRAYS"
+.IX Subsection "Access and Printing of an ARRAY OF ARRAYS"
+.Vb 2
+\& # one element
+\& $AoA[0][0] = "Fred";
+\&
+\& # another element
+\& $AoA[1][1] =~ s/(\ew)/\eu$1/;
+\&
+\& # print the whole thing with refs
+\& for my $aref ( @AoA ) {
+\&     print "\et [ @$aref ],\en";
+\& }
+\&
+\& # print the whole thing with indices
+\& for my $i ( 0 .. $#AoA ) {
+\&     print "\et [ $AoA[$i]\->@* ],\en";
+\& }
+\&
+\& # print the whole thing one at a time
+\& for my $i ( 0 .. $#AoA ) {
+\&     for my $j ( 0 .. $AoA[$i]\->$#* ) {
+\&         print "elem at ($i, $j) is $AoA[$i][$j]\en";
+\&     }
+\& }
+.Ve
+.SH "HASHES OF ARRAYS"
+.IX Xref "hash of arrays HoA"
+.IX Header "HASHES OF ARRAYS"
+.SS "Declaration of a HASH OF ARRAYS"
+.IX Subsection "Declaration of a HASH OF ARRAYS"
+.Vb 5
+\& my %HoA = (
+\&        flintstones        => [ "fred", "barney" ],
+\&        jetsons            => [ "george", "jane", "elroy" ],
+\&        simpsons           => [ "homer", "marge", "bart" ],
+\&      );
+.Ve
+.SS "Generation of a HASH OF ARRAYS"
+.IX Subsection "Generation of a HASH OF ARRAYS"
+.Vb 6
+\& # reading from file
+\& # flintstones: fred barney wilma dino
+\& while ( <> ) {
+\&     next unless s/^(.*?):\es*//;
+\&     $HoA{$1} = [ split ];
+\& }
+\&
+\& # reading from file; more temps
+\& # flintstones: fred barney wilma dino
+\& while ( my $line = <> ) {
+\&     my ($who, $rest) = split /:\es*/, $line, 2;
+\&     my @fields = split \*(Aq \*(Aq, $rest;
+\&     $HoA{$who} = [ @fields ];
+\& }
+\&
+\& # calling a function that returns a list
+\& for my $group ( "simpsons", "jetsons", "flintstones" ) {
+\&     $HoA{$group} = [ get_family($group) ];
+\& }
+\&
+\& # likewise, but using temps
+\& for my $group ( "simpsons", "jetsons", "flintstones" ) {
+\&     my @members = get_family($group);
+\&     $HoA{$group} = [ @members ];
+\& }
+\&
+\& # append new members to an existing family
+\& push $HoA{flintstones}\->@*, "wilma", "betty";
+.Ve
+.SS "Access and Printing of a HASH OF ARRAYS"
+.IX Subsection "Access and Printing of a HASH OF ARRAYS"
+.Vb 2
+\& # one element
+\& $HoA{flintstones}[0] = "Fred";
+\&
+\& # another element
+\& $HoA{simpsons}[1] =~ s/(\ew)/\eu$1/;
+\&
+\& # print the whole thing
+\& foreach my $family ( keys %HoA ) {
+\&     print "$family: $HoA{$family}\->@* \en"
+\& }
+\&
+\& # print the whole thing with indices
+\& foreach my $family ( keys %HoA ) {
+\&     print "family: ";
+\&     foreach my $i ( 0 .. $HoA{$family}\->$#* ) {
+\&         print " $i = $HoA{$family}[$i]";
+\&     }
+\&     print "\en";
+\& }
+\&
+\& # print the whole thing sorted by number of members
+\& foreach my $family ( sort { $HoA{$b}\->@* <=> $HoA{$a}\->@* } keys %HoA ) {
+\&     print "$family: $HoA{$family}\->@* \en"
+\& }
+\&
+\& # print the whole thing sorted by number of members and name
+\& foreach my $family ( sort {
+\&                            $HoA{$b}\->@* <=> $HoA{$a}\->@*
+\&                                          ||
+\&                                      $a cmp $b
+\&            } keys %HoA )
+\& {
+\&     print "$family: ", join(", ", sort $HoA{$family}\->@* ), "\en";
+\& }
+.Ve
+.SH "ARRAYS OF HASHES"
+.IX Xref "array of hashes AoH"
+.IX Header "ARRAYS OF HASHES"
+.SS "Declaration of an ARRAY OF HASHES"
+.IX Subsection "Declaration of an ARRAY OF HASHES"
+.Vb 10
+\& my @AoH = (
+\&        {
+\&            Lead     => "fred",
+\&            Friend   => "barney",
+\&        },
+\&        {
+\&            Lead     => "george",
+\&            Wife     => "jane",
+\&            Son      => "elroy",
+\&        },
+\&        {
+\&            Lead     => "homer",
+\&            Wife     => "marge",
+\&            Son      => "bart",
+\&        }
+\&  );
+.Ve
+.SS "Generation of an ARRAY OF HASHES"
+.IX Subsection "Generation of an ARRAY OF HASHES"
+.Vb 10
+\& # reading from file
+\& # format: LEAD=fred FRIEND=barney
+\& while ( <> ) {
+\&     my $rec = {};
+\&     for my $field ( split ) {
+\&         my ($key, $value) = split /=/, $field;
+\&         $rec\->{$key} = $value;
+\&     }
+\&     push @AoH, $rec;
+\& }
+\&
+\&
+\& # reading from file
+\& # format: LEAD=fred FRIEND=barney
+\& # no temp
+\& while ( <> ) {
+\&     push @AoH, { split /[\es+=]/ };
+\& }
+\&
+\& # calling a function  that returns a key/value pair list, like
+\& # "lead","fred","daughter","pebbles"
+\& while ( my %fields = getnextpairset() ) {
+\&     push @AoH, { %fields };
+\& }
+\&
+\& # likewise, but using no temp vars
+\& while (<>) {
+\&     push @AoH, { parsepairs($_) };
+\& }
+\&
+\& # add key/value to an element
+\& $AoH[0]{pet} = "dino";
+\& $AoH[2]{pet} = "santa\*(Aqs little helper";
+.Ve
+.SS "Access and Printing of an ARRAY OF HASHES"
+.IX Subsection "Access and Printing of an ARRAY OF HASHES"
+.Vb 2
+\& # one element
+\& $AoH[0]{lead} = "fred";
+\&
+\& # another element
+\& $AoH[1]{lead} =~ s/(\ew)/\eu$1/;
+\&
+\& # print the whole thing with refs
+\& for my $href ( @AoH ) {
+\&     print "{ ";
+\&     for my $role ( keys %$href ) {
+\&         print "$role=$href\->{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+\&
+\& # print the whole thing with indices
+\& for my $i ( 0 .. $#AoH ) {
+\&     print "$i is { ";
+\&     for my $role ( keys $AoH[$i]\->%* ) {
+\&         print "$role=$AoH[$i]{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+\&
+\& # print the whole thing one at a time
+\& for my $i ( 0 .. $#AoH ) {
+\&     for my $role ( keys $AoH[$i]\->%* ) {
+\&         print "elem at ($i, $role) is $AoH[$i]{$role}\en";
+\&     }
+\& }
+.Ve
+.SH "HASHES OF HASHES"
+.IX Xref "hash of hashes HoH"
+.IX Header "HASHES OF HASHES"
+.SS "Declaration of a HASH OF HASHES"
+.IX Subsection "Declaration of a HASH OF HASHES"
+.Vb 10
+\& my %HoH = (
+\&        flintstones => {
+\&                lead      => "fred",
+\&                pal       => "barney",
+\&        },
+\&        jetsons     => {
+\&                lead      => "george",
+\&                wife      => "jane",
+\&                "his boy" => "elroy",
+\&        },
+\&        simpsons    => {
+\&                lead      => "homer",
+\&                wife      => "marge",
+\&                kid       => "bart",
+\&        },
+\& );
+.Ve
+.SS "Generation of a HASH OF HASHES"
+.IX Subsection "Generation of a HASH OF HASHES"
+.Vb 10
+\& # reading from file
+\& # flintstones: lead=fred pal=barney wife=wilma pet=dino
+\& while ( <> ) {
+\&     next unless s/^(.*?):\es*//;
+\&     my $who = $1;
+\&     for my $field ( split ) {
+\&         my ($key, $value) = split /=/, $field;
+\&         $HoH{$who}{$key} = $value;
+\&     }
+\& }
+\&
+\&
+\& # reading from file; more temps
+\& while ( <> ) {
+\&     next unless s/^(.*?):\es*//;
+\&     my $who = $1;
+\&     my $rec = {};
+\&     $HoH{$who} = $rec;
+\&     for my $field ( split ) {
+\&         my ($key, $value) = split /=/, $field;
+\&         $rec\->{$key} = $value;
+\&     }
+\& }
+\&
+\& # calling a function  that returns a key,value hash
+\& for my $group ( "simpsons", "jetsons", "flintstones" ) {
+\&     $HoH{$group} = { get_family($group) };
+\& }
+\&
+\& # likewise, but using temps
+\& for my $group ( "simpsons", "jetsons", "flintstones" ) {
+\&     my %members = get_family($group);
+\&     $HoH{$group} = { %members };
+\& }
+\&
+\& # append new members to an existing family
+\& my %new_folks = (
+\&     wife => "wilma",
+\&     pet  => "dino",
+\& );
+\&
+\& for my $what (keys %new_folks) {
+\&     $HoH{flintstones}{$what} = $new_folks{$what};
+\& }
+.Ve
+.SS "Access and Printing of a HASH OF HASHES"
+.IX Subsection "Access and Printing of a HASH OF HASHES"
+.Vb 2
+\& # one element
+\& $HoH{flintstones}{wife} = "wilma";
+\&
+\& # another element
+\& $HoH{simpsons}{lead} =~ s/(\ew)/\eu$1/;
+\&
+\& # print the whole thing
+\& foreach my $family ( keys %HoH ) {
+\&     print "$family: { ";
+\&     for my $role ( keys $HoH{$family}\->%* ) {
+\&         print "$role=$HoH{$family}{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+\&
+\& # print the whole thing  somewhat sorted
+\& foreach my $family ( sort keys %HoH ) {
+\&     print "$family: { ";
+\&     for my $role ( sort keys $HoH{$family}\->%* ) {
+\&         print "$role=$HoH{$family}{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+\&
+\&
+\& # print the whole thing sorted by number of members
+\& foreach my $family ( sort { $HoH{$b}\->%* <=> $HoH{$a}\->%* } keys %HoH ) {
+\&     print "$family: { ";
+\&     for my $role ( sort keys $HoH{$family}\->%* ) {
+\&         print "$role=$HoH{$family}{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+\&
+\& # establish a sort order (rank) for each role
+\& my $i = 0;
+\& my %rank;
+\& for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i }
+\&
+\& # now print the whole thing sorted by number of members
+\& foreach my $family ( sort { $HoH{$b}\->%* <=> $HoH{$a}\->%* } keys %HoH ) {
+\&     print "$family: { ";
+\&     # and print these according to rank order
+\&     for my $role ( sort { $rank{$a} <=> $rank{$b} }
+\&                                               keys $HoH{$family}\->%* )
+\&     {
+\&         print "$role=$HoH{$family}{$role} ";
+\&     }
+\&     print "}\en";
+\& }
+.Ve
+.SH "MORE ELABORATE RECORDS"
+.IX Xref "record structure struct"
+.IX Header "MORE ELABORATE RECORDS"
+.SS "Declaration of MORE ELABORATE RECORDS"
+.IX Subsection "Declaration of MORE ELABORATE RECORDS"
+Here's a sample showing how to create and use a record whose fields are of
+many different sorts:
+.PP
+.Vb 8
+\&     my $rec = {
+\&         TEXT      => $string,
+\&         SEQUENCE  => [ @old_values ],
+\&         LOOKUP    => { %some_table },
+\&         THATCODE  => \e&some_function,
+\&         THISCODE  => sub { $_[0] ** $_[1] },
+\&         HANDLE    => \e*STDOUT,
+\&     };
+\&
+\&     print $rec\->{TEXT};
+\&
+\&     print $rec\->{SEQUENCE}[0];
+\&     my $last = pop $rec\->{SEQUENCE}\->@*;
+\&
+\&     print $rec\->{LOOKUP}{"key"};
+\&     my ($first_k, $first_v) = each $rec\->{LOOKUP}\->%*;
+\&
+\&     my $answer = $rec\->{THATCODE}\->($arg);
+\&     $answer = $rec\->{THISCODE}\->($arg1, $arg2);
+\&
+\&     # careful of extra block braces on fh ref
+\&     print { $rec\->{HANDLE} } "a string\en";
+\&
+\&     use FileHandle;
+\&     $rec\->{HANDLE}\->autoflush(1);
+\&     $rec\->{HANDLE}\->print(" a string\en");
+.Ve
+.SS "Declaration of a HASH OF COMPLEX RECORDS"
+.IX Subsection "Declaration of a HASH OF COMPLEX RECORDS"
+.Vb 10
+\&     my %TV = (
+\&        flintstones => {
+\&            series   => "flintstones",
+\&            nights   => [ qw(monday thursday friday) ],
+\&            members  => [
+\&                { name => "fred",    role => "lead", age  => 36, },
+\&                { name => "wilma",   role => "wife", age  => 31, },
+\&                { name => "pebbles", role => "kid",  age  =>  4, },
+\&            ],
+\&        },
+\&
+\&        jetsons     => {
+\&            series   => "jetsons",
+\&            nights   => [ qw(wednesday saturday) ],
+\&            members  => [
+\&                { name => "george",  role => "lead", age  => 41, },
+\&                { name => "jane",    role => "wife", age  => 39, },
+\&                { name => "elroy",   role => "kid",  age  =>  9, },
+\&            ],
+\&         },
+\&
+\&        simpsons    => {
+\&            series   => "simpsons",
+\&            nights   => [ qw(monday) ],
+\&            members  => [
+\&                { name => "homer", role => "lead", age  => 34, },
+\&                { name => "marge", role => "wife", age => 37, },
+\&                { name => "bart",  role => "kid",  age  =>  11, },
+\&            ],
+\&         },
+\&      );
+.Ve
+.SS "Generation of a HASH OF COMPLEX RECORDS"
+.IX Subsection "Generation of a HASH OF COMPLEX RECORDS"
+.Vb 5
+\&     # reading from file
+\&     # this is most easily done by having the file itself be
+\&     # in the raw data format as shown above.  perl is happy
+\&     # to parse complex data structures if declared as data, so
+\&     # sometimes it\*(Aqs easiest to do that
+\&
+\&     # here\*(Aqs a piece by piece build up
+\&     my $rec = {};
+\&     $rec\->{series} = "flintstones";
+\&     $rec\->{nights} = [ find_days() ];
+\&
+\&     my @members = ();
+\&     # assume this file in field=value syntax
+\&     while (<>) {
+\&         my %fields = split /[\es=]+/;
+\&         push @members, { %fields };
+\&     }
+\&     $rec\->{members} = [ @members ];
+\&
+\&     # now remember the whole thing
+\&     $TV{ $rec\->{series} } = $rec;
+\&
+\&     ###########################################################
+\&     # now, you might want to make interesting extra fields that
+\&     # include pointers back into the same data structure so if
+\&     # change one piece, it changes everywhere, like for example
+\&     # if you wanted a {kids} field that was a reference
+\&     # to an array of the kids\*(Aq records without having duplicate
+\&     # records and thus update problems.
+\&     ###########################################################
+\&     foreach my $family (keys %TV) {
+\&         my $rec = $TV{$family}; # temp pointer
+\&         my @kids = ();
+\&         for my $person ( $rec\->{members}\->@* ) {
+\&             if ($person\->{role} =~ /kid|son|daughter/) {
+\&                 push @kids, $person;
+\&             }
+\&         }
+\&         # REMEMBER: $rec and $TV{$family} point to same data!!
+\&         $rec\->{kids} = [ @kids ];
+\&     }
+\&
+\&     # you copied the array, but the array itself contains pointers
+\&     # to uncopied objects. this means that if you make bart get
+\&     # older via
+\&
+\&     $TV{simpsons}{kids}[0]{age}++;
+\&
+\&     # then this would also change in
+\&     print $TV{simpsons}{members}[2]{age};
+\&
+\&     # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2]
+\&     # both point to the same underlying anonymous hash table
+\&
+\&     # print the whole thing
+\&     foreach my $family ( keys %TV ) {
+\&         print "the $family";
+\&         print " is on during $TV{$family}{nights}\->@*\en";
+\&         print "its members are:\en";
+\&         for my $who ( $TV{$family}{members}\->@* ) {
+\&             print " $who\->{name} ($who\->{role}), age $who\->{age}\en";
+\&         }
+\&         print "it turns out that $TV{$family}{lead} has ";
+\&         print scalar ( $TV{$family}{kids}\->@* ), " kids named ";
+\&         print join (", ", map { $_\->{name} } $TV{$family}{kids}\->@* );
+\&         print "\en";
+\&     }
+.Ve
+.SH "Database Ties"
+.IX Header "Database Ties"
+You cannot easily tie a multilevel data structure (such as a hash of
+hashes) to a dbm file.  The first problem is that all but GDBM and
+Berkeley DB have size limitations, but beyond that, you also have problems
+with how references are to be represented on disk.  One experimental
+module that does partially attempt to address this need is the MLDBM
+module.  Check your nearest CPAN site as described in perlmodlib for
+source code to MLDBM.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlref, perllol, perldata, perlobj
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen <\fItchrist@perl.com\fR>
diff --git a/upstream/mageia-cauldron/man1/perldtrace.1 b/upstream/mageia-cauldron/man1/perldtrace.1
new file mode 100644
index 00000000..df40e317
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldtrace.1
@@ -0,0 +1,278 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDTRACE 1"
+.TH PERLDTRACE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perldtrace \- Perl's support for DTrace
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\& # dtrace \-Zn \*(Aqperl::sub\-entry, perl::sub\-return { trace(copyinstr(arg0)) }\*(Aq
+\& dtrace: description \*(Aqperl::sub\-entry, perl::sub\-return \*(Aq matched 10 probes
+\&
+\& # perl \-E \*(Aqsub outer { inner(@_) } sub inner { say shift } outer("hello")\*(Aq
+\& hello
+\&
+\& (dtrace output)
+\& CPU     ID                    FUNCTION:NAME
+\&   0  75915       Perl_pp_entersub:sub\-entry   BEGIN
+\&   0  75915       Perl_pp_entersub:sub\-entry   import
+\&   0  75922      Perl_pp_leavesub:sub\-return   import
+\&   0  75922      Perl_pp_leavesub:sub\-return   BEGIN
+\&   0  75915       Perl_pp_entersub:sub\-entry   outer
+\&   0  75915       Perl_pp_entersub:sub\-entry   inner
+\&   0  75922      Perl_pp_leavesub:sub\-return   inner
+\&   0  75922      Perl_pp_leavesub:sub\-return   outer
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+DTrace is a framework for comprehensive system\- and application-level
+tracing. Perl is a DTrace \fIprovider\fR, meaning it exposes several
+\&\fIprobes\fR for instrumentation. You can use these in conjunction
+with kernel-level probes, as well as probes from other providers
+such as MySQL, in order to diagnose software defects, or even just
+your application's bottlenecks.
+.PP
+Perl must be compiled with the \f(CW\*(C`\-Dusedtrace\*(C'\fR option in order to
+make use of the provided probes. While DTrace aims to have no
+overhead when its instrumentation is not active, Perl's support
+itself cannot uphold that guarantee, so it is built without DTrace
+probes under most systems. One notable exception is that Mac OS X
+ships a \fI/usr/bin/perl\fR with DTrace support enabled.
+.SH HISTORY
+.IX Header "HISTORY"
+.IP 5.10.1 4
+.IX Item "5.10.1"
+Perl's initial DTrace support was added, providing \f(CW\*(C`sub\-entry\*(C'\fR and
+\&\f(CW\*(C`sub\-return\*(C'\fR probes.
+.IP 5.14.0 4
+.IX Item "5.14.0"
+The \f(CW\*(C`sub\-entry\*(C'\fR and \f(CW\*(C`sub\-return\*(C'\fR probes gain a fourth argument: the
+package name of the function.
+.IP 5.16.0 4
+.IX Item "5.16.0"
+The \f(CW\*(C`phase\-change\*(C'\fR probe was added.
+.IP 5.18.0 4
+.IX Item "5.18.0"
+The \f(CW\*(C`op\-entry\*(C'\fR, \f(CW\*(C`loading\-file\*(C'\fR, and \f(CW\*(C`loaded\-file\*(C'\fR probes were added.
+.SH PROBES
+.IX Header "PROBES"
+.IP "sub\-entry(SUBNAME, FILE, LINE, PACKAGE)" 4
+.IX Item "sub-entry(SUBNAME, FILE, LINE, PACKAGE)"
+Traces the entry of any subroutine. Note that all of the variables
+refer to the subroutine that is being invoked; there is currently
+no way to get ahold of any information about the subroutine's
+\&\fIcaller\fR from a DTrace action.
+.Sp
+.Vb 4
+\& :*perl*::sub\-entry {
+\&     printf("%s::%s entered at %s line %d\en",
+\&           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+\& }
+.Ve
+.IP "sub\-return(SUBNAME, FILE, LINE, PACKAGE)" 4
+.IX Item "sub-return(SUBNAME, FILE, LINE, PACKAGE)"
+Traces the exit of any subroutine. Note that all of the variables
+refer to the subroutine that is returning; there is currently no
+way to get ahold of any information about the subroutine's \fIcaller\fR
+from a DTrace action.
+.Sp
+.Vb 4
+\& :*perl*::sub\-return {
+\&     printf("%s::%s returned at %s line %d\en",
+\&           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+\& }
+.Ve
+.IP "phase\-change(NEWPHASE, OLDPHASE)" 4
+.IX Item "phase-change(NEWPHASE, OLDPHASE)"
+Traces changes to Perl's interpreter state. You can internalize this
+as tracing changes to Perl's \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable, especially
+since the values for \f(CW\*(C`NEWPHASE\*(C'\fR and \f(CW\*(C`OLDPHASE\*(C'\fR are the strings that
+\&\f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR reports.
+.Sp
+.Vb 4
+\& :*perl*::phase\-change {
+\&     printf("Phase changed from %s to %s\en",
+\&         copyinstr(arg1), copyinstr(arg0));
+\& }
+.Ve
+.IP op\-entry(OPNAME) 4
+.IX Item "op-entry(OPNAME)"
+Traces the execution of each opcode in the Perl runloop. This probe
+is fired before the opcode is executed. When the Perl debugger is
+enabled, the DTrace probe is fired \fIafter\fR the debugger hooks (but
+still before the opcode itself is executed).
+.Sp
+.Vb 3
+\& :*perl*::op\-entry {
+\&     printf("About to execute opcode %s\en", copyinstr(arg0));
+\& }
+.Ve
+.IP loading\-file(FILENAME) 4
+.IX Item "loading-file(FILENAME)"
+Fires when Perl is about to load an individual file, whether from
+\&\f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires before the file is
+read from disk. The filename argument is converted to local filesystem
+paths instead of providing \f(CW\*(C`Module::Name\*(C'\fR\-style names.
+.Sp
+.Vb 3
+\& :*perl*:loading\-file {
+\&     printf("About to load %s\en", copyinstr(arg0));
+\& }
+.Ve
+.IP loaded\-file(FILENAME) 4
+.IX Item "loaded-file(FILENAME)"
+Fires when Perl has successfully loaded an individual file, whether
+from \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires after the file
+is read from disk and its contents evaluated. The filename argument
+is converted to local filesystem paths instead of providing
+\&\f(CW\*(C`Module::Name\*(C'\fR\-style names.
+.Sp
+.Vb 3
+\& :*perl*:loaded\-file {
+\&     printf("Successfully loaded %s\en", copyinstr(arg0));
+\& }
+.Ve
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.IP "Most frequently called functions" 4
+.IX Item "Most frequently called functions"
+.Vb 1
+\& # dtrace \-qZn \*(Aqsub\-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}\*(Aq
+\&
+\& Class::MOP::Attribute::slots                                    400
+\& Try::Tiny::catch                                                411
+\& Try::Tiny::try                                                  411
+\& Class::MOP::Instance::inline_slot_access                        451
+\& Class::MOP::Class::Immutable::Trait:::around                    472
+\& Class::MOP::Mixin::AttributeCore::has_initializer               496
+\& Class::MOP::Method::Wrapped::_\|_ANON_\|_                           544
+\& Class::MOP::Package::_package_stash                             737
+\& Class::MOP::Class::initialize                                  1128
+\& Class::MOP::get_metaclass_by_name                              1204
+.Ve
+.IP "Trace function calls" 4
+.IX Item "Trace function calls"
+.Vb 1
+\& # dtrace \-qFZn \*(Aqsub\-entry, sub\-return { trace(copyinstr(arg0)) }\*(Aq
+\&
+\& 0  \-> Perl_pp_entersub                        BEGIN
+\& 0  <\- Perl_pp_leavesub                        BEGIN
+\& 0  \-> Perl_pp_entersub                        BEGIN
+\& 0    \-> Perl_pp_entersub                      import
+\& 0    <\- Perl_pp_leavesub                      import
+\& 0  <\- Perl_pp_leavesub                        BEGIN
+\& 0  \-> Perl_pp_entersub                        BEGIN
+\& 0    \-> Perl_pp_entersub                      dress
+\& 0    <\- Perl_pp_leavesub                      dress
+\& 0    \-> Perl_pp_entersub                      dirty
+\& 0    <\- Perl_pp_leavesub                      dirty
+\& 0    \-> Perl_pp_entersub                      whiten
+\& 0    <\- Perl_pp_leavesub                      whiten
+\& 0  <\- Perl_dounwind                           BEGIN
+.Ve
+.IP "Function calls during interpreter cleanup" 4
+.IX Item "Function calls during interpreter cleanup"
+.Vb 1
+\& # dtrace \-Zn \*(Aqphase\-change /copyinstr(arg0) == "END"/ { self\->ending = 1 } sub\-entry /self\->ending/ { trace(copyinstr(arg0)) }\*(Aq
+\&
+\& CPU     ID                    FUNCTION:NAME
+\&   1  77214       Perl_pp_entersub:sub\-entry   END
+\&   1  77214       Perl_pp_entersub:sub\-entry   END
+\&   1  77214       Perl_pp_entersub:sub\-entry   cleanup
+\&   1  77214       Perl_pp_entersub:sub\-entry   _force_writable
+\&   1  77214       Perl_pp_entersub:sub\-entry   _force_writable
+.Ve
+.IP "System calls at compile time" 4
+.IX Item "System calls at compile time"
+.Vb 1
+\& # dtrace \-qZn \*(Aqphase\-change /copyinstr(arg0) == "START"/ { self\->interesting = 1 } phase\-change /copyinstr(arg0) == "RUN"/ { self\->interesting = 0 } syscall::: /self\->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }\*(Aq
+\&
+\& lseek                                                           310
+\& read                                                            374
+\& stat64                                                         1056
+.Ve
+.IP "Perl functions that execute the most opcodes" 4
+.IX Item "Perl functions that execute the most opcodes"
+.Vb 1
+\& # dtrace \-qZn \*(Aqsub\-entry { self\->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op\-entry /self\->fqn != ""/ { @[self\->fqn] = count() } END { trunc(@, 3) }\*(Aq
+\&
+\& warnings::unimport                                             4589
+\& Exporter::Heavy::_rebuild_cache                                5039
+\& Exporter::import                                              14578
+.Ve
+.SH REFERENCES
+.IX Header "REFERENCES"
+.IP "DTrace Dynamic Tracing Guide" 4
+.IX Item "DTrace Dynamic Tracing Guide"
+<http://dtrace.org/guide/preface.html>
+.IP "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD" 4
+.IX Item "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD"
+<https://www.amazon.com/DTrace\-Dynamic\-Tracing\-Solaris\-FreeBSD/dp/0132091518/>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP Devel::DTrace::Provider 4
+.IX Item "Devel::DTrace::Provider"
+This CPAN module lets you create application-level DTrace probes written in
+Perl.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Shawn M Moore \f(CW\*(C`sartak@gmail.com\*(C'\fR
diff --git a/upstream/mageia-cauldron/man1/perlebcdic.1 b/upstream/mageia-cauldron/man1/perlebcdic.1
new file mode 100644
index 00000000..b23c5fd5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlebcdic.1
@@ -0,0 +1,1998 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLEBCDIC 1"
+.TH PERLEBCDIC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlebcdic \- Considerations for running Perl on EBCDIC platforms
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+An exploration of some of the issues facing Perl programmers
+on EBCDIC based computers.
+.PP
+Portions of this document that are still incomplete are marked with XXX.
+.PP
+Early Perl versions worked on some EBCDIC machines, but the last known
+version that ran on EBCDIC was v5.8.7, until v5.22, when the Perl core
+again works on z/OS.  Theoretically, it could work on OS/400 or Siemens'
+BS2000  (or their successors), but this is untested.  In v5.22 and 5.24,
+not all
+the modules found on CPAN but shipped with core Perl work on z/OS.
+.PP
+If you want to use Perl on a non\-z/OS EBCDIC machine, please let us know
+at <https://github.com/Perl/perl5/issues>.
+.PP
+Writing Perl on an EBCDIC platform is really no different than writing
+on an "ASCII" one, but with different underlying numbers, as we'll see
+shortly.  You'll have to know something about those "ASCII" platforms
+because the documentation is biased and will frequently use example
+numbers that don't apply to EBCDIC.  There are also very few CPAN
+modules that are written for EBCDIC and which don't work on ASCII;
+instead the vast majority of CPAN modules are written for ASCII, and
+some may happen to work on EBCDIC, while a few have been designed to
+portably work on both.
+.PP
+If your code just uses the 52 letters A\-Z and a\-z, plus SPACE, the
+digits 0\-9, and the punctuation characters that Perl uses, plus a few
+controls that are denoted by escape sequences like \f(CW\*(C`\en\*(C'\fR and \f(CW\*(C`\et\*(C'\fR, then
+there's nothing special about using Perl, and your code may very well
+work on an ASCII machine without change.
+.PP
+But if you write code that uses \f(CW\*(C`\e005\*(C'\fR to mean a TAB or \f(CW\*(C`\exC1\*(C'\fR to mean
+an "A", or \f(CW\*(C`\exDF\*(C'\fR to mean a "ÿ" (small \f(CW"y"\fR with a diaeresis),
+then your code may well work on your EBCDIC platform, but not on an
+ASCII one.  That's fine to do if no one will ever want to run your code
+on an ASCII platform; but the bias in this document will be towards writing
+code portable between EBCDIC and ASCII systems.  Again, if every
+character you care about is easily enterable from your keyboard, you
+don't have to know anything about ASCII, but many keyboards don't easily
+allow you to directly enter, say, the character \f(CW\*(C`\exDF\*(C'\fR, so you have to
+specify it indirectly, such as by using the \f(CW"\exDF"\fR escape sequence.
+In those cases it's easiest to know something about the ASCII/Unicode
+character sets.  If you know that the small "ÿ" is \f(CW\*(C`U+00FF\*(C'\fR, then
+you can instead specify it as \f(CW"\eN{U+FF}"\fR, and have the computer
+automatically translate it to \f(CW\*(C`\exDF\*(C'\fR on your platform, and leave it as
+\&\f(CW\*(C`\exFF\*(C'\fR on ASCII ones.  Or you could specify it by name, \f(CW\*(C`\eN{LATIN
+SMALL LETTER Y WITH DIAERESIS\*(C'\fR and not have to know the  numbers.
+Either way works, but both require familiarity with Unicode.
+.SH "COMMON CHARACTER CODE SETS"
+.IX Header "COMMON CHARACTER CODE SETS"
+.SS ASCII
+.IX Subsection "ASCII"
+The American Standard Code for Information Interchange (ASCII or
+US-ASCII) is a set of
+integers running from 0 to 127 (decimal) that have standardized
+interpretations by the computers which use ASCII.  For example, 65 means
+the letter "A".
+The range 0..127 can be covered by setting various bits in a 7\-bit binary
+digit, hence the set is sometimes referred to as "7\-bit ASCII".
+ASCII was described by the American National Standards Institute
+document ANSI X3.4\-1986.  It was also described by ISO 646:1991
+(with localization for currency symbols).  The full ASCII set is
+given in the table below as the first 128 elements.
+Languages that
+can be written adequately with the characters in ASCII include
+English, Hawaiian, Indonesian, Swahili and some Native American
+languages.
+.PP
+Most non-EBCDIC character sets are supersets of ASCII.  That is the
+integers 0\-127 mean what ASCII says they mean.  But integers 128 and
+above are specific to the character set.
+.PP
+Many of these fit entirely into 8 bits, using ASCII as 0\-127, while
+specifying what 128\-255 mean, and not using anything above 255.
+Thus, these are single-byte (or octet if you prefer) character sets.
+One important one (since Unicode is a superset of it) is the ISO 8859\-1
+character set.
+.SS "ISO 8859"
+.IX Subsection "ISO 8859"
+The ISO 8859\-\fR\f(CB$n\fR\f(BI\fR\fI\fR are a collection of character code sets from the
+International Organization for Standardization (ISO), each of which adds
+characters to the ASCII set that are typically found in various
+languages, many of which are based on the Roman, or Latin, alphabet.
+Most are for European languages, but there are also ones for Arabic,
+Greek, Hebrew, and Thai.  There are good references on the web about
+all these.
+.SS "Latin 1 (ISO 8859\-1)"
+.IX Subsection "Latin 1 (ISO 8859-1)"
+A particular 8\-bit extension to ASCII that includes grave and acute
+accented Latin characters.  Languages that can employ ISO 8859\-1
+include all the languages covered by ASCII as well as Afrikaans,
+Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian,
+Portuguese, Spanish, and Swedish.  Dutch is covered albeit without
+the ij ligature.  French is covered too but without the oe ligature.
+German can use ISO 8859\-1 but must do so without German-style
+quotation marks.  This set is based on Western European extensions
+to ASCII and is commonly encountered in world wide web work.
+In IBM character code set identification terminology, ISO 8859\-1 is
+also known as CCSID 819 (or sometimes 0819 or even 00819).
+.SS EBCDIC
+.IX Subsection "EBCDIC"
+The Extended Binary Coded Decimal Interchange Code refers to a
+large collection of single\- and multi-byte coded character sets that are
+quite different from ASCII and ISO 8859\-1, and are all slightly
+different from each other; they typically run on host computers.  The
+EBCDIC encodings derive from 8\-bit byte extensions of Hollerith punched
+card encodings, which long predate ASCII.  The layout on the
+cards was such that high bits were set for the upper and lower case
+alphabetic
+characters \f(CW\*(C`[a\-z]\*(C'\fR and \f(CW\*(C`[A\-Z]\*(C'\fR, but there were gaps within each Latin
+alphabet range, visible in the table below.  These gaps can
+cause complications.
+.PP
+Some IBM EBCDIC character sets may be known by character code set
+identification numbers (CCSID numbers) or code page numbers.
+.PP
+Perl can be compiled on platforms that run any of three commonly used EBCDIC
+character sets, listed below.
+.PP
+\fIThe 13 variant characters\fR
+.IX Subsection "The 13 variant characters"
+.PP
+Among IBM EBCDIC character code sets there are 13 characters that
+are often mapped to different integer values.  Those characters
+are known as the 13 "variant" characters and are:
+.PP
+.Vb 1
+\&    \e [ ] { } ^ ~ ! # | $ @ \`
+.Ve
+.PP
+When Perl is compiled for a platform, it looks at all of these characters to
+guess which EBCDIC character set the platform uses, and adapts itself
+accordingly to that platform.  If the platform uses a character set that is not
+one of the three Perl knows about, Perl will either fail to compile, or
+mistakenly and silently choose one of the three.
+.PP
+The Line Feed (LF) character is actually a 14th variant character, and
+Perl checks for that as well.
+.PP
+\fIEBCDIC code sets recognized by Perl\fR
+.IX Subsection "EBCDIC code sets recognized by Perl"
+.IP \fB0037\fR 4
+.IX Item "0037"
+Character code set ID 0037 is a mapping of the ASCII plus Latin\-1
+characters (i.e. ISO 8859\-1) to an EBCDIC set.  0037 is used
+in North American English locales on the OS/400 operating system
+that runs on AS/400 computers.  CCSID 0037 differs from ISO 8859\-1
+in 236 places; in other words they agree on only 20 code point values.
+.IP \fB1047\fR 4
+.IX Item "1047"
+Character code set ID 1047 is also a mapping of the ASCII plus
+Latin\-1 characters (i.e. ISO 8859\-1) to an EBCDIC set.  1047 is
+used under Unix System Services for OS/390 or z/OS, and OpenEdition
+for VM/ESA.  CCSID 1047 differs from CCSID 0037 in eight places,
+and from ISO 8859\-1 in 236.
+.IP \fBPOSIX-BC\fR 4
+.IX Item "POSIX-BC"
+The EBCDIC code page in use on Siemens' BS2000 system is distinct from
+1047 and 0037.  It is identified below as the POSIX-BC set.
+Like 0037 and 1047, it is the same as ISO 8859\-1 in 20 code point
+values.
+.SS "Unicode code points versus EBCDIC code points"
+.IX Subsection "Unicode code points versus EBCDIC code points"
+In Unicode terminology a \fIcode point\fR is the number assigned to a
+character: for example, in EBCDIC the character "A" is usually assigned
+the number 193.  In Unicode, the character "A" is assigned the number 65.
+All the code points in ASCII and Latin\-1 (ISO 8859\-1) have the same
+meaning in Unicode.  All three of the recognized EBCDIC code sets have
+256 code points, and in each code set, all 256 code points are mapped to
+equivalent Latin1 code points.  Obviously, "A" will map to "A", "B" =>
+"B", "%" => "%", etc., for all printable characters in Latin1 and these
+code pages.
+.PP
+It also turns out that EBCDIC has nearly precise equivalents for the
+ASCII/Latin1 C0 controls and the DELETE control.  (The C0 controls are
+those whose ASCII code points are 0..0x1F; things like TAB, ACK, BEL,
+etc.)  A mapping is set up between these ASCII/EBCDIC controls.  There
+isn't such a precise mapping between the C1 controls on ASCII platforms
+and the remaining EBCDIC controls.  What has been done is to map these
+controls, mostly arbitrarily, to some otherwise unmatched character in
+the other character set.  Most of these are very very rarely used
+nowadays in EBCDIC anyway, and their names have been dropped, without
+much complaint.  For example the EO (Eight Ones) EBCDIC control
+(consisting of eight one bits = 0xFF) is mapped to the C1 APC control
+(0x9F), and you can't use the name "EO".
+.PP
+The EBCDIC controls provide three possible line terminator characters,
+CR (0x0D), LF (0x25), and NL (0x15).  On ASCII platforms, the symbols
+"NL" and "LF" refer to the same character, but in strict EBCDIC
+terminology they are different ones.  The EBCDIC NL is mapped to the C1
+control called "NEL" ("Next Line"; here's a case where the mapping makes
+quite a bit of sense, and hence isn't just arbitrary).  On some EBCDIC
+platforms, this NL or NEL is the typical line terminator.  This is true
+of z/OS and BS2000.  In these platforms, the C compilers will swap the
+LF and NEL code points, so that \f(CW"\en"\fR is 0x15, and refers to NL.  Perl
+does that too; you can see it in the code chart below.
+This makes things generally "just work" without you even having to be
+aware that there is a swap.
+.SS "Unicode and UTF"
+.IX Subsection "Unicode and UTF"
+UTF stands for "Unicode Transformation Format".
+UTF\-8 is an encoding of Unicode into a sequence of 8\-bit byte chunks, based on
+ASCII and Latin\-1.
+The length of a sequence required to represent a Unicode code point
+depends on the ordinal number of that code point,
+with larger numbers requiring more bytes.
+UTF-EBCDIC is like UTF\-8, but based on EBCDIC.
+They are enough alike that often, casual usage will conflate the two
+terms, and use "UTF\-8" to mean both the UTF\-8 found on ASCII platforms,
+and the UTF-EBCDIC found on EBCDIC ones.
+.PP
+You may see the term "invariant" character or code point.
+This simply means that the character has the same numeric
+value and representation when encoded in UTF\-8 (or UTF-EBCDIC) as when
+not.  (Note that this is a very different concept from "The 13 variant
+characters" mentioned above.  Careful prose will use the term "UTF\-8
+invariant" instead of just "invariant", but most often you'll see just
+"invariant".) For example, the ordinal value of "A" is 193 in most
+EBCDIC code pages, and also is 193 when encoded in UTF-EBCDIC.  All
+UTF\-8 (or UTF-EBCDIC) variant code points occupy at least two bytes when
+encoded in UTF\-8 (or UTF-EBCDIC); by definition, the UTF\-8 (or
+UTF-EBCDIC) invariant code points are exactly one byte whether encoded
+in UTF\-8 (or UTF-EBCDIC), or not.  (By now you see why people typically
+just say "UTF\-8" when they also mean "UTF-EBCDIC".  For the rest of this
+document, we'll mostly be casual about it too.)
+In ASCII UTF\-8, the code points corresponding to the lowest 128
+ordinal numbers (0 \- 127: the ASCII characters) are invariant.
+In UTF-EBCDIC, there are 160 invariant characters.
+(If you care, the EBCDIC invariants are those characters
+which have ASCII equivalents, plus those that correspond to
+the C1 controls (128 \- 159 on ASCII platforms).)
+.PP
+A string encoded in UTF-EBCDIC may be longer (very rarely shorter) than
+one encoded in UTF\-8.  Perl extends both UTF\-8 and UTF-EBCDIC so that
+they can encode code points above the Unicode maximum of U+10FFFF.  Both
+extensions are constructed to allow encoding of any code point that fits
+in a 64\-bit word.
+.PP
+UTF-EBCDIC is defined by
+Unicode Technical Report #16 <https://www.unicode.org/reports/tr16>
+(often referred to as just TR16).
+It is defined based on CCSID 1047, not allowing for the differences for
+other code pages.  This allows for easy interchange of text between
+computers running different code pages, but makes it unusable, without
+adaptation, for Perl on those other code pages.
+.PP
+The reason for this unusability is that a fundamental assumption of Perl
+is that the characters it cares about for parsing and lexical analysis
+are the same whether or not the text is in UTF\-8.  For example, Perl
+expects the character \f(CW"["\fR to have the same representation, no matter
+if the string containing it (or program text) is UTF\-8 encoded or not.
+To ensure this, Perl adapts UTF-EBCDIC to the particular code page so
+that all characters it expects to be UTF\-8 invariant are in fact UTF\-8
+invariant.  This means that text generated on a computer running one
+version of Perl's UTF-EBCDIC has to be translated to be intelligible to
+a computer running another.
+.PP
+TR16 implies a method to extend UTF-EBCDIC to encode points up through
+\&\f(CW\*(C`2\ **\ 31\ \-\ 1\*(C'\fR.  Perl uses this method for code points up through
+\&\f(CW\*(C`2\ **\ 30\ \-\ 1\*(C'\fR, but uses an incompatible method for larger ones, to
+enable it to handle much larger code points than otherwise.
+.SS "Using Encode"
+.IX Subsection "Using Encode"
+Starting from Perl 5.8 you can use the standard module Encode
+to translate from EBCDIC to Latin\-1 code points.
+Encode knows about more EBCDIC character sets than Perl can currently
+be compiled to run on.
+.PP
+.Vb 1
+\&   use Encode \*(Aqfrom_to\*(Aq;
+\&
+\&   my %ebcdic = ( 176 => \*(Aqcp37\*(Aq, 95 => \*(Aqcp1047\*(Aq, 106 => \*(Aqposix\-bc\*(Aq );
+\&
+\&   # $a is in EBCDIC code points
+\&   from_to($a, $ebcdic{ord \*(Aq^\*(Aq}, \*(Aqlatin1\*(Aq);
+\&   # $a is ISO 8859\-1 code points
+.Ve
+.PP
+and from Latin\-1 code points to EBCDIC code points
+.PP
+.Vb 1
+\&   use Encode \*(Aqfrom_to\*(Aq;
+\&
+\&   my %ebcdic = ( 176 => \*(Aqcp37\*(Aq, 95 => \*(Aqcp1047\*(Aq, 106 => \*(Aqposix\-bc\*(Aq );
+\&
+\&   # $a is ISO 8859\-1 code points
+\&   from_to($a, \*(Aqlatin1\*(Aq, $ebcdic{ord \*(Aq^\*(Aq});
+\&   # $a is in EBCDIC code points
+.Ve
+.PP
+For doing I/O it is suggested that you use the autotranslating features
+of PerlIO, see perluniintro.
+.PP
+Since version 5.8 Perl uses the PerlIO I/O library.  This enables
+you to use different encodings per IO channel.  For example you may use
+.PP
+.Vb 9
+\&    use Encode;
+\&    open($f, ">:encoding(ascii)", "test.ascii");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(cp37)", "test.ebcdic");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(latin1)", "test.latin1");
+\&    print $f "Hello World!\en";
+\&    open($f, ">:encoding(utf8)", "test.utf8");
+\&    print $f "Hello World!\en";
+.Ve
+.PP
+to get four files containing "Hello World!\en" in ASCII, CP 0037 EBCDIC,
+ISO 8859\-1 (Latin\-1) (in this example identical to ASCII since only ASCII
+characters were printed), and
+UTF-EBCDIC (in this example identical to normal EBCDIC since only characters
+that don't differ between EBCDIC and UTF-EBCDIC were printed).  See the
+documentation of Encode::PerlIO for details.
+.PP
+As the PerlIO layer uses raw IO (bytes) internally, all this totally
+ignores things like the type of your filesystem (ASCII or EBCDIC).
+.SH "SINGLE OCTET TABLES"
+.IX Header "SINGLE OCTET TABLES"
+The following tables list the ASCII and Latin 1 ordered sets including
+the subsets: C0 controls (0..31), ASCII graphics (32..7e), delete (7f),
+C1 controls (80..9f), and Latin\-1 (a.k.a. ISO 8859\-1) (a0..ff).  In the
+table names of the Latin 1
+extensions to ASCII have been labelled with character names roughly
+corresponding to \fIThe Unicode Standard, Version 6.1\fR albeit with
+substitutions such as \f(CW\*(C`s/LATIN//\*(C'\fR and \f(CW\*(C`s/VULGAR//\*(C'\fR in all cases;
+\&\f(CW\*(C`s/CAPITAL\ LETTER//\*(C'\fR in some cases; and
+\&\f(CW\*(C`s/SMALL\ LETTER\ ([A\-Z])/\el$1/\*(C'\fR in some other
+cases.  Controls are listed using their Unicode 6.2 abbreviations.
+The differences between the 0037 and 1047 sets are
+flagged with \f(CW\*(C`**\*(C'\fR.  The differences between the 1047 and POSIX-BC sets
+are flagged with \f(CW\*(C`##.\*(C'\fR  All \f(CWord()\fR numbers listed are decimal.  If you
+would rather see this table listing octal values, then run the table
+(that is, the pod source text of this document, since this recipe may not
+work with a pod2_other_format translation) through:
+.IP "recipe 0" 4
+.IX Item "recipe 0"
+.PP
+.Vb 3
+\&    perl \-ne \*(Aqif(/(.{29})(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)/)\*(Aq \e
+\&     \-e \*(Aq{printf("%s%\-5.03o%\-5.03o%\-5.03o%.03o\en",$1,$2,$3,$4,$5)}\*(Aq \e
+\&     perlebcdic.pod
+.Ve
+.PP
+If you want to retain the UTF-x code points then in script form you
+might want to write:
+.IP "recipe 1" 4
+.IX Item "recipe 1"
+.PP
+.Vb 10
+\& open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
+\& while (<FH>) {
+\&     if (/(.{29})(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)\e.?(\ed*)
+\&                                                     \es+(\ed+)\e.?(\ed*)/x)
+\&     {
+\&         if ($7 ne \*(Aq\*(Aq && $9 ne \*(Aq\*(Aq) {
+\&             printf(
+\&                "%s%\-5.03o%\-5.03o%\-5.03o%\-5.03o%\-3o.%\-5o%\-3o.%.03o\en",
+\&                                            $1,$2,$3,$4,$5,$6,$7,$8,$9);
+\&         }
+\&         elsif ($7 ne \*(Aq\*(Aq) {
+\&             printf("%s%\-5.03o%\-5.03o%\-5.03o%\-5.03o%\-3o.%\-5o%.03o\en",
+\&                                           $1,$2,$3,$4,$5,$6,$7,$8);
+\&         }
+\&         else {
+\&             printf("%s%\-5.03o%\-5.03o%\-5.03o%\-5.03o%\-5.03o%.03o\en",
+\&                                                $1,$2,$3,$4,$5,$6,$8);
+\&         }
+\&     }
+\& }
+.Ve
+.PP
+If you would rather see this table listing hexadecimal values then
+run the table through:
+.IP "recipe 2" 4
+.IX Item "recipe 2"
+.PP
+.Vb 3
+\&    perl \-ne \*(Aqif(/(.{29})(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)/)\*(Aq \e
+\&     \-e \*(Aq{printf("%s%\-5.02X%\-5.02X%\-5.02X%.02X\en",$1,$2,$3,$4,$5)}\*(Aq \e
+\&     perlebcdic.pod
+.Ve
+.PP
+Or, in order to retain the UTF-x code points in hexadecimal:
+.IP "recipe 3" 4
+.IX Item "recipe 3"
+.PP
+.Vb 10
+\& open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
+\& while (<FH>) {
+\&     if (/(.{29})(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)\es+(\ed+)\e.?(\ed*)
+\&                                                     \es+(\ed+)\e.?(\ed*)/x)
+\&     {
+\&         if ($7 ne \*(Aq\*(Aq && $9 ne \*(Aq\*(Aq) {
+\&             printf(
+\&                "%s%\-5.02X%\-5.02X%\-5.02X%\-5.02X%\-2X.%\-6.02X%02X.%02X\en",
+\&                                           $1,$2,$3,$4,$5,$6,$7,$8,$9);
+\&         }
+\&         elsif ($7 ne \*(Aq\*(Aq) {
+\&             printf("%s%\-5.02X%\-5.02X%\-5.02X%\-5.02X%\-2X.%\-6.02X%02X\en",
+\&                                              $1,$2,$3,$4,$5,$6,$7,$8);
+\&         }
+\&         else {
+\&             printf("%s%\-5.02X%\-5.02X%\-5.02X%\-5.02X%\-5.02X%02X\en",
+\&                                                  $1,$2,$3,$4,$5,$6,$8);
+\&         }
+\&     }
+\& }
+\&
+\&
+\&                          ISO
+\&                         8859\-1             POS\-         CCSID
+\&                         CCSID  CCSID CCSID IX\-          1047
+\&  chr                     0819   0037 1047  BC  UTF\-8  UTF\-EBCDIC
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& <NUL>                       0    0    0    0    0        0
+\& <SOH>                       1    1    1    1    1        1
+\& <STX>                       2    2    2    2    2        2
+\& <ETX>                       3    3    3    3    3        3
+\& <EOT>                       4    55   55   55   4        55
+\& <ENQ>                       5    45   45   45   5        45
+\& <ACK>                       6    46   46   46   6        46
+\& <BEL>                       7    47   47   47   7        47
+\& <BS>                        8    22   22   22   8        22
+\& <HT>                        9    5    5    5    9        5
+\& <LF>                        10   37   21   21   10       21  **
+\& <VT>                        11   11   11   11   11       11
+\& <FF>                        12   12   12   12   12       12
+\& <CR>                        13   13   13   13   13       13
+\& <SO>                        14   14   14   14   14       14
+\& <SI>                        15   15   15   15   15       15
+\& <DLE>                       16   16   16   16   16       16
+\& <DC1>                       17   17   17   17   17       17
+\& <DC2>                       18   18   18   18   18       18
+\& <DC3>                       19   19   19   19   19       19
+\& <DC4>                       20   60   60   60   20       60
+\& <NAK>                       21   61   61   61   21       61
+\& <SYN>                       22   50   50   50   22       50
+\& <ETB>                       23   38   38   38   23       38
+\& <CAN>                       24   24   24   24   24       24
+\& <EOM>                       25   25   25   25   25       25
+\& <SUB>                       26   63   63   63   26       63
+\& <ESC>                       27   39   39   39   27       39
+\& <FS>                        28   28   28   28   28       28
+\& <GS>                        29   29   29   29   29       29
+\& <RS>                        30   30   30   30   30       30
+\& <US>                        31   31   31   31   31       31
+\& <SPACE>                     32   64   64   64   32       64
+\& !                           33   90   90   90   33       90
+\& "                           34   127  127  127  34       127
+\& #                           35   123  123  123  35       123
+\& $                           36   91   91   91   36       91
+\& %                           37   108  108  108  37       108
+\& &                           38   80   80   80   38       80
+\& \*(Aq                           39   125  125  125  39       125
+\& (                           40   77   77   77   40       77
+\& )                           41   93   93   93   41       93
+\& *                           42   92   92   92   42       92
+\& +                           43   78   78   78   43       78
+\& ,                           44   107  107  107  44       107
+\& \-                           45   96   96   96   45       96
+\& .                           46   75   75   75   46       75
+\& /                           47   97   97   97   47       97
+\& 0                           48   240  240  240  48       240
+\& 1                           49   241  241  241  49       241
+\& 2                           50   242  242  242  50       242
+\& 3                           51   243  243  243  51       243
+\& 4                           52   244  244  244  52       244
+\& 5                           53   245  245  245  53       245
+\& 6                           54   246  246  246  54       246
+\& 7                           55   247  247  247  55       247
+\& 8                           56   248  248  248  56       248
+\& 9                           57   249  249  249  57       249
+\& :                           58   122  122  122  58       122
+\& ;                           59   94   94   94   59       94
+\& <                           60   76   76   76   60       76
+\& =                           61   126  126  126  61       126
+\& >                           62   110  110  110  62       110
+\& ?                           63   111  111  111  63       111
+\& @                           64   124  124  124  64       124
+\& A                           65   193  193  193  65       193
+\& B                           66   194  194  194  66       194
+\& C                           67   195  195  195  67       195
+\& D                           68   196  196  196  68       196
+\& E                           69   197  197  197  69       197
+\& F                           70   198  198  198  70       198
+\& G                           71   199  199  199  71       199
+\& H                           72   200  200  200  72       200
+\& I                           73   201  201  201  73       201
+\& J                           74   209  209  209  74       209
+\& K                           75   210  210  210  75       210
+\& L                           76   211  211  211  76       211
+\& M                           77   212  212  212  77       212
+\& N                           78   213  213  213  78       213
+\& O                           79   214  214  214  79       214
+\& P                           80   215  215  215  80       215
+\& Q                           81   216  216  216  81       216
+\& R                           82   217  217  217  82       217
+\& S                           83   226  226  226  83       226
+\& T                           84   227  227  227  84       227
+\& U                           85   228  228  228  85       228
+\& V                           86   229  229  229  86       229
+\& W                           87   230  230  230  87       230
+\& X                           88   231  231  231  88       231
+\& Y                           89   232  232  232  89       232
+\& Z                           90   233  233  233  90       233
+\& [                           91   186  173  187  91       173  ** ##
+\& \e                           92   224  224  188  92       224  ##
+\& ]                           93   187  189  189  93       189  **
+\& ^                           94   176  95   106  94       95   ** ##
+\& _                           95   109  109  109  95       109
+\& \`                           96   121  121  74   96       121  ##
+\& a                           97   129  129  129  97       129
+\& b                           98   130  130  130  98       130
+\& c                           99   131  131  131  99       131
+\& d                           100  132  132  132  100      132
+\& e                           101  133  133  133  101      133
+\& f                           102  134  134  134  102      134
+\& g                           103  135  135  135  103      135
+\& h                           104  136  136  136  104      136
+\& i                           105  137  137  137  105      137
+\& j                           106  145  145  145  106      145
+\& k                           107  146  146  146  107      146
+\& l                           108  147  147  147  108      147
+\& m                           109  148  148  148  109      148
+\& n                           110  149  149  149  110      149
+\& o                           111  150  150  150  111      150
+\& p                           112  151  151  151  112      151
+\& q                           113  152  152  152  113      152
+\& r                           114  153  153  153  114      153
+\& s                           115  162  162  162  115      162
+\& t                           116  163  163  163  116      163
+\& u                           117  164  164  164  117      164
+\& v                           118  165  165  165  118      165
+\& w                           119  166  166  166  119      166
+\& x                           120  167  167  167  120      167
+\& y                           121  168  168  168  121      168
+\& z                           122  169  169  169  122      169
+\& {                           123  192  192  251  123      192  ##
+\& |                           124  79   79   79   124      79
+\& }                           125  208  208  253  125      208  ##
+\& ~                           126  161  161  255  126      161  ##
+\& <DEL>                       127  7    7    7    127      7
+\& <PAD>                       128  32   32   32   194.128  32
+\& <HOP>                       129  33   33   33   194.129  33
+\& <BPH>                       130  34   34   34   194.130  34
+\& <NBH>                       131  35   35   35   194.131  35
+\& <IND>                       132  36   36   36   194.132  36
+\& <NEL>                       133  21   37   37   194.133  37   **
+\& <SSA>                       134  6    6    6    194.134  6
+\& <ESA>                       135  23   23   23   194.135  23
+\& <HTS>                       136  40   40   40   194.136  40
+\& <HTJ>                       137  41   41   41   194.137  41
+\& <VTS>                       138  42   42   42   194.138  42
+\& <PLD>                       139  43   43   43   194.139  43
+\& <PLU>                       140  44   44   44   194.140  44
+\& <RI>                        141  9    9    9    194.141  9
+\& <SS2>                       142  10   10   10   194.142  10
+\& <SS3>                       143  27   27   27   194.143  27
+\& <DCS>                       144  48   48   48   194.144  48
+\& <PU1>                       145  49   49   49   194.145  49
+\& <PU2>                       146  26   26   26   194.146  26
+\& <STS>                       147  51   51   51   194.147  51
+\& <CCH>                       148  52   52   52   194.148  52
+\& <MW>                        149  53   53   53   194.149  53
+\& <SPA>                       150  54   54   54   194.150  54
+\& <EPA>                       151  8    8    8    194.151  8
+\& <SOS>                       152  56   56   56   194.152  56
+\& <SGC>                       153  57   57   57   194.153  57
+\& <SCI>                       154  58   58   58   194.154  58
+\& <CSI>                       155  59   59   59   194.155  59
+\& <ST>                        156  4    4    4    194.156  4
+\& <OSC>                       157  20   20   20   194.157  20
+\& <PM>                        158  62   62   62   194.158  62
+\& <APC>                       159  255  255  95   194.159  255      ##
+\& <NON\-BREAKING SPACE>        160  65   65   65   194.160  128.65
+\& <INVERTED "!" >             161  170  170  170  194.161  128.66
+\& <CENT SIGN>                 162  74   74   176  194.162  128.67   ##
+\& <POUND SIGN>                163  177  177  177  194.163  128.68
+\& <CURRENCY SIGN>             164  159  159  159  194.164  128.69
+\& <YEN SIGN>                  165  178  178  178  194.165  128.70
+\& <BROKEN BAR>                166  106  106  208  194.166  128.71   ##
+\& <SECTION SIGN>              167  181  181  181  194.167  128.72
+\& <DIAERESIS>                 168  189  187  121  194.168  128.73   ** ##
+\& <COPYRIGHT SIGN>            169  180  180  180  194.169  128.74
+\& <FEMININE ORDINAL>          170  154  154  154  194.170  128.81
+\& <LEFT POINTING GUILLEMET>   171  138  138  138  194.171  128.82
+\& <NOT SIGN>                  172  95   176  186  194.172  128.83   ** ##
+\& <SOFT HYPHEN>               173  202  202  202  194.173  128.84
+\& <REGISTERED TRADE MARK>     174  175  175  175  194.174  128.85
+\& <MACRON>                    175  188  188  161  194.175  128.86   ##
+\& <DEGREE SIGN>               176  144  144  144  194.176  128.87
+\& <PLUS\-OR\-MINUS SIGN>        177  143  143  143  194.177  128.88
+\& <SUPERSCRIPT TWO>           178  234  234  234  194.178  128.89
+\& <SUPERSCRIPT THREE>         179  250  250  250  194.179  128.98
+\& <ACUTE ACCENT>              180  190  190  190  194.180  128.99
+\& <MICRO SIGN>                181  160  160  160  194.181  128.100
+\& <PARAGRAPH SIGN>            182  182  182  182  194.182  128.101
+\& <MIDDLE DOT>                183  179  179  179  194.183  128.102
+\& <CEDILLA>                   184  157  157  157  194.184  128.103
+\& <SUPERSCRIPT ONE>           185  218  218  218  194.185  128.104
+\& <MASC. ORDINAL INDICATOR>   186  155  155  155  194.186  128.105
+\& <RIGHT POINTING GUILLEMET>  187  139  139  139  194.187  128.106
+\& <FRACTION ONE QUARTER>      188  183  183  183  194.188  128.112
+\& <FRACTION ONE HALF>         189  184  184  184  194.189  128.113
+\& <FRACTION THREE QUARTERS>   190  185  185  185  194.190  128.114
+\& <INVERTED QUESTION MARK>    191  171  171  171  194.191  128.115
+\& <A WITH GRAVE>              192  100  100  100  195.128  138.65
+\& <A WITH ACUTE>              193  101  101  101  195.129  138.66
+\& <A WITH CIRCUMFLEX>         194  98   98   98   195.130  138.67
+\& <A WITH TILDE>              195  102  102  102  195.131  138.68
+\& <A WITH DIAERESIS>          196  99   99   99   195.132  138.69
+\& <A WITH RING ABOVE>         197  103  103  103  195.133  138.70
+\& <CAPITAL LIGATURE AE>       198  158  158  158  195.134  138.71
+\& <C WITH CEDILLA>            199  104  104  104  195.135  138.72
+\& <E WITH GRAVE>              200  116  116  116  195.136  138.73
+\& <E WITH ACUTE>              201  113  113  113  195.137  138.74
+\& <E WITH CIRCUMFLEX>         202  114  114  114  195.138  138.81
+\& <E WITH DIAERESIS>          203  115  115  115  195.139  138.82
+\& <I WITH GRAVE>              204  120  120  120  195.140  138.83
+\& <I WITH ACUTE>              205  117  117  117  195.141  138.84
+\& <I WITH CIRCUMFLEX>         206  118  118  118  195.142  138.85
+\& <I WITH DIAERESIS>          207  119  119  119  195.143  138.86
+\& <CAPITAL LETTER ETH>        208  172  172  172  195.144  138.87
+\& <N WITH TILDE>              209  105  105  105  195.145  138.88
+\& <O WITH GRAVE>              210  237  237  237  195.146  138.89
+\& <O WITH ACUTE>              211  238  238  238  195.147  138.98
+\& <O WITH CIRCUMFLEX>         212  235  235  235  195.148  138.99
+\& <O WITH TILDE>              213  239  239  239  195.149  138.100
+\& <O WITH DIAERESIS>          214  236  236  236  195.150  138.101
+\& <MULTIPLICATION SIGN>       215  191  191  191  195.151  138.102
+\& <O WITH STROKE>             216  128  128  128  195.152  138.103
+\& <U WITH GRAVE>              217  253  253  224  195.153  138.104  ##
+\& <U WITH ACUTE>              218  254  254  254  195.154  138.105
+\& <U WITH CIRCUMFLEX>         219  251  251  221  195.155  138.106  ##
+\& <U WITH DIAERESIS>          220  252  252  252  195.156  138.112
+\& <Y WITH ACUTE>              221  173  186  173  195.157  138.113  ** ##
+\& <CAPITAL LETTER THORN>      222  174  174  174  195.158  138.114
+\& <SMALL LETTER SHARP S>      223  89   89   89   195.159  138.115
+\& <a WITH GRAVE>              224  68   68   68   195.160  139.65
+\& <a WITH ACUTE>              225  69   69   69   195.161  139.66
+\& <a WITH CIRCUMFLEX>         226  66   66   66   195.162  139.67
+\& <a WITH TILDE>              227  70   70   70   195.163  139.68
+\& <a WITH DIAERESIS>          228  67   67   67   195.164  139.69
+\& <a WITH RING ABOVE>         229  71   71   71   195.165  139.70
+\& <SMALL LIGATURE ae>         230  156  156  156  195.166  139.71
+\& <c WITH CEDILLA>            231  72   72   72   195.167  139.72
+\& <e WITH GRAVE>              232  84   84   84   195.168  139.73
+\& <e WITH ACUTE>              233  81   81   81   195.169  139.74
+\& <e WITH CIRCUMFLEX>         234  82   82   82   195.170  139.81
+\& <e WITH DIAERESIS>          235  83   83   83   195.171  139.82
+\& <i WITH GRAVE>              236  88   88   88   195.172  139.83
+\& <i WITH ACUTE>              237  85   85   85   195.173  139.84
+\& <i WITH CIRCUMFLEX>         238  86   86   86   195.174  139.85
+\& <i WITH DIAERESIS>          239  87   87   87   195.175  139.86
+\& <SMALL LETTER eth>          240  140  140  140  195.176  139.87
+\& <n WITH TILDE>              241  73   73   73   195.177  139.88
+\& <o WITH GRAVE>              242  205  205  205  195.178  139.89
+\& <o WITH ACUTE>              243  206  206  206  195.179  139.98
+\& <o WITH CIRCUMFLEX>         244  203  203  203  195.180  139.99
+\& <o WITH TILDE>              245  207  207  207  195.181  139.100
+\& <o WITH DIAERESIS>          246  204  204  204  195.182  139.101
+\& <DIVISION SIGN>             247  225  225  225  195.183  139.102
+\& <o WITH STROKE>             248  112  112  112  195.184  139.103
+\& <u WITH GRAVE>              249  221  221  192  195.185  139.104  ##
+\& <u WITH ACUTE>              250  222  222  222  195.186  139.105
+\& <u WITH CIRCUMFLEX>         251  219  219  219  195.187  139.106
+\& <u WITH DIAERESIS>          252  220  220  220  195.188  139.112
+\& <y WITH ACUTE>              253  141  141  141  195.189  139.113
+\& <SMALL LETTER thorn>        254  142  142  142  195.190  139.114
+\& <y WITH DIAERESIS>          255  223  223  223  195.191  139.115
+.Ve
+.PP
+If you would rather see the above table in CCSID 0037 order rather than
+ASCII + Latin\-1 order then run the table through:
+.IP "recipe 4" 4
+.IX Item "recipe 4"
+.PP
+.Vb 6
+\& perl \e
+\&    \-ne \*(Aqif(/.{29}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}/)\*(Aq\e
+\&     \-e \*(Aq{push(@l,$_)}\*(Aq \e
+\&     \-e \*(AqEND{print map{$_\->[0]}\*(Aq \e
+\&     \-e \*(Aq          sort{$a\->[1] <=> $b\->[1]}\*(Aq \e
+\&     \-e \*(Aq          map{[$_,substr($_,34,3)]}@l;}\*(Aq perlebcdic.pod
+.Ve
+.PP
+If you would rather see it in CCSID 1047 order then change the number
+34 in the last line to 39, like this:
+.IP "recipe 5" 4
+.IX Item "recipe 5"
+.PP
+.Vb 6
+\& perl \e
+\&    \-ne \*(Aqif(/.{29}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}/)\*(Aq\e
+\&    \-e \*(Aq{push(@l,$_)}\*(Aq \e
+\&    \-e \*(AqEND{print map{$_\->[0]}\*(Aq \e
+\&    \-e \*(Aq          sort{$a\->[1] <=> $b\->[1]}\*(Aq \e
+\&    \-e \*(Aq          map{[$_,substr($_,39,3)]}@l;}\*(Aq perlebcdic.pod
+.Ve
+.PP
+If you would rather see it in POSIX-BC order then change the number
+34 in the last line to 44, like this:
+.IP "recipe 6" 4
+.IX Item "recipe 6"
+.PP
+.Vb 6
+\& perl \e
+\&    \-ne \*(Aqif(/.{29}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}\es{2,4}\ed{1,3}/)\*(Aq\e
+\&     \-e \*(Aq{push(@l,$_)}\*(Aq \e
+\&     \-e \*(AqEND{print map{$_\->[0]}\*(Aq \e
+\&     \-e \*(Aq          sort{$a\->[1] <=> $b\->[1]}\*(Aq \e
+\&     \-e \*(Aq          map{[$_,substr($_,44,3)]}@l;}\*(Aq perlebcdic.pod
+.Ve
+.SS "Table in hex, sorted in 1047 order"
+.IX Subsection "Table in hex, sorted in 1047 order"
+Since this document was first written, the convention has become more
+and more to use hexadecimal notation for code points.  To do this with
+the recipes and to also sort is a multi-step process, so here, for
+convenience, is the table from above, re-sorted to be in Code Page 1047
+order, and using hex notation.
+.PP
+.Vb 10
+\&                          ISO
+\&                         8859\-1             POS\-         CCSID
+\&                         CCSID  CCSID CCSID IX\-          1047
+\&  chr                     0819   0037 1047  BC  UTF\-8  UTF\-EBCDIC
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& <NUL>                       00   00   00   00   00       00
+\& <SOH>                       01   01   01   01   01       01
+\& <STX>                       02   02   02   02   02       02
+\& <ETX>                       03   03   03   03   03       03
+\& <ST>                        9C   04   04   04   C2.9C    04
+\& <HT>                        09   05   05   05   09       05
+\& <SSA>                       86   06   06   06   C2.86    06
+\& <DEL>                       7F   07   07   07   7F       07
+\& <EPA>                       97   08   08   08   C2.97    08
+\& <RI>                        8D   09   09   09   C2.8D    09
+\& <SS2>                       8E   0A   0A   0A   C2.8E    0A
+\& <VT>                        0B   0B   0B   0B   0B       0B
+\& <FF>                        0C   0C   0C   0C   0C       0C
+\& <CR>                        0D   0D   0D   0D   0D       0D
+\& <SO>                        0E   0E   0E   0E   0E       0E
+\& <SI>                        0F   0F   0F   0F   0F       0F
+\& <DLE>                       10   10   10   10   10       10
+\& <DC1>                       11   11   11   11   11       11
+\& <DC2>                       12   12   12   12   12       12
+\& <DC3>                       13   13   13   13   13       13
+\& <OSC>                       9D   14   14   14   C2.9D    14
+\& <LF>                        0A   25   15   15   0A       15    **
+\& <BS>                        08   16   16   16   08       16
+\& <ESA>                       87   17   17   17   C2.87    17
+\& <CAN>                       18   18   18   18   18       18
+\& <EOM>                       19   19   19   19   19       19
+\& <PU2>                       92   1A   1A   1A   C2.92    1A
+\& <SS3>                       8F   1B   1B   1B   C2.8F    1B
+\& <FS>                        1C   1C   1C   1C   1C       1C
+\& <GS>                        1D   1D   1D   1D   1D       1D
+\& <RS>                        1E   1E   1E   1E   1E       1E
+\& <US>                        1F   1F   1F   1F   1F       1F
+\& <PAD>                       80   20   20   20   C2.80    20
+\& <HOP>                       81   21   21   21   C2.81    21
+\& <BPH>                       82   22   22   22   C2.82    22
+\& <NBH>                       83   23   23   23   C2.83    23
+\& <IND>                       84   24   24   24   C2.84    24
+\& <NEL>                       85   15   25   25   C2.85    25     **
+\& <ETB>                       17   26   26   26   17       26
+\& <ESC>                       1B   27   27   27   1B       27
+\& <HTS>                       88   28   28   28   C2.88    28
+\& <HTJ>                       89   29   29   29   C2.89    29
+\& <VTS>                       8A   2A   2A   2A   C2.8A    2A
+\& <PLD>                       8B   2B   2B   2B   C2.8B    2B
+\& <PLU>                       8C   2C   2C   2C   C2.8C    2C
+\& <ENQ>                       05   2D   2D   2D   05       2D
+\& <ACK>                       06   2E   2E   2E   06       2E
+\& <BEL>                       07   2F   2F   2F   07       2F
+\& <DCS>                       90   30   30   30   C2.90    30
+\& <PU1>                       91   31   31   31   C2.91    31
+\& <SYN>                       16   32   32   32   16       32
+\& <STS>                       93   33   33   33   C2.93    33
+\& <CCH>                       94   34   34   34   C2.94    34
+\& <MW>                        95   35   35   35   C2.95    35
+\& <SPA>                       96   36   36   36   C2.96    36
+\& <EOT>                       04   37   37   37   04       37
+\& <SOS>                       98   38   38   38   C2.98    38
+\& <SGC>                       99   39   39   39   C2.99    39
+\& <SCI>                       9A   3A   3A   3A   C2.9A    3A
+\& <CSI>                       9B   3B   3B   3B   C2.9B    3B
+\& <DC4>                       14   3C   3C   3C   14       3C
+\& <NAK>                       15   3D   3D   3D   15       3D
+\& <PM>                        9E   3E   3E   3E   C2.9E    3E
+\& <SUB>                       1A   3F   3F   3F   1A       3F
+\& <SPACE>                     20   40   40   40   20       40
+\& <NON\-BREAKING SPACE>        A0   41   41   41   C2.A0    80.41
+\& <a WITH CIRCUMFLEX>         E2   42   42   42   C3.A2    8B.43
+\& <a WITH DIAERESIS>          E4   43   43   43   C3.A4    8B.45
+\& <a WITH GRAVE>              E0   44   44   44   C3.A0    8B.41
+\& <a WITH ACUTE>              E1   45   45   45   C3.A1    8B.42
+\& <a WITH TILDE>              E3   46   46   46   C3.A3    8B.44
+\& <a WITH RING ABOVE>         E5   47   47   47   C3.A5    8B.46
+\& <c WITH CEDILLA>            E7   48   48   48   C3.A7    8B.48
+\& <n WITH TILDE>              F1   49   49   49   C3.B1    8B.58
+\& <CENT SIGN>                 A2   4A   4A   B0   C2.A2    80.43  ##
+\& .                           2E   4B   4B   4B   2E       4B
+\& <                           3C   4C   4C   4C   3C       4C
+\& (                           28   4D   4D   4D   28       4D
+\& +                           2B   4E   4E   4E   2B       4E
+\& |                           7C   4F   4F   4F   7C       4F
+\& &                           26   50   50   50   26       50
+\& <e WITH ACUTE>              E9   51   51   51   C3.A9    8B.4A
+\& <e WITH CIRCUMFLEX>         EA   52   52   52   C3.AA    8B.51
+\& <e WITH DIAERESIS>          EB   53   53   53   C3.AB    8B.52
+\& <e WITH GRAVE>              E8   54   54   54   C3.A8    8B.49
+\& <i WITH ACUTE>              ED   55   55   55   C3.AD    8B.54
+\& <i WITH CIRCUMFLEX>         EE   56   56   56   C3.AE    8B.55
+\& <i WITH DIAERESIS>          EF   57   57   57   C3.AF    8B.56
+\& <i WITH GRAVE>              EC   58   58   58   C3.AC    8B.53
+\& <SMALL LETTER SHARP S>      DF   59   59   59   C3.9F    8A.73
+\& !                           21   5A   5A   5A   21       5A
+\& $                           24   5B   5B   5B   24       5B
+\& *                           2A   5C   5C   5C   2A       5C
+\& )                           29   5D   5D   5D   29       5D
+\& ;                           3B   5E   5E   5E   3B       5E
+\& ^                           5E   B0   5F   6A   5E       5F     ** ##
+\& \-                           2D   60   60   60   2D       60
+\& /                           2F   61   61   61   2F       61
+\& <A WITH CIRCUMFLEX>         C2   62   62   62   C3.82    8A.43
+\& <A WITH DIAERESIS>          C4   63   63   63   C3.84    8A.45
+\& <A WITH GRAVE>              C0   64   64   64   C3.80    8A.41
+\& <A WITH ACUTE>              C1   65   65   65   C3.81    8A.42
+\& <A WITH TILDE>              C3   66   66   66   C3.83    8A.44
+\& <A WITH RING ABOVE>         C5   67   67   67   C3.85    8A.46
+\& <C WITH CEDILLA>            C7   68   68   68   C3.87    8A.48
+\& <N WITH TILDE>              D1   69   69   69   C3.91    8A.58
+\& <BROKEN BAR>                A6   6A   6A   D0   C2.A6    80.47  ##
+\& ,                           2C   6B   6B   6B   2C       6B
+\& %                           25   6C   6C   6C   25       6C
+\& _                           5F   6D   6D   6D   5F       6D
+\& >                           3E   6E   6E   6E   3E       6E
+\& ?                           3F   6F   6F   6F   3F       6F
+\& <o WITH STROKE>             F8   70   70   70   C3.B8    8B.67
+\& <E WITH ACUTE>              C9   71   71   71   C3.89    8A.4A
+\& <E WITH CIRCUMFLEX>         CA   72   72   72   C3.8A    8A.51
+\& <E WITH DIAERESIS>          CB   73   73   73   C3.8B    8A.52
+\& <E WITH GRAVE>              C8   74   74   74   C3.88    8A.49
+\& <I WITH ACUTE>              CD   75   75   75   C3.8D    8A.54
+\& <I WITH CIRCUMFLEX>         CE   76   76   76   C3.8E    8A.55
+\& <I WITH DIAERESIS>          CF   77   77   77   C3.8F    8A.56
+\& <I WITH GRAVE>              CC   78   78   78   C3.8C    8A.53
+\& \`                           60   79   79   4A   60       79     ##
+\& :                           3A   7A   7A   7A   3A       7A
+\& #                           23   7B   7B   7B   23       7B
+\& @                           40   7C   7C   7C   40       7C
+\& \*(Aq                           27   7D   7D   7D   27       7D
+\& =                           3D   7E   7E   7E   3D       7E
+\& "                           22   7F   7F   7F   22       7F
+\& <O WITH STROKE>             D8   80   80   80   C3.98    8A.67
+\& a                           61   81   81   81   61       81
+\& b                           62   82   82   82   62       82
+\& c                           63   83   83   83   63       83
+\& d                           64   84   84   84   64       84
+\& e                           65   85   85   85   65       85
+\& f                           66   86   86   86   66       86
+\& g                           67   87   87   87   67       87
+\& h                           68   88   88   88   68       88
+\& i                           69   89   89   89   69       89
+\& <LEFT POINTING GUILLEMET>   AB   8A   8A   8A   C2.AB    80.52
+\& <RIGHT POINTING GUILLEMET>  BB   8B   8B   8B   C2.BB    80.6A
+\& <SMALL LETTER eth>          F0   8C   8C   8C   C3.B0    8B.57
+\& <y WITH ACUTE>              FD   8D   8D   8D   C3.BD    8B.71
+\& <SMALL LETTER thorn>        FE   8E   8E   8E   C3.BE    8B.72
+\& <PLUS\-OR\-MINUS SIGN>        B1   8F   8F   8F   C2.B1    80.58
+\& <DEGREE SIGN>               B0   90   90   90   C2.B0    80.57
+\& j                           6A   91   91   91   6A       91
+\& k                           6B   92   92   92   6B       92
+\& l                           6C   93   93   93   6C       93
+\& m                           6D   94   94   94   6D       94
+\& n                           6E   95   95   95   6E       95
+\& o                           6F   96   96   96   6F       96
+\& p                           70   97   97   97   70       97
+\& q                           71   98   98   98   71       98
+\& r                           72   99   99   99   72       99
+\& <FEMININE ORDINAL>          AA   9A   9A   9A   C2.AA    80.51
+\& <MASC. ORDINAL INDICATOR>   BA   9B   9B   9B   C2.BA    80.69
+\& <SMALL LIGATURE ae>         E6   9C   9C   9C   C3.A6    8B.47
+\& <CEDILLA>                   B8   9D   9D   9D   C2.B8    80.67
+\& <CAPITAL LIGATURE AE>       C6   9E   9E   9E   C3.86    8A.47
+\& <CURRENCY SIGN>             A4   9F   9F   9F   C2.A4    80.45
+\& <MICRO SIGN>                B5   A0   A0   A0   C2.B5    80.64
+\& ~                           7E   A1   A1   FF   7E       A1     ##
+\& s                           73   A2   A2   A2   73       A2
+\& t                           74   A3   A3   A3   74       A3
+\& u                           75   A4   A4   A4   75       A4
+\& v                           76   A5   A5   A5   76       A5
+\& w                           77   A6   A6   A6   77       A6
+\& x                           78   A7   A7   A7   78       A7
+\& y                           79   A8   A8   A8   79       A8
+\& z                           7A   A9   A9   A9   7A       A9
+\& <INVERTED "!" >             A1   AA   AA   AA   C2.A1    80.42
+\& <INVERTED QUESTION MARK>    BF   AB   AB   AB   C2.BF    80.73
+\& <CAPITAL LETTER ETH>        D0   AC   AC   AC   C3.90    8A.57
+\& [                           5B   BA   AD   BB   5B       AD     ** ##
+\& <CAPITAL LETTER THORN>      DE   AE   AE   AE   C3.9E    8A.72
+\& <REGISTERED TRADE MARK>     AE   AF   AF   AF   C2.AE    80.55
+\& <NOT SIGN>                  AC   5F   B0   BA   C2.AC    80.53  ** ##
+\& <POUND SIGN>                A3   B1   B1   B1   C2.A3    80.44
+\& <YEN SIGN>                  A5   B2   B2   B2   C2.A5    80.46
+\& <MIDDLE DOT>                B7   B3   B3   B3   C2.B7    80.66
+\& <COPYRIGHT SIGN>            A9   B4   B4   B4   C2.A9    80.4A
+\& <SECTION SIGN>              A7   B5   B5   B5   C2.A7    80.48
+\& <PARAGRAPH SIGN>            B6   B6   B6   B6   C2.B6    80.65
+\& <FRACTION ONE QUARTER>      BC   B7   B7   B7   C2.BC    80.70
+\& <FRACTION ONE HALF>         BD   B8   B8   B8   C2.BD    80.71
+\& <FRACTION THREE QUARTERS>   BE   B9   B9   B9   C2.BE    80.72
+\& <Y WITH ACUTE>              DD   AD   BA   AD   C3.9D    8A.71  ** ##
+\& <DIAERESIS>                 A8   BD   BB   79   C2.A8    80.49  ** ##
+\& <MACRON>                    AF   BC   BC   A1   C2.AF    80.56  ##
+\& ]                           5D   BB   BD   BD   5D       BD     **
+\& <ACUTE ACCENT>              B4   BE   BE   BE   C2.B4    80.63
+\& <MULTIPLICATION SIGN>       D7   BF   BF   BF   C3.97    8A.66
+\& {                           7B   C0   C0   FB   7B       C0     ##
+\& A                           41   C1   C1   C1   41       C1
+\& B                           42   C2   C2   C2   42       C2
+\& C                           43   C3   C3   C3   43       C3
+\& D                           44   C4   C4   C4   44       C4
+\& E                           45   C5   C5   C5   45       C5
+\& F                           46   C6   C6   C6   46       C6
+\& G                           47   C7   C7   C7   47       C7
+\& H                           48   C8   C8   C8   48       C8
+\& I                           49   C9   C9   C9   49       C9
+\& <SOFT HYPHEN>               AD   CA   CA   CA   C2.AD    80.54
+\& <o WITH CIRCUMFLEX>         F4   CB   CB   CB   C3.B4    8B.63
+\& <o WITH DIAERESIS>          F6   CC   CC   CC   C3.B6    8B.65
+\& <o WITH GRAVE>              F2   CD   CD   CD   C3.B2    8B.59
+\& <o WITH ACUTE>              F3   CE   CE   CE   C3.B3    8B.62
+\& <o WITH TILDE>              F5   CF   CF   CF   C3.B5    8B.64
+\& }                           7D   D0   D0   FD   7D       D0     ##
+\& J                           4A   D1   D1   D1   4A       D1
+\& K                           4B   D2   D2   D2   4B       D2
+\& L                           4C   D3   D3   D3   4C       D3
+\& M                           4D   D4   D4   D4   4D       D4
+\& N                           4E   D5   D5   D5   4E       D5
+\& O                           4F   D6   D6   D6   4F       D6
+\& P                           50   D7   D7   D7   50       D7
+\& Q                           51   D8   D8   D8   51       D8
+\& R                           52   D9   D9   D9   52       D9
+\& <SUPERSCRIPT ONE>           B9   DA   DA   DA   C2.B9    80.68
+\& <u WITH CIRCUMFLEX>         FB   DB   DB   DB   C3.BB    8B.6A
+\& <u WITH DIAERESIS>          FC   DC   DC   DC   C3.BC    8B.70
+\& <u WITH GRAVE>              F9   DD   DD   C0   C3.B9    8B.68  ##
+\& <u WITH ACUTE>              FA   DE   DE   DE   C3.BA    8B.69
+\& <y WITH DIAERESIS>          FF   DF   DF   DF   C3.BF    8B.73
+\& \e                           5C   E0   E0   BC   5C       E0     ##
+\& <DIVISION SIGN>             F7   E1   E1   E1   C3.B7    8B.66
+\& S                           53   E2   E2   E2   53       E2
+\& T                           54   E3   E3   E3   54       E3
+\& U                           55   E4   E4   E4   55       E4
+\& V                           56   E5   E5   E5   56       E5
+\& W                           57   E6   E6   E6   57       E6
+\& X                           58   E7   E7   E7   58       E7
+\& Y                           59   E8   E8   E8   59       E8
+\& Z                           5A   E9   E9   E9   5A       E9
+\& <SUPERSCRIPT TWO>           B2   EA   EA   EA   C2.B2    80.59
+\& <O WITH CIRCUMFLEX>         D4   EB   EB   EB   C3.94    8A.63
+\& <O WITH DIAERESIS>          D6   EC   EC   EC   C3.96    8A.65
+\& <O WITH GRAVE>              D2   ED   ED   ED   C3.92    8A.59
+\& <O WITH ACUTE>              D3   EE   EE   EE   C3.93    8A.62
+\& <O WITH TILDE>              D5   EF   EF   EF   C3.95    8A.64
+\& 0                           30   F0   F0   F0   30       F0
+\& 1                           31   F1   F1   F1   31       F1
+\& 2                           32   F2   F2   F2   32       F2
+\& 3                           33   F3   F3   F3   33       F3
+\& 4                           34   F4   F4   F4   34       F4
+\& 5                           35   F5   F5   F5   35       F5
+\& 6                           36   F6   F6   F6   36       F6
+\& 7                           37   F7   F7   F7   37       F7
+\& 8                           38   F8   F8   F8   38       F8
+\& 9                           39   F9   F9   F9   39       F9
+\& <SUPERSCRIPT THREE>         B3   FA   FA   FA   C2.B3    80.62
+\& <U WITH CIRCUMFLEX>         DB   FB   FB   DD   C3.9B    8A.6A  ##
+\& <U WITH DIAERESIS>          DC   FC   FC   FC   C3.9C    8A.70
+\& <U WITH GRAVE>              D9   FD   FD   E0   C3.99    8A.68  ##
+\& <U WITH ACUTE>              DA   FE   FE   FE   C3.9A    8A.69
+\& <APC>                       9F   FF   FF   5F   C2.9F    FF     ##
+.Ve
+.SH "IDENTIFYING CHARACTER CODE SETS"
+.IX Header "IDENTIFYING CHARACTER CODE SETS"
+It is possible to determine which character set you are operating under.
+But first you need to be really really sure you need to do this.  Your
+code will be simpler and probably just as portable if you don't have
+to test the character set and do different things, depending.  There are
+actually only very few circumstances where it's not easy to write
+straight-line code portable to all character sets.  See
+"Unicode and EBCDIC" in perluniintro for how to portably specify
+characters.
+.PP
+But there are some cases where you may want to know which character set
+you are running under.  One possible example is doing
+sorting in inner loops where performance is critical.
+.PP
+To determine if you are running under ASCII or EBCDIC, you can use the
+return value of \f(CWord()\fR or \f(CWchr()\fR to test one or more character
+values.  For example:
+.PP
+.Vb 4
+\&    $is_ascii  = "A" eq chr(65);
+\&    $is_ebcdic = "A" eq chr(193);
+\&    $is_ascii  = ord("A") == 65;
+\&    $is_ebcdic = ord("A") == 193;
+.Ve
+.PP
+There's even less need to distinguish between EBCDIC code pages, but to
+do so try looking at one or more of the characters that differ between
+them.
+.PP
+.Vb 4
+\&    $is_ascii           = ord(\*(Aq[\*(Aq) == 91;
+\&    $is_ebcdic_37       = ord(\*(Aq[\*(Aq) == 186;
+\&    $is_ebcdic_1047     = ord(\*(Aq[\*(Aq) == 173;
+\&    $is_ebcdic_POSIX_BC = ord(\*(Aq[\*(Aq) == 187;
+.Ve
+.PP
+However, it would be unwise to write tests such as:
+.PP
+.Vb 2
+\&    $is_ascii = "\er" ne chr(13);  #  WRONG
+\&    $is_ascii = "\en" ne chr(10);  #  ILL ADVISED
+.Ve
+.PP
+Obviously the first of these will fail to distinguish most ASCII
+platforms from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC
+platform since \f(CW\*(C`"\er"\ eq\ chr(13)\*(C'\fR under all of those coded character
+sets.  But note too that because \f(CW"\en"\fR is \f(CWchr(13)\fR and \f(CW"\er"\fR is
+\&\f(CWchr(10)\fR on old Macintosh (which is an ASCII platform) the second
+\&\f(CW$is_ascii\fR test will lead to trouble there.
+.PP
+To determine whether or not perl was built under an EBCDIC
+code page you can use the Config module like so:
+.PP
+.Vb 2
+\&    use Config;
+\&    $is_ebcdic = $Config{\*(Aqebcdic\*(Aq} eq \*(Aqdefine\*(Aq;
+.Ve
+.SH CONVERSIONS
+.IX Header "CONVERSIONS"
+.ie n .SS "utf8::unicode_to_native() and utf8::native_to_unicode()"
+.el .SS "\f(CWutf8::unicode_to_native()\fP and \f(CWutf8::native_to_unicode()\fP"
+.IX Subsection "utf8::unicode_to_native() and utf8::native_to_unicode()"
+These functions take an input numeric code point in one encoding and
+return what its equivalent value is in the other.
+.PP
+See utf8.
+.SS tr///
+.IX Subsection "tr///"
+In order to convert a string of characters from one character set to
+another a simple list of numbers, such as in the right columns in the
+above table, along with Perl's \f(CW\*(C`tr///\*(C'\fR operator is all that is needed.
+The data in the table are in ASCII/Latin1 order, hence the EBCDIC columns
+provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily
+reversed.
+.PP
+For example, to convert ASCII/Latin1 to code page 037 take the output of the
+second numbers column from the output of recipe 2 (modified to add
+\&\f(CW"\e"\fR characters), and use it in \f(CW\*(C`tr///\*(C'\fR like so:
+.PP
+.Vb 10
+\&    $cp_037 =
+\&    \*(Aq\ex00\ex01\ex02\ex03\ex37\ex2D\ex2E\ex2F\ex16\ex05\ex25\ex0B\ex0C\ex0D\ex0E\ex0F\*(Aq .
+\&    \*(Aq\ex10\ex11\ex12\ex13\ex3C\ex3D\ex32\ex26\ex18\ex19\ex3F\ex27\ex1C\ex1D\ex1E\ex1F\*(Aq .
+\&    \*(Aq\ex40\ex5A\ex7F\ex7B\ex5B\ex6C\ex50\ex7D\ex4D\ex5D\ex5C\ex4E\ex6B\ex60\ex4B\ex61\*(Aq .
+\&    \*(Aq\exF0\exF1\exF2\exF3\exF4\exF5\exF6\exF7\exF8\exF9\ex7A\ex5E\ex4C\ex7E\ex6E\ex6F\*(Aq .
+\&    \*(Aq\ex7C\exC1\exC2\exC3\exC4\exC5\exC6\exC7\exC8\exC9\exD1\exD2\exD3\exD4\exD5\exD6\*(Aq .
+\&    \*(Aq\exD7\exD8\exD9\exE2\exE3\exE4\exE5\exE6\exE7\exE8\exE9\exBA\exE0\exBB\exB0\ex6D\*(Aq .
+\&    \*(Aq\ex79\ex81\ex82\ex83\ex84\ex85\ex86\ex87\ex88\ex89\ex91\ex92\ex93\ex94\ex95\ex96\*(Aq .
+\&    \*(Aq\ex97\ex98\ex99\exA2\exA3\exA4\exA5\exA6\exA7\exA8\exA9\exC0\ex4F\exD0\exA1\ex07\*(Aq .
+\&    \*(Aq\ex20\ex21\ex22\ex23\ex24\ex15\ex06\ex17\ex28\ex29\ex2A\ex2B\ex2C\ex09\ex0A\ex1B\*(Aq .
+\&    \*(Aq\ex30\ex31\ex1A\ex33\ex34\ex35\ex36\ex08\ex38\ex39\ex3A\ex3B\ex04\ex14\ex3E\exFF\*(Aq .
+\&    \*(Aq\ex41\exAA\ex4A\exB1\ex9F\exB2\ex6A\exB5\exBD\exB4\ex9A\ex8A\ex5F\exCA\exAF\exBC\*(Aq .
+\&    \*(Aq\ex90\ex8F\exEA\exFA\exBE\exA0\exB6\exB3\ex9D\exDA\ex9B\ex8B\exB7\exB8\exB9\exAB\*(Aq .
+\&    \*(Aq\ex64\ex65\ex62\ex66\ex63\ex67\ex9E\ex68\ex74\ex71\ex72\ex73\ex78\ex75\ex76\ex77\*(Aq .
+\&    \*(Aq\exAC\ex69\exED\exEE\exEB\exEF\exEC\exBF\ex80\exFD\exFE\exFB\exFC\exAD\exAE\ex59\*(Aq .
+\&    \*(Aq\ex44\ex45\ex42\ex46\ex43\ex47\ex9C\ex48\ex54\ex51\ex52\ex53\ex58\ex55\ex56\ex57\*(Aq .
+\&    \*(Aq\ex8C\ex49\exCD\exCE\exCB\exCF\exCC\exE1\ex70\exDD\exDE\exDB\exDC\ex8D\ex8E\exDF\*(Aq;
+\&
+\&    my $ebcdic_string = $ascii_string;
+\&    eval \*(Aq$ebcdic_string =~ tr/\e000\-\e377/\*(Aq . $cp_037 . \*(Aq/\*(Aq;
+.Ve
+.PP
+To convert from EBCDIC 037 to ASCII just reverse the order of the tr///
+arguments like so:
+.PP
+.Vb 2
+\&    my $ascii_string = $ebcdic_string;
+\&    eval \*(Aq$ascii_string =~ tr/\*(Aq . $cp_037 . \*(Aq/\e000\-\e377/\*(Aq;
+.Ve
+.PP
+Similarly one could take the output of the third numbers column from recipe 2
+to obtain a \f(CW$cp_1047\fR table.  The fourth numbers column of the output from
+recipe 2 could provide a \f(CW$cp_posix_bc\fR table suitable for transcoding as
+well.
+.PP
+If you wanted to see the inverse tables, you would first have to sort on the
+desired numbers column as in recipes 4, 5 or 6, then take the output of the
+first numbers column.
+.SS iconv
+.IX Subsection "iconv"
+XPG operability often implies the presence of an \fIiconv\fR utility
+available from the shell or from the C library.  Consult your system's
+documentation for information on iconv.
+.PP
+On OS/390 or z/OS see the \fBiconv\fR\|(1) manpage.  One way to invoke the \f(CW\*(C`iconv\*(C'\fR
+shell utility from within perl would be to:
+.PP
+.Vb 2
+\&    # OS/390 or z/OS example
+\&    $ascii_data = \`echo \*(Aq$ebcdic_data\*(Aq| iconv \-f IBM\-1047 \-t ISO8859\-1\`
+.Ve
+.PP
+or the inverse map:
+.PP
+.Vb 2
+\&    # OS/390 or z/OS example
+\&    $ebcdic_data = \`echo \*(Aq$ascii_data\*(Aq| iconv \-f ISO8859\-1 \-t IBM\-1047\`
+.Ve
+.PP
+For other Perl-based conversion options see the \f(CW\*(C`Convert::*\*(C'\fR modules on CPAN.
+.SS "C RTL"
+.IX Subsection "C RTL"
+The OS/390 and z/OS C run-time libraries provide \f(CW_atoe()\fR and \f(CW_etoa()\fR functions.
+.SH "OPERATOR DIFFERENCES"
+.IX Header "OPERATOR DIFFERENCES"
+The \f(CW\*(C`..\*(C'\fR range operator treats certain character ranges with
+care on EBCDIC platforms.  For example the following array
+will have twenty six elements on either an EBCDIC platform
+or an ASCII platform:
+.PP
+.Vb 1
+\&    @alphabet = (\*(AqA\*(Aq..\*(AqZ\*(Aq);   #  $#alphabet == 25
+.Ve
+.PP
+The bitwise operators such as & ^ | may return different results
+when operating on string or character data in a Perl program running
+on an EBCDIC platform than when run on an ASCII platform.  Here is
+an example adapted from the one in perlop:
+.PP
+.Vb 5
+\&    # EBCDIC\-based examples
+\&    print "j p \en" ^ " a h";                      # prints "JAPH\en"
+\&    print "JA" | "  ph\en";                        # prints "japh\en"
+\&    print "JAPH\enJunk" & "\e277\e277\e277\e277\e277";  # prints "japh\en";
+\&    print \*(Aqp N$\*(Aq ^ " E<H\en";                      # prints "Perl\en";
+.Ve
+.PP
+An interesting property of the 32 C0 control characters
+in the ASCII table is that they can "literally" be constructed
+as control characters in Perl, e.g. \f(CW\*(C`(chr(0)\*(C'\fR eq \f(CW\*(C`\ec@\*(C'\fR)>
+\&\f(CW\*(C`(chr(1)\*(C'\fR eq \f(CW\*(C`\ecA\*(C'\fR)>, and so on.  Perl on EBCDIC platforms has been
+ported to take \f(CW\*(C`\ec@\*(C'\fR to \f(CWchr(0)\fR and \f(CW\*(C`\ecA\*(C'\fR to \f(CWchr(1)\fR, etc. as well, but the
+characters that result depend on which code page you are
+using.  The table below uses the standard acronyms for the controls.
+The POSIX-BC and 1047 sets are
+identical throughout this range and differ from the 0037 set at only
+one spot (21 decimal).  Note that the line terminator character
+may be generated by \f(CW\*(C`\ecJ\*(C'\fR on ASCII platforms but by \f(CW\*(C`\ecU\*(C'\fR on 1047 or POSIX-BC
+platforms and cannot be generated as a \f(CW"\ec.letter."\fR control character on
+0037 platforms.  Note also that \f(CW\*(C`\ec\e\*(C'\fR cannot be the final element in a string
+or regex, as it will absorb the terminator.   But \f(CW\*(C`\ec\e\fR\f(CIX\fR\f(CW\*(C'\fR is a \f(CW\*(C`FILE
+SEPARATOR\*(C'\fR concatenated with \fIX\fR for all \fIX\fR.
+The outlier \f(CW\*(C`\ec?\*(C'\fR on ASCII, which yields a non\-C0 control \f(CW\*(C`DEL\*(C'\fR,
+yields the outlier control \f(CW\*(C`APC\*(C'\fR on EBCDIC, the one that isn't in the
+block of contiguous controls.  Note that a subtlety of this is that
+\&\f(CW\*(C`\ec?\*(C'\fR on ASCII platforms is an ASCII character, while it isn't
+equivalent to any ASCII character in EBCDIC platforms.
+.PP
+.Vb 10
+\& chr   ord   8859\-1    0037    1047 && POSIX\-BC
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& \ec@     0   <NUL>     <NUL>        <NUL>
+\& \ecA     1   <SOH>     <SOH>        <SOH>
+\& \ecB     2   <STX>     <STX>        <STX>
+\& \ecC     3   <ETX>     <ETX>        <ETX>
+\& \ecD     4   <EOT>     <ST>         <ST>
+\& \ecE     5   <ENQ>     <HT>         <HT>
+\& \ecF     6   <ACK>     <SSA>        <SSA>
+\& \ecG     7   <BEL>     <DEL>        <DEL>
+\& \ecH     8   <BS>      <EPA>        <EPA>
+\& \ecI     9   <HT>      <RI>         <RI>
+\& \ecJ    10   <LF>      <SS2>        <SS2>
+\& \ecK    11   <VT>      <VT>         <VT>
+\& \ecL    12   <FF>      <FF>         <FF>
+\& \ecM    13   <CR>      <CR>         <CR>
+\& \ecN    14   <SO>      <SO>         <SO>
+\& \ecO    15   <SI>      <SI>         <SI>
+\& \ecP    16   <DLE>     <DLE>        <DLE>
+\& \ecQ    17   <DC1>     <DC1>        <DC1>
+\& \ecR    18   <DC2>     <DC2>        <DC2>
+\& \ecS    19   <DC3>     <DC3>        <DC3>
+\& \ecT    20   <DC4>     <OSC>        <OSC>
+\& \ecU    21   <NAK>     <NEL>        <LF>              **
+\& \ecV    22   <SYN>     <BS>         <BS>
+\& \ecW    23   <ETB>     <ESA>        <ESA>
+\& \ecX    24   <CAN>     <CAN>        <CAN>
+\& \ecY    25   <EOM>     <EOM>        <EOM>
+\& \ecZ    26   <SUB>     <PU2>        <PU2>
+\& \ec[    27   <ESC>     <SS3>        <SS3>
+\& \ec\eX   28   <FS>X     <FS>X        <FS>X
+\& \ec]    29   <GS>      <GS>         <GS>
+\& \ec^    30   <RS>      <RS>         <RS>
+\& \ec_    31   <US>      <US>         <US>
+\& \ec?    *    <DEL>     <APC>        <APC>
+.Ve
+.PP
+\&\f(CW\*(C`*\*(C'\fR Note: \f(CW\*(C`\ec?\*(C'\fR maps to ordinal 127 (\f(CW\*(C`DEL\*(C'\fR) on ASCII platforms, but
+since ordinal 127 is a not a control character on EBCDIC machines,
+\&\f(CW\*(C`\ec?\*(C'\fR instead maps on them to \f(CW\*(C`APC\*(C'\fR, which is 255 in 0037 and 1047,
+and 95 in POSIX-BC.
+.SH "FUNCTION DIFFERENCES"
+.IX Header "FUNCTION DIFFERENCES"
+.ie n .IP chr() 8
+.el .IP \f(CWchr()\fR 8
+.IX Item "chr()"
+\&\f(CWchr()\fR must be given an EBCDIC code number argument to yield a desired
+character return value on an EBCDIC platform.  For example:
+.Sp
+.Vb 1
+\&    $CAPITAL_LETTER_A = chr(193);
+.Ve
+.ie n .IP ord() 8
+.el .IP \f(CWord()\fR 8
+.IX Item "ord()"
+\&\f(CWord()\fR will return EBCDIC code number values on an EBCDIC platform.
+For example:
+.Sp
+.Vb 1
+\&    $the_number_193 = ord("A");
+.Ve
+.ie n .IP pack() 8
+.el .IP \f(CWpack()\fR 8
+.IX Item "pack()"
+The \f(CW"c"\fR and \f(CW"C"\fR templates for \f(CWpack()\fR are dependent upon character set
+encoding.  Examples of usage on EBCDIC include:
+.Sp
+.Vb 4
+\&    $foo = pack("CCCC",193,194,195,196);
+\&    # $foo eq "ABCD"
+\&    $foo = pack("C4",193,194,195,196);
+\&    # same thing
+\&
+\&    $foo = pack("ccxxcc",193,194,195,196);
+\&    # $foo eq "AB\e0\e0CD"
+.Ve
+.Sp
+The \f(CW"U"\fR template has been ported to mean "Unicode" on all platforms so
+that
+.Sp
+.Vb 1
+\&    pack("U", 65) eq \*(AqA\*(Aq
+.Ve
+.Sp
+is true on all platforms.  If you want native code points for the low
+256, use the \f(CW"W"\fR template.  This means that the equivalences
+.Sp
+.Vb 2
+\&    pack("W", ord($character)) eq $character
+\&    unpack("W", $character) == ord $character
+.Ve
+.Sp
+will hold.
+.ie n .IP print() 8
+.el .IP \f(CWprint()\fR 8
+.IX Item "print()"
+One must be careful with scalars and strings that are passed to
+print that contain ASCII encodings.  One common place
+for this to occur is in the output of the MIME type header for
+CGI script writing.  For example, many Perl programming guides
+recommend something similar to:
+.Sp
+.Vb 2
+\&    print "Content\-type:\ettext/html\e015\e012\e015\e012";
+\&    # this may be wrong on EBCDIC
+.Ve
+.Sp
+You can instead write
+.Sp
+.Vb 1
+\&    print "Content\-type:\ettext/html\er\en\er\en"; # OK for DGW et al
+.Ve
+.Sp
+and have it work portably.
+.Sp
+That is because the translation from EBCDIC to ASCII is done
+by the web server in this case.  Consult your web server's documentation for
+further details.
+.ie n .IP printf() 8
+.el .IP \f(CWprintf()\fR 8
+.IX Item "printf()"
+The formats that can convert characters to numbers and vice versa
+will be different from their ASCII counterparts when executed
+on an EBCDIC platform.  Examples include:
+.Sp
+.Vb 1
+\&    printf("%c%c%c",193,194,195);  # prints ABC
+.Ve
+.ie n .IP sort() 8
+.el .IP \f(CWsort()\fR 8
+.IX Item "sort()"
+EBCDIC sort results may differ from ASCII sort results especially for
+mixed case strings.  This is discussed in more detail below.
+.ie n .IP sprintf() 8
+.el .IP \f(CWsprintf()\fR 8
+.IX Item "sprintf()"
+See the discussion of \f(CW"printf()"\fR above.  An example of the use
+of sprintf would be:
+.Sp
+.Vb 1
+\&    $CAPITAL_LETTER_A = sprintf("%c",193);
+.Ve
+.ie n .IP unpack() 8
+.el .IP \f(CWunpack()\fR 8
+.IX Item "unpack()"
+See the discussion of \f(CW"pack()"\fR above.
+.PP
+Note that it is possible to write portable code for these by specifying
+things in Unicode numbers, and using a conversion function:
+.PP
+.Vb 3
+\&    printf("%c",utf8::unicode_to_native(65));  # prints A on all
+\&                                               # platforms
+\&    print utf8::native_to_unicode(ord("A"));   # Likewise, prints 65
+.Ve
+.PP
+See "Unicode and EBCDIC" in perluniintro and "CONVERSIONS"
+for other options.
+.SH "REGULAR EXPRESSION DIFFERENCES"
+.IX Header "REGULAR EXPRESSION DIFFERENCES"
+You can write your regular expressions just like someone on an ASCII
+platform would do.  But keep in mind that using octal or hex notation to
+specify a particular code point will give you the character that the
+EBCDIC code page natively maps to it.   (This is also true of all
+double-quoted strings.)  If you want to write portably, just use the
+\&\f(CW\*(C`\eN{U+...}\*(C'\fR notation everywhere where you would have used \f(CW\*(C`\ex{...}\*(C'\fR,
+and don't use octal notation at all.
+.PP
+Starting in Perl v5.22, this applies to ranges in bracketed character
+classes.  If you say, for example, \f(CW\*(C`qr/[\eN{U+20}\-\eN{U+7F}]/\*(C'\fR, it means
+the characters \f(CW\*(C`\eN{U+20}\*(C'\fR, \f(CW\*(C`\eN{U+21}\*(C'\fR, ..., \f(CW\*(C`\eN{U+7F}\*(C'\fR.  This range
+is all the printable characters that the ASCII character set contains.
+.PP
+Prior to v5.22, you couldn't specify any ranges portably, except
+(starting in Perl v5.5.3) all subsets of the \f(CW\*(C`[A\-Z]\*(C'\fR and \f(CW\*(C`[a\-z]\*(C'\fR
+ranges are specially coded to not pick up gap characters.  For example,
+characters such as "ô" (\f(CW\*(C`o WITH CIRCUMFLEX\*(C'\fR) that lie between
+"I" and "J" would not be matched by the regular expression range
+\&\f(CW\*(C`/[H\-K]/\*(C'\fR.  But if either of the range end points is explicitly numeric
+(and neither is specified by \f(CW\*(C`\eN{U+...}\*(C'\fR), the gap characters are
+matched:
+.PP
+.Vb 1
+\&    /[\ex89\-\ex91]/
+.Ve
+.PP
+will match \f(CW\*(C`\ex8e\*(C'\fR, even though \f(CW\*(C`\ex89\*(C'\fR is "i" and \f(CW\*(C`\ex91 \*(C'\fR is "j",
+and \f(CW\*(C`\ex8e\*(C'\fR is a gap character, from the alphabetic viewpoint.
+.PP
+Another construct to be wary of is the inappropriate use of hex (unless
+you use \f(CW\*(C`\eN{U+...}\*(C'\fR) or
+octal constants in regular expressions.  Consider the following
+set of subs:
+.PP
+.Vb 4
+\&    sub is_c0 {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\e000\-\e037]/;
+\&    }
+\&
+\&    sub is_print_ascii {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\e040\-\e176]/;
+\&    }
+\&
+\&    sub is_delete {
+\&        my $char = substr(shift,0,1);
+\&        $char eq "\e177";
+\&    }
+\&
+\&    sub is_c1 {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\e200\-\e237]/;
+\&    }
+\&
+\&    sub is_latin_1 {    # But not ASCII; not C1
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\e240\-\e377]/;
+\&    }
+.Ve
+.PP
+These are valid only on ASCII platforms.  Starting in Perl v5.22, simply
+changing the octal constants to equivalent \f(CW\*(C`\eN{U+...}\*(C'\fR values makes
+them portable:
+.PP
+.Vb 4
+\&    sub is_c0 {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\eN{U+00}\-\eN{U+1F}]/;
+\&    }
+\&
+\&    sub is_print_ascii {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\eN{U+20}\-\eN{U+7E}]/;
+\&    }
+\&
+\&    sub is_delete {
+\&        my $char = substr(shift,0,1);
+\&        $char eq "\eN{U+7F}";
+\&    }
+\&
+\&    sub is_c1 {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\eN{U+80}\-\eN{U+9F}]/;
+\&    }
+\&
+\&    sub is_latin_1 {    # But not ASCII; not C1
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\eN{U+A0}\-\eN{U+FF}]/;
+\&    }
+.Ve
+.PP
+And here are some alternative portable ways to write them:
+.PP
+.Vb 3
+\&    sub Is_c0 {
+\&        my $char = substr(shift,0,1);
+\&        return $char =~ /[[:cntrl:]]/a && ! Is_delete($char);
+\&
+\&        # Alternatively:
+\&        # return $char =~ /[[:cntrl:]]/
+\&        #        && $char =~ /[[:ascii:]]/
+\&        #        && ! Is_delete($char);
+\&    }
+\&
+\&    sub Is_print_ascii {
+\&        my $char = substr(shift,0,1);
+\&
+\&        return $char =~ /[[:print:]]/a;
+\&
+\&        # Alternatively:
+\&        # return $char =~ /[[:print:]]/ && $char =~ /[[:ascii:]]/;
+\&
+\&        # Or
+\&        # return $char
+\&        #      =~ /[ !"\e#\e$%&\*(Aq()*+,\e\-.\e/0\-9:;<=>?\e@A\-Z[\e\e\e]^_\`a\-z{|}~]/;
+\&    }
+\&
+\&    sub Is_delete {
+\&        my $char = substr(shift,0,1);
+\&        return utf8::native_to_unicode(ord $char) == 0x7F;
+\&    }
+\&
+\&    sub Is_c1 {
+\&        use feature \*(Aqunicode_strings\*(Aq;
+\&        my $char = substr(shift,0,1);
+\&        return $char =~ /[[:cntrl:]]/ && $char !~ /[[:ascii:]]/;
+\&    }
+\&
+\&    sub Is_latin_1 {    # But not ASCII; not C1
+\&        use feature \*(Aqunicode_strings\*(Aq;
+\&        my $char = substr(shift,0,1);
+\&        return ord($char) < 256
+\&               && $char !~ /[[:ascii:]]/
+\&               && $char !~ /[[:cntrl:]]/;
+\&    }
+.Ve
+.PP
+Another way to write \f(CWIs_latin_1()\fR would be
+to use the characters in the range explicitly:
+.PP
+.Vb 5
+\&    sub Is_latin_1 {
+\&        my $char = substr(shift,0,1);
+\&        $char =~ /[\ ¡¢£¤¥¦§¨©ª«¬\%®¯°±²³´µ¶·¸¹º»¼½¾¿À�ÂÃÄÅÆÇÈÉÊËÌ�Î�]
+\&                  [�ÑÒÓÔÕÖ×ØÙÚÛÜ�Þßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ]/x;
+\&    }
+.Ve
+.PP
+Although that form may run into trouble in network transit (due to the
+presence of 8 bit characters) or on non ISO-Latin character sets.  But
+it does allow \f(CW\*(C`Is_c1\*(C'\fR to be rewritten so it works on Perls that don't
+have \f(CW\*(Aqunicode_strings\*(Aq\fR (earlier than v5.14):
+.PP
+.Vb 6
+\&    sub Is_latin_1 {    # But not ASCII; not C1
+\&        my $char = substr(shift,0,1);
+\&        return ord($char) < 256
+\&               && $char !~ /[[:ascii:]]/
+\&               && ! Is_latin1($char);
+\&    }
+.Ve
+.SH SOCKETS
+.IX Header "SOCKETS"
+Most socket programming assumes ASCII character encodings in network
+byte order.  Exceptions can include CGI script writing under a
+host web server where the server may take care of translation for you.
+Most host web servers convert EBCDIC data to ISO\-8859\-1 or Unicode on
+output.
+.SH SORTING
+.IX Header "SORTING"
+One big difference between ASCII-based character sets and EBCDIC ones
+are the relative positions of the characters when sorted in native
+order.  Of most concern are the upper\- and lowercase letters, the
+digits, and the underscore (\f(CW"_"\fR).  On ASCII platforms the native sort
+order has the digits come before the uppercase letters which come before
+the underscore which comes before the lowercase letters.  On EBCDIC, the
+underscore comes first, then the lowercase letters, then the uppercase
+ones, and the digits last.  If sorted on an ASCII-based platform, the
+two-letter abbreviation for a physician comes before the two letter
+abbreviation for drive; that is:
+.PP
+.Vb 2
+\& @sorted = sort(qw(Dr. dr.));  # @sorted holds (\*(AqDr.\*(Aq,\*(Aqdr.\*(Aq) on ASCII,
+\&                                  # but (\*(Aqdr.\*(Aq,\*(AqDr.\*(Aq) on EBCDIC
+.Ve
+.PP
+The property of lowercase before uppercase letters in EBCDIC is
+even carried to the Latin 1 EBCDIC pages such as 0037 and 1047.
+An example would be that "Ë" (\f(CW\*(C`E WITH DIAERESIS\*(C'\fR, 203) comes
+before "ë" (\f(CW\*(C`e WITH DIAERESIS\*(C'\fR, 235) on an ASCII platform, but
+the latter (83) comes before the former (115) on an EBCDIC platform.
+(Astute readers will note that the uppercase version of "ß"
+\&\f(CW\*(C`SMALL LETTER SHARP S\*(C'\fR is simply "SS" and that the upper case versions
+of "ÿ" (small \f(CW\*(C`y WITH DIAERESIS\*(C'\fR) and "µ" (\f(CW\*(C`MICRO SIGN\*(C'\fR)
+are not in the 0..255 range but are in Unicode, in a Unicode enabled
+Perl).
+.PP
+The sort order will cause differences between results obtained on
+ASCII platforms versus EBCDIC platforms.  What follows are some suggestions
+on how to deal with these differences.
+.SS "Ignore ASCII vs. EBCDIC sort differences."
+.IX Subsection "Ignore ASCII vs. EBCDIC sort differences."
+This is the least computationally expensive strategy.  It may require
+some user education.
+.SS "Use a sort helper function"
+.IX Subsection "Use a sort helper function"
+This is completely general, but the most computationally expensive
+strategy.  Choose one or the other character set and transform to that
+for every sort comparison.  Here's a complete example that transforms
+to ASCII sort order:
+.PP
+.Vb 2
+\& sub native_to_uni($) {
+\&    my $string = shift;
+\&
+\&    # Saves time on an ASCII platform
+\&    return $string if ord \*(AqA\*(Aq ==  65;
+\&
+\&    my $output = "";
+\&    for my $i (0 .. length($string) \- 1) {
+\&        $output
+\&           .= chr(utf8::native_to_unicode(ord(substr($string, $i, 1))));
+\&    }
+\&
+\&    # Preserve utf8ness of input onto the output, even if it didn\*(Aqt need
+\&    # to be utf8
+\&    utf8::upgrade($output) if utf8::is_utf8($string);
+\&
+\&    return $output;
+\& }
+\&
+\& sub ascii_order {   # Sort helper
+\&    return native_to_uni($a) cmp native_to_uni($b);
+\& }
+\&
+\& sort ascii_order @list;
+.Ve
+.SS "MONO CASE then sort data (for non-digits, non-underscore)"
+.IX Subsection "MONO CASE then sort data (for non-digits, non-underscore)"
+If you don't care about where digits and underscore sort to, you can do
+something like this
+.PP
+.Vb 3
+\& sub case_insensitive_order {   # Sort helper
+\&    return lc($a) cmp lc($b)
+\& }
+\&
+\& sort case_insensitive_order @list;
+.Ve
+.PP
+If performance is an issue, and you don't care if the output is in the
+same case as the input, Use \f(CW\*(C`tr///\*(C'\fR to transform to the case most
+employed within the data.  If the data are primarily UPPERCASE
+non\-Latin1, then apply \f(CW\*(C`tr/[a\-z]/[A\-Z]/\*(C'\fR, and then \f(CWsort()\fR.  If the
+data are primarily lowercase non Latin1 then apply \f(CW\*(C`tr/[A\-Z]/[a\-z]/\*(C'\fR
+before sorting.  If the data are primarily UPPERCASE and include Latin\-1
+characters then apply:
+.PP
+.Vb 3
+\&   tr/[a\-z]/[A\-Z]/;
+\&   tr/[àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ]/[À�ÂÃÄÅÆÇÈÉÊËÌ�Î��ÑÒÓÔÕÖØÙÚÛÜ�Þ/;
+\&   s/ß/SS/g;
+.Ve
+.PP
+then \f(CWsort()\fR.  If you have a choice, it's better to lowercase things
+to avoid the problems of the two Latin\-1 characters whose uppercase is
+outside Latin\-1: "ÿ" (small \f(CW\*(C`y WITH DIAERESIS\*(C'\fR) and "µ"
+(\f(CW\*(C`MICRO SIGN\*(C'\fR).  If you do need to upppercase, you can; with a
+Unicode-enabled Perl, do:
+.PP
+.Vb 2
+\&    tr/ÿ/\ex{178}/;
+\&    tr/µ/\ex{39C}/;
+.Ve
+.SS "Perform sorting on one type of platform only."
+.IX Subsection "Perform sorting on one type of platform only."
+This strategy can employ a network connection.  As such
+it would be computationally expensive.
+.SH "TRANSFORMATION FORMATS"
+.IX Header "TRANSFORMATION FORMATS"
+There are a variety of ways of transforming data with an intra character set
+mapping that serve a variety of purposes.  Sorting was discussed in the
+previous section and a few of the other more popular mapping techniques are
+discussed next.
+.SS "URL decoding and encoding"
+.IX Subsection "URL decoding and encoding"
+Note that some URLs have hexadecimal ASCII code points in them in an
+attempt to overcome character or protocol limitation issues.  For example
+the tilde character is not on every keyboard hence a URL of the form:
+.PP
+.Vb 1
+\&    http://www.pvhp.com/~pvhp/
+.Ve
+.PP
+may also be expressed as either of:
+.PP
+.Vb 1
+\&    http://www.pvhp.com/%7Epvhp/
+\&
+\&    http://www.pvhp.com/%7epvhp/
+.Ve
+.PP
+where 7E is the hexadecimal ASCII code point for "~".  Here is an example
+of decoding such a URL in any EBCDIC code page:
+.PP
+.Vb 3
+\&    $url = \*(Aqhttp://www.pvhp.com/%7Epvhp/\*(Aq;
+\&    $url =~ s/%([0\-9a\-fA\-F]{2})/
+\&              pack("c",utf8::unicode_to_native(hex($1)))/xge;
+.Ve
+.PP
+Conversely, here is a partial solution for the task of encoding such
+a URL in any EBCDIC code page:
+.PP
+.Vb 5
+\&    $url = \*(Aqhttp://www.pvhp.com/~pvhp/\*(Aq;
+\&    # The following regular expression does not address the
+\&    # mappings for: (\*(Aq.\*(Aq => \*(Aq%2E\*(Aq, \*(Aq/\*(Aq => \*(Aq%2F\*(Aq, \*(Aq:\*(Aq => \*(Aq%3A\*(Aq)
+\&    $url =~ s/([\et "#%&\e(\e),;<=>\e?\e@\e[\e\e\e]^\`{|}~])/
+\&               sprintf("%%%02X",utf8::native_to_unicode(ord($1)))/xge;
+.Ve
+.PP
+where a more complete solution would split the URL into components
+and apply a full s/// substitution only to the appropriate parts.
+.SS "uu encoding and decoding"
+.IX Subsection "uu encoding and decoding"
+The \f(CW\*(C`u\*(C'\fR template to \f(CWpack()\fR or \f(CWunpack()\fR will render EBCDIC data in
+EBCDIC characters equivalent to their ASCII counterparts.  For example,
+the following will print "Yes indeed\en" on either an ASCII or EBCDIC
+computer:
+.PP
+.Vb 10
+\&    $all_byte_chrs = \*(Aq\*(Aq;
+\&    for (0..255) { $all_byte_chrs .= chr($_); }
+\&    $uuencode_byte_chrs = pack(\*(Aqu\*(Aq, $all_byte_chrs);
+\&    ($uu = <<\*(AqENDOFHEREDOC\*(Aq) =~ s/^\es*//gm;
+\&    M\`\`$"\`P0%!@<("0H+#\`T.#Q\`1$A,4%187&!D:&QP=\*(AqA\e@(2(C)"4F)R@I*BLL
+\&    M+2XO,#$R,S0U\-C<X.3H[/#T^/T!!0D\-$149\*(Aq2$E*2TQ\-3D]045)35%565UA9
+\&    M6EM<75Y?8&%B8V1E9F=H:6IK;&UN;W!Q<G\-T=79W>\*(AqEZ>WQ]?G^\`@8*#A(6&
+\&    MAXB)BHN,C8Z/D)&2DY25EI>8F9J;G)V>GZ"AHJ.DI::GJ*FJJZRMKJ^PL;*S
+\&    MM+6VM[BYNKN\eO;Z_P,\*(Aq"P\e3%QL?(R<K+S,W.S]#1TM/4U=;7V\-G:V]S=WM_@
+\&    ?X>+CY.7FY^CIZNOL[>[O\e/\*(AqR\e_3U]O?X^?K[_/W^_P\`\`
+\&    ENDOFHEREDOC
+\&    if ($uuencode_byte_chrs eq $uu) {
+\&        print "Yes ";
+\&    }
+\&    $uudecode_byte_chrs = unpack(\*(Aqu\*(Aq, $uuencode_byte_chrs);
+\&    if ($uudecode_byte_chrs eq $all_byte_chrs) {
+\&        print "indeed\en";
+\&    }
+.Ve
+.PP
+Here is a very spartan uudecoder that will work on EBCDIC:
+.PP
+.Vb 10
+\&    #!/usr/local/bin/perl
+\&    $_ = <> until ($mode,$file) = /^begin\es*(\ed*)\es*(\eS*)/;
+\&    open(OUT, "> $file") if $file ne "";
+\&    while(<>) {
+\&        last if /^end/;
+\&        next if /[a\-z]/;
+\&        next unless int((((utf8::native_to_unicode(ord()) \- 32 ) & 077)
+\&                                                               + 2) / 3)
+\&                    == int(length() / 4);
+\&        print OUT unpack("u", $_);
+\&    }
+\&    close(OUT);
+\&    chmod oct($mode), $file;
+.Ve
+.SS "Quoted-Printable encoding and decoding"
+.IX Subsection "Quoted-Printable encoding and decoding"
+On ASCII-encoded platforms it is possible to strip characters outside of
+the printable set using:
+.PP
+.Vb 3
+\&    # This QP encoder works on ASCII only
+\&    $qp_string =~ s/([=\ex00\-\ex1F\ex80\-\exFF])/
+\&                    sprintf("=%02X",ord($1))/xge;
+.Ve
+.PP
+Starting in Perl v5.22, this is trivially changeable to work portably on
+both ASCII and EBCDIC platforms.
+.PP
+.Vb 3
+\&    # This QP encoder works on both ASCII and EBCDIC
+\&    $qp_string =~ s/([=\eN{U+00}\-\eN{U+1F}\eN{U+80}\-\eN{U+FF}])/
+\&                    sprintf("=%02X",ord($1))/xge;
+.Ve
+.PP
+For earlier Perls, a QP encoder that works on both ASCII and EBCDIC
+platforms would look somewhat like the following:
+.PP
+.Vb 4
+\&    $delete = utf8::unicode_to_native(ord("\ex7F"));
+\&    $qp_string =~
+\&      s/([^[:print:]$delete])/
+\&         sprintf("=%02X",utf8::native_to_unicode(ord($1)))/xage;
+.Ve
+.PP
+(although in production code the substitutions might be done
+in the EBCDIC branch with the function call and separately in the
+ASCII branch without the expense of the identity map; in Perl v5.22, the
+identity map is optimized out so there is no expense, but the
+alternative above is simpler and is also available in v5.22).
+.PP
+Such QP strings can be decoded with:
+.PP
+.Vb 3
+\&    # This QP decoder is limited to ASCII only
+\&    $string =~ s/=([[:xdigit:][[:xdigit:])/chr hex $1/ge;
+\&    $string =~ s/=[\en\er]+$//;
+.Ve
+.PP
+Whereas a QP decoder that works on both ASCII and EBCDIC platforms
+would look somewhat like the following:
+.PP
+.Vb 3
+\&    $string =~ s/=([[:xdigit:][:xdigit:]])/
+\&                                chr utf8::native_to_unicode(hex $1)/xge;
+\&    $string =~ s/=[\en\er]+$//;
+.Ve
+.SS "Caesarean ciphers"
+.IX Subsection "Caesarean ciphers"
+The practice of shifting an alphabet one or more characters for encipherment
+dates back thousands of years and was explicitly detailed by Gaius Julius
+Caesar in his \fBGallic Wars\fR text.  A single alphabet shift is sometimes
+referred to as a rotation and the shift amount is given as a number \f(CW$n\fR after
+the string 'rot' or "rot$n".  Rot0 and rot26 would designate identity maps
+on the 26\-letter English version of the Latin alphabet.  Rot13 has the
+interesting property that alternate subsequent invocations are identity maps
+(thus rot13 is its own non-trivial inverse in the group of 26 alphabet
+rotations).  Hence the following is a rot13 encoder and decoder that will
+work on ASCII and EBCDIC platforms:
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl
+\&
+\&    while(<>){
+\&        tr/n\-za\-mN\-ZA\-M/a\-zA\-Z/;
+\&        print;
+\&    }
+.Ve
+.PP
+In one-liner form:
+.PP
+.Vb 1
+\&    perl \-ne \*(Aqtr/n\-za\-mN\-ZA\-M/a\-zA\-Z/;print\*(Aq
+.Ve
+.SH "Hashing order and checksums"
+.IX Header "Hashing order and checksums"
+Perl deliberately randomizes hash order for security purposes on both
+ASCII and EBCDIC platforms.
+.PP
+EBCDIC checksums will differ for the same file translated into ASCII
+and vice versa.
+.SH "I18N AND L10N"
+.IX Header "I18N AND L10N"
+Internationalization (I18N) and localization (L10N) are supported at least
+in principle even on EBCDIC platforms.  The details are system-dependent
+and discussed under the "OS ISSUES" section below.
+.SH "MULTI-OCTET CHARACTER SETS"
+.IX Header "MULTI-OCTET CHARACTER SETS"
+Perl works with UTF-EBCDIC, a multi-byte encoding.  In Perls earlier
+than v5.22, there may be various bugs in this regard.
+.PP
+Legacy multi byte EBCDIC code pages XXX.
+.SH "OS ISSUES"
+.IX Header "OS ISSUES"
+There may be a few system-dependent issues
+of concern to EBCDIC Perl programmers.
+.SS OS/400
+.IX Subsection "OS/400"
+.IP PASE 8
+.IX Item "PASE"
+The PASE environment is a runtime environment for OS/400 that can run
+executables built for PowerPC AIX in OS/400; see perlos400.  PASE
+is ASCII-based, not EBCDIC-based as the ILE.
+.IP "IFS access" 8
+.IX Item "IFS access"
+XXX.
+.SS "OS/390, z/OS"
+.IX Subsection "OS/390, z/OS"
+Perl runs under Unix Systems Services or USS.
+.ie n .IP """sigaction""" 8
+.el .IP \f(CWsigaction\fR 8
+.IX Item "sigaction"
+\&\f(CW\*(C`SA_SIGINFO\*(C'\fR can have segmentation faults.
+.ie n .IP """chcp""" 8
+.el .IP \f(CWchcp\fR 8
+.IX Item "chcp"
+\&\fBchcp\fR is supported as a shell utility for displaying and changing
+one's code page.  See also \fBchcp\fR\|(1).
+.IP "dataset access" 8
+.IX Item "dataset access"
+For sequential data set access try:
+.Sp
+.Vb 1
+\&    my @ds_records = \`cat //DSNAME\`;
+.Ve
+.Sp
+or:
+.Sp
+.Vb 1
+\&    my @ds_records = \`cat //\*(AqHLQ.DSNAME\*(Aq\`;
+.Ve
+.Sp
+See also the OS390::Stdio module on CPAN.
+.ie n .IP """iconv""" 8
+.el .IP \f(CWiconv\fR 8
+.IX Item "iconv"
+\&\fBiconv\fR is supported as both a shell utility and a C RTL routine.
+See also the \fBiconv\fR\|(1) and \fBiconv\fR\|(3) manual pages.
+.IP locales 8
+.IX Item "locales"
+Locales are supported.  There may be glitches when a locale is another
+EBCDIC code page which has some of the
+code-page variant characters in other
+positions.
+.Sp
+There aren't currently any real UTF\-8 locales, even though some locale
+names contain the string "UTF\-8".
+.Sp
+See perllocale for information on locales.  The L10N files
+are in \fI/usr/nls/locale\fR.  \f(CW$Config{d_setlocale}\fR is \f(CW\*(Aqdefine\*(Aq\fR on
+OS/390 or z/OS.
+.SS POSIX-BC?
+.IX Subsection "POSIX-BC?"
+XXX.
+.SH BUGS
+.IX Header "BUGS"
+.IP \(bu 4
+Not all shells will allow multiple \f(CW\*(C`\-e\*(C'\fR string arguments to perl to
+be concatenated together properly as recipes in this document
+0, 2, 4, 5, and 6 might
+seem to imply.
+.IP \(bu 4
+There are a significant number of test failures in the CPAN modules
+shipped with Perl v5.22 and 5.24.  These are only in modules not primarily
+maintained by Perl 5 porters.  Some of these are failures in the tests
+only: they don't realize that it is proper to get different results on
+EBCDIC platforms.  And some of the failures are real bugs.  If you
+compile and do a \f(CW\*(C`make test\*(C'\fR on Perl, all tests on the \f(CW\*(C`/cpan\*(C'\fR
+directory are skipped.
+.Sp
+Encode partially works.
+.IP \(bu 4
+In earlier Perl versions, when byte and character data were
+concatenated, the new string was sometimes created by
+decoding the byte strings as \fIISO 8859\-1 (Latin\-1)\fR, even if the
+old Unicode string used EBCDIC.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perllocale, perlfunc, perlunicode, utf8.
+.SH REFERENCES
+.IX Header "REFERENCES"
+<http://std.dkuug.dk/i18n/charmaps>
+.PP
+<https://www.unicode.org/>
+.PP
+<https://www.unicode.org/reports/tr16/>
+.PP
+<https://www.sr\-ix.com/Archive/CharCodeHist/index.html>
+\&\fBASCII: American Standard Code for Information Infiltration\fR Tom Jennings,
+September 1999.
+.PP
+\&\fBThe Unicode Standard, Version 3.0\fR The Unicode Consortium, Lisa Moore ed.,
+ISBN 0\-201\-61633\-5, Addison Wesley Developers Press, February 2000.
+.PP
+\&\fBCDRA: IBM \- Character Data Representation Architecture \-
+Reference and Registry\fR, IBM SC09\-2190\-00, December 1996.
+.PP
+"Demystifying Character Sets", Andrea Vine, Multilingual Computing
+& Technology, \fB#26 Vol. 10 Issue 4\fR, August/September 1999;
+ISSN 1523\-0309; Multilingual Computing Inc. Sandpoint ID, USA.
+.PP
+\&\fBCodes, Ciphers, and Other Cryptic and Clandestine Communication\fR
+Fred B. Wrixon, ISBN 1\-57912\-040\-7, Black Dog & Leventhal Publishers,
+1998.
+.PP
+<http://www.bobbemer.com/P\-BIT.HTM>
+\&\fBIBM \- EBCDIC and the P\-bit; The biggest Computer Goof Ever\fR Robert Bemer.
+.SH HISTORY
+.IX Header "HISTORY"
+15 April 2001: added UTF\-8 and UTF-EBCDIC to main table, pvhp.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Peter Prymmer pvhp@best.com wrote this in 1999 and 2000
+with CCSID 0819 and 0037 help from Chris Leach and
+André Pirard A.Pirard@ulg.ac.be as well as POSIX-BC
+help from Thomas Dorner Thomas.Dorner@start.de.
+Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and
+Joe Smith.  Trademarks, registered trademarks, service marks and
+registered service marks used in this document are the property of
+their respective owners.
+.PP
+Now maintained by Perl5 Porters.
diff --git a/upstream/mageia-cauldron/man1/perlembed.1 b/upstream/mageia-cauldron/man1/perlembed.1
new file mode 100644
index 00000000..b8de30ac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlembed.1
@@ -0,0 +1,1246 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLEMBED 1"
+.TH PERLEMBED 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlembed \- how to embed perl in your C program
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS PREAMBLE
+.IX Subsection "PREAMBLE"
+Do you want to:
+.IP "\fBUse C from Perl?\fR" 5
+.IX Item "Use C from Perl?"
+Read perlxstut, perlxs, h2xs, perlguts, and perlapi.
+.IP "\fBUse a Unix program from Perl?\fR" 5
+.IX Item "Use a Unix program from Perl?"
+Read about back-quotes and about \f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR in perlfunc.
+.IP "\fBUse Perl from Perl?\fR" 5
+.IX Item "Use Perl from Perl?"
+Read about "do" in perlfunc and "eval" in perlfunc and "require" in perlfunc
+and "use" in perlfunc.
+.IP "\fBUse C from C?\fR" 5
+.IX Item "Use C from C?"
+Rethink your design.
+.IP "\fBUse Perl from C?\fR" 5
+.IX Item "Use Perl from C?"
+Read on...
+.SS ROADMAP
+.IX Subsection "ROADMAP"
+.IP \(bu 5
+Compiling your C program
+.IP \(bu 5
+Adding a Perl interpreter to your C program
+.IP \(bu 5
+Calling a Perl subroutine from your C program
+.IP \(bu 5
+Evaluating a Perl statement from your C program
+.IP \(bu 5
+Performing Perl pattern matches and substitutions from your C program
+.IP \(bu 5
+Fiddling with the Perl stack from your C program
+.IP \(bu 5
+Maintaining a persistent interpreter
+.IP \(bu 5
+Maintaining multiple interpreter instances
+.IP \(bu 5
+Using Perl modules, which themselves use C libraries, from your C program
+.IP \(bu 5
+Embedding Perl under Win32
+.SS "Compiling your C program"
+.IX Subsection "Compiling your C program"
+If you have trouble compiling the scripts in this documentation,
+you're not alone.  The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
+THE SAME WAY THAT YOUR PERL WAS COMPILED.  (Sorry for yelling.)
+.PP
+Also, every C program that uses Perl must link in the \fIperl library\fR.
+What's that, you ask?  Perl is itself written in C; the perl library
+is the collection of compiled C programs that were used to create your
+perl executable (\fI/usr/bin/perl\fR or equivalent).  (Corollary: you
+can't use Perl from your C program unless Perl has been compiled on
+your machine, or installed properly\-\-that's why you shouldn't blithely
+copy Perl executables from machine to machine without also copying the
+\&\fIlib\fR directory.)
+.PP
+When you use Perl from C, your C program will\-\-usually\-\-allocate,
+"run", and deallocate a \fIPerlInterpreter\fR object, which is defined by
+the perl library.
+.PP
+If your copy of Perl is recent enough to contain this documentation
+(version 5.002 or later), then the perl library (and \fIEXTERN.h\fR and
+\&\fIperl.h\fR, which you'll also need) will reside in a directory
+that looks like this:
+.PP
+.Vb 1
+\&    /usr/local/lib/perl5/your_architecture_here/CORE
+.Ve
+.PP
+or perhaps just
+.PP
+.Vb 1
+\&    /usr/local/lib/perl5/CORE
+.Ve
+.PP
+or maybe something like
+.PP
+.Vb 1
+\&    /usr/opt/perl5/CORE
+.Ve
+.PP
+Execute this statement for a hint about where to find CORE:
+.PP
+.Vb 1
+\&    perl \-MConfig \-e \*(Aqprint $Config{archlib}\*(Aq
+.Ve
+.PP
+Here's how you'd compile the example in the next section,
+"Adding a Perl interpreter to your C program", on my Linux box:
+.PP
+.Vb 4
+\&    % gcc \-O2 \-Dbool=char \-DHAS_BOOL \-I/usr/local/include
+\&    \-I/usr/local/lib/perl5/i586\-linux/5.003/CORE
+\&    \-L/usr/local/lib/perl5/i586\-linux/5.003/CORE
+\&    \-o interp interp.c \-lperl \-lm
+.Ve
+.PP
+(That's all one line.)  On my DEC Alpha running old 5.003_05, the
+incantation is a bit different:
+.PP
+.Vb 4
+\&    % cc \-O2 \-Olimit 2900 \-I/usr/local/include
+\&    \-I/usr/local/lib/perl5/alpha\-dec_osf/5.00305/CORE
+\&    \-L/usr/local/lib/perl5/alpha\-dec_osf/5.00305/CORE \-L/usr/local/lib
+\&    \-D_\|_LANGUAGE_C_\|_ \-D_NO_PROTO \-o interp interp.c \-lperl \-lm
+.Ve
+.PP
+How can you figure out what to add?  Assuming your Perl is post\-5.001,
+execute a \f(CW\*(C`perl \-V\*(C'\fR command and pay special attention to the "cc" and
+"ccflags" information.
+.PP
+You'll have to choose the appropriate compiler (\fIcc\fR, \fIgcc\fR, et al.) for
+your machine: \f(CW\*(C`perl \-MConfig \-e \*(Aqprint $Config{cc}\*(Aq\*(C'\fR will tell you what
+to use.
+.PP
+You'll also have to choose the appropriate library directory
+(\fI/usr/local/lib/...\fR) for your machine.  If your compiler complains
+that certain functions are undefined, or that it can't locate
+\&\fI\-lperl\fR, then you need to change the path following the \f(CW\*(C`\-L\*(C'\fR.  If it
+complains that it can't find \fIEXTERN.h\fR and \fIperl.h\fR, you need to
+change the path following the \f(CW\*(C`\-I\*(C'\fR.
+.PP
+You may have to add extra libraries as well.  Which ones?
+Perhaps those printed by
+.PP
+.Vb 1
+\&   perl \-MConfig \-e \*(Aqprint $Config{libs}\*(Aq
+.Ve
+.PP
+Provided your perl binary was properly configured and installed the
+\&\fBExtUtils::Embed\fR module will determine all of this information for
+you:
+.PP
+.Vb 1
+\&   % cc \-o interp interp.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+.Ve
+.PP
+If the \fBExtUtils::Embed\fR module isn't part of your Perl distribution,
+you can retrieve it from
+<https://metacpan.org/pod/ExtUtils::Embed>
+(If this documentation came from your Perl distribution, then you're
+running 5.004 or better and you already have it.)
+.PP
+The \fBExtUtils::Embed\fR kit on CPAN also contains all source code for
+the examples in this document, tests, additional examples and other
+information you may find useful.
+.SS "Adding a Perl interpreter to your C program"
+.IX Subsection "Adding a Perl interpreter to your C program"
+In a sense, perl (the C program) is a good example of embedding Perl
+(the language), so I'll demonstrate embedding with \fIminiperlmain.c\fR,
+included in the source distribution.  Here's a bastardized, non-portable
+version of \fIminiperlmain.c\fR containing the essentials of embedding:
+.PP
+.Vb 2
+\& #include <EXTERN.h>               /* from the Perl distribution     */
+\& #include <perl.h>                 /* from the Perl distribution     */
+\&
+\& static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
+\&
+\& int main(int argc, char **argv, char **env)
+\& {
+\&        PERL_SYS_INIT3(&argc,&argv,&env);
+\&        my_perl = perl_alloc();
+\&        perl_construct(my_perl);
+\&        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&        perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
+\&        perl_run(my_perl);
+\&        perl_destruct(my_perl);
+\&        perl_free(my_perl);
+\&        PERL_SYS_TERM();
+\&        exit(EXIT_SUCCESS);
+\& }
+.Ve
+.PP
+Notice that we don't use the \f(CW\*(C`env\*(C'\fR pointer.  Normally handed to
+\&\f(CW\*(C`perl_parse\*(C'\fR as its final argument, \f(CW\*(C`env\*(C'\fR here is replaced by
+\&\f(CW\*(C`NULL\*(C'\fR, which means that the current environment will be used.
+.PP
+The macros \fBPERL_SYS_INIT3()\fR and \fBPERL_SYS_TERM()\fR provide system-specific
+tune up of the C runtime environment necessary to run Perl interpreters;
+they should only be called once regardless of how many interpreters you
+create or destroy. Call \fBPERL_SYS_INIT3()\fR before you create your first
+interpreter, and \fBPERL_SYS_TERM()\fR after you free your last interpreter.
+.PP
+Since \fBPERL_SYS_INIT3()\fR may change \f(CW\*(C`env\*(C'\fR, it may be more appropriate to
+provide \f(CW\*(C`env\*(C'\fR as an argument to \fBperl_parse()\fR.
+.PP
+Also notice that no matter what arguments you pass to \fBperl_parse()\fR,
+\&\fBPERL_SYS_INIT3()\fR must be invoked on the C \fBmain()\fR argc, argv and env and
+only once.
+.PP
+Mind that argv[argc] must be NULL, same as those passed to a main
+function in C.
+.PP
+Now compile this program (I'll call it \fIinterp.c\fR) into an executable:
+.PP
+.Vb 1
+\&    % cc \-o interp interp.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+.Ve
+.PP
+After a successful compilation, you'll be able to use \fIinterp\fR just
+like perl itself:
+.PP
+.Vb 6
+\&    % interp
+\&    print "Pretty Good Perl \en";
+\&    print "10890 \- 9801 is ", 10890 \- 9801;
+\&    <CTRL\-D>
+\&    Pretty Good Perl
+\&    10890 \- 9801 is 1089
+.Ve
+.PP
+or
+.PP
+.Vb 2
+\&    % interp \-e \*(Aqprintf("%x", 3735928559)\*(Aq
+\&    deadbeef
+.Ve
+.PP
+You can also read and execute Perl statements from a file while in the
+midst of your C program, by placing the filename in \fIargv[1]\fR before
+calling \fIperl_run\fR.
+.SS "Calling a Perl subroutine from your C program"
+.IX Subsection "Calling a Perl subroutine from your C program"
+To call individual Perl subroutines, you can use any of the \fBcall_*\fR
+functions documented in perlcall.
+In this example we'll use \f(CW\*(C`call_argv\*(C'\fR.
+.PP
+That's shown below, in a program I'll call \fIshowtime.c\fR.
+.PP
+.Vb 2
+\&    #include <EXTERN.h>
+\&    #include <perl.h>
+\&
+\&    static PerlInterpreter *my_perl;
+\&
+\&    int main(int argc, char **argv, char **env)
+\&    {
+\&        char *args[] = { NULL };
+\&        PERL_SYS_INIT3(&argc,&argv,&env);
+\&        my_perl = perl_alloc();
+\&        perl_construct(my_perl);
+\&
+\&        perl_parse(my_perl, NULL, argc, argv, NULL);
+\&        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&
+\&        /*** skipping perl_run() ***/
+\&
+\&        call_argv("showtime", G_DISCARD | G_NOARGS, args);
+\&
+\&        perl_destruct(my_perl);
+\&        perl_free(my_perl);
+\&        PERL_SYS_TERM();
+\&        exit(EXIT_SUCCESS);
+\&    }
+.Ve
+.PP
+where \fIshowtime\fR is a Perl subroutine that takes no arguments (that's the
+\&\fIG_NOARGS\fR) and for which I'll ignore the return value (that's the
+\&\fIG_DISCARD\fR).  Those flags, and others, are discussed in perlcall.
+.PP
+I'll define the \fIshowtime\fR subroutine in a file called \fIshowtime.pl\fR:
+.PP
+.Vb 1
+\& print "I shan\*(Aqt be printed.";
+\&
+\& sub showtime {
+\&     print time;
+\& }
+.Ve
+.PP
+Simple enough. Now compile and run:
+.PP
+.Vb 4
+\& % cc \-o showtime showtime.c \e
+\&     \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+\& % showtime showtime.pl
+\& 818284590
+.Ve
+.PP
+yielding the number of seconds that elapsed between January 1, 1970
+(the beginning of the Unix epoch), and the moment I began writing this
+sentence.
+.PP
+In this particular case we don't have to call \fIperl_run\fR, as we set
+the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
+perl_destruct.
+.PP
+If you want to pass arguments to the Perl subroutine, you can add
+strings to the \f(CW\*(C`NULL\*(C'\fR\-terminated \f(CW\*(C`args\*(C'\fR list passed to
+\&\fIcall_argv\fR.  For other data types, or to examine return values,
+you'll need to manipulate the Perl stack.  That's demonstrated in
+"Fiddling with the Perl stack from your C program".
+.SS "Evaluating a Perl statement from your C program"
+.IX Subsection "Evaluating a Perl statement from your C program"
+Perl provides two API functions to evaluate pieces of Perl code.
+These are "eval_sv" in perlapi and "eval_pv" in perlapi.
+.PP
+Arguably, these are the only routines you'll ever need to execute
+snippets of Perl code from within your C program.  Your code can be as
+long as you wish; it can contain multiple statements; it can employ
+"use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to
+include external Perl files.
+.PP
+\&\fIeval_pv\fR lets us evaluate individual Perl strings, and then
+extract variables for coercion into C types.  The following program,
+\&\fIstring.c\fR, executes three Perl strings, extracting an \f(CW\*(C`int\*(C'\fR from
+the first, a \f(CW\*(C`float\*(C'\fR from the second, and a \f(CW\*(C`char *\*(C'\fR from the third.
+.PP
+.Vb 2
+\& #include <EXTERN.h>
+\& #include <perl.h>
+\&
+\& static PerlInterpreter *my_perl;
+\&
+\& main (int argc, char **argv, char **env)
+\& {
+\&     char *embedding[] = { "", "\-e", "0", NULL };
+\&
+\&     PERL_SYS_INIT3(&argc,&argv,&env);
+\&     my_perl = perl_alloc();
+\&     perl_construct( my_perl );
+\&
+\&     perl_parse(my_perl, NULL, 3, embedding, NULL);
+\&     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&     perl_run(my_perl);
+\&
+\&     /** Treat $a as an integer **/
+\&     eval_pv("$a = 3; $a **= 2", TRUE);
+\&     printf("a = %d\en", SvIV(get_sv("a", 0)));
+\&
+\&     /** Treat $a as a float **/
+\&     eval_pv("$a = 3.14; $a **= 2", TRUE);
+\&     printf("a = %f\en", SvNV(get_sv("a", 0)));
+\&
+\&     /** Treat $a as a string **/
+\&     eval_pv(
+\&       "$a = \*(AqrekcaH lreP rehtonA tsuJ\*(Aq; $a = reverse($a);", TRUE);
+\&     printf("a = %s\en", SvPV_nolen(get_sv("a", 0)));
+\&
+\&     perl_destruct(my_perl);
+\&     perl_free(my_perl);
+\&     PERL_SYS_TERM();
+\& }
+.Ve
+.PP
+All of those strange functions with \fIsv\fR in their names help convert Perl
+scalars to C types.  They're described in perlguts and perlapi.
+.PP
+If you compile and run \fIstring.c\fR, you'll see the results of using
+\&\fR\f(BISvIV()\fR\fI\fR to create an \f(CW\*(C`int\*(C'\fR, \fI\fR\f(BISvNV()\fR\fI\fR to create a \f(CW\*(C`float\*(C'\fR, and
+\&\fI\fR\f(BISvPV()\fR\fI\fR to create a string:
+.PP
+.Vb 3
+\&   a = 9
+\&   a = 9.859600
+\&   a = Just Another Perl Hacker
+.Ve
+.PP
+In the example above, we've created a global variable to temporarily
+store the computed value of our eval'ed expression.  It is also
+possible and in most cases a better strategy to fetch the return value
+from \fR\f(BIeval_pv()\fR\fI\fR instead.  Example:
+.PP
+.Vb 4
+\&   ...
+\&   SV *val = eval_pv("reverse \*(AqrekcaH lreP rehtonA tsuJ\*(Aq", TRUE);
+\&   printf("%s\en", SvPV_nolen(val));
+\&   ...
+.Ve
+.PP
+This way, we avoid namespace pollution by not creating global
+variables and we've simplified our code as well.
+.SS "Performing Perl pattern matches and substitutions from your C program"
+.IX Subsection "Performing Perl pattern matches and substitutions from your C program"
+The \fR\f(BIeval_sv()\fR\fI\fR function lets us evaluate strings of Perl code, so we can
+define some functions that use it to "specialize" in matches and
+substitutions: \fI\fR\f(BImatch()\fR\fI\fR, \fI\fR\f(BIsubstitute()\fR\fI\fR, and \fI\fR\f(BImatches()\fR\fI\fR.
+.PP
+.Vb 1
+\&   I32 match(SV *string, char *pattern);
+.Ve
+.PP
+Given a string and a pattern (e.g., \f(CW\*(C`m/clasp/\*(C'\fR or \f(CW\*(C`/\eb\ew*\eb/\*(C'\fR, which
+in your C program might appear as "/\e\eb\e\ew*\e\eb/"), \fBmatch()\fR
+returns 1 if the string matches the pattern and 0 otherwise.
+.PP
+.Vb 1
+\&   int substitute(SV **string, char *pattern);
+.Ve
+.PP
+Given a pointer to an \f(CW\*(C`SV\*(C'\fR and an \f(CW\*(C`=~\*(C'\fR operation (e.g.,
+\&\f(CW\*(C`s/bob/robert/g\*(C'\fR or \f(CW\*(C`tr[A\-Z][a\-z]\*(C'\fR), \fBsubstitute()\fR modifies the string
+within the \f(CW\*(C`SV\*(C'\fR as according to the operation, returning the number of
+substitutions made.
+.PP
+.Vb 1
+\&   SSize_t matches(SV *string, char *pattern, AV **matches);
+.Ve
+.PP
+Given an \f(CW\*(C`SV\*(C'\fR, a pattern, and a pointer to an empty \f(CW\*(C`AV\*(C'\fR,
+\&\fBmatches()\fR evaluates \f(CW\*(C`$string =~ $pattern\*(C'\fR in a list context, and
+fills in \fImatches\fR with the array elements, returning the number of matches
+found.
+.PP
+Here's a sample program, \fImatch.c\fR, that uses all three (long lines have
+been wrapped here):
+.PP
+.Vb 2
+\& #include <EXTERN.h>
+\& #include <perl.h>
+\&
+\& static PerlInterpreter *my_perl;
+\&
+\& /** my_eval_sv(code, error_check)
+\& ** kinda like eval_sv(),
+\& ** but we pop the return value off the stack
+\& **/
+\& SV* my_eval_sv(SV *sv, I32 croak_on_error)
+\& {
+\&     dSP;
+\&     SV* retval;
+\&
+\&
+\&     PUSHMARK(SP);
+\&     eval_sv(sv, G_SCALAR);
+\&
+\&     SPAGAIN;
+\&     retval = POPs;
+\&     PUTBACK;
+\&
+\&     if (croak_on_error && SvTRUE(ERRSV))
+\&        croak_sv(ERRSV);
+\&
+\&     return retval;
+\& }
+\&
+\& /** match(string, pattern)
+\& **
+\& ** Used for matches in a scalar context.
+\& **
+\& ** Returns 1 if the match was successful; 0 otherwise.
+\& **/
+\&
+\& I32 match(SV *string, char *pattern)
+\& {
+\&     SV *command = newSV(0), *retval;
+\&
+\&     sv_setpvf(command, "my $string = \*(Aq%s\*(Aq; $string =~ %s",
+\&              SvPV_nolen(string), pattern);
+\&
+\&     retval = my_eval_sv(command, TRUE);
+\&     SvREFCNT_dec(command);
+\&
+\&     return SvIV(retval);
+\& }
+\&
+\& /** substitute(string, pattern)
+\& **
+\& ** Used for =~ operations that
+\& ** modify their left\-hand side (s/// and tr///)
+\& **
+\& ** Returns the number of successful matches, and
+\& ** modifies the input string if there were any.
+\& **/
+\&
+\& I32 substitute(SV **string, char *pattern)
+\& {
+\&     SV *command = newSV(0), *retval;
+\&
+\&     sv_setpvf(command, "$string = \*(Aq%s\*(Aq; ($string =~ %s)",
+\&              SvPV_nolen(*string), pattern);
+\&
+\&     retval = my_eval_sv(command, TRUE);
+\&     SvREFCNT_dec(command);
+\&
+\&     *string = get_sv("string", 0);
+\&     return SvIV(retval);
+\& }
+\&
+\& /** matches(string, pattern, matches)
+\& **
+\& ** Used for matches in a list context.
+\& **
+\& ** Returns the number of matches,
+\& ** and fills in **matches with the matching substrings
+\& **/
+\&
+\& SSize_t matches(SV *string, char *pattern, AV **match_list)
+\& {
+\&     SV *command = newSV(0);
+\&     SSize_t num_matches;
+\&
+\&     sv_setpvf(command, "my $string = \*(Aq%s\*(Aq; @array = ($string =~ %s)",
+\&              SvPV_nolen(string), pattern);
+\&
+\&     my_eval_sv(command, TRUE);
+\&     SvREFCNT_dec(command);
+\&
+\&     *match_list = get_av("array", 0);
+\&     num_matches = av_top_index(*match_list) + 1;
+\&
+\&     return num_matches;
+\& }
+\&
+\& main (int argc, char **argv, char **env)
+\& {
+\&     char *embedding[] = { "", "\-e", "0", NULL };
+\&     AV *match_list;
+\&     I32 num_matches, i;
+\&     SV *text;
+\&
+\&     PERL_SYS_INIT3(&argc,&argv,&env);
+\&     my_perl = perl_alloc();
+\&     perl_construct(my_perl);
+\&     perl_parse(my_perl, NULL, 3, embedding, NULL);
+\&     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&
+\&     text = newSV(0);
+\&     sv_setpv(text, "When he is at a convenience store and the "
+\&        "bill comes to some amount like 76 cents, Maynard is "
+\&        "aware that there is something he *should* do, something "
+\&        "that will enable him to get back a quarter, but he has "
+\&        "no idea *what*.  He fumbles through his red squeezey "
+\&        "changepurse and gives the boy three extra pennies with "
+\&        "his dollar, hoping that he might luck into the correct "
+\&        "amount.  The boy gives him back two of his own pennies "
+\&        "and then the big shiny quarter that is his prize. "
+\&        "\-RICHH");
+\&
+\&     if (match(text, "m/quarter/")) /** Does text contain \*(Aqquarter\*(Aq? **/
+\&        printf("match: Text contains the word \*(Aqquarter\*(Aq.\en\en");
+\&     else
+\&        printf("match: Text doesn\*(Aqt contain the word \*(Aqquarter\*(Aq.\en\en");
+\&
+\&     if (match(text, "m/eighth/")) /** Does text contain \*(Aqeighth\*(Aq? **/
+\&        printf("match: Text contains the word \*(Aqeighth\*(Aq.\en\en");
+\&     else
+\&        printf("match: Text doesn\*(Aqt contain the word \*(Aqeighth\*(Aq.\en\en");
+\&
+\&     /** Match all occurrences of /wi../ **/
+\&     num_matches = matches(text, "m/(wi..)/g", &match_list);
+\&     printf("matches: m/(wi..)/g found %d matches...\en", num_matches);
+\&
+\&     for (i = 0; i < num_matches; i++)
+\&         printf("match: %s\en",
+\&                  SvPV_nolen(*av_fetch(match_list, i, FALSE)));
+\&     printf("\en");
+\&
+\&     /** Remove all vowels from text **/
+\&     num_matches = substitute(&text, "s/[aeiou]//gi");
+\&     if (num_matches) {
+\&        printf("substitute: s/[aeiou]//gi...%lu substitutions made.\en",
+\&               (unsigned long)num_matches);
+\&        printf("Now text is: %s\en\en", SvPV_nolen(text));
+\&     }
+\&
+\&     /** Attempt a substitution **/
+\&     if (!substitute(&text, "s/Perl/C/")) {
+\&        printf("substitute: s/Perl/C...No substitution made.\en\en");
+\&     }
+\&
+\&     SvREFCNT_dec(text);
+\&     PL_perl_destruct_level = 1;
+\&     perl_destruct(my_perl);
+\&     perl_free(my_perl);
+\&     PERL_SYS_TERM();
+\& }
+.Ve
+.PP
+which produces the output (again, long lines have been wrapped here)
+.PP
+.Vb 1
+\&  match: Text contains the word \*(Aqquarter\*(Aq.
+\&
+\&  match: Text doesn\*(Aqt contain the word \*(Aqeighth\*(Aq.
+\&
+\&  matches: m/(wi..)/g found 2 matches...
+\&  match: will
+\&  match: with
+\&
+\&  substitute: s/[aeiou]//gi...139 substitutions made.
+\&  Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
+\&  Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
+\&  bck qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd
+\&  gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
+\&  mnt.  Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
+\&  hs prz. \-RCHH
+\&
+\&  substitute: s/Perl/C...No substitution made.
+.Ve
+.SS "Fiddling with the Perl stack from your C program"
+.IX Subsection "Fiddling with the Perl stack from your C program"
+When trying to explain stacks, most computer science textbooks mumble
+something about spring-loaded columns of cafeteria plates: the last
+thing you pushed on the stack is the first thing you pop off.  That'll
+do for our purposes: your C program will push some arguments onto "the Perl
+stack", shut its eyes while some magic happens, and then pop the
+results\-\-the return value of your Perl subroutine\-\-off the stack.
+.PP
+First you'll need to know how to convert between C types and Perl
+types, with \fBnewSViv()\fR and \fBsv_setnv()\fR and \fBnewAV()\fR and all their
+friends.  They're described in perlguts and perlapi.
+.PP
+Then you'll need to know how to manipulate the Perl stack.  That's
+described in perlcall.
+.PP
+Once you've understood those, embedding Perl in C is easy.
+.PP
+Because C has no builtin function for integer exponentiation, let's
+make Perl's ** operator available to it (this is less useful than it
+sounds, because Perl implements ** with C's \fR\f(BIpow()\fR\fI\fR function).  First
+I'll create a stub exponentiation function in \fIpower.pl\fR:
+.PP
+.Vb 4
+\&    sub expo {
+\&        my ($a, $b) = @_;
+\&        return $a ** $b;
+\&    }
+.Ve
+.PP
+Now I'll create a C program, \fIpower.c\fR, with a function
+\&\fR\f(BIPerlPower()\fR\fI\fR that contains all the perlguts necessary to push the
+two arguments into \fI\fR\f(BIexpo()\fR\fI\fR and to pop the return value out.  Take a
+deep breath...
+.PP
+.Vb 2
+\& #include <EXTERN.h>
+\& #include <perl.h>
+\&
+\& static PerlInterpreter *my_perl;
+\&
+\& static void
+\& PerlPower(int a, int b)
+\& {
+\&   dSP;                            /* initialize stack pointer      */
+\&   ENTER;                          /* everything created after here */
+\&   SAVETMPS;                       /* ...is a temporary variable.   */
+\&   PUSHMARK(SP);                   /* remember the stack pointer    */
+\&   XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
+\&   XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
+\&   PUTBACK;                      /* make local stack pointer global */
+\&   call_pv("expo", G_SCALAR);      /* call the function             */
+\&   SPAGAIN;                        /* refresh stack pointer         */
+\&                                 /* pop the return value from stack */
+\&   printf ("%d to the %dth power is %d.\en", a, b, POPi);
+\&   PUTBACK;
+\&   FREETMPS;                       /* free that return value        */
+\&   LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
+\& }
+\&
+\& int main (int argc, char **argv, char **env)
+\& {
+\&   char *my_argv[] = { "", "power.pl", NULL };
+\&
+\&   PERL_SYS_INIT3(&argc,&argv,&env);
+\&   my_perl = perl_alloc();
+\&   perl_construct( my_perl );
+\&
+\&   perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
+\&   PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&   perl_run(my_perl);
+\&
+\&   PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
+\&
+\&   perl_destruct(my_perl);
+\&   perl_free(my_perl);
+\&   PERL_SYS_TERM();
+\&   exit(EXIT_SUCCESS);
+\& }
+.Ve
+.PP
+Compile and run:
+.PP
+.Vb 1
+\&    % cc \-o power power.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+\&
+\&    % power
+\&    3 to the 4th power is 81.
+.Ve
+.SS "Maintaining a persistent interpreter"
+.IX Subsection "Maintaining a persistent interpreter"
+When developing interactive and/or potentially long-running
+applications, it's a good idea to maintain a persistent interpreter
+rather than allocating and constructing a new interpreter multiple
+times.  The major reason is speed: since Perl will only be loaded into
+memory once.
+.PP
+However, you have to be more cautious with namespace and variable
+scoping when using a persistent interpreter.  In previous examples
+we've been using global variables in the default package \f(CW\*(C`main\*(C'\fR.  We
+knew exactly what code would be run, and assumed we could avoid
+variable collisions and outrageous symbol table growth.
+.PP
+Let's say your application is a server that will occasionally run Perl
+code from some arbitrary file.  Your server has no way of knowing what
+code it's going to run.  Very dangerous.
+.PP
+If the file is pulled in by \f(CWperl_parse()\fR, compiled into a newly
+constructed interpreter, and subsequently cleaned out with
+\&\f(CWperl_destruct()\fR afterwards, you're shielded from most namespace
+troubles.
+.PP
+One way to avoid namespace collisions in this scenario is to translate
+the filename into a guaranteed-unique package name, and then compile
+the code into that package using "eval" in perlfunc.  In the example
+below, each file will only be compiled once.  Or, the application
+might choose to clean out the symbol table associated with the file
+after it's no longer needed.  Using "call_argv" in perlapi, We'll
+call the subroutine \f(CW\*(C`Embed::Persistent::eval_file\*(C'\fR which lives in the
+file \f(CW\*(C`persistent.pl\*(C'\fR and pass the filename and boolean cleanup/cache
+flag as arguments.
+.PP
+Note that the process will continue to grow for each file that it
+uses.  In addition, there might be \f(CW\*(C`AUTOLOAD\*(C'\fRed subroutines and other
+conditions that cause Perl's symbol table to grow.  You might want to
+add some logic that keeps track of the process size, or restarts
+itself after a certain number of requests, to ensure that memory
+consumption is minimized.  You'll also want to scope your variables
+with "my" in perlfunc whenever possible.
+.PP
+.Vb 2
+\& package Embed::Persistent;
+\& #persistent.pl
+\&
+\& use strict;
+\& our %Cache;
+\& use Symbol qw(delete_package);
+\&
+\& sub valid_package_name {
+\&     my($string) = @_;
+\&     $string =~ s/([^A\-Za\-z0\-9\e/])/sprintf("_%2x",unpack("C",$1))/eg;
+\&     # second pass only for words starting with a digit
+\&     $string =~ s|/(\ed)|sprintf("/_%2x",unpack("C",$1))|eg;
+\&
+\&     # Dress it up as a real package name
+\&     $string =~ s|/|::|g;
+\&     return "Embed" . $string;
+\& }
+\&
+\& sub eval_file {
+\&     my($filename, $delete) = @_;
+\&     my $package = valid_package_name($filename);
+\&     my $mtime = \-M $filename;
+\&     if(defined $Cache{$package}{mtime}
+\&        &&
+\&        $Cache{$package}{mtime} <= $mtime)
+\&     {
+\&        # we have compiled this subroutine already,
+\&        # it has not been updated on disk, nothing left to do
+\&        print STDERR "already compiled $package\->handler\en";
+\&     }
+\&     else {
+\&        local *FH;
+\&        open FH, $filename or die "open \*(Aq$filename\*(Aq $!";
+\&        local($/) = undef;
+\&        my $sub = <FH>;
+\&        close FH;
+\&
+\&        #wrap the code into a subroutine inside our unique package
+\&        my $eval = qq{package $package; sub handler { $sub; }};
+\&        {
+\&            # hide our variables within this block
+\&            my($filename,$mtime,$package,$sub);
+\&            eval $eval;
+\&        }
+\&        die $@ if $@;
+\&
+\&        #cache it unless we\*(Aqre cleaning out each time
+\&        $Cache{$package}{mtime} = $mtime unless $delete;
+\&     }
+\&
+\&     eval {$package\->handler;};
+\&     die $@ if $@;
+\&
+\&     delete_package($package) if $delete;
+\&
+\&     #take a look if you want
+\&     #print Devel::Symdump\->rnew($package)\->as_string, $/;
+\& }
+\&
+\& 1;
+\&
+\& _\|_END_\|_
+\&
+\& /* persistent.c */
+\& #include <EXTERN.h>
+\& #include <perl.h>
+\&
+\& /* 1 = clean out filename\*(Aqs symbol table after each request,
+\&    0 = don\*(Aqt
+\& */
+\& #ifndef DO_CLEAN
+\& #define DO_CLEAN 0
+\& #endif
+\&
+\& #define BUFFER_SIZE 1024
+\&
+\& static PerlInterpreter *my_perl = NULL;
+\&
+\& int
+\& main(int argc, char **argv, char **env)
+\& {
+\&     char *embedding[] = { "", "persistent.pl", NULL };
+\&     char *args[] = { "", DO_CLEAN, NULL };
+\&     char filename[BUFFER_SIZE];
+\&     int failing, exitstatus;
+\&
+\&     PERL_SYS_INIT3(&argc,&argv,&env);
+\&     if((my_perl = perl_alloc()) == NULL) {
+\&        fprintf(stderr, "no memory!");
+\&        exit(EXIT_FAILURE);
+\&     }
+\&     perl_construct(my_perl);
+\&
+\&     PL_origalen = 1; /* don\*(Aqt let $0 assignment update the
+\&                         proctitle or embedding[0] */
+\&     failing = perl_parse(my_perl, NULL, 2, embedding, NULL);
+\&     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+\&     if(!failing)
+\&        failing = perl_run(my_perl);
+\&     if(!failing) {
+\&        while(printf("Enter file name: ") &&
+\&              fgets(filename, BUFFER_SIZE, stdin)) {
+\&
+\&            filename[strlen(filename)\-1] = \*(Aq\e0\*(Aq; /* strip \en */
+\&            /* call the subroutine,
+\&                     passing it the filename as an argument */
+\&            args[0] = filename;
+\&            call_argv("Embed::Persistent::eval_file",
+\&                           G_DISCARD | G_EVAL, args);
+\&
+\&            /* check $@ */
+\&            if(SvTRUE(ERRSV))
+\&                fprintf(stderr, "eval error: %s\en", SvPV_nolen(ERRSV));
+\&        }
+\&     }
+\&
+\&     PL_perl_destruct_level = 0;
+\&     exitstatus = perl_destruct(my_perl);
+\&     perl_free(my_perl);
+\&     PERL_SYS_TERM();
+\&     exit(exitstatus);
+\& }
+.Ve
+.PP
+Now compile:
+.PP
+.Vb 2
+\& % cc \-o persistent persistent.c \e
+\&        \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+.Ve
+.PP
+Here's an example script file:
+.PP
+.Vb 3
+\& #test.pl
+\& my $string = "hello";
+\& foo($string);
+\&
+\& sub foo {
+\&     print "foo says: @_\en";
+\& }
+.Ve
+.PP
+Now run:
+.PP
+.Vb 7
+\& % persistent
+\& Enter file name: test.pl
+\& foo says: hello
+\& Enter file name: test.pl
+\& already compiled Embed::test_2epl\->handler
+\& foo says: hello
+\& Enter file name: ^C
+.Ve
+.SS "Execution of END blocks"
+.IX Subsection "Execution of END blocks"
+Traditionally END blocks have been executed at the end of the perl_run.
+This causes problems for applications that never call perl_run. Since
+perl 5.7.2 you can specify \f(CW\*(C`PL_exit_flags |= PERL_EXIT_DESTRUCT_END\*(C'\fR
+to get the new behaviour. This also enables the running of END blocks if
+the perl_parse fails and \f(CW\*(C`perl_destruct\*(C'\fR will return the exit value.
+.ie n .SS "$0 assignments"
+.el .SS "\f(CW$0\fP assignments"
+.IX Subsection "$0 assignments"
+When a perl script assigns a value to \f(CW$0\fR then the perl runtime will
+try to make this value show up as the program name reported by "ps" by
+updating the memory pointed to by the argv passed to \fBperl_parse()\fR and
+also calling API functions like \fBsetproctitle()\fR where available.  This
+behaviour might not be appropriate when embedding perl and can be
+disabled by assigning the value \f(CW1\fR to the variable \f(CW\*(C`PL_origalen\*(C'\fR
+before \fBperl_parse()\fR is called.
+.PP
+The \fIpersistent.c\fR example above is for instance likely to segfault
+when \f(CW$0\fR is assigned to if the \f(CW\*(C`PL_origalen = 1;\*(C'\fR assignment is
+removed.  This because perl will try to write to the read only memory
+of the \f(CW\*(C`embedding[]\*(C'\fR strings.
+.SS "Maintaining multiple interpreter instances"
+.IX Subsection "Maintaining multiple interpreter instances"
+Some rare applications will need to create more than one interpreter
+during a session.  Such an application might sporadically decide to
+release any resources associated with the interpreter.
+.PP
+The program must take care to ensure that this takes place \fIbefore\fR
+the next interpreter is constructed.  By default, when perl is not
+built with any special options, the global variable
+\&\f(CW\*(C`PL_perl_destruct_level\*(C'\fR is set to \f(CW0\fR, since extra cleaning isn't
+usually needed when a program only ever creates a single interpreter
+in its entire lifetime.
+.PP
+Setting \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to \f(CW1\fR makes everything squeaky clean:
+.PP
+.Vb 10
+\& while(1) {
+\&     ...
+\&     /* reset global variables here with PL_perl_destruct_level = 1 */
+\&     PL_perl_destruct_level = 1;
+\&     perl_construct(my_perl);
+\&     ...
+\&     /* clean and reset _everything_ during perl_destruct */
+\&     PL_perl_destruct_level = 1;
+\&     perl_destruct(my_perl);
+\&     perl_free(my_perl);
+\&     ...
+\&     /* let\*(Aqs go do it again! */
+\& }
+.Ve
+.PP
+When \fR\f(BIperl_destruct()\fR\fI\fR is called, the interpreter's syntax parse tree
+and symbol tables are cleaned up, and global variables are reset.  The
+second assignment to \f(CW\*(C`PL_perl_destruct_level\*(C'\fR is needed because
+perl_construct resets it to \f(CW0\fR.
+.PP
+Now suppose we have more than one interpreter instance running at the
+same time.  This is feasible, but only if you used the Configure option
+\&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR or the options \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR when
+building perl.  By default, enabling one of these Configure options
+sets the per-interpreter global variable \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to
+\&\f(CW1\fR, so that thorough cleaning is automatic and interpreter variables
+are initialized correctly.  Even if you don't intend to run two or
+more interpreters at the same time, but to run them sequentially, like
+in the above example, it is recommended to build perl with the
+\&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR option otherwise some interpreter variables may
+not be initialized correctly between consecutive runs and your
+application may crash.
+.PP
+See also "Thread-aware system interfaces" in perlxs.
+.PP
+Using \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR rather than \f(CW\*(C`\-Dusemultiplicity\*(C'\fR
+is more appropriate if you intend to run multiple interpreters
+concurrently in different threads, because it enables support for
+linking in the thread libraries of your system with the interpreter.
+.PP
+Let's give it a try:
+.PP
+.Vb 2
+\& #include <EXTERN.h>
+\& #include <perl.h>
+\&
+\& /* we\*(Aqre going to embed two interpreters */
+\&
+\& #define SAY_HELLO "\-e", "print qq(Hi, I\*(Aqm $^X\en)"
+\&
+\& int main(int argc, char **argv, char **env)
+\& {
+\&     PerlInterpreter *one_perl, *two_perl;
+\&     char *one_args[] = { "one_perl", SAY_HELLO, NULL };
+\&     char *two_args[] = { "two_perl", SAY_HELLO, NULL };
+\&
+\&     PERL_SYS_INIT3(&argc,&argv,&env);
+\&     one_perl = perl_alloc();
+\&     two_perl = perl_alloc();
+\&
+\&     PERL_SET_CONTEXT(one_perl);
+\&     perl_construct(one_perl);
+\&     PERL_SET_CONTEXT(two_perl);
+\&     perl_construct(two_perl);
+\&
+\&     PERL_SET_CONTEXT(one_perl);
+\&     perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
+\&     PERL_SET_CONTEXT(two_perl);
+\&     perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
+\&
+\&     PERL_SET_CONTEXT(one_perl);
+\&     perl_run(one_perl);
+\&     PERL_SET_CONTEXT(two_perl);
+\&     perl_run(two_perl);
+\&
+\&     PERL_SET_CONTEXT(one_perl);
+\&     perl_destruct(one_perl);
+\&     PERL_SET_CONTEXT(two_perl);
+\&     perl_destruct(two_perl);
+\&
+\&     PERL_SET_CONTEXT(one_perl);
+\&     perl_free(one_perl);
+\&     PERL_SET_CONTEXT(two_perl);
+\&     perl_free(two_perl);
+\&     PERL_SYS_TERM();
+\&     exit(EXIT_SUCCESS);
+\& }
+.Ve
+.PP
+Note the calls to \fBPERL_SET_CONTEXT()\fR.  These are necessary to initialize
+the global state that tracks which interpreter is the "current" one on
+the particular process or thread that may be running it.  It should
+always be used if you have more than one interpreter and are making
+perl API calls on both interpreters in an interleaved fashion.
+.PP
+PERL_SET_CONTEXT(interp) should also be called whenever \f(CW\*(C`interp\*(C'\fR is
+used by a thread that did not create it (using either \fBperl_alloc()\fR, or
+the more esoteric \fBperl_clone()\fR).
+.PP
+Compile as usual:
+.PP
+.Vb 2
+\& % cc \-o multiplicity multiplicity.c \e
+\&  \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+.Ve
+.PP
+Run it, Run it:
+.PP
+.Vb 3
+\& % multiplicity
+\& Hi, I\*(Aqm one_perl
+\& Hi, I\*(Aqm two_perl
+.Ve
+.SS "Using Perl modules, which themselves use C libraries, from your C program"
+.IX Subsection "Using Perl modules, which themselves use C libraries, from your C program"
+If you've played with the examples above and tried to embed a script
+that \fR\f(BIuse()\fR\fI\fRs a Perl module (such as \fISocket\fR) which itself uses a C or C++
+library, this probably happened:
+.PP
+.Vb 3
+\& Can\*(Aqt load module Socket, dynamic loading not available in this perl.
+\&  (You may need to build a new perl executable which either supports
+\&  dynamic loading or has the Socket module statically linked into it.)
+.Ve
+.PP
+What's wrong?
+.PP
+Your interpreter doesn't know how to communicate with these extensions
+on its own.  A little glue will help.  Up until now you've been
+calling \fR\f(BIperl_parse()\fR\fI\fR, handing it NULL for the second argument:
+.PP
+.Vb 1
+\& perl_parse(my_perl, NULL, argc, my_argv, NULL);
+.Ve
+.PP
+That's where the glue code can be inserted to create the initial contact
+between Perl and linked C/C++ routines. Let's take a look some pieces of
+\&\fIperlmain.c\fR to see how Perl does this:
+.PP
+.Vb 1
+\& static void xs_init (pTHX);
+\&
+\& EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
+\& EXTERN_C void boot_Socket (pTHX_ CV* cv);
+\&
+\&
+\& EXTERN_C void
+\& xs_init(pTHX)
+\& {
+\&        char *file = _\|_FILE_\|_;
+\&        /* DynaLoader is a special case */
+\&        newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
+\&        newXS("Socket::bootstrap", boot_Socket, file);
+\& }
+.Ve
+.PP
+Simply put: for each extension linked with your Perl executable
+(determined during its initial configuration on your
+computer or when adding a new extension),
+a Perl subroutine is created to incorporate the extension's
+routines.  Normally, that subroutine is named
+\&\fR\f(BIModule::bootstrap()\fR\fI\fR and is invoked when you say \fIuse Module\fR.  In
+turn, this hooks into an XSUB, \fIboot_Module\fR, which creates a Perl
+counterpart for each of the extension's XSUBs.  Don't worry about this
+part; leave that to the \fIxsubpp\fR and extension authors.  If your
+extension is dynamically loaded, DynaLoader creates \fI\fR\f(BIModule::bootstrap()\fR\fI\fR
+for you on the fly.  In fact, if you have a working DynaLoader then there
+is rarely any need to link in any other extensions statically.
+.PP
+Once you have this code, slap it into the second argument of \fR\f(BIperl_parse()\fR\fI\fR:
+.PP
+.Vb 1
+\& perl_parse(my_perl, xs_init, argc, my_argv, NULL);
+.Ve
+.PP
+Then compile:
+.PP
+.Vb 1
+\& % cc \-o interp interp.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
+\&
+\& % interp
+\&   use Socket;
+\&   use SomeDynamicallyLoadedModule;
+\&
+\&   print "Now I can use extensions!\en"\*(Aq
+.Ve
+.PP
+\&\fBExtUtils::Embed\fR can also automate writing the \fIxs_init\fR glue code.
+.PP
+.Vb 4
+\& % perl \-MExtUtils::Embed \-e xsinit \-\- \-o perlxsi.c
+\& % cc \-c perlxsi.c \`perl \-MExtUtils::Embed \-e ccopts\`
+\& % cc \-c interp.c  \`perl \-MExtUtils::Embed \-e ccopts\`
+\& % cc \-o interp perlxsi.o interp.o \`perl \-MExtUtils::Embed \-e ldopts\`
+.Ve
+.PP
+Consult perlxs, perlguts, and perlapi for more details.
+.SS "Using embedded Perl with POSIX locales"
+.IX Subsection "Using embedded Perl with POSIX locales"
+(See perllocale for information about these.)
+When a Perl interpreter normally starts up, it tells the system it wants
+to use the system's default locale.  This is often, but not necessarily,
+the "C" or "POSIX" locale.  Absent a \f(CW"use\ locale"\fR within the perl
+code, this mostly has no effect (but see "Not within the
+scope of "use locale"" in perllocale).  Also, there is not a problem if the
+locale you want to use in your embedded perl is the same as the system
+default.  However, this doesn't work if you have set up and want to use
+a locale that isn't the system default one.  Starting in Perl v5.20, you
+can tell the embedded Perl interpreter that the locale is already
+properly set up, and to skip doing its own normal initialization.  It
+skips if the environment variable \f(CW\*(C`PERL_SKIP_LOCALE_INIT\*(C'\fR is set (even
+if set to 0 or \f(CW""\fR).  A perl that has this capability will define the
+C pre-processor symbol \f(CW\*(C`HAS_SKIP_LOCALE_INIT\*(C'\fR.  This allows code that
+has to work with multiple Perl versions to do some sort of work-around
+when confronted with an earlier Perl.
+.PP
+If your program is using the POSIX 2008 multi-thread locale
+functionality, you should switch into the global locale and set that up
+properly before starting the Perl interpreter.  It will then properly
+switch back to using the thread-safe functions.
+.SH "Hiding Perl_"
+.IX Header "Hiding Perl_"
+If you completely hide the short forms of the Perl public API,
+add \-DPERL_NO_SHORT_NAMES to the compilation flags.  This means that
+for example instead of writing
+.PP
+.Vb 1
+\&    warn("%d bottles of beer on the wall", bottlecount);
+.Ve
+.PP
+you will have to write the explicit full form
+.PP
+.Vb 1
+\&    Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
+.Ve
+.PP
+(See "Background and MULTIPLICITY" in perlguts for the explanation
+of the \f(CW\*(C`aTHX_\*(C'\fR. )  Hiding the short forms is very useful for avoiding
+all sorts of nasty (C preprocessor or otherwise) conflicts with other
+software packages (Perl defines about 2400 APIs with these short names,
+take or leave few hundred, so there certainly is room for conflict.)
+.SH MORAL
+.IX Header "MORAL"
+You can sometimes \fIwrite faster code\fR in C, but
+you can always \fIwrite code faster\fR in Perl.  Because you can use
+each from the other, combine them as you wish.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Jon Orwant <\fIorwant@media.mit.edu\fR> and Doug MacEachern
+<\fIdougm@covalent.net\fR>, with small contributions from Tim Bunce, Tom
+Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
+Zakharevich.
+.PP
+Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
+The Perl Journal ( <http://www.tpj.com/> ).  Doug is also the developer of the
+most widely-used Perl embedding: the mod_perl system
+(perl.apache.org), which embeds Perl in the Apache web server.
+Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
+have used this model for Oracle, Netscape and Internet Information
+Server Perl plugins.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.  All
+Rights Reserved.
+.PP
+This document may be distributed under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlexperiment.1 b/upstream/mageia-cauldron/man1/perlexperiment.1
new file mode 100644
index 00000000..a266029b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlexperiment.1
@@ -0,0 +1,479 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLEXPERIMENT 1"
+.TH PERLEXPERIMENT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlexperiment \- A listing of experimental features in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document lists the current and past experimental features in the perl
+core. Although all of these are documented with their appropriate topics,
+this succinct listing gives you an overview and basic facts about their
+status.
+.PP
+So far we've merely tried to find and list the experimental features and infer
+their inception, versions, etc. There's a lot of speculation here.
+.SS "Current experiments"
+.IX Subsection "Current experiments"
+.ie n .IP "Smart match (""~~"")" 8
+.el .IP "Smart match (\f(CW~~\fR)" 8
+.IX Item "Smart match (~~)"
+Introduced in Perl 5.10.0
+.Sp
+Modified in Perl 5.10.1, 5.12.0
+.Sp
+Deprecated in 5.38.0
+.Sp
+Will be removed in 5.42.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`deprecated\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #13173] <https://github.com/Perl/perl5/issues/13173>.
+.IP "Pluggable keywords" 8
+.IX Item "Pluggable keywords"
+Introduced in Perl 5.11.2
+.Sp
+See "PL_keyword_plugin" in perlapi for the mechanism.
+.Sp
+The ticket for this experiment is
+[perl #13199] <https://github.com/Perl/perl5/issues/13199>.
+.IP "Aliasing via reference" 8
+.IX Item "Aliasing via reference"
+Introduced in Perl 5.22.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::refaliasing\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #14150] <https://github.com/Perl/perl5/issues/14150>.
+.Sp
+See also: "Assigning to References" in perlref
+.IP "The ""const"" attribute" 8
+.IX Item "The ""const"" attribute"
+Introduced in Perl 5.22.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::const_attr\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #14428] <https://github.com/Perl/perl5/issues/14428>.
+.Sp
+See also: "Constant Functions" in perlsub
+.IP "use re 'strict';" 8
+.IX Item "use re 'strict';"
+Introduced in Perl 5.22.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::re_strict\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #18755] <https://github.com/Perl/perl5/issues/18755>
+.Sp
+See "'strict' mode" in re
+.IP "Declaring a reference to a variable" 8
+.IX Item "Declaring a reference to a variable"
+Introduced in Perl 5.26.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::declared_refs\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #15458] <https://github.com/Perl/perl5/issues/15458>.
+.Sp
+See also: "Declaring a Reference to a Variable" in perlref
+.ie n .IP "There is an ""installhtml"" target in the Makefile." 8
+.el .IP "There is an \f(CWinstallhtml\fR target in the Makefile." 8
+.IX Item "There is an installhtml target in the Makefile."
+The ticket for this experiment is
+[perl #12726] <https://github.com/Perl/perl5/issues/12726>.
+.IP "(Limited) Variable-length look-behind" 8
+.IX Item "(Limited) Variable-length look-behind"
+Introduced in Perl 5.30.0.
+.Sp
+Variability of up to 255 characters is handled.
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::vlb\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #18756] <https://github.com/Perl/perl5/issues/18756>.
+.Sp
+See also: "(*positive_lookbehind:\fIpattern\fR)" in perlre and
+"(*negative_lookbehind:\fIpattern\fR)" in perlre
+.IP "Unicode private use character hooks" 8
+.IX Item "Unicode private use character hooks"
+Introduced in Perl 5.30.0.
+.Sp
+This feature is part of an interface intended for internal and experimental
+use by the perl5 developers.  You are unlikely to encounter it in the wild.
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::private_use\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #18758] <https://github.com/Perl/perl5/issues/18758>.
+.IP "Unicode property wildcards" 8
+.IX Item "Unicode property wildcards"
+Introduced in Perl 5.30.0.
+.Sp
+This feature allows regular expression matching against Unicode character
+properties to be expressed more concisely.
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::uniprop_wildcards\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #18759] <https://github.com/Perl/perl5/issues/18759>.
+.IP "try/catch control structure" 8
+.IX Item "try/catch control structure"
+Introduced in Perl 5.34.0.
+.Sp
+Using this feature triggers warnings in the category \f(CW\*(C`experimental::try\*(C'\fR.
+.Sp
+The ticket for this experiment is
+[perl #18760] <https://github.com/Perl/perl5/issues/18760>
+.ie n .IP "Use of @_ within subroutine signatures" 8
+.el .IP "Use of \f(CW@_\fR within subroutine signatures" 8
+.IX Item "Use of @_ within subroutine signatures"
+Introduced in Perl 5.36.0 as part of a reduction in the scope of experimental
+subroutine signatures.
+.Sp
+Using the default arguments array (\f(CW@_\fR) within a subroutine that uses
+signatures will emit a warning in the category
+\&\f(CW\*(C`experimental::args_array_with_signatures\*(C'\fR. This includes \f(CW@_\fR directly,
+elements of it such as \f(CW$_[$index]\fR, or situations where the default
+arguments array is accessed implicitly such as \f(CW\*(C`shift\*(C'\fR or \f(CW\*(C`pop\*(C'\fR without
+arguments.
+.IP "for loop with multiple iteration variables" 8
+.IX Item "for loop with multiple iteration variables"
+Introduced in Perl 5.36.0.
+.Sp
+Using this feature triggers warnings in the category \f(CW\*(C`experimental::for_list\*(C'\fR.
+.Sp
+This feature enables a parenthesized list of iteration variables for \f(CW\*(C`for\*(C'\fR
+rather than a single variable.
+.Sp
+The ticket for this experiment is
+[perl #18744] <https://github.com/Perl/perl5/issues/18744>.
+.IP "The builtin namespace" 8
+.IX Item "The builtin namespace"
+Introduced in Perl 5.36.0.
+.Sp
+Using this feature triggers warnings in the category \f(CW\*(C`experimental::builtin\*(C'\fR.
+.Sp
+In Perl 5.36.0, a new namespace, \f(CW\*(C`builtin\*(C'\fR, was created for new core functions
+that will not be present in every namespace, but will be available for
+importing.  The namespace itself is considered an experiment.  Specific
+functions within it may also be experimental.
+.Sp
+The ticket for this experiment is
+[perl #19764] <https://github.com/Perl/perl5/issues/19764>.
+.IP "The defer block modifier" 8
+.IX Item "The defer block modifier"
+Introduced in Perl 5.36.0
+.Sp
+Using this feature triggers warnings in the category \f(CW\*(C`experimental::defer\*(C'\fR.
+.Sp
+This feature adds a new kind of block, a \f(CW\*(C`defer\*(C'\fR block, which will not be
+executed until the containing block is being exited.
+.Sp
+The ticket for this experiment is
+[perl #17949] <https://github.com/Perl/perl5/issues/17949>.
+.IP "Extra paired delimiters for quote-like operators" 8
+.IX Item "Extra paired delimiters for quote-like operators"
+Introduced in Perl 5.36.0
+.Sp
+Using this feature triggers warnings in the category
+\&\f(CW\*(C`experimental::extra_paired_delimiters\*(C'\fR.
+.Sp
+This feature allows for many non-ASCII pairs of mirroring delimiters, for
+example:
+.Sp
+.Vb 1
+\&    my @array = qw« tinker tailer soldier spy »;
+.Ve
+.Sp
+The ticket for this experiment is
+[perl #19765] <https://github.com/Perl/perl5/issues/19765>.
+.SS "Accepted features"
+.IX Subsection "Accepted features"
+These features were so wildly successful and played so well with others that
+we decided to remove their experimental status and admit them as full, stable
+features in the world of Perl, lavishing all the benefits and luxuries thereof.
+They are also awarded +5 Stability and +3 Charisma.
+.IP "64\-bit support" 8
+.IX Item "64-bit support"
+Introduced in Perl 5.005
+.IP "die accepts a reference" 8
+.IX Item "die accepts a reference"
+Introduced in Perl 5.005
+.IP "DB module" 8
+.IX Item "DB module"
+Introduced in Perl 5.6.0
+.Sp
+See also perldebug, perldebtut
+.IP "Weak references" 8
+.IX Item "Weak references"
+Introduced in Perl 5.6.0
+.IP "Internal file glob" 8
+.IX Item "Internal file glob"
+Introduced in Perl 5.6.0
+.IP "\fBfork()\fR emulation" 8
+.IX Item "fork() emulation"
+Introduced in Perl 5.6.1
+.Sp
+See also perlfork
+.IP "\-Dusemultiplicity \-Duseithreads" 8
+.IX Item "-Dusemultiplicity -Duseithreads"
+Introduced in Perl 5.6.0
+.Sp
+Accepted in Perl 5.8.0
+.IP "Support for long doubles" 8
+.IX Item "Support for long doubles"
+Introduced in Perl 5.6.0
+.Sp
+Accepted in Perl 5.8.1
+.ie n .IP "The ""\eN"" regex character class" 8
+.el .IP "The \f(CW\eN\fR regex character class" 8
+.IX Item "The N regex character class"
+The \f(CW\*(C`\eN\*(C'\fR character class, not to be confused with the named character
+sequence \f(CW\*(C`\eN{NAME}\*(C'\fR, denotes any non-newline character in a regular
+expression.
+.Sp
+Introduced in Perl 5.12
+.Sp
+Exact version of acceptance unclear, but no later than Perl 5.18.
+.ie n .IP """(?{code})"" and ""(??{ code })""" 8
+.el .IP "\f(CW(?{code})\fR and \f(CW(??{ code })\fR" 8
+.IX Item "(?{code}) and (??{ code })"
+Introduced in Perl 5.6.0
+.Sp
+Accepted in Perl 5.20.0
+.Sp
+See also perlre
+.IP "Linux abstract Unix domain sockets" 8
+.IX Item "Linux abstract Unix domain sockets"
+Introduced in Perl 5.9.2
+.Sp
+Accepted before Perl 5.20.0.  The Socket library is now primarily maintained
+on CPAN, rather than in the perl core.
+.Sp
+See also Socket
+.IP "Lvalue subroutines" 8
+.IX Item "Lvalue subroutines"
+Introduced in Perl 5.6.0
+.Sp
+Accepted in Perl 5.20.0
+.Sp
+See also perlsub
+.IP "Backtracking control verbs" 8
+.IX Item "Backtracking control verbs"
+\&\f(CW\*(C`(*ACCEPT)\*(C'\fR
+.Sp
+Introduced in Perl 5.10
+.Sp
+Accepted in Perl 5.20.0
+.ie n .IP "The "":pop"" IO pseudolayer" 8
+.el .IP "The \f(CW:pop\fR IO pseudolayer" 8
+.IX Item "The :pop IO pseudolayer"
+See also "PERLIO" in perlrun
+.Sp
+Accepted in Perl 5.20.0
+.ie n .IP """\es"" in regexp matches vertical tab" 8
+.el .IP "\f(CW\es\fR in regexp matches vertical tab" 8
+.IX Item "s in regexp matches vertical tab"
+Accepted in Perl 5.22.0
+.IP "Postfix dereference syntax" 8
+.IX Item "Postfix dereference syntax"
+Introduced in Perl 5.20.0
+.Sp
+Accepted in Perl 5.24.0
+.IP "Lexical subroutines" 8
+.IX Item "Lexical subroutines"
+Introduced in Perl 5.18.0
+.Sp
+Accepted in Perl 5.26.0
+.IP "String\- and number-specific bitwise operators" 8
+.IX Item "String- and number-specific bitwise operators"
+Introduced in Perl 5.22.0
+.Sp
+Accepted in Perl 5.28.0
+.IP "Alphabetic assertions" 8
+.IX Item "Alphabetic assertions"
+Introduced in Perl 5.28.0
+.Sp
+Accepted in Perl 5.32.0
+.IP "Script runs" 8
+.IX Item "Script runs"
+Introduced in Perl 5.28.0
+.Sp
+Accepted in Perl 5.32.0
+.ie n .IP "The infix ""isa"" operator" 8
+.el .IP "The infix \f(CWisa\fR operator" 8
+.IX Item "The infix isa operator"
+Introduced in Perl 5.32.0
+.Sp
+Accepted in Perl 5.36.0
+.IP "Subroutine signatures" 8
+.IX Item "Subroutine signatures"
+Introduced in Perl 5.20.0
+.Sp
+Accepted in Perl 5.36.0
+.IP "Regular Expression Set Operations" 8
+.IX Item "Regular Expression Set Operations"
+Introduced in Perl 5.18
+.Sp
+Accepted in Perl 5.36
+.Sp
+See : "Extended Bracketed Character Classes" in perlrecharclass
+.SS "Removed features"
+.IX Subsection "Removed features"
+These features are no longer considered experimental and their functionality
+has disappeared. It's your own fault if you wrote production programs using
+these features after we explicitly told you not to (see perlpolicy).
+.IP "5.005\-style threading" 8
+.IX Item "5.005-style threading"
+Introduced in Perl 5.005
+.Sp
+Removed in Perl 5.10
+.IP perlcc 8
+.IX Item "perlcc"
+Introduced in Perl 5.005
+.Sp
+Moved from Perl 5.9.0 to CPAN
+.IP "The pseudo-hash data type" 8
+.IX Item "The pseudo-hash data type"
+Introduced in Perl 5.6.0
+.Sp
+Removed in Perl 5.9.0
+.IP "GetOpt::Long Options can now take multiple values at once (experimental)" 8
+.IX Item "GetOpt::Long Options can now take multiple values at once (experimental)"
+\&\f(CW\*(C`Getopt::Long\*(C'\fR upgraded to version 2.35
+.Sp
+Removed in Perl 5.8.8
+.IP Assertions 8
+.IX Item "Assertions"
+The \f(CW\*(C`\-A\*(C'\fR command line switch
+.Sp
+Introduced in Perl 5.9.0
+.Sp
+Removed in Perl 5.9.5
+.IP Test::Harness::Straps 8
+.IX Item "Test::Harness::Straps"
+Moved from Perl 5.10.1 to CPAN
+.ie n .IP """legacy""" 8
+.el .IP \f(CWlegacy\fR 8
+.IX Item "legacy"
+The experimental \f(CW\*(C`legacy\*(C'\fR pragma was swallowed by the \f(CW\*(C`feature\*(C'\fR pragma.
+.Sp
+Introduced in Perl 5.11.2
+.Sp
+Removed in Perl 5.11.3
+.ie n .IP "Lexical $_" 8
+.el .IP "Lexical \f(CW$_\fR" 8
+.IX Item "Lexical $_"
+Using this feature triggered warnings in the category
+\&\f(CW\*(C`experimental::lexical_topic\*(C'\fR.
+.Sp
+Introduced in Perl 5.10.0
+.Sp
+Removed in Perl 5.24.0
+.IP "Array and hash container functions accept references" 8
+.IX Item "Array and hash container functions accept references"
+Using this feature triggered warnings in the category
+\&\f(CW\*(C`experimental::autoderef\*(C'\fR.
+.Sp
+Superseded by "Postfix dereference syntax".
+.Sp
+Introduced in Perl 5.14.0
+.Sp
+Removed in Perl 5.24.0
+.ie n .IP """our"" can have an experimental optional attribute ""unique""" 8
+.el .IP "\f(CWour\fR can have an experimental optional attribute \f(CWunique\fR" 8
+.IX Item "our can have an experimental optional attribute unique"
+Introduced in Perl 5.8.0
+.Sp
+Deprecated in Perl 5.10.0
+.Sp
+Removed in Perl 5.28.0
+.ie n .IP "The "":win32"" IO pseudolayer" 8
+.el .IP "The \f(CW:win32\fR IO pseudolayer" 8
+.IX Item "The :win32 IO pseudolayer"
+Introduced in Perl 5.8.0 (or before)
+.Sp
+Removed in Perl 5.36.0
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+For a complete list of features check feature.
+.SH AUTHORS
+.IX Header "AUTHORS"
+brian d foy \f(CW\*(C`<brian.d.foy@gmail.com>\*(C'\fR
+.PP
+Sébastien Aperghis-Tramoni \f(CW\*(C`<saper@cpan.org>\*(C'\fR
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2010, brian d foy \f(CW\*(C`<brian.d.foy@gmail.com>\*(C'\fR
+.SH LICENSE
+.IX Header "LICENSE"
+You can use and redistribute this document under the same terms as Perl
+itself.
diff --git a/upstream/mageia-cauldron/man1/perlfaq.1 b/upstream/mageia-cauldron/man1/perlfaq.1
new file mode 100644
index 00000000..ae9f50f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq.1
@@ -0,0 +1,780 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ 1"
+.TH PERLFAQ 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq \- Frequently asked questions about Perl
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The perlfaq comprises several documents that answer the most commonly
+asked questions about Perl and Perl programming. It's divided by topic
+into nine major sections outlined in this document.
+.SS "Where to find the perlfaq"
+.IX Subsection "Where to find the perlfaq"
+The perlfaq is an evolving document.  Read the latest version at
+<https://perldoc.perl.org/perlfaq>.  It is also included in the standard Perl
+distribution.
+.SS "How to use the perlfaq"
+.IX Subsection "How to use the perlfaq"
+The \f(CW\*(C`perldoc\*(C'\fR command line tool is part of the standard Perl distribution. To
+read the perlfaq:
+.PP
+.Vb 1
+\&    $ perldoc perlfaq
+.Ve
+.PP
+To search the perlfaq question headings:
+.PP
+.Vb 1
+\&    $ perldoc \-q open
+.Ve
+.SS "How to contribute to the perlfaq"
+.IX Subsection "How to contribute to the perlfaq"
+Review <https://github.com/perl\-doc\-cats/perlfaq/wiki>.  If you don't find
+your suggestion create an issue or pull request against
+<https://github.com/perl\-doc\-cats/perlfaq>.
+.PP
+Once approved, changes will be distributed with the next Perl release and
+subsequently appear at <https://perldoc.perl.org/perlfaq>.
+.SS "What if my question isn't answered in the FAQ?"
+.IX Subsection "What if my question isn't answered in the FAQ?"
+Try the resources in perlfaq2.
+.SH "TABLE OF CONTENTS"
+.IX Header "TABLE OF CONTENTS"
+.IP "perlfaq1 \- General Questions About Perl" 4
+.IX Item "perlfaq1 - General Questions About Perl"
+.PD 0
+.IP "perlfaq2 \- Obtaining and Learning about Perl" 4
+.IX Item "perlfaq2 - Obtaining and Learning about Perl"
+.IP "perlfaq3 \- Programming Tools" 4
+.IX Item "perlfaq3 - Programming Tools"
+.IP "perlfaq4 \- Data Manipulation" 4
+.IX Item "perlfaq4 - Data Manipulation"
+.IP "perlfaq5 \- Files and Formats" 4
+.IX Item "perlfaq5 - Files and Formats"
+.IP "perlfaq6 \- Regular Expressions" 4
+.IX Item "perlfaq6 - Regular Expressions"
+.IP "perlfaq7 \- General Perl Language Issues" 4
+.IX Item "perlfaq7 - General Perl Language Issues"
+.IP "perlfaq8 \- System Interaction" 4
+.IX Item "perlfaq8 - System Interaction"
+.IP "perlfaq9 \- Web, Email and Networking" 4
+.IX Item "perlfaq9 - Web, Email and Networking"
+.PD
+.SH "THE QUESTIONS"
+.IX Header "THE QUESTIONS"
+.SS "perlfaq1: General Questions About Perl"
+.IX Subsection "perlfaq1: General Questions About Perl"
+This section of the FAQ answers very general, high-level questions about Perl.
+.IP \(bu 4
+What is Perl?
+.IP \(bu 4
+Who supports Perl? Who develops it? Why is it free?
+.IP \(bu 4
+Which version of Perl should I use?
+.IP \(bu 4
+What are Perl 4, Perl 5, or Raku (Perl 6)?
+.IP \(bu 4
+What is Raku (Perl 6)?
+.IP \(bu 4
+How stable is Perl?
+.IP \(bu 4
+How often are new versions of Perl released?
+.IP \(bu 4
+Is Perl difficult to learn?
+.IP \(bu 4
+How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
+.IP \(bu 4
+Can I do [task] in Perl?
+.IP \(bu 4
+When shouldn't I program in Perl?
+.IP \(bu 4
+What's the difference between "perl" and "Perl"?
+.IP \(bu 4
+What is a JAPH?
+.IP \(bu 4
+How can I convince others to use Perl?
+.SS "perlfaq2: Obtaining and Learning about Perl"
+.IX Subsection "perlfaq2: Obtaining and Learning about Perl"
+This section of the FAQ answers questions about where to find source and documentation for Perl, support, and related matters.
+.IP \(bu 4
+What machines support Perl? Where do I get it?
+.IP \(bu 4
+How can I get a binary version of Perl?
+.IP \(bu 4
+I don't have a C compiler. How can I build my own Perl interpreter?
+.IP \(bu 4
+I copied the Perl binary from one machine to another, but scripts don't work.
+.IP \(bu 4
+I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
+.IP \(bu 4
+What modules and extensions are available for Perl? What is CPAN?
+.IP \(bu 4
+Where can I get information on Perl?
+.IP \(bu 4
+What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
+.IP \(bu 4
+Where can I post questions?
+.IP \(bu 4
+Perl Books
+.IP \(bu 4
+Which magazines have Perl content?
+.IP \(bu 4
+Which Perl blogs should I read?
+.IP \(bu 4
+What mailing lists are there for Perl?
+.IP \(bu 4
+Where can I buy a commercial version of Perl?
+.IP \(bu 4
+Where do I send bug reports?
+.SS "perlfaq3: Programming Tools"
+.IX Subsection "perlfaq3: Programming Tools"
+This section of the FAQ answers questions related to programmer tools and programming support.
+.IP \(bu 4
+How do I do (anything)?
+.IP \(bu 4
+How can I use Perl interactively?
+.IP \(bu 4
+How do I find which modules are installed on my system?
+.IP \(bu 4
+How do I debug my Perl programs?
+.IP \(bu 4
+How do I profile my Perl programs?
+.IP \(bu 4
+How do I cross-reference my Perl programs?
+.IP \(bu 4
+Is there a pretty-printer (formatter) for Perl?
+.IP \(bu 4
+Is there an IDE or Windows Perl Editor?
+.IP \(bu 4
+Where can I get Perl macros for vi?
+.IP \(bu 4
+Where can I get perl-mode or cperl-mode for emacs?
+.IP \(bu 4
+How can I use curses with Perl?
+.IP \(bu 4
+How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
+.IP \(bu 4
+How can I make my Perl program run faster?
+.IP \(bu 4
+How can I make my Perl program take less memory?
+.IP \(bu 4
+Is it safe to return a reference to local or lexical data?
+.IP \(bu 4
+How can I free an array or hash so my program shrinks?
+.IP \(bu 4
+How can I make my CGI script more efficient?
+.IP \(bu 4
+How can I hide the source for my Perl program?
+.IP \(bu 4
+How can I compile my Perl program into byte code or C?
+.IP \(bu 4
+How can I get \f(CW\*(C`#!perl\*(C'\fR to work on [MS\-DOS,NT,...]?
+.IP \(bu 4
+Can I write useful Perl programs on the command line?
+.IP \(bu 4
+Why don't Perl one-liners work on my DOS/Mac/VMS system?
+.IP \(bu 4
+Where can I learn about CGI or Web programming in Perl?
+.IP \(bu 4
+Where can I learn about object-oriented Perl programming?
+.IP \(bu 4
+Where can I learn about linking C with Perl?
+.IP \(bu 4
+I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
+.IP \(bu 4
+When I tried to run my script, I got this message. What does it mean?
+.IP \(bu 4
+What's MakeMaker?
+.SS "perlfaq4: Data Manipulation"
+.IX Subsection "perlfaq4: Data Manipulation"
+This section of the FAQ answers questions related to manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
+.IP \(bu 4
+Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
+.IP \(bu 4
+Why is \fBint()\fR broken?
+.IP \(bu 4
+Why isn't my octal data interpreted correctly?
+.IP \(bu 4
+Does Perl have a \fBround()\fR function? What about \fBceil()\fR and \fBfloor()\fR? Trig functions?
+.IP \(bu 4
+How do I convert between numeric representations/bases/radixes?
+.IP \(bu 4
+Why doesn't & work the way I want it to?
+.IP \(bu 4
+How do I multiply matrices?
+.IP \(bu 4
+How do I perform an operation on a series of integers?
+.IP \(bu 4
+How can I output Roman numerals?
+.IP \(bu 4
+Why aren't my random numbers random?
+.IP \(bu 4
+How do I get a random number between X and Y?
+.IP \(bu 4
+How do I find the day or week of the year?
+.IP \(bu 4
+How do I find the current century or millennium?
+.IP \(bu 4
+How can I compare two dates and find the difference?
+.IP \(bu 4
+How can I take a string and turn it into epoch seconds?
+.IP \(bu 4
+How can I find the Julian Day?
+.IP \(bu 4
+How do I find yesterday's date?
+.IP \(bu 4
+Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
+.IP \(bu 4
+How do I validate input?
+.IP \(bu 4
+How do I unescape a string?
+.IP \(bu 4
+How do I remove consecutive pairs of characters?
+.IP \(bu 4
+How do I expand function calls in a string?
+.IP \(bu 4
+How do I find matching/nesting anything?
+.IP \(bu 4
+How do I reverse a string?
+.IP \(bu 4
+How do I expand tabs in a string?
+.IP \(bu 4
+How do I reformat a paragraph?
+.IP \(bu 4
+How can I access or change N characters of a string?
+.IP \(bu 4
+How do I change the Nth occurrence of something?
+.IP \(bu 4
+How can I count the number of occurrences of a substring within a string?
+.IP \(bu 4
+How do I capitalize all the words on one line?
+.IP \(bu 4
+How can I split a [character]\-delimited string except when inside [character]?
+.IP \(bu 4
+How do I strip blank space from the beginning/end of a string?
+.IP \(bu 4
+How do I pad a string with blanks or pad a number with zeroes?
+.IP \(bu 4
+How do I extract selected columns from a string?
+.IP \(bu 4
+How do I find the soundex value of a string?
+.IP \(bu 4
+How can I expand variables in text strings?
+.IP \(bu 4
+Does Perl have anything like Ruby's #{} or Python's f string?
+.IP \(bu 4
+What's wrong with always quoting "$vars"?
+.IP \(bu 4
+Why don't my <<HERE documents work?
+.IP \(bu 4
+What is the difference between a list and an array?
+.IP \(bu 4
+What is the difference between \f(CW$array\fR[1] and \f(CW@array\fR[1]?
+.IP \(bu 4
+How can I remove duplicate elements from a list or array?
+.IP \(bu 4
+How can I tell whether a certain element is contained in a list or array?
+.IP \(bu 4
+How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
+.IP \(bu 4
+How do I test whether two arrays or hashes are equal?
+.IP \(bu 4
+How do I find the first array element for which a condition is true?
+.IP \(bu 4
+How do I handle linked lists?
+.IP \(bu 4
+How do I handle circular lists?
+.IP \(bu 4
+How do I shuffle an array randomly?
+.IP \(bu 4
+How do I process/modify each element of an array?
+.IP \(bu 4
+How do I select a random element from an array?
+.IP \(bu 4
+How do I permute N elements of a list?
+.IP \(bu 4
+How do I sort an array by (anything)?
+.IP \(bu 4
+How do I manipulate arrays of bits?
+.IP \(bu 4
+Why does \fBdefined()\fR return true on empty arrays and hashes?
+.IP \(bu 4
+How do I process an entire hash?
+.IP \(bu 4
+How do I merge two hashes?
+.IP \(bu 4
+What happens if I add or remove keys from a hash while iterating over it?
+.IP \(bu 4
+How do I look up a hash element by value?
+.IP \(bu 4
+How can I know how many entries are in a hash?
+.IP \(bu 4
+How do I sort a hash (optionally by value instead of key)?
+.IP \(bu 4
+How can I always keep my hash sorted?
+.IP \(bu 4
+What's the difference between "delete" and "undef" with hashes?
+.IP \(bu 4
+Why don't my tied hashes make the defined/exists distinction?
+.IP \(bu 4
+How do I reset an \fBeach()\fR operation part-way through?
+.IP \(bu 4
+How can I get the unique keys from two hashes?
+.IP \(bu 4
+How can I store a multidimensional array in a DBM file?
+.IP \(bu 4
+How can I make my hash remember the order I put elements into it?
+.IP \(bu 4
+Why does passing a subroutine an undefined element in a hash create it?
+.IP \(bu 4
+How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
+.IP \(bu 4
+How can I use a reference as a hash key?
+.IP \(bu 4
+How can I check if a key exists in a multilevel hash?
+.IP \(bu 4
+How can I prevent addition of unwanted keys into a hash?
+.IP \(bu 4
+How do I handle binary data correctly?
+.IP \(bu 4
+How do I determine whether a scalar is a number/whole/integer/float?
+.IP \(bu 4
+How do I keep persistent data across program calls?
+.IP \(bu 4
+How do I print out or copy a recursive data structure?
+.IP \(bu 4
+How do I define methods for every class/object?
+.IP \(bu 4
+How do I verify a credit card checksum?
+.IP \(bu 4
+How do I pack arrays of doubles or floats for XS code?
+.SS "perlfaq5: Files and Formats"
+.IX Subsection "perlfaq5: Files and Formats"
+This section deals with I/O and the "f" issues: filehandles, flushing, formats, and footers.
+.IP \(bu 4
+How do I flush/unbuffer an output filehandle? Why must I do this?
+.IP \(bu 4
+How do I change, delete, or insert a line in a file, or append to the beginning of a file?
+.IP \(bu 4
+How do I count the number of lines in a file?
+.IP \(bu 4
+How do I delete the last N lines from a file?
+.IP \(bu 4
+How can I use Perl's \f(CW\*(C`\-i\*(C'\fR option from within a program?
+.IP \(bu 4
+How can I copy a file?
+.IP \(bu 4
+How do I make a temporary file name?
+.IP \(bu 4
+How can I manipulate fixed-record-length files?
+.IP \(bu 4
+How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
+.IP \(bu 4
+How can I use a filehandle indirectly?
+.IP \(bu 4
+How can I open a filehandle to a string?
+.IP \(bu 4
+How can I set up a footer format to be used with \fBwrite()\fR?
+.IP \(bu 4
+How can I \fBwrite()\fR into a string?
+.IP \(bu 4
+How can I output my numbers with commas added?
+.IP \(bu 4
+How can I translate tildes (~) in a filename?
+.IP \(bu 4
+How come when I open a file read-write it wipes it out?
+.IP \(bu 4
+Why do I sometimes get an "Argument list too long" when I use <*>?
+.IP \(bu 4
+How can I open a file named with a leading ">" or trailing blanks?
+.IP \(bu 4
+How can I reliably rename a file?
+.IP \(bu 4
+How can I lock a file?
+.IP \(bu 4
+Why can't I just open(FH, ">file.lock")?
+.IP \(bu 4
+I still don't get locking. I just want to increment the number in the file. How can I do this?
+.IP \(bu 4
+All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
+.IP \(bu 4
+How do I randomly update a binary file?
+.IP \(bu 4
+How do I get a file's timestamp in perl?
+.IP \(bu 4
+How do I set a file's timestamp in perl?
+.IP \(bu 4
+How do I print to more than one file at once?
+.IP \(bu 4
+How can I read in an entire file all at once?
+.IP \(bu 4
+How can I read in a file by paragraphs?
+.IP \(bu 4
+How can I read a single character from a file? From the keyboard?
+.IP \(bu 4
+How can I tell whether there's a character waiting on a filehandle?
+.IP \(bu 4
+How do I do a \f(CW\*(C`tail \-f\*(C'\fR in perl?
+.IP \(bu 4
+How do I \fBdup()\fR a filehandle in Perl?
+.IP \(bu 4
+How do I close a file descriptor by number?
+.IP \(bu 4
+Why can't I use "C:\etemp\efoo" in DOS paths? Why doesn't `C:\etemp\efoo.exe` work?
+.IP \(bu 4
+Why doesn't glob("*.*") get all the files?
+.IP \(bu 4
+Why does Perl let me delete read-only files? Why does \f(CW\*(C`\-i\*(C'\fR clobber protected files? Isn't this a bug in Perl?
+.IP \(bu 4
+How do I select a random line from a file?
+.IP \(bu 4
+Why do I get weird spaces when I print an array of lines?
+.IP \(bu 4
+How do I traverse a directory tree?
+.IP \(bu 4
+How do I delete a directory tree?
+.IP \(bu 4
+How do I copy an entire directory?
+.SS "perlfaq6: Regular Expressions"
+.IX Subsection "perlfaq6: Regular Expressions"
+This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number can be handled with regular expressions, but those answers are found elsewhere in this document (in perlfaq9 : "How do I decode or create those %\-encodings on the web" and perlfaq4 : "How do I determine whether a scalar is a number/whole/integer/float", to be precise).
+.IP \(bu 4
+How can I hope to use regular expressions without creating illegible and unmaintainable code?
+.IP \(bu 4
+I'm having trouble matching over more than one line. What's wrong?
+.IP \(bu 4
+How can I pull out lines between two patterns that are themselves on different lines?
+.IP \(bu 4
+How do I match XML, HTML, or other nasty, ugly things with a regex?
+.IP \(bu 4
+I put a regular expression into $/ but it didn't work. What's wrong?
+.IP \(bu 4
+How do I substitute case-insensitively on the LHS while preserving case on the RHS?
+.IP \(bu 4
+How can I make \f(CW\*(C`\ew\*(C'\fR match national character sets?
+.IP \(bu 4
+How can I match a locale-smart version of \f(CW\*(C`/[a\-zA\-Z]/\*(C'\fR ?
+.IP \(bu 4
+How can I quote a variable to use in a regex?
+.IP \(bu 4
+What is \f(CW\*(C`/o\*(C'\fR really for?
+.IP \(bu 4
+How do I use a regular expression to strip C\-style comments from a file?
+.IP \(bu 4
+Can I use Perl regular expressions to match balanced text?
+.IP \(bu 4
+What does it mean that regexes are greedy? How can I get around it?
+.IP \(bu 4
+How do I process each word on each line?
+.IP \(bu 4
+How can I print out a word-frequency or line-frequency summary?
+.IP \(bu 4
+How can I do approximate matching?
+.IP \(bu 4
+How do I efficiently match many regular expressions at once?
+.IP \(bu 4
+Why don't word-boundary searches with \f(CW\*(C`\eb\*(C'\fR work for me?
+.IP \(bu 4
+Why does using $&, $`, or $' slow my program down?
+.IP \(bu 4
+What good is \f(CW\*(C`\eG\*(C'\fR in a regular expression?
+.IP \(bu 4
+Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
+.IP \(bu 4
+What's wrong with using grep in a void context?
+.IP \(bu 4
+How can I match strings with multibyte characters?
+.IP \(bu 4
+How do I match a regular expression that's in a variable?
+.SS "perlfaq7: General Perl Language Issues"
+.IX Subsection "perlfaq7: General Perl Language Issues"
+This section deals with general Perl language issues that don't clearly fit into any of the other sections.
+.IP \(bu 4
+Can I get a BNF/yacc/RE for the Perl language?
+.IP \(bu 4
+What are all these $@%&* punctuation signs, and how do I know when to use them?
+.IP \(bu 4
+Do I always/never have to quote my strings or use semicolons and commas?
+.IP \(bu 4
+How do I skip some return values?
+.IP \(bu 4
+How do I temporarily block warnings?
+.IP \(bu 4
+What's an extension?
+.IP \(bu 4
+Why do Perl operators have different precedence than C operators?
+.IP \(bu 4
+How do I declare/create a structure?
+.IP \(bu 4
+How do I create a module?
+.IP \(bu 4
+How do I adopt or take over a module already on CPAN?
+.IP \(bu 4
+How do I create a class?
+.IP \(bu 4
+How can I tell if a variable is tainted?
+.IP \(bu 4
+What's a closure?
+.IP \(bu 4
+What is variable suicide and how can I prevent it?
+.IP \(bu 4
+How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
+.IP \(bu 4
+How do I create a static variable?
+.IP \(bu 4
+What's the difference between dynamic and lexical (static) scoping? Between \fBlocal()\fR and \fBmy()\fR?
+.IP \(bu 4
+How can I access a dynamic variable while a similarly named lexical is in scope?
+.IP \(bu 4
+What's the difference between deep and shallow binding?
+.IP \(bu 4
+Why doesn't "my($foo) = <$fh>;" work right?
+.IP \(bu 4
+How do I redefine a builtin function, operator, or method?
+.IP \(bu 4
+What's the difference between calling a function as &foo and \fBfoo()\fR?
+.IP \(bu 4
+How do I create a switch or case statement?
+.IP \(bu 4
+How can I catch accesses to undefined variables, functions, or methods?
+.IP \(bu 4
+Why can't a method included in this same file be found?
+.IP \(bu 4
+How can I find out my current or calling package?
+.IP \(bu 4
+How can I comment out a large block of Perl code?
+.IP \(bu 4
+How do I clear a package?
+.IP \(bu 4
+How can I use a variable as a variable name?
+.IP \(bu 4
+What does "bad interpreter" mean?
+.IP \(bu 4
+Do I need to recompile XS modules when there is a change in the C library?
+.SS "perlfaq8: System Interaction"
+.IX Subsection "perlfaq8: System Interaction"
+This section of the Perl FAQ covers questions involving operating system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation.
+.IP \(bu 4
+How do I find out which operating system I'm running under?
+.IP \(bu 4
+How come \fBexec()\fR doesn't return?
+.IP \(bu 4
+How do I do fancy stuff with the keyboard/screen/mouse?
+.IP \(bu 4
+How do I print something out in color?
+.IP \(bu 4
+How do I read just one key without waiting for a return key?
+.IP \(bu 4
+How do I check whether input is ready on the keyboard?
+.IP \(bu 4
+How do I clear the screen?
+.IP \(bu 4
+How do I get the screen size?
+.IP \(bu 4
+How do I ask the user for a password?
+.IP \(bu 4
+How do I read and write the serial port?
+.IP \(bu 4
+How do I decode encrypted password files?
+.IP \(bu 4
+How do I start a process in the background?
+.IP \(bu 4
+How do I trap control characters/signals?
+.IP \(bu 4
+How do I modify the shadow password file on a Unix system?
+.IP \(bu 4
+How do I set the time and date?
+.IP \(bu 4
+How can I \fBsleep()\fR or \fBalarm()\fR for under a second?
+.IP \(bu 4
+How can I measure time under a second?
+.IP \(bu 4
+How can I do an \fBatexit()\fR or \fBsetjmp()\fR/\fBlongjmp()\fR? (Exception handling)
+.IP \(bu 4
+Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
+.IP \(bu 4
+How can I call my system's unique C functions from Perl?
+.IP \(bu 4
+Where do I get the include files to do \fBioctl()\fR or \fBsyscall()\fR?
+.IP \(bu 4
+Why do setuid perl scripts complain about kernel problems?
+.IP \(bu 4
+How can I open a pipe both to and from a command?
+.IP \(bu 4
+Why can't I get the output of a command with \fBsystem()\fR?
+.IP \(bu 4
+How can I capture STDERR from an external command?
+.IP \(bu 4
+Why doesn't \fBopen()\fR return an error when a pipe open fails?
+.IP \(bu 4
+What's wrong with using backticks in a void context?
+.IP \(bu 4
+How can I call backticks without shell processing?
+.IP \(bu 4
+Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
+.IP \(bu 4
+How can I convert my shell script to perl?
+.IP \(bu 4
+Can I use perl to run a telnet or ftp session?
+.IP \(bu 4
+How can I write expect in Perl?
+.IP \(bu 4
+Is there a way to hide perl's command line from programs such as "ps"?
+.IP \(bu 4
+I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?
+.IP \(bu 4
+How do I close a process's filehandle without waiting for it to complete?
+.IP \(bu 4
+How do I fork a daemon process?
+.IP \(bu 4
+How do I find out if I'm running interactively or not?
+.IP \(bu 4
+How do I timeout a slow event?
+.IP \(bu 4
+How do I set CPU limits?
+.IP \(bu 4
+How do I avoid zombies on a Unix system?
+.IP \(bu 4
+How do I use an SQL database?
+.IP \(bu 4
+How do I make a \fBsystem()\fR exit on control-C?
+.IP \(bu 4
+How do I open a file without blocking?
+.IP \(bu 4
+How do I tell the difference between errors from the shell and perl?
+.IP \(bu 4
+How do I install a module from CPAN?
+.IP \(bu 4
+What's the difference between require and use?
+.IP \(bu 4
+How do I keep my own module/library directory?
+.IP \(bu 4
+How do I add the directory my program lives in to the module/library search path?
+.IP \(bu 4
+How do I add a directory to my include path (@INC) at runtime?
+.IP \(bu 4
+Where are modules installed?
+.IP \(bu 4
+What is socket.ph and where do I get it?
+.SS "perlfaq9: Web, Email and Networking"
+.IX Subsection "perlfaq9: Web, Email and Networking"
+This section deals with questions related to running web sites, sending and receiving email as well as general networking.
+.IP \(bu 4
+Should I use a web framework?
+.IP \(bu 4
+Which web framework should I use?
+.IP \(bu 4
+What is Plack and PSGI?
+.IP \(bu 4
+How do I remove HTML from a string?
+.IP \(bu 4
+How do I extract URLs?
+.IP \(bu 4
+How do I fetch an HTML file?
+.IP \(bu 4
+How do I automate an HTML form submission?
+.IP \(bu 4
+How do I decode or create those %\-encodings on the web?
+.IP \(bu 4
+How do I redirect to another page?
+.IP \(bu 4
+How do I put a password on my web pages?
+.IP \(bu 4
+How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
+.IP \(bu 4
+How do I parse a mail header?
+.IP \(bu 4
+How do I check a valid mail address?
+.IP \(bu 4
+How do I decode a MIME/BASE64 string?
+.IP \(bu 4
+How do I find the user's mail address?
+.IP \(bu 4
+How do I send email?
+.IP \(bu 4
+How do I use MIME to make an attachment to a mail message?
+.IP \(bu 4
+How do I read email?
+.IP \(bu 4
+How do I find out my hostname, domainname, or IP address?
+.IP \(bu 4
+How do I fetch/put an (S)FTP file?
+.IP \(bu 4
+How can I do RPC in Perl?
+.SH CREDITS
+.IX Header "CREDITS"
+Tom Christiansen wrote the original perlfaq then expanded it with the
+help of Nat Torkington. brian d foy substantially edited and expanded
+the perlfaq. perlfaq-workers and others have also supplied feedback,
+patches and corrections over the years.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Tom Christiansen wrote the original version of this document.
+brian d foy \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR wrote this version. See the
+individual perlfaq documents for additional copyright information.
+.PP
+This document is available under the same terms as Perl itself. Code
+examples in all the perlfaq documents are in the public domain. Use
+them as you see fit (and at your own risk with no warranty from anyone).
diff --git a/upstream/mageia-cauldron/man1/perlfaq1.1 b/upstream/mageia-cauldron/man1/perlfaq1.1
new file mode 100644
index 00000000..ef17efea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq1.1
@@ -0,0 +1,371 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ1 1"
+.TH PERLFAQ1 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq1 \- General Questions About Perl
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section of the FAQ answers very general, high-level questions
+about Perl.
+.SS "What is Perl?"
+.IX Subsection "What is Perl?"
+Perl is a high-level programming language with an eclectic heritage
+written by Larry Wall and a cast of thousands.
+.PP
+Perl's process, file, and text manipulation facilities make it
+particularly well-suited for tasks involving quick prototyping, system
+utilities, software tools, system management tasks, database access,
+graphical programming, networking, and web programming.
+.PP
+Perl derives from the ubiquitous C programming language and to a
+lesser extent from sed, awk, the Unix shell, and many other tools
+and languages.
+.PP
+These strengths make it especially popular with web developers
+and system administrators. Mathematicians, geneticists, journalists,
+managers and many other people also use Perl.
+.SS "Who supports Perl? Who develops it? Why is it free?"
+.IX Subsection "Who supports Perl? Who develops it? Why is it free?"
+The original culture of the pre-populist Internet and the deeply-held
+beliefs of Perl's author, Larry Wall, gave rise to the free and open
+distribution policy of Perl. Perl is supported by its users. The
+core, the standard Perl library, the optional modules, and the
+documentation you're reading now were all written by volunteers.
+.PP
+The core development team (known as the Perl Porters)
+are a group of highly altruistic individuals committed to
+producing better software for free than you could hope to purchase for
+money. You may snoop on pending developments via the
+archives <http://www.nntp.perl.org/group/perl.perl5.porters/>
+or you can subscribe to the mailing list by sending
+perl5\-porters\-subscribe@perl.org a subscription request
+(an empty message with no subject is fine).
+.PP
+While the GNU project includes Perl in its distributions, there's no
+such thing as "GNU Perl". Perl is not produced nor maintained by the
+Free Software Foundation. Perl's licensing terms are also more open
+than GNU software's tend to be.
+.PP
+You can get commercial support of Perl if you wish, although for most
+users the informal support will more than suffice. See the answer to
+"Where can I buy a commercial version of Perl?" for more information.
+.SS "Which version of Perl should I use?"
+.IX Subsection "Which version of Perl should I use?"
+(contributed by brian d foy with updates from others)
+.PP
+There is often a matter of opinion and taste, and there isn't any one
+answer that fits everyone. In general, you want to use either the current
+stable release, or the stable release immediately prior to that one.
+.PP
+Beyond that, you have to consider several things and decide which is best
+for you.
+.IP \(bu 4
+If things aren't broken, upgrading perl may break them (or at least issue
+new warnings).
+.IP \(bu 4
+The latest versions of perl have more bug fixes.
+.IP \(bu 4
+The latest versions of perl may contain performance improvements and
+features not present in older versions.  There have been many changes
+in perl since perl5 was first introduced.
+.IP \(bu 4
+The Perl community is geared toward supporting the most recent releases,
+so you'll have an easier time finding help for those.
+.IP \(bu 4
+Older versions of perl may have security vulnerabilities, some of which
+are serious (see perlsec and search
+CVEs <https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=Perl> for more
+information).
+.IP \(bu 4
+The latest versions are probably the least deployed and widely tested, so
+you may want to wait a few months after their release and see what
+problems others have if you are risk averse.
+.IP \(bu 4
+The immediate, in addition to the current stable release, the previous
+stable release is maintained.  See
+"MAINTENANCE AND SUPPORT" in perlpolicy for more information.
+.IP \(bu 4
+There are really two tracks of perl development: a maintenance version
+and an experimental version. The maintenance versions are stable, and
+have an even number as the minor release (i.e. perl5.24.x, where 24 is the
+minor release). The experimental versions may include features that
+don't make it into the stable versions, and have an odd number as the
+minor release (i.e. perl5.25.x, where 25 is the minor release).
+.IP \(bu 4
+You can consult releases <http://dev.perl.org/perl5> to determine the
+current stable release of Perl.
+.SS "What are Perl 4, Perl 5, or Raku (Perl 6)?"
+.IX Subsection "What are Perl 4, Perl 5, or Raku (Perl 6)?"
+In short, Perl 4 is the parent to both Perl 5 and Raku (formerly known as
+Perl 6). Perl 5 is the older sibling, and though they are different languages,
+someone who knows one will spot many similarities in the other.
+.PP
+The number after Perl (i.e. the 5 after Perl 5) is the major release
+of the perl interpreter as well as the version of the language. Each
+major version has significant differences that earlier versions cannot
+support.
+.PP
+The current major release of Perl is Perl 5, first released in
+1994. It can run scripts from the previous major release, Perl 4
+(March 1991), but has significant differences.
+.PP
+Raku is a reinvention of Perl, a language in the same lineage but
+not compatible. The two are complementary, not mutually exclusive. Raku is
+not meant to replace Perl, and vice versa. See "What is Raku (Perl 6)?"
+below to find out more.
+.PP
+See perlhist for a history of Perl revisions.
+.SS "What is Raku (Perl 6)?"
+.IX Subsection "What is Raku (Perl 6)?"
+Raku (formerly known as Perl 6) was \fIoriginally\fR described as the community's
+rewrite of Perl, however as the language evolved, it became clear that it is
+a separate language, but in the same language family as Perl.
+.PP
+Raku is not intended primarily as a replacement for Perl, but as its
+own thing \- and libraries exist to allow you to call Perl code from Raku
+programs and vice versa.
+.PP
+Contrary to popular belief, Raku and Perl peacefully coexist with one
+another. Raku has proven to be a fascinating source of ideas for those
+using Perl (the Moose object system is a well-known example). There is
+overlap in the communities, and this overlap fosters the tradition of sharing
+and borrowing that have been instrumental to Perl's success.
+.PP
+For more about Raku see <https://www.raku.org/>.
+.PP
+"We're really serious about reinventing everything that needs reinventing."
+\&\-\-Larry Wall
+.SS "How stable is Perl?"
+.IX Subsection "How stable is Perl?"
+Production releases, which incorporate bug fixes and new functionality,
+are widely tested before release. Since the 5.000 release, we have
+averaged about one production release per year.
+.PP
+The Perl development team occasionally make changes to the
+internal core of the language, but all possible efforts are made toward
+backward compatibility.
+.SS "How often are new versions of Perl released?"
+.IX Subsection "How often are new versions of Perl released?"
+Recently, the plan has been to release a new version of Perl roughly every
+April, but getting the release right is more important than sticking rigidly to
+a calendar date, so the release date is somewhat flexible.  The historical
+release dates can be viewed at <http://www.cpan.org/src/README.html>.
+.PP
+Even numbered minor versions (5.14, 5.16, 5.18) are production versions, and
+odd numbered minor versions (5.15, 5.17, 5.19) are development versions. Unless
+you want to try out an experimental feature, you probably never want to install
+a development version of Perl.
+.PP
+The Perl development team are called Perl 5 Porters, and their
+organization is described at <http://perldoc.perl.org/perlpolicy.html>.
+The organizational rules really just boil down to one: Larry is always
+right, even when he was wrong.
+.SS "Is Perl difficult to learn?"
+.IX Subsection "Is Perl difficult to learn?"
+No, Perl is easy to start learning <http://learn.perl.org/> \-\-and easy to keep learning. It looks
+like most programming languages you're likely to have experience
+with, so if you've ever written a C program, an awk script, a shell
+script, or even a BASIC program, you're already partway there.
+.PP
+Most tasks only require a small subset of the Perl language. One of
+the guiding mottos for Perl development is "there's more than one way
+to do it" (TMTOWTDI, sometimes pronounced "tim toady"). Perl's
+learning curve is therefore shallow (easy to learn) and long (there's
+a whole lot you can do if you really want).
+.PP
+Finally, because Perl is frequently (but not always, and certainly not by
+definition) an interpreted language, you can write your programs and test
+them without an intermediate compilation step, allowing you to experiment
+and test/debug quickly and easily. This ease of experimentation flattens
+the learning curve even more.
+.PP
+Things that make Perl easier to learn: Unix experience, almost any kind
+of programming experience, an understanding of regular expressions, and
+the ability to understand other people's code. If there's something you
+need to do, then it's probably already been done, and a working example is
+usually available for free. Don't forget Perl modules, either.
+They're discussed in Part 3 of this FAQ, along with CPAN <http://www.cpan.org/>, which is
+discussed in Part 2.
+.SS "How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?"
+.IX Subsection "How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?"
+Perl can be used for almost any coding problem, even ones which require
+integrating specialist C code for extra speed. As with any tool it can
+be used well or badly. Perl has many strengths, and a few weaknesses,
+precisely which areas are good and bad is often a personal choice.
+.PP
+When choosing a language you should also be influenced by the
+resources <http://www.cpan.org/>, testing culture <http://www.cpantesters.org/>
+and community <http://www.perl.org/community.html> which surrounds it.
+.PP
+For comparisons to a specific language it is often best to create
+a small project in both languages and compare the results, make sure
+to use all the resources <http://www.cpan.org/> of each language,
+as a language is far more than just it's syntax.
+.SS "Can I do [task] in Perl?"
+.IX Subsection "Can I do [task] in Perl?"
+Perl is flexible and extensible enough for you to use on virtually any
+task, from one-line file-processing tasks to large, elaborate systems.
+.PP
+For many people, Perl serves as a great replacement for shell scripting.
+For others, it serves as a convenient, high-level replacement for most of
+what they'd program in low-level languages like C or C++. It's ultimately
+up to you (and possibly your management) which tasks you'll use Perl
+for and which you won't.
+.PP
+If you have a library that provides an API, you can make any component
+of it available as just another Perl function or variable using a Perl
+extension written in C or C++ and dynamically linked into your main
+perl interpreter. You can also go the other direction, and write your
+main program in C or C++, and then link in some Perl code on the fly,
+to create a powerful application. See perlembed.
+.PP
+That said, there will always be small, focused, special-purpose
+languages dedicated to a specific problem domain that are simply more
+convenient for certain kinds of problems. Perl tries to be all things
+to all people, but nothing special to anyone. Examples of specialized
+languages that come to mind include prolog and matlab.
+.SS "When shouldn't I program in Perl?"
+.IX Subsection "When shouldn't I program in Perl?"
+One good reason is when you already have an existing
+application written in another language that's all done (and done
+well), or you have an application language specifically designed for a
+certain task (e.g. prolog, make).
+.PP
+If you find that you need to speed up a specific part of a Perl
+application (not something you often need) you may want to use C,
+but you can access this from your Perl code with perlxs.
+.SS "What's the difference between ""perl"" and ""Perl""?"
+.IX Subsection "What's the difference between ""perl"" and ""Perl""?"
+"Perl" is the name of the language. Only the "P" is capitalized.
+The name of the interpreter (the program which runs the Perl script)
+is "perl" with a lowercase "p".
+.PP
+You may or may not choose to follow this usage. But never write "PERL",
+because perl is not an acronym.
+.SS "What is a JAPH?"
+.IX Subsection "What is a JAPH?"
+(contributed by brian d foy)
+.PP
+JAPH stands for "Just another Perl hacker,", which Randal Schwartz used
+to sign email and usenet messages starting in the late 1980s. He
+previously used the phrase with many subjects ("Just another x hacker,"),
+so to distinguish his JAPH, he started to write them as Perl programs:
+.PP
+.Vb 1
+\&    print "Just another Perl hacker,";
+.Ve
+.PP
+Other people picked up on this and started to write clever or obfuscated
+programs to produce the same output, spinning things quickly out of
+control while still providing hours of amusement for their creators and
+readers.
+.PP
+CPAN has several JAPH programs at <http://www.cpan.org/misc/japh>.
+.SS "How can I convince others to use Perl?"
+.IX Subsection "How can I convince others to use Perl?"
+(contributed by brian d foy)
+.PP
+Appeal to their self interest! If Perl is new (and thus scary) to them,
+find something that Perl can do to solve one of their problems. That
+might mean that Perl either saves them something (time, headaches, money)
+or gives them something (flexibility, power, testability).
+.PP
+In general, the benefit of a language is closely related to the skill of
+the people using that language. If you or your team can be faster,
+better, and stronger through Perl, you'll deliver more value. Remember,
+people often respond better to what they get out of it. If you run
+into resistance, figure out what those people get out of the other
+choice and how Perl might satisfy that requirement.
+.PP
+You don't have to worry about finding or paying for Perl; it's freely
+available and several popular operating systems come with Perl. Community
+support in places such as Perlmonks ( <http://www.perlmonks.com> )
+and the various Perl mailing lists ( <http://lists.perl.org> ) means that
+you can usually get quick answers to your problems.
+.PP
+Finally, keep in mind that Perl might not be the right tool for every
+job. You're a much better advocate if your claims are reasonable and
+grounded in reality. Dogmatically advocating anything tends to make
+people discount your message. Be honest about possible disadvantages
+to your choice of Perl since any choice has trade-offs.
+.PP
+You might find these links useful:
+.IP \(bu 4
+<http://www.perl.org/about.html>
+.IP \(bu 4
+<http://perltraining.com.au/whyperl.html>
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples here are in the public
+domain. You are permitted and encouraged to use this code and any
+derivatives thereof in your own programs for fun or for profit as you
+see fit. A simple comment in the code giving credit to the FAQ would
+be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq2.1 b/upstream/mageia-cauldron/man1/perlfaq2.1
new file mode 100644
index 00000000..a941372e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq2.1
@@ -0,0 +1,288 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ2 1"
+.TH PERLFAQ2 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq2 \- Obtaining and Learning about Perl
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section of the FAQ answers questions about where to find
+source and documentation for Perl, support, and
+related matters.
+.SS "What machines support Perl? Where do I get it?"
+.IX Subsection "What machines support Perl? Where do I get it?"
+The standard release of Perl (the one maintained by the Perl
+development team) is distributed only in source code form. You
+can find the latest releases at <http://www.cpan.org/src/>.
+.PP
+Perl builds and runs on a bewildering number of platforms. Virtually
+all known and current Unix derivatives are supported (perl's native
+platform), as are other systems like VMS, DOS, OS/2, Windows,
+QNX, BeOS, OS X, MPE/iX and the Amiga.
+.PP
+Binary distributions for some proprietary platforms can be found
+<http://www.cpan.org/ports/> directory. Because these are not part of
+the standard distribution, they may and in fact do differ from the
+base perl port in a variety of ways. You'll have to check their
+respective release notes to see just what the differences are. These
+differences can be either positive (e.g. extensions for the features
+of the particular platform that are not supported in the source
+release of perl) or negative (e.g. might be based upon a less current
+source release of perl).
+.SS "How can I get a binary version of Perl?"
+.IX Subsection "How can I get a binary version of Perl?"
+See CPAN Ports <http://www.cpan.org/ports/>
+.SS "I don't have a C compiler. How can I build my own Perl interpreter?"
+.IX Subsection "I don't have a C compiler. How can I build my own Perl interpreter?"
+For Windows, use a binary version of Perl,
+Strawberry Perl <http://strawberryperl.com/> and
+ActivePerl <http://www.activestate.com/activeperl> come with a
+bundled C compiler.
+.PP
+Otherwise if you really do want to build Perl, you need to get a
+binary version of \f(CW\*(C`gcc\*(C'\fR for your system first. Use a search
+engine to find out how to do this for your operating system.
+.SS "I copied the Perl binary from one machine to another, but scripts don't work."
+.IX Subsection "I copied the Perl binary from one machine to another, but scripts don't work."
+That's probably because you forgot libraries, or library paths differ.
+You really should build the whole distribution on the machine it will
+eventually live on, and then type \f(CW\*(C`make install\*(C'\fR. Most other
+approaches are doomed to failure.
+.PP
+One simple way to check that things are in the right place is to print out
+the hard-coded \f(CW@INC\fR that perl looks through for libraries:
+.PP
+.Vb 1
+\&    % perl \-le \*(Aqprint for @INC\*(Aq
+.Ve
+.PP
+If this command lists any paths that don't exist on your system, then you
+may need to move the appropriate libraries to these locations, or create
+symbolic links, aliases, or shortcuts appropriately. \f(CW@INC\fR is also printed as
+part of the output of
+.PP
+.Vb 1
+\&    % perl \-V
+.Ve
+.PP
+You might also want to check out
+"How do I keep my own module/library directory?" in perlfaq8.
+.SS "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?"
+.IX Subsection "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?"
+Read the \fIINSTALL\fR file, which is part of the source distribution.
+It describes in detail how to cope with most idiosyncrasies that the
+\&\f(CW\*(C`Configure\*(C'\fR script can't work around for any given system or
+architecture.
+.SS "What modules and extensions are available for Perl? What is CPAN?"
+.IX Subsection "What modules and extensions are available for Perl? What is CPAN?"
+CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte
+archive replicated on hundreds of machines all over the world. CPAN
+contains tens of thousands of modules and extensions, source code
+and documentation, designed for \fIeverything\fR from commercial
+database interfaces to keyboard/screen control and running large web sites.
+.PP
+You can search CPAN on <http://metacpan.org>.
+.PP
+The master web site for CPAN is <http://www.cpan.org/>,
+<http://www.cpan.org/SITES.html> lists all mirrors.
+.PP
+See the CPAN FAQ at <http://www.cpan.org/misc/cpan\-faq.html> for answers
+to the most frequently asked questions about CPAN.
+.PP
+The Task::Kensho module has a list of recommended modules which
+you should review as a good starting point.
+.SS "Where can I get information on Perl?"
+.IX Subsection "Where can I get information on Perl?"
+.IP \(bu 4
+<http://www.perl.org/>
+.IP \(bu 4
+<http://perldoc.perl.org/>
+.IP \(bu 4
+<http://learn.perl.org/>
+.PP
+The complete Perl documentation is available with the Perl distribution.
+If you have Perl installed locally, you probably have the documentation
+installed as well: type \f(CW\*(C`perldoc perl\*(C'\fR in a terminal or
+view online <http://perldoc.perl.org/perl.html>.
+.PP
+(Some operating system distributions may ship the documentation in a different
+package; for instance, on Debian, you need to install the \f(CW\*(C`perl\-doc\*(C'\fR package.)
+.PP
+Many good books have been written about Perl\-\-see the section later in
+perlfaq2 for more details.
+.SS "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?"
+.IX Subsection "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?"
+Perl.com <http://www.perl.com/> used to be part of the O'Reilly
+Network, a subsidiary of O'Reilly Media. Although it retains most of
+the original content from its O'Reilly Network, it is now hosted by
+The Perl Foundation <http://www.perlfoundation.org/>.
+.PP
+The Perl Foundation is an advocacy organization for the Perl language
+which maintains the web site <http://www.perl.org/> as a general
+advocacy site for the Perl language. It uses the domain to provide
+general support services to the Perl community, including the hosting
+of mailing lists, web sites, and other services. There are also many
+other sub-domains for special topics like learning Perl and jobs in Perl,
+such as:
+.IP \(bu 4
+<http://www.perl.org/>
+.IP \(bu 4
+<http://learn.perl.org/>
+.IP \(bu 4
+<http://jobs.perl.org/>
+.IP \(bu 4
+<http://lists.perl.org/>
+.PP
+Perl Mongers <http://www.pm.org/> uses the pm.org domain for services
+related to local Perl user groups, including the hosting of mailing lists
+and web sites. See the Perl Mongers web site <http://www.pm.org/> for more
+information about joining, starting, or requesting services for a
+Perl user group.
+.PP
+CPAN, or the Comprehensive Perl Archive Network <http://www.cpan.org/>,
+is a replicated, worldwide repository of Perl software.
+See What is CPAN?.
+.SS "Where can I post questions?"
+.IX Subsection "Where can I post questions?"
+There are many Perl mailing lists for various
+topics, specifically the beginners list <http://lists.perl.org/list/beginners.html>
+may be of use.
+.PP
+Other places to ask questions are on the
+PerlMonks site <http://www.perlmonks.org/> or
+stackoverflow <http://stackoverflow.com/questions/tagged/perl>.
+.SS "Perl Books"
+.IX Subsection "Perl Books"
+There are many good books on Perl <http://www.perl.org/books/library.html>.
+.SS "Which magazines have Perl content?"
+.IX Subsection "Which magazines have Perl content?"
+There's also \fR\f(CI$foo\fR\fI Magazin\fR, a German magazine dedicated to Perl, at
+( <http://www.foo\-magazin.de> ). The \fIPerl-Zeitung\fR is another
+German-speaking magazine for Perl beginners (see
+<http://perl\-zeitung.at.tf> ).
+.PP
+Several Unix/Linux related magazines frequently include articles on Perl.
+.SS "Which Perl blogs should I read?"
+.IX Subsection "Which Perl blogs should I read?"
+Perl News <http://perlnews.org/> covers some of the major events in the Perl
+world, Perl Weekly <http://perlweekly.com/> is a weekly e\-mail
+(and RSS feed) of hand-picked Perl articles.
+.PP
+<http://blogs.perl.org/> hosts many Perl blogs, there are also
+several blog aggregators: Perlsphere <http://perlsphere.net/> and
+IronMan <http://ironman.enlightenedperl.org/> are two of them.
+.SS "What mailing lists are there for Perl?"
+.IX Subsection "What mailing lists are there for Perl?"
+A comprehensive list of Perl-related mailing lists can be found at
+<http://lists.perl.org/>
+.SS "Where can I buy a commercial version of Perl?"
+.IX Subsection "Where can I buy a commercial version of Perl?"
+Perl already \fIis\fR commercial software: it has a license
+that you can grab and carefully read to your manager. It is distributed
+in releases and comes in well-defined packages. There is a very large
+and supportive user community and an extensive literature.
+.PP
+If you still need commercial support
+ActiveState <http://www.activestate.com/activeperl> offers
+this.
+.SS "Where do I send bug reports?"
+.IX Subsection "Where do I send bug reports?"
+(contributed by brian d foy)
+.PP
+First, ensure that you've found an actual bug. Second, ensure you've
+found an actual bug.
+.PP
+If you've found a bug with the perl interpreter or one of the modules
+in the standard library (those that come with Perl), you can submit a
+bug report to the GitHub issue tracker at
+<https://github.com/Perl/perl5/issues>.
+.PP
+To determine if a module came with your version of Perl, you can
+install and use the Module::CoreList module. It has the information
+about the modules (with their versions) included with each release
+of Perl.
+.PP
+Every CPAN module has a bug tracker set up in RT, <http://rt.cpan.org>.
+You can submit bugs to RT either through its web interface or by
+email. To email a bug report, send it to
+bug\-<distribution\-name>@rt.cpan.org . For example, if you
+wanted to report a bug in Business::ISBN, you could send a message to
+bug\-Business\-ISBN@rt.cpan.org .
+.PP
+Some modules might have special reporting requirements, such as a
+GitHub or Google Code tracking system, so you should check the
+module documentation too.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples here are in the public
+domain. You are permitted and encouraged to use this code and any
+derivatives thereof in your own programs for fun or for profit as you
+see fit. A simple comment in the code giving credit to the FAQ would
+be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq3.1 b/upstream/mageia-cauldron/man1/perlfaq3.1
new file mode 100644
index 00000000..c7c2b7aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq3.1
@@ -0,0 +1,1161 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ3 1"
+.TH PERLFAQ3 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq3 \- Programming Tools
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section of the FAQ answers questions related to programmer tools
+and programming support.
+.SS "How do I do (anything)?"
+.IX Subsection "How do I do (anything)?"
+Have you looked at CPAN (see perlfaq2)? The chances are that
+someone has already written a module that can solve your problem.
+Have you read the appropriate manpages? Here's a brief index:
+.IP Basics 4
+.IX Item "Basics"
+.RS 4
+.PD 0
+.IP "perldata \- Perl data types" 4
+.IX Item "perldata - Perl data types"
+.IP "perlvar \- Perl pre-defined variables" 4
+.IX Item "perlvar - Perl pre-defined variables"
+.IP "perlsyn \- Perl syntax" 4
+.IX Item "perlsyn - Perl syntax"
+.IP "perlop \- Perl operators and precedence" 4
+.IX Item "perlop - Perl operators and precedence"
+.IP "perlsub \- Perl subroutines" 4
+.IX Item "perlsub - Perl subroutines"
+.RE
+.RS 4
+.RE
+.IP Execution 4
+.IX Item "Execution"
+.RS 4
+.IP "perlrun \- how to execute the Perl interpreter" 4
+.IX Item "perlrun - how to execute the Perl interpreter"
+.IP "perldebug \- Perl debugging" 4
+.IX Item "perldebug - Perl debugging"
+.RE
+.RS 4
+.RE
+.IP Functions 4
+.IX Item "Functions"
+.RS 4
+.IP "perlfunc \- Perl builtin functions" 4
+.IX Item "perlfunc - Perl builtin functions"
+.RE
+.RS 4
+.RE
+.IP Objects 4
+.IX Item "Objects"
+.RS 4
+.IP "perlref \- Perl references and nested data structures" 4
+.IX Item "perlref - Perl references and nested data structures"
+.IP "perlmod \- Perl modules (packages and symbol tables)" 4
+.IX Item "perlmod - Perl modules (packages and symbol tables)"
+.IP "perlobj \- Perl objects" 4
+.IX Item "perlobj - Perl objects"
+.IP "perltie \- how to hide an object class in a simple variable" 4
+.IX Item "perltie - how to hide an object class in a simple variable"
+.RE
+.RS 4
+.RE
+.IP "Data Structures" 4
+.IX Item "Data Structures"
+.RS 4
+.IP "perlref \- Perl references and nested data structures" 4
+.IX Item "perlref - Perl references and nested data structures"
+.IP "perllol \- Manipulating arrays of arrays in Perl" 4
+.IX Item "perllol - Manipulating arrays of arrays in Perl"
+.IP "perldsc \- Perl Data Structures Cookbook" 4
+.IX Item "perldsc - Perl Data Structures Cookbook"
+.RE
+.RS 4
+.RE
+.IP Modules 4
+.IX Item "Modules"
+.RS 4
+.IP "perlmod \- Perl modules (packages and symbol tables)" 4
+.IX Item "perlmod - Perl modules (packages and symbol tables)"
+.IP "perlmodlib \- constructing new Perl modules and finding existing ones" 4
+.IX Item "perlmodlib - constructing new Perl modules and finding existing ones"
+.RE
+.RS 4
+.RE
+.IP Regexes 4
+.IX Item "Regexes"
+.RS 4
+.IP "perlre \- Perl regular expressions" 4
+.IX Item "perlre - Perl regular expressions"
+.IP "perlfunc \- Perl builtin functions>" 4
+.IX Item "perlfunc - Perl builtin functions>"
+.IP "perlop \- Perl operators and precedence" 4
+.IX Item "perlop - Perl operators and precedence"
+.IP "perllocale \- Perl locale handling (internationalization and localization)" 4
+.IX Item "perllocale - Perl locale handling (internationalization and localization)"
+.RE
+.RS 4
+.RE
+.IP "Moving to perl5" 4
+.IX Item "Moving to perl5"
+.RS 4
+.IP "perltrap \- Perl traps for the unwary" 4
+.IX Item "perltrap - Perl traps for the unwary"
+.IP perl 4
+.IX Item "perl"
+.RE
+.RS 4
+.RE
+.IP "Linking with C" 4
+.IX Item "Linking with C"
+.RS 4
+.IP "perlxstut \- Tutorial for writing XSUBs" 4
+.IX Item "perlxstut - Tutorial for writing XSUBs"
+.IP "perlxs \- XS language reference manual" 4
+.IX Item "perlxs - XS language reference manual"
+.IP "perlcall \- Perl calling conventions from C" 4
+.IX Item "perlcall - Perl calling conventions from C"
+.IP "perlguts \- Introduction to the Perl API" 4
+.IX Item "perlguts - Introduction to the Perl API"
+.IP "perlembed \- how to embed perl in your C program" 4
+.IX Item "perlembed - how to embed perl in your C program"
+.RE
+.RS 4
+.RE
+.IP Various 4
+.IX Item "Various"
+.PD
+<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>
+(not a man-page but still useful, a collection of various essays on
+Perl techniques)
+.PP
+A crude table of contents for the Perl manpage set is found in perltoc.
+.SS "How can I use Perl interactively?"
+.IX Subsection "How can I use Perl interactively?"
+The typical approach uses the Perl debugger, described in the
+\&\fBperldebug\fR\|(1) manpage, on an "empty" program, like this:
+.PP
+.Vb 1
+\&    perl \-de 42
+.Ve
+.PP
+Now just type in any legal Perl code, and it will be immediately
+evaluated. You can also examine the symbol table, get stack
+backtraces, check variable values, set breakpoints, and other
+operations typically found in symbolic debuggers.
+.PP
+You can also use Devel::REPL which is an interactive shell for Perl,
+commonly known as a REPL \- Read, Evaluate, Print, Loop. It provides
+various handy features.
+.SS "How do I find which modules are installed on my system?"
+.IX Subsection "How do I find which modules are installed on my system?"
+From the command line, you can use the \f(CW\*(C`cpan\*(C'\fR command's \f(CW\*(C`\-l\*(C'\fR switch:
+.PP
+.Vb 1
+\&    $ cpan \-l
+.Ve
+.PP
+You can also use \f(CW\*(C`cpan\*(C'\fR's \f(CW\*(C`\-a\*(C'\fR switch to create an autobundle file
+that \f(CW\*(C`CPAN.pm\*(C'\fR understands and can use to re-install every module:
+.PP
+.Vb 1
+\&    $ cpan \-a
+.Ve
+.PP
+Inside a Perl program, you can use the ExtUtils::Installed module to
+show all installed distributions, although it can take awhile to do
+its magic. The standard library which comes with Perl just shows up
+as "Perl" (although you can get those with Module::CoreList).
+.PP
+.Vb 1
+\&    use ExtUtils::Installed;
+\&
+\&    my $inst    = ExtUtils::Installed\->new();
+\&    my @modules = $inst\->modules();
+.Ve
+.PP
+If you want a list of all of the Perl module filenames, you
+can use File::Find::Rule:
+.PP
+.Vb 1
+\&    use File::Find::Rule;
+\&
+\&    my @files = File::Find::Rule\->
+\&        extras({follow => 1})\->
+\&        file()\->
+\&        name( \*(Aq*.pm\*(Aq )\->
+\&        in( @INC )
+\&        ;
+.Ve
+.PP
+If you do not have that module, you can do the same thing
+with File::Find which is part of the standard library:
+.PP
+.Vb 2
+\&    use File::Find;
+\&    my @files;
+\&
+\&    find(
+\&        {
+\&        wanted => sub {
+\&            push @files, $File::Find::fullname
+\&            if \-f $File::Find::fullname && /\e.pm$/
+\&        },
+\&        follow => 1,
+\&        follow_skip => 2,
+\&        },
+\&        @INC
+\&    );
+\&
+\&    print join "\en", @files;
+.Ve
+.PP
+If you simply need to check quickly to see if a module is
+available, you can check for its documentation. If you can
+read the documentation the module is most likely installed.
+If you cannot read the documentation, the module might not
+have any (in rare cases):
+.PP
+.Vb 1
+\&    $ perldoc Module::Name
+.Ve
+.PP
+You can also try to include the module in a one-liner to see if
+perl finds it:
+.PP
+.Vb 1
+\&    $ perl \-MModule::Name \-e1
+.Ve
+.PP
+(If you don't receive a "Can't locate ... in \f(CW@INC\fR" error message, then Perl
+found the module name you asked for.)
+.SS "How do I debug my Perl programs?"
+.IX Subsection "How do I debug my Perl programs?"
+(contributed by brian d foy)
+.PP
+Before you do anything else, you can help yourself by ensuring that
+you let Perl tell you about problem areas in your code. By turning
+on warnings and strictures, you can head off many problems before
+they get too big. You can find out more about these in strict
+and warnings.
+.PP
+.Vb 3
+\&    #!/usr/bin/perl
+\&    use strict;
+\&    use warnings;
+.Ve
+.PP
+Beyond that, the simplest debugger is the \f(CW\*(C`print\*(C'\fR function. Use it
+to look at values as you run your program:
+.PP
+.Vb 1
+\&    print STDERR "The value is [$value]\en";
+.Ve
+.PP
+The Data::Dumper module can pretty-print Perl data structures:
+.PP
+.Vb 2
+\&    use Data::Dumper qw( Dumper );
+\&    print STDERR "The hash is " . Dumper( \e%hash ) . "\en";
+.Ve
+.PP
+Perl comes with an interactive debugger, which you can start with the
+\&\f(CW\*(C`\-d\*(C'\fR switch. It's fully explained in perldebug.
+.PP
+If you'd like a graphical user interface and you have Tk, you can use
+\&\f(CW\*(C`ptkdb\*(C'\fR. It's on CPAN and available for free.
+.PP
+If you need something much more sophisticated and controllable, Leon
+Brocard's Devel::ebug (which you can call with the \f(CW\*(C`\-D\*(C'\fR switch as \f(CW\*(C`\-Debug\*(C'\fR)
+gives you the programmatic hooks into everything you need to write your
+own (without too much pain and suffering).
+.PP
+You can also use a commercial debugger such as Affrus (Mac OS X), Komodo
+from Activestate (Windows and Mac OS X), or EPIC (most platforms).
+.SS "How do I profile my Perl programs?"
+.IX Subsection "How do I profile my Perl programs?"
+(contributed by brian d foy, updated Fri Jul 25 12:22:26 PDT 2008)
+.PP
+The \f(CW\*(C`Devel\*(C'\fR namespace has several modules which you can use to
+profile your Perl programs.
+.PP
+The Devel::NYTProf (New York Times Profiler) does both statement
+and subroutine profiling. It's available from CPAN and you also invoke
+it with the \f(CW\*(C`\-d\*(C'\fR switch:
+.PP
+.Vb 1
+\&    perl \-d:NYTProf some_perl.pl
+.Ve
+.PP
+It creates a database of the profile information that you can turn into
+reports. The \f(CW\*(C`nytprofhtml\*(C'\fR command turns the data into an HTML report
+similar to the Devel::Cover report:
+.PP
+.Vb 1
+\&    nytprofhtml
+.Ve
+.PP
+You might also be interested in using the Benchmark to
+measure and compare code snippets.
+.PP
+You can read more about profiling in \fIProgramming Perl\fR, chapter 20,
+or \fIMastering Perl\fR, chapter 5.
+.PP
+perldebguts documents creating a custom debugger if you need to
+create a special sort of profiler. brian d foy describes the process
+in \fIThe Perl Journal\fR, "Creating a Perl Debugger",
+<http://www.ddj.com/184404522> , and "Profiling in Perl"
+<http://www.ddj.com/184404580> .
+.PP
+Perl.com has two interesting articles on profiling: "Profiling Perl",
+by Simon Cozens, <https://www.perl.com/pub/2004/06/25/profiling.html/>
+and "Debugging and Profiling mod_perl Applications", by Frank Wiles,
+<http://www.perl.com/pub/a/2006/02/09/debug_mod_perl.html> .
+.PP
+Randal L. Schwartz writes about profiling in "Speeding up Your Perl
+Programs" for \fIUnix Review\fR,
+<http://www.stonehenge.com/merlyn/UnixReview/col49.html> , and "Profiling
+in Template Toolkit via Overriding" for \fILinux Magazine\fR,
+<http://www.stonehenge.com/merlyn/LinuxMag/col75.html> .
+.SS "How do I cross-reference my Perl programs?"
+.IX Subsection "How do I cross-reference my Perl programs?"
+The B::Xref module can be used to generate cross-reference reports
+for Perl programs.
+.PP
+.Vb 1
+\&    perl \-MO=Xref[,OPTIONS] scriptname.plx
+.Ve
+.SS "Is there a pretty-printer (formatter) for Perl?"
+.IX Subsection "Is there a pretty-printer (formatter) for Perl?"
+Perl::Tidy comes with a perl script perltidy which indents and
+reformats Perl scripts to make them easier to read by trying to follow
+the rules of the perlstyle. If you write Perl, or spend much time reading
+Perl, you will probably find it useful.
+.PP
+Of course, if you simply follow the guidelines in perlstyle,
+you shouldn't need to reformat. The habit of formatting your code
+as you write it will help prevent bugs. Your editor can and should
+help you with this. The perl-mode or newer cperl-mode for emacs
+can provide remarkable amounts of help with most (but not all)
+code, and even less programmable editors can provide significant
+assistance. Tom Christiansen and many other VI users swear by
+the following settings in vi and its clones:
+.PP
+.Vb 2
+\&    set ai sw=4
+\&    map! ^O {^M}^[O^T
+.Ve
+.PP
+Put that in your \fI.exrc\fR file (replacing the caret characters
+with control characters) and away you go. In insert mode, ^T is
+for indenting, ^D is for undenting, and ^O is for blockdenting\-\-as
+it were. A more complete example, with comments, can be found at
+<http://www.cpan.org/authors/id/T/TO/TOMC/scripts/toms.exrc.gz>
+.SS "Is there an IDE or Windows Perl Editor?"
+.IX Subsection "Is there an IDE or Windows Perl Editor?"
+Perl programs are just plain text, so any editor will do.
+.PP
+If you're on Unix, you already have an IDE\-\-Unix itself. The Unix
+philosophy is the philosophy of several small tools that each do one
+thing and do it well. It's like a carpenter's toolbox.
+.PP
+If you want an IDE, check the following (in alphabetical order, not
+order of preference):
+.IP Eclipse 4
+.IX Item "Eclipse"
+<http://e\-p\-i\-c.sf.net/>
+.Sp
+The Eclipse Perl Integration Project integrates Perl
+editing/debugging with Eclipse.
+.IP Enginsite 4
+.IX Item "Enginsite"
+<http://www.enginsite.com/>
+.Sp
+Perl Editor by EngInSite is a complete integrated development
+environment (IDE) for creating, testing, and  debugging  Perl scripts;
+the tool runs on Windows 9x/NT/2000/XP or later.
+.IP "IntelliJ IDEA" 4
+.IX Item "IntelliJ IDEA"
+<https://plugins.jetbrains.com/plugin/7796>
+.Sp
+Camelcade plugin provides Perl5 support in IntelliJ IDEA and other JetBrains IDEs.
+.IP Kephra 4
+.IX Item "Kephra"
+<http://kephra.sf.net>
+.Sp
+GUI editor written in Perl using wxWidgets and Scintilla with lots of smaller features.
+Aims for a UI based on Perl principles like TIMTOWTDI and "easy things should be easy,
+hard things should be possible".
+.IP Komodo 4
+.IX Item "Komodo"
+<http://www.ActiveState.com/Products/Komodo/>
+.Sp
+ActiveState's cross-platform (as of October 2004, that's Windows, Linux,
+and Solaris), multi-language IDE has Perl support, including a regular expression
+debugger and remote debugging.
+.IP Notepad++ 4
+.IX Item "Notepad++"
+<http://notepad\-plus.sourceforge.net/>
+.IP "Open Perl IDE" 4
+.IX Item "Open Perl IDE"
+<http://open\-perl\-ide.sourceforge.net/>
+.Sp
+Open Perl IDE is an integrated development environment for writing
+and debugging Perl scripts with ActiveState's ActivePerl distribution
+under Windows 95/98/NT/2000.
+.IP OptiPerl 4
+.IX Item "OptiPerl"
+<http://www.optiperl.com/>
+.Sp
+OptiPerl is a Windows IDE with simulated CGI environment, including
+debugger and syntax-highlighting editor.
+.IP Padre 4
+.IX Item "Padre"
+<http://padre.perlide.org/>
+.Sp
+Padre is cross-platform IDE for Perl written in Perl using wxWidgets to provide
+a native look and feel. It's open source under the Artistic License. It
+is one of the newer Perl IDEs.
+.IP PerlBuilder 4
+.IX Item "PerlBuilder"
+<http://www.solutionsoft.com/perl.htm>
+.Sp
+PerlBuilder is an integrated development environment for Windows that
+supports Perl development.
+.IP visiPerl+ 4
+.IX Item "visiPerl+"
+<http://helpconsulting.net/visiperl/index.html>
+.Sp
+From Help Consulting, for Windows.
+.IP "Visual Perl" 4
+.IX Item "Visual Perl"
+<http://www.activestate.com/Products/Visual_Perl/>
+.Sp
+Visual Perl is a Visual Studio.NET plug-in from ActiveState.
+.IP Zeus 4
+.IX Item "Zeus"
+<http://www.zeusedit.com/lookmain.html>
+.Sp
+Zeus for Windows is another Win32 multi-language editor/IDE
+that comes with support for Perl.
+.PP
+For editors: if you're on Unix you probably have vi or a vi clone
+already, and possibly an emacs too, so you may not need to download
+anything. In any emacs the cperl-mode (M\-x cperl-mode) gives you
+perhaps the best available Perl editing mode in any editor.
+.PP
+If you are using Windows, you can use any editor that lets you work
+with plain text, such as NotePad or WordPad. Word processors, such as
+Microsoft Word or WordPerfect, typically do not work since they insert
+all sorts of behind-the-scenes information, although some allow you to
+save files as "Text Only". You can also download text editors designed
+specifically for programming, such as Textpad (
+<http://www.textpad.com/> ) and UltraEdit ( <http://www.ultraedit.com/> ),
+among others.
+.PP
+If you are using MacOS, the same concerns apply. MacPerl (for Classic
+environments) comes with a simple editor. Popular external editors are
+BBEdit ( <http://www.barebones.com/products/bbedit/> ) or Alpha (
+<http://www.his.com/~jguyer/Alpha/Alpha8.html> ). MacOS X users can use
+Unix editors as well.
+.IP "GNU Emacs" 4
+.IX Item "GNU Emacs"
+<http://www.gnu.org/software/emacs/windows/ntemacs.html>
+.IP MicroEMACS 4
+.IX Item "MicroEMACS"
+<http://www.microemacs.de/>
+.IP XEmacs 4
+.IX Item "XEmacs"
+<http://www.xemacs.org/Download/index.html>
+.IP Jed 4
+.IX Item "Jed"
+<http://space.mit.edu/~davis/jed/>
+.PP
+or a vi clone such as
+.IP Vim 4
+.IX Item "Vim"
+<http://www.vim.org/>
+.IP Vile 4
+.IX Item "Vile"
+<http://invisible\-island.net/vile/vile.html>
+.PP
+The following are Win32 multilanguage editor/IDEs that support Perl:
+.IP MultiEdit 4
+.IX Item "MultiEdit"
+<http://www.MultiEdit.com/>
+.IP SlickEdit 4
+.IX Item "SlickEdit"
+<http://www.slickedit.com/>
+.IP ConTEXT 4
+.IX Item "ConTEXT"
+<http://www.contexteditor.org/>
+.PP
+There is also a toyedit Text widget based editor written in Perl
+that is distributed with the Tk module on CPAN. The ptkdb
+( <http://ptkdb.sourceforge.net/> ) is a Perl/Tk\-based debugger that
+acts as a development environment of sorts. Perl Composer
+( <http://perlcomposer.sourceforge.net/> ) is an IDE for Perl/Tk
+GUI creation.
+.PP
+In addition to an editor/IDE you might be interested in a more
+powerful shell environment for Win32. Your options include
+.IP bash 4
+.IX Item "bash"
+from the Cygwin package ( <http://cygwin.com/> )
+.IP zsh 4
+.IX Item "zsh"
+<http://www.zsh.org/>
+.PP
+Cygwin is covered by the GNU General Public
+License (but that shouldn't matter for Perl use). Cygwin
+contains (in addition to the shell) a comprehensive set
+of standard Unix toolkit utilities.
+.IP "BBEdit and TextWrangler" 4
+.IX Item "BBEdit and TextWrangler"
+are text editors for OS X that have a Perl sensitivity mode
+( <http://www.barebones.com/> ).
+.SS "Where can I get Perl macros for vi?"
+.IX Subsection "Where can I get Perl macros for vi?"
+For a complete version of Tom Christiansen's vi configuration file,
+see <http://www.cpan.org/authors/id/T/TO/TOMC/scripts/toms.exrc.gz> ,
+the standard benchmark file for vi emulators. The file runs best with nvi,
+the current version of vi out of Berkeley, which incidentally can be built
+with an embedded Perl interpreter\-\-see <http://www.cpan.org/src/misc/> .
+.SS "Where can I get perl-mode or cperl-mode for emacs?"
+.IX Xref "emacs"
+.IX Subsection "Where can I get perl-mode or cperl-mode for emacs?"
+Since Emacs version 19 patchlevel 22 or so, there have been both a
+perl\-mode.el and support for the Perl debugger built in. These should
+come with the standard Emacs 19 distribution.
+.PP
+Note that the perl-mode of emacs will have fits with \f(CW"main\*(Aqfoo"\fR
+(single quote), and mess up the indentation and highlighting. You
+are probably using \f(CW"main::foo"\fR in new Perl code anyway, so this
+shouldn't be an issue.
+.PP
+For CPerlMode, see <http://www.emacswiki.org/cgi\-bin/wiki/CPerlMode>
+.SS "How can I use curses with Perl?"
+.IX Subsection "How can I use curses with Perl?"
+The Curses module from CPAN provides a dynamically loadable object
+module interface to a curses library. A small demo can be found at the
+directory <http://www.cpan.org/authors/id/T/TO/TOMC/scripts/rep.gz> ;
+this program repeats a command and updates the screen as needed, rendering
+\&\fBrep ps axu\fR similar to \fBtop\fR.
+.SS "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?"
+.IX Xref "GUI Tk Wx WxWidgets Gtk Gtk2 CamelBones Qt"
+.IX Subsection "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?"
+(contributed by Ben Morrow)
+.PP
+There are a number of modules which let you write GUIs in Perl. Most
+GUI toolkits have a perl interface: an incomplete list follows.
+.IP Tk 4
+.IX Item "Tk"
+This works under Unix and Windows, and the current version doesn't
+look half as bad under Windows as it used to. Some of the gui elements
+still don't 'feel' quite right, though. The interface is very natural
+and 'perlish', making it easy to use in small scripts that just need a
+simple gui. It hasn't been updated in a while.
+.IP Wx 4
+.IX Item "Wx"
+This is a Perl binding for the cross-platform wxWidgets toolkit
+( <http://www.wxwidgets.org> ). It works under Unix, Win32 and Mac OS X,
+using native widgets (Gtk under Unix). The interface follows the C++
+interface closely, but the documentation is a little sparse for someone
+who doesn't know the library, mostly just referring you to the C++
+documentation.
+.IP "Gtk and Gtk2" 4
+.IX Item "Gtk and Gtk2"
+These are Perl bindings for the Gtk toolkit ( <http://www.gtk.org> ). The
+interface changed significantly between versions 1 and 2 so they have
+separate Perl modules. It runs under Unix, Win32 and Mac OS X (currently
+it requires an X server on Mac OS, but a 'native' port is underway), and
+the widgets look the same on every platform: i.e., they don't match the
+native widgets. As with Wx, the Perl bindings follow the C API closely,
+and the documentation requires you to read the C documentation to
+understand it.
+.IP Win32::GUI 4
+.IX Item "Win32::GUI"
+This provides access to most of the Win32 GUI widgets from Perl.
+Obviously, it only runs under Win32, and uses native widgets. The Perl
+interface doesn't really follow the C interface: it's been made more
+Perlish, and the documentation is pretty good. More advanced stuff may
+require familiarity with the C Win32 APIs, or reference to MSDN.
+.IP CamelBones 4
+.IX Item "CamelBones"
+CamelBones ( <http://camelbones.sourceforge.net> ) is a Perl interface to
+Mac OS X's Cocoa GUI toolkit, and as such can be used to produce native
+GUIs on Mac OS X. It's not on CPAN, as it requires frameworks that
+CPAN.pm doesn't know how to install, but installation is via the
+standard OSX package installer. The Perl API is, again, very close to
+the ObjC API it's wrapping, and the documentation just tells you how to
+translate from one to the other.
+.IP Qt 4
+.IX Item "Qt"
+There is a Perl interface to TrollTech's Qt toolkit, but it does not
+appear to be maintained.
+.IP Athena 4
+.IX Item "Athena"
+Sx is an interface to the Athena widget set which comes with X, but
+again it appears not to be much used nowadays.
+.SS "How can I make my Perl program run faster?"
+.IX Subsection "How can I make my Perl program run faster?"
+The best way to do this is to come up with a better algorithm. This
+can often make a dramatic difference. Jon Bentley's book
+\&\fIProgramming Pearls\fR (that's not a misspelling!)  has some good tips
+on optimization, too. Advice on benchmarking boils down to: benchmark
+and profile to make sure you're optimizing the right part, look for
+better algorithms instead of microtuning your code, and when all else
+fails consider just buying faster hardware. You will probably want to
+read the answer to the earlier question "How do I profile my Perl
+programs?" if you haven't done so already.
+.PP
+A different approach is to autoload seldom-used Perl code. See the
+AutoSplit and AutoLoader modules in the standard distribution for
+that. Or you could locate the bottleneck and think about writing just
+that part in C, the way we used to take bottlenecks in C code and
+write them in assembler. Similar to rewriting in C, modules that have
+critical sections can be written in C (for instance, the PDL module
+from CPAN).
+.PP
+If you're currently linking your perl executable to a shared
+\&\fIlibc.so\fR, you can often gain a 10\-25% performance benefit by
+rebuilding it to link with a static libc.a instead. This will make a
+bigger perl executable, but your Perl programs (and programmers) may
+thank you for it. See the \fIINSTALL\fR file in the source distribution
+for more information.
+.PP
+The undump program was an ancient attempt to speed up Perl program by
+storing the already-compiled form to disk. This is no longer a viable
+option, as it only worked on a few architectures, and wasn't a good
+solution anyway.
+.SS "How can I make my Perl program take less memory?"
+.IX Subsection "How can I make my Perl program take less memory?"
+When it comes to time-space tradeoffs, Perl nearly always prefers to
+throw memory at a problem. Scalars in Perl use more memory than
+strings in C, arrays take more than that, and hashes use even more. While
+there's still a lot to be done, recent releases have been addressing
+these issues. For example, as of 5.004, duplicate hash keys are
+shared amongst all hashes using them, so require no reallocation.
+.PP
+In some cases, using \fBsubstr()\fR or \fBvec()\fR to simulate arrays can be
+highly beneficial. For example, an array of a thousand booleans will
+take at least 20,000 bytes of space, but it can be turned into one
+125\-byte bit vector\-\-a considerable memory savings. The standard
+Tie::SubstrHash module can also help for certain types of data
+structure. If you're working with specialist data structures
+(matrices, for instance) modules that implement these in C may use
+less memory than equivalent Perl modules.
+.PP
+Another thing to try is learning whether your Perl was compiled with
+the system malloc or with Perl's builtin malloc. Whichever one it
+is, try using the other one and see whether this makes a difference.
+Information about malloc is in the \fIINSTALL\fR file in the source
+distribution. You can find out whether you are using perl's malloc by
+typing \f(CW\*(C`perl \-V:usemymalloc\*(C'\fR.
+.PP
+Of course, the best way to save memory is to not do anything to waste
+it in the first place. Good programming practices can go a long way
+toward this:
+.IP "Don't slurp!" 4
+.IX Item "Don't slurp!"
+Don't read an entire file into memory if you can process it line
+by line. Or more concretely, use a loop like this:
+.Sp
+.Vb 6
+\&    #
+\&    # Good Idea
+\&    #
+\&    while (my $line = <$file_handle>) {
+\&       # ...
+\&    }
+.Ve
+.Sp
+instead of this:
+.Sp
+.Vb 7
+\&    #
+\&    # Bad Idea
+\&    #
+\&    my @data = <$file_handle>;
+\&    foreach (@data) {
+\&        # ...
+\&    }
+.Ve
+.Sp
+When the files you're processing are small, it doesn't much matter which
+way you do it, but it makes a huge difference when they start getting
+larger.
+.IP "Use map and grep selectively" 4
+.IX Item "Use map and grep selectively"
+Remember that both map and grep expect a LIST argument, so doing this:
+.Sp
+.Vb 1
+\&        @wanted = grep {/pattern/} <$file_handle>;
+.Ve
+.Sp
+will cause the entire file to be slurped. For large files, it's better
+to loop:
+.Sp
+.Vb 3
+\&        while (<$file_handle>) {
+\&                push(@wanted, $_) if /pattern/;
+\&        }
+.Ve
+.IP "Avoid unnecessary quotes and stringification" 4
+.IX Item "Avoid unnecessary quotes and stringification"
+Don't quote large strings unless absolutely necessary:
+.Sp
+.Vb 1
+\&        my $copy = "$large_string";
+.Ve
+.Sp
+makes 2 copies of \f(CW$large_string\fR (one for \f(CW$copy\fR and another for the
+quotes), whereas
+.Sp
+.Vb 1
+\&        my $copy = $large_string;
+.Ve
+.Sp
+only makes one copy.
+.Sp
+Ditto for stringifying large arrays:
+.Sp
+.Vb 4
+\&    {
+\&    local $, = "\en";
+\&    print @big_array;
+\&    }
+.Ve
+.Sp
+is much more memory-efficient than either
+.Sp
+.Vb 1
+\&    print join "\en", @big_array;
+.Ve
+.Sp
+or
+.Sp
+.Vb 4
+\&    {
+\&    local $" = "\en";
+\&    print "@big_array";
+\&    }
+.Ve
+.IP "Pass by reference" 4
+.IX Item "Pass by reference"
+Pass arrays and hashes by reference, not by value. For one thing, it's
+the only way to pass multiple lists or hashes (or both) in a single
+call/return. It also avoids creating a copy of all the contents. This
+requires some judgement, however, because any changes will be propagated
+back to the original data. If you really want to mangle (er, modify) a
+copy, you'll have to sacrifice the memory needed to make one.
+.IP "Tie large variables to disk" 4
+.IX Item "Tie large variables to disk"
+For "big" data stores (i.e. ones that exceed available memory) consider
+using one of the DB modules to store it on disk instead of in RAM. This
+will incur a penalty in access time, but that's probably better than
+causing your hard disk to thrash due to massive swapping.
+.SS "Is it safe to return a reference to local or lexical data?"
+.IX Subsection "Is it safe to return a reference to local or lexical data?"
+Yes. Perl's garbage collection system takes care of this so
+everything works out right.
+.PP
+.Vb 4
+\&    sub makeone {
+\&        my @a = ( 1 .. 10 );
+\&        return \e@a;
+\&    }
+\&
+\&    for ( 1 .. 10 ) {
+\&        push @many, makeone();
+\&    }
+\&
+\&    print $many[4][5], "\en";
+\&
+\&    print "@many\en";
+.Ve
+.SS "How can I free an array or hash so my program shrinks?"
+.IX Subsection "How can I free an array or hash so my program shrinks?"
+(contributed by Michael Carman)
+.PP
+You usually can't. Memory allocated to lexicals (i.e. \fBmy()\fR variables)
+cannot be reclaimed or reused even if they go out of scope. It is
+reserved in case the variables come back into scope. Memory allocated
+to global variables can be reused (within your program) by using
+\&\fBundef()\fR and/or \fBdelete()\fR.
+.PP
+On most operating systems, memory allocated to a program can never be
+returned to the system. That's why long-running programs sometimes re\-
+exec themselves. Some operating systems (notably, systems that use
+\&\fBmmap\fR\|(2) for allocating large chunks of memory) can reclaim memory that
+is no longer used, but on such systems, perl must be configured and
+compiled to use the OS's malloc, not perl's.
+.PP
+In general, memory allocation and de-allocation isn't something you can
+or should be worrying about much in Perl.
+.PP
+See also "How can I make my Perl program take less memory?"
+.SS "How can I make my CGI script more efficient?"
+.IX Subsection "How can I make my CGI script more efficient?"
+Beyond the normal measures described to make general Perl programs
+faster or smaller, a CGI program has additional issues. It may be run
+several times per second. Given that each time it runs it will need
+to be re-compiled and will often allocate a megabyte or more of system
+memory, this can be a killer. Compiling into C \fBisn't going to help
+you\fR because the process start-up overhead is where the bottleneck is.
+.PP
+There are three popular ways to avoid this overhead. One solution
+involves running the Apache HTTP server (available from
+<http://www.apache.org/> ) with either of the mod_perl or mod_fastcgi
+plugin modules.
+.PP
+With mod_perl and the Apache::Registry module (distributed with
+mod_perl), httpd will run with an embedded Perl interpreter which
+pre-compiles your script and then executes it within the same address
+space without forking. The Apache extension also gives Perl access to
+the internal server API, so modules written in Perl can do just about
+anything a module written in C can. For more on mod_perl, see
+<http://perl.apache.org/>
+.PP
+With the FCGI module (from CPAN) and the mod_fastcgi
+module (available from <http://www.fastcgi.com/> ) each of your Perl
+programs becomes a permanent CGI daemon process.
+.PP
+Finally, Plack is a Perl module and toolkit that contains PSGI middleware,
+helpers and adapters to web servers, allowing you to easily deploy scripts which
+can continue running, and provides flexibility with regards to which web server
+you use. It can allow existing CGI scripts to enjoy this flexibility and
+performance with minimal changes, or can be used along with modern Perl web
+frameworks to make writing and deploying web services with Perl a breeze.
+.PP
+These solutions can have far-reaching effects on your system and on the way you
+write your CGI programs, so investigate them with care.
+.PP
+See also
+<http://www.cpan.org/modules/by\-category/15_World_Wide_Web_HTML_HTTP_CGI/> .
+.SS "How can I hide the source for my Perl program?"
+.IX Subsection "How can I hide the source for my Perl program?"
+Delete it. :\-) Seriously, there are a number of (mostly
+unsatisfactory) solutions with varying levels of "security".
+.PP
+First of all, however, you \fIcan't\fR take away read permission, because
+the source code has to be readable in order to be compiled and
+interpreted. (That doesn't mean that a CGI script's source is
+readable by people on the web, though\-\-only by people with access to
+the filesystem.)  So you have to leave the permissions at the socially
+friendly 0755 level.
+.PP
+Some people regard this as a security problem. If your program does
+insecure things and relies on people not knowing how to exploit those
+insecurities, it is not secure. It is often possible for someone to
+determine the insecure things and exploit them without viewing the
+source. Security through obscurity, the name for hiding your bugs
+instead of fixing them, is little security indeed.
+.PP
+You can try using encryption via source filters (Starting from Perl
+5.8 the Filter::Simple and Filter::Util::Call modules are included in
+the standard distribution), but any decent programmer will be able to
+decrypt it. You can try using the byte code compiler and interpreter
+described later in perlfaq3, but the curious might still be able to
+de-compile it. You can try using the native-code compiler described
+later, but crackers might be able to disassemble it. These pose
+varying degrees of difficulty to people wanting to get at your code,
+but none can definitively conceal it (true of every language, not just
+Perl).
+.PP
+It is very easy to recover the source of Perl programs. You simply
+feed the program to the perl interpreter and use the modules in
+the B:: hierarchy. The B::Deparse module should be able to
+defeat most attempts to hide source. Again, this is not
+unique to Perl.
+.PP
+If you're concerned about people profiting from your code, then the
+bottom line is that nothing but a restrictive license will give you
+legal security. License your software and pepper it with threatening
+statements like "This is unpublished proprietary software of XYZ Corp.
+Your access to it does not give you permission to use it blah blah
+blah."  We are not lawyers, of course, so you should see a lawyer if
+you want to be sure your license's wording will stand up in court.
+.SS "How can I compile my Perl program into byte code or C?"
+.IX Subsection "How can I compile my Perl program into byte code or C?"
+(contributed by brian d foy)
+.PP
+In general, you can't do this. There are some things that may work
+for your situation though. People usually ask this question
+because they want to distribute their works without giving away
+the source code, and most solutions trade disk space for convenience.
+You probably won't see much of a speed increase either, since most
+solutions simply bundle a Perl interpreter in the final product
+(but see "How can I make my Perl program run faster?").
+.PP
+The Perl Archive Toolkit is Perl's analog to Java's JAR. It's freely
+available and on CPAN ( <https://metacpan.org/pod/PAR> ).
+.PP
+There are also some commercial products that may work for you, although
+you have to buy a license for them.
+.PP
+The Perl Dev Kit ( <http://www.activestate.com/Products/Perl_Dev_Kit/> )
+from ActiveState can "Turn your Perl programs into ready-to-run
+executables for HP-UX, Linux, Solaris and Windows."
+.PP
+Perl2Exe ( <http://www.indigostar.com/perl2exe.htm> ) is a command line
+program for converting perl scripts to executable files. It targets both
+Windows and Unix platforms.
+.ie n .SS "How can I get ""#!perl"" to work on [MS\-DOS,NT,...]?"
+.el .SS "How can I get \f(CW#!perl\fP to work on [MS\-DOS,NT,...]?"
+.IX Subsection "How can I get #!perl to work on [MS-DOS,NT,...]?"
+For OS/2 just use
+.PP
+.Vb 1
+\&    extproc perl \-S \-your_switches
+.Ve
+.PP
+as the first line in \f(CW\*(C`*.cmd\*(C'\fR file (\f(CW\*(C`\-S\*(C'\fR due to a bug in cmd.exe's
+"extproc" handling). For DOS one should first invent a corresponding
+batch file and codify it in \f(CW\*(C`ALTERNATE_SHEBANG\*(C'\fR (see the
+\&\fIdosish.h\fR file in the source distribution for more information).
+.PP
+The Win95/NT installation, when using the ActiveState port of Perl,
+will modify the Registry to associate the \f(CW\*(C`.pl\*(C'\fR extension with the
+perl interpreter. If you install another port, perhaps even building
+your own Win95/NT Perl from the standard sources by using a Windows port
+of gcc (e.g., with cygwin or mingw32), then you'll have to modify
+the Registry yourself. In addition to associating \f(CW\*(C`.pl\*(C'\fR with the
+interpreter, NT people can use: \f(CW\*(C`SET PATHEXT=%PATHEXT%;.PL\*(C'\fR to let them
+run the program \f(CW\*(C`install\-linux.pl\*(C'\fR merely by typing \f(CW\*(C`install\-linux\*(C'\fR.
+.PP
+Under "Classic" MacOS, a perl program will have the appropriate Creator and
+Type, so that double-clicking them will invoke the MacPerl application.
+Under Mac OS X, clickable apps can be made from any \f(CW\*(C`#!\*(C'\fR script using Wil
+Sanchez' DropScript utility: <http://www.wsanchez.net/software/> .
+.PP
+\&\fIIMPORTANT!\fR: Whatever you do, PLEASE don't get frustrated, and just
+throw the perl interpreter into your cgi-bin directory, in order to
+get your programs working for a web server. This is an EXTREMELY big
+security risk. Take the time to figure out how to do it correctly.
+.SS "Can I write useful Perl programs on the command line?"
+.IX Subsection "Can I write useful Perl programs on the command line?"
+Yes. Read perlrun for more information. Some examples follow.
+(These assume standard Unix shell quoting rules.)
+.PP
+.Vb 2
+\&    # sum first and last fields
+\&    perl \-lane \*(Aqprint $F[0] + $F[\-1]\*(Aq *
+\&
+\&    # identify text files
+\&    perl \-le \*(Aqfor(@ARGV) {print if \-f && \-T _}\*(Aq *
+\&
+\&    # remove (most) comments from C program
+\&    perl \-0777 \-pe \*(Aqs{/\e*.*?\e*/}{}gs\*(Aq foo.c
+\&
+\&    # make file a month younger than today, defeating reaper daemons
+\&    perl \-e \*(Aq$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)\*(Aq *
+\&
+\&    # find first unused uid
+\&    perl \-le \*(Aq$i++ while getpwuid($i); print $i\*(Aq
+\&
+\&    # display reasonable manpath
+\&    echo $PATH | perl \-nl \-072 \-e \*(Aq
+\&    s![^/+]*$!man!&&\-d&&!$s{$_}++&&push@m,$_;END{print"@m"}\*(Aq
+.Ve
+.PP
+OK, the last one was actually an Obfuscated Perl Contest entry. :\-)
+.SS "Why don't Perl one-liners work on my DOS/Mac/VMS system?"
+.IX Subsection "Why don't Perl one-liners work on my DOS/Mac/VMS system?"
+The problem is usually that the command interpreters on those systems
+have rather different ideas about quoting than the Unix shells under
+which the one-liners were created. On some systems, you may have to
+change single-quotes to double ones, which you must \fINOT\fR do on Unix
+or Plan9 systems. You might also have to change a single % to a %%.
+.PP
+For example:
+.PP
+.Vb 2
+\&    # Unix (including Mac OS X)
+\&    perl \-e \*(Aqprint "Hello world\en"\*(Aq
+\&
+\&    # DOS, etc.
+\&    perl \-e "print \e"Hello world\en\e""
+\&
+\&    # Mac Classic
+\&    print "Hello world\en"
+\&     (then Run "Myscript" or Shift\-Command\-R)
+\&
+\&    # MPW
+\&    perl \-e \*(Aqprint "Hello world\en"\*(Aq
+\&
+\&    # VMS
+\&    perl \-e "print ""Hello world\en"""
+.Ve
+.PP
+The problem is that none of these examples are reliable: they depend on the
+command interpreter. Under Unix, the first two often work. Under DOS,
+it's entirely possible that neither works. If 4DOS was the command shell,
+you'd probably have better luck like this:
+.PP
+.Vb 1
+\&  perl \-e "print <Ctrl\-x>"Hello world\en<Ctrl\-x>""
+.Ve
+.PP
+Under the Mac, it depends which environment you are using. The MacPerl
+shell, or MPW, is much like Unix shells in its support for several
+quoting variants, except that it makes free use of the Mac's non-ASCII
+characters as control characters.
+.PP
+Using \fBqq()\fR, q(), and \fBqx()\fR, instead of "double quotes", 'single
+quotes', and `backticks`, may make one-liners easier to write.
+.PP
+There is no general solution to all of this. It is a mess.
+.PP
+[Some of this answer was contributed by Kenneth Albanowski.]
+.SS "Where can I learn about CGI or Web programming in Perl?"
+.IX Subsection "Where can I learn about CGI or Web programming in Perl?"
+For modules, get the CGI or LWP modules from CPAN. For textbooks,
+see the two especially dedicated to web stuff in the question on
+books. For problems and questions related to the web, like "Why
+do I get 500 Errors" or "Why doesn't it run from the browser right
+when it runs fine on the command line", see the troubleshooting
+guides and references in perlfaq9 or in the CGI MetaFAQ:
+.PP
+.Vb 1
+\&    L<http://www.perl.org/CGI_MetaFAQ.html>
+.Ve
+.PP
+Looking into <https://plackperl.org> and modern Perl web frameworks is highly recommended,
+though; web programming in Perl has evolved a long way from the old days of
+simple CGI scripts.
+.SS "Where can I learn about object-oriented Perl programming?"
+.IX Subsection "Where can I learn about object-oriented Perl programming?"
+A good place to start is perlootut, and you can use perlobj for
+reference.
+.PP
+A good book on OO on Perl is the "Object-Oriented Perl"
+by Damian Conway from Manning Publications, or "Intermediate Perl"
+by Randal Schwartz, brian d foy, and Tom Phoenix from O'Reilly Media.
+.SS "Where can I learn about linking C with Perl?"
+.IX Subsection "Where can I learn about linking C with Perl?"
+If you want to call C from Perl, start with perlxstut,
+moving on to perlxs, xsubpp, and perlguts. If you want to
+call Perl from C, then read perlembed, perlcall, and
+perlguts. Don't forget that you can learn a lot from looking at
+how the authors of existing extension modules wrote their code and
+solved their problems.
+.PP
+You might not need all the power of XS. The Inline::C module lets
+you put C code directly in your Perl source. It handles all the
+magic to make it work. You still have to learn at least some of
+the perl API but you won't have to deal with the complexity of the
+XS support files.
+.SS "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?"
+.IX Subsection "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?"
+Download the ExtUtils::Embed kit from CPAN and run `make test'. If
+the tests pass, read the pods again and again and again. If they
+fail, submit a bug report to <https://github.com/Perl/perl5/issues>
+with the output of
+\&\f(CW\*(C`make test TEST_VERBOSE=1\*(C'\fR along with \f(CW\*(C`perl \-V\*(C'\fR.
+.SS "When I tried to run my script, I got this message. What does it mean?"
+.IX Subsection "When I tried to run my script, I got this message. What does it mean?"
+A complete list of Perl's error messages and warnings with explanatory
+text can be found in perldiag. You can also use the splain program
+(distributed with Perl) to explain the error messages:
+.PP
+.Vb 2
+\&    perl program 2>diag.out
+\&    splain [\-v] [\-p] diag.out
+.Ve
+.PP
+or change your program to explain the messages for you:
+.PP
+.Vb 1
+\&    use diagnostics;
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    use diagnostics \-verbose;
+.Ve
+.SS "What's MakeMaker?"
+.IX Subsection "What's MakeMaker?"
+(contributed by brian d foy)
+.PP
+The ExtUtils::MakeMaker module, better known simply as "MakeMaker",
+turns a Perl script, typically called \f(CW\*(C`Makefile.PL\*(C'\fR, into a Makefile.
+The Unix tool \f(CW\*(C`make\*(C'\fR uses this file to manage dependencies and actions
+to process and install a Perl distribution.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples here are in the public
+domain. You are permitted and encouraged to use this code and any
+derivatives thereof in your own programs for fun or for profit as you
+see fit. A simple comment in the code giving credit to the FAQ would
+be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq4.1 b/upstream/mageia-cauldron/man1/perlfaq4.1
new file mode 100644
index 00000000..7dd8b5d6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq4.1
@@ -0,0 +1,3085 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ4 1"
+.TH PERLFAQ4 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq4 \- Data Manipulation
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section of the FAQ answers questions related to manipulating
+numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
+.SH "Data: Numbers"
+.IX Header "Data: Numbers"
+.SS "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?"
+.IX Subsection "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?"
+For the long explanation, see David Goldberg's "What Every Computer
+Scientist Should Know About Floating-Point Arithmetic"
+(<http://web.cse.msu.edu/~cse320/Documents/FloatingPoint.pdf>).
+.PP
+Internally, your computer represents floating-point numbers in binary.
+Digital (as in powers of two) computers cannot store all numbers
+exactly. Some real numbers lose precision in the process. This is a
+problem with how computers store numbers and affects all computer
+languages, not just Perl.
+.PP
+perlnumber shows the gory details of number representations and
+conversions.
+.PP
+To limit the number of decimal places in your numbers, you can use the
+\&\f(CW\*(C`printf\*(C'\fR or \f(CW\*(C`sprintf\*(C'\fR function. See
+"Floating-point Arithmetic" in perlop for more details.
+.PP
+.Vb 1
+\&    printf "%.2f", 10/3;
+\&
+\&    my $number = sprintf "%.2f", 10/3;
+.Ve
+.SS "Why is \fBint()\fP broken?"
+.IX Subsection "Why is int() broken?"
+Your \f(CWint()\fR is most probably working just fine. It's the numbers that
+aren't quite what you think.
+.PP
+First, see the answer to "Why am I getting long decimals
+(eg, 19.9499999999999) instead of the numbers I should be getting
+(eg, 19.95)?".
+.PP
+For example, this
+.PP
+.Vb 1
+\&    print int(0.6/0.2\-2), "\en";
+.Ve
+.PP
+will in most computers print 0, not 1, because even such simple
+numbers as 0.6 and 0.2 cannot be presented exactly by floating-point
+numbers. What you think in the above as 'three' is really more like
+2.9999999999999995559.
+.SS "Why isn't my octal data interpreted correctly?"
+.IX Subsection "Why isn't my octal data interpreted correctly?"
+(contributed by brian d foy)
+.PP
+You're probably trying to convert a string to a number, which Perl only
+converts as a decimal number. When Perl converts a string to a number, it
+ignores leading spaces and zeroes, then assumes the rest of the digits
+are in base 10:
+.PP
+.Vb 1
+\&    my $string = \*(Aq0644\*(Aq;
+\&
+\&    print $string + 0;  # prints 644
+\&
+\&    print $string + 44; # prints 688, certainly not octal!
+.Ve
+.PP
+This problem usually involves one of the Perl built-ins that has the
+same name a Unix command that uses octal numbers as arguments on the
+command line. In this example, \f(CW\*(C`chmod\*(C'\fR on the command line knows that
+its first argument is octal because that's what it does:
+.PP
+.Vb 1
+\&    %prompt> chmod 644 file
+.Ve
+.PP
+If you want to use the same literal digits (644) in Perl, you have to tell
+Perl to treat them as octal numbers either by prefixing the digits with
+a \f(CW0\fR or using \f(CW\*(C`oct\*(C'\fR:
+.PP
+.Vb 2
+\&    chmod(     0644, $filename );  # right, has leading zero
+\&    chmod( oct(644), $filename );  # also correct
+.Ve
+.PP
+The problem comes in when you take your numbers from something that Perl
+thinks is a string, such as a command line argument in \f(CW@ARGV\fR:
+.PP
+.Vb 1
+\&    chmod( $ARGV[0],      $filename );  # wrong, even if "0644"
+\&
+\&    chmod( oct($ARGV[0]), $filename );  # correct, treat string as octal
+.Ve
+.PP
+You can always check the value you're using by printing it in octal
+notation to ensure it matches what you think it should be. Print it
+in octal  and decimal format:
+.PP
+.Vb 1
+\&    printf "0%o %d", $number, $number;
+.Ve
+.SS "Does Perl have a \fBround()\fP function? What about \fBceil()\fP and \fBfloor()\fP? Trig functions?"
+.IX Subsection "Does Perl have a round() function? What about ceil() and floor()? Trig functions?"
+Remember that \f(CWint()\fR merely truncates toward 0. For rounding to a
+certain number of digits, \f(CWsprintf()\fR or \f(CWprintf()\fR is usually the
+easiest route.
+.PP
+.Vb 1
+\&    printf("%.3f", 3.1415926535);   # prints 3.142
+.Ve
+.PP
+The POSIX module (part of the standard Perl distribution)
+implements \f(CWceil()\fR, \f(CWfloor()\fR, and a number of other mathematical
+and trigonometric functions.
+.PP
+.Vb 3
+\&    use POSIX;
+\&    my $ceil   = ceil(3.5);   # 4
+\&    my $floor  = floor(3.5);  # 3
+.Ve
+.PP
+In 5.000 to 5.003 perls, trigonometry was done in the Math::Complex
+module. With 5.004, the Math::Trig module (part of the standard Perl
+distribution) implements the trigonometric functions. Internally it
+uses the Math::Complex module and some functions can break out from
+the real axis into the complex plane, for example the inverse sine of
+2.
+.PP
+Rounding in financial applications can have serious implications, and
+the rounding method used should be specified precisely. In these
+cases, it probably pays not to trust whichever system of rounding is
+being used by Perl, but instead to implement the rounding function you
+need yourself.
+.PP
+To see why, notice how you'll still have an issue on half-way-point
+alternation:
+.PP
+.Vb 1
+\&    for (my $i = \-5; $i <= 5; $i += 0.5) { printf "%.0f ",$i }
+\&
+\&    \-5 \-4 \-4 \-4 \-3 \-2 \-2 \-2 \-1 \-0 0 0 1 2 2 2 3 4 4 4 5
+.Ve
+.PP
+Don't blame Perl. It's the same as in C. IEEE says we have to do
+this. Perl numbers whose absolute values are integers under 2**31 (on
+32\-bit machines) will work pretty much like mathematical integers.
+Other numbers are not guaranteed.
+.SS "How do I convert between numeric representations/bases/radixes?"
+.IX Subsection "How do I convert between numeric representations/bases/radixes?"
+As always with Perl there is more than one way to do it. Below are a
+few examples of approaches to making common conversions between number
+representations. This is intended to be representational rather than
+exhaustive.
+.PP
+Some of the examples later in perlfaq4 use the Bit::Vector
+module from CPAN. The reason you might choose Bit::Vector over the
+perl built-in functions is that it works with numbers of ANY size,
+that it is optimized for speed on some operations, and for at least
+some programmers the notation might be familiar.
+.IP "How do I convert hexadecimal into decimal" 4
+.IX Item "How do I convert hexadecimal into decimal"
+Using perl's built in conversion of \f(CW\*(C`0x\*(C'\fR notation:
+.Sp
+.Vb 1
+\&    my $dec = 0xDEADBEEF;
+.Ve
+.Sp
+Using the \f(CW\*(C`hex\*(C'\fR function:
+.Sp
+.Vb 1
+\&    my $dec = hex("DEADBEEF");
+.Ve
+.Sp
+Using \f(CW\*(C`pack\*(C'\fR:
+.Sp
+.Vb 1
+\&    my $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", \-8)));
+.Ve
+.Sp
+Using the CPAN module \f(CW\*(C`Bit::Vector\*(C'\fR:
+.Sp
+.Vb 3
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new_Hex(32, "DEADBEEF");
+\&    my $dec = $vec\->to_Dec();
+.Ve
+.IP "How do I convert from decimal to hexadecimal" 4
+.IX Item "How do I convert from decimal to hexadecimal"
+Using \f(CW\*(C`sprintf\*(C'\fR:
+.Sp
+.Vb 2
+\&    my $hex = sprintf("%X", 3735928559); # upper case A\-F
+\&    my $hex = sprintf("%x", 3735928559); # lower case a\-f
+.Ve
+.Sp
+Using \f(CW\*(C`unpack\*(C'\fR:
+.Sp
+.Vb 1
+\&    my $hex = unpack("H*", pack("N", 3735928559));
+.Ve
+.Sp
+Using Bit::Vector:
+.Sp
+.Vb 3
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new_Dec(32, \-559038737);
+\&    my $hex = $vec\->to_Hex();
+.Ve
+.Sp
+And Bit::Vector supports odd bit counts:
+.Sp
+.Vb 4
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new_Dec(33, 3735928559);
+\&    $vec\->Resize(32); # suppress leading 0 if unwanted
+\&    my $hex = $vec\->to_Hex();
+.Ve
+.IP "How do I convert from octal to decimal" 4
+.IX Item "How do I convert from octal to decimal"
+Using Perl's built in conversion of numbers with leading zeros:
+.Sp
+.Vb 1
+\&    my $dec = 033653337357; # note the leading 0!
+.Ve
+.Sp
+Using the \f(CW\*(C`oct\*(C'\fR function:
+.Sp
+.Vb 1
+\&    my $dec = oct("33653337357");
+.Ve
+.Sp
+Using Bit::Vector:
+.Sp
+.Vb 4
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new(32);
+\&    $vec\->Chunk_List_Store(3, split(//, reverse "33653337357"));
+\&    my $dec = $vec\->to_Dec();
+.Ve
+.IP "How do I convert from decimal to octal" 4
+.IX Item "How do I convert from decimal to octal"
+Using \f(CW\*(C`sprintf\*(C'\fR:
+.Sp
+.Vb 1
+\&    my $oct = sprintf("%o", 3735928559);
+.Ve
+.Sp
+Using Bit::Vector:
+.Sp
+.Vb 3
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new_Dec(32, \-559038737);
+\&    my $oct = reverse join(\*(Aq\*(Aq, $vec\->Chunk_List_Read(3));
+.Ve
+.IP "How do I convert from binary to decimal" 4
+.IX Item "How do I convert from binary to decimal"
+Perl 5.6 lets you write binary numbers directly with
+the \f(CW\*(C`0b\*(C'\fR notation:
+.Sp
+.Vb 1
+\&    my $number = 0b10110110;
+.Ve
+.Sp
+Using \f(CW\*(C`oct\*(C'\fR:
+.Sp
+.Vb 2
+\&    my $input = "10110110";
+\&    my $decimal = oct( "0b$input" );
+.Ve
+.Sp
+Using \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`ord\*(C'\fR:
+.Sp
+.Vb 1
+\&    my $decimal = ord(pack(\*(AqB8\*(Aq, \*(Aq10110110\*(Aq));
+.Ve
+.Sp
+Using \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR for larger strings:
+.Sp
+.Vb 3
+\&    my $int = unpack("N", pack("B32",
+\&    substr("0" x 32 . "11110101011011011111011101111", \-32)));
+\&    my $dec = sprintf("%d", $int);
+\&
+\&    # substr() is used to left\-pad a 32\-character string with zeros.
+.Ve
+.Sp
+Using Bit::Vector:
+.Sp
+.Vb 2
+\&    my $vec = Bit::Vector\->new_Bin(32, "11011110101011011011111011101111");
+\&    my $dec = $vec\->to_Dec();
+.Ve
+.IP "How do I convert from decimal to binary" 4
+.IX Item "How do I convert from decimal to binary"
+Using \f(CW\*(C`sprintf\*(C'\fR (perl 5.6+):
+.Sp
+.Vb 1
+\&    my $bin = sprintf("%b", 3735928559);
+.Ve
+.Sp
+Using \f(CW\*(C`unpack\*(C'\fR:
+.Sp
+.Vb 1
+\&    my $bin = unpack("B*", pack("N", 3735928559));
+.Ve
+.Sp
+Using Bit::Vector:
+.Sp
+.Vb 3
+\&    use Bit::Vector;
+\&    my $vec = Bit::Vector\->new_Dec(32, \-559038737);
+\&    my $bin = $vec\->to_Bin();
+.Ve
+.Sp
+The remaining transformations (e.g. hex \-> oct, bin \-> hex, etc.)
+are left as an exercise to the inclined reader.
+.SS "Why doesn't & work the way I want it to?"
+.IX Subsection "Why doesn't & work the way I want it to?"
+The behavior of binary arithmetic operators depends on whether they're
+used on numbers or strings. The operators treat a string as a series
+of bits and work with that (the string \f(CW"3"\fR is the bit pattern
+\&\f(CW00110011\fR). The operators work with the binary form of a number
+(the number \f(CW3\fR is treated as the bit pattern \f(CW00000011\fR).
+.PP
+So, saying \f(CW\*(C`11 & 3\*(C'\fR performs the "and" operation on numbers (yielding
+\&\f(CW3\fR). Saying \f(CW"11" & "3"\fR performs the "and" operation on strings
+(yielding \f(CW"1"\fR).
+.PP
+Most problems with \f(CW\*(C`&\*(C'\fR and \f(CW\*(C`|\*(C'\fR arise because the programmer thinks
+they have a number but really it's a string or vice versa. To avoid this,
+stringify the arguments explicitly (using \f(CW""\fR or \f(CWqq()\fR) or convert them
+to numbers explicitly (using \f(CW\*(C`0+$arg\*(C'\fR). The rest arise because
+the programmer says:
+.PP
+.Vb 3
+\&    if ("\e020\e020" & "\e101\e101") {
+\&        # ...
+\&    }
+.Ve
+.PP
+but a string consisting of two null bytes (the result of \f(CW"\e020\e020"
+& "\e101\e101"\fR) is not a false value in Perl. You need:
+.PP
+.Vb 3
+\&    if ( ("\e020\e020" & "\e101\e101") !~ /[^\e000]/) {
+\&        # ...
+\&    }
+.Ve
+.SS "How do I multiply matrices?"
+.IX Subsection "How do I multiply matrices?"
+Use the Math::Matrix or Math::MatrixReal modules (available from CPAN)
+or the PDL extension (also available from CPAN).
+.SS "How do I perform an operation on a series of integers?"
+.IX Subsection "How do I perform an operation on a series of integers?"
+To call a function on each element in an array, and collect the
+results, use:
+.PP
+.Vb 1
+\&    my @results = map { my_func($_) } @array;
+.Ve
+.PP
+For example:
+.PP
+.Vb 1
+\&    my @triple = map { 3 * $_ } @single;
+.Ve
+.PP
+To call a function on each element of an array, but ignore the
+results:
+.PP
+.Vb 3
+\&    foreach my $iterator (@array) {
+\&        some_func($iterator);
+\&    }
+.Ve
+.PP
+To call a function on each integer in a (small) range, you \fBcan\fR use:
+.PP
+.Vb 1
+\&    my @results = map { some_func($_) } (5 .. 25);
+.Ve
+.PP
+but you should be aware that in this form, the \f(CW\*(C`..\*(C'\fR operator
+creates a list of all integers in the range, which can take a lot of
+memory for large ranges. However, the problem does not occur when
+using \f(CW\*(C`..\*(C'\fR within a \f(CW\*(C`for\*(C'\fR loop, because in that case the range
+operator is optimized to \fIiterate\fR over the range, without creating
+the entire list. So
+.PP
+.Vb 4
+\&    my @results = ();
+\&    for my $i (5 .. 500_005) {
+\&        push(@results, some_func($i));
+\&    }
+.Ve
+.PP
+or even
+.PP
+.Vb 1
+\&   push(@results, some_func($_)) for 5 .. 500_005;
+.Ve
+.PP
+will not create an intermediate list of 500,000 integers.
+.SS "How can I output Roman numerals?"
+.IX Subsection "How can I output Roman numerals?"
+Get the <http://www.cpan.org/modules/by\-module/Roman> module.
+.SS "Why aren't my random numbers random?"
+.IX Subsection "Why aren't my random numbers random?"
+If you're using a version of Perl before 5.004, you must call \f(CW\*(C`srand\*(C'\fR
+once at the start of your program to seed the random number generator.
+.PP
+.Vb 1
+\&     BEGIN { srand() if $] < 5.004 }
+.Ve
+.PP
+5.004 and later automatically call \f(CW\*(C`srand\*(C'\fR at the beginning. Don't
+call \f(CW\*(C`srand\*(C'\fR more than once\-\-you make your numbers less random,
+rather than more.
+.PP
+Computers are good at being predictable and bad at being random
+(despite appearances caused by bugs in your programs :\-). The
+\&\fIrandom\fR article in the "Far More Than You Ever Wanted To Know"
+collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>, courtesy
+of Tom Phoenix, talks more about this. John von Neumann said, "Anyone
+who attempts to generate random numbers by deterministic means is, of
+course, living in a state of sin."
+.PP
+Perl relies on the underlying system for the implementation of
+\&\f(CW\*(C`rand\*(C'\fR and \f(CW\*(C`srand\*(C'\fR; on some systems, the generated numbers are
+not random enough (especially on Windows : see
+<http://www.perlmonks.org/?node_id=803632>).
+Several CPAN modules in the \f(CW\*(C`Math\*(C'\fR namespace implement better
+pseudorandom generators; see for example
+Math::Random::MT ("Mersenne Twister", fast), or
+Math::TrulyRandom (uses the imperfections in the system's
+timer to generate random numbers, which is rather slow).
+More algorithms for random numbers are described in
+"Numerical Recipes in C" at <http://www.nr.com/>
+.SS "How do I get a random number between X and Y?"
+.IX Subsection "How do I get a random number between X and Y?"
+To get a random number between two values, you can use the \f(CWrand()\fR
+built-in to get a random number between 0 and 1. From there, you shift
+that into the range that you want.
+.PP
+\&\f(CWrand($x)\fR returns a number such that \f(CW\*(C`0 <= rand($x) < $x\*(C'\fR. Thus
+what you want to have perl figure out is a random number in the range
+from 0 to the difference between your \fIX\fR and \fIY\fR.
+.PP
+That is, to get a number between 10 and 15, inclusive, you want a
+random number between 0 and 5 that you can then add to 10.
+.PP
+.Vb 1
+\&    my $number = 10 + int rand( 15\-10+1 ); # ( 10,11,12,13,14, or 15 )
+.Ve
+.PP
+Hence you derive the following simple function to abstract
+that. It selects a random integer between the two given
+integers (inclusive). For example: \f(CW\*(C`random_int_between(50,120)\*(C'\fR.
+.PP
+.Vb 7
+\&    sub random_int_between {
+\&        my($min, $max) = @_;
+\&        # Assumes that the two arguments are integers themselves!
+\&        return $min if $min == $max;
+\&        ($min, $max) = ($max, $min)  if  $min > $max;
+\&        return $min + int rand(1 + $max \- $min);
+\&    }
+.Ve
+.SH "Data: Dates"
+.IX Header "Data: Dates"
+.SS "How do I find the day or week of the year?"
+.IX Subsection "How do I find the day or week of the year?"
+The day of the year is in the list returned
+by the \f(CW\*(C`localtime\*(C'\fR function. Without an
+argument \f(CW\*(C`localtime\*(C'\fR uses the current time.
+.PP
+.Vb 1
+\&    my $day_of_year = (localtime)[7];
+.Ve
+.PP
+The POSIX module can also format a date as the day of the year or
+week of the year.
+.PP
+.Vb 3
+\&    use POSIX qw/strftime/;
+\&    my $day_of_year  = strftime "%j", localtime;
+\&    my $week_of_year = strftime "%W", localtime;
+.Ve
+.PP
+To get the day of year for any date, use POSIX's \f(CW\*(C`mktime\*(C'\fR to get
+a time in epoch seconds for the argument to \f(CW\*(C`localtime\*(C'\fR.
+.PP
+.Vb 3
+\&    use POSIX qw/mktime strftime/;
+\&    my $week_of_year = strftime "%W",
+\&        localtime( mktime( 0, 0, 0, 18, 11, 87 ) );
+.Ve
+.PP
+You can also use Time::Piece, which comes with Perl and provides a
+\&\f(CW\*(C`localtime\*(C'\fR that returns an object:
+.PP
+.Vb 3
+\&    use Time::Piece;
+\&    my $day_of_year  = localtime\->yday;
+\&    my $week_of_year = localtime\->week;
+.Ve
+.PP
+The Date::Calc module provides two functions to calculate these, too:
+.PP
+.Vb 3
+\&    use Date::Calc;
+\&    my $day_of_year  = Day_of_Year(  1987, 12, 18 );
+\&    my $week_of_year = Week_of_Year( 1987, 12, 18 );
+.Ve
+.SS "How do I find the current century or millennium?"
+.IX Subsection "How do I find the current century or millennium?"
+Use the following simple functions:
+.PP
+.Vb 3
+\&    sub get_century    {
+\&        return int((((localtime(shift || time))[5] + 1999))/100);
+\&    }
+\&
+\&    sub get_millennium {
+\&        return 1+int((((localtime(shift || time))[5] + 1899))/1000);
+\&    }
+.Ve
+.PP
+On some systems, the POSIX module's \f(CWstrftime()\fR function has been
+extended in a non-standard way to use a \f(CW%C\fR format, which they
+sometimes claim is the "century". It isn't, because on most such
+systems, this is only the first two digits of the four-digit year, and
+thus cannot be used to determine reliably the current century or
+millennium.
+.SS "How can I compare two dates and find the difference?"
+.IX Subsection "How can I compare two dates and find the difference?"
+(contributed by brian d foy)
+.PP
+You could just store all your dates as a number and then subtract.
+Life isn't always that simple though.
+.PP
+The Time::Piece module, which comes with Perl, replaces localtime
+with a version that returns an object. It also overloads the comparison
+operators so you can compare them directly:
+.PP
+.Vb 3
+\&    use Time::Piece;
+\&    my $date1 = localtime( $some_time );
+\&    my $date2 = localtime( $some_other_time );
+\&
+\&    if( $date1 < $date2 ) {
+\&        print "The date was in the past\en";
+\&    }
+.Ve
+.PP
+You can also get differences with a subtraction, which returns a
+Time::Seconds object:
+.PP
+.Vb 2
+\&    my $date_diff = $date1 \- $date2;
+\&    print "The difference is ", $date_diff\->days, " days\en";
+.Ve
+.PP
+If you want to work with formatted dates, the Date::Manip,
+Date::Calc, or DateTime modules can help you.
+.SS "How can I take a string and turn it into epoch seconds?"
+.IX Subsection "How can I take a string and turn it into epoch seconds?"
+If it's a regular enough string that it always has the same format,
+you can split it up and pass the parts to \f(CW\*(C`timelocal\*(C'\fR in the standard
+Time::Local module. Otherwise, you should look into the Date::Calc,
+Date::Parse, and Date::Manip modules from CPAN.
+.SS "How can I find the Julian Day?"
+.IX Subsection "How can I find the Julian Day?"
+(contributed by brian d foy and Dave Cross)
+.PP
+You can use the Time::Piece module, part of the Standard Library,
+which can convert a date/time to a Julian Day:
+.PP
+.Vb 2
+\&    $ perl \-MTime::Piece \-le \*(Aqprint localtime\->julian_day\*(Aq
+\&    2455607.7959375
+.Ve
+.PP
+Or the modified Julian Day:
+.PP
+.Vb 2
+\&    $ perl \-MTime::Piece \-le \*(Aqprint localtime\->mjd\*(Aq
+\&    55607.2961226851
+.Ve
+.PP
+Or even the day of the year (which is what some people think of as a
+Julian day):
+.PP
+.Vb 2
+\&    $ perl \-MTime::Piece \-le \*(Aqprint localtime\->yday\*(Aq
+\&    45
+.Ve
+.PP
+You can also do the same things with the DateTime module:
+.PP
+.Vb 6
+\&    $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->jd\*(Aq
+\&    2453401.5
+\&    $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->mjd\*(Aq
+\&    53401
+\&    $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->doy\*(Aq
+\&    31
+.Ve
+.PP
+You can use the Time::JulianDay module available on CPAN. Ensure
+that you really want to find a Julian day, though, as many people have
+different ideas about Julian days (see <http://www.hermetic.ch/cal_stud/jdn.htm>
+for instance):
+.PP
+.Vb 2
+\&    $  perl \-MTime::JulianDay \-le \*(Aqprint local_julian_day( time )\*(Aq
+\&    55608
+.Ve
+.SS "How do I find yesterday's date?"
+.IX Xref "date yesterday DateTime Date::Calc Time::Local daylight saving time day Today_and_Now localtime timelocal"
+.IX Subsection "How do I find yesterday's date?"
+(contributed by brian d foy)
+.PP
+To do it correctly, you can use one of the \f(CW\*(C`Date\*(C'\fR modules since they
+work with calendars instead of times. The DateTime module makes it
+simple, and give you the same time of day, only the day before,
+despite daylight saving time changes:
+.PP
+.Vb 1
+\&    use DateTime;
+\&
+\&    my $yesterday = DateTime\->now\->subtract( days => 1 );
+\&
+\&    print "Yesterday was $yesterday\en";
+.Ve
+.PP
+You can also use the Date::Calc module using its \f(CW\*(C`Today_and_Now\*(C'\fR
+function.
+.PP
+.Vb 1
+\&    use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
+\&
+\&    my @date_time = Add_Delta_DHMS( Today_and_Now(), \-1, 0, 0, 0 );
+\&
+\&    print "@date_time\en";
+.Ve
+.PP
+Most people try to use the time rather than the calendar to figure out
+dates, but that assumes that days are twenty-four hours each. For
+most people, there are two days a year when they aren't: the switch to
+and from summer time throws this off. For example, the rest of the
+suggestions will be wrong sometimes:
+.PP
+Starting with Perl 5.10, Time::Piece and Time::Seconds are part
+of the standard distribution, so you might think that you could do
+something like this:
+.PP
+.Vb 2
+\&    use Time::Piece;
+\&    use Time::Seconds;
+\&
+\&    my $yesterday = localtime() \- ONE_DAY; # WRONG
+\&    print "Yesterday was $yesterday\en";
+.Ve
+.PP
+The Time::Piece module exports a new \f(CW\*(C`localtime\*(C'\fR that returns an
+object, and Time::Seconds exports the \f(CW\*(C`ONE_DAY\*(C'\fR constant that is a
+set number of seconds. This means that it always gives the time 24
+hours ago, which is not always yesterday. This can cause problems
+around the end of daylight saving time when there's one day that is 25
+hours long.
+.PP
+You have the same problem with Time::Local, which will give the wrong
+answer for those same special cases:
+.PP
+.Vb 5
+\&    # contributed by Gunnar Hjalmarsson
+\&     use Time::Local;
+\&     my $today = timelocal 0, 0, 12, ( localtime )[3..5];
+\&     my ($d, $m, $y) = ( localtime $today\-86400 )[3..5]; # WRONG
+\&     printf "Yesterday: %d\-%02d\-%02d\en", $y+1900, $m+1, $d;
+.Ve
+.SS "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?"
+.IX Subsection "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?"
+(contributed by brian d foy)
+.PP
+Perl itself never had a Y2K problem, although that never stopped people
+from creating Y2K problems on their own. See the documentation for
+\&\f(CW\*(C`localtime\*(C'\fR for its proper use.
+.PP
+Starting with Perl 5.12, \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR can handle dates past
+03:14:08 January 19, 2038, when a 32\-bit based time would overflow. You
+still might get a warning on a 32\-bit \f(CW\*(C`perl\*(C'\fR:
+.PP
+.Vb 3
+\&    % perl5.12 \-E \*(Aqsay scalar localtime( 0x9FFF_FFFFFFFF )\*(Aq
+\&    Integer overflow in hexadecimal number at \-e line 1.
+\&    Wed Nov  1 19:42:39 5576711
+.Ve
+.PP
+On a 64\-bit \f(CW\*(C`perl\*(C'\fR, you can get even larger dates for those really long
+running projects:
+.PP
+.Vb 2
+\&    % perl5.12 \-E \*(Aqsay scalar gmtime( 0x9FFF_FFFFFFFF )\*(Aq
+\&    Thu Nov  2 00:42:39 5576711
+.Ve
+.PP
+You're still out of luck if you need to keep track of decaying protons
+though.
+.SH "Data: Strings"
+.IX Header "Data: Strings"
+.SS "How do I validate input?"
+.IX Subsection "How do I validate input?"
+(contributed by brian d foy)
+.PP
+There are many ways to ensure that values are what you expect or
+want to accept. Besides the specific examples that we cover in the
+perlfaq, you can also look at the modules with "Assert" and "Validate"
+in their names, along with other modules such as Regexp::Common.
+.PP
+Some modules have validation for particular types of input, such
+as Business::ISBN, Business::CreditCard, Email::Valid,
+and Data::Validate::IP.
+.SS "How do I unescape a string?"
+.IX Subsection "How do I unescape a string?"
+It depends just what you mean by "escape". URL escapes are dealt
+with in perlfaq9. Shell escapes with the backslash (\f(CW\*(C`\e\*(C'\fR)
+character are removed with
+.PP
+.Vb 1
+\&    s/\e\e(.)/$1/g;
+.Ve
+.PP
+This won't expand \f(CW"\en"\fR or \f(CW"\et"\fR or any other special escapes.
+.SS "How do I remove consecutive pairs of characters?"
+.IX Subsection "How do I remove consecutive pairs of characters?"
+(contributed by brian d foy)
+.PP
+You can use the substitution operator to find pairs of characters (or
+runs of characters) and replace them with a single instance. In this
+substitution, we find a character in \f(CW\*(C`(.)\*(C'\fR. The memory parentheses
+store the matched character in the back-reference \f(CW\*(C`\eg1\*(C'\fR and we use
+that to require that the same thing immediately follow it. We replace
+that part of the string with the character in \f(CW$1\fR.
+.PP
+.Vb 1
+\&    s/(.)\eg1/$1/g;
+.Ve
+.PP
+We can also use the transliteration operator, \f(CW\*(C`tr///\*(C'\fR. In this
+example, the search list side of our \f(CW\*(C`tr///\*(C'\fR contains nothing, but
+the \f(CW\*(C`c\*(C'\fR option complements that so it contains everything. The
+replacement list also contains nothing, so the transliteration is
+almost a no-op since it won't do any replacements (or more exactly,
+replace the character with itself). However, the \f(CW\*(C`s\*(C'\fR option squashes
+duplicated and consecutive characters in the string so a character
+does not show up next to itself
+.PP
+.Vb 2
+\&    my $str = \*(AqHaarlem\*(Aq;   # in the Netherlands
+\&    $str =~ tr///cs;       # Now Harlem, like in New York
+.Ve
+.SS "How do I expand function calls in a string?"
+.IX Subsection "How do I expand function calls in a string?"
+(contributed by brian d foy)
+.PP
+This is documented in perlref, and although it's not the easiest
+thing to read, it does work. In each of these examples, we call the
+function inside the braces used to dereference a reference. If we
+have more than one return value, we can construct and dereference an
+anonymous array. In this case, we call the function in list context.
+.PP
+.Vb 1
+\&    print "The time values are @{ [localtime] }.\en";
+.Ve
+.PP
+If we want to call the function in scalar context, we have to do a bit
+more work. We can really have any code we like inside the braces, so
+we simply have to end with the scalar reference, although how you do
+that is up to you, and you can use code inside the braces. Note that
+the use of parens creates a list context, so we need \f(CW\*(C`scalar\*(C'\fR to
+force the scalar context on the function:
+.PP
+.Vb 1
+\&    print "The time is ${\e(scalar localtime)}.\en"
+\&
+\&    print "The time is ${ my $x = localtime; \e$x }.\en";
+.Ve
+.PP
+If your function already returns a reference, you don't need to create
+the reference yourself.
+.PP
+.Vb 1
+\&    sub timestamp { my $t = localtime; \e$t }
+\&
+\&    print "The time is ${ timestamp() }.\en";
+.Ve
+.PP
+The \f(CW\*(C`Interpolation\*(C'\fR module can also do a lot of magic for you. You can
+specify a variable name, in this case \f(CW\*(C`E\*(C'\fR, to set up a tied hash that
+does the interpolation for you. It has several other methods to do this
+as well.
+.PP
+.Vb 2
+\&    use Interpolation E => \*(Aqeval\*(Aq;
+\&    print "The time values are $E{localtime()}.\en";
+.Ve
+.PP
+In most cases, it is probably easier to simply use string concatenation,
+which also forces scalar context.
+.PP
+.Vb 1
+\&    print "The time is " . localtime() . ".\en";
+.Ve
+.SS "How do I find matching/nesting anything?"
+.IX Subsection "How do I find matching/nesting anything?"
+To find something between two single
+characters, a pattern like \f(CW\*(C`/x([^x]*)x/\*(C'\fR will get the intervening
+bits in \f(CW$1\fR. For multiple ones, then something more like
+\&\f(CW\*(C`/alpha(.*?)omega/\*(C'\fR would be needed. For nested patterns
+and/or balanced expressions, see the so-called
+(?PARNO)
+construct (available since perl 5.10).
+The CPAN module Regexp::Common can help to build such
+regular expressions (see in particular
+Regexp::Common::balanced and Regexp::Common::delimited).
+.PP
+More complex cases will require to write a parser, probably
+using a parsing module from CPAN, like
+Regexp::Grammars, Parse::RecDescent, Parse::Yapp,
+Text::Balanced, or Marpa::R2.
+.SS "How do I reverse a string?"
+.IX Subsection "How do I reverse a string?"
+Use \f(CWreverse()\fR in scalar context, as documented in
+"reverse" in perlfunc.
+.PP
+.Vb 1
+\&    my $reversed = reverse $string;
+.Ve
+.SS "How do I expand tabs in a string?"
+.IX Subsection "How do I expand tabs in a string?"
+You can do it yourself:
+.PP
+.Vb 1
+\&    1 while $string =~ s/\et+/\*(Aq \*(Aq x (length($&) * 8 \- length($\`) % 8)/e;
+.Ve
+.PP
+Or you can just use the Text::Tabs module (part of the standard Perl
+distribution).
+.PP
+.Vb 2
+\&    use Text::Tabs;
+\&    my @expanded_lines = expand(@lines_with_tabs);
+.Ve
+.SS "How do I reformat a paragraph?"
+.IX Subsection "How do I reformat a paragraph?"
+Use Text::Wrap (part of the standard Perl distribution):
+.PP
+.Vb 2
+\&    use Text::Wrap;
+\&    print wrap("\et", \*(Aq  \*(Aq, @paragraphs);
+.Ve
+.PP
+The paragraphs you give to Text::Wrap should not contain embedded
+newlines. Text::Wrap doesn't justify the lines (flush-right).
+.PP
+Or use the CPAN module Text::Autoformat. Formatting files can be
+easily done by making a shell alias, like so:
+.PP
+.Vb 2
+\&    alias fmt="perl \-i \-MText::Autoformat \-n0777 \e
+\&        \-e \*(Aqprint autoformat $_, {all=>1}\*(Aq $*"
+.Ve
+.PP
+See the documentation for Text::Autoformat to appreciate its many
+capabilities.
+.SS "How can I access or change N characters of a string?"
+.IX Subsection "How can I access or change N characters of a string?"
+You can access the first characters of a string with \fBsubstr()\fR.
+To get the first character, for example, start at position 0
+and grab the string of length 1.
+.PP
+.Vb 2
+\&    my $string = "Just another Perl Hacker";
+\&    my $first_char = substr( $string, 0, 1 );  #  \*(AqJ\*(Aq
+.Ve
+.PP
+To change part of a string, you can use the optional fourth
+argument which is the replacement string.
+.PP
+.Vb 1
+\&    substr( $string, 13, 4, "Perl 5.8.0" );
+.Ve
+.PP
+You can also use \fBsubstr()\fR as an lvalue.
+.PP
+.Vb 1
+\&    substr( $string, 13, 4 ) =  "Perl 5.8.0";
+.Ve
+.SS "How do I change the Nth occurrence of something?"
+.IX Subsection "How do I change the Nth occurrence of something?"
+You have to keep track of N yourself. For example, let's say you want
+to change the fifth occurrence of \f(CW"whoever"\fR or \f(CW"whomever"\fR into
+\&\f(CW"whosoever"\fR or \f(CW"whomsoever"\fR, case insensitively. These
+all assume that \f(CW$_\fR contains the string to be altered.
+.PP
+.Vb 6
+\&    $count = 0;
+\&    s{((whom?)ever)}{
+\&    ++$count == 5       # is it the 5th?
+\&        ? "${2}soever"  # yes, swap
+\&        : $1            # renege and leave it there
+\&        }ige;
+.Ve
+.PP
+In the more general case, you can use the \f(CW\*(C`/g\*(C'\fR modifier in a \f(CW\*(C`while\*(C'\fR
+loop, keeping count of matches.
+.PP
+.Vb 8
+\&    $WANT = 3;
+\&    $count = 0;
+\&    $_ = "One fish two fish red fish blue fish";
+\&    while (/(\ew+)\es+fish\eb/gi) {
+\&        if (++$count == $WANT) {
+\&            print "The third fish is a $1 one.\en";
+\&        }
+\&    }
+.Ve
+.PP
+That prints out: \f(CW"The third fish is a red one."\fR  You can also use a
+repetition count and repeated pattern like this:
+.PP
+.Vb 1
+\&    /(?:\ew+\es+fish\es+){2}(\ew+)\es+fish/i;
+.Ve
+.SS "How can I count the number of occurrences of a substring within a string?"
+.IX Subsection "How can I count the number of occurrences of a substring within a string?"
+There are a number of ways, with varying efficiency. If you want a
+count of a certain single character (X) within a string, you can use the
+\&\f(CW\*(C`tr///\*(C'\fR function like so:
+.PP
+.Vb 3
+\&    my $string = "ThisXlineXhasXsomeXx\*(AqsXinXit";
+\&    my $count = ($string =~ tr/X//);
+\&    print "There are $count X characters in the string";
+.Ve
+.PP
+This is fine if you are just looking for a single character. However,
+if you are trying to count multiple character substrings within a
+larger string, \f(CW\*(C`tr///\*(C'\fR won't work. What you can do is wrap a \fBwhile()\fR
+loop around a global pattern match. For example, let's count negative
+integers:
+.PP
+.Vb 4
+\&    my $string = "\-9 55 48 \-2 23 \-76 4 14 \-44";
+\&    my $count = 0;
+\&    while ($string =~ /\-\ed+/g) { $count++ }
+\&    print "There are $count negative numbers in the string";
+.Ve
+.PP
+Another version uses a global match in list context, then assigns the
+result to a scalar, producing a count of the number of matches.
+.PP
+.Vb 1
+\&    my $count = () = $string =~ /\-\ed+/g;
+.Ve
+.SS "How do I capitalize all the words on one line?"
+.IX Xref "Text::Autoformat capitalize case, title case, sentence"
+.IX Subsection "How do I capitalize all the words on one line?"
+(contributed by brian d foy)
+.PP
+Damian Conway's Text::Autoformat handles all of the thinking
+for you.
+.PP
+.Vb 3
+\&    use Text::Autoformat;
+\&    my $x = "Dr. Strangelove or: How I Learned to Stop ".
+\&      "Worrying and Love the Bomb";
+\&
+\&    print $x, "\en";
+\&    for my $style (qw( sentence title highlight )) {
+\&        print autoformat($x, { case => $style }), "\en";
+\&    }
+.Ve
+.PP
+How do you want to capitalize those words?
+.PP
+.Vb 3
+\&    FRED AND BARNEY\*(AqS LODGE        # all uppercase
+\&    Fred And Barney\*(Aqs Lodge        # title case
+\&    Fred and Barney\*(Aqs Lodge        # highlight case
+.Ve
+.PP
+It's not as easy a problem as it looks. How many words do you think
+are in there? Wait for it... wait for it.... If you answered 5
+you're right. Perl words are groups of \f(CW\*(C`\ew+\*(C'\fR, but that's not what
+you want to capitalize. How is Perl supposed to know not to capitalize
+that \f(CW\*(C`s\*(C'\fR after the apostrophe? You could try a regular expression:
+.PP
+.Vb 6
+\&    $string =~ s/ (
+\&                 (^\ew)    #at the beginning of the line
+\&                   |      # or
+\&                 (\es\ew)   #preceded by whitespace
+\&                   )
+\&                /\eU$1/xg;
+\&
+\&    $string =~ s/([\ew\*(Aq]+)/\eu\eL$1/g;
+.Ve
+.PP
+Now, what if you don't want to capitalize that "and"? Just use
+Text::Autoformat and get on with the next problem. :)
+.SS "How can I split a [character]\-delimited string except when inside [character]?"
+.IX Subsection "How can I split a [character]-delimited string except when inside [character]?"
+Several modules can handle this sort of parsing\-\-Text::Balanced,
+Text::CSV, Text::CSV_XS, and Text::ParseWords, among others.
+.PP
+Take the example case of trying to split a string that is
+comma-separated into its different fields. You can't use \f(CW\*(C`split(/,/)\*(C'\fR
+because you shouldn't split if the comma is inside quotes. For
+example, take a data line like this:
+.PP
+.Vb 1
+\&    SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"
+.Ve
+.PP
+Due to the restriction of the quotes, this is a fairly complex
+problem. Thankfully, we have Jeffrey Friedl, author of
+\&\fIMastering Regular Expressions\fR, to handle these for us. He
+suggests (assuming your string is contained in \f(CW$text\fR):
+.PP
+.Vb 7
+\&     my @new = ();
+\&     push(@new, $+) while $text =~ m{
+\&         "([^\e"\e\e]*(?:\e\e.[^\e"\e\e]*)*)",? # groups the phrase inside the quotes
+\&        | ([^,]+),?
+\&        | ,
+\&     }gx;
+\&     push(@new, undef) if substr($text,\-1,1) eq \*(Aq,\*(Aq;
+.Ve
+.PP
+If you want to represent quotation marks inside a
+quotation-mark-delimited field, escape them with backslashes (eg,
+\&\f(CW"like \e"this\e""\fR.
+.PP
+Alternatively, the Text::ParseWords module (part of the standard
+Perl distribution) lets you say:
+.PP
+.Vb 2
+\&    use Text::ParseWords;
+\&    @new = quotewords(",", 0, $text);
+.Ve
+.PP
+For parsing or generating CSV, though, using Text::CSV rather than
+implementing it yourself is highly recommended; you'll save yourself odd bugs
+popping up later by just using code which has already been tried and tested in
+production for years.
+.SS "How do I strip blank space from the beginning/end of a string?"
+.IX Subsection "How do I strip blank space from the beginning/end of a string?"
+(contributed by brian d foy)
+.PP
+A substitution can do this for you. For a single line, you want to
+replace all the leading or trailing whitespace with nothing. You
+can do that with a pair of substitutions:
+.PP
+.Vb 2
+\&    s/^\es+//;
+\&    s/\es+$//;
+.Ve
+.PP
+You can also write that as a single substitution, although it turns
+out the combined statement is slower than the separate ones. That
+might not matter to you, though:
+.PP
+.Vb 1
+\&    s/^\es+|\es+$//g;
+.Ve
+.PP
+In this regular expression, the alternation matches either at the
+beginning or the end of the string since the anchors have a lower
+precedence than the alternation. With the \f(CW\*(C`/g\*(C'\fR flag, the substitution
+makes all possible matches, so it gets both. Remember, the trailing
+newline matches the \f(CW\*(C`\es+\*(C'\fR, and  the \f(CW\*(C`$\*(C'\fR anchor can match to the
+absolute end of the string, so the newline disappears too. Just add
+the newline to the output, which has the added benefit of preserving
+"blank" (consisting entirely of whitespace) lines which the \f(CW\*(C`^\es+\*(C'\fR
+would remove all by itself:
+.PP
+.Vb 4
+\&    while( <> ) {
+\&        s/^\es+|\es+$//g;
+\&        print "$_\en";
+\&    }
+.Ve
+.PP
+For a multi-line string, you can apply the regular expression to each
+logical line in the string by adding the \f(CW\*(C`/m\*(C'\fR flag (for
+"multi-line"). With the \f(CW\*(C`/m\*(C'\fR flag, the \f(CW\*(C`$\*(C'\fR matches \fIbefore\fR an
+embedded newline, so it doesn't remove it. This pattern still removes
+the newline at the end of the string:
+.PP
+.Vb 1
+\&    $string =~ s/^\es+|\es+$//gm;
+.Ve
+.PP
+Remember that lines consisting entirely of whitespace will disappear,
+since the first part of the alternation can match the entire string
+and replace it with nothing. If you need to keep embedded blank lines,
+you have to do a little more work. Instead of matching any whitespace
+(since that includes a newline), just match the other whitespace:
+.PP
+.Vb 1
+\&    $string =~ s/^[\et\ef ]+|[\et\ef ]+$//mg;
+.Ve
+.SS "How do I pad a string with blanks or pad a number with zeroes?"
+.IX Subsection "How do I pad a string with blanks or pad a number with zeroes?"
+In the following examples, \f(CW$pad_len\fR is the length to which you wish
+to pad the string, \f(CW$text\fR or \f(CW$num\fR contains the string to be padded,
+and \f(CW$pad_char\fR contains the padding character. You can use a single
+character string constant instead of the \f(CW$pad_char\fR variable if you
+know what it is in advance. And in the same way you can use an integer in
+place of \f(CW$pad_len\fR if you know the pad length in advance.
+.PP
+The simplest method uses the \f(CW\*(C`sprintf\*(C'\fR function. It can pad on the left
+or right with blanks and on the left with zeroes and it will not
+truncate the result. The \f(CW\*(C`pack\*(C'\fR function can only pad strings on the
+right with blanks and it will truncate the result to a maximum length of
+\&\f(CW$pad_len\fR.
+.PP
+.Vb 3
+\&    # Left padding a string with blanks (no truncation):
+\&    my $padded = sprintf("%${pad_len}s", $text);
+\&    my $padded = sprintf("%*s", $pad_len, $text);  # same thing
+\&
+\&    # Right padding a string with blanks (no truncation):
+\&    my $padded = sprintf("%\-${pad_len}s", $text);
+\&    my $padded = sprintf("%\-*s", $pad_len, $text); # same thing
+\&
+\&    # Left padding a number with 0 (no truncation):
+\&    my $padded = sprintf("%0${pad_len}d", $num);
+\&    my $padded = sprintf("%0*d", $pad_len, $num); # same thing
+\&
+\&    # Right padding a string with blanks using pack (will truncate):
+\&    my $padded = pack("A$pad_len",$text);
+.Ve
+.PP
+If you need to pad with a character other than blank or zero you can use
+one of the following methods. They all generate a pad string with the
+\&\f(CW\*(C`x\*(C'\fR operator and combine that with \f(CW$text\fR. These methods do
+not truncate \f(CW$text\fR.
+.PP
+Left and right padding with any character, creating a new string:
+.PP
+.Vb 2
+\&    my $padded = $pad_char x ( $pad_len \- length( $text ) ) . $text;
+\&    my $padded = $text . $pad_char x ( $pad_len \- length( $text ) );
+.Ve
+.PP
+Left and right padding with any character, modifying \f(CW$text\fR directly:
+.PP
+.Vb 2
+\&    substr( $text, 0, 0 ) = $pad_char x ( $pad_len \- length( $text ) );
+\&    $text .= $pad_char x ( $pad_len \- length( $text ) );
+.Ve
+.SS "How do I extract selected columns from a string?"
+.IX Subsection "How do I extract selected columns from a string?"
+(contributed by brian d foy)
+.PP
+If you know the columns that contain the data, you can
+use \f(CW\*(C`substr\*(C'\fR to extract a single column.
+.PP
+.Vb 1
+\&    my $column = substr( $line, $start_column, $length );
+.Ve
+.PP
+You can use \f(CW\*(C`split\*(C'\fR if the columns are separated by whitespace or
+some other delimiter, as long as whitespace or the delimiter cannot
+appear as part of the data.
+.PP
+.Vb 3
+\&    my $line    = \*(Aq fred barney   betty   \*(Aq;
+\&    my @columns = split /\es+/, $line;
+\&        # ( \*(Aq\*(Aq, \*(Aqfred\*(Aq, \*(Aqbarney\*(Aq, \*(Aqbetty\*(Aq );
+\&
+\&    my $line    = \*(Aqfred||barney||betty\*(Aq;
+\&    my @columns = split /\e|/, $line;
+\&        # ( \*(Aqfred\*(Aq, \*(Aq\*(Aq, \*(Aqbarney\*(Aq, \*(Aq\*(Aq, \*(Aqbetty\*(Aq );
+.Ve
+.PP
+If you want to work with comma-separated values, don't do this since
+that format is a bit more complicated. Use one of the modules that
+handle that format, such as Text::CSV, Text::CSV_XS, or
+Text::CSV_PP.
+.PP
+If you want to break apart an entire line of fixed columns, you can use
+\&\f(CW\*(C`unpack\*(C'\fR with the A (ASCII) format. By using a number after the format
+specifier, you can denote the column width. See the \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR
+entries in perlfunc for more details.
+.PP
+.Vb 1
+\&    my @fields = unpack( $line, "A8 A8 A8 A16 A4" );
+.Ve
+.PP
+Note that spaces in the format argument to \f(CW\*(C`unpack\*(C'\fR do not denote literal
+spaces. If you have space separated data, you may want \f(CW\*(C`split\*(C'\fR instead.
+.SS "How do I find the soundex value of a string?"
+.IX Subsection "How do I find the soundex value of a string?"
+(contributed by brian d foy)
+.PP
+You can use the \f(CW\*(C`Text::Soundex\*(C'\fR module. If you want to do fuzzy or close
+matching, you might also try the String::Approx, and
+Text::Metaphone, and Text::DoubleMetaphone modules.
+.SS "How can I expand variables in text strings?"
+.IX Subsection "How can I expand variables in text strings?"
+(contributed by brian d foy)
+.PP
+If you can avoid it, don't, or if you can use a templating system,
+such as Text::Template or Template Toolkit, do that instead. You
+might even be able to get the job done with \f(CW\*(C`sprintf\*(C'\fR or \f(CW\*(C`printf\*(C'\fR:
+.PP
+.Vb 1
+\&    my $string = sprintf \*(AqSay hello to %s and %s\*(Aq, $foo, $bar;
+.Ve
+.PP
+However, for the one-off simple case where I don't want to pull out a
+full templating system, I'll use a string that has two Perl scalar
+variables in it. In this example, I want to expand \f(CW$foo\fR and \f(CW$bar\fR
+to their variable's values:
+.PP
+.Vb 3
+\&    my $foo = \*(AqFred\*(Aq;
+\&    my $bar = \*(AqBarney\*(Aq;
+\&    $string = \*(AqSay hello to $foo and $bar\*(Aq;
+.Ve
+.PP
+One way I can do this involves the substitution operator and a double
+\&\f(CW\*(C`/e\*(C'\fR flag. The first \f(CW\*(C`/e\*(C'\fR evaluates \f(CW$1\fR on the replacement side and
+turns it into \f(CW$foo\fR. The second /e starts with \f(CW$foo\fR and replaces
+it with its value. \f(CW$foo\fR, then, turns into 'Fred', and that's finally
+what's left in the string:
+.PP
+.Vb 1
+\&    $string =~ s/(\e$\ew+)/$1/eeg; # \*(AqSay hello to Fred and Barney\*(Aq
+.Ve
+.PP
+The \f(CW\*(C`/e\*(C'\fR will also silently ignore violations of strict, replacing
+undefined variable names with the empty string. Since I'm using the
+\&\f(CW\*(C`/e\*(C'\fR flag (twice even!), I have all of the same security problems I
+have with \f(CW\*(C`eval\*(C'\fR in its string form. If there's something odd in
+\&\f(CW$foo\fR, perhaps something like \f(CW\*(C`@{[ system "rm \-rf /" ]}\*(C'\fR, then
+I could get myself in trouble.
+.PP
+To get around the security problem, I could also pull the values from
+a hash instead of evaluating variable names. Using a single \f(CW\*(C`/e\*(C'\fR, I
+can check the hash to ensure the value exists, and if it doesn't, I
+can replace the missing value with a marker, in this case \f(CW\*(C`???\*(C'\fR to
+signal that I missed something:
+.PP
+.Vb 1
+\&    my $string = \*(AqThis has $foo and $bar\*(Aq;
+\&
+\&    my %Replacements = (
+\&        foo  => \*(AqFred\*(Aq,
+\&        );
+\&
+\&    # $string =~ s/\e$(\ew+)/$Replacements{$1}/g;
+\&    $string =~ s/\e$(\ew+)/
+\&        exists $Replacements{$1} ? $Replacements{$1} : \*(Aq???\*(Aq
+\&        /eg;
+\&
+\&    print $string;
+.Ve
+.SS "Does Perl have anything like Ruby's #{} or Python's f string?"
+.IX Subsection "Does Perl have anything like Ruby's #{} or Python's f string?"
+Unlike the others, Perl allows you to embed a variable naked in a double
+quoted string, e.g. \f(CW"variable $variable"\fR. When there isn't whitespace or
+other non-word characters following the variable name, you can add braces
+(e.g. \f(CW"foo ${foo}bar"\fR) to ensure correct parsing.
+.PP
+An array can also be embedded directly in a string, and will be expanded
+by default with spaces between the elements. The default
+LIST_SEPARATOR can be changed by assigning a
+different string to the special variable \f(CW$"\fR, such as \f(CW\*(C`local $" = \*(Aq, \*(Aq;\*(C'\fR.
+.PP
+Perl also supports references within a string providing the equivalent of
+the features in the other two languages.
+.PP
+\&\f(CW\*(C`${\e ... }\*(C'\fR embedded within a string will work for most simple statements
+such as an object\->method call. More complex code can be wrapped in a do
+block \f(CW\*(C`${\e do{...} }\*(C'\fR.
+.PP
+When you want a list to be expanded per \f(CW$"\fR, use \f(CW\*(C`@{[ ... ]}\*(C'\fR.
+.PP
+.Vb 4
+\&    use Time::Piece;
+\&    use Time::Seconds;
+\&    my $scalar = \*(AqSTRING\*(Aq;
+\&    my @array = ( \*(Aqzorro\*(Aq, \*(Aqa\*(Aq, 1, \*(AqB\*(Aq, 3 );
+\&
+\&    # Print the current date and time and then Tommorrow
+\&    my $t = Time::Piece\->new;
+\&    say "Now is: ${\e $t\->cdate() }";
+\&    say "Tomorrow: ${\e do{ my $T=Time::Piece\->new + ONE_DAY ; $T\->fullday }}";
+\&
+\&    # some variables in strings
+\&    say "This is some scalar I have $scalar, this is an array @array.";
+\&    say "You can also write it like this ${scalar} @{array}.";
+\&
+\&    # Change the $LIST_SEPARATOR
+\&    local $" = \*(Aq:\*(Aq;
+\&    say "Set \e$\e" to delimit with \*(Aq:\*(Aq and sort the Array @{[ sort @array ]}";
+.Ve
+.PP
+You may also want to look at the module
+Quote::Code, and templating tools such as Template::Toolkit and
+Mojo::Template.
+.PP
+See also: "How can I expand variables in text strings?" and
+"How do I expand function calls in a string?" in this FAQ.
+.SS "What's wrong with always quoting ""$vars""?"
+.IX Subsection "What's wrong with always quoting ""$vars""?"
+The problem is that those double-quotes force
+stringification\-\-coercing numbers and references into strings\-\-even
+when you don't want them to be strings. Think of it this way:
+double-quote expansion is used to produce new strings. If you already
+have a string, why do you need more?
+.PP
+If you get used to writing odd things like these:
+.PP
+.Vb 3
+\&    print "$var";       # BAD
+\&    my $new = "$old";       # BAD
+\&    somefunc("$var");    # BAD
+.Ve
+.PP
+You'll be in trouble. Those should (in 99.8% of the cases) be
+the simpler and more direct:
+.PP
+.Vb 3
+\&    print $var;
+\&    my $new = $old;
+\&    somefunc($var);
+.Ve
+.PP
+Otherwise, besides slowing you down, you're going to break code when
+the thing in the scalar is actually neither a string nor a number, but
+a reference:
+.PP
+.Vb 5
+\&    func(\e@array);
+\&    sub func {
+\&        my $aref = shift;
+\&        my $oref = "$aref";  # WRONG
+\&    }
+.Ve
+.PP
+You can also get into subtle problems on those few operations in Perl
+that actually do care about the difference between a string and a
+number, such as the magical \f(CW\*(C`++\*(C'\fR autoincrement operator or the
+\&\fBsyscall()\fR function.
+.PP
+Stringification also destroys arrays.
+.PP
+.Vb 3
+\&    my @lines = \`command\`;
+\&    print "@lines";     # WRONG \- extra blanks
+\&    print @lines;       # right
+.Ve
+.SS "Why don't my <<HERE documents work?"
+.IX Subsection "Why don't my <<HERE documents work?"
+Here documents are found in perlop. Check for these three things:
+.IP "There must be no space after the << part." 4
+.IX Item "There must be no space after the << part."
+.PD 0
+.IP "There (probably) should be a semicolon at the end of the opening token" 4
+.IX Item "There (probably) should be a semicolon at the end of the opening token"
+.IP "You can't (easily) have any space in front of the tag." 4
+.IX Item "You can't (easily) have any space in front of the tag."
+.IP "There needs to be at least a line separator after the end token." 4
+.IX Item "There needs to be at least a line separator after the end token."
+.PD
+.PP
+If you want to indent the text in the here document, you
+can do this:
+.PP
+.Vb 5
+\&    # all in one
+\&    (my $VAR = <<HERE_TARGET) =~ s/^\es+//gm;
+\&        your text
+\&        goes here
+\&    HERE_TARGET
+.Ve
+.PP
+But the HERE_TARGET must still be flush against the margin.
+If you want that indented also, you'll have to quote
+in the indentation.
+.PP
+.Vb 7
+\&    (my $quote = <<\*(Aq    FINIS\*(Aq) =~ s/^\es+//gm;
+\&            ...we will have peace, when you and all your works have
+\&            perished\-\-and the works of your dark master to whom you
+\&            would deliver us. You are a liar, Saruman, and a corrupter
+\&            of men\*(Aqs hearts. \-\-Theoden in /usr/src/perl/taint.c
+\&        FINIS
+\&    $quote =~ s/\es+\-\-/\en\-\-/;
+.Ve
+.PP
+A nice general-purpose fixer-upper function for indented here documents
+follows. It expects to be called with a here document as its argument.
+It looks to see whether each line begins with a common substring, and
+if so, strips that substring off. Otherwise, it takes the amount of leading
+whitespace found on the first line and removes that much off each
+subsequent line.
+.PP
+.Vb 11
+\&    sub fix {
+\&        local $_ = shift;
+\&        my ($white, $leader);  # common whitespace and common leading string
+\&        if (/^\es*(?:([^\ew\es]+)(\es*).*\en)(?:\es*\eg1\eg2?.*\en)+$/) {
+\&            ($white, $leader) = ($2, quotemeta($1));
+\&        } else {
+\&            ($white, $leader) = (/^(\es+)/, \*(Aq\*(Aq);
+\&        }
+\&        s/^\es*?$leader(?:$white)?//gm;
+\&        return $_;
+\&    }
+.Ve
+.PP
+This works with leading special strings, dynamically determined:
+.PP
+.Vb 10
+\&    my $remember_the_main = fix<<\*(Aq    MAIN_INTERPRETER_LOOP\*(Aq;
+\&    @@@ int
+\&    @@@ runops() {
+\&    @@@     SAVEI32(runlevel);
+\&    @@@     runlevel++;
+\&    @@@     while ( op = (*op\->op_ppaddr)() );
+\&    @@@     TAINT_NOT;
+\&    @@@     return 0;
+\&    @@@ }
+\&    MAIN_INTERPRETER_LOOP
+.Ve
+.PP
+Or with a fixed amount of leading whitespace, with remaining
+indentation correctly preserved:
+.PP
+.Vb 9
+\&    my $poem = fix<<EVER_ON_AND_ON;
+\&       Now far ahead the Road has gone,
+\&      And I must follow, if I can,
+\&       Pursuing it with eager feet,
+\&      Until it joins some larger way
+\&       Where many paths and errands meet.
+\&      And whither then? I cannot say.
+\&        \-\-Bilbo in /usr/src/perl/pp_ctl.c
+\&    EVER_ON_AND_ON
+.Ve
+.PP
+Beginning with Perl version 5.26, a much simpler and cleaner way to
+write indented here documents has been added to the language: the
+tilde (~) modifier. See "Indented Here-docs" in perlop for details.
+.SH "Data: Arrays"
+.IX Header "Data: Arrays"
+.SS "What is the difference between a list and an array?"
+.IX Subsection "What is the difference between a list and an array?"
+(contributed by brian d foy)
+.PP
+A list is a fixed collection of scalars. An array is a variable that
+holds a variable collection of scalars. An array can supply its collection
+for list operations, so list operations also work on arrays:
+.PP
+.Vb 3
+\&    # slices
+\&    ( \*(Aqdog\*(Aq, \*(Aqcat\*(Aq, \*(Aqbird\*(Aq )[2,3];
+\&    @animals[2,3];
+\&
+\&    # iteration
+\&    foreach ( qw( dog cat bird ) ) { ... }
+\&    foreach ( @animals ) { ... }
+\&
+\&    my @three = grep { length == 3 } qw( dog cat bird );
+\&    my @three = grep { length == 3 } @animals;
+\&
+\&    # supply an argument list
+\&    wash_animals( qw( dog cat bird ) );
+\&    wash_animals( @animals );
+.Ve
+.PP
+Array operations, which change the scalars, rearrange them, or add
+or subtract some scalars, only work on arrays. These can't work on a
+list, which is fixed. Array operations include \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR,
+\&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, and \f(CW\*(C`splice\*(C'\fR.
+.PP
+An array can also change its length:
+.PP
+.Vb 2
+\&    $#animals = 1;  # truncate to two elements
+\&    $#animals = 10000; # pre\-extend to 10,001 elements
+.Ve
+.PP
+You can change an array element, but you can't change a list element:
+.PP
+.Vb 2
+\&    $animals[0] = \*(AqRottweiler\*(Aq;
+\&    qw( dog cat bird )[0] = \*(AqRottweiler\*(Aq; # syntax error!
+\&
+\&    foreach ( @animals ) {
+\&        s/^d/fr/;  # works fine
+\&    }
+\&
+\&    foreach ( qw( dog cat bird ) ) {
+\&        s/^d/fr/;  # Error! Modification of read only value!
+\&    }
+.Ve
+.PP
+However, if the list element is itself a variable, it appears that you
+can change a list element. However, the list element is the variable, not
+the data. You're not changing the list element, but something the list
+element refers to. The list element itself doesn't change: it's still
+the same variable.
+.PP
+You also have to be careful about context. You can assign an array to
+a scalar to get the number of elements in the array. This only works
+for arrays, though:
+.PP
+.Vb 1
+\&    my $count = @animals;  # only works with arrays
+.Ve
+.PP
+If you try to do the same thing with what you think is a list, you
+get a quite different result. Although it looks like you have a list
+on the righthand side, Perl actually sees a bunch of scalars separated
+by a comma:
+.PP
+.Vb 1
+\&    my $scalar = ( \*(Aqdog\*(Aq, \*(Aqcat\*(Aq, \*(Aqbird\*(Aq );  # $scalar gets bird
+.Ve
+.PP
+Since you're assigning to a scalar, the righthand side is in scalar
+context. The comma operator (yes, it's an operator!) in scalar
+context evaluates its lefthand side, throws away the result, and
+evaluates it's righthand side and returns the result. In effect,
+that list-lookalike assigns to \f(CW$scalar\fR it's rightmost value. Many
+people mess this up because they choose a list-lookalike whose
+last element is also the count they expect:
+.PP
+.Vb 1
+\&    my $scalar = ( 1, 2, 3 );  # $scalar gets 3, accidentally
+.Ve
+.ie n .SS "What is the difference between $array[1] and @array[1]?"
+.el .SS "What is the difference between \f(CW$array\fP[1] and \f(CW@array\fP[1]?"
+.IX Subsection "What is the difference between $array[1] and @array[1]?"
+(contributed by brian d foy)
+.PP
+The difference is the sigil, that special character in front of the
+array name. The \f(CW\*(C`$\*(C'\fR sigil means "exactly one item", while the \f(CW\*(C`@\*(C'\fR
+sigil means "zero or more items". The \f(CW\*(C`$\*(C'\fR gets you a single scalar,
+while the \f(CW\*(C`@\*(C'\fR gets you a list.
+.PP
+The confusion arises because people incorrectly assume that the sigil
+denotes the variable type.
+.PP
+The \f(CW$array[1]\fR is a single-element access to the array. It's going
+to return the item in index 1 (or undef if there is no item there).
+If you intend to get exactly one element from the array, this is the
+form you should use.
+.PP
+The \f(CW@array[1]\fR is an array slice, although it has only one index.
+You can pull out multiple elements simultaneously by specifying
+additional indices as a list, like \f(CW@array[1,4,3,0]\fR.
+.PP
+Using a slice on the lefthand side of the assignment supplies list
+context to the righthand side. This can lead to unexpected results.
+For instance, if you want to read a single line from a filehandle,
+assigning to a scalar value is fine:
+.PP
+.Vb 1
+\&    $array[1] = <STDIN>;
+.Ve
+.PP
+However, in list context, the line input operator returns all of the
+lines as a list. The first line goes into \f(CW@array[1]\fR and the rest
+of the lines mysteriously disappear:
+.PP
+.Vb 1
+\&    @array[1] = <STDIN>;  # most likely not what you want
+.Ve
+.PP
+Either the \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR flag will warn you when
+you use an array slice with a single index.
+.SS "How can I remove duplicate elements from a list or array?"
+.IX Subsection "How can I remove duplicate elements from a list or array?"
+(contributed by brian d foy)
+.PP
+Use a hash. When you think the words "unique" or "duplicated", think
+"hash keys".
+.PP
+If you don't care about the order of the elements, you could just
+create the hash then extract the keys. It's not important how you
+create that hash: just that you use \f(CW\*(C`keys\*(C'\fR to get the unique
+elements.
+.PP
+.Vb 3
+\&    my %hash   = map { $_, 1 } @array;
+\&    # or a hash slice: @hash{ @array } = ();
+\&    # or a foreach: $hash{$_} = 1 foreach ( @array );
+\&
+\&    my @unique = keys %hash;
+.Ve
+.PP
+If you want to use a module, try the \f(CW\*(C`uniq\*(C'\fR function from
+List::MoreUtils. In list context it returns the unique elements,
+preserving their order in the list. In scalar context, it returns the
+number of unique elements.
+.PP
+.Vb 1
+\&    use List::MoreUtils qw(uniq);
+\&
+\&    my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 1,2,3,4,5,6,7
+\&    my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 7
+.Ve
+.PP
+You can also go through each element and skip the ones you've seen
+before. Use a hash to keep track. The first time the loop sees an
+element, that element has no key in \f(CW%Seen\fR. The \f(CW\*(C`next\*(C'\fR statement
+creates the key and immediately uses its value, which is \f(CW\*(C`undef\*(C'\fR, so
+the loop continues to the \f(CW\*(C`push\*(C'\fR and increments the value for that
+key. The next time the loop sees that same element, its key exists in
+the hash \fIand\fR the value for that key is true (since it's not 0 or
+\&\f(CW\*(C`undef\*(C'\fR), so the next skips that iteration and the loop goes to the
+next element.
+.PP
+.Vb 2
+\&    my @unique = ();
+\&    my %seen   = ();
+\&
+\&    foreach my $elem ( @array ) {
+\&        next if $seen{ $elem }++;
+\&        push @unique, $elem;
+\&    }
+.Ve
+.PP
+You can write this more briefly using a grep, which does the
+same thing.
+.PP
+.Vb 2
+\&    my %seen = ();
+\&    my @unique = grep { ! $seen{ $_ }++ } @array;
+.Ve
+.SS "How can I tell whether a certain element is contained in a list or array?"
+.IX Subsection "How can I tell whether a certain element is contained in a list or array?"
+(portions of this answer contributed by Anno Siegel and brian d foy)
+.PP
+Hearing the word "in" is an \fIin\fRdication that you probably should have
+used a hash, not a list or array, to store your data. Hashes are
+designed to answer this question quickly and efficiently. Arrays aren't.
+.PP
+That being said, there are several ways to approach this. If you
+are going to make this query many times over arbitrary string values,
+the fastest way is probably to invert the original array and maintain a
+hash whose keys are the first array's values:
+.PP
+.Vb 3
+\&    my @blues = qw/azure cerulean teal turquoise lapis\-lazuli/;
+\&    my %is_blue = ();
+\&    for (@blues) { $is_blue{$_} = 1 }
+.Ve
+.PP
+Now you can check whether \f(CW$is_blue{$some_color}\fR. It might have
+been a good idea to keep the blues all in a hash in the first place.
+.PP
+If the values are all small integers, you could use a simple indexed
+array. This kind of an array will take up less space:
+.PP
+.Vb 4
+\&    my @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31);
+\&    my @is_tiny_prime = ();
+\&    for (@primes) { $is_tiny_prime[$_] = 1 }
+\&    # or simply  @istiny_prime[@primes] = (1) x @primes;
+.Ve
+.PP
+Now you check whether \f(CW$is_tiny_prime\fR[$some_number].
+.PP
+If the values in question are integers instead of strings, you can save
+quite a lot of space by using bit strings instead:
+.PP
+.Vb 3
+\&    my @articles = ( 1..10, 150..2000, 2017 );
+\&    undef $read;
+\&    for (@articles) { vec($read,$_,1) = 1 }
+.Ve
+.PP
+Now check whether \f(CW\*(C`vec($read,$n,1)\*(C'\fR is true for some \f(CW$n\fR.
+.PP
+These methods guarantee fast individual tests but require a re-organization
+of the original list or array. They only pay off if you have to test
+multiple values against the same array.
+.PP
+If you are testing only once, the standard module List::Util exports
+the function \f(CW\*(C`any\*(C'\fR for this purpose. It works by stopping once it
+finds the element. It's written in C for speed, and its Perl equivalent
+looks like this subroutine:
+.PP
+.Vb 7
+\&    sub any (&@) {
+\&        my $code = shift;
+\&        foreach (@_) {
+\&            return 1 if $code\->();
+\&        }
+\&        return 0;
+\&    }
+.Ve
+.PP
+If speed is of little concern, the common idiom uses grep in scalar context
+(which returns the number of items that passed its condition) to traverse the
+entire list. This does have the benefit of telling you how many matches it
+found, though.
+.PP
+.Vb 1
+\&    my $is_there = grep $_ eq $whatever, @array;
+.Ve
+.PP
+If you want to actually extract the matching elements, simply use grep in
+list context.
+.PP
+.Vb 1
+\&    my @matches = grep $_ eq $whatever, @array;
+.Ve
+.SS "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?"
+.IX Subsection "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?"
+Use a hash. Here's code to do both and more. It assumes that each
+element is unique in a given array:
+.PP
+.Vb 7
+\&    my (@union, @intersection, @difference);
+\&    my %count = ();
+\&    foreach my $element (@array1, @array2) { $count{$element}++ }
+\&    foreach my $element (keys %count) {
+\&        push @union, $element;
+\&        push @{ $count{$element} > 1 ? \e@intersection : \e@difference }, $element;
+\&    }
+.Ve
+.PP
+Note that this is the \fIsymmetric difference\fR, that is, all elements
+in either A or in B but not in both. Think of it as an xor operation.
+.SS "How do I test whether two arrays or hashes are equal?"
+.IX Subsection "How do I test whether two arrays or hashes are equal?"
+The following code works for single-level arrays. It uses a
+stringwise comparison, and does not distinguish defined versus
+undefined empty strings. Modify if you have other needs.
+.PP
+.Vb 1
+\&    $are_equal = compare_arrays(\e@frogs, \e@toads);
+\&
+\&    sub compare_arrays {
+\&        my ($first, $second) = @_;
+\&        no warnings;  # silence spurious \-w undef complaints
+\&        return 0 unless @$first == @$second;
+\&        for (my $i = 0; $i < @$first; $i++) {
+\&            return 0 if $first\->[$i] ne $second\->[$i];
+\&        }
+\&        return 1;
+\&    }
+.Ve
+.PP
+For multilevel structures, you may wish to use an approach more
+like this one. It uses the CPAN module FreezeThaw:
+.PP
+.Vb 2
+\&    use FreezeThaw qw(cmpStr);
+\&    my @a = my @b = ( "this", "that", [ "more", "stuff" ] );
+\&
+\&    printf "a and b contain %s arrays\en",
+\&        cmpStr(\e@a, \e@b) == 0
+\&        ? "the same"
+\&        : "different";
+.Ve
+.PP
+This approach also works for comparing hashes. Here we'll demonstrate
+two different answers:
+.PP
+.Vb 1
+\&    use FreezeThaw qw(cmpStr cmpStrHard);
+\&
+\&    my %a = my %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
+\&    $a{EXTRA} = \e%b;
+\&    $b{EXTRA} = \e%a;
+\&
+\&    printf "a and b contain %s hashes\en",
+\&    cmpStr(\e%a, \e%b) == 0 ? "the same" : "different";
+\&
+\&    printf "a and b contain %s hashes\en",
+\&    cmpStrHard(\e%a, \e%b) == 0 ? "the same" : "different";
+.Ve
+.PP
+The first reports that both those the hashes contain the same data,
+while the second reports that they do not. Which you prefer is left as
+an exercise to the reader.
+.SS "How do I find the first array element for which a condition is true?"
+.IX Subsection "How do I find the first array element for which a condition is true?"
+To find the first array element which satisfies a condition, you can
+use the \f(CWfirst()\fR function in the List::Util module, which comes
+with Perl 5.8. This example finds the first element that contains
+"Perl".
+.PP
+.Vb 1
+\&    use List::Util qw(first);
+\&
+\&    my $element = first { /Perl/ } @array;
+.Ve
+.PP
+If you cannot use List::Util, you can make your own loop to do the
+same thing. Once you find the element, you stop the loop with last.
+.PP
+.Vb 4
+\&    my $found;
+\&    foreach ( @array ) {
+\&        if( /Perl/ ) { $found = $_; last }
+\&    }
+.Ve
+.PP
+If you want the array index, use the \f(CWfirstidx()\fR function from
+\&\f(CW\*(C`List::MoreUtils\*(C'\fR:
+.PP
+.Vb 2
+\&    use List::MoreUtils qw(firstidx);
+\&    my $index = firstidx { /Perl/ } @array;
+.Ve
+.PP
+Or write it yourself, iterating through the indices
+and checking the array element at each index until you find one
+that satisfies the condition:
+.PP
+.Vb 8
+\&    my( $found, $index ) = ( undef, \-1 );
+\&    for( $i = 0; $i < @array; $i++ ) {
+\&        if( $array[$i] =~ /Perl/ ) {
+\&            $found = $array[$i];
+\&            $index = $i;
+\&            last;
+\&        }
+\&    }
+.Ve
+.SS "How do I handle linked lists?"
+.IX Subsection "How do I handle linked lists?"
+(contributed by brian d foy)
+.PP
+Perl's arrays do not have a fixed size, so you don't need linked lists
+if you just want to add or remove items. You can use array operations
+such as \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR, or \f(CW\*(C`splice\*(C'\fR to do
+that.
+.PP
+Sometimes, however, linked lists can be useful in situations where you
+want to "shard" an array so you have many small arrays instead of
+a single big array. You can keep arrays longer than Perl's largest
+array index, lock smaller arrays separately in threaded programs,
+reallocate less memory, or quickly insert elements in the middle of
+the chain.
+.PP
+Steve Lembark goes through the details in his YAPC::NA 2009 talk "Perly
+Linked Lists" ( <http://www.slideshare.net/lembark/perly\-linked\-lists> ),
+although you can just use his LinkedList::Single module.
+.SS "How do I handle circular lists?"
+.IX Xref "circular array Tie::Cycle Array::Iterator::Circular cycle modulus"
+.IX Subsection "How do I handle circular lists?"
+(contributed by brian d foy)
+.PP
+If you want to cycle through an array endlessly, you can increment the
+index modulo the number of elements in the array:
+.PP
+.Vb 2
+\&    my @array = qw( a b c );
+\&    my $i = 0;
+\&
+\&    while( 1 ) {
+\&        print $array[ $i++ % @array ], "\en";
+\&        last if $i > 20;
+\&    }
+.Ve
+.PP
+You can also use Tie::Cycle to use a scalar that always has the
+next element of the circular array:
+.PP
+.Vb 1
+\&    use Tie::Cycle;
+\&
+\&    tie my $cycle, \*(AqTie::Cycle\*(Aq, [ qw( FFFFFF 000000 FFFF00 ) ];
+\&
+\&    print $cycle; # FFFFFF
+\&    print $cycle; # 000000
+\&    print $cycle; # FFFF00
+.Ve
+.PP
+The Array::Iterator::Circular creates an iterator object for
+circular arrays:
+.PP
+.Vb 1
+\&    use Array::Iterator::Circular;
+\&
+\&    my $color_iterator = Array::Iterator::Circular\->new(
+\&        qw(red green blue orange)
+\&        );
+\&
+\&    foreach ( 1 .. 20 ) {
+\&        print $color_iterator\->next, "\en";
+\&    }
+.Ve
+.SS "How do I shuffle an array randomly?"
+.IX Subsection "How do I shuffle an array randomly?"
+If you either have Perl 5.8.0 or later installed, or if you have
+Scalar-List-Utils 1.03 or later installed, you can say:
+.PP
+.Vb 1
+\&    use List::Util \*(Aqshuffle\*(Aq;
+\&
+\&    @shuffled = shuffle(@list);
+.Ve
+.PP
+If not, you can use a Fisher-Yates shuffle.
+.PP
+.Vb 3
+\&    sub fisher_yates_shuffle {
+\&        my $deck = shift;  # $deck is a reference to an array
+\&        return unless @$deck; # must not be empty!
+\&
+\&        my $i = @$deck;
+\&        while (\-\-$i) {
+\&            my $j = int rand ($i+1);
+\&            @$deck[$i,$j] = @$deck[$j,$i];
+\&        }
+\&    }
+\&
+\&    # shuffle my mpeg collection
+\&    #
+\&    my @mpeg = <audio/*/*.mp3>;
+\&    fisher_yates_shuffle( \e@mpeg );    # randomize @mpeg in place
+\&    print @mpeg;
+.Ve
+.PP
+Note that the above implementation shuffles an array in place,
+unlike the \f(CWList::Util::shuffle()\fR which takes a list and returns
+a new shuffled list.
+.PP
+You've probably seen shuffling algorithms that work using splice,
+randomly picking another element to swap the current element with
+.PP
+.Vb 6
+\&    srand;
+\&    @new = ();
+\&    @old = 1 .. 10;  # just a demo
+\&    while (@old) {
+\&        push(@new, splice(@old, rand @old, 1));
+\&    }
+.Ve
+.PP
+This is bad because splice is already O(N), and since you do it N
+times, you just invented a quadratic algorithm; that is, O(N**2).
+This does not scale, although Perl is so efficient that you probably
+won't notice this until you have rather largish arrays.
+.SS "How do I process/modify each element of an array?"
+.IX Subsection "How do I process/modify each element of an array?"
+Use \f(CW\*(C`for\*(C'\fR/\f(CW\*(C`foreach\*(C'\fR:
+.PP
+.Vb 4
+\&    for (@lines) {
+\&        s/foo/bar/;    # change that word
+\&        tr/XZ/ZX/;    # swap those letters
+\&    }
+.Ve
+.PP
+Here's another; let's compute spherical volumes:
+.PP
+.Vb 5
+\&    my @volumes = @radii;
+\&    for (@volumes) {   # @volumes has changed parts
+\&        $_ **= 3;
+\&        $_ *= (4/3) * 3.14159;  # this will be constant folded
+\&    }
+.Ve
+.PP
+which can also be done with \f(CWmap()\fR which is made to transform
+one list into another:
+.PP
+.Vb 1
+\&    my @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;
+.Ve
+.PP
+If you want to do the same thing to modify the values of the
+hash, you can use the \f(CW\*(C`values\*(C'\fR function. As of Perl 5.6
+the values are not copied, so if you modify \f(CW$orbit\fR (in this
+case), you modify the value.
+.PP
+.Vb 3
+\&    for my $orbit ( values %orbits ) {
+\&        ($orbit **= 3) *= (4/3) * 3.14159;
+\&    }
+.Ve
+.PP
+Prior to perl 5.6 \f(CW\*(C`values\*(C'\fR returned copies of the values,
+so older perl code often contains constructions such as
+\&\f(CW@orbits{keys %orbits}\fR instead of \f(CW\*(C`values %orbits\*(C'\fR where
+the hash is to be modified.
+.SS "How do I select a random element from an array?"
+.IX Subsection "How do I select a random element from an array?"
+Use the \f(CWrand()\fR function (see "rand" in perlfunc):
+.PP
+.Vb 2
+\&    my $index   = rand @array;
+\&    my $element = $array[$index];
+.Ve
+.PP
+Or, simply:
+.PP
+.Vb 1
+\&    my $element = $array[ rand @array ];
+.Ve
+.SS "How do I permute N elements of a list?"
+.IX Xref "List::Permutor permute Algorithm::Loops Knuth The Art of Computer Programming Fischer-Krause"
+.IX Subsection "How do I permute N elements of a list?"
+Use the List::Permutor module on CPAN. If the list is actually an
+array, try the Algorithm::Permute module (also on CPAN). It's
+written in XS code and is very efficient:
+.PP
+.Vb 1
+\&    use Algorithm::Permute;
+\&
+\&    my @array = \*(Aqa\*(Aq..\*(Aqd\*(Aq;
+\&    my $p_iterator = Algorithm::Permute\->new ( \e@array );
+\&
+\&    while (my @perm = $p_iterator\->next) {
+\&       print "next permutation: (@perm)\en";
+\&    }
+.Ve
+.PP
+For even faster execution, you could do:
+.PP
+.Vb 1
+\&    use Algorithm::Permute;
+\&
+\&    my @array = \*(Aqa\*(Aq..\*(Aqd\*(Aq;
+\&
+\&    Algorithm::Permute::permute {
+\&        print "next permutation: (@array)\en";
+\&    } @array;
+.Ve
+.PP
+Here's a little program that generates all permutations of all the
+words on each line of input. The algorithm embodied in the
+\&\f(CWpermute()\fR function is discussed in Volume 4 (still unpublished) of
+Knuth's \fIThe Art of Computer Programming\fR and will work on any list:
+.PP
+.Vb 2
+\&    #!/usr/bin/perl \-n
+\&    # Fischer\-Krause ordered permutation generator
+\&
+\&    sub permute (&@) {
+\&        my $code = shift;
+\&        my @idx = 0..$#_;
+\&        while ( $code\->(@_[@idx]) ) {
+\&            my $p = $#idx;
+\&            \-\-$p while $idx[$p\-1] > $idx[$p];
+\&            my $q = $p or return;
+\&            push @idx, reverse splice @idx, $p;
+\&            ++$q while $idx[$p\-1] > $idx[$q];
+\&            @idx[$p\-1,$q]=@idx[$q,$p\-1];
+\&        }
+\&    }
+\&
+\&    permute { print "@_\en" } split;
+.Ve
+.PP
+The Algorithm::Loops module also provides the \f(CW\*(C`NextPermute\*(C'\fR and
+\&\f(CW\*(C`NextPermuteNum\*(C'\fR functions which efficiently find all unique permutations
+of an array, even if it contains duplicate values, modifying it in-place:
+if its elements are in reverse-sorted order then the array is reversed,
+making it sorted, and it returns false; otherwise the next
+permutation is returned.
+.PP
+\&\f(CW\*(C`NextPermute\*(C'\fR uses string order and \f(CW\*(C`NextPermuteNum\*(C'\fR numeric order, so
+you can enumerate all the permutations of \f(CW0..9\fR like this:
+.PP
+.Vb 1
+\&    use Algorithm::Loops qw(NextPermuteNum);
+\&
+\&    my @list= 0..9;
+\&    do { print "@list\en" } while NextPermuteNum @list;
+.Ve
+.SS "How do I sort an array by (anything)?"
+.IX Subsection "How do I sort an array by (anything)?"
+Supply a comparison function to \fBsort()\fR (described in "sort" in perlfunc):
+.PP
+.Vb 1
+\&    @list = sort { $a <=> $b } @list;
+.Ve
+.PP
+The default sort function is cmp, string comparison, which would
+sort \f(CW\*(C`(1, 2, 10)\*(C'\fR into \f(CW\*(C`(1, 10, 2)\*(C'\fR. \f(CW\*(C`<=>\*(C'\fR, used above, is
+the numerical comparison operator.
+.PP
+If you have a complicated function needed to pull out the part you
+want to sort on, then don't do it inside the sort function. Pull it
+out first, because the sort BLOCK can be called many times for the
+same element. Here's an example of how to pull out the first word
+after the first number on each item, and then sort those words
+case-insensitively.
+.PP
+.Vb 7
+\&    my @idx;
+\&    for (@data) {
+\&        my $item;
+\&        ($item) = /\ed+\es*(\eS+)/;
+\&        push @idx, uc($item);
+\&    }
+\&    my @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];
+.Ve
+.PP
+which could also be written this way, using a trick
+that's come to be known as the Schwartzian Transform:
+.PP
+.Vb 3
+\&    my @sorted = map  { $_\->[0] }
+\&        sort { $a\->[1] cmp $b\->[1] }
+\&        map  { [ $_, uc( (/\ed+\es*(\eS+)/)[0]) ] } @data;
+.Ve
+.PP
+If you need to sort on several fields, the following paradigm is useful.
+.PP
+.Vb 5
+\&    my @sorted = sort {
+\&        field1($a) <=> field1($b) ||
+\&        field2($a) cmp field2($b) ||
+\&        field3($a) cmp field3($b)
+\&    } @data;
+.Ve
+.PP
+This can be conveniently combined with precalculation of keys as given
+above.
+.PP
+See the \fIsort\fR article in the "Far More Than You Ever Wanted
+To Know" collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> for
+more about this approach.
+.PP
+See also the question later in perlfaq4 on sorting hashes.
+.SS "How do I manipulate arrays of bits?"
+.IX Subsection "How do I manipulate arrays of bits?"
+Use \f(CWpack()\fR and \f(CWunpack()\fR, or else \f(CWvec()\fR and the bitwise
+operations.
+.PP
+For example, you don't have to store individual bits in an array
+(which would mean that you're wasting a lot of space). To convert an
+array of bits to a string, use \f(CWvec()\fR to set the right bits. This
+sets \f(CW$vec\fR to have bit N set only if \f(CW$ints[N]\fR was set:
+.PP
+.Vb 5
+\&    my @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )
+\&    my $vec = \*(Aq\*(Aq;
+\&    foreach( 0 .. $#ints ) {
+\&        vec($vec,$_,1) = 1 if $ints[$_];
+\&    }
+.Ve
+.PP
+The string \f(CW$vec\fR only takes up as many bits as it needs. For
+instance, if you had 16 entries in \f(CW@ints\fR, \f(CW$vec\fR only needs two
+bytes to store them (not counting the scalar variable overhead).
+.PP
+Here's how, given a vector in \f(CW$vec\fR, you can get those bits into
+your \f(CW@ints\fR array:
+.PP
+.Vb 7
+\&    sub bitvec_to_list {
+\&        my $vec = shift;
+\&        my @ints;
+\&        # Find null\-byte density then select best algorithm
+\&        if ($vec =~ tr/\e0// / length $vec > 0.95) {
+\&            use integer;
+\&            my $i;
+\&
+\&            # This method is faster with mostly null\-bytes
+\&            while($vec =~ /[^\e0]/g ) {
+\&                $i = \-9 + 8 * pos $vec;
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&                push @ints, $i if vec($vec, ++$i, 1);
+\&            }
+\&        }
+\&        else {
+\&            # This method is a fast general algorithm
+\&            use integer;
+\&            my $bits = unpack "b*", $vec;
+\&            push @ints, 0 if $bits =~ s/^(\ed)// && $1;
+\&            push @ints, pos $bits while($bits =~ /1/g);
+\&        }
+\&
+\&        return \e@ints;
+\&    }
+.Ve
+.PP
+This method gets faster the more sparse the bit vector is.
+(Courtesy of Tim Bunce and Winfried Koenig.)
+.PP
+You can make the while loop a lot shorter with this suggestion
+from Benjamin Goldberg:
+.PP
+.Vb 3
+\&    while($vec =~ /[^\e0]+/g ) {
+\&        push @ints, grep vec($vec, $_, 1), $\-[0] * 8 .. $+[0] * 8;
+\&    }
+.Ve
+.PP
+Or use the CPAN module Bit::Vector:
+.PP
+.Vb 3
+\&    my $vector = Bit::Vector\->new($num_of_bits);
+\&    $vector\->Index_List_Store(@ints);
+\&    my @ints = $vector\->Index_List_Read();
+.Ve
+.PP
+Bit::Vector provides efficient methods for bit vector, sets of
+small integers and "big int" math.
+.PP
+Here's a more extensive illustration using \fBvec()\fR:
+.PP
+.Vb 7
+\&    # vec demo
+\&    my $vector = "\exff\ex0f\exef\exfe";
+\&    print "Ilya\*(Aqs string \e\exff\e\ex0f\e\exef\e\exfe represents the number ",
+\&    unpack("N", $vector), "\en";
+\&    my $is_set = vec($vector, 23, 1);
+\&    print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\en";
+\&    pvec($vector);
+\&
+\&    set_vec(1,1,1);
+\&    set_vec(3,1,1);
+\&    set_vec(23,1,1);
+\&
+\&    set_vec(3,1,3);
+\&    set_vec(3,2,3);
+\&    set_vec(3,4,3);
+\&    set_vec(3,4,7);
+\&    set_vec(3,8,3);
+\&    set_vec(3,8,7);
+\&
+\&    set_vec(0,32,17);
+\&    set_vec(1,32,17);
+\&
+\&    sub set_vec {
+\&        my ($offset, $width, $value) = @_;
+\&        my $vector = \*(Aq\*(Aq;
+\&        vec($vector, $offset, $width) = $value;
+\&        print "offset=$offset width=$width value=$value\en";
+\&        pvec($vector);
+\&    }
+\&
+\&    sub pvec {
+\&        my $vector = shift;
+\&        my $bits = unpack("b*", $vector);
+\&        my $i = 0;
+\&        my $BASE = 8;
+\&
+\&        print "vector length in bytes: ", length($vector), "\en";
+\&        @bytes = unpack("A8" x length($vector), $bits);
+\&        print "bits are: @bytes\en\en";
+\&    }
+.Ve
+.SS "Why does \fBdefined()\fP return true on empty arrays and hashes?"
+.IX Subsection "Why does defined() return true on empty arrays and hashes?"
+The short story is that you should probably only use defined on scalars or
+functions, not on aggregates (arrays and hashes). See "defined" in perlfunc
+in the 5.004 release or later of Perl for more detail.
+.SH "Data: Hashes (Associative Arrays)"
+.IX Header "Data: Hashes (Associative Arrays)"
+.SS "How do I process an entire hash?"
+.IX Subsection "How do I process an entire hash?"
+(contributed by brian d foy)
+.PP
+There are a couple of ways that you can process an entire hash. You
+can get a list of keys, then go through each key, or grab a one
+key-value pair at a time.
+.PP
+To go through all of the keys, use the \f(CW\*(C`keys\*(C'\fR function. This extracts
+all of the keys of the hash and gives them back to you as a list. You
+can then get the value through the particular key you're processing:
+.PP
+.Vb 4
+\&    foreach my $key ( keys %hash ) {
+\&        my $value = $hash{$key}
+\&        ...
+\&    }
+.Ve
+.PP
+Once you have the list of keys, you can process that list before you
+process the hash elements. For instance, you can sort the keys so you
+can process them in lexical order:
+.PP
+.Vb 4
+\&    foreach my $key ( sort keys %hash ) {
+\&        my $value = $hash{$key}
+\&        ...
+\&    }
+.Ve
+.PP
+Or, you might want to only process some of the items. If you only want
+to deal with the keys that start with \f(CW\*(C`text:\*(C'\fR, you can select just
+those using \f(CW\*(C`grep\*(C'\fR:
+.PP
+.Vb 4
+\&    foreach my $key ( grep /^text:/, keys %hash ) {
+\&        my $value = $hash{$key}
+\&        ...
+\&    }
+.Ve
+.PP
+If the hash is very large, you might not want to create a long list of
+keys. To save some memory, you can grab one key-value pair at a time using
+\&\f(CWeach()\fR, which returns a pair you haven't seen yet:
+.PP
+.Vb 3
+\&    while( my( $key, $value ) = each( %hash ) ) {
+\&        ...
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`each\*(C'\fR operator returns the pairs in apparently random order, so if
+ordering matters to you, you'll have to stick with the \f(CW\*(C`keys\*(C'\fR method.
+.PP
+The \f(CWeach()\fR operator can be a bit tricky though. You can't add or
+delete keys of the hash while you're using it without possibly
+skipping or re-processing some pairs after Perl internally rehashes
+all of the elements. Additionally, a hash has only one iterator, so if
+you mix \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR, or \f(CW\*(C`each\*(C'\fR on the same hash, you risk resetting
+the iterator and messing up your processing. See the \f(CW\*(C`each\*(C'\fR entry in
+perlfunc for more details.
+.SS "How do I merge two hashes?"
+.IX Xref "hash merge slice, hash"
+.IX Subsection "How do I merge two hashes?"
+(contributed by brian d foy)
+.PP
+Before you decide to merge two hashes, you have to decide what to do
+if both hashes contain keys that are the same and if you want to leave
+the original hashes as they were.
+.PP
+If you want to preserve the original hashes, copy one hash (\f(CW%hash1\fR)
+to a new hash (\f(CW%new_hash\fR), then add the keys from the other hash
+(\f(CW%hash2\fR to the new hash. Checking that the key already exists in
+\&\f(CW%new_hash\fR gives you a chance to decide what to do with the
+duplicates:
+.PP
+.Vb 1
+\&    my %new_hash = %hash1; # make a copy; leave %hash1 alone
+\&
+\&    foreach my $key2 ( keys %hash2 ) {
+\&        if( exists $new_hash{$key2} ) {
+\&            warn "Key [$key2] is in both hashes!";
+\&            # handle the duplicate (perhaps only warning)
+\&            ...
+\&            next;
+\&        }
+\&        else {
+\&            $new_hash{$key2} = $hash2{$key2};
+\&        }
+\&    }
+.Ve
+.PP
+If you don't want to create a new hash, you can still use this looping
+technique; just change the \f(CW%new_hash\fR to \f(CW%hash1\fR.
+.PP
+.Vb 11
+\&    foreach my $key2 ( keys %hash2 ) {
+\&        if( exists $hash1{$key2} ) {
+\&            warn "Key [$key2] is in both hashes!";
+\&            # handle the duplicate (perhaps only warning)
+\&            ...
+\&            next;
+\&        }
+\&        else {
+\&            $hash1{$key2} = $hash2{$key2};
+\&        }
+\&      }
+.Ve
+.PP
+If you don't care that one hash overwrites keys and values from the other, you
+could just use a hash slice to add one hash to another. In this case, values
+from \f(CW%hash2\fR replace values from \f(CW%hash1\fR when they have keys in common:
+.PP
+.Vb 1
+\&    @hash1{ keys %hash2 } = values %hash2;
+.Ve
+.SS "What happens if I add or remove keys from a hash while iterating over it?"
+.IX Subsection "What happens if I add or remove keys from a hash while iterating over it?"
+(contributed by brian d foy)
+.PP
+The easy answer is "Don't do that!"
+.PP
+If you iterate through the hash with \fBeach()\fR, you can delete the key
+most recently returned without worrying about it. If you delete or add
+other keys, the iterator may skip or double up on them since perl
+may rearrange the hash table. See the
+entry for \f(CWeach()\fR in perlfunc.
+.SS "How do I look up a hash element by value?"
+.IX Subsection "How do I look up a hash element by value?"
+Create a reverse hash:
+.PP
+.Vb 2
+\&    my %by_value = reverse %by_key;
+\&    my $key = $by_value{$value};
+.Ve
+.PP
+That's not particularly efficient. It would be more space-efficient
+to use:
+.PP
+.Vb 3
+\&    while (my ($key, $value) = each %by_key) {
+\&        $by_value{$value} = $key;
+\&    }
+.Ve
+.PP
+If your hash could have repeated values, the methods above will only find
+one of the associated keys.  This may or may not worry you. If it does
+worry you, you can always reverse the hash into a hash of arrays instead:
+.PP
+.Vb 3
+\&    while (my ($key, $value) = each %by_key) {
+\&         push @{$key_list_by_value{$value}}, $key;
+\&    }
+.Ve
+.SS "How can I know how many entries are in a hash?"
+.IX Subsection "How can I know how many entries are in a hash?"
+(contributed by brian d foy)
+.PP
+This is very similar to "How do I process an entire hash?", also in
+perlfaq4, but a bit simpler in the common cases.
+.PP
+You can use the \f(CWkeys()\fR built-in function in scalar context to find out
+have many entries you have in a hash:
+.PP
+.Vb 1
+\&    my $key_count = keys %hash; # must be scalar context!
+.Ve
+.PP
+If you want to find out how many entries have a defined value, that's
+a bit different. You have to check each value. A \f(CW\*(C`grep\*(C'\fR is handy:
+.PP
+.Vb 1
+\&    my $defined_value_count = grep { defined } values %hash;
+.Ve
+.PP
+You can use that same structure to count the entries any way that
+you like. If you want the count of the keys with vowels in them,
+you just test for that instead:
+.PP
+.Vb 1
+\&    my $vowel_count = grep { /[aeiou]/ } keys %hash;
+.Ve
+.PP
+The \f(CW\*(C`grep\*(C'\fR in scalar context returns the count. If you want the list
+of matching items, just use it in list context instead:
+.PP
+.Vb 1
+\&    my @defined_values = grep { defined } values %hash;
+.Ve
+.PP
+The \f(CWkeys()\fR function also resets the iterator, which means that you may
+see strange results if you use this between uses of other hash operators
+such as \f(CWeach()\fR.
+.SS "How do I sort a hash (optionally by value instead of key)?"
+.IX Subsection "How do I sort a hash (optionally by value instead of key)?"
+(contributed by brian d foy)
+.PP
+To sort a hash, start with the keys. In this example, we give the list of
+keys to the sort function which then compares them ASCIIbetically (which
+might be affected by your locale settings). The output list has the keys
+in ASCIIbetical order. Once we have the keys, we can go through them to
+create a report which lists the keys in ASCIIbetical order.
+.PP
+.Vb 1
+\&    my @keys = sort { $a cmp $b } keys %hash;
+\&
+\&    foreach my $key ( @keys ) {
+\&        printf "%\-20s %6d\en", $key, $hash{$key};
+\&    }
+.Ve
+.PP
+We could get more fancy in the \f(CWsort()\fR block though. Instead of
+comparing the keys, we can compute a value with them and use that
+value as the comparison.
+.PP
+For instance, to make our report order case-insensitive, we use
+\&\f(CW\*(C`lc\*(C'\fR to lowercase the keys before comparing them:
+.PP
+.Vb 1
+\&    my @keys = sort { lc $a cmp lc $b } keys %hash;
+.Ve
+.PP
+Note: if the computation is expensive or the hash has many elements,
+you may want to look at the Schwartzian Transform to cache the
+computation results.
+.PP
+If we want to sort by the hash value instead, we use the hash key
+to look it up. We still get out a list of keys, but this time they
+are ordered by their value.
+.PP
+.Vb 1
+\&    my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;
+.Ve
+.PP
+From there we can get more complex. If the hash values are the same,
+we can provide a secondary sort on the hash key.
+.PP
+.Vb 5
+\&    my @keys = sort {
+\&        $hash{$a} <=> $hash{$b}
+\&            or
+\&        "\eL$a" cmp "\eL$b"
+\&    } keys %hash;
+.Ve
+.SS "How can I always keep my hash sorted?"
+.IX Xref "hash tie sort DB_File Tie::IxHash"
+.IX Subsection "How can I always keep my hash sorted?"
+You can look into using the \f(CW\*(C`DB_File\*(C'\fR module and \f(CWtie()\fR using the
+\&\f(CW$DB_BTREE\fR hash bindings as documented in "In Memory
+Databases" in DB_File. The Tie::IxHash module from CPAN might also be
+instructive. Although this does keep your hash sorted, you might not
+like the slowdown you suffer from the tie interface. Are you sure you
+need to do this? :)
+.SS "What's the difference between ""delete"" and ""undef"" with hashes?"
+.IX Subsection "What's the difference between ""delete"" and ""undef"" with hashes?"
+Hashes contain pairs of scalars: the first is the key, the
+second is the value. The key will be coerced to a string,
+although the value can be any kind of scalar: string,
+number, or reference. If a key \f(CW$key\fR is present in
+\&\f(CW%hash\fR, \f(CWexists($hash{$key})\fR will return true. The value
+for a given key can be \f(CW\*(C`undef\*(C'\fR, in which case
+\&\f(CW$hash{$key}\fR will be \f(CW\*(C`undef\*(C'\fR while \f(CW\*(C`exists $hash{$key}\*(C'\fR
+will return true. This corresponds to (\f(CW$key\fR, \f(CW\*(C`undef\*(C'\fR)
+being in the hash.
+.PP
+Pictures help... Here's the \f(CW%hash\fR table:
+.PP
+.Vb 7
+\&      keys  values
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+\&    |  a   |  3   |
+\&    |  x   |  7   |
+\&    |  d   |  0   |
+\&    |  e   |  2   |
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+.Ve
+.PP
+And these conditions hold
+.PP
+.Vb 6
+\&    $hash{\*(Aqa\*(Aq}                       is true
+\&    $hash{\*(Aqd\*(Aq}                       is false
+\&    defined $hash{\*(Aqd\*(Aq}               is true
+\&    defined $hash{\*(Aqa\*(Aq}               is true
+\&    exists $hash{\*(Aqa\*(Aq}                is true (Perl 5 only)
+\&    grep ($_ eq \*(Aqa\*(Aq, keys %hash)     is true
+.Ve
+.PP
+If you now say
+.PP
+.Vb 1
+\&    undef $hash{\*(Aqa\*(Aq}
+.Ve
+.PP
+your table now reads:
+.PP
+.Vb 7
+\&      keys  values
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+\&    |  a   | undef|
+\&    |  x   |  7   |
+\&    |  d   |  0   |
+\&    |  e   |  2   |
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+.Ve
+.PP
+and these conditions now hold; changes in caps:
+.PP
+.Vb 6
+\&    $hash{\*(Aqa\*(Aq}                       is FALSE
+\&    $hash{\*(Aqd\*(Aq}                       is false
+\&    defined $hash{\*(Aqd\*(Aq}               is true
+\&    defined $hash{\*(Aqa\*(Aq}               is FALSE
+\&    exists $hash{\*(Aqa\*(Aq}                is true (Perl 5 only)
+\&    grep ($_ eq \*(Aqa\*(Aq, keys %hash)     is true
+.Ve
+.PP
+Notice the last two: you have an undef value, but a defined key!
+.PP
+Now, consider this:
+.PP
+.Vb 1
+\&    delete $hash{\*(Aqa\*(Aq}
+.Ve
+.PP
+your table now reads:
+.PP
+.Vb 6
+\&      keys  values
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+\&    |  x   |  7   |
+\&    |  d   |  0   |
+\&    |  e   |  2   |
+\&    +\-\-\-\-\-\-+\-\-\-\-\-\-+
+.Ve
+.PP
+and these conditions now hold; changes in caps:
+.PP
+.Vb 6
+\&    $hash{\*(Aqa\*(Aq}                       is false
+\&    $hash{\*(Aqd\*(Aq}                       is false
+\&    defined $hash{\*(Aqd\*(Aq}               is true
+\&    defined $hash{\*(Aqa\*(Aq}               is false
+\&    exists $hash{\*(Aqa\*(Aq}                is FALSE (Perl 5 only)
+\&    grep ($_ eq \*(Aqa\*(Aq, keys %hash)     is FALSE
+.Ve
+.PP
+See, the whole entry is gone!
+.SS "Why don't my tied hashes make the defined/exists distinction?"
+.IX Subsection "Why don't my tied hashes make the defined/exists distinction?"
+This depends on the tied hash's implementation of \fBEXISTS()\fR.
+For example, there isn't the concept of undef with hashes
+that are tied to DBM* files. It also means that \fBexists()\fR and
+\&\fBdefined()\fR do the same thing with a DBM* file, and what they
+end up doing is not what they do with ordinary hashes.
+.SS "How do I reset an \fBeach()\fP operation part-way through?"
+.IX Subsection "How do I reset an each() operation part-way through?"
+(contributed by brian d foy)
+.PP
+You can use the \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`values\*(C'\fR functions to reset \f(CW\*(C`each\*(C'\fR. To
+simply reset the iterator used by \f(CW\*(C`each\*(C'\fR without doing anything else,
+use one of them in void context:
+.PP
+.Vb 2
+\&    keys %hash; # resets iterator, nothing else.
+\&    values %hash; # resets iterator, nothing else.
+.Ve
+.PP
+See the documentation for \f(CW\*(C`each\*(C'\fR in perlfunc.
+.SS "How can I get the unique keys from two hashes?"
+.IX Subsection "How can I get the unique keys from two hashes?"
+First you extract the keys from the hashes into lists, then solve
+the "removing duplicates" problem described above. For example:
+.PP
+.Vb 5
+\&    my %seen = ();
+\&    for my $element (keys(%foo), keys(%bar)) {
+\&        $seen{$element}++;
+\&    }
+\&    my @uniq = keys %seen;
+.Ve
+.PP
+Or more succinctly:
+.PP
+.Vb 1
+\&    my @uniq = keys %{{%foo,%bar}};
+.Ve
+.PP
+Or if you really want to save space:
+.PP
+.Vb 8
+\&    my %seen = ();
+\&    while (defined ($key = each %foo)) {
+\&        $seen{$key}++;
+\&    }
+\&    while (defined ($key = each %bar)) {
+\&        $seen{$key}++;
+\&    }
+\&    my @uniq = keys %seen;
+.Ve
+.SS "How can I store a multidimensional array in a DBM file?"
+.IX Subsection "How can I store a multidimensional array in a DBM file?"
+Either stringify the structure yourself (no fun), or else
+get the MLDBM (which uses Data::Dumper) module from CPAN and layer
+it on top of either DB_File or GDBM_File. You might also try DBM::Deep, but
+it can be a bit slow.
+.SS "How can I make my hash remember the order I put elements into it?"
+.IX Subsection "How can I make my hash remember the order I put elements into it?"
+Use the Tie::IxHash from CPAN.
+.PP
+.Vb 1
+\&    use Tie::IxHash;
+\&
+\&    tie my %myhash, \*(AqTie::IxHash\*(Aq;
+\&
+\&    for (my $i=0; $i<20; $i++) {
+\&        $myhash{$i} = 2*$i;
+\&    }
+\&
+\&    my @keys = keys %myhash;
+\&    # @keys = (0,1,2,3,...)
+.Ve
+.SS "Why does passing a subroutine an undefined element in a hash create it?"
+.IX Subsection "Why does passing a subroutine an undefined element in a hash create it?"
+(contributed by brian d foy)
+.PP
+Are you using a really old version of Perl?
+.PP
+Normally, accessing a hash key's value for a nonexistent key will
+\&\fInot\fR create the key.
+.PP
+.Vb 3
+\&    my %hash  = ();
+\&    my $value = $hash{ \*(Aqfoo\*(Aq };
+\&    print "This won\*(Aqt print\en" if exists $hash{ \*(Aqfoo\*(Aq };
+.Ve
+.PP
+Passing \f(CW$hash{ \*(Aqfoo\*(Aq }\fR to a subroutine used to be a special case, though.
+Since you could assign directly to \f(CW$_[0]\fR, Perl had to be ready to
+make that assignment so it created the hash key ahead of time:
+.PP
+.Vb 2
+\&    my_sub( $hash{ \*(Aqfoo\*(Aq } );
+\&    print "This will print before 5.004\en" if exists $hash{ \*(Aqfoo\*(Aq };
+\&
+\&    sub my_sub {
+\&        # $_[0] = \*(Aqbar\*(Aq; # create hash key in case you do this
+\&        1;
+\&    }
+.Ve
+.PP
+Since Perl 5.004, however, this situation is a special case and Perl
+creates the hash key only when you make the assignment:
+.PP
+.Vb 2
+\&    my_sub( $hash{ \*(Aqfoo\*(Aq } );
+\&    print "This will print, even after 5.004\en" if exists $hash{ \*(Aqfoo\*(Aq };
+\&
+\&    sub my_sub {
+\&        $_[0] = \*(Aqbar\*(Aq;
+\&    }
+.Ve
+.PP
+However, if you want the old behavior (and think carefully about that
+because it's a weird side effect), you can pass a hash slice instead.
+Perl 5.004 didn't make this a special case:
+.PP
+.Vb 1
+\&    my_sub( @hash{ qw/foo/ } );
+.Ve
+.SS "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?"
+.IX Subsection "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?"
+Usually a hash ref, perhaps like this:
+.PP
+.Vb 8
+\&    $record = {
+\&        NAME   => "Jason",
+\&        EMPNO  => 132,
+\&        TITLE  => "deputy peon",
+\&        AGE    => 23,
+\&        SALARY => 37_000,
+\&        PALS   => [ "Norbert", "Rhys", "Phineas"],
+\&    };
+.Ve
+.PP
+References are documented in perlref and perlreftut.
+Examples of complex data structures are given in perldsc and
+perllol. Examples of structures and object-oriented classes are
+in perlootut.
+.SS "How can I use a reference as a hash key?"
+.IX Subsection "How can I use a reference as a hash key?"
+(contributed by brian d foy and Ben Morrow)
+.PP
+Hash keys are strings, so you can't really use a reference as the key.
+When you try to do that, perl turns the reference into its stringified
+form (for instance, \f(CWHASH(0xDEADBEEF)\fR). From there you can't get
+back the reference from the stringified form, at least without doing
+some extra work on your own.
+.PP
+Remember that the entry in the hash will still be there even if
+the referenced variable  goes out of scope, and that it is entirely
+possible for Perl to subsequently allocate a different variable at
+the same address. This will mean a new variable might accidentally
+be associated with the value for an old.
+.PP
+If you have Perl 5.10 or later, and you just want to store a value
+against the reference for lookup later, you can use the core
+Hash::Util::Fieldhash module. This will also handle renaming the
+keys if you use multiple threads (which causes all variables to be
+reallocated at new addresses, changing their stringification), and
+garbage-collecting the entries when the referenced variable goes out
+of scope.
+.PP
+If you actually need to be able to get a real reference back from
+each hash entry, you can use the Tie::RefHash module, which does the
+required work for you.
+.SS "How can I check if a key exists in a multilevel hash?"
+.IX Subsection "How can I check if a key exists in a multilevel hash?"
+(contributed by brian d foy)
+.PP
+The trick to this problem is avoiding accidental autovivification. If
+you want to check three keys deep, you might naïvely try this:
+.PP
+.Vb 4
+\&    my %hash;
+\&    if( exists $hash{key1}{key2}{key3} ) {
+\&        ...;
+\&    }
+.Ve
+.PP
+Even though you started with a completely empty hash, after that call to
+\&\f(CW\*(C`exists\*(C'\fR you've created the structure you needed to check for \f(CW\*(C`key3\*(C'\fR:
+.PP
+.Vb 5
+\&    %hash = (
+\&              \*(Aqkey1\*(Aq => {
+\&                          \*(Aqkey2\*(Aq => {}
+\&                        }
+\&            );
+.Ve
+.PP
+That's autovivification. You can get around this in a few ways. The
+easiest way is to just turn it off. The lexical \f(CW\*(C`autovivification\*(C'\fR
+pragma is available on CPAN. Now you don't add to the hash:
+.PP
+.Vb 7
+\&    {
+\&        no autovivification;
+\&        my %hash;
+\&        if( exists $hash{key1}{key2}{key3} ) {
+\&            ...;
+\&        }
+\&    }
+.Ve
+.PP
+The Data::Diver module on CPAN can do it for you too. Its \f(CW\*(C`Dive\*(C'\fR
+subroutine can tell you not only if the keys exist but also get the
+value:
+.PP
+.Vb 1
+\&    use Data::Diver qw(Dive);
+\&
+\&    my @exists = Dive( \e%hash, qw(key1 key2 key3) );
+\&    if(  ! @exists  ) {
+\&        ...; # keys do not exist
+\&    }
+\&    elsif(  ! defined $exists[0]  ) {
+\&        ...; # keys exist but value is undef
+\&    }
+.Ve
+.PP
+You can easily do this yourself too by checking each level of the hash
+before you move onto the next level. This is essentially what
+Data::Diver does for you:
+.PP
+.Vb 3
+\&    if( check_hash( \e%hash, qw(key1 key2 key3) ) ) {
+\&        ...;
+\&    }
+\&
+\&    sub check_hash {
+\&       my( $hash, @keys ) = @_;
+\&
+\&       return unless @keys;
+\&
+\&       foreach my $key ( @keys ) {
+\&           return unless eval { exists $hash\->{$key} };
+\&           $hash = $hash\->{$key};
+\&        }
+\&
+\&       return 1;
+\&    }
+.Ve
+.SS "How can I prevent addition of unwanted keys into a hash?"
+.IX Subsection "How can I prevent addition of unwanted keys into a hash?"
+Since version 5.8.0, hashes can be \fIrestricted\fR to a fixed number
+of given keys. Methods for creating and dealing with restricted hashes
+are exported by the Hash::Util module.
+.SH "Data: Misc"
+.IX Header "Data: Misc"
+.SS "How do I handle binary data correctly?"
+.IX Subsection "How do I handle binary data correctly?"
+Perl is binary-clean, so it can handle binary data just fine.
+On Windows or DOS, however, you have to use \f(CW\*(C`binmode\*(C'\fR for binary
+files to avoid conversions for line endings. In general, you should
+use \f(CW\*(C`binmode\*(C'\fR any time you want to work with binary data.
+.PP
+Also see "binmode" in perlfunc or perlopentut.
+.PP
+If you're concerned about 8\-bit textual data then see perllocale.
+If you want to deal with multibyte characters, however, there are
+some gotchas. See the section on Regular Expressions.
+.SS "How do I determine whether a scalar is a number/whole/integer/float?"
+.IX Subsection "How do I determine whether a scalar is a number/whole/integer/float?"
+Assuming that you don't care about IEEE notations like "NaN" or
+"Infinity", you probably just want to use a regular expression (see also
+perlretut and perlre):
+.PP
+.Vb 1
+\&    use 5.010;
+\&
+\&    if ( /\eD/ )
+\&        { say "\ethas nondigits"; }
+\&    if ( /^\ed+\ez/ )
+\&        { say "\etis a whole number"; }
+\&    if ( /^\-?\ed+\ez/ )
+\&        { say "\etis an integer"; }
+\&    if ( /^[+\-]?\ed+\ez/ )
+\&        { say "\etis a +/\- integer"; }
+\&    if ( /^\-?(?:\ed+\e.?|\e.\ed)\ed*\ez/ )
+\&        { say "\etis a real number"; }
+\&    if ( /^[+\-]?(?=\e.?\ed)\ed*\e.?\ed*(?:e[+\-]?\ed+)?\ez/i )
+\&        { say "\etis a C float" }
+.Ve
+.PP
+There are also some commonly used modules for the task.
+Scalar::Util (distributed with 5.8) provides access to perl's
+internal function \f(CW\*(C`looks_like_number\*(C'\fR for determining whether a
+variable looks like a number. Data::Types exports functions that
+validate data types using both the above and other regular
+expressions. Thirdly, there is Regexp::Common which has regular
+expressions to match various types of numbers. Those three modules are
+available from the CPAN.
+.PP
+If you're on a POSIX system, Perl supports the \f(CW\*(C`POSIX::strtod\*(C'\fR
+function for converting strings to doubles (and also \f(CW\*(C`POSIX::strtol\*(C'\fR
+for longs). Its semantics are somewhat cumbersome, so here's a
+\&\f(CW\*(C`getnum\*(C'\fR wrapper function for more convenient access. This function
+takes a string and returns the number it found, or \f(CW\*(C`undef\*(C'\fR for input
+that isn't a C float. The \f(CW\*(C`is_numeric\*(C'\fR function is a front end to
+\&\f(CW\*(C`getnum\*(C'\fR if you just want to say, "Is this a float?"
+.PP
+.Vb 10
+\&    sub getnum {
+\&        use POSIX qw(strtod);
+\&        my $str = shift;
+\&        $str =~ s/^\es+//;
+\&        $str =~ s/\es+$//;
+\&        $! = 0;
+\&        my($num, $unparsed) = strtod($str);
+\&        if (($str eq \*(Aq\*(Aq) || ($unparsed != 0) || $!) {
+\&                return undef;
+\&        }
+\&        else {
+\&            return $num;
+\&        }
+\&    }
+\&
+\&    sub is_numeric { defined getnum($_[0]) }
+.Ve
+.PP
+Or you could check out the String::Scanf module on the CPAN
+instead.
+.SS "How do I keep persistent data across program calls?"
+.IX Subsection "How do I keep persistent data across program calls?"
+For some specific applications, you can use one of the DBM modules.
+See AnyDBM_File. More generically, you should consult the FreezeThaw
+or Storable modules from CPAN. Starting from Perl 5.8, Storable is part
+of the standard distribution. Here's one example using Storable's \f(CW\*(C`store\*(C'\fR
+and \f(CW\*(C`retrieve\*(C'\fR functions:
+.PP
+.Vb 2
+\&    use Storable;
+\&    store(\e%hash, "filename");
+\&
+\&    # later on...
+\&    $href = retrieve("filename");        # by ref
+\&    %hash = %{ retrieve("filename") };   # direct to hash
+.Ve
+.SS "How do I print out or copy a recursive data structure?"
+.IX Subsection "How do I print out or copy a recursive data structure?"
+The Data::Dumper module on CPAN (or the 5.005 release of Perl) is great
+for printing out data structures. The Storable module on CPAN (or the
+5.8 release of Perl), provides a function called \f(CW\*(C`dclone\*(C'\fR that recursively
+copies its argument.
+.PP
+.Vb 2
+\&    use Storable qw(dclone);
+\&    $r2 = dclone($r1);
+.Ve
+.PP
+Where \f(CW$r1\fR can be a reference to any kind of data structure you'd like.
+It will be deeply copied. Because \f(CW\*(C`dclone\*(C'\fR takes and returns references,
+you'd have to add extra punctuation if you had a hash of arrays that
+you wanted to copy.
+.PP
+.Vb 1
+\&    %newhash = %{ dclone(\e%oldhash) };
+.Ve
+.SS "How do I define methods for every class/object?"
+.IX Subsection "How do I define methods for every class/object?"
+(contributed by Ben Morrow)
+.PP
+You can use the \f(CW\*(C`UNIVERSAL\*(C'\fR class (see UNIVERSAL). However, please
+be very careful to consider the consequences of doing this: adding
+methods to every object is very likely to have unintended
+consequences. If possible, it would be better to have all your object
+inherit from some common base class, or to use an object system like
+Moose that supports roles.
+.SS "How do I verify a credit card checksum?"
+.IX Subsection "How do I verify a credit card checksum?"
+Get the Business::CreditCard module from CPAN.
+.SS "How do I pack arrays of doubles or floats for XS code?"
+.IX Subsection "How do I pack arrays of doubles or floats for XS code?"
+The arrays.h/arrays.c code in the PGPLOT module on CPAN does just this.
+If you're doing a lot of float or double processing, consider using
+the PDL module from CPAN instead\-\-it makes number-crunching easy.
+.PP
+See <https://metacpan.org/release/PGPLOT> for the code.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq5.1 b/upstream/mageia-cauldron/man1/perlfaq5.1
new file mode 100644
index 00000000..813f4e43
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq5.1
@@ -0,0 +1,1806 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ5 1"
+.TH PERLFAQ5 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq5 \- Files and Formats
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section deals with I/O and the "f" issues: filehandles, flushing,
+formats, and footers.
+.SS "How do I flush/unbuffer an output filehandle? Why must I do this?"
+.IX Xref "flush buffer unbuffer autoflush"
+.IX Subsection "How do I flush/unbuffer an output filehandle? Why must I do this?"
+(contributed by brian d foy)
+.PP
+You might like to read Mark Jason Dominus's "Suffering From Buffering"
+at <http://perl.plover.com/FAQs/Buffering.html> .
+.PP
+Perl normally buffers output so it doesn't make a system call for every
+bit of output. By saving up output, it makes fewer expensive system calls.
+For instance, in this little bit of code, you want to print a dot to the
+screen for every line you process to watch the progress of your program.
+Instead of seeing a dot for every line, Perl buffers the output and you
+have a long wait before you see a row of 50 dots all at once:
+.PP
+.Vb 4
+\&    # long wait, then row of dots all at once
+\&    while( <> ) {
+\&        print ".";
+\&        print "\en" unless ++$count % 50;
+\&
+\&        #... expensive line processing operations
+\&    }
+.Ve
+.PP
+To get around this, you have to unbuffer the output filehandle, in this
+case, \f(CW\*(C`STDOUT\*(C'\fR. You can set the special variable \f(CW$|\fR to a true value
+(mnemonic: making your filehandles "piping hot"):
+.PP
+.Vb 1
+\&    $|++;
+\&
+\&    # dot shown immediately
+\&    while( <> ) {
+\&        print ".";
+\&        print "\en" unless ++$count % 50;
+\&
+\&        #... expensive line processing operations
+\&    }
+.Ve
+.PP
+The \f(CW$|\fR is one of the per-filehandle special variables, so each
+filehandle has its own copy of its value. If you want to merge
+standard output and standard error for instance, you have to unbuffer
+each (although STDERR might be unbuffered by default):
+.PP
+.Vb 7
+\&    {
+\&        my $previous_default = select(STDOUT);  # save previous default
+\&        $|++;                                   # autoflush STDOUT
+\&        select(STDERR);
+\&        $|++;                                   # autoflush STDERR, to be sure
+\&        select($previous_default);              # restore previous default
+\&    }
+\&
+\&    # now should alternate . and +
+\&    while( 1 ) {
+\&        sleep 1;
+\&        print STDOUT ".";
+\&        print STDERR "+";
+\&        print STDOUT "\en" unless ++$count % 25;
+\&    }
+.Ve
+.PP
+Besides the \f(CW$|\fR special variable, you can use \f(CW\*(C`binmode\*(C'\fR to give
+your filehandle a \f(CW\*(C`:unix\*(C'\fR layer, which is unbuffered:
+.PP
+.Vb 1
+\&    binmode( STDOUT, ":unix" );
+\&
+\&    while( 1 ) {
+\&        sleep 1;
+\&        print ".";
+\&        print "\en" unless ++$count % 50;
+\&    }
+.Ve
+.PP
+For more information on output layers, see the entries for \f(CW\*(C`binmode\*(C'\fR
+and open in perlfunc, and the PerlIO module documentation.
+.PP
+If you are using IO::Handle or one of its subclasses, you can
+call the \f(CW\*(C`autoflush\*(C'\fR method to change the settings of the
+filehandle:
+.PP
+.Vb 3
+\&    use IO::Handle;
+\&    open my( $io_fh ), ">", "output.txt";
+\&    $io_fh\->autoflush(1);
+.Ve
+.PP
+The IO::Handle objects also have a \f(CW\*(C`flush\*(C'\fR method. You can flush
+the buffer any time you want without auto-buffering
+.PP
+.Vb 1
+\&    $io_fh\->flush;
+.Ve
+.SS "How do I change, delete, or insert a line in a file, or append to the beginning of a file?"
+.IX Xref "file, editing"
+.IX Subsection "How do I change, delete, or insert a line in a file, or append to the beginning of a file?"
+(contributed by brian d foy)
+.PP
+The basic idea of inserting, changing, or deleting a line from a text
+file involves reading and printing the file to the point you want to
+make the change, making the change, then reading and printing the rest
+of the file. Perl doesn't provide random access to lines (especially
+since the record input separator, \f(CW$/\fR, is mutable), although modules
+such as Tie::File can fake it.
+.PP
+A Perl program to do these tasks takes the basic form of opening a
+file, printing its lines, then closing the file:
+.PP
+.Vb 2
+\&    open my $in,  \*(Aq<\*(Aq,  $file      or die "Can\*(Aqt read old file: $!";
+\&    open my $out, \*(Aq>\*(Aq, "$file.new" or die "Can\*(Aqt write new file: $!";
+\&
+\&    while( <$in> ) {
+\&            print $out $_;
+\&    }
+\&
+\&    close $out;
+.Ve
+.PP
+Within that basic form, add the parts that you need to insert, change,
+or delete lines.
+.PP
+To prepend lines to the beginning, print those lines before you enter
+the loop that prints the existing lines.
+.PP
+.Vb 2
+\&    open my $in,  \*(Aq<\*(Aq,  $file      or die "Can\*(Aqt read old file: $!";
+\&    open my $out, \*(Aq>\*(Aq, "$file.new" or die "Can\*(Aqt write new file: $!";
+\&
+\&    print $out "# Add this line to the top\en"; # <\-\-\- HERE\*(AqS THE MAGIC
+\&
+\&    while( <$in> ) {
+\&            print $out $_;
+\&    }
+\&
+\&    close $out;
+.Ve
+.PP
+To change existing lines, insert the code to modify the lines inside
+the \f(CW\*(C`while\*(C'\fR loop. In this case, the code finds all lowercased
+versions of "perl" and uppercases them. The happens for every line, so
+be sure that you're supposed to do that on every line!
+.PP
+.Vb 2
+\&    open my $in,  \*(Aq<\*(Aq,  $file      or die "Can\*(Aqt read old file: $!";
+\&    open my $out, \*(Aq>\*(Aq, "$file.new" or die "Can\*(Aqt write new file: $!";
+\&
+\&    print $out "# Add this line to the top\en";
+\&
+\&    while( <$in> ) {
+\&        s/\eb(perl)\eb/Perl/g;
+\&        print $out $_;
+\&    }
+\&
+\&    close $out;
+.Ve
+.PP
+To change only a particular line, the input line number, \f(CW$.\fR, is
+useful. First read and print the lines up to the one you  want to
+change. Next, read the single line you want to change, change it, and
+print it. After that, read the rest of the lines and print those:
+.PP
+.Vb 4
+\&    while( <$in> ) { # print the lines before the change
+\&        print $out $_;
+\&        last if $. == 4; # line number before change
+\&    }
+\&
+\&    my $line = <$in>;
+\&    $line =~ s/\eb(perl)\eb/Perl/g;
+\&    print $out $line;
+\&
+\&    while( <$in> ) { # print the rest of the lines
+\&        print $out $_;
+\&    }
+.Ve
+.PP
+To skip lines, use the looping controls. The \f(CW\*(C`next\*(C'\fR in this example
+skips comment lines, and the \f(CW\*(C`last\*(C'\fR stops all processing once it
+encounters either \f(CW\*(C`_\|_END_\|_\*(C'\fR or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
+.PP
+.Vb 5
+\&    while( <$in> ) {
+\&        next if /^\es+#/;             # skip comment lines
+\&        last if /^_\|_(END|DATA)_\|_$/;  # stop at end of code marker
+\&        print $out $_;
+\&    }
+.Ve
+.PP
+Do the same sort of thing to delete a particular line by using \f(CW\*(C`next\*(C'\fR
+to skip the lines you don't want to show up in the output. This
+example skips every fifth line:
+.PP
+.Vb 4
+\&    while( <$in> ) {
+\&        next unless $. % 5;
+\&        print $out $_;
+\&    }
+.Ve
+.PP
+If, for some odd reason, you really want to see the whole file at once
+rather than processing line-by-line, you can slurp it in (as long as
+you can fit the whole thing in memory!):
+.PP
+.Vb 2
+\&    open my $in,  \*(Aq<\*(Aq,  $file      or die "Can\*(Aqt read old file: $!"
+\&    open my $out, \*(Aq>\*(Aq, "$file.new" or die "Can\*(Aqt write new file: $!";
+\&
+\&    my $content = do { local $/; <$in> }; # slurp!
+\&
+\&        # do your magic here
+\&
+\&    print $out $content;
+.Ve
+.PP
+Modules such as Path::Tiny and Tie::File can help with that
+too. If you can, however, avoid reading the entire file at once. Perl
+won't give that memory back to the operating system until the process
+finishes.
+.PP
+You can also use Perl one-liners to modify a file in-place. The
+following changes all 'Fred' to 'Barney' in \fIinFile.txt\fR, overwriting
+the file with the new contents. With the \f(CW\*(C`\-p\*(C'\fR switch, Perl wraps a
+\&\f(CW\*(C`while\*(C'\fR loop around the code you specify with \f(CW\*(C`\-e\*(C'\fR, and \f(CW\*(C`\-i\*(C'\fR turns
+on in-place editing. The current line is in \f(CW$_\fR. With \f(CW\*(C`\-p\*(C'\fR, Perl
+automatically prints the value of \f(CW$_\fR at the end of the loop. See
+perlrun for more details.
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqs/Fred/Barney/\*(Aq inFile.txt
+.Ve
+.PP
+To make a backup of \f(CW\*(C`inFile.txt\*(C'\fR, give \f(CW\*(C`\-i\*(C'\fR a file extension to add:
+.PP
+.Vb 1
+\&    perl \-pi.bak \-e \*(Aqs/Fred/Barney/\*(Aq inFile.txt
+.Ve
+.PP
+To change only the fifth line, you can add a test checking \f(CW$.\fR, the
+input line number, then only perform the operation when the test
+passes:
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqs/Fred/Barney/ if $. == 5\*(Aq inFile.txt
+.Ve
+.PP
+To add lines before a certain line, you can add a line (or lines!)
+before Perl prints \f(CW$_\fR:
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqprint "Put before third line\en" if $. == 3\*(Aq inFile.txt
+.Ve
+.PP
+You can even add a line to the beginning of a file, since the current
+line prints at the end of the loop:
+.PP
+.Vb 1
+\&    perl \-pi \-e \*(Aqprint "Put before first line\en" if $. == 1\*(Aq inFile.txt
+.Ve
+.PP
+To insert a line after one already in the file, use the \f(CW\*(C`\-n\*(C'\fR switch.
+It's just like \f(CW\*(C`\-p\*(C'\fR except that it doesn't print \f(CW$_\fR at the end of
+the loop, so you have to do that yourself. In this case, print \f(CW$_\fR
+first, then print the line that you want to add.
+.PP
+.Vb 1
+\&    perl \-ni \-e \*(Aqprint; print "Put after fifth line\en" if $. == 5\*(Aq inFile.txt
+.Ve
+.PP
+To delete lines, only print the ones that you want.
+.PP
+.Vb 1
+\&    perl \-ni \-e \*(Aqprint if /d/\*(Aq inFile.txt
+.Ve
+.SS "How do I count the number of lines in a file?"
+.IX Xref "file, counting lines lines line"
+.IX Subsection "How do I count the number of lines in a file?"
+(contributed by brian d foy)
+.PP
+Conceptually, the easiest way to count the lines in a file is to
+simply read them and count them:
+.PP
+.Vb 2
+\&    my $count = 0;
+\&    while( <$fh> ) { $count++; }
+.Ve
+.PP
+You don't really have to count them yourself, though, since Perl
+already does that with the \f(CW$.\fR variable, which is the current line
+number from the last filehandle read:
+.PP
+.Vb 2
+\&    1 while( <$fh> );
+\&    my $count = $.;
+.Ve
+.PP
+If you want to use \f(CW$.\fR, you can reduce it to a simple one-liner,
+like one of these:
+.PP
+.Vb 1
+\&    % perl \-lne \*(Aq} print $.; {\*(Aq    file
+\&
+\&    % perl \-lne \*(AqEND { print $. }\*(Aq file
+.Ve
+.PP
+Those can be rather inefficient though. If they aren't fast enough for
+you, you might just read chunks of data and count the number of
+newlines:
+.PP
+.Vb 6
+\&    my $lines = 0;
+\&    open my($fh), \*(Aq<:raw\*(Aq, $filename or die "Can\*(Aqt open $filename: $!";
+\&    while( sysread $fh, $buffer, 4096 ) {
+\&        $lines += ( $buffer =~ tr/\en// );
+\&    }
+\&    close $fh;
+.Ve
+.PP
+However, that doesn't work if the line ending isn't a newline. You
+might change that \f(CW\*(C`tr///\*(C'\fR to a \f(CW\*(C`s///\*(C'\fR so you can count the number of
+times the input record separator, \f(CW$/\fR, shows up:
+.PP
+.Vb 6
+\&    my $lines = 0;
+\&    open my($fh), \*(Aq<:raw\*(Aq, $filename or die "Can\*(Aqt open $filename: $!";
+\&    while( sysread $fh, $buffer, 4096 ) {
+\&        $lines += ( $buffer =~ s|$/||g; );
+\&    }
+\&    close $fh;
+.Ve
+.PP
+If you don't mind shelling out, the \f(CW\*(C`wc\*(C'\fR command is usually the
+fastest, even with the extra interprocess overhead. Ensure that you
+have an untainted filename though:
+.PP
+.Vb 1
+\&    #!perl \-T
+\&
+\&    $ENV{PATH} = undef;
+\&
+\&    my $lines;
+\&    if( $filename =~ /^([0\-9a\-z_.]+)\ez/ ) {
+\&        $lines = \`/usr/bin/wc \-l $1\`
+\&        chomp $lines;
+\&    }
+.Ve
+.SS "How do I delete the last N lines from a file?"
+.IX Xref "lines file"
+.IX Subsection "How do I delete the last N lines from a file?"
+(contributed by brian d foy)
+.PP
+The easiest conceptual solution is to count the lines in the
+file then start at the beginning and print the number of lines
+(minus the last N) to a new file.
+.PP
+Most often, the real question is how you can delete the last N lines
+without making more than one pass over the file, or how to do it
+without a lot of copying. The easy concept is the hard reality when
+you might have millions of lines in your file.
+.PP
+One trick is to use File::ReadBackwards, which starts at the end of
+the file. That module provides an object that wraps the real filehandle
+to make it easy for you to move around the file. Once you get to the
+spot you need, you can get the actual filehandle and work with it as
+normal. In this case, you get the file position at the end of the last
+line you want to keep and truncate the file to that point:
+.PP
+.Vb 1
+\&    use File::ReadBackwards;
+\&
+\&    my $filename = \*(Aqtest.txt\*(Aq;
+\&    my $Lines_to_truncate = 2;
+\&
+\&    my $bw = File::ReadBackwards\->new( $filename )
+\&        or die "Could not read backwards in [$filename]: $!";
+\&
+\&    my $lines_from_end = 0;
+\&    until( $bw\->eof or $lines_from_end == $Lines_to_truncate ) {
+\&        print "Got: ", $bw\->readline;
+\&        $lines_from_end++;
+\&    }
+\&
+\&    truncate( $filename, $bw\->tell );
+.Ve
+.PP
+The File::ReadBackwards module also has the advantage of setting
+the input record separator to a regular expression.
+.PP
+You can also use the Tie::File module which lets you access
+the lines through a tied array. You can use normal array operations
+to modify your file, including setting the last index and using
+\&\f(CW\*(C`splice\*(C'\fR.
+.ie n .SS "How can I use Perl's ""\-i"" option from within a program?"
+.el .SS "How can I use Perl's \f(CW\-i\fP option from within a program?"
+.IX Xref "-i in-place"
+.IX Subsection "How can I use Perl's -i option from within a program?"
+\&\f(CW\*(C`\-i\*(C'\fR sets the value of Perl's \f(CW$^I\fR variable, which in turn affects
+the behavior of \f(CW\*(C`<>\*(C'\fR; see perlrun for more details. By
+modifying the appropriate variables directly, you can get the same
+behavior within a larger program. For example:
+.PP
+.Vb 10
+\&    # ...
+\&    {
+\&        local($^I, @ARGV) = (\*(Aq.orig\*(Aq, glob("*.c"));
+\&        while (<>) {
+\&            if ($. == 1) {
+\&                print "This line should appear at the top of each file\en";
+\&            }
+\&            s/\eb(p)earl\eb/${1}erl/i;        # Correct typos, preserving case
+\&            print;
+\&            close ARGV if eof;              # Reset $.
+\&        }
+\&    }
+\&    # $^I and @ARGV return to their old values here
+.Ve
+.PP
+This block modifies all the \f(CW\*(C`.c\*(C'\fR files in the current directory,
+leaving a backup of the original data from each file in a new
+\&\f(CW\*(C`.c.orig\*(C'\fR file.
+.SS "How can I copy a file?"
+.IX Xref "copy file, copy File::Copy"
+.IX Subsection "How can I copy a file?"
+(contributed by brian d foy)
+.PP
+Use the File::Copy module. It comes with Perl and can do a
+true copy across file systems, and it does its magic in
+a portable fashion.
+.PP
+.Vb 1
+\&    use File::Copy;
+\&
+\&    copy( $original, $new_copy ) or die "Copy failed: $!";
+.Ve
+.PP
+If you can't use File::Copy, you'll have to do the work yourself:
+open the original file, open the destination file, then print
+to the destination file as you read the original. You also have to
+remember to copy the permissions, owner, and group to the new file.
+.SS "How do I make a temporary file name?"
+.IX Xref "file, temporary"
+.IX Subsection "How do I make a temporary file name?"
+If you don't need to know the name of the file, you can use \f(CWopen()\fR
+with \f(CW\*(C`undef\*(C'\fR in place of the file name. In Perl 5.8 or later, the
+\&\f(CWopen()\fR function creates an anonymous temporary file:
+.PP
+.Vb 1
+\&    open my $tmp, \*(Aq+>\*(Aq, undef or die $!;
+.Ve
+.PP
+Otherwise, you can use the File::Temp module.
+.PP
+.Vb 1
+\&    use File::Temp qw/ tempfile tempdir /;
+\&
+\&    my $dir = tempdir( CLEANUP => 1 );
+\&    ($fh, $filename) = tempfile( DIR => $dir );
+\&
+\&    # or if you don\*(Aqt need to know the filename
+\&
+\&    my $fh = tempfile( DIR => $dir );
+.Ve
+.PP
+The File::Temp has been a standard module since Perl 5.6.1. If you
+don't have a modern enough Perl installed, use the \f(CW\*(C`new_tmpfile\*(C'\fR
+class method from the IO::File module to get a filehandle opened for
+reading and writing. Use it if you don't need to know the file's name:
+.PP
+.Vb 3
+\&    use IO::File;
+\&    my $fh = IO::File\->new_tmpfile()
+\&        or die "Unable to make new temporary file: $!";
+.Ve
+.PP
+If you're committed to creating a temporary file by hand, use the
+process ID and/or the current time-value. If you need to have many
+temporary files in one process, use a counter:
+.PP
+.Vb 6
+\&    BEGIN {
+\&        use Fcntl;
+\&        use File::Spec;
+\&        my $temp_dir  = File::Spec\->tmpdir();
+\&        my $file_base = sprintf "%d\-%d\-0000", $$, time;
+\&        my $base_name = File::Spec\->catfile($temp_dir, $file_base);
+\&
+\&        sub temp_file {
+\&            my $fh;
+\&            my $count = 0;
+\&            until( defined(fileno($fh)) || $count++ > 100 ) {
+\&                $base_name =~ s/\-(\ed+)$/"\-" . (1 + $1)/e;
+\&                # O_EXCL is required for security reasons.
+\&                sysopen $fh, $base_name, O_WRONLY|O_EXCL|O_CREAT;
+\&            }
+\&
+\&            if( defined fileno($fh) ) {
+\&                return ($fh, $base_name);
+\&            }
+\&            else {
+\&                return ();
+\&            }
+\&        }
+\&    }
+.Ve
+.SS "How can I manipulate fixed-record-length files?"
+.IX Xref "fixed-length file, fixed-length records"
+.IX Subsection "How can I manipulate fixed-record-length files?"
+The most efficient way is using \fBpack()\fR and
+\&\fBunpack()\fR. This is faster than using
+\&\fBsubstr()\fR when taking many, many strings. It is
+slower for just a few.
+.PP
+Here is a sample chunk of code to break up and put back together again
+some fixed-format input lines, in this case from the output of a normal,
+Berkeley-style ps:
+.PP
+.Vb 10
+\&    # sample input line:
+\&    #   15158 p5  T      0:00 perl /home/tchrist/scripts/now\-what
+\&    my $PS_T = \*(AqA6 A4 A7 A5 A*\*(Aq;
+\&    open my $ps, \*(Aq\-|\*(Aq, \*(Aqps\*(Aq;
+\&    print scalar <$ps>;
+\&    my @fields = qw( pid tt stat time command );
+\&    while (<$ps>) {
+\&        my %process;
+\&        @process{@fields} = unpack($PS_T, $_);
+\&        for my $field ( @fields ) {
+\&            print "$field: <$process{$field}>\en";
+\&        }
+\&        print \*(Aqline=\*(Aq, pack($PS_T, @process{@fields} ), "\en";
+\&    }
+.Ve
+.PP
+We've used a hash slice in order to easily handle the fields of each row.
+Storing the keys in an array makes it easy to operate on them as a
+group or loop over them with \f(CW\*(C`for\*(C'\fR. It also avoids polluting the program
+with global variables and using symbolic references.
+.SS "How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?"
+.IX Xref "filehandle, local filehandle, passing filehandle, reference"
+.IX Subsection "How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?"
+As of perl5.6, \fBopen()\fR autovivifies file and directory handles
+as references if you pass it an uninitialized scalar variable.
+You can then pass these references just like any other scalar,
+and use them in the place of named handles.
+.PP
+.Vb 1
+\&    open my    $fh, $file_name;
+\&
+\&    open local $fh, $file_name;
+\&
+\&    print $fh "Hello World!\en";
+\&
+\&    process_file( $fh );
+.Ve
+.PP
+If you like, you can store these filehandles in an array or a hash.
+If you access them directly, they aren't simple scalars and you
+need to give \f(CW\*(C`print\*(C'\fR a little help by placing the filehandle
+reference in braces. Perl can only figure it out on its own when
+the filehandle reference is a simple scalar.
+.PP
+.Vb 1
+\&    my @fhs = ( $fh1, $fh2, $fh3 );
+\&
+\&    for( $i = 0; $i <= $#fhs; $i++ ) {
+\&        print {$fhs[$i]} "just another Perl answer, \en";
+\&    }
+.Ve
+.PP
+Before perl5.6, you had to deal with various typeglob idioms
+which you may see in older code.
+.PP
+.Vb 3
+\&    open FILE, "> $filename";
+\&    process_typeglob(   *FILE );
+\&    process_reference( \e*FILE );
+\&
+\&    sub process_typeglob  { local *FH = shift; print FH  "Typeglob!" }
+\&    sub process_reference { local $fh = shift; print $fh "Reference!" }
+.Ve
+.PP
+If you want to create many anonymous handles, you should
+check out the Symbol or IO::Handle modules.
+.SS "How can I use a filehandle indirectly?"
+.IX Xref "filehandle, indirect"
+.IX Subsection "How can I use a filehandle indirectly?"
+An indirect filehandle is the use of something other than a symbol
+in a place that a filehandle is expected. Here are ways
+to get indirect filehandles:
+.PP
+.Vb 5
+\&    $fh =   SOME_FH;       # bareword is strict\-subs hostile
+\&    $fh =  "SOME_FH";      # strict\-refs hostile; same package only
+\&    $fh =  *SOME_FH;       # typeglob
+\&    $fh = \e*SOME_FH;       # ref to typeglob (bless\-able)
+\&    $fh =  *SOME_FH{IO};   # blessed IO::Handle from *SOME_FH typeglob
+.Ve
+.PP
+Or, you can use the \f(CW\*(C`new\*(C'\fR method from one of the IO::* modules to
+create an anonymous filehandle and store that in a scalar variable.
+.PP
+.Vb 2
+\&    use IO::Handle;                     # 5.004 or higher
+\&    my $fh = IO::Handle\->new();
+.Ve
+.PP
+Then use any of those as you would a normal filehandle. Anywhere that
+Perl is expecting a filehandle, an indirect filehandle may be used
+instead. An indirect filehandle is just a scalar variable that contains
+a filehandle. Functions like \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`seek\*(C'\fR, or
+the \f(CW\*(C`<FH>\*(C'\fR diamond operator will accept either a named filehandle
+or a scalar variable containing one:
+.PP
+.Vb 4
+\&    ($ifh, $ofh, $efh) = (*STDIN, *STDOUT, *STDERR);
+\&    print $ofh "Type it: ";
+\&    my $got = <$ifh>
+\&    print $efh "What was that: $got";
+.Ve
+.PP
+If you're passing a filehandle to a function, you can write
+the function in two ways:
+.PP
+.Vb 4
+\&    sub accept_fh {
+\&        my $fh = shift;
+\&        print $fh "Sending to indirect filehandle\en";
+\&    }
+.Ve
+.PP
+Or it can localize a typeglob and use the filehandle directly:
+.PP
+.Vb 4
+\&    sub accept_fh {
+\&        local *FH = shift;
+\&        print  FH "Sending to localized filehandle\en";
+\&    }
+.Ve
+.PP
+Both styles work with either objects or typeglobs of real filehandles.
+(They might also work with strings under some circumstances, but this
+is risky.)
+.PP
+.Vb 2
+\&    accept_fh(*STDOUT);
+\&    accept_fh($handle);
+.Ve
+.PP
+In the examples above, we assigned the filehandle to a scalar variable
+before using it. That is because only simple scalar variables, not
+expressions or subscripts of hashes or arrays, can be used with
+built-ins like \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, or the diamond operator. Using
+something other than a simple scalar variable as a filehandle is
+illegal and won't even compile:
+.PP
+.Vb 4
+\&    my @fd = (*STDIN, *STDOUT, *STDERR);
+\&    print $fd[1] "Type it: ";                           # WRONG
+\&    my $got = <$fd[0]>                                  # WRONG
+\&    print $fd[2] "What was that: $got";                 # WRONG
+.Ve
+.PP
+With \f(CW\*(C`print\*(C'\fR and \f(CW\*(C`printf\*(C'\fR, you get around this by using a block and
+an expression where you would place the filehandle:
+.PP
+.Vb 3
+\&    print  { $fd[1] } "funny stuff\en";
+\&    printf { $fd[1] } "Pity the poor %x.\en", 3_735_928_559;
+\&    # Pity the poor deadbeef.
+.Ve
+.PP
+That block is a proper block like any other, so you can put more
+complicated code there. This sends the message out to one of two places:
+.PP
+.Vb 3
+\&    my $ok = \-x "/bin/cat";
+\&    print { $ok ? $fd[1] : $fd[2] } "cat stat $ok\en";
+\&    print { $fd[ 1+ ($ok || 0) ]  } "cat stat $ok\en";
+.Ve
+.PP
+This approach of treating \f(CW\*(C`print\*(C'\fR and \f(CW\*(C`printf\*(C'\fR like object methods
+calls doesn't work for the diamond operator. That's because it's a
+real operator, not just a function with a comma-less argument. Assuming
+you've been storing typeglobs in your structure as we did above, you
+can use the built-in function named \f(CW\*(C`readline\*(C'\fR to read a record just
+as \f(CW\*(C`<>\*(C'\fR does. Given the initialization shown above for \f(CW@fd\fR, this
+would work, but only because \fBreadline()\fR requires a typeglob. It doesn't
+work with objects or strings, which might be a bug we haven't fixed yet.
+.PP
+.Vb 1
+\&    $got = readline($fd[0]);
+.Ve
+.PP
+Let it be noted that the flakiness of indirect filehandles is not
+related to whether they're strings, typeglobs, objects, or anything else.
+It's the syntax of the fundamental operators. Playing the object
+game doesn't help you at all here.
+.SS "How can I open a filehandle to a string?"
+.IX Xref "string open IO::String filehandle"
+.IX Subsection "How can I open a filehandle to a string?"
+(contributed by Peter J. Holzer, hjp\-usenet2@hjp.at)
+.PP
+Since Perl 5.8.0 a file handle referring to a string can be created by
+calling open with a reference to that string instead of the filename.
+This file handle can then be used to read from or write to the string:
+.PP
+.Vb 3
+\&    open(my $fh, \*(Aq>\*(Aq, \e$string) or die "Could not open string for writing";
+\&    print $fh "foo\en";
+\&    print $fh "bar\en";    # $string now contains "foo\enbar\en"
+\&
+\&    open(my $fh, \*(Aq<\*(Aq, \e$string) or die "Could not open string for reading";
+\&    my $x = <$fh>;    # $x now contains "foo\en"
+.Ve
+.PP
+With older versions of Perl, the IO::String module provides similar
+functionality.
+.SS "How can I set up a footer format to be used with \fBwrite()\fP?"
+.IX Xref "footer"
+.IX Subsection "How can I set up a footer format to be used with write()?"
+There's no builtin way to do this, but perlform has a couple of
+techniques to make it possible for the intrepid hacker.
+.SS "How can I \fBwrite()\fP into a string?"
+.IX Xref "write, into a string"
+.IX Subsection "How can I write() into a string?"
+(contributed by brian d foy)
+.PP
+If you want to \f(CW\*(C`write\*(C'\fR into a string, you just have to <open> a
+filehandle to a string, which Perl has been able to do since Perl 5.6:
+.PP
+.Vb 2
+\&    open FH, \*(Aq>\*(Aq, \emy $string;
+\&    write( FH );
+.Ve
+.PP
+Since you want to be a good programmer, you probably want to use a lexical
+filehandle, even though formats are designed to work with bareword filehandles
+since the default format names take the filehandle name. However, you can
+control this with some Perl special per-filehandle variables: \f(CW$^\fR, which
+names the top-of-page format, and \f(CW$~\fR which shows the line format. You have
+to change the default filehandle to set these variables:
+.PP
+.Vb 1
+\&    open my($fh), \*(Aq>\*(Aq, \emy $string;
+\&
+\&    { # set per\-filehandle variables
+\&        my $old_fh = select( $fh );
+\&        $~ = \*(AqANIMAL\*(Aq;
+\&        $^ = \*(AqANIMAL_TOP\*(Aq;
+\&        select( $old_fh );
+\&    }
+\&
+\&    format ANIMAL_TOP =
+\&     ID  Type    Name
+\&    .
+\&
+\&    format ANIMAL =
+\&    @##   @<<<    @<<<<<<<<<<<<<<
+\&    $id,  $type,  $name
+\&    .
+.Ve
+.PP
+Although write can work with lexical or package variables, whatever variables
+you use have to scope in the format. That most likely means you'll want to
+localize some package variables:
+.PP
+.Vb 4
+\&    {
+\&        local( $id, $type, $name ) = qw( 12 cat Buster );
+\&        write( $fh );
+\&    }
+\&
+\&    print $string;
+.Ve
+.PP
+There are also some tricks that you can play with \f(CW\*(C`formline\*(C'\fR and the
+accumulator variable \f(CW$^A\fR, but you lose a lot of the value of formats
+since \f(CW\*(C`formline\*(C'\fR won't handle paging and so on. You end up reimplementing
+formats when you use them.
+.SS "How can I output my numbers with commas added?"
+.IX Xref "number, commify"
+.IX Subsection "How can I output my numbers with commas added?"
+(contributed by brian d foy and Benjamin Goldberg)
+.PP
+You can use Number::Format to separate places in a number.
+It handles locale information for those of you who want to insert
+full stops instead (or anything else that they want to use,
+really).
+.PP
+This subroutine will add commas to your number:
+.PP
+.Vb 5
+\&    sub commify {
+\&        local $_  = shift;
+\&        1 while s/^([\-+]?\ed+)(\ed{3})/$1,$2/;
+\&        return $_;
+\&    }
+.Ve
+.PP
+This regex from Benjamin Goldberg will add commas to numbers:
+.PP
+.Vb 1
+\&    s/(^[\-+]?\ed+?(?=(?>(?:\ed{3})+)(?!\ed))|\eG\ed{3}(?=\ed))/$1,/g;
+.Ve
+.PP
+It is easier to see with comments:
+.PP
+.Vb 11
+\&    s/(
+\&        ^[\-+]?             # beginning of number.
+\&        \ed+?               # first digits before first comma
+\&        (?=                # followed by, (but not included in the match) :
+\&            (?>(?:\ed{3})+) # some positive multiple of three digits.
+\&            (?!\ed)         # an *exact* multiple, not x * 3 + 1 or whatever.
+\&        )
+\&        |                  # or:
+\&        \eG\ed{3}            # after the last group, get three digits
+\&        (?=\ed)             # but they have to have more digits after them.
+\&    )/$1,/xg;
+.Ve
+.SS "How can I translate tildes (~) in a filename?"
+.IX Xref "tilde tilde expansion"
+.IX Subsection "How can I translate tildes (~) in a filename?"
+Use the <> (\f(CWglob()\fR) operator, documented in perlfunc.
+Versions of Perl older than 5.6 require that you have a shell
+installed that groks tildes. Later versions of Perl have this feature
+built in. The File::KGlob module (available from CPAN) gives more
+portable glob functionality.
+.PP
+Within Perl, you may use this directly:
+.PP
+.Vb 11
+\&    $filename =~ s{
+\&      ^ ~             # find a leading tilde
+\&      (               # save this in $1
+\&          [^/]        # a non\-slash character
+\&                *     # repeated 0 or more times (0 means me)
+\&      )
+\&    }{
+\&      $1
+\&          ? (getpwnam($1))[7]
+\&          : ( $ENV{HOME} || $ENV{LOGDIR} )
+\&    }ex;
+.Ve
+.SS "How come when I open a file read-write it wipes it out?"
+.IX Xref "clobber read-write clobbering truncate truncating"
+.IX Subsection "How come when I open a file read-write it wipes it out?"
+Because you're using something like this, which truncates the file
+\&\fIthen\fR gives you read-write access:
+.PP
+.Vb 1
+\&    open my $fh, \*(Aq+>\*(Aq, \*(Aq/path/name\*(Aq; # WRONG (almost always)
+.Ve
+.PP
+Whoops. You should instead use this, which will fail if the file
+doesn't exist:
+.PP
+.Vb 1
+\&    open my $fh, \*(Aq+<\*(Aq, \*(Aq/path/name\*(Aq; # open for update
+.Ve
+.PP
+Using ">" always clobbers or creates. Using "<" never does
+either. The "+" doesn't change this.
+.PP
+Here are examples of many kinds of file opens. Those using \f(CW\*(C`sysopen\*(C'\fR
+all assume that you've pulled in the constants from Fcntl:
+.PP
+.Vb 1
+\&    use Fcntl;
+.Ve
+.PP
+To open file for reading:
+.PP
+.Vb 2
+\&    open my $fh, \*(Aq<\*(Aq, $path                               or die $!;
+\&    sysopen my $fh, $path, O_RDONLY                       or die $!;
+.Ve
+.PP
+To open file for writing, create new file if needed or else truncate old file:
+.PP
+.Vb 3
+\&    open my $fh, \*(Aq>\*(Aq, $path                               or die $!;
+\&    sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT       or die $!;
+\&    sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666 or die $!;
+.Ve
+.PP
+To open file for writing, create new file, file must not exist:
+.PP
+.Vb 2
+\&    sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT        or die $!;
+\&    sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT, 0666  or die $!;
+.Ve
+.PP
+To open file for appending, create if necessary:
+.PP
+.Vb 3
+\&    open my $fh, \*(Aq>>\*(Aq, $path                              or die $!;
+\&    sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT      or die $!;
+\&    sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT, 0666 or die $!;
+.Ve
+.PP
+To open file for appending, file must exist:
+.PP
+.Vb 1
+\&    sysopen my $fh, $path, O_WRONLY|O_APPEND              or die $!;
+.Ve
+.PP
+To open file for update, file must exist:
+.PP
+.Vb 2
+\&    open my $fh, \*(Aq+<\*(Aq, $path                              or die $!;
+\&    sysopen my $fh, $path, O_RDWR                         or die $!;
+.Ve
+.PP
+To open file for update, create file if necessary:
+.PP
+.Vb 2
+\&    sysopen my $fh, $path, O_RDWR|O_CREAT                 or die $!;
+\&    sysopen my $fh, $path, O_RDWR|O_CREAT, 0666           or die $!;
+.Ve
+.PP
+To open file for update, file must not exist:
+.PP
+.Vb 2
+\&    sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT          or die $!;
+\&    sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT, 0666    or die $!;
+.Ve
+.PP
+To open a file without blocking, creating if necessary:
+.PP
+.Vb 2
+\&    sysopen my $fh, \*(Aq/foo/somefile\*(Aq, O_WRONLY|O_NDELAY|O_CREAT
+\&        or die "can\*(Aqt open /foo/somefile: $!":
+.Ve
+.PP
+Be warned that neither creation nor deletion of files is guaranteed to
+be an atomic operation over NFS. That is, two processes might both
+successfully create or unlink the same file! Therefore O_EXCL
+isn't as exclusive as you might wish.
+.PP
+See also perlopentut.
+.SS "Why do I sometimes get an ""Argument list too long"" when I use <*>?"
+.IX Xref "argument list too long"
+.IX Subsection "Why do I sometimes get an ""Argument list too long"" when I use <*>?"
+The \f(CW\*(C`<>\*(C'\fR operator performs a globbing operation (see above).
+In Perl versions earlier than v5.6.0, the internal \fBglob()\fR operator forks
+\&\fBcsh\fR\|(1) to do the actual glob expansion, but
+csh can't handle more than 127 items and so gives the error message
+\&\f(CW\*(C`Argument list too long\*(C'\fR. People who installed tcsh as csh won't
+have this problem, but their users may be surprised by it.
+.PP
+To get around this, either upgrade to Perl v5.6.0 or later, do the glob
+yourself with \fBreaddir()\fR and patterns, or use a module like File::Glob,
+one that doesn't use the shell to do globbing.
+.SS "How can I open a file named with a leading "">"" or trailing blanks?"
+.IX Xref "filename, special characters"
+.IX Subsection "How can I open a file named with a leading "">"" or trailing blanks?"
+(contributed by Brian McCauley)
+.PP
+The special two-argument form of Perl's \fBopen()\fR function ignores
+trailing blanks in filenames and infers the mode from certain leading
+characters (or a trailing "|"). In older versions of Perl this was the
+only version of \fBopen()\fR and so it is prevalent in old code and books.
+.PP
+Unless you have a particular reason to use the two-argument form you
+should use the three-argument form of \fBopen()\fR which does not treat any
+characters in the filename as special.
+.PP
+.Vb 2
+\&    open my $fh, "<", "  file  ";  # filename is "   file   "
+\&    open my $fh, ">", ">file";     # filename is ">file"
+.Ve
+.SS "How can I reliably rename a file?"
+.IX Xref "rename mv move file, rename"
+.IX Subsection "How can I reliably rename a file?"
+If your operating system supports a proper \fBmv\fR\|(1) utility or its
+functional equivalent, this works:
+.PP
+.Vb 1
+\&    rename($old, $new) or system("mv", $old, $new);
+.Ve
+.PP
+It may be more portable to use the File::Copy module instead.
+You just copy to the new file to the new name (checking return
+values), then delete the old one. This isn't really the same
+semantically as a \f(CWrename()\fR, which preserves meta-information like
+permissions, timestamps, inode info, etc.
+.SS "How can I lock a file?"
+.IX Xref "lock file, lock flock"
+.IX Subsection "How can I lock a file?"
+Perl's builtin \fBflock()\fR function (see perlfunc for details) will call
+\&\fBflock\fR\|(2) if that exists, \fBfcntl\fR\|(2) if it doesn't (on perl version 5.004 and
+later), and \fBlockf\fR\|(3) if neither of the two previous system calls exists.
+On some systems, it may even use a different form of native locking.
+Here are some gotchas with Perl's \fBflock()\fR:
+.IP 1. 4
+Produces a fatal error if none of the three system calls (or their
+close equivalent) exists.
+.IP 2. 4
+\&\fBlockf\fR\|(3) does not provide shared locking, and requires that the
+filehandle be open for writing (or appending, or read/writing).
+.IP 3. 4
+Some versions of \fBflock()\fR can't lock files over a network (e.g. on NFS file
+systems), so you'd need to force the use of \fBfcntl\fR\|(2) when you build Perl.
+But even this is dubious at best. See the flock entry of perlfunc
+and the \fIINSTALL\fR file in the source distribution for information on
+building Perl to do this.
+.Sp
+Two potentially non-obvious but traditional flock semantics are that
+it waits indefinitely until the lock is granted, and that its locks are
+\&\fImerely advisory\fR. Such discretionary locks are more flexible, but
+offer fewer guarantees. This means that files locked with \fBflock()\fR may
+be modified by programs that do not also use \fBflock()\fR. Cars that stop
+for red lights get on well with each other, but not with cars that don't
+stop for red lights. See the perlport manpage, your port's specific
+documentation, or your system-specific local manpages for details. It's
+best to assume traditional behavior if you're writing portable programs.
+(If you're not, you should as always feel perfectly free to write
+for your own system's idiosyncrasies (sometimes called "features").
+Slavish adherence to portability concerns shouldn't get in the way of
+your getting your job done.)
+.Sp
+For more information on file locking, see also
+"File Locking" in perlopentut if you have it (new for 5.6).
+.SS "Why can't I just open(FH, "">file.lock"")?"
+.IX Xref "lock, lockfile race condition"
+.IX Subsection "Why can't I just open(FH, "">file.lock"")?"
+A common bit of code \fBNOT TO USE\fR is this:
+.PP
+.Vb 2
+\&    sleep(3) while \-e \*(Aqfile.lock\*(Aq;    # PLEASE DO NOT USE
+\&    open my $lock, \*(Aq>\*(Aq, \*(Aqfile.lock\*(Aq; # THIS BROKEN CODE
+.Ve
+.PP
+This is a classic race condition: you take two steps to do something
+which must be done in one. That's why computer hardware provides an
+atomic test-and-set instruction. In theory, this "ought" to work:
+.PP
+.Vb 2
+\&    sysopen my $fh, "file.lock", O_WRONLY|O_EXCL|O_CREAT
+\&        or die "can\*(Aqt open  file.lock: $!";
+.Ve
+.PP
+except that lamentably, file creation (and deletion) is not atomic
+over NFS, so this won't work (at least, not every time) over the net.
+Various schemes involving \fBlink()\fR have been suggested, but
+these tend to involve busy-wait, which is also less than desirable.
+.SS "I still don't get locking. I just want to increment the number in the file. How can I do this?"
+.IX Xref "counter file, counter"
+.IX Subsection "I still don't get locking. I just want to increment the number in the file. How can I do this?"
+Didn't anyone ever tell you web-page hit counters were useless?
+They don't count number of hits, they're a waste of time, and they serve
+only to stroke the writer's vanity. It's better to pick a random number;
+they're more realistic.
+.PP
+Anyway, this is what you can do if you can't help yourself.
+.PP
+.Vb 8
+\&    use Fcntl qw(:DEFAULT :flock);
+\&    sysopen my $fh, "numfile", O_RDWR|O_CREAT or die "can\*(Aqt open numfile: $!";
+\&    flock $fh, LOCK_EX                        or die "can\*(Aqt flock numfile: $!";
+\&    my $num = <$fh> || 0;
+\&    seek $fh, 0, 0                            or die "can\*(Aqt rewind numfile: $!";
+\&    truncate $fh, 0                           or die "can\*(Aqt truncate numfile: $!";
+\&    (print $fh $num+1, "\en")                  or die "can\*(Aqt write numfile: $!";
+\&    close $fh                                 or die "can\*(Aqt close numfile: $!";
+.Ve
+.PP
+Here's a much better web-page hit counter:
+.PP
+.Vb 1
+\&    $hits = int( (time() \- 850_000_000) / rand(1_000) );
+.Ve
+.PP
+If the count doesn't impress your friends, then the code might. :\-)
+.SS "All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?"
+.IX Xref "append file, append"
+.IX Subsection "All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?"
+If you are on a system that correctly implements \f(CW\*(C`flock\*(C'\fR and you use
+the example appending code from "perldoc \-f flock" everything will be
+OK even if the OS you are on doesn't implement append mode correctly
+(if such a system exists). So if you are happy to restrict yourself to
+OSs that implement \f(CW\*(C`flock\*(C'\fR (and that's not really much of a
+restriction) then that is what you should do.
+.PP
+If you know you are only going to use a system that does correctly
+implement appending (i.e. not Win32) then you can omit the \f(CW\*(C`seek\*(C'\fR
+from the code in the previous answer.
+.PP
+If you know you are only writing code to run on an OS and filesystem
+that does implement append mode correctly (a local filesystem on a
+modern Unix for example), and you keep the file in block-buffered mode
+and you write less than one buffer-full of output between each manual
+flushing of the buffer then each bufferload is almost guaranteed to be
+written to the end of the file in one chunk without getting
+intermingled with anyone else's output. You can also use the
+\&\f(CW\*(C`syswrite\*(C'\fR function which is simply a wrapper around your system's
+\&\f(CWwrite(2)\fR system call.
+.PP
+There is still a small theoretical chance that a signal will interrupt
+the system-level \f(CWwrite()\fR operation before completion. There is also
+a possibility that some STDIO implementations may call multiple system
+level \f(CWwrite()\fRs even if the buffer was empty to start. There may be
+some systems where this probability is reduced to zero, and this is
+not a concern when using \f(CW\*(C`:perlio\*(C'\fR instead of your system's STDIO.
+.SS "How do I randomly update a binary file?"
+.IX Xref "file, binary patch"
+.IX Subsection "How do I randomly update a binary file?"
+If you're just trying to patch a binary, in many cases something as
+simple as this works:
+.PP
+.Vb 1
+\&    perl \-i \-pe \*(Aqs{window manager}{window mangler}g\*(Aq /usr/bin/emacs
+.Ve
+.PP
+However, if you have fixed sized records, then you might do something more
+like this:
+.PP
+.Vb 9
+\&    my $RECSIZE = 220; # size of record, in bytes
+\&    my $recno   = 37;  # which record to update
+\&    open my $fh, \*(Aq+<\*(Aq, \*(Aqsomewhere\*(Aq or die "can\*(Aqt update somewhere: $!";
+\&    seek $fh, $recno * $RECSIZE, 0;
+\&    read $fh, $record, $RECSIZE == $RECSIZE or die "can\*(Aqt read record $recno: $!";
+\&    # munge the record
+\&    seek $fh, \-$RECSIZE, 1;
+\&    print $fh $record;
+\&    close $fh;
+.Ve
+.PP
+Locking and error checking are left as an exercise for the reader.
+Don't forget them or you'll be quite sorry.
+.SS "How do I get a file's timestamp in perl?"
+.IX Xref "timestamp file, timestamp"
+.IX Subsection "How do I get a file's timestamp in perl?"
+If you want to retrieve the time at which the file was last read,
+written, or had its meta-data (owner, etc) changed, you use the \fB\-A\fR,
+\&\fB\-M\fR, or \fB\-C\fR file test operations as documented in perlfunc.
+These retrieve the age of the file (measured against the start-time of
+your program) in days as a floating point number. Some platforms may
+not have all of these times. See perlport for details. To retrieve
+the "raw" time in seconds since the epoch, you would call the stat
+function, then use \f(CWlocaltime()\fR, \f(CWgmtime()\fR, or
+\&\f(CWPOSIX::strftime()\fR to convert this into human-readable form.
+.PP
+Here's an example:
+.PP
+.Vb 3
+\&    my $write_secs = (stat($file))[9];
+\&    printf "file %s updated at %s\en", $file,
+\&        scalar localtime($write_secs);
+.Ve
+.PP
+If you prefer something more legible, use the File::stat module
+(part of the standard distribution in version 5.004 and later):
+.PP
+.Vb 5
+\&    # error checking left as an exercise for reader.
+\&    use File::stat;
+\&    use Time::localtime;
+\&    my $date_string = ctime(stat($file)\->mtime);
+\&    print "file $file updated at $date_string\en";
+.Ve
+.PP
+The \fBPOSIX::strftime()\fR approach has the benefit of being,
+in theory, independent of the current locale. See perllocale
+for details.
+.SS "How do I set a file's timestamp in perl?"
+.IX Xref "timestamp file, timestamp"
+.IX Subsection "How do I set a file's timestamp in perl?"
+You use the \fButime()\fR function documented in "utime" in perlfunc.
+By way of example, here's a little program that copies the
+read and write times from its first argument to all the rest
+of them.
+.PP
+.Vb 6
+\&    if (@ARGV < 2) {
+\&        die "usage: cptimes timestamp_file other_files ...\en";
+\&    }
+\&    my $timestamp = shift;
+\&    my($atime, $mtime) = (stat($timestamp))[8,9];
+\&    utime $atime, $mtime, @ARGV;
+.Ve
+.PP
+Error checking is, as usual, left as an exercise for the reader.
+.PP
+The perldoc for utime also has an example that has the same
+effect as \fBtouch\fR\|(1) on files that \fIalready exist\fR.
+.PP
+Certain file systems have a limited ability to store the times
+on a file at the expected level of precision. For example, the
+FAT and HPFS filesystem are unable to create dates on files with
+a finer granularity than two seconds. This is a limitation of
+the filesystems, not of \fButime()\fR.
+.SS "How do I print to more than one file at once?"
+.IX Xref "print, to multiple files"
+.IX Subsection "How do I print to more than one file at once?"
+To connect one filehandle to several output filehandles,
+you can use the IO::Tee or Tie::FileHandle::Multiplex modules.
+.PP
+If you only have to do this once, you can print individually
+to each filehandle.
+.PP
+.Vb 1
+\&    for my $fh ($fh1, $fh2, $fh3) { print $fh "whatever\en" }
+.Ve
+.SS "How can I read in an entire file all at once?"
+.IX Xref "slurp file, slurping"
+.IX Subsection "How can I read in an entire file all at once?"
+The customary Perl approach for processing all the lines in a file is to
+do so one line at a time:
+.PP
+.Vb 6
+\&    open my $input, \*(Aq<\*(Aq, $file or die "can\*(Aqt open $file: $!";
+\&    while (<$input>) {
+\&        chomp;
+\&        # do something with $_
+\&    }
+\&    close $input or die "can\*(Aqt close $file: $!";
+.Ve
+.PP
+This is tremendously more efficient than reading the entire file into
+memory as an array of lines and then processing it one element at a time,
+which is often\-\-if not almost always\-\-the wrong approach. Whenever
+you see someone do this:
+.PP
+.Vb 1
+\&    my @lines = <INPUT>;
+.Ve
+.PP
+You should think long and hard about why you need everything loaded at
+once. It's just not a scalable solution.
+.PP
+If you "mmap" the file with the File::Map module from
+CPAN, you can virtually load the entire file into a
+string without actually storing it in memory:
+.PP
+.Vb 1
+\&    use File::Map qw(map_file);
+\&
+\&    map_file my $string, $filename;
+.Ve
+.PP
+Once mapped, you can treat \f(CW$string\fR as you would any other string.
+Since you don't necessarily have to load the data, mmap-ing can be
+very fast and may not increase your memory footprint.
+.PP
+You might also find it more
+fun to use the standard Tie::File module, or the DB_File module's
+\&\f(CW$DB_RECNO\fR bindings, which allow you to tie an array to a file so that
+accessing an element of the array actually accesses the corresponding
+line in the file.
+.PP
+If you want to load the entire file, you can use the Path::Tiny
+module to do it in one simple and efficient step:
+.PP
+.Vb 1
+\&    use Path::Tiny;
+\&
+\&    my $all_of_it = path($filename)\->slurp; # entire file in scalar
+\&    my @all_lines = path($filename)\->lines; # one line per element
+.Ve
+.PP
+Or you can read the entire file contents into a scalar like this:
+.PP
+.Vb 6
+\&    my $var;
+\&    {
+\&        local $/;
+\&        open my $fh, \*(Aq<\*(Aq, $file or die "can\*(Aqt open $file: $!";
+\&        $var = <$fh>;
+\&    }
+.Ve
+.PP
+That temporarily undefs your record separator, and will automatically
+close the file at block exit. If the file is already open, just use this:
+.PP
+.Vb 1
+\&    my $var = do { local $/; <$fh> };
+.Ve
+.PP
+You can also use a localized \f(CW@ARGV\fR to eliminate the \f(CW\*(C`open\*(C'\fR:
+.PP
+.Vb 1
+\&    my $var = do { local( @ARGV, $/ ) = $file; <> };
+.Ve
+.SS "How can I read in a file by paragraphs?"
+.IX Xref "file, reading by paragraphs"
+.IX Subsection "How can I read in a file by paragraphs?"
+Use the \f(CW$/\fR variable (see perlvar for details). You can either
+set it to \f(CW""\fR to eliminate empty paragraphs (\f(CW"abc\en\en\en\endef"\fR,
+for instance, gets treated as two paragraphs and not three), or
+\&\f(CW"\en\en"\fR to accept empty paragraphs.
+.PP
+Note that a blank line must have no blanks in it. Thus
+\&\f(CW"fred\en\ \enstuff\en\en"\fR is one paragraph, but \f(CW"fred\en\enstuff\en\en"\fR is two.
+.SS "How can I read a single character from a file? From the keyboard?"
+.IX Xref "getc file, reading one character at a time"
+.IX Subsection "How can I read a single character from a file? From the keyboard?"
+You can use the builtin \f(CWgetc()\fR function for most filehandles, but
+it won't (easily) work on a terminal device. For STDIN, either use
+the Term::ReadKey module from CPAN or use the sample code in
+"getc" in perlfunc.
+.PP
+If your system supports the portable operating system programming
+interface (POSIX), you can use the following code, which you'll note
+turns off echo processing as well.
+.PP
+.Vb 9
+\&    #!/usr/bin/perl \-w
+\&    use strict;
+\&    $| = 1;
+\&    for (1..4) {
+\&        print "gimme: ";
+\&        my $got = getone();
+\&        print "\-\-> $got\en";
+\&    }
+\&    exit;
+\&
+\&    BEGIN {
+\&        use POSIX qw(:termios_h);
+\&
+\&        my ($term, $oterm, $echo, $noecho, $fd_stdin);
+\&
+\&        my $fd_stdin = fileno(STDIN);
+\&
+\&        $term     = POSIX::Termios\->new();
+\&        $term\->getattr($fd_stdin);
+\&        $oterm     = $term\->getlflag();
+\&
+\&        $echo     = ECHO | ECHOK | ICANON;
+\&        $noecho   = $oterm & ~$echo;
+\&
+\&        sub cbreak {
+\&            $term\->setlflag($noecho);
+\&            $term\->setcc(VTIME, 1);
+\&            $term\->setattr($fd_stdin, TCSANOW);
+\&        }
+\&
+\&        sub cooked {
+\&            $term\->setlflag($oterm);
+\&            $term\->setcc(VTIME, 0);
+\&            $term\->setattr($fd_stdin, TCSANOW);
+\&        }
+\&
+\&        sub getone {
+\&            my $key = \*(Aq\*(Aq;
+\&            cbreak();
+\&            sysread(STDIN, $key, 1);
+\&            cooked();
+\&            return $key;
+\&        }
+\&    }
+\&
+\&    END { cooked() }
+.Ve
+.PP
+The Term::ReadKey module from CPAN may be easier to use. Recent versions
+include also support for non-portable systems as well.
+.PP
+.Vb 8
+\&    use Term::ReadKey;
+\&    open my $tty, \*(Aq<\*(Aq, \*(Aq/dev/tty\*(Aq;
+\&    print "Gimme a char: ";
+\&    ReadMode "raw";
+\&    my $key = ReadKey 0, $tty;
+\&    ReadMode "normal";
+\&    printf "\enYou said %s, char number %03d\en",
+\&        $key, ord $key;
+.Ve
+.SS "How can I tell whether there's a character waiting on a filehandle?"
+.IX Subsection "How can I tell whether there's a character waiting on a filehandle?"
+The very first thing you should do is look into getting the Term::ReadKey
+extension from CPAN. As we mentioned earlier, it now even has limited
+support for non-portable (read: not open systems, closed, proprietary,
+not POSIX, not Unix, etc.) systems.
+.PP
+You should also check out the Frequently Asked Questions list in
+comp.unix.* for things like this: the answer is essentially the same.
+It's very system-dependent. Here's one solution that works on BSD
+systems:
+.PP
+.Vb 5
+\&    sub key_ready {
+\&        my($rin, $nfd);
+\&        vec($rin, fileno(STDIN), 1) = 1;
+\&        return $nfd = select($rin,undef,undef,0);
+\&    }
+.Ve
+.PP
+If you want to find out how many characters are waiting, there's
+also the FIONREAD ioctl call to be looked at. The \fIh2ph\fR tool that
+comes with Perl tries to convert C include files to Perl code, which
+can be \f(CW\*(C`require\*(C'\fRd. FIONREAD ends up defined as a function in the
+\&\fIsys/ioctl.ph\fR file:
+.PP
+.Vb 1
+\&    require \*(Aq./sys/ioctl.ph\*(Aq;
+\&
+\&    $size = pack("L", 0);
+\&    ioctl(FH, FIONREAD(), $size)    or die "Couldn\*(Aqt call ioctl: $!\en";
+\&    $size = unpack("L", $size);
+.Ve
+.PP
+If \fIh2ph\fR wasn't installed or doesn't work for you, you can
+\&\fIgrep\fR the include files by hand:
+.PP
+.Vb 2
+\&    % grep FIONREAD /usr/include/*/*
+\&    /usr/include/asm/ioctls.h:#define FIONREAD      0x541B
+.Ve
+.PP
+Or write a small C program using the editor of champions:
+.PP
+.Vb 9
+\&    % cat > fionread.c
+\&    #include <sys/ioctl.h>
+\&    main() {
+\&        printf("%#08x\en", FIONREAD);
+\&    }
+\&    ^D
+\&    % cc \-o fionread fionread.c
+\&    % ./fionread
+\&    0x4004667f
+.Ve
+.PP
+And then hard-code it, leaving porting as an exercise to your successor.
+.PP
+.Vb 1
+\&    $FIONREAD = 0x4004667f;         # XXX: opsys dependent
+\&
+\&    $size = pack("L", 0);
+\&    ioctl(FH, $FIONREAD, $size)     or die "Couldn\*(Aqt call ioctl: $!\en";
+\&    $size = unpack("L", $size);
+.Ve
+.PP
+FIONREAD requires a filehandle connected to a stream, meaning that sockets,
+pipes, and tty devices work, but \fInot\fR files.
+.ie n .SS "How do I do a ""tail \-f"" in perl?"
+.el .SS "How do I do a \f(CWtail \-f\fP in perl?"
+.IX Xref "tail IO::Handle File::Tail clearerr"
+.IX Subsection "How do I do a tail -f in perl?"
+First try
+.PP
+.Vb 1
+\&    seek($gw_fh, 0, 1);
+.Ve
+.PP
+The statement \f(CW\*(C`seek($gw_fh, 0, 1)\*(C'\fR doesn't change the current position,
+but it does clear the end-of-file condition on the handle, so that the
+next \f(CW\*(C`<$gw_fh>\*(C'\fR makes Perl try again to read something.
+.PP
+If that doesn't work (it relies on features of your stdio implementation),
+then you need something more like this:
+.PP
+.Vb 7
+\&    for (;;) {
+\&      for ($curpos = tell($gw_fh); <$gw_fh>; $curpos =tell($gw_fh)) {
+\&        # search for some stuff and put it into files
+\&      }
+\&      # sleep for a while
+\&      seek($gw_fh, $curpos, 0);  # seek to where we had been
+\&    }
+.Ve
+.PP
+If this still doesn't work, look into the \f(CW\*(C`clearerr\*(C'\fR method
+from IO::Handle, which resets the error and end-of-file states
+on the handle.
+.PP
+There's also a File::Tail module from CPAN.
+.SS "How do I \fBdup()\fP a filehandle in Perl?"
+.IX Xref "dup"
+.IX Subsection "How do I dup() a filehandle in Perl?"
+If you check "open" in perlfunc, you'll see that several of the ways
+to call \fBopen()\fR should do the trick. For example:
+.PP
+.Vb 2
+\&    open my $log, \*(Aq>>\*(Aq, \*(Aq/foo/logfile\*(Aq;
+\&    open STDERR, \*(Aq>&\*(Aq, $log;
+.Ve
+.PP
+Or even with a literal numeric descriptor:
+.PP
+.Vb 2
+\&    my $fd = $ENV{MHCONTEXTFD};
+\&    open $mhcontext, "<&=$fd";  # like fdopen(3S)
+.Ve
+.PP
+Note that "<&STDIN" makes a copy, but "<&=STDIN" makes
+an alias. That means if you close an aliased handle, all
+aliases become inaccessible. This is not true with
+a copied one.
+.PP
+Error checking, as always, has been left as an exercise for the reader.
+.SS "How do I close a file descriptor by number?"
+.IX Xref "file, closing file descriptors POSIX close"
+.IX Subsection "How do I close a file descriptor by number?"
+If, for some reason, you have a file descriptor instead of a
+filehandle (perhaps you used \f(CW\*(C`POSIX::open\*(C'\fR), you can use the
+\&\f(CWclose()\fR function from the POSIX module:
+.PP
+.Vb 1
+\&    use POSIX ();
+\&
+\&    POSIX::close( $fd );
+.Ve
+.PP
+This should rarely be necessary, as the Perl \f(CWclose()\fR function is to be
+used for things that Perl opened itself, even if it was a dup of a
+numeric descriptor as with \f(CW\*(C`MHCONTEXT\*(C'\fR above. But if you really have
+to, you may be able to do this:
+.PP
+.Vb 3
+\&    require \*(Aq./sys/syscall.ph\*(Aq;
+\&    my $rc = syscall(SYS_close(), $fd + 0);  # must force numeric
+\&    die "can\*(Aqt sysclose $fd: $!" unless $rc == \-1;
+.Ve
+.PP
+Or, just use the fdopen(3S) feature of \f(CWopen()\fR:
+.PP
+.Vb 4
+\&    {
+\&        open my $fh, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
+\&        close $fh;
+\&    }
+.Ve
+.SS "Why can't I use ""C:\etemp\efoo"" in DOS paths? Why doesn't `C:\etemp\efoo.exe` work?"
+.IX Xref "filename, DOS issues"
+.IX Subsection "Why can't I use ""C:tempfoo"" in DOS paths? Why doesn't `C:tempfoo.exe` work?"
+Whoops!  You just put a tab and a formfeed into that filename!
+Remember that within double quoted strings ("like\ethis"), the
+backslash is an escape character. The full list of these is in
+"Quote and Quote-like Operators" in perlop. Unsurprisingly, you don't
+have a file called "c:(tab)emp(formfeed)oo" or
+"c:(tab)emp(formfeed)oo.exe" on your legacy DOS filesystem.
+.PP
+Either single-quote your strings, or (preferably) use forward slashes.
+Since all DOS and Windows versions since something like MS-DOS 2.0 or so
+have treated \f(CW\*(C`/\*(C'\fR and \f(CW\*(C`\e\*(C'\fR the same in a path, you might as well use the
+one that doesn't clash with Perl\-\-or the POSIX shell, ANSI C and C++,
+awk, Tcl, Java, or Python, just to mention a few. POSIX paths
+are more portable, too.
+.SS "Why doesn't glob(""*.*"") get all the files?"
+.IX Xref "glob"
+.IX Subsection "Why doesn't glob(""*.*"") get all the files?"
+Because even on non-Unix ports, Perl's glob function follows standard
+Unix globbing semantics. You'll need \f(CWglob("*")\fR to get all (non-hidden)
+files. This makes \fBglob()\fR portable even to legacy systems. Your
+port may include proprietary globbing functions as well. Check its
+documentation for details.
+.ie n .SS "Why does Perl let me delete read-only files? Why does ""\-i"" clobber protected files? Isn't this a bug in Perl?"
+.el .SS "Why does Perl let me delete read-only files? Why does \f(CW\-i\fP clobber protected files? Isn't this a bug in Perl?"
+.IX Subsection "Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?"
+This is elaborately and painstakingly described in the
+\&\fIfile-dir-perms\fR article in the "Far More Than You Ever Wanted To
+Know" collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> .
+.PP
+The executive summary: learn how your filesystem works. The
+permissions on a file say what can happen to the data in that file.
+The permissions on a directory say what can happen to the list of
+files in that directory. If you delete a file, you're removing its
+name from the directory (so the operation depends on the permissions
+of the directory, not of the file). If you try to write to the file,
+the permissions of the file govern whether you're allowed to.
+.SS "How do I select a random line from a file?"
+.IX Xref "file, selecting a random line"
+.IX Subsection "How do I select a random line from a file?"
+Short of loading the file into a database or pre-indexing the lines in
+the file, there are a couple of things that you can do.
+.PP
+Here's a reservoir-sampling algorithm from the Camel Book:
+.PP
+.Vb 2
+\&    srand;
+\&    rand($.) < 1 && ($line = $_) while <>;
+.Ve
+.PP
+This has a significant advantage in space over reading the whole file
+in. You can find a proof of this method in \fIThe Art of Computer
+Programming\fR, Volume 2, Section 3.4.2, by Donald E. Knuth.
+.PP
+You can use the File::Random module which provides a function
+for that algorithm:
+.PP
+.Vb 2
+\&    use File::Random qw/random_line/;
+\&    my $line = random_line($filename);
+.Ve
+.PP
+Another way is to use the Tie::File module, which treats the entire
+file as an array. Simply access a random array element.
+.SS "Why do I get weird spaces when I print an array of lines?"
+.IX Subsection "Why do I get weird spaces when I print an array of lines?"
+(contributed by brian d foy)
+.PP
+If you are seeing spaces between the elements of your array when
+you print the array, you are probably interpolating the array in
+double quotes:
+.PP
+.Vb 2
+\&    my @animals = qw(camel llama alpaca vicuna);
+\&    print "animals are: @animals\en";
+.Ve
+.PP
+It's the double quotes, not the \f(CW\*(C`print\*(C'\fR, doing this. Whenever you
+interpolate an array in a double quote context, Perl joins the
+elements with spaces (or whatever is in \f(CW$"\fR, which is a space by
+default):
+.PP
+.Vb 1
+\&    animals are: camel llama alpaca vicuna
+.Ve
+.PP
+This is different than printing the array without the interpolation:
+.PP
+.Vb 2
+\&    my @animals = qw(camel llama alpaca vicuna);
+\&    print "animals are: ", @animals, "\en";
+.Ve
+.PP
+Now the output doesn't have the spaces between the elements because
+the elements of \f(CW@animals\fR simply become part of the list to
+\&\f(CW\*(C`print\*(C'\fR:
+.PP
+.Vb 1
+\&    animals are: camelllamaalpacavicuna
+.Ve
+.PP
+You might notice this when each of the elements of \f(CW@array\fR end with
+a newline. You expect to print one element per line, but notice that
+every line after the first is indented:
+.PP
+.Vb 3
+\&    this is a line
+\&     this is another line
+\&     this is the third line
+.Ve
+.PP
+That extra space comes from the interpolation of the array. If you
+don't want to put anything between your array elements, don't use the
+array in double quotes. You can send it to print without them:
+.PP
+.Vb 1
+\&    print @lines;
+.Ve
+.SS "How do I traverse a directory tree?"
+.IX Subsection "How do I traverse a directory tree?"
+(contributed by brian d foy)
+.PP
+The File::Find module, which comes with Perl, does all of the hard
+work to traverse a directory structure. It comes with Perl. You simply
+call the \f(CW\*(C`find\*(C'\fR subroutine with a callback subroutine and the
+directories you want to traverse:
+.PP
+.Vb 1
+\&    use File::Find;
+\&
+\&    find( \e&wanted, @directories );
+\&
+\&    sub wanted {
+\&        # full path in $File::Find::name
+\&        # just filename in $_
+\&        ... do whatever you want to do ...
+\&    }
+.Ve
+.PP
+The File::Find::Closures, which you can download from CPAN, provides
+many ready-to-use subroutines that you can use with File::Find.
+.PP
+The File::Finder, which you can download from CPAN, can help you
+create the callback subroutine using something closer to the syntax of
+the \f(CW\*(C`find\*(C'\fR command-line utility:
+.PP
+.Vb 2
+\&    use File::Find;
+\&    use File::Finder;
+\&
+\&    my $deep_dirs = File::Finder\->depth\->type(\*(Aqd\*(Aq)\->ls\->exec(\*(Aqrmdir\*(Aq,\*(Aq{}\*(Aq);
+\&
+\&    find( $deep_dirs\->as_options, @places );
+.Ve
+.PP
+The File::Find::Rule module, which you can download from CPAN, has
+a similar interface, but does the traversal for you too:
+.PP
+.Vb 1
+\&    use File::Find::Rule;
+\&
+\&    my @files = File::Find::Rule\->file()
+\&                             \->name( \*(Aq*.pm\*(Aq )
+\&                             \->in( @INC );
+.Ve
+.SS "How do I delete a directory tree?"
+.IX Subsection "How do I delete a directory tree?"
+(contributed by brian d foy)
+.PP
+If you have an empty directory, you can use Perl's built-in \f(CW\*(C`rmdir\*(C'\fR.
+If the directory is not empty (so, with files or subdirectories), you
+either have to empty it yourself (a lot of work) or use a module to
+help you.
+.PP
+The File::Path module, which comes with Perl, has a \f(CW\*(C`remove_tree\*(C'\fR
+which can take care of all of the hard work for you:
+.PP
+.Vb 1
+\&    use File::Path qw(remove_tree);
+\&
+\&    remove_tree( @directories );
+.Ve
+.PP
+The File::Path module also has a legacy interface to the older
+\&\f(CW\*(C`rmtree\*(C'\fR subroutine.
+.SS "How do I copy an entire directory?"
+.IX Subsection "How do I copy an entire directory?"
+(contributed by Shlomi Fish)
+.PP
+To do the equivalent of \f(CW\*(C`cp \-R\*(C'\fR (i.e. copy an entire directory tree
+recursively) in portable Perl, you'll either need to write something yourself
+or find a good CPAN module such as  File::Copy::Recursive.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples here are in the public
+domain. You are permitted and encouraged to use this code and any
+derivatives thereof in your own programs for fun or for profit as you
+see fit. A simple comment in the code giving credit to the FAQ would
+be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq6.1 b/upstream/mageia-cauldron/man1/perlfaq6.1
new file mode 100644
index 00000000..64311d6d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq6.1
@@ -0,0 +1,1270 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ6 1"
+.TH PERLFAQ6 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq6 \- Regular Expressions
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section is surprisingly small because the rest of the FAQ is
+littered with answers involving regular expressions. For example,
+decoding a URL and checking whether something is a number can be handled
+with regular expressions, but those answers are found elsewhere in
+this document (in perlfaq9: "How do I decode or create those %\-encodings
+on the web" and perlfaq4: "How do I determine whether a scalar is
+a number/whole/integer/float", to be precise).
+.SS "How can I hope to use regular expressions without creating illegible and unmaintainable code?"
+.IX Xref "regex, legibility regexp, legibility regular expression, legibility x"
+.IX Subsection "How can I hope to use regular expressions without creating illegible and unmaintainable code?"
+Three techniques can make regular expressions maintainable and
+understandable.
+.IP "Comments Outside the Regex" 4
+.IX Item "Comments Outside the Regex"
+Describe what you're doing and how you're doing it, using normal Perl
+comments.
+.Sp
+.Vb 3
+\&    # turn the line into the first word, a colon, and the
+\&    # number of characters on the rest of the line
+\&    s/^(\ew+)(.*)/ lc($1) . ":" . length($2) /meg;
+.Ve
+.IP "Comments Inside the Regex" 4
+.IX Item "Comments Inside the Regex"
+The \f(CW\*(C`/x\*(C'\fR modifier causes whitespace to be ignored in a regex pattern
+(except in a character class and a few other places), and also allows you to
+use normal comments there, too. As you can imagine, whitespace and comments
+help a lot.
+.Sp
+\&\f(CW\*(C`/x\*(C'\fR lets you turn this:
+.Sp
+.Vb 1
+\&    s{<(?:[^>\*(Aq"]*|".*?"|\*(Aq.*?\*(Aq)+>}{}gs;
+.Ve
+.Sp
+into this:
+.Sp
+.Vb 10
+\&    s{ <                    # opening angle bracket
+\&        (?:                 # Non\-backreffing grouping paren
+\&            [^>\*(Aq"] *        # 0 or more things that are neither > nor \*(Aq nor "
+\&                |           #    or else
+\&            ".*?"           # a section between double quotes (stingy match)
+\&                |           #    or else
+\&            \*(Aq.*?\*(Aq           # a section between single quotes (stingy match)
+\&        ) +                 #   all occurring one or more times
+\&        >                   # closing angle bracket
+\&    }{}gsx;                 # replace with nothing, i.e. delete
+.Ve
+.Sp
+It's still not quite so clear as prose, but it is very useful for
+describing the meaning of each part of the pattern.
+.IP "Different Delimiters" 4
+.IX Item "Different Delimiters"
+While we normally think of patterns as being delimited with \f(CW\*(C`/\*(C'\fR
+characters, they can be delimited by almost any character. perlre
+describes this. For example, the \f(CW\*(C`s///\*(C'\fR above uses braces as
+delimiters. Selecting another delimiter can avoid quoting the
+delimiter within the pattern:
+.Sp
+.Vb 2
+\&    s/\e/usr\e/local/\e/usr\e/share/g;    # bad delimiter choice
+\&    s#/usr/local#/usr/share#g;        # better
+.Ve
+.Sp
+Using logically paired delimiters can be even more readable:
+.Sp
+.Vb 1
+\&    s{/usr/local/}{/usr/share}g;      # better still
+.Ve
+.SS "I'm having trouble matching over more than one line. What's wrong?"
+.IX Xref "regex, multiline regexp, multiline regular expression, multiline"
+.IX Subsection "I'm having trouble matching over more than one line. What's wrong?"
+Either you don't have more than one line in the string you're looking
+at (probably), or else you aren't using the correct modifier(s) on
+your pattern (possibly).
+.PP
+There are many ways to get multiline data into a string. If you want
+it to happen automatically while reading input, you'll want to set $/
+(probably to '' for paragraphs or \f(CW\*(C`undef\*(C'\fR for the whole file) to
+allow you to read more than one line at a time.
+.PP
+Read perlre to help you decide which of \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR (or both)
+you might want to use: \f(CW\*(C`/s\*(C'\fR allows dot to include newline, and \f(CW\*(C`/m\*(C'\fR
+allows caret and dollar to match next to a newline, not just at the
+end of the string. You do need to make sure that you've actually
+got a multiline string in there.
+.PP
+For example, this program detects duplicate words, even when they span
+line breaks (but not paragraph ones). For this example, we don't need
+\&\f(CW\*(C`/s\*(C'\fR because we aren't using dot in a regular expression that we want
+to cross line boundaries. Neither do we need \f(CW\*(C`/m\*(C'\fR because we don't
+want caret or dollar to match at any point inside the record next
+to newlines. But it's imperative that $/ be set to something other
+than the default, or else we won't actually ever have a multiline
+record read in.
+.PP
+.Vb 6
+\&    $/ = \*(Aq\*(Aq;          # read in whole paragraph, not just one line
+\&    while ( <> ) {
+\&        while ( /\eb([\ew\*(Aq\-]+)(\es+\eg1)+\eb/gi ) {     # word starts alpha
+\&            print "Duplicate $1 at paragraph $.\en";
+\&        }
+\&    }
+.Ve
+.PP
+Here's some code that finds sentences that begin with "From " (which would
+be mangled by many mailers):
+.PP
+.Vb 6
+\&    $/ = \*(Aq\*(Aq;          # read in whole paragraph, not just one line
+\&    while ( <> ) {
+\&        while ( /^From /gm ) { # /m makes ^ match next to \en
+\&        print "leading From in paragraph $.\en";
+\&        }
+\&    }
+.Ve
+.PP
+Here's code that finds everything between START and END in a paragraph:
+.PP
+.Vb 6
+\&    undef $/;          # read in whole file, not just one line or paragraph
+\&    while ( <> ) {
+\&        while ( /START(.*?)END/sgm ) { # /s makes . cross line boundaries
+\&            print "$1\en";
+\&        }
+\&    }
+.Ve
+.SS "How can I pull out lines between two patterns that are themselves on different lines?"
+.IX Xref ".."
+.IX Subsection "How can I pull out lines between two patterns that are themselves on different lines?"
+You can use Perl's somewhat exotic \f(CW\*(C`..\*(C'\fR operator (documented in
+perlop):
+.PP
+.Vb 1
+\&    perl \-ne \*(Aqprint if /START/ .. /END/\*(Aq file1 file2 ...
+.Ve
+.PP
+If you wanted text and not lines, you would use
+.PP
+.Vb 1
+\&    perl \-0777 \-ne \*(Aqprint "$1\en" while /START(.*?)END/gs\*(Aq file1 file2 ...
+.Ve
+.PP
+But if you want nested occurrences of \f(CW\*(C`START\*(C'\fR through \f(CW\*(C`END\*(C'\fR, you'll
+run up against the problem described in the question in this section
+on matching balanced text.
+.PP
+Here's another example of using \f(CW\*(C`..\*(C'\fR:
+.PP
+.Vb 7
+\&    while (<>) {
+\&        my $in_header =   1  .. /^$/;
+\&        my $in_body   = /^$/ .. eof;
+\&    # now choose between them
+\&    } continue {
+\&        $. = 0 if eof;    # fix $.
+\&    }
+.Ve
+.SS "How do I match XML, HTML, or other nasty, ugly things with a regex?"
+.IX Xref "regex, XML regex, HTML XML HTML pain frustration sucking out, will to live"
+.IX Subsection "How do I match XML, HTML, or other nasty, ugly things with a regex?"
+Do not use regexes. Use a module and forget about the
+regular expressions. The XML::LibXML, HTML::TokeParser and
+HTML::TreeBuilder modules are good starts, although each namespace
+has other parsing modules specialized for certain tasks and different
+ways of doing it. Start at CPAN Search ( <http://metacpan.org/> )
+and wonder at all the work people have done for you already! :)
+.SS "I put a regular expression into $/ but it didn't work. What's wrong?"
+.IX Xref "$ , regexes in $INPUT_RECORD_SEPARATOR, regexes in $RS, regexes in"
+.IX Subsection "I put a regular expression into $/ but it didn't work. What's wrong?"
+$/ has to be a string. You can use these examples if you really need to
+do this.
+.PP
+If you have File::Stream, this is easy.
+.PP
+.Vb 1
+\&    use File::Stream;
+\&
+\&    my $stream = File::Stream\->new(
+\&        $filehandle,
+\&        separator => qr/\es*,\es*/,
+\&        );
+\&
+\&    print "$_\en" while <$stream>;
+.Ve
+.PP
+If you don't have File::Stream, you have to do a little more work.
+.PP
+You can use the four-argument form of sysread to continually add to
+a buffer. After you add to the buffer, you check if you have a
+complete line (using your regular expression).
+.PP
+.Vb 7
+\&    local $_ = "";
+\&    while( sysread FH, $_, 8192, length ) {
+\&        while( s/^((?s).*?)your_pattern// ) {
+\&            my $record = $1;
+\&            # do stuff here.
+\&        }
+\&    }
+.Ve
+.PP
+You can do the same thing with foreach and a match using the
+c flag and the \eG anchor, if you do not mind your entire file
+being in memory at the end.
+.PP
+.Vb 7
+\&    local $_ = "";
+\&    while( sysread FH, $_, 8192, length ) {
+\&        foreach my $record ( m/\eG((?s).*?)your_pattern/gc ) {
+\&            # do stuff here.
+\&        }
+\&        substr( $_, 0, pos ) = "" if pos;
+\&    }
+.Ve
+.SS "How do I substitute case-insensitively on the LHS while preserving case on the RHS?"
+.IX Xref "replace, case preserving substitute, case preserving substitution, case preserving s, case preserving"
+.IX Subsection "How do I substitute case-insensitively on the LHS while preserving case on the RHS?"
+Here's a lovely Perlish solution by Larry Rosler. It exploits
+properties of bitwise xor on ASCII strings.
+.PP
+.Vb 1
+\&    $_= "this is a TEsT case";
+\&
+\&    $old = \*(Aqtest\*(Aq;
+\&    $new = \*(Aqsuccess\*(Aq;
+\&
+\&    s{(\eQ$old\eE)}
+\&    { uc $new | (uc $1 ^ $1) .
+\&        (uc(substr $1, \-1) ^ substr $1, \-1) x
+\&        (length($new) \- length $1)
+\&    }egi;
+\&
+\&    print;
+.Ve
+.PP
+And here it is as a subroutine, modeled after the above:
+.PP
+.Vb 3
+\&    sub preserve_case {
+\&        my ($old, $new) = @_;
+\&        my $mask = uc $old ^ $old;
+\&
+\&        uc $new | $mask .
+\&            substr($mask, \-1) x (length($new) \- length($old))
+\&    }
+\&
+\&    $string = "this is a TEsT case";
+\&    $string =~ s/(test)/preserve_case($1, "success")/egi;
+\&    print "$string\en";
+.Ve
+.PP
+This prints:
+.PP
+.Vb 1
+\&    this is a SUcCESS case
+.Ve
+.PP
+As an alternative, to keep the case of the replacement word if it is
+longer than the original, you can use this code, by Jeff Pinyan:
+.PP
+.Vb 3
+\&    sub preserve_case {
+\&        my ($from, $to) = @_;
+\&        my ($lf, $lt) = map length, @_;
+\&
+\&        if ($lt < $lf) { $from = substr $from, 0, $lt }
+\&        else { $from .= substr $to, $lf }
+\&
+\&        return uc $to | ($from ^ uc $from);
+\&    }
+.Ve
+.PP
+This changes the sentence to "this is a SUcCess case."
+.PP
+Just to show that C programmers can write C in any programming language,
+if you prefer a more C\-like solution, the following script makes the
+substitution have the same case, letter by letter, as the original.
+(It also happens to run about 240% slower than the Perlish solution runs.)
+If the substitution has more characters than the string being substituted,
+the case of the last character is used for the rest of the substitution.
+.PP
+.Vb 8
+\&    # Original by Nathan Torkington, massaged by Jeffrey Friedl
+\&    #
+\&    sub preserve_case
+\&    {
+\&        my ($old, $new) = @_;
+\&        my $state = 0; # 0 = no change; 1 = lc; 2 = uc
+\&        my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new));
+\&        my $len = $oldlen < $newlen ? $oldlen : $newlen;
+\&
+\&        for ($i = 0; $i < $len; $i++) {
+\&            if ($c = substr($old, $i, 1), $c =~ /[\eW\ed_]/) {
+\&                $state = 0;
+\&            } elsif (lc $c eq $c) {
+\&                substr($new, $i, 1) = lc(substr($new, $i, 1));
+\&                $state = 1;
+\&            } else {
+\&                substr($new, $i, 1) = uc(substr($new, $i, 1));
+\&                $state = 2;
+\&            }
+\&        }
+\&        # finish up with any remaining new (for when new is longer than old)
+\&        if ($newlen > $oldlen) {
+\&            if ($state == 1) {
+\&                substr($new, $oldlen) = lc(substr($new, $oldlen));
+\&            } elsif ($state == 2) {
+\&                substr($new, $oldlen) = uc(substr($new, $oldlen));
+\&            }
+\&        }
+\&        return $new;
+\&    }
+.Ve
+.ie n .SS "How can I make ""\ew"" match national character sets?"
+.el .SS "How can I make \f(CW\ew\fP match national character sets?"
+.IX Xref "\\w"
+.IX Subsection "How can I make w match national character sets?"
+Put \f(CW\*(C`use locale;\*(C'\fR in your script. The \ew character class is taken
+from the current locale.
+.PP
+See perllocale for details.
+.ie n .SS "How can I match a locale-smart version of ""/[a\-zA\-Z]/""?"
+.el .SS "How can I match a locale-smart version of \f(CW/[a\-zA\-Z]/\fP?"
+.IX Xref "alpha"
+.IX Subsection "How can I match a locale-smart version of /[a-zA-Z]/?"
+You can use the POSIX character class syntax \f(CW\*(C`/[[:alpha:]]/\*(C'\fR
+documented in perlre.
+.PP
+No matter which locale you are in, the alphabetic characters are
+the characters in \ew without the digits and the underscore.
+As a regex, that looks like \f(CW\*(C`/[^\eW\ed_]/\*(C'\fR. Its complement,
+the non-alphabetics, is then everything in \eW along with
+the digits and the underscore, or \f(CW\*(C`/[\eW\ed_]/\*(C'\fR.
+.SS "How can I quote a variable to use in a regex?"
+.IX Xref "regex, escaping regexp, escaping regular expression, escaping"
+.IX Subsection "How can I quote a variable to use in a regex?"
+The Perl parser will expand \f(CW$variable\fR and \f(CW@variable\fR references in
+regular expressions unless the delimiter is a single quote. Remember,
+too, that the right-hand side of a \f(CW\*(C`s///\*(C'\fR substitution is considered
+a double-quoted string (see perlop for more details). Remember
+also that any regex special characters will be acted on unless you
+precede the substitution with \eQ. Here's an example:
+.PP
+.Vb 2
+\&    $string = "Placido P. Octopus";
+\&    $regex  = "P.";
+\&
+\&    $string =~ s/$regex/Polyp/;
+\&    # $string is now "Polypacido P. Octopus"
+.Ve
+.PP
+Because \f(CW\*(C`.\*(C'\fR is special in regular expressions, and can match any
+single character, the regex \f(CW\*(C`P.\*(C'\fR here has matched the <Pl> in the
+original string.
+.PP
+To escape the special meaning of \f(CW\*(C`.\*(C'\fR, we use \f(CW\*(C`\eQ\*(C'\fR:
+.PP
+.Vb 2
+\&    $string = "Placido P. Octopus";
+\&    $regex  = "P.";
+\&
+\&    $string =~ s/\eQ$regex/Polyp/;
+\&    # $string is now "Placido Polyp Octopus"
+.Ve
+.PP
+The use of \f(CW\*(C`\eQ\*(C'\fR causes the \f(CW\*(C`.\*(C'\fR in the regex to be treated as a
+regular character, so that \f(CW\*(C`P.\*(C'\fR matches a \f(CW\*(C`P\*(C'\fR followed by a dot.
+.ie n .SS "What is ""/o"" really for?"
+.el .SS "What is \f(CW/o\fP really for?"
+.IX Xref " o, regular expressions compile, regular expressions"
+.IX Subsection "What is /o really for?"
+(contributed by brian d foy)
+.PP
+The \f(CW\*(C`/o\*(C'\fR option for regular expressions (documented in perlop and
+perlreref) tells Perl to compile the regular expression only once.
+This is only useful when the pattern contains a variable. Perls 5.6
+and later handle this automatically if the pattern does not change.
+.PP
+Since the match operator \f(CW\*(C`m//\*(C'\fR, the substitution operator \f(CW\*(C`s///\*(C'\fR,
+and the regular expression quoting operator \f(CW\*(C`qr//\*(C'\fR are double-quotish
+constructs, you can interpolate variables into the pattern. See the
+answer to "How can I quote a variable to use in a regex?" for more
+details.
+.PP
+This example takes a regular expression from the argument list and
+prints the lines of input that match it:
+.PP
+.Vb 1
+\&    my $pattern = shift @ARGV;
+\&
+\&    while( <> ) {
+\&        print if m/$pattern/;
+\&    }
+.Ve
+.PP
+Versions of Perl prior to 5.6 would recompile the regular expression
+for each iteration, even if \f(CW$pattern\fR had not changed. The \f(CW\*(C`/o\*(C'\fR
+would prevent this by telling Perl to compile the pattern the first
+time, then reuse that for subsequent iterations:
+.PP
+.Vb 1
+\&    my $pattern = shift @ARGV;
+\&
+\&    while( <> ) {
+\&        print if m/$pattern/o; # useful for Perl < 5.6
+\&    }
+.Ve
+.PP
+In versions 5.6 and later, Perl won't recompile the regular expression
+if the variable hasn't changed, so you probably don't need the \f(CW\*(C`/o\*(C'\fR
+option. It doesn't hurt, but it doesn't help either. If you want any
+version of Perl to compile the regular expression only once even if
+the variable changes (thus, only using its initial value), you still
+need the \f(CW\*(C`/o\*(C'\fR.
+.PP
+You can watch Perl's regular expression engine at work to verify for
+yourself if Perl is recompiling a regular expression. The \f(CWuse re
+\&\*(Aqdebug\*(Aq\fR pragma (comes with Perl 5.005 and later) shows the details.
+With Perls before 5.6, you should see \f(CW\*(C`re\*(C'\fR reporting that its
+compiling the regular expression on each iteration. With Perl 5.6 or
+later, you should only see \f(CW\*(C`re\*(C'\fR report that for the first iteration.
+.PP
+.Vb 1
+\&    use re \*(Aqdebug\*(Aq;
+\&
+\&    my $regex = \*(AqPerl\*(Aq;
+\&    foreach ( qw(Perl Java Ruby Python) ) {
+\&        print STDERR "\-" x 73, "\en";
+\&        print STDERR "Trying $_...\en";
+\&        print STDERR "\et$_ is good!\en" if m/$regex/;
+\&    }
+.Ve
+.SS "How do I use a regular expression to strip C\-style comments from a file?"
+.IX Subsection "How do I use a regular expression to strip C-style comments from a file?"
+While this actually can be done, it's much harder than you'd think.
+For example, this one-liner
+.PP
+.Vb 1
+\&    perl \-0777 \-pe \*(Aqs{/\e*.*?\e*/}{}gs\*(Aq foo.c
+.Ve
+.PP
+will work in many but not all cases. You see, it's too simple-minded for
+certain kinds of C programs, in particular, those with what appear to be
+comments in quoted strings. For that, you'd need something like this,
+created by Jeffrey Friedl and later modified by Fred Curtis.
+.PP
+.Vb 4
+\&    $/ = undef;
+\&    $_ = <>;
+\&    s#/\e*[^*]*\e*+([^/*][^*]*\e*+)*/|("(\e\e.|[^"\e\e])*"|\*(Aq(\e\e.|[^\*(Aq\e\e])*\*(Aq|.[^/"\*(Aq\e\e]*)#defined $2 ? $2 : ""#gse;
+\&    print;
+.Ve
+.PP
+This could, of course, be more legibly written with the \f(CW\*(C`/x\*(C'\fR modifier, adding
+whitespace and comments. Here it is expanded, courtesy of Fred Curtis.
+.PP
+.Vb 8
+\&    s{
+\&       /\e*         ##  Start of /* ... */ comment
+\&       [^*]*\e*+    ##  Non\-* followed by 1\-or\-more *\*(Aqs
+\&       (
+\&         [^/*][^*]*\e*+
+\&       )*          ##  0\-or\-more things which don\*(Aqt start with /
+\&                   ##    but do end with \*(Aq*\*(Aq
+\&       /           ##  End of /* ... */ comment
+\&
+\&     |         ##     OR  various things which aren\*(Aqt comments:
+\&
+\&       (
+\&         "           ##  Start of " ... " string
+\&         (
+\&           \e\e.           ##  Escaped char
+\&         |               ##    OR
+\&           [^"\e\e]        ##  Non "\e
+\&         )*
+\&         "           ##  End of " ... " string
+\&
+\&       |         ##     OR
+\&
+\&         \*(Aq           ##  Start of \*(Aq ... \*(Aq string
+\&         (
+\&           \e\e.           ##  Escaped char
+\&         |               ##    OR
+\&           [^\*(Aq\e\e]        ##  Non \*(Aq\e
+\&         )*
+\&         \*(Aq           ##  End of \*(Aq ... \*(Aq string
+\&
+\&       |         ##     OR
+\&
+\&         .           ##  Anything other char
+\&         [^/"\*(Aq\e\e]*   ##  Chars which doesn\*(Aqt start a comment, string or escape
+\&       )
+\&     }{defined $2 ? $2 : ""}gxse;
+.Ve
+.PP
+A slight modification also removes C++ comments, possibly spanning multiple lines
+using a continuation character:
+.PP
+.Vb 1
+\& s#/\e*[^*]*\e*+([^/*][^*]*\e*+)*/|//([^\e\e]|[^\en][\en]?)*?\en|("(\e\e.|[^"\e\e])*"|\*(Aq(\e\e.|[^\*(Aq\e\e])*\*(Aq|.[^/"\*(Aq\e\e]*)#defined $3 ? $3 : ""#gse;
+.Ve
+.SS "Can I use Perl regular expressions to match balanced text?"
+.IX Xref "regex, matching balanced test regexp, matching balanced test regular expression, matching balanced test possessive PARNO Text::Balanced Regexp::Common backtracking recursion"
+.IX Subsection "Can I use Perl regular expressions to match balanced text?"
+(contributed by brian d foy)
+.PP
+Your first try should probably be the Text::Balanced module, which
+is in the Perl standard library since Perl 5.8. It has a variety of
+functions to deal with tricky text. The Regexp::Common module can
+also help by providing canned patterns you can use.
+.PP
+As of Perl 5.10, you can match balanced text with regular expressions
+using recursive patterns. Before Perl 5.10, you had to resort to
+various tricks such as using Perl code in \f(CW\*(C`(??{})\*(C'\fR sequences.
+.PP
+Here's an example using a recursive regular expression. The goal is to
+capture all of the text within angle brackets, including the text in
+nested angle brackets. This sample text has two "major" groups: a
+group with one level of nesting and a group with two levels of
+nesting. There are five total groups in angle brackets:
+.PP
+.Vb 3
+\&    I have some <brackets in <nested brackets> > and
+\&    <another group <nested once <nested twice> > >
+\&    and that\*(Aqs it.
+.Ve
+.PP
+The regular expression to match the balanced text uses two new (to
+Perl 5.10) regular expression features. These are covered in perlre
+and this example is a modified version of one in that documentation.
+.PP
+First, adding the new possessive \f(CW\*(C`+\*(C'\fR to any quantifier finds the
+longest match and does not backtrack. That's important since you want
+to handle any angle brackets through the recursion, not backtracking.
+The group \f(CW\*(C`[^<>]++\*(C'\fR finds one or more non-angle brackets without
+backtracking.
+.PP
+Second, the new \f(CW\*(C`(?PARNO)\*(C'\fR refers to the sub-pattern in the
+particular capture group given by \f(CW\*(C`PARNO\*(C'\fR. In the following regex,
+the first capture group finds (and remembers) the balanced text, and
+you need that same pattern within the first buffer to get past the
+nested text. That's the recursive part. The \f(CW\*(C`(?1)\*(C'\fR uses the pattern
+in the outer capture group as an independent part of the regex.
+.PP
+Putting it all together, you have:
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl5.10.0
+\&
+\&    my $string =<<"HERE";
+\&    I have some <brackets in <nested brackets> > and
+\&    <another group <nested once <nested twice> > >
+\&    and that\*(Aqs it.
+\&    HERE
+\&
+\&    my @groups = $string =~ m/
+\&            (                   # start of capture group 1
+\&            <                   # match an opening angle bracket
+\&                (?:
+\&                    [^<>]++     # one or more non angle brackets, non backtracking
+\&                      |
+\&                    (?1)        # found < or >, so recurse to capture group 1
+\&                )*
+\&            >                   # match a closing angle bracket
+\&            )                   # end of capture group 1
+\&            /xg;
+\&
+\&    $" = "\en\et";
+\&    print "Found:\en\et@groups\en";
+.Ve
+.PP
+The output shows that Perl found the two major groups:
+.PP
+.Vb 3
+\&    Found:
+\&        <brackets in <nested brackets> >
+\&        <another group <nested once <nested twice> > >
+.Ve
+.PP
+With a little extra work, you can get all of the groups in angle
+brackets even if they are in other angle brackets too. Each time you
+get a balanced match, remove its outer delimiter (that's the one you
+just matched so don't match it again) and add it to a queue of strings
+to process. Keep doing that until you get no matches:
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl5.10.0
+\&
+\&    my @queue =<<"HERE";
+\&    I have some <brackets in <nested brackets> > and
+\&    <another group <nested once <nested twice> > >
+\&    and that\*(Aqs it.
+\&    HERE
+\&
+\&    my $regex = qr/
+\&            (                   # start of bracket 1
+\&            <                   # match an opening angle bracket
+\&                (?:
+\&                    [^<>]++     # one or more non angle brackets, non backtracking
+\&                      |
+\&                    (?1)        # recurse to bracket 1
+\&                )*
+\&            >                   # match a closing angle bracket
+\&            )                   # end of bracket 1
+\&            /x;
+\&
+\&    $" = "\en\et";
+\&
+\&    while( @queue ) {
+\&        my $string = shift @queue;
+\&
+\&        my @groups = $string =~ m/$regex/g;
+\&        print "Found:\en\et@groups\en\en" if @groups;
+\&
+\&        unshift @queue, map { s/^<//; s/>$//; $_ } @groups;
+\&    }
+.Ve
+.PP
+The output shows all of the groups. The outermost matches show up
+first and the nested matches show up later:
+.PP
+.Vb 3
+\&    Found:
+\&        <brackets in <nested brackets> >
+\&        <another group <nested once <nested twice> > >
+\&
+\&    Found:
+\&        <nested brackets>
+\&
+\&    Found:
+\&        <nested once <nested twice> >
+\&
+\&    Found:
+\&        <nested twice>
+.Ve
+.SS "What does it mean that regexes are greedy? How can I get around it?"
+.IX Xref "greedy greediness"
+.IX Subsection "What does it mean that regexes are greedy? How can I get around it?"
+Most people mean that greedy regexes match as much as they can.
+Technically speaking, it's actually the quantifiers (\f(CW\*(C`?\*(C'\fR, \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`+\*(C'\fR,
+\&\f(CW\*(C`{}\*(C'\fR) that are greedy rather than the whole pattern; Perl prefers local
+greed and immediate gratification to overall greed. To get non-greedy
+versions of the same quantifiers, use (\f(CW\*(C`??\*(C'\fR, \f(CW\*(C`*?\*(C'\fR, \f(CW\*(C`+?\*(C'\fR, \f(CW\*(C`{}?\*(C'\fR).
+.PP
+An example:
+.PP
+.Vb 3
+\&    my $s1 = my $s2 = "I am very very cold";
+\&    $s1 =~ s/ve.*y //;      # I am cold
+\&    $s2 =~ s/ve.*?y //;     # I am very cold
+.Ve
+.PP
+Notice how the second substitution stopped matching as soon as it
+encountered "y ". The \f(CW\*(C`*?\*(C'\fR quantifier effectively tells the regular
+expression engine to find a match as quickly as possible and pass
+control on to whatever is next in line, as you would if you were
+playing hot potato.
+.SS "How do I process each word on each line?"
+.IX Xref "word"
+.IX Subsection "How do I process each word on each line?"
+Use the split function:
+.PP
+.Vb 5
+\&    while (<>) {
+\&        foreach my $word ( split ) {
+\&            # do something with $word here
+\&        }
+\&    }
+.Ve
+.PP
+Note that this isn't really a word in the English sense; it's just
+chunks of consecutive non-whitespace characters.
+.PP
+To work with only alphanumeric sequences (including underscores), you
+might consider
+.PP
+.Vb 5
+\&    while (<>) {
+\&        foreach $word (m/(\ew+)/g) {
+\&            # do something with $word here
+\&        }
+\&    }
+.Ve
+.SS "How can I print out a word-frequency or line-frequency summary?"
+.IX Subsection "How can I print out a word-frequency or line-frequency summary?"
+To do this, you have to parse out each word in the input stream. We'll
+pretend that by word you mean chunk of alphabetics, hyphens, or
+apostrophes, rather than the non-whitespace chunk idea of a word given
+in the previous question:
+.PP
+.Vb 6
+\&    my (%seen);
+\&    while (<>) {
+\&        while ( /(\eb[^\eW_\ed][\ew\*(Aq\-]+\eb)/g ) {   # misses "\`sheep\*(Aq"
+\&            $seen{$1}++;
+\&        }
+\&    }
+\&
+\&    while ( my ($word, $count) = each %seen ) {
+\&        print "$count $word\en";
+\&    }
+.Ve
+.PP
+If you wanted to do the same thing for lines, you wouldn't need a
+regular expression:
+.PP
+.Vb 1
+\&    my (%seen);
+\&
+\&    while (<>) {
+\&        $seen{$_}++;
+\&    }
+\&
+\&    while ( my ($line, $count) = each %seen ) {
+\&        print "$count $line";
+\&    }
+.Ve
+.PP
+If you want these output in a sorted order, see perlfaq4: "How do I
+sort a hash (optionally by value instead of key)?".
+.SS "How can I do approximate matching?"
+.IX Xref "match, approximate matching, approximate"
+.IX Subsection "How can I do approximate matching?"
+See the module String::Approx available from CPAN.
+.SS "How do I efficiently match many regular expressions at once?"
+.IX Xref "regex, efficiency regexp, efficiency regular expression, efficiency"
+.IX Subsection "How do I efficiently match many regular expressions at once?"
+(contributed by brian d foy)
+.PP
+You want to
+avoid compiling a regular expression every time you want to match it.
+In this example, perl must recompile the regular expression for every
+iteration of the \f(CW\*(C`foreach\*(C'\fR loop since \f(CW$pattern\fR can change:
+.PP
+.Vb 1
+\&    my @patterns = qw( fo+ ba[rz] );
+\&
+\&    LINE: while( my $line = <> ) {
+\&        foreach my $pattern ( @patterns ) {
+\&            if( $line =~ m/\eb$pattern\eb/i ) {
+\&                print $line;
+\&                next LINE;
+\&            }
+\&        }
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`qr//\*(C'\fR operator compiles a regular
+expression, but doesn't apply it. When you use the pre-compiled
+version of the regex, perl does less work. In this example, I inserted
+a \f(CW\*(C`map\*(C'\fR to turn each pattern into its pre-compiled form. The rest of
+the script is the same, but faster:
+.PP
+.Vb 1
+\&    my @patterns = map { qr/\eb$_\eb/i } qw( fo+ ba[rz] );
+\&
+\&    LINE: while( my $line = <> ) {
+\&        foreach my $pattern ( @patterns ) {
+\&            if( $line =~ m/$pattern/ ) {
+\&                print $line;
+\&                next LINE;
+\&            }
+\&        }
+\&    }
+.Ve
+.PP
+In some cases, you may be able to make several patterns into a single
+regular expression. Beware of situations that require backtracking
+though. In this example, the regex is only compiled once because
+\&\f(CW$regex\fR doesn't change between iterations:
+.PP
+.Vb 1
+\&    my $regex = join \*(Aq|\*(Aq, qw( fo+ ba[rz] );
+\&
+\&    while( my $line = <> ) {
+\&        print if $line =~ m/\eb(?:$regex)\eb/i;
+\&    }
+.Ve
+.PP
+The function "list2re" in Data::Munge on CPAN can also be used to form
+a single regex that matches a list of literal strings (not regexes).
+.PP
+For more details on regular expression efficiency, see \fIMastering
+Regular Expressions\fR by Jeffrey Friedl. He explains how the regular
+expressions engine works and why some patterns are surprisingly
+inefficient. Once you understand how perl applies regular expressions,
+you can tune them for individual situations.
+.ie n .SS "Why don't word-boundary searches with ""\eb"" work for me?"
+.el .SS "Why don't word-boundary searches with \f(CW\eb\fP work for me?"
+.IX Xref "\\b"
+.IX Subsection "Why don't word-boundary searches with b work for me?"
+(contributed by brian d foy)
+.PP
+Ensure that you know what \eb really does: it's the boundary between a
+word character, \ew, and something that isn't a word character. That
+thing that isn't a word character might be \eW, but it can also be the
+start or end of the string.
+.PP
+It's not (not!) the boundary between whitespace and non-whitespace,
+and it's not the stuff between words we use to create sentences.
+.PP
+In regex speak, a word boundary (\eb) is a "zero width assertion",
+meaning that it doesn't represent a character in the string, but a
+condition at a certain position.
+.PP
+For the regular expression, /\ebPerl\eb/, there has to be a word
+boundary before the "P" and after the "l". As long as something other
+than a word character precedes the "P" and succeeds the "l", the
+pattern will match. These strings match /\ebPerl\eb/.
+.PP
+.Vb 4
+\&    "Perl"    # no word char before "P" or after "l"
+\&    "Perl "   # same as previous (space is not a word char)
+\&    "\*(AqPerl\*(Aq"  # the "\*(Aq" char is not a word char
+\&    "Perl\*(Aqs"  # no word char before "P", non\-word char after "l"
+.Ve
+.PP
+These strings do not match /\ebPerl\eb/.
+.PP
+.Vb 2
+\&    "Perl_"   # "_" is a word char!
+\&    "Perler"  # no word char before "P", but one after "l"
+.Ve
+.PP
+You don't have to use \eb to match words though. You can look for
+non-word characters surrounded by word characters. These strings
+match the pattern /\eb'\eb/.
+.PP
+.Vb 2
+\&    "don\*(Aqt"   # the "\*(Aq" char is surrounded by "n" and "t"
+\&    "qep\*(Aqa\*(Aq"  # the "\*(Aq" char is surrounded by "p" and "a"
+.Ve
+.PP
+These strings do not match /\eb'\eb/.
+.PP
+.Vb 1
+\&    "foo\*(Aq"    # there is no word char after non\-word "\*(Aq"
+.Ve
+.PP
+You can also use the complement of \eb, \eB, to specify that there
+should not be a word boundary.
+.PP
+In the pattern /\eBam\eB/, there must be a word character before the "a"
+and after the "m". These patterns match /\eBam\eB/:
+.PP
+.Vb 2
+\&    "llama"   # "am" surrounded by word chars
+\&    "Samuel"  # same
+.Ve
+.PP
+These strings do not match /\eBam\eB/
+.PP
+.Vb 2
+\&    "Sam"      # no word boundary before "a", but one after "m"
+\&    "I am Sam" # "am" surrounded by non\-word chars
+.Ve
+.SS "Why does using $&, $`, or $' slow my program down?"
+.IX Xref "$MATCH $& $POSTMATCH $' $PREMATCH $`"
+.IX Subsection "Why does using $&, $`, or $' slow my program down?"
+(contributed by Anno Siegel)
+.PP
+Once Perl sees that you need one of these variables anywhere in the
+program, it provides them on each and every pattern match. That means
+that on every pattern match the entire string will be copied, part of it
+to $`, part to $&, and part to $'. Thus the penalty is most severe with
+long strings and patterns that match often. Avoid $&, $', and $` if you
+can, but if you can't, once you've used them at all, use them at will
+because you've already paid the price. Remember that some algorithms
+really appreciate them. As of the 5.005 release, the $& variable is no
+longer "expensive" the way the other two are.
+.PP
+Since Perl 5.6.1 the special variables @\- and @+ can functionally replace
+$`, $& and $'. These arrays contain pointers to the beginning and end
+of each match (see perlvar for the full story), so they give you
+essentially the same information, but without the risk of excessive
+string copying.
+.PP
+Perl 5.10 added three specials, \f(CW\*(C`${^MATCH}\*(C'\fR, \f(CW\*(C`${^PREMATCH}\*(C'\fR, and
+\&\f(CW\*(C`${^POSTMATCH}\*(C'\fR to do the same job but without the global performance
+penalty. Perl 5.10 only sets these variables if you compile or execute the
+regular expression with the \f(CW\*(C`/p\*(C'\fR modifier.
+.ie n .SS "What good is ""\eG"" in a regular expression?"
+.el .SS "What good is \f(CW\eG\fP in a regular expression?"
+.IX Xref "\\G"
+.IX Subsection "What good is G in a regular expression?"
+You use the \f(CW\*(C`\eG\*(C'\fR anchor to start the next match on the same
+string where the last match left off. The regular
+expression engine cannot skip over any characters to find
+the next match with this anchor, so \f(CW\*(C`\eG\*(C'\fR is similar to the
+beginning of string anchor, \f(CW\*(C`^\*(C'\fR. The \f(CW\*(C`\eG\*(C'\fR anchor is typically
+used with the \f(CW\*(C`g\*(C'\fR modifier. It uses the value of \f(CWpos()\fR
+as the position to start the next match. As the match
+operator makes successive matches, it updates \f(CWpos()\fR with the
+position of the next character past the last match (or the
+first character of the next match, depending on how you like
+to look at it). Each string has its own \f(CWpos()\fR value.
+.PP
+Suppose you want to match all of consecutive pairs of digits
+in a string like "1122a44" and stop matching when you
+encounter non-digits. You want to match \f(CW11\fR and \f(CW22\fR but
+the letter \f(CW\*(C`a\*(C'\fR shows up between \f(CW22\fR and \f(CW44\fR and you want
+to stop at \f(CW\*(C`a\*(C'\fR. Simply matching pairs of digits skips over
+the \f(CW\*(C`a\*(C'\fR and still matches \f(CW44\fR.
+.PP
+.Vb 2
+\&    $_ = "1122a44";
+\&    my @pairs = m/(\ed\ed)/g;   # qw( 11 22 44 )
+.Ve
+.PP
+If you use the \f(CW\*(C`\eG\*(C'\fR anchor, you force the match after \f(CW22\fR to
+start with the \f(CW\*(C`a\*(C'\fR. The regular expression cannot match
+there since it does not find a digit, so the next match
+fails and the match operator returns the pairs it already
+found.
+.PP
+.Vb 2
+\&    $_ = "1122a44";
+\&    my @pairs = m/\eG(\ed\ed)/g; # qw( 11 22 )
+.Ve
+.PP
+You can also use the \f(CW\*(C`\eG\*(C'\fR anchor in scalar context. You
+still need the \f(CW\*(C`g\*(C'\fR modifier.
+.PP
+.Vb 4
+\&    $_ = "1122a44";
+\&    while( m/\eG(\ed\ed)/g ) {
+\&        print "Found $1\en";
+\&    }
+.Ve
+.PP
+After the match fails at the letter \f(CW\*(C`a\*(C'\fR, perl resets \f(CWpos()\fR
+and the next match on the same string starts at the beginning.
+.PP
+.Vb 4
+\&    $_ = "1122a44";
+\&    while( m/\eG(\ed\ed)/g ) {
+\&        print "Found $1\en";
+\&    }
+\&
+\&    print "Found $1 after while" if m/(\ed\ed)/g; # finds "11"
+.Ve
+.PP
+You can disable \f(CWpos()\fR resets on fail with the \f(CW\*(C`c\*(C'\fR modifier, documented
+in perlop and perlreref. Subsequent matches start where the last
+successful match ended (the value of \f(CWpos()\fR) even if a match on the
+same string has failed in the meantime. In this case, the match after
+the \f(CWwhile()\fR loop starts at the \f(CW\*(C`a\*(C'\fR (where the last match stopped),
+and since it does not use any anchor it can skip over the \f(CW\*(C`a\*(C'\fR to find
+\&\f(CW44\fR.
+.PP
+.Vb 4
+\&    $_ = "1122a44";
+\&    while( m/\eG(\ed\ed)/gc ) {
+\&        print "Found $1\en";
+\&    }
+\&
+\&    print "Found $1 after while" if m/(\ed\ed)/g; # finds "44"
+.Ve
+.PP
+Typically you use the \f(CW\*(C`\eG\*(C'\fR anchor with the \f(CW\*(C`c\*(C'\fR modifier
+when you want to try a different match if one fails,
+such as in a tokenizer. Jeffrey Friedl offers this example
+which works in 5.004 or later.
+.PP
+.Vb 9
+\&    while (<>) {
+\&        chomp;
+\&        PARSER: {
+\&            m/ \eG( \ed+\eb    )/gcx   && do { print "number: $1\en";  redo; };
+\&            m/ \eG( \ew+      )/gcx   && do { print "word:   $1\en";  redo; };
+\&            m/ \eG( \es+      )/gcx   && do { print "space:  $1\en";  redo; };
+\&            m/ \eG( [^\ew\ed]+ )/gcx   && do { print "other:  $1\en";  redo; };
+\&        }
+\&    }
+.Ve
+.PP
+For each line, the \f(CW\*(C`PARSER\*(C'\fR loop first tries to match a series
+of digits followed by a word boundary. This match has to
+start at the place the last match left off (or the beginning
+of the string on the first match). Since \f(CW\*(C`m/ \eG( \ed+\eb
+)/gcx\*(C'\fR uses the \f(CW\*(C`c\*(C'\fR modifier, if the string does not match that
+regular expression, perl does not reset \fBpos()\fR and the next
+match starts at the same position to try a different
+pattern.
+.SS "Are Perl regexes DFAs or NFAs? Are they POSIX compliant?"
+.IX Xref "DFA NFA POSIX"
+.IX Subsection "Are Perl regexes DFAs or NFAs? Are they POSIX compliant?"
+While it's true that Perl's regular expressions resemble the DFAs
+(deterministic finite automata) of the \fBegrep\fR\|(1) program, they are in
+fact implemented as NFAs (non-deterministic finite automata) to allow
+backtracking and backreferencing. And they aren't POSIX-style either,
+because those guarantee worst-case behavior for all cases. (It seems
+that some people prefer guarantees of consistency, even when what's
+guaranteed is slowness.) See the book "Mastering Regular Expressions"
+(from O'Reilly) by Jeffrey Friedl for all the details you could ever
+hope to know on these matters (a full citation appears in
+perlfaq2).
+.SS "What's wrong with using grep in a void context?"
+.IX Xref "grep"
+.IX Subsection "What's wrong with using grep in a void context?"
+The problem is that grep builds a return list, regardless of the context.
+This means you're making Perl go to the trouble of building a list that
+you then just throw away. If the list is large, you waste both time and space.
+If your intent is to iterate over the list, then use a for loop for this
+purpose.
+.PP
+In perls older than 5.8.1, map suffers from this problem as well.
+But since 5.8.1, this has been fixed, and map is context aware \- in void
+context, no lists are constructed.
+.SS "How can I match strings with multibyte characters?"
+.IX Xref "regex, and multibyte characters regexp, and multibyte characters regular expression, and multibyte characters martian encoding, Martian"
+.IX Subsection "How can I match strings with multibyte characters?"
+Starting from Perl 5.6 Perl has had some level of multibyte character
+support. Perl 5.8 or later is recommended. Supported multibyte
+character repertoires include Unicode, and legacy encodings
+through the Encode module. See perluniintro, perlunicode,
+and Encode.
+.PP
+If you are stuck with older Perls, you can do Unicode with the
+Unicode::String module, and character conversions using the
+Unicode::Map8 and Unicode::Map modules. If you are using
+Japanese encodings, you might try using the jperl 5.005_03.
+.PP
+Finally, the following set of approaches was offered by Jeffrey
+Friedl, whose article in issue #5 of The Perl Journal talks about
+this very matter.
+.PP
+Let's suppose you have some weird Martian encoding where pairs of
+ASCII uppercase letters encode single Martian letters (i.e. the two
+bytes "CV" make a single Martian letter, as do the two bytes "SG",
+"VS", "XX", etc.). Other bytes represent single characters, just like
+ASCII.
+.PP
+So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the
+nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.
+.PP
+Now, say you want to search for the single character \f(CW\*(C`/GX/\*(C'\fR. Perl
+doesn't know about Martian, so it'll find the two bytes "GX" in the "I
+am CVSGXX!" string, even though that character isn't there: it just
+looks like it is because "SG" is next to "XX", but there's no real
+"GX". This is a big problem.
+.PP
+Here are a few ways, all painful, to deal with it:
+.PP
+.Vb 2
+\&    # Make sure adjacent "martian" bytes are no longer adjacent.
+\&    $martian =~ s/([A\-Z][A\-Z])/ $1 /g;
+\&
+\&    print "found GX!\en" if $martian =~ /GX/;
+.Ve
+.PP
+Or like this:
+.PP
+.Vb 6
+\&    my @chars = $martian =~ m/([A\-Z][A\-Z]|[^A\-Z])/g;
+\&    # above is conceptually similar to:     my @chars = $text =~ m/(.)/g;
+\&    #
+\&    foreach my $char (@chars) {
+\&        print "found GX!\en", last if $char eq \*(AqGX\*(Aq;
+\&    }
+.Ve
+.PP
+Or like this:
+.PP
+.Vb 6
+\&    while ($martian =~ m/\eG([A\-Z][A\-Z]|.)/gs) {  # \eG probably unneeded
+\&        if ($1 eq \*(AqGX\*(Aq) {
+\&            print "found GX!\en";
+\&            last;
+\&        }
+\&    }
+.Ve
+.PP
+Here's another, slightly less painful, way to do it from Benjamin
+Goldberg, who uses a zero-width negative look-behind assertion.
+.PP
+.Vb 5
+\&    print "found GX!\en" if    $martian =~ m/
+\&        (?<![A\-Z])
+\&        (?:[A\-Z][A\-Z])*?
+\&        GX
+\&        /x;
+.Ve
+.PP
+This succeeds if the "martian" character GX is in the string, and fails
+otherwise. If you don't like using (?<!), a zero-width negative
+look-behind assertion, you can replace (?<![A\-Z]) with (?:^|[^A\-Z]).
+.PP
+It does have the drawback of putting the wrong thing in $\-[0] and $+[0],
+but this usually can be worked around.
+.SS "How do I match a regular expression that's in a variable?"
+.IX Xref "regex, in variable eval regex quotemeta \\Q, regex \\E, regex qr"
+.IX Subsection "How do I match a regular expression that's in a variable?"
+(contributed by brian d foy)
+.PP
+We don't have to hard-code patterns into the match operator (or
+anything else that works with regular expressions). We can put the
+pattern in a variable for later use.
+.PP
+The match operator is a double quote context, so you can interpolate
+your variable just like a double quoted string. In this case, you
+read the regular expression as user input and store it in \f(CW$regex\fR.
+Once you have the pattern in \f(CW$regex\fR, you use that variable in the
+match operator.
+.PP
+.Vb 1
+\&    chomp( my $regex = <STDIN> );
+\&
+\&    if( $string =~ m/$regex/ ) { ... }
+.Ve
+.PP
+Any regular expression special characters in \f(CW$regex\fR are still
+special, and the pattern still has to be valid or Perl will complain.
+For instance, in this pattern there is an unpaired parenthesis.
+.PP
+.Vb 1
+\&    my $regex = "Unmatched ( paren";
+\&
+\&    "Two parens to bind them all" =~ m/$regex/;
+.Ve
+.PP
+When Perl compiles the regular expression, it treats the parenthesis
+as the start of a memory match. When it doesn't find the closing
+parenthesis, it complains:
+.PP
+.Vb 1
+\&    Unmatched ( in regex; marked by <\-\- HERE in m/Unmatched ( <\-\- HERE  paren/ at script line 3.
+.Ve
+.PP
+You can get around this in several ways depending on our situation.
+First, if you don't want any of the characters in the string to be
+special, you can escape them with \f(CW\*(C`quotemeta\*(C'\fR before you use the string.
+.PP
+.Vb 2
+\&    chomp( my $regex = <STDIN> );
+\&    $regex = quotemeta( $regex );
+\&
+\&    if( $string =~ m/$regex/ ) { ... }
+.Ve
+.PP
+You can also do this directly in the match operator using the \f(CW\*(C`\eQ\*(C'\fR
+and \f(CW\*(C`\eE\*(C'\fR sequences. The \f(CW\*(C`\eQ\*(C'\fR tells Perl where to start escaping
+special characters, and the \f(CW\*(C`\eE\*(C'\fR tells it where to stop (see perlop
+for more details).
+.PP
+.Vb 1
+\&    chomp( my $regex = <STDIN> );
+\&
+\&    if( $string =~ m/\eQ$regex\eE/ ) { ... }
+.Ve
+.PP
+Alternately, you can use \f(CW\*(C`qr//\*(C'\fR, the regular expression quote operator (see
+perlop for more details). It quotes and perhaps compiles the pattern,
+and you can apply regular expression flags to the pattern.
+.PP
+.Vb 1
+\&    chomp( my $input = <STDIN> );
+\&
+\&    my $regex = qr/$input/is;
+\&
+\&    $string =~ m/$regex/  # same as m/$input/is;
+.Ve
+.PP
+You might also want to trap any errors by wrapping an \f(CW\*(C`eval\*(C'\fR block
+around the whole thing.
+.PP
+.Vb 1
+\&    chomp( my $input = <STDIN> );
+\&
+\&    eval {
+\&        if( $string =~ m/\eQ$input\eE/ ) { ... }
+\&    };
+\&    warn $@ if $@;
+.Ve
+.PP
+Or...
+.PP
+.Vb 7
+\&    my $regex = eval { qr/$input/is };
+\&    if( defined $regex ) {
+\&        $string =~ m/$regex/;
+\&    }
+\&    else {
+\&        warn $@;
+\&    }
+.Ve
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq7.1 b/upstream/mageia-cauldron/man1/perlfaq7.1
new file mode 100644
index 00000000..4f123e1d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq7.1
@@ -0,0 +1,1222 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ7 1"
+.TH PERLFAQ7 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq7 \- General Perl Language Issues
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section deals with general Perl language issues that don't
+clearly fit into any of the other sections.
+.SS "Can I get a BNF/yacc/RE for the Perl language?"
+.IX Subsection "Can I get a BNF/yacc/RE for the Perl language?"
+There is no BNF, but you can paw your way through the yacc grammar in
+perly.y in the source distribution if you're particularly brave. The
+grammar relies on very smart tokenizing code, so be prepared to
+venture into toke.c as well.
+.PP
+In the words of Chaim Frenkel: "Perl's grammar can not be reduced to BNF.
+The work of parsing perl is distributed between yacc, the lexer, smoke
+and mirrors."
+.SS "What are all these $@%&* punctuation signs, and how do I know when to use them?"
+.IX Subsection "What are all these $@%&* punctuation signs, and how do I know when to use them?"
+They are type specifiers, as detailed in perldata:
+.PP
+.Vb 6
+\&    $ for scalar values (number, string or reference)
+\&    @ for arrays
+\&    % for hashes (associative arrays)
+\&    & for subroutines (aka functions, procedures, methods)
+\&    * for all types of that symbol name. In version 4 you used them like
+\&      pointers, but in modern perls you can just use references.
+.Ve
+.PP
+There are a couple of other symbols that
+you're likely to encounter that aren't
+really type specifiers:
+.PP
+.Vb 2
+\&    <> are used for inputting a record from a filehandle.
+\&    \e  takes a reference to something.
+.Ve
+.PP
+Note that <FILE> is \fIneither\fR the type specifier for files
+nor the name of the handle. It is the \f(CW\*(C`<>\*(C'\fR operator applied
+to the handle FILE. It reads one line (well, record\-\-see
+"$/" in perlvar) from the handle FILE in scalar context, or \fIall\fR lines
+in list context. When performing open, close, or any other operation
+besides \f(CW\*(C`<>\*(C'\fR on files, or even when talking about the handle, do
+\&\fInot\fR use the brackets. These are correct: \f(CWeof(FH)\fR, \f(CW\*(C`seek(FH, 0,
+2)\*(C'\fR and "copying from STDIN to FILE".
+.SS "Do I always/never have to quote my strings or use semicolons and commas?"
+.IX Subsection "Do I always/never have to quote my strings or use semicolons and commas?"
+Normally, a bareword doesn't need to be quoted, but in most cases
+probably should be (and must be under \f(CW\*(C`use strict\*(C'\fR). But a hash key
+consisting of a simple word and the left-hand
+operand to the \f(CW\*(C`=>\*(C'\fR operator both
+count as though they were quoted:
+.PP
+.Vb 4
+\&    This                    is like this
+\&    \-\-\-\-\-\-\-\-\-\-\-\-            \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    $foo{line}              $foo{\*(Aqline\*(Aq}
+\&    bar => stuff            \*(Aqbar\*(Aq => stuff
+.Ve
+.PP
+The final semicolon in a block is optional, as is the final comma in a
+list. Good style (see perlstyle) says to put them in except for
+one-liners:
+.PP
+.Vb 2
+\&    if ($whoops) { exit 1 }
+\&    my @nums = (1, 2, 3);
+\&
+\&    if ($whoops) {
+\&        exit 1;
+\&    }
+\&
+\&    my @lines = (
+\&        "There Beren came from mountains cold",
+\&        "And lost he wandered under leaves",
+\&    );
+.Ve
+.SS "How do I skip some return values?"
+.IX Subsection "How do I skip some return values?"
+One way is to treat the return values as a list and index into it:
+.PP
+.Vb 1
+\&    $dir = (getpwnam($user))[7];
+.Ve
+.PP
+Another way is to use undef as an element on the left-hand-side:
+.PP
+.Vb 1
+\&    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+.Ve
+.PP
+You can also use a list slice to select only the elements that
+you need:
+.PP
+.Vb 1
+\&    ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
+.Ve
+.SS "How do I temporarily block warnings?"
+.IX Subsection "How do I temporarily block warnings?"
+If you are running Perl 5.6.0 or better, the \f(CW\*(C`use warnings\*(C'\fR pragma
+allows fine control of what warnings are produced.
+See perllexwarn for more details.
+.PP
+.Vb 4
+\&    {
+\&        no warnings;          # temporarily turn off warnings
+\&        $x = $y + $z;         # I know these might be undef
+\&    }
+.Ve
+.PP
+Additionally, you can enable and disable categories of warnings.
+You turn off the categories you want to ignore and you can still
+get other categories of warnings. See perllexwarn for the
+complete details, including the category names and hierarchy.
+.PP
+.Vb 4
+\&    {
+\&        no warnings \*(Aquninitialized\*(Aq;
+\&        $x = $y + $z;
+\&    }
+.Ve
+.PP
+If you have an older version of Perl, the \f(CW$^W\fR variable (documented
+in perlvar) controls runtime warnings for a block:
+.PP
+.Vb 4
+\&    {
+\&        local $^W = 0;        # temporarily turn off warnings
+\&        $x = $y + $z;         # I know these might be undef
+\&    }
+.Ve
+.PP
+Note that like all the punctuation variables, you cannot currently
+use \fBmy()\fR on \f(CW$^W\fR, only \fBlocal()\fR.
+.SS "What's an extension?"
+.IX Subsection "What's an extension?"
+An extension is a way of calling compiled C code from Perl. Reading
+perlxstut is a good place to learn more about extensions.
+.SS "Why do Perl operators have different precedence than C operators?"
+.IX Subsection "Why do Perl operators have different precedence than C operators?"
+Actually, they don't. All C operators that Perl copies have the same
+precedence in Perl as they do in C. The problem is with operators that C
+doesn't have, especially functions that give a list context to everything
+on their right, eg. print, chmod, exec, and so on. Such functions are
+called "list operators" and appear as such in the precedence table in
+perlop.
+.PP
+A common mistake is to write:
+.PP
+.Vb 1
+\&    unlink $file || die "snafu";
+.Ve
+.PP
+This gets interpreted as:
+.PP
+.Vb 1
+\&    unlink ($file || die "snafu");
+.Ve
+.PP
+To avoid this problem, either put in extra parentheses or use the
+super low precedence \f(CW\*(C`or\*(C'\fR operator:
+.PP
+.Vb 2
+\&    (unlink $file) || die "snafu";
+\&    unlink $file or die "snafu";
+.Ve
+.PP
+The "English" operators (\f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR, \f(CW\*(C`xor\*(C'\fR, and \f(CW\*(C`not\*(C'\fR)
+deliberately have precedence lower than that of list operators for
+just such situations as the one above.
+.PP
+Another operator with surprising precedence is exponentiation. It
+binds more tightly even than unary minus, making \f(CW\*(C`\-2**2\*(C'\fR produce a
+negative four and not a positive one. It is also right-associating, meaning
+that \f(CW\*(C`2**3**2\*(C'\fR is two raised to the ninth power, not eight squared.
+.PP
+Although it has the same precedence as in C, Perl's \f(CW\*(C`?:\*(C'\fR operator
+produces an lvalue. This assigns \f(CW$x\fR to either \f(CW$if_true\fR or \f(CW$if_false\fR, depending
+on the trueness of \f(CW$maybe:\fR
+.PP
+.Vb 1
+\&    ($maybe ? $if_true : $if_false) = $x;
+.Ve
+.SS "How do I declare/create a structure?"
+.IX Subsection "How do I declare/create a structure?"
+In general, you don't "declare" a structure. Just use a (probably
+anonymous) hash reference. See perlref and perldsc for details.
+Here's an example:
+.PP
+.Vb 3
+\&    $person = {};                   # new anonymous hash
+\&    $person\->{AGE}  = 24;           # set field AGE to 24
+\&    $person\->{NAME} = "Nat";        # set field NAME to "Nat"
+.Ve
+.PP
+If you're looking for something a bit more rigorous, try perlootut.
+.SS "How do I create a module?"
+.IX Subsection "How do I create a module?"
+perlnewmod is a good place to start, ignore the bits
+about uploading to CPAN if you don't want to make your
+module publicly available.
+.PP
+ExtUtils::ModuleMaker and Module::Starter are also
+good places to start. Many CPAN authors now use Dist::Zilla
+to automate as much as possible.
+.PP
+Detailed documentation about modules can be found at:
+perlmod, perlmodlib, perlmodstyle.
+.PP
+If you need to include C code or C library interfaces
+use h2xs. h2xs will create the module distribution structure
+and the initial interface files.
+perlxs and perlxstut explain the details.
+.SS "How do I adopt or take over a module already on CPAN?"
+.IX Subsection "How do I adopt or take over a module already on CPAN?"
+Ask the current maintainer to make you a co-maintainer or
+transfer the module to you.
+.PP
+If you can not reach the author for some reason contact
+the PAUSE admins at modules@perl.org who may be able to help,
+but each case is treated separately.
+.IP \(bu 4
+Get a login for the Perl Authors Upload Server (PAUSE) if you don't
+already have one: <http://pause.perl.org>
+.IP \(bu 4
+Write to modules@perl.org explaining what you did to contact the
+current maintainer. The PAUSE admins will also try to reach the
+maintainer.
+.IP \(bu 4
+Post a public message in a heavily trafficked site announcing your
+intention to take over the module.
+.IP \(bu 4
+Wait a bit. The PAUSE admins don't want to act too quickly in case
+the current maintainer is on holiday. If there's no response to
+private communication or the public post, a PAUSE admin can transfer
+it to you.
+.SS "How do I create a class?"
+.IX Xref "class, creation package"
+.IX Subsection "How do I create a class?"
+(contributed by brian d foy)
+.PP
+In Perl, a class is just a package, and methods are just subroutines.
+Perl doesn't get more formal than that and lets you set up the package
+just the way that you like it (that is, it doesn't set up anything for
+you).
+.PP
+See also perlootut, a tutorial that covers class creation, and perlobj.
+.SS "How can I tell if a variable is tainted?"
+.IX Subsection "How can I tell if a variable is tainted?"
+You can use the \fBtainted()\fR function of the Scalar::Util module, available
+from CPAN (or included with Perl since release 5.8.0).
+See also "Laundering and Detecting Tainted Data" in perlsec.
+.SS "What's a closure?"
+.IX Subsection "What's a closure?"
+Closures are documented in perlref.
+.PP
+\&\fIClosure\fR is a computer science term with a precise but
+hard-to-explain meaning. Usually, closures are implemented in Perl as
+anonymous subroutines with lasting references to lexical variables
+outside their own scopes. These lexicals magically refer to the
+variables that were around when the subroutine was defined (deep
+binding).
+.PP
+Closures are most often used in programming languages where you can
+have the return value of a function be itself a function, as you can
+in Perl. Note that some languages provide anonymous functions but are
+not capable of providing proper closures: the Python language, for
+example. For more information on closures, check out any textbook on
+functional programming. Scheme is a language that not only supports
+but encourages closures.
+.PP
+Here's a classic non-closure function-generating function:
+.PP
+.Vb 3
+\&    sub add_function_generator {
+\&        return sub { shift() + shift() };
+\&    }
+\&
+\&    my $add_sub = add_function_generator();
+\&    my $sum = $add_sub\->(4,5);                # $sum is 9 now.
+.Ve
+.PP
+The anonymous subroutine returned by \fBadd_function_generator()\fR isn't
+technically a closure because it refers to no lexicals outside its own
+scope. Using a closure gives you a \fIfunction template\fR with some
+customization slots left out to be filled later.
+.PP
+Contrast this with the following \fBmake_adder()\fR function, in which the
+returned anonymous function contains a reference to a lexical variable
+outside the scope of that function itself. Such a reference requires
+that Perl return a proper closure, thus locking in for all time the
+value that the lexical had when the function was created.
+.PP
+.Vb 4
+\&    sub make_adder {
+\&        my $addpiece = shift;
+\&        return sub { shift() + $addpiece };
+\&    }
+\&
+\&    my $f1 = make_adder(20);
+\&    my $f2 = make_adder(555);
+.Ve
+.PP
+Now \f(CW$f1\->($n)\fR is always 20 plus whatever \f(CW$n\fR you pass in, whereas
+\&\f(CW$f2\->($n)\fR is always 555 plus whatever \f(CW$n\fR you pass in. The \f(CW$addpiece\fR
+in the closure sticks around.
+.PP
+Closures are often used for less esoteric purposes. For example, when
+you want to pass in a bit of code into a function:
+.PP
+.Vb 2
+\&    my $line;
+\&    timeout( 30, sub { $line = <STDIN> } );
+.Ve
+.PP
+If the code to execute had been passed in as a string,
+\&\f(CW\*(Aq$line = <STDIN>\*(Aq\fR, there would have been no way for the
+hypothetical \fBtimeout()\fR function to access the lexical variable
+\&\f(CW$line\fR back in its caller's scope.
+.PP
+Another use for a closure is to make a variable \fIprivate\fR to a
+named subroutine, e.g. a counter that gets initialized at creation
+time of the sub and can only be modified from within the sub.
+This is sometimes used with a BEGIN block in package files to make
+sure a variable doesn't get meddled with during the lifetime of the
+package:
+.PP
+.Vb 4
+\&    BEGIN {
+\&        my $id = 0;
+\&        sub next_id { ++$id }
+\&    }
+.Ve
+.PP
+This is discussed in more detail in perlsub; see the entry on
+\&\fIPersistent Private Variables\fR.
+.SS "What is variable suicide and how can I prevent it?"
+.IX Subsection "What is variable suicide and how can I prevent it?"
+This problem was fixed in perl 5.004_05, so preventing it means upgrading
+your version of perl. ;)
+.PP
+Variable suicide is when you (temporarily or permanently) lose the value
+of a variable. It is caused by scoping through \fBmy()\fR and \fBlocal()\fR
+interacting with either closures or aliased \fBforeach()\fR iterator variables
+and subroutine arguments. It used to be easy to inadvertently lose a
+variable's value this way, but now it's much harder. Take this code:
+.PP
+.Vb 4
+\&    my $f = \*(Aqfoo\*(Aq;
+\&    sub T {
+\&        while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\en" }
+\&    }
+\&
+\&    T;
+\&    print "Finally $f\en";
+.Ve
+.PP
+If you are experiencing variable suicide, that \f(CW\*(C`my $f\*(C'\fR in the subroutine
+doesn't pick up a fresh copy of the \f(CW$f\fR whose value is \f(CW\*(Aqfoo\*(Aq\fR. The
+output shows that inside the subroutine the value of \f(CW$f\fR leaks through
+when it shouldn't, as in this output:
+.PP
+.Vb 4
+\&    foobar
+\&    foobarbar
+\&    foobarbarbar
+\&    Finally foo
+.Ve
+.PP
+The \f(CW$f\fR that has "bar" added to it three times should be a new \f(CW$f\fR
+\&\f(CW\*(C`my $f\*(C'\fR should create a new lexical variable each time through the loop.
+The expected output is:
+.PP
+.Vb 4
+\&    foobar
+\&    foobar
+\&    foobar
+\&    Finally foo
+.Ve
+.SS "How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?"
+.IX Subsection "How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?"
+You need to pass references to these objects. See "Pass by
+Reference" in perlsub for this particular question, and perlref for
+information on references.
+.IP "Passing Variables and Functions" 4
+.IX Item "Passing Variables and Functions"
+Regular variables and functions are quite easy to pass: just pass in a
+reference to an existing or anonymous variable or function:
+.Sp
+.Vb 1
+\&    func( \e$some_scalar );
+\&
+\&    func( \e@some_array  );
+\&    func( [ 1 .. 10 ]   );
+\&
+\&    func( \e%some_hash   );
+\&    func( { this => 10, that => 20 }   );
+\&
+\&    func( \e&some_func   );
+\&    func( sub { $_[0] ** $_[1] }   );
+.Ve
+.IP "Passing Filehandles" 4
+.IX Item "Passing Filehandles"
+As of Perl 5.6, you can represent filehandles with scalar variables
+which you treat as any other scalar.
+.Sp
+.Vb 2
+\&    open my $fh, $filename or die "Cannot open $filename! $!";
+\&    func( $fh );
+\&
+\&    sub func {
+\&        my $passed_fh = shift;
+\&
+\&        my $line = <$passed_fh>;
+\&    }
+.Ve
+.Sp
+Before Perl 5.6, you had to use the \f(CW*FH\fR or \f(CW\*(C`\e*FH\*(C'\fR notations.
+These are "typeglobs"\-\-see "Typeglobs and Filehandles" in perldata
+and especially "Pass by Reference" in perlsub for more information.
+.IP "Passing Regexes" 4
+.IX Item "Passing Regexes"
+Here's an example of how to pass in a string and a regular expression
+for it to match against. You construct the pattern with the \f(CW\*(C`qr//\*(C'\fR
+operator:
+.Sp
+.Vb 6
+\&    sub compare {
+\&        my ($val1, $regex) = @_;
+\&        my $retval = $val1 =~ /$regex/;
+\&        return $retval;
+\&    }
+\&    $match = compare("old McDonald", qr/d.*D/i);
+.Ve
+.IP "Passing Methods" 4
+.IX Item "Passing Methods"
+To pass an object method into a subroutine, you can do this:
+.Sp
+.Vb 7
+\&    call_a_lot(10, $some_obj, "methname")
+\&    sub call_a_lot {
+\&        my ($count, $widget, $trick) = @_;
+\&        for (my $i = 0; $i < $count; $i++) {
+\&            $widget\->$trick();
+\&        }
+\&    }
+.Ve
+.Sp
+Or, you can use a closure to bundle up the object, its
+method call, and arguments:
+.Sp
+.Vb 6
+\&    my $whatnot = sub { $some_obj\->obfuscate(@args) };
+\&    func($whatnot);
+\&    sub func {
+\&        my $code = shift;
+\&        &$code();
+\&    }
+.Ve
+.Sp
+You could also investigate the \fBcan()\fR method in the UNIVERSAL class
+(part of the standard perl distribution).
+.SS "How do I create a static variable?"
+.IX Subsection "How do I create a static variable?"
+(contributed by brian d foy)
+.PP
+In Perl 5.10, declare the variable with \f(CW\*(C`state\*(C'\fR. The \f(CW\*(C`state\*(C'\fR
+declaration creates the lexical variable that persists between calls
+to the subroutine:
+.PP
+.Vb 1
+\&    sub counter { state $count = 1; $count++ }
+.Ve
+.PP
+You can fake a static variable by using a lexical variable which goes
+out of scope. In this example, you define the subroutine \f(CW\*(C`counter\*(C'\fR, and
+it uses the lexical variable \f(CW$count\fR. Since you wrap this in a BEGIN
+block, \f(CW$count\fR is defined at compile-time, but also goes out of
+scope at the end of the BEGIN block. The BEGIN block also ensures that
+the subroutine and the value it uses is defined at compile-time so the
+subroutine is ready to use just like any other subroutine, and you can
+put this code in the same place as other subroutines in the program
+text (i.e. at the end of the code, typically). The subroutine
+\&\f(CW\*(C`counter\*(C'\fR still has a reference to the data, and is the only way you
+can access the value (and each time you do, you increment the value).
+The data in chunk of memory defined by \f(CW$count\fR is private to
+\&\f(CW\*(C`counter\*(C'\fR.
+.PP
+.Vb 4
+\&    BEGIN {
+\&        my $count = 1;
+\&        sub counter { $count++ }
+\&    }
+\&
+\&    my $start = counter();
+\&
+\&    .... # code that calls counter();
+\&
+\&    my $end = counter();
+.Ve
+.PP
+In the previous example, you created a function-private variable
+because only one function remembered its reference. You could define
+multiple functions while the variable is in scope, and each function
+can share the "private" variable. It's not really "static" because you
+can access it outside the function while the lexical variable is in
+scope, and even create references to it. In this example,
+\&\f(CW\*(C`increment_count\*(C'\fR and \f(CW\*(C`return_count\*(C'\fR share the variable. One
+function adds to the value and the other simply returns the value.
+They can both access \f(CW$count\fR, and since it has gone out of scope,
+there is no other way to access it.
+.PP
+.Vb 5
+\&    BEGIN {
+\&        my $count = 1;
+\&        sub increment_count { $count++ }
+\&        sub return_count    { $count }
+\&    }
+.Ve
+.PP
+To declare a file-private variable, you still use a lexical variable.
+A file is also a scope, so a lexical variable defined in the file
+cannot be seen from any other file.
+.PP
+See "Persistent Private Variables" in perlsub for more information.
+The discussion of closures in perlref may help you even though we
+did not use anonymous subroutines in this answer. See
+"Persistent Private Variables" in perlsub for details.
+.SS "What's the difference between dynamic and lexical (static) scoping? Between \fBlocal()\fP and \fBmy()\fP?"
+.IX Subsection "What's the difference between dynamic and lexical (static) scoping? Between local() and my()?"
+\&\f(CWlocal($x)\fR saves away the old value of the global variable \f(CW$x\fR
+and assigns a new value for the duration of the subroutine \fIwhich is
+visible in other functions called from that subroutine\fR. This is done
+at run-time, so is called dynamic scoping. \fBlocal()\fR always affects global
+variables, also called package variables or dynamic variables.
+.PP
+\&\f(CWmy($x)\fR creates a new variable that is only visible in the current
+subroutine. This is done at compile-time, so it is called lexical or
+static scoping. \fBmy()\fR always affects private variables, also called
+lexical variables or (improperly) static(ly scoped) variables.
+.PP
+For instance:
+.PP
+.Vb 3
+\&    sub visible {
+\&        print "var has value $var\en";
+\&    }
+\&
+\&    sub dynamic {
+\&        local $var = \*(Aqlocal\*(Aq;    # new temporary value for the still\-global
+\&        visible();              #   variable called $var
+\&    }
+\&
+\&    sub lexical {
+\&        my $var = \*(Aqprivate\*(Aq;    # new private variable, $var
+\&        visible();              # (invisible outside of sub scope)
+\&    }
+\&
+\&    $var = \*(Aqglobal\*(Aq;
+\&
+\&    visible();              # prints global
+\&    dynamic();              # prints local
+\&    lexical();              # prints global
+.Ve
+.PP
+Notice how at no point does the value "private" get printed. That's
+because \f(CW$var\fR only has that value within the block of the \fBlexical()\fR
+function, and it is hidden from the called subroutine.
+.PP
+In summary, \fBlocal()\fR doesn't make what you think of as private, local
+variables. It gives a global variable a temporary value. \fBmy()\fR is
+what you're looking for if you want private variables.
+.PP
+See "Private Variables via \fBmy()\fR" in perlsub and
+"Temporary Values via \fBlocal()\fR" in perlsub for excruciating details.
+.SS "How can I access a dynamic variable while a similarly named lexical is in scope?"
+.IX Subsection "How can I access a dynamic variable while a similarly named lexical is in scope?"
+If you know your package, you can just mention it explicitly, as in
+\&\f(CW$Some_Pack::var\fR. Note that the notation \f(CW$::var\fR is \fBnot\fR the dynamic \f(CW$var\fR
+in the current package, but rather the one in the "main" package, as
+though you had written \f(CW$main::var\fR.
+.PP
+.Vb 3
+\&    use vars \*(Aq$var\*(Aq;
+\&    local $var = "global";
+\&    my    $var = "lexical";
+\&
+\&    print "lexical is $var\en";
+\&    print "global  is $main::var\en";
+.Ve
+.PP
+Alternatively you can use the compiler directive \fBour()\fR to bring a
+dynamic variable into the current lexical scope.
+.PP
+.Vb 2
+\&    require 5.006; # our() did not exist before 5.6
+\&    use vars \*(Aq$var\*(Aq;
+\&
+\&    local $var = "global";
+\&    my $var    = "lexical";
+\&
+\&    print "lexical is $var\en";
+\&
+\&    {
+\&        our $var;
+\&        print "global  is $var\en";
+\&    }
+.Ve
+.SS "What's the difference between deep and shallow binding?"
+.IX Subsection "What's the difference between deep and shallow binding?"
+In deep binding, lexical variables mentioned in anonymous subroutines
+are the same ones that were in scope when the subroutine was created.
+In shallow binding, they are whichever variables with the same names
+happen to be in scope when the subroutine is called. Perl always uses
+deep binding of lexical variables (i.e., those created with \fBmy()\fR).
+However, dynamic variables (aka global, local, or package variables)
+are effectively shallowly bound. Consider this just one more reason
+not to use them. See the answer to "What's a closure?".
+.SS "Why doesn't ""my($foo) = <$fh>;"" work right?"
+.IX Subsection "Why doesn't ""my($foo) = <$fh>;"" work right?"
+\&\f(CWmy()\fR and \f(CWlocal()\fR give list context to the right hand side
+of \f(CW\*(C`=\*(C'\fR. The <$fh> read operation, like so many of Perl's
+functions and operators, can tell which context it was called in and
+behaves appropriately. In general, the \fBscalar()\fR function can help.
+This function does nothing to the data itself (contrary to popular myth)
+but rather tells its argument to behave in whatever its scalar fashion is.
+If that function doesn't have a defined scalar behavior, this of course
+doesn't help you (such as with \fBsort()\fR).
+.PP
+To enforce scalar context in this particular case, however, you need
+merely omit the parentheses:
+.PP
+.Vb 3
+\&    local($foo) = <$fh>;        # WRONG
+\&    local($foo) = scalar(<$fh>);   # ok
+\&    local $foo  = <$fh>;        # right
+.Ve
+.PP
+You should probably be using lexical variables anyway, although the
+issue is the same here:
+.PP
+.Vb 2
+\&    my($foo) = <$fh>;    # WRONG
+\&    my $foo  = <$fh>;    # right
+.Ve
+.SS "How do I redefine a builtin function, operator, or method?"
+.IX Subsection "How do I redefine a builtin function, operator, or method?"
+Why do you want to do that? :\-)
+.PP
+If you want to override a predefined function, such as \fBopen()\fR,
+then you'll have to import the new definition from a different
+module. See "Overriding Built-in Functions" in perlsub.
+.PP
+If you want to overload a Perl operator, such as \f(CW\*(C`+\*(C'\fR or \f(CW\*(C`**\*(C'\fR,
+then you'll want to use the \f(CW\*(C`use overload\*(C'\fR pragma, documented
+in overload.
+.PP
+If you're talking about obscuring method calls in parent classes,
+see "Overriding methods and method resolution" in perlootut.
+.SS "What's the difference between calling a function as &foo and \fBfoo()\fP?"
+.IX Subsection "What's the difference between calling a function as &foo and foo()?"
+(contributed by brian d foy)
+.PP
+Calling a subroutine as \f(CW&foo\fR with no trailing parentheses ignores
+the prototype of \f(CW\*(C`foo\*(C'\fR and passes it the current value of the argument
+list, \f(CW@_\fR. Here's an example; the \f(CW\*(C`bar\*(C'\fR subroutine calls \f(CW&foo\fR,
+which prints its arguments list:
+.PP
+.Vb 1
+\&    sub foo { print "Args in foo are: @_\en"; }
+\&
+\&    sub bar { &foo; }
+\&
+\&    bar( "a", "b", "c" );
+.Ve
+.PP
+When you call \f(CW\*(C`bar\*(C'\fR with arguments, you see that \f(CW\*(C`foo\*(C'\fR got the same \f(CW@_\fR:
+.PP
+.Vb 1
+\&    Args in foo are: a b c
+.Ve
+.PP
+Calling the subroutine with trailing parentheses, with or without arguments,
+does not use the current \f(CW@_\fR. Changing the example to put parentheses after
+the call to \f(CW\*(C`foo\*(C'\fR changes the program:
+.PP
+.Vb 1
+\&    sub foo { print "Args in foo are: @_\en"; }
+\&
+\&    sub bar { &foo(); }
+\&
+\&    bar( "a", "b", "c" );
+.Ve
+.PP
+Now the output shows that \f(CW\*(C`foo\*(C'\fR doesn't get the \f(CW@_\fR from its caller.
+.PP
+.Vb 1
+\&    Args in foo are:
+.Ve
+.PP
+However, using \f(CW\*(C`&\*(C'\fR in the call still overrides the prototype of \f(CW\*(C`foo\*(C'\fR if
+present:
+.PP
+.Vb 1
+\&    sub foo ($$$) { print "Args infoo are: @_\en"; }
+\&
+\&    sub bar_1 { &foo; }
+\&    sub bar_2 { &foo(); }
+\&    sub bar_3 { foo( $_[0], $_[1], $_[2] ); }
+\&    # sub bar_4 { foo(); }
+\&    # bar_4 doesn\*(Aqt compile: "Not enough arguments for main::foo at ..."
+\&
+\&    bar_1( "a", "b", "c" );
+\&    # Args in foo are: a b c
+\&
+\&    bar_2( "a", "b", "c" );
+\&    # Args in foo are:
+\&
+\&    bar_3( "a", "b", "c" );
+\&    # Args in foo are: a b c
+.Ve
+.PP
+The main use of the \f(CW@_\fR pass-through feature is to write subroutines
+whose main job it is to call other subroutines for you. For further
+details, see perlsub.
+.SS "How do I create a switch or case statement?"
+.IX Subsection "How do I create a switch or case statement?"
+There is a given/when statement in Perl, but it is experimental and
+likely to change in future. See perlsyn for more details.
+.PP
+The general answer is to use a CPAN module such as Switch::Plain:
+.PP
+.Vb 6
+\&    use Switch::Plain;
+\&    sswitch($variable_holding_a_string) {
+\&        case \*(Aqfirst\*(Aq: { }
+\&        case \*(Aqsecond\*(Aq: { }
+\&        default: { }
+\&    }
+.Ve
+.PP
+or for more complicated comparisons, \f(CW\*(C`if\-elsif\-else\*(C'\fR:
+.PP
+.Vb 6
+\&    for ($variable_to_test) {
+\&        if    (/pat1/)  { }     # do something
+\&        elsif (/pat2/)  { }     # do something else
+\&        elsif (/pat3/)  { }     # do something else
+\&        else            { }     # default
+\&    }
+.Ve
+.PP
+Here's a simple example of a switch based on pattern matching,
+lined up in a way to make it look more like a switch statement.
+We'll do a multiway conditional based on the type of reference stored
+in \f(CW$whatchamacallit:\fR
+.PP
+.Vb 1
+\&    SWITCH: for (ref $whatchamacallit) {
+\&
+\&        /^$/           && die "not a reference";
+\&
+\&        /SCALAR/       && do {
+\&                        print_scalar($$ref);
+\&                        last SWITCH;
+\&                      };
+\&
+\&        /ARRAY/        && do {
+\&                        print_array(@$ref);
+\&                        last SWITCH;
+\&                      };
+\&
+\&        /HASH/        && do {
+\&                        print_hash(%$ref);
+\&                        last SWITCH;
+\&                      };
+\&
+\&        /CODE/        && do {
+\&                        warn "can\*(Aqt print function ref";
+\&                        last SWITCH;
+\&                      };
+\&
+\&        # DEFAULT
+\&
+\&        warn "User defined type skipped";
+\&
+\&    }
+.Ve
+.PP
+See perlsyn for other examples in this style.
+.PP
+Sometimes you should change the positions of the constant and the variable.
+For example, let's say you wanted to test which of many answers you were
+given, but in a case-insensitive way that also allows abbreviations.
+You can use the following technique if the strings all start with
+different characters or if you want to arrange the matches so that
+one takes precedence over another, as \f(CW"SEND"\fR has precedence over
+\&\f(CW"STOP"\fR here:
+.PP
+.Vb 6
+\&    chomp($answer = <>);
+\&    if    ("SEND"  =~ /^\eQ$answer/i) { print "Action is send\en"  }
+\&    elsif ("STOP"  =~ /^\eQ$answer/i) { print "Action is stop\en"  }
+\&    elsif ("ABORT" =~ /^\eQ$answer/i) { print "Action is abort\en" }
+\&    elsif ("LIST"  =~ /^\eQ$answer/i) { print "Action is list\en"  }
+\&    elsif ("EDIT"  =~ /^\eQ$answer/i) { print "Action is edit\en"  }
+.Ve
+.PP
+A totally different approach is to create a hash of function references.
+.PP
+.Vb 6
+\&    my %commands = (
+\&        "happy" => \e&joy,
+\&        "sad",  => \e&sullen,
+\&        "done"  => sub { die "See ya!" },
+\&        "mad"   => \e&angry,
+\&    );
+\&
+\&    print "How are you? ";
+\&    chomp($string = <STDIN>);
+\&    if ($commands{$string}) {
+\&        $commands{$string}\->();
+\&    } else {
+\&        print "No such command: $string\en";
+\&    }
+.Ve
+.PP
+Starting from Perl 5.8, a source filter module, \f(CW\*(C`Switch\*(C'\fR, can also be
+used to get switch and case. Its use is now discouraged, because it's
+not fully compatible with the native switch of Perl 5.10, and because,
+as it's implemented as a source filter, it doesn't always work as intended
+when complex syntax is involved.
+.SS "How can I catch accesses to undefined variables, functions, or methods?"
+.IX Subsection "How can I catch accesses to undefined variables, functions, or methods?"
+The AUTOLOAD method, discussed in "Autoloading" in perlsub lets you capture
+calls to undefined functions and methods.
+.PP
+When it comes to undefined variables that would trigger a warning
+under \f(CW\*(C`use warnings\*(C'\fR, you can promote the warning to an error.
+.PP
+.Vb 1
+\&    use warnings FATAL => qw(uninitialized);
+.Ve
+.SS "Why can't a method included in this same file be found?"
+.IX Subsection "Why can't a method included in this same file be found?"
+Some possible reasons: your inheritance is getting confused, you've
+misspelled the method name, or the object is of the wrong type. Check
+out perlootut for details about any of the above cases. You may
+also use \f(CW\*(C`print ref($object)\*(C'\fR to find out the class \f(CW$object\fR was
+blessed into.
+.PP
+Another possible reason for problems is that you've used the
+indirect object syntax (eg, \f(CW\*(C`find Guru "Samy"\*(C'\fR) on a class name
+before Perl has seen that such a package exists. It's wisest to make
+sure your packages are all defined before you start using them, which
+will be taken care of if you use the \f(CW\*(C`use\*(C'\fR statement instead of
+\&\f(CW\*(C`require\*(C'\fR. If not, make sure to use arrow notation (eg.,
+\&\f(CW\*(C`Guru\->find("Samy")\*(C'\fR) instead. Object notation is explained in
+perlobj.
+.PP
+Make sure to read about creating modules in perlmod and
+the perils of indirect objects in "Method Invocation" in perlobj.
+.SS "How can I find out my current or calling package?"
+.IX Subsection "How can I find out my current or calling package?"
+(contributed by brian d foy)
+.PP
+To find the package you are currently in, use the special literal
+\&\f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR, as documented in perldata. You can only use the
+special literals as separate tokens, so you can't interpolate them
+into strings like you can with variables:
+.PP
+.Vb 2
+\&    my $current_package = _\|_PACKAGE_\|_;
+\&    print "I am in package $current_package\en";
+.Ve
+.PP
+If you want to find the package calling your code, perhaps to give better
+diagnostics as Carp does, use the \f(CW\*(C`caller\*(C'\fR built-in:
+.PP
+.Vb 3
+\&    sub foo {
+\&        my @args = ...;
+\&        my( $package, $filename, $line ) = caller;
+\&
+\&        print "I was called from package $package\en";
+\&        );
+.Ve
+.PP
+By default, your program starts in package \f(CW\*(C`main\*(C'\fR, so you will
+always be in some package.
+.PP
+This is different from finding out the package an object is blessed
+into, which might not be the current package. For that, use \f(CW\*(C`blessed\*(C'\fR
+from Scalar::Util, part of the Standard Library since Perl 5.8:
+.PP
+.Vb 2
+\&    use Scalar::Util qw(blessed);
+\&    my $object_package = blessed( $object );
+.Ve
+.PP
+Most of the time, you shouldn't care what package an object is blessed
+into, however, as long as it claims to inherit from that class:
+.PP
+.Vb 1
+\&    my $is_right_class = eval { $object\->isa( $package ) }; # true or false
+.Ve
+.PP
+And, with Perl 5.10 and later, you don't have to check for an
+inheritance to see if the object can handle a role. For that, you can
+use \f(CW\*(C`DOES\*(C'\fR, which comes from \f(CW\*(C`UNIVERSAL\*(C'\fR:
+.PP
+.Vb 1
+\&    my $class_does_it = eval { $object\->DOES( $role ) }; # true or false
+.Ve
+.PP
+You can safely replace \f(CW\*(C`isa\*(C'\fR with \f(CW\*(C`DOES\*(C'\fR (although the converse is not true).
+.SS "How can I comment out a large block of Perl code?"
+.IX Subsection "How can I comment out a large block of Perl code?"
+(contributed by brian d foy)
+.PP
+The quick-and-dirty way to comment out more than one line of Perl is
+to surround those lines with Pod directives. You have to put these
+directives at the beginning of the line and somewhere where Perl
+expects a new statement (so not in the middle of statements like the \f(CW\*(C`#\*(C'\fR
+comments). You end the comment with \f(CW\*(C`=cut\*(C'\fR, ending the Pod section:
+.PP
+.Vb 1
+\&    =pod
+\&
+\&    my $object = NotGonnaHappen\->new();
+\&
+\&    ignored_sub();
+\&
+\&    $wont_be_assigned = 37;
+\&
+\&    =cut
+.Ve
+.PP
+The quick-and-dirty method only works well when you don't plan to
+leave the commented code in the source. If a Pod parser comes along,
+your multiline comment is going to show up in the Pod translation.
+A better way hides it from Pod parsers as well.
+.PP
+The \f(CW\*(C`=begin\*(C'\fR directive can mark a section for a particular purpose.
+If the Pod parser doesn't want to handle it, it just ignores it. Label
+the comments with \f(CW\*(C`comment\*(C'\fR. End the comment using \f(CW\*(C`=end\*(C'\fR with the
+same label. You still need the \f(CW\*(C`=cut\*(C'\fR to go back to Perl code from
+the Pod comment:
+.PP
+.Vb 1
+\&    =begin comment
+\&
+\&    my $object = NotGonnaHappen\->new();
+\&
+\&    ignored_sub();
+\&
+\&    $wont_be_assigned = 37;
+\&
+\&    =end comment
+\&
+\&    =cut
+.Ve
+.PP
+For more information on Pod, check out perlpod and perlpodspec.
+.SS "How do I clear a package?"
+.IX Subsection "How do I clear a package?"
+Use this code, provided by Mark-Jason Dominus:
+.PP
+.Vb 10
+\&    sub scrub_package {
+\&        no strict \*(Aqrefs\*(Aq;
+\&        my $pack = shift;
+\&        die "Shouldn\*(Aqt delete main package"
+\&            if $pack eq "" || $pack eq "main";
+\&        my $stash = *{$pack . \*(Aq::\*(Aq}{HASH};
+\&        my $name;
+\&        foreach $name (keys %$stash) {
+\&            my $fullname = $pack . \*(Aq::\*(Aq . $name;
+\&            # Get rid of everything with that name.
+\&            undef $$fullname;
+\&            undef @$fullname;
+\&            undef %$fullname;
+\&            undef &$fullname;
+\&            undef *$fullname;
+\&        }
+\&    }
+.Ve
+.PP
+Or, if you're using a recent release of Perl, you can
+just use the \fBSymbol::delete_package()\fR function instead.
+.SS "How can I use a variable as a variable name?"
+.IX Subsection "How can I use a variable as a variable name?"
+Beginners often think they want to have a variable contain the name
+of a variable.
+.PP
+.Vb 3
+\&    $fred    = 23;
+\&    $varname = "fred";
+\&    ++$$varname;         # $fred now 24
+.Ve
+.PP
+This works \fIsometimes\fR, but it is a very bad idea for two reasons.
+.PP
+The first reason is that this technique \fIonly works on global
+variables\fR. That means that if \f(CW$fred\fR is a lexical variable created
+with \fBmy()\fR in the above example, the code wouldn't work at all: you'd
+accidentally access the global and skip right over the private lexical
+altogether. Global variables are bad because they can easily collide
+accidentally and in general make for non-scalable and confusing code.
+.PP
+Symbolic references are forbidden under the \f(CW\*(C`use strict\*(C'\fR pragma.
+They are not true references and consequently are not reference-counted
+or garbage-collected.
+.PP
+The other reason why using a variable to hold the name of another
+variable is a bad idea is that the question often stems from a lack of
+understanding of Perl data structures, particularly hashes. By using
+symbolic references, you are just using the package's symbol-table hash
+(like \f(CW%main::\fR) instead of a user-defined hash. The solution is to
+use your own hash or a real reference instead.
+.PP
+.Vb 3
+\&    $USER_VARS{"fred"} = 23;
+\&    my $varname = "fred";
+\&    $USER_VARS{$varname}++;  # not $$varname++
+.Ve
+.PP
+There we're using the \f(CW%USER_VARS\fR hash instead of symbolic references.
+Sometimes this comes up in reading strings from the user with variable
+references and wanting to expand them to the values of your perl
+program's variables. This is also a bad idea because it conflates the
+program-addressable namespace and the user-addressable one. Instead of
+reading a string and expanding it to the actual contents of your program's
+own variables:
+.PP
+.Vb 2
+\&    $str = \*(Aqthis has a $fred and $barney in it\*(Aq;
+\&    $str =~ s/(\e$\ew+)/$1/eeg;          # need double eval
+.Ve
+.PP
+it would be better to keep a hash around like \f(CW%USER_VARS\fR and have
+variable references actually refer to entries in that hash:
+.PP
+.Vb 1
+\&    $str =~ s/\e$(\ew+)/$USER_VARS{$1}/g;   # no /e here at all
+.Ve
+.PP
+That's faster, cleaner, and safer than the previous approach. Of course,
+you don't need to use a dollar sign. You could use your own scheme to
+make it less confusing, like bracketed percent symbols, etc.
+.PP
+.Vb 2
+\&    $str = \*(Aqthis has a %fred% and %barney% in it\*(Aq;
+\&    $str =~ s/%(\ew+)%/$USER_VARS{$1}/g;   # no /e here at all
+.Ve
+.PP
+Another reason that folks sometimes think they want a variable to
+contain the name of a variable is that they don't know how to build
+proper data structures using hashes. For example, let's say they
+wanted two hashes in their program: \f(CW%fred\fR and \f(CW%barney\fR, and that they
+wanted to use another scalar variable to refer to those by name.
+.PP
+.Vb 2
+\&    $name = "fred";
+\&    $$name{WIFE} = "wilma";     # set %fred
+\&
+\&    $name = "barney";
+\&    $$name{WIFE} = "betty";    # set %barney
+.Ve
+.PP
+This is still a symbolic reference, and is still saddled with the
+problems enumerated above. It would be far better to write:
+.PP
+.Vb 2
+\&    $folks{"fred"}{WIFE}   = "wilma";
+\&    $folks{"barney"}{WIFE} = "betty";
+.Ve
+.PP
+And just use a multilevel hash to start with.
+.PP
+The only times that you absolutely \fImust\fR use symbolic references are
+when you really must refer to the symbol table. This may be because it's
+something that one can't take a real reference to, such as a format name.
+Doing so may also be important for method calls, since these always go
+through the symbol table for resolution.
+.PP
+In those cases, you would turn off \f(CW\*(C`strict \*(Aqrefs\*(Aq\*(C'\fR temporarily so you
+can play around with the symbol table. For example:
+.PP
+.Vb 5
+\&    @colors = qw(red blue green yellow orange purple violet);
+\&    for my $name (@colors) {
+\&        no strict \*(Aqrefs\*(Aq;  # renege for the block
+\&        *$name = sub { "<FONT COLOR=\*(Aq$name\*(Aq>@_</FONT>" };
+\&    }
+.Ve
+.PP
+All those functions (\fBred()\fR, \fBblue()\fR, \fBgreen()\fR, etc.) appear to be separate,
+but the real code in the closure actually was compiled only once.
+.PP
+So, sometimes you might want to use symbolic references to manipulate
+the symbol table directly. This doesn't matter for formats, handles, and
+subroutines, because they are always global\-\-you can't use \fBmy()\fR on them.
+For scalars, arrays, and hashes, though\-\-and usually for subroutines\-\-
+you probably only want to use hard references.
+.SS "What does ""bad interpreter"" mean?"
+.IX Subsection "What does ""bad interpreter"" mean?"
+(contributed by brian d foy)
+.PP
+The "bad interpreter" message comes from the shell, not perl. The
+actual message may vary depending on your platform, shell, and locale
+settings.
+.PP
+If you see "bad interpreter \- no such file or directory", the first
+line in your perl script (the "shebang" line) does not contain the
+right path to perl (or any other program capable of running scripts).
+Sometimes this happens when you move the script from one machine to
+another and each machine has a different path to perl\-\-/usr/bin/perl
+versus /usr/local/bin/perl for instance. It may also indicate
+that the source machine has CRLF line terminators and the
+destination machine has LF only: the shell tries to find
+/usr/bin/perl<CR>, but can't.
+.PP
+If you see "bad interpreter: Permission denied", you need to make your
+script executable.
+.PP
+In either case, you should still be able to run the scripts with perl
+explicitly:
+.PP
+.Vb 1
+\&    % perl script.pl
+.Ve
+.PP
+If you get a message like "perl: command not found", perl is not in
+your PATH, which might also mean that the location of perl is not
+where you expect it so you need to adjust your shebang line.
+.SS "Do I need to recompile XS modules when there is a change in the C library?"
+.IX Subsection "Do I need to recompile XS modules when there is a change in the C library?"
+(contributed by Alex Beamish)
+.PP
+If the new version of the C library is ABI-compatible (that's Application
+Binary Interface compatible) with the version you're upgrading from, and if the
+shared library version didn't change, no re-compilation should be necessary.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2013 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq8.1 b/upstream/mageia-cauldron/man1/perlfaq8.1
new file mode 100644
index 00000000..36377cde
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq8.1
@@ -0,0 +1,1579 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ8 1"
+.TH PERLFAQ8 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq8 \- System Interaction
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section of the Perl FAQ covers questions involving operating
+system interaction. Topics include interprocess communication (IPC),
+control over the user-interface (keyboard, screen and pointing
+devices), and most anything else not related to data manipulation.
+.PP
+Read the FAQs and documentation specific to the port of perl to your
+operating system (eg, perlvms, perlplan9, ...). These should
+contain more detailed information on the vagaries of your perl.
+.SS "How do I find out which operating system I'm running under?"
+.IX Subsection "How do I find out which operating system I'm running under?"
+The \f(CW$^O\fR variable (\f(CW$OSNAME\fR if you use \f(CW\*(C`English\*(C'\fR) contains an
+indication of the name of the operating system (not its release
+number) that your perl binary was built for.
+.SS "How come \fBexec()\fP doesn't return?"
+.IX Xref "exec system fork open pipe"
+.IX Subsection "How come exec() doesn't return?"
+(contributed by brian d foy)
+.PP
+The \f(CW\*(C`exec\*(C'\fR function's job is to turn your process into another
+command and never to return. If that's not what you want to do, don't
+use \f(CW\*(C`exec\*(C'\fR. :)
+.PP
+If you want to run an external command and still keep your Perl process
+going, look at a piped \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, or \f(CW\*(C`system\*(C'\fR.
+.SS "How do I do fancy stuff with the keyboard/screen/mouse?"
+.IX Subsection "How do I do fancy stuff with the keyboard/screen/mouse?"
+How you access/control keyboards, screens, and pointing devices
+("mice") is system-dependent. Try the following modules:
+.IP Keyboard 4
+.IX Item "Keyboard"
+.Vb 5
+\&    Term::Cap               Standard perl distribution
+\&    Term::ReadKey           CPAN
+\&    Term::ReadLine::Gnu     CPAN
+\&    Term::ReadLine::Perl    CPAN
+\&    Term::Screen            CPAN
+.Ve
+.IP Screen 4
+.IX Item "Screen"
+.Vb 3
+\&    Term::Cap               Standard perl distribution
+\&    Curses                  CPAN
+\&    Term::ANSIColor         CPAN
+.Ve
+.IP Mouse 4
+.IX Item "Mouse"
+.Vb 4
+\&    Tk                      CPAN
+\&    Wx                      CPAN
+\&    Gtk2                    CPAN
+\&    Qt4                     kdebindings4 package
+.Ve
+.PP
+Some of these specific cases are shown as examples in other answers
+in this section of the perlfaq.
+.SS "How do I print something out in color?"
+.IX Subsection "How do I print something out in color?"
+In general, you don't, because you don't know whether
+the recipient has a color-aware display device. If you
+know that they have an ANSI terminal that understands
+color, you can use the Term::ANSIColor module from CPAN:
+.PP
+.Vb 3
+\&    use Term::ANSIColor;
+\&    print color("red"), "Stop!\en", color("reset");
+\&    print color("green"), "Go!\en", color("reset");
+.Ve
+.PP
+Or like this:
+.PP
+.Vb 3
+\&    use Term::ANSIColor qw(:constants);
+\&    print RED, "Stop!\en", RESET;
+\&    print GREEN, "Go!\en", RESET;
+.Ve
+.SS "How do I read just one key without waiting for a return key?"
+.IX Subsection "How do I read just one key without waiting for a return key?"
+Controlling input buffering is a remarkably system-dependent matter.
+On many systems, you can just use the \fBstty\fR command as shown in
+"getc" in perlfunc, but as you see, that's already getting you into
+portability snags.
+.PP
+.Vb 6
+\&    open(TTY, "+</dev/tty") or die "no tty: $!";
+\&    system "stty  cbreak </dev/tty >/dev/tty 2>&1";
+\&    $key = getc(TTY);        # perhaps this works
+\&    # OR ELSE
+\&    sysread(TTY, $key, 1);    # probably this does
+\&    system "stty \-cbreak </dev/tty >/dev/tty 2>&1";
+.Ve
+.PP
+The Term::ReadKey module from CPAN offers an easy-to-use interface that
+should be more efficient than shelling out to \fBstty\fR for each key.
+It even includes limited support for Windows.
+.PP
+.Vb 4
+\&    use Term::ReadKey;
+\&    ReadMode(\*(Aqcbreak\*(Aq);
+\&    $key = ReadKey(0);
+\&    ReadMode(\*(Aqnormal\*(Aq);
+.Ve
+.PP
+However, using the code requires that you have a working C compiler
+and can use it to build and install a CPAN module. Here's a solution
+using the standard POSIX module, which is already on your system
+(assuming your system supports POSIX).
+.PP
+.Vb 2
+\&    use HotKey;
+\&    $key = readkey();
+.Ve
+.PP
+And here's the \f(CW\*(C`HotKey\*(C'\fR module, which hides the somewhat mystifying calls
+to manipulate the POSIX termios structures.
+.PP
+.Vb 2
+\&    # HotKey.pm
+\&    package HotKey;
+\&
+\&    use strict;
+\&    use warnings;
+\&
+\&    use parent \*(AqExporter\*(Aq;
+\&    our @EXPORT = qw(cbreak cooked readkey);
+\&
+\&    use POSIX qw(:termios_h);
+\&    my ($term, $oterm, $echo, $noecho, $fd_stdin);
+\&
+\&    $fd_stdin = fileno(STDIN);
+\&    $term     = POSIX::Termios\->new();
+\&    $term\->getattr($fd_stdin);
+\&    $oterm     = $term\->getlflag();
+\&
+\&    $echo     = ECHO | ECHOK | ICANON;
+\&    $noecho   = $oterm & ~$echo;
+\&
+\&    sub cbreak {
+\&        $term\->setlflag($noecho);  # ok, so i don\*(Aqt want echo either
+\&        $term\->setcc(VTIME, 1);
+\&        $term\->setattr($fd_stdin, TCSANOW);
+\&    }
+\&
+\&    sub cooked {
+\&        $term\->setlflag($oterm);
+\&        $term\->setcc(VTIME, 0);
+\&        $term\->setattr($fd_stdin, TCSANOW);
+\&    }
+\&
+\&    sub readkey {
+\&        my $key = \*(Aq\*(Aq;
+\&        cbreak();
+\&        sysread(STDIN, $key, 1);
+\&        cooked();
+\&        return $key;
+\&    }
+\&
+\&    END { cooked() }
+\&
+\&    1;
+.Ve
+.SS "How do I check whether input is ready on the keyboard?"
+.IX Subsection "How do I check whether input is ready on the keyboard?"
+The easiest way to do this is to read a key in nonblocking mode with the
+Term::ReadKey module from CPAN, passing it an argument of \-1 to indicate
+not to block:
+.PP
+.Vb 1
+\&    use Term::ReadKey;
+\&
+\&    ReadMode(\*(Aqcbreak\*(Aq);
+\&
+\&    if (defined (my $char = ReadKey(\-1)) ) {
+\&        # input was waiting and it was $char
+\&    } else {
+\&        # no input was waiting
+\&    }
+\&
+\&    ReadMode(\*(Aqnormal\*(Aq);                  # restore normal tty settings
+.Ve
+.SS "How do I clear the screen?"
+.IX Subsection "How do I clear the screen?"
+(contributed by brian d foy)
+.PP
+To clear the screen, you just have to print the special sequence
+that tells the terminal to clear the screen. Once you have that
+sequence, output it when you want to clear the screen.
+.PP
+You can use the Term::ANSIScreen module to get the special
+sequence. Import the \f(CW\*(C`cls\*(C'\fR function (or the \f(CW\*(C`:screen\*(C'\fR tag):
+.PP
+.Vb 2
+\&    use Term::ANSIScreen qw(cls);
+\&    my $clear_screen = cls();
+\&
+\&    print $clear_screen;
+.Ve
+.PP
+The Term::Cap module can also get the special sequence if you want
+to deal with the low-level details of terminal control. The \f(CW\*(C`Tputs\*(C'\fR
+method returns the string for the given capability:
+.PP
+.Vb 1
+\&    use Term::Cap;
+\&
+\&    my $terminal = Term::Cap\->Tgetent( { OSPEED => 9600 } );
+\&    my $clear_screen = $terminal\->Tputs(\*(Aqcl\*(Aq);
+\&
+\&    print $clear_screen;
+.Ve
+.PP
+On Windows, you can use the Win32::Console module. After creating
+an object for the output filehandle you want to affect, call the
+\&\f(CW\*(C`Cls\*(C'\fR method:
+.PP
+.Vb 1
+\&    Win32::Console;
+\&
+\&    my $OUT = Win32::Console\->new(STD_OUTPUT_HANDLE);
+\&    my $clear_string = $OUT\->Cls;
+\&
+\&    print $clear_screen;
+.Ve
+.PP
+If you have a command-line program that does the job, you can call
+it in backticks to capture whatever it outputs so you can use it
+later:
+.PP
+.Vb 1
+\&    my $clear_string = \`clear\`;
+\&
+\&    print $clear_string;
+.Ve
+.SS "How do I get the screen size?"
+.IX Subsection "How do I get the screen size?"
+If you have Term::ReadKey module installed from CPAN,
+you can use it to fetch the width and height in characters
+and in pixels:
+.PP
+.Vb 2
+\&    use Term::ReadKey;
+\&    my ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
+.Ve
+.PP
+This is more portable than the raw \f(CW\*(C`ioctl\*(C'\fR, but not as
+illustrative:
+.PP
+.Vb 10
+\&    require \*(Aq./sys/ioctl.ph\*(Aq;
+\&    die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
+\&    open(my $tty_fh, "+</dev/tty")                     or die "No tty: $!";
+\&    unless (ioctl($tty_fh, &TIOCGWINSZ, $winsize=\*(Aq\*(Aq)) {
+\&        die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\en", &TIOCGWINSZ;
+\&    }
+\&    my ($row, $col, $xpixel, $ypixel) = unpack(\*(AqS4\*(Aq, $winsize);
+\&    print "(row,col) = ($row,$col)";
+\&    print "  (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
+\&    print "\en";
+.Ve
+.SS "How do I ask the user for a password?"
+.IX Subsection "How do I ask the user for a password?"
+(This question has nothing to do with the web. See a different
+FAQ for that.)
+.PP
+There's an example of this in "crypt" in perlfunc. First, you put the
+terminal into "no echo" mode, then just read the password normally.
+You may do this with an old-style \f(CWioctl()\fR function, POSIX terminal
+control (see POSIX or its documentation the Camel Book), or a call
+to the \fBstty\fR program, with varying degrees of portability.
+.PP
+You can also do this for most systems using the Term::ReadKey module
+from CPAN, which is easier to use and in theory more portable.
+.PP
+.Vb 1
+\&    use Term::ReadKey;
+\&
+\&    ReadMode(\*(Aqnoecho\*(Aq);
+\&    my $password = ReadLine(0);
+.Ve
+.SS "How do I read and write the serial port?"
+.IX Subsection "How do I read and write the serial port?"
+This depends on which operating system your program is running on. In
+the case of Unix, the serial ports will be accessible through files in
+\&\f(CW\*(C`/dev\*(C'\fR; on other systems, device names will doubtless differ.
+Several problem areas common to all device interaction are the
+following:
+.IP lockfiles 4
+.IX Item "lockfiles"
+Your system may use lockfiles to control multiple access. Make sure
+you follow the correct protocol. Unpredictable behavior can result
+from multiple processes reading from one device.
+.IP "open mode" 4
+.IX Item "open mode"
+If you expect to use both read and write operations on the device,
+you'll have to open it for update (see "open" in perlfunc for
+details). You may wish to open it without running the risk of
+blocking by using \f(CWsysopen()\fR and \f(CW\*(C`O_RDWR|O_NDELAY|O_NOCTTY\*(C'\fR from the
+Fcntl module (part of the standard perl distribution). See
+"sysopen" in perlfunc for more on this approach.
+.IP "end of line" 4
+.IX Item "end of line"
+Some devices will be expecting a "\er" at the end of each line rather
+than a "\en". In some ports of perl, "\er" and "\en" are different from
+their usual (Unix) ASCII values of "\e015" and "\e012". You may have to
+give the numeric values you want directly, using octal ("\e015"), hex
+("0x0D"), or as a control-character specification ("\ecM").
+.Sp
+.Vb 2
+\&    print DEV "atv1\e012";    # wrong, for some devices
+\&    print DEV "atv1\e015";    # right, for some devices
+.Ve
+.Sp
+Even though with normal text files a "\en" will do the trick, there is
+still no unified scheme for terminating a line that is portable
+between Unix, DOS/Win, and Macintosh, except to terminate \fIALL\fR line
+ends with "\e015\e012", and strip what you don't need from the output.
+This applies especially to socket I/O and autoflushing, discussed
+next.
+.IP "flushing output" 4
+.IX Item "flushing output"
+If you expect characters to get to your device when you \f(CWprint()\fR them,
+you'll want to autoflush that filehandle. You can use \f(CWselect()\fR
+and the \f(CW$|\fR variable to control autoflushing (see "$|" in perlvar
+and "select" in perlfunc, or perlfaq5, "How do I flush/unbuffer an
+output filehandle? Why must I do this?"):
+.Sp
+.Vb 3
+\&    my $old_handle = select($dev_fh);
+\&    $| = 1;
+\&    select($old_handle);
+.Ve
+.Sp
+You'll also see code that does this without a temporary variable, as in
+.Sp
+.Vb 1
+\&    select((select($deb_handle), $| = 1)[0]);
+.Ve
+.Sp
+Or if you don't mind pulling in a few thousand lines
+of code just because you're afraid of a little \f(CW$|\fR variable:
+.Sp
+.Vb 2
+\&    use IO::Handle;
+\&    $dev_fh\->autoflush(1);
+.Ve
+.Sp
+As mentioned in the previous item, this still doesn't work when using
+socket I/O between Unix and Macintosh. You'll need to hard code your
+line terminators, in that case.
+.IP "non-blocking input" 4
+.IX Item "non-blocking input"
+If you are doing a blocking \f(CWread()\fR or \f(CWsysread()\fR, you'll have to
+arrange for an alarm handler to provide a timeout (see
+"alarm" in perlfunc). If you have a non-blocking open, you'll likely
+have a non-blocking read, which means you may have to use a 4\-arg
+\&\f(CWselect()\fR to determine whether I/O is ready on that device (see
+"select" in perlfunc.
+.PP
+While trying to read from his caller-id box, the notorious Jamie
+Zawinski \f(CW\*(C`<jwz@netscape.com>\*(C'\fR, after much gnashing of teeth and
+fighting with \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, POSIX's \f(CW\*(C`tcgetattr\*(C'\fR business,
+and various other functions that go bump in the night, finally came up
+with this:
+.PP
+.Vb 10
+\&    sub open_modem {
+\&        use IPC::Open2;
+\&        my $stty = \`/bin/stty \-g\`;
+\&        open2( \e*MODEM_IN, \e*MODEM_OUT, "cu \-l$modem_device \-s2400 2>&1");
+\&        # starting cu hoses /dev/tty\*(Aqs stty settings, even when it has
+\&        # been opened on a pipe...
+\&        system("/bin/stty $stty");
+\&        $_ = <MODEM_IN>;
+\&        chomp;
+\&        if ( !m/^Connected/ ) {
+\&            print STDERR "$0: cu printed \`$_\*(Aq instead of \`Connected\*(Aq\en";
+\&        }
+\&    }
+.Ve
+.SS "How do I decode encrypted password files?"
+.IX Subsection "How do I decode encrypted password files?"
+You spend lots and lots of money on dedicated hardware, but this is
+bound to get you talked about.
+.PP
+Seriously, you can't if they are Unix password files\-\-the Unix
+password system employs one-way encryption. It's more like hashing
+than encryption. The best you can do is check whether something else
+hashes to the same string. You can't turn a hash back into the
+original string. Programs like Crack can forcibly (and intelligently)
+try to guess passwords, but don't (can't) guarantee quick success.
+.PP
+If you're worried about users selecting bad passwords, you should
+proactively check when they try to change their password (by modifying
+\&\fBpasswd\fR\|(1), for example).
+.SS "How do I start a process in the background?"
+.IX Subsection "How do I start a process in the background?"
+(contributed by brian d foy)
+.PP
+There's not a single way to run code in the background so you don't
+have to wait for it to finish before your program moves on to other
+tasks. Process management depends on your particular operating system,
+and many of the techniques are covered in perlipc.
+.PP
+Several CPAN modules may be able to help, including IPC::Open2 or
+IPC::Open3, IPC::Run, Parallel::Jobs,
+Parallel::ForkManager, POE, Proc::Background, and
+Win32::Process. There are many other modules you might use, so
+check those namespaces for other options too.
+.PP
+If you are on a Unix-like system, you might be able to get away with a
+system call where you put an \f(CW\*(C`&\*(C'\fR on the end of the command:
+.PP
+.Vb 1
+\&    system("cmd &")
+.Ve
+.PP
+You can also try using \f(CW\*(C`fork\*(C'\fR, as described in perlfunc (although
+this is the same thing that many of the modules will do for you).
+.IP "STDIN, STDOUT, and STDERR are shared" 4
+.IX Item "STDIN, STDOUT, and STDERR are shared"
+Both the main process and the backgrounded one (the "child" process)
+share the same STDIN, STDOUT and STDERR filehandles. If both try to
+access them at once, strange things can happen. You may want to close
+or reopen these for the child. You can get around this with
+\&\f(CW\*(C`open\*(C'\fRing a pipe (see "open" in perlfunc) but on some systems this
+means that the child process cannot outlive the parent.
+.IP Signals 4
+.IX Item "Signals"
+You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too.
+SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is
+sent when you write to a filehandle whose child process has closed (an
+untrapped SIGPIPE can cause your program to silently die). This is
+not an issue with \f(CWsystem("cmd&")\fR.
+.IP Zombies 4
+.IX Item "Zombies"
+You have to be prepared to "reap" the child process when it finishes.
+.Sp
+.Vb 1
+\&    $SIG{CHLD} = sub { wait };
+\&
+\&    $SIG{CHLD} = \*(AqIGNORE\*(Aq;
+.Ve
+.Sp
+You can also use a double fork. You immediately \f(CWwait()\fR for your
+first child, and the init daemon will \f(CWwait()\fR for your grandchild once
+it exits.
+.Sp
+.Vb 8
+\&    unless ($pid = fork) {
+\&        unless (fork) {
+\&            exec "what you really wanna do";
+\&            die "exec failed!";
+\&        }
+\&        exit 0;
+\&    }
+\&    waitpid($pid, 0);
+.Ve
+.Sp
+See "Signals" in perlipc for other examples of code to do this.
+Zombies are not an issue with \f(CW\*(C`system("prog &")\*(C'\fR.
+.SS "How do I trap control characters/signals?"
+.IX Subsection "How do I trap control characters/signals?"
+You don't actually "trap" a control character. Instead, that character
+generates a signal which is sent to your terminal's currently
+foregrounded process group, which you then trap in your process.
+Signals are documented in "Signals" in perlipc and the
+section on "Signals" in the Camel.
+.PP
+You can set the values of the \f(CW%SIG\fR hash to be the functions you want
+to handle the signal. After perl catches the signal, it looks in \f(CW%SIG\fR
+for a key with the same name as the signal, then calls the subroutine
+value for that key.
+.PP
+.Vb 1
+\&    # as an anonymous subroutine
+\&
+\&    $SIG{INT} = sub { syswrite(STDERR, "ouch\en", 5 ) };
+\&
+\&    # or a reference to a function
+\&
+\&    $SIG{INT} = \e&ouch;
+\&
+\&    # or the name of the function as a string
+\&
+\&    $SIG{INT} = "ouch";
+.Ve
+.PP
+Perl versions before 5.8 had in its C source code signal handlers which
+would catch the signal and possibly run a Perl function that you had set
+in \f(CW%SIG\fR. This violated the rules of signal handling at that level
+causing perl to dump core. Since version 5.8.0, perl looks at \f(CW%SIG\fR
+\&\fBafter\fR the signal has been caught, rather than while it is being caught.
+Previous versions of this answer were incorrect.
+.SS "How do I modify the shadow password file on a Unix system?"
+.IX Subsection "How do I modify the shadow password file on a Unix system?"
+If perl was installed correctly and your shadow library was written
+properly, the \f(CW\*(C`getpw*()\*(C'\fR functions described in perlfunc should in
+theory provide (read-only) access to entries in the shadow password
+file. To change the file, make a new shadow password file (the format
+varies from system to system\-\-see \fBpasswd\fR\|(1) for specifics) and use
+\&\f(CWpwd_mkdb(8)\fR to install it (see \fBpwd_mkdb\fR\|(8) for more details).
+.SS "How do I set the time and date?"
+.IX Subsection "How do I set the time and date?"
+Assuming you're running under sufficient permissions, you should be
+able to set the system-wide date and time by running the \f(CWdate(1)\fR
+program. (There is no way to set the time and date on a per-process
+basis.)  This mechanism will work for Unix, MS-DOS, Windows, and NT;
+the VMS equivalent is \f(CW\*(C`set time\*(C'\fR.
+.PP
+However, if all you want to do is change your time zone, you can
+probably get away with setting an environment variable:
+.PP
+.Vb 3
+\&    $ENV{TZ} = "MST7MDT";           # Unixish
+\&    $ENV{\*(AqSYS$TIMEZONE_DIFFERENTIAL\*(Aq}="\-5" # vms
+\&    system(\*(Aqtrn\*(Aq, \*(Aqcomp.lang.perl.misc\*(Aq);
+.Ve
+.SS "How can I \fBsleep()\fP or \fBalarm()\fP for under a second?"
+.IX Xref "Time::HiRes BSD::Itimer sleep select"
+.IX Subsection "How can I sleep() or alarm() for under a second?"
+If you want finer granularity than the 1 second that the \f(CWsleep()\fR
+function provides, the easiest way is to use the \f(CWselect()\fR function as
+documented in "select" in perlfunc. Try the Time::HiRes and
+the BSD::Itimer modules (available from CPAN, and starting from
+Perl 5.8 Time::HiRes is part of the standard distribution).
+.SS "How can I measure time under a second?"
+.IX Xref "Time::HiRes BSD::Itimer sleep select"
+.IX Subsection "How can I measure time under a second?"
+(contributed by brian d foy)
+.PP
+The Time::HiRes module (part of the standard distribution as of
+Perl 5.8) measures time with the \f(CWgettimeofday()\fR system call, which
+returns the time in microseconds since the epoch. If you can't install
+Time::HiRes for older Perls and you are on a Unixish system, you
+may be able to call \f(CWgettimeofday(2)\fR directly. See
+"syscall" in perlfunc.
+.SS "How can I do an \fBatexit()\fP or \fBsetjmp()\fP/\fBlongjmp()\fP? (Exception handling)"
+.IX Subsection "How can I do an atexit() or setjmp()/longjmp()? (Exception handling)"
+You can use the \f(CW\*(C`END\*(C'\fR block to simulate \f(CWatexit()\fR. Each package's
+\&\f(CW\*(C`END\*(C'\fR block is called when the program or thread ends. See the perlmod
+manpage for more details about \f(CW\*(C`END\*(C'\fR blocks.
+.PP
+For example, you can use this to make sure your filter program managed
+to finish its output without filling up the disk:
+.PP
+.Vb 3
+\&    END {
+\&        close(STDOUT) || die "stdout close failed: $!";
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`END\*(C'\fR block isn't called when untrapped signals kill the program,
+though, so if you use \f(CW\*(C`END\*(C'\fR blocks you should also use
+.PP
+.Vb 1
+\&    use sigtrap qw(die normal\-signals);
+.Ve
+.PP
+Perl's exception-handling mechanism is its \f(CWeval()\fR operator. You
+can use \f(CWeval()\fR as \f(CW\*(C`setjmp\*(C'\fR and \f(CWdie()\fR as \f(CW\*(C`longjmp\*(C'\fR. For
+details of this, see the section on signals, especially the time-out
+handler for a blocking \f(CWflock()\fR in "Signals" in perlipc or the
+section on "Signals" in \fIProgramming Perl\fR.
+.PP
+If exception handling is all you're interested in, use one of the
+many CPAN modules that handle exceptions, such as Try::Tiny.
+.PP
+If you want the \f(CWatexit()\fR syntax (and an \f(CWrmexit()\fR as well), try the
+\&\f(CW\*(C`AtExit\*(C'\fR module available from CPAN.
+.SS "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?"
+.IX Subsection "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?"
+Some Sys-V based systems, notably Solaris 2.X, redefined some of the
+standard socket constants. Since these were constant across all
+architectures, they were often hardwired into perl code. The proper
+way to deal with this is to "use Socket" to get the correct values.
+.PP
+Note that even though SunOS and Solaris are binary compatible, these
+values are different. Go figure.
+.SS "How can I call my system's unique C functions from Perl?"
+.IX Subsection "How can I call my system's unique C functions from Perl?"
+In most cases, you write an external module to do it\-\-see the answer
+to "Where can I learn about linking C with Perl? [h2xs, xsubpp]".
+However, if the function is a system call, and your system supports
+\&\f(CWsyscall()\fR, you can use the \f(CW\*(C`syscall\*(C'\fR function (documented in
+perlfunc).
+.PP
+Remember to check the modules that came with your distribution, and
+CPAN as well\-\-someone may already have written a module to do it. On
+Windows, try Win32::API. On Macs, try Mac::Carbon. If no module
+has an interface to the C function, you can inline a bit of C in your
+Perl source with Inline::C.
+.SS "Where do I get the include files to do \fBioctl()\fP or \fBsyscall()\fP?"
+.IX Subsection "Where do I get the include files to do ioctl() or syscall()?"
+Historically, these would be generated by the h2ph tool, part of the
+standard perl distribution. This program converts \f(CWcpp(1)\fR directives
+in C header files to files containing subroutine definitions, like
+\&\f(CWSYS_getitimer()\fR, which you can use as arguments to your functions.
+It doesn't work perfectly, but it usually gets most of the job done.
+Simple files like \fIerrno.h\fR, \fIsyscall.h\fR, and \fIsocket.h\fR were fine,
+but the hard ones like \fIioctl.h\fR nearly always need to be hand-edited.
+Here's how to install the *.ph files:
+.PP
+.Vb 3
+\&    1. Become the super\-user
+\&    2. cd /usr/include
+\&    3. h2ph *.h */*.h
+.Ve
+.PP
+If your system supports dynamic loading, for reasons of portability and
+sanity you probably ought to use h2xs (also part of the standard perl
+distribution). This tool converts C header files to Perl extensions.
+See perlxstut for how to get started with h2xs.
+.PP
+If your system doesn't support dynamic loading, you still probably
+ought to use h2xs. See perlxstut and ExtUtils::MakeMaker for
+more information (in brief, just use \fBmake perl\fR instead of a plain
+\&\fBmake\fR to rebuild perl with a new static extension).
+.SS "Why do setuid perl scripts complain about kernel problems?"
+.IX Subsection "Why do setuid perl scripts complain about kernel problems?"
+Some operating systems have bugs in the kernel that make setuid
+scripts inherently insecure. Perl gives you a number of options
+(described in perlsec) to work around such systems.
+.SS "How can I open a pipe both to and from a command?"
+.IX Subsection "How can I open a pipe both to and from a command?"
+The IPC::Open2 module (part of the standard perl distribution) is
+an easy-to-use approach that internally uses \f(CWpipe()\fR, \f(CWfork()\fR, and
+\&\f(CWexec()\fR to do the job. Make sure you read the deadlock warnings in
+its documentation, though (see IPC::Open2). See
+"Bidirectional Communication with Another Process" in perlipc and
+"Bidirectional Communication with Yourself" in perlipc
+.PP
+You may also use the IPC::Open3 module (part of the standard perl
+distribution), but be warned that it has a different order of
+arguments from IPC::Open2 (see IPC::Open3).
+.SS "Why can't I get the output of a command with \fBsystem()\fP?"
+.IX Subsection "Why can't I get the output of a command with system()?"
+You're confusing the purpose of \f(CWsystem()\fR and backticks (``). \f(CWsystem()\fR
+runs a command and returns exit status information (as a 16 bit value:
+the low 7 bits are the signal the process died from, if any, and
+the high 8 bits are the actual exit value). Backticks (``) run a
+command and return what it sent to STDOUT.
+.PP
+.Vb 2
+\&    my $exit_status   = system("mail\-users");
+\&    my $output_string = \`ls\`;
+.Ve
+.SS "How can I capture STDERR from an external command?"
+.IX Subsection "How can I capture STDERR from an external command?"
+There are three basic ways of running external commands:
+.PP
+.Vb 3
+\&    system $cmd;        # using system()
+\&    my $output = \`$cmd\`;        # using backticks (\`\`)
+\&    open (my $pipe_fh, "$cmd |");    # using open()
+.Ve
+.PP
+With \f(CWsystem()\fR, both STDOUT and STDERR will go the same place as the
+script's STDOUT and STDERR, unless the \f(CWsystem()\fR command redirects them.
+Backticks and \f(CWopen()\fR read \fBonly\fR the STDOUT of your command.
+.PP
+You can also use the \f(CWopen3()\fR function from IPC::Open3. Benjamin
+Goldberg provides some sample code:
+.PP
+To capture a program's STDOUT, but discard its STDERR:
+.PP
+.Vb 7
+\&    use IPC::Open3;
+\&    use File::Spec;
+\&    my $in = \*(Aq\*(Aq;
+\&    open(NULL, ">", File::Spec\->devnull);
+\&    my $pid = open3($in, \e*PH, ">&NULL", "cmd");
+\&    while( <PH> ) { }
+\&    waitpid($pid, 0);
+.Ve
+.PP
+To capture a program's STDERR, but discard its STDOUT:
+.PP
+.Vb 7
+\&    use IPC::Open3;
+\&    use File::Spec;
+\&    my $in = \*(Aq\*(Aq;
+\&    open(NULL, ">", File::Spec\->devnull);
+\&    my $pid = open3($in, ">&NULL", \e*PH, "cmd");
+\&    while( <PH> ) { }
+\&    waitpid($pid, 0);
+.Ve
+.PP
+To capture a program's STDERR, and let its STDOUT go to our own STDERR:
+.PP
+.Vb 5
+\&    use IPC::Open3;
+\&    my $in = \*(Aq\*(Aq;
+\&    my $pid = open3($in, ">&STDERR", \e*PH, "cmd");
+\&    while( <PH> ) { }
+\&    waitpid($pid, 0);
+.Ve
+.PP
+To read both a command's STDOUT and its STDERR separately, you can
+redirect them to temp files, let the command run, then read the temp
+files:
+.PP
+.Vb 10
+\&    use IPC::Open3;
+\&    use IO::File;
+\&    my $in = \*(Aq\*(Aq;
+\&    local *CATCHOUT = IO::File\->new_tmpfile;
+\&    local *CATCHERR = IO::File\->new_tmpfile;
+\&    my $pid = open3($in, ">&CATCHOUT", ">&CATCHERR", "cmd");
+\&    waitpid($pid, 0);
+\&    seek $_, 0, 0 for \e*CATCHOUT, \e*CATCHERR;
+\&    while( <CATCHOUT> ) {}
+\&    while( <CATCHERR> ) {}
+.Ve
+.PP
+But there's no real need for \fBboth\fR to be tempfiles... the following
+should work just as well, without deadlocking:
+.PP
+.Vb 9
+\&    use IPC::Open3;
+\&    my $in = \*(Aq\*(Aq;
+\&    use IO::File;
+\&    local *CATCHERR = IO::File\->new_tmpfile;
+\&    my $pid = open3($in, \e*CATCHOUT, ">&CATCHERR", "cmd");
+\&    while( <CATCHOUT> ) {}
+\&    waitpid($pid, 0);
+\&    seek CATCHERR, 0, 0;
+\&    while( <CATCHERR> ) {}
+.Ve
+.PP
+And it'll be faster, too, since we can begin processing the program's
+stdout immediately, rather than waiting for the program to finish.
+.PP
+With any of these, you can change file descriptors before the call:
+.PP
+.Vb 2
+\&    open(STDOUT, ">logfile");
+\&    system("ls");
+.Ve
+.PP
+or you can use Bourne shell file-descriptor redirection:
+.PP
+.Vb 2
+\&    $output = \`$cmd 2>some_file\`;
+\&    open (PIPE, "cmd 2>some_file |");
+.Ve
+.PP
+You can also use file-descriptor redirection to make STDERR a
+duplicate of STDOUT:
+.PP
+.Vb 2
+\&    $output = \`$cmd 2>&1\`;
+\&    open (PIPE, "cmd 2>&1 |");
+.Ve
+.PP
+Note that you \fIcannot\fR simply open STDERR to be a dup of STDOUT
+in your Perl program and avoid calling the shell to do the redirection.
+This doesn't work:
+.PP
+.Vb 2
+\&    open(STDERR, ">&STDOUT");
+\&    $alloutput = \`cmd args\`;  # stderr still escapes
+.Ve
+.PP
+This fails because the \f(CWopen()\fR makes STDERR go to where STDOUT was
+going at the time of the \f(CWopen()\fR. The backticks then make STDOUT go to
+a string, but don't change STDERR (which still goes to the old
+STDOUT).
+.PP
+Note that you \fImust\fR use Bourne shell (\f(CWsh(1)\fR) redirection syntax in
+backticks, not \f(CWcsh(1)\fR!  Details on why Perl's \f(CWsystem()\fR and backtick
+and pipe opens all use the Bourne shell are in the
+\&\fIversus/csh.whynot\fR article in the "Far More Than You Ever Wanted To
+Know" collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> . To
+capture a command's STDERR and STDOUT together:
+.PP
+.Vb 3
+\&    $output = \`cmd 2>&1\`;                       # either with backticks
+\&    $pid = open(PH, "cmd 2>&1 |");              # or with an open pipe
+\&    while (<PH>) { }                            #    plus a read
+.Ve
+.PP
+To capture a command's STDOUT but discard its STDERR:
+.PP
+.Vb 3
+\&    $output = \`cmd 2>/dev/null\`;                # either with backticks
+\&    $pid = open(PH, "cmd 2>/dev/null |");       # or with an open pipe
+\&    while (<PH>) { }                            #    plus a read
+.Ve
+.PP
+To capture a command's STDERR but discard its STDOUT:
+.PP
+.Vb 3
+\&    $output = \`cmd 2>&1 1>/dev/null\`;           # either with backticks
+\&    $pid = open(PH, "cmd 2>&1 1>/dev/null |");  # or with an open pipe
+\&    while (<PH>) { }                            #    plus a read
+.Ve
+.PP
+To exchange a command's STDOUT and STDERR in order to capture the STDERR
+but leave its STDOUT to come out our old STDERR:
+.PP
+.Vb 3
+\&    $output = \`cmd 3>&1 1>&2 2>&3 3>&\-\`;        # either with backticks
+\&    $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&\-|");# or with an open pipe
+\&    while (<PH>) { }                            #    plus a read
+.Ve
+.PP
+To read both a command's STDOUT and its STDERR separately, it's easiest
+to redirect them separately to files, and then read from those files
+when the program is done:
+.PP
+.Vb 1
+\&    system("program args 1>program.stdout 2>program.stderr");
+.Ve
+.PP
+Ordering is important in all these examples. That's because the shell
+processes file descriptor redirections in strictly left to right order.
+.PP
+.Vb 2
+\&    system("prog args 1>tmpfile 2>&1");
+\&    system("prog args 2>&1 1>tmpfile");
+.Ve
+.PP
+The first command sends both standard out and standard error to the
+temporary file. The second command sends only the old standard output
+there, and the old standard error shows up on the old standard out.
+.SS "Why doesn't \fBopen()\fP return an error when a pipe open fails?"
+.IX Subsection "Why doesn't open() return an error when a pipe open fails?"
+If the second argument to a piped \f(CWopen()\fR contains shell
+metacharacters, perl \f(CWfork()\fRs, then \f(CWexec()\fRs a shell to decode the
+metacharacters and eventually run the desired program. If the program
+couldn't be run, it's the shell that gets the message, not Perl. All
+your Perl program can find out is whether the shell itself could be
+successfully started. You can still capture the shell's STDERR and
+check it for error messages. See "How can I capture STDERR from an
+external command?" elsewhere in this document, or use the
+IPC::Open3 module.
+.PP
+If there are no shell metacharacters in the argument of \f(CWopen()\fR, Perl
+runs the command directly, without using the shell, and can correctly
+report whether the command started.
+.SS "What's wrong with using backticks in a void context?"
+.IX Subsection "What's wrong with using backticks in a void context?"
+Strictly speaking, nothing. Stylistically speaking, it's not a good
+way to write maintainable code. Perl has several operators for
+running external commands. Backticks are one; they collect the output
+from the command for use in your program. The \f(CW\*(C`system\*(C'\fR function is
+another; it doesn't do this.
+.PP
+Writing backticks in your program sends a clear message to the readers
+of your code that you wanted to collect the output of the command.
+Why send a clear message that isn't true?
+.PP
+Consider this line:
+.PP
+.Vb 1
+\&    \`cat /etc/termcap\`;
+.Ve
+.PP
+You forgot to check \f(CW$?\fR to see whether the program even ran
+correctly. Even if you wrote
+.PP
+.Vb 1
+\&    print \`cat /etc/termcap\`;
+.Ve
+.PP
+this code could and probably should be written as
+.PP
+.Vb 2
+\&    system("cat /etc/termcap") == 0
+\&    or die "cat program failed!";
+.Ve
+.PP
+which will echo the cat command's output as it is generated, instead
+of waiting until the program has completed to print it out. It also
+checks the return value.
+.PP
+\&\f(CW\*(C`system\*(C'\fR also provides direct control over whether shell wildcard
+processing may take place, whereas backticks do not.
+.SS "How can I call backticks without shell processing?"
+.IX Subsection "How can I call backticks without shell processing?"
+This is a bit tricky. You can't simply write the command
+like this:
+.PP
+.Vb 1
+\&    @ok = \`grep @opts \*(Aq$search_string\*(Aq @filenames\`;
+.Ve
+.PP
+As of Perl 5.8.0, you can use \f(CWopen()\fR with multiple arguments.
+Just like the list forms of \f(CWsystem()\fR and \f(CWexec()\fR, no shell
+escapes happen.
+.PP
+.Vb 3
+\&    open( GREP, "\-|", \*(Aqgrep\*(Aq, @opts, $search_string, @filenames );
+\&    chomp(@ok = <GREP>);
+\&    close GREP;
+.Ve
+.PP
+You can also:
+.PP
+.Vb 10
+\&    my @ok = ();
+\&    if (open(GREP, "\-|")) {
+\&        while (<GREP>) {
+\&            chomp;
+\&            push(@ok, $_);
+\&        }
+\&        close GREP;
+\&    } else {
+\&        exec \*(Aqgrep\*(Aq, @opts, $search_string, @filenames;
+\&    }
+.Ve
+.PP
+Just as with \f(CWsystem()\fR, no shell escapes happen when you \f(CWexec()\fR a
+list. Further examples of this can be found in "Safe Pipe
+Opens" in perlipc.
+.PP
+Note that if you're using Windows, no solution to this vexing issue is
+even possible. Even though Perl emulates \f(CWfork()\fR, you'll still be
+stuck, because Windows does not have an argc/argv\-style API.
+.SS "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?"
+.IX Subsection "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?"
+This happens only if your perl is compiled to use stdio instead of
+perlio, which is the default. Some (maybe all?) stdios set error and
+eof flags that you may need to clear. The POSIX module defines
+\&\f(CWclearerr()\fR that you can use. That is the technically correct way to
+do it. Here are some less reliable workarounds:
+.IP 1. 4
+Try keeping around the seekpointer and go there, like this:
+.Sp
+.Vb 2
+\&    my $where = tell($log_fh);
+\&    seek($log_fh, $where, 0);
+.Ve
+.IP 2. 4
+If that doesn't work, try seeking to a different part of the file and
+then back.
+.IP 3. 4
+If that doesn't work, try seeking to a different part of
+the file, reading something, and then seeking back.
+.IP 4. 4
+If that doesn't work, give up on your stdio package and use sysread.
+.SS "How can I convert my shell script to perl?"
+.IX Subsection "How can I convert my shell script to perl?"
+Learn Perl and rewrite it. Seriously, there's no simple converter.
+Things that are awkward to do in the shell are easy to do in Perl, and
+this very awkwardness is what would make a shell\->perl converter
+nigh-on impossible to write. By rewriting it, you'll think about what
+you're really trying to do, and hopefully will escape the shell's
+pipeline datastream paradigm, which while convenient for some matters,
+causes many inefficiencies.
+.SS "Can I use perl to run a telnet or ftp session?"
+.IX Subsection "Can I use perl to run a telnet or ftp session?"
+Try the Net::FTP, TCP::Client, and Net::Telnet modules
+(available from CPAN).
+<http://www.cpan.org/scripts/netstuff/telnet.emul.shar> will also help
+for emulating the telnet protocol, but Net::Telnet is quite
+probably easier to use.
+.PP
+If all you want to do is pretend to be telnet but don't need
+the initial telnet handshaking, then the standard dual-process
+approach will suffice:
+.PP
+.Vb 12
+\&    use IO::Socket;             # new in 5.004
+\&    my $handle = IO::Socket::INET\->new(\*(Aqwww.perl.com:80\*(Aq)
+\&        or die "can\*(Aqt connect to port 80 on www.perl.com $!";
+\&    $handle\->autoflush(1);
+\&    if (fork()) {               # XXX: undef means failure
+\&        select($handle);
+\&        print while <STDIN>;    # everything from stdin to socket
+\&    } else {
+\&        print while <$handle>;  # everything from socket to stdout
+\&    }
+\&    close $handle;
+\&    exit;
+.Ve
+.SS "How can I write expect in Perl?"
+.IX Subsection "How can I write expect in Perl?"
+Once upon a time, there was a library called \fIchat2.pl\fR (part of the
+standard perl distribution), which never really got finished. If you
+find it somewhere, \fIdon't use it\fR. These days, your best bet is to
+look at the Expect module available from CPAN, which also requires two
+other modules from CPAN, IO::Pty and IO::Stty.
+.SS "Is there a way to hide perl's command line from programs such as ""ps""?"
+.IX Subsection "Is there a way to hide perl's command line from programs such as ""ps""?"
+First of all note that if you're doing this for security reasons (to
+avoid people seeing passwords, for example) then you should rewrite
+your program so that critical information is never given as an
+argument. Hiding the arguments won't make your program completely
+secure.
+.PP
+To actually alter the visible command line, you can assign to the
+variable \f(CW$0\fR as documented in perlvar. This won't work on all
+operating systems, though. Daemon programs like sendmail place their
+state there, as in:
+.PP
+.Vb 1
+\&    $0 = "orcus [accepting connections]";
+.Ve
+.SS "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?"
+.IX Subsection "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?"
+.IP Unix 4
+.IX Item "Unix"
+In the strictest sense, it can't be done\-\-the script executes as a
+different process from the shell it was started from. Changes to a
+process are not reflected in its parent\-\-only in any children
+created after the change. There is shell magic that may allow you to
+fake it by \f(CWeval()\fRing the script's output in your shell; check out the
+comp.unix.questions FAQ for details.
+.SS "How do I close a process's filehandle without waiting for it to complete?"
+.IX Subsection "How do I close a process's filehandle without waiting for it to complete?"
+Assuming your system supports such things, just send an appropriate signal
+to the process (see "kill" in perlfunc). It's common to first send a TERM
+signal, wait a little bit, and then send a KILL signal to finish it off.
+.SS "How do I fork a daemon process?"
+.IX Subsection "How do I fork a daemon process?"
+If by daemon process you mean one that's detached (disassociated from
+its tty), then the following process is reported to work on most
+Unixish systems. Non-Unix users should check their Your_OS::Process
+module for other solutions.
+.IP \(bu 4
+Open /dev/tty and use the TIOCNOTTY ioctl on it. See \fBtty\fR\|(1)
+for details. Or better yet, you can just use the \f(CWPOSIX::setsid()\fR
+function, so you don't have to worry about process groups.
+.IP \(bu 4
+Change directory to /
+.IP \(bu 4
+Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
+tty.
+.IP \(bu 4
+Background yourself like this:
+.Sp
+.Vb 1
+\&    fork && exit;
+.Ve
+.PP
+The Proc::Daemon module, available from CPAN, provides a function to
+perform these actions for you.
+.SS "How do I find out if I'm running interactively or not?"
+.IX Subsection "How do I find out if I'm running interactively or not?"
+(contributed by brian d foy)
+.PP
+This is a difficult question to answer, and the best answer is
+only a guess.
+.PP
+What do you really want to know? If you merely want to know if one of
+your filehandles is connected to a terminal, you can try the \f(CW\*(C`\-t\*(C'\fR
+file test:
+.PP
+.Vb 3
+\&    if( \-t STDOUT ) {
+\&        print "I\*(Aqm connected to a terminal!\en";
+\&    }
+.Ve
+.PP
+However, you might be out of luck if you expect that means there is a
+real person on the other side. With the Expect module, another
+program can pretend to be a person. The program might even come close
+to passing the Turing test.
+.PP
+The IO::Interactive module does the best it can to give you an
+answer. Its \f(CW\*(C`is_interactive\*(C'\fR function returns an output filehandle;
+that filehandle points to standard output if the module thinks the
+session is interactive. Otherwise, the filehandle is a null handle
+that simply discards the output:
+.PP
+.Vb 1
+\&    use IO::Interactive;
+\&
+\&    print { is_interactive } "I might go to standard output!\en";
+.Ve
+.PP
+This still doesn't guarantee that a real person is answering your
+prompts or reading your output.
+.PP
+If you want to know how to handle automated testing for your
+distribution, you can check the environment. The CPAN
+Testers, for instance, set the value of \f(CW\*(C`AUTOMATED_TESTING\*(C'\fR:
+.PP
+.Vb 3
+\&    unless( $ENV{AUTOMATED_TESTING} ) {
+\&        print "Hello interactive tester!\en";
+\&    }
+.Ve
+.SS "How do I timeout a slow event?"
+.IX Subsection "How do I timeout a slow event?"
+Use the \f(CWalarm()\fR function, probably in conjunction with a signal
+handler, as documented in "Signals" in perlipc and the section on
+"Signals" in the Camel. You may instead use the more flexible
+Sys::AlarmCall module available from CPAN.
+.PP
+The \f(CWalarm()\fR function is not implemented on all versions of Windows.
+Check the documentation for your specific version of Perl.
+.SS "How do I set CPU limits?"
+.IX Xref "BSD::Resource limit CPU"
+.IX Subsection "How do I set CPU limits?"
+(contributed by Xho)
+.PP
+Use the BSD::Resource module from CPAN. As an example:
+.PP
+.Vb 2
+\&    use BSD::Resource;
+\&    setrlimit(RLIMIT_CPU,10,20) or die $!;
+.Ve
+.PP
+This sets the soft and hard limits to 10 and 20 seconds, respectively.
+After 10 seconds of time spent running on the CPU (not "wall" time),
+the process will be sent a signal (XCPU on some systems) which, if not
+trapped, will cause the process to terminate. If that signal is
+trapped, then after 10 more seconds (20 seconds in total) the process
+will be killed with a non-trappable signal.
+.PP
+See the BSD::Resource and your systems documentation for the gory
+details.
+.SS "How do I avoid zombies on a Unix system?"
+.IX Subsection "How do I avoid zombies on a Unix system?"
+Use the reaper code from "Signals" in perlipc to call \f(CWwait()\fR when a
+SIGCHLD is received, or else use the double-fork technique described
+in "How do I start a process in the background?" in perlfaq8.
+.SS "How do I use an SQL database?"
+.IX Subsection "How do I use an SQL database?"
+The DBI module provides an abstract interface to most database
+servers and types, including Oracle, DB2, Sybase, mysql, Postgresql,
+ODBC, and flat files. The DBI module accesses each database type
+through a database driver, or DBD. You can see a complete list of
+available drivers on CPAN: <http://www.cpan.org/modules/by\-module/DBD/> .
+You can read more about DBI on <http://dbi.perl.org/> .
+.PP
+Other modules provide more specific access: Win32::ODBC, Alzabo,
+\&\f(CW\*(C`iodbc\*(C'\fR, and others found on CPAN Search: <https://metacpan.org/> .
+.SS "How do I make a \fBsystem()\fP exit on control-C?"
+.IX Subsection "How do I make a system() exit on control-C?"
+You can't. You need to imitate the \f(CWsystem()\fR call (see perlipc for
+sample code) and then have a signal handler for the INT signal that
+passes the signal on to the subprocess. Or you can check for it:
+.PP
+.Vb 2
+\&    $rc = system($cmd);
+\&    if ($rc & 127) { die "signal death" }
+.Ve
+.SS "How do I open a file without blocking?"
+.IX Subsection "How do I open a file without blocking?"
+If you're lucky enough to be using a system that supports
+non-blocking reads (most Unixish systems do), you need only to use the
+\&\f(CW\*(C`O_NDELAY\*(C'\fR or \f(CW\*(C`O_NONBLOCK\*(C'\fR flag from the \f(CW\*(C`Fcntl\*(C'\fR module in conjunction with
+\&\f(CWsysopen()\fR:
+.PP
+.Vb 3
+\&    use Fcntl;
+\&    sysopen(my $fh, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
+\&        or die "can\*(Aqt open /foo/somefile: $!":
+.Ve
+.SS "How do I tell the difference between errors from the shell and perl?"
+.IX Subsection "How do I tell the difference between errors from the shell and perl?"
+(answer contributed by brian d foy)
+.PP
+When you run a Perl script, something else is running the script for you,
+and that something else may output error messages. The script might
+emit its own warnings and error messages. Most of the time you cannot
+tell who said what.
+.PP
+You probably cannot fix the thing that runs perl, but you can change how
+perl outputs its warnings by defining a custom warning and die functions.
+.PP
+Consider this script, which has an error you may not notice immediately.
+.PP
+.Vb 1
+\&    #!/usr/locl/bin/perl
+\&
+\&    print "Hello World\en";
+.Ve
+.PP
+I get an error when I run this from my shell (which happens to be
+bash). That may look like perl forgot it has a \f(CWprint()\fR function,
+but my shebang line is not the path to perl, so the shell runs the
+script, and I get the error.
+.PP
+.Vb 2
+\&    $ ./test
+\&    ./test: line 3: print: command not found
+.Ve
+.PP
+A quick and dirty fix involves a little bit of code, but this may be all
+you need to figure out the problem.
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-w
+\&
+\&    BEGIN {
+\&        $SIG{_\|_WARN_\|_} = sub{ print STDERR "Perl: ", @_; };
+\&        $SIG{_\|_DIE_\|_}  = sub{ print STDERR "Perl: ", @_; exit 1};
+\&    }
+\&
+\&    $a = 1 + undef;
+\&    $x / 0;
+\&    _\|_END_\|_
+.Ve
+.PP
+The perl message comes out with "Perl" in front. The \f(CW\*(C`BEGIN\*(C'\fR block
+works at compile time so all of the compilation errors and warnings
+get the "Perl:" prefix too.
+.PP
+.Vb 7
+\&    Perl: Useless use of division (/) in void context at ./test line 9.
+\&    Perl: Name "main::a" used only once: possible typo at ./test line 8.
+\&    Perl: Name "main::x" used only once: possible typo at ./test line 9.
+\&    Perl: Use of uninitialized value in addition (+) at ./test line 8.
+\&    Perl: Use of uninitialized value in division (/) at ./test line 9.
+\&    Perl: Illegal division by zero at ./test line 9.
+\&    Perl: Illegal division by zero at \-e line 3.
+.Ve
+.PP
+If I don't see that "Perl:", it's not from perl.
+.PP
+You could also just know all the perl errors, and although there are
+some people who may know all of them, you probably don't. However, they
+all should be in the perldiag manpage. If you don't find the error in
+there, it probably isn't a perl error.
+.PP
+Looking up every message is not the easiest way, so let perl to do it
+for you. Use the diagnostics pragma with turns perl's normal messages
+into longer discussions on the topic.
+.PP
+.Vb 1
+\&    use diagnostics;
+.Ve
+.PP
+If you don't get a paragraph or two of expanded discussion, it
+might not be perl's message.
+.SS "How do I install a module from CPAN?"
+.IX Subsection "How do I install a module from CPAN?"
+(contributed by brian d foy)
+.PP
+The easiest way is to have a module also named CPAN do it for you by using
+the \f(CW\*(C`cpan\*(C'\fR command that comes with Perl. You can give it a list of modules
+to install:
+.PP
+.Vb 1
+\&    $ cpan IO::Interactive Getopt::Whatever
+.Ve
+.PP
+If you prefer \f(CW\*(C`CPANPLUS\*(C'\fR, it's just as easy:
+.PP
+.Vb 1
+\&    $ cpanp i IO::Interactive Getopt::Whatever
+.Ve
+.PP
+If you want to install a distribution from the current directory, you can
+tell \f(CW\*(C`CPAN.pm\*(C'\fR to install \f(CW\*(C`.\*(C'\fR (the full stop):
+.PP
+.Vb 1
+\&    $ cpan .
+.Ve
+.PP
+See the documentation for either of those commands to see what else
+you can do.
+.PP
+If you want to try to install a distribution by yourself, resolving
+all dependencies on your own, you follow one of two possible build
+paths.
+.PP
+For distributions that use \fIMakefile.PL\fR:
+.PP
+.Vb 2
+\&    $ perl Makefile.PL
+\&    $ make test install
+.Ve
+.PP
+For distributions that use \fIBuild.PL\fR:
+.PP
+.Vb 3
+\&    $ perl Build.PL
+\&    $ ./Build test
+\&    $ ./Build install
+.Ve
+.PP
+Some distributions may need to link to libraries or other third-party
+code and their build and installation sequences may be more complicated.
+Check any \fIREADME\fR or \fIINSTALL\fR files that you may find.
+.SS "What's the difference between require and use?"
+.IX Subsection "What's the difference between require and use?"
+(contributed by brian d foy)
+.PP
+Perl runs \f(CW\*(C`require\*(C'\fR statement at run-time. Once Perl loads, compiles,
+and runs the file, it doesn't do anything else. The \f(CW\*(C`use\*(C'\fR statement
+is the same as a \f(CW\*(C`require\*(C'\fR run at compile-time, but Perl also calls the
+\&\f(CW\*(C`import\*(C'\fR method for the loaded package. These two are the same:
+.PP
+.Vb 1
+\&    use MODULE qw(import list);
+\&
+\&    BEGIN {
+\&        require MODULE;
+\&        MODULE\->import(import list);
+\&    }
+.Ve
+.PP
+However, you can suppress the \f(CW\*(C`import\*(C'\fR by using an explicit, empty
+import list. Both of these still happen at compile-time:
+.PP
+.Vb 1
+\&    use MODULE ();
+\&
+\&    BEGIN {
+\&        require MODULE;
+\&    }
+.Ve
+.PP
+Since \f(CW\*(C`use\*(C'\fR will also call the \f(CW\*(C`import\*(C'\fR method, the actual value
+for \f(CW\*(C`MODULE\*(C'\fR must be a bareword. That is, \f(CW\*(C`use\*(C'\fR cannot load files
+by name, although \f(CW\*(C`require\*(C'\fR can:
+.PP
+.Vb 1
+\&    require "$ENV{HOME}/lib/Foo.pm"; # no @INC searching!
+.Ve
+.PP
+See the entry for \f(CW\*(C`use\*(C'\fR in perlfunc for more details.
+.SS "How do I keep my own module/library directory?"
+.IX Subsection "How do I keep my own module/library directory?"
+When you build modules, tell Perl where to install the modules.
+.PP
+If you want to install modules for your own use, the easiest way might
+be local::lib, which you can download from CPAN. It sets various
+installation settings for you, and uses those same settings within
+your programs.
+.PP
+If you want more flexibility, you need to configure your CPAN client
+for your particular situation.
+.PP
+For \f(CW\*(C`Makefile.PL\*(C'\fR\-based distributions, use the INSTALL_BASE option
+when generating Makefiles:
+.PP
+.Vb 1
+\&    perl Makefile.PL INSTALL_BASE=/mydir/perl
+.Ve
+.PP
+You can set this in your \f(CW\*(C`CPAN.pm\*(C'\fR configuration so modules
+automatically install in your private library directory when you use
+the CPAN.pm shell:
+.PP
+.Vb 3
+\&    % cpan
+\&    cpan> o conf makepl_arg INSTALL_BASE=/mydir/perl
+\&    cpan> o conf commit
+.Ve
+.PP
+For \f(CW\*(C`Build.PL\*(C'\fR\-based distributions, use the \-\-install_base option:
+.PP
+.Vb 1
+\&    perl Build.PL \-\-install_base /mydir/perl
+.Ve
+.PP
+You can configure \f(CW\*(C`CPAN.pm\*(C'\fR to automatically use this option too:
+.PP
+.Vb 3
+\&    % cpan
+\&    cpan> o conf mbuild_arg "\-\-install_base /mydir/perl"
+\&    cpan> o conf commit
+.Ve
+.PP
+INSTALL_BASE tells these tools to put your modules into
+\&\fI/mydir/perl/lib/perl5\fR. See "How do I add a directory to my
+include path (@INC) at runtime?" for details on how to run your newly
+installed modules.
+.PP
+There is one caveat with INSTALL_BASE, though, since it acts
+differently from the PREFIX and LIB settings that older versions of
+ExtUtils::MakeMaker advocated. INSTALL_BASE does not support
+installing modules for multiple versions of Perl or different
+architectures under the same directory. You should consider whether you
+really want that and, if you do, use the older PREFIX and LIB
+settings. See the ExtUtils::Makemaker documentation for more details.
+.SS "How do I add the directory my program lives in to the module/library search path?"
+.IX Subsection "How do I add the directory my program lives in to the module/library search path?"
+(contributed by brian d foy)
+.PP
+If you know the directory already, you can add it to \f(CW@INC\fR as you would
+for any other directory. You might \f(CW\*(C`use lib\*(C'\fR if you know the directory
+at compile time:
+.PP
+.Vb 1
+\&    use lib $directory;
+.Ve
+.PP
+The trick in this task is to find the directory. Before your script does
+anything else (such as a \f(CW\*(C`chdir\*(C'\fR), you can get the current working
+directory with the \f(CW\*(C`Cwd\*(C'\fR module, which comes with Perl:
+.PP
+.Vb 4
+\&    BEGIN {
+\&        use Cwd;
+\&        our $directory = cwd;
+\&    }
+\&
+\&    use lib $directory;
+.Ve
+.PP
+You can do a similar thing with the value of \f(CW$0\fR, which holds the
+script name. That might hold a relative path, but \f(CW\*(C`rel2abs\*(C'\fR can turn
+it into an absolute path. Once you have the
+.PP
+.Vb 3
+\&    BEGIN {
+\&        use File::Spec::Functions qw(rel2abs);
+\&        use File::Basename qw(dirname);
+\&
+\&        my $path   = rel2abs( $0 );
+\&        our $directory = dirname( $path );
+\&    }
+\&
+\&    use lib $directory;
+.Ve
+.PP
+The FindBin module, which comes with Perl, might work. It finds the
+directory of the currently running script and puts it in \f(CW$Bin\fR, which
+you can then use to construct the right library path:
+.PP
+.Vb 1
+\&    use FindBin qw($Bin);
+.Ve
+.PP
+You can also use local::lib to do much of the same thing. Install
+modules using local::lib's settings then use the module in your
+program:
+.PP
+.Vb 1
+\&     use local::lib; # sets up a local lib at ~/perl5
+.Ve
+.PP
+See the local::lib documentation for more details.
+.SS "How do I add a directory to my include path (@INC) at runtime?"
+.IX Subsection "How do I add a directory to my include path (@INC) at runtime?"
+Here are the suggested ways of modifying your include path, including
+environment variables, run-time switches, and in-code statements:
+.ie n .IP "the ""PERLLIB"" environment variable" 4
+.el .IP "the \f(CWPERLLIB\fR environment variable" 4
+.IX Item "the PERLLIB environment variable"
+.Vb 2
+\&    $ export PERLLIB=/path/to/my/dir
+\&    $ perl program.pl
+.Ve
+.ie n .IP "the ""PERL5LIB"" environment variable" 4
+.el .IP "the \f(CWPERL5LIB\fR environment variable" 4
+.IX Item "the PERL5LIB environment variable"
+.Vb 2
+\&    $ export PERL5LIB=/path/to/my/dir
+\&    $ perl program.pl
+.Ve
+.ie n .IP "the ""perl \-Idir"" command line flag" 4
+.el .IP "the \f(CWperl \-Idir\fR command line flag" 4
+.IX Item "the perl -Idir command line flag"
+.Vb 1
+\&    $ perl \-I/path/to/my/dir program.pl
+.Ve
+.ie n .IP "the ""lib"" pragma:" 4
+.el .IP "the \f(CWlib\fR pragma:" 4
+.IX Item "the lib pragma:"
+.Vb 1
+\&    use lib "$ENV{HOME}/myown_perllib";
+.Ve
+.IP "the local::lib module:" 4
+.IX Item "the local::lib module:"
+.Vb 1
+\&    use local::lib;
+\&
+\&    use local::lib "~/myown_perllib";
+.Ve
+.SS "Where are modules installed?"
+.IX Subsection "Where are modules installed?"
+Modules are installed on a case-by-case basis (as provided by the methods
+described in the previous section), and in the operating system. All of these
+paths are stored in \f(CW@INC\fR, which you can display with the one-liner
+.PP
+.Vb 1
+\&    perl \-e \*(Aqprint join("\en",@INC,"")\*(Aq
+.Ve
+.PP
+The same information is displayed at the end of the output from the command
+.PP
+.Vb 1
+\&    perl \-V
+.Ve
+.PP
+To find out where a module's source code is located, use
+.PP
+.Vb 1
+\&    perldoc \-l Encode
+.Ve
+.PP
+to display the path to the module. In some cases (for example, the \f(CW\*(C`AutoLoader\*(C'\fR
+module), this command will show the path to a separate \f(CW\*(C`pod\*(C'\fR file; the module
+itself should be in the same directory, with a 'pm' file extension.
+.SS "What is socket.ph and where do I get it?"
+.IX Subsection "What is socket.ph and where do I get it?"
+It's a Perl 4 style file defining values for system networking
+constants. Sometimes it is built using h2ph when Perl is installed,
+but other times it is not. Modern programs should use \f(CW\*(C`use Socket;\*(C'\fR
+instead.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfaq9.1 b/upstream/mageia-cauldron/man1/perlfaq9.1
new file mode 100644
index 00000000..799553d8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfaq9.1
@@ -0,0 +1,480 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFAQ9 1"
+.TH PERLFAQ9 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfaq9 \- Web, Email and Networking
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This section deals with questions related to running web sites,
+sending and receiving email as well as general networking.
+.SS "Should I use a web framework?"
+.IX Subsection "Should I use a web framework?"
+Yes. If you are building a web site with any level of interactivity
+(forms / users / databases), you
+will want to use a framework to make handling requests
+and responses easier.
+.PP
+If there is no interactivity then you may still want
+to look at using something like Template Toolkit <https://metacpan.org/module/Template>
+or Plack::Middleware::TemplateToolkit
+so maintenance of your HTML files (and other assets) is easier.
+.SS "Which web framework should I use?"
+.IX Xref "framework CGI.pm CGI Catalyst Dancer"
+.IX Subsection "Which web framework should I use?"
+There is no simple answer to this question. Perl frameworks can run everything
+from basic file servers and small scale intranets to massive multinational
+multilingual websites that are the core to international businesses.
+.PP
+Below is a list of a few frameworks with comments which might help you in
+making a decision, depending on your specific requirements. Start by reading
+the docs, then ask questions on the relevant mailing list or IRC channel.
+.IP Catalyst 4
+.IX Item "Catalyst"
+Strongly object-oriented and fully-featured with a long development history and
+a large community and addon ecosystem. It is excellent for large and complex
+applications, where you have full control over the server.
+.IP Dancer2 4
+.IX Item "Dancer2"
+Free of legacy weight, providing a lightweight and easy to learn API.
+Has a growing addon ecosystem. It is best used for smaller projects and
+very easy to learn for beginners.
+.IP Mojolicious 4
+.IX Item "Mojolicious"
+Self-contained and powerful for both small and larger projects,
+with a focus on HTML5 and real-time web technologies such as WebSockets.
+.IP Web::Simple 4
+.IX Item "Web::Simple"
+Strongly object-oriented and minimal, built for speed and intended
+as a toolkit for building micro web apps, custom frameworks or for tieing
+together existing Plack-compatible web applications with one central dispatcher.
+.PP
+All of these interact with or use Plack which is worth understanding
+the basics of when building a website in Perl (there is a lot of useful
+Plack::Middleware <https://metacpan.org/search?q=plack%3A%3Amiddleware>).
+.SS "What is Plack and PSGI?"
+.IX Subsection "What is Plack and PSGI?"
+PSGI is the Perl Web Server Gateway Interface Specification, it is
+a standard that many Perl web frameworks use, you should not need to
+understand it to build a web site, the part you might want to use is Plack.
+.PP
+Plack is a set of tools for using the PSGI stack. It contains
+middleware <https://metacpan.org/search?q=plack%3A%3Amiddleware>
+components, a reference server and utilities for Web application frameworks.
+Plack is like Ruby's Rack or Python's Paste for WSGI.
+.PP
+You could build a web site using Plack and your own code,
+but for anything other than a very basic web site, using a web framework
+(that uses <https://plackperl.org>) is a better option.
+.SS "How do I remove HTML from a string?"
+.IX Subsection "How do I remove HTML from a string?"
+Use HTML::Strip, or HTML::FormatText which not only removes HTML
+but also attempts to do a little simple formatting of the resulting
+plain text.
+.SS "How do I extract URLs?"
+.IX Subsection "How do I extract URLs?"
+HTML::SimpleLinkExtor will extract URLs from HTML, it handles anchors,
+images, objects, frames, and many other tags that can contain a URL.
+If you need anything more complex, you can create your own subclass of
+HTML::LinkExtor or HTML::Parser. You might even use
+HTML::SimpleLinkExtor as an example for something specifically
+suited to your needs.
+.PP
+You can use URI::Find or URL::Search to extract URLs from an
+arbitrary text document.
+.SS "How do I fetch an HTML file?"
+.IX Subsection "How do I fetch an HTML file?"
+(contributed by brian d foy)
+.PP
+The core HTTP::Tiny module can fetch web resources and give their
+content back to you as a string:
+.PP
+.Vb 1
+\&    use HTTP::Tiny;
+\&
+\&    my $ua = HTTP::Tiny\->new;
+\&    my $html = $ua\->get( "http://www.example.com/index.html" )\->{content};
+.Ve
+.PP
+It can also store the resource directly in a file:
+.PP
+.Vb 1
+\&    $ua\->mirror( "http://www.example.com/index.html", "foo.html" );
+.Ve
+.PP
+If you need to do something more complicated, the HTTP::Tiny object can
+be customized by setting attributes, or you can use LWP::UserAgent from
+the libwww-perl distribution or Mojo::UserAgent from the Mojolicious
+distribution to make common tasks easier. If you want to simulate an
+interactive web browser, you can use the WWW::Mechanize module.
+.SS "How do I automate an HTML form submission?"
+.IX Subsection "How do I automate an HTML form submission?"
+If you are doing something complex, such as moving through many pages
+and forms or a web site, you can use WWW::Mechanize. See its
+documentation for all the details.
+.PP
+If you're submitting values using the GET method, create a URL and encode
+the form using the \f(CW\*(C`www_form_urlencode\*(C'\fR method from HTTP::Tiny:
+.PP
+.Vb 1
+\&    use HTTP::Tiny;
+\&
+\&    my $ua = HTTP::Tiny\->new;
+\&
+\&    my $query = $ua\->www_form_urlencode([ q => \*(AqDB_File\*(Aq, lucky => 1 ]);
+\&    my $url = "https://metacpan.org/search?$query";
+\&    my $content = $ua\->get($url)\->{content};
+.Ve
+.PP
+If you're using the POST method, the \f(CW\*(C`post_form\*(C'\fR method will encode the
+content appropriately.
+.PP
+.Vb 1
+\&    use HTTP::Tiny;
+\&
+\&    my $ua = HTTP::Tiny\->new;
+\&
+\&    my $url = \*(Aqhttps://metacpan.org/search\*(Aq;
+\&    my $form = [ q => \*(AqDB_File\*(Aq, lucky => 1 ];
+\&    my $content = $ua\->post_form($url, $form)\->{content};
+.Ve
+.SS "How do I decode or create those %\-encodings on the web?"
+.IX Xref "URI URI::Escape RFC 2396"
+.IX Subsection "How do I decode or create those %-encodings on the web?"
+Most of the time you should not need to do this as
+your web framework, or if you are making a request,
+the LWP or other module would handle it for you.
+.PP
+To encode a string yourself, use the URI::Escape module. The \f(CW\*(C`uri_escape\*(C'\fR
+function returns the escaped string:
+.PP
+.Vb 1
+\&    my $original = "Colon : Hash # Percent %";
+\&
+\&    my $escaped = uri_escape( $original );
+\&
+\&    print "$escaped\en"; # \*(AqColon%20%3A%20Hash%20%23%20Percent%20%25\*(Aq
+.Ve
+.PP
+To decode the string, use the \f(CW\*(C`uri_unescape\*(C'\fR function:
+.PP
+.Vb 1
+\&    my $unescaped = uri_unescape( $escaped );
+\&
+\&    print $unescaped; # back to original
+.Ve
+.PP
+Remember not to encode a full URI, you need to escape each
+component separately and then join them together.
+.SS "How do I redirect to another page?"
+.IX Subsection "How do I redirect to another page?"
+Most Perl Web Frameworks will have a mechanism for doing this,
+using the Catalyst framework it would be:
+.PP
+.Vb 2
+\&    $c\->res\->redirect($url);
+\&    $c\->detach();
+.Ve
+.PP
+If you are using Plack (which most frameworks do), then
+Plack::Middleware::Rewrite is worth looking at if you
+are migrating from Apache or have URL's you want to always
+redirect.
+.SS "How do I put a password on my web pages?"
+.IX Subsection "How do I put a password on my web pages?"
+See if the web framework you are using has an
+authentication system and if that fits your needs.
+.PP
+Alternativly look at Plack::Middleware::Auth::Basic,
+or one of the other Plack authentication <https://metacpan.org/search?q=plack+auth>
+options.
+.SS "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?"
+.IX Subsection "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?"
+(contributed by brian d foy)
+.PP
+You can't prevent people from sending your script bad data. Even if
+you add some client-side checks, people may disable them or bypass
+them completely. For instance, someone might use a module such as
+LWP to submit to your web site. If you want to prevent data that
+try to use SQL injection or other sorts of attacks (and you should
+want to), you have to not trust any data that enter your program.
+.PP
+The perlsec documentation has general advice about data security.
+If you are using the DBI module, use placeholder to fill in data.
+If you are running external programs with \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR, use
+the list forms. There are many other precautions that you should take,
+too many to list here, and most of them fall under the category of not
+using any data that you don't intend to use. Trust no one.
+.SS "How do I parse a mail header?"
+.IX Subsection "How do I parse a mail header?"
+Use the Email::MIME module. It's well-tested and supports all the
+craziness that you'll see in the real world (comment-folding whitespace,
+encodings, comments, etc.).
+.PP
+.Vb 1
+\&  use Email::MIME;
+\&
+\&  my $message = Email::MIME\->new($rfc2822);
+\&  my $subject = $message\->header(\*(AqSubject\*(Aq);
+\&  my $from    = $message\->header(\*(AqFrom\*(Aq);
+.Ve
+.PP
+If you've already got some other kind of email object, consider passing
+it to Email::Abstract and then using its cast method to get an
+Email::MIME object:
+.PP
+.Vb 2
+\&  my $abstract = Email::Abstract\->new($mail_message_object);
+\&  my $email_mime_object = $abstract\->cast(\*(AqEmail::MIME\*(Aq);
+.Ve
+.SS "How do I check a valid mail address?"
+.IX Subsection "How do I check a valid mail address?"
+(partly contributed by Aaron Sherman)
+.PP
+This isn't as simple a question as it sounds. There are two parts:
+.PP
+a) How do I verify that an email address is correctly formatted?
+.PP
+b) How do I verify that an email address targets a valid recipient?
+.PP
+Without sending mail to the address and seeing whether there's a human
+on the other end to answer you, you cannot fully answer part \fIb\fR, but
+the Email::Valid module will do both part \fIa\fR and part \fIb\fR as far
+as you can in real-time.
+.PP
+Our best advice for verifying a person's mail address is to have them
+enter their address twice, just as you normally do to change a
+password. This usually weeds out typos. If both versions match, send
+mail to that address with a personal message. If you get the message
+back and they've followed your directions, you can be reasonably
+assured that it's real.
+.PP
+A related strategy that's less open to forgery is to give them a PIN
+(personal ID number). Record the address and PIN (best that it be a
+random one) for later processing. In the mail you send, include a link to
+your site with the PIN included. If the mail bounces, you know it's not
+valid. If they don't click on the link, either they forged the address or
+(assuming they got the message) following through wasn't important so you
+don't need to worry about it.
+.SS "How do I decode a MIME/BASE64 string?"
+.IX Subsection "How do I decode a MIME/BASE64 string?"
+The MIME::Base64 package handles this as well as the MIME/QP encoding.
+Decoding base 64 becomes as simple as:
+.PP
+.Vb 2
+\&    use MIME::Base64;
+\&    my $decoded = decode_base64($encoded);
+.Ve
+.PP
+The Email::MIME module can decode base 64\-encoded email message parts
+transparently so the developer doesn't need to worry about it.
+.SS "How do I find the user's mail address?"
+.IX Subsection "How do I find the user's mail address?"
+Ask them for it. There are so many email providers available that it's
+unlikely the local system has any idea how to determine a user's email address.
+.PP
+The exception is for organization-specific email (e.g. foo@yourcompany.com)
+where policy can be codified in your program. In that case, you could look at
+\&\f(CW$ENV\fR{USER}, \f(CW$ENV\fR{LOGNAME}, and getpwuid($<) in scalar context, like so:
+.PP
+.Vb 1
+\&  my $user_name = getpwuid($<)
+.Ve
+.PP
+But you still cannot make assumptions about whether this is correct, unless
+your policy says it is. You really are best off asking the user.
+.SS "How do I send email?"
+.IX Subsection "How do I send email?"
+Use the Email::Stuffer module, like so:
+.PP
+.Vb 5
+\&  # first, create your message
+\&  my $message = Email::Stuffer\->from(\*(Aqyou@example.com\*(Aq)
+\&                              \->to(\*(Aqfriend@example.com\*(Aq)
+\&                              \->subject(\*(AqHappy birthday!\*(Aq)
+\&                              \->text_body("Happy birthday to you!\en");
+\&
+\&  $message\->send_or_die;
+.Ve
+.PP
+By default, Email::Sender::Simple (the \f(CW\*(C`send\*(C'\fR and \f(CW\*(C`send_or_die\*(C'\fR methods
+use this under the hood) will try \f(CW\*(C`sendmail\*(C'\fR first, if it exists
+in your \f(CW$PATH\fR. This generally isn't the case. If there's a remote mail
+server you use to send mail, consider investigating one of the Transport
+classes. At time of writing, the available transports include:
+.IP Email::Sender::Transport::Sendmail 4
+.IX Item "Email::Sender::Transport::Sendmail"
+This is the default. If you can use the \fBmail\fR\|(1) or \fBmailx\fR\|(1)
+program to send mail from the machine where your code runs, you should
+be able to use this.
+.IP Email::Sender::Transport::SMTP 4
+.IX Item "Email::Sender::Transport::SMTP"
+This transport contacts a remote SMTP server over TCP. It optionally
+uses TLS or SSL and can authenticate to the server via SASL.
+.PP
+Telling Email::Stuffer to use your transport is straightforward.
+.PP
+.Vb 1
+\&  $message\->transport($email_sender_transport_object)\->send_or_die;
+.Ve
+.SS "How do I use MIME to make an attachment to a mail message?"
+.IX Subsection "How do I use MIME to make an attachment to a mail message?"
+Email::MIME directly supports multipart messages. Email::MIME
+objects themselves are parts and can be attached to other Email::MIME
+objects. Consult the Email::MIME documentation for more information,
+including all of the supported methods and examples of their use.
+.PP
+Email::Stuffer uses Email::MIME under the hood to construct
+messages, and wraps the most common attachment tasks with the simple
+\&\f(CW\*(C`attach\*(C'\fR and \f(CW\*(C`attach_file\*(C'\fR methods.
+.PP
+.Vb 4
+\&  Email::Stuffer\->to(\*(Aqfriend@example.com\*(Aq)
+\&                \->subject(\*(AqThe file\*(Aq)
+\&                \->attach_file(\*(Aqstuff.csv\*(Aq)
+\&                \->send_or_die;
+.Ve
+.SS "How do I read email?"
+.IX Subsection "How do I read email?"
+Use the Email::Folder module, like so:
+.PP
+.Vb 1
+\&  use Email::Folder;
+\&
+\&  my $folder = Email::Folder\->new(\*(Aq/path/to/email/folder\*(Aq);
+\&  while(my $message = $folder\->next_message) {
+\&    # next_message returns Email::Simple objects, but we want
+\&    # Email::MIME objects as they\*(Aqre more robust
+\&    my $mime = Email::MIME\->new($message\->as_string);
+\&  }
+.Ve
+.PP
+There are different classes in the Email::Folder namespace for
+supporting various mailbox types. Note that these modules are generally
+rather limited and only support \fBreading\fR rather than writing.
+.SS "How do I find out my hostname, domainname, or IP address?"
+.IX Xref "hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa, gethostbyname, Socket, Net::Domain, Sys::Hostname"
+.IX Subsection "How do I find out my hostname, domainname, or IP address?"
+(contributed by brian d foy)
+.PP
+The Net::Domain module, which is part of the Standard Library starting
+in Perl 5.7.3, can get you the fully qualified domain name (FQDN), the host
+name, or the domain name.
+.PP
+.Vb 1
+\&    use Net::Domain qw(hostname hostfqdn hostdomain);
+\&
+\&    my $host = hostfqdn();
+.Ve
+.PP
+The Sys::Hostname module, part of the Standard Library, can also get the
+hostname:
+.PP
+.Vb 1
+\&    use Sys::Hostname;
+\&
+\&    $host = hostname();
+.Ve
+.PP
+The Sys::Hostname::Long module takes a different approach and tries
+harder to return the fully qualified hostname:
+.PP
+.Vb 1
+\&  use Sys::Hostname::Long \*(Aqhostname_long\*(Aq;
+\&
+\&  my $hostname = hostname_long();
+.Ve
+.PP
+To get the IP address, you can use the \f(CW\*(C`gethostbyname\*(C'\fR built-in function
+to turn the name into a number. To turn that number into the dotted octet
+form (a.b.c.d) that most people expect, use the \f(CW\*(C`inet_ntoa\*(C'\fR function
+from the Socket module, which also comes with perl.
+.PP
+.Vb 1
+\&    use Socket;
+\&
+\&    my $address = inet_ntoa(
+\&        scalar gethostbyname( $host || \*(Aqlocalhost\*(Aq )
+\&    );
+.Ve
+.SS "How do I fetch/put an (S)FTP file?"
+.IX Subsection "How do I fetch/put an (S)FTP file?"
+Net::FTP, and Net::SFTP allow you to interact with FTP and SFTP (Secure
+FTP) servers.
+.SS "How can I do RPC in Perl?"
+.IX Subsection "How can I do RPC in Perl?"
+Use one of the RPC modules( <https://metacpan.org/search?q=RPC> ).
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlfilter.1 b/upstream/mageia-cauldron/man1/perlfilter.1
new file mode 100644
index 00000000..38303fef
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfilter.1
@@ -0,0 +1,697 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFILTER 1"
+.TH PERLFILTER 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfilter \- Source Filters
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This article is about a little-known feature of Perl called
+\&\fIsource filters\fR. Source filters alter the program text of a module
+before Perl sees it, much as a C preprocessor alters the source text of
+a C program before the compiler sees it. This article tells you more
+about what source filters are, how they work, and how to write your
+own.
+.PP
+The original purpose of source filters was to let you encrypt your
+program source to prevent casual reading. This isn't all they can do, as
+you'll soon learn. But first, the basics.
+.SH CONCEPTS
+.IX Header "CONCEPTS"
+Before the Perl interpreter can execute a Perl script, it must first
+read it from a file into memory for parsing and compilation. If that
+script itself includes other scripts with a \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR
+statement, then each of those scripts will have to be read from their
+respective files as well.
+.PP
+Now think of each logical connection between the Perl parser and an
+individual file as a \fIsource stream\fR. A source stream is created when
+the Perl parser opens a file, it continues to exist as the source code
+is read into memory, and it is destroyed when Perl is finished parsing
+the file. If the parser encounters a \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR statement in
+a source stream, a new and distinct stream is created just for that
+file.
+.PP
+The diagram below represents a single source stream, with the flow of
+source from a Perl script file on the left into the Perl parser on the
+right. This is how Perl normally operates.
+.PP
+.Vb 1
+\&    file \-\-\-\-\-\-\-> parser
+.Ve
+.PP
+There are two important points to remember:
+.IP 1. 5
+Although there can be any number of source streams in existence at any
+given time, only one will be active.
+.IP 2. 5
+Every source stream is associated with only one file.
+.PP
+A source filter is a special kind of Perl module that intercepts and
+modifies a source stream before it reaches the parser. A source filter
+changes our diagram like this:
+.PP
+.Vb 1
+\&    file \-\-\-\-> filter \-\-\-\-> parser
+.Ve
+.PP
+If that doesn't make much sense, consider the analogy of a command
+pipeline. Say you have a shell script stored in the compressed file
+\&\fItrial.gz\fR. The simple pipeline command below runs the script without
+needing to create a temporary file to hold the uncompressed file.
+.PP
+.Vb 1
+\&    gunzip \-c trial.gz | sh
+.Ve
+.PP
+In this case, the data flow from the pipeline can be represented as follows:
+.PP
+.Vb 1
+\&    trial.gz \-\-\-\-> gunzip \-\-\-\-> sh
+.Ve
+.PP
+With source filters, you can store the text of your script compressed and use a source filter to uncompress it for Perl's parser:
+.PP
+.Vb 2
+\&     compressed           gunzip
+\&    Perl program \-\-\-> source filter \-\-\-> parser
+.Ve
+.SH "USING FILTERS"
+.IX Header "USING FILTERS"
+So how do you use a source filter in a Perl script? Above, I said that
+a source filter is just a special kind of module. Like all Perl
+modules, a source filter is invoked with a use statement.
+.PP
+Say you want to pass your Perl source through the C preprocessor before
+execution. As it happens, the source filters distribution comes with a C
+preprocessor filter module called Filter::cpp.
+.PP
+Below is an example program, \f(CW\*(C`cpp_test\*(C'\fR, which makes use of this filter.
+Line numbers have been added to allow specific lines to be referenced
+easily.
+.PP
+.Vb 4
+\&    1: use Filter::cpp;
+\&    2: #define TRUE 1
+\&    3: $a = TRUE;
+\&    4: print "a = $a\en";
+.Ve
+.PP
+When you execute this script, Perl creates a source stream for the
+file. Before the parser processes any of the lines from the file, the
+source stream looks like this:
+.PP
+.Vb 1
+\&    cpp_test \-\-\-\-\-\-\-\-\-> parser
+.Ve
+.PP
+Line 1, \f(CW\*(C`use Filter::cpp\*(C'\fR, includes and installs the \f(CW\*(C`cpp\*(C'\fR filter
+module. All source filters work this way. The use statement is compiled
+and executed at compile time, before any more of the file is read, and
+it attaches the cpp filter to the source stream behind the scenes. Now
+the data flow looks like this:
+.PP
+.Vb 1
+\&    cpp_test \-\-\-\-> cpp filter \-\-\-\-> parser
+.Ve
+.PP
+As the parser reads the second and subsequent lines from the source
+stream, it feeds those lines through the \f(CW\*(C`cpp\*(C'\fR source filter before
+processing them. The \f(CW\*(C`cpp\*(C'\fR filter simply passes each line through the
+real C preprocessor. The output from the C preprocessor is then
+inserted back into the source stream by the filter.
+.PP
+.Vb 5
+\&                  .\-> cpp \-\-.
+\&                  |         |
+\&                  |         |
+\&                  |       <\-\*(Aq
+\&   cpp_test \-\-\-\-> cpp filter \-\-\-\-> parser
+.Ve
+.PP
+The parser then sees the following code:
+.PP
+.Vb 3
+\&    use Filter::cpp;
+\&    $a = 1;
+\&    print "a = $a\en";
+.Ve
+.PP
+Let's consider what happens when the filtered code includes another
+module with use:
+.PP
+.Vb 5
+\&    1: use Filter::cpp;
+\&    2: #define TRUE 1
+\&    3: use Fred;
+\&    4: $a = TRUE;
+\&    5: print "a = $a\en";
+.Ve
+.PP
+The \f(CW\*(C`cpp\*(C'\fR filter does not apply to the text of the Fred module, only
+to the text of the file that used it (\f(CW\*(C`cpp_test\*(C'\fR). Although the use
+statement on line 3 will pass through the cpp filter, the module that
+gets included (\f(CW\*(C`Fred\*(C'\fR) will not. The source streams look like this
+after line 3 has been parsed and before line 4 is parsed:
+.PP
+.Vb 1
+\&    cpp_test \-\-\-> cpp filter \-\-\-> parser (INACTIVE)
+\&
+\&    Fred.pm \-\-\-\-> parser
+.Ve
+.PP
+As you can see, a new stream has been created for reading the source
+from \f(CW\*(C`Fred.pm\*(C'\fR. This stream will remain active until all of \f(CW\*(C`Fred.pm\*(C'\fR
+has been parsed. The source stream for \f(CW\*(C`cpp_test\*(C'\fR will still exist,
+but is inactive. Once the parser has finished reading Fred.pm, the
+source stream associated with it will be destroyed. The source stream
+for \f(CW\*(C`cpp_test\*(C'\fR then becomes active again and the parser reads line 4
+and subsequent lines from \f(CW\*(C`cpp_test\*(C'\fR.
+.PP
+You can use more than one source filter on a single file. Similarly,
+you can reuse the same filter in as many files as you like.
+.PP
+For example, if you have a uuencoded and compressed source file, it is
+possible to stack a uudecode filter and an uncompression filter like
+this:
+.PP
+.Vb 4
+\&    use Filter::uudecode; use Filter::uncompress;
+\&    M\*(AqXL(".H<US4\*(Aq\*(AqV9I;F%L\*(Aq)Q;>7/;1I;_>_I3=&E=%:F*I"T?22Q/
+\&    M6]9*<IQCO*XFT"0[PL%%\*(AqY+IG?WN^ZYN\-$\*(AqJ.[.JE$,20/?K=_[>
+\&    ...
+.Ve
+.PP
+Once the first line has been processed, the flow will look like this:
+.PP
+.Vb 2
+\&    file \-\-\-> uudecode \-\-\-> uncompress \-\-\-> parser
+\&               filter         filter
+.Ve
+.PP
+Data flows through filters in the same order they appear in the source
+file. The uudecode filter appeared before the uncompress filter, so the
+source file will be uudecoded before it's uncompressed.
+.SH "WRITING A SOURCE FILTER"
+.IX Header "WRITING A SOURCE FILTER"
+There are three ways to write your own source filter. You can write it
+in C, use an external program as a filter, or write the filter in Perl.
+I won't cover the first two in any great detail, so I'll get them out
+of the way first. Writing the filter in Perl is most convenient, so
+I'll devote the most space to it.
+.SH "WRITING A SOURCE FILTER IN C"
+.IX Header "WRITING A SOURCE FILTER IN C"
+The first of the three available techniques is to write the filter
+completely in C. The external module you create interfaces directly
+with the source filter hooks provided by Perl.
+.PP
+The advantage of this technique is that you have complete control over
+the implementation of your filter. The big disadvantage is the
+increased complexity required to write the filter \- not only do you
+need to understand the source filter hooks, but you also need a
+reasonable knowledge of Perl guts. One of the few times it is worth
+going to this trouble is when writing a source scrambler. The
+\&\f(CW\*(C`decrypt\*(C'\fR filter (which unscrambles the source before Perl parses it)
+included with the source filter distribution is an example of a C
+source filter (see Decryption Filters, below).
+.IP "\fBDecryption Filters\fR" 5
+.IX Item "Decryption Filters"
+All decryption filters work on the principle of "security through
+obscurity." Regardless of how well you write a decryption filter and
+how strong your encryption algorithm is, anyone determined enough can
+retrieve the original source code. The reason is quite simple:
+in order to execute your program Perl must parse its source code.
+This means that Perl must have all the information needed to decrypt
+your program, and that means that that information is also available to
+anyone able to run the program.
+.Sp
+That said, there are a number of steps that can be taken to make life
+difficult for the potential reader. The most important: Write your
+decryption filter in C and statically link the decryption module into
+the Perl binary. For further tips to make life difficult for the
+potential reader, see the file \fIdecrypt.pm\fR in the source filters
+distribution.
+.SH "CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE"
+.IX Header "CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE"
+An alternative to writing the filter in C is to create a separate
+executable in the language of your choice. The separate executable
+reads from standard input, does whatever processing is necessary, and
+writes the filtered data to standard output. \f(CW\*(C`Filter::cpp\*(C'\fR is an
+example of a source filter implemented as a separate executable \- the
+executable is the C preprocessor bundled with your C compiler.
+.PP
+The source filter distribution includes two modules that simplify this
+task: \f(CW\*(C`Filter::exec\*(C'\fR and \f(CW\*(C`Filter::sh\*(C'\fR. Both allow you to run any
+external executable. Both use a coprocess to control the flow of data
+into and out of the external executable. (For details on coprocesses,
+see Stephens, W.R., "Advanced Programming in the UNIX Environment."
+Addison-Wesley, ISBN 0\-210\-56317\-7, pages 441\-445.) The difference
+between them is that \f(CW\*(C`Filter::exec\*(C'\fR spawns the external command
+directly, while \f(CW\*(C`Filter::sh\*(C'\fR spawns a shell to execute the external
+command. (Unix uses the Bourne shell; NT uses the cmd shell.) Spawning
+a shell allows you to make use of the shell metacharacters and
+redirection facilities.
+.PP
+Here is an example script that uses \f(CW\*(C`Filter::sh\*(C'\fR:
+.PP
+.Vb 3
+\&    use Filter::sh \*(Aqtr XYZ PQR\*(Aq;
+\&    $a = 1;
+\&    print "XYZ a = $a\en";
+.Ve
+.PP
+The output you'll get when the script is executed:
+.PP
+.Vb 1
+\&    PQR a = 1
+.Ve
+.PP
+Writing a source filter as a separate executable works fine, but a
+small performance penalty is incurred. For example, if you execute the
+small example above, a separate subprocess will be created to run the
+Unix \f(CW\*(C`tr\*(C'\fR command. Each use of the filter requires its own subprocess.
+If creating subprocesses is expensive on your system, you might want to
+consider one of the other options for creating source filters.
+.SH "WRITING A SOURCE FILTER IN PERL"
+.IX Header "WRITING A SOURCE FILTER IN PERL"
+The easiest and most portable option available for creating your own
+source filter is to write it completely in Perl. To distinguish this
+from the previous two techniques, I'll call it a Perl source filter.
+.PP
+To help understand how to write a Perl source filter we need an example
+to study. Here is a complete source filter that performs rot13
+decoding. (Rot13 is a very simple encryption scheme used in Usenet
+postings to hide the contents of offensive posts. It moves every letter
+forward thirteen places, so that A becomes N, B becomes O, and Z
+becomes M.)
+.PP
+.Vb 1
+\&   package Rot13;
+\&
+\&   use Filter::Util::Call;
+\&
+\&   sub import {
+\&      my ($type) = @_;
+\&      my ($ref) = [];
+\&      filter_add(bless $ref);
+\&   }
+\&
+\&   sub filter {
+\&      my ($self) = @_;
+\&      my ($status);
+\&
+\&      tr/n\-za\-mN\-ZA\-M/a\-zA\-Z/
+\&         if ($status = filter_read()) > 0;
+\&      $status;
+\&   }
+\&
+\&   1;
+.Ve
+.PP
+All Perl source filters are implemented as Perl classes and have the
+same basic structure as the example above.
+.PP
+First, we include the \f(CW\*(C`Filter::Util::Call\*(C'\fR module, which exports a
+number of functions into your filter's namespace. The filter shown
+above uses two of these functions, \f(CWfilter_add()\fR and
+\&\f(CWfilter_read()\fR.
+.PP
+Next, we create the filter object and associate it with the source
+stream by defining the \f(CW\*(C`import\*(C'\fR function. If you know Perl well
+enough, you know that \f(CW\*(C`import\*(C'\fR is called automatically every time a
+module is included with a use statement. This makes \f(CW\*(C`import\*(C'\fR the ideal
+place to both create and install a filter object.
+.PP
+In the example filter, the object (\f(CW$ref\fR) is blessed just like any
+other Perl object. Our example uses an anonymous array, but this isn't
+a requirement. Because this example doesn't need to store any context
+information, we could have used a scalar or hash reference just as
+well. The next section demonstrates context data.
+.PP
+The association between the filter object and the source stream is made
+with the \f(CWfilter_add()\fR function. This takes a filter object as a
+parameter (\f(CW$ref\fR in this case) and installs it in the source stream.
+.PP
+Finally, there is the code that actually does the filtering. For this
+type of Perl source filter, all the filtering is done in a method
+called \f(CWfilter()\fR. (It is also possible to write a Perl source filter
+using a closure. See the \f(CW\*(C`Filter::Util::Call\*(C'\fR manual page for more
+details.) It's called every time the Perl parser needs another line of
+source to process. The \f(CWfilter()\fR method, in turn, reads lines from
+the source stream using the \f(CWfilter_read()\fR function.
+.PP
+If a line was available from the source stream, \f(CWfilter_read()\fR
+returns a status value greater than zero and appends the line to \f(CW$_\fR.
+A status value of zero indicates end-of-file, less than zero means an
+error. The filter function itself is expected to return its status in
+the same way, and put the filtered line it wants written to the source
+stream in \f(CW$_\fR. The use of \f(CW$_\fR accounts for the brevity of most Perl
+source filters.
+.PP
+In order to make use of the rot13 filter we need some way of encoding
+the source file in rot13 format. The script below, \f(CW\*(C`mkrot13\*(C'\fR, does
+just that.
+.PP
+.Vb 5
+\&    die "usage mkrot13 filename\en" unless @ARGV;
+\&    my $in = $ARGV[0];
+\&    my $out = "$in.tmp";
+\&    open(IN, "<$in") or die "Cannot open file $in: $!\en";
+\&    open(OUT, ">$out") or die "Cannot open file $out: $!\en";
+\&
+\&    print OUT "use Rot13;\en";
+\&    while (<IN>) {
+\&       tr/a\-zA\-Z/n\-za\-mN\-ZA\-M/;
+\&       print OUT;
+\&    }
+\&
+\&    close IN;
+\&    close OUT;
+\&    unlink $in;
+\&    rename $out, $in;
+.Ve
+.PP
+If we encrypt this with \f(CW\*(C`mkrot13\*(C'\fR:
+.PP
+.Vb 1
+\&    print " hello fred \en";
+.Ve
+.PP
+the result will be this:
+.PP
+.Vb 2
+\&    use Rot13;
+\&    cevag "uryyb serq\ea";
+.Ve
+.PP
+Running it produces this output:
+.PP
+.Vb 1
+\&    hello fred
+.Ve
+.SH "USING CONTEXT: THE DEBUG FILTER"
+.IX Header "USING CONTEXT: THE DEBUG FILTER"
+The rot13 example was a trivial example. Here's another demonstration
+that shows off a few more features.
+.PP
+Say you wanted to include a lot of debugging code in your Perl script
+during development, but you didn't want it available in the released
+product. Source filters offer a solution. In order to keep the example
+simple, let's say you wanted the debugging output to be controlled by
+an environment variable, \f(CW\*(C`DEBUG\*(C'\fR. Debugging code is enabled if the
+variable exists, otherwise it is disabled.
+.PP
+Two special marker lines will bracket debugging code, like this:
+.PP
+.Vb 5
+\&    ## DEBUG_BEGIN
+\&    if ($year > 1999) {
+\&       warn "Debug: millennium bug in year $year\en";
+\&    }
+\&    ## DEBUG_END
+.Ve
+.PP
+The filter ensures that Perl parses the code between the <DEBUG_BEGIN>
+and \f(CW\*(C`DEBUG_END\*(C'\fR markers only when the \f(CW\*(C`DEBUG\*(C'\fR environment variable
+exists. That means that when \f(CW\*(C`DEBUG\*(C'\fR does exist, the code above
+should be passed through the filter unchanged. The marker lines can
+also be passed through as-is, because the Perl parser will see them as
+comment lines. When \f(CW\*(C`DEBUG\*(C'\fR isn't set, we need a way to disable the
+debug code. A simple way to achieve that is to convert the lines
+between the two markers into comments:
+.PP
+.Vb 5
+\&    ## DEBUG_BEGIN
+\&    #if ($year > 1999) {
+\&    #     warn "Debug: millennium bug in year $year\en";
+\&    #}
+\&    ## DEBUG_END
+.Ve
+.PP
+Here is the complete Debug filter:
+.PP
+.Vb 1
+\&    package Debug;
+\&
+\&    use v5.36;
+\&    use Filter::Util::Call;
+\&
+\&    use constant TRUE => 1;
+\&    use constant FALSE => 0;
+\&
+\&    sub import {
+\&       my ($type) = @_;
+\&       my (%context) = (
+\&         Enabled => defined $ENV{DEBUG},
+\&         InTraceBlock => FALSE,
+\&         Filename => (caller)[1],
+\&         LineNo => 0,
+\&         LastBegin => 0,
+\&       );
+\&       filter_add(bless \e%context);
+\&    }
+\&
+\&    sub Die {
+\&       my ($self) = shift;
+\&       my ($message) = shift;
+\&       my ($line_no) = shift || $self\->{LastBegin};
+\&       die "$message at $self\->{Filename} line $line_no.\en"
+\&    }
+\&
+\&    sub filter {
+\&       my ($self) = @_;
+\&       my ($status);
+\&       $status = filter_read();
+\&       ++ $self\->{LineNo};
+\&
+\&       # deal with EOF/error first
+\&       if ($status <= 0) {
+\&           $self\->Die("DEBUG_BEGIN has no DEBUG_END")
+\&               if $self\->{InTraceBlock};
+\&           return $status;
+\&       }
+\&
+\&       if ($self\->{InTraceBlock}) {
+\&          if (/^\es*##\es*DEBUG_BEGIN/ ) {
+\&              $self\->Die("Nested DEBUG_BEGIN", $self\->{LineNo})
+\&          } elsif (/^\es*##\es*DEBUG_END/) {
+\&              $self\->{InTraceBlock} = FALSE;
+\&          }
+\&
+\&          # comment out the debug lines when the filter is disabled
+\&          s/^/#/ if ! $self\->{Enabled};
+\&       } elsif ( /^\es*##\es*DEBUG_BEGIN/ ) {
+\&          $self\->{InTraceBlock} = TRUE;
+\&          $self\->{LastBegin} = $self\->{LineNo};
+\&       } elsif ( /^\es*##\es*DEBUG_END/ ) {
+\&          $self\->Die("DEBUG_END has no DEBUG_BEGIN", $self\->{LineNo});
+\&       }
+\&       return $status;
+\&    }
+\&
+\&    1;
+.Ve
+.PP
+The big difference between this filter and the previous example is the
+use of context data in the filter object. The filter object is based on
+a hash reference, and is used to keep various pieces of context
+information between calls to the filter function. All but two of the
+hash fields are used for error reporting. The first of those two,
+Enabled, is used by the filter to determine whether the debugging code
+should be given to the Perl parser. The second, InTraceBlock, is true
+when the filter has encountered a \f(CW\*(C`DEBUG_BEGIN\*(C'\fR line, but has not yet
+encountered the following \f(CW\*(C`DEBUG_END\*(C'\fR line.
+.PP
+If you ignore all the error checking that most of the code does, the
+essence of the filter is as follows:
+.PP
+.Vb 4
+\&    sub filter {
+\&       my ($self) = @_;
+\&       my ($status);
+\&       $status = filter_read();
+\&
+\&       # deal with EOF/error first
+\&       return $status if $status <= 0;
+\&       if ($self\->{InTraceBlock}) {
+\&          if (/^\es*##\es*DEBUG_END/) {
+\&             $self\->{InTraceBlock} = FALSE
+\&          }
+\&
+\&          # comment out debug lines when the filter is disabled
+\&          s/^/#/ if ! $self\->{Enabled};
+\&       } elsif ( /^\es*##\es*DEBUG_BEGIN/ ) {
+\&          $self\->{InTraceBlock} = TRUE;
+\&       }
+\&       return $status;
+\&    }
+.Ve
+.PP
+Be warned: just as the C\-preprocessor doesn't know C, the Debug filter
+doesn't know Perl. It can be fooled quite easily:
+.PP
+.Vb 3
+\&    print <<EOM;
+\&    ##DEBUG_BEGIN
+\&    EOM
+.Ve
+.PP
+Such things aside, you can see that a lot can be achieved with a modest
+amount of code.
+.SH CONCLUSION
+.IX Header "CONCLUSION"
+You now have better understanding of what a source filter is, and you
+might even have a possible use for them. If you feel like playing with
+source filters but need a bit of inspiration, here are some extra
+features you could add to the Debug filter.
+.PP
+First, an easy one. Rather than having debugging code that is
+all-or-nothing, it would be much more useful to be able to control
+which specific blocks of debugging code get included. Try extending the
+syntax for debug blocks to allow each to be identified. The contents of
+the \f(CW\*(C`DEBUG\*(C'\fR environment variable can then be used to control which
+blocks get included.
+.PP
+Once you can identify individual blocks, try allowing them to be
+nested. That isn't difficult either.
+.PP
+Here is an interesting idea that doesn't involve the Debug filter.
+Currently Perl subroutines have fairly limited support for formal
+parameter lists. You can specify the number of parameters and their
+type, but you still have to manually take them out of the \f(CW@_\fR array
+yourself. Write a source filter that allows you to have a named
+parameter list. Such a filter would turn this:
+.PP
+.Vb 1
+\&    sub MySub ($first, $second, @rest) { ... }
+.Ve
+.PP
+into this:
+.PP
+.Vb 6
+\&    sub MySub($$@) {
+\&       my ($first) = shift;
+\&       my ($second) = shift;
+\&       my (@rest) = @_;
+\&       ...
+\&    }
+.Ve
+.PP
+Finally, if you feel like a real challenge, have a go at writing a
+full-blown Perl macro preprocessor as a source filter. Borrow the
+useful features from the C preprocessor and any other macro processors
+you know. The tricky bit will be choosing how much knowledge of Perl's
+syntax you want your filter to have.
+.SH LIMITATIONS
+.IX Header "LIMITATIONS"
+Source filters only work on the string level, thus are highly limited
+in its ability to change source code on the fly. It cannot detect
+comments, quoted strings, heredocs, it is no replacement for a real
+parser.
+The only stable usage for source filters are encryption, compression,
+or the byteloader, to translate binary code back to source code.
+.PP
+See for example the limitations in Switch, which uses source filters,
+and thus is does not work inside a string eval, the presence of
+regexes with embedded newlines that are specified with raw \f(CW\*(C`/.../\*(C'\fR
+delimiters and don't have a modifier \f(CW\*(C`//x\*(C'\fR are indistinguishable from
+code chunks beginning with the division operator \f(CW\*(C`/\*(C'\fR. As a workaround
+you must use \f(CW\*(C`m/.../\*(C'\fR or \f(CW\*(C`m?...?\*(C'\fR for such patterns. Also, the presence of
+regexes specified with raw \f(CW\*(C`?...?\*(C'\fR delimiters may cause mysterious
+errors. The workaround is to use \f(CW\*(C`m?...?\*(C'\fR instead.  See
+<https://metacpan.org/pod/Switch#LIMITATIONS>.
+.PP
+Currently the content of the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR block is not filtered.
+.PP
+Currently internal buffer lengths are limited to 32\-bit only.
+.SH "THINGS TO LOOK OUT FOR"
+.IX Header "THINGS TO LOOK OUT FOR"
+.ie n .IP "Some Filters Clobber the ""DATA"" Handle" 5
+.el .IP "Some Filters Clobber the \f(CWDATA\fR Handle" 5
+.IX Item "Some Filters Clobber the DATA Handle"
+Some source filters use the \f(CW\*(C`DATA\*(C'\fR handle to read the calling program.
+When using these source filters you cannot rely on this handle, nor expect
+any particular kind of behavior when operating on it.  Filters based on
+Filter::Util::Call (and therefore Filter::Simple) do not alter the \f(CW\*(C`DATA\*(C'\fR
+filehandle, but on the other hand totally ignore the text after \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
+.SH REQUIREMENTS
+.IX Header "REQUIREMENTS"
+The Source Filters distribution is available on CPAN, in
+.PP
+.Vb 1
+\&    CPAN/modules/by\-module/Filter
+.Ve
+.PP
+Starting from Perl 5.8 Filter::Util::Call (the core part of the
+Source Filters distribution) is part of the standard Perl distribution.
+Also included is a friendlier interface called Filter::Simple, by
+Damian Conway.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess <Paul.Marquess@btinternet.com>
+.PP
+Reini Urban <rurban@cpan.org>
+.SH Copyrights
+.IX Header "Copyrights"
+The first version of this article originally appeared in The Perl
+Journal #11, and is copyright 1998 The Perl Journal. It appears
+courtesy of Jon Orwant and The Perl Journal.  This document may be
+distributed under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlfork.1 b/upstream/mageia-cauldron/man1/perlfork.1
new file mode 100644
index 00000000..e4829041
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfork.1
@@ -0,0 +1,388 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFORK 1"
+.TH PERLFORK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfork \- Perl's fork() emulation
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 4
+\&    NOTE:  As of the 5.8.0 release, fork() emulation has considerably
+\&    matured.  However, there are still a few known bugs and differences
+\&    from real fork() that might affect you.  See the "BUGS" and
+\&    "CAVEATS AND LIMITATIONS" sections below.
+.Ve
+.PP
+Perl provides a \fBfork()\fR keyword that corresponds to the Unix system call
+of the same name.  On most Unix-like platforms where the \fBfork()\fR system
+call is available, Perl's \fBfork()\fR simply calls it.
+.PP
+On some platforms such as Windows where the \fBfork()\fR system call is not
+available, Perl can be built to emulate \fBfork()\fR at the interpreter level.
+While the emulation is designed to be as compatible as possible with the
+real \fBfork()\fR at the level of the Perl program, there are certain
+important differences that stem from the fact that all the pseudo child
+"processes" created this way live in the same real process as far as the
+operating system is concerned.
+.PP
+This document provides a general overview of the capabilities and
+limitations of the \fBfork()\fR emulation.  Note that the issues discussed here
+are not applicable to platforms where a real \fBfork()\fR is available and Perl
+has been configured to use it.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The \fBfork()\fR emulation is implemented at the level of the Perl interpreter.
+What this means in general is that running \fBfork()\fR will actually clone the
+running interpreter and all its state, and run the cloned interpreter in
+a separate thread, beginning execution in the new thread just after the
+point where the \fBfork()\fR was called in the parent.  We will refer to the
+thread that implements this child "process" as the pseudo-process.
+.PP
+To the Perl program that called \fBfork()\fR, all this is designed to be
+transparent.  The parent returns from the \fBfork()\fR with a pseudo-process
+ID that can be subsequently used in any process-manipulation functions;
+the child returns from the \fBfork()\fR with a value of \f(CW0\fR to signify that
+it is the child pseudo-process.
+.SS "Behavior of other Perl features in forked pseudo-processes"
+.IX Subsection "Behavior of other Perl features in forked pseudo-processes"
+Most Perl features behave in a natural way within pseudo-processes.
+.ie n .IP "$$ or $PROCESS_ID" 8
+.el .IP "$$ or \f(CW$PROCESS_ID\fR" 8
+.IX Item "$$ or $PROCESS_ID"
+This special variable is correctly set to the pseudo-process ID.
+It can be used to identify pseudo-processes within a particular
+session.  Note that this value is subject to recycling if any
+pseudo-processes are launched after others have been \fBwait()\fR\-ed on.
+.ie n .IP %ENV 8
+.el .IP \f(CW%ENV\fR 8
+.IX Item "%ENV"
+Each pseudo-process maintains its own virtual environment.  Modifications
+to \f(CW%ENV\fR affect the virtual environment, and are only visible within that
+pseudo-process, and in any processes (or pseudo-processes) launched from
+it.
+.IP "\fBchdir()\fR and all other builtins that accept filenames" 8
+.IX Item "chdir() and all other builtins that accept filenames"
+Each pseudo-process maintains its own virtual idea of the current directory.
+Modifications to the current directory using \fBchdir()\fR are only visible within
+that pseudo-process, and in any processes (or pseudo-processes) launched from
+it.  All file and directory accesses from the pseudo-process will correctly
+map the virtual working directory to the real working directory appropriately.
+.IP "\fBwait()\fR and \fBwaitpid()\fR" 8
+.IX Item "wait() and waitpid()"
+\&\fBwait()\fR and \fBwaitpid()\fR can be passed a pseudo-process ID returned by \fBfork()\fR.
+These calls will properly wait for the termination of the pseudo-process
+and return its status.
+.IP \fBkill()\fR 8
+.IX Item "kill()"
+\&\f(CW\*(C`kill(\*(AqKILL\*(Aq, ...)\*(C'\fR can be used to terminate a pseudo-process by
+passing it the ID returned by \fBfork()\fR. The outcome of kill on a pseudo-process
+is unpredictable and it should not be used except
+under dire circumstances, because the operating system may not
+guarantee integrity of the process resources when a running thread is
+terminated.  The process which implements the pseudo-processes can be blocked
+and the Perl interpreter hangs. Note that using \f(CW\*(C`kill(\*(AqKILL\*(Aq, ...)\*(C'\fR on a
+pseudo\-\fBprocess()\fR may typically cause memory leaks, because the thread
+that implements the pseudo-process does not get a chance to clean up
+its resources.
+.Sp
+\&\f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR can also be used on pseudo-processes, but the
+signal will not be delivered while the pseudo-process is blocked by a
+system call, e.g. waiting for a socket to connect, or trying to read
+from a socket with no data available.  Starting in Perl 5.14 the
+parent process will not wait for children to exit once they have been
+signalled with \f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR to avoid deadlock during process
+exit.  You will have to explicitly call \fBwaitpid()\fR to make sure the
+child has time to clean-up itself, but you are then also responsible
+that the child is not blocking on I/O either.
+.IP \fBexec()\fR 8
+.IX Item "exec()"
+Calling \fBexec()\fR within a pseudo-process actually spawns the requested
+executable in a separate process and waits for it to complete before
+exiting with the same exit status as that process.  This means that the
+process ID reported within the running executable will be different from
+what the earlier Perl \fBfork()\fR might have returned.  Similarly, any process
+manipulation functions applied to the ID returned by \fBfork()\fR will affect the
+waiting pseudo-process that called \fBexec()\fR, not the real process it is
+waiting for after the \fBexec()\fR.
+.Sp
+When \fBexec()\fR is called inside a pseudo-process then DESTROY methods and
+END blocks will still be called after the external process returns.
+.IP \fBexit()\fR 8
+.IX Item "exit()"
+\&\fBexit()\fR always exits just the executing pseudo-process, after automatically
+\&\fBwait()\fR\-ing for any outstanding child pseudo-processes.  Note that this means
+that the process as a whole will not exit unless all running pseudo-processes
+have exited.  See below for some limitations with open filehandles.
+.IP "Open handles to files, directories and network sockets" 8
+.IX Item "Open handles to files, directories and network sockets"
+All open handles are \fBdup()\fR\-ed in pseudo-processes, so that closing
+any handles in one process does not affect the others.  See below for
+some limitations.
+.SS "Resource limits"
+.IX Subsection "Resource limits"
+In the eyes of the operating system, pseudo-processes created via the \fBfork()\fR
+emulation are simply threads in the same process.  This means that any
+process-level limits imposed by the operating system apply to all
+pseudo-processes taken together.  This includes any limits imposed by the
+operating system on the number of open file, directory and socket handles,
+limits on disk space usage, limits on memory size, limits on CPU utilization
+etc.
+.SS "Killing the parent process"
+.IX Subsection "Killing the parent process"
+If the parent process is killed (either using Perl's \fBkill()\fR builtin, or
+using some external means) all the pseudo-processes are killed as well,
+and the whole process exits.
+.SS "Lifetime of the parent process and pseudo-processes"
+.IX Subsection "Lifetime of the parent process and pseudo-processes"
+During the normal course of events, the parent process and every
+pseudo-process started by it will wait for their respective pseudo-children
+to complete before they exit.  This means that the parent and every
+pseudo-child created by it that is also a pseudo-parent will only exit
+after their pseudo-children have exited.
+.PP
+Starting with Perl 5.14 a parent will not \fBwait()\fR automatically
+for any child that has been signalled with \f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR
+to avoid a deadlock in case the child is blocking on I/O and
+never receives the signal.
+.SH "CAVEATS AND LIMITATIONS"
+.IX Header "CAVEATS AND LIMITATIONS"
+.IP "BEGIN blocks" 8
+.IX Item "BEGIN blocks"
+The \fBfork()\fR emulation will not work entirely correctly when called from
+within a BEGIN block.  The forked copy will run the contents of the
+BEGIN block, but will not continue parsing the source stream after the
+BEGIN block.  For example, consider the following code:
+.Sp
+.Vb 5
+\&    BEGIN {
+\&        fork and exit;          # fork child and exit the parent
+\&        print "inner\en";
+\&    }
+\&    print "outer\en";
+.Ve
+.Sp
+This will print:
+.Sp
+.Vb 1
+\&    inner
+.Ve
+.Sp
+rather than the expected:
+.Sp
+.Vb 2
+\&    inner
+\&    outer
+.Ve
+.Sp
+This limitation arises from fundamental technical difficulties in
+cloning and restarting the stacks used by the Perl parser in the
+middle of a parse.
+.IP "Open filehandles" 8
+.IX Item "Open filehandles"
+Any filehandles open at the time of the \fBfork()\fR will be \fBdup()\fR\-ed.  Thus,
+the files can be closed independently in the parent and child, but beware
+that the \fBdup()\fR\-ed handles will still share the same seek pointer.  Changing
+the seek position in the parent will change it in the child and vice-versa.
+One can avoid this by opening files that need distinct seek pointers
+separately in the child.
+.Sp
+On some operating systems, notably Solaris and Unixware, calling \f(CWexit()\fR
+from a child process will flush and close open filehandles in the parent,
+thereby corrupting the filehandles.  On these systems, calling \f(CW_exit()\fR
+is suggested instead.  \f(CW_exit()\fR is available in Perl through the
+\&\f(CW\*(C`POSIX\*(C'\fR module.  Please consult your system's manpages for more information
+on this.
+.IP "Open directory handles" 8
+.IX Item "Open directory handles"
+Perl will completely read from all open directory handles until they
+reach the end of the stream.  It will then \fBseekdir()\fR back to the
+original location and all future \fBreaddir()\fR requests will be fulfilled
+from the cache buffer.  That means that neither the directory handle held
+by the parent process nor the one held by the child process will see
+any changes made to the directory after the \fBfork()\fR call.
+.Sp
+Note that \fBrewinddir()\fR has a similar limitation on Windows and will not
+force \fBreaddir()\fR to read the directory again either.  Only a newly
+opened directory handle will reflect changes to the directory.
+.IP "Forking pipe \fBopen()\fR not yet implemented" 8
+.IX Item "Forking pipe open() not yet implemented"
+The \f(CW\*(C`open(FOO, "|\-")\*(C'\fR and \f(CW\*(C`open(BAR, "\-|")\*(C'\fR constructs are not yet
+implemented.  This limitation can be easily worked around in new code
+by creating a pipe explicitly.  The following example shows how to
+write to a forked child:
+.Sp
+.Vb 10
+\&    # simulate open(FOO, "|\-")
+\&    sub pipe_to_fork ($) {
+\&        my $parent = shift;
+\&        pipe my $child, $parent or die;
+\&        my $pid = fork();
+\&        die "fork() failed: $!" unless defined $pid;
+\&        if ($pid) {
+\&            close $child;
+\&        }
+\&        else {
+\&            close $parent;
+\&            open(STDIN, "<&=" . fileno($child)) or die;
+\&        }
+\&        $pid;
+\&    }
+\&
+\&    if (pipe_to_fork(\*(AqFOO\*(Aq)) {
+\&        # parent
+\&        print FOO "pipe_to_fork\en";
+\&        close FOO;
+\&    }
+\&    else {
+\&        # child
+\&        while (<STDIN>) { print; }
+\&        exit(0);
+\&    }
+.Ve
+.Sp
+And this one reads from the child:
+.Sp
+.Vb 10
+\&    # simulate open(FOO, "\-|")
+\&    sub pipe_from_fork ($) {
+\&        my $parent = shift;
+\&        pipe $parent, my $child or die;
+\&        my $pid = fork();
+\&        die "fork() failed: $!" unless defined $pid;
+\&        if ($pid) {
+\&            close $child;
+\&        }
+\&        else {
+\&            close $parent;
+\&            open(STDOUT, ">&=" . fileno($child)) or die;
+\&        }
+\&        $pid;
+\&    }
+\&
+\&    if (pipe_from_fork(\*(AqBAR\*(Aq)) {
+\&        # parent
+\&        while (<BAR>) { print; }
+\&        close BAR;
+\&    }
+\&    else {
+\&        # child
+\&        print "pipe_from_fork\en";
+\&        exit(0);
+\&    }
+.Ve
+.Sp
+Forking pipe \fBopen()\fR constructs will be supported in future.
+.IP "Global state maintained by XSUBs" 8
+.IX Item "Global state maintained by XSUBs"
+External subroutines (XSUBs) that maintain their own global state may
+not work correctly.  Such XSUBs will either need to maintain locks to
+protect simultaneous access to global data from different pseudo-processes,
+or maintain all their state on the Perl symbol table, which is copied
+naturally when \fBfork()\fR is called.  A callback mechanism that provides
+extensions an opportunity to clone their state will be provided in the
+near future.
+.IP "Interpreter embedded in larger application" 8
+.IX Item "Interpreter embedded in larger application"
+The \fBfork()\fR emulation may not behave as expected when it is executed in an
+application which embeds a Perl interpreter and calls Perl APIs that can
+evaluate bits of Perl code.  This stems from the fact that the emulation
+only has knowledge about the Perl interpreter's own data structures and
+knows nothing about the containing application's state.  For example, any
+state carried on the application's own call stack is out of reach.
+.IP "Thread-safety of extensions" 8
+.IX Item "Thread-safety of extensions"
+Since the \fBfork()\fR emulation runs code in multiple threads, extensions
+calling into non-thread-safe libraries may not work reliably when
+calling \fBfork()\fR.  As Perl's threading support gradually becomes more
+widely adopted even on platforms with a native \fBfork()\fR, such extensions
+are expected to be fixed for thread-safety.
+.SH "PORTABILITY CAVEATS"
+.IX Header "PORTABILITY CAVEATS"
+In portable Perl code, \f(CW\*(C`kill(9, $child)\*(C'\fR must not be used on forked processes.
+Killing a forked process is unsafe and has unpredictable results.
+See "\fBkill()\fR", above.
+.SH BUGS
+.IX Header "BUGS"
+.IP \(bu 8
+Having pseudo-process IDs be negative integers breaks down for the integer
+\&\f(CW\-1\fR because the \fBwait()\fR and \fBwaitpid()\fR functions treat this number as
+being special.  The tacit assumption in the current implementation is that
+the system never allocates a thread ID of \f(CW1\fR for user threads.  A better
+representation for pseudo-process IDs will be implemented in future.
+.IP \(bu 8
+In certain cases, the OS-level handles created by the \fBpipe()\fR, \fBsocket()\fR,
+and \fBaccept()\fR operators are apparently not duplicated accurately in
+pseudo-processes.  This only happens in some situations, but where it
+does happen, it may result in deadlocks between the read and write ends
+of pipe handles, or inability to send or receive data across socket
+handles.
+.IP \(bu 8
+This document may be incomplete in some respects.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Support for concurrent interpreters and the \fBfork()\fR emulation was implemented
+by ActiveState, with funding from Microsoft Corporation.
+.PP
+This document is authored and maintained by Gurusamy Sarathy
+<gsar@activestate.com>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+"fork" in perlfunc, perlipc
diff --git a/upstream/mageia-cauldron/man1/perlform.1 b/upstream/mageia-cauldron/man1/perlform.1
new file mode 100644
index 00000000..6974f485
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlform.1
@@ -0,0 +1,514 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFORM 1"
+.TH PERLFORM 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlform \- Perl formats
+.IX Xref "format report chart"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl has a mechanism to help you generate simple reports and charts.  To
+facilitate this, Perl helps you code up your output page close to how it
+will look when it's printed.  It can keep track of things like how many
+lines are on a page, what page you're on, when to print page headers,
+etc.  Keywords are borrowed from FORTRAN: \fBformat()\fR to declare and \fBwrite()\fR
+to execute; see their entries in perlfunc.  Fortunately, the layout is
+much more legible, more like BASIC's PRINT USING statement.  Think of it
+as a poor man's \fBnroff\fR\|(1).
+.IX Xref "nroff"
+.PP
+Formats, like packages and subroutines, are declared rather than
+executed, so they may occur at any point in your program.  (Usually it's
+best to keep them all together though.) They have their own namespace
+apart from all the other "types" in Perl.  This means that if you have a
+function named "Foo", it is not the same thing as having a format named
+"Foo".  However, the default name for the format associated with a given
+filehandle is the same as the name of the filehandle.  Thus, the default
+format for STDOUT is named "STDOUT", and the default format for filehandle
+TEMP is named "TEMP".  They just look the same.  They aren't.
+.PP
+Output record formats are declared as follows:
+.PP
+.Vb 3
+\&    format NAME =
+\&    FORMLIST
+\&    .
+.Ve
+.PP
+If the name is omitted, format "STDOUT" is defined. A single "." in 
+column 1 is used to terminate a format.  FORMLIST consists of a sequence 
+of lines, each of which may be one of three types:
+.IP 1. 4
+A comment, indicated by putting a '#' in the first column.
+.IP 2. 4
+A "picture" line giving the format for one output line.
+.IP 3. 4
+An argument line supplying values to plug into the previous picture line.
+.PP
+Picture lines contain output field definitions, intermingled with
+literal text. These lines do not undergo any kind of variable interpolation.
+Field definitions are made up from a set of characters, for starting and
+extending a field to its desired width. This is the complete set of
+characters for field definitions:
+.IX Xref "format, picture line @ ^ < | > # 0 . ... @* ^* ~ ~~"
+.PP
+.Vb 10
+\&   @    start of regular field
+\&   ^    start of special field
+\&   <    pad character for left justification
+\&   |    pad character for centering
+\&   >    pad character for right justification
+\&   #    pad character for a right\-justified numeric field
+\&   0    instead of first #: pad number with leading zeroes
+\&   .    decimal point within a numeric field
+\&   ...  terminate a text field, show "..." as truncation evidence
+\&   @*   variable width field for a multi\-line value
+\&   ^*   variable width field for next line of a multi\-line value
+\&   ~    suppress line with all fields empty
+\&   ~~   repeat line until all fields are exhausted
+.Ve
+.PP
+Each field in a picture line starts with either "@" (at) or "^" (caret),
+indicating what we'll call, respectively, a "regular" or "special" field.
+The choice of pad characters determines whether a field is textual or
+numeric. The tilde operators are not part of a field.  Let's look at
+the various possibilities in detail.
+.SS "Text Fields"
+.IX Xref "format, text field"
+.IX Subsection "Text Fields"
+The length of the field is supplied by padding out the field with multiple 
+"<", ">", or "|" characters to specify a non-numeric field with,
+respectively, left justification, right justification, or centering. 
+For a regular field, the value (up to the first newline) is taken and
+printed according to the selected justification, truncating excess characters.
+If you terminate a text field with "...", three dots will be shown if
+the value is truncated. A special text field may be used to do rudimentary 
+multi-line text block filling; see "Using Fill Mode" for details.
+.PP
+.Vb 7
+\&   Example:
+\&      format STDOUT =
+\&      @<<<<<<   @||||||   @>>>>>>
+\&      "left",   "middle", "right"
+\&      .
+\&   Output:
+\&      left      middle    right
+.Ve
+.SS "Numeric Fields"
+.IX Xref "# format, numeric field"
+.IX Subsection "Numeric Fields"
+Using "#" as a padding character specifies a numeric field, with
+right justification. An optional "." defines the position of the
+decimal point. With a "0" (zero) instead of the first "#", the
+formatted number will be padded with leading zeroes if necessary.
+A special numeric field is blanked out if the value is undefined.
+If the resulting value would exceed the width specified the field is
+filled with "#" as overflow evidence.
+.PP
+.Vb 7
+\&   Example:
+\&      format STDOUT =
+\&      @###   @.###   @##.###  @###   @###   ^####
+\&       42,   3.1415,  undef,    0, 10000,   undef
+\&      .
+\&   Output:
+\&        42   3.142     0.000     0   ####
+.Ve
+.SS "The Field @* for Variable-Width Multi-Line Text"
+.IX Xref "@*"
+.IX Subsection "The Field @* for Variable-Width Multi-Line Text"
+The field "@*" can be used for printing multi-line, nontruncated
+values; it should (but need not) appear by itself on a line. A final
+line feed is chomped off, but all other characters are emitted verbatim.
+.SS "The Field ^* for Variable-Width One-line-at-a-time Text"
+.IX Xref "^*"
+.IX Subsection "The Field ^* for Variable-Width One-line-at-a-time Text"
+Like "@*", this is a variable-width field. The value supplied must be a 
+scalar variable. Perl puts the first line (up to the first "\en") of the 
+text into the field, and then chops off the front of the string so that 
+the next time the variable is referenced, more of the text can be printed. 
+The variable will \fInot\fR be restored.
+.PP
+.Vb 12
+\&   Example:
+\&      $text = "line 1\enline 2\enline 3";
+\&      format STDOUT =
+\&      Text: ^*
+\&            $text
+\&      ~~    ^*
+\&            $text
+\&      .
+\&   Output:
+\&      Text: line 1
+\&            line 2
+\&            line 3
+.Ve
+.SS "Specifying Values"
+.IX Xref "format, specifying values"
+.IX Subsection "Specifying Values"
+The values are specified on the following format line in the same order as
+the picture fields.  The expressions providing the values must be
+separated by commas.  They are all evaluated in a list context
+before the line is processed, so a single list expression could produce
+multiple list elements.  The expressions may be spread out to more than
+one line if enclosed in braces.  If so, the opening brace must be the first
+token on the first line.  If an expression evaluates to a number with a
+decimal part, and if the corresponding picture specifies that the decimal
+part should appear in the output (that is, any picture except multiple "#"
+characters \fBwithout\fR an embedded "."), the character used for the decimal
+point is determined by the current LC_NUMERIC locale if \f(CW\*(C`use locale\*(C'\fR is in
+effect.  This means that, if, for example, the run-time environment happens
+to specify a German locale, "," will be used instead of the default ".".  See
+perllocale and "WARNINGS" for more information.
+.SS "Using Fill Mode"
+.IX Xref "format, fill mode"
+.IX Subsection "Using Fill Mode"
+On text fields the caret enables a kind of fill mode.  Instead of an
+arbitrary expression, the value supplied must be a scalar variable
+that contains a text string.  Perl puts the next portion of the text into
+the field, and then chops off the front of the string so that the next time
+the variable is referenced, more of the text can be printed.  (Yes, this
+means that the variable itself is altered during execution of the \fBwrite()\fR
+call, and is not restored.)  The next portion of text is determined by
+a crude line-breaking algorithm. You may use the carriage return character
+(\f(CW\*(C`\er\*(C'\fR) to force a line break. You can change which characters are legal 
+to break on by changing the variable \f(CW$:\fR (that's 
+\&\f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR if you're using the English module) to a 
+list of the desired characters.
+.PP
+Normally you would use a sequence of fields in a vertical stack associated 
+with the same scalar variable to print out a block of text. You might wish 
+to end the final field with the text "...", which will appear in the output 
+if the text was too long to appear in its entirety.
+.SS "Suppressing Lines Where All Fields Are Void"
+.IX Xref "format, suppressing lines"
+.IX Subsection "Suppressing Lines Where All Fields Are Void"
+Using caret fields can produce lines where all fields are blank. You can
+suppress such lines by putting a "~" (tilde) character anywhere in the
+line.  The tilde will be translated to a space upon output.
+.SS "Repeating Format Lines"
+.IX Xref "format, repeating lines"
+.IX Subsection "Repeating Format Lines"
+If you put two contiguous tilde characters "~~" anywhere into a line,
+the line will be repeated until all the fields on the line are exhausted,
+i.e. undefined. For special (caret) text fields this will occur sooner or
+later, but if you use a text field of the at variety, the  expression you
+supply had better not give the same value every time forever! (\f(CWshift(@f)\fR
+is a simple example that would work.)  Don't use a regular (at) numeric 
+field in such lines, because it will never go blank.
+.SS "Top of Form Processing"
+.IX Xref "format, top of form top header"
+.IX Subsection "Top of Form Processing"
+Top-of-form processing is by default handled by a format with the
+same name as the current filehandle with "_TOP" concatenated to it.
+It's triggered at the top of each page.  See "write" in perlfunc.
+.PP
+Examples:
+.PP
+.Vb 10
+\& # a report on the /etc/passwd file
+\& format STDOUT_TOP =
+\&                         Passwd File
+\& Name                Login    Office   Uid   Gid Home
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& .
+\& format STDOUT =
+\& @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
+\& $name,              $login,  $office,$uid,$gid, $home
+\& .
+\&
+\&
+\& # a report from a bug report form
+\& format STDOUT_TOP =
+\&                         Bug Reports
+\& @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
+\& $system,                      $%,         $date
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& .
+\& format STDOUT =
+\& Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&          $subject
+\& Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&        $index,                       $description
+\& Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&           $priority,        $date,   $description
+\& From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&       $from,                         $description
+\& Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&              $programmer,            $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
+\&                                      $description
+\& .
+.Ve
+.PP
+It is possible to intermix \fBprint()\fRs with \fBwrite()\fRs on the same output
+channel, but you'll have to handle \f(CW\*(C`$\-\*(C'\fR (\f(CW$FORMAT_LINES_LEFT\fR)
+yourself.
+.SS "Format Variables"
+.IX Xref "format variables format, variables"
+.IX Subsection "Format Variables"
+The current format name is stored in the variable \f(CW$~\fR (\f(CW$FORMAT_NAME\fR),
+and the current top of form format name is in \f(CW$^\fR (\f(CW$FORMAT_TOP_NAME\fR).
+The current output page number is stored in \f(CW$%\fR (\f(CW$FORMAT_PAGE_NUMBER\fR),
+and the number of lines on the page is in \f(CW$=\fR (\f(CW$FORMAT_LINES_PER_PAGE\fR).
+Whether to autoflush output on this handle is stored in \f(CW$|\fR
+(\f(CW$OUTPUT_AUTOFLUSH\fR).  The string output before each top of page (except
+the first) is stored in \f(CW$^L\fR (\f(CW$FORMAT_FORMFEED\fR).  These variables are
+set on a per-filehandle basis, so you'll need to \fBselect()\fR into a different
+one to affect them:
+.PP
+.Vb 4
+\&    select((select(OUTF),
+\&            $~ = "My_Other_Format",
+\&            $^ = "My_Top_Format"
+\&           )[0]);
+.Ve
+.PP
+Pretty ugly, eh?  It's a common idiom though, so don't be too surprised
+when you see it.  You can at least use a temporary variable to hold
+the previous filehandle: (this is a much better approach in general,
+because not only does legibility improve, you now have an intermediary
+stage in the expression to single-step the debugger through):
+.PP
+.Vb 4
+\&    $ofh = select(OUTF);
+\&    $~ = "My_Other_Format";
+\&    $^ = "My_Top_Format";
+\&    select($ofh);
+.Ve
+.PP
+If you use the English module, you can even read the variable names:
+.PP
+.Vb 5
+\&    use English;
+\&    $ofh = select(OUTF);
+\&    $FORMAT_NAME     = "My_Other_Format";
+\&    $FORMAT_TOP_NAME = "My_Top_Format";
+\&    select($ofh);
+.Ve
+.PP
+But you still have those funny \fBselect()\fRs.  So just use the FileHandle
+module.  Now, you can access these special variables using lowercase
+method names instead:
+.PP
+.Vb 3
+\&    use FileHandle;
+\&    format_name     OUTF "My_Other_Format";
+\&    format_top_name OUTF "My_Top_Format";
+.Ve
+.PP
+Much better!
+.SH NOTES
+.IX Header "NOTES"
+Because the values line may contain arbitrary expressions (for at fields,
+not caret fields), you can farm out more sophisticated processing
+to other functions, like \fBsprintf()\fR or one of your own.  For example:
+.PP
+.Vb 4
+\&    format Ident =
+\&        @<<<<<<<<<<<<<<<
+\&        &commify($n)
+\&    .
+.Ve
+.PP
+To get a real at or caret into the field, do this:
+.PP
+.Vb 4
+\&    format Ident =
+\&    I have an @ here.
+\&            "@"
+\&    .
+.Ve
+.PP
+To center a whole line of text, do something like this:
+.PP
+.Vb 4
+\&    format Ident =
+\&    @|||||||||||||||||||||||||||||||||||||||||||||||
+\&            "Some text line"
+\&    .
+.Ve
+.PP
+There is no builtin way to say "float this to the right hand side
+of the page, however wide it is."  You have to specify where it goes.
+The truly desperate can generate their own format on the fly, based
+on the current number of columns, and then \fBeval()\fR it:
+.PP
+.Vb 9
+\&    $format  = "format STDOUT = \en"
+\&             . \*(Aq^\*(Aq . \*(Aq<\*(Aq x $cols . "\en"
+\&             . \*(Aq$entry\*(Aq . "\en"
+\&             . "\et^" . "<" x ($cols\-8) . "~~\en"
+\&             . \*(Aq$entry\*(Aq . "\en"
+\&             . ".\en";
+\&    print $format if $Debugging;
+\&    eval $format;
+\&    die $@ if $@;
+.Ve
+.PP
+Which would generate a format looking something like this:
+.PP
+.Vb 6
+\& format STDOUT =
+\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\& $entry
+\&         ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
+\& $entry
+\& .
+.Ve
+.PP
+Here's a little program that's somewhat like \fBfmt\fR\|(1):
+.PP
+.Vb 3
+\& format =
+\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
+\& $_
+\&
+\& .
+\&
+\& $/ = \*(Aq\*(Aq;
+\& while (<>) {
+\&     s/\es*\en\es*/ /g;
+\&     write;
+\& }
+.Ve
+.SS Footers
+.IX Xref "format, footer footer"
+.IX Subsection "Footers"
+While \f(CW$FORMAT_TOP_NAME\fR contains the name of the current header format,
+there is no corresponding mechanism to automatically do the same thing
+for a footer.  Not knowing how big a format is going to be until you
+evaluate it is one of the major problems.  It's on the TODO list.
+.PP
+Here's one strategy:  If you have a fixed-size footer, you can get footers
+by checking \f(CW$FORMAT_LINES_LEFT\fR before each \fBwrite()\fR and print the footer
+yourself if necessary.
+.PP
+Here's another strategy: Open a pipe to yourself, using \f(CW\*(C`open(MYSELF, "|\-")\*(C'\fR
+(see "open" in perlfunc) and always \fBwrite()\fR to MYSELF instead of STDOUT.
+Have your child process massage its STDIN to rearrange headers and footers
+however you like.  Not very convenient, but doable.
+.SS "Accessing Formatting Internals"
+.IX Xref "format, internals"
+.IX Subsection "Accessing Formatting Internals"
+For low-level access to the formatting mechanism, you may use \fBformline()\fR
+and access \f(CW$^A\fR (the \f(CW$ACCUMULATOR\fR variable) directly.
+.PP
+For example:
+.PP
+.Vb 3
+\&    $str = formline <<\*(AqEND\*(Aq, 1,2,3;
+\&    @<<<  @|||  @>>>
+\&    END
+\&
+\&    print "Wow, I just stored \*(Aq$^A\*(Aq in the accumulator!\en";
+.Ve
+.PP
+Or to make an \fBswrite()\fR subroutine, which is to \fBwrite()\fR what \fBsprintf()\fR
+is to \fBprintf()\fR, do this:
+.PP
+.Vb 8
+\&    use Carp;
+\&    sub swrite {
+\&        croak "usage: swrite PICTURE ARGS" unless @_;
+\&        my $format = shift;
+\&        $^A = "";
+\&        formline($format,@_);
+\&        return $^A;
+\&    }
+\&
+\&    $string = swrite(<<\*(AqEND\*(Aq, 1, 2, 3);
+\& Check me out
+\& @<<<  @|||  @>>>
+\& END
+\&    print $string;
+.Ve
+.SH WARNINGS
+.IX Header "WARNINGS"
+The lone dot that ends a format can also prematurely end a mail
+message passing through a misconfigured Internet mailer (and based on
+experience, such misconfiguration is the rule, not the exception).  So
+when sending format code through mail, you should indent it so that
+the format-ending dot is not on the left margin; this will prevent
+SMTP cutoff.
+.PP
+Lexical variables (declared with "my") are not visible within a
+format unless the format is declared within the scope of the lexical
+variable.
+.PP
+If a program's environment specifies an LC_NUMERIC locale and \f(CW\*(C`use
+locale\*(C'\fR is in effect when the format is declared, the locale is used
+to specify the decimal point character in formatted output.  Formatted
+output cannot be controlled by \f(CW\*(C`use locale\*(C'\fR at the time when \fBwrite()\fR
+is called. See perllocale for further discussion of locale handling.
+.PP
+Within strings that are to be displayed in a fixed-length text field,
+each control character is substituted by a space. (But remember the
+special meaning of \f(CW\*(C`\er\*(C'\fR when using fill mode.) This is done to avoid
+misalignment when control characters "disappear" on some output media.
diff --git a/upstream/mageia-cauldron/man1/perlfreebsd.1 b/upstream/mageia-cauldron/man1/perlfreebsd.1
new file mode 100644
index 00000000..88e3420a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfreebsd.1
@@ -0,0 +1,94 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFREEBSD 1"
+.TH PERLFREEBSD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfreebsd \- Perl version 5 on FreeBSD systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of FreeBSD that will affect how Perl
+version 5 (hereafter just Perl) is compiled and/or runs.
+.SS "FreeBSD core dumps from readdir_r with ithreads"
+.IX Subsection "FreeBSD core dumps from readdir_r with ithreads"
+When perl is configured to use ithreads, it will use re-entrant library calls
+in preference to non-re-entrant versions.  There is a bug in FreeBSD's
+\&\f(CW\*(C`readdir_r\*(C'\fR function in versions 4.5 and earlier that can cause a SEGV when
+reading large directories. A patch for FreeBSD libc is available
+(see <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=30631>)
+which has been integrated into FreeBSD 4.6.
+.ie n .SS "$^X doesn't always contain a full path in FreeBSD"
+.el .SS "\f(CW$^X\fP doesn't always contain a full path in FreeBSD"
+.IX Subsection "$^X doesn't always contain a full path in FreeBSD"
+perl sets \f(CW$^X\fR where possible to a full path by asking the operating
+system. On FreeBSD the full path of the perl interpreter is found by using
+\&\f(CW\*(C`sysctl\*(C'\fR with \f(CW\*(C`KERN_PROC_PATHNAME\*(C'\fR if that is supported, else by reading
+the symlink \fI/proc/curproc/file\fR. FreeBSD 7 and earlier has a bug where
+either approach sometimes returns an incorrect value
+(see <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=35703>).
+In these cases perl will fall back to the old behaviour of using C's
+\&\f(CW\*(C`argv[0]\*(C'\fR value for \f(CW$^X\fR.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic
+and Tim Bunce.
+.PP
+Please report any errors, updates, or suggestions to
+<https://github.com/Perl/perl5/issues>.
diff --git a/upstream/mageia-cauldron/man1/perlfunc.1 b/upstream/mageia-cauldron/man1/perlfunc.1
new file mode 100644
index 00000000..ecddb6e6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlfunc.1
@@ -0,0 +1,10931 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLFUNC 1"
+.TH PERLFUNC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlfunc \- Perl builtin functions
+.IX Xref "function"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The functions in this section can serve as terms in an expression.
+They fall into two major categories: list operators and named unary
+operators.  These differ in their precedence relationship with a
+following comma.  (See the precedence table in perlop.)  List
+operators take more than one argument, while unary operators can never
+take more than one argument.  Thus, a comma terminates the argument of
+a unary operator, but merely separates the arguments of a list
+operator.  A unary operator generally provides scalar context to its
+argument, while a list operator may provide either scalar or list
+contexts for its arguments.  If it does both, scalar arguments
+come first and list argument follow, and there can only ever
+be one such list argument.  For instance,
+\&\f(CW\*(C`splice\*(C'\fR has three scalar arguments
+followed by a list, whereas \f(CW\*(C`gethostbyname\*(C'\fR has
+four scalar arguments.
+.PP
+In the syntax descriptions that follow, list operators that expect a
+list (and provide list context for elements of the list) are shown
+with LIST as an argument.  Such a list may consist of any combination
+of scalar arguments or list values; the list values will be included
+in the list as if each individual element were interpolated at that
+point in the list, forming a longer single-dimensional list value.
+Commas should separate literal elements of the LIST.
+.PP
+Any function in the list below may be used either with or without
+parentheses around its arguments.  (The syntax descriptions omit the
+parentheses.)  If you use parentheses, the simple but occasionally
+surprising rule is this: It \fIlooks\fR like a function, therefore it \fIis\fR a
+function, and precedence doesn't matter.  Otherwise it's a list
+operator or unary operator, and precedence does matter.  Whitespace
+between the function and left parenthesis doesn't count, so sometimes
+you need to be careful:
+.PP
+.Vb 5
+\&    print 1+2+4;      # Prints 7.
+\&    print(1+2) + 4;   # Prints 3.
+\&    print (1+2)+4;    # Also prints 3!
+\&    print +(1+2)+4;   # Prints 7.
+\&    print ((1+2)+4);  # Prints 7.
+.Ve
+.PP
+If you run Perl with the \f(CW\*(C`use warnings\*(C'\fR pragma, it can warn
+you about this.  For example, the third line above produces:
+.PP
+.Vb 2
+\&    print (...) interpreted as function at \- line 1.
+\&    Useless use of integer addition in void context at \- line 1.
+.Ve
+.PP
+A few functions take no arguments at all, and therefore work as neither
+unary nor list operators.  These include such functions as
+\&\f(CW\*(C`time\*(C'\fR and \f(CW\*(C`endpwent\*(C'\fR.  For example,
+\&\f(CW\*(C`time+86_400\*(C'\fR always means \f(CW\*(C`time() + 86_400\*(C'\fR.
+.PP
+For functions that can be used in either a scalar or list context,
+nonabortive failure is generally indicated in scalar context by
+returning the undefined value, and in list context by returning the
+empty list.
+.PP
+Remember the following important rule: There is \fBno rule\fR that relates
+the behavior of an expression in list context to its behavior in scalar
+context, or vice versa.  It might do two totally different things.
+Each operator and function decides which sort of value would be most
+appropriate to return in scalar context.  Some operators return the
+length of the list that would have been returned in list context.  Some
+operators return the first value in the list.  Some operators return the
+last value in the list.  Some operators return a count of successful
+operations.  In general, they do what you want, unless you want
+consistency.
+.IX Xref "context"
+.PP
+A named array in scalar context is quite different from what would at
+first glance appear to be a list in scalar context.  You can't get a list
+like \f(CW\*(C`(1,2,3)\*(C'\fR into being in scalar context, because the compiler knows
+the context at compile time.  It would generate the scalar comma operator
+there, not the list concatenation version of the comma.  That means it
+was never a list to start with.
+.PP
+In general, functions in Perl that serve as wrappers for system calls
+("syscalls") of the same name (like \fBchown\fR\|(2), \fBfork\fR\|(2),
+\&\fBclosedir\fR\|(2), etc.) return true when they succeed and
+\&\f(CW\*(C`undef\*(C'\fR otherwise, as is usually mentioned in the
+descriptions below.  This is different from the C interfaces, which
+return \f(CW\-1\fR on failure.  Exceptions to this rule include
+\&\f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR, and
+\&\f(CW\*(C`syscall\*(C'\fR.  System calls also set the special
+\&\f(CW$!\fR variable on failure.  Other functions do not, except
+accidentally.
+.PP
+Extension modules can also hook into the Perl parser to define new
+kinds of keyword-headed expression.  These may look like functions, but
+may also look completely different.  The syntax following the keyword
+is defined entirely by the extension.  If you are an implementor, see
+"PL_keyword_plugin" in perlapi for the mechanism.  If you are using such
+a module, see the module's documentation for details of the syntax that
+it defines.
+.SS "Perl Functions by Category"
+.IX Xref "function"
+.IX Subsection "Perl Functions by Category"
+Here are Perl's functions (including things that look like
+functions, like some keywords and named operators)
+arranged by category.  Some functions appear in more
+than one place.  Any warnings, including those produced by
+keywords, are described in perldiag and warnings.
+.IP "Functions for SCALARs or strings" 4
+.IX Xref "scalar string character"
+.IX Item "Functions for SCALARs or strings"
+\&\f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chop\*(C'\fR,
+\&\f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR,
+\&\f(CW\*(C`fc\*(C'\fR, \f(CW\*(C`hex\*(C'\fR,
+\&\f(CW\*(C`index\*(C'\fR, \f(CW\*(C`lc\*(C'\fR,
+\&\f(CW\*(C`lcfirst\*(C'\fR, \f(CW\*(C`length\*(C'\fR,
+\&\f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`ord\*(C'\fR,
+\&\f(CW\*(C`pack\*(C'\fR,
+\&\f(CW\*(C`q//\*(C'\fR,
+\&\f(CW\*(C`qq//\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR,
+\&\f(CW\*(C`rindex\*(C'\fR,
+\&\f(CW\*(C`sprintf\*(C'\fR,
+\&\f(CW\*(C`substr\*(C'\fR,
+\&\f(CW\*(C`tr///\*(C'\fR, \f(CW\*(C`uc\*(C'\fR,
+\&\f(CW\*(C`ucfirst\*(C'\fR,
+\&\f(CW\*(C`y///\*(C'\fR
+.Sp
+\&\f(CW\*(C`fc\*(C'\fR is available only if the
+\&\f(CW"fc"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"fc"\fR feature is enabled automatically
+with a \f(CW\*(C`use v5.16\*(C'\fR (or higher) declaration in the current scope.
+.IP "Regular expressions and pattern matching" 4
+.IX Xref "regular expression regex regexp"
+.IX Item "Regular expressions and pattern matching"
+\&\f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`pos\*(C'\fR,
+\&\f(CW\*(C`qr//\*(C'\fR,
+\&\f(CW\*(C`quotemeta\*(C'\fR,
+\&\f(CW\*(C`s///\*(C'\fR,
+\&\f(CW\*(C`split\*(C'\fR,
+\&\f(CW\*(C`study\*(C'\fR
+.IP "Numeric functions" 4
+.IX Xref "numeric number trigonometric trigonometry"
+.IX Item "Numeric functions"
+\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR, \f(CW\*(C`cos\*(C'\fR,
+\&\f(CW\*(C`exp\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`int\*(C'\fR,
+\&\f(CW\*(C`log\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`rand\*(C'\fR,
+\&\f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`srand\*(C'\fR
+.ie n .IP "Functions for real @ARRAYs" 4
+.el .IP "Functions for real \f(CW@ARRAYs\fR" 4
+.IX Xref "array"
+.IX Item "Functions for real @ARRAYs"
+\&\f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`pop\*(C'\fR,
+\&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`shift\*(C'\fR,
+\&\f(CW\*(C`splice\*(C'\fR,
+\&\f(CW\*(C`unshift\*(C'\fR, \f(CW\*(C`values\*(C'\fR
+.IP "Functions for list data" 4
+.IX Xref "list"
+.IX Item "Functions for list data"
+\&\f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`join\*(C'\fR,
+\&\f(CW\*(C`map\*(C'\fR, \f(CW\*(C`qw//\*(C'\fR,
+\&\f(CW\*(C`reverse\*(C'\fR, \f(CW\*(C`sort\*(C'\fR,
+\&\f(CW\*(C`unpack\*(C'\fR
+.ie n .IP "Functions for real %HASHes" 4
+.el .IP "Functions for real \f(CW%HASHes\fR" 4
+.IX Xref "hash"
+.IX Item "Functions for real %HASHes"
+\&\f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`each\*(C'\fR,
+\&\f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`keys\*(C'\fR,
+\&\f(CW\*(C`values\*(C'\fR
+.IP "Input and output functions" 4
+.IX Xref "I O input output dbm"
+.IX Item "Input and output functions"
+\&\f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`close\*(C'\fR,
+\&\f(CW\*(C`closedir\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR,
+\&\f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`die\*(C'\fR,
+\&\f(CW\*(C`eof\*(C'\fR, \f(CW\*(C`fileno\*(C'\fR,
+\&\f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`format\*(C'\fR,
+\&\f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`print\*(C'\fR,
+\&\f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`read\*(C'\fR,
+\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`readline\*(C'\fR,
+\&\f(CW\*(C`rewinddir\*(C'\fR, \f(CW\*(C`say\*(C'\fR,
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`seekdir\*(C'\fR,
+\&\f(CW\*(C`select\*(C'\fR,
+\&\f(CW\*(C`syscall\*(C'\fR,
+\&\f(CW\*(C`sysread\*(C'\fR,
+\&\f(CW\*(C`sysseek\*(C'\fR,
+\&\f(CW\*(C`syswrite\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`telldir\*(C'\fR,
+\&\f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`warn\*(C'\fR,
+\&\f(CW\*(C`write\*(C'\fR
+.Sp
+\&\f(CW\*(C`say\*(C'\fR is available only if the
+\&\f(CW"say"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"say"\fR feature is enabled automatically
+with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current scope.
+.IP "Functions for fixed-length data or records" 4
+.IX Item "Functions for fixed-length data or records"
+\&\f(CW\*(C`pack\*(C'\fR,
+\&\f(CW\*(C`read\*(C'\fR,
+\&\f(CW\*(C`syscall\*(C'\fR,
+\&\f(CW\*(C`sysread\*(C'\fR,
+\&\f(CW\*(C`sysseek\*(C'\fR,
+\&\f(CW\*(C`syswrite\*(C'\fR,
+\&\f(CW\*(C`unpack\*(C'\fR, \f(CW\*(C`vec\*(C'\fR
+.IP "Functions for filehandles, files, or directories" 4
+.IX Xref "file filehandle directory pipe link symlink"
+.IX Item "Functions for filehandles, files, or directories"
+\&\f(CW\*(C`\-\fR\f(CIX\fR\f(CW\*(C'\fR, \f(CW\*(C`chdir\*(C'\fR,
+\&\f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR,
+\&\f(CW\*(C`chroot\*(C'\fR,
+\&\f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`glob\*(C'\fR,
+\&\f(CW\*(C`ioctl\*(C'\fR,
+\&\f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR,
+\&\f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`open\*(C'\fR,
+\&\f(CW\*(C`opendir\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR,
+\&\f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR,
+\&\f(CW\*(C`select\*(C'\fR, \f(CW\*(C`stat\*(C'\fR,
+\&\f(CW\*(C`symlink\*(C'\fR,
+\&\f(CW\*(C`sysopen\*(C'\fR,
+\&\f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR,
+\&\f(CW\*(C`utime\*(C'\fR
+.IP "Keywords related to the control flow of your Perl program" 4
+.IX Xref "control flow"
+.IX Item "Keywords related to the control flow of your Perl program"
+\&\f(CW\*(C`break\*(C'\fR, \f(CW\*(C`caller\*(C'\fR,
+\&\f(CW\*(C`continue\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`do\*(C'\fR,
+\&\f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR,
+\&\f(CW\*(C`evalbytes\*(C'\fR, \f(CW\*(C`exit\*(C'\fR,
+\&\f(CW\*(C`_\|_FILE_\|_\*(C'\fR, \f(CW\*(C`goto\*(C'\fR,
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`_\|_LINE_\|_\*(C'\fR,
+\&\f(CW\*(C`method\*(C'\fR,
+\&\f(CW\*(C`next\*(C'\fR, \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR,
+\&\f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`return\*(C'\fR,
+\&\f(CW\*(C`sub\*(C'\fR, \f(CW\*(C`_\|_SUB_\|_\*(C'\fR,
+\&\f(CW\*(C`wantarray\*(C'\fR
+.Sp
+\&\f(CW\*(C`break\*(C'\fR is available only if you enable the experimental
+\&\f(CW"switch"\fR feature or use the \f(CW\*(C`CORE::\*(C'\fR
+prefix.  The \f(CW"switch"\fR feature also
+enables the \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`given\*(C'\fR and \f(CW\*(C`when\*(C'\fR statements, which are
+documented in "Switch Statements" in perlsyn.
+The \f(CW"switch"\fR feature is enabled
+automatically with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current
+scope.  In Perl v5.14 and earlier, \f(CW\*(C`continue\*(C'\fR
+required the \f(CW"switch"\fR feature, like
+the other keywords.
+.Sp
+\&\f(CW\*(C`evalbytes\*(C'\fR is only available with the
+\&\f(CW"evalbytes"\fR feature
+(see feature) or if prefixed with \f(CW\*(C`CORE::\*(C'\fR.  \f(CW\*(C`_\|_SUB_\|_\*(C'\fR
+is only available with the
+\&\f(CW"current_sub"\fR feature or if
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  Both the
+\&\f(CW"evalbytes"\fR
+and \f(CW"current_sub"\fR features are
+enabled automatically with a \f(CW\*(C`use v5.16\*(C'\fR (or higher) declaration in the
+current scope.
+.IP "Keywords related to scoping" 4
+.IX Item "Keywords related to scoping"
+\&\f(CW\*(C`caller\*(C'\fR,
+\&\f(CW\*(C`class\*(C'\fR, 
+\&\f(CW\*(C`field\*(C'\fR,
+\&\f(CW\*(C`import\*(C'\fR,
+\&\f(CW\*(C`local\*(C'\fR,
+\&\f(CW\*(C`my\*(C'\fR,
+\&\f(CW\*(C`our\*(C'\fR,
+\&\f(CW\*(C`package\*(C'\fR,
+\&\f(CW\*(C`state\*(C'\fR,
+\&\f(CW\*(C`use\*(C'\fR
+.Sp
+\&\f(CW\*(C`state\*(C'\fR is available only if the
+\&\f(CW"state"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"state"\fR feature is enabled
+automatically with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current
+scope.
+.IP "Miscellaneous functions" 4
+.IX Item "Miscellaneous functions"
+\&\f(CW\*(C`defined\*(C'\fR, \f(CW\*(C`formline\*(C'\fR,
+\&\f(CW\*(C`lock\*(C'\fR, \f(CW\*(C`prototype\*(C'\fR,
+\&\f(CW\*(C`reset\*(C'\fR, \f(CW\*(C`scalar\*(C'\fR,
+\&\f(CW\*(C`undef\*(C'\fR
+.IP "Functions for processes and process groups" 4
+.IX Xref "process pid process id"
+.IX Item "Functions for processes and process groups"
+\&\f(CW\*(C`alarm\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`fork\*(C'\fR,
+\&\f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getppid\*(C'\fR,
+\&\f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`kill\*(C'\fR,
+\&\f(CW\*(C`pipe\*(C'\fR,
+\&\f(CW\*(C`qx//\*(C'\fR,
+\&\f(CW\*(C`readpipe\*(C'\fR, \f(CW\*(C`setpgrp\*(C'\fR,
+\&\f(CW\*(C`setpriority\*(C'\fR,
+\&\f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`times\*(C'\fR,
+\&\f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR
+.IP "Keywords related to Perl modules" 4
+.IX Xref "module"
+.IX Item "Keywords related to Perl modules"
+\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`import\*(C'\fR,
+\&\f(CW\*(C`no\*(C'\fR, \f(CW\*(C`package\*(C'\fR,
+\&\f(CW\*(C`require\*(C'\fR, \f(CW\*(C`use\*(C'\fR
+.IP "Keywords related to classes and object-orientation" 4
+.IX Xref "object class package"
+.IX Item "Keywords related to classes and object-orientation"
+\&\f(CW\*(C`bless\*(C'\fR,
+\&\f(CW\*(C`class\*(C'\fR,
+\&\f(CW\*(C`dbmclose\*(C'\fR,
+\&\f(CW\*(C`dbmopen\*(C'\fR,
+\&\f(CW\*(C`field\*(C'\fR,
+\&\f(CW\*(C`method\*(C'\fR,
+\&\f(CW\*(C`package\*(C'\fR,
+\&\f(CW\*(C`ref\*(C'\fR,
+\&\f(CW\*(C`tie\*(C'\fR,
+\&\f(CW\*(C`tied\*(C'\fR,
+\&\f(CW\*(C`untie\*(C'\fR,
+\&\f(CW\*(C`use\*(C'\fR
+.IP "Low-level socket functions" 4
+.IX Xref "socket sock"
+.IX Item "Low-level socket functions"
+\&\f(CW\*(C`accept\*(C'\fR,
+\&\f(CW\*(C`bind\*(C'\fR, \f(CW\*(C`connect\*(C'\fR,
+\&\f(CW\*(C`getpeername\*(C'\fR,
+\&\f(CW\*(C`getsockname\*(C'\fR,
+\&\f(CW\*(C`getsockopt\*(C'\fR,
+\&\f(CW\*(C`listen\*(C'\fR,
+\&\f(CW\*(C`recv\*(C'\fR,
+\&\f(CW\*(C`send\*(C'\fR,
+\&\f(CW\*(C`setsockopt\*(C'\fR,
+\&\f(CW\*(C`shutdown\*(C'\fR,
+\&\f(CW\*(C`socket\*(C'\fR,
+\&\f(CW\*(C`socketpair\*(C'\fR
+.IP "System V interprocess communication functions" 4
+.IX Xref "IPC System V semaphore shared memory memory message"
+.IX Item "System V interprocess communication functions"
+\&\f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR,
+\&\f(CW\*(C`msgrcv\*(C'\fR,
+\&\f(CW\*(C`msgsnd\*(C'\fR,
+\&\f(CW\*(C`semctl\*(C'\fR,
+\&\f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR,
+\&\f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR,
+\&\f(CW\*(C`shmread\*(C'\fR,
+\&\f(CW\*(C`shmwrite\*(C'\fR
+.IP "Fetching user and group info" 4
+.IX Xref "user group password uid gid passwd etc passwd"
+.IX Item "Fetching user and group info"
+\&\f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR,
+\&\f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR,
+\&\f(CW\*(C`getgrent\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR,
+\&\f(CW\*(C`getgrnam\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR,
+\&\f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR,
+\&\f(CW\*(C`getpwuid\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR,
+\&\f(CW\*(C`setpwent\*(C'\fR
+.IP "Fetching network info" 4
+.IX Xref "network protocol host hostname IP address service"
+.IX Item "Fetching network info"
+\&\f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR,
+\&\f(CW\*(C`gethostbyaddr\*(C'\fR,
+\&\f(CW\*(C`gethostbyname\*(C'\fR, \f(CW\*(C`gethostent\*(C'\fR,
+\&\f(CW\*(C`getnetbyaddr\*(C'\fR,
+\&\f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR,
+\&\f(CW\*(C`getprotobyname\*(C'\fR,
+\&\f(CW\*(C`getprotobynumber\*(C'\fR,
+\&\f(CW\*(C`getprotoent\*(C'\fR,
+\&\f(CW\*(C`getservbyname\*(C'\fR,
+\&\f(CW\*(C`getservbyport\*(C'\fR,
+\&\f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR,
+\&\f(CW\*(C`setnetent\*(C'\fR,
+\&\f(CW\*(C`setprotoent\*(C'\fR,
+\&\f(CW\*(C`setservent\*(C'\fR
+.IP "Time-related functions" 4
+.IX Xref "time date"
+.IX Item "Time-related functions"
+\&\f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR,
+\&\f(CW\*(C`time\*(C'\fR, \f(CW\*(C`times\*(C'\fR
+.IP "Non-function keywords" 4
+.IX Item "Non-function keywords"
+\&\f(CW\*(C`ADJUST\*(C'\fR,
+\&\f(CW\*(C`and\*(C'\fR,
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR,
+\&\f(CW\*(C`BEGIN\*(C'\fR,
+\&\f(CW\*(C`catch\*(C'\fR,
+\&\f(CW\*(C`CHECK\*(C'\fR,
+\&\f(CW\*(C`cmp\*(C'\fR,
+\&\f(CW\*(C`CORE\*(C'\fR,
+\&\f(CW\*(C`_\|_DATA_\|_\*(C'\fR,
+\&\f(CW\*(C`default\*(C'\fR,
+\&\f(CW\*(C`defer\*(C'\fR,
+\&\f(CW\*(C`DESTROY\*(C'\fR,
+\&\f(CW\*(C`else\*(C'\fR,
+\&\f(CW\*(C`elseif\*(C'\fR,
+\&\f(CW\*(C`elsif\*(C'\fR,
+\&\f(CW\*(C`END\*(C'\fR,
+\&\f(CW\*(C`_\|_END_\|_\*(C'\fR,
+\&\f(CW\*(C`eq\*(C'\fR,
+\&\f(CW\*(C`finally\*(C'\fR,
+\&\f(CW\*(C`for\*(C'\fR,
+\&\f(CW\*(C`foreach\*(C'\fR,
+\&\f(CW\*(C`ge\*(C'\fR,
+\&\f(CW\*(C`given\*(C'\fR,
+\&\f(CW\*(C`gt\*(C'\fR,
+\&\f(CW\*(C`if\*(C'\fR,
+\&\f(CW\*(C`INIT\*(C'\fR,
+\&\f(CW\*(C`isa\*(C'\fR,
+\&\f(CW\*(C`le\*(C'\fR,
+\&\f(CW\*(C`lt\*(C'\fR,
+\&\f(CW\*(C`ne\*(C'\fR,
+\&\f(CW\*(C`not\*(C'\fR,
+\&\f(CW\*(C`or\*(C'\fR,
+\&\f(CW\*(C`try\*(C'\fR,
+\&\f(CW\*(C`UNITCHECK\*(C'\fR,
+\&\f(CW\*(C`unless\*(C'\fR,
+\&\f(CW\*(C`until\*(C'\fR,
+\&\f(CW\*(C`when\*(C'\fR,
+\&\f(CW\*(C`while\*(C'\fR,
+\&\f(CW\*(C`x\*(C'\fR,
+\&\f(CW\*(C`xor\*(C'\fR
+.SS Portability
+.IX Xref "portability Unix portable"
+.IX Subsection "Portability"
+Perl was born in Unix and can therefore access all common Unix
+system calls.  In non-Unix environments, the functionality of some
+Unix system calls may not be available or details of the available
+functionality may differ slightly.  The Perl functions affected
+by this are:
+.PP
+\&\f(CW\*(C`\-\fR\f(CIX\fR\f(CW\*(C'\fR, \f(CW\*(C`binmode\*(C'\fR,
+\&\f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR,
+\&\f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR,
+\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR,
+\&\f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`endgrent\*(C'\fR,
+\&\f(CW\*(C`endhostent\*(C'\fR, \f(CW\*(C`endnetent\*(C'\fR,
+\&\f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR,
+\&\f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`exec\*(C'\fR,
+\&\f(CW\*(C`fcntl\*(C'\fR,
+\&\f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`fork\*(C'\fR,
+\&\f(CW\*(C`getgrent\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR,
+\&\f(CW\*(C`gethostbyname\*(C'\fR, \f(CW\*(C`gethostent\*(C'\fR,
+\&\f(CW\*(C`getlogin\*(C'\fR,
+\&\f(CW\*(C`getnetbyaddr\*(C'\fR,
+\&\f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR,
+\&\f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR,
+\&\f(CW\*(C`getpriority\*(C'\fR,
+\&\f(CW\*(C`getprotobynumber\*(C'\fR,
+\&\f(CW\*(C`getprotoent\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR,
+\&\f(CW\*(C`getpwnam\*(C'\fR, \f(CW\*(C`getpwuid\*(C'\fR,
+\&\f(CW\*(C`getservbyport\*(C'\fR,
+\&\f(CW\*(C`getservent\*(C'\fR,
+\&\f(CW\*(C`getsockopt\*(C'\fR,
+\&\f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`ioctl\*(C'\fR,
+\&\f(CW\*(C`kill\*(C'\fR, \f(CW\*(C`link\*(C'\fR,
+\&\f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`msgctl\*(C'\fR,
+\&\f(CW\*(C`msgget\*(C'\fR,
+\&\f(CW\*(C`msgrcv\*(C'\fR,
+\&\f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`open\*(C'\fR,
+\&\f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR,
+\&\f(CW\*(C`rename\*(C'\fR,
+\&\f(CW\*(C`select\*(C'\fR,
+\&\f(CW\*(C`semctl\*(C'\fR,
+\&\f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR,
+\&\f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR,
+\&\f(CW\*(C`setnetent\*(C'\fR, \f(CW\*(C`setpgrp\*(C'\fR,
+\&\f(CW\*(C`setpriority\*(C'\fR,
+\&\f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR,
+\&\f(CW\*(C`setservent\*(C'\fR,
+\&\f(CW\*(C`setsockopt\*(C'\fR,
+\&\f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR,
+\&\f(CW\*(C`shmread\*(C'\fR,
+\&\f(CW\*(C`shmwrite\*(C'\fR,
+\&\f(CW\*(C`socket\*(C'\fR,
+\&\f(CW\*(C`socketpair\*(C'\fR,
+\&\f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR,
+\&\f(CW\*(C`syscall\*(C'\fR,
+\&\f(CW\*(C`sysopen\*(C'\fR,
+\&\f(CW\*(C`system\*(C'\fR, \f(CW\*(C`times\*(C'\fR,
+\&\f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`umask\*(C'\fR,
+\&\f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`wait\*(C'\fR,
+\&\f(CW\*(C`waitpid\*(C'\fR
+.PP
+For more information about the portability of these functions, see
+perlport and other available platform-specific documentation.
+.SS "Alphabetical Listing of Perl Functions"
+.IX Subsection "Alphabetical Listing of Perl Functions"
+.IP "\-X FILEHANDLE" 4
+.IX Xref "-r -w -x -o -R -W -X -O -e -z -s -f -d -l -p -S -b -c -t -u -g -k -T -B -M -A -C"
+.IX Item "-X FILEHANDLE"
+.PD 0
+.IP "\-X EXPR" 4
+.IX Item "-X EXPR"
+.IP "\-X DIRHANDLE" 4
+.IX Item "-X DIRHANDLE"
+.IP \-X 4
+.IX Item "-X"
+.PD
+A file test, where X is one of the letters listed below.  This unary
+operator takes one argument, either a filename, a filehandle, or a dirhandle,
+and tests the associated file to see if something is true about it.  If the
+argument is omitted, tests \f(CW$_\fR, except for \f(CW\*(C`\-t\*(C'\fR, which
+tests STDIN.  Unless otherwise documented, it returns \f(CW1\fR for true and
+\&\f(CW\*(Aq\*(Aq\fR for false.  If the file doesn't exist or can't be examined, it
+returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$!\fR (errno).
+With the exception of the \f(CW\*(C`\-l\*(C'\fR test they all follow symbolic links
+because they use \f(CWstat()\fR and not \f(CWlstat()\fR (so dangling symlinks can't
+be examined and will therefore report failure).
+.Sp
+Despite the funny names, precedence is the same as any other named unary
+operator.  The operator may be any of:
+.Sp
+.Vb 4
+\&    \-r  File is readable by effective uid/gid.
+\&    \-w  File is writable by effective uid/gid.
+\&    \-x  File is executable by effective uid/gid.
+\&    \-o  File is owned by effective uid.
+\&
+\&    \-R  File is readable by real uid/gid.
+\&    \-W  File is writable by real uid/gid.
+\&    \-X  File is executable by real uid/gid.
+\&    \-O  File is owned by real uid.
+\&
+\&    \-e  File exists.
+\&    \-z  File has zero size (is empty).
+\&    \-s  File has nonzero size (returns size in bytes).
+\&
+\&    \-f  File is a plain file.
+\&    \-d  File is a directory.
+\&    \-l  File is a symbolic link (false if symlinks aren\*(Aqt
+\&        supported by the file system).
+\&    \-p  File is a named pipe (FIFO), or Filehandle is a pipe.
+\&    \-S  File is a socket.
+\&    \-b  File is a block special file.
+\&    \-c  File is a character special file.
+\&    \-t  Filehandle is opened to a tty.
+\&
+\&    \-u  File has setuid bit set.
+\&    \-g  File has setgid bit set.
+\&    \-k  File has sticky bit set.
+\&
+\&    \-T  File is an ASCII or UTF\-8 text file (heuristic guess).
+\&    \-B  File is a "binary" file (opposite of \-T).
+\&
+\&    \-M  Script start time minus file modification time, in days.
+\&    \-A  Same for access time.
+\&    \-C  Same for inode change time (Unix, may differ for other
+\&        platforms)
+.Ve
+.Sp
+Example:
+.Sp
+.Vb 5
+\&    while (<>) {
+\&        chomp;
+\&        next unless \-f $_;  # ignore specials
+\&        #...
+\&    }
+.Ve
+.Sp
+Note that \f(CW\*(C`\-s/a/b/\*(C'\fR does not do a negated substitution.  Saying
+\&\f(CW\*(C`\-exp($foo)\*(C'\fR still works as expected, however: only single letters
+following a minus are interpreted as file tests.
+.Sp
+These operators are exempt from the "looks like a function rule" described
+above.  That is, an opening parenthesis after the operator does not affect
+how much of the following code constitutes the argument.  Put the opening
+parentheses before the operator to separate it from code that follows (this
+applies only to operators with higher precedence than unary operators, of
+course):
+.Sp
+.Vb 2
+\&    \-s($file) + 1024   # probably wrong; same as \-s($file + 1024)
+\&    (\-s $file) + 1024  # correct
+.Ve
+.Sp
+The interpretation of the file permission operators \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR,
+\&\f(CW\*(C`\-w\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and \f(CW\*(C`\-X\*(C'\fR is by default based solely on the mode
+of the file and the uids and gids of the user.  There may be other
+reasons you can't actually read, write, or execute the file: for
+example network filesystem access controls, ACLs (access control lists),
+read-only filesystems, and unrecognized executable formats.  Note
+that the use of these six specific operators to verify if some operation
+is possible is usually a mistake, because it may be open to race
+conditions.
+.Sp
+Also note that, for the superuser on the local filesystems, the \f(CW\*(C`\-r\*(C'\fR,
+\&\f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-W\*(C'\fR tests always return 1, and \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR return 1
+if any execute bit is set in the mode.  Scripts run by the superuser
+may thus need to do a \f(CW\*(C`stat\*(C'\fR to determine the
+actual mode of the file, or temporarily set their effective uid to
+something else.
+.Sp
+If you are using ACLs, there is a pragma called \f(CW\*(C`filetest\*(C'\fR
+that may produce more accurate results than the bare
+\&\f(CW\*(C`stat\*(C'\fR mode bits.
+When under \f(CW\*(C`use filetest \*(Aqaccess\*(Aq\*(C'\fR, the above-mentioned filetests
+test whether the permission can(not) be granted using the \fBaccess\fR\|(2)
+family of system calls.  Also note that the \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR tests may
+under this pragma return true even if there are no execute permission
+bits set (nor any extra execute permission ACLs).  This strangeness is
+due to the underlying system calls' definitions.  Note also that, due to
+the implementation of \f(CW\*(C`use filetest \*(Aqaccess\*(Aq\*(C'\fR, the \f(CW\*(C`_\*(C'\fR special
+filehandle won't cache the results of the file tests when this pragma is
+in effect.  Read the documentation for the \f(CW\*(C`filetest\*(C'\fR
+pragma for more information.
+.Sp
+The \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR tests work as follows.  The first block or so of
+the file is examined to see if it is valid UTF\-8 that includes non-ASCII
+characters.  If so, it's a \f(CW\*(C`\-T\*(C'\fR file.  Otherwise, that same portion of
+the file is examined for odd characters such as strange control codes or
+characters with the high bit set.  If more than a third of the
+characters are strange, it's a \f(CW\*(C`\-B\*(C'\fR file; otherwise it's a \f(CW\*(C`\-T\*(C'\fR file.
+Also, any file containing a zero byte in the examined portion is
+considered a binary file.  (If executed within the scope of a use\ locale which includes \f(CW\*(C`LC_CTYPE\*(C'\fR, odd characters are
+anything that isn't a printable nor space in the current locale.)  If
+\&\f(CW\*(C`\-T\*(C'\fR or \f(CW\*(C`\-B\*(C'\fR is used on a filehandle, the current IO buffer is
+examined
+rather than the first block.  Both \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR return true on an empty
+file, or a file at EOF when testing a filehandle.  Because you have to
+read a file to do the \f(CW\*(C`\-T\*(C'\fR test, on most occasions you want to use a \f(CW\*(C`\-f\*(C'\fR
+against the file first, as in \f(CW\*(C`next unless \-f $file && \-T $file\*(C'\fR.
+.Sp
+If any of the file tests (or either the \f(CW\*(C`stat\*(C'\fR or
+\&\f(CW\*(C`lstat\*(C'\fR operator) is given the special filehandle
+consisting of a solitary underline, then the stat structure of the
+previous file test (or \f(CW\*(C`stat\*(C'\fR operator) is used,
+saving a system call.  (This doesn't work with \f(CW\*(C`\-t\*(C'\fR, and you need to
+remember that \f(CW\*(C`lstat\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR leave values in
+the stat structure for the symbolic link, not the real file.)  (Also, if
+the stat buffer was filled by an \f(CW\*(C`lstat\*(C'\fR call,
+\&\f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR will reset it with the results of \f(CW\*(C`stat _\*(C'\fR).
+Example:
+.Sp
+.Vb 1
+\&    print "Can do.\en" if \-r $a || \-w _ || \-x _;
+\&
+\&    stat($filename);
+\&    print "Readable\en" if \-r _;
+\&    print "Writable\en" if \-w _;
+\&    print "Executable\en" if \-x _;
+\&    print "Setuid\en" if \-u _;
+\&    print "Setgid\en" if \-g _;
+\&    print "Sticky\en" if \-k _;
+\&    print "Text\en" if \-T _;
+\&    print "Binary\en" if \-B _;
+.Ve
+.Sp
+As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file
+test operators, in a way that \f(CW\*(C`\-f \-w \-x $file\*(C'\fR is equivalent to
+\&\f(CW\*(C`\-x $file && \-w _ && \-f _\*(C'\fR.  (This is only fancy syntax: if you use
+the return value of \f(CW\*(C`\-f $file\*(C'\fR as an argument to another filetest
+operator, no special magic will happen.)
+.Sp
+Portability issues: "\-X" in perlport.
+.Sp
+To avoid confusing would-be users of your code with mysterious
+syntax errors, put something like this at the top of your script:
+.Sp
+.Vb 1
+\&    use v5.10;  # so filetest ops can stack
+.Ve
+.IP "abs VALUE" 4
+.IX Xref "abs absolute"
+.IX Item "abs VALUE"
+.PD 0
+.IP abs 4
+.IX Item "abs"
+.PD
+Returns the absolute value of its argument.
+If VALUE is omitted, uses \f(CW$_\fR.
+.IP "accept NEWSOCKET,GENERICSOCKET" 4
+.IX Xref "accept"
+.IX Item "accept NEWSOCKET,GENERICSOCKET"
+Accepts an incoming socket connect, just as \fBaccept\fR\|(2)
+does.  Returns the packed address if it succeeded, false otherwise.
+See the example in "Sockets: Client/Server Communication" in perlipc.
+.Sp
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptor, as determined by the
+value of \f(CW$^F\fR.  See "$^F" in perlvar.
+.IP "alarm SECONDS" 4
+.IX Xref "alarm SIGALRM timer"
+.IX Item "alarm SECONDS"
+.PD 0
+.IP alarm 4
+.IX Item "alarm"
+.PD
+Arranges to have a SIGALRM delivered to this process after the
+specified number of wallclock seconds has elapsed.  If SECONDS is not
+specified, the value stored in \f(CW$_\fR is used.  (On some
+machines, unfortunately, the elapsed time may be up to one second less
+or more than you specified because of how seconds are counted, and
+process scheduling may delay the delivery of the signal even further.)
+.Sp
+Only one timer may be counting at once.  Each call disables the
+previous timer, and an argument of \f(CW0\fR may be supplied to cancel the
+previous timer without starting a new one.  The returned value is the
+amount of time remaining on the previous timer.
+.Sp
+For delays of finer granularity than one second, the Time::HiRes module
+(from CPAN, and starting from Perl 5.8 part of the standard
+distribution) provides
+\&\f(CW\*(C`ualarm\*(C'\fR.
+You may also use Perl's four-argument version of
+\&\f(CW\*(C`select\*(C'\fR leaving the first three
+arguments undefined, or you might be able to use the
+\&\f(CW\*(C`syscall\*(C'\fR interface to access \fBsetitimer\fR\|(2)
+if your system supports it.  See perlfaq8 for details.
+.Sp
+It is usually a mistake to intermix \f(CW\*(C`alarm\*(C'\fR and
+\&\f(CW\*(C`sleep\*(C'\fR calls, because \f(CW\*(C`sleep\*(C'\fR may be
+internally implemented on your system with \f(CW\*(C`alarm\*(C'\fR.
+.Sp
+If you want to use \f(CW\*(C`alarm\*(C'\fR to time out a system call
+you need to use an \f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR pair.  You
+can't rely on the alarm causing the system call to fail with
+\&\f(CW$!\fR set to \f(CW\*(C`EINTR\*(C'\fR because Perl sets up signal handlers
+to restart system calls on some systems.  Using
+\&\f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR always works, modulo the
+caveats given in "Signals" in perlipc.
+.Sp
+.Vb 10
+\&    eval {
+\&        local $SIG{ALRM} = sub { die "alarm\en" }; # NB: \en required
+\&        alarm $timeout;
+\&        my $nread = sysread $socket, $buffer, $size;
+\&        alarm 0;
+\&    };
+\&    if ($@) {
+\&        die unless $@ eq "alarm\en";   # propagate unexpected errors
+\&        # timed out
+\&    }
+\&    else {
+\&        # didn\*(Aqt
+\&    }
+.Ve
+.Sp
+For more information see perlipc.
+.Sp
+Portability issues: "alarm" in perlport.
+.IP "atan2 Y,X" 4
+.IX Xref "atan2 arctangent tan tangent"
+.IX Item "atan2 Y,X"
+Returns the arctangent of Y/X in the range \-PI to PI.
+.Sp
+For the tangent operation, you may use the
+\&\f(CW\*(C`Math::Trig::tan\*(C'\fR function, or use the familiar
+relation:
+.Sp
+.Vb 1
+\&    sub tan { sin($_[0]) / cos($_[0])  }
+.Ve
+.Sp
+The return value for \f(CW\*(C`atan2(0,0)\*(C'\fR is implementation-defined; consult
+your \fBatan2\fR\|(3) manpage for more information.
+.Sp
+Portability issues: "atan2" in perlport.
+.IP "bind SOCKET,NAME" 4
+.IX Xref "bind"
+.IX Item "bind SOCKET,NAME"
+Binds a network address to a socket, just as \fBbind\fR\|(2)
+does.  Returns true if it succeeded, false otherwise.  NAME should be a
+packed address of the appropriate type for the socket.  See the examples in
+"Sockets: Client/Server Communication" in perlipc.
+.IP "binmode FILEHANDLE, LAYER" 4
+.IX Xref "binmode binary text DOS Windows"
+.IX Item "binmode FILEHANDLE, LAYER"
+.PD 0
+.IP "binmode FILEHANDLE" 4
+.IX Item "binmode FILEHANDLE"
+.PD
+Arranges for FILEHANDLE to be read or written in "binary" or "text"
+mode on systems where the run-time libraries distinguish between
+binary and text files.  If FILEHANDLE is an expression, the value is
+taken as the name of the filehandle.  Returns true on success,
+otherwise it returns \f(CW\*(C`undef\*(C'\fR and sets
+\&\f(CW$!\fR (errno).
+.Sp
+On some systems (in general, DOS\- and Windows-based systems)
+\&\f(CW\*(C`binmode\*(C'\fR is necessary when you're not
+working with a text file.  For the sake of portability it is a good idea
+always to use it when appropriate, and never to use it when it isn't
+appropriate.  Also, people can set their I/O to be by default
+UTF8\-encoded Unicode, not bytes.
+.Sp
+In other words: regardless of platform, use
+\&\f(CW\*(C`binmode\*(C'\fR on binary data, like images,
+for example.
+.Sp
+If LAYER is present it is a single string, but may contain multiple
+directives.  The directives alter the behaviour of the filehandle.
+When LAYER is present, using binmode on a text file makes sense.
+.Sp
+If LAYER is omitted or specified as \f(CW\*(C`:raw\*(C'\fR the filehandle is made
+suitable for passing binary data.  This includes turning off possible CRLF
+translation and marking it as bytes (as opposed to Unicode characters).
+Note that, despite what may be implied in \fI"Programming Perl"\fR (the
+Camel, 3rd edition) or elsewhere, \f(CW\*(C`:raw\*(C'\fR is \fInot\fR simply the inverse of \f(CW\*(C`:crlf\*(C'\fR.
+Other layers that would affect the binary nature of the stream are
+\&\fIalso\fR disabled.  See PerlIO, and the discussion about the PERLIO
+environment variable in perlrun.
+.Sp
+The \f(CW\*(C`:bytes\*(C'\fR, \f(CW\*(C`:crlf\*(C'\fR, \f(CW\*(C`:utf8\*(C'\fR, and any other directives of the
+form \f(CW\*(C`:...\*(C'\fR, are called I/O \fIlayers\fR.  The open pragma can be used to
+establish default I/O layers.
+.Sp
+\&\fIThe LAYER parameter of the \fR\f(CI\*(C`binmode\*(C'\fR\fI
+function is described as "DISCIPLINE" in "Programming Perl, 3rd
+Edition".  However, since the publishing of this book, by many known as
+"Camel III", the consensus of the naming of this functionality has moved
+from "discipline" to "layer".  All documentation of this version of Perl
+therefore refers to "layers" rather than to "disciplines".  Now back to
+the regularly scheduled documentation...\fR
+.Sp
+To mark FILEHANDLE as UTF\-8, use \f(CW\*(C`:utf8\*(C'\fR or \f(CW:encoding(UTF\-8)\fR.
+\&\f(CW\*(C`:utf8\*(C'\fR just marks the data as UTF\-8 without further checking,
+while \f(CW:encoding(UTF\-8)\fR checks the data for actually being valid
+UTF\-8.  More details can be found in PerlIO::encoding.
+.Sp
+In general, \f(CW\*(C`binmode\*(C'\fR should be called
+after \f(CW\*(C`open\*(C'\fR but before any I/O is done on the
+filehandle.  Calling \f(CW\*(C`binmode\*(C'\fR normally
+flushes any pending buffered output data (and perhaps pending input
+data) on the handle.  An exception to this is the \f(CW\*(C`:encoding\*(C'\fR layer
+that changes the default character encoding of the handle.
+The \f(CW\*(C`:encoding\*(C'\fR layer sometimes needs to be called in
+mid-stream, and it doesn't flush the stream.  \f(CW\*(C`:encoding\*(C'\fR
+also implicitly pushes on top of itself the \f(CW\*(C`:utf8\*(C'\fR layer because
+internally Perl operates on UTF8\-encoded Unicode characters.
+.Sp
+The operating system, device drivers, C libraries, and Perl run-time
+system all conspire to let the programmer treat a single
+character (\f(CW\*(C`\en\*(C'\fR) as the line terminator, irrespective of external
+representation.  On many operating systems, the native text file
+representation matches the internal representation, but on some
+platforms the external representation of \f(CW\*(C`\en\*(C'\fR is made up of more than
+one character.
+.Sp
+All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use
+a single character to end each line in the external representation of text
+(even though that single character is CARRIAGE RETURN on old, pre-Darwin
+flavors of Mac OS, and is LINE FEED on Unix and most VMS files).  In other
+systems like OS/2, DOS, and the various flavors of MS-Windows, your program
+sees a \f(CW\*(C`\en\*(C'\fR as a simple \f(CW\*(C`\ecJ\*(C'\fR, but what's stored in text files are the
+two characters \f(CW\*(C`\ecM\ecJ\*(C'\fR.  That means that if you don't use
+\&\f(CW\*(C`binmode\*(C'\fR on these systems, \f(CW\*(C`\ecM\ecJ\*(C'\fR
+sequences on disk will be converted to \f(CW\*(C`\en\*(C'\fR on input, and any \f(CW\*(C`\en\*(C'\fR in
+your program will be converted back to \f(CW\*(C`\ecM\ecJ\*(C'\fR on output.  This is
+what you want for text files, but it can be disastrous for binary files.
+.Sp
+Another consequence of using \f(CW\*(C`binmode\*(C'\fR
+(on some systems) is that special end-of-file markers will be seen as
+part of the data stream.  For systems from the Microsoft family this
+means that, if your binary data contain \f(CW\*(C`\ecZ\*(C'\fR, the I/O subsystem will
+regard it as the end of the file, unless you use
+\&\f(CW\*(C`binmode\*(C'\fR.
+.Sp
+\&\f(CW\*(C`binmode\*(C'\fR is important not only for
+\&\f(CW\*(C`readline\*(C'\fR and \f(CW\*(C`print\*(C'\fR
+operations, but also when using
+\&\f(CW\*(C`read\*(C'\fR,
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`sysread\*(C'\fR,
+\&\f(CW\*(C`syswrite\*(C'\fR and
+\&\f(CW\*(C`tell\*(C'\fR (see perlport for more details).  See the
+\&\f(CW$/\fR and \f(CW\*(C`$\e\*(C'\fR variables in
+perlvar for how to manually set your input and output
+line-termination sequences.
+.Sp
+Portability issues: "binmode" in perlport.
+.IP "bless REF,CLASSNAME" 4
+.IX Xref "bless"
+.IX Item "bless REF,CLASSNAME"
+.PD 0
+.IP "bless REF" 4
+.IX Item "bless REF"
+.PD
+\&\f(CW\*(C`bless\*(C'\fR tells Perl to mark the item referred to by \f(CW\*(C`REF\*(C'\fR as an
+object in a package.  The two-argument version of \f(CW\*(C`bless\*(C'\fR is
+always preferable unless there is a specific reason to \fInot\fR
+use it.
+.RS 4
+.IP \(bu 4
+Bless the referred-to item into a specific package
+(recommended form):
+.Sp
+.Vb 1
+\&    bless $ref, $package;
+.Ve
+.Sp
+The two-argument form adds the object to the package specified
+as the second argument.
+.IP \(bu 4
+Bless the referred-to item into package \f(CW\*(C`main\*(C'\fR:
+.Sp
+.Vb 1
+\&    bless $ref, "";
+.Ve
+.Sp
+If the second argument is an empty string, \f(CW\*(C`bless\*(C'\fR adds the
+object to package \f(CW\*(C`main\*(C'\fR.
+.IP \(bu 4
+Bless the referred-to item into the current package (not
+inheritable):
+.Sp
+.Vb 1
+\&    bless $ref;
+.Ve
+.Sp
+If \f(CW\*(C`bless\*(C'\fR is used without its second argument, the object is
+created in the current package. The second argument should
+always be supplied if a derived class might inherit a method
+executing \f(CW\*(C`bless\*(C'\fR. Because it is a potential source of bugs,
+one-argument \f(CW\*(C`bless\*(C'\fR is discouraged.
+.RE
+.RS 4
+.Sp
+See perlobj for more about the blessing (and blessings) of
+objects.
+.Sp
+\&\f(CW\*(C`bless\*(C'\fR returns its first argument, the
+supplied reference, as the value of the function; since \f(CW\*(C`bless\*(C'\fR
+is commonly the last thing executed in constructors, this means
+that the reference to the object is returned as the
+constructor's value and allows the caller to immediately use
+this returned object in method calls.
+.Sp
+\&\f(CW\*(C`CLASSNAME\*(C'\fR should always be a mixed-case name, as
+all-uppercase and all-lowercase names are meant to be used only
+for Perl builtin types and pragmas, respectively. Avoid creating
+all-uppercase or all-lowercase package names to prevent
+confusion.
+.Sp
+Also avoid <Cbless>ing things into the class name \f(CW0\fR; this
+will cause code which (erroneously) checks the result of
+\&\f(CW\*(C`ref\*(C'\fR to see if a reference is \f(CW\*(C`bless\*(C'\fRed to fail,
+as "0", a falsy value, is returned.
+.Sp
+See "Perl Modules" in perlmod for more details.
+.RE
+.IP break 4
+.IX Item "break"
+Break out of a \f(CW\*(C`given\*(C'\fR block.
+.Sp
+\&\f(CW\*(C`break\*(C'\fR is available only if the
+\&\f(CW"switch"\fR feature is enabled or if it
+is prefixed with \f(CW\*(C`CORE::\*(C'\fR. The
+\&\f(CW"switch"\fR feature is enabled
+automatically with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current
+scope.
+.IP "caller EXPR" 4
+.IX Xref "caller call stack stack stack trace"
+.IX Item "caller EXPR"
+.PD 0
+.IP caller 4
+.IX Item "caller"
+.PD
+Returns the context of the current pure perl subroutine call.  In scalar
+context, returns the caller's package name if there \fIis\fR a caller (that is, if
+we're in a subroutine or \f(CW\*(C`eval\*(C'\fR or
+\&\f(CW\*(C`require\*(C'\fR) and the undefined value otherwise.
+caller never returns XS subs and they are skipped.  The next pure perl
+sub will appear instead of the XS sub in caller's return values.  In
+list context, caller returns
+.Sp
+.Vb 2
+\&       # 0         1          2
+\&    my ($package, $filename, $line) = caller;
+.Ve
+.Sp
+Like \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, the filename and
+line number returned here may be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.Sp
+With EXPR, it returns some extra information that the debugger uses to
+print a stack trace.  The value of EXPR indicates how many call frames
+to go back before the current one.
+.Sp
+.Vb 2
+\&    #  0         1          2      3            4
+\& my ($package, $filename, $line, $subroutine, $hasargs,
+\&
+\&    #  5          6          7            8       9         10
+\&    $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
+\&  = caller($i);
+.Ve
+.Sp
+Here, \f(CW$subroutine\fR is the function that the caller called (rather than the
+function containing the caller).  Note that \f(CW$subroutine\fR may be \f(CW\*(C`(eval)\*(C'\fR if
+the frame is not a subroutine call, but an \f(CW\*(C`eval\*(C'\fR.  In
+such a case additional elements \f(CW$evaltext\fR and \f(CW$is_require\fR are set:
+\&\f(CW$is_require\fR is true if the frame is created by a
+\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR
+statement, \f(CW$evaltext\fR contains the text of the \f(CW\*(C`eval EXPR\*(C'\fR statement.
+In particular, for an \f(CW\*(C`eval BLOCK\*(C'\fR statement, \f(CW$subroutine\fR is \f(CW\*(C`(eval)\*(C'\fR,
+but \f(CW$evaltext\fR is undefined.  (Note also that each
+\&\f(CW\*(C`use\*(C'\fR statement creates a
+\&\f(CW\*(C`require\*(C'\fR frame inside an \f(CW\*(C`eval EXPR\*(C'\fR frame.)
+\&\f(CW$subroutine\fR may also be \f(CW\*(C`(unknown)\*(C'\fR if this particular subroutine
+happens to have been deleted from the symbol table.  \f(CW$hasargs\fR is true
+if a new instance of \f(CW@_\fR was set up for the frame.
+\&\f(CW$hints\fR and \f(CW$bitmask\fR contain pragmatic hints that the caller was
+compiled with.  \f(CW$hints\fR corresponds to \f(CW$^H\fR, and
+\&\f(CW$bitmask\fR corresponds to
+\&\f(CW\*(C`${^WARNING_BITS}\*(C'\fR.  The \f(CW$hints\fR and
+\&\f(CW$bitmask\fR values are subject to change between versions of Perl, and
+are not meant for external use.
+.Sp
+\&\f(CW$hinthash\fR is a reference to a hash containing the value of
+\&\f(CW\*(C`%^H\*(C'\fR when the caller was compiled, or
+\&\f(CW\*(C`undef\*(C'\fR if \f(CW\*(C`%^H\*(C'\fR was empty.  Do not
+modify the values of this hash, as they are the actual values stored in
+the optree.
+.Sp
+Note that the only types of call frames that are visible are subroutine
+calls and \f(CW\*(C`eval\*(C'\fR. Other forms of context, such as \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`foreach\*(C'\fR
+loops or \f(CW\*(C`try\*(C'\fR blocks are not considered interesting to \f(CW\*(C`caller\*(C'\fR, as they
+do not alter the behaviour of the \f(CW\*(C`return\*(C'\fR expression.
+.Sp
+Furthermore, when called from within the DB package in
+list context, and with an argument, caller returns more
+detailed information: it sets the list variable \f(CW@DB::args\fR to be the
+arguments with which the subroutine was invoked.
+.Sp
+Be aware that the optimizer might have optimized call frames away before
+\&\f(CW\*(C`caller\*(C'\fR had a chance to get the information.  That
+means that \f(CWcaller(N)\fR might not return information about the call
+frame you expect it to, for \f(CW\*(C`N > 1\*(C'\fR.  In particular, \f(CW@DB::args\fR
+might have information from the previous time \f(CW\*(C`caller\*(C'\fR
+was called.
+.Sp
+Be aware that setting \f(CW@DB::args\fR is \fIbest effort\fR, intended for
+debugging or generating backtraces, and should not be relied upon.  In
+particular, as \f(CW@_\fR contains aliases to the caller's
+arguments, Perl does not take a copy of \f(CW@_\fR, so
+\&\f(CW@DB::args\fR will contain modifications the subroutine makes to
+\&\f(CW@_\fR or its contents, not the original values at call
+time.  \f(CW@DB::args\fR, like \f(CW@_\fR, does not hold explicit
+references to its elements, so under certain cases its elements may have
+become freed and reallocated for other variables or temporary values.
+Finally, a side effect of the current implementation is that the effects
+of \f(CW\*(C`shift @_\*(C'\fR can \fInormally\fR be undone (but not \f(CW\*(C`pop @_\*(C'\fR or other
+splicing, \fIand\fR not if a reference to \f(CW@_\fR has been
+taken, \fIand\fR subject to the caveat about reallocated elements), so
+\&\f(CW@DB::args\fR is actually a hybrid of the current state and initial state
+of \f(CW@_\fR.  Buyer beware.
+.IP "chdir EXPR" 4
+.IX Xref "chdir cd directory, change"
+.IX Item "chdir EXPR"
+.PD 0
+.IP "chdir FILEHANDLE" 4
+.IX Item "chdir FILEHANDLE"
+.IP "chdir DIRHANDLE" 4
+.IX Item "chdir DIRHANDLE"
+.IP chdir 4
+.IX Item "chdir"
+.PD
+Changes the working directory to EXPR, if possible.  If EXPR is omitted,
+changes to the directory specified by \f(CW$ENV{HOME}\fR, if set; if not,
+changes to the directory specified by \f(CW$ENV{LOGDIR}\fR.  (Under VMS, the
+variable \f(CW$ENV{\*(AqSYS$LOGIN\*(Aq}\fR is also checked, and used if it is set.)  If
+neither is set, \f(CW\*(C`chdir\*(C'\fR does nothing and fails.  It
+returns true on success, false otherwise.  See the example under
+\&\f(CW\*(C`die\*(C'\fR.
+.Sp
+On systems that support \fBfchdir\fR\|(2), you may pass a filehandle or
+directory handle as the argument.  On systems that don't support \fBfchdir\fR\|(2),
+passing handles raises an exception.
+.IP "chmod LIST" 4
+.IX Xref "chmod permission mode"
+.IX Item "chmod LIST"
+Changes the permissions of a list of files.  The first element of the
+list must be the numeric mode, which should probably be an octal
+number, and which definitely should \fInot\fR be a string of octal digits:
+\&\f(CW0644\fR is okay, but \f(CW"0644"\fR is not.  Returns the number of files
+successfully changed.  See also \f(CW\*(C`oct\*(C'\fR if all you have is a
+string.
+.Sp
+.Vb 6
+\&    my $cnt = chmod 0755, "foo", "bar";
+\&    chmod 0755, @executables;
+\&    my $mode = "0644"; chmod $mode, "foo";      # !!! sets mode to
+\&                                                # \-\-w\-\-\-\-r\-T
+\&    my $mode = "0644"; chmod oct($mode), "foo"; # this is better
+\&    my $mode = 0644;   chmod $mode, "foo";      # this is best
+.Ve
+.Sp
+On systems that support \fBfchmod\fR\|(2), you may pass filehandles among the
+files.  On systems that don't support \fBfchmod\fR\|(2), passing filehandles raises
+an exception.  Filehandles must be passed as globs or glob references to be
+recognized; barewords are considered filenames.
+.Sp
+.Vb 3
+\&    open(my $fh, "<", "foo");
+\&    my $perm = (stat $fh)[2] & 07777;
+\&    chmod($perm | 0600, $fh);
+.Ve
+.Sp
+You can also import the symbolic \f(CW\*(C`S_I*\*(C'\fR constants from the
+\&\f(CW\*(C`Fcntl\*(C'\fR module:
+.Sp
+.Vb 3
+\&    use Fcntl qw( :mode );
+\&    chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
+\&    # Identical to the chmod 0755 of the example above.
+.Ve
+.Sp
+Portability issues: "chmod" in perlport.
+.IP "chomp VARIABLE" 4
+.IX Xref "chomp INPUT_RECORD_SEPARATOR $ newline eol"
+.IX Item "chomp VARIABLE"
+.PD 0
+.IP "chomp( LIST )" 4
+.IX Item "chomp( LIST )"
+.IP chomp 4
+.IX Item "chomp"
+.PD
+This safer version of \f(CW\*(C`chop\*(C'\fR removes any trailing
+string that corresponds to the current value of
+\&\f(CW$/\fR (also known as \f(CW$INPUT_RECORD_SEPARATOR\fR
+in the \f(CW\*(C`English\*(C'\fR module).  It returns the total
+number of characters removed from all its arguments.  It's often used to
+remove the newline from the end of an input record when you're worried
+that the final record may be missing its newline.  When in paragraph
+mode (\f(CW\*(C`$/ = \*(Aq\*(Aq\*(C'\fR), it removes all trailing newlines from the string.
+When in slurp mode (\f(CW\*(C`$/ = undef\*(C'\fR) or fixed-length record mode
+(\f(CW$/\fR is a reference to an integer or the like;
+see perlvar), \f(CW\*(C`chomp\*(C'\fR won't remove anything.
+If VARIABLE is omitted, it chomps \f(CW$_\fR.  Example:
+.Sp
+.Vb 5
+\&    while (<>) {
+\&        chomp;  # avoid \en on last field
+\&        my @array = split(/:/);
+\&        # ...
+\&    }
+.Ve
+.Sp
+If VARIABLE is a hash, it chomps the hash's values, but not its keys,
+resetting the \f(CW\*(C`each\*(C'\fR iterator in the process.
+.Sp
+You can actually chomp anything that's an lvalue, including an assignment:
+.Sp
+.Vb 2
+\&    chomp(my $cwd = \`pwd\`);
+\&    chomp(my $answer = <STDIN>);
+.Ve
+.Sp
+If you chomp a list, each element is chomped, and the total number of
+characters removed is returned.
+.Sp
+Note that parentheses are necessary when you're chomping anything
+that is not a simple variable.  This is because \f(CW\*(C`chomp $cwd = \`pwd\`;\*(C'\fR
+is interpreted as \f(CW\*(C`(chomp $cwd) = \`pwd\`;\*(C'\fR, rather than as
+\&\f(CW\*(C`chomp( $cwd = \`pwd\` )\*(C'\fR which you might expect.  Similarly,
+\&\f(CW\*(C`chomp $a, $b\*(C'\fR is interpreted as \f(CW\*(C`chomp($a), $b\*(C'\fR rather than
+as \f(CW\*(C`chomp($a, $b)\*(C'\fR.
+.IP "chop VARIABLE" 4
+.IX Xref "chop"
+.IX Item "chop VARIABLE"
+.PD 0
+.IP "chop( LIST )" 4
+.IX Item "chop( LIST )"
+.IP chop 4
+.IX Item "chop"
+.PD
+Chops off the last character of a string and returns the character
+chopped.  It is much more efficient than \f(CW\*(C`s/.$//s\*(C'\fR because it neither
+scans nor copies the string.  If VARIABLE is omitted, chops
+\&\f(CW$_\fR.
+If VARIABLE is a hash, it chops the hash's values, but not its keys,
+resetting the \f(CW\*(C`each\*(C'\fR iterator in the process.
+.Sp
+You can actually chop anything that's an lvalue, including an assignment.
+.Sp
+If you chop a list, each element is chopped.  Only the value of the
+last \f(CW\*(C`chop\*(C'\fR is returned.
+.Sp
+Note that \f(CW\*(C`chop\*(C'\fR returns the last character.  To
+return all but the last character, use \f(CW\*(C`substr($string, 0, \-1)\*(C'\fR.
+.Sp
+See also \f(CW\*(C`chomp\*(C'\fR.
+.IP "chown LIST" 4
+.IX Xref "chown owner user group"
+.IX Item "chown LIST"
+Changes the owner (and group) of a list of files.  The first two
+elements of the list must be the \fInumeric\fR uid and gid, in that
+order.  A value of \-1 in either position is interpreted by most
+systems to leave that value unchanged.  Returns the number of files
+successfully changed.
+.Sp
+.Vb 2
+\&    my $cnt = chown $uid, $gid, \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq;
+\&    chown $uid, $gid, @filenames;
+.Ve
+.Sp
+On systems that support \fBfchown\fR\|(2), you may pass filehandles among the
+files.  On systems that don't support \fBfchown\fR\|(2), passing filehandles raises
+an exception.  Filehandles must be passed as globs or glob references to be
+recognized; barewords are considered filenames.
+.Sp
+Here's an example that looks up nonnumeric uids in the passwd file:
+.Sp
+.Vb 4
+\&    print "User: ";
+\&    chomp(my $user = <STDIN>);
+\&    print "Files: ";
+\&    chomp(my $pattern = <STDIN>);
+\&
+\&    my ($login,$pass,$uid,$gid) = getpwnam($user)
+\&        or die "$user not in passwd file";
+\&
+\&    my @ary = glob($pattern);  # expand filenames
+\&    chown $uid, $gid, @ary;
+.Ve
+.Sp
+On most systems, you are not allowed to change the ownership of the
+file unless you're the superuser, although you should be able to change
+the group to any of your secondary groups.  On insecure systems, these
+restrictions may be relaxed, but this is not a portable assumption.
+On POSIX systems, you can detect this condition this way:
+.Sp
+.Vb 2
+\&    use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
+\&    my $can_chown_giveaway = ! sysconf(_PC_CHOWN_RESTRICTED);
+.Ve
+.Sp
+Portability issues: "chown" in perlport.
+.IP "chr NUMBER" 4
+.IX Xref "chr character ASCII Unicode"
+.IX Item "chr NUMBER"
+.PD 0
+.IP chr 4
+.IX Item "chr"
+.PD
+Returns the character represented by that NUMBER in the character set.
+For example, \f(CWchr(65)\fR is \f(CW"A"\fR in either ASCII or Unicode, and
+chr(0x263a) is a Unicode smiley face.
+.Sp
+Negative values give the Unicode replacement character (\fBchr\fR\|(0xfffd)),
+except under the bytes pragma, where the low eight bits of the value
+(truncated to an integer) are used.
+.Sp
+If NUMBER is omitted, uses \f(CW$_\fR.
+.Sp
+For the reverse, use \f(CW\*(C`ord\*(C'\fR.
+.Sp
+Note that characters from 128 to 255 (inclusive) are by default
+internally not encoded as UTF\-8 for backward compatibility reasons.
+.Sp
+See perlunicode for more about Unicode.
+.IP "chroot FILENAME" 4
+.IX Xref "chroot root"
+.IX Item "chroot FILENAME"
+.PD 0
+.IP chroot 4
+.IX Item "chroot"
+.PD
+This function works like the system call by the same name: it makes the
+named directory the new root directory for all further pathnames that
+begin with a \f(CW\*(C`/\*(C'\fR by your process and all its children.  (It doesn't
+change your current working directory, which is unaffected.)  For security
+reasons, this call is restricted to the superuser.  If FILENAME is
+omitted, does a \f(CW\*(C`chroot\*(C'\fR to \f(CW$_\fR.
+.Sp
+\&\fBNOTE:\fR  It is mandatory for security to \f(CWchdir("/")\fR
+(\f(CW\*(C`chdir\*(C'\fR to the root directory) immediately after a
+\&\f(CW\*(C`chroot\*(C'\fR, otherwise the current working directory
+may be outside of the new root.
+.Sp
+Portability issues: "chroot" in perlport.
+.IP "class NAMESPACE" 4
+.IX Item "class NAMESPACE"
+.PD 0
+.IP "class NAMESPACE VERSION" 4
+.IX Item "class NAMESPACE VERSION"
+.IP "class NAMESPACE BLOCK" 4
+.IX Item "class NAMESPACE BLOCK"
+.IP "class NAMESPACE VERSION BLOCK" 4
+.IX Item "class NAMESPACE VERSION BLOCK"
+.PD
+Declares the BLOCK or the rest of the compilation unit as being in the given
+namespace, which implements an object class.  This behaves similarly to
+\&\f(CW\*(C`package\*(C'\fR, except that the newly-created package behaves
+as a class.
+.IP "close FILEHANDLE" 4
+.IX Xref "close"
+.IX Item "close FILEHANDLE"
+.PD 0
+.IP close 4
+.IX Item "close"
+.PD
+Closes the file or pipe associated with the filehandle, flushes the IO
+buffers, and closes the system file descriptor.  Returns true if those
+operations succeed and if no error was reported by any PerlIO
+layer.  Closes the currently selected filehandle if the argument is
+omitted.
+.Sp
+You don't have to close FILEHANDLE if you are immediately going to do
+another \f(CW\*(C`open\*(C'\fR on it, because
+\&\f(CW\*(C`open\*(C'\fR closes it for you.  (See
+\&\f(CW\*(C`open\*(C'\fR.) However, an explicit
+\&\f(CW\*(C`close\*(C'\fR on an input file resets the line counter
+(\f(CW$.\fR), while the implicit close done by
+\&\f(CW\*(C`open\*(C'\fR does not.
+.Sp
+If the filehandle came from a piped open, \f(CW\*(C`close\*(C'\fR
+returns false if one of the other syscalls involved fails or if its
+program exits with non-zero status.  If the only problem was that the
+program exited non-zero, \f(CW$!\fR will be set to \f(CW0\fR.
+Closing a pipe also waits for the process executing on the pipe to
+exit\-\-in case you wish to look at the output of the pipe afterwards\-\-and
+implicitly puts the exit status value of that command into
+\&\f(CW$?\fR and
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR.
+.Sp
+If there are multiple threads running, \f(CW\*(C`close\*(C'\fR on
+a filehandle from a piped open returns true without waiting for the
+child process to terminate, if the filehandle is still open in another
+thread.
+.Sp
+Closing the read end of a pipe before the process writing to it at the
+other end is done writing results in the writer receiving a SIGPIPE.  If
+the other end can't handle that, be sure to read all the data before
+closing the pipe.
+.Sp
+Example:
+.Sp
+.Vb 8
+\&    open(OUTPUT, \*(Aq|sort >foo\*(Aq)  # pipe to sort
+\&        or die "Can\*(Aqt start sort: $!";
+\&    #...                        # print stuff to output
+\&    close OUTPUT                # wait for sort to finish
+\&        or warn $! ? "Error closing sort pipe: $!"
+\&                   : "Exit status $? from sort";
+\&    open(INPUT, \*(Aqfoo\*(Aq)          # get sort\*(Aqs results
+\&        or die "Can\*(Aqt open \*(Aqfoo\*(Aq for input: $!";
+.Ve
+.Sp
+FILEHANDLE may be an expression whose value can be used as an indirect
+filehandle, usually the real filehandle name or an autovivified handle.
+.IP "closedir DIRHANDLE" 4
+.IX Xref "closedir"
+.IX Item "closedir DIRHANDLE"
+Closes a directory opened by \f(CW\*(C`opendir\*(C'\fR and
+returns the success of that system call.
+.IP "connect SOCKET,NAME" 4
+.IX Xref "connect"
+.IX Item "connect SOCKET,NAME"
+Attempts to connect to a remote socket, just like \fBconnect\fR\|(2).
+Returns true if it succeeded, false otherwise.  NAME should be a
+packed address of the appropriate type for the socket.  See the examples in
+"Sockets: Client/Server Communication" in perlipc.
+.IP "continue BLOCK" 4
+.IX Xref "continue"
+.IX Item "continue BLOCK"
+.PD 0
+.IP continue 4
+.IX Item "continue"
+.PD
+When followed by a BLOCK, \f(CW\*(C`continue\*(C'\fR is actually a
+flow control statement rather than a function.  If there is a
+\&\f(CW\*(C`continue\*(C'\fR BLOCK attached to a BLOCK (typically in a
+\&\f(CW\*(C`while\*(C'\fR or \f(CW\*(C`foreach\*(C'\fR), it is always executed just before the
+conditional is about to be evaluated again, just like the third part of
+a \f(CW\*(C`for\*(C'\fR loop in C.  Thus it can be used to increment a loop variable,
+even when the loop has been continued via the \f(CW\*(C`next\*(C'\fR
+statement (which is similar to the C \f(CW\*(C`continue\*(C'\fR
+statement).
+.Sp
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, or
+\&\f(CW\*(C`redo\*(C'\fR may appear within a
+\&\f(CW\*(C`continue\*(C'\fR block; \f(CW\*(C`last\*(C'\fR and
+\&\f(CW\*(C`redo\*(C'\fR behave as if they had been executed within the
+main block.  So will \f(CW\*(C`next\*(C'\fR, but since it will execute a
+\&\f(CW\*(C`continue\*(C'\fR block, it may be more entertaining.
+.Sp
+.Vb 9
+\&    while (EXPR) {
+\&        ### redo always comes here
+\&        do_something;
+\&    } continue {
+\&        ### next always comes here
+\&        do_something_else;
+\&        # then back the top to re\-check EXPR
+\&    }
+\&    ### last always comes here
+.Ve
+.Sp
+Omitting the \f(CW\*(C`continue\*(C'\fR section is equivalent to
+using an empty one, logically enough, so \f(CW\*(C`next\*(C'\fR goes
+directly back to check the condition at the top of the loop.
+.Sp
+When there is no BLOCK, \f(CW\*(C`continue\*(C'\fR is a function
+that falls through the current \f(CW\*(C`when\*(C'\fR or \f(CW\*(C`default\*(C'\fR block instead of
+iterating a dynamically enclosing \f(CW\*(C`foreach\*(C'\fR or exiting a lexically
+enclosing \f(CW\*(C`given\*(C'\fR.  In Perl 5.14 and earlier, this form of
+\&\f(CW\*(C`continue\*(C'\fR was only available when the
+\&\f(CW"switch"\fR feature was enabled.  See
+feature and "Switch Statements" in perlsyn for more information.
+.IP "cos EXPR" 4
+.IX Xref "cos cosine acos arccosine"
+.IX Item "cos EXPR"
+.PD 0
+.IP cos 4
+.IX Item "cos"
+.PD
+Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
+takes the cosine of \f(CW$_\fR.
+.Sp
+For the inverse cosine operation, you may use the
+\&\f(CW\*(C`Math::Trig::acos\*(C'\fR function, or use this relation:
+.Sp
+.Vb 1
+\&    sub acos { atan2( sqrt(1 \- $_[0] * $_[0]), $_[0] ) }
+.Ve
+.IP "crypt PLAINTEXT,SALT" 4
+.IX Xref "crypt digest hash salt plaintext password decrypt cryptography passwd encrypt"
+.IX Item "crypt PLAINTEXT,SALT"
+Creates a digest string exactly like the \fBcrypt\fR\|(3) function in the C
+library (assuming that you actually have a version there that has not
+been extirpated as a potential munition).
+.Sp
+\&\f(CW\*(C`crypt\*(C'\fR is a one-way hash function.  The
+PLAINTEXT and SALT are turned
+into a short string, called a digest, which is returned.  The same
+PLAINTEXT and SALT will always return the same string, but there is no
+(known) way to get the original PLAINTEXT from the hash.  Small
+changes in the PLAINTEXT or SALT will result in large changes in the
+digest.
+.Sp
+There is no decrypt function.  This function isn't all that useful for
+cryptography (for that, look for \fICrypt\fR modules on your nearby CPAN
+mirror) and the name "crypt" is a bit of a misnomer.  Instead it is
+primarily used to check if two pieces of text are the same without
+having to transmit or store the text itself.  An example is checking
+if a correct password is given.  The digest of the password is stored,
+not the password itself.  The user types in a password that is
+\&\f(CW\*(C`crypt\*(C'\fR'd with the same salt as the stored
+digest.  If the two digests match, the password is correct.
+.Sp
+When verifying an existing digest string you should use the digest as
+the salt (like \f(CW\*(C`crypt($plain, $digest) eq $digest\*(C'\fR).  The SALT used
+to create the digest is visible as part of the digest.  This ensures
+\&\f(CW\*(C`crypt\*(C'\fR will hash the new string with the same
+salt as the digest.  This allows your code to work with the standard
+\&\f(CW\*(C`crypt\*(C'\fR and with more exotic implementations.
+In other words, assume nothing about the returned string itself nor
+about how many bytes of SALT may matter.
+.Sp
+Traditionally the result is a string of 13 bytes: two first bytes of
+the salt, followed by 11 bytes from the set \f(CW\*(C`[./0\-9A\-Za\-z]\*(C'\fR, and only
+the first eight bytes of PLAINTEXT mattered.  But alternative
+hashing schemes (like MD5), higher level security schemes (like C2),
+and implementations on non-Unix platforms may produce different
+strings.
+.Sp
+When choosing a new salt create a random two character string whose
+characters come from the set \f(CW\*(C`[./0\-9A\-Za\-z]\*(C'\fR (like \f(CW\*(C`join \*(Aq\*(Aq, (\*(Aq.\*(Aq,
+\&\*(Aq/\*(Aq, 0..9, \*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq)[rand 64, rand 64]\*(C'\fR).  This set of
+characters is just a recommendation; the characters allowed in
+the salt depend solely on your system's crypt library, and Perl can't
+restrict what salts \f(CW\*(C`crypt\*(C'\fR accepts.
+.Sp
+Here's an example that makes sure that whoever runs this program knows
+their password:
+.Sp
+.Vb 1
+\&    my $pwd = (getpwuid($<))[1];
+\&
+\&    system "stty \-echo";
+\&    print "Password: ";
+\&    chomp(my $word = <STDIN>);
+\&    print "\en";
+\&    system "stty echo";
+\&
+\&    if (crypt($word, $pwd) ne $pwd) {
+\&        die "Sorry...\en";
+\&    } else {
+\&        print "ok\en";
+\&    }
+.Ve
+.Sp
+Of course, typing in your own password to whoever asks you
+for it is unwise.
+.Sp
+The \f(CW\*(C`crypt\*(C'\fR function is unsuitable for hashing
+large quantities of data, not least of all because you can't get the
+information back.  Look at the Digest module for more robust
+algorithms.
+.Sp
+If using \f(CW\*(C`crypt\*(C'\fR on a Unicode string (which
+\&\fIpotentially\fR has characters with codepoints above 255), Perl tries to
+make sense of the situation by trying to downgrade (a copy of) the
+string back to an eight-bit byte string before calling
+\&\f(CW\*(C`crypt\*(C'\fR (on that copy).  If that works, good.
+If not, \f(CW\*(C`crypt\*(C'\fR dies with
+\&\f(CW\*(C`Wide character in crypt\*(C'\fR.
+.Sp
+Portability issues: "crypt" in perlport.
+.IP "dbmclose HASH" 4
+.IX Xref "dbmclose"
+.IX Item "dbmclose HASH"
+[This function has been largely superseded by the
+\&\f(CW\*(C`untie\*(C'\fR function.]
+.Sp
+Breaks the binding between a DBM file and a hash.
+.Sp
+Portability issues: "dbmclose" in perlport.
+.IP "dbmopen HASH,DBNAME,MASK" 4
+.IX Xref "dbmopen dbm ndbm sdbm gdbm"
+.IX Item "dbmopen HASH,DBNAME,MASK"
+[This function has been largely superseded by the
+\&\f(CW\*(C`tie\*(C'\fR function.]
+.Sp
+This binds a \fBdbm\fR\|(3), \fBndbm\fR\|(3), \fBsdbm\fR\|(3), \fBgdbm\fR\|(3), or Berkeley
+DB file to a hash.  HASH is the name of the hash.  (Unlike normal
+\&\f(CW\*(C`open\*(C'\fR, the first argument is \fInot\fR a
+filehandle, even though it looks like one).  DBNAME is the name of the
+database (without the \fI.dir\fR or \fI.pag\fR extension if any).  If the
+database does not exist, it is created with protection specified by MASK
+(as modified by the \f(CW\*(C`umask\*(C'\fR).  To prevent creation of
+the database if it doesn't exist, you may specify a MASK of 0, and the
+function will return a false value if it can't find an existing
+database.  If your system supports only the older DBM functions, you may
+make only one \f(CW\*(C`dbmopen\*(C'\fR call in your
+program.  In older versions of Perl, if your system had neither DBM nor
+ndbm, calling \f(CW\*(C`dbmopen\*(C'\fR produced a fatal
+error; it now falls back to \fBsdbm\fR\|(3).
+.Sp
+If you don't have write access to the DBM file, you can only read hash
+variables, not set them.  If you want to test whether you can write,
+either use file tests or try setting a dummy hash entry inside an
+\&\f(CW\*(C`eval\*(C'\fR to trap the error.
+.Sp
+Note that functions such as \f(CW\*(C`keys\*(C'\fR and
+\&\f(CW\*(C`values\*(C'\fR may return huge lists when used on large DBM
+files.  You may prefer to use the \f(CW\*(C`each\*(C'\fR function to
+iterate over large DBM files.  Example:
+.Sp
+.Vb 6
+\&    # print out history file offsets
+\&    dbmopen(%HIST,\*(Aq/usr/lib/news/history\*(Aq,0666);
+\&    while (($key,$val) = each %HIST) {
+\&        print $key, \*(Aq = \*(Aq, unpack(\*(AqL\*(Aq,$val), "\en";
+\&    }
+\&    dbmclose(%HIST);
+.Ve
+.Sp
+See also AnyDBM_File for a more general description of the pros and
+cons of the various dbm approaches, as well as DB_File for a particularly
+rich implementation.
+.Sp
+You can control which DBM library you use by loading that library
+before you call \f(CW\*(C`dbmopen\*(C'\fR:
+.Sp
+.Vb 3
+\&    use DB_File;
+\&    dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
+\&        or die "Can\*(Aqt open netscape history file: $!";
+.Ve
+.Sp
+Portability issues: "dbmopen" in perlport.
+.IP "defined EXPR" 4
+.IX Xref "defined undef undefined"
+.IX Item "defined EXPR"
+.PD 0
+.IP defined 4
+.IX Item "defined"
+.PD
+Returns a Boolean value telling whether EXPR has a value other than the
+undefined value \f(CW\*(C`undef\*(C'\fR.  If EXPR is not present,
+\&\f(CW$_\fR is checked.
+.Sp
+Many operations return \f(CW\*(C`undef\*(C'\fR to indicate failure, end
+of file, system error, uninitialized variable, and other exceptional
+conditions.  This function allows you to distinguish
+\&\f(CW\*(C`undef\*(C'\fR from other values.  (A simple Boolean test will
+not distinguish among \f(CW\*(C`undef\*(C'\fR, zero, the empty string,
+and \f(CW"0"\fR, which are all equally false.)  Note that since
+\&\f(CW\*(C`undef\*(C'\fR is a valid scalar, its presence doesn't
+\&\fInecessarily\fR indicate an exceptional condition: \f(CW\*(C`pop\*(C'\fR
+returns \f(CW\*(C`undef\*(C'\fR when its argument is an empty array,
+\&\fIor\fR when the element to return happens to be \f(CW\*(C`undef\*(C'\fR.
+.Sp
+You may also use \f(CWdefined(&func)\fR to check whether subroutine \f(CW\*(C`func\*(C'\fR
+has ever been defined.  The return value is unaffected by any forward
+declarations of \f(CW\*(C`func\*(C'\fR.  A subroutine that is not defined
+may still be callable: its package may have an \f(CW\*(C`AUTOLOAD\*(C'\fR method that
+makes it spring into existence the first time that it is called; see
+perlsub.
+.Sp
+Use of \f(CW\*(C`defined\*(C'\fR on aggregates (hashes and arrays) is
+no longer supported. It used to report whether memory for that
+aggregate had ever been allocated.  You should instead use a simple
+test for size:
+.Sp
+.Vb 2
+\&    if (@an_array) { print "has array elements\en" }
+\&    if (%a_hash)   { print "has hash members\en"   }
+.Ve
+.Sp
+When used on a hash element, it tells you whether the value is defined,
+not whether the key exists in the hash.  Use \f(CW\*(C`exists\*(C'\fR
+for the latter purpose.
+.Sp
+Examples:
+.Sp
+.Vb 6
+\&    print if defined $switch{D};
+\&    print "$val\en" while defined($val = pop(@ary));
+\&    die "Can\*(Aqt readlink $sym: $!"
+\&        unless defined($value = readlink $sym);
+\&    sub foo { defined &$bar ? $bar\->(@_) : die "No bar"; }
+\&    $debugging = 0 unless defined $debugging;
+.Ve
+.Sp
+Note:  Many folks tend to overuse \f(CW\*(C`defined\*(C'\fR and are
+then surprised to discover that the number \f(CW0\fR and \f(CW""\fR (the
+zero-length string) are, in fact, defined values.  For example, if you
+say
+.Sp
+.Vb 1
+\&    "ab" =~ /a(.*)b/;
+.Ve
+.Sp
+The pattern match succeeds and \f(CW$1\fR is defined, although it
+matched "nothing".  It didn't really fail to match anything.  Rather, it
+matched something that happened to be zero characters long.  This is all
+very above-board and honest.  When a function returns an undefined value,
+it's an admission that it couldn't give you an honest answer.  So you
+should use \f(CW\*(C`defined\*(C'\fR only when questioning the
+integrity of what you're trying to do.  At other times, a simple
+comparison to \f(CW0\fR or \f(CW""\fR is what you want.
+.Sp
+See also \f(CW\*(C`undef\*(C'\fR, \f(CW\*(C`exists\*(C'\fR,
+\&\f(CW\*(C`ref\*(C'\fR.
+.IP "delete EXPR" 4
+.IX Xref "delete"
+.IX Item "delete EXPR"
+Given an expression that specifies an element or slice of a hash,
+\&\f(CW\*(C`delete\*(C'\fR deletes the specified elements from that hash
+so that \f(CW\*(C`exists\*(C'\fR on that element no longer returns
+true.  Setting a hash element to the undefined value does not remove its
+key, but deleting it does; see \f(CW\*(C`exists\*(C'\fR.
+.Sp
+In list context, usually returns the value or values deleted, or the last such
+element in scalar context.  The return list's length corresponds to that of
+the argument list: deleting non-existent elements returns the undefined value
+in their corresponding positions. Since Perl 5.28, a
+key/value hash slice can be passed
+to \f(CW\*(C`delete\*(C'\fR, and the return value is a list of key/value pairs (two elements
+for each item deleted from the hash).
+.Sp
+\&\f(CW\*(C`delete\*(C'\fR may also be used on arrays and array slices,
+but its behavior is less straightforward.  Although
+\&\f(CW\*(C`exists\*(C'\fR will return false for deleted entries,
+deleting array elements never changes indices of existing values; use
+\&\f(CW\*(C`shift\*(C'\fR or \f(CW\*(C`splice\*(C'\fR for that.  However, if any deleted elements
+fall at the end of an array, the array's size shrinks to the position of
+the highest element that still tests true for \f(CW\*(C`exists\*(C'\fR,
+or to 0 if none do.  In other words, an array won't have trailing
+nonexistent elements after a delete.
+.Sp
+\&\fBWARNING:\fR Calling \f(CW\*(C`delete\*(C'\fR on array values is
+strongly discouraged.  The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
+.Sp
+Deleting from \f(CW%ENV\fR modifies the environment.
+Deleting from a hash tied to a DBM file deletes the entry from the DBM
+file.  Deleting from a \f(CW\*(C`tied\*(C'\fR hash or array may not
+necessarily return anything; it depends on the implementation of the
+\&\f(CW\*(C`tied\*(C'\fR package's DELETE method, which may do whatever
+it pleases.
+.Sp
+The \f(CW\*(C`delete local EXPR\*(C'\fR construct localizes the deletion to the current
+block at run time.  Until the block exits, elements locally deleted
+temporarily no longer exist.  See "Localized deletion of elements
+of composite types" in perlsub.
+.Sp
+.Vb 4
+\&    my %hash = (foo => 11, bar => 22, baz => 33);
+\&    my $scalar = delete $hash{foo};         # $scalar is 11
+\&    $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
+\&    my @array  = delete @hash{qw(foo baz)}; # @array  is (undef,33)
+.Ve
+.Sp
+The following (inefficiently) deletes all the values of \f(CW%HASH\fR and \f(CW@ARRAY:\fR
+.Sp
+.Vb 3
+\&    foreach my $key (keys %HASH) {
+\&        delete $HASH{$key};
+\&    }
+\&
+\&    foreach my $index (0 .. $#ARRAY) {
+\&        delete $ARRAY[$index];
+\&    }
+.Ve
+.Sp
+And so do these:
+.Sp
+.Vb 1
+\&    delete @HASH{keys %HASH};
+\&
+\&    delete @ARRAY[0 .. $#ARRAY];
+.Ve
+.Sp
+But both are slower than assigning the empty list
+or undefining \f(CW%HASH\fR or \f(CW@ARRAY\fR, which is the customary
+way to empty out an aggregate:
+.Sp
+.Vb 2
+\&    %HASH = ();     # completely empty %HASH
+\&    undef %HASH;    # forget %HASH ever existed
+\&
+\&    @ARRAY = ();    # completely empty @ARRAY
+\&    undef @ARRAY;   # forget @ARRAY ever existed
+.Ve
+.Sp
+The EXPR can be arbitrarily complicated provided its
+final operation is an element or slice of an aggregate:
+.Sp
+.Vb 2
+\&    delete $ref\->[$x][$y]{$key};
+\&    delete $ref\->[$x][$y]\->@{$key1, $key2, @morekeys};
+\&
+\&    delete $ref\->[$x][$y][$index];
+\&    delete $ref\->[$x][$y]\->@[$index1, $index2, @moreindices];
+.Ve
+.IP "die LIST" 4
+.IX Xref "die throw exception raise $@ abort"
+.IX Item "die LIST"
+\&\f(CW\*(C`die\*(C'\fR raises an exception.  Inside an \f(CW\*(C`eval\*(C'\fR
+the exception is stuffed into \f(CW$@\fR and the \f(CW\*(C`eval\*(C'\fR is terminated with the undefined value.  If the exception is
+outside of all enclosing \f(CW\*(C`eval\*(C'\fRs, then the uncaught
+exception is printed to \f(CW\*(C`STDERR\*(C'\fR and perl exits with an exit code
+indicating failure.  If you need to exit the process with a specific
+exit code, see \f(CW\*(C`exit\*(C'\fR.
+.Sp
+Equivalent examples:
+.Sp
+.Vb 2
+\&    die "Can\*(Aqt cd to spool: $!\en" unless chdir \*(Aq/usr/spool/news\*(Aq;
+\&    chdir \*(Aq/usr/spool/news\*(Aq or die "Can\*(Aqt cd to spool: $!\en"
+.Ve
+.Sp
+Most of the time, \f(CW\*(C`die\*(C'\fR is called with a string to use as the exception.
+You may either give a single non-reference operand to serve as the
+exception, or a list of two or more items, which will be stringified
+and concatenated to make the exception.
+.Sp
+If the string exception does not end in a newline, the current
+script line number and input line number (if any) and a newline
+are appended to it.  Note that the "input line number" (also
+known as "chunk") is subject to whatever notion of "line" happens to
+be currently in effect, and is also available as the special variable
+\&\f(CW$.\fR.  See "$/" in perlvar and "$." in perlvar.
+.Sp
+Hint: sometimes appending \f(CW", stopped"\fR to your message will cause it
+to make better sense when the string \f(CW"at foo line 123"\fR is appended.
+Suppose you are running script "canasta".
+.Sp
+.Vb 2
+\&    die "/etc/games is no good";
+\&    die "/etc/games is no good, stopped";
+.Ve
+.Sp
+produce, respectively
+.Sp
+.Vb 2
+\&    /etc/games is no good at canasta line 123.
+\&    /etc/games is no good, stopped at canasta line 123.
+.Ve
+.Sp
+If LIST was empty or made an empty string, and \f(CW$@\fR
+already contains an exception value (typically from a previous
+\&\f(CW\*(C`eval\*(C'\fR), then that value is reused after
+appending \f(CW"\et...propagated"\fR.  This is useful for propagating exceptions:
+.Sp
+.Vb 2
+\&    eval { ... };
+\&    die unless $@ =~ /Expected exception/;
+.Ve
+.Sp
+If LIST was empty or made an empty string,
+and \f(CW$@\fR contains an object
+reference that has a \f(CW\*(C`PROPAGATE\*(C'\fR method, that method will be called
+with additional file and line number parameters.  The return value
+replaces the value in \f(CW$@\fR;  i.e., as if
+\&\f(CW\*(C`$@ = eval { $@\->PROPAGATE(_\|_FILE_\|_, _\|_LINE_\|_) };\*(C'\fR were called.
+.Sp
+If LIST was empty or made an empty string, and \f(CW$@\fR
+is also empty, then the string \f(CW"Died"\fR is used.
+.Sp
+You can also call \f(CW\*(C`die\*(C'\fR with a reference argument, and if
+this is trapped within an \f(CW\*(C`eval\*(C'\fR, \f(CW$@\fR
+contains that reference.  This permits more elaborate exception handling
+using objects that maintain arbitrary state about the exception.  Such a
+scheme is sometimes preferable to matching particular string values of
+\&\f(CW$@\fR with regular expressions.
+.Sp
+Because Perl stringifies uncaught exception messages before display,
+you'll probably want to overload stringification operations on
+exception objects.  See overload for details about that.
+The stringified message should be non-empty, and should end in a newline,
+in order to fit in with the treatment of string exceptions.
+Also, because an exception object reference cannot be stringified
+without destroying it, Perl doesn't attempt to append location or other
+information to a reference exception.  If you want location information
+with a complex exception object, you'll have to arrange to put the
+location information into the object yourself.
+.Sp
+Because \f(CW$@\fR is a global variable, be careful that
+analyzing an exception caught by \f(CW\*(C`eval\*(C'\fR doesn't replace the reference
+in the global variable.  It's
+easiest to make a local copy of the reference before any manipulations.
+Here's an example:
+.Sp
+.Vb 1
+\&    use Scalar::Util "blessed";
+\&
+\&    eval { ... ; die Some::Module::Exception\->new( FOO => "bar" ) };
+\&    if (my $ev_err = $@) {
+\&        if (blessed($ev_err)
+\&            && $ev_err\->isa("Some::Module::Exception")) {
+\&            # handle Some::Module::Exception
+\&        }
+\&        else {
+\&            # handle all other possible exceptions
+\&        }
+\&    }
+.Ve
+.Sp
+If an uncaught exception results in interpreter exit, the exit code is
+determined from the values of \f(CW$!\fR and
+\&\f(CW$?\fR with this pseudocode:
+.Sp
+.Vb 3
+\&    exit $! if $!;              # errno
+\&    exit $? >> 8 if $? >> 8;    # child exit status
+\&    exit 255;                   # last resort
+.Ve
+.Sp
+As with \f(CW\*(C`exit\*(C'\fR, \f(CW$?\fR is set prior to
+unwinding the call stack; any \f(CW\*(C`DESTROY\*(C'\fR or \f(CW\*(C`END\*(C'\fR handlers can then
+alter this value, and thus Perl's exit code.
+.Sp
+The intent is to squeeze as much possible information about the likely cause
+into the limited space of the system exit code.  However, as
+\&\f(CW$!\fR is the value of C's \f(CW\*(C`errno\*(C'\fR, which can be set by
+any system call, this means that the value of the exit code used by
+\&\f(CW\*(C`die\*(C'\fR can be non-predictable, so should not be relied
+upon, other than to be non-zero.
+.Sp
+You can arrange for a callback to be run just before the
+\&\f(CW\*(C`die\*(C'\fR does its deed, by setting the
+\&\f(CW$SIG{_\|_DIE_\|_}\fR hook.  The associated handler is called
+with the exception as an argument, and can change the exception,
+if it sees fit, by
+calling \f(CW\*(C`die\*(C'\fR again.  See "%SIG" in perlvar for details on
+setting \f(CW%SIG\fR entries, and \f(CW\*(C`eval\*(C'\fR for some
+examples.  Although this feature was to be run only right before your
+program was to exit, this is not currently so: the
+\&\f(CW$SIG{_\|_DIE_\|_}\fR hook is currently called even inside
+\&\f(CW\*(C`eval\*(C'\fRed blocks/strings!  If one wants the hook to do
+nothing in such situations, put
+.Sp
+.Vb 1
+\&    die @_ if $^S;
+.Ve
+.Sp
+as the first line of the handler (see "$^S" in perlvar).  Because
+this promotes strange action at a distance, this counterintuitive
+behavior may be fixed in a future release.
+.Sp
+See also \f(CW\*(C`exit\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, and the Carp
+module.
+.IP "do BLOCK" 4
+.IX Xref "do block"
+.IX Item "do BLOCK"
+Not really a function.  Returns the value of the last command in the
+sequence of commands indicated by BLOCK.  When modified by the \f(CW\*(C`while\*(C'\fR or
+\&\f(CW\*(C`until\*(C'\fR loop modifier, executes the BLOCK once before testing the loop
+condition.  (On other statements the loop modifiers test the conditional
+first.)
+.Sp
+\&\f(CW\*(C`do BLOCK\*(C'\fR does \fInot\fR count as a loop, so the loop control statements
+\&\f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, or
+\&\f(CW\*(C`redo\*(C'\fR cannot be used to leave or restart the block.
+See perlsyn for alternative strategies.
+.IP "do EXPR" 4
+.IX Xref "do"
+.IX Item "do EXPR"
+Uses the value of EXPR as a filename and executes the contents of the
+file as a Perl script:
+.Sp
+.Vb 4
+\&    # load the exact specified file (./ and ../ special\-cased)
+\&    do \*(Aq/foo/stat.pl\*(Aq;
+\&    do \*(Aq./stat.pl\*(Aq;
+\&    do \*(Aq../foo/stat.pl\*(Aq;
+\&
+\&    # search for the named file within @INC
+\&    do \*(Aqstat.pl\*(Aq;
+\&    do \*(Aqfoo/stat.pl\*(Aq;
+.Ve
+.Sp
+\&\f(CW\*(C`do \*(Aq./stat.pl\*(Aq\*(C'\fR is largely like
+.Sp
+.Vb 1
+\&    eval \`cat stat.pl\`;
+.Ve
+.Sp
+except that it's more concise, runs no external processes, and keeps
+track of the current filename for error messages. It also differs in that
+code evaluated with \f(CW\*(C`do FILE\*(C'\fR cannot see lexicals in the enclosing
+scope; \f(CW\*(C`eval STRING\*(C'\fR does.  It's the same, however, in that it does
+reparse the file every time you call it, so you probably don't want
+to do this inside a loop.
+.Sp
+Using \f(CW\*(C`do\*(C'\fR with a relative path (except for \fI./\fR and \fI../\fR), like
+.Sp
+.Vb 1
+\&    do \*(Aqfoo/stat.pl\*(Aq;
+.Ve
+.Sp
+will search the \f(CW@INC\fR directories, and update
+\&\f(CW%INC\fR if the file is found.  See "@INC" in perlvar
+and "%INC" in perlvar for these variables. In particular, note that
+whilst historically \f(CW@INC\fR contained '.' (the
+current directory) making these two cases equivalent, that is no
+longer necessarily the case, as '.' is not included in \f(CW@INC\fR by default
+in perl versions 5.26.0 onwards. Instead, perl will now warn:
+.Sp
+.Vb 2
+\&    do "stat.pl" failed, \*(Aq.\*(Aq is no longer in @INC;
+\&    did you mean do "./stat.pl"?
+.Ve
+.Sp
+If \f(CW\*(C`do\*(C'\fR can read the file but cannot compile it, it
+returns \f(CW\*(C`undef\*(C'\fR and sets an error message in
+\&\f(CW$@\fR.  If \f(CW\*(C`do\*(C'\fR cannot read the file, it
+returns undef and sets \f(CW$!\fR to the error.  Always check
+\&\f(CW$@\fR first, as compilation could fail in a way that also
+sets \f(CW$!\fR.  If the file is successfully compiled,
+\&\f(CW\*(C`do\*(C'\fR returns the value of the last expression evaluated.
+.Sp
+Inclusion of library modules is better done with the
+\&\f(CW\*(C`use\*(C'\fR and \f(CW\*(C`require\*(C'\fR
+operators, which also do automatic error checking and raise an exception
+if there's a problem.
+.Sp
+You might like to use \f(CW\*(C`do\*(C'\fR to read in a program
+configuration file.  Manual error checking can be done this way:
+.Sp
+.Vb 11
+\&    # Read in config files: system first, then user.
+\&    # Beware of using relative pathnames here.
+\&    for $file ("/share/prog/defaults.rc",
+\&               "$ENV{HOME}/.someprogrc")
+\&    {
+\&        unless ($return = do $file) {
+\&            warn "couldn\*(Aqt parse $file: $@" if $@;
+\&            warn "couldn\*(Aqt do $file: $!"    unless defined $return;
+\&            warn "couldn\*(Aqt run $file"       unless $return;
+\&        }
+\&    }
+.Ve
+.IP "dump LABEL" 4
+.IX Xref "dump core undump"
+.IX Item "dump LABEL"
+.PD 0
+.IP "dump EXPR" 4
+.IX Item "dump EXPR"
+.IP dump 4
+.IX Item "dump"
+.PD
+This function causes an immediate core dump.  See also the \fB\-u\fR
+command-line switch in perlrun, which does the same thing.
+Primarily this is so that you can use the \fBundump\fR program (not
+supplied) to turn your core dump into an executable binary after
+having initialized all your variables at the beginning of the
+program.  When the new binary is executed it will begin by executing
+a \f(CW\*(C`goto LABEL\*(C'\fR (with all the restrictions that \f(CW\*(C`goto\*(C'\fR
+suffers).
+Think of it as a goto with an intervening core dump and reincarnation.
+If \f(CW\*(C`LABEL\*(C'\fR is omitted, restarts the program from the top.  The
+\&\f(CW\*(C`dump EXPR\*(C'\fR form, available starting in Perl 5.18.0, allows a name to be
+computed at run time, being otherwise identical to \f(CW\*(C`dump LABEL\*(C'\fR.
+.Sp
+\&\fBWARNING\fR: Any files opened at the time of the dump will \fInot\fR
+be open any more when the program is reincarnated, with possible
+resulting confusion by Perl.
+.Sp
+This function is now largely obsolete, mostly because it's very hard to
+convert a core file into an executable.  As of Perl 5.30, it must be invoked
+as \f(CWCORE::dump()\fR.
+.Sp
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+\&\f(CW\*(C`dump ("foo")."bar"\*(C'\fR will cause "bar" to be part of the argument to
+\&\f(CW\*(C`dump\*(C'\fR.
+.Sp
+Portability issues: "dump" in perlport.
+.IP "each HASH" 4
+.IX Xref "each hash, iterator"
+.IX Item "each HASH"
+.PD 0
+.IP "each ARRAY" 4
+.IX Xref "array, iterator"
+.IX Item "each ARRAY"
+.PD
+When called on a hash in list context, returns a 2\-element list
+consisting of the key and value for the next element of a hash.  In Perl
+5.12 and later only, it will also return the index and value for the next
+element of an array so that you can iterate over it; older Perls consider
+this a syntax error.  When called in scalar context, returns only the key
+(not the value) in a hash, or the index in an array.
+.Sp
+Hash entries are returned in an apparently random order.  The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash.  Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by \f(CW\*(C`each\*(C'\fR or
+\&\f(CW\*(C`keys\*(C'\fR may be deleted without changing the order.  So
+long as a given hash is unmodified you may rely on
+\&\f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR and
+\&\f(CW\*(C`each\*(C'\fR to repeatedly return the same order
+as each other.  See "Algorithmic Complexity Attacks" in perlsec for
+details on why hash order is randomized.  Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
+.Sp
+After \f(CW\*(C`each\*(C'\fR has returned all entries from the hash or
+array, the next call to \f(CW\*(C`each\*(C'\fR returns the empty list in
+list context and \f(CW\*(C`undef\*(C'\fR in scalar context; the next
+call following \fIthat\fR one restarts iteration.  Each hash or array has
+its own internal iterator, accessed by \f(CW\*(C`each\*(C'\fR,
+\&\f(CW\*(C`keys\*(C'\fR, and \f(CW\*(C`values\*(C'\fR.  The iterator is
+implicitly reset when \f(CW\*(C`each\*(C'\fR has reached the end as just
+described; it can be explicitly reset by calling \f(CW\*(C`keys\*(C'\fR
+or \f(CW\*(C`values\*(C'\fR on the hash or array, or by referencing
+the hash (but not array) in list context.  If you add or delete
+a hash's elements while iterating over it, the effect on the iterator is
+unspecified; for example, entries may be skipped or duplicated\-\-so don't
+do that.  Exception: It is always safe to delete the item most recently
+returned by \f(CW\*(C`each\*(C'\fR, so the following code works properly:
+.Sp
+.Vb 4
+\&    while (my ($key, $value) = each %hash) {
+\&        print $key, "\en";
+\&        delete $hash{$key};   # This is safe
+\&    }
+.Ve
+.Sp
+Tied hashes may have a different ordering behaviour to perl's hash
+implementation.
+.Sp
+The iterator used by \f(CW\*(C`each\*(C'\fR is attached to the hash or array, and is
+shared between all iteration operations applied to the same hash or array.
+Thus all uses of \f(CW\*(C`each\*(C'\fR on a single hash or array advance the same
+iterator location.  All uses of \f(CW\*(C`each\*(C'\fR are also subject to having the
+iterator reset by any use of \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`values\*(C'\fR on the same hash or
+array, or by the hash (but not array) being referenced in list context.
+This makes \f(CW\*(C`each\*(C'\fR\-based loops quite fragile: it is easy to arrive at
+such a loop with the iterator already part way through the object, or to
+accidentally clobber the iterator state during execution of the loop body.
+It's easy enough to explicitly reset the iterator before starting a loop,
+but there is no way to insulate the iterator state used by a loop from
+the iterator state used by anything else that might execute during the
+loop body.  To avoid these problems, use a \f(CW\*(C`foreach\*(C'\fR loop rather than
+\&\f(CW\*(C`while\*(C'\fR\-\f(CW\*(C`each\*(C'\fR.
+.Sp
+This extends to using \f(CW\*(C`each\*(C'\fR on the result of an anonymous hash or
+array constructor.  A new underlying array or hash is created each
+time so each will always start iterating from scratch, eg:
+.Sp
+.Vb 4
+\&  # loops forever
+\&  while (my ($key, $value) = each @{ +{ a => 1 } }) {
+\&      print "$key=$value\en";
+\&  }
+.Ve
+.Sp
+This prints out your environment like the \fBprintenv\fR\|(1) program,
+but in a different order:
+.Sp
+.Vb 3
+\&    while (my ($key,$value) = each %ENV) {
+\&        print "$key=$value\en";
+\&    }
+.Ve
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`each\*(C'\fR to take a scalar expression. This experiment has
+been deemed unsuccessful, and was removed as of Perl 5.24.
+.Sp
+As of Perl 5.18 you can use a bare \f(CW\*(C`each\*(C'\fR in a \f(CW\*(C`while\*(C'\fR
+loop, which will set \f(CW$_\fR on every iteration.
+If either an \f(CW\*(C`each\*(C'\fR expression or an explicit assignment of an \f(CW\*(C`each\*(C'\fR
+expression to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then
+the condition actually tests for definedness of the expression's value,
+not for its regular truth value.
+.Sp
+.Vb 3
+\&    while (each %ENV) {
+\&        print "$_=$ENV{$_}\en";
+\&    }
+.Ve
+.Sp
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work \fIonly\fR on Perls of
+a recent vintage:
+.Sp
+.Vb 2
+\&    use v5.12;  # so keys/values/each work on arrays
+\&    use v5.18;  # so each assigns to $_ in a lone while test
+.Ve
+.Sp
+See also \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR, and
+\&\f(CW\*(C`sort\*(C'\fR.
+.IP "eof FILEHANDLE" 4
+.IX Xref "eof end of file end-of-file"
+.IX Item "eof FILEHANDLE"
+.PD 0
+.IP "eof ()" 4
+.IX Item "eof ()"
+.IP eof 4
+.IX Item "eof"
+.PD
+Returns 1 if the next read on FILEHANDLE will return end of file \fIor\fR if
+FILEHANDLE is not open.  FILEHANDLE may be an expression whose value
+gives the real filehandle.  (Note that this function actually
+reads a character and then \f(CW\*(C`ungetc\*(C'\fRs it, so isn't useful in an
+interactive context.)  Do not read from a terminal file (or call
+\&\f(CWeof(FILEHANDLE)\fR on it) after end-of-file is reached.  File types such
+as terminals may lose the end-of-file condition if you do.
+.Sp
+An \f(CW\*(C`eof\*(C'\fR without an argument uses the last file
+read.  Using \f(CWeof()\fR with empty parentheses is
+different.  It refers to the pseudo file formed from the files listed on
+the command line and accessed via the \f(CW\*(C`<>\*(C'\fR operator.  Since
+\&\f(CW\*(C`<>\*(C'\fR isn't explicitly opened, as a normal filehandle is, an
+\&\f(CWeof()\fR before \f(CW\*(C`<>\*(C'\fR has been used will cause
+\&\f(CW@ARGV\fR to be examined to determine if input is
+available.   Similarly, an \f(CWeof()\fR after \f(CW\*(C`<>\*(C'\fR
+has returned end-of-file will assume you are processing another
+\&\f(CW@ARGV\fR list, and if you haven't set
+\&\f(CW@ARGV\fR, will read input from \f(CW\*(C`STDIN\*(C'\fR; see
+"I/O Operators" in perlop.
+.Sp
+In a \f(CW\*(C`while (<>)\*(C'\fR loop, \f(CW\*(C`eof\*(C'\fR or \f(CWeof(ARGV)\fR
+can be used to detect the end of each file, whereas
+\&\f(CWeof()\fR will detect the end of the very last file
+only.  Examples:
+.Sp
+.Vb 7
+\&    # reset line numbering on each input file
+\&    while (<>) {
+\&        next if /^\es*#/;  # skip comments
+\&        print "$.\et$_";
+\&    } continue {
+\&        close ARGV if eof;  # Not eof()!
+\&    }
+\&
+\&    # insert dashes just before last line of last file
+\&    while (<>) {
+\&        if (eof()) {  # check for end of last file
+\&            print "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en";
+\&        }
+\&        print;
+\&        last if eof();     # needed if we\*(Aqre reading from a terminal
+\&    }
+.Ve
+.Sp
+Practical hint: you almost never need to use \f(CW\*(C`eof\*(C'\fR
+in Perl, because the input operators typically return \f(CW\*(C`undef\*(C'\fR when they run out of data or encounter an error.
+.IP "eval EXPR" 4
+.IX Xref "eval try catch evaluate parse execute error, handling exception, handling"
+.IX Item "eval EXPR"
+.PD 0
+.IP "eval BLOCK" 4
+.IX Item "eval BLOCK"
+.IP eval 4
+.IX Item "eval"
+.PD
+\&\f(CW\*(C`eval\*(C'\fR in all its forms is used to execute a little Perl program,
+trapping any errors encountered so they don't crash the calling program.
+.Sp
+Plain \f(CW\*(C`eval\*(C'\fR with no argument is just \f(CW\*(C`eval EXPR\*(C'\fR, where the
+expression is understood to be contained in \f(CW$_\fR.  Thus
+there are only two real \f(CW\*(C`eval\*(C'\fR forms; the one with an EXPR is often
+called "string eval".  In a string eval, the value of the expression
+(which is itself determined within scalar context) is first parsed, and
+if there were no errors, executed as a block within the lexical context
+of the current Perl program.  This form is typically used to delay
+parsing and subsequent execution of the text of EXPR until run time.
+Note that the value is parsed every time the \f(CW\*(C`eval\*(C'\fR executes.
+.Sp
+The other form is called "block eval".  It is less general than string
+eval, but the code within the BLOCK is parsed only once (at the same
+time the code surrounding the \f(CW\*(C`eval\*(C'\fR itself was parsed) and executed
+within the context of the current Perl program.  This form is typically
+used to trap exceptions more efficiently than the first, while also
+providing the benefit of checking the code within BLOCK at compile time.
+BLOCK is parsed and compiled just once.  Since errors are trapped, it
+often is used to check if a given feature is available.
+.Sp
+In both forms, the value returned is the value of the last expression
+evaluated inside the mini-program; a return statement may also be used, just
+as with subroutines.  The expression providing the return value is evaluated
+in void, scalar, or list context, depending on the context of the
+\&\f(CW\*(C`eval\*(C'\fR itself.  See \f(CW\*(C`wantarray\*(C'\fR for more
+on how the evaluation context can be determined.
+.Sp
+If there is a syntax error or runtime error, or a \f(CW\*(C`die\*(C'\fR
+statement is executed, \f(CW\*(C`eval\*(C'\fR returns
+\&\f(CW\*(C`undef\*(C'\fR in scalar context, or an empty list in list
+context, and \f(CW$@\fR is set to the error message.  (Prior to
+5.16, a bug caused \f(CW\*(C`undef\*(C'\fR to be returned in list
+context for syntax errors, but not for runtime errors.) If there was no
+error, \f(CW$@\fR is set to the empty string.  A control flow
+operator like \f(CW\*(C`last\*(C'\fR or \f(CW\*(C`goto\*(C'\fR can
+bypass the setting of \f(CW$@\fR.  Beware that using
+\&\f(CW\*(C`eval\*(C'\fR neither silences Perl from printing warnings to
+STDERR, nor does it stuff the text of warning messages into
+\&\f(CW$@\fR.  To do either of those, you have to use the
+\&\f(CW$SIG{_\|_WARN_\|_}\fR facility, or turn off warnings inside
+the BLOCK or EXPR using \f(CW\*(C`no\ warnings\ \*(Aqall\*(Aq\*(C'\fR.  See
+\&\f(CW\*(C`warn\*(C'\fR, perlvar, and warnings.
+.Sp
+Note that, because \f(CW\*(C`eval\*(C'\fR traps otherwise-fatal errors,
+it is useful for determining whether a particular feature (such as
+\&\f(CW\*(C`socket\*(C'\fR or
+\&\f(CW\*(C`symlink\*(C'\fR) is implemented.  It is also
+Perl's exception-trapping mechanism, where the \f(CW\*(C`die\*(C'\fR
+operator is used to raise exceptions.
+.Sp
+Before Perl 5.14, the assignment to \f(CW$@\fR occurred before
+restoration
+of localized variables, which means that for your code to run on older
+versions, a temporary is required if you want to mask some, but not all
+errors:
+.Sp
+.Vb 11
+\& # alter $@ on nefarious repugnancy only
+\& {
+\&    my $e;
+\&    {
+\&      local $@; # protect existing $@
+\&      eval { test_repugnancy() };
+\&      # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
+\&      $@ =~ /nefarious/ and $e = $@;
+\&    }
+\&    die $e if defined $e
+\& }
+.Ve
+.Sp
+There are some different considerations for each form:
+.RS 4
+.IP "String eval" 4
+.IX Item "String eval"
+Since the return value of EXPR is executed as a block within the lexical
+context of the current Perl program, any outer lexical variables are
+visible to it, and any package variable settings or subroutine and
+format definitions remain afterwards.
+.Sp
+Note that when \f(CW\*(C`BEGIN {}\*(C'\fR blocks are embedded inside of an eval block
+the contents of the block will be executed immediately and before the rest
+of the eval code is executed. You can disable this entirely by
+.Sp
+.Vb 2
+\&   local ${^MAX_NESTED_EVAL_BEGIN_BLOCKS} = 0;
+\&   eval $string;
+.Ve
+.Sp
+which will cause any embedded \f(CW\*(C`BEGIN\*(C'\fR blocks in \f(CW$string\fR to throw an
+exception.
+.RS 4
+.ie n .IP "Under the ""unicode_eval"" feature" 4
+.el .IP "Under the \f(CW""unicode_eval""\fR feature" 4
+.IX Item "Under the ""unicode_eval"" feature"
+If this feature is enabled (which is the default under a \f(CW\*(C`use 5.16\*(C'\fR or
+higher declaration), Perl assumes that EXPR is a character string.
+Any \f(CW\*(C`use\ utf8\*(C'\fR or \f(CW\*(C`no\ utf8\*(C'\fR declarations within
+the string thus have no effect. Source filters are forbidden as well.
+(\f(CW\*(C`unicode_strings\*(C'\fR, however, can appear within the string.)
+.Sp
+See also the \f(CW\*(C`evalbytes\*(C'\fR operator, which works properly
+with source filters.
+.ie n .IP "Outside the ""unicode_eval"" feature" 4
+.el .IP "Outside the \f(CW""unicode_eval""\fR feature" 4
+.IX Item "Outside the ""unicode_eval"" feature"
+In this case, the behavior is problematic and is not so easily
+described.  Here are two bugs that cannot easily be fixed without
+breaking existing programs:
+.RS 4
+.IP \(bu 4
+Perl's internal storage of EXPR affects the behavior of the executed code.
+For example:
+.Sp
+.Vb 1
+\&    my $v = eval "use utf8; \*(Aq$expr\*(Aq";
+.Ve
+.Sp
+If \f(CW$expr\fR is \f(CW"\exc4\ex80"\fR (U+0100 in UTF\-8), then the value stored in \f(CW$v\fR
+will depend on whether Perl stores \f(CW$expr\fR "upgraded" (cf. utf8) or
+not:
+.RS 4
+.IP \(bu 4
+If upgraded, \f(CW$v\fR will be \f(CW"\exc4\ex80"\fR (i.e., the
+\&\f(CW\*(C`use utf8\*(C'\fR has no effect.)
+.IP \(bu 4
+If non-upgraded, \f(CW$v\fR will be \f(CW"\ex{100}"\fR.
+.RE
+.RS 4
+.Sp
+This is undesirable since being
+upgraded or not should not affect a string's behavior.
+.RE
+.IP \(bu 4
+Source filters activated within \f(CW\*(C`eval\*(C'\fR leak out into whichever file
+scope is currently being compiled.  To give an example with the CPAN module
+Semi::Semicolons:
+.Sp
+.Vb 2
+\& BEGIN { eval "use Semi::Semicolons; # not filtered" }
+\& # filtered here!
+.Ve
+.Sp
+\&\f(CW\*(C`evalbytes\*(C'\fR fixes that to work the way one would
+expect:
+.Sp
+.Vb 3
+\& use feature "evalbytes";
+\& BEGIN { evalbytes "use Semi::Semicolons; # filtered" }
+\& # not filtered
+.Ve
+.RE
+.RS 4
+.RE
+.RE
+.RS 4
+.Sp
+Problems can arise if the string expands a scalar containing a floating
+point number.  That scalar can expand to letters, such as \f(CW"NaN"\fR or
+\&\f(CW"Infinity"\fR; or, within the scope of a \f(CW\*(C`use locale\*(C'\fR, the
+decimal point character may be something other than a dot (such as a
+comma).  None of these are likely to parse as you are likely expecting.
+.Sp
+You should be especially careful to remember what's being looked at
+when:
+.Sp
+.Vb 2
+\&    eval $x;        # CASE 1
+\&    eval "$x";      # CASE 2
+\&
+\&    eval \*(Aq$x\*(Aq;      # CASE 3
+\&    eval { $x };    # CASE 4
+\&
+\&    eval "\e$$x++";  # CASE 5
+\&    $$x++;          # CASE 6
+.Ve
+.Sp
+Cases 1 and 2 above behave identically: they run the code contained in
+the variable \f(CW$x\fR.  (Although case 2 has misleading double quotes making
+the reader wonder what else might be happening (nothing is).)  Cases 3
+and 4 likewise behave in the same way: they run the code \f(CW\*(Aq$x\*(Aq\fR, which
+does nothing but return the value of \f(CW$x\fR.  (Case 4 is preferred for
+purely visual reasons, but it also has the advantage of compiling at
+compile-time instead of at run-time.)  Case 5 is a place where
+normally you \fIwould\fR like to use double quotes, except that in this
+particular situation, you can just use symbolic references instead, as
+in case 6.
+.Sp
+An \f(CW\*(C`eval \*(Aq\*(Aq\*(C'\fR executed within a subroutine defined
+in the \f(CW\*(C`DB\*(C'\fR package doesn't see the usual
+surrounding lexical scope, but rather the scope of the first non-DB piece
+of code that called it.  You don't normally need to worry about this unless
+you are writing a Perl debugger.
+.Sp
+The final semicolon, if any, may be omitted from the value of EXPR.
+.RE
+.IP "Block eval" 4
+.IX Item "Block eval"
+If the code to be executed doesn't vary, you may use the eval-BLOCK
+form to trap run-time errors without incurring the penalty of
+recompiling each time.  The error, if any, is still returned in
+\&\f(CW$@\fR.
+Examples:
+.Sp
+.Vb 2
+\&    # make divide\-by\-zero nonfatal
+\&    eval { $answer = $a / $b; }; warn $@ if $@;
+\&
+\&    # same thing, but less efficient
+\&    eval \*(Aq$answer = $a / $b\*(Aq; warn $@ if $@;
+\&
+\&    # a compile\-time error
+\&    eval { $answer = }; # WRONG
+\&
+\&    # a run\-time error
+\&    eval \*(Aq$answer =\*(Aq;   # sets $@
+.Ve
+.Sp
+If you want to trap errors when loading an XS module, some problems with
+the binary interface (such as Perl version skew) may be fatal even with
+\&\f(CW\*(C`eval\*(C'\fR unless \f(CW$ENV{PERL_DL_NONLAZY}\fR is set.  See
+perlrun.
+.Sp
+Using the \f(CW\*(C`eval {}\*(C'\fR form as an exception trap in libraries does have some
+issues.  Due to the current arguably broken state of \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hooks, you
+may wish not to trigger any \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hooks that user code may have installed.
+You can use the \f(CW\*(C`local $SIG{_\|_DIE_\|_}\*(C'\fR construct for this purpose,
+as this example shows:
+.Sp
+.Vb 3
+\&    # a private exception trap for divide\-by\-zero
+\&    eval { local $SIG{\*(Aq_\|_DIE_\|_\*(Aq}; $answer = $a / $b; };
+\&    warn $@ if $@;
+.Ve
+.Sp
+This is especially significant, given that \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hooks can call
+\&\f(CW\*(C`die\*(C'\fR again, which has the effect of changing their error
+messages:
+.Sp
+.Vb 7
+\&    # _\|_DIE_\|_ hooks may modify error messages
+\&    {
+\&       local $SIG{\*(Aq_\|_DIE_\|_\*(Aq} =
+\&              sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
+\&       eval { die "foo lives here" };
+\&       print $@ if $@;                # prints "bar lives here"
+\&    }
+.Ve
+.Sp
+Because this promotes action at a distance, this counterintuitive behavior
+may be fixed in a future release.
+.Sp
+\&\f(CW\*(C`eval BLOCK\*(C'\fR does \fInot\fR count as a loop, so the loop control statements
+\&\f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, or
+\&\f(CW\*(C`redo\*(C'\fR cannot be used to leave or restart the block.
+.Sp
+The final semicolon, if any, may be omitted from within the BLOCK.
+.RE
+.RS 4
+.RE
+.IP "evalbytes EXPR" 4
+.IX Xref "evalbytes"
+.IX Item "evalbytes EXPR"
+.PD 0
+.IP evalbytes 4
+.IX Item "evalbytes"
+.PD
+This function is similar to a string eval, except it
+always parses its argument (or \f(CW$_\fR if EXPR is omitted)
+as a byte string. If the string contains any code points above 255, then
+it cannot be a byte string, and the \f(CW\*(C`evalbytes\*(C'\fR will fail with the error
+stored in \f(CW$@\fR.
+.Sp
+\&\f(CW\*(C`use utf8\*(C'\fR and \f(CW\*(C`no utf8\*(C'\fR within the string have their usual effect.
+.Sp
+Source filters activated within the evaluated code apply to the code
+itself.
+.Sp
+\&\f(CW\*(C`evalbytes\*(C'\fR is available starting in Perl v5.16.  To
+access it, you must say \f(CW\*(C`CORE::evalbytes\*(C'\fR, but you can omit the
+\&\f(CW\*(C`CORE::\*(C'\fR if the
+\&\f(CW"evalbytes"\fR feature
+is enabled.  This is enabled automatically with a \f(CW\*(C`use v5.16\*(C'\fR (or
+higher) declaration in the current scope.
+.IP "exec LIST" 4
+.IX Xref "exec execute"
+.IX Item "exec LIST"
+.PD 0
+.IP "exec PROGRAM LIST" 4
+.IX Item "exec PROGRAM LIST"
+.PD
+The \f(CW\*(C`exec\*(C'\fR function executes a system command \fIand never
+returns\fR; use \f(CW\*(C`system\*(C'\fR instead of \f(CW\*(C`exec\*(C'\fR
+if you want it to return.  It fails and
+returns false only if the command does not exist \fIand\fR it is executed
+directly instead of via your system's command shell (see below).
+.Sp
+Since it's a common mistake to use \f(CW\*(C`exec\*(C'\fR instead of
+\&\f(CW\*(C`system\*(C'\fR, Perl warns you if \f(CW\*(C`exec\*(C'\fR is
+called in void context and if there is a following statement that isn't
+\&\f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, or \f(CW\*(C`exit\*(C'\fR (if
+warnings are enabled\-\-but you always do that, right?).  If you
+\&\fIreally\fR want to follow an \f(CW\*(C`exec\*(C'\fR with some other
+statement, you can use one of these styles to avoid the warning:
+.Sp
+.Vb 2
+\&    exec (\*(Aqfoo\*(Aq)   or print STDERR "couldn\*(Aqt exec foo: $!";
+\&    { exec (\*(Aqfoo\*(Aq) }; print STDERR "couldn\*(Aqt exec foo: $!";
+.Ve
+.Sp
+If there is more than one argument in LIST, this calls \fBexecvp\fR\|(3) with the
+arguments in LIST.  If there is only one element in LIST, the argument is
+checked for shell metacharacters, and if there are any, the entire
+argument is passed to the system's command shell for parsing (this is
+\&\f(CW\*(C`/bin/sh \-c\*(C'\fR on Unix platforms, but varies on other platforms).  If
+there are no shell metacharacters in the argument, it is split into words
+and passed directly to \f(CW\*(C`execvp\*(C'\fR, which is more efficient.  Examples:
+.Sp
+.Vb 2
+\&    exec \*(Aq/bin/echo\*(Aq, \*(AqYour arguments are: \*(Aq, @ARGV;
+\&    exec "sort $outfile | uniq";
+.Ve
+.Sp
+If you don't really want to execute the first argument, but want to lie
+to the program you are executing about its own name, you can specify
+the program you actually want to run as an "indirect object" (without a
+comma) in front of the LIST, as in \f(CW\*(C`exec PROGRAM LIST\*(C'\fR.  (This always
+forces interpretation of the LIST as a multivalued list, even if there
+is only a single scalar in the list.)  Example:
+.Sp
+.Vb 2
+\&    my $shell = \*(Aq/bin/csh\*(Aq;
+\&    exec $shell \*(Aq\-sh\*(Aq;    # pretend it\*(Aqs a login shell
+.Ve
+.Sp
+or, more directly,
+.Sp
+.Vb 1
+\&    exec {\*(Aq/bin/csh\*(Aq} \*(Aq\-sh\*(Aq;  # pretend it\*(Aqs a login shell
+.Ve
+.Sp
+When the arguments get executed via the system shell, results are
+subject to its quirks and capabilities.  See "`STRING`" in perlop
+for details.
+.Sp
+Using an indirect object with \f(CW\*(C`exec\*(C'\fR or
+\&\f(CW\*(C`system\*(C'\fR is also more secure.  This usage (which also
+works fine with \f(CW\*(C`system\*(C'\fR) forces
+interpretation of the arguments as a multivalued list, even if the
+list had just one argument.  That way you're safe from the shell
+expanding wildcards or splitting up words with whitespace in them.
+.Sp
+.Vb 1
+\&    my @args = ( "echo surprise" );
+\&
+\&    exec @args;               # subject to shell escapes
+\&                                # if @args == 1
+\&    exec { $args[0] } @args;  # safe even with one\-arg list
+.Ve
+.Sp
+The first version, the one without the indirect object, ran the \fIecho\fR
+program, passing it \f(CW"surprise"\fR an argument.  The second version didn't;
+it tried to run a program named \fI"echo surprise"\fR, didn't find it, and set
+\&\f(CW$?\fR to a non-zero value indicating failure.
+.Sp
+On Windows, only the \f(CW\*(C`exec PROGRAM LIST\*(C'\fR indirect object syntax will
+reliably avoid using the shell; \f(CW\*(C`exec LIST\*(C'\fR, even with more than one
+element, will fall back to the shell if the first spawn fails.
+.Sp
+Perl attempts to flush all files opened for output before the exec,
+but this may not be supported on some platforms (see perlport).
+To be safe, you may need to set \f(CW$|\fR
+(\f(CW$AUTOFLUSH\fR in English) or call the \f(CW\*(C`autoflush\*(C'\fR method of
+\&\f(CW\*(C`IO::Handle\*(C'\fR on any open handles to avoid lost
+output.
+.Sp
+Note that \f(CW\*(C`exec\*(C'\fR will not call your \f(CW\*(C`END\*(C'\fR blocks, nor
+will it invoke \f(CW\*(C`DESTROY\*(C'\fR methods on your objects.
+.Sp
+Portability issues: "exec" in perlport.
+.IP "exists EXPR" 4
+.IX Xref "exists autovivification"
+.IX Item "exists EXPR"
+Given an expression that specifies an element of a hash, returns true if the
+specified element in the hash has ever been initialized, even if the
+corresponding value is undefined.
+.Sp
+.Vb 3
+\&    print "Exists\en"    if exists $hash{$key};
+\&    print "Defined\en"   if defined $hash{$key};
+\&    print "True\en"      if $hash{$key};
+.Ve
+.Sp
+exists may also be called on array elements, but its behavior is much less
+obvious and is strongly tied to the use of \f(CW\*(C`delete\*(C'\fR on
+arrays.
+.Sp
+\&\fBWARNING:\fR Calling \f(CW\*(C`exists\*(C'\fR on array values is
+strongly discouraged.  The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
+.Sp
+.Vb 3
+\&    print "Exists\en"    if exists $array[$index];
+\&    print "Defined\en"   if defined $array[$index];
+\&    print "True\en"      if $array[$index];
+.Ve
+.Sp
+A hash or array element can be true only if it's defined and defined only if
+it exists, but the reverse doesn't necessarily hold true.
+.Sp
+Given an expression that specifies the name of a subroutine,
+returns true if the specified subroutine has ever been declared, even
+if it is undefined.  Mentioning a subroutine name for exists or defined
+does not count as declaring it.  Note that a subroutine that does not
+exist may still be callable: its package may have an \f(CW\*(C`AUTOLOAD\*(C'\fR
+method that makes it spring into existence the first time that it is
+called; see perlsub.
+.Sp
+.Vb 2
+\&    print "Exists\en"  if exists &subroutine;
+\&    print "Defined\en" if defined &subroutine;
+.Ve
+.Sp
+Note that the EXPR can be arbitrarily complicated as long as the final
+operation is a hash or array key lookup or subroutine name:
+.Sp
+.Vb 2
+\&    if (exists $ref\->{A}\->{B}\->{$key})  { }
+\&    if (exists $hash{A}{B}{$key})       { }
+\&
+\&    if (exists $ref\->{A}\->{B}\->[$ix])   { }
+\&    if (exists $hash{A}{B}[$ix])        { }
+\&
+\&    if (exists &{$ref\->{A}{B}{$key}})   { }
+.Ve
+.Sp
+Although the most deeply nested array or hash element will not spring into
+existence just because its existence was tested, any intervening ones will.
+Thus \f(CW\*(C`$ref\->{"A"}\*(C'\fR and \f(CW\*(C`$ref\->{"A"}\->{"B"}\*(C'\fR will spring
+into existence due to the existence test for the \f(CW$key\fR element above.
+This happens anywhere the arrow operator is used, including even here:
+.Sp
+.Vb 3
+\&    undef $ref;
+\&    if (exists $ref\->{"Some key"})    { }
+\&    print $ref;  # prints HASH(0x80d3d5c)
+.Ve
+.Sp
+Use of a subroutine call, rather than a subroutine name, as an argument
+to \f(CW\*(C`exists\*(C'\fR is an error.
+.Sp
+.Vb 2
+\&    exists &sub;    # OK
+\&    exists &sub();  # Error
+.Ve
+.IP "exit EXPR" 4
+.IX Xref "exit terminate abort"
+.IX Item "exit EXPR"
+.PD 0
+.IP exit 4
+.IX Item "exit"
+.PD
+Evaluates EXPR and exits immediately with that value.    Example:
+.Sp
+.Vb 2
+\&    my $ans = <STDIN>;
+\&    exit 0 if $ans =~ /^[Xx]/;
+.Ve
+.Sp
+See also \f(CW\*(C`die\*(C'\fR.  If EXPR is omitted, exits with \f(CW0\fR
+status.  The only
+universally recognized values for EXPR are \f(CW0\fR for success and \f(CW1\fR
+for error; other values are subject to interpretation depending on the
+environment in which the Perl program is running.  For example, exiting
+69 (EX_UNAVAILABLE) from a \fIsendmail\fR incoming-mail filter will cause
+the mailer to return the item undelivered, but that's not true everywhere.
+.Sp
+Don't use \f(CW\*(C`exit\*(C'\fR to abort a subroutine if there's any
+chance that someone might want to trap whatever error happened.  Use
+\&\f(CW\*(C`die\*(C'\fR instead, which can be trapped by an
+\&\f(CW\*(C`eval\*(C'\fR.
+.Sp
+The \f(CW\*(C`exit\*(C'\fR function does not always exit immediately.  It
+calls any defined \f(CW\*(C`END\*(C'\fR routines first, but these \f(CW\*(C`END\*(C'\fR routines may
+not themselves abort the exit.  Likewise any object destructors that
+need to be called are called before the real exit.  \f(CW\*(C`END\*(C'\fR routines and
+destructors can change the exit status by modifying \f(CW$?\fR.
+If this is a problem, you can call
+\&\f(CWPOSIX::_exit($status)\fR to avoid \f(CW\*(C`END\*(C'\fR and destructor
+processing.  See perlmod for details.
+.Sp
+Portability issues: "exit" in perlport.
+.IP "exp EXPR" 4
+.IX Xref "exp exponential antilog antilogarithm e"
+.IX Item "exp EXPR"
+.PD 0
+.IP exp 4
+.IX Item "exp"
+.PD
+Returns \fIe\fR (the natural logarithm base) to the power of EXPR.
+If EXPR is omitted, gives \f(CWexp($_)\fR.
+.IP "fc EXPR" 4
+.IX Xref "fc foldcase casefold fold-case case-fold"
+.IX Item "fc EXPR"
+.PD 0
+.IP fc 4
+.IX Item "fc"
+.PD
+Returns the casefolded version of EXPR.  This is the internal function
+implementing the \f(CW\*(C`\eF\*(C'\fR escape in double-quoted strings.
+.Sp
+Casefolding is the process of mapping strings to a form where case
+differences are erased; comparing two strings in their casefolded
+form is effectively a way of asking if two strings are equal,
+regardless of case.
+.Sp
+Roughly, if you ever found yourself writing this
+.Sp
+.Vb 5
+\&    lc($this) eq lc($that)    # Wrong!
+\&        # or
+\&    uc($this) eq uc($that)    # Also wrong!
+\&        # or
+\&    $this =~ /^\eQ$that\eE\ez/i  # Right!
+.Ve
+.Sp
+Now you can write
+.Sp
+.Vb 1
+\&    fc($this) eq fc($that)
+.Ve
+.Sp
+And get the correct results.
+.Sp
+Perl only implements the full form of casefolding, but you can access
+the simple folds using "\fBcasefold()\fR" in Unicode::UCD and
+"\fBprop_invmap()\fR" in Unicode::UCD.
+For further information on casefolding, refer to
+the Unicode Standard, specifically sections 3.13 \f(CW\*(C`Default Case Operations\*(C'\fR,
+4.2 \f(CW\*(C`Case\-Normative\*(C'\fR, and 5.18 \f(CW\*(C`Case Mappings\*(C'\fR,
+available at <https://www.unicode.org/versions/latest/>, as well as the
+Case Charts available at <https://www.unicode.org/charts/case/>.
+.Sp
+If EXPR is omitted, uses \f(CW$_\fR.
+.Sp
+This function behaves the same way under various pragmas, such as within
+\&\f(CW"use\ feature\ \*(Aqunicode_strings"\fR,
+as \f(CW\*(C`lc\*(C'\fR does, with the single exception of
+\&\f(CW\*(C`fc\*(C'\fR of \fILATIN CAPITAL LETTER SHARP S\fR (U+1E9E) within the
+scope of \f(CW\*(C`use\ locale\*(C'\fR.  The foldcase of this character
+would normally be \f(CW"ss"\fR, but as explained in the \f(CW\*(C`lc\*(C'\fR
+section, case
+changes that cross the 255/256 boundary are problematic under locales,
+and are hence prohibited.  Therefore, this function under locale returns
+instead the string \f(CW"\ex{17F}\ex{17F}"\fR, which is the \fILATIN SMALL LETTER
+LONG S\fR.  Since that character itself folds to \f(CW"s"\fR, the string of two
+of them together should be equivalent to a single U+1E9E when foldcased.
+.Sp
+While the Unicode Standard defines two additional forms of casefolding,
+one for Turkic languages and one that never maps one character into multiple
+characters, these are not provided by the Perl core.  However, the CPAN module
+\&\f(CW\*(C`Unicode::Casing\*(C'\fR may be used to provide an implementation.
+.Sp
+\&\f(CW\*(C`fc\*(C'\fR is available only if the
+\&\f(CW"fc"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"fc"\fR feature is enabled automatically
+with a \f(CW\*(C`use v5.16\*(C'\fR (or higher) declaration in the current scope.
+.IP "fcntl FILEHANDLE,FUNCTION,SCALAR" 4
+.IX Xref "fcntl"
+.IX Item "fcntl FILEHANDLE,FUNCTION,SCALAR"
+Implements the \fBfcntl\fR\|(2) function.  You'll probably have to say
+.Sp
+.Vb 1
+\&    use Fcntl;
+.Ve
+.Sp
+first to get the correct constant definitions.  Argument processing and
+value returned work just like \f(CW\*(C`ioctl\*(C'\fR below.  For example:
+.Sp
+.Vb 3
+\&    use Fcntl;
+\&    my $flags = fcntl($filehandle, F_GETFL, 0)
+\&        or die "Can\*(Aqt fcntl F_GETFL: $!";
+.Ve
+.Sp
+You don't have to check for \f(CW\*(C`defined\*(C'\fR on the return
+from \f(CW\*(C`fcntl\*(C'\fR.  Like
+\&\f(CW\*(C`ioctl\*(C'\fR, it maps a \f(CW0\fR return
+from the system call into \f(CW"0 but true"\fR in Perl.  This string is true
+in boolean context and \f(CW0\fR in numeric context.  It is also exempt from
+the normal
+\&\f(CW\*(C`Argument "..." isn\*(Aqt numeric\*(C'\fR
+warnings on improper numeric conversions.
+.Sp
+Note that \f(CW\*(C`fcntl\*(C'\fR raises an
+exception if used on a machine that doesn't implement \fBfcntl\fR\|(2).  See
+the Fcntl module or your \fBfcntl\fR\|(2) manpage to learn what functions
+are available on your system.
+.Sp
+Here's an example of setting a filehandle named \f(CW$REMOTE\fR to be
+non-blocking at the system level.  You'll have to negotiate
+\&\f(CW$|\fR on your own, though.
+.Sp
+.Vb 1
+\&    use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
+\&
+\&    my $flags = fcntl($REMOTE, F_GETFL, 0)
+\&        or die "Can\*(Aqt get flags for the socket: $!\en";
+\&
+\&    fcntl($REMOTE, F_SETFL, $flags | O_NONBLOCK)
+\&        or die "Can\*(Aqt set flags for the socket: $!\en";
+.Ve
+.Sp
+Portability issues: "fcntl" in perlport.
+.IP _\|_FILE_\|_ 4
+.IX Xref "__FILE__"
+.IX Item "__FILE__"
+A special token that returns the name of the file in which it occurs.
+It can be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.IP "field VARNAME" 4
+.IX Xref "field"
+.IX Item "field VARNAME"
+Declares a new field variable within the current class.  Methods and
+\&\f(CW\*(C`ADJUST\*(C'\fR blocks of the class will have access to this variable as if it
+was a lexical in scope at that point.
+.IP "fileno FILEHANDLE" 4
+.IX Xref "fileno"
+.IX Item "fileno FILEHANDLE"
+.PD 0
+.IP "fileno DIRHANDLE" 4
+.IX Item "fileno DIRHANDLE"
+.PD
+Returns the file descriptor for a filehandle or directory handle,
+or undefined if the
+filehandle is not open.  If there is no real file descriptor at the OS
+level, as can happen with filehandles connected to memory objects via
+\&\f(CW\*(C`open\*(C'\fR with a reference for the third
+argument, \-1 is returned.
+.Sp
+This is mainly useful for constructing bitmaps for
+\&\f(CW\*(C`select\*(C'\fR and low-level POSIX
+tty-handling operations.
+If FILEHANDLE is an expression, the value is taken as an indirect
+filehandle, generally its name.
+.Sp
+You can use this to find out whether two handles refer to the
+same underlying descriptor:
+.Sp
+.Vb 9
+\&    if (fileno($this) != \-1 && fileno($this) == fileno($that)) {
+\&        print "\e$this and \e$that are dups\en";
+\&    } elsif (fileno($this) != \-1 && fileno($that) != \-1) {
+\&        print "\e$this and \e$that have different " .
+\&            "underlying file descriptors\en";
+\&    } else {
+\&        print "At least one of \e$this and \e$that does " .
+\&            "not have a real file descriptor\en";
+\&    }
+.Ve
+.Sp
+The behavior of \f(CW\*(C`fileno\*(C'\fR on a directory handle
+depends on the operating system.  On a system with \fBdirfd\fR\|(3) or
+similar, \f(CW\*(C`fileno\*(C'\fR on a directory
+handle returns the underlying file descriptor associated with the
+handle; on systems with no such support, it returns the undefined value,
+and sets \f(CW$!\fR (errno).
+.IP "flock FILEHANDLE,OPERATION" 4
+.IX Xref "flock lock locking"
+.IX Item "flock FILEHANDLE,OPERATION"
+Calls \fBflock\fR\|(2), or an emulation of it, on FILEHANDLE.  Returns true
+for success, false on failure.  Produces a fatal error if used on a
+machine that doesn't implement \fBflock\fR\|(2), \fBfcntl\fR\|(2) locking, or
+\&\fBlockf\fR\|(3).  \f(CW\*(C`flock\*(C'\fR is Perl's portable
+file-locking interface, although it locks entire files only, not
+records.
+.Sp
+Two potentially non-obvious but traditional \f(CW\*(C`flock\*(C'\fR semantics are
+that it waits indefinitely until the lock is granted, and that its locks
+are \fBmerely advisory\fR.  Such discretionary locks are more flexible, but
+offer fewer guarantees.  This means that programs that do not also use
+\&\f(CW\*(C`flock\*(C'\fR may modify files locked with
+\&\f(CW\*(C`flock\*(C'\fR.  See perlport,
+your port's specific documentation, and your system-specific local manpages
+for details.  It's best to assume traditional behavior if you're writing
+portable programs.  (But if you're not, you should as always feel perfectly
+free to write for your own system's idiosyncrasies (sometimes called
+"features").  Slavish adherence to portability concerns shouldn't get
+in the way of your getting your job done.)
+.Sp
+OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
+LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
+you can use the symbolic names if you import them from the Fcntl module,
+either individually, or as a group using the \f(CW\*(C`:flock\*(C'\fR tag.  LOCK_SH
+requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
+releases a previously requested lock.  If LOCK_NB is bitwise-or'ed with
+LOCK_SH or LOCK_EX, then \f(CW\*(C`flock\*(C'\fR returns
+immediately rather than blocking waiting for the lock; check the return
+status to see if you got it.
+.Sp
+To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
+before locking or unlocking it.
+.Sp
+Note that the emulation built with \fBlockf\fR\|(3) doesn't provide shared
+locks, and it requires that FILEHANDLE be open with write intent.  These
+are the semantics that \fBlockf\fR\|(3) implements.  Most if not all systems
+implement \fBlockf\fR\|(3) in terms of \fBfcntl\fR\|(2) locking, though, so the
+differing semantics shouldn't bite too many people.
+.Sp
+Note that the \fBfcntl\fR\|(2) emulation of \fBflock\fR\|(3) requires that FILEHANDLE
+be open with read intent to use LOCK_SH and requires that it be open
+with write intent to use LOCK_EX.
+.Sp
+Note also that some versions of \f(CW\*(C`flock\*(C'\fR
+cannot lock things over the network; you would need to use the more
+system-specific \f(CW\*(C`fcntl\*(C'\fR for
+that.  If you like you can force Perl to ignore your system's \fBflock\fR\|(2)
+function, and so provide its own \fBfcntl\fR\|(2)\-based emulation, by passing
+the switch \f(CW\*(C`\-Ud_flock\*(C'\fR to the \fIConfigure\fR program when you configure
+and build a new Perl.
+.Sp
+Here's a mailbox appender for BSD systems.
+.Sp
+.Vb 2
+\&    # import LOCK_* and SEEK_END constants
+\&    use Fcntl qw(:flock SEEK_END);
+\&
+\&    sub lock {
+\&        my ($fh) = @_;
+\&        flock($fh, LOCK_EX) or die "Cannot lock mailbox \- $!\en";
+\&        # and, in case we\*(Aqre running on a very old UNIX
+\&        # variant without the modern O_APPEND semantics...
+\&        seek($fh, 0, SEEK_END) or die "Cannot seek \- $!\en";
+\&    }
+\&
+\&    sub unlock {
+\&        my ($fh) = @_;
+\&        flock($fh, LOCK_UN) or die "Cannot unlock mailbox \- $!\en";
+\&    }
+\&
+\&    open(my $mbox, ">>", "/usr/spool/mail/$ENV{\*(AqUSER\*(Aq}")
+\&        or die "Can\*(Aqt open mailbox: $!";
+\&
+\&    lock($mbox);
+\&    print $mbox $msg,"\en\en";
+\&    unlock($mbox);
+.Ve
+.Sp
+On systems that support a real \fBflock\fR\|(2), locks are inherited across
+\&\f(CW\*(C`fork\*(C'\fR calls, whereas those that must resort to the more
+capricious \fBfcntl\fR\|(2) function lose their locks, making it seriously
+harder to write servers.
+.Sp
+See also DB_File for other \f(CW\*(C`flock\*(C'\fR
+examples.
+.Sp
+Portability issues: "flock" in perlport.
+.IP fork 4
+.IX Xref "fork child parent"
+.IX Item "fork"
+Does a \fBfork\fR\|(2) system call to create a new process running the
+same program at the same point.  It returns the child pid to the
+parent process, \f(CW0\fR to the child process, or \f(CW\*(C`undef\*(C'\fR if
+the fork is
+unsuccessful.  File descriptors (and sometimes locks on those descriptors)
+are shared, while everything else is copied.  On most systems supporting
+\&\fBfork\fR\|(2), great care has gone into making it extremely efficient (for
+example, using copy-on-write technology on data pages), making it the
+dominant paradigm for multitasking over the last few decades.
+.Sp
+Perl attempts to flush all files opened for output before forking the
+child process, but this may not be supported on some platforms (see
+perlport).  To be safe, you may need to set
+\&\f(CW$|\fR (\f(CW$AUTOFLUSH\fR in English) or
+call the \f(CW\*(C`autoflush\*(C'\fR method of \f(CW\*(C`IO::Handle\*(C'\fR on
+any open handles to avoid duplicate output.
+.Sp
+If you \f(CW\*(C`fork\*(C'\fR without ever waiting on your children, you will
+accumulate zombies.  On some systems, you can avoid this by setting
+\&\f(CW$SIG{CHLD}\fR to \f(CW"IGNORE"\fR.  See also perlipc for
+more examples of forking and reaping moribund children.
+.Sp
+Note that if your forked child inherits system file descriptors like
+STDIN and STDOUT that are actually connected by a pipe or socket, even
+if you exit, then the remote server (such as, say, a CGI script or a
+backgrounded job launched from a remote shell) won't think you're done.
+You should reopen those to \fI/dev/null\fR if it's any issue.
+.Sp
+On some platforms such as Windows, where the \fBfork\fR\|(2) system call is
+not available, Perl can be built to emulate \f(CW\*(C`fork\*(C'\fR in the Perl
+interpreter.  The emulation is designed, at the level of the Perl
+program, to be as compatible as possible with the "Unix" \fBfork\fR\|(2).
+However it has limitations that have to be considered in code intended
+to be portable.  See perlfork for more details.
+.Sp
+Portability issues: "fork" in perlport.
+.IP format 4
+.IX Xref "format"
+.IX Item "format"
+Declare a picture format for use by the \f(CW\*(C`write\*(C'\fR
+function.  For example:
+.Sp
+.Vb 4
+\&    format Something =
+\&        Test: @<<<<<<<< @||||| @>>>>>
+\&              $str,     $%,    \*(Aq$\*(Aq . int($num)
+\&    .
+\&
+\&    $str = "widget";
+\&    $num = $cost/$quantity;
+\&    $~ = \*(AqSomething\*(Aq;
+\&    write;
+.Ve
+.Sp
+See perlform for many details and examples.
+.IP "formline PICTURE,LIST" 4
+.IX Xref "formline"
+.IX Item "formline PICTURE,LIST"
+This is an internal function used by \f(CW\*(C`format\*(C'\fRs, though you
+may call it, too.  It formats (see perlform) a list of values
+according to the contents of PICTURE, placing the output into the format
+output accumulator, \f(CW$^A\fR (or \f(CW$ACCUMULATOR\fR in
+English).  Eventually, when a \f(CW\*(C`write\*(C'\fR is done,
+the contents of \f(CW$^A\fR are written to some filehandle.
+You could also read \f(CW$^A\fR and then set
+\&\f(CW$^A\fR back to \f(CW""\fR.  Note that a format typically does
+one \f(CW\*(C`formline\*(C'\fR per line of form, but the
+\&\f(CW\*(C`formline\*(C'\fR function itself doesn't care how
+many newlines are embedded in the PICTURE.  This means that the \f(CW\*(C`~\*(C'\fR and
+\&\f(CW\*(C`~~\*(C'\fR tokens treat the entire PICTURE as a single line.  You may
+therefore need to use multiple formlines to implement a single record
+format, just like the \f(CW\*(C`format\*(C'\fR compiler.
+.Sp
+Be careful if you put double quotes around the picture, because an \f(CW\*(C`@\*(C'\fR
+character may be taken to mean the beginning of an array name.
+\&\f(CW\*(C`formline\*(C'\fR always returns true.  See
+perlform for other examples.
+.Sp
+If you are trying to use this instead of \f(CW\*(C`write\*(C'\fR
+to capture the output, you may find it easier to open a filehandle to a
+scalar (\f(CW\*(C`open my $fh, ">", \e$output\*(C'\fR) and write to that instead.
+.IP "getc FILEHANDLE" 4
+.IX Xref "getc getchar character file, read"
+.IX Item "getc FILEHANDLE"
+.PD 0
+.IP getc 4
+.IX Item "getc"
+.PD
+Returns the next character from the input file attached to FILEHANDLE,
+or the undefined value at end of file or if there was an error (in
+the latter case \f(CW$!\fR is set).  If FILEHANDLE is omitted,
+reads from
+STDIN.  This is not particularly efficient.  However, it cannot be
+used by itself to fetch single characters without waiting for the user
+to hit enter.  For that, try something more like:
+.Sp
+.Vb 6
+\&    if ($BSD_STYLE) {
+\&        system "stty cbreak </dev/tty >/dev/tty 2>&1";
+\&    }
+\&    else {
+\&        system "stty", \*(Aq\-icanon\*(Aq, \*(Aqeol\*(Aq, "\e001";
+\&    }
+\&
+\&    my $key = getc(STDIN);
+\&
+\&    if ($BSD_STYLE) {
+\&        system "stty \-cbreak </dev/tty >/dev/tty 2>&1";
+\&    }
+\&    else {
+\&        system \*(Aqstty\*(Aq, \*(Aqicanon\*(Aq, \*(Aqeol\*(Aq, \*(Aq^@\*(Aq; # ASCII NUL
+\&    }
+\&    print "\en";
+.Ve
+.Sp
+Determination of whether \f(CW$BSD_STYLE\fR should be set is left as an
+exercise to the reader.
+.Sp
+The \f(CW\*(C`POSIX::getattr\*(C'\fR function can do this more
+portably on systems purporting POSIX compliance.  See also the
+\&\f(CW\*(C`Term::ReadKey\*(C'\fR module on CPAN.
+.IP getlogin 4
+.IX Xref "getlogin login"
+.IX Item "getlogin"
+This implements the C library function of the same name, which on most
+systems returns the current login from \fI/etc/utmp\fR, if any.  If it
+returns the empty string, use \f(CW\*(C`getpwuid\*(C'\fR.
+.Sp
+.Vb 1
+\&    my $login = getlogin || getpwuid($<) || "Kilroy";
+.Ve
+.Sp
+Do not consider \f(CW\*(C`getlogin\*(C'\fR for authentication: it is not
+as secure as \f(CW\*(C`getpwuid\*(C'\fR.
+.Sp
+Portability issues: "getlogin" in perlport.
+.IP "getpeername SOCKET" 4
+.IX Xref "getpeername peer"
+.IX Item "getpeername SOCKET"
+Returns the packed sockaddr address of the other end of the SOCKET
+connection.
+.Sp
+.Vb 5
+\&    use Socket;
+\&    my $hersockaddr    = getpeername($sock);
+\&    my ($port, $iaddr) = sockaddr_in($hersockaddr);
+\&    my $herhostname    = gethostbyaddr($iaddr, AF_INET);
+\&    my $herstraddr     = inet_ntoa($iaddr);
+.Ve
+.IP "getpgrp PID" 4
+.IX Xref "getpgrp group"
+.IX Item "getpgrp PID"
+Returns the current process group for the specified PID.  Use
+a PID of \f(CW0\fR to get the current process group for the
+current process.  Will raise an exception if used on a machine that
+doesn't implement \fBgetpgrp\fR\|(2).  If PID is omitted, returns the process
+group of the current process.  Note that the POSIX version of
+\&\f(CW\*(C`getpgrp\*(C'\fR does not accept a PID argument, so only
+\&\f(CW\*(C`PID==0\*(C'\fR is truly portable.
+.Sp
+Portability issues: "getpgrp" in perlport.
+.IP getppid 4
+.IX Xref "getppid parent pid"
+.IX Item "getppid"
+Returns the process id of the parent process.
+.Sp
+Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
+around non-POSIX thread semantics the minority of Linux systems (and
+Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
+has since been removed.  See the documentation for $$ for
+details.
+.Sp
+Portability issues: "getppid" in perlport.
+.IP "getpriority WHICH,WHO" 4
+.IX Xref "getpriority priority nice"
+.IX Item "getpriority WHICH,WHO"
+Returns the current priority for a process, a process group, or a user.
+(See \fBgetpriority\fR\|(2).)  Will raise a fatal exception if used on a
+machine that doesn't implement \fBgetpriority\fR\|(2).
+.Sp
+\&\f(CW\*(C`WHICH\*(C'\fR can be any of \f(CW\*(C`PRIO_PROCESS\*(C'\fR, \f(CW\*(C`PRIO_PGRP\*(C'\fR or \f(CW\*(C`PRIO_USER\*(C'\fR
+imported from "RESOURCE CONSTANTS" in POSIX.
+.Sp
+Portability issues: "getpriority" in perlport.
+.IP "getpwnam NAME" 4
+.IX Xref "getpwnam getgrnam gethostbyname getnetbyname getprotobyname getpwuid getgrgid getservbyname gethostbyaddr getnetbyaddr getprotobynumber getservbyport getpwent getgrent gethostent getnetent getprotoent getservent setpwent setgrent sethostent setnetent setprotoent setservent endpwent endgrent endhostent endnetent endprotoent endservent"
+.IX Item "getpwnam NAME"
+.PD 0
+.IP "getgrnam NAME" 4
+.IX Item "getgrnam NAME"
+.IP "gethostbyname NAME" 4
+.IX Item "gethostbyname NAME"
+.IP "getnetbyname NAME" 4
+.IX Item "getnetbyname NAME"
+.IP "getprotobyname NAME" 4
+.IX Item "getprotobyname NAME"
+.IP "getpwuid UID" 4
+.IX Item "getpwuid UID"
+.IP "getgrgid GID" 4
+.IX Item "getgrgid GID"
+.IP "getservbyname NAME,PROTO" 4
+.IX Item "getservbyname NAME,PROTO"
+.IP "gethostbyaddr ADDR,ADDRTYPE" 4
+.IX Item "gethostbyaddr ADDR,ADDRTYPE"
+.IP "getnetbyaddr ADDR,ADDRTYPE" 4
+.IX Item "getnetbyaddr ADDR,ADDRTYPE"
+.IP "getprotobynumber NUMBER" 4
+.IX Item "getprotobynumber NUMBER"
+.IP "getservbyport PORT,PROTO" 4
+.IX Item "getservbyport PORT,PROTO"
+.IP getpwent 4
+.IX Item "getpwent"
+.IP getgrent 4
+.IX Item "getgrent"
+.IP gethostent 4
+.IX Item "gethostent"
+.IP getnetent 4
+.IX Item "getnetent"
+.IP getprotoent 4
+.IX Item "getprotoent"
+.IP getservent 4
+.IX Item "getservent"
+.IP setpwent 4
+.IX Item "setpwent"
+.IP setgrent 4
+.IX Item "setgrent"
+.IP "sethostent STAYOPEN" 4
+.IX Item "sethostent STAYOPEN"
+.IP "setnetent STAYOPEN" 4
+.IX Item "setnetent STAYOPEN"
+.IP "setprotoent STAYOPEN" 4
+.IX Item "setprotoent STAYOPEN"
+.IP "setservent STAYOPEN" 4
+.IX Item "setservent STAYOPEN"
+.IP endpwent 4
+.IX Item "endpwent"
+.IP endgrent 4
+.IX Item "endgrent"
+.IP endhostent 4
+.IX Item "endhostent"
+.IP endnetent 4
+.IX Item "endnetent"
+.IP endprotoent 4
+.IX Item "endprotoent"
+.IP endservent 4
+.IX Item "endservent"
+.PD
+These routines are the same as their counterparts in the
+system C library.  In list context, the return values from the
+various get routines are as follows:
+.Sp
+.Vb 9
+\& #    0        1          2           3         4
+\& my ( $name,   $passwd,   $gid,       $members  ) = getgr*
+\& my ( $name,   $aliases,  $addrtype,  $net      ) = getnet*
+\& my ( $name,   $aliases,  $port,      $proto    ) = getserv*
+\& my ( $name,   $aliases,  $proto                ) = getproto*
+\& my ( $name,   $aliases,  $addrtype,  $length,  @addrs ) = gethost*
+\& my ( $name,   $passwd,   $uid,       $gid,     $quota,
+\&    $comment,  $gcos,     $dir,       $shell,   $expire ) = getpw*
+\& #    5        6          7           8         9
+.Ve
+.Sp
+(If the entry doesn't exist, the return value is a single meaningless true
+value.)
+.Sp
+The exact meaning of the \f(CW$gcos\fR field varies but it usually contains
+the real name of the user (as opposed to the login name) and other
+information pertaining to the user.  Beware, however, that in many
+system users are able to change this information and therefore it
+cannot be trusted and therefore the \f(CW$gcos\fR is tainted (see
+perlsec).  The \f(CW$passwd\fR and \f(CW$shell\fR, user's encrypted password and
+login shell, are also tainted, for the same reason.
+.Sp
+In scalar context, you get the name, unless the function was a
+lookup by name, in which case you get the other thing, whatever it is.
+(If the entry doesn't exist you get the undefined value.)  For example:
+.Sp
+.Vb 7
+\&    my $uid   = getpwnam($name);
+\&    my $name  = getpwuid($num);
+\&    my $name  = getpwent();
+\&    my $gid   = getgrnam($name);
+\&    my $name  = getgrgid($num);
+\&    my $name  = getgrent();
+\&    # etc.
+.Ve
+.Sp
+In \fIgetpw*()\fR the fields \f(CW$quota\fR, \f(CW$comment\fR, and \f(CW$expire\fR are special
+in that they are unsupported on many systems.  If the
+\&\f(CW$quota\fR is unsupported, it is an empty scalar.  If it is supported, it
+usually encodes the disk quota.  If the \f(CW$comment\fR field is unsupported,
+it is an empty scalar.  If it is supported it usually encodes some
+administrative comment about the user.  In some systems the \f(CW$quota\fR
+field may be \f(CW$change\fR or \f(CW$age\fR, fields that have to do with password
+aging.  In some systems the \f(CW$comment\fR field may be \f(CW$class\fR.  The \f(CW$expire\fR
+field, if present, encodes the expiration period of the account or the
+password.  For the availability and the exact meaning of these fields
+in your system, please consult \fBgetpwnam\fR\|(3) and your system's
+\&\fIpwd.h\fR file.  You can also find out from within Perl what your
+\&\f(CW$quota\fR and \f(CW$comment\fR fields mean and whether you have the \f(CW$expire\fR field
+by using the \f(CW\*(C`Config\*(C'\fR module and the values \f(CW\*(C`d_pwquota\*(C'\fR, \f(CW\*(C`d_pwage\*(C'\fR,
+\&\f(CW\*(C`d_pwchange\*(C'\fR, \f(CW\*(C`d_pwcomment\*(C'\fR, and \f(CW\*(C`d_pwexpire\*(C'\fR.  Shadow password
+files are supported only if your vendor has implemented them in the
+intuitive fashion that calling the regular C library routines gets the
+shadow versions if you're running under privilege or if there exists
+the \fBshadow\fR\|(3) functions as found in System V (this includes Solaris
+and Linux).  Those systems that implement a proprietary shadow password
+facility are unlikely to be supported.
+.Sp
+The \f(CW$members\fR value returned by \fIgetgr*()\fR is a space-separated list of
+the login names of the members of the group.
+.Sp
+For the \fIgethost*()\fR functions, if the \f(CW\*(C`h_errno\*(C'\fR variable is supported in
+C, it will be returned to you via \f(CW$?\fR if the function
+call fails.  The
+\&\f(CW@addrs\fR value returned by a successful call is a list of raw
+addresses returned by the corresponding library call.  In the
+Internet domain, each address is four bytes long; you can unpack it
+by saying something like:
+.Sp
+.Vb 1
+\&    my ($w,$x,$y,$z) = unpack(\*(AqW4\*(Aq,$addr[0]);
+.Ve
+.Sp
+The Socket library makes this slightly easier:
+.Sp
+.Vb 3
+\&    use Socket;
+\&    my $iaddr = inet_aton("127.1"); # or whatever address
+\&    my $name  = gethostbyaddr($iaddr, AF_INET);
+\&
+\&    # or going the other way
+\&    my $straddr = inet_ntoa($iaddr);
+.Ve
+.Sp
+In the opposite way, to resolve a hostname to the IP address
+you can write this:
+.Sp
+.Vb 6
+\&    use Socket;
+\&    my $packed_ip = gethostbyname("www.perl.org");
+\&    my $ip_address;
+\&    if (defined $packed_ip) {
+\&        $ip_address = inet_ntoa($packed_ip);
+\&    }
+.Ve
+.Sp
+Make sure \f(CW\*(C`gethostbyname\*(C'\fR is called in SCALAR
+context and that its return value is checked for definedness.
+.Sp
+The \f(CW\*(C`getprotobynumber\*(C'\fR function, even
+though it only takes one argument, has the precedence of a list
+operator, so beware:
+.Sp
+.Vb 3
+\&    getprotobynumber $number eq \*(Aqicmp\*(Aq   # WRONG
+\&    getprotobynumber($number eq \*(Aqicmp\*(Aq)  # actually means this
+\&    getprotobynumber($number) eq \*(Aqicmp\*(Aq  # better this way
+.Ve
+.Sp
+If you get tired of remembering which element of the return list
+contains which return value, by-name interfaces are provided in standard
+modules: \f(CW\*(C`File::stat\*(C'\fR, \f(CW\*(C`Net::hostent\*(C'\fR,
+\&\f(CW\*(C`Net::netent\*(C'\fR, \f(CW\*(C`Net::protoent\*(C'\fR,
+\&\f(CW\*(C`Net::servent\*(C'\fR, \f(CW\*(C`Time::gmtime\*(C'\fR,
+\&\f(CW\*(C`Time::localtime\*(C'\fR, and
+\&\f(CW\*(C`User::grent\*(C'\fR.  These override the normal built-ins,
+supplying versions that return objects with the appropriate names for
+each field.  For example:
+.Sp
+.Vb 3
+\&   use File::stat;
+\&   use User::pwent;
+\&   my $is_his = (stat($filename)\->uid == pwent($whoever)\->uid);
+.Ve
+.Sp
+Even though it looks as though they're the same method calls (uid),
+they aren't, because a \f(CW\*(C`File::stat\*(C'\fR object is different from
+a \f(CW\*(C`User::pwent\*(C'\fR object.
+.Sp
+Many of these functions are not safe in a multi-threaded environment
+where more than one thread can be using them.  In particular, functions
+like \f(CWgetpwent()\fR iterate per-process and not per-thread, so if two
+threads are simultaneously iterating, neither will get all the records.
+.Sp
+Some systems have thread-safe versions of some of the functions, such as
+\&\f(CWgetpwnam_r()\fR instead of \f(CWgetpwnam()\fR.  There, Perl automatically and
+invisibly substitutes the thread-safe version, without notice.  This
+means that code that safely runs on some systems can fail on others that
+lack the thread-safe versions.
+.Sp
+Portability issues: "getpwnam" in perlport to "endservent" in perlport.
+.IP "getsockname SOCKET" 4
+.IX Xref "getsockname"
+.IX Item "getsockname SOCKET"
+Returns the packed sockaddr address of this end of the SOCKET connection,
+in case you don't know the address because you have several different
+IPs that the connection might have come in on.
+.Sp
+.Vb 6
+\&    use Socket;
+\&    my $mysockaddr = getsockname($sock);
+\&    my ($port, $myaddr) = sockaddr_in($mysockaddr);
+\&    printf "Connect to %s [%s]\en",
+\&       scalar gethostbyaddr($myaddr, AF_INET),
+\&       inet_ntoa($myaddr);
+.Ve
+.IP "getsockopt SOCKET,LEVEL,OPTNAME" 4
+.IX Xref "getsockopt"
+.IX Item "getsockopt SOCKET,LEVEL,OPTNAME"
+Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
+Options may exist at multiple protocol levels depending on the socket
+type, but at least the uppermost socket level SOL_SOCKET (defined in the
+\&\f(CW\*(C`Socket\*(C'\fR module) will exist.  To query options at another
+level the protocol number of the appropriate protocol controlling the
+option should be supplied.  For example, to indicate that an option is
+to be interpreted by the TCP protocol, LEVEL should be set to the
+protocol number of TCP, which you can get using
+\&\f(CW\*(C`getprotobyname\*(C'\fR.
+.Sp
+The function returns a packed string representing the requested socket
+option, or \f(CW\*(C`undef\*(C'\fR on error, with the reason for the
+error placed in \f(CW$!\fR.  Just what is in the packed string
+depends on LEVEL and OPTNAME; consult \fBgetsockopt\fR\|(2) for details.  A
+common case is that the option is an integer, in which case the result
+is a packed integer, which you can decode using
+\&\f(CW\*(C`unpack\*(C'\fR with the \f(CW\*(C`i\*(C'\fR (or \f(CW\*(C`I\*(C'\fR) format.
+.Sp
+Here's an example to test whether Nagle's algorithm is enabled on a socket:
+.Sp
+.Vb 1
+\&    use Socket qw(:all);
+\&
+\&    defined(my $tcp = getprotobyname("tcp"))
+\&        or die "Could not determine the protocol number for tcp";
+\&    # my $tcp = IPPROTO_TCP; # Alternative
+\&    my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
+\&        or die "getsockopt TCP_NODELAY: $!";
+\&    my $nodelay = unpack("I", $packed);
+\&    print "Nagle\*(Aqs algorithm is turned ",
+\&           $nodelay ? "off\en" : "on\en";
+.Ve
+.Sp
+Portability issues: "getsockopt" in perlport.
+.IP "glob EXPR" 4
+.IX Xref "glob wildcard filename, expansion expand"
+.IX Item "glob EXPR"
+.PD 0
+.IP glob 4
+.IX Item "glob"
+.PD
+In list context, returns a (possibly empty) list of filename expansions on
+the value of EXPR such as the Unix shell Bash would do. In
+scalar context, glob iterates through such filename expansions, returning
+\&\f(CW\*(C`undef\*(C'\fR when the list is exhausted. If EXPR is omitted,
+\&\f(CW$_\fR is used.
+.Sp
+.Vb 3
+\&    # List context
+\&    my @txt_files  = glob("*.txt");
+\&    my @perl_files = glob("*.pl *.pm");
+\&
+\&    # Scalar context
+\&    while (my $file = glob("*.mp3")) {
+\&        # Do stuff
+\&    }
+.Ve
+.Sp
+Glob also supports an alternate syntax using \f(CW\*(C`<\*(C'\fR \f(CW\*(C`>\*(C'\fR as
+delimiters. While this syntax is supported, it is recommended that you
+use \f(CW\*(C`glob\*(C'\fR instead as it is more readable and searchable.
+.Sp
+.Vb 1
+\&    my @txt_files  = <"*.txt">;
+.Ve
+.Sp
+If you need case insensitive file globbing that can be achieved using the
+\&\f(CW\*(C`:nocase\*(C'\fR parameter of the \f(CW\*(C`bsd_glob\*(C'\fR module.
+.Sp
+.Vb 1
+\&    use File::Glob qw(:globally :nocase);
+\&
+\&        my @txt = glob("readme*"); # README readme.txt Readme.md
+.Ve
+.Sp
+Note that \f(CW\*(C`glob\*(C'\fR splits its arguments on whitespace and
+treats
+each segment as separate pattern.  As such, \f(CW\*(C`glob("*.c *.h")\*(C'\fR
+matches all files with a \fI.c\fR or \fI.h\fR extension.  The expression
+\&\f(CW\*(C`glob(".* *")\*(C'\fR matches all files in the current working directory.
+If you want to glob filenames that might contain whitespace, you'll
+have to use extra quotes around the spacey filename to protect it.
+For example, to glob filenames that have an \f(CW\*(C`e\*(C'\fR followed by a space
+followed by an \f(CW\*(C`f\*(C'\fR, use one of:
+.Sp
+.Vb 3
+\&    my @spacies = <"*e f*">;
+\&    my @spacies = glob(\*(Aq"*e f*"\*(Aq);
+\&    my @spacies = glob(q("*e f*"));
+.Ve
+.Sp
+If you had to get a variable through, you could do this:
+.Sp
+.Vb 2
+\&    my @spacies = glob("\*(Aq*${var}e f*\*(Aq");
+\&    my @spacies = glob(qq("*${var}e f*"));
+.Ve
+.Sp
+If non-empty braces are the only wildcard characters used in the
+\&\f(CW\*(C`glob\*(C'\fR, no filenames are matched, but potentially many
+strings are returned.  For example, this produces nine strings, one for
+each pairing of fruits and colors:
+.Sp
+.Vb 1
+\&    my @many = glob("{apple,tomato,cherry}={green,yellow,red}");
+.Ve
+.Sp
+This operator is implemented using the standard \f(CW\*(C`File::Glob\*(C'\fR extension.
+See \f(CW\*(C`bsd_glob\*(C'\fR for details, including
+\&\f(CW\*(C`bsd_glob\*(C'\fR, which does not treat whitespace
+as a pattern separator.
+.Sp
+If a \f(CW\*(C`glob\*(C'\fR expression is used as the condition of a \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`for\*(C'\fR
+loop, then it will be implicitly assigned to \f(CW$_\fR.  If either a \f(CW\*(C`glob\*(C'\fR
+expression or an explicit assignment of a \f(CW\*(C`glob\*(C'\fR expression to a scalar
+is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then the condition actually
+tests for definedness of the expression's value, not for its regular
+truth value.
+.Sp
+Internal implemenation details:
+.Sp
+This is the internal function implementing the \f(CW\*(C`<*.c>\*(C'\fR operator,
+but you can use it directly. The \f(CW\*(C`<*.c>\*(C'\fR operator is discussed in
+more detail in "I/O Operators" in perlop.
+.Sp
+Portability issues: "glob" in perlport.
+.IP "gmtime EXPR" 4
+.IX Xref "gmtime UTC Greenwich"
+.IX Item "gmtime EXPR"
+.PD 0
+.IP gmtime 4
+.IX Item "gmtime"
+.PD
+Works just like \f(CW\*(C`localtime\*(C'\fR, but the returned values
+are localized for the standard Greenwich time zone.
+.Sp
+Note: When called in list context, \f(CW$isdst\fR, the last value
+returned by gmtime, is always \f(CW0\fR.  There is no
+Daylight Saving Time in GMT.
+.Sp
+Portability issues: "gmtime" in perlport.
+.IP "goto LABEL" 4
+.IX Xref "goto jump jmp"
+.IX Item "goto LABEL"
+.PD 0
+.IP "goto EXPR" 4
+.IX Item "goto EXPR"
+.IP "goto &NAME" 4
+.IX Item "goto &NAME"
+.PD
+The \f(CW\*(C`goto LABEL\*(C'\fR form finds the statement labeled with LABEL and
+resumes execution there.  It can't be used to get out of a block or
+subroutine given to \f(CW\*(C`sort\*(C'\fR.  It can be used to go
+almost anywhere else within the dynamic scope, including out of
+subroutines, but it's usually better to use some other construct such as
+\&\f(CW\*(C`last\*(C'\fR or \f(CW\*(C`die\*(C'\fR.  The author of Perl has
+never felt the need to use this form of \f(CW\*(C`goto\*(C'\fR (in Perl,
+that is; C is another matter).  (The difference is that C does not offer
+named loops combined with loop control.  Perl does, and this replaces
+most structured uses of \f(CW\*(C`goto\*(C'\fR in other languages.)
+.Sp
+The \f(CW\*(C`goto EXPR\*(C'\fR form expects to evaluate \f(CW\*(C`EXPR\*(C'\fR to a code reference or
+a label name.  If it evaluates to a code reference, it will be handled
+like \f(CW\*(C`goto &NAME\*(C'\fR, below.  This is especially useful for implementing
+tail recursion via \f(CW\*(C`goto _\|_SUB_\|_\*(C'\fR.
+.Sp
+If the expression evaluates to a label name, its scope will be resolved
+dynamically.  This allows for computed \f(CW\*(C`goto\*(C'\fRs per
+FORTRAN, but isn't necessarily recommended if you're optimizing for
+maintainability:
+.Sp
+.Vb 1
+\&    goto ("FOO", "BAR", "GLARCH")[$i];
+.Ve
+.Sp
+As shown in this example, \f(CW\*(C`goto EXPR\*(C'\fR is exempt from the "looks like a
+function" rule.  A pair of parentheses following it does not (necessarily)
+delimit its argument.  \f(CW\*(C`goto("NE")."XT"\*(C'\fR is equivalent to \f(CW\*(C`goto NEXT\*(C'\fR.
+Also, unlike most named operators, this has the same precedence as
+assignment.
+.Sp
+Use of \f(CW\*(C`goto LABEL\*(C'\fR or \f(CW\*(C`goto EXPR\*(C'\fR to jump into a construct is
+deprecated and will issue a warning.  Even then, it may not be used to
+go into any construct that requires initialization, such as a
+subroutine, a \f(CW\*(C`foreach\*(C'\fR loop, or a \f(CW\*(C`given\*(C'\fR
+block.  In general, it may not be used to jump into the parameter
+of a binary or list operator, but it may be used to jump into the
+\&\fIfirst\fR parameter of a binary operator.  (The \f(CW\*(C`=\*(C'\fR
+assignment operator's "first" operand is its right-hand
+operand.)  It also can't be used to go into a
+construct that is optimized away.
+.Sp
+The \f(CW\*(C`goto &NAME\*(C'\fR form is quite different from the other forms of
+\&\f(CW\*(C`goto\*(C'\fR.  In fact, it isn't a goto in the normal sense at
+all, and doesn't have the stigma associated with other gotos.  Instead,
+it exits the current subroutine (losing any changes set by
+\&\f(CW\*(C`local\*(C'\fR) and immediately calls in its place the named
+subroutine using the current value of \f(CW@_\fR.  This is used
+by \f(CW\*(C`AUTOLOAD\*(C'\fR subroutines that wish to load another subroutine and then
+pretend that the other subroutine had been called in the first place
+(except that any modifications to \f(CW@_\fR in the current
+subroutine are propagated to the other subroutine.) After the
+\&\f(CW\*(C`goto\*(C'\fR, not even \f(CW\*(C`caller\*(C'\fR will be able
+to tell that this routine was called first.
+.Sp
+NAME needn't be the name of a subroutine; it can be a scalar variable
+containing a code reference or a block that evaluates to a code
+reference.
+.IP "grep BLOCK LIST" 4
+.IX Xref "grep"
+.IX Item "grep BLOCK LIST"
+.PD 0
+.IP "grep EXPR,LIST" 4
+.IX Item "grep EXPR,LIST"
+.PD
+This is similar in spirit to, but not the same as, \fBgrep\fR\|(1) and its
+relatives.  In particular, it is not limited to using regular expressions.
+.Sp
+Evaluates the BLOCK or EXPR for each element of LIST (locally setting
+\&\f(CW$_\fR to each element) and returns the list value
+consisting of those
+elements for which the expression evaluated to true.  In scalar
+context, returns the number of times the expression was true.
+.Sp
+.Vb 1
+\&    my @foo = grep(!/^#/, @bar);    # weed out comments
+.Ve
+.Sp
+or equivalently,
+.Sp
+.Vb 1
+\&    my @foo = grep {!/^#/} @bar;    # weed out comments
+.Ve
+.Sp
+Note that \f(CW$_\fR is an alias to the list value, so it can
+be used to
+modify the elements of the LIST.  While this is useful and supported,
+it can cause bizarre results if the elements of LIST are not variables.
+Similarly, grep returns aliases into the original list, much as a for
+loop's index variable aliases the list elements.  That is, modifying an
+element of a list returned by grep (for example, in a \f(CW\*(C`foreach\*(C'\fR,
+\&\f(CW\*(C`map\*(C'\fR or another \f(CW\*(C`grep\*(C'\fR)
+actually modifies the element in the original list.
+This is usually something to be avoided when writing clear code.
+.Sp
+See also \f(CW\*(C`map\*(C'\fR for a list composed of the results of
+the BLOCK or EXPR.
+.IP "hex EXPR" 4
+.IX Xref "hex hexadecimal"
+.IX Item "hex EXPR"
+.PD 0
+.IP hex 4
+.IX Item "hex"
+.PD
+Interprets EXPR as a hex string and returns the corresponding numeric value.
+If EXPR is omitted, uses \f(CW$_\fR.
+.Sp
+.Vb 3
+\&    print hex \*(Aq0xAf\*(Aq; # prints \*(Aq175\*(Aq
+\&    print hex \*(AqaF\*(Aq;   # same
+\&    $valid_input =~ /\eA(?:0?[xX])?(?:_?[0\-9a\-fA\-F])*\ez/
+.Ve
+.Sp
+A hex string consists of hex digits and an optional \f(CW\*(C`0x\*(C'\fR or \f(CW\*(C`x\*(C'\fR prefix.
+Each hex digit may be preceded by a single underscore, which will be ignored.
+Any other character triggers a warning and causes the rest of the string
+to be ignored (even leading whitespace, unlike \f(CW\*(C`oct\*(C'\fR).
+Only integers can be represented, and integer overflow triggers a warning.
+.Sp
+To convert strings that might start with any of \f(CW0\fR, \f(CW\*(C`0x\*(C'\fR, or \f(CW\*(C`0b\*(C'\fR,
+see \f(CW\*(C`oct\*(C'\fR.  To present something as hex, look into
+\&\f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`sprintf\*(C'\fR, and
+\&\f(CW\*(C`unpack\*(C'\fR.
+.IP "import LIST" 4
+.IX Xref "import"
+.IX Item "import LIST"
+There is no builtin \f(CW\*(C`import\*(C'\fR function.  It is just an
+ordinary method (subroutine) defined (or inherited) by modules that wish
+to export names to another module.  The
+\&\f(CW\*(C`use\*(C'\fR function calls the
+\&\f(CW\*(C`import\*(C'\fR method for the package used.  See also
+\&\f(CW\*(C`use\*(C'\fR, perlmod, and Exporter.
+.IP "index STR,SUBSTR,POSITION" 4
+.IX Xref "index indexOf InStr"
+.IX Item "index STR,SUBSTR,POSITION"
+.PD 0
+.IP "index STR,SUBSTR" 4
+.IX Item "index STR,SUBSTR"
+.PD
+The index function searches for one string within another, but without
+the wildcard-like behavior of a full regular-expression pattern match.
+It returns the position of the first occurrence of SUBSTR in STR at
+or after POSITION.  If POSITION is omitted, starts searching from the
+beginning of the string.  POSITION before the beginning of the string
+or after its end is treated as if it were the beginning or the end,
+respectively.  POSITION and the return value are based at zero.
+If the substring is not found, \f(CW\*(C`index\*(C'\fR
+returns \-1.
+.Sp
+Find characters or strings:
+.Sp
+.Vb 3
+\&    index("Perl is great", "P");     # Returns 0
+\&    index("Perl is great", "g");     # Returns 8
+\&    index("Perl is great", "great"); # Also returns 8
+.Ve
+.Sp
+Attempting to find something not there:
+.Sp
+.Vb 1
+\&    index("Perl is great", "Z");     # Returns \-1 (not found)
+.Ve
+.Sp
+Using an offset to find the \fIsecond\fR occurrence:
+.Sp
+.Vb 1
+\&    index("Perl is great", "e", 5);  # Returns 10
+.Ve
+.IP "int EXPR" 4
+.IX Xref "int integer truncate trunc floor"
+.IX Item "int EXPR"
+.PD 0
+.IP int 4
+.IX Item "int"
+.PD
+Returns the integer portion of EXPR.  If EXPR is omitted, uses
+\&\f(CW$_\fR.
+You should not use this function for rounding: one because it truncates
+towards \f(CW0\fR, and two because machine representations of floating-point
+numbers can sometimes produce counterintuitive results.  For example,
+\&\f(CWint(\-6.725/0.025)\fR produces \-268 rather than the correct \-269; that's
+because it's really more like \-268.99999999999994315658 instead.  Usually,
+the \f(CW\*(C`sprintf\*(C'\fR,
+\&\f(CW\*(C`printf\*(C'\fR, or the
+\&\f(CW\*(C`POSIX::floor\*(C'\fR and \f(CW\*(C`POSIX::ceil\*(C'\fR
+functions will serve you better than will \f(CW\*(C`int\*(C'\fR.
+.IP "ioctl FILEHANDLE,FUNCTION,SCALAR" 4
+.IX Xref "ioctl"
+.IX Item "ioctl FILEHANDLE,FUNCTION,SCALAR"
+Implements the \fBioctl\fR\|(2) function.  You'll probably first have to say
+.Sp
+.Vb 2
+\&    require "sys/ioctl.ph";  # probably in
+\&                             # $Config{archlib}/sys/ioctl.ph
+.Ve
+.Sp
+to get the correct function definitions.  If \fIsys/ioctl.ph\fR doesn't
+exist or doesn't have the correct definitions you'll have to roll your
+own, based on your C header files such as \fI<sys/ioctl.h>\fR.
+(There is a Perl script called \fBh2ph\fR that comes with the Perl kit that
+may help you in this, but it's nontrivial.)  SCALAR will be read and/or
+written depending on the FUNCTION; a C pointer to the string value of SCALAR
+will be passed as the third argument of the actual
+\&\f(CW\*(C`ioctl\*(C'\fR call.  (If SCALAR
+has no string value but does have a numeric value, that value will be
+passed rather than a pointer to the string value.  To guarantee this to be
+true, add a \f(CW0\fR to the scalar before using it.)  The
+\&\f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR
+functions may be needed to manipulate the values of structures used by
+\&\f(CW\*(C`ioctl\*(C'\fR.
+.Sp
+The return value of \f(CW\*(C`ioctl\*(C'\fR (and
+\&\f(CW\*(C`fcntl\*(C'\fR) is as follows:
+.Sp
+.Vb 4
+\&    if OS returns:      then Perl returns:
+\&        \-1               undefined value
+\&         0              string "0 but true"
+\&    anything else           that number
+.Ve
+.Sp
+Thus Perl returns true on success and false on failure, yet you can
+still easily determine the actual value returned by the operating
+system:
+.Sp
+.Vb 2
+\&    my $retval = ioctl(...) || \-1;
+\&    printf "System returned %d\en", $retval;
+.Ve
+.Sp
+The special string \f(CW"0 but true"\fR is exempt from
+\&\f(CW\*(C`Argument "..." isn\*(Aqt numeric\*(C'\fR
+warnings on improper numeric conversions.
+.Sp
+Portability issues: "ioctl" in perlport.
+.IP "join EXPR,LIST" 4
+.IX Xref "join"
+.IX Item "join EXPR,LIST"
+Joins the separate strings of LIST into a single string with fields
+separated by the value of EXPR, and returns that new string.  Example:
+.Sp
+.Vb 1
+\&   my $rec = join(\*(Aq:\*(Aq, $login,$passwd,$uid,$gid,$gcos,$home,$shell);
+.Ve
+.Sp
+Beware that unlike \f(CW\*(C`split\*(C'\fR,
+\&\f(CW\*(C`join\*(C'\fR doesn't take a pattern as its first argument.
+Compare \f(CW\*(C`split\*(C'\fR.
+.IP "keys HASH" 4
+.IX Xref "keys key"
+.IX Item "keys HASH"
+.PD 0
+.IP "keys ARRAY" 4
+.IX Item "keys ARRAY"
+.PD
+Called in list context, returns a list consisting of all the keys of the
+named hash, or in Perl 5.12 or later only, the indices of an array.  Perl
+releases prior to 5.12 will produce a syntax error if you try to use an
+array argument.  In scalar context, returns the number of keys or indices.
+.Sp
+Hash entries are returned in an apparently random order.  The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash.  Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by \f(CW\*(C`each\*(C'\fR or
+\&\f(CW\*(C`keys\*(C'\fR may be deleted without changing the order.  So
+long as a given hash is unmodified you may rely on
+\&\f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR and \f(CW\*(C`each\*(C'\fR to repeatedly return the same order
+as each other.  See "Algorithmic Complexity Attacks" in perlsec for
+details on why hash order is randomized.  Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.  Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
+.Sp
+As a side effect, calling \f(CW\*(C`keys\*(C'\fR resets the internal
+iterator of the HASH or ARRAY (see \f(CW\*(C`each\*(C'\fR) before
+yielding the keys.  In
+particular, calling \f(CW\*(C`keys\*(C'\fR in void context resets the
+iterator with no other overhead.
+.Sp
+Here is yet another way to print your environment:
+.Sp
+.Vb 5
+\&    my @keys = keys %ENV;
+\&    my @values = values %ENV;
+\&    while (@keys) {
+\&        print pop(@keys), \*(Aq=\*(Aq, pop(@values), "\en";
+\&    }
+.Ve
+.Sp
+or how about sorted by key:
+.Sp
+.Vb 3
+\&    foreach my $key (sort(keys %ENV)) {
+\&        print $key, \*(Aq=\*(Aq, $ENV{$key}, "\en";
+\&    }
+.Ve
+.Sp
+The returned values are copies of the original keys in the hash, so
+modifying them will not affect the original hash.  Compare
+\&\f(CW\*(C`values\*(C'\fR.
+.Sp
+To sort a hash by value, you'll need to use a
+\&\f(CW\*(C`sort\*(C'\fR function.  Here's a descending numeric
+sort of a hash by its values:
+.Sp
+.Vb 3
+\&    foreach my $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
+\&        printf "%4d %s\en", $hash{$key}, $key;
+\&    }
+.Ve
+.Sp
+Used as an lvalue, \f(CW\*(C`keys\*(C'\fR allows you to increase the
+number of hash buckets
+allocated for the given hash.  This can gain you a measure of efficiency if
+you know the hash is going to get big.  (This is similar to pre-extending
+an array by assigning a larger number to $#array.)  If you say
+.Sp
+.Vb 1
+\&    keys %hash = 200;
+.Ve
+.Sp
+then \f(CW%hash\fR will have at least 200 buckets allocated for it\-\-256 of them,
+in fact, since it rounds up to the next power of two.  These
+buckets will be retained even if you do \f(CW\*(C`%hash = ()\*(C'\fR, use \f(CWundef
+%hash\fR if you want to free the storage while \f(CW%hash\fR is still in scope.
+You can't shrink the number of buckets allocated for the hash using
+\&\f(CW\*(C`keys\*(C'\fR in this way (but you needn't worry about doing
+this by accident, as trying has no effect).  \f(CW\*(C`keys @array\*(C'\fR in an lvalue
+context is a syntax error.
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`keys\*(C'\fR to take a scalar expression. This experiment has
+been deemed unsuccessful, and was removed as of Perl 5.24.
+.Sp
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work \fIonly\fR on Perls of
+a recent vintage:
+.Sp
+.Vb 1
+\&    use v5.12;  # so keys/values/each work on arrays
+.Ve
+.Sp
+See also \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`values\*(C'\fR, and
+\&\f(CW\*(C`sort\*(C'\fR.
+.IP "kill SIGNAL, LIST" 4
+.IX Item "kill SIGNAL, LIST"
+.PD 0
+.IP "kill SIGNAL" 4
+.IX Xref "kill signal"
+.IX Item "kill SIGNAL"
+.PD
+Sends a signal to a list of processes.  Returns the number of arguments
+that were successfully used to signal (which is not necessarily the same
+as the number of processes actually killed, e.g. where a process group is
+killed).
+.Sp
+.Vb 2
+\&    my $cnt = kill \*(AqHUP\*(Aq, $child1, $child2;
+\&    kill \*(AqKILL\*(Aq, @goners;
+.Ve
+.Sp
+SIGNAL may be either a signal name (a string) or a signal number.  A signal
+name may start with a \f(CW\*(C`SIG\*(C'\fR prefix, thus \f(CW\*(C`FOO\*(C'\fR and \f(CW\*(C`SIGFOO\*(C'\fR refer to the
+same signal.  The string form of SIGNAL is recommended for portability because
+the same signal may have different numbers in different operating systems.
+.Sp
+A list of signal names supported by the current platform can be found in
+\&\f(CW$Config{sig_name}\fR, which is provided by the \f(CW\*(C`Config\*(C'\fR
+module.  See Config for more details.
+.Sp
+A negative signal name is the same as a negative signal number, killing process
+groups instead of processes.  For example, \f(CW\*(C`kill \*(Aq\-KILL\*(Aq, $pgrp\*(C'\fR and
+\&\f(CW\*(C`kill \-9, $pgrp\*(C'\fR will send \f(CW\*(C`SIGKILL\*(C'\fR to
+the entire process group specified.  That
+means you usually want to use positive not negative signals.
+.Sp
+If SIGNAL is either the number 0 or the string \f(CW\*(C`ZERO\*(C'\fR (or \f(CW\*(C`SIGZERO\*(C'\fR),
+no signal is sent to the process, but \f(CW\*(C`kill\*(C'\fR
+checks whether it's \fIpossible\fR to send a signal to it
+(that means, to be brief, that the process is owned by the same user, or we are
+the super-user).  This is useful to check that a child process is still
+alive (even if only as a zombie) and hasn't changed its UID.  See
+perlport for notes on the portability of this construct.
+.Sp
+The behavior of kill when a \fIPROCESS\fR number is zero or negative depends on
+the operating system.  For example, on POSIX-conforming systems, zero will
+signal the current process group, \-1 will signal all processes, and any
+other negative PROCESS number will act as a negative signal number and
+kill the entire process group specified.
+.Sp
+If both the SIGNAL and the PROCESS are negative, the results are undefined.
+A warning may be produced in a future version.
+.Sp
+See "Signals" in perlipc for more details.
+.Sp
+On some platforms such as Windows where the \fBfork\fR\|(2) system call is not
+available, Perl can be built to emulate \f(CW\*(C`fork\*(C'\fR at the
+interpreter level.
+This emulation has limitations related to kill that have to be considered,
+for code running on Windows and in code intended to be portable.
+.Sp
+See perlfork for more details.
+.Sp
+If there is no \fILIST\fR of processes, no signal is sent, and the return
+value is 0.  This form is sometimes used, however, because it causes
+tainting checks to be run, if your perl support taint checks.  But see
+"Laundering and Detecting Tainted Data" in perlsec.
+.Sp
+Portability issues: "kill" in perlport.
+.IP "last LABEL" 4
+.IX Xref "last break"
+.IX Item "last LABEL"
+.PD 0
+.IP "last EXPR" 4
+.IX Item "last EXPR"
+.IP last 4
+.IX Item "last"
+.PD
+The \f(CW\*(C`last\*(C'\fR command is like the \f(CW\*(C`break\*(C'\fR statement in C
+(as used in
+loops); it immediately exits the loop in question.  If the LABEL is
+omitted, the command refers to the innermost enclosing
+loop.  The \f(CW\*(C`last EXPR\*(C'\fR form, available starting in Perl
+5.18.0, allows a label name to be computed at run time,
+and is otherwise identical to \f(CW\*(C`last LABEL\*(C'\fR.  The
+\&\f(CW\*(C`continue\*(C'\fR block, if any, is not executed:
+.Sp
+.Vb 4
+\&    LINE: while (<STDIN>) {
+\&        last LINE if /^$/;  # exit when done with header
+\&        #...
+\&    }
+.Ve
+.Sp
+\&\f(CW\*(C`last\*(C'\fR cannot return a value from a block that typically
+returns a value, such as \f(CW\*(C`eval {}\*(C'\fR, \f(CW\*(C`sub {}\*(C'\fR, or \f(CW\*(C`do {}\*(C'\fR. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a \f(CW\*(C`grep\*(C'\fR or \f(CW\*(C`map\*(C'\fR
+operation.
+.Sp
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus \f(CW\*(C`last\*(C'\fR can be used to effect
+an early exit out of such a block.
+.Sp
+See also \f(CW\*(C`continue\*(C'\fR for an illustration of how
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, and
+\&\f(CW\*(C`redo\*(C'\fR work.
+.Sp
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+\&\f(CW\*(C`last ("foo")."bar"\*(C'\fR will cause "bar" to be part of the argument to
+\&\f(CW\*(C`last\*(C'\fR.
+.IP "lc EXPR" 4
+.IX Xref "lc lowercase"
+.IX Item "lc EXPR"
+.PD 0
+.IP lc 4
+.IX Item "lc"
+.PD
+Returns a lowercased version of EXPR.  If EXPR is omitted, uses
+\&\f(CW$_\fR.
+.Sp
+.Vb 1
+\&    my $str = lc("Perl is GREAT"); # "perl is great"
+.Ve
+.Sp
+What gets returned depends on several factors:
+.RS 4
+.ie n .IP "If ""use bytes"" is in effect:" 4
+.el .IP "If \f(CWuse bytes\fR is in effect:" 4
+.IX Item "If use bytes is in effect:"
+The results follow ASCII rules.  Only the characters \f(CW\*(C`A\-Z\*(C'\fR change,
+to \f(CW\*(C`a\-z\*(C'\fR respectively.
+.ie n .IP "Otherwise, if ""use locale"" for ""LC_CTYPE"" is in effect:" 4
+.el .IP "Otherwise, if \f(CWuse locale\fR for \f(CWLC_CTYPE\fR is in effect:" 4
+.IX Item "Otherwise, if use locale for LC_CTYPE is in effect:"
+Respects current \f(CW\*(C`LC_CTYPE\*(C'\fR locale for code points < 256; and uses Unicode
+rules for the remaining code points (this last can only happen if
+the UTF8 flag is also set).  See perllocale.
+.Sp
+Starting in v5.20, Perl uses full Unicode rules if the locale is
+UTF\-8.  Otherwise, there is a deficiency in this scheme, which is that
+case changes that cross the 255/256
+boundary are not well-defined.  For example, the lower case of LATIN CAPITAL
+LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
+platforms).   But under \f(CW\*(C`use locale\*(C'\fR (prior to v5.20 or not a UTF\-8
+locale), the lower case of U+1E9E is
+itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
+current locale, and Perl has no way of knowing if that character even
+exists in the locale, much less what code point it is.  Perl returns
+a result that is above 255 (almost always the input character unchanged),
+for all instances (and there aren't many) where the 255/256 boundary
+would otherwise be crossed; and starting in v5.22, it raises a
+locale warning.
+.IP "Otherwise, If EXPR has the UTF8 flag set:" 4
+.IX Item "Otherwise, If EXPR has the UTF8 flag set:"
+Unicode rules are used for the case change.
+.ie n .IP "Otherwise, if ""use feature \*(Aqunicode_strings\*(Aq"" or ""use locale \*(Aq:not_characters\*(Aq"" is in effect:" 4
+.el .IP "Otherwise, if \f(CWuse feature \*(Aqunicode_strings\*(Aq\fR or \f(CWuse locale \*(Aq:not_characters\*(Aq\fR is in effect:" 4
+.IX Item "Otherwise, if use feature unicode_strings or use locale :not_characters is in effect:"
+Unicode rules are used for the case change.
+.IP Otherwise: 4
+.IX Item "Otherwise:"
+ASCII rules are used for the case change.  The lowercase of any character
+outside the ASCII range is the character itself.
+.RE
+.RS 4
+.Sp
+\&\fBNote:\fR This is the internal function implementing the
+\&\f(CW\*(C`\eL\*(C'\fR escape in double-quoted
+strings.
+.Sp
+.Vb 1
+\&    my $str = "Perl is \eLGREAT\eE"; # "Perl is great"
+.Ve
+.RE
+.IP "lcfirst EXPR" 4
+.IX Xref "lcfirst lowercase"
+.IX Item "lcfirst EXPR"
+.PD 0
+.IP lcfirst 4
+.IX Item "lcfirst"
+.PD
+Returns the value of EXPR with the first character lowercased.  This
+is the internal function implementing the \f(CW\*(C`\el\*(C'\fR escape in
+double-quoted strings.
+.Sp
+If EXPR is omitted, uses \f(CW$_\fR.
+.Sp
+This function behaves the same way under various pragmas, such as in a locale,
+as \f(CW\*(C`lc\*(C'\fR does.
+.IP "length EXPR" 4
+.IX Xref "length size"
+.IX Item "length EXPR"
+.PD 0
+.IP length 4
+.IX Item "length"
+.PD
+Returns the length in \fIcharacters\fR of the value of EXPR.  If EXPR is
+omitted, returns the length of \f(CW$_\fR.  If EXPR is
+undefined, returns \f(CW\*(C`undef\*(C'\fR.
+.Sp
+This function cannot be used on an entire array or hash to find out how
+many elements these have.  For that, use \f(CW\*(C`scalar @array\*(C'\fR and \f(CWscalar keys
+%hash\fR, respectively.
+.Sp
+Like all Perl character operations, \f(CW\*(C`length\*(C'\fR normally
+deals in logical
+characters, not physical bytes.  For how many bytes a string encoded as
+UTF\-8 would take up, use \f(CW\*(C`length(Encode::encode(\*(AqUTF\-8\*(Aq, EXPR))\*(C'\fR
+(you'll have to \f(CW\*(C`use Encode\*(C'\fR first).  See Encode and perlunicode.
+.IP _\|_LINE_\|_ 4
+.IX Xref "__LINE__"
+.IX Item "__LINE__"
+A special token that compiles to the current line number.
+It can be altered by the mechanism described at
+"Plain Old Comments (Not!)" in perlsyn.
+.IP "link OLDFILE,NEWFILE" 4
+.IX Xref "link"
+.IX Item "link OLDFILE,NEWFILE"
+Creates a new filename linked to the old filename.  Returns true for
+success, false otherwise.
+.Sp
+Portability issues: "link" in perlport.
+.IP "listen SOCKET,QUEUESIZE" 4
+.IX Xref "listen"
+.IX Item "listen SOCKET,QUEUESIZE"
+Does the same thing that the \fBlisten\fR\|(2) system call does.  Returns true if
+it succeeded, false otherwise.  See the example in
+"Sockets: Client/Server Communication" in perlipc.
+.IP "local EXPR" 4
+.IX Xref "local"
+.IX Item "local EXPR"
+You really probably want to be using \f(CW\*(C`my\*(C'\fR instead,
+because \f(CW\*(C`local\*(C'\fR isn't what most people think of as
+"local".  See "Private Variables via \fBmy()\fR" in perlsub for details.
+.Sp
+A local modifies the listed variables to be local to the enclosing
+block, file, or eval.  If more than one value is listed, the list must
+be placed in parentheses.  See "Temporary Values via \fBlocal()\fR" in perlsub
+for details, including issues with tied arrays and hashes.
+.Sp
+The \f(CW\*(C`delete local EXPR\*(C'\fR construct can also be used to localize the deletion
+of array/hash elements to the current block.
+See "Localized deletion of elements of composite types" in perlsub.
+.IP "localtime EXPR" 4
+.IX Xref "localtime ctime"
+.IX Item "localtime EXPR"
+.PD 0
+.IP localtime 4
+.IX Item "localtime"
+.PD
+Converts a time as returned by the time function to a 9\-element list
+with the time analyzed for the local time zone.  Typically used as
+follows:
+.Sp
+.Vb 3
+\&    #     0    1    2     3     4    5     6     7     8
+\&    my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
+\&                                                localtime(time);
+.Ve
+.Sp
+All list elements are numeric and come straight out of the C `struct
+tm'.  \f(CW$sec\fR, \f(CW$min\fR, and \f(CW$hour\fR are the seconds, minutes, and hours
+of the specified time.
+.Sp
+\&\f(CW$mday\fR is the day of the month and \f(CW$mon\fR the month in
+the range \f(CW0..11\fR, with 0 indicating January and 11 indicating December.
+This makes it easy to get a month name from a list:
+.Sp
+.Vb 3
+\&    my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
+\&    print "$abbr[$mon] $mday";
+\&    # $mon=9, $mday=18 gives "Oct 18"
+.Ve
+.Sp
+\&\f(CW$year\fR contains the number of years since 1900.  To get the full
+year write:
+.Sp
+.Vb 1
+\&    $year += 1900;
+.Ve
+.Sp
+To get the last two digits of the year (e.g., "01" in 2001) do:
+.Sp
+.Vb 1
+\&    $year = sprintf("%02d", $year % 100);
+.Ve
+.Sp
+\&\f(CW$wday\fR is the day of the week, with 0 indicating Sunday and 3 indicating
+Wednesday.  \f(CW$yday\fR is the day of the year, in the range \f(CW0..364\fR
+(or \f(CW0..365\fR in leap years.)
+.Sp
+\&\f(CW$isdst\fR is true if the specified time occurs when Daylight Saving
+Time is in effect, false otherwise.
+.Sp
+If EXPR is omitted, \f(CW\*(C`localtime\*(C'\fR uses the current
+time (as returned by \f(CW\*(C`time\*(C'\fR).
+.Sp
+In scalar context, \f(CW\*(C`localtime\*(C'\fR returns the
+\&\fBctime\fR\|(3) value:
+.Sp
+.Vb 1
+\& my $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
+.Ve
+.Sp
+This scalar value is always in English, and is \fBnot\fR locale-dependent.
+To get similar but locale-dependent date strings, try for example:
+.Sp
+.Vb 4
+\& use POSIX qw(strftime);
+\& my $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
+\& # or for GMT formatted appropriately for your locale:
+\& my $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
+.Ve
+.Sp
+C$now_string> will be formatted according to the current LC_TIME locale
+the program or thread is running in.  See perllocale for how to set
+up and change that locale.  Note that \f(CW%a\fR and \f(CW%b\fR, the short forms
+of the day of the week and the month of the year, may not necessarily be
+three characters wide.
+.Sp
+The Time::gmtime and Time::localtime modules provide a convenient,
+by-name access mechanism to the \f(CW\*(C`gmtime\*(C'\fR and
+\&\f(CW\*(C`localtime\*(C'\fR functions, respectively.
+.Sp
+For a comprehensive date and time representation look at the
+DateTime module on CPAN.
+.Sp
+For GMT instead of local time use the \f(CW\*(C`gmtime\*(C'\fR builtin.
+.Sp
+See also the \f(CW\*(C`Time::Local\*(C'\fR module (for converting
+seconds, minutes, hours, and such back to the integer value returned by
+\&\f(CW\*(C`time\*(C'\fR), and the POSIX module's
+\&\f(CW\*(C`mktime\*(C'\fR function.
+.Sp
+Portability issues: "localtime" in perlport.
+.IP "lock THING" 4
+.IX Xref "lock"
+.IX Item "lock THING"
+This function places an advisory lock on a shared variable or referenced
+object contained in \fITHING\fR until the lock goes out of scope.
+.Sp
+The value returned is the scalar itself, if the argument is a scalar, or a
+reference, if the argument is a hash, array or subroutine.
+.Sp
+\&\f(CW\*(C`lock\*(C'\fR is a "weak keyword"; this means that if you've
+defined a function
+by this name (before any calls to it), that function will be called
+instead.  If you are not under \f(CW\*(C`use threads::shared\*(C'\fR this does nothing.
+See threads::shared.
+.IP "log EXPR" 4
+.IX Xref "log logarithm e ln base"
+.IX Item "log EXPR"
+.PD 0
+.IP log 4
+.IX Item "log"
+.PD
+Returns the natural logarithm (base \fIe\fR) of EXPR.  If EXPR is omitted,
+returns the log of \f(CW$_\fR.  To get the
+log of another base, use basic algebra:
+The base-N log of a number is equal to the natural log of that number
+divided by the natural log of N.  For example:
+.Sp
+.Vb 4
+\&    sub log10 {
+\&        my $n = shift;
+\&        return log($n)/log(10);
+\&    }
+.Ve
+.Sp
+See also \f(CW\*(C`exp\*(C'\fR for the inverse operation.
+.IP "lstat FILEHANDLE" 4
+.IX Xref "lstat"
+.IX Item "lstat FILEHANDLE"
+.PD 0
+.IP "lstat EXPR" 4
+.IX Item "lstat EXPR"
+.IP "lstat DIRHANDLE" 4
+.IX Item "lstat DIRHANDLE"
+.IP lstat 4
+.IX Item "lstat"
+.PD
+Does the same thing as the \f(CW\*(C`stat\*(C'\fR function
+(including setting the special \f(CW\*(C`_\*(C'\fR filehandle) but stats a symbolic
+link instead of the file the symbolic link points to.  If symbolic links
+are unimplemented on your system, a normal \f(CW\*(C`stat\*(C'\fR
+is done.  For much more detailed information, please see the
+documentation for \f(CW\*(C`stat\*(C'\fR.
+.Sp
+If EXPR is omitted, stats \f(CW$_\fR.
+.Sp
+Portability issues: "lstat" in perlport.
+.IP m// 4
+.IX Item "m//"
+The match operator.  See "Regexp Quote-Like Operators" in perlop.
+.IP "map BLOCK LIST" 4
+.IX Xref "map"
+.IX Item "map BLOCK LIST"
+.PD 0
+.IP "map EXPR,LIST" 4
+.IX Item "map EXPR,LIST"
+.PD
+Evaluates the BLOCK or EXPR for each element of LIST (locally setting
+\&\f(CW$_\fR to each element) and composes a list of the results of
+each such evaluation.  Each element of LIST may produce zero, one, or more
+elements in the generated list, so the number of elements in the generated
+list may differ from that in LIST.  In scalar context, returns the total
+number of elements so generated.  In list context, returns the generated list.
+.Sp
+.Vb 1
+\&    my @chars = map(chr, @numbers);
+.Ve
+.Sp
+translates a list of numbers to the corresponding characters.
+.Sp
+.Vb 1
+\&    my @squares = map { $_ * $_ } @numbers;
+.Ve
+.Sp
+translates a list of numbers to their squared values.
+.Sp
+.Vb 1
+\&    my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
+.Ve
+.Sp
+shows that number of returned elements can differ from the number of
+input elements.  To omit an element, return an empty list ().
+This could also be achieved by writing
+.Sp
+.Vb 1
+\&    my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
+.Ve
+.Sp
+which makes the intention more clear.
+.Sp
+Map always returns a list, which can be
+assigned to a hash such that the elements
+become key/value pairs.  See perldata for more details.
+.Sp
+.Vb 1
+\&    my %hash = map { get_a_key_for($_) => $_ } @array;
+.Ve
+.Sp
+is just a funny way to write
+.Sp
+.Vb 4
+\&    my %hash;
+\&    foreach (@array) {
+\&        $hash{get_a_key_for($_)} = $_;
+\&    }
+.Ve
+.Sp
+Note that \f(CW$_\fR is an alias to the list value, so it can
+be used to modify the elements of the LIST.  While this is useful and
+supported, it can cause bizarre results if the elements of LIST are not
+variables.  Using a regular \f(CW\*(C`foreach\*(C'\fR loop for this purpose would be
+clearer in most cases.  See also \f(CW\*(C`grep\*(C'\fR for a
+list composed of those items of the original list for which the BLOCK
+or EXPR evaluates to true.
+.Sp
+\&\f(CW\*(C`{\*(C'\fR starts both hash references and blocks, so \f(CW\*(C`map { ...\*(C'\fR could be either
+the start of map BLOCK LIST or map EXPR, LIST.  Because Perl doesn't look
+ahead for the closing \f(CW\*(C`}\*(C'\fR it has to take a guess at which it's dealing with
+based on what it finds just after the
+\&\f(CW\*(C`{\*(C'\fR.  Usually it gets it right, but if it
+doesn't it won't realize something is wrong until it gets to the \f(CW\*(C`}\*(C'\fR and
+encounters the missing (or unexpected) comma.  The syntax error will be
+reported close to the \f(CW\*(C`}\*(C'\fR, but you'll need to change something near the \f(CW\*(C`{\*(C'\fR
+such as using a unary \f(CW\*(C`+\*(C'\fR or semicolon to give Perl some help:
+.Sp
+.Vb 6
+\& my %hash = map {  "\eL$_" => 1  } @array # perl guesses EXPR. wrong
+\& my %hash = map { +"\eL$_" => 1  } @array # perl guesses BLOCK. right
+\& my %hash = map {; "\eL$_" => 1  } @array # this also works
+\& my %hash = map { ("\eL$_" => 1) } @array # as does this
+\& my %hash = map {  lc($_) => 1  } @array # and this.
+\& my %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
+\&
+\& my %hash = map  ( lc($_), 1 ),   @array # evaluates to (1, @array)
+.Ve
+.Sp
+or to force an anon hash constructor use \f(CW\*(C`+{\*(C'\fR:
+.Sp
+.Vb 2
+\&    my @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs
+\&                                              # comma at end
+.Ve
+.Sp
+to get a list of anonymous hashes each with only one entry apiece.
+.IP "method NAME BLOCK" 4
+.IX Xref "method"
+.IX Item "method NAME BLOCK"
+.PD 0
+.IP "method NAME : ATTRS BLOCK" 4
+.IX Item "method NAME : ATTRS BLOCK"
+.PD
+Creates a new named method in the scope of the class that it appears within.
+This is only valid inside a \f(CW\*(C`class\*(C'\fR declaration.
+.IP "mkdir FILENAME,MODE" 4
+.IX Xref "mkdir md directory, create"
+.IX Item "mkdir FILENAME,MODE"
+.PD 0
+.IP "mkdir FILENAME" 4
+.IX Item "mkdir FILENAME"
+.IP mkdir 4
+.IX Item "mkdir"
+.PD
+Creates the directory specified by FILENAME, with permissions
+specified by MODE (as modified by \f(CW\*(C`umask\*(C'\fR).  If it
+succeeds it returns true; otherwise it returns false and sets
+\&\f(CW$!\fR (errno).
+MODE defaults to 0777 if omitted, and FILENAME defaults
+to \f(CW$_\fR if omitted.
+.Sp
+In general, it is better to create directories with a permissive MODE
+and let the user modify that with their \f(CW\*(C`umask\*(C'\fR than it
+is to supply
+a restrictive MODE and give the user no way to be more permissive.
+The exceptions to this rule are when the file or directory should be
+kept private (mail files, for instance).  The documentation for
+\&\f(CW\*(C`umask\*(C'\fR discusses the choice of MODE in more detail.
+If bits in MODE other than the permission bits are set, the result may
+be implementation defined, per POSIX 1003.1\-2008.
+.Sp
+Note that according to the POSIX 1003.1\-1996 the FILENAME may have any
+number of trailing slashes.  Some operating and filesystems do not get
+this right, so Perl automatically removes all trailing slashes to keep
+everyone happy.
+.Sp
+To recursively create a directory structure, look at
+the \f(CW\*(C`make_path\*(C'\fR function
+of the File::Path module.
+.IP "msgctl ID,CMD,ARG" 4
+.IX Xref "msgctl"
+.IX Item "msgctl ID,CMD,ARG"
+Calls the System V IPC function \fBmsgctl\fR\|(2).  You'll probably have to say
+.Sp
+.Vb 1
+\&    use IPC::SysV;
+.Ve
+.Sp
+first to get the correct constant definitions.  If CMD is \f(CW\*(C`IPC_STAT\*(C'\fR,
+then ARG must be a variable that will hold the returned \f(CW\*(C`msqid_ds\*(C'\fR
+structure.  Returns like \f(CW\*(C`ioctl\*(C'\fR:
+the undefined value for error, \f(CW"0 but true"\fR for zero, or the actual
+return value otherwise.  See also "SysV IPC" in perlipc and the
+documentation for \f(CW\*(C`IPC::SysV\*(C'\fR and
+\&\f(CW\*(C`IPC::Semaphore\*(C'\fR.
+.Sp
+Portability issues: "msgctl" in perlport.
+.IP "msgget KEY,FLAGS" 4
+.IX Xref "msgget"
+.IX Item "msgget KEY,FLAGS"
+Calls the System V IPC function \fBmsgget\fR\|(2).  Returns the message queue
+id, or \f(CW\*(C`undef\*(C'\fR on error.  See also "SysV IPC" in perlipc
+and the documentation for \f(CW\*(C`IPC::SysV\*(C'\fR and
+\&\f(CW\*(C`IPC::Msg\*(C'\fR.
+.Sp
+Portability issues: "msgget" in perlport.
+.IP "msgrcv ID,VAR,SIZE,TYPE,FLAGS" 4
+.IX Xref "msgrcv"
+.IX Item "msgrcv ID,VAR,SIZE,TYPE,FLAGS"
+Calls the System V IPC function msgrcv to receive a message from
+message queue ID into variable VAR with a maximum message size of
+SIZE.  Note that when a message is received, the message type as a
+native long integer will be the first thing in VAR, followed by the
+actual message.  This packing may be opened with \f(CW\*(C`unpack("l! a*")\*(C'\fR.
+Taints the variable.  Returns true if successful, false
+on error.  See also "SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR and \f(CW\*(C`IPC::Msg\*(C'\fR.
+.Sp
+Portability issues: "msgrcv" in perlport.
+.IP "msgsnd ID,MSG,FLAGS" 4
+.IX Xref "msgsnd"
+.IX Item "msgsnd ID,MSG,FLAGS"
+Calls the System V IPC function msgsnd to send the message MSG to the
+message queue ID.  MSG must begin with the native long integer message
+type, followed by the message itself.  This kind of packing can be achieved
+with \f(CW\*(C`pack("l! a*", $type, $message)\*(C'\fR.  Returns true if successful,
+false on error.  See also "SysV IPC" in perlipc and the documentation
+for \f(CW\*(C`IPC::SysV\*(C'\fR and \f(CW\*(C`IPC::Msg\*(C'\fR.
+.Sp
+Portability issues: "msgsnd" in perlport.
+.IP "my VARLIST" 4
+.IX Xref "my"
+.IX Item "my VARLIST"
+.PD 0
+.IP "my TYPE VARLIST" 4
+.IX Item "my TYPE VARLIST"
+.IP "my VARLIST : ATTRS" 4
+.IX Item "my VARLIST : ATTRS"
+.IP "my TYPE VARLIST : ATTRS" 4
+.IX Item "my TYPE VARLIST : ATTRS"
+.PD
+A \f(CW\*(C`my\*(C'\fR declares the listed variables to be local
+(lexically) to the enclosing block, file, or \f(CW\*(C`eval\*(C'\fR.  If
+more than one variable is listed, the list must be placed in
+parentheses.
+.Sp
+Note that with a parenthesised list, \f(CW\*(C`undef\*(C'\fR can be used
+as a dummy placeholder, for example to skip assignment of initial
+values:
+.Sp
+.Vb 1
+\&    my ( undef, $min, $hour ) = localtime;
+.Ve
+.Sp
+Redeclaring a variable in the same scope or statement will "shadow" the
+previous declaration, creating a new instance and preventing access to
+the previous one. This is usually undesired and, if warnings are enabled,
+will result in a warning in the \f(CW\*(C`shadow\*(C'\fR category.
+.Sp
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE may be a bareword, a constant declared
+with \f(CW\*(C`use constant\*(C'\fR, or \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR.  It
+is
+currently bound to the use of the fields pragma,
+and attributes are handled using the attributes pragma, or starting
+from Perl 5.8.0 also via the Attribute::Handlers module.  See
+"Private Variables via \fBmy()\fR" in perlsub for details.
+.IP "next LABEL" 4
+.IX Xref "next continue"
+.IX Item "next LABEL"
+.PD 0
+.IP "next EXPR" 4
+.IX Item "next EXPR"
+.IP next 4
+.IX Item "next"
+.PD
+The \f(CW\*(C`next\*(C'\fR command is like the \f(CW\*(C`continue\*(C'\fR statement in
+C; it starts the next iteration of the loop:
+.Sp
+.Vb 4
+\&    LINE: while (<STDIN>) {
+\&        next LINE if /^#/;  # discard comments
+\&        #...
+\&    }
+.Ve
+.Sp
+Note that if there were a \f(CW\*(C`continue\*(C'\fR block on the
+above, it would get
+executed even on discarded lines.  If LABEL is omitted, the command
+refers to the innermost enclosing loop.  The \f(CW\*(C`next EXPR\*(C'\fR form, available
+as of Perl 5.18.0, allows a label name to be computed at run time, being
+otherwise identical to \f(CW\*(C`next LABEL\*(C'\fR.
+.Sp
+\&\f(CW\*(C`next\*(C'\fR cannot return a value from a block that typically
+returns a value, such as \f(CW\*(C`eval {}\*(C'\fR, \f(CW\*(C`sub {}\*(C'\fR, or \f(CW\*(C`do {}\*(C'\fR. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a \f(CW\*(C`grep\*(C'\fR or \f(CW\*(C`map\*(C'\fR
+operation.
+.Sp
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus \f(CW\*(C`next\*(C'\fR will exit such a block
+early.
+.Sp
+See also \f(CW\*(C`continue\*(C'\fR for an illustration of how
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, and
+\&\f(CW\*(C`redo\*(C'\fR work.
+.Sp
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+\&\f(CW\*(C`next ("foo")."bar"\*(C'\fR will cause "bar" to be part of the argument to
+\&\f(CW\*(C`next\*(C'\fR.
+.IP "no MODULE VERSION LIST" 4
+.IX Xref "no declarations unimporting"
+.IX Item "no MODULE VERSION LIST"
+.PD 0
+.IP "no MODULE VERSION" 4
+.IX Item "no MODULE VERSION"
+.IP "no MODULE LIST" 4
+.IX Item "no MODULE LIST"
+.IP "no MODULE" 4
+.IX Item "no MODULE"
+.IP "no VERSION" 4
+.IX Item "no VERSION"
+.PD
+See the \f(CW\*(C`use\*(C'\fR function, of which
+\&\f(CW\*(C`no\*(C'\fR is the opposite.
+.IP "oct EXPR" 4
+.IX Xref "oct octal hex hexadecimal binary bin"
+.IX Item "oct EXPR"
+.PD 0
+.IP oct 4
+.IX Item "oct"
+.PD
+Interprets EXPR as an octal string and returns the corresponding
+value.  An octal string consists of octal digits and, as of Perl 5.33.5,
+an optional \f(CW\*(C`0o\*(C'\fR or \f(CW\*(C`o\*(C'\fR prefix.  Each octal digit may be preceded by
+a single underscore, which will be ignored.
+(If EXPR happens to start off with \f(CW\*(C`0x\*(C'\fR or \f(CW\*(C`x\*(C'\fR, interprets it as a
+hex string.  If EXPR starts off with \f(CW\*(C`0b\*(C'\fR or \f(CW\*(C`b\*(C'\fR, it is interpreted as a
+binary string.  Leading whitespace is ignored in all three cases.)
+The following will handle decimal, binary, octal, and hex in standard
+Perl notation:
+.Sp
+.Vb 1
+\&    $val = oct($val) if $val =~ /^0/;
+.Ve
+.Sp
+If EXPR is omitted, uses \f(CW$_\fR.   To go the other way
+(produce a number in octal), use \f(CW\*(C`sprintf\*(C'\fR or
+\&\f(CW\*(C`printf\*(C'\fR:
+.Sp
+.Vb 2
+\&    my $dec_perms = (stat("filename"))[2] & 07777;
+\&    my $oct_perm_str = sprintf "%o", $perms;
+.Ve
+.Sp
+The \f(CW\*(C`oct\*(C'\fR function is commonly used when a string such as
+\&\f(CW644\fR needs
+to be converted into a file mode, for example.  Although Perl
+automatically converts strings into numbers as needed, this automatic
+conversion assumes base 10.
+.Sp
+Leading white space is ignored without warning, as too are any trailing
+non-digits, such as a decimal point (\f(CW\*(C`oct\*(C'\fR only handles
+non-negative integers, not negative integers or floating point).
+.IP "open FILEHANDLE,MODE,EXPR" 4
+.IX Xref "open pipe file, open fopen"
+.IX Item "open FILEHANDLE,MODE,EXPR"
+.PD 0
+.IP "open FILEHANDLE,MODE,EXPR,LIST" 4
+.IX Item "open FILEHANDLE,MODE,EXPR,LIST"
+.IP "open FILEHANDLE,MODE,REFERENCE" 4
+.IX Item "open FILEHANDLE,MODE,REFERENCE"
+.IP "open FILEHANDLE,EXPR" 4
+.IX Item "open FILEHANDLE,EXPR"
+.IP "open FILEHANDLE" 4
+.IX Item "open FILEHANDLE"
+.PD
+Associates an internal FILEHANDLE with the external file specified by
+EXPR. That filehandle will subsequently allow you to perform
+I/O operations on that file, such as reading from it or writing to it.
+.Sp
+Instead of a filename, you may specify an external command
+(plus an optional argument list) or a scalar reference, in order to open
+filehandles on commands or in-memory scalars, respectively.
+.Sp
+A thorough reference to \f(CW\*(C`open\*(C'\fR follows. For a gentler introduction to
+the basics of \f(CW\*(C`open\*(C'\fR, see also the perlopentut manual page.
+.RS 4
+.IP "Working with files" 4
+.IX Item "Working with files"
+Most often, \f(CW\*(C`open\*(C'\fR gets invoked with three arguments: the required
+FILEHANDLE (usually an empty scalar variable), followed by MODE (usually
+a literal describing the I/O mode the filehandle will use), and then the
+filename  that the new filehandle will refer to.
+.RS 4
+.IP "Simple examples" 4
+.IX Item "Simple examples"
+Reading from a file:
+.Sp
+.Vb 2
+\&    open(my $fh, "<", "input.txt")
+\&        or die "Can\*(Aqt open < input.txt: $!";
+\&
+\&    # Process every line in input.txt
+\&    while (my $line = readline($fh)) {
+\&        #
+\&        # ... do something interesting with $line here ...
+\&        #
+\&    }
+.Ve
+.Sp
+or writing to one:
+.Sp
+.Vb 2
+\&    open(my $fh, ">", "output.txt")
+\&        or die "Can\*(Aqt open > output.txt: $!";
+\&
+\&    print $fh "This line gets printed into output.txt.\en";
+.Ve
+.Sp
+For a summary of common filehandle operations such as these, see
+"Files and I/O" in perlintro.
+.IP "About filehandles" 4
+.IX Item "About filehandles"
+The first argument to \f(CW\*(C`open\*(C'\fR, labeled FILEHANDLE in this reference, is
+usually a scalar variable. (Exceptions exist, described in "Other
+considerations", below.) If the call to \f(CW\*(C`open\*(C'\fR succeeds, then the
+expression provided as FILEHANDLE will get assigned an open
+\&\fIfilehandle\fR. That filehandle provides an internal reference to the
+specified external file, conveniently stored in a Perl variable, and
+ready for I/O operations such as reading and writing.
+.IP "About modes" 4
+.IX Item "About modes"
+When calling \f(CW\*(C`open\*(C'\fR with three or more arguments, the second argument
+\&\-\- labeled MODE here \-\- defines the \fIopen mode\fR. MODE is usually a
+literal string comprising special characters that define the intended
+I/O role of the filehandle being created: whether it's read-only, or
+read-and-write, and so on.
+.Sp
+If MODE is \f(CW\*(C`<\*(C'\fR, the file is opened for input (read-only).
+If MODE is \f(CW\*(C`>\*(C'\fR, the file is opened for output, with existing files
+first being truncated ("clobbered") and nonexisting files newly created.
+If MODE is \f(CW\*(C`>>\*(C'\fR, the file is opened for appending, again being
+created if necessary.
+.Sp
+You can put a \f(CW\*(C`+\*(C'\fR in front of the \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR to
+indicate that you want both read and write access to the file; thus
+\&\f(CW\*(C`+<\*(C'\fR is almost always preferred for read/write updates\-\-the
+\&\f(CW\*(C`+>\*(C'\fR mode would clobber the file first.  You can't usually use
+either read-write mode for updating textfiles, since they have
+variable-length records.  See the \fB\-i\fR switch in
+perlrun for a better approach.  The file is
+created with permissions of \f(CW0666\fR modified by the process's
+\&\f(CW\*(C`umask\*(C'\fR value.
+.Sp
+These various prefixes correspond to the \fBfopen\fR\|(3) modes of \f(CW\*(C`r\*(C'\fR,
+\&\f(CW\*(C`r+\*(C'\fR, \f(CW\*(C`w\*(C'\fR, \f(CW\*(C`w+\*(C'\fR, \f(CW\*(C`a\*(C'\fR, and \f(CW\*(C`a+\*(C'\fR.
+.Sp
+More examples of different modes in action:
+.Sp
+.Vb 3
+\& # Open a file for concatenation
+\& open(my $log, ">>", "/usr/spool/news/twitlog")
+\&     or warn "Couldn\*(Aqt open log file; discarding input";
+\&
+\& # Open a file for reading and writing
+\& open(my $dbase, "+<", "dbase.mine")
+\&     or die "Can\*(Aqt open \*(Aqdbase.mine\*(Aq for update: $!";
+.Ve
+.IP "Checking the return value" 4
+.IX Item "Checking the return value"
+Open returns nonzero on success, the undefined value otherwise.  If the
+\&\f(CW\*(C`open\*(C'\fR involved a pipe, the return value happens to be the pid of the
+subprocess.
+.Sp
+When opening a file, it's seldom a good idea to continue if the request
+failed, so \f(CW\*(C`open\*(C'\fR is frequently used with \f(CW\*(C`die\*(C'\fR. Even if
+you want your code to do something other than \f(CW\*(C`die\*(C'\fR on a failed open,
+you should still always check the return value from opening a file.
+.RE
+.RS 4
+.RE
+.IP "Specifying I/O layers in MODE" 4
+.IX Item "Specifying I/O layers in MODE"
+You can use the three-argument form of open to specify
+I/O layers (sometimes referred to as "disciplines") to apply to the new
+filehandle. These affect how the input and output are processed (see
+open and
+PerlIO for more details).  For example:
+.Sp
+.Vb 3
+\&    # loads PerlIO::encoding automatically
+\&    open(my $fh, "<:encoding(UTF\-8)", $filename)
+\&        || die "Can\*(Aqt open UTF\-8 encoded $filename: $!";
+.Ve
+.Sp
+This opens the UTF8\-encoded file containing Unicode characters;
+see perluniintro.  Note that if layers are specified in the
+three-argument form, then default layers stored in
+\&\f(CW\*(C`${^OPEN}\*(C'\fR
+(usually set by the open pragma or the switch \f(CW\*(C`\-CioD\*(C'\fR) are ignored.
+Those layers will also be ignored if you specify a colon with no name
+following it.  In that case the default layer for the operating system
+(:raw on Unix, :crlf on Windows) is used.
+.Sp
+On some systems (in general, DOS\- and Windows-based systems)
+\&\f(CW\*(C`binmode\*(C'\fR is necessary when you're not
+working with a text file.  For the sake of portability it is a good idea
+always to use it when appropriate, and never to use it when it isn't
+appropriate.  Also, people can set their I/O to be by default
+UTF8\-encoded Unicode, not bytes.
+.ie n .IP "Using ""undef"" for temporary files" 4
+.el .IP "Using \f(CWundef\fR for temporary files" 4
+.IX Item "Using undef for temporary files"
+As a special case the three-argument form with a read/write mode and the third
+argument being \f(CW\*(C`undef\*(C'\fR:
+.Sp
+.Vb 1
+\&    open(my $tmp, "+>", undef) or die ...
+.Ve
+.Sp
+opens a filehandle to a newly created empty anonymous temporary file.
+(This happens under any mode, which makes \f(CW\*(C`+>\*(C'\fR the only useful and
+sensible mode to use.)  You will need to
+\&\f(CW\*(C`seek\*(C'\fR to do the reading.
+.IP "Opening a filehandle into an in-memory scalar" 4
+.IX Item "Opening a filehandle into an in-memory scalar"
+You can open filehandles directly to Perl scalars instead of a file or
+other resource external to the program. To do so, provide a reference to
+that scalar as the third argument to \f(CW\*(C`open\*(C'\fR, like so:
+.Sp
+.Vb 3
+\& open(my $memory, ">", \e$var)
+\&     or die "Can\*(Aqt open memory file: $!";
+\& print $memory "foo!\en";    # output will appear in $var
+.Ve
+.Sp
+To (re)open \f(CW\*(C`STDOUT\*(C'\fR or \f(CW\*(C`STDERR\*(C'\fR as an in-memory file, close it first:
+.Sp
+.Vb 3
+\&    close STDOUT;
+\&    open(STDOUT, ">", \e$variable)
+\&        or die "Can\*(Aqt open STDOUT: $!";
+.Ve
+.Sp
+The scalars for in-memory files are treated as octet strings: unless
+the file is being opened with truncation the scalar may not contain
+any code points over 0xFF.
+.Sp
+Opening in-memory files \fIcan\fR fail for a variety of reasons.  As with
+any other \f(CW\*(C`open\*(C'\fR, check the return value for success.
+.Sp
+\&\fITechnical note\fR: This feature works only when Perl is built with
+PerlIO \-\- the default, except with older (pre\-5.16) Perl installations
+that were configured to not include it (e.g. via \f(CW\*(C`Configure
+\&\-Uuseperlio\*(C'\fR). You can see whether your Perl was built with PerlIO by
+running \f(CW\*(C`perl \-V:useperlio\*(C'\fR.  If it says \f(CW\*(Aqdefine\*(Aq\fR, you have PerlIO;
+otherwise you don't.
+.Sp
+See perliol for detailed info on PerlIO.
+.IP "Opening a filehandle into a command" 4
+.IX Item "Opening a filehandle into a command"
+If MODE is \f(CW\*(C`|\-\*(C'\fR, then the filename is
+interpreted as a command to which output is to be piped, and if MODE
+is \f(CW\*(C`\-|\*(C'\fR, the filename is interpreted as a command that pipes
+output to us.  In the two-argument (and one-argument) form, one should
+replace dash (\f(CW\*(C`\-\*(C'\fR) with the command.
+See "Using \fBopen()\fR for IPC" in perlipc for more examples of this.
+(You are not allowed to \f(CW\*(C`open\*(C'\fR to a command
+that pipes both in \fIand\fR out, but see IPC::Open2, IPC::Open3, and
+"Bidirectional Communication with Another Process" in perlipc for
+alternatives.)
+.Sp
+.Vb 3
+\& open(my $article_fh, "\-|", "caesar <$article")  # decrypt
+\&                                                 # article
+\&     or die "Can\*(Aqt start caesar: $!";
+\&
+\& open(my $article_fh, "caesar <$article |")      # ditto
+\&     or die "Can\*(Aqt start caesar: $!";
+\&
+\& open(my $out_fh, "|\-", "sort >Tmp$$")    # $$ is our process id
+\&     or die "Can\*(Aqt start sort: $!";
+.Ve
+.Sp
+In the form of pipe opens taking three or more arguments, if LIST is specified
+(extra arguments after the command name) then LIST becomes arguments
+to the command invoked if the platform supports it.  The meaning of
+\&\f(CW\*(C`open\*(C'\fR with more than three arguments for
+non-pipe modes is not yet defined, but experimental "layers" may give
+extra LIST arguments meaning.
+.Sp
+If you open a pipe on the command \f(CW\*(C`\-\*(C'\fR (that is, specify either \f(CW\*(C`|\-\*(C'\fR or \f(CW\*(C`\-|\*(C'\fR
+with the one\- or two-argument forms of
+\&\f(CW\*(C`open\*(C'\fR), an implicit \f(CW\*(C`fork\*(C'\fR is done,
+so \f(CW\*(C`open\*(C'\fR returns twice: in the parent process
+it returns the pid
+of the child process, and in the child process it returns (a defined) \f(CW0\fR.
+Use \f(CWdefined($pid)\fR or \f(CW\*(C`//\*(C'\fR to determine whether the open was successful.
+.Sp
+For example, use either
+.Sp
+.Vb 2
+\&   my $child_pid = open(my $from_kid, "\-|")
+\&        // die "Can\*(Aqt fork: $!";
+.Ve
+.Sp
+or
+.Sp
+.Vb 2
+\&   my $child_pid = open(my $to_kid,   "|\-")
+\&        // die "Can\*(Aqt fork: $!";
+.Ve
+.Sp
+followed by
+.Sp
+.Vb 10
+\&    if ($child_pid) {
+\&        # am the parent:
+\&        # either write $to_kid or else read $from_kid
+\&        ...
+\&       waitpid $child_pid, 0;
+\&    } else {
+\&        # am the child; use STDIN/STDOUT normally
+\&        ...
+\&        exit;
+\&    }
+.Ve
+.Sp
+The filehandle behaves normally for the parent, but I/O to that
+filehandle is piped from/to the STDOUT/STDIN of the child process.
+In the child process, the filehandle isn't opened\-\-I/O happens from/to
+the new STDOUT/STDIN.  Typically this is used like the normal
+piped open when you want to exercise more control over just how the
+pipe command gets executed, such as when running setuid and
+you don't want to have to scan shell commands for metacharacters.
+.Sp
+The following blocks are more or less equivalent:
+.Sp
+.Vb 4
+\&    open(my $fh, "|tr \*(Aq[a\-z]\*(Aq \*(Aq[A\-Z]\*(Aq");
+\&    open(my $fh, "|\-", "tr \*(Aq[a\-z]\*(Aq \*(Aq[A\-Z]\*(Aq");
+\&    open(my $fh, "|\-") || exec \*(Aqtr\*(Aq, \*(Aq[a\-z]\*(Aq, \*(Aq[A\-Z]\*(Aq;
+\&    open(my $fh, "|\-", "tr", \*(Aq[a\-z]\*(Aq, \*(Aq[A\-Z]\*(Aq);
+\&
+\&    open(my $fh, "cat \-n \*(Aq$file\*(Aq|");
+\&    open(my $fh, "\-|", "cat \-n \*(Aq$file\*(Aq");
+\&    open(my $fh, "\-|") || exec "cat", "\-n", $file;
+\&    open(my $fh, "\-|", "cat", "\-n", $file);
+.Ve
+.Sp
+The last two examples in each block show the pipe as "list form", which
+is not yet supported on all platforms. (If your platform has a real
+\&\f(CW\*(C`fork\*(C'\fR, such as Linux and macOS, you can use the list form; it
+also works on Windows with Perl 5.22 or later.) You would want to use
+the list form of the pipe so you can pass literal arguments to the
+command without risk of the shell interpreting any shell metacharacters
+in them. However, this also bars you from opening pipes to commands that
+intentionally contain shell metacharacters, such as:
+.Sp
+.Vb 2
+\&    open(my $fh, "|cat \-n | expand \-4 | lpr")
+\&        || die "Can\*(Aqt open pipeline to lpr: $!";
+.Ve
+.Sp
+See "Safe Pipe Opens" in perlipc for more examples of this.
+.IP "Duping filehandles" 4
+.IX Item "Duping filehandles"
+You may also, in the Bourne shell tradition, specify an EXPR beginning
+with \f(CW\*(C`>&\*(C'\fR, in which case the rest of the string is interpreted
+as the name of a filehandle (or file descriptor, if numeric) to be
+duped (as in \fBdup\fR\|(2)) and opened.  You may use \f(CW\*(C`&\*(C'\fR after \f(CW\*(C`>\*(C'\fR,
+\&\f(CW\*(C`>>\*(C'\fR, \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`+>\*(C'\fR, \f(CW\*(C`+>>\*(C'\fR, and \f(CW\*(C`+<\*(C'\fR.
+The mode you specify should match the mode of the original filehandle.
+(Duping a filehandle does not take into account any existing contents
+of IO buffers.)  If you use the three-argument
+form, then you can pass either a
+number, the name of a filehandle, or the normal "reference to a glob".
+.Sp
+Here is a script that saves, redirects, and restores \f(CW\*(C`STDOUT\*(C'\fR and
+\&\f(CW\*(C`STDERR\*(C'\fR using various methods:
+.Sp
+.Vb 5
+\&    #!/usr/bin/perl
+\&    open(my $oldout, ">&STDOUT")
+\&        or die "Can\*(Aqt dup STDOUT: $!";
+\&    open(OLDERR,     ">&", \e*STDERR)
+\&        or die "Can\*(Aqt dup STDERR: $!";
+\&
+\&    open(STDOUT, \*(Aq>\*(Aq, "foo.out")
+\&        or die "Can\*(Aqt redirect STDOUT: $!";
+\&    open(STDERR, ">&STDOUT")
+\&        or die "Can\*(Aqt dup STDOUT: $!";
+\&
+\&    select STDERR; $| = 1;  # make unbuffered
+\&    select STDOUT; $| = 1;  # make unbuffered
+\&
+\&    print STDOUT "stdout 1\en";  # this works for
+\&    print STDERR "stderr 1\en";  # subprocesses too
+\&
+\&    open(STDOUT, ">&", $oldout)
+\&        or die "Can\*(Aqt dup \e$oldout: $!";
+\&    open(STDERR, ">&OLDERR")
+\&        or die "Can\*(Aqt dup OLDERR: $!";
+\&
+\&    print STDOUT "stdout 2\en";
+\&    print STDERR "stderr 2\en";
+.Ve
+.Sp
+If you specify \f(CW\*(Aq<&=X\*(Aq\fR, where \f(CW\*(C`X\*(C'\fR is a file descriptor number
+or a filehandle, then Perl will do an equivalent of C's \fBfdopen\fR\|(3) of
+that file descriptor (and not call \fBdup\fR\|(2)); this is more
+parsimonious of file descriptors.  For example:
+.Sp
+.Vb 2
+\&    # open for input, reusing the fileno of $fd
+\&    open(my $fh, "<&=", $fd)
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&    open(my $fh, "<&=$fd")
+.Ve
+.Sp
+or
+.Sp
+.Vb 2
+\&    # open for append, using the fileno of $oldfh
+\&    open(my $fh, ">>&=", $oldfh)
+.Ve
+.Sp
+Being parsimonious on filehandles is also useful (besides being
+parsimonious) for example when something is dependent on file
+descriptors, like for example locking using
+\&\f(CW\*(C`flock\*(C'\fR.  If you do just
+\&\f(CW\*(C`open(my $A, ">>&", $B)\*(C'\fR, the filehandle \f(CW$A\fR will not have the
+same file descriptor as \f(CW$B\fR, and therefore \f(CWflock($A)\fR will not
+\&\f(CWflock($B)\fR nor vice versa.  But with \f(CW\*(C`open(my $A, ">>&=", $B)\*(C'\fR,
+the filehandles will share the same underlying system file descriptor.
+.Sp
+Note that under Perls older than 5.8.0, Perl uses the standard C library's'
+\&\fBfdopen\fR\|(3) to implement the \f(CW\*(C`=\*(C'\fR functionality.  On many Unix systems,
+\&\fBfdopen\fR\|(3) fails when file descriptors exceed a certain value, typically 255.
+For Perls 5.8.0 and later, PerlIO is (most often) the default.
+.IP "Legacy usage" 4
+.IX Item "Legacy usage"
+This section describes ways to call \f(CW\*(C`open\*(C'\fR outside of best practices;
+you may encounter these uses in older code. Perl does not consider their
+use deprecated, exactly, but neither is it recommended in new code, for
+the sake of clarity and readability.
+.RS 4
+.IP "Specifying mode and filename as a single argument" 4
+.IX Item "Specifying mode and filename as a single argument"
+In the one\- and two-argument forms of the call, the mode and filename
+should be concatenated (in that order), preferably separated by white
+space.  You can\-\-but shouldn't\-\-omit the mode in these forms when that mode
+is \f(CW\*(C`<\*(C'\fR.  It is safe to use the two-argument form of
+\&\f(CW\*(C`open\*(C'\fR if the filename argument is a known literal.
+.Sp
+.Vb 2
+\& open(my $dbase, "+<dbase.mine")          # ditto
+\&     or die "Can\*(Aqt open \*(Aqdbase.mine\*(Aq for update: $!";
+.Ve
+.Sp
+In the two-argument (and one-argument) form, opening \f(CW\*(C`<\-\*(C'\fR
+or \f(CW\*(C`\-\*(C'\fR opens STDIN and opening \f(CW\*(C`>\-\*(C'\fR opens STDOUT.
+.Sp
+New code should favor the three-argument form of \f(CW\*(C`open\*(C'\fR over this older
+form. Declaring the mode and the filename as two distinct arguments
+avoids any confusion between the two.
+.ie n .IP "Calling ""open"" with one argument via global variables" 4
+.el .IP "Calling \f(CWopen\fR with one argument via global variables" 4
+.IX Item "Calling open with one argument via global variables"
+As a shortcut, a one-argument call takes the filename from the global
+scalar variable of the same name as the filehandle:
+.Sp
+.Vb 3
+\&    $ARTICLE = 100;
+\&    open(ARTICLE)
+\&        or die "Can\*(Aqt find article $ARTICLE: $!\en";
+.Ve
+.Sp
+Here \f(CW$ARTICLE\fR must be a global (package) scalar variable \- not one
+declared with \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`state\*(C'\fR.
+.IP "Assigning a filehandle to a bareword" 4
+.IX Item "Assigning a filehandle to a bareword"
+An older style is to use a bareword as the filehandle, as
+.Sp
+.Vb 2
+\&    open(FH, "<", "input.txt")
+\&       or die "Can\*(Aqt open < input.txt: $!";
+.Ve
+.Sp
+Then you can use \f(CW\*(C`FH\*(C'\fR as the filehandle, in \f(CW\*(C`close FH\*(C'\fR and \f(CW\*(C`<FH>\*(C'\fR and so on.  Note that it's a global variable, so this form is
+not recommended when dealing with filehandles other than Perl's built-in ones
+(e.g. STDOUT and STDIN).  In fact, using a bareword for the filehandle is
+an error when the \f(CW\*(C`bareword_filehandles\*(C'\fR feature has been disabled.  This
+feature is disabled by default when in the scope of \f(CW\*(C`use v5.36.0\*(C'\fR or later.
+.RE
+.RS 4
+.RE
+.IP "Other considerations" 4
+.IX Item "Other considerations"
+.RS 4
+.PD 0
+.IP "Automatic filehandle closure" 4
+.IX Item "Automatic filehandle closure"
+.PD
+The filehandle will be closed when its reference count reaches zero. If
+it is a lexically scoped variable declared with \f(CW\*(C`my\*(C'\fR,
+that usually means the end of the enclosing scope.  However, this
+automatic close does not check for errors, so it is better to explicitly
+close filehandles, especially those used for writing:
+.Sp
+.Vb 2
+\&    close($handle)
+\&       || warn "close failed: $!";
+.Ve
+.IP "Automatic pipe flushing" 4
+.IX Item "Automatic pipe flushing"
+Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see perlport).  To be safe, you may need
+to set \f(CW$|\fR (\f(CW$AUTOFLUSH\fR in English)
+or call the \f(CW\*(C`autoflush\*(C'\fR method of \f(CW\*(C`IO::Handle\*(C'\fR
+on any open handles.
+.Sp
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptor as determined by the value
+of \f(CW$^F\fR.  See "$^F" in perlvar.
+.Sp
+Closing any piped filehandle causes the parent process to wait for the
+child to finish, then returns the status value in \f(CW$?\fR and
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR.
+.IP "Direct versus by-reference assignment of filehandles" 4
+.IX Item "Direct versus by-reference assignment of filehandles"
+If FILEHANDLE \-\- the first argument in a call to \f(CW\*(C`open\*(C'\fR \-\- is an
+undefined scalar variable (or array or hash element), a new filehandle
+is autovivified, meaning that the variable is assigned a reference to a
+newly allocated anonymous filehandle.  Otherwise if FILEHANDLE is an
+expression, its value is the real filehandle.  (This is considered a
+symbolic reference, so \f(CW\*(C`use strict "refs"\*(C'\fR should \fInot\fR be in effect.)
+.IP "Whitespace and special characters in the filename argument" 4
+.IX Item "Whitespace and special characters in the filename argument"
+The filename passed to the one\- and two-argument forms of
+\&\f(CW\*(C`open\*(C'\fR will
+have leading and trailing whitespace deleted and normal
+redirection characters honored.  This property, known as "magic open",
+can often be used to good effect.  A user could specify a filename of
+\&\fI"rsh cat file |"\fR, or you could change certain filenames as needed:
+.Sp
+.Vb 3
+\&    $filename =~ s/(.*\e.gz)\es*$/gzip \-dc < $1|/;
+\&    open(my $fh, $filename)
+\&        or die "Can\*(Aqt open $filename: $!";
+.Ve
+.Sp
+Use the three-argument form to open a file with arbitrary weird characters in it,
+.Sp
+.Vb 2
+\&    open(my $fh, "<", $file)
+\&        || die "Can\*(Aqt open $file: $!";
+.Ve
+.Sp
+otherwise it's necessary to protect any leading and trailing whitespace:
+.Sp
+.Vb 3
+\&    $file =~ s#^(\es)#./$1#;
+\&    open(my $fh, "< $file\e0")
+\&        || die "Can\*(Aqt open $file: $!";
+.Ve
+.Sp
+(this may not work on some bizarre filesystems).  One should
+conscientiously choose between the \fImagic\fR and \fIthree-argument\fR form
+of \f(CW\*(C`open\*(C'\fR:
+.Sp
+.Vb 1
+\&    open(my $in, $ARGV[0]) || die "Can\*(Aqt open $ARGV[0]: $!";
+.Ve
+.Sp
+will allow the user to specify an argument of the form \f(CW"rsh cat file |"\fR,
+but will not work on a filename that happens to have a trailing space, while
+.Sp
+.Vb 2
+\&    open(my $in, "<", $ARGV[0])
+\&        || die "Can\*(Aqt open $ARGV[0]: $!";
+.Ve
+.Sp
+will have exactly the opposite restrictions. (However, some shells
+support the syntax \f(CW\*(C`perl your_program.pl <( rsh cat file )\*(C'\fR, which
+produces a filename that can be opened normally.)
+.ie n .IP "Invoking C\-style ""open""" 4
+.el .IP "Invoking C\-style \f(CWopen\fR" 4
+.IX Item "Invoking C-style open"
+If you want a "real" C \fBopen\fR\|(2), then you should use the
+\&\f(CW\*(C`sysopen\*(C'\fR function, which involves
+no such magic (but uses different filemodes than Perl
+\&\f(CW\*(C`open\*(C'\fR, which corresponds to C \fBfopen\fR\|(3)).
+This is another way to protect your filenames from interpretation.  For
+example:
+.Sp
+.Vb 7
+\&    use IO::Handle;
+\&    sysopen(my $fh, $path, O_RDWR|O_CREAT|O_EXCL)
+\&        or die "Can\*(Aqt open $path: $!";
+\&    $fh\->autoflush(1);
+\&    print $fh "stuff $$\en";
+\&    seek($fh, 0, 0);
+\&    print "File contains: ", readline($fh);
+.Ve
+.Sp
+See \f(CW\*(C`seek\*(C'\fR for some details about
+mixing reading and writing.
+.IP "Portability issues" 4
+.IX Item "Portability issues"
+See "open" in perlport.
+.RE
+.RS 4
+.RE
+.RE
+.RS 4
+.RE
+.IP "opendir DIRHANDLE,EXPR" 4
+.IX Xref "opendir"
+.IX Item "opendir DIRHANDLE,EXPR"
+Opens a directory named EXPR for processing by
+\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`telldir\*(C'\fR,
+\&\f(CW\*(C`seekdir\*(C'\fR,
+\&\f(CW\*(C`rewinddir\*(C'\fR, and
+\&\f(CW\*(C`closedir\*(C'\fR.  Returns true if successful.
+DIRHANDLE may be an expression whose value can be used as an indirect
+dirhandle, usually the real dirhandle name.  If DIRHANDLE is an undefined
+scalar variable (or array or hash element), the variable is assigned a
+reference to a new anonymous dirhandle; that is, it's autovivified.
+Dirhandles are the same objects as filehandles; an I/O object can only
+be open as one of these handle types at once.
+.Sp
+See the example at \f(CW\*(C`readdir\*(C'\fR.
+.IP "ord EXPR" 4
+.IX Xref "ord encoding"
+.IX Item "ord EXPR"
+.PD 0
+.IP ord 4
+.IX Item "ord"
+.PD
+Returns the numeric value of the first character of EXPR.
+If EXPR is an empty string, returns 0.  If EXPR is omitted, uses
+\&\f(CW$_\fR.
+(Note \fIcharacter\fR, not byte.)
+.Sp
+For the reverse, see \f(CW\*(C`chr\*(C'\fR.
+See perlunicode for more about Unicode.
+.IP "our VARLIST" 4
+.IX Xref "our global"
+.IX Item "our VARLIST"
+.PD 0
+.IP "our TYPE VARLIST" 4
+.IX Item "our TYPE VARLIST"
+.IP "our VARLIST : ATTRS" 4
+.IX Item "our VARLIST : ATTRS"
+.IP "our TYPE VARLIST : ATTRS" 4
+.IX Item "our TYPE VARLIST : ATTRS"
+.PD
+\&\f(CW\*(C`our\*(C'\fR makes a lexical alias to a package (i.e. global)
+variable of the same name in the current package for use within the
+current lexical scope.
+.Sp
+\&\f(CW\*(C`our\*(C'\fR has the same scoping rules as
+\&\f(CW\*(C`my\*(C'\fR or \f(CW\*(C`state\*(C'\fR, meaning that it is
+only valid within a lexical scope.  Unlike \f(CW\*(C`my\*(C'\fR and
+\&\f(CW\*(C`state\*(C'\fR, which both declare new (lexical) variables,
+\&\f(CW\*(C`our\*(C'\fR only creates an alias to an existing variable: a
+package variable of the same name.
+.Sp
+This means that when \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR is in effect, \f(CW\*(C`our\*(C'\fR lets you use a package variable without qualifying it with the
+package name, but only within the lexical scope of the
+\&\f(CW\*(C`our\*(C'\fR declaration.  This applies immediately\-\-even
+within the same statement.
+.Sp
+.Vb 2
+\&    package Foo;
+\&    use v5.36;  # which implies "use strict;"
+\&
+\&    $Foo::foo = 23;
+\&
+\&    {
+\&        our $foo;   # alias to $Foo::foo
+\&        print $foo; # prints 23
+\&    }
+\&
+\&    print $Foo::foo; # prints 23
+\&
+\&    print $foo; # ERROR: requires explicit package name
+.Ve
+.Sp
+This works even if the package variable has not been used before, as
+package variables spring into existence when first used.
+.Sp
+.Vb 2
+\&    package Foo;
+\&    use v5.36;
+\&
+\&    our $foo = 23;   # just like $Foo::foo = 23
+\&
+\&    print $Foo::foo; # prints 23
+.Ve
+.Sp
+Because the variable becomes legal immediately under \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR, so
+long as there is no variable with that name is already in scope, you can then
+reference the package variable again even within the same statement.
+.Sp
+.Vb 2
+\&    package Foo;
+\&    use v5.36;
+\&
+\&    my  $foo = $foo; # error, undeclared $foo on right\-hand side
+\&    our $foo = $foo; # no errors
+.Ve
+.Sp
+If more than one variable is listed, the list must be placed
+in parentheses.
+.Sp
+.Vb 1
+\&    our($bar, $baz);
+.Ve
+.Sp
+An \f(CW\*(C`our\*(C'\fR declaration declares an alias for a package
+variable that will be visible
+across its entire lexical scope, even across package boundaries.  The
+package in which the variable is entered is determined at the point
+of the declaration, not at the point of use.  This means the following
+behavior holds:
+.Sp
+.Vb 3
+\&    package Foo;
+\&    our $bar;      # declares $Foo::bar for rest of lexical scope
+\&    $bar = 20;
+\&
+\&    package Bar;
+\&    print $bar;    # prints 20, as it refers to $Foo::bar
+.Ve
+.Sp
+Multiple \f(CW\*(C`our\*(C'\fR declarations with the same name in the
+same lexical
+scope are allowed if they are in different packages.  If they happen
+to be in the same package, Perl will emit warnings if you have asked
+for them, just like multiple \f(CW\*(C`my\*(C'\fR declarations.  Unlike
+a second \f(CW\*(C`my\*(C'\fR declaration, which will bind the name to a
+fresh variable, a second \f(CW\*(C`our\*(C'\fR declaration in the same
+package, in the same scope, is merely redundant.
+.Sp
+.Vb 4
+\&    use warnings;
+\&    package Foo;
+\&    our $bar;      # declares $Foo::bar for rest of lexical scope
+\&    $bar = 20;
+\&
+\&    package Bar;
+\&    our $bar = 30; # declares $Bar::bar for rest of lexical scope
+\&    print $bar;    # prints 30
+\&
+\&    our $bar;      # emits warning but has no other effect
+\&    print $bar;    # still prints 30
+.Ve
+.Sp
+An \f(CW\*(C`our\*(C'\fR declaration may also have a list of attributes
+associated with it.
+.Sp
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of the fields pragma,
+and attributes are handled using the attributes pragma, or, starting
+from Perl 5.8.0, also via the Attribute::Handlers module.  See
+"Private Variables via \fBmy()\fR" in perlsub for details.
+.Sp
+Note that with a parenthesised list, \f(CW\*(C`undef\*(C'\fR can be used
+as a dummy placeholder, for example to skip assignment of initial
+values:
+.Sp
+.Vb 1
+\&    our ( undef, $min, $hour ) = localtime;
+.Ve
+.Sp
+\&\f(CW\*(C`our\*(C'\fR differs from \f(CW\*(C`use vars\*(C'\fR, which allows
+use of an unqualified name \fIonly\fR within the affected package, but
+across scopes.
+.IP "pack TEMPLATE,LIST" 4
+.IX Xref "pack"
+.IX Item "pack TEMPLATE,LIST"
+Takes a LIST of values and converts it into a string using the rules
+given by the TEMPLATE.  The resulting string is the concatenation of
+the converted values.  Typically, each converted value looks
+like its machine-level representation.  For example, on 32\-bit machines
+an integer may be represented by a sequence of 4 bytes, which  will in
+Perl be presented as a string that's 4 characters long.
+.Sp
+See perlpacktut for an introduction to this function.
+.Sp
+The TEMPLATE is a sequence of characters that give the order and type
+of values, as follows:
+.Sp
+.Vb 3
+\&    a  A string with arbitrary binary data, will be null padded.
+\&    A  A text (ASCII) string, will be space padded.
+\&    Z  A null\-terminated (ASCIZ) string, will be null padded.
+\&
+\&    b  A bit string (ascending bit order inside each byte,
+\&       like vec()).
+\&    B  A bit string (descending bit order inside each byte).
+\&    h  A hex string (low nybble first).
+\&    H  A hex string (high nybble first).
+\&
+\&    c  A signed char (8\-bit) value.
+\&    C  An unsigned char (octet) value.
+\&    W  An unsigned char value (can be greater than 255).
+\&
+\&    s  A signed short (16\-bit) value.
+\&    S  An unsigned short value.
+\&
+\&    l  A signed long (32\-bit) value.
+\&    L  An unsigned long value.
+\&
+\&    q  A signed quad (64\-bit) value.
+\&    Q  An unsigned quad value.
+\&         (Quads are available only if your system supports 64\-bit
+\&          integer values _and_ if Perl has been compiled to support
+\&          those.  Raises an exception otherwise.)
+\&
+\&    i  A signed integer value.
+\&    I  An unsigned integer value.
+\&         (This \*(Aqinteger\*(Aq is _at_least_ 32 bits wide.  Its exact
+\&          size depends on what a local C compiler calls \*(Aqint\*(Aq.)
+\&
+\&    n  An unsigned short (16\-bit) in "network" (big\-endian) order.
+\&    N  An unsigned long (32\-bit) in "network" (big\-endian) order.
+\&    v  An unsigned short (16\-bit) in "VAX" (little\-endian) order.
+\&    V  An unsigned long (32\-bit) in "VAX" (little\-endian) order.
+\&
+\&    j  A Perl internal signed integer value (IV).
+\&    J  A Perl internal unsigned integer value (UV).
+\&
+\&    f  A single\-precision float in native format.
+\&    d  A double\-precision float in native format.
+\&
+\&    F  A Perl internal floating\-point value (NV) in native format
+\&    D  A float of long\-double precision in native format.
+\&         (Long doubles are available only if your system supports
+\&          long double values. Raises an exception otherwise.
+\&          Note that there are different long double formats.)
+\&
+\&    p  A pointer to a null\-terminated string.
+\&    P  A pointer to a structure (fixed\-length string).
+\&
+\&    u  A uuencoded string.
+\&    U  A Unicode character number.  Encodes to a character in char\-
+\&       acter mode and UTF\-8 (or UTF\-EBCDIC in EBCDIC platforms) in
+\&       byte mode.  Also on EBCDIC platforms, the character number will
+\&       be the native EBCDIC value for character numbers below 256.
+\&       This allows most programs using this feature to not have to
+\&       care which type of platform they are running on.
+\&
+\&    w  A BER compressed integer (not an ASN.1 BER, see perlpacktut
+\&       for details).  Its bytes represent an unsigned integer in
+\&       base 128, most significant digit first, with as few digits
+\&       as possible.  Bit eight (the high bit) is set on each byte
+\&       except the last.
+\&
+\&    x  A null byte (a.k.a ASCII NUL, "\e000", chr(0))
+\&    X  Back up a byte.
+\&    @  Null\-fill or truncate to absolute position, counted from the
+\&       start of the innermost ()\-group.
+\&    .  Null\-fill or truncate to absolute position specified by
+\&       the value.
+\&    (  Start of a ()\-group.
+.Ve
+.Sp
+One or more modifiers below may optionally follow certain letters in the
+TEMPLATE (the second column lists letters for which the modifier is valid):
+.Sp
+.Vb 2
+\&    !   sSlLiI     Forces native (short, long, int) sizes instead
+\&                   of fixed (16\-/32\-bit) sizes.
+\&
+\&    !   xX         Make x and X act as alignment commands.
+\&
+\&    !   nNvV       Treat integers as signed instead of unsigned.
+\&
+\&    !   @.         Specify position as byte offset in the internal
+\&                   representation of the packed string.  Efficient
+\&                   but dangerous.
+\&
+\&    >   sSiIlLqQ   Force big\-endian byte\-order on the type.
+\&        jJfFdDpP   (The "big end" touches the construct.)
+\&
+\&    <   sSiIlLqQ   Force little\-endian byte\-order on the type.
+\&        jJfFdDpP   (The "little end" touches the construct.)
+.Ve
+.Sp
+The \f(CW\*(C`>\*(C'\fR and \f(CW\*(C`<\*(C'\fR modifiers can also be used on \f(CW\*(C`()\*(C'\fR groups
+to force a particular byte-order on all components in that group,
+including all its subgroups.
+.Sp
+The following rules apply:
+.RS 4
+.IP \(bu 4
+Each letter may optionally be followed by a number indicating the repeat
+count.  A numeric repeat count may optionally be enclosed in brackets, as
+in \f(CW\*(C`pack("C[80]", @arr)\*(C'\fR.  The repeat count gobbles that many values from
+the LIST when used with all format types other than \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`A\*(C'\fR, \f(CW\*(C`Z\*(C'\fR, \f(CW\*(C`b\*(C'\fR,
+\&\f(CW\*(C`B\*(C'\fR, \f(CW\*(C`h\*(C'\fR, \f(CW\*(C`H\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`X\*(C'\fR, and \f(CW\*(C`P\*(C'\fR, where it means
+something else, described below.  Supplying a \f(CW\*(C`*\*(C'\fR for the repeat count
+instead of a number means to use however many items are left, except for:
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`@\*(C'\fR, \f(CW\*(C`x\*(C'\fR, and \f(CW\*(C`X\*(C'\fR, where it is equivalent to \f(CW0\fR.
+.IP \(bu 4
+<.>, where it means relative to the start of the string.
+.IP \(bu 4
+\&\f(CW\*(C`u\*(C'\fR, where it is equivalent to 1 (or 45, which here is equivalent).
+.RE
+.RS 4
+.Sp
+One can replace a numeric repeat count with a template letter enclosed in
+brackets to use the packed byte length of the bracketed template for the
+repeat count.
+.Sp
+For example, the template \f(CW\*(C`x[L]\*(C'\fR skips as many bytes as in a packed long,
+and the template \f(CW"$t X[$t] $t"\fR unpacks twice whatever \f(CW$t\fR (when
+variable-expanded) unpacks.  If the template in brackets contains alignment
+commands (such as \f(CW\*(C`x![d]\*(C'\fR), its packed length is calculated as if the
+start of the template had the maximal possible alignment.
+.Sp
+When used with \f(CW\*(C`Z\*(C'\fR, a \f(CW\*(C`*\*(C'\fR as the repeat count is guaranteed to add a
+trailing null byte, so the resulting string is always one byte longer than
+the byte length of the item itself.
+.Sp
+When used with \f(CW\*(C`@\*(C'\fR, the repeat count represents an offset from the start
+of the innermost \f(CW\*(C`()\*(C'\fR group.
+.Sp
+When used with \f(CW\*(C`.\*(C'\fR, the repeat count determines the starting position to
+calculate the value offset as follows:
+.IP \(bu 4
+If the repeat count is \f(CW0\fR, it's relative to the current position.
+.IP \(bu 4
+If the repeat count is \f(CW\*(C`*\*(C'\fR, the offset is relative to the start of the
+packed string.
+.IP \(bu 4
+And if it's an integer \fIn\fR, the offset is relative to the start of the
+\&\fIn\fRth innermost \f(CW\*(C`( )\*(C'\fR group, or to the start of the string if \fIn\fR is
+bigger then the group level.
+.RE
+.RS 4
+.Sp
+The repeat count for \f(CW\*(C`u\*(C'\fR is interpreted as the maximal number of bytes
+to encode per line of output, with 0, 1 and 2 replaced by 45.  The repeat
+count should not be more than 65.
+.RE
+.IP \(bu 4
+The \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`A\*(C'\fR, and \f(CW\*(C`Z\*(C'\fR types gobble just one value, but pack it as a
+string of length count, padding with nulls or spaces as needed.  When
+unpacking, \f(CW\*(C`A\*(C'\fR strips trailing whitespace and nulls, \f(CW\*(C`Z\*(C'\fR strips everything
+after the first null, and \f(CW\*(C`a\*(C'\fR returns data with no stripping at all.
+.Sp
+If the value to pack is too long, the result is truncated.  If it's too
+long and an explicit count is provided, \f(CW\*(C`Z\*(C'\fR packs only \f(CW\*(C`$count\-1\*(C'\fR bytes,
+followed by a null byte.  Thus \f(CW\*(C`Z\*(C'\fR always packs a trailing null, except
+when the count is 0.
+.IP \(bu 4
+Likewise, the \f(CW\*(C`b\*(C'\fR and \f(CW\*(C`B\*(C'\fR formats pack a string that's that many bits long.
+Each such format generates 1 bit of the result.  These are typically followed
+by a repeat count like \f(CW\*(C`B8\*(C'\fR or \f(CW\*(C`B64\*(C'\fR.
+.Sp
+Each result bit is based on the least-significant bit of the corresponding
+input character, i.e., on \f(CW\*(C`ord($char)%2\*(C'\fR.  In particular, characters \f(CW"0"\fR
+and \f(CW"1"\fR generate bits 0 and 1, as do characters \f(CW"\e000"\fR and \f(CW"\e001"\fR.
+.Sp
+Starting from the beginning of the input string, each 8\-tuple
+of characters is converted to 1 character of output.  With format \f(CW\*(C`b\*(C'\fR,
+the first character of the 8\-tuple determines the least-significant bit of a
+character; with format \f(CW\*(C`B\*(C'\fR, it determines the most-significant bit of
+a character.
+.Sp
+If the length of the input string is not evenly divisible by 8, the
+remainder is packed as if the input string were padded by null characters
+at the end.  Similarly during unpacking, "extra" bits are ignored.
+.Sp
+If the input string is longer than needed, remaining characters are ignored.
+.Sp
+A \f(CW\*(C`*\*(C'\fR for the repeat count uses all characters of the input field.
+On unpacking, bits are converted to a string of \f(CW0\fRs and \f(CW1\fRs.
+.IP \(bu 4
+The \f(CW\*(C`h\*(C'\fR and \f(CW\*(C`H\*(C'\fR formats pack a string that many nybbles (4\-bit groups,
+representable as hexadecimal digits, \f(CW"0".."9"\fR \f(CW"a".."f"\fR) long.
+.Sp
+For each such format, \f(CW\*(C`pack\*(C'\fR generates 4 bits of result.
+With non-alphabetical characters, the result is based on the 4 least-significant
+bits of the input character, i.e., on \f(CW\*(C`ord($char)%16\*(C'\fR.  In particular,
+characters \f(CW"0"\fR and \f(CW"1"\fR generate nybbles 0 and 1, as do bytes
+\&\f(CW"\e000"\fR and \f(CW"\e001"\fR.  For characters \f(CW"a".."f"\fR and \f(CW"A".."F"\fR, the result
+is compatible with the usual hexadecimal digits, so that \f(CW"a"\fR and
+\&\f(CW"A"\fR both generate the nybble \f(CW\*(C`0xA==10\*(C'\fR.  Use only these specific hex
+characters with this format.
+.Sp
+Starting from the beginning of the template to
+\&\f(CW\*(C`pack\*(C'\fR, each pair
+of characters is converted to 1 character of output.  With format \f(CW\*(C`h\*(C'\fR, the
+first character of the pair determines the least-significant nybble of the
+output character; with format \f(CW\*(C`H\*(C'\fR, it determines the most-significant
+nybble.
+.Sp
+If the length of the input string is not even, it behaves as if padded by
+a null character at the end.  Similarly, "extra" nybbles are ignored during
+unpacking.
+.Sp
+If the input string is longer than needed, extra characters are ignored.
+.Sp
+A \f(CW\*(C`*\*(C'\fR for the repeat count uses all characters of the input field.  For
+\&\f(CW\*(C`unpack\*(C'\fR, nybbles are converted to a string of
+hexadecimal digits.
+.IP \(bu 4
+The \f(CW\*(C`p\*(C'\fR format packs a pointer to a null-terminated string.  You are
+responsible for ensuring that the string is not a temporary value, as that
+could potentially get deallocated before you got around to using the packed
+result.  The \f(CW\*(C`P\*(C'\fR format packs a pointer to a structure of the size indicated
+by the length.  A null pointer is created if the corresponding value for
+\&\f(CW\*(C`p\*(C'\fR or \f(CW\*(C`P\*(C'\fR is \f(CW\*(C`undef\*(C'\fR; similarly with
+\&\f(CW\*(C`unpack\*(C'\fR, where a null pointer unpacks into
+\&\f(CW\*(C`undef\*(C'\fR.
+.Sp
+If your system has a strange pointer size\-\-meaning a pointer is neither as
+big as an int nor as big as a long\-\-it may not be possible to pack or
+unpack pointers in big\- or little-endian byte order.  Attempting to do
+so raises an exception.
+.IP \(bu 4
+The \f(CW\*(C`/\*(C'\fR template character allows packing and unpacking of a sequence of
+items where the packed structure contains a packed item count followed by
+the packed items themselves.  This is useful when the structure you're
+unpacking has encoded the sizes or repeat counts for some of its fields
+within the structure itself as separate fields.
+.Sp
+For \f(CW\*(C`pack\*(C'\fR, you write
+\&\fIlength-item\fR\f(CW\*(C`/\*(C'\fR\fIsequence-item\fR, and the
+\&\fIlength-item\fR describes how the length value is packed.  Formats likely
+to be of most use are integer-packing ones like \f(CW\*(C`n\*(C'\fR for Java strings,
+\&\f(CW\*(C`w\*(C'\fR for ASN.1 or SNMP, and \f(CW\*(C`N\*(C'\fR for Sun XDR.
+.Sp
+For \f(CW\*(C`pack\*(C'\fR, \fIsequence-item\fR may have a repeat
+count, in which case
+the minimum of that and the number of available items is used as the argument
+for \fIlength-item\fR.  If it has no repeat count or uses a '*', the number
+of available items is used.
+.Sp
+For \f(CW\*(C`unpack\*(C'\fR, an internal stack of integer
+arguments unpacked so far is
+used.  You write \f(CW\*(C`/\*(C'\fR\fIsequence-item\fR and the repeat count is obtained by
+popping off the last element from the stack.  The \fIsequence-item\fR must not
+have a repeat count.
+.Sp
+If \fIsequence-item\fR refers to a string type (\f(CW"A"\fR, \f(CW"a"\fR, or \f(CW"Z"\fR),
+the \fIlength-item\fR is the string length, not the number of strings.  With
+an explicit repeat count for pack, the packed string is adjusted to that
+length.  For example:
+.Sp
+.Vb 1
+\& This code:                             gives this result:
+\&
+\& unpack("W/a", "\e004Gurusamy")          ("Guru")
+\& unpack("a3/A A*", "007 Bond  J ")      (" Bond", "J")
+\& unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
+\&
+\& pack("n/a* w/a","hello,","world")     "\e000\e006hello,\e005world"
+\& pack("a/W2", ord("a") .. ord("z"))    "2ab"
+.Ve
+.Sp
+The \fIlength-item\fR is not returned explicitly from
+\&\f(CW\*(C`unpack\*(C'\fR.
+.Sp
+Supplying a count to the \fIlength-item\fR format letter is only useful with
+\&\f(CW\*(C`A\*(C'\fR, \f(CW\*(C`a\*(C'\fR, or \f(CW\*(C`Z\*(C'\fR.  Packing with a \fIlength-item\fR of \f(CW\*(C`a\*(C'\fR or \f(CW\*(C`Z\*(C'\fR may
+introduce \f(CW"\e000"\fR characters, which Perl does not regard as legal in
+numeric strings.
+.IP \(bu 4
+The integer types \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`S\*(C'\fR, \f(CW\*(C`l\*(C'\fR, and \f(CW\*(C`L\*(C'\fR may be
+followed by a \f(CW\*(C`!\*(C'\fR modifier to specify native shorts or
+longs.  As shown in the example above, a bare \f(CW\*(C`l\*(C'\fR means
+exactly 32 bits, although the native \f(CW\*(C`long\*(C'\fR as seen by the local C compiler
+may be larger.  This is mainly an issue on 64\-bit platforms.  You can
+see whether using \f(CW\*(C`!\*(C'\fR makes any difference this way:
+.Sp
+.Vb 2
+\&    printf "format s is %d, s! is %d\en",
+\&        length pack("s"), length pack("s!");
+\&
+\&    printf "format l is %d, l! is %d\en",
+\&        length pack("l"), length pack("l!");
+.Ve
+.Sp
+\&\f(CW\*(C`i!\*(C'\fR and \f(CW\*(C`I!\*(C'\fR are also allowed, but only for completeness' sake:
+they are identical to \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`I\*(C'\fR.
+.Sp
+The actual sizes (in bytes) of native shorts, ints, longs, and long
+longs on the platform where Perl was built are also available from
+the command line:
+.Sp
+.Vb 5
+\&    $ perl \-V:{short,int,long{,long}}size
+\&    shortsize=\*(Aq2\*(Aq;
+\&    intsize=\*(Aq4\*(Aq;
+\&    longsize=\*(Aq4\*(Aq;
+\&    longlongsize=\*(Aq8\*(Aq;
+.Ve
+.Sp
+or programmatically via the \f(CW\*(C`Config\*(C'\fR module:
+.Sp
+.Vb 5
+\&       use Config;
+\&       print $Config{shortsize},    "\en";
+\&       print $Config{intsize},      "\en";
+\&       print $Config{longsize},     "\en";
+\&       print $Config{longlongsize}, "\en";
+.Ve
+.Sp
+\&\f(CW$Config{longlongsize}\fR is undefined on systems without
+long long support.
+.IP \(bu 4
+The integer formats \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`S\*(C'\fR, \f(CW\*(C`i\*(C'\fR, \f(CW\*(C`I\*(C'\fR, \f(CW\*(C`l\*(C'\fR, \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`j\*(C'\fR, and \f(CW\*(C`J\*(C'\fR are
+inherently non-portable between processors and operating systems because
+they obey native byteorder and endianness.  For example, a 4\-byte integer
+0x12345678 (305419896 decimal) would be ordered natively (arranged in and
+handled by the CPU registers) into bytes as
+.Sp
+.Vb 2
+\&    0x12 0x34 0x56 0x78  # big\-endian
+\&    0x78 0x56 0x34 0x12  # little\-endian
+.Ve
+.Sp
+Basically, Intel and VAX CPUs are little-endian, while everybody else,
+including Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray, are
+big-endian.  Alpha and MIPS can be either: Digital/Compaq uses (well, used)
+them in little-endian mode, but SGI/Cray uses them in big-endian mode.
+.Sp
+The names \fIbig-endian\fR and \fIlittle-endian\fR are comic references to the
+egg-eating habits of the little-endian Lilliputians and the big-endian
+Blefuscudians from the classic Jonathan Swift satire, \fIGulliver's Travels\fR.
+This entered computer lingo via the paper "On Holy Wars and a Plea for
+Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980.
+.Sp
+Some systems may have even weirder byte orders such as
+.Sp
+.Vb 2
+\&   0x56 0x78 0x12 0x34
+\&   0x34 0x12 0x78 0x56
+.Ve
+.Sp
+These are called mid-endian, middle-endian, mixed-endian, or just weird.
+.Sp
+You can determine your system endianness with this incantation:
+.Sp
+.Vb 1
+\&   printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
+.Ve
+.Sp
+The byteorder on the platform where Perl was built is also available
+via Config:
+.Sp
+.Vb 2
+\&    use Config;
+\&    print "$Config{byteorder}\en";
+.Ve
+.Sp
+or from the command line:
+.Sp
+.Vb 1
+\&    $ perl \-V:byteorder
+.Ve
+.Sp
+Byteorders \f(CW"1234"\fR and \f(CW"12345678"\fR are little-endian; \f(CW"4321"\fR
+and \f(CW"87654321"\fR are big-endian.  Systems with multiarchitecture binaries
+will have \f(CW"ffff"\fR, signifying that static information doesn't work,
+one must use runtime probing.
+.Sp
+For portably packed integers, either use the formats \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`N\*(C'\fR, \f(CW\*(C`v\*(C'\fR,
+and \f(CW\*(C`V\*(C'\fR or else use the \f(CW\*(C`>\*(C'\fR and \f(CW\*(C`<\*(C'\fR modifiers described
+immediately below.  See also perlport.
+.IP \(bu 4
+Also floating point numbers have endianness.  Usually (but not always)
+this agrees with the integer endianness.  Even though most platforms
+these days use the IEEE 754 binary format, there are differences,
+especially if the long doubles are involved.  You can see the
+\&\f(CW\*(C`Config\*(C'\fR variables \f(CW\*(C`doublekind\*(C'\fR and \f(CW\*(C`longdblkind\*(C'\fR (also \f(CW\*(C`doublesize\*(C'\fR,
+\&\f(CW\*(C`longdblsize\*(C'\fR): the "kind" values are enums, unlike \f(CW\*(C`byteorder\*(C'\fR.
+.Sp
+Portability-wise the best option is probably to keep to the IEEE 754
+64\-bit doubles, and of agreed-upon endianness.  Another possibility
+is the \f(CW"%a"\fR) format of \f(CW\*(C`printf\*(C'\fR.
+.IP \(bu 4
+Starting with Perl 5.10.0, integer and floating-point formats, along with
+the \f(CW\*(C`p\*(C'\fR and \f(CW\*(C`P\*(C'\fR formats and \f(CW\*(C`()\*(C'\fR groups, may all be followed by the
+\&\f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR endianness modifiers to respectively enforce big\-
+or little-endian byte-order.  These modifiers are especially useful
+given how \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`N\*(C'\fR, \f(CW\*(C`v\*(C'\fR, and \f(CW\*(C`V\*(C'\fR don't cover signed integers,
+64\-bit integers, or floating-point values.
+.Sp
+Here are some concerns to keep in mind when using an endianness modifier:
+.RS 4
+.IP \(bu 4
+Exchanging signed integers between different platforms works only
+when all platforms store them in the same format.  Most platforms store
+signed integers in two's-complement notation, so usually this is not an issue.
+.IP \(bu 4
+The \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR modifiers can only be used on floating-point
+formats on big\- or little-endian machines.  Otherwise, attempting to
+use them raises an exception.
+.IP \(bu 4
+Forcing big\- or little-endian byte-order on floating-point values for
+data exchange can work only if all platforms use the same
+binary representation such as IEEE floating-point.  Even if all
+platforms are using IEEE, there may still be subtle differences.  Being able
+to use \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR on floating-point values can be useful,
+but also dangerous if you don't know exactly what you're doing.
+It is not a general way to portably store floating-point values.
+.IP \(bu 4
+When using \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR on a \f(CW\*(C`()\*(C'\fR group, this affects
+all types inside the group that accept byte-order modifiers,
+including all subgroups.  It is silently ignored for all other
+types.  You are not allowed to override the byte-order within a group
+that already has a byte-order modifier suffix.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Real numbers (floats and doubles) are in native machine format only.
+Due to the multiplicity of floating-point formats and the lack of a
+standard "network" representation for them, no facility for interchange has been
+made.  This means that packed floating-point data written on one machine
+may not be readable on another, even if both use IEEE floating-point
+arithmetic (because the endianness of the memory representation is not part
+of the IEEE spec).  See also perlport.
+.Sp
+If you know \fIexactly\fR what you're doing, you can use the \f(CW\*(C`>\*(C'\fR or \f(CW\*(C`<\*(C'\fR
+modifiers to force big\- or little-endian byte-order on floating-point values.
+.Sp
+Because Perl uses doubles (or long doubles, if configured) internally for
+all numeric calculation, converting from double into float and thence
+to double again loses precision, so \f(CW\*(C`unpack("f", pack("f", $foo)\*(C'\fR)
+will not in general equal \f(CW$foo\fR.
+.IP \(bu 4
+Pack and unpack can operate in two modes: character mode (\f(CW\*(C`C0\*(C'\fR mode) where
+the packed string is processed per character, and UTF\-8 byte mode (\f(CW\*(C`U0\*(C'\fR mode)
+where the packed string is processed in its UTF\-8\-encoded Unicode form on
+a byte-by-byte basis.  Character mode is the default
+unless the format string starts with \f(CW\*(C`U\*(C'\fR.  You
+can always switch mode mid-format with an explicit
+\&\f(CW\*(C`C0\*(C'\fR or \f(CW\*(C`U0\*(C'\fR in the format.  This mode remains in effect until the next
+mode change, or until the end of the \f(CW\*(C`()\*(C'\fR group it (directly) applies to.
+.Sp
+Using \f(CW\*(C`C0\*(C'\fR to get Unicode characters while using \f(CW\*(C`U0\*(C'\fR to get \fInon\fR\-Unicode
+bytes is not necessarily obvious.   Probably only the first of these
+is what you want:
+.Sp
+.Vb 12
+\&    $ perl \-CS \-E \*(Aqsay "\ex{3B1}\ex{3C9}"\*(Aq |
+\&      perl \-CS \-ne \*(Aqprintf "%v04X\en", $_ for unpack("C0A*", $_)\*(Aq
+\&    03B1.03C9
+\&    $ perl \-CS \-E \*(Aqsay "\ex{3B1}\ex{3C9}"\*(Aq |
+\&      perl \-CS \-ne \*(Aqprintf "%v02X\en", $_ for unpack("U0A*", $_)\*(Aq
+\&    CE.B1.CF.89
+\&    $ perl \-CS \-E \*(Aqsay "\ex{3B1}\ex{3C9}"\*(Aq |
+\&      perl \-C0 \-ne \*(Aqprintf "%v02X\en", $_ for unpack("C0A*", $_)\*(Aq
+\&    CE.B1.CF.89
+\&    $ perl \-CS \-E \*(Aqsay "\ex{3B1}\ex{3C9}"\*(Aq |
+\&      perl \-C0 \-ne \*(Aqprintf "%v02X\en", $_ for unpack("U0A*", $_)\*(Aq
+\&    C3.8E.C2.B1.C3.8F.C2.89
+.Ve
+.Sp
+Those examples also illustrate that you should not try to use
+\&\f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR as a
+substitute for the Encode module.
+.IP \(bu 4
+You must yourself do any alignment or padding by inserting, for example,
+enough \f(CW"x"\fRes while packing.  There is no way for
+\&\f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR
+to know where characters are going to or coming from, so they
+handle their output and input as flat sequences of characters.
+.IP \(bu 4
+A \f(CW\*(C`()\*(C'\fR group is a sub-TEMPLATE enclosed in parentheses.  A group may
+take a repeat count either as postfix, or for
+\&\f(CW\*(C`unpack\*(C'\fR, also via the \f(CW\*(C`/\*(C'\fR
+template character.  Within each repetition of a group, positioning with
+\&\f(CW\*(C`@\*(C'\fR starts over at 0.  Therefore, the result of
+.Sp
+.Vb 1
+\&    pack("@1A((@2A)@3A)", qw[X Y Z])
+.Ve
+.Sp
+is the string \f(CW"\e0X\e0\e0YZ"\fR.
+.IP \(bu 4
+\&\f(CW\*(C`x\*(C'\fR and \f(CW\*(C`X\*(C'\fR accept the \f(CW\*(C`!\*(C'\fR modifier to act as alignment commands: they
+jump forward or back to the closest position aligned at a multiple of \f(CW\*(C`count\*(C'\fR
+characters.  For example, to \f(CW\*(C`pack\*(C'\fR or
+\&\f(CW\*(C`unpack\*(C'\fR a C structure like
+.Sp
+.Vb 5
+\&    struct {
+\&        char   c;    /* one signed, 8\-bit character */
+\&        double d;
+\&        char   cc[2];
+\&    }
+.Ve
+.Sp
+one may need to use the template \f(CW\*(C`c x![d] d c[2]\*(C'\fR.  This assumes that
+doubles must be aligned to the size of double.
+.Sp
+For alignment commands, a \f(CW\*(C`count\*(C'\fR of 0 is equivalent to a \f(CW\*(C`count\*(C'\fR of 1;
+both are no-ops.
+.IP \(bu 4
+\&\f(CW\*(C`n\*(C'\fR, \f(CW\*(C`N\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`V\*(C'\fR accept the \f(CW\*(C`!\*(C'\fR modifier to
+represent signed 16\-/32\-bit integers in big\-/little\-endian order.
+This is portable only when all platforms sharing packed data use the
+same binary representation for signed integers; for example, when all
+platforms use two's-complement representation.
+.IP \(bu 4
+Comments can be embedded in a TEMPLATE using \f(CW\*(C`#\*(C'\fR through the end of line.
+White space can separate pack codes from each other, but modifiers and
+repeat counts must follow immediately.  Breaking complex templates into
+individual line-by-line components, suitably annotated, can do as much to
+improve legibility and maintainability of pack/unpack formats as \f(CW\*(C`/x\*(C'\fR can
+for complicated pattern matches.
+.IP \(bu 4
+If TEMPLATE requires more arguments than \f(CW\*(C`pack\*(C'\fR
+is given, \f(CW\*(C`pack\*(C'\fR
+assumes additional \f(CW""\fR arguments.  If TEMPLATE requires fewer arguments
+than given, extra arguments are ignored.
+.IP \(bu 4
+Attempting to pack the special floating point values \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR
+(infinity, also in negative, and not-a-number) into packed integer values
+(like \f(CW"L"\fR) is a fatal error.  The reason for this is that there simply
+isn't any sensible mapping for these special values into integers.
+.RE
+.RS 4
+.Sp
+Examples:
+.Sp
+.Vb 10
+\&    $foo = pack("WWWW",65,66,67,68);
+\&    # foo eq "ABCD"
+\&    $foo = pack("W4",65,66,67,68);
+\&    # same thing
+\&    $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
+\&    # same thing with Unicode circled letters.
+\&    $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
+\&    # same thing with Unicode circled letters.  You don\*(Aqt get the
+\&    # UTF\-8 bytes because the U at the start of the format caused
+\&    # a switch to U0\-mode, so the UTF\-8 bytes get joined into
+\&    # characters
+\&    $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
+\&    # foo eq "\exe2\ex92\exb6\exe2\ex92\exb7\exe2\ex92\exb8\exe2\ex92\exb9"
+\&    # This is the UTF\-8 encoding of the string in the
+\&    # previous example
+\&
+\&    $foo = pack("ccxxcc",65,66,67,68);
+\&    # foo eq "AB\e0\e0CD"
+\&
+\&    # NOTE: The examples above featuring "W" and "c" are true
+\&    # only on ASCII and ASCII\-derived systems such as ISO Latin 1
+\&    # and UTF\-8.  On EBCDIC systems, the first example would be
+\&    #      $foo = pack("WWWW",193,194,195,196);
+\&
+\&    $foo = pack("s2",1,2);
+\&    # "\e001\e000\e002\e000" on little\-endian
+\&    # "\e000\e001\e000\e002" on big\-endian
+\&
+\&    $foo = pack("a4","abcd","x","y","z");
+\&    # "abcd"
+\&
+\&    $foo = pack("aaaa","abcd","x","y","z");
+\&    # "axyz"
+\&
+\&    $foo = pack("a14","abcdefg");
+\&    # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
+\&
+\&    $foo = pack("i9pl", gmtime);
+\&    # a real struct tm (on my system anyway)
+\&
+\&    $utmp_template = "Z8 Z8 Z16 L";
+\&    $utmp = pack($utmp_template, @utmp1);
+\&    # a struct utmp (BSDish)
+\&
+\&    @utmp2 = unpack($utmp_template, $utmp);
+\&    # "@utmp1" eq "@utmp2"
+\&
+\&    sub bintodec {
+\&        unpack("N", pack("B32", substr("0" x 32 . shift, \-32)));
+\&    }
+\&
+\&    $foo = pack(\*(Aqsx2l\*(Aq, 12, 34);
+\&    # short 12, two zero bytes padding, long 34
+\&    $bar = pack(\*(Aqs@4l\*(Aq, 12, 34);
+\&    # short 12, zero fill to position 4, long 34
+\&    # $foo eq $bar
+\&    $baz = pack(\*(Aqs.l\*(Aq, 12, 4, 34);
+\&    # short 12, zero fill to position 4, long 34
+\&
+\&    $foo = pack(\*(AqnN\*(Aq, 42, 4711);
+\&    # pack big\-endian 16\- and 32\-bit unsigned integers
+\&    $foo = pack(\*(AqS>L>\*(Aq, 42, 4711);
+\&    # exactly the same
+\&    $foo = pack(\*(Aqs<l<\*(Aq, \-42, 4711);
+\&    # pack little\-endian 16\- and 32\-bit signed integers
+\&    $foo = pack(\*(Aq(sl)<\*(Aq, \-42, 4711);
+\&    # exactly the same
+.Ve
+.Sp
+The same template may generally also be used in
+\&\f(CW\*(C`unpack\*(C'\fR.
+.RE
+.IP "package NAMESPACE" 4
+.IX Item "package NAMESPACE"
+.PD 0
+.IP "package NAMESPACE VERSION" 4
+.IX Xref "package module namespace version"
+.IX Item "package NAMESPACE VERSION"
+.IP "package NAMESPACE BLOCK" 4
+.IX Item "package NAMESPACE BLOCK"
+.IP "package NAMESPACE VERSION BLOCK" 4
+.IX Xref "package module namespace version"
+.IX Item "package NAMESPACE VERSION BLOCK"
+.PD
+Declares the BLOCK or the rest of the compilation unit as being in the
+given namespace.  The scope of the package declaration is either the
+supplied code BLOCK or, in the absence of a BLOCK, from the declaration
+itself through the end of current scope (the enclosing block, file, or
+\&\f(CW\*(C`eval\*(C'\fR).  That is, the forms without a BLOCK are
+operative through the end of the current scope, just like the
+\&\f(CW\*(C`my\*(C'\fR, \f(CW\*(C`state\*(C'\fR, and
+\&\f(CW\*(C`our\*(C'\fR operators.  All unqualified dynamic identifiers
+in this scope will be in the given namespace, except where overridden by
+another \f(CW\*(C`package\*(C'\fR declaration or
+when they're one of the special identifiers that qualify into \f(CW\*(C`main::\*(C'\fR,
+like \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`ARGV\*(C'\fR, \f(CW\*(C`ENV\*(C'\fR, and the punctuation variables.
+.Sp
+A package statement affects dynamic variables only, including those
+you've used \f(CW\*(C`local\*(C'\fR on, but \fInot\fR lexically-scoped
+variables, which are created with \f(CW\*(C`my\*(C'\fR,
+\&\f(CW\*(C`state\*(C'\fR, or \f(CW\*(C`our\*(C'\fR.  Typically it
+would be the first declaration in a file included by
+\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR.
+You can switch into a
+package in more than one place, since this only determines which default
+symbol table the compiler uses for the rest of that block.  You can refer to
+identifiers in other packages than the current one by prefixing the identifier
+with the package name and a double colon, as in \f(CW$SomePack::var\fR
+or \f(CW\*(C`ThatPack::INPUT_HANDLE\*(C'\fR.  If package name is omitted, the \f(CW\*(C`main\*(C'\fR
+package is assumed.  That is, \f(CW$::sail\fR is equivalent to
+\&\f(CW$main::sail\fR (as well as to \f(CW\*(C`$main\*(Aqsail\*(C'\fR, still seen in ancient
+code, mostly from Perl 4).
+.Sp
+If VERSION is provided, \f(CW\*(C`package\*(C'\fR sets the
+\&\f(CW$VERSION\fR variable in the given
+namespace to a version object with the VERSION provided.  VERSION must be a
+"strict" style version number as defined by the version module: a positive
+decimal number (integer or decimal-fraction) without exponentiation or else a
+dotted-decimal v\-string with a leading 'v' character and at least three
+components.  You should set \f(CW$VERSION\fR only once per package.
+.Sp
+See "Packages" in perlmod for more information about packages, modules,
+and classes.  See perlsub for other scoping issues.
+.IP _\|_PACKAGE_\|_ 4
+.IX Xref "__PACKAGE__"
+.IX Item "__PACKAGE__"
+A special token that returns the name of the package in which it occurs.
+.IP "pipe READHANDLE,WRITEHANDLE" 4
+.IX Xref "pipe"
+.IX Item "pipe READHANDLE,WRITEHANDLE"
+Opens a pair of connected pipes like the corresponding system call.
+Note that if you set up a loop of piped processes, deadlock can occur
+unless you are very careful.  In addition, note that Perl's pipes use
+IO buffering, so you may need to set \f(CW$|\fR
+to flush your WRITEHANDLE after each command, depending on the
+application.
+.Sp
+Returns true on success.
+.Sp
+See IPC::Open2, IPC::Open3, and
+"Bidirectional Communication with Another Process" in perlipc
+for examples of such things.
+.Sp
+On systems that support a close-on-exec flag on files, that flag is set
+on all newly opened file descriptors whose
+\&\f(CW\*(C`fileno\*(C'\fRs are \fIhigher\fR than the current value of
+\&\f(CW$^F\fR (by default 2 for \f(CW\*(C`STDERR\*(C'\fR).  See "$^F" in perlvar.
+.IP "pop ARRAY" 4
+.IX Xref "pop stack"
+.IX Item "pop ARRAY"
+.PD 0
+.IP pop 4
+.IX Item "pop"
+.PD
+Removes and returns the \fBlast\fR element of the array, shortening the array by
+one element.
+.Sp
+.Vb 2
+\&    my @arr  = (\*(Aqcat\*(Aq, \*(Aqdog\*(Aq, \*(Aqmouse\*(Aq);
+\&    my $item = pop(@arr); # \*(Aqmouse\*(Aq
+\&
+\&    # @arr is now (\*(Aqcat\*(Aq, \*(Aqdog\*(Aq)
+.Ve
+.Sp
+Returns \f(CW\*(C`undef\*(C'\fR if the array is empty.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`pop\*(C'\fR may also return \f(CW\*(C`undef\*(C'\fR if the last element in the array
+is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+.Vb 2
+\&    my @arr  = (\*(Aqone\*(Aq, \*(Aqtwo\*(Aq, undef);
+\&    my $item = pop(@arr); # undef
+.Ve
+.Sp
+If ARRAY is omitted, \f(CW\*(C`pop\*(C'\fR operates on the \f(CW@ARGV\fR array
+in the main program, but the \f(CW@_\fR array in subroutines. \f(CW\*(C`pop\*(C'\fR
+will operate on the \f(CW@ARGV\fR array in \f(CW\*(C`eval STRING\*(C'\fR, \f(CW\*(C`BEGIN {}\*(C'\fR, \f(CW\*(C`INIT {}\*(C'\fR,
+\&\f(CW\*(C`CHECK {}\*(C'\fR blocks.
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`pop\*(C'\fR to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.IP "pos SCALAR" 4
+.IX Xref "pos match, position"
+.IX Item "pos SCALAR"
+.PD 0
+.IP pos 4
+.IX Item "pos"
+.PD
+Returns the offset of where the last \f(CW\*(C`m//g\*(C'\fR search left off for the
+variable in question (\f(CW$_\fR is used when the variable is not
+specified).  This offset is in characters unless the
+(no-longer-recommended) \f(CW\*(C`use bytes\*(C'\fR pragma is in effect, in
+which case the offset is in bytes.  Note that 0 is a valid match offset.
+\&\f(CW\*(C`undef\*(C'\fR indicates
+that the search position is reset (usually due to match failure, but
+can also be because no match has yet been run on the scalar).
+.Sp
+\&\f(CW\*(C`pos\*(C'\fR directly accesses the location used by the regexp
+engine to store the offset, so assigning to \f(CW\*(C`pos\*(C'\fR will
+change that offset, and so will also influence the \f(CW\*(C`\eG\*(C'\fR zero-width
+assertion in regular expressions.  Both of these effects take place for
+the next match, so you can't affect the position with
+\&\f(CW\*(C`pos\*(C'\fR during the current match, such as in
+\&\f(CW\*(C`(?{pos() = 5})\*(C'\fR or \f(CW\*(C`s//pos() = 5/e\*(C'\fR.
+.Sp
+Setting \f(CW\*(C`pos\*(C'\fR also resets the \fImatched with
+zero-length\fR flag, described
+under "Repeated Patterns Matching a Zero-length Substring" in perlre.
+.Sp
+Because a failed \f(CW\*(C`m//gc\*(C'\fR match doesn't reset the offset, the return
+from \f(CW\*(C`pos\*(C'\fR won't change either in this case.  See
+perlre and perlop.
+.IP "print FILEHANDLE LIST" 4
+.IX Xref "print"
+.IX Item "print FILEHANDLE LIST"
+.PD 0
+.IP "print FILEHANDLE" 4
+.IX Item "print FILEHANDLE"
+.IP "print LIST" 4
+.IX Item "print LIST"
+.IP print 4
+.IX Item "print"
+.PD
+Prints a string or a list of strings.  Returns true if successful.
+FILEHANDLE may be a scalar variable containing the name of or a reference
+to the filehandle, thus introducing one level of indirection.  (NOTE: If
+FILEHANDLE is a variable and the next token is a term, it may be
+misinterpreted as an operator unless you interpose a \f(CW\*(C`+\*(C'\fR or put
+parentheses around the arguments.)  If FILEHANDLE is omitted, prints to the
+last selected (see \f(CW\*(C`select\*(C'\fR) output handle.  If
+LIST is omitted, prints \f(CW$_\fR to the currently selected
+output handle.  To use FILEHANDLE alone to print the content of
+\&\f(CW$_\fR to it, you must use a bareword filehandle like
+\&\f(CW\*(C`FH\*(C'\fR, not an indirect one like \f(CW$fh\fR.  To set the default output handle
+to something other than STDOUT, use the select operation.
+.Sp
+The current value of \f(CW$,\fR (if any) is printed between
+each LIST item.  The current value of \f(CW\*(C`$\e\*(C'\fR (if any) is
+printed after the entire LIST has been printed.  Because print takes a
+LIST, anything in the LIST is evaluated in list context, including any
+subroutines whose return lists you pass to
+\&\f(CW\*(C`print\*(C'\fR.  Be careful not to follow the print
+keyword with a left
+parenthesis unless you want the corresponding right parenthesis to
+terminate the arguments to the print; put parentheses around all arguments
+(or interpose a \f(CW\*(C`+\*(C'\fR, but that doesn't look as good).
+.Sp
+If you're storing handles in an array or hash, or in general whenever
+you're using any expression more complex than a bareword handle or a plain,
+unsubscripted scalar variable to retrieve it, you will have to use a block
+returning the filehandle value instead, in which case the LIST may not be
+omitted:
+.Sp
+.Vb 2
+\&    print { $files[$i] } "stuff\en";
+\&    print { $OK ? *STDOUT : *STDERR } "stuff\en";
+.Ve
+.Sp
+Printing to a closed pipe or socket will generate a SIGPIPE signal.  See
+perlipc for more on signal handling.
+.IP "printf FILEHANDLE FORMAT, LIST" 4
+.IX Xref "printf"
+.IX Item "printf FILEHANDLE FORMAT, LIST"
+.PD 0
+.IP "printf FILEHANDLE" 4
+.IX Item "printf FILEHANDLE"
+.IP "printf FORMAT, LIST" 4
+.IX Item "printf FORMAT, LIST"
+.IP printf 4
+.IX Item "printf"
+.PD
+Equivalent to \f(CW\*(C`print FILEHANDLE sprintf(FORMAT, LIST)\*(C'\fR, except that
+\&\f(CW\*(C`$\e\*(C'\fR (the output record separator) is not appended.  The
+FORMAT and the LIST are actually parsed as a single list.  The first
+argument of the list will be interpreted as the
+\&\f(CW\*(C`printf\*(C'\fR format.  This means that
+\&\f(CWprintf(@_)\fR will use \f(CW$_[0]\fR as the format.  See
+sprintf for an explanation of the format
+argument.  If \f(CW\*(C`use locale\*(C'\fR (including \f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR)
+is in effect and \f(CW\*(C`POSIX::setlocale\*(C'\fR has been
+called, the character used for the decimal separator in formatted
+floating-point numbers is affected by the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale setting.
+See perllocale and POSIX.
+.Sp
+For historical reasons, if you omit the list, \f(CW$_\fR is
+used as the format;
+to use FILEHANDLE without a list, you must use a bareword filehandle like
+\&\f(CW\*(C`FH\*(C'\fR, not an indirect one like \f(CW$fh\fR.  However, this will rarely do what
+you want; if \f(CW$_\fR contains formatting codes, they will be
+replaced with the empty string and a warning will be emitted if
+warnings are enabled.  Just use \f(CW\*(C`print\*(C'\fR if
+you want to print the contents of \f(CW$_\fR.
+.Sp
+Don't fall into the trap of using a
+\&\f(CW\*(C`printf\*(C'\fR when a simple
+\&\f(CW\*(C`print\*(C'\fR would do.  The
+\&\f(CW\*(C`print\*(C'\fR is more efficient and less error
+prone.
+.IP "prototype FUNCTION" 4
+.IX Xref "prototype"
+.IX Item "prototype FUNCTION"
+.PD 0
+.IP prototype 4
+.IX Item "prototype"
+.PD
+Returns the prototype of a function as a string (or
+\&\f(CW\*(C`undef\*(C'\fR if the
+function has no prototype).  FUNCTION is a reference to, or the name of,
+the function whose prototype you want to retrieve.  If FUNCTION is omitted,
+\&\f(CW$_\fR is used.
+.Sp
+If FUNCTION is a string starting with \f(CW\*(C`CORE::\*(C'\fR, the rest is taken as a
+name for a Perl builtin.  If the builtin's arguments
+cannot be adequately expressed by a prototype
+(such as \f(CW\*(C`system\*(C'\fR), \f(CW\*(C`prototype\*(C'\fR
+returns \f(CW\*(C`undef\*(C'\fR, because the builtin
+does not really behave like a Perl function.  Otherwise, the string
+describing the equivalent prototype is returned.
+.IP "push ARRAY,LIST" 4
+.IX Xref "push stack"
+.IX Item "push ARRAY,LIST"
+Adds one or more items to the \fBend\fR of an array.
+.Sp
+.Vb 2
+\&        my @animals = ("cat");
+\&        push(@animals, "mouse"); # ("cat", "mouse")
+\&
+\&        my @colors = ("red");
+\&        push(@colors, ("blue", "green")); # ("red", "blue", "green")
+.Ve
+.Sp
+Returns the number of elements in the array following the completed
+\&\f(CW\*(C`push\*(C'\fR.
+.Sp
+.Vb 1
+\&        my $color_count = push(@colors, ("yellow", "purple"));
+\&
+\&        say "There are $color_count colors in the updated array";
+.Ve
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`push\*(C'\fR to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.IP q/STRING/ 4
+.IX Item "q/STRING/"
+.PD 0
+.IP qq/STRING/ 4
+.IX Item "qq/STRING/"
+.IP qw/STRING/ 4
+.IX Item "qw/STRING/"
+.IP qx/STRING/ 4
+.IX Item "qx/STRING/"
+.PD
+Generalized quotes.  See "Quote-Like Operators" in perlop.
+.IP qr/STRING/ 4
+.IX Item "qr/STRING/"
+Regexp-like quote.  See "Regexp Quote-Like Operators" in perlop.
+.IP "quotemeta EXPR" 4
+.IX Xref "quotemeta metacharacter"
+.IX Item "quotemeta EXPR"
+.PD 0
+.IP quotemeta 4
+.IX Item "quotemeta"
+.PD
+Returns the value of EXPR with all the ASCII non\-"word"
+characters backslashed.  (That is, all ASCII characters not matching
+\&\f(CW\*(C`/[A\-Za\-z_0\-9]/\*(C'\fR will be preceded by a backslash in the
+returned string, regardless of any locale settings.)
+This is the internal function implementing
+the \f(CW\*(C`\eQ\*(C'\fR escape in double-quoted strings.
+(See below for the behavior on non-ASCII code points.)
+.Sp
+If EXPR is omitted, uses \f(CW$_\fR.
+.Sp
+quotemeta (and \f(CW\*(C`\eQ\*(C'\fR ... \f(CW\*(C`\eE\*(C'\fR) are useful when interpolating strings into
+regular expressions, because by default an interpolated variable will be
+considered a mini-regular expression.  For example:
+.Sp
+.Vb 3
+\&    my $sentence = \*(AqThe quick brown fox jumped over the lazy dog\*(Aq;
+\&    my $substring = \*(Aqquick.*?fox\*(Aq;
+\&    $sentence =~ s{$substring}{big bad wolf};
+.Ve
+.Sp
+Will cause \f(CW$sentence\fR to become \f(CW\*(AqThe big bad wolf jumped over...\*(Aq\fR.
+.Sp
+On the other hand:
+.Sp
+.Vb 3
+\&    my $sentence = \*(AqThe quick brown fox jumped over the lazy dog\*(Aq;
+\&    my $substring = \*(Aqquick.*?fox\*(Aq;
+\&    $sentence =~ s{\eQ$substring\eE}{big bad wolf};
+.Ve
+.Sp
+Or:
+.Sp
+.Vb 4
+\&    my $sentence = \*(AqThe quick brown fox jumped over the lazy dog\*(Aq;
+\&    my $substring = \*(Aqquick.*?fox\*(Aq;
+\&    my $quoted_substring = quotemeta($substring);
+\&    $sentence =~ s{$quoted_substring}{big bad wolf};
+.Ve
+.Sp
+Will both leave the sentence as is.
+Normally, when accepting literal string input from the user,
+\&\f(CW\*(C`quotemeta\*(C'\fR or \f(CW\*(C`\eQ\*(C'\fR must be used.
+.Sp
+Beware that if you put literal backslashes (those not inside
+interpolated variables) between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR, double-quotish
+backslash interpolation may lead to confusing results.  If you
+\&\fIneed\fR to use literal backslashes within \f(CW\*(C`\eQ...\eE\*(C'\fR,
+consult "Gory details of parsing quoted constructs" in perlop.
+.Sp
+Because the result of \f(CW"\eQ\ \fR\f(CISTRING\fR\f(CW\ \eE"\fR has all metacharacters
+quoted, there is no way to insert a literal \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR inside a
+\&\f(CW\*(C`\eQ\eE\*(C'\fR pair.  If protected by \f(CW\*(C`\e\*(C'\fR, \f(CW\*(C`$\*(C'\fR will be quoted to become
+\&\f(CW"\e\e\e$"\fR; if not, it is interpreted as the start of an interpolated
+scalar.
+.Sp
+In Perl v5.14, all non-ASCII characters are quoted in non\-UTF\-8\-encoded
+strings, but not quoted in UTF\-8 strings.
+.Sp
+Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
+quoting non-ASCII characters; the quoting of ASCII characters is
+unchanged.
+.Sp
+Also unchanged is the quoting of non\-UTF\-8 strings when outside the
+scope of a
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR,
+which is to quote all
+characters in the upper Latin1 range.  This provides complete backwards
+compatibility for old programs which do not use Unicode.  (Note that
+\&\f(CW\*(C`unicode_strings\*(C'\fR is automatically enabled within the scope of a
+\&\f(CW\*(C`use\ v5.12\*(C'\fR or greater.)
+.Sp
+Within the scope of \f(CW\*(C`use locale\*(C'\fR, all non-ASCII Latin1 code
+points
+are quoted whether the string is encoded as UTF\-8 or not.  As mentioned
+above, locale does not affect the quoting of ASCII-range characters.
+This protects against those locales where characters such as \f(CW"|"\fR are
+considered to be word characters.
+.Sp
+Otherwise, Perl quotes non-ASCII characters using an adaptation from
+Unicode (see <https://www.unicode.org/reports/tr31/>).
+The only code points that are quoted are those that have any of the
+Unicode properties:  Pattern_Syntax, Pattern_White_Space, White_Space,
+Default_Ignorable_Code_Point, or General_Category=Control.
+.Sp
+Of these properties, the two important ones are Pattern_Syntax and
+Pattern_White_Space.  They have been set up by Unicode for exactly this
+purpose of deciding which characters in a regular expression pattern
+should be quoted.  No character that can be in an identifier has these
+properties.
+.Sp
+Perl promises, that if we ever add regular expression pattern
+metacharacters to the dozen already defined
+(\f(CW\*(C`\e | ( ) [ { ^ $ * + ? .\*(C'\fR), that we will only use ones that have the
+Pattern_Syntax property.  Perl also promises, that if we ever add
+characters that are considered to be white space in regular expressions
+(currently mostly affected by \f(CW\*(C`/x\*(C'\fR), they will all have the
+Pattern_White_Space property.
+.Sp
+Unicode promises that the set of code points that have these two
+properties will never change, so something that is not quoted in v5.16
+will never need to be quoted in any future Perl release.  (Not all the
+code points that match Pattern_Syntax have actually had characters
+assigned to them; so there is room to grow, but they are quoted
+whether assigned or not.  Perl, of course, would never use an
+unassigned code point as an actual metacharacter.)
+.Sp
+Quoting characters that have the other 3 properties is done to enhance
+the readability of the regular expression and not because they actually
+need to be quoted for regular expression purposes (characters with the
+White_Space property are likely to be indistinguishable on the page or
+screen from those with the Pattern_White_Space property; and the other
+two properties contain non-printing characters).
+.IP "rand EXPR" 4
+.IX Xref "rand random"
+.IX Item "rand EXPR"
+.PD 0
+.IP rand 4
+.IX Item "rand"
+.PD
+Returns a random fractional number greater than or equal to \f(CW0\fR and less
+than the value of EXPR.  (EXPR should be positive.)  If EXPR is
+omitted, the value \f(CW1\fR is used.  Currently EXPR with the value \f(CW0\fR is
+also special-cased as \f(CW1\fR (this was undocumented before Perl 5.8.0
+and is subject to change in future versions of Perl).  Automatically calls
+\&\f(CW\*(C`srand\*(C'\fR unless \f(CW\*(C`srand\*(C'\fR has already been
+called.  See also \f(CW\*(C`srand\*(C'\fR.
+.Sp
+Apply \f(CW\*(C`int\*(C'\fR to the value returned by \f(CW\*(C`rand\*(C'\fR
+if you want random integers instead of random fractional numbers.  For
+example,
+.Sp
+.Vb 1
+\&    int(rand(10))
+.Ve
+.Sp
+returns a random integer between \f(CW0\fR and \f(CW9\fR, inclusive.
+.Sp
+(Note: If your rand function consistently returns numbers that are too
+large or too small, then your version of Perl was probably compiled
+with the wrong number of RANDBITS.)
+.Sp
+\&\fR\f(CB\*(C`rand\*(C'\fR\fB is not cryptographically secure.  You should not rely
+on it in security-sensitive situations.\fR  As of this writing, a
+number of third-party CPAN modules offer random number generators
+intended by their authors to be cryptographically secure,
+including: Data::Entropy, Crypt::Random, Math::Random::Secure,
+and Math::TrulyRandom.
+.IP "read FILEHANDLE,SCALAR,LENGTH,OFFSET" 4
+.IX Xref "read file, read"
+.IX Item "read FILEHANDLE,SCALAR,LENGTH,OFFSET"
+.PD 0
+.IP "read FILEHANDLE,SCALAR,LENGTH" 4
+.IX Item "read FILEHANDLE,SCALAR,LENGTH"
+.PD
+Attempts to read LENGTH \fIcharacters\fR of data into variable SCALAR
+from the specified FILEHANDLE.  Returns the number of characters
+actually read, \f(CW0\fR at end of file, or undef if there was an error (in
+the latter case \f(CW$!\fR is also set).  SCALAR will be grown
+or shrunk
+so that the last character actually read is the last character of the
+scalar after the read.
+.Sp
+An OFFSET may be specified to place the read data at some place in the
+string other than the beginning.  A negative OFFSET specifies
+placement at that many characters counting backwards from the end of
+the string.  A positive OFFSET greater than the length of SCALAR
+results in the string being padded to the required size with \f(CW"\e0"\fR
+bytes before the result of the read is appended.
+.Sp
+The call is implemented in terms of either Perl's or your system's native
+\&\fBfread\fR\|(3) library function, via the PerlIO layers applied to the
+handle.  To get a true \fBread\fR\|(2) system call, see
+sysread.
+.Sp
+Note the \fIcharacters\fR: depending on the status of the filehandle,
+either (8\-bit) bytes or characters are read.  By default, all
+filehandles operate on bytes, but for example if the filehandle has
+been opened with the \f(CW\*(C`:utf8\*(C'\fR I/O layer (see
+\&\f(CW\*(C`open\*(C'\fR, and the open
+pragma), the I/O will operate on UTF8\-encoded Unicode
+characters, not bytes.  Similarly for the \f(CW\*(C`:encoding\*(C'\fR layer:
+in that case pretty much any characters can be read.
+.IP "readdir DIRHANDLE" 4
+.IX Xref "readdir"
+.IX Item "readdir DIRHANDLE"
+Returns the next directory entry for a directory opened by
+\&\f(CW\*(C`opendir\*(C'\fR.
+If used in list context, returns all the rest of the entries in the
+directory.  If there are no more entries, returns the undefined value in
+scalar context and the empty list in list context.
+.Sp
+If you're planning to filetest the return values out of a
+\&\f(CW\*(C`readdir\*(C'\fR, you'd better prepend the directory in
+question.  Otherwise, because we didn't \f(CW\*(C`chdir\*(C'\fR there,
+it would have been testing the wrong file.
+.Sp
+.Vb 3
+\&    opendir(my $dh, $some_dir) || die "Can\*(Aqt opendir $some_dir: $!";
+\&    my @dots = grep { /^\e./ && \-f "$some_dir/$_" } readdir($dh);
+\&    closedir $dh;
+.Ve
+.Sp
+As of Perl 5.12 you can use a bare \f(CW\*(C`readdir\*(C'\fR in a
+\&\f(CW\*(C`while\*(C'\fR loop, which will set \f(CW$_\fR on every iteration.
+If either a \f(CW\*(C`readdir\*(C'\fR expression or an explicit assignment of a
+\&\f(CW\*(C`readdir\*(C'\fR expression to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition,
+then the condition actually tests for definedness of the expression's
+value, not for its regular truth value.
+.Sp
+.Vb 5
+\&    opendir(my $dh, $some_dir) || die "Can\*(Aqt open $some_dir: $!";
+\&    while (readdir $dh) {
+\&        print "$some_dir/$_\en";
+\&    }
+\&    closedir $dh;
+.Ve
+.Sp
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious failures, put this sort of thing at the
+top of your file to signal that your code will work \fIonly\fR on Perls of a
+recent vintage:
+.Sp
+.Vb 1
+\&    use v5.12; # so readdir assigns to $_ in a lone while test
+.Ve
+.IP "readline EXPR" 4
+.IX Item "readline EXPR"
+.PD 0
+.IP readline 4
+.IX Xref "readline gets fgets"
+.IX Item "readline"
+.PD
+Reads from the filehandle whose typeglob is contained in EXPR (or from
+\&\f(CW*ARGV\fR if EXPR is not provided).  In scalar context, each call reads and
+returns the next line until end-of-file is reached, whereupon the
+subsequent call returns \f(CW\*(C`undef\*(C'\fR.  In list context, reads
+until end-of-file is reached and returns a list of lines.  Note that the
+notion of "line" used here is whatever you may have defined with
+\&\f(CW$/\fR (or \f(CW$INPUT_RECORD_SEPARATOR\fR in
+English).  See "$/" in perlvar.
+.Sp
+When \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR,
+when \f(CW\*(C`readline\*(C'\fR is in scalar context (i.e., file
+slurp mode), and when an empty file is read, it returns \f(CW\*(Aq\*(Aq\fR the first
+time, followed by \f(CW\*(C`undef\*(C'\fR subsequently.
+.Sp
+This is the internal function implementing the \f(CW\*(C`<EXPR>\*(C'\fR
+operator, but you can use it directly.  The \f(CW\*(C`<EXPR>\*(C'\fR
+operator is discussed in more detail in "I/O Operators" in perlop.
+.Sp
+.Vb 2
+\&    my $line = <STDIN>;
+\&    my $line = readline(STDIN);    # same thing
+.Ve
+.Sp
+If \f(CW\*(C`readline\*(C'\fR encounters an operating system error,
+\&\f(CW$!\fR will be set with the corresponding error message.
+It can be helpful to check \f(CW$!\fR when you are reading from
+filehandles you don't trust, such as a tty or a socket.  The following
+example uses the operator form of \f(CW\*(C`readline\*(C'\fR and dies
+if the result is not defined.
+.Sp
+.Vb 4
+\&    while ( ! eof($fh) ) {
+\&        defined( $_ = readline $fh ) or die "readline failed: $!";
+\&        ...
+\&    }
+.Ve
+.Sp
+Note that you can't handle \f(CW\*(C`readline\*(C'\fR errors
+that way with the \f(CW\*(C`ARGV\*(C'\fR filehandle.  In that case, you have to open
+each element of \f(CW@ARGV\fR yourself since
+\&\f(CW\*(C`eof\*(C'\fR handles \f(CW\*(C`ARGV\*(C'\fR differently.
+.Sp
+.Vb 2
+\&    foreach my $arg (@ARGV) {
+\&        open(my $fh, $arg) or warn "Can\*(Aqt open $arg: $!";
+\&
+\&        while ( ! eof($fh) ) {
+\&            defined( $_ = readline $fh )
+\&                or die "readline failed for $arg: $!";
+\&            ...
+\&        }
+\&    }
+.Ve
+.Sp
+Like the \f(CW\*(C`<EXPR>\*(C'\fR operator, if a \f(CW\*(C`readline\*(C'\fR expression is
+used as the condition of a \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`for\*(C'\fR loop, then it will be
+implicitly assigned to \f(CW$_\fR.  If either a \f(CW\*(C`readline\*(C'\fR expression or
+an explicit assignment of a \f(CW\*(C`readline\*(C'\fR expression to a scalar is used
+as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then the condition actually tests for
+definedness of the expression's value, not for its regular truth value.
+.IP "readlink EXPR" 4
+.IX Xref "readlink"
+.IX Item "readlink EXPR"
+.PD 0
+.IP readlink 4
+.IX Item "readlink"
+.PD
+Returns the value of a symbolic link, if symbolic links are
+implemented.  If not, raises an exception.  If there is a system
+error, returns the undefined value and sets \f(CW$!\fR (errno).
+If EXPR is omitted, uses \f(CW$_\fR.
+.Sp
+Portability issues: "readlink" in perlport.
+.IP "readpipe EXPR" 4
+.IX Item "readpipe EXPR"
+.PD 0
+.IP readpipe 4
+.IX Xref "readpipe"
+.IX Item "readpipe"
+.PD
+EXPR is executed as a system command.
+The collected standard output of the command is returned.
+In scalar context, it comes back as a single (potentially
+multi-line) string.  In list context, returns a list of lines
+(however you've defined lines with \f(CW$/\fR (or
+\&\f(CW$INPUT_RECORD_SEPARATOR\fR in English)).
+This is the internal function implementing the \f(CW\*(C`qx/EXPR/\*(C'\fR
+operator, but you can use it directly.  The \f(CW\*(C`qx/EXPR/\*(C'\fR
+operator is discussed in more detail in "\f(CW\*(C`qx/\fR\f(CISTRING\fR\f(CW/\*(C'\fR" in perlop.
+If EXPR is omitted, uses \f(CW$_\fR.
+.IP "recv SOCKET,SCALAR,LENGTH,FLAGS" 4
+.IX Xref "recv"
+.IX Item "recv SOCKET,SCALAR,LENGTH,FLAGS"
+Receives a message on a socket.  Attempts to receive LENGTH characters
+of data into variable SCALAR from the specified SOCKET filehandle.
+SCALAR will be grown or shrunk to the length actually read.  Takes the
+same flags as the system call of the same name.  Returns the address
+of the sender if SOCKET's protocol supports this; returns an empty
+string otherwise.  If there's an error, returns the undefined value.
+This call is actually implemented in terms of the \fBrecvfrom\fR\|(2) system call.
+See "UDP: Message Passing" in perlipc for examples.
+.Sp
+Note that if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`recv\*(C'\fR will
+throw an exception.  The \f(CW:encoding(...)\fR layer implicitly introduces
+the \f(CW\*(C`:utf8\*(C'\fR layer.  See \f(CW\*(C`binmode\*(C'\fR.
+.IP "redo LABEL" 4
+.IX Xref "redo"
+.IX Item "redo LABEL"
+.PD 0
+.IP "redo EXPR" 4
+.IX Item "redo EXPR"
+.IP redo 4
+.IX Item "redo"
+.PD
+The \f(CW\*(C`redo\*(C'\fR command restarts the loop block without
+evaluating the conditional again.  The \f(CW\*(C`continue\*(C'\fR
+block, if any, is not executed.  If
+the LABEL is omitted, the command refers to the innermost enclosing
+loop.  The \f(CW\*(C`redo EXPR\*(C'\fR form, available starting in Perl 5.18.0, allows a
+label name to be computed at run time, and is otherwise identical to \f(CW\*(C`redo
+LABEL\*(C'\fR.  Programs that want to lie to themselves about what was just input
+normally use this command:
+.Sp
+.Vb 10
+\&    # a simpleminded Pascal comment stripper
+\&    # (warning: assumes no { or } in strings)
+\&    LINE: while (<STDIN>) {
+\&        while (s|({.*}.*){.*}|$1 |) {}
+\&        s|{.*}| |;
+\&        if (s|{.*| |) {
+\&            my $front = $_;
+\&            while (<STDIN>) {
+\&                if (/}/) {  # end of comment?
+\&                    s|^|$front\e{|;
+\&                    redo LINE;
+\&                }
+\&            }
+\&        }
+\&        print;
+\&    }
+.Ve
+.Sp
+\&\f(CW\*(C`redo\*(C'\fR cannot return a value from a block that typically
+returns a value, such as \f(CW\*(C`eval {}\*(C'\fR, \f(CW\*(C`sub {}\*(C'\fR, or \f(CW\*(C`do {}\*(C'\fR. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a \f(CW\*(C`grep\*(C'\fR or \f(CW\*(C`map\*(C'\fR
+operation.
+.Sp
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus \f(CW\*(C`redo\*(C'\fR inside such a block
+will effectively turn it into a looping construct.
+.Sp
+See also \f(CW\*(C`continue\*(C'\fR for an illustration of how
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, and
+\&\f(CW\*(C`redo\*(C'\fR work.
+.Sp
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+\&\f(CW\*(C`redo ("foo")."bar"\*(C'\fR will cause "bar" to be part of the argument to
+\&\f(CW\*(C`redo\*(C'\fR.
+.IP "ref EXPR" 4
+.IX Xref "ref reference"
+.IX Item "ref EXPR"
+.PD 0
+.IP ref 4
+.IX Item "ref"
+.PD
+Examines the value of EXPR, expecting it to be a reference, and returns
+a string giving information about the reference and the type of referent.
+If EXPR is not specified, \f(CW$_\fR will be used.
+.Sp
+If the operand is not a reference, then the empty string will be returned.
+An empty string will only be returned in this situation.  \f(CW\*(C`ref\*(C'\fR is often
+useful to just test whether a value is a reference, which can be done
+by comparing the result to the empty string.  It is a common mistake
+to use the result of \f(CW\*(C`ref\*(C'\fR directly as a truth value: this goes wrong
+because \f(CW0\fR (which is false) can be returned for a reference.
+.Sp
+If the operand is a reference to a blessed object, then the name of
+the class into which the referent is blessed will be returned.  \f(CW\*(C`ref\*(C'\fR
+doesn't care what the physical type of the referent is; blessing takes
+precedence over such concerns.  Beware that exact comparison of \f(CW\*(C`ref\*(C'\fR
+results against a class name doesn't perform a class membership test:
+a class's members also include objects blessed into subclasses, for
+which \f(CW\*(C`ref\*(C'\fR will return the name of the subclass.  Also beware that
+class names can clash with the built-in type names (described below).
+.Sp
+If the operand is a reference to an unblessed object, then the return
+value indicates the type of object.  If the unblessed referent is not
+a scalar, then the return value will be one of the strings \f(CW\*(C`ARRAY\*(C'\fR,
+\&\f(CW\*(C`HASH\*(C'\fR, \f(CW\*(C`CODE\*(C'\fR, \f(CW\*(C`FORMAT\*(C'\fR, or \f(CW\*(C`IO\*(C'\fR, indicating only which kind of
+object it is.  If the unblessed referent is a scalar, then the return
+value will be one of the strings \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`VSTRING\*(C'\fR, \f(CW\*(C`REF\*(C'\fR, \f(CW\*(C`GLOB\*(C'\fR,
+\&\f(CW\*(C`LVALUE\*(C'\fR, or \f(CW\*(C`REGEXP\*(C'\fR, depending on the kind of value the scalar
+currently has.   But note that \f(CW\*(C`qr//\*(C'\fR scalars are created already
+blessed, so \f(CW\*(C`ref qr/.../\*(C'\fR will likely return \f(CW\*(C`Regexp\*(C'\fR.  Beware that
+these built-in type names can also be used as
+class names, so \f(CW\*(C`ref\*(C'\fR returning one of these names doesn't unambiguously
+indicate that the referent is of the kind to which the name refers.
+.Sp
+The ambiguity between built-in type names and class names significantly
+limits the utility of \f(CW\*(C`ref\*(C'\fR.  For unambiguous information, use
+\&\f(CWScalar::Util::blessed()\fR for information about
+blessing, and \f(CWScalar::Util::reftype()\fR for
+information about physical types.  Use the \f(CW\*(C`isa\*(C'\fR method for class membership tests, though one must be
+sure of blessedness before attempting a method call.  Alternatively, the
+\&\f(CW\*(C`isa\*(C'\fR operator can test class
+membership without checking blessedness first.
+.Sp
+See also perlref and perlobj.
+.IP "rename OLDNAME,NEWNAME" 4
+.IX Xref "rename move mv ren"
+.IX Item "rename OLDNAME,NEWNAME"
+Changes the name of a file; an existing file NEWNAME will be
+clobbered.  Returns true for success; on failure returns false and sets
+\&\f(CW$!\fR.
+.Sp
+Behavior of this function varies wildly depending on your system
+implementation.  For example, it will usually not work across file system
+boundaries, even though the system \fImv\fR command sometimes compensates
+for this.  Other restrictions include whether it works on directories,
+open files, or pre-existing files.  Check perlport and either the
+\&\fBrename\fR\|(2) manpage or equivalent system documentation for details.
+.Sp
+For a platform independent \f(CW\*(C`move\*(C'\fR function look at
+the File::Copy module.
+.Sp
+Portability issues: "rename" in perlport.
+.IP "require VERSION" 4
+.IX Xref "require"
+.IX Item "require VERSION"
+.PD 0
+.IP "require EXPR" 4
+.IX Item "require EXPR"
+.IP require 4
+.IX Item "require"
+.PD
+Demands a version of Perl specified by VERSION, or demands some semantics
+specified by EXPR or by \f(CW$_\fR if EXPR is not supplied.
+.Sp
+VERSION may be either a literal such as v5.24.1, which will be
+compared to \f(CW$^V\fR (or \f(CW$PERL_VERSION\fR in English),
+or a numeric argument of the form 5.024001, which will be compared to
+\&\f(CW$]\fR. An exception is raised if VERSION is greater than
+the version of the current Perl interpreter.  Compare with
+\&\f(CW\*(C`use\*(C'\fR, which can do a similar check at
+compile time.
+.Sp
+Specifying VERSION as a numeric argument of the form 5.024001 should
+generally be avoided as older less readable syntax compared to
+v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose numeric
+form was the only supported syntax, which is why you might see it in
+older code.
+.Sp
+.Vb 4
+\&    require v5.24.1;    # run time version check
+\&    require 5.24.1;     # ditto
+\&    require 5.024_001;  # ditto; older syntax compatible
+\&                          with perl 5.6
+.Ve
+.Sp
+Otherwise, \f(CW\*(C`require\*(C'\fR demands that a library file be
+included if it hasn't already been included.  The file is included via
+the do-FILE mechanism, which is essentially just a variety of
+\&\f(CW\*(C`eval\*(C'\fR with the
+caveat that lexical variables in the invoking script will be invisible
+to the included code.  If it were implemented in pure Perl, it
+would have semantics similar to the following:
+.Sp
+.Vb 2
+\&    use Carp \*(Aqcroak\*(Aq;
+\&    use version;
+\&
+\&    sub require {
+\&        my ($filename) = @_;
+\&        if ( my $version = eval { version\->parse($filename) } ) {
+\&            if ( $version > $^V ) {
+\&               my $vn = $version\->normal;
+\&               croak "Perl $vn required\-\-this is only $^V, stopped";
+\&            }
+\&            return 1;
+\&        }
+\&
+\&        if (exists $INC{$filename}) {
+\&            return 1 if $INC{$filename};
+\&            croak "Compilation failed in require";
+\&        }
+\&
+\&        local $INC;
+\&        # this type of loop lets a hook overwrite $INC if they wish
+\&        for($INC = 0; $INC < @INC; $INC++) {
+\&            my $prefix = $INC[$INC];
+\&            if (!defined $prefix) {
+\&                next;
+\&            }
+\&            if (ref $prefix) {
+\&                #... do other stuff \- see text below ....
+\&            }
+\&            # (see text below about possible appending of .pmc
+\&            # suffix to $filename)
+\&            my $realfilename = "$prefix/$filename";
+\&            next if ! \-e $realfilename || \-d _ || \-b _;
+\&            $INC{$filename} = $realfilename;
+\&            my $result = do($realfilename);
+\&                         # but run in caller\*(Aqs namespace
+\&
+\&            if (!defined $result) {
+\&                $INC{$filename} = undef;
+\&                croak $@ ? "$@Compilation failed in require"
+\&                         : "Can\*(Aqt locate $filename: $!\en";
+\&            }
+\&            if (!$result) {
+\&                delete $INC{$filename};
+\&                croak "$filename did not return true value";
+\&            }
+\&            $! = 0;
+\&            return $result;
+\&        }
+\&        croak "Can\*(Aqt locate $filename in \e@INC ...";
+\&    }
+.Ve
+.Sp
+Note that the file will not be included twice under the same specified
+name.
+.Sp
+Historically the file must return true as the last statement to indicate
+successful execution of any initialization code, so it's customary to
+end such a file with \f(CW\*(C`1;\*(C'\fR unless you're sure it'll return true
+otherwise.  But it's better just to put the \f(CW\*(C`1;\*(C'\fR, in case you add more
+statements. As of 5.37.6 this requirement may be avoided by enabling
+the 'module_true' feature, which is enabled by default in modern
+version bundles. Thus code with \f(CW\*(C`use v5.37;\*(C'\fR no longer needs to concern
+itself with this issue. See feature for more details. Note that this
+affects the compilation unit within which the feature is used, and using
+it before requiring a module will not change the behavior of existing
+modules that do not themselves also use it.
+.Sp
+If EXPR is a bareword, \f(CW\*(C`require\*(C'\fR assumes a \fI.pm\fR
+extension and replaces \f(CW\*(C`::\*(C'\fR with \f(CW\*(C`/\*(C'\fR in the filename for you,
+to make it easy to load standard modules.  This form of loading of
+modules does not risk altering your namespace, however it will autovivify
+the stash for the required module.
+.Sp
+In other words, if you try this:
+.Sp
+.Vb 1
+\&        require Foo::Bar;     # a splendid bareword
+.Ve
+.Sp
+The require function will actually look for the \fIFoo/Bar.pm\fR file in the
+directories specified in the \f(CW@INC\fR array, and it will
+autovivify the \f(CW\*(C`Foo::Bar::\*(C'\fR stash at compile time.
+.Sp
+But if you try this:
+.Sp
+.Vb 4
+\&        my $class = \*(AqFoo::Bar\*(Aq;
+\&        require $class;       # $class is not a bareword
+\&    #or
+\&        require "Foo::Bar";   # not a bareword because of the ""
+.Ve
+.Sp
+The require function will look for the \fIFoo::Bar\fR file in the
+\&\f(CW@INC\fR  array and
+will complain about not finding \fIFoo::Bar\fR there.  In this case you can do:
+.Sp
+.Vb 1
+\&        eval "require $class";
+.Ve
+.Sp
+or you could do
+.Sp
+.Vb 1
+\&        require "Foo/Bar.pm";
+.Ve
+.Sp
+Neither of these forms will autovivify any stashes at compile time and
+only have run time effects.
+.Sp
+Now that you understand how \f(CW\*(C`require\*(C'\fR looks for
+files with a bareword argument, there is a little extra functionality
+going on behind the scenes.  Before \f(CW\*(C`require\*(C'\fR looks
+for a \fI.pm\fR extension, it will first look for a similar filename with a
+\&\fI.pmc\fR extension.  If this file is found, it will be loaded in place of
+any file ending in a \fI.pm\fR extension. This applies to both the explicit
+\&\f(CW\*(C`require "Foo/Bar.pm";\*(C'\fR form and the \f(CW\*(C`require Foo::Bar;\*(C'\fR form.
+.Sp
+You can also insert hooks into the import facility by putting Perl
+coderefs or objects directly into the \f(CW@INC\fR array.
+There are two types of hooks, INC filters, and INCDIR hooks, and there
+are three forms of representing a hook: subroutine references, array
+references, and blessed objects.
+.Sp
+Subroutine references are the simplest case.  When the inclusion system
+walks through \f(CW@INC\fR and encounters a subroutine, unless
+this subroutine is blessed and supports an INCDIR hook this
+subroutine will be assumed to be an INC hook will be called with two
+parameters, the first a reference to itself, and the second the name of
+the file to be included (e.g., \fIFoo/Bar.pm\fR).  The subroutine should
+return either nothing or else a list of up to four values in the
+following order:
+.RS 4
+.IP 1. 4
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
+.IP 2. 4
+A filehandle, from which the file will be read.
+.IP 3. 4
+A reference to a subroutine.  If there is no filehandle (previous item),
+then this subroutine is expected to generate one line of source code per
+call, writing the line into \f(CW$_\fR and returning 1, then
+finally at end of file returning 0.  If there is a filehandle, then the
+subroutine will be called to act as a simple source filter, with the
+line as read in \f(CW$_\fR.
+Again, return 1 for each valid line, and 0 after all lines have been
+returned.
+For historical reasons the subroutine will receive a meaningless argument
+(in fact always the numeric value zero) as \f(CW$_[0]\fR.
+.IP 4. 4
+Optional state for the subroutine.  The state is passed in as \f(CW$_[1]\fR.
+.RE
+.RS 4
+.Sp
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR cannot be used to resolve the \f(CW\*(C`INCDIR\*(C'\fR method, \f(CW\*(C`INC\*(C'\fR is
+checked first, and \f(CW\*(C`AUTOLOAD\*(C'\fR would resolve that.
+.Sp
+If an empty list, \f(CW\*(C`undef\*(C'\fR, or nothing that matches the
+first 3 values above is returned, then \f(CW\*(C`require\*(C'\fR
+looks at the remaining elements of \f(CW@INC\fR.
+Note that this filehandle must be a real filehandle (strictly a typeglob
+or reference to a typeglob, whether blessed or unblessed); tied filehandles
+will be ignored and processing will stop there.
+.Sp
+If the hook is an object, it should provide an \f(CW\*(C`INC\*(C'\fR or \f(CW\*(C`INCDIR\*(C'\fR
+method that will be called as above, the first parameter being the
+object itself. If it does not provide either method, and the object is
+not CODE ref then an exception will be thrown, otherwise it will simply
+be executed like an unblessed CODE ref would. Note that you must fully
+qualify the method name when you declare an \f(CW\*(C`INC\*(C'\fR sub (unlike the
+\&\f(CW\*(C`INCDIR\*(C'\fR sub), as the unqualified symbol \f(CW\*(C`INC\*(C'\fR is always forced into
+package \f(CW\*(C`main\*(C'\fR.  Here is a typical code layout for an \f(CW\*(C`INC\*(C'\fR hook:
+.Sp
+.Vb 7
+\&    # In Foo.pm
+\&    package Foo;
+\&    sub new { ... }
+\&    sub Foo::INC {
+\&        my ($self, $filename) = @_;
+\&        ...
+\&    }
+\&
+\&    # In the main program
+\&    push @INC, Foo\->new(...);
+.Ve
+.Sp
+If the hook is an array reference, its first element must be a
+subroutine reference or an object as described above. When the first
+element is an object that supports an \f(CW\*(C`INC\*(C'\fR or \f(CW\*(C`INCDIR\*(C'\fR method then
+the method will be called with the object as the first argument, the
+filename requested as the second, and the hook array reference as the
+the third. When the first element is a subroutine then it will be
+called with the array as the first argument, and the filename as the
+second, no third parameter will be passed in. In both forms you can
+modify the contents of the array to provide state between calls, or
+whatever you like.
+.Sp
+In other words, you can write:
+.Sp
+.Vb 5
+\&    push @INC, \e&my_sub;
+\&    sub my_sub {
+\&        my ($coderef, $filename) = @_;  # $coderef is \e&my_sub
+\&        ...
+\&    }
+.Ve
+.Sp
+or:
+.Sp
+.Vb 7
+\&    push @INC, [ \e&my_sub, $x, $y, ... ];
+\&    sub my_sub {
+\&        my ($arrayref, $filename) = @_;
+\&        # Retrieve $x, $y, ...
+\&        my (undef, @parameters) = @$arrayref;
+\&        ...
+\&    }
+.Ve
+.Sp
+or:
+.Sp
+.Vb 6
+\&    push @INC, [ HookObj\->new(), $x, $y, ... ];
+\&    sub HookObj::INC {
+\&        my ($self, $filename, $arrayref)= @_;
+\&        my (undef, @parameters) = @$arrayref;
+\&        ...
+\&    }
+.Ve
+.Sp
+These hooks are also permitted to set the \f(CW%INC\fR entry
+corresponding to the files they have loaded.  See "%INC" in perlvar.
+Should an \f(CW\*(C`INC\*(C'\fR hook not do this then perl will set the \f(CW%INC\fR entry
+to be the hook reference itself.
+.Sp
+A hook may also be used to rewrite the \f(CW@INC\fR array. While this might
+sound strange, there are situations where it can be very useful to do
+this. Such hooks usually just return undef and do not mix filtering and
+\&\f(CW@INC\fR modifications. While in older versions of perl having a hook
+modify \f(CW@INC\fR was fraught with issues and could even result in
+segfaults or assert failures, as of 5.37.7 the logic has been made much
+more robust and the hook now has control over the loop iteration if it
+wishes to do so.
+.Sp
+There is a now a facility to control the iterator for the \f(CW@INC\fR array
+traversal that is performed during require. The \f(CW$INC\fR variable will be
+initialized with the index of the currently executing hook. Once the
+hook returns the next slot in \f(CW@INC\fR that will be checked will be the
+integer successor of value in \f(CW$INC\fR (or \-1 if it is undef). For example
+the following code
+.Sp
+.Vb 7
+\&    push @INC, sub {
+\&        splice @INC, $INC, 1; # remove this hook from @INC
+\&        unshift @INC, sub { warn "A" };
+\&        undef $INC; # reset the $INC iterator so we
+\&                    # execute the newly installed sub
+\&                    # immediately.
+\&    };
+.Ve
+.Sp
+would install a sub into \f(CW@INC\fR that when executed as a hook (by for
+instance a require of a file that does not exist), the hook will splice
+itself out of \f(CW@INC\fR, and add a new sub to the front that will warn
+whenever someone does a require operation that requires an \f(CW@INC\fR
+search, and then immediately execute that hook.
+.Sp
+Prior to 5.37.7, there was no way to cause perl to use the newly
+installed hook immediately, or to inspect any changed items in \f(CW@INC\fR to
+the left of the iterator, and so the warning would only be generated on
+the second call to require. In more recent perl the presence of the last
+statement which undefines \f(CW$INC\fR will cause perl to restart the
+traversal of the \f(CW@INC\fR array at the beginning and execute the newly
+installed sub immediately.
+.Sp
+Whatever value \f(CW$INC\fR held, if any, will be restored at the end of the
+require. Any changes made to \f(CW$INC\fR during the lifetime of the hook
+will be unrolled after the hook exits, and its value only has meaning
+immediately after execution of the hook, thus setting \f(CW$INC\fR to some
+value prior to executing a \f(CW\*(C`require\*(C'\fR will have no effect on how the
+require executes at all.
+.Sp
+As of 5.37.7 \f(CW@INC\fR values of undef will be silently ignored.
+.Sp
+The function \f(CWrequire()\fR is difficult to wrap properly. Many modules
+consult the stack to find information about their caller, and injecting
+a new stack frame by wrapping \f(CWrequire()\fR often breaks things.
+Nevertheless it can be very helpful to have the ability to perform
+actions before and after a \f(CW\*(C`require\*(C'\fR, for instance for trace utilities
+like \f(CW\*(C`Devel::TraceUse\*(C'\fR or to measure time to load and the memory
+consumption of the require graph. Because of the difficulties in safely
+creating a \f(CWrequire()\fR wrapper in 5.37.10 we introduced a new mechanism.
+.Sp
+As of 5.37.10, prior to any other actions it performs, \f(CW\*(C`require\*(C'\fR will
+check if \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR contains a coderef, and if it does
+it will be called with the filename form of the item being loaded. The hook
+may modify \f(CW$_[0]\fR to load a different filename, or it may throw a fatal
+exception to cause the require to fail, which will be treated as though the
+required code itself had thrown an exception.
+.Sp
+The \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR hook may return a code reference, in
+which case the code reference will be executed (in an eval with the
+filname as a parameter) after the require completes. It will be executed
+regardless of how the compilation completed, and even if the require
+throws a fatal exception.  The function may consult \f(CW%INC\fR to determine
+if the require failed or not.  For instance the following code will print
+some diagnostics before and after every \f(CW\*(C`require\*(C'\fR statement.  The
+example also includes logic to chain the signal, so that multiple
+signals can cooperate. Well behaved \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR
+handlers should always take this into account.
+.Sp
+.Vb 10
+\&    {
+\&        use Scalar::Util qw(reftype);
+\&        my $old_hook = ${^HOOK}{require_\|_before};
+\&        local ${^HOOK}{require_\|_before} = sub {
+\&            my ($name) = @_;
+\&            my $old_hook_ret;
+\&            $old_hook_ret = $old_hook\->($name) if $old_hook;
+\&            warn "Requiring: $name\en";
+\&            return sub {
+\&                $old_hook_ret\->() if ref($old_hook_ret)
+\&                                  && reftype($old_hook_ret) eq "CODE";
+\&                warn sprintf "Finished requiring %s: %s\en",
+\&                        $name, $INC{$name} ? "loaded" :"failed";
+\&            };
+\&        };
+\&        require Whatever;
+\&    }
+.Ve
+.Sp
+This hook executes for ALL \f(CW\*(C`require\*(C'\fR statements, unlike \f(CW\*(C`INC\*(C'\fR and
+\&\f(CW\*(C`INCDIR\*(C'\fR hooks, which are only executed for relative file names, and it
+executes first before any other special behaviour inside of require.
+Note that the initial hook in \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR is *not*
+executed inside of an eval, and throwing an exception will stop further
+processing, but the after hook it may return is executed inside of an
+eval, and any exceptions it throws will be silently ignored.  This is
+because it executes inside of the scope cleanup logic that is triggered
+after the require completes, and an exception at this time would not
+stop the module from being loaded, etc.
+.Sp
+There is a similar hook that fires after require completes,
+\&\f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR, which will be called after each require statement
+completes, either via an exception or successfully. It will be called with
+the filename of the most recently executed require statement. It is executed
+in an eval, and will not in any way affect execution.
+.Sp
+For a yet-more-powerful import facility built around \f(CW\*(C`require\*(C'\fR, see
+\&\f(CW\*(C`use\*(C'\fR and perlmod.
+.RE
+.IP "reset EXPR" 4
+.IX Xref "reset"
+.IX Item "reset EXPR"
+.PD 0
+.IP reset 4
+.IX Item "reset"
+.PD
+Generally used in a \f(CW\*(C`continue\*(C'\fR block at the end of a
+loop to clear variables and reset \f(CW\*(C`m?pattern?\*(C'\fR searches so that they
+work again.  The
+expression is interpreted as a list of single characters (hyphens
+allowed for ranges).  All variables (scalars, arrays, and hashes)
+in the current package beginning with one of
+those letters are reset to their pristine state.  If the expression is
+omitted, one-match searches (\f(CW\*(C`m?pattern?\*(C'\fR) are reset to match again.
+Only resets variables or searches in the current package.  Always returns
+1.  Examples:
+.Sp
+.Vb 3
+\&    reset \*(AqX\*(Aq;      # reset all X variables
+\&    reset \*(Aqa\-z\*(Aq;    # reset lower case variables
+\&    reset;          # just reset m?one\-time? searches
+.Ve
+.Sp
+Resetting \f(CW"A\-Z"\fR is not recommended because you'll wipe out your
+\&\f(CW@ARGV\fR and \f(CW@INC\fR arrays and your
+\&\f(CW%ENV\fR hash.
+.Sp
+Resets only package variables; lexical variables are unaffected, but
+they clean themselves up on scope exit anyway, so you'll probably want
+to use them instead.  See \f(CW\*(C`my\*(C'\fR.
+.IP "return EXPR" 4
+.IX Xref "return"
+.IX Item "return EXPR"
+.PD 0
+.IP return 4
+.IX Item "return"
+.PD
+Returns from a subroutine, \f(CW\*(C`eval\*(C'\fR,
+\&\f(CW\*(C`do FILE\*(C'\fR, \f(CW\*(C`sort\*(C'\fR block or regex
+eval block (but not a \f(CW\*(C`grep\*(C'\fR,
+\&\f(CW\*(C`map\*(C'\fR, or \f(CW\*(C`do BLOCK\*(C'\fR block) with the value
+given in EXPR.  Evaluation of EXPR may be in list, scalar, or void
+context, depending on how the return value will be used, and the context
+may vary from one execution to the next (see
+\&\f(CW\*(C`wantarray\*(C'\fR).  If no EXPR
+is given, returns an empty list in list context, the undefined value in
+scalar context, and (of course) nothing at all in void context.
+.Sp
+(In the absence of an explicit \f(CW\*(C`return\*(C'\fR, a subroutine,
+\&\f(CW\*(C`eval\*(C'\fR,
+or \f(CW\*(C`do FILE\*(C'\fR automatically returns the value of the last expression
+evaluated.)
+.Sp
+Unlike most named operators, this is also exempt from the
+looks-like-a-function rule, so \f(CW\*(C`return ("foo")."bar"\*(C'\fR will
+cause \f(CW"bar"\fR to be part of the argument to \f(CW\*(C`return\*(C'\fR.
+.IP "reverse LIST" 4
+.IX Xref "reverse rev invert"
+.IX Item "reverse LIST"
+In list context, returns a list value consisting of the elements
+of LIST in the opposite order.  In scalar context, concatenates the
+elements of LIST and returns a string value with all characters
+in the opposite order.
+.Sp
+.Vb 1
+\&    print join(", ", reverse "world", "Hello"); # Hello, world
+\&
+\&    print scalar reverse "dlrow ,", "olleH";    # Hello, world
+.Ve
+.Sp
+Used without arguments in scalar context, \f(CW\*(C`reverse\*(C'\fR
+reverses \f(CW$_\fR.
+.Sp
+.Vb 3
+\&    $_ = "dlrow ,olleH";
+\&    print reverse;                         # No output, list context
+\&    print scalar reverse;                  # Hello, world
+.Ve
+.Sp
+Note that reversing an array to itself (as in \f(CW\*(C`@a = reverse @a\*(C'\fR) will
+preserve non-existent elements whenever possible; i.e., for non-magical
+arrays or for tied arrays with \f(CW\*(C`EXISTS\*(C'\fR and \f(CW\*(C`DELETE\*(C'\fR methods.
+.Sp
+This operator is also handy for inverting a hash, although there are some
+caveats.  If a value is duplicated in the original hash, only one of those
+can be represented as a key in the inverted hash.  Also, this has to
+unwind one hash and build a whole new one, which may take some time
+on a large hash, such as from a DBM file.
+.Sp
+.Vb 1
+\&    my %by_name = reverse %by_address;  # Invert the hash
+.Ve
+.IP "rewinddir DIRHANDLE" 4
+.IX Xref "rewinddir"
+.IX Item "rewinddir DIRHANDLE"
+Sets the current position to the beginning of the directory for the
+\&\f(CW\*(C`readdir\*(C'\fR routine on DIRHANDLE.
+.Sp
+Portability issues: "rewinddir" in perlport.
+.IP "rindex STR,SUBSTR,POSITION" 4
+.IX Xref "rindex"
+.IX Item "rindex STR,SUBSTR,POSITION"
+.PD 0
+.IP "rindex STR,SUBSTR" 4
+.IX Item "rindex STR,SUBSTR"
+.PD
+Works just like \f(CW\*(C`index\*(C'\fR except that it
+returns the position of the \fIlast\fR
+occurrence of SUBSTR in STR.  If POSITION is specified, returns the
+last occurrence beginning at or before that position.
+.IP "rmdir FILENAME" 4
+.IX Xref "rmdir rd directory, remove"
+.IX Item "rmdir FILENAME"
+.PD 0
+.IP rmdir 4
+.IX Item "rmdir"
+.PD
+Deletes the directory specified by FILENAME if that directory is
+empty.  If it succeeds it returns true; otherwise it returns false and
+sets \f(CW$!\fR (errno).  If FILENAME is omitted, uses
+\&\f(CW$_\fR.
+.Sp
+To remove a directory tree recursively (\f(CW\*(C`rm \-rf\*(C'\fR on Unix) look at
+the \f(CW\*(C`rmtree\*(C'\fR function of the File::Path
+module.
+.IP s/// 4
+.IX Item "s///"
+The substitution operator.  See "Regexp Quote-Like Operators" in perlop.
+.IP "say FILEHANDLE LIST" 4
+.IX Xref "say"
+.IX Item "say FILEHANDLE LIST"
+.PD 0
+.IP "say FILEHANDLE" 4
+.IX Item "say FILEHANDLE"
+.IP "say LIST" 4
+.IX Item "say LIST"
+.IP say 4
+.IX Item "say"
+.PD
+Just like \f(CW\*(C`print\*(C'\fR, but implicitly appends a
+newline at the end of the LIST instead of any value \f(CW\*(C`$\e\*(C'\fR
+might have.  To use FILEHANDLE without a LIST to
+print the contents of \f(CW$_\fR to it, you must use a bareword
+filehandle like \f(CW\*(C`FH\*(C'\fR, not an indirect one like \f(CW$fh\fR.
+.Sp
+\&\f(CW\*(C`say\*(C'\fR is available only if the
+\&\f(CW"say"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"say"\fR feature is enabled automatically
+with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current scope.
+.IP "scalar EXPR" 4
+.IX Xref "scalar context"
+.IX Item "scalar EXPR"
+Forces EXPR to be interpreted in scalar context and returns the value
+of EXPR.
+.Sp
+.Vb 1
+\&    my @counts = ( scalar @a, scalar @b, scalar @c );
+.Ve
+.Sp
+There is no equivalent operator to force an expression to
+be interpolated in list context because in practice, this is never
+needed.  If you really wanted to do so, however, you could use
+the construction \f(CW\*(C`@{[ (some expression) ]}\*(C'\fR, but usually a simple
+\&\f(CW\*(C`(some expression)\*(C'\fR suffices.
+.Sp
+Because \f(CW\*(C`scalar\*(C'\fR is a unary operator, if you
+accidentally use a
+parenthesized list for the EXPR, this behaves as a scalar comma expression,
+evaluating all but the last element in void context and returning the final
+element evaluated in scalar context.  This is seldom what you want.
+.Sp
+The following single statement:
+.Sp
+.Vb 1
+\&    print uc(scalar(foo(), $bar)), $baz;
+.Ve
+.Sp
+is the moral equivalent of these two:
+.Sp
+.Vb 2
+\&    foo();
+\&    print(uc($bar), $baz);
+.Ve
+.Sp
+See perlop for more details on unary operators and the comma operator,
+and perldata for details on evaluating a hash in scalar context.
+.IP "seek FILEHANDLE,POSITION,WHENCE" 4
+.IX Xref "seek fseek filehandle, position"
+.IX Item "seek FILEHANDLE,POSITION,WHENCE"
+Sets FILEHANDLE's position, just like the \fBfseek\fR\|(3) call of C \f(CW\*(C`stdio\*(C'\fR.
+FILEHANDLE may be an expression whose value gives the name of the
+filehandle.  The values for WHENCE are \f(CW0\fR to set the new position
+\&\fIin bytes\fR to POSITION; \f(CW1\fR to set it to the current position plus
+POSITION; and \f(CW2\fR to set it to EOF plus POSITION, typically
+negative.  For WHENCE you may use the constants \f(CW\*(C`SEEK_SET\*(C'\fR,
+\&\f(CW\*(C`SEEK_CUR\*(C'\fR, and \f(CW\*(C`SEEK_END\*(C'\fR (start of the file, current position, end
+of the file) from the Fcntl module.  Returns \f(CW1\fR on success, false
+otherwise.
+.Sp
+Note the emphasis on bytes: even if the filehandle has been set to operate
+on characters (for example using the \f(CW:encoding(UTF\-8)\fR I/O layer), the
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, and
+\&\f(CW\*(C`sysseek\*(C'\fR
+family of functions use byte offsets, not character offsets,
+because seeking to a character offset would be very slow in a UTF\-8 file.
+.Sp
+If you want to position the file for
+\&\f(CW\*(C`sysread\*(C'\fR or
+\&\f(CW\*(C`syswrite\*(C'\fR, don't use
+\&\f(CW\*(C`seek\*(C'\fR, because buffering makes its
+effect on the file's read-write position unpredictable and non-portable.
+Use \f(CW\*(C`sysseek\*(C'\fR instead.
+.Sp
+Due to the rules and rigors of ANSI C, on some systems you have to do a
+seek whenever you switch between reading and writing.  Amongst other
+things, this may have the effect of calling stdio's \fBclearerr\fR\|(3).
+A WHENCE of \f(CW1\fR (\f(CW\*(C`SEEK_CUR\*(C'\fR) is useful for not moving the file position:
+.Sp
+.Vb 1
+\&    seek($fh, 0, 1);
+.Ve
+.Sp
+This is also useful for applications emulating \f(CW\*(C`tail \-f\*(C'\fR.  Once you hit
+EOF on your read and then sleep for a while, you (probably) have to stick in a
+dummy \f(CW\*(C`seek\*(C'\fR to reset things.  The
+\&\f(CW\*(C`seek\*(C'\fR doesn't change the position,
+but it \fIdoes\fR clear the end-of-file condition on the handle, so that the
+next \f(CW\*(C`readline FILE\*(C'\fR makes Perl try again to read something.  (We hope.)
+.Sp
+If that doesn't work (some I/O implementations are particularly
+cantankerous), you might need something like this:
+.Sp
+.Vb 8
+\&    for (;;) {
+\&        for ($curpos = tell($fh); $_ = readline($fh);
+\&             $curpos = tell($fh)) {
+\&            # search for some stuff and put it into files
+\&        }
+\&        sleep($for_a_while);
+\&        seek($fh, $curpos, 0);
+\&    }
+.Ve
+.IP "seekdir DIRHANDLE,POS" 4
+.IX Xref "seekdir"
+.IX Item "seekdir DIRHANDLE,POS"
+Sets the current position for the \f(CW\*(C`readdir\*(C'\fR
+routine on DIRHANDLE.  POS must be a value returned by
+\&\f(CW\*(C`telldir\*(C'\fR.  \f(CW\*(C`seekdir\*(C'\fR
+also has the same caveats about possible directory compaction as the
+corresponding system library routine.
+.IP "select FILEHANDLE" 4
+.IX Xref "select filehandle, default"
+.IX Item "select FILEHANDLE"
+.PD 0
+.IP select 4
+.IX Item "select"
+.PD
+Returns the currently selected filehandle.  If FILEHANDLE is supplied,
+sets the new current default filehandle for output.  This has two
+effects: first, a \f(CW\*(C`write\*(C'\fR,  \f(CW\*(C`print\*(C'\fR, or \f(CW\*(C`say\*(C'\fR without a
+filehandle default to this FILEHANDLE.  Second, references to variables
+related to output will refer to this output channel.
+.Sp
+For example, to set the top-of-form format for more than one
+output channel, you might do the following:
+.Sp
+.Vb 4
+\&    select(REPORT1);
+\&    $^ = \*(Aqreport1_top\*(Aq;
+\&    select(REPORT2);
+\&    $^ = \*(Aqreport2_top\*(Aq;
+.Ve
+.Sp
+FILEHANDLE may be an expression whose value gives the name of the
+actual filehandle.  Thus:
+.Sp
+.Vb 1
+\&    my $oldfh = select(STDERR); $| = 1; select($oldfh);
+.Ve
+.Sp
+Some programmers may prefer to think of filehandles as objects with
+methods, preferring to write the last example as:
+.Sp
+.Vb 1
+\&    STDERR\->autoflush(1);
+.Ve
+.Sp
+(Prior to Perl version 5.14, you have to \f(CW\*(C`use IO::Handle;\*(C'\fR explicitly
+first.)
+.Sp
+Whilst you can use \f(CW\*(C`select\*(C'\fR to temporarily "capture" the output of
+\&\f(CW\*(C`print\*(C'\fR like this:
+.Sp
+.Vb 2
+\&    {
+\&        my $old_handle = select $new_handle;
+\&
+\&        # This goes to $new_handle:
+\&        print "ok 1\en";
+\&        ...
+\&
+\&        select $old_handle;
+\&    }
+.Ve
+.Sp
+you might find it easier to localize the typeglob instead:
+.Sp
+.Vb 2
+\&    {
+\&        local *STDOUT = $new_handle;
+\&
+\&        print "ok 1\en";
+\&        ...
+\&    }
+.Ve
+.Sp
+The two are not exactly equivalent, but the latter might be clearer and will
+restore STDOUT if the wrapped code dies.  The difference is that in the
+former, the original STDOUT can still be accessed by explicitly using it in a
+\&\f(CW\*(C`print\*(C'\fR statement (as \f(CW\*(C`print STDOUT ...\*(C'\fR), whereas in the latter the meaning
+of the STDOUT handle itself has temporarily been changed.
+.Sp
+Portability issues: "select" in perlport.
+.IP "select RBITS,WBITS,EBITS,TIMEOUT" 4
+.IX Xref "select"
+.IX Item "select RBITS,WBITS,EBITS,TIMEOUT"
+This calls the \fBselect\fR\|(2) syscall with the bit masks specified, which
+can be constructed using \f(CW\*(C`fileno\*(C'\fR and
+\&\f(CW\*(C`vec\*(C'\fR, along these lines:
+.Sp
+.Vb 4
+\&    my $rin = my $win = my $ein = \*(Aq\*(Aq;
+\&    vec($rin, fileno(STDIN),  1) = 1;
+\&    vec($win, fileno(STDOUT), 1) = 1;
+\&    $ein = $rin | $win;
+.Ve
+.Sp
+If you want to select on many filehandles, you may wish to write a
+subroutine like this:
+.Sp
+.Vb 9
+\&    sub fhbits {
+\&        my @fhlist = @_;
+\&        my $bits = "";
+\&        for my $fh (@fhlist) {
+\&            vec($bits, fileno($fh), 1) = 1;
+\&        }
+\&        return $bits;
+\&    }
+\&    my $rin = fhbits(\e*STDIN, $tty, $mysock);
+.Ve
+.Sp
+The usual idiom is:
+.Sp
+.Vb 3
+\& my ($nfound, $timeleft) =
+\&   select(my $rout = $rin, my $wout = $win, my $eout = $ein,
+\&                                                          $timeout);
+.Ve
+.Sp
+or to block until something becomes ready just do this
+.Sp
+.Vb 2
+\& my $nfound =
+\&   select(my $rout = $rin, my $wout = $win, my $eout = $ein, undef);
+.Ve
+.Sp
+Most systems do not bother to return anything useful in \f(CW$timeleft\fR, so
+calling \f(CW\*(C`select\*(C'\fR in scalar context
+just returns \f(CW$nfound\fR.
+.Sp
+Any of the bit masks can also be \f(CW\*(C`undef\*(C'\fR.  The timeout,
+if specified, is
+in seconds, which may be fractional.  Note: not all implementations are
+capable of returning the \f(CW$timeleft\fR.  If not, they always return
+\&\f(CW$timeleft\fR equal to the supplied \f(CW$timeout\fR.
+.Sp
+You can effect a sleep of 250 milliseconds this way:
+.Sp
+.Vb 1
+\&    select(undef, undef, undef, 0.25);
+.Ve
+.Sp
+Note that whether \f(CW\*(C`select\*(C'\fR gets
+restarted after signals (say, SIGALRM) is implementation-dependent.  See
+also perlport for notes on the portability of
+\&\f(CW\*(C`select\*(C'\fR.
+.Sp
+On error, \f(CW\*(C`select\*(C'\fR behaves just
+like \fBselect\fR\|(2): it returns \f(CW\-1\fR and sets \f(CW$!\fR.
+.Sp
+On some Unixes, \fBselect\fR\|(2) may report a socket file descriptor as
+"ready for reading" even when no data is available, and thus any
+subsequent \f(CW\*(C`read\*(C'\fR would block.
+This can be avoided if you always use \f(CW\*(C`O_NONBLOCK\*(C'\fR on the socket.  See
+\&\fBselect\fR\|(2) and \fBfcntl\fR\|(2) for further details.
+.Sp
+The standard \f(CW\*(C`IO::Select\*(C'\fR module provides a
+user-friendlier interface to
+\&\f(CW\*(C`select\*(C'\fR, mostly because it does
+all the bit-mask work for you.
+.Sp
+\&\fBWARNING\fR: One should not attempt to mix buffered I/O (like
+\&\f(CW\*(C`read\*(C'\fR or
+\&\f(CW\*(C`readline\*(C'\fR) with
+\&\f(CW\*(C`select\*(C'\fR, except as permitted by
+POSIX, and even then only on POSIX systems.  You have to use
+\&\f(CW\*(C`sysread\*(C'\fR instead.
+.Sp
+Portability issues: "select" in perlport.
+.IP "semctl ID,SEMNUM,CMD,ARG" 4
+.IX Xref "semctl"
+.IX Item "semctl ID,SEMNUM,CMD,ARG"
+Calls the System V IPC function \fBsemctl\fR\|(2).  You'll probably have to say
+.Sp
+.Vb 1
+\&    use IPC::SysV;
+.Ve
+.Sp
+first to get the correct constant definitions.  If CMD is IPC_STAT or
+GETALL, then ARG must be a variable that will hold the returned
+semid_ds structure or semaphore value array.  Returns like
+\&\f(CW\*(C`ioctl\*(C'\fR:
+the undefined value for error, "\f(CW\*(C`0 but true\*(C'\fR" for zero, or the actual
+return value otherwise.  The ARG must consist of a vector of native
+short integers, which may be created with \f(CW\*(C`pack("s!",(0)x$nsem)\*(C'\fR.
+See also "SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR and \f(CW\*(C`IPC::Semaphore\*(C'\fR.
+.Sp
+Portability issues: "semctl" in perlport.
+.IP "semget KEY,NSEMS,FLAGS" 4
+.IX Xref "semget"
+.IX Item "semget KEY,NSEMS,FLAGS"
+Calls the System V IPC function \fBsemget\fR\|(2).  Returns the semaphore id, or
+the undefined value on error.  See also
+"SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR and \f(CW\*(C`IPC::Semaphore\*(C'\fR.
+.Sp
+Portability issues: "semget" in perlport.
+.IP "semop KEY,OPSTRING" 4
+.IX Xref "semop"
+.IX Item "semop KEY,OPSTRING"
+Calls the System V IPC function \fBsemop\fR\|(2) for semaphore operations
+such as signalling and waiting.  OPSTRING must be a packed array of
+semop structures.  Each semop structure can be generated with
+\&\f(CW\*(C`pack("s!3", $semnum, $semop, $semflag)\*(C'\fR.  The length of OPSTRING
+implies the number of semaphore operations.  Returns true if
+successful, false on error.  As an example, the
+following code waits on semaphore \f(CW$semnum\fR of semaphore id \f(CW$semid:\fR
+.Sp
+.Vb 2
+\&    my $semop = pack("s!3", $semnum, \-1, 0);
+\&    die "Semaphore trouble: $!\en" unless semop($semid, $semop);
+.Ve
+.Sp
+To signal the semaphore, replace \f(CW\-1\fR with \f(CW1\fR.  See also
+"SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR and \f(CW\*(C`IPC::Semaphore\*(C'\fR.
+.Sp
+Portability issues: "semop" in perlport.
+.IP "send SOCKET,MSG,FLAGS,TO" 4
+.IX Xref "send"
+.IX Item "send SOCKET,MSG,FLAGS,TO"
+.PD 0
+.IP "send SOCKET,MSG,FLAGS" 4
+.IX Item "send SOCKET,MSG,FLAGS"
+.PD
+Sends a message on a socket.  Attempts to send the scalar MSG to the SOCKET
+filehandle.  Takes the same flags as the system call of the same name.  On
+unconnected sockets, you must specify a destination to \fIsend to\fR, in which
+case it does a \fBsendto\fR\|(2) syscall.  Returns the number of characters sent,
+or the undefined value on error.  The \fBsendmsg\fR\|(2) syscall is currently
+unimplemented.  See "UDP: Message Passing" in perlipc for examples.
+.Sp
+Note that if the socket has been marked as \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`send\*(C'\fR will
+throw an exception.  The \f(CW:encoding(...)\fR layer implicitly introduces
+the \f(CW\*(C`:utf8\*(C'\fR layer.  See \f(CW\*(C`binmode\*(C'\fR.
+.IP "setpgrp PID,PGRP" 4
+.IX Xref "setpgrp group"
+.IX Item "setpgrp PID,PGRP"
+Sets the current process group for the specified PID, \f(CW0\fR for the current
+process.  Raises an exception when used on a machine that doesn't
+implement POSIX \fBsetpgid\fR\|(2) or BSD \fBsetpgrp\fR\|(2).  If the arguments
+are omitted, it defaults to \f(CW\*(C`0,0\*(C'\fR.  Note that the BSD 4.2 version of
+\&\f(CW\*(C`setpgrp\*(C'\fR does not accept any arguments, so only
+\&\f(CW\*(C`setpgrp(0,0)\*(C'\fR is portable.  See also
+\&\f(CWPOSIX::setsid()\fR.
+.Sp
+Portability issues: "setpgrp" in perlport.
+.IP "setpriority WHICH,WHO,PRIORITY" 4
+.IX Xref "setpriority priority nice renice"
+.IX Item "setpriority WHICH,WHO,PRIORITY"
+Sets the current priority for a process, a process group, or a user.
+(See \fBsetpriority\fR\|(2).)  Raises an exception when used on a machine
+that doesn't implement \fBsetpriority\fR\|(2).
+.Sp
+\&\f(CW\*(C`WHICH\*(C'\fR can be any of \f(CW\*(C`PRIO_PROCESS\*(C'\fR, \f(CW\*(C`PRIO_PGRP\*(C'\fR or \f(CW\*(C`PRIO_USER\*(C'\fR
+imported from "RESOURCE CONSTANTS" in POSIX.
+.Sp
+Portability issues: "setpriority" in perlport.
+.IP "setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL" 4
+.IX Xref "setsockopt"
+.IX Item "setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL"
+Sets the socket option requested.  Returns \f(CW\*(C`undef\*(C'\fR on
+error.  Use integer constants provided by the \f(CW\*(C`Socket\*(C'\fR module
+for
+LEVEL and OPNAME.  Values for LEVEL can also be obtained from
+getprotobyname.  OPTVAL might either be a packed string or an integer.
+An integer OPTVAL is shorthand for pack("i", OPTVAL).
+.Sp
+An example disabling Nagle's algorithm on a socket:
+.Sp
+.Vb 2
+\&    use Socket qw(IPPROTO_TCP TCP_NODELAY);
+\&    setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
+.Ve
+.Sp
+Portability issues: "setsockopt" in perlport.
+.IP "shift ARRAY" 4
+.IX Xref "shift"
+.IX Item "shift ARRAY"
+.PD 0
+.IP shift 4
+.IX Item "shift"
+.PD
+Removes and returns the \fBfirst\fR element of an array. This shortens the
+array by one and moves everything down.
+.Sp
+.Vb 2
+\&    my @arr  = (\*(Aqcat\*(Aq, \*(Aqdog\*(Aq);
+\&    my $item = shift(@arr); # \*(Aqcat\*(Aq
+\&
+\&    # @arr is now (\*(Aqdog\*(Aq);
+.Ve
+.Sp
+Returns \f(CW\*(C`undef\*(C'\fR if the array is empty.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`shift\*(C'\fR may also return \f(CW\*(C`undef\*(C'\fR if the first element in the array
+is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+.Vb 2
+\&    my @arr  = (undef, \*(Aqtwo\*(Aq, \*(Aqthree\*(Aq);
+\&    my $item = shift(@arr); # undef
+.Ve
+.Sp
+If ARRAY is omitted, \f(CW\*(C`shift\*(C'\fR operates on the \f(CW@ARGV\fR array in the main
+program, and the \f(CW@_\fR array in subroutines. \f(CW\*(C`shift\*(C'\fR will operate on the
+\&\f(CW@ARGV\fR array in \f(CW\*(C`eval STRING\*(C'\fR, \f(CW\*(C`BEGIN {}\*(C'\fR, \f(CW\*(C`INIT {}\*(C'\fR, \f(CW\*(C`CHECK {}\*(C'\fR blocks.
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`shift\*(C'\fR to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.Sp
+See also \f(CW\*(C`unshift\*(C'\fR, \f(CW\*(C`push\*(C'\fR,
+and \f(CW\*(C`pop\*(C'\fR.  \f(CW\*(C`shift\*(C'\fR and
+\&\f(CW\*(C`unshift\*(C'\fR do the same thing to the left end of
+an array that \f(CW\*(C`pop\*(C'\fR and \f(CW\*(C`push\*(C'\fR do to
+the right end.
+.IP "shmctl ID,CMD,ARG" 4
+.IX Xref "shmctl"
+.IX Item "shmctl ID,CMD,ARG"
+Calls the System V IPC function shmctl.  You'll probably have to say
+.Sp
+.Vb 1
+\&    use IPC::SysV;
+.Ve
+.Sp
+first to get the correct constant definitions.  If CMD is \f(CW\*(C`IPC_STAT\*(C'\fR,
+then ARG must be a variable that will hold the returned \f(CW\*(C`shmid_ds\*(C'\fR
+structure.  Returns like ioctl: \f(CW\*(C`undef\*(C'\fR for error; "\f(CW0\fR
+but true" for zero; and the actual return value otherwise.
+See also "SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR.
+.Sp
+Portability issues: "shmctl" in perlport.
+.IP "shmget KEY,SIZE,FLAGS" 4
+.IX Xref "shmget"
+.IX Item "shmget KEY,SIZE,FLAGS"
+Calls the System V IPC function shmget.  Returns the shared memory
+segment id, or \f(CW\*(C`undef\*(C'\fR on error.
+See also "SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR.
+.Sp
+Portability issues: "shmget" in perlport.
+.IP "shmread ID,VAR,POS,SIZE" 4
+.IX Xref "shmread shmwrite"
+.IX Item "shmread ID,VAR,POS,SIZE"
+.PD 0
+.IP "shmwrite ID,STRING,POS,SIZE" 4
+.IX Item "shmwrite ID,STRING,POS,SIZE"
+.PD
+Reads or writes the System V shared memory segment ID starting at
+position POS for size SIZE by attaching to it, copying in/out, and
+detaching from it.  When reading, VAR must be a variable that will
+hold the data read.  When writing, if STRING is too long, only SIZE
+bytes are used; if STRING is too short, nulls are written to fill out
+SIZE bytes.  Return true if successful, false on error.
+\&\f(CW\*(C`shmread\*(C'\fR taints the variable.  See also
+"SysV IPC" in perlipc and the documentation for
+\&\f(CW\*(C`IPC::SysV\*(C'\fR and the \f(CW\*(C`IPC::Shareable\*(C'\fR
+module from CPAN.
+.Sp
+Portability issues: "shmread" in perlport and "shmwrite" in perlport.
+.IP "shutdown SOCKET,HOW" 4
+.IX Xref "shutdown"
+.IX Item "shutdown SOCKET,HOW"
+Shuts down a socket connection in the manner indicated by HOW, which
+has the same interpretation as in the syscall of the same name.
+.Sp
+.Vb 3
+\&    shutdown($socket, 0);    # I/we have stopped reading data
+\&    shutdown($socket, 1);    # I/we have stopped writing data
+\&    shutdown($socket, 2);    # I/we have stopped using this socket
+.Ve
+.Sp
+This is useful with sockets when you want to tell the other
+side you're done writing but not done reading, or vice versa.
+It's also a more insistent form of close because it also
+disables the file descriptor in any forked copies in other
+processes.
+.Sp
+Returns \f(CW1\fR for success; on error, returns \f(CW\*(C`undef\*(C'\fR if
+the first argument is not a valid filehandle, or returns \f(CW0\fR and sets
+\&\f(CW$!\fR for any other failure.
+.IP "sin EXPR" 4
+.IX Xref "sin sine asin arcsine"
+.IX Item "sin EXPR"
+.PD 0
+.IP sin 4
+.IX Item "sin"
+.PD
+Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
+returns sine of \f(CW$_\fR.
+.Sp
+For the inverse sine operation, you may use the \f(CW\*(C`Math::Trig::asin\*(C'\fR
+function, or use this relation:
+.Sp
+.Vb 1
+\&    sub asin { atan2($_[0], sqrt(1 \- $_[0] * $_[0])) }
+.Ve
+.IP "sleep EXPR" 4
+.IX Xref "sleep pause"
+.IX Item "sleep EXPR"
+.PD 0
+.IP sleep 4
+.IX Item "sleep"
+.PD
+Causes the script to sleep for (integer) EXPR seconds, or forever if no
+argument is given.  Returns the integer number of seconds actually slept.
+.Sp
+EXPR should be a positive integer. If called with a negative integer,
+\&\f(CW\*(C`sleep\*(C'\fR does not sleep but instead emits a warning, sets
+\&\f(CW$!\fR (\f(CW\*(C`errno\*(C'\fR), and returns zero.
+.Sp
+If called with a non-integer, the fractional part is ignored.
+.Sp
+\&\f(CW\*(C`sleep 0\*(C'\fR is permitted, but a function call to the underlying platform
+implementation still occurs, with any side effects that may have.
+\&\f(CW\*(C`sleep 0\*(C'\fR is therefore not exactly identical to not sleeping at all.
+.Sp
+May be interrupted if the process receives a signal such as \f(CW\*(C`SIGALRM\*(C'\fR.
+.Sp
+.Vb 5
+\&    eval {
+\&        local $SIG{ALRM} = sub { die "Alarm!\en" };
+\&        sleep;
+\&    };
+\&    die $@ unless $@ eq "Alarm!\en";
+.Ve
+.Sp
+You probably cannot mix \f(CW\*(C`alarm\*(C'\fR and
+\&\f(CW\*(C`sleep\*(C'\fR calls, because \f(CW\*(C`sleep\*(C'\fR is often
+implemented using \f(CW\*(C`alarm\*(C'\fR.
+.Sp
+On some older systems, it may sleep up to a full second less than what
+you requested, depending on how it counts seconds.  Most modern systems
+always sleep the full amount.  They may appear to sleep longer than that,
+however, because your process might not be scheduled right away in a
+busy multitasking system.
+.Sp
+For delays of finer granularity than one second, the Time::HiRes
+module (from CPAN, and starting from Perl 5.8 part of the standard
+distribution) provides \f(CW\*(C`usleep\*(C'\fR.
+You may also use Perl's four-argument
+version of \f(CW\*(C`select\*(C'\fR leaving the
+first three arguments undefined, or you might be able to use the
+\&\f(CW\*(C`syscall\*(C'\fR interface to access \fBsetitimer\fR\|(2)
+if your system supports it.  See perlfaq8 for details.
+.Sp
+See also the POSIX module's \f(CW\*(C`pause\*(C'\fR function.
+.IP "socket SOCKET,DOMAIN,TYPE,PROTOCOL" 4
+.IX Xref "socket"
+.IX Item "socket SOCKET,DOMAIN,TYPE,PROTOCOL"
+Opens a socket of the specified kind and attaches it to filehandle
+SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
+the syscall of the same name.  You should \f(CW\*(C`use Socket\*(C'\fR first
+to get the proper definitions imported.  See the examples in
+"Sockets: Client/Server Communication" in perlipc.
+.Sp
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptor, as determined by the
+value of \f(CW$^F\fR.  See "$^F" in perlvar.
+.IP "socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL" 4
+.IX Xref "socketpair"
+.IX Item "socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL"
+Creates an unnamed pair of sockets in the specified domain, of the
+specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
+for the syscall of the same name.  If unimplemented, raises an exception.
+Returns true if successful.
+.Sp
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptors, as determined by the value
+of \f(CW$^F\fR.  See "$^F" in perlvar.
+.Sp
+Some systems define \f(CW\*(C`pipe\*(C'\fR in terms of
+\&\f(CW\*(C`socketpair\*(C'\fR, in
+which a call to \f(CW\*(C`pipe($rdr, $wtr)\*(C'\fR is essentially:
+.Sp
+.Vb 4
+\&    use Socket;
+\&    socketpair(my $rdr, my $wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
+\&    shutdown($rdr, 1);        # no more writing for reader
+\&    shutdown($wtr, 0);        # no more reading for writer
+.Ve
+.Sp
+See perlipc for an example of socketpair use.  Perl 5.8 and later will
+emulate socketpair using IP sockets to localhost if your system implements
+sockets but not socketpair.
+.Sp
+Portability issues: "socketpair" in perlport.
+.IP "sort SUBNAME LIST" 4
+.IX Xref "sort"
+.IX Item "sort SUBNAME LIST"
+.PD 0
+.IP "sort BLOCK LIST" 4
+.IX Item "sort BLOCK LIST"
+.IP "sort LIST" 4
+.IX Item "sort LIST"
+.PD
+In list context, this sorts the LIST and returns the sorted list value.
+In scalar context, the behaviour of \f(CW\*(C`sort\*(C'\fR is
+undefined.
+.Sp
+If SUBNAME or BLOCK is omitted, \f(CW\*(C`sort\*(C'\fRs in
+standard string comparison
+order.  If SUBNAME is specified, it gives the name of a subroutine
+that returns a numeric value less than, equal to, or greater than \f(CW0\fR,
+depending on how the elements of the list are to be ordered.  (The
+\&\f(CW\*(C`<=>\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR operators are extremely useful in such routines.)
+SUBNAME may be a scalar variable name (unsubscripted), in which case
+the value provides the name of (or a reference to) the actual
+subroutine to use.  In place of a SUBNAME, you can provide a BLOCK as
+an anonymous, in-line sort subroutine.
+.Sp
+If the subroutine's prototype is \f(CW\*(C`($$)\*(C'\fR, the elements to be compared are
+passed by reference in \f(CW@_\fR, as for a normal subroutine.
+This is slower than unprototyped subroutines, where the elements to be
+compared are passed into the subroutine as the package global variables
+\&\f(CW$a\fR and \f(CW$b\fR (see example below).
+.Sp
+If the subroutine is an XSUB, the elements to be compared are pushed on
+to the stack, the way arguments are usually passed to XSUBs.  \f(CW$a\fR and
+\&\f(CW$b\fR are not set.
+.Sp
+The values to be compared are always passed by reference and should not
+be modified.
+.Sp
+You also cannot exit out of the sort block or subroutine using any of the
+loop control operators described in perlsyn or with
+\&\f(CW\*(C`goto\*(C'\fR.
+.Sp
+When \f(CW\*(C`use locale\*(C'\fR (but not \f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR)
+is in effect, \f(CW\*(C`sort LIST\*(C'\fR sorts LIST according to the
+current collation locale.  See perllocale.
+.Sp
+\&\f(CW\*(C`sort\*(C'\fR returns aliases into the original list,
+much as a for loop's index variable aliases the list elements.  That is,
+modifying an element of a list returned by \f(CW\*(C`sort\*(C'\fR
+(for example, in a \f(CW\*(C`foreach\*(C'\fR, \f(CW\*(C`map\*(C'\fR or
+\&\f(CW\*(C`grep\*(C'\fR)
+actually modifies the element in the original list.  This is usually
+something to be avoided when writing clear code.
+.Sp
+Historically Perl has varied in whether sorting is stable by default.
+If stability matters, it can be controlled explicitly by using the
+sort pragma.
+.Sp
+Examples:
+.Sp
+.Vb 2
+\&    # sort lexically
+\&    my @articles = sort @files;
+\&
+\&    # same thing, but with explicit sort routine
+\&    my @articles = sort {$a cmp $b} @files;
+\&
+\&    # now case\-insensitively
+\&    my @articles = sort {fc($a) cmp fc($b)} @files;
+\&
+\&    # same thing in reversed order
+\&    my @articles = sort {$b cmp $a} @files;
+\&
+\&    # sort numerically ascending
+\&    my @articles = sort {$a <=> $b} @files;
+\&
+\&    # sort numerically descending
+\&    my @articles = sort {$b <=> $a} @files;
+\&
+\&    # this sorts the %age hash by value instead of key
+\&    # using an in\-line function
+\&    my @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
+\&
+\&    # sort using explicit subroutine name
+\&    sub byage {
+\&        $age{$a} <=> $age{$b};  # presuming numeric
+\&    }
+\&    my @sortedclass = sort byage @class;
+\&
+\&    sub backwards { $b cmp $a }
+\&    my @harry  = qw(dog cat x Cain Abel);
+\&    my @george = qw(gone chased yz Punished Axed);
+\&    print sort @harry;
+\&        # prints AbelCaincatdogx
+\&    print sort backwards @harry;
+\&        # prints xdogcatCainAbel
+\&    print sort @george, \*(Aqto\*(Aq, @harry;
+\&        # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
+\&
+\&    # inefficiently sort by descending numeric compare using
+\&    # the first integer after the first = sign, or the
+\&    # whole record case\-insensitively otherwise
+\&
+\&    my @new = sort {
+\&        ($b =~ /=(\ed+)/)[0] <=> ($a =~ /=(\ed+)/)[0]
+\&                            ||
+\&                    fc($a)  cmp  fc($b)
+\&    } @old;
+\&
+\&    # same thing, but much more efficiently;
+\&    # we\*(Aqll build auxiliary indices instead
+\&    # for speed
+\&    my (@nums, @caps);
+\&    for (@old) {
+\&        push @nums, ( /=(\ed+)/ ? $1 : undef );
+\&        push @caps, fc($_);
+\&    }
+\&
+\&    my @new = @old[ sort {
+\&                           $nums[$b] <=> $nums[$a]
+\&                                    ||
+\&                           $caps[$a] cmp $caps[$b]
+\&                         } 0..$#old
+\&                  ];
+\&
+\&    # same thing, but without any temps
+\&    my @new = map { $_\->[0] }
+\&           sort { $b\->[1] <=> $a\->[1]
+\&                           ||
+\&                  $a\->[2] cmp $b\->[2]
+\&           } map { [$_, /=(\ed+)/, fc($_)] } @old;
+\&
+\&    # using a prototype allows you to use any comparison subroutine
+\&    # as a sort subroutine (including other package\*(Aqs subroutines)
+\&    package Other;
+\&    sub backwards ($$) { $_[1] cmp $_[0]; }  # $a and $b are
+\&                                             # not set here
+\&    package main;
+\&    my @new = sort Other::backwards @old;
+\&
+\&    ## using a prototype with function signature
+\&    use feature \*(Aqsignatures\*(Aq;
+\&    sub function_with_signature :prototype($$) ($one, $two) {
+\&        return $one <=> $two
+\&    }
+\&
+\&    my @new = sort function_with_signature @old;
+\&
+\&    # guarantee stability
+\&    use sort \*(Aqstable\*(Aq;
+\&    my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
+.Ve
+.Sp
+Warning: syntactical care is required when sorting the list returned from
+a function.  If you want to sort the list returned by the function call
+\&\f(CWfind_records(@key)\fR, you can use:
+.Sp
+.Vb 4
+\&    my @contact = sort { $a cmp $b } find_records @key;
+\&    my @contact = sort +find_records(@key);
+\&    my @contact = sort &find_records(@key);
+\&    my @contact = sort(find_records(@key));
+.Ve
+.Sp
+If instead you want to sort the array \f(CW@key\fR with the comparison routine
+\&\f(CWfind_records()\fR then you can use:
+.Sp
+.Vb 4
+\&    my @contact = sort { find_records() } @key;
+\&    my @contact = sort find_records(@key);
+\&    my @contact = sort(find_records @key);
+\&    my @contact = sort(find_records (@key));
+.Ve
+.Sp
+\&\f(CW$a\fR and \f(CW$b\fR are set as package globals in the package the \fBsort()\fR is
+called from.  That means \f(CW$main::a\fR and \f(CW$main::b\fR (or \f(CW$::a\fR and
+\&\f(CW$::b\fR) in the \f(CW\*(C`main\*(C'\fR package, \f(CW$FooPack::a\fR and \f(CW$FooPack::b\fR in the
+\&\f(CW\*(C`FooPack\*(C'\fR package, etc.  If the sort block is in scope of a \f(CW\*(C`my\*(C'\fR or
+\&\f(CW\*(C`state\*(C'\fR declaration of \f(CW$a\fR and/or \f(CW$b\fR, you \fImust\fR spell out the full
+name of the variables in the sort block :
+.Sp
+.Vb 2
+\&   package main;
+\&   my $a = "C"; # DANGER, Will Robinson, DANGER !!!
+\&
+\&   print sort { $a cmp $b }               qw(A C E G B D F H);
+\&                                          # WRONG
+\&   sub badlexi { $a cmp $b }
+\&   print sort badlexi                     qw(A C E G B D F H);
+\&                                          # WRONG
+\&   # the above prints BACFEDGH or some other incorrect ordering
+\&
+\&   print sort { $::a cmp $::b }           qw(A C E G B D F H);
+\&                                          # OK
+\&   print sort { our $a cmp our $b }       qw(A C E G B D F H);
+\&                                          # also OK
+\&   print sort { our ($a, $b); $a cmp $b } qw(A C E G B D F H);
+\&                                          # also OK
+\&   sub lexi { our $a cmp our $b }
+\&   print sort lexi                        qw(A C E G B D F H);
+\&                                          # also OK
+\&   # the above print ABCDEFGH
+.Ve
+.Sp
+With proper care you may mix package and my (or state) \f(CW$a\fR and/or \f(CW$b\fR:
+.Sp
+.Vb 7
+\&   my $a = {
+\&      tiny   => \-2,
+\&      small  => \-1,
+\&      normal => 0,
+\&      big    => 1,
+\&      huge   => 2
+\&   };
+\&
+\&   say sort { $a\->{our $a} <=> $a\->{our $b} }
+\&       qw{ huge normal tiny small big};
+\&
+\&   # prints tinysmallnormalbighuge
+.Ve
+.Sp
+\&\f(CW$a\fR and \f(CW$b\fR are implicitly local to the \fBsort()\fR execution and regain their
+former values upon completing the sort.
+.Sp
+Sort subroutines written using \f(CW$a\fR and \f(CW$b\fR are bound to their calling
+package. It is possible, but of limited interest, to define them in a
+different package, since the subroutine must still refer to the calling
+package's \f(CW$a\fR and \f(CW$b\fR :
+.Sp
+.Vb 4
+\&   package Foo;
+\&   sub lexi { $Bar::a cmp $Bar::b }
+\&   package Bar;
+\&   ... sort Foo::lexi ...
+.Ve
+.Sp
+Use the prototyped versions (see above) for a more generic alternative.
+.Sp
+The comparison function is required to behave.  If it returns
+inconsistent results (sometimes saying \f(CW$x[1]\fR is less than \f(CW$x[2]\fR and
+sometimes saying the opposite, for example) the results are not
+well-defined.
+.Sp
+Because \f(CW\*(C`<=>\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR when either operand
+is \f(CW\*(C`NaN\*(C'\fR (not-a-number), be careful when sorting with a
+comparison function like \f(CW\*(C`$a <=> $b\*(C'\fR any lists that might contain a
+\&\f(CW\*(C`NaN\*(C'\fR.  The following example takes advantage that \f(CW\*(C`NaN != NaN\*(C'\fR to
+eliminate any \f(CW\*(C`NaN\*(C'\fRs from the input list.
+.Sp
+.Vb 1
+\&    my @result = sort { $a <=> $b } grep { $_ == $_ } @input;
+.Ve
+.Sp
+In this version of \fIperl\fR, the \f(CW\*(C`sort\*(C'\fR function is implemented via the
+mergesort algorithm.
+.IP "splice ARRAY,OFFSET,LENGTH,LIST" 4
+.IX Xref "splice"
+.IX Item "splice ARRAY,OFFSET,LENGTH,LIST"
+.PD 0
+.IP "splice ARRAY,OFFSET,LENGTH" 4
+.IX Item "splice ARRAY,OFFSET,LENGTH"
+.IP "splice ARRAY,OFFSET" 4
+.IX Item "splice ARRAY,OFFSET"
+.IP "splice ARRAY" 4
+.IX Item "splice ARRAY"
+.PD
+Removes the elements designated by OFFSET and LENGTH from an array, and
+replaces them with the elements of LIST, if any.  In list context,
+returns the elements removed from the array.  In scalar context,
+returns the last element removed, or \f(CW\*(C`undef\*(C'\fR if no
+elements are
+removed.  The array grows or shrinks as necessary.
+If OFFSET is negative then it starts that far from the end of the array.
+If LENGTH is omitted, removes everything from OFFSET onward.
+If LENGTH is negative, removes the elements from OFFSET onward
+except for \-LENGTH elements at the end of the array.
+If both OFFSET and LENGTH are omitted, removes everything.  If OFFSET is
+past the end of the array and a LENGTH was provided, Perl issues a warning,
+and splices at the end of the array.
+.Sp
+The following equivalences hold (assuming \f(CW\*(C`$#a >= $i\*(C'\fR )
+.Sp
+.Vb 5
+\&    push(@a,$x,$y)      splice(@a,@a,0,$x,$y)
+\&    pop(@a)             splice(@a,\-1)
+\&    shift(@a)           splice(@a,0,1)
+\&    unshift(@a,$x,$y)   splice(@a,0,0,$x,$y)
+\&    $a[$i] = $y         splice(@a,$i,1,$y)
+.Ve
+.Sp
+\&\f(CW\*(C`splice\*(C'\fR can be used, for example,
+to implement n\-ary queue processing:
+.Sp
+.Vb 6
+\&    sub nary_print {
+\&      my $n = shift;
+\&      while (my @next_n = splice @_, 0, $n) {
+\&        say join q{ \-\- }, @next_n;
+\&      }
+\&    }
+\&
+\&    nary_print(3, qw(a b c d e f g h));
+\&    # prints:
+\&    #   a \-\- b \-\- c
+\&    #   d \-\- e \-\- f
+\&    #   g \-\- h
+.Ve
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`splice\*(C'\fR to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.IP "split /PATTERN/,EXPR,LIMIT" 4
+.IX Xref "split"
+.IX Item "split /PATTERN/,EXPR,LIMIT"
+.PD 0
+.IP "split /PATTERN/,EXPR" 4
+.IX Item "split /PATTERN/,EXPR"
+.IP "split /PATTERN/" 4
+.IX Item "split /PATTERN/"
+.IP split 4
+.IX Item "split"
+.PD
+Splits the string EXPR into a list of strings and returns the
+list in list context, or the size of the list in scalar context.
+(Prior to Perl 5.11, it also overwrote \f(CW@_\fR with the list in
+void and scalar context. If you target old perls, beware.)
+.Sp
+If only PATTERN is given, EXPR defaults to \f(CW$_\fR.
+.Sp
+Anything in EXPR that matches PATTERN is taken to be a separator
+that separates the EXPR into substrings (called "\fIfields\fR") that
+do \fBnot\fR include the separator.  Note that a separator may be
+longer than one character or even have no characters at all (the
+empty string, which is a zero-width match).
+.Sp
+The PATTERN need not be constant; an expression may be used
+to specify a pattern that varies at runtime.
+.Sp
+If PATTERN matches the empty string, the EXPR is split at the match
+position (between characters).  As an example, the following:
+.Sp
+.Vb 1
+\&    my @x = split(/b/, "abc"); # ("a", "c")
+.Ve
+.Sp
+uses the \f(CW\*(C`b\*(C'\fR in \f(CW\*(Aqabc\*(Aq\fR as a separator to produce the list ("a", "c").
+However, this:
+.Sp
+.Vb 1
+\&    my @x = split(//, "abc"); # ("a", "b", "c")
+.Ve
+.Sp
+uses empty string matches as separators; thus, the empty string
+may be used to split EXPR into a list of its component characters.
+.Sp
+As a special case for \f(CW\*(C`split\*(C'\fR,
+the empty pattern given in
+match operator syntax (\f(CW\*(C`//\*(C'\fR)
+specifically matches the empty string, which is contrary to its usual
+interpretation as the last successful match.
+.Sp
+If PATTERN is \f(CW\*(C`/^/\*(C'\fR, then it is treated as if it used the
+multiline modifier (\f(CW\*(C`/^/m\*(C'\fR), since it
+isn't much use otherwise.
+.Sp
+\&\f(CW\*(C`/m\*(C'\fR and any of the other pattern modifiers valid for \f(CW\*(C`qr\*(C'\fR
+(summarized in "qr/STRING/msixpodualn" in perlop) may be
+specified explicitly.
+.Sp
+As another special case,
+\&\f(CW\*(C`split\*(C'\fR emulates the default
+behavior of the
+command line tool \fBawk\fR when the PATTERN is either omitted or a
+string composed of a single space character (such as \f(CW\*(Aq\ \*(Aq\fR or
+\&\f(CW"\ex20"\fR, but not e.g. \f(CW\*(C`/\ /\*(C'\fR).  In this case, any leading
+whitespace in EXPR is removed before splitting occurs, and the PATTERN is
+instead treated as if it were \f(CW\*(C`/\es+/\*(C'\fR; in particular, this means that
+\&\fIany\fR contiguous whitespace (not just a single space character) is used as
+a separator.
+.Sp
+.Vb 2
+\&    my @x = split(" ", "  Quick brown fox\en");
+\&    # ("Quick", "brown", "fox")
+\&
+\&    my @x = split(" ", "RED\etGREEN\etBLUE");
+\&    # ("RED", "GREEN", "BLUE")
+.Ve
+.Sp
+Using split in this fashion is very similar to how
+\&\f(CW\*(C`qw//\*(C'\fR works.
+.Sp
+However, this special treatment can be avoided by specifying
+the pattern \f(CW\*(C`/\ /\*(C'\fR instead of the string \f(CW"\ "\fR, thereby allowing
+only a single space character to be a separator.  In earlier Perls this
+special case was restricted to the use of a plain \f(CW"\ "\fR as the
+pattern argument to split; in Perl 5.18.0 and later this special case is
+triggered by any expression which evaluates to the simple string \f(CW"\ "\fR.
+.Sp
+As of Perl 5.28, this special-cased whitespace splitting works as expected in
+the scope of \f(CW"use\ feature\ \*(Aqunicode_strings\*(Aq"\fR. In previous versions, and outside the scope of
+that feature, it exhibits "The "Unicode Bug"" in perlunicode: characters that are
+whitespace according to Unicode rules but not according to ASCII rules can be
+treated as part of fields rather than as field separators, depending on the
+string's internal encoding.
+.Sp
+If omitted, PATTERN defaults to a single space, \f(CW"\ "\fR, triggering
+the previously described \fIawk\fR emulation.
+.Sp
+If LIMIT is specified and positive, it represents the maximum number
+of fields into which the EXPR may be split; in other words, LIMIT is
+one greater than the maximum number of times EXPR may be split.  Thus,
+the LIMIT value \f(CW1\fR means that EXPR may be split a maximum of zero
+times, producing a maximum of one field (namely, the entire value of
+EXPR).  For instance:
+.Sp
+.Vb 4
+\&    my @x = split(//, "abc", 1); # ("abc")
+\&    my @x = split(//, "abc", 2); # ("a", "bc")
+\&    my @x = split(//, "abc", 3); # ("a", "b", "c")
+\&    my @x = split(//, "abc", 4); # ("a", "b", "c")
+.Ve
+.Sp
+If LIMIT is negative, it is treated as if it were instead arbitrarily
+large; as many fields as possible are produced.
+.Sp
+If LIMIT is omitted (or, equivalently, zero), then it is usually
+treated as if it were instead negative but with the exception that
+trailing empty fields are stripped (empty leading fields are always
+preserved); if all fields are empty, then all fields are considered to
+be trailing (and are thus stripped in this case).  Thus, the following:
+.Sp
+.Vb 1
+\&    my @x = split(/,/, "a,b,c,,,"); # ("a", "b", "c")
+.Ve
+.Sp
+produces only a three element list.
+.Sp
+.Vb 1
+\&    my @x = split(/,/, "a,b,c,,,", \-1); # ("a", "b", "c", "", "", "")
+.Ve
+.Sp
+produces a six element list.
+.Sp
+In time-critical applications, it is worthwhile to avoid splitting
+into more fields than necessary.  Thus, when assigning to a list,
+if LIMIT is omitted (or zero), then LIMIT is treated as though it
+were one larger than the number of variables in the list; for the
+following, LIMIT is implicitly 3:
+.Sp
+.Vb 1
+\&    my ($login, $passwd) = split(/:/);
+.Ve
+.Sp
+Note that splitting an EXPR that evaluates to the empty string always
+produces zero fields, regardless of the LIMIT specified.
+.Sp
+An empty leading field is produced when there is a positive-width
+match at the beginning of EXPR.  For instance:
+.Sp
+.Vb 1
+\&    my @x = split(/ /, " abc"); # ("", "abc")
+.Ve
+.Sp
+splits into two elements.  However, a zero-width match at the
+beginning of EXPR never produces an empty field, so that:
+.Sp
+.Vb 1
+\&    my @x = split(//, " abc"); # (" ", "a", "b", "c")
+.Ve
+.Sp
+splits into four elements instead of five.
+.Sp
+An empty trailing field, on the other hand, is produced when there is a
+match at the end of EXPR, regardless of the length of the match
+(of course, unless a non-zero LIMIT is given explicitly, such fields are
+removed, as in the last example).  Thus:
+.Sp
+.Vb 1
+\&    my @x = split(//, " abc", \-1); # (" ", "a", "b", "c", "")
+.Ve
+.Sp
+If the PATTERN contains
+capturing groups,
+then for each separator, an additional field is produced for each substring
+captured by a group (in the order in which the groups are specified,
+as per backreferences); if any group does not
+match, then it captures the \f(CW\*(C`undef\*(C'\fR value instead of a
+substring.  Also,
+note that any such additional field is produced whenever there is a
+separator (that is, whenever a split occurs), and such an additional field
+does \fBnot\fR count towards the LIMIT.  Consider the following expressions
+evaluated in list context (each returned list is provided in the associated
+comment):
+.Sp
+.Vb 2
+\&    my @x = split(/\-|,/    , "1\-10,20", 3);
+\&    # ("1", "10", "20")
+\&
+\&    my @x = split(/(\-|,)/  , "1\-10,20", 3);
+\&    # ("1", "\-", "10", ",", "20")
+\&
+\&    my @x = split(/\-|(,)/  , "1\-10,20", 3);
+\&    # ("1", undef, "10", ",", "20")
+\&
+\&    my @x = split(/(\-)|,/  , "1\-10,20", 3);
+\&    # ("1", "\-", "10", undef, "20")
+\&
+\&    my @x = split(/(\-)|(,)/, "1\-10,20", 3);
+\&    # ("1", "\-", undef, "10", undef, ",", "20")
+.Ve
+.IP "sprintf FORMAT, LIST" 4
+.IX Xref "sprintf"
+.IX Item "sprintf FORMAT, LIST"
+Returns a string formatted by the usual
+\&\f(CW\*(C`printf\*(C'\fR conventions of the C
+library function \f(CW\*(C`sprintf\*(C'\fR.  See below for
+more details and see \fBsprintf\fR\|(3) or \fBprintf\fR\|(3) on your system for an
+explanation of the general principles.
+.Sp
+For example:
+.Sp
+.Vb 2
+\&        # Format number with up to 8 leading zeroes
+\&        my $result = sprintf("%08d", $number);
+\&
+\&        # Round number to 3 digits after decimal point
+\&        my $rounded = sprintf("%.3f", $number);
+.Ve
+.Sp
+Perl does its own \f(CW\*(C`sprintf\*(C'\fR formatting: it
+emulates the C
+function \fBsprintf\fR\|(3), but doesn't use it except for floating-point
+numbers, and even then only standard modifiers are allowed.
+Non-standard extensions in your local \fBsprintf\fR\|(3) are
+therefore unavailable from Perl.
+.Sp
+Unlike \f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`sprintf\*(C'\fR does not do what you probably mean
+when you pass it an array as your first argument.
+The array is given scalar context,
+and instead of using the 0th element of the array as the format, Perl will
+use the count of elements in the array as the format, which is almost never
+useful.
+.Sp
+Perl's \f(CW\*(C`sprintf\*(C'\fR permits the following
+universally-known conversions:
+.Sp
+.Vb 10
+\&   %%    a percent sign
+\&   %c    a character with the given number
+\&   %s    a string
+\&   %d    a signed integer, in decimal
+\&   %u    an unsigned integer, in decimal
+\&   %o    an unsigned integer, in octal
+\&   %x    an unsigned integer, in hexadecimal
+\&   %e    a floating\-point number, in scientific notation
+\&   %f    a floating\-point number, in fixed decimal notation
+\&   %g    a floating\-point number, in %e or %f notation
+.Ve
+.Sp
+In addition, Perl permits the following widely-supported conversions:
+.Sp
+.Vb 10
+\&   %X    like %x, but using upper\-case letters
+\&   %E    like %e, but using an upper\-case "E"
+\&   %G    like %g, but with an upper\-case "E" (if applicable)
+\&   %b    an unsigned integer, in binary
+\&   %B    like %b, but using an upper\-case "B" with the # flag
+\&   %p    a pointer (outputs the Perl value\*(Aqs address in hexadecimal)
+\&   %n    special: *stores* the number of characters output so far
+\&         into the next argument in the parameter list
+\&   %a    hexadecimal floating point
+\&   %A    like %a, but using upper\-case letters
+.Ve
+.Sp
+Finally, for backward (and we do mean "backward") compatibility, Perl
+permits these unnecessary but widely-supported conversions:
+.Sp
+.Vb 5
+\&   %i    a synonym for %d
+\&   %D    a synonym for %ld
+\&   %U    a synonym for %lu
+\&   %O    a synonym for %lo
+\&   %F    a synonym for %f
+.Ve
+.Sp
+Note that the number of exponent digits in the scientific notation produced
+by \f(CW%e\fR, \f(CW%E\fR, \f(CW%g\fR and \f(CW%G\fR for numbers with the modulus of the
+exponent less than 100 is system-dependent: it may be three or less
+(zero-padded as necessary).  In other words, 1.23 times ten to the
+99th may be either "1.23e99" or "1.23e099".  Similarly for \f(CW%a\fR and \f(CW%A\fR:
+the exponent or the hexadecimal digits may float: especially the
+"long doubles" Perl configuration option may cause surprises.
+.Sp
+Between the \f(CW\*(C`%\*(C'\fR and the format letter, you may specify several
+additional attributes controlling the interpretation of the format.
+In order, these are:
+.RS 4
+.IP "format parameter index" 4
+.IX Item "format parameter index"
+An explicit format parameter index, such as \f(CW\*(C`2$\*(C'\fR.  By default sprintf
+will format the next unused argument in the list, but this allows you
+to take the arguments out of order:
+.Sp
+.Vb 2
+\&  printf \*(Aq%2$d %1$d\*(Aq, 12, 34;      # prints "34 12"
+\&  printf \*(Aq%3$d %d %1$d\*(Aq, 1, 2, 3;  # prints "3 1 1"
+.Ve
+.IP flags 4
+.IX Item "flags"
+one or more of:
+.Sp
+.Vb 7
+\&   space   prefix non\-negative number with a space
+\&   +       prefix non\-negative number with a plus sign
+\&   \-       left\-justify within the field
+\&   0       use zeros, not spaces, to right\-justify
+\&   #       ensure the leading "0" for any octal,
+\&           prefix non\-zero hexadecimal with "0x" or "0X",
+\&           prefix non\-zero binary with "0b" or "0B"
+.Ve
+.Sp
+For example:
+.Sp
+.Vb 10
+\&  printf \*(Aq<% d>\*(Aq,  12;   # prints "< 12>"
+\&  printf \*(Aq<% d>\*(Aq,   0;   # prints "< 0>"
+\&  printf \*(Aq<% d>\*(Aq, \-12;   # prints "<\-12>"
+\&  printf \*(Aq<%+d>\*(Aq,  12;   # prints "<+12>"
+\&  printf \*(Aq<%+d>\*(Aq,   0;   # prints "<+0>"
+\&  printf \*(Aq<%+d>\*(Aq, \-12;   # prints "<\-12>"
+\&  printf \*(Aq<%6s>\*(Aq,  12;   # prints "<    12>"
+\&  printf \*(Aq<%\-6s>\*(Aq, 12;   # prints "<12    >"
+\&  printf \*(Aq<%06s>\*(Aq, 12;   # prints "<000012>"
+\&  printf \*(Aq<%#o>\*(Aq,  12;   # prints "<014>"
+\&  printf \*(Aq<%#x>\*(Aq,  12;   # prints "<0xc>"
+\&  printf \*(Aq<%#X>\*(Aq,  12;   # prints "<0XC>"
+\&  printf \*(Aq<%#b>\*(Aq,  12;   # prints "<0b1100>"
+\&  printf \*(Aq<%#B>\*(Aq,  12;   # prints "<0B1100>"
+.Ve
+.Sp
+When a space and a plus sign are given as the flags at once,
+the space is ignored.
+.Sp
+.Vb 2
+\&  printf \*(Aq<%+ d>\*(Aq, 12;   # prints "<+12>"
+\&  printf \*(Aq<% +d>\*(Aq, 12;   # prints "<+12>"
+.Ve
+.Sp
+When the # flag and a precision are given in the \f(CW%o\fR conversion,
+the precision is incremented if it's necessary for the leading "0".
+.Sp
+.Vb 3
+\&  printf \*(Aq<%#.5o>\*(Aq, 012;      # prints "<00012>"
+\&  printf \*(Aq<%#.5o>\*(Aq, 012345;   # prints "<012345>"
+\&  printf \*(Aq<%#.0o>\*(Aq, 0;        # prints "<0>"
+.Ve
+.IP "vector flag" 4
+.IX Item "vector flag"
+This flag tells Perl to interpret the supplied string as a vector of
+integers, one for each character in the string.  Perl applies the format to
+each integer in turn, then joins the resulting strings with a separator (a
+dot \f(CW\*(C`.\*(C'\fR by default).  This can be useful for displaying ordinal values of
+characters in arbitrary strings:
+.Sp
+.Vb 2
+\&  printf "%vd", "AB\ex{100}";           # prints "65.66.256"
+\&  printf "version is v%vd\en", $^V;     # Perl\*(Aqs version
+.Ve
+.Sp
+Put an asterisk \f(CW\*(C`*\*(C'\fR before the \f(CW\*(C`v\*(C'\fR to override the string to
+use to separate the numbers:
+.Sp
+.Vb 2
+\&  printf "address is %*vX\en", ":", $addr;   # IPv6 address
+\&  printf "bits are %0*v8b\en", " ", $bits;   # random bitstring
+.Ve
+.Sp
+You can also explicitly specify the argument number to use for
+the join string using something like \f(CW\*(C`*2$v\*(C'\fR; for example:
+.Sp
+.Vb 2
+\&  printf \*(Aq%*4$vX %*4$vX %*4$vX\*(Aq,       # 3 IPv6 addresses
+\&          @addr[1..3], ":";
+.Ve
+.IP "(minimum) width" 4
+.IX Item "(minimum) width"
+Arguments are usually formatted to be only as wide as required to
+display the given value.  You can override the width by putting
+a number here, or get the width from the next argument (with \f(CW\*(C`*\*(C'\fR)
+or from a specified argument (e.g., with \f(CW\*(C`*2$\*(C'\fR):
+.Sp
+.Vb 5
+\& printf "<%s>", "a";       # prints "<a>"
+\& printf "<%6s>", "a";      # prints "<     a>"
+\& printf "<%*s>", 6, "a";   # prints "<     a>"
+\& printf \*(Aq<%*2$s>\*(Aq, "a", 6; # prints "<     a>"
+\& printf "<%2s>", "long";   # prints "<long>" (does not truncate)
+.Ve
+.Sp
+If a field width obtained through \f(CW\*(C`*\*(C'\fR is negative, it has the same
+effect as the \f(CW\*(C`\-\*(C'\fR flag: left-justification.
+.IP "precision, or maximum width" 4
+.IX Xref "precision"
+.IX Item "precision, or maximum width"
+You can specify a precision (for numeric conversions) or a maximum
+width (for string conversions) by specifying a \f(CW\*(C`.\*(C'\fR followed by a number.
+For floating-point formats except \f(CW\*(C`g\*(C'\fR and \f(CW\*(C`G\*(C'\fR, this specifies
+how many places right of the decimal point to show (the default being 6).
+For example:
+.Sp
+.Vb 6
+\&  # these examples are subject to system\-specific variation
+\&  printf \*(Aq<%f>\*(Aq, 1;    # prints "<1.000000>"
+\&  printf \*(Aq<%.1f>\*(Aq, 1;  # prints "<1.0>"
+\&  printf \*(Aq<%.0f>\*(Aq, 1;  # prints "<1>"
+\&  printf \*(Aq<%e>\*(Aq, 10;   # prints "<1.000000e+01>"
+\&  printf \*(Aq<%.1e>\*(Aq, 10; # prints "<1.0e+01>"
+.Ve
+.Sp
+For "g" and "G", this specifies the maximum number of significant digits to
+show; for example:
+.Sp
+.Vb 11
+\&  # These examples are subject to system\-specific variation.
+\&  printf \*(Aq<%g>\*(Aq, 1;        # prints "<1>"
+\&  printf \*(Aq<%.10g>\*(Aq, 1;     # prints "<1>"
+\&  printf \*(Aq<%g>\*(Aq, 100;      # prints "<100>"
+\&  printf \*(Aq<%.1g>\*(Aq, 100;    # prints "<1e+02>"
+\&  printf \*(Aq<%.2g>\*(Aq, 100.01; # prints "<1e+02>"
+\&  printf \*(Aq<%.5g>\*(Aq, 100.01; # prints "<100.01>"
+\&  printf \*(Aq<%.4g>\*(Aq, 100.01; # prints "<100>"
+\&  printf \*(Aq<%.1g>\*(Aq, 0.0111; # prints "<0.01>"
+\&  printf \*(Aq<%.2g>\*(Aq, 0.0111; # prints "<0.011>"
+\&  printf \*(Aq<%.3g>\*(Aq, 0.0111; # prints "<0.0111>"
+.Ve
+.Sp
+For integer conversions, specifying a precision implies that the
+output of the number itself should be zero-padded to this width,
+where the 0 flag is ignored:
+.Sp
+.Vb 6
+\&  printf \*(Aq<%.6d>\*(Aq, 1;      # prints "<000001>"
+\&  printf \*(Aq<%+.6d>\*(Aq, 1;     # prints "<+000001>"
+\&  printf \*(Aq<%\-10.6d>\*(Aq, 1;   # prints "<000001    >"
+\&  printf \*(Aq<%10.6d>\*(Aq, 1;    # prints "<    000001>"
+\&  printf \*(Aq<%010.6d>\*(Aq, 1;   # prints "<    000001>"
+\&  printf \*(Aq<%+10.6d>\*(Aq, 1;   # prints "<   +000001>"
+\&
+\&  printf \*(Aq<%.6x>\*(Aq, 1;      # prints "<000001>"
+\&  printf \*(Aq<%#.6x>\*(Aq, 1;     # prints "<0x000001>"
+\&  printf \*(Aq<%\-10.6x>\*(Aq, 1;   # prints "<000001    >"
+\&  printf \*(Aq<%10.6x>\*(Aq, 1;    # prints "<    000001>"
+\&  printf \*(Aq<%010.6x>\*(Aq, 1;   # prints "<    000001>"
+\&  printf \*(Aq<%#10.6x>\*(Aq, 1;   # prints "<  0x000001>"
+.Ve
+.Sp
+For string conversions, specifying a precision truncates the string
+to fit the specified width:
+.Sp
+.Vb 2
+\&  printf \*(Aq<%.5s>\*(Aq, "truncated";   # prints "<trunc>"
+\&  printf \*(Aq<%10.5s>\*(Aq, "truncated"; # prints "<     trunc>"
+.Ve
+.Sp
+You can also get the precision from the next argument using \f(CW\*(C`.*\*(C'\fR, or from a
+specified argument (e.g., with \f(CW\*(C`.*2$\*(C'\fR):
+.Sp
+.Vb 2
+\&  printf \*(Aq<%.6x>\*(Aq, 1;       # prints "<000001>"
+\&  printf \*(Aq<%.*x>\*(Aq, 6, 1;    # prints "<000001>"
+\&
+\&  printf \*(Aq<%.*2$x>\*(Aq, 1, 6;  # prints "<000001>"
+\&
+\&  printf \*(Aq<%6.*2$x>\*(Aq, 1, 4; # prints "<  0001>"
+.Ve
+.Sp
+If a precision obtained through \f(CW\*(C`*\*(C'\fR is negative, it counts
+as having no precision at all.
+.Sp
+.Vb 4
+\&  printf \*(Aq<%.*s>\*(Aq,  7, "string";   # prints "<string>"
+\&  printf \*(Aq<%.*s>\*(Aq,  3, "string";   # prints "<str>"
+\&  printf \*(Aq<%.*s>\*(Aq,  0, "string";   # prints "<>"
+\&  printf \*(Aq<%.*s>\*(Aq, \-1, "string";   # prints "<string>"
+\&
+\&  printf \*(Aq<%.*d>\*(Aq,  1, 0;   # prints "<0>"
+\&  printf \*(Aq<%.*d>\*(Aq,  0, 0;   # prints "<>"
+\&  printf \*(Aq<%.*d>\*(Aq, \-1, 0;   # prints "<0>"
+.Ve
+.IP size 4
+.IX Item "size"
+For numeric conversions, you can specify the size to interpret the
+number as using \f(CW\*(C`l\*(C'\fR, \f(CW\*(C`h\*(C'\fR, \f(CW\*(C`V\*(C'\fR, \f(CW\*(C`q\*(C'\fR, \f(CW\*(C`L\*(C'\fR, or \f(CW\*(C`ll\*(C'\fR.  For integer
+conversions (\f(CW\*(C`d u o x X b i D U O\*(C'\fR), numbers are usually assumed to be
+whatever the default integer size is on your platform (usually 32 or 64
+bits), but you can override this to use instead one of the standard C types,
+as supported by the compiler used to build Perl:
+.Sp
+.Vb 10
+\&   hh          interpret integer as C type "char" or "unsigned
+\&               char" on Perl 5.14 or later
+\&   h           interpret integer as C type "short" or
+\&               "unsigned short"
+\&   j           interpret integer as C type "intmax_t" on Perl
+\&               5.14 or later; and prior to Perl 5.30, only with
+\&               a C99 compiler (unportable)
+\&   l           interpret integer as C type "long" or
+\&               "unsigned long"
+\&   q, L, or ll interpret integer as C type "long long",
+\&               "unsigned long long", or "quad" (typically
+\&               64\-bit integers)
+\&   t           interpret integer as C type "ptrdiff_t" on Perl
+\&               5.14 or later
+\&   z           interpret integer as C types "size_t" or
+\&               "ssize_t" on Perl 5.14 or later
+.Ve
+.Sp
+Note that, in general, using the \f(CW\*(C`l\*(C'\fR modifier (for example, when writing
+\&\f(CW"%ld"\fR or \f(CW"%lu"\fR instead of \f(CW"%d"\fR and \f(CW"%u"\fR) is unnecessary
+when used from Perl code.  Moreover, it may be harmful, for example on
+Windows 64\-bit where a long is 32\-bits.
+.Sp
+As of 5.14, none of these raises an exception if they are not supported on
+your platform.  However, if warnings are enabled, a warning of the
+\&\f(CW\*(C`printf\*(C'\fR warning class is issued on an unsupported
+conversion flag.  Should you instead prefer an exception, do this:
+.Sp
+.Vb 1
+\&    use warnings FATAL => "printf";
+.Ve
+.Sp
+If you would like to know about a version dependency before you
+start running the program, put something like this at its top:
+.Sp
+.Vb 1
+\&    use v5.14;  # for hh/j/t/z/ printf modifiers
+.Ve
+.Sp
+You can find out whether your Perl supports quads via Config:
+.Sp
+.Vb 5
+\&    use Config;
+\&    if ($Config{use64bitint} eq "define"
+\&        || $Config{longsize} >= 8) {
+\&        print "Nice quads!\en";
+\&    }
+.Ve
+.Sp
+For floating-point conversions (\f(CW\*(C`e f g E F G\*(C'\fR), numbers are usually assumed
+to be the default floating-point size on your platform (double or long double),
+but you can force "long double" with \f(CW\*(C`q\*(C'\fR, \f(CW\*(C`L\*(C'\fR, or \f(CW\*(C`ll\*(C'\fR if your
+platform supports them.  You can find out whether your Perl supports long
+doubles via Config:
+.Sp
+.Vb 2
+\&    use Config;
+\&    print "long doubles\en" if $Config{d_longdbl} eq "define";
+.Ve
+.Sp
+You can find out whether Perl considers "long double" to be the default
+floating-point size to use on your platform via Config:
+.Sp
+.Vb 4
+\&    use Config;
+\&    if ($Config{uselongdouble} eq "define") {
+\&        print "long doubles by default\en";
+\&    }
+.Ve
+.Sp
+It can also be that long doubles and doubles are the same thing:
+.Sp
+.Vb 3
+\&        use Config;
+\&        ($Config{doublesize} == $Config{longdblsize}) &&
+\&                print "doubles are long doubles\en";
+.Ve
+.Sp
+The size specifier \f(CW\*(C`V\*(C'\fR has no effect for Perl code, but is supported for
+compatibility with XS code.  It means "use the standard size for a Perl
+integer or floating-point number", which is the default.
+.IP "order of arguments" 4
+.IX Item "order of arguments"
+Normally, \f(CW\*(C`sprintf\*(C'\fR takes the next unused
+argument as the value to
+format for each format specification.  If the format specification
+uses \f(CW\*(C`*\*(C'\fR to require additional arguments, these are consumed from
+the argument list in the order they appear in the format
+specification \fIbefore\fR the value to format.  Where an argument is
+specified by an explicit index, this does not affect the normal
+order for the arguments, even when the explicitly specified index
+would have been the next argument.
+.Sp
+So:
+.Sp
+.Vb 1
+\&    printf "<%*.*s>", $a, $b, $c;
+.Ve
+.Sp
+uses \f(CW$a\fR for the width, \f(CW$b\fR for the precision, and \f(CW$c\fR
+as the value to format; while:
+.Sp
+.Vb 1
+\&  printf \*(Aq<%*1$.*s>\*(Aq, $a, $b;
+.Ve
+.Sp
+would use \f(CW$a\fR for the width and precision, and \f(CW$b\fR as the
+value to format.
+.Sp
+Here are some more examples; be aware that when using an explicit
+index, the \f(CW\*(C`$\*(C'\fR may need escaping:
+.Sp
+.Vb 5
+\& printf "%2\e$d %d\en",      12, 34;     # will print "34 12\en"
+\& printf "%2\e$d %d %d\en",   12, 34;     # will print "34 12 34\en"
+\& printf "%3\e$d %d %d\en",   12, 34, 56; # will print "56 12 34\en"
+\& printf "%2\e$*3\e$d %d\en",  12, 34,  3; # will print " 34 12\en"
+\& printf "%*1\e$.*f\en",       4,  5, 10; # will print "5.0000\en"
+.Ve
+.RE
+.RS 4
+.Sp
+If \f(CW\*(C`use locale\*(C'\fR (including \f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR)
+is in effect and \f(CW\*(C`POSIX::setlocale\*(C'\fR has been
+called,
+the character used for the decimal separator in formatted floating-point
+numbers is affected by the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale.  See perllocale
+and POSIX.
+.RE
+.IP "sqrt EXPR" 4
+.IX Xref "sqrt root square root"
+.IX Item "sqrt EXPR"
+.PD 0
+.IP sqrt 4
+.IX Item "sqrt"
+.PD
+Return the positive square root of EXPR.  If EXPR is omitted, uses
+\&\f(CW$_\fR.  Works only for non-negative operands unless you've
+loaded the \f(CW\*(C`Math::Complex\*(C'\fR module.
+.Sp
+.Vb 2
+\&    use Math::Complex;
+\&    print sqrt(\-4);    # prints 2i
+.Ve
+.IP "srand EXPR" 4
+.IX Xref "srand seed randseed"
+.IX Item "srand EXPR"
+.PD 0
+.IP srand 4
+.IX Item "srand"
+.PD
+Sets and returns the random number seed for the \f(CW\*(C`rand\*(C'\fR
+operator.
+.Sp
+The point of the function is to "seed" the \f(CW\*(C`rand\*(C'\fR
+function so that \f(CW\*(C`rand\*(C'\fR can produce a different sequence
+each time you run your program.  When called with a parameter,
+\&\f(CW\*(C`srand\*(C'\fR uses that for the seed; otherwise it
+(semi\-)randomly chooses a seed (see below).  In either case, starting with Perl 5.14,
+it returns the seed.  To signal that your code will work \fIonly\fR on Perls
+of a recent vintage:
+.Sp
+.Vb 1
+\&    use v5.14;  # so srand returns the seed
+.Ve
+.Sp
+If \f(CW\*(C`srand\*(C'\fR is not called explicitly, it is called
+implicitly without a parameter at the first use of the
+\&\f(CW\*(C`rand\*(C'\fR operator.  However, there are a few situations
+where programs are likely to want to call \f(CW\*(C`srand\*(C'\fR.  One
+is for generating predictable results, generally for testing or
+debugging.  There, you use \f(CWsrand($seed)\fR, with the same \f(CW$seed\fR each
+time.  Another case is that you may want to call \f(CW\*(C`srand\*(C'\fR
+after a \f(CW\*(C`fork\*(C'\fR to avoid child processes sharing the same seed
+value as the parent (and consequently each other).
+.Sp
+Do \fBnot\fR call \f(CWsrand()\fR (i.e., without an argument) more than once per
+process.  The internal state of the random number generator should
+contain more entropy than can be provided by any seed, so calling
+\&\f(CW\*(C`srand\*(C'\fR again actually \fIloses\fR randomness.
+.Sp
+Most implementations of \f(CW\*(C`srand\*(C'\fR take an integer and will
+silently
+truncate decimal numbers.  This means \f(CWsrand(42)\fR will usually
+produce the same results as \f(CWsrand(42.1)\fR.  To be safe, always pass
+\&\f(CW\*(C`srand\*(C'\fR an integer.
+.Sp
+A typical use of the returned seed is for a test program which has too many
+combinations to test comprehensively in the time available to it each run.  It
+can test a random subset each time, and should there be a failure, log the seed
+used for that run so that it can later be used to reproduce the same results.
+.Sp
+If the \f(CW\*(C`PERL_RAND_SEED\*(C'\fR environment variable is set to a non-negative
+integer during process startup then calls to \f(CWsrand()\fR with no
+arguments will initialize the perl random number generator with a
+consistent seed each time it is called, whether called explicitly with
+no arguments or implicitly via use of \f(CWrand()\fR. The exact seeding that
+a given \f(CW\*(C`PERL_RAND_SEED\*(C'\fR will produce is deliberately unspecified, but
+using different values for \f(CW\*(C`PERL_RAND_SEED\*(C'\fR should produce different
+results. This is intended for debugging and performance analysis and is
+only guaranteed to produce consistent results between invocations of the
+same perl executable running the same code when all other factors are
+equal. The environment variable is read only once during process
+startup, and changing it during the program flow will not affect the
+currently running process. See perlrun for more details.
+.Sp
+\&\fR\f(CB\*(C`rand\*(C'\fR\fB is not cryptographically secure.  You should not rely
+on it in security-sensitive situations.\fR  As of this writing, a
+number of third-party CPAN modules offer random number generators
+intended by their authors to be cryptographically secure,
+including: Data::Entropy, Crypt::Random, Math::Random::Secure,
+and Math::TrulyRandom.
+.IP "stat FILEHANDLE" 4
+.IX Xref "stat file, status ctime"
+.IX Item "stat FILEHANDLE"
+.PD 0
+.IP "stat EXPR" 4
+.IX Item "stat EXPR"
+.IP "stat DIRHANDLE" 4
+.IX Item "stat DIRHANDLE"
+.IP stat 4
+.IX Item "stat"
+.PD
+Returns a 13\-element list giving the status info for a file, either
+the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR.  If EXPR is
+omitted, it stats \f(CW$_\fR (not \f(CW\*(C`_\*(C'\fR!).  Returns the empty
+list if \f(CW\*(C`stat\*(C'\fR fails.  Typically
+used as follows:
+.Sp
+.Vb 3
+\&    my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
+\&        $atime,$mtime,$ctime,$blksize,$blocks)
+\&           = stat($filename);
+.Ve
+.Sp
+Not all fields are supported on all filesystem types.  Here are the
+meanings of the fields:
+.Sp
+.Vb 10
+\&  0 dev      device number of filesystem
+\&  1 ino      inode number
+\&  2 mode     file mode  (type and permissions)
+\&  3 nlink    number of (hard) links to the file
+\&  4 uid      numeric user ID of file\*(Aqs owner
+\&  5 gid      numeric group ID of file\*(Aqs owner
+\&  6 rdev     the device identifier (special files only)
+\&  7 size     total size of file, in bytes
+\&  8 atime    last access time in seconds since the epoch
+\&  9 mtime    last modify time in seconds since the epoch
+\& 10 ctime    inode change time in seconds since the epoch (*)
+\& 11 blksize  preferred I/O size in bytes for interacting with the
+\&             file (may vary from file to file)
+\& 12 blocks   actual number of system\-specific blocks allocated
+\&             on disk (often, but not always, 512 bytes each)
+.Ve
+.Sp
+(The epoch was at 00:00 January 1, 1970 GMT.)
+.Sp
+(*) Not all fields are supported on all filesystem types.  Notably, the
+ctime field is non-portable.  In particular, you cannot expect it to be a
+"creation time"; see "Files and Filesystems" in perlport for details.
+.Sp
+If \f(CW\*(C`stat\*(C'\fR is passed the special filehandle
+consisting of an underline, no stat is done, but the current contents of
+the stat structure from the last \f(CW\*(C`stat\*(C'\fR,
+\&\f(CW\*(C`lstat\*(C'\fR, or filetest are returned.  Example:
+.Sp
+.Vb 3
+\&    if (\-x $file && (($d) = stat(_)) && $d < 0) {
+\&        print "$file is executable NFS file\en";
+\&    }
+.Ve
+.Sp
+(This works on machines only for which the device number is negative
+under NFS.)
+.Sp
+On some platforms inode numbers are of a type larger than perl knows how
+to handle as integer numerical values.  If necessary, an inode number will
+be returned as a decimal string in order to preserve the entire value.
+If used in a numeric context, this will be converted to a floating-point
+numerical value, with rounding, a fate that is best avoided.  Therefore,
+you should prefer to compare inode numbers using \f(CW\*(C`eq\*(C'\fR rather than \f(CW\*(C`==\*(C'\fR.
+\&\f(CW\*(C`eq\*(C'\fR will work fine on inode numbers that are represented numerically,
+as well as those represented as strings.
+.Sp
+Because the mode contains both the file type and its permissions, you
+should mask off the file type portion and (s)printf using a \f(CW"%o"\fR
+if you want to see the real permissions.
+.Sp
+.Vb 2
+\&    my $mode = (stat($filename))[2];
+\&    printf "Permissions are %04o\en", $mode & 07777;
+.Ve
+.Sp
+In scalar context, \f(CW\*(C`stat\*(C'\fR returns a boolean value
+indicating success
+or failure, and, if successful, sets the information associated with
+the special filehandle \f(CW\*(C`_\*(C'\fR.
+.Sp
+The File::stat module provides a convenient, by-name access mechanism:
+.Sp
+.Vb 5
+\&    use File::stat;
+\&    my $sb = stat($filename);
+\&    printf "File is %s, size is %s, perm %04o, mtime %s\en",
+\&           $filename, $sb\->size, $sb\->mode & 07777,
+\&           scalar localtime $sb\->mtime;
+.Ve
+.Sp
+You can import symbolic mode constants (\f(CW\*(C`S_IF*\*(C'\fR) and functions
+(\f(CW\*(C`S_IS*\*(C'\fR) from the Fcntl module:
+.Sp
+.Vb 1
+\&    use Fcntl \*(Aq:mode\*(Aq;
+\&
+\&    my $mode = (stat($filename))[2];
+\&
+\&    my $user_rwx      = ($mode & S_IRWXU) >> 6;
+\&    my $group_read    = ($mode & S_IRGRP) >> 3;
+\&    my $other_execute =  $mode & S_IXOTH;
+\&
+\&    printf "Permissions are %04o\en", S_IMODE($mode), "\en";
+\&
+\&    my $is_setuid     =  $mode & S_ISUID;
+\&    my $is_directory  =  S_ISDIR($mode);
+.Ve
+.Sp
+You could write the last two using the \f(CW\*(C`\-u\*(C'\fR and \f(CW\*(C`\-d\*(C'\fR operators.
+Commonly available \f(CW\*(C`S_IF*\*(C'\fR constants are:
+.Sp
+.Vb 1
+\&    # Permissions: read, write, execute, for user, group, others.
+\&
+\&    S_IRWXU S_IRUSR S_IWUSR S_IXUSR
+\&    S_IRWXG S_IRGRP S_IWGRP S_IXGRP
+\&    S_IRWXO S_IROTH S_IWOTH S_IXOTH
+\&
+\&    # Setuid/Setgid/Stickiness/SaveText.
+\&    # Note that the exact meaning of these is system\-dependent.
+\&
+\&    S_ISUID S_ISGID S_ISVTX S_ISTXT
+\&
+\&    # File types.  Not all are necessarily available on
+\&    # your system.
+\&
+\&    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
+\&    S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+\&
+\&    # The following are compatibility aliases for S_IRUSR,
+\&    # S_IWUSR, and S_IXUSR.
+\&
+\&    S_IREAD S_IWRITE S_IEXEC
+.Ve
+.Sp
+and the \f(CW\*(C`S_IF*\*(C'\fR functions are
+.Sp
+.Vb 2
+\&    S_IMODE($mode)    the part of $mode containing the permission
+\&                      bits and the setuid/setgid/sticky bits
+\&
+\&    S_IFMT($mode)     the part of $mode containing the file type
+\&                      which can be bit\-anded with (for example)
+\&                      S_IFREG or with the following functions
+\&
+\&    # The operators \-f, \-d, \-l, \-b, \-c, \-p, and \-S.
+\&
+\&    S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
+\&    S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
+\&
+\&    # No direct \-X operator counterpart, but for the first one
+\&    # the \-g operator is often equivalent.  The ENFMT stands for
+\&    # record flocking enforcement, a platform\-dependent feature.
+\&
+\&    S_ISENFMT($mode) S_ISWHT($mode)
+.Ve
+.Sp
+See your native \fBchmod\fR\|(2) and \fBstat\fR\|(2) documentation for more details
+about the \f(CW\*(C`S_*\*(C'\fR constants.  To get status info for a symbolic link
+instead of the target file behind the link, use the
+\&\f(CW\*(C`lstat\*(C'\fR function.
+.Sp
+Portability issues: "stat" in perlport.
+.IP "state VARLIST" 4
+.IX Xref "state"
+.IX Item "state VARLIST"
+.PD 0
+.IP "state TYPE VARLIST" 4
+.IX Item "state TYPE VARLIST"
+.IP "state VARLIST : ATTRS" 4
+.IX Item "state VARLIST : ATTRS"
+.IP "state TYPE VARLIST : ATTRS" 4
+.IX Item "state TYPE VARLIST : ATTRS"
+.PD
+\&\f(CW\*(C`state\*(C'\fR declares a lexically scoped variable, just
+like \f(CW\*(C`my\*(C'\fR.
+However, those variables will never be reinitialized, contrary to
+lexical variables that are reinitialized each time their enclosing block
+is entered.
+See "Persistent Private Variables" in perlsub for details.
+.Sp
+If more than one variable is listed, the list must be placed in
+parentheses.  With a parenthesised list, \f(CW\*(C`undef\*(C'\fR can be
+used as a
+dummy placeholder.  However, since initialization of state variables in
+such lists is currently not possible this would serve no purpose.
+.Sp
+Redeclaring a variable in the same scope or statement will "shadow" the
+previous declaration, creating a new instance and preventing access to
+the previous one. This is usually undesired and, if warnings are enabled,
+will result in a warning in the \f(CW\*(C`shadow\*(C'\fR category.
+.Sp
+\&\f(CW\*(C`state\*(C'\fR is available only if the
+\&\f(CW"state"\fR feature is enabled or if it is
+prefixed with \f(CW\*(C`CORE::\*(C'\fR.  The
+\&\f(CW"state"\fR feature is enabled
+automatically with a \f(CW\*(C`use v5.10\*(C'\fR (or higher) declaration in the current
+scope.
+.IP "study SCALAR" 4
+.IX Xref "study"
+.IX Item "study SCALAR"
+.PD 0
+.IP study 4
+.IX Item "study"
+.PD
+At this time, \f(CW\*(C`study\*(C'\fR does nothing. This may change in the future.
+.Sp
+Prior to Perl version 5.16, it would create an inverted index of all characters
+that occurred in the given SCALAR (or \f(CW$_\fR if unspecified). When
+matching a pattern, the rarest character from the pattern would be looked up in
+this index. Rarity was based on some static frequency tables constructed from
+some C programs and English text.
+.IP "sub NAME BLOCK" 4
+.IX Xref "sub"
+.IX Item "sub NAME BLOCK"
+.PD 0
+.IP "sub NAME (PROTO) BLOCK" 4
+.IX Item "sub NAME (PROTO) BLOCK"
+.IP "sub NAME : ATTRS BLOCK" 4
+.IX Item "sub NAME : ATTRS BLOCK"
+.IP "sub NAME (PROTO) : ATTRS BLOCK" 4
+.IX Item "sub NAME (PROTO) : ATTRS BLOCK"
+.PD
+This is subroutine definition, not a real function \fIper se\fR.  Without a
+BLOCK it's just a forward declaration.  Without a NAME, it's an anonymous
+function declaration, so does return a value: the CODE ref of the closure
+just created.
+.Sp
+See perlsub and perlref for details about subroutines and
+references; see attributes and Attribute::Handlers for more
+information about attributes.
+.IP _\|_SUB_\|_ 4
+.IX Xref "__SUB__"
+.IX Item "__SUB__"
+A special token that returns a reference to the current subroutine, or
+\&\f(CW\*(C`undef\*(C'\fR outside of a subroutine.
+.Sp
+The behaviour of \f(CW\*(C`_\|_SUB_\|_\*(C'\fR within a regex code block (such
+as \f(CW\*(C`/(?{...})/\*(C'\fR) is subject to change.
+.Sp
+This token is only available under \f(CW\*(C`use v5.16\*(C'\fR or the
+\&\f(CW"current_sub"\fR feature.
+See feature.
+.IP "substr EXPR,OFFSET,LENGTH,REPLACEMENT" 4
+.IX Xref "substr substring mid left right"
+.IX Item "substr EXPR,OFFSET,LENGTH,REPLACEMENT"
+.PD 0
+.IP "substr EXPR,OFFSET,LENGTH" 4
+.IX Item "substr EXPR,OFFSET,LENGTH"
+.IP "substr EXPR,OFFSET" 4
+.IX Item "substr EXPR,OFFSET"
+.PD
+Extracts a substring out of EXPR and returns it.  First character is at
+offset zero.  If OFFSET is negative, starts
+that far back from the end of the string.  If LENGTH is omitted, returns
+everything through the end of the string.  If LENGTH is negative, leaves that
+many characters off the end of the string.
+.Sp
+.Vb 6
+\&    my $s = "The black cat climbed the green tree";
+\&    my $color  = substr $s, 4, 5;      # black
+\&    my $middle = substr $s, 4, \-11;    # black cat climbed the
+\&    my $end    = substr $s, 14;        # climbed the green tree
+\&    my $tail   = substr $s, \-4;        # tree
+\&    my $z      = substr $s, \-4, 2;     # tr
+.Ve
+.Sp
+You can use the \f(CW\*(C`substr\*(C'\fR
+function as an lvalue, in which case EXPR
+must itself be an lvalue.  If you assign something shorter than LENGTH,
+the string will shrink, and if you assign something longer than LENGTH,
+the string will grow to accommodate it.  To keep the string the same
+length, you may need to pad or chop your value using
+\&\f(CW\*(C`sprintf\*(C'\fR.
+.Sp
+If OFFSET and LENGTH specify a substring that is partly outside the
+string, only the part within the string is returned.  If the substring
+is beyond either end of the string,
+\&\f(CW\*(C`substr\*(C'\fR returns the undefined
+value and produces a warning.  When used as an lvalue, specifying a
+substring that is entirely outside the string raises an exception.
+Here's an example showing the behavior for boundary cases:
+.Sp
+.Vb 5
+\&    my $name = \*(Aqfred\*(Aq;
+\&    substr($name, 4) = \*(Aqdy\*(Aq;         # $name is now \*(Aqfreddy\*(Aq
+\&    my $null = substr $name, 6, 2;   # returns "" (no warning)
+\&    my $oops = substr $name, 7;      # returns undef, with warning
+\&    substr($name, 7) = \*(Aqgap\*(Aq;        # raises an exception
+.Ve
+.Sp
+An alternative to using
+\&\f(CW\*(C`substr\*(C'\fR as an lvalue is to
+specify the
+REPLACEMENT string as the 4th argument.  This allows you to replace
+parts of the EXPR and return what was there before in one operation,
+just as you can with
+\&\f(CW\*(C`splice\*(C'\fR.
+.Sp
+.Vb 3
+\&    my $s = "The black cat climbed the green tree";
+\&    my $z = substr $s, 14, 7, "jumped from";    # climbed
+\&    # $s is now "The black cat jumped from the green tree"
+.Ve
+.Sp
+Note that the lvalue returned by the three-argument version of
+\&\f(CW\*(C`substr\*(C'\fR acts as
+a 'magic bullet'; each time it is assigned to, it remembers which part
+of the original string is being modified; for example:
+.Sp
+.Vb 7
+\&    my $x = \*(Aq1234\*(Aq;
+\&    for (substr($x,1,2)) {
+\&        $_ = \*(Aqa\*(Aq;   print $x,"\en";    # prints 1a4
+\&        $_ = \*(Aqxyz\*(Aq; print $x,"\en";    # prints 1xyz4
+\&        $x = \*(Aq56789\*(Aq;
+\&        $_ = \*(Aqpq\*(Aq;  print $x,"\en";    # prints 5pq9
+\&    }
+.Ve
+.Sp
+With negative offsets, it remembers its position from the end of the string
+when the target string is modified:
+.Sp
+.Vb 6
+\&    my $x = \*(Aq1234\*(Aq;
+\&    for (substr($x, \-3, 2)) {
+\&        $_ = \*(Aqa\*(Aq;   print $x,"\en";    # prints 1a4, as above
+\&        $x = \*(Aqabcdefg\*(Aq;
+\&        print $_,"\en";                # prints f
+\&    }
+.Ve
+.Sp
+Prior to Perl version 5.10, the result of using an lvalue multiple times was
+unspecified.  Prior to 5.16, the result with negative offsets was
+unspecified.
+.IP "symlink OLDFILE,NEWFILE" 4
+.IX Xref "symlink link symbolic link link, symbolic"
+.IX Item "symlink OLDFILE,NEWFILE"
+Creates a new filename symbolically linked to the old filename.
+Returns \f(CW1\fR for success, \f(CW0\fR otherwise.  On systems that don't support
+symbolic links, raises an exception.  To check for that,
+use eval:
+.Sp
+.Vb 1
+\&    my $symlink_exists = eval { symlink("",""); 1 };
+.Ve
+.Sp
+Portability issues: "symlink" in perlport.
+.IP "syscall NUMBER, LIST" 4
+.IX Xref "syscall system call"
+.IX Item "syscall NUMBER, LIST"
+Calls the system call specified as the first element of the list,
+passing the remaining elements as arguments to the system call.  If
+unimplemented, raises an exception.  The arguments are interpreted
+as follows: if a given argument is numeric, the argument is passed as
+an int.  If not, the pointer to the string value is passed.  You are
+responsible to make sure a string is pre-extended long enough to
+receive any result that might be written into a string.  You can't use a
+string literal (or other read-only string) as an argument to
+\&\f(CW\*(C`syscall\*(C'\fR because Perl has to assume that any
+string pointer might be written through.  If your
+integer arguments are not literals and have never been interpreted in a
+numeric context, you may need to add \f(CW0\fR to them to force them to look
+like numbers.  This emulates the
+\&\f(CW\*(C`syswrite\*(C'\fR function (or
+vice versa):
+.Sp
+.Vb 3
+\&    require \*(Aqsyscall.ph\*(Aq;        # may need to run h2ph
+\&    my $s = "hi there\en";
+\&    syscall(SYS_write(), fileno(STDOUT), $s, length $s);
+.Ve
+.Sp
+Note that Perl supports passing of up to only 14 arguments to your syscall,
+which in practice should (usually) suffice.
+.Sp
+Syscall returns whatever value returned by the system call it calls.
+If the system call fails, \f(CW\*(C`syscall\*(C'\fR returns
+\&\f(CW\-1\fR and sets \f(CW$!\fR (errno).
+Note that some system calls \fIcan\fR legitimately return \f(CW\-1\fR.  The proper
+way to handle such calls is to assign \f(CW\*(C`$! = 0\*(C'\fR before the call, then
+check the value of \f(CW$!\fR if
+\&\f(CW\*(C`syscall\*(C'\fR returns \f(CW\-1\fR.
+.Sp
+There's a problem with \f(CW\*(C`syscall(SYS_pipe())\*(C'\fR: it returns the file
+number of the read end of the pipe it creates, but there is no way
+to retrieve the file number of the other end.  You can avoid this
+problem by using \f(CW\*(C`pipe\*(C'\fR instead.
+.Sp
+Portability issues: "syscall" in perlport.
+.IP "sysopen FILEHANDLE,FILENAME,MODE" 4
+.IX Xref "sysopen"
+.IX Item "sysopen FILEHANDLE,FILENAME,MODE"
+.PD 0
+.IP "sysopen FILEHANDLE,FILENAME,MODE,PERMS" 4
+.IX Item "sysopen FILEHANDLE,FILENAME,MODE,PERMS"
+.PD
+Opens the file whose filename is given by FILENAME, and associates it with
+FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the real
+filehandle wanted; an undefined scalar will be suitably autovivified.  This
+function calls the underlying operating system's \fBopen\fR\|(2) function with the
+parameters FILENAME, MODE, and PERMS.
+.Sp
+Returns true on success and \f(CW\*(C`undef\*(C'\fR otherwise.
+.Sp
+PerlIO layers will be applied to the handle the same way they would in an
+\&\f(CW\*(C`open\*(C'\fR call that does not specify layers. That is,
+the current value of \f(CW\*(C`${^OPEN}\*(C'\fR as set by the open
+pragma in a lexical scope, or the \f(CW\*(C`\-C\*(C'\fR commandline option or \f(CW\*(C`PERL_UNICODE\*(C'\fR
+environment variable in the main program scope, falling back to the platform
+defaults as described in "Defaults and how to override them" in PerlIO. If you
+want to remove any layers that may transform the byte stream, use
+\&\f(CW\*(C`binmode\*(C'\fR after opening it.
+.Sp
+The possible values and flag bits of the MODE parameter are
+system-dependent; they are available via the standard module
+\&\f(CW\*(C`Fcntl\*(C'\fR.  See the documentation of your operating system's
+\&\fBopen\fR\|(2) syscall to see
+which values and flag bits are available.  You may combine several flags
+using the \f(CW\*(C`|\*(C'\fR\-operator.
+.Sp
+Some of the most common values are \f(CW\*(C`O_RDONLY\*(C'\fR for opening the file in
+read-only mode, \f(CW\*(C`O_WRONLY\*(C'\fR for opening the file in write-only mode,
+and \f(CW\*(C`O_RDWR\*(C'\fR for opening the file in read-write mode.
+.IX Xref "O_RDONLY O_RDWR O_WRONLY"
+.Sp
+For historical reasons, some values work on almost every system
+supported by Perl: 0 means read-only, 1 means write-only, and 2
+means read/write.  We know that these values do \fInot\fR work under
+OS/390; you probably don't want to use them in new code.
+.Sp
+If the file named by FILENAME does not exist and the
+\&\f(CW\*(C`open\*(C'\fR call creates
+it (typically because MODE includes the \f(CW\*(C`O_CREAT\*(C'\fR flag), then the value of
+PERMS specifies the permissions of the newly created file.  If you omit
+the PERMS argument to \f(CW\*(C`sysopen\*(C'\fR,
+Perl uses the octal value \f(CW0666\fR.
+These permission values need to be in octal, and are modified by your
+process's current \f(CW\*(C`umask\*(C'\fR.
+.IX Xref "O_CREAT"
+.Sp
+In many systems the \f(CW\*(C`O_EXCL\*(C'\fR flag is available for opening files in
+exclusive mode.  This is \fBnot\fR locking: exclusiveness means here that
+if the file already exists,
+\&\f(CW\*(C`sysopen\*(C'\fR fails.  \f(CW\*(C`O_EXCL\*(C'\fR may
+not work
+on network filesystems, and has no effect unless the \f(CW\*(C`O_CREAT\*(C'\fR flag
+is set as well.  Setting \f(CW\*(C`O_CREAT|O_EXCL\*(C'\fR prevents the file from
+being opened if it is a symbolic link.  It does not protect against
+symbolic links in the file's path.
+.IX Xref "O_EXCL"
+.Sp
+Sometimes you may want to truncate an already-existing file.  This
+can be done using the \f(CW\*(C`O_TRUNC\*(C'\fR flag.  The behavior of
+\&\f(CW\*(C`O_TRUNC\*(C'\fR with \f(CW\*(C`O_RDONLY\*(C'\fR is undefined.
+.IX Xref "O_TRUNC"
+.Sp
+You should seldom if ever use \f(CW0644\fR as argument to
+\&\f(CW\*(C`sysopen\*(C'\fR, because
+that takes away the user's option to have a more permissive umask.
+Better to omit it.  See \f(CW\*(C`umask\*(C'\fR for more on this.
+.Sp
+This function has no direct relation to the usage of
+\&\f(CW\*(C`sysread\*(C'\fR,
+\&\f(CW\*(C`syswrite\*(C'\fR,
+or \f(CW\*(C`sysseek\*(C'\fR.  A handle opened with
+this function can be used with buffered IO just as one opened with
+\&\f(CW\*(C`open\*(C'\fR can be used with unbuffered IO.
+.Sp
+Note that under Perls older than 5.8.0,
+\&\f(CW\*(C`sysopen\*(C'\fR depends on the
+\&\fBfdopen\fR\|(3) C library function.  On many Unix systems, \fBfdopen\fR\|(3) is known
+to fail when file descriptors exceed a certain value, typically 255.  If
+you need more file descriptors than that, consider using the
+\&\f(CW\*(C`POSIX::open\*(C'\fR function.  For Perls 5.8.0 and later,
+PerlIO is (most often) the default.
+.Sp
+See perlopentut for a kinder, gentler explanation of opening files.
+.Sp
+Portability issues: "sysopen" in perlport.
+.IP "sysread FILEHANDLE,SCALAR,LENGTH,OFFSET" 4
+.IX Xref "sysread"
+.IX Item "sysread FILEHANDLE,SCALAR,LENGTH,OFFSET"
+.PD 0
+.IP "sysread FILEHANDLE,SCALAR,LENGTH" 4
+.IX Item "sysread FILEHANDLE,SCALAR,LENGTH"
+.PD
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE, using \fBread\fR\|(2).  It bypasses any PerlIO layers
+including buffered IO (but is affected by the presence of the \f(CW\*(C`:utf8\*(C'\fR
+layer as described later), so mixing this with other kinds of reads,
+\&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`write\*(C'\fR,
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, or \f(CW\*(C`eof\*(C'\fR can cause
+confusion because the
+\&\f(CW\*(C`:perlio\*(C'\fR or \f(CW\*(C`:crlf\*(C'\fR layers usually buffer data.  Returns the number of
+bytes actually read, \f(CW0\fR at end of file, or undef if there was an
+error (in the latter case \f(CW$!\fR is also set).  SCALAR will
+be grown or
+shrunk so that the last byte actually read is the last byte of the
+scalar after the read.
+.Sp
+An OFFSET may be specified to place the read data at some place in the
+string other than the beginning.  A negative OFFSET specifies
+placement at that many characters counting backwards from the end of
+the string.  A positive OFFSET greater than the length of SCALAR
+results in the string being padded to the required size with \f(CW"\e0"\fR
+bytes before the result of the read is appended.
+.Sp
+There is no \fBsyseof()\fR function, which is ok, since
+\&\f(CW\*(C`eof\*(C'\fR doesn't work well on device files (like ttys)
+anyway.  Use \f(CW\*(C`sysread\*(C'\fR and
+check for a return value of 0 to decide whether you're done.
+.Sp
+Note that if the filehandle has been marked as \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`sysread\*(C'\fR will
+throw an exception.  The \f(CW:encoding(...)\fR layer implicitly
+introduces the \f(CW\*(C`:utf8\*(C'\fR layer.  See
+\&\f(CW\*(C`binmode\*(C'\fR,
+\&\f(CW\*(C`open\*(C'\fR, and the open pragma.
+.IP "sysseek FILEHANDLE,POSITION,WHENCE" 4
+.IX Xref "sysseek lseek"
+.IX Item "sysseek FILEHANDLE,POSITION,WHENCE"
+Sets FILEHANDLE's system position \fIin bytes\fR using \fBlseek\fR\|(2).  FILEHANDLE may
+be an expression whose value gives the name of the filehandle.  The values
+for WHENCE are \f(CW0\fR to set the new position to POSITION; \f(CW1\fR to set it
+to the current position plus POSITION; and \f(CW2\fR to set it to EOF plus
+POSITION, typically negative.
+.Sp
+Note the emphasis on bytes: even if the filehandle has been set to operate
+on characters (for example using the \f(CW:encoding(UTF\-8)\fR I/O layer), the
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, and
+\&\f(CW\*(C`sysseek\*(C'\fR
+family of functions use byte offsets, not character offsets,
+because seeking to a character offset would be very slow in a UTF\-8 file.
+.Sp
+\&\f(CW\*(C`sysseek\*(C'\fR bypasses normal
+buffered IO, so mixing it with reads other than
+\&\f(CW\*(C`sysread\*(C'\fR (for example
+\&\f(CW\*(C`readline\*(C'\fR or
+\&\f(CW\*(C`read\*(C'\fR),
+\&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`write\*(C'\fR,
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, or \f(CW\*(C`eof\*(C'\fR may cause
+confusion.
+.Sp
+For WHENCE, you may also use the constants \f(CW\*(C`SEEK_SET\*(C'\fR, \f(CW\*(C`SEEK_CUR\*(C'\fR,
+and \f(CW\*(C`SEEK_END\*(C'\fR (start of the file, current position, end of the file)
+from the Fcntl module.  Use of the constants is also more portable
+than relying on 0, 1, and 2.  For example to define a "systell" function:
+.Sp
+.Vb 2
+\&    use Fcntl \*(AqSEEK_CUR\*(Aq;
+\&    sub systell { sysseek($_[0], 0, SEEK_CUR) }
+.Ve
+.Sp
+Returns the new position, or the undefined value on failure.  A position
+of zero is returned as the string \f(CW"0 but true"\fR; thus
+\&\f(CW\*(C`sysseek\*(C'\fR returns
+true on success and false on failure, yet you can still easily determine
+the new position.
+.IP "system LIST" 4
+.IX Xref "system shell"
+.IX Item "system LIST"
+.PD 0
+.IP "system PROGRAM LIST" 4
+.IX Item "system PROGRAM LIST"
+.PD
+Does exactly the same thing as \f(CW\*(C`exec\*(C'\fR, except that a fork is
+done first and the parent process waits for the child process to
+exit.  Note that argument processing varies depending on the
+number of arguments.  If there is more than one argument in LIST,
+or if LIST is an array with more than one value, starts the program
+given by the first element of the list with arguments given by the
+rest of the list.  If there is only one scalar argument, the argument
+is checked for shell metacharacters, and if there are any, the
+entire argument is passed to the system's command shell for parsing
+(this is \f(CW\*(C`/bin/sh \-c\*(C'\fR on Unix platforms, but varies on other
+platforms).  If there are no shell metacharacters in the argument,
+it is split into words and passed directly to \f(CW\*(C`execvp\*(C'\fR, which is
+more efficient.  On Windows, only the \f(CW\*(C`system PROGRAM LIST\*(C'\fR syntax will
+reliably avoid using the shell; \f(CW\*(C`system LIST\*(C'\fR, even with more than one
+element, will fall back to the shell if the first spawn fails.
+.Sp
+Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see perlport).  To be safe, you may need
+to set \f(CW$|\fR (\f(CW$AUTOFLUSH\fR in English)
+or call the \f(CW\*(C`autoflush\*(C'\fR method of \f(CW\*(C`IO::Handle\*(C'\fR
+on any open handles.
+.Sp
+The return value is the exit status of the program as returned by the
+\&\f(CW\*(C`wait\*(C'\fR call.  To get the actual exit value, shift right by
+eight (see below).  See also \f(CW\*(C`exec\*(C'\fR.  This is \fInot\fR what
+you want to use to capture the output from a command; for that you
+should use merely backticks or
+\&\f(CW\*(C`qx//\*(C'\fR, as described in
+"`STRING`" in perlop.  Return value of \-1 indicates a failure to start
+the program or an error of the \fBwait\fR\|(2) system call (inspect
+\&\f(CW$!\fR for the reason).
+.Sp
+If you'd like to make \f(CW\*(C`system\*(C'\fR (and many other bits of
+Perl) die on error, have a look at the autodie pragma.
+.Sp
+Like \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`system\*(C'\fR allows you to lie
+to a program about its name if you use the \f(CW\*(C`system PROGRAM LIST\*(C'\fR
+syntax.  Again, see \f(CW\*(C`exec\*(C'\fR.
+.Sp
+Since \f(CW\*(C`SIGINT\*(C'\fR and \f(CW\*(C`SIGQUIT\*(C'\fR are ignored during the execution of
+\&\f(CW\*(C`system\*(C'\fR, if you expect your program to terminate on
+receipt of these signals you will need to arrange to do so yourself
+based on the return value.
+.Sp
+.Vb 3
+\&    my @args = ("command", "arg1", "arg2");
+\&    system(@args) == 0
+\&        or die "system @args failed: $?";
+.Ve
+.Sp
+If you'd like to manually inspect \f(CW\*(C`system\*(C'\fR's failure,
+you can check all possible failure modes by inspecting
+\&\f(CW$?\fR like this:
+.Sp
+.Vb 10
+\&    if ($? == \-1) {
+\&        print "failed to execute: $!\en";
+\&    }
+\&    elsif ($? & 127) {
+\&        printf "child died with signal %d, %s coredump\en",
+\&            ($? & 127),  ($? & 128) ? \*(Aqwith\*(Aq : \*(Aqwithout\*(Aq;
+\&    }
+\&    else {
+\&        printf "child exited with value %d\en", $? >> 8;
+\&    }
+.Ve
+.Sp
+Alternatively, you may inspect the value of
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR with the
+\&\f(CW\*(C`W*()\*(C'\fR calls from the POSIX module.
+.Sp
+When \f(CW\*(C`system\*(C'\fR's arguments are executed indirectly by
+the shell, results and return codes are subject to its quirks.
+See "`STRING`" in perlop and \f(CW\*(C`exec\*(C'\fR for details.
+.Sp
+Since \f(CW\*(C`system\*(C'\fR does a \f(CW\*(C`fork\*(C'\fR and
+\&\f(CW\*(C`wait\*(C'\fR it may affect a \f(CW\*(C`SIGCHLD\*(C'\fR handler.  See perlipc for
+details.
+.Sp
+Portability issues: "system" in perlport.
+.IP "syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET" 4
+.IX Xref "syswrite"
+.IX Item "syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET"
+.PD 0
+.IP "syswrite FILEHANDLE,SCALAR,LENGTH" 4
+.IX Item "syswrite FILEHANDLE,SCALAR,LENGTH"
+.IP "syswrite FILEHANDLE,SCALAR" 4
+.IX Item "syswrite FILEHANDLE,SCALAR"
+.PD
+Attempts to write LENGTH bytes of data from variable SCALAR to the
+specified FILEHANDLE, using \fBwrite\fR\|(2).  If LENGTH is
+not specified, writes whole SCALAR.  It bypasses any PerlIO layers
+including buffered IO (but is affected by the presence of the \f(CW\*(C`:utf8\*(C'\fR
+layer as described later), so
+mixing this with reads (other than \f(CW\*(C`sysread)\*(C'\fR),
+\&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`write\*(C'\fR,
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, or \f(CW\*(C`eof\*(C'\fR may cause
+confusion because the \f(CW\*(C`:perlio\*(C'\fR and \f(CW\*(C`:crlf\*(C'\fR layers usually buffer data.
+Returns the number of bytes actually written, or \f(CW\*(C`undef\*(C'\fR
+if there was an error (in this case the errno variable
+\&\f(CW$!\fR is also set).  If the LENGTH is greater than the
+data available in the SCALAR after the OFFSET, only as much data as is
+available will be written.
+.Sp
+An OFFSET may be specified to write the data from some part of the
+string other than the beginning.  A negative OFFSET specifies writing
+that many characters counting backwards from the end of the string.
+If SCALAR is of length zero, you can only use an OFFSET of 0.
+.Sp
+\&\fBWARNING\fR: If the filehandle is marked \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR will raise an exception.
+The \f(CW:encoding(...)\fR layer implicitly introduces the \f(CW\*(C`:utf8\*(C'\fR layer.
+Alternately, if the handle is not marked with an encoding but you
+attempt to write characters with code points over 255, raises an exception.
+See \f(CW\*(C`binmode\*(C'\fR,
+\&\f(CW\*(C`open\*(C'\fR, and the open pragma.
+.IP "tell FILEHANDLE" 4
+.IX Xref "tell"
+.IX Item "tell FILEHANDLE"
+.PD 0
+.IP tell 4
+.IX Item "tell"
+.PD
+Returns the current position \fIin bytes\fR for FILEHANDLE, or \-1 on
+error.  FILEHANDLE may be an expression whose value gives the name of
+the actual filehandle.  If FILEHANDLE is omitted, assumes the file
+last read.
+.Sp
+Note the emphasis on bytes: even if the filehandle has been set to operate
+on characters (for example using the \f(CW:encoding(UTF\-8)\fR I/O layer), the
+\&\f(CW\*(C`seek\*(C'\fR,
+\&\f(CW\*(C`tell\*(C'\fR, and
+\&\f(CW\*(C`sysseek\*(C'\fR
+family of functions use byte offsets, not character offsets,
+because seeking to a character offset would be very slow in a UTF\-8 file.
+.Sp
+The return value of \f(CW\*(C`tell\*(C'\fR for the standard streams
+like the STDIN depends on the operating system: it may return \-1 or
+something else.  \f(CW\*(C`tell\*(C'\fR on pipes, fifos, and
+sockets usually returns \-1.
+.Sp
+There is no \f(CW\*(C`systell\*(C'\fR function.  Use
+\&\f(CW\*(C`sysseek($fh, 0, 1)\*(C'\fR for that.
+.Sp
+Do not use \f(CW\*(C`tell\*(C'\fR (or other buffered I/O
+operations) on a filehandle that has been manipulated by
+\&\f(CW\*(C`sysread\*(C'\fR,
+\&\f(CW\*(C`syswrite\*(C'\fR, or
+\&\f(CW\*(C`sysseek\*(C'\fR.  Those functions
+ignore the buffering, while \f(CW\*(C`tell\*(C'\fR does not.
+.IP "telldir DIRHANDLE" 4
+.IX Xref "telldir"
+.IX Item "telldir DIRHANDLE"
+Returns the current position of the \f(CW\*(C`readdir\*(C'\fR
+routines on DIRHANDLE.  Value may be given to
+\&\f(CW\*(C`seekdir\*(C'\fR to access a particular location in
+a directory.  \f(CW\*(C`telldir\*(C'\fR has the same caveats
+about possible directory compaction as the corresponding system library
+routine.
+.IP "tie VARIABLE,CLASSNAME,LIST" 4
+.IX Xref "tie"
+.IX Item "tie VARIABLE,CLASSNAME,LIST"
+This function binds a variable to a package class that will provide the
+implementation for the variable.  VARIABLE is the name of the variable
+to be enchanted.  CLASSNAME is the name of a class implementing objects
+of correct type.  Any additional arguments are passed to the
+appropriate constructor
+method of the class (meaning \f(CW\*(C`TIESCALAR\*(C'\fR, \f(CW\*(C`TIEHANDLE\*(C'\fR, \f(CW\*(C`TIEARRAY\*(C'\fR,
+or \f(CW\*(C`TIEHASH\*(C'\fR).  Typically these are arguments such as might be passed
+to the \fBdbm_open\fR\|(3) function of C.  The object returned by the
+constructor is also returned by the
+\&\f(CW\*(C`tie\*(C'\fR function, which would be useful
+if you want to access other methods in CLASSNAME.
+.Sp
+Note that functions such as \f(CW\*(C`keys\*(C'\fR and
+\&\f(CW\*(C`values\*(C'\fR may return huge lists when used on large
+objects, like DBM files.  You may prefer to use the \f(CW\*(C`each\*(C'\fR function to iterate over such.  Example:
+.Sp
+.Vb 6
+\&    # print out history file offsets
+\&    use NDBM_File;
+\&    tie(my %HIST, \*(AqNDBM_File\*(Aq, \*(Aq/usr/lib/news/history\*(Aq, 1, 0);
+\&    while (my ($key,$val) = each %HIST) {
+\&        print $key, \*(Aq = \*(Aq, unpack(\*(AqL\*(Aq, $val), "\en";
+\&    }
+.Ve
+.Sp
+A class implementing a hash should have the following methods:
+.Sp
+.Vb 11
+\&    TIEHASH classname, LIST
+\&    FETCH this, key
+\&    STORE this, key, value
+\&    DELETE this, key
+\&    CLEAR this
+\&    EXISTS this, key
+\&    FIRSTKEY this
+\&    NEXTKEY this, lastkey
+\&    SCALAR this
+\&    DESTROY this
+\&    UNTIE this
+.Ve
+.Sp
+A class implementing an ordinary array should have the following methods:
+.Sp
+.Vb 10
+\&    TIEARRAY classname, LIST
+\&    FETCH this, key
+\&    STORE this, key, value
+\&    FETCHSIZE this
+\&    STORESIZE this, count
+\&    CLEAR this
+\&    PUSH this, LIST
+\&    POP this
+\&    SHIFT this
+\&    UNSHIFT this, LIST
+\&    SPLICE this, offset, length, LIST
+\&    EXTEND this, count
+\&    DELETE this, key
+\&    EXISTS this, key
+\&    DESTROY this
+\&    UNTIE this
+.Ve
+.Sp
+A class implementing a filehandle should have the following methods:
+.Sp
+.Vb 10
+\&    TIEHANDLE classname, LIST
+\&    READ this, scalar, length, offset
+\&    READLINE this
+\&    GETC this
+\&    WRITE this, scalar, length, offset
+\&    PRINT this, LIST
+\&    PRINTF this, format, LIST
+\&    BINMODE this
+\&    EOF this
+\&    FILENO this
+\&    SEEK this, position, whence
+\&    TELL this
+\&    OPEN this, mode, LIST
+\&    CLOSE this
+\&    DESTROY this
+\&    UNTIE this
+.Ve
+.Sp
+A class implementing a scalar should have the following methods:
+.Sp
+.Vb 5
+\&    TIESCALAR classname, LIST
+\&    FETCH this,
+\&    STORE this, value
+\&    DESTROY this
+\&    UNTIE this
+.Ve
+.Sp
+Not all methods indicated above need be implemented.  See perltie,
+Tie::Hash, Tie::Array, Tie::Scalar, and Tie::Handle.
+.Sp
+Unlike \f(CW\*(C`dbmopen\*(C'\fR, the
+\&\f(CW\*(C`tie\*(C'\fR function will not
+\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR a
+module for you; you need to do that explicitly yourself.  See DB_File
+or the Config module for interesting
+\&\f(CW\*(C`tie\*(C'\fR implementations.
+.Sp
+For further details see perltie, \f(CW\*(C`tied\*(C'\fR.
+.IP "tied VARIABLE" 4
+.IX Xref "tied"
+.IX Item "tied VARIABLE"
+Returns a reference to the object underlying VARIABLE (the same value
+that was originally returned by the
+\&\f(CW\*(C`tie\*(C'\fR call that bound the variable
+to a package.)  Returns the undefined value if VARIABLE isn't tied to a
+package.
+.IP time 4
+.IX Xref "time epoch"
+.IX Item "time"
+Returns the number of non-leap seconds since whatever time the system
+considers to be the epoch, suitable for feeding to
+\&\f(CW\*(C`gmtime\*(C'\fR and \f(CW\*(C`localtime\*(C'\fR.  On most
+systems the epoch is 00:00:00 UTC, January 1, 1970;
+a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
+1904 in the current local time zone for its epoch.
+.Sp
+For measuring time in better granularity than one second, use the
+Time::HiRes module from Perl 5.8 onwards (or from CPAN before then), or,
+if you have \fBgettimeofday\fR\|(2), you may be able to use the
+\&\f(CW\*(C`syscall\*(C'\fR interface of Perl.  See perlfaq8
+for details.
+.Sp
+For date and time processing look at the many related modules on CPAN.
+For a comprehensive date and time representation look at the
+DateTime module.
+.IP times 4
+.IX Xref "times"
+.IX Item "times"
+Returns a four-element list giving the user and system times in
+seconds for this process and any exited children of this process.
+.Sp
+.Vb 1
+\&    my ($user,$system,$cuser,$csystem) = times;
+.Ve
+.Sp
+In scalar context, \f(CW\*(C`times\*(C'\fR returns \f(CW$user\fR.
+.Sp
+Children's times are only included for terminated children.
+.Sp
+Portability issues: "times" in perlport.
+.IP tr/// 4
+.IX Item "tr///"
+The transliteration operator.  Same as
+\&\f(CW\*(C`y///\*(C'\fR.  See
+"Quote-Like Operators" in perlop.
+.IP "truncate FILEHANDLE,LENGTH" 4
+.IX Xref "truncate"
+.IX Item "truncate FILEHANDLE,LENGTH"
+.PD 0
+.IP "truncate EXPR,LENGTH" 4
+.IX Item "truncate EXPR,LENGTH"
+.PD
+Truncates the file opened on FILEHANDLE, or named by EXPR, to the
+specified length.  Raises an exception if truncate isn't implemented
+on your system.  Returns true if successful, \f(CW\*(C`undef\*(C'\fR on
+error.
+.Sp
+The behavior is undefined if LENGTH is greater than the length of the
+file.
+.Sp
+The position in the file of FILEHANDLE is left unchanged.  You may want to
+call seek before writing to the
+file.
+.Sp
+Portability issues: "truncate" in perlport.
+.IP "uc EXPR" 4
+.IX Xref "uc uppercase toupper"
+.IX Item "uc EXPR"
+.PD 0
+.IP uc 4
+.IX Item "uc"
+.PD
+Returns an uppercased version of EXPR.  If EXPR is omitted, uses
+\&\f(CW$_\fR.
+.Sp
+.Vb 1
+\&    my $str = uc("Perl is GREAT"); # "PERL IS GREAT"
+.Ve
+.Sp
+This function behaves the same way under various pragmas, such as in a locale,
+as \f(CW\*(C`lc\*(C'\fR does.
+.Sp
+If you want titlecase mapping on initial letters see
+\&\f(CW\*(C`ucfirst\*(C'\fR instead.
+.Sp
+\&\fBNote:\fR This is the internal function implementing the
+\&\f(CW\*(C`\eU\*(C'\fR escape in double-quoted
+strings.
+.Sp
+.Vb 1
+\&    my $str = "Perl is \eUgreat\eE"; # "Perl is GREAT"
+.Ve
+.IP "ucfirst EXPR" 4
+.IX Xref "ucfirst uppercase"
+.IX Item "ucfirst EXPR"
+.PD 0
+.IP ucfirst 4
+.IX Item "ucfirst"
+.PD
+Returns the value of EXPR with the \fBfirst\fR character in uppercase
+(Unicode calls this titlecase). If EXPR is omitted, \f(CW\*(C`ucfirst\*(C'\fR uses \f(CW$_\fR.
+.Sp
+.Vb 1
+\&    my $str = ucfirst("hello world!"); # "Hello world!"
+.Ve
+.Sp
+This function behaves the same way under various pragmas, such as in a locale,
+as \f(CW\*(C`lc\*(C'\fR does.
+.Sp
+\&\fBNote:\fR This is the internal function implementing the \f(CW\*(C`\eu\*(C'\fR escape in
+double-quoted strings.
+.Sp
+.Vb 1
+\&    my $str = "\euperl\eE is great"; # "Perl is great"
+.Ve
+.IP "umask EXPR" 4
+.IX Xref "umask"
+.IX Item "umask EXPR"
+.PD 0
+.IP umask 4
+.IX Item "umask"
+.PD
+Sets the umask for the process to EXPR and returns the previous value.
+If EXPR is omitted, merely returns the current umask.
+.Sp
+The Unix permission \f(CW\*(C`rwxr\-x\-\-\-\*(C'\fR is represented as three sets of three
+bits, or three octal digits: \f(CW0750\fR (the leading 0 indicates octal
+and isn't one of the digits).  The \f(CW\*(C`umask\*(C'\fR value is such
+a number representing disabled permissions bits.  The permission (or
+"mode") values you pass \f(CW\*(C`mkdir\*(C'\fR or
+\&\f(CW\*(C`sysopen\*(C'\fR are modified by your
+umask, so even if you tell
+\&\f(CW\*(C`sysopen\*(C'\fR to create a file with
+permissions \f(CW0777\fR, if your umask is \f(CW0022\fR, then the file will
+actually be created with permissions \f(CW0755\fR.  If your
+\&\f(CW\*(C`umask\*(C'\fR were \f(CW0027\fR (group can't write; others can't
+read, write, or execute), then passing
+\&\f(CW\*(C`sysopen\*(C'\fR \f(CW0666\fR would create a
+file with mode \f(CW0640\fR (because \f(CW\*(C`0666 &~ 027\*(C'\fR is \f(CW0640\fR).
+.Sp
+Here's some advice: supply a creation mode of \f(CW0666\fR for regular
+files (in \f(CW\*(C`sysopen\*(C'\fR) and one of
+\&\f(CW0777\fR for directories (in \f(CW\*(C`mkdir\*(C'\fR) and
+executable files.  This gives users the freedom of
+choice: if they want protected files, they might choose process umasks
+of \f(CW022\fR, \f(CW027\fR, or even the particularly antisocial mask of \f(CW077\fR.
+Programs should rarely if ever make policy decisions better left to
+the user.  The exception to this is when writing files that should be
+kept private: mail files, web browser cookies, \fI.rhosts\fR files, and
+so on.
+.Sp
+If \fBumask\fR\|(2) is not implemented on your system and you are trying to
+restrict access for \fIyourself\fR (i.e., \f(CW\*(C`(EXPR & 0700) > 0\*(C'\fR),
+raises an exception.  If \fBumask\fR\|(2) is not implemented and you are
+not trying to restrict access for yourself, returns
+\&\f(CW\*(C`undef\*(C'\fR.
+.Sp
+Remember that a umask is a number, usually given in octal; it is \fInot\fR a
+string of octal digits.  See also \f(CW\*(C`oct\*(C'\fR, if all you have
+is a string.
+.Sp
+Portability issues: "umask" in perlport.
+.IP "undef EXPR" 4
+.IX Xref "undef undefine"
+.IX Item "undef EXPR"
+.PD 0
+.IP undef 4
+.IX Item "undef"
+.PD
+Undefines the value of EXPR, which must be an lvalue.  Use only on a
+scalar value, an array (using \f(CW\*(C`@\*(C'\fR), a hash (using \f(CW\*(C`%\*(C'\fR), a subroutine
+(using \f(CW\*(C`&\*(C'\fR), or a typeglob (using \f(CW\*(C`*\*(C'\fR).  Saying \f(CW\*(C`undef $hash{$key}\*(C'\fR
+will probably not do what you expect on most predefined variables or
+DBM list values, so don't do that; see \f(CW\*(C`delete\*(C'\fR.
+Always returns the undefined value.
+You can omit the EXPR, in which case nothing is
+undefined, but you still get an undefined value that you could, for
+instance, return from a subroutine, assign to a variable, or pass as a
+parameter.  Examples:
+.Sp
+.Vb 9
+\&    undef $foo;
+\&    undef $bar{\*(Aqblurfl\*(Aq};      # Compare to: delete $bar{\*(Aqblurfl\*(Aq};
+\&    undef @ary;
+\&    undef %hash;
+\&    undef &mysub;
+\&    undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
+\&    return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
+\&    select undef, undef, undef, 0.25;
+\&    my ($x, $y, undef, $z) = foo();    # Ignore third value returned
+.Ve
+.Sp
+Note that this is a unary operator, not a list operator.
+.IP "unlink LIST" 4
+.IX Xref "unlink delete remove rm del"
+.IX Item "unlink LIST"
+.PD 0
+.IP unlink 4
+.IX Item "unlink"
+.PD
+Deletes a list of files.  On success, it returns the number of files
+it successfully deleted.  On failure, it returns false and sets
+\&\f(CW$!\fR (errno):
+.Sp
+.Vb 3
+\&    my $unlinked = unlink \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq;
+\&    unlink @goners;
+\&    unlink glob "*.bak";
+.Ve
+.Sp
+On error, \f(CW\*(C`unlink\*(C'\fR will not tell you which files it
+could not remove.
+If you want to know which files you could not remove, try them one
+at a time:
+.Sp
+.Vb 3
+\&     foreach my $file ( @goners ) {
+\&         unlink $file or warn "Could not unlink $file: $!";
+\&     }
+.Ve
+.Sp
+Note: \f(CW\*(C`unlink\*(C'\fR will not attempt to delete directories
+unless you are
+superuser and the \fB\-U\fR flag is supplied to Perl.  Even if these
+conditions are met, be warned that unlinking a directory can inflict
+damage on your filesystem.  Finally, using \f(CW\*(C`unlink\*(C'\fR on
+directories is not supported on many operating systems.  Use
+\&\f(CW\*(C`rmdir\*(C'\fR instead.
+.Sp
+If LIST is omitted, \f(CW\*(C`unlink\*(C'\fR uses \f(CW$_\fR.
+.IP "unpack TEMPLATE,EXPR" 4
+.IX Xref "unpack"
+.IX Item "unpack TEMPLATE,EXPR"
+.PD 0
+.IP "unpack TEMPLATE" 4
+.IX Item "unpack TEMPLATE"
+.PD
+\&\f(CW\*(C`unpack\*(C'\fR does the reverse of
+\&\f(CW\*(C`pack\*(C'\fR: it takes a string
+and expands it out into a list of values.
+(In scalar context, it returns merely the first value produced.)
+.Sp
+If EXPR is omitted, unpacks the \f(CW$_\fR string.
+See perlpacktut for an introduction to this function.
+.Sp
+The string is broken into chunks described by the TEMPLATE.  Each chunk
+is converted separately to a value.  Typically, either the string is a result
+of \f(CW\*(C`pack\*(C'\fR, or the characters of the string
+represent a C structure of some kind.
+.Sp
+The TEMPLATE has the same format as in the
+\&\f(CW\*(C`pack\*(C'\fR function.
+Here's a subroutine that does substring:
+.Sp
+.Vb 4
+\&    sub substr {
+\&        my ($what, $where, $howmuch) = @_;
+\&        unpack("x$where a$howmuch", $what);
+\&    }
+.Ve
+.Sp
+and then there's
+.Sp
+.Vb 1
+\&    sub ordinal { unpack("W",$_[0]); } # same as ord()
+.Ve
+.Sp
+In addition to fields allowed in \f(CW\*(C`pack\*(C'\fR, you may
+prefix a field with a %<number> to indicate that
+you want a <number>\-bit checksum of the items instead of the items
+themselves.  Default is a 16\-bit checksum.  The checksum is calculated by
+summing numeric values of expanded values (for string fields the sum of
+\&\f(CWord($char)\fR is taken; for bit fields the sum of zeroes and ones).
+.Sp
+For example, the following
+computes the same number as the System V sum program:
+.Sp
+.Vb 4
+\&    my $checksum = do {
+\&        local $/;  # slurp!
+\&        unpack("%32W*", readline) % 65535;
+\&    };
+.Ve
+.Sp
+The following efficiently counts the number of set bits in a bit vector:
+.Sp
+.Vb 1
+\&    my $setbits = unpack("%32b*", $selectmask);
+.Ve
+.Sp
+The \f(CW\*(C`p\*(C'\fR and \f(CW\*(C`P\*(C'\fR formats should be used with care.  Since Perl
+has no way of checking whether the value passed to
+\&\f(CW\*(C`unpack\*(C'\fR
+corresponds to a valid memory location, passing a pointer value that's
+not known to be valid is likely to have disastrous consequences.
+.Sp
+If there are more pack codes or if the repeat count of a field or a group
+is larger than what the remainder of the input string allows, the result
+is not well defined: the repeat count may be decreased, or
+\&\f(CW\*(C`unpack\*(C'\fR may produce empty strings or zeros,
+or it may raise an exception.
+If the input string is longer than one described by the TEMPLATE,
+the remainder of that input string is ignored.
+.Sp
+See \f(CW\*(C`pack\*(C'\fR for more examples and notes.
+.IP "unshift ARRAY,LIST" 4
+.IX Xref "unshift"
+.IX Item "unshift ARRAY,LIST"
+Add one or more elements to the \fBbeginning\fR of an array. This is the
+opposite of a \f(CW\*(C`shift\*(C'\fR.
+.Sp
+.Vb 2
+\&    my @animals = ("cat");
+\&    unshift(@animals, "mouse"); # ("mouse", "cat")
+\&
+\&    my @colors = ("red");
+\&    unshift(@colors, ("blue", "green")); # ("blue", "green", "red")
+.Ve
+.Sp
+Returns the new number of elements in the updated array.
+.Sp
+.Vb 2
+\&    # Return value is the number of items in the updated array
+\&    my $color_count = unshift(@colors, ("yellow", "purple"));
+\&
+\&    say "There are $color_count colors in the updated array";
+.Ve
+.Sp
+Note the LIST is prepended whole, not one element at a time, so the
+prepended elements stay in the same order.  Use
+\&\f(CW\*(C`reverse\*(C'\fR to do the reverse.
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`unshift\*(C'\fR to take
+a scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.IP "untie VARIABLE" 4
+.IX Xref "untie"
+.IX Item "untie VARIABLE"
+Breaks the binding between a variable and a package.
+(See tie.)
+Has no effect if the variable is not tied.
+.IP "use Module VERSION LIST" 4
+.IX Xref "use module import"
+.IX Item "use Module VERSION LIST"
+.PD 0
+.IP "use Module VERSION" 4
+.IX Item "use Module VERSION"
+.IP "use Module LIST" 4
+.IX Item "use Module LIST"
+.IP "use Module" 4
+.IX Item "use Module"
+.PD
+Imports some semantics into the current package from the named module,
+generally by aliasing certain subroutine or variable names into your
+package.  It is exactly equivalent to
+.Sp
+.Vb 1
+\&    BEGIN { require Module; Module\->import( LIST ); }
+.Ve
+.Sp
+except that Module \fImust\fR be a bareword.
+The importation can be made conditional by using the if module.
+.Sp
+The \f(CW\*(C`BEGIN\*(C'\fR forces the \f(CW\*(C`require\*(C'\fR and
+\&\f(CW\*(C`import\*(C'\fR to happen at compile time.  The
+\&\f(CW\*(C`require\*(C'\fR makes sure the module is loaded into
+memory if it hasn't been yet.  The \f(CW\*(C`import\*(C'\fR is not a
+builtin; it's just an ordinary static method
+call into the \f(CW\*(C`Module\*(C'\fR package to tell the module to import the list of
+features back into the current package.  The module can implement its
+\&\f(CW\*(C`import\*(C'\fR method any way it likes, though most modules
+just choose to derive their \f(CW\*(C`import\*(C'\fR method via
+inheritance from the \f(CW\*(C`Exporter\*(C'\fR class that is defined in the
+\&\f(CW\*(C`Exporter\*(C'\fR module.  See Exporter.  If no
+\&\f(CW\*(C`import\*(C'\fR method can be found, then the call is skipped,
+even if there is an AUTOLOAD method.
+.Sp
+If you do not want to call the package's \f(CW\*(C`import\*(C'\fR
+method (for instance,
+to stop your namespace from being altered), explicitly supply the empty list:
+.Sp
+.Vb 1
+\&    use Module ();
+.Ve
+.Sp
+That is exactly equivalent to
+.Sp
+.Vb 1
+\&    BEGIN { require Module }
+.Ve
+.Sp
+If the VERSION argument is present between Module and LIST, then the
+\&\f(CW\*(C`use\*(C'\fR will call the \f(CW\*(C`VERSION\*(C'\fR method in
+class Module with the given version as an argument:
+.Sp
+.Vb 1
+\&    use Module 12.34;
+.Ve
+.Sp
+is equivalent to:
+.Sp
+.Vb 1
+\&    BEGIN { require Module; Module\->VERSION(12.34) }
+.Ve
+.Sp
+The default \f(CW\*(C`VERSION\*(C'\fR method,
+inherited from the \f(CW\*(C`UNIVERSAL\*(C'\fR class, croaks if the given
+version is larger than the value of the variable \f(CW$Module::VERSION\fR.
+.Sp
+The VERSION argument cannot be an arbitrary expression.  It only counts
+as a VERSION argument if it is a version number literal, starting with
+either a digit or \f(CW\*(C`v\*(C'\fR followed by a digit.  Anything that doesn't
+look like a version literal will be parsed as the start of the LIST.
+Nevertheless, many attempts to use an arbitrary expression as a VERSION
+argument will appear to work, because Exporter's \f(CW\*(C`import\*(C'\fR method
+handles numeric arguments specially, performing version checks rather
+than treating them as things to export.
+.Sp
+Again, there is a distinction between omitting LIST (\f(CW\*(C`import\*(C'\fR called with no arguments) and an explicit empty LIST \f(CW\*(C`()\*(C'\fR
+(\f(CW\*(C`import\*(C'\fR not called).  Note that there is no comma
+after VERSION!
+.Sp
+Because this is a wide-open interface, pragmas (compiler directives)
+are also implemented this way.  Some of the currently implemented
+pragmas are:
+.Sp
+.Vb 8
+\&    use constant;
+\&    use diagnostics;
+\&    use integer;
+\&    use sigtrap  qw(SEGV BUS);
+\&    use strict   qw(subs vars refs);
+\&    use subs     qw(afunc blurfl);
+\&    use warnings qw(all);
+\&    use sort     qw(stable);
+.Ve
+.Sp
+Some of these pseudo-modules import semantics into the current
+block scope (like \f(CW\*(C`strict\*(C'\fR or \f(CW\*(C`integer\*(C'\fR, unlike
+ordinary modules, which import symbols into the current package (which
+are effective through the end of the file).
+.Sp
+Because \f(CW\*(C`use\*(C'\fR takes effect at compile time,
+it doesn't respect the ordinary flow control of the code being compiled.
+In particular, putting a \f(CW\*(C`use\*(C'\fR inside the
+false branch of a conditional doesn't prevent it
+from being processed.  If a module or pragma only needs to be loaded
+conditionally, this can be done using the if pragma:
+.Sp
+.Vb 2
+\&    use if $] < 5.008, "utf8";
+\&    use if WANT_WARNINGS, warnings => qw(all);
+.Ve
+.Sp
+There's a corresponding \f(CW\*(C`no\*(C'\fR declaration
+that unimports meanings imported by \f(CW\*(C`use\*(C'\fR,
+i.e., it calls \f(CW\*(C`Module\->unimport(LIST)\*(C'\fR instead of
+\&\f(CW\*(C`import\*(C'\fR.  It behaves just as \f(CW\*(C`import\*(C'\fR
+does with VERSION, an omitted or empty LIST,
+or no unimport method being found.
+.Sp
+.Vb 3
+\&    no integer;
+\&    no strict \*(Aqrefs\*(Aq;
+\&    no warnings;
+.Ve
+.Sp
+See perlmodlib for a list of standard modules and pragmas.  See
+perlrun for the \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-m\*(C'\fR command-line
+options to Perl that give \f(CW\*(C`use\*(C'\fR
+functionality from the command-line.
+.IP "use VERSION" 4
+.IX Item "use VERSION"
+Lexically enables all features available in the requested version as
+defined by the feature pragma, disabling any features not in the
+requested version's feature bundle.  See feature.
+.Sp
+VERSION may be either a v\-string such as v5.24.1, which will be compared
+to \f(CW$^V\fR (aka \f(CW$PERL_VERSION\fR), or a numeric argument of the
+form 5.024001, which will be compared to \f(CW$]\fR.  An
+exception is raised if VERSION is greater than the version of the current
+Perl interpreter; Perl will not attempt to parse the rest of the file.
+Compare with \f(CW\*(C`require\*(C'\fR, which can do a similar check
+at run time.
+.Sp
+If the specified Perl version is 5.12 or higher, strictures are enabled
+lexically as with \f(CW\*(C`use strict\*(C'\fR.  Similarly, if the specified
+Perl version is 5.35.0 or higher, warnings are enabled.  Later use of
+\&\f(CW\*(C`use VERSION\*(C'\fR will override all behavior of a previous \f(CW\*(C`use VERSION\*(C'\fR,
+possibly removing the \f(CW\*(C`strict\*(C'\fR, \f(CW\*(C`warnings\*(C'\fR, and \f(CW\*(C`feature\*(C'\fR added by it.
+\&\f(CW\*(C`use VERSION\*(C'\fR does not load the \fIfeature.pm\fR, \fIstrict.pm\fR, or
+\&\fIwarnings.pm\fR files.
+.Sp
+In the current implementation, any explicit use of \f(CW\*(C`use strict\*(C'\fR or
+\&\f(CW\*(C`no strict\*(C'\fR overrides \f(CW\*(C`use VERSION\*(C'\fR, even if it comes before it.
+However, this may be subject to change in a future release of Perl, so new
+code should not rely on this fact.  It is recommended that a
+\&\f(CW\*(C`use VERSION\*(C'\fR declaration be the first significant statement within a
+file (possibly after a \f(CW\*(C`package\*(C'\fR statement or any amount of whitespace or
+comment), so that its effects happen first, and other pragmata are applied
+after it.
+.Sp
+Specifying VERSION as a numeric argument of the form 5.024001 should
+generally be avoided as older less readable syntax compared to
+v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric
+form was the only supported syntax, which is why you might see it in
+older code.
+.Sp
+.Vb 3
+\&    use v5.24.1;    # compile time version check
+\&    use 5.24.1;     # ditto
+\&    use 5.024_001;  # ditto; older syntax compatible with perl 5.6
+.Ve
+.Sp
+This is often useful if you need to check the current Perl version before
+\&\f(CW\*(C`use\*(C'\fRing library modules that won't work
+with older versions of Perl.
+(We try not to do this more than we have to.)
+.Sp
+Symmetrically, \f(CW\*(C`no VERSION\*(C'\fR allows you to specify that you want a version
+of Perl older than the specified one.  Historically this was added during
+early designs of the Raku language (formerly "Perl 6"), so that a Perl 5
+program could begin
+.Sp
+.Vb 1
+\&    no 6;
+.Ve
+.Sp
+to declare that it is not a Perl 6 program.  As the two languages have
+different implementations, file naming conventions, and other
+infrastructure, this feature is now little used in practice and should be
+avoided in newly-written code.
+.Sp
+Care should be taken when using the \f(CW\*(C`no VERSION\*(C'\fR form, as it is \fIonly\fR
+meant to be used to assert that the running Perl is of a earlier version
+than its argument and \fInot\fR to undo the feature-enabling side effects
+of \f(CW\*(C`use VERSION\*(C'\fR.
+.IP "utime LIST" 4
+.IX Xref "utime"
+.IX Item "utime LIST"
+Changes the access and modification times on each file of a list of
+files.  The first two elements of the list must be the NUMERIC access
+and modification times, in that order.  Returns the number of files
+successfully changed.  The inode change time of each file is set
+to the current time.  For example, this code has the same effect as the
+Unix \fBtouch\fR\|(1) command when the files \fIalready exist\fR and belong to
+the user running the program:
+.Sp
+.Vb 3
+\&    #!/usr/bin/perl
+\&    my $atime = my $mtime = time;
+\&    utime $atime, $mtime, @ARGV;
+.Ve
+.Sp
+Since Perl 5.8.0, if the first two elements of the list are
+\&\f(CW\*(C`undef\*(C'\fR,
+the \fButime\fR\|(2) syscall from your C library is called with a null second
+argument.  On most systems, this will set the file's access and
+modification times to the current time (i.e., equivalent to the example
+above) and will work even on files you don't own provided you have write
+permission:
+.Sp
+.Vb 4
+\&    for my $file (@ARGV) {
+\&        utime(undef, undef, $file)
+\&            || warn "Couldn\*(Aqt touch $file: $!";
+\&    }
+.Ve
+.Sp
+Under NFS this will use the time of the NFS server, not the time of
+the local machine.  If there is a time synchronization problem, the
+NFS server and local machine will have different times.  The Unix
+\&\fBtouch\fR\|(1) command will in fact normally use this form instead of the
+one shown in the first example.
+.Sp
+Passing only one of the first two elements as \f(CW\*(C`undef\*(C'\fR is
+equivalent to passing a 0 and will not have the effect described when
+both are \f(CW\*(C`undef\*(C'\fR.  This also triggers an
+uninitialized warning.
+.Sp
+On systems that support \fBfutimes\fR\|(2), you may pass filehandles among the
+files.  On systems that don't support \fBfutimes\fR\|(2), passing filehandles raises
+an exception.  Filehandles must be passed as globs or glob references to be
+recognized; barewords are considered filenames.
+.Sp
+Portability issues: "utime" in perlport.
+.IP "values HASH" 4
+.IX Xref "values"
+.IX Item "values HASH"
+.PD 0
+.IP "values ARRAY" 4
+.IX Item "values ARRAY"
+.PD
+In list context, returns a list consisting of all the values of the named
+hash.  In Perl 5.12 or later only, will also return a list of the values of
+an array; prior to that release, attempting to use an array argument will
+produce a syntax error.  In scalar context, returns the number of values.
+.Sp
+Hash entries are returned in an apparently random order.  The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash.  Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by \f(CW\*(C`each\*(C'\fR or
+\&\f(CW\*(C`keys\*(C'\fR may be deleted without changing the order.  So
+long as a given hash is unmodified you may rely on
+\&\f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR and
+\&\f(CW\*(C`each\*(C'\fR to repeatedly return the same order
+as each other.  See "Algorithmic Complexity Attacks" in perlsec for
+details on why hash order is randomized.  Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.  Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
+.Sp
+As a side effect, calling \f(CW\*(C`values\*(C'\fR resets the HASH or
+ARRAY's internal iterator (see \f(CW\*(C`each\*(C'\fR) before yielding the
+values.  In particular,
+calling \f(CW\*(C`values\*(C'\fR in void context resets the iterator
+with no other overhead.
+.Sp
+Apart from resetting the iterator,
+\&\f(CW\*(C`values @array\*(C'\fR in list context is the same as plain \f(CW@array\fR.
+(We recommend that you use void context \f(CW\*(C`keys @array\*(C'\fR for this, but
+reasoned that taking \f(CW\*(C`values @array\*(C'\fR out would require more
+documentation than leaving it in.)
+.Sp
+Note that the values are not copied, which means modifying them will
+modify the contents of the hash:
+.Sp
+.Vb 2
+\&    for (values %hash)      { s/foo/bar/g }  # modifies %hash values
+\&    for (@hash{keys %hash}) { s/foo/bar/g }  # same
+.Ve
+.Sp
+Starting with Perl 5.14, an experimental feature allowed
+\&\f(CW\*(C`values\*(C'\fR to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
+.Sp
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work \fIonly\fR on Perls of
+a recent vintage:
+.Sp
+.Vb 1
+\&    use v5.12;  # so keys/values/each work on arrays
+.Ve
+.Sp
+See also \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`each\*(C'\fR, and
+\&\f(CW\*(C`sort\*(C'\fR.
+.IP "vec EXPR,OFFSET,BITS" 4
+.IX Xref "vec bit bit vector"
+.IX Item "vec EXPR,OFFSET,BITS"
+Treats the string in EXPR as a bit vector made up of elements of
+width BITS and returns the value of the element specified by OFFSET
+as an unsigned integer.  BITS therefore specifies the number of bits
+that are reserved for each element in the bit vector.  This must
+be a power of two from 1 to 32 (or 64, if your platform supports
+that).
+.Sp
+If BITS is 8, "elements" coincide with bytes of the input string.
+.Sp
+If BITS is 16 or more, bytes of the input string are grouped into chunks
+of size BITS/8, and each group is converted to a number as with
+\&\f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR with
+big-endian formats \f(CW\*(C`n\*(C'\fR/\f(CW\*(C`N\*(C'\fR (and analogously for BITS==64).  See
+\&\f(CW\*(C`pack\*(C'\fR for details.
+.Sp
+If bits is 4 or less, the string is broken into bytes, then the bits
+of each byte are broken into 8/BITS groups.  Bits of a byte are
+numbered in a little-endian-ish way, as in \f(CW0x01\fR, \f(CW0x02\fR,
+\&\f(CW0x04\fR, \f(CW0x08\fR, \f(CW0x10\fR, \f(CW0x20\fR, \f(CW0x40\fR, \f(CW0x80\fR.  For example,
+breaking the single input byte \f(CWchr(0x36)\fR into two groups gives a list
+\&\f(CW\*(C`(0x6, 0x3)\*(C'\fR; breaking it into 4 groups gives \f(CW\*(C`(0x2, 0x1, 0x3, 0x0)\*(C'\fR.
+.Sp
+\&\f(CW\*(C`vec\*(C'\fR may also be assigned to, in which case
+parentheses are needed
+to give the expression the correct precedence as in
+.Sp
+.Vb 1
+\&    vec($image, $max_x * $x + $y, 8) = 3;
+.Ve
+.Sp
+If the selected element is outside the string, the value 0 is returned.
+If an element off the end of the string is written to, Perl will first
+extend the string with sufficiently many zero bytes.   It is an error
+to try to write off the beginning of the string (i.e., negative OFFSET).
+.Sp
+If the string happens to be encoded as UTF\-8 internally (and thus has
+the UTF8 flag set), \f(CW\*(C`vec\*(C'\fR tries to convert it
+to use a one-byte-per-character internal representation. However, if the
+string contains characters with values of 256 or higher, a fatal error
+will occur.
+.Sp
+Strings created with \f(CW\*(C`vec\*(C'\fR can also be
+manipulated with the logical
+operators \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR.  These operators will assume a bit
+vector operation is desired when both operands are strings.
+See "Bitwise String Operators" in perlop.
+.Sp
+The following code will build up an ASCII string saying \f(CW\*(AqPerlPerlPerl\*(Aq\fR.
+The comments show the string after each step.  Note that this code works
+in the same way on big-endian or little-endian machines.
+.Sp
+.Vb 2
+\&    my $foo = \*(Aq\*(Aq;
+\&    vec($foo,  0, 32) = 0x5065726C; # \*(AqPerl\*(Aq
+\&
+\&    # $foo eq "Perl" eq "\ex50\ex65\ex72\ex6C", 32 bits
+\&    print vec($foo, 0, 8);  # prints 80 == 0x50 == ord(\*(AqP\*(Aq)
+\&
+\&    vec($foo,  2, 16) = 0x5065; # \*(AqPerlPe\*(Aq
+\&    vec($foo,  3, 16) = 0x726C; # \*(AqPerlPerl\*(Aq
+\&    vec($foo,  8,  8) = 0x50;   # \*(AqPerlPerlP\*(Aq
+\&    vec($foo,  9,  8) = 0x65;   # \*(AqPerlPerlPe\*(Aq
+\&    vec($foo, 20,  4) = 2;      # \*(AqPerlPerlPe\*(Aq   . "\ex02"
+\&    vec($foo, 21,  4) = 7;      # \*(AqPerlPerlPer\*(Aq
+\&                                   # \*(Aqr\*(Aq is "\ex72"
+\&    vec($foo, 45,  2) = 3;      # \*(AqPerlPerlPer\*(Aq  . "\ex0c"
+\&    vec($foo, 93,  1) = 1;      # \*(AqPerlPerlPer\*(Aq  . "\ex2c"
+\&    vec($foo, 94,  1) = 1;      # \*(AqPerlPerlPerl\*(Aq
+\&                                   # \*(Aql\*(Aq is "\ex6c"
+.Ve
+.Sp
+To transform a bit vector into a string or list of 0's and 1's, use these:
+.Sp
+.Vb 2
+\&    my $bits = unpack("b*", $vector);
+\&    my @bits = split(//, unpack("b*", $vector));
+.Ve
+.Sp
+If you know the exact length in bits, it can be used in place of the \f(CW\*(C`*\*(C'\fR.
+.Sp
+Here is an example to illustrate how the bits actually fall in place:
+.Sp
+.Vb 1
+\&  #!/usr/bin/perl \-wl
+\&
+\&  print <<\*(AqEOT\*(Aq;
+\&                                    0         1         2         3
+\&                     unpack("V",$_) 01234567890123456789012345678901
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  EOT
+\&
+\&  for $w (0..3) {
+\&      $width = 2**$w;
+\&      for ($shift=0; $shift < $width; ++$shift) {
+\&          for ($off=0; $off < 32/$width; ++$off) {
+\&              $str = pack("B*", "0"x32);
+\&              $bits = (1<<$shift);
+\&              vec($str, $off, $width) = $bits;
+\&              $res = unpack("b*",$str);
+\&              $val = unpack("V", $str);
+\&              write;
+\&          }
+\&      }
+\&  }
+\&
+\&  format STDOUT =
+\&  vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\&  $off, $width, $bits, $val, $res
+\&  .
+\&  _\|_END_\|_
+.Ve
+.Sp
+Regardless of the machine architecture on which it runs, the
+example above should print the following table:
+.Sp
+.Vb 10
+\&                                    0         1         2         3
+\&                     unpack("V",$_) 01234567890123456789012345678901
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
+\&  vec($_, 1, 1) = 1   ==          2 01000000000000000000000000000000
+\&  vec($_, 2, 1) = 1   ==          4 00100000000000000000000000000000
+\&  vec($_, 3, 1) = 1   ==          8 00010000000000000000000000000000
+\&  vec($_, 4, 1) = 1   ==         16 00001000000000000000000000000000
+\&  vec($_, 5, 1) = 1   ==         32 00000100000000000000000000000000
+\&  vec($_, 6, 1) = 1   ==         64 00000010000000000000000000000000
+\&  vec($_, 7, 1) = 1   ==        128 00000001000000000000000000000000
+\&  vec($_, 8, 1) = 1   ==        256 00000000100000000000000000000000
+\&  vec($_, 9, 1) = 1   ==        512 00000000010000000000000000000000
+\&  vec($_,10, 1) = 1   ==       1024 00000000001000000000000000000000
+\&  vec($_,11, 1) = 1   ==       2048 00000000000100000000000000000000
+\&  vec($_,12, 1) = 1   ==       4096 00000000000010000000000000000000
+\&  vec($_,13, 1) = 1   ==       8192 00000000000001000000000000000000
+\&  vec($_,14, 1) = 1   ==      16384 00000000000000100000000000000000
+\&  vec($_,15, 1) = 1   ==      32768 00000000000000010000000000000000
+\&  vec($_,16, 1) = 1   ==      65536 00000000000000001000000000000000
+\&  vec($_,17, 1) = 1   ==     131072 00000000000000000100000000000000
+\&  vec($_,18, 1) = 1   ==     262144 00000000000000000010000000000000
+\&  vec($_,19, 1) = 1   ==     524288 00000000000000000001000000000000
+\&  vec($_,20, 1) = 1   ==    1048576 00000000000000000000100000000000
+\&  vec($_,21, 1) = 1   ==    2097152 00000000000000000000010000000000
+\&  vec($_,22, 1) = 1   ==    4194304 00000000000000000000001000000000
+\&  vec($_,23, 1) = 1   ==    8388608 00000000000000000000000100000000
+\&  vec($_,24, 1) = 1   ==   16777216 00000000000000000000000010000000
+\&  vec($_,25, 1) = 1   ==   33554432 00000000000000000000000001000000
+\&  vec($_,26, 1) = 1   ==   67108864 00000000000000000000000000100000
+\&  vec($_,27, 1) = 1   ==  134217728 00000000000000000000000000010000
+\&  vec($_,28, 1) = 1   ==  268435456 00000000000000000000000000001000
+\&  vec($_,29, 1) = 1   ==  536870912 00000000000000000000000000000100
+\&  vec($_,30, 1) = 1   == 1073741824 00000000000000000000000000000010
+\&  vec($_,31, 1) = 1   == 2147483648 00000000000000000000000000000001
+\&  vec($_, 0, 2) = 1   ==          1 10000000000000000000000000000000
+\&  vec($_, 1, 2) = 1   ==          4 00100000000000000000000000000000
+\&  vec($_, 2, 2) = 1   ==         16 00001000000000000000000000000000
+\&  vec($_, 3, 2) = 1   ==         64 00000010000000000000000000000000
+\&  vec($_, 4, 2) = 1   ==        256 00000000100000000000000000000000
+\&  vec($_, 5, 2) = 1   ==       1024 00000000001000000000000000000000
+\&  vec($_, 6, 2) = 1   ==       4096 00000000000010000000000000000000
+\&  vec($_, 7, 2) = 1   ==      16384 00000000000000100000000000000000
+\&  vec($_, 8, 2) = 1   ==      65536 00000000000000001000000000000000
+\&  vec($_, 9, 2) = 1   ==     262144 00000000000000000010000000000000
+\&  vec($_,10, 2) = 1   ==    1048576 00000000000000000000100000000000
+\&  vec($_,11, 2) = 1   ==    4194304 00000000000000000000001000000000
+\&  vec($_,12, 2) = 1   ==   16777216 00000000000000000000000010000000
+\&  vec($_,13, 2) = 1   ==   67108864 00000000000000000000000000100000
+\&  vec($_,14, 2) = 1   ==  268435456 00000000000000000000000000001000
+\&  vec($_,15, 2) = 1   == 1073741824 00000000000000000000000000000010
+\&  vec($_, 0, 2) = 2   ==          2 01000000000000000000000000000000
+\&  vec($_, 1, 2) = 2   ==          8 00010000000000000000000000000000
+\&  vec($_, 2, 2) = 2   ==         32 00000100000000000000000000000000
+\&  vec($_, 3, 2) = 2   ==        128 00000001000000000000000000000000
+\&  vec($_, 4, 2) = 2   ==        512 00000000010000000000000000000000
+\&  vec($_, 5, 2) = 2   ==       2048 00000000000100000000000000000000
+\&  vec($_, 6, 2) = 2   ==       8192 00000000000001000000000000000000
+\&  vec($_, 7, 2) = 2   ==      32768 00000000000000010000000000000000
+\&  vec($_, 8, 2) = 2   ==     131072 00000000000000000100000000000000
+\&  vec($_, 9, 2) = 2   ==     524288 00000000000000000001000000000000
+\&  vec($_,10, 2) = 2   ==    2097152 00000000000000000000010000000000
+\&  vec($_,11, 2) = 2   ==    8388608 00000000000000000000000100000000
+\&  vec($_,12, 2) = 2   ==   33554432 00000000000000000000000001000000
+\&  vec($_,13, 2) = 2   ==  134217728 00000000000000000000000000010000
+\&  vec($_,14, 2) = 2   ==  536870912 00000000000000000000000000000100
+\&  vec($_,15, 2) = 2   == 2147483648 00000000000000000000000000000001
+\&  vec($_, 0, 4) = 1   ==          1 10000000000000000000000000000000
+\&  vec($_, 1, 4) = 1   ==         16 00001000000000000000000000000000
+\&  vec($_, 2, 4) = 1   ==        256 00000000100000000000000000000000
+\&  vec($_, 3, 4) = 1   ==       4096 00000000000010000000000000000000
+\&  vec($_, 4, 4) = 1   ==      65536 00000000000000001000000000000000
+\&  vec($_, 5, 4) = 1   ==    1048576 00000000000000000000100000000000
+\&  vec($_, 6, 4) = 1   ==   16777216 00000000000000000000000010000000
+\&  vec($_, 7, 4) = 1   ==  268435456 00000000000000000000000000001000
+\&  vec($_, 0, 4) = 2   ==          2 01000000000000000000000000000000
+\&  vec($_, 1, 4) = 2   ==         32 00000100000000000000000000000000
+\&  vec($_, 2, 4) = 2   ==        512 00000000010000000000000000000000
+\&  vec($_, 3, 4) = 2   ==       8192 00000000000001000000000000000000
+\&  vec($_, 4, 4) = 2   ==     131072 00000000000000000100000000000000
+\&  vec($_, 5, 4) = 2   ==    2097152 00000000000000000000010000000000
+\&  vec($_, 6, 4) = 2   ==   33554432 00000000000000000000000001000000
+\&  vec($_, 7, 4) = 2   ==  536870912 00000000000000000000000000000100
+\&  vec($_, 0, 4) = 4   ==          4 00100000000000000000000000000000
+\&  vec($_, 1, 4) = 4   ==         64 00000010000000000000000000000000
+\&  vec($_, 2, 4) = 4   ==       1024 00000000001000000000000000000000
+\&  vec($_, 3, 4) = 4   ==      16384 00000000000000100000000000000000
+\&  vec($_, 4, 4) = 4   ==     262144 00000000000000000010000000000000
+\&  vec($_, 5, 4) = 4   ==    4194304 00000000000000000000001000000000
+\&  vec($_, 6, 4) = 4   ==   67108864 00000000000000000000000000100000
+\&  vec($_, 7, 4) = 4   == 1073741824 00000000000000000000000000000010
+\&  vec($_, 0, 4) = 8   ==          8 00010000000000000000000000000000
+\&  vec($_, 1, 4) = 8   ==        128 00000001000000000000000000000000
+\&  vec($_, 2, 4) = 8   ==       2048 00000000000100000000000000000000
+\&  vec($_, 3, 4) = 8   ==      32768 00000000000000010000000000000000
+\&  vec($_, 4, 4) = 8   ==     524288 00000000000000000001000000000000
+\&  vec($_, 5, 4) = 8   ==    8388608 00000000000000000000000100000000
+\&  vec($_, 6, 4) = 8   ==  134217728 00000000000000000000000000010000
+\&  vec($_, 7, 4) = 8   == 2147483648 00000000000000000000000000000001
+\&  vec($_, 0, 8) = 1   ==          1 10000000000000000000000000000000
+\&  vec($_, 1, 8) = 1   ==        256 00000000100000000000000000000000
+\&  vec($_, 2, 8) = 1   ==      65536 00000000000000001000000000000000
+\&  vec($_, 3, 8) = 1   ==   16777216 00000000000000000000000010000000
+\&  vec($_, 0, 8) = 2   ==          2 01000000000000000000000000000000
+\&  vec($_, 1, 8) = 2   ==        512 00000000010000000000000000000000
+\&  vec($_, 2, 8) = 2   ==     131072 00000000000000000100000000000000
+\&  vec($_, 3, 8) = 2   ==   33554432 00000000000000000000000001000000
+\&  vec($_, 0, 8) = 4   ==          4 00100000000000000000000000000000
+\&  vec($_, 1, 8) = 4   ==       1024 00000000001000000000000000000000
+\&  vec($_, 2, 8) = 4   ==     262144 00000000000000000010000000000000
+\&  vec($_, 3, 8) = 4   ==   67108864 00000000000000000000000000100000
+\&  vec($_, 0, 8) = 8   ==          8 00010000000000000000000000000000
+\&  vec($_, 1, 8) = 8   ==       2048 00000000000100000000000000000000
+\&  vec($_, 2, 8) = 8   ==     524288 00000000000000000001000000000000
+\&  vec($_, 3, 8) = 8   ==  134217728 00000000000000000000000000010000
+\&  vec($_, 0, 8) = 16  ==         16 00001000000000000000000000000000
+\&  vec($_, 1, 8) = 16  ==       4096 00000000000010000000000000000000
+\&  vec($_, 2, 8) = 16  ==    1048576 00000000000000000000100000000000
+\&  vec($_, 3, 8) = 16  ==  268435456 00000000000000000000000000001000
+\&  vec($_, 0, 8) = 32  ==         32 00000100000000000000000000000000
+\&  vec($_, 1, 8) = 32  ==       8192 00000000000001000000000000000000
+\&  vec($_, 2, 8) = 32  ==    2097152 00000000000000000000010000000000
+\&  vec($_, 3, 8) = 32  ==  536870912 00000000000000000000000000000100
+\&  vec($_, 0, 8) = 64  ==         64 00000010000000000000000000000000
+\&  vec($_, 1, 8) = 64  ==      16384 00000000000000100000000000000000
+\&  vec($_, 2, 8) = 64  ==    4194304 00000000000000000000001000000000
+\&  vec($_, 3, 8) = 64  == 1073741824 00000000000000000000000000000010
+\&  vec($_, 0, 8) = 128 ==        128 00000001000000000000000000000000
+\&  vec($_, 1, 8) = 128 ==      32768 00000000000000010000000000000000
+\&  vec($_, 2, 8) = 128 ==    8388608 00000000000000000000000100000000
+\&  vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
+.Ve
+.IP wait 4
+.IX Xref "wait"
+.IX Item "wait"
+Behaves like \fBwait\fR\|(2) on your system: it waits for a child
+process to terminate and returns the pid of the deceased process, or
+\&\f(CW\-1\fR if there are no child processes.  The status is returned in
+\&\f(CW$?\fR and
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR.
+Note that a return value of \f(CW\-1\fR could mean that child processes are
+being automatically reaped, as described in perlipc.
+.Sp
+If you use \f(CW\*(C`wait\*(C'\fR in your handler for
+\&\f(CW$SIG{CHLD}\fR, it may accidentally wait for the child
+created by \f(CW\*(C`qx\*(C'\fR or \f(CW\*(C`system\*(C'\fR.
+See perlipc for details.
+.Sp
+Portability issues: "wait" in perlport.
+.IP "waitpid PID,FLAGS" 4
+.IX Xref "waitpid"
+.IX Item "waitpid PID,FLAGS"
+Waits for a particular child process to terminate and returns the pid of
+the deceased process, or \f(CW\-1\fR if there is no such child process.  A
+non-blocking wait (with WNOHANG in FLAGS) can return 0 if
+there are child processes matching PID but none have terminated yet.
+The status is returned in \f(CW$?\fR and
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR.
+.Sp
+A PID of \f(CW0\fR indicates to wait for any child process whose process group ID is
+equal to that of the current process.  A PID of less than \f(CW\-1\fR indicates to
+wait for any child process whose process group ID is equal to \-PID.  A PID of
+\&\f(CW\-1\fR indicates to wait for any child process.
+.Sp
+If you say
+.Sp
+.Vb 1
+\&    use POSIX ":sys_wait_h";
+\&
+\&    my $kid;
+\&    do {
+\&        $kid = waitpid(\-1, WNOHANG);
+\&    } while $kid > 0;
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&    1 while waitpid(\-1, WNOHANG) > 0;
+.Ve
+.Sp
+then you can do a non-blocking wait for all pending zombie processes (see
+"WAIT" in POSIX).
+Non-blocking wait is available on machines supporting either the
+\&\fBwaitpid\fR\|(2) or \fBwait4\fR\|(2) syscalls.  However, waiting for a particular
+pid with FLAGS of \f(CW0\fR is implemented everywhere.  (Perl emulates the
+system call by remembering the status values of processes that have
+exited but have not been harvested by the Perl script yet.)
+.Sp
+Note that on some systems, a return value of \f(CW\-1\fR could mean that child
+processes are being automatically reaped.  See perlipc for details,
+and for other examples.
+.Sp
+Portability issues: "waitpid" in perlport.
+.IP wantarray 4
+.IX Xref "wantarray context"
+.IX Item "wantarray"
+Returns true if the context of the currently executing subroutine or
+\&\f(CW\*(C`eval\*(C'\fR is looking for a list value.  Returns false if the
+context is
+looking for a scalar.  Returns the undefined value if the context is
+looking for no value (void context).
+.Sp
+.Vb 3
+\&    return unless defined wantarray; # don\*(Aqt bother doing more
+\&    my @a = complex_calculation();
+\&    return wantarray ? @a : "@a";
+.Ve
+.Sp
+\&\f(CW\*(C`wantarray\*(C'\fR's result is unspecified in the top level of a file,
+in a \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR or \f(CW\*(C`END\*(C'\fR block, or
+in a \f(CW\*(C`DESTROY\*(C'\fR method.
+.Sp
+This function should have been named \fBwantlist()\fR instead.
+.IP "warn LIST" 4
+.IX Xref "warn warning STDERR"
+.IX Item "warn LIST"
+Emits a warning, usually by printing it to \f(CW\*(C`STDERR\*(C'\fR.  \f(CW\*(C`warn\*(C'\fR interprets
+its operand LIST in the same way as \f(CW\*(C`die\*(C'\fR, but is slightly different
+in what it defaults to when LIST is empty or makes an empty string.
+If it is empty and \f(CW$@\fR already contains an exception
+value then that value is used after appending \f(CW"\et...caught"\fR.  If it
+is empty and \f(CW$@\fR is also empty then the string \f(CW"Warning: Something\*(Aqs
+wrong"\fR is used.
+.Sp
+By default, the exception derived from the operand LIST is stringified
+and printed to \f(CW\*(C`STDERR\*(C'\fR.  This behaviour can be altered by installing
+a \f(CW$SIG{_\|_WARN_\|_}\fR handler.  If there is such a
+handler then no message is automatically printed; it is the handler's
+responsibility to deal with the exception
+as it sees fit (like, for instance, converting it into a
+\&\f(CW\*(C`die\*(C'\fR).  Most
+handlers must therefore arrange to actually display the
+warnings that they are not prepared to deal with, by calling
+\&\f(CW\*(C`warn\*(C'\fR
+again in the handler.  Note that this is quite safe and will not
+produce an endless loop, since \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hooks are not called from
+inside one.
+.Sp
+You will find this behavior is slightly different from that of
+\&\f(CW$SIG{_\|_DIE_\|_}\fR handlers (which don't suppress the
+error text, but can instead call \f(CW\*(C`die\*(C'\fR again to change
+it).
+.Sp
+Using a \f(CW\*(C`_\|_WARN_\|_\*(C'\fR handler provides a powerful way to silence all
+warnings (even the so-called mandatory ones).  An example:
+.Sp
+.Vb 7
+\&    # wipe out *all* compile\-time warnings
+\&    BEGIN { $SIG{\*(Aq_\|_WARN_\|_\*(Aq} = sub { warn $_[0] if $DOWARN } }
+\&    my $foo = 10;
+\&    my $foo = 20;          # no warning about duplicate my $foo,
+\&                           # but hey, you asked for it!
+\&    # no compile\-time or run\-time warnings before here
+\&    $DOWARN = 1;
+\&
+\&    # run\-time warnings enabled after here
+\&    warn "\e$foo is alive and $foo!";     # does show up
+.Ve
+.Sp
+See perlvar for details on setting \f(CW%SIG\fR entries
+and for more
+examples.  See the Carp module for other kinds of warnings using its
+\&\f(CW\*(C`carp\*(C'\fR and \f(CW\*(C`cluck\*(C'\fR functions.
+.IP "write FILEHANDLE" 4
+.IX Xref "write"
+.IX Item "write FILEHANDLE"
+.PD 0
+.IP "write EXPR" 4
+.IX Item "write EXPR"
+.IP write 4
+.IX Item "write"
+.PD
+Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
+using the format associated with that file.  By default the format for
+a file is the one having the same name as the filehandle, but the
+format for the current output channel (see the
+\&\f(CW\*(C`select\*(C'\fR function) may be set explicitly by
+assigning the name of the format to the \f(CW$~\fR variable.
+.Sp
+Top of form processing is handled automatically:  if there is insufficient
+room on the current page for the formatted record, the page is advanced by
+writing a form feed and a special top-of-page
+format is used to format the new
+page header before the record is written.  By default, the top-of-page
+format is the name of the filehandle with \f(CW\*(C`_TOP\*(C'\fR appended, or \f(CW\*(C`top\*(C'\fR
+in the current package if the former does not exist.  This would be a
+problem with autovivified filehandles, but it may be dynamically set to the
+format of your choice by assigning the name to the \f(CW$^\fR
+variable while that filehandle is selected.  The number of lines
+remaining on the current page is in variable \f(CW\*(C`$\-\*(C'\fR, which
+can be set to \f(CW0\fR to force a new page.
+.Sp
+If FILEHANDLE is unspecified, output goes to the current default output
+channel, which starts out as STDOUT but may be changed by the
+\&\f(CW\*(C`select\*(C'\fR operator.  If the FILEHANDLE is an EXPR,
+then the expression
+is evaluated and the resulting string is used to look up the name of
+the FILEHANDLE at run time.  For more on formats, see perlform.
+.Sp
+Note that write is \fInot\fR the opposite of
+\&\f(CW\*(C`read\*(C'\fR.  Unfortunately.
+.IP y/// 4
+.IX Item "y///"
+The transliteration operator.  Same as
+\&\f(CW\*(C`tr///\*(C'\fR.  See
+"Quote-Like Operators" in perlop.
+.SS "Non-function Keywords by Cross-reference"
+.IX Subsection "Non-function Keywords by Cross-reference"
+\fIperldata\fR
+.IX Subsection "perldata"
+.IP _\|_DATA_\|_ 4
+.IX Item "__DATA__"
+.PD 0
+.IP _\|_END_\|_ 4
+.IX Item "__END__"
+.PD
+These keywords are documented in "Special Literals" in perldata.
+.PP
+\fIperlmod\fR
+.IX Subsection "perlmod"
+.IP BEGIN 4
+.IX Item "BEGIN"
+.PD 0
+.IP CHECK 4
+.IX Item "CHECK"
+.IP END 4
+.IX Item "END"
+.IP INIT 4
+.IX Item "INIT"
+.IP UNITCHECK 4
+.IX Item "UNITCHECK"
+.PD
+These compile phase keywords are documented in "BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod.
+.PP
+\fIperlobj\fR
+.IX Subsection "perlobj"
+.IP DESTROY 4
+.IX Item "DESTROY"
+This method keyword is documented in "Destructors" in perlobj.
+.PP
+\fIperlop\fR
+.IX Subsection "perlop"
+.IP and 4
+.IX Item "and"
+.PD 0
+.IP cmp 4
+.IX Item "cmp"
+.IP eq 4
+.IX Item "eq"
+.IP ge 4
+.IX Item "ge"
+.IP gt 4
+.IX Item "gt"
+.IP isa 4
+.IX Item "isa"
+.IP le 4
+.IX Item "le"
+.IP lt 4
+.IX Item "lt"
+.IP ne 4
+.IX Item "ne"
+.IP not 4
+.IX Item "not"
+.IP or 4
+.IX Item "or"
+.IP x 4
+.IX Item "x"
+.IP xor 4
+.IX Item "xor"
+.PD
+These operators are documented in perlop.
+.PP
+\fIperlsub\fR
+.IX Subsection "perlsub"
+.IP AUTOLOAD 4
+.IX Item "AUTOLOAD"
+This keyword is documented in "Autoloading" in perlsub.
+.PP
+\fIperlsyn\fR
+.IX Subsection "perlsyn"
+.IP else 4
+.IX Item "else"
+.PD 0
+.IP elsif 4
+.IX Item "elsif"
+.IP for 4
+.IX Item "for"
+.IP foreach 4
+.IX Item "foreach"
+.IP if 4
+.IX Item "if"
+.IP unless 4
+.IX Item "unless"
+.IP until 4
+.IX Item "until"
+.IP while 4
+.IX Item "while"
+.PD
+These flow-control keywords are documented in "Compound Statements" in perlsyn.
+.IP elseif 4
+.IX Item "elseif"
+The "else if" keyword is spelled \f(CW\*(C`elsif\*(C'\fR in Perl.  There's no \f(CW\*(C`elif\*(C'\fR
+or \f(CW\*(C`else if\*(C'\fR either.  It does parse \f(CW\*(C`elseif\*(C'\fR, but only to warn you
+about not using it.
+.Sp
+See the documentation for flow-control keywords in "Compound
+Statements" in perlsyn.
+.IP default 4
+.IX Item "default"
+.PD 0
+.IP given 4
+.IX Item "given"
+.IP when 4
+.IX Item "when"
+.PD
+These flow-control keywords related to the experimental switch feature are
+documented in "Switch Statements" in perlsyn.
+.IP try 4
+.IX Item "try"
+.PD 0
+.IP catch 4
+.IX Item "catch"
+.IP finally 4
+.IX Item "finally"
+.PD
+These flow-control keywords related to the experimental \f(CW\*(C`try\*(C'\fR feature are
+documented in "Try Catch Exception Handling" in perlsyn.
+.IP defer 4
+.IX Item "defer"
+This flow-control keyword related to the experimental \f(CW\*(C`defer\*(C'\fR feature is
+documented in "defer blocks" in perlsyn.
+.IP ADJUST 4
+.IX Item "ADJUST"
+This class-related phaser block is documented in perlclass.
diff --git a/upstream/mageia-cauldron/man1/perlgit.1 b/upstream/mageia-cauldron/man1/perlgit.1
new file mode 100644
index 00000000..70753920
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlgit.1
@@ -0,0 +1,1076 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGIT 1"
+.TH PERLGIT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlgit \- Detailed information about git and the Perl repository
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides details on using git to develop Perl. If you are
+just interested in working on a quick patch, see perlhack first.
+This document is intended for people who are regular contributors to
+Perl, including those with write access to the git repository.
+.SH "CLONING THE REPOSITORY"
+.IX Header "CLONING THE REPOSITORY"
+All of Perl's source code is kept centrally in a Git repository at
+\&\fIgithub.com\fR.
+.PP
+You can make a read-only clone of the repository by running:
+.PP
+.Vb 1
+\&  % git clone git@github.com:Perl/perl5.git perl
+.Ve
+.PP
+If you cannot use that for firewall reasons, you can also clone via http:
+.PP
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.SH "WORKING WITH THE REPOSITORY"
+.IX Header "WORKING WITH THE REPOSITORY"
+Once you have changed into the repository directory, you can inspect
+it. After a clone the repository will contain a single local branch,
+which will be the current branch as well, as indicated by the asterisk.
+.PP
+.Vb 2
+\&  % git branch
+\&  * blead
+.Ve
+.PP
+Using the \-a switch to \f(CW\*(C`branch\*(C'\fR will also show the remote tracking
+branches in the repository:
+.PP
+.Vb 5
+\&  % git branch \-a
+\&  * blead
+\&    origin/HEAD
+\&    origin/blead
+\&  ...
+.Ve
+.PP
+The branches that begin with "origin" correspond to the "git remote"
+that you cloned from (which is named "origin"). Each branch on the
+remote will be exactly tracked by these branches. You should NEVER do
+work on these remote tracking branches. You only ever do work in a
+local branch. Local branches can be configured to automerge (on pull)
+from a designated remote tracking branch. This is the case with the
+default branch \f(CW\*(C`blead\*(C'\fR which will be configured to merge from the
+remote tracking branch \f(CW\*(C`origin/blead\*(C'\fR.
+.PP
+You can see recent commits:
+.PP
+.Vb 1
+\&  % git log
+.Ve
+.PP
+And pull new changes from the repository, and update your local
+repository (must be clean first)
+.PP
+.Vb 1
+\&  % git pull
+.Ve
+.PP
+Assuming we are on the branch \f(CW\*(C`blead\*(C'\fR immediately after a pull, this
+command would be more or less equivalent to:
+.PP
+.Vb 2
+\&  % git fetch
+\&  % git merge origin/blead
+.Ve
+.PP
+In fact if you want to update your local repository without touching
+your working directory you do:
+.PP
+.Vb 1
+\&  % git fetch
+.Ve
+.PP
+And if you want to update your remote-tracking branches for all defined
+remotes simultaneously you can do
+.PP
+.Vb 1
+\&  % git remote update
+.Ve
+.PP
+Neither of these last two commands will update your working directory,
+however both will update the remote-tracking branches in your
+repository.
+.PP
+To make a local branch of a remote branch:
+.PP
+.Vb 1
+\&  % git checkout \-b maint\-5.10 origin/maint\-5.10
+.Ve
+.PP
+To switch back to blead:
+.PP
+.Vb 1
+\&  % git checkout blead
+.Ve
+.SS "Finding out your status"
+.IX Subsection "Finding out your status"
+The most common git command you will use will probably be
+.PP
+.Vb 1
+\&  % git status
+.Ve
+.PP
+This command will produce as output a description of the current state
+of the repository, including modified files and unignored untracked
+files, and in addition it will show things like what files have been
+staged for the next commit, and usually some useful information about
+how to change things. For instance the following:
+.PP
+.Vb 3
+\& % git status
+\& On branch blead
+\& Your branch is ahead of \*(Aqorigin/blead\*(Aq by 1 commit.
+\&
+\& Changes to be committed:
+\&   (use "git reset HEAD <file>..." to unstage)
+\&
+\&       modified:   pod/perlgit.pod
+\&
+\& Changes not staged for commit:
+\&   (use "git add <file>..." to update what will be committed)
+\&   (use "git checkout \-\- <file>..." to discard changes in working
+\&                                                              directory)
+\&
+\&       modified:   pod/perlgit.pod
+\&
+\& Untracked files:
+\&   (use "git add <file>..." to include in what will be committed)
+\&
+\&       deliberate.untracked
+.Ve
+.PP
+This shows that there were changes to this document staged for commit,
+and that there were further changes in the working directory not yet
+staged. It also shows that there was an untracked file in the working
+directory, and as you can see shows how to change all of this. It also
+shows that there is one commit on the working branch \f(CW\*(C`blead\*(C'\fR which has
+not been pushed to the \f(CW\*(C`origin\*(C'\fR remote yet. \fBNOTE\fR: This output
+is also what you see as a template if you do not provide a message to
+\&\f(CW\*(C`git commit\*(C'\fR.
+.SS "Patch workflow"
+.IX Subsection "Patch workflow"
+First, please read perlhack for details on hacking the Perl core.
+That document covers many details on how to create a good patch.
+.PP
+If you already have a Perl repository, you should ensure that you're on
+the \fIblead\fR branch, and your repository is up to date:
+.PP
+.Vb 2
+\&  % git checkout blead
+\&  % git pull
+.Ve
+.PP
+It's preferable to patch against the latest blead version, since this
+is where new development occurs for all changes other than critical bug
+fixes. Critical bug fix patches should be made against the relevant
+maint branches, or should be submitted with a note indicating all the
+branches where the fix should be applied.
+.PP
+Now that we have everything up to date, we need to create a temporary
+new branch for these changes and switch into it:
+.PP
+.Vb 1
+\&  % git checkout \-b orange
+.Ve
+.PP
+which is the short form of
+.PP
+.Vb 2
+\&  % git branch orange
+\&  % git checkout orange
+.Ve
+.PP
+Creating a topic branch makes it easier for the maintainers to rebase
+or merge back into the master blead for a more linear history. If you
+don't work on a topic branch the maintainer has to manually cherry pick
+your changes onto blead before they can be applied.
+.PP
+That'll get you scolded on perl5\-porters, so don't do that. Be Awesome.
+.PP
+Then make your changes. For example, if Leon Brocard changes his name
+to Orange Brocard, we should change his name in the AUTHORS file:
+.PP
+.Vb 1
+\&  % perl \-pi \-e \*(Aqs{Leon Brocard}{Orange Brocard}\*(Aq AUTHORS
+.Ve
+.PP
+You can see what files are changed:
+.PP
+.Vb 4
+\&  % git status
+\&  On branch orange
+\&  Changes to be committed:
+\&    (use "git reset HEAD <file>..." to unstage)
+\&
+\&     modified:   AUTHORS
+.Ve
+.PP
+And you can see the changes:
+.PP
+.Vb 10
+\& % git diff
+\& diff \-\-git a/AUTHORS b/AUTHORS
+\& index 293dd70..722c93e 100644
+\& \-\-\- a/AUTHORS
+\& +++ b/AUTHORS
+\& @@ \-541,7 +541,7 @@    Lars Hecking              <lhecking@nmrc.ucc.ie>
+\&  Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
+\&  Leif Huhn                      <leif@hale.dkstat.com>
+\&  Len Johnson                    <lenjay@ibm.net>
+\& \-Leon Brocard                   <acme@astray.com>
+\& +Orange Brocard                 <acme@astray.com>
+\&  Les Peters                     <lpeters@aol.net>
+\&  Lesley Binks                   <lesley.binks@gmail.com>
+\&  Lincoln D. Stein               <lstein@cshl.org>
+.Ve
+.PP
+Now commit your change locally:
+.PP
+.Vb 3
+\& % git commit \-a \-m \*(AqRename Leon Brocard to Orange Brocard\*(Aq
+\& Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
+\&  1 files changed, 1 insertions(+), 1 deletions(\-)
+.Ve
+.PP
+The \f(CW\*(C`\-a\*(C'\fR option is used to include all files that git tracks that you
+have changed. If at this time, you only want to commit some of the
+files you have worked on, you can omit the \f(CW\*(C`\-a\*(C'\fR and use the command
+\&\f(CW\*(C`git\ add\ \fR\f(CIFILE\ ...\fR\f(CW\*(C'\fR before doing the commit. \f(CW\*(C`git\ add\ \-\-interactive\*(C'\fR allows you to even just commit portions of files
+instead of all the changes in them.
+.PP
+The \f(CW\*(C`\-m\*(C'\fR option is used to specify the commit message. If you omit it,
+git will open a text editor for you to compose the message
+interactively. This is useful when the changes are more complex than
+the sample given here, and, depending on the editor, to know that the
+first line of the commit message doesn't exceed the 50 character legal
+maximum. See "Commit message" in perlhack for more information about what
+makes a good commit message.
+.PP
+Once you've finished writing your commit message and exited your
+editor, git will write your change to disk and tell you something like
+this:
+.PP
+.Vb 2
+\& Created commit daf8e63: explain git status and stuff about remotes
+\&  1 files changed, 83 insertions(+), 3 deletions(\-)
+.Ve
+.PP
+If you re-run \f(CW\*(C`git status\*(C'\fR, you should see something like this:
+.PP
+.Vb 4
+\& % git status
+\& On branch orange
+\& Untracked files:
+\&   (use "git add <file>..." to include in what will be committed)
+\&
+\&       deliberate.untracked
+\&
+\& nothing added to commit but untracked files present (use "git add" to
+\&                                                                  track)
+.Ve
+.PP
+When in doubt, before you do anything else, check your status and read
+it carefully, many questions are answered directly by the git status
+output.
+.PP
+You can examine your last commit with:
+.PP
+.Vb 1
+\&  % git show HEAD
+.Ve
+.PP
+and if you are not happy with either the description or the patch
+itself you can fix it up by editing the files once more and then issue:
+.PP
+.Vb 1
+\&  % git commit \-a \-\-amend
+.Ve
+.PP
+Now, create a fork on GitHub to push your branch to, and add it as a
+remote if you haven't already, as described in the GitHub documentation
+at <https://help.github.com/en/articles/working\-with\-forks>:
+.PP
+.Vb 1
+\&  % git remote add fork git@github.com:MyUser/perl5.git
+.Ve
+.PP
+And push the branch to your fork:
+.PP
+.Vb 1
+\&  % git push \-u fork orange
+.Ve
+.PP
+You should now submit a Pull Request (PR) on GitHub from the new branch
+to blead. For more information, see the GitHub documentation at
+<https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>.
+.PP
+You can also send patch files to
+perl5\-porters@perl.org <mailto:perl5-porters@perl.org> directly if the
+patch is not ready to be applied, but intended for discussion.
+.PP
+To create a patch file for all your local changes:
+.PP
+.Vb 2
+\&  % git format\-patch \-M blead..
+\&  0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+.Ve
+.PP
+Or for a lot of changes, e.g. from a topic branch:
+.PP
+.Vb 1
+\&  % git format\-patch \-\-stdout \-M blead.. > topic\-branch\-changes.patch
+.Ve
+.PP
+If you want to delete your temporary branch, you may do so with:
+.PP
+.Vb 6
+\& % git checkout blead
+\& % git branch \-d orange
+\& error: The branch \*(Aqorange\*(Aq is not an ancestor of your current HEAD.
+\& If you are sure you want to delete it, run \*(Aqgit branch \-D orange\*(Aq.
+\& % git branch \-D orange
+\& Deleted branch orange.
+.Ve
+.SS "A note on derived files"
+.IX Subsection "A note on derived files"
+Be aware that many files in the distribution are derivative\-\-avoid
+patching them, because git won't see the changes to them, and the build
+process will overwrite them. Patch the originals instead. Most
+utilities (like perldoc) are in this category, i.e. patch
+\&\fIutils/perldoc.PL\fR rather than \fIutils/perldoc\fR. Similarly, don't
+create patches for files under \fR\f(CI$src_root\fR\fI/ext\fR from their copies found
+in \fI\fR\f(CI$install_root\fR\fI/lib\fR. If you are unsure about the proper location of
+a file that may have gotten copied while building the source
+distribution, consult the \fIMANIFEST\fR.
+.SS "Cleaning a working directory"
+.IX Subsection "Cleaning a working directory"
+The command \f(CW\*(C`git clean\*(C'\fR can with varying arguments be used as a
+replacement for \f(CW\*(C`make clean\*(C'\fR.
+.PP
+To reset your working directory to a pristine condition you can do:
+.PP
+.Vb 1
+\&  % git clean \-dxf
+.Ve
+.PP
+However, be aware this will delete ALL untracked content. You can use
+.PP
+.Vb 1
+\&  % git clean \-Xf
+.Ve
+.PP
+to remove all ignored untracked files, such as build and test
+byproduct, but leave any manually created files alone.
+.PP
+If you only want to cancel some uncommitted edits, you can use \f(CW\*(C`git
+checkout\*(C'\fR and give it a list of files to be reverted, or \f(CW\*(C`git checkout
+\&\-f\*(C'\fR to revert them all.
+.PP
+If you want to cancel one or several commits, you can use \f(CW\*(C`git reset\*(C'\fR.
+.SS Bisecting
+.IX Subsection "Bisecting"
+\&\f(CW\*(C`git\*(C'\fR provides a built-in way to determine which commit should be blamed
+for introducing a given bug. \f(CW\*(C`git bisect\*(C'\fR performs a binary search of
+history to locate the first failing commit. It is fast, powerful and
+flexible, but requires some setup and to automate the process an auxiliary
+shell script is needed.
+.PP
+The core provides a wrapper program, \fIPorting/bisect.pl\fR, which attempts to
+simplify as much as possible, making bisecting as simple as running a Perl
+one-liner. For example, if you want to know when this became an error:
+.PP
+.Vb 1
+\&    perl \-e \*(Aqmy $a := 2\*(Aq
+.Ve
+.PP
+you simply run this:
+.PP
+.Vb 1
+\&    .../Porting/bisect.pl \-e \*(Aqmy $a := 2;\*(Aq
+.Ve
+.PP
+Using \fIPorting/bisect.pl\fR, with one command (and no other files) it's easy to
+find out
+.IP \(bu 4
+Which commit caused this example code to break?
+.IP \(bu 4
+Which commit caused this example code to start working?
+.IP \(bu 4
+Which commit added the first file to match this regex?
+.IP \(bu 4
+Which commit removed the last file to match this regex?
+.PP
+usually without needing to know which versions of perl to use as start and
+end revisions, as \fIPorting/bisect.pl\fR automatically searches to find the
+earliest stable version for which the test case passes. Run
+\&\f(CW\*(C`Porting/bisect.pl \-\-help\*(C'\fR for the full documentation, including how to
+set the \f(CW\*(C`Configure\*(C'\fR and build time options.
+.PP
+If you require more flexibility than \fIPorting/bisect.pl\fR has to offer, you'll
+need to run \f(CW\*(C`git bisect\*(C'\fR yourself. It's most useful to use \f(CW\*(C`git bisect run\*(C'\fR
+to automate the building and testing of perl revisions. For this you'll need
+a shell script for \f(CW\*(C`git\*(C'\fR to call to test a particular revision. An example
+script is \fIPorting/bisect\-example.sh\fR, which you should copy \fBoutside\fR of
+the repository, as the bisect process will reset the state to a clean checkout
+as it runs. The instructions below assume that you copied it as \fI~/run\fR and
+then edited it as appropriate.
+.PP
+You first enter in bisect mode with:
+.PP
+.Vb 1
+\&  % git bisect start
+.Ve
+.PP
+For example, if the bug is present on \f(CW\*(C`HEAD\*(C'\fR but wasn't in 5.10.0,
+\&\f(CW\*(C`git\*(C'\fR will learn about this when you enter:
+.PP
+.Vb 3
+\&  % git bisect bad
+\&  % git bisect good perl\-5.10.0
+\&  Bisecting: 853 revisions left to test after this
+.Ve
+.PP
+This results in checking out the median commit between \f(CW\*(C`HEAD\*(C'\fR and
+\&\f(CW\*(C`perl\-5.10.0\*(C'\fR. You can then run the bisecting process with:
+.PP
+.Vb 1
+\&  % git bisect run ~/run
+.Ve
+.PP
+When the first bad commit is isolated, \f(CW\*(C`git bisect\*(C'\fR will tell you so:
+.PP
+.Vb 4
+\&  ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
+\&  commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
+\&  Author: Dave Mitchell <davem@fdisolutions.com>
+\&  Date:   Sat Feb 9 14:56:23 2008 +0000
+\&
+\&      [perl #49472] Attributes + Unknown Error
+\&      ...
+\&
+\&  bisect run success
+.Ve
+.PP
+You can peek into the bisecting process with \f(CW\*(C`git bisect log\*(C'\fR and
+\&\f(CW\*(C`git bisect visualize\*(C'\fR. \f(CW\*(C`git bisect reset\*(C'\fR will get you out of bisect
+mode.
+.PP
+Please note that the first \f(CW\*(C`good\*(C'\fR state must be an ancestor of the
+first \f(CW\*(C`bad\*(C'\fR state. If you want to search for the commit that \fIsolved\fR
+some bug, you have to negate your test case (i.e. exit with \f(CW1\fR if OK
+and \f(CW0\fR if not) and still mark the lower bound as \f(CW\*(C`good\*(C'\fR and the
+upper as \f(CW\*(C`bad\*(C'\fR. The "first bad commit" has then to be understood as
+the "first commit where the bug is solved".
+.PP
+\&\f(CW\*(C`git help bisect\*(C'\fR has much more information on how you can tweak your
+binary searches.
+.PP
+Following bisection you may wish to configure, build and test perl at
+commits identified by the bisection process.  Sometimes, particularly
+with older perls, \f(CW\*(C`make\*(C'\fR may fail during this process.  In this case
+you may be able to patch the source code at the older commit point.  To
+do so, please follow the suggestions provided in
+"Building perl at older commits" in perlhack.
+.SS "Topic branches and rewriting history"
+.IX Subsection "Topic branches and rewriting history"
+Individual committers should create topic branches under
+\&\fByourname\fR/\fBsome_descriptive_name\fR:
+.PP
+.Vb 4
+\&  % branch="$yourname/$some_descriptive_name"
+\&  % git checkout \-b $branch
+\&  ... do local edits, commits etc ...
+\&  % git push origin \-u $branch
+.Ve
+.PP
+Should you be stuck with an ancient version of git (prior to 1.7), then
+\&\f(CW\*(C`git push\*(C'\fR will not have the \f(CW\*(C`\-u\*(C'\fR switch, and you have to replace the
+last step with the following sequence:
+.PP
+.Vb 3
+\&  % git push origin $branch:refs/heads/$branch
+\&  % git config branch.$branch.remote origin
+\&  % git config branch.$branch.merge refs/heads/$branch
+.Ve
+.PP
+If you want to make changes to someone else's topic branch, you should
+check with its creator before making any change to it.
+.PP
+You
+might sometimes find that the original author has edited the branch's
+history. There are lots of good reasons for this. Sometimes, an author
+might simply be rebasing the branch onto a newer source point.
+Sometimes, an author might have found an error in an early commit which
+they wanted to fix before merging the branch to blead.
+.PP
+Currently the master repository is configured to forbid
+non-fast-forward merges. This means that the branches within can not be
+rebased and pushed as a single step.
+.PP
+The only way you will ever be allowed to rebase or modify the history
+of a pushed branch is to delete it and push it as a new branch under
+the same name. Please think carefully about doing this. It may be
+better to sequentially rename your branches so that it is easier for
+others working with you to cherry-pick their local changes onto the new
+version. (XXX: needs explanation).
+.PP
+If you want to rebase a personal topic branch, you will have to delete
+your existing topic branch and push as a new version of it. You can do
+this via the following formula (see the explanation about \f(CW\*(C`refspec\*(C'\fR's
+in the git push documentation for details) after you have rebased your
+branch:
+.PP
+.Vb 4
+\&  # first rebase
+\&  % git checkout $user/$topic
+\&  % git fetch
+\&  % git rebase origin/blead
+\&
+\&  # then "delete\-and\-push"
+\&  % git push origin :$user/$topic
+\&  % git push origin $user/$topic
+.Ve
+.PP
+\&\fBNOTE:\fR it is forbidden at the repository level to delete any of the
+"primary" branches. That is any branch matching
+\&\f(CW\*(C`m!^(blead|maint|perl)!\*(C'\fR. Any attempt to do so will result in git
+producing an error like this:
+.PP
+.Vb 7
+\&  % git push origin :blead
+\&  *** It is forbidden to delete blead/maint branches in this repository
+\&  error: hooks/update exited with error code 1
+\&  error: hook declined to update refs/heads/blead
+\&  To ssh://perl5.git.perl.org/perl
+\&   ! [remote rejected] blead (hook declined)
+\&   error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl\*(Aq
+.Ve
+.PP
+As a matter of policy we do \fBnot\fR edit the history of the blead and
+maint\-* branches. If a typo (or worse) sneaks into a commit to blead or
+maint\-*, we'll fix it in another commit. The only types of updates
+allowed on these branches are "fast-forwards", where all history is
+preserved.
+.PP
+Annotated tags in the canonical perl.git repository will never be
+deleted or modified. Think long and hard about whether you want to push
+a local tag to perl.git before doing so. (Pushing simple tags is
+not allowed.)
+.SS Grafts
+.IX Subsection "Grafts"
+The perl history contains one mistake which was not caught in the
+conversion: a merge was recorded in the history between blead and
+maint\-5.10 where no merge actually occurred. Due to the nature of git,
+this is now impossible to fix in the public repository. You can remove
+this mis-merge locally by adding the following line to your
+\&\f(CW\*(C`.git/info/grafts\*(C'\fR file:
+.PP
+.Vb 1
+\& 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
+.Ve
+.PP
+It is particularly important to have this graft line if any bisecting
+is done in the area of the "merge" in question.
+.SH "WRITE ACCESS TO THE GIT REPOSITORY"
+.IX Header "WRITE ACCESS TO THE GIT REPOSITORY"
+Once you have write access, you will need to modify the URL for the
+origin remote to enable pushing. Edit \fI.git/config\fR with the
+\&\fBgit\-config\fR\|(1) command:
+.PP
+.Vb 1
+\&  % git config remote.origin.url git@github.com:Perl/perl5.git
+.Ve
+.PP
+You can also set up your user name and e\-mail address. Most people do
+this once globally in their \fI~/.gitconfig\fR by doing something like:
+.PP
+.Vb 2
+\&  % git config \-\-global user.name "Ævar Arnfjörð Bjarmason"
+\&  % git config \-\-global user.email avarab@gmail.com
+.Ve
+.PP
+However, if you'd like to override that just for perl,
+execute something like the following in \fIperl\fR:
+.PP
+.Vb 1
+\&  % git config user.email avar@cpan.org
+.Ve
+.PP
+It is also possible to keep \f(CW\*(C`origin\*(C'\fR as a git remote, and add a new
+remote for ssh access:
+.PP
+.Vb 1
+\&  % git remote add camel git@github.com:Perl/perl5.git
+.Ve
+.PP
+This allows you to update your local repository by pulling from
+\&\f(CW\*(C`origin\*(C'\fR, which is faster and doesn't require you to authenticate, and
+to push your changes back with the \f(CW\*(C`camel\*(C'\fR remote:
+.PP
+.Vb 2
+\&  % git fetch camel
+\&  % git push camel
+.Ve
+.PP
+The \f(CW\*(C`fetch\*(C'\fR command just updates the \f(CW\*(C`camel\*(C'\fR refs, as the objects
+themselves should have been fetched when pulling from \f(CW\*(C`origin\*(C'\fR.
+.SS "Working with Github pull requests"
+.IX Subsection "Working with Github pull requests"
+Pull requests typically originate from outside of the \f(CW\*(C`Perl/perl.git\*(C'\fR
+repository, so if you want to test or work with it locally a vanilla
+\&\f(CW\*(C`git fetch\*(C'\fR from the \f(CW\*(C`Perl/perl5.git\*(C'\fR repository won't fetch it.
+.PP
+However Github does provide a mechanism to fetch a pull request to a
+local branch.  They are available on Github remotes under \f(CW\*(C`pull/\*(C'\fR, so
+you can use \f(CW\*(C`git fetch pull/\fR\f(CIPRID\fR\f(CW/head:\fR\f(CIlocalname\fR\f(CW\*(C'\fR to make a
+local copy.  eg.  to fetch pull request 9999 to the local branch
+\&\f(CW\*(C`local\-branch\-name\*(C'\fR run:
+.PP
+.Vb 1
+\&  git fetch origin pull/9999/head:local\-branch\-name
+.Ve
+.PP
+and then:
+.PP
+.Vb 1
+\&  git checkout local\-branch\-name
+.Ve
+.PP
+Note: this branch is not rebased on \f(CW\*(C`blead\*(C'\fR, so instead of the
+checkout above, you might want:
+.PP
+.Vb 1
+\&  git rebase origin/blead local\-branch\-name
+.Ve
+.PP
+which rebases \f(CW\*(C`local\-branch\-name\*(C'\fR on \f(CW\*(C`blead\*(C'\fR, and checks it out.
+.PP
+Alternatively you can configure the remote to fetch all pull requests
+as remote-tracking branches.  To do this edit the remote in
+\&\fI.git/config\fR, for example if your github remote is \f(CW\*(C`origin\*(C'\fR you'd
+have:
+.PP
+.Vb 3
+\&  [remote "origin"]
+\&          url = git@github.com:/Perl/perl5.git
+\&          fetch = +refs/heads/*:refs/remotes/origin/*
+.Ve
+.PP
+Add a line to map the remote pull request branches to remote-tracking
+branches:
+.PP
+.Vb 4
+\&  [remote "origin"]
+\&          url = git@github.com:/Perl/perl5.git
+\&          fetch = +refs/heads/*:refs/remotes/origin/*
+\&          fetch = +refs/pull/*/head:refs/remotes/origin/pull/*
+.Ve
+.PP
+and then do a fetch as normal:
+.PP
+.Vb 1
+\&  git fetch origin
+.Ve
+.PP
+This will create a remote-tracking branch for every pull request, including
+closed requests.
+.PP
+To remove those remote-tracking branches, remove the line added above
+and prune:
+.PP
+.Vb 1
+\&  git fetch \-p origin # or git remote prune origin
+.Ve
+.SS "Accepting a patch"
+.IX Subsection "Accepting a patch"
+If you have received a patch file generated using the above section,
+you should try out the patch.
+.PP
+First we need to create a temporary new branch for these changes and
+switch into it:
+.PP
+.Vb 1
+\& % git checkout \-b experimental
+.Ve
+.PP
+Patches that were formatted by \f(CW\*(C`git format\-patch\*(C'\fR are applied with
+\&\f(CW\*(C`git am\*(C'\fR:
+.PP
+.Vb 2
+\& % git am 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+\& Applying Rename Leon Brocard to Orange Brocard
+.Ve
+.PP
+Note that some UNIX mail systems can mess with text attachments containing
+\&'From '. This will fix them up:
+.PP
+.Vb 2
+\& % perl \-pi \-e\*(Aqs/^>From /From /\*(Aq \e
+\&                        0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+.Ve
+.PP
+If just a raw diff is provided, it is also possible use this two-step
+process:
+.PP
+.Vb 3
+\& % git apply bugfix.diff
+\& % git commit \-a \-m "Some fixing" \e
+\&                            \-\-author="That Guy <that.guy@internets.com>"
+.Ve
+.PP
+Now we can inspect the change:
+.PP
+.Vb 4
+\& % git show HEAD
+\& commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
+\& Author: Leon Brocard <acme@astray.com>
+\& Date:   Fri Dec 19 17:02:59 2008 +0000
+\&
+\&   Rename Leon Brocard to Orange Brocard
+\&
+\& diff \-\-git a/AUTHORS b/AUTHORS
+\& index 293dd70..722c93e 100644
+\& \-\-\- a/AUTHORS
+\& +++ b/AUTHORS
+\& @@ \-541,7 +541,7 @@ Lars Hecking                 <lhecking@nmrc.ucc.ie>
+\&  Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
+\&  Leif Huhn                      <leif@hale.dkstat.com>
+\&  Len Johnson                    <lenjay@ibm.net>
+\& \-Leon Brocard                   <acme@astray.com>
+\& +Orange Brocard                 <acme@astray.com>
+\&  Les Peters                     <lpeters@aol.net>
+\&  Lesley Binks                   <lesley.binks@gmail.com>
+\&  Lincoln D. Stein               <lstein@cshl.org>
+.Ve
+.PP
+If you are a committer to Perl and you think the patch is good, you can
+then merge it into blead then push it out to the main repository:
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git merge experimental
+\&  % git push origin blead
+.Ve
+.PP
+If you want to delete your temporary branch, you may do so with:
+.PP
+.Vb 7
+\& % git checkout blead
+\& % git branch \-d experimental
+\& error: The branch \*(Aqexperimental\*(Aq is not an ancestor of your current
+\& HEAD.  If you are sure you want to delete it, run \*(Aqgit branch \-D
+\& experimental\*(Aq.
+\& % git branch \-D experimental
+\& Deleted branch experimental.
+.Ve
+.SS "Committing to blead"
+.IX Subsection "Committing to blead"
+The 'blead' branch will become the next production release of Perl.
+.PP
+Before pushing \fIany\fR local change to blead, it's incredibly important
+that you do a few things, lest other committers come after you with
+pitchforks and torches:
+.IP \(bu 4
+Make sure you have a good commit message. See "Commit
+message" in perlhack for details.
+.IP \(bu 4
+Run the test suite. You might not think that one typo fix would break a
+test file. You'd be wrong. Here's an example of where not running the
+suite caused problems. A patch was submitted that added a couple of
+tests to an existing \fI.t\fR. It couldn't possibly affect anything else, so
+no need to test beyond the single affected \fI.t\fR, right?  But, the
+submitter's email address had changed since the last of their
+submissions, and this caused other tests to fail. Running the test
+target given in the next item would have caught this problem.
+.IP \(bu 4
+If you don't run the full test suite, at least \f(CW\*(C`make test_porting\*(C'\fR.
+This will run basic sanity checks. To see which sanity checks, have a
+look in \fIt/porting\fR.
+.IP \(bu 4
+If you make any changes that affect miniperl or core routines that have
+different code paths for miniperl, be sure to run \f(CW\*(C`make minitest\*(C'\fR.
+This will catch problems that even the full test suite will not catch
+because it runs a subset of tests under miniperl rather than perl.
+.SS "On merging and rebasing"
+.IX Subsection "On merging and rebasing"
+Simple, one-off commits pushed to the 'blead' branch should be simple
+commits that apply cleanly.  In other words, you should make sure your
+work is committed against the current position of blead, so that you can
+push back to the master repository without merging.
+.PP
+Sometimes, blead will move while you're building or testing your
+changes.  When this happens, your push will be rejected with a message
+like this:
+.PP
+.Vb 7
+\& To ssh://perl5.git.perl.org/perl.git
+\&  ! [rejected]        blead \-> blead (non\-fast\-forward)
+\& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl.git\*(Aq
+\& To prevent you from losing history, non\-fast\-forward updates were
+\& rejected Merge the remote changes (e.g. \*(Aqgit pull\*(Aq) before pushing
+\& again.  See the \*(AqNote about fast\-forwards\*(Aq section of \*(Aqgit push \-\-help\*(Aq
+\& for details.
+.Ve
+.PP
+When this happens, you can just \fIrebase\fR your work against the new
+position of blead, like this (assuming your remote for the master
+repository is "p5p"):
+.PP
+.Vb 2
+\&  % git fetch p5p
+\&  % git rebase p5p/blead
+.Ve
+.PP
+You will see your commits being re-applied, and you will then be able to
+push safely.  More information about rebasing can be found in the
+documentation for the \fBgit\-rebase\fR\|(1) command.
+.PP
+For larger sets of commits that only make sense together, or that would
+benefit from a summary of the set's purpose, you should use a merge
+commit.  You should perform your work on a topic branch, which you should regularly rebase
+against blead to ensure that your code is not broken by blead moving.
+When you have finished your work, please perform a final rebase and
+test.  Linear history is something that gets lost with every
+commit on blead, but a final rebase makes the history linear
+again, making it easier for future maintainers to see what has
+happened.  Rebase as follows (assuming your work was on the
+branch \f(CW\*(C`committer/somework\*(C'\fR):
+.PP
+.Vb 2
+\&  % git checkout committer/somework
+\&  % git rebase blead
+.Ve
+.PP
+Then you can merge it into master like this:
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git merge \-\-no\-ff \-\-no\-commit committer/somework
+\&  % git commit \-a
+.Ve
+.PP
+The switches above deserve explanation.  \f(CW\*(C`\-\-no\-ff\*(C'\fR indicates that even
+if all your work can be applied linearly against blead, a merge commit
+should still be prepared.  This ensures that all your work will be shown
+as a side branch, with all its commits merged into the mainstream blead
+by the merge commit.
+.PP
+\&\f(CW\*(C`\-\-no\-commit\*(C'\fR means that the merge commit will be \fIprepared\fR but not
+\&\fIcommitted\fR.  The commit is then actually performed when you run the
+next command, which will bring up your editor to describe the commit.
+Without \f(CW\*(C`\-\-no\-commit\*(C'\fR, the commit would be made with nearly no useful
+message, which would greatly diminish the value of the merge commit as a
+placeholder for the work's description.
+.PP
+When describing the merge commit, explain the purpose of the branch, and
+keep in mind that this description will probably be used by the
+eventual release engineer when reviewing the next perldelta document.
+.PP
+If the subsequent \fIpush\fR fails then you must be careful on how you \fIrebase\fR.
+If you use
+.PP
+.Vb 1
+\&  % git rebase p5p/blead
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&  % git pull \-\-rebase
+.Ve
+.PP
+then your carefully created merge commit will be lost! To avoid this you
+can use:
+.PP
+.Vb 2
+\&  % git fetch p5p
+\&  % git rebase \-\-rebase\-merges p5p/blead
+.Ve
+.PP
+This will recreate your merge commit.
+.PP
+(Should you be stuck with an older version of git (prior to 2.18), then
+\&\f(CW\*(C`git rebase\*(C'\fR will not have the \f(CW\*(C`\-\-rebase\-merges\*(C'\fR switch, instead you
+have to use the \f(CW\*(C`\-\-preserve\-merges\*(C'\fR switch.)
+.SS "Committing to maintenance versions"
+.IX Subsection "Committing to maintenance versions"
+Maintenance versions should only be altered to add critical bug fixes,
+see perlpolicy.
+.PP
+To commit to a maintenance version of perl, you need to create a local
+tracking branch:
+.PP
+.Vb 1
+\&  % git checkout \-\-track \-b maint\-5.005 origin/maint\-5.005
+.Ve
+.PP
+This creates a local branch named \f(CW\*(C`maint\-5.005\*(C'\fR, which tracks the
+remote branch \f(CW\*(C`origin/maint\-5.005\*(C'\fR. Then you can pull, commit, merge
+and push as before.
+.PP
+You can also cherry-pick commits from blead and another branch, by
+using the \f(CW\*(C`git cherry\-pick\*(C'\fR command. It is recommended to use the
+\&\fB\-x\fR option to \f(CW\*(C`git cherry\-pick\*(C'\fR in order to record the SHA1 of the
+original commit in the new commit message.
+.PP
+Before pushing any change to a maint version, make sure you've
+satisfied the steps in "Committing to blead" above.
+.SS "Using a smoke-me branch to test changes"
+.IX Subsection "Using a smoke-me branch to test changes"
+Sometimes a change affects code paths which you cannot test on the OSes
+which are directly available to you and it would be wise to have users
+on other OSes test the change before you commit it to blead.
+.PP
+Fortunately, there is a way to get your change smoke-tested on various
+OSes: push it to a "smoke-me" branch and wait for certain automated
+smoke-testers to report the results from their OSes.
+A "smoke-me" branch is identified by the branch name: specifically, as
+seen on github.com it must be a local branch whose first name
+component is precisely \f(CW\*(C`smoke\-me\*(C'\fR.
+.PP
+The procedure for doing this is roughly as follows (using the example of
+tonyc's smoke-me branch called win32stat):
+.PP
+First, make a local branch and switch to it:
+.PP
+.Vb 1
+\&  % git checkout \-b win32stat
+.Ve
+.PP
+Make some changes, build perl and test your changes, then commit them to
+your local branch. Then push your local branch to a remote smoke-me
+branch:
+.PP
+.Vb 1
+\&  % git push origin win32stat:smoke\-me/tonyc/win32stat
+.Ve
+.PP
+Now you can switch back to blead locally:
+.PP
+.Vb 1
+\&  % git checkout blead
+.Ve
+.PP
+and continue working on other things while you wait a day or two,
+keeping an eye on the results reported for your smoke-me branch at
+<http://perl.develop\-help.com/?b=smoke\-me/tonyc/win32state>.
+.PP
+If all is well then update your blead branch:
+.PP
+.Vb 1
+\&  % git pull
+.Ve
+.PP
+then checkout your smoke-me branch once more and rebase it on blead:
+.PP
+.Vb 1
+\&  % git rebase blead win32stat
+.Ve
+.PP
+Now switch back to blead and merge your smoke-me branch into it:
+.PP
+.Vb 2
+\&  % git checkout blead
+\&  % git merge win32stat
+.Ve
+.PP
+As described earlier, if there are many changes on your smoke-me branch
+then you should prepare a merge commit in which to give an overview of
+those changes by using the following command instead of the last
+command above:
+.PP
+.Vb 1
+\&  % git merge win32stat \-\-no\-ff \-\-no\-commit
+.Ve
+.PP
+You should now build perl and test your (merged) changes one last time
+(ideally run the whole test suite, but failing that at least run the
+\&\fIt/porting/*.t\fR tests) before pushing your changes as usual:
+.PP
+.Vb 1
+\&  % git push origin blead
+.Ve
+.PP
+Finally, you should then delete the remote smoke-me branch:
+.PP
+.Vb 1
+\&  % git push origin :smoke\-me/tonyc/win32stat
+.Ve
+.PP
+(which is likely to produce a warning like this, which can be ignored:
+.PP
+.Vb 4
+\& remote: fatal: ambiguous argument
+\&                                  \*(Aqrefs/heads/smoke\-me/tonyc/win32stat\*(Aq:
+\& unknown revision or path not in the working tree.
+\& remote: Use \*(Aq\-\-\*(Aq to separate paths from revisions
+.Ve
+.PP
+) and then delete your local branch:
+.PP
+.Vb 1
+\&  % git branch \-d win32stat
+.Ve
diff --git a/upstream/mageia-cauldron/man1/perlglossary.1 b/upstream/mageia-cauldron/man1/perlglossary.1
new file mode 100644
index 00000000..7f57973f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlglossary.1
@@ -0,0 +1,3678 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGLOSSARY 1"
+.TH PERLGLOSSARY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlglossary \- Perl Glossary
+.SH VERSION
+.IX Header "VERSION"
+version 5.20210520
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A glossary of terms (technical and otherwise) used in the Perl
+documentation, derived from the Glossary of \fIProgramming
+Perl\fR, Fourth Edition.  Words or phrases in bold are defined elsewhere in
+this glossary.
+.PP
+Other useful sources include the Unicode Glossary <http://unicode.org/glossary/>,
+the Free On-Line Dictionary of Computing <http://foldoc.org/>,
+the Jargon File <http://catb.org/~esr/jargon/>,
+and Wikipedia <http://www.wikipedia.org/>.
+.SS A
+.IX Subsection "A"
+.IP "accessor methods" 4
+.IX Item "accessor methods"
+A \fBmethod\fR used to
+indirectly inspect or update an \fBobject\fR’s state (its \fBinstance
+variables\fR).
+.IX Xref "accessor methods, defined methods, accessor"
+.IP "actual arguments" 4
+.IX Item "actual arguments"
+The \fBscalar values\fR that you supply
+to a \fBfunction\fR or \fBsubroutine\fR when you call it. For instance, when you
+call \f(CWpower("puff")\fR, the string \f(CW"puff"\fR is the actual argument. See also
+\&\fBargument\fR and \fBformal arguments\fR.
+.IX Xref "actual arguments arguments, actual"
+.IP "address operator" 4
+.IX Item "address operator"
+Some languages work directly with the memory addresses of
+values, but this can be like playing with fire. Perl provides a set of
+asbestos gloves for handling all memory management. The closest to an
+address operator in Perl is the backslash operator, but it gives you a
+\&\fBhard reference\fR, which is much safer than a memory address.
+.IX Xref "address operator"
+.IP algorithm 4
+.IX Item "algorithm"
+A well-defined sequence of steps, explained clearly
+enough that even a computer could do them.
+.IX Xref "algorithms (term)"
+.IP alias 4
+.IX Item "alias"
+A nickname for something, which behaves in all ways as
+though you’d used the original name instead of the nickname. Temporary
+aliases are implicitly created in the loop variable for \f(CW\*(C`foreach\*(C'\fR loops, in
+the \f(CW$_\fR variable for \f(CW\*(C`map\*(C'\fR or \f(CW\*(C`grep\*(C'\fR operators, in \f(CW$a\fR and \f(CW$b\fR
+during \f(CW\*(C`sort\*(C'\fR’s comparison function, and in each element of \f(CW@_\fR for the
+\&\fBactual arguments\fR of a subroutine call. Permanent aliases are explicitly
+created in \fBpackages\fR by \fBimporting\fR symbols or by assignment to
+\&\fBtypeglobs\fR. Lexically scoped aliases for package variables are explicitly
+created by the \f(CW\*(C`our\*(C'\fR declaration.
+.IX Xref "aliases, defined"
+.IP alphabetic 4
+.IX Item "alphabetic"
+The sort of characters we put into words. In Unicode, this
+is all letters including all ideographs and certain diacritics, letter
+numbers like Roman numerals, and various combining marks.
+.IX Xref "alphabetic sort"
+.IP alternatives 4
+.IX Item "alternatives"
+A list of possible choices from which you may
+select only one, as in, “Would you like door A, B, or C?� Alternatives in
+regular expressions are separated with a single vertical bar: \f(CW\*(C`|\*(C'\fR.
+Alternatives in normal Perl expressions are separated with a double vertical
+bar: \f(CW\*(C`||\*(C'\fR. Logical alternatives in \fBBoolean\fR expressions are separated
+with either \f(CW\*(C`||\*(C'\fR or \f(CW\*(C`or\*(C'\fR.
+.IX Xref "alternative characters"
+.IP anonymous 4
+.IX Item "anonymous"
+Used to describe a \fBreferent\fR
+that is not directly accessible through a named \fBvariable\fR. Such a referent
+must be indirectly accessible through at least one \fBhard reference\fR. When
+the last hard reference goes away, the anonymous referent is destroyed
+without pity.
+.IX Xref "anonymous referents referents, anonymous"
+.IP application 4
+.IX Item "application"
+A bigger, fancier sort of \fBprogram\fR with a fancier
+name so people don’t realize they are using a program.
+.IX Xref "applications (term)"
+.IP architecture 4
+.IX Item "architecture"
+The kind of computer you’re working on, where one “kind of
+computer� means all those computers sharing a compatible machine language.
+Since Perl programs are (typically) simple text files, not executable
+images, a Perl program is much less sensitive to the architecture it’s
+running on than programs in other languages, such as C, that are \fBcompiled\fR
+into machine code. See also \fBplatform\fR and \fBoperating system\fR.
+.IX Xref "architecture"
+.IP argument 4
+.IX Item "argument"
+A piece of data supplied to a \fBprogram\fR,
+\&\fBsubroutine\fR, \fBfunction\fR, or \fBmethod\fR to tell it what it’s supposed to
+do. Also called a “parameter�.
+.IX Xref "arguments, defined"
+.IP ARGV 4
+.IX Item "ARGV"
+The name of the array containing the \fBargument\fR \fBvector\fR
+from the command line. If you use the empty \f(CW\*(C`<>\*(C'\fR operator, \f(CW\*(C`ARGV\*(C'\fR
+is the name of both the \fBfilehandle\fR used to traverse the arguments and the
+\&\fBscalar\fR containing the name of the current input file.
+.IX Xref "ARGV filehandle"
+.IP "arithmetical operator" 4
+.IX Item "arithmetical operator"
+A \fBsymbol\fR such as \f(CW\*(C`+\*(C'\fR or \f(CW\*(C`/\*(C'\fR that tells
+Perl to do the arithmetic you were supposed to learn in grade school.
+.IX Xref "arithmetic operators, about"
+.IP array 4
+.IX Item "array"
+An ordered sequence of \fBvalues\fR, stored such that you can
+easily access any of the values using an \fIinteger subscript\fR that specifies
+the value’s \fBoffset\fR in the sequence.
+.IX Xref "arrays, defined"
+.IP "array context" 4
+.IX Item "array context"
+An archaic expression for what is more correctly referred to
+as \fBlist context\fR.
+.IX Xref "array context"
+.IP "Artistic License" 4
+.IX Item "Artistic License"
+The open source license that Larry Wall
+created for Perl, maximizing Perl’s usefulness, availability, and
+modifiability. The current version is 2. (<http://www.opensource.org/licenses/artistic\-license.php>).
+.IX Xref "Artistic License Wall, Larry"
+.IP ASCII 4
+.IX Item "ASCII"
+The American Standard Code for
+Information Interchange (a 7\-bit character set adequate only for poorly
+representing English text). Often used loosely to describe the lowest 128
+values of the various ISO\-8859\-X character sets, a bunch of mutually
+incompatible 8\-bit codes best described as half ASCII. See also \fBUnicode\fR.
+.IX Xref "ASCII (American Standard Code for Information Interchange) American Standard Code for Information Interchange (ASCII)"
+.IP assertion 4
+.IX Item "assertion"
+A component of a \fBregular expression\fR that must be true for the pattern to
+match but does not necessarily match any characters itself. Often used
+specifically to mean a \fBzero-width\fR assertion.
+.IX Xref "assertions (in regexes), defined regular expressions, assertions in"
+.IP assignment 4
+.IX Item "assignment"
+An \fBoperator\fR whose assigned mission in life is to
+change the value of a \fBvariable\fR.
+.IX Xref "assignments, defined"
+.IP "assignment operator" 4
+.IX Item "assignment operator"
+Either a regular \fBassignment\fR or a compound
+\&\fBoperator\fR composed of an ordinary assignment and some other operator, that
+changes the value of a variable in place; that is, relative to its old
+value. For example, \f(CW\*(C`$a += 2\*(C'\fR adds \f(CW2\fR to \f(CW$a\fR.
+.IX Xref "assignment operators, about"
+.IP "associative array" 4
+.IX Item "associative array"
+See \fBhash\fR. Please. The term associative array is the
+old Perl 4 term for a \fBhash\fR. Some languages call it a dictionary.
+.IX Xref "associative arrays"
+.IP associativity 4
+.IX Item "associativity"
+Determines whether you do the left \fBoperator\fR first or the
+right \fBoperator\fR first when you have “A \fBoperator\fR B \fBoperator\fR C�, and
+the two operators are of the same precedence. Operators like \f(CW\*(C`+\*(C'\fR are left
+associative, while operators like \f(CW\*(C`**\*(C'\fR are right associative. See Camel
+chapter 3, “Unary and Binary Operators� for a list of operators and their
+associativity.
+.IX Xref "associativity"
+.IP asynchronous 4
+.IX Item "asynchronous"
+Said of events or activities whose relative
+temporal ordering is indeterminate because too many things are going on at
+once. Hence, an asynchronous event is one you didn’t know when to expect.
+.IX Xref "asynchronous event processing"
+.IP atom 4
+.IX Item "atom"
+A \fBregular expression\fR component potentially matching a
+\&\fBsubstring\fR containing one or more characters and treated as an indivisible
+syntactic unit by any following \fBquantifier\fR. (Contrast with an
+\&\fBassertion\fR that matches something of \fBzero width\fR and may not be quantified.)
+.IX Xref "atoms"
+.IP "atomic operation" 4
+.IX Item "atomic operation"
+When Democritus gave the word “atom� to the indivisible
+bits of matter, he meant literally something that could not be cut: \fIá¼€\-\fR
+(not) + \fI\-τομος\fR (cuttable). An atomic operation is an action that can’t be
+interrupted, not one forbidden in a nuclear-free zone.
+.IX Xref "atomic operation"
+.IP attribute 4
+.IX Item "attribute"
+A new feature that allows the declaration of
+\&\fBvariables\fR and \fBsubroutines\fR with modifiers, as in \f(CW\*(C`sub foo : locked
+method\*(C'\fR. Also another name for an \fBinstance variable\fR of an \fBobject\fR.
+.IX Xref "attribute feature"
+.IP autogeneration 4
+.IX Item "autogeneration"
+A feature of \fBoperator overloading\fR of \fBobjects\fR,
+whereby the behavior of certain \fBoperators\fR can be reasonably deduced using
+more fundamental operators. This assumes that the overloaded operators will
+often have the same relationships as the regular operators. See Camel
+chapter 13, “Overloading�.
+.IX Xref "autogeneration, about"
+.IP autoincrement 4
+.IX Item "autoincrement"
+To add one to something automatically, hence the name
+of the \f(CW\*(C`++\*(C'\fR operator. To instead subtract one from something automatically
+is known as an “autodecrement�.
+.IX Xref "autoincrement (term)"
+.IP autoload 4
+.IX Item "autoload"
+To load on demand. (Also called “lazy� loading.)
+Specifically, to call an \f(CW\*(C`AUTOLOAD\*(C'\fR subroutine on behalf of an undefined
+subroutine.
+.IX Xref "autoloading, defined"
+.IP autosplit 4
+.IX Item "autosplit"
+To split a string automatically, as the \fI–a\fR \fBswitch\fR
+does when running under \fI–p\fR or \fI–n\fR in order to emulate \fBawk\fR. (See also
+the \f(CW\*(C`AutoSplit\*(C'\fR module, which has nothing to do with the
+\&\f(CW\*(C`–a\*(C'\fR switch but a lot to do with autoloading.)
+.IX Xref "autosplit (term) AutoSplit module"
+.IP autovivification 4
+.IX Item "autovivification"
+A Graeco-Roman word meaning “to bring oneself to life�.
+In Perl, storage locations (\fBlvalues\fR) spontaneously generate themselves as
+needed, including the creation of any \fBhard reference\fR values to point to
+the next level of storage. The assignment \f(CW\*(C`$a[5][5][5][5][5] = "quintet"\*(C'\fR
+potentially creates five scalar storage locations, plus four references (in
+the first four scalar locations) pointing to four new anonymous arrays (to
+hold the last four scalar locations). But the point of autovivification is
+that you don’t have to worry about it.
+.IX Xref "autovivification"
+.IP AV 4
+.IX Item "AV"
+Short for “array
+value�, which refers to one of Perl’s internal data types that holds an
+\&\fBarray\fR. The \f(CW\*(C`AV\*(C'\fR type is a subclass of \fBSV\fR.
+.IX Xref "AV (array value) array value (AV) values, array"
+.IP awk 4
+.IX Item "awk"
+Descriptive editing term—short for “awkward�. Also
+coincidentally refers to a venerable text-processing language from which
+Perl derived some of its high-level ideas.
+.IX Xref "awk (editing term)"
+.SS B
+.IX Subsection "B"
+.IP backreference 4
+.IX Item "backreference"
+A substring \fBcaptured\fR
+by a subpattern within unadorned parentheses in a \fBregex\fR. Backslashed
+decimal numbers (\f(CW\*(C`\e1\*(C'\fR, \f(CW\*(C`\e2\*(C'\fR, etc.) later in the same pattern refer back to
+the corresponding subpattern in the current match. Outside the pattern, the
+numbered variables (\f(CW$1\fR, \f(CW$2\fR, etc.) continue to refer to these same
+values, as long as the pattern was the last successful match of the current
+\&\fBdynamic scope\fR.
+.IX Xref "backreferences, about references, backreferences"
+.IP backtracking 4
+.IX Item "backtracking"
+The practice of saying, “If I had to do it all over, I’d do
+it differently,� and then actually going back and doing it all over
+differently. Mathematically speaking, it’s returning from an unsuccessful
+recursion on a tree of possibilities. Perl backtracks when it attempts to
+match patterns with a \fBregular expression\fR, and its earlier attempts don’t
+pan out. See the section “The Little Engine That /Couldn(n’t)� in Camel
+chapter 5, “Pattern Matching�.
+.IX Xref "backtracking"
+.IP "backward compatibility" 4
+.IX Item "backward compatibility"
+Means you can still run your old program
+because we didn’t break any of the features or bugs it was relying on.
+.IX Xref "backward compatibility, defined"
+.IP bareword 4
+.IX Item "bareword"
+A word sufficiently ambiguous to be deemed illegal under
+\&\f(CW\*(C`use strict \*(Aqsubs\*(Aq\*(C'\fR. In the absence of that stricture, a bareword is
+treated as if quotes were around it.
+.IX Xref "barewords, about"
+.IP "base class" 4
+.IX Item "base class"
+A generic \fBobject\fR type; that is, a \fBclass\fR
+from which other, more specific classes are derived genetically by
+\&\fBinheritance\fR. Also called a
+“superclass� by people who respect their ancestors.
+.IX Xref "base classes classes, base superclasses classes, superclasses"
+.IP big-endian 4
+.IX Item "big-endian"
+From Swift: someone who
+eats eggs big end first. Also used of computers that store the most
+significant \fBbyte\fR of a word at a lower byte address than the least
+significant byte. Often considered superior to little-endian machines. See
+also \fBlittle-endian\fR.
+.IX Xref "big–endian, defined endianness, big–endian"
+.IP binary 4
+.IX Item "binary"
+Having to do with numbers represented in base 2. That means
+there’s basically two numbers: 0 and 1. Also used to describe a file of
+“nontext�, presumably because such a file makes full use of all the binary
+bits in its bytes. With the advent of \fBUnicode\fR, this distinction, already
+suspect, loses even more of its meaning.
+.IX Xref "binary (term)"
+.IP "binary operator" 4
+.IX Item "binary operator"
+An \fBoperator\fR that takes two \fBoperands\fR.
+.IX Xref "binary operators, about"
+.IP bind 4
+.IX Item "bind"
+To assign a specific \fBnetwork address\fR to a \fBsocket\fR.
+.IX Xref "bind (term)"
+.IP bit 4
+.IX Item "bit"
+An integer in the range from 0 to 1, inclusive. The smallest
+possible unit of information storage. An eighth of a \fBbyte\fR or of a dollar.
+(The term “Pieces of Eight� comes from being able to split the old Spanish
+dollar into 8 bits, each of which still counted for money. That’s why a 25\-
+cent piece today is still “two bits�.)
+.IX Xref "bits, defined"
+.IP "bit shift" 4
+.IX Item "bit shift"
+The movement of bits left or right in a
+computer word, which has the effect of multiplying or dividing by a
+power of 2.
+.IX Xref "bit–shift operators, defined"
+.IP "bit string" 4
+.IX Item "bit string"
+A sequence of \fBbits\fR that is actually being thought of as a
+sequence of bits, for once.
+.IX Xref "bit string"
+.IP bless 4
+.IX Item "bless"
+In corporate life, to grant official
+approval to a thing, as in, “The VP of Engineering has blessed our
+WebCruncher project.� Similarly, in Perl, to grant official approval to a
+\&\fBreferent\fR so that it can function as an \fBobject\fR, such as a WebCruncher
+object. See the \f(CW\*(C`bless\*(C'\fR function in Camel chapter 27, “Functions�.
+.IX Xref "bless function, about bless (term)"
+.IP block 4
+.IX Item "block"
+What a \fBprocess\fR does when it has to wait for something:
+“My process blocked waiting for the disk.� As an unrelated noun, it refers
+to a large chunk of data, of a size that the \fBoperating system\fR likes to
+deal with (normally a power of 2 such as 512 or 8192). Typically refers to
+a chunk of data that’s coming from or going to a disk file.
+.IX Xref "blocks, defined"
+.IP BLOCK 4
+.IX Item "BLOCK"
+A syntactic construct
+consisting of a sequence of Perl \fBstatements\fR that is delimited by braces.
+The \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`while\*(C'\fR statements are defined in terms of \fR\f(CI\*(C`BLOCK\*(C'\fR\fI\fRs, for
+instance. Sometimes we also say “block� to mean a lexical scope; that is, a
+sequence of statements that acts like a \fI\fR\f(CI\*(C`BLOCK\*(C'\fR\fI\fR, such as within an
+\&\f(CW\*(C`eval\*(C'\fR or a file, even though the statements aren’t delimited by braces.
+.IX Xref "BLOCK construct, about constructs, BLOCK"
+.IP "block buffering" 4
+.IX Item "block buffering"
+A method of making input and output
+efficient by passing one \fBblock\fR at a time. By default, Perl does block
+buffering to disk files. See \fBbuffer\fR and \fBcommand buffering\fR.
+.IX Xref "block buffering buffering, block"
+.IP Boolean 4
+.IX Item "Boolean"
+A value that is either \fBtrue\fR or
+\&\fBfalse\fR.
+.IX Xref "Boolean values values, Boolean"
+.IP "Boolean context" 4
+.IX Item "Boolean context"
+A special kind of \fBscalar
+context\fR used in conditionals to decide whether the \fBscalar value\fR returned
+by an expression is \fBtrue\fR or \fBfalse\fR. Does not evaluate as either a
+string or a number. See \fBcontext\fR.
+.IX Xref "Boolean context, about context, Boolean"
+.IP breakpoint 4
+.IX Item "breakpoint"
+A spot in your program where you’ve told the debugger
+to stop \fBexecution\fR so you can poke around and see whether anything is
+wrong yet.
+.IX Xref "breakpoints, defined"
+.IP broadcast 4
+.IX Item "broadcast"
+To send a \fBdatagram\fR to multiple destinations
+simultaneously.
+.IX Xref "broadcast (networking term)"
+.IP BSD 4
+.IX Item "BSD"
+A psychoactive drug, popular in the ’80s, probably developed at UC
+Berkeley or thereabouts. Similar in many ways to the prescription-only
+medication called “System V�, but infinitely more useful. (Or, at least,
+more fun.) The full chemical name is “Berkeley Standard Distribution�.
+.IX Xref "BSD (Berkeley Standard Distribution) Berkeley Standard Distribution (BSD)"
+.IP bucket 4
+.IX Item "bucket"
+A location in a \fBhash table\fR containing (potentially)
+multiple entries whose keys “hash� to the same hash value according to its
+hash function. (As internal policy, you don’t have to worry about it unless
+you’re into internals, or policy.)
+.IX Xref "buckets (term)"
+.IP buffer 4
+.IX Item "buffer"
+A temporary holding location for data. Data that are
+\&\fBBlock buffering\fR means that the data is passed on to its destination
+whenever the buffer is full. \fBLine buffering\fR means that it’s passed on
+whenever a complete line is received. \fBCommand buffering\fR means that it’s
+passed every time you do a \f(CW\*(C`print\*(C'\fR command (or equivalent). If your output
+is unbuffered, the system processes it one byte at a time without the use of
+a holding area. This can be rather inefficient.
+.IX Xref "buffers, defined"
+.IP built-in 4
+.IX Item "built-in"
+A \fBfunction\fR that is predefined in the
+language. Even when hidden by \fBoverriding\fR, you can always get at a built\-
+in function by \fBqualifying\fR its name with the \f(CW\*(C`CORE::\*(C'\fR pseudopackage.
+.IX Xref "built–in functions, about"
+.IP bundle 4
+.IX Item "bundle"
+A group of related modules on \fBCPAN\fR. (Also sometimes
+refers to a group of command-line switches grouped into one \fBswitch
+cluster\fR.)
+.IX Xref "bundles (term)"
+.IP byte 4
+.IX Item "byte"
+A piece of data worth eight \fBbits\fR in most places.
+.IX Xref "bytes (term)"
+.IP bytecode 4
+.IX Item "bytecode"
+A pidgin-like lingo spoken among ’droids when they don’t wish to reveal
+their orientation (see \fBendian\fR). Named after some similar languages spoken
+(for similar reasons) between compilers and interpreters in the late 20áµ—Ê°
+century. These languages are characterized by representing everything as a
+nonarchitecture-dependent sequence of bytes.
+.SS C
+.IX Subsection "C"
+.IP C 4
+.IX Item "C"
+A language beloved by many for its inside-out \fBtype\fR
+definitions, inscrutable \fBprecedence\fR rules, and heavy \fBoverloading\fR of
+the function-call mechanism. (Well, actually, people first switched to C
+because they found lowercase identifiers easier to read than upper.) Perl is
+written in C, so it’s not surprising that Perl borrowed a few ideas from it.
+.IX Xref "C language, about"
+.IP cache 4
+.IX Item "cache"
+A data repository. Instead of computing expensive answers
+several times, compute it once and save the result.
+.IX Xref "cache (term)"
+.IP callback 4
+.IX Item "callback"
+A \fBhandler\fR that you register with some other part of your
+program in the hope that the other part of your program will \fBtrigger\fR your
+handler when some event of interest transpires.
+.IX Xref "callbacks"
+.IP "call by reference" 4
+.IX Item "call by reference"
+An \fBargument\fR\-passing mechanism in which the \fBformal arguments\fR refer directly to the
+\&\fBactual arguments\fR, and the \fBsubroutine\fR can change the actual arguments
+by changing the formal arguments. That is, the formal argument is an
+\&\fBalias\fR for the actual argument. See also \fBcall by value\fR.
+.IX Xref "call by reference references, call by reference mechanism"
+.IP "call by value" 4
+.IX Item "call by value"
+An \fBargument\fR\-passing mechanism in which the \fBformal
+arguments\fR refer to a copy of the \fBactual arguments\fR, and the
+\&\fBsubroutine\fR cannot change the actual arguments by changing the formal
+arguments. See also \fBcall by reference\fR.
+.IX Xref "call by value"
+.IP canonical 4
+.IX Item "canonical"
+Reduced to a standard form to facilitate comparison.
+.IX Xref "canonical (term)"
+.IP "capture variables" 4
+.IX Item "capture variables"
+The variables—such as \f(CW$1\fR and
+\&\f(CW$2\fR, and \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%– \*(C'\fR—that hold the text remembered in a pattern
+match. See Camel chapter 5, “Pattern Matching�.
+.IX Xref "capture variables variables, capture"
+.IP capturing 4
+.IX Item "capturing"
+The use of parentheses around a \fBsubpattern\fR in a
+\&\fBregular expression\fR to store the matched \fBsubstring\fR as a
+\&\fBbackreference\fR. (Captured strings are also returned as a list in \fBlist
+context\fR.) See Camel chapter 5, “Pattern Matching�.
+.IX Xref "capturing in pattern matching subpatterns, capturing pattern matching, capturing in"
+.IP "cargo cult" 4
+.IX Item "cargo cult"
+Copying and pasting code without understanding it, while
+superstitiously believing in its value. This term originated from
+preindustrial cultures dealing with the detritus of explorers and colonizers
+of technologically advanced cultures. See \fIThe Gods Must Be Crazy\fR.
+.IX Xref "cargo cult"
+.IP case 4
+.IX Item "case"
+A property of certain
+characters. Originally, typesetter stored capital letters in the upper of
+two cases and small letters in the lower one. Unicode recognizes three
+cases: \fBlowercase\fR (\fBcharacter property\fR \f(CW\*(C`\ep{lower}\*(C'\fR), \fBtitlecase\fR
+(\f(CW\*(C`\ep{title}\*(C'\fR), and \fBuppercase\fR (\f(CW\*(C`\ep{upper}\*(C'\fR). A fourth casemapping called
+\&\fBfoldcase\fR is not itself a distinct case, but it is used internally to
+implement \fBcasefolding\fR. Not all letters have case, and some nonletters
+have case.
+.IX Xref "case (character) characters, case considerations"
+.IP casefolding 4
+.IX Item "casefolding"
+Comparing or matching a string case-insensitively. In Perl, it
+is implemented with the \f(CW\*(C`/i\*(C'\fR pattern modifier, the \f(CW\*(C`fc\*(C'\fR function, and the
+\&\f(CW\*(C`\eF\*(C'\fR double-quote translation escape.
+.IX Xref "casefolding"
+.IP casemapping 4
+.IX Item "casemapping"
+The process of converting a string to one of the four Unicode
+\&\fBcasemaps\fR; in Perl, it is implemented with the \f(CW\*(C`fc\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR,
+and \f(CW\*(C`uc\*(C'\fR functions.
+.IX Xref "casemapping"
+.IP character 4
+.IX Item "character"
+The smallest individual element of a string. Computers
+store characters as integers, but Perl lets you operate on them as text. The
+integer used to represent a particular character is called that character’s
+\&\fBcodepoint\fR.
+.IX Xref "characters, defined"
+.IP "character class" 4
+.IX Item "character class"
+A square-bracketed list of
+characters used in a \fBregular expression\fR to indicate that any character
+of the set may occur at a given point. Loosely, any predefined set of
+characters so used.
+.IX Xref "character classes, about classes, character"
+.IP "character property" 4
+.IX Item "character property"
+A predefined \fBcharacter class\fR matchable by the \f(CW\*(C`\ep\*(C'\fR
+or \f(CW\*(C`\eP\*(C'\fR \fBmetasymbol\fR. \fBUnicode\fR defines hundreds of standard properties
+for every possible codepoint, and Perl defines a few of its own, too.
+.IX Xref "character property"
+.IP "circumfix operator" 4
+.IX Item "circumfix operator"
+An \fBoperator\fR that surrounds its \fBoperand\fR, like the
+angle operator, or parentheses, or a hug.
+.IX Xref "circumfix operator"
+.IP class 4
+.IX Item "class"
+A user-defined \fBtype\fR, implemented in Perl via a
+\&\fBpackage\fR that provides (either directly or by inheritance) \fBmethods\fR
+(that is, \fBsubroutines\fR) to handle \fBinstances\fR of the class (its
+\&\fBobjects\fR). See also \fBinheritance\fR.
+.IX Xref "classes, defined"
+.IP "class method" 4
+.IX Item "class method"
+A \fBmethod\fR whose \fBinvocant\fR is a
+\&\fBpackage\fR name, not an \fBobject\fR reference. A method associated with the
+class as a whole. Also see \fBinstance method\fR.
+.IX Xref "class methods methods, class"
+.IP client 4
+.IX Item "client"
+In networking, a \fBprocess\fR that
+initiates contact with a \fBserver\fR process in order to exchange data and
+perhaps receive a service.
+.IX Xref "clients, defined processes, client"
+.IP closure 4
+.IX Item "closure"
+An \fBanonymous\fR subroutine
+that, when a reference to it is generated at runtime, keeps track of the
+identities of externally visible \fBlexical variables\fR, even after those
+lexical variables have supposedly gone out of \fBscope\fR. They’re called
+“closures� because this sort of behavior gives mathematicians a sense of
+closure.
+.IX Xref "closure subroutines subroutines, closure"
+.IP cluster 4
+.IX Item "cluster"
+A parenthesized \fBsubpattern\fR
+used to group parts of a \fBregular expression\fR into a single \fBatom\fR.
+.IX Xref "clusters, defined subpatterns, cluster"
+.IP CODE 4
+.IX Item "CODE"
+The word returned by the \f(CW\*(C`ref\*(C'\fR
+function when you apply it to a reference to a subroutine. See also \fBCV\fR.
+.IX Xref "CODE (ref function) ref function, about"
+.IP "code generator" 4
+.IX Item "code generator"
+A system that writes code for you in a low-level
+language, such as code to implement the backend of a compiler. See \fBprogram
+generator\fR.
+.IX Xref "code generators, defined"
+.IP codepoint 4
+.IX Item "codepoint"
+The integer a computer uses to represent a given
+character. ASCII codepoints are in the range 0 to 127; Unicode codepoints
+are in the range 0 to 0x1F_FFFF; and Perl codepoints are in the range 0 to
+2³²−1 or 0 to 2��−1, depending on your native integer size. In Perl Culture,
+sometimes called \fBordinals\fR.
+.IX Xref "codepoints, about"
+.IP "code subpattern" 4
+.IX Item "code subpattern"
+A \fBregular expression\fR subpattern
+whose real purpose is to execute some Perl code—for example, the \f(CW\*(C`(?{...})\*(C'\fR
+and \f(CW\*(C`(??{...})\*(C'\fR subpatterns.
+.IX Xref "code subpatterns subpatterns, code"
+.IP "collating sequence" 4
+.IX Item "collating sequence"
+The order into which \fBcharacters\fR
+sort. This is used by \fBstring\fR comparison routines to decide, for example,
+where in this glossary to put “collating sequence�.
+.IX Xref "collating sequence collating sequence"
+.IP co-maintainer 4
+.IX Item "co-maintainer"
+A person with permissions to index a \fBnamespace\fR in
+\&\fBPAUSE\fR. Anyone can upload any namespace, but only primary and
+co-maintainers get their contributions indexed.
+.IX Xref "co–maintainers"
+.IP "combining character" 4
+.IX Item "combining character"
+Any character with the
+General Category of Combining Mark (\f(CW\*(C`\ep{GC=M}\*(C'\fR), which may be spacing or
+nonspacing. Some are even invisible. A sequence of combining characters
+following a grapheme base character together make up a single user-visible
+character called a \fBgrapheme\fR. Most but not all diacritics are combining
+characters, and vice versa.
+.IX Xref "combining characters characters, combining"
+.IP command 4
+.IX Item "command"
+In \fBshell\fR programming, the syntactic combination of a
+program name and its arguments. More loosely, anything you type to a shell
+(a command interpreter) that starts it doing something. Even more loosely, a
+Perl \fBstatement\fR, which might start with a \fBlabel\fR and typically ends with
+a semicolon.
+.IX Xref "commands, defined"
+.IP "command buffering" 4
+.IX Item "command buffering"
+A mechanism in Perl that lets you
+store up the output of each Perl \fBcommand\fR and then flush it out as a
+single request to the \fBoperating system\fR. It’s enabled by setting the \f(CW$|\fR
+(\f(CW$AUTOFLUSH\fR) variable to a true value. It’s used when you don’t want data
+sitting around, not going where it’s supposed to, which may happen because
+the default on a \fBfile\fR or \fBpipe\fR is to use \fBblock buffering\fR.
+.IX Xref "command buffering buffering, command"
+.IP "command-line arguments" 4
+.IX Item "command-line arguments"
+The \fBvalues\fR you supply
+along with a program name when you tell a \fBshell\fR to execute a \fBcommand\fR.
+These values are passed to a Perl program through \f(CW@ARGV\fR.
+.IX Xref "command–line arguments arguments, command–line"
+.IP "command name" 4
+.IX Item "command name"
+The name of the program currently executing, as typed on the
+command line. In C, the \fBcommand\fR name is passed to the program as the
+first command-line argument. In Perl, it comes in separately as \f(CW$0\fR.
+.IX Xref "command names"
+.IP comment 4
+.IX Item "comment"
+A remark that doesn’t affect the meaning of the program.
+In Perl, a comment is introduced by a \f(CW\*(C`#\*(C'\fR character and continues to the
+end of the line.
+.IX Xref "comments, defined"
+.IP "compilation unit" 4
+.IX Item "compilation unit"
+The \fBfile\fR (or \fBstring\fR, in the case of \f(CW\*(C`eval\*(C'\fR) that
+is currently being \fBcompiled\fR.
+.IX Xref "compilation units"
+.IP compile 4
+.IX Item "compile"
+The process of turning source code into a machine-usable form. See \fBcompile
+phase\fR.
+.IP "compile phase" 4
+.IX Item "compile phase"
+Any time before Perl starts running your main
+program. See also \fBrun phase\fR. Compile phase is mostly spent in \fBcompile
+time\fR, but may also be spent in \fBruntime\fR when \f(CW\*(C`BEGIN\*(C'\fR blocks, \f(CW\*(C`use\*(C'\fR or
+\&\f(CW\*(C`no\*(C'\fR declarations, or constant subexpressions are being evaluated. The
+startup and import code of any \f(CW\*(C`use\*(C'\fR declaration is also run during
+compile phase.
+.IX Xref "compile phase, defined"
+.IP compiler 4
+.IX Item "compiler"
+Strictly speaking, a program that munches
+up another program and spits out yet another file containing the program in
+a “more executable� form, typically containing native machine instructions.
+The \fIperl\fR program is not a compiler by this definition, but it does
+contain a kind of compiler that takes a program and turns it into a more
+executable form (\fBsyntax trees\fR) within the \fIperl\fR process itself, which
+the \fBinterpreter\fR then interprets. There are, however, extension \fBmodules\fR
+to get Perl to act more like a “real� compiler. See Camel chapter 16,
+“Compiling�.
+.IX Xref "compilers and compiling, about"
+.IP "compile time" 4
+.IX Item "compile time"
+The time when Perl is trying to make sense of your
+code, as opposed to when it thinks it knows what your code means and is
+merely trying to do what it thinks your code says to do, which is \fBruntime\fR.
+.IX Xref "compile time, defined"
+.IP composer 4
+.IX Item "composer"
+A “constructor� for a \fBreferent\fR that isn’t really an
+\&\fBobject\fR, like an anonymous array or a hash (or a sonata, for that matter).
+For example, a pair of braces acts as a composer for a hash, and a pair of
+brackets acts as a composer for an array. See the section “Creating
+References� in Camel chapter 8, “References�.
+.IX Xref "composers, about"
+.IP concatenation 4
+.IX Item "concatenation"
+The process of gluing one
+cat’s nose to another cat’s tail. Also a similar operation on two
+\&\fBstrings\fR.
+.IX Xref "concatenating strings strings, concatenating"
+.IP conditional 4
+.IX Item "conditional"
+Something “iffy�. See \fBBoolean context\fR.
+.IX Xref "conditional (term)"
+.IP connection 4
+.IX Item "connection"
+In telephony, the temporary electrical circuit between
+the caller’s and the callee’s phone. In networking, the same kind of
+temporary circuit between a \fBclient\fR and a \fBserver\fR.
+.IX Xref "connections (term)"
+.IP construct 4
+.IX Item "construct"
+As a noun, a piece of syntax made up of smaller
+pieces. As a transitive verb, to create an \fBobject\fR using a \fBconstructor\fR.
+.IX Xref "constructs, defined"
+.IP constructor 4
+.IX Item "constructor"
+Any \fBclass method\fR, \fBinstance\fR, or \fBsubroutine\fR
+that composes, initializes, blesses, and returns an \fBobject\fR. Sometimes we
+use the term loosely to mean a \fBcomposer\fR.
+.IX Xref "constructors, defined"
+.IP context 4
+.IX Item "context"
+The surroundings or environment. The context given by the
+surrounding code determines what kind of data a particular \fBexpression\fR is
+expected to return. The three primary contexts are \fBlist context\fR,
+\&\fBscalar\fR, and \fBvoid context\fR. Scalar context is sometimes subdivided into
+\&\fBBoolean context\fR, \fBnumeric context\fR, \fBstring context\fR, and \fBvoid
+context\fR. There’s also a “don’t care� context (which is dealt with in Camel
+chapter 2, “Bits and Pieces�, if you care).
+.IX Xref "context, about"
+.IP continuation 4
+.IX Item "continuation"
+The treatment of more than one physical \fBline\fR as a
+single logical line. \fBMakefile\fR lines are continued by putting a backslash
+before the \fBnewline\fR. Mail headers, as defined by RFC 822, are
+continued by putting a space or tab \fIafter\fR the newline. In general, lines
+in Perl do not need any form of continuation mark, because \fBwhitespace\fR
+(including newlines) is gleefully ignored. Usually.
+.IX Xref "continuation lines RFC 822"
+.IP "core dump" 4
+.IX Item "core dump"
+The corpse of a \fBprocess\fR, in the form of a file left in the
+\&\fBworking directory\fR of the process, usually as a result of certain kinds
+of fatal errors.
+.IX Xref "core dump"
+.IP CPAN 4
+.IX Item "CPAN"
+The Comprehensive Perl Archive Network. (See the Camel Preface
+and Camel chapter 19, “CPAN� for details.)
+.IX Xref "Comprehensive Perl Archive Network CPAN (Comprehensive Perl Archive Network), about"
+.IP "C preprocessor" 4
+.IX Item "C preprocessor"
+The typical C compiler’s first pass, which processes lines
+beginning with \f(CW\*(C`#\*(C'\fR for conditional compilation and macro definition, and
+does various manipulations of the program text based on the current
+definitions. Also known as \fIcpp\fR(1).
+.IX Xref "C preprocessor"
+.IP cracker 4
+.IX Item "cracker"
+Someone who breaks security on computer systems. A cracker may
+be a true \fBhacker\fR or only a \fBscript kiddie\fR.
+.IX Xref "crackers"
+.IP "currently selected output channel" 4
+.IX Item "currently selected output channel"
+The last \fBfilehandle\fR that was
+designated with \f(CWselect(FILEHANDLE)\fR; \f(CW\*(C`STDOUT\*(C'\fR, if no filehandle has
+been selected.
+.IX Xref "currently selected output channel"
+.IP "current package" 4
+.IX Item "current package"
+The \fBpackage\fR in which the current statement is
+\&\fBcompiled\fR. Scan backward in the text of your program through the current
+\&\fBlexical scope\fR or any enclosing lexical scopes until you find a package
+declaration. That’s your current package name.
+.IX Xref "current package"
+.IP "current working directory" 4
+.IX Item "current working directory"
+See \fBworking directory\fR.
+.IX Xref "current working directory"
+.IP CV 4
+.IX Item "CV"
+In academia, a curriculum vitæ, a fancy kind of résumé. In Perl, an internal “code value� typedef holding a
+\&\fBsubroutine\fR. The \f(CW\*(C`CV\*(C'\fR type is a subclass of \fBSV\fR.
+.IX Xref "CV (code value) code value (CV)"
+.SS D
+.IX Subsection "D"
+.IP "dangling statement" 4
+.IX Item "dangling statement"
+A bare, single \fBstatement\fR,
+without any braces, hanging off an \f(CW\*(C`if\*(C'\fR or \f(CW\*(C`while\*(C'\fR conditional. C allows
+them. Perl doesn’t.
+.IX Xref "dangling statements statements, dangling"
+.IP datagram 4
+.IX Item "datagram"
+A packet of data, such as a \fBUDP\fR message, that (from
+the viewpoint of the programs involved) can be sent independently over the
+network. (In fact, all packets are sent independently at the \fBIP\fR level,
+but \fBstream\fR protocols such as \fBTCP\fR hide this from your program.)
+.IX Xref "datagrams, defined"
+.IP "data structure" 4
+.IX Item "data structure"
+How your various pieces of data relate to each
+other and what shape they make when you put them all together, as in a
+rectangular table or a triangular tree.
+.IX Xref "data structures, defined"
+.IP "data type" 4
+.IX Item "data type"
+A set of possible values, together with all the
+operations that know how to deal with those values. For example, a numeric
+data type has a certain set of numbers that you can work with, as well as
+various mathematical operations that you can do on the numbers, but would
+make little sense on, say, a string such as \f(CW"Kilroy"\fR. Strings have their
+own operations, such as \fBconcatenation\fR. Compound types made of a number of
+smaller pieces generally have operations to compose and decompose them, and
+perhaps to rearrange them. \fBObjects\fR that model things in the real world
+often have operations that correspond to real activities. For instance, if
+you model an elevator, your elevator object might have an \f(CW\*(C`open_door\*(C'\fR
+\&\fBmethod\fR.
+.IX Xref "data types, defined"
+.IP DBM 4
+.IX Item "DBM"
+Stands for “Database Management� routines, a set of routines that emulate an
+\&\fBassociative array\fR using disk files. The routines use a dynamic hashing
+scheme to locate any entry with only two disk accesses. DBM files allow a
+Perl program to keep a persistent \fBhash\fR across multiple invocations. You
+can \f(CW\*(C`tie\*(C'\fR your hash variables to various DBM implementations.
+.IX Xref "DBM (Database Management) routines Database Management (DBM) routines"
+.IP declaration 4
+.IX Item "declaration"
+An \fBassertion\fR that states something exists and
+perhaps describes what it’s like, without giving any commitment as to how
+or where you’ll use it. A declaration is like the part of your recipe that
+says, “two cups flour, one large egg, four or five tadpoles…� See
+\&\fBstatement\fR for its opposite. Note that some declarations also function
+as statements. Subroutine declarations also act as definitions if a body
+is supplied.
+.IX Xref "declarations, defined"
+.IP declarator 4
+.IX Item "declarator"
+Something that tells your program what sort of variable
+you’d like. Perl doesn’t require you to declare variables, but you can use
+\&\f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, or \f(CW\*(C`state\*(C'\fR to denote that you want something other than
+the default.
+.IX Xref "declarators"
+.IP decrement 4
+.IX Item "decrement"
+To subtract a value from a
+variable, as in “decrement \f(CW$x\fR� (meaning to remove 1 from its value) or
+“decrement \f(CW$x\fR by 3�.
+.IX Xref "decrementing values values, decrementing"
+.IP default 4
+.IX Item "default"
+A \fBvalue\fR chosen for you if you don’t
+supply a value of your own.
+.IX Xref "default values values, default"
+.IP defined 4
+.IX Item "defined"
+Having a meaning. Perl thinks that some of the things
+people try to do are devoid of meaning; in particular, making use of
+variables that have never been given a \fBvalue\fR and performing certain
+operations on data that isn’t there. For example, if you try to read data
+past the end of a file, Perl will hand you back an undefined value. See also
+\&\fBfalse\fR and the \f(CW\*(C`defined\*(C'\fR entry in Camel chapter 27, “Functions�.
+.IX Xref "defined (term)"
+.IP delimiter 4
+.IX Item "delimiter"
+A \fBcharacter\fR or \fBstring\fR that sets bounds to an
+arbitrarily sized textual object, not to be confused with a \fBseparator\fR or
+\&\fBterminator\fR. “To delimit� really just means “to surround� or “to enclose�
+(like these parentheses are doing).
+.IX Xref "delimiters (term)"
+.IP dereference 4
+.IX Item "dereference"
+A fancy computer science term
+meaning “to follow a \fBreference\fR to what it points to�. The “de� part of it
+refers to the fact that you’re taking away one level of \fBindirection\fR.
+.IX Xref "dereference (term) references, dereference"
+.IP "derived class" 4
+.IX Item "derived class"
+A \fBclass\fR that defines some of its \fBmethods\fR in terms of a more generic class,
+called a \fBbase class\fR. Note that classes aren’t classified exclusively into
+base classes or derived classes: a class can function as both a derived
+class and a base class simultaneously, which is kind of classy.
+.IX Xref "derived classes classes, derived subclasses classes, subclasses"
+.IP descriptor 4
+.IX Item "descriptor"
+See \fBfile descriptor\fR.
+.IP destroy 4
+.IX Item "destroy"
+To deallocate the memory of a \fBreferent\fR (first triggering
+its \f(CW\*(C`DESTROY\*(C'\fR method, if it has one).
+.IX Xref "destroy (term)"
+.IP destructor 4
+.IX Item "destructor"
+A special \fBmethod\fR that is called
+when an \fBobject\fR is thinking about \fBdestroying\fR itself. A Perl program’s
+\&\f(CW\*(C`DESTROY\*(C'\fR method doesn’t do the actual destruction; Perl just \fBtriggers\fR
+the method in case the \fBclass\fR wants to do any associated cleanup.
+.IX Xref "destructor method methods, destructor"
+.IP device 4
+.IX Item "device"
+A whiz-bang hardware gizmo (like a disk or tape drive or a
+modem or a joystick or a mouse) attached to your computer, which the
+\&\fBoperating system\fR tries to make look like a \fBfile\fR (or a bunch of files).
+Under Unix, these fake files tend to live in the \fI/dev\fR directory.
+.IX Xref "devices (term)"
+.IP directive 4
+.IX Item "directive"
+A \fBpod\fR directive. See Camel chapter 23, “Plain Old
+Documentation�.
+.IX Xref "directives, defined"
+.IP directory 4
+.IX Item "directory"
+A special file that contains other files. Some
+\&\fBoperating systems\fR call these “folders�, “drawers�, “catalogues�, or
+“catalogs�.
+.IX Xref "directories, defined"
+.IP "directory handle" 4
+.IX Item "directory handle"
+A name that represents a particular instance of opening a
+directory to read it, until you close it. See the \f(CW\*(C`opendir\*(C'\fR function.
+.IX Xref "directory handle"
+.IP discipline 4
+.IX Item "discipline"
+Some people need this and some people avoid it.
+For Perl, it’s an old way to say \fBI/O layer\fR.
+.IX Xref "discipline (I O layer)"
+.IP dispatch 4
+.IX Item "dispatch"
+To send something to its correct destination. Often used
+metaphorically to indicate a transfer of programmatic control to a
+destination selected algorithmically, often by lookup in a table of function
+\&\fBreferences\fR or, in the case of object \fBmethods\fR, by traversing the
+inheritance tree looking for the most specific definition for the method.
+.IX Xref "dispatching"
+.IP distribution 4
+.IX Item "distribution"
+A standard, bundled release of a system of
+software. The default usage implies source code is included. If that is not
+the case, it will be called a “binary\-only� distribution.
+.IX Xref "distributions, defined"
+.IP dual-lived 4
+.IX Item "dual-lived"
+Some modules live both in the
+\&\fBStandard Library\fR and on \fBCPAN\fR. These modules might be developed on two
+tracks as people modify either version. The trend currently is to untangle
+these situations.
+.IX Xref "dual–lived modules modules, dual–lived"
+.IP dweomer 4
+.IX Item "dweomer"
+An enchantment, illusion, phantasm, or jugglery. Said when Perl’s
+magical \fBdwimmer\fR effects don’t do what you expect, but rather seem to be
+the product of arcane \fIdweomercraft\fR, sorcery, or wonder working. [From
+Middle English.]
+.IX Xref "dweomer"
+.IP dwimmer 4
+.IX Item "dwimmer"
+DWIM is
+an acronym for “Do What I Mean�, the principle that something
+should just do what you want it to do without an undue amount of fuss. A bit
+of code that does “dwimming� is a “dwimmer�. Dwimming can require a great
+deal of behind-the-scenes magic, which (if it doesn’t stay properly behind
+the scenes) is called a \fBdweomer\fR instead.
+.IX Xref "DWIM (Do What I Mean) principle Do What I Mean (DWIM) principle dwimming"
+.IP "dynamic scoping" 4
+.IX Item "dynamic scoping"
+Dynamic scoping works over a \fBdynamic
+scope\fR, making variables visible throughout the rest of the \fBblock\fR in
+which they are first used and in any \fBsubroutines\fR that are called by the
+rest of the block. Dynamically scoped variables can have their values
+temporarily changed (and implicitly restored later) by a \f(CW\*(C`local\*(C'\fR operator.
+(Compare \fBlexical scoping\fR.) Used more loosely to mean how a subroutine
+that is in the middle of calling another subroutine “contains� that
+subroutine at \fBruntime\fR.
+.IX Xref "dynamic scope scopes, dynamic"
+.SS E
+.IX Subsection "E"
+.IP eclectic 4
+.IX Item "eclectic"
+Derived from many sources. Some would say \fItoo\fR many.
+.IX Xref "eclectic (term)"
+.IP element 4
+.IX Item "element"
+A basic building block. When you’re talking about an
+\&\fBarray\fR, it’s one of the items that make up the array.
+.IX Xref "elements, about"
+.IP embedding 4
+.IX Item "embedding"
+When something is contained in something else,
+particularly when that might be considered surprising: “I’ve embedded a
+complete Perl interpreter in my editor!�
+.IX Xref "embedding (term)"
+.IP "empty subclass test" 4
+.IX Item "empty subclass test"
+The notion that an empty \fBderived class\fR should
+behave exactly like its \fBbase class\fR.
+.IX Xref "empty subclass test"
+.IP encapsulation 4
+.IX Item "encapsulation"
+The veil of abstraction separating the \fBinterface\fR
+from the \fBimplementation\fR (whether enforced or not), which mandates that
+all access to an \fBobject\fR’s state be through \fBmethods\fR alone.
+.IX Xref "encapsulation (term)"
+.IP endian 4
+.IX Item "endian"
+See \fBlittle-endian\fR and \fBbig-endian\fR.
+.IP "en passant" 4
+.IX Item "en passant"
+When you change a \fBvalue\fR as it is being copied. [From
+French “in passing�, as in the exotic pawn-capturing maneuver in chess.]
+.IX Xref "en passant (term)"
+.IP environment 4
+.IX Item "environment"
+The collective set of \fBenvironment variables\fR your
+\&\fBprocess\fR inherits from its parent. Accessed via \f(CW%ENV\fR.
+.IX Xref "environment (term)"
+.IP "environment variable" 4
+.IX Item "environment variable"
+A mechanism by which some high-level agent such as a user can pass its
+preferences down to its future offspring (child \fBprocesses\fR, grandchild
+processes, great-grandchild processes, and so on). Each environment
+variable is a \fBkey\fR/\fBvalue\fR pair, like one entry in a \fBhash\fR.
+.IX Xref "environment variables variables, environment environment variables"
+.IP EOF 4
+.IX Item "EOF"
+End of File. Sometimes used
+metaphorically as the terminating string of a \fBhere document\fR.
+.IX Xref "End of File (EOF) EOF (End of File)"
+.IP errno 4
+.IX Item "errno"
+The error number returned by a
+\&\fBsyscall\fR when it fails. Perl refers to the error by the name \f(CW$!\fR (or
+\&\f(CW$OS_ERROR\fR if you use the English module).
+.IX Xref "errno (error number) error number (errno)"
+.IP error 4
+.IX Item "error"
+See \fBexception\fR or \fBfatal error\fR.
+.IP "escape sequence" 4
+.IX Item "escape sequence"
+See \fBmetasymbol\fR.
+.IP exception 4
+.IX Item "exception"
+A fancy term for an error. See \fBfatal error\fR.
+.IP "exception handling" 4
+.IX Item "exception handling"
+The way a program responds to an error. The
+exception-handling mechanism in Perl is the \f(CW\*(C`eval\*(C'\fR operator.
+.IX Xref "exception handling, defined"
+.IP exec 4
+.IX Item "exec"
+To throw away the current \fBprocess\fR’s program and replace
+it with another, without exiting the process or relinquishing any resources
+held (apart from the old memory image).
+.IX Xref "exec function"
+.IP "executable file" 4
+.IX Item "executable file"
+A \fBfile\fR that is specially marked to
+tell the \fBoperating system\fR that it’s okay to run this file as a program.
+Usually shortened to “executable�.
+.IX Xref "executable files files, executable"
+.IP execute 4
+.IX Item "execute"
+To run a \fBprogram\fR or \fBsubroutine\fR. (Has nothing to do
+with the \f(CW\*(C`kill\*(C'\fR built-in, unless you’re trying to run a \fBsignal handler\fR.)
+.IX Xref "execute (term)"
+.IP "execute bit" 4
+.IX Item "execute bit"
+The special mark that tells the operating system it can run
+this program. There are actually three execute bits under Unix, and which
+bit gets used depends on whether you own the file singularly, collectively,
+or not at all.
+.IX Xref "execute bit"
+.IP "exit status" 4
+.IX Item "exit status"
+See \fBstatus\fR.
+.IP exploit 4
+.IX Item "exploit"
+Used as a noun in this case, this refers to a known way
+to compromise a program to get it to do something the author didn’t intend.
+Your task is to write unexploitable programs.
+.IX Xref "exploits, security"
+.IP export 4
+.IX Item "export"
+To make symbols from a \fBmodule\fR available for
+\&\fBimport\fR by other modules.
+.IX Xref "exporting, defined"
+.IP expression 4
+.IX Item "expression"
+Anything you can legally say in a spot
+where a \fBvalue\fR is required. Typically composed of \fBliterals\fR,
+\&\fBvariables\fR, \fBoperators\fR, \fBfunctions\fR, and \fBsubroutine\fR calls, not
+necessarily in that order.
+.IX Xref "expressions, defined expressions"
+.IP extension 4
+.IX Item "extension"
+A Perl module that also pulls in \fBcompiled\fR C or C++
+code. More generally, any experimental option that can be \fBcompiled\fR into
+Perl, such as multithreading.
+.IX Xref "extensions, defined"
+.SS F
+.IX Subsection "F"
+.IP false 4
+.IX Item "false"
+In Perl, any value that would look like \f(CW""\fR
+or \f(CW"0"\fR if evaluated in a string context. Since undefined values evaluate
+to \f(CW""\fR, all undefined values are false, but not all false values are
+undefined.
+.IX Xref "false values values, false"
+.IP FAQ 4
+.IX Item "FAQ"
+Frequently Asked Question (although not necessarily
+frequently answered, especially if the answer appears in the Perl FAQ
+shipped standard with Perl).
+.IX Xref "FAQ (Frequently Asked Question) Frequently Asked Question (FAQ)"
+.IP "fatal error" 4
+.IX Item "fatal error"
+An uncaught \fBexception\fR, which causes termination of the
+\&\fBprocess\fR after printing a message on your \fBstandard error\fR stream. Errors
+that happen inside an \f(CW\*(C`eval\*(C'\fR are not fatal. Instead, the \f(CW\*(C`eval\*(C'\fR terminates
+after placing the exception message in the \f(CW$@\fR (\f(CW$EVAL_ERROR\fR) variable.
+You can try to provoke a fatal error with the \f(CW\*(C`die\*(C'\fR operator (known as
+throwing or raising an exception), but this may be caught by a dynamically
+enclosing \f(CW\*(C`eval\*(C'\fR. If not caught, the \f(CW\*(C`die\*(C'\fR becomes a fatal error.
+.IX Xref "fatal errors"
+.IP "feeping creaturism" 4
+.IX Item "feeping creaturism"
+A spoonerism of “creeping
+featurism�, noting the biological urge to add just one more feature to
+a program.
+.IX Xref "feeping creaturism creeping featurism"
+.IP field 4
+.IX Item "field"
+A single piece of numeric or string data that is part of a
+longer \fBstring\fR, \fBrecord\fR, or \fBline\fR. Variable-width fields are usually
+split up by \fBseparators\fR (so use \f(CW\*(C`split\*(C'\fR to extract the fields), while
+fixed-width fields are usually at fixed positions (so use \f(CW\*(C`unpack\*(C'\fR).
+\&\fBInstance variables\fR are also known as “fields�.
+.IX Xref "fields (term)"
+.IP FIFO 4
+.IX Item "FIFO"
+First In, First Out. See also \fBLIFO\fR. Also a nickname for a \fBnamed pipe\fR.
+.IX Xref "First In, First Out (FIFO) FIFO (First In, First Out)"
+.IP file 4
+.IX Item "file"
+A named collection of data, usually stored on disk in a
+\&\fBdirectory\fR in a \fBfilesystem\fR. Roughly like a document, if you’re into
+office metaphors. In modern filesystems, you can actually give a file more
+than one name. Some files have special properties, like directories and
+devices.
+.IX Xref "files, defined"
+.IP "file descriptor" 4
+.IX Item "file descriptor"
+The little number the \fBoperating
+system\fR uses to keep track of which opened \fBfile\fR you’re talking about.
+Perl hides the file descriptor inside a \fBstandard I/O\fR stream and then
+attaches the stream to a \fBfilehandle\fR.
+.IX Xref "file descriptors descriptors, file"
+.IP fileglob 4
+.IX Item "fileglob"
+A “wildcard� match on \fBfilenames\fR. See the \f(CW\*(C`glob\*(C'\fR function.
+.IX Xref "fileglobs"
+.IP filehandle 4
+.IX Item "filehandle"
+An identifier (not necessarily related to the real
+name of a file) that represents a particular instance of opening a file,
+until you close it. If you’re going to open and close several different
+files in succession, it’s fine to open each of them with the same
+filehandle, so you don’t have to write out separate code to process each
+file.
+.IX Xref "filehandles, about"
+.IP filename 4
+.IX Item "filename"
+One name for a file. This name is listed in a
+\&\fBdirectory\fR. You can use it in an \f(CW\*(C`open\*(C'\fR to tell the \fBoperating system\fR
+exactly which file you want to open, and associate the file with a
+\&\fBfilehandle\fR, which will carry the subsequent identity of that file in
+your program, until you close it.
+.IX Xref "filenames, about"
+.IP filesystem 4
+.IX Item "filesystem"
+A set of \fBdirectories\fR and \fBfiles\fR residing on a
+partition of the disk. Sometimes known as a “partition�. You can change the
+file’s name or even move a file around from directory to directory within a
+filesystem without actually moving the file itself, at least under Unix.
+.IX Xref "filesystems, defined"
+.IP "file test operator" 4
+.IX Item "file test operator"
+A built-in unary operator that you use to
+determine whether something is \fBtrue\fR about a file, such as \f(CW–o
+$filename\fR to test whether you’re the owner of the file.
+.IX Xref "file test operators, about"
+.IP filter 4
+.IX Item "filter"
+A program designed to take a \fBstream\fR of input and
+transform it into a stream of output.
+.IX Xref "filters, defined"
+.IP first-come 4
+.IX Item "first-come"
+The first \fBPAUSE\fR
+author to upload a \fBnamespace\fR automatically becomes the \fBprimary
+maintainer\fR for that namespace. The “first come� permissions distinguish a
+\&\fBprimary maintainer\fR who was assigned that role from one who received it
+automatically.
+.IX Xref "first–come permissions permissions, first–come"
+.IP flag 4
+.IX Item "flag"
+We tend to avoid this term because it means so many things.
+It may mean a command-line \fBswitch\fR that takes no argument itself (such as
+Perl’s \f(CW\*(C`–n\*(C'\fR and \f(CW\*(C`–p\*(C'\fR flags) or, less frequently, a single-bit indicator
+(such as the \f(CW\*(C`O_CREAT\*(C'\fR and \f(CW\*(C`O_EXCL\*(C'\fR flags used in \f(CW\*(C`sysopen\*(C'\fR). Sometimes
+informally used to refer to certain regex modifiers.
+.IX Xref "flags (term)"
+.IP "floating point" 4
+.IX Item "floating point"
+A method of storing
+numbers in “scientific notation�, such that the precision of the number is
+independent of its magnitude (the decimal point “floats�). Perl does its
+numeric work with floating-point numbers (sometimes called “floats�) when
+it can’t get away with using \fBintegers\fR. Floating-point numbers are mere
+approximations of real numbers.
+.IX Xref "floating point methods methods, floating point"
+.IP flush 4
+.IX Item "flush"
+The act of emptying a \fBbuffer\fR,
+often before it’s full.
+.IX Xref "flushing buffers buffers, flushing"
+.IP FMTEYEWTK 4
+.IX Item "FMTEYEWTK"
+Far More Than Everything You Ever Wanted To Know. An
+exhaustive treatise on one narrow topic, something of a super\-\fBFAQ\fR. See
+Tom for far more.
+.IX Xref "FMTEYEWTK acronym"
+.IP foldcase 4
+.IX Item "foldcase"
+The casemap used in Unicode when comparing or matching
+without regard to case. Comparing lower\-, title\-, or uppercase are all
+unreliable due to Unicode’s complex, one-to-many case mappings. Foldcase is
+a \fBlowercase\fR variant (using a partially decomposed \fBnormalization\fR form
+for certain codepoints) created specifically to resolve this.
+.IX Xref "foldcase (term)"
+.IP fork 4
+.IX Item "fork"
+To create a child \fBprocess\fR
+identical to the parent process at its moment of conception, at least until
+it gets ideas of its own. A thread with protected memory.
+.IX Xref "forking processes processes, forking"
+.IP "formal arguments" 4
+.IX Item "formal arguments"
+The generic names by which a
+\&\fBsubroutine\fR knows its \fBarguments\fR. In many languages, formal arguments
+are always given individual names; in Perl, the formal arguments are just
+the elements of an array. The formal arguments to a Perl program are
+\&\f(CW$ARGV[0]\fR, \f(CW$ARGV[1]\fR, and so on. Similarly, the formal arguments to a
+Perl subroutine are \f(CW$_[0]\fR, \f(CW$_[1]\fR, and so on. You may give the
+arguments individual names by assigning the values to a \f(CW\*(C`my\*(C'\fR list. See
+also \fBactual arguments\fR.
+.IX Xref "formal arguments arguments, formal"
+.IP format 4
+.IX Item "format"
+A specification of how many spaces and digits and things
+to put somewhere so that whatever you’re printing comes out nice and
+pretty.
+.IX Xref "formats, defined"
+.IP "freely available" 4
+.IX Item "freely available"
+Means you don’t have to pay money to get it, but
+the copyright on it may still belong to someone else (like Larry).
+.IX Xref "freely available (term)"
+.IP "freely redistributable" 4
+.IX Item "freely redistributable"
+Means you’re not in legal trouble if you
+give a bootleg copy of it to your friends and we find out about it. In
+fact, we’d rather you gave a copy to all your friends.
+.IX Xref "freely redistributable (term)"
+.IP freeware 4
+.IX Item "freeware"
+Historically, any software that you give away,
+particularly if you make the source code available as well. Now often
+called \fBopen source software\fR. Recently there has been a trend to use the
+term in contradistinction to \fBopen source software\fR, to refer only to free
+software released under the Free Software
+Foundation’s GPL (General Public License), but this is difficult to justify
+etymologically.
+.IX Xref "freeware (term) Free Software Foundation"
+.IP function 4
+.IX Item "function"
+Mathematically, a mapping of each of a set of input
+values to a particular output value. In computers, refers to a
+\&\fBsubroutine\fR or \fBoperator\fR that returns a \fBvalue\fR. It may or may not
+have input values (called \fBarguments\fR).
+.IX Xref "functions, about"
+.IP "funny character" 4
+.IX Item "funny character"
+Someone like Larry, or one of his
+peculiar friends. Also refers to the strange prefixes that Perl requires as
+noun markers on its variables.
+.IX Xref "funny characters characters, funny"
+.SS G
+.IX Subsection "G"
+.IP "garbage collection" 4
+.IX Item "garbage collection"
+A misnamed feature—it should be called,
+“expecting your mother to pick up after you�. Strictly speaking, Perl
+doesn’t do this, but it relies on a reference-counting mechanism to keep
+things tidy. However, we rarely speak strictly and will often refer to the
+reference-counting scheme as a form of garbage collection. (If it’s any
+comfort, when your interpreter exits, a “real� garbage collector runs to
+make sure everything is cleaned up if you’ve been messy with circular
+references and such.)
+.IX Xref "garbage collection, defined"
+.IP GID 4
+.IX Item "GID"
+Group ID—in Unix, the numeric group ID
+that the \fBoperating system\fR uses to identify you and members of your
+\&\fBgroup\fR.
+.IX Xref "GID (Group ID) Group ID (GID)"
+.IP glob 4
+.IX Item "glob"
+Strictly, the shell’s \f(CW\*(C`*\*(C'\fR character, which will match
+a “glob� of characters when you’re trying to generate a list of filenames.
+Loosely, the act of using globs and similar symbols to do pattern matching.
+See also \fBfileglob\fR and \fBtypeglob\fR.
+.IX Xref "glob (* character)"
+.IP global 4
+.IX Item "global"
+Something you can see from anywhere, usually used of
+\&\fBvariables\fR and \fBsubroutines\fR that are visible everywhere in your
+program.  In Perl, only certain special variables are truly global—most
+variables (and all subroutines) exist only in the current \fBpackage\fR.
+Global variables can be declared with \f(CW\*(C`our\*(C'\fR. See “Global Declarations� in
+Camel chapter 4, “Statements and Declarations�.
+.IX Xref "global (term)"
+.IP "global destruction" 4
+.IX Item "global destruction"
+The \fBgarbage collection\fR of globals (and the running
+of any associated object destructors) that takes place when a Perl
+\&\fBinterpreter\fR is being shut down. Global destruction should not be
+confused with the Apocalypse, except perhaps when it should.
+.IX Xref "global destruction"
+.IP "glue language" 4
+.IX Item "glue language"
+A language such as Perl that is good at hooking things
+together that weren’t intended to be hooked together.
+.IX Xref "glue language"
+.IP granularity 4
+.IX Item "granularity"
+The size of the pieces you’re dealing with, mentally
+speaking.
+.IX Xref "granularity"
+.IP grapheme 4
+.IX Item "grapheme"
+A graphene is an allotrope of carbon arranged in a
+hexagonal crystal lattice one atom thick. A \fBgrapheme\fR, or more fully, a
+\&\fIgrapheme cluster string\fR is a single user-visible \fBcharacter\fR, which may
+in turn be several characters (\fBcodepoints\fR) long. For example, a carriage
+return plus a line feed is a single grapheme but two characters, while a
+“ȫ� is a single grapheme but one, two, or even three characters, depending
+on \fBnormalization\fR.
+.IX Xref "graphemes, defined"
+.IP greedy 4
+.IX Item "greedy"
+A \fBsubpattern\fR whose
+\&\fBquantifier\fR wants to match as many things as possible.
+.IX Xref "greedy subpatterns subpatterns, greedy"
+.IP grep 4
+.IX Item "grep"
+Originally from the old Unix editor command for “Globally
+search for a Regular Expression and Print it�, now used in the general
+sense of any kind of search, especially text searches. Perl has a built-in
+\&\f(CW\*(C`grep\*(C'\fR function that searches a list for elements matching any given
+criterion, whereas the \fBgrep\fR(1) program searches for lines matching a
+\&\fBregular expression\fR in one or more files.
+.IX Xref "grep function"
+.IP group 4
+.IX Item "group"
+A set of users of which you are a member. In some
+operating systems (like Unix), you can give certain file access permissions
+to other members of your group.
+.IX Xref "groups, defined"
+.IP GV 4
+.IX Item "GV"
+An internal “glob value� typedef,
+holding a \fBtypeglob\fR. The \f(CW\*(C`GV\*(C'\fR type is a subclass of \fBSV\fR.
+.IX Xref "GV (glob value) glob value (GV)"
+.SS H
+.IX Subsection "H"
+.IP hacker 4
+.IX Item "hacker"
+Someone who is brilliantly persistent in solving technical
+problems, whether these involve golfing, fighting orcs, or programming.
+Hacker is a neutral term, morally speaking. Good hackers are not to be
+confused with evil \fBcrackers\fR or clueless \fBscript kiddies\fR. If you
+confuse them, we will presume that you are either evil or clueless.
+.IX Xref "hackers"
+.IP handler 4
+.IX Item "handler"
+A \fBsubroutine\fR or \fBmethod\fR that Perl calls when your
+program needs to respond to some internal event, such as a \fBsignal\fR, or an
+encounter with an operator subject to \fBoperator overloading\fR. See also
+\&\fBcallback\fR.
+.IX Xref "handlers, defined"
+.IP "hard reference" 4
+.IX Item "hard reference"
+A \fBscalar\fR \fBvalue\fR containing
+the actual address of a \fBreferent\fR, such that the referent’s \fBreference\fR
+count accounts for it. (Some hard references are held internally, such as
+the implicit reference from one of a \fBtypeglob\fR’s variable slots to its
+corresponding referent.) A hard reference is different from a \fBsymbolic
+reference\fR.
+.IX Xref "hard references, about references, hard"
+.IP hash 4
+.IX Item "hash"
+An unordered association of \fBkey\fR/\fBvalue\fR pairs, stored such that you can easily use a string \fBkey\fR to
+look up its associated data \fBvalue\fR. This glossary is like a hash, where
+the word to be defined is the key and the definition is the value. A hash
+is also sometimes septisyllabically called an “associative array�, which is
+a pretty good reason for simply calling it a “hash� instead.
+.IX Xref "hashes, about key value pairs, about"
+.IP "hash table" 4
+.IX Item "hash table"
+A data structure used internally by Perl for implementing
+associative arrays (hashes) efficiently. See also \fBbucket\fR.
+.IX Xref "hash tables"
+.IP "header file" 4
+.IX Item "header file"
+A file containing certain required
+definitions that you must include “ahead� of the rest of your program to do
+certain obscure operations. A C header file has a \fI.h\fR extension. Perl
+doesn’t really have header files, though historically Perl has sometimes
+used translated \fI.h\fR files with a \fI.ph\fR extension. See \f(CW\*(C`require\*(C'\fR in
+Camel chapter 27, “Functions�. (Header files have been superseded by the
+\&\fBmodule\fR mechanism.)
+.IX Xref "header files files, header"
+.IP "here document" 4
+.IX Item "here document"
+So called because of a similar construct in \fBshells\fR that
+pretends that the \fBlines\fR following the \fBcommand\fR are a separate \fBfile\fR
+to be fed to the command, up to some terminating string. In Perl, however,
+it’s just a fancy form of quoting.
+.IX Xref "here documents"
+.IP hexadecimal 4
+.IX Item "hexadecimal"
+A number in base 16, “hex� for short. The digits for 10
+through 15 are customarily represented by the letters \f(CW\*(C`a\*(C'\fR through \f(CW\*(C`f\*(C'\fR.
+Hexadecimal constants in Perl start with \f(CW\*(C`0x\*(C'\fR. See also the \f(CW\*(C`hex\*(C'\fR
+function in Camel chapter 27, “Functions�.
+.IX Xref "hexadecimals"
+.IP "home directory" 4
+.IX Item "home directory"
+The directory you are put into when
+you log in. On a Unix system, the name is often placed into \f(CW$ENV{HOME}\fR
+or \f(CW$ENV{LOGDIR}\fR by \fIlogin\fR, but you can also find it with
+\&\f(CW\*(C`(get\*(C'\fR\f(CW\*(C`pwuid($<))[7]\*(C'\fR. (Some platforms do not have a concept of a
+home directory.)
+.IX Xref "home directory directories, home"
+.IP host 4
+.IX Item "host"
+The computer on which a program or other data resides.
+.IX Xref "host computers"
+.IP hubris 4
+.IX Item "hubris"
+Excessive pride, the sort of thing for which Zeus zaps
+you.  Also the quality that makes you write (and maintain) programs that
+other people won’t want to say bad things about. Hence, the third great
+virtue of a programmer. See also \fBlaziness\fR and \fBimpatience\fR.
+.IX Xref "hubris quality"
+.IP HV 4
+.IX Item "HV"
+Short for a “hash value� typedef, which
+holds Perl’s internal representation of a hash. The \f(CW\*(C`HV\*(C'\fR type is a
+subclass of \fBSV\fR.
+.IX Xref "HV (hash value) hash value (HV)"
+.SS I
+.IX Subsection "I"
+.IP identifier 4
+.IX Item "identifier"
+A legally formed name for most anything in which a
+computer program might be interested. Many languages (including Perl) allow
+identifiers to start with an alphabetic character, and then contain
+alphabetics and digits. Perl also allows connector punctuation like the
+underscore character wherever it allows alphabetics. (Perl also has more
+complicated names, like \fBqualified\fR names.)
+.IX Xref "identifiers, defined"
+.IP impatience 4
+.IX Item "impatience"
+The anger you feel when the computer is being lazy.
+This makes you write programs that don’t just react to your needs, but
+actually anticipate them. Or at least that pretend to. Hence, the second
+great virtue of a programmer. See also \fBlaziness\fR and \fBhubris\fR.
+.IX Xref "impatience quality"
+.IP implementation 4
+.IX Item "implementation"
+How a piece of code actually goes about doing its
+job. Users of the code should not count on implementation details staying
+the same unless they are part of the published \fBinterface\fR.
+.IX Xref "implementation (term)"
+.IP import 4
+.IX Item "import"
+To gain access to symbols that are exported from another
+module. See \f(CW\*(C`use\*(C'\fR in Camel chapter 27, “Functions�.
+.IX Xref "import (term)"
+.IP increment 4
+.IX Item "increment"
+To increase the value of
+something by 1 (or by some other number, if so specified).
+.IX Xref "incrementing values values, incrementing"
+.IP indexing 4
+.IX Item "indexing"
+In olden days, the act of looking up a \fBkey\fR in an
+actual index (such as a phone book). But now it's merely the act of using
+any kind of key or position to find the corresponding \fBvalue\fR, even if no
+index is involved. Things have degenerated to the point that Perl’s
+\&\f(CW\*(C`index\*(C'\fR function merely locates the position (index) of one string in
+another.
+.IX Xref "indexing (term)"
+.IP "indirect filehandle" 4
+.IX Item "indirect filehandle"
+An \fBexpression\fR that
+evaluates to something that can be used as a \fBfilehandle\fR: a \fBstring\fR
+(filehandle name), a \fBtypeglob\fR, a typeglob \fBreference\fR, or a low-level
+\&\fBIO\fR object.
+.IX Xref "indirect filehandles filehandles, indirect"
+.IP indirection 4
+.IX Item "indirection"
+If something in a program isn’t the value you’re
+looking for but indicates where the value is, that’s indirection. This can
+be done with either \fBsymbolic references\fR or \fBhard\fR.
+.IX Xref "indirection (term)"
+.IP "indirect object" 4
+.IX Item "indirect object"
+In English grammar, a short
+noun phrase between a verb and its direct object indicating the beneficiary
+or recipient of the action. In Perl, \f(CW\*(C`print STDOUT "$foo\en";\*(C'\fR can be
+understood as “verb indirect-object object�, where \f(CW\*(C`STDOUT\*(C'\fR is the
+recipient of the \f(CW\*(C`print\*(C'\fR action, and \f(CW"$foo"\fR is the object being
+printed.  Similarly, when invoking a \fBmethod\fR, you might place the
+invocant in the dative slot between the method and its arguments:
+.IX Xref "indirect objects, defined objects, indirect"
+.Sp
+.Vb 3
+\&    $gollum = new Pathetic::Creature "Sméagol";
+\&    give $gollum "Fisssssh!";
+\&    give $gollum "Precious!";
+.Ve
+.IP "indirect object slot" 4
+.IX Item "indirect object slot"
+The syntactic position falling between a method call
+and its arguments when using the indirect object invocation syntax. (The
+slot is distinguished by the absence of a comma between it and the next
+argument.) \f(CW\*(C`STDERR\*(C'\fR is in the indirect object slot here:
+.IX Xref "indirect object slot"
+.Sp
+.Vb 1
+\&    print STDERR "Awake! Awake! Fear, Fire, Foes! Awake!\en";
+.Ve
+.IP infix 4
+.IX Item "infix"
+An \fBoperator\fR that comes in between its \fBoperands\fR,
+such as multiplication in \f(CW\*(C`24 * 7\*(C'\fR.
+.IX Xref "infix operators"
+.IP inheritance 4
+.IX Item "inheritance"
+What you get from your ancestors, genetically or
+otherwise. If you happen to be a \fBclass\fR, your ancestors are called \fBbase
+classes\fR and your descendants are called \fBderived classes\fR. See \fBsingle
+inheritance\fR and \fBmultiple inheritance\fR.
+.IX Xref "inheritance, defined"
+.IP instance 4
+.IX Item "instance"
+Short for “an instance of a class�, meaning an \fBobject\fR
+of that \fBclass\fR.
+.IX Xref "instances (term)"
+.IP "instance data" 4
+.IX Item "instance data"
+See \fBinstance variable\fR.
+.IX Xref "instance data"
+.IP "instance method" 4
+.IX Item "instance method"
+A \fBmethod\fR of an \fBobject\fR, as
+opposed to a \fBclass method\fR.
+.IX Xref "instance methods methods, instance"
+.Sp
+A \fBmethod\fR whose \fBinvocant\fR is an \fBobject\fR, not a \fBpackage\fR name. Every
+object of a class shares all the methods of that class, so an instance
+method applies to all instances of the class, rather than applying to a
+particular instance. Also see \fBclass method\fR.
+.IP "instance variable" 4
+.IX Item "instance variable"
+An \fBattribute\fR of an \fBobject\fR; data stored with the particular object rather than with the class
+as a whole.
+.IX Xref "instance variables, defined variables, instance"
+.IP integer 4
+.IX Item "integer"
+A number with no fractional (decimal) part. A counting
+number, like 1, 2, 3, and so on, but including 0 and the negatives.
+.IX Xref "integers (term)"
+.IP interface 4
+.IX Item "interface"
+The services a piece of code promises to provide
+forever, in contrast to its \fBimplementation\fR, which it should feel free to
+change whenever it likes.
+.IX Xref "interfaces (term)"
+.IP interpolation 4
+.IX Item "interpolation"
+The insertion of a scalar or list value somewhere
+in the middle of another value, such that it appears to have been there all
+along. In Perl, variable interpolation happens in double-quoted strings and
+patterns, and list interpolation occurs when constructing the list of
+values to pass to a list operator or other such construct that takes a
+\&\fR\f(CI\*(C`LIST\*(C'\fR\fI\fR.
+.IX Xref "interpolation, defined"
+.IP interpreter 4
+.IX Item "interpreter"
+Strictly speaking, a program that reads a second
+program and does what the second program says directly without turning the
+program into a different form first, which is what \fBcompilers\fR do. Perl is
+not an interpreter by this definition, because it contains a kind of
+compiler that takes a program and turns it into a more executable form
+(\fBsyntax trees\fR) within the \fIperl\fR process itself, which the Perl
+\&\fBruntime\fR system then interprets.
+.IX Xref "interpreters, defined"
+.IP invocant 4
+.IX Item "invocant"
+The agent on whose behalf a \fBmethod\fR is invoked. In a
+\&\fBclass\fR method, the invocant is a package name. In an \fBinstance\fR method,
+the invocant is an object reference.
+.IX Xref "invocants, defined"
+.IP invocation 4
+.IX Item "invocation"
+The act of calling up a deity, daemon, program,
+method, subroutine, or function to get it to do what you think it’s
+supposed to do.  We usually “call� subroutines but “invoke� methods, since
+it sounds cooler.
+.IX Xref "invocation, method"
+.IP I/O 4
+.IX Item "I/O"
+Input from, or output to, a \fBfile\fR or \fBdevice\fR.
+.IX Xref "I O (Input Output), defined Input Output (I O), defined"
+.IP IO 4
+.IX Item "IO"
+An internal I/O object. Can also mean \fBindirect object\fR.
+.IP "I/O layer" 4
+.IX Item "I/O layer"
+One of the filters between the data and what you get as input
+or what you end up with as output.
+.IX Xref "I O layer"
+.IP IPA 4
+.IX Item "IPA"
+India Pale Ale. Also the International Phonetic Alphabet, the
+standard alphabet used for phonetic notation worldwide. Draws heavily on
+Unicode, including many combining characters.
+.IX Xref "International Phonetic Alphabet (IPA) IPA (International Phonetic Alphabet)"
+.IP IP 4
+.IX Item "IP"
+Internet Protocol, or
+Intellectual
+Property.
+.IX Xref "Internet Protocol (IP) IP (Internet Protocol) IP (Intellectual Property) Intellectual Property (IP)"
+.IP IPC 4
+.IX Item "IPC"
+Interprocess Communication.
+.IX Xref "Interprocess Communication IPC (Interprocess Communication), about communication"
+.IP is-a 4
+.IX Item "is-a"
+A relationship between two \fBobjects\fR in which one
+object is considered to be a more specific version of the other, generic
+object: “A camel is a mammal.� Since the generic object really only exists
+in a Platonic sense, we usually add a little abstraction to the notion of
+objects and think of the relationship as being between a generic \fBbase
+class\fR and a specific \fBderived class\fR. Oddly enough, Platonic classes
+don’t always have Platonic relationships—see \fBinheritance\fR.
+.IX Xref "is–a relationship"
+.IP iteration 4
+.IX Item "iteration"
+Doing something repeatedly.
+.IX Xref "iteration"
+.IP iterator 4
+.IX Item "iterator"
+A special programming gizmo that keeps track of where you are
+in something that you’re trying to iterate over. The \f(CW\*(C`foreach\*(C'\fR loop in
+Perl contains an iterator; so does a hash, allowing you to \f(CW\*(C`each\*(C'\fR through
+it.
+.IX Xref "iterators"
+.IP IV 4
+.IX Item "IV"
+The integer four, not to be
+confused with six, Tom’s favorite editor. IV also means an internal Integer
+Value of the type a \fBscalar\fR can hold, not to be confused with an \fBNV\fR.
+.IX Xref "IV (Integer Value) Integer Value (IV)"
+.SS J
+.IX Subsection "J"
+.IP JAPH 4
+.IX Item "JAPH"
+“Just Another Perl Hacker�, a clever but cryptic bit of Perl
+code that, when executed, evaluates to that string. Often used to
+illustrate a particular Perl feature, and something of an ongoing
+Obfuscated Perl Contest seen in USENET signatures.
+.IX Xref "JAPH acronym"
+.SS K
+.IX Subsection "K"
+.IP key 4
+.IX Item "key"
+The string index to a \fBhash\fR, used to look up the \fBvalue\fR
+associated with that key.
+.IX Xref "keys, defined"
+.IP keyword 4
+.IX Item "keyword"
+See \fBreserved words\fR.
+.SS L
+.IX Subsection "L"
+.IP label 4
+.IX Item "label"
+A name you give to a \fBstatement\fR so that you can talk
+about that statement elsewhere in the program.
+.IX Xref "labels, defined"
+.IP laziness 4
+.IX Item "laziness"
+The quality that makes you go to great effort to reduce
+overall energy expenditure. It makes you write labor-saving programs that
+other people will find useful, and then document what you wrote so you
+don’t have to answer so many questions about it. Hence, the first great
+virtue of a programmer. Also hence, this book. See also \fBimpatience\fR and
+\&\fBhubris\fR.
+.IX Xref "laziness quality"
+.IP "leftmost longest" 4
+.IX Item "leftmost longest"
+The preference of the \fBregular expression\fR engine to match the
+leftmost occurrence of a \fBpattern\fR, then given a position at which a match
+will occur, the preference for the longest match (presuming the use of a
+\&\fBgreedy\fR quantifier). See Camel chapter 5, “Pattern Matching� for \fImuch\fR
+more on this subject.
+.IX Xref "leftmost longest preference regular expressions, leftmost longest preference"
+.IP "left shift" 4
+.IX Item "left shift"
+A \fBbit shift\fR that multiplies the
+number by some power of 2.
+.IX Xref "left shift (<<) bit operator bit–shift operators, left shift << (left shift) bit operator"
+.IP lexeme 4
+.IX Item "lexeme"
+Fancy term for a \fBtoken\fR.
+.IX Xref "lexeme (token)"
+.IP lexer 4
+.IX Item "lexer"
+Fancy term for a \fBtokener\fR.
+.IX Xref "lexer (tokener)"
+.IP "lexical analysis" 4
+.IX Item "lexical analysis"
+Fancy term for \fBtokenizing\fR.
+.IX Xref "lexical analysis"
+.IP "lexical scoping" 4
+.IX Item "lexical scoping"
+Looking at your \fIOxford English
+Dictionary\fR through a microscope. (Also known as \fBstatic scoping\fR, because
+dictionaries don’t change very fast.) Similarly, looking at variables
+stored in a private dictionary (namespace) for each scope, which are
+visible only from their point of declaration down to the end of the lexical scope in which they are declared. —Syn.
+\&\fBstatic scoping\fR. —Ant. \fBdynamic scoping\fR.
+.IX Xref "lexical scopes, defined scopes static scopes scopes, static"
+.IP "lexical variable" 4
+.IX Item "lexical variable"
+A \fBvariable\fR subject to
+\&\fBlexical scoping\fR, declared by \f(CW\*(C`my\*(C'\fR. Often just called a “lexical�. (The
+\&\f(CW\*(C`our\*(C'\fR declaration declares a lexically scoped name for a global variable,
+which is not itself a lexical variable.)
+.IX Xref "lexical variables, about variables, lexical"
+.IP library 4
+.IX Item "library"
+Generally, a collection of procedures. In ancient
+days, referred to a collection of subroutines in a \fI.pl\fR file. In modern
+times, refers more often to the entire collection of Perl \fBmodules\fR on
+your system.
+.IX Xref "libraries, defined"
+.IP LIFO 4
+.IX Item "LIFO"
+Last In, First Out. See also \fBFIFO\fR. A LIFO is usually called a
+\&\fBstack\fR.
+.IX Xref "Last In, First Out (LIFO) LIFO (Last In, First Out) stacks, defined"
+.IP line 4
+.IX Item "line"
+In Unix, a sequence of zero or more nonnewline characters
+terminated with a \fBnewline\fR character. On non-Unix machines, this is
+emulated by the C library even if the underlying \fBoperating system\fR has
+different ideas.
+.IX Xref "line (term)"
+.IP linebreak 4
+.IX Item "linebreak"
+A \fBgrapheme\fR consisting of either a carriage return followed
+by a line feed or any character with the Unicode Vertical Space \fBcharacter
+property\fR.
+.IX Xref "linebreaks"
+.IP "line buffering" 4
+.IX Item "line buffering"
+Used by a \fBstandard I/O\fR output stream that
+flushes its \fBbuffer\fR after every \fBnewline\fR. Many standard I/O libraries
+automatically set up line buffering on output that is going to the terminal.
+.IX Xref "line buffering buffering, line"
+.IP "line number" 4
+.IX Item "line number"
+The number of lines read previous to this one, plus 1. Perl
+keeps a separate line number for each source or input file it opens. The
+current source file’s line number is represented by \f(CW\*(C`_\|_LINE_\|_\*(C'\fR. The
+current input line number (for the file that was most recently read via
+\&\f(CW\*(C`<FH>\*(C'\fR) is represented by the \f(CW$.\fR (\f(CW$INPUT_LINE_NUMBER\fR)
+variable. Many error messages report both values, if available.
+.IX Xref "line number"
+.IP link 4
+.IX Item "link"
+Used as a noun, a name in a \fBdirectory\fR that represents a
+\&\fBfile\fR. A given file can have multiple links to it. It’s like having the
+same phone number listed in the phone directory under different names. As a
+verb, to resolve a partially \fBcompiled\fR file’s unresolved symbols into a
+(nearly) executable image. Linking can generally be static or dynamic,
+which has nothing to do with static or dynamic scoping.
+.IX Xref "links, defined"
+.IP LIST 4
+.IX Item "LIST"
+A syntactic construct representing a
+comma\- separated list of expressions, evaluated to produce a \fBlist value\fR.
+Each \fBexpression\fR in a \fR\f(CI\*(C`LIST\*(C'\fR\fI\fR is evaluated in \fBlist context\fR and
+interpolated into the list value.
+.IX Xref "LIST construct constructs, LIST"
+.IP list 4
+.IX Item "list"
+An ordered set of scalar values.
+.IX Xref "lists, defined"
+.IP "list context" 4
+.IX Item "list context"
+The situation in which an \fBexpression\fR is
+expected by its surroundings (the code calling it) to return a list of
+values rather than a single value. Functions that want a \fR\f(CI\*(C`LIST\*(C'\fR\fI\fR of
+arguments tell those arguments that they should produce a list value. See
+also \fBcontext\fR.
+.IX Xref "list context context, list"
+.IP "list operator" 4
+.IX Item "list operator"
+An \fBoperator\fR that does something with a list of
+values, such as \f(CW\*(C`join\*(C'\fR or \f(CW\*(C`grep\*(C'\fR. Usually used for named built-in
+operators (such as \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, and \f(CW\*(C`system\*(C'\fR) that do not require
+parentheses around their \fBargument\fR list.
+.IX Xref "list operators, about"
+.IP "list value" 4
+.IX Item "list value"
+An unnamed list of temporary scalar
+values that may be passed around within a program from any list-generating
+function to any function or construct that provides a \fBlist context\fR.
+.IX Xref "list values, about values, list"
+.IP literal 4
+.IX Item "literal"
+A token in a programming language, such as a number or
+\&\fBstring\fR, that gives you an actual \fBvalue\fR instead of merely representing
+possible values as a \fBvariable\fR does.
+.IX Xref "literals, defined"
+.IP little-endian 4
+.IX Item "little-endian"
+From Swift: someone
+who eats eggs little end first. Also used of computers that store the least
+significant \fBbyte\fR of a word at a lower byte address than the most
+significant byte. Often considered superior to big-endian machines. See
+also \fBbig-endian\fR.
+.IX Xref "little–endian, defined endianness, little–endian"
+.IP local 4
+.IX Item "local"
+Not meaning the same thing everywhere. A global
+variable in Perl can be localized inside a \fBdynamic scope\fR via the
+\&\f(CW\*(C`local\*(C'\fR operator.
+.IX Xref "local operator, about"
+.IP "logical operator" 4
+.IX Item "logical operator"
+Symbols representing the concepts “and�, “or�,
+“xor�, and “not�.
+.IX Xref "logical operators, about"
+.IP lookahead 4
+.IX Item "lookahead"
+An \fBassertion\fR that peeks at the string to the right of the current match location.
+.IX Xref "lookahead assertions assertions (in regexes), lookahead"
+.IP lookbehind 4
+.IX Item "lookbehind"
+An \fBassertion\fR that peeks at the string to the left of the current match
+location.
+.IX Xref "lookbehind assertions assertions (in regexes), lookbehind"
+.IP loop 4
+.IX Item "loop"
+A construct that
+performs something repeatedly, like a roller coaster.
+.IX Xref "loop constructs and statements, about constructs, loop"
+.IP "loop control statement" 4
+.IX Item "loop control statement"
+Any statement within the body of a loop that can
+make a loop prematurely stop looping or skip an \fBiteration\fR. Generally,
+you shouldn’t try this on roller coasters.
+.IX Xref "statements, loop control"
+.IP "loop label" 4
+.IX Item "loop label"
+A kind of key or name attached to a loop (or
+roller coaster) so that loop control statements can talk about which loop
+they want to control.
+.IX Xref "loop labels labels, loop"
+.IP lowercase 4
+.IX Item "lowercase"
+In Unicode, not just
+characters with the General Category of Lowercase Letter, but any character
+with the Lowercase property, including Modifier Letters, Letter Numbers,
+some Other Symbols, and one Combining Mark.
+.IX Xref "lowercase characters characters, lowercase"
+.IP lvaluable 4
+.IX Item "lvaluable"
+Able to serve as an \fBlvalue\fR.
+.IX Xref "lvaluable function functions, lvaluable"
+.IP lvalue 4
+.IX Item "lvalue"
+Term used by language lawyers for a
+storage location you can assign a new \fBvalue\fR to, such as a \fBvariable\fR or
+an element of an \fBarray\fR. The “l� is short for “left�, as in the left side
+of an assignment, a typical place for lvalues. An \fBlvaluable\fR function or
+expression is one to which a value may be assigned, as in \f(CW\*(C`pos($x) = 10\*(C'\fR.
+.IX Xref "lvalue (term) values, lvalue"
+.IP "lvalue modifier" 4
+.IX Item "lvalue modifier"
+An adjectival pseudofunction that
+warps the meaning of an \fBlvalue\fR in some declarative fashion. Currently
+there are three lvalue modifiers: \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, and \f(CW\*(C`local\*(C'\fR.
+.IX Xref "lvalue modifier modifiers, lvalue"
+.SS M
+.IX Subsection "M"
+.IP magic 4
+.IX Item "magic"
+Technically speaking, any extra semantics attached to a
+variable such as \f(CW$!\fR, \f(CW$0\fR, \f(CW%ENV\fR, or \f(CW%SIG\fR, or to any tied
+variable.  Magical things happen when you diddle those variables.
+.IX Xref "magic (term)"
+.IP "magical increment" 4
+.IX Item "magical increment"
+An \fBincrement\fR operator that knows how to
+bump up ASCII alphabetics as well as numbers.
+.IX Xref "magical increment operator"
+.IP "magical variables" 4
+.IX Item "magical variables"
+Special variables that have side
+effects when you access them or assign to them. For example, in Perl,
+changing elements of the \f(CW%ENV\fR array also changes the corresponding
+environment variables that subprocesses will use. Reading the \f(CW$!\fR
+variable gives you the current system error number or message.
+.IX Xref "magical variables variables, magical"
+.IP Makefile 4
+.IX Item "Makefile"
+A file that controls the compilation of a program. Perl programs
+don’t usually need a \fBMakefile\fR because the Perl compiler has plenty of
+self-control.
+.IX Xref "Makefile"
+.IP man 4
+.IX Item "man"
+The Unix program that displays online documentation
+(manual pages) for you.
+.IX Xref "man program (Unix)"
+.IP manpage 4
+.IX Item "manpage"
+A “page� from the manuals, typically accessed via the
+\&\fIman\fR(1) command. A manpage contains a SYNOPSIS, a DESCRIPTION, a list of
+BUGS, and so on, and is typically longer than a page. There are manpages
+documenting \fBcommands\fR, \fBsyscalls\fR, \fBlibrary\fR \fBfunctions\fR, \fBdevices\fR,
+\&\fBprotocols\fR, \fBfiles\fR, and such. In this book, we call any piece of
+standard Perl documentation (like perlop or perldelta) a manpage, no
+matter what format it’s installed in on your system.
+.IX Xref "manpages, defined"
+.IP matching 4
+.IX Item "matching"
+See \fBpattern matching\fR.
+.IX Xref "matching"
+.IP "member data" 4
+.IX Item "member data"
+See \fBinstance variable\fR.
+.IX Xref "member data"
+.IP memory 4
+.IX Item "memory"
+This always means your main memory, not your disk.
+Clouding the issue is the fact that your machine may implement
+\&\fBvirtual\fR memory; that is, it will pretend that it has more memory than
+it really does, and it’ll use disk space to hold inactive bits. This can
+make it seem like you have a little more memory than you really do, but
+it’s not a substitute for real memory. The best thing that can be said
+about virtual memory is that it lets your performance degrade gradually
+rather than suddenly when you run out of real memory. But your program
+can die when you run out of virtual memory, too—if you haven’t thrashed
+your disk to death first.
+.IX Xref "memory, defined"
+.IP metacharacter 4
+.IX Item "metacharacter"
+A \fBcharacter\fR that is \fInot\fR supposed to be treated normally. Which characters
+are to be treated specially as metacharacters varies greatly from context to
+context. Your \fBshell\fR will have certain metacharacters, double-quoted Perl
+\&\fBstrings\fR have other metacharacters,
+and \fBregular expression\fR patterns have all the double-quote metacharacters plus
+some extra ones of their own.
+.IX Xref "metacharacters, about characters, regex metacharacters regular expressions, metacharacters and"
+.IP metasymbol 4
+.IX Item "metasymbol"
+Something we’d call a
+\&\fBmetacharacter\fR except that it’s a sequence of more than one character.
+Generally, the first character in the sequence must be a true metacharacter
+to get the other characters in the metasymbol to misbehave along with it.
+.IX Xref "metasymbols, about escape sequences"
+.IP method 4
+.IX Item "method"
+A kind of action that an \fBobject\fR can take if you tell
+it to. See Camel chapter 12, “Objects�.
+.IX Xref "methods, defined"
+.IP "method resolution order" 4
+.IX Item "method resolution order"
+The path Perl takes through \f(CW@INC\fR. By default, this is a double depth first
+search, once looking for defined methods and once for \f(CW\*(C`AUTOLOAD\*(C'\fR. However,
+Perl lets you configure this with \f(CW\*(C`mro\*(C'\fR.
+.IX Xref "method resolution order (mro) mro (method resolution order)"
+.IP minicpan 4
+.IX Item "minicpan"
+A CPAN mirror that includes just the latest versions for each
+distribution, probably created with \f(CW\*(C`CPAN::Mini\*(C'\fR. See
+Camel chapter 19, “CPAN�.
+.IX Xref "minicpan, defined CPAN (Comprehensive Perl Archive Network), minicpan and CPAN::Mini module"
+.IP minimalism 4
+.IX Item "minimalism"
+The belief that “small is beautiful�. Paradoxically, if you
+say something in a small language, it turns out big, and if you say it in a
+big language, it turns out small. Go figure.
+.IX Xref "minimalism"
+.IP mode 4
+.IX Item "mode"
+In the context of the \fIstat\fR(2) syscall, refers to the field
+holding the \fBpermission bits\fR and the type of the \fBfile\fR.
+.IX Xref "mode"
+.IP modifier 4
+.IX Item "modifier"
+See \fBstatement modifier\fR, \fBregular expression\fR, and
+\&\fBlvalue\fR, not necessarily in that order.
+.IX Xref "modifiers, defined"
+.IP module 4
+.IX Item "module"
+A \fBfile\fR that defines a \fBpackage\fR of (almost) the same
+name, which can either \fBexport\fR symbols or function as an \fBobject\fR class.
+(A module’s main \fI.pm\fR file may also load in other files in support of the
+module.) See the \f(CW\*(C`use\*(C'\fR built-in.
+.IX Xref "modules, defined"
+.IP modulus 4
+.IX Item "modulus"
+An integer divisor when
+you’re interested in the remainder instead of the quotient.
+.IX Xref "modulus (%) operator % (modulus) operator"
+.IP mojibake 4
+.IX Item "mojibake"
+When you speak one language and the computer thinks you’re
+speaking another. You’ll see odd translations when you send UTF‑8, for
+instance, but the computer thinks you sent Latin\-1, showing all sorts of
+weird characters instead. The term is written 「文字化��in Japanese and
+means “character rot�, an apt description. Pronounced [\f(CW\*(C`modʑibake\*(C'\fR] in
+standard \fBIPA\fR phonetics, or approximately “moh\-jee\-bah\-keh�.
+.IX Xref "mojibake"
+.IP monger 4
+.IX Item "monger"
+Short for one member of \fBPerl mongers\fR, a
+purveyor of Perl.
+.IX Xref "mongers, Perl Perl mongers"
+.IP mortal 4
+.IX Item "mortal"
+A temporary value scheduled to die when the
+current statement finishes.
+.IX Xref "mortal value values, mortal"
+.IP mro 4
+.IX Item "mro"
+See \fBmethod resolution order\fR.
+.IP "multidimensional array" 4
+.IX Item "multidimensional array"
+An array with multiple
+subscripts for finding a single element. Perl implements these using
+\&\fBreferences\fR—see Camel chapter 9, “Data Structures�.
+.IX Xref "multidimensional arrays arrays, multidimensional"
+.IP "multiple inheritance" 4
+.IX Item "multiple inheritance"
+The features you got from
+your mother and father, mixed together unpredictably. (See also
+\&\fBinheritance\fR and \fBsingle inheritance\fR.) In computer languages (including
+Perl), it is the notion that a given class may have multiple direct
+ancestors or \fBbase classes\fR.
+.IX Xref "multiple inheritance inheritance, multiple"
+.SS N
+.IX Subsection "N"
+.IP "named pipe" 4
+.IX Item "named pipe"
+A \fBpipe\fR with a name embedded in the
+\&\fBfilesystem\fR so that it can be accessed by two unrelated \fBprocesses\fR.
+.IX Xref "named pipes pipes, names"
+.IP namespace 4
+.IX Item "namespace"
+A domain of names. You needn’t worry about whether the
+names in one such domain have been used in another. See \fBpackage\fR.
+.IX Xref "namespaces, about"
+.IP NaN 4
+.IX Item "NaN"
+Not a number. The value Perl uses
+for certain invalid or inexpressible floating-point operations.
+.IX Xref "NaN (not a number) not a number (NaN)"
+.IP "network address" 4
+.IX Item "network address"
+The most important attribute of a socket, like your
+telephone’s telephone number. Typically an IP address. See also \fBport\fR.
+.IX Xref "network address"
+.IP newline 4
+.IX Item "newline"
+A single character that
+represents the end of a line, with the ASCII value of 012 octal under Unix
+(but 015 on a Mac), and represented by \f(CW\*(C`\en\*(C'\fR in Perl strings. For Windows
+machines writing text files, and for certain physical devices like
+terminals, the single newline gets automatically translated by your C
+library into a line feed and a carriage return, but normally, no
+translation is done.
+.IX Xref "newline character characters, newline"
+.IP NFS 4
+.IX Item "NFS"
+Network File System, which allows you to mount a remote filesystem as if it were local.
+.IX Xref "NFS (Network File System) Network File System (NFS)"
+.IP normalization 4
+.IX Item "normalization"
+Converting a text string into an alternate but equivalent
+\&\fBcanonical\fR (or compatible) representation that can then be compared for
+equivalence. Unicode recognizes four different normalization forms: NFD,
+NFC, NFKD, and NFKC.
+.IX Xref "normalization"
+.IP "null character" 4
+.IX Item "null character"
+A character with the numeric value of
+zero. It’s used by C to terminate strings, but Perl allows strings to
+contain a null.
+.IX Xref "null character characters, null"
+.IP "null list" 4
+.IX Item "null list"
+A \fBlist value\fR with zero elements, represented
+in Perl by \f(CW\*(C`()\*(C'\fR.
+.IX Xref "null lists lists, null"
+.IP "null string" 4
+.IX Item "null string"
+A \fBstring\fR containing no characters, not to
+be confused with a string containing a \fBnull character\fR, which has a
+positive length and is \fBtrue\fR.
+.IX Xref "null strings strings, null"
+.IP "numeric context" 4
+.IX Item "numeric context"
+The situation in which an expression
+is expected by its surroundings (the code calling it) to return a number.
+See also \fBcontext\fR and \fBstring context\fR.
+.IX Xref "numeric context context, numeric"
+.IP numification 4
+.IX Item "numification"
+(Sometimes spelled \fInummification\fR and \fInummify\fR.) Perl lingo
+for implicit conversion into a number; the related verb is \fInumify\fR.
+\&\fINumification\fR is intended to rhyme with \fImummification\fR, and \fInumify\fR with
+\&\fImummify\fR. It is unrelated to English \fInumen\fR, \fInumina\fR, \fInuminous\fR. We
+originally forgot the extra \fIm\fR a long time ago, and some people got used to
+our funny spelling, and so just as with \f(CW\*(C`HTTP_REFERER\*(C'\fR’s own missing letter,
+our weird spelling has stuck around.
+.IX Xref "numification"
+.IP NV 4
+.IX Item "NV"
+Short for Nevada, no part of
+which will ever be confused with civilization. NV also means an internal
+floating\- point Numeric Value of the type a \fBscalar\fR can hold, not to be
+confused with an \fBIV\fR.
+.IX Xref "Numeric Value (NV) NV (Numeric Value)"
+.IP nybble 4
+.IX Item "nybble"
+Half a \fBbyte\fR, equivalent to one \fBhexadecimal\fR digit, and worth
+four \fBbits\fR.
+.IX Xref "nybble"
+.SS O
+.IX Subsection "O"
+.IP object 4
+.IX Item "object"
+An \fBinstance\fR of a \fBclass\fR. Something that “knows�
+what user-defined type (class) it is, and what it can do because of what
+class it is. Your program can request an object to do things, but the
+object gets to decide whether it wants to do them or not. Some objects are
+more accommodating than others.
+.IX Xref "objects, defined"
+.IP octal 4
+.IX Item "octal"
+A number in base 8. Only the digits 0 through 7 are allowed. Octal
+constants in Perl start with 0, as in 013. See also the \f(CW\*(C`oct\*(C'\fR function.
+.IX Xref "octals"
+.IP offset 4
+.IX Item "offset"
+How many things you have to skip
+over when moving from the beginning of a string or array to a specific
+position within it. Thus, the minimum offset is zero, not one, because you
+don’t skip anything to get to the first item.
+.IX Xref "offsets in strings strings, offsets in"
+.IP one-liner 4
+.IX Item "one-liner"
+An entire computer program crammed into one line of
+text.
+.IX Xref "one–liner programs"
+.IP "open source software" 4
+.IX Item "open source software"
+Programs for which the source code is freely
+available and freely redistributable, with no commercial strings attached.
+For a more detailed definition, see <http://www.opensource.org/osd.html>.
+.IX Xref "open source software"
+.IP operand 4
+.IX Item "operand"
+An \fBexpression\fR that yields a \fBvalue\fR that an
+\&\fBoperator\fR operates on. See also \fBprecedence\fR.
+.IX Xref "operands (term)"
+.IP "operating system" 4
+.IX Item "operating system"
+A special program that runs on the bare
+machine and hides the gory details of managing \fBprocesses\fR and \fBdevices\fR.
+Usually used in a looser sense to indicate a particular culture of
+programming. The loose sense can be used at varying levels of specificity.
+At one extreme, you might say that all versions of Unix and Unix-lookalikes
+are the same operating system (upsetting many people, especially lawyers
+and other advocates). At the other extreme, you could say this particular
+version of this particular vendor’s operating system is different from any
+other version of this or any other vendor’s operating system. Perl is much
+more portable across operating systems than many other languages. See also
+\&\fBarchitecture\fR and \fBplatform\fR.
+.IX Xref "operating systems, defined"
+.IP operator 4
+.IX Item "operator"
+A gizmo that transforms some number of input values to
+some number of output values, often built into a language with a special
+syntax or symbol. A given operator may have specific expectations about
+what \fBtypes\fR of data you give as its arguments (\fBoperands\fR) and what type
+of data you want back from it.
+.IX Xref "operators, about"
+.IP "operator overloading" 4
+.IX Item "operator overloading"
+A kind of
+\&\fBoverloading\fR that you can do on built-in \fBoperators\fR to make them work
+on \fBobjects\fR as if the objects were ordinary scalar values, but with the
+actual semantics supplied by the object class. This is set up with the
+overload \fBpragma\fR—see Camel chapter 13, “Overloading�.
+.IX Xref "operator overloading, about overloading, operator"
+.IP options 4
+.IX Item "options"
+See either \fBswitches\fR or \fBregular expression modifiers\fR.
+.IX Xref "options"
+.IP ordinal 4
+.IX Item "ordinal"
+An abstract character’s integer value. Same thing as
+\&\fBcodepoint\fR.
+.IX Xref "ordinals (term)"
+.IP overloading 4
+.IX Item "overloading"
+Giving additional meanings to a symbol or construct.
+Actually, all languages do overloading to one extent or another, since
+people are good at figuring out things from \fBcontext\fR.
+.IX Xref "overloading, defined"
+.IP overriding 4
+.IX Item "overriding"
+Hiding or invalidating some other definition of the
+same name. (Not to be confused with \fBoverloading\fR, which adds definitions
+that must be disambiguated some other way.) To confuse the issue further,
+we use the word with two overloaded definitions: to describe how you can
+define your own \fBsubroutine\fR to hide a built-in \fBfunction\fR of the same
+name (see the section “Overriding Built-in Functions� in Camel chapter 11,
+“Modules�), and to describe how you can define a replacement \fBmethod\fR in a
+\&\fBderived class\fR to hide a \fBbase class\fR’s method of the same name (see
+Camel chapter 12, “Objects�).
+.IX Xref "overriding, defined"
+.IP owner 4
+.IX Item "owner"
+The one user (apart from the
+superuser) who has absolute control over a \fBfile\fR. A file may also have a
+\&\fBgroup\fR of users who may exercise joint ownership if the real owner
+permits it. See \fBpermission bits\fR.
+.IX Xref "ownership, file files, ownership of"
+.SS P
+.IX Subsection "P"
+.IP package 4
+.IX Item "package"
+A \fBnamespace\fR for global \fBvariables\fR, \fBsubroutines\fR,
+and the like, such that they can be kept separate from like-named
+\&\fBsymbols\fR in other namespaces. In a sense, only the package is global,
+since the symbols in the package’s symbol table are only accessible from
+code \fBcompiled\fR outside the package by naming the package. But in another
+sense, all package symbols are also globals—they’re just well-organized
+globals.
+.IX Xref "packages, defined"
+.IP pad 4
+.IX Item "pad"
+Short for \fBscratchpad\fR.
+.IX Xref "pads (scratchpads)"
+.IP parameter 4
+.IX Item "parameter"
+See \fBargument\fR.
+.IX Xref "parameters"
+.IP "parent class" 4
+.IX Item "parent class"
+See \fBbase class\fR.
+.IX Xref "parent classes classes, parent"
+.IP "parse tree" 4
+.IX Item "parse tree"
+See \fBsyntax tree\fR.
+.IX Xref "parse tree"
+.IP parsing 4
+.IX Item "parsing"
+The subtle but sometimes brutal art of attempting to turn
+your possibly malformed program into a valid \fBsyntax tree\fR.
+.IX Xref "parsing, about"
+.IP patch 4
+.IX Item "patch"
+To fix by applying one, as it were. In the realm of hackerdom, a
+listing of the differences between two versions of a program as might be
+applied by the \fBpatch\fR(1) program when you want to fix a bug or upgrade
+your old version.
+.IX Xref "patches"
+.IP PATH 4
+.IX Item "PATH"
+The list of
+\&\fBdirectories\fR the system searches to find a program you want to
+\&\fBexecute\fR.  The list is stored as one of your \fBenvironment variables\fR,
+accessible in Perl as \f(CW$ENV{PATH}\fR.
+.IX Xref "PATH environment variable variables, environment"
+.IP pathname 4
+.IX Item "pathname"
+A fully qualified filename such as \fI/usr/bin/perl\fR. Sometimes
+confused with \f(CW\*(C`PATH\*(C'\fR.
+.IX Xref "pathname"
+.IP pattern 4
+.IX Item "pattern"
+A template used in \fBpattern matching\fR.
+.IX Xref "patterns, defined"
+.IP "pattern matching" 4
+.IX Item "pattern matching"
+Taking a pattern, usually a \fBregular
+expression\fR, and trying the pattern various ways on a string to see whether
+there’s any way to make it fit. Often used to pick interesting tidbits out
+of a file.
+.IX Xref "pattern matching, about"
+.IP PAUSE 4
+.IX Item "PAUSE"
+The Perl Authors Upload SErver (<http://pause.perl.org>), the gateway
+for \fBmodules\fR on their way to \fBCPAN\fR.
+.IX Xref "Perl Authors Upload SErver (PAUSE) PAUSE (Perl Authors Upload SErver)"
+.IP "Perl mongers" 4
+.IX Item "Perl mongers"
+A Perl user group, taking the form of its
+name from the New York Perl mongers, the first Perl user group. Find one
+near you at <http://www.pm.org>.
+.IX Xref "Perl mongers mongers, Perl"
+.IP "permission bits" 4
+.IX Item "permission bits"
+Bits that the \fBowner\fR of a file sets
+or unsets to allow or disallow access to other people. These flag bits are
+part of the \fBmode\fR word returned by the \f(CW\*(C`stat\*(C'\fR built-in when you ask
+about a file. On Unix systems, you can check the \fIls\fR(1) manpage for more
+information.
+.IX Xref "permission bits bits, permission"
+.IP Pern 4
+.IX Item "Pern"
+What you get when you do \f(CW\*(C`Perl++\*(C'\fR twice. Doing it only once
+will curl your hair. You have to increment it eight times to shampoo your
+hair. Lather, rinse, iterate.
+.IX Xref "Pern (term)"
+.IP pipe 4
+.IX Item "pipe"
+A direct \fBconnection\fR that carries the output of one
+\&\fBprocess\fR to the input of another without an intermediate temporary file.
+Once the pipe is set up, the two processes in question can read and write
+as if they were talking to a normal file, with some caveats.
+.IX Xref "pipes, defined"
+.IP pipeline 4
+.IX Item "pipeline"
+A series of \fBprocesses\fR all in a row, linked by \fBpipes\fR, where
+each passes its output stream to the next.
+.IX Xref "pipeline"
+.IP platform 4
+.IX Item "platform"
+The entire hardware and software context in which a
+program runs. A program written in a platform-dependent language might
+break if you change any of the following: machine, operating system,
+libraries, compiler, or system configuration. The \fIperl\fR interpreter has
+to be \fBcompiled\fR differently for each platform because it is implemented
+in C, but programs written in the Perl language are largely platform
+independent.
+.IX Xref "platforms, defined"
+.IP pod 4
+.IX Item "pod"
+The markup
+used to embed documentation into your Perl code. Pod stands for “Plain old
+documentation�. See Camel chapter 23, “Plain Old Documentation�.
+.IX Xref "pod (plain old documentation), about plain old documentation"
+.IP "pod command" 4
+.IX Item "pod command"
+A sequence, such as \f(CW\*(C`=head1\*(C'\fR, that denotes
+the start of a \fBpod\fR section.
+.IX Xref "pod commands commands, pod"
+.IP pointer 4
+.IX Item "pointer"
+A \fBvariable\fR in a language like C that contains the exact
+memory location of some other item. Perl handles pointers internally so you
+don’t have to worry about them. Instead, you just use symbolic pointers in
+the form of \fBkeys\fR and \fBvariable\fR names, or \fBhard references\fR, which
+aren’t pointers (but act like pointers and do in fact contain pointers).
+.IX Xref "pointers"
+.IP polymorphism 4
+.IX Item "polymorphism"
+The notion that you can tell an \fBobject\fR to do something
+generic, and the object will interpret the command in different ways
+depending on its type. [< Greek πολυ\- + μο�ϕή, many forms.]
+.IX Xref "polymorphism"
+.IP port 4
+.IX Item "port"
+The part of the address of a TCP or UDP socket that directs
+packets to the correct process after finding the right machine, something
+like the phone extension you give when you reach the company operator. Also
+the result of converting code to run on a different platform than
+originally intended, or the verb denoting this conversion.
+.IX Xref "ports (term)"
+.IP portable 4
+.IX Item "portable"
+Once upon a time, C code compilable under both BSD and
+SysV. In general, code that can be easily converted to run on another
+\&\fBplatform\fR, where “easily� can be defined however you like, and usually
+is.  Anything may be considered portable if you try hard enough, such as a
+mobile home or London Bridge.
+.IX Xref "portability, about"
+.IP porter 4
+.IX Item "porter"
+Someone who “carries� software from one \fBplatform\fR to another.
+Porting programs written in platform-dependent languages such as C can be
+difficult work, but porting programs like Perl is very much worth the
+agony.
+.IX Xref "porters"
+.IP possessive 4
+.IX Item "possessive"
+Said of quantifiers and groups in patterns that refuse
+to give up anything once they’ve gotten their mitts on it. Catchier and
+easier to say than the even more formal \fInonbacktrackable\fR.
+.IX Xref "possessive (term)"
+.IP POSIX 4
+.IX Item "POSIX"
+The Portable Operating System Interface
+specification.
+.IX Xref "Portable Operating System Interface (POSIX), about POSIX (Portable Operating System Interface), about"
+.IP postfix 4
+.IX Item "postfix"
+An \fBoperator\fR that follows its \fBoperand\fR, as in
+\&\f(CW\*(C`$x++\*(C'\fR.
+.IX Xref "postfix operator"
+.IP pp 4
+.IX Item "pp"
+An internal shorthand for a
+“push\- pop� code; that is, C code implementing Perl’s stack machine.
+.IX Xref "pp (push–pop) code push–pop (pp) code"
+.IP pragma 4
+.IX Item "pragma"
+A standard module whose practical hints and
+suggestions are received (and possibly ignored) at compile time. Pragmas
+are named in all lowercase.
+.IX Xref "pragmas, about modules"
+.IP precedence 4
+.IX Item "precedence"
+The rules of
+conduct that, in the absence of other guidance, determine what should
+happen first.  For example, in the absence of parentheses, you always do
+multiplication before addition.
+.IX Xref "precedence rules, about operators, precedence rules"
+.IP prefix 4
+.IX Item "prefix"
+An \fBoperator\fR that precedes its \fBoperand\fR, as in
+\&\f(CW\*(C`++$x\*(C'\fR.
+.IX Xref "prefix operators"
+.IP preprocessing 4
+.IX Item "preprocessing"
+What some helper \fBprocess\fR did to transform the incoming
+data into a form more suitable for the current process. Often done with an
+incoming \fBpipe\fR. See also \fBC preprocessor\fR.
+.IX Xref "preprocessing"
+.IP "primary maintainer" 4
+.IX Item "primary maintainer"
+The author that PAUSE allows to assign \fBco-maintainer\fR
+permissions to a \fBnamespace\fR. A primary maintainer can give up this
+distinction by assigning it to another PAUSE author. See Camel chapter 19,
+“CPAN�.
+.IX Xref "primary maintainer"
+.IP procedure 4
+.IX Item "procedure"
+A \fBsubroutine\fR.
+.IX Xref "procedures, defined"
+.IP process 4
+.IX Item "process"
+An instance of a running program. Under multitasking
+systems like Unix, two or more separate processes could be running the same
+program independently at the same time—in fact, the \f(CW\*(C`fork\*(C'\fR function is
+designed to bring about this happy state of affairs. Under other operating
+systems, processes are sometimes called “threads�, “tasks�, or “jobs�,
+often with slight nuances in meaning.
+.IX Xref "processes, defined"
+.IP program 4
+.IX Item "program"
+See \fBscript\fR.
+.IP "program generator" 4
+.IX Item "program generator"
+A system that algorithmically writes code for you in a
+high-level language. See also \fBcode generator\fR.
+.IX Xref "program generators"
+.IP "progressive matching" 4
+.IX Item "progressive matching"
+\&\fBPattern matching\fR  matching>that picks up where it left off before.
+.IX Xref "progressive matching pattern matching, progressive matching"
+.IP property 4
+.IX Item "property"
+See either \fBinstance variable\fR or \fBcharacter property\fR.
+.IX Xref "property"
+.IP protocol 4
+.IX Item "protocol"
+In networking, an agreed-upon way of sending messages
+back and forth so that neither correspondent will get too confused.
+.IX Xref "protocols (term)"
+.IP prototype 4
+.IX Item "prototype"
+An optional part of a \fBsubroutine\fR declaration telling
+the Perl compiler how many and what flavor of arguments may be passed as
+\&\fBactual arguments\fR, so you can write subroutine calls that parse much like
+built-in functions. (Or don’t parse, as the case may be.)
+.IX Xref "prototypes, about"
+.IP pseudofunction 4
+.IX Item "pseudofunction"
+A construct that sometimes looks like a function but really
+isn’t. Usually reserved for \fBlvalue\fR modifiers like \f(CW\*(C`my\*(C'\fR, for \fBcontext\fR
+modifiers like \f(CW\*(C`scalar\*(C'\fR, and for the pick-your-own-quotes constructs,
+\&\f(CW\*(C`q//\*(C'\fR, \f(CW\*(C`qq//\*(C'\fR, \f(CW\*(C`qx//\*(C'\fR, \f(CW\*(C`qw//\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR, \f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`y///\*(C'\fR, and
+\&\f(CW\*(C`tr///\*(C'\fR.
+.IX Xref "pseudofunctions constructs, pseudofunctions functions, pseudofunctions"
+.IP pseudohash 4
+.IX Item "pseudohash"
+Formerly, a reference to an array
+whose initial element happens to hold a reference to a hash. You used to be
+able to treat a pseudohash reference as either an array reference or a hash
+reference. Pseudohashes are no longer supported.
+.IX Xref "pseudohashes hashes, pseudohashes"
+.IP pseudoliteral 4
+.IX Item "pseudoliteral"
+An \fBoperator\fR X\f(CW\*(C`that looks something like a \fR\f(CBliteral\fR\f(CW,
+such as the output\-grabbing operator, <literal
+moreinfo="none"\*(C'\fR`>\fR\f(CI\*(C`command\*(C'\fR\fI\fR\f(CW\*(C`\`\*(C'\fR.
+.IX Xref "pseudoliterals"
+.IP "public domain" 4
+.IX Item "public domain"
+Something not owned by anybody. Perl is copyrighted and is
+thus \fInot\fR in the public domain—it’s just \fBfreely available\fR and \fBfreely
+redistributable\fR.
+.IX Xref "public domain"
+.IP pumpkin 4
+.IX Item "pumpkin"
+A notional “baton� handed around the Perl community
+indicating who is the lead integrator in some arena of development.
+.IX Xref "pumpkin (term)"
+.IP pumpking 4
+.IX Item "pumpking"
+A \fBpumpkin\fR holder, the person in charge of pumping the pump,
+or at least priming it. Must be willing to play the part of the Great
+Pumpkin now and then.
+.IX Xref "pumpking"
+.IP PV 4
+.IX Item "PV"
+A “pointer value�, which is Perl
+Internals Talk for a \f(CW\*(C`char*\*(C'\fR.
+.IX Xref "PV (pointer value) pointer value (PV)"
+.SS Q
+.IX Subsection "Q"
+.IP qualified 4
+.IX Item "qualified"
+Possessing a complete name. The symbol \f(CW$Ent::moot\fR is
+qualified; \f(CW$moot\fR is unqualified. A fully qualified filename is specified
+from the top-level directory.
+.IX Xref "qualified (term)"
+.IP quantifier 4
+.IX Item "quantifier"
+A component of a \fBregular expression\fR specifying how
+many times the foregoing \fBatom\fR may occur.
+.IX Xref "quantifiers, about"
+.SS R
+.IX Subsection "R"
+.IP "race condition" 4
+.IX Item "race condition"
+A race condition exists when the result of
+several interrelated events depends on the ordering of those events, but
+that order cannot be guaranteed due to nondeterministic timing effects. If
+two or more programs, or parts of the same program, try to go through the
+same series of events, one might interrupt the work of the other. This is a
+good way to find an \fBexploit\fR.
+.IX Xref "race conditions, defined"
+.IP readable 4
+.IX Item "readable"
+With respect to files, one that has the proper permission
+bit set to let you access the file. With respect to computer programs, one
+that’s written well enough that someone has a chance of figuring out what
+it’s trying to do.
+.IX Xref "readable (term)"
+.IP reaping 4
+.IX Item "reaping"
+The last rites performed by a parent \fBprocess\fR
+on behalf of a deceased child process so that it doesn’t remain a
+\&\fBzombie\fR.  See the \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`waitpid\*(C'\fR function calls.
+.IX Xref "reaping zombie processes"
+.IP record 4
+.IX Item "record"
+A set of related data values in a \fBfile\fR or \fBstream\fR,
+often associated with a unique \fBkey\fR field. In Unix, often commensurate
+with a \fBline\fR, or a blank\-line–terminated set of lines (a “paragraph�).
+Each line of the \fI/etc/passwd\fR file is a record, keyed on login name,
+containing information about that user.
+.IX Xref "records, defined"
+.IP recursion 4
+.IX Item "recursion"
+The art of defining something (at least partly) in
+terms of itself, which is a naughty no-no in dictionaries but often works
+out okay in computer programs if you’re careful not to recurse forever
+(which is like an infinite loop with more spectacular failure modes).
+.IX Xref "recursion, defined"
+.IP reference 4
+.IX Item "reference"
+Where you look to find a pointer to information
+somewhere else. (See \fBindirection\fR.) References come in two flavors:
+\&\fBsymbolic references\fR and \fBhard references\fR.
+.IX Xref "references, about"
+.IP referent 4
+.IX Item "referent"
+Whatever a reference refers to, which may or may not
+have a name. Common types of referents include scalars, arrays, hashes, and
+subroutines.
+.IX Xref "referents, defined"
+.IP regex 4
+.IX Item "regex"
+See \fBregular expression\fR.
+.IP "regular expression" 4
+.IX Item "regular expression"
+A single entity with various
+interpretations, like an elephant. To a computer scientist, it’s a grammar
+for a little language in which some strings are legal and others aren’t. To
+normal people, it’s a pattern you can use to find what you’re looking for
+when it varies from case to case. Perl’s regular expressions are far from
+regular in the theoretical sense, but in regular use they work quite well.
+Here’s a regular expression: \f(CW\*(C`/Oh s.*t./\*(C'\fR. This will match strings like
+“\f(CW\*(C`Oh say can you see by the dawn\*(Aqs early light\*(C'\fR� and “\f(CW\*(C`Oh sit!\*(C'\fR�. See
+Camel chapter 5, “Pattern Matching�.
+.IX Xref "regular expressions, defined"
+.IP "regular expression modifier" 4
+.IX Item "regular expression modifier"
+An option on a pattern or substitution, such as \f(CW\*(C`/i\*(C'\fR to render the pattern
+case\- insensitive.
+.IX Xref "regular expression modifiers modifiers, regular expression"
+.IP "regular file" 4
+.IX Item "regular file"
+A \fBfile\fR that’s not a \fBdirectory\fR, a
+\&\fBdevice\fR, a named \fBpipe\fR or \fBsocket\fR, or a \fBsymbolic link\fR. Perl uses
+the \f(CW\*(C`–f\*(C'\fR file test operator to identify regular files. Sometimes called a
+“plain� file.
+.IX Xref "regular files files, regular"
+.IP "relational operator" 4
+.IX Item "relational operator"
+An \fBoperator\fR that says whether a particular
+ordering relationship is \fBtrue\fR about a pair of \fBoperands\fR. Perl has both
+numeric and string relational operators. See \fBcollating sequence\fR.
+.IX Xref "relational operators"
+.IP "reserved words" 4
+.IX Item "reserved words"
+A word with a specific, built-in meaning
+to a \fBcompiler\fR, such as \f(CW\*(C`if\*(C'\fR or \f(CW\*(C`delete\*(C'\fR. In many languages (not Perl),
+it’s illegal to use reserved words to name anything else. (Which is why
+they’re reserved, after all.) In Perl, you just can’t use them to name
+\&\fBlabels\fR or \fBfilehandles\fR. Also called “keywords�.
+.IX Xref "reserved words keywords (term)"
+.IP "return value" 4
+.IX Item "return value"
+The \fBvalue\fR produced by a \fBsubroutine\fR
+or \fBexpression\fR when evaluated. In Perl, a return value may be either a
+\&\fBlist\fR or a \fBscalar\fR.
+.IX Xref "return values values, return"
+.IP RFC 4
+.IX Item "RFC"
+Request For Comment, which despite the timid connotations is the name of a series of
+important standards documents.
+.IX Xref "Request For Comment (RFC) RFC (Request For Comment)"
+.IP "right shift" 4
+.IX Item "right shift"
+A \fBbit shift\fR that divides
+a number by some power of 2.
+.IX Xref "right shift (>>) bit operator bit–shift operators, right shift >> (right shift) bit operator"
+.IP role 4
+.IX Item "role"
+A name for a concrete set of behaviors. A role is a way to
+add behavior to a class without inheritance.
+.IX Xref "roles (term)"
+.IP root 4
+.IX Item "root"
+The superuser (\f(CW\*(C`UID\*(C'\fR == 0). Also the top-level directory of
+the filesystem.
+.IX Xref "root (term)"
+.IP RTFM 4
+.IX Item "RTFM"
+What you are told when someone thinks you should Read The
+Fine Manual.
+.IX Xref "RTFM acronym"
+.IP "run phase" 4
+.IX Item "run phase"
+Any time after Perl starts running your main program.
+See also \fBcompile phase\fR. Run phase is mostly spent in \fBruntime\fR but may
+also be spent in \fBcompile time\fR when \f(CW\*(C`require\*(C'\fR, \f(CW\*(C`do\*(C'\fR \fR\f(CI\*(C`FILE\*(C'\fR\fI\fR, or
+\&\f(CW\*(C`eval\*(C'\fR \fI\fR\f(CI\*(C`STRING\*(C'\fR\fI\fR operators are executed, or when a substitution uses
+the \f(CW\*(C`/ee\*(C'\fR modifier.
+.IX Xref "run phase, defined"
+.IP runtime 4
+.IX Item "runtime"
+The time when Perl is actually doing what your
+code says to do, as opposed to the earlier period of time when it was
+trying to figure out whether what you said made any sense whatsoever, which
+is \fBcompile time\fR.
+.IX Xref "runtime (term), defined"
+.IP "runtime pattern" 4
+.IX Item "runtime pattern"
+A pattern that contains one or more
+variables to be interpolated before parsing the pattern as a \fBregular
+expression\fR, and that therefore cannot be analyzed at compile time, but
+must be reanalyzed each time the pattern match operator is evaluated.
+Runtime patterns are useful but expensive.
+.IX Xref "runtime patterns patterns, runtime"
+.IP RV 4
+.IX Item "RV"
+A recreational vehicle, not
+to be confused with vehicular recreation. RV also means an internal
+Reference Value of the type a \fBscalar\fR can hold. See also \fBIV\fR and \fBNV\fR
+if you’re not confused yet.
+.IX Xref "Reference Value (RV) RV (Reference Value)"
+.IP rvalue 4
+.IX Item "rvalue"
+A \fBvalue\fR that you might find on the
+right side of an \fBassignment\fR. See also \fBlvalue\fR.
+.IX Xref "rvalue (term) values, rvalue"
+.SS S
+.IX Subsection "S"
+.IP sandbox 4
+.IX Item "sandbox"
+A walled off area that’s not supposed to affect beyond
+its walls. You let kids play in the sandbox instead of running in the road.
+See Camel chapter 20, “Security�.
+.IX Xref "sandbox, defined"
+.IP scalar 4
+.IX Item "scalar"
+A simple, singular value; a number, \fBstring\fR, or
+\&\fBreference\fR.
+.IX Xref "scalars, defined"
+.IP "scalar context" 4
+.IX Item "scalar context"
+The situation in which an
+\&\fBexpression\fR is expected by its surroundings (the code calling it) to
+return a single \fBvalue\fR rather than a \fBlist\fR of values. See also
+\&\fBcontext\fR and \fBlist context\fR. A scalar context sometimes imposes
+additional constraints on the return value—see \fBstring context\fR and
+\&\fBnumeric context\fR. Sometimes we talk about a \fBBoolean context\fR inside
+conditionals, but this imposes no additional constraints, since any scalar
+value, whether numeric or \fBstring\fR, is already true or false.
+.IX Xref "scalar context, about context, scalar"
+.IP "scalar literal" 4
+.IX Item "scalar literal"
+A number or quoted \fBstring\fR—an actual
+\&\fBvalue\fR in the text of your program, as opposed to a \fBvariable\fR.
+.IX Xref "scalar literals literals, scalar"
+.IP "scalar value" 4
+.IX Item "scalar value"
+A value that happens to be a
+\&\fBscalar\fR as opposed to a \fBlist\fR.
+.IX Xref "scalar values, about values, scalar SV"
+.IP "scalar variable" 4
+.IX Item "scalar variable"
+A \fBvariable\fR prefixed with
+\&\f(CW\*(C`$\*(C'\fR that holds a single value.
+.IX Xref "scalar variables, defined variables, scalar"
+.IP scope 4
+.IX Item "scope"
+From how far away you can see a variable, looking through
+one. Perl has two visibility mechanisms. It does \fBdynamic scoping\fR of
+\&\f(CW\*(C`local\*(C'\fR \fBvariables\fR, meaning that the rest of the \fBblock\fR, and any
+\&\fBsubroutines\fR that are called by the rest of the block, can see the
+variables that are local to the block. Perl does \fBlexical scoping\fR of
+\&\f(CW\*(C`my\*(C'\fR variables, meaning that the rest of the block can see the variable,
+but other subroutines called by the block \fIcannot\fR see the variable.
+.IX Xref "scopes, defined"
+.IP scratchpad 4
+.IX Item "scratchpad"
+The area in which a particular invocation of a particular
+file or subroutine keeps some of its temporary values, including any
+lexically scoped variables.
+.IX Xref "scratchpads"
+.IP script 4
+.IX Item "script"
+A text \fBfile\fR that is a program
+intended to be \fBexecuted\fR directly rather than \fBcompiled\fR to another form
+of file before \fBexecution\fR.
+.IX Xref "scripts (term) programs, defined"
+.Sp
+Also, in the context of \fBUnicode\fR, a writing system for a particular
+language or group of languages, such as Greek, Bengali, or Tengwar.
+.IP "script kiddie" 4
+.IX Item "script kiddie"
+A \fBcracker\fR who is not a \fBhacker\fR but knows just enough
+to run canned scripts. A \fBcargo-cult\fR programmer.
+.IX Xref "script kiddie"
+.IP sed 4
+.IX Item "sed"
+A venerable Stream EDitor from
+which Perl derives some of its ideas.
+.IX Xref "sed (Stream EDitor) Stream EDitor (sed)"
+.IP semaphore 4
+.IX Item "semaphore"
+A fancy kind of interlock that prevents multiple \fBthreads\fR or
+\&\fBprocesses\fR from using up the same resources simultaneously.
+.IX Xref "semaphore"
+.IP separator 4
+.IX Item "separator"
+A \fBcharacter\fR or \fBstring\fR that keeps two surrounding strings from being
+confused with each other. The \f(CW\*(C`split\*(C'\fR function works on separators. Not to be confused with \fBdelimiters\fR
+or \fBterminators\fR. The “or� in the previous sentence separated the two
+alternatives.
+.IX Xref "separators characters, separators strings, separators split function, separators and"
+.IP serialization 4
+.IX Item "serialization"
+Putting a fancy \fBdata structure\fR into
+linear order so that it can be stored as a \fBstring\fR in a disk file or
+database, or sent through a \fBpipe\fR. Also called marshalling.
+.IX Xref "serialization marshalling (term)"
+.IP server 4
+.IX Item "server"
+In networking, a \fBprocess\fR that
+either advertises a \fBservice\fR or just hangs around at a known location and
+waits for \fBclients\fR who need service to get in touch with it.
+.IX Xref "servers, defined processes, server"
+.IP service 4
+.IX Item "service"
+Something you do for someone else to make them happy,
+like giving them the time of day (or of their life). On some machines,
+well-known services are listed by the \f(CW\*(C`getservent\*(C'\fR
+function.
+.IX Xref "services (term) getservent function"
+.IP setgid 4
+.IX Item "setgid"
+Same as \fBsetuid\fR, only having to do with giving
+away \fBgroup\fR privileges.
+.IX Xref "setgid program, about"
+.IP setuid 4
+.IX Item "setuid"
+Said of a program that runs with the privileges of
+its \fBowner\fR rather than (as is usually the case) the privileges of whoever
+is running it. Also describes the bit in the mode word (\fBpermission bits\fR)
+that controls the feature. This bit must be explicitly set by the owner to
+enable this feature, and the program must be carefully written not to give
+away more privileges than it ought to.
+.IX Xref "setuid program, about"
+.IP "shared memory" 4
+.IX Item "shared memory"
+A piece of \fBmemory\fR accessible by two
+different \fBprocesses\fR who otherwise would not see each other’s memory.
+.IX Xref "shared memory memory, shared"
+.IP shebang 4
+.IX Item "shebang"
+Irish for the whole McGillicuddy. In Perl culture, a
+portmanteau of “sharp� and “bang�, meaning the \f(CW\*(C`#!\*(C'\fR sequence that tells
+the system where to find the interpreter.
+.IX Xref "shebang (term)"
+.IP shell 4
+.IX Item "shell"
+A \fBcommand\fR\-line \fBinterpreter\fR. The program that
+interactively gives you a prompt, accepts one or more \fBlines\fR of input,
+and executes the programs you mentioned, feeding each of them their proper
+\&\fBarguments\fR and input data. Shells can also execute scripts containing
+such commands. Under Unix, typical shells include the Bourne shell
+(\fI/bin/sh\fR), the C shell (\fI/bin/csh\fR), and the Korn shell (\fI/bin/ksh\fR).
+Perl is not strictly a shell because it’s not interactive (although Perl
+programs can be interactive).
+.IX Xref "shell program, defined"
+.IP "side effects" 4
+.IX Item "side effects"
+Something extra that happens when you evaluate an
+\&\fBexpression\fR. Nowadays it can refer to almost anything. For example,
+evaluating a simple assignment statement typically has the “side effect� of
+assigning a value to a variable. (And you thought assigning the value was
+your primary intent in the first place!) Likewise, assigning a value to the
+special variable \f(CW$|\fR (\f(CW$AUTOFLUSH\fR) has the side effect of forcing a
+flush after every \f(CW\*(C`write\*(C'\fR or \f(CW\*(C`print\*(C'\fR on the currently selected
+filehandle.
+.IX Xref "side effects"
+.IP sigil 4
+.IX Item "sigil"
+A glyph used in magic. Or, for Perl, the symbol in front
+of a variable name, such as \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, and \f(CW\*(C`%\*(C'\fR.
+.IX Xref "sigils, defined"
+.IP signal 4
+.IX Item "signal"
+A bolt out of the blue; that is, an
+event triggered by the \fBoperating system\fR, probably when you’re least
+expecting it.
+.IX Xref "signals and signal handling, about"
+.IP "signal handler" 4
+.IX Item "signal handler"
+A \fBsubroutine\fR that, instead of being content to be
+called in the normal fashion, sits around waiting for a bolt out of the
+blue before it will deign to \fBexecute\fR. Under Perl, bolts out of the blue
+are called signals, and you send them with the \f(CW\*(C`kill\*(C'\fR built-in. See the
+\&\f(CW%SIG\fR hash in Camel chapter 25, “Special Names� and the section “Signals�
+in Camel chapter 15, “Interprocess Communication�.
+.IX Xref "handlers, signal"
+.IP "single inheritance" 4
+.IX Item "single inheritance"
+The features you got from your
+mother, if she told you that you don’t have a father. (See also
+\&\fBinheritance\fR and \fBmultiple inheritance\fR.) In computer languages, the
+idea that \fBclasses\fR reproduce asexually so that a given class can only
+have one direct ancestor or \fBbase class\fR. Perl supplies no such
+restriction, though you may certainly program Perl that way if you like.
+.IX Xref "single inheritance inheritance, single"
+.IP slice 4
+.IX Item "slice"
+A selection of any number of
+\&\fBelements\fR from a \fBlist\fR, \fBarray\fR, or \fBhash\fR.
+.IX Xref "slices of elements elements, slices of"
+.IP slurp 4
+.IX Item "slurp"
+To read an entire \fBfile\fR into a \fBstring\fR in one operation.
+.IX Xref "slurp (term)"
+.IP socket 4
+.IX Item "socket"
+An endpoint for network communication among multiple
+\&\fBprocesses\fR that works much like a telephone or a post office box. The
+most important thing about a socket is its \fBnetwork address\fR (like a phone
+number). Different kinds of sockets have different kinds of addresses—some
+look like filenames, and some don’t.
+.IX Xref "sockets, defined"
+.IP "soft reference" 4
+.IX Item "soft reference"
+See \fBsymbolic reference\fR.
+.IX Xref "soft references references, soft"
+.IP "source filter" 4
+.IX Item "source filter"
+A special kind of \fBmodule\fR that does
+\&\fBpreprocessing\fR on your script just before it gets to the \fBtokener\fR.
+.IX Xref "source filters filters, source"
+.IP stack 4
+.IX Item "stack"
+A device you can put things on the top of, and later take
+them back off in the opposite order in which you put them on. See \fBLIFO\fR.
+.IX Xref "stacks, defined"
+.IP standard 4
+.IX Item "standard"
+Included in the official Perl distribution, as in a
+standard module, a standard tool, or a standard Perl \fBmanpage\fR.
+.IX Xref "standard (term)"
+.IP "standard error" 4
+.IX Item "standard error"
+The default output \fBstream\fR for nasty remarks that don’t belong in
+\&\fBstandard output\fR. Represented within a Perl program by the output>  \fBfilehandle\fR \f(CW\*(C`STDERR\*(C'\fR. You can use this
+stream explicitly, but the \f(CW\*(C`die\*(C'\fR and \f(CW\*(C`warn\*(C'\fR built-ins write to your
+standard error stream automatically (unless trapped or otherwise
+intercepted).
+.IX Xref "STDERR filehandle, about"
+.IP "standard input" 4
+.IX Item "standard input"
+The default input \fBstream\fR for your program,
+which if possible shouldn’t care where its data is coming from. Represented
+within a Perl program by the \fBfilehandle\fR \f(CW\*(C`STDIN\*(C'\fR.
+.IX Xref "STDIN filehandle, about"
+.IP "standard I/O" 4
+.IX Item "standard I/O"
+A standard C library for doing \fBbuffered\fR input
+and output to the \fBoperating system\fR. (The “standard� of standard I/O is
+at most marginally related to the “standard� of standard input and output.)
+In general, Perl relies on whatever implementation of standard I/O a given
+operating system supplies, so the buffering characteristics of a Perl
+program on one machine may not exactly match those on another machine.
+Normally this only influences efficiency, not semantics. If your standard
+I/O package is doing block buffering and you want it to \fBflush\fR the buffer
+more often, just set the \f(CW$|\fR variable to a true value.
+.IX Xref "standard I O I O (Input Output), standard Input Output (I O), standard STDIO filehandle"
+.IP "Standard Library" 4
+.IX Item "Standard Library"
+Everything that comes with the official
+\&\fIperl\fR distribution. Some vendor versions of \fIperl\fR change their
+distributions, leaving out some parts or including extras. See also
+\&\fBdual-lived\fR.
+.IX Xref "Standard Perl Library, about"
+.IP "standard output" 4
+.IX Item "standard output"
+The default output \fBstream\fR for your program,
+which if possible shouldn’t care where its data is going. Represented
+within a Perl program by the \fBfilehandle\fR \f(CW\*(C`STDOUT\*(C'\fR.
+.IX Xref "STDOUT filehandle, about"
+.IP statement 4
+.IX Item "statement"
+A \fBcommand\fR to the computer about what to do next,
+like a step in a recipe: “Add marmalade to batter and mix until mixed.� A
+statement is distinguished from a \fBdeclaration\fR, which doesn’t tell the
+computer to do anything, but just to learn something.
+.IX Xref "statements, about"
+.IP "statement modifier" 4
+.IX Item "statement modifier"
+A \fBconditional\fR or
+\&\fBloop\fR that you put after the \fBstatement\fR instead of before, if you know
+what we mean.
+.IX Xref "statement modifiers, about modifiers, statement"
+.IP static 4
+.IX Item "static"
+Varying slowly compared to something else. (Unfortunately,
+everything is relatively stable compared to something else, except for
+certain elementary particles, and we’re not so sure about them.) In
+computers, where things are supposed to vary rapidly, “static� has a
+derogatory connotation, indicating a slightly dysfunctional \fBvariable\fR,
+\&\fBsubroutine\fR, or \fBmethod\fR. In Perl culture, the word is politely avoided.
+.IX Xref "static (term)"
+.Sp
+If you’re a C or C++ programmer, you might be looking for Perl’s \f(CW\*(C`state\*(C'\fR
+keyword.
+.IP "static method" 4
+.IX Item "static method"
+No such thing. See \fBclass method\fR.
+.IX Xref "static methods methods, static"
+.IP "static scoping" 4
+.IX Item "static scoping"
+No such thing. See \fBlexical scoping\fR.
+.IP "static variable" 4
+.IX Item "static variable"
+No such thing. Just use a \fBlexical
+variable\fR in a scope larger than your \fBsubroutine\fR, or declare it with
+\&\f(CW\*(C`state\*(C'\fR instead of with \f(CW\*(C`my\*(C'\fR.
+.IX Xref "static variables variables, static"
+.IP "stat structure" 4
+.IX Item "stat structure"
+A special internal spot
+in which Perl keeps the information about the last \fBfile\fR on which you
+requested information.
+.IX Xref "stat structure data structures, stat structure"
+.IP status 4
+.IX Item "status"
+The \fBvalue\fR returned to the
+parent \fBprocess\fR when one of its child processes dies. This value is
+placed in the special variable \f(CW$?\fR. Its upper eight \fBbits\fR are the exit
+status of the defunct process, and its lower eight bits identify the signal
+(if any) that the process died from. On Unix systems, this status value is
+the same as the status word returned by \fIwait\fR(2). See \f(CW\*(C`system\*(C'\fR in Camel
+chapter 27, “Functions�.
+.IX Xref "status value values, status exit status"
+.IP STDERR 4
+.IX Item "STDERR"
+See \fBstandard error\fR.
+.IP STDIN 4
+.IX Item "STDIN"
+See \fBstandard input\fR.
+.IP STDIO 4
+.IX Item "STDIO"
+See \fBstandard I/O\fR.
+.IP STDOUT 4
+.IX Item "STDOUT"
+See \fBstandard output\fR.
+.IP stream 4
+.IX Item "stream"
+A flow of data into or out of
+a process as a steady sequence of bytes or characters, without the
+appearance of being broken up into packets. This is a kind of
+\&\fBinterface\fR—the underlying \fBimplementation\fR may well break your data up
+into separate packets for delivery, but this is hidden from you.
+.IX Xref "streaming data processes, streaming data"
+.IP string 4
+.IX Item "string"
+A sequence of characters such as “He said !@#*&%@#*?!�.
+A string does not have to be entirely printable.
+.IX Xref "strings, defined"
+.IP "string context" 4
+.IX Item "string context"
+The situation in which an expression is
+expected by its surroundings (the code calling it) to return a \fBstring\fR.
+See also \fBcontext\fR and \fBnumeric context\fR.
+.IX Xref "string context context, string"
+.IP stringification 4
+.IX Item "stringification"
+The process of producing a \fBstring\fR representation of an
+abstract object.
+.IX Xref "stringification"
+.IP struct 4
+.IX Item "struct"
+C keyword introducing a structure definition or name.
+.IX Xref "struct keyword"
+.IP structure 4
+.IX Item "structure"
+See \fBdata structure\fR.
+.IX Xref "structures"
+.IP subclass 4
+.IX Item "subclass"
+See \fBderived class\fR.
+.IP subpattern 4
+.IX Item "subpattern"
+A component of a \fBregular expression\fR pattern.
+.IX Xref "subpatterns, defined"
+.IP subroutine 4
+.IX Item "subroutine"
+A named or otherwise accessible piece of program
+that can be invoked from elsewhere in the program in order to accomplish
+some subgoal of the program. A subroutine is often parameterized to
+accomplish different but related things depending on its input
+\&\fBarguments\fR. If the subroutine returns a meaningful \fBvalue\fR, it is also
+called a \fBfunction\fR.
+.IX Xref "subroutines, defined"
+.IP subscript 4
+.IX Item "subscript"
+A \fBvalue\fR that indicates the position of a particular
+\&\fBarray\fR \fBelement\fR in an array.
+.IX Xref "subscripts"
+.IP substitution 4
+.IX Item "substitution"
+Changing parts of a string via the \f(CW\*(C`s///\*(C'\fR
+operator. (We avoid use of this term to mean \fBvariable interpolation\fR.)
+.IX Xref "substitution (s ) operator, about strings, substitution in s (substitution) operator, about"
+.IP substring 4
+.IX Item "substring"
+A portion of a \fBstring\fR, starting at a certain
+\&\fBcharacter\fR position (\fBoffset\fR) and proceeding for a certain number of
+characters.
+.IX Xref "substrings (term)"
+.IP superclass 4
+.IX Item "superclass"
+See \fBbase class\fR.
+.IP superuser 4
+.IX Item "superuser"
+The person whom the \fBoperating system\fR will let do almost
+anything. Typically your system administrator or someone pretending to be
+your system administrator. On Unix systems, the \fBroot\fR user. On Windows
+systems, usually the Administrator user.
+.IX Xref "superusers"
+.IP SV 4
+.IX Item "SV"
+Short for “scalar value�. But
+within the Perl interpreter, every \fBreferent\fR is treated as a member of a
+class derived from SV, in an object-oriented sort of way. Every \fBvalue\fR
+inside Perl is passed around as a C language \f(CW\*(C`SV*\*(C'\fR pointer. The SV
+\&\fBstruct\fR knows its own “referent type�, and the code is smart enough (we
+hope) not to try to call a \fBhash\fR function on a \fBsubroutine\fR.
+.IX Xref "scalar values, about values, scalar"
+.IP switch 4
+.IX Item "switch"
+An option you give on a command line to
+influence the way your program works, usually introduced with a minus sign.
+The word is also used as a nickname for a \fBswitch statement\fR.
+.IX Xref "switches, about switches"
+.IP "switch cluster" 4
+.IX Item "switch cluster"
+The combination of multiple command\-
+line switches (\fIe.g.\fR, \f(CW\*(C`–a –b –c\*(C'\fR) into one switch (\fIe.g.\fR, \f(CW\*(C`–abc\*(C'\fR).
+Any switch with an additional \fBargument\fR must be the last switch in a
+cluster.
+.IX Xref "switch clusters clusters, switch"
+.IP "switch statement" 4
+.IX Item "switch statement"
+A program technique that lets you
+evaluate an \fBexpression\fR and then, based on the value of the expression,
+do a multiway branch to the appropriate piece of code for that value. Also
+called a “case structure�, named after the similar Pascal construct. Most
+switch statements in Perl are spelled \f(CW\*(C`given\*(C'\fR. See “The \f(CW\*(C`given\*(C'\fR
+statement� in Camel chapter 4, “Statements and Declarations�.
+.IX Xref "switch statement statements, switch"
+.IP symbol 4
+.IX Item "symbol"
+Generally, any \fBtoken\fR or \fBmetasymbol\fR. Often used
+more specifically to mean the sort of name you might find in a \fBsymbol
+table\fR.
+.IX Xref "symbols symbols"
+.IP "symbolic debugger" 4
+.IX Item "symbolic debugger"
+A program that lets you step through
+the \fBexecution\fR of your program, stopping or printing things out here and
+there to see whether anything has gone wrong, and, if so, what. The
+“symbolic� part just means that you can talk to the debugger using the same
+symbols with which your program is written.
+.IX Xref "symbolic debugger debugger, about"
+.IP "symbolic link" 4
+.IX Item "symbolic link"
+An alternate filename that points to the
+real \fBfilename\fR, which in turn points to the real \fBfile\fR. Whenever the
+\&\fBoperating system\fR is trying to parse a \fBpathname\fR containing a symbolic
+link, it merely substitutes the new name and continues parsing.
+.IX Xref "symbolic links links, symbolic"
+.IP "symbolic reference" 4
+.IX Item "symbolic reference"
+A variable whose value is the
+name of another variable or subroutine. By \fBdereferencing\fR the first
+variable, you can get at the second one. Symbolic references are illegal
+under \f(CW\*(C`use strict "refs"\*(C'\fR.
+.IX Xref "symbolic references references, symbolic"
+.IP "symbol table" 4
+.IX Item "symbol table"
+Where a \fBcompiler\fR remembers symbols. A program
+like Perl must somehow remember all the names of all the \fBvariables\fR,
+\&\fBfilehandles\fR, and \fBsubroutines\fR you’ve used. It does this by placing the
+names in a symbol table, which is implemented in Perl using a \fBhash
+table\fR. There is a separate symbol table for each \fBpackage\fR to give each
+package its own \fBnamespace\fR.
+.IX Xref "symbol tables, about"
+.IP synchronous 4
+.IX Item "synchronous"
+Programming in which the orderly sequence of events
+can be determined; that is, when things happen one after the other, not at
+the same time.
+.IX Xref "synchronous (term)"
+.IP "syntactic sugar" 4
+.IX Item "syntactic sugar"
+An alternative way of writing something more easily; a
+shortcut.
+.IX Xref "syntactic sugar"
+.IP syntax 4
+.IX Item "syntax"
+From Greek σ�νταξις, “with\-arrangement�. How things
+(particularly symbols) are put together with each other.
+.IX Xref "syntax, about"
+.IP "syntax tree" 4
+.IX Item "syntax tree"
+An internal representation of your program wherein
+lower-level \fBconstructs\fR dangle off the higher-level constructs enclosing
+them.
+.IX Xref "syntax tree"
+.IP syscall 4
+.IX Item "syscall"
+A \fBfunction\fR call directly to the \fBoperating
+system\fR. Many of the important subroutines and functions you use aren’t
+direct system calls, but are built up in one or more layers above the
+system call level. In general, Perl programmers don’t need to worry about
+the distinction. However, if you do happen to know which Perl functions are
+really syscalls, you can predict which of these will set the \f(CW$!\fR
+(\f(CW$ERRNO\fR) variable on failure. Unfortunately, beginning programmers often
+confusingly employ the term “system call� to mean what happens when you
+call the Perl \f(CW\*(C`system\*(C'\fR function, which actually involves many syscalls. To
+avoid any confusion, we nearly always say “syscall� for something you could
+call indirectly via Perl’s \f(CW\*(C`syscall\*(C'\fR function, and never for something you
+would call with Perl’s \f(CW\*(C`system\*(C'\fR function.
+.IX Xref "syscall function, about"
+.SS T
+.IX Subsection "T"
+.IP "taint checks" 4
+.IX Item "taint checks"
+The special bookkeeping Perl does to track the flow
+of external data through your program and disallow their use in system
+commands.
+.IX Xref "taint checks, about"
+.IP tainted 4
+.IX Item "tainted"
+Said of data derived from the grubby hands of a user,
+and thus unsafe for a secure program to rely on. Perl does taint checks if
+you run a \fBsetuid\fR (or \fBsetgid\fR) program, or if you use the \f(CW\*(C`–T\*(C'\fR switch.
+.IX Xref "tainted data, about"
+.IP "taint mode" 4
+.IX Item "taint mode"
+Running under the \f(CW\*(C`–T\*(C'\fR switch, marking all external data as
+suspect and refusing to use it with system commands. See Camel chapter 20,
+“Security�.
+.IX Xref "taint mode"
+.IP TCP 4
+.IX Item "TCP"
+Short for Transmission Control Protocol. A protocol wrapped around the
+Internet Protocol to make an unreliable packet transmission mechanism
+appear to the application program to be a reliable \fBstream\fR of bytes.
+(Usually.)
+.IX Xref "TCP (Transmission Control Protocol) Transmission Control Protocol (TCP)"
+.IP term 4
+.IX Item "term"
+Short for a “terminal�—that is, a leaf node of a \fBsyntax
+tree\fR. A thing that functions grammatically as an \fBoperand\fR for the
+operators in an expression.
+.IX Xref "terms, defined"
+.IP terminator 4
+.IX Item "terminator"
+A \fBcharacter\fR or \fBstring\fR that marks the end of another string. The \f(CW$/\fR
+variable contains the string that terminates a \f(CW\*(C`readline\*(C'\fR operation, which
+\&\f(CW\*(C`chomp\*(C'\fR deletes from the end. Not to be confused with \fBdelimiters\fR or
+\&\fBseparators\fR. The period at the end of this sentence is a terminator.
+.IX Xref "terminators (term) characters, terminators strings, terminators in"
+.IP ternary 4
+.IX Item "ternary"
+An \fBoperator\fR taking three \fBoperands\fR. Sometimes
+pronounced \fBtrinary\fR.
+.IX Xref "ternary operators"
+.IP text 4
+.IX Item "text"
+A \fBstring\fR or \fBfile\fR containing primarily printable characters.
+.IX Xref "text, defined strings, text files, text text"
+.IP thread 4
+.IX Item "thread"
+Like a forked process, but without \fBfork\fR’s inherent
+memory protection. A thread is lighter weight than a full process, in that
+a process could have multiple threads running around in it, all fighting
+over the same process’s memory space unless steps are taken to protect
+threads from one another.
+.IX Xref "threads (term)"
+.IP tie 4
+.IX Item "tie"
+The bond between a magical variable and its
+implementation class. See the \f(CW\*(C`tie\*(C'\fR function in Camel chapter 27,
+“Functions� and Camel chapter 14, “Tied Variables�.
+.IX Xref "tied variables, about"
+.IP titlecase 4
+.IX Item "titlecase"
+The case used for capitals
+that are followed by lowercase characters instead of by more capitals.
+Sometimes called sentence case or headline case. English doesn’t use
+Unicode titlecase, but casing rules for English titles are more complicated
+than simply capitalizing each word’s first character.
+.IX Xref "titlecase characters characters, titlecase"
+.IP TMTOWTDI 4
+.IX Item "TMTOWTDI"
+There’s More Than One Way To Do It, the Perl Motto. The
+notion that there can be more than one valid path to solving a programming
+problem in context. (This doesn’t mean that more ways are always better or
+that all possible paths are equally desirable—just that there need not be
+One True Way.)
+.IX Xref "TMTOWTDI acronym"
+.IP token 4
+.IX Item "token"
+A morpheme in a programming language, the smallest unit
+of text with semantic significance.
+.IX Xref "tokens, defined"
+.IP tokener 4
+.IX Item "tokener"
+A module that breaks a program text into a sequence of
+\&\fBtokens\fR for later analysis by a parser.
+.IX Xref "tokeners, defined"
+.IP tokenizing 4
+.IX Item "tokenizing"
+Splitting up a program text into \fBtokens\fR. Also known as
+“lexing�, in which case you get “lexemes� instead of tokens.
+.IX Xref "tokenizing"
+.IP "toolbox approach" 4
+.IX Item "toolbox approach"
+The notion that, with a complete set of simple tools
+that work well together, you can build almost anything you want. Which is
+fine if you’re assembling a tricycle, but if you’re building a
+defranishizing comboflux regurgalator, you really want your own machine
+shop in which to build special tools. Perl is sort of a machine shop.
+.IX Xref "toolbox approach"
+.IP topic 4
+.IX Item "topic"
+The thing you’re working on. Structures like
+\&\f(CWwhile(<>)\fR, \f(CW\*(C`for\*(C'\fR, \f(CW\*(C`foreach\*(C'\fR, and \f(CW\*(C`given\*(C'\fR set the topic for
+you by assigning to \f(CW$_\fR, the default (\fItopic\fR) variable.
+.IX Xref "topics (term)"
+.IP transliterate 4
+.IX Item "transliterate"
+To turn one string
+representation into another by mapping each character of the source string
+to its corresponding character in the result string. Not to be confused
+with translation: for example, Greek \fIπολ�χ�ωμος\fR transliterates into
+\&\fIpolychromos\fR but translates into \fImany-colored\fR. See the \f(CW\*(C`tr///\*(C'\fR
+operator in Camel chapter 5, “Pattern Matching�.
+.IX Xref "tr (transliteration) operator, about strings, transliteration of transliteration (tr ) operator, about"
+.IP trigger 4
+.IX Item "trigger"
+An event that causes a \fBhandler\fR to be run.
+.IX Xref "triggers (term)"
+.IP trinary 4
+.IX Item "trinary"
+Not a stellar system with three stars, but an
+\&\fBoperator\fR taking three \fBoperands\fR. Sometimes pronounced \fBternary\fR.
+.IX Xref "trinary operators"
+.IP troff 4
+.IX Item "troff"
+A venerable typesetting language from which Perl derives
+the name of its \f(CW$%\fR variable and which is secretly used in the production
+of Camel books.
+.IX Xref "troff language"
+.IP true 4
+.IX Item "true"
+Any scalar value that doesn’t evaluate to 0 or
+\&\f(CW""\fR.
+.IX Xref "true values values, true"
+.IP truncating 4
+.IX Item "truncating"
+Emptying a file of existing
+contents, either automatically when opening a file for writing or
+explicitly via the \f(CW\*(C`truncate\*(C'\fR function.
+.IX Xref "truncate function files, truncating"
+.IP type 4
+.IX Item "type"
+See \fBdata type\fR and \fBclass\fR.
+.IX Xref "type"
+.IP "type casting" 4
+.IX Item "type casting"
+Converting data from one type to another. C permits this.
+Perl does not need it. Nor want it.
+.IX Xref "type casting"
+.IP typedef 4
+.IX Item "typedef"
+A type definition in the C and C++ languages.
+.IX Xref "typedef"
+.IP "typed lexical" 4
+.IX Item "typed lexical"
+A \fBlexical variable\fR  lexical>that is declared with a \fBclass\fR
+type: \f(CW\*(C`my Pony $bill\*(C'\fR.
+.IX Xref "typed lexicals lexical variables, typed lexicals variables, variable"
+.IP typeglob 4
+.IX Item "typeglob"
+Use of a single identifier, prefixed with \f(CW\*(C`*\*(C'\fR. For
+example, \f(CW*name\fR stands for any or all of \f(CW$name\fR, \f(CW@name\fR, \f(CW%name\fR,
+\&\f(CW&name\fR, or just \f(CW\*(C`name\*(C'\fR. How you use it determines whether it is
+interpreted as all or only one of them. See “Typeglobs and Filehandles� in
+Camel chapter 2, “Bits and Pieces�.
+.IX Xref "typeglobs, defined"
+.IP typemap 4
+.IX Item "typemap"
+A description of how C types may be transformed to and from Perl
+types within an \fBextension\fR module written in \fBXS\fR.
+.IX Xref "typemap"
+.SS U
+.IX Subsection "U"
+.IP UDP 4
+.IX Item "UDP"
+User Datagram Protocol, the typical way to send
+\&\fBdatagrams\fR over the Internet.
+.IX Xref "User Datagram Protocol (UDP) UDP (User Datagram Protocol) datagrams, UDP support"
+.IP UID 4
+.IX Item "UID"
+A user ID. Often used in the context of
+\&\fBfile\fR or \fBprocess\fR ownership.
+.IX Xref "UID (user ID) user ID (UID)"
+.IP umask 4
+.IX Item "umask"
+A mask of those \fBpermission bits\fR that should be forced
+off when creating files or directories, in order to establish a policy of
+whom you’ll ordinarily deny access to. See the \f(CW\*(C`umask\*(C'\fR function.
+.IX Xref "umask function"
+.IP "unary operator" 4
+.IX Item "unary operator"
+An operator with only one \fBoperand\fR, like \f(CW\*(C`!\*(C'\fR or
+\&\f(CW\*(C`chdir\*(C'\fR. Unary operators are usually prefix operators; that is, they
+precede their operand. The \f(CW\*(C`++\*(C'\fR and \f(CW\*(C`––\*(C'\fR operators can be either prefix
+or postfix. (Their position \fIdoes\fR change their meanings.)
+.IX Xref "unary operators, about"
+.IP Unicode 4
+.IX Item "Unicode"
+A character set comprising all the major character sets of
+the world, more or less. See <http://www.unicode.org>.
+.IX Xref "Unicode, about"
+.IP Unix 4
+.IX Item "Unix"
+A very large and constantly evolving language with several
+alternative and largely incompatible syntaxes, in which anyone can define
+anything any way they choose, and usually do. Speakers of this language
+think it’s easy to learn because it’s so easily twisted to one’s own ends,
+but dialectical differences make tribal intercommunication nearly
+impossible, and travelers are often reduced to a pidgin-like subset of the
+language. To be universally understood, a Unix shell programmer must spend
+years of study in the art. Many have abandoned this discipline and now
+communicate via an Esperanto-like language called Perl.
+.IX Xref "Unix language"
+.Sp
+In ancient times, Unix was also used to refer to some code that a couple of
+people at Bell Labs wrote to make use of a PDP\-7 computer that wasn’t doing
+much of anything else at the time.
+.IP uppercase 4
+.IX Item "uppercase"
+In Unicode, not just
+characters with the General Category of Uppercase Letter, but any character
+with the Uppercase property, including some Letter Numbers and Symbols. Not
+to be confused with \fBtitlecase\fR.
+.IX Xref "uppercase characters characters, uppercase"
+.SS V
+.IX Subsection "V"
+.IP value 4
+.IX Item "value"
+An actual piece of data, in contrast to all the
+variables, references, keys, indices, operators, and whatnot that you need
+to access the value.
+.IX Xref "values, defined"
+.IP variable 4
+.IX Item "variable"
+A named storage location that can hold any
+of various kinds of \fBvalue\fR, as your program sees fit.
+.IX Xref "variables, defined variables"
+.IP "variable interpolation" 4
+.IX Item "variable interpolation"
+The \fBinterpolation\fR of
+a scalar or array variable into a string.
+.IX Xref "variable interpolation interpolation, variable"
+.IP variadic 4
+.IX Item "variadic"
+Said of a \fBfunction\fR that happily receives an
+indeterminate number of \fBactual arguments\fR.
+.IX Xref "variadic (term)"
+.IP vector 4
+.IX Item "vector"
+Mathematical jargon for a list of \fBscalar values\fR.
+.IX Xref "vectors"
+.IP virtual 4
+.IX Item "virtual"
+Providing the appearance of something without the reality,
+as in: virtual memory is not real memory. (See also \fBmemory\fR.) The
+opposite of “virtual� is “transparent�, which means providing the reality
+of something without the appearance, as in: Perl handles the
+variable-length UTF‑8 character encoding transparently.
+.IX Xref "virtual (term)"
+.IP "void context" 4
+.IX Item "void context"
+A form of \fBscalar context\fR in which an
+\&\fBexpression\fR is not expected to return any \fBvalue\fR at all and is
+evaluated for its \fBside effects\fR alone.
+.IX Xref "void context context, void"
+.IP v\-string 4
+.IX Item "v-string"
+A “version� or “vector� \fBstring\fR
+specified with a \f(CW\*(C`v\*(C'\fR followed by a series of decimal integers in dot
+notation, for instance, \f(CW\*(C`v1.20.300.4000\*(C'\fR. Each number turns into a
+\&\fBcharacter\fR with the specified ordinal value. (The \f(CW\*(C`v\*(C'\fR is optional when
+there are at least three integers.)
+.IX Xref "v–strings strings, v–strings"
+.SS W
+.IX Subsection "W"
+.IP warning 4
+.IX Item "warning"
+A message printed to the \f(CW\*(C`STDERR\*(C'\fR stream to the effect that something might be
+wrong but isn’t worth blowing up over. See \f(CW\*(C`warn\*(C'\fR in Camel chapter 27,
+“Functions� and the \f(CW\*(C`warnings\*(C'\fR pragma in Camel chapter 28, “Pragmantic
+Modules�.
+.IX Xref "warning messages STDERR filehandle, warning messages and"
+.IP "watch expression" 4
+.IX Item "watch expression"
+An expression which, when its value
+changes, causes a breakpoint in the Perl debugger.
+.IX Xref "watch expression expressions, watch"
+.IP "weak reference" 4
+.IX Item "weak reference"
+A reference that doesn’t get counted
+normally. When all the normal references to data disappear, the data
+disappears. These are useful for circular references that would never
+disappear otherwise.
+.IX Xref "weak references references, weak"
+.IP whitespace 4
+.IX Item "whitespace"
+A \fBcharacter\fR that moves
+your cursor but doesn’t otherwise put anything on your screen. Typically
+refers to any of: space, tab, line feed, carriage return, or form feed. In
+Unicode, matches many other characters that Unicode considers whitespace,
+including the ɴ\-ʙʀ .
+.IX Xref "whitespace characters characters, whitespace"
+.IP word 4
+.IX Item "word"
+In normal “computerese�, the piece of data of the size most
+efficiently handled by your computer, typically 32 bits or so, give or take a
+few powers of 2. In Perl culture, it more often refers to an alphanumeric
+\&\fBidentifier\fR (including underscores), or to a string of nonwhitespace
+\&\fBcharacters\fR bounded by whitespace or string boundaries.
+.IX Xref "words (term)"
+.IP "working directory" 4
+.IX Item "working directory"
+Your current \fBdirectory\fR, from
+which relative pathnames are interpreted by the \fBoperating system\fR. The
+operating system knows your current directory because you told it with a
+\&\f(CW\*(C`chdir\*(C'\fR, or because you started out in the place where your parent
+\&\fBprocess\fR was when you were born.
+.IX Xref "working directory directories, working"
+.IP wrapper 4
+.IX Item "wrapper"
+A program or subroutine that runs some other program or
+subroutine for you, modifying some of its input or output to better suit
+your purposes.
+.IX Xref "wrappers (term)"
+.IP WYSIWYG 4
+.IX Item "WYSIWYG"
+What You See Is What You Get. Usually used when something
+that appears on the screen matches how it will eventually look, like Perl’s
+\&\f(CW\*(C`format\*(C'\fR declarations. Also used to mean the opposite of magic because
+everything works exactly as it appears, as in the three\- argument form of
+\&\f(CW\*(C`open\*(C'\fR.
+.IX Xref "WYSIWYG acronym"
+.SS X
+.IX Subsection "X"
+.IP XS 4
+.IX Item "XS"
+An extraordinarily
+exported, expeditiously excellent, expressly eXternal Subroutine, executed
+in existing C or C++ or in an exciting extension language called
+(exasperatingly) XS.
+.IX Xref "XS (eXternal Subroutine) eXternal Subroutine (XS)"
+.IP XSUB 4
+.IX Item "XSUB"
+An external \fBsubroutine\fR defined in \fBXS\fR.
+.IX Xref "XSUB (term)"
+.SS Y
+.IX Subsection "Y"
+.IP yacc 4
+.IX Item "yacc"
+Yet Another Compiler Compiler. A parser generator without
+which Perl probably would not have existed. See the file \fIperly.y\fR in the
+Perl source distribution.
+.IX Xref "yacc acronym"
+.SS Z
+.IX Subsection "Z"
+.IP "zero width" 4
+.IX Item "zero width"
+A subpattern \fBassertion\fR matching the \fBnull
+string\fR between \fBcharacters\fR.
+.IX Xref "zero–width assertions subpatterns, zero–width assertions assertions (in regexes), zero–width"
+.IP zombie 4
+.IX Item "zombie"
+A process that has died (exited) but
+whose parent has not yet received proper notification of its demise by
+virtue of having called \f(CW\*(C`wait\*(C'\fR or \f(CW\*(C`waitpid\*(C'\fR. If you \f(CW\*(C`fork\*(C'\fR, you must
+clean up after your child processes when they exit; otherwise, the process
+table will fill up and your system administrator will Not Be Happy with
+you.
+.IX Xref "zombie processes processes, zombie"
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Based on the Glossary of \fIProgramming Perl\fR, Fourth Edition,
+by Tom Christiansen, brian d foy, Larry Wall, & Jon Orwant.
+Copyright (c) 2000, 1996, 1991, 2012 O'Reilly Media, Inc.
+This document may be distributed under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlgov.1 b/upstream/mageia-cauldron/man1/perlgov.1
new file mode 100644
index 00000000..d3b60ac9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlgov.1
@@ -0,0 +1,519 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGOV 1"
+.TH PERLGOV 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlgov \- Perl Rules of Governance
+.SH PREAMBLE
+.IX Header "PREAMBLE"
+We are forming a system of governance for development of the Perl programming
+language.
+.PP
+The scope of governance includes the language definition, its
+implementation, its test suite, its documentation, and the policies and
+procedures by which it is developed and maintained.
+.PP
+The system of governance includes definitions of the groups that will make
+decisions, the rules by which these groups are formed and changed, and the
+enumerated powers and constraints on the activities of these governing
+groups.
+.PP
+In forming a system of governance, we seek to achieve the following goals:
+.IP \(bu 4
+We want a system that is functional.  That means the governing groups may
+decide to undertake large changes, or they may decide to act conservatively,
+but they will act with intent and clear communication rather than fail to reach
+decisions when needed.
+.IP \(bu 4
+We want a system that is trusted. That means that a reasonable contributor to
+Perl might disagree with decisions made by the governing groups, but will
+accept that they were made in good faith in consultation with relevant
+communities outside the governing groups.
+.IP \(bu 4
+We want a system that is sustainable.  That means it has provisions to
+self-modify, including ways of adding new members to the governing groups, ways
+to survive members becoming inactive, and ways of amending the rules of
+governance themselves if needed.
+.IP \(bu 4
+We want a system that is transparent.  That means that it will prefer policies
+that manage ordinary matters in public, and it will prefer secrecy in a limited
+number of situations.
+.IP \(bu 4
+We want a system that is respectful.  That means that it will establish
+standards of civil discourse that allow for healthy disagreement but avoid
+rancor and hostility in the community for which it is responsible.
+.SH Mandate
+.IX Header "Mandate"
+Perl language governance shall work to:
+.IP \(bu 4
+Maintain the quality, stability, and continuity of the Perl language and
+interpreter
+.IP \(bu 4
+Guide the evolution of the Perl language and interpreter
+.IP \(bu 4
+Establish and oversee the policies, procedures, systems, and mechanisms that
+enable a community of contributors to the Perl language and interpreter
+.IP \(bu 4
+Encourage discussion and consensus among contributors as preferential to formal
+decision making by governance groups
+.IP \(bu 4
+Facilitate communication between contributors and external stakeholders in the
+broader Perl ecosystem
+.SH Definitions
+.IX Header "Definitions"
+This document describes three roles involved in governance:
+.IP """Core Team""" 4
+.IX Item """Core Team"""
+.PD 0
+.IP """Steering Council""" 4
+.IX Item """Steering Council"""
+.IP """Vote Administrator""" 4
+.IX Item """Vote Administrator"""
+.PD
+.PP
+A section on each follows.
+.SS "The Core Team"
+.IX Subsection "The Core Team"
+The Core Team are a group of trusted volunteers involved in the ongoing
+development of the Perl language and interpreter.  They are not required to be
+language developers or committers.
+.PP
+References to specific votes are explained in the "Rules for Voting" section.
+.PP
+\fIPowers\fR
+.IX Subsection "Powers"
+.PP
+In addition to their contributions to the Perl language, the Core Team sets
+the rules of Perl governance, decides who participates in what role in
+governance, and delegates substantial decision making power to the Steering
+Council.
+.PP
+Specifically:
+.IP \(bu 4
+They elect the Steering Council and have the power to remove Steering
+Council members.
+.IP \(bu 4
+In concert with the Steering Council, they manage Core Team membership.
+.IP \(bu 4
+In concert with the Steering Council, they have the power to modify the Perl
+Rules of Governance.
+.PP
+The Core Team do not have any authority over parts of the Perl ecosystem
+unrelated to developing and releasing the language itself.  These include, but
+are not limited to:
+.IP \(bu 4
+The Perl Foundation
+.IP \(bu 4
+CPAN administration and CPAN authors
+.IP \(bu 4
+perl.org, metacpan.org, and other community-maintained websites and services
+.IP \(bu 4
+Perl conferences and events, except those organized directly by the Core Team
+.IP \(bu 4
+Perl-related intellectual property legally owned by third-parties, except as
+allowed by applicable licenses or agreements
+.PP
+\fIMembership\fR
+.IX Subsection "Membership"
+.PP
+The initial Core Team members will be specified when this document is
+first ratified.
+.PP
+Any Core Team member may nominate someone to be added to the Core Team by
+sending the nomination to the Steering Council.  The Steering Council must
+approve or reject the nomination.  If approved, the Steering Council will
+organize a Membership Change Vote to ratify the addition.
+.PP
+Core Team members should demonstrate:
+.IP \(bu 4
+A solid track record of being constructive and helpful
+.IP \(bu 4
+Significant contributions to the project's goals, in any form
+.IP \(bu 4
+Willingness to dedicate some time to improving Perl
+.PP
+Contributions are not limited to code. Here is an incomplete list of areas
+where contributions may be considered for joining the Core Team:
+.IP \(bu 4
+Working on community management and outreach
+.IP \(bu 4
+Providing support on mailing lists, IRC, or other forums
+.IP \(bu 4
+Triaging tickets
+.IP \(bu 4
+Writing patches (code, docs, or tests)
+.IP \(bu 4
+Reviewing patches (code, docs, or tests)
+.IP \(bu 4
+Participating in design discussions
+.IP \(bu 4
+Providing expertise in a particular domain (security, i18n, etc.)
+.IP \(bu 4
+Managing Perl infrastructure (websites, CI, documentation, etc.)
+.IP \(bu 4
+Maintaining significant projects in the Perl ecosystem
+.IP \(bu 4
+Creating visual designs
+.PP
+Core Team membership acknowledges sustained and valuable efforts that align
+well with the philosophy and the goals of the Perl project.
+.PP
+Core Team members are expected to act as role models for the community and
+custodians of the project, on behalf of the community and all those who rely
+on Perl.
+.PP
+\fITerm\fR
+.IX Subsection "Term"
+.PP
+Core Team members serve until they are removed.
+.PP
+\fIRemoval\fR
+.IX Subsection "Removal"
+.PP
+Core Team Members may resign their position at any time.
+.PP
+In exceptional circumstances, it may be necessary to remove someone from the
+Core Team against their will, such as for flagrant or repeated violations of a
+Code of Conduct.  Any Core Team member may send a recall request to the
+Steering Council naming the individual to be removed.  The Steering Council
+must approve or reject the recall request.  If approved, the Steering Council
+will organize a Membership Change vote to ratify the removal.
+.PP
+If the removed member is also on the Steering Council, then they are removed
+from the Steering Council as well.
+.PP
+\fIInactivity\fR
+.IX Subsection "Inactivity"
+.PP
+Core Team members who have stopped contributing are encouraged to declare
+themselves "inactive". Inactive members do not nominate or vote.  Inactive
+members may declare themselves active at any time, except when a vote has been
+proposed and is not concluded.  Eligibility to nominate or vote will be
+determined by the Vote Administrator.
+.PP
+To record and honor their contributions, inactive Core Team members will
+continue to be listed alongside active members.
+.PP
+\fINo Confidence in the Steering Council\fR
+.IX Subsection "No Confidence in the Steering Council"
+.PP
+The Core Team may remove either a single Steering Council member or the entire
+Steering Council via a No Confidence Vote.
+.PP
+A No Confidence Vote is triggered when a Core Team member calls for one
+publicly on an appropriate project communication channel, and another Core
+Team member seconds the proposal.
+.PP
+If a No Confidence Vote removes all Steering Council members, the Vote
+Administrator of the No Confidence Vote will then administer an election
+to select a new Steering Council.
+.PP
+\fIAmending Perl Rules of Governance\fR
+.IX Subsection "Amending Perl Rules of Governance"
+.PP
+Any Core Team member may propose amending the Perl Rules of Governance by
+sending a proposal to the Steering Council.  The Steering Council must decide
+to approve or reject the proposal.  If approved, the Steering Council will
+organize an Amendment Vote.
+.PP
+\fIRules for Voting\fR
+.IX Subsection "Rules for Voting"
+.PP
+Membership Change, Amendment, and No Confidence Votes require 2/3 of
+participating votes from Core Team members to pass.
+.PP
+A Vote Administrator must be selected following the rules in the "Vote
+Administrator" section.
+.PP
+The vote occurs in two steps:
+.IP 1. 4
+The Vote Administrator describes the proposal being voted upon.  The Core Team
+then may discuss the matter in advance of voting.
+.IP 2. 4
+Active Core Team members vote in favor or against the proposal.  Voting is
+performed anonymously.
+.PP
+For a Membership Change Vote, each phase will last one week.  For Amendment and
+No Confidence Votes, each phase will last two weeks.
+.SS "The Steering Council"
+.IX Subsection "The Steering Council"
+The Steering Council is a 3\-person committee, elected by the Core
+Team.  Candidates are not required to be members of the Core Team.  Non-member
+candidates are added to the Core Team if elected as if by a Membership Change
+Vote.
+.PP
+References to specific elections are explained in the "Rules for Elections" section.
+.PP
+\fIPowers\fR
+.IX Subsection "Powers"
+.PP
+The Steering Council has broad authority to make decisions about the
+development of the Perl language, the interpreter, and all other components,
+systems and processes that result in new releases of the language interpreter.
+.PP
+For example, it can:
+.IP \(bu 4
+Manage the schedule and process for shipping new releases
+.IP \(bu 4
+Establish procedures for proposing, discussing and deciding upon changes to the
+language
+.IP \(bu 4
+Delegate power to individuals on or outside the Steering Council
+.PP
+Decisions of the Steering Council will be made by majority vote of non-vacant
+seats on the council.
+.PP
+The Steering Council should look for ways to use these powers as little as
+possible.  Instead of voting, it's better to seek consensus. Instead of ruling
+on individual cases, it's better to define standards and processes that apply
+to all cases.
+.PP
+As with the Core Team, the Steering Council does not have any authority over
+parts of the Perl ecosystem unrelated to developing and releasing the language
+itself.
+.PP
+The Steering Council does not have the power to modify the Perl Rules of
+Governance, except as provided in the section "Amending Perl Rules of
+Governance".
+.PP
+\fITerm\fR
+.IX Subsection "Term"
+.PP
+A new Steering Council will be chosen by a Term Election after each stable
+feature release (that is, change to \f(CW\*(C`PERL_REVISION\*(C'\fR or \f(CW\*(C`PERL_VERSION\*(C'\fR) or
+after two years, whichever comes first. The Term Election will be organized
+within two weeks of the triggering event. The council members will serve until
+the completion of the next Term Election unless they are removed.
+.PP
+\fIRemoval\fR
+.IX Subsection "Removal"
+.PP
+Steering Council members may resign their position at any time.
+.PP
+Whenever there are vacancies on the Steering Council, the council will
+organize a Special Election within one week after the vacancy occurs.  If the
+entire Steering Council is ever vacant, a Term Election will be held instead.
+.PP
+The Steering Council may defer the Special Election for up to twelve weeks.
+Their intent to do so must be publicly stated to the Core Team.  If any active
+Core Team member objects within one week, the Special Election must be
+organized within two weeks.  At any time, the Steering Council may choose to
+cancel the deferment and immediately commence organizing a Special Election.
+.PP
+If a Steering Council member is deceased, or drops out of touch and cannot be
+contacted for a month or longer, then the rest of the council may vote to
+declare their seat vacant.  If an absent member returns after such a
+declaration is made, they are not reinstated automatically, but may run in the
+Special Election to fill the vacancy.
+.PP
+Otherwise, Steering Council members may only be removed before the end of
+their term through a No Confidence Vote by the Core Team.
+.PP
+\fIRules for Elections\fR
+.IX Subsection "Rules for Elections"
+.PP
+Term and Special Election are ranked-choice votes to construct an ordered list
+of candidates to fill vacancies in the Steering Council.
+.PP
+A Vote Administrator must be selected following the rules in the "Vote
+Administrator" section.
+.PP
+Both Term and Special Elections occur in two stages:
+.IP 1. 4
+Candidates advertise their interest in serving. Candidates must be nominated by
+an active Core Team member. Self-nominations are allowed.  Nominated candidates
+may share a statement about their candidacy with the Core Team.
+.IP 2. 4
+If there are no more candidates than open seats, no vote is required.  The
+candidates will be declared to have won when the nomination period ends.
+.Sp
+Otherwise, active Core Team Members vote by ranking all candidates.  Voting is
+performed anonymously.  After voting is complete, candidates are ranked using
+the Condorcet Internet Voting Service's proportional representation mode.  If a
+tie occurs, it may be resolved by mutual agreement among the tied candidates,
+or else the tie will be resolved through random selection by the Vote
+Administrator.
+.PP
+Anyone voted off the Core Team is not eligible to be a candidate for Steering
+Council unless re-instated to the Core Team.
+.PP
+For a Term Election, each phase will last two weeks.  At the end of the second
+phase, the top three ranked candidates are elected as the new Steering Council.
+.PP
+For a Special Election, each phase will last one week.  At the end of the
+second phase, vacancies are filled from the ordered list of candidates until
+no vacancies remain.
+.PP
+The election of the first Steering Council will be a Term Election.  Ricardo
+Signes will be the Vote Administrator for the initial Term Election unless he
+is a candidate, in which case he will select a non-candidate administrator to
+replace him.
+.SS "The Vote Administrator"
+.IX Subsection "The Vote Administrator"
+Every election or vote requires a Vote Administrator who manages
+communication, collection of secret ballots, and all other necessary
+activities to complete the voting process.
+.PP
+Unless otherwise specified, the Steering Council selects the Vote
+Administrator.
+.PP
+A Vote Administrator must not be a member of the Steering Council nor a
+candidate or subject of the vote.  A Vote Administrator may be a member of the
+Core Team and, if so, may cast a vote while also serving as administrator.  If
+the Vote Administrator becomes a candidate during an election vote, they will
+appoint a non-candidate replacement.
+.PP
+If the entire Steering Council is vacant or is the subject of a No Confidence
+Vote, then the Core Team will select a Vote Administrator by consensus.  If
+consensus cannot be reached within one week, the President of The Perl
+Foundation will select a Vote Administrator.
+.SH "Steering Council and Core Team Members"
+.IX Header "Steering Council and Core Team Members"
+The list below names the members of the Steering Council and Core Team
+responsible for creating the release of perl with which this document shipped.
+.PP
+Remember, though that if you're reading the copy of this document that was
+installed with perl, it's very likely out of date.  Because every new stable
+feature release triggers an election, you're better off looking at the most
+up to date copy of this
+document <https://github.com/Perl/perl5/blob/blead/pod/perlgov.pod>, in the
+\&\fIblead\fR branch of Perl's git repository.  Because it's git, you can also see
+how the membership has changed over time.
+.SH "Steering Council Members"
+.IX Header "Steering Council Members"
+.IP \(bu 4
+Paul Evans
+.IP \(bu 4
+Philippe Bruhat
+.IP \(bu 4
+Ricardo Signes
+.SH "Core Team Members"
+.IX Header "Core Team Members"
+The current members of the Perl Core Team are:
+.SS "Active Members"
+.IX Subsection "Active Members"
+.IP "Chad Granum <exodist7@gmail.com>" 4
+.IX Item "Chad Granum <exodist7@gmail.com>"
+.PD 0
+.IP "Chris 'BinGOs' Williams <chris@bingosnet.co.uk>" 4
+.IX Item "Chris 'BinGOs' Williams <chris@bingosnet.co.uk>"
+.IP "Craig Berry <craigberry@mac.com>" 4
+.IX Item "Craig Berry <craigberry@mac.com>"
+.IP "Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>" 4
+.IX Item "Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>"
+.IP "David Mitchell <davem@iabyn.com>" 4
+.IX Item "David Mitchell <davem@iabyn.com>"
+.IP "Graham Knop <haarg@haarg.org>" 4
+.IX Item "Graham Knop <haarg@haarg.org>"
+.IP "H. Merijn Brand <perl5@tux.freedom.nl>" 4
+.IX Item "H. Merijn Brand <perl5@tux.freedom.nl>"
+.IP "Hugo van der Sanden <hv@crypt.org>" 4
+.IX Item "Hugo van der Sanden <hv@crypt.org>"
+.IP "James E Keenan <jkeenan@cpan.org>" 4
+.IX Item "James E Keenan <jkeenan@cpan.org>"
+.IP "Karen Etheridge <ether@cpan.org>" 4
+.IX Item "Karen Etheridge <ether@cpan.org>"
+.IP "Karl Williamson <khw@cpan.org>" 4
+.IX Item "Karl Williamson <khw@cpan.org>"
+.IP "Leon Timmermans <fawaka@gmail.com>" 4
+.IX Item "Leon Timmermans <fawaka@gmail.com>"
+.IP "Matthew Horsfall <wolfsage@gmail.com>" 4
+.IX Item "Matthew Horsfall <wolfsage@gmail.com>"
+.IP "Max Maischein <cpan@corion.net>" 4
+.IX Item "Max Maischein <cpan@corion.net>"
+.IP "Neil Bowers <neilb@neilb.org>" 4
+.IX Item "Neil Bowers <neilb@neilb.org>"
+.IP "Nicholas Clark <nick@ccl4.org>" 4
+.IX Item "Nicholas Clark <nick@ccl4.org>"
+.IP "Nicolas R <atoomic@cpan.org>" 4
+.IX Item "Nicolas R <atoomic@cpan.org>"
+.IP "Paul ""LeoNerd"" Evans <leonerd@leonerd.org.uk>" 4
+.IX Item "Paul ""LeoNerd"" Evans <leonerd@leonerd.org.uk>"
+.IP "Philippe ""BooK"" Bruhat <book@cpan.org>" 4
+.IX Item "Philippe ""BooK"" Bruhat <book@cpan.org>"
+.IP "Ricardo Signes <rjbs@semiotic.systems>" 4
+.IX Item "Ricardo Signes <rjbs@semiotic.systems>"
+.IP "Steve Hay <steve.m.hay@googlemail.com>" 4
+.IX Item "Steve Hay <steve.m.hay@googlemail.com>"
+.IP "Stuart Mackintosh <stuart@perlfoundation.org>" 4
+.IX Item "Stuart Mackintosh <stuart@perlfoundation.org>"
+.IP "Todd Rinaldo <toddr@cpanel.net>" 4
+.IX Item "Todd Rinaldo <toddr@cpanel.net>"
+.IP "Tony Cook <tony@develop\-help.com>" 4
+.IX Item "Tony Cook <tony@develop-help.com>"
+.IP "Yves Orton <demerphq@gmail.com>" 4
+.IX Item "Yves Orton <demerphq@gmail.com>"
+.PD
+.SS "Inactive Members"
+.IX Subsection "Inactive Members"
+.IP "Abhijit Menon-Sen <ams@toroid.org>" 4
+.IX Item "Abhijit Menon-Sen <ams@toroid.org>"
+.PD 0
+.IP "Andy Dougherty <doughera@lafayette.edu>" 4
+.IX Item "Andy Dougherty <doughera@lafayette.edu>"
+.IP "David Golden <xdg@xdg.me>" 4
+.IX Item "David Golden <xdg@xdg.me>"
+.IP "Jan Dubois <jan@jandubois.com>" 4
+.IX Item "Jan Dubois <jan@jandubois.com>"
+.IP "Jason McIntosh <jmac@jmac.org>" 4
+.IX Item "Jason McIntosh <jmac@jmac.org>"
+.IP "Jesse Vincent <jesse@fsck.com>" 4
+.IX Item "Jesse Vincent <jesse@fsck.com>"
diff --git a/upstream/mageia-cauldron/man1/perlgpl.1 b/upstream/mageia-cauldron/man1/perlgpl.1
new file mode 100644
index 00000000..b63bec39
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlgpl.1
@@ -0,0 +1,348 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGPL 1"
+.TH PERLGPL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlgpl \- the GNU General Public License, version 1
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\& You can refer to this document in Pod via "L<perlgpl>"
+\& Or you can see this document by entering "perldoc perlgpl"
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl is free software; you can redistribute it and/or modify
+it under the terms of either:
+.PP
+.Vb 3
+\&        a) the GNU General Public License as published by the Free
+\&        Software Foundation; either version 1, or (at your option) any
+\&        later version, or
+\&
+\&        b) the "Artistic License" which comes with this Kit.
+.Ve
+.PP
+This is the \fB"GNU General Public License, version 1"\fR.
+It's here so that modules, programs, etc., that want to declare
+this as their distribution license can link to it.
+.PP
+For the Perl Artistic License, see perlartistic.
+.SH "GNU GENERAL PUBLIC LICENSE"
+.IX Header "GNU GENERAL PUBLIC LICENSE"
+.Vb 2
+\&                    GNU GENERAL PUBLIC LICENSE
+\&                     Version 1, February 1989
+\&
+\&  Copyright (C) 1989 Free Software Foundation, Inc.
+\&                51 Franklin St, Fifth Floor, Boston, MA  02110\-1301  USA
+\&
+\&  Everyone is permitted to copy and distribute verbatim copies
+\&  of this license document, but changing it is not allowed.
+\&
+\&                            Preamble
+\&
+\&   The license agreements of most software companies try to keep users
+\& at the mercy of those companies.  By contrast, our General Public
+\& License is intended to guarantee your freedom to share and change free
+\& software\-\-to make sure the software is free for all its users.  The
+\& General Public License applies to the Free Software Foundation\*(Aqs
+\& software and to any other program whose authors commit to using it.
+\& You can use it for your programs, too.
+\&
+\&   When we speak of free software, we are referring to freedom, not
+\& price.  Specifically, the General Public License is designed to make
+\& sure that you have the freedom to give away or sell copies of free
+\& software, that you receive source code or can get it if you want it,
+\& that you can change the software or use pieces of it in new free
+\& programs; and that you know you can do these things.
+\&
+\&   To protect your rights, we need to make restrictions that forbid
+\& anyone to deny you these rights or to ask you to surrender the rights.
+\& These restrictions translate to certain responsibilities for you if you
+\& distribute copies of the software, or if you modify it.
+\&
+\&   For example, if you distribute copies of a such a program, whether
+\& gratis or for a fee, you must give the recipients all the rights that
+\& you have.  You must make sure that they, too, receive or can get the
+\& source code.  And you must tell them their rights.
+\&
+\&   We protect your rights with two steps: (1) copyright the software,
+\& and (2) offer you this license which gives you legal permission to
+\& copy, distribute and/or modify the software.
+\&
+\&   Also, for each author\*(Aqs protection and ours, we want to make certain
+\& that everyone understands that there is no warranty for this free
+\& software.  If the software is modified by someone else and passed on,
+\& we want its recipients to know that what they have is not the original,
+\& so that any problems introduced by others will not reflect on the
+\& original authors\*(Aq reputations.
+\&
+\&   The precise terms and conditions for copying, distribution and
+\& modification follow.
+\&
+\&                    GNU GENERAL PUBLIC LICENSE
+\&    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+\&
+\&   0. This License Agreement applies to any program or other work which
+\& contains a notice placed by the copyright holder saying it may be
+\& distributed under the terms of this General Public License.  The
+\& "Program", below, refers to any such program or work, and a "work based
+\& on the Program" means either the Program or any work containing the
+\& Program or a portion of it, either verbatim or with modifications.
+\& Each licensee is addressed as "you".
+\&
+\&   1. You may copy and distribute verbatim copies of the Program\*(Aqs
+\& source code as you receive it, in any medium, provided that you
+\& conspicuously and appropriately publish on each copy an appropriate
+\& copyright notice and disclaimer of warranty; keep intact all the
+\& notices that refer to this General Public License and to the absence of
+\& any warranty; and give any other recipients of the Program a copy of
+\& this General Public License along with the Program.  You may charge a
+\& fee for the physical act of transferring a copy.
+\&
+\&   2. You may modify your copy or copies of the Program or any portion
+\& of it, and copy and distribute such modifications under the terms of
+\& Paragraph 1 above, provided that you also do the following:
+\&
+\&     a) cause the modified files to carry prominent notices stating that
+\&     you changed the files and the date of any change; and
+\&
+\&     b) cause the whole of any work that you distribute or publish, that
+\&     in whole or in part contains the Program or any part thereof,
+\&     either with or without modifications, to be licensed at no charge
+\&     to all third parties under the terms of this General Public License
+\&     (except that you may choose to grant warranty protection to some or
+\&     all third parties, at your option).
+\&
+\&     c) If the modified program normally reads commands interactively
+\&     when run, you must cause it, when started running for such
+\&     interactive use in the simplest and most usual way, to print or
+\&     display an announcement including an appropriate copyright notice
+\&     and a notice that there is no warranty (or else, saying that you
+\&     provide a warranty) and that users may redistribute the program
+\&     under these conditions, and telling the user how to view a copy of
+\&     this General Public License.
+\&
+\&     d) You may charge a fee for the physical act of transferring a
+\&     copy, and you may at your option offer warranty protection in
+\&     exchange for a fee.
+\&
+\& Mere aggregation of another independent work with the Program (or its
+\& derivative) on a volume of a storage or distribution medium does not
+\& bring the other work under the scope of these terms.
+\&
+\&   3. You may copy and distribute the Program (or a portion or
+\& derivative of it, under Paragraph 2) in object code or executable form
+\& under the terms of Paragraphs 1 and 2 above provided that you also do
+\& one of the following:
+\&
+\&     a) accompany it with the complete corresponding machine\-readable
+\&     source code, which must be distributed under the terms of
+\&     Paragraphs 1 and 2 above; or,
+\&
+\&     b) accompany it with a written offer, valid for at least three
+\&     years, to give any third party free (except for a nominal charge
+\&     for the cost of distribution) a complete machine\-readable copy of
+\&     the corresponding source code, to be distributed under the terms of
+\&     Paragraphs 1 and 2 above; or,
+\&
+\&     c) accompany it with the information you received as to where the
+\&     corresponding source code may be obtained.  (This alternative is
+\&     allowed only for noncommercial distribution and only if you
+\&     received the program in object code or executable form alone.)
+\&
+\& Source code for a work means the preferred form of the work for making
+\& modifications to it.  For an executable file, complete source code
+\& means all the source code for all modules it contains; but, as a
+\& special exception, it need not include source code for modules which
+\& are standard libraries that accompany the operating system on which the
+\& executable file runs, or for standard header files or definitions files
+\& that accompany that operating system.
+\&
+\&   4. You may not copy, modify, sublicense, distribute or transfer the
+\& Program except as expressly provided under this General Public License.
+\& Any attempt otherwise to copy, modify, sublicense, distribute or
+\& transfer the Program is void, and will automatically terminate your
+\& rights to use the Program under this License.  However, parties who
+\& have received copies, or rights to use copies, from you under this
+\& General Public License will not have their licenses terminated so long
+\& as such parties remain in full compliance.
+\&
+\&   5. By copying, distributing or modifying the Program (or any work
+\& based on the Program) you indicate your acceptance of this license to
+\& do so, and all its terms and conditions.
+\&
+\&   6. Each time you redistribute the Program (or any work based on the
+\& Program), the recipient automatically receives a license from the
+\& original licensor to copy, distribute or modify the Program subject to
+\& these terms and conditions.  You may not impose any further
+\& restrictions on the recipients\*(Aq exercise of the rights granted herein.
+\&
+\&   7. The Free Software Foundation may publish revised and/or new
+\& versions of the General Public License from time to time.  Such new
+\& versions will be similar in spirit to the present version, but may
+\& differ in detail to address new problems or concerns.
+\&
+\& Each version is given a distinguishing version number.  If the Program
+\& specifies a version number of the license which applies to it and "any
+\& later version", you have the option of following the terms and
+\& conditions either of that version or of any later version published by
+\& the Free Software Foundation.  If the Program does not specify a
+\& version number of the license, you may choose any version ever
+\& published by the Free Software Foundation.
+\&
+\&   8. If you wish to incorporate parts of the Program into other free
+\& programs whose distribution conditions are different, write to the
+\& author to ask for permission.  For software which is copyrighted by the
+\& Free Software Foundation, write to the Free Software Foundation; we
+\& sometimes make exceptions for this.  Our decision will be guided by the
+\& two goals of preserving the free status of all derivatives of our free
+\& software and of promoting the sharing and reuse of software generally.
+\&
+\&                            NO WARRANTY
+\&
+\&   9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+\& WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+\& EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+\& OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
+\& EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+\& WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+\& THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
+\& WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+\& ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+\&
+\&   10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+\& WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+\& AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
+\& FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+\& CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+\& PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+\& RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+\& FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
+\& SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+\& DAMAGES.
+\&
+\&                     END OF TERMS AND CONDITIONS
+\&
+\&        Appendix: How to Apply These Terms to Your New Programs
+\&
+\&   If you develop a new program, and you want it to be of the greatest
+\& possible use to humanity, the best way to achieve this is to make it
+\& free software which everyone can redistribute and change under these
+\& terms.
+\&
+\&   To do so, attach the following notices to the program.  It is safest
+\& to attach them to the start of each source file to most effectively
+\& convey the exclusion of warranty; and each file should have at least
+\& the "copyright" line and a pointer to where the full notice is found.
+\&
+\&     <one line to give the program\*(Aqs name and a brief idea of what it
+\&     does.>
+\&     Copyright (C) 19yy  <name of author>
+\&
+\&     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 1, or (at
+\&     your option) any later version.
+\&
+\&     This program is distributed in the hope that it will be useful,
+\&     but WITHOUT ANY WARRANTY; without even the implied warranty of
+\&     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+\&     GNU General Public License for more details.
+\&
+\&     You should have received a copy of the GNU General Public License
+\&     along with this program; if not, write to the Free Software
+\&     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA
+\&     02110\-1301 USA
+\&
+\&
+\& Also add information on how to contact you by electronic and paper
+\& mail.
+\&
+\& If the program is interactive, make it output a short notice like this
+\& when it starts in an interactive mode:
+\&
+\&     Gnomovision version 69, Copyright (C) 19xx name of author
+\&     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
+\&     \*(Aqshow w\*(Aq.  This is free software, and you are welcome to
+\&     redistribute it under certain conditions; type \*(Aqshow c\*(Aq for
+\&     details.
+\&
+\& The hypothetical commands \*(Aqshow w\*(Aq and \*(Aqshow c\*(Aq should show the
+\& appropriate parts of the General Public License.  Of course, the
+\& commands you use may be called something other than \*(Aqshow w\*(Aq and \*(Aqshow
+\& c\*(Aq; they could even be mouse\-clicks or menu items\-\-whatever suits your
+\& program.
+\&
+\& You should also get your employer (if you work as a programmer) or your
+\& school, if any, to sign a "copyright disclaimer" for the program, if
+\& necessary.  Here a sample; alter the names:
+\&
+\&   Yoyodyne, Inc., hereby disclaims all copyright interest in the
+\&   program \*(AqGnomovision\*(Aq (a program to direct compilers to make passes
+\&   at assemblers) written by James Hacker.
+\&
+\&   <signature of Ty Coon>, 1 April 1989
+\&   Ty Coon, President of Vice
+\&
+\& That\*(Aqs all there is to it!
+.Ve
diff --git a/upstream/mageia-cauldron/man1/perlguts.1 b/upstream/mageia-cauldron/man1/perlguts.1
new file mode 100644
index 00000000..567ef540
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlguts.1
@@ -0,0 +1,4465 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGUTS 1"
+.TH PERLGUTS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlguts \- Introduction to the Perl API
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document attempts to describe how to use the Perl API, as well as
+to provide some info on the basic workings of the Perl core.  It is far
+from complete and probably contains many errors.  Please refer any
+questions or comments to the author below.
+.SH Variables
+.IX Header "Variables"
+.SS Datatypes
+.IX Subsection "Datatypes"
+Perl has three typedefs that handle Perl's three main data types:
+.PP
+.Vb 3
+\&    SV  Scalar Value
+\&    AV  Array Value
+\&    HV  Hash Value
+.Ve
+.PP
+Each typedef has specific routines that manipulate the various data types.
+.SS "What is an ""IV""?"
+.IX Subsection "What is an ""IV""?"
+Perl uses a special typedef IV which is a simple signed integer type that is
+guaranteed to be large enough to hold a pointer (as well as an integer).
+Additionally, there is the UV, which is simply an unsigned IV.
+.PP
+Perl also uses several special typedefs to declare variables to hold
+integers of (at least) a given size.
+Use I8, I16, I32, and I64 to declare a signed integer variable which has
+at least as many bits as the number in its name.  These all evaluate to
+the native C type that is closest to the given number of bits, but no
+smaller than that number.  For example, on many platforms, a \f(CW\*(C`short\*(C'\fR is
+16 bits long, and if so, I16 will evaluate to a \f(CW\*(C`short\*(C'\fR.  But on
+platforms where a \f(CW\*(C`short\*(C'\fR isn't exactly 16 bits, Perl will use the
+smallest type that contains 16 bits or more.
+.PP
+U8, U16, U32, and U64 are to declare the corresponding unsigned integer
+types.
+.PP
+If the platform doesn't support 64\-bit integers, both I64 and U64 will
+be undefined.  Use IV and UV to declare the largest practicable, and
+\&\f(CW\*(C`"WIDEST_UTYPE" in perlapi\*(C'\fR for the absolute maximum unsigned, but which
+may not be usable in all circumstances.
+.PP
+A numeric constant can be specified with "\f(CW\*(C`INT16_C\*(C'\fR" in perlapi,
+"\f(CW\*(C`UINTMAX_C\*(C'\fR" in perlapi, and similar.
+.SS "Working with SVs"
+.IX Subsection "Working with SVs"
+An SV can be created and loaded with one command.  There are five types of
+values that can be loaded: an integer value (IV), an unsigned integer
+value (UV), a double (NV), a string (PV), and another scalar (SV).
+("PV" stands for "Pointer Value".  You might think that it is misnamed
+because it is described as pointing only to strings.  However, it is
+possible to have it point to other things.  For example, it could point
+to an array of UVs.  But,
+using it for non-strings requires care, as the underlying assumption of
+much of the internals is that PVs are just for strings.  Often, for
+example, a trailing \f(CW\*(C`NUL\*(C'\fR is tacked on automatically.  The non-string use
+is documented only in this paragraph.)
+.PP
+The seven routines are:
+.PP
+.Vb 7
+\&    SV*  newSViv(IV);
+\&    SV*  newSVuv(UV);
+\&    SV*  newSVnv(double);
+\&    SV*  newSVpv(const char*, STRLEN);
+\&    SV*  newSVpvn(const char*, STRLEN);
+\&    SV*  newSVpvf(const char*, ...);
+\&    SV*  newSVsv(SV*);
+.Ve
+.PP
+\&\f(CW\*(C`STRLEN\*(C'\fR is an integer type (\f(CW\*(C`Size_t\*(C'\fR, usually defined as \f(CW\*(C`size_t\*(C'\fR in
+\&\fIconfig.h\fR) guaranteed to be large enough to represent the size of
+any string that perl can handle.
+.PP
+In the unlikely case of a SV requiring more complex initialization, you
+can create an empty SV with newSV(len).  If \f(CW\*(C`len\*(C'\fR is 0 an empty SV of
+type NULL is returned, else an SV of type PV is returned with len + 1 (for
+the \f(CW\*(C`NUL\*(C'\fR) bytes of storage allocated, accessible via SvPVX.  In both cases
+the SV has the undef value.
+.PP
+.Vb 3
+\&    SV *sv = newSV(0);   /* no storage allocated  */
+\&    SV *sv = newSV(10);  /* 10 (+1) bytes of uninitialised storage
+\&                          * allocated */
+.Ve
+.PP
+To change the value of an \fIalready-existing\fR SV, there are eight routines:
+.PP
+.Vb 9
+\&    void  sv_setiv(SV*, IV);
+\&    void  sv_setuv(SV*, UV);
+\&    void  sv_setnv(SV*, double);
+\&    void  sv_setpv(SV*, const char*);
+\&    void  sv_setpvn(SV*, const char*, STRLEN)
+\&    void  sv_setpvf(SV*, const char*, ...);
+\&    void  sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
+\&                                        SV **, Size_t, bool *);
+\&    void  sv_setsv(SV*, SV*);
+.Ve
+.PP
+Notice that you can choose to specify the length of the string to be
+assigned by using \f(CW\*(C`sv_setpvn\*(C'\fR, \f(CW\*(C`newSVpvn\*(C'\fR, or \f(CW\*(C`newSVpv\*(C'\fR, or you may
+allow Perl to calculate the length by using \f(CW\*(C`sv_setpv\*(C'\fR or by specifying
+0 as the second argument to \f(CW\*(C`newSVpv\*(C'\fR.  Be warned, though, that Perl will
+determine the string's length by using \f(CW\*(C`strlen\*(C'\fR, which depends on the
+string terminating with a \f(CW\*(C`NUL\*(C'\fR character, and not otherwise containing
+NULs.
+.PP
+The arguments of \f(CW\*(C`sv_setpvf\*(C'\fR are processed like \f(CW\*(C`sprintf\*(C'\fR, and the
+formatted output becomes the value.
+.PP
+\&\f(CW\*(C`sv_vsetpvfn\*(C'\fR is an analogue of \f(CW\*(C`vsprintf\*(C'\fR, but it allows you to specify
+either a pointer to a variable argument list or the address and length of
+an array of SVs.  The last argument points to a boolean; on return, if that
+boolean is true, then locale-specific information has been used to format
+the string, and the string's contents are therefore untrustworthy (see
+perlsec).  This pointer may be NULL if that information is not
+important.  Note that this function requires you to specify the length of
+the format.
+.PP
+The \f(CW\*(C`sv_set*()\*(C'\fR functions are not generic enough to operate on values
+that have "magic".  See "Magic Virtual Tables" later in this document.
+.PP
+All SVs that contain strings should be terminated with a \f(CW\*(C`NUL\*(C'\fR character.
+If it is not \f(CW\*(C`NUL\*(C'\fR\-terminated there is a risk of
+core dumps and corruptions from code which passes the string to C
+functions or system calls which expect a \f(CW\*(C`NUL\*(C'\fR\-terminated string.
+Perl's own functions typically add a trailing \f(CW\*(C`NUL\*(C'\fR for this reason.
+Nevertheless, you should be very careful when you pass a string stored
+in an SV to a C function or system call.
+.PP
+To access the actual value that an SV points to, Perl's API exposes
+several macros that coerce the actual scalar type into an IV, UV, double,
+or string:
+.IP \(bu 4
+\&\f(CWSvIV(SV*)\fR (\f(CW\*(C`IV\*(C'\fR) and \f(CWSvUV(SV*)\fR (\f(CW\*(C`UV\*(C'\fR)
+.IP \(bu 4
+\&\f(CWSvNV(SV*)\fR (\f(CW\*(C`double\*(C'\fR)
+.IP \(bu 4
+Strings are a bit complicated:
+.RS 4
+.IP \(bu 4
+Byte string: \f(CW\*(C`SvPVbyte(SV*, STRLEN len)\*(C'\fR or \f(CWSvPVbyte_nolen(SV*)\fR
+.Sp
+If the Perl string is \f(CW"\exff\exff"\fR, then this returns a 2\-byte \f(CW\*(C`char*\*(C'\fR.
+.Sp
+This is suitable for Perl strings that represent bytes.
+.IP \(bu 4
+UTF\-8 string: \f(CW\*(C`SvPVutf8(SV*, STRLEN len)\*(C'\fR or \f(CWSvPVutf8_nolen(SV*)\fR
+.Sp
+If the Perl string is \f(CW"\exff\exff"\fR, then this returns a 4\-byte \f(CW\*(C`char*\*(C'\fR.
+.Sp
+This is suitable for Perl strings that represent characters.
+.Sp
+\&\fBCAVEAT\fR: That \f(CW\*(C`char*\*(C'\fR will be encoded via Perl's internal UTF\-8 variant,
+which means that if the SV contains non-Unicode code points (e.g.,
+0x110000), then the result may contain extensions over valid UTF\-8.
+See "is_strict_utf8_string" in perlapi for some methods Perl gives
+you to check the UTF\-8 validity of these macros' returns.
+.IP \(bu 4
+You can also use \f(CW\*(C`SvPV(SV*, STRLEN len)\*(C'\fR or \f(CWSvPV_nolen(SV*)\fR
+to fetch the SV's raw internal buffer. This is tricky, though; if your Perl
+string
+is \f(CW"\exff\exff"\fR, then depending on the SV's internal encoding you might get
+back a 2\-byte \fBOR\fR a 4\-byte \f(CW\*(C`char*\*(C'\fR.
+Moreover, if it's the 4\-byte string, that could come from either Perl
+\&\f(CW"\exff\exff"\fR stored UTF\-8 encoded, or Perl \f(CW"\exc3\exbf\exc3\exbf"\fR stored
+as raw octets. To differentiate between these you \fBMUST\fR look up the
+SV's UTF8 bit (cf. \f(CW\*(C`SvUTF8\*(C'\fR) to know whether the source Perl string
+is 2 characters (\f(CW\*(C`SvUTF8\*(C'\fR would be on) or 4 characters (\f(CW\*(C`SvUTF8\*(C'\fR would be
+off).
+.Sp
+\&\fBIMPORTANT:\fR Use of \f(CW\*(C`SvPV\*(C'\fR, \f(CW\*(C`SvPV_nolen\*(C'\fR, or
+similarly-named macros \fIwithout\fR looking up the SV's UTF8 bit is
+almost certainly a bug if non-ASCII input is allowed.
+.Sp
+When the UTF8 bit is on, the same \fBCAVEAT\fR about UTF\-8 validity applies
+here as for \f(CW\*(C`SvPVutf8\*(C'\fR.
+.RE
+.RS 4
+.Sp
+(See "How do I pass a Perl string to a C library?" for more details.)
+.Sp
+In \f(CW\*(C`SvPVbyte\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR, and \f(CW\*(C`SvPV\*(C'\fR, the length of the \f(CW\*(C`char*\*(C'\fR returned
+is placed into the
+variable \f(CW\*(C`len\*(C'\fR (these are macros, so you do \fInot\fR use \f(CW&len\fR). If you do
+not care what the length of the data is, use \f(CW\*(C`SvPVbyte_nolen\*(C'\fR,
+\&\f(CW\*(C`SvPVutf8_nolen\*(C'\fR, or \f(CW\*(C`SvPV_nolen\*(C'\fR instead.
+The global variable \f(CW\*(C`PL_na\*(C'\fR can also be given to
+\&\f(CW\*(C`SvPVbyte\*(C'\fR/\f(CW\*(C`SvPVutf8\*(C'\fR/\f(CW\*(C`SvPV\*(C'\fR
+in this case.  But that can be quite inefficient because \f(CW\*(C`PL_na\*(C'\fR must
+be accessed in thread-local storage in threaded Perl.  In any case, remember
+that Perl allows arbitrary strings of data that may both contain NULs and
+might not be terminated by a \f(CW\*(C`NUL\*(C'\fR.
+.Sp
+Also remember that C doesn't allow you to safely say \f(CW\*(C`foo(SvPVbyte(s, len),
+len);\*(C'\fR.  It might work with your
+compiler, but it won't work for everyone.
+Break this sort of statement up into separate assignments:
+.Sp
+.Vb 5
+\&    SV *s;
+\&    STRLEN len;
+\&    char *ptr;
+\&    ptr = SvPVbyte(s, len);
+\&    foo(ptr, len);
+.Ve
+.RE
+.PP
+If you want to know if the scalar value is TRUE, you can use:
+.PP
+.Vb 1
+\&    SvTRUE(SV*)
+.Ve
+.PP
+Although Perl will automatically grow strings for you, if you need to force
+Perl to allocate more memory for your SV, you can use the macro
+.PP
+.Vb 1
+\&    SvGROW(SV*, STRLEN newlen)
+.Ve
+.PP
+which will determine if more memory needs to be allocated.  If so, it will
+call the function \f(CW\*(C`sv_grow\*(C'\fR.  Note that \f(CW\*(C`SvGROW\*(C'\fR can only increase, not
+decrease, the allocated memory of an SV and that it does not automatically
+add space for the trailing \f(CW\*(C`NUL\*(C'\fR byte (perl's own string functions typically do
+\&\f(CW\*(C`SvGROW(sv, len + 1)\*(C'\fR).
+.PP
+If you want to write to an existing SV's buffer and set its value to a
+string, use \fBSvPVbyte_force()\fR or one of its variants to force the SV to be
+a PV.  This will remove any of various types of non-stringness from
+the SV while preserving the content of the SV in the PV.  This can be
+used, for example, to append data from an API function to a buffer
+without extra copying:
+.PP
+.Vb 11
+\&    (void)SvPVbyte_force(sv, len);
+\&    s = SvGROW(sv, len + needlen + 1);
+\&    /* something that modifies up to needlen bytes at s+len, but
+\&       modifies newlen bytes
+\&         eg. newlen = read(fd, s + len, needlen);
+\&       ignoring errors for these examples
+\&     */
+\&    s[len + newlen] = \*(Aq\e0\*(Aq;
+\&    SvCUR_set(sv, len + newlen);
+\&    SvUTF8_off(sv);
+\&    SvSETMAGIC(sv);
+.Ve
+.PP
+If you already have the data in memory or if you want to keep your
+code simple, you can use one of the sv_cat*() variants, such as
+\&\fBsv_catpvn()\fR.  If you want to insert anywhere in the string you can use
+\&\fBsv_insert()\fR or \fBsv_insert_flags()\fR.
+.PP
+If you don't need the existing content of the SV, you can avoid some
+copying with:
+.PP
+.Vb 10
+\&    SvPVCLEAR(sv);
+\&    s = SvGROW(sv, needlen + 1);
+\&    /* something that modifies up to needlen bytes at s, but modifies
+\&       newlen bytes
+\&         eg. newlen = read(fd, s, needlen);
+\&     */
+\&    s[newlen] = \*(Aq\e0\*(Aq;
+\&    SvCUR_set(sv, newlen);
+\&    SvPOK_only(sv); /* also clears SVf_UTF8 */
+\&    SvSETMAGIC(sv);
+.Ve
+.PP
+Again, if you already have the data in memory or want to avoid the
+complexity of the above, you can use \fBsv_setpvn()\fR.
+.PP
+If you have a buffer allocated with \fBNewx()\fR and want to set that as the
+SV's value, you can use \fBsv_usepvn_flags()\fR.  That has some requirements
+if you want to avoid perl re-allocating the buffer to fit the trailing
+NUL:
+.PP
+.Vb 5
+\&   Newx(buf, somesize+1, char);
+\&   /* ... fill in buf ... */
+\&   buf[somesize] = \*(Aq\e0\*(Aq;
+\&   sv_usepvn_flags(sv, buf, somesize, SV_SMAGIC | SV_HAS_TRAILING_NUL);
+\&   /* buf now belongs to perl, don\*(Aqt release it */
+.Ve
+.PP
+If you have an SV and want to know what kind of data Perl thinks is stored
+in it, you can use the following macros to check the type of SV you have.
+.PP
+.Vb 3
+\&    SvIOK(SV*)
+\&    SvNOK(SV*)
+\&    SvPOK(SV*)
+.Ve
+.PP
+Be aware that retrieving the numeric value of an SV can set IOK or NOK
+on that SV, even when the SV started as a string.  Prior to Perl
+5.36.0 retrieving the string value of an integer could set POK, but
+this can no longer occur.  From 5.36.0 this can be used to distinguish
+the original representation of an SV and is intended to make life
+simpler for serializers:
+.PP
+.Vb 10
+\&    /* references handled elsewhere */
+\&    if (SvIsBOOL(sv)) {
+\&        /* originally boolean */
+\&        ...
+\&    }
+\&    else if (SvPOK(sv)) {
+\&        /* originally a string */
+\&        ...
+\&    }
+\&    else if (SvNIOK(sv)) {
+\&        /* originally numeric */
+\&        ...
+\&    }
+\&    else {
+\&        /* something special or undef */
+\&    }
+.Ve
+.PP
+You can get and set the current length of the string stored in an SV with
+the following macros:
+.PP
+.Vb 2
+\&    SvCUR(SV*)
+\&    SvCUR_set(SV*, I32 val)
+.Ve
+.PP
+You can also get a pointer to the end of the string stored in the SV
+with the macro:
+.PP
+.Vb 1
+\&    SvEND(SV*)
+.Ve
+.PP
+But note that these last three macros are valid only if \f(CWSvPOK()\fR is true.
+.PP
+If you want to append something to the end of string stored in an \f(CW\*(C`SV*\*(C'\fR,
+you can use the following functions:
+.PP
+.Vb 6
+\&    void  sv_catpv(SV*, const char*);
+\&    void  sv_catpvn(SV*, const char*, STRLEN);
+\&    void  sv_catpvf(SV*, const char*, ...);
+\&    void  sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **,
+\&                                                             I32, bool);
+\&    void  sv_catsv(SV*, SV*);
+.Ve
+.PP
+The first function calculates the length of the string to be appended by
+using \f(CW\*(C`strlen\*(C'\fR.  In the second, you specify the length of the string
+yourself.  The third function processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and
+appends the formatted output.  The fourth function works like \f(CW\*(C`vsprintf\*(C'\fR.
+You can specify the address and length of an array of SVs instead of the
+va_list argument.  The fifth function
+extends the string stored in the first
+SV with the string stored in the second SV.  It also forces the second SV
+to be interpreted as a string.
+.PP
+The \f(CW\*(C`sv_cat*()\*(C'\fR functions are not generic enough to operate on values that
+have "magic".  See "Magic Virtual Tables" later in this document.
+.PP
+If you know the name of a scalar variable, you can get a pointer to its SV
+by using the following:
+.PP
+.Vb 1
+\&    SV*  get_sv("package::varname", 0);
+.Ve
+.PP
+This returns NULL if the variable does not exist.
+.PP
+If you want to know if this variable (or any other SV) is actually \f(CW\*(C`defined\*(C'\fR,
+you can call:
+.PP
+.Vb 1
+\&    SvOK(SV*)
+.Ve
+.PP
+The scalar \f(CW\*(C`undef\*(C'\fR value is stored in an SV instance called \f(CW\*(C`PL_sv_undef\*(C'\fR.
+.PP
+Its address can be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed.  Make sure that
+you don't try to compare a random sv with \f(CW&PL_sv_undef\fR.  For example
+when interfacing Perl code, it'll work correctly for:
+.PP
+.Vb 1
+\&  foo(undef);
+.Ve
+.PP
+But won't work when called as:
+.PP
+.Vb 2
+\&  $x = undef;
+\&  foo($x);
+.Ve
+.PP
+So to repeat always use \fBSvOK()\fR to check whether an sv is defined.
+.PP
+Also you have to be careful when using \f(CW&PL_sv_undef\fR as a value in
+AVs or HVs (see "AVs, HVs and undefined values").
+.PP
+There are also the two values \f(CW\*(C`PL_sv_yes\*(C'\fR and \f(CW\*(C`PL_sv_no\*(C'\fR, which contain
+boolean TRUE and FALSE values, respectively.  Like \f(CW\*(C`PL_sv_undef\*(C'\fR, their
+addresses can be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed.
+.PP
+Do not be fooled into thinking that \f(CW\*(C`(SV *) 0\*(C'\fR is the same as \f(CW&PL_sv_undef\fR.
+Take this code:
+.PP
+.Vb 5
+\&    SV* sv = (SV*) 0;
+\&    if (I\-am\-to\-return\-a\-real\-value) {
+\&            sv = sv_2mortal(newSViv(42));
+\&    }
+\&    sv_setsv(ST(0), sv);
+.Ve
+.PP
+This code tries to return a new SV (which contains the value 42) if it should
+return a real value, or undef otherwise.  Instead it has returned a NULL
+pointer which, somewhere down the line, will cause a segmentation violation,
+bus error, or just weird results.  Change the zero to \f(CW&PL_sv_undef\fR in the
+first line and all will be well.
+.PP
+To free an SV that you've created, call \f(CWSvREFCNT_dec(SV*)\fR.  Normally this
+call is not necessary (see "Reference Counts and Mortality").
+.SS Offsets
+.IX Subsection "Offsets"
+Perl provides the function \f(CW\*(C`sv_chop\*(C'\fR to efficiently remove characters
+from the beginning of a string; you give it an SV and a pointer to
+somewhere inside the PV, and it discards everything before the
+pointer.  The efficiency comes by means of a little hack: instead of
+actually removing the characters, \f(CW\*(C`sv_chop\*(C'\fR sets the flag \f(CW\*(C`OOK\*(C'\fR
+(offset OK) to signal to other functions that the offset hack is in
+effect, and it moves the PV pointer (called \f(CW\*(C`SvPVX\*(C'\fR) forward
+by the number of bytes chopped off, and adjusts \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR
+accordingly.  (A portion of the space between the old and new PV
+pointers is used to store the count of chopped bytes.)
+.PP
+Hence, at this point, the start of the buffer that we allocated lives
+at \f(CW\*(C`SvPVX(sv) \- SvIV(sv)\*(C'\fR in memory and the PV pointer is pointing
+into the middle of this allocated storage.
+.PP
+This is best demonstrated by example.  Normally copy-on-write will prevent
+the substitution from operator from using this hack, but if you can craft a
+string for which copy-on-write is not possible, you can see it in play.  In
+the current implementation, the final byte of a string buffer is used as a
+copy-on-write reference count.  If the buffer is not big enough, then
+copy-on-write is skipped.  First have a look at an empty string:
+.PP
+.Vb 7
+\&  % ./perl \-Ilib \-MDevel::Peek \-le \*(Aq$a=""; $a .= ""; Dump $a\*(Aq
+\&  SV = PV(0x7ffb7c008a70) at 0x7ffb7c030390
+\&    REFCNT = 1
+\&    FLAGS = (POK,pPOK)
+\&    PV = 0x7ffb7bc05b50 ""\e0
+\&    CUR = 0
+\&    LEN = 10
+.Ve
+.PP
+Notice here the LEN is 10.  (It may differ on your platform.)  Extend the
+length of the string to one less than 10, and do a substitution:
+.PP
+.Vb 9
+\& % ./perl \-Ilib \-MDevel::Peek \-le \*(Aq$a=""; $a.="123456789"; $a=~s/.//; \e
+\&                                                            Dump($a)\*(Aq
+\& SV = PV(0x7ffa04008a70) at 0x7ffa04030390
+\&   REFCNT = 1
+\&   FLAGS = (POK,OOK,pPOK)
+\&   OFFSET = 1
+\&   PV = 0x7ffa03c05b61 ( "\e1" . ) "23456789"\e0
+\&   CUR = 8
+\&   LEN = 9
+.Ve
+.PP
+Here the number of bytes chopped off (1) is shown next as the OFFSET.  The
+portion of the string between the "real" and the "fake" beginnings is
+shown in parentheses, and the values of \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR reflect
+the fake beginning, not the real one.  (The first character of the string
+buffer happens to have changed to "\e1" here, not "1", because the current
+implementation stores the offset count in the string buffer.  This is
+subject to change.)
+.PP
+Something similar to the offset hack is performed on AVs to enable
+efficient shifting and splicing off the beginning of the array; while
+\&\f(CW\*(C`AvARRAY\*(C'\fR points to the first element in the array that is visible from
+Perl, \f(CW\*(C`AvALLOC\*(C'\fR points to the real start of the C array.  These are
+usually the same, but a \f(CW\*(C`shift\*(C'\fR operation can be carried out by
+increasing \f(CW\*(C`AvARRAY\*(C'\fR by one and decreasing \f(CW\*(C`AvFILL\*(C'\fR and \f(CW\*(C`AvMAX\*(C'\fR.
+Again, the location of the real start of the C array only comes into
+play when freeing the array.  See \f(CW\*(C`av_shift\*(C'\fR in \fIav.c\fR.
+.SS "What's Really Stored in an SV?"
+.IX Subsection "What's Really Stored in an SV?"
+Recall that the usual method of determining the type of scalar you have is
+to use \f(CW\*(C`Sv*OK\*(C'\fR macros.  Because a scalar can be both a number and a string,
+usually these macros will always return TRUE and calling the \f(CW\*(C`Sv*V\*(C'\fR
+macros will do the appropriate conversion of string to integer/double or
+integer/double to string.
+.PP
+If you \fIreally\fR need to know if you have an integer, double, or string
+pointer in an SV, you can use the following three macros instead:
+.PP
+.Vb 3
+\&    SvIOKp(SV*)
+\&    SvNOKp(SV*)
+\&    SvPOKp(SV*)
+.Ve
+.PP
+These will tell you if you truly have an integer, double, or string pointer
+stored in your SV.  The "p" stands for private.
+.PP
+There are various ways in which the private and public flags may differ.
+For example, in perl 5.16 and earlier a tied SV may have a valid
+underlying value in the IV slot (so SvIOKp is true), but the data
+should be accessed via the FETCH routine rather than directly,
+so SvIOK is false.  (In perl 5.18 onwards, tied scalars use
+the flags the same way as untied scalars.)  Another is when
+numeric conversion has occurred and precision has been lost: only the
+private flag is set on 'lossy' values.  So when an NV is converted to an
+IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.
+.PP
+In general, though, it's best to use the \f(CW\*(C`Sv*V\*(C'\fR macros.
+.SS "Working with AVs"
+.IX Subsection "Working with AVs"
+There are two main, longstanding ways to create and load an AV.  The first
+method creates an empty AV:
+.PP
+.Vb 1
+\&    AV*  newAV();
+.Ve
+.PP
+The second method both creates the AV and initially populates it with SVs:
+.PP
+.Vb 1
+\&    AV*  av_make(SSize_t num, SV **ptr);
+.Ve
+.PP
+The second argument points to an array containing \f(CW\*(C`num\*(C'\fR \f(CW\*(C`SV*\*(C'\fR's.  Once the
+AV has been created, the SVs can be destroyed, if so desired.
+.PP
+Perl v5.36 added two new ways to create an AV and allocate a SV** array
+without populating it. These are more efficient than a \fBnewAV()\fR followed by an
+\&\fBav_extend()\fR.
+.PP
+.Vb 4
+\&    /* Creates but does not initialize (Zero) the SV** array */
+\&    AV *av = newAV_alloc_x(1);
+\&    /* Creates and does initialize (Zero) the SV** array */
+\&    AV *av = newAV_alloc_xz(1);
+.Ve
+.PP
+The numerical argument refers to the number of array elements to allocate, not
+an array index, and must be >0. The first form must only ever be used when all
+elements will be initialized before any read occurs. Reading a non-initialized
+SV* \- i.e. treating a random memory address as a SV* \- is a serious bug.
+.PP
+Once the AV has been created, the following operations are possible on it:
+.PP
+.Vb 4
+\&    void  av_push(AV*, SV*);
+\&    SV*   av_pop(AV*);
+\&    SV*   av_shift(AV*);
+\&    void  av_unshift(AV*, SSize_t num);
+.Ve
+.PP
+These should be familiar operations, with the exception of \f(CW\*(C`av_unshift\*(C'\fR.
+This routine adds \f(CW\*(C`num\*(C'\fR elements at the front of the array with the \f(CW\*(C`undef\*(C'\fR
+value.  You must then use \f(CW\*(C`av_store\*(C'\fR (described below) to assign values
+to these new elements.
+.PP
+Here are some other functions:
+.PP
+.Vb 3
+\&    SSize_t av_top_index(AV*);
+\&    SV**    av_fetch(AV*, SSize_t key, I32 lval);
+\&    SV**    av_store(AV*, SSize_t key, SV* val);
+.Ve
+.PP
+The \f(CW\*(C`av_top_index\*(C'\fR function returns the highest index value in an array (just
+like $#array in Perl).  If the array is empty, \-1 is returned.  The
+\&\f(CW\*(C`av_fetch\*(C'\fR function returns the value at index \f(CW\*(C`key\*(C'\fR, but if \f(CW\*(C`lval\*(C'\fR
+is non-zero, then \f(CW\*(C`av_fetch\*(C'\fR will store an undef value at that index.
+The \f(CW\*(C`av_store\*(C'\fR function stores the value \f(CW\*(C`val\*(C'\fR at index \f(CW\*(C`key\*(C'\fR, and does
+not increment the reference count of \f(CW\*(C`val\*(C'\fR.  Thus the caller is responsible
+for taking care of that, and if \f(CW\*(C`av_store\*(C'\fR returns NULL, the caller will
+have to decrement the reference count to avoid a memory leak.  Note that
+\&\f(CW\*(C`av_fetch\*(C'\fR and \f(CW\*(C`av_store\*(C'\fR both return \f(CW\*(C`SV**\*(C'\fR's, not \f(CW\*(C`SV*\*(C'\fR's as their
+return value.
+.PP
+A few more:
+.PP
+.Vb 3
+\&    void  av_clear(AV*);
+\&    void  av_undef(AV*);
+\&    void  av_extend(AV*, SSize_t key);
+.Ve
+.PP
+The \f(CW\*(C`av_clear\*(C'\fR function deletes all the elements in the AV* array, but
+does not actually delete the array itself.  The \f(CW\*(C`av_undef\*(C'\fR function will
+delete all the elements in the array plus the array itself.  The
+\&\f(CW\*(C`av_extend\*(C'\fR function extends the array so that it contains at least \f(CW\*(C`key+1\*(C'\fR
+elements.  If \f(CW\*(C`key+1\*(C'\fR is less than the currently allocated length of the array,
+then nothing is done.
+.PP
+If you know the name of an array variable, you can get a pointer to its AV
+by using the following:
+.PP
+.Vb 1
+\&    AV*  get_av("package::varname", 0);
+.Ve
+.PP
+This returns NULL if the variable does not exist.
+.PP
+See "Understanding the Magic of Tied Hashes and Arrays" for more
+information on how to use the array access functions on tied arrays.
+.PP
+\fIMore efficient working with new or vanilla AVs\fR
+.IX Subsection "More efficient working with new or vanilla AVs"
+.PP
+Perl v5.36 and v5.38 introduced streamlined, inlined versions of some
+functions:
+.IP \(bu 4
+\&\f(CW\*(C`av_store_simple\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`av_fetch_simple\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`av_push_simple\*(C'\fR
+.PP
+These are drop-in replacements, but can only be used on straightforward
+AVs that meet the following criteria:
+.IP \(bu 4
+are not magical
+.IP \(bu 4
+are not readonly
+.IP \(bu 4
+are "real" (refcounted) AVs
+.IP \(bu 4
+have an av_top_index value > \-2
+.PP
+AVs created using \f(CWnewAV()\fR, \f(CW\*(C`av_make\*(C'\fR, \f(CW\*(C`newAV_alloc_x\*(C'\fR, and
+\&\f(CW\*(C`newAV_alloc_xz\*(C'\fR are all compatible at the time of creation. It is
+only if they are declared readonly or unreal, have magic attached, or
+are otherwise configured unusually that they will stop being compatible.
+.PP
+Note that some interpreter functions may attach magic to an AV as part
+of normal operations. It is therefore safest, unless you are sure of the
+lifecycle of an AV, to only use these new functions close to the point
+of AV creation.
+.SS "Working with HVs"
+.IX Subsection "Working with HVs"
+To create an HV, you use the following routine:
+.PP
+.Vb 1
+\&    HV*  newHV();
+.Ve
+.PP
+Once the HV has been created, the following operations are possible on it:
+.PP
+.Vb 2
+\&    SV**  hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
+\&    SV**  hv_fetch(HV*, const char* key, U32 klen, I32 lval);
+.Ve
+.PP
+The \f(CW\*(C`klen\*(C'\fR parameter is the length of the key being passed in (Note that
+you cannot pass 0 in as a value of \f(CW\*(C`klen\*(C'\fR to tell Perl to measure the
+length of the key).  The \f(CW\*(C`val\*(C'\fR argument contains the SV pointer to the
+scalar being stored, and \f(CW\*(C`hash\*(C'\fR is the precomputed hash value (zero if
+you want \f(CW\*(C`hv_store\*(C'\fR to calculate it for you).  The \f(CW\*(C`lval\*(C'\fR parameter
+indicates whether this fetch is actually a part of a store operation, in
+which case a new undefined value will be added to the HV with the supplied
+key and \f(CW\*(C`hv_fetch\*(C'\fR will return as if the value had already existed.
+.PP
+Remember that \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_fetch\*(C'\fR return \f(CW\*(C`SV**\*(C'\fR's and not just
+\&\f(CW\*(C`SV*\*(C'\fR.  To access the scalar value, you must first dereference the return
+value.  However, you should check to make sure that the return value is
+not NULL before dereferencing it.
+.PP
+The first of these two functions checks if a hash table entry exists, and the 
+second deletes it.
+.PP
+.Vb 2
+\&    bool  hv_exists(HV*, const char* key, U32 klen);
+\&    SV*   hv_delete(HV*, const char* key, U32 klen, I32 flags);
+.Ve
+.PP
+If \f(CW\*(C`flags\*(C'\fR does not include the \f(CW\*(C`G_DISCARD\*(C'\fR flag then \f(CW\*(C`hv_delete\*(C'\fR will
+create and return a mortal copy of the deleted value.
+.PP
+And more miscellaneous functions:
+.PP
+.Vb 2
+\&    void   hv_clear(HV*);
+\&    void   hv_undef(HV*);
+.Ve
+.PP
+Like their AV counterparts, \f(CW\*(C`hv_clear\*(C'\fR deletes all the entries in the hash
+table but does not actually delete the hash table.  The \f(CW\*(C`hv_undef\*(C'\fR deletes
+both the entries and the hash table itself.
+.PP
+Perl keeps the actual data in a linked list of structures with a typedef of HE.
+These contain the actual key and value pointers (plus extra administrative
+overhead).  The key is a string pointer; the value is an \f(CW\*(C`SV*\*(C'\fR.  However,
+once you have an \f(CW\*(C`HE*\*(C'\fR, to get the actual key and value, use the routines
+specified below.
+.PP
+.Vb 10
+\&    I32    hv_iterinit(HV*);
+\&            /* Prepares starting point to traverse hash table */
+\&    HE*    hv_iternext(HV*);
+\&            /* Get the next entry, and return a pointer to a
+\&               structure that has both the key and value */
+\&    char*  hv_iterkey(HE* entry, I32* retlen);
+\&            /* Get the key from an HE structure and also return
+\&               the length of the key string */
+\&    SV*    hv_iterval(HV*, HE* entry);
+\&            /* Return an SV pointer to the value of the HE
+\&               structure */
+\&    SV*    hv_iternextsv(HV*, char** key, I32* retlen);
+\&            /* This convenience routine combines hv_iternext,
+\&               hv_iterkey, and hv_iterval.  The key and retlen
+\&               arguments are return values for the key and its
+\&               length.  The value is returned in the SV* argument */
+.Ve
+.PP
+If you know the name of a hash variable, you can get a pointer to its HV
+by using the following:
+.PP
+.Vb 1
+\&    HV*  get_hv("package::varname", 0);
+.Ve
+.PP
+This returns NULL if the variable does not exist.
+.PP
+The hash algorithm is defined in the \f(CW\*(C`PERL_HASH\*(C'\fR macro:
+.PP
+.Vb 1
+\&    PERL_HASH(hash, key, klen)
+.Ve
+.PP
+The exact implementation of this macro varies by architecture and version
+of perl, and the return value may change per invocation, so the value
+is only valid for the duration of a single perl process.
+.PP
+See "Understanding the Magic of Tied Hashes and Arrays" for more
+information on how to use the hash access functions on tied hashes.
+.SS "Hash API Extensions"
+.IX Subsection "Hash API Extensions"
+Beginning with version 5.004, the following functions are also supported:
+.PP
+.Vb 2
+\&    HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
+\&    HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
+\&
+\&    bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
+\&    SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
+\&
+\&    SV*     hv_iterkeysv  (HE* entry);
+.Ve
+.PP
+Note that these functions take \f(CW\*(C`SV*\*(C'\fR keys, which simplifies writing
+of extension code that deals with hash structures.  These functions
+also allow passing of \f(CW\*(C`SV*\*(C'\fR keys to \f(CW\*(C`tie\*(C'\fR functions without forcing
+you to stringify the keys (unlike the previous set of functions).
+.PP
+They also return and accept whole hash entries (\f(CW\*(C`HE*\*(C'\fR), making their
+use more efficient (since the hash number for a particular string
+doesn't have to be recomputed every time).  See perlapi for detailed
+descriptions.
+.PP
+The following macros must always be used to access the contents of hash
+entries.  Note that the arguments to these macros must be simple
+variables, since they may get evaluated more than once.  See
+perlapi for detailed descriptions of these macros.
+.PP
+.Vb 6
+\&    HePV(HE* he, STRLEN len)
+\&    HeVAL(HE* he)
+\&    HeHASH(HE* he)
+\&    HeSVKEY(HE* he)
+\&    HeSVKEY_force(HE* he)
+\&    HeSVKEY_set(HE* he, SV* sv)
+.Ve
+.PP
+These two lower level macros are defined, but must only be used when
+dealing with keys that are not \f(CW\*(C`SV*\*(C'\fRs:
+.PP
+.Vb 2
+\&    HeKEY(HE* he)
+\&    HeKLEN(HE* he)
+.Ve
+.PP
+Note that both \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_store_ent\*(C'\fR do not increment the
+reference count of the stored \f(CW\*(C`val\*(C'\fR, which is the caller's responsibility.
+If these functions return a NULL value, the caller will usually have to
+decrement the reference count of \f(CW\*(C`val\*(C'\fR to avoid a memory leak.
+.SS "AVs, HVs and undefined values"
+.IX Subsection "AVs, HVs and undefined values"
+Sometimes you have to store undefined values in AVs or HVs.  Although
+this may be a rare case, it can be tricky.  That's because you're
+used to using \f(CW&PL_sv_undef\fR if you need an undefined SV.
+.PP
+For example, intuition tells you that this XS code:
+.PP
+.Vb 2
+\&    AV *av = newAV();
+\&    av_store( av, 0, &PL_sv_undef );
+.Ve
+.PP
+is equivalent to this Perl code:
+.PP
+.Vb 2
+\&    my @av;
+\&    $av[0] = undef;
+.Ve
+.PP
+Unfortunately, this isn't true.  In perl 5.18 and earlier, AVs use \f(CW&PL_sv_undef\fR as a marker
+for indicating that an array element has not yet been initialized.
+Thus, \f(CW\*(C`exists $av[0]\*(C'\fR would be true for the above Perl code, but
+false for the array generated by the XS code.  In perl 5.20, storing
+&PL_sv_undef will create a read-only element, because the scalar
+&PL_sv_undef itself is stored, not a copy.
+.PP
+Similar problems can occur when storing \f(CW&PL_sv_undef\fR in HVs:
+.PP
+.Vb 1
+\&    hv_store( hv, "key", 3, &PL_sv_undef, 0 );
+.Ve
+.PP
+This will indeed make the value \f(CW\*(C`undef\*(C'\fR, but if you try to modify
+the value of \f(CW\*(C`key\*(C'\fR, you'll get the following error:
+.PP
+.Vb 1
+\&    Modification of non\-creatable hash value attempted
+.Ve
+.PP
+In perl 5.8.0, \f(CW&PL_sv_undef\fR was also used to mark placeholders
+in restricted hashes.  This caused such hash entries not to appear
+when iterating over the hash or when checking for the keys
+with the \f(CW\*(C`hv_exists\*(C'\fR function.
+.PP
+You can run into similar problems when you store \f(CW&PL_sv_yes\fR or
+\&\f(CW&PL_sv_no\fR into AVs or HVs.  Trying to modify such elements
+will give you the following error:
+.PP
+.Vb 1
+\&    Modification of a read\-only value attempted
+.Ve
+.PP
+To make a long story short, you can use the special variables
+\&\f(CW&PL_sv_undef\fR, \f(CW&PL_sv_yes\fR and \f(CW&PL_sv_no\fR with AVs and
+HVs, but you have to make sure you know what you're doing.
+.PP
+Generally, if you want to store an undefined value in an AV
+or HV, you should not use \f(CW&PL_sv_undef\fR, but rather create a
+new undefined value using the \f(CW\*(C`newSV\*(C'\fR function, for example:
+.PP
+.Vb 2
+\&    av_store( av, 42, newSV(0) );
+\&    hv_store( hv, "foo", 3, newSV(0), 0 );
+.Ve
+.SS References
+.IX Subsection "References"
+References are a special type of scalar that point to other data types
+(including other references).
+.PP
+To create a reference, use either of the following functions:
+.PP
+.Vb 2
+\&    SV* newRV_inc((SV*) thing);
+\&    SV* newRV_noinc((SV*) thing);
+.Ve
+.PP
+The \f(CW\*(C`thing\*(C'\fR argument can be any of an \f(CW\*(C`SV*\*(C'\fR, \f(CW\*(C`AV*\*(C'\fR, or \f(CW\*(C`HV*\*(C'\fR.  The
+functions are identical except that \f(CW\*(C`newRV_inc\*(C'\fR increments the reference
+count of the \f(CW\*(C`thing\*(C'\fR, while \f(CW\*(C`newRV_noinc\*(C'\fR does not.  For historical
+reasons, \f(CW\*(C`newRV\*(C'\fR is a synonym for \f(CW\*(C`newRV_inc\*(C'\fR.
+.PP
+Once you have a reference, you can use the following macro to dereference
+the reference:
+.PP
+.Vb 1
+\&    SvRV(SV*)
+.Ve
+.PP
+then call the appropriate routines, casting the returned \f(CW\*(C`SV*\*(C'\fR to either an
+\&\f(CW\*(C`AV*\*(C'\fR or \f(CW\*(C`HV*\*(C'\fR, if required.
+.PP
+To determine if an SV is a reference, you can use the following macro:
+.PP
+.Vb 1
+\&    SvROK(SV*)
+.Ve
+.PP
+To discover what type of value the reference refers to, use the following
+macro and then check the return value.
+.PP
+.Vb 1
+\&    SvTYPE(SvRV(SV*))
+.Ve
+.PP
+The most useful types that will be returned are:
+.PP
+.Vb 4
+\&    SVt_PVAV    Array
+\&    SVt_PVHV    Hash
+\&    SVt_PVCV    Code
+\&    SVt_PVGV    Glob (possibly a file handle)
+.Ve
+.PP
+Any numerical value returned which is less than SVt_PVAV will be a scalar
+of some form.
+.PP
+See "svtype" in perlapi for more details.
+.SS "Blessed References and Class Objects"
+.IX Subsection "Blessed References and Class Objects"
+References are also used to support object-oriented programming.  In perl's
+OO lexicon, an object is simply a reference that has been blessed into a
+package (or class).  Once blessed, the programmer may now use the reference
+to access the various methods in the class.
+.PP
+A reference can be blessed into a package with the following function:
+.PP
+.Vb 1
+\&    SV* sv_bless(SV* sv, HV* stash);
+.Ve
+.PP
+The \f(CW\*(C`sv\*(C'\fR argument must be a reference value.  The \f(CW\*(C`stash\*(C'\fR argument
+specifies which class the reference will belong to.  See
+"Stashes and Globs" for information on converting class names into stashes.
+.PP
+/* Still under construction */
+.PP
+The following function upgrades rv to reference if not already one.
+Creates a new SV for rv to point to.  If \f(CW\*(C`classname\*(C'\fR is non-null, the SV
+is blessed into the specified class.  SV is returned.
+.PP
+.Vb 1
+\&        SV* newSVrv(SV* rv, const char* classname);
+.Ve
+.PP
+The following three functions copy integer, unsigned integer or double
+into an SV whose reference is \f(CW\*(C`rv\*(C'\fR.  SV is blessed if \f(CW\*(C`classname\*(C'\fR is
+non-null.
+.PP
+.Vb 3
+\&        SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
+\&        SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
+\&        SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
+.Ve
+.PP
+The following function copies the pointer value (\fIthe address, not the
+string!\fR) into an SV whose reference is rv.  SV is blessed if \f(CW\*(C`classname\*(C'\fR
+is non-null.
+.PP
+.Vb 1
+\&        SV* sv_setref_pv(SV* rv, const char* classname, void* pv);
+.Ve
+.PP
+The following function copies a string into an SV whose reference is \f(CW\*(C`rv\*(C'\fR.
+Set length to 0 to let Perl calculate the string length.  SV is blessed if
+\&\f(CW\*(C`classname\*(C'\fR is non-null.
+.PP
+.Vb 2
+\&    SV* sv_setref_pvn(SV* rv, const char* classname, char* pv,
+\&                                                         STRLEN length);
+.Ve
+.PP
+The following function tests whether the SV is blessed into the specified
+class.  It does not check inheritance relationships.
+.PP
+.Vb 1
+\&        int  sv_isa(SV* sv, const char* name);
+.Ve
+.PP
+The following function tests whether the SV is a reference to a blessed object.
+.PP
+.Vb 1
+\&        int  sv_isobject(SV* sv);
+.Ve
+.PP
+The following function tests whether the SV is derived from the specified
+class.  SV can be either a reference to a blessed object or a string
+containing a class name.  This is the function implementing the
+\&\f(CW\*(C`UNIVERSAL::isa\*(C'\fR functionality.
+.PP
+.Vb 1
+\&        bool sv_derived_from(SV* sv, const char* name);
+.Ve
+.PP
+To check if you've got an object derived from a specific class you have
+to write:
+.PP
+.Vb 1
+\&        if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
+.Ve
+.SS "Creating New Variables"
+.IX Subsection "Creating New Variables"
+To create a new Perl variable with an undef value which can be accessed from
+your Perl script, use the following routines, depending on the variable type.
+.PP
+.Vb 3
+\&    SV*  get_sv("package::varname", GV_ADD);
+\&    AV*  get_av("package::varname", GV_ADD);
+\&    HV*  get_hv("package::varname", GV_ADD);
+.Ve
+.PP
+Notice the use of GV_ADD as the second parameter.  The new variable can now
+be set, using the routines appropriate to the data type.
+.PP
+There are additional macros whose values may be bitwise OR'ed with the
+\&\f(CW\*(C`GV_ADD\*(C'\fR argument to enable certain extra features.  Those bits are:
+.IP GV_ADDMULTI 4
+.IX Item "GV_ADDMULTI"
+Marks the variable as multiply defined, thus preventing the:
+.Sp
+.Vb 1
+\&  Name <varname> used only once: possible typo
+.Ve
+.Sp
+warning.
+.IP GV_ADDWARN 4
+.IX Item "GV_ADDWARN"
+Issues the warning:
+.Sp
+.Vb 1
+\&  Had to create <varname> unexpectedly
+.Ve
+.Sp
+if the variable did not exist before the function was called.
+.PP
+If you do not specify a package name, the variable is created in the current
+package.
+.SS "Reference Counts and Mortality"
+.IX Subsection "Reference Counts and Mortality"
+Perl uses a reference count-driven garbage collection mechanism.  SVs,
+AVs, or HVs (xV for short in the following) start their life with a
+reference count of 1.  If the reference count of an xV ever drops to 0,
+then it will be destroyed and its memory made available for reuse.
+At the most basic internal level, reference counts can be manipulated
+with the following macros:
+.PP
+.Vb 3
+\&    int SvREFCNT(SV* sv);
+\&    SV* SvREFCNT_inc(SV* sv);
+\&    void SvREFCNT_dec(SV* sv);
+.Ve
+.PP
+(There are also suffixed versions of the increment and decrement macros,
+for situations where the full generality of these basic macros can be
+exchanged for some performance.)
+.PP
+However, the way a programmer should think about references is not so
+much in terms of the bare reference count, but in terms of \fIownership\fR
+of references.  A reference to an xV can be owned by any of a variety
+of entities: another xV, the Perl interpreter, an XS data structure,
+a piece of running code, or a dynamic scope.  An xV generally does not
+know what entities own the references to it; it only knows how many
+references there are, which is the reference count.
+.PP
+To correctly maintain reference counts, it is essential to keep track
+of what references the XS code is manipulating.  The programmer should
+always know where a reference has come from and who owns it, and be
+aware of any creation or destruction of references, and any transfers
+of ownership.  Because ownership isn't represented explicitly in the xV
+data structures, only the reference count need be actually maintained
+by the code, and that means that this understanding of ownership is not
+actually evident in the code.  For example, transferring ownership of a
+reference from one owner to another doesn't change the reference count
+at all, so may be achieved with no actual code.  (The transferring code
+doesn't touch the referenced object, but does need to ensure that the
+former owner knows that it no longer owns the reference, and that the
+new owner knows that it now does.)
+.PP
+An xV that is visible at the Perl level should not become unreferenced
+and thus be destroyed.  Normally, an object will only become unreferenced
+when it is no longer visible, often by the same means that makes it
+invisible.  For example, a Perl reference value (RV) owns a reference to
+its referent, so if the RV is overwritten that reference gets destroyed,
+and the no-longer-reachable referent may be destroyed as a result.
+.PP
+Many functions have some kind of reference manipulation as
+part of their purpose.  Sometimes this is documented in terms
+of ownership of references, and sometimes it is (less helpfully)
+documented in terms of changes to reference counts.  For example, the
+\&\fBnewRV_inc()\fR function is documented to create a new RV
+(with reference count 1) and increment the reference count of the referent
+that was supplied by the caller.  This is best understood as creating
+a new reference to the referent, which is owned by the created RV,
+and returning to the caller ownership of the sole reference to the RV.
+The \fBnewRV_noinc()\fR function instead does not
+increment the reference count of the referent, but the RV nevertheless
+ends up owning a reference to the referent.  It is therefore implied
+that the caller of \f(CWnewRV_noinc()\fR is relinquishing a reference to the
+referent, making this conceptually a more complicated operation even
+though it does less to the data structures.
+.PP
+For example, imagine you want to return a reference from an XSUB
+function.  Inside the XSUB routine, you create an SV which initially
+has just a single reference, owned by the XSUB routine.  This reference
+needs to be disposed of before the routine is complete, otherwise it
+will leak, preventing the SV from ever being destroyed.  So to create
+an RV referencing the SV, it is most convenient to pass the SV to
+\&\f(CWnewRV_noinc()\fR, which consumes that reference.  Now the XSUB routine
+no longer owns a reference to the SV, but does own a reference to the RV,
+which in turn owns a reference to the SV.  The ownership of the reference
+to the RV is then transferred by the process of returning the RV from
+the XSUB.
+.PP
+There are some convenience functions available that can help with the
+destruction of xVs.  These functions introduce the concept of "mortality".
+Much documentation speaks of an xV itself being mortal, but this is
+misleading.  It is really \fIa reference to\fR an xV that is mortal, and it
+is possible for there to be more than one mortal reference to a single xV.
+For a reference to be mortal means that it is owned by the temps stack,
+one of perl's many internal stacks, which will destroy that reference
+"a short time later".  Usually the "short time later" is the end of
+the current Perl statement.  However, it gets more complicated around
+dynamic scopes: there can be multiple sets of mortal references hanging
+around at the same time, with different death dates.  Internally, the
+actual determinant for when mortal xV references are destroyed depends
+on two macros, SAVETMPS and FREETMPS.  See perlcall and perlxs
+and "Temporaries Stack" below for more details on these macros.
+.PP
+Mortal references are mainly used for xVs that are placed on perl's
+main stack.  The stack is problematic for reference tracking, because it
+contains a lot of xV references, but doesn't own those references: they
+are not counted.  Currently, there are many bugs resulting from xVs being
+destroyed while referenced by the stack, because the stack's uncounted
+references aren't enough to keep the xVs alive.  So when putting an
+(uncounted) reference on the stack, it is vitally important to ensure that
+there will be a counted reference to the same xV that will last at least
+as long as the uncounted reference.  But it's also important that that
+counted reference be cleaned up at an appropriate time, and not unduly
+prolong the xV's life.  For there to be a mortal reference is often the
+best way to satisfy this requirement, especially if the xV was created
+especially to be put on the stack and would otherwise be unreferenced.
+.PP
+To create a mortal reference, use the functions:
+.PP
+.Vb 3
+\&    SV*  sv_newmortal()
+\&    SV*  sv_mortalcopy(SV*)
+\&    SV*  sv_2mortal(SV*)
+.Ve
+.PP
+\&\f(CWsv_newmortal()\fR creates an SV (with the undefined value) whose sole
+reference is mortal.  \f(CWsv_mortalcopy()\fR creates an xV whose value is a
+copy of a supplied xV and whose sole reference is mortal.  \f(CWsv_2mortal()\fR
+mortalises an existing xV reference: it transfers ownership of a reference
+from the caller to the temps stack.  Because \f(CW\*(C`sv_newmortal\*(C'\fR gives the new
+SV no value, it must normally be given one via \f(CW\*(C`sv_setpv\*(C'\fR, \f(CW\*(C`sv_setiv\*(C'\fR,
+etc. :
+.PP
+.Vb 2
+\&    SV *tmp = sv_newmortal();
+\&    sv_setiv(tmp, an_integer);
+.Ve
+.PP
+As that is multiple C statements it is quite common so see this idiom instead:
+.PP
+.Vb 1
+\&    SV *tmp = sv_2mortal(newSViv(an_integer));
+.Ve
+.PP
+The mortal routines are not just for SVs; AVs and HVs can be
+made mortal by passing their address (type-casted to \f(CW\*(C`SV*\*(C'\fR) to the
+\&\f(CW\*(C`sv_2mortal\*(C'\fR or \f(CW\*(C`sv_mortalcopy\*(C'\fR routines.
+.SS "Stashes and Globs"
+.IX Subsection "Stashes and Globs"
+A \fBstash\fR is a hash that contains all variables that are defined
+within a package.  Each key of the stash is a symbol
+name (shared by all the different types of objects that have the same
+name), and each value in the hash table is a GV (Glob Value).  This GV
+in turn contains references to the various objects of that name,
+including (but not limited to) the following:
+.PP
+.Vb 6
+\&    Scalar Value
+\&    Array Value
+\&    Hash Value
+\&    I/O Handle
+\&    Format
+\&    Subroutine
+.Ve
+.PP
+There is a single stash called \f(CW\*(C`PL_defstash\*(C'\fR that holds the items that exist
+in the \f(CW\*(C`main\*(C'\fR package.  To get at the items in other packages, append the
+string "::" to the package name.  The items in the \f(CW\*(C`Foo\*(C'\fR package are in
+the stash \f(CW\*(C`Foo::\*(C'\fR in PL_defstash.  The items in the \f(CW\*(C`Bar::Baz\*(C'\fR package are
+in the stash \f(CW\*(C`Baz::\*(C'\fR in \f(CW\*(C`Bar::\*(C'\fR's stash.
+.PP
+To get the stash pointer for a particular package, use the function:
+.PP
+.Vb 2
+\&    HV*  gv_stashpv(const char* name, I32 flags)
+\&    HV*  gv_stashsv(SV*, I32 flags)
+.Ve
+.PP
+The first function takes a literal string, the second uses the string stored
+in the SV.  Remember that a stash is just a hash table, so you get back an
+\&\f(CW\*(C`HV*\*(C'\fR.  The \f(CW\*(C`flags\*(C'\fR flag will create a new package if it is set to GV_ADD.
+.PP
+The name that \f(CW\*(C`gv_stash*v\*(C'\fR wants is the name of the package whose symbol table
+you want.  The default package is called \f(CW\*(C`main\*(C'\fR.  If you have multiply nested
+packages, pass their names to \f(CW\*(C`gv_stash*v\*(C'\fR, separated by \f(CW\*(C`::\*(C'\fR as in the Perl
+language itself.
+.PP
+Alternately, if you have an SV that is a blessed reference, you can find
+out the stash pointer by using:
+.PP
+.Vb 1
+\&    HV*  SvSTASH(SvRV(SV*));
+.Ve
+.PP
+then use the following to get the package name itself:
+.PP
+.Vb 1
+\&    char*  HvNAME(HV* stash);
+.Ve
+.PP
+If you need to bless or re-bless an object you can use the following
+function:
+.PP
+.Vb 1
+\&    SV*  sv_bless(SV*, HV* stash)
+.Ve
+.PP
+where the first argument, an \f(CW\*(C`SV*\*(C'\fR, must be a reference, and the second
+argument is a stash.  The returned \f(CW\*(C`SV*\*(C'\fR can now be used in the same way
+as any other SV.
+.PP
+For more information on references and blessings, consult perlref.
+.SS "I/O Handles"
+.IX Subsection "I/O Handles"
+Like AVs and HVs, IO objects are another type of non-scalar SV which
+may contain input and output PerlIO objects or a \f(CW\*(C`DIR *\*(C'\fR
+from \fBopendir()\fR.
+.PP
+You can create a new IO object:
+.PP
+.Vb 1
+\&    IO*  newIO();
+.Ve
+.PP
+Unlike other SVs, a new IO object is automatically blessed into the
+IO::File class.
+.PP
+The IO object contains an input and output PerlIO handle:
+.PP
+.Vb 2
+\&  PerlIO *IoIFP(IO *io);
+\&  PerlIO *IoOFP(IO *io);
+.Ve
+.PP
+Typically if the IO object has been opened on a file, the input handle
+is always present, but the output handle is only present if the file
+is open for output.  For a file, if both are present they will be the
+same PerlIO object.
+.PP
+Distinct input and output PerlIO objects are created for sockets and
+character devices.
+.PP
+The IO object also contains other data associated with Perl I/O
+handles:
+.PP
+.Vb 12
+\&  IV IoLINES(io);                /* $. */
+\&  IV IoPAGE(io);                 /* $% */
+\&  IV IoPAGE_LEN(io);             /* $= */
+\&  IV IoLINES_LEFT(io);           /* $\- */
+\&  char *IoTOP_NAME(io);          /* $^ */
+\&  GV *IoTOP_GV(io);              /* $^ */
+\&  char *IoFMT_NAME(io);          /* $~ */
+\&  GV *IoFMT_GV(io);              /* $~ */
+\&  char *IoBOTTOM_NAME(io);
+\&  GV *IoBOTTOM_GV(io);
+\&  char IoTYPE(io);
+\&  U8 IoFLAGS(io);
+\&
+\& =for apidoc_sections $io_scn, $formats_section
+\&=for apidoc_section $reports
+\&=for apidoc Amh|IV|IoLINES|IO *io
+\&=for apidoc Amh|IV|IoPAGE|IO *io
+\&=for apidoc Amh|IV|IoPAGE_LEN|IO *io
+\&=for apidoc Amh|IV|IoLINES_LEFT|IO *io
+\&=for apidoc Amh|char *|IoTOP_NAME|IO *io
+\&=for apidoc Amh|GV *|IoTOP_GV|IO *io
+\&=for apidoc Amh|char *|IoFMT_NAME|IO *io
+\&=for apidoc Amh|GV *|IoFMT_GV|IO *io
+\&=for apidoc Amh|char *|IoBOTTOM_NAME|IO *io
+\&=for apidoc Amh|GV *|IoBOTTOM_GV|IO *io
+\&=for apidoc_section $io
+\&=for apidoc Amh|char|IoTYPE|IO *io
+\&=for apidoc Amh|U8|IoFLAGS|IO *io
+.Ve
+.PP
+Most of these are involved with formats.
+.PP
+\&\fBIoFLAGs()\fR may contain a combination of flags, the most interesting of
+which are \f(CW\*(C`IOf_FLUSH\*(C'\fR (\f(CW$|\fR) for autoflush and \f(CW\*(C`IOf_UNTAINT\*(C'\fR,
+settable with IO::Handle's \fBuntaint()\fR method.
+.PP
+The IO object may also contains a directory handle:
+.PP
+.Vb 1
+\&  DIR *IoDIRP(io);
+.Ve
+.PP
+suitable for use with \fBPerlDir_read()\fR etc.
+.PP
+All of these accessors macros are lvalues, there are no distinct
+\&\f(CW_set()\fR macros to modify the members of the IO object.
+.SS "Double-Typed SVs"
+.IX Subsection "Double-Typed SVs"
+Scalar variables normally contain only one type of value, an integer,
+double, pointer, or reference.  Perl will automatically convert the
+actual scalar data from the stored type into the requested type.
+.PP
+Some scalar variables contain more than one type of scalar data.  For
+example, the variable \f(CW$!\fR contains either the numeric value of \f(CW\*(C`errno\*(C'\fR
+or its string equivalent from either \f(CW\*(C`strerror\*(C'\fR or \f(CW\*(C`sys_errlist[]\*(C'\fR.
+.PP
+To force multiple data values into an SV, you must do two things: use the
+\&\f(CW\*(C`sv_set*v\*(C'\fR routines to add the additional scalar type, then set a flag
+so that Perl will believe it contains more than one type of data.  The
+four macros to set the flags are:
+.PP
+.Vb 4
+\&        SvIOK_on
+\&        SvNOK_on
+\&        SvPOK_on
+\&        SvROK_on
+.Ve
+.PP
+The particular macro you must use depends on which \f(CW\*(C`sv_set*v\*(C'\fR routine
+you called first.  This is because every \f(CW\*(C`sv_set*v\*(C'\fR routine turns on
+only the bit for the particular type of data being set, and turns off
+all the rest.
+.PP
+For example, to create a new Perl variable called "dberror" that contains
+both the numeric and descriptive string error values, you could use the
+following code:
+.PP
+.Vb 2
+\&    extern int  dberror;
+\&    extern char *dberror_list;
+\&
+\&    SV* sv = get_sv("dberror", GV_ADD);
+\&    sv_setiv(sv, (IV) dberror);
+\&    sv_setpv(sv, dberror_list[dberror]);
+\&    SvIOK_on(sv);
+.Ve
+.PP
+If the order of \f(CW\*(C`sv_setiv\*(C'\fR and \f(CW\*(C`sv_setpv\*(C'\fR had been reversed, then the
+macro \f(CW\*(C`SvPOK_on\*(C'\fR would need to be called instead of \f(CW\*(C`SvIOK_on\*(C'\fR.
+.SS "Read-Only Values"
+.IX Subsection "Read-Only Values"
+In Perl 5.16 and earlier, copy-on-write (see the next section) shared a
+flag bit with read-only scalars.  So the only way to test whether
+\&\f(CW\*(C`sv_setsv\*(C'\fR, etc., will raise a "Modification of a read-only value" error
+in those versions is:
+.PP
+.Vb 1
+\&    SvREADONLY(sv) && !SvIsCOW(sv)
+.Ve
+.PP
+Under Perl 5.18 and later, SvREADONLY only applies to read-only variables,
+and, under 5.20, copy-on-write scalars can also be read-only, so the above
+check is incorrect.  You just want:
+.PP
+.Vb 1
+\&    SvREADONLY(sv)
+.Ve
+.PP
+If you need to do this check often, define your own macro like this:
+.PP
+.Vb 5
+\&    #if PERL_VERSION >= 18
+\&    # define SvTRULYREADONLY(sv) SvREADONLY(sv)
+\&    #else
+\&    # define SvTRULYREADONLY(sv) (SvREADONLY(sv) && !SvIsCOW(sv))
+\&    #endif
+.Ve
+.SS "Copy on Write"
+.IX Subsection "Copy on Write"
+Perl implements a copy-on-write (COW) mechanism for scalars, in which
+string copies are not immediately made when requested, but are deferred
+until made necessary by one or the other scalar changing.  This is mostly
+transparent, but one must take care not to modify string buffers that are
+shared by multiple SVs.
+.PP
+You can test whether an SV is using copy-on-write with \f(CWSvIsCOW(sv)\fR.
+.PP
+You can force an SV to make its own copy of its string buffer by calling \f(CWsv_force_normal(sv)\fR or SvPV_force_nolen(sv).
+.PP
+If you want to make the SV drop its string buffer, use
+\&\f(CW\*(C`sv_force_normal_flags(sv, SV_COW_DROP_PV)\*(C'\fR or simply
+\&\f(CW\*(C`sv_setsv(sv, NULL)\*(C'\fR.
+.PP
+All of these functions will croak on read-only scalars (see the previous
+section for more on those).
+.PP
+To test that your code is behaving correctly and not modifying COW buffers,
+on systems that support \fBmmap\fR\|(2) (i.e., Unix) you can configure perl with
+\&\f(CW\*(C`\-Accflags=\-DPERL_DEBUG_READONLY_COW\*(C'\fR and it will turn buffer violations
+into crashes.  You will find it to be marvellously slow, so you may want to
+skip perl's own tests.
+.SS "Magic Variables"
+.IX Subsection "Magic Variables"
+[This section still under construction.  Ignore everything here.  Post no
+bills.  Everything not permitted is forbidden.]
+.PP
+Any SV may be magical, that is, it has special features that a normal
+SV does not have.  These features are stored in the SV structure in a
+linked list of \f(CW\*(C`struct magic\*(C'\fR's, typedef'ed to \f(CW\*(C`MAGIC\*(C'\fR.
+.PP
+.Vb 10
+\&    struct magic {
+\&        MAGIC*      mg_moremagic;
+\&        MGVTBL*     mg_virtual;
+\&        U16         mg_private;
+\&        char        mg_type;
+\&        U8          mg_flags;
+\&        I32         mg_len;
+\&        SV*         mg_obj;
+\&        char*       mg_ptr;
+\&    };
+.Ve
+.PP
+Note this is current as of patchlevel 0, and could change at any time.
+.SS "Assigning Magic"
+.IX Subsection "Assigning Magic"
+Perl adds magic to an SV using the sv_magic function:
+.PP
+.Vb 1
+\&  void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
+.Ve
+.PP
+The \f(CW\*(C`sv\*(C'\fR argument is a pointer to the SV that is to acquire a new magical
+feature.
+.PP
+If \f(CW\*(C`sv\*(C'\fR is not already magical, Perl uses the \f(CW\*(C`SvUPGRADE\*(C'\fR macro to
+convert \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR.
+Perl then continues by adding new magic
+to the beginning of the linked list of magical features.  Any prior entry
+of the same type of magic is deleted.  Note that this can be overridden,
+and multiple instances of the same type of magic can be associated with an
+SV.
+.PP
+The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments are used to associate a string with
+the magic, typically the name of a variable.  \f(CW\*(C`namlen\*(C'\fR is stored in the
+\&\f(CW\*(C`mg_len\*(C'\fR field and if \f(CW\*(C`name\*(C'\fR is non-null then either a \f(CW\*(C`savepvn\*(C'\fR copy of
+\&\f(CW\*(C`name\*(C'\fR or \f(CW\*(C`name\*(C'\fR itself is stored in the \f(CW\*(C`mg_ptr\*(C'\fR field, depending on
+whether \f(CW\*(C`namlen\*(C'\fR is greater than zero or equal to zero respectively.  As a
+special case, if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed
+to contain an \f(CW\*(C`SV*\*(C'\fR and is stored as-is with its REFCNT incremented.
+.PP
+The sv_magic function uses \f(CW\*(C`how\*(C'\fR to determine which, if any, predefined
+"Magic Virtual Table" should be assigned to the \f(CW\*(C`mg_virtual\*(C'\fR field.
+See the "Magic Virtual Tables" section below.  The \f(CW\*(C`how\*(C'\fR argument is also
+stored in the \f(CW\*(C`mg_type\*(C'\fR field.  The value of
+\&\f(CW\*(C`how\*(C'\fR should be chosen from the set of macros
+\&\f(CW\*(C`PERL_MAGIC_foo\*(C'\fR found in \fIperl.h\fR.  Note that before
+these macros were added, Perl internals used to directly use character
+literals, so you may occasionally come across old code or documentation
+referring to 'U' magic rather than \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR for example.
+.PP
+The \f(CW\*(C`obj\*(C'\fR argument is stored in the \f(CW\*(C`mg_obj\*(C'\fR field of the \f(CW\*(C`MAGIC\*(C'\fR
+structure.  If it is not the same as the \f(CW\*(C`sv\*(C'\fR argument, the reference
+count of the \f(CW\*(C`obj\*(C'\fR object is incremented.  If it is the same, or if
+the \f(CW\*(C`how\*(C'\fR argument is \f(CW\*(C`PERL_MAGIC_arylen\*(C'\fR, \f(CW\*(C`PERL_MAGIC_regdatum\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_regdata\*(C'\fR, or if it is a NULL pointer, then \f(CW\*(C`obj\*(C'\fR is merely
+stored, without the reference count being incremented.
+.PP
+See also \f(CW\*(C`sv_magicext\*(C'\fR in perlapi for a more flexible way to add magic
+to an SV.
+.PP
+There is also a function to add magic to an \f(CW\*(C`HV\*(C'\fR:
+.PP
+.Vb 1
+\&    void hv_magic(HV *hv, GV *gv, int how);
+.Ve
+.PP
+This simply calls \f(CW\*(C`sv_magic\*(C'\fR and coerces the \f(CW\*(C`gv\*(C'\fR argument into an \f(CW\*(C`SV\*(C'\fR.
+.PP
+To remove the magic from an SV, call the function sv_unmagic:
+.PP
+.Vb 1
+\&    int sv_unmagic(SV *sv, int type);
+.Ve
+.PP
+The \f(CW\*(C`type\*(C'\fR argument should be equal to the \f(CW\*(C`how\*(C'\fR value when the \f(CW\*(C`SV\*(C'\fR
+was initially made magical.
+.PP
+However, note that \f(CW\*(C`sv_unmagic\*(C'\fR removes all magic of a certain \f(CW\*(C`type\*(C'\fR from the
+\&\f(CW\*(C`SV\*(C'\fR.  If you want to remove only certain
+magic of a \f(CW\*(C`type\*(C'\fR based on the magic
+virtual table, use \f(CW\*(C`sv_unmagicext\*(C'\fR instead:
+.PP
+.Vb 1
+\&    int sv_unmagicext(SV *sv, int type, MGVTBL *vtbl);
+.Ve
+.SS "Magic Virtual Tables"
+.IX Subsection "Magic Virtual Tables"
+The \f(CW\*(C`mg_virtual\*(C'\fR field in the \f(CW\*(C`MAGIC\*(C'\fR structure is a pointer to an
+\&\f(CW\*(C`MGVTBL\*(C'\fR, which is a structure of function pointers and stands for
+"Magic Virtual Table" to handle the various operations that might be
+applied to that variable.
+.PP
+The \f(CW\*(C`MGVTBL\*(C'\fR has five (or sometimes eight) pointers to the following
+routine types:
+.PP
+.Vb 5
+\&    int  (*svt_get)  (pTHX_ SV* sv, MAGIC* mg);
+\&    int  (*svt_set)  (pTHX_ SV* sv, MAGIC* mg);
+\&    U32  (*svt_len)  (pTHX_ SV* sv, MAGIC* mg);
+\&    int  (*svt_clear)(pTHX_ SV* sv, MAGIC* mg);
+\&    int  (*svt_free) (pTHX_ SV* sv, MAGIC* mg);
+\&
+\&    int  (*svt_copy) (pTHX_ SV *sv, MAGIC* mg, SV *nsv,
+\&                                          const char *name, I32 namlen);
+\&    int  (*svt_dup)  (pTHX_ MAGIC *mg, CLONE_PARAMS *param);
+\&    int  (*svt_local)(pTHX_ SV *nsv, MAGIC *mg);
+.Ve
+.PP
+This MGVTBL structure is set at compile-time in \fIperl.h\fR and there are
+currently 32 types.  These different structures contain pointers to various
+routines that perform additional actions depending on which function is
+being called.
+.PP
+.Vb 8
+\&   Function pointer    Action taken
+\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-    \-\-\-\-\-\-\-\-\-\-\-\-
+\&   svt_get             Do something before the value of the SV is
+\&                       retrieved.
+\&   svt_set             Do something after the SV is assigned a value.
+\&   svt_len             Report on the SV\*(Aqs length.
+\&   svt_clear           Clear something the SV represents.
+\&   svt_free            Free any extra storage associated with the SV.
+\&
+\&   svt_copy            copy tied variable magic to a tied element
+\&   svt_dup             duplicate a magic structure during thread cloning
+\&   svt_local           copy magic to local value during \*(Aqlocal\*(Aq
+.Ve
+.PP
+For instance, the MGVTBL structure called \f(CW\*(C`vtbl_sv\*(C'\fR (which corresponds
+to an \f(CW\*(C`mg_type\*(C'\fR of \f(CW\*(C`PERL_MAGIC_sv\*(C'\fR) contains:
+.PP
+.Vb 1
+\&    { magic_get, magic_set, magic_len, 0, 0 }
+.Ve
+.PP
+Thus, when an SV is determined to be magical and of type \f(CW\*(C`PERL_MAGIC_sv\*(C'\fR,
+if a get operation is being performed, the routine \f(CW\*(C`magic_get\*(C'\fR is
+called.  All the various routines for the various magical types begin
+with \f(CW\*(C`magic_\*(C'\fR.  NOTE: the magic routines are not considered part of
+the Perl API, and may not be exported by the Perl library.
+.PP
+The last three slots are a recent addition, and for source code
+compatibility they are only checked for if one of the three flags
+\&\f(CW\*(C`MGf_COPY\*(C'\fR, \f(CW\*(C`MGf_DUP\*(C'\fR, or \f(CW\*(C`MGf_LOCAL\*(C'\fR is set in mg_flags.
+This means that most code can continue declaring
+a vtable as a 5\-element value.  These three are
+currently used exclusively by the threading code, and are highly subject
+to change.
+.PP
+The current kinds of Magic Virtual Tables are:
+.PP
+.Vb 10
+\& mg_type
+\& (old\-style char and macro)   MGVTBL         Type of magic
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-         \-\-\-\-\-\-\-\-\-\-\-\-\-
+\& \e0 PERL_MAGIC_sv             vtbl_sv        Special scalar variable
+\& #  PERL_MAGIC_arylen         vtbl_arylen    Array length ($#ary)
+\& %  PERL_MAGIC_rhash          (none)         Extra data for restricted
+\&                                             hashes
+\& *  PERL_MAGIC_debugvar       vtbl_debugvar  $DB::single, signal, trace
+\&                                             vars
+\& .  PERL_MAGIC_pos            vtbl_pos       pos() lvalue
+\& :  PERL_MAGIC_symtab         (none)         Extra data for symbol
+\&                                             tables
+\& <  PERL_MAGIC_backref        vtbl_backref   For weak ref data
+\& @  PERL_MAGIC_arylen_p       (none)         To move arylen out of XPVAV
+\& B  PERL_MAGIC_bm             vtbl_regexp    Boyer\-Moore
+\&                                             (fast string search)
+\& c  PERL_MAGIC_overload_table vtbl_ovrld     Holds overload table
+\&                                             (AMT) on stash
+\& D  PERL_MAGIC_regdata        vtbl_regdata   Regex match position data
+\&                                             (@+ and @\- vars)
+\& d  PERL_MAGIC_regdatum       vtbl_regdatum  Regex match position data
+\&                                             element
+\& E  PERL_MAGIC_env            vtbl_env       %ENV hash
+\& e  PERL_MAGIC_envelem        vtbl_envelem   %ENV hash element
+\& f  PERL_MAGIC_fm             vtbl_regexp    Formline
+\&                                             (\*(Aqcompiled\*(Aq format)
+\& g  PERL_MAGIC_regex_global   vtbl_mglob     m//g target
+\& H  PERL_MAGIC_hints          vtbl_hints     %^H hash
+\& h  PERL_MAGIC_hintselem      vtbl_hintselem %^H hash element
+\& I  PERL_MAGIC_isa            vtbl_isa       @ISA array
+\& i  PERL_MAGIC_isaelem        vtbl_isaelem   @ISA array element
+\& k  PERL_MAGIC_nkeys          vtbl_nkeys     scalar(keys()) lvalue
+\& L  PERL_MAGIC_dbfile         (none)         Debugger %_<filename
+\& l  PERL_MAGIC_dbline         vtbl_dbline    Debugger %_<filename
+\&                                             element
+\& N  PERL_MAGIC_shared         (none)         Shared between threads
+\& n  PERL_MAGIC_shared_scalar  (none)         Shared between threads
+\& o  PERL_MAGIC_collxfrm       vtbl_collxfrm  Locale transformation
+\& P  PERL_MAGIC_tied           vtbl_pack      Tied array or hash
+\& p  PERL_MAGIC_tiedelem       vtbl_packelem  Tied array or hash element
+\& q  PERL_MAGIC_tiedscalar     vtbl_packelem  Tied scalar or handle
+\& r  PERL_MAGIC_qr             vtbl_regexp    Precompiled qr// regex
+\& S  PERL_MAGIC_sig            vtbl_sig       %SIG hash
+\& s  PERL_MAGIC_sigelem        vtbl_sigelem   %SIG hash element
+\& t  PERL_MAGIC_taint          vtbl_taint     Taintedness
+\& U  PERL_MAGIC_uvar           vtbl_uvar      Available for use by
+\&                                             extensions
+\& u  PERL_MAGIC_uvar_elem      (none)         Reserved for use by
+\&                                             extensions
+\& V  PERL_MAGIC_vstring        (none)         SV was vstring literal
+\& v  PERL_MAGIC_vec            vtbl_vec       vec() lvalue
+\& w  PERL_MAGIC_utf8           vtbl_utf8      Cached UTF\-8 information
+\& X  PERL_MAGIC_destruct       vtbl_destruct  destruct callback
+\& x  PERL_MAGIC_substr         vtbl_substr    substr() lvalue
+\& Y  PERL_MAGIC_nonelem        vtbl_nonelem   Array element that does not
+\&                                             exist
+\& y  PERL_MAGIC_defelem        vtbl_defelem   Shadow "foreach" iterator
+\&                                             variable / smart parameter
+\&                                             vivification
+\& Z  PERL_MAGIC_hook           vtbl_hook      %{^HOOK} hash
+\& z  PERL_MAGIC_hookelem       vtbl_hookelem  %{^HOOK} hash element
+\& \e  PERL_MAGIC_lvref          vtbl_lvref     Lvalue reference
+\&                                             constructor
+\& ]  PERL_MAGIC_checkcall      vtbl_checkcall Inlining/mutation of call
+\&                                             to this CV
+\& ^  PERL_MAGIC_extvalue       (none)         Value magic available for
+\&                                             use by extensions
+\& ~  PERL_MAGIC_ext            (none)         Variable magic available
+\&                                             for use by extensions
+.Ve
+.PP
+When an uppercase and lowercase letter both exist in the table, then the
+uppercase letter is typically used to represent some kind of composite type
+(a list or a hash), and the lowercase letter is used to represent an element
+of that composite type.  Some internals code makes use of this case
+relationship.  However, 'v' and 'V' (vec and v\-string) are in no way related.
+.PP
+The \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR, \f(CW\*(C`PERL_MAGIC_extvalue\*(C'\fR and \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic types
+are defined specifically for use by extensions and will not be used by perl
+itself.  Extensions can use \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR or \f(CW\*(C`PERL_MAGIC_extvalue\*(C'\fR magic to
+\&'attach' private information to variables (typically objects).  This is
+especially useful because there is no way for normal perl code to corrupt this
+private information (unlike using extra elements of a hash object).
+\&\f(CW\*(C`PERL_MAGIC_extvalue\*(C'\fR is value magic (unlike \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR and
+\&\f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR) meaning that on localization the new value will not be
+magical.
+.PP
+Similarly, \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic can be used much like \fBtie()\fR to call a
+C function any time a scalar's value is used or changed.  The \f(CW\*(C`MAGIC\*(C'\fR's
+\&\f(CW\*(C`mg_ptr\*(C'\fR field points to a \f(CW\*(C`ufuncs\*(C'\fR structure:
+.PP
+.Vb 5
+\&    struct ufuncs {
+\&        I32 (*uf_val)(pTHX_ IV, SV*);
+\&        I32 (*uf_set)(pTHX_ IV, SV*);
+\&        IV uf_index;
+\&    };
+.Ve
+.PP
+When the SV is read from or written to, the \f(CW\*(C`uf_val\*(C'\fR or \f(CW\*(C`uf_set\*(C'\fR
+function will be called with \f(CW\*(C`uf_index\*(C'\fR as the first arg and a pointer to
+the SV as the second.  A simple example of how to add \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR
+magic is shown below.  Note that the ufuncs structure is copied by
+sv_magic, so you can safely allocate it on the stack.
+.PP
+.Vb 10
+\&    void
+\&    Umagic(sv)
+\&        SV *sv;
+\&    PREINIT:
+\&        struct ufuncs uf;
+\&    CODE:
+\&        uf.uf_val   = &my_get_fn;
+\&        uf.uf_set   = &my_set_fn;
+\&        uf.uf_index = 0;
+\&        sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));
+.Ve
+.PP
+Attaching \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR to arrays is permissible but has no effect.
+.PP
+For hashes there is a specialized hook that gives control over hash
+keys (but not values).  This hook calls \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR 'get' magic
+if the "set" function in the \f(CW\*(C`ufuncs\*(C'\fR structure is NULL.  The hook
+is activated whenever the hash is accessed with a key specified as
+an \f(CW\*(C`SV\*(C'\fR through the functions \f(CW\*(C`hv_store_ent\*(C'\fR, \f(CW\*(C`hv_fetch_ent\*(C'\fR,
+\&\f(CW\*(C`hv_delete_ent\*(C'\fR, and \f(CW\*(C`hv_exists_ent\*(C'\fR.  Accessing the key as a string
+through the functions without the \f(CW\*(C`..._ent\*(C'\fR suffix circumvents the
+hook.  See "GUTS" in Hash::Util::FieldHash for a detailed description.
+.PP
+Note that because multiple extensions may be using \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR
+or \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic, it is important for extensions to take
+extra care to avoid conflict.  Typically only using the magic on
+objects blessed into the same class as the extension is sufficient.
+For \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR magic, it is usually a good idea to define an
+\&\f(CW\*(C`MGVTBL\*(C'\fR, even if all its fields will be \f(CW0\fR, so that individual
+\&\f(CW\*(C`MAGIC\*(C'\fR pointers can be identified as a particular kind of magic
+using their magic virtual table.  \f(CW\*(C`mg_findext\*(C'\fR provides an easy way
+to do that:
+.PP
+.Vb 1
+\&    STATIC MGVTBL my_vtbl = { 0, 0, 0, 0, 0, 0, 0, 0 };
+\&
+\&    MAGIC *mg;
+\&    if ((mg = mg_findext(sv, PERL_MAGIC_ext, &my_vtbl))) {
+\&        /* this is really ours, not another module\*(Aqs PERL_MAGIC_ext */
+\&        my_priv_data_t *priv = (my_priv_data_t *)mg\->mg_ptr;
+\&        ...
+\&    }
+.Ve
+.PP
+Also note that the \f(CW\*(C`sv_set*()\*(C'\fR and \f(CW\*(C`sv_cat*()\*(C'\fR functions described
+earlier do \fBnot\fR invoke 'set' magic on their targets.  This must
+be done by the user either by calling the \f(CWSvSETMAGIC()\fR macro after
+calling these functions, or by using one of the \f(CW\*(C`sv_set*_mg()\*(C'\fR or
+\&\f(CW\*(C`sv_cat*_mg()\*(C'\fR functions.  Similarly, generic C code must call the
+\&\f(CWSvGETMAGIC()\fR macro to invoke any 'get' magic if they use an SV
+obtained from external sources in functions that don't handle magic.
+See perlapi for a description of these functions.
+For example, calls to the \f(CW\*(C`sv_cat*()\*(C'\fR functions typically need to be
+followed by \f(CWSvSETMAGIC()\fR, but they don't need a prior \f(CWSvGETMAGIC()\fR
+since their implementation handles 'get' magic.
+.SS "Finding Magic"
+.IX Subsection "Finding Magic"
+.Vb 2
+\&    MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that
+\&                                       * type */
+.Ve
+.PP
+This routine returns a pointer to a \f(CW\*(C`MAGIC\*(C'\fR structure stored in the SV.
+If the SV does not have that magical
+feature, \f(CW\*(C`NULL\*(C'\fR is returned.  If the
+SV has multiple instances of that magical feature, the first one will be
+returned.  \f(CW\*(C`mg_findext\*(C'\fR can be used
+to find a \f(CW\*(C`MAGIC\*(C'\fR structure of an SV
+based on both its magic type and its magic virtual table:
+.PP
+.Vb 1
+\&    MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl);
+.Ve
+.PP
+Also, if the SV passed to \f(CW\*(C`mg_find\*(C'\fR or \f(CW\*(C`mg_findext\*(C'\fR is not of type
+SVt_PVMG, Perl may core dump.
+.PP
+.Vb 1
+\&    int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);
+.Ve
+.PP
+This routine checks to see what types of magic \f(CW\*(C`sv\*(C'\fR has.  If the mg_type
+field is an uppercase letter, then the mg_obj is copied to \f(CW\*(C`nsv\*(C'\fR, but
+the mg_type field is changed to be the lowercase letter.
+.SS "Understanding the Magic of Tied Hashes and Arrays"
+.IX Subsection "Understanding the Magic of Tied Hashes and Arrays"
+Tied hashes and arrays are magical beasts of the \f(CW\*(C`PERL_MAGIC_tied\*(C'\fR
+magic type.
+.PP
+WARNING: As of the 5.004 release, proper usage of the array and hash
+access functions requires understanding a few caveats.  Some
+of these caveats are actually considered bugs in the API, to be fixed
+in later releases, and are bracketed with [MAYCHANGE] below.  If
+you find yourself actually applying such information in this section, be
+aware that the behavior may change in the future, umm, without warning.
+.PP
+The perl tie function associates a variable with an object that implements
+the various GET, SET, etc methods.  To perform the equivalent of the perl
+tie function from an XSUB, you must mimic this behaviour.  The code below
+carries out the necessary steps \-\- firstly it creates a new hash, and then
+creates a second hash which it blesses into the class which will implement
+the tie methods.  Lastly it ties the two hashes together, and returns a
+reference to the new tied hash.  Note that the code below does NOT call the
+TIEHASH method in the MyTie class \-
+see "Calling Perl Routines from within C Programs" for details on how
+to do this.
+.PP
+.Vb 10
+\&    SV*
+\&    mytie()
+\&    PREINIT:
+\&        HV *hash;
+\&        HV *stash;
+\&        SV *tie;
+\&    CODE:
+\&        hash = newHV();
+\&        tie = newRV_noinc((SV*)newHV());
+\&        stash = gv_stashpv("MyTie", GV_ADD);
+\&        sv_bless(tie, stash);
+\&        hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
+\&        RETVAL = newRV_noinc(hash);
+\&    OUTPUT:
+\&        RETVAL
+.Ve
+.PP
+The \f(CW\*(C`av_store\*(C'\fR function, when given a tied array argument, merely
+copies the magic of the array onto the value to be "stored", using
+\&\f(CW\*(C`mg_copy\*(C'\fR.  It may also return NULL, indicating that the value did not
+actually need to be stored in the array.  [MAYCHANGE] After a call to
+\&\f(CW\*(C`av_store\*(C'\fR on a tied array, the caller will usually need to call
+\&\f(CWmg_set(val)\fR to actually invoke the perl level "STORE" method on the
+TIEARRAY object.  If \f(CW\*(C`av_store\*(C'\fR did return NULL, a call to
+\&\f(CWSvREFCNT_dec(val)\fR will also be usually necessary to avoid a memory
+leak. [/MAYCHANGE]
+.PP
+The previous paragraph is applicable verbatim to tied hash access using the
+\&\f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_store_ent\*(C'\fR functions as well.
+.PP
+\&\f(CW\*(C`av_fetch\*(C'\fR and the corresponding hash functions \f(CW\*(C`hv_fetch\*(C'\fR and
+\&\f(CW\*(C`hv_fetch_ent\*(C'\fR actually return an undefined mortal value whose magic
+has been initialized using \f(CW\*(C`mg_copy\*(C'\fR.  Note the value so returned does not
+need to be deallocated, as it is already mortal.  [MAYCHANGE] But you will
+need to call \f(CWmg_get()\fR on the returned value in order to actually invoke
+the perl level "FETCH" method on the underlying TIE object.  Similarly,
+you may also call \f(CWmg_set()\fR on the return value after possibly assigning
+a suitable value to it using \f(CW\*(C`sv_setsv\*(C'\fR,  which will invoke the "STORE"
+method on the TIE object. [/MAYCHANGE]
+.PP
+[MAYCHANGE]
+In other words, the array or hash fetch/store functions don't really
+fetch and store actual values in the case of tied arrays and hashes.  They
+merely call \f(CW\*(C`mg_copy\*(C'\fR to attach magic to the values that were meant to be
+"stored" or "fetched".  Later calls to \f(CW\*(C`mg_get\*(C'\fR and \f(CW\*(C`mg_set\*(C'\fR actually
+do the job of invoking the TIE methods on the underlying objects.  Thus
+the magic mechanism currently implements a kind of lazy access to arrays
+and hashes.
+.PP
+Currently (as of perl version 5.004), use of the hash and array access
+functions requires the user to be aware of whether they are operating on
+"normal" hashes and arrays, or on their tied variants.  The API may be
+changed to provide more transparent access to both tied and normal data
+types in future versions.
+[/MAYCHANGE]
+.PP
+You would do well to understand that the TIEARRAY and TIEHASH interfaces
+are mere sugar to invoke some perl method calls while using the uniform hash
+and array syntax.  The use of this sugar imposes some overhead (typically
+about two to four extra opcodes per FETCH/STORE operation, in addition to
+the creation of all the mortal variables required to invoke the methods).
+This overhead will be comparatively small if the TIE methods are themselves
+substantial, but if they are only a few statements long, the overhead
+will not be insignificant.
+.SS "Localizing changes"
+.IX Subsection "Localizing changes"
+Perl has a very handy construction
+.PP
+.Vb 4
+\&  {
+\&    local $var = 2;
+\&    ...
+\&  }
+.Ve
+.PP
+This construction is \fIapproximately\fR equivalent to
+.PP
+.Vb 6
+\&  {
+\&    my $oldvar = $var;
+\&    $var = 2;
+\&    ...
+\&    $var = $oldvar;
+\&  }
+.Ve
+.PP
+The biggest difference is that the first construction would
+reinstate the initial value of \f(CW$var\fR, irrespective of how control exits
+the block: \f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`die\*(C'\fR/\f(CW\*(C`eval\*(C'\fR, etc.  It is a little bit
+more efficient as well.
+.PP
+There is a way to achieve a similar task from C via Perl API: create a
+\&\fIpseudo-block\fR, and arrange for some changes to be automatically
+undone at the end of it, either explicit, or via a non-local exit (via
+\&\fBdie()\fR).  A \fIblock\fR\-like construct is created by a pair of
+\&\f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR macros (see "Returning a Scalar" in perlcall).
+Such a construct may be created specially for some important localized
+task, or an existing one (like boundaries of enclosing Perl
+subroutine/block, or an existing pair for freeing TMPs) may be
+used.  (In the second case the overhead of additional localization must
+be almost negligible.)  Note that any XSUB is automatically enclosed in
+an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair.
+.PP
+Inside such a \fIpseudo-block\fR the following service is available:
+.ie n .IP """SAVEINT(int i)""" 4
+.el .IP "\f(CWSAVEINT(int i)\fR" 4
+.IX Item "SAVEINT(int i)"
+.PD 0
+.ie n .IP """SAVEIV(IV i)""" 4
+.el .IP "\f(CWSAVEIV(IV i)\fR" 4
+.IX Item "SAVEIV(IV i)"
+.ie n .IP """SAVEI32(I32 i)""" 4
+.el .IP "\f(CWSAVEI32(I32 i)\fR" 4
+.IX Item "SAVEI32(I32 i)"
+.ie n .IP """SAVELONG(long i)""" 4
+.el .IP "\f(CWSAVELONG(long i)\fR" 4
+.IX Item "SAVELONG(long i)"
+.ie n .IP """SAVEI8(I8 i)""" 4
+.el .IP "\f(CWSAVEI8(I8 i)\fR" 4
+.IX Item "SAVEI8(I8 i)"
+.ie n .IP """SAVEI16(I16 i)""" 4
+.el .IP "\f(CWSAVEI16(I16 i)\fR" 4
+.IX Item "SAVEI16(I16 i)"
+.ie n .IP """SAVEBOOL(int i)""" 4
+.el .IP "\f(CWSAVEBOOL(int i)\fR" 4
+.IX Item "SAVEBOOL(int i)"
+.ie n .IP """SAVESTRLEN(STRLEN i)""" 4
+.el .IP "\f(CWSAVESTRLEN(STRLEN i)\fR" 4
+.IX Item "SAVESTRLEN(STRLEN i)"
+.PD
+These macros arrange things to restore the value of integer variable
+\&\f(CW\*(C`i\*(C'\fR at the end of the enclosing \fIpseudo-block\fR.
+.ie n .IP SAVESPTR(s) 4
+.el .IP \f(CWSAVESPTR(s)\fR 4
+.IX Item "SAVESPTR(s)"
+.PD 0
+.ie n .IP SAVEPPTR(p) 4
+.el .IP \f(CWSAVEPPTR(p)\fR 4
+.IX Item "SAVEPPTR(p)"
+.PD
+These macros arrange things to restore the value of pointers \f(CW\*(C`s\*(C'\fR and
+\&\f(CW\*(C`p\*(C'\fR.  \f(CW\*(C`s\*(C'\fR must be a pointer of a type which survives conversion to
+\&\f(CW\*(C`SV*\*(C'\fR and back, \f(CW\*(C`p\*(C'\fR should be able to survive conversion to \f(CW\*(C`char*\*(C'\fR
+and back.
+.ie n .IP """SAVERCPV(char **ppv)""" 4
+.el .IP "\f(CWSAVERCPV(char **ppv)\fR" 4
+.IX Item "SAVERCPV(char **ppv)"
+This macro arranges to restore the value of a \f(CW\*(C`char *\*(C'\fR variable which
+was allocated with a call to \f(CWrcpv_new()\fR to its previous state when
+the current pseudo block is completed. The pointer stored in \f(CW*ppv\fR at
+the time of the call will be refcount incremented and stored on the save
+stack. Later when the current \fIpseudo-block\fR is completed the value
+stored in \f(CW*ppv\fR will be refcount decremented, and the previous value
+restored from the savestack which will also be refcount decremented.
+.Sp
+This is the \f(CW\*(C`RCPV\*(C'\fR equivalent of \f(CWSAVEGENERICSV()\fR.
+.ie n .IP """SAVEGENERICSV(SV **psv)""" 4
+.el .IP "\f(CWSAVEGENERICSV(SV **psv)\fR" 4
+.IX Item "SAVEGENERICSV(SV **psv)"
+This macro arranges to restore the value of a \f(CW\*(C`SV *\*(C'\fR variable to its
+previous state when the current pseudo block is completed. The pointer
+stored in \f(CW*psv\fR at the time of the call will be refcount incremented
+and stored on the save stack. Later when the current \fIpseudo-block\fR is
+completed the value stored in \f(CW*ppv\fR will be refcount decremented, and
+the previous value restored from the savestack which will also be refcount
+decremented. This the C equivalent of \f(CW\*(C`local $sv\*(C'\fR.
+.ie n .IP """SAVEFREESV(SV *sv)""" 4
+.el .IP "\f(CWSAVEFREESV(SV *sv)\fR" 4
+.IX Item "SAVEFREESV(SV *sv)"
+The refcount of \f(CW\*(C`sv\*(C'\fR will be decremented at the end of
+\&\fIpseudo-block\fR.  This is similar to \f(CW\*(C`sv_2mortal\*(C'\fR in that it is also a
+mechanism for doing a delayed \f(CW\*(C`SvREFCNT_dec\*(C'\fR.  However, while \f(CW\*(C`sv_2mortal\*(C'\fR
+extends the lifetime of \f(CW\*(C`sv\*(C'\fR until the beginning of the next statement,
+\&\f(CW\*(C`SAVEFREESV\*(C'\fR extends it until the end of the enclosing scope.  These
+lifetimes can be wildly different.
+.Sp
+Also compare \f(CW\*(C`SAVEMORTALIZESV\*(C'\fR.
+.ie n .IP """SAVEMORTALIZESV(SV *sv)""" 4
+.el .IP "\f(CWSAVEMORTALIZESV(SV *sv)\fR" 4
+.IX Item "SAVEMORTALIZESV(SV *sv)"
+Just like \f(CW\*(C`SAVEFREESV\*(C'\fR, but mortalizes \f(CW\*(C`sv\*(C'\fR at the end of the current
+scope instead of decrementing its reference count.  This usually has the
+effect of keeping \f(CW\*(C`sv\*(C'\fR alive until the statement that called the currently
+live scope has finished executing.
+.ie n .IP """SAVEFREEOP(OP *op)""" 4
+.el .IP "\f(CWSAVEFREEOP(OP *op)\fR" 4
+.IX Item "SAVEFREEOP(OP *op)"
+The \f(CW\*(C`OP *\*(C'\fR is \f(CWop_free()\fRed at the end of \fIpseudo-block\fR.
+.ie n .IP SAVEFREEPV(p) 4
+.el .IP \f(CWSAVEFREEPV(p)\fR 4
+.IX Item "SAVEFREEPV(p)"
+The chunk of memory which is pointed to by \f(CW\*(C`p\*(C'\fR is \f(CWSafefree()\fRed at the
+end of the current \fIpseudo-block\fR.
+.ie n .IP """SAVEFREERCPV(char *pv)""" 4
+.el .IP "\f(CWSAVEFREERCPV(char *pv)\fR" 4
+.IX Item "SAVEFREERCPV(char *pv)"
+Ensures that a \f(CW\*(C`char *\*(C'\fR which was created by a call to \f(CWrcpv_new()\fR is
+\&\f(CWrcpv_free()\fRed at the end of the current \fIpseudo-block\fR.
+.Sp
+This is the RCPV equivalent of \f(CWSAVEFREESV()\fR.
+.ie n .IP """SAVECLEARSV(SV *sv)""" 4
+.el .IP "\f(CWSAVECLEARSV(SV *sv)\fR" 4
+.IX Item "SAVECLEARSV(SV *sv)"
+Clears a slot in the current scratchpad which corresponds to \f(CW\*(C`sv\*(C'\fR at
+the end of \fIpseudo-block\fR.
+.ie n .IP """SAVEDELETE(HV *hv, char *key, I32 length)""" 4
+.el .IP "\f(CWSAVEDELETE(HV *hv, char *key, I32 length)\fR" 4
+.IX Item "SAVEDELETE(HV *hv, char *key, I32 length)"
+The key \f(CW\*(C`key\*(C'\fR of \f(CW\*(C`hv\*(C'\fR is deleted at the end of \fIpseudo-block\fR.  The
+string pointed to by \f(CW\*(C`key\*(C'\fR is \fBSafefree()\fRed.  If one has a \fIkey\fR in
+short-lived storage, the corresponding string may be reallocated like
+this:
+.Sp
+.Vb 1
+\&  SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
+.Ve
+.ie n .IP """SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)""" 4
+.el .IP "\f(CWSAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)\fR" 4
+.IX Item "SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)"
+At the end of \fIpseudo-block\fR the function \f(CW\*(C`f\*(C'\fR is called with the
+only argument \f(CW\*(C`p\*(C'\fR which may be NULL.
+.ie n .IP """SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)""" 4
+.el .IP "\f(CWSAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)\fR" 4
+.IX Item "SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)"
+At the end of \fIpseudo-block\fR the function \f(CW\*(C`f\*(C'\fR is called with the
+implicit context argument (if any), and \f(CW\*(C`p\*(C'\fR which may be NULL.
+.Sp
+Note the \fIend of the current pseudo-block\fR may occur much later than
+the \fIend of the current statement\fR. You may wish to look at the
+\&\f(CWMORTALDESTRUCTOR_X()\fR macro instead.
+.ie n .IP """MORTALSVFUNC_X(SVFUNC_t f, SV *sv)""" 4
+.el .IP "\f(CWMORTALSVFUNC_X(SVFUNC_t f, SV *sv)\fR" 4
+.IX Item "MORTALSVFUNC_X(SVFUNC_t f, SV *sv)"
+At the end of \fIthe current statement\fR the function \f(CW\*(C`f\*(C'\fR is called with
+the implicit context argument (if any), and \f(CW\*(C`sv\*(C'\fR which may be NULL.
+.Sp
+Be aware that the parameter argument to the destructor function differs
+from the related \f(CWSAVEDESTRUCTOR_X()\fR in that it MUST be either NULL or
+an \f(CW\*(C`SV*\*(C'\fR.
+.Sp
+Note the \fIend of the current statement\fR may occur much before the
+the \fIend of the current pseudo-block\fR.  You may wish to look at the
+\&\f(CWSAVEDESTRUCTOR_X()\fR macro instead.
+.ie n .IP """MORTALDESTRUCTOR_SV(SV *coderef, SV *args)""" 4
+.el .IP "\f(CWMORTALDESTRUCTOR_SV(SV *coderef, SV *args)\fR" 4
+.IX Item "MORTALDESTRUCTOR_SV(SV *coderef, SV *args)"
+At the end of \fIthe current statement\fR the Perl function contained in
+\&\f(CW\*(C`coderef\*(C'\fR is called with the arguments provided (if any) in \f(CW\*(C`args\*(C'\fR.
+See the documentation for \f(CWmortal_destructor_sv()\fR for details on
+the \f(CW\*(C`args\*(C'\fR parameter is handled.
+.Sp
+Note the \fIend of the current statement\fR may occur much before the
+the \fIend of the current pseudo-block\fR.  If you wish to call a perl
+function at the end of the current pseudo block you should use the
+\&\f(CWSAVEDESTRUCTOR_X()\fR API instead, which will require you create a
+C wrapper to call the Perl function.
+.ie n .IP SAVESTACK_POS() 4
+.el .IP \f(CWSAVESTACK_POS()\fR 4
+.IX Item "SAVESTACK_POS()"
+The current offset on the Perl internal stack (cf. \f(CW\*(C`SP\*(C'\fR) is restored
+at the end of \fIpseudo-block\fR.
+.PP
+The following API list contains functions, thus one needs to
+provide pointers to the modifiable data explicitly (either C pointers,
+or Perlish \f(CW\*(C`GV *\*(C'\fRs).  Where the above macros take \f(CW\*(C`int\*(C'\fR, a similar
+function takes \f(CW\*(C`int *\*(C'\fR.
+.PP
+Other macros above have functions implementing them, but its probably
+best to just use the macro, and not those or the ones below.
+.ie n .IP """SV* save_scalar(GV *gv)""" 4
+.el .IP "\f(CWSV* save_scalar(GV *gv)\fR" 4
+.IX Item "SV* save_scalar(GV *gv)"
+Equivalent to Perl code \f(CW\*(C`local $gv\*(C'\fR.
+.ie n .IP """AV* save_ary(GV *gv)""" 4
+.el .IP "\f(CWAV* save_ary(GV *gv)\fR" 4
+.IX Item "AV* save_ary(GV *gv)"
+.PD 0
+.ie n .IP """HV* save_hash(GV *gv)""" 4
+.el .IP "\f(CWHV* save_hash(GV *gv)\fR" 4
+.IX Item "HV* save_hash(GV *gv)"
+.PD
+Similar to \f(CW\*(C`save_scalar\*(C'\fR, but localize \f(CW@gv\fR and \f(CW%gv\fR.
+.ie n .IP """void save_item(SV *item)""" 4
+.el .IP "\f(CWvoid save_item(SV *item)\fR" 4
+.IX Item "void save_item(SV *item)"
+Duplicates the current value of \f(CW\*(C`SV\*(C'\fR. On the exit from the current
+\&\f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR \fIpseudo-block\fR the value of \f(CW\*(C`SV\*(C'\fR will be restored
+using the stored value.  It doesn't handle magic.  Use \f(CW\*(C`save_scalar\*(C'\fR if
+magic is affected.
+.ie n .IP """SV* save_svref(SV **sptr)""" 4
+.el .IP "\f(CWSV* save_svref(SV **sptr)\fR" 4
+.IX Item "SV* save_svref(SV **sptr)"
+Similar to \f(CW\*(C`save_scalar\*(C'\fR, but will reinstate an \f(CW\*(C`SV *\*(C'\fR.
+.ie n .IP """void save_aptr(AV **aptr)""" 4
+.el .IP "\f(CWvoid save_aptr(AV **aptr)\fR" 4
+.IX Item "void save_aptr(AV **aptr)"
+.PD 0
+.ie n .IP """void save_hptr(HV **hptr)""" 4
+.el .IP "\f(CWvoid save_hptr(HV **hptr)\fR" 4
+.IX Item "void save_hptr(HV **hptr)"
+.PD
+Similar to \f(CW\*(C`save_svref\*(C'\fR, but localize \f(CW\*(C`AV *\*(C'\fR and \f(CW\*(C`HV *\*(C'\fR.
+.PP
+The \f(CW\*(C`Alias\*(C'\fR module implements localization of the basic types within the
+\&\fIcaller's scope\fR.  People who are interested in how to localize things in
+the containing scope should take a look there too.
+.SH Subroutines
+.IX Header "Subroutines"
+.SS "XSUBs and the Argument Stack"
+.IX Subsection "XSUBs and the Argument Stack"
+The XSUB mechanism is a simple way for Perl programs to access C subroutines.
+An XSUB routine will have a stack that contains the arguments from the Perl
+program, and a way to map from the Perl data structures to a C equivalent.
+.PP
+The stack arguments are accessible through the \f(CWST(n)\fR macro, which returns
+the \f(CW\*(C`n\*(C'\fR'th stack argument.  Argument 0 is the first argument passed in the
+Perl subroutine call.  These arguments are \f(CW\*(C`SV*\*(C'\fR, and can be used anywhere
+an \f(CW\*(C`SV*\*(C'\fR is used.
+.PP
+Most of the time, output from the C routine can be handled through use of
+the RETVAL and OUTPUT directives.  However, there are some cases where the
+argument stack is not already long enough to handle all the return values.
+An example is the POSIX \fBtzname()\fR call, which takes no arguments, but returns
+two, the local time zone's standard and summer time abbreviations.
+.PP
+To handle this situation, the PPCODE directive is used and the stack is
+extended using the macro:
+.PP
+.Vb 1
+\&    EXTEND(SP, num);
+.Ve
+.PP
+where \f(CW\*(C`SP\*(C'\fR is the macro that represents the local copy of the stack pointer,
+and \f(CW\*(C`num\*(C'\fR is the number of elements the stack should be extended by.
+.PP
+Now that there is room on the stack, values can be pushed on it using \f(CW\*(C`PUSHs\*(C'\fR
+macro.  The pushed values will often need to be "mortal" (See
+"Reference Counts and Mortality"):
+.PP
+.Vb 7
+\&    PUSHs(sv_2mortal(newSViv(an_integer)))
+\&    PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
+\&    PUSHs(sv_2mortal(newSVnv(a_double)))
+\&    PUSHs(sv_2mortal(newSVpv("Some String",0)))
+\&    /* Although the last example is better written as the more
+\&     * efficient: */
+\&    PUSHs(newSVpvs_flags("Some String", SVs_TEMP))
+.Ve
+.PP
+And now the Perl program calling \f(CW\*(C`tzname\*(C'\fR, the two values will be assigned
+as in:
+.PP
+.Vb 1
+\&    ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
+.Ve
+.PP
+An alternate (and possibly simpler) method to pushing values on the stack is
+to use the macro:
+.PP
+.Vb 1
+\&    XPUSHs(SV*)
+.Ve
+.PP
+This macro automatically adjusts the stack for you, if needed.  Thus, you
+do not need to call \f(CW\*(C`EXTEND\*(C'\fR to extend the stack.
+.PP
+Despite their suggestions in earlier versions of this document the macros
+\&\f(CW\*(C`(X)PUSH[iunp]\*(C'\fR are \fInot\fR suited to XSUBs which return multiple results.
+For that, either stick to the \f(CW\*(C`(X)PUSHs\*(C'\fR macros shown above, or use the new
+\&\f(CW\*(C`m(X)PUSH[iunp]\*(C'\fR macros instead; see "Putting a C value on Perl stack".
+.PP
+For more information, consult perlxs and perlxstut.
+.SS "Autoloading with XSUBs"
+.IX Subsection "Autoloading with XSUBs"
+If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
+fully-qualified name of the autoloaded subroutine in the \f(CW$AUTOLOAD\fR variable
+of the XSUB's package.
+.PP
+But it also puts the same information in certain fields of the XSUB itself:
+.PP
+.Vb 4
+\&    HV *stash           = CvSTASH(cv);
+\&    const char *subname = SvPVX(cv);
+\&    STRLEN name_length  = SvCUR(cv); /* in bytes */
+\&    U32 is_utf8         = SvUTF8(cv);
+.Ve
+.PP
+\&\f(CWSvPVX(cv)\fR contains just the sub name itself, not including the package.
+For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
+\&\f(CWCvSTASH(cv)\fR returns NULL during a method call on a nonexistent package.
+.PP
+\&\fBNote\fR: Setting \f(CW$AUTOLOAD\fR stopped working in 5.6.1, which did not support
+XS AUTOLOAD subs at all.  Perl 5.8.0 introduced the use of fields in the
+XSUB itself.  Perl 5.16.0 restored the setting of \f(CW$AUTOLOAD\fR.  If you need
+to support 5.8\-5.14, use the XSUB's fields.
+.SS "Calling Perl Routines from within C Programs"
+.IX Subsection "Calling Perl Routines from within C Programs"
+There are four routines that can be used to call a Perl subroutine from
+within a C program.  These four are:
+.PP
+.Vb 4
+\&    I32  call_sv(SV*, I32);
+\&    I32  call_pv(const char*, I32);
+\&    I32  call_method(const char*, I32);
+\&    I32  call_argv(const char*, I32, char**);
+.Ve
+.PP
+The routine most often used is \f(CW\*(C`call_sv\*(C'\fR.  The \f(CW\*(C`SV*\*(C'\fR argument
+contains either the name of the Perl subroutine to be called, or a
+reference to the subroutine.  The second argument consists of flags
+that control the context in which the subroutine is called, whether
+or not the subroutine is being passed arguments, how errors should be
+trapped, and how to treat return values.
+.PP
+All four routines return the number of arguments that the subroutine returned
+on the Perl stack.
+.PP
+These routines used to be called \f(CW\*(C`perl_call_sv\*(C'\fR, etc., before Perl v5.6.0,
+but those names are now deprecated; macros of the same name are provided for
+compatibility.
+.PP
+When using any of these routines (except \f(CW\*(C`call_argv\*(C'\fR), the programmer
+must manipulate the Perl stack.  These include the following macros and
+functions:
+.PP
+.Vb 11
+\&    dSP
+\&    SP
+\&    PUSHMARK()
+\&    PUTBACK
+\&    SPAGAIN
+\&    ENTER
+\&    SAVETMPS
+\&    FREETMPS
+\&    LEAVE
+\&    XPUSH*()
+\&    POP*()
+.Ve
+.PP
+For a detailed description of calling conventions from C to Perl,
+consult perlcall.
+.SS "Putting a C value on Perl stack"
+.IX Subsection "Putting a C value on Perl stack"
+A lot of opcodes (this is an elementary operation in the internal perl
+stack machine) put an SV* on the stack.  However, as an optimization
+the corresponding SV is (usually) not recreated each time.  The opcodes
+reuse specially assigned SVs (\fItarget\fRs) which are (as a corollary)
+not constantly freed/created.
+.PP
+Each of the targets is created only once (but see
+"Scratchpads and recursion" below), and when an opcode needs to put
+an integer, a double, or a string on the stack, it just sets the
+corresponding parts of its \fItarget\fR and puts the \fItarget\fR on stack.
+.PP
+The macro to put this target on stack is \f(CW\*(C`PUSHTARG\*(C'\fR, and it is
+directly used in some opcodes, as well as indirectly in zillions of
+others, which use it via \f(CW\*(C`(X)PUSH[iunp]\*(C'\fR.
+.PP
+Because the target is reused, you must be careful when pushing multiple
+values on the stack.  The following code will not do what you think:
+.PP
+.Vb 2
+\&    XPUSHi(10);
+\&    XPUSHi(20);
+.Ve
+.PP
+This translates as "set \f(CW\*(C`TARG\*(C'\fR to 10, push a pointer to \f(CW\*(C`TARG\*(C'\fR onto
+the stack; set \f(CW\*(C`TARG\*(C'\fR to 20, push a pointer to \f(CW\*(C`TARG\*(C'\fR onto the stack".
+At the end of the operation, the stack does not contain the values 10
+and 20, but actually contains two pointers to \f(CW\*(C`TARG\*(C'\fR, which we have set
+to 20.
+.PP
+If you need to push multiple different values then you should either use
+the \f(CW\*(C`(X)PUSHs\*(C'\fR macros, or else use the new \f(CW\*(C`m(X)PUSH[iunp]\*(C'\fR macros,
+none of which make use of \f(CW\*(C`TARG\*(C'\fR.  The \f(CW\*(C`(X)PUSHs\*(C'\fR macros simply push an
+SV* on the stack, which, as noted under "XSUBs and the Argument Stack",
+will often need to be "mortal".  The new \f(CW\*(C`m(X)PUSH[iunp]\*(C'\fR macros make
+this a little easier to achieve by creating a new mortal for you (via
+\&\f(CW\*(C`(X)PUSHmortal\*(C'\fR), pushing that onto the stack (extending it if necessary
+in the case of the \f(CW\*(C`mXPUSH[iunp]\*(C'\fR macros), and then setting its value.
+Thus, instead of writing this to "fix" the example above:
+.PP
+.Vb 2
+\&    XPUSHs(sv_2mortal(newSViv(10)))
+\&    XPUSHs(sv_2mortal(newSViv(20)))
+.Ve
+.PP
+you can simply write:
+.PP
+.Vb 2
+\&    mXPUSHi(10)
+\&    mXPUSHi(20)
+.Ve
+.PP
+On a related note, if you do use \f(CW\*(C`(X)PUSH[iunp]\*(C'\fR, then you're going to
+need a \f(CW\*(C`dTARG\*(C'\fR in your variable declarations so that the \f(CW\*(C`*PUSH*\*(C'\fR
+macros can make use of the local variable \f(CW\*(C`TARG\*(C'\fR.  See also
+\&\f(CW\*(C`dTARGET\*(C'\fR and \f(CW\*(C`dXSTARG\*(C'\fR.
+.SS Scratchpads
+.IX Subsection "Scratchpads"
+The question remains on when the SVs which are \fItarget\fRs for opcodes
+are created.  The answer is that they are created when the current
+unit\-\-a subroutine or a file (for opcodes for statements outside of
+subroutines)\-\-is compiled.  During this time a special anonymous Perl
+array is created, which is called a scratchpad for the current unit.
+.PP
+A scratchpad keeps SVs which are lexicals for the current unit and are
+targets for opcodes.  A previous version of this document
+stated that one can deduce that an SV lives on a scratchpad
+by looking on its flags: lexicals have \f(CW\*(C`SVs_PADMY\*(C'\fR set, and
+\&\fItarget\fRs have \f(CW\*(C`SVs_PADTMP\*(C'\fR set.  But this has never been fully true.
+\&\f(CW\*(C`SVs_PADMY\*(C'\fR could be set on a variable that no longer resides in any pad.
+While \fItarget\fRs do have \f(CW\*(C`SVs_PADTMP\*(C'\fR set, it can also be set on variables
+that have never resided in a pad, but nonetheless act like \fItarget\fRs.  As
+of perl 5.21.5, the \f(CW\*(C`SVs_PADMY\*(C'\fR flag is no longer used and is defined as
+0.  \f(CWSvPADMY()\fR now returns true for anything without \f(CW\*(C`SVs_PADTMP\*(C'\fR.
+.PP
+The correspondence between OPs and \fItarget\fRs is not 1\-to\-1.  Different
+OPs in the compile tree of the unit can use the same target, if this
+would not conflict with the expected life of the temporary.
+.SS "Scratchpads and recursion"
+.IX Subsection "Scratchpads and recursion"
+In fact it is not 100% true that a compiled unit contains a pointer to
+the scratchpad AV.  In fact it contains a pointer to an AV of
+(initially) one element, and this element is the scratchpad AV.  Why do
+we need an extra level of indirection?
+.PP
+The answer is \fBrecursion\fR, and maybe \fBthreads\fR.  Both
+these can create several execution pointers going into the same
+subroutine.  For the subroutine-child not write over the temporaries
+for the subroutine-parent (lifespan of which covers the call to the
+child), the parent and the child should have different
+scratchpads.  (\fIAnd\fR the lexicals should be separate anyway!)
+.PP
+So each subroutine is born with an array of scratchpads (of length 1).
+On each entry to the subroutine it is checked that the current
+depth of the recursion is not more than the length of this array, and
+if it is, new scratchpad is created and pushed into the array.
+.PP
+The \fItarget\fRs on this scratchpad are \f(CW\*(C`undef\*(C'\fRs, but they are already
+marked with correct flags.
+.SH "Memory Allocation"
+.IX Header "Memory Allocation"
+.SS Allocation
+.IX Subsection "Allocation"
+All memory meant to be used with the Perl API functions should be manipulated
+using the macros described in this section.  The macros provide the necessary
+transparency between differences in the actual malloc implementation that is
+used within perl.
+.PP
+The following three macros are used to initially allocate memory :
+.PP
+.Vb 3
+\&    Newx(pointer, number, type);
+\&    Newxc(pointer, number, type, cast);
+\&    Newxz(pointer, number, type);
+.Ve
+.PP
+The first argument \f(CW\*(C`pointer\*(C'\fR should be the name of a variable that will
+point to the newly allocated memory.
+.PP
+The second and third arguments \f(CW\*(C`number\*(C'\fR and \f(CW\*(C`type\*(C'\fR specify how many of
+the specified type of data structure should be allocated.  The argument
+\&\f(CW\*(C`type\*(C'\fR is passed to \f(CW\*(C`sizeof\*(C'\fR.  The final argument to \f(CW\*(C`Newxc\*(C'\fR, \f(CW\*(C`cast\*(C'\fR,
+should be used if the \f(CW\*(C`pointer\*(C'\fR argument is different from the \f(CW\*(C`type\*(C'\fR
+argument.
+.PP
+Unlike the \f(CW\*(C`Newx\*(C'\fR and \f(CW\*(C`Newxc\*(C'\fR macros, the \f(CW\*(C`Newxz\*(C'\fR macro calls \f(CW\*(C`memzero\*(C'\fR
+to zero out all the newly allocated memory.
+.SS Reallocation
+.IX Subsection "Reallocation"
+.Vb 3
+\&    Renew(pointer, number, type);
+\&    Renewc(pointer, number, type, cast);
+\&    Safefree(pointer)
+.Ve
+.PP
+These three macros are used to change a memory buffer size or to free a
+piece of memory no longer needed.  The arguments to \f(CW\*(C`Renew\*(C'\fR and \f(CW\*(C`Renewc\*(C'\fR
+match those of \f(CW\*(C`New\*(C'\fR and \f(CW\*(C`Newc\*(C'\fR with the exception of not needing the
+"magic cookie" argument.
+.SS Moving
+.IX Subsection "Moving"
+.Vb 3
+\&    Move(source, dest, number, type);
+\&    Copy(source, dest, number, type);
+\&    Zero(dest, number, type);
+.Ve
+.PP
+These three macros are used to move, copy, or zero out previously allocated
+memory.  The \f(CW\*(C`source\*(C'\fR and \f(CW\*(C`dest\*(C'\fR arguments point to the source and
+destination starting points.  Perl will move, copy, or zero out \f(CW\*(C`number\*(C'\fR
+instances of the size of the \f(CW\*(C`type\*(C'\fR data structure (using the \f(CW\*(C`sizeof\*(C'\fR
+function).
+.SH PerlIO
+.IX Header "PerlIO"
+The most recent development releases of Perl have been experimenting with
+removing Perl's dependency on the "normal" standard I/O suite and allowing
+other stdio implementations to be used.  This involves creating a new
+abstraction layer that then calls whichever implementation of stdio Perl
+was compiled with.  All XSUBs should now use the functions in the PerlIO
+abstraction layer and not make any assumptions about what kind of stdio
+is being used.
+.PP
+For a complete description of the PerlIO abstraction, consult perlapio.
+.SH "Compiled code"
+.IX Header "Compiled code"
+.SS "Code tree"
+.IX Subsection "Code tree"
+Here we describe the internal form your code is converted to by
+Perl.  Start with a simple example:
+.PP
+.Vb 1
+\&  $a = $b + $c;
+.Ve
+.PP
+This is converted to a tree similar to this one:
+.PP
+.Vb 5
+\&             assign\-to
+\&           /           \e
+\&          +             $a
+\&        /   \e
+\&      $b     $c
+.Ve
+.PP
+(but slightly more complicated).  This tree reflects the way Perl
+parsed your code, but has nothing to do with the execution order.
+There is an additional "thread" going through the nodes of the tree
+which shows the order of execution of the nodes.  In our simplified
+example above it looks like:
+.PP
+.Vb 1
+\&     $b \-\-\-> $c \-\-\-> + \-\-\-> $a \-\-\-> assign\-to
+.Ve
+.PP
+But with the actual compile tree for \f(CW\*(C`$a = $b + $c\*(C'\fR it is different:
+some nodes \fIoptimized away\fR.  As a corollary, though the actual tree
+contains more nodes than our simplified example, the execution order
+is the same as in our example.
+.SS "Examining the tree"
+.IX Subsection "Examining the tree"
+If you have your perl compiled for debugging (usually done with
+\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR on the \f(CW\*(C`Configure\*(C'\fR command line), you may examine the
+compiled tree by specifying \f(CW\*(C`\-Dx\*(C'\fR on the Perl command line.  The
+output takes several lines per node, and for \f(CW\*(C`$b+$c\*(C'\fR it looks like
+this:
+.PP
+.Vb 10
+\&    5           TYPE = add  ===> 6
+\&                TARG = 1
+\&                FLAGS = (SCALAR,KIDS)
+\&                {
+\&                    TYPE = null  ===> (4)
+\&                      (was rv2sv)
+\&                    FLAGS = (SCALAR,KIDS)
+\&                    {
+\&    3                   TYPE = gvsv  ===> 4
+\&                        FLAGS = (SCALAR)
+\&                        GV = main::b
+\&                    }
+\&                }
+\&                {
+\&                    TYPE = null  ===> (5)
+\&                      (was rv2sv)
+\&                    FLAGS = (SCALAR,KIDS)
+\&                    {
+\&    4                   TYPE = gvsv  ===> 5
+\&                        FLAGS = (SCALAR)
+\&                        GV = main::c
+\&                    }
+\&                }
+.Ve
+.PP
+This tree has 5 nodes (one per \f(CW\*(C`TYPE\*(C'\fR specifier), only 3 of them are
+not optimized away (one per number in the left column).  The immediate
+children of the given node correspond to \f(CW\*(C`{}\*(C'\fR pairs on the same level
+of indentation, thus this listing corresponds to the tree:
+.PP
+.Vb 5
+\&                   add
+\&                 /     \e
+\&               null    null
+\&                |       |
+\&               gvsv    gvsv
+.Ve
+.PP
+The execution order is indicated by \f(CW\*(C`===>\*(C'\fR marks, thus it is \f(CW\*(C`3
+4 5 6\*(C'\fR (node \f(CW6\fR is not included into above listing), i.e.,
+\&\f(CW\*(C`gvsv gvsv add whatever\*(C'\fR.
+.PP
+Each of these nodes represents an op, a fundamental operation inside the
+Perl core.  The code which implements each operation can be found in the
+\&\fIpp*.c\fR files; the function which implements the op with type \f(CW\*(C`gvsv\*(C'\fR
+is \f(CW\*(C`pp_gvsv\*(C'\fR, and so on.  As the tree above shows, different ops have
+different numbers of children: \f(CW\*(C`add\*(C'\fR is a binary operator, as one would
+expect, and so has two children.  To accommodate the various different
+numbers of children, there are various types of op data structure, and
+they link together in different ways.
+.PP
+The simplest type of op structure is \f(CW\*(C`OP\*(C'\fR: this has no children.  Unary
+operators, \f(CW\*(C`UNOP\*(C'\fRs, have one child, and this is pointed to by the
+\&\f(CW\*(C`op_first\*(C'\fR field.  Binary operators (\f(CW\*(C`BINOP\*(C'\fRs) have not only an
+\&\f(CW\*(C`op_first\*(C'\fR field but also an \f(CW\*(C`op_last\*(C'\fR field.  The most complex type of
+op is a \f(CW\*(C`LISTOP\*(C'\fR, which has any number of children.  In this case, the
+first child is pointed to by \f(CW\*(C`op_first\*(C'\fR and the last child by
+\&\f(CW\*(C`op_last\*(C'\fR.  The children in between can be found by iteratively
+following the \f(CW\*(C`OpSIBLING\*(C'\fR pointer from the first child to the last (but
+see below).
+.PP
+There are also some other op types: a \f(CW\*(C`PMOP\*(C'\fR holds a regular expression,
+and has no children, and a \f(CW\*(C`LOOP\*(C'\fR may or may not have children.  If the
+\&\f(CW\*(C`op_children\*(C'\fR field is non-zero, it behaves like a \f(CW\*(C`LISTOP\*(C'\fR.  To
+complicate matters, if a \f(CW\*(C`UNOP\*(C'\fR is actually a \f(CW\*(C`null\*(C'\fR op after
+optimization (see "Compile pass 2: context propagation") it will still
+have children in accordance with its former type.
+.PP
+Finally, there is a \f(CW\*(C`LOGOP\*(C'\fR, or logic op. Like a \f(CW\*(C`LISTOP\*(C'\fR, this has one
+or more children, but it doesn't have an \f(CW\*(C`op_last\*(C'\fR field: so you have to
+follow \f(CW\*(C`op_first\*(C'\fR and then the \f(CW\*(C`OpSIBLING\*(C'\fR chain itself to find the
+last child. Instead it has an \f(CW\*(C`op_other\*(C'\fR field, which is comparable to
+the \f(CW\*(C`op_next\*(C'\fR field described below, and represents an alternate
+execution path. Operators like \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`?\*(C'\fR are \f(CW\*(C`LOGOP\*(C'\fRs. Note
+that in general, \f(CW\*(C`op_other\*(C'\fR may not point to any of the direct children
+of the \f(CW\*(C`LOGOP\*(C'\fR.
+.PP
+Starting in version 5.21.2, perls built with the experimental
+define \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR add an extra boolean flag for each op,
+\&\f(CW\*(C`op_moresib\*(C'\fR.  When not set, this indicates that this is the last op in an
+\&\f(CW\*(C`OpSIBLING\*(C'\fR chain. This frees up the \f(CW\*(C`op_sibling\*(C'\fR field on the last
+sibling to point back to the parent op. Under this build, that field is
+also renamed \f(CW\*(C`op_sibparent\*(C'\fR to reflect its joint role. The macro
+\&\f(CWOpSIBLING(o)\fR wraps this special behaviour, and always returns NULL on
+the last sibling.  With this build the \f(CWop_parent(o)\fR function can be
+used to find the parent of any op. Thus for forward compatibility, you
+should always use the \f(CWOpSIBLING(o)\fR macro rather than accessing
+\&\f(CW\*(C`op_sibling\*(C'\fR directly.
+.PP
+Another way to examine the tree is to use a compiler back-end module, such
+as B::Concise.
+.SS "Compile pass 1: check routines"
+.IX Subsection "Compile pass 1: check routines"
+The tree is created by the compiler while \fIyacc\fR code feeds it
+the constructions it recognizes.  Since \fIyacc\fR works bottom-up, so does
+the first pass of perl compilation.
+.PP
+What makes this pass interesting for perl developers is that some
+optimization may be performed on this pass.  This is optimization by
+so-called "check routines".  The correspondence between node names
+and corresponding check routines is described in \fIopcode.pl\fR (do not
+forget to run \f(CW\*(C`make regen_headers\*(C'\fR if you modify this file).
+.PP
+A check routine is called when the node is fully constructed except
+for the execution-order thread.  Since at this time there are no
+back-links to the currently constructed node, one can do most any
+operation to the top-level node, including freeing it and/or creating
+new nodes above/below it.
+.PP
+The check routine returns the node which should be inserted into the
+tree (if the top-level node was not modified, check routine returns
+its argument).
+.PP
+By convention, check routines have names \f(CW\*(C`ck_*\*(C'\fR.  They are usually
+called from \f(CW\*(C`new*OP\*(C'\fR subroutines (or \f(CW\*(C`convert\*(C'\fR) (which in turn are
+called from \fIperly.y\fR).
+.SS "Compile pass 1a: constant folding"
+.IX Subsection "Compile pass 1a: constant folding"
+Immediately after the check routine is called the returned node is
+checked for being compile-time executable.  If it is (the value is
+judged to be constant) it is immediately executed, and a \fIconstant\fR
+node with the "return value" of the corresponding subtree is
+substituted instead.  The subtree is deleted.
+.PP
+If constant folding was not performed, the execution-order thread is
+created.
+.SS "Compile pass 2: context propagation"
+.IX Subsection "Compile pass 2: context propagation"
+When a context for a part of compile tree is known, it is propagated
+down through the tree.  At this time the context can have 5 values
+(instead of 2 for runtime context): void, boolean, scalar, list, and
+lvalue.  In contrast with the pass 1 this pass is processed from top
+to bottom: a node's context determines the context for its children.
+.PP
+Additional context-dependent optimizations are performed at this time.
+Since at this moment the compile tree contains back-references (via
+"thread" pointers), nodes cannot be \fBfree()\fRd now.  To allow
+optimized-away nodes at this stage, such nodes are \fBnull()\fRified instead
+of \fBfree()\fRing (i.e. their type is changed to OP_NULL).
+.SS "Compile pass 3: peephole optimization"
+.IX Subsection "Compile pass 3: peephole optimization"
+After the compile tree for a subroutine (or for an \f(CW\*(C`eval\*(C'\fR or a file)
+is created, an additional pass over the code is performed.  This pass
+is neither top-down or bottom-up, but in the execution order (with
+additional complications for conditionals).  Optimizations performed
+at this stage are subject to the same restrictions as in the pass 2.
+.PP
+Peephole optimizations are done by calling the function pointed to
+by the global variable \f(CW\*(C`PL_peepp\*(C'\fR.  By default, \f(CW\*(C`PL_peepp\*(C'\fR just
+calls the function pointed to by the global variable \f(CW\*(C`PL_rpeepp\*(C'\fR.
+By default, that performs some basic op fixups and optimisations along
+the execution-order op chain, and recursively calls \f(CW\*(C`PL_rpeepp\*(C'\fR for
+each side chain of ops (resulting from conditionals).  Extensions may
+provide additional optimisations or fixups, hooking into either the
+per-subroutine or recursive stage, like this:
+.PP
+.Vb 10
+\&    static peep_t prev_peepp;
+\&    static void my_peep(pTHX_ OP *o)
+\&    {
+\&        /* custom per\-subroutine optimisation goes here */
+\&        prev_peepp(aTHX_ o);
+\&        /* custom per\-subroutine optimisation may also go here */
+\&    }
+\&    BOOT:
+\&        prev_peepp = PL_peepp;
+\&        PL_peepp = my_peep;
+\&
+\&    static peep_t prev_rpeepp;
+\&    static void my_rpeep(pTHX_ OP *first)
+\&    {
+\&        OP *o = first, *t = first;
+\&        for(; o = o\->op_next, t = t\->op_next) {
+\&            /* custom per\-op optimisation goes here */
+\&            o = o\->op_next;
+\&            if (!o || o == t) break;
+\&            /* custom per\-op optimisation goes AND here */
+\&        }
+\&        prev_rpeepp(aTHX_ orig_o);
+\&    }
+\&    BOOT:
+\&        prev_rpeepp = PL_rpeepp;
+\&        PL_rpeepp = my_rpeep;
+.Ve
+.SS "Pluggable runops"
+.IX Subsection "Pluggable runops"
+The compile tree is executed in a runops function.  There are two runops
+functions, in \fIrun.c\fR and in \fIdump.c\fR.  \f(CW\*(C`Perl_runops_debug\*(C'\fR is used
+with DEBUGGING and \f(CW\*(C`Perl_runops_standard\*(C'\fR is used otherwise.  For fine
+control over the execution of the compile tree it is possible to provide
+your own runops function.
+.PP
+It's probably best to copy one of the existing runops functions and
+change it to suit your needs.  Then, in the BOOT section of your XS
+file, add the line:
+.PP
+.Vb 1
+\&  PL_runops = my_runops;
+.Ve
+.PP
+This function should be as efficient as possible to keep your programs
+running as fast as possible.
+.SS "Compile-time scope hooks"
+.IX Subsection "Compile-time scope hooks"
+As of perl 5.14 it is possible to hook into the compile-time lexical
+scope mechanism using \f(CW\*(C`Perl_blockhook_register\*(C'\fR.  This is used like
+this:
+.PP
+.Vb 2
+\&    STATIC void my_start_hook(pTHX_ int full);
+\&    STATIC BHK my_hooks;
+\&
+\&    BOOT:
+\&        BhkENTRY_set(&my_hooks, bhk_start, my_start_hook);
+\&        Perl_blockhook_register(aTHX_ &my_hooks);
+.Ve
+.PP
+This will arrange to have \f(CW\*(C`my_start_hook\*(C'\fR called at the start of
+compiling every lexical scope.  The available hooks are:
+.ie n .IP """void bhk_start(pTHX_ int full)""" 4
+.el .IP "\f(CWvoid bhk_start(pTHX_ int full)\fR" 4
+.IX Item "void bhk_start(pTHX_ int full)"
+This is called just after starting a new lexical scope.  Note that Perl
+code like
+.Sp
+.Vb 1
+\&    if ($x) { ... }
+.Ve
+.Sp
+creates two scopes: the first starts at the \f(CW\*(C`(\*(C'\fR and has \f(CW\*(C`full == 1\*(C'\fR,
+the second starts at the \f(CW\*(C`{\*(C'\fR and has \f(CW\*(C`full == 0\*(C'\fR.  Both end at the
+\&\f(CW\*(C`}\*(C'\fR, so calls to \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`pre\*(C'\fR/\f(CW\*(C`post_end\*(C'\fR will match.  Anything
+pushed onto the save stack by this hook will be popped just before the
+scope ends (between the \f(CW\*(C`pre_\*(C'\fR and \f(CW\*(C`post_end\*(C'\fR hooks, in fact).
+.ie n .IP """void bhk_pre_end(pTHX_ OP **o)""" 4
+.el .IP "\f(CWvoid bhk_pre_end(pTHX_ OP **o)\fR" 4
+.IX Item "void bhk_pre_end(pTHX_ OP **o)"
+This is called at the end of a lexical scope, just before unwinding the
+stack.  \fIo\fR is the root of the optree representing the scope; it is a
+double pointer so you can replace the OP if you need to.
+.ie n .IP """void bhk_post_end(pTHX_ OP **o)""" 4
+.el .IP "\f(CWvoid bhk_post_end(pTHX_ OP **o)\fR" 4
+.IX Item "void bhk_post_end(pTHX_ OP **o)"
+This is called at the end of a lexical scope, just after unwinding the
+stack.  \fIo\fR is as above.  Note that it is possible for calls to \f(CW\*(C`pre_\*(C'\fR
+and \f(CW\*(C`post_end\*(C'\fR to nest, if there is something on the save stack that
+calls string eval.
+.ie n .IP """void bhk_eval(pTHX_ OP *const o)""" 4
+.el .IP "\f(CWvoid bhk_eval(pTHX_ OP *const o)\fR" 4
+.IX Item "void bhk_eval(pTHX_ OP *const o)"
+This is called just before starting to compile an \f(CW\*(C`eval STRING\*(C'\fR, \f(CW\*(C`do
+FILE\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR, after the eval has been set up.  \fIo\fR is the
+OP that requested the eval, and will normally be an \f(CW\*(C`OP_ENTEREVAL\*(C'\fR,
+\&\f(CW\*(C`OP_DOFILE\*(C'\fR or \f(CW\*(C`OP_REQUIRE\*(C'\fR.
+.PP
+Once you have your hook functions, you need a \f(CW\*(C`BHK\*(C'\fR structure to put
+them in.  It's best to allocate it statically, since there is no way to
+free it once it's registered.  The function pointers should be inserted
+into this structure using the \f(CW\*(C`BhkENTRY_set\*(C'\fR macro, which will also set
+flags indicating which entries are valid.  If you do need to allocate
+your \f(CW\*(C`BHK\*(C'\fR dynamically for some reason, be sure to zero it before you
+start.
+.PP
+Once registered, there is no mechanism to switch these hooks off, so if
+that is necessary you will need to do this yourself.  An entry in \f(CW\*(C`%^H\*(C'\fR
+is probably the best way, so the effect is lexically scoped; however it
+is also possible to use the \f(CW\*(C`BhkDISABLE\*(C'\fR and \f(CW\*(C`BhkENABLE\*(C'\fR macros to
+temporarily switch entries on and off.  You should also be aware that
+generally speaking at least one scope will have opened before your
+extension is loaded, so you will see some \f(CW\*(C`pre\*(C'\fR/\f(CW\*(C`post_end\*(C'\fR pairs that
+didn't have a matching \f(CW\*(C`start\*(C'\fR.
+.ie n .SH "Examining internal data structures with the ""dump"" functions"
+.el .SH "Examining internal data structures with the \f(CWdump\fP functions"
+.IX Header "Examining internal data structures with the dump functions"
+To aid debugging, the source file \fIdump.c\fR contains a number of
+functions which produce formatted output of internal data structures.
+.PP
+The most commonly used of these functions is \f(CW\*(C`Perl_sv_dump\*(C'\fR; it's used
+for dumping SVs, AVs, HVs, and CVs.  The \f(CW\*(C`Devel::Peek\*(C'\fR module calls
+\&\f(CW\*(C`sv_dump\*(C'\fR to produce debugging output from Perl-space, so users of that
+module should already be familiar with its format.
+.PP
+\&\f(CW\*(C`Perl_op_dump\*(C'\fR can be used to dump an \f(CW\*(C`OP\*(C'\fR structure or any of its
+derivatives, and produces output similar to \f(CW\*(C`perl \-Dx\*(C'\fR; in fact,
+\&\f(CW\*(C`Perl_dump_eval\*(C'\fR will dump the main root of the code being evaluated,
+exactly like \f(CW\*(C`\-Dx\*(C'\fR.
+.PP
+Other useful functions are \f(CW\*(C`Perl_dump_sub\*(C'\fR, which turns a \f(CW\*(C`GV\*(C'\fR into an
+op tree, \f(CW\*(C`Perl_dump_packsubs\*(C'\fR which calls \f(CW\*(C`Perl_dump_sub\*(C'\fR on all the
+subroutines in a package like so: (Thankfully, these are all xsubs, so
+there is no op tree)
+.PP
+.Vb 1
+\&    (gdb) print Perl_dump_packsubs(PL_defstash)
+\&
+\&    SUB attributes::bootstrap = (xsub 0x811fedc 0)
+\&
+\&    SUB UNIVERSAL::can = (xsub 0x811f50c 0)
+\&
+\&    SUB UNIVERSAL::isa = (xsub 0x811f304 0)
+\&
+\&    SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0)
+\&
+\&    SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0)
+.Ve
+.PP
+and \f(CW\*(C`Perl_dump_all\*(C'\fR, which dumps all the subroutines in the stash and
+the op tree of the main root.
+.SH "How multiple interpreters and concurrency are supported"
+.IX Header "How multiple interpreters and concurrency are supported"
+.SS "Background and MULTIPLICITY"
+.IX Subsection "Background and MULTIPLICITY"
+The Perl interpreter can be regarded as a closed box: it has an API
+for feeding it code or otherwise making it do things, but it also has
+functions for its own use.  This smells a lot like an object, and
+there is a way for you to build Perl so that you can have multiple
+interpreters, with one interpreter represented either as a C structure,
+or inside a thread-specific structure.  These structures contain all
+the context, the state of that interpreter.
+.PP
+The macro that controls the major Perl build flavor is MULTIPLICITY.  The
+MULTIPLICITY build has a C structure that packages all the interpreter
+state, which is being passed to various perl functions as a "hidden"
+first argument. MULTIPLICITY makes multi-threaded perls possible (with the
+ithreads threading model, related to the macro USE_ITHREADS.)
+.PP
+PERL_IMPLICIT_CONTEXT is a legacy synonym for MULTIPLICITY.
+.PP
+To see whether you have non-const data you can use a BSD (or GNU)
+compatible \f(CW\*(C`nm\*(C'\fR:
+.PP
+.Vb 1
+\&  nm libperl.a | grep \-v \*(Aq [TURtr] \*(Aq
+.Ve
+.PP
+If this displays any \f(CW\*(C`D\*(C'\fR or \f(CW\*(C`d\*(C'\fR symbols (or possibly \f(CW\*(C`C\*(C'\fR or \f(CW\*(C`c\*(C'\fR),
+you have non-const data.  The symbols the \f(CW\*(C`grep\*(C'\fR removed are as follows:
+\&\f(CW\*(C`Tt\*(C'\fR are \fItext\fR, or code, the \f(CW\*(C`Rr\*(C'\fR are \fIread-only\fR (const) data,
+and the \f(CW\*(C`U\*(C'\fR is <undefined>, external symbols referred to.
+.PP
+The test \fIt/porting/libperl.t\fR does this kind of symbol sanity
+checking on \f(CW\*(C`libperl.a\*(C'\fR.
+.PP
+All this obviously requires a way for the Perl internal functions to be
+either subroutines taking some kind of structure as the first
+argument, or subroutines taking nothing as the first argument.  To
+enable these two very different ways of building the interpreter,
+the Perl source (as it does in so many other situations) makes heavy
+use of macros and subroutine naming conventions.
+.PP
+First problem: deciding which functions will be public API functions and
+which will be private.  All functions whose names begin \f(CW\*(C`S_\*(C'\fR are private
+(think "S" for "secret" or "static").  All other functions begin with
+"Perl_", but just because a function begins with "Perl_" does not mean it is
+part of the API.  (See "Internal
+Functions".)  The easiest way to be \fBsure\fR a
+function is part of the API is to find its entry in perlapi.
+If it exists in perlapi, it's part of the API.  If it doesn't, and you
+think it should be (i.e., you need it for your extension), submit an issue at
+<https://github.com/Perl/perl5/issues> explaining why you think it should be.
+.PP
+Second problem: there must be a syntax so that the same subroutine
+declarations and calls can pass a structure as their first argument,
+or pass nothing.  To solve this, the subroutines are named and
+declared in a particular way.  Here's a typical start of a static
+function used within the Perl guts:
+.PP
+.Vb 2
+\&  STATIC void
+\&  S_incline(pTHX_ char *s)
+.Ve
+.PP
+STATIC becomes "static" in C, and may be #define'd to nothing in some
+configurations in the future.
+.PP
+A public function (i.e. part of the internal API, but not necessarily
+sanctioned for use in extensions) begins like this:
+.PP
+.Vb 2
+\&  void
+\&  Perl_sv_setiv(pTHX_ SV* dsv, IV num)
+.Ve
+.PP
+\&\f(CW\*(C`pTHX_\*(C'\fR is one of a number of macros (in \fIperl.h\fR) that hide the
+details of the interpreter's context.  THX stands for "thread", "this",
+or "thingy", as the case may be.  (And no, George Lucas is not involved. :\-)
+The first character could be 'p' for a \fBp\fRrototype, 'a' for \fBa\fRrgument,
+or 'd' for \fBd\fReclaration, so we have \f(CW\*(C`pTHX\*(C'\fR, \f(CW\*(C`aTHX\*(C'\fR and \f(CW\*(C`dTHX\*(C'\fR, and
+their variants.
+.PP
+When Perl is built without options that set MULTIPLICITY, there is no
+first argument containing the interpreter's context.  The trailing underscore
+in the pTHX_ macro indicates that the macro expansion needs a comma
+after the context argument because other arguments follow it.  If
+MULTIPLICITY is not defined, pTHX_ will be ignored, and the
+subroutine is not prototyped to take the extra argument.  The form of the
+macro without the trailing underscore is used when there are no additional
+explicit arguments.
+.PP
+When a core function calls another, it must pass the context.  This
+is normally hidden via macros.  Consider \f(CW\*(C`sv_setiv\*(C'\fR.  It expands into
+something like this:
+.PP
+.Vb 6
+\&    #ifdef MULTIPLICITY
+\&      #define sv_setiv(a,b)      Perl_sv_setiv(aTHX_ a, b)
+\&      /* can\*(Aqt do this for vararg functions, see below */
+\&    #else
+\&      #define sv_setiv           Perl_sv_setiv
+\&    #endif
+.Ve
+.PP
+This works well, and means that XS authors can gleefully write:
+.PP
+.Vb 1
+\&    sv_setiv(foo, bar);
+.Ve
+.PP
+and still have it work under all the modes Perl could have been
+compiled with.
+.PP
+This doesn't work so cleanly for varargs functions, though, as macros
+imply that the number of arguments is known in advance.  Instead we
+either need to spell them out fully, passing \f(CW\*(C`aTHX_\*(C'\fR as the first
+argument (the Perl core tends to do this with functions like
+Perl_warner), or use a context-free version.
+.PP
+The context-free version of Perl_warner is called
+Perl_warner_nocontext, and does not take the extra argument.  Instead
+it does \f(CW\*(C`dTHX;\*(C'\fR to get the context from thread-local storage.  We
+\&\f(CW\*(C`#define warner Perl_warner_nocontext\*(C'\fR so that extensions get source
+compatibility at the expense of performance.  (Passing an arg is
+cheaper than grabbing it from thread-local storage.)
+.PP
+You can ignore [pad]THXx when browsing the Perl headers/sources.
+Those are strictly for use within the core.  Extensions and embedders
+need only be aware of [pad]THX.
+.SS "So what happened to dTHR?"
+.IX Subsection "So what happened to dTHR?"
+\&\f(CW\*(C`dTHR\*(C'\fR was introduced in perl 5.005 to support the older thread model.
+The older thread model now uses the \f(CW\*(C`THX\*(C'\fR mechanism to pass context
+pointers around, so \f(CW\*(C`dTHR\*(C'\fR is not useful any more.  Perl 5.6.0 and
+later still have it for backward source compatibility, but it is defined
+to be a no-op.
+.SS "How do I use all this in extensions?"
+.IX Subsection "How do I use all this in extensions?"
+When Perl is built with MULTIPLICITY, extensions that call
+any functions in the Perl API will need to pass the initial context
+argument somehow.  The kicker is that you will need to write it in
+such a way that the extension still compiles when Perl hasn't been
+built with MULTIPLICITY enabled.
+.PP
+There are three ways to do this.  First, the easy but inefficient way,
+which is also the default, in order to maintain source compatibility
+with extensions: whenever \fIXSUB.h\fR is #included, it redefines the aTHX
+and aTHX_ macros to call a function that will return the context.
+Thus, something like:
+.PP
+.Vb 1
+\&        sv_setiv(sv, num);
+.Ve
+.PP
+in your extension will translate to this when MULTIPLICITY is
+in effect:
+.PP
+.Vb 1
+\&        Perl_sv_setiv(Perl_get_context(), sv, num);
+.Ve
+.PP
+or to this otherwise:
+.PP
+.Vb 1
+\&        Perl_sv_setiv(sv, num);
+.Ve
+.PP
+You don't have to do anything new in your extension to get this; since
+the Perl library provides \fBPerl_get_context()\fR, it will all just
+work.
+.PP
+The second, more efficient way is to use the following template for
+your Foo.xs:
+.PP
+.Vb 4
+\&        #define PERL_NO_GET_CONTEXT     /* we want efficiency */
+\&        #include "EXTERN.h"
+\&        #include "perl.h"
+\&        #include "XSUB.h"
+\&
+\&        STATIC void my_private_function(int arg1, int arg2);
+\&
+\&        STATIC void
+\&        my_private_function(int arg1, int arg2)
+\&        {
+\&            dTHX;       /* fetch context */
+\&            ... call many Perl API functions ...
+\&        }
+\&
+\&        [... etc ...]
+\&
+\&        MODULE = Foo            PACKAGE = Foo
+\&
+\&        /* typical XSUB */
+\&
+\&        void
+\&        my_xsub(arg)
+\&                int arg
+\&            CODE:
+\&                my_private_function(arg, 10);
+.Ve
+.PP
+Note that the only two changes from the normal way of writing an
+extension is the addition of a \f(CW\*(C`#define PERL_NO_GET_CONTEXT\*(C'\fR before
+including the Perl headers, followed by a \f(CW\*(C`dTHX;\*(C'\fR declaration at
+the start of every function that will call the Perl API.  (You'll
+know which functions need this, because the C compiler will complain
+that there's an undeclared identifier in those functions.)  No changes
+are needed for the XSUBs themselves, because the \fBXS()\fR macro is
+correctly defined to pass in the implicit context if needed.
+.PP
+The third, even more efficient way is to ape how it is done within
+the Perl guts:
+.PP
+.Vb 4
+\&        #define PERL_NO_GET_CONTEXT     /* we want efficiency */
+\&        #include "EXTERN.h"
+\&        #include "perl.h"
+\&        #include "XSUB.h"
+\&
+\&        /* pTHX_ only needed for functions that call Perl API */
+\&        STATIC void my_private_function(pTHX_ int arg1, int arg2);
+\&
+\&        STATIC void
+\&        my_private_function(pTHX_ int arg1, int arg2)
+\&        {
+\&            /* dTHX; not needed here, because THX is an argument */
+\&            ... call Perl API functions ...
+\&        }
+\&
+\&        [... etc ...]
+\&
+\&        MODULE = Foo            PACKAGE = Foo
+\&
+\&        /* typical XSUB */
+\&
+\&        void
+\&        my_xsub(arg)
+\&                int arg
+\&            CODE:
+\&                my_private_function(aTHX_ arg, 10);
+.Ve
+.PP
+This implementation never has to fetch the context using a function
+call, since it is always passed as an extra argument.  Depending on
+your needs for simplicity or efficiency, you may mix the previous
+two approaches freely.
+.PP
+Never add a comma after \f(CW\*(C`pTHX\*(C'\fR yourself\-\-always use the form of the
+macro with the underscore for functions that take explicit arguments,
+or the form without the argument for functions with no explicit arguments.
+.SS "Should I do anything special if I call perl from multiple threads?"
+.IX Subsection "Should I do anything special if I call perl from multiple threads?"
+If you create interpreters in one thread and then proceed to call them in
+another, you need to make sure perl's own Thread Local Storage (TLS) slot is
+initialized correctly in each of those threads.
+.PP
+The \f(CW\*(C`perl_alloc\*(C'\fR and \f(CW\*(C`perl_clone\*(C'\fR API functions will automatically set
+the TLS slot to the interpreter they created, so that there is no need to do
+anything special if the interpreter is always accessed in the same thread that
+created it, and that thread did not create or call any other interpreters
+afterwards.  If that is not the case, you have to set the TLS slot of the
+thread before calling any functions in the Perl API on that particular
+interpreter.  This is done by calling the \f(CW\*(C`PERL_SET_CONTEXT\*(C'\fR macro in that
+thread as the first thing you do:
+.PP
+.Vb 2
+\&        /* do this before doing anything else with some_perl */
+\&        PERL_SET_CONTEXT(some_perl);
+\&
+\&        ... other Perl API calls on some_perl go here ...
+.Ve
+.PP
+(You can always get the current context via \f(CW\*(C`PERL_GET_CONTEXT\*(C'\fR.)
+.SS "Future Plans and PERL_IMPLICIT_SYS"
+.IX Subsection "Future Plans and PERL_IMPLICIT_SYS"
+Just as MULTIPLICITY provides a way to bundle up everything
+that the interpreter knows about itself and pass it around, so too are
+there plans to allow the interpreter to bundle up everything it knows
+about the environment it's running on.  This is enabled with the
+PERL_IMPLICIT_SYS macro.  Currently it only works with USE_ITHREADS on
+Windows.
+.PP
+This allows the ability to provide an extra pointer (called the "host"
+environment) for all the system calls.  This makes it possible for
+all the system stuff to maintain their own state, broken down into
+seven C structures.  These are thin wrappers around the usual system
+calls (see \fIwin32/perllib.c\fR) for the default perl executable, but for a
+more ambitious host (like the one that would do \fBfork()\fR emulation) all
+the extra work needed to pretend that different interpreters are
+actually different "processes", would be done here.
+.PP
+The Perl engine/interpreter and the host are orthogonal entities.
+There could be one or more interpreters in a process, and one or
+more "hosts", with free association between them.
+.SH "Internal Functions"
+.IX Header "Internal Functions"
+All of Perl's internal functions which will be exposed to the outside
+world are prefixed by \f(CW\*(C`Perl_\*(C'\fR so that they will not conflict with XS
+functions or functions used in a program in which Perl is embedded.
+Similarly, all global variables begin with \f(CW\*(C`PL_\*(C'\fR.  (By convention,
+static functions start with \f(CW\*(C`S_\*(C'\fR.)
+.PP
+Inside the Perl core (\f(CW\*(C`PERL_CORE\*(C'\fR defined), you can get at the functions
+either with or without the \f(CW\*(C`Perl_\*(C'\fR prefix, thanks to a bunch of defines
+that live in \fIembed.h\fR.  Note that extension code should \fInot\fR set
+\&\f(CW\*(C`PERL_CORE\*(C'\fR; this exposes the full perl internals, and is likely to cause
+breakage of the XS in each new perl release.
+.PP
+The file \fIembed.h\fR is generated automatically from
+\&\fIembed.pl\fR and \fIembed.fnc\fR.  \fIembed.pl\fR also creates the prototyping
+header files for the internal functions, generates the documentation
+and a lot of other bits and pieces.  It's important that when you add
+a new function to the core or change an existing one, you change the
+data in the table in \fIembed.fnc\fR as well.  Here's a sample entry from
+that table:
+.PP
+.Vb 1
+\&    Apd |SV**   |av_fetch   |AV* ar|I32 key|I32 lval
+.Ve
+.PP
+The first column is a set of flags, the second column the return type,
+the third column the name.  Columns after that are the arguments.
+The flags are documented at the top of \fIembed.fnc\fR.
+.PP
+If you edit \fIembed.pl\fR or \fIembed.fnc\fR, you will need to run
+\&\f(CW\*(C`make regen_headers\*(C'\fR to force a rebuild of \fIembed.h\fR and other
+auto-generated files.
+.SS "Formatted Printing of IVs, UVs, and NVs"
+.IX Subsection "Formatted Printing of IVs, UVs, and NVs"
+If you are printing IVs, UVs, or NVS instead of the \fBstdio\fR\|(3) style
+formatting codes like \f(CW%d\fR, \f(CW%ld\fR, \f(CW%f\fR, you should use the
+following macros for portability
+.PP
+.Vb 7
+\&        IVdf            IV in decimal
+\&        UVuf            UV in decimal
+\&        UVof            UV in octal
+\&        UVxf            UV in hexadecimal
+\&        NVef            NV %e\-like
+\&        NVff            NV %f\-like
+\&        NVgf            NV %g\-like
+.Ve
+.PP
+These will take care of 64\-bit integers and long doubles.
+For example:
+.PP
+.Vb 1
+\&        printf("IV is %" IVdf "\en", iv);
+.Ve
+.PP
+The \f(CW\*(C`IVdf\*(C'\fR will expand to whatever is the correct format for the IVs.
+Note that the spaces are required around the format in case the code is
+compiled with C++, to maintain compliance with its standard.
+.PP
+Note that there are different "long doubles": Perl will use
+whatever the compiler has.
+.PP
+If you are printing addresses of pointers, use \f(CW%p\fR or UVxf combined
+with \fBPTR2UV()\fR.
+.SS "Formatted Printing of SVs"
+.IX Subsection "Formatted Printing of SVs"
+The contents of SVs may be printed using the \f(CW\*(C`SVf\*(C'\fR format, like so:
+.PP
+.Vb 1
+\& Perl_croak(aTHX_ "This croaked because: %" SVf "\en", SVfARG(err_msg))
+.Ve
+.PP
+where \f(CW\*(C`err_msg\*(C'\fR is an SV.
+.PP
+Not all scalar types are printable.  Simple values certainly are: one of
+IV, UV, NV, or PV.  Also, if the SV is a reference to some value,
+either it will be dereferenced and the value printed, or information
+about the type of that value and its address are displayed.  The results
+of printing any other type of SV are undefined and likely to lead to an
+interpreter crash.  NVs are printed using a \f(CW%g\fR\-ish format.
+.PP
+Note that the spaces are required around the \f(CW\*(C`SVf\*(C'\fR in case the code is
+compiled with C++, to maintain compliance with its standard.
+.PP
+Note that any filehandle being printed to under UTF\-8 must be expecting
+UTF\-8 in order to get good results and avoid Wide-character warnings.
+One way to do this for typical filehandles is to invoke perl with the
+\&\f(CW\*(C`\-C\*(C'\fR parameter.  (See "\-C [number/list]" in perlrun.
+.PP
+You can use this to concatenate two scalars:
+.PP
+.Vb 4
+\& SV *var1 = get_sv("var1", GV_ADD);
+\& SV *var2 = get_sv("var2", GV_ADD);
+\& SV *var3 = newSVpvf("var1=%" SVf " and var2=%" SVf,
+\&                     SVfARG(var1), SVfARG(var2));
+.Ve
+.PP
+\&\f(CW\*(C`SVf_QUOTEDPREFIX\*(C'\fR is similar to \f(CW\*(C`SVf\*(C'\fR except that it restricts the
+number of the characters printed, showing at most the first
+\&\f(CW\*(C`PERL_QUOTEDPREFIX_LEN\*(C'\fR characters of the argument, and rendering it with
+double quotes and with the contents escaped using double quoted string
+escaping rules. If the string is longer than this then ellipses "..."
+will be appended after the trailing quote. This is intended for error
+messages where the string is assumed to be a class name.
+.PP
+\&\f(CW\*(C`HvNAMEf\*(C'\fR and \f(CW\*(C`HvNAMEf_QUOTEDPREFIX\*(C'\fR are similar to \f(CW\*(C`SVf\*(C'\fR except they
+extract the string, length and utf8 flags from the argument using the
+\&\f(CWHvNAME()\fR, \f(CWHvNAMELEN()\fR, \f(CWHvNAMEUTF8()\fR macros. This is intended
+for stringifying a class name directly from an stash HV.
+.SS "Formatted Printing of Strings"
+.IX Subsection "Formatted Printing of Strings"
+If you just want the bytes printed in a 7bit NUL-terminated string, you can
+just use \f(CW%s\fR (assuming they are all really only 7bit).  But if there is a
+possibility the value will be encoded as UTF\-8 or contains bytes above
+\&\f(CW0x7F\fR (and therefore 8bit), you should instead use the \f(CW\*(C`UTF8f\*(C'\fR format.
+And as its parameter, use the \f(CWUTF8fARG()\fR macro:
+.PP
+.Vb 1
+\& chr * msg;
+\&
+\& /* U+2018: \exE2\ex80\ex98 LEFT SINGLE QUOTATION MARK
+\&    U+2019: \exE2\ex80\ex99 RIGHT SINGLE QUOTATION MARK */
+\& if (can_utf8)
+\&   msg = "\exE2\ex80\ex98Uses fancy quotes\exE2\ex80\ex99";
+\& else
+\&   msg = "\*(AqUses simple quotes\*(Aq";
+\&
+\& Perl_croak(aTHX_ "The message is: %" UTF8f "\en",
+\&                  UTF8fARG(can_utf8, strlen(msg), msg));
+.Ve
+.PP
+The first parameter to \f(CW\*(C`UTF8fARG\*(C'\fR is a boolean: 1 if the string is in
+UTF\-8; 0 if string is in native byte encoding (Latin1).
+The second parameter is the number of bytes in the string to print.
+And the third and final parameter is a pointer to the first byte in the
+string.
+.PP
+Note that any filehandle being printed to under UTF\-8 must be expecting
+UTF\-8 in order to get good results and avoid Wide-character warnings.
+One way to do this for typical filehandles is to invoke perl with the
+\&\f(CW\*(C`\-C\*(C'\fR parameter.  (See "\-C [number/list]" in perlrun.
+.ie n .SS "Formatted Printing of ""Size_t"" and ""SSize_t"""
+.el .SS "Formatted Printing of \f(CWSize_t\fP and \f(CWSSize_t\fP"
+.IX Subsection "Formatted Printing of Size_t and SSize_t"
+The most general way to do this is to cast them to a UV or IV, and
+print as in the
+previous section.
+.PP
+But if you're using \f(CWPerlIO_printf()\fR, it's less typing and visual
+clutter to use the \f(CW%z\fR length modifier (for \fIsiZe\fR):
+.PP
+.Vb 1
+\&        PerlIO_printf("STRLEN is %zu\en", len);
+.Ve
+.PP
+This modifier is not portable, so its use should be restricted to
+\&\f(CWPerlIO_printf()\fR.
+.ie n .SS "Formatted Printing of ""Ptrdiff_t"", ""intmax_t"", ""short"" and other special sizes"
+.el .SS "Formatted Printing of \f(CWPtrdiff_t\fP, \f(CWintmax_t\fP, \f(CWshort\fP and other special sizes"
+.IX Subsection "Formatted Printing of Ptrdiff_t, intmax_t, short and other special sizes"
+There are modifiers for these special situations if you are using
+\&\f(CWPerlIO_printf()\fR.  See "size" in perlfunc.
+.SS "Pointer-To-Integer and Integer-To-Pointer"
+.IX Subsection "Pointer-To-Integer and Integer-To-Pointer"
+Because pointer size does not necessarily equal integer size,
+use the follow macros to do it right.
+.PP
+.Vb 4
+\&        PTR2UV(pointer)
+\&        PTR2IV(pointer)
+\&        PTR2NV(pointer)
+\&        INT2PTR(pointertotype, integer)
+.Ve
+.PP
+For example:
+.PP
+.Vb 2
+\&        IV  iv = ...;
+\&        SV *sv = INT2PTR(SV*, iv);
+.Ve
+.PP
+and
+.PP
+.Vb 2
+\&        AV *av = ...;
+\&        UV  uv = PTR2UV(av);
+.Ve
+.PP
+There are also
+.PP
+.Vb 2
+\& PTR2nat(pointer)   /* pointer to integer of PTRSIZE */
+\& PTR2ul(pointer)    /* pointer to unsigned long */
+.Ve
+.PP
+And \f(CW\*(C`PTRV\*(C'\fR which gives the native type for an integer the same size as
+pointers, such as \f(CW\*(C`unsigned\*(C'\fR or \f(CW\*(C`unsigned long\*(C'\fR.
+.SS "Exception Handling"
+.IX Subsection "Exception Handling"
+There are a couple of macros to do very basic exception handling in XS
+modules.  You have to define \f(CW\*(C`NO_XSLOCKS\*(C'\fR before including \fIXSUB.h\fR to
+be able to use these macros:
+.PP
+.Vb 2
+\&        #define NO_XSLOCKS
+\&        #include "XSUB.h"
+.Ve
+.PP
+You can use these macros if you call code that may croak, but you need
+to do some cleanup before giving control back to Perl.  For example:
+.PP
+.Vb 1
+\&        dXCPT;    /* set up necessary variables */
+\&
+\&        XCPT_TRY_START {
+\&          code_that_may_croak();
+\&        } XCPT_TRY_END
+\&
+\&        XCPT_CATCH
+\&        {
+\&          /* do cleanup here */
+\&          XCPT_RETHROW;
+\&        }
+.Ve
+.PP
+Note that you always have to rethrow an exception that has been
+caught.  Using these macros, it is not possible to just catch the
+exception and ignore it.  If you have to ignore the exception, you
+have to use the \f(CW\*(C`call_*\*(C'\fR function.
+.PP
+The advantage of using the above macros is that you don't have
+to setup an extra function for \f(CW\*(C`call_*\*(C'\fR, and that using these
+macros is faster than using \f(CW\*(C`call_*\*(C'\fR.
+.SS "Source Documentation"
+.IX Subsection "Source Documentation"
+There's an effort going on to document the internal functions and
+automatically produce reference manuals from them \-\- perlapi is one
+such manual which details all the functions which are available to XS
+writers.  perlintern is the autogenerated manual for the functions
+which are not part of the API and are supposedly for internal use only.
+.PP
+Source documentation is created by putting POD comments into the C
+source, like this:
+.PP
+.Vb 2
+\& /*
+\& =for apidoc sv_setiv
+\&
+\& Copies an integer into the given SV.  Does not handle \*(Aqset\*(Aq magic.  See
+\& L<perlapi/sv_setiv_mg>.
+\&
+\& =cut
+\& */
+.Ve
+.PP
+Please try and supply some documentation if you add functions to the
+Perl core.
+.SS "Backwards compatibility"
+.IX Subsection "Backwards compatibility"
+The Perl API changes over time.  New functions are
+added or the interfaces of existing functions are
+changed.  The \f(CW\*(C`Devel::PPPort\*(C'\fR module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+.PP
+\&\f(CW\*(C`Devel::PPPort\*(C'\fR generates a C header file \fIppport.h\fR that can also
+be run as a Perl script.  To generate \fIppport.h\fR, run:
+.PP
+.Vb 1
+\&    perl \-MDevel::PPPort \-eDevel::PPPort::WriteFile
+.Ve
+.PP
+Besides checking existing XS code, the script can also be used to retrieve
+compatibility information for various API calls using the \f(CW\*(C`\-\-api\-info\*(C'\fR
+command line switch.  For example:
+.PP
+.Vb 1
+\&  % perl ppport.h \-\-api\-info=sv_magicext
+.Ve
+.PP
+For details, see \f(CW\*(C`perldoc\ ppport.h\*(C'\fR.
+.SH "Unicode Support"
+.IX Header "Unicode Support"
+Perl 5.6.0 introduced Unicode support.  It's important for porters and XS
+writers to understand this support and make sure that the code they
+write does not corrupt Unicode data.
+.SS "What \fBis\fP Unicode, anyway?"
+.IX Subsection "What is Unicode, anyway?"
+In the olden, less enlightened times, we all used to use ASCII.  Most of
+us did, anyway.  The big problem with ASCII is that it's American.  Well,
+no, that's not actually the problem; the problem is that it's not
+particularly useful for people who don't use the Roman alphabet.  What
+used to happen was that particular languages would stick their own
+alphabet in the upper range of the sequence, between 128 and 255.  Of
+course, we then ended up with plenty of variants that weren't quite
+ASCII, and the whole point of it being a standard was lost.
+.PP
+Worse still, if you've got a language like Chinese or
+Japanese that has hundreds or thousands of characters, then you really
+can't fit them into a mere 256, so they had to forget about ASCII
+altogether, and build their own systems using pairs of numbers to refer
+to one character.
+.PP
+To fix this, some people formed Unicode, Inc. and
+produced a new character set containing all the characters you can
+possibly think of and more.  There are several ways of representing these
+characters, and the one Perl uses is called UTF\-8.  UTF\-8 uses
+a variable number of bytes to represent a character.  You can learn more
+about Unicode and Perl's Unicode model in perlunicode.
+.PP
+(On EBCDIC platforms, Perl uses instead UTF-EBCDIC, which is a form of
+UTF\-8 adapted for EBCDIC platforms.  Below, we just talk about UTF\-8.
+UTF-EBCDIC is like UTF\-8, but the details are different.  The macros
+hide the differences from you, just remember that the particular numbers
+and bit patterns presented below will differ in UTF-EBCDIC.)
+.SS "How can I recognise a UTF\-8 string?"
+.IX Subsection "How can I recognise a UTF-8 string?"
+You can't.  This is because UTF\-8 data is stored in bytes just like
+non\-UTF\-8 data.  The Unicode character 200, (\f(CW0xC8\fR for you hex types)
+capital E with a grave accent, is represented by the two bytes
+\&\f(CW\*(C`v196.172\*(C'\fR.  Unfortunately, the non-Unicode string \f(CW\*(C`chr(196).chr(172)\*(C'\fR
+has that byte sequence as well.  So you can't tell just by looking \-\- this
+is what makes Unicode input an interesting problem.
+.PP
+In general, you either have to know what you're dealing with, or you
+have to guess.  The API function \f(CW\*(C`is_utf8_string\*(C'\fR can help; it'll tell
+you if a string contains only valid UTF\-8 characters, and the chances
+of a non\-UTF\-8 string looking like valid UTF\-8 become very small very
+quickly with increasing string length.  On a character-by-character
+basis, \f(CW\*(C`isUTF8_CHAR\*(C'\fR
+will tell you whether the current character in a string is valid UTF\-8.
+.SS "How does UTF\-8 represent Unicode characters?"
+.IX Subsection "How does UTF-8 represent Unicode characters?"
+As mentioned above, UTF\-8 uses a variable number of bytes to store a
+character.  Characters with values 0...127 are stored in one
+byte, just like good ol' ASCII.  Character 128 is stored as
+\&\f(CW\*(C`v194.128\*(C'\fR; this continues up to character 191, which is
+\&\f(CW\*(C`v194.191\*(C'\fR.  Now we've run out of bits (191 is binary
+\&\f(CW10111111\fR) so we move on; character 192 is \f(CW\*(C`v195.128\*(C'\fR.  And
+so it goes on, moving to three bytes at character 2048.
+"Unicode Encodings" in perlunicode has pictures of how this works.
+.PP
+Assuming you know you're dealing with a UTF\-8 string, you can find out
+how long the first character in it is with the \f(CW\*(C`UTF8SKIP\*(C'\fR macro:
+.PP
+.Vb 2
+\&    char *utf = "\e305\e233\e340\e240\e201";
+\&    I32 len;
+\&
+\&    len = UTF8SKIP(utf); /* len is 2 here */
+\&    utf += len;
+\&    len = UTF8SKIP(utf); /* len is 3 here */
+.Ve
+.PP
+Another way to skip over characters in a UTF\-8 string is to use
+\&\f(CW\*(C`utf8_hop\*(C'\fR, which takes a string and a number of characters to skip
+over.  You're on your own about bounds checking, though, so don't use it
+lightly.
+.PP
+All bytes in a multi-byte UTF\-8 character will have the high bit set,
+so you can test if you need to do something special with this
+character like this (the \f(CWUTF8_IS_INVARIANT()\fR is a macro that tests
+whether the byte is encoded as a single byte even in UTF\-8):
+.PP
+.Vb 7
+\&    U8 *utf;     /* Initialize this to point to the beginning of the
+\&                    sequence to convert */
+\&    U8 *utf_end; /* Initialize this to 1 beyond the end of the sequence
+\&                    pointed to by \*(Aqutf\*(Aq */
+\&    UV uv;       /* Returned code point; note: a UV, not a U8, not a
+\&                    char */
+\&    STRLEN len; /* Returned length of character in bytes */
+\&
+\&    if (!UTF8_IS_INVARIANT(*utf))
+\&        /* Must treat this as UTF\-8 */
+\&        uv = utf8_to_uvchr_buf(utf, utf_end, &len);
+\&    else
+\&        /* OK to treat this character as a byte */
+\&        uv = *utf;
+.Ve
+.PP
+You can also see in that example that we use \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR to get the
+value of the character; the inverse function \f(CW\*(C`uvchr_to_utf8\*(C'\fR is available
+for putting a UV into UTF\-8:
+.PP
+.Vb 6
+\&    if (!UVCHR_IS_INVARIANT(uv))
+\&        /* Must treat this as UTF8 */
+\&        utf8 = uvchr_to_utf8(utf8, uv);
+\&    else
+\&        /* OK to treat this character as a byte */
+\&        *utf8++ = uv;
+.Ve
+.PP
+You \fBmust\fR convert characters to UVs using the above functions if
+you're ever in a situation where you have to match UTF\-8 and non\-UTF\-8
+characters.  You may not skip over UTF\-8 characters in this case.  If you
+do this, you'll lose the ability to match hi-bit non\-UTF\-8 characters;
+for instance, if your UTF\-8 string contains \f(CW\*(C`v196.172\*(C'\fR, and you skip
+that character, you can never match a \f(CWchr(200)\fR in a non\-UTF\-8 string.
+So don't do that!
+.PP
+(Note that we don't have to test for invariant characters in the
+examples above.  The functions work on any well-formed UTF\-8 input.
+It's just that its faster to avoid the function overhead when it's not
+needed.)
+.SS "How does Perl store UTF\-8 strings?"
+.IX Subsection "How does Perl store UTF-8 strings?"
+Currently, Perl deals with UTF\-8 strings and non\-UTF\-8 strings
+slightly differently.  A flag in the SV, \f(CW\*(C`SVf_UTF8\*(C'\fR, indicates that the
+string is internally encoded as UTF\-8.  Without it, the byte value is the
+codepoint number and vice versa.  This flag is only meaningful if the SV
+is \f(CW\*(C`SvPOK\*(C'\fR or immediately after stringification via \f(CW\*(C`SvPV\*(C'\fR or a
+similar macro.  You can check and manipulate this flag with the
+following macros:
+.PP
+.Vb 3
+\&    SvUTF8(sv)
+\&    SvUTF8_on(sv)
+\&    SvUTF8_off(sv)
+.Ve
+.PP
+This flag has an important effect on Perl's treatment of the string: if
+UTF\-8 data is not properly distinguished, regular expressions,
+\&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`substr\*(C'\fR and other string handling operations will have
+undesirable (wrong) results.
+.PP
+The problem comes when you have, for instance, a string that isn't
+flagged as UTF\-8, and contains a byte sequence that could be UTF\-8 \-\-
+especially when combining non\-UTF\-8 and UTF\-8 strings.
+.PP
+Never forget that the \f(CW\*(C`SVf_UTF8\*(C'\fR flag is separate from the PV value; you
+need to be sure you don't accidentally knock it off while you're
+manipulating SVs.  More specifically, you cannot expect to do this:
+.PP
+.Vb 4
+\&    SV *sv;
+\&    SV *nsv;
+\&    STRLEN len;
+\&    char *p;
+\&
+\&    p = SvPV(sv, len);
+\&    frobnicate(p);
+\&    nsv = newSVpvn(p, len);
+.Ve
+.PP
+The \f(CW\*(C`char*\*(C'\fR string does not tell you the whole story, and you can't
+copy or reconstruct an SV just by copying the string value.  Check if the
+old SV has the UTF8 flag set (\fIafter\fR the \f(CW\*(C`SvPV\*(C'\fR call), and act
+accordingly:
+.PP
+.Vb 6
+\&    p = SvPV(sv, len);
+\&    is_utf8 = SvUTF8(sv);
+\&    frobnicate(p, is_utf8);
+\&    nsv = newSVpvn(p, len);
+\&    if (is_utf8)
+\&        SvUTF8_on(nsv);
+.Ve
+.PP
+In the above, your \f(CW\*(C`frobnicate\*(C'\fR function has been changed to be made
+aware of whether or not it's dealing with UTF\-8 data, so that it can
+handle the string appropriately.
+.PP
+Since just passing an SV to an XS function and copying the data of
+the SV is not enough to copy the UTF8 flags, even less right is just
+passing a \f(CW\*(C`char\ *\*(C'\fR to an XS function.
+.PP
+For full generality, use the \f(CW\*(C`DO_UTF8\*(C'\fR macro to see if the
+string in an SV is to be \fItreated\fR as UTF\-8.  This takes into account
+if the call to the XS function is being made from within the scope of
+\&\f(CW\*(C`use\ bytes\*(C'\fR.  If so, the underlying bytes that comprise the
+UTF\-8 string are to be exposed, rather than the character they
+represent.  But this pragma should only really be used for debugging and
+perhaps low-level testing at the byte level.  Hence most XS code need
+not concern itself with this, but various areas of the perl core do need
+to support it.
+.PP
+And this isn't the whole story.  Starting in Perl v5.12, strings that
+aren't encoded in UTF\-8 may also be treated as Unicode under various
+conditions (see "ASCII Rules versus Unicode Rules" in perlunicode).
+This is only really a problem for characters whose ordinals are between
+128 and 255, and their behavior varies under ASCII versus Unicode rules
+in ways that your code cares about (see "The "Unicode Bug"" in perlunicode).
+There is no published API for dealing with this, as it is subject to
+change, but you can look at the code for \f(CW\*(C`pp_lc\*(C'\fR in \fIpp.c\fR for an
+example as to how it's currently done.
+.SS "How do I pass a Perl string to a C library?"
+.IX Subsection "How do I pass a Perl string to a C library?"
+A Perl string, conceptually, is an opaque sequence of code points.
+Many C libraries expect their inputs to be "classical" C strings, which are
+arrays of octets 1\-255, terminated with a NUL byte. Your job when writing
+an interface between Perl and a C library is to define the mapping between
+Perl and that library.
+.PP
+Generally speaking, \f(CW\*(C`SvPVbyte\*(C'\fR and related macros suit this task well.
+These assume that your Perl string is a "byte string", i.e., is either
+raw, undecoded input into Perl or is pre-encoded to, e.g., UTF\-8.
+.PP
+Alternatively, if your C library expects UTF\-8 text, you can use
+\&\f(CW\*(C`SvPVutf8\*(C'\fR and related macros. This has the same effect as encoding
+to UTF\-8 then calling the corresponding \f(CW\*(C`SvPVbyte\*(C'\fR\-related macro.
+.PP
+Some C libraries may expect other encodings (e.g., UTF\-16LE). To give
+Perl strings to such libraries
+you must either do that encoding in Perl then use \f(CW\*(C`SvPVbyte\*(C'\fR, or
+use an intermediary C library to convert from however Perl stores the
+string to the desired encoding.
+.PP
+Take care also that NULs in your Perl string don't confuse the C
+library. If possible, give the string's length to the C library; if that's
+not possible, consider rejecting strings that contain NUL bytes.
+.PP
+\fIWhat about \fR\f(CI\*(C`SvPV\*(C'\fR\fI, \fR\f(CI\*(C`SvPV_nolen\*(C'\fR\fI, etc.?\fR
+.IX Subsection "What about SvPV, SvPV_nolen, etc.?"
+.PP
+Consider a 3\-character Perl string \f(CW\*(C`$foo = "\ex64\ex78\ex8c"\*(C'\fR.
+Perl can store these 3 characters either of two ways:
+.IP \(bu 4
+bytes: 0x64 0x78 0x8c
+.IP \(bu 4
+UTF\-8: 0x64 0x78 0xc2 0x8c
+.PP
+Now let's say you convert \f(CW$foo\fR to a C string thus:
+.PP
+.Vb 2
+\&    STRLEN strlen;
+\&    char *str = SvPV(foo_sv, strlen);
+.Ve
+.PP
+At this point \f(CW\*(C`str\*(C'\fR could point to a 3\-byte C string or a 4\-byte one.
+.PP
+Generally speaking, we want \f(CW\*(C`str\*(C'\fR to be the same regardless of how
+Perl stores \f(CW$foo\fR, so the ambiguity here is undesirable. \f(CW\*(C`SvPVbyte\*(C'\fR
+and \f(CW\*(C`SvPVutf8\*(C'\fR solve that by giving predictable output: use
+\&\f(CW\*(C`SvPVbyte\*(C'\fR if your C library expects byte strings, or \f(CW\*(C`SvPVutf8\*(C'\fR
+if it expects UTF\-8.
+.PP
+If your C library happens to support both encodings, then \f(CW\*(C`SvPV\*(C'\fR\-\-always
+in tandem with lookups to \f(CW\*(C`SvUTF8\*(C'\fR!\-\-may be safe and (slightly) more
+efficient.
+.PP
+\&\fBTESTING\fR \fBTIP:\fR Use utf8's \f(CW\*(C`upgrade\*(C'\fR and \f(CW\*(C`downgrade\*(C'\fR functions
+in your tests to ensure consistent handling regardless of Perl's
+internal encoding.
+.SS "How do I convert a string to UTF\-8?"
+.IX Subsection "How do I convert a string to UTF-8?"
+If you're mixing UTF\-8 and non\-UTF\-8 strings, it is necessary to upgrade
+the non\-UTF\-8 strings to UTF\-8.  If you've got an SV, the easiest way to do
+this is:
+.PP
+.Vb 1
+\&    sv_utf8_upgrade(sv);
+.Ve
+.PP
+However, you must not do this, for example:
+.PP
+.Vb 2
+\&    if (!SvUTF8(left))
+\&        sv_utf8_upgrade(left);
+.Ve
+.PP
+If you do this in a binary operator, you will actually change one of the
+strings that came into the operator, and, while it shouldn't be noticeable
+by the end user, it can cause problems in deficient code.
+.PP
+Instead, \f(CW\*(C`bytes_to_utf8\*(C'\fR will give you a UTF\-8\-encoded \fBcopy\fR of its
+string argument.  This is useful for having the data available for
+comparisons and so on, without harming the original SV.  There's also
+\&\f(CW\*(C`utf8_to_bytes\*(C'\fR to go the other way, but naturally, this will fail if
+the string contains any characters above 255 that can't be represented
+in a single byte.
+.SS "How do I compare strings?"
+.IX Subsection "How do I compare strings?"
+"sv_cmp" in perlapi and "sv_cmp_flags" in perlapi do a lexigraphic
+comparison of two SV's, and handle UTF\-8ness properly.  Note, however,
+that Unicode specifies a much fancier mechanism for collation, available
+via the Unicode::Collate module.
+.PP
+To just compare two strings for equality/non\-equality, you can just use
+\&\f(CWmemEQ()\fR and \f(CWmemNE()\fR as usual,
+except the strings must be both UTF\-8 or not UTF\-8 encoded.
+.PP
+To compare two strings case-insensitively, use
+\&\f(CWfoldEQ_utf8()\fR (the strings don't have to have
+the same UTF\-8ness).
+.SS "Is there anything else I need to know?"
+.IX Subsection "Is there anything else I need to know?"
+Not really.  Just remember these things:
+.IP \(bu 3
+There's no way to tell if a \f(CW\*(C`char\ *\*(C'\fR or \f(CW\*(C`U8\ *\*(C'\fR string is UTF\-8
+or not.  But you can tell if an SV is to be treated as UTF\-8 by calling
+\&\f(CW\*(C`DO_UTF8\*(C'\fR on it, after stringifying it with \f(CW\*(C`SvPV\*(C'\fR or a similar
+macro.  And, you can tell if SV is actually UTF\-8 (even if it is not to
+be treated as such) by looking at its \f(CW\*(C`SvUTF8\*(C'\fR flag (again after
+stringifying it).  Don't forget to set the flag if something should be
+UTF\-8.
+Treat the flag as part of the PV, even though it's not \-\- if you pass on
+the PV to somewhere, pass on the flag too.
+.IP \(bu 3
+If a string is UTF\-8, \fBalways\fR use \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR to get at the value,
+unless \f(CWUTF8_IS_INVARIANT(*s)\fR in which case you can use \f(CW*s\fR.
+.IP \(bu 3
+When writing a character UV to a UTF\-8 string, \fBalways\fR use
+\&\f(CW\*(C`uvchr_to_utf8\*(C'\fR, unless \f(CW\*(C`UVCHR_IS_INVARIANT(uv))\*(C'\fR in which case
+you can use \f(CW\*(C`*s = uv\*(C'\fR.
+.IP \(bu 3
+Mixing UTF\-8 and non\-UTF\-8 strings is
+tricky.  Use \f(CW\*(C`bytes_to_utf8\*(C'\fR to get
+a new string which is UTF\-8 encoded, and then combine them.
+.SH "Custom Operators"
+.IX Header "Custom Operators"
+Custom operator support is an experimental feature that allows you to
+define your own ops.  This is primarily to allow the building of
+interpreters for other languages in the Perl core, but it also allows
+optimizations through the creation of "macro-ops" (ops which perform the
+functions of multiple ops which are usually executed together, such as
+\&\f(CW\*(C`gvsv, gvsv, add\*(C'\fR.)
+.PP
+This feature is implemented as a new op type, \f(CW\*(C`OP_CUSTOM\*(C'\fR.  The Perl
+core does not "know" anything special about this op type, and so it will
+not be involved in any optimizations.  This also means that you can
+define your custom ops to be any op structure \-\- unary, binary, list and
+so on \-\- you like.
+.PP
+It's important to know what custom operators won't do for you.  They
+won't let you add new syntax to Perl, directly.  They won't even let you
+add new keywords, directly.  In fact, they won't change the way Perl
+compiles a program at all.  You have to do those changes yourself, after
+Perl has compiled the program.  You do this either by manipulating the op
+tree using a \f(CW\*(C`CHECK\*(C'\fR block and the \f(CW\*(C`B::Generate\*(C'\fR module, or by adding
+a custom peephole optimizer with the \f(CW\*(C`optimize\*(C'\fR module.
+.PP
+When you do this, you replace ordinary Perl ops with custom ops by
+creating ops with the type \f(CW\*(C`OP_CUSTOM\*(C'\fR and the \f(CW\*(C`op_ppaddr\*(C'\fR of your own
+PP function.  This should be defined in XS code, and should look like
+the PP ops in \f(CW\*(C`pp_*.c\*(C'\fR.  You are responsible for ensuring that your op
+takes the appropriate number of values from the stack, and you are
+responsible for adding stack marks if necessary.
+.PP
+You should also "register" your op with the Perl interpreter so that it
+can produce sensible error and warning messages.  Since it is possible to
+have multiple custom ops within the one "logical" op type \f(CW\*(C`OP_CUSTOM\*(C'\fR,
+Perl uses the value of \f(CW\*(C`o\->op_ppaddr\*(C'\fR to determine which custom op
+it is dealing with.  You should create an \f(CW\*(C`XOP\*(C'\fR structure for each
+ppaddr you use, set the properties of the custom op with
+\&\f(CW\*(C`XopENTRY_set\*(C'\fR, and register the structure against the ppaddr using
+\&\f(CW\*(C`Perl_custom_op_register\*(C'\fR.  A trivial example might look like:
+.PP
+.Vb 2
+\&    static XOP my_xop;
+\&    static OP *my_pp(pTHX);
+\&
+\&    BOOT:
+\&        XopENTRY_set(&my_xop, xop_name, "myxop");
+\&        XopENTRY_set(&my_xop, xop_desc, "Useless custom op");
+\&        Perl_custom_op_register(aTHX_ my_pp, &my_xop);
+.Ve
+.PP
+The available fields in the structure are:
+.IP xop_name 4
+.IX Item "xop_name"
+A short name for your op.  This will be included in some error messages,
+and will also be returned as \f(CW\*(C`$op\->name\*(C'\fR by the B module, so
+it will appear in the output of module like B::Concise.
+.IP xop_desc 4
+.IX Item "xop_desc"
+A short description of the function of the op.
+.IP xop_class 4
+.IX Item "xop_class"
+Which of the various \f(CW*OP\fR structures this op uses.  This should be one of
+the \f(CW\*(C`OA_*\*(C'\fR constants from \fIop.h\fR, namely
+.RS 4
+.IP OA_BASEOP 4
+.IX Item "OA_BASEOP"
+.PD 0
+.IP OA_UNOP 4
+.IX Item "OA_UNOP"
+.IP OA_BINOP 4
+.IX Item "OA_BINOP"
+.IP OA_LOGOP 4
+.IX Item "OA_LOGOP"
+.IP OA_LISTOP 4
+.IX Item "OA_LISTOP"
+.IP OA_PMOP 4
+.IX Item "OA_PMOP"
+.IP OA_SVOP 4
+.IX Item "OA_SVOP"
+.IP OA_PADOP 4
+.IX Item "OA_PADOP"
+.IP OA_PVOP_OR_SVOP 4
+.IX Item "OA_PVOP_OR_SVOP"
+.PD
+This should be interpreted as '\f(CW\*(C`PVOP\*(C'\fR' only.  The \f(CW\*(C`_OR_SVOP\*(C'\fR is because
+the only core \f(CW\*(C`PVOP\*(C'\fR, \f(CW\*(C`OP_TRANS\*(C'\fR, can sometimes be a \f(CW\*(C`SVOP\*(C'\fR instead.
+.IP OA_LOOP 4
+.IX Item "OA_LOOP"
+.PD 0
+.IP OA_COP 4
+.IX Item "OA_COP"
+.RE
+.RS 4
+.PD
+.Sp
+The other \f(CW\*(C`OA_*\*(C'\fR constants should not be used.
+.RE
+.IP xop_peep 4
+.IX Item "xop_peep"
+This member is of type \f(CW\*(C`Perl_cpeep_t\*(C'\fR, which expands to \f(CW\*(C`void
+(*Perl_cpeep_t)(aTHX_ OP *o, OP *oldop)\*(C'\fR.  If it is set, this function
+will be called from \f(CW\*(C`Perl_rpeep\*(C'\fR when ops of this type are encountered
+by the peephole optimizer.  \fIo\fR is the OP that needs optimizing;
+\&\fIoldop\fR is the previous OP optimized, whose \f(CW\*(C`op_next\*(C'\fR points to \fIo\fR.
+.PP
+\&\f(CW\*(C`B::Generate\*(C'\fR directly supports the creation of custom ops by name.
+.SH Stacks
+.IX Header "Stacks"
+Descriptions above occasionally refer to "the stack", but there are in fact
+many stack-like data structures within the perl interpreter. When otherwise
+unqualified, "the stack" usually refers to the value stack.
+.PP
+The various stacks have different purposes, and operate in slightly different
+ways. Their differences are noted below.
+.SS "Value Stack"
+.IX Subsection "Value Stack"
+This stack stores the values that regular perl code is operating on, usually
+intermediate values of expressions within a statement. The stack itself is
+formed of an array of SV pointers.
+.PP
+The base of this stack is pointed to by the interpreter variable
+\&\f(CW\*(C`PL_stack_base\*(C'\fR, of type \f(CW\*(C`SV **\*(C'\fR.
+.PP
+The head of the stack is \f(CW\*(C`PL_stack_sp\*(C'\fR, and points to the most
+recently-pushed item.
+.PP
+Items are pushed to the stack by using the \f(CWPUSHs()\fR macro or its variants
+described above; \f(CWXPUSHs()\fR, \f(CWmPUSHs()\fR, \f(CWmXPUSHs()\fR and the typed
+versions. Note carefully that the non\-\f(CW\*(C`X\*(C'\fR versions of these macros do not
+check the size of the stack and assume it to be big enough. These must be
+paired with a suitable check of the stack's size, such as the \f(CW\*(C`EXTEND\*(C'\fR macro
+to ensure it is large enough. For example
+.PP
+.Vb 5
+\&    EXTEND(SP, 4);
+\&    mPUSHi(10);
+\&    mPUSHi(20);
+\&    mPUSHi(30);
+\&    mPUSHi(40);
+.Ve
+.PP
+This is slightly more performant than making four separate checks in four
+separate \f(CWmXPUSHi()\fR calls.
+.PP
+As a further performance optimisation, the various \f(CW\*(C`PUSH\*(C'\fR macros all operate
+using a local variable \f(CW\*(C`SP\*(C'\fR, rather than the interpreter-global variable
+\&\f(CW\*(C`PL_stack_sp\*(C'\fR. This variable is declared by the \f(CW\*(C`dSP\*(C'\fR macro \- though it is
+normally implied by XSUBs and similar so it is rare you have to consider it
+directly. Once declared, the \f(CW\*(C`PUSH\*(C'\fR macros will operate only on this local
+variable, so before invoking any other perl core functions you must use the
+\&\f(CW\*(C`PUTBACK\*(C'\fR macro to return the value from the local \f(CW\*(C`SP\*(C'\fR variable back to
+the interpreter variable. Similarly, after calling a perl core function which
+may have had reason to move the stack or push/pop values to it, you must use
+the \f(CW\*(C`SPAGAIN\*(C'\fR macro which refreshes the local \f(CW\*(C`SP\*(C'\fR value back from the
+interpreter one.
+.PP
+Items are popped from the stack by using the \f(CW\*(C`POPs\*(C'\fR macro or its typed
+versions, There is also a macro \f(CW\*(C`TOPs\*(C'\fR that inspects the topmost item without
+removing it.
+.PP
+Note specifically that SV pointers on the value stack do not contribute to the
+overall reference count of the xVs being referred to. If newly-created xVs are
+being pushed to the stack you must arrange for them to be destroyed at a
+suitable time; usually by using one of the \f(CW\*(C`mPUSH*\*(C'\fR macros or \f(CWsv_2mortal()\fR
+to mortalise the xV.
+.SS "Mark Stack"
+.IX Subsection "Mark Stack"
+The value stack stores individual perl scalar values as temporaries between
+expressions. Some perl expressions operate on entire lists; for that purpose
+we need to know where on the stack each list begins. This is the purpose of the
+mark stack.
+.PP
+The mark stack stores integers as I32 values, which are the height of the
+value stack at the time before the list began; thus the mark itself actually
+points to the value stack entry one before the list. The list itself starts at
+\&\f(CW\*(C`mark + 1\*(C'\fR.
+.PP
+The base of this stack is pointed to by the interpreter variable
+\&\f(CW\*(C`PL_markstack\*(C'\fR, of type \f(CW\*(C`I32 *\*(C'\fR.
+.PP
+The head of the stack is \f(CW\*(C`PL_markstack_ptr\*(C'\fR, and points to the most
+recently-pushed item.
+.PP
+Items are pushed to the stack by using the \f(CWPUSHMARK()\fR macro. Even though
+the stack itself stores (value) stack indices as integers, the \f(CW\*(C`PUSHMARK\*(C'\fR
+macro should be given a stack pointer directly; it will calculate the index
+offset by comparing to the \f(CW\*(C`PL_stack_sp\*(C'\fR variable. Thus almost always the
+code to perform this is
+.PP
+.Vb 1
+\&    PUSHMARK(SP);
+.Ve
+.PP
+Items are popped from the stack by the \f(CW\*(C`POPMARK\*(C'\fR macro. There is also a macro
+\&\f(CW\*(C`TOPMARK\*(C'\fR that inspects the topmost item without removing it. These macros
+return I32 index values directly. There is also the \f(CW\*(C`dMARK\*(C'\fR macro which
+declares a new SV double-pointer variable, called \f(CW\*(C`mark\*(C'\fR, which points at the
+marked stack slot; this is the usual macro that C code will use when operating
+on lists given on the stack.
+.PP
+As noted above, the \f(CW\*(C`mark\*(C'\fR variable itself will point at the most recently
+pushed value on the value stack before the list begins, and so the list itself
+starts at \f(CW\*(C`mark + 1\*(C'\fR. The values of the list may be iterated by code such as
+.PP
+.Vb 4
+\&    for(SV **svp = mark + 1; svp <= PL_stack_sp; svp++) {
+\&      SV *item = *svp;
+\&      ...
+\&    }
+.Ve
+.PP
+Note specifically in the case that the list is already empty, \f(CW\*(C`mark\*(C'\fR will
+equal \f(CW\*(C`PL_stack_sp\*(C'\fR.
+.PP
+Because the \f(CW\*(C`mark\*(C'\fR variable is converted to a pointer on the value stack,
+extra care must be taken if \f(CW\*(C`EXTEND\*(C'\fR or any of the \f(CW\*(C`XPUSH\*(C'\fR macros are
+invoked within the function, because the stack may need to be moved to
+extend it and so the existing pointer will now be invalid. If this may be a
+problem, a possible solution is to track the mark offset as an integer and
+track the mark itself later on after the stack had been moved.
+.PP
+.Vb 1
+\&    I32 markoff = POPMARK;
+\&
+\&    ...
+\&
+\&    SP **mark = PL_stack_base + markoff;
+.Ve
+.SS "Temporaries Stack"
+.IX Subsection "Temporaries Stack"
+As noted above, xV references on the main value stack do not contribute to the
+reference count of an xV, and so another mechanism is used to track when
+temporary values which live on the stack must be released. This is the job of
+the temporaries stack.
+.PP
+The temporaries stack stores pointers to xVs whose reference counts will be
+decremented soon.
+.PP
+The base of this stack is pointed to by the interpreter variable
+\&\f(CW\*(C`PL_tmps_stack\*(C'\fR, of type \f(CW\*(C`SV **\*(C'\fR.
+.PP
+The head of the stack is indexed by \f(CW\*(C`PL_tmps_ix\*(C'\fR, an integer which stores the
+index in the array of the most recently-pushed item.
+.PP
+There is no public API to directly push items to the temporaries stack. Instead,
+the API function \f(CWsv_2mortal()\fR is used to mortalize an xV, adding its
+address to the temporaries stack.
+.PP
+Likewise, there is no public API to read values from the temporaries stack.
+Instead, the macros \f(CW\*(C`SAVETMPS\*(C'\fR and \f(CW\*(C`FREETMPS\*(C'\fR are used. The \f(CW\*(C`SAVETMPS\*(C'\fR
+macro establishes the base levels of the temporaries stack, by capturing the
+current value of \f(CW\*(C`PL_tmps_ix\*(C'\fR into \f(CW\*(C`PL_tmps_floor\*(C'\fR and saving the previous
+value to the save stack. Thereafter, whenever \f(CW\*(C`FREETMPS\*(C'\fR is invoked all of
+the temporaries that have been pushed since that level are reclaimed.
+.PP
+While it is common to see these two macros in pairs within an \f(CW\*(C`ENTER\*(C'\fR/
+\&\f(CW\*(C`LEAVE\*(C'\fR pair, it is not necessary to match them. It is permitted to invoke
+\&\f(CW\*(C`FREETMPS\*(C'\fR multiple times since the most recent \f(CW\*(C`SAVETMPS\*(C'\fR; for example in a
+loop iterating over elements of a list. While you can invoke \f(CW\*(C`SAVETMPS\*(C'\fR
+multiple times within a scope pair, it is unlikely to be useful. Subsequent
+invocations will move the temporaries floor further up, thus effectively
+trapping the existing temporaries to only be released at the end of the scope.
+.SS "Save Stack"
+.IX Subsection "Save Stack"
+The save stack is used by perl to implement the \f(CW\*(C`local\*(C'\fR keyword and other
+similar behaviours; any cleanup operations that need to be performed when
+leaving the current scope. Items pushed to this stack generally capture the
+current value of some internal variable or state, which will be restored when
+the scope is unwound due to leaving, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`goto\*(C'\fR or other
+reasons.
+.PP
+Whereas other perl internal stacks store individual items all of the same type
+(usually SV pointers or integers), the items pushed to the save stack are
+formed of many different types, having multiple fields to them. For example,
+the \f(CW\*(C`SAVEt_INT\*(C'\fR type needs to store both the address of the \f(CW\*(C`int\*(C'\fR variable
+to restore, and the value to restore it to. This information could have been
+stored using fields of a \f(CW\*(C`struct\*(C'\fR, but would have to be large enough to store
+three pointers in the largest case, which would waste a lot of space in most
+of the smaller cases.
+.PP
+Instead, the stack stores information in a variable-length encoding of \f(CW\*(C`ANY\*(C'\fR
+structures. The final value pushed is stored in the \f(CW\*(C`UV\*(C'\fR field which encodes
+the kind of item held by the preceding items; the count and types of which
+will depend on what kind of item is being stored. The kind field is pushed
+last because that will be the first field to be popped when unwinding items
+from the stack.
+.PP
+The base of this stack is pointed to by the interpreter variable
+\&\f(CW\*(C`PL_savestack\*(C'\fR, of type \f(CW\*(C`ANY *\*(C'\fR.
+.PP
+The head of the stack is indexed by \f(CW\*(C`PL_savestack_ix\*(C'\fR, an integer which
+stores the index in the array at which the next item should be pushed. (Note
+that this is different to most other stacks, which reference the most
+recently-pushed item).
+.PP
+Items are pushed to the save stack by using the various \f(CW\*(C`SAVE...()\*(C'\fR macros.
+Many of these macros take a variable and store both its address and current
+value on the save stack, ensuring that value gets restored on scope exit.
+.PP
+.Vb 5
+\&    SAVEI8(i8)
+\&    SAVEI16(i16)
+\&    SAVEI32(i32)
+\&    SAVEINT(i)
+\&    ...
+.Ve
+.PP
+There are also a variety of other special-purpose macros which save particular
+types or values of interest. \f(CW\*(C`SAVETMPS\*(C'\fR has already been mentioned above.
+Others include \f(CW\*(C`SAVEFREEPV\*(C'\fR which arranges for a PV (i.e. a string buffer) to
+be freed, or \f(CW\*(C`SAVEDESTRUCTOR\*(C'\fR which arranges for a given function pointer to
+be invoked on scope exit. A full list of such macros can be found in
+\&\fIscope.h\fR.
+.PP
+There is no public API for popping individual values or items from the save
+stack. Instead, via the scope stack, the \f(CW\*(C`ENTER\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR pair form a way
+to start and stop nested scopes. Leaving a nested scope via \f(CW\*(C`LEAVE\*(C'\fR will
+restore all of the saved values that had been pushed since the most recent
+\&\f(CW\*(C`ENTER\*(C'\fR.
+.SS "Scope Stack"
+.IX Subsection "Scope Stack"
+As with the mark stack to the value stack, the scope stack forms a pair with
+the save stack. The scope stack stores the height of the save stack at which
+nested scopes begin, and allows the save stack to be unwound back to that
+point when the scope is left.
+.PP
+When perl is built with debugging enabled, there is a second part to this
+stack storing human-readable string names describing the type of stack
+context. Each push operation saves the name as well as the height of the save
+stack, and each pop operation checks the topmost name with what is expected,
+causing an assertion failure if the name does not match.
+.PP
+The base of this stack is pointed to by the interpreter variable
+\&\f(CW\*(C`PL_scopestack\*(C'\fR, of type \f(CW\*(C`I32 *\*(C'\fR. If enabled, the scope stack names are
+stored in a separate array pointed to by \f(CW\*(C`PL_scopestack_name\*(C'\fR, of type
+\&\f(CW\*(C`const char **\*(C'\fR.
+.PP
+The head of the stack is indexed by \f(CW\*(C`PL_scopestack_ix\*(C'\fR, an integer which
+stores the index of the array or arrays at which the next item should be
+pushed. (Note that this is different to most other stacks, which reference the
+most recently-pushed item).
+.PP
+Values are pushed to the scope stack using the \f(CW\*(C`ENTER\*(C'\fR macro, which begins a
+new nested scope. Any items pushed to the save stack are then restored at the
+next nested invocation of the \f(CW\*(C`LEAVE\*(C'\fR macro.
+.SH "Dynamic Scope and the Context Stack"
+.IX Header "Dynamic Scope and the Context Stack"
+\&\fBNote:\fR this section describes a non-public internal API that is subject
+to change without notice.
+.SS "Introduction to the context stack"
+.IX Subsection "Introduction to the context stack"
+In Perl, dynamic scoping refers to the runtime nesting of things like
+subroutine calls, evals etc, as well as the entering and exiting of block
+scopes. For example, the restoring of a \f(CW\*(C`local\*(C'\fRised variable is
+determined by the dynamic scope.
+.PP
+Perl tracks the dynamic scope by a data structure called the context
+stack, which is an array of \f(CW\*(C`PERL_CONTEXT\*(C'\fR structures, and which is
+itself a big union for all the types of context. Whenever a new scope is
+entered (such as a block, a \f(CW\*(C`for\*(C'\fR loop, or a subroutine call), a new
+context entry is pushed onto the stack. Similarly when leaving a block or
+returning from a subroutine call etc. a context is popped. Since the
+context stack represents the current dynamic scope, it can be searched.
+For example, \f(CW\*(C`next LABEL\*(C'\fR searches back through the stack looking for a
+loop context that matches the label; \f(CW\*(C`return\*(C'\fR pops contexts until it
+finds a sub or eval context or similar; \f(CW\*(C`caller\*(C'\fR examines sub contexts on
+the stack.
+.PP
+Each context entry is labelled with a context type, \f(CW\*(C`cx_type\*(C'\fR. Typical
+context types are \f(CW\*(C`CXt_SUB\*(C'\fR, \f(CW\*(C`CXt_EVAL\*(C'\fR etc., as well as \f(CW\*(C`CXt_BLOCK\*(C'\fR
+and \f(CW\*(C`CXt_NULL\*(C'\fR which represent a basic scope (as pushed by \f(CW\*(C`pp_enter\*(C'\fR)
+and a sort block. The type determines which part of the context union are
+valid.
+.PP
+The main division in the context struct is between a substitution scope
+(\f(CW\*(C`CXt_SUBST\*(C'\fR) and block scopes, which are everything else. The former is
+just used while executing \f(CW\*(C`s///e\*(C'\fR, and won't be discussed further
+here.
+.PP
+All the block scope types share a common base, which corresponds to
+\&\f(CW\*(C`CXt_BLOCK\*(C'\fR. This stores the old values of various scope-related
+variables like \f(CW\*(C`PL_curpm\*(C'\fR, as well as information about the current
+scope, such as \f(CW\*(C`gimme\*(C'\fR. On scope exit, the old variables are restored.
+.PP
+Particular block scope types store extra per-type information. For
+example, \f(CW\*(C`CXt_SUB\*(C'\fR stores the currently executing CV, while the various
+for loop types might hold the original loop variable SV. On scope exit,
+the per-type data is processed; for example the CV has its reference count
+decremented, and the original loop variable is restored.
+.PP
+The macro \f(CW\*(C`cxstack\*(C'\fR returns the base of the current context stack, while
+\&\f(CW\*(C`cxstack_ix\*(C'\fR is the index of the current frame within that stack.
+.PP
+In fact, the context stack is actually part of a stack-of-stacks system;
+whenever something unusual is done such as calling a \f(CW\*(C`DESTROY\*(C'\fR or tie
+handler, a new stack is pushed, then popped at the end.
+.PP
+Note that the API described here changed considerably in perl 5.24; prior
+to that, big macros like \f(CW\*(C`PUSHBLOCK\*(C'\fR and \f(CW\*(C`POPSUB\*(C'\fR were used; in 5.24
+they were replaced by the inline static functions described below. In
+addition, the ordering and detail of how these macros/function work
+changed in many ways, often subtly. In particular they didn't handle
+saving the savestack and temps stack positions, and required additional
+\&\f(CW\*(C`ENTER\*(C'\fR, \f(CW\*(C`SAVETMPS\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR compared to the new functions. The
+old-style macros will not be described further.
+.SS "Pushing contexts"
+.IX Subsection "Pushing contexts"
+For pushing a new context, the two basic functions are
+\&\f(CW\*(C`cx = cx_pushblock()\*(C'\fR, which pushes a new basic context block and returns
+its address, and a family of similar functions with names like
+\&\f(CWcx_pushsub(cx)\fR which populate the additional type-dependent fields in
+the \f(CW\*(C`cx\*(C'\fR struct. Note that \f(CW\*(C`CXt_NULL\*(C'\fR and \f(CW\*(C`CXt_BLOCK\*(C'\fR don't have their
+own push functions, as they don't store any data beyond that pushed by
+\&\f(CW\*(C`cx_pushblock\*(C'\fR.
+.PP
+The fields of the context struct and the arguments to the \f(CW\*(C`cx_*\*(C'\fR
+functions are subject to change between perl releases, representing
+whatever is convenient or efficient for that release.
+.PP
+A typical context stack pushing can be found in \f(CW\*(C`pp_entersub\*(C'\fR; the
+following shows a simplified and stripped-down example of a non-XS call,
+along with comments showing roughly what each function does.
+.PP
+.Vb 6
+\& dMARK;
+\& U8 gimme      = GIMME_V;
+\& bool hasargs  = cBOOL(PL_op\->op_flags & OPf_STACKED);
+\& OP *retop     = PL_op\->op_next;
+\& I32 old_ss_ix = PL_savestack_ix;
+\& CV *cv        = ....;
+\&
+\& /* ... make mortal copies of stack args which are PADTMPs here ... */
+\&
+\& /* ... do any additional savestack pushes here ... */
+\&
+\& /* Now push a new context entry of type \*(AqCXt_SUB\*(Aq; initially just
+\&  * doing the actions common to all block types: */
+\&
+\& cx = cx_pushblock(CXt_SUB, gimme, MARK, old_ss_ix);
+\&
+\&     /* this does (approximately):
+\&         CXINC;              /* cxstack_ix++ (grow if necessary) */
+\&         cx = CX_CUR();      /* and get the address of new frame */
+\&         cx\->cx_type        = CXt_SUB;
+\&         cx\->blk_gimme      = gimme;
+\&         cx\->blk_oldsp      = MARK \- PL_stack_base;
+\&         cx\->blk_oldsaveix  = old_ss_ix;
+\&         cx\->blk_oldcop     = PL_curcop;
+\&         cx\->blk_oldmarksp  = PL_markstack_ptr \- PL_markstack;
+\&         cx\->blk_oldscopesp = PL_scopestack_ix;
+\&         cx\->blk_oldpm      = PL_curpm;
+\&         cx\->blk_old_tmpsfloor = PL_tmps_floor;
+\&
+\&         PL_tmps_floor        = PL_tmps_ix;
+\&     */
+\&
+\&
+\& /* then update the new context frame with subroutine\-specific info,
+\&  * such as the CV about to be executed: */
+\&
+\& cx_pushsub(cx, cv, retop, hasargs);
+\&
+\&     /* this does (approximately):
+\&         cx\->blk_sub.cv          = cv;
+\&         cx\->blk_sub.olddepth    = CvDEPTH(cv);
+\&         cx\->blk_sub.prevcomppad = PL_comppad;
+\&         cx\->cx_type            |= (hasargs) ? CXp_HASARGS : 0;
+\&         cx\->blk_sub.retop       = retop;
+\&         SvREFCNT_inc_simple_void_NN(cv);
+\&     */
+.Ve
+.PP
+Note that \f(CWcx_pushblock()\fR sets two new floors: for the args stack (to
+\&\f(CW\*(C`MARK\*(C'\fR) and the temps stack (to \f(CW\*(C`PL_tmps_ix\*(C'\fR). While executing at this
+scope level, every \f(CW\*(C`nextstate\*(C'\fR (amongst others) will reset the args and
+tmps stack levels to these floors. Note that since \f(CW\*(C`cx_pushblock\*(C'\fR uses
+the current value of \f(CW\*(C`PL_tmps_ix\*(C'\fR rather than it being passed as an arg,
+this dictates at what point \f(CW\*(C`cx_pushblock\*(C'\fR should be called. In
+particular, any new mortals which should be freed only on scope exit
+(rather than at the next \f(CW\*(C`nextstate\*(C'\fR) should be created first.
+.PP
+Most callers of \f(CW\*(C`cx_pushblock\*(C'\fR simply set the new args stack floor to the
+top of the previous stack frame, but for \f(CW\*(C`CXt_LOOP_LIST\*(C'\fR it stores the
+items being iterated over on the stack, and so sets \f(CW\*(C`blk_oldsp\*(C'\fR to the
+top of these items instead. Note that, contrary to its name, \f(CW\*(C`blk_oldsp\*(C'\fR
+doesn't always represent the value to restore \f(CW\*(C`PL_stack_sp\*(C'\fR to on scope
+exit.
+.PP
+Note the early capture of \f(CW\*(C`PL_savestack_ix\*(C'\fR to \f(CW\*(C`old_ss_ix\*(C'\fR, which is
+later passed as an arg to \f(CW\*(C`cx_pushblock\*(C'\fR. In the case of \f(CW\*(C`pp_entersub\*(C'\fR,
+this is because, although most values needing saving are stored in fields
+of the context struct, an extra value needs saving only when the debugger
+is running, and it doesn't make sense to bloat the struct for this rare
+case. So instead it is saved on the savestack. Since this value gets
+calculated and saved before the context is pushed, it is necessary to pass
+the old value of \f(CW\*(C`PL_savestack_ix\*(C'\fR to \f(CW\*(C`cx_pushblock\*(C'\fR, to ensure that the
+saved value gets freed during scope exit.  For most users of
+\&\f(CW\*(C`cx_pushblock\*(C'\fR, where nothing needs pushing on the save stack,
+\&\f(CW\*(C`PL_savestack_ix\*(C'\fR is just passed directly as an arg to \f(CW\*(C`cx_pushblock\*(C'\fR.
+.PP
+Note that where possible, values should be saved in the context struct
+rather than on the save stack; it's much faster that way.
+.PP
+Normally \f(CW\*(C`cx_pushblock\*(C'\fR should be immediately followed by the appropriate
+\&\f(CW\*(C`cx_pushfoo\*(C'\fR, with nothing between them; this is because if code
+in-between could die (e.g. a warning upgraded to fatal), then the context
+stack unwinding code in \f(CW\*(C`dounwind\*(C'\fR would see (in the example above) a
+\&\f(CW\*(C`CXt_SUB\*(C'\fR context frame, but without all the subroutine-specific fields
+set, and crashes would soon ensue.
+.PP
+Where the two must be separate, initially set the type to \f(CW\*(C`CXt_NULL\*(C'\fR or
+\&\f(CW\*(C`CXt_BLOCK\*(C'\fR, and later change it to \f(CW\*(C`CXt_foo\*(C'\fR when doing the
+\&\f(CW\*(C`cx_pushfoo\*(C'\fR. This is exactly what \f(CW\*(C`pp_enteriter\*(C'\fR does, once it's
+determined which type of loop it's pushing.
+.SS "Popping contexts"
+.IX Subsection "Popping contexts"
+Contexts are popped using \f(CWcx_popsub()\fR etc. and \f(CWcx_popblock()\fR. Note
+however, that unlike \f(CW\*(C`cx_pushblock\*(C'\fR, neither of these functions actually
+decrement the current context stack index; this is done separately using
+\&\f(CWCX_POP()\fR.
+.PP
+There are two main ways that contexts are popped. During normal execution
+as scopes are exited, functions like \f(CW\*(C`pp_leave\*(C'\fR, \f(CW\*(C`pp_leaveloop\*(C'\fR and
+\&\f(CW\*(C`pp_leavesub\*(C'\fR process and pop just one context using \f(CW\*(C`cx_popfoo\*(C'\fR and
+\&\f(CW\*(C`cx_popblock\*(C'\fR. On the other hand, things like \f(CW\*(C`pp_return\*(C'\fR and \f(CW\*(C`next\*(C'\fR
+may have to pop back several scopes until a sub or loop context is found,
+and exceptions (such as \f(CW\*(C`die\*(C'\fR) need to pop back contexts until an eval
+context is found. Both of these are accomplished by \f(CWdounwind()\fR, which
+is capable of processing and popping all contexts above the target one.
+.PP
+Here is a typical example of context popping, as found in \f(CW\*(C`pp_leavesub\*(C'\fR
+(simplified slightly):
+.PP
+.Vb 4
+\& U8 gimme;
+\& PERL_CONTEXT *cx;
+\& SV **oldsp;
+\& OP *retop;
+\&
+\& cx = CX_CUR();
+\&
+\& gimme = cx\->blk_gimme;
+\& oldsp = PL_stack_base + cx\->blk_oldsp; /* last arg of previous frame */
+\&
+\& if (gimme == G_VOID)
+\&     PL_stack_sp = oldsp;
+\& else
+\&     leave_adjust_stacks(oldsp, oldsp, gimme, 0);
+\&
+\& CX_LEAVE_SCOPE(cx);
+\& cx_popsub(cx);
+\& cx_popblock(cx);
+\& retop = cx\->blk_sub.retop;
+\& CX_POP(cx);
+\&
+\& return retop;
+.Ve
+.PP
+The steps above are in a very specific order, designed to be the reverse
+order of when the context was pushed. The first thing to do is to copy
+and/or protect any return arguments and free any temps in the current
+scope. Scope exits like an rvalue sub normally return a mortal copy of
+their return args (as opposed to lvalue subs). It is important to make
+this copy before the save stack is popped or variables are restored, or
+bad things like the following can happen:
+.PP
+.Vb 2
+\&    sub f { my $x =...; $x }  # $x freed before we get to copy it
+\&    sub f { /(...)/;    $1 }  # PL_curpm restored before $1 copied
+.Ve
+.PP
+Although we wish to free any temps at the same time, we have to be careful
+not to free any temps which are keeping return args alive; nor to free the
+temps we have just created while mortal copying return args. Fortunately,
+\&\f(CWleave_adjust_stacks()\fR is capable of making mortal copies of return args,
+shifting args down the stack, and only processing those entries on the
+temps stack that are safe to do so.
+.PP
+In void context no args are returned, so it's more efficient to skip
+calling \f(CWleave_adjust_stacks()\fR. Also in void context, a \f(CW\*(C`nextstate\*(C'\fR op
+is likely to be imminently called which will do a \f(CW\*(C`FREETMPS\*(C'\fR, so there's
+no need to do that either.
+.PP
+The next step is to pop savestack entries: \f(CWCX_LEAVE_SCOPE(cx)\fR is just
+defined as \f(CWLEAVE_SCOPE(cx\->blk_oldsaveix)\fR. Note that during the
+popping, it's possible for perl to call destructors, call \f(CW\*(C`STORE\*(C'\fR to undo
+localisations of tied vars, and so on. Any of these can die or call
+\&\f(CWexit()\fR. In this case, \f(CWdounwind()\fR will be called, and the current
+context stack frame will be re-processed. Thus it is vital that all steps
+in popping a context are done in such a way to support reentrancy.  The
+other alternative, of decrementing \f(CW\*(C`cxstack_ix\*(C'\fR \fIbefore\fR processing the
+frame, would lead to leaks and the like if something died halfway through,
+or overwriting of the current frame.
+.PP
+\&\f(CW\*(C`CX_LEAVE_SCOPE\*(C'\fR itself is safely re-entrant: if only half the savestack
+items have been popped before dying and getting trapped by eval, then the
+\&\f(CW\*(C`CX_LEAVE_SCOPE\*(C'\fRs in \f(CW\*(C`dounwind\*(C'\fR or \f(CW\*(C`pp_leaveeval\*(C'\fR will continue where
+the first one left off.
+.PP
+The next step is the type-specific context processing; in this case
+\&\f(CW\*(C`cx_popsub\*(C'\fR. In part, this looks like:
+.PP
+.Vb 4
+\&    cv = cx\->blk_sub.cv;
+\&    CvDEPTH(cv) = cx\->blk_sub.olddepth;
+\&    cx\->blk_sub.cv = NULL;
+\&    SvREFCNT_dec(cv);
+.Ve
+.PP
+where its processing the just-executed CV. Note that before it decrements
+the CV's reference count, it nulls the \f(CW\*(C`blk_sub.cv\*(C'\fR. This means that if
+it re-enters, the CV won't be freed twice. It also means that you can't
+rely on such type-specific fields having useful values after the return
+from \f(CW\*(C`cx_popfoo\*(C'\fR.
+.PP
+Next, \f(CW\*(C`cx_popblock\*(C'\fR restores all the various interpreter vars to their
+previous values or previous high water marks; it expands to:
+.PP
+.Vb 5
+\&    PL_markstack_ptr = PL_markstack + cx\->blk_oldmarksp;
+\&    PL_scopestack_ix = cx\->blk_oldscopesp;
+\&    PL_curpm         = cx\->blk_oldpm;
+\&    PL_curcop        = cx\->blk_oldcop;
+\&    PL_tmps_floor    = cx\->blk_old_tmpsfloor;
+.Ve
+.PP
+Note that it \fIdoesn't\fR restore \f(CW\*(C`PL_stack_sp\*(C'\fR; as mentioned earlier,
+which value to restore it to depends on the context type (specifically
+\&\f(CW\*(C`for (list) {}\*(C'\fR), and what args (if any) it returns; and that will
+already have been sorted out earlier by \f(CWleave_adjust_stacks()\fR.
+.PP
+Finally, the context stack pointer is actually decremented by \f(CWCX_POP(cx)\fR.
+After this point, it's possible that that the current context frame could
+be overwritten by other contexts being pushed. Although things like ties
+and \f(CW\*(C`DESTROY\*(C'\fR are supposed to work within a new context stack, it's best
+not to assume this. Indeed on debugging builds, \f(CWCX_POP(cx)\fR deliberately
+sets \f(CW\*(C`cx\*(C'\fR to null to detect code that is still relying on the field
+values in that context frame. Note in the \f(CWpp_leavesub()\fR example above,
+we grab \f(CW\*(C`blk_sub.retop\*(C'\fR \fIbefore\fR calling \f(CW\*(C`CX_POP\*(C'\fR.
+.SS "Redoing contexts"
+.IX Subsection "Redoing contexts"
+Finally, there is \f(CWcx_topblock(cx)\fR, which acts like a super\-\f(CW\*(C`nextstate\*(C'\fR
+as regards to resetting various vars to their base values. It is used in
+places like \f(CW\*(C`pp_next\*(C'\fR, \f(CW\*(C`pp_redo\*(C'\fR and \f(CW\*(C`pp_goto\*(C'\fR where rather than
+exiting a scope, we want to re-initialise the scope. As well as resetting
+\&\f(CW\*(C`PL_stack_sp\*(C'\fR like \f(CW\*(C`nextstate\*(C'\fR, it also resets \f(CW\*(C`PL_markstack_ptr\*(C'\fR,
+\&\f(CW\*(C`PL_scopestack_ix\*(C'\fR and \f(CW\*(C`PL_curpm\*(C'\fR. Note that it doesn't do a
+\&\f(CW\*(C`FREETMPS\*(C'\fR.
+.SH "Slab-based operator allocation"
+.IX Header "Slab-based operator allocation"
+\&\fBNote:\fR this section describes a non-public internal API that is subject
+to change without notice.
+.PP
+Perl's internal error-handling mechanisms implement \f(CW\*(C`die\*(C'\fR (and its internal
+equivalents) using longjmp. If this occurs during lexing, parsing or
+compilation, we must ensure that any ops allocated as part of the compilation
+process are freed. (Older Perl versions did not adequately handle this
+situation: when failing a parse, they would leak ops that were stored in
+C \f(CW\*(C`auto\*(C'\fR variables and not linked anywhere else.)
+.PP
+To handle this situation, Perl uses \fIop slabs\fR that are attached to the
+currently-compiling CV. A slab is a chunk of allocated memory. New ops are
+allocated as regions of the slab. If the slab fills up, a new one is created
+(and linked from the previous one). When an error occurs and the CV is freed,
+any ops remaining are freed.
+.PP
+Each op is preceded by two pointers: one points to the next op in the slab, and
+the other points to the slab that owns it. The next-op pointer is needed so
+that Perl can iterate over a slab and free all its ops. (Op structures are of
+different sizes, so the slab's ops can't merely be treated as a dense array.)
+The slab pointer is needed for accessing a reference count on the slab: when
+the last op on a slab is freed, the slab itself is freed.
+.PP
+The slab allocator puts the ops at the end of the slab first. This will tend to
+allocate the leaves of the op tree first, and the layout will therefore
+hopefully be cache-friendly. In addition, this means that there's no need to
+store the size of the slab (see below on why slabs vary in size), because Perl
+can follow pointers to find the last op.
+.PP
+It might seem possible to eliminate slab reference counts altogether, by having
+all ops implicitly attached to \f(CW\*(C`PL_compcv\*(C'\fR when allocated and freed when the
+CV is freed. That would also allow \f(CW\*(C`op_free\*(C'\fR to skip \f(CW\*(C`FreeOp\*(C'\fR altogether, and
+thus free ops faster. But that doesn't work in those cases where ops need to
+survive beyond their CVs, such as re-evals.
+.PP
+The CV also has to have a reference count on the slab. Sometimes the first op
+created is immediately freed. If the reference count of the slab reaches 0,
+then it will be freed with the CV still pointing to it.
+.PP
+CVs use the \f(CW\*(C`CVf_SLABBED\*(C'\fR flag to indicate that the CV has a reference count
+on the slab. When this flag is set, the slab is accessible via \f(CW\*(C`CvSTART\*(C'\fR when
+\&\f(CW\*(C`CvROOT\*(C'\fR is not set, or by subtracting two pointers \f(CW\*(C`(2*sizeof(I32 *))\*(C'\fR from
+\&\f(CW\*(C`CvROOT\*(C'\fR when it is set. The alternative to this approach of sneaking the slab
+into \f(CW\*(C`CvSTART\*(C'\fR during compilation would be to enlarge the \f(CW\*(C`xpvcv\*(C'\fR struct by
+another pointer. But that would make all CVs larger, even though slab-based op
+freeing is typically of benefit only for programs that make significant use of
+string eval.
+.PP
+When the \f(CW\*(C`CVf_SLABBED\*(C'\fR flag is set, the CV takes responsibility for freeing
+the slab. If \f(CW\*(C`CvROOT\*(C'\fR is not set when the CV is freed or undeffed, it is
+assumed that a compilation error has occurred, so the op slab is traversed and
+all the ops are freed.
+.PP
+Under normal circumstances, the CV forgets about its slab (decrementing the
+reference count) when the root is attached. So the slab reference counting that
+happens when ops are freed takes care of freeing the slab. In some cases, the
+CV is told to forget about the slab (\f(CW\*(C`cv_forget_slab\*(C'\fR) precisely so that the
+ops can survive after the CV is done away with.
+.PP
+Forgetting the slab when the root is attached is not strictly necessary, but
+avoids potential problems with \f(CW\*(C`CvROOT\*(C'\fR being written over. There is code all
+over the place, both in core and on CPAN, that does things with \f(CW\*(C`CvROOT\*(C'\fR, so
+forgetting the slab makes things more robust and avoids potential problems.
+.PP
+Since the CV takes ownership of its slab when flagged, that flag is never
+copied when a CV is cloned, as one CV could free a slab that another CV still
+points to, since forced freeing of ops ignores the reference count (but asserts
+that it looks right).
+.PP
+To avoid slab fragmentation, freed ops are marked as freed and attached to the
+slab's freed chain (an idea stolen from DBM::Deep). Those freed ops are reused
+when possible. Not reusing freed ops would be simpler, but it would result in
+significantly higher memory usage for programs with large \f(CW\*(C`if (DEBUG) {...}\*(C'\fR
+blocks.
+.PP
+\&\f(CW\*(C`SAVEFREEOP\*(C'\fR is slightly problematic under this scheme. Sometimes it can cause
+an op to be freed after its CV. If the CV has forcibly freed the ops on its
+slab and the slab itself, then we will be fiddling with a freed slab. Making
+\&\f(CW\*(C`SAVEFREEOP\*(C'\fR a no-op doesn't help, as sometimes an op can be savefreed when
+there is no compilation error, so the op would never be freed. It holds
+a reference count on the slab, so the whole slab would leak. So \f(CW\*(C`SAVEFREEOP\*(C'\fR
+now sets a special flag on the op (\f(CW\*(C`\->op_savefree\*(C'\fR). The forced freeing of
+ops after a compilation error won't free any ops thus marked.
+.PP
+Since many pieces of code create tiny subroutines consisting of only a few ops,
+and since a huge slab would be quite a bit of baggage for those to carry
+around, the first slab is always very small. To avoid allocating too many
+slabs for a single CV, each subsequent slab is twice the size of the previous.
+.PP
+Smartmatch expects to be able to allocate an op at run time, run it, and then
+throw it away. For that to work the op is simply malloced when \f(CW\*(C`PL_compcv\*(C'\fR hasn't
+been set up. So all slab-allocated ops are marked as such (\f(CW\*(C`\->op_slabbed\*(C'\fR),
+to distinguish them from malloced ops.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Until May 1997, this document was maintained by Jeff Okamoto
+<okamoto@corp.hp.com>.  It is now maintained as part of Perl
+itself by the Perl 5 Porters <perl5\-porters@perl.org>.
+.PP
+With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
+Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
+Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
+Stephen McCamant, and Gurusamy Sarathy.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlapi, perlintern, perlxs, perlembed
diff --git a/upstream/mageia-cauldron/man1/perlhack.1 b/upstream/mageia-cauldron/man1/perlhack.1
new file mode 100644
index 00000000..1dd7ff95
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhack.1
@@ -0,0 +1,1259 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHACK 1"
+.TH PERLHACK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhack \- How to hack on Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document explains how Perl development works.  It includes details
+about the Perl 5 Porters email list, the Perl repository, the Perl
+bug tracker, patch guidelines, and commentary on Perl development
+philosophy.
+.SH "SUPER QUICK PATCH GUIDE"
+.IX Header "SUPER QUICK PATCH GUIDE"
+If you just want to submit a single small patch like a pod fix, a test
+for a bug, comment fixes, etc., it's easy! Here's how:
+.IP \(bu 4
+Check out the source repository
+.Sp
+The perl source is in a git repository.  You can clone the repository
+with the following command:
+.Sp
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.IP \(bu 4
+Ensure you're following the latest advice
+.Sp
+In case the advice in this guide has been updated recently, read the
+latest version directly from the perl source:
+.Sp
+.Vb 1
+\&  % perldoc pod/perlhack.pod
+.Ve
+.IP \(bu 4
+Create a branch for your change
+.Sp
+Create a branch based on blead to commit your change to, which will
+later be used to send it to the Perl issue tracker.
+.Sp
+.Vb 1
+\&  % git checkout \-b mychange
+.Ve
+.IP \(bu 4
+Make your change
+.Sp
+Hack, hack, hack.  Keep in mind that Perl runs on many different
+platforms, with different operating systems that have different
+capabilities, different filesystem organizations, and even different
+character sets.  perlhacktips gives advice on this.
+.IP \(bu 4
+Test your change
+.Sp
+You can run all the tests with the following commands:
+.Sp
+.Vb 2
+\&  % ./Configure \-des \-Dusedevel
+\&  % make test
+.Ve
+.Sp
+Keep hacking until the tests pass.
+.IP \(bu 4
+Commit your change
+.Sp
+Committing your work will save the change \fIon your local system\fR:
+.Sp
+.Vb 1
+\&  % git commit \-a \-m \*(AqCommit message goes here\*(Aq
+.Ve
+.Sp
+Make sure the commit message describes your change in a single
+sentence.  For example, "Fixed spelling errors in perlhack.pod".
+.IP \(bu 4
+Send your change to the Perl issue tracker
+.Sp
+The next step is to submit your patch to the Perl core ticket system.
+.Sp
+Create a GitHub fork of the perl5 repository and add it as a remote,
+if you haven't already, as described in the GitHub documentation at
+<https://help.github.com/en/articles/working\-with\-forks>.
+.Sp
+.Vb 1
+\&  % git remote add fork git@github.com:MyUser/perl5.git
+.Ve
+.Sp
+For more information, see "Connecting to GitHub with SSH" <https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh>.
+.Sp
+If you'd rather use an HTTPS URL for your \f(CW\*(C`git push\*(C'\fR see "Cloning with
+HTTPS URLs" <https://docs.github.com/en/free-pro-team@latest/github/using-git/which-remote-url-should-i-use#cloning-with-https-urls>.
+.Sp
+.Vb 1
+\&  % git remote add fork https://github.com/MyUser/perl5.git
+.Ve
+.Sp
+Then, push your new branch to your fork.
+.Sp
+.Vb 1
+\&  % git push \-u fork mychange
+.Ve
+.Sp
+Finally, create a Pull Request on GitHub from your branch to blead as
+described in the GitHub documentation at
+<https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>.
+.IP \(bu 4
+Thank you
+.Sp
+The porters appreciate the time you spent helping to make Perl better.
+Thank you!
+.IP \(bu 4
+Acknowledgement
+.Sp
+All contributors are credited (by name and email address) in the
+AUTHORS file, which is part of the perl distribution, as well as the
+Git commit history.
+.Sp
+If you don’t want to be included in the AUTHORS file, just let us
+know. Otherwise we will take your submission of a patch as permission
+to credit you in the AUTHORS file.
+.IP \(bu 4
+Next time
+.Sp
+The next time you wish to make a patch, you need to start from the
+latest perl in a pristine state.  Check you don't have any local changes
+or added files in your perl check-out which you wish to keep, then run
+these commands:
+.Sp
+.Vb 4
+\&  % git checkout blead
+\&  % git pull
+\&  % git reset \-\-hard origin/blead
+\&  % git clean \-dxf
+.Ve
+.SH "BUG REPORTING"
+.IX Header "BUG REPORTING"
+If you want to report a bug in Perl, or browse existing Perl bugs and
+patches, use the GitHub issue tracker at
+<https://github.com/perl/perl5/issues>.
+.PP
+Please check the archive of the perl5\-porters list (see below) and/or
+the bug tracking system before submitting a bug report.  Often, you'll
+find that the bug has been reported already.
+.PP
+You can log in to the bug tracking system and comment on existing bug
+reports.  If you have additional information regarding an existing bug,
+please add it.  This will help the porters fix the bug.
+.SH "PERL 5 PORTERS"
+.IX Header "PERL 5 PORTERS"
+The perl5\-porters (p5p) mailing list is where the Perl standard
+distribution is maintained and developed.  The people who maintain Perl
+are also referred to as the "Perl 5 Porters", "p5p" or just the
+"porters".
+.PP
+A searchable archive of the list is available at
+<https://markmail.org/search/?q=perl5\-porters>.  There is also an archive at
+<https://archive.develooper.com/perl5\-porters@perl.org/>.
+.SS "perl-changes mailing list"
+.IX Subsection "perl-changes mailing list"
+The perl5\-changes mailing list receives a copy of each patch that gets
+submitted to the maintenance and development branches of the perl
+repository.  See <https://lists.perl.org/list/perl5\-changes.html> for
+subscription and archive information.
+.SS "#p5p on IRC"
+.IX Subsection "#p5p on IRC"
+Many porters are also active on the <irc://irc.perl.org/#p5p> channel.
+Feel free to join the channel and ask questions about hacking on the
+Perl core.
+.SH "GETTING THE PERL SOURCE"
+.IX Header "GETTING THE PERL SOURCE"
+All of Perl's source code is kept centrally in a Git repository at
+\&\fIgithub.com\fR.  The repository contains many Perl revisions
+from Perl 1 onwards and all the revisions from Perforce, the previous
+version control system.
+.PP
+For much more detail on using git with the Perl repository, please see
+perlgit.
+.SS "Read access via Git"
+.IX Subsection "Read access via Git"
+You will need a copy of Git for your computer.  You can fetch a copy of
+the repository using the git protocol:
+.PP
+.Vb 1
+\&  % git clone git@github.com:Perl/perl5.git perl
+.Ve
+.PP
+This clones the repository and makes a local copy in the \fIperl\fR
+directory.
+.PP
+If you cannot use the git protocol for firewall reasons, you can also
+clone via http:
+.PP
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.SS "Read access via the web"
+.IX Subsection "Read access via the web"
+You may access the repository over the web.  This allows you to browse
+the tree, see recent commits, subscribe to repository notifications,
+search for particular commits and more.  You may access it at
+<https://github.com/Perl/perl5>.
+.SS "Write access via git"
+.IX Subsection "Write access via git"
+If you have a commit bit, please see perlgit for more details on
+using git.
+.SH "PATCHING PERL"
+.IX Header "PATCHING PERL"
+If you're planning to do more extensive work than a single small fix,
+we encourage you to read the documentation below.  This will help you
+focus your work and make your patches easier to incorporate into the
+Perl source.
+.SS "Submitting patches"
+.IX Subsection "Submitting patches"
+If you have a small patch to submit, please submit it via the GitHub
+Pull Request workflow.  You may also send patches to the p5p list.
+.PP
+Patches are reviewed and discussed on GitHub or the p5p list.  Simple,
+uncontroversial patches will usually be applied without any discussion.
+When the patch is applied, the ticket will be updated and you will
+receive email.
+.PP
+In other cases, the patch will need more work or discussion.
+You are encouraged to participate in the discussion and advocate for
+your patch.  Sometimes your patch may get lost in the shuffle.  It's
+appropriate to send a reminder email to p5p if no action has been taken
+in a month.  Please remember that the Perl 5 developers are all
+volunteers, and be polite.
+.PP
+Changes are always applied directly to the main development branch,
+called "blead".  Some patches may be backported to a maintenance
+branch.  If you think your patch is appropriate for the maintenance
+branch (see "MAINTENANCE BRANCHES" in perlpolicy), please explain why
+when you submit it.
+.SS "Getting your patch accepted"
+.IX Subsection "Getting your patch accepted"
+If you are submitting a code patch there are several things that you
+can do to help the Perl 5 Porters accept your patch.
+.PP
+\fIPatch style\fR
+.IX Subsection "Patch style"
+.PP
+Using the GitHub Pull Request workflow, your patch will automatically
+be available in a suitable format.  If you wish to submit a patch to
+the p5p list for review, make sure to create it appropriately.
+.PP
+If you used git to check out the Perl source, then using \f(CW\*(C`git
+format\-patch\*(C'\fR will produce a patch in a style suitable for Perl.  The
+\&\f(CW\*(C`format\-patch\*(C'\fR command produces one patch file for each commit you
+made.  If you prefer to send a single patch for all commits, you can
+use \f(CW\*(C`git diff\*(C'\fR.
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git pull
+\&  % git diff blead my\-branch\-name
+.Ve
+.PP
+This produces a patch based on the difference between blead and your
+current branch.  It's important to make sure that blead is up to date
+before producing the diff, that's why we call \f(CW\*(C`git pull\*(C'\fR first.
+.PP
+We strongly recommend that you use git if possible.  It will make your
+life easier, and ours as well.
+.PP
+However, if you're not using git, you can still produce a suitable
+patch.  You'll need a pristine copy of the Perl source to diff against.
+The porters prefer unified diffs.  Using GNU \f(CW\*(C`diff\*(C'\fR, you can produce a
+diff like this:
+.PP
+.Vb 1
+\&  % diff \-Npurd perl.pristine perl.mine
+.Ve
+.PP
+Make sure that you \f(CW\*(C`make realclean\*(C'\fR in your copy of Perl to remove any
+build artifacts, or you may get a confusing result.
+.PP
+\fICommit message\fR
+.IX Subsection "Commit message"
+.PP
+As you craft each patch you intend to submit to the Perl core, it's
+important to write a good commit message.  This is especially important
+if your submission will consist of a series of commits.
+.PP
+The first line of the commit message should be a short description
+without a period.  It should be no longer than the subject line of an
+email, 50 characters being a good rule of thumb.
+.PP
+A lot of Git tools (Gitweb, GitHub, git log \-\-pretty=oneline, ...) will
+only display the first line (cut off at 50 characters) when presenting
+commit summaries.
+.PP
+The commit message should include a description of the problem that the
+patch corrects or new functionality that the patch adds.
+.PP
+As a general rule of thumb, your commit message should help a
+programmer who knows the Perl core quickly understand what you were
+trying to do, how you were trying to do it, and why the change matters
+to Perl.
+.IP \(bu 4
+Why
+.Sp
+Your commit message should describe why the change you are making is
+important.  When someone looks at your change in six months or six
+years, your intent should be clear.
+.Sp
+If you're deprecating a feature with the intent of later simplifying
+another bit of code, say so.  If you're fixing a performance problem or
+adding a new feature to support some other bit of the core, mention
+that.
+.IP \(bu 4
+What
+.Sp
+Your commit message should describe what part of the Perl core you're
+changing and what you expect your patch to do.
+.IP \(bu 4
+How
+.Sp
+While it's not necessary for documentation changes, new tests or
+trivial patches, it's often worth explaining how your change works.
+Even if it's clear to you today, it may not be clear to a porter next
+month or next year.
+.PP
+A commit message isn't intended to take the place of comments in your
+code.  Commit messages should describe the change you made, while code
+comments should describe the current state of the code.
+.PP
+If you've just implemented a new feature, complete with doc, tests and
+well-commented code, a brief commit message will often suffice.  If,
+however, you've just changed a single character deep in the parser or
+lexer, you might need to write a small novel to ensure that future
+readers understand what you did and why you did it.
+.PP
+\fIComments, Comments, Comments\fR
+.IX Subsection "Comments, Comments, Comments"
+.PP
+Be sure to adequately comment your code.  While commenting every line
+is unnecessary, anything that takes advantage of side effects of
+operators, that creates changes that will be felt outside of the
+function being patched, or that others may find confusing should be
+documented.  If you are going to err, it is better to err on the side
+of adding too many comments than too few.
+.PP
+The best comments explain \fIwhy\fR the code does what it does, not \fIwhat
+it does\fR.
+.PP
+\fIStyle\fR
+.IX Subsection "Style"
+.PP
+In general, please follow the particular style of the code you are
+patching.
+.PP
+In particular, follow these general guidelines for patching Perl
+sources:
+.IP \(bu 4
+4\-wide indents for code, 2\-wide indents for nested CPP \f(CW\*(C`#define\*(C'\fRs,
+with 8\-wide tabstops.
+.IP \(bu 4
+Use spaces for indentation, not tab characters.
+.Sp
+The codebase is a mixture of tabs and spaces for indentation, and we
+are moving to spaces only.  Converting lines you're patching from 8\-wide
+tabs to spaces will help this migration.
+.IP \(bu 4
+Try not to exceed 79 columns
+.Sp
+In general, we target 80 column lines.  When sticking to 80 columns would lead
+to torturous code or rework, it's fine to go longer.  Try to keep your excess
+past 80 to a minimum.
+.IP \(bu 4
+ANSI C prototypes
+.IP \(bu 4
+Uncuddled elses and "K&R" style for indenting control constructs
+.IP \(bu 4
+No C++ style (//) comments
+.IP \(bu 4
+Mark places that need to be revisited with XXX (and revisit often!)
+.IP \(bu 4
+Opening brace lines up with "if" when conditional spans multiple lines;
+should be at end-of-line otherwise
+.IP \(bu 4
+In function definitions, name starts in column 0 (return value-type is on
+previous line)
+.IP \(bu 4
+Single space after keywords that are followed by parens, no space
+between function name and following paren
+.IP \(bu 4
+Avoid assignments in conditionals, but if they're unavoidable, use
+extra paren, e.g. "if (a && (b = c)) ..."
+.IP \(bu 4
+"return foo;" rather than "return(foo);"
+.IP \(bu 4
+"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
+.IP \(bu 4
+Do not declare variables using "register".  It may be counterproductive
+with modern compilers, and is deprecated in C++, under which the Perl
+source is regularly compiled.
+.IP \(bu 4
+In-line functions that are in headers that are accessible to XS code
+need to be able to compile without warnings with commonly used extra
+compilation flags, such as gcc's \f(CW\*(C`\-Wswitch\-default\*(C'\fR which warns
+whenever a switch statement does not have a "default" case.  The use of
+these extra flags is to catch potential problems in legal C code, and
+is often used by Perl aggregators, such as Linux distributors.
+.PP
+\fITest suite\fR
+.IX Subsection "Test suite"
+.PP
+If your patch changes code (rather than just changing documentation),
+you should also include one or more test cases which illustrate the bug
+you're fixing or validate the new functionality you're adding.  In
+general, you should update an existing test file rather than create a
+new one.
+.PP
+Your test suite additions should generally follow these guidelines
+(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
+.IP \(bu 4
+Know what you're testing.  Read the docs, and the source.
+.IP \(bu 4
+Tend to fail, not succeed.
+.IP \(bu 4
+Interpret results strictly.
+.IP \(bu 4
+Use unrelated features (this will flush out bizarre interactions).
+.IP \(bu 4
+Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
+.IP \(bu 4
+Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
+found in t/op/tie.t is much more maintainable, and gives better failure
+reports).
+.IP \(bu 4
+Give meaningful error messages when a test fails.
+.IP \(bu 4
+Avoid using qx// and \fBsystem()\fR unless you are testing for them.  If you
+do use them, make sure that you cover _all_ perl platforms.
+.IP \(bu 4
+Unlink any temporary files you create.
+.IP \(bu 4
+Promote unforeseen warnings to errors with \f(CW$SIG\fR{_\|_WARN_\|_}.
+.IP \(bu 4
+Be sure to use the libraries and modules shipped with the version being
+tested, not those that were already installed.
+.IP \(bu 4
+Add comments to the code explaining what you are testing for.
+.IP \(bu 4
+Make updating the '1..42' string unnecessary.  Or make sure that you
+update it.
+.IP \(bu 4
+Test _all_ behaviors of a given operator, library, or function.
+.Sp
+Test all optional arguments.
+.Sp
+Test return values in various contexts (boolean, scalar, list, lvalue).
+.Sp
+Use both global and lexical variables.
+.Sp
+Don't forget the exceptional, pathological cases.
+.SS "Patching a core module"
+.IX Subsection "Patching a core module"
+This works just like patching anything else, with one extra
+consideration.
+.PP
+Modules in the \fIcpan/\fR directory of the source tree are maintained
+outside of the Perl core.  When the author updates the module, the
+updates are simply copied into the core.  See that module's
+documentation or its listing on <https://metacpan.org/> for more
+information on reporting bugs and submitting patches.
+.PP
+In most cases, patches to modules in \fIcpan/\fR should be sent upstream
+and should not be applied to the Perl core individually.  If a patch to
+a file in \fIcpan/\fR absolutely cannot wait for the fix to be made
+upstream, released to CPAN and copied to blead, you must add (or
+update) a \f(CW\*(C`CUSTOMIZED\*(C'\fR entry in the \fIPorting/Maintainers.pl\fR file
+to flag that a local modification has been made.  See
+\&\fIPorting/Maintainers.pl\fR for more details.
+.PP
+In contrast, modules in the \fIdist/\fR directory are maintained in the
+core.
+.SS "Updating perldelta"
+.IX Subsection "Updating perldelta"
+For changes significant enough to warrant a \fIpod/perldelta.pod\fR entry,
+the porters will greatly appreciate it if you submit a delta entry
+along with your actual change.  Significant changes include, but are
+not limited to:
+.IP \(bu 4
+Adding, deprecating, or removing core features
+.IP \(bu 4
+Adding, deprecating, removing, or upgrading core or dual-life modules
+.IP \(bu 4
+Adding new core tests
+.IP \(bu 4
+Fixing security issues and user-visible bugs in the core
+.IP \(bu 4
+Changes that might break existing code, either on the perl or C level
+.IP \(bu 4
+Significant performance improvements
+.IP \(bu 4
+Adding, removing, or significantly changing documentation in the
+\&\fIpod/\fR directory
+.IP \(bu 4
+Important platform-specific changes
+.PP
+Please make sure you add the perldelta entry to the right section
+within \fIpod/perldelta.pod\fR.  More information on how to write good
+perldelta entries is available in the \f(CW\*(C`Style\*(C'\fR section of
+\&\fIPorting/how_to_write_a_perldelta.pod\fR.
+.SS "What makes for a good patch?"
+.IX Subsection "What makes for a good patch?"
+New features and extensions to the language can be contentious.  There
+is no specific set of criteria which determine what features get added,
+but here are some questions to consider when developing a patch:
+.PP
+\fIDoes the concept match the general goals of Perl?\fR
+.IX Subsection "Does the concept match the general goals of Perl?"
+.PP
+Our goals include, but are not limited to:
+.IP 1. 4
+Keep it fast, simple, and useful.
+.IP 2. 4
+Keep features/concepts as orthogonal as possible.
+.IP 3. 4
+No arbitrary limits (platforms, data sizes, cultures).
+.IP 4. 4
+Keep it open and exciting to use/patch/advocate Perl everywhere.
+.IP 5. 4
+Either assimilate new technologies, or build bridges to them.
+.PP
+\fIWhere is the implementation?\fR
+.IX Subsection "Where is the implementation?"
+.PP
+All the talk in the world is useless without an implementation.  In
+almost every case, the person or people who argue for a new feature
+will be expected to be the ones who implement it.  Porters capable of
+coding new features have their own agendas, and are not available to
+implement your (possibly good) idea.
+.PP
+\fIBackwards compatibility\fR
+.IX Subsection "Backwards compatibility"
+.PP
+It's a cardinal sin to break existing Perl programs.  New warnings can
+be contentious\-\-some say that a program that emits warnings is not
+broken, while others say it is.  Adding keywords has the potential to
+break programs, changing the meaning of existing token sequences or
+functions might break programs.
+.PP
+The Perl 5 core includes mechanisms to help porters make backwards
+incompatible changes more compatible such as the feature and
+deprecate modules.  Please use them when appropriate.
+.PP
+\fICould it be a module instead?\fR
+.IX Subsection "Could it be a module instead?"
+.PP
+Perl 5 has extension mechanisms, modules and XS, specifically to avoid
+the need to keep changing the Perl interpreter.  You can write modules
+that export functions, you can give those functions prototypes so they
+can be called like built-in functions, you can even write XS code to
+mess with the runtime data structures of the Perl interpreter if you
+want to implement really complicated things.
+.PP
+Whenever possible, new features should be prototyped in a CPAN module
+before they will be considered for the core.
+.PP
+\fIIs the feature generic enough?\fR
+.IX Subsection "Is the feature generic enough?"
+.PP
+Is this something that only the submitter wants added to the language,
+or is it broadly useful?  Sometimes, instead of adding a feature with a
+tight focus, the porters might decide to wait until someone implements
+the more generalized feature.
+.PP
+\fIDoes it potentially introduce new bugs?\fR
+.IX Subsection "Does it potentially introduce new bugs?"
+.PP
+Radical rewrites of large chunks of the Perl interpreter have the
+potential to introduce new bugs.
+.PP
+\fIHow big is it?\fR
+.IX Subsection "How big is it?"
+.PP
+The smaller and more localized the change, the better.  Similarly, a
+series of small patches is greatly preferred over a single large patch.
+.PP
+\fIDoes it preclude other desirable features?\fR
+.IX Subsection "Does it preclude other desirable features?"
+.PP
+A patch is likely to be rejected if it closes off future avenues of
+development.  For instance, a patch that placed a true and final
+interpretation on prototypes is likely to be rejected because there are
+still options for the future of prototypes that haven't been addressed.
+.PP
+\fIIs the implementation robust?\fR
+.IX Subsection "Is the implementation robust?"
+.PP
+Good patches (tight code, complete, correct) stand more chance of going
+in.  Sloppy or incorrect patches might be placed on the back burner
+until fixes can be made, or they might be discarded altogether
+without further notice.
+.PP
+\fIIs the implementation generic enough to be portable?\fR
+.IX Subsection "Is the implementation generic enough to be portable?"
+.PP
+The worst patches make use of system-specific features.  It's highly
+unlikely that non-portable additions to the Perl language will be
+accepted.
+.PP
+\fIIs the implementation tested?\fR
+.IX Subsection "Is the implementation tested?"
+.PP
+Patches which change behaviour (fixing bugs or introducing new
+features) must include regression tests to verify that everything works
+as expected.
+.PP
+Without tests provided by the original author, how can anyone else
+changing perl in the future be sure that they haven't unwittingly
+broken the behaviour the patch implements? And without tests, how can
+the patch's author be confident that his/her hard work put into the
+patch won't be accidentally thrown away by someone in the future?
+.PP
+\fIIs there enough documentation?\fR
+.IX Subsection "Is there enough documentation?"
+.PP
+Patches without documentation are probably ill-thought out or
+incomplete.  No features can be added or changed without documentation,
+so submitting a patch for the appropriate pod docs as well as the
+source code is important.
+.PP
+\fIIs there another way to do it?\fR
+.IX Subsection "Is there another way to do it?"
+.PP
+Larry said "Although the Perl Slogan is \fIThere's More Than One Way to
+Do It\fR, I hesitate to make 10 ways to do something".  This is a tricky
+heuristic to navigate, though\-\-one man's essential addition is another
+man's pointless cruft.
+.PP
+\fIDoes it create too much work?\fR
+.IX Subsection "Does it create too much work?"
+.PP
+Work for the committers, work for Perl programmers, work for module
+authors, ... Perl is supposed to be easy.
+.PP
+\fIPatches speak louder than words\fR
+.IX Subsection "Patches speak louder than words"
+.PP
+Working code is always preferred to pie-in-the-sky ideas.  A patch to
+add a feature stands a much higher chance of making it to the language
+than does a random feature request, no matter how fervently argued the
+request might be.  This ties into "Will it be useful?", as the fact
+that someone took the time to make the patch demonstrates a strong
+desire for the feature.
+.SH TESTING
+.IX Header "TESTING"
+The core uses the same testing style as the rest of Perl, a simple
+"ok/not ok" run through Test::Harness, but there are a few special
+considerations.
+.PP
+There are three ways to write a test in the core: Test::More,
+\&\fIt/test.pl\fR and ad hoc \f(CW\*(C`print $test ? "ok 42\en" : "not ok 42\en"\*(C'\fR.
+The decision of which to use depends on what part of the test suite
+you're working on.  This is a measure to prevent a high-level failure
+(such as Config.pm breaking) from causing basic functionality tests to
+fail.
+.PP
+The \fIt/test.pl\fR library provides some of the features of
+Test::More, but avoids loading most modules and uses as few core
+features as possible.
+.PP
+If you write your own test, use the Test Anything
+Protocol <https://testanything.org>.
+.IP \(bu 4
+\&\fIt/base\fR, \fIt/comp\fR and \fIt/opbasic\fR
+.Sp
+Since we don't know if \f(CW\*(C`require\*(C'\fR works, or even subroutines, use ad hoc
+tests for these three.  Step carefully to avoid using the feature being
+tested.  Tests in \fIt/opbasic\fR, for instance, have been placed there
+rather than in \fIt/op\fR because they test functionality which
+\&\fIt/test.pl\fR presumes has already been demonstrated to work.
+.IP \(bu 4
+All other subdirectories of \fIt/\fR
+.Sp
+Now that basic \fBrequire()\fR and subroutines are tested, you can use the
+\&\fIt/test.pl\fR library.
+.Sp
+You can also use certain libraries like Config conditionally, but be
+sure to skip the test gracefully if it's not there.
+.IP \(bu 4
+Test files not found under \fIt/\fR
+.Sp
+This category includes \fI.t\fR files underneath directories such as \fIdist\fR,
+\&\fIext\fR and \fIlib\fR.  Since the core of Perl has now been tested, Test::More
+can and now should be used.  You can also use the full suite of core modules
+in the tests.  (As noted in "Patching a core module" above, changes to
+\&\fI.t\fR files found under \fIcpan/\fR should be submitted to the upstream
+maintainers of those modules.)
+.PP
+When you say "make test", Perl uses the \fIt/TEST\fR program to run the
+test suite (except under Win32 where it uses \fIt/harness\fR instead).
+All tests are run from the \fIt/\fR directory, \fBnot\fR the directory which
+contains the test.  This causes some problems with the tests in
+\&\fIlib/\fR, so here's some opportunity for some patching.
+.PP
+You must be triply conscious of cross-platform concerns.  This usually
+boils down to using File::Spec, avoiding things like \f(CWfork()\fR
+and \f(CWsystem()\fR unless absolutely necessary, and not assuming that a
+given character has a particular ordinal value (code point) or that its
+UTF\-8 representation is composed of particular bytes.
+.PP
+There are several functions available to specify characters and code
+points portably in tests.  The always-preloaded functions
+\&\f(CWutf8::unicode_to_native()\fR and its inverse
+\&\f(CWutf8::native_to_unicode()\fR take code points and translate
+appropriately.  The file \fIt/charset_tools.pl\fR has several functions
+that can be useful.  It has versions of the previous two functions
+that take strings as inputs \-\- not single numeric code points:
+\&\f(CWuni_to_native()\fR and \f(CWnative_to_uni()\fR.  If you must look at the
+individual bytes comprising a UTF\-8 encoded string,
+\&\f(CWbyte_utf8a_to_utf8n()\fR takes as input a string of those bytes encoded
+for an ASCII platform, and returns the equivalent string in the native
+platform.  For example, \f(CWbyte_utf8a_to_utf8n("\exC2\exA0")\fR returns the
+byte sequence on the current platform that form the UTF\-8 for \f(CW\*(C`U+00A0\*(C'\fR,
+since \f(CW"\exC2\exA0"\fR are the UTF\-8 bytes on an ASCII platform for that
+code point.  This function returns \f(CW"\exC2\exA0"\fR on an ASCII platform, and
+\&\f(CW"\ex80\ex41"\fR on an EBCDIC 1047 one.
+.PP
+But easiest is, if the character is specifiable as a literal, like
+\&\f(CW"A"\fR or \f(CW"%"\fR, to use that; if not so specificable, you can use
+\&\f(CW\*(C`\eN{}\*(C'\fR , if the side effects aren't troublesome.  Simply specify all
+your characters in hex, using \f(CW\*(C`\eN{U+ZZ}\*(C'\fR instead of \f(CW\*(C`\exZZ\*(C'\fR.  \f(CW\*(C`\eN{}\*(C'\fR
+is the Unicode name, and so it
+always gives you the Unicode character.  \f(CW\*(C`\eN{U+41}\*(C'\fR is the character
+whose Unicode code point is \f(CW0x41\fR, hence is \f(CW\*(AqA\*(Aq\fR on all platforms.
+The side effects are:
+.IP \(bu 4
+These select Unicode rules.  That means that in double-quotish strings,
+the string is always converted to UTF\-8 to force a Unicode
+interpretation (you can \f(CWutf8::downgrade()\fR afterwards to convert back
+to non\-UTF8, if possible).  In regular expression patterns, the
+conversion isn't done, but if the character set modifier would
+otherwise be \f(CW\*(C`/d\*(C'\fR, it is changed to \f(CW\*(C`/u\*(C'\fR.
+.IP \(bu 4
+If you use the form \f(CW\*(C`\eN{\fR\f(CIcharacter name\fR\f(CW}\*(C'\fR, the charnames module
+gets automatically loaded.  This may not be suitable for the test level
+you are doing.
+.PP
+If you are testing locales (see perllocale), there are helper
+functions in \fIt/loc_tools.pl\fR to enable you to see what locales there
+are on the current platform.
+.ie n .SS "Special ""make test"" targets"
+.el .SS "Special \f(CWmake test\fP targets"
+.IX Subsection "Special make test targets"
+There are various special make targets that can be used to test Perl
+slightly differently than the standard "test" target.  Not all them are
+expected to give a 100% success rate.  Many of them have several
+aliases, and many of them are not available on certain operating
+systems.
+.IP \(bu 4
+test_porting
+.Sp
+This runs some basic sanity tests on the source tree and helps catch
+basic errors before you submit a patch.
+.IP \(bu 4
+minitest
+.Sp
+Run \fIminiperl\fR on \fIt/base\fR, \fIt/comp\fR, \fIt/cmd\fR, \fIt/run\fR, \fIt/io\fR,
+\&\fIt/op\fR, \fIt/uni\fR and \fIt/mro\fR tests.
+.Sp
+\&\fIminiperl\fR is a minimalistic perl built to bootstrap building
+extensions, utilties, documentation etc.  It doesn't support dynamic
+loading and depending on the point in the build process will only have
+access to a limited set of core modules.  \fIminiperl\fR is not intended
+for day to day use.
+.IP \(bu 4
+test.valgrind check.valgrind
+.Sp
+(Only in Linux) Run all the tests using the memory leak + naughty
+memory access tool "valgrind".  The log files will be named
+\&\fItestname.valgrind\fR.
+.IP \(bu 4
+test_harness
+.Sp
+Run the test suite with the \fIt/harness\fR controlling program, instead
+of \fIt/TEST\fR.  \fIt/harness\fR is more sophisticated, and uses the
+Test::Harness module, thus using this test target supposes that perl
+mostly works.  The main advantage for our purposes is that it prints a
+detailed summary of failed tests at the end.  Also, unlike \fIt/TEST\fR,
+it doesn't redirect stderr to stdout.
+.Sp
+Note that under Win32 \fIt/harness\fR is always used instead of \fIt/TEST\fR,
+so there is no special "test_harness" target.
+.Sp
+Under the Unix build process you may use the TEST_ARGS and TEST_FILES
+parameters to pass arguments through to the underlying harness call.
+This means that for instance you could do
+.Sp
+.Vb 1
+\&    make test_harness TEST_ARGS="\-v \-re pat"
+.Ve
+.Sp
+which would make, and then run the test harness in verbose mode over
+files which contain "pat". Or you could do
+.Sp
+.Vb 1
+\&    make test_harness TEST_ARGS="\-torture" TEST_FILES="op/*.t"
+.Ve
+.Sp
+and run torture tests on files matching the glob "op/*.t".
+.Sp
+Under Win32's "test" target you may use the TEST_SWITCHES and
+TEST_FILES environment variables to control the behaviour of
+\&\fIt/harness\fR.  This means you can say
+.Sp
+.Vb 2
+\&    nmake test TEST_FILES="op/*.t"
+\&    nmake test TEST_SWITCHES="\-torture" TEST_FILES="op/*.t"
+.Ve
+.Sp
+Note that for compatibility with the unix build process TEST_ARGS
+may also be used instead of the traditional TEST_SWITCHES argument.
+.IP \(bu 4
+test-notty test_notty
+.Sp
+Sets PERL_SKIP_TTY_TEST to true before running normal test.
+.SS "Parallel tests"
+.IX Subsection "Parallel tests"
+The core distribution can now run its regression tests in parallel on
+Unix-like and Windows platforms.  On Unix, instead of running \f(CW\*(C`make
+test\*(C'\fR, set \f(CW\*(C`TEST_JOBS\*(C'\fR in your environment to the number of tests to
+run in parallel, and run \f(CW\*(C`make test_harness\*(C'\fR.  On a Bourne-like shell,
+this can be done as
+.PP
+.Vb 1
+\&    TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
+.Ve
+.PP
+An environment variable is used, rather than parallel make itself,
+because TAP::Harness needs to be able to schedule individual
+non-conflicting test scripts itself, and there is no standard interface
+to \f(CW\*(C`make\*(C'\fR utilities to interact with their job schedulers.
+.PP
+Tests are normally run in a logical order, with the sanity tests first,
+then the main tests of the Perl core functionality, then the tests for
+the non-core modules.  On many-core systems, this may not use the
+hardware as effectively as possible.  By also specifying
+.PP
+.Vb 1
+\& TEST_JOBS=19 PERL_TEST_HARNESS_ASAP=1 make \-j19 test_harness
+.Ve
+.PP
+you signal that you want the tests to finish in wall-clock time as short
+as possible.  After the sanity tests are completed, this causes the
+remaining ones to be packed into the available cores as tightly as
+we know how.  This has its greatest effect on slower, many-core systems.
+Throughput was sped up by 20% on an outmoded 24\-core system; less on
+more recent faster ones with fewer cores.
+.PP
+Note that the command line above added a \f(CW\*(C`\-j\*(C'\fR parameter to make, so as
+to cause parallel compilation.  This may or may not work on your
+platform.
+.PP
+Normally data on how long tests take is stored in \fIt/test_state\fR,
+however you can change this to use a different filename by setting the
+\&\f(CW\*(C`PERL_TEST_STATE_FILE\*(C'\fR environment variable to something different, or
+to a false value (0 or the empty string) to disable use of the state
+mechanism entirely.  There are no protections against the format of the
+state file changing over time, so if you have any issues related to this
+file it is up to you to delete the file manually and then let the
+harness recreate it, although the file format does not change frequently
+so this should not be necessary very often.
+.SS "Running tests by hand"
+.IX Subsection "Running tests by hand"
+You can run part of the test suite by hand by using one of the
+following commands from the \fIt/\fR directory:
+.PP
+.Vb 1
+\&    ./perl \-I../lib TEST list\-of\-.t\-files
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    ./perl \-I../lib harness list\-of\-.t\-files
+.Ve
+.PP
+(If you don't specify test scripts, the whole test suite will be run.)
+.SS "Using \fIt/harness\fP for testing"
+.IX Subsection "Using t/harness for testing"
+If you use \f(CW\*(C`harness\*(C'\fR for testing, you have several command line
+options available to you.  The arguments are as follows, and are in the
+order that they must appear if used together.
+.PP
+.Vb 2
+\&    harness \-v \-torture \-re=pattern LIST OF FILES TO TEST
+\&    harness \-v \-torture \-re LIST OF PATTERNS TO MATCH
+.Ve
+.PP
+If \f(CW\*(C`LIST OF FILES TO TEST\*(C'\fR is omitted, the file list is obtained from
+the manifest.  The file list may include shell wildcards which will be
+expanded out.
+.IP \(bu 4
+\&\-v
+.Sp
+Run the tests under verbose mode so you can see what tests were run,
+and debug output.
+.IP \(bu 4
+\&\-torture
+.Sp
+Run the torture tests as well as the normal set.
+.IP \(bu 4
+\&\-re=PATTERN
+.Sp
+Filter the file list so that all the test files run match PATTERN.
+Note that this form is distinct from the \fB\-re LIST OF PATTERNS\fR form
+below in that it allows the file list to be provided as well.
+.IP \(bu 4
+\&\-re LIST OF PATTERNS
+.Sp
+Filter the file list so that all the test files run match
+/(LIST|OF|PATTERNS)/.  Note that with this form the patterns are joined
+by '|' and you cannot supply a list of files, instead the test files
+are obtained from the MANIFEST.
+.PP
+You can run an individual test by a command similar to
+.PP
+.Vb 1
+\&    ./perl \-I../lib path/to/foo.t
+.Ve
+.PP
+except that the harnesses set up some environment variables that may
+affect the execution of the test:
+.IP \(bu 4
+PERL_CORE=1
+.Sp
+indicates that we're running this test as part of the perl core test
+suite.  This is useful for modules that have a dual life on CPAN.
+.IP \(bu 4
+PERL_DESTRUCT_LEVEL=2
+.Sp
+is set to 2 if it isn't set already (see
+"PERL_DESTRUCT_LEVEL" in perlhacktips).
+.IP \(bu 4
+PERL
+.Sp
+(used only by \fIt/TEST\fR) if set, overrides the path to the perl
+executable that should be used to run the tests (the default being
+\&\fI./perl\fR).
+.IP \(bu 4
+PERL_SKIP_TTY_TEST
+.Sp
+if set, tells to skip the tests that need a terminal.  It's actually
+set automatically by the Makefile, but can also be forced artificially
+by running 'make test_notty'.
+.PP
+\fIOther environment variables that may influence tests\fR
+.IX Subsection "Other environment variables that may influence tests"
+.IP \(bu 4
+PERL_TEST_Net_Ping
+.Sp
+Setting this variable runs all the Net::Ping modules tests, otherwise
+some tests that interact with the outside world are skipped.  See
+perl58delta.
+.IP \(bu 4
+PERL_TEST_NOVREXX
+.Sp
+Setting this variable skips the vrexx.t tests for OS2::REXX.
+.IP \(bu 4
+PERL_TEST_NUMCONVERTS
+.Sp
+This sets a variable in op/numconvert.t.
+.IP \(bu 4
+PERL_TEST_MEMORY
+.Sp
+Setting this variable includes the tests in \fIt/bigmem/\fR.  This should
+be set to the number of gigabytes of memory available for testing, eg.
+\&\f(CW\*(C`PERL_TEST_MEMORY=4\*(C'\fR indicates that tests that require 4GiB of
+available memory can be run safely.
+.PP
+See also the documentation for the Test and Test::Harness modules, for
+more environment variables that affect testing.
+.SS "Performance testing"
+.IX Subsection "Performance testing"
+The file \fIt/perf/benchmarks\fR contains snippets of perl code which are
+intended to be benchmarked across a range of perls by the
+\&\fIPorting/bench.pl\fR tool. If you fix or enhance a performance issue, you
+may want to add a representative code sample to the file, then run
+\&\fIbench.pl\fR against the previous and current perls to see what difference
+it has made, and whether anything else has slowed down as a consequence.
+.PP
+The file \fIt/perf/opcount.t\fR is designed to test whether a particular
+code snippet has been compiled into an optree containing specified
+numbers of particular op types. This is good for testing whether
+optimisations which alter ops, such as converting an \f(CW\*(C`aelem\*(C'\fR op into an
+\&\f(CW\*(C`aelemfast\*(C'\fR op, are really doing that.
+.PP
+The files \fIt/perf/speed.t\fR and \fIt/re/speed.t\fR are designed to test
+things that run thousands of times slower if a particular optimisation
+is broken (for example, the utf8 length cache on long utf8 strings).
+Add a test that will take a fraction of a second normally, and minutes
+otherwise, causing the test file to time out on failure.
+.SS "Building perl at older commits"
+.IX Subsection "Building perl at older commits"
+In the course of hacking on the Perl core distribution, you may have occasion
+to configure, build and test perl at an old commit.  Sometimes \f(CW\*(C`make\*(C'\fR will
+fail during this process.  If that happens, you may be able to salvage the
+situation by using the Devel::PatchPerl library from CPAN (not included in the
+core) to bring the source code at that commit to a buildable state.
+.PP
+Here's a real world example, taken from work done to resolve
+perl #10118 <https://github.com/Perl/perl5/issues/10118>.
+Use of \fIPorting/bisect.pl\fR had identified commit
+\&\f(CW\*(C`ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6\*(C'\fR as the commit in which a bug was
+corrected.  To confirm, a P5P developer wanted to configure and build perl at
+commit \f(CW\*(C`ba77e4c^\*(C'\fR (presumably "bad") and then at \f(CW\*(C`ba77e4c\*(C'\fR (presumably
+"good").  Normal configuration and build was attempted:
+.PP
+.Vb 2
+\&    $ sh ./Configure \-des \-Dusedevel
+\&    $ make test_prep
+.Ve
+.PP
+\&\f(CW\*(C`make\*(C'\fR, however, failed with output (excerpted) like this:
+.PP
+.Vb 10
+\&    cc \-fstack\-protector \-L/usr/local/lib \-o miniperl \e
+\&      gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \e
+\&      mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \e
+\&      pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \e
+\&      utf8.o taint.o deb.o universal.o globals.o perlio.o \e
+\&      numeric.o mathoms.o locale.o pp_pack.o pp_sort.o  \e
+\&      miniperlmain.o opmini.o perlmini.o
+\&    pp.o: In function \`Perl_pp_pow\*(Aq:
+\&    pp.c:(.text+0x2db9): undefined reference to \`pow\*(Aq
+\&    ...
+\&    collect2: error: ld returned 1 exit status
+\&    makefile:348: recipe for target \*(Aqminiperl\*(Aq failed
+\&    make: *** [miniperl] Error 1
+.Ve
+.PP
+Another P5P contributor recommended installation and use of Devel::PatchPerl
+for this situation, first to determine the version of perl at the commit in
+question, then to patch the source code at that point to facilitate a build.
+.PP
+.Vb 6
+\& $ perl \-MDevel::PatchPerl \-e \e
+\&     \*(Aqprint Devel::PatchPerl\->determine_version("/path/to/sourcecode"),
+\&            "\en";\*(Aq
+\& 5.11.1
+\& $ perl \-MDevel::PatchPerl \-e \e
+\&     \*(AqDevel::PatchPerl\->patch_source("5.11.1", "/path/to/sourcecode");\*(Aq
+.Ve
+.PP
+Once the source was patched, \f(CW\*(C`./Configure\*(C'\fR and \f(CW\*(C`make test_prep\*(C'\fR were called
+and completed successfully, enabling confirmation of the findings in RT
+#72414.
+.SH "MORE READING FOR GUTS HACKERS"
+.IX Header "MORE READING FOR GUTS HACKERS"
+To hack on the Perl guts, you'll need to read the following things:
+.IP \(bu 4
+perlsource
+.Sp
+An overview of the Perl source tree.  This will help you find the files
+you're looking for.
+.IP \(bu 4
+perlinterp
+.Sp
+An overview of the Perl interpreter source code and some details on how
+Perl does what it does.
+.IP \(bu 4
+perlhacktut
+.Sp
+This document walks through the creation of a small patch to Perl's C
+code.  If you're just getting started with Perl core hacking, this will
+help you understand how it works.
+.IP \(bu 4
+perlhacktips
+.Sp
+More details on hacking the Perl core.  This document focuses on lower
+level details such as how to write tests, compilation issues,
+portability, debugging, etc.
+.Sp
+If you plan on doing serious C hacking, make sure to read this.
+.IP \(bu 4
+perlguts
+.Sp
+This is of paramount importance, since it's the documentation of what
+goes where in the Perl source.  Read it over a couple of times and it
+might start to make sense \- don't worry if it doesn't yet, because the
+best way to study it is to read it in conjunction with poking at Perl
+source, and we'll do that later on.
+.Sp
+Gisle Aas's "illustrated perlguts", also known as \fIillguts\fR, has very
+helpful pictures:
+.Sp
+<https://metacpan.org/release/RURBAN/illguts\-0.49>
+.IP \(bu 4
+perlxstut and perlxs
+.Sp
+A working knowledge of XSUB programming is incredibly useful for core
+hacking; XSUBs use techniques drawn from the PP code, the portion of
+the guts that actually executes a Perl program.  It's a lot gentler to
+learn those techniques from simple examples and explanation than from
+the core itself.
+.IP \(bu 4
+perlapi
+.Sp
+The documentation for the Perl API explains what some of the internal
+functions do, as well as the many macros used in the source.
+.IP \(bu 4
+\&\fIPorting/pumpkin.pod\fR
+.Sp
+This is a collection of words of wisdom for a Perl porter; some of it
+is only useful to the pumpkin holders, but most of it applies to anyone
+wanting to go about Perl development.
+.SH "CPAN TESTERS AND PERL SMOKERS"
+.IX Header "CPAN TESTERS AND PERL SMOKERS"
+The CPAN testers ( <http://cpantesters.org/> ) are a group of volunteers
+who test CPAN modules on a variety of platforms.
+.PP
+Perl Smokers ( <https://www.nntp.perl.org/group/perl.daily\-build/> and
+<https://www.nntp.perl.org/group/perl.daily\-build.reports/> )
+automatically test Perl source releases on platforms with various
+configurations.
+.PP
+Both efforts welcome volunteers.  In order to get involved in smoke
+testing of the perl itself visit
+<https://metacpan.org/release/Test\-Smoke>.  In order to start smoke
+testing CPAN modules visit
+<https://metacpan.org/release/CPANPLUS\-YACSmoke> or
+<https://metacpan.org/release/minismokebox> or
+<https://metacpan.org/release/CPAN\-Reporter>.
+.SH "WHAT NEXT?"
+.IX Header "WHAT NEXT?"
+If you've read all the documentation in the document and the ones
+listed above, you're more than ready to hack on Perl.
+.PP
+Here's some more recommendations
+.IP \(bu 4
+Subscribe to perl5\-porters, follow the patches and try and understand
+them; don't be afraid to ask if there's a portion you're not clear on \-
+who knows, you may unearth a bug in the patch...
+.IP \(bu 4
+Do read the README associated with your operating system, e.g.
+README.aix on the IBM AIX OS.  Don't hesitate to supply patches to that
+README if you find anything missing or changed over a new OS release.
+.IP \(bu 4
+Find an area of Perl that seems interesting to you, and see if you can
+work out how it works.  Scan through the source, and step over it in
+the debugger.  Play, poke, investigate, fiddle! You'll probably get to
+understand not just your chosen area but a much wider range of
+\&\fIperl\fR's activity as well, and probably sooner than you'd think.
+.SS """The Road goes ever on and on, down from the door where it began."""
+.IX Subsection """The Road goes ever on and on, down from the door where it began."""
+If you can do these things, you've started on the long road to Perl
+porting.  Thanks for wanting to help make Perl better \- and happy
+hacking!
+.SS "Metaphoric Quotations"
+.IX Subsection "Metaphoric Quotations"
+If you recognized the quote about the Road above, you're in luck.
+.PP
+Most software projects begin each file with a literal description of
+each file's purpose.  Perl instead begins each with a literary allusion
+to that file's purpose.
+.PP
+Like chapters in many books, all top-level Perl source files (along
+with a few others here and there) begin with an epigrammatic
+inscription that alludes, indirectly and metaphorically, to the
+material you're about to read.
+.PP
+Quotations are taken from writings of J.R.R. Tolkien pertaining to his
+Legendarium, almost always from \fIThe Lord of the Rings\fR.  Chapters and
+page numbers are given using the following editions:
+.IP \(bu 4
+\&\fIThe Hobbit\fR, by J.R.R. Tolkien.  The hardcover, 70th\-anniversary
+edition of 2007 was used, published in the UK by Harper Collins
+Publishers and in the US by the Houghton Mifflin Company.
+.IP \(bu 4
+\&\fIThe Lord of the Rings\fR, by J.R.R. Tolkien.  The hardcover,
+50th\-anniversary edition of 2004 was used, published in the UK by
+Harper Collins Publishers and in the US by the Houghton Mifflin
+Company.
+.IP \(bu 4
+\&\fIThe Lays of Beleriand\fR, by J.R.R. Tolkien and published posthumously
+by his son and literary executor, C.J.R. Tolkien, being the 3rd of the
+12 volumes in Christopher's mammoth \fIHistory of Middle Earth\fR.  Page
+numbers derive from the hardcover edition, first published in 1983 by
+George Allen & Unwin; no page numbers changed for the special 3\-volume
+omnibus edition of 2002 or the various trade-paper editions, all again
+now by Harper Collins or Houghton Mifflin.
+.PP
+Other JRRT books fair game for quotes would thus include \fIThe
+Adventures of Tom Bombadil\fR, \fIThe Silmarillion\fR, \fIUnfinished Tales\fR,
+and \fIThe Tale of the Children of Hurin\fR, all but the first
+posthumously assembled by CJRT.  But \fIThe Lord of the Rings\fR itself is
+perfectly fine and probably best to quote from, provided you can find a
+suitable quote there.
+.PP
+So if you were to supply a new, complete, top-level source file to add
+to Perl, you should conform to this peculiar practice by yourself
+selecting an appropriate quotation from Tolkien, retaining the original
+spelling and punctuation and using the same format the rest of the
+quotes are in.  Indirect and oblique is just fine; remember, it's a
+metaphor, so being meta is, after all, what it's for.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This document was originally written by Nathan Torkington, and is
+maintained by the perl5\-porters mailing list.
diff --git a/upstream/mageia-cauldron/man1/perlhacktips.1 b/upstream/mageia-cauldron/man1/perlhacktips.1
new file mode 100644
index 00000000..b9fa2a7c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhacktips.1
@@ -0,0 +1,2067 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHACKTIPS 1"
+.TH PERLHACKTIPS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhacktips \- Tips for Perl core C code hacking
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document will help you learn the best way to go about hacking on
+the Perl core C code.  It covers common problems, debugging, profiling,
+and more.
+.PP
+If you haven't read perlhack and perlhacktut yet, you might want
+to do that first.
+.SH "COMMON PROBLEMS"
+.IX Header "COMMON PROBLEMS"
+Perl source now permits some specific C99 features which we know are
+supported by all platforms, but mostly plays by ANSI C89 rules.
+You don't care about some particular platform having broken Perl? I
+hear there is still a strong demand for J2EE programmers.
+.SS "Perl environment problems"
+.IX Subsection "Perl environment problems"
+.IP \(bu 4
+Not compiling with threading
+.Sp
+Compiling with threading (\-Duseithreads) completely rewrites the
+function prototypes of Perl.  You better try your changes with that.
+Related to this is the difference between "Perl_\-less" and "Perl_\-ly"
+APIs, for example:
+.Sp
+.Vb 2
+\&  Perl_sv_setiv(aTHX_ ...);
+\&  sv_setiv(...);
+.Ve
+.Sp
+The first one explicitly passes in the context, which is needed for
+e.g. threaded builds.  The second one does that implicitly; do not get
+them mixed.  If you are not passing in a aTHX_, you will need to do a
+dTHX as the first thing in the function.
+.Sp
+See "How multiple interpreters and concurrency are
+supported" in perlguts for further discussion about context.
+.IP \(bu 4
+Not compiling with \-DDEBUGGING
+.Sp
+The DEBUGGING define exposes more code to the compiler, therefore more
+ways for things to go wrong.  You should try it.
+.IP \(bu 4
+Introducing (non-read-only) globals
+.Sp
+Do not introduce any modifiable globals, truly global or file static.
+They are bad form and complicate multithreading and other forms of
+concurrency.  The right way is to introduce them as new interpreter
+variables, see \fIintrpvar.h\fR (at the very end for binary
+compatibility).
+.Sp
+Introducing read-only (const) globals is okay, as long as you verify
+with e.g. \f(CW\*(C`nm libperl.a|egrep \-v \*(Aq [TURtr] \*(Aq\*(C'\fR (if your \f(CW\*(C`nm\*(C'\fR has
+BSD-style output) that the data you added really is read-only.  (If it
+is, it shouldn't show up in the output of that command.)
+.Sp
+If you want to have static strings, make them constant:
+.Sp
+.Vb 1
+\&  static const char etc[] = "...";
+.Ve
+.Sp
+If you want to have arrays of constant strings, note carefully the
+right combination of \f(CW\*(C`const\*(C'\fRs:
+.Sp
+.Vb 2
+\&    static const char * const yippee[] =
+\&        {"hi", "ho", "silver"};
+.Ve
+.IP \(bu 4
+Not exporting your new function
+.Sp
+Some platforms (Win32, AIX, VMS, OS/2, to name a few) require any
+function that is part of the public API (the shared Perl library) to be
+explicitly marked as exported.  See the discussion about \fIembed.pl\fR in
+perlguts.
+.IP \(bu 4
+Exporting your new function
+.Sp
+The new shiny result of either genuine new functionality or your
+arduous refactoring is now ready and correctly exported.  So what could
+possibly go wrong?
+.Sp
+Maybe simply that your function did not need to be exported in the
+first place.  Perl has a long and not so glorious history of exporting
+functions that it should not have.
+.Sp
+If the function is used only inside one source code file, make it
+static.  See the discussion about \fIembed.pl\fR in perlguts.
+.Sp
+If the function is used across several files, but intended only for
+Perl's internal use (and this should be the common case), do not export
+it to the public API.  See the discussion about \fIembed.pl\fR in
+perlguts.
+.SS C99
+.IX Subsection "C99"
+Starting from 5.35.5 we now permit some C99 features in the core C source.
+However, code in dual life extensions still needs to be C89 only, because it
+needs to compile against earlier version of Perl running on older platforms.
+Also note that our headers need to also be valid as C++, because XS extensions
+written in C++ need to include them, hence \fImember structure initialisers\fR
+can't be used in headers.
+.PP
+C99 support is still far from complete on all platforms we currently support.
+As a baseline we can only assume C89 semantics with the specific C99 features
+described below, which we've verified work everywhere.  It's fine to probe for
+additional C99 features and use them where available, providing there is also a
+fallback for compilers that don't support the feature.  For example, we use C11
+thread local storage when available, but fall back to POSIX thread specific
+APIs otherwise, and we use \f(CW\*(C`char\*(C'\fR for booleans if \f(CW\*(C`<stdbool.h>\*(C'\fR isn't
+available.
+.PP
+Code can use (and rely on) the following C99 features being present
+.IP \(bu 4
+mixed declarations and code
+.IP \(bu 4
+64 bit integer types
+.Sp
+For consistency with the existing source code, use the typedefs \f(CW\*(C`I64\*(C'\fR and
+\&\f(CW\*(C`U64\*(C'\fR, instead of using \f(CW\*(C`long long\*(C'\fR and \f(CW\*(C`unsigned long long\*(C'\fR directly.
+.IP \(bu 4
+variadic macros
+.Sp
+.Vb 2
+\&    void greet(char *file, unsigned int line, char *format, ...);
+\&    #define logged_greet(...) greet(_\|_FILE_\|_, _\|_LINE_\|_, _\|_VA_ARGS_\|_);
+.Ve
+.Sp
+Note that \f(CW\*(C`_\|_VA_OPT_\|_\*(C'\fR is a gcc extension not yet in any published standard.
+.IP \(bu 4
+declarations in for loops
+.Sp
+.Vb 3
+\&    for (const char *p = message; *p; ++p) {
+\&        putchar(*p);
+\&    }
+.Ve
+.IP \(bu 4
+member structure initialisers
+.Sp
+But not in headers, as support was only added to C++ relatively recently.
+.Sp
+Hence this is fine in C and XS code, but not headers:
+.Sp
+.Vb 4
+\&    struct message {
+\&        char *action;
+\&        char *target;
+\&    };
+\&
+\&    struct message mcguffin = {
+\&        .target = "member structure initialisers",
+\&        .action = "Built"
+\&     };
+.Ve
+.IP \(bu 4
+flexible array members
+.Sp
+This is standards conformant:
+.Sp
+.Vb 4
+\&    struct greeting {
+\&        unsigned int len;
+\&        char message[];
+\&    };
+.Ve
+.Sp
+However, the source code already uses the "unwarranted chumminess with the
+compiler" hack in many places:
+.Sp
+.Vb 4
+\&    struct greeting {
+\&        unsigned int len;
+\&        char message[1];
+\&    };
+.Ve
+.Sp
+Strictly it \fBis\fR undefined behaviour accessing beyond \f(CW\*(C`message[0]\*(C'\fR, but this
+has been a commonly used hack since K&R times, and using it hasn't been a
+practical issue anywhere (in the perl source or any other common C code).
+Hence it's unclear what we would gain from actively changing to the C99
+approach.
+.IP \(bu 4
+\&\f(CW\*(C`//\*(C'\fR comments
+.Sp
+All compilers we tested support their use. Not all humans we tested support
+their use.
+.PP
+Code explicitly should not use any other C99 features. For example
+.IP \(bu 4
+variable length arrays
+.Sp
+Not supported by \fBany\fR MSVC, and this is not going to change.
+.Sp
+Even "variable" length arrays where the variable is a constant expression
+are syntax errors under MSVC.
+.IP \(bu 4
+C99 types in \f(CW\*(C`<stdint.h>\*(C'\fR
+.Sp
+Use \f(CW\*(C`PERL_INT_FAST8_T\*(C'\fR etc as defined in \fIhandy.h\fR
+.IP \(bu 4
+C99 format strings in \f(CW\*(C`<inttypes.h>\*(C'\fR
+.Sp
+\&\f(CW\*(C`snprintf\*(C'\fR in the VMS libc only added support for \f(CW\*(C`PRIdN\*(C'\fR etc very recently,
+meaning that there are live supported installations without this, or formats
+such as \f(CW%zu\fR.
+.Sp
+(perl's \f(CW\*(C`sv_catpvf\*(C'\fR etc use parser code code in \f(CW\*(C`sv.c\*(C'\fR, which supports the
+\&\f(CW\*(C`z\*(C'\fR modifier, along with perl-specific formats such as \f(CW\*(C`SVf\*(C'\fR.)
+.PP
+If you want to use a C99 feature not listed above then you need to do one of
+.IP \(bu 4
+Probe for it in \fIConfigure\fR, set a variable in \fIconfig.sh\fR, and add fallback logic in the headers for platforms which don't have it.
+.IP \(bu 4
+Write test code and verify that it works on platforms we need to support, before relying on it unconditionally.
+.PP
+Likely you want to repeat the same plan as we used to get the current C99
+feature set. See the message at https://markmail.org/thread/odr4fjrn72u2fkpz
+for the C99 probes we used before. Note that the two most "fussy" compilers
+appear to be MSVC and the vendor compiler on VMS. To date all the *nix
+compilers have been far more flexible in what they support.
+.PP
+On *nix platforms, \fIConfigure\fR attempts to set compiler flags appropriately.
+All vendor compilers that we tested defaulted to C99 (or C11) support.
+However, older versions of gcc default to C89, or permit \fImost\fR C99 (with
+warnings), but forbid \fIdeclarations in for loops\fR unless \f(CW\*(C`\-std=gnu99\*(C'\fR is
+added. The alternative \f(CW\*(C`\-std=c99\*(C'\fR \fBmight\fR seem better, but using it on some
+platforms can prevent \f(CW\*(C`<unistd.h>\*(C'\fR declaring some prototypes being
+declared, which breaks the build. gcc's \f(CW\*(C`\-ansi\*(C'\fR flag implies \f(CW\*(C`\-std=c89\*(C'\fR so we
+can no longer set that, hence the Configure option \f(CW\*(C`\-gccansipedantic\*(C'\fR now only
+adds \f(CW\*(C`\-pedantic\*(C'\fR.
+.PP
+The Perl core source code files (the ones at the top level of the source code
+distribution) are automatically compiled with as many as possible of the
+\&\f(CW\*(C`\-std=gnu99\*(C'\fR, \f(CW\*(C`\-pedantic\*(C'\fR, and a selection of \f(CW\*(C`\-W\*(C'\fR flags (see
+cflags.SH). Files in \fIext/\fR \fIdist/\fR \fIcpan/\fR etc are compiled with the same
+flags as the installed perl would use to compile XS extensions.
+.PP
+Basically, it's safe to assume that \fIConfigure\fR and \fIcflags.SH\fR have
+picked the best combination of flags for the version of gcc on the platform,
+and attempting to add more flags related to enforcing a C dialect will
+cause problems either locally, or on other systems that the code is shipped
+to.
+.PP
+We believe that the C99 support in gcc 3.1 is good enough for us, but we don't
+have a 19 year old gcc handy to check this :\-)
+If you have ancient vendor compilers that don't default to C99, the flags
+you might want to try are
+.IP AIX 4
+.IX Item "AIX"
+\&\f(CW\*(C`\-qlanglvl=stdc99\*(C'\fR
+.IP HP/UX 4
+.IX Item "HP/UX"
+\&\f(CW\*(C`\-AC99\*(C'\fR
+.IP Solaris 4
+.IX Item "Solaris"
+\&\f(CW\*(C`\-xc99\*(C'\fR
+.SS "Symbol Names and Namespace Pollution"
+.IX Subsection "Symbol Names and Namespace Pollution"
+\fIChoosing legal symbol names\fR
+.IX Subsection "Choosing legal symbol names"
+.PP
+C reserves for its implementation any symbol whose name begins with an
+underscore followed immediately by either an uppercase letter \f(CW\*(C`[A\-Z]\*(C'\fR
+or another underscore.  C++ further reserves any symbol containing two
+consecutive underscores, and further reserves in the global name space any
+symbol beginning with an underscore, not just ones followed by a
+capital.  We care about C++ because \f(CW\*(C`hdr\*(C'\fR files need to be compilable by
+it, and some people do all their development using a C++ compiler.
+.PP
+The consequences of failing to do this are probably none.  Unless you
+stumble on a name that the implementation uses, things will work.
+Indeed, the perl core has more than a few instances of using
+implementation-reserved symbols.  (These are gradually being changed.)
+But your code might stop working any time that the implementation
+decides to use a name you already had chosen, potentially many years
+before.
+.PP
+It's best then to:
+.ie n .IP "\fBDon't begin a symbol name with an underscore\fR; (\fIe.g.\fR, don't use: ""_FOOBAR"")" 4
+.el .IP "\fBDon't begin a symbol name with an underscore\fR; (\fIe.g.\fR, don't use: \f(CW_FOOBAR\fR)" 4
+.IX Item "Don't begin a symbol name with an underscore; (e.g., don't use: _FOOBAR)"
+.PD 0
+.ie n .IP "\fBDon't use two consecutive underscores in a symbol name\fR; (\fIe.g.\fR, don't use ""FOO_\|_BAR"")" 4
+.el .IP "\fBDon't use two consecutive underscores in a symbol name\fR; (\fIe.g.\fR, don't use \f(CWFOO_\|_BAR\fR)" 4
+.IX Item "Don't use two consecutive underscores in a symbol name; (e.g., don't use FOO__BAR)"
+.PD
+.PP
+POSIX also reserves many symbols.  See Section 2.2.2 in
+<http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html>.
+Perl also has conflicts with that.
+.PP
+Perl reserves for its use any symbol beginning with \f(CW\*(C`Perl\*(C'\fR, \f(CW\*(C`perl\*(C'\fR, or
+\&\f(CW\*(C`PL_\*(C'\fR.  Any time you introduce a macro into a \f(CW\*(C`hdr\*(C'\fR file that doesn't
+follow that convention, you are creating the possiblity of a namespace
+clash with an existing XS module, unless you restrict it by, say,
+.PP
+.Vb 3
+\& #ifdef PERL_CORE
+\& #  define my_symbol
+\& #endif
+.Ve
+.PP
+There are many symbols in \f(CW\*(C`hdr\*(C'\fR files that aren't of this form, and
+which are accessible from XS namespace, intentionally or not, just about
+anything in \fIconfig.h\fR, for example.
+.PP
+Having to use one of these prefixes detracts from the readability of the
+code, and hasn't been an actual issue for non-trivial names.  Things
+like perl defining its own \f(CW\*(C`MAX\*(C'\fR macro have been problematic, but they
+were quickly discovered, and a \f(CW\*(C`#ifdef\ PERL_CORE\*(C'\fR guard added.
+.PP
+So there's no rule imposed about using such symbols, just be aware of
+the issues.
+.PP
+\fIChoosing good symbol names\fR
+.IX Subsection "Choosing good symbol names"
+.PP
+Ideally, a symbol name name should correctly and precisely describe its
+intended purpose.  But there is a tension between that and getting names
+that are overly long and hence awkward to type and read.  Metaphors
+could be helpful (a poetic name), but those tend to be culturally
+specific, and may not translate for someone whose native language isn't
+English, or even comes from a different cultural background.  Besides,
+the talent of writing poetry seems to be rare in programmers.
+.PP
+Certain symbol names don't reflect their purpose, but are nonetheless
+fine to use because of long-standing conventions.  These often
+originated in the field of Mathematics, where \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`j\*(C'\fR are
+frequently used as subscripts, and \f(CW\*(C`n\*(C'\fR as a population count.  Since at
+least the 1950's, computer programs have used \f(CW\*(C`i\*(C'\fR, \fIetc.\fR as loop
+variables.
+.PP
+Our guidance is to choose a name that reasonably describes the purpose,
+and to comment its declaration more precisely.
+.PP
+One certainly shouldn't use misleading nor ambiguous names.  \f(CW\*(C`last_foo\*(C'\fR
+could mean either the final \f(CW\*(C`foo\*(C'\fR or the previous \f(CW\*(C`foo\*(C'\fR, and so could
+be confusing to the reader, or even to the writer coming back to the
+code after a few months of working on something else.  Sometimes the
+programmer has a particular line of thought in mind, and it doesn't
+occur to them that ambiguity is present.
+.PP
+There are probably still many off\-by\-1 bugs around because the name
+"\f(CW\*(C`av_len\*(C'\fR" in perlapi doesn't correspond to what other \fI\-len\fR constructs
+mean, such as "\f(CW\*(C`sv_len\*(C'\fR" in perlapi.  Awkward (and controversial)
+synonyms were created to use instead that conveyed its true meaning
+("\f(CW\*(C`av_top_index\*(C'\fR" in perlapi).  Eventually, though someone had the better
+idea to create a new name to signify what most people think \f(CW\*(C`\-len\*(C'\fR
+signifies.  So "\f(CW\*(C`av_count\*(C'\fR" in perlapi was born.  And we wish it had been
+thought up much earlier.
+.SS "Writing safer macros"
+.IX Subsection "Writing safer macros"
+Macros are used extensively in the Perl core for such things as hiding
+internal details from the caller, so that it doesn't have to be
+concerned about them.  For example, most lines of code don't need
+to know if they are running on a threaded versus unthreaded perl.  That
+detail is automatically mostly hidden.
+.PP
+It is often better to use an inline function instead of a macro.  They
+are immune to name collisions with the caller, and don't magnify
+problems when called with parameters that are expressions with side
+effects.  There was a time when one might choose a macro over an inline
+function because compiler support for inline functions was quite
+limited.  Some only would actually only inline the first two or three
+encountered in a compilation.  But those days are long gone, and inline
+functions are fully supported in modern compilers.
+.PP
+Nevertheless, there are situations where a function won't do, and a
+macro is required.  One example is when a parameter can be any of
+several types.  A function has to be declared with a single explicit
+.PP
+Or maybe the code involved is so trivial that a function would be just
+complicating overkill, such as when the macro simply creates a mnemonic
+name for some constant value.
+.PP
+If you do choose to use a non-trivial macro, be aware that there are
+several avoidable pitfalls that can occur.  Keep in mind that a macro is
+expanded within the lexical context of each place in the source it is
+called.  If you have a token \f(CW\*(C`foo\*(C'\fR in the macro and the source happens
+also to have \f(CW\*(C`foo\*(C'\fR, the meaning of the macro's \f(CW\*(C`foo\*(C'\fR will become that
+of the caller's.  Sometimes that is exactly the behavior you want, but
+be aware that this tends to be confusing later on.  It effectively turns
+\&\f(CW\*(C`foo\*(C'\fR into a reserved word for any code that calls the macro, and this
+fact is usually not documented nor considered.  It is safer to pass
+\&\f(CW\*(C`foo\*(C'\fR as a parameter, so that \f(CW\*(C`foo\*(C'\fR remains freely available to the
+caller and the macro interface is explicitly specified.
+.PP
+Worse is when the equivalence between the two \f(CW\*(C`foo\*(C'\fR's is coincidental.
+Suppose for example, that the macro declares a variable
+.PP
+.Vb 1
+\& int foo
+.Ve
+.PP
+That works fine as long as the caller doesn't define the string \f(CW\*(C`foo\*(C'\fR
+in some way.  And it might not be until years later that someone comes
+along with an instance where \f(CW\*(C`foo\*(C'\fR is used.  For example a future
+caller could do this:
+.PP
+.Vb 1
+\& #define foo  bar
+.Ve
+.PP
+Then that declaration of \f(CW\*(C`foo\*(C'\fR in the macro suddenly becomes
+.PP
+.Vb 1
+\& int bar
+.Ve
+.PP
+That could mean that something completely different happens than
+intended.  It is hard to debug; the macro and call may not even be in
+the same file, so it would require some digging and gnashing of teeth to
+figure out.
+.PP
+Therefore, if a macro does use variables, their names should be such
+that it is very unlikely that they would collide with any caller, now or
+forever.  One way to do that, now being used in the perl source, is to
+include the name of the macro itself as part of the name of each
+variable in the macro.  Suppose the macro is named \f(CW\*(C`SvPV\*(C'\fR  Then we
+could have
+.PP
+.Vb 1
+\& int foo_svpv_ = 0;
+.Ve
+.PP
+This is harder to read than plain \f(CW\*(C`foo\*(C'\fR, but it is pretty much
+guaranteed that a caller will never naively use \f(CW\*(C`foo_svpv_\*(C'\fR (and run
+into problems).  (The lowercasing makes it clearer that this is a
+variable, but assumes that there won't be two elements whose names
+differ only in the case of their letters.)  The trailing underscore
+makes it even more unlikely to clash, as those, by convention, signify a
+private variable name.  (See "Choosing legal symbol names" for
+restrictions on what names you can use.)
+.PP
+This kind of name collision doesn't happen with the macro's formal
+parameters, so they don't need to have complicated names.  But there are
+pitfalls when a a parameter is an expression, or has some Perl magic
+attached.  When calling a function, C will evaluate the parameter once,
+and pass the result to the function.  But when calling a macro, the
+parameter is copied as-is by the C preprocessor to each instance inside
+the macro.  This means that when evaluating a parameter having side
+effects, the function and macro results differ.  This is particularly
+fraught when a parameter has overload magic, say it is a tied variable
+that reads the next line in a file upon each evaluation.  Having it read
+multiple lines per call is probably not what the caller intended.  If a
+macro refers to a potentially overloadable parameter more than once, it
+should first make a copy and then use that copy the rest of the time.
+There are macros in the perl core that violate this, but are gradually
+being converted, usually by changing to use inline functions instead.
+.PP
+Above we said "first make a copy".  In a macro, that is easier said than
+done, because macros are normally expressions, and declarations aren't
+allowed in expressions.  But the \f(CW\*(C`STMT_START\*(C'\fR\ ..\ \f(CW\*(C`STMT_END\*(C'\fR
+construct, described in perlapi, allows you to
+have declarations in most contexts, as long as you don't need a return
+value.  If you do need a value returned, you can make the interface such
+that a pointer is passed to the construct, which then stores its result
+there.  (Or you can use GCC brace groups.  But these require a fallback
+if the code will ever get executed on a platform that lacks this
+non-standard extension to C.  And that fallback would be another code
+path, which can get out-of-sync with the brace group one, so doing this
+isn't advisable.)  In situations where there's no other way, Perl does
+furnish "\f(CW\*(C`PL_Sv\*(C'\fR" in perlintern and "\f(CW\*(C`PL_na\*(C'\fR" in perlapi to use (with a
+slight performance penalty) for some such common cases.  But beware that
+a call chain involving multiple macros using them will zap the other's
+use.  These have been very difficult to debug.
+.PP
+For a concrete example of these pitfalls in action, see
+<https://perlmonks.org/?node_id=11144355>
+.SS "Portability problems"
+.IX Subsection "Portability problems"
+The following are common causes of compilation and/or execution
+failures, not common to Perl as such.  The C FAQ is good bedtime
+reading.  Please test your changes with as many C compilers and
+platforms as possible; we will, anyway, and it's nice to save oneself
+from public embarrassment.
+.PP
+Also study perlport carefully to avoid any bad assumptions about the
+operating system, filesystems, character set, and so forth.
+.PP
+Do not assume an operating system indicates a certain compiler.
+.IP \(bu 4
+Casting pointers to integers or casting integers to pointers
+.Sp
+.Vb 3
+\&    void castaway(U8* p)
+\&    {
+\&      IV i = p;
+.Ve
+.Sp
+or
+.Sp
+.Vb 3
+\&    void castaway(U8* p)
+\&    {
+\&      IV i = (IV)p;
+.Ve
+.Sp
+Both are bad, and broken, and unportable.  Use the \fBPTR2IV()\fR macro that
+does it right.  (Likewise, there are \fBPTR2UV()\fR, \fBPTR2NV()\fR, \fBINT2PTR()\fR, and
+\&\fBNUM2PTR()\fR.)
+.IP \(bu 4
+Casting between function pointers and data pointers
+.Sp
+Technically speaking casting between function pointers and data
+pointers is unportable and undefined, but practically speaking it seems
+to work, but you should use the \fBFPTR2DPTR()\fR and \fBDPTR2FPTR()\fR macros.
+Sometimes you can also play games with unions.
+.IP \(bu 4
+Assuming sizeof(int) == sizeof(long)
+.Sp
+There are platforms where longs are 64 bits, and platforms where ints
+are 64 bits, and while we are out to shock you, even platforms where
+shorts are 64 bits.  This is all legal according to the C standard.  (In
+other words, "long long" is not a portable way to specify 64 bits, and
+"long long" is not even guaranteed to be any wider than "long".)
+.Sp
+Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth.
+Avoid things like I32 because they are \fBnot\fR guaranteed to be
+\&\fIexactly\fR 32 bits, they are \fIat least\fR 32 bits, nor are they
+guaranteed to be \fBint\fR or \fBlong\fR.  If you explicitly need
+64\-bit variables, use I64 and U64.
+.IP \(bu 4
+Assuming one can dereference any type of pointer for any type of data
+.Sp
+.Vb 2
+\&  char *p = ...;
+\&  long pony = *(long *)p;    /* BAD */
+.Ve
+.Sp
+Many platforms, quite rightly so, will give you a core dump instead of
+a pony if the p happens not to be correctly aligned.
+.IP \(bu 4
+Lvalue casts
+.Sp
+.Vb 1
+\&  (int)*p = ...;    /* BAD */
+.Ve
+.Sp
+Simply not portable.  Get your lvalue to be of the right type, or maybe
+use temporary variables, or dirty tricks with unions.
+.IP \(bu 4
+Assume \fBanything\fR about structs (especially the ones you don't
+control, like the ones coming from the system headers)
+.RS 4
+.IP \(bu 8
+That a certain field exists in a struct
+.IP \(bu 8
+That no other fields exist besides the ones you know of
+.IP \(bu 8
+That a field is of certain signedness, sizeof, or type
+.IP \(bu 8
+That the fields are in a certain order
+.RS 8
+.IP \(bu 8
+While C guarantees the ordering specified in the struct definition,
+between different platforms the definitions might differ
+.RE
+.RS 8
+.RE
+.IP \(bu 8
+That the sizeof(struct) or the alignments are the same everywhere
+.RS 8
+.IP \(bu 8
+There might be padding bytes between the fields to align the fields \-
+the bytes can be anything
+.IP \(bu 8
+Structs are required to be aligned to the maximum alignment required by
+the fields \- which for native types is for usually equivalent to
+\&\fBsizeof()\fR of the field
+.RE
+.RS 8
+.RE
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Assuming the character set is ASCIIish
+.Sp
+Perl can compile and run under EBCDIC platforms.  See perlebcdic.
+This is transparent for the most part, but because the character sets
+differ, you shouldn't use numeric (decimal, octal, nor hex) constants
+to refer to characters.  You can safely say \f(CW\*(AqA\*(Aq\fR, but not \f(CW0x41\fR.
+You can safely say \f(CW\*(Aq\en\*(Aq\fR, but not \f(CW\*(C`\e012\*(C'\fR.  However, you can use
+macros defined in \fIutf8.h\fR to specify any code point portably.
+\&\f(CWLATIN1_TO_NATIVE(0xDF)\fR is going to be the code point that means
+LATIN SMALL LETTER SHARP S on whatever platform you are running on (on
+ASCII platforms it compiles without adding any extra code, so there is
+zero performance hit on those).  The acceptable inputs to
+\&\f(CW\*(C`LATIN1_TO_NATIVE\*(C'\fR are from \f(CW0x00\fR through \f(CW0xFF\fR.  If your input
+isn't guaranteed to be in that range, use \f(CW\*(C`UNICODE_TO_NATIVE\*(C'\fR instead.
+\&\f(CW\*(C`NATIVE_TO_LATIN1\*(C'\fR and \f(CW\*(C`NATIVE_TO_UNICODE\*(C'\fR translate the opposite
+direction.
+.Sp
+If you need the string representation of a character that doesn't have a
+mnemonic name in C, you should add it to the list in
+\&\fIregen/unicode_constants.pl\fR, and have Perl create \f(CW\*(C`#define\*(C'\fR's for you,
+based on the current platform.
+.Sp
+Note that the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW\*(C'\fR and \f(CW\*(C`to\fR\f(CIFOO\fR\f(CW\*(C'\fR macros in \fIhandy.h\fR work
+properly on native code points and strings.
+.Sp
+Also, the range 'A' \- 'Z' in ASCII is an unbroken sequence of 26 upper
+case alphabetic characters.  That is not true in EBCDIC.  Nor for 'a' to
+\&'z'.  But '0' \- '9' is an unbroken range in both systems.  Don't assume
+anything about other ranges.  (Note that special handling of ranges in
+regular expression patterns and transliterations makes it appear to Perl
+code that the aforementioned ranges are all unbroken.)
+.Sp
+Many of the comments in the existing code ignore the possibility of
+EBCDIC, and may be wrong therefore, even if the code works.  This is
+actually a tribute to the successful transparent insertion of being
+able to handle EBCDIC without having to change pre-existing code.
+.Sp
+UTF\-8 and UTF-EBCDIC are two different encodings used to represent
+Unicode code points as sequences of bytes.  Macros  with the same names
+(but different definitions) in \fIutf8.h\fR and \fIutfebcdic.h\fR are used to
+allow the calling code to think that there is only one such encoding.
+This is almost always referred to as \f(CW\*(C`utf8\*(C'\fR, but it means the EBCDIC
+version as well.  Again, comments in the code may well be wrong even if
+the code itself is right.  For example, the concept of UTF\-8 \f(CW\*(C`invariant
+characters\*(C'\fR differs between ASCII and EBCDIC.  On ASCII platforms, only
+characters that do not have the high-order bit set (i.e.  whose ordinals
+are strict ASCII, 0 \- 127) are invariant, and the documentation and
+comments in the code may assume that, often referring to something
+like, say, \f(CW\*(C`hibit\*(C'\fR.  The situation differs and is not so simple on
+EBCDIC machines, but as long as the code itself uses the
+\&\f(CWNATIVE_IS_INVARIANT()\fR macro appropriately, it works, even if the
+comments are wrong.
+.Sp
+As noted in "TESTING" in perlhack, when writing test scripts, the file
+\&\fIt/charset_tools.pl\fR contains some helpful functions for writing tests
+valid on both ASCII and EBCDIC platforms.  Sometimes, though, a test
+can't use a function and it's inconvenient to have different test
+versions depending on the platform.  There are 20 code points that are
+the same in all 4 character sets currently recognized by Perl (the 3
+EBCDIC code pages plus ISO 8859\-1 (ASCII/Latin1)).  These can be used in
+such tests, though there is a small possibility that Perl will become
+available in yet another character set, breaking your test.  All but one
+of these code points are C0 control characters.  The most significant
+controls that are the same are \f(CW\*(C`\e0\*(C'\fR, \f(CW\*(C`\er\*(C'\fR, and \f(CW\*(C`\eN{VT}\*(C'\fR (also
+specifiable as \f(CW\*(C`\ecK\*(C'\fR, \f(CW\*(C`\ex0B\*(C'\fR, \f(CW\*(C`\eN{U+0B}\*(C'\fR, or \f(CW\*(C`\e013\*(C'\fR).  The single
+non-control is U+00B6 PILCROW SIGN.  The controls that are the same have
+the same bit pattern in all 4 character sets, regardless of the UTF8ness
+of the string containing them.  The bit pattern for U+B6 is the same in
+all 4 for non\-UTF8 strings, but differs in each when its containing
+string is UTF\-8 encoded.  The only other code points that have some sort
+of sameness across all 4 character sets are the pair 0xDC and 0xFC.
+Together these represent upper\- and lowercase LATIN LETTER U WITH
+DIAERESIS, but which is upper and which is lower may be reversed: 0xDC
+is the capital in Latin1 and 0xFC is the small letter, while 0xFC is the
+capital in EBCDIC and 0xDC is the small one.  This factoid may be
+exploited in writing case insensitive tests that are the same across all
+4 character sets.
+.IP \(bu 4
+Assuming the character set is just ASCII
+.Sp
+ASCII is a 7 bit encoding, but bytes have 8 bits in them.  The 128 extra
+characters have different meanings depending on the locale.  Absent a
+locale, currently these extra characters are generally considered to be
+unassigned, and this has presented some problems.  This has being
+changed starting in 5.12 so that these characters can be considered to
+be Latin\-1 (ISO\-8859\-1).
+.IP \(bu 4
+Mixing #define and #ifdef
+.Sp
+.Vb 6
+\&  #define BURGLE(x) ... \e
+\&  #ifdef BURGLE_OLD_STYLE        /* BAD */
+\&  ... do it the old way ... \e
+\&  #else
+\&  ... do it the new way ... \e
+\&  #endif
+.Ve
+.Sp
+You cannot portably "stack" cpp directives.  For example in the above
+you need two separate \fBBURGLE()\fR #defines, one for each #ifdef branch.
+.IP \(bu 4
+Adding non-comment stuff after #endif or #else
+.Sp
+.Vb 5
+\&  #ifdef SNOSH
+\&  ...
+\&  #else !SNOSH    /* BAD */
+\&  ...
+\&  #endif SNOSH    /* BAD */
+.Ve
+.Sp
+The #endif and #else cannot portably have anything non-comment after
+them.  If you want to document what is going (which is a good idea
+especially if the branches are long), use (C) comments:
+.Sp
+.Vb 5
+\&  #ifdef SNOSH
+\&  ...
+\&  #else /* !SNOSH */
+\&  ...
+\&  #endif /* SNOSH */
+.Ve
+.Sp
+The gcc option \f(CW\*(C`\-Wendif\-labels\*(C'\fR warns about the bad variant (by
+default on starting from Perl 5.9.4).
+.IP \(bu 4
+Having a comma after the last element of an enum list
+.Sp
+.Vb 5
+\&  enum color {
+\&    CERULEAN,
+\&    CHARTREUSE,
+\&    CINNABAR,     /* BAD */
+\&  };
+.Ve
+.Sp
+is not portable.  Leave out the last comma.
+.Sp
+Also note that whether enums are implicitly morphable to ints varies
+between compilers, you might need to (int).
+.IP \(bu 4
+Mixing signed char pointers with unsigned char pointers
+.Sp
+.Vb 4
+\&  int foo(char *s) { ... }
+\&  ...
+\&  unsigned char *t = ...; /* Or U8* t = ... */
+\&  foo(t);   /* BAD */
+.Ve
+.Sp
+While this is legal practice, it is certainly dubious, and downright
+fatal in at least one platform: for example VMS cc considers this a
+fatal error.  One cause for people often making this mistake is that a
+"naked char" and therefore dereferencing a "naked char pointer" have an
+undefined signedness: it depends on the compiler and the flags of the
+compiler and the underlying platform whether the result is signed or
+unsigned.  For this very same reason using a 'char' as an array index is
+bad.
+.IP \(bu 4
+Macros that have string constants and their arguments as substrings of
+the string constants
+.Sp
+.Vb 2
+\&  #define FOO(n) printf("number = %d\en", n)    /* BAD */
+\&  FOO(10);
+.Ve
+.Sp
+Pre-ANSI semantics for that was equivalent to
+.Sp
+.Vb 1
+\&  printf("10umber = %d\e10");
+.Ve
+.Sp
+which is probably not what you were expecting.  Unfortunately at least
+one reasonably common and modern C compiler does "real backward
+compatibility" here, in AIX that is what still happens even though the
+rest of the AIX compiler is very happily C89.
+.IP \(bu 4
+Using printf formats for non-basic C types
+.Sp
+.Vb 2
+\&   IV i = ...;
+\&   printf("i = %d\en", i);    /* BAD */
+.Ve
+.Sp
+While this might by accident work in some platform (where IV happens to
+be an \f(CW\*(C`int\*(C'\fR), in general it cannot.  IV might be something larger.  Even
+worse the situation is with more specific types (defined by Perl's
+configuration step in \fIconfig.h\fR):
+.Sp
+.Vb 2
+\&   Uid_t who = ...;
+\&   printf("who = %d\en", who);    /* BAD */
+.Ve
+.Sp
+The problem here is that Uid_t might be not only not \f(CW\*(C`int\*(C'\fR\-wide but it
+might also be unsigned, in which case large uids would be printed as
+negative values.
+.Sp
+There is no simple solution to this because of \fBprintf()\fR's limited
+intelligence, but for many types the right format is available as with
+either 'f' or '_f' suffix, for example:
+.Sp
+.Vb 2
+\&   IVdf /* IV in decimal */
+\&   UVxf /* UV is hexadecimal */
+\&
+\&   printf("i = %"IVdf"\en", i); /* The IVdf is a string constant. */
+\&
+\&   Uid_t_f /* Uid_t in decimal */
+\&
+\&   printf("who = %"Uid_t_f"\en", who);
+.Ve
+.Sp
+Or you can try casting to a "wide enough" type:
+.Sp
+.Vb 1
+\&   printf("i = %"IVdf"\en", (IV)something_very_small_and_signed);
+.Ve
+.Sp
+See "Formatted Printing of Size_t and SSize_t" in perlguts for how to
+print those.
+.Sp
+Also remember that the \f(CW%p\fR format really does require a void pointer:
+.Sp
+.Vb 2
+\&   U8* p = ...;
+\&   printf("p = %p\en", (void*)p);
+.Ve
+.Sp
+The gcc option \f(CW\*(C`\-Wformat\*(C'\fR scans for such problems.
+.IP \(bu 4
+Blindly passing va_list
+.Sp
+Not all platforms support passing va_list to further varargs (stdarg)
+functions.  The right thing to do is to copy the va_list using the
+\&\fBPerl_va_copy()\fR if the NEED_VA_COPY is defined.
+.IP \(bu 4
+Using gcc statement expressions
+.Sp
+.Vb 1
+\&   val = ({...;...;...});    /* BAD */
+.Ve
+.Sp
+While a nice extension, it's not portable.  Historically, Perl used
+them in macros if available to gain some extra speed (essentially
+as a funky form of inlining), but we now support (or emulate) C99
+\&\f(CW\*(C`static inline\*(C'\fR functions, so use them instead. Declare functions as
+\&\f(CW\*(C`PERL_STATIC_INLINE\*(C'\fR to transparently fall back to emulation where needed.
+.IP \(bu 4
+Binding together several statements in a macro
+.Sp
+Use the macros \f(CW\*(C`STMT_START\*(C'\fR and \f(CW\*(C`STMT_END\*(C'\fR.
+.Sp
+.Vb 3
+\&   STMT_START {
+\&      ...
+\&   } STMT_END
+.Ve
+.Sp
+But there can be subtle (but avoidable if you do it right) bugs
+introduced with these; see "\f(CW\*(C`STMT_START\*(C'\fR" in perlapi for best practices
+for their use.
+.IP \(bu 4
+Testing for operating systems or versions when you should be testing for
+features
+.Sp
+.Vb 3
+\&  #ifdef _\|_FOONIX_\|_    /* BAD */
+\&  foo = quux();
+\&  #endif
+.Ve
+.Sp
+Unless you know with 100% certainty that \fBquux()\fR is only ever available
+for the "Foonix" operating system \fBand\fR that is available \fBand\fR
+correctly working for \fBall\fR past, present, \fBand\fR future versions of
+"Foonix", the above is very wrong.  This is more correct (though still
+not perfect, because the below is a compile-time check):
+.Sp
+.Vb 3
+\&  #ifdef HAS_QUUX
+\&  foo = quux();
+\&  #endif
+.Ve
+.Sp
+How does the HAS_QUUX become defined where it needs to be?  Well, if
+Foonix happens to be Unixy enough to be able to run the Configure
+script, and Configure has been taught about detecting and testing
+\&\fBquux()\fR, the HAS_QUUX will be correctly defined.  In other platforms, the
+corresponding configuration step will hopefully do the same.
+.Sp
+In a pinch, if you cannot wait for Configure to be educated, or if you
+have a good hunch of where \fBquux()\fR might be available, you can
+temporarily try the following:
+.Sp
+.Vb 3
+\&  #if (defined(_\|_FOONIX_\|_) || defined(_\|_BARNIX_\|_))
+\&  # define HAS_QUUX
+\&  #endif
+\&
+\&  ...
+\&
+\&  #ifdef HAS_QUUX
+\&  foo = quux();
+\&  #endif
+.Ve
+.Sp
+But in any case, try to keep the features and operating systems
+separate.
+.Sp
+A good resource on the predefined macros for various operating
+systems, compilers, and so forth is
+<http://sourceforge.net/p/predef/wiki/Home/>
+.IP \(bu 4
+Assuming the contents of static memory pointed to by the return values
+of Perl wrappers for C library functions doesn't change.  Many C library
+functions return pointers to static storage that can be overwritten by
+subsequent calls to the same or related functions.  Perl has wrappers
+for some of these functions.  Originally many of those wrappers returned
+those volatile pointers.  But over time almost all of them have evolved
+to return stable copies.  To cope with the remaining ones, do a
+"savepv" in perlapi to make a copy, thus avoiding these problems.  You
+will have to free the copy when you're done to avoid memory leaks.  If
+you don't have control over when it gets freed, you'll need to make the
+copy in a mortal scalar, like so
+.Sp
+.Vb 1
+\& SvPVX(sv_2mortal(newSVpv(volatile_string, 0)))
+.Ve
+.SS "Problematic System Interfaces"
+.IX Subsection "Problematic System Interfaces"
+.IP \(bu 4
+Perl strings are NOT the same as C strings:  They may contain \f(CW\*(C`NUL\*(C'\fR
+characters, whereas a C string is terminated by the first \f(CW\*(C`NUL\*(C'\fR.
+That is why Perl API functions that deal with strings generally take a
+pointer to the first byte and either a length or a pointer to the byte
+just beyond the final one.
+.Sp
+And this is the reason that many of the C library string handling
+functions should not be used.  They don't cope with the full generality
+of Perl strings.  It may be that your test cases don't have embedded
+\&\f(CW\*(C`NUL\*(C'\fRs, and so the tests pass, whereas there may well eventually arise
+real-world cases where they fail.  A lesson here is to include \f(CW\*(C`NUL\*(C'\fRs
+in your tests.  Now it's fairly rare in most real world cases to get
+\&\f(CW\*(C`NUL\*(C'\fRs, so your code may seem to work, until one day a \f(CW\*(C`NUL\*(C'\fR comes
+along.
+.Sp
+Here's an example.  It used to be a common paradigm, for decades, in the
+perl core to use \f(CW\*(C`strchr("list",\ c)\*(C'\fR to see if the character \f(CW\*(C`c\*(C'\fR is
+any of the ones given in \f(CW"list"\fR, a double-quote-enclosed string of
+the set of characters that we are seeing if \f(CW\*(C`c\*(C'\fR is one of.  As long as
+\&\f(CW\*(C`c\*(C'\fR isn't a \f(CW\*(C`NUL\*(C'\fR, it works.  But when \f(CW\*(C`c\*(C'\fR is a \f(CW\*(C`NUL\*(C'\fR, \f(CW\*(C`strchr\*(C'\fR
+returns a pointer to the terminating \f(CW\*(C`NUL\*(C'\fR in \f(CW"list"\fR.   This likely
+will result in a segfault or a security issue when the caller uses that
+end pointer as the starting point to read from.
+.Sp
+A solution to this and many similar issues is to use the \f(CW\*(C`mem\*(C'\fR\fI\-foo\fR C
+library functions instead.  In this case \f(CW\*(C`memchr\*(C'\fR can be used to see if
+\&\f(CW\*(C`c\*(C'\fR is in \f(CW"list"\fR and works even if \f(CW\*(C`c\*(C'\fR is \f(CW\*(C`NUL\*(C'\fR.  These functions
+need an additional parameter to give the string length.
+In the case of literal string parameters, perl has defined macros that
+calculate the length for you.  See "String Handling" in perlapi.
+.IP \(bu 4
+\&\fBmalloc\fR\|(0), \fBrealloc\fR\|(0), calloc(0, 0) are non-portable.  To be portable
+allocate at least one byte.  (In general you should rarely need to work
+at this low level, but instead use the various malloc wrappers.)
+.IP \(bu 4
+\&\fBsnprintf()\fR \- the return type is unportable.  Use \fBmy_snprintf()\fR instead.
+.SS "Security problems"
+.IX Subsection "Security problems"
+Last but not least, here are various tips for safer coding.
+See also perlclib for libc/stdio replacements one should use.
+.IP \(bu 4
+Do not use \fBgets()\fR
+.Sp
+Or we will publicly ridicule you.  Seriously.
+.IP \(bu 4
+Do not use \fBtmpfile()\fR
+.Sp
+Use \fBmkstemp()\fR instead.
+.IP \(bu 4
+Do not use \fBstrcpy()\fR or \fBstrcat()\fR or \fBstrncpy()\fR or \fBstrncat()\fR
+.Sp
+Use \fBmy_strlcpy()\fR and \fBmy_strlcat()\fR instead: they either use the native
+implementation, or Perl's own implementation (borrowed from the public
+domain implementation of INN).
+.IP \(bu 4
+Do not use \fBsprintf()\fR or \fBvsprintf()\fR
+.Sp
+If you really want just plain byte strings, use \fBmy_snprintf()\fR and
+\&\fBmy_vsnprintf()\fR instead, which will try to use \fBsnprintf()\fR and
+\&\fBvsnprintf()\fR if those safer APIs are available.  If you want something
+fancier than a plain byte string, use
+\&\f(CW\*(C`Perl_form\*(C'\fR() or SVs and
+\&\f(CWPerl_sv_catpvf()\fR.
+.Sp
+Note that glibc \f(CWprintf()\fR, \f(CWsprintf()\fR, etc. are buggy before glibc
+version 2.17.  They won't allow a \f(CW\*(C`%.s\*(C'\fR format with a precision to
+create a string that isn't valid UTF\-8 if the current underlying locale
+of the program is UTF\-8.  What happens is that the \f(CW%s\fR and its operand are
+simply skipped without any notice.
+<https://sourceware.org/bugzilla/show_bug.cgi?id=6530>.
+.IP \(bu 4
+Do not use \fBatoi()\fR
+.Sp
+Use \fBgrok_atoUV()\fR instead.  \fBatoi()\fR has ill-defined behavior on overflows,
+and cannot be used for incremental parsing.  It is also affected by locale,
+which is bad.
+.IP \(bu 4
+Do not use \fBstrtol()\fR or \fBstrtoul()\fR
+.Sp
+Use \fBgrok_atoUV()\fR instead.  \fBstrtol()\fR or \fBstrtoul()\fR (or their IV/UV\-friendly
+macro disguises, \fBStrtol()\fR and \fBStrtoul()\fR, or \fBAtol()\fR and \fBAtoul()\fR are
+affected by locale, which is bad.
+.SH DEBUGGING
+.IX Header "DEBUGGING"
+You can compile a special debugging version of Perl, which allows you
+to use the \f(CW\*(C`\-D\*(C'\fR option of Perl to tell more about what Perl is doing.
+But sometimes there is no alternative than to dive in with a debugger,
+either to see the stack trace of a core dump (very useful in a bug
+report), or trying to figure out what went wrong before the core dump
+happened, or how did we end up having wrong or unexpected results.
+.SS "Poking at Perl"
+.IX Subsection "Poking at Perl"
+To really poke around with Perl, you'll probably want to build Perl for
+debugging, like this:
+.PP
+.Vb 2
+\&    ./Configure \-d \-DDEBUGGING
+\&    make
+.Ve
+.PP
+\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR turns on the C compiler's \f(CW\*(C`\-g\*(C'\fR flag to have it produce
+debugging information which will allow us to step through a running
+program, and to see in which C function we are at (without the debugging
+information we might see only the numerical addresses of the functions,
+which is not very helpful). It will also turn on the \f(CW\*(C`DEBUGGING\*(C'\fR
+compilation symbol which enables all the internal debugging code in Perl.
+There are a whole bunch of things you can debug with this:
+perlrun lists them all, and the best way to find out
+about them is to play about with them.  The most useful options are
+probably
+.PP
+.Vb 5
+\&    l  Context (loop) stack processing
+\&    s  Stack snapshots (with v, displays all stacks)
+\&    t  Trace execution
+\&    o  Method and overloading resolution
+\&    c  String/numeric conversions
+.Ve
+.PP
+For example
+.PP
+.Vb 8
+\&    $ perl \-Dst \-e \*(Aq$a + 1\*(Aq
+\&    ....
+\&    (\-e:1)      gvsv(main::a)
+\&        =>  UNDEF
+\&    (\-e:1)      const(IV(1))
+\&        =>  UNDEF  IV(1)
+\&    (\-e:1)      add
+\&        =>  NV(1)
+.Ve
+.PP
+Some of the functionality of the debugging code can be achieved with a
+non-debugging perl by using XS modules:
+.PP
+.Vb 2
+\&    \-Dr => use re \*(Aqdebug\*(Aq
+\&    \-Dx => use O \*(AqDebug\*(Aq
+.Ve
+.SS "Using a source-level debugger"
+.IX Subsection "Using a source-level debugger"
+If the debugging output of \f(CW\*(C`\-D\*(C'\fR doesn't help you, it's time to step
+through perl's execution with a source-level debugger.
+.IP \(bu 3
+We'll use \f(CW\*(C`gdb\*(C'\fR for our examples here; the principles will apply to
+any debugger (many vendors call their debugger \f(CW\*(C`dbx\*(C'\fR), but check the
+manual of the one you're using.
+.PP
+To fire up the debugger, type
+.PP
+.Vb 1
+\&    gdb ./perl
+.Ve
+.PP
+Or if you have a core dump:
+.PP
+.Vb 1
+\&    gdb ./perl core
+.Ve
+.PP
+You'll want to do that in your Perl source tree so the debugger can
+read the source code.  You should see the copyright message, followed by
+the prompt.
+.PP
+.Vb 1
+\&    (gdb)
+.Ve
+.PP
+\&\f(CW\*(C`help\*(C'\fR will get you into the documentation, but here are the most
+useful commands:
+.IP \(bu 3
+run [args]
+.Sp
+Run the program with the given arguments.
+.IP \(bu 3
+break function_name
+.IP \(bu 3
+break source.c:xxx
+.Sp
+Tells the debugger that we'll want to pause execution when we reach
+either the named function (but see "Internal Functions" in perlguts!) or
+the given line in the named source file.
+.IP \(bu 3
+step
+.Sp
+Steps through the program a line at a time.
+.IP \(bu 3
+next
+.Sp
+Steps through the program a line at a time, without descending into
+functions.
+.IP \(bu 3
+continue
+.Sp
+Run until the next breakpoint.
+.IP \(bu 3
+finish
+.Sp
+Run until the end of the current function, then stop again.
+.IP \(bu 3
+\&'enter'
+.Sp
+Just pressing Enter will do the most recent operation again \- it's a
+blessing when stepping through miles of source code.
+.IP \(bu 3
+ptype
+.Sp
+Prints the C definition of the argument given.
+.Sp
+.Vb 10
+\&  (gdb) ptype PL_op
+\&  type = struct op {
+\&      OP *op_next;
+\&      OP *op_sibparent;
+\&      OP *(*op_ppaddr)(void);
+\&      PADOFFSET op_targ;
+\&      unsigned int op_type : 9;
+\&      unsigned int op_opt : 1;
+\&      unsigned int op_slabbed : 1;
+\&      unsigned int op_savefree : 1;
+\&      unsigned int op_static : 1;
+\&      unsigned int op_folded : 1;
+\&      unsigned int op_spare : 2;
+\&      U8 op_flags;
+\&      U8 op_private;
+\&  } *
+.Ve
+.IP \(bu 3
+print
+.Sp
+Execute the given C code and print its results.  \fBWARNING\fR: Perl makes
+heavy use of macros, and \fIgdb\fR does not necessarily support macros
+(see later "gdb macro support").  You'll have to substitute them
+yourself, or to invoke cpp on the source code files (see "The .i
+Targets") So, for instance, you can't say
+.Sp
+.Vb 1
+\&    print SvPV_nolen(sv)
+.Ve
+.Sp
+but you have to say
+.Sp
+.Vb 1
+\&    print Perl_sv_2pv_nolen(sv)
+.Ve
+.PP
+You may find it helpful to have a "macro dictionary", which you can
+produce by saying \f(CW\*(C`cpp \-dM perl.c | sort\*(C'\fR.  Even then, \fIcpp\fR won't
+recursively apply those macros for you.
+.SS "gdb macro support"
+.IX Subsection "gdb macro support"
+Recent versions of \fIgdb\fR have fairly good macro support, but in order
+to use it you'll need to compile perl with macro definitions included
+in the debugging information.  Using \fIgcc\fR version 3.1, this means
+configuring with \f(CW\*(C`\-Doptimize=\-g3\*(C'\fR.  Other compilers might use a
+different switch (if they support debugging macros at all).
+.SS "Dumping Perl Data Structures"
+.IX Subsection "Dumping Perl Data Structures"
+One way to get around this macro hell is to use the dumping functions
+in \fIdump.c\fR; these work a little like an internal
+Devel::Peek, but they also cover OPs and other
+structures that you can't get at from Perl.  Let's take an example.
+We'll use the \f(CW\*(C`$a = $b + $c\*(C'\fR we used before, but give it a bit of
+context: \f(CW\*(C`$b = "6XXXX"; $c = 2.3;\*(C'\fR.  Where's a good place to stop and
+poke around?
+.PP
+What about \f(CW\*(C`pp_add\*(C'\fR, the function we examined earlier to implement the
+\&\f(CW\*(C`+\*(C'\fR operator:
+.PP
+.Vb 2
+\&    (gdb) break Perl_pp_add
+\&    Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.
+.Ve
+.PP
+Notice we use \f(CW\*(C`Perl_pp_add\*(C'\fR and not \f(CW\*(C`pp_add\*(C'\fR \- see
+"Internal Functions" in perlguts.  With the breakpoint in place, we can
+run our program:
+.PP
+.Vb 1
+\&    (gdb) run \-e \*(Aq$b = "6XXXX"; $c = 2.3; $a = $b + $c\*(Aq
+.Ve
+.PP
+Lots of junk will go past as gdb reads in the relevant source files and
+libraries, and then:
+.PP
+.Vb 5
+\&    Breakpoint 1, Perl_pp_add () at pp_hot.c:309
+\&    1396    dSP; dATARGET; bool useleft; SV *svl, *svr;
+\&    (gdb) step
+\&    311           dPOPTOPnnrl_ul;
+\&    (gdb)
+.Ve
+.PP
+We looked at this bit of code before, and we said that
+\&\f(CW\*(C`dPOPTOPnnrl_ul\*(C'\fR arranges for two \f(CW\*(C`NV\*(C'\fRs to be placed into \f(CW\*(C`left\*(C'\fR and
+\&\f(CW\*(C`right\*(C'\fR \- let's slightly expand it:
+.PP
+.Vb 3
+\& #define dPOPTOPnnrl_ul  NV right = POPn; \e
+\&                         SV *leftsv = TOPs; \e
+\&                         NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
+.Ve
+.PP
+\&\f(CW\*(C`POPn\*(C'\fR takes the SV from the top of the stack and obtains its NV
+either directly (if \f(CW\*(C`SvNOK\*(C'\fR is set) or by calling the \f(CW\*(C`sv_2nv\*(C'\fR
+function.  \f(CW\*(C`TOPs\*(C'\fR takes the next SV from the top of the stack \- yes,
+\&\f(CW\*(C`POPn\*(C'\fR uses \f(CW\*(C`TOPs\*(C'\fR \- but doesn't remove it.  We then use \f(CW\*(C`SvNV\*(C'\fR to
+get the NV from \f(CW\*(C`leftsv\*(C'\fR in the same way as before \- yes, \f(CW\*(C`POPn\*(C'\fR uses
+\&\f(CW\*(C`SvNV\*(C'\fR.
+.PP
+Since we don't have an NV for \f(CW$b\fR, we'll have to use \f(CW\*(C`sv_2nv\*(C'\fR to
+convert it.  If we step again, we'll find ourselves there:
+.PP
+.Vb 4
+\&    (gdb) step
+\&    Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
+\&    1669        if (!sv)
+\&    (gdb)
+.Ve
+.PP
+We can now use \f(CW\*(C`Perl_sv_dump\*(C'\fR to investigate the SV:
+.PP
+.Vb 8
+\&    (gdb) print Perl_sv_dump(sv)
+\&    SV = PV(0xa057cc0) at 0xa0675d0
+\&    REFCNT = 1
+\&    FLAGS = (POK,pPOK)
+\&    PV = 0xa06a510 "6XXXX"\e0
+\&    CUR = 5
+\&    LEN = 6
+\&    $1 = void
+.Ve
+.PP
+We know we're going to get \f(CW6\fR from this, so let's finish the
+subroutine:
+.PP
+.Vb 4
+\&    (gdb) finish
+\&    Run till exit from #0  Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
+\&    0x462669 in Perl_pp_add () at pp_hot.c:311
+\&    311           dPOPTOPnnrl_ul;
+.Ve
+.PP
+We can also dump out this op: the current op is always stored in
+\&\f(CW\*(C`PL_op\*(C'\fR, and we can dump it with \f(CW\*(C`Perl_op_dump\*(C'\fR.  This'll give us
+similar output to CPAN module B::Debug.
+.PP
+.Vb 10
+\&    (gdb) print Perl_op_dump(PL_op)
+\&    {
+\&    13  TYPE = add  ===> 14
+\&        TARG = 1
+\&        FLAGS = (SCALAR,KIDS)
+\&        {
+\&            TYPE = null  ===> (12)
+\&              (was rv2sv)
+\&            FLAGS = (SCALAR,KIDS)
+\&            {
+\&    11          TYPE = gvsv  ===> 12
+\&                FLAGS = (SCALAR)
+\&                GV = main::b
+\&            }
+\&        }
+.Ve
+.PP
+# finish this later #
+.SS "Using gdb to look at specific parts of a program"
+.IX Subsection "Using gdb to look at specific parts of a program"
+With the example above, you knew to look for \f(CW\*(C`Perl_pp_add\*(C'\fR, but what if
+there were multiple calls to it all over the place, or you didn't know what
+the op was you were looking for?
+.PP
+One way to do this is to inject a rare call somewhere near what you're looking
+for.  For example, you could add \f(CW\*(C`study\*(C'\fR before your method:
+.PP
+.Vb 1
+\&    study;
+.Ve
+.PP
+And in gdb do:
+.PP
+.Vb 1
+\&    (gdb) break Perl_pp_study
+.Ve
+.PP
+And then step until you hit what you're
+looking for.  This works well in a loop
+if you want to only break at certain iterations:
+.PP
+.Vb 3
+\&    for my $c (1..100) {
+\&        study if $c == 50;
+\&    }
+.Ve
+.SS "Using gdb to look at what the parser/lexer are doing"
+.IX Subsection "Using gdb to look at what the parser/lexer are doing"
+If you want to see what perl is doing when parsing/lexing your code, you can
+use \f(CW\*(C`BEGIN {}\*(C'\fR:
+.PP
+.Vb 3
+\&    print "Before\en";
+\&    BEGIN { study; }
+\&    print "After\en";
+.Ve
+.PP
+And in gdb:
+.PP
+.Vb 1
+\&    (gdb) break Perl_pp_study
+.Ve
+.PP
+If you want to see what the parser/lexer is doing inside of \f(CW\*(C`if\*(C'\fR blocks and
+the like you need to be a little trickier:
+.PP
+.Vb 1
+\&    if ($a && $b && do { BEGIN { study } 1 } && $c) { ... }
+.Ve
+.SH "SOURCE CODE STATIC ANALYSIS"
+.IX Header "SOURCE CODE STATIC ANALYSIS"
+Various tools exist for analysing C source code \fBstatically\fR, as
+opposed to \fBdynamically\fR, that is, without executing the code.  It is
+possible to detect resource leaks, undefined behaviour, type
+mismatches, portability problems, code paths that would cause illegal
+memory accesses, and other similar problems by just parsing the C code
+and looking at the resulting graph, what does it tell about the
+execution and data flows.  As a matter of fact, this is exactly how C
+compilers know to give warnings about dubious code.
+.SS lint
+.IX Subsection "lint"
+The good old C code quality inspector, \f(CW\*(C`lint\*(C'\fR, is available in several
+platforms, but please be aware that there are several different
+implementations of it by different vendors, which means that the flags
+are not identical across different platforms.
+.PP
+There is a \f(CW\*(C`lint\*(C'\fR target in Makefile, but you may have to
+diddle with the flags (see above).
+.SS Coverity
+.IX Subsection "Coverity"
+Coverity (<http://www.coverity.com/>) is a product similar to lint and as
+a testbed for their product they periodically check several open source
+projects, and they give out accounts to open source developers to the
+defect databases.
+.PP
+There is Coverity setup for the perl5 project:
+<https://scan.coverity.com/projects/perl5>
+.SS "HP-UX cadvise (Code Advisor)"
+.IX Subsection "HP-UX cadvise (Code Advisor)"
+HP has a C/C++ static analyzer product for HP-UX caller Code Advisor.
+(Link not given here because the URL is horribly long and seems horribly
+unstable; use the search engine of your choice to find it.)  The use of
+the \f(CW\*(C`cadvise_cc\*(C'\fR recipe with \f(CW\*(C`Configure ... \-Dcc=./cadvise_cc\*(C'\fR
+(see cadvise "User Guide") is recommended; as is the use of \f(CW\*(C`+wall\*(C'\fR.
+.SS "cpd (cut-and-paste detector)"
+.IX Subsection "cpd (cut-and-paste detector)"
+The cpd tool detects cut-and-paste coding.  If one instance of the
+cut-and-pasted code changes, all the other spots should probably be
+changed, too.  Therefore such code should probably be turned into a
+subroutine or a macro.
+.PP
+cpd (<https://pmd.github.io/latest/pmd_userdocs_cpd.html>) is part of the pmd project
+(<https://pmd.github.io/>).  pmd was originally written for static
+analysis of Java code, but later the cpd part of it was extended to
+parse also C and C++.
+.PP
+Download the pmd\-bin\-X.Y.zip () from the SourceForge site, extract the
+pmd\-X.Y.jar from it, and then run that on source code thusly:
+.PP
+.Vb 2
+\&  java \-cp pmd\-X.Y.jar net.sourceforge.pmd.cpd.CPD \e
+\&   \-\-minimum\-tokens 100 \-\-files /some/where/src \-\-language c > cpd.txt
+.Ve
+.PP
+You may run into memory limits, in which case you should use the \-Xmx
+option:
+.PP
+.Vb 1
+\&  java \-Xmx512M ...
+.Ve
+.SS "gcc warnings"
+.IX Subsection "gcc warnings"
+Though much can be written about the inconsistency and coverage
+problems of gcc warnings (like \f(CW\*(C`\-Wall\*(C'\fR not meaning "all the warnings",
+or some common portability problems not being covered by \f(CW\*(C`\-Wall\*(C'\fR, or
+\&\f(CW\*(C`\-ansi\*(C'\fR and \f(CW\*(C`\-pedantic\*(C'\fR both being a poorly defined collection of
+warnings, and so forth), gcc is still a useful tool in keeping our
+coding nose clean.
+.PP
+The \f(CW\*(C`\-Wall\*(C'\fR is by default on.
+.PP
+It would be nice for \f(CW\*(C`\-pedantic\*(C'\fR) to be on always, but unfortunately it is not
+safe on all platforms \- for example fatal conflicts with the system headers
+(Solaris being a prime example).  If Configure \f(CW\*(C`\-Dgccansipedantic\*(C'\fR is used,
+the \f(CW\*(C`cflags\*(C'\fR frontend selects \f(CW\*(C`\-pedantic\*(C'\fR for the platforms where it is known
+to be safe.
+.PP
+The following extra flags are added:
+.IP \(bu 4
+\&\f(CW\*(C`\-Wendif\-labels\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Wextra\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Wc++\-compat\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Wwrite\-strings\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Werror=pointer\-arith\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Werror=vla\*(C'\fR
+.PP
+The following flags would be nice to have but they would first need
+their own Augean stablemaster:
+.IP \(bu 4
+\&\f(CW\*(C`\-Wshadow\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\-Wstrict\-prototypes\*(C'\fR
+.PP
+The \f(CW\*(C`\-Wtraditional\*(C'\fR is another example of the annoying tendency of gcc
+to bundle a lot of warnings under one switch (it would be impossible to
+deploy in practice because it would complain a lot) but it does contain
+some warnings that would be beneficial to have available on their own,
+such as the warning about string constants inside macros containing the
+macro arguments: this behaved differently pre-ANSI than it does in
+ANSI, and some C compilers are still in transition, AIX being an
+example.
+.SS "Warnings of other C compilers"
+.IX Subsection "Warnings of other C compilers"
+Other C compilers (yes, there \fBare\fR other C compilers than gcc) often
+have their "strict ANSI" or "strict ANSI with some portability
+extensions" modes on, like for example the Sun Workshop has its \f(CW\*(C`\-Xa\*(C'\fR
+mode on (though implicitly), or the DEC (these days, HP...) has its
+\&\f(CW\*(C`\-std1\*(C'\fR mode on.
+.SH "MEMORY DEBUGGERS"
+.IX Header "MEMORY DEBUGGERS"
+\&\fBNOTE 1\fR: Running under older memory debuggers such as Purify,
+valgrind or Third Degree greatly slows down the execution: seconds
+become minutes, minutes become hours.  For example as of Perl 5.8.1, the
+ext/Encode/t/Unicode.t takes extraordinarily long to complete under
+e.g. Purify, Third Degree, and valgrind.  Under valgrind it takes more
+than six hours, even on a snappy computer.  The said test must be doing
+something that is quite unfriendly for memory debuggers.  If you don't
+feel like waiting, that you can simply kill away the perl process.
+Roughly valgrind slows down execution by factor 10, AddressSanitizer by
+factor 2.
+.PP
+\&\fBNOTE 2\fR: To minimize the number of memory leak false alarms (see
+"PERL_DESTRUCT_LEVEL" for more information), you have to set the
+environment variable PERL_DESTRUCT_LEVEL to 2.  For example, like this:
+.PP
+.Vb 1
+\&    env PERL_DESTRUCT_LEVEL=2 valgrind ./perl \-Ilib ...
+.Ve
+.PP
+\&\fBNOTE 3\fR: There are known memory leaks when there are compile-time
+errors within eval or require, seeing \f(CW\*(C`S_doeval\*(C'\fR in the call stack is
+a good sign of these.  Fixing these leaks is non-trivial, unfortunately,
+but they must be fixed eventually.
+.PP
+\&\fBNOTE 4\fR: DynaLoader will not clean up after itself completely
+unless Perl is built with the Configure option
+\&\f(CW\*(C`\-Accflags=\-DDL_UNLOAD_ALL_AT_EXIT\*(C'\fR.
+.SS valgrind
+.IX Subsection "valgrind"
+The valgrind tool can be used to find out both memory leaks and illegal
+heap memory accesses.  As of version 3.3.0, Valgrind only supports Linux
+on x86, x86\-64 and PowerPC and Darwin (OS X) on x86 and x86\-64.  The
+special "test.valgrind" target can be used to run the tests under
+valgrind.  Found errors and memory leaks are logged in files named
+\&\fItestfile.valgrind\fR and by default output is displayed inline.
+.PP
+Example usage:
+.PP
+.Vb 1
+\&    make test.valgrind
+.Ve
+.PP
+Since valgrind adds significant overhead, tests will take much longer to
+run.  The valgrind tests support being run in parallel to help with this:
+.PP
+.Vb 1
+\&    TEST_JOBS=9 make test.valgrind
+.Ve
+.PP
+Note that the above two invocations will be very verbose as reachable
+memory and leak-checking is enabled by default.  If you want to just see
+pure errors, try:
+.PP
+.Vb 2
+\&    VG_OPTS=\*(Aq\-q \-\-leak\-check=no \-\-show\-reachable=no\*(Aq TEST_JOBS=9 \e
+\&        make test.valgrind
+.Ve
+.PP
+Valgrind also provides a cachegrind tool, invoked on perl as:
+.PP
+.Vb 1
+\&    VG_OPTS=\-\-tool=cachegrind make test.valgrind
+.Ve
+.PP
+As system libraries (most notably glibc) are also triggering errors,
+valgrind allows to suppress such errors using suppression files.  The
+default suppression file that comes with valgrind already catches a lot
+of them.  Some additional suppressions are defined in \fIt/perl.supp\fR.
+.PP
+To get valgrind and for more information see
+.PP
+.Vb 1
+\&    http://valgrind.org/
+.Ve
+.SS AddressSanitizer
+.IX Subsection "AddressSanitizer"
+AddressSanitizer ("ASan") consists of a compiler instrumentation module
+and a run-time \f(CW\*(C`malloc\*(C'\fR library. ASan is available for a variety of
+architectures, operating systems, and compilers (see project link below).
+It checks for unsafe memory usage, such as use after free and buffer
+overflow conditions, and is fast enough that you can easily compile your
+debugging or optimized perl with it. Modern versions of ASan check for
+memory leaks by default on most platforms, otherwise (e.g. x86_64 OS X)
+this feature can be enabled via \f(CW\*(C`ASAN_OPTIONS=detect_leaks=1\*(C'\fR.
+.PP
+To build perl with AddressSanitizer, your Configure invocation should
+look like:
+.PP
+.Vb 4
+\&    sh Configure \-des \-Dcc=clang \e
+\&       \-Accflags=\-fsanitize=address \-Aldflags=\-fsanitize=address \e
+\&       \-Alddlflags=\-shared\e \-fsanitize=address \e
+\&       \-fsanitize\-blacklist=\`pwd\`/asan_ignore
+.Ve
+.PP
+where these arguments mean:
+.IP \(bu 4
+\&\-Dcc=clang
+.Sp
+This should be replaced by the full path to your clang executable if it
+is not in your path.
+.IP \(bu 4
+\&\-Accflags=\-fsanitize=address
+.Sp
+Compile perl and extensions sources with AddressSanitizer.
+.IP \(bu 4
+\&\-Aldflags=\-fsanitize=address
+.Sp
+Link the perl executable with AddressSanitizer.
+.IP \(bu 4
+\&\-Alddlflags=\-shared\e \-fsanitize=address
+.Sp
+Link dynamic extensions with AddressSanitizer.  You must manually
+specify \f(CW\*(C`\-shared\*(C'\fR because using \f(CW\*(C`\-Alddlflags=\-shared\*(C'\fR will prevent
+Configure from setting a default value for \f(CW\*(C`lddlflags\*(C'\fR, which usually
+contains \f(CW\*(C`\-shared\*(C'\fR (at least on Linux).
+.IP \(bu 4
+\&\-fsanitize\-blacklist=`pwd`/asan_ignore
+.Sp
+AddressSanitizer will ignore functions listed in the \f(CW\*(C`asan_ignore\*(C'\fR
+file. (This file should contain a short explanation of why each of
+the functions is listed.)
+.PP
+See also
+<https://github.com/google/sanitizers/wiki/AddressSanitizer>.
+.SH PROFILING
+.IX Header "PROFILING"
+Depending on your platform there are various ways of profiling Perl.
+.PP
+There are two commonly used techniques of profiling executables:
+\&\fIstatistical time-sampling\fR and \fIbasic-block counting\fR.
+.PP
+The first method takes periodically samples of the CPU program counter,
+and since the program counter can be correlated with the code generated
+for functions, we get a statistical view of in which functions the
+program is spending its time.  The caveats are that very small/fast
+functions have lower probability of showing up in the profile, and that
+periodically interrupting the program (this is usually done rather
+frequently, in the scale of milliseconds) imposes an additional
+overhead that may skew the results.  The first problem can be alleviated
+by running the code for longer (in general this is a good idea for
+profiling), the second problem is usually kept in guard by the
+profiling tools themselves.
+.PP
+The second method divides up the generated code into \fIbasic blocks\fR.
+Basic blocks are sections of code that are entered only in the
+beginning and exited only at the end.  For example, a conditional jump
+starts a basic block.  Basic block profiling usually works by
+\&\fIinstrumenting\fR the code by adding \fIenter basic block #nnnn\fR
+book-keeping code to the generated code.  During the execution of the
+code the basic block counters are then updated appropriately.  The
+caveat is that the added extra code can skew the results: again, the
+profiling tools usually try to factor their own effects out of the
+results.
+.SS "Gprof Profiling"
+.IX Subsection "Gprof Profiling"
+\&\fIgprof\fR is a profiling tool available in many Unix platforms which
+uses \fIstatistical time-sampling\fR.  You can build a profiled version of
+\&\fIperl\fR by compiling using gcc with the flag \f(CW\*(C`\-pg\*(C'\fR.  Either edit
+\&\fIconfig.sh\fR or re-run \fIConfigure\fR.  Running the profiled version of
+Perl will create an output file called \fIgmon.out\fR which contains the
+profiling data collected during the execution.
+.PP
+quick hint:
+.PP
+.Vb 6
+\&    $ sh Configure \-des \-Dusedevel \-Accflags=\*(Aq\-pg\*(Aq \e
+\&        \-Aldflags=\*(Aq\-pg\*(Aq \-Alddlflags=\*(Aq\-pg \-shared\*(Aq \e
+\&        && make perl
+\&    $ ./perl ... # creates gmon.out in current directory
+\&    $ gprof ./perl > out
+\&    $ less out
+.Ve
+.PP
+(you probably need to add \f(CW\*(C`\-shared\*(C'\fR to the <\-Alddlflags> line until RT
+#118199 is resolved)
+.PP
+The \fIgprof\fR tool can then display the collected data in various ways.
+Usually \fIgprof\fR understands the following options:
+.IP \(bu 4
+\&\-a
+.Sp
+Suppress statically defined functions from the profile.
+.IP \(bu 4
+\&\-b
+.Sp
+Suppress the verbose descriptions in the profile.
+.IP \(bu 4
+\&\-e routine
+.Sp
+Exclude the given routine and its descendants from the profile.
+.IP \(bu 4
+\&\-f routine
+.Sp
+Display only the given routine and its descendants in the profile.
+.IP \(bu 4
+\&\-s
+.Sp
+Generate a summary file called \fIgmon.sum\fR which then may be given to
+subsequent gprof runs to accumulate data over several runs.
+.IP \(bu 4
+\&\-z
+.Sp
+Display routines that have zero usage.
+.PP
+For more detailed explanation of the available commands and output
+formats, see your own local documentation of \fIgprof\fR.
+.SS "GCC gcov Profiling"
+.IX Subsection "GCC gcov Profiling"
+\&\fIbasic block profiling\fR is officially available in gcc 3.0 and later.
+You can build a profiled version of \fIperl\fR by compiling using gcc with
+the flags \f(CW\*(C`\-fprofile\-arcs \-ftest\-coverage\*(C'\fR.  Either edit \fIconfig.sh\fR
+or re-run \fIConfigure\fR.
+.PP
+quick hint:
+.PP
+.Vb 9
+\&    $ sh Configure \-des \-Dusedevel \-Doptimize=\*(Aq\-g\*(Aq \e
+\&        \-Accflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage\*(Aq \e
+\&        \-Aldflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage\*(Aq \e
+\&        \-Alddlflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage \-shared\*(Aq \e
+\&        && make perl
+\&    $ rm \-f regexec.c.gcov regexec.gcda
+\&    $ ./perl ...
+\&    $ gcov regexec.c
+\&    $ less regexec.c.gcov
+.Ve
+.PP
+(you probably need to add \f(CW\*(C`\-shared\*(C'\fR to the <\-Alddlflags> line until RT
+#118199 is resolved)
+.PP
+Running the profiled version of Perl will cause profile output to be
+generated.  For each source file an accompanying \fI.gcda\fR file will be
+created.
+.PP
+To display the results you use the \fIgcov\fR utility (which should be
+installed if you have gcc 3.0 or newer installed).  \fIgcov\fR is run on
+source code files, like this
+.PP
+.Vb 1
+\&    gcov sv.c
+.Ve
+.PP
+which will cause \fIsv.c.gcov\fR to be created.  The \fI.gcov\fR files contain
+the source code annotated with relative frequencies of execution
+indicated by "#" markers.  If you want to generate \fI.gcov\fR files for
+all profiled object files, you can run something like this:
+.PP
+.Vb 3
+\&    for file in \`find . \-name \e*.gcno\`
+\&    do sh \-c "cd \`dirname $file\` && gcov \`basename $file .gcno\`"
+\&    done
+.Ve
+.PP
+Useful options of \fIgcov\fR include \f(CW\*(C`\-b\*(C'\fR which will summarise the basic
+block, branch, and function call coverage, and \f(CW\*(C`\-c\*(C'\fR which instead of
+relative frequencies will use the actual counts.  For more information
+on the use of \fIgcov\fR and basic block profiling with gcc, see the
+latest GNU CC manual.  As of gcc 4.8, this is at
+<http://gcc.gnu.org/onlinedocs/gcc/Gcov\-Intro.html#Gcov\-Intro>
+.SS "callgrind profiling"
+.IX Subsection "callgrind profiling"
+callgrind is a valgrind tool for profiling source code. Paired
+with kcachegrind (a Qt based UI), it gives you an overview of
+where code is taking up time, as well as the ability
+to examine callers, call trees, and more. One of its benefits
+is you can use it on perl and XS modules that have not been
+compiled with debugging symbols.
+.PP
+If perl is compiled with debugging symbols (\f(CW\*(C`\-g\*(C'\fR), you can view
+the annotated source and click around, much like Devel::NYTProf's
+HTML output.
+.PP
+For basic usage:
+.PP
+.Vb 1
+\&    valgrind \-\-tool=callgrind ./perl ...
+.Ve
+.PP
+By default it will write output to \fIcallgrind.out.PID\fR, but you
+can change that with \f(CW\*(C`\-\-callgrind\-out\-file=...\*(C'\fR
+.PP
+To view the data, do:
+.PP
+.Vb 1
+\&    kcachegrind callgrind.out.PID
+.Ve
+.PP
+If you'd prefer to view the data in a terminal, you can use
+\&\fIcallgrind_annotate\fR. In it's basic form:
+.PP
+.Vb 1
+\&    callgrind_annotate callgrind.out.PID | less
+.Ve
+.PP
+Some useful options are:
+.IP \(bu 4
+\&\-\-threshold
+.Sp
+Percentage of counts (of primary sort event) we are interested in.
+The default is 99%, 100% might show things that seem to be missing.
+.IP \(bu 4
+\&\-\-auto
+.Sp
+Annotate all source files containing functions that helped reach
+the event count threshold.
+.SH "MISCELLANEOUS TRICKS"
+.IX Header "MISCELLANEOUS TRICKS"
+.SS PERL_DESTRUCT_LEVEL
+.IX Subsection "PERL_DESTRUCT_LEVEL"
+If you want to run any of the tests yourself manually using e.g.
+valgrind, please note that by default perl \fBdoes not\fR explicitly
+cleanup all the memory it has allocated (such as global memory arenas)
+but instead lets the \fBexit()\fR of the whole program "take care" of such
+allocations, also known as "global destruction of objects".
+.PP
+There is a way to tell perl to do complete cleanup: set the environment
+variable PERL_DESTRUCT_LEVEL to a non-zero value.  The t/TEST wrapper
+does set this to 2, and this is what you need to do too, if you don't
+want to see the "global leaks": For example, for running under valgrind
+.PP
+.Vb 1
+\&    env PERL_DESTRUCT_LEVEL=2 valgrind ./perl \-Ilib t/foo/bar.t
+.Ve
+.PP
+(Note: the mod_perl apache module uses also this environment variable
+for its own purposes and extended its semantics.  Refer to the mod_perl
+documentation for more information.  Also, spawned threads do the
+equivalent of setting this variable to the value 1.)
+.PP
+If, at the end of a run you get the message \fIN scalars leaked\fR, you
+can recompile with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR,
+(\f(CW\*(C`Configure \-Accflags=\-DDEBUG_LEAKING_SCALARS\*(C'\fR), which will cause the
+addresses of all those leaked SVs to be dumped along with details as to
+where each SV was originally allocated.  This information is also
+displayed by Devel::Peek.  Note that the extra details recorded with
+each SV increases memory usage, so it shouldn't be used in production
+environments.  It also converts \f(CWnew_SV()\fR from a macro into a real
+function, so you can use your favourite debugger to discover where
+those pesky SVs were allocated.
+.PP
+If you see that you're leaking memory at runtime, but neither valgrind
+nor \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR will find anything, you're probably
+leaking SVs that are still reachable and will be properly cleaned up
+during destruction of the interpreter.  In such cases, using the \f(CW\*(C`\-Dm\*(C'\fR
+switch can point you to the source of the leak.  If the executable was
+built with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR, \f(CW\*(C`\-Dm\*(C'\fR will output SV
+allocations in addition to memory allocations.  Each SV allocation has a
+distinct serial number that will be written on creation and destruction
+of the SV.  So if you're executing the leaking code in a loop, you need
+to look for SVs that are created, but never destroyed between each
+cycle.  If such an SV is found, set a conditional breakpoint within
+\&\f(CWnew_SV()\fR and make it break only when \f(CW\*(C`PL_sv_serial\*(C'\fR is equal to the
+serial number of the leaking SV.  Then you will catch the interpreter in
+exactly the state where the leaking SV is allocated, which is
+sufficient in many cases to find the source of the leak.
+.PP
+As \f(CW\*(C`\-Dm\*(C'\fR is using the PerlIO layer for output, it will by itself
+allocate quite a bunch of SVs, which are hidden to avoid recursion.  You
+can bypass the PerlIO layer if you use the SV logging provided by
+\&\f(CW\*(C`\-DPERL_MEM_LOG\*(C'\fR instead.
+.SS PERL_MEM_LOG
+.IX Subsection "PERL_MEM_LOG"
+If compiled with \f(CW\*(C`\-DPERL_MEM_LOG\*(C'\fR (\f(CW\*(C`\-Accflags=\-DPERL_MEM_LOG\*(C'\fR), both
+memory and SV allocations go through logging functions, which is
+handy for breakpoint setting.
+.PP
+Unless \f(CW\*(C`\-DPERL_MEM_LOG_NOIMPL\*(C'\fR (\f(CW\*(C`\-Accflags=\-DPERL_MEM_LOG_NOIMPL\*(C'\fR) is
+also compiled, the logging functions read \f(CW$ENV\fR{PERL_MEM_LOG} to
+determine whether to log the event, and if so how:
+.PP
+.Vb 6
+\&    $ENV{PERL_MEM_LOG} =~ /m/           Log all memory ops
+\&    $ENV{PERL_MEM_LOG} =~ /s/           Log all SV ops
+\&    $ENV{PERL_MEM_LOG} =~ /c/           Additionally log C backtrace for
+\&                                        new_SV events
+\&    $ENV{PERL_MEM_LOG} =~ /t/           include timestamp in Log
+\&    $ENV{PERL_MEM_LOG} =~ /^(\ed+)/      write to FD given (default is 2)
+.Ve
+.PP
+Memory logging is somewhat similar to \f(CW\*(C`\-Dm\*(C'\fR but is independent of
+\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR, and at a higher level; all uses of \fBNewx()\fR, \fBRenew()\fR, and
+\&\fBSafefree()\fR are logged with the caller's source code file and line
+number (and C function name, if supported by the C compiler).  In
+contrast, \f(CW\*(C`\-Dm\*(C'\fR is directly at the point of \f(CWmalloc()\fR.  SV logging is
+similar.
+.PP
+Since the logging doesn't use PerlIO, all SV allocations are logged and
+no extra SV allocations are introduced by enabling the logging.  If
+compiled with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR, the serial number for each SV
+allocation is also logged.
+.PP
+The \f(CW\*(C`c\*(C'\fR option uses the \f(CW\*(C`Perl_c_backtrace\*(C'\fR facility, and therefore
+additionally requires the Configure \f(CW\*(C`\-Dusecbacktrace\*(C'\fR compile flag in
+order to access it.
+.SS "DDD over gdb"
+.IX Subsection "DDD over gdb"
+Those debugging perl with the DDD frontend over gdb may find the
+following useful:
+.PP
+You can extend the data conversion shortcuts menu, so for example you
+can display an SV's IV value with one click, without doing any typing.
+To do that simply edit ~/.ddd/init file and add after:
+.PP
+.Vb 6
+\&  ! Display shortcuts.
+\&  Ddd*gdbDisplayShortcuts: \e
+\&  /t ()   // Convert to Bin\en\e
+\&  /d ()   // Convert to Dec\en\e
+\&  /x ()   // Convert to Hex\en\e
+\&  /o ()   // Convert to Oct(\en\e
+.Ve
+.PP
+the following two lines:
+.PP
+.Vb 2
+\&  ((XPV*) (())\->sv_any )\->xpv_pv  // 2pvx\en\e
+\&  ((XPVIV*) (())\->sv_any )\->xiv_iv // 2ivx
+.Ve
+.PP
+so now you can do ivx and pvx lookups or you can plug there the sv_peek
+"conversion":
+.PP
+.Vb 1
+\&  Perl_sv_peek(my_perl, (SV*)()) // sv_peek
+.Ve
+.PP
+(The my_perl is for threaded builds.)  Just remember that every line,
+but the last one, should end with \en\e
+.PP
+Alternatively edit the init file interactively via: 3rd mouse button \->
+New Display \-> Edit Menu
+.PP
+Note: you can define up to 20 conversion shortcuts in the gdb section.
+.SS "C backtrace"
+.IX Subsection "C backtrace"
+On some platforms Perl supports retrieving the C level backtrace
+(similar to what symbolic debuggers like gdb do).
+.PP
+The backtrace returns the stack trace of the C call frames,
+with the symbol names (function names), the object names (like "perl"),
+and if it can, also the source code locations (file:line).
+.PP
+The supported platforms are Linux, and OS X (some *BSD might
+work at least partly, but they have not yet been tested).
+.PP
+This feature hasn't been tested with multiple threads, but it will
+only show the backtrace of the thread doing the backtracing.
+.PP
+The feature needs to be enabled with \f(CW\*(C`Configure \-Dusecbacktrace\*(C'\fR.
+.PP
+The \f(CW\*(C`\-Dusecbacktrace\*(C'\fR also enables keeping the debug information when
+compiling/linking (often: \f(CW\*(C`\-g\*(C'\fR).  Many compilers/linkers do support
+having both optimization and keeping the debug information.  The debug
+information is needed for the symbol names and the source locations.
+.PP
+Static functions might not be visible for the backtrace.
+.PP
+Source code locations, even if available, can often be missing or
+misleading if the compiler has e.g. inlined code.  Optimizer can
+make matching the source code and the object code quite challenging.
+.IP Linux 4
+.IX Item "Linux"
+You \fBmust\fR have the BFD (\-lbfd) library installed, otherwise \f(CW\*(C`perl\*(C'\fR will
+fail to link.  The BFD is usually distributed as part of the GNU binutils.
+.Sp
+Summary: \f(CW\*(C`Configure ... \-Dusecbacktrace\*(C'\fR
+and you need \f(CW\*(C`\-lbfd\*(C'\fR.
+.IP "OS X" 4
+.IX Item "OS X"
+The source code locations are supported \fBonly\fR if you have
+the Developer Tools installed.  (BFD is \fBnot\fR needed.)
+.Sp
+Summary: \f(CW\*(C`Configure ... \-Dusecbacktrace\*(C'\fR
+and installing the Developer Tools would be good.
+.PP
+Optionally, for trying out the feature, you may want to enable
+automatic dumping of the backtrace just before a warning or croak (die)
+message is emitted, by adding \f(CW\*(C`\-Accflags=\-DUSE_C_BACKTRACE_ON_ERROR\*(C'\fR
+for Configure.
+.PP
+Unless the above additional feature is enabled, nothing about the
+backtrace functionality is visible, except for the Perl/XS level.
+.PP
+Furthermore, even if you have enabled this feature to be compiled,
+you need to enable it in runtime with an environment variable:
+\&\f(CW\*(C`PERL_C_BACKTRACE_ON_ERROR=10\*(C'\fR.  It must be an integer higher
+than zero, telling the desired frame count.
+.PP
+Retrieving the backtrace from Perl level (using for example an XS
+extension) would be much less exciting than one would hope: normally
+you would see \f(CW\*(C`runops\*(C'\fR, \f(CW\*(C`entersub\*(C'\fR, and not much else.  This API is
+intended to be called \fBfrom within\fR the Perl implementation, not from
+Perl level execution.
+.PP
+The C API for the backtrace is as follows:
+.IP get_c_backtrace 4
+.IX Item "get_c_backtrace"
+.PD 0
+.IP free_c_backtrace 4
+.IX Item "free_c_backtrace"
+.IP get_c_backtrace_dump 4
+.IX Item "get_c_backtrace_dump"
+.IP dump_c_backtrace 4
+.IX Item "dump_c_backtrace"
+.PD
+.SS Poison
+.IX Subsection "Poison"
+If you see in a debugger a memory area mysteriously full of 0xABABABAB
+or 0xEFEFEFEF, you may be seeing the effect of the \fBPoison()\fR macros, see
+perlclib.
+.SS "Read-only optrees"
+.IX Subsection "Read-only optrees"
+Under ithreads the optree is read only.  If you want to enforce this, to
+check for write accesses from buggy code, compile with
+\&\f(CW\*(C`\-Accflags=\-DPERL_DEBUG_READONLY_OPS\*(C'\fR
+to enable code that allocates op memory
+via \f(CW\*(C`mmap\*(C'\fR, and sets it read-only when it is attached to a subroutine.
+Any write access to an op results in a \f(CW\*(C`SIGBUS\*(C'\fR and abort.
+.PP
+This code is intended for development only, and may not be portable
+even to all Unix variants.  Also, it is an 80% solution, in that it
+isn't able to make all ops read only.  Specifically it does not apply to
+op slabs belonging to \f(CW\*(C`BEGIN\*(C'\fR blocks.
+.PP
+However, as an 80% solution it is still effective, as it has caught
+bugs in the past.
+.SS "When is a bool not a bool?"
+.IX Subsection "When is a bool not a bool?"
+There wasn't necessarily a standard \f(CW\*(C`bool\*(C'\fR type on compilers prior to
+C99, and so some workarounds were created.  The \f(CW\*(C`TRUE\*(C'\fR and \f(CW\*(C`FALSE\*(C'\fR
+macros are still available as alternatives for \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR.
+And the \f(CW\*(C`cBOOL\*(C'\fR macro was created to correctly cast to a true/false
+value in all circumstances, but should no longer be necessary.
+Using \f(CW\*(C`(bool)\*(C'\fR\ \fIexpr\fR> should now always work.
+.PP
+There are no plans to remove any of \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`FALSE\*(C'\fR, nor \f(CW\*(C`cBOOL\*(C'\fR.
+.SS "Finding unsafe truncations"
+.IX Subsection "Finding unsafe truncations"
+You may wish to run \f(CW\*(C`Configure\*(C'\fR with something like
+.PP
+.Vb 1
+\&    \-Accflags=\*(Aq\-Wconversion \-Wno\-sign\-conversion \-Wno\-shorten\-64\-to\-32\*(Aq
+.Ve
+.PP
+or your compiler's equivalent to make it easier to spot any unsafe truncations
+that show up.
+.SS "The .i Targets"
+.IX Subsection "The .i Targets"
+You can expand the macros in a \fIfoo.c\fR file by saying
+.PP
+.Vb 1
+\&    make foo.i
+.Ve
+.PP
+which will expand the macros using cpp.  Don't be scared by the
+results.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This document was originally written by Nathan Torkington, and is
+maintained by the perl5\-porters mailing list.
diff --git a/upstream/mageia-cauldron/man1/perlhacktut.1 b/upstream/mageia-cauldron/man1/perlhacktut.1
new file mode 100644
index 00000000..84b55d4a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhacktut.1
@@ -0,0 +1,264 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHACKTUT 1"
+.TH PERLHACKTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhacktut \- Walk through the creation of a simple C code patch
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document takes you through a simple patch example.
+.PP
+If you haven't read perlhack yet, go do that first! You might also
+want to read through perlsource too.
+.PP
+Once you're done here, check out perlhacktips next.
+.SH "EXAMPLE OF A SIMPLE PATCH"
+.IX Header "EXAMPLE OF A SIMPLE PATCH"
+Let's take a simple patch from start to finish.
+.PP
+Here's something Larry suggested: if a \f(CW\*(C`U\*(C'\fR is the first active format
+during a \f(CW\*(C`pack\*(C'\fR, (for example, \f(CW\*(C`pack "U3C8", @stuff\*(C'\fR) then the
+resulting string should be treated as UTF\-8 encoded.
+.PP
+If you are working with a git clone of the Perl repository, you will
+want to create a branch for your changes. This will make creating a
+proper patch much simpler. See the perlgit for details on how to do
+this.
+.SS "Writing the patch"
+.IX Subsection "Writing the patch"
+How do we prepare to fix this up? First we locate the code in question
+\&\- the \f(CW\*(C`pack\*(C'\fR happens at runtime, so it's going to be in one of the
+\&\fIpp\fR files. Sure enough, \f(CW\*(C`pp_pack\*(C'\fR is in \fIpp.c\fR. Since we're going
+to be altering this file, let's copy it to \fIpp.c~\fR.
+.PP
+[Well, it was in \fIpp.c\fR when this tutorial was written. It has now
+been split off with \f(CW\*(C`pp_unpack\*(C'\fR to its own file, \fIpp_pack.c\fR]
+.PP
+Now let's look over \f(CW\*(C`pp_pack\*(C'\fR: we take a pattern into \f(CW\*(C`pat\*(C'\fR, and then
+loop over the pattern, taking each format character in turn into
+\&\f(CW\*(C`datum_type\*(C'\fR. Then for each possible format character, we swallow up
+the other arguments in the pattern (a field width, an asterisk, and so
+on) and convert the next chunk input into the specified format, adding
+it onto the output SV \f(CW\*(C`cat\*(C'\fR.
+.PP
+How do we know if the \f(CW\*(C`U\*(C'\fR is the first format in the \f(CW\*(C`pat\*(C'\fR? Well, if
+we have a pointer to the start of \f(CW\*(C`pat\*(C'\fR then, if we see a \f(CW\*(C`U\*(C'\fR we can
+test whether we're still at the start of the string. So, here's where
+\&\f(CW\*(C`pat\*(C'\fR is set up:
+.PP
+.Vb 6
+\&    STRLEN fromlen;
+\&    char *pat = SvPVx(*++MARK, fromlen);
+\&    char *patend = pat + fromlen;
+\&    I32 len;
+\&    I32 datumtype;
+\&    SV *fromstr;
+.Ve
+.PP
+We'll have another string pointer in there:
+.PP
+.Vb 7
+\&    STRLEN fromlen;
+\&    char *pat = SvPVx(*++MARK, fromlen);
+\&    char *patend = pat + fromlen;
+\& +  char *patcopy;
+\&    I32 len;
+\&    I32 datumtype;
+\&    SV *fromstr;
+.Ve
+.PP
+And just before we start the loop, we'll set \f(CW\*(C`patcopy\*(C'\fR to be the start
+of \f(CW\*(C`pat\*(C'\fR:
+.PP
+.Vb 5
+\&    items = SP \- MARK;
+\&    MARK++;
+\&    SvPVCLEAR(cat);
+\& +  patcopy = pat;
+\&    while (pat < patend) {
+.Ve
+.PP
+Now if we see a \f(CW\*(C`U\*(C'\fR which was at the start of the string, we turn on
+the \f(CW\*(C`UTF8\*(C'\fR flag for the output SV, \f(CW\*(C`cat\*(C'\fR:
+.PP
+.Vb 5
+\& +  if (datumtype == \*(AqU\*(Aq && pat==patcopy+1)
+\& +      SvUTF8_on(cat);
+\&    if (datumtype == \*(Aq#\*(Aq) {
+\&        while (pat < patend && *pat != \*(Aq\en\*(Aq)
+\&            pat++;
+.Ve
+.PP
+Remember that it has to be \f(CW\*(C`patcopy+1\*(C'\fR because the first character of
+the string is the \f(CW\*(C`U\*(C'\fR which has been swallowed into \f(CW\*(C`datumtype!\*(C'\fR
+.PP
+Oops, we forgot one thing: what if there are spaces at the start of the
+pattern? \f(CW\*(C`pack("  U*", @stuff)\*(C'\fR will have \f(CW\*(C`U\*(C'\fR as the first active
+character, even though it's not the first thing in the pattern. In this
+case, we have to advance \f(CW\*(C`patcopy\*(C'\fR along with \f(CW\*(C`pat\*(C'\fR when we see
+spaces:
+.PP
+.Vb 2
+\&    if (isSPACE(datumtype))
+\&        continue;
+.Ve
+.PP
+needs to become
+.PP
+.Vb 4
+\&    if (isSPACE(datumtype)) {
+\&        patcopy++;
+\&        continue;
+\&    }
+.Ve
+.PP
+OK. That's the C part done. Now we must do two additional things before
+this patch is ready to go: we've changed the behaviour of Perl, and so
+we must document that change. We must also provide some more regression
+tests to make sure our patch works and doesn't create a bug somewhere
+else along the line.
+.SS "Testing the patch"
+.IX Subsection "Testing the patch"
+The regression tests for each operator live in \fIt/op/\fR, and so we make
+a copy of \fIt/op/pack.t\fR to \fIt/op/pack.t~\fR. Now we can add our tests
+to the end. First, we'll test that the \f(CW\*(C`U\*(C'\fR does indeed create Unicode
+strings.
+.PP
+t/op/pack.t has a sensible \fBok()\fR function, but if it didn't we could use
+the one from t/test.pl.
+.PP
+.Vb 2
+\& require \*(Aq./test.pl\*(Aq;
+\& plan( tests => 159 );
+.Ve
+.PP
+so instead of this:
+.PP
+.Vb 3
+\& print \*(Aqnot \*(Aq unless "1.20.300.4000" eq sprintf "%vd",
+\&                                               pack("U*",1,20,300,4000);
+\& print "ok $test\en"; $test++;
+.Ve
+.PP
+we can write the more sensible (see Test::More for a full
+explanation of \fBis()\fR and other testing functions).
+.PP
+.Vb 2
+\& is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000),
+\&                                       "U* produces Unicode" );
+.Ve
+.PP
+Now we'll test that we got that space-at-the-beginning business right:
+.PP
+.Vb 2
+\& is( "1.20.300.4000", sprintf "%vd", pack("  U*",1,20,300,4000),
+\&                                     "  with spaces at the beginning" );
+.Ve
+.PP
+And finally we'll test that we don't make Unicode strings if \f(CW\*(C`U\*(C'\fR is
+\&\fBnot\fR the first active format:
+.PP
+.Vb 2
+\& isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000),
+\&                                       "U* not first isn\*(Aqt Unicode" );
+.Ve
+.PP
+Mustn't forget to change the number of tests which appears at the top,
+or else the automated tester will get confused. This will either look
+like this:
+.PP
+.Vb 1
+\& print "1..156\en";
+.Ve
+.PP
+or this:
+.PP
+.Vb 1
+\& plan( tests => 156 );
+.Ve
+.PP
+We now compile up Perl, and run it through the test suite. Our new
+tests pass, hooray!
+.SS "Documenting the patch"
+.IX Subsection "Documenting the patch"
+Finally, the documentation. The job is never done until the paperwork
+is over, so let's describe the change we've just made. The relevant
+place is \fIpod/perlfunc.pod\fR; again, we make a copy, and then we'll
+insert this text in the description of \f(CW\*(C`pack\*(C'\fR:
+.PP
+.Vb 1
+\& =item *
+\&
+\& If the pattern begins with a C<U>, the resulting string will be treated
+\& as UTF\-8\-encoded Unicode. You can force UTF\-8 encoding on in a string
+\& with an initial C<U0>, and the bytes that follow will be interpreted as
+\& Unicode characters. If you don\*(Aqt want this to happen, you can begin
+\& your pattern with C<C0> (or anything else) to force Perl not to UTF\-8
+\& encode your string, and then follow this with a C<U*> somewhere in your
+\& pattern.
+.Ve
+.SS Submit
+.IX Subsection "Submit"
+See perlhack for details on how to submit this patch.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This document was originally written by Nathan Torkington, and is
+maintained by the perl5\-porters mailing list.
diff --git a/upstream/mageia-cauldron/man1/perlhaiku.1 b/upstream/mageia-cauldron/man1/perlhaiku.1
new file mode 100644
index 00000000..8562acd3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhaiku.1
@@ -0,0 +1,109 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHAIKU 1"
+.TH PERLHAIKU 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhaiku \- Perl version 5.10+ on Haiku
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This file contains instructions how to build Perl for Haiku and lists
+known problems.
+.SH "BUILD AND INSTALL"
+.IX Header "BUILD AND INSTALL"
+The build procedure is completely standard:
+.PP
+.Vb 3
+\&  ./Configure \-de
+\&  make
+\&  make install
+.Ve
+.PP
+Make perl executable and create a symlink for libperl:
+.PP
+.Vb 2
+\&  chmod a+x /boot/common/bin/perl
+\&  cd /boot/common/lib; ln \-s perl5/5.38.2/BePC\-haiku/CORE/libperl.so .
+.Ve
+.PP
+Replace \f(CW5.38.2\fR with your respective version of Perl.
+.SH "KNOWN PROBLEMS"
+.IX Header "KNOWN PROBLEMS"
+The following problems are encountered with Haiku revision 28311:
+.IP \(bu 4
+Perl cannot be compiled with threading support ATM.
+.IP \(bu 4
+The \fIcpan/Socket/t/socketpair.t\fR test fails. More precisely: the subtests
+using datagram sockets fail. Unix datagram sockets aren't implemented in
+Haiku yet.
+.IP \(bu 4
+A subtest of the \fIcpan/Sys\-Syslog/t/syslog.t\fR test fails. This is due to Haiku
+not implementing \fI/dev/log\fR support yet.
+.IP \(bu 4
+The tests \fIdist/Net\-Ping/t/450_service.t\fR and \fIdist/Net\-Ping/t/510_ping_udp.t\fR
+fail. This is due to bugs in Haiku's network stack implementation.
+.SH CONTACT
+.IX Header "CONTACT"
+For Haiku specific problems contact the HaikuPorts developers:
+<http://ports.haiku\-files.org/>
+.PP
+The initial Haiku port was done by Ingo Weinhold <ingo_weinhold@gmx.de>.
+.PP
+Last update: 2008\-10\-29
diff --git a/upstream/mageia-cauldron/man1/perlhist.1 b/upstream/mageia-cauldron/man1/perlhist.1
new file mode 100644
index 00000000..4725f116
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhist.1
@@ -0,0 +1,1414 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHIST 1"
+.TH PERLHIST 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhist \- the Perl history records
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document aims to record the Perl source code releases.
+.SH INTRODUCTION
+.IX Header "INTRODUCTION"
+Perl history in brief, by Larry Wall:
+.PP
+.Vb 9
+\&   Perl 0 introduced Perl to my officemates.
+\&   Perl 1 introduced Perl to the world, and changed /\e(...\e|...\e)/ to
+\&       /(...|...)/.  \e(Dan Faigin still hasn\*(Aqt forgiven me. :\-\e)
+\&   Perl 2 introduced Henry Spencer\*(Aqs regular expression package.
+\&   Perl 3 introduced the ability to handle binary data (embedded nulls).
+\&   Perl 4 introduced the first Camel book.  Really.  We mostly just
+\&       switched version numbers so the book could refer to 4.000.
+\&   Perl 5 introduced everything else, including the ability to
+\&       introduce everything else.
+.Ve
+.SH "THE KEEPERS OF THE PUMPKIN"
+.IX Header "THE KEEPERS OF THE PUMPKIN"
+Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick
+Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie, Gurusamy
+Sarathy, Graham Barr, Jarkko Hietaniemi, Hugo van der Sanden,
+Michael Schwern, Rafael Garcia-Suarez, Nicholas Clark, Richard Clamp,
+Leon Brocard, Dave Mitchell, Jesse Vincent, Ricardo Signes, Steve Hay,
+Matt S Trout, David Golden, Florian Ragwitz, Tatsuhiko Miyagawa,
+Chris \f(CW\*(C`BinGOs\*(C'\fR Williams, Zefram, Ævar Arnfjörð Bjarmason, Stevan
+Little, Dave Rolsky, Max Maischein, Abigail, Jesse Luehrs, Tony Cook,
+Dominic Hargreaves, Aaron Crane, Aristotle Pagaltzis, Matthew Horsfall,
+Peter Martini, Sawyer X, Chad 'Exodist' Granum, Renee Bäcker, Eric Herman,
+John SJ Anderson, Karen Etheridge, Zak B. Elep, Tom Hukins, Richard Leach,
+Neil Bowers, Yves Orton, Paul Evans, and Graham Knop.
+.SS PUMPKIN?
+.IX Subsection "PUMPKIN?"
+[from Porting/pumpkin.pod in the Perl source code distribution]
+.PP
+Chip Salzenberg gets credit for that, with a nod to his cow orker,
+David Croy.  We had passed around various names (baton, token, hot
+potato) but none caught on.  Then, Chip asked:
+.PP
+[begin quote]
+.PP
+.Vb 1
+\&   Who has the patch pumpkin?
+.Ve
+.PP
+To explain:  David Croy once told me that at a previous job,
+there was one tape drive and multiple systems that used it for backups.
+But instead of some high-tech exclusion software, they used a low-tech
+method to prevent multiple simultaneous backups: a stuffed pumpkin.
+No one was allowed to make backups unless they had the "backup pumpkin".
+.PP
+[end quote]
+.PP
+The name has stuck.  The holder of the pumpkin is sometimes called
+the pumpking (keeping the source afloat?) or the pumpkineer (pulling
+the strings?).
+.SH "THE RECORDS"
+.IX Header "THE RECORDS"
+.Vb 6
+\& Pump\-  Release         Date            Notes
+\& kin                                    (by no means
+\& Holder                                  comprehensive,
+\&                                         see Changes*
+\&                                         for details)
+\& ======================================================================
+\&
+\& Larry   0              Classified.     Don\*(Aqt ask.
+\&
+\& Larry   1.000          1987\-Dec\-18
+\&
+\&          1.001..10     1988\-Jan\-30
+\&          1.011..14     1988\-Feb\-02
+\& Schwern  1.0.15        2002\-Dec\-18     Modernization
+\& Richard  1.0_16        2003\-Dec\-18
+\&
+\& Larry   2.000          1988\-Jun\-05
+\&
+\&          2.001         1988\-Jun\-28
+\&
+\& Larry   3.000          1989\-Oct\-18
+\&
+\&          3.001         1989\-Oct\-26
+\&          3.002..4      1989\-Nov\-11
+\&          3.005         1989\-Nov\-18
+\&          3.006..8      1989\-Dec\-22
+\&          3.009..13     1990\-Mar\-02
+\&          3.014         1990\-Mar\-13
+\&          3.015         1990\-Mar\-14
+\&          3.016..18     1990\-Mar\-28
+\&          3.019..27     1990\-Aug\-10     User subs.
+\&          3.028         1990\-Aug\-14
+\&          3.029..36     1990\-Oct\-17
+\&          3.037         1990\-Oct\-20
+\&          3.040         1990\-Nov\-10
+\&          3.041         1990\-Nov\-13
+\&          3.042..43     1991\-Jan\-??
+\&          3.044         1991\-Jan\-12
+\&
+\& Larry   4.000          1991\-Mar\-21
+\&
+\&          4.001..3      1991\-Apr\-12
+\&          4.004..9      1991\-Jun\-07
+\&          4.010         1991\-Jun\-10
+\&          4.011..18     1991\-Nov\-05
+\&          4.019         1991\-Nov\-11     Stable.
+\&          4.020..33     1992\-Jun\-08
+\&          4.034         1992\-Jun\-11
+\&          4.035         1992\-Jun\-23
+\& Larry    4.036         1993\-Feb\-05     Very stable.
+\&
+\&          5.000alpha1   1993\-Jul\-31
+\&          5.000alpha2   1993\-Aug\-16
+\&          5.000alpha3   1993\-Oct\-10
+\&          5.000alpha4   1993\-???\-??
+\&          5.000alpha5   1993\-???\-??
+\&          5.000alpha6   1994\-Mar\-18
+\&          5.000alpha7   1994\-Mar\-25
+\& Andy     5.000alpha8   1994\-Apr\-04
+\& Larry    5.000alpha9   1994\-May\-05     ext appears.
+\&          5.000alpha10  1994\-Jun\-11
+\&          5.000alpha11  1994\-Jul\-01
+\& Andy     5.000a11a     1994\-Jul\-07     To fit 14.
+\&          5.000a11b     1994\-Jul\-14
+\&          5.000a11c     1994\-Jul\-19
+\&          5.000a11d     1994\-Jul\-22
+\& Larry    5.000alpha12  1994\-Aug\-04
+\& Andy     5.000a12a     1994\-Aug\-08
+\&          5.000a12b     1994\-Aug\-15
+\&          5.000a12c     1994\-Aug\-22
+\&          5.000a12d     1994\-Aug\-22
+\&          5.000a12e     1994\-Aug\-22
+\&          5.000a12f     1994\-Aug\-24
+\&          5.000a12g     1994\-Aug\-24
+\&          5.000a12h     1994\-Aug\-24
+\& Larry    5.000beta1    1994\-Aug\-30
+\& Andy     5.000b1a      1994\-Sep\-06
+\& Larry    5.000beta2    1994\-Sep\-14     Core slushified.
+\& Andy     5.000b2a      1994\-Sep\-14
+\&          5.000b2b      1994\-Sep\-17
+\&          5.000b2c      1994\-Sep\-17
+\& Larry    5.000beta3    1994\-Sep\-??
+\& Andy     5.000b3a      1994\-Sep\-18
+\&          5.000b3b      1994\-Sep\-22
+\&          5.000b3c      1994\-Sep\-23
+\&          5.000b3d      1994\-Sep\-27
+\&          5.000b3e      1994\-Sep\-28
+\&          5.000b3f      1994\-Sep\-30
+\&          5.000b3g      1994\-Oct\-04
+\& Andy     5.000b3h      1994\-Oct\-07
+\& Larry?   5.000gamma    1994\-Oct\-13?
+\&
+\& Larry   5.000          1994\-Oct\-17
+\&
+\& Andy     5.000a        1994\-Dec\-19
+\&          5.000b        1995\-Jan\-18
+\&          5.000c        1995\-Jan\-18
+\&          5.000d        1995\-Jan\-18
+\&          5.000e        1995\-Jan\-18
+\&          5.000f        1995\-Jan\-18
+\&          5.000g        1995\-Jan\-18
+\&          5.000h        1995\-Jan\-18
+\&          5.000i        1995\-Jan\-26
+\&          5.000j        1995\-Feb\-07
+\&          5.000k        1995\-Feb\-11
+\&          5.000l        1995\-Feb\-21
+\&          5.000m        1995\-Feb\-28
+\&          5.000n        1995\-Mar\-07
+\&          5.000o        1995\-Mar\-13?
+\&
+\& Larry   5.001          1995\-Mar\-13
+\&
+\& Andy     5.001a        1995\-Mar\-15
+\&          5.001b        1995\-Mar\-31
+\&          5.001c        1995\-Apr\-07
+\&          5.001d        1995\-Apr\-14
+\&          5.001e        1995\-Apr\-18     Stable.
+\&          5.001f        1995\-May\-31
+\&          5.001g        1995\-May\-25
+\&          5.001h        1995\-May\-25
+\&          5.001i        1995\-May\-30
+\&          5.001j        1995\-Jun\-05
+\&          5.001k        1995\-Jun\-06
+\&          5.001l        1995\-Jun\-06     Stable.
+\&          5.001m        1995\-Jul\-02     Very stable.
+\&          5.001n        1995\-Oct\-31     Very unstable.
+\&          5.002beta1    1995\-Nov\-21
+\&          5.002b1a      1995\-Dec\-04
+\&          5.002b1b      1995\-Dec\-04
+\&          5.002b1c      1995\-Dec\-04
+\&          5.002b1d      1995\-Dec\-04
+\&          5.002b1e      1995\-Dec\-08
+\&          5.002b1f      1995\-Dec\-08
+\& Tom      5.002b1g      1995\-Dec\-21     Doc release.
+\& Andy     5.002b1h      1996\-Jan\-05
+\&          5.002b2       1996\-Jan\-14
+\& Larry    5.002b3       1996\-Feb\-02
+\& Andy     5.002gamma    1996\-Feb\-11
+\& Larry    5.002delta    1996\-Feb\-27
+\&
+\& Larry   5.002          1996\-Feb\-29     Prototypes.
+\&
+\& Charles  5.002_01      1996\-Mar\-25
+\&
+\&         5.003          1996\-Jun\-25     Security release.
+\&
+\&          5.003_01      1996\-Jul\-31
+\& Nick     5.003_02      1996\-Aug\-10
+\& Andy     5.003_03      1996\-Aug\-28
+\&          5.003_04      1996\-Sep\-02
+\&          5.003_05      1996\-Sep\-12
+\&          5.003_06      1996\-Oct\-07
+\&          5.003_07      1996\-Oct\-10
+\& Chip     5.003_08      1996\-Nov\-19
+\&          5.003_09      1996\-Nov\-26
+\&          5.003_10      1996\-Nov\-29
+\&          5.003_11      1996\-Dec\-06
+\&          5.003_12      1996\-Dec\-19
+\&          5.003_13      1996\-Dec\-20
+\&          5.003_14      1996\-Dec\-23
+\&          5.003_15      1996\-Dec\-23
+\&          5.003_16      1996\-Dec\-24
+\&          5.003_17      1996\-Dec\-27
+\&          5.003_18      1996\-Dec\-31
+\&          5.003_19      1997\-Jan\-04
+\&          5.003_20      1997\-Jan\-07
+\&          5.003_21      1997\-Jan\-15
+\&          5.003_22      1997\-Jan\-16
+\&          5.003_23      1997\-Jan\-25
+\&          5.003_24      1997\-Jan\-29
+\&          5.003_25      1997\-Feb\-04
+\&          5.003_26      1997\-Feb\-10
+\&          5.003_27      1997\-Feb\-18
+\&          5.003_28      1997\-Feb\-21
+\&          5.003_90      1997\-Feb\-25     Ramping up to the 5.004 release.
+\&          5.003_91      1997\-Mar\-01
+\&          5.003_92      1997\-Mar\-06
+\&          5.003_93      1997\-Mar\-10
+\&          5.003_94      1997\-Mar\-22
+\&          5.003_95      1997\-Mar\-25
+\&          5.003_96      1997\-Apr\-01
+\&          5.003_97      1997\-Apr\-03     Fairly widely used.
+\&          5.003_97a     1997\-Apr\-05
+\&          5.003_97b     1997\-Apr\-08
+\&          5.003_97c     1997\-Apr\-10
+\&          5.003_97d     1997\-Apr\-13
+\&          5.003_97e     1997\-Apr\-15
+\&          5.003_97f     1997\-Apr\-17
+\&          5.003_97g     1997\-Apr\-18
+\&          5.003_97h     1997\-Apr\-24
+\&          5.003_97i     1997\-Apr\-25
+\&          5.003_97j     1997\-Apr\-28
+\&          5.003_98      1997\-Apr\-30
+\&          5.003_99      1997\-May\-01
+\&          5.003_99a     1997\-May\-09
+\&          p54rc1        1997\-May\-12     Release Candidates.
+\&          p54rc2        1997\-May\-14
+\&
+\& Chip    5.004          1997\-May\-15     A major maintenance release.
+\&
+\& Tim      5.004_01\-t1   1997\-???\-??     The 5.004 maintenance track.
+\&          5.004_01\-t2   1997\-Jun\-11     aka perl5.004m1t2
+\&          5.004_01      1997\-Jun\-13
+\&          5.004_01_01   1997\-Jul\-29     aka perl5.004m2t1
+\&          5.004_01_02   1997\-Aug\-01     aka perl5.004m2t2
+\&          5.004_01_03   1997\-Aug\-05     aka perl5.004m2t3
+\&          5.004_02      1997\-Aug\-07
+\&          5.004_02_01   1997\-Aug\-12     aka perl5.004m3t1
+\&          5.004_03\-t2   1997\-Aug\-13     aka perl5.004m3t2
+\&          5.004_03      1997\-Sep\-05
+\&          5.004_04\-t1   1997\-Sep\-19     aka perl5.004m4t1
+\&          5.004_04\-t2   1997\-Sep\-23     aka perl5.004m4t2
+\&          5.004_04\-t3   1997\-Oct\-10     aka perl5.004m4t3
+\&          5.004_04\-t4   1997\-Oct\-14     aka perl5.004m4t4
+\&          5.004_04      1997\-Oct\-15
+\&          5.004_04\-m1   1998\-Mar\-04     (5.004m5t1) Maint. trials for
+\&                                        5.004_05.
+\&          5.004_04\-m2   1998\-May\-01
+\&          5.004_04\-m3   1998\-May\-15
+\&          5.004_04\-m4   1998\-May\-19
+\&          5.004_05\-MT5  1998\-Jul\-21
+\&          5.004_05\-MT6  1998\-Oct\-09
+\&          5.004_05\-MT7  1998\-Nov\-22
+\&          5.004_05\-MT8  1998\-Dec\-03
+\& Chip     5.004_05\-MT9  1999\-Apr\-26
+\&          5.004_05      1999\-Apr\-29
+\&
+\& Malcolm  5.004_50      1997\-Sep\-09     The 5.005 development track.
+\&          5.004_51      1997\-Oct\-02
+\&          5.004_52      1997\-Oct\-15
+\&          5.004_53      1997\-Oct\-16
+\&          5.004_54      1997\-Nov\-14
+\&          5.004_55      1997\-Nov\-25
+\&          5.004_56      1997\-Dec\-18
+\&          5.004_57      1998\-Feb\-03
+\&          5.004_58      1998\-Feb\-06
+\&          5.004_59      1998\-Feb\-13
+\&          5.004_60      1998\-Feb\-20
+\&          5.004_61      1998\-Feb\-27
+\&          5.004_62      1998\-Mar\-06
+\&          5.004_63      1998\-Mar\-17
+\&          5.004_64      1998\-Apr\-03
+\&          5.004_65      1998\-May\-15
+\&          5.004_66      1998\-May\-29
+\& Sarathy  5.004_67      1998\-Jun\-15
+\&          5.004_68      1998\-Jun\-23
+\&          5.004_69      1998\-Jun\-29
+\&          5.004_70      1998\-Jul\-06
+\&          5.004_71      1998\-Jul\-09
+\&          5.004_72      1998\-Jul\-12
+\&          5.004_73      1998\-Jul\-13
+\&          5.004_74      1998\-Jul\-14     5.005 beta candidate.
+\&          5.004_75      1998\-Jul\-15     5.005 beta1.
+\&          5.004_76      1998\-Jul\-21     5.005 beta2.
+\&
+\& Sarathy  5.005         1998\-Jul\-22     Oneperl.
+\&
+\& Sarathy  5.005_01      1998\-Jul\-27     The 5.005 maintenance track.
+\&          5.005_02\-T1   1998\-Aug\-02
+\&          5.005_02\-T2   1998\-Aug\-05
+\&          5.005_02      1998\-Aug\-08
+\& Graham   5.005_03\-MT1  1998\-Nov\-30
+\&          5.005_03\-MT2  1999\-Jan\-04
+\&          5.005_03\-MT3  1999\-Jan\-17
+\&          5.005_03\-MT4  1999\-Jan\-26
+\&          5.005_03\-MT5  1999\-Jan\-28
+\&          5.005_03\-MT6  1999\-Mar\-05
+\&          5.005_03      1999\-Mar\-28
+\& Leon     5.005_04\-RC1  2004\-Feb\-05
+\&          5.005_04\-RC2  2004\-Feb\-18
+\&          5.005_04      2004\-Feb\-23
+\&          5.005_05\-RC1  2009\-Feb\-16
+\&
+\& Sarathy  5.005_50      1998\-Jul\-26     The 5.6 development track.
+\&          5.005_51      1998\-Aug\-10
+\&          5.005_52      1998\-Sep\-25
+\&          5.005_53      1998\-Oct\-31
+\&          5.005_54      1998\-Nov\-30
+\&          5.005_55      1999\-Feb\-16
+\&          5.005_56      1999\-Mar\-01
+\&          5.005_57      1999\-May\-25
+\&          5.005_58      1999\-Jul\-27
+\&          5.005_59      1999\-Aug\-02
+\&          5.005_60      1999\-Aug\-02
+\&          5.005_61      1999\-Aug\-20
+\&          5.005_62      1999\-Oct\-15
+\&          5.005_63      1999\-Dec\-09
+\&          5.5.640       2000\-Feb\-02
+\&          5.5.650       2000\-Feb\-08     beta1
+\&          5.5.660       2000\-Feb\-22     beta2
+\&          5.5.670       2000\-Feb\-29     beta3
+\&          5.6.0\-RC1     2000\-Mar\-09     Release candidate 1.
+\&          5.6.0\-RC2     2000\-Mar\-14     Release candidate 2.
+\&          5.6.0\-RC3     2000\-Mar\-21     Release candidate 3.
+\&
+\& Sarathy  5.6.0         2000\-Mar\-22
+\&
+\& Sarathy  5.6.1\-TRIAL1  2000\-Dec\-18     The 5.6 maintenance track.
+\&          5.6.1\-TRIAL2  2001\-Jan\-31
+\&          5.6.1\-TRIAL3  2001\-Mar\-19
+\&          5.6.1\-foolish 2001\-Apr\-01     The "fools\-gold" release.
+\&          5.6.1         2001\-Apr\-08
+\& Rafael   5.6.2\-RC1     2003\-Nov\-08
+\&          5.6.2         2003\-Nov\-15     Fix new build issues
+\&
+\& Jarkko   5.7.0         2000\-Sep\-02     The 5.7 track: Development.
+\&          5.7.1         2001\-Apr\-09
+\&          5.7.2         2001\-Jul\-13     Virtual release candidate 0.
+\&          5.7.3         2002\-Mar\-05
+\&          5.8.0\-RC1     2002\-Jun\-01
+\&          5.8.0\-RC2     2002\-Jun\-21
+\&          5.8.0\-RC3     2002\-Jul\-13
+\&
+\& Jarkko   5.8.0         2002\-Jul\-18
+\&
+\& Jarkko   5.8.1\-RC1     2003\-Jul\-10     The 5.8 maintenance track
+\&          5.8.1\-RC2     2003\-Jul\-11
+\&          5.8.1\-RC3     2003\-Jul\-30
+\&          5.8.1\-RC4     2003\-Aug\-01
+\&          5.8.1\-RC5     2003\-Sep\-22
+\&          5.8.1         2003\-Sep\-25
+\& Nicholas 5.8.2\-RC1     2003\-Oct\-27
+\&          5.8.2\-RC2     2003\-Nov\-03
+\&          5.8.2         2003\-Nov\-05
+\&          5.8.3\-RC1     2004\-Jan\-07
+\&          5.8.3         2004\-Jan\-14
+\&          5.8.4\-RC1     2004\-Apr\-05
+\&          5.8.4\-RC2     2004\-Apr\-15
+\&          5.8.4         2004\-Apr\-21
+\&          5.8.5\-RC1     2004\-Jul\-06
+\&          5.8.5\-RC2     2004\-Jul\-08
+\&          5.8.5         2004\-Jul\-19
+\&          5.8.6\-RC1     2004\-Nov\-11
+\&          5.8.6         2004\-Nov\-27
+\&          5.8.7\-RC1     2005\-May\-18
+\&          5.8.7         2005\-May\-30
+\&          5.8.8\-RC1     2006\-Jan\-20
+\&          5.8.8         2006\-Jan\-31
+\&          5.8.9\-RC1     2008\-Nov\-10
+\&          5.8.9\-RC2     2008\-Dec\-06
+\&          5.8.9         2008\-Dec\-14
+\&
+\& Hugo     5.9.0         2003\-Oct\-27     The 5.9 development track
+\& Rafael   5.9.1         2004\-Mar\-16
+\&          5.9.2         2005\-Apr\-01
+\&          5.9.3         2006\-Jan\-28
+\&          5.9.4         2006\-Aug\-15
+\&          5.9.5         2007\-Jul\-07
+\&          5.10.0\-RC1    2007\-Nov\-17
+\&          5.10.0\-RC2    2007\-Nov\-25
+\&
+\& Rafael   5.10.0        2007\-Dec\-18
+\&
+\& David M  5.10.1\-RC1    2009\-Aug\-06     The 5.10 maintenance track
+\&          5.10.1\-RC2    2009\-Aug\-18
+\&          5.10.1        2009\-Aug\-22
+\&
+\& Jesse    5.11.0        2009\-Oct\-02     The 5.11 development track
+\&          5.11.1        2009\-Oct\-20
+\& Leon     5.11.2        2009\-Nov\-20
+\& Jesse    5.11.3        2009\-Dec\-20
+\& Ricardo  5.11.4        2010\-Jan\-20
+\& Steve    5.11.5        2010\-Feb\-20
+\& Jesse    5.12.0\-RC0    2010\-Mar\-21
+\&          5.12.0\-RC1    2010\-Mar\-29
+\&          5.12.0\-RC2    2010\-Apr\-01
+\&          5.12.0\-RC3    2010\-Apr\-02
+\&          5.12.0\-RC4    2010\-Apr\-06
+\&          5.12.0\-RC5    2010\-Apr\-09
+\&
+\& Jesse    5.12.0        2010\-Apr\-12
+\&
+\& Jesse    5.12.1\-RC2    2010\-May\-13     The 5.12 maintenance track
+\&          5.12.1\-RC1    2010\-May\-09
+\&          5.12.1        2010\-May\-16
+\&          5.12.2\-RC2    2010\-Aug\-31
+\&          5.12.2        2010\-Sep\-06
+\& Ricardo  5.12.3\-RC1    2011\-Jan\-09
+\& Ricardo  5.12.3\-RC2    2011\-Jan\-14
+\& Ricardo  5.12.3\-RC3    2011\-Jan\-17
+\& Ricardo  5.12.3        2011\-Jan\-21
+\& Leon     5.12.4\-RC1    2011\-Jun\-08
+\& Leon     5.12.4        2011\-Jun\-20
+\& Dominic  5.12.5        2012\-Nov\-10
+\&
+\& Leon     5.13.0        2010\-Apr\-20     The 5.13 development track
+\& Ricardo  5.13.1        2010\-May\-20
+\& Matt     5.13.2        2010\-Jun\-22
+\& David G  5.13.3        2010\-Jul\-20
+\& Florian  5.13.4        2010\-Aug\-20
+\& Steve    5.13.5        2010\-Sep\-19
+\& Miyagawa 5.13.6        2010\-Oct\-20
+\& BinGOs   5.13.7        2010\-Nov\-20
+\& Zefram   5.13.8        2010\-Dec\-20
+\& Jesse    5.13.9        2011\-Jan\-20
+\& Ævar     5.13.10       2011\-Feb\-20
+\& Florian  5.13.11       2011\-Mar\-20
+\& Jesse    5.14.0RC1     2011\-Apr\-20
+\& Jesse    5.14.0RC2     2011\-May\-04
+\& Jesse    5.14.0RC3     2011\-May\-11
+\&
+\& Jesse    5.14.0        2011\-May\-14     The 5.14 maintenance track
+\& Jesse    5.14.1        2011\-Jun\-16
+\& Florian  5.14.2\-RC1    2011\-Sep\-19
+\&          5.14.2        2011\-Sep\-26
+\& Dominic  5.14.3        2012\-Oct\-12
+\& David M  5.14.4\-RC1    2013\-Mar\-05
+\& David M  5.14.4\-RC2    2013\-Mar\-07
+\& David M  5.14.4        2013\-Mar\-10
+\&
+\& David G  5.15.0        2011\-Jun\-20     The 5.15 development track
+\& Zefram   5.15.1        2011\-Jul\-20
+\& Ricardo  5.15.2        2011\-Aug\-20
+\& Stevan   5.15.3        2011\-Sep\-20
+\& Florian  5.15.4        2011\-Oct\-20
+\& Steve    5.15.5        2011\-Nov\-20
+\& Dave R   5.15.6        2011\-Dec\-20
+\& BinGOs   5.15.7        2012\-Jan\-20
+\& Max M    5.15.8        2012\-Feb\-20
+\& Abigail  5.15.9        2012\-Mar\-20
+\& Ricardo  5.16.0\-RC0    2012\-May\-10
+\& Ricardo  5.16.0\-RC1    2012\-May\-14
+\& Ricardo  5.16.0\-RC2    2012\-May\-15
+\&
+\& Ricardo  5.16.0        2012\-May\-20     The 5.16 maintenance track
+\& Ricardo  5.16.1        2012\-Aug\-08
+\& Ricardo  5.16.2        2012\-Nov\-01
+\& Ricardo  5.16.3\-RC1    2013\-Mar\-06
+\& Ricardo  5.16.3        2013\-Mar\-11
+\&
+\& Zefram   5.17.0        2012\-May\-26     The 5.17 development track
+\& Jesse L  5.17.1        2012\-Jun\-20
+\& TonyC    5.17.2        2012\-Jul\-20
+\& Steve    5.17.3        2012\-Aug\-20
+\& Florian  5.17.4        2012\-Sep\-20
+\& Florian  5.17.5        2012\-Oct\-20
+\& Ricardo  5.17.6        2012\-Nov\-20
+\& Dave R   5.17.7        2012\-Dec\-18
+\& Aaron    5.17.8        2013\-Jan\-20
+\& BinGOs   5.17.9        2013\-Feb\-20
+\& Max M    5.17.10       2013\-Mar\-21
+\& Ricardo  5.17.11       2013\-Apr\-20
+\&
+\& Ricardo  5.18.0\-RC1    2013\-May\-11     The 5.18 maintenance track
+\& Ricardo  5.18.0\-RC2    2013\-May\-12
+\& Ricardo  5.18.0\-RC3    2013\-May\-13
+\& Ricardo  5.18.0\-RC4    2013\-May\-15
+\& Ricardo  5.18.0        2013\-May\-18
+\& Ricardo  5.18.1\-RC1    2013\-Aug\-01
+\& Ricardo  5.18.1\-RC2    2013\-Aug\-03
+\& Ricardo  5.18.1\-RC3    2013\-Aug\-08
+\& Ricardo  5.18.1        2013\-Aug\-12
+\& Ricardo  5.18.2        2014\-Jan\-06
+\& Ricardo  5.18.3\-RC1    2014\-Sep\-17
+\& Ricardo  5.18.3\-RC2    2014\-Sep\-27
+\& Ricardo  5.18.3        2014\-Oct\-01
+\& Ricardo  5.18.4        2014\-Oct\-01
+\&
+\& Ricardo   5.19.0       2013\-May\-20     The 5.19 development track
+\& David G   5.19.1       2013\-Jun\-21
+\& Aristotle 5.19.2       2013\-Jul\-22
+\& Steve     5.19.3       2013\-Aug\-20
+\& Steve     5.19.4       2013\-Sep\-20
+\& Steve     5.19.5       2013\-Oct\-20
+\& BinGOs    5.19.6       2013\-Nov\-20
+\& Abigail   5.19.7       2013\-Dec\-20
+\& Ricardo   5.19.8       2014\-Jan\-20
+\& TonyC     5.19.9       2014\-Feb\-20
+\& Aaron     5.19.10      2014\-Mar\-20
+\& Steve     5.19.11      2014\-Apr\-20
+\&
+\& Ricardo   5.20.0\-RC1   2014\-May\-16     The 5.20 maintenance track
+\& Ricardo   5.20.0       2014\-May\-27
+\& Steve     5.20.1\-RC1   2014\-Aug\-25
+\& Steve     5.20.1\-RC2   2014\-Sep\-07
+\& Steve     5.20.1       2014\-Sep\-14
+\& Steve     5.20.2\-RC1   2015\-Jan\-31
+\& Steve     5.20.2       2015\-Feb\-14
+\& Steve     5.20.3\-RC1   2015\-Aug\-22
+\& Steve     5.20.3\-RC2   2015\-Aug\-29
+\& Steve     5.20.3       2015\-Sep\-12
+\&
+\& Ricardo   5.21.0       2014\-May\-27     The 5.21 development track
+\& Matthew H 5.21.1       2014\-Jun\-20
+\& Abigail   5.21.2       2014\-Jul\-20
+\& Peter     5.21.3       2014\-Aug\-20
+\& Steve     5.21.4       2014\-Sep\-20
+\& Abigail   5.21.5       2014\-Oct\-20
+\& BinGOs    5.21.6       2014\-Nov\-20
+\& Max M     5.21.7       2014\-Dec\-20
+\& Matthew H 5.21.8       2015\-Jan\-20
+\& Sawyer X  5.21.9       2015\-Feb\-20
+\& Steve     5.21.10      2015\-Mar\-20
+\& Steve     5.21.11      2015\-Apr\-20
+\&
+\& Ricardo   5.22.0\-RC1   2015\-May\-19     The 5.22 maintenance track
+\& Ricardo   5.22.0\-RC2   2015\-May\-21
+\& Ricardo   5.22.0       2015\-Jun\-01
+\& Steve     5.22.1\-RC1   2015\-Oct\-31
+\& Steve     5.22.1\-RC2   2015\-Nov\-15
+\& Steve     5.22.1\-RC3   2015\-Dec\-02
+\& Steve     5.22.1\-RC4   2015\-Dec\-08
+\& Steve     5.22.1       2015\-Dec\-13
+\& Steve     5.22.2\-RC1   2016\-Apr\-10
+\& Steve     5.22.2       2016\-Apr\-29
+\& Steve     5.22.3\-RC1   2016\-Jul\-17
+\& Steve     5.22.3\-RC2   2016\-Jul\-25
+\& Steve     5.22.3\-RC3   2016\-Aug\-11
+\& Steve     5.22.3\-RC4   2016\-Oct\-12
+\& Steve     5.22.3\-RC5   2017\-Jan\-02
+\& Steve     5.22.3       2017\-Jan\-14
+\& Steve     5.22.4\-RC1   2017\-Jul\-01
+\& Steve     5.22.4       2017\-Jul\-15
+\&
+\& Ricardo   5.23.0       2015\-Jun\-20     The 5.23 development track
+\& Matthew H 5.23.1       2015\-Jul\-20
+\& Matthew H 5.23.2       2015\-Aug\-20
+\& Peter     5.23.3       2015\-Sep\-20
+\& Steve     5.23.4       2015\-Oct\-20
+\& Abigail   5.23.5       2015\-Nov\-20
+\& David G   5.23.6       2015\-Dec\-21
+\& Stevan    5.23.7       2016\-Jan\-20
+\& Sawyer X  5.23.8       2016\-Feb\-20
+\& Abigail   5.23.9       2016\-Mar\-20
+\&
+\& Ricardo   5.24.0\-RC1   2016\-Apr\-13     The 5.24 maintenance track
+\& Ricardo   5.24.0\-RC2   2016\-Apr\-23
+\& Ricardo   5.24.0\-RC3   2016\-Apr\-26
+\& Ricardo   5.24.0\-RC4   2016\-May\-02
+\& Ricardo   5.24.0\-RC5   2016\-May\-04
+\& Ricardo   5.24.0       2016\-May\-09
+\& Steve     5.24.1\-RC1   2016\-Jul\-17
+\& Steve     5.24.1\-RC2   2016\-Jul\-25
+\& Steve     5.24.1\-RC3   2016\-Aug\-11
+\& Steve     5.24.1\-RC4   2016\-Oct\-12
+\& Steve     5.24.1\-RC5   2017\-Jan\-02
+\& Steve     5.24.1       2017\-Jan\-14
+\& Steve     5.24.2\-RC1   2017\-Jul\-01
+\& Steve     5.24.2       2017\-Jul\-15
+\& Steve     5.24.3\-RC1   2017\-Sep\-10
+\& Steve     5.24.3       2017\-Sep\-22
+\& Steve     5.24.4\-RC1   2018\-Mar\-24
+\& Steve     5.24.4       2018\-Apr\-14
+\&
+\& Ricardo   5.25.0       2016\-May\-09     The 5.25 development track
+\& Sawyer X  5.25.1       2016\-May\-20
+\& Matthew H 5.25.2       2016\-Jun\-20
+\& Steve     5.25.3       2016\-Jul\-20
+\& BinGOs    5.25.4       2016\-Aug\-20
+\& Stevan    5.25.5       2016\-Sep\-20
+\& Aaron     5.25.6       2016\-Oct\-20
+\& Chad      5.25.7       2016\-Nov\-20
+\& Sawyer X  5.25.8       2016\-Dec\-20
+\& Abigail   5.25.9       2017\-Jan\-20
+\& Renee     5.25.10      2017\-Feb\-20
+\& Sawyer X  5.25.11      2017\-Mar\-20
+\& Sawyer X  5.25.12      2017\-Apr\-20
+\&
+\& Sawyer X  5.26.0\-RC1   2017\-May\-11     The 5.26 maintenance track
+\& Sawyer X  5.26.0\-RC2   2017\-May\-23
+\& Sawyer X  5.26.0       2017\-May\-30
+\& Steve     5.26.1\-RC1   2017\-Sep\-10
+\& Steve     5.26.1       2017\-Sep\-22
+\& Steve     5.26.2\-RC1   2018\-Mar\-24
+\& Steve     5.26.2       2018\-Apr\-14
+\& Steve     5.26.3\-RC1   2018\-Nov\-08
+\& Steve     5.26.3       2018\-Nov\-29
+\&
+\& Sawyer X  5.27.0       2017\-May\-31     The 5.27 development track
+\& Eric      5.27.1       2017\-Jun\-20
+\& Aaron     5.27.2       2017\-Jul\-20
+\& Matthew H 5.27.3       2017\-Aug\-21
+\& John      5.27.4       2017\-Sep\-20
+\& Steve     5.27.5       2017\-Oct\-20
+\& Ether     5.27.6       2017\-Nov\-20
+\& BinGOs    5.27.7       2017\-Dec\-20
+\& Abigail   5.27.8       2018\-Jan\-20
+\& Renee     5.27.9       2018\-Feb\-20
+\& Todd      5.27.10      2018\-Mar\-20
+\& Sawyer X  5.27.11      2018\-Apr\-20
+\&
+\& Sawyer X  5.28.0\-RC1   2018\-May\-21     The 5.28 maintenance track
+\& Sawyer X  5.28.0\-RC2   2018\-Jun\-06
+\& Sawyer X  5.28.0\-RC3   2018\-Jun\-18
+\& Sawyer X  5.28.0\-RC4   2018\-Jun\-19
+\& Sawyer X  5.28.0       2018\-Jun\-22
+\& Steve     5.28.1\-RC1   2018\-Nov\-08
+\& Steve     5.28.1       2018\-Nov\-29
+\& Steve     5.28.2\-RC1   2019\-Apr\-05
+\& Steve     5.28.2       2019\-Apr\-19
+\& Steve     5.28.3\-RC1   2020\-May\-18
+\& Steve     5.28.3       2020\-Jun\-01
+\&
+\& Sawyer X  5.29.0       2018\-Jun\-26     The 5.29 development track
+\& Steve     5.29.1       2018\-Jul\-20
+\& BinGOs    5.29.2       2018\-Aug\-20
+\& John      5.29.3       2018\-Sep\-20
+\& Aaron     5.29.4       2018\-Oct\-20
+\& Ether     5.29.5       2018\-Nov\-20
+\& Abigail   5.29.6       2018\-Dec\-18
+\& Abigail   5.29.7       2019\-Jan\-20
+\& Nicolas R 5.29.8       2019\-Feb\-20
+\& Zak Elep  5.29.9       2019\-Mar\-20
+\& Sawyer X  5.29.10      2019\-Apr\-20
+\&
+\& Sawyer X  5.30.0\-RC1   2019\-May\-11     The 5.30 maintenance track
+\& Sawyer X  5.30.0\-RC2   2019\-May\-17
+\& Sawyer X  5.30.0       2019\-May\-22
+\& Steve     5.30.1\-RC1   2019\-Oct\-27
+\& Steve     5.30.1       2019\-Nov\-10
+\& Steve     5.30.2\-RC1   2020\-Feb\-29
+\& Steve     5.30.2       2020\-Mar\-14
+\& Steve     5.30.3\-RC1   2020\-May\-18
+\& Steve     5.30.3       2020\-Jun\-01
+\&
+\& Sawyer X  5.31.0       2019\-May\-24     The 5.31 development track
+\& Ether     5.31.1       2019\-Jun\-20
+\& Steve     5.31.2       2019\-Jul\-20
+\& Tom H     5.31.3       2019\-Aug\-20
+\& Max M     5.31.4       2019\-Sep\-20
+\& Steve     5.31.5       2019\-Oct\-20
+\& BinGOs    5.31.6       2019\-Nov\-20
+\& Nicolas R 5.31.7       2019\-Dec\-20
+\& Matthew H 5.31.8       2020\-Jan\-20
+\& Renee     5.31.9       2020\-Feb\-20
+\& Sawyer X  5.31.10      2020\-Mar\-20
+\& Sawyer X  5.31.11      2020\-Apr\-28
+\&
+\& Sawyer X  5.32.0\-RC0   2020\-May\-30     The 5.32 maintenance track
+\& Sawyer X  5.32.0\-RC1   2020\-Jun\-07
+\& Sawyer X  5.32.0       2020\-Jun\-20
+\& Steve     5.32.1\-RC1   2021\-Jan\-09
+\& Steve     5.32.1       2021\-Jan\-23
+\&
+\& Sawyer X  5.33.0       2020\-Jul\-17     The 5.33 development track
+\& Ether     5.33.1       2020\-Aug\-20
+\& Sawyer X  5.33.2       2020\-Sep\-20
+\& Steve     5.33.3       2020\-Oct\-20
+\& Tom H     5.33.4       2020\-Nov\-20
+\& Max M     5.33.5       2020\-Dec\-20
+\& Richard L 5.33.6       2021\-Jan\-20
+\& Renee     5.33.7       2021\-Feb\-20
+\& Nicolas R 5.33.8       2021\-Mar\-20
+\& Todd R    5.33.9       2021\-Apr\-20
+\&
+\& Sawyer X  5.34.0\-RC1   2021\-May\-04     The 5.34 maintenance track
+\& Sawyer X  5.34.0\-RC2   2021\-May\-15
+\& Sawyer X  5.34.0       2021\-May\-20
+\& Steve     5.34.1\-RC1   2022\-Feb\-27
+\& Steve     5.34.1\-RC2   2022\-Mar\-06
+\& Steve     5.34.1       2022\-Mar\-13
+\& Paul E    5.34.2       2023\-Nov\-25
+\& Paul E    5.34.3       2023\-Nov\-29
+\&
+\& Ricardo   5.35.0       2021\-May\-20     The 5.35 development track
+\& Max       5.35.1       2021\-Jun\-20
+\& Neil B    5.35.2       2021\-Jul\-23
+\& Ether     5.35.3       2021\-Aug\-20
+\& Matthew H 5.35.4       2021\-Sep\-20
+\& Leon T    5.35.5       2021\-Oct\-21
+\& Richard L 5.35.6       2021\-Nov\-20
+\& Neil B    5.35.7       2021\-Dec\-20
+\& Nicolas R 5.35.8       2022\-Jan\-20
+\& Renee     5.35.9       2022\-Feb\-20
+\& Sawyer X  5.35.10      2022\-Mar\-20
+\& Steve     5.35.11      2022\-Apr\-20
+\&
+\& Ricardo   5.36.0\-RC1   2022\-May\-20     The 5.36 maintenance track
+\& Ricardo   5.36.0\-RC2   2022\-May\-20
+\& Ricardo   5.36.0\-RC3   2022\-May\-22
+\& Ricardo   5.36.0       2022\-May\-27
+\& Steve     5.36.1\-RC1   2023\-Apr\-10
+\& Steve     5.36.1\-RC2   2023\-Apr\-11
+\& Steve     5.36.1\-RC3   2023\-Apr\-16
+\& Steve     5.36.1       2023\-Apr\-23
+\& Paul E    5.36.2       2023\-Nov\-25
+\& Paul E    5.36.3       2023\-Nov\-29
+\&
+\& Ricardo   5.37.0       2022\-May\-27     The 5.37 development track
+\& Matthew H 5.37.1       2022\-Jun\-20
+\& Nicolas R 5.37.2       2022\-Jul\-20
+\& Neil B    5.37.3       2022\-Aug\-20
+\& Ether     5.37.4       2022\-Sep\-20
+\& Todd R    5.37.5       2022\-Oct\-20
+\& Max M     5.37.6       2022\-Nov\-20
+\& Richard L 5.37.7       2022\-Dec\-20
+\& Renee     5.37.8       2023\-Jan\-20
+\& Ether     5.37.9       2023\-Feb\-20
+\& Yves      5.37.10      2023\-Mar\-20
+\& Steve     5.37.11      2023\-Apr\-20
+\&
+\& Ricardo   5.38.0\-RC1   2023\-Jun\-15     The 5.38 maintenance track
+\& Ricardo   5.38.0\-RC2   2023\-Jun\-23
+\& Ricardo   5.38.0       2023\-Jul\-02
+\& Paul E    5.38.1       2023\-Nov\-25
+\& Paul E    5.38.2       2023\-Nov\-29
+\&
+\& Ricardo   5.39.0       2023\-Jun\-30     The 5.39 development track
+\& Steve     5.39.1       2023\-Jul\-20
+\& Paul E    5.39.2       2023\-Aug\-20
+\& Matthew H 5.39.3       2023\-Sep\-20
+\& Graham K  5.39.4       2023\-Oct\-25
+\& Ether     5.39.5       2023\-Nov\-20
+.Ve
+.SS "SELECTED RELEASE SIZES"
+.IX Subsection "SELECTED RELEASE SIZES"
+For example the notation "core: 212  29" in the release 1.000 means that
+it had in the core 212 kilobytes, in 29 files.  The "core".."doc" are
+explained below.
+.PP
+.Vb 2
+\& release        core       lib         ext        t         doc
+\& ======================================================================
+\&
+\& 1.000           212  29      \-   \-      \-    \-     38   51     62   3
+\& 1.014           219  29      \-   \-      \-    \-     39   52     68   4
+\& 2.000           309  31      2   3      \-    \-     55   57     92   4
+\& 2.001           312  31      2   3      \-    \-     55   57     94   4
+\& 3.000           508  36     24  11      \-    \-     79   73    156   5
+\& 3.044           645  37     61  20      \-    \-     90   74    190   6
+\& 4.000           635  37     59  20      \-    \-     91   75    198   4
+\& 4.019           680  37     85  29      \-    \-     98   76    199   4
+\& 4.036           709  37     89  30      \-    \-     98   76    208   5
+\& 5.000alpha2     785  50    114  32      \-    \-    112   86    209   5
+\& 5.000alpha3     801  50    117  33      \-    \-    121   87    209   5
+\& 5.000alpha9    1022  56    149  43    116   29    125   90    217   6
+\& 5.000a12h       978  49    140  49    205   46    152   97    228   9
+\& 5.000b3h       1035  53    232  70    216   38    162   94    218  21
+\& 5.000          1038  53    250  76    216   38    154   92    536  62
+\& 5.001m         1071  54    388  82    240   38    159   95    544  29
+\& 5.002          1121  54    661 101    287   43    155   94    847  35
+\& 5.003          1129  54    680 102    291   43    166  100    853  35
+\& 5.003_07       1231  60    748 106    396   53    213  137    976  39
+\& 5.004          1351  60   1230 136    408   51    355  161   1587  55
+\& 5.004_01       1356  60   1258 138    410   51    358  161   1587  55
+\& 5.004_04       1375  60   1294 139    413   51    394  162   1629  55
+\& 5.004_05       1463  60   1435 150    394   50    445  175   1855  59
+\& 5.004_51       1401  61   1260 140    413   53    358  162   1594  56
+\& 5.004_53       1422  62   1295 141    438   70    394  162   1637  56
+\& 5.004_56       1501  66   1301 140    447   74    408  165   1648  57
+\& 5.004_59       1555  72   1317 142    448   74    424  171   1678  58
+\& 5.004_62       1602  77   1327 144    629   92    428  173   1674  58
+\& 5.004_65       1626  77   1358 146    615   92    446  179   1698  60
+\& 5.004_68       1856  74   1382 152    619   92    463  187   1784  60
+\& 5.004_70       1863  75   1456 154    675   92    494  194   1809  60
+\& 5.004_73       1874  76   1467 152    762  102    506  196   1883  61
+\& 5.004_75       1877  76   1467 152    770  103    508  196   1896  62
+\& 5.005          1896  76   1469 152    795  103    509  197   1945  63
+\& 5.005_03       1936  77   1541 153    813  104    551  201   2176  72
+\& 5.005_50       1969  78   1842 301    795  103    514  198   1948  63
+\& 5.005_53       1999  79   1885 303    806  104    602  224   2002  67
+\& 5.005_56       2086  79   1970 307    866  113    672  238   2221  75
+\& 5.6.0          2820  79   2626 364   1096  129    863  280   2840  93
+\& 5.6.1          2946  78   2921 430   1171  132   1024  304   3330 102
+\& 5.6.2          2947  78   3143 451   1247  127   1303  387   3406 102
+\& 5.7.0          2977  80   2801 425   1250  132    975  307   3206 100
+\& 5.7.1          3351  84   3442 455   1944  167   1334  357   3698 124
+\& 5.7.2          3491  87   4858 618   3290  298   1598  449   3910 139
+\& 5.7.3          3299  85   4295 537   2196  300   2176  626   4171 120
+\& 5.8.0          3489  87   4533 585   2437  331   2588  726   4368 125
+\& 5.8.1          3674  90   5104 623   2604  353   2983  836   4625 134
+\& 5.8.2          3633  90   5111 623   2623  357   3019  848   4634 135
+\& 5.8.3          3625  90   5141 624   2660  363   3083  869   4669 136
+\& 5.8.4          3653  90   5170 634   2684  368   3148  885   4689 137
+\& 5.8.5          3664  90   4260 303   2707  369   3208  898   4689 138
+\& 5.8.6          3690  90   4271 303   3141  396   3411  925   4709 139
+\& 5.8.7          3788  90   4322 307   3297  401   3485  964   4744 141
+\& 5.8.8          3895  90   4357 314   3409  431   3622 1017   4979 144
+\& 5.8.9          4132  93   5508 330   3826  529   4364 1234   5348 152
+\& 5.9.0          3657  90   4951 626   2603  354   3011  841   4609 135
+\& 5.9.1          3580  90   5196 634   2665  367   3186  889   4725 138
+\& 5.9.2          3863  90   4654 312   3283  403   3551  973   4800 142
+\& 5.9.3          4096  91   5318 381   4806  597   4272 1214   5139 147
+\& 5.9.4          4393  94   5718 415   4578  642   4646 1310   5335 153
+\& 5.9.5          4681  96   6849 479   4827  671   5155 1490   5572 159
+\& 5.10.0         4710  97   7050 486   4899  673   5275 1503   5673 160
+\& 5.10.1         4858  98   7440 519   6195  921   6147 1751   5151 163
+\& 5.12.0         4999 100   1146 121  15227 2176   6400 1843   5342 168
+\& 5.12.1         5000 100   1146 121  15283 2178   6407 1846   5354 169
+\& 5.12.2         5003 100   1146 121  15404 2178   6413 1846   5376 170
+\& 5.12.3         5004 100   1146 121  15529 2180   6417 1848   5391 171
+\& 5.14.0         5328 104   1100 114  17779 2479   7697 2130   5871 188
+\& 5.16.0         5562 109   1077  80  20504 2702   8750 2375   4815 152
+\& 5.18.0         5892 113   1088  79  20077 2760   9365 2439   4943 154
+\& 5.20.0         6243 115   1187  75  19499 2701   9620 2457   5145 159
+\& 5.22.0         7819 115   1284  77  19121 2635   9772 2434   5615 176
+\& 5.24.0         7922 113   1287  77  19535 2677   9994 2465   5702 177
+\& 5.26.0         9140 121  24925 1200 40643 3017  10514 2614   7854 211
+\& 5.28.0        13056 128  27267 1230 41745 3130  10952 2715   8185 218
+\& 5.30.0        13535 128  26294 1237 39643 3080  11083 2711   8252 222
+\& 5.32.0        14147 127  25562 1255 40869 3098  11334 2734   8407 225
+\& 5.34.0        14620 126  28150 1262 42711 3138  11535 2774   8791 228
+\& 5.36.0        15300 129  27899 1270 48275 3236  11899 2863   8858 224
+\& 5.38.0        15793 139  29070 1270 48250 3219  11950 2863   9129 239
+.Ve
+.PP
+The "core"..."doc" mean the following files from the Perl source code
+distribution.  The glob notation ** means recursively, (.) means
+regular files.
+.PP
+.Vb 6
+\& core   *.[hcy]
+\& lib    lib/**/*.p[ml]
+\& ext    ext/**/*.{[hcyt],xs,pm} (for \-5.10.1) or
+\&        {dist,ext,cpan}/**/*.{[hcyt],xs,pm} (for 5.12.0\-)
+\& t      t/**/*(.) (for 1\-5.005_56) or **/*.t (for 5.6.0\-5.7.3)
+\& doc    {README*,INSTALL,*[_.]man{,.?},pod/**/*.pod}
+.Ve
+.PP
+Here are some statistics for the other subdirectories and one file in
+the Perl source distribution for somewhat more selected releases.
+.PP
+.Vb 2
+\& ======================================================================
+\&   Legend:  kB   #
+\&
+\&                  1.014      2.001      3.044
+\&
+\& Configure      31    1    37    1    62    1
+\& eg              \-    \-    34   28    47   39
+\& h2pl            \-    \-     \-    \-    12   12
+\& msdos           \-    \-     \-    \-    41   13
+\& os2             \-    \-     \-    \-    63   22
+\& usub            \-    \-     \-    \-    21   16
+\& x2p           103   17   104   17   137   17
+\&
+\& ======================================================================
+\&
+\&                  4.000      4.019      4.036
+\&
+\& atarist         \-    \-     \-    \-   113   31
+\& Configure      73    1    83    1    86    1
+\& eg             47   39    47   39    47   39
+\& emacs          67    4    67    4    67    4
+\& h2pl           12   12    12   12    12   12
+\& hints           \-    \-     5   42    11   56
+\& msdos          57   15    58   15    60   15
+\& os2            81   29    81   29   113   31
+\& usub           25    7    43    8    43    8
+\& x2p           147   18   152   19   154   19
+\&
+\& ======================================================================
+\&
+\&                5.000a2  5.000a12h   5.000b3h      5.000     5.001m
+\&
+\& apollo          8    3     8    3     8    3     8    3     8    3
+\& atarist       113   31   113   31     \-    \-     \-    \-     \-    \-
+\& bench           \-    \-     0    1     \-    \-     \-    \-     \-    \-
+\& Bugs            2    5    26    1     \-    \-     \-    \-     \-    \-
+\& dlperl         40    5     \-    \-     \-    \-     \-    \-     \-    \-
+\& do            127   71     \-    \-     \-    \-     \-    \-     \-    \-
+\& Configure       \-    \-   153    1   159    1   160    1   180    1
+\& Doc             \-    \-    26    1    75    7    11    1    11    1
+\& eg             79   58    53   44    51   43    54   44    54   44
+\& emacs          67    4   104    6   104    6   104    1   104    6
+\& h2pl           12   12    12   12    12   12    12   12    12   12
+\& hints          11   56    12   46    18   48    18   48    44   56
+\& msdos          60   15    60   15     \-    \-     \-    \-     \-    \-
+\& os2           113   31   113   31     \-    \-     \-    \-     \-    \-
+\& U               \-    \-    62    8   112   42     \-    \-     \-    \-
+\& usub           43    8     \-    \-     \-    \-     \-    \-     \-    \-
+\& vms             \-    \-    80    7   123    9   184   15   304   20
+\& x2p           171   22   171   21   162   20   162   20   279   20
+\&
+\& ======================================================================
+\&
+\&                  5.002      5.003   5.003_07
+\&
+\& Configure     201    1   201    1   217    1
+\& eg             54   44    54   44    54   44
+\& emacs         108    1   108    1   143    1
+\& h2pl           12   12    12   12    12   12
+\& hints          73   59    77   60    90   62
+\& os2            84   17    56   10   117   42
+\& plan9           \-    \-     \-    \-    79   15
+\& Porting         \-    \-     \-    \-    51    1
+\& utils          87    7    88    7    97    7
+\& vms           500   24   475   26   505   27
+\& x2p           280   20   280   20   280   19
+\&
+\& ======================================================================
+\&
+\&                  5.004   5.004_04   5.004_62   5.004_65   5.004_68
+\&
+\& beos            \-    \-     \-    \-     \-    \-      1   1      1   1
+\& Configure     225    1   225    1   240    1    248   1    256   1
+\& cygwin32       23    5    23    5    23    5     24   5     24   5
+\& djgpp           \-    \-     \-    \-    14    5     14   5     14   5
+\& eg             81   62    81   62    81   62     81  62     81  62
+\& emacs         194    1   204    1   212    2    212   2    212   2
+\& h2pl           12   12    12   12    12   12     12  12     12  12
+\& hints         129   69   132   71   144   72    151  74    155  74
+\& os2           121   42   127   42   127   44    129  44    129  44
+\& plan9          82   15    82   15    82   15     82  15     82  15
+\& Porting        94    2   109    4   203    6    234   8    241   9
+\& qnx             1    2     1    2     1    2      1   2      1   2
+\& utils         112    8   118    8   124    8    156   9    159   9
+\& vms           518   34   524   34   538   34    569  34    569  34
+\& win32         285   33   378   36   470   39    493  39    575  41
+\& x2p           281   19   281   19   281   19    282  19    281  19
+\&
+\& ======================================================================
+\&
+\&               5.004_70   5.004_73   5.004_75      5.005   5.005_03
+\&
+\& apollo          \-    \-     \-    \-     \-    \-     \-    \-      0   1
+\& beos            1    1     1    1     1    1     1    1      1   1
+\& Configure     256    1   256    1   264    1   264    1    270   1
+\& cygwin32       24    5    24    5    24    5    24    5     24   5
+\& djgpp          14    5    14    5    14    5    14    5     15   5
+\& eg             86   65    86   65    86   65    86   65     86  65
+\& emacs         262    2   262    2   262    2   262    2    274   2
+\& h2pl           12   12    12   12    12   12    12   12     12  12
+\& hints         157   74   157   74   159   74   160   74    179  77
+\& mint            \-    \-     \-    \-     \-    \-     \-    \-      4   7
+\& mpeix           \-    \-     \-    \-     5    3     5    3      5   3
+\& os2           129   44   139   44   142   44   143   44    148  44
+\& plan9          82   15    82   15    82   15    82   15     82  15
+\& Porting       241    9   253    9   259   10   264   12    272  13
+\& qnx             1    2     1    2     1    2     1    2      1   2
+\& utils         160    9   160    9   160    9   160    9    164   9
+\& vms           570   34   572   34   573   34   575   34    583  34
+\& vos             \-    \-     \-    \-     \-    \-     \-   \-     156  10
+\& win32         577   41   585   41   585   41   587   41    600  42
+\& x2p           281   19   281   19   281   19   281   19    281  19
+\&
+\& ======================================================================
+\&
+\&                  5.6.0      5.6.1      5.6.2      5.7.3
+\&
+\& apollo          8    3     8    3     8    3     8    3
+\& beos            5    2     5    2     5    2     6    4
+\& Configure     346    1   361    1   363    1   394    1
+\& Cross           \-    \-     \-    \-     \-    \-     4    2
+\& djgpp          19    6    19    6    19    6    21    7
+\& eg            112   71   112   71   112   71     \-    \-
+\& emacs         303    4   319    4   319    4   319    4
+\& epoc           29    8    35    8    35    8    36    8
+\& h2pl           24   15    24   15    24   15    24   15
+\& hints         242   83   250   84   321   89   272   87
+\& mint           11    9    11    9    11    9    11    9
+\& mpeix           9    4     9    4     9    4     9    4
+\& NetWare         \-    \-     \-    \-     \-    \-   423   57
+\& os2           214   59   224   60   224   60   357   66
+\& plan9          92   17    92   17    92   17    85   15
+\& Porting       361   15   390   16   390   16   425   21
+\& qnx             5    3     5    3     5    3     5    3
+\& utils         228   12   221   11   222   11   267   13
+\& uts             \-    \-     \-    \-     \-    \-    12    3
+\& vmesa          25    4    25    4    25    4    25    4
+\& vms           686   38   627   38   627   38   649   36
+\& vos           227   12   249   15   248   15   281   17
+\& win32         755   41   782   42   801   42  1006   50
+\& x2p           307   20   307   20   307   20   345   20
+\&
+\& ======================================================================
+\&
+\&                  5.8.0      5.8.1      5.8.2      5.8.3      5.8.4
+\&
+\& apollo          8    3     8    3     8    3     8    3     8    3
+\& beos            6    4     6    4     6    4     6    4     6    4
+\& Configure     472    1   493    1   493    1   493    1   494    1
+\& Cross           4    2    45   10    45   10    45   10    45   10
+\& djgpp          21    7    21    7    21    7    21    7    21    7
+\& emacs         319    4   329    4   329    4   329    4   329    4
+\& epoc           33    8    33    8    33    8    33    8    33    8
+\& h2pl           24   15    24   15    24   15    24   15    24   15
+\& hints         294   88   321   89   321   89   321   89   348   91
+\& mint           11    9    11    9    11    9    11    9    11    9
+\& mpeix          24    5    25    5    25    5    25    5    25    5
+\& NetWare       488   61   490   61   490   61   490   61   488   61
+\& os2           361   66   445   67   450   67   488   67   488   67
+\& plan9          85   15   325   17   325   17   325   17   321   17
+\& Porting       479   22   537   32   538   32   539   32   538   33
+\& qnx             5    3     5    3     5    3     5    3     5    3
+\& utils         275   15   258   16   258   16   263   19   263   19
+\& uts            12    3    12    3    12    3    12    3    12    3
+\& vmesa          25    4    25    4    25    4    25    4    25    4
+\& vms           648   36   654   36   654   36   656   36   656   36
+\& vos           330   20   335   20   335   20   335   20   335   20
+\& win32        1062   49  1125   49  1127   49  1126   49  1181   56
+\& x2p           347   20   348   20   348   20   348   20   348   20
+\&
+\& ======================================================================
+\&
+\&                  5.8.5      5.8.6      5.8.7      5.8.8      5.8.9
+\&
+\& apollo          8    3     8    3     8    3     8    3     8    3
+\& beos            6    4     6    4     8    4     8    4     8    4
+\& Configure     494    1   494    1   495    1   506    1   520    1
+\& Cross          45   10    45   10    45   10    45   10    46   10
+\& djgpp          21    7    21    7    21    7    21    7    21    7
+\& emacs         329    4   329    4   329    4   329    4   406    4
+\& epoc           33    8    33    8    33    8    34    8    35    8
+\& h2pl           24   15    24   15    24   15    24   15    24   15
+\& hints         350   91   352   91   355   94   360   94   387   99
+\& mint           11    9    11    9    11    9    11    9    11    9
+\& mpeix          25    5    25    5    25    5    49    6    49    6
+\& NetWare       488   61   488   61   488   61   490   61   491   61
+\& os2           488   67   488   67   488   67   488   67   552   70
+\& plan9         321   17   321   17   321   17   322   17   324   17
+\& Porting       538   34   548   35   549   35   564   37   625   41
+\& qnx             5    3     5    3     5    3     5    3     5    3
+\& utils         265   19   265   19   266   19   267   19   281   21
+\& uts            12    3    12    3    12    3    12    3    12    3
+\& vmesa          25    4    25    4    25    4    25    4    25    4
+\& vms           657   36   658   36   662   36   664   36   716   35
+\& vos           335   20   335   20   335   20   336   21   345   22
+\& win32        1183   56  1190   56  1199   56  1219   56  1484   68
+\& x2p           349   20   349   20   349   20   349   19   350   19
+\&
+\& ======================================================================
+\&
+\&                  5.9.0      5.9.1      5.9.2      5.9.3      5.9.4
+\&
+\& apollo          8    3     8    3     8    3     8    3     8    3
+\& beos            6    4     6    4     8    4     8    4     8    4
+\& Configure     493    1   493    1   495    1   508    1   512    1
+\& Cross          45   10    45   10    45   10    45   10    46   10
+\& djgpp          21    7    21    7    21    7    21    7    21    7
+\& emacs         329    4   329    4   329    4   329    4   329    4
+\& epoc           33    8    33    8    33    8    34    8    34    8
+\& h2pl           24   15    24   15    24   15    24   15    24   15
+\& hints         321   89   346   91   355   94   359   94   366   96
+\& mad             \-    \-     \-    \-     \-    \-     \-    \-   174    6
+\& mint           11    9    11    9    11    9    11    9    11    9
+\& mpeix          25    5    25    5    25    5    49    6    49    6
+\& NetWare       489   61   487   61   487   61   489   61   489   61
+\& os2           444   67   488   67   488   67   488   67   488   67
+\& plan9         325   17   321   17   321   17   322   17   323   17
+\& Porting       537   32   536   33   549   36   564   38   576   38
+\& qnx             5    3     5    3     5    3     5    3     5    3
+\& symbian         \-    \-     \-    \-     \-    \-   293   53   293   53
+\& utils         258   16   263   19   268   20   273   23   275   24
+\& uts            12    3    12    3    12    3    12    3    12    3
+\& vmesa          25    4    25    4    25    4    25    4    25    4
+\& vms           660   36   547   33   553   33   661   33   696   33
+\& vos            11    7    11    7    11    7    11    7    11    7
+\& win32        1120   49  1124   51  1191   56  1209   56  1719   90
+\& x2p           348   20   348   20   349   20   349   19   349   19
+\&
+\& ======================================================================
+\&
+\&                  5.9.5     5.10.0     5.10.1     5.12.0     5.12.1
+\&
+\& apollo          8    3     8    3     0    3     0    3     0    3
+\& beos            8    4     8    4     4    4     4    4     4    4
+\& Configure     518    1   518    1   533    1   536    1   536    1
+\& Cross         122   15   122   15   119   15   118   15   118   15
+\& djgpp          21    7    21    7    17    7    17    7    17    7
+\& emacs         329    4   406    4   402    4   402    4   402    4
+\& epoc           34    8    35    8    31    8    31    8    31    8
+\& h2pl           24   15    24   15    12   15    12   15    12   15
+\& hints         377   98   381   98   385  100   368   97   368   97
+\& mad           182    8   182    8   174    8   174    8   174    8
+\& mint           11    9    11    9     3    9     \-    \-     \-    \-
+\& mpeix          49    6    49    6    45    6    45    6    45    6
+\& NetWare       489   61   489   61   465   61   466   61   466   61
+\& os2           552   70   552   70   507   70   507   70   507   70
+\& plan9         324   17   324   17   316   17   316   17   316   17
+\& Porting       627   40   632   40   933   53   749   54   749   54
+\& qnx             5    3     5    4     1    4     1    4     1    4
+\& symbian       300   54   300   54   290   54   288   54   288   54
+\& utils         260   26   264   27   268   27   269   27   269   27
+\& uts            12    3    12    3     8    3     8    3     8    3
+\& vmesa          25    4    25    4    21    4    21    4    21    4
+\& vms           690   32   722   32   693   30   645   18   645   18
+\& vos            19    8    19    8    16    8    16    8    16    8
+\& win32        1482   68  1485   68  1497   70  1841   73  1841   73
+\& x2p           349   19   349   19   345   19   345   19   345   19
+\&
+\& ======================================================================
+\&
+\&                 5.12.2     5.12.3      5.14.0     5.16.0       5.18.0
+\&
+\& apollo          0    3     0    3      \-    \-     \-    \-      \-     \-
+\& beos            4    4     4    4      5    4     5    4      \-     \-
+\& Configure     536    1   536    1    539    1   547    1    550     1
+\& Cross         118   15   118   15    118   15   118   15    118    15
+\& djgpp          17    7    17    7     18    7    18    7     18     7
+\& emacs         402    4   402    4      \-    \-     \-    \-      \-     \-
+\& epoc           31    8    31    8     32    8    30    8      \-     \-
+\& h2pl           12   15    12   15     15   15    15   15     13    15
+\& hints         368   97   368   97    370   96   371   96    354    91
+\& mad           174    8   174    8    176    8   176    8    174     8
+\& mpeix          45    6    45    6     46    6    46    6      \-     \-
+\& NetWare       466   61   466   61    473   61   472   61    469    61
+\& os2           507   70   507   70    518   70   519   70    510    70
+\& plan9         316   17   316   17    319   17   319   17    318    17
+\& Porting       750   54   750   54    855   60  1093   69   1149    70
+\& qnx             1    4     1    4      2    4     2    4      1     4
+\& symbian       288   54   288   54    292   54   292   54    290    54
+\& utils         269   27   269   27    249   29   245   30    246    31
+\& uts             8    3     8    3      9    3     9    3      \-     \-
+\& vmesa          21    4    21    4     22    4    22    4      \-     \-
+\& vms           646   18   644   18    639   17   571   15    564    15
+\& vos            16    8    16    8     17    8     9    7      8     7
+\& win32        1841   73  1841   73   1833   72  1655   67   1157    62
+\& x2p           345   19   345   19    346   19   345   19    344    20
+\&
+\& ======================================================================
+\&
+\&                  5.20.0           5.22.0          5.24.0
+\&
+\& Configure    552      1       570      1      586      1
+\& Cross        118     15       118     15      118     15
+\& djgpp         18      7        17      7       17      7
+\& h2pl          13     15        13     15       13     15
+\& hints        355     90       356     87      362     87
+\& mad          174      8         \-      \-        \-      \-
+\& NetWare      467     61       466     61      467     61
+\& os2          510     70       510     70      510     70
+\& plan9        316     17       317     17      314     17
+\& Porting     1204     68      1393     71     1321     71
+\& qnx            1      4         1      4        1      4
+\& symbian      290     54       291     54      292     54
+\& utils        241     27       242     27      679     53
+\& vms          538     12       532     12      524     12
+\& vos            8      7         8      7        8      7
+\& win32       1183     64      1201     64     1268     65
+\& x2p          341     19         \-      \-        \-      \-
+\&
+\& ======================================================================
+\&
+\&                  5.26.0           5.28.0           5.30.0
+\&
+\& Configure    593      1       580      1       587      1
+\& Cross        122     15       125     15       126     15
+\& djgpp         21      7        21      7        21      7
+\& h2pl          24     15        24     15        24     15
+\& hints        376     87       364     85       372     86
+\& mad            \-      \-         \-      \-         \-      \-
+\& NetWare      499     61       493     61       493     61
+\& os2          552     70       552     70       552     70
+\& plan9        322     17       309     17       308     17
+\& Porting     1380     73      1462     75      1460     74
+\& qnx            5      4         5      4         5      4
+\& symbian      315     54       315     54       315     54
+\& utils        578     50       584     50       587     50
+\& vms          527     12       526     12       526     12
+\& vos           12      7        12      7        12      7
+\& win32       1313     65      1326     65      1331     65
+\& x2p            \-      \-         \-      \-         \-      \-
+\&
+\&                  5.32.0           5.34.0           5.36.0
+\&
+\& Configure    588      1       592      1       603      1
+\& Cross        126     15       126     15       122     15
+\& djgpp         21      7        22      7         \-      \-
+\& h2pl          24     15        24     15        13     15
+\& hints        363     86       364     86       359     84
+\& NetWare      484     61       533     61         \-      \-
+\& os2          552     70       580     70       538     70
+\& plan9        308     17       325     20       318     20
+\& Porting     1482     75      1514     75      1559     78
+\& qnx            5      4         5      4         1      4
+\& symbian      307     54         \-      \-         \-      \-
+\& utils        583     52       597     52       607     52
+\& vms          527     12       549     12       545     12
+\& vos           12      7        12      7         8      7
+\& win32       1011     47      1001     46       966     45
+\&
+\&                  5.38.0
+\&
+\& Configure    604      1
+\& Cross        122     15
+\& h2pl          13     15
+\& hints        358     83
+\& os2          538     70
+\& plan9        322     20
+\& Porting     1640     80
+\& qnx            1      4
+\& utils        606     52
+\& vms          544     12
+\& vos            8      7
+\& win32        982     45
+.Ve
+.SS "SELECTED PATCH SIZES"
+.IX Subsection "SELECTED PATCH SIZES"
+The "diff lines kB" means that for example the patch 5.003_08, to be
+applied on top of the 5.003_07 (or whatever was before the 5.003_08)
+added lines for 110 kilobytes, it removed lines for 19 kilobytes, and
+changed lines for 424 kilobytes.  Just the lines themselves are
+counted, not their context.  The "+ \- !" become from the \fBdiff\fR\|(1)
+context diff output format.
+.PP
+.Vb 4
+\& Pump\-  Release         Date              diff lines kB
+\& king                                     \-\-\-\-\-\-\-\-\-\-\-\-\-
+\&                                          +     \-     !
+\& ======================================================================
+\&
+\& Chip     5.003_08      1996\-Nov\-19     110    19   424
+\&          5.003_09      1996\-Nov\-26      38     9   248
+\&          5.003_10      1996\-Nov\-29      29     2    27
+\&          5.003_11      1996\-Dec\-06      73    12   165
+\&          5.003_12      1996\-Dec\-19     275     6   436
+\&          5.003_13      1996\-Dec\-20      95     1    56
+\&          5.003_14      1996\-Dec\-23      23     7   333
+\&          5.003_15      1996\-Dec\-23       0     0     1
+\&          5.003_16      1996\-Dec\-24      12     3    50
+\&          5.003_17      1996\-Dec\-27      19     1    14
+\&          5.003_18      1996\-Dec\-31      21     1    32
+\&          5.003_19      1997\-Jan\-04      80     3    85
+\&          5.003_20      1997\-Jan\-07      18     1   146
+\&          5.003_21      1997\-Jan\-15      38    10   221
+\&          5.003_22      1997\-Jan\-16       4     0    18
+\&          5.003_23      1997\-Jan\-25      71    15   119
+\&          5.003_24      1997\-Jan\-29     426     1    20
+\&          5.003_25      1997\-Feb\-04      21     8   169
+\&          5.003_26      1997\-Feb\-10      16     1    15
+\&          5.003_27      1997\-Feb\-18      32    10    38
+\&          5.003_28      1997\-Feb\-21      58     4    66
+\&          5.003_90      1997\-Feb\-25      22     2    34
+\&          5.003_91      1997\-Mar\-01      37     1    39
+\&          5.003_92      1997\-Mar\-06      16     3    69
+\&          5.003_93      1997\-Mar\-10      12     3    15
+\&          5.003_94      1997\-Mar\-22     407     7   200
+\&          5.003_95      1997\-Mar\-25      41     1    37
+\&          5.003_96      1997\-Apr\-01     283     5   261
+\&          5.003_97      1997\-Apr\-03      13     2    34
+\&          5.003_97a     1997\-Apr\-05      57     1    27
+\&          5.003_97b     1997\-Apr\-08      14     1    20
+\&          5.003_97c     1997\-Apr\-10      20     1    16
+\&          5.003_97d     1997\-Apr\-13       8     0    16
+\&          5.003_97e     1997\-Apr\-15      15     4    46
+\&          5.003_97f     1997\-Apr\-17       7     1    33
+\&          5.003_97g     1997\-Apr\-18       6     1    42
+\&          5.003_97h     1997\-Apr\-24      23     3    68
+\&          5.003_97i     1997\-Apr\-25      23     1    31
+\&          5.003_97j     1997\-Apr\-28      36     1    49
+\&          5.003_98      1997\-Apr\-30     171    12   539
+\&          5.003_99      1997\-May\-01       6     0     7
+\&          5.003_99a     1997\-May\-09      36     2    61
+\&          p54rc1        1997\-May\-12       8     1    11
+\&          p54rc2        1997\-May\-14       6     0    40
+\&
+\&        5.004           1997\-May\-15       4     0     4
+\&
+\& Tim      5.004_01      1997\-Jun\-13     222    14    57
+\&          5.004_02      1997\-Aug\-07     112    16   119
+\&          5.004_03      1997\-Sep\-05     109     0    17
+\&          5.004_04      1997\-Oct\-15      66     8   173
+.Ve
+.PP
+\fIThe patch-free era\fR
+.IX Subsection "The patch-free era"
+.PP
+In more modern times, named releases don't come as often, and as progress
+can be followed (nearly) instantly (with rsync, and since late 2008, git)
+patches between versions are no longer provided. However, that doesn't
+keep us from calculating how large a patch could have been. Which is
+shown in the table below. Unless noted otherwise, the size mentioned is
+the patch to bring version x.y.z to x.y.z+1.
+.PP
+.Vb 2
+\& Sarathy  5.6.1         2001\-Apr\-08     531    44   651
+\& Rafael   5.6.2         2003\-Nov\-15      20    11  1819
+\&
+\& Jarkko   5.8.0         2002\-Jul\-18    1205    31   471   From 5.7.3
+\&
+\&          5.8.1         2003\-Sep\-25     243   102  6162
+\& Nicholas 5.8.2         2003\-Nov\-05      10    50   788
+\&          5.8.3         2004\-Jan\-14      31    13   360
+\&          5.8.4         2004\-Apr\-21      33     8   299
+\&          5.8.5         2004\-Jul\-19      11    19   255
+\&          5.8.6         2004\-Nov\-27      35     3   192
+\&          5.8.7         2005\-May\-30      75    34   778
+\&          5.8.8         2006\-Jan\-31     131    42  1251
+\&          5.8.9         2008\-Dec\-14     340   132 12988
+\&
+\& Hugo     5.9.0         2003\-Oct\-27     281   168  7132   From 5.8.0
+\& Rafael   5.9.1         2004\-Mar\-16      57   250  2107
+\&          5.9.2         2005\-Apr\-01     720    57   858
+\&          5.9.3         2006\-Jan\-28    1124   102  1906
+\&          5.9.4         2006\-Aug\-15     896    60   862
+\&          5.9.5         2007\-Jul\-07    1149   128  1062
+\&
+\&          5.10.0        2007\-Dec\-18      50    31 13111   From 5.9.5
+.Ve
+.SH "THE KEEPERS OF THE RECORDS"
+.IX Header "THE KEEPERS OF THE RECORDS"
+Jarkko Hietaniemi <\fIjhi@iki.fi\fR>.
+.PP
+Thanks to the collective memory of the Perlfolk.  In addition to the
+Keepers of the Pumpkin also Alan Champion, Mark Dominus,
+Andreas König, John Macdonald, Matthias Neeracher, Jeff Okamoto,
+Michael Peppler, Randal Schwartz, and Paul D. Smith sent corrections
+and additions. Abigail added file and patch size data for the 5.6.0 \- 5.10
+era.
diff --git a/upstream/mageia-cauldron/man1/perlhpux.1 b/upstream/mageia-cauldron/man1/perlhpux.1
new file mode 100644
index 00000000..b9b2e843
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhpux.1
@@ -0,0 +1,784 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHPUX 1"
+.TH PERLHPUX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhpux \- Perl version 5 on Hewlett\-Packard Unix (HP\-UX) systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of HP's Unix operating system
+(HP-UX) that will affect how Perl version 5 (hereafter just Perl) is
+compiled and/or runs.
+.SS "Using perl as shipped with HP-UX"
+.IX Subsection "Using perl as shipped with HP-UX"
+Application release September 2001, HP-UX 11.00 is the first to ship
+with Perl. By the time it was perl\-5.6.1 in /opt/perl. The first
+occurrence is on CD 5012\-7954 and can be installed using
+.PP
+.Vb 1
+\&  swinstall \-s /cdrom perl
+.Ve
+.PP
+assuming you have mounted that CD on /cdrom.
+.PP
+That build was a portable hppa\-1.1 multithread build that supports large
+files compiled with gcc\-2.9\-hppa\-991112.
+.PP
+If you perform a new installation, then (a newer) Perl will be installed
+automatically.  Pre-installed HP-UX systems now have more recent versions
+of Perl and the updated modules.
+.PP
+The official (threaded) builds from HP, as they are shipped on the
+Application DVD/CD's are available on
+<http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL>
+for both PA-RISC and IPF (Itanium Processor Family). They are built
+with the HP ANSI-C compiler. Up till 5.8.8 that was done by ActiveState.
+.PP
+To see what version is included on the DVD (assumed here to be mounted
+on /cdrom), issue this command:
+.PP
+.Vb 6
+\&  # swlist \-s /cdrom perl
+\&  # perl           D.5.8.8.B  5.8.8 Perl Programming Language
+\&    perl.Perl5\-32  D.5.8.8.B  32\-bit 5.8.8 Perl Programming Language
+\&                                           with Extensions
+\&    perl.Perl5\-64  D.5.8.8.B  64\-bit 5.8.8 Perl Programming Language
+\&                                           with Extensions
+.Ve
+.PP
+To see what is installed on your system:
+.PP
+.Vb 10
+\&  # swlist \-R perl
+\&  # perl                    E.5.8.8.J  Perl Programming Language
+\&  # perl.Perl5\-32           E.5.8.8.J  32\-bit Perl Programming Language
+\&                                       with Extensions
+\&    perl.Perl5\-32.PERL\-MAN  E.5.8.8.J  32\-bit Perl Man Pages for IA
+\&    perl.Perl5\-32.PERL\-RUN  E.5.8.8.J  32\-bit Perl Binaries for IA
+\&  # perl.Perl5\-64           E.5.8.8.J  64\-bit Perl Programming Language
+\&                                       with Extensions
+\&    perl.Perl5\-64.PERL\-MAN  E.5.8.8.J  64\-bit Perl Man Pages for IA
+\&    perl.Perl5\-64.PERL\-RUN  E.5.8.8.J  64\-bit Perl Binaries for IA
+.Ve
+.SS "Using perl from HP's porting centre"
+.IX Subsection "Using perl from HP's porting centre"
+HP porting centre tries to keep up with customer demand and release
+updates from the Open Source community. Having precompiled Perl binaries
+available is obvious, though "up-to-date" is something relative. At the
+moment of writing perl\-5.10.1 and 5.28.0 were available.
+.PP
+The HP porting centres are limited in what systems they are allowed
+to port to and they usually choose the two most recent OS versions
+available.
+.PP
+HP has asked the porting centre to move Open Source binaries
+from /opt to /usr/local, so binaries produced since the start
+of July 2002 are located in /usr/local.
+.PP
+One of HP porting centres URL's is <http://hpux.connect.org.uk/>
+The port currently available is built with GNU gcc. As porting modern
+GNU gcc is extremely hard on HP-UX, they are stuck at version gcc\-4.2.3.
+.SS "Other prebuilt perl binaries"
+.IX Subsection "Other prebuilt perl binaries"
+To get more perl depots for the whole range of HP-UX, visit
+H.Merijn Brand's site at <http://mirrors.develooper.com/hpux/#Perl>.
+Carefully read the notes to see if the available versions suit your needs.
+.SS "Compiling Perl 5 on HP-UX"
+.IX Subsection "Compiling Perl 5 on HP-UX"
+When compiling Perl, you must use an ANSI C compiler.  The C compiler
+that ships with all HP-UX systems is a K&R compiler that should only be
+used to build new kernels.
+.PP
+Perl can be compiled with either HP's ANSI C compiler or with gcc.  The
+former is recommended, as not only can it compile Perl with no
+difficulty, but also can take advantage of features listed later that
+require the use of HP compiler-specific command-line flags.
+.PP
+If you decide to use gcc, make sure your installation is recent and
+complete, and be sure to read the Perl INSTALL file for more gcc-specific
+details.
+.SS PA-RISC
+.IX Subsection "PA-RISC"
+The last and final version of PA-RISC is 2.0, HP no longer sells any
+system with these CPU's.
+.PP
+HP's HP9000 Unix systems run on HP's own Precision Architecture
+(PA-RISC) chip.  HP-UX used to run on the Motorola MC68000 family of
+chips, but any machine with this chip in it is quite obsolete and this
+document will not attempt to address issues for compiling Perl on the
+Motorola chipset. Even though PA-RISC hardware is not sold anymore, a
+lot of machines still running on these CPU's can be found in the wild.
+.PP
+The last order date for HP 9000 systems was December 31, 2008.
+.PP
+HP PA-RISC systems are usually referred to with model description "HP 9000".
+The last CPU in this series is the PA\-8900.  Support for PA-RISC
+architectured machines officially ended as shown in the following table:
+.PP
+.Vb 10
+\&   PA\-RISC End\-of\-Life Roadmap
+\& +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | HP9000 | Superdome      | PA\-8700        | Spring 2011     |
+\& | 4\-128  |                | PA\-8800/sx1000 | Summer 2012     |
+\& | cores  |                | PA\-8900/sx1000 | 2014            |
+\& |        |                | PA\-8900/sx2000 | 2015            |
+\& +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | HP9000 | rp7410, rp8400 | PA\-8700        | Spring 2011     |
+\& | 2\-32   | rp7420, rp8420 | PA\-8800/sx1000 | 2012            |
+\& | cores  | rp7440, rp8440 | PA\-8900/sx1000 | Autumn 2013     |
+\& |        |                | PA\-8900/sx2000 | 2015            |
+\& +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | HP9000 | rp44x0         | PA\-8700        | Spring 2011     |
+\& | 1\-8    |                | PA\-8800/rp44x0 | 2012            |
+\& | cores  |                | PA\-8900/rp44x0 | 2014            |
+\& +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | HP9000 | rp34x0         | PA\-8700        | Spring 2011     |
+\& | 1\-4    |                | PA\-8800/rp34x0 | 2012            |
+\& | cores  |                | PA\-8900/rp34x0 | 2014            |
+\& +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+A complete list of models at the time the OS was built is in the file
+/usr/sam/lib/mo/sched.models. The first column corresponds to the last
+part of the output of the "model" command.  The second column is the
+PA-RISC version and the third column is the exact chip type used.
+(Start browsing at the bottom to prevent confusion ;\-)
+.PP
+.Vb 4
+\&  # model
+\&  9000/800/L1000\-44
+\&  # grep L1000\-44 /usr/sam/lib/mo/sched.models
+\&  L1000\-44        2.0     PA8500
+.Ve
+.SS "PA-RISC 1.0"
+.IX Subsection "PA-RISC 1.0"
+The original version of PA-RISC, HP no longer sells any system with this chip.
+.PP
+The following systems contained PA-RISC 1.0 chips:
+.PP
+.Vb 2
+\&  600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850,
+\&  852, 855, 860, 865, 870, 890
+.Ve
+.SS "PA-RISC 1.1"
+.IX Subsection "PA-RISC 1.1"
+An upgrade to the PA-RISC design, it shipped for many years in many different
+system.
+.PP
+The following systems contain with PA-RISC 1.1 chips:
+.PP
+.Vb 10
+\&  705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 744, 745,
+\&  747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
+\&  813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
+\&  851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
+\&  B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
+\&  C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
+\&  D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
+\&  G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
+\&  I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
+\&  K420, S700i, S715, S744, S760, T500, T520
+.Ve
+.SS "PA-RISC 2.0"
+.IX Subsection "PA-RISC 2.0"
+The most recent upgrade to the PA-RISC design, it added support for
+64\-bit integer data.
+.PP
+As of the date of this document's last update, the following systems
+contain PA-RISC 2.0 chips:
+.PP
+.Vb 8
+\&  700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
+\&  893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
+\&  C180, C180+, C180\-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
+\&  D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
+\&  J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260\-EG, K270, K360,
+\&  K370, K380, K450, K460, K460\-EG, K460\-XP, K470, K570, K580, L1000,
+\&  L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
+\&  T600, V2000, V2200, V2250, V2500, V2600
+.Ve
+.PP
+Just before HP took over Compaq, some systems were renamed. the link
+that contained the explanation is dead, so here's a short summary:
+.PP
+.Vb 3
+\&  HP 9000 A\-Class servers, now renamed HP Server rp2400 series.
+\&  HP 9000 L\-Class servers, now renamed HP Server rp5400 series.
+\&  HP 9000 N\-Class servers, now renamed HP Server rp7400.
+\&
+\&  rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
+\&  rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
+\&  rp7410, rp7420, rp7440, rp8400, rp8420, rp8440, Superdome
+.Ve
+.PP
+The current naming convention is:
+.PP
+.Vb 10
+\&  aadddd
+\&  ||||\`+\- 00 \- 99 relative capacity & newness (upgrades, etc.)
+\&  |||\`\-\-\- unique number for each architecture to ensure different
+\&  |||     systems do not have the same numbering across
+\&  |||     architectures
+\&  ||\`\-\-\-\- 1 \- 9 identifies family and/or relative positioning
+\&  ||
+\&  |\`\-\-\-\-\- c = ia32 (cisc)
+\&  |       p = pa\-risc
+\&  |       x = ia\-64 (Itanium & Itanium 2)
+\&  |       h = housing
+\&  \`\-\-\-\-\-\- t = tower
+\&          r = rack optimized
+\&          s = super scalable
+\&          b = blade
+\&          sa = appliance
+.Ve
+.SS "Portability Between PA-RISC Versions"
+.IX Subsection "Portability Between PA-RISC Versions"
+An executable compiled on a PA-RISC 2.0 platform will not execute on a
+PA-RISC 1.1 platform, even if they are running the same version of
+HP-UX.  If you are building Perl on a PA-RISC 2.0 platform and want that
+Perl to also run on a PA-RISC 1.1, the compiler flags +DAportable and
++DS32 should be used.
+.PP
+It is no longer possible to compile PA-RISC 1.0 executables on either
+the PA-RISC 1.1 or 2.0 platforms.  The command-line flags are accepted,
+but the resulting executable will not run when transferred to a PA-RISC
+1.0 system.
+.SS "Itanium Processor Family (IPF) and HP-UX"
+.IX Subsection "Itanium Processor Family (IPF) and HP-UX"
+HP-UX also runs on the newer Itanium processor.  This requires the use
+of HP-UX version 11.23 (11i v2) or 11.31 (11i v3), and with the exception
+of a few differences detailed below and in later sections, Perl should
+compile with no problems.
+.PP
+Although PA-RISC binaries can run on Itanium systems, you should not
+attempt to use a PA-RISC version of Perl on an Itanium system.  This is
+because shared libraries created on an Itanium system cannot be loaded
+while running a PA-RISC executable.
+.PP
+HP Itanium 2 systems are usually referred to with model description
+"HP Integrity".
+.SS "Itanium, Itanium 2 & Madison 6"
+.IX Subsection "Itanium, Itanium 2 & Madison 6"
+HP also ships servers with the 128\-bit Itanium processor(s). The cx26x0
+is told to have Madison 6. As of the date of this document's last update,
+the following systems contain Itanium or Itanium 2 chips (this is likely
+to be out of date):
+.PP
+.Vb 4
+\&  BL60p, BL860c, BL870c, BL890c, cx2600, cx2620, rx1600, rx1620, rx2600,
+\&  rx2600hptc, rx2620, rx2660, rx2800, rx3600, rx4610, rx4640, rx5670,
+\&  rx6600, rx7420, rx7620, rx7640, rx8420, rx8620, rx8640, rx9610,
+\&  sx1000, sx2000
+.Ve
+.PP
+To see all about your machine, type
+.PP
+.Vb 3
+\&  # model
+\&  ia64 hp server rx2600
+\&  # /usr/contrib/bin/machinfo
+.Ve
+.SS "HP-UX versions"
+.IX Subsection "HP-UX versions"
+Not all architectures (PA = PA-RISC, IPF = Itanium Processor Family)
+support all versions of HP-UX, here is a short list
+.PP
+.Vb 8
+\&  HP\-UX version  Kernel  Architecture End\-of\-factory support
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  10.20          32 bit  PA           30\-Jun\-2003
+\&  11.00          32/64   PA           31\-Dec\-2006
+\&  11.11  11i v1  32/64   PA           31\-Dec\-2015
+\&  11.22  11i v2     64        IPF     30\-Apr\-2004
+\&  11.23  11i v2     64   PA & IPF     31\-Dec\-2015
+\&  11.31  11i v3     64   PA & IPF     31\-Dec\-2020 (PA) 31\-Dec\-2025 (IPF)
+.Ve
+.PP
+See for the full list of hardware/OS support and expected end-of-life
+<https://h20195.www2.hpe.com/V2/getpdf.aspx/4AA4\-7673ENW.pdf>
+.SS "Building Dynamic Extensions on HP-UX"
+.IX Subsection "Building Dynamic Extensions on HP-UX"
+HP-UX supports dynamically loadable libraries (shared libraries).
+Shared libraries end with the suffix .sl.  On Itanium systems,
+they end with the suffix .so.
+.PP
+Shared libraries created on a platform using a particular PA-RISC
+version are not usable on platforms using an earlier PA-RISC version by
+default.  However, this backwards compatibility may be enabled using the
+same +DAportable compiler flag (with the same PA-RISC 1.0 caveat
+mentioned above).
+.PP
+Shared libraries created on an Itanium platform cannot be loaded on
+a PA-RISC platform.  Shared libraries created on a PA-RISC platform
+can only be loaded on an Itanium platform if it is a PA-RISC executable
+that is attempting to load the PA-RISC library.  A PA-RISC shared
+library cannot be loaded into an Itanium executable nor vice-versa.
+.PP
+To create a shared library, the following steps must be performed:
+.PP
+.Vb 4
+\&  1. Compile source modules with +z or +Z flag to create a .o module
+\&     which contains Position\-Independent Code (PIC).  The linker will
+\&     tell you in the next step if +Z was needed.
+\&     (For gcc, the appropriate flag is \-fpic or \-fPIC.)
+\&
+\&  2. Link the shared library using the \-b flag.  If the code calls
+\&     any functions in other system libraries (e.g., libm), it must
+\&     be included on this line.
+.Ve
+.PP
+(Note that these steps are usually handled automatically by the extension's
+Makefile).
+.PP
+If these dependent libraries are not listed at shared library creation
+time, you will get fatal "Unresolved symbol" errors at run time when the
+library is loaded.
+.PP
+You may create a shared library that refers to another library, which
+may be either an archive library or a shared library.  If this second
+library is a shared library, this is called a "dependent library".  The
+dependent library's name is recorded in the main shared library, but it
+is not linked into the shared library.  Instead, it is loaded when the
+main shared library is loaded.  This can cause problems if you build an
+extension on one system and move it to another system where the
+libraries may not be located in the same place as on the first system.
+.PP
+If the referred library is an archive library, then it is treated as a
+simple collection of .o modules (all of which must contain PIC).  These
+modules are then linked into the shared library.
+.PP
+Note that it is okay to create a library which contains a dependent
+library that is already linked into perl.
+.PP
+Some extensions, like DB_File and Compress::Zlib use/require prebuilt
+libraries for the perl extensions/modules to work. If these libraries
+are built using the default configuration, it might happen that you
+run into an error like "invalid loader fixup" during load phase.
+HP is aware of this problem.  Search the HP-UX cxx-dev forums for
+discussions about the subject.  The short answer is that \fBeverything\fR
+(all libraries, everything) must be compiled with \f(CW\*(C`+z\*(C'\fR or \f(CW\*(C`+Z\*(C'\fR to be
+PIC (position independent code).  (For gcc, that would be
+\&\f(CW\*(C`\-fpic\*(C'\fR or \f(CW\*(C`\-fPIC\*(C'\fR).  In HP-UX 11.00 or newer the linker
+error message should tell the name of the offending object file.
+.PP
+A more general approach is to intervene manually, as with an example for
+the DB_File module, which requires SleepyCat's libdb.sl:
+.PP
+.Vb 7
+\&  # cd .../db\-3.2.9/build_unix
+\&  # vi Makefile
+\&  ... add +Z to all cflags to create shared objects
+\&  CFLAGS=         \-c $(CPPFLAGS) +Z \-Ae +O2 +Onolimit \e
+\&                  \-I/usr/local/include \-I/usr/include/X11R6
+\&  CXXFLAGS=       \-c $(CPPFLAGS) +Z \-Ae +O2 +Onolimit \e
+\&                  \-I/usr/local/include \-I/usr/include/X11R6
+\&
+\&  # make clean
+\&  # make
+\&  # mkdir tmp
+\&  # cd tmp
+\&  # ar x ../libdb.a
+\&  # ld \-b \-o libdb\-3.2.sl *.o
+\&  # mv libdb\-3.2.sl /usr/local/lib
+\&  # rm *.o
+\&  # cd /usr/local/lib
+\&  # rm \-f libdb.sl
+\&  # ln \-s libdb\-3.2.sl libdb.sl
+\&
+\&  # cd .../DB_File\-1.76
+\&  # make distclean
+\&  # perl Makefile.PL
+\&  # make
+\&  # make test
+\&  # make install
+.Ve
+.PP
+As of db\-4.2.x it is no longer needed to do this by hand. Sleepycat
+has changed the configuration process to add +z on HP-UX automatically.
+.PP
+.Vb 2
+\&  # cd .../db\-4.2.25/build_unix
+\&  # env CFLAGS=+DD64 LDFLAGS=+DD64 ../dist/configure
+.Ve
+.PP
+should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.
+.PP
+It is no longer possible to link PA-RISC 1.0 shared libraries (even
+though the command-line flags are still present).
+.PP
+PA-RISC and Itanium object files are not interchangeable.  Although
+you may be able to use ar to create an archive library of PA-RISC
+object files on an Itanium system, you cannot link against it using
+an Itanium link editor.
+.SS "The HP ANSI C Compiler"
+.IX Subsection "The HP ANSI C Compiler"
+When using this compiler to build Perl, you should make sure that the
+flag \-Aa is added to the cpprun and cppstdin variables in the config.sh
+file (though see the section on 64\-bit perl below). If you are using a
+recent version of the Perl distribution, these flags are set automatically.
+.PP
+Even though HP-UX 10.20 and 11.00 are not actively maintained by HP
+anymore, updates for the HP ANSI C compiler are still available from
+time to time, and it might be advisable to see if updates are applicable.
+At the moment of writing, the latests available patches for 11.00 that
+should be applied are PHSS_35098, PHSS_35175, PHSS_35100, PHSS_33036,
+and PHSS_33902). If you have a SUM account, you can use it to search
+for updates/patches. Enter "ANSI" as keyword.
+.SS "The GNU C Compiler"
+.IX Subsection "The GNU C Compiler"
+When you are going to use the GNU C compiler (gcc), and you don't have
+gcc yet, you can either build it yourself (if you feel masochistic enough)
+from the sources (available from e.g. <http://gcc.gnu.org/mirrors.html>)
+or fetch a prebuilt binary from the HP porting center at
+<http://hpux.connect.org.uk/hppd/cgi\-bin/search?term=gcc&Search=Search>
+or from the DSPP (you need to be a member) at
+<http://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=2a08725cc2f02110725cc2f02110275d6e10RCRD&jumpid=reg_r1002_usen_c\-001_title_r0001>
+(Browse through the list, because there are often multiple versions of
+the same package available).
+.PP
+Most mentioned distributions are depots. H.Merijn Brand has made prebuilt
+gcc binaries available on <http://mirrors.develooper.com/hpux/> and/or
+<http://www.cmve.net/~merijn/> for HP-UX 10.20 (only 32bit), HP-UX 11.00,
+HP-UX 11.11 (HP-UX 11i v1), and HP-UX 11.23 (HP-UX 11i v2 PA-RISC) in both
+32\- and 64\-bit versions. For HP-UX 11.23 IPF and HP-UX 11.31 IPF depots are
+available too. The IPF versions do not need two versions of GNU gcc.
+.PP
+On PA-RISC you need a different compiler for 32\-bit applications and for
+64\-bit applications. On PA-RISC, 32\-bit objects and 64\-bit objects do
+not mix. Period. There is no different behaviour for HP C\-ANSI-C or GNU
+gcc. So if you require your perl binary to use 64\-bit libraries, like
+Oracle\-64bit, you MUST build a 64\-bit perl.
+.PP
+Building a 64\-bit capable gcc on PA-RISC from source is possible only when
+you have the HP C\-ANSI C compiler or an already working 64\-bit binary of
+gcc available. Best performance for perl is achieved with HP's native
+compiler.
+.SS "Using Large Files with Perl on HP-UX"
+.IX Subsection "Using Large Files with Perl on HP-UX"
+Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
+may be created and manipulated.  Three separate methods of doing this
+are available.  Of these methods, the best method for Perl is to compile
+using the \-Duselargefiles flag to Configure.  This causes Perl to be
+compiled using structures and functions in which these are 64 bits wide,
+rather than 32 bits wide.  (Note that this will only work with HP's ANSI
+C compiler.  If you want to compile Perl using gcc, you will have to get
+a version of the compiler that supports 64\-bit operations. See above for
+where to find it.)
+.PP
+There are some drawbacks to this approach.  One is that any extension
+which calls any file-manipulating C function will need to be recompiled
+(just follow the usual "perl Makefile.PL; make; make test; make install"
+procedure).
+.PP
+The list of functions that will need to recompiled is:
+  creat,          fgetpos,        fopen,
+  freopen,        fsetpos,        fstat,
+  fstatvfs,       fstatvfsdev,    ftruncate,
+  ftw,            lockf,          lseek,
+  lstat,          mmap,           nftw,
+  open,           prealloc,       stat,
+  statvfs,        statvfsdev,     tmpfile,
+  truncate,       getrlimit,      setrlimit
+.PP
+Another drawback is only valid for Perl versions before 5.6.0.  This
+drawback is that the seek and tell functions (both the builtin version
+and POSIX module version) will not perform correctly.
+.PP
+It is strongly recommended that you use this flag when you run
+Configure.  If you do not do this, but later answer the question about
+large files when Configure asks you, you may get a configuration that
+cannot be compiled, or that does not function as expected.
+.SS "Threaded Perl on HP-UX"
+.IX Subsection "Threaded Perl on HP-UX"
+It is possible to compile a version of threaded Perl on any version of
+HP-UX before 10.30, but it is strongly suggested that you be running on
+HP-UX 11.00 at least.
+.PP
+To compile Perl with threads, add \-Dusethreads to the arguments of
+Configure.  Verify that the \-D_POSIX_C_SOURCE=199506L compiler flag is
+automatically added to the list of flags.  Also make sure that \-lpthread
+is listed before \-lc in the list of libraries to link Perl with. The
+hints provided for HP-UX during Configure will try very hard to get
+this right for you.
+.PP
+HP-UX versions before 10.30 require a separate installation of a POSIX
+threads library package. Two examples are the HP DCE package, available
+on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
+April 1999 (B3920\-13941)" or the Freely available PTH package, available
+on H.Merijn's site (<http://mirrors.develooper.com/hpux/>). The use of PTH
+will be unsupported in perl\-5.12 and up and is rather buggy in 5.11.x.
+.PP
+If you are going to use the HP DCE package, the library used for threading
+is /usr/lib/libcma.sl, but there have been multiple updates of that
+library over time. Perl will build with the first version, but it
+will not pass the test suite. Older Oracle versions might be a compelling
+reason not to update that library, otherwise please find a newer version
+in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672
+.PP
+reformatted output:
+.PP
+.Vb 10
+\&  d3:/usr/lib 106 > what libcma\-*.1
+\&  libcma\-00000.1:
+\&     HP DCE/9000 1.5               Module: libcma.sl (Export)
+\&                                   Date: Apr 29 1996 22:11:24
+\&  libcma\-19739.1:
+\&     HP DCE/9000 1.5 PHSS_19739\-40 Module: libcma.sl (Export)
+\&                                   Date: Sep  4 1999 01:59:07
+\&  libcma\-20608.1:
+\&     HP DCE/9000 1.5 PHSS_20608    Module: libcma.1 (Export)
+\&                                   Date: Dec  8 1999 18:41:23
+\&  libcma\-23672.1:
+\&     HP DCE/9000 1.5 PHSS_23672    Module: libcma.1 (Export)
+\&                                   Date: Apr  9 2001 10:01:06
+\&  d3:/usr/lib 107 >
+.Ve
+.PP
+If you choose for the PTH package, use swinstall to install pth in
+the default location (/opt/pth), and then make symbolic links to the
+libraries from /usr/lib
+.PP
+.Vb 2
+\&  # cd /usr/lib
+\&  # ln \-s /opt/pth/lib/libpth* .
+.Ve
+.PP
+For building perl to support Oracle, it needs to be linked with libcl
+and libpthread. So even if your perl is an unthreaded build, these
+libraries might be required. See "Oracle on HP-UX" below.
+.SS "64\-bit Perl on HP-UX"
+.IX Subsection "64-bit Perl on HP-UX"
+Beginning with HP-UX 11.00, programs compiled under HP-UX can take
+advantage of the LP64 programming environment (LP64 means Longs and
+Pointers are 64 bits wide), in which scalar variables will be able
+to hold numbers larger than 2^32 with complete precision.  Perl has
+proven to be consistent and reliable in 64bit mode since 5.8.1 on
+all HP-UX 11.xx.
+.PP
+As of the date of this document, Perl is fully 64\-bit compliant on
+HP-UX 11.00 and up for both cc\- and gcc builds. If you are about to
+build a 64\-bit perl with GNU gcc, please read the gcc section carefully.
+.PP
+Should a user have the need for compiling Perl in the LP64 environment,
+use the \-Duse64bitall flag to Configure.  This will force Perl to be
+compiled in a pure LP64 environment (with the +DD64 flag for HP C\-ANSI-C,
+with no additional options for GNU gcc 64\-bit on PA-RISC, and with
+\&\-mlp64 for GNU gcc on Itanium).
+If you want to compile Perl using gcc, you will have to get a version of
+the compiler that supports 64\-bit operations.)
+.PP
+You can also use the \-Duse64bitint flag to Configure.  Although there
+are some minor differences between compiling Perl with this flag versus
+the \-Duse64bitall flag, they should not be noticeable from a Perl user's
+perspective. When configuring \-Duse64bitint using a 64bit gcc on a
+pa-risc architecture, \-Duse64bitint is silently promoted to \-Duse64bitall.
+.PP
+In both cases, it is strongly recommended that you use these flags when
+you run Configure.  If you do not use do this, but later answer the
+questions about 64\-bit numbers when Configure asks you, you may get a
+configuration that cannot be compiled, or that does not function as
+expected.
+.SS "Oracle on HP-UX"
+.IX Subsection "Oracle on HP-UX"
+Using perl to connect to Oracle databases through DBI and DBD::Oracle
+has caused a lot of people many headaches. Read README.hpux in the
+DBD::Oracle for much more information. The reason to mention it here
+is that Oracle requires a perl built with libcl and libpthread, the
+latter even when perl is build without threads. Building perl using
+all defaults, but still enabling to build DBD::Oracle later on can be
+achieved using
+.PP
+.Vb 1
+\&  Configure \-A prepend:libswanted=\*(Aqcl pthread \*(Aq ...
+.Ve
+.PP
+Do not forget the space before the trailing quote.
+.PP
+Also note that this does not (yet) work with all configurations,
+it is known to fail with 64\-bit versions of GCC.
+.SS "GDBM and Threads on HP-UX"
+.IX Subsection "GDBM and Threads on HP-UX"
+If you attempt to compile Perl with (POSIX) threads on an 11.X system
+and also link in the GDBM library, then Perl will immediately core dump
+when it starts up.  The only workaround at this point is to relink the
+GDBM library under 11.X, then relink it into Perl.
+.PP
+the error might show something like:
+.PP
+Pthread internal error: message: _\|\fB_libc_reinit()\fR failed, file: ../pthreads/pthread.c, line: 1096
+Return Pointer is 0xc082bf33
+sh: 5345 Quit(coredump)
+.PP
+and Configure will give up.
+.SS "NFS filesystems and \fButime\fP\|(2) on HP-UX"
+.IX Subsection "NFS filesystems and utime on HP-UX"
+If you are compiling Perl on a remotely-mounted NFS filesystem, the test
+io/fs.t may fail on test #18.  This appears to be a bug in HP-UX and no
+fix is currently available.
+.SS "HP-UX Kernel Parameters (maxdsiz) for Compiling Perl"
+.IX Subsection "HP-UX Kernel Parameters (maxdsiz) for Compiling Perl"
+By default, HP-UX comes configured with a maximum data segment size of
+64MB.  This is too small to correctly compile Perl with the maximum
+optimization levels.  You can increase the size of the maxdsiz kernel
+parameter through the use of SAM.
+.PP
+When using the GUI version of SAM, click on the Kernel Configuration
+icon, then the Configurable Parameters icon.  Scroll down and select
+the maxdsiz line.  From the Actions menu, select the Modify Configurable
+Parameter item.  Insert the new formula into the Formula/Value box.
+Then follow the instructions to rebuild your kernel and reboot your
+system.
+.PP
+In general, a value of 256MB (or "256*1024*1024") is sufficient for
+Perl to compile at maximum optimization.
+.SH "nss_delete core dump from op/pwent or op/grent"
+.IX Header "nss_delete core dump from op/pwent or op/grent"
+You may get a bus error core dump from the op/pwent or op/grent
+tests. If compiled with \-g you will see a stack trace much like
+the following:
+.PP
+.Vb 10
+\&  #0  0xc004216c in  () from /usr/lib/libc.2
+\&  #1  0xc00d7550 in _\|_nss_src_state_destr () from /usr/lib/libc.2
+\&  #2  0xc00d7768 in _\|_nss_src_state_destr () from /usr/lib/libc.2
+\&  #3  0xc00d78a8 in nss_delete () from /usr/lib/libc.2
+\&  #4  0xc01126d8 in endpwent () from /usr/lib/libc.2
+\&  #5  0xd1950 in Perl_pp_epwent () from ./perl
+\&  #6  0x94d3c in Perl_runops_standard () from ./perl
+\&  #7  0x23728 in S_run_body () from ./perl
+\&  #8  0x23428 in perl_run () from ./perl
+\&  #9  0x2005c in main () from ./perl
+.Ve
+.PP
+The key here is the \f(CW\*(C`nss_delete\*(C'\fR call.  One workaround for this
+bug seems to be to create add to the file \fI/etc/nsswitch.conf\fR
+(at least) the following lines
+.PP
+.Vb 2
+\&  group: files
+\&  passwd: files
+.Ve
+.PP
+Whether you are using NIS does not matter.  Amazingly enough,
+the same bug also affects Solaris.
+.SH "error: pasting "")"" and ""l"" does not give a valid preprocessing token"
+.IX Header "error: pasting "")"" and ""l"" does not give a valid preprocessing token"
+There seems to be a broken system header file in HP-UX 11.00 that
+breaks perl building in 32bit mode with GNU gcc\-4.x causing this
+error. The same file for HP-UX 11.11 (even though the file is older)
+does not show this failure, and has the correct definition, so the
+best fix is to patch the header to match:
+.PP
+.Vb 9
+\& \-\-\- /usr/include/inttypes.h  2001\-04\-20 18:42:14 +0200
+\& +++ /usr/include/inttypes.h  2000\-11\-14 09:00:00 +0200
+\& @@ \-72,7 +72,7 @@
+\&  #define UINT32_C(_\|_c)                   _\|_CONCAT_U_\|_(_\|_c)
+\&  #else /* _\|_LP64 */
+\&  #define INT32_C(_\|_c)                    _\|_CONCAT_\|_(_\|_c,l)
+\& \-#define UINT32_C(_\|_c)                   _\|_CONCAT_\|_(_\|_CONCAT_U_\|_(_\|_c),l)
+\& +#define UINT32_C(_\|_c)                   _\|_CONCAT_\|_(_\|_c,ul)
+\&  #endif /* _\|_LP64 */
+\&
+\&  #define INT64_C(_\|_c)                    _\|_CONCAT_L_\|_(_\|_c,l)
+.Ve
+.SH "Redeclaration of ""sendpath"" with a different storage class specifier"
+.IX Header "Redeclaration of ""sendpath"" with a different storage class specifier"
+The following compilation warnings may happen in HP-UX releases
+earlier than 11.31 but are harmless:
+.PP
+.Vb 6
+\& cc: "/usr/include/sys/socket.h", line 535: warning 562:
+\&    Redeclaration of "sendfile" with a different storage class
+\&    specifier: "sendfile" will have internal linkage.
+\& cc: "/usr/include/sys/socket.h", line 536: warning 562:
+\&    Redeclaration of "sendpath" with a different storage class
+\&    specifier: "sendpath" will have internal linkage.
+.Ve
+.PP
+They seem to be caused by broken system header files, and also other
+open source projects are seeing them.  The following HP-UX patches
+should make the warnings go away:
+.PP
+.Vb 2
+\&  CR JAGae12001: PHNE_27063
+\&  Warning 562 on sys/socket.h due to redeclaration of prototypes
+\&
+\&  CR JAGae16787:
+\&  Warning 562 from socket.h sendpath/sendfile \-D_FILEFFSET_BITS=64
+\&
+\&  CR JAGae73470 (11.23)
+\&  ER: Compiling socket.h with cc \-D_FILEFFSET_BITS=64 warning 267/562
+.Ve
+.SH Miscellaneous
+.IX Header "Miscellaneous"
+HP-UX 11 Y2K patch "Y2K\-1100 B.11.00.B0125 HP-UX Core OS Year 2000
+Patch Bundle" has been reported to break the io/fs test #18 which
+tests whether \fButime()\fR can change timestamps.  The Y2K patch seems to
+break \fButime()\fR so that over NFS the timestamps do not get changed
+(on local filesystems \fButime()\fR still works). This has probably been
+fixed on your system by now.
+.SH AUTHOR
+.IX Header "AUTHOR"
+H.Merijn Brand <h.m.brand@xs4all.nl>
+Jeff Okamoto <okamoto@corp.hp.com>
+.PP
+With much assistance regarding shared libraries from Marc Sabatella.
diff --git a/upstream/mageia-cauldron/man1/perlhurd.1 b/upstream/mageia-cauldron/man1/perlhurd.1
new file mode 100644
index 00000000..c0ba082c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlhurd.1
@@ -0,0 +1,110 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHURD 1"
+.TH PERLHURD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlhurd \- Perl version 5 on Hurd
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+If you want to use Perl on the Hurd, I recommend using the Debian
+GNU/Hurd distribution ( see <https://www.debian.org/> ), even if an
+official, stable release has not yet been made.  The old "gnu\-0.2"
+binary distribution will most certainly have additional problems.
+.SS "Known Problems with Perl on Hurd"
+.IX Subsection "Known Problems with Perl on Hurd"
+The Perl test suite may still report some errors on the Hurd.  The
+"lib/anydbm" and "pragma/warnings" tests will almost certainly fail.
+Both failures are not really specific to the Hurd, as indicated by the
+test suite output.
+.PP
+The socket tests may fail if the network is not configured.  You have
+to make "/hurd/pfinet" the translator for "/servers/socket/2", giving
+it the right arguments.  Try "/hurd/pfinet \-\-help" for more
+information.
+.PP
+Here are the statistics for Perl 5.005_62 on my system:
+.PP
+.Vb 4
+\& Failed Test  Status Wstat Total Fail  Failed  List of failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& lib/anydbm.t                 12    1   8.33%  12
+\& pragma/warnings             333    1   0.30%  215
+\&
+\& 8 tests and 24 subtests skipped.
+\& Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed,
+\&     99.98% okay.
+.Ve
+.PP
+There are quite a few systems out there that do worse!
+.PP
+However, since I am running a very recent Hurd snapshot, in which a lot of
+bugs that were exposed by the Perl test suite have been fixed, you may
+encounter more failures.  Likely candidates are: "op/stat", "lib/io_pipe",
+"lib/io_sock", "lib/io_udp" and "lib/time".
+.PP
+In any way, if you're seeing failures beyond those mentioned in this
+document, please consider upgrading to the latest Hurd before reporting
+the failure as a bug.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Mark Kettenis <kettenis@gnu.org>
+.PP
+Last Updated: Fri, 29 Oct 1999 22:50:30 +0200
diff --git a/upstream/mageia-cauldron/man1/perlintern.1 b/upstream/mageia-cauldron/man1/perlintern.1
new file mode 100644
index 00000000..38f268a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlintern.1
@@ -0,0 +1,5045 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLINTERN 1"
+.TH PERLINTERN 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlintern \- autogenerated documentation of purely internal
+Perl functions
+.SH DESCRIPTION
+.IX Xref "internal Perl functions interpreter functions"
+.IX Header "DESCRIPTION"
+This file is the autogenerated documentation of functions in the
+Perl interpreter that are documented using Perl's internal documentation
+format but are not marked as part of the Perl API.  In other words,
+\&\fBthey are not for use in extensions\fR!
+.PP
+It has the same sections as perlapi, though some may be empty.
+.SH "AV Handling"
+.IX Header "AV Handling"
+.ie n .IP """av_fetch_simple""" 4
+.el .IP \f(CWav_fetch_simple\fR 4
+.IX Xref "av_fetch_simple"
+.IX Item "av_fetch_simple"
+This is a cut-down version of av_fetch that assumes that the array is
+very straightforward \- no magic, not readonly, and AvREAL \- and that
+\&\f(CW\*(C`key\*(C'\fR is not negative. This function MUST NOT be used in situations
+where any of those assumptions may not hold.
+.Sp
+Returns the SV at the specified index in the array.  The \f(CW\*(C`key\*(C'\fR is the
+index.  If lval is true, you are guaranteed to get a real SV back (in case
+it wasn't real before), which you can then modify.  Check that the return
+value is non-null before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR.
+.Sp
+The rough perl equivalent is \f(CW$myarray[$key]\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  av_fetch_simple(AV *av, SSize_t key, I32 lval)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """AvFILLp""" 4
+.el .IP \f(CWAvFILLp\fR 4
+.IX Xref "AvFILLp"
+.IX Item "AvFILLp"
+If the array \f(CW\*(C`av\*(C'\fR is empty, this returns \-1; otherwise it returns the maximum
+value of the indices of all the array elements which are currently defined in
+\&\f(CW\*(C`av\*(C'\fR.  It does not handle magic, hence the \f(CW\*(C`p\*(C'\fR private indication in its name.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  AvFILLp(AV* av)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_new_alloc""" 4
+.el .IP \f(CWav_new_alloc\fR 4
+.IX Xref "av_new_alloc"
+.IX Item "av_new_alloc"
+This implements "\f(CW\*(C`newAV_alloc_x\*(C'\fR" in perlapi
+and "\f(CW\*(C`newAV_alloc_xz\*(C'\fR" in perlapi, which are the public API for this
+functionality.
+.Sp
+Creates a new AV and allocates its SV* array.
+.Sp
+This is similar to, but more efficient than doing:
+.Sp
+.Vb 2
+\&    AV *av = newAV();
+\&    av_extend(av, key);
+.Ve
+.Sp
+The size parameter is used to pre-allocate a SV* array large enough to
+hold at least elements \f(CW\*(C`0..(size\-1)\*(C'\fR.  \f(CW\*(C`size\*(C'\fR must be at least 1.
+.Sp
+The \f(CW\*(C`zeroflag\*(C'\fR parameter controls whether or not the array is NULL
+initialized.
+.RS 4
+.Sp
+.Vb 1
+\& AV *  av_new_alloc(SSize_t size, bool zeroflag)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """av_store_simple""" 4
+.el .IP \f(CWav_store_simple\fR 4
+.IX Xref "av_store_simple"
+.IX Item "av_store_simple"
+This is a cut-down version of av_store that assumes that the array is
+very straightforward \- no magic, not readonly, and AvREAL \- and that
+\&\f(CW\*(C`key\*(C'\fR is not negative. This function MUST NOT be used in situations
+where any of those assumptions may not hold.
+.Sp
+Stores an SV in an array.  The array index is specified as \f(CW\*(C`key\*(C'\fR. It
+can be dereferenced to get the \f(CW\*(C`SV*\*(C'\fR that was stored there (= \f(CW\*(C`val\*(C'\fR)).
+.Sp
+Note that the caller is responsible for suitably incrementing the reference
+count of \f(CW\*(C`val\*(C'\fR before the call.
+.Sp
+Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& SV **  av_store_simple(AV *av, SSize_t key, SV *val)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Callback Functions"
+.IX Header "Callback Functions"
+.ie n .IP """dowantarray""" 4
+.el .IP \f(CWdowantarray\fR 4
+.IX Xref "dowantarray"
+.IX Item "dowantarray"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`dowantarray\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Implements the deprecated "\f(CW\*(C`GIMME\*(C'\fR" in perlapi.
+.RS 4
+.Sp
+.Vb 1
+\& U8  dowantarray()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """leave_scope""" 4
+.el .IP \f(CWleave_scope\fR 4
+.IX Xref "leave_scope"
+.IX Item "leave_scope"
+Implements \f(CW\*(C`LEAVE_SCOPE\*(C'\fR which you should use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  leave_scope(I32 base)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """magic_freedestruct""" 4
+.el .IP \f(CWmagic_freedestruct\fR 4
+.IX Xref "magic_freedestruct"
+.IX Item "magic_freedestruct"
+This function is called via magic to implement the
+\&\f(CWmortal_destructor_sv()\fR and \f(CWmortal_destructor_x()\fR functions. It
+should not be called directly and has no user servicable parts.
+.RS 4
+.Sp
+.Vb 1
+\& int  magic_freedestruct(SV *sv, MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mortal_svfunc_x""" 4
+.el .IP \f(CWmortal_svfunc_x\fR 4
+.IX Xref "mortal_svfunc_x"
+.IX Item "mortal_svfunc_x"
+This function arranges for a C function reference to be called at the
+\&\fBend of the current statement\fR with the arguments provided. It is a
+wrapper around \f(CWmortal_destructor_sv()\fR which ensures that the latter
+function is called appropriately.
+.Sp
+Be aware that there is a signficant difference in timing between the
+\&\fIend of the current statement\fR and the \fIend of the current pseudo
+block\fR. If you are looking for a mechanism to trigger a function at the
+end of the \fBcurrent pseudo block\fR you should look at
+\&\f(CWSAVEDESTRUCTORX()\fR instead of this function.
+.RS 4
+.Sp
+.Vb 1
+\& void  mortal_svfunc_x(SVFUNC_t f, SV *p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pop_scope""" 4
+.el .IP \f(CWpop_scope\fR 4
+.IX Xref "pop_scope"
+.IX Item "pop_scope"
+Implements "\f(CW\*(C`LEAVE\*(C'\fR" in perlapi
+.RS 4
+.Sp
+.Vb 1
+\& void  pop_scope()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """push_scope""" 4
+.el .IP \f(CWpush_scope\fR 4
+.IX Xref "push_scope"
+.IX Item "push_scope"
+Implements "\f(CW\*(C`ENTER\*(C'\fR" in perlapi
+.RS 4
+.Sp
+.Vb 1
+\& void  push_scope()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_adelete""" 4
+.el .IP \f(CWsave_adelete\fR 4
+.IX Xref "save_adelete"
+.IX Item "save_adelete"
+Implements \f(CW\*(C`SAVEADELETE\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_adelete(AV *av, SSize_t key)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_freercpv""" 4
+.el .IP \f(CWsave_freercpv\fR 4
+.IX Xref "save_freercpv"
+.IX Item "save_freercpv"
+Implements \f(CW\*(C`SAVEFREERCPV\*(C'\fR.
+.Sp
+Saves and frees a refcounted string. Calls \fBrcpv_free()\fR
+on the argument when the current pseudo block is finished.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_freercpv(char *rcpv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_generic_pvref""" 4
+.el .IP \f(CWsave_generic_pvref\fR 4
+.IX Xref "save_generic_pvref"
+.IX Item "save_generic_pvref"
+Implements \f(CW\*(C`SAVEGENERICPV\*(C'\fR.
+.Sp
+Like \fBsave_pptr()\fR, but also \fBSafefree()\fRs the new value if it is different
+from the old one.  Can be used to restore a global char* to its prior
+contents, freeing new value.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_generic_pvref(char **str)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_generic_svref""" 4
+.el .IP \f(CWsave_generic_svref\fR 4
+.IX Xref "save_generic_svref"
+.IX Item "save_generic_svref"
+Implements \f(CW\*(C`SAVEGENERICSV\*(C'\fR.
+.Sp
+Like \fBsave_sptr()\fR, but also \fBSvREFCNT_dec()\fRs the new value.  Can be used to
+restore a global SV to its prior contents, freeing new value.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_generic_svref(SV **sptr)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_hdelete""" 4
+.el .IP \f(CWsave_hdelete\fR 4
+.IX Xref "save_hdelete"
+.IX Item "save_hdelete"
+Implements \f(CW\*(C`SAVEHDELETE\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_hdelete(HV *hv, SV *keysv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_hints""" 4
+.el .IP \f(CWsave_hints\fR 4
+.IX Xref "save_hints"
+.IX Item "save_hints"
+Implements \f(CW\*(C`SAVEHINTS\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_hints()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_op""" 4
+.el .IP \f(CWsave_op\fR 4
+.IX Xref "save_op"
+.IX Item "save_op"
+Implements \f(CW\*(C`SAVEOP\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_op()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_padsv_and_mortalize""" 4
+.el .IP \f(CWsave_padsv_and_mortalize\fR 4
+.IX Xref "save_padsv_and_mortalize"
+.IX Item "save_padsv_and_mortalize"
+Implements \f(CW\*(C`SAVEPADSVANDMORTALIZE\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_padsv_and_mortalize(PADOFFSET off)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_pushptr""" 4
+.el .IP \f(CWsave_pushptr\fR 4
+.IX Xref "save_pushptr"
+.IX Item "save_pushptr"
+The refcnt of object \f(CW\*(C`ptr\*(C'\fR will be decremented at the end of the current
+\&\fIpseudo-block\fR.  \f(CW\*(C`type\*(C'\fR gives the type of \f(CW\*(C`ptr\*(C'\fR, expressed as one of the
+constants in \fIscope.h\fR whose name begins with \f(CW\*(C`SAVEt_\*(C'\fR.
+.Sp
+This is the underlying implementation of several macros, like
+\&\f(CW\*(C`SAVEFREESV\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_pushptr(void * const ptr, const int type)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_rcpv""" 4
+.el .IP \f(CWsave_rcpv\fR 4
+.IX Xref "save_rcpv"
+.IX Item "save_rcpv"
+Implements \f(CW\*(C`SAVERCPV\*(C'\fR.
+.Sp
+Saves and restores a refcounted string, similar to what
+save_generic_svref would do for a SV*. Can be used to restore
+a refcounted string to its previous state. Performs the 
+appropriate refcount counting so that nothing should leak
+or be prematurely freed.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_rcpv(char **prcpv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_scalar_at""" 4
+.el .IP \f(CWsave_scalar_at\fR 4
+.IX Xref "save_scalar_at"
+.IX Item "save_scalar_at"
+A helper function for localizing the SV referenced by \f(CW*sptr\fR.
+.Sp
+If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is set in in \f(CW\*(C`flags\*(C'\fR, the function returns the input
+scalar untouched.
+.Sp
+Otherwise it replaces \f(CW*sptr\fR with a new \f(CW\*(C`undef\*(C'\fR scalar, and returns that.
+The new scalar will have the old one's magic (if any) copied to it.
+If there is such magic, and \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR is set in in \f(CW\*(C`flags\*(C'\fR, 'set'
+magic will be processed on the new scalar.  If unset, 'set' magic will be
+skipped.  The latter typically means that assignment will soon follow (\fIe.g.\fR,
+\&\f(CW\*(Aqlocal\ $x\ =\ $y\*(Aq\fR), and that will handle the magic.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  save_scalar_at(SV **sptr, const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_set_svflags""" 4
+.el .IP \f(CWsave_set_svflags\fR 4
+.IX Xref "save_set_svflags"
+.IX Item "save_set_svflags"
+Implements \f(CW\*(C`SAVESETSVFLAGS\*(C'\fR.
+.Sp
+Set the SvFLAGS specified by mask to the values in val
+.RS 4
+.Sp
+.Vb 1
+\& void  save_set_svflags(SV *sv, U32 mask, U32 val)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_shared_pvref""" 4
+.el .IP \f(CWsave_shared_pvref\fR 4
+.IX Xref "save_shared_pvref"
+.IX Item "save_shared_pvref"
+Implements \f(CW\*(C`SAVESHAREDPV\*(C'\fR.
+.Sp
+Like \fBsave_generic_pvref()\fR, but uses \fBPerlMemShared_free()\fR rather than \fBSafefree()\fR.
+Can be used to restore a shared global char* to its prior
+contents, freeing new value.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_shared_pvref(char **str)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """save_vptr""" 4
+.el .IP \f(CWsave_vptr\fR 4
+.IX Xref "save_vptr"
+.IX Item "save_vptr"
+Implements \f(CW\*(C`SAVEVPTR\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  save_vptr(void *ptr)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Casting
+.IX Xref "NUM2PTR"
+.IX Header "Casting"
+There are currently no internal API items in Casting
+.SH "Character case changing"
+.IX Header "Character case changing"
+There are currently no internal API items in Character case changing
+.SH "Character classification"
+.IX Header "Character classification"
+There are currently no internal API items in Character classification
+.SH "Compiler and Preprocessor information"
+.IX Header "Compiler and Preprocessor information"
+There are currently no internal API items in Compiler and Preprocessor information
+.SH "Compiler directives"
+.IX Header "Compiler directives"
+There are currently no internal API items in Compiler directives
+.SH "Compile-time scope hooks"
+.IX Header "Compile-time scope hooks"
+.ie n .IP """BhkENTRY""" 4
+.el .IP \f(CWBhkENTRY\fR 4
+.IX Xref "BhkENTRY"
+.IX Item "BhkENTRY"
+NOTE: \f(CW\*(C`BhkENTRY\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Return an entry from the BHK structure.  \f(CW\*(C`which\*(C'\fR is a preprocessor token
+indicating which entry to return.  If the appropriate flag is not set
+this will return \f(CW\*(C`NULL\*(C'\fR.  The type of the return value depends on which
+entry you ask for.
+.RS 4
+.Sp
+.Vb 1
+\& void *  BhkENTRY(BHK *hk, token which)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """BhkFLAGS""" 4
+.el .IP \f(CWBhkFLAGS\fR 4
+.IX Xref "BhkFLAGS"
+.IX Item "BhkFLAGS"
+NOTE: \f(CW\*(C`BhkFLAGS\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Return the BHK's flags.
+.RS 4
+.Sp
+.Vb 1
+\& U32  BhkFLAGS(BHK *hk)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CALL_BLOCK_HOOKS""" 4
+.el .IP \f(CWCALL_BLOCK_HOOKS\fR 4
+.IX Xref "CALL_BLOCK_HOOKS"
+.IX Item "CALL_BLOCK_HOOKS"
+NOTE: \f(CW\*(C`CALL_BLOCK_HOOKS\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Call all the registered block hooks for type \f(CW\*(C`which\*(C'\fR.  \f(CW\*(C`which\*(C'\fR is a
+preprocessing token; the type of \f(CW\*(C`arg\*(C'\fR depends on \f(CW\*(C`which\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  CALL_BLOCK_HOOKS(token which, arg)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Concurrency
+.IX Header "Concurrency"
+.ie n .IP """CVf_SLABBED""" 4
+.el .IP \f(CWCVf_SLABBED\fR 4
+.IX Item "CVf_SLABBED"
+.PD 0
+.ie n .IP """CvROOT""" 4
+.el .IP \f(CWCvROOT\fR 4
+.IX Item "CvROOT"
+.ie n .IP """CvSTART""" 4
+.el .IP \f(CWCvSTART\fR 4
+.IX Item "CvSTART"
+.PD
+Described in perlguts.
+.ie n .IP """CX_CUR""" 4
+.el .IP \f(CWCX_CUR\fR 4
+.IX Item "CX_CUR"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\&   CX_CUR()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CXINC""" 4
+.el .IP \f(CWCXINC\fR 4
+.IX Item "CXINC"
+Described in perlguts.
+.ie n .IP """CX_LEAVE_SCOPE""" 4
+.el .IP \f(CWCX_LEAVE_SCOPE\fR 4
+.IX Item "CX_LEAVE_SCOPE"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  CX_LEAVE_SCOPE(PERL_CONTEXT* cx)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CX_POP""" 4
+.el .IP \f(CWCX_POP\fR 4
+.IX Item "CX_POP"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  CX_POP(PERL_CONTEXT* cx)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cxstack""" 4
+.el .IP \f(CWcxstack\fR 4
+.IX Item "cxstack"
+Described in perlguts.
+.ie n .IP """cxstack_ix""" 4
+.el .IP \f(CWcxstack_ix\fR 4
+.IX Item "cxstack_ix"
+Described in perlguts.
+.ie n .IP """CXt_BLOCK""" 4
+.el .IP \f(CWCXt_BLOCK\fR 4
+.IX Item "CXt_BLOCK"
+.PD 0
+.ie n .IP """CXt_EVAL""" 4
+.el .IP \f(CWCXt_EVAL\fR 4
+.IX Item "CXt_EVAL"
+.ie n .IP """CXt_FORMAT""" 4
+.el .IP \f(CWCXt_FORMAT\fR 4
+.IX Item "CXt_FORMAT"
+.ie n .IP """CXt_GIVEN""" 4
+.el .IP \f(CWCXt_GIVEN\fR 4
+.IX Item "CXt_GIVEN"
+.ie n .IP """CXt_LOOP_ARY""" 4
+.el .IP \f(CWCXt_LOOP_ARY\fR 4
+.IX Item "CXt_LOOP_ARY"
+.ie n .IP """CXt_LOOP_LAZYIV""" 4
+.el .IP \f(CWCXt_LOOP_LAZYIV\fR 4
+.IX Item "CXt_LOOP_LAZYIV"
+.ie n .IP """CXt_LOOP_LAZYSV""" 4
+.el .IP \f(CWCXt_LOOP_LAZYSV\fR 4
+.IX Item "CXt_LOOP_LAZYSV"
+.ie n .IP """CXt_LOOP_LIST""" 4
+.el .IP \f(CWCXt_LOOP_LIST\fR 4
+.IX Item "CXt_LOOP_LIST"
+.ie n .IP """CXt_LOOP_PLAIN""" 4
+.el .IP \f(CWCXt_LOOP_PLAIN\fR 4
+.IX Item "CXt_LOOP_PLAIN"
+.ie n .IP """CXt_NULL""" 4
+.el .IP \f(CWCXt_NULL\fR 4
+.IX Item "CXt_NULL"
+.ie n .IP """CXt_SUB""" 4
+.el .IP \f(CWCXt_SUB\fR 4
+.IX Item "CXt_SUB"
+.ie n .IP """CXt_SUBST""" 4
+.el .IP \f(CWCXt_SUBST\fR 4
+.IX Item "CXt_SUBST"
+.ie n .IP """CXt_WHEN""" 4
+.el .IP \f(CWCXt_WHEN\fR 4
+.IX Item "CXt_WHEN"
+.PD
+Described in perlguts.
+.ie n .IP """cx_type""" 4
+.el .IP \f(CWcx_type\fR 4
+.IX Item "cx_type"
+Described in perlguts.
+.ie n .IP """dounwind""" 4
+.el .IP \f(CWdounwind\fR 4
+.IX Item "dounwind"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& void  dounwind(I32 cxix)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_fork""" 4
+.el .IP \f(CWmy_fork\fR 4
+.IX Xref "my_fork"
+.IX Item "my_fork"
+This is for the use of \f(CW\*(C`PerlProc_fork\*(C'\fR as a wrapper for the C library
+\&\fBfork\fR\|(2) on some platforms to hide some platform quirks.  It should not be
+used except through \f(CW\*(C`PerlProc_fork\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& Pid_t  my_fork()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PERL_CONTEXT""" 4
+.el .IP \f(CWPERL_CONTEXT\fR 4
+.IX Item "PERL_CONTEXT"
+Described in perlguts.
+.SH "COPs and Hint Hashes"
+.IX Header "COPs and Hint Hashes"
+There are currently no internal API items in COPs and Hint Hashes
+.SH "Custom Operators"
+.IX Header "Custom Operators"
+.ie n .IP """core_prototype""" 4
+.el .IP \f(CWcore_prototype\fR 4
+.IX Xref "core_prototype"
+.IX Item "core_prototype"
+This function assigns the prototype of the named core function to \f(CW\*(C`sv\*(C'\fR, or
+to a new mortal SV if \f(CW\*(C`sv\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR.  It returns the modified \f(CW\*(C`sv\*(C'\fR, or
+\&\f(CW\*(C`NULL\*(C'\fR if the core function has no prototype.  \f(CW\*(C`code\*(C'\fR is a code as returned
+by \f(CWkeyword()\fR.  It must not be equal to 0.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  core_prototype(SV *sv, const char *name, const int code,
+\&                      int * const opnum)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "CV Handling"
+.IX Header "CV Handling"
+.ie n .IP """CvREFCOUNTED_ANYSV""" 4
+.el .IP \f(CWCvREFCOUNTED_ANYSV\fR 4
+.IX Xref "CvREFCOUNTED_ANYSV"
+.IX Item "CvREFCOUNTED_ANYSV"
+If true, indicates that the \f(CW\*(C`CvXSUBANY(cv).any_sv\*(C'\fR member contains an SV
+pointer whose reference count should be decremented when the CV itself is
+freed.  In addition, \f(CWcv_clone()\fR will increment the reference count, and
+\&\f(CWsv_dup()\fR will duplicate the entire pointed-to SV if this flag is set.
+.Sp
+Any CV that wraps an XSUB has an \f(CW\*(C`ANY\*(C'\fR union that the XSUB function is free
+to use for its own purposes.  It may be the case that the code wishes to store
+an SV in the \f(CW\*(C`any_sv\*(C'\fR member of this union.  By setting this flag, this SV
+reference will be properly reclaimed or duplicated when the CV itself is.
+.RS 4
+.Sp
+.Vb 1
+\& bool  CvREFCOUNTED_ANYSV(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvREFCOUNTED_ANYSV_off""" 4
+.el .IP \f(CWCvREFCOUNTED_ANYSV_off\fR 4
+.IX Xref "CvREFCOUNTED_ANYSV_off"
+.IX Item "CvREFCOUNTED_ANYSV_off"
+Helper macro to turn off the \f(CW\*(C`CvREFCOUNTED_ANYSV\*(C'\fR flag.
+.RS 4
+.Sp
+.Vb 1
+\& void  CvREFCOUNTED_ANYSV_off(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvREFCOUNTED_ANYSV_on""" 4
+.el .IP \f(CWCvREFCOUNTED_ANYSV_on\fR 4
+.IX Xref "CvREFCOUNTED_ANYSV_on"
+.IX Item "CvREFCOUNTED_ANYSV_on"
+Helper macro to turn on the \f(CW\*(C`CvREFCOUNTED_ANYSV\*(C'\fR flag.
+.RS 4
+.Sp
+.Vb 1
+\& void  CvREFCOUNTED_ANYSV_on(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CvWEAKOUTSIDE""" 4
+.el .IP \f(CWCvWEAKOUTSIDE\fR 4
+.IX Xref "CvWEAKOUTSIDE"
+.IX Item "CvWEAKOUTSIDE"
+Each CV has a pointer, \f(CWCvOUTSIDE()\fR, to its lexically enclosing
+CV (if any).  Because pointers to anonymous sub prototypes are
+stored in \f(CW\*(C`&\*(C'\fR pad slots, it is a possible to get a circular reference,
+with the parent pointing to the child and vice-versa.  To avoid the
+ensuing memory leak, we do not increment the reference count of the CV
+pointed to by \f(CW\*(C`CvOUTSIDE\*(C'\fR in the \fIone specific instance\fR that the parent
+has a \f(CW\*(C`&\*(C'\fR pad slot pointing back to us.  In this case, we set the
+\&\f(CW\*(C`CvWEAKOUTSIDE\*(C'\fR flag in the child.  This allows us to determine under what
+circumstances we should decrement the refcount of the parent when freeing
+the child.
+.Sp
+There is a further complication with non-closure anonymous subs (i.e. those
+that do not refer to any lexicals outside that sub).  In this case, the
+anonymous prototype is shared rather than being cloned.  This has the
+consequence that the parent may be freed while there are still active
+children, \fIe.g.\fR,
+.Sp
+.Vb 1
+\&    BEGIN { $a = sub { eval \*(Aq$x\*(Aq } }
+.Ve
+.Sp
+In this case, the BEGIN is freed immediately after execution since there
+are no active references to it: the anon sub prototype has
+\&\f(CW\*(C`CvWEAKOUTSIDE\*(C'\fR set since it's not a closure, and \f(CW$a\fR points to the same
+CV, so it doesn't contribute to BEGIN's refcount either.  When \f(CW$a\fR is
+executed, the \f(CW\*(C`eval \*(Aq$x\*(Aq\*(C'\fR causes the chain of \f(CW\*(C`CvOUTSIDE\*(C'\fRs to be followed,
+and the freed BEGIN is accessed.
+.Sp
+To avoid this, whenever a CV and its associated pad is freed, any
+\&\f(CW\*(C`&\*(C'\fR entries in the pad are explicitly removed from the pad, and if the
+refcount of the pointed-to anon sub is still positive, then that
+child's \f(CW\*(C`CvOUTSIDE\*(C'\fR is set to point to its grandparent.  This will only
+occur in the single specific case of a non-closure anon prototype
+having one or more active references (such as \f(CW$a\fR above).
+.Sp
+One other thing to consider is that a CV may be merely undefined
+rather than freed, eg \f(CW\*(C`undef &foo\*(C'\fR.  In this case, its refcount may
+not have reached zero, but we still delete its pad and its \f(CW\*(C`CvROOT\*(C'\fR etc.
+Since various children may still have their \f(CW\*(C`CvOUTSIDE\*(C'\fR pointing at this
+undefined CV, we keep its own \f(CW\*(C`CvOUTSIDE\*(C'\fR for the time being, so that
+the chain of lexical scopes is unbroken.  For example, the following
+should print 123:
+.Sp
+.Vb 5
+\&    my $x = 123;
+\&    sub tmp { sub { eval \*(Aq$x\*(Aq } }
+\&    my $a = tmp();
+\&    undef &tmp;
+\&    print  $a\->();
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& bool  CvWEAKOUTSIDE(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """docatch""" 4
+.el .IP \f(CWdocatch\fR 4
+.IX Xref "docatch"
+.IX Item "docatch"
+Interpose, for the current op and RUNOPS loop,
+.Sp
+.Vb 3
+\&    \- a new JMPENV stack catch frame, and
+\&    \- an inner RUNOPS loop to run all the remaining ops following the
+\&      current PL_op.
+.Ve
+.Sp
+Then handle any exceptions raised while in that loop.
+For a caught eval at this level, re-enter the loop with the specified
+restart op (i.e. the op following the OP_LEAVETRY etc); otherwise re-throw
+the exception.
+.Sp
+\&\fBdocatch()\fR is intended to be used like this:
+.Sp
+.Vb 4
+\&    PP(pp_entertry)
+\&    {
+\&        if (CATCH_GET)
+\&            return docatch(Perl_pp_entertry);
+\&
+\&        ... rest of function ...
+\&        return PL_op\->op_next;
+\&    }
+.Ve
+.Sp
+If a new catch frame isn't needed, the op behaves normally. Otherwise it
+calls \fBdocatch()\fR, which recursively calls \fBpp_entertry()\fR, this time with
+\&\fBCATCH_GET()\fR false, so the rest of the body of the entertry is run. Then
+\&\fBdocatch()\fR calls \fBCALLRUNOPS()\fR which executes all the ops following the
+entertry. When the loop finally finishes, control returns to \fBdocatch()\fR,
+which pops the JMPENV and returns to the parent \fBpp_entertry()\fR, which
+itself immediately returns. Note that *all* subsequent ops are run within
+the inner RUNOPS loop, not just the body of the eval. For example, in
+.Sp
+.Vb 2
+\&    sub TIEARRAY { eval {1}; my $x }
+\&    tie @a, "main";
+.Ve
+.Sp
+at the point the 'my' is executed, the C stack will look something like:
+.Sp
+.Vb 11
+\&    #10 main()
+\&    #9  perl_run()              # JMPENV_PUSH level 1 here
+\&    #8  S_run_body()
+\&    #7  Perl_runops_standard()  # main RUNOPS loop
+\&    #6  Perl_pp_tie()
+\&    #5  Perl_call_sv()
+\&    #4  Perl_runops_standard()  # unguarded RUNOPS loop: no new JMPENV
+\&    #3  Perl_pp_entertry()
+\&    #2  S_docatch()             # JMPENV_PUSH level 2 here
+\&    #1  Perl_runops_standard()  # docatch()\*(Aqs RUNOPs loop
+\&    #0  Perl_pp_padsv()
+.Ve
+.Sp
+Basically, any section of the perl core which starts a RUNOPS loop may
+make a promise that it will catch any exceptions and restart the loop if
+necessary. If it's not prepared to do that (like \fBcall_sv()\fR isn't), then
+it sets \fBCATCH_GET()\fR to true, so that any later eval-like code knows to
+set up a new handler and loop (via \fBdocatch()\fR).
+.Sp
+See "Exception handing" in perlinterp for further details.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  docatch(Perl_ppaddr_t firstpp)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Debugging
+.IX Header "Debugging"
+.ie n .IP """comma_aDEPTH""" 4
+.el .IP \f(CWcomma_aDEPTH\fR 4
+.IX Xref "comma_aDEPTH"
+.IX Item "comma_aDEPTH"
+Some functions when compiled under DEBUGGING take an extra final argument named
+\&\f(CW\*(C`depth\*(C'\fR, indicating the C stack depth.  This argument is omitted otherwise.
+This macro expands to either \f(CW\*(C`,\ depth\*(C'\fR under DEBUGGING, or to nothing at
+all when not under DEBUGGING, reducing the number of \f(CW\*(C`#ifdef\*(C'\fR's in the code.
+.Sp
+The program is responsible for maintaining the correct value for \f(CW\*(C`depth\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   comma_aDEPTH
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """comma_pDEPTH""" 4
+.el .IP \f(CWcomma_pDEPTH\fR 4
+.IX Xref "comma_pDEPTH"
+.IX Item "comma_pDEPTH"
+This is used in the prototype declarations for functions that take a "\f(CW\*(C`comma_aDEPTH\*(C'\fR"
+final parameter, much like \f(CW\*(C`pTHX_\*(C'\fR
+is used in functions that take a thread context initial parameter.
+.ie n .IP """debop""" 4
+.el .IP \f(CWdebop\fR 4
+.IX Xref "debop"
+.IX Item "debop"
+Implements \fB\-Dt\fR perl command line option on OP \f(CW\*(C`o\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& I32  debop(const OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """debprof""" 4
+.el .IP \f(CWdebprof\fR 4
+.IX Xref "debprof"
+.IX Item "debprof"
+Called to indicate that \f(CW\*(C`o\*(C'\fR was executed, for profiling purposes under the
+\&\f(CW\*(C`\-DP\*(C'\fR command line option.
+.RS 4
+.Sp
+.Vb 1
+\& void  debprof(const OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """debprofdump""" 4
+.el .IP \f(CWdebprofdump\fR 4
+.IX Xref "debprofdump"
+.IX Item "debprofdump"
+Dumps the contents of the data collected by the \f(CW\*(C`\-DP\*(C'\fR perl command line
+option.
+.RS 4
+.Sp
+.Vb 1
+\& void  debprofdump()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """debug_aDEPTH""" 4
+.el .IP \f(CWdebug_aDEPTH\fR 4
+.IX Xref "debug_aDEPTH"
+.IX Item "debug_aDEPTH"
+Same as "\f(CW\*(C`comma_aDEPTH\*(C'\fR" but with no leading argument. Intended for functions with
+no normal arguments, and used by "\f(CW\*(C`comma_aDEPTH\*(C'\fR" itself.
+.RS 4
+.Sp
+.Vb 1
+\&   debug_aDEPTH
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """debug_pDEPTH""" 4
+.el .IP \f(CWdebug_pDEPTH\fR 4
+.IX Xref "debug_pDEPTH"
+.IX Item "debug_pDEPTH"
+Same as "\f(CW\*(C`comma_pDEPTH\*(C'\fR" but with no leading argument. Intended for functions with
+no normal arguments, and used by "\f(CW\*(C`comma_pDEPTH\*(C'\fR" itself.
+.RS 4
+.Sp
+.Vb 1
+\&   debug_pDEPTH
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """free_c_backtrace""" 4
+.el .IP \f(CWfree_c_backtrace\fR 4
+.IX Xref "free_c_backtrace"
+.IX Item "free_c_backtrace"
+Deallocates a backtrace received from get_c_backtrace.
+.RS 4
+.Sp
+.Vb 1
+\& void  free_c_backtrace(Perl_c_backtrace *bt)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_c_backtrace""" 4
+.el .IP \f(CWget_c_backtrace\fR 4
+.IX Xref "get_c_backtrace"
+.IX Item "get_c_backtrace"
+Collects the backtrace (aka "stacktrace") into a single linear
+malloced buffer, which the caller \fBmust\fR \f(CWPerl_free_c_backtrace()\fR.
+.Sp
+Scans the frames back by \f(CW\*(C`depth\ +\ skip\*(C'\fR, then drops the \f(CW\*(C`skip\*(C'\fR innermost,
+returning at most \f(CW\*(C`depth\*(C'\fR frames.
+.RS 4
+.Sp
+.Vb 1
+\& Perl_c_backtrace *  get_c_backtrace(int max_depth, int skip)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_DBsingle""" 4
+.el .IP \f(CWPL_DBsingle\fR 4
+.IX Xref "PL_DBsingle"
+.IX Item "PL_DBsingle"
+When Perl is run in debugging mode, with the \fB\-d\fR switch, this SV is a
+boolean which indicates whether subs are being single-stepped.
+Single-stepping is automatically turned on after every step.  This is the C
+variable which corresponds to Perl's \f(CW$DB::single\fR variable.  See
+\&\f(CW"PL_DBsub"\fR.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PL_DBsingle
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_DBsub""" 4
+.el .IP \f(CWPL_DBsub\fR 4
+.IX Xref "PL_DBsub"
+.IX Item "PL_DBsub"
+When Perl is run in debugging mode, with the \fB\-d\fR switch, this GV contains
+the SV which holds the name of the sub being debugged.  This is the C
+variable which corresponds to Perl's \f(CW$DB::sub\fR variable.  See
+\&\f(CW"PL_DBsingle"\fR.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& GV *  PL_DBsub
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_DBtrace""" 4
+.el .IP \f(CWPL_DBtrace\fR 4
+.IX Xref "PL_DBtrace"
+.IX Item "PL_DBtrace"
+Trace variable used when Perl is run in debugging mode, with the \fB\-d\fR
+switch.  This is the C variable which corresponds to Perl's \f(CW$DB::trace\fR
+variable.  See \f(CW"PL_DBsingle"\fR.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PL_DBtrace
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """runops_debug""" 4
+.el .IP \f(CWrunops_debug\fR 4
+.IX Item "runops_debug"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& int  runops_debug()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """runops_standard""" 4
+.el .IP \f(CWrunops_standard\fR 4
+.IX Item "runops_standard"
+Described in perlguts.
+.RS 4
+.Sp
+.Vb 1
+\& int  runops_standard()
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Display functions"
+.IX Xref "PERL_PV_PRETTY_DUMP PERL_PV_PRETTY_NOCLEAR PERL_PV_PRETTY_REGPROP"
+.IX Header "Display functions"
+.ie n .IP """sv_peek""" 4
+.el .IP \f(CWsv_peek\fR 4
+.IX Xref "sv_peek"
+.IX Item "sv_peek"
+Implements \f(CW\*(C`SvPEEK\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_peek(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Embedding, Threads, and Interpreter Cloning"
+.IX Header "Embedding, Threads, and Interpreter Cloning"
+.ie n .IP """cv_dump""" 4
+.el .IP \f(CWcv_dump\fR 4
+.IX Xref "cv_dump"
+.IX Item "cv_dump"
+dump the contents of a CV
+.RS 4
+.Sp
+.Vb 1
+\& void  cv_dump(const CV *cv, const char *title)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """cv_forget_slab""" 4
+.el .IP \f(CWcv_forget_slab\fR 4
+.IX Xref "cv_forget_slab"
+.IX Item "cv_forget_slab"
+When a CV has a reference count on its slab (\f(CW\*(C`CvSLABBED\*(C'\fR), it is responsible
+for making sure it is freed.  (Hence, no two CVs should ever have a
+reference count on the same slab.)  The CV only needs to reference the slab
+during compilation.  Once it is compiled and \f(CW\*(C`CvROOT\*(C'\fR attached, it has
+finished its job, so it can forget the slab.
+.RS 4
+.Sp
+.Vb 1
+\& void  cv_forget_slab(CV *cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """do_dump_pad""" 4
+.el .IP \f(CWdo_dump_pad\fR 4
+.IX Xref "do_dump_pad"
+.IX Item "do_dump_pad"
+Dump the contents of a padlist
+.RS 4
+.Sp
+.Vb 2
+\& void  do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist,
+\&                   int full)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """get_context""" 4
+.el .IP \f(CWget_context\fR 4
+.IX Xref "get_context"
+.IX Item "get_context"
+Implements "\f(CW\*(C`PERL_GET_CONTEXT\*(C'\fR" in perlapi, which you should use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void *  get_context()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_alloc_name""" 4
+.el .IP \f(CWpad_alloc_name\fR 4
+.IX Xref "pad_alloc_name"
+.IX Item "pad_alloc_name"
+Allocates a place in the currently-compiling
+pad (via "pad_alloc" in perlapi) and
+then stores a name for that entry.  \f(CW\*(C`name\*(C'\fR is adopted and
+becomes the name entry; it must already contain the name
+string.  \f(CW\*(C`typestash\*(C'\fR and \f(CW\*(C`ourstash\*(C'\fR and the \f(CW\*(C`padadd_STATE\*(C'\fR
+flag get added to \f(CW\*(C`name\*(C'\fR.  None of the other
+processing of "pad_add_name_pvn" in perlapi
+is done.  Returns the offset of the allocated pad slot.
+.RS 4
+.Sp
+.Vb 2
+\& PADOFFSET  pad_alloc_name(PADNAME *name, U32 flags, HV *typestash,
+\&                           HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_block_start""" 4
+.el .IP \f(CWpad_block_start\fR 4
+.IX Xref "pad_block_start"
+.IX Item "pad_block_start"
+Update the pad compilation state variables on entry to a new block.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_block_start(int full)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_check_dup""" 4
+.el .IP \f(CWpad_check_dup\fR 4
+.IX Xref "pad_check_dup"
+.IX Item "pad_check_dup"
+Check for duplicate declarations: report any of:
+.Sp
+.Vb 3
+\&     * a \*(Aqmy\*(Aq in the current scope with the same name;
+\&     * an \*(Aqour\*(Aq (anywhere in the pad) with the same name and the
+\&       same stash as \*(Aqourstash\*(Aq
+.Ve
+.Sp
+\&\f(CW\*(C`is_our\*(C'\fR indicates that the name to check is an \f(CW"our"\fR declaration.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_check_dup(PADNAME *name, U32 flags, const HV *ourstash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_findlex""" 4
+.el .IP \f(CWpad_findlex\fR 4
+.IX Xref "pad_findlex"
+.IX Item "pad_findlex"
+Find a named lexical anywhere in a chain of nested pads.  Add fake entries
+in the inner pads if it's found in an outer one.
+.Sp
+Returns the offset in the bottom pad of the lex or the fake lex.
+\&\f(CW\*(C`cv\*(C'\fR is the CV in which to start the search, and seq is the current \f(CW\*(C`cop_seq\*(C'\fR
+to match against.  If \f(CW\*(C`warn\*(C'\fR is true, print appropriate warnings.  The \f(CW\*(C`out_\*(C'\fR*
+vars return values, and so are pointers to where the returned values
+should be stored.  \f(CW\*(C`out_capture\*(C'\fR, if non-null, requests that the innermost
+instance of the lexical is captured; \f(CW\*(C`out_name\*(C'\fR is set to the innermost
+matched pad name or fake pad name; \f(CW\*(C`out_flags\*(C'\fR returns the flags normally
+associated with the \f(CW\*(C`PARENT_FAKELEX_FLAGS\*(C'\fR field of a fake pad name.
+.Sp
+Note that \f(CWpad_findlex()\fR is recursive; it recurses up the chain of CVs,
+then comes back down, adding fake entries
+as it goes.  It has to be this way
+because fake names in anon prototypes have to store in \f(CW\*(C`xpadn_low\*(C'\fR the
+index into the parent pad.
+.RS 4
+.Sp
+.Vb 4
+\& PADOFFSET  pad_findlex(const char *namepv, STRLEN namelen,
+\&                        U32 flags, const CV *cv, U32 seq, int warn,
+\&                        SV **out_capture, PADNAME **out_name,
+\&                        int *out_flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_fixup_inner_anons""" 4
+.el .IP \f(CWpad_fixup_inner_anons\fR 4
+.IX Xref "pad_fixup_inner_anons"
+.IX Item "pad_fixup_inner_anons"
+For any anon CVs in the pad, change \f(CW\*(C`CvOUTSIDE\*(C'\fR of that CV from
+\&\f(CW\*(C`old_cv\*(C'\fR to \f(CW\*(C`new_cv\*(C'\fR if necessary.  Needed when a newly-compiled CV has to be
+moved to a pre-existing CV struct.
+.RS 4
+.Sp
+.Vb 2
+\& void  pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv,
+\&                             CV *new_cv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_free""" 4
+.el .IP \f(CWpad_free\fR 4
+.IX Xref "pad_free"
+.IX Item "pad_free"
+Free the SV at offset po in the current pad.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_free(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_leavemy""" 4
+.el .IP \f(CWpad_leavemy\fR 4
+.IX Xref "pad_leavemy"
+.IX Item "pad_leavemy"
+Cleanup at end of scope during compilation: set the max seq number for
+lexicals in this scope and warn of any lexicals that never got introduced.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  pad_leavemy()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """padlist_dup""" 4
+.el .IP \f(CWpadlist_dup\fR 4
+.IX Xref "padlist_dup"
+.IX Item "padlist_dup"
+Duplicates a pad.
+.RS 4
+.Sp
+.Vb 1
+\& PADLIST *  padlist_dup(PADLIST *srcpad, CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """padname_dup""" 4
+.el .IP \f(CWpadname_dup\fR 4
+.IX Xref "padname_dup"
+.IX Item "padname_dup"
+Duplicates a pad name.
+.RS 4
+.Sp
+.Vb 1
+\& PADNAME *  padname_dup(PADNAME *src, CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """padnamelist_dup""" 4
+.el .IP \f(CWpadnamelist_dup\fR 4
+.IX Xref "padnamelist_dup"
+.IX Item "padnamelist_dup"
+Duplicates a pad name list.
+.RS 4
+.Sp
+.Vb 2
+\& PADNAMELIST *  padnamelist_dup(PADNAMELIST *srcpad,
+\&                                CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_push""" 4
+.el .IP \f(CWpad_push\fR 4
+.IX Xref "pad_push"
+.IX Item "pad_push"
+Push a new pad frame onto the padlist, unless there's already a pad at
+this depth, in which case don't bother creating a new one.  Then give
+the new pad an \f(CW@_\fR in slot zero.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_push(PADLIST *padlist, int depth)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_reset""" 4
+.el .IP \f(CWpad_reset\fR 4
+.IX Xref "pad_reset"
+.IX Item "pad_reset"
+Mark all the current temporaries for reuse
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_reset()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_setsv""" 4
+.el .IP \f(CWpad_setsv\fR 4
+.IX Xref "pad_setsv"
+.IX Item "pad_setsv"
+Set the value at offset \f(CW\*(C`po\*(C'\fR in the current (compiling or executing) pad.
+Use the macro \f(CWPAD_SETSV()\fR rather than calling this function directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_setsv(PADOFFSET po, SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_sv""" 4
+.el .IP \f(CWpad_sv\fR 4
+.IX Xref "pad_sv"
+.IX Item "pad_sv"
+Get the value at offset \f(CW\*(C`po\*(C'\fR in the current (compiling or executing) pad.
+Use macro \f(CW\*(C`PAD_SV\*(C'\fR instead of calling this function directly.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  pad_sv(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """pad_swipe""" 4
+.el .IP \f(CWpad_swipe\fR 4
+.IX Xref "pad_swipe"
+.IX Item "pad_swipe"
+Abandon the tmp in the current pad at offset \f(CW\*(C`po\*(C'\fR and replace with a
+new one.
+.RS 4
+.Sp
+.Vb 1
+\& void  pad_swipe(PADOFFSET po, bool refadjust)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """set_context""" 4
+.el .IP \f(CWset_context\fR 4
+.IX Xref "set_context"
+.IX Item "set_context"
+Implements "\f(CW\*(C`PERL_SET_CONTEXT\*(C'\fR" in perlapi, which you should use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  set_context(void *t)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """si_dup""" 4
+.el .IP \f(CWsi_dup\fR 4
+.IX Xref "si_dup"
+.IX Item "si_dup"
+Duplicate a stack info structure, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 1
+\& PERL_SI *  si_dup(PERL_SI *si, CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """ss_dup""" 4
+.el .IP \f(CWss_dup\fR 4
+.IX Xref "ss_dup"
+.IX Item "ss_dup"
+Duplicate the save stack, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 1
+\& ANY *  ss_dup(PerlInterpreter *proto_perl, CLONE_PARAMS *param)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Errno
+.IX Header "Errno"
+.ie n .IP """dSAVEDERRNO""" 4
+.el .IP \f(CWdSAVEDERRNO\fR 4
+.IX Xref "dSAVEDERRNO"
+.IX Item "dSAVEDERRNO"
+Declare variables needed to save \f(CW\*(C`errno\*(C'\fR and any operating system
+specific error number.
+.RS 4
+.Sp
+.Vb 1
+\& void  dSAVEDERRNO
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """dSAVE_ERRNO""" 4
+.el .IP \f(CWdSAVE_ERRNO\fR 4
+.IX Xref "dSAVE_ERRNO"
+.IX Item "dSAVE_ERRNO"
+Declare variables needed to save \f(CW\*(C`errno\*(C'\fR and any operating system
+specific error number, and save them for optional later restoration
+by \f(CW\*(C`RESTORE_ERRNO\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  dSAVE_ERRNO
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """RESTORE_ERRNO""" 4
+.el .IP \f(CWRESTORE_ERRNO\fR 4
+.IX Xref "RESTORE_ERRNO"
+.IX Item "RESTORE_ERRNO"
+Restore \f(CW\*(C`errno\*(C'\fR and any operating system specific error number that
+was saved by \f(CW\*(C`dSAVE_ERRNO\*(C'\fR or \f(CW\*(C`RESTORE_ERRNO\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  RESTORE_ERRNO
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVE_ERRNO""" 4
+.el .IP \f(CWSAVE_ERRNO\fR 4
+.IX Xref "SAVE_ERRNO"
+.IX Item "SAVE_ERRNO"
+Save \f(CW\*(C`errno\*(C'\fR and any operating system specific error number for
+optional later restoration by \f(CW\*(C`RESTORE_ERRNO\*(C'\fR.  Requires
+\&\f(CW\*(C`dSAVEDERRNO\*(C'\fR or \f(CW\*(C`dSAVE_ERRNO\*(C'\fR in scope.
+.RS 4
+.Sp
+.Vb 1
+\& void  SAVE_ERRNO
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SETERRNO""" 4
+.el .IP \f(CWSETERRNO\fR 4
+.IX Xref "SETERRNO"
+.IX Item "SETERRNO"
+Set \f(CW\*(C`errno\*(C'\fR, and on VMS set \f(CW\*(C`vaxc$errno\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  SETERRNO(int errcode, int vmserrcode)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Exception Handling (simple) Macros"
+.IX Header "Exception Handling (simple) Macros"
+There are currently no internal API items in Exception Handling (simple) Macros
+.SH "Filesystem configuration values"
+.IX Header "Filesystem configuration values"
+There are currently no internal API items in Filesystem configuration values
+.SH "Floating point"
+.IX Header "Floating point"
+There are currently no internal API items in Floating point
+.SH "General Configuration"
+.IX Header "General Configuration"
+There are currently no internal API items in General Configuration
+.SH "Global Variables"
+.IX Header "Global Variables"
+There are currently no internal API items in Global Variables
+.SH "GV Handling and Stashes"
+.IX Xref "GV_CACHE_ONLY"
+.IX Header "GV Handling and Stashes"
+.ie n .IP """amagic_applies""" 4
+.el .IP \f(CWamagic_applies\fR 4
+.IX Xref "amagic_applies"
+.IX Item "amagic_applies"
+Check \f(CW\*(C`sv\*(C'\fR to see if the overloaded (active magic) operation \f(CW\*(C`method\*(C'\fR
+applies to it. If the sv is not SvROK or it is not an object then returns
+false, otherwise checks if the object is blessed into a class supporting
+overloaded operations, and returns true if a call to \fBamagic_call()\fR with
+this SV and the given method would trigger an amagic operation, including
+via the overload fallback rules or via nomethod. Thus a call like:
+.Sp
+.Vb 1
+\&    amagic_applies(sv, string_amg, AMG_unary)
+.Ve
+.Sp
+would return true for an object with overloading set up in any of the
+following ways:
+.Sp
+.Vb 2
+\&    use overload q("") => sub { ... };
+\&    use overload q(0+) => sub { ... }, fallback => 1;
+.Ve
+.Sp
+and could be used to tell if a given object would stringify to something
+other than the normal default ref stringification.
+.Sp
+Note that the fact that this function returns TRUE does not mean you
+can succesfully perform the operation with \fBamagic_call()\fR, for instance
+any overloaded method might throw a fatal exception,  however if this
+function returns FALSE you can be confident that it will NOT perform
+the given overload operation.
+.Sp
+\&\f(CW\*(C`method\*(C'\fR is an integer enum, one of the values found in \fIoverload.h\fR,
+for instance \f(CW\*(C`string_amg\*(C'\fR.
+.Sp
+\&\f(CW\*(C`flags\*(C'\fR should be set to AMG_unary for unary operations.
+.RS 4
+.Sp
+.Vb 1
+\& bool  amagic_applies(SV *sv, int method, int flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gp_dup""" 4
+.el .IP \f(CWgp_dup\fR 4
+.IX Xref "gp_dup"
+.IX Item "gp_dup"
+Duplicate a typeglob, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 1
+\& GP *  gp_dup(GP * const gp, CLONE_PARAMS * const param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_handler""" 4
+.el .IP \f(CWgv_handler\fR 4
+.IX Xref "gv_handler"
+.IX Item "gv_handler"
+Implements \f(CW\*(C`StashHANDLER\*(C'\fR, which you should use instead
+.RS 4
+.Sp
+.Vb 1
+\& CV *  gv_handler(HV *stash, I32 id)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_stashsvpvn_cached""" 4
+.el .IP \f(CWgv_stashsvpvn_cached\fR 4
+.IX Xref "gv_stashsvpvn_cached"
+.IX Item "gv_stashsvpvn_cached"
+Returns a pointer to the stash for a specified package, possibly
+cached.  Implements both "\f(CW\*(C`gv_stashpvn\*(C'\fR" in perlapi and
+"\f(CW\*(C`gv_stashsv\*(C'\fR" in perlapi.
+.Sp
+Requires one of either \f(CW\*(C`namesv\*(C'\fR or \f(CW\*(C`namepv\*(C'\fR to be non-null.
+.Sp
+If the flag \f(CW\*(C`GV_CACHE_ONLY\*(C'\fR is set, return the stash only if found in the
+cache; see "\f(CW\*(C`gv_stashpvn\*(C'\fR" in perlapi for details on the other \f(CW\*(C`flags\*(C'\fR.
+.Sp
+Note it is strongly preferred for \f(CW\*(C`namesv\*(C'\fR to be non-null, for performance
+reasons.
+.RS 4
+.Sp
+.Vb 2
+\& HV *  gv_stashsvpvn_cached(SV *namesv, const char *name,
+\&                            U32 namelen, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """gv_try_downgrade""" 4
+.el .IP \f(CWgv_try_downgrade\fR 4
+.IX Xref "gv_try_downgrade"
+.IX Item "gv_try_downgrade"
+NOTE: \f(CW\*(C`gv_try_downgrade\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+If the typeglob \f(CW\*(C`gv\*(C'\fR can be expressed more succinctly, by having
+something other than a real GV in its place in the stash, replace it
+with the optimised form.  Basic requirements for this are that \f(CW\*(C`gv\*(C'\fR
+is a real typeglob, is sufficiently ordinary, and is only referenced
+from its package.  This function is meant to be used when a GV has been
+looked up in part to see what was there, causing upgrading, but based
+on what was found it turns out that the real GV isn't required after all.
+.Sp
+If \f(CW\*(C`gv\*(C'\fR is a completely empty typeglob, it is deleted from the stash.
+.Sp
+If \f(CW\*(C`gv\*(C'\fR is a typeglob containing only a sufficiently-ordinary constant
+sub, the typeglob is replaced with a scalar-reference placeholder that
+more compactly represents the same thing.
+.RS 4
+.Sp
+.Vb 1
+\& void  gv_try_downgrade(GV *gv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Hook manipulation"
+.IX Header "Hook manipulation"
+There are currently no internal API items in Hook manipulation
+.SH "HV Handling"
+.IX Xref "HvNAME_get"
+.IX Header "HV Handling"
+.ie n .IP """hv_eiter_p""" 4
+.el .IP \f(CWhv_eiter_p\fR 4
+.IX Xref "hv_eiter_p"
+.IX Item "hv_eiter_p"
+Implements \f(CW\*(C`HvEITER\*(C'\fR which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_eiter_p\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_eiter_p\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& HE **  Perl_hv_eiter_p(pTHX_ HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_eiter_set""" 4
+.el .IP \f(CWhv_eiter_set\fR 4
+.IX Xref "hv_eiter_set"
+.IX Item "hv_eiter_set"
+Implements \f(CW\*(C`HvEITER_set\*(C'\fR which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_eiter_set\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_eiter_set\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_hv_eiter_set(pTHX_ HV *hv, HE *eiter)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_ename_add""" 4
+.el .IP \f(CWhv_ename_add\fR 4
+.IX Xref "hv_ename_add"
+.IX Item "hv_ename_add"
+Adds a name to a stash's internal list of effective names.  See
+\&\f(CW"hv_ename_delete"\fR.
+.Sp
+This is called when a stash is assigned to a new location in the symbol
+table.
+.RS 4
+.Sp
+.Vb 1
+\& void  hv_ename_add(HV *hv, const char *name, U32 len, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_ename_delete""" 4
+.el .IP \f(CWhv_ename_delete\fR 4
+.IX Xref "hv_ename_delete"
+.IX Item "hv_ename_delete"
+Removes a name from a stash's internal list of effective names.  If this is
+the name returned by \f(CW\*(C`HvENAME\*(C'\fR, then another name in the list will take
+its place (\f(CW\*(C`HvENAME\*(C'\fR will use it).
+.Sp
+This is called when a stash is deleted from the symbol table.
+.RS 4
+.Sp
+.Vb 2
+\& void  hv_ename_delete(HV *hv, const char *name, U32 len,
+\&                       U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_fill""" 4
+.el .IP \f(CWhv_fill\fR 4
+.IX Xref "hv_fill"
+.IX Item "hv_fill"
+Returns the number of hash buckets that happen to be in use.
+.Sp
+This function implements the \f(CW\*(C`HvFILL\*(C'\fR macro which you should
+use instead.
+.Sp
+As of perl 5.25 this function is used only for debugging
+purposes, and the number of used hash buckets is not
+in any way cached, thus this function can be costly
+to execute as it must iterate over all the buckets in the
+hash.
+.Sp
+NOTE: \f(CW\*(C`hv_fill\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_fill\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  Perl_hv_fill(pTHX_ HV * const hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_placeholders_get""" 4
+.el .IP \f(CWhv_placeholders_get\fR 4
+.IX Xref "hv_placeholders_get"
+.IX Item "hv_placeholders_get"
+Implements \f(CW\*(C`HvPLACEHOLDERS_get\*(C'\fR, which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_placeholders_get\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_placeholders_get\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& I32  Perl_hv_placeholders_get(pTHX_ const HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_placeholders_set""" 4
+.el .IP \f(CWhv_placeholders_set\fR 4
+.IX Xref "hv_placeholders_set"
+.IX Item "hv_placeholders_set"
+Implements \f(CW\*(C`HvPLACEHOLDERS_set\*(C'\fR, which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_placeholders_set\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_placeholders_set\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_hv_placeholders_set(pTHX_ HV *hv, I32 ph)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_riter_p""" 4
+.el .IP \f(CWhv_riter_p\fR 4
+.IX Xref "hv_riter_p"
+.IX Item "hv_riter_p"
+Implements \f(CW\*(C`HvRITER\*(C'\fR which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_riter_p\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_riter_p\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& I32 *  Perl_hv_riter_p(pTHX_ HV *hv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """hv_riter_set""" 4
+.el .IP \f(CWhv_riter_set\fR 4
+.IX Xref "hv_riter_set"
+.IX Item "hv_riter_set"
+Implements \f(CW\*(C`HvRITER_set\*(C'\fR which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`hv_riter_set\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_hv_riter_set\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void  Perl_hv_riter_set(pTHX_ HV *hv, I32 riter)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_chain_2hv""" 4
+.el .IP \f(CWrefcounted_he_chain_2hv\fR 4
+.IX Xref "refcounted_he_chain_2hv"
+.IX Item "refcounted_he_chain_2hv"
+Generates and returns a \f(CW\*(C`HV *\*(C'\fR representing the content of a
+\&\f(CW\*(C`refcounted_he\*(C'\fR chain.
+\&\f(CW\*(C`flags\*(C'\fR is currently unused and must be zero.
+.RS 4
+.Sp
+.Vb 2
+\& HV *  refcounted_he_chain_2hv(const struct refcounted_he *c,
+\&                               U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_fetch_pv""" 4
+.el .IP \f(CWrefcounted_he_fetch_pv\fR 4
+.IX Xref "refcounted_he_fetch_pv"
+.IX Item "refcounted_he_fetch_pv"
+Like "refcounted_he_fetch_pvn", but takes a nul-terminated string
+instead of a string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  refcounted_he_fetch_pv(const struct refcounted_he *chain,
+\&                              const char *key, U32 hash, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_fetch_pvn""" 4
+.el .IP \f(CWrefcounted_he_fetch_pvn\fR 4
+.IX Xref "refcounted_he_fetch_pvn"
+.IX Item "refcounted_he_fetch_pvn"
+Search along a \f(CW\*(C`refcounted_he\*(C'\fR chain for an entry with the key specified
+by \f(CW\*(C`keypv\*(C'\fR and \f(CW\*(C`keylen\*(C'\fR.  If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`REFCOUNTED_HE_KEY_UTF8\*(C'\fR
+bit set, the key octets are interpreted as UTF\-8, otherwise they
+are interpreted as Latin\-1.  \f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key
+string, or zero if it has not been precomputed.  Returns a mortal scalar
+representing the value associated with the key, or \f(CW&PL_sv_placeholder\fR
+if there is no value associated with the key.
+.RS 4
+.Sp
+.Vb 3
+\& SV *  refcounted_he_fetch_pvn(const struct refcounted_he *chain,
+\&                               const char *keypv, STRLEN keylen,
+\&                               U32 hash, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_fetch_pvs""" 4
+.el .IP \f(CWrefcounted_he_fetch_pvs\fR 4
+.IX Xref "refcounted_he_fetch_pvs"
+.IX Item "refcounted_he_fetch_pvs"
+Like "refcounted_he_fetch_pvn", but takes a literal string
+instead of a string/length pair, and no precomputed hash.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  refcounted_he_fetch_pvs(const struct refcounted_he *chain,
+\&                               "key", U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_fetch_sv""" 4
+.el .IP \f(CWrefcounted_he_fetch_sv\fR 4
+.IX Xref "refcounted_he_fetch_sv"
+.IX Item "refcounted_he_fetch_sv"
+Like "refcounted_he_fetch_pvn", but takes a Perl scalar instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  refcounted_he_fetch_sv(const struct refcounted_he *chain,
+\&                              SV *key, U32 hash, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_free""" 4
+.el .IP \f(CWrefcounted_he_free\fR 4
+.IX Xref "refcounted_he_free"
+.IX Item "refcounted_he_free"
+Decrements the reference count of a \f(CW\*(C`refcounted_he\*(C'\fR by one.  If the
+reference count reaches zero the structure's memory is freed, which
+(recursively) causes a reduction of its parent \f(CW\*(C`refcounted_he\*(C'\fR's
+reference count.  It is safe to pass a null pointer to this function:
+no action occurs in this case.
+.RS 4
+.Sp
+.Vb 1
+\& void  refcounted_he_free(struct refcounted_he *he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_inc""" 4
+.el .IP \f(CWrefcounted_he_inc\fR 4
+.IX Xref "refcounted_he_inc"
+.IX Item "refcounted_he_inc"
+Increment the reference count of a \f(CW\*(C`refcounted_he\*(C'\fR.  The pointer to the
+\&\f(CW\*(C`refcounted_he\*(C'\fR is also returned.  It is safe to pass a null pointer
+to this function: no action occurs and a null pointer is returned.
+.RS 4
+.Sp
+.Vb 2
+\& struct refcounted_he *  refcounted_he_inc(
+\&                                          struct refcounted_he *he)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_new_pv""" 4
+.el .IP \f(CWrefcounted_he_new_pv\fR 4
+.IX Xref "refcounted_he_new_pv"
+.IX Item "refcounted_he_new_pv"
+Like "refcounted_he_new_pvn", but takes a nul-terminated string instead
+of a string/length pair.
+.RS 4
+.Sp
+.Vb 4
+\& struct refcounted_he *  refcounted_he_new_pv(
+\&                                      struct refcounted_he *parent,
+\&                                      const char *key, U32 hash,
+\&                                      SV *value, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_new_pvn""" 4
+.el .IP \f(CWrefcounted_he_new_pvn\fR 4
+.IX Xref "refcounted_he_new_pvn"
+.IX Item "refcounted_he_new_pvn"
+Creates a new \f(CW\*(C`refcounted_he\*(C'\fR.  This consists of a single key/value
+pair and a reference to an existing \f(CW\*(C`refcounted_he\*(C'\fR chain (which may
+be empty), and thus forms a longer chain.  When using the longer chain,
+the new key/value pair takes precedence over any entry for the same key
+further along the chain.
+.Sp
+The new key is specified by \f(CW\*(C`keypv\*(C'\fR and \f(CW\*(C`keylen\*(C'\fR.  If \f(CW\*(C`flags\*(C'\fR has
+the \f(CW\*(C`REFCOUNTED_HE_KEY_UTF8\*(C'\fR bit set, the key octets are interpreted
+as UTF\-8, otherwise they are interpreted as Latin\-1.  \f(CW\*(C`hash\*(C'\fR is
+a precomputed hash of the key string, or zero if it has not been
+precomputed.
+.Sp
+\&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key.  \f(CW\*(C`value\*(C'\fR is copied
+by this function, which thus does not take ownership of any reference
+to it, and later changes to the scalar will not be reflected in the
+value visible in the \f(CW\*(C`refcounted_he\*(C'\fR.  Complex types of scalar will not
+be stored with referential integrity, but will be coerced to strings.
+\&\f(CW\*(C`value\*(C'\fR may be either null or \f(CW&PL_sv_placeholder\fR to indicate that no
+value is to be associated with the key; this, as with any non-null value,
+takes precedence over the existence of a value for the key further along
+the chain.
+.Sp
+\&\f(CW\*(C`parent\*(C'\fR points to the rest of the \f(CW\*(C`refcounted_he\*(C'\fR chain to be
+attached to the new \f(CW\*(C`refcounted_he\*(C'\fR.  This function takes ownership
+of one reference to \f(CW\*(C`parent\*(C'\fR, and returns one reference to the new
+\&\f(CW\*(C`refcounted_he\*(C'\fR.
+.RS 4
+.Sp
+.Vb 5
+\& struct refcounted_he *  refcounted_he_new_pvn(
+\&                                      struct refcounted_he *parent,
+\&                                      const char *keypv,
+\&                                      STRLEN keylen, U32 hash,
+\&                                      SV *value, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_new_pvs""" 4
+.el .IP \f(CWrefcounted_he_new_pvs\fR 4
+.IX Xref "refcounted_he_new_pvs"
+.IX Item "refcounted_he_new_pvs"
+Like "refcounted_he_new_pvn", but takes a literal string
+instead of a string/length pair, and no precomputed hash.
+.RS 4
+.Sp
+.Vb 3
+\& struct refcounted_he *  refcounted_he_new_pvs(
+\&                                      struct refcounted_he *parent,
+\&                                      "key", SV *value, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """refcounted_he_new_sv""" 4
+.el .IP \f(CWrefcounted_he_new_sv\fR 4
+.IX Xref "refcounted_he_new_sv"
+.IX Item "refcounted_he_new_sv"
+Like "refcounted_he_new_pvn", but takes a Perl scalar instead of a
+string/length pair.
+.RS 4
+.Sp
+.Vb 4
+\& struct refcounted_he *  refcounted_he_new_sv(
+\&                                      struct refcounted_he *parent,
+\&                                      SV *key, U32 hash, SV *value,
+\&                                      U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """unsharepvn""" 4
+.el .IP \f(CWunsharepvn\fR 4
+.IX Xref "unsharepvn"
+.IX Item "unsharepvn"
+If no one has access to shared string \f(CW\*(C`str\*(C'\fR with length \f(CW\*(C`len\*(C'\fR, free it.
+.Sp
+\&\f(CW\*(C`len\*(C'\fR and \f(CW\*(C`hash\*(C'\fR must both be valid for \f(CW\*(C`str\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  unsharepvn(const char *sv, I32 len, U32 hash)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Input/Output
+.IX Header "Input/Output"
+.ie n .IP """dirp_dup""" 4
+.el .IP \f(CWdirp_dup\fR 4
+.IX Xref "dirp_dup"
+.IX Item "dirp_dup"
+Duplicate a directory handle, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 1
+\& DIR *  dirp_dup(DIR * const dp, CLONE_PARAMS * const param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """fp_dup""" 4
+.el .IP \f(CWfp_dup\fR 4
+.IX Xref "fp_dup"
+.IX Item "fp_dup"
+Duplicate a file handle, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 2
+\& PerlIO *  fp_dup(PerlIO * const fp, const char type,
+\&                  CLONE_PARAMS * const param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_fflush_all""" 4
+.el .IP \f(CWmy_fflush_all\fR 4
+.IX Xref "my_fflush_all"
+.IX Item "my_fflush_all"
+Implements \f(CW\*(C`PERL_FLUSHALL_FOR_CHILD\*(C'\fR on some platforms.
+.RS 4
+.Sp
+.Vb 1
+\& I32  my_fflush_all()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_mkostemp""" 4
+.el .IP \f(CWmy_mkostemp\fR 4
+.IX Xref "my_mkostemp"
+.IX Item "my_mkostemp"
+The C library \f(CWmkostemp(3)\fR if available, or a Perl implementation of it.
+.Sp
+NOTE: \f(CW\*(C`my_mkostemp\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_my_mkostemp\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& int  Perl_my_mkostemp(char *templte, int flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_mkstemp""" 4
+.el .IP \f(CWmy_mkstemp\fR 4
+.IX Xref "my_mkstemp"
+.IX Item "my_mkstemp"
+The C library \f(CWmkstemp(3)\fR if available, or a Perl implementation of it.
+.Sp
+NOTE: \f(CW\*(C`my_mkstemp\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_my_mkstemp\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& int  Perl_my_mkstemp(char *templte)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_last_in_gv""" 4
+.el .IP \f(CWPL_last_in_gv\fR 4
+.IX Xref "PL_last_in_gv"
+.IX Item "PL_last_in_gv"
+The GV which was last used for a filehandle input operation.  (\f(CW\*(C`<FH>\*(C'\fR)
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& GV*  PL_last_in_gv
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_ofsgv""" 4
+.el .IP \f(CWPL_ofsgv\fR 4
+.IX Xref "PL_ofsgv"
+.IX Item "PL_ofsgv"
+The glob containing the output field separator \- \f(CW\*(C`*,\*(C'\fR in Perl space.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& GV*  PL_ofsgv
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_rs""" 4
+.el .IP \f(CWPL_rs\fR 4
+.IX Xref "PL_rs"
+.IX Item "PL_rs"
+The input record separator \- \f(CW$/\fR in Perl space.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& SV*  PL_rs
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """start_glob""" 4
+.el .IP \f(CWstart_glob\fR 4
+.IX Xref "start_glob"
+.IX Item "start_glob"
+NOTE: \f(CW\*(C`start_glob\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Function called by \f(CW\*(C`do_readline\*(C'\fR to spawn a glob (or do the glob inside
+perl on VMS).  This code used to be inline, but now perl uses \f(CW\*(C`File::Glob\*(C'\fR
+this glob starter is only used by miniperl during the build process,
+or when PERL_EXTERNAL_GLOB is defined.
+Moving it away shrinks \fIpp_hot.c\fR; shrinking \fIpp_hot.c\fR helps speed perl up.
+.Sp
+NOTE: \f(CW\*(C`start_glob\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_start_glob\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& PerlIO *  Perl_start_glob(pTHX_ SV *tmpglob, IO *io)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Integer
+.IX Header "Integer"
+There are currently no internal API items in Integer
+.SH "I/O Formats"
+.IX Header "I/O Formats"
+There are currently no internal API items in I/O Formats
+.SH "Lexer interface"
+.IX Header "Lexer interface"
+.ie n .IP """resume_compcv_and_save""" 4
+.el .IP \f(CWresume_compcv_and_save\fR 4
+.IX Xref "resume_compcv_and_save"
+.IX Item "resume_compcv_and_save"
+Resumes a buffer previously suspended by the \f(CW\*(C`suspend_compcv\*(C'\fR function, in a
+way that will be re-suspended at the end of the scope so it can be used again
+later.  This should be used within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  resume_compcv_and_save(struct suspended_compcv *buffer)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """resume_compcv_final""" 4
+.el .IP \f(CWresume_compcv_final\fR 4
+.IX Xref "resume_compcv_final"
+.IX Item "resume_compcv_final"
+Resumes the parser state previously saved using the \f(CW\*(C`suspend_compcv\*(C'\fR function
+for a final time before being compiled into a full CV.  This should be used
+within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
+.RS 4
+.Sp
+.Vb 1
+\& void  resume_compcv_final(struct suspended_compcv *buffer)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """validate_proto""" 4
+.el .IP \f(CWvalidate_proto\fR 4
+.IX Xref "validate_proto"
+.IX Item "validate_proto"
+NOTE: \f(CW\*(C`validate_proto\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+This function performs syntax checking on a prototype, \f(CW\*(C`proto\*(C'\fR.
+If \f(CW\*(C`warn\*(C'\fR is true, any illegal characters or mismatched brackets
+will trigger illegalproto warnings, declaring that they were
+detected in the prototype for \f(CW\*(C`name\*(C'\fR.
+.Sp
+The return value is \f(CW\*(C`true\*(C'\fR if this is a valid prototype, and
+\&\f(CW\*(C`false\*(C'\fR if it is not, regardless of whether \f(CW\*(C`warn\*(C'\fR was \f(CW\*(C`true\*(C'\fR or
+\&\f(CW\*(C`false\*(C'\fR.
+.Sp
+Note that \f(CW\*(C`NULL\*(C'\fR is a valid \f(CW\*(C`proto\*(C'\fR and will always return \f(CW\*(C`true\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& bool  validate_proto(SV *name, SV *proto, bool warn,
+\&                      bool curstash)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Locales
+.IX Header "Locales"
+There are currently no internal API items in Locales
+.SH Magic
+.IX Header "Magic"
+.ie n .IP """magic_clearhint""" 4
+.el .IP \f(CWmagic_clearhint\fR 4
+.IX Xref "magic_clearhint"
+.IX Item "magic_clearhint"
+Triggered by a delete from \f(CW\*(C`%^H\*(C'\fR, records the key to
+\&\f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  magic_clearhint(SV *sv, MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """magic_clearhints""" 4
+.el .IP \f(CWmagic_clearhints\fR 4
+.IX Xref "magic_clearhints"
+.IX Item "magic_clearhints"
+Triggered by clearing \f(CW\*(C`%^H\*(C'\fR, resets \f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& int  magic_clearhints(SV *sv, MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """magic_methcall""" 4
+.el .IP \f(CWmagic_methcall\fR 4
+.IX Xref "magic_methcall"
+.IX Item "magic_methcall"
+Invoke a magic method (like FETCH).
+.Sp
+\&\f(CW\*(C`sv\*(C'\fR and \f(CW\*(C`mg\*(C'\fR are the tied thingy and the tie magic.
+.Sp
+\&\f(CW\*(C`meth\*(C'\fR is the name of the method to call.
+.Sp
+\&\f(CW\*(C`argc\*(C'\fR is the number of args (in addition to \f(CW$self\fR) to pass to the method.
+.Sp
+The \f(CW\*(C`flags\*(C'\fR can be:
+.Sp
+.Vb 4
+\&    G_DISCARD     invoke method with G_DISCARD flag and don\*(Aqt
+\&                  return a value
+\&    G_UNDEF_FILL  fill the stack with argc pointers to
+\&                  PL_sv_undef
+.Ve
+.Sp
+The arguments themselves are any values following the \f(CW\*(C`flags\*(C'\fR argument.
+.Sp
+Returns the SV (if any) returned by the method, or \f(CW\*(C`NULL\*(C'\fR on failure.
+.Sp
+NOTE: \f(CW\*(C`magic_methcall\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_magic_methcall\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 2
+\& SV *  Perl_magic_methcall(pTHX_ SV *sv, const MAGIC *mg,
+\&                           SV *meth, U32 flags, U32 argc, ...)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """magic_sethint""" 4
+.el .IP \f(CWmagic_sethint\fR 4
+.IX Xref "magic_sethint"
+.IX Item "magic_sethint"
+Triggered by a store to \f(CW\*(C`%^H\*(C'\fR, records the key/value pair to
+\&\f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR.  It is assumed that hints aren't storing
+anything that would need a deep copy.  Maybe we should warn if we find a
+reference.
+.RS 4
+.Sp
+.Vb 1
+\& int  magic_sethint(SV *sv, MAGIC *mg)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_dup""" 4
+.el .IP \f(CWmg_dup\fR 4
+.IX Xref "mg_dup"
+.IX Item "mg_dup"
+Duplicate a chain of magic, returning a pointer to the cloned object.
+.RS 4
+.Sp
+.Vb 1
+\& MAGIC *  mg_dup(MAGIC *mg, CLONE_PARAMS * const param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mg_localize""" 4
+.el .IP \f(CWmg_localize\fR 4
+.IX Xref "mg_localize"
+.IX Item "mg_localize"
+Copy some of the magic from an existing SV to new localized version of that
+SV.  Container magic (\fIe.g.\fR, \f(CW%ENV\fR, \f(CW$1\fR, \f(CW\*(C`tie\*(C'\fR)
+gets copied, value magic doesn't (\fIe.g.\fR,
+\&\f(CW\*(C`taint\*(C'\fR, \f(CW\*(C`pos\*(C'\fR).
+.Sp
+If \f(CW\*(C`setmagic\*(C'\fR is false then no set magic will be called on the new (empty) SV.
+This typically means that assignment will soon follow (e.g. \f(CW\*(Aqlocal\ $x\ =\ $y\*(Aq\fR),
+and that will handle the magic.
+.RS 4
+.Sp
+.Vb 1
+\& void  mg_localize(SV *sv, SV *nsv, bool setmagic)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Memory Management"
+.IX Header "Memory Management"
+.ie n .IP """calloc""" 4
+.el .IP \f(CWcalloc\fR 4
+.IX Xref "calloc"
+.IX Item "calloc"
+Implements "\f(CW\*(C`Newxz\*(C'\fR" in perlapi which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`calloc\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_calloc\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  Perl_calloc(MEM_SIZE elements, MEM_SIZE size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """malloc""" 4
+.el .IP \f(CWmalloc\fR 4
+.IX Xref "malloc"
+.IX Item "malloc"
+Implements "\f(CW\*(C`Newx\*(C'\fR" in perlapi which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`malloc\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_malloc\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  Perl_malloc(MEM_SIZE nbytes)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mfree""" 4
+.el .IP \f(CWmfree\fR 4
+.IX Xref "mfree"
+.IX Item "mfree"
+Implements "\f(CW\*(C`Safefree\*(C'\fR" in perlapi which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`mfree\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_mfree\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& Free_t  Perl_mfree(Malloc_t where)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """realloc""" 4
+.el .IP \f(CWrealloc\fR 4
+.IX Xref "realloc"
+.IX Item "realloc"
+Implements "\f(CW\*(C`Renew\*(C'\fR" in perlapi which you should use instead.
+.Sp
+NOTE: \f(CW\*(C`realloc\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_realloc\*(C'\fR
+\&.
+.RS 4
+.Sp
+.Vb 1
+\& Malloc_t  Perl_realloc(Malloc_t where, MEM_SIZE nbytes)
+.Ve
+.RE
+.RS 4
+.RE
+.SH MRO
+.IX Header "MRO"
+.ie n .IP """mro_get_linear_isa_dfs""" 4
+.el .IP \f(CWmro_get_linear_isa_dfs\fR 4
+.IX Xref "mro_get_linear_isa_dfs"
+.IX Item "mro_get_linear_isa_dfs"
+Returns the Depth-First Search linearization of \f(CW@ISA\fR
+the given stash.  The return value is a read-only AV*
+whose elements are string SVs giving class names.
+\&\f(CW\*(C`level\*(C'\fR should be 0 (it is used internally in this
+function's recursion).
+.Sp
+You are responsible for \f(CWSvREFCNT_inc()\fR on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+.RS 4
+.Sp
+.Vb 1
+\& AV *  mro_get_linear_isa_dfs(HV *stash, U32 level)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_isa_changed_in""" 4
+.el .IP \f(CWmro_isa_changed_in\fR 4
+.IX Xref "mro_isa_changed_in"
+.IX Item "mro_isa_changed_in"
+Takes the necessary steps (cache invalidations, mostly)
+when the \f(CW@ISA\fR of the given package has changed.  Invoked
+by the \f(CW\*(C`setisa\*(C'\fR magic, should not need to invoke directly.
+.RS 4
+.Sp
+.Vb 1
+\& void  mro_isa_changed_in(HV *stash)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """mro_package_moved""" 4
+.el .IP \f(CWmro_package_moved\fR 4
+.IX Xref "mro_package_moved"
+.IX Item "mro_package_moved"
+Call this function to signal to a stash that it has been assigned to
+another spot in the stash hierarchy.  \f(CW\*(C`stash\*(C'\fR is the stash that has been
+assigned.  \f(CW\*(C`oldstash\*(C'\fR is the stash it replaces, if any.  \f(CW\*(C`gv\*(C'\fR is the glob
+that is actually being assigned to.
+.Sp
+This can also be called with a null first argument to
+indicate that \f(CW\*(C`oldstash\*(C'\fR has been deleted.
+.Sp
+This function invalidates isa caches on the old stash, on all subpackages
+nested inside it, and on the subclasses of all those, including
+non-existent packages that have corresponding entries in \f(CW\*(C`stash\*(C'\fR.
+.Sp
+It also sets the effective names (\f(CW\*(C`HvENAME\*(C'\fR) on all the stashes as
+appropriate.
+.Sp
+If the \f(CW\*(C`gv\*(C'\fR is present and is not in the symbol table, then this function
+simply returns.  This checked will be skipped if \f(CW\*(C`flags & 1\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& void  mro_package_moved(HV * const stash, HV * const oldstash,
+\&                         const GV * const gv, U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Multicall Functions"
+.IX Header "Multicall Functions"
+There are currently no internal API items in Multicall Functions
+.SH "Numeric Functions"
+.IX Header "Numeric Functions"
+.ie n .IP """isinfnansv""" 4
+.el .IP \f(CWisinfnansv\fR 4
+.IX Xref "isinfnansv"
+.IX Item "isinfnansv"
+Checks whether the argument would be either an infinity or \f(CW\*(C`NaN\*(C'\fR when used
+as a number, but is careful not to trigger non-numeric or uninitialized
+warnings.  it assumes the caller has done \f(CWSvGETMAGIC(sv)\fR already.
+.Sp
+Note that this always accepts trailing garbage (similar to \f(CW\*(C`grok_number_flags\*(C'\fR
+with \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR), so \f(CW"inferior"\fR and \f(CW"NAND gates"\fR will
+return true.
+.RS 4
+.Sp
+.Vb 1
+\& bool  isinfnansv(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Optrees
+.IX Header "Optrees"
+.ie n .IP """newATTRSUB_x""" 4
+.el .IP \f(CWnewATTRSUB_x\fR 4
+.IX Xref "newATTRSUB_x"
+.IX Item "newATTRSUB_x"
+Construct a Perl subroutine, also performing some surrounding jobs.
+.Sp
+This function is expected to be called in a Perl compilation context,
+and some aspects of the subroutine are taken from global variables
+associated with compilation.  In particular, \f(CW\*(C`PL_compcv\*(C'\fR represents
+the subroutine that is currently being compiled.  It must be non-null
+when this function is called, and some aspects of the subroutine being
+constructed are taken from it.  The constructed subroutine may actually
+be a reuse of the \f(CW\*(C`PL_compcv\*(C'\fR object, but will not necessarily be so.
+.Sp
+If \f(CW\*(C`block\*(C'\fR is null then the subroutine will have no body, and for the
+time being it will be an error to call it.  This represents a forward
+subroutine declaration such as \f(CW\*(C`sub\ foo\ ($$);\*(C'\fR.  If \f(CW\*(C`block\*(C'\fR is
+non-null then it provides the Perl code of the subroutine body, which
+will be executed when the subroutine is called.  This body includes
+any argument unwrapping code resulting from a subroutine signature or
+similar.  The pad use of the code must correspond to the pad attached
+to \f(CW\*(C`PL_compcv\*(C'\fR.  The code is not expected to include a \f(CW\*(C`leavesub\*(C'\fR or
+\&\f(CW\*(C`leavesublv\*(C'\fR op; this function will add such an op.  \f(CW\*(C`block\*(C'\fR is consumed
+by this function and will become part of the constructed subroutine.
+.Sp
+\&\f(CW\*(C`proto\*(C'\fR specifies the subroutine's prototype, unless one is supplied
+as an attribute (see below).  If \f(CW\*(C`proto\*(C'\fR is null, then the subroutine
+will not have a prototype.  If \f(CW\*(C`proto\*(C'\fR is non-null, it must point to a
+\&\f(CW\*(C`const\*(C'\fR op whose value is a string, and the subroutine will have that
+string as its prototype.  If a prototype is supplied as an attribute, the
+attribute takes precedence over \f(CW\*(C`proto\*(C'\fR, but in that case \f(CW\*(C`proto\*(C'\fR should
+preferably be null.  In any case, \f(CW\*(C`proto\*(C'\fR is consumed by this function.
+.Sp
+\&\f(CW\*(C`attrs\*(C'\fR supplies attributes to be applied the subroutine.  A handful of
+attributes take effect by built-in means, being applied to \f(CW\*(C`PL_compcv\*(C'\fR
+immediately when seen.  Other attributes are collected up and attached
+to the subroutine by this route.  \f(CW\*(C`attrs\*(C'\fR may be null to supply no
+attributes, or point to a \f(CW\*(C`const\*(C'\fR op for a single attribute, or point
+to a \f(CW\*(C`list\*(C'\fR op whose children apart from the \f(CW\*(C`pushmark\*(C'\fR are \f(CW\*(C`const\*(C'\fR
+ops for one or more attributes.  Each \f(CW\*(C`const\*(C'\fR op must be a string,
+giving the attribute name optionally followed by parenthesised arguments,
+in the manner in which attributes appear in Perl source.  The attributes
+will be applied to the sub by this function.  \f(CW\*(C`attrs\*(C'\fR is consumed by
+this function.
+.Sp
+If \f(CW\*(C`o_is_gv\*(C'\fR is false and \f(CW\*(C`o\*(C'\fR is null, then the subroutine will
+be anonymous.  If \f(CW\*(C`o_is_gv\*(C'\fR is false and \f(CW\*(C`o\*(C'\fR is non-null, then \f(CW\*(C`o\*(C'\fR
+must point to a \f(CW\*(C`const\*(C'\fR OP, which will be consumed by this function,
+and its string value supplies a name for the subroutine.  The name may
+be qualified or unqualified, and if it is unqualified then a default
+stash will be selected in some manner.  If \f(CW\*(C`o_is_gv\*(C'\fR is true, then \f(CW\*(C`o\*(C'\fR
+doesn't point to an \f(CW\*(C`OP\*(C'\fR at all, but is instead a cast pointer to a \f(CW\*(C`GV\*(C'\fR
+by which the subroutine will be named.
+.Sp
+If there is already a subroutine of the specified name, then the new
+sub will either replace the existing one in the glob or be merged with
+the existing one.  A warning may be generated about redefinition.
+.Sp
+If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
+\&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
+running of phase-related subroutines.  In this case the relevant glob will
+be left not containing any subroutine, even if it did contain one before.
+In the case of \f(CW\*(C`BEGIN\*(C'\fR, the subroutine will be executed and the reference
+to it disposed of before this function returns.
+.Sp
+The function returns a pointer to the constructed subroutine.  If the sub
+is anonymous then ownership of one counted reference to the subroutine
+is transferred to the caller.  If the sub is named then the caller does
+not get ownership of a reference.  In most such cases, where the sub
+has a non-phase name, the sub will be alive at the point it is returned
+by virtue of being contained in the glob that names it.  A phase-named
+subroutine will usually be alive by virtue of the reference owned by the
+phase's automatic run queue.  But a \f(CW\*(C`BEGIN\*(C'\fR subroutine, having already
+been executed, will quite likely have been destroyed already by the
+time this function returns, making it erroneous for the caller to make
+any use of the returned pointer.  It is the caller's responsibility to
+ensure that it knows which of these situations applies.
+.RS 4
+.Sp
+.Vb 2
+\& CV *  newATTRSUB_x(I32 floor, OP *o, OP *proto, OP *attrs,
+\&                    OP *block, bool o_is_gv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """newXS_len_flags""" 4
+.el .IP \f(CWnewXS_len_flags\fR 4
+.IX Xref "newXS_len_flags"
+.IX Item "newXS_len_flags"
+Construct an XS subroutine, also performing some surrounding jobs.
+.Sp
+The subroutine will have the entry point \f(CW\*(C`subaddr\*(C'\fR.  It will have
+the prototype specified by the nul-terminated string \f(CW\*(C`proto\*(C'\fR, or
+no prototype if \f(CW\*(C`proto\*(C'\fR is null.  The prototype string is copied;
+the caller can mutate the supplied string afterwards.  If \f(CW\*(C`filename\*(C'\fR
+is non-null, it must be a nul-terminated filename, and the subroutine
+will have its \f(CW\*(C`CvFILE\*(C'\fR set accordingly.  By default \f(CW\*(C`CvFILE\*(C'\fR is set to
+point directly to the supplied string, which must be static.  If \f(CW\*(C`flags\*(C'\fR
+has the \f(CW\*(C`XS_DYNAMIC_FILENAME\*(C'\fR bit set, then a copy of the string will
+be taken instead.
+.Sp
+Other aspects of the subroutine will be left in their default state.
+If anything else needs to be done to the subroutine for it to function
+correctly, it is the caller's responsibility to do that after this
+function has constructed it.  However, beware of the subroutine
+potentially being destroyed before this function returns, as described
+below.
+.Sp
+If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its
+\&\f(CW\*(C`CvGV\*(C'\fR referring to an \f(CW\*(C`_\|_ANON_\|_\*(C'\fR glob.  If \f(CW\*(C`name\*(C'\fR is non-null then the
+subroutine will be named accordingly, referenced by the appropriate glob.
+\&\f(CW\*(C`name\*(C'\fR is a string of length \f(CW\*(C`len\*(C'\fR bytes giving a sigilless symbol name,
+in UTF\-8 if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SVf_UTF8\*(C'\fR bit set and in Latin\-1 otherwise.
+The name may be either qualified or unqualified, with the stash defaulting
+in the same manner as for \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR.  \f(CW\*(C`flags\*(C'\fR may contain
+flag bits understood by \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR with the same meaning as
+they have there, such as \f(CW\*(C`GV_ADDWARN\*(C'\fR.  The symbol is always added to
+the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR semantics.
+.Sp
+If there is already a subroutine of the specified name, then the new sub
+will replace the existing one in the glob.  A warning may be generated
+about the redefinition.  If the old subroutine was \f(CW\*(C`CvCONST\*(C'\fR then the
+decision about whether to warn is influenced by an expectation about
+whether the new subroutine will become a constant of similar value.
+That expectation is determined by \f(CW\*(C`const_svp\*(C'\fR.  (Note that the call to
+this function doesn't make the new subroutine \f(CW\*(C`CvCONST\*(C'\fR in any case;
+that is left to the caller.)  If \f(CW\*(C`const_svp\*(C'\fR is null then it indicates
+that the new subroutine will not become a constant.  If \f(CW\*(C`const_svp\*(C'\fR
+is non-null then it indicates that the new subroutine will become a
+constant, and it points to an \f(CW\*(C`SV*\*(C'\fR that provides the constant value
+that the subroutine will have.
+.Sp
+If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
+\&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
+running of phase-related subroutines.  In this case the relevant glob will
+be left not containing any subroutine, even if it did contain one before.
+In the case of \f(CW\*(C`BEGIN\*(C'\fR, the subroutine will be executed and the reference
+to it disposed of before this function returns, and also before its
+prototype is set.  If a \f(CW\*(C`BEGIN\*(C'\fR subroutine would not be sufficiently
+constructed by this function to be ready for execution then the caller
+must prevent this happening by giving the subroutine a different name.
+.Sp
+The function returns a pointer to the constructed subroutine.  If the sub
+is anonymous then ownership of one counted reference to the subroutine
+is transferred to the caller.  If the sub is named then the caller does
+not get ownership of a reference.  In most such cases, where the sub
+has a non-phase name, the sub will be alive at the point it is returned
+by virtue of being contained in the glob that names it.  A phase-named
+subroutine will usually be alive by virtue of the reference owned by the
+phase's automatic run queue.  But a \f(CW\*(C`BEGIN\*(C'\fR subroutine, having already
+been executed, will quite likely have been destroyed already by the
+time this function returns, making it erroneous for the caller to make
+any use of the returned pointer.  It is the caller's responsibility to
+ensure that it knows which of these situations applies.
+.RS 4
+.Sp
+.Vb 5
+\& CV *  newXS_len_flags(const char *name, STRLEN len,
+\&                       XSUBADDR_t subaddr,
+\&                       const char * const filename,
+\&                       const char * const proto, SV ** const_svp,
+\&                       U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_refcnt_lock""" 4
+.el .IP \f(CWop_refcnt_lock\fR 4
+.IX Xref "op_refcnt_lock"
+.IX Item "op_refcnt_lock"
+Implements the \f(CW\*(C`OP_REFCNT_LOCK\*(C'\fR macro which you should use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  op_refcnt_lock()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """op_refcnt_unlock""" 4
+.el .IP \f(CWop_refcnt_unlock\fR 4
+.IX Xref "op_refcnt_unlock"
+.IX Item "op_refcnt_unlock"
+Implements the \f(CW\*(C`OP_REFCNT_UNLOCK\*(C'\fR macro which you should use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  op_refcnt_unlock()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """traverse_op_tree""" 4
+.el .IP \f(CWtraverse_op_tree\fR 4
+.IX Xref "traverse_op_tree"
+.IX Item "traverse_op_tree"
+Return the next op in a depth-first traversal of the op tree,
+returning NULL when the traversal is complete.
+.Sp
+The initial call must supply the root of the tree as both top and o.
+.Sp
+For now it's static, but it may be exposed to the API in the future.
+.RS 4
+.Sp
+.Vb 1
+\& OP *  traverse_op_tree(OP *top, OP *o)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Pack and Unpack"
+.IX Header "Pack and Unpack"
+There are currently no internal API items in Pack and Unpack
+.SH "Pad Data Structures"
+.IX Header "Pad Data Structures"
+.ie n .IP """CX_CURPAD_SAVE""" 4
+.el .IP \f(CWCX_CURPAD_SAVE\fR 4
+.IX Xref "CX_CURPAD_SAVE"
+.IX Item "CX_CURPAD_SAVE"
+Save the current pad in the given context block structure.
+.RS 4
+.Sp
+.Vb 1
+\& void  CX_CURPAD_SAVE(struct context)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """CX_CURPAD_SV""" 4
+.el .IP \f(CWCX_CURPAD_SV\fR 4
+.IX Xref "CX_CURPAD_SV"
+.IX Item "CX_CURPAD_SV"
+Access the SV at offset \f(CW\*(C`po\*(C'\fR in the saved current pad in the given
+context block structure (can be used as an lvalue).
+.RS 4
+.Sp
+.Vb 1
+\& SV *  CX_CURPAD_SV(struct context, PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_BASE_SV""" 4
+.el .IP \f(CWPAD_BASE_SV\fR 4
+.IX Xref "PAD_BASE_SV"
+.IX Item "PAD_BASE_SV"
+Get the value from slot \f(CW\*(C`po\*(C'\fR in the base (DEPTH=1) pad of a padlist
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_CLONE_VARS""" 4
+.el .IP \f(CWPAD_CLONE_VARS\fR 4
+.IX Xref "PAD_CLONE_VARS"
+.IX Item "PAD_CLONE_VARS"
+Clone the state variables associated with running and compiling pads.
+.RS 4
+.Sp
+.Vb 2
+\& void  PAD_CLONE_VARS(PerlInterpreter *proto_perl,
+\&                      CLONE_PARAMS* param)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_FLAGS""" 4
+.el .IP \f(CWPAD_COMPNAME_FLAGS\fR 4
+.IX Xref "PAD_COMPNAME_FLAGS"
+.IX Item "PAD_COMPNAME_FLAGS"
+Return the flags for the current compiling pad name
+at offset \f(CW\*(C`po\*(C'\fR.  Assumes a valid slot entry.
+.RS 4
+.Sp
+.Vb 1
+\& U32  PAD_COMPNAME_FLAGS(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_GEN""" 4
+.el .IP \f(CWPAD_COMPNAME_GEN\fR 4
+.IX Xref "PAD_COMPNAME_GEN"
+.IX Item "PAD_COMPNAME_GEN"
+The generation number of the name at offset \f(CW\*(C`po\*(C'\fR in the current
+compiling pad (lvalue).
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  PAD_COMPNAME_GEN(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_GEN_set""" 4
+.el .IP \f(CWPAD_COMPNAME_GEN_set\fR 4
+.IX Xref "PAD_COMPNAME_GEN_set"
+.IX Item "PAD_COMPNAME_GEN_set"
+Sets the generation number of the name at offset \f(CW\*(C`po\*(C'\fR in the current
+ling pad (lvalue) to \f(CW\*(C`gen\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& STRLEN  PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_OURSTASH""" 4
+.el .IP \f(CWPAD_COMPNAME_OURSTASH\fR 4
+.IX Xref "PAD_COMPNAME_OURSTASH"
+.IX Item "PAD_COMPNAME_OURSTASH"
+Return the stash associated with an \f(CW\*(C`our\*(C'\fR variable.
+Assumes the slot entry is a valid \f(CW\*(C`our\*(C'\fR lexical.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  PAD_COMPNAME_OURSTASH(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_PV""" 4
+.el .IP \f(CWPAD_COMPNAME_PV\fR 4
+.IX Xref "PAD_COMPNAME_PV"
+.IX Item "PAD_COMPNAME_PV"
+Return the name of the current compiling pad name
+at offset \f(CW\*(C`po\*(C'\fR.  Assumes a valid slot entry.
+.RS 4
+.Sp
+.Vb 1
+\& char *  PAD_COMPNAME_PV(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_COMPNAME_TYPE""" 4
+.el .IP \f(CWPAD_COMPNAME_TYPE\fR 4
+.IX Xref "PAD_COMPNAME_TYPE"
+.IX Item "PAD_COMPNAME_TYPE"
+Return the type (stash) of the current compiling pad name at offset
+\&\f(CW\*(C`po\*(C'\fR.  Must be a valid name.  Returns null if not typed.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  PAD_COMPNAME_TYPE(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameIsFIELD""" 4
+.el .IP \f(CWPadnameIsFIELD\fR 4
+.IX Xref "PadnameIsFIELD"
+.IX Item "PadnameIsFIELD"
+Whether this is a "field" variable.  PADNAMEs where this is true will
+have additional information available via \f(CW\*(C`PadnameFIELDINFO\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& bool  PadnameIsFIELD(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameIsOUR""" 4
+.el .IP \f(CWPadnameIsOUR\fR 4
+.IX Xref "PadnameIsOUR"
+.IX Item "PadnameIsOUR"
+Whether this is an "our" variable.
+.RS 4
+.Sp
+.Vb 1
+\& bool  PadnameIsOUR(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameIsSTATE""" 4
+.el .IP \f(CWPadnameIsSTATE\fR 4
+.IX Xref "PadnameIsSTATE"
+.IX Item "PadnameIsSTATE"
+Whether this is a "state" variable.
+.RS 4
+.Sp
+.Vb 1
+\& bool  PadnameIsSTATE(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameOURSTASH""" 4
+.el .IP \f(CWPadnameOURSTASH\fR 4
+.IX Xref "PadnameOURSTASH"
+.IX Item "PadnameOURSTASH"
+The stash in which this "our" variable was declared.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  PadnameOURSTASH(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameOUTER""" 4
+.el .IP \f(CWPadnameOUTER\fR 4
+.IX Xref "PadnameOUTER"
+.IX Item "PadnameOUTER"
+Whether this entry belongs to an outer pad.  Entries for which this is true
+are often referred to as 'fake'.
+.RS 4
+.Sp
+.Vb 1
+\& bool  PadnameOUTER(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PadnameTYPE""" 4
+.el .IP \f(CWPadnameTYPE\fR 4
+.IX Xref "PadnameTYPE"
+.IX Item "PadnameTYPE"
+The stash associated with a typed lexical.  This returns the \f(CW%Foo::\fR hash
+for \f(CW\*(C`my Foo $bar\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& HV *  PadnameTYPE(PADNAME * pn)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_RESTORE_LOCAL""" 4
+.el .IP \f(CWPAD_RESTORE_LOCAL\fR 4
+.IX Xref "PAD_RESTORE_LOCAL"
+.IX Item "PAD_RESTORE_LOCAL"
+Restore the old pad saved into the local variable \f(CW\*(C`opad\*(C'\fR by \f(CWPAD_SAVE_LOCAL()\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  PAD_RESTORE_LOCAL(PAD *opad)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SAVE_LOCAL""" 4
+.el .IP \f(CWPAD_SAVE_LOCAL\fR 4
+.IX Xref "PAD_SAVE_LOCAL"
+.IX Item "PAD_SAVE_LOCAL"
+Save the current pad to the local variable \f(CW\*(C`opad\*(C'\fR, then make the
+current pad equal to \f(CW\*(C`npad\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SAVE_SETNULLPAD""" 4
+.el .IP \f(CWPAD_SAVE_SETNULLPAD\fR 4
+.IX Xref "PAD_SAVE_SETNULLPAD"
+.IX Item "PAD_SAVE_SETNULLPAD"
+Save the current pad then set it to null.
+.RS 4
+.Sp
+.Vb 1
+\& void  PAD_SAVE_SETNULLPAD()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SET_CUR""" 4
+.el .IP \f(CWPAD_SET_CUR\fR 4
+.IX Xref "PAD_SET_CUR"
+.IX Item "PAD_SET_CUR"
+Set the current pad to be pad \f(CW\*(C`n\*(C'\fR in the padlist, saving
+the previous current pad.  NB currently this macro expands to a string too
+long for some compilers, so it's best to replace it with
+.Sp
+.Vb 2
+\&    SAVECOMPPAD();
+\&    PAD_SET_CUR_NOSAVE(padlist,n);
+.Ve
+.RS 4
+.Sp
+.Vb 1
+\& void  PAD_SET_CUR(PADLIST padlist, I32 n)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SET_CUR_NOSAVE""" 4
+.el .IP \f(CWPAD_SET_CUR_NOSAVE\fR 4
+.IX Xref "PAD_SET_CUR_NOSAVE"
+.IX Item "PAD_SET_CUR_NOSAVE"
+like PAD_SET_CUR, but without the save
+.RS 4
+.Sp
+.Vb 1
+\& void  PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SETSV""" 4
+.el .IP \f(CWPAD_SETSV\fR 4
+.IX Xref "PAD_SETSV"
+.IX Item "PAD_SETSV"
+Set the slot at offset \f(CW\*(C`po\*(C'\fR in the current pad to \f(CW\*(C`sv\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PAD_SETSV(PADOFFSET po, SV* sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SV""" 4
+.el .IP \f(CWPAD_SV\fR 4
+.IX Xref "PAD_SV"
+.IX Item "PAD_SV"
+Get the value at offset \f(CW\*(C`po\*(C'\fR in the current pad
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PAD_SV(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PAD_SVl""" 4
+.el .IP \f(CWPAD_SVl\fR 4
+.IX Xref "PAD_SVl"
+.IX Item "PAD_SVl"
+Lightweight and lvalue version of \f(CW\*(C`PAD_SV\*(C'\fR.
+Get or set the value at offset \f(CW\*(C`po\*(C'\fR in the current pad.
+Unlike \f(CW\*(C`PAD_SV\*(C'\fR, does not print diagnostics with \-DX.
+For internal use only.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  PAD_SVl(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVECLEARSV""" 4
+.el .IP \f(CWSAVECLEARSV\fR 4
+.IX Xref "SAVECLEARSV"
+.IX Item "SAVECLEARSV"
+Clear the pointed to pad value on scope exit.  (i.e. the runtime action of
+\&\f(CW\*(C`my\*(C'\fR)
+.RS 4
+.Sp
+.Vb 1
+\& void  SAVECLEARSV(SV **svp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVECOMPPAD""" 4
+.el .IP \f(CWSAVECOMPPAD\fR 4
+.IX Xref "SAVECOMPPAD"
+.IX Item "SAVECOMPPAD"
+save \f(CW\*(C`PL_comppad\*(C'\fR and \f(CW\*(C`PL_curpad\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& void  SAVECOMPPAD()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SAVEPADSV""" 4
+.el .IP \f(CWSAVEPADSV\fR 4
+.IX Xref "SAVEPADSV"
+.IX Item "SAVEPADSV"
+Save a pad slot (used to restore after an iteration)
+.RS 4
+.Sp
+.Vb 1
+\& void  SAVEPADSV(PADOFFSET po)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Password and Group access"
+.IX Header "Password and Group access"
+There are currently no internal API items in Password and Group access
+.SH "Paths to system commands"
+.IX Header "Paths to system commands"
+There are currently no internal API items in Paths to system commands
+.SH "Prototype information"
+.IX Header "Prototype information"
+There are currently no internal API items in Prototype information
+.SH "REGEXP Functions"
+.IX Header "REGEXP Functions"
+.ie n .IP """regnode""" 4
+.el .IP \f(CWregnode\fR 4
+.IX Item "regnode"
+Described in perlreguts.
+.SH "Reports and Formats"
+.IX Header "Reports and Formats"
+There are currently no internal API items in Reports and Formats
+.SH Signals
+.IX Header "Signals"
+There are currently no internal API items in Signals
+.SH "Site configuration"
+.IX Header "Site configuration"
+There are currently no internal API items in Site configuration
+.SH "Sockets configuration values"
+.IX Header "Sockets configuration values"
+There are currently no internal API items in Sockets configuration values
+.SH "Source Filters"
+.IX Header "Source Filters"
+There are currently no internal API items in Source Filters
+.SH "Stack Manipulation Macros"
+.IX Header "Stack Manipulation Macros"
+.ie n .IP """djSP""" 4
+.el .IP \f(CWdjSP\fR 4
+.IX Xref "djSP"
+.IX Item "djSP"
+Declare Just \f(CW\*(C`SP\*(C'\fR.  This is actually identical to \f(CW\*(C`dSP\*(C'\fR, and declares
+a local copy of perl's stack pointer, available via the \f(CW\*(C`SP\*(C'\fR macro.
+See \f(CW\*(C`"SP" in perlapi\*(C'\fR.  (Available for backward source code compatibility with
+the old (Perl 5.005) thread model.)
+.RS 4
+.Sp
+.Vb 1
+\&   djSP();
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """LVRET""" 4
+.el .IP \f(CWLVRET\fR 4
+.IX Xref "LVRET"
+.IX Item "LVRET"
+True if this op will be the return value of an lvalue subroutine
+.ie n .IP """save_alloc""" 4
+.el .IP \f(CWsave_alloc\fR 4
+.IX Xref "save_alloc"
+.IX Item "save_alloc"
+Implements "\f(CW\*(C`SSNEW\*(C'\fR" in perlapi and kin, which should be used instead of this
+function.
+.RS 4
+.Sp
+.Vb 1
+\& SSize_t  save_alloc(SSize_t size, I32 pad)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "String Handling"
+.IX Header "String Handling"
+.ie n .IP """delimcpy_no_escape""" 4
+.el .IP \f(CWdelimcpy_no_escape\fR 4
+.IX Xref "delimcpy_no_escape"
+.IX Item "delimcpy_no_escape"
+Copy a source buffer to a destination buffer, stopping at (but not including)
+the first occurrence in the source of the delimiter byte, \f(CW\*(C`delim\*(C'\fR.  The source
+is the bytes between \f(CW\*(C`from\*(C'\fR\ and\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1.  Similarly, the dest is
+\&\f(CW\*(C`to\*(C'\fR up to \f(CW\*(C`to_end\*(C'\fR.
+.Sp
+The number of bytes copied is written to \f(CW*retlen\fR.
+.Sp
+Returns the position of \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but if there is no
+such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned, and the entire
+buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied.
+.Sp
+If there is room in the destination available after the copy, an extra
+terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned
+length).
+.Sp
+The error case is if the destination buffer is not large enough to accommodate
+everything that should be copied.  In this situation, a value larger than
+\&\f(CW\*(C`to_end\*(C'\fR\ \-\ \f(CW\*(C`to\*(C'\fR is written to \f(CW*retlen\fR, and as much of the source as
+fits will be written to the destination.  Not having room for the safety \f(CW\*(C`NUL\*(C'\fR
+is not considered an error.
+.RS 4
+.Sp
+.Vb 3
+\& char *  delimcpy_no_escape(char *to, const char *to_end,
+\&                            const char *from, const char *from_end,
+\&                            const int delim, I32 *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_cxt_init""" 4
+.el .IP \f(CWmy_cxt_init\fR 4
+.IX Xref "my_cxt_init"
+.IX Item "my_cxt_init"
+Implements the "\f(CW\*(C`MY_CXT_INIT\*(C'\fR" in perlxs macro, which you should use instead.
+.Sp
+The first time a module is loaded, the global \f(CW\*(C`PL_my_cxt_index\*(C'\fR is incremented,
+and that value is assigned to that module's static \f(CW\*(C`my_cxt_index\*(C'\fR (whose
+address is passed as an arg).  Then, for each interpreter this function is
+called for, it makes sure a \f(CW\*(C`void*\*(C'\fR slot is available to hang the static data
+off, by allocating or extending the interpreter's \f(CW\*(C`PL_my_cxt_list\*(C'\fR array
+.Sp
+NOTE: \f(CW\*(C`my_cxt_init\*(C'\fR must be explicitly called as
+\&\f(CW\*(C`Perl_my_cxt_init\*(C'\fR
+with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
+.RS 4
+.Sp
+.Vb 1
+\& void *  Perl_my_cxt_init(pTHX_ int *indexp, size_t size)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """quadmath_format_needed""" 4
+.el .IP \f(CWquadmath_format_needed\fR 4
+.IX Xref "quadmath_format_needed"
+.IX Item "quadmath_format_needed"
+\&\f(CWquadmath_format_needed()\fR returns true if the \f(CW\*(C`format\*(C'\fR string seems to
+contain at least one non-Q-prefixed \f(CW\*(C`%[efgaEFGA]\*(C'\fR format specifier,
+or returns false otherwise.
+.Sp
+The format specifier detection is not complete printf-syntax detection,
+but it should catch most common cases.
+.Sp
+If true is returned, those arguments \fBshould\fR in theory be processed
+with \f(CWquadmath_snprintf()\fR, but in case there is more than one such
+format specifier (see "quadmath_format_valid"), and if there is
+anything else beyond that one (even just a single byte), they
+\&\fBcannot\fR be processed because \f(CWquadmath_snprintf()\fR is very strict,
+accepting only one format spec, and nothing else.
+In this case, the code should probably fail.
+.RS 4
+.Sp
+.Vb 1
+\& bool  quadmath_format_needed(const char *format)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """quadmath_format_valid""" 4
+.el .IP \f(CWquadmath_format_valid\fR 4
+.IX Xref "quadmath_format_valid"
+.IX Item "quadmath_format_valid"
+\&\f(CWquadmath_snprintf()\fR is very strict about its \f(CW\*(C`format\*(C'\fR string and will
+fail, returning \-1, if the format is invalid.  It accepts exactly
+one format spec.
+.Sp
+\&\f(CWquadmath_format_valid()\fR checks that the intended single spec looks
+sane: begins with \f(CW\*(C`%\*(C'\fR, has only one \f(CW\*(C`%\*(C'\fR, ends with \f(CW\*(C`[efgaEFGA]\*(C'\fR,
+and has \f(CW\*(C`Q\*(C'\fR before it.  This is not a full "printf syntax check",
+just the basics.
+.Sp
+Returns true if it is valid, false if not.
+.Sp
+See also "quadmath_format_needed".
+.RS 4
+.Sp
+.Vb 1
+\& bool  quadmath_format_valid(const char *format)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "SV Flags"
+.IX Header "SV Flags"
+.ie n .IP """SVt_INVLIST""" 4
+.el .IP \f(CWSVt_INVLIST\fR 4
+.IX Xref "SVt_INVLIST"
+.IX Item "SVt_INVLIST"
+Type flag for scalars.  See "svtype" in perlapi.
+.SH "SV Handling"
+.IX Header "SV Handling"
+.ie n .IP """PL_Sv""" 4
+.el .IP \f(CWPL_Sv\fR 4
+.IX Xref "PL_Sv"
+.IX Item "PL_Sv"
+A scratch pad SV for whatever temporary use you need.  Chiefly used as a
+fallback by macros on platforms where "PERL_USE_GCC_BRACE_GROUPS" in perlapi> is
+unavailable, and which would otherwise evaluate their SV parameter more than
+once.
+.Sp
+\&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it
+is in a call stack with something else that is using it, this variable would
+get zapped, leading to hard-to-diagnose errors.
+.RS 4
+.Sp
+.Vb 1
+\&   PL_Sv
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_add_arena""" 4
+.el .IP \f(CWsv_add_arena\fR 4
+.IX Xref "sv_add_arena"
+.IX Item "sv_add_arena"
+Given a chunk of memory, link it to the head of the list of arenas,
+and split it into a list of free SVs.
+.RS 4
+.Sp
+.Vb 2
+\& void  sv_add_arena(char * const ptr, const U32 size,
+\&                    const U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2bool""" 4
+.el .IP \f(CWsv_2bool\fR 4
+.IX Xref "sv_2bool"
+.IX Item "sv_2bool"
+This macro is only used by \f(CWsv_true()\fR or its macro equivalent, and only if
+the latter's argument is neither \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR nor \f(CW\*(C`SvNOK\*(C'\fR.
+It calls \f(CW\*(C`sv_2bool_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_2bool(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2bool_flags""" 4
+.el .IP \f(CWsv_2bool_flags\fR 4
+.IX Xref "sv_2bool_flags"
+.IX Item "sv_2bool_flags"
+This function is only used by \f(CWsv_true()\fR and friends,  and only if
+the latter's argument is neither \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR nor \f(CW\*(C`SvNOK\*(C'\fR.  If the flags
+contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, then it does an \f(CWmg_get()\fR first.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_2bool_flags(SV *sv, I32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_clean_all""" 4
+.el .IP \f(CWsv_clean_all\fR 4
+.IX Xref "sv_clean_all"
+.IX Item "sv_clean_all"
+Decrement the refcnt of each remaining SV, possibly triggering a
+cleanup.  This function may have to be called multiple times to free
+SVs which are in complex self-referential hierarchies.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_clean_all()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_clean_objs""" 4
+.el .IP \f(CWsv_clean_objs\fR 4
+.IX Xref "sv_clean_objs"
+.IX Item "sv_clean_objs"
+Attempt to destroy all objects not yet freed.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_clean_objs()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_free_arenas""" 4
+.el .IP \f(CWsv_free_arenas\fR 4
+.IX Xref "sv_free_arenas"
+.IX Item "sv_free_arenas"
+Deallocate the memory used by all arenas.  Note that all the individual SV
+heads and bodies within the arenas must already have been freed.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_free_arenas()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_grow""" 4
+.el .IP \f(CWsv_grow\fR 4
+.IX Xref "sv_grow"
+.IX Item "sv_grow"
+Expands the character buffer in the SV.  If necessary, uses \f(CW\*(C`sv_unref\*(C'\fR and
+upgrades the SV to \f(CW\*(C`SVt_PV\*(C'\fR.  Returns a pointer to the character buffer.
+Use the \f(CW\*(C`SvGROW\*(C'\fR wrapper instead.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_grow(SV * const sv, STRLEN newlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_grow_fresh""" 4
+.el .IP \f(CWsv_grow_fresh\fR 4
+.IX Xref "sv_grow_fresh"
+.IX Item "sv_grow_fresh"
+A cut-down version of sv_grow intended only for when sv is a freshly-minted
+SVt_PV, SVt_PVIV, SVt_PVNV, or SVt_PVMG. i.e. sv has the default flags, has
+never been any other type, and does not have an existing string. Basically,
+just assigns a char buffer and returns a pointer to it.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_grow_fresh(SV * const sv, STRLEN newlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_newref""" 4
+.el .IP \f(CWsv_newref\fR 4
+.IX Xref "sv_newref"
+.IX Item "sv_newref"
+Increment an SV's reference count.  Use the \f(CWSvREFCNT_inc()\fR wrapper
+instead.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_newref(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2num""" 4
+.el .IP \f(CWsv_2num\fR 4
+.IX Xref "sv_2num"
+.IX Item "sv_2num"
+NOTE: \f(CW\*(C`sv_2num\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Return an SV with the numeric value of the source SV, doing any necessary
+reference or overload conversion.  The caller is expected to have handled
+get-magic already.
+.RS 4
+.Sp
+.Vb 1
+\& SV *  sv_2num(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pv""" 4
+.el .IP \f(CWsv_pv\fR 4
+.IX Xref "sv_pv"
+.IX Item "sv_pv"
+Use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro instead
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pv(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvbyte""" 4
+.el .IP \f(CWsv_pvbyte\fR 4
+.IX Xref "sv_pvbyte"
+.IX Item "sv_pvbyte"
+Use \f(CW\*(C`SvPVbyte_nolen\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pvbyte(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvbyten_force""" 4
+.el .IP \f(CWsv_pvbyten_force\fR 4
+.IX Xref "sv_pvbyten_force"
+.IX Item "sv_pvbyten_force"
+The backend for the \f(CW\*(C`SvPVbytex_force\*(C'\fR macro.  Always use the macro
+instead.  If the SV cannot be downgraded from UTF\-8, this croaks.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pvbyten_force(SV * const sv, STRLEN * const lp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pvbyte_nolen""" 4
+.el .IP \f(CWsv_2pvbyte_nolen\fR 4
+.IX Xref "sv_2pvbyte_nolen"
+.IX Item "sv_2pvbyte_nolen"
+Return a pointer to the byte-encoded representation of the SV.
+May cause the SV to be downgraded from UTF\-8 as a side-effect.
+.Sp
+Usually accessed via the \f(CW\*(C`SvPVbyte_nolen\*(C'\fR macro.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_2pvbyte_nolen(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvn_force""" 4
+.el .IP \f(CWsv_pvn_force\fR 4
+.IX Xref "sv_pvn_force"
+.IX Item "sv_pvn_force"
+Get a sensible string out of the SV somehow.
+A private implementation of the \f(CW\*(C`SvPV_force\*(C'\fR macro for compilers which
+can't cope with complex macro expressions.  Always use the macro instead.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pvn_force(SV *sv, STRLEN *lp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pv_nolen""" 4
+.el .IP \f(CWsv_2pv_nolen\fR 4
+.IX Xref "sv_2pv_nolen"
+.IX Item "sv_2pv_nolen"
+Like \f(CWsv_2pv()\fR, but doesn't return the length too.  You should usually
+use the macro wrapper \f(CWSvPV_nolen(sv)\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_2pv_nolen(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvutf8n_force""" 4
+.el .IP \f(CWsv_pvutf8n_force\fR 4
+.IX Xref "sv_pvutf8n_force"
+.IX Item "sv_pvutf8n_force"
+The backend for the \f(CW\*(C`SvPVutf8x_force\*(C'\fR macro.  Always use the macro
+instead.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pvutf8n_force(SV * const sv, STRLEN * const lp)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_2pvutf8_nolen""" 4
+.el .IP \f(CWsv_2pvutf8_nolen\fR 4
+.IX Xref "sv_2pvutf8_nolen"
+.IX Item "sv_2pvutf8_nolen"
+Return a pointer to the UTF\-8\-encoded representation of the SV.
+May cause the SV to be upgraded to UTF\-8 as a side-effect.
+.Sp
+Usually accessed via the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro.
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_2pvutf8_nolen(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_pvutf8""" 4
+.el .IP \f(CWsv_pvutf8\fR 4
+.IX Xref "sv_pvutf8"
+.IX Item "sv_pvutf8"
+Use the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro instead
+.RS 4
+.Sp
+.Vb 1
+\& char *  sv_pvutf8(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_tainted""" 4
+.el .IP \f(CWsv_tainted\fR 4
+.IX Xref "sv_tainted"
+.IX Item "sv_tainted"
+Test an SV for taintedness.  Use \f(CW\*(C`SvTAINTED\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& bool  sv_tainted(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """SvTHINKFIRST""" 4
+.el .IP \f(CWSvTHINKFIRST\fR 4
+.IX Xref "SvTHINKFIRST"
+.IX Item "SvTHINKFIRST"
+A quick flag check to see whether an \f(CW\*(C`sv\*(C'\fR should be passed to \f(CW\*(C`sv_force_normal\*(C'\fR
+to be "downgraded" before \f(CW\*(C`SvIVX\*(C'\fR or \f(CW\*(C`SvPVX\*(C'\fR can be modified directly.
+.Sp
+For example, if your scalar is a reference and you want to modify the \f(CW\*(C`SvIVX\*(C'\fR
+slot, you can't just do \f(CW\*(C`SvROK_off\*(C'\fR, as that will leak the referent.
+.Sp
+This is used internally by various sv-modifying functions, such as
+\&\f(CW\*(C`sv_setsv\*(C'\fR, \f(CW\*(C`sv_setiv\*(C'\fR and \f(CW\*(C`sv_pvn_force\*(C'\fR.
+.Sp
+One case that this does not handle is a gv without SvFAKE set.  After
+.Sp
+.Vb 1
+\&    if (SvTHINKFIRST(gv)) sv_force_normal(gv);
+.Ve
+.Sp
+it will still be a gv.
+.Sp
+\&\f(CW\*(C`SvTHINKFIRST\*(C'\fR sometimes produces false positives.  In those cases
+\&\f(CW\*(C`sv_force_normal\*(C'\fR does nothing.
+.RS 4
+.Sp
+.Vb 1
+\& U32  SvTHINKFIRST(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_true""" 4
+.el .IP \f(CWsv_true\fR 4
+.IX Xref "sv_true"
+.IX Item "sv_true"
+Returns true if the SV has a true value by Perl's rules.
+Use the \f(CW\*(C`SvTRUE\*(C'\fR macro instead, which may call \f(CWsv_true()\fR or may
+instead use an in-line version.
+.RS 4
+.Sp
+.Vb 1
+\& I32  sv_true(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """sv_untaint""" 4
+.el .IP \f(CWsv_untaint\fR 4
+.IX Xref "sv_untaint"
+.IX Item "sv_untaint"
+Untaint an SV.  Use \f(CW\*(C`SvTAINTED_off\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_untaint(SV * const sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Tainting
+.IX Header "Tainting"
+.ie n .IP """sv_taint""" 4
+.el .IP \f(CWsv_taint\fR 4
+.IX Xref "sv_taint"
+.IX Item "sv_taint"
+Taint an SV.  Use \f(CW\*(C`SvTAINTED_on\*(C'\fR instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  sv_taint(SV *sv)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT""" 4
+.el .IP \f(CWTAINT\fR 4
+.IX Xref "TAINT"
+.IX Item "TAINT"
+If we aren't in taint checking mode, do nothing;
+otherwise indicate to "\f(CW\*(C`TAINT_set\*(C'\fR" and "\f(CW\*(C`TAINT_PROPER\*(C'\fR" that some
+unspecified element is tainted.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_ENV""" 4
+.el .IP \f(CWTAINT_ENV\fR 4
+.IX Xref "TAINT_ENV"
+.IX Item "TAINT_ENV"
+Looks at several components of \f(CW%ENV\fR for taintedness, and
+calls "\f(CW\*(C`taint_proper\*(C'\fR" if any are tainted.  The components it searches are
+things like \f(CW$PATH\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_ENV
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """taint_env""" 4
+.el .IP \f(CWtaint_env\fR 4
+.IX Xref "taint_env"
+.IX Item "taint_env"
+Implements the "TAINT_ENV" macro, which you should generally use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  taint_env()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_get""" 4
+.el .IP \f(CWTAINT_get\fR 4
+.IX Xref "TAINT_get"
+.IX Item "TAINT_get"
+Returns a boolean as to whether some element is tainted or not.
+.RS 4
+.Sp
+.Vb 1
+\& bool  TAINT_get()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_IF""" 4
+.el .IP \f(CWTAINT_IF\fR 4
+.IX Xref "TAINT_IF"
+.IX Item "TAINT_IF"
+If \f(CW\*(C`c\*(C'\fR evaluates to true, call "\f(CW\*(C`TAINT\*(C'\fR" to indicate that something is
+tainted; otherwise do nothing.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_IF(bool c)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINTING_get""" 4
+.el .IP \f(CWTAINTING_get\fR 4
+.IX Xref "TAINTING_get"
+.IX Item "TAINTING_get"
+Returns a boolean as to whether taint checking is enabled or not.
+.RS 4
+.Sp
+.Vb 1
+\& bool  TAINTING_get()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINTING_set""" 4
+.el .IP \f(CWTAINTING_set\fR 4
+.IX Xref "TAINTING_set"
+.IX Item "TAINTING_set"
+Turn taint checking mode off/on
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINTING_set(bool s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_NOT""" 4
+.el .IP \f(CWTAINT_NOT\fR 4
+.IX Xref "TAINT_NOT"
+.IX Item "TAINT_NOT"
+Remove any taintedness previously set by, \fIe.g.\fR, \f(CW\*(C`TAINT\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_NOT()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_PROPER""" 4
+.el .IP \f(CWTAINT_PROPER\fR 4
+.IX Xref "TAINT_PROPER"
+.IX Item "TAINT_PROPER"
+If no element is tainted, do nothing;
+otherwise output a message (containing \f(CW\*(C`s\*(C'\fR) that indicates there is a
+tainting violation.  If such violations are fatal, it croaks.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_PROPER(const char * s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """taint_proper""" 4
+.el .IP \f(CWtaint_proper\fR 4
+.IX Xref "taint_proper"
+.IX Item "taint_proper"
+Implements the "TAINT_PROPER" macro, which you should generally use instead.
+.RS 4
+.Sp
+.Vb 1
+\& void  taint_proper(const char *f, const char * const s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_set""" 4
+.el .IP \f(CWTAINT_set\fR 4
+.IX Xref "TAINT_set"
+.IX Item "TAINT_set"
+If \f(CW\*(C`s\*(C'\fR is true, "\f(CW\*(C`TAINT_get\*(C'\fR" returns true;
+If \f(CW\*(C`s\*(C'\fR is false, "\f(CW\*(C`TAINT_get\*(C'\fR" returns false;
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_set(bool s)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_WARN_get""" 4
+.el .IP \f(CWTAINT_WARN_get\fR 4
+.IX Xref "TAINT_WARN_get"
+.IX Item "TAINT_WARN_get"
+Returns false if tainting violations are fatal;
+Returns true if they're just warnings
+.RS 4
+.Sp
+.Vb 1
+\& bool  TAINT_WARN_get()
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """TAINT_WARN_set""" 4
+.el .IP \f(CWTAINT_WARN_set\fR 4
+.IX Xref "TAINT_WARN_set"
+.IX Item "TAINT_WARN_set"
+\&\f(CW\*(C`s\*(C'\fR being true indicates "\f(CW\*(C`TAINT_WARN_get\*(C'\fR" should return that tainting
+violations are just warnings
+.Sp
+\&\f(CW\*(C`s\*(C'\fR being false indicates "\f(CW\*(C`TAINT_WARN_get\*(C'\fR" should return that tainting
+violations are fatal.
+.RS 4
+.Sp
+.Vb 1
+\& void  TAINT_WARN_set(bool s)
+.Ve
+.RE
+.RS 4
+.RE
+.SH Time
+.IX Header "Time"
+There are currently no internal API items in Time
+.SH "Typedef names"
+.IX Header "Typedef names"
+There are currently no internal API items in Typedef names
+.SH "Unicode Support"
+.IX Xref "FOLDEQ_LOCALE FOLDEQ_S1_ALREADY_FOLDED FOLDEQ_S1_FOLDS_SANE FOLDEQ_S2_ALREADY_FOLDED FOLDEQ_S2_FOLDS_SANE FOLDEQ_UTF8_NOMIX_ASCII"
+.IX Header "Unicode Support"
+.ie n .IP """bytes_from_utf8_loc""" 4
+.el .IP \f(CWbytes_from_utf8_loc\fR 4
+.IX Xref "bytes_from_utf8_loc"
+.IX Item "bytes_from_utf8_loc"
+NOTE: \f(CW\*(C`bytes_from_utf8_loc\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Like \f(CW\*(C`"bytes_from_utf8" in perlapi()\*(C'\fR, but takes an extra parameter, a pointer
+to where to store the location of the first character in \f(CW"s"\fR that cannot be
+converted to non\-UTF8.
+.Sp
+If that parameter is \f(CW\*(C`NULL\*(C'\fR, this function behaves identically to
+\&\f(CW\*(C`bytes_from_utf8\*(C'\fR.
+.Sp
+Otherwise if \f(CW*is_utf8p\fR is 0 on input, the function behaves identically to
+\&\f(CW\*(C`bytes_from_utf8\*(C'\fR, except it also sets \f(CW*first_non_downgradable\fR to \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Otherwise, the function returns a newly created \f(CW\*(C`NUL\*(C'\fR\-terminated string
+containing the non\-UTF8 equivalent of the convertible first portion of
+\&\f(CW"s"\fR.  \f(CW*lenp\fR is set to its length, not including the terminating \f(CW\*(C`NUL\*(C'\fR.
+If the entire input string was converted, \f(CW*is_utf8p\fR is set to a FALSE value,
+and \f(CW*first_non_downgradable\fR is set to \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Otherwise, \f(CW*first_non_downgradable\fR is set to point to the first byte of the
+first character in the original string that wasn't converted.  \f(CW*is_utf8p\fR is
+unchanged.  Note that the new string may have length 0.
+.Sp
+Another way to look at it is, if \f(CW*first_non_downgradable\fR is non\-\f(CW\*(C`NULL\*(C'\fR and
+\&\f(CW*is_utf8p\fR is TRUE, this function starts at the beginning of \f(CW"s"\fR and
+converts as many characters in it as possible stopping at the first one it
+finds that can't be converted to non\-UTF\-8.  \f(CW*first_non_downgradable\fR is
+set to point to that.  The function returns the portion that could be converted
+in a newly created \f(CW\*(C`NUL\*(C'\fR\-terminated string, and \f(CW*lenp\fR is set to its length,
+not including the terminating \f(CW\*(C`NUL\*(C'\fR.  If the very first character in the
+original could not be converted, \f(CW*lenp\fR will be 0, and the new string will
+contain just a single \f(CW\*(C`NUL\*(C'\fR.  If the entire input string was converted,
+\&\f(CW*is_utf8p\fR is set to FALSE and \f(CW*first_non_downgradable\fR is set to \f(CW\*(C`NULL\*(C'\fR.
+.Sp
+Upon successful return, the number of variants in the converted portion of the
+string can be computed by having saved the value of \f(CW*lenp\fR before the call,
+and subtracting the after-call value of \f(CW*lenp\fR from it.
+.RS 4
+.Sp
+.Vb 3
+\& U8 *  bytes_from_utf8_loc(const U8 *s, STRLEN *lenp,
+\&                           bool *is_utf8p,
+\&                           const U8 **first_unconverted)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """find_uninit_var""" 4
+.el .IP \f(CWfind_uninit_var\fR 4
+.IX Xref "find_uninit_var"
+.IX Item "find_uninit_var"
+NOTE: \f(CW\*(C`find_uninit_var\*(C'\fR is \fBexperimental\fR and may change or be
+removed without notice.
+.Sp
+Find the name of the undefined variable (if any) that caused the operator
+to issue a "Use of uninitialized value" warning.
+If match is true, only return a name if its value matches \f(CW\*(C`uninit_sv\*(C'\fR.
+So roughly speaking, if a unary operator (such as \f(CW\*(C`OP_COS\*(C'\fR) generates a
+warning, then following the direct child of the op may yield an
+\&\f(CW\*(C`OP_PADSV\*(C'\fR or \f(CW\*(C`OP_GV\*(C'\fR that gives the name of the undefined variable.  On the
+other hand, with \f(CW\*(C`OP_ADD\*(C'\fR there are two branches to follow, so we only print
+the variable name if we get an exact match.
+\&\f(CW\*(C`desc_p\*(C'\fR points to a string pointer holding the description of the op.
+This may be updated if needed.
+.Sp
+The name is returned as a mortal SV.
+.Sp
+Assumes that \f(CW\*(C`PL_op\*(C'\fR is the OP that originally triggered the error, and that
+\&\f(CW\*(C`PL_comppad\*(C'\fR/\f(CW\*(C`PL_curpad\*(C'\fR points to the currently executing pad.
+.RS 4
+.Sp
+.Vb 3
+\& SV *  find_uninit_var(const OP * const obase,
+\&                       const SV * const uninit_sv, bool match,
+\&                       const char **desc_p)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """isSCRIPT_RUN""" 4
+.el .IP \f(CWisSCRIPT_RUN\fR 4
+.IX Xref "isSCRIPT_RUN"
+.IX Item "isSCRIPT_RUN"
+Returns a bool as to whether or not the sequence of bytes from \f(CW\*(C`s\*(C'\fR up to but
+not including \f(CW\*(C`send\*(C'\fR form a "script run".  \f(CW\*(C`utf8_target\*(C'\fR is TRUE iff the
+sequence starting at \f(CW\*(C`s\*(C'\fR is to be treated as UTF\-8.  To be precise, except for
+two degenerate cases given below, this function returns TRUE iff all code
+points in it come from any combination of three "scripts" given by the Unicode
+"Script Extensions" property: Common, Inherited, and possibly one other.
+Additionally all decimal digits must come from the same consecutive sequence of
+10.
+.Sp
+For example, if all the characters in the sequence are Greek, or Common, or
+Inherited, this function will return TRUE, provided any decimal digits in it
+are from the same block of digits in Common.  (These are the ASCII digits
+"0".."9" and additionally a block for full width forms of these, and several
+others used in mathematical notation.)   For scripts (unlike Greek) that have
+their own digits defined this will accept either digits from that set or from
+one of the Common digit sets, but not a combination of the two.  Some scripts,
+such as Arabic, have more than one set of digits.  All digits must come from
+the same set for this function to return TRUE.
+.Sp
+\&\f(CW*ret_script\fR, if \f(CW\*(C`ret_script\*(C'\fR is not NULL, will on return of TRUE
+contain the script found, using the \f(CW\*(C`SCX_enum\*(C'\fR typedef.  Its value will be
+\&\f(CW\*(C`SCX_INVALID\*(C'\fR if the function returns FALSE.
+.Sp
+If the sequence is empty, TRUE is returned, but \f(CW*ret_script\fR (if asked for)
+will be \f(CW\*(C`SCX_INVALID\*(C'\fR.
+.Sp
+If the sequence contains a single code point which is unassigned to a character
+in the version of Unicode being used, the function will return TRUE, and the
+script will be \f(CW\*(C`SCX_Unknown\*(C'\fR.  Any other combination of unassigned code points
+in the input sequence will result in the function treating the input as not
+being a script run.
+.Sp
+The returned script will be \f(CW\*(C`SCX_Inherited\*(C'\fR iff all the code points in it are
+from the Inherited script.
+.Sp
+Otherwise, the returned script will be \f(CW\*(C`SCX_Common\*(C'\fR iff all the code points in
+it are from the Inherited or Common scripts.
+.RS 4
+.Sp
+.Vb 2
+\& bool  isSCRIPT_RUN(const U8 *s, const U8 *send,
+\&                    const bool utf8_target)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """is_utf8_non_invariant_string""" 4
+.el .IP \f(CWis_utf8_non_invariant_string\fR 4
+.IX Xref "is_utf8_non_invariant_string"
+.IX Item "is_utf8_non_invariant_string"
+Returns TRUE if "is_utf8_invariant_string" in perlapi returns FALSE for the first
+\&\f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR, but they are, nonetheless, legal Perl-extended
+UTF\-8; otherwise returns FALSE.
+.Sp
+A TRUE return means that at least one code point represented by the sequence
+either is a wide character not representable as a single byte, or the
+representation differs depending on whether the sequence is encoded in UTF\-8 or
+not.
+.Sp
+See also
+\&\f(CW\*(C`"is_utf8_invariant_string" in perlapi\*(C'\fR,
+\&\f(CW\*(C`"is_utf8_string" in perlapi\*(C'\fR
+.RS 4
+.Sp
+.Vb 1
+\& bool  is_utf8_non_invariant_string(const U8 * const s, STRLEN len)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8n_to_uvuni""" 4
+.el .IP \f(CWutf8n_to_uvuni\fR 4
+.IX Xref "utf8n_to_uvuni"
+.IX Item "utf8n_to_uvuni"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`utf8n_to_uvuni\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Instead use "utf8_to_uvchr_buf" in perlapi, or rarely, "utf8n_to_uvchr" in perlapi.
+.Sp
+This function was useful for code that wanted to handle both EBCDIC and
+ASCII platforms with Unicode properties, but starting in Perl v5.20, the
+distinctions between the platforms have mostly been made invisible to most
+code, so this function is quite unlikely to be what you want.  If you do need
+this precise functionality, use instead
+\&\f(CW\*(C`NATIVE_TO_UNI(utf8_to_uvchr_buf(...))\*(C'\fR
+or \f(CW\*(C`NATIVE_TO_UNI(utf8n_to_uvchr(...))\*(C'\fR.
+.RS 4
+.Sp
+.Vb 2
+\& UV  utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen,
+\&                    U32 flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """utf8_to_uvuni""" 4
+.el .IP \f(CWutf8_to_uvuni\fR 4
+.IX Xref "utf8_to_uvuni"
+.IX Item "utf8_to_uvuni"
+\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR  It is planned to remove \f(CW\*(C`utf8_to_uvuni\*(C'\fR
+from a future release of Perl.  Do not use it for
+new code; remove it from existing code.
+.Sp
+Returns the Unicode code point of the first character in the string \f(CW\*(C`s\*(C'\fR
+which is assumed to be in UTF\-8 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the
+length, in bytes, of that character.
+.Sp
+Some, but not all, UTF\-8 malformations are detected, and in fact, some
+malformed input could cause reading beyond the end of the input buffer, which
+is one reason why this function is deprecated.  The other is that only in
+extremely limited circumstances should the Unicode versus native code point be
+of any interest to you.
+.Sp
+If \f(CW\*(C`s\*(C'\fR points to one of the detected malformations, and UTF8 warnings are
+enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR doesn't point to
+NULL) to \-1.  If those warnings are off, the computed value if well-defined (or
+the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and \f(CW*retlen\fR
+is set (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the
+next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
+See "utf8n_to_uvchr" in perlapi for details on when the REPLACEMENT CHARACTER is returned.
+.RS 4
+.Sp
+.Vb 1
+\& UV  utf8_to_uvuni(const U8 *s, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """uvoffuni_to_utf8_flags""" 4
+.el .IP \f(CWuvoffuni_to_utf8_flags\fR 4
+.IX Xref "uvoffuni_to_utf8_flags"
+.IX Item "uvoffuni_to_utf8_flags"
+THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
+Instead, \fBAlmost all code should use "uvchr_to_utf8" in perlapi or
+"uvchr_to_utf8_flags" in perlapi\fR.
+.Sp
+This function is like them, but the input is a strict Unicode
+(as opposed to native) code point.  Only in very rare circumstances should code
+not be using the native code point.
+.Sp
+For details, see the description for "uvchr_to_utf8_flags" in perlapi.
+.RS 4
+.Sp
+.Vb 1
+\& U8 *  uvoffuni_to_utf8_flags(U8 *d, UV uv, UV flags)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """valid_utf8_to_uvchr""" 4
+.el .IP \f(CWvalid_utf8_to_uvchr\fR 4
+.IX Xref "valid_utf8_to_uvchr"
+.IX Item "valid_utf8_to_uvchr"
+Like \f(CW\*(C`"utf8_to_uvchr_buf" in perlapi\*(C'\fR, but should only be called when it is
+known that the next character in the input UTF\-8 string \f(CW\*(C`s\*(C'\fR is well-formed
+(\fIe.g.\fR, it passes \f(CW\*(C`"isUTF8_CHAR" in perlapi\*(C'\fR.  Surrogates, non-character code
+points, and non-Unicode code points are allowed.
+.RS 4
+.Sp
+.Vb 1
+\& UV  valid_utf8_to_uvchr(const U8 *s, STRLEN *retlen)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """variant_under_utf8_count""" 4
+.el .IP \f(CWvariant_under_utf8_count\fR 4
+.IX Xref "variant_under_utf8_count"
+.IX Item "variant_under_utf8_count"
+This function looks at the sequence of bytes between \f(CW\*(C`s\*(C'\fR and \f(CW\*(C`e\*(C'\fR, which are
+assumed to be encoded in ASCII/Latin1, and returns how many of them would
+change should the string be translated into UTF\-8.  Due to the nature of UTF\-8,
+each of these would occupy two bytes instead of the single one in the input
+string.  Thus, this function returns the precise number of bytes the string
+would expand by when translated to UTF\-8.
+.Sp
+Unlike most of the other functions that have \f(CW\*(C`utf8\*(C'\fR in their name, the input
+to this function is NOT a UTF\-8\-encoded string.  The function name is slightly
+\&\fIodd\fR to emphasize this.
+.Sp
+This function is internal to Perl because khw thinks that any XS code that
+would want this is probably operating too close to the internals.  Presenting a
+valid use case could change that.
+.Sp
+See also
+\&\f(CW\*(C`"is_utf8_invariant_string" in perlapi\*(C'\fR
+and
+\&\f(CW\*(C`"is_utf8_invariant_string_loc" in perlapi\*(C'\fR,
+.RS 4
+.Sp
+.Vb 2
+\& Size_t  variant_under_utf8_count(const U8 * const s,
+\&                                  const U8 * const e)
+.Ve
+.RE
+.RS 4
+.RE
+.SH "Utility Functions"
+.IX Header "Utility Functions"
+.ie n .IP """my_popen_list""" 4
+.el .IP \f(CWmy_popen_list\fR 4
+.IX Xref "my_popen_list"
+.IX Item "my_popen_list"
+Implementing function on some systems for \fBPerlProc_popen_list()\fR
+.RS 4
+.Sp
+.Vb 1
+\& PerlIO *  my_popen_list(const char *mode, int n, SV **args)
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """my_socketpair""" 4
+.el .IP \f(CWmy_socketpair\fR 4
+.IX Xref "my_socketpair"
+.IX Item "my_socketpair"
+Emulates \fBsocketpair\fR\|(2) on systems that don't have it, but which do have
+enough functionality for the emulation.
+.RS 4
+.Sp
+.Vb 1
+\& int  my_socketpair(int family, int type, int protocol, int fd[2])
+.Ve
+.RE
+.RS 4
+.RE
+.SH Versioning
+.IX Header "Versioning"
+There are currently no internal API items in Versioning
+.SH "Warning and Dieing"
+.IX Header "Warning and Dieing"
+.ie n .IP """deprecate""" 4
+.el .IP \f(CWdeprecate\fR 4
+.IX Xref "deprecate"
+.IX Item "deprecate"
+Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
+given category with an appropriate message. The \f(CW\*(C`message\*(C'\fR argument must
+be a C string. The string " is deprecated" will automatically be added
+to the end of the \f(CW\*(C`message\*(C'\fR.
+.RS 4
+.Sp
+.Vb 1
+\&   deprecate(U32 category, "message")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """deprecate_disappears_in""" 4
+.el .IP \f(CWdeprecate_disappears_in\fR 4
+.IX Xref "deprecate_disappears_in"
+.IX Item "deprecate_disappears_in"
+Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
+given category with an appropriate message that the construct referred
+to by the message will disappear in a specific release.  The \f(CW\*(C`when\*(C'\fR and
+\&\f(CW\*(C`message\*(C'\fR arguments must be a C string.  The \f(CW\*(C`when\*(C'\fR string is expected
+to be of the form "5.40", with no minor element in the version.  The actual
+message output will be the result of the following expression \f(CW\*(C`message
+" is deprecated, and will disappear in Perl " when\*(C'\fR which is why \f(CW\*(C`message\*(C'\fR
+and \f(CW\*(C`when\*(C'\fR must be literal C strings.
+.RS 4
+.Sp
+.Vb 1
+\&   deprecate_disappears_in(U32 category, "when", "message")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """deprecate_fatal_in""" 4
+.el .IP \f(CWdeprecate_fatal_in\fR 4
+.IX Xref "deprecate_fatal_in"
+.IX Item "deprecate_fatal_in"
+Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
+given category with an appropriate message that the construct referred
+to by the message will become fatal in a specific release.  The \f(CW\*(C`when\*(C'\fR
+and \f(CW\*(C`message\*(C'\fR arguments must be a C string.  The \f(CW\*(C`when\*(C'\fR string is expected
+to be of the form "5.40", with no minor element in the version.  The actual
+message output will be the result of the following expression \f(CW\*(C`message " is
+deprecated, and will become fatal in Perl " when\*(C'\fR which is why \f(CW\*(C`message\*(C'\fR
+and \f(CW\*(C`when\*(C'\fR must be literal C strings.
+.RS 4
+.Sp
+.Vb 1
+\&   deprecate_fatal_in(U32 category, "when", "message")
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """PL_dowarn""" 4
+.el .IP \f(CWPL_dowarn\fR 4
+.IX Xref "PL_dowarn"
+.IX Item "PL_dowarn"
+The C variable that roughly corresponds to Perl's \f(CW$^W\fR warning variable.
+However, \f(CW$^W\fR is treated as a boolean, whereas \f(CW\*(C`PL_dowarn\*(C'\fR is a
+collection of flag bits.
+.Sp
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+.RS 4
+.Sp
+.Vb 1
+\& U8  PL_dowarn
+.Ve
+.RE
+.RS 4
+.RE
+.ie n .IP """report_uninit""" 4
+.el .IP \f(CWreport_uninit\fR 4
+.IX Xref "report_uninit"
+.IX Item "report_uninit"
+Print appropriate "Use of uninitialized variable" warning.
+.RS 4
+.Sp
+.Vb 1
+\& void  report_uninit(const SV *uninit_sv)
+.Ve
+.RE
+.RS 4
+.RE
+.SH XS
+.IX Header "XS"
+There are currently no internal API items in XS
+.SH "Undocumented elements"
+.IX Header "Undocumented elements"
+This section lists the elements that are otherwise undocumented.  If you use
+any of them, please consider creating and submitting documentation for it.
+.PP
+Experimental and deprecated undocumented elements are listed separately at the
+end.
+.PP
+
+.IX Xref "abort_execution add_above_Latin1_folds add_cp_to_invlist _add_range_to_invlist allocmy amagic_cmp amagic_cmp_desc amagic_cmp_locale amagic_cmp_locale_desc amagic_i_ncmp amagic_i_ncmp_desc amagic_is_enabled amagic_ncmp amagic_ncmp_desc any_dup append_utf8_from_native_byte apply atfork_lock atfork_unlock av_arylen_p av_extend_guts av_iter_p av_nonelem av_reify bind_match block_gimme boot_core_builtin boot_core_mro boot_core_PerlIO boot_core_UNIVERSAL build_infix_plugin _byte_dump_string call_list cando capture_clear cast_iv cast_i32 cast_ulong cast_uv check_hash_fields_and_hekify check_regnode_after check_utf8_print ck_anoncode ck_backtick ck_bitop ck_cmp ck_concat ck_defined ck_delete ck_each ck_entersub_args_core ck_eof ck_eval ck_exec ck_exists ck_ftst ck_fun ck_glob ck_grep ck_helemexistsor ck_index ck_isa ck_join ck_length ck_lfun ck_listiob ck_match ck_method ck_null ck_open ck_prototype ck_readline ck_refassign ck_repeat ck_require ck_return ck_rfun ck_rvconst ck_sassign ck_select ck_shift ck_smartmatch ck_sort ck_spair ck_split ck_stringify ck_subr ck_substr ck_svconst ck_tell ck_trunc ck_trycatch ckwarn ckwarn_d class_add_ADJUST class_add_field class_apply_attributes class_apply_field_attributes class_prepare_initfield_parse class_prepare_method_parse class_seal_stash class_set_field_defop class_setup_stash class_wrap_method_body clear_defarray closest_cop cmpchain_extend cmpchain_finish cmpchain_start cmp_desc cmp_locale_desc cntrl_to_mnemonic construct_ahocorasick_from_trie cop_file_avn coresub_op croak_caller croak_kw_unless_class croak_memory_wrap croak_no_mem croak_popstack csighandler csighandler1 csighandler3 current_re_engine custom_op_get_field cv_clone_into cv_const_sv_or_av cvgv_from_hek cvgv_set cvstash_set cv_undef_flags cx_dump cx_dup cxinc deb_stack_all debstackptrs debug_hash_seed debug_peep debug_show_study_flags debug_studydata defelem_target despatch_signals die_unwind do_aexec do_aexec5 do_aspawn do_eof does_utf8_overflow do_exec do_exec3 dofile do_gv_dump do_gvgv_dump do_hv_dump doing_taint do_ipcctl do_ipcget do_magic_dump do_msgrcv do_msgsnd do_ncmp do_op_dump do_pmop_dump do_print do_readline doref do_seek do_semop do_shmio do_spawn do_spawn_nowait do_sv_dump do_sysseek do_tell do_trans do_uniprop_match do_vecget do_vecset do_vop drand48_init_r drand48_r dtrace_probe_call dtrace_probe_load dtrace_probe_op dtrace_probe_phase dump_all_perl dump_indent dump_packsubs_perl dump_sub_perl dump_sv_child dumpuntil dump_vindent dup_warnings find_first_differing_byte_pos find_lexical_cv find_runcv_where find_script foldEQ_latin1_s2_folded foldEQ_latin1 foldEQ_utf8_flags force_locale_unlock _force_out_malformed_utf8_message form_alien_digit_msg form_cp_too_large_msg free_tied_hv_pool free_tmps get_and_check_backslash_N_name get_ANYOFHbbm_contents get_ANYOFM_contents get_db_sub get_debug_opts get_deprecated_property_msg getenv_len get_extended_os_errno get_hash_seed get_invlist_iter_addr get_invlist_offset_addr get_invlist_previous_index_addr get_mstats get_prop_definition get_prop_values get_regclass_aux_data get_re_gclass_aux_data get_regex_charset_name get_win32_message_utf8ness gp_free gp_ref grok_bin_oct_hex grok_bslash_c grok_bslash_o grok_bslash_x gv_check gv_fetchmeth_internal gv_override gv_setref gv_stashpvn_internal he_dup hek_dup hfree_next_entry hv_auxalloc hv_common hv_common_key_len hv_delayfree_ent hv_free_ent hv_placeholders_p hv_pushkv hv_rand_set hv_undef_flags infix_plugin_standard init_argv_symbols init_constants init_dbargs init_debugger init_i18nl10n init_named_cv init_stacks init_tm init_uniprops _inverse_folds invert invlist_array _invlist_array_init invlist_clear invlist_clone _invlist_contains_cp invlist_contents _invlist_dump _invlistEQ invlist_extend invlist_highest _invlist_intersection _invlist_intersection_maybe_complement_2nd _invlist_invert invlist_is_iterating invlist_iterfinish invlist_iterinit invlist_iternext _invlist_len invlist_max invlist_previous_index _invlist_search invlist_set_len invlist_set_previous_index _invlist_subtract invlist_trim _invlist_union _invlist_union_maybe_complement_2nd invmap_dump invoke_exception_hook io_close isFF_overlong is_grapheme _is_in_locale_category is_invlist is_ssc_worth_it _is_uni_FOO _is_uni_perl_idcont _is_uni_perl_idstart is_utf8_char_helper_ is_utf8_common is_utf8_FF_helper_ _is_utf8_FOO is_utf8_overlong _is_utf8_perl_idcont _is_utf8_perl_idstart jmaybe join_exact keyword keyword_plugin_standard list load_charnames locale_panic localize lossless_NV_to_IV lsbit_pos32 lsbit_pos64 magic_clear_all_env magic_cleararylen_p magic_clearenv magic_clearhook magic_clearhookall magic_clearisa magic_clearpack magic_clearsig magic_copycallchecker magic_existspack magic_freearylen_p magic_freecollxfrm magic_freemglob magic_freeovrld magic_freeutf8 magic_get magic_getarylen magic_getdebugvar magic_getdefelem magic_getnkeys magic_getpack magic_getpos magic_getsig magic_getsubstr magic_gettaint magic_getuvar magic_getvec magic_killbackrefs magic_nextpack magic_regdata_cnt magic_regdatum_get magic_regdatum_set magic_scalarpack magic_set magic_set_all_env magic_setarylen magic_setcollxfrm magic_setdbline magic_setdebugvar magic_setdefelem magic_setenv magic_sethook magic_sethookall magic_setisa magic_setlvref magic_setmglob magic_setnkeys magic_setnonelem magic_setpack magic_setpos magic_setregexp magic_setsig magic_setsigall magic_setsubstr magic_settaint magic_setutf8 magic_setuvar magic_setvec magic_sizepack magic_wipepack make_trie malloced_size malloc_good_size markstack_grow mbtowc_ mem_collxfrm_ mem_log_alloc mem_log_del_sv mem_log_free mem_log_new_sv mem_log_realloc mg_find_mglob mg_size mode_from_discipline more_bodies more_sv moreswitches mortal_getenv mortalized_pv_copy mro_get_private_data mro_meta_dup mro_meta_init msbit_pos32 msbit_pos64 multiconcat_stringify multideref_stringify my_atof2 my_atof3 my_attrs my_clearenv my_lstat my_lstat_flags my_memrchr my_mkostemp_cloexec my_mkstemp_cloexec my_stat my_stat_flags my_strerror my_strftime8_temp my_unexec newFORM _new_invlist _new_invlist_C_array newMETHOP_internal newMYSUB newPROG new_stackinfo newSTUB newSVavdefelem newXS_deffile nextargv no_bareword_allowed no_bareword_filehandle noperl_die notify_parser_that_changed_to_utf8 oopsAV oopsHV op_clear op_integerize op_lvalue_flags opmethod_stash op_prune_chain_head op_relocate_sv opslab_force_free opslab_free opslab_free_nopad op_std_init op_varname package package_version pad_add_weakref padlist_store padname_free PadnameIN_SCOPE padnamelist_free parser_dup parser_free parser_free_nexttoke_ops parse_unicode_opts path_is_searchable peep perl_alloc_using perl_clone_using PerlEnv_putenv PerlIO_context_layers PerlIO_restore_errno PerlIO_save_errno PerlLIO_dup_cloexec PerlLIO_dup2_cloexec PerlLIO_open_cloexec PerlLIO_open3_cloexec PerlProc_pipe_cloexec PerlSock_accept_cloexec PerlSock_socket_cloexec PerlSock_socketpair_cloexec perly_sighandler pmruntime POPMARK populate_anyof_bitmap_from_invlist populate_bitmap_from_invlist populate_invlist_from_bitmap populate_isa pregfree pregfree2 ptr_hash qerror ReANY reentrant_free reentrant_init reentrant_retry reentrant_size re_exec_indentf ref reg_add_data regcurly regdump regdupe_internal regexec_flags regfree_internal reginitcolors reg_named_buff reg_named_buff_all reg_named_buff_exists reg_named_buff_fetch reg_named_buff_firstkey reg_named_buff_iter reg_named_buff_nextkey reg_named_buff_scalar regnext regnode_after reg_numbered_buff_fetch reg_numbered_buff_fetch_flags reg_numbered_buff_length reg_numbered_buff_store regprop reg_qr_package reg_skipcomment reg_temp_copy re_indentf re_intuit_start re_intuit_string re_op_compile report_evil_fh report_redefined_cv report_wrongway_fh re_printf rpeep rsignal_restore rsignal_save rvpv_dup rxres_save same_dirent save_bool save_clearsv save_delete save_destructor save_destructor_x save_freeop save_freepv save_freesv save_int save_iv save_I8 save_I16 save_I32 save_mortalizesv save_pptr save_pushi32ptr save_pushptrptr save_re_context save_sptr savestack_grow savestack_grow_cnt save_strlen sawparens scalar scalarvoid scan_commit scan_num seed set_ANYOF_arg set_caret_X setfd_cloexec setfd_cloexec_for_nonsysfd setfd_cloexec_or_inhexec_by_sysfdness setfd_inhexec setfd_inhexec_for_sysfd set_numeric_standard set_numeric_underlying set_padlist _setup_canned_invlist share_hek should_warn_nl should_we_output_Debug_r sighandler sighandler1 sighandler3 single_1bit_pos32 single_1bit_pos64 Slab_Alloc Slab_Free Slab_to_ro Slab_to_rw softref2xv sortsv_flags_impl ssc_finalize ssc_init stack_grow str_to_version strxfrm study_chunk sub_crush_depth sv_add_backref sv_buf_to_ro sv_del_backref sv_i_ncmp sv_i_ncmp_desc sv_2iv sv_magicext_mglob sv_ncmp sv_ncmp_desc sv_only_taint_gmagic sv_or_pv_pos_u2b sv_pvbyten_force_wrapper sv_pvutf8n_force_wrapper sv_resetpvn sv_sethek SvTRUE_common sv_unglob sv_2uv switch_locale_context sys_init sys_init3 sys_intern_clear sys_intern_dup sys_intern_init sys_term tied_method tmps_grow_p _to_fold_latin1 TOPMARK to_uni_fold _to_uni_fold_flags to_uni_lower to_uni_title to_uni_upper _to_upper_title_latin1 _to_utf8_fold_flags _to_utf8_lower_flags _to_utf8_title_flags _to_utf8_upper_flags translate_substr_offsets try_amagic_bin try_amagic_un uiv_2buf unlnk unshare_hek unwind_paren _utf8n_to_uvchr_msgs_helper utf16_to_utf8_base utf16_to_utf8_reversed utf16_to_utf8 utf8_to_uvchr_buf_helper utilize uvoffuni_to_utf8_flags_msgs uvuni_to_utf8 variant_byte_number varname vivify_defelem vivify_ref wait4pid warn_elem_scalar_context _warn_problematic_locale was_lvalue_sub watch win32_croak_not_implemented write_to_stderr xs_boot_epilog xs_handshake yyerror yyerror_pv yyerror_pvn yylex yyparse yyquit yyunlex"
+.PP
+.Vb 10
+\& abort_execution
+\& add_above_Latin1_folds
+\& add_cp_to_invlist
+\& _add_range_to_invlist
+\& allocmy
+\& amagic_cmp
+\& amagic_cmp_desc
+\& amagic_cmp_locale
+\& amagic_cmp_locale_desc
+\& amagic_i_ncmp
+\& amagic_i_ncmp_desc
+\& amagic_is_enabled
+\& amagic_ncmp
+\& amagic_ncmp_desc
+\& any_dup
+\& append_utf8_from_native_byte
+\& apply
+\& atfork_lock
+\& atfork_unlock
+\& av_arylen_p
+\& av_extend_guts
+\& av_iter_p
+\& av_nonelem
+\& av_reify
+\& bind_match
+\& block_gimme
+\& boot_core_builtin
+\& boot_core_mro
+\& boot_core_PerlIO
+\& boot_core_UNIVERSAL
+\& build_infix_plugin
+\& _byte_dump_string
+\& call_list
+\& cando
+\& capture_clear
+\& cast_iv
+\& cast_i32
+\& cast_ulong
+\& cast_uv
+\& check_hash_fields_and_hekify
+\& check_regnode_after
+\& check_utf8_print
+\& ck_anoncode
+\& ck_backtick
+\& ck_bitop
+\& ck_cmp
+\& ck_concat
+\& ck_defined
+\& ck_delete
+\& ck_each
+\& ck_entersub_args_core
+\& ck_eof
+\& ck_eval
+\& ck_exec
+\& ck_exists
+\& ck_ftst
+\& ck_fun
+\& ck_glob
+\& ck_grep
+\& ck_helemexistsor
+\& ck_index
+\& ck_isa
+\& ck_join
+\& ck_length
+\& ck_lfun
+\& ck_listiob
+\& ck_match
+\& ck_method
+\& ck_null
+\& ck_open
+\& ck_prototype
+\& ck_readline
+\& ck_refassign
+\& ck_repeat
+\& ck_require
+\& ck_return
+\& ck_rfun
+\& ck_rvconst
+\& ck_sassign
+\& ck_select
+\& ck_shift
+\& ck_smartmatch
+\& ck_sort
+\& ck_spair
+\& ck_split
+\& ck_stringify
+\& ck_subr
+\& ck_substr
+\& ck_svconst
+\& ck_tell
+\& ck_trunc
+\& ck_trycatch
+\& ckwarn
+\& ckwarn_d
+\& class_add_ADJUST
+\& class_add_field
+\& class_apply_attributes
+\& class_apply_field_attributes
+\& class_prepare_initfield_parse
+\& class_prepare_method_parse
+\& class_seal_stash
+\& class_set_field_defop
+\& class_setup_stash
+\& class_wrap_method_body
+\& clear_defarray
+\& closest_cop
+\& cmpchain_extend
+\& cmpchain_finish
+\& cmpchain_start
+\& cmp_desc
+\& cmp_locale_desc
+\& cntrl_to_mnemonic
+\& construct_ahocorasick_from_trie
+\& cop_file_avn
+\& coresub_op
+\& croak_caller
+\& croak_kw_unless_class
+\& croak_memory_wrap
+\& croak_no_mem
+\& croak_popstack
+\& csighandler
+\& csighandler1
+\& csighandler3
+\& current_re_engine
+\& custom_op_get_field
+\& cv_clone_into
+\& cv_const_sv_or_av
+\& cvgv_from_hek
+\& cvgv_set
+\& cvstash_set
+\& cv_undef_flags
+\& cx_dump
+\& cx_dup
+\& cxinc
+\& deb_stack_all
+\& debstackptrs
+\& debug_hash_seed
+\& debug_peep
+\& debug_show_study_flags
+\& debug_studydata
+\& defelem_target
+\& despatch_signals
+\& die_unwind
+\& do_aexec
+\& do_aexec5
+\& do_aspawn
+\& do_eof
+\& does_utf8_overflow
+\& do_exec
+\& do_exec3
+\& dofile
+\& do_gv_dump
+\& do_gvgv_dump
+\& do_hv_dump
+\& doing_taint
+\& do_ipcctl
+\& do_ipcget
+\& do_magic_dump
+\& do_msgrcv
+\& do_msgsnd
+\& do_ncmp
+\& do_op_dump
+\& do_pmop_dump
+\& do_print
+\& do_readline
+\& doref
+\& do_seek
+\& do_semop
+\& do_shmio
+\& do_spawn
+\& do_spawn_nowait
+\& do_sv_dump
+\& do_sysseek
+\& do_tell
+\& do_trans
+\& do_uniprop_match
+\& do_vecget
+\& do_vecset
+\& do_vop
+\& drand48_init_r
+\& drand48_r
+\& dtrace_probe_call
+\& dtrace_probe_load
+\& dtrace_probe_op
+\& dtrace_probe_phase
+\& dump_all_perl
+\& dump_indent
+\& dump_packsubs_perl
+\& dump_sub_perl
+\& dump_sv_child
+\& dumpuntil
+\& dump_vindent
+\& dup_warnings
+\& find_first_differing_byte_pos
+\& find_lexical_cv
+\& find_runcv_where
+\& find_script
+\& foldEQ_latin1_s2_folded
+\& foldEQ_latin1
+\& foldEQ_utf8_flags
+\& force_locale_unlock
+\& _force_out_malformed_utf8_message
+\& form_alien_digit_msg
+\& form_cp_too_large_msg
+\& free_tied_hv_pool
+\& free_tmps
+\& get_and_check_backslash_N_name
+\& get_ANYOFHbbm_contents
+\& get_ANYOFM_contents
+\& get_db_sub
+\& get_debug_opts
+\& get_deprecated_property_msg
+\& getenv_len
+\& get_extended_os_errno
+\& get_hash_seed
+\& get_invlist_iter_addr
+\& get_invlist_offset_addr
+\& get_invlist_previous_index_addr
+\& get_mstats
+\& get_prop_definition
+\& get_prop_values
+\& get_regclass_aux_data
+\& get_re_gclass_aux_data
+\& get_regex_charset_name
+\& get_win32_message_utf8ness
+\& gp_free
+\& gp_ref
+\& grok_bin_oct_hex
+\& grok_bslash_c
+\& grok_bslash_o
+\& grok_bslash_x
+\& gv_check
+\& gv_fetchmeth_internal
+\& gv_override
+\& gv_setref
+\& gv_stashpvn_internal
+\& he_dup
+\& hek_dup
+\& hfree_next_entry
+\& hv_auxalloc
+\& hv_common
+\& hv_common_key_len
+\& hv_delayfree_ent
+\& hv_free_ent
+\& hv_placeholders_p
+\& hv_pushkv
+\& hv_rand_set
+\& hv_undef_flags
+\& infix_plugin_standard
+\& init_argv_symbols
+\& init_constants
+\& init_dbargs
+\& init_debugger
+\& init_i18nl10n
+\& init_named_cv
+\& init_stacks
+\& init_tm
+\& init_uniprops
+\& _inverse_folds
+\& invert
+\& invlist_array
+\& _invlist_array_init
+\& invlist_clear
+\& invlist_clone
+\& _invlist_contains_cp
+\& invlist_contents
+\& _invlist_dump
+\& _invlistEQ
+\& invlist_extend
+\& invlist_highest
+\& _invlist_intersection
+\& _invlist_intersection_maybe_complement_2nd
+\& _invlist_invert
+\& invlist_is_iterating
+\& invlist_iterfinish
+\& invlist_iterinit
+\& invlist_iternext
+\& _invlist_len
+\& invlist_max
+\& invlist_previous_index
+\& _invlist_search
+\& invlist_set_len
+\& invlist_set_previous_index
+\& _invlist_subtract
+\& invlist_trim
+\& _invlist_union
+\& _invlist_union_maybe_complement_2nd
+\& invmap_dump
+\& invoke_exception_hook
+\& io_close
+\& isFF_overlong
+\& is_grapheme
+\& _is_in_locale_category
+\& is_invlist
+\& is_ssc_worth_it
+\& _is_uni_FOO
+\& _is_uni_perl_idcont
+\& _is_uni_perl_idstart
+\& is_utf8_char_helper_
+\& is_utf8_common
+\& is_utf8_FF_helper_
+\& _is_utf8_FOO
+\& is_utf8_overlong
+\& _is_utf8_perl_idcont
+\& _is_utf8_perl_idstart
+\& jmaybe
+\& join_exact
+\& keyword
+\& keyword_plugin_standard
+\& list
+\& load_charnames
+\& locale_panic
+\& localize
+\& lossless_NV_to_IV
+\& lsbit_pos32
+\& lsbit_pos64
+\& magic_clear_all_env
+\& magic_cleararylen_p
+\& magic_clearenv
+\& magic_clearhook
+\& magic_clearhookall
+\& magic_clearisa
+\& magic_clearpack
+\& magic_clearsig
+\& magic_copycallchecker
+\& magic_existspack
+\& magic_freearylen_p
+\& magic_freecollxfrm
+\& magic_freemglob
+\& magic_freeovrld
+\& magic_freeutf8
+\& magic_get
+\& magic_getarylen
+\& magic_getdebugvar
+\& magic_getdefelem
+\& magic_getnkeys
+\& magic_getpack
+\& magic_getpos
+\& magic_getsig
+\& magic_getsubstr
+\& magic_gettaint
+\& magic_getuvar
+\& magic_getvec
+\& magic_killbackrefs
+\& magic_nextpack
+\& magic_regdata_cnt
+\& magic_regdatum_get
+\& magic_regdatum_set
+\& magic_scalarpack
+\& magic_set
+\& magic_set_all_env
+\& magic_setarylen
+\& magic_setcollxfrm
+\& magic_setdbline
+\& magic_setdebugvar
+\& magic_setdefelem
+\& magic_setenv
+\& magic_sethook
+\& magic_sethookall
+\& magic_setisa
+\& magic_setlvref
+\& magic_setmglob
+\& magic_setnkeys
+\& magic_setnonelem
+\& magic_setpack
+\& magic_setpos
+\& magic_setregexp
+\& magic_setsig
+\& magic_setsigall
+\& magic_setsubstr
+\& magic_settaint
+\& magic_setutf8
+\& magic_setuvar
+\& magic_setvec
+\& magic_sizepack
+\& magic_wipepack
+\& make_trie
+\& malloced_size
+\& malloc_good_size
+\& markstack_grow
+\& mbtowc_
+\& mem_collxfrm_
+\& mem_log_alloc
+\& mem_log_del_sv
+\& mem_log_free
+\& mem_log_new_sv
+\& mem_log_realloc
+\& mg_find_mglob
+\& mg_size
+\& mode_from_discipline
+\& more_bodies
+\& more_sv
+\& moreswitches
+\& mortal_getenv
+\& mortalized_pv_copy
+\& mro_get_private_data
+\& mro_meta_dup
+\& mro_meta_init
+\& msbit_pos32
+\& msbit_pos64
+\& multiconcat_stringify
+\& multideref_stringify
+\& my_atof2
+\& my_atof3
+\& my_attrs
+\& my_clearenv
+\& my_lstat
+\& my_lstat_flags
+\& my_memrchr
+\& my_mkostemp_cloexec
+\& my_mkstemp_cloexec
+\& my_stat
+\& my_stat_flags
+\& my_strerror
+\& my_strftime8_temp
+\& my_unexec
+\& newFORM
+\& _new_invlist
+\& _new_invlist_C_array
+\& newMETHOP_internal
+\& newMYSUB
+\& newPROG
+\& new_stackinfo
+\& newSTUB
+\& newSVavdefelem
+\& newXS_deffile
+\& nextargv
+\& no_bareword_allowed
+\& no_bareword_filehandle
+\& noperl_die
+\& notify_parser_that_changed_to_utf8
+\& oopsAV
+\& oopsHV
+\& op_clear
+\& op_integerize
+\& op_lvalue_flags
+\& opmethod_stash
+\& op_prune_chain_head
+\& op_relocate_sv
+\& opslab_force_free
+\& opslab_free
+\& opslab_free_nopad
+\& op_std_init
+\& op_varname
+\& package
+\& package_version
+\& pad_add_weakref
+\& padlist_store
+\& padname_free
+\& PadnameIN_SCOPE
+\& padnamelist_free
+\& parser_dup
+\& parser_free
+\& parser_free_nexttoke_ops
+\& parse_unicode_opts
+\& path_is_searchable
+\& peep
+\& perl_alloc_using
+\& perl_clone_using
+\& PerlEnv_putenv
+\& PerlIO_context_layers
+\& PerlIO_restore_errno
+\& PerlIO_save_errno
+\& PerlLIO_dup_cloexec
+\& PerlLIO_dup2_cloexec
+\& PerlLIO_open_cloexec
+\& PerlLIO_open3_cloexec
+\& PerlProc_pipe_cloexec
+\& PerlSock_accept_cloexec
+\& PerlSock_socket_cloexec
+\& PerlSock_socketpair_cloexec
+\& perly_sighandler
+\& pmruntime
+\& POPMARK
+\& populate_anyof_bitmap_from_invlist
+\& populate_bitmap_from_invlist
+\& populate_invlist_from_bitmap
+\& populate_isa
+\& pregfree
+\& pregfree2
+\& ptr_hash
+\& qerror
+\& ReANY
+\& reentrant_free
+\& reentrant_init
+\& reentrant_retry
+\& reentrant_size
+\& re_exec_indentf
+\& ref
+\& reg_add_data
+\& regcurly
+\& regdump
+\& regdupe_internal
+\& regexec_flags
+\& regfree_internal
+\& reginitcolors
+\& reg_named_buff
+\& reg_named_buff_all
+\& reg_named_buff_exists
+\& reg_named_buff_fetch
+\& reg_named_buff_firstkey
+\& reg_named_buff_iter
+\& reg_named_buff_nextkey
+\& reg_named_buff_scalar
+\& regnext
+\& regnode_after
+\& reg_numbered_buff_fetch
+\& reg_numbered_buff_fetch_flags
+\& reg_numbered_buff_length
+\& reg_numbered_buff_store
+\& regprop
+\& reg_qr_package
+\& reg_skipcomment
+\& reg_temp_copy
+\& re_indentf
+\& re_intuit_start
+\& re_intuit_string
+\& re_op_compile
+\& report_evil_fh
+\& report_redefined_cv
+\& report_wrongway_fh
+\& re_printf
+\& rpeep
+\& rsignal_restore
+\& rsignal_save
+\& rvpv_dup
+\& rxres_save
+\& same_dirent
+\& save_bool
+\& save_clearsv
+\& save_delete
+\& save_destructor
+\& save_destructor_x
+\& save_freeop
+\& save_freepv
+\& save_freesv
+\& save_int
+\& save_iv
+\& save_I8
+\& save_I16
+\& save_I32
+\& save_mortalizesv
+\& save_pptr
+\& save_pushi32ptr
+\& save_pushptrptr
+\& save_re_context
+\& save_sptr
+\& savestack_grow
+\& savestack_grow_cnt
+\& save_strlen
+\& sawparens
+\& scalar
+\& scalarvoid
+\& scan_commit
+\& scan_num
+\& seed
+\& set_ANYOF_arg
+\& set_caret_X
+\& setfd_cloexec
+\& setfd_cloexec_for_nonsysfd
+\& setfd_cloexec_or_inhexec_by_sysfdness
+\& setfd_inhexec
+\& setfd_inhexec_for_sysfd
+\& set_numeric_standard
+\& set_numeric_underlying
+\& set_padlist
+\& _setup_canned_invlist
+\& share_hek
+\& should_warn_nl
+\& should_we_output_Debug_r
+\& sighandler
+\& sighandler1
+\& sighandler3
+\& single_1bit_pos32
+\& single_1bit_pos64
+\& Slab_Alloc
+\& Slab_Free
+\& Slab_to_ro
+\& Slab_to_rw
+\& softref2xv
+\& sortsv_flags_impl
+\& ssc_finalize
+\& ssc_init
+\& stack_grow
+\& str_to_version
+\& strxfrm
+\& study_chunk
+\& sub_crush_depth
+\& sv_add_backref
+\& sv_buf_to_ro
+\& sv_del_backref
+\& sv_i_ncmp
+\& sv_i_ncmp_desc
+\& sv_2iv
+\& sv_magicext_mglob
+\& sv_ncmp
+\& sv_ncmp_desc
+\& sv_only_taint_gmagic
+\& sv_or_pv_pos_u2b
+\& sv_pvbyten_force_wrapper
+\& sv_pvutf8n_force_wrapper
+\& sv_resetpvn
+\& sv_sethek
+\& SvTRUE_common
+\& sv_unglob
+\& sv_2uv
+\& switch_locale_context
+\& sys_init
+\& sys_init3
+\& sys_intern_clear
+\& sys_intern_dup
+\& sys_intern_init
+\& sys_term
+\& tied_method
+\& tmps_grow_p
+\& _to_fold_latin1
+\& TOPMARK
+\& to_uni_fold
+\& _to_uni_fold_flags
+\& to_uni_lower
+\& to_uni_title
+\& to_uni_upper
+\& _to_upper_title_latin1
+\& _to_utf8_fold_flags
+\& _to_utf8_lower_flags
+\& _to_utf8_title_flags
+\& _to_utf8_upper_flags
+\& translate_substr_offsets
+\& try_amagic_bin
+\& try_amagic_un
+\& uiv_2buf
+\& unlnk
+\& unshare_hek
+\& unwind_paren
+\& _utf8n_to_uvchr_msgs_helper
+\& utf16_to_utf8_base
+\& utf16_to_utf8_reversed
+\& utf16_to_utf8
+\& utf8_to_uvchr_buf_helper
+\& utilize
+\& uvoffuni_to_utf8_flags_msgs
+\& uvuni_to_utf8
+\& variant_byte_number
+\& varname
+\& vivify_defelem
+\& vivify_ref
+\& wait4pid
+\& warn_elem_scalar_context
+\& _warn_problematic_locale
+\& was_lvalue_sub
+\& watch
+\& win32_croak_not_implemented
+\& write_to_stderr
+\& xs_boot_epilog
+\& xs_handshake
+\& yyerror
+\& yyerror_pv
+\& yyerror_pvn
+\& yylex
+\& yyparse
+\& yyquit
+\& yyunlex
+.Ve
+.PP
+Next are the experimental undocumented elements
+.PP
+
+.IX Xref "alloc_LOGOP create_eval_scope cv_ckproto_len_flags cx_popblock cx_popeval cx_popformat cx_popgiven cx_poploop cx_popsub cx_popsub_args cx_popsub_common cx_popwhen cx_pushblock cx_pusheval cx_pushformat cx_pushgiven cx_pushloop_for cx_pushloop_plain cx_pushsub cx_pushtry cx_pushwhen cx_topblock delete_eval_scope do_open_raw do_open6 emulate_cop_io get_re_arg get_vtbl gimme_V hv_backreferences_p hv_kill_backrefs invlist_highest_range_start invlist_lowest newGP new_warnings_bitfield op_refcnt_dec op_refcnt_inc op_unscope scan_str scan_word scan_word6 skipspace_flags sv_free2 sv_kill_backrefs sv_setpv_freshbuf sv_setsv_cow utf8_to_utf16_base"
+.PP
+.Vb 10
+\& alloc_LOGOP           cx_pushloop_for              invlist_lowest
+\& create_eval_scope     cx_pushloop_plain            newGP
+\& cv_ckproto_len_flags  cx_pushsub                   new_warnings_bitfield
+\& cx_popblock           cx_pushtry                   op_refcnt_dec
+\& cx_popeval            cx_pushwhen                  op_refcnt_inc
+\& cx_popformat          cx_topblock                  op_unscope
+\& cx_popgiven           delete_eval_scope            scan_str
+\& cx_poploop            do_open_raw                  scan_word
+\& cx_popsub             do_open6                     scan_word6
+\& cx_popsub_args        emulate_cop_io               skipspace_flags
+\& cx_popsub_common      get_re_arg                   sv_free2
+\& cx_popwhen            get_vtbl                     sv_kill_backrefs
+\& cx_pushblock          gimme_V                      sv_setpv_freshbuf
+\& cx_pusheval           hv_backreferences_p          sv_setsv_cow
+\& cx_pushformat         hv_kill_backrefs             utf8_to_utf16_base
+\& cx_pushgiven          invlist_highest_range_start
+.Ve
+.PP
+Finally are the deprecated undocumented elements.
+Do not use any for new code; remove all occurrences of all of these from
+existing code.
+.PP
+
+.IX Xref "get_no_modify get_opargs get_ppaddr"
+.PP
+.Vb 1
+\& get_no_modify  get_opargs  get_ppaddr
+.Ve
+.SH AUTHORS
+.IX Header "AUTHORS"
+The autodocumentation system was originally added to the Perl core by
+Benjamin Stuhl.  Documentation is by whoever was kind enough to
+document their functions.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIconfig.h\fR, perlapi, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs
diff --git a/upstream/mageia-cauldron/man1/perlinterp.1 b/upstream/mageia-cauldron/man1/perlinterp.1
new file mode 100644
index 00000000..d8097a3c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlinterp.1
@@ -0,0 +1,1024 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLINTERP 1"
+.TH PERLINTERP 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlinterp \- An overview of the Perl interpreter
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides an overview of how the Perl interpreter works at
+the level of C code, along with pointers to the relevant C source code
+files.
+.SH "ELEMENTS OF THE INTERPRETER"
+.IX Header "ELEMENTS OF THE INTERPRETER"
+The work of the interpreter has two main stages: compiling the code
+into the internal representation, or bytecode, and then executing it.
+"Compiled code" in perlguts explains exactly how the compilation stage
+happens.
+.PP
+Here is a short breakdown of perl's operation:
+.SS Startup
+.IX Subsection "Startup"
+The action begins in \fIperlmain.c\fR. (or \fIminiperlmain.c\fR for miniperl)
+This is very high-level code, enough to fit on a single screen, and it
+resembles the code found in perlembed; most of the real action takes
+place in \fIperl.c\fR
+.PP
+\&\fIperlmain.c\fR is generated by \f(CW\*(C`ExtUtils::Miniperl\*(C'\fR from
+\&\fIminiperlmain.c\fR at make time, so you should make perl to follow this
+along.
+.PP
+First, \fIperlmain.c\fR allocates some memory and constructs a Perl
+interpreter, along these lines:
+.PP
+.Vb 9
+\&    1 PERL_SYS_INIT3(&argc,&argv,&env);
+\&    2
+\&    3 if (!PL_do_undump) {
+\&    4     my_perl = perl_alloc();
+\&    5     if (!my_perl)
+\&    6         exit(1);
+\&    7     perl_construct(my_perl);
+\&    8     PL_perl_destruct_level = 0;
+\&    9 }
+.Ve
+.PP
+Line 1 is a macro, and its definition is dependent on your operating
+system. Line 3 references \f(CW\*(C`PL_do_undump\*(C'\fR, a global variable \- all
+global variables in Perl start with \f(CW\*(C`PL_\*(C'\fR. This tells you whether the
+current running program was created with the \f(CW\*(C`\-u\*(C'\fR flag to perl and
+then \fIundump\fR, which means it's going to be false in any sane context.
+.PP
+Line 4 calls a function in \fIperl.c\fR to allocate memory for a Perl
+interpreter. It's quite a simple function, and the guts of it looks
+like this:
+.PP
+.Vb 1
+\& my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
+.Ve
+.PP
+Here you see an example of Perl's system abstraction, which we'll see
+later: \f(CW\*(C`PerlMem_malloc\*(C'\fR is either your system's \f(CW\*(C`malloc\*(C'\fR, or Perl's
+own \f(CW\*(C`malloc\*(C'\fR as defined in \fImalloc.c\fR if you selected that option at
+configure time.
+.PP
+Next, in line 7, we construct the interpreter using perl_construct,
+also in \fIperl.c\fR; this sets up all the special variables that Perl
+needs, the stacks, and so on.
+.PP
+Now we pass Perl the command line options, and tell it to go:
+.PP
+.Vb 2
+\& if (!perl_parse(my_perl, xs_init, argc, argv, (char **)NULL))
+\&     perl_run(my_perl);
+\&
+\& exitstatus = perl_destruct(my_perl);
+\&
+\& perl_free(my_perl);
+.Ve
+.PP
+\&\f(CW\*(C`perl_parse\*(C'\fR is actually a wrapper around \f(CW\*(C`S_parse_body\*(C'\fR, as defined
+in \fIperl.c\fR, which processes the command line options, sets up any
+statically linked XS modules, opens the program and calls \f(CW\*(C`yyparse\*(C'\fR to
+parse it.
+.SS Parsing
+.IX Subsection "Parsing"
+The aim of this stage is to take the Perl source, and turn it into an
+op tree. We'll see what one of those looks like later. Strictly
+speaking, there's three things going on here.
+.PP
+\&\f(CW\*(C`yyparse\*(C'\fR, the parser, lives in \fIperly.c\fR, although you're better off
+reading the original YACC input in \fIperly.y\fR. (Yes, Virginia, there
+\&\fBis\fR a YACC grammar for Perl!) The job of the parser is to take your
+code and "understand" it, splitting it into sentences, deciding which
+operands go with which operators and so on.
+.PP
+The parser is nobly assisted by the lexer, which chunks up your input
+into tokens, and decides what type of thing each token is: a variable
+name, an operator, a bareword, a subroutine, a core function, and so
+on. The main point of entry to the lexer is \f(CW\*(C`yylex\*(C'\fR, and that and its
+associated routines can be found in \fItoke.c\fR. Perl isn't much like
+other computer languages; it's highly context sensitive at times, it
+can be tricky to work out what sort of token something is, or where a
+token ends. As such, there's a lot of interplay between the tokeniser
+and the parser, which can get pretty frightening if you're not used to
+it.
+.PP
+As the parser understands a Perl program, it builds up a tree of
+operations for the interpreter to perform during execution. The
+routines which construct and link together the various operations are
+to be found in \fIop.c\fR, and will be examined later.
+.SS Optimization
+.IX Subsection "Optimization"
+Now the parsing stage is complete, and the finished tree represents the
+operations that the Perl interpreter needs to perform to execute our
+program. Next, Perl does a dry run over the tree looking for
+optimisations: constant expressions such as \f(CW\*(C`3 + 4\*(C'\fR will be computed
+now, and the optimizer will also see if any multiple operations can be
+replaced with a single one. For instance, to fetch the variable
+\&\f(CW$foo\fR, instead of grabbing the glob \f(CW*foo\fR and looking at the scalar
+component, the optimizer fiddles the op tree to use a function which
+directly looks up the scalar in question. The main optimizer is \f(CW\*(C`peep\*(C'\fR
+in \fIop.c\fR, and many ops have their own optimizing functions.
+.SS Running
+.IX Subsection "Running"
+Now we're finally ready to go: we have compiled Perl byte code, and all
+that's left to do is run it. The actual execution is done by the
+\&\f(CW\*(C`runops_standard\*(C'\fR function in \fIrun.c\fR; more specifically, it's done
+by these three innocent looking lines:
+.PP
+.Vb 3
+\&    while ((PL_op = PL_op\->op_ppaddr(aTHX))) {
+\&        PERL_ASYNC_CHECK();
+\&    }
+.Ve
+.PP
+You may be more comfortable with the Perl version of that:
+.PP
+.Vb 1
+\&    PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op\->{function}};
+.Ve
+.PP
+Well, maybe not. Anyway, each op contains a function pointer, which
+stipulates the function which will actually carry out the operation.
+This function will return the next op in the sequence \- this allows for
+things like \f(CW\*(C`if\*(C'\fR which choose the next op dynamically at run time. The
+\&\f(CW\*(C`PERL_ASYNC_CHECK\*(C'\fR makes sure that things like signals interrupt
+execution if required.
+.PP
+The actual functions called are known as PP code, and they're spread
+between four files: \fIpp_hot.c\fR contains the "hot" code, which is most
+often used and highly optimized, \fIpp_sys.c\fR contains all the
+system-specific functions, \fIpp_ctl.c\fR contains the functions which
+implement control structures (\f(CW\*(C`if\*(C'\fR, \f(CW\*(C`while\*(C'\fR and the like) and \fIpp.c\fR
+contains everything else. These are, if you like, the C code for Perl's
+built-in functions and operators.
+.PP
+Note that each \f(CW\*(C`pp_\*(C'\fR function is expected to return a pointer to the
+next op. Calls to perl subs (and eval blocks) are handled within the
+same runops loop, and do not consume extra space on the C stack. For
+example, \f(CW\*(C`pp_entersub\*(C'\fR and \f(CW\*(C`pp_entertry\*(C'\fR just push a \f(CW\*(C`CXt_SUB\*(C'\fR or
+\&\f(CW\*(C`CXt_EVAL\*(C'\fR block struct onto the context stack, which contain the address
+of the op following the sub call or eval. They then return the first op
+of that sub or eval block, and so execution continues of that sub or
+block. Later, a \f(CW\*(C`pp_leavesub\*(C'\fR or \f(CW\*(C`pp_leavetry\*(C'\fR op pops the \f(CW\*(C`CXt_SUB\*(C'\fR
+or \f(CW\*(C`CXt_EVAL\*(C'\fR, retrieves the return op from it, and returns it.
+.SS "Exception handing"
+.IX Subsection "Exception handing"
+Perl's exception handing (i.e. \f(CW\*(C`die\*(C'\fR etc.) is built on top of the
+low-level \f(CWsetjmp()\fR/\f(CWlongjmp()\fR C\-library functions. These basically
+provide a way to capture the current PC and SP registers of the CPU and
+later restore them: i.e. a \f(CWlongjmp()\fR continues at the point in code
+where a previous \f(CWsetjmp()\fR was done, with anything further up on the C
+stack being lost. (This is why code should always save values using
+\&\f(CW\*(C`SAVE_\fR\f(CIFOO\fR\f(CW\*(C'\fR rather than in auto variables.)
+.PP
+The perl core wraps \f(CWsetjmp()\fR and \f(CWlongjmp()\fR in the macros
+\&\f(CW\*(C`JMPENV_PUSH\*(C'\fR and \f(CW\*(C`JMPENV_JUMP\*(C'\fR. The push operation, as well as setting
+a \f(CWsetjump()\fR, stores some temporary state in a struct local to the
+current function (allocated by \f(CW\*(C`dJMPENV\*(C'\fR). In particular, it stores a
+pointer to the previous \f(CW\*(C`JMPENV\*(C'\fR struct, and updates \f(CW\*(C`PL_top_env\*(C'\fR to
+point to the newest one, forming a chain of \f(CW\*(C`JMPENV\*(C'\fR states. Both the
+push and jump can output debugging information under \f(CW\*(C`perl \-Dl\*(C'\fR.
+.PP
+A basic rule of the perl internals is that all interpreter exits are
+achieved via a \f(CWJMPENV_JUMP()\fR. In particular:
+.IP \(bu 4
+level 2: perl-level \fBexit()\fR and internals \fBmy_exit()\fR
+.Sp
+These unwind all stacks, then perform a \fBJMPENV_JUMP\fR\|(2).
+.IP \(bu 4
+level 3: perl-level \fBdie()\fR and internals \fBcroak()\fR
+.Sp
+If currently within an eval, these pop the context stack back to the
+nearest \f(CW\*(C`CXt_EVAL\*(C'\fR frame, set \f(CW$@\fR as appropriate, set \f(CW\*(C`PL_restartop\*(C'\fR
+to the op which follows the eval associated with that frame, then perform
+a \fBJMPENV_JUMP\fR\|(3).
+.Sp
+Otherwise, the error message is printed to \f(CW\*(C`STDERR\*(C'\fR, then it is treated
+as an exit: unwind all stacks and perform a \fBJMPENV_JUMP\fR\|(2).
+.IP \(bu 4
+level 1: unused
+.Sp
+\&\fBJMPENV_JUMP\fR\|(1) is currently unused except in \fBperl_run()\fR.
+.IP \(bu 4
+level 0: normal return.
+.Sp
+The zero value is for a normal return from \fBJMPENV_PUSH()\fR
+.PP
+So the perl interpreter expects that, at all times, there is a suitable
+\&\f(CW\*(C`JMPENV_PUSH\*(C'\fR set up (and at a suitable location within the CPU call
+stack) that can catch and process a 2\- or 3\-valued jump; and in the case
+of a 3, start a new runops loop to execute \f(CW\*(C`PL_restartop\*(C'\fR and all
+remaining ops (as will be explained shortly).
+.PP
+The entry points to the perl interpreter all provide such a facility. For
+example, \fBperl_parse()\fR,  \fBperl_run()\fR and  \f(CW\*(C`call_sv(cv, G_EVAL)\*(C'\fR all contain
+something similar in outline to:
+.PP
+.Vb 10
+\&    {
+\&        dJMPENV;
+\&        JMPENV_PUSH(ret);
+\&        switch (ret) {
+\&        case 0:                     /* normal return from JMPENV_PUSH() */
+\&          redo_body:
+\&            CALLRUNOPS(aTHX);
+\&            break;
+\&        case 2:                     /* caught longjmp(2) \- exit / die */
+\&            break;
+\&        case 3:                     /* caught longjmp(3) \- eval { die } */
+\&            PL_op = PL_restartop;
+\&            goto redo_body;
+\&        }
+\&
+\&        JMPENV_POP;
+\&    }
+.Ve
+.PP
+A runops loop such as \fBPerl_runops_standard()\fR (as set up by \fBCALLRUNOPS()\fR)
+is, at its heart, just a simple:
+.PP
+.Vb 1
+\&    while ((PL_op = PL_op\->op_ppaddr(aTHX))) { 1; }
+.Ve
+.PP
+which calls the \fBpp()\fR function associated with each op, relying on that to
+return a pointer to the next op to be executed.
+.PP
+As well as setting catches at the entry points to the perl interpreter,
+you might expect perl to also do a \fBJMPENV_PUSH()\fR in places like
+\&\fBpp_entertry()\fR, just before some trappable ops are executed. In fact perl
+doesn't normally do this. The drawback with doing it is that with nested
+or recursive code such as:
+.PP
+.Vb 1
+\&    sub foo { my ($i) = @_; return if $i < 0; eval { foo(\-\-$i) } }
+.Ve
+.PP
+Then the C stack would quickly overflow with pairs of entries like
+.PP
+.Vb 6
+\&    ...
+\&    #N+3 Perl_runops()
+\&    #N+2 Perl_pp_entertry()
+\&    #N+1 Perl_runops()
+\&    #N   Perl_pp_entertry()
+\&    ...
+.Ve
+.PP
+Instead, perl puts its guards at the \fIcallers\fR of runops loops. Then as
+many nested subroutine calls and evals may be called as you like, all
+within the one runops loop. If an exception occurs, control passes back to
+the caller of the loop, which just immediately restarts a new loop with
+\&\f(CW\*(C`PL_restartop\*(C'\fR being the next op to call.
+.PP
+So in normal operation where there are several nested evals, there
+will be multiple \f(CW\*(C`CXt_EVAL\*(C'\fR context stack entries, but only a single
+runops loop, guarded by a single \f(CW\*(C`JMPENV_PUSH\*(C'\fR. Each caught eval will pop
+the next \f(CW\*(C`CXt_EVAL\*(C'\fR off the stack, set \f(CW\*(C`PL_restartop\*(C'\fR, then \fBlongjmp()\fR
+back to \fBperl_run()\fR and continue.
+.PP
+However, ops are sometimes executed within an inner runops loop, such as
+in a tie, sort, or overload code. In this case, something like
+.PP
+.Vb 1
+\&    sub FETCH { eval { die }; .... }
+.Ve
+.PP
+would, unless handled specially, cause a \fBlongjmp()\fR right back to the guard
+in \fBperl_run()\fR, popping \fIboth\fR the runops loops \- which is clearly
+incorrect.  One way to avoid this is for the tie code to do a
+\&\f(CW\*(C`JMPENV_PUSH\*(C'\fR before executing \f(CW\*(C`FETCH\*(C'\fR in the inner runops loop, but for
+efficiency reasons, perl in fact just temporarily sets a flag using
+\&\f(CWCATCH_SET(TRUE)\fR. This flag warns any subsequent \f(CW\*(C`require\*(C'\fR,
+\&\f(CW\*(C`entereval\*(C'\fR or \f(CW\*(C`entertry\*(C'\fR ops that the caller is no longer promising to
+catch any raised exceptions on their behalf.
+.PP
+These ops check this flag, and if true, they (via \fBdocatch()\fR) do a
+\&\f(CW\*(C`JMPENV_PUSH\*(C'\fR and start a new runops loop to execute the code, rather
+than doing it with the current loop.
+.PP
+As a consequence, on exit from the eval block in the \f(CW\*(C`FETCH\*(C'\fR above,
+execution of the code following the block is still carried on in the
+inner loop (i.e. the one established by the \fBpp_entertry()\fR). To avoid
+confusion, if a further exception is then raised, \fBdocatch()\fR compares the
+\&\f(CW\*(C`JMPENV\*(C'\fR level of the \f(CW\*(C`CXt_EVAL\*(C'\fR with \f(CW\*(C`PL_top_env\*(C'\fR and if they differ,
+just re-throws the exception. In this way any inner loops get popped,
+and the exception will be dealt with properly by the level which is
+expecting it.
+.PP
+Here's an example.
+.PP
+.Vb 5
+\&    1: eval { tie @a, \*(AqA\*(Aq };
+\&    2: sub A::TIEARRAY {
+\&    3:     eval { die };
+\&    4:     die;
+\&    5: }
+.Ve
+.PP
+To run this code, \fBperl_run()\fR is called, which does a \fBJMPENV_PUSH()\fR,
+then enters a runops loop. This loop executes the \f(CW\*(C`entereval\*(C'\fR and \f(CW\*(C`tie\*(C'\fR
+ops on line 1, with the \f(CW\*(C`entereval\*(C'\fR pushing a \f(CW\*(C`CXt_EVAL\*(C'\fR onto the context
+stack.
+.PP
+The \fBpp_tie()\fR does a \f(CWCATCH_SET(TRUE)\fR, then starts a second runops
+loop to execute the body of \fBTIEARRAY()\fR. When the loop executes the
+\&\f(CW\*(C`entertry\*(C'\fR op on line 3, \fBCATCH_GET()\fR is true, so \fBpp_entertry()\fR calls
+\&\fBdocatch()\fR which does a \f(CW\*(C`JMPENV_PUSH\*(C'\fR and starts a third runops loop,
+which restarts the \fBpp_entertry()\fR, then executes the \f(CW\*(C`die\*(C'\fR op. At this
+point the C call stack looks like this:
+.PP
+.Vb 11
+\&    #10 Perl_pp_die()
+\&    #9  Perl_runops()      # runops loop 3
+\&    #8  S_docatch()        # JMPENV level 2
+\&    #7  Perl_pp_entertry()
+\&    #6  Perl_runops()      # runops loop 2
+\&    #5  Perl_call_sv()
+\&    #4  Perl_pp_tie()
+\&    #3  Perl_runops()      # runops loop 1
+\&    #2  S_run_body()
+\&    #1  perl_run()         # JMPENV level 1
+\&    #0  main()
+.Ve
+.PP
+and the context and data stacks, as shown by \f(CW\*(C`perl \-Dstv\*(C'\fR, look like:
+.PP
+.Vb 9
+\&    STACK 0: MAIN
+\&      CX 0: BLOCK  =>
+\&      CX 1: EVAL   => AV()  PV("A"\e0)
+\&      retop=leave
+\&    STACK 1: MAGIC
+\&      CX 0: SUB    =>
+\&      retop=(null)
+\&      CX 1: EVAL   => *
+\&    retop=nextstate
+.Ve
+.PP
+The \fBdie()\fR pops the first \f(CW\*(C`CXt_EVAL\*(C'\fR off the context stack, sets
+\&\f(CW\*(C`PL_restartop\*(C'\fR from it, does a \f(CWJMPENV_JUMP(3)\fR, and control returns
+to the \f(CW\*(C`JMPENV\*(C'\fR level set in \fBdocatch()\fR. This then starts another
+third-level runops level, which executes the \f(CW\*(C`nextstate\*(C'\fR, \f(CW\*(C`pushmark\*(C'\fR and
+\&\f(CW\*(C`die\*(C'\fR ops from line 4. At the point that the second \fBpp_die()\fR is called,
+the C call stack looks exactly like that above, even though we are no
+longer within an inner eval. However, the context stack now looks like
+this, i.e. with the top CXt_EVAL popped:
+.PP
+.Vb 7
+\&    STACK 0: MAIN
+\&      CX 0: BLOCK  =>
+\&      CX 1: EVAL   => AV()  PV("A"\e0)
+\&      retop=leave
+\&    STACK 1: MAGIC
+\&      CX 0: SUB    =>
+\&      retop=(null)
+.Ve
+.PP
+The \fBdie()\fR on line 4 pops the context stack back down to the \f(CW\*(C`CXt_EVAL\*(C'\fR,
+leaving it as:
+.PP
+.Vb 2
+\&    STACK 0: MAIN
+\&      CX 0: BLOCK  =>
+.Ve
+.PP
+As usual, \f(CW\*(C`PL_restartop\*(C'\fR is extracted from the \f(CW\*(C`CXt_EVAL\*(C'\fR, and a
+\&\fBJMPENV_JUMP\fR\|(3) done, which pops the C stack back to the \fBdocatch()\fR:
+.PP
+.Vb 9
+\&    #8  S_docatch()        # JMPENV level 2
+\&    #7  Perl_pp_entertry()
+\&    #6  Perl_runops()      # runops loop 2
+\&    #5  Perl_call_sv()
+\&    #4  Perl_pp_tie()
+\&    #3  Perl_runops()      # runops loop 1
+\&    #2  S_run_body()
+\&    #1  perl_run()         # JMPENV level 1
+\&    #0  main()
+.Ve
+.PP
+In  this case, because the \f(CW\*(C`JMPENV\*(C'\fR level recorded in the \f(CW\*(C`CXt_EVAL\*(C'\fR
+differs from the current one, \fBdocatch()\fR just does a \fBJMPENV_JUMP\fR\|(3)
+to re-throw the exception, and the C stack unwinds to:
+.PP
+.Vb 2
+\&    #1  perl_run()         # JMPENV level 1
+\&    #0  main()
+.Ve
+.PP
+Because \f(CW\*(C`PL_restartop\*(C'\fR is non-null, \fBrun_body()\fR starts a new runops
+loop, and execution continues.
+.SS "INTERNAL VARIABLE TYPES"
+.IX Subsection "INTERNAL VARIABLE TYPES"
+You should by now have had a look at perlguts, which tells you about
+Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do
+that now.
+.PP
+These variables are used not only to represent Perl-space variables,
+but also any constants in the code, as well as some structures
+completely internal to Perl. The symbol table, for instance, is an
+ordinary Perl hash. Your code is represented by an SV as it's read into
+the parser; any program files you call are opened via ordinary Perl
+filehandles, and so on.
+.PP
+The core Devel::Peek module lets us examine SVs from a
+Perl program. Let's see, for instance, how Perl treats the constant
+\&\f(CW"hello"\fR.
+.PP
+.Vb 7
+\&      % perl \-MDevel::Peek \-e \*(AqDump("hello")\*(Aq
+\&    1 SV = PV(0xa041450) at 0xa04ecbc
+\&    2   REFCNT = 1
+\&    3   FLAGS = (POK,READONLY,pPOK)
+\&    4   PV = 0xa0484e0 "hello"\e0
+\&    5   CUR = 5
+\&    6   LEN = 6
+.Ve
+.PP
+Reading \f(CW\*(C`Devel::Peek\*(C'\fR output takes a bit of practise, so let's go
+through it line by line.
+.PP
+Line 1 tells us we're looking at an SV which lives at \f(CW0xa04ecbc\fR in
+memory. SVs themselves are very simple structures, but they contain a
+pointer to a more complex structure. In this case, it's a PV, a
+structure which holds a string value, at location \f(CW0xa041450\fR. Line 2
+is the reference count; there are no other references to this data, so
+it's 1.
+.PP
+Line 3 are the flags for this SV \- it's OK to use it as a PV, it's a
+read-only SV (because it's a constant) and the data is a PV internally.
+Next we've got the contents of the string, starting at location
+\&\f(CW0xa0484e0\fR.
+.PP
+Line 5 gives us the current length of the string \- note that this does
+\&\fBnot\fR include the null terminator. Line 6 is not the length of the
+string, but the length of the currently allocated buffer; as the string
+grows, Perl automatically extends the available storage via a routine
+called \f(CW\*(C`SvGROW\*(C'\fR.
+.PP
+You can get at any of these quantities from C very easily; just add
+\&\f(CW\*(C`Sv\*(C'\fR to the name of the field shown in the snippet, and you've got a
+macro which will return the value: \f(CWSvCUR(sv)\fR returns the current
+length of the string, \f(CWSvREFCOUNT(sv)\fR returns the reference count,
+\&\f(CW\*(C`SvPV(sv, len)\*(C'\fR returns the string itself with its length, and so on.
+More macros to manipulate these properties can be found in perlguts.
+.PP
+Let's take an example of manipulating a PV, from \f(CW\*(C`sv_catpvn\*(C'\fR, in
+\&\fIsv.c\fR
+.PP
+.Vb 5
+\&     1  void
+\&     2  Perl_sv_catpvn(pTHX_ SV *sv, const char *ptr, STRLEN len)
+\&     3  {
+\&     4      STRLEN tlen;
+\&     5      char *junk;
+\&
+\&     6      junk = SvPV_force(sv, tlen);
+\&     7      SvGROW(sv, tlen + len + 1);
+\&     8      if (ptr == junk)
+\&     9          ptr = SvPVX(sv);
+\&    10      Move(ptr,SvPVX(sv)+tlen,len,char);
+\&    11      SvCUR(sv) += len;
+\&    12      *SvEND(sv) = \*(Aq\e0\*(Aq;
+\&    13      (void)SvPOK_only_UTF8(sv);          /* validate pointer */
+\&    14      SvTAINT(sv);
+\&    15  }
+.Ve
+.PP
+This is a function which adds a string, \f(CW\*(C`ptr\*(C'\fR, of length \f(CW\*(C`len\*(C'\fR onto
+the end of the PV stored in \f(CW\*(C`sv\*(C'\fR. The first thing we do in line 6 is
+make sure that the SV \fBhas\fR a valid PV, by calling the \f(CW\*(C`SvPV_force\*(C'\fR
+macro to force a PV. As a side effect, \f(CW\*(C`tlen\*(C'\fR gets set to the current
+value of the PV, and the PV itself is returned to \f(CW\*(C`junk\*(C'\fR.
+.PP
+In line 7, we make sure that the SV will have enough room to
+accommodate the old string, the new string and the null terminator. If
+\&\f(CW\*(C`LEN\*(C'\fR isn't big enough, \f(CW\*(C`SvGROW\*(C'\fR will reallocate space for us.
+.PP
+Now, if \f(CW\*(C`junk\*(C'\fR is the same as the string we're trying to add, we can
+grab the string directly from the SV; \f(CW\*(C`SvPVX\*(C'\fR is the address of the PV
+in the SV.
+.PP
+Line 10 does the actual catenation: the \f(CW\*(C`Move\*(C'\fR macro moves a chunk of
+memory around: we move the string \f(CW\*(C`ptr\*(C'\fR to the end of the PV \- that's
+the start of the PV plus its current length. We're moving \f(CW\*(C`len\*(C'\fR bytes
+of type \f(CW\*(C`char\*(C'\fR. After doing so, we need to tell Perl we've extended
+the string, by altering \f(CW\*(C`CUR\*(C'\fR to reflect the new length. \f(CW\*(C`SvEND\*(C'\fR is a
+macro which gives us the end of the string, so that needs to be a
+\&\f(CW"\e0"\fR.
+.PP
+Line 13 manipulates the flags; since we've changed the PV, any IV or NV
+values will no longer be valid: if we have \f(CW\*(C`$a=10; $a.="6";\*(C'\fR we don't
+want to use the old IV of 10. \f(CW\*(C`SvPOK_only_utf8\*(C'\fR is a special
+UTF\-8\-aware version of \f(CW\*(C`SvPOK_only\*(C'\fR, a macro which turns off the IOK
+and NOK flags and turns on POK. The final \f(CW\*(C`SvTAINT\*(C'\fR is a macro which
+launders tainted data if taint mode is turned on.
+.PP
+AVs and HVs are more complicated, but SVs are by far the most common
+variable type being thrown around. Having seen something of how we
+manipulate these, let's go on and look at how the op tree is
+constructed.
+.SH "OP TREES"
+.IX Header "OP TREES"
+First, what is the op tree, anyway? The op tree is the parsed
+representation of your program, as we saw in our section on parsing,
+and it's the sequence of operations that Perl goes through to execute
+your program, as we saw in "Running".
+.PP
+An op is a fundamental operation that Perl can perform: all the
+built-in functions and operators are ops, and there are a series of ops
+which deal with concepts the interpreter needs internally \- entering
+and leaving a block, ending a statement, fetching a variable, and so
+on.
+.PP
+The op tree is connected in two ways: you can imagine that there are
+two "routes" through it, two orders in which you can traverse the tree.
+First, parse order reflects how the parser understood the code, and
+secondly, execution order tells perl what order to perform the
+operations in.
+.PP
+The easiest way to examine the op tree is to stop Perl after it has
+finished parsing, and get it to dump out the tree. This is exactly what
+the compiler backends B::Terse, B::Concise
+and CPAN module <B::Debug do.
+.PP
+Let's have a look at how Perl sees \f(CW\*(C`$a = $b + $c\*(C'\fR:
+.PP
+.Vb 12
+\&     % perl \-MO=Terse \-e \*(Aq$a=$b+$c\*(Aq
+\&     1  LISTOP (0x8179888) leave
+\&     2      OP (0x81798b0) enter
+\&     3      COP (0x8179850) nextstate
+\&     4      BINOP (0x8179828) sassign
+\&     5          BINOP (0x8179800) add [1]
+\&     6              UNOP (0x81796e0) null [15]
+\&     7                  SVOP (0x80fafe0) gvsv  GV (0x80fa4cc) *b
+\&     8              UNOP (0x81797e0) null [15]
+\&     9                  SVOP (0x8179700) gvsv  GV (0x80efeb0) *c
+\&    10          UNOP (0x816b4f0) null [15]
+\&    11              SVOP (0x816dcf0) gvsv  GV (0x80fa460) *a
+.Ve
+.PP
+Let's start in the middle, at line 4. This is a BINOP, a binary
+operator, which is at location \f(CW0x8179828\fR. The specific operator in
+question is \f(CW\*(C`sassign\*(C'\fR \- scalar assignment \- and you can find the code
+which implements it in the function \f(CW\*(C`pp_sassign\*(C'\fR in \fIpp_hot.c\fR. As a
+binary operator, it has two children: the add operator, providing the
+result of \f(CW\*(C`$b+$c\*(C'\fR, is uppermost on line 5, and the left hand side is
+on line 10.
+.PP
+Line 10 is the null op: this does exactly nothing. What is that doing
+there? If you see the null op, it's a sign that something has been
+optimized away after parsing. As we mentioned in "Optimization", the
+optimization stage sometimes converts two operations into one, for
+example when fetching a scalar variable. When this happens, instead of
+rewriting the op tree and cleaning up the dangling pointers, it's
+easier just to replace the redundant operation with the null op.
+Originally, the tree would have looked like this:
+.PP
+.Vb 2
+\&    10          SVOP (0x816b4f0) rv2sv [15]
+\&    11              SVOP (0x816dcf0) gv  GV (0x80fa460) *a
+.Ve
+.PP
+That is, fetch the \f(CW\*(C`a\*(C'\fR entry from the main symbol table, and then look
+at the scalar component of it: \f(CW\*(C`gvsv\*(C'\fR (\f(CW\*(C`pp_gvsv\*(C'\fR in \fIpp_hot.c\fR)
+happens to do both these things.
+.PP
+The right hand side, starting at line 5 is similar to what we've just
+seen: we have the \f(CW\*(C`add\*(C'\fR op (\f(CW\*(C`pp_add\*(C'\fR, also in \fIpp_hot.c\fR) add
+together two \f(CW\*(C`gvsv\*(C'\fRs.
+.PP
+Now, what's this about?
+.PP
+.Vb 3
+\&     1  LISTOP (0x8179888) leave
+\&     2      OP (0x81798b0) enter
+\&     3      COP (0x8179850) nextstate
+.Ve
+.PP
+\&\f(CW\*(C`enter\*(C'\fR and \f(CW\*(C`leave\*(C'\fR are scoping ops, and their job is to perform any
+housekeeping every time you enter and leave a block: lexical variables
+are tidied up, unreferenced variables are destroyed, and so on. Every
+program will have those first three lines: \f(CW\*(C`leave\*(C'\fR is a list, and its
+children are all the statements in the block. Statements are delimited
+by \f(CW\*(C`nextstate\*(C'\fR, so a block is a collection of \f(CW\*(C`nextstate\*(C'\fR ops, with
+the ops to be performed for each statement being the children of
+\&\f(CW\*(C`nextstate\*(C'\fR. \f(CW\*(C`enter\*(C'\fR is a single op which functions as a marker.
+.PP
+That's how Perl parsed the program, from top to bottom:
+.PP
+.Vb 10
+\&                        Program
+\&                           |
+\&                       Statement
+\&                           |
+\&                           =
+\&                          / \e
+\&                         /   \e
+\&                        $a   +
+\&                            / \e
+\&                          $b   $c
+.Ve
+.PP
+However, it's impossible to \fBperform\fR the operations in this order:
+you have to find the values of \f(CW$b\fR and \f(CW$c\fR before you add them
+together, for instance. So, the other thread that runs through the op
+tree is the execution order: each op has a field \f(CW\*(C`op_next\*(C'\fR which
+points to the next op to be run, so following these pointers tells us
+how perl executes the code. We can traverse the tree in this order
+using the \f(CW\*(C`exec\*(C'\fR option to \f(CW\*(C`B::Terse\*(C'\fR:
+.PP
+.Vb 9
+\&     % perl \-MO=Terse,exec \-e \*(Aq$a=$b+$c\*(Aq
+\&     1  OP (0x8179928) enter
+\&     2  COP (0x81798c8) nextstate
+\&     3  SVOP (0x81796c8) gvsv  GV (0x80fa4d4) *b
+\&     4  SVOP (0x8179798) gvsv  GV (0x80efeb0) *c
+\&     5  BINOP (0x8179878) add [1]
+\&     6  SVOP (0x816dd38) gvsv  GV (0x80fa468) *a
+\&     7  BINOP (0x81798a0) sassign
+\&     8  LISTOP (0x8179900) leave
+.Ve
+.PP
+This probably makes more sense for a human: enter a block, start a
+statement. Get the values of \f(CW$b\fR and \f(CW$c\fR, and add them together.
+Find \f(CW$a\fR, and assign one to the other. Then leave.
+.PP
+The way Perl builds up these op trees in the parsing process can be
+unravelled by examining \fItoke.c\fR, the lexer, and \fIperly.y\fR, the YACC
+grammar. Let's look at the code that constructs the tree for \f(CW$a = $b +
+$c\fR.
+.PP
+First, we'll look at the \f(CW\*(C`Perl_yylex\*(C'\fR function in the lexer. We want to
+look for \f(CW\*(C`case \*(Aqx\*(Aq\*(C'\fR, where x is the first character of the operator.
+(Incidentally, when looking for the code that handles a keyword, you'll
+want to search for \f(CW\*(C`KEY_foo\*(C'\fR where "foo" is the keyword.) Here is the code
+that handles assignment (there are quite a few operators beginning with
+\&\f(CW\*(C`=\*(C'\fR, so most of it is omitted for brevity):
+.PP
+.Vb 5
+\&     1    case \*(Aq=\*(Aq:
+\&     2        s++;
+\&              ... code that handles == => etc. and pod ...
+\&     3        pl_yylval.ival = 0;
+\&     4        OPERATOR(ASSIGNOP);
+.Ve
+.PP
+We can see on line 4 that our token type is \f(CW\*(C`ASSIGNOP\*(C'\fR (\f(CW\*(C`OPERATOR\*(C'\fR is a
+macro, defined in \fItoke.c\fR, that returns the token type, among other
+things). And \f(CW\*(C`+\*(C'\fR:
+.PP
+.Vb 10
+\&     1     case \*(Aq+\*(Aq:
+\&     2         {
+\&     3             const char tmp = *s++;
+\&                   ... code for ++ ...
+\&     4             if (PL_expect == XOPERATOR) {
+\&                       ...
+\&     5                 Aop(OP_ADD);
+\&     6             }
+\&                   ...
+\&     7         }
+.Ve
+.PP
+Line 4 checks what type of token we are expecting. \f(CW\*(C`Aop\*(C'\fR returns a token.
+If you search for \f(CW\*(C`Aop\*(C'\fR elsewhere in \fItoke.c\fR, you will see that it
+returns an \f(CW\*(C`ADDOP\*(C'\fR token.
+.PP
+Now that we know the two token types we want to look for in the parser,
+let's take the piece of \fIperly.y\fR we need to construct the tree for
+\&\f(CW\*(C`$a = $b + $c\*(C'\fR
+.PP
+.Vb 4
+\&    1 term    :   term ASSIGNOP term
+\&    2                { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); }
+\&    3         |   term ADDOP term
+\&    4                { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
+.Ve
+.PP
+If you're not used to reading BNF grammars, this is how it works:
+You're fed certain things by the tokeniser, which generally end up in
+upper case. \f(CW\*(C`ADDOP\*(C'\fR and \f(CW\*(C`ASSIGNOP\*(C'\fR are examples of "terminal symbols",
+because you can't get any simpler than
+them.
+.PP
+The grammar, lines one and three of the snippet above, tells you how to
+build up more complex forms. These complex forms, "non-terminal
+symbols" are generally placed in lower case. \f(CW\*(C`term\*(C'\fR here is a
+non-terminal symbol, representing a single expression.
+.PP
+The grammar gives you the following rule: you can make the thing on the
+left of the colon if you see all the things on the right in sequence.
+This is called a "reduction", and the aim of parsing is to completely
+reduce the input. There are several different ways you can perform a
+reduction, separated by vertical bars: so, \f(CW\*(C`term\*(C'\fR followed by \f(CW\*(C`=\*(C'\fR
+followed by \f(CW\*(C`term\*(C'\fR makes a \f(CW\*(C`term\*(C'\fR, and \f(CW\*(C`term\*(C'\fR followed by \f(CW\*(C`+\*(C'\fR
+followed by \f(CW\*(C`term\*(C'\fR can also make a \f(CW\*(C`term\*(C'\fR.
+.PP
+So, if you see two terms with an \f(CW\*(C`=\*(C'\fR or \f(CW\*(C`+\*(C'\fR, between them, you can
+turn them into a single expression. When you do this, you execute the
+code in the block on the next line: if you see \f(CW\*(C`=\*(C'\fR, you'll do the code
+in line 2. If you see \f(CW\*(C`+\*(C'\fR, you'll do the code in line 4. It's this
+code which contributes to the op tree.
+.PP
+.Vb 2
+\&            |   term ADDOP term
+\&            { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
+.Ve
+.PP
+What this does is creates a new binary op, and feeds it a number of
+variables. The variables refer to the tokens: \f(CW$1\fR is the first token
+in the input, \f(CW$2\fR the second, and so on \- think regular expression
+backreferences. \f(CW$$\fR is the op returned from this reduction. So, we
+call \f(CW\*(C`newBINOP\*(C'\fR to create a new binary operator. The first parameter
+to \f(CW\*(C`newBINOP\*(C'\fR, a function in \fIop.c\fR, is the op type. It's an addition
+operator, so we want the type to be \f(CW\*(C`ADDOP\*(C'\fR. We could specify this
+directly, but it's right there as the second token in the input, so we
+use \f(CW$2\fR. The second parameter is the op's flags: 0 means "nothing
+special". Then the things to add: the left and right hand side of our
+expression, in scalar context.
+.PP
+The functions that create ops, which have names like \f(CW\*(C`newUNOP\*(C'\fR and
+\&\f(CW\*(C`newBINOP\*(C'\fR, call a "check" function associated with each op type, before
+returning the op. The check functions can mangle the op as they see fit,
+and even replace it with an entirely new one. These functions are defined
+in \fIop.c\fR, and have a \f(CW\*(C`Perl_ck_\*(C'\fR prefix. You can find out which
+check function is used for a particular op type by looking in
+\&\fIregen/opcodes\fR.  Take \f(CW\*(C`OP_ADD\*(C'\fR, for example. (\f(CW\*(C`OP_ADD\*(C'\fR is the token
+value from the \f(CWAop(OP_ADD)\fR in \fItoke.c\fR which the parser passes to
+\&\f(CW\*(C`newBINOP\*(C'\fR as its first argument.) Here is the relevant line:
+.PP
+.Vb 1
+\&    add             addition (+)            ck_null         IfsT2   S S
+.Ve
+.PP
+The check function in this case is \f(CW\*(C`Perl_ck_null\*(C'\fR, which does nothing.
+Let's look at a more interesting case:
+.PP
+.Vb 1
+\&    readline        <HANDLE>                ck_readline     t%      F?
+.Ve
+.PP
+And here is the function from \fIop.c\fR:
+.PP
+.Vb 10
+\&     1 OP *
+\&     2 Perl_ck_readline(pTHX_ OP *o)
+\&     3 {
+\&     4     PERL_ARGS_ASSERT_CK_READLINE;
+\&     5 
+\&     6     if (o\->op_flags & OPf_KIDS) {
+\&     7          OP *kid = cLISTOPo\->op_first;
+\&     8          if (kid\->op_type == OP_RV2GV)
+\&     9              kid\->op_private |= OPpALLOW_FAKE;
+\&    10     }
+\&    11     else {
+\&    12         OP * const newop
+\&    13             = newUNOP(OP_READLINE, 0, newGVOP(OP_GV, 0,
+\&    14                                               PL_argvgv));
+\&    15         op_free(o);
+\&    16         return newop;
+\&    17     }
+\&    18     return o;
+\&    19 }
+.Ve
+.PP
+One particularly interesting aspect is that if the op has no kids (i.e.,
+\&\f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR) the op is freed and replaced with an entirely
+new one that references \f(CW*ARGV\fR (lines 12\-16).
+.SH STACKS
+.IX Header "STACKS"
+When perl executes something like \f(CW\*(C`addop\*(C'\fR, how does it pass on its
+results to the next op? The answer is, through the use of stacks. Perl
+has a number of stacks to store things it's currently working on, and
+we'll look at the three most important ones here.
+.SS "Argument stack"
+.IX Subsection "Argument stack"
+Arguments are passed to PP code and returned from PP code using the
+argument stack, \f(CW\*(C`ST\*(C'\fR. The typical way to handle arguments is to pop
+them off the stack, deal with them how you wish, and then push the
+result back onto the stack. This is how, for instance, the cosine
+operator works:
+.PP
+.Vb 4
+\&      NV value;
+\&      value = POPn;
+\&      value = Perl_cos(value);
+\&      XPUSHn(value);
+.Ve
+.PP
+We'll see a more tricky example of this when we consider Perl's macros
+below. \f(CW\*(C`POPn\*(C'\fR gives you the NV (floating point value) of the top SV on
+the stack: the \f(CW$x\fR in \f(CWcos($x)\fR. Then we compute the cosine, and
+push the result back as an NV. The \f(CW\*(C`X\*(C'\fR in \f(CW\*(C`XPUSHn\*(C'\fR means that the
+stack should be extended if necessary \- it can't be necessary here,
+because we know there's room for one more item on the stack, since
+we've just removed one! The \f(CW\*(C`XPUSH*\*(C'\fR macros at least guarantee safety.
+.PP
+Alternatively, you can fiddle with the stack directly: \f(CW\*(C`SP\*(C'\fR gives you
+the first element in your portion of the stack, and \f(CW\*(C`TOP*\*(C'\fR gives you
+the top SV/IV/NV/etc. on the stack. So, for instance, to do unary
+negation of an integer:
+.PP
+.Vb 1
+\&     SETi(\-TOPi);
+.Ve
+.PP
+Just set the integer value of the top stack entry to its negation.
+.PP
+Argument stack manipulation in the core is exactly the same as it is in
+XSUBs \- see perlxstut, perlxs and perlguts for a longer
+description of the macros used in stack manipulation.
+.SS "Mark stack"
+.IX Subsection "Mark stack"
+I say "your portion of the stack" above because PP code doesn't
+necessarily get the whole stack to itself: if your function calls
+another function, you'll only want to expose the arguments aimed for
+the called function, and not (necessarily) let it get at your own data.
+The way we do this is to have a "virtual" bottom-of-stack, exposed to
+each function. The mark stack keeps bookmarks to locations in the
+argument stack usable by each function. For instance, when dealing with
+a tied variable, (internally, something with "P" magic) Perl has to
+call methods for accesses to the tied variables. However, we need to
+separate the arguments exposed to the method to the argument exposed to
+the original function \- the store or fetch or whatever it may be.
+Here's roughly how the tied \f(CW\*(C`push\*(C'\fR is implemented; see \f(CW\*(C`av_push\*(C'\fR in
+\&\fIav.c\fR:
+.PP
+.Vb 8
+\&     1  PUSHMARK(SP);
+\&     2  EXTEND(SP,2);
+\&     3  PUSHs(SvTIED_obj((SV*)av, mg));
+\&     4  PUSHs(val);
+\&     5  PUTBACK;
+\&     6  ENTER;
+\&     7  call_method("PUSH", G_SCALAR|G_DISCARD);
+\&     8  LEAVE;
+.Ve
+.PP
+Let's examine the whole implementation, for practice:
+.PP
+.Vb 1
+\&     1  PUSHMARK(SP);
+.Ve
+.PP
+Push the current state of the stack pointer onto the mark stack. This
+is so that when we've finished adding items to the argument stack, Perl
+knows how many things we've added recently.
+.PP
+.Vb 3
+\&     2  EXTEND(SP,2);
+\&     3  PUSHs(SvTIED_obj((SV*)av, mg));
+\&     4  PUSHs(val);
+.Ve
+.PP
+We're going to add two more items onto the argument stack: when you
+have a tied array, the \f(CW\*(C`PUSH\*(C'\fR subroutine receives the object and the
+value to be pushed, and that's exactly what we have here \- the tied
+object, retrieved with \f(CW\*(C`SvTIED_obj\*(C'\fR, and the value, the SV \f(CW\*(C`val\*(C'\fR.
+.PP
+.Vb 1
+\&     5  PUTBACK;
+.Ve
+.PP
+Next we tell Perl to update the global stack pointer from our internal
+variable: \f(CW\*(C`dSP\*(C'\fR only gave us a local copy, not a reference to the
+global.
+.PP
+.Vb 3
+\&     6  ENTER;
+\&     7  call_method("PUSH", G_SCALAR|G_DISCARD);
+\&     8  LEAVE;
+.Ve
+.PP
+\&\f(CW\*(C`ENTER\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR localise a block of code \- they make sure that
+all variables are tidied up, everything that has been localised gets
+its previous value returned, and so on. Think of them as the \f(CW\*(C`{\*(C'\fR and
+\&\f(CW\*(C`}\*(C'\fR of a Perl block.
+.PP
+To actually do the magic method call, we have to call a subroutine in
+Perl space: \f(CW\*(C`call_method\*(C'\fR takes care of that, and it's described in
+perlcall. We call the \f(CW\*(C`PUSH\*(C'\fR method in scalar context, and we're
+going to discard its return value. The \fBcall_method()\fR function removes
+the top element of the mark stack, so there is nothing for the caller
+to clean up.
+.SS "Save stack"
+.IX Subsection "Save stack"
+C doesn't have a concept of local scope, so perl provides one. We've
+seen that \f(CW\*(C`ENTER\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR are used as scoping braces; the save
+stack implements the C equivalent of, for example:
+.PP
+.Vb 4
+\&    {
+\&        local $foo = 42;
+\&        ...
+\&    }
+.Ve
+.PP
+See "Localizing changes" in perlguts for how to use the save stack.
+.SH "MILLIONS OF MACROS"
+.IX Header "MILLIONS OF MACROS"
+One thing you'll notice about the Perl source is that it's full of
+macros. Some have called the pervasive use of macros the hardest thing
+to understand, others find it adds to clarity. Let's take an example,
+a stripped-down version the code which implements the addition operator:
+.PP
+.Vb 10
+\&   1  PP(pp_add)
+\&   2  {
+\&   3      dSP; dATARGET;
+\&   4      tryAMAGICbin_MG(add_amg, AMGf_assign|AMGf_numeric);
+\&   5      {
+\&   6        dPOPTOPnnrl_ul;
+\&   7        SETn( left + right );
+\&   8        RETURN;
+\&   9      }
+\&  10  }
+.Ve
+.PP
+Every line here (apart from the braces, of course) contains a macro.
+The first line sets up the function declaration as Perl expects for PP
+code; line 3 sets up variable declarations for the argument stack and
+the target, the return value of the operation. Line 4 tries to see
+if the addition operation is overloaded; if so, the appropriate
+subroutine is called.
+.PP
+Line 6 is another variable declaration \- all variable declarations
+start with \f(CW\*(C`d\*(C'\fR \- which pops from the top of the argument stack two NVs
+(hence \f(CW\*(C`nn\*(C'\fR) and puts them into the variables \f(CW\*(C`right\*(C'\fR and \f(CW\*(C`left\*(C'\fR,
+hence the \f(CW\*(C`rl\*(C'\fR. These are the two operands to the addition operator.
+Next, we call \f(CW\*(C`SETn\*(C'\fR to set the NV of the return value to the result
+of adding the two values. This done, we return \- the \f(CW\*(C`RETURN\*(C'\fR macro
+makes sure that our return value is properly handled, and we pass the
+next operator to run back to the main run loop.
+.PP
+Most of these macros are explained in perlapi, and some of the more
+important ones are explained in perlxs as well. Pay special
+attention to "Background and MULTIPLICITY" in perlguts for
+information on the \f(CW\*(C`[pad]THX_?\*(C'\fR macros.
+.SH "FURTHER READING"
+.IX Header "FURTHER READING"
+For more information on the Perl internals, please see the documents
+listed at "Internals and C Language Interface" in perl.
diff --git a/upstream/mageia-cauldron/man1/perlintro.1 b/upstream/mageia-cauldron/man1/perlintro.1
new file mode 100644
index 00000000..ea6b4aac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlintro.1
@@ -0,0 +1,845 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLINTRO 1"
+.TH PERLINTRO 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlintro \- a brief introduction and overview of Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is intended to give you a quick overview of the Perl
+programming language, along with pointers to further documentation.  It
+is intended as a "bootstrap" guide for those who are new to the
+language, and provides just enough information for you to be able to
+read other peoples' Perl and understand roughly what it's doing, or
+write your own simple scripts.
+.PP
+This introductory document does not aim to be complete.  It does not
+even aim to be entirely accurate.  In some cases perfection has been
+sacrificed in the goal of getting the general idea across.  You are
+\&\fIstrongly\fR advised to follow this introduction with more information
+from the full Perl manual, the table of contents to which can be found
+in perltoc.
+.PP
+Throughout this document you'll see references to other parts of the
+Perl documentation.  You can read that documentation using the \f(CW\*(C`perldoc\*(C'\fR
+command or whatever method you're using to read this document.
+.PP
+Throughout Perl's documentation, you'll find numerous examples intended
+to help explain the discussed features.  Please keep in mind that many
+of them are code fragments rather than complete programs.
+.PP
+These examples often reflect the style and preference of the author of
+that piece of the documentation, and may be briefer than a corresponding
+line of code in a real program.  Except where otherwise noted, you
+should assume that \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR statements
+appear earlier in the "program", and that any variables used have
+already been declared, even if those declarations have been omitted
+to make the example easier to read.
+.PP
+Do note that the examples have been written by many different authors over
+a period of several decades.  Styles and techniques will therefore differ,
+although some effort has been made to not vary styles too widely in the
+same sections.  Do not consider one style to be better than others \- "There's
+More Than One Way To Do It" is one of Perl's mottos.  After all, in your
+journey as a programmer, you are likely to encounter different styles.
+.SS "What is Perl?"
+.IX Subsection "What is Perl?"
+Perl is a general-purpose programming language originally developed for
+text manipulation and now used for a wide range of tasks including
+system administration, web development, network programming, GUI
+development, and more.
+.PP
+The language is intended to be practical (easy to use, efficient,
+complete) rather than beautiful (tiny, elegant, minimal).  Its major
+features are that it's easy to use, supports both procedural and
+object-oriented (OO) programming, has powerful built-in support for text
+processing, and has one of the world's most impressive collections of
+third-party modules.
+.PP
+Different definitions of Perl are given in perl, perlfaq1 and
+no doubt other places.  From this we can determine that Perl is different
+things to different people, but that lots of people think it's at least
+worth writing about.
+.SS "Running Perl programs"
+.IX Subsection "Running Perl programs"
+To run a Perl program from the Unix command line:
+.PP
+.Vb 1
+\& perl progname.pl
+.Ve
+.PP
+Alternatively, put this as the first line of your script:
+.PP
+.Vb 1
+\& #!/usr/bin/env perl
+.Ve
+.PP
+\&... and run the script as \fI/path/to/script.pl\fR.  Of course, it'll need
+to be executable first, so \f(CW\*(C`chmod 755 script.pl\*(C'\fR (under Unix).
+.PP
+(This start line assumes you have the \fBenv\fR program.  You can also put
+directly the path to your perl executable, like in \f(CW\*(C`#!/usr/bin/perl\*(C'\fR).
+.PP
+For more information, including instructions for other platforms such as
+Windows, read perlrun.
+.SS "Safety net"
+.IX Subsection "Safety net"
+Perl by default is very forgiving.  In order to make it more robust
+it is recommended to start every program with the following lines:
+.PP
+.Vb 3
+\& #!/usr/bin/perl
+\& use strict;
+\& use warnings;
+.Ve
+.PP
+The two additional lines request from perl to catch various common
+problems in your code.  They check different things so you need both.  A
+potential problem caught by \f(CW\*(C`use strict;\*(C'\fR will cause your code to stop
+immediately when it is encountered, while \f(CW\*(C`use warnings;\*(C'\fR will merely
+give a warning (like the command-line switch \fB\-w\fR) and let your code run.
+To read more about them, check their respective manual pages at strict
+and warnings.
+.PP
+A \f(CW\*(C`use v5.35\*(C'\fR (or higher) declaration will
+enable both \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR:
+.PP
+.Vb 2
+\&  #!/usr/bin/perl
+\&  use v5.35;
+.Ve
+.PP
+In addition to enabling the \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmata, this
+declaration will also activate a
+"feature bundle"; a collection of named
+features that enable many of the more recent additions and changes to the
+language, as well as occasionally removing older features found to have
+been mistakes in design and discouraged.
+.SS "Basic syntax overview"
+.IX Subsection "Basic syntax overview"
+A Perl script or program consists of one or more statements.  These
+statements are simply written in the script in a straightforward
+fashion.  There is no need to have a \f(CWmain()\fR function or anything of
+that kind.
+.PP
+Perl statements end in a semi-colon:
+.PP
+.Vb 1
+\& print "Hello, world";
+.Ve
+.PP
+Comments start with a hash symbol and run to the end of the line
+.PP
+.Vb 1
+\& # This is a comment
+.Ve
+.PP
+Whitespace is irrelevant:
+.PP
+.Vb 3
+\& print
+\&     "Hello, world"
+\&     ;
+.Ve
+.PP
+\&... except inside quoted strings:
+.PP
+.Vb 3
+\& # this would print with a linebreak in the middle
+\& print "Hello
+\& world";
+.Ve
+.PP
+Double quotes or single quotes may be used around literal strings:
+.PP
+.Vb 2
+\& print "Hello, world";
+\& print \*(AqHello, world\*(Aq;
+.Ve
+.PP
+However, only double quotes "interpolate" variables and special
+characters such as newlines (\f(CW\*(C`\en\*(C'\fR):
+.PP
+.Vb 2
+\& print "Hello, $name\en";     # works fine
+\& print \*(AqHello, $name\en\*(Aq;     # prints $name\en literally
+.Ve
+.PP
+Numbers don't need quotes around them:
+.PP
+.Vb 1
+\& print 42;
+.Ve
+.PP
+You can use parentheses for functions' arguments or omit them
+according to your personal taste.  They are only required
+occasionally to clarify issues of precedence.
+.PP
+.Vb 2
+\& print("Hello, world\en");
+\& print "Hello, world\en";
+.Ve
+.PP
+More detailed information about Perl syntax can be found in perlsyn.
+.SS "Perl variable types"
+.IX Subsection "Perl variable types"
+Perl has three main variable types: scalars, arrays, and hashes.
+.IP Scalars 4
+.IX Item "Scalars"
+A scalar represents a single value:
+.Sp
+.Vb 2
+\& my $animal = "camel";
+\& my $answer = 42;
+.Ve
+.Sp
+Scalar values can be strings, integers or floating point numbers, and Perl
+will automatically convert between them as required.  You have to declare
+them using the \f(CW\*(C`my\*(C'\fR keyword the first time you use them.  (This is one of the
+requirements of \f(CW\*(C`use strict;\*(C'\fR.)
+.Sp
+Scalar values can be used in various ways:
+.Sp
+.Vb 3
+\& print $animal;
+\& print "The animal is $animal\en";
+\& print "The square of $answer is ", $answer * $answer, "\en";
+.Ve
+.Sp
+Perl defines a number of special scalars with short names, often single
+punctuation marks or digits. These variables are used for all
+kinds of purposes, and are documented in perlvar.  The only one you
+need to know about for now is \f(CW$_\fR which is the "default variable".
+It's used as the default argument to a number of functions in Perl, and
+it's set implicitly by certain looping constructs.
+.Sp
+.Vb 1
+\& print;          # prints contents of $_ by default
+.Ve
+.IP Arrays 4
+.IX Item "Arrays"
+An array represents a list of values:
+.Sp
+.Vb 3
+\& my @animals = ("camel", "llama", "owl");
+\& my @numbers = (23, 42, 69);
+\& my @mixed   = ("camel", 42, 1.23);
+.Ve
+.Sp
+Arrays are zero-indexed.  Here's how you get at elements in an array:
+.Sp
+.Vb 2
+\& print $animals[0];              # prints "camel"
+\& print $animals[1];              # prints "llama"
+.Ve
+.Sp
+The special variable \f(CW$#array\fR tells you the index of the last element
+of an array:
+.Sp
+.Vb 1
+\& print $mixed[$#mixed];       # last element, prints 1.23
+.Ve
+.Sp
+You might be tempted to use \f(CW\*(C`$#array + 1\*(C'\fR to tell you how many items there
+are in an array.  Don't bother.  As it happens, using \f(CW@array\fR where Perl
+expects to find a scalar value ("in scalar context") will give you the number
+of elements in the array:
+.Sp
+.Vb 1
+\& if (@animals < 5) { ... }
+.Ve
+.Sp
+The elements we're getting from the array start with a \f(CW\*(C`$\*(C'\fR because
+we're getting just a single value out of the array; you ask for a scalar,
+you get a scalar.
+.Sp
+To get multiple values from an array:
+.Sp
+.Vb 3
+\& @animals[0,1];                 # gives ("camel", "llama");
+\& @animals[0..2];                # gives ("camel", "llama", "owl");
+\& @animals[1..$#animals];        # gives all except the first element
+.Ve
+.Sp
+This is called an "array slice".
+.Sp
+You can do various useful things to lists:
+.Sp
+.Vb 2
+\& my @sorted    = sort @animals;
+\& my @backwards = reverse @numbers;
+.Ve
+.Sp
+There are a couple of special arrays too, such as \f(CW@ARGV\fR (the command
+line arguments to your script) and \f(CW@_\fR (the arguments passed to a
+subroutine).  These are documented in perlvar.
+.IP Hashes 4
+.IX Item "Hashes"
+A hash represents a set of key/value pairs:
+.Sp
+.Vb 1
+\& my %fruit_color = ("apple", "red", "banana", "yellow");
+.Ve
+.Sp
+You can use whitespace and the \f(CW\*(C`=>\*(C'\fR operator to lay them out more
+nicely:
+.Sp
+.Vb 4
+\& my %fruit_color = (
+\&     apple  => "red",
+\&     banana => "yellow",
+\& );
+.Ve
+.Sp
+To get at hash elements:
+.Sp
+.Vb 1
+\& $fruit_color{"apple"};           # gives "red"
+.Ve
+.Sp
+You can get at lists of keys and values with \f(CWkeys()\fR and
+\&\f(CWvalues()\fR.
+.Sp
+.Vb 2
+\& my @fruits = keys %fruit_color;
+\& my @colors = values %fruit_color;
+.Ve
+.Sp
+Hashes have no particular internal order, though you can sort the keys
+and loop through them.
+.Sp
+Just like special scalars and arrays, there are also special hashes.
+The most well known of these is \f(CW%ENV\fR which contains environment
+variables.  Read all about it (and other special variables) in
+perlvar.
+.PP
+Scalars, arrays and hashes are documented more fully in perldata.
+.PP
+More complex data types can be constructed using references, which allow
+you to build lists and hashes within lists and hashes.
+.PP
+A reference is a scalar value and can refer to any other Perl data
+type.  So by storing a reference as the value of an array or hash
+element, you can easily create lists and hashes within lists and
+hashes.  The following example shows a 2 level hash of hash
+structure using anonymous hash references.
+.PP
+.Vb 10
+\& my $variables = {
+\&     scalar  =>  {
+\&                  description => "single item",
+\&                  sigil => \*(Aq$\*(Aq,
+\&                 },
+\&     array   =>  {
+\&                  description => "ordered list of items",
+\&                  sigil => \*(Aq@\*(Aq,
+\&                 },
+\&     hash    =>  {
+\&                  description => "key/value pairs",
+\&                  sigil => \*(Aq%\*(Aq,
+\&                 },
+\& };
+\&
+\& print "Scalars begin with a $variables\->{\*(Aqscalar\*(Aq}\->{\*(Aqsigil\*(Aq}\en";
+.Ve
+.PP
+Exhaustive information on the topic of references can be found in
+perlreftut, perllol, perlref and perldsc.
+.SS "Variable scoping"
+.IX Subsection "Variable scoping"
+Throughout the previous section all the examples have used the syntax:
+.PP
+.Vb 1
+\& my $var = "value";
+.Ve
+.PP
+The \f(CW\*(C`my\*(C'\fR is actually not required; you could just use:
+.PP
+.Vb 1
+\& $var = "value";
+.Ve
+.PP
+However, the above usage will create global variables throughout your
+program, which is bad programming practice.  \f(CW\*(C`my\*(C'\fR creates lexically
+scoped variables instead.  The variables are scoped to the block
+(i.e. a bunch of statements surrounded by curly-braces) in which they
+are defined.
+.PP
+.Vb 9
+\& my $x = "foo";
+\& my $some_condition = 1;
+\& if ($some_condition) {
+\&     my $y = "bar";
+\&     print $x;           # prints "foo"
+\&     print $y;           # prints "bar"
+\& }
+\& print $x;               # prints "foo"
+\& print $y;               # prints nothing; $y has fallen out of scope
+.Ve
+.PP
+Using \f(CW\*(C`my\*(C'\fR in combination with a \f(CW\*(C`use strict;\*(C'\fR at the top of
+your Perl scripts means that the interpreter will pick up certain common
+programming errors.  For instance, in the example above, the final
+\&\f(CW\*(C`print $y\*(C'\fR would cause a compile-time error and prevent you from
+running the program.  Using \f(CW\*(C`strict\*(C'\fR is highly recommended.
+.SS "Conditional and looping constructs"
+.IX Subsection "Conditional and looping constructs"
+Perl has most of the usual conditional and looping constructs.
+.PP
+The conditions can be any Perl expression.  See the list of operators in
+the next section for information on comparison and boolean logic operators,
+which are commonly used in conditional statements.
+.IP if 4
+.IX Item "if"
+.Vb 7
+\& if ( condition ) {
+\&     ...
+\& } elsif ( other condition ) {
+\&     ...
+\& } else {
+\&     ...
+\& }
+.Ve
+.Sp
+There's also a negated version of it:
+.Sp
+.Vb 3
+\& unless ( condition ) {
+\&     ...
+\& }
+.Ve
+.Sp
+This is provided as a more readable version of \f(CW\*(C`if (!\fR\f(CIcondition\fR\f(CW)\*(C'\fR.
+.Sp
+Note that the braces are required in Perl, even if you've only got one
+line in the block.  However, there is a clever way of making your one-line
+conditional blocks more English like:
+.Sp
+.Vb 4
+\& # the traditional way
+\& if ($zippy) {
+\&     print "Yow!";
+\& }
+\&
+\& # the Perlish post\-condition way
+\& print "Yow!" if $zippy;
+\& print "We have no bananas" unless $bananas;
+.Ve
+.IP while 4
+.IX Item "while"
+.Vb 3
+\& while ( condition ) {
+\&     ...
+\& }
+.Ve
+.Sp
+There's also a negated version, for the same reason we have \f(CW\*(C`unless\*(C'\fR:
+.Sp
+.Vb 3
+\& until ( condition ) {
+\&     ...
+\& }
+.Ve
+.Sp
+You can also use \f(CW\*(C`while\*(C'\fR in a post-condition:
+.Sp
+.Vb 1
+\& print "LA LA LA\en" while 1;          # loops forever
+.Ve
+.IP for 4
+.IX Item "for"
+Exactly like C:
+.Sp
+.Vb 3
+\& for ($i = 0; $i <= $max; $i++) {
+\&     ...
+\& }
+.Ve
+.Sp
+The C style for loop is rarely needed in Perl since Perl provides
+the more friendly list scanning \f(CW\*(C`foreach\*(C'\fR loop.
+.IP foreach 4
+.IX Item "foreach"
+.Vb 3
+\& foreach (@array) {
+\&     print "This element is $_\en";
+\& }
+\&
+\& print $list[$_] foreach 0 .. $max;
+\&
+\& # you don\*(Aqt have to use the default $_ either...
+\& foreach my $key (keys %hash) {
+\&     print "The value of $key is $hash{$key}\en";
+\& }
+.Ve
+.Sp
+The \f(CW\*(C`foreach\*(C'\fR keyword is actually a synonym for the \f(CW\*(C`for\*(C'\fR
+keyword.  See \f(CW\*(C`"Foreach Loops" in perlsyn\*(C'\fR.
+.PP
+For more detail on looping constructs (and some that weren't mentioned in
+this overview) see perlsyn.
+.SS "Builtin operators and functions"
+.IX Subsection "Builtin operators and functions"
+Perl comes with a wide selection of builtin functions.  Some of the ones
+we've already seen include \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`sort\*(C'\fR and \f(CW\*(C`reverse\*(C'\fR.  A list of
+them is given at the start of perlfunc and you can easily read
+about any given function by using \f(CW\*(C`perldoc \-f \fR\f(CIfunctionname\fR\f(CW\*(C'\fR.
+.PP
+Perl operators are documented in full in perlop, but here are a few
+of the most common ones:
+.IP Arithmetic 4
+.IX Item "Arithmetic"
+.Vb 4
+\& +   addition
+\& \-   subtraction
+\& *   multiplication
+\& /   division
+.Ve
+.IP "Numeric comparison" 4
+.IX Item "Numeric comparison"
+.Vb 6
+\& ==  equality
+\& !=  inequality
+\& <   less than
+\& >   greater than
+\& <=  less than or equal
+\& >=  greater than or equal
+.Ve
+.IP "String comparison" 4
+.IX Item "String comparison"
+.Vb 6
+\& eq  equality
+\& ne  inequality
+\& lt  less than
+\& gt  greater than
+\& le  less than or equal
+\& ge  greater than or equal
+.Ve
+.Sp
+(Why do we have separate numeric and string comparisons?  Because we don't
+have special variable types, and Perl needs to know whether to sort
+numerically (where 99 is less than 100) or alphabetically (where 100 comes
+before 99).
+.IP "Boolean logic" 4
+.IX Item "Boolean logic"
+.Vb 3
+\& &&  and
+\& ||  or
+\& !   not
+.Ve
+.Sp
+(\f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR aren't just in the above table as descriptions
+of the operators.  They're also supported as operators in their own
+right.  They're more readable than the C\-style operators, but have
+different precedence to \f(CW\*(C`&&\*(C'\fR and friends.  Check perlop for more
+detail.)
+.IP Miscellaneous 4
+.IX Item "Miscellaneous"
+.Vb 4
+\& =   assignment
+\& .   string concatenation
+\& x   string multiplication (repeats strings)
+\& ..  range operator (creates a list of numbers or strings)
+.Ve
+.PP
+Many operators can be combined with a \f(CW\*(C`=\*(C'\fR as follows:
+.PP
+.Vb 3
+\& $a += 1;        # same as $a = $a + 1
+\& $a \-= 1;        # same as $a = $a \- 1
+\& $a .= "\en";     # same as $a = $a . "\en";
+.Ve
+.SS "Files and I/O"
+.IX Subsection "Files and I/O"
+You can open a file for input or output using the \f(CWopen()\fR function.
+It's documented in extravagant detail in perlfunc and perlopentut,
+but in short:
+.PP
+.Vb 3
+\& open(my $in,  "<",  "input.txt")  or die "Can\*(Aqt open input.txt: $!";
+\& open(my $out, ">",  "output.txt") or die "Can\*(Aqt open output.txt: $!";
+\& open(my $log, ">>", "my.log")     or die "Can\*(Aqt open my.log: $!";
+.Ve
+.PP
+You can read from an open filehandle using the \f(CW\*(C`<>\*(C'\fR operator.  In
+scalar context it reads a single line from the filehandle, and in list
+context it reads the whole file in, assigning each line to an element of
+the list:
+.PP
+.Vb 2
+\& my $line  = <$in>;
+\& my @lines = <$in>;
+.Ve
+.PP
+Reading in the whole file at one time is called slurping.  It can
+be useful but it may be a memory hog.  Most text file processing
+can be done a line at a time with Perl's looping constructs.
+.PP
+The \f(CW\*(C`<>\*(C'\fR operator is most often seen in a \f(CW\*(C`while\*(C'\fR loop:
+.PP
+.Vb 3
+\& while (<$in>) {     # assigns each line in turn to $_
+\&     print "Just read in this line: $_";
+\& }
+.Ve
+.PP
+We've already seen how to print to standard output using \f(CWprint()\fR.
+However, \f(CWprint()\fR can also take an optional first argument specifying
+which filehandle to print to:
+.PP
+.Vb 3
+\& print STDERR "This is your final warning.\en";
+\& print $out $record;
+\& print $log $logmessage;
+.Ve
+.PP
+When you're done with your filehandles, you should \f(CWclose()\fR them
+(though to be honest, Perl will clean up after you if you forget):
+.PP
+.Vb 1
+\& close $in or die "$in: $!";
+.Ve
+.SS "Regular expressions"
+.IX Subsection "Regular expressions"
+Perl's regular expression support is both broad and deep, and is the
+subject of lengthy documentation in perlrequick, perlretut, and
+elsewhere.  However, in short:
+.IP "Simple matching" 4
+.IX Item "Simple matching"
+.Vb 2
+\& if (/foo/)       { ... }  # true if $_ contains "foo"
+\& if ($a =~ /foo/) { ... }  # true if $a contains "foo"
+.Ve
+.Sp
+The \f(CW\*(C`//\*(C'\fR matching operator is documented in perlop.  It operates on
+\&\f(CW$_\fR by default, or can be bound to another variable using the \f(CW\*(C`=~\*(C'\fR
+binding operator (also documented in perlop).
+.IP "Simple substitution" 4
+.IX Item "Simple substitution"
+.Vb 4
+\& s/foo/bar/;               # replaces foo with bar in $_
+\& $a =~ s/foo/bar/;         # replaces foo with bar in $a
+\& $a =~ s/foo/bar/g;        # replaces ALL INSTANCES of foo with bar
+\&                           # in $a
+.Ve
+.Sp
+The \f(CW\*(C`s///\*(C'\fR substitution operator is documented in perlop.
+.IP "More complex regular expressions" 4
+.IX Item "More complex regular expressions"
+You don't just have to match on fixed strings.  In fact, you can match
+on just about anything you could dream of by using more complex regular
+expressions.  These are documented at great length in perlre, but for
+the meantime, here's a quick cheat sheet:
+.Sp
+.Vb 12
+\& .                   a single character
+\& \es                  a whitespace character (space, tab, newline,
+\&                     ...)
+\& \eS                  non\-whitespace character
+\& \ed                  a digit (0\-9)
+\& \eD                  a non\-digit
+\& \ew                  a word character (a\-z, A\-Z, 0\-9, _)
+\& \eW                  a non\-word character
+\& [aeiou]             matches a single character in the given set
+\& [^aeiou]            matches a single character outside the given
+\&                     set
+\& (foo|bar|baz)       matches any of the alternatives specified
+\&
+\& ^                   start of string
+\& $                   end of string
+.Ve
+.Sp
+Quantifiers can be used to specify how many of the previous thing you
+want to match on, where "thing" means either a literal character, one
+of the metacharacters listed above, or a group of characters or
+metacharacters in parentheses.
+.Sp
+.Vb 6
+\& *                   zero or more of the previous thing
+\& +                   one or more of the previous thing
+\& ?                   zero or one of the previous thing
+\& {3}                 matches exactly 3 of the previous thing
+\& {3,6}               matches between 3 and 6 of the previous thing
+\& {3,}                matches 3 or more of the previous thing
+.Ve
+.Sp
+Some brief examples:
+.Sp
+.Vb 7
+\& /^\ed+/              string starts with one or more digits
+\& /^$/                nothing in the string (start and end are
+\&                     adjacent)
+\& /(\ed\es){3}/         three digits, each followed by a whitespace
+\&                     character (eg "3 4 5 ")
+\& /(a.)+/             matches a string in which every odd\-numbered
+\&                     letter is a (eg "abacadaf")
+\&
+\& # This loop reads from STDIN, and prints non\-blank lines:
+\& while (<>) {
+\&     next if /^$/;
+\&     print;
+\& }
+.Ve
+.IP "Parentheses for capturing" 4
+.IX Item "Parentheses for capturing"
+As well as grouping, parentheses serve a second purpose.  They can be
+used to capture the results of parts of the regexp match for later use.
+The results end up in \f(CW$1\fR, \f(CW$2\fR and so on.
+.Sp
+.Vb 1
+\& # a cheap and nasty way to break an email address up into parts
+\&
+\& if ($email =~ /([^@]+)@(.+)/) {
+\&     print "Username is $1\en";
+\&     print "Hostname is $2\en";
+\& }
+.Ve
+.IP "Other regexp features" 4
+.IX Item "Other regexp features"
+Perl regexps also support backreferences, lookaheads, and all kinds of
+other complex details.  Read all about them in perlrequick,
+perlretut, and perlre.
+.SS "Writing subroutines"
+.IX Subsection "Writing subroutines"
+Writing subroutines is easy:
+.PP
+.Vb 5
+\& sub logger {
+\&    my $logmessage = shift;
+\&    open my $logfile, ">>", "my.log" or die "Could not open my.log: $!";
+\&    print $logfile $logmessage;
+\& }
+.Ve
+.PP
+Now we can use the subroutine just as any other built-in function:
+.PP
+.Vb 1
+\& logger("We have a logger subroutine!");
+.Ve
+.PP
+What's that \f(CW\*(C`shift\*(C'\fR?  Well, the arguments to a subroutine are available
+to us as a special array called \f(CW@_\fR (see perlvar for more on that).
+The default argument to the \f(CW\*(C`shift\*(C'\fR function just happens to be \f(CW@_\fR.
+So \f(CW\*(C`my $logmessage = shift;\*(C'\fR shifts the first item off the list of
+arguments and assigns it to \f(CW$logmessage\fR.
+.PP
+We can manipulate \f(CW@_\fR in other ways too:
+.PP
+.Vb 2
+\& my ($logmessage, $priority) = @_;       # common
+\& my $logmessage = $_[0];                 # uncommon, and ugly
+.Ve
+.PP
+Subroutines can also return values:
+.PP
+.Vb 5
+\& sub square {
+\&     my $num = shift;
+\&     my $result = $num * $num;
+\&     return $result;
+\& }
+.Ve
+.PP
+Then use it like:
+.PP
+.Vb 1
+\& $sq = square(8);
+.Ve
+.PP
+For more information on writing subroutines, see perlsub.
+.SS "OO Perl"
+.IX Subsection "OO Perl"
+OO Perl is relatively simple and is implemented using references which
+know what sort of object they are based on Perl's concept of packages.
+However, OO Perl is largely beyond the scope of this document.
+Read perlootut and perlobj.
+.PP
+As a beginning Perl programmer, your most common use of OO Perl will be
+in using third-party modules, which are documented below.
+.SS "Using Perl modules"
+.IX Subsection "Using Perl modules"
+Perl modules provide a range of features to help you avoid reinventing
+the wheel, and can be downloaded from CPAN ( <http://www.cpan.org/> ).  A
+number of popular modules are included with the Perl distribution
+itself.
+.PP
+Categories of modules range from text manipulation to network protocols
+to database integration to graphics.  A categorized list of modules is
+also available from CPAN.
+.PP
+To learn how to install modules you download from CPAN, read
+perlmodinstall.
+.PP
+To learn how to use a particular module, use \f(CW\*(C`perldoc \fR\f(CIModule::Name\fR\f(CW\*(C'\fR.
+Typically you will want to \f(CW\*(C`use \fR\f(CIModule::Name\fR\f(CW\*(C'\fR, which will then give
+you access to exported functions or an OO interface to the module.
+.PP
+perlfaq contains questions and answers related to many common
+tasks, and often provides suggestions for good CPAN modules to use.
+.PP
+perlmod describes Perl modules in general.  perlmodlib lists the
+modules which came with your Perl installation.
+.PP
+If you feel the urge to write Perl modules, perlnewmod will give you
+good advice.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Kirrily "Skud" Robert <skud@cpan.org>
diff --git a/upstream/mageia-cauldron/man1/perliol.1 b/upstream/mageia-cauldron/man1/perliol.1
new file mode 100644
index 00000000..2d0702d9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perliol.1
@@ -0,0 +1,1074 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLIOL 1"
+.TH PERLIOL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perliol \- C API for Perl's implementation of IO in Layers.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    /* Defining a layer ... */
+\&    #include <perliol.h>
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the behavior and implementation of the PerlIO
+abstraction described in perlapio when \f(CW\*(C`USE_PERLIO\*(C'\fR is defined.
+.SS "History and Background"
+.IX Subsection "History and Background"
+The PerlIO abstraction was introduced in perl5.003_02 but languished as
+just an abstraction until perl5.7.0. However during that time a number
+of perl extensions switched to using it, so the API is mostly fixed to
+maintain (source) compatibility.
+.PP
+The aim of the implementation is to provide the PerlIO API in a flexible
+and platform neutral manner. It is also a trial of an "Object Oriented
+C, with vtables" approach which may be applied to Raku.
+.SS "Basic Structure"
+.IX Subsection "Basic Structure"
+PerlIO is a stack of layers.
+.PP
+The low levels of the stack work with the low-level operating system
+calls (file descriptors in C) getting bytes in and out, the higher
+layers of the stack buffer, filter, and otherwise manipulate the I/O,
+and return characters (or bytes) to Perl.  Terms \fIabove\fR and \fIbelow\fR
+are used to refer to the relative positioning of the stack layers.
+.PP
+A layer contains a "vtable", the table of I/O operations (at C level
+a table of function pointers), and status flags.  The functions in the
+vtable implement operations like "open", "read", and "write".
+.PP
+When I/O, for example "read", is requested, the request goes from Perl
+first down the stack using "read" functions of each layer, then at the
+bottom the input is requested from the operating system services, then
+the result is returned up the stack, finally being interpreted as Perl
+data.
+.PP
+The requests do not necessarily go always all the way down to the
+operating system: that's where PerlIO buffering comes into play.
+.PP
+When you do an \fBopen()\fR and specify extra PerlIO layers to be deployed,
+the layers you specify are "pushed" on top of the already existing
+default stack.  One way to see it is that "operating system is
+on the left" and "Perl is on the right".
+.PP
+What exact layers are in this default stack depends on a lot of
+things: your operating system, Perl version, Perl compile time
+configuration, and Perl runtime configuration.  See PerlIO,
+"PERLIO" in perlrun, and open for more information.
+.PP
+\&\fBbinmode()\fR operates similarly to \fBopen()\fR: by default the specified
+layers are pushed on top of the existing stack.
+.PP
+However, note that even as the specified layers are "pushed on top"
+for \fBopen()\fR and \fBbinmode()\fR, this doesn't mean that the effects are
+limited to the "top": PerlIO layers can be very 'active' and inspect
+and affect layers also deeper in the stack.  As an example there
+is a layer called "raw" which repeatedly "pops" layers until
+it reaches the first layer that has declared itself capable of
+handling binary data.  The "pushed" layers are processed in left-to-right
+order.
+.PP
+\&\fBsysopen()\fR operates (unsurprisingly) at a lower level in the stack than
+\&\fBopen()\fR.  For example in Unix or Unix-like systems \fBsysopen()\fR operates
+directly at the level of file descriptors: in the terms of PerlIO
+layers, it uses only the "unix" layer, which is a rather thin wrapper
+on top of the Unix file descriptors.
+.SS "Layers vs Disciplines"
+.IX Subsection "Layers vs Disciplines"
+Initial discussion of the ability to modify IO streams behaviour used
+the term "discipline" for the entities which were added. This came (I
+believe) from the use of the term in "sfio", which in turn borrowed it
+from "line disciplines" on Unix terminals. However, this document (and
+the C code) uses the term "layer".
+.PP
+This is, I hope, a natural term given the implementation, and should
+avoid connotations that are inherent in earlier uses of "discipline"
+for things which are rather different.
+.SS "Data Structures"
+.IX Subsection "Data Structures"
+The basic data structure is a PerlIOl:
+.PP
+.Vb 3
+\&        typedef struct _PerlIO PerlIOl;
+\&        typedef struct _PerlIO_funcs PerlIO_funcs;
+\&        typedef PerlIOl *PerlIO;
+\&
+\&        struct _PerlIO
+\&        {
+\&         PerlIOl *      next;       /* Lower layer */
+\&         PerlIO_funcs * tab;        /* Functions for this layer */
+\&         U32            flags;      /* Various flags for state */
+\&        };
+.Ve
+.PP
+A \f(CW\*(C`PerlIOl *\*(C'\fR is a pointer to the struct, and the \fIapplication\fR
+level \f(CW\*(C`PerlIO *\*(C'\fR is a pointer to a \f(CW\*(C`PerlIOl *\*(C'\fR \- i.e. a pointer
+to a pointer to the struct. This allows the application level \f(CW\*(C`PerlIO *\*(C'\fR
+to remain constant while the actual \f(CW\*(C`PerlIOl *\*(C'\fR underneath
+changes. (Compare perl's \f(CW\*(C`SV *\*(C'\fR which remains constant while its
+\&\f(CW\*(C`sv_any\*(C'\fR field changes as the scalar's type changes.) An IO stream is
+then in general represented as a pointer to this linked-list of
+"layers".
+.PP
+It should be noted that because of the double indirection in a \f(CW\*(C`PerlIO *\*(C'\fR,
+a \f(CW\*(C`&(perlio\->next)\*(C'\fR "is" a \f(CW\*(C`PerlIO *\*(C'\fR, and so to some degree
+at least one layer can use the "standard" API on the next layer down.
+.PP
+A "layer" is composed of two parts:
+.IP 1. 4
+The functions and attributes of the "layer class".
+.IP 2. 4
+The per-instance data for a particular handle.
+.SS "Functions and Attributes"
+.IX Subsection "Functions and Attributes"
+The functions and attributes are accessed via the "tab" (for table)
+member of \f(CW\*(C`PerlIOl\*(C'\fR. The functions (methods of the layer "class") are
+fixed, and are defined by the \f(CW\*(C`PerlIO_funcs\*(C'\fR type. They are broadly the
+same as the public \f(CW\*(C`PerlIO_xxxxx\*(C'\fR functions:
+.PP
+.Vb 10
+\& struct _PerlIO_funcs
+\& {
+\&  Size_t     fsize;
+\&  char *     name;
+\&  Size_t     size;
+\&  IV         kind;
+\&  IV         (*Pushed)(pTHX_ PerlIO *f,
+\&                             const char *mode,
+\&                             SV *arg,
+\&                             PerlIO_funcs *tab);
+\&  IV         (*Popped)(pTHX_ PerlIO *f);
+\&  PerlIO *   (*Open)(pTHX_ PerlIO_funcs *tab,
+\&                           PerlIO_list_t *layers, IV n,
+\&                           const char *mode,
+\&                           int fd, int imode, int perm,
+\&                           PerlIO *old,
+\&                           int narg, SV **args);
+\&  IV         (*Binmode)(pTHX_ PerlIO *f);
+\&  SV *       (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
+\&  IV         (*Fileno)(pTHX_ PerlIO *f);
+\&  PerlIO *   (*Dup)(pTHX_ PerlIO *f,
+\&                          PerlIO *o,
+\&                          CLONE_PARAMS *param,
+\&                          int flags)
+\&  /* Unix\-like functions \- cf sfio line disciplines */
+\&  SSize_t    (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
+\&  SSize_t    (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
+\&  SSize_t    (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
+\&  IV         (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
+\&  Off_t      (*Tell)(pTHX_ PerlIO *f);
+\&  IV         (*Close)(pTHX_ PerlIO *f);
+\&  /* Stdio\-like buffered IO functions */
+\&  IV         (*Flush)(pTHX_ PerlIO *f);
+\&  IV         (*Fill)(pTHX_ PerlIO *f);
+\&  IV         (*Eof)(pTHX_ PerlIO *f);
+\&  IV         (*Error)(pTHX_ PerlIO *f);
+\&  void       (*Clearerr)(pTHX_ PerlIO *f);
+\&  void       (*Setlinebuf)(pTHX_ PerlIO *f);
+\&  /* Perl\*(Aqs snooping functions */
+\&  STDCHAR *  (*Get_base)(pTHX_ PerlIO *f);
+\&  Size_t     (*Get_bufsiz)(pTHX_ PerlIO *f);
+\&  STDCHAR *  (*Get_ptr)(pTHX_ PerlIO *f);
+\&  SSize_t    (*Get_cnt)(pTHX_ PerlIO *f);
+\&  void       (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
+\& };
+.Ve
+.PP
+The first few members of the struct give a function table size for
+compatibility check "name" for the layer, the  size to \f(CW\*(C`malloc\*(C'\fR for the per-instance data,
+and some flags which are attributes of the class as whole (such as whether it is a buffering
+layer), then follow the functions which fall into four basic groups:
+.IP 1. 4
+Opening and setup functions
+.IP 2. 4
+Basic IO operations
+.IP 3. 4
+Stdio class buffering options.
+.IP 4. 4
+Functions to support Perl's traditional "fast" access to the buffer.
+.PP
+A layer does not have to implement all the functions, but the whole
+table has to be present. Unimplemented slots can be NULL (which will
+result in an error when called) or can be filled in with stubs to
+"inherit" behaviour from a "base class". This "inheritance" is fixed
+for all instances of the layer, but as the layer chooses which stubs
+to populate the table, limited "multiple inheritance" is possible.
+.SS "Per-instance Data"
+.IX Subsection "Per-instance Data"
+The per-instance data are held in memory beyond the basic PerlIOl
+struct, by making a PerlIOl the first member of the layer's struct
+thus:
+.PP
+.Vb 10
+\&        typedef struct
+\&        {
+\&         struct _PerlIO base;       /* Base "class" info */
+\&         STDCHAR *      buf;        /* Start of buffer */
+\&         STDCHAR *      end;        /* End of valid part of buffer */
+\&         STDCHAR *      ptr;        /* Current position in buffer */
+\&         Off_t          posn;       /* Offset of buf into the file */
+\&         Size_t         bufsiz;     /* Real size of buffer */
+\&         IV             oneword;    /* Emergency buffer */
+\&        } PerlIOBuf;
+.Ve
+.PP
+In this way (as for perl's scalars) a pointer to a PerlIOBuf can be
+treated as a pointer to a PerlIOl.
+.SS "Layers in action."
+.IX Subsection "Layers in action."
+.Vb 8
+\&                table           perlio          unix
+\&            |           |
+\&            +\-\-\-\-\-\-\-\-\-\-\-+    +\-\-\-\-\-\-\-\-\-\-+    +\-\-\-\-\-\-\-\-+
+\&   PerlIO \->|           |\-\-\->|  next    |\-\-\->|  NULL  |
+\&            +\-\-\-\-\-\-\-\-\-\-\-+    +\-\-\-\-\-\-\-\-\-\-+    +\-\-\-\-\-\-\-\-+
+\&            |           |    |  buffer  |    |   fd   |
+\&            +\-\-\-\-\-\-\-\-\-\-\-+    |          |    +\-\-\-\-\-\-\-\-+
+\&            |           |    +\-\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+The above attempts to show how the layer scheme works in a simple case.
+The application's \f(CW\*(C`PerlIO *\*(C'\fR points to an entry in the table(s)
+representing open (allocated) handles. For example the first three slots
+in the table correspond to \f(CW\*(C`stdin\*(C'\fR,\f(CW\*(C`stdout\*(C'\fR and \f(CW\*(C`stderr\*(C'\fR. The table
+in turn points to the current "top" layer for the handle \- in this case
+an instance of the generic buffering layer "perlio". That layer in turn
+points to the next layer down \- in this case the low-level "unix" layer.
+.PP
+The above is roughly equivalent to a "stdio" buffered stream, but with
+much more flexibility:
+.IP \(bu 4
+If Unix level \f(CW\*(C`read\*(C'\fR/\f(CW\*(C`write\*(C'\fR/\f(CW\*(C`lseek\*(C'\fR is not appropriate for (say)
+sockets then the "unix" layer can be replaced (at open time or even
+dynamically) with a "socket" layer.
+.IP \(bu 4
+Different handles can have different buffering schemes. The "top"
+layer could be the "mmap" layer if reading disk files was quicker
+using \f(CW\*(C`mmap\*(C'\fR than \f(CW\*(C`read\*(C'\fR. An "unbuffered" stream can be implemented
+simply by not having a buffer layer.
+.IP \(bu 4
+Extra layers can be inserted to process the data as it flows through.
+This was the driving need for including the scheme in perl 5.7.0+ \- we
+needed a mechanism to allow data to be translated between perl's
+internal encoding (conceptually at least Unicode as UTF\-8), and the
+"native" format used by the system. This is provided by the
+":encoding(xxxx)" layer which typically sits above the buffering layer.
+.IP \(bu 4
+A layer can be added that does "\en" to CRLF translation. This layer
+can be used on any platform, not just those that normally do such
+things.
+.SS "Per-instance flag bits"
+.IX Subsection "Per-instance flag bits"
+The generic flag bits are a hybrid of \f(CW\*(C`O_XXXXX\*(C'\fR style flags deduced
+from the mode string passed to \f(CWPerlIO_open()\fR, and state bits for
+typical buffer layers.
+.IP PERLIO_F_EOF 4
+.IX Item "PERLIO_F_EOF"
+End of file.
+.IP PERLIO_F_CANWRITE 4
+.IX Item "PERLIO_F_CANWRITE"
+Writes are permitted, i.e. opened as "w" or "r+" or "a", etc.
+.IP PERLIO_F_CANREAD 4
+.IX Item "PERLIO_F_CANREAD"
+Reads are permitted i.e. opened "r" or "w+" (or even "a+" \- ick).
+.IP PERLIO_F_ERROR 4
+.IX Item "PERLIO_F_ERROR"
+An error has occurred (for \f(CWPerlIO_error()\fR).
+.IP PERLIO_F_TRUNCATE 4
+.IX Item "PERLIO_F_TRUNCATE"
+Truncate file suggested by open mode.
+.IP PERLIO_F_APPEND 4
+.IX Item "PERLIO_F_APPEND"
+All writes should be appends.
+.IP PERLIO_F_CRLF 4
+.IX Item "PERLIO_F_CRLF"
+Layer is performing Win32\-like "\en" mapped to CR,LF for output and CR,LF
+mapped to "\en" for input. Normally the provided "crlf" layer is the only
+layer that need bother about this. \f(CWPerlIO_binmode()\fR will mess with this
+flag rather than add/remove layers if the \f(CW\*(C`PERLIO_K_CANCRLF\*(C'\fR bit is set
+for the layers class.
+.IP PERLIO_F_UTF8 4
+.IX Item "PERLIO_F_UTF8"
+Data written to this layer should be UTF\-8 encoded; data provided
+by this layer should be considered UTF\-8 encoded. Can be set on any layer
+by ":utf8" dummy layer. Also set on ":encoding" layer.
+.IP PERLIO_F_UNBUF 4
+.IX Item "PERLIO_F_UNBUF"
+Layer is unbuffered \- i.e. write to next layer down should occur for
+each write to this layer.
+.IP PERLIO_F_WRBUF 4
+.IX Item "PERLIO_F_WRBUF"
+The buffer for this layer currently holds data written to it but not sent
+to next layer.
+.IP PERLIO_F_RDBUF 4
+.IX Item "PERLIO_F_RDBUF"
+The buffer for this layer currently holds unconsumed data read from
+layer below.
+.IP PERLIO_F_LINEBUF 4
+.IX Item "PERLIO_F_LINEBUF"
+Layer is line buffered. Write data should be passed to next layer down
+whenever a "\en" is seen. Any data beyond the "\en" should then be
+processed.
+.IP PERLIO_F_TEMP 4
+.IX Item "PERLIO_F_TEMP"
+File has been \f(CWunlink()\fRed, or should be deleted on \f(CWclose()\fR.
+.IP PERLIO_F_OPEN 4
+.IX Item "PERLIO_F_OPEN"
+Handle is open.
+.IP PERLIO_F_FASTGETS 4
+.IX Item "PERLIO_F_FASTGETS"
+This instance of this layer supports the "fast \f(CW\*(C`gets\*(C'\fR" interface.
+Normally set based on \f(CW\*(C`PERLIO_K_FASTGETS\*(C'\fR for the class and by the
+existence of the function(s) in the table. However a class that
+normally provides that interface may need to avoid it on a
+particular instance. The "pending" layer needs to do this when
+it is pushed above a layer which does not support the interface.
+(Perl's \f(CWsv_gets()\fR does not expect the streams fast \f(CW\*(C`gets\*(C'\fR behaviour
+to change during one "get".)
+.SS "Methods in Detail"
+.IX Subsection "Methods in Detail"
+.IP fsize 4
+.IX Item "fsize"
+.Vb 1
+\&        Size_t fsize;
+.Ve
+.Sp
+Size of the function table. This is compared against the value PerlIO
+code "knows" as a compatibility check. Future versions \fImay\fR be able
+to tolerate layers compiled against an old version of the headers.
+.IP name 4
+.IX Item "name"
+.Vb 1
+\&        char * name;
+.Ve
+.Sp
+The name of the layer whose \fBopen()\fR method Perl should invoke on
+\&\fBopen()\fR.  For example if the layer is called APR, you will call:
+.Sp
+.Vb 1
+\&  open $fh, ">:APR", ...
+.Ve
+.Sp
+and Perl knows that it has to invoke the \fBPerlIOAPR_open()\fR method
+implemented by the APR layer.
+.IP size 4
+.IX Item "size"
+.Vb 1
+\&        Size_t size;
+.Ve
+.Sp
+The size of the per-instance data structure, e.g.:
+.Sp
+.Vb 1
+\&  sizeof(PerlIOAPR)
+.Ve
+.Sp
+If this field is zero then \f(CW\*(C`PerlIO_pushed\*(C'\fR does not malloc anything
+and assumes layer's Pushed function will do any required layer stack
+manipulation \- used to avoid malloc/free overhead for dummy layers.
+If the field is non-zero it must be at least the size of \f(CW\*(C`PerlIOl\*(C'\fR,
+\&\f(CW\*(C`PerlIO_pushed\*(C'\fR will allocate memory for the layer's data structures
+and link new layer onto the stream's stack. (If the layer's Pushed
+method returns an error indication the layer is popped again.)
+.IP kind 4
+.IX Item "kind"
+.Vb 1
+\&        IV kind;
+.Ve
+.RS 4
+.IP \(bu 4
+PERLIO_K_BUFFERED
+.Sp
+The layer is buffered.
+.IP \(bu 4
+PERLIO_K_RAW
+.Sp
+The layer is acceptable to have in a binmode(FH) stack \- i.e. it does not
+(or will configure itself not to) transform bytes passing through it.
+.IP \(bu 4
+PERLIO_K_CANCRLF
+.Sp
+Layer can translate between "\en" and CRLF line ends.
+.IP \(bu 4
+PERLIO_K_FASTGETS
+.Sp
+Layer allows buffer snooping.
+.IP \(bu 4
+PERLIO_K_MULTIARG
+.Sp
+Used when the layer's \fBopen()\fR accepts more arguments than usual. The
+extra arguments should come not before the \f(CW\*(C`MODE\*(C'\fR argument. When this
+flag is used it's up to the layer to validate the args.
+.RE
+.RS 4
+.RE
+.IP Pushed 4
+.IX Item "Pushed"
+.Vb 1
+\& IV     (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
+.Ve
+.Sp
+The only absolutely mandatory method. Called when the layer is pushed
+onto the stack.  The \f(CW\*(C`mode\*(C'\fR argument may be NULL if this occurs
+post-open. The \f(CW\*(C`arg\*(C'\fR will be non\-\f(CW\*(C`NULL\*(C'\fR if an argument string was
+passed. In most cases this should call \f(CWPerlIOBase_pushed()\fR to
+convert \f(CW\*(C`mode\*(C'\fR into the appropriate \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags in
+addition to any actions the layer itself takes.  If a layer is not
+expecting an argument it need neither save the one passed to it, nor
+provide \f(CWGetarg()\fR (it could perhaps \f(CW\*(C`Perl_warn\*(C'\fR that the argument
+was un-expected).
+.Sp
+Returns 0 on success. On failure returns \-1 and should set errno.
+.IP Popped 4
+.IX Item "Popped"
+.Vb 1
+\&        IV      (*Popped)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Called when the layer is popped from the stack. A layer will normally
+be popped after \f(CWClose()\fR is called. But a layer can be popped
+without being closed if the program is dynamically managing layers on
+the stream. In such cases \f(CWPopped()\fR should free any resources
+(buffers, translation tables, ...) not held directly in the layer's
+struct.  It should also \f(CWUnread()\fR any unconsumed data that has been
+read and buffered from the layer below back to that layer, so that it
+can be re-provided to what ever is now above.
+.Sp
+Returns 0 on success and failure.  If \f(CWPopped()\fR returns \fItrue\fR then
+\&\fIperlio.c\fR assumes that either the layer has popped itself, or the
+layer is super special and needs to be retained for other reasons.
+In most cases it should return \fIfalse\fR.
+.IP Open 4
+.IX Item "Open"
+.Vb 1
+\&        PerlIO *        (*Open)(...);
+.Ve
+.Sp
+The \f(CWOpen()\fR method has lots of arguments because it combines the
+functions of perl's \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`PerlIO_open\*(C'\fR, perl's \f(CW\*(C`sysopen\*(C'\fR,
+\&\f(CW\*(C`PerlIO_fdopen\*(C'\fR and \f(CW\*(C`PerlIO_reopen\*(C'\fR.  The full prototype is as
+follows:
+.Sp
+.Vb 6
+\& PerlIO *       (*Open)(pTHX_ PerlIO_funcs *tab,
+\&                        PerlIO_list_t *layers, IV n,
+\&                        const char *mode,
+\&                        int fd, int imode, int perm,
+\&                        PerlIO *old,
+\&                        int narg, SV **args);
+.Ve
+.Sp
+Open should (perhaps indirectly) call \f(CWPerlIO_allocate()\fR to allocate
+a slot in the table and associate it with the layers information for
+the opened file, by calling \f(CW\*(C`PerlIO_push\*(C'\fR.  The \fIlayers\fR is an
+array of all the layers destined for the \f(CW\*(C`PerlIO *\*(C'\fR, and any
+arguments passed to them, \fIn\fR is the index into that array of the
+layer being called. The macro \f(CW\*(C`PerlIOArg\*(C'\fR will return a (possibly
+\&\f(CW\*(C`NULL\*(C'\fR) SV * for the argument passed to the layer.
+.Sp
+Where a layer opens or takes ownership of a file descriptor, that layer is
+responsible for getting the file descriptor's close-on-exec flag into the
+correct state.  The flag should be clear for a file descriptor numbered
+less than or equal to \f(CW\*(C`PL_maxsysfd\*(C'\fR, and set for any file descriptor
+numbered higher.  For thread safety, when a layer opens a new file
+descriptor it should if possible open it with the close-on-exec flag
+initially set.
+.Sp
+The \fImode\fR string is an "\f(CWfopen()\fR\-like" string which would match
+the regular expression \f(CW\*(C`/^[I#]?[rwa]\e+?[bt]?$/\*(C'\fR.
+.Sp
+The \f(CW\*(AqI\*(Aq\fR prefix is used during creation of \f(CW\*(C`stdin\*(C'\fR..\f(CW\*(C`stderr\*(C'\fR via
+special \f(CW\*(C`PerlIO_fdopen\*(C'\fR calls; the \f(CW\*(Aq#\*(Aq\fR prefix means that this is
+\&\f(CW\*(C`sysopen\*(C'\fR and that \fIimode\fR and \fIperm\fR should be passed to
+\&\f(CW\*(C`PerlLIO_open3\*(C'\fR; \f(CW\*(Aqr\*(Aq\fR means \fBr\fRead, \f(CW\*(Aqw\*(Aq\fR means \fBw\fRrite and
+\&\f(CW\*(Aqa\*(Aq\fR means \fBa\fRppend. The \f(CW\*(Aq+\*(Aq\fR suffix means that both reading and
+writing/appending are permitted.  The \f(CW\*(Aqb\*(Aq\fR suffix means file should
+be binary, and \f(CW\*(Aqt\*(Aq\fR means it is text. (Almost all layers should do
+the IO in binary mode, and ignore the b/t bits. The \f(CW\*(C`:crlf\*(C'\fR layer
+should be pushed to handle the distinction.)
+.Sp
+If \fIold\fR is not \f(CW\*(C`NULL\*(C'\fR then this is a \f(CW\*(C`PerlIO_reopen\*(C'\fR. Perl itself
+does not use this (yet?) and semantics are a little vague.
+.Sp
+If \fIfd\fR not negative then it is the numeric file descriptor \fIfd\fR,
+which will be open in a manner compatible with the supplied mode
+string, the call is thus equivalent to \f(CW\*(C`PerlIO_fdopen\*(C'\fR. In this case
+\&\fInargs\fR will be zero.
+The file descriptor may have the close-on-exec flag either set or clear;
+it is the responsibility of the layer that takes ownership of it to get
+the flag into the correct state.
+.Sp
+If \fInargs\fR is greater than zero then it gives the number of arguments
+passed to \f(CW\*(C`open\*(C'\fR, otherwise it will be 1 if for example
+\&\f(CW\*(C`PerlIO_open\*(C'\fR was called.  In simple cases SvPV_nolen(*args) is the
+pathname to open.
+.Sp
+If a layer provides \f(CWOpen()\fR it should normally call the \f(CWOpen()\fR
+method of next layer down (if any) and then push itself on top if that
+succeeds.  \f(CW\*(C`PerlIOBase_open\*(C'\fR is provided to do exactly that, so in
+most cases you don't have to write your own \f(CWOpen()\fR method.  If this
+method is not defined, other layers may have difficulty pushing
+themselves on top of it during open.
+.Sp
+If \f(CW\*(C`PerlIO_push\*(C'\fR was performed and open has failed, it must
+\&\f(CW\*(C`PerlIO_pop\*(C'\fR itself, since if it's not, the layer won't be removed
+and may cause bad problems.
+.Sp
+Returns \f(CW\*(C`NULL\*(C'\fR on failure.
+.IP Binmode 4
+.IX Item "Binmode"
+.Vb 1
+\&        IV        (*Binmode)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Optional. Used when \f(CW\*(C`:raw\*(C'\fR layer is pushed (explicitly or as a result
+of binmode(FH)). If not present layer will be popped. If present
+should configure layer as binary (or pop itself) and return 0.
+If it returns \-1 for error \f(CW\*(C`binmode\*(C'\fR will fail with layer
+still on the stack.
+.IP Getarg 4
+.IX Item "Getarg"
+.Vb 2
+\&        SV *      (*Getarg)(pTHX_ PerlIO *f,
+\&                            CLONE_PARAMS *param, int flags);
+.Ve
+.Sp
+Optional. If present should return an SV * representing the string
+argument passed to the layer when it was
+pushed. e.g. ":encoding(ascii)" would return an SvPV with value
+"ascii". (\fIparam\fR and \fIflags\fR arguments can be ignored in most
+cases)
+.Sp
+\&\f(CW\*(C`Dup\*(C'\fR uses \f(CW\*(C`Getarg\*(C'\fR to retrieve the argument originally passed to
+\&\f(CW\*(C`Pushed\*(C'\fR, so you must implement this function if your layer has an
+extra argument to \f(CW\*(C`Pushed\*(C'\fR and will ever be \f(CW\*(C`Dup\*(C'\fRed.
+.IP Fileno 4
+.IX Item "Fileno"
+.Vb 1
+\&        IV        (*Fileno)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Returns the Unix/Posix numeric file descriptor for the handle. Normally
+\&\f(CWPerlIOBase_fileno()\fR (which just asks next layer down) will suffice
+for this.
+.Sp
+Returns \-1 on error, which is considered to include the case where the
+layer cannot provide such a file descriptor.
+.IP Dup 4
+.IX Item "Dup"
+.Vb 2
+\&        PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
+\&                        CLONE_PARAMS *param, int flags);
+.Ve
+.Sp
+XXX: Needs more docs.
+.Sp
+Used as part of the "clone" process when a thread is spawned (in which
+case param will be non-NULL) and when a stream is being duplicated via
+\&'&' in the \f(CW\*(C`open\*(C'\fR.
+.Sp
+Similar to \f(CW\*(C`Open\*(C'\fR, returns PerlIO* on success, \f(CW\*(C`NULL\*(C'\fR on failure.
+.IP Read 4
+.IX Item "Read"
+.Vb 1
+\&        SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
+.Ve
+.Sp
+Basic read operation.
+.Sp
+Typically will call \f(CW\*(C`Fill\*(C'\fR and manipulate pointers (possibly via the
+API).  \f(CWPerlIOBuf_read()\fR may be suitable for derived classes which
+provide "fast gets" methods.
+.Sp
+Returns actual bytes read, or \-1 on an error.
+.IP Unread 4
+.IX Item "Unread"
+.Vb 2
+\&        SSize_t (*Unread)(pTHX_ PerlIO *f,
+\&                          const void *vbuf, Size_t count);
+.Ve
+.Sp
+A superset of stdio's \f(CWungetc()\fR. Should arrange for future reads to
+see the bytes in \f(CW\*(C`vbuf\*(C'\fR. If there is no obviously better implementation
+then \f(CWPerlIOBase_unread()\fR provides the function by pushing a "fake"
+"pending" layer above the calling layer.
+.Sp
+Returns the number of unread chars.
+.IP Write 4
+.IX Item "Write"
+.Vb 1
+\&        SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
+.Ve
+.Sp
+Basic write operation.
+.Sp
+Returns bytes written or \-1 on an error.
+.IP Seek 4
+.IX Item "Seek"
+.Vb 1
+\&        IV      (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
+.Ve
+.Sp
+Position the file pointer. Should normally call its own \f(CW\*(C`Flush\*(C'\fR
+method and then the \f(CW\*(C`Seek\*(C'\fR method of next layer down.
+.Sp
+Returns 0 on success, \-1 on failure.
+.IP Tell 4
+.IX Item "Tell"
+.Vb 1
+\&        Off_t   (*Tell)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return the file pointer. May be based on layers cached concept of
+position to avoid overhead.
+.Sp
+Returns \-1 on failure to get the file pointer.
+.IP Close 4
+.IX Item "Close"
+.Vb 1
+\&        IV      (*Close)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Close the stream. Should normally call \f(CWPerlIOBase_close()\fR to flush
+itself and close layers below, and then deallocate any data structures
+(buffers, translation tables, ...) not  held directly in the data
+structure.
+.Sp
+Returns 0 on success, \-1 on failure.
+.IP Flush 4
+.IX Item "Flush"
+.Vb 1
+\&        IV      (*Flush)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Should make stream's state consistent with layers below. That is, any
+buffered write data should be written, and file position of lower layers
+adjusted for data read from below but not actually consumed.
+(Should perhaps \f(CWUnread()\fR such data to the lower layer.)
+.Sp
+Returns 0 on success, \-1 on failure.
+.IP Fill 4
+.IX Item "Fill"
+.Vb 1
+\&        IV      (*Fill)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+The buffer for this layer should be filled (for read) from layer
+below.  When you "subclass" PerlIOBuf layer, you want to use its
+\&\fI_read\fR method and to supply your own fill method, which fills the
+PerlIOBuf's buffer.
+.Sp
+Returns 0 on success, \-1 on failure.
+.IP Eof 4
+.IX Item "Eof"
+.Vb 1
+\&        IV      (*Eof)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return end-of-file indicator. \f(CWPerlIOBase_eof()\fR is normally sufficient.
+.Sp
+Returns 0 on end-of-file, 1 if not end-of-file, \-1 on error.
+.IP Error 4
+.IX Item "Error"
+.Vb 1
+\&        IV      (*Error)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return error indicator. \f(CWPerlIOBase_error()\fR is normally sufficient.
+.Sp
+Returns 1 if there is an error (usually when \f(CW\*(C`PERLIO_F_ERROR\*(C'\fR is set),
+0 otherwise.
+.IP Clearerr 4
+.IX Item "Clearerr"
+.Vb 1
+\&        void    (*Clearerr)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Clear end-of-file and error indicators. Should call \f(CWPerlIOBase_clearerr()\fR
+to set the \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags, which may suffice.
+.IP Setlinebuf 4
+.IX Item "Setlinebuf"
+.Vb 1
+\&        void    (*Setlinebuf)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Mark the stream as line buffered. \f(CWPerlIOBase_setlinebuf()\fR sets the
+PERLIO_F_LINEBUF flag and is normally sufficient.
+.IP Get_base 4
+.IX Item "Get_base"
+.Vb 1
+\&        STDCHAR *       (*Get_base)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Allocate (if not already done so) the read buffer for this layer and
+return pointer to it. Return NULL on failure.
+.IP Get_bufsiz 4
+.IX Item "Get_bufsiz"
+.Vb 1
+\&        Size_t  (*Get_bufsiz)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return the number of bytes that last \f(CWFill()\fR put in the buffer.
+.IP Get_ptr 4
+.IX Item "Get_ptr"
+.Vb 1
+\&        STDCHAR *       (*Get_ptr)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return the current read pointer relative to this layer's buffer.
+.IP Get_cnt 4
+.IX Item "Get_cnt"
+.Vb 1
+\&        SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
+.Ve
+.Sp
+Return the number of bytes left to be read in the current buffer.
+.IP Set_ptrcnt 4
+.IX Item "Set_ptrcnt"
+.Vb 2
+\&        void    (*Set_ptrcnt)(pTHX_ PerlIO *f,
+\&                              STDCHAR *ptr, SSize_t cnt);
+.Ve
+.Sp
+Adjust the read pointer and count of bytes to match \f(CW\*(C`ptr\*(C'\fR and/or \f(CW\*(C`cnt\*(C'\fR.
+The application (or layer above) must ensure they are consistent.
+(Checking is allowed by the paranoid.)
+.SS Utilities
+.IX Subsection "Utilities"
+To ask for the next layer down use PerlIONext(PerlIO *f).
+.PP
+To check that a PerlIO* is valid use PerlIOValid(PerlIO *f).  (All
+this does is really just to check that the pointer is non-NULL and
+that the pointer behind that is non-NULL.)
+.PP
+PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words,
+the \f(CW\*(C`PerlIOl*\*(C'\fR pointer.
+.PP
+PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
+.PP
+Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
+calls the \fIcallback\fR from the functions of the layer \fIf\fR (just by
+the name of the IO function, like "Read") with the \fIargs\fR, or if
+there is no such callback, calls the \fIbase\fR version of the callback
+with the same args, or if the f is invalid, set errno to EBADF and
+return \fIfailure\fR.
+.PP
+Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
+the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR,
+or if there is no such callback, set errno to EINVAL.  Or if the f is
+invalid, set errno to EBADF and return \fIfailure\fR.
+.PP
+Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
+the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR,
+or if there is no such callback, calls the \fIbase\fR version of the
+callback with the same args, or if the f is invalid, set errno to
+EBADF.
+.PP
+Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
+\&\fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, or if
+there is no such callback, set errno to EINVAL.  Or if the f is
+invalid, set errno to EBADF.
+.SS "Implementing PerlIO Layers"
+.IX Subsection "Implementing PerlIO Layers"
+If you find the implementation document unclear or not sufficient,
+look at the existing PerlIO layer implementations, which include:
+.IP \(bu 4
+C implementations
+.Sp
+The \fIperlio.c\fR and \fIperliol.h\fR in the Perl core implement the
+"unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending"
+layers, and also the "mmap" and "win32" layers if applicable.
+(The "win32" is currently unfinished and unused, to see what is used
+instead in Win32, see "Querying the layers of filehandles" in PerlIO .)
+.Sp
+PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
+.Sp
+PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
+.IP \(bu 4
+Perl implementations
+.Sp
+PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
+.PP
+If you are creating a PerlIO layer, you may want to be lazy, in other
+words, implement only the methods that interest you.  The other methods
+you can either replace with the "blank" methods
+.PP
+.Vb 2
+\&    PerlIOBase_noop_ok
+\&    PerlIOBase_noop_fail
+.Ve
+.PP
+(which do nothing, and return zero and \-1, respectively) or for
+certain methods you may assume a default behaviour by using a NULL
+method.  The Open method looks for help in the 'parent' layer.
+The following table summarizes the behaviour:
+.PP
+.Vb 1
+\&    method      behaviour with NULL
+\&
+\&    Clearerr    PerlIOBase_clearerr
+\&    Close       PerlIOBase_close
+\&    Dup         PerlIOBase_dup
+\&    Eof         PerlIOBase_eof
+\&    Error       PerlIOBase_error
+\&    Fileno      PerlIOBase_fileno
+\&    Fill        FAILURE
+\&    Flush       SUCCESS
+\&    Getarg      SUCCESS
+\&    Get_base    FAILURE
+\&    Get_bufsiz  FAILURE
+\&    Get_cnt     FAILURE
+\&    Get_ptr     FAILURE
+\&    Open        INHERITED
+\&    Popped      SUCCESS
+\&    Pushed      SUCCESS
+\&    Read        PerlIOBase_read
+\&    Seek        FAILURE
+\&    Set_cnt     FAILURE
+\&    Set_ptrcnt  FAILURE
+\&    Setlinebuf  PerlIOBase_setlinebuf
+\&    Tell        FAILURE
+\&    Unread      PerlIOBase_unread
+\&    Write       FAILURE
+\&
+\& FAILURE        Set errno (to EINVAL in Unixish, to LIB$_INVARG in VMS)
+\&                and return \-1 (for numeric return values) or NULL (for
+\&                pointers)
+\& INHERITED      Inherited from the layer below
+\& SUCCESS        Return 0 (for numeric return values) or a pointer
+.Ve
+.SS "Core Layers"
+.IX Subsection "Core Layers"
+The file \f(CW\*(C`perlio.c\*(C'\fR provides the following layers:
+.IP """unix""" 4
+.IX Item """unix"""
+A basic non-buffered layer which calls Unix/POSIX \f(CWread()\fR, \f(CWwrite()\fR,
+\&\f(CWlseek()\fR, \f(CWclose()\fR. No buffering. Even on platforms that distinguish
+between O_TEXT and O_BINARY this layer is always O_BINARY.
+.IP """perlio""" 4
+.IX Item """perlio"""
+A very complete generic buffering layer which provides the whole of
+PerlIO API. It is also intended to be used as a "base class" for other
+layers. (For example its \f(CWRead()\fR method is implemented in terms of
+the \f(CWGet_cnt()\fR/\f(CWGet_ptr()\fR/\f(CWSet_ptrcnt()\fR methods).
+.Sp
+"perlio" over "unix" provides a complete replacement for stdio as seen
+via PerlIO API. This is the default for USE_PERLIO when system's stdio
+does not permit perl's "fast gets" access, and which do not
+distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR.
+.IP """stdio""" 4
+.IX Item """stdio"""
+A layer which provides the PerlIO API via the layer scheme, but
+implements it by calling system's stdio. This is (currently) the default
+if system's stdio provides sufficient access to allow perl's "fast gets"
+access and which do not distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR.
+.IP """crlf""" 4
+.IX Item """crlf"""
+A layer derived using "perlio" as a base class. It provides Win32\-like
+"\en" to CR,LF translation. Can either be applied above "perlio" or serve
+as the buffer layer itself. "crlf" over "unix" is the default if system
+distinguishes between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR opens. (At some point
+"unix" will be replaced by a "native" Win32 IO layer on that platform,
+as Win32's read/write layer has various drawbacks.) The "crlf" layer is
+a reasonable model for a layer which transforms data in some way.
+.IP """mmap""" 4
+.IX Item """mmap"""
+If Configure detects \f(CWmmap()\fR functions this layer is provided (with
+"perlio" as a "base") which does "read" operations by \fBmmap()\fRing the
+file. Performance improvement is marginal on modern systems, so it is
+mainly there as a proof of concept. It is likely to be unbundled from
+the core at some point. The "mmap" layer is a reasonable model for a
+minimalist "derived" layer.
+.IP """pending""" 4
+.IX Item """pending"""
+An "internal" derivative of "perlio" which can be used to provide
+\&\fBUnread()\fR function for layers which have no buffer or cannot be
+bothered.  (Basically this layer's \f(CWFill()\fR pops itself off the stack
+and so resumes reading from layer below.)
+.IP """raw""" 4
+.IX Item """raw"""
+A dummy layer which never exists on the layer stack. Instead when
+"pushed" it actually pops the stack removing itself, it then calls
+Binmode function table entry on all the layers in the stack \- normally
+this (via PerlIOBase_binmode) removes any layers which do not have
+\&\f(CW\*(C`PERLIO_K_RAW\*(C'\fR bit set. Layers can modify that behaviour by defining
+their own Binmode entry.
+.IP """utf8""" 4
+.IX Item """utf8"""
+Another dummy layer. When pushed it pops itself and sets the
+\&\f(CW\*(C`PERLIO_F_UTF8\*(C'\fR flag on the layer which was (and now is once more)
+the top of the stack.
+.PP
+In addition \fIperlio.c\fR also provides a number of \f(CWPerlIOBase_xxxx()\fR
+functions which are intended to be used in the table slots of classes
+which do not need to do anything special for a particular method.
+.SS "Extension Layers"
+.IX Subsection "Extension Layers"
+Layers can be made available by extension modules. When an unknown layer
+is encountered the PerlIO code will perform the equivalent of :
+.PP
+.Vb 1
+\&   use PerlIO \*(Aqlayer\*(Aq;
+.Ve
+.PP
+Where \fIlayer\fR is the unknown layer. \fIPerlIO.pm\fR will then attempt to:
+.PP
+.Vb 1
+\&   require PerlIO::layer;
+.Ve
+.PP
+If after that process the layer is still not defined then the \f(CW\*(C`open\*(C'\fR
+will fail.
+.PP
+The following extension layers are bundled with perl:
+.IP """:encoding""" 4
+.IX Item """:encoding"""
+.Vb 1
+\&   use Encoding;
+.Ve
+.Sp
+makes this layer available, although \fIPerlIO.pm\fR "knows" where to
+find it.  It is an example of a layer which takes an argument as it is
+called thus:
+.Sp
+.Vb 1
+\&   open( $fh, "<:encoding(iso\-8859\-7)", $pathname );
+.Ve
+.IP """:scalar""" 4
+.IX Item """:scalar"""
+Provides support for reading data from and writing data to a scalar.
+.Sp
+.Vb 1
+\&   open( $fh, "+<:scalar", \e$scalar );
+.Ve
+.Sp
+When a handle is so opened, then reads get bytes from the string value
+of \fR\f(CI$scalar\fR\fI\fR, and writes change the value. In both cases the position
+in \fI\fR\f(CI$scalar\fR\fI\fR starts as zero but can be altered via \f(CW\*(C`seek\*(C'\fR, and
+determined via \f(CW\*(C`tell\*(C'\fR.
+.Sp
+Please note that this layer is implied when calling \fBopen()\fR thus:
+.Sp
+.Vb 1
+\&   open( $fh, "+<", \e$scalar );
+.Ve
+.IP """:via""" 4
+.IX Item """:via"""
+Provided to allow layers to be implemented as Perl code.  For instance:
+.Sp
+.Vb 2
+\&   use PerlIO::via::StripHTML;
+\&   open( my $fh, "<:via(StripHTML)", "index.html" );
+.Ve
+.Sp
+See PerlIO::via for details.
+.SH TODO
+.IX Header "TODO"
+Things that need to be done to improve this document.
+.IP \(bu 4
+Explain how to make a valid fh without going through \fBopen()\fR(i.e. apply
+a layer). For example if the file is not opened through perl, but we
+want to get back a fh, like it was opened by Perl.
+.Sp
+How PerlIO_apply_layera fits in, where its docs, was it made public?
+.Sp
+Currently the example could be something like this:
+.Sp
+.Vb 8
+\&  PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
+\&  {
+\&      char *mode; /* "w", "r", etc */
+\&      const char *layers = ":APR"; /* the layer name */
+\&      PerlIO *f = PerlIO_allocate(aTHX);
+\&      if (!f) {
+\&          return NULL;
+\&      }
+\&
+\&      PerlIO_apply_layers(aTHX_ f, mode, layers);
+\&
+\&      if (f) {
+\&          PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
+\&          /* fill in the st struct, as in _open() */
+\&          st\->file = file;
+\&          PerlIOBase(f)\->flags |= PERLIO_F_OPEN;
+\&
+\&          return f;
+\&      }
+\&      return NULL;
+\&  }
+.Ve
+.IP \(bu 4
+fix/add the documentation in places marked as XXX.
+.IP \(bu 4
+The handling of errors by the layer is not specified. e.g. when $!
+should be set explicitly, when the error handling should be just
+delegated to the top layer.
+.Sp
+Probably give some hints on using \fBSETERRNO()\fR or pointers to where they
+can be found.
+.IP \(bu 4
+I think it would help to give some concrete examples to make it easier
+to understand the API. Of course I agree that the API has to be
+concise, but since there is no second document that is more of a
+guide, I think that it'd make it easier to start with the doc which is
+an API, but has examples in it in places where things are unclear, to
+a person who is not a PerlIO guru (yet).
diff --git a/upstream/mageia-cauldron/man1/perlipc.1 b/upstream/mageia-cauldron/man1/perlipc.1
new file mode 100644
index 00000000..6b869be2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlipc.1
@@ -0,0 +1,1956 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLIPC 1"
+.TH PERLIPC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlipc \- Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The basic IPC facilities of Perl are built out of the good old Unix
+signals, named pipes, pipe opens, the Berkeley socket routines, and SysV
+IPC calls.  Each is used in slightly different situations.
+.SH Signals
+.IX Header "Signals"
+Perl uses a simple signal handling model: the \f(CW%SIG\fR hash contains names
+or references of user-installed signal handlers.  These handlers will
+be called with an argument which is the name of the signal that
+triggered it.  A signal may be generated intentionally from a
+particular keyboard sequence like control-C or control-Z, sent to you
+from another process, or triggered automatically by the kernel when
+special events transpire, like a child process exiting, your own process
+running out of stack space, or hitting a process file-size limit.
+.PP
+For example, to trap an interrupt signal, set up a handler like this:
+.PP
+.Vb 1
+\&    our $shucks;
+\&
+\&    sub catch_zap {
+\&        my $signame = shift;
+\&        $shucks++;
+\&        die "Somebody sent me a SIG$signame";
+\&    }
+\&    $SIG{INT} = _\|_PACKAGE_\|_ . "::catch_zap";
+\&    $SIG{INT} = \e&catch_zap;  # best strategy
+.Ve
+.PP
+Prior to Perl 5.8.0 it was necessary to do as little as you possibly
+could in your handler; notice how all we do is set a global variable
+and then raise an exception.  That's because on most systems,
+libraries are not re-entrant; particularly, memory allocation and I/O
+routines are not.  That meant that doing nearly \fIanything\fR in your
+handler could in theory trigger a memory fault and subsequent core
+dump \- see "Deferred Signals (Safe Signals)" below.
+.PP
+The names of the signals are the ones listed out by \f(CW\*(C`kill \-l\*(C'\fR on your
+system, or you can retrieve them using the CPAN module IPC::Signal.
+.PP
+You may also choose to assign the strings \f(CW"IGNORE"\fR or \f(CW"DEFAULT"\fR as
+the handler, in which case Perl will try to discard the signal or do the
+default thing.
+.PP
+On most Unix platforms, the \f(CW\*(C`CHLD\*(C'\fR (sometimes also known as \f(CW\*(C`CLD\*(C'\fR) signal
+has special behavior with respect to a value of \f(CW"IGNORE"\fR.
+Setting \f(CW$SIG{CHLD}\fR to \f(CW"IGNORE"\fR on such a platform has the effect of
+not creating zombie processes when the parent process fails to \f(CWwait()\fR
+on its child processes (i.e., child processes are automatically reaped).
+Calling \f(CWwait()\fR with \f(CW$SIG{CHLD}\fR set to \f(CW"IGNORE"\fR usually returns
+\&\f(CW\-1\fR on such platforms.
+.PP
+Some signals can be neither trapped nor ignored, such as the KILL and STOP
+(but not the TSTP) signals. Note that ignoring signals makes them disappear.
+If you only want them blocked temporarily without them getting lost you'll
+have to use the \f(CW\*(C`POSIX\*(C'\fR module's sigprocmask.
+.PP
+Sending a signal to a negative process ID means that you send the signal
+to the entire Unix process group.  This code sends a hang-up signal to all
+processes in the current process group, and also sets \f(CW$SIG\fR{HUP} to \f(CW"IGNORE"\fR
+so it doesn't kill itself:
+.PP
+.Vb 6
+\&    # block scope for local
+\&    {
+\&        local $SIG{HUP} = "IGNORE";
+\&        kill HUP => \-getpgrp();
+\&        # snazzy writing of: kill("HUP", \-getpgrp())
+\&    }
+.Ve
+.PP
+Another interesting signal to send is signal number zero.  This doesn't
+actually affect a child process, but instead checks whether it's alive
+or has changed its UIDs.
+.PP
+.Vb 3
+\&    unless (kill 0 => $kid_pid) {
+\&        warn "something wicked happened to $kid_pid";
+\&    }
+.Ve
+.PP
+Signal number zero may fail because you lack permission to send the
+signal when directed at a process whose real or saved UID is not
+identical to the real or effective UID of the sending process, even
+though the process is alive.  You may be able to determine the cause of
+failure using \f(CW$!\fR or \f(CW\*(C`%!\*(C'\fR.
+.PP
+.Vb 3
+\&    unless (kill(0 => $pid) || $!{EPERM}) {
+\&        warn "$pid looks dead";
+\&    }
+.Ve
+.PP
+You might also want to employ anonymous functions for simple signal
+handlers:
+.PP
+.Vb 1
+\&    $SIG{INT} = sub { die "\enOutta here!\en" };
+.Ve
+.PP
+SIGCHLD handlers require some special care.  If a second child dies
+while in the signal handler caused by the first death, we won't get
+another signal. So must loop here else we will leave the unreaped child
+as a zombie. And the next time two children die we get another zombie.
+And so on.
+.PP
+.Vb 7
+\&    use POSIX ":sys_wait_h";
+\&    $SIG{CHLD} = sub {
+\&        while ((my $child = waitpid(\-1, WNOHANG)) > 0) {
+\&            $Kid_Status{$child} = $?;
+\&        }
+\&    };
+\&    # do something that forks...
+.Ve
+.PP
+Be careful: \fBqx()\fR, \fBsystem()\fR, and some modules for calling external commands
+do a \fBfork()\fR, then \fBwait()\fR for the result. Thus, your signal handler
+will be called. Because \fBwait()\fR was already called by \fBsystem()\fR or \fBqx()\fR,
+the \fBwait()\fR in the signal handler will see no more zombies and will
+therefore block.
+.PP
+The best way to prevent this issue is to use \fBwaitpid()\fR, as in the following
+example:
+.PP
+.Vb 1
+\&    use POSIX ":sys_wait_h"; # for nonblocking read
+\&
+\&    my %children;
+\&
+\&    $SIG{CHLD} = sub {
+\&        # don\*(Aqt change $! and $? outside handler
+\&        local ($!, $?);
+\&        while ( (my $pid = waitpid(\-1, WNOHANG)) > 0 ) {
+\&            delete $children{$pid};
+\&            cleanup_child($pid, $?);
+\&        }
+\&    };
+\&
+\&    while (1) {
+\&        my $pid = fork();
+\&        die "cannot fork" unless defined $pid;
+\&        if ($pid == 0) {
+\&            # ...
+\&            exit 0;
+\&        } else {
+\&            $children{$pid}=1;
+\&            # ...
+\&            system($command);
+\&            # ...
+\&       }
+\&    }
+.Ve
+.PP
+Signal handling is also used for timeouts in Unix.  While safely
+protected within an \f(CW\*(C`eval{}\*(C'\fR block, you set a signal handler to trap
+alarm signals and then schedule to have one delivered to you in some
+number of seconds.  Then try your blocking operation, clearing the alarm
+when it's done but not before you've exited your \f(CW\*(C`eval{}\*(C'\fR block.  If it
+goes off, you'll use \fBdie()\fR to jump out of the block.
+.PP
+Here's an example:
+.PP
+.Vb 9
+\&    my $ALARM_EXCEPTION = "alarm clock restart";
+\&    eval {
+\&        local $SIG{ALRM} = sub { die $ALARM_EXCEPTION };
+\&        alarm 10;
+\&        flock($fh, 2)    # blocking write lock
+\&                        || die "cannot flock: $!";
+\&        alarm 0;
+\&    };
+\&    if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
+.Ve
+.PP
+If the operation being timed out is \fBsystem()\fR or \fBqx()\fR, this technique
+is liable to generate zombies.    If this matters to you, you'll
+need to do your own \fBfork()\fR and \fBexec()\fR, and kill the errant child process.
+.PP
+For more complex signal handling, you might see the standard POSIX
+module.  Lamentably, this is almost entirely undocumented, but the
+\&\fIext/POSIX/t/sigaction.t\fR file from the Perl source distribution has
+some examples in it.
+.SS "Handling the SIGHUP Signal in Daemons"
+.IX Subsection "Handling the SIGHUP Signal in Daemons"
+A process that usually starts when the system boots and shuts down
+when the system is shut down is called a daemon (Disk And Execution
+MONitor). If a daemon process has a configuration file which is
+modified after the process has been started, there should be a way to
+tell that process to reread its configuration file without stopping
+the process. Many daemons provide this mechanism using a \f(CW\*(C`SIGHUP\*(C'\fR
+signal handler. When you want to tell the daemon to reread the file,
+simply send it the \f(CW\*(C`SIGHUP\*(C'\fR signal.
+.PP
+The following example implements a simple daemon, which restarts
+itself every time the \f(CW\*(C`SIGHUP\*(C'\fR signal is received. The actual code is
+located in the subroutine \f(CWcode()\fR, which just prints some debugging
+info to show that it works; it should be replaced with the real code.
+.PP
+.Vb 1
+\&  #!/usr/bin/perl
+\&
+\&  use v5.36;
+\&
+\&  use POSIX ();
+\&  use FindBin ();
+\&  use File::Basename ();
+\&  use File::Spec::Functions qw(catfile);
+\&
+\&  $| = 1;
+\&
+\&  # make the daemon cross\-platform, so exec always calls the script
+\&  # itself with the right path, no matter how the script was invoked.
+\&  my $script = File::Basename::basename($0);
+\&  my $SELF  = catfile($FindBin::Bin, $script);
+\&
+\&  # POSIX unmasks the sigprocmask properly
+\&  $SIG{HUP} = sub {
+\&      print "got SIGHUP\en";
+\&      exec($SELF, @ARGV)        || die "$0: couldn\*(Aqt restart: $!";
+\&  };
+\&
+\&  code();
+\&
+\&  sub code {
+\&      print "PID: $$\en";
+\&      print "ARGV: @ARGV\en";
+\&      my $count = 0;
+\&      while (1) {
+\&          sleep 2;
+\&          print ++$count, "\en";
+\&      }
+\&  }
+.Ve
+.SS "Deferred Signals (Safe Signals)"
+.IX Subsection "Deferred Signals (Safe Signals)"
+Before Perl 5.8.0, installing Perl code to deal with signals exposed you to
+danger from two things.  First, few system library functions are
+re-entrant.  If the signal interrupts while Perl is executing one function
+(like \fBmalloc\fR\|(3) or \fBprintf\fR\|(3)), and your signal handler then calls the same
+function again, you could get unpredictable behavior\-\-often, a core dump.
+Second, Perl isn't itself re-entrant at the lowest levels.  If the signal
+interrupts Perl while Perl is changing its own internal data structures,
+similarly unpredictable behavior may result.
+.PP
+There were two things you could do, knowing this: be paranoid or be
+pragmatic.  The paranoid approach was to do as little as possible in your
+signal handler.  Set an existing integer variable that already has a
+value, and return.  This doesn't help you if you're in a slow system call,
+which will just restart.  That means you have to \f(CW\*(C`die\*(C'\fR to \fBlongjmp\fR\|(3) out
+of the handler.  Even this is a little cavalier for the true paranoiac,
+who avoids \f(CW\*(C`die\*(C'\fR in a handler because the system \fIis\fR out to get you.
+The pragmatic approach was to say "I know the risks, but prefer the
+convenience", and to do anything you wanted in your signal handler,
+and be prepared to clean up core dumps now and again.
+.PP
+Perl 5.8.0 and later avoid these problems by "deferring" signals.  That is,
+when the signal is delivered to the process by the system (to the C code
+that implements Perl) a flag is set, and the handler returns immediately.
+Then at strategic "safe" points in the Perl interpreter (e.g. when it is
+about to execute a new opcode) the flags are checked and the Perl level
+handler from \f(CW%SIG\fR is executed. The "deferred" scheme allows much more
+flexibility in the coding of signal handlers as we know the Perl
+interpreter is in a safe state, and that we are not in a system library
+function when the handler is called.  However the implementation does
+differ from previous Perls in the following ways:
+.IP "Long-running opcodes" 4
+.IX Item "Long-running opcodes"
+As the Perl interpreter looks at signal flags only when it is about
+to execute a new opcode, a signal that arrives during a long-running
+opcode (e.g. a regular expression operation on a very large string) will
+not be seen until the current opcode completes.
+.Sp
+If a signal of any given type fires multiple times during an opcode
+(such as from a fine-grained timer), the handler for that signal will
+be called only once, after the opcode completes; all other
+instances will be discarded.  Furthermore, if your system's signal queue
+gets flooded to the point that there are signals that have been raised
+but not yet caught (and thus not deferred) at the time an opcode
+completes, those signals may well be caught and deferred during
+subsequent opcodes, with sometimes surprising results.  For example, you
+may see alarms delivered even after calling \f(CWalarm(0)\fR as the latter
+stops the raising of alarms but does not cancel the delivery of alarms
+raised but not yet caught.  Do not depend on the behaviors described in
+this paragraph as they are side effects of the current implementation and
+may change in future versions of Perl.
+.IP "Interrupting IO" 4
+.IX Item "Interrupting IO"
+When a signal is delivered (e.g., SIGINT from a control-C) the operating
+system breaks into IO operations like \fIread\fR(2), which is used to
+implement Perl's \fBreadline()\fR function, the \f(CW\*(C`<>\*(C'\fR operator. On older
+Perls the handler was called immediately (and as \f(CW\*(C`read\*(C'\fR is not "unsafe",
+this worked well). With the "deferred" scheme the handler is \fInot\fR called
+immediately, and if Perl is using the system's \f(CW\*(C`stdio\*(C'\fR library that
+library may restart the \f(CW\*(C`read\*(C'\fR without returning to Perl to give it a
+chance to call the \f(CW%SIG\fR handler. If this happens on your system the
+solution is to use the \f(CW\*(C`:perlio\*(C'\fR layer to do IO\-\-at least on those handles
+that you want to be able to break into with signals. (The \f(CW\*(C`:perlio\*(C'\fR layer
+checks the signal flags and calls \f(CW%SIG\fR handlers before resuming IO
+operation.)
+.Sp
+The default in Perl 5.8.0 and later is to automatically use
+the \f(CW\*(C`:perlio\*(C'\fR layer.
+.Sp
+Note that it is not advisable to access a file handle within a signal
+handler where that signal has interrupted an I/O operation on that same
+handle. While perl will at least try hard not to crash, there are no
+guarantees of data integrity; for example, some data might get dropped or
+written twice.
+.Sp
+Some networking library functions like \fBgethostbyname()\fR are known to have
+their own implementations of timeouts which may conflict with your
+timeouts.  If you have problems with such functions, try using the POSIX
+\&\fBsigaction()\fR function, which bypasses Perl safe signals.  Be warned that
+this does subject you to possible memory corruption, as described above.
+.Sp
+Instead of setting \f(CW$SIG{ALRM}\fR:
+.Sp
+.Vb 1
+\&   local $SIG{ALRM} = sub { die "alarm" };
+.Ve
+.Sp
+try something like the following:
+.Sp
+.Vb 4
+\& use POSIX qw(SIGALRM);
+\& POSIX::sigaction(SIGALRM,
+\&                  POSIX::SigAction\->new(sub { die "alarm" }))
+\&          || die "Error setting SIGALRM handler: $!\en";
+.Ve
+.Sp
+Another way to disable the safe signal behavior locally is to use
+the \f(CW\*(C`Perl::Unsafe::Signals\*(C'\fR module from CPAN, which affects
+all signals.
+.IP "Restartable system calls" 4
+.IX Item "Restartable system calls"
+On systems that supported it, older versions of Perl used the
+SA_RESTART flag when installing \f(CW%SIG\fR handlers.  This meant that
+restartable system calls would continue rather than returning when
+a signal arrived.  In order to deliver deferred signals promptly,
+Perl 5.8.0 and later do \fInot\fR use SA_RESTART.  Consequently,
+restartable system calls can fail (with $! set to \f(CW\*(C`EINTR\*(C'\fR) in places
+where they previously would have succeeded.
+.Sp
+The default \f(CW\*(C`:perlio\*(C'\fR layer retries \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`write\*(C'\fR
+and \f(CW\*(C`close\*(C'\fR as described above; interrupted \f(CW\*(C`wait\*(C'\fR and
+\&\f(CW\*(C`waitpid\*(C'\fR calls will always be retried.
+.IP "Signals as ""faults""" 4
+.IX Item "Signals as ""faults"""
+Certain signals like SEGV, ILL, BUS and FPE are generated by virtual memory
+addressing errors and similar "faults". These are normally fatal: there is
+little a Perl-level handler can do with them.  So Perl delivers them
+immediately rather than attempting to defer them.
+.Sp
+It is possible to catch these with a \f(CW%SIG\fR handler (see perlvar),
+but on top of the usual problems of "unsafe" signals the signal is likely
+to get rethrown immediately on return from the signal handler, so such
+a handler should \f(CW\*(C`die\*(C'\fR or \f(CW\*(C`exit\*(C'\fR instead.
+.IP "Signals triggered by operating system state" 4
+.IX Item "Signals triggered by operating system state"
+On some operating systems certain signal handlers are supposed to "do
+something" before returning. One example can be CHLD or CLD, which
+indicates a child process has completed. On some operating systems the
+signal handler is expected to \f(CW\*(C`wait\*(C'\fR for the completed child
+process. On such systems the deferred signal scheme will not work for
+those signals: it does not do the \f(CW\*(C`wait\*(C'\fR. Again the failure will
+look like a loop as the operating system will reissue the signal because
+there are completed child processes that have not yet been \f(CW\*(C`wait\*(C'\fRed for.
+.PP
+If you want the old signal behavior back despite possible
+memory corruption, set the environment variable \f(CW\*(C`PERL_SIGNALS\*(C'\fR to
+\&\f(CW"unsafe"\fR.  This feature first appeared in Perl 5.8.1.
+.SH "Named Pipes"
+.IX Header "Named Pipes"
+A named pipe (often referred to as a FIFO) is an old Unix IPC
+mechanism for processes communicating on the same machine.  It works
+just like regular anonymous pipes, except that the
+processes rendezvous using a filename and need not be related.
+.PP
+To create a named pipe, use the \f(CWPOSIX::mkfifo()\fR function.
+.PP
+.Vb 2
+\&    use POSIX qw(mkfifo);
+\&    mkfifo($path, 0700)     ||  die "mkfifo $path failed: $!";
+.Ve
+.PP
+You can also use the Unix command \fBmknod\fR\|(1), or on some
+systems, \fBmkfifo\fR\|(1).  These may not be in your normal path, though.
+.PP
+.Vb 8
+\&    # system return val is backwards, so && not ||
+\&    #
+\&    $ENV{PATH} .= ":/etc:/usr/etc";
+\&    if  (      system("mknod",  $path, "p")
+\&            && system("mkfifo", $path) )
+\&    {
+\&        die "mk{nod,fifo} $path failed";
+\&    }
+.Ve
+.PP
+A fifo is convenient when you want to connect a process to an unrelated
+one.  When you open a fifo, the program will block until there's something
+on the other end.
+.PP
+For example, let's say you'd like to have your \fI.signature\fR file be a
+named pipe that has a Perl program on the other end.  Now every time any
+program (like a mailer, news reader, finger program, etc.) tries to read
+from that file, the reading program will read the new signature from your
+program.  We'll use the pipe-checking file-test operator, \fB\-p\fR, to find
+out whether anyone (or anything) has accidentally removed our fifo.
+.PP
+.Vb 2
+\&    chdir();    # go home
+\&    my $FIFO = ".signature";
+\&
+\&    while (1) {
+\&        unless (\-p $FIFO) {
+\&            unlink $FIFO;   # discard any failure, will catch later
+\&            require POSIX;  # delayed loading of heavy module
+\&            POSIX::mkfifo($FIFO, 0700)
+\&                                  || die "can\*(Aqt mkfifo $FIFO: $!";
+\&        }
+\&
+\&        # next line blocks till there\*(Aqs a reader
+\&        open (my $fh, ">", $FIFO) || die "can\*(Aqt open $FIFO: $!";
+\&        print $fh "John Smith (smith\e@host.org)\en", \`fortune \-s\`;
+\&        close($fh)                || die "can\*(Aqt close $FIFO: $!";
+\&        sleep 2;                # to avoid dup signals
+\&    }
+.Ve
+.SH "Using \fBopen()\fP for IPC"
+.IX Header "Using open() for IPC"
+Perl's basic \fBopen()\fR statement can also be used for unidirectional
+interprocess communication by specifying the open mode as \f(CW\*(C`|\-\*(C'\fR or \f(CW\*(C`\-|\*(C'\fR.
+Here's how to start
+something up in a child process you intend to write to:
+.PP
+.Vb 5
+\&    open(my $spooler, "|\-", "cat \-v | lpr \-h 2>/dev/null")
+\&                        || die "can\*(Aqt fork: $!";
+\&    local $SIG{PIPE} = sub { die "spooler pipe broke" };
+\&    print $spooler "stuff\en";
+\&    close $spooler      || die "bad spool: $! $?";
+.Ve
+.PP
+And here's how to start up a child process you intend to read from:
+.PP
+.Vb 7
+\&    open(my $status, "\-|", "netstat \-an 2>&1")
+\&                        || die "can\*(Aqt fork: $!";
+\&    while (<$status>) {
+\&        next if /^(tcp|udp)/;
+\&        print;
+\&    }
+\&    close $status       || die "bad netstat: $! $?";
+.Ve
+.PP
+Be aware that these operations are full Unix forks, which means they may
+not be correctly implemented on all alien systems.  See "open" in perlport
+for portability details.
+.PP
+In the two-argument form of \fBopen()\fR, a pipe open can be achieved by
+either appending or prepending a pipe symbol to the second argument:
+.PP
+.Vb 4
+\&    open(my $spooler, "| cat \-v | lpr \-h 2>/dev/null")
+\&                        || die "can\*(Aqt fork: $!";
+\&    open(my $status, "netstat \-an 2>&1 |")
+\&                        || die "can\*(Aqt fork: $!";
+.Ve
+.PP
+This can be used even on systems that do not support forking, but this
+possibly allows code intended to read files to unexpectedly execute
+programs.  If one can be sure that a particular program is a Perl script
+expecting filenames in \f(CW@ARGV\fR using the two-argument form of \fBopen()\fR or the
+\&\f(CW\*(C`<>\*(C'\fR operator, the clever programmer can write something like this:
+.PP
+.Vb 1
+\&    % program f1 "cmd1|" \- f2 "cmd2|" f3 < tmpfile
+.Ve
+.PP
+and no matter which sort of shell it's called from, the Perl program will
+read from the file \fIf1\fR, the process \fIcmd1\fR, standard input (\fItmpfile\fR
+in this case), the \fIf2\fR file, the \fIcmd2\fR command, and finally the \fIf3\fR
+file.  Pretty nifty, eh?
+.PP
+You might notice that you could use backticks for much the
+same effect as opening a pipe for reading:
+.PP
+.Vb 2
+\&    print grep { !/^(tcp|udp)/ } \`netstat \-an 2>&1\`;
+\&    die "bad netstatus ($?)" if $?;
+.Ve
+.PP
+While this is true on the surface, it's much more efficient to process the
+file one line or record at a time because then you don't have to read the
+whole thing into memory at once.  It also gives you finer control of the
+whole process, letting you kill off the child process early if you'd like.
+.PP
+Be careful to check the return values from both \fBopen()\fR and \fBclose()\fR.  If
+you're \fIwriting\fR to a pipe, you should also trap SIGPIPE.  Otherwise,
+think of what happens when you start up a pipe to a command that doesn't
+exist: the \fBopen()\fR will in all likelihood succeed (it only reflects the
+\&\fBfork()\fR's success), but then your output will fail\-\-spectacularly.  Perl
+can't know whether the command worked, because your command is actually
+running in a separate process whose \fBexec()\fR might have failed.  Therefore,
+while readers of bogus commands return just a quick EOF, writers
+to bogus commands will get hit with a signal, which they'd best be prepared
+to handle.  Consider:
+.PP
+.Vb 4
+\&    open(my $fh, "|\-", "bogus") || die "can\*(Aqt fork: $!";
+\&    print $fh "bang\en";         #  neither necessary nor sufficient
+\&                                #  to check print retval!
+\&    close($fh)                  || die "can\*(Aqt close: $!";
+.Ve
+.PP
+The reason for not checking the return value from \fBprint()\fR is because of
+pipe buffering; physical writes are delayed.  That won't blow up until the
+close, and it will blow up with a SIGPIPE.  To catch it, you could use
+this:
+.PP
+.Vb 4
+\&    $SIG{PIPE} = "IGNORE";
+\&    open(my $fh, "|\-", "bogus") || die "can\*(Aqt fork: $!";
+\&    print $fh "bang\en";
+\&    close($fh)                  || die "can\*(Aqt close: status=$?";
+.Ve
+.SS Filehandles
+.IX Subsection "Filehandles"
+Both the main process and any child processes it forks share the same
+STDIN, STDOUT, and STDERR filehandles.  If both processes try to access
+them at once, strange things can happen.  You may also want to close
+or reopen the filehandles for the child.  You can get around this by
+opening your pipe with \fBopen()\fR, but on some systems this means that the
+child process cannot outlive the parent.
+.SS "Background Processes"
+.IX Subsection "Background Processes"
+You can run a command in the background with:
+.PP
+.Vb 1
+\&    system("cmd &");
+.Ve
+.PP
+The command's STDOUT and STDERR (and possibly STDIN, depending on your
+shell) will be the same as the parent's.  You won't need to catch
+SIGCHLD because of the double-fork taking place; see below for details.
+.SS "Complete Dissociation of Child from Parent"
+.IX Subsection "Complete Dissociation of Child from Parent"
+In some cases (starting server processes, for instance) you'll want to
+completely dissociate the child process from the parent.  This is
+often called daemonization.  A well-behaved daemon will also \fBchdir()\fR
+to the root directory so it doesn't prevent unmounting the filesystem
+containing the directory from which it was launched, and redirect its
+standard file descriptors from and to \fI/dev/null\fR so that random
+output doesn't wind up on the user's terminal.
+.PP
+.Vb 1
+\& use POSIX "setsid";
+\&
+\& sub daemonize {
+\&     chdir("/")                     || die "can\*(Aqt chdir to /: $!";
+\&     open(STDIN,  "<", "/dev/null") || die "can\*(Aqt read /dev/null: $!";
+\&     open(STDOUT, ">", "/dev/null") || die "can\*(Aqt write /dev/null: $!";
+\&     defined(my $pid = fork())      || die "can\*(Aqt fork: $!";
+\&     exit if $pid;              # non\-zero now means I am the parent
+\&     (setsid() != \-1)           || die "Can\*(Aqt start a new session: $!";
+\&     open(STDERR, ">&", STDOUT) || die "can\*(Aqt dup stdout: $!";
+\& }
+.Ve
+.PP
+The \fBfork()\fR has to come before the \fBsetsid()\fR to ensure you aren't a
+process group leader; the \fBsetsid()\fR will fail if you are.  If your
+system doesn't have the \fBsetsid()\fR function, open \fI/dev/tty\fR and use the
+\&\f(CW\*(C`TIOCNOTTY\*(C'\fR \fBioctl()\fR on it instead.  See \fBtty\fR\|(4) for details.
+.PP
+Non-Unix users should check their \f(CW\*(C`\fR\f(CIYour_OS\fR\f(CW::Process\*(C'\fR module for
+other possible solutions.
+.SS "Safe Pipe Opens"
+.IX Subsection "Safe Pipe Opens"
+Another interesting approach to IPC is making your single program go
+multiprocess and communicate between\-\-or even amongst\-\-yourselves.  The
+two-argument form of the
+\&\fBopen()\fR function will accept a file argument of either \f(CW"\-|"\fR or \f(CW"|\-"\fR
+to do a very interesting thing: it forks a child connected to the
+filehandle you've opened.  The child is running the same program as the
+parent.  This is useful for safely opening a file when running under an
+assumed UID or GID, for example.  If you open a pipe \fIto\fR minus, you can
+write to the filehandle you opened and your kid will find it in \fIhis\fR
+STDIN.  If you open a pipe \fIfrom\fR minus, you can read from the filehandle
+you opened whatever your kid writes to \fIhis\fR STDOUT.
+.PP
+.Vb 4
+\&    my $PRECIOUS = "/path/to/some/safe/file";
+\&    my $sleep_count;
+\&    my $pid;
+\&    my $kid_to_write;
+\&
+\&    do {
+\&        $pid = open($kid_to_write, "|\-");
+\&        unless (defined $pid) {
+\&            warn "cannot fork: $!";
+\&            die "bailing out" if $sleep_count++ > 6;
+\&            sleep 10;
+\&        }
+\&    } until defined $pid;
+\&
+\&    if ($pid) {                 # I am the parent
+\&        print $kid_to_write @some_data;
+\&        close($kid_to_write)    || warn "kid exited $?";
+\&    } else {                    # I am the child
+\&        # drop permissions in setuid and/or setgid programs:
+\&        ($>, $)) = ($<, $();
+\&        open (my $outfile, ">", $PRECIOUS)
+\&                                || die "can\*(Aqt open $PRECIOUS: $!";
+\&        while (<STDIN>) {
+\&            print $outfile;     # child STDIN is parent $kid_to_write
+\&        }
+\&        close($outfile)         || die "can\*(Aqt close $PRECIOUS: $!";
+\&        exit(0);                # don\*(Aqt forget this!!
+\&    }
+.Ve
+.PP
+Another common use for this construct is when you need to execute
+something without the shell's interference.  With \fBsystem()\fR, it's
+straightforward, but you can't use a pipe open or backticks safely.
+That's because there's no way to stop the shell from getting its hands on
+your arguments.   Instead, use lower-level control to call \fBexec()\fR directly.
+.PP
+Here's a safe backtick or pipe open for read:
+.PP
+.Vb 2
+\&    my $pid = open(my $kid_to_read, "\-|");
+\&    defined($pid)            || die "can\*(Aqt fork: $!";
+\&
+\&    if ($pid) {             # parent
+\&        while (<$kid_to_read>) {
+\&                            # do something interesting
+\&        }
+\&        close($kid_to_read)  || warn "kid exited $?";
+\&
+\&    } else {                # child
+\&        ($>, $)) = ($<, $(); # suid only
+\&        exec($program, @options, @args)
+\&                             || die "can\*(Aqt exec program: $!";
+\&        # NOTREACHED
+\&    }
+.Ve
+.PP
+And here's a safe pipe open for writing:
+.PP
+.Vb 2
+\&    my $pid = open(my $kid_to_write, "|\-");
+\&    defined($pid)            || die "can\*(Aqt fork: $!";
+\&
+\&    $SIG{PIPE} = sub { die "whoops, $program pipe broke" };
+\&
+\&    if ($pid) {             # parent
+\&        print $kid_to_write @data;
+\&        close($kid_to_write) || warn "kid exited $?";
+\&
+\&    } else {                # child
+\&        ($>, $)) = ($<, $();
+\&        exec($program, @options, @args)
+\&                             || die "can\*(Aqt exec program: $!";
+\&        # NOTREACHED
+\&    }
+.Ve
+.PP
+It is very easy to dead-lock a process using this form of \fBopen()\fR, or
+indeed with any use of \fBpipe()\fR with multiple subprocesses.  The
+example above is "safe" because it is simple and calls \fBexec()\fR.  See
+"Avoiding Pipe Deadlocks" for general safety principles, but there
+are extra gotchas with Safe Pipe Opens.
+.PP
+In particular, if you opened the pipe using \f(CW\*(C`open $fh, "|\-"\*(C'\fR, then you
+cannot simply use \fBclose()\fR in the parent process to close an unwanted
+writer.  Consider this code:
+.PP
+.Vb 10
+\&    my $pid = open(my $writer, "|\-");        # fork open a kid
+\&    defined($pid)               || die "first fork failed: $!";
+\&    if ($pid) {
+\&        if (my $sub_pid = fork()) {
+\&            defined($sub_pid)   || die "second fork failed: $!";
+\&            close($writer)      || die "couldn\*(Aqt close writer: $!";
+\&            # now do something else...
+\&        }
+\&        else {
+\&            # first write to $writer
+\&            # ...
+\&            # then when finished
+\&            close($writer)      || die "couldn\*(Aqt close writer: $!";
+\&            exit(0);
+\&        }
+\&    }
+\&    else {
+\&        # first do something with STDIN, then
+\&        exit(0);
+\&    }
+.Ve
+.PP
+In the example above, the true parent does not want to write to the \f(CW$writer\fR
+filehandle, so it closes it.  However, because \f(CW$writer\fR was opened using
+\&\f(CW\*(C`open $fh, "|\-"\*(C'\fR, it has a special behavior: closing it calls
+\&\fBwaitpid()\fR (see "waitpid" in perlfunc), which waits for the subprocess
+to exit.  If the child process ends up waiting for something happening
+in the section marked "do something else", you have deadlock.
+.PP
+This can also be a problem with intermediate subprocesses in more
+complicated code, which will call \fBwaitpid()\fR on all open filehandles
+during global destruction\-\-in no predictable order.
+.PP
+To solve this, you must manually use \fBpipe()\fR, \fBfork()\fR, and the form of
+\&\fBopen()\fR which sets one file descriptor to another, as shown below:
+.PP
+.Vb 10
+\&    pipe(my $reader, my $writer)   || die "pipe failed: $!";
+\&    my $pid = fork();
+\&    defined($pid)                  || die "first fork failed: $!";
+\&    if ($pid) {
+\&        close $reader;
+\&        if (my $sub_pid = fork()) {
+\&            defined($sub_pid)      || die "first fork failed: $!";
+\&            close($writer)         || die "can\*(Aqt close writer: $!";
+\&        }
+\&        else {
+\&            # write to $writer...
+\&            # ...
+\&            # then  when finished
+\&            close($writer)         || die "can\*(Aqt close writer: $!";
+\&            exit(0);
+\&        }
+\&        # write to $writer...
+\&    }
+\&    else {
+\&        open(STDIN, "<&", $reader) || die "can\*(Aqt reopen STDIN: $!";
+\&        close($writer)             || die "can\*(Aqt close writer: $!";
+\&        # do something...
+\&        exit(0);
+\&    }
+.Ve
+.PP
+Since Perl 5.8.0, you can also use the list form of \f(CW\*(C`open\*(C'\fR for pipes.
+This is preferred when you wish to avoid having the shell interpret
+metacharacters that may be in your command string.
+.PP
+So for example, instead of using:
+.PP
+.Vb 1
+\&    open(my $ps_pipe, "\-|", "ps aux") || die "can\*(Aqt open ps pipe: $!";
+.Ve
+.PP
+One would use either of these:
+.PP
+.Vb 2
+\&    open(my $ps_pipe, "\-|", "ps", "aux")
+\&                                      || die "can\*(Aqt open ps pipe: $!";
+\&
+\&    my @ps_args = qw[ ps aux ];
+\&    open(my $ps_pipe, "\-|", @ps_args)
+\&                                      || die "can\*(Aqt open @ps_args|: $!";
+.Ve
+.PP
+Because there are more than three arguments to \fBopen()\fR, it forks the \fBps\fR\|(1)
+command \fIwithout\fR spawning a shell, and reads its standard output via the
+\&\f(CW$ps_pipe\fR filehandle.  The corresponding syntax to \fIwrite\fR to command
+pipes is to use \f(CW"|\-"\fR in place of \f(CW"\-|"\fR.
+.PP
+This was admittedly a rather silly example, because you're using string
+literals whose content is perfectly safe.  There is therefore no cause to
+resort to the harder-to-read, multi-argument form of pipe \fBopen()\fR.  However,
+whenever you cannot be assured that the program arguments are free of shell
+metacharacters, the fancier form of \fBopen()\fR should be used.  For example:
+.PP
+.Vb 3
+\&    my @grep_args = ("egrep", "\-i", $some_pattern, @many_files);
+\&    open(my $grep_pipe, "\-|", @grep_args)
+\&                        || die "can\*(Aqt open @grep_args|: $!";
+.Ve
+.PP
+Here the multi-argument form of pipe \fBopen()\fR is preferred because the
+pattern and indeed even the filenames themselves might hold metacharacters.
+.SS "Avoiding Pipe Deadlocks"
+.IX Subsection "Avoiding Pipe Deadlocks"
+Whenever you have more than one subprocess, you must be careful that each
+closes whichever half of any pipes created for interprocess communication
+it is not using.  This is because any child process reading from the pipe
+and expecting an EOF will never receive it, and therefore never exit. A
+single process closing a pipe is not enough to close it; the last process
+with the pipe open must close it for it to read EOF.
+.PP
+Certain built-in Unix features help prevent this most of the time.  For
+instance, filehandles have a "close on exec" flag, which is set \fIen masse\fR
+under control of the \f(CW$^F\fR variable.  This is so any filehandles you
+didn't explicitly route to the STDIN, STDOUT or STDERR of a child
+\&\fIprogram\fR will be automatically closed.
+.PP
+Always explicitly and immediately call \fBclose()\fR on the writable end of any
+pipe, unless that process is actually writing to it.  Even if you don't
+explicitly call \fBclose()\fR, Perl will still \fBclose()\fR all filehandles during
+global destruction.  As previously discussed, if those filehandles have
+been opened with Safe Pipe Open, this will result in calling \fBwaitpid()\fR,
+which may again deadlock.
+.SS "Bidirectional Communication with Another Process"
+.IX Subsection "Bidirectional Communication with Another Process"
+While this works reasonably well for unidirectional communication, what
+about bidirectional communication?  The most obvious approach doesn't work:
+.PP
+.Vb 2
+\&    # THIS DOES NOT WORK!!
+\&    open(my $prog_for_reading_and_writing, "| some program |")
+.Ve
+.PP
+If you forget to \f(CW\*(C`use warnings\*(C'\fR, you'll miss out entirely on the
+helpful diagnostic message:
+.PP
+.Vb 1
+\&    Can\*(Aqt do bidirectional pipe at \-e line 1.
+.Ve
+.PP
+If you really want to, you can use the standard \fBopen2()\fR from the
+IPC::Open2 module to catch both ends.  There's also an \fBopen3()\fR in
+IPC::Open3 for tridirectional I/O so you can also catch your child's
+STDERR, but doing so would then require an awkward \fBselect()\fR loop and
+wouldn't allow you to use normal Perl input operations.
+.PP
+If you look at its source, you'll see that \fBopen2()\fR uses low-level
+primitives like the \fBpipe()\fR and \fBexec()\fR syscalls to create all the
+connections.  Although it might have been more efficient by using
+\&\fBsocketpair()\fR, this would have been even less portable than it already
+is. The \fBopen2()\fR and \fBopen3()\fR functions are unlikely to work anywhere
+except on a Unix system, or at least one purporting POSIX compliance.
+.PP
+Here's an example of using \fBopen2()\fR:
+.PP
+.Vb 5
+\&    use IPC::Open2;
+\&    my $pid = open2(my $reader, my $writer, "cat \-un");
+\&    print $writer "stuff\en";
+\&    my $got = <$reader>;
+\&    waitpid $pid, 0;
+.Ve
+.PP
+The problem with this is that buffering is really going to ruin your
+day.  Even though your \f(CW$writer\fR filehandle is auto-flushed so the process
+on the other end gets your data in a timely manner, you can't usually do
+anything to force that process to give its data to you in a similarly quick
+fashion.  In this special case, we could actually so, because we gave
+\&\fIcat\fR a \fB\-u\fR flag to make it unbuffered.  But very few commands are
+designed to operate over pipes, so this seldom works unless you yourself
+wrote the program on the other end of the double-ended pipe.
+.PP
+A solution to this is to use a library which uses pseudottys to make your
+program behave more reasonably.  This way you don't have to have control
+over the source code of the program you're using.  The \f(CW\*(C`Expect\*(C'\fR module
+from CPAN also addresses this kind of thing.  This module requires two
+other modules from CPAN, \f(CW\*(C`IO::Pty\*(C'\fR and \f(CW\*(C`IO::Stty\*(C'\fR.  It sets up a pseudo
+terminal to interact with programs that insist on talking to the terminal
+device driver.  If your system is supported, this may be your best bet.
+.SS "Bidirectional Communication with Yourself"
+.IX Subsection "Bidirectional Communication with Yourself"
+If you want, you may make low-level \fBpipe()\fR and \fBfork()\fR syscalls to stitch
+this together by hand.  This example only talks to itself, but you could
+reopen the appropriate handles to STDIN and STDOUT and call other processes.
+(The following example lacks proper error checking.)
+.PP
+.Vb 9
+\& #!/usr/bin/perl
+\& # pipe1 \- bidirectional communication using two pipe pairs
+\& #         designed for the socketpair\-challenged
+\& use v5.36;
+\& use IO::Handle;  # enable autoflush method before Perl 5.14
+\& pipe(my $parent_rdr, my $child_wtr);  # XXX: check failure?
+\& pipe(my $child_rdr,  my $parent_wtr); # XXX: check failure?
+\& $child_wtr\->autoflush(1);
+\& $parent_wtr\->autoflush(1);
+\&
+\& if ($pid = fork()) {
+\&     close $parent_rdr;
+\&     close $parent_wtr;
+\&     print $child_wtr "Parent Pid $$ is sending this\en";
+\&     chomp(my $line = <$child_rdr>);
+\&     print "Parent Pid $$ just read this: \*(Aq$line\*(Aq\en";
+\&     close $child_rdr; close $child_wtr;
+\&     waitpid($pid, 0);
+\& } else {
+\&     die "cannot fork: $!" unless defined $pid;
+\&     close $child_rdr;
+\&     close $child_wtr;
+\&     chomp(my $line = <$parent_rdr>);
+\&     print "Child Pid $$ just read this: \*(Aq$line\*(Aq\en";
+\&     print $parent_wtr "Child Pid $$ is sending this\en";
+\&     close $parent_rdr;
+\&     close $parent_wtr;
+\&     exit(0);
+\& }
+.Ve
+.PP
+But you don't actually have to make two pipe calls.  If you
+have the \fBsocketpair()\fR system call, it will do this all for you.
+.PP
+.Vb 3
+\& #!/usr/bin/perl
+\& # pipe2 \- bidirectional communication using socketpair
+\& #   "the best ones always go both ways"
+\&
+\& use v5.36;
+\& use Socket;
+\& use IO::Handle;  # enable autoflush method before Perl 5.14
+\&
+\& # We say AF_UNIX because although *_LOCAL is the
+\& # POSIX 1003.1g form of the constant, many machines
+\& # still don\*(Aqt have it.
+\& socketpair(my $child, my $parent, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
+\&                             ||  die "socketpair: $!";
+\&
+\& $child\->autoflush(1);
+\& $parent\->autoflush(1);
+\&
+\& if ($pid = fork()) {
+\&     close $parent;
+\&     print $child "Parent Pid $$ is sending this\en";
+\&     chomp(my $line = <$child>);
+\&     print "Parent Pid $$ just read this: \*(Aq$line\*(Aq\en";
+\&     close $child;
+\&     waitpid($pid, 0);
+\& } else {
+\&     die "cannot fork: $!" unless defined $pid;
+\&     close $child;
+\&     chomp(my $line = <$parent>);
+\&     print "Child Pid $$ just read this: \*(Aq$line\*(Aq\en";
+\&     print $parent "Child Pid $$ is sending this\en";
+\&     close $parent;
+\&     exit(0);
+\& }
+.Ve
+.SH "Sockets: Client/Server Communication"
+.IX Header "Sockets: Client/Server Communication"
+While not entirely limited to Unix-derived operating systems (e.g., WinSock
+on PCs provides socket support, as do some VMS libraries), you might not have
+sockets on your system, in which case this section probably isn't going to
+do you much good.  With sockets, you can do both virtual circuits like TCP
+streams and datagrams like UDP packets.  You may be able to do even more
+depending on your system.
+.PP
+The Perl functions for dealing with sockets have the same names as
+the corresponding system calls in C, but their arguments tend to differ
+for two reasons.  First, Perl filehandles work differently than C file
+descriptors.  Second, Perl already knows the length of its strings, so you
+don't need to pass that information.
+.PP
+One of the major problems with ancient, antemillennial socket code in Perl
+was that it used hard-coded values for some of the constants, which
+severely hurt portability.  If you ever see code that does anything like
+explicitly setting \f(CW\*(C`$AF_INET = 2\*(C'\fR, you know you're in for big trouble.
+An immeasurably superior approach is to use the Socket module, which more
+reliably grants access to the various constants and functions you'll need.
+.PP
+If you're not writing a server/client for an existing protocol like
+NNTP or SMTP, you should give some thought to how your server will
+know when the client has finished talking, and vice-versa.  Most
+protocols are based on one-line messages and responses (so one party
+knows the other has finished when a "\en" is received) or multi-line
+messages and responses that end with a period on an empty line
+("\en.\en" terminates a message/response).
+.SS "Internet Line Terminators"
+.IX Subsection "Internet Line Terminators"
+The Internet line terminator is "\e015\e012".  Under ASCII variants of
+Unix, that could usually be written as "\er\en", but under other systems,
+"\er\en" might at times be "\e015\e015\e012", "\e012\e012\e015", or something
+completely different.  The standards specify writing "\e015\e012" to be
+conformant (be strict in what you provide), but they also recommend
+accepting a lone "\e012" on input (be lenient in what you require).
+We haven't always been very good about that in the code in this manpage,
+but unless you're on a Mac from way back in its pre-Unix dark ages, you'll
+probably be ok.
+.SS "Internet TCP Clients and Servers"
+.IX Subsection "Internet TCP Clients and Servers"
+Use Internet-domain sockets when you want to do client-server
+communication that might extend to machines outside of your own system.
+.PP
+Here's a sample TCP client using Internet-domain sockets:
+.PP
+.Vb 3
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use Socket;
+\&
+\&    my $remote  = shift || "localhost";
+\&    my $port    = shift || 2345;  # random port
+\&    if ($port =~ /\eD/) { $port = getservbyname($port, "tcp") }
+\&    die "No port" unless $port;
+\&    my $iaddr   = inet_aton($remote)       || die "no host: $remote";
+\&    my $paddr   = sockaddr_in($port, $iaddr);
+\&
+\&    my $proto   = getprotobyname("tcp");
+\&    socket(my $sock, PF_INET, SOCK_STREAM, $proto)  || die "socket: $!";
+\&    connect($sock, $paddr)              || die "connect: $!";
+\&    while (my $line = <$sock>) {
+\&        print $line;
+\&    }
+\&
+\&    close ($sock)                        || die "close: $!";
+\&    exit(0);
+.Ve
+.PP
+And here's a corresponding server to go along with it.  We'll
+leave the address as \f(CW\*(C`INADDR_ANY\*(C'\fR so that the kernel can choose
+the appropriate interface on multihomed hosts.  If you want sit
+on a particular interface (like the external side of a gateway
+or firewall machine), fill this in with your real address instead.
+.PP
+.Vb 6
+\& #!/usr/bin/perl \-T
+\& use v5.36;
+\& BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
+\& use Socket;
+\& use Carp;
+\& my $EOL = "\e015\e012";
+\&
+\& sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\en" }
+\&
+\& my $port  = shift || 2345;
+\& die "invalid port" unless $port =~ /^ \ed+ $/x;
+\&
+\& my $proto = getprotobyname("tcp");
+\&
+\& socket(my $server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
+\& setsockopt($server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
+\&                                               || die "setsockopt: $!";
+\& bind($server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
+\& listen($server, SOMAXCONN)                    || die "listen: $!";
+\&
+\& logmsg "server started on port $port";
+\&
+\& for (my $paddr; $paddr = accept(my $client, $server); close $client) {
+\&     my($port, $iaddr) = sockaddr_in($paddr);
+\&     my $name = gethostbyaddr($iaddr, AF_INET);
+\&
+\&     logmsg "connection from $name [",
+\&             inet_ntoa($iaddr), "]
+\&             at port $port";
+\&
+\&     print $client "Hello there, $name, it\*(Aqs now ",
+\&                     scalar localtime(), $EOL;
+\& }
+.Ve
+.PP
+And here's a multitasking version.  It's multitasked in that
+like most typical servers, it spawns (\fBfork()\fRs) a child server to
+handle the client request so that the master server can quickly
+go back to service a new client.
+.PP
+.Vb 6
+\& #!/usr/bin/perl \-T
+\& use v5.36;
+\& BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
+\& use Socket;
+\& use Carp;
+\& my $EOL = "\e015\e012";
+\&
+\& sub spawn;  # forward declaration
+\& sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\en" }
+\&
+\& my $port  = shift || 2345;
+\& die "invalid port" unless $port =~ /^ \ed+ $/x;
+\&
+\& my $proto = getprotobyname("tcp");
+\&
+\& socket(my $server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
+\& setsockopt($server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
+\&                                               || die "setsockopt: $!";
+\& bind($server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
+\& listen($server, SOMAXCONN)                    || die "listen: $!";
+\&
+\& logmsg "server started on port $port";
+\&
+\& my $waitedpid = 0;
+\&
+\& use POSIX ":sys_wait_h";
+\& use Errno;
+\&
+\& sub REAPER {
+\&     local $!;   # don\*(Aqt let waitpid() overwrite current error
+\&     while ((my $pid = waitpid(\-1, WNOHANG)) > 0 && WIFEXITED($?)) {
+\&         logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
+\&     }
+\&     $SIG{CHLD} = \e&REAPER;  # loathe SysV
+\& }
+\&
+\& $SIG{CHLD} = \e&REAPER;
+\&
+\& while (1) {
+\&     my $paddr = accept(my $client, $server) || do {
+\&         # try again if accept() returned because got a signal
+\&         next if $!{EINTR};
+\&         die "accept: $!";
+\&     };
+\&     my ($port, $iaddr) = sockaddr_in($paddr);
+\&     my $name = gethostbyaddr($iaddr, AF_INET);
+\&
+\&     logmsg "connection from $name [",
+\&            inet_ntoa($iaddr),
+\&            "] at port $port";
+\&
+\&     spawn $client, sub {
+\&         $| = 1;
+\&         print "Hello there, $name, it\*(Aqs now ",
+\&               scalar localtime(),
+\&               $EOL;
+\&         exec "/usr/games/fortune"       # XXX: "wrong" line terminators
+\&             or confess "can\*(Aqt exec fortune: $!";
+\&     };
+\&     close $client;
+\& }
+\&
+\& sub spawn {
+\&     my $client = shift;
+\&     my $coderef = shift;
+\&
+\&     unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
+\&         confess "usage: spawn CLIENT CODEREF";
+\&     }
+\&
+\&     my $pid;
+\&     unless (defined($pid = fork())) {
+\&         logmsg "cannot fork: $!";
+\&         return;
+\&     }
+\&     elsif ($pid) {
+\&         logmsg "begat $pid";
+\&         return; # I\*(Aqm the parent
+\&     }
+\&     # else I\*(Aqm the child \-\- go spawn
+\&
+\&     open(STDIN,  "<&", $client)   || die "can\*(Aqt dup client to stdin";
+\&     open(STDOUT, ">&", $client)   || die "can\*(Aqt dup client to stdout";
+\&     ## open(STDERR, ">&", STDOUT) || die "can\*(Aqt dup stdout to stderr";
+\&     exit($coderef\->());
+\& }
+.Ve
+.PP
+This server takes the trouble to clone off a child version via \fBfork()\fR
+for each incoming request.  That way it can handle many requests at
+once, which you might not always want.  Even if you don't \fBfork()\fR, the
+\&\fBlisten()\fR will allow that many pending connections.  Forking servers
+have to be particularly careful about cleaning up their dead children
+(called "zombies" in Unix parlance), because otherwise you'll quickly
+fill up your process table.  The REAPER subroutine is used here to
+call \fBwaitpid()\fR for any child processes that have finished, thereby
+ensuring that they terminate cleanly and don't join the ranks of the
+living dead.
+.PP
+Within the while loop we call \fBaccept()\fR and check to see if it returns
+a false value.  This would normally indicate a system error needs
+to be reported.  However, the introduction of safe signals (see
+"Deferred Signals (Safe Signals)" above) in Perl 5.8.0 means that
+\&\fBaccept()\fR might also be interrupted when the process receives a signal.
+This typically happens when one of the forked subprocesses exits and
+notifies the parent process with a CHLD signal.
+.PP
+If \fBaccept()\fR is interrupted by a signal, $! will be set to EINTR.
+If this happens, we can safely continue to the next iteration of
+the loop and another call to \fBaccept()\fR.  It is important that your
+signal handling code not modify the value of $!, or else this test
+will likely fail.  In the REAPER subroutine we create a local version
+of $! before calling \fBwaitpid()\fR.  When \fBwaitpid()\fR sets $! to ECHILD as
+it inevitably does when it has no more children waiting, it
+updates the local copy and leaves the original unchanged.
+.PP
+You should use the \fB\-T\fR flag to enable taint checking (see perlsec)
+even if we aren't running setuid or setgid.  This is always a good idea
+for servers or any program run on behalf of someone else (like CGI
+scripts), because it lessens the chances that people from the outside will
+be able to compromise your system.
+Note that perl can be built without taint support.  There are two
+different modes: in one, \fB\-T\fR will silently do nothing.  In the other
+mode \fB\-T\fR results in a fatal error.
+.PP
+Let's look at another TCP client.  This one connects to the TCP "time"
+service on a number of different machines and shows how far their clocks
+differ from the system on which it's being run:
+.PP
+.Vb 3
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use Socket;
+\&
+\&    my $SECS_OF_70_YEARS = 2208988800;
+\&    sub ctime { scalar localtime(shift() || time()) }
+\&
+\&    my $iaddr = gethostbyname("localhost");
+\&    my $proto = getprotobyname("tcp");
+\&    my $port = getservbyname("time", "tcp");
+\&    my $paddr = sockaddr_in(0, $iaddr);
+\&
+\&    $| = 1;
+\&    printf "%\-24s %8s %s\en", "localhost", 0, ctime();
+\&
+\&    foreach my $host (@ARGV) {
+\&        printf "%\-24s ", $host;
+\&        my $hisiaddr = inet_aton($host)     || die "unknown host";
+\&        my $hispaddr = sockaddr_in($port, $hisiaddr);
+\&        socket(my $socket, PF_INET, SOCK_STREAM, $proto)
+\&                                            || die "socket: $!";
+\&        connect($socket, $hispaddr)         || die "connect: $!";
+\&        my $rtime = pack("C4", ());
+\&        read($socket, $rtime, 4);
+\&        close($socket);
+\&        my $histime = unpack("N", $rtime) \- $SECS_OF_70_YEARS;
+\&        printf "%8d %s\en", $histime \- time(), ctime($histime);
+\&    }
+.Ve
+.SS "Unix-Domain TCP Clients and Servers"
+.IX Subsection "Unix-Domain TCP Clients and Servers"
+That's fine for Internet-domain clients and servers, but what about local
+communications?  While you can use the same setup, sometimes you don't
+want to.  Unix-domain sockets are local to the current host, and are often
+used internally to implement pipes.  Unlike Internet domain sockets, Unix
+domain sockets can show up in the file system with an \fBls\fR\|(1) listing.
+.PP
+.Vb 2
+\&    % ls \-l /dev/log
+\&    srw\-rw\-rw\-  1 root            0 Oct 31 07:23 /dev/log
+.Ve
+.PP
+You can test for these with Perl's \fB\-S\fR file test:
+.PP
+.Vb 3
+\&    unless (\-S "/dev/log") {
+\&        die "something\*(Aqs wicked with the log system";
+\&    }
+.Ve
+.PP
+Here's a sample Unix-domain client:
+.PP
+.Vb 3
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use Socket;
+\&
+\&    my $rendezvous = shift || "catsock";
+\&    socket(my $sock, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
+\&    connect($sock, sockaddr_un($rendezvous))  || die "connect: $!";
+\&    while (defined(my $line = <$sock>)) {
+\&        print $line;
+\&    }
+\&    exit(0);
+.Ve
+.PP
+And here's a corresponding server.  You don't have to worry about silly
+network terminators here because Unix domain sockets are guaranteed
+to be on the localhost, and thus everything works right.
+.PP
+.Vb 4
+\&    #!/usr/bin/perl \-T
+\&    use v5.36;
+\&    use Socket;
+\&    use Carp;
+\&
+\&    BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
+\&    sub spawn;  # forward declaration
+\&    sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\en" }
+\&
+\&    my $NAME = "catsock";
+\&    my $uaddr = sockaddr_un($NAME);
+\&    my $proto = getprotobyname("tcp");
+\&
+\&    socket(my $server, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
+\&    unlink($NAME);
+\&    bind  ($server, $uaddr)                     || die "bind: $!";
+\&    listen($server, SOMAXCONN)                  || die "listen: $!";
+\&
+\&    logmsg "server started on $NAME";
+\&
+\&    my $waitedpid;
+\&
+\&    use POSIX ":sys_wait_h";
+\&    sub REAPER {
+\&        my $child;
+\&        while (($waitedpid = waitpid(\-1, WNOHANG)) > 0) {
+\&            logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
+\&        }
+\&        $SIG{CHLD} = \e&REAPER;  # loathe SysV
+\&    }
+\&
+\&    $SIG{CHLD} = \e&REAPER;
+\&
+\&
+\&    for ( $waitedpid = 0;
+\&          accept(my $client, $server) || $waitedpid;
+\&          $waitedpid = 0, close $client)
+\&    {
+\&        next if $waitedpid;
+\&        logmsg "connection on $NAME";
+\&        spawn $client, sub {
+\&            print "Hello there, it\*(Aqs now ", scalar localtime(), "\en";
+\&            exec("/usr/games/fortune")  || die "can\*(Aqt exec fortune: $!";
+\&        };
+\&    }
+\&
+\&    sub spawn {
+\&        my $client = shift();
+\&        my $coderef = shift();
+\&
+\&        unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
+\&            confess "usage: spawn CLIENT CODEREF";
+\&        }
+\&
+\&        my $pid;
+\&        unless (defined($pid = fork())) {
+\&            logmsg "cannot fork: $!";
+\&            return;
+\&        }
+\&        elsif ($pid) {
+\&            logmsg "begat $pid";
+\&            return; # I\*(Aqm the parent
+\&        }
+\&        else {
+\&            # I\*(Aqm the child \-\- go spawn
+\&        }
+\&
+\&        open(STDIN,  "<&", $client)
+\&            || die "can\*(Aqt dup client to stdin";
+\&        open(STDOUT, ">&", $client)
+\&            || die "can\*(Aqt dup client to stdout";
+\&        ## open(STDERR, ">&", STDOUT)
+\&        ##  || die "can\*(Aqt dup stdout to stderr";
+\&        exit($coderef\->());
+\&    }
+.Ve
+.PP
+As you see, it's remarkably similar to the Internet domain TCP server, so
+much so, in fact, that we've omitted several duplicate functions\-\-\fBspawn()\fR,
+\&\fBlogmsg()\fR, \fBctime()\fR, and \fBREAPER()\fR\-\-which are the same as in the other server.
+.PP
+So why would you ever want to use a Unix domain socket instead of a
+simpler named pipe?  Because a named pipe doesn't give you sessions.  You
+can't tell one process's data from another's.  With socket programming,
+you get a separate session for each client; that's why \fBaccept()\fR takes two
+arguments.
+.PP
+For example, let's say that you have a long-running database server daemon
+that you want folks to be able to access from the Web, but only
+if they go through a CGI interface.  You'd have a small, simple CGI
+program that does whatever checks and logging you feel like, and then acts
+as a Unix-domain client and connects to your private server.
+.SH "TCP Clients with IO::Socket"
+.IX Header "TCP Clients with IO::Socket"
+For those preferring a higher-level interface to socket programming, the
+IO::Socket module provides an object-oriented approach.  If for some reason
+you lack this module, you can just fetch IO::Socket from CPAN, where you'll also
+find modules providing easy interfaces to the following systems: DNS, FTP,
+Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay,
+Telnet, and Time\-\-to name just a few.
+.SS "A Simple Client"
+.IX Subsection "A Simple Client"
+Here's a client that creates a TCP connection to the "daytime"
+service at port 13 of the host name "localhost" and prints out everything
+that the server there cares to provide.
+.PP
+.Vb 10
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use IO::Socket;
+\&    my $remote = IO::Socket::INET\->new(
+\&                        Proto    => "tcp",
+\&                        PeerAddr => "localhost",
+\&                        PeerPort => "daytime(13)",
+\&                    )
+\&                 || die "can\*(Aqt connect to daytime service on localhost";
+\&    while (<$remote>) { print }
+.Ve
+.PP
+When you run this program, you should get something back that
+looks like this:
+.PP
+.Vb 1
+\&    Wed May 14 08:40:46 MDT 1997
+.Ve
+.PP
+Here are what those parameters to the \fBnew()\fR constructor mean:
+.ie n .IP """Proto""" 4
+.el .IP \f(CWProto\fR 4
+.IX Item "Proto"
+This is which protocol to use.  In this case, the socket handle returned
+will be connected to a TCP socket, because we want a stream-oriented
+connection, that is, one that acts pretty much like a plain old file.
+Not all sockets are this of this type.  For example, the UDP protocol
+can be used to make a datagram socket, used for message-passing.
+.ie n .IP """PeerAddr""" 4
+.el .IP \f(CWPeerAddr\fR 4
+.IX Item "PeerAddr"
+This is the name or Internet address of the remote host the server is
+running on.  We could have specified a longer name like \f(CW"www.perl.com"\fR,
+or an address like \f(CW"207.171.7.72"\fR.  For demonstration purposes, we've
+used the special hostname \f(CW"localhost"\fR, which should always mean the
+current machine you're running on.  The corresponding Internet address
+for localhost is \f(CW"127.0.0.1"\fR, if you'd rather use that.
+.ie n .IP """PeerPort""" 4
+.el .IP \f(CWPeerPort\fR 4
+.IX Item "PeerPort"
+This is the service name or port number we'd like to connect to.
+We could have gotten away with using just \f(CW"daytime"\fR on systems with a
+well-configured system services file,[FOOTNOTE: The system services file
+is found in \fI/etc/services\fR under Unixy systems.] but here we've specified the
+port number (13) in parentheses.  Using just the number would have also
+worked, but numeric literals make careful programmers nervous.
+.SS "A Webget Client"
+.IX Subsection "A Webget Client"
+Here's a simple client that takes a remote host to fetch a document
+from, and then a list of files to get from that host.  This is a
+more interesting client than the previous one because it first sends
+something to the server before fetching the server's response.
+.PP
+.Vb 10
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use IO::Socket;
+\&    unless (@ARGV > 1) { die "usage: $0 host url ..." }
+\&    my $host = shift(@ARGV);
+\&    my $EOL = "\e015\e012";
+\&    my $BLANK = $EOL x 2;
+\&    for my $document (@ARGV) {
+\&        my $remote = IO::Socket::INET\->new( Proto     => "tcp",
+\&                                            PeerAddr  => $host,
+\&                                            PeerPort  => "http(80)",
+\&                  )     || die "cannot connect to httpd on $host";
+\&        $remote\->autoflush(1);
+\&        print $remote "GET $document HTTP/1.0" . $BLANK;
+\&        while ( <$remote> ) { print }
+\&        close $remote;
+\&    }
+.Ve
+.PP
+The web server handling the HTTP service is assumed to be at
+its standard port, number 80.  If the server you're trying to
+connect to is at a different port, like 1080 or 8080, you should specify it
+as the named-parameter pair, \f(CW\*(C`PeerPort => 8080\*(C'\fR.  The \f(CW\*(C`autoflush\*(C'\fR
+method is used on the socket because otherwise the system would buffer
+up the output we sent it.  (If you're on a prehistoric Mac, you'll also
+need to change every \f(CW"\en"\fR in your code that sends data over the network
+to be a \f(CW"\e015\e012"\fR instead.)
+.PP
+Connecting to the server is only the first part of the process: once you
+have the connection, you have to use the server's language.  Each server
+on the network has its own little command language that it expects as
+input.  The string that we send to the server starting with "GET" is in
+HTTP syntax.  In this case, we simply request each specified document.
+Yes, we really are making a new connection for each document, even though
+it's the same host.  That's the way you always used to have to speak HTTP.
+Recent versions of web browsers may request that the remote server leave
+the connection open a little while, but the server doesn't have to honor
+such a request.
+.PP
+Here's an example of running that program, which we'll call \fIwebget\fR:
+.PP
+.Vb 6
+\&    % webget www.perl.com /guanaco.html
+\&    HTTP/1.1 404 File Not Found
+\&    Date: Thu, 08 May 1997 18:02:32 GMT
+\&    Server: Apache/1.2b6
+\&    Connection: close
+\&    Content\-type: text/html
+\&
+\&    <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
+\&    <BODY><H1>File Not Found</H1>
+\&    The requested URL /guanaco.html was not found on this server.<P>
+\&    </BODY>
+.Ve
+.PP
+Ok, so that's not very interesting, because it didn't find that
+particular document.  But a long response wouldn't have fit on this page.
+.PP
+For a more featureful version of this program, you should look to
+the \fIlwp-request\fR program included with the LWP modules from CPAN.
+.SS "Interactive Client with IO::Socket"
+.IX Subsection "Interactive Client with IO::Socket"
+Well, that's all fine if you want to send one command and get one answer,
+but what about setting up something fully interactive, somewhat like
+the way \fItelnet\fR works?  That way you can type a line, get the answer,
+type a line, get the answer, etc.
+.PP
+This client is more complicated than the two we've done so far, but if
+you're on a system that supports the powerful \f(CW\*(C`fork\*(C'\fR call, the solution
+isn't that rough.  Once you've made the connection to whatever service
+you'd like to chat with, call \f(CW\*(C`fork\*(C'\fR to clone your process.  Each of
+these two identical process has a very simple job to do: the parent
+copies everything from the socket to standard output, while the child
+simultaneously copies everything from standard input to the socket.
+To accomplish the same thing using just one process would be \fImuch\fR
+harder, because it's easier to code two processes to do one thing than it
+is to code one process to do two things.  (This keep-it-simple principle
+a cornerstones of the Unix philosophy, and good software engineering as
+well, which is probably why it's spread to other systems.)
+.PP
+Here's the code:
+.PP
+.Vb 3
+\&    #!/usr/bin/perl
+\&    use v5.36;
+\&    use IO::Socket;
+\&
+\&    unless (@ARGV == 2) { die "usage: $0 host port" }
+\&    my ($host, $port) = @ARGV;
+\&
+\&    # create a tcp connection to the specified host and port
+\&    my $handle = IO::Socket::INET\->new(Proto     => "tcp",
+\&                                       PeerAddr  => $host,
+\&                                       PeerPort  => $port)
+\&               || die "can\*(Aqt connect to port $port on $host: $!";
+\&
+\&    $handle\->autoflush(1);       # so output gets there right away
+\&    print STDERR "[Connected to $host:$port]\en";
+\&
+\&    # split the program into two processes, identical twins
+\&    die "can\*(Aqt fork: $!" unless defined(my $kidpid = fork());
+\&
+\&    # the if{} block runs only in the parent process
+\&    if ($kidpid) {
+\&        # copy the socket to standard output
+\&        while (defined (my $line = <$handle>)) {
+\&            print STDOUT $line;
+\&        }
+\&        kill("TERM", $kidpid);   # send SIGTERM to child
+\&    }
+\&    # the else{} block runs only in the child process
+\&    else {
+\&        # copy standard input to the socket
+\&        while (defined (my $line = <STDIN>)) {
+\&            print $handle $line;
+\&        }
+\&        exit(0);                # just in case
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`kill\*(C'\fR function in the parent's \f(CW\*(C`if\*(C'\fR block is there to send a
+signal to our child process, currently running in the \f(CW\*(C`else\*(C'\fR block,
+as soon as the remote server has closed its end of the connection.
+.PP
+If the remote server sends data a byte at time, and you need that
+data immediately without waiting for a newline (which might not happen),
+you may wish to replace the \f(CW\*(C`while\*(C'\fR loop in the parent with the
+following:
+.PP
+.Vb 4
+\&    my $byte;
+\&    while (sysread($handle, $byte, 1) == 1) {
+\&        print STDOUT $byte;
+\&    }
+.Ve
+.PP
+Making a system call for each byte you want to read is not very efficient
+(to put it mildly) but is the simplest to explain and works reasonably
+well.
+.SH "TCP Servers with IO::Socket"
+.IX Header "TCP Servers with IO::Socket"
+As always, setting up a server is little bit more involved than running a client.
+The model is that the server creates a special kind of socket that
+does nothing but listen on a particular port for incoming connections.
+It does this by calling the \f(CW\*(C`IO::Socket::INET\->new()\*(C'\fR method with
+slightly different arguments than the client did.
+.IP Proto 4
+.IX Item "Proto"
+This is which protocol to use.  Like our clients, we'll
+still specify \f(CW"tcp"\fR here.
+.IP LocalPort 4
+.IX Item "LocalPort"
+We specify a local
+port in the \f(CW\*(C`LocalPort\*(C'\fR argument, which we didn't do for the client.
+This is service name or port number for which you want to be the
+server. (Under Unix, ports under 1024 are restricted to the
+superuser.)  In our sample, we'll use port 9000, but you can use
+any port that's not currently in use on your system.  If you try
+to use one already in used, you'll get an "Address already in use"
+message.  Under Unix, the \f(CW\*(C`netstat \-a\*(C'\fR command will show
+which services current have servers.
+.IP Listen 4
+.IX Item "Listen"
+The \f(CW\*(C`Listen\*(C'\fR parameter is set to the maximum number of
+pending connections we can accept until we turn away incoming clients.
+Think of it as a call-waiting queue for your telephone.
+The low-level Socket module has a special symbol for the system maximum, which
+is SOMAXCONN.
+.IP Reuse 4
+.IX Item "Reuse"
+The \f(CW\*(C`Reuse\*(C'\fR parameter is needed so that we restart our server
+manually without waiting a few minutes to allow system buffers to
+clear out.
+.PP
+Once the generic server socket has been created using the parameters
+listed above, the server then waits for a new client to connect
+to it.  The server blocks in the \f(CW\*(C`accept\*(C'\fR method, which eventually accepts a
+bidirectional connection from the remote client.  (Make sure to autoflush
+this handle to circumvent buffering.)
+.PP
+To add to user-friendliness, our server prompts the user for commands.
+Most servers don't do this.  Because of the prompt without a newline,
+you'll have to use the \f(CW\*(C`sysread\*(C'\fR variant of the interactive client above.
+.PP
+This server accepts one of five different commands, sending output back to
+the client.  Unlike most network servers, this one handles only one
+incoming client at a time.  Multitasking servers are covered in
+Chapter 16 of the Camel.
+.PP
+Here's the code.
+.PP
+.Vb 4
+\& #!/usr/bin/perl
+\& use v5.36;
+\& use IO::Socket;
+\& use Net::hostent;      # for OOish version of gethostbyaddr
+\&
+\& my $PORT = 9000;       # pick something not in use
+\&
+\& my $server = IO::Socket::INET\->new( Proto     => "tcp",
+\&                                     LocalPort => $PORT,
+\&                                     Listen    => SOMAXCONN,
+\&                                     Reuse     => 1);
+\&
+\& die "can\*(Aqt setup server" unless $server;
+\& print "[Server $0 accepting clients]\en";
+\&
+\& while (my $client = $server\->accept()) {
+\&   $client\->autoflush(1);
+\&   print $client "Welcome to $0; type help for command list.\en";
+\&   my $hostinfo = gethostbyaddr($client\->peeraddr);
+\&   printf "[Connect from %s]\en",
+\&          $hostinfo ? $hostinfo\->name : $client\->peerhost;
+\&   print $client "Command? ";
+\&   while ( <$client>) {
+\&     next unless /\eS/;     # blank line
+\&     if    (/quit|exit/i)  { last                                      }
+\&     elsif (/date|time/i)  { printf $client "%s\en", scalar localtime() }
+\&     elsif (/who/i )       { print  $client \`who 2>&1\`                 }
+\&     elsif (/cookie/i )    { print  $client \`/usr/games/fortune 2>&1\`  }
+\&     elsif (/motd/i )      { print  $client \`cat /etc/motd 2>&1\`       }
+\&     else {
+\&       print $client "Commands: quit date who cookie motd\en";
+\&     }
+\&   } continue {
+\&      print $client "Command? ";
+\&   }
+\&   close $client;
+\& }
+.Ve
+.SH "UDP: Message Passing"
+.IX Header "UDP: Message Passing"
+Another kind of client-server setup is one that uses not connections, but
+messages.  UDP communications involve much lower overhead but also provide
+less reliability, as there are no promises that messages will arrive at
+all, let alone in order and unmangled.  Still, UDP offers some advantages
+over TCP, including being able to "broadcast" or "multicast" to a whole
+bunch of destination hosts at once (usually on your local subnet).  If you
+find yourself overly concerned about reliability and start building checks
+into your message system, then you probably should use just TCP to start
+with.
+.PP
+UDP datagrams are \fInot\fR a bytestream and should not be treated as such.
+This makes using I/O mechanisms with internal buffering like stdio (i.e.
+\&\fBprint()\fR and friends) especially cumbersome. Use \fBsyswrite()\fR, or better
+\&\fBsend()\fR, like in the example below.
+.PP
+Here's a UDP program similar to the sample Internet TCP client given
+earlier.  However, instead of checking one host at a time, the UDP version
+will check many of them asynchronously by simulating a multicast and then
+using \fBselect()\fR to do a timed-out wait for I/O.  To do something similar
+with TCP, you'd have to use a different socket handle for each host.
+.PP
+.Vb 4
+\& #!/usr/bin/perl
+\& use v5.36;
+\& use Socket;
+\& use Sys::Hostname;
+\&
+\& my $SECS_OF_70_YEARS = 2_208_988_800;
+\&
+\& my $iaddr = gethostbyname(hostname());
+\& my $proto = getprotobyname("udp");
+\& my $port = getservbyname("time", "udp");
+\& my $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
+\&
+\& socket(my $socket, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!";
+\& bind($socket, $paddr)                           || die "bind: $!";
+\&
+\& $| = 1;
+\& printf "%\-12s %8s %s\en",  "localhost", 0, scalar localtime();
+\& my $count = 0;
+\& for my $host (@ARGV) {
+\&     $count++;
+\&     my $hisiaddr = inet_aton($host)         || die "unknown host";
+\&     my $hispaddr = sockaddr_in($port, $hisiaddr);
+\&     defined(send($socket, 0, 0, $hispaddr)) || die "send $host: $!";
+\& }
+\&
+\& my $rout = my $rin = "";
+\& vec($rin, fileno($socket), 1) = 1;
+\&
+\& # timeout after 10.0 seconds
+\& while ($count && select($rout = $rin, undef, undef, 10.0)) {
+\&     my $rtime = "";
+\&     my $hispaddr = recv($socket, $rtime, 4, 0) || die "recv: $!";
+\&     my ($port, $hisiaddr) = sockaddr_in($hispaddr);
+\&     my $host = gethostbyaddr($hisiaddr, AF_INET);
+\&     my $histime = unpack("N", $rtime) \- $SECS_OF_70_YEARS;
+\&     printf "%\-12s ", $host;
+\&     printf "%8d %s\en", $histime \- time(), scalar localtime($histime);
+\&     $count\-\-;
+\& }
+.Ve
+.PP
+This example does not include any retries and may consequently fail to
+contact a reachable host. The most prominent reason for this is congestion
+of the queues on the sending host if the number of hosts to contact is
+sufficiently large.
+.SH "SysV IPC"
+.IX Header "SysV IPC"
+While System V IPC isn't so widely used as sockets, it still has some
+interesting uses.  However, you cannot use SysV IPC or Berkeley \fBmmap()\fR to
+have a variable shared amongst several processes.  That's because Perl
+would reallocate your string when you weren't wanting it to.  You might
+look into the \f(CW\*(C`IPC::Shareable\*(C'\fR or \f(CW\*(C`threads::shared\*(C'\fR modules for that.
+.PP
+Here's a small example showing shared memory usage.
+.PP
+.Vb 1
+\&    use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR S_IWUSR);
+\&
+\&    my $size = 2000;
+\&    my $id = shmget(IPC_PRIVATE, $size, S_IRUSR | S_IWUSR);
+\&    defined($id)                    || die "shmget: $!";
+\&    print "shm key $id\en";
+\&
+\&    my $message = "Message #1";
+\&    shmwrite($id, $message, 0, 60)  || die "shmwrite: $!";
+\&    print "wrote: \*(Aq$message\*(Aq\en";
+\&    shmread($id, my $buff, 0, 60)      || die "shmread: $!";
+\&    print "read : \*(Aq$buff\*(Aq\en";
+\&
+\&    # the buffer of shmread is zero\-character end\-padded.
+\&    substr($buff, index($buff, "\e0")) = "";
+\&    print "un" unless $buff eq $message;
+\&    print "swell\en";
+\&
+\&    print "deleting shm $id\en";
+\&    shmctl($id, IPC_RMID, 0)        || die "shmctl: $!";
+.Ve
+.PP
+Here's an example of a semaphore:
+.PP
+.Vb 1
+\&    use IPC::SysV qw(IPC_CREAT);
+\&
+\&    my $IPC_KEY = 1234;
+\&    my $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT);
+\&    defined($id)                    || die "semget: $!";
+\&    print "sem id $id\en";
+.Ve
+.PP
+Put this code in a separate file to be run in more than one process.
+Call the file \fItake\fR:
+.PP
+.Vb 1
+\&    # create a semaphore
+\&
+\&    my $IPC_KEY = 1234;
+\&    my $id = semget($IPC_KEY, 0, 0);
+\&    defined($id)                    || die "semget: $!";
+\&
+\&    my $semnum  = 0;
+\&    my $semflag = 0;
+\&
+\&    # "take" semaphore
+\&    # wait for semaphore to be zero
+\&    my $semop = 0;
+\&    my $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
+\&
+\&    # Increment the semaphore count
+\&    $semop = 1;
+\&    my $opstring2 = pack("s!s!s!", $semnum, $semop,  $semflag);
+\&    my $opstring  = $opstring1 . $opstring2;
+\&
+\&    semop($id, $opstring)   || die "semop: $!";
+.Ve
+.PP
+Put this code in a separate file to be run in more than one process.
+Call this file \fIgive\fR:
+.PP
+.Vb 3
+\&    # "give" the semaphore
+\&    # run this in the original process and you will see
+\&    # that the second process continues
+\&
+\&    my $IPC_KEY = 1234;
+\&    my $id = semget($IPC_KEY, 0, 0);
+\&    die unless defined($id);
+\&
+\&    my $semnum  = 0;
+\&    my $semflag = 0;
+\&
+\&    # Decrement the semaphore count
+\&    my $semop = \-1;
+\&    my $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
+\&
+\&    semop($id, $opstring)   || die "semop: $!";
+.Ve
+.PP
+The SysV IPC code above was written long ago, and it's definitely
+clunky looking.  For a more modern look, see the IPC::SysV module.
+.PP
+A small example demonstrating SysV message queues:
+.PP
+.Vb 1
+\&    use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRUSR S_IWUSR);
+\&
+\&    my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR);
+\&    defined($id)                || die "msgget failed: $!";
+\&
+\&    my $sent      = "message";
+\&    my $type_sent = 1234;
+\&
+\&    msgsnd($id, pack("l! a*", $type_sent, $sent), 0)
+\&                                || die "msgsnd failed: $!";
+\&
+\&    msgrcv($id, my $rcvd_buf, 60, 0, 0)
+\&                                || die "msgrcv failed: $!";
+\&
+\&    my($type_rcvd, $rcvd) = unpack("l! a*", $rcvd_buf);
+\&
+\&    if ($rcvd eq $sent) {
+\&        print "okay\en";
+\&    } else {
+\&        print "not okay\en";
+\&    }
+\&
+\&    msgctl($id, IPC_RMID, 0)    || die "msgctl failed: $!\en";
+.Ve
+.SH NOTES
+.IX Header "NOTES"
+Most of these routines quietly but politely return \f(CW\*(C`undef\*(C'\fR when they
+fail instead of causing your program to die right then and there due to
+an uncaught exception.  (Actually, some of the new \fISocket\fR conversion
+functions do \fBcroak()\fR on bad arguments.)  It is therefore essential to
+check return values from these functions.  Always begin your socket
+programs this way for optimal success, and don't forget to add the \fB\-T\fR
+taint-checking flag to the \f(CW\*(C`#!\*(C'\fR line for servers:
+.PP
+.Vb 4
+\&    #!/usr/bin/perl \-T
+\&    use v5.36;
+\&    use sigtrap;
+\&    use Socket;
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+These routines all create system-specific portability problems.  As noted
+elsewhere, Perl is at the mercy of your C libraries for much of its system
+behavior.  It's probably safest to assume broken SysV semantics for
+signals and to stick with simple TCP and UDP socket operations; e.g., don't
+try to pass open file descriptors over a local UDP datagram socket if you
+want your code to stand a chance of being portable.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen, with occasional vestiges of Larry Wall's original
+version and suggestions from the Perl Porters.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+There's a lot more to networking than this, but this should get you
+started.
+.PP
+For intrepid programmers, the indispensable textbook is \fIUnix Network
+Programming, 2nd Edition, Volume 1\fR by W. Richard Stevens (published by
+Prentice-Hall).  Most books on networking address the subject from the
+perspective of a C programmer; translation to Perl is left as an exercise
+for the reader.
+.PP
+The \fBIO::Socket\fR\|(3) manpage describes the object library, and the \fBSocket\fR\|(3)
+manpage describes the low-level interface to sockets.  Besides the obvious
+functions in perlfunc, you should also check out the \fImodules\fR file at
+your nearest CPAN site, especially
+<http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_>.
+See perlmodlib or best yet, the \fIPerl FAQ\fR for a description
+of what CPAN is and where to get it if the previous link doesn't work
+for you.
+.PP
+Section 5 of CPAN's \fImodules\fR file is devoted to "Networking, Device
+Control (modems), and Interprocess Communication", and contains numerous
+unbundled modules numerous networking modules, Chat and Expect operations,
+CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
+Threads, and ToolTalk\-\-to name just a few.
diff --git a/upstream/mageia-cauldron/man1/perlirix.1 b/upstream/mageia-cauldron/man1/perlirix.1
new file mode 100644
index 00000000..e2514109
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlirix.1
@@ -0,0 +1,206 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLIRIX 1"
+.TH PERLIRIX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlirix \- Perl version 5 on Irix systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of Irix that will affect how Perl
+version 5 (hereafter just Perl) is compiled and/or runs.
+.SS "Building 32\-bit Perl in Irix"
+.IX Subsection "Building 32-bit Perl in Irix"
+Use
+.PP
+.Vb 1
+\&        sh Configure \-Dcc=\*(Aqcc \-n32\*(Aq
+.Ve
+.PP
+to compile Perl 32\-bit.  Don't bother with \-n32 unless you have 7.1
+or later compilers (use cc \-version to check).
+.PP
+(Building 'cc \-n32' is the default.)
+.SS "Building 64\-bit Perl in Irix"
+.IX Subsection "Building 64-bit Perl in Irix"
+Use
+.PP
+.Vb 1
+\&        sh Configure \-Dcc=\*(Aqcc \-64\*(Aq \-Duse64bitint
+.Ve
+.PP
+This requires require a 64\-bit MIPS CPU (R8000, R10000, ...)
+.PP
+You can also use
+.PP
+.Vb 1
+\&        sh Configure \-Dcc=\*(Aqcc \-64\*(Aq \-Duse64bitall
+.Ve
+.PP
+but that makes no difference compared with the \-Duse64bitint because
+of the \f(CW\*(C`cc \-64\*(C'\fR.
+.PP
+You can also do
+.PP
+.Vb 1
+\&        sh Configure \-Dcc=\*(Aqcc \-n32\*(Aq \-Duse64bitint
+.Ve
+.PP
+to use long longs for the 64\-bit integer type, in case you don't
+have a 64\-bit CPU.
+.PP
+If you are using gcc, just
+.PP
+.Vb 1
+\&        sh Configure \-Dcc=gcc \-Duse64bitint
+.Ve
+.PP
+should be enough, the Configure should automatically probe for the
+correct 64\-bit settings.
+.SS "About Compiler Versions of Irix"
+.IX Subsection "About Compiler Versions of Irix"
+Some Irix cc versions, e.g. 7.3.1.1m (try cc \-version) have been known
+to have issues (coredumps) when compiling perl.c.  If you've used
+\&\-OPT:fast_io=ON and this happens, try removing it.  If that fails, or
+you didn't use that, then try adjusting other optimization options
+(\-LNO, \-INLINE, \-O3 to \-O2, et cetera).  The compiler bug has been
+reported to SGI.  (Allen Smith <easmith@beatrice.rutgers.edu>)
+.SS "Linker Problems in Irix"
+.IX Subsection "Linker Problems in Irix"
+If you get complaints about so_locations then search in the file
+hints/irix_6.sh for "lddflags" and do the suggested adjustments.
+(David Billinghurst <David.Billinghurst@riotinto.com.au>)
+.SS "Malloc in Irix"
+.IX Subsection "Malloc in Irix"
+Do not try to use Perl's malloc, this will lead into very mysterious
+errors (especially with \-Duse64bitall).
+.SS "Building with threads in Irix"
+.IX Subsection "Building with threads in Irix"
+Run Configure with \-Duseithreads which will configure Perl with
+the Perl 5.8.0 "interpreter threads", see threads.
+.PP
+For Irix 6.2 with perl threads, you have to have the following
+patches installed:
+.PP
+.Vb 5
+\&        1404 Irix 6.2 Posix 1003.1b man pages
+\&        1645 Irix 6.2 & 6.3 POSIX header file updates
+\&        2000 Irix 6.2 Posix 1003.1b support modules
+\&        2254 Pthread library fixes
+\&        2401 6.2 all platform kernel rollup
+.Ve
+.PP
+\&\fBIMPORTANT\fR: Without patch 2401, a kernel bug in Irix 6.2 will cause
+your machine to panic and crash when running threaded perl.  Irix 6.3
+and later are okay.
+.PP
+.Vb 2
+\&    Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
+\&    pthreads patches information.
+.Ve
+.SS "Irix 5.3"
+.IX Subsection "Irix 5.3"
+While running Configure and when building, you are likely to get
+quite a few of these warnings:
+.PP
+.Vb 3
+\&  ld:
+\&  The shared object /usr/lib/libm.so did not resolve any symbols.
+\&        You may want to remove it from your link line.
+.Ve
+.PP
+Ignore them: in IRIX 5.3 there is no way to quieten ld about this.
+.PP
+During compilation you will see this warning from toke.c:
+.PP
+.Vb 3
+\&  uopt: Warning: Perl_yylex: this procedure not optimized because it
+\&        exceeds size threshold; to optimize this procedure, use \-Olimit
+\&        option with value >= 4252.
+.Ve
+.PP
+Ignore the warning.
+.PP
+In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3)
+the following failures are known.
+.PP
+.Vb 8
+\& Failed Test                  Stat Wstat Total Fail  Failed|Failing List
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& ../ext/List/Util/t/shuffle.t    0   139    ??   ??       %  ??
+\& ../lib/Math/Trig.t            255 65280    29   12  41.38%  24\-29
+\& ../lib/sort.t                   0   138   119   72  60.50%  48\-119
+\& 56 tests and 474 subtests skipped.
+\& Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed,
+\&    99.90% okay.
+.Ve
+.PP
+They are suspected to be compiler errors (at least the shuffle.t
+failure is known from some IRIX 6 setups) and math library errors
+(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
+further fixes for the IRIX are unlikely.  If you can get gcc for 5.3,
+you could try that, too, since gcc in IRIX 6 is a known workaround for
+at least the shuffle.t and sort.t failures.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Jarkko Hietaniemi <jhi@iki.fi>
+.PP
+Please report any errors, updates, or suggestions to
+<https://github.com/Perl/perl5/issues>.
diff --git a/upstream/mageia-cauldron/man1/perljp.1 b/upstream/mageia-cauldron/man1/perljp.1
new file mode 100644
index 00000000..ac498f2d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perljp.1
@@ -0,0 +1,234 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLJP 1"
+.TH PERLJP 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perljp \- 日本語 Perl ガイド
+.SH 説明
+.IX Header "説明"
+Perl �世界�よ���!
+.PP
+Perl 5.8.0 より�Unicodeサ�ート�大幅�強化�れ����果ラテン文字以外�文字コード�サ�ート� CJK (中国語�日本語��ングル)を���加�り���。Unicode�世界中�文字を一��文字コード�扱���を目指��標準�格��り���ら西�������間�文字（ギリシャ文字�キリール文字�アラビア文字�ヘブライ文字�ディーヴァナガーリ文字�����）や��れ���OSベンダー�独自�定����文字(PC�よ�Macintosh)������れ����。
+.PP
+Perl 自身� Unicode �動作���。Perl スクリプト内�文字列リテラルや正�表�� Unicode を��������。���入出力�������れ��使�れ��������文字コード�対応�るモジュール�「 Encode ��標準装備�れ��り�Unicode ��れら�文字コード�相互変�も簡��行�るよ��������。
+.PP
+�時点� Encode �サ�ート�る文字コード�以下���り��。
+.PP
+.Vb 10
+\&  7bit\-jis      AdobeStandardEncoding AdobeSymbol       AdobeZdingbat
+\&  ascii             big5              big5\-hkscs        cp1006
+\&  cp1026            cp1047            cp1250            cp1251
+\&  cp1252            cp1253            cp1254            cp1255
+\&  cp1256            cp1257            cp1258            cp37
+\&  cp424             cp437             cp500             cp737
+\&  cp775             cp850             cp852             cp855
+\&  cp856             cp857             cp860             cp861
+\&  cp862             cp863             cp864             cp865
+\&  cp866             cp869             cp874             cp875
+\&  cp932             cp936             cp949             cp950
+\&  dingbats          euc\-cn            euc\-jp            euc\-kr
+\&  gb12345\-raw       gb2312\-raw        gsm0338           hp\-roman8
+\&  hz                iso\-2022\-jp       iso\-2022\-jp\-1     iso\-8859\-1
+\&  iso\-8859\-10       iso\-8859\-11       iso\-8859\-13       iso\-8859\-14
+\&  iso\-8859\-15       iso\-8859\-16       iso\-8859\-2        iso\-8859\-3
+\&  iso\-8859\-4        iso\-8859\-5        iso\-8859\-6        iso\-8859\-7
+\&  iso\-8859\-8        iso\-8859\-9        iso\-ir\-165        jis0201\-raw
+\&  jis0208\-raw       jis0212\-raw       johab             koi8\-f
+\&  koi8\-r            koi8\-u            ksc5601\-raw       MacArabic
+\&  MacCentralEurRoman  MacChineseSimp    MacChineseTrad    MacCroatian
+\&  MacCyrillic       MacDingbats       MacFarsi          MacGreek
+\&  MacHebrew         MacIcelandic      MacJapanese       MacKorean
+\&  MacRoman          MacRomanian       MacRumanian       MacSami
+\&  MacSymbol         MacThai           MacTurkish        MacUkrainian
+\&  nextstep          posix\-bc          shiftjis          symbol
+\&  UCS\-2BE           UCS\-2LE           UTF\-16            UTF\-16BE
+\&  UTF\-16LE          UTF\-32            UTF\-32BE          UTF\-32LE
+\&  utf8              viscii
+.Ve
+.PP
+(全114種類)
+.PP
+例���文字コードFOO�ファイルをUTF\-8�変��る���以下�よ�����。
+.PP
+.Vb 1
+\&    perl \-Mencoding=FOO,STDOUT,utf8 \-pe1 < file.FOO > file.utf8
+.Ve
+.PP
+���Perl���全部�Perl�書�れ�文字コード変�ユーティリティ�piconvも付属���る���以下�よ���る��も����。
+.PP
+.Vb 2
+\&   piconv \-f FOO \-t utf8 < file.FOO > file.utf8
+\&   piconv \-f utf8 \-t FOO < file.utf8 > file.FOO
+.Ve
+.SS "(jcode.pl|Jcode.pm|JPerl) �ら�移行"
+.IX Subsection "(jcode.pl|Jcode.pm|JPerl) �ら�移行"
+5.8以���スクリプト�EUC\-JP��れ�リテラル���扱���������。���入出力を扱�モジュール����Jcode.pm�( <http://openlab.ring.gr.jp/Jcode/> )�perl4用�ユーティリティ����jcode.pl��れ�れ存在��日本語�扱�るCGI�よ�利用�れ��る��を御存��方も少��������れ��。����日本語�よる正�表�を���扱������能���。
+.PP
+5.005以��Perl���日本語�特化��ローカライズ版�Jperl�存在����( <http://homepage2.nifty.com/kipp/perl/jperl/index.html> ※1)。���Mac OS 9.x/Classic用�Perl�MacPerl�日本語版もMacJPerl���存在�����。( <https://habilis.net/macjperl/> ).�れら��文字コード���EUC\-JP�加�Shift_JISも����扱���������日本語�よる正�表�を扱���も�能���。
+.PP
+Perl5.8����れら�機能����Perl本体���実���る上��日本語���ら�上記114�文字コードを������も�時�扱��������。�ら��CPAN���ら新��文字コード用�モジュールを入手�る��も簡����るよ��������。
+.PP
+※1: ホスティングサービス�終了�より�在�閲覧����ん。 Vector( <https://www.vector.co.jp/soft/win95/util/se098198.html> )�らWindow用��イナリを�CPAN( <https://www.cpan.org/src/unsupported/4.036/jperl/> )�らperl4用�パッ�を入手�る�������。
+.IP \(bu 4
+入出力
+.Sp
+以下�例���れもShift_JIS�入力をEUC\-JP�変���出力���。
+.Sp
+.Vb 10
+\&  # jcode.pl
+\&  require "jcode.pl";
+\&  while(<>){
+\&    jcode::convert(*_, \*(Aqeuc\*(Aq, \*(Aqsjis\*(Aq);
+\&    print;
+\&  }
+\&  # Jcode.pm
+\&  use Jcode;
+\&  while(<>){
+\&        print Jcode\->new($_, \*(Aqsjis\*(Aq)\->euc;
+\&  }
+\&  # Perl 5.8
+\&  use Encode;
+\&  while(<>){
+\&    from_to($_, \*(Aqshiftjis\*(Aq, \*(Aqeuc\-jp\*(Aq);
+\&    print;
+\&  }
+\&  # Perl 5.8 \- encoding を利用��
+\&  use encoding \*(Aqeuc\-jp\*(Aq, STDIN => \*(Aqshiftjis\*(Aq;
+\&  while(<>){
+\&        print;
+\&  }
+.Ve
+.IP \(bu 4
+Jperl 互�スクリプト
+.Sp
+��ゆる"shebang"を変更�る����Jperl用�script���ん��変更���利用�能����れ��。
+.Sp
+.Vb 3
+\&   #!/path/to/jperl
+\&   ↓
+\&   #!/path/to/perl \-Mencoding=euc\-jp
+.Ve
+.Sp
+詳��� perldoc encoding を�照������。
+.SS �ら�詳��
+.IX Subsection "�ら�詳��"
+Perl��膨大�資料�付属���り�Perl�新機能やUnicodeサ�ート����Encodeモジュール�使用法���細��網羅�れ����（残念��ら���ん�英語���り���）。以下�コマンド��れら�一部を閲覧�る����能��。
+.PP
+.Vb 3
+\&  perldoc perlunicode # Perl�Unicodeサ�ート全般
+\&  perldoc Encode      # Encodeモジュール�関��
+\&  perldoc Encode::JP  # ��日本語文字コード�関��
+.Ve
+.SS "Perl全般�関�る URL"
+.IX Subsection "Perl全般�関�る URL"
+.IP <https://www.perl.org/> 4
+.IX Item "<https://www.perl.org/>"
+Perl ホームページ
+.IP <https://www.perl.com/> 4
+.IX Item "<https://www.perl.com/>"
+Perl 財団�営業�る文章作�集
+.IP <https://www.cpan.org/> 4
+.IX Item "<https://www.cpan.org/>"
+CPAN (Comprehensive Perl Archive Network)
+.IP <https://metacpan.org/> 4
+.IX Item "<https://metacpan.org/>"
+MetaCPAN CPAN�検索エンジン
+.IP <https://lists.perl.org/> 4
+.IX Item "<https://lists.perl.org/>"
+Perl メーリングリスト集
+.IP <https://perldoc.jp/> 4
+.IX Item "<https://perldoc.jp/>"
+perldoc.jp Perl �公�ドキュメント�モジュールドキュメント�日本語訳
+.SS "Perl�修得�役立� URL"
+.IX Subsection "Perl�修得�役立� URL"
+.IP <http://www.oreilly.com.cn/> 4
+.IX Item "<http://www.oreilly.com.cn/>"
+O'Reilly 社�Perl関連書�(簡体字中国語)
+.IP <https://www.oreilly.co.jp/catalog/> 4
+.IX Item "<https://www.oreilly.co.jp/catalog/>"
+オライリー社�Perl関連書�(日本語)
+.SS "Perl �関�る団体"
+.IX Subsection "Perl �関�る団体"
+.IP <https://www.pm.org/groups/asia.html> 4
+.IX Item "<https://www.pm.org/groups/asia.html>"
+アジア地域� Perl Mongers (Perl�ユーザーグループ) 一覧
+.IP <https://japan.perlassociation.org> 4
+.IX Item "<https://japan.perlassociation.org>"
+一般社団法人Japan Perl Association (JPA) Perl技術��文化�啓蒙・促進����組織
+.SS Unicode関連�URL
+.IX Subsection "Unicode関連�URL"
+.IP <https://www.unicode.org/> 4
+.IX Item "<https://www.unicode.org/>"
+Unicode コンソーシアム (Unicode�格��定団体)
+.IP <https://www.cl.cam.ac.uk/%7Emgk25/unicode.html> 4
+.IX Item "<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>"
+UTF\-8 and Unicode FAQ for Unix/Linux
+.IP <https://wiki.kldp.org/Translations/html/UTF8\-Unicode\-KLDP/UTF8\-Unicode\-KLDP.html> 4
+.IX Item "<https://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>"
+UTF\-8 and Unicode FAQ for Unix/Linux (�ングル訳)
+.SH AUTHORS
+.IX Header "AUTHORS"
+.IP \(bu 4
+Jarkko Hietaniemi <jhi@iki.fi>
+.IP \(bu 4
+Dan Kogai (�飼　弾) <dankogai@dan.co.jp>
+.IP \(bu 4
+Shogo Ichinose (一野瀬　翔�) <shogo82148@gmail.com>
diff --git a/upstream/mageia-cauldron/man1/perlko.1 b/upstream/mageia-cauldron/man1/perlko.1
new file mode 100644
index 00000000..5cfa29a5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlko.1
@@ -0,0 +1,358 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLKO 1"
+.TH PERLKO 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlko \- 한국어 Perl 안내서
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl� 세계� 오신 것� 환�합니다!
+.PP
+Perl� 가� \fB'Practical Extraction and Report Language'\fR�고 하기� 합니다만
+다른 �리 알려진 것들 중�서 \fB'Pathologically Eclectic Rubbish Lister'\fR�고
+하기� 합니다. 사실 �것� �워 맞춘 것�며 Perl� �것들� 첫 글�를
+가져와서 �름� 붙� 것� 아닙니다. Perl� 창시� Larry가 첫 번째 �름�
+먼저 ��했고 �리 알려진 것� 나중� 지었기 때문입니다. 그렇기 때문�
+\&\fB'Perl'\fR� 모� 대문�가 아닙니다. �리 알려진 어떤 것� 가지고 논�하는
+것� �미가 없습니다. Larry는 � 개 다 지지합니다.
+.PP
+가� p가 소문�로 작성� \fB'perl'\fR� 볼 것입니다. P가 대문�로 �어 있는
+\&\fB'Perl'\fR� 언어를 참조할 때 쓰�며 \fB'perl'\fR처럼 p가 소문�� 경우는 여러분�
+프로그램� 컴파�하고 �릴 때 사용�는 해�기를 지칭할 때 사용�니다.
+.SH "Perl� 관하여"
+.IX Header "Perl� 관하여"
+Perl� 본래 문�열 �성� 위해 만들졌지만 지금� 시스템 관리와 웹 개발,
+네트워� 프로그래�, GUI 개발 등� �함한 여러 분야�서 �리 사용�는
+범용 프로그래� 언어입니다.
+.PP
+� 언어는 아름다움(아주 작고, 우아하고, 아주 �고)보다
+실용�(사용하기 쉽고, 효율��며, 가능한 최대한)� 것� 지향하고 있습니다.
+사용하기 쉽고, 절차� 프로그래�과 �체 지향 프로그래�� 모� 지�하고,
+강력한 문�열 처리 기능� 내장하고, 세��서 가장 ���� 제 3�� 모듈
+모�처를 가지고 있다는 것� Perl� 가장 중요한 특징입니다.
+.PP
+Perl� 언어� 특징� \fIpod/perlintro.pod\fR 문서�서 소개합니다.
+.PP
+�번 릴리스�서 가장 중요한 변화는 \fIpod/perldelta.pod\fR�서 논�합니다.
+.PP
+�한 다양한 출�사가 출�한 많� Perl 책� 다양한 주제를 다루고 있습니다.
+�세한 정보는 \fIpod/perlbook.pod\fR 문서를 확�하세요.
+.SH 설치
+.IX Header "설치"
+여러분� 비�� 현대� 운�체제를 사용하고 있고 현재 버전� Perl�
+지역�으로 설치하고 싶다면 다� 명령� 실행하세요.
+.PP
+.Vb 3
+\&    ./Configure \-des \-Dprefix=$HOME/localperl
+\&    make test
+\&    make install
+.Ve
+.PP
+앞� 명령� 여러분� 플랫�� 맞게 환경� 설정하고 컴파�� 수행한 후,
+회기 테스트를 수행한뒤, 홈 디렉터리 하부� \fIlocalperl\fR 디렉터리� perl�
+설치합니다.
+.PP
+여러분� 어떠한 문제든 겪게 �거나 사용� 정� 버전 Perl� 설치할 필요가 있다면
+현재 배��� 들어있는 \fIINSTALL\fR 파� 안� �세한 설명� �어야 합니다.
+추가�으로 �반��지 않� 다양한 플랫��서 Perl� 빌드하고 사용하는
+방법� 대한 �움�과 귀�� �혀있는 많� 수� \fIREADME\fR 파�� 있습니다.
+.PP
+�단 Perl� 설치하고 나면 \f(CW\*(C`perldoc\*(C'\fR �구를 �용해 �부한 문서를 사용할
+수 있습니다. 시작하기 위해서 다� 명령� 실행하세요.
+.PP
+.Vb 1
+\&    perldoc perl
+.Ve
+.SH "실행� 어려움� 겪는다면"
+.IX Header "실행� 어려움� 겪는다면"
+Perl� 뜨개질�서 부터 로켓 과학까지 모든 분야�서 사용할 수 있는 �고
+복잡한 시스템입니다. 여러분� 어려움� 부딪혔�때 그 문제는 �미 다른
+사람� 해결했� 가능성� 높습니다. 문서를 모� 확�했는�� 버그가
+확실하다면 \f(CW\*(C`perlbug\*(C'\fR �구를 �용해서 저��게 버그를 보고해주세요.
+\&\f(CW\*(C`perlbug\*(C'\fR� 대한 � �세한 정보는 \f(CW\*(C`perldoc perlbug\*(C'\fR �는 \f(CW\*(C`perlbug\*(C'\fR를
+명령줄�서 실행해서 확�할 수 있습니다.
+.PP
+Perl� 사용 가능하게 만들었다 하��� Perl� 계�해서 진화하기 때문�
+여러분� 맞닥뜨린 버그를 수정했거나 여러분� 유용하다고 ��할법한
+새로운 기능� 추가� 좀 � 최신 버전� 있� 수 있습니다.
+.PP
+여러분� 항� 최신 버전� perl� CPAN (Comprehensive Perl Archive Network)
+사�트 <http://www.cpan.org/src/> �서 찾� 수 있습니다.
+.PP
+perl 소스� 간단한 패치를 등�하고 싶다면 \fIpod/perlhack.pod\fR 문서�
+\&\fB"SUPER QUICK PATCH GUIDE"\fR를 살펴보세요.
+.PP
+그냥 개��으로 참고하세요.
+제가 �것처럼 멋진 물건� 만든다는 것� 여러분� 알기를 바�니다.
+그것� 제 �야기� \fB"저�(Author)"\fR를 기�게하기 때문입니다.
+�것� 여러분� 귀찮게 한다면 여러분� \fB"저작(Authorship)"\fR�
+대한 ��� 정정해야 할 수� 있습니다. 하지만 어쨌거나 여러분�
+Perl� 사용하는�는 문제가 없답니다. :\-)
+.PP
+\&\- \fB"저�"\fR로부터.
+.SH �코딩
+.IX Header "�코딩"
+Perl� 5.8.0�부터 유니코드/ISO 10646� 대해 광범위하게 지�합니다.
+유니코드 지�� �환으로 한중�� 비롯한 세계 �국�서
+유니코드 �전� 쓰고 있었고 지금� �리 쓰�고 있는 수많� �코딩�
+지�합니다. 유니코드는 전 세계�서 쓰�는 모든 언어를 위한
+표기 체계(유럽� �틴 알파벳, 키릴 알파벳, 그리스 알파벳, ��와 �남 아시아�
+브�미 계열 스�립트, 아� 문�, 히브리 문�, 한중�� 한�, 한국어� 한글,
+�본어� 가나, �미 �디안� 표기 체계 등)를 수용하는 것� 목표로 하고
+있기 때문� 기존� 쓰��  � 언어 � 국가 그리고 운� 체계� 고유한
+문� 집합과 �코딩� 쓸 수 있는 모든 글�는 물론�고  기존 문� 집합�서
+지�하고 있지 않� 아주 많� 글�를  �함하고 있습니다.
+.PP
+Perl� 내부�으로 유니코드를 문� 표현� 위해 사용합니다.
+보다 구체�으로 �하면 Perl 스�립트 안�서  UTF\-8 문�열� 쓸 수 있고,
+�종 함수와 연산�(예를 들어, 정규�, index, substr)가 바�트 단위
+대신 유니코드 글� 단위로 �작합니다.
+� �세한 것� \fIpod/perlunicode.pod\fR 문서를 참고하세요.
+유니코드가 �리 보급�기 전� �리 쓰�고 있었고, 여전히 �리 쓰�고 있는
+�국/� 언어별 �코딩으로 입출력� 하고 �들 �코딩으로 � ��터와 문서를
+다루는 것� �기 위해 Encode 모듈� 쓰�고 있습니다.
+무엇보다 Encode 모듈� 사용하면 수많� �코딩 사�� 변환� 쉽게 할 수 있습니다.
+.SS "Encode 모듈"
+.IX Subsection "Encode 모듈"
+\fI지� �코딩\fR
+.IX Subsection "지� �코딩"
+.PP
+Encode 모듈� 다�과 같� 한국어 �코딩� 지�합니다.
+.IP \(bu 4
+\&\f(CW\*(C`euc\-kr\*(C'\fR
+.Sp
+US\-ASCII와 KS X 1001� 같� 쓰는 멀티바�트 �코딩으로 �히
+완성형��고 불림. KS X 2901과 RFC 1557 참고.
+.IP \(bu 4
+\&\f(CW\*(C`cp949\*(C'\fR
+.Sp
+MS-Windows 9x/ME�서 쓰�는 확장 완성형. euc\-kr� 8,822��
+한글 �절� �한 것임. alias는 uhc, windows\-949, x\-windows\-949,
+ks_c_5601\-1987. 맨 마지막 �름� �절하지 않� �름�지만, Microsoft
+제품�서 CP949� �미로 쓰�고 있�.
+.IP \(bu 4
+\&\f(CW\*(C`johab\*(C'\fR
+.Sp
+KS X 1001:1998 부� 3�서 규정한 조합형. 문� 레�토리는 cp949와 마찬가지로
+US\-ASCII와  KS X 1001� 8,822�� 한글 �절� �한 것으로 �코딩 방�� 전혀 다름.
+.IP \(bu 4
+\&\f(CW\*(C`iso\-2022\-kr\*(C'\fR
+.Sp
+RFC 1557�서 규정한 한국어 �터넷 메� �환용 �코딩으로 US\-ASCII와
+KS X 1001� 레�토리로 하는 ��서 euc\-kr과 같지만 �코딩 방�� 다름.
+1997\-8년 경까지 쓰였으나 � �� 메� �환� 쓰�지 않�.
+.IP \(bu 4
+\&\f(CW\*(C`ksc5601\-raw\*(C'\fR
+.Sp
+KS X 1001(KS C 5601)� GL(즉, MSB를 0으로 한 경우)� 놓았� 때� �코딩.
+US\-ASCII와 결합하지 않고 단�으로 쓰�는 �� X11 등�서 글꼴
+�코딩(ksc5601.1987\-0. '0'� GL� �미함)으로 쓰�는 것� 제외하고는
+거� 없�. KS C 5601� 1997년 KS X 1001로 �름� 바꾸었�. 1998년�는 �
+글�(유로화 부호와 등� �표 부호)가 �해졌�.
+.PP
+\fI변환 예제\fR
+.IX Subsection "변환 예제"
+.PP
+예를 들어, euc-kr �코딩으로 � 파�� UTF\-8로 변환하려면
+명령줄�서 다�처럼 실행합니다.
+.PP
+.Vb 1
+\&    perl \-Mencoding=euc\-kr,STDOUT,utf8 \-pe1 < file.euc\-kr > file.utf8
+.Ve
+.PP
+반대로 변환할 경우 다�처럼 실행합니다.
+.PP
+.Vb 1
+\&    perl \-Mencoding=utf8,STDOUT,euc\-kr \-pe1 < file.utf8 > file.euc\-kr
+.Ve
+.PP
+�런 변환� 좀� 편리하게 할 수 있�� �와주는 \fIpiconv\fR가 Perl�
+기본으로 들어있습니다. � 유틸리티는 Encode 모듈� �용한 순수 Perl
+유틸리티로 �름�서 알 수 있듯� Unix� \f(CW\*(C`iconv\*(C'\fR를 모�로 한 것입니다.
+사용법� 다�과 같습니다.
+.PP
+.Vb 2
+\&   piconv \-f euc\-kr \-t utf8 < file.euc\-kr > file.utf8
+\&   piconv \-f utf8 \-t euc\-kr < file.utf8 > file.euc\-kr
+.Ve
+.PP
+\fI모범 사례\fR
+.IX Subsection "모범 사례"
+.PP
+Perl� 기본�으로 내부�서 UTF\-8� 사용하며 Encode 모듈� 통해
+다양한 �코딩� 지�하지만 항� 다� 규칙� 지킴으로� �코딩과
+관련한 다양하게 발�할 수 있는 문제� 가능성� 줄�는 것� 추천합니다.
+.IP \(bu 4
+소스 코드는 항� UTF\-8 �코딩으로 저장
+.IP \(bu 4
+소스 코드 �단� \f(CW\*(C`use utf8;\*(C'\fR 프�그마 사용
+.IP \(bu 4
+소스 코드, 터미�, 운�체제, ��터 �코딩� 분리해서 �해
+.IP \(bu 4
+입출력 파� 핸들� 명시�� �코딩� 사용
+.IP \(bu 4
+중복(double) �코딩� 주�
+.PP
+\fI유니코드 � 한국어 �코딩 관련 �료\fR
+.IX Subsection "유니코드 � 한국어 �코딩 관련 �료"
+.IP \(bu 4
+perluniintro
+.IP \(bu 4
+perlunicode
+.IP \(bu 4
+Encode
+.IP \(bu 4
+Encode::KR
+.IP \(bu 4
+encoding
+.IP \(bu 4
+<https://www.unicode.org/>
+.Sp
+유니코드 컨소시엄
+.IP \(bu 4
+<http://std.dkuug.dk/JTC1/SC2/WG2>
+.Sp
+기본�으로 Unicode와 같� ISO 표준�  ISO/IEC 10646 UCS(Universal
+Character Set)� 만드는 ISO/IEC JTC1/SC2/WG2� 웹 페�지
+.IP \(bu 4
+<https://www.cl.cam.ac.uk/~mgk25/unicode.html>
+.Sp
+유닉스/리눅스 사용�를 위한 UTF\-8 � 유니코드 관련 FAQ
+.IP \(bu 4
+<http://wiki.kldp.org/Translations/html/UTF8\-Unicode\-KLDP/UTF8\-Unicode\-KLDP.html>
+.Sp
+유닉스/리눅스 사용�를 위한 UTF\-8 � 유니코드 관련 FAQ� 한국어 번역
+.SH "Perl 관련 �료"
+.IX Header "Perl 관련 �료"
+다�� 공��� Perl 관련 �료중 �부입니다.
+.IP \(bu 4
+<https://www.perl.org/>
+.Sp
+Perl 공� 홈페�지
+.IP \(bu 4
+<https://www.perl.com/>
+.Sp
+O'Reilly� Perl 웹 페�지
+.IP \(bu 4
+<https://www.cpan.org/>
+.Sp
+CPAN \- Comprehensive Perl Archive Network, 통합� Perl 파� 보관 네트워�
+.IP \(bu 4
+<https://metacpan.org>
+.Sp
+메타 CPAN
+.IP \(bu 4
+<https://lists.perl.org/>
+.Sp
+Perl 메�� 리스트
+.IP \(bu 4
+<http://blogs.perl.org/>
+.Sp
+Perl 메타 블로그
+.IP \(bu 4
+<https://www.perlmonks.org/>
+.Sp
+Perl 수�승들� 위한 수��
+.IP \(bu 4
+<https://www.pm.org/groups/asia.html>
+.Sp
+아시아 지역 Perl 몽거스 모임
+.IP \(bu 4
+<http://www.perladvent.org/>
+.Sp
+Perl �리스마스 달력
+.PP
+다�� Perl� � 깊게 공부하는� �움� 줄 수 있는 한국어 관련 사�트입니다.
+.IP \(bu 4
+<https://perl.kr/>
+.Sp
+한국 Perl 커뮤니티 공� �털
+.IP \(bu 4
+<https://doc.perl.kr/>
+.Sp
+Perl 문서 한글화 프로�트
+.IP \(bu 4
+<https://cafe.naver.com/perlstudy.cafe>
+.Sp
+네�버 Perl 카페
+.IP \(bu 4
+<http://www.perl.or.kr/>
+.Sp
+한국 Perl 사용� 모임
+.IP \(bu 4
+<https://advent.perl.kr>
+.Sp
+Seoul.pm Perl �리스마스 달력 (2010 ~ 2012)
+.IP \(bu 4
+<http://gypark.pe.kr/wiki/Perl>
+.Sp
+GYPARK(Geunyoung Park)� Perl 관련 한글 문서 저장소
+.SH ��센스
+.IX Header "��센스"
+\&\fIREADME\fR 파�� \fB'LICENSING'\fR 항목� 참고하세요.
+.SH AUTHORS
+.IX Header "AUTHORS"
+.IP \(bu 4
+Jarkko Hietaniemi <jhi@iki.fi>
+.IP \(bu 4
+신정� <jshin@mailaps.org>
+.IP \(bu 4
+김�형 <keedi@cpan.org>
diff --git a/upstream/mageia-cauldron/man1/perllexwarn.1 b/upstream/mageia-cauldron/man1/perllexwarn.1
new file mode 100644
index 00000000..8e9504b8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perllexwarn.1
@@ -0,0 +1,70 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLLEXWARN 1"
+.TH PERLLEXWARN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perllexwarn \- Perl Lexical Warnings
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl v5.6.0 introduced lexical control over the handling of warnings by
+category.  The \f(CW\*(C`warnings\*(C'\fR pragma generally replaces the command line flag
+\&\fB\-w\fR.  Documentation on the use of lexical warnings, once partly found in
+this document, is now found in the warnings documentation.
diff --git a/upstream/mageia-cauldron/man1/perllinux.1 b/upstream/mageia-cauldron/man1/perllinux.1
new file mode 100644
index 00000000..7c43ad77
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perllinux.1
@@ -0,0 +1,105 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLLINUX 1"
+.TH PERLLINUX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perllinux \- Perl version 5 on Linux systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of Linux that will affect how Perl
+version 5 (hereafter just Perl) is compiled and/or runs.
+.SS "Deploying Perl on Linux"
+.IX Subsection "Deploying Perl on Linux"
+Normally one can install \fI/usr/bin/perl\fR on Linux using your distribution's
+package manager (e.g: \f(CW\*(C`sudo apt\-get install perl\*(C'\fR, or
+\&\f(CW\*(C`sudo dnf install perl\*(C'\fR). Note that sometimes one needs to install some
+extra system packages in order to be able to use CPAN frontends, and that
+messing with the system's perl is not always recommended. One can use
+perlbrew <https://perlbrew.pl/> to avoid such issues.
+.PP
+Otherwise, perl should build fine on Linux using the mainstream compilers
+GCC and clang, while following the usual instructions.
+.SS "Experimental Support for Sun Studio Compilers for Linux OS"
+.IX Subsection "Experimental Support for Sun Studio Compilers for Linux OS"
+Sun Microsystems has released a port of their Sun Studio compilers for
+Linux.  As of May 2019, the last stable release took place on 2017, and one can
+buy support contracts for them.
+.PP
+There are some special instructions for building Perl with Sun Studio on
+Linux.  Following the normal \f(CW\*(C`Configure\*(C'\fR, you have to run make as follows:
+.PP
+.Vb 1
+\&    LDLOADLIBS=\-lc make
+.Ve
+.PP
+\&\f(CW\*(C`LDLOADLIBS\*(C'\fR is an environment variable used by the linker to link
+\&\f(CW\*(C`/ext\*(C'\fR modules to glibc.  Currently, that environment variable is not getting
+populated by a combination of \f(CW\*(C`Config\*(C'\fR entries and \f(CW\*(C`ExtUtil::MakeMaker\*(C'\fR.
+While there may be a bug somewhere in Perl's configuration or
+\&\f(CW\*(C`ExtUtil::MakeMaker\*(C'\fR causing the problem, the most likely cause is an
+incomplete understanding of Sun Studio by this author.  Further investigation
+is needed to get this working better.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Steve Peters <steve@fisharerojo.org>
+.PP
+Please report any errors, updates, or suggestions to
+<https://github.com/Perl/perl5/issues>.
diff --git a/upstream/mageia-cauldron/man1/perllocale.1 b/upstream/mageia-cauldron/man1/perllocale.1
new file mode 100644
index 00000000..eb5597ff
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perllocale.1
@@ -0,0 +1,1764 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLLOCALE 1"
+.TH PERLLOCALE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perllocale \- Perl locale handling (internationalization and localization)
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+In the beginning there was ASCII, the "American Standard Code for
+Information Interchange", which works quite well for Americans with
+their English alphabet and dollar-denominated currency.  But it doesn't
+work so well even for other English speakers, who may use different
+currencies, such as the pound sterling (as the symbol for that currency
+is not in ASCII); and it's hopelessly inadequate for many of the
+thousands of the world's other languages.
+.PP
+To address these deficiencies, the concept of locales was invented
+(formally the ISO C, XPG4, POSIX 1.c "locale system").  And applications
+were and are being written that use the locale mechanism.  The process of
+making such an application take account of its users' preferences in
+these kinds of matters is called \fBinternationalization\fR (often
+abbreviated as \fBi18n\fR); telling such an application about a particular
+set of preferences is known as \fBlocalization\fR (\fBl10n\fR).
+.PP
+Perl has been extended to support certain types of locales available in
+the locale system.  This is controlled per application by using one
+pragma, one function call, and several environment variables.
+.PP
+Perl supports single-byte locales that are supersets of ASCII, such as
+the ISO 8859 ones, and one multi-byte-type locale, UTF\-8 ones, described
+in the next paragraph.  Perl doesn't support any other multi-byte
+locales, such as the ones for East Asian languages.
+.PP
+Unfortunately, there are quite a few deficiencies with the design (and
+often, the implementations) of locales.  Unicode was invented (see
+perlunitut for an introduction to that) in part to address these
+design deficiencies, and nowadays, there is a series of "UTF\-8
+locales", based on Unicode.  These are locales whose character set is
+Unicode, encoded in UTF\-8.  Starting in v5.20, Perl fully supports
+UTF\-8 locales, except for sorting and string comparisons like \f(CW\*(C`lt\*(C'\fR and
+\&\f(CW\*(C`ge\*(C'\fR.  Starting in v5.26, Perl can handle these reasonably as well,
+depending on the platform's implementation.  However, for earlier
+releases or for better control, use Unicode::Collate.  There are
+actually two slightly different types of UTF\-8 locales: one for Turkic
+languages and one for everything else.
+.PP
+Starting in Perl v5.30, Perl detects Turkic locales by their
+behaviour, and seamlessly handles both types; previously only the
+non-Turkic one was supported.  The name of the locale is ignored, if
+your system has a \f(CW\*(C`tr_TR.UTF\-8\*(C'\fR locale and it doesn't behave like a
+Turkic locale, perl will treat it like a non-Turkic locale.
+.PP
+Perl continues to support the old non UTF\-8 locales as well.  There are
+currently no UTF\-8 locales for EBCDIC platforms.
+.PP
+(Unicode is also creating \f(CW\*(C`CLDR\*(C'\fR, the "Common Locale Data Repository",
+<http://cldr.unicode.org/> which includes more types of information than
+are available in the POSIX locale system.  At the time of this writing,
+there was no CPAN module that provides access to this XML-encoded data.
+However, it is possible to compute the POSIX locale data from them, and
+earlier CLDR versions had these already extracted for you as UTF\-8 locales
+<http://unicode.org/Public/cldr/2.0.1/>.)
+.SH "WHAT IS A LOCALE"
+.IX Header "WHAT IS A LOCALE"
+A locale is a set of data that describes various aspects of how various
+communities in the world categorize their world.  These categories are
+broken down into the following types (some of which include a brief
+note here):
+.ie n .IP "Category ""LC_NUMERIC"": Numeric formatting" 4
+.el .IP "Category \f(CWLC_NUMERIC\fR: Numeric formatting" 4
+.IX Item "Category LC_NUMERIC: Numeric formatting"
+This indicates how numbers should be formatted for human readability,
+for example the character used as the decimal point.
+.ie n .IP "Category ""LC_MONETARY"": Formatting of monetary amounts" 4
+.el .IP "Category \f(CWLC_MONETARY\fR: Formatting of monetary amounts" 4
+.IX Item "Category LC_MONETARY: Formatting of monetary amounts"
+
+.ie n .IP "Category ""LC_TIME"": Date/Time formatting" 4
+.el .IP "Category \f(CWLC_TIME\fR: Date/Time formatting" 4
+.IX Item "Category LC_TIME: Date/Time formatting"
+
+.ie n .IP "Category ""LC_MESSAGES"": Error and other messages" 4
+.el .IP "Category \f(CWLC_MESSAGES\fR: Error and other messages" 4
+.IX Item "Category LC_MESSAGES: Error and other messages"
+This is used by Perl itself only for accessing operating system error
+messages via \f(CW$!\fR and \f(CW$^E\fR.
+.ie n .IP "Category ""LC_COLLATE"": Collation" 4
+.el .IP "Category \f(CWLC_COLLATE\fR: Collation" 4
+.IX Item "Category LC_COLLATE: Collation"
+This indicates the ordering of letters for comparison and sorting.
+In Latin alphabets, for example, "b", generally follows "a".
+.ie n .IP "Category ""LC_CTYPE"": Character Types" 4
+.el .IP "Category \f(CWLC_CTYPE\fR: Character Types" 4
+.IX Item "Category LC_CTYPE: Character Types"
+This indicates, for example if a character is an uppercase letter.
+.IP "Other categories" 4
+.IX Item "Other categories"
+Some platforms have other categories, dealing with such things as
+measurement units and paper sizes.  None of these are used directly by
+Perl, but outside operations that Perl interacts with may use
+these.  See "Not within the scope of "use locale"" below.
+.PP
+More details on the categories used by Perl are given below in "LOCALE
+CATEGORIES".
+.PP
+Together, these categories go a long way towards being able to customize
+a single program to run in many different locations.  But there are
+deficiencies, so keep reading.
+.SH "PREPARING TO USE LOCALES"
+.IX Header "PREPARING TO USE LOCALES"
+Perl itself (outside the POSIX module) will not use locales unless
+specifically requested to (but
+again note that Perl may interact with code that does use them).  Even
+if there is such a request, \fBall\fR of the following must be true
+for it to work properly:
+.IP \(bu 4
+\&\fBYour operating system must support the locale system\fR.  If it does,
+you should find that the \f(CWsetlocale()\fR function is a documented part of
+its C library.
+.IP \(bu 4
+\&\fBDefinitions for locales that you use must be installed\fR.  You, or
+your system administrator, must make sure that this is the case. The
+available locales, the location in which they are kept, and the manner
+in which they are installed all vary from system to system.  Some systems
+provide only a few, hard-wired locales and do not allow more to be
+added.  Others allow you to add "canned" locales provided by the system
+supplier.  Still others allow you or the system administrator to define
+and add arbitrary locales.  (You may have to ask your supplier to
+provide canned locales that are not delivered with your operating
+system.)  Read your system documentation for further illumination.
+.IP \(bu 4
+\&\fBPerl must believe that the locale system is supported\fR.  If it does,
+\&\f(CW\*(C`perl \-V:d_setlocale\*(C'\fR will say that the value for \f(CW\*(C`d_setlocale\*(C'\fR is
+\&\f(CW\*(C`define\*(C'\fR.
+.PP
+If you want a Perl application to process and present your data
+according to a particular locale, the application code should include
+the \f(CW\*(C`use\ locale\*(C'\fR pragma (see "The "use locale" pragma") where
+appropriate, and \fBat least one\fR of the following must be true:
+.IP 1. 4
+\&\fBThe locale-determining environment variables (see "ENVIRONMENT")
+must be correctly set up\fR at the time the application is started, either
+by yourself or by whomever set up your system account; or
+.IP 2. 4
+\&\fBThe application must set its own locale\fR using the method described in
+"The setlocale function".
+.SH "USING LOCALES"
+.IX Header "USING LOCALES"
+.ie n .SS "The ""use locale"" pragma"
+.el .SS "The \f(CW""use locale""\fP pragma"
+.IX Subsection "The ""use locale"" pragma"
+Starting in Perl 5.28, this pragma may be used in
+multi-threaded applications on systems that have thread-safe
+locale ability.  Some caveats apply, see "Multi-threaded" below.  On
+systems without this capability, or in earlier Perls, do NOT use this
+pragma in scripts that have multiple threads active.  The
+locale in these cases is not local to a single thread.  Another thread
+may change the locale at any time, which could cause at a minimum that a
+given thread is operating in a locale it isn't expecting to be in.  On
+some platforms, segfaults can also occur.  The locale change need not be
+explicit; some operations cause perl itself to change the locale.  You
+are vulnerable simply by having done a \f(CW"use\ locale"\fR.
+.PP
+By default, Perl itself (outside the POSIX module)
+ignores the current locale.  The \f(CW\*(C`use\ locale\*(C'\fR
+pragma tells Perl to use the current locale for some operations.
+Starting in v5.16, there are optional parameters to this pragma,
+described below, which restrict which operations are affected by it.
+.PP
+The current locale is set at execution time by
+\&\fBsetlocale()\fR described below.  If that function
+hasn't yet been called in the course of the program's execution, the
+current locale is that which was determined by the "ENVIRONMENT" in
+effect at the start of the program.
+If there is no valid environment, the current locale is whatever the
+system default has been set to.   On POSIX systems, it is likely, but
+not necessarily, the "C" locale.  On Windows, the default is set via the
+computer's \f(CW\*(C`Control\ Panel\->Regional\ and\ Language\ Options\*(C'\fR (or its
+current equivalent).
+.PP
+The operations that are affected by locale are:
+.ie n .IP "\fBNot within the scope of \fR\fB""use locale""\fR" 4
+.el .IP "\fBNot within the scope of \fR\f(CB""use locale""\fR" 4
+.IX Item "Not within the scope of ""use locale"""
+Only certain operations (all originating outside Perl) should be
+affected, as follows:
+.RS 4
+.IP \(bu 4
+The current locale is used when going outside of Perl with
+operations like \fBsystem()\fR or
+qx//, if those operations are
+locale-sensitive.
+.IP \(bu 4
+Also Perl gives access to various C library functions through the
+POSIX module.  Some of those functions are always affected by the
+current locale.  For example, \f(CWPOSIX::strftime()\fR uses \f(CW\*(C`LC_TIME\*(C'\fR;
+\&\f(CWPOSIX::strtod()\fR uses \f(CW\*(C`LC_NUMERIC\*(C'\fR; \f(CWPOSIX::strcoll()\fR and
+\&\f(CWPOSIX::strxfrm()\fR use \f(CW\*(C`LC_COLLATE\*(C'\fR.  All such functions
+will behave according to the current underlying locale, even if that
+locale isn't exposed to Perl space.
+.Sp
+This applies as well to I18N::Langinfo.
+.IP \(bu 4
+XS modules for all categories but \f(CW\*(C`LC_NUMERIC\*(C'\fR get the underlying
+locale, and hence any C library functions they call will use that
+underlying locale.  For more discussion, see "CAVEATS" in perlxs.
+.RE
+.RS 4
+.Sp
+Note that all C programs (including the perl interpreter, which is
+written in C) always have an underlying locale.  That locale is the "C"
+locale unless changed by a call to \fBsetlocale()\fR.  When Perl starts up, it changes the underlying locale to the
+one which is indicated by the "ENVIRONMENT".  When using the POSIX
+module or writing XS code, it is important to keep in mind that the
+underlying locale may be something other than "C", even if the program
+hasn't explicitly changed it.
+.Sp
+
+.RE
+.ie n .IP "\fBLingering effects of \fR\fB""use\ locale""\fR" 4
+.el .IP "\fBLingering effects of \fR\f(CBuse\ locale\fR" 4
+.IX Item "Lingering effects of use locale"
+Certain Perl operations that are set-up within the scope of a
+\&\f(CW\*(C`use locale\*(C'\fR retain that effect even outside the scope.
+These include:
+.RS 4
+.IP \(bu 4
+The output format of a \fBwrite()\fR is determined by an
+earlier format declaration ("format" in perlfunc), so whether or not the
+output is affected by locale is determined by if the \f(CWformat()\fR is
+within the scope of a \f(CW\*(C`use locale\*(C'\fR, not whether the \f(CWwrite()\fR
+is.
+.IP \(bu 4
+Regular expression patterns can be compiled using
+qr// with actual
+matching deferred to later.  Again, it is whether or not the compilation
+was done within the scope of \f(CW\*(C`use locale\*(C'\fR that determines the match
+behavior, not if the matches are done within such a scope or not.
+.RE
+.RS 4
+.Sp
+
+.RE
+.ie n .IP "\fBUnder \fR\fB""""use locale"";""\fR" 4
+.el .IP "\fBUnder \fR\f(CB""use locale"";\fR" 4
+.IX Item "Under ""use locale"";"
+.RS 4
+.PD 0
+.IP \(bu 4
+.PD
+All the above operations
+.IP \(bu 4
+\&\fBFormat declarations\fR ("format" in perlfunc) and hence any subsequent
+\&\f(CWwrite()\fRs use \f(CW\*(C`LC_NUMERIC\*(C'\fR.
+.IP \(bu 4
+\&\fBstringification and output\fR use \f(CW\*(C`LC_NUMERIC\*(C'\fR.
+These include the results of
+\&\f(CWprint()\fR,
+\&\f(CWprintf()\fR,
+\&\f(CWsay()\fR,
+and
+\&\f(CWsprintf()\fR.
+.IP \(bu 4
+\&\fBThe comparison operators\fR (\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`le\*(C'\fR, \f(CW\*(C`cmp\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, and \f(CW\*(C`gt\*(C'\fR) use
+\&\f(CW\*(C`LC_COLLATE\*(C'\fR.  \f(CWsort()\fR is also affected if used without an
+explicit comparison function, because it uses \f(CW\*(C`cmp\*(C'\fR by default.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR are unaffected by locale: they always
+perform a char-by-char comparison of their scalar operands.  What's
+more, if \f(CW\*(C`cmp\*(C'\fR finds that its operands are equal according to the
+collation sequence specified by the current locale, it goes on to
+perform a char-by-char comparison, and only returns \fI0\fR (equal) if the
+operands are char-for-char identical.  If you really want to know whether
+two strings\-\-which \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR may consider different\-\-are equal
+as far as collation in the locale is concerned, see the discussion in
+"Category \f(CW\*(C`LC_COLLATE\*(C'\fR: Collation".
+.IP \(bu 4
+\&\fBRegular expressions and case-modification functions\fR (\f(CWuc()\fR, \f(CWlc()\fR,
+\&\f(CWucfirst()\fR, and \f(CWlcfirst()\fR) use \f(CW\*(C`LC_CTYPE\*(C'\fR
+.IP \(bu 4
+\&\fBThe variables \fR\f(CB$!\fR (and its synonyms \f(CW$ERRNO\fR and
+\&\f(CW$OS_ERROR\fR) \fBand\fR \f(CW$^E\fR> (and its synonym
+\&\f(CW$EXTENDED_OS_ERROR\fR) when used as strings use \f(CW\*(C`LC_MESSAGES\*(C'\fR.
+.RE
+.RS 4
+.RE
+.PP
+The default behavior is restored with the \f(CW\*(C`no\ locale\*(C'\fR pragma, or
+upon reaching the end of the block enclosing \f(CW\*(C`use locale\*(C'\fR.
+Note that \f(CW\*(C`use locale\*(C'\fR calls may be
+nested, and that what is in effect within an inner scope will revert to
+the outer scope's rules at the end of the inner scope.
+.PP
+The string result of any operation that uses locale
+information is tainted (if your perl supports taint checking),
+as it is possible for a locale to be untrustworthy.
+See "SECURITY".
+.PP
+Starting in Perl v5.16 in a very limited way, and more generally in
+v5.22, you can restrict which category or categories are enabled by this
+particular instance of the pragma by adding parameters to it.  For
+example,
+.PP
+.Vb 1
+\& use locale qw(:ctype :numeric);
+.Ve
+.PP
+enables locale awareness within its scope of only those operations
+(listed above) that are affected by \f(CW\*(C`LC_CTYPE\*(C'\fR and \f(CW\*(C`LC_NUMERIC\*(C'\fR.
+.PP
+The possible categories are: \f(CW\*(C`:collate\*(C'\fR, \f(CW\*(C`:ctype\*(C'\fR, \f(CW\*(C`:messages\*(C'\fR,
+\&\f(CW\*(C`:monetary\*(C'\fR, \f(CW\*(C`:numeric\*(C'\fR, \f(CW\*(C`:time\*(C'\fR, and the pseudo category
+\&\f(CW\*(C`:characters\*(C'\fR (described below).
+.PP
+Thus you can say
+.PP
+.Vb 1
+\& use locale \*(Aq:messages\*(Aq;
+.Ve
+.PP
+and only \f(CW$!\fR and \f(CW$^E\fR
+will be locale aware.  Everything else is unaffected.
+.PP
+Since Perl doesn't currently do anything with the \f(CW\*(C`LC_MONETARY\*(C'\fR
+category, specifying \f(CW\*(C`:monetary\*(C'\fR does effectively nothing.  Some
+systems have other categories, such as \f(CW\*(C`LC_PAPER\*(C'\fR, but Perl
+also doesn't do anything with them, and there is no way to specify
+them in this pragma's arguments.
+.PP
+You can also easily say to use all categories but one, by either, for
+example,
+.PP
+.Vb 2
+\& use locale \*(Aq:!ctype\*(Aq;
+\& use locale \*(Aq:not_ctype\*(Aq;
+.Ve
+.PP
+both of which mean to enable locale awareness of all categories but
+\&\f(CW\*(C`LC_CTYPE\*(C'\fR.  Only one category argument may be specified in a
+\&\f(CW\*(C`use\ locale\*(C'\fR if it is of the negated form.
+.PP
+Prior to v5.22 only one form of the pragma with arguments is available:
+.PP
+.Vb 1
+\& use locale \*(Aq:not_characters\*(Aq;
+.Ve
+.PP
+(and you have to say \f(CW\*(C`not_\*(C'\fR; you can't use the bang \f(CW\*(C`!\*(C'\fR form).  This
+pseudo category is a shorthand for specifying both \f(CW\*(C`:collate\*(C'\fR and
+\&\f(CW\*(C`:ctype\*(C'\fR.  Hence, in the negated form, it is nearly the same thing as
+saying
+.PP
+.Vb 1
+\& use locale qw(:messages :monetary :numeric :time);
+.Ve
+.PP
+We use the term "nearly", because \f(CW\*(C`:not_characters\*(C'\fR also turns on
+\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR within its scope.  This form is
+less useful in v5.20 and later, and is described fully in
+"Unicode and UTF\-8", but briefly, it tells Perl to not use the
+character portions of the locale definition, that is the \f(CW\*(C`LC_CTYPE\*(C'\fR and
+\&\f(CW\*(C`LC_COLLATE\*(C'\fR categories.  Instead it will use the native character set
+(extended by Unicode).  When using this parameter, you are responsible
+for getting the external character set translated into the
+native/Unicode one (which it already will be if it is one of the
+increasingly popular UTF\-8 locales).  There are convenient ways of doing
+this, as described in "Unicode and UTF\-8".
+.SS "The setlocale function"
+.IX Subsection "The setlocale function"
+WARNING!  Prior to Perl 5.28 or on a system that does not support
+thread-safe locale operations, do NOT use this function in a
+thread.  The locale will change in all other threads at the
+same time, and should your thread get paused by the operating system,
+and another started, that thread will not have the locale it is
+expecting.  On some platforms, there can be a race leading to segfaults
+if two threads call this function nearly simultaneously.  This warning
+does not apply on unthreaded builds, or on perls where
+\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR exists and is non-zero; namely Perl 5.28 and later
+unthreaded or compiled to be locale-thread-safe.  On z/OS systems, this
+function becomes a no-op once any thread is started.  Thus, on that
+system, you can set up the locale before creating any threads, and that
+locale will be the one in effect for the entire program.
+.PP
+Otherwise, you can switch locales as often as you wish at run time with
+the \f(CWPOSIX::setlocale()\fR function:
+.PP
+.Vb 6
+\&        # Import locale\-handling tool set from POSIX module.
+\&        # This example uses: setlocale \-\- the function call
+\&        #                    LC_CTYPE \-\- explained below
+\&        # (Showing the testing for success/failure of operations is
+\&        # omitted in these examples to avoid distracting from the main
+\&        # point)
+\&
+\&        use POSIX qw(locale_h);
+\&        use locale;
+\&        my $old_locale;
+\&
+\&        # query and save the old locale
+\&        $old_locale = setlocale(LC_CTYPE);
+\&
+\&        setlocale(LC_CTYPE, "fr_CA.ISO8859\-1");
+\&        # LC_CTYPE now in locale "French, Canada, codeset ISO 8859\-1"
+\&
+\&        setlocale(LC_CTYPE, "");
+\&        # LC_CTYPE now reset to the default defined by the
+\&        # LC_ALL/LC_CTYPE/LANG environment variables, or to the system
+\&        # default.  See below for documentation.
+\&
+\&        # restore the old locale
+\&        setlocale(LC_CTYPE, $old_locale);
+.Ve
+.PP
+The first argument of \f(CWsetlocale()\fR gives the \fBcategory\fR, the second the
+\&\fBlocale\fR.  The category tells in what aspect of data processing you
+want to apply locale-specific rules.  Category names are discussed in
+"LOCALE CATEGORIES" and "ENVIRONMENT".  The locale is the name of a
+collection of customization information corresponding to a particular
+combination of language, country or territory, and codeset.  Read on for
+hints on the naming of locales: not all systems name locales as in the
+example.
+.PP
+If no second argument is provided and the category is something other
+than \f(CW\*(C`LC_ALL\*(C'\fR, the function returns a string naming the current locale
+for the category.  You can use this value as the second argument in a
+subsequent call to \f(CWsetlocale()\fR, \fBbut\fR on some platforms the string
+is opaque, not something that most people would be able to decipher as
+to what locale it means.
+.PP
+If no second argument is provided and the category is \f(CW\*(C`LC_ALL\*(C'\fR, the
+result is implementation-dependent.  It may be a string of
+concatenated locale names (separator also implementation-dependent)
+or a single locale name.  Please consult your \fBsetlocale\fR\|(3) man page for
+details.
+.PP
+If a second argument is given and it corresponds to a valid locale,
+the locale for the category is set to that value, and the function
+returns the now-current locale value.  You can then use this in yet
+another call to \f(CWsetlocale()\fR.  (In some implementations, the return
+value may sometimes differ from the value you gave as the second
+argument\-\-think of it as an alias for the value you gave.)
+.PP
+As the example shows, if the second argument is an empty string, the
+category's locale is returned to the default specified by the
+corresponding environment variables.  Generally, this results in a
+return to the default that was in force when Perl started up: changes
+to the environment made by the application after startup may or may not
+be noticed, depending on your system's C library.
+.PP
+Note that when a form of \f(CW\*(C`use locale\*(C'\fR that doesn't include all
+categories is specified, Perl ignores the excluded categories.
+.PP
+If \f(CWsetlocale()\fR fails for some reason (for example, an attempt to set
+to a locale unknown to the system), the locale for the category is not
+changed, and the function returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+Starting in Perl 5.28, on multi-threaded perls compiled on systems that
+implement POSIX 2008 thread-safe locale operations, this function
+doesn't actually call the system \f(CW\*(C`setlocale\*(C'\fR.  Instead those
+thread-safe operations are used to emulate the \f(CW\*(C`setlocale\*(C'\fR function,
+but in a thread-safe manner.
+.PP
+You can force the thread-safe locale operations to always be used (if
+available) by recompiling perl with
+.PP
+.Vb 1
+\& \-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq
+.Ve
+.PP
+added to your call to \fIConfigure\fR.
+.PP
+For further information about the categories, consult \fBsetlocale\fR\|(3).
+.SS "Multi-threaded operation"
+.IX Subsection "Multi-threaded operation"
+Beginning in Perl 5.28, multi-threaded locale operation is supported on
+systems that implement either the POSIX 2008 or Windows-specific
+thread-safe locale operations.  Many modern systems, such as various
+Unix variants and Darwin do have this.
+.PP
+You can tell if using locales is safe on your system by looking at the
+read-only boolean variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR.  The value is 1 if the
+perl is not threaded, or if it is using thread-safe locale operations.
+.PP
+Thread-safe operations are supported in Windows starting in Visual Studio
+2005, and in systems compatible with POSIX 2008.  Some platforms claim
+to support POSIX 2008, but have buggy implementations, so that the hints
+files for compiling to run on them turn off attempting to use
+thread-safety.  \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR will be 0 on them.
+.PP
+Be aware that writing a multi-threaded application will not be portable
+to a platform which lacks the native thread-safe locale support.  On
+systems that do have it, you automatically get this behavior for
+threaded perls, without having to do anything.  If for some reason, you
+don't want to use this capability (perhaps the POSIX 2008 support is
+buggy on your system), you can manually compile Perl to use the old
+non-thread-safe implementation by passing the argument
+\&\f(CW\*(C`\-Accflags=\*(Aq\-DNO_THREAD_SAFE_LOCALE\*(Aq\*(C'\fR to \fIConfigure\fR.
+Except on Windows, this will continue to use certain of the POSIX 2008
+functions in some situations.  If these are buggy, you can pass the
+following to \fIConfigure\fR instead or additionally:
+\&\f(CW\*(C`\-Accflags=\*(Aq\-DNO_POSIX_2008_LOCALE\*(Aq\*(C'\fR.  This will also keep the code
+from using thread-safe locales.
+\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR will be 0 on systems that turn off the thread-safe
+operations.
+.PP
+Normally on unthreaded builds, the traditional \f(CWsetlocale()\fR is used
+and not the thread-safe locale functions.  You can force the use of these
+on systems that have them by adding the
+\&\f(CW\*(C`\-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq\*(C'\fR to \fIConfigure\fR.
+.PP
+The initial program is started up using the locale specified from the
+environment, as currently, described in "ENVIRONMENT".   All newly
+created threads start with \f(CW\*(C`LC_ALL\*(C'\fR set to \f(CW"C"\fR.  Each thread may
+use \f(CWPOSIX::setlocale()\fR to query or switch its locale at any time,
+without affecting any other thread.  All locale-dependent operations
+automatically use their thread's locale.
+.PP
+This should be completely transparent to any applications written
+entirely in Perl (minus a few rarely encountered caveats given in the
+"Multi-threaded" section).  Information for XS module writers is given
+in "Locale-aware XS code" in perlxs.
+.SS "Finding locales"
+.IX Subsection "Finding locales"
+For locales available in your system, consult also \fBsetlocale\fR\|(3) to
+see whether it leads to the list of available locales (search for the
+\&\fISEE ALSO\fR section).  If that fails, try the following command lines:
+.PP
+.Vb 1
+\&        locale \-a
+\&
+\&        nlsinfo
+\&
+\&        ls /usr/lib/nls/loc
+\&
+\&        ls /usr/lib/locale
+\&
+\&        ls /usr/lib/nls
+\&
+\&        ls /usr/share/locale
+.Ve
+.PP
+and see whether they list something resembling these
+.PP
+.Vb 7
+\&        en_US.ISO8859\-1     de_DE.ISO8859\-1     ru_RU.ISO8859\-5
+\&        en_US.iso88591      de_DE.iso88591      ru_RU.iso88595
+\&        en_US               de_DE               ru_RU
+\&        en                  de                  ru
+\&        english             german              russian
+\&        english.iso88591    german.iso88591     russian.iso88595
+\&        english.roman8                          russian.koi8r
+.Ve
+.PP
+Sadly, even though the calling interface for \f(CWsetlocale()\fR has been
+standardized, names of locales and the directories where the
+configuration resides have not been.  The basic form of the name is
+\&\fIlanguage_territory\fR\fB.\fR\fIcodeset\fR, but the latter parts after
+\&\fIlanguage\fR are not always present.  The \fIlanguage\fR and \fIcountry\fR
+are usually from the standards \fBISO 3166\fR and \fBISO 639\fR, the
+two-letter abbreviations for the countries and the languages of the
+world, respectively.  The \fIcodeset\fR part often mentions some \fBISO
+8859\fR character set, the Latin codesets.  For example, \f(CW\*(C`ISO 8859\-1\*(C'\fR
+is the so-called "Western European codeset" that can be used to encode
+most Western European languages adequately.  Again, there are several
+ways to write even the name of that one standard.  Lamentably.
+.PP
+Two special locales are worth particular mention: "C" and "POSIX".
+Currently these are effectively the same locale: the difference is
+mainly that the first one is defined by the C standard, the second by
+the POSIX standard.  They define the \fBdefault locale\fR in which
+every program starts in the absence of locale information in its
+environment.  (The \fIdefault\fR default locale, if you will.)  Its language
+is (American) English and its character codeset ASCII or, rarely, a
+superset thereof (such as the "DEC Multinational Character Set
+(DEC-MCS)").  \fBWarning\fR. The C locale delivered by some vendors
+may not actually exactly match what the C standard calls for.  So
+beware.
+.PP
+\&\fBNOTE\fR: Not all systems have the "POSIX" locale (not all systems are
+POSIX-conformant), so use "C" when you need explicitly to specify this
+default locale.
+.SS "LOCALE PROBLEMS"
+.IX Subsection "LOCALE PROBLEMS"
+You may encounter the following warning message at Perl startup:
+.PP
+.Vb 6
+\&        perl: warning: Setting locale failed.
+\&        perl: warning: Please check that your locale settings:
+\&                LC_ALL = "En_US",
+\&                LANG = (unset)
+\&            are supported and installed on your system.
+\&        perl: warning: Falling back to the standard locale ("C").
+.Ve
+.PP
+This means that your locale settings had \f(CW\*(C`LC_ALL\*(C'\fR set to "En_US" and
+LANG exists but has no value.  Perl tried to believe you but could not.
+Instead, Perl gave up and fell back to the "C" locale, the default locale
+that is supposed to work no matter what.  (On Windows, it first tries
+falling back to the system default locale.)  This usually means your
+locale settings were wrong, they mention locales your system has never
+heard of, or the locale installation in your system has problems (for
+example, some system files are broken or missing).  There are quick and
+temporary fixes to these problems, as well as more thorough and lasting
+fixes.
+.SS "Testing for broken locales"
+.IX Subsection "Testing for broken locales"
+If you are building Perl from source, the Perl test suite file
+\&\fIlib/locale.t\fR can be used to test the locales on your system.
+Setting the environment variable \f(CW\*(C`PERL_DEBUG_FULL_TEST\*(C'\fR to 1
+will cause it to output detailed results.  For example, on Linux, you
+could say
+.PP
+.Vb 1
+\& PERL_DEBUG_FULL_TEST=1 ./perl \-T \-Ilib lib/locale.t > locale.log 2>&1
+.Ve
+.PP
+Besides many other tests, it will test every locale it finds on your
+system to see if they conform to the POSIX standard.  If any have
+errors, it will include a summary near the end of the output of which
+locales passed all its tests, and which failed, and why.
+.SS "Temporarily fixing locale problems"
+.IX Subsection "Temporarily fixing locale problems"
+The two quickest fixes are either to render Perl silent about any
+locale inconsistencies or to run Perl under the default locale "C".
+.PP
+Perl's moaning about locale problems can be silenced by setting the
+environment variable \f(CW\*(C`PERL_BADLANG\*(C'\fR to "0" or "".
+This method really just sweeps the problem under the carpet: you tell
+Perl to shut up even when Perl sees that something is wrong.  Do not
+be surprised if later something locale-dependent misbehaves.
+.PP
+Perl can be run under the "C" locale by setting the environment
+variable \f(CW\*(C`LC_ALL\*(C'\fR to "C".  This method is perhaps a bit more civilized
+than the \f(CW\*(C`PERL_BADLANG\*(C'\fR approach, but setting \f(CW\*(C`LC_ALL\*(C'\fR (or
+other locale variables) may affect other programs as well, not just
+Perl.  In particular, external programs run from within Perl will see
+these changes.  If you make the new settings permanent (read on), all
+programs you run see the changes.  See "ENVIRONMENT" for
+the full list of relevant environment variables and "USING LOCALES"
+for their effects in Perl.  Effects in other programs are
+easily deducible.  For example, the variable \f(CW\*(C`LC_COLLATE\*(C'\fR may well affect
+your \fBsort\fR program (or whatever the program that arranges "records"
+alphabetically in your system is called).
+.PP
+You can test out changing these variables temporarily, and if the
+new settings seem to help, put those settings into your shell startup
+files.  Consult your local documentation for the exact details.  For
+Bourne-like shells (\fBsh\fR, \fBksh\fR, \fBbash\fR, \fBzsh\fR):
+.PP
+.Vb 2
+\&        LC_ALL=en_US.ISO8859\-1
+\&        export LC_ALL
+.Ve
+.PP
+This assumes that we saw the locale "en_US.ISO8859\-1" using the commands
+discussed above.  We decided to try that instead of the above faulty
+locale "En_US"\-\-and in Cshish shells (\fBcsh\fR, \fBtcsh\fR)
+.PP
+.Vb 1
+\&        setenv LC_ALL en_US.ISO8859\-1
+.Ve
+.PP
+or if you have the "env" application you can do (in any shell)
+.PP
+.Vb 1
+\&        env LC_ALL=en_US.ISO8859\-1 perl ...
+.Ve
+.PP
+If you do not know what shell you have, consult your local
+helpdesk or the equivalent.
+.SS "Permanently fixing locale problems"
+.IX Subsection "Permanently fixing locale problems"
+The slower but superior fixes are when you may be able to yourself
+fix the misconfiguration of your own environment variables.  The
+mis(sing)configuration of the whole system's locales usually requires
+the help of your friendly system administrator.
+.PP
+First, see earlier in this document about "Finding locales".  That tells
+how to find which locales are really supported\-\-and more importantly,
+installed\-\-on your system.  In our example error message, environment
+variables affecting the locale are listed in the order of decreasing
+importance (and unset variables do not matter).  Therefore, having
+LC_ALL set to "En_US" must have been the bad choice, as shown by the
+error message.  First try fixing locale settings listed first.
+.PP
+Second, if using the listed commands you see something \fBexactly\fR
+(prefix matches do not count and case usually counts) like "En_US"
+without the quotes, then you should be okay because you are using a
+locale name that should be installed and available in your system.
+In this case, see "Permanently fixing your system's locale configuration".
+.SS "Permanently fixing your system's locale configuration"
+.IX Subsection "Permanently fixing your system's locale configuration"
+This is when you see something like:
+.PP
+.Vb 4
+\&        perl: warning: Please check that your locale settings:
+\&                LC_ALL = "En_US",
+\&                LANG = (unset)
+\&            are supported and installed on your system.
+.Ve
+.PP
+but then cannot see that "En_US" listed by the above-mentioned
+commands.  You may see things like "en_US.ISO8859\-1", but that isn't
+the same.  In this case, try running under a locale
+that you can list and which somehow matches what you tried.  The
+rules for matching locale names are a bit vague because
+standardization is weak in this area.  See again the
+"Finding locales" about general rules.
+.SS "Fixing system locale configuration"
+.IX Subsection "Fixing system locale configuration"
+Contact a system administrator (preferably your own) and report the exact
+error message you get, and ask them to read this same documentation you
+are now reading.  They should be able to check whether there is something
+wrong with the locale configuration of the system.  The "Finding locales"
+section is unfortunately a bit vague about the exact commands and places
+because these things are not that standardized.
+.SS "The localeconv function"
+.IX Subsection "The localeconv function"
+The \f(CWPOSIX::localeconv()\fR function allows you to get particulars of the
+locale-dependent numeric formatting information specified by the current
+underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR and \f(CW\*(C`LC_MONETARY\*(C'\fR locales (regardless of
+whether called from within the scope of \f(CW\*(C`use\ locale\*(C'\fR or not).  (If
+you just want the name of
+the current locale for a particular category, use \f(CWPOSIX::setlocale()\fR
+with a single parameter\-\-see "The setlocale function".)
+.PP
+.Vb 1
+\&        use POSIX qw(locale_h);
+\&
+\&        # Get a reference to a hash of locale\-dependent info
+\&        $locale_values = localeconv();
+\&
+\&        # Output sorted list of the values
+\&        for (sort keys %$locale_values) {
+\&            printf "%\-20s = %s\en", $_, $locale_values\->{$_}
+\&        }
+.Ve
+.PP
+\&\f(CWlocaleconv()\fR takes no arguments, and returns \fBa reference to\fR a hash.
+The keys of this hash are variable names for formatting, such as
+\&\f(CW\*(C`decimal_point\*(C'\fR and \f(CW\*(C`thousands_sep\*(C'\fR.  The values are the
+corresponding, er, values.  See "localeconv" in POSIX for a longer
+example listing the categories an implementation might be expected to
+provide; some provide more and others fewer.  You don't need an
+explicit \f(CW\*(C`use locale\*(C'\fR, because \f(CWlocaleconv()\fR always observes the
+current locale.
+.PP
+Here's a simple-minded example program that rewrites its command-line
+parameters as integers correctly formatted in the current locale:
+.PP
+.Vb 1
+\&    use POSIX qw(locale_h);
+\&
+\&    # Get some of locale\*(Aqs numeric formatting parameters
+\&    my ($thousands_sep, $grouping) =
+\&            @{localeconv()}{\*(Aqthousands_sep\*(Aq, \*(Aqgrouping\*(Aq};
+\&
+\&    # Apply defaults if values are missing
+\&    $thousands_sep = \*(Aq,\*(Aq unless $thousands_sep;
+\&
+\&    # grouping and mon_grouping are packed lists
+\&    # of small integers (characters) telling the
+\&    # grouping (thousand_seps and mon_thousand_seps
+\&    # being the group dividers) of numbers and
+\&    # monetary quantities.  The integers\*(Aq meanings:
+\&    # 255 means no more grouping, 0 means repeat
+\&    # the previous grouping, 1\-254 means use that
+\&    # as the current grouping.  Grouping goes from
+\&    # right to left (low to high digits).  In the
+\&    # below we cheat slightly by never using anything
+\&    # else than the first grouping (whatever that is).
+\&    if ($grouping) {
+\&        @grouping = unpack("C*", $grouping);
+\&    } else {
+\&        @grouping = (3);
+\&    }
+\&
+\&    # Format command line params for current locale
+\&    for (@ARGV) {
+\&        $_ = int;    # Chop non\-integer part
+\&        1 while
+\&        s/(\ed)(\ed{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
+\&        print "$_";
+\&    }
+\&    print "\en";
+.Ve
+.PP
+Note that if the platform doesn't have \f(CW\*(C`LC_NUMERIC\*(C'\fR and/or
+\&\f(CW\*(C`LC_MONETARY\*(C'\fR available or enabled, the corresponding elements of the
+hash will be missing.
+.SS I18N::Langinfo
+.IX Subsection "I18N::Langinfo"
+Another interface for querying locale-dependent information is the
+\&\f(CWI18N::Langinfo::langinfo()\fR function.
+.PP
+The following example will import the \f(CWlanginfo()\fR function itself and
+three constants to be used as arguments to \f(CWlanginfo()\fR: a constant for
+the abbreviated first day of the week (the numbering starts from
+Sunday = 1) and two more constants for the affirmative and negative
+answers for a yes/no question in the current locale.
+.PP
+.Vb 1
+\&    use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
+\&
+\&    my ($abday_1, $yesstr, $nostr)
+\&                = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
+\&
+\&    print "$abday_1? [$yesstr/$nostr] ";
+.Ve
+.PP
+In other words, in the "C" (or English) locale the above will probably
+print something like:
+.PP
+.Vb 1
+\&    Sun? [yes/no]
+.Ve
+.PP
+See I18N::Langinfo for more information.
+.SH "LOCALE CATEGORIES"
+.IX Header "LOCALE CATEGORIES"
+The following subsections describe basic locale categories.  Beyond these,
+some combination categories allow manipulation of more than one
+basic category at a time.  See "ENVIRONMENT" for a discussion of these.
+.ie n .SS "Category ""LC_COLLATE"": Collation: Text Comparisons and Sorting"
+.el .SS "Category \f(CWLC_COLLATE\fP: Collation: Text Comparisons and Sorting"
+.IX Subsection "Category LC_COLLATE: Collation: Text Comparisons and Sorting"
+In the scope of a \f(CW\*(C`use\ locale\*(C'\fR form that includes collation, Perl
+looks to the \f(CW\*(C`LC_COLLATE\*(C'\fR
+environment variable to determine the application's notions on collation
+(ordering) of characters.  For example, "b" follows "a" in Latin
+alphabets, but where do "á" and "å" belong?  And while
+"color" follows "chocolate" in English, what about in traditional Spanish?
+.PP
+The following collations all make sense and you may meet any of them
+if you \f(CW"use locale"\fR.
+.PP
+.Vb 4
+\&        A B C D E a b c d e
+\&        A a B b C c D d E e
+\&        a A b B c C d D e E
+\&        a b c d e A B C D E
+.Ve
+.PP
+Here is a code snippet to tell what "word"
+characters are in the current locale, in that locale's order:
+.PP
+.Vb 2
+\&        use locale;
+\&        print +(sort grep /\ew/, map { chr } 0..255), "\en";
+.Ve
+.PP
+Compare this with the characters that you see and their order if you
+state explicitly that the locale should be ignored:
+.PP
+.Vb 2
+\&        no locale;
+\&        print +(sort grep /\ew/, map { chr } 0..255), "\en";
+.Ve
+.PP
+This machine-native collation (which is what you get unless \f(CW\*(C`use\ locale\*(C'\fR has appeared earlier in the same block) must be used for
+sorting raw binary data, whereas the locale-dependent collation of the
+first example is useful for natural text.
+.PP
+As noted in "USING LOCALES", \f(CW\*(C`cmp\*(C'\fR compares according to the current
+collation locale when \f(CW\*(C`use locale\*(C'\fR is in effect, but falls back to a
+char-by-char comparison for strings that the locale says are equal. You
+can use \f(CWPOSIX::strcoll()\fR if you don't want this fall-back:
+.PP
+.Vb 3
+\&        use POSIX qw(strcoll);
+\&        $equal_in_locale =
+\&            !strcoll("space and case ignored", "SpaceAndCaseIgnored");
+.Ve
+.PP
+\&\f(CW$equal_in_locale\fR will be true if the collation locale specifies a
+dictionary-like ordering that ignores space characters completely and
+which folds case.
+.PP
+Perl uses the platform's C library collation functions \f(CWstrcoll()\fR and
+\&\f(CWstrxfrm()\fR.  That means you get whatever they give.  On some
+platforms, these functions work well on UTF\-8 locales, giving
+a reasonable default collation for the code points that are important in
+that locale.  (And if they aren't working well, the problem may only be
+that the locale definition is deficient, so can be fixed by using a
+better definition file.  Unicode's definitions (see "Freely available
+locale definitions") provide reasonable UTF\-8 locale collation
+definitions.)  Starting in Perl v5.26, Perl's use of these functions has
+been made more seamless.  This may be sufficient for your needs.  For
+more control, and to make sure strings containing any code point (not
+just the ones important in the locale) collate properly, the
+Unicode::Collate module is suggested.
+.PP
+In non\-UTF\-8 locales (hence single byte), code points above 0xFF are
+technically invalid.  But if present, again starting in v5.26, they will
+collate to the same position as the highest valid code point does.  This
+generally gives good results, but the collation order may be skewed if
+the valid code point gets special treatment when it forms particular
+sequences with other characters as defined by the locale.
+When two strings collate identically, the code point order is used as a
+tie breaker.
+.PP
+If Perl detects that there are problems with the locale collation order,
+it reverts to using non-locale collation rules for that locale.
+.PP
+If you have a single string that you want to check for "equality in
+locale" against several others, you might think you could gain a little
+efficiency by using \f(CWPOSIX::strxfrm()\fR in conjunction with \f(CW\*(C`eq\*(C'\fR:
+.PP
+.Vb 8
+\&        use POSIX qw(strxfrm);
+\&        $xfrm_string = strxfrm("Mixed\-case string");
+\&        print "locale collation ignores spaces\en"
+\&            if $xfrm_string eq strxfrm("Mixed\-casestring");
+\&        print "locale collation ignores hyphens\en"
+\&            if $xfrm_string eq strxfrm("Mixedcase string");
+\&        print "locale collation ignores case\en"
+\&            if $xfrm_string eq strxfrm("mixed\-case string");
+.Ve
+.PP
+\&\f(CWstrxfrm()\fR takes a string and maps it into a transformed string for use
+in char-by-char comparisons against other transformed strings during
+collation.  "Under the hood", locale-affected Perl comparison operators
+call \f(CWstrxfrm()\fR for both operands, then do a char-by-char
+comparison of the transformed strings.  By calling \f(CWstrxfrm()\fR explicitly
+and using a non locale-affected comparison, the example attempts to save
+a couple of transformations.  But in fact, it doesn't save anything: Perl
+magic (see "Magic Variables" in perlguts) creates the transformed version of a
+string the first time it's needed in a comparison, then keeps this version around
+in case it's needed again.  An example rewritten the easy way with
+\&\f(CW\*(C`cmp\*(C'\fR runs just about as fast.  It also copes with null characters
+embedded in strings; if you call \f(CWstrxfrm()\fR directly, it treats the first
+null it finds as a terminator.  Don't expect the transformed strings
+it produces to be portable across systems\-\-or even from one revision
+of your operating system to the next.  In short, don't call \f(CWstrxfrm()\fR
+directly: let Perl do it for you.
+.PP
+Note: \f(CW\*(C`use locale\*(C'\fR isn't shown in some of these examples because it isn't
+needed: \f(CWstrcoll()\fR and \f(CWstrxfrm()\fR are POSIX functions
+which use the standard system-supplied \f(CW\*(C`libc\*(C'\fR functions that
+always obey the current \f(CW\*(C`LC_COLLATE\*(C'\fR locale.
+.ie n .SS "Category ""LC_CTYPE"": Character Types"
+.el .SS "Category \f(CWLC_CTYPE\fP: Character Types"
+.IX Subsection "Category LC_CTYPE: Character Types"
+In the scope of a \f(CW\*(C`use\ locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR, Perl
+obeys the \f(CW\*(C`LC_CTYPE\*(C'\fR locale
+setting.  This controls the application's notion of which characters are
+alphabetic, numeric, punctuation, \fIetc\fR.  This affects Perl's \f(CW\*(C`\ew\*(C'\fR
+regular expression metanotation,
+which stands for alphanumeric characters\-\-that is, alphabetic,
+numeric, and the platform's native underscore.
+(Consult perlre for more information about
+regular expressions.)  Thanks to \f(CW\*(C`LC_CTYPE\*(C'\fR, depending on your locale
+setting, characters like "æ", "ð", "ß", and
+"ø" may be understood as \f(CW\*(C`\ew\*(C'\fR characters.
+It also affects things like \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\eD\*(C'\fR, and the POSIX character
+classes, like \f(CW\*(C`[[:graph:]]\*(C'\fR.  (See perlrecharclass for more
+information on all these.)
+.PP
+The \f(CW\*(C`LC_CTYPE\*(C'\fR locale also provides the map used in transliterating
+characters between lower and uppercase.  This affects the case-mapping
+functions\-\-\f(CWfc()\fR, \f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR, and \f(CWucfirst()\fR;
+case-mapping
+interpolation with \f(CW\*(C`\eF\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, or \f(CW\*(C`\eU\*(C'\fR in double-quoted
+strings and \f(CW\*(C`s///\*(C'\fR substitutions; and case-insensitive regular expression
+pattern matching using the \f(CW\*(C`i\*(C'\fR modifier.
+.PP
+Starting in v5.20, Perl supports UTF\-8 locales for \f(CW\*(C`LC_CTYPE\*(C'\fR, but
+otherwise Perl only supports single-byte locales, such as the ISO 8859
+series.  This means that wide character locales, for example for Asian
+languages, are not well-supported.  Use of these locales may cause core
+dumps.  If the platform has the capability for Perl to detect such a
+locale, starting in Perl v5.22, Perl will warn, default
+enabled, using the \f(CW\*(C`locale\*(C'\fR warning
+category, whenever such a locale is switched into.  The UTF\-8 locale
+support is actually a
+superset of POSIX locales, because it is really full Unicode behavior
+as if no \f(CW\*(C`LC_CTYPE\*(C'\fR locale were in effect at all (except for tainting;
+see "SECURITY").  POSIX locales, even UTF\-8 ones,
+are lacking certain concepts in Unicode, such as the idea that changing
+the case of a character could expand to be more than one character.
+Perl in a UTF\-8 locale, will give you that expansion.  Prior to v5.20,
+Perl treated a UTF\-8 locale on some platforms like an ISO 8859\-1 one,
+with some restrictions, and on other platforms more like the "C" locale.
+For releases v5.16 and v5.18, \f(CW\*(C`use\ locale\ \*(Aqnot_characters\*(C'\fR could be
+used as a workaround for this (see "Unicode and UTF\-8").
+.PP
+Note that there are quite a few things that are unaffected by the
+current locale.  Any literal character is the native character for the
+given platform.  Hence 'A' means the character at code point 65 on ASCII
+platforms, and 193 on EBCDIC.  That may or may not be an 'A' in the
+current locale, if that locale even has an 'A'.
+Similarly, all the escape sequences for particular characters,
+\&\f(CW\*(C`\en\*(C'\fR for example, always mean the platform's native one.  This means,
+for example, that \f(CW\*(C`\eN\*(C'\fR in regular expressions (every character
+but new-line) works on the platform character set.
+.PP
+Starting in v5.22, Perl will by default warn when switching into a
+locale that redefines any ASCII printable character (plus \f(CW\*(C`\et\*(C'\fR and
+\&\f(CW\*(C`\en\*(C'\fR) into a different class than expected.  This is likely to
+happen on modern locales only on EBCDIC platforms, where, for example,
+a CCSID 0037 locale on a CCSID 1047 machine moves \f(CW"["\fR, but it can
+happen on ASCII platforms with the ISO 646 and other
+7\-bit locales that are essentially obsolete.  Things may still work,
+depending on what features of Perl are used by the program.  For
+example, in the example from above where \f(CW"|"\fR becomes a \f(CW\*(C`\ew\*(C'\fR, and
+there are no regular expressions where this matters, the program may
+still work properly.  The warning lists all the characters that
+it can determine could be adversely affected.
+.PP
+\&\fBNote:\fR A broken or malicious \f(CW\*(C`LC_CTYPE\*(C'\fR locale definition may result
+in clearly ineligible characters being considered to be alphanumeric by
+your application.  For strict matching of (mundane) ASCII letters and
+digits\-\-for example, in command strings\-\-locale\-aware applications
+should use \f(CW\*(C`\ew\*(C'\fR with the \f(CW\*(C`/a\*(C'\fR regular expression modifier.  See "SECURITY".
+.ie n .SS "Category ""LC_NUMERIC"": Numeric Formatting"
+.el .SS "Category \f(CWLC_NUMERIC\fP: Numeric Formatting"
+.IX Subsection "Category LC_NUMERIC: Numeric Formatting"
+After a proper \f(CWPOSIX::setlocale()\fR call, and within the scope
+of a \f(CW\*(C`use locale\*(C'\fR form that includes numerics, Perl obeys the
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR locale information, which controls an application's idea
+of how numbers should be formatted for human readability.
+In most implementations the only effect is to
+change the character used for the decimal point\-\-perhaps from "."  to ",".
+The functions aren't aware of such niceties as thousands separation and
+so on. (See "The localeconv function" if you care about these things.)
+.PP
+.Vb 2
+\& use POSIX qw(strtod setlocale LC_NUMERIC);
+\& use locale;
+\&
+\& setlocale LC_NUMERIC, "";
+\&
+\& $n = 5/2;   # Assign numeric 2.5 to $n
+\&
+\& $a = " $n"; # Locale\-dependent conversion to string
+\&
+\& print "half five is $n\en";       # Locale\-dependent output
+\&
+\& printf "half five is %g\en", $n;  # Locale\-dependent output
+\&
+\& print "DECIMAL POINT IS COMMA\en"
+\&          if $n == (strtod("2,5"))[0]; # Locale\-dependent conversion
+.Ve
+.PP
+See also I18N::Langinfo and \f(CW\*(C`RADIXCHAR\*(C'\fR.
+.ie n .SS "Category ""LC_MONETARY"": Formatting of monetary amounts"
+.el .SS "Category \f(CWLC_MONETARY\fP: Formatting of monetary amounts"
+.IX Subsection "Category LC_MONETARY: Formatting of monetary amounts"
+The C standard defines the \f(CW\*(C`LC_MONETARY\*(C'\fR category, but not a function
+that is affected by its contents.  (Those with experience of standards
+committees will recognize that the working group decided to punt on the
+issue.)  Consequently, Perl essentially takes no notice of it.  If you
+really want to use \f(CW\*(C`LC_MONETARY\*(C'\fR, you can query its contents\-\-see
+"The localeconv function"\-\-and use the information that it returns in your
+application's own formatting of currency amounts.  However, you may well
+find that the information, voluminous and complex though it may be, still
+does not quite meet your requirements: currency formatting is a hard nut
+to crack.
+.PP
+See also I18N::Langinfo and \f(CW\*(C`CRNCYSTR\*(C'\fR.
+.ie n .SS "Category ""LC_TIME"": Respresentation of time"
+.el .SS "Category \f(CWLC_TIME\fP: Respresentation of time"
+.IX Subsection "Category LC_TIME: Respresentation of time"
+Output produced by \f(CWPOSIX::strftime()\fR, which builds a formatted
+human-readable date/time string, is affected by the current \f(CW\*(C`LC_TIME\*(C'\fR
+locale.  Thus, in a French locale, the output produced by the \f(CW%B\fR
+format element (full month name) for the first month of the year would
+be "janvier".  Here's how to get a list of long month names in the
+current locale:
+.PP
+.Vb 5
+\&        use POSIX qw(strftime);
+\&        for (0..11) {
+\&            $long_month_name[$_] =
+\&                strftime("%B", 0, 0, 0, 1, $_, 96);
+\&        }
+.Ve
+.PP
+Note: \f(CW\*(C`use locale\*(C'\fR isn't needed in this example: \f(CWstrftime()\fR is a POSIX
+function which uses the standard system-supplied \f(CW\*(C`libc\*(C'\fR function that
+always obeys the current \f(CW\*(C`LC_TIME\*(C'\fR locale.
+.PP
+See also I18N::Langinfo and \f(CW\*(C`ABDAY_1\*(C'\fR..\f(CW\*(C`ABDAY_7\*(C'\fR, \f(CW\*(C`DAY_1\*(C'\fR..\f(CW\*(C`DAY_7\*(C'\fR,
+\&\f(CW\*(C`ABMON_1\*(C'\fR..\f(CW\*(C`ABMON_12\*(C'\fR, and \f(CW\*(C`ABMON_1\*(C'\fR..\f(CW\*(C`ABMON_12\*(C'\fR.
+.SS "Other categories"
+.IX Subsection "Other categories"
+The remaining locale categories are not currently used by Perl itself.
+But again note that things Perl interacts with may use these, including
+extensions outside the standard Perl distribution, and by the
+operating system and its utilities.  Note especially that the string
+value of \f(CW$!\fR and the error messages given by external utilities may
+be changed by \f(CW\*(C`LC_MESSAGES\*(C'\fR.  If you want to have portable error
+codes, use \f(CW\*(C`%!\*(C'\fR.  See Errno.
+.SH SECURITY
+.IX Header "SECURITY"
+Although the main discussion of Perl security issues can be found in
+perlsec, a discussion of Perl's locale handling would be incomplete
+if it did not draw your attention to locale-dependent security issues.
+Locales\-\-particularly on systems that allow unprivileged users to
+build their own locales\-\-are untrustworthy.  A malicious (or just plain
+broken) locale can make a locale-aware application give unexpected
+results.  Here are a few possibilities:
+.IP \(bu 4
+Regular expression checks for safe file names or mail addresses using
+\&\f(CW\*(C`\ew\*(C'\fR may be spoofed by an \f(CW\*(C`LC_CTYPE\*(C'\fR locale that claims that
+characters such as \f(CW">"\fR and \f(CW"|"\fR are alphanumeric.
+.IP \(bu 4
+String interpolation with case-mapping, as in, say, \f(CW$dest =
+"C:\eU$name.$ext"\fR, may produce dangerous results if a bogus \f(CW\*(C`LC_CTYPE\*(C'\fR
+case-mapping table is in effect.
+.IP \(bu 4
+A sneaky \f(CW\*(C`LC_COLLATE\*(C'\fR locale could result in the names of students with
+"D" grades appearing ahead of those with "A"s.
+.IP \(bu 4
+An application that takes the trouble to use information in
+\&\f(CW\*(C`LC_MONETARY\*(C'\fR may format debits as if they were credits and vice versa
+if that locale has been subverted.  Or it might make payments in US
+dollars instead of Hong Kong dollars.
+.IP \(bu 4
+The date and day names in dates formatted by \f(CWstrftime()\fR could be
+manipulated to advantage by a malicious user able to subvert the
+\&\f(CW\*(C`LC_DATE\*(C'\fR locale.  ("Look\-\-it says I wasn't in the building on
+Sunday.")
+.PP
+Such dangers are not peculiar to the locale system: any aspect of an
+application's environment which may be modified maliciously presents
+similar challenges.  Similarly, they are not specific to Perl: any
+programming language that allows you to write programs that take
+account of their environment exposes you to these issues.
+.PP
+Perl cannot protect you from all possibilities shown in the
+examples\-\-there is no substitute for your own vigilance\-\-but, when
+\&\f(CW\*(C`use locale\*(C'\fR is in effect, Perl uses the tainting mechanism (see
+perlsec) to mark string results that become locale-dependent, and
+which may be untrustworthy in consequence.
+.PP
+Note that it is possible to compile Perl without taint support,
+in which case all taint features silently do nothing.
+.PP
+Here is a summary of the tainting behavior of operators and functions
+that may be affected by the locale:
+.IP \(bu 4
+\&\fBComparison operators\fR (\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`le\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, \f(CW\*(C`gt\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR):
+.Sp
+Scalar true/false (or less/equal/greater) result is never tainted.
+.IP \(bu 4
+\&\fBCase-mapping interpolation\fR (with \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, or \f(CW\*(C`\eF\*(C'\fR)
+.Sp
+The result string containing interpolated material is tainted if
+a \f(CW\*(C`use locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect.
+.IP \(bu 4
+\&\fBMatching operator\fR (\f(CW\*(C`m//\*(C'\fR):
+.Sp
+Scalar true/false result never tainted.
+.Sp
+All subpatterns, either delivered as a list-context result or as \f(CW$1\fR
+\&\fIetc\fR., are tainted if a \f(CW\*(C`use locale\*(C'\fR form that includes
+\&\f(CW\*(C`LC_CTYPE\*(C'\fR is in effect, and the subpattern
+regular expression contains a locale-dependent construct.  These
+constructs include \f(CW\*(C`\ew\*(C'\fR (to match an alphanumeric character), \f(CW\*(C`\eW\*(C'\fR
+(non-alphanumeric character), \f(CW\*(C`\eb\*(C'\fR and \f(CW\*(C`\eB\*(C'\fR (word-boundary and
+non-boundardy, which depend on what \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eW\*(C'\fR match), \f(CW\*(C`\es\*(C'\fR
+(whitespace character), \f(CW\*(C`\eS\*(C'\fR (non whitespace character), \f(CW\*(C`\ed\*(C'\fR and
+\&\f(CW\*(C`\eD\*(C'\fR (digits and non-digits), and the POSIX character classes, such as
+\&\f(CW\*(C`[:alpha:]\*(C'\fR (see "POSIX Character Classes" in perlrecharclass).
+.Sp
+Tainting is also likely if the pattern is to be matched
+case-insensitively (via \f(CW\*(C`/i\*(C'\fR).  The exception is if all the code points
+to be matched this way are above 255 and do not have folds under Unicode
+rules to below 256.  Tainting is not done for these because Perl
+only uses Unicode rules for such code points, and those rules are the
+same no matter what the current locale.
+.Sp
+The matched-pattern variables, \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR (pre-match), \f(CW\*(C`$\*(Aq\*(C'\fR
+(post-match), and \f(CW$+\fR (last match) also are tainted.
+.IP \(bu 4
+\&\fBSubstitution operator\fR (\f(CW\*(C`s///\*(C'\fR):
+.Sp
+Has the same behavior as the match operator.  Also, the left
+operand of \f(CW\*(C`=~\*(C'\fR becomes tainted when a \f(CW\*(C`use locale\*(C'\fR
+form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect, if modified as
+a result of a substitution based on a regular
+expression match involving any of the things mentioned in the previous
+item, or of case-mapping, such as \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR,\f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, or \f(CW\*(C`\eF\*(C'\fR.
+.IP \(bu 4
+\&\fBOutput formatting functions\fR (\f(CWprintf()\fR and \f(CWwrite()\fR):
+.Sp
+Results are never tainted because otherwise even output from print,
+for example \f(CWprint(1/7)\fR, should be tainted if \f(CW\*(C`use locale\*(C'\fR is in
+effect.
+.IP \(bu 4
+\&\fBCase-mapping functions\fR (\f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR, \f(CWucfirst()\fR):
+.Sp
+Results are tainted if a \f(CW\*(C`use locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is
+in effect.
+.IP \(bu 4
+\&\fBPOSIX locale-dependent functions\fR (\f(CWlocaleconv()\fR, \f(CWstrcoll()\fR,
+\&\f(CWstrftime()\fR, \f(CWstrxfrm()\fR):
+.Sp
+Results are never tainted.
+.PP
+Three examples illustrate locale-dependent tainting.
+The first program, which ignores its locale, won't run: a value taken
+directly from the command line may not be used to name an output file
+when taint checks are enabled.
+.PP
+.Vb 2
+\&        #/usr/local/bin/perl \-T
+\&        # Run with taint checking
+\&
+\&        # Command line sanity check omitted...
+\&        $tainted_output_file = shift;
+\&
+\&        open(F, ">$tainted_output_file")
+\&            or warn "Open of $tainted_output_file failed: $!\en";
+.Ve
+.PP
+The program can be made to run by "laundering" the tainted value through
+a regular expression: the second example\-\-which still ignores locale
+information\-\-runs, creating the file named on its command line
+if it can.
+.PP
+.Vb 1
+\&        #/usr/local/bin/perl \-T
+\&
+\&        $tainted_output_file = shift;
+\&        $tainted_output_file =~ m%[\ew/]+%;
+\&        $untainted_output_file = $&;
+\&
+\&        open(F, ">$untainted_output_file")
+\&            or warn "Open of $untainted_output_file failed: $!\en";
+.Ve
+.PP
+Compare this with a similar but locale-aware program:
+.PP
+.Vb 1
+\&        #/usr/local/bin/perl \-T
+\&
+\&        $tainted_output_file = shift;
+\&        use locale;
+\&        $tainted_output_file =~ m%[\ew/]+%;
+\&        $localized_output_file = $&;
+\&
+\&        open(F, ">$localized_output_file")
+\&            or warn "Open of $localized_output_file failed: $!\en";
+.Ve
+.PP
+This third program fails to run because \f(CW$&\fR is tainted: it is the result
+of a match involving \f(CW\*(C`\ew\*(C'\fR while \f(CW\*(C`use locale\*(C'\fR is in effect.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+.IP PERL_SKIP_LOCALE_INIT 12
+.IX Item "PERL_SKIP_LOCALE_INIT"
+This environment variable, available starting in Perl v5.20, if set
+(to any value), tells Perl to not use the rest of the
+environment variables to initialize with.  Instead, Perl uses whatever
+the current locale settings are.  This is particularly useful in
+embedded environments, see
+"Using embedded Perl with POSIX locales" in perlembed.
+.IP PERL_BADLANG 12
+.IX Item "PERL_BADLANG"
+A string that can suppress Perl's warning about failed locale settings
+at startup.  Failure can occur if the locale support in the operating
+system is lacking (broken) in some way\-\-or if you mistyped the name of
+a locale when you set up your environment.  If this environment
+variable is absent, or has a value other than "0" or "", Perl will
+complain about locale setting failures.
+.Sp
+\&\fBNOTE\fR: \f(CW\*(C`PERL_BADLANG\*(C'\fR only gives you a way to hide the warning message.
+The message tells about some problem in your system's locale support,
+and you should investigate what the problem is.
+.PP
+The following environment variables are not specific to Perl: They are
+part of the standardized (ISO C, XPG4, POSIX 1.c) \f(CWsetlocale()\fR method
+for controlling an application's opinion on data.  Windows is non-POSIX,
+but Perl arranges for the following to work as described anyway.
+If the locale given by an environment variable is not valid, Perl tries
+the next lower one in priority.  If none are valid, on Windows, the
+system default locale is then tried.  If all else fails, the \f(CW"C"\fR
+locale is used.  If even that doesn't work, something is badly broken,
+but Perl tries to forge ahead with whatever the locale settings might
+be.
+.ie n .IP """LC_ALL""" 12
+.el .IP \f(CWLC_ALL\fR 12
+.IX Item "LC_ALL"
+\&\f(CW\*(C`LC_ALL\*(C'\fR is the "override-all" locale environment variable. If
+set, it overrides all the rest of the locale environment variables.
+.ie n .IP """LANGUAGE""" 12
+.el .IP \f(CWLANGUAGE\fR 12
+.IX Item "LANGUAGE"
+\&\fBNOTE\fR: \f(CW\*(C`LANGUAGE\*(C'\fR is a GNU extension, it affects you only if you
+are using the GNU libc.  This is the case if you are using e.g. Linux.
+If you are using "commercial" Unixes you are most probably \fInot\fR
+using GNU libc and you can ignore \f(CW\*(C`LANGUAGE\*(C'\fR.
+.Sp
+However, in the case you are using \f(CW\*(C`LANGUAGE\*(C'\fR: it affects the
+language of informational, warning, and error messages output by
+commands (in other words, it's like \f(CW\*(C`LC_MESSAGES\*(C'\fR) but it has higher
+priority than \f(CW\*(C`LC_ALL\*(C'\fR.  Moreover, it's not a single value but
+instead a "path" (":"\-separated list) of \fIlanguages\fR (not locales).
+See the GNU \f(CW\*(C`gettext\*(C'\fR library documentation for more information.
+.ie n .IP """LC_CTYPE""" 12
+.el .IP \f(CWLC_CTYPE\fR 12
+.IX Item "LC_CTYPE"
+In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_CTYPE\*(C'\fR chooses the character type
+locale.  In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_CTYPE\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR
+chooses the character type locale.
+.ie n .IP """LC_COLLATE""" 12
+.el .IP \f(CWLC_COLLATE\fR 12
+.IX Item "LC_COLLATE"
+In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_COLLATE\*(C'\fR chooses the collation
+(sorting) locale.  In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_COLLATE\*(C'\fR,
+\&\f(CW\*(C`LANG\*(C'\fR chooses the collation locale.
+.ie n .IP """LC_MONETARY""" 12
+.el .IP \f(CWLC_MONETARY\fR 12
+.IX Item "LC_MONETARY"
+In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_MONETARY\*(C'\fR chooses the monetary
+formatting locale.  In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_MONETARY\*(C'\fR,
+\&\f(CW\*(C`LANG\*(C'\fR chooses the monetary formatting locale.
+.ie n .IP """LC_NUMERIC""" 12
+.el .IP \f(CWLC_NUMERIC\fR 12
+.IX Item "LC_NUMERIC"
+In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_NUMERIC\*(C'\fR chooses the numeric format
+locale.  In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_NUMERIC\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR
+chooses the numeric format.
+.ie n .IP """LC_TIME""" 12
+.el .IP \f(CWLC_TIME\fR 12
+.IX Item "LC_TIME"
+In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_TIME\*(C'\fR chooses the date and time
+formatting locale.  In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_TIME\*(C'\fR,
+\&\f(CW\*(C`LANG\*(C'\fR chooses the date and time formatting locale.
+.ie n .IP """LANG""" 12
+.el .IP \f(CWLANG\fR 12
+.IX Item "LANG"
+\&\f(CW\*(C`LANG\*(C'\fR is the "catch-all" locale environment variable. If it is set, it
+is used as the last resort after the overall \f(CW\*(C`LC_ALL\*(C'\fR and the
+category-specific \f(CW\*(C`LC_\fR\f(CIfoo\fR\f(CW\*(C'\fR.
+.SS Examples
+.IX Subsection "Examples"
+The \f(CW\*(C`LC_NUMERIC\*(C'\fR controls the numeric output:
+.PP
+.Vb 4
+\&   use locale;
+\&   use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
+\&   setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
+\&   printf "%g\en", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
+.Ve
+.PP
+and also how strings are parsed by \f(CWPOSIX::strtod()\fR as numbers:
+.PP
+.Vb 5
+\&   use locale;
+\&   use POSIX qw(locale_h strtod);
+\&   setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
+\&   my $x = strtod("2,34") + 5;
+\&   print $x, "\en"; # Probably shows 7,34.
+.Ve
+.SH NOTES
+.IX Header "NOTES"
+.ie n .SS "String ""eval"" and ""LC_NUMERIC"""
+.el .SS "String \f(CWeval\fP and \f(CWLC_NUMERIC\fP"
+.IX Subsection "String eval and LC_NUMERIC"
+A string eval parses its expression as standard
+Perl.  It is therefore expecting the decimal point to be a dot.  If
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR is set to have this be a comma instead, the parsing will
+be confused, perhaps silently.
+.PP
+.Vb 6
+\& use locale;
+\& use POSIX qw(locale_h);
+\& setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
+\& my $a = 1.2;
+\& print eval "$a + 1.5";
+\& print "\en";
+.Ve
+.PP
+prints \f(CW\*(C`13,5\*(C'\fR.  This is because in that locale, the comma is the
+decimal point character.  The \f(CW\*(C`eval\*(C'\fR thus expands to:
+.PP
+.Vb 1
+\& eval "1,2 + 1.5"
+.Ve
+.PP
+and the result is not what you likely expected.  No warnings are
+generated.  If you do string \f(CW\*(C`eval\*(C'\fR's within the scope of
+\&\f(CW\*(C`use\ locale\*(C'\fR, you should instead change the \f(CW\*(C`eval\*(C'\fR line to do
+something like:
+.PP
+.Vb 1
+\& print eval "no locale; $a + 1.5";
+.Ve
+.PP
+This prints \f(CW2.7\fR.
+.PP
+You could also exclude \f(CW\*(C`LC_NUMERIC\*(C'\fR, if you don't need it, by
+.PP
+.Vb 1
+\& use locale \*(Aq:!numeric\*(Aq;
+.Ve
+.SS "Backward compatibility"
+.IX Subsection "Backward compatibility"
+Versions of Perl prior to 5.004 \fBmostly\fR ignored locale information,
+generally behaving as if something similar to the \f(CW"C"\fR locale were
+always in force, even if the program environment suggested otherwise
+(see "The setlocale function").  By default, Perl still behaves this
+way for backward compatibility.  If you want a Perl application to pay
+attention to locale information, you \fBmust\fR use the \f(CW\*(C`use\ locale\*(C'\fR
+pragma (see "The "use locale" pragma") or, in the unlikely event
+that you want to do so for just pattern matching, the
+\&\f(CW\*(C`/l\*(C'\fR regular expression modifier (see "Character set
+modifiers" in perlre) to instruct it to do so.
+.PP
+Versions of Perl from 5.002 to 5.003 did use the \f(CW\*(C`LC_CTYPE\*(C'\fR
+information if available; that is, \f(CW\*(C`\ew\*(C'\fR did understand what
+were the letters according to the locale environment variables.
+The problem was that the user had no control over the feature:
+if the C library supported locales, Perl used them.
+.SS "I18N:Collate obsolete"
+.IX Subsection "I18N:Collate obsolete"
+In versions of Perl prior to 5.004, per-locale collation was possible
+using the \f(CW\*(C`I18N::Collate\*(C'\fR library module.  This module is now mildly
+obsolete and should be avoided in new applications.  The \f(CW\*(C`LC_COLLATE\*(C'\fR
+functionality is now integrated into the Perl core language: One can
+use locale-specific scalar data completely normally with \f(CW\*(C`use locale\*(C'\fR,
+so there is no longer any need to juggle with the scalar references of
+\&\f(CW\*(C`I18N::Collate\*(C'\fR.
+.SS "Sort speed and memory use impacts"
+.IX Subsection "Sort speed and memory use impacts"
+Comparing and sorting by locale is usually slower than the default
+sorting; slow-downs of two to four times have been observed.  It will
+also consume more memory: once a Perl scalar variable has participated
+in any string comparison or sorting operation obeying the locale
+collation rules, it will take 3\-15 times more memory than before.  (The
+exact multiplier depends on the string's contents, the operating system
+and the locale.) These downsides are dictated more by the operating
+system's implementation of the locale system than by Perl.
+.SS "Freely available locale definitions"
+.IX Subsection "Freely available locale definitions"
+The Unicode CLDR project extracts the POSIX portion of many of its
+locales, available at
+.PP
+.Vb 1
+\&  https://unicode.org/Public/cldr/2.0.1/
+.Ve
+.PP
+(Newer versions of CLDR require you to compute the POSIX data yourself.
+See <http://unicode.org/Public/cldr/latest/>.)
+.PP
+There is a large collection of locale definitions at:
+.PP
+.Vb 1
+\&  http://std.dkuug.dk/i18n/WG15\-collection/locales/
+.Ve
+.PP
+You should be aware that it is
+unsupported, and is not claimed to be fit for any purpose.  If your
+system allows installation of arbitrary locales, you may find the
+definitions useful as they are, or as a basis for the development of
+your own locales.
+.SS "I18n and l10n"
+.IX Subsection "I18n and l10n"
+"Internationalization" is often abbreviated as \fBi18n\fR because its first
+and last letters are separated by eighteen others.  (You may guess why
+the internalin ... internaliti ... i18n tends to get abbreviated.)  In
+the same way, "localization" is often abbreviated to \fBl10n\fR.
+.SS "An imperfect standard"
+.IX Subsection "An imperfect standard"
+Internationalization, as defined in the C and POSIX standards, can be
+criticized as incomplete and ungainly.  They also have a tendency, like
+standards groups, to divide the world into nations, when we all know
+that the world can equally well be divided into bankers, bikers, gamers,
+and so on.
+.SH "Unicode and UTF\-8"
+.IX Header "Unicode and UTF-8"
+The support of Unicode is new starting from Perl version v5.6, and more fully
+implemented in versions v5.8 and later.  See perluniintro.
+.PP
+Starting in Perl v5.20, UTF\-8 locales are supported in Perl, except
+\&\f(CW\*(C`LC_COLLATE\*(C'\fR is only partially supported; collation support is improved
+in Perl v5.26 to a level that may be sufficient for your needs
+(see "Category \f(CW\*(C`LC_COLLATE\*(C'\fR: Collation: Text Comparisons and Sorting").
+.PP
+If you have Perl v5.16 or v5.18 and can't upgrade, you can use
+.PP
+.Vb 1
+\&    use locale \*(Aq:not_characters\*(Aq;
+.Ve
+.PP
+When this form of the pragma is used, only the non-character portions of
+locales are used by Perl, for example \f(CW\*(C`LC_NUMERIC\*(C'\fR.  Perl assumes that
+you have translated all the characters it is to operate on into Unicode
+(actually the platform's native character set (ASCII or EBCDIC) plus
+Unicode).  For data in files, this can conveniently be done by also
+specifying
+.PP
+.Vb 1
+\&    use open \*(Aq:locale\*(Aq;
+.Ve
+.PP
+This pragma arranges for all inputs from files to be translated into
+Unicode from the current locale as specified in the environment (see
+"ENVIRONMENT"), and all outputs to files to be translated back
+into the locale.  (See open).  On a per-filehandle basis, you can
+instead use the PerlIO::locale module, or the Encode::Locale
+module, both available from CPAN.  The latter module also has methods to
+ease the handling of \f(CW\*(C`ARGV\*(C'\fR and environment variables, and can be used
+on individual strings.  If you know that all your locales will be
+UTF\-8, as many are these days, you can use the
+\&\fB\-C\fR command line switch.
+.PP
+This form of the pragma allows essentially seamless handling of locales
+with Unicode.  The collation order will be by Unicode code point order.
+Unicode::Collate can be used to get Unicode rules collation.
+.PP
+All the modules and switches just described can be used in v5.20 with
+just plain \f(CW\*(C`use locale\*(C'\fR, and, should the input locales not be UTF\-8,
+you'll get the less than ideal behavior, described below, that you get
+with pre\-v5.16 Perls, or when you use the locale pragma without the
+\&\f(CW\*(C`:not_characters\*(C'\fR parameter in v5.16 and v5.18.  If you are using
+exclusively UTF\-8 locales in v5.20 and higher, the rest of this section
+does not apply to you.
+.PP
+There are two cases, multi-byte and single-byte locales.  First
+multi-byte:
+.PP
+The only multi-byte (or wide character) locale that Perl is ever likely
+to support is UTF\-8.  This is due to the difficulty of implementation,
+the fact that high quality UTF\-8 locales are now published for every
+area of the world (<https://unicode.org/Public/cldr/2.0.1/> for
+ones that are already set-up, but from an earlier version;
+<https://unicode.org/Public/cldr/latest/> for the most up-to-date, but
+you have to extract the POSIX information yourself), and
+failing all that, you can use the Encode module to translate to/from
+your locale.  So, you'll have to do one of those things if you're using
+one of these locales, such as Big5 or Shift JIS.  For UTF\-8 locales, in
+Perls (pre v5.20) that don't have full UTF\-8 locale support, they may
+work reasonably well (depending on your C library implementation)
+simply because both
+they and Perl store characters that take up multiple bytes the same way.
+However, some, if not most, C library implementations may not process
+the characters in the upper half of the Latin\-1 range (128 \- 255)
+properly under \f(CW\*(C`LC_CTYPE\*(C'\fR.  To see if a character is a particular type
+under a locale, Perl uses the functions like \f(CWisalnum()\fR.  Your C
+library may not work for UTF\-8 locales with those functions, instead
+only working under the newer wide library functions like \f(CWiswalnum()\fR,
+which Perl does not use.
+These multi-byte locales are treated like single-byte locales, and will
+have the restrictions described below.  Starting in Perl v5.22 a warning
+message is raised when Perl detects a multi-byte locale that it doesn't
+fully support.
+.PP
+For single-byte locales,
+Perl generally takes the tack to use locale rules on code points that can fit
+in a single byte, and Unicode rules for those that can't (though this
+isn't uniformly applied, see the note at the end of this section).  This
+prevents many problems in locales that aren't UTF\-8.  Suppose the locale
+is ISO8859\-7, Greek.  The character at 0xD7 there is a capital Chi. But
+in the ISO8859\-1 locale, Latin1, it is a multiplication sign.  The POSIX
+regular expression character class \f(CW\*(C`[[:alpha:]]\*(C'\fR will magically match
+0xD7 in the Greek locale but not in the Latin one.
+.PP
+However, there are places where this breaks down.  Certain Perl constructs are
+for Unicode only, such as \f(CW\*(C`\ep{Alpha}\*(C'\fR.  They assume that 0xD7 always has its
+Unicode meaning (or the equivalent on EBCDIC platforms).  Since Latin1 is a
+subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and
+Unicode, \f(CW\*(C`\ep{Alpha}\*(C'\fR will never match it, regardless of locale.  A similar
+issue occurs with \f(CW\*(C`\eN{...}\*(C'\fR.  Prior to v5.20, it is therefore a bad
+idea to use \f(CW\*(C`\ep{}\*(C'\fR or
+\&\f(CW\*(C`\eN{}\*(C'\fR under plain \f(CW\*(C`use locale\*(C'\fR\-\-\fIunless\fR you can guarantee that the
+locale will be ISO8859\-1.  Use POSIX character classes instead.
+.PP
+Another problem with this approach is that operations that cross the
+single byte/multiple byte boundary are not well-defined, and so are
+disallowed.  (This boundary is between the codepoints at 255/256.)
+For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
+should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF).  But in the
+Greek locale, for example, there is no character at 0xFF, and Perl
+has no way of knowing what the character at 0xFF is really supposed to
+represent.  Thus it disallows the operation.  In this mode, the
+lowercase of U+0178 is itself.
+.PP
+The same problems ensue if you enable automatic UTF\-8\-ification of your
+standard file handles, default \f(CWopen()\fR layer, and \f(CW@ARGV\fR on non\-ISO8859\-1,
+non\-UTF\-8 locales (by using either the \fB\-C\fR command line switch or the
+\&\f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable; see
+perlrun).
+Things are read in as UTF\-8, which would normally imply a Unicode
+interpretation, but the presence of a locale causes them to be interpreted
+in that locale instead.  For example, a 0xD7 code point in the Unicode
+input, which should mean the multiplication sign, won't be interpreted by
+Perl that way under the Greek locale.  This is not a problem
+\&\fIprovided\fR you make certain that all locales will always and only be either
+an ISO8859\-1, or, if you don't have a deficient C library, a UTF\-8 locale.
+.PP
+Still another problem is that this approach can lead to two code
+points meaning the same character.  Thus in a Greek locale, both U+03A7
+and U+00D7 are GREEK CAPITAL LETTER CHI.
+.PP
+Because of all these problems, starting in v5.22, Perl will raise a
+warning if a multi-byte (hence Unicode) code point is used when a
+single-byte locale is in effect.  (Although it doesn't check for this if
+doing so would unreasonably slow execution down.)
+.PP
+Vendor locales are notoriously buggy, and it is difficult for Perl to test
+its locale-handling code because this interacts with code that Perl has no
+control over; therefore the locale-handling code in Perl may be buggy as
+well.  (However, the Unicode-supplied locales should be better, and
+there is a feed back mechanism to correct any problems.  See
+"Freely available locale definitions".)
+.PP
+If you have Perl v5.16, the problems mentioned above go away if you use
+the \f(CW\*(C`:not_characters\*(C'\fR parameter to the locale pragma (except for vendor
+bugs in the non-character portions).  If you don't have v5.16, and you
+\&\fIdo\fR have locales that work, using them may be worthwhile for certain
+specific purposes, as long as you keep in mind the gotchas already
+mentioned.  For example, if the collation for your locales works, it
+runs faster under locales than under Unicode::Collate; and you gain
+access to such things as the local currency symbol and the names of the
+months and days of the week.  (But to hammer home the point, in v5.16,
+you get this access without the downsides of locales by using the
+\&\f(CW\*(C`:not_characters\*(C'\fR form of the pragma.)
+.PP
+Note: The policy of using locale rules for code points that can fit in a
+byte, and Unicode rules for those that can't is not uniformly applied.
+Pre\-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
+consistently to regular expression matching except for bracketed
+character classes; in v5.14 it was extended to all regex matches; and in
+v5.16 to the casing operations such as \f(CW\*(C`\eL\*(C'\fR and \f(CWuc()\fR.  For
+collation, in all releases so far, the system's \f(CWstrxfrm()\fR function is
+called, and whatever it does is what you get.  Starting in v5.26, various
+bugs are fixed with the way perl uses this function.
+.SH BUGS
+.IX Header "BUGS"
+.ie n .SS "Collation of strings containing embedded ""NUL"" characters"
+.el .SS "Collation of strings containing embedded \f(CWNUL\fP characters"
+.IX Subsection "Collation of strings containing embedded NUL characters"
+\&\f(CW\*(C`NUL\*(C'\fR characters will sort the same as the lowest collating control
+character does, or to \f(CW"\e001"\fR in the unlikely event that there are no
+control characters at all in the locale.  In cases where the strings
+don't contain this non\-\f(CW\*(C`NUL\*(C'\fR control, the results will be correct, and
+in many locales, this control, whatever it might be, will rarely be
+encountered.  But there are cases where a \f(CW\*(C`NUL\*(C'\fR should sort before this
+control, but doesn't.  If two strings do collate identically, the one
+containing the \f(CW\*(C`NUL\*(C'\fR will sort to earlier.  Prior to 5.26, there were
+more bugs.
+.SS Multi-threaded
+.IX Subsection "Multi-threaded"
+XS code or C\-language libraries called from it that use the system
+\&\f(CWsetlocale(3)\fR function (except on Windows) likely will not work
+from a multi-threaded application without changes.  See
+"Locale-aware XS code" in perlxs.
+.PP
+An XS module that is locale-dependent could have been written under the
+assumption that it will never be called in a multi-threaded environment,
+and so uses other non-locale constructs that aren't multi-thread-safe.
+See "Thread-aware system interfaces" in perlxs.
+.PP
+POSIX does not define a way to get the name of the current per-thread
+locale.  Some systems, such as Darwin and FreeBSD do implement a
+function, \fBquerylocale\fR\|(3) to do this.  On non-Windows systems without
+it, such as Linux, there are some additional caveats:
+.IP \(bu 4
+An embedded perl needs to be started up while the global locale is in
+effect.  See "Using embedded Perl with POSIX locales" in perlembed.
+.IP \(bu 4
+It becomes more important for perl to know about all the possible
+locale categories on the platform, even if they aren't apparently used
+in your program.  Perl knows all of the Linux ones.  If your platform
+has others, you can submit an issue at
+<https://github.com/Perl/perl5/issues> for
+inclusion of it in the next release.  In the meantime, it is possible to
+edit the Perl source to teach it about the category, and then recompile.
+Search for instances of, say, \f(CW\*(C`LC_PAPER\*(C'\fR in the source, and use that as
+a template to add the omitted one.
+.IP \(bu 4
+It is possible, though hard to do, to call \f(CW\*(C`POSIX::setlocale\*(C'\fR with a
+locale that it doesn't recognize as syntactically legal, but actually is
+legal on that system.  This should happen only with embedded perls, or
+if you hand-craft a locale name yourself.
+.SS "Broken systems"
+.IX Subsection "Broken systems"
+In certain systems, the operating system's locale support
+is broken and cannot be fixed or used by Perl.  Such deficiencies can
+and will result in mysterious hangs and/or Perl core dumps when
+\&\f(CW\*(C`use locale\*(C'\fR is in effect.  When confronted with such a system,
+please report in excruciating detail to
+<<https://github.com/Perl/perl5/issues>>, and
+also contact your vendor: bug fixes may exist for these problems
+in your operating system.  Sometimes such bug fixes are called an
+operating system upgrade.  If you have the source for Perl, include in
+the bug report the output of the test described above in "Testing
+for broken locales".
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+I18N::Langinfo, perluniintro, perlunicode, open,
+"localeconv" in POSIX,
+"setlocale" in POSIX, "strcoll" in POSIX, "strftime" in POSIX,
+"strtod" in POSIX, "strxfrm" in POSIX.
+.PP
+For special considerations when Perl is embedded in a C program,
+see "Using embedded Perl with POSIX locales" in perlembed.
+.SH HISTORY
+.IX Header "HISTORY"
+Jarkko Hietaniemi's original \fIperli18n.pod\fR heavily hacked by Dominic
+Dunlop, assisted by the perl5\-porters.  Prose worked over a bit by
+Tom Christiansen, and now maintained by Perl 5 porters.
diff --git a/upstream/mageia-cauldron/man1/perllol.1 b/upstream/mageia-cauldron/man1/perllol.1
new file mode 100644
index 00000000..5a441c66
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perllol.1
@@ -0,0 +1,464 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLLOL 1"
+.TH PERLLOL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perllol \- Manipulating Arrays of Arrays in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Declaration and Access of Arrays of Arrays"
+.IX Subsection "Declaration and Access of Arrays of Arrays"
+The simplest two-level data structure to build in Perl is an array of
+arrays, sometimes casually called a list of lists.  It's reasonably easy to
+understand, and almost everything that applies here will also be applicable
+later on with the fancier data structures.
+.PP
+An array of an array is just a regular old array \f(CW@AoA\fR that you can
+get at with two subscripts, like \f(CW\*(C`$AoA[3][2]\*(C'\fR.  Here's a declaration
+of the array:
+.PP
+.Vb 1
+\&    use v5.10;  # so we can use say()
+\&
+\&    # assign to our array, an array of array references
+\&    @AoA = (
+\&           [ "fred", "barney", "pebbles", "bambam", "dino", ],
+\&           [ "george", "jane", "elroy", "judy", ],
+\&           [ "homer", "bart", "marge", "maggie", ],
+\&    );
+\&    say $AoA[2][1];
+\&  bart
+.Ve
+.PP
+Now you should be very careful that the outer bracket type
+is a round one, that is, a parenthesis.  That's because you're assigning to
+an \f(CW@array\fR, so you need parentheses.  If you wanted there \fInot\fR to be an \f(CW@AoA\fR,
+but rather just a reference to it, you could do something more like this:
+.PP
+.Vb 8
+\&    # assign a reference to array of array references
+\&    $ref_to_AoA = [
+\&        [ "fred", "barney", "pebbles", "bambam", "dino", ],
+\&        [ "george", "jane", "elroy", "judy", ],
+\&        [ "homer", "bart", "marge", "maggie", ],
+\&    ];
+\&    say $ref_to_AoA\->[2][1];
+\&  bart
+.Ve
+.PP
+Notice that the outer bracket type has changed, and so our access syntax
+has also changed.  That's because unlike C, in perl you can't freely
+interchange arrays and references thereto.  \f(CW$ref_to_AoA\fR is a reference to an
+array, whereas \f(CW@AoA\fR is an array proper.  Likewise, \f(CW$AoA[2]\fR is not an
+array, but an array ref.  So how come you can write these:
+.PP
+.Vb 2
+\&    $AoA[2][2]
+\&    $ref_to_AoA\->[2][2]
+.Ve
+.PP
+instead of having to write these:
+.PP
+.Vb 2
+\&    $AoA[2]\->[2]
+\&    $ref_to_AoA\->[2]\->[2]
+.Ve
+.PP
+Well, that's because the rule is that on adjacent brackets only (whether
+square or curly), you are free to omit the pointer dereferencing arrow.
+But you cannot do so for the very first one if it's a scalar containing
+a reference, which means that \f(CW$ref_to_AoA\fR always needs it.
+.SS "Growing Your Own"
+.IX Subsection "Growing Your Own"
+That's all well and good for declaration of a fixed data structure,
+but what if you wanted to add new elements on the fly, or build
+it up entirely from scratch?
+.PP
+First, let's look at reading it in from a file.  This is something like
+adding a row at a time.  We'll assume that there's a flat file in which
+each line is a row and each word an element.  If you're trying to develop an
+\&\f(CW@AoA\fR array containing all these, here's the right way to do that:
+.PP
+.Vb 4
+\&    while (<>) {
+\&        @tmp = split;
+\&        push @AoA, [ @tmp ];
+\&    }
+.Ve
+.PP
+You might also have loaded that from a function:
+.PP
+.Vb 3
+\&    for $i ( 1 .. 10 ) {
+\&        $AoA[$i] = [ somefunc($i) ];
+\&    }
+.Ve
+.PP
+Or you might have had a temporary variable sitting around with the
+array in it.
+.PP
+.Vb 4
+\&    for $i ( 1 .. 10 ) {
+\&        @tmp = somefunc($i);
+\&        $AoA[$i] = [ @tmp ];
+\&    }
+.Ve
+.PP
+It's important you make sure to use the \f(CW\*(C`[ ]\*(C'\fR array reference
+constructor.  That's because this wouldn't work:
+.PP
+.Vb 1
+\&    $AoA[$i] = @tmp;   # WRONG!
+.Ve
+.PP
+The reason that doesn't do what you want is because assigning a
+named array like that to a scalar is taking an array in scalar
+context, which means just counts the number of elements in \f(CW@tmp\fR.
+.PP
+If you are running under \f(CW\*(C`use strict\*(C'\fR (and if you aren't, why in
+the world aren't you?), you'll have to add some declarations to
+make it happy:
+.PP
+.Vb 6
+\&    use strict;
+\&    my(@AoA, @tmp);
+\&    while (<>) {
+\&        @tmp = split;
+\&        push @AoA, [ @tmp ];
+\&    }
+.Ve
+.PP
+Of course, you don't need the temporary array to have a name at all:
+.PP
+.Vb 3
+\&    while (<>) {
+\&        push @AoA, [ split ];
+\&    }
+.Ve
+.PP
+You also don't have to use \fBpush()\fR.  You could just make a direct assignment
+if you knew where you wanted to put it:
+.PP
+.Vb 5
+\&    my (@AoA, $i, $line);
+\&    for $i ( 0 .. 10 ) {
+\&        $line = <>;
+\&        $AoA[$i] = [ split " ", $line ];
+\&    }
+.Ve
+.PP
+or even just
+.PP
+.Vb 4
+\&    my (@AoA, $i);
+\&    for $i ( 0 .. 10 ) {
+\&        $AoA[$i] = [ split " ", <> ];
+\&    }
+.Ve
+.PP
+You should in general be leery of using functions that could
+potentially return lists in scalar context without explicitly stating
+such.  This would be clearer to the casual reader:
+.PP
+.Vb 4
+\&    my (@AoA, $i);
+\&    for $i ( 0 .. 10 ) {
+\&        $AoA[$i] = [ split " ", scalar(<>) ];
+\&    }
+.Ve
+.PP
+If you wanted to have a \f(CW$ref_to_AoA\fR variable as a reference to an array,
+you'd have to do something like this:
+.PP
+.Vb 3
+\&    while (<>) {
+\&        push @$ref_to_AoA, [ split ];
+\&    }
+.Ve
+.PP
+Now you can add new rows.  What about adding new columns?  If you're
+dealing with just matrices, it's often easiest to use simple assignment:
+.PP
+.Vb 5
+\&    for $x (1 .. 10) {
+\&        for $y (1 .. 10) {
+\&            $AoA[$x][$y] = func($x, $y);
+\&        }
+\&    }
+\&
+\&    for $x ( 3, 7, 9 ) {
+\&        $AoA[$x][20] += func2($x);
+\&    }
+.Ve
+.PP
+It doesn't matter whether those elements are already
+there or not: it'll gladly create them for you, setting
+intervening elements to \f(CW\*(C`undef\*(C'\fR as need be.
+.PP
+If you wanted just to append to a row, you'd have
+to do something a bit funnier looking:
+.PP
+.Vb 2
+\&    # add new columns to an existing row
+\&    push $AoA[0]\->@*, "wilma", "betty";   # explicit deref
+.Ve
+.SS "Access and Printing"
+.IX Subsection "Access and Printing"
+Now it's time to print your data structure out.  How
+are you going to do that?  Well, if you want only one
+of the elements, it's trivial:
+.PP
+.Vb 1
+\&    print $AoA[0][0];
+.Ve
+.PP
+If you want to print the whole thing, though, you can't
+say
+.PP
+.Vb 1
+\&    print @AoA;         # WRONG
+.Ve
+.PP
+because you'll get just references listed, and perl will never
+automatically dereference things for you.  Instead, you have to
+roll yourself a loop or two.  This prints the whole structure,
+using the shell-style \fBfor()\fR construct to loop across the outer
+set of subscripts.
+.PP
+.Vb 3
+\&    for $aref ( @AoA ) {
+\&        say "\et [ @$aref ],";
+\&    }
+.Ve
+.PP
+If you wanted to keep track of subscripts, you might do this:
+.PP
+.Vb 3
+\&    for $i ( 0 .. $#AoA ) {
+\&        say "\et elt $i is [ @{$AoA[$i]} ],";
+\&    }
+.Ve
+.PP
+or maybe even this.  Notice the inner loop.
+.PP
+.Vb 5
+\&    for $i ( 0 .. $#AoA ) {
+\&        for $j ( 0 .. $#{$AoA[$i]} ) {
+\&            say "elt $i $j is $AoA[$i][$j]";
+\&        }
+\&    }
+.Ve
+.PP
+As you can see, it's getting a bit complicated.  That's why
+sometimes is easier to take a temporary on your way through:
+.PP
+.Vb 6
+\&    for $i ( 0 .. $#AoA ) {
+\&        $aref = $AoA[$i];
+\&        for $j ( 0 .. $#{$aref} ) {
+\&            say "elt $i $j is $AoA[$i][$j]";
+\&        }
+\&    }
+.Ve
+.PP
+Hmm... that's still a bit ugly.  How about this:
+.PP
+.Vb 7
+\&    for $i ( 0 .. $#AoA ) {
+\&        $aref = $AoA[$i];
+\&        $n = @$aref \- 1;
+\&        for $j ( 0 .. $n ) {
+\&            say "elt $i $j is $AoA[$i][$j]";
+\&        }
+\&    }
+.Ve
+.PP
+When you get tired of writing a custom print for your data structures,
+you might look at the standard Dumpvalue or Data::Dumper modules.
+The former is what the Perl debugger uses, while the latter generates
+parsable Perl code.  For example:
+.PP
+.Vb 1
+\& use v5.14;     # using the + prototype, new to v5.14
+\&
+\& sub show(+) {
+\&        require Dumpvalue;
+\&        state $prettily = new Dumpvalue::
+\&                            tick        => q("),
+\&                            compactDump => 1,  # comment these two lines
+\&                                               # out
+\&                            veryCompact => 1,  # if you want a bigger
+\&                                               # dump
+\&                        ;
+\&        dumpValue $prettily @_;
+\& }
+\&
+\& # Assign a list of array references to an array.
+\& my @AoA = (
+\&           [ "fred", "barney" ],
+\&           [ "george", "jane", "elroy" ],
+\&           [ "homer", "marge", "bart" ],
+\& );
+\& push $AoA[0]\->@*, "wilma", "betty";
+\& show @AoA;
+.Ve
+.PP
+will print out:
+.PP
+.Vb 3
+\&    0  0..3  "fred" "barney" "wilma" "betty"
+\&    1  0..2  "george" "jane" "elroy"
+\&    2  0..2  "homer" "marge" "bart"
+.Ve
+.PP
+Whereas if you comment out the two lines I said you might wish to,
+then it shows it to you this way instead:
+.PP
+.Vb 10
+\&    0  ARRAY(0x8031d0)
+\&       0  "fred"
+\&       1  "barney"
+\&       2  "wilma"
+\&       3  "betty"
+\&    1  ARRAY(0x803d40)
+\&       0  "george"
+\&       1  "jane"
+\&       2  "elroy"
+\&    2  ARRAY(0x803e10)
+\&       0  "homer"
+\&       1  "marge"
+\&       2  "bart"
+.Ve
+.SS Slices
+.IX Subsection "Slices"
+If you want to get at a slice (part of a row) in a multidimensional
+array, you're going to have to do some fancy subscripting.  That's
+because while we have a nice synonym for single elements via the
+pointer arrow for dereferencing, no such convenience exists for slices.
+.PP
+Here's how to do one operation using a loop.  We'll assume an \f(CW@AoA\fR
+variable as before.
+.PP
+.Vb 5
+\&    @part = ();
+\&    $x = 4;
+\&    for ($y = 7; $y < 13; $y++) {
+\&        push @part, $AoA[$x][$y];
+\&    }
+.Ve
+.PP
+That same loop could be replaced with a slice operation:
+.PP
+.Vb 1
+\&    @part = $AoA[4]\->@[ 7..12 ];
+.Ve
+.PP
+Now, what if you wanted a \fItwo-dimensional slice\fR, such as having
+\&\f(CW$x\fR run from 4..8 and \f(CW$y\fR run from 7 to 12?  Hmm... here's the simple way:
+.PP
+.Vb 6
+\&    @newAoA = ();
+\&    for ($startx = $x = 4; $x <= 8; $x++) {
+\&        for ($starty = $y = 7; $y <= 12; $y++) {
+\&            $newAoA[$x \- $startx][$y \- $starty] = $AoA[$x][$y];
+\&        }
+\&    }
+.Ve
+.PP
+We can reduce some of the looping through slices
+.PP
+.Vb 3
+\&    for ($x = 4; $x <= 8; $x++) {
+\&        push @newAoA, [ $AoA[$x]\->@[ 7..12 ] ];
+\&    }
+.Ve
+.PP
+If you were into Schwartzian Transforms, you would probably
+have selected map for that
+.PP
+.Vb 1
+\&    @newAoA = map { [ $AoA[$_]\->@[ 7..12 ] ] } 4 .. 8;
+.Ve
+.PP
+Although if your manager accused you of seeking job security (or rapid
+insecurity) through inscrutable code, it would be hard to argue. :\-)
+If I were you, I'd put that in a function:
+.PP
+.Vb 5
+\&    @newAoA = splice_2D( \e@AoA, 4 => 8, 7 => 12 );
+\&    sub splice_2D {
+\&        my $lrr = shift;        # ref to array of array refs!
+\&        my ($x_lo, $x_hi,
+\&            $y_lo, $y_hi) = @_;
+\&
+\&        return map {
+\&            [ $lrr\->[$_]\->@[ $y_lo .. $y_hi ] ]
+\&        } $x_lo .. $x_hi;
+\&    }
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perldata, perlref, perldsc
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen <\fItchrist@perl.com\fR>
+.PP
+Last update: Tue Apr 26 18:30:55 MDT 2011
diff --git a/upstream/mageia-cauldron/man1/perlmacosx.1 b/upstream/mageia-cauldron/man1/perlmacosx.1
new file mode 100644
index 00000000..6935ea1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmacosx.1
@@ -0,0 +1,337 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMACOSX 1"
+.TH PERLMACOSX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmacosx \- Perl under Mac OS X
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+This document briefly describes Perl under Mac OS X.
+.PP
+.Vb 7
+\&  curl \-O https://www.cpan.org/src/perl\-5.38.2.tar.gz
+\&  tar \-xzf perl\-5.38.2.tar.gz
+\&  cd perl\-5.38.2
+\&  ./Configure \-des \-Dprefix=/usr/local/
+\&  make
+\&  make test
+\&  sudo make install
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The latest Perl release (5.38.2 as of this writing) builds without changes
+under all versions of Mac OS X from 10.3 "Panther" onwards.
+.PP
+In order to build your own version of Perl you will need 'make',
+which is part of Apple's developer tools \- also known as Xcode. From
+Mac OS X 10.7 "Lion" onwards, it can be downloaded separately as the
+\&'Command Line Tools' bundle directly from <https://developer.apple.com/downloads/>
+(you will need a free account to log in), or as a part of the Xcode suite,
+freely available at the App Store. Xcode is a pretty big app, so
+unless you already have it or really want it, you are advised to get the
+\&'Command Line Tools' bundle separately from the link above. If you want
+to do it from within Xcode, go to Xcode \-> Preferences \-> Downloads and
+select the 'Command Line Tools' option.
+.PP
+Between Mac OS X 10.3 "Panther" and 10.6 "Snow Leopard", the 'Command
+Line Tools' bundle was called 'unix tools', and was usually supplied
+with Mac OS install DVDs.
+.PP
+Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a
+completely thread-safe libc, so threading is not fully supported. Also,
+earlier releases included a buggy libdb, so some of the DB_File tests
+are known to fail on those releases.
+.SS "Installation Prefix"
+.IX Subsection "Installation Prefix"
+The default installation location for this release uses the traditional
+UNIX directory layout under /usr/local. This is the recommended location
+for most users, and will leave the Apple-supplied Perl and its modules
+undisturbed.
+.PP
+Using an installation prefix of '/usr' will result in a directory layout
+that mirrors that of Apple's default Perl, with core modules stored in
+\&'/System/Library/Perl/${version}', CPAN modules stored in
+\&'/Library/Perl/${version}', and the addition of
+\&'/Network/Library/Perl/${version}' to \f(CW@INC\fR for modules that are stored
+on a file server and used by many Macs.
+.SS "SDK support"
+.IX Subsection "SDK support"
+First, export the path to the SDK into the build environment:
+.PP
+.Vb 1
+\& export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk
+.Ve
+.PP
+Please make sure the SDK version (i.e. the numbers right before '.sdk')
+matches your system's (in this case, Mac OS X 10.8 "Mountain Lion"), as it is
+possible to have more than one SDK installed. Also make sure the path exists
+in your system, and if it doesn't please make sure the SDK is properly
+installed, as it should come with the 'Command Line Tools' bundle mentioned
+above. Finally, if you have an older Mac OS X (10.6 "Snow Leopard" and below)
+running Xcode 4.2 or lower, the SDK path might be something like
+\&\f(CW\*(Aq/Developer/SDKs/MacOSX10.3.9.sdk\*(Aq\fR.
+.PP
+You can use the SDK by exporting some additions to Perl's 'ccflags' and '..flags'
+config variables:
+.PP
+.Vb 5
+\&    ./Configure \-Accflags="\-nostdinc \-B$SDK/usr/include/gcc \e
+\&                           \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include \e
+\&                           \-F$SDK/System/Library/Frameworks" \e
+\&                \-Aldflags="\-Wl,\-syslibroot,$SDK" \e
+\&                \-de
+.Ve
+.SS "Universal Binary support"
+.IX Subsection "Universal Binary support"
+Note: From Mac OS X 10.6 "Snow Leopard" onwards, Apple only supports
+Intel-based hardware. This means you can safely skip this section unless
+you have an older Apple computer running on ppc or wish to create a perl
+binary with backwards compatibility.
+.PP
+You can compile perl as a universal binary (built for both ppc and intel).
+In Mac OS X 10.4 "Tiger", you must export the 'u' variant of the SDK:
+.PP
+.Vb 1
+\&    export SDK=/Developer/SDKs/MacOSX10.4u.sdk
+.Ve
+.PP
+Mac OS X 10.5 "Leopard" and above do not require the 'u' variant.
+.PP
+In addition to the compiler flags used to select the SDK, also add the flags
+for creating a universal binary:
+.PP
+.Vb 6
+\& ./Configure \-Accflags="\-arch i686 \-arch ppc \-nostdinc               \e
+\&                         \-B$SDK/usr/include/gcc                      \e
+\&                        \-B$SDK/usr/lib/gcc \-isystem$SDK/usr/include  \e
+\&                        \-F$SDK/System/Library/Frameworks"            \e
+\&             \-Aldflags="\-arch i686 \-arch ppc \-Wl,\-syslibroot,$SDK"   \e
+\&             \-de
+.Ve
+.PP
+Keep in mind that these compiler and linker settings will also be used when
+building CPAN modules. For XS modules to be compiled as a universal binary, any
+libraries it links to must also be universal binaries. The system libraries that
+Apple includes with the 10.4u SDK are all universal, but user-installed libraries
+may need to be re-installed as universal binaries.
+.SS "64\-bit PPC support"
+.IX Subsection "64-bit PPC support"
+Follow the instructions in \fIINSTALL\fR to build perl with support for 64\-bit 
+integers (\f(CW\*(C`use64bitint\*(C'\fR) or both 64\-bit integers and 64\-bit addressing
+(\f(CW\*(C`use64bitall\*(C'\fR). In the latter case, the resulting binary will run only
+on G5\-based hosts.
+.PP
+Support for 64\-bit addressing is experimental: some aspects of Perl may be
+omitted or buggy. Note the messages output by \fIConfigure\fR for further 
+information. Please use <https://github.com/Perl/perl5/issues> to submit a
+problem report in the event that you encounter difficulties.
+.PP
+When building 64\-bit modules, it is your responsibility to ensure that linked
+external libraries and frameworks provide 64\-bit support: if they do not,
+module building may appear to succeed, but attempts to use the module will
+result in run-time dynamic linking errors, and subsequent test failures.
+You can use \f(CW\*(C`file\*(C'\fR to discover the architectures supported by a library:
+.PP
+.Vb 4
+\&    $ file libgdbm.3.0.0.dylib 
+\&    libgdbm.3.0.0.dylib: Mach\-O fat file with 2 architectures
+\&    libgdbm.3.0.0.dylib (for architecture ppc):      Mach\-O dynamically linked shared library ppc
+\&    libgdbm.3.0.0.dylib (for architecture ppc64):    Mach\-O 64\-bit dynamically linked shared library ppc64
+.Ve
+.PP
+Note that this issue precludes the building of many Macintosh-specific CPAN
+modules (\f(CW\*(C`Mac::*\*(C'\fR), as the required Apple frameworks do not provide PPC64
+support. Similarly, downloads from Fink or Darwinports are unlikely to provide
+64\-bit support; the libraries must be rebuilt from source with the appropriate
+compiler and linker flags. For further information, see Apple's
+\&\fI64\-Bit Transition Guide\fR at
+<https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/64bitPorting/transition/transition.html>.
+.SS "libperl and Prebinding"
+.IX Subsection "libperl and Prebinding"
+Mac OS X ships with a dynamically-loaded libperl, but the default for
+this release is to compile a static libperl. The reason for this is
+pre-binding. Dynamic libraries can be pre-bound to a specific address in
+memory in order to decrease load time. To do this, one needs to be aware
+of the location and size of all previously-loaded libraries. Apple
+collects this information as part of their overall OS build process, and
+thus has easy access to it when building Perl, but ordinary users would
+need to go to a great deal of effort to obtain the information needed
+for pre-binding.
+.PP
+You can override the default and build a shared libperl if you wish
+(Configure\ ...\ \-Duseshrplib).
+.PP
+With Mac OS X 10.4 "Tiger" and newer, there is almost no performance
+penalty for non-prebound libraries. Earlier releases will suffer a greater
+load time than either the static library, or Apple's pre-bound dynamic library.
+.SS "Updating Apple's Perl"
+.IX Subsection "Updating Apple's Perl"
+In a word \- don't, at least not without a *very* good reason. Your scripts
+can just as easily begin with "#!/usr/local/bin/perl" as with
+"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
+part of installation packages and such have generally only been tested
+with the /usr/bin/perl that's installed by Apple.
+.PP
+If you find that you do need to update the system Perl, one issue worth
+keeping in mind is the question of static vs. dynamic libraries. If you
+upgrade using the default static libperl, you will find that the dynamic
+libperl supplied by Apple will not be deleted. If both libraries are
+present when an application that links against libperl is built, ld will
+link against the dynamic library by default. So, if you need to replace
+Apple's dynamic libperl with a static libperl, you need to be sure to
+delete the older dynamic library after you've installed the update.
+.SS "Known problems"
+.IX Subsection "Known problems"
+If you have installed extra libraries such as GDBM through Fink
+(in other words, you have libraries under \fI/sw/lib\fR), or libdlcompat
+to \fI/usr/local/lib\fR, you may need to be extra careful when running
+Configure to not to confuse Configure and Perl about which libraries
+to use.  Being confused will show up for example as "dyld" errors about
+symbol problems, for example during "make test". The safest bet is to run
+Configure as
+.PP
+.Vb 1
+\&    Configure ... \-Uloclibpth \-Dlibpth=/usr/lib
+.Ve
+.PP
+to make Configure look only into the system libraries.  If you have some
+extra library directories that you really want to use (such as newer
+Berkeley DB libraries in pre-Panther systems), add those to the libpth:
+.PP
+.Vb 1
+\&    Configure ... \-Uloclibpth \-Dlibpth=\*(Aq/usr/lib /opt/lib\*(Aq
+.Ve
+.PP
+The default of building Perl statically may cause problems with complex
+applications like Tk: in that case consider building shared Perl
+.PP
+.Vb 1
+\&    Configure ... \-Duseshrplib
+.Ve
+.PP
+but remember that there's a startup cost to pay in that case (see above
+"libperl and Prebinding").
+.PP
+Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
+the eu_ES locale (Basque-Spain).  In previous releases of Perl, this resulted in
+failures in the \fIlib/locale\fR test. These failures have been suppressed
+in the current release of Perl by making the test ignore the broken locale.
+If you need to use the eu_ES locale, you should contact Apple support.
+.SS Cocoa
+.IX Subsection "Cocoa"
+There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
+module, included with Mac OS X, can be used by standalone scripts to
+access Foundation (i.e. non-GUI) classes and objects.
+.PP
+An alternative is CamelBones, a framework that allows access to both
+Foundation and AppKit classes and objects, so that full GUI applications
+can be built in Perl. CamelBones can be found on SourceForge, at
+<https://www.sourceforge.net/projects/camelbones/>.
+.SH "Starting From Scratch"
+.IX Header "Starting From Scratch"
+Unfortunately it is not that difficult somehow manage to break one's
+Mac OS X Perl rather severely.  If all else fails and you want to
+really, \fBREALLY\fR, start from scratch and remove even your Apple Perl
+installation (which has become corrupted somehow), the following
+instructions should do it.  \fBPlease think twice before following
+these instructions: they are much like conducting brain surgery to
+yourself.  Without anesthesia.\fR  We will \fBnot\fR come to fix your system
+if you do this.
+.PP
+First, get rid of the libperl.dylib:
+.PP
+.Vb 2
+\&    # cd /System/Library/Perl/darwin/CORE
+\&    # rm libperl.dylib
+.Ve
+.PP
+Then delete every .bundle file found anywhere in the folders:
+.PP
+.Vb 2
+\&    /System/Library/Perl
+\&    /Library/Perl
+.Ve
+.PP
+You can find them for example by
+.PP
+.Vb 1
+\&    # find /System/Library/Perl /Library/Perl \-name \*(Aq*.bundle\*(Aq \-print
+.Ve
+.PP
+After this you can either copy Perl from your operating system media
+(you will need at least the /System/Library/Perl and /usr/bin/perl),
+or rebuild Perl from the source code with \f(CW\*(C`Configure \-Dprefix=/usr
+\&\-Duseshrplib\*(C'\fR NOTE: the \f(CW\*(C`\-Dprefix=/usr\*(C'\fR to replace the system Perl
+works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
+settings were not quite right.
+.PP
+"Pacifist" from CharlesSoft (<https://www.charlessoft.com/>) is a nice
+way to extract the Perl binaries from the OS media, without having to
+reinstall the entire OS.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This README was written by Sherm Pendley <sherm@dot\-app.org>,
+and subsequently updated by Dominic Dunlop <domo@computer.org>
+and Breno G. de Oliveira <garu@cpan.org>. The "Starting From Scratch"
+recipe was contributed by John Montbriand <montbriand@apple.com>.
+.SH DATE
+.IX Header "DATE"
+Last modified 2013\-04\-29.
diff --git a/upstream/mageia-cauldron/man1/perlmod.1 b/upstream/mageia-cauldron/man1/perlmod.1
new file mode 100644
index 00000000..b77cb631
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmod.1
@@ -0,0 +1,740 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMOD 1"
+.TH PERLMOD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmod \- Perl modules (packages and symbol tables)
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Is this the document you were after?"
+.IX Subsection "Is this the document you were after?"
+There are other documents which might contain the information that you're
+looking for:
+.IP "This doc" 2
+.IX Item "This doc"
+Perl's packages, namespaces, and some info on classes.
+.IP perlnewmod 2
+.IX Item "perlnewmod"
+Tutorial on making a new module.
+.IP perlmodstyle 2
+.IX Item "perlmodstyle"
+Best practices for making a new module.
+.SS Packages
+.IX Xref "package namespace variable, global global variable global"
+.IX Subsection "Packages"
+Unlike Perl 4, in which all the variables were dynamic and shared one
+global name space, causing maintainability problems, Perl 5 provides two
+mechanisms for protecting code from having its variables stomped on by
+other code: lexically scoped variables created with \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`state\*(C'\fR and
+namespaced global variables, which are exposed via the \f(CW\*(C`vars\*(C'\fR pragma,
+or the \f(CW\*(C`our\*(C'\fR keyword. Any global variable is considered to
+be part of a namespace and can be accessed via a "fully qualified form".
+Conversely, any lexically scoped variable is considered to be part of
+that lexical-scope, and does not have a "fully qualified form".
+.PP
+In perl namespaces are called "packages" and
+the \f(CW\*(C`package\*(C'\fR declaration tells the compiler which
+namespace to prefix to \f(CW\*(C`our\*(C'\fR variables and unqualified dynamic names.
+This both protects
+against accidental stomping and provides an interface for deliberately
+clobbering global dynamic variables declared and used in other scopes or
+packages, when that is what you want to do.
+.PP
+The scope of the \f(CW\*(C`package\*(C'\fR declaration is from the
+declaration itself through the end of the enclosing block, \f(CW\*(C`eval\*(C'\fR,
+or file, whichever comes first (the same scope as the \fBmy()\fR, \fBour()\fR, \fBstate()\fR, and
+\&\fBlocal()\fR operators, and also the effect
+of the experimental "reference aliasing," which may change), or until
+the next \f(CW\*(C`package\*(C'\fR declaration.  Unqualified dynamic identifiers will be in
+this namespace, except for those few identifiers that, if unqualified,
+default to the main package instead of the current one as described
+below.  A \f(CW\*(C`package\*(C'\fR statement affects only dynamic global
+symbols, including subroutine names, and variables you've used \fBlocal()\fR
+on, but \fInot\fR lexical variables created with \fBmy()\fR, \fBour()\fR or \fBstate()\fR.
+.PP
+Typically, a \f(CW\*(C`package\*(C'\fR statement is the first declaration in a file
+included in a program by one of the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators.  You can
+switch into a package in more than one place: \f(CW\*(C`package\*(C'\fR has no
+effect beyond specifying which symbol table the compiler will use for
+dynamic symbols for the rest of that block or until the next \f(CW\*(C`package\*(C'\fR statement.
+You can refer to variables and filehandles in other packages
+by prefixing the identifier with the package name and a double
+colon: \f(CW$Package::Variable\fR.  If the package name is null, the
+\&\f(CW\*(C`main\*(C'\fR package is assumed.  That is, \f(CW$::sail\fR is equivalent to
+\&\f(CW$main::sail\fR.
+.PP
+The old package delimiter was a single quote, but double colon is now the
+preferred delimiter, in part because it's more readable to humans, and
+in part because it's more readable to \fBemacs\fR macros.  It also makes C++
+programmers feel like they know what's going on\-\-as opposed to using the
+single quote as separator, which was there to make Ada programmers feel
+like they knew what was going on.  Because the old-fashioned syntax is still
+supported for backwards compatibility, if you try to use a string like
+\&\f(CW"This is $owner\*(Aqs house"\fR, you'll be accessing \f(CW$owner::s\fR; that is,
+the \f(CW$s\fR variable in package \f(CW\*(C`owner\*(C'\fR, which is probably not what you meant.
+Use braces to disambiguate, as in \f(CW"This is ${owner}\*(Aqs house"\fR.
+.IX Xref ":: '"
+.PP
+Using \f(CW\*(C`\*(Aq\*(C'\fR as a package separator is deprecated and will be removed in
+Perl 5.40.
+.PP
+Packages may themselves contain package separators, as in
+\&\f(CW$OUTER::INNER::var\fR.  This implies nothing about the order of
+name lookups, however.  There are no relative packages: all symbols
+are either local to the current package, or must be fully qualified
+from the outer package name down.  For instance, there is nowhere
+within package \f(CW\*(C`OUTER\*(C'\fR that \f(CW$INNER::var\fR refers to
+\&\f(CW$OUTER::INNER::var\fR.  \f(CW\*(C`INNER\*(C'\fR refers to a totally
+separate global package. The custom of treating package names as a
+hierarchy is very strong, but the language in no way enforces it.
+.PP
+Only identifiers starting with letters (or underscore) are stored
+in a package's symbol table.  All other symbols are kept in package
+\&\f(CW\*(C`main\*(C'\fR, including all punctuation variables, like \f(CW$_\fR.  In addition,
+when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
+ARGVOUT, ENV, INC, and SIG are forced to be in package \f(CW\*(C`main\*(C'\fR,
+even when used for other purposes than their built-in ones.  If you
+have a package called \f(CW\*(C`m\*(C'\fR, \f(CW\*(C`s\*(C'\fR, or \f(CW\*(C`y\*(C'\fR, then you can't use the
+qualified form of an identifier because it would be instead interpreted
+as a pattern match, a substitution, or a transliteration.
+.IX Xref "variable, punctuation"
+.PP
+Variables beginning with underscore used to be forced into package
+main, but we decided it was more useful for package writers to be able
+to use leading underscore to indicate private variables and method names.
+However, variables and functions named with a single \f(CW\*(C`_\*(C'\fR, such as
+\&\f(CW$_\fR and \f(CW\*(C`sub _\*(C'\fR, are still forced into the package \f(CW\*(C`main\*(C'\fR.  See also
+"The Syntax of Variable Names" in perlvar.
+.PP
+\&\f(CW\*(C`eval\*(C'\fRed strings are compiled in the package in which the \fBeval()\fR was
+compiled.  (Assignments to \f(CW\*(C`$SIG{}\*(C'\fR, however, assume the signal
+handler specified is in the \f(CW\*(C`main\*(C'\fR package.  Qualify the signal handler
+name if you wish to have a signal handler in a package.)  For an
+example, examine \fIperldb.pl\fR in the Perl library.  It initially switches
+to the \f(CW\*(C`DB\*(C'\fR package so that the debugger doesn't interfere with variables
+in the program you are trying to debug.  At various points, however, it
+temporarily switches back to the \f(CW\*(C`main\*(C'\fR package to evaluate various
+expressions in the context of the \f(CW\*(C`main\*(C'\fR package (or wherever you came
+from).  See perldebug.
+.PP
+The special symbol \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR contains the current package, but cannot
+(easily) be used to construct variable names. After \f(CWmy($foo)\fR has hidden
+package variable \f(CW$foo\fR, it can still be accessed, without knowing what
+package you are in, as \f(CW\*(C`${_\|_PACKAGE_\|_.\*(Aq::foo\*(Aq}\*(C'\fR.
+.PP
+See perlsub for other scoping issues related to \fBmy()\fR and \fBlocal()\fR,
+and perlref regarding closures.
+.SS "Symbol Tables"
+.IX Xref "symbol table stash %:: %main:: typeglob glob alias"
+.IX Subsection "Symbol Tables"
+The symbol table for a package happens to be stored in the hash of that
+name with two colons appended.  The main symbol table's name is thus
+\&\f(CW%main::\fR, or \f(CW%::\fR for short.  Likewise the symbol table for the nested
+package mentioned earlier is named \f(CW%OUTER::INNER::\fR.
+.PP
+The value in each entry of the hash is what you are referring to when you
+use the \f(CW*name\fR typeglob notation.
+.PP
+.Vb 1
+\&    local *main::foo    = *main::bar;
+.Ve
+.PP
+You can use this to print out all the variables in a package, for
+instance.  The standard but antiquated \fIdumpvar.pl\fR library and
+the CPAN module Devel::Symdump make use of this.
+.PP
+The results of creating new symbol table entries directly or modifying any
+entries that are not already typeglobs are undefined and subject to change
+between releases of perl.
+.PP
+Assignment to a typeglob performs an aliasing operation, i.e.,
+.PP
+.Vb 1
+\&    *dick = *richard;
+.Ve
+.PP
+causes variables, subroutines, formats, and file and directory handles
+accessible via the identifier \f(CW\*(C`richard\*(C'\fR also to be accessible via the
+identifier \f(CW\*(C`dick\*(C'\fR.  If you want to alias only a particular variable or
+subroutine, assign a reference instead:
+.PP
+.Vb 1
+\&    *dick = \e$richard;
+.Ve
+.PP
+Which makes \f(CW$richard\fR and \f(CW$dick\fR the same variable, but leaves
+\&\f(CW@richard\fR and \f(CW@dick\fR as separate arrays.  Tricky, eh?
+.PP
+There is one subtle difference between the following statements:
+.PP
+.Vb 2
+\&    *foo = *bar;
+\&    *foo = \e$bar;
+.Ve
+.PP
+\&\f(CW\*(C`*foo = *bar\*(C'\fR makes the typeglobs themselves synonymous while
+\&\f(CW\*(C`*foo = \e$bar\*(C'\fR makes the SCALAR portions of two distinct typeglobs
+refer to the same scalar value. This means that the following code:
+.PP
+.Vb 2
+\&    $bar = 1;
+\&    *foo = \e$bar;       # Make $foo an alias for $bar
+\&
+\&    {
+\&        local $bar = 2; # Restrict changes to block
+\&        print $foo;     # Prints \*(Aq1\*(Aq!
+\&    }
+.Ve
+.PP
+Would print '1', because \f(CW$foo\fR holds a reference to the \fIoriginal\fR
+\&\f(CW$bar\fR. The one that was stuffed away by \f(CWlocal()\fR and which will be
+restored when the block ends. Because variables are accessed through the
+typeglob, you can use \f(CW\*(C`*foo = *bar\*(C'\fR to create an alias which can be
+localized. (But be aware that this means you can't have a separate
+\&\f(CW@foo\fR and \f(CW@bar\fR, etc.)
+.PP
+What makes all of this important is that the Exporter module uses glob
+aliasing as the import/export mechanism. Whether or not you can properly
+localize a variable that has been exported from a module depends on how
+it was exported:
+.PP
+.Vb 2
+\&    @EXPORT = qw($FOO); # Usual form, can\*(Aqt be localized
+\&    @EXPORT = qw(*FOO); # Can be localized
+.Ve
+.PP
+You can work around the first case by using the fully qualified name
+(\f(CW$Package::FOO\fR) where you need a local value, or by overriding it
+by saying \f(CW\*(C`*FOO = *Package::FOO\*(C'\fR in your script.
+.PP
+The \f(CW\*(C`*x = \e$y\*(C'\fR mechanism may be used to pass and return cheap references
+into or from subroutines if you don't want to copy the whole
+thing.  It only works when assigning to dynamic variables, not
+lexicals.
+.PP
+.Vb 9
+\&    %some_hash = ();                    # can\*(Aqt be my()
+\&    *some_hash = fn( \e%another_hash );
+\&    sub fn {
+\&        local *hashsym = shift;
+\&        # now use %hashsym normally, and you
+\&        # will affect the caller\*(Aqs %another_hash
+\&        my %nhash = (); # do what you want
+\&        return \e%nhash;
+\&    }
+.Ve
+.PP
+On return, the reference will overwrite the hash slot in the
+symbol table specified by the *some_hash typeglob.  This
+is a somewhat tricky way of passing around references cheaply
+when you don't want to have to remember to dereference variables
+explicitly.
+.PP
+Another use of symbol tables is for making "constant" scalars.
+.IX Xref "constant scalar, constant"
+.PP
+.Vb 1
+\&    *PI = \e3.14159265358979;
+.Ve
+.PP
+Now you cannot alter \f(CW$PI\fR, which is probably a good thing all in all.
+This isn't the same as a constant subroutine, which is subject to
+optimization at compile-time.  A constant subroutine is one prototyped
+to take no arguments and to return a constant expression.  See
+perlsub for details on these.  The \f(CW\*(C`use constant\*(C'\fR pragma is a
+convenient shorthand for these.
+.PP
+You can say \f(CW*foo{PACKAGE}\fR and \f(CW*foo{NAME}\fR to find out what name and
+package the *foo symbol table entry comes from.  This may be useful
+in a subroutine that gets passed typeglobs as arguments:
+.PP
+.Vb 7
+\&    sub identify_typeglob {
+\&        my $glob = shift;
+\&        print \*(AqYou gave me \*(Aq, *{$glob}{PACKAGE},
+\&            \*(Aq::\*(Aq, *{$glob}{NAME}, "\en";
+\&    }
+\&    identify_typeglob *foo;
+\&    identify_typeglob *bar::baz;
+.Ve
+.PP
+This prints
+.PP
+.Vb 2
+\&    You gave me main::foo
+\&    You gave me bar::baz
+.Ve
+.PP
+The \f(CW*foo{THING}\fR notation can also be used to obtain references to the
+individual elements of *foo.  See perlref.
+.PP
+Subroutine definitions (and declarations, for that matter) need
+not necessarily be situated in the package whose symbol table they
+occupy.  You can define a subroutine outside its package by
+explicitly qualifying the name of the subroutine:
+.PP
+.Vb 2
+\&    package main;
+\&    sub Some_package::foo { ... }   # &foo defined in Some_package
+.Ve
+.PP
+This is just a shorthand for a typeglob assignment at compile time:
+.PP
+.Vb 1
+\&    BEGIN { *Some_package::foo = sub { ... } }
+.Ve
+.PP
+and is \fInot\fR the same as writing:
+.PP
+.Vb 4
+\&    {
+\&        package Some_package;
+\&        sub foo { ... }
+\&    }
+.Ve
+.PP
+In the first two versions, the body of the subroutine is
+lexically in the main package, \fInot\fR in Some_package. So
+something like this:
+.PP
+.Vb 1
+\&    package main;
+\&
+\&    $Some_package::name = "fred";
+\&    $main::name = "barney";
+\&
+\&    sub Some_package::foo {
+\&        print "in ", _\|_PACKAGE_\|_, ": \e$name is \*(Aq$name\*(Aq\en";
+\&    }
+\&
+\&    Some_package::foo();
+.Ve
+.PP
+prints:
+.PP
+.Vb 1
+\&    in main: $name is \*(Aqbarney\*(Aq
+.Ve
+.PP
+rather than:
+.PP
+.Vb 1
+\&    in Some_package: $name is \*(Aqfred\*(Aq
+.Ve
+.PP
+This also has implications for the use of the SUPER:: qualifier
+(see perlobj).
+.SS "BEGIN, UNITCHECK, CHECK, INIT and END"
+.IX Xref "BEGIN UNITCHECK CHECK INIT END"
+.IX Subsection "BEGIN, UNITCHECK, CHECK, INIT and END"
+Five specially named code blocks are executed at the beginning and at
+the end of a running Perl program.  These are the \f(CW\*(C`BEGIN\*(C'\fR,
+\&\f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, and \f(CW\*(C`END\*(C'\fR blocks.
+.PP
+These code blocks can be prefixed with \f(CW\*(C`sub\*(C'\fR to give the appearance of a
+subroutine (although this is not considered good style).  One should note
+that these code blocks don't really exist as named subroutines (despite
+their appearance). The thing that gives this away is the fact that you can
+have \fBmore than one\fR of these code blocks in a program, and they will get
+\&\fBall\fR executed at the appropriate moment.  So you can't execute any of
+these code blocks by name.
+.PP
+A \f(CW\*(C`BEGIN\*(C'\fR code block is executed as soon as possible, that is, the moment
+it is completely defined, even before the rest of the containing file (or
+string) is parsed.  You may have multiple \f(CW\*(C`BEGIN\*(C'\fR blocks within a file (or
+eval'ed string); they will execute in order of definition.  Because a \f(CW\*(C`BEGIN\*(C'\fR
+code block executes immediately, it can pull in definitions of subroutines
+and such from other files in time to be visible to the rest of the compile
+and run time.  Once a \f(CW\*(C`BEGIN\*(C'\fR has run, it is immediately undefined and any
+code it used is returned to Perl's memory pool.
+.PP
+An \f(CW\*(C`END\*(C'\fR code block is executed as late as possible, that is, after
+perl has finished running the program and just before the interpreter
+is being exited, even if it is exiting as a result of a \fBdie()\fR function.
+(But not if it's morphing into another program via \f(CW\*(C`exec\*(C'\fR, or
+being blown out of the water by a signal\-\-you have to trap that yourself
+(if you can).)  You may have multiple \f(CW\*(C`END\*(C'\fR blocks within a file\-\-they
+will execute in reverse order of definition; that is: last in, first
+out (LIFO).  \f(CW\*(C`END\*(C'\fR blocks are not executed when you run perl with the
+\&\f(CW\*(C`\-c\*(C'\fR switch, or if compilation fails.
+.PP
+Note that \f(CW\*(C`END\*(C'\fR code blocks are \fBnot\fR executed at the end of a string
+\&\f(CWeval()\fR: if any \f(CW\*(C`END\*(C'\fR code blocks are created in a string \f(CWeval()\fR,
+they will be executed just as any other \f(CW\*(C`END\*(C'\fR code block of that package
+in LIFO order just before the interpreter is being exited.
+.PP
+Inside an \f(CW\*(C`END\*(C'\fR code block, \f(CW$?\fR contains the value that the program is
+going to pass to \f(CWexit()\fR.  You can modify \f(CW$?\fR to change the exit
+value of the program.  Beware of changing \f(CW$?\fR by accident (e.g. by
+running something via \f(CW\*(C`system\*(C'\fR).
+.IX Xref "$?"
+.PP
+Inside of a \f(CW\*(C`END\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be
+\&\f(CW"END"\fR.
+.PP
+Similar to an \f(CW\*(C`END\*(C'\fR block are \f(CW\*(C`defer\*(C'\fR blocks, though they operate on the
+lifetime of individual block scopes, rather than the program as a whole. They
+are documented in "defer" in perlsyn.
+.PP
+\&\f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR code blocks are useful to catch the
+transition between the compilation phase and the execution phase of
+the main program.
+.PP
+\&\f(CW\*(C`UNITCHECK\*(C'\fR blocks are run just after the unit which defined them has
+been compiled.  The main program file and each module it loads are
+compilation units, as are string \f(CW\*(C`eval\*(C'\fRs, run-time code compiled using the
+\&\f(CW\*(C`(?{ })\*(C'\fR construct in a regex, calls to \f(CW\*(C`do FILE\*(C'\fR, \f(CW\*(C`require FILE\*(C'\fR,
+and code after the \f(CW\*(C`\-e\*(C'\fR switch on the command line.
+.PP
+\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`UNITCHECK\*(C'\fR blocks are not directly related to the phase of
+the interpreter.  They can be created and executed during any phase.
+.PP
+\&\f(CW\*(C`CHECK\*(C'\fR code blocks are run just after the \fBinitial\fR Perl compile phase ends
+and before the run time begins, in LIFO order.  \f(CW\*(C`CHECK\*(C'\fR code blocks are used
+in the Perl compiler suite to save the compiled state of the program.
+.PP
+Inside of a \f(CW\*(C`CHECK\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be
+\&\f(CW"CHECK"\fR.
+.PP
+\&\f(CW\*(C`INIT\*(C'\fR blocks are run just before the Perl runtime begins execution, in
+"first in, first out" (FIFO) order.
+.PP
+Inside of an \f(CW\*(C`INIT\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be \f(CW"INIT"\fR.
+.PP
+The \f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR blocks in code compiled by \f(CW\*(C`require\*(C'\fR, string \f(CW\*(C`do\*(C'\fR,
+or string \f(CW\*(C`eval\*(C'\fR will not be executed if they occur after the end of the
+main compilation phase; that can be a problem in mod_perl and other persistent
+environments which use those functions to load code at runtime.
+.PP
+When you use the \fB\-n\fR and \fB\-p\fR switches to Perl, \f(CW\*(C`BEGIN\*(C'\fR and
+\&\f(CW\*(C`END\*(C'\fR work just as they do in \fBawk\fR, as a degenerate case.
+Both \f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`CHECK\*(C'\fR blocks are run when you use the \fB\-c\fR
+switch for a compile-only syntax check, although your main code
+is not.
+.PP
+The \fBbegincheck\fR program makes it all clear, eventually:
+.PP
+.Vb 1
+\&  #!/usr/bin/perl
+\&
+\&  # begincheck
+\&
+\&  print         "10. Ordinary code runs at runtime.\en";
+\&
+\&  END { print   "16.   So this is the end of the tale.\en" }
+\&  INIT { print  " 7. INIT blocks run FIFO just before runtime.\en" }
+\&  UNITCHECK {
+\&    print       " 4.   And therefore before any CHECK blocks.\en"
+\&  }
+\&  CHECK { print " 6.   So this is the sixth line.\en" }
+\&
+\&  print         "11.   It runs in order, of course.\en";
+\&
+\&  BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\en" }
+\&  END { print   "15.   Read perlmod for the rest of the story.\en" }
+\&  CHECK { print " 5. CHECK blocks run LIFO after all compilation.\en" }
+\&  INIT { print  " 8.   Run this again, using Perl\*(Aqs \-c switch.\en" }
+\&
+\&  print         "12.   This is anti\-obfuscated code.\en";
+\&
+\&  END { print   "14. END blocks run LIFO at quitting time.\en" }
+\&  BEGIN { print " 2.   So this line comes out second.\en" }
+\&  UNITCHECK {
+\&   print " 3. UNITCHECK blocks run LIFO after each file is compiled.\en"
+\&  }
+\&  INIT { print  " 9.   You\*(Aqll see the difference right away.\en" }
+\&
+\&  print         "13.   It only _looks_ like it should be confusing.\en";
+\&
+\&  _\|_END_\|_
+.Ve
+.SS "Perl Classes"
+.IX Xref "class @ISA"
+.IX Subsection "Perl Classes"
+There is no special class syntax in Perl, but a package may act
+as a class if it provides subroutines to act as methods.  Such a
+package may also derive some of its methods from another class (package)
+by listing the other package name(s) in its global \f(CW@ISA\fR array (which
+must be a package global, not a lexical).
+.PP
+For more on this, see perlootut and perlobj.
+.SS "Perl Modules"
+.IX Xref "module"
+.IX Subsection "Perl Modules"
+A module is just a set of related functions in a library file, i.e.,
+a Perl package with the same name as the file.  It is specifically
+designed to be reusable by other modules or programs.  It may do this
+by providing a mechanism for exporting some of its symbols into the
+symbol table of any package using it, or it may function as a class
+definition and make its semantics available implicitly through
+method calls on the class and its objects, without explicitly
+exporting anything.  Or it can do a little of both.
+.PP
+For example, to start a traditional, non-OO module called Some::Module,
+create a file called \fISome/Module.pm\fR and start with this template:
+.PP
+.Vb 1
+\&    package Some::Module;  # assumes Some/Module.pm
+\&
+\&    use v5.36;
+\&
+\&    # Get the import method from Exporter to export functions and
+\&    # variables
+\&    use Exporter 5.57 \*(Aqimport\*(Aq;
+\&
+\&    # set the version for version checking
+\&    our $VERSION     = \*(Aq1.00\*(Aq;
+\&
+\&    # Functions and variables which are exported by default
+\&    our @EXPORT      = qw(func1 func2);
+\&
+\&    # Functions and variables which can be optionally exported
+\&    our @EXPORT_OK   = qw($Var1 %Hashit func3);
+\&
+\&    # exported package globals go here
+\&    our $Var1    = \*(Aq\*(Aq;
+\&    our %Hashit  = ();
+\&
+\&    # non\-exported package globals go here
+\&    # (they are still accessible as $Some::Module::stuff)
+\&    our @more    = ();
+\&    our $stuff   = \*(Aq\*(Aq;
+\&
+\&    # file\-private lexicals go here, before any functions which use them
+\&    my $priv_var    = \*(Aq\*(Aq;
+\&    my %secret_hash = ();
+\&
+\&    # here\*(Aqs a file\-private function as a closure,
+\&    # callable as $priv_func\->();
+\&    my $priv_func = sub {
+\&        ...
+\&    };
+\&
+\&    # make all your functions, whether exported or not;
+\&    # remember to put something interesting in the {} stubs
+\&    sub func1      { ... }
+\&    sub func2      { ... }
+\&
+\&    # this one isn\*(Aqt always exported, but could be called directly
+\&    # as Some::Module::func3()
+\&    sub func3      { ... }
+\&
+\&    END { ... }       # module clean\-up code here (global destructor)
+\&
+\&    1;  # don\*(Aqt forget to return a true value from the file
+.Ve
+.PP
+Then go on to declare and use your variables in functions without
+any qualifications.  See Exporter and the perlmodlib for
+details on mechanics and style issues in module creation.
+.PP
+Perl modules are included into your program by saying
+.PP
+.Vb 1
+\&    use Module;
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    use Module LIST;
+.Ve
+.PP
+This is exactly equivalent to
+.PP
+.Vb 1
+\&    BEGIN { require \*(AqModule.pm\*(Aq; \*(AqModule\*(Aq\->import; }
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    BEGIN { require \*(AqModule.pm\*(Aq; \*(AqModule\*(Aq\->import( LIST ); }
+.Ve
+.PP
+As a special case
+.PP
+.Vb 1
+\&    use Module ();
+.Ve
+.PP
+is exactly equivalent to
+.PP
+.Vb 1
+\&    BEGIN { require \*(AqModule.pm\*(Aq; }
+.Ve
+.PP
+All Perl module files have the extension \fI.pm\fR.  The \f(CW\*(C`use\*(C'\fR operator
+assumes this so you don't have to spell out "\fIModule.pm\fR" in quotes.
+This also helps to differentiate new modules from old \fI.pl\fR and
+\&\fI.ph\fR files.  Module names are also capitalized unless they're
+functioning as pragmas; pragmas are in effect compiler directives,
+and are sometimes called "pragmatic modules" (or even "pragmata"
+if you're a classicist).
+.PP
+The two statements:
+.PP
+.Vb 2
+\&    require SomeModule;
+\&    require "SomeModule.pm";
+.Ve
+.PP
+differ from each other in two ways.  In the first case, any double
+colons in the module name, such as \f(CW\*(C`Some::Module\*(C'\fR, are translated
+into your system's directory separator, usually "/".   The second
+case does not, and would have to be specified literally.  The other
+difference is that seeing the first \f(CW\*(C`require\*(C'\fR clues in the compiler
+that uses of indirect object notation involving "SomeModule", as
+in \f(CW\*(C`$ob = purge SomeModule\*(C'\fR, are method calls, not function calls.
+(Yes, this really can make a difference.)
+.PP
+Because the \f(CW\*(C`use\*(C'\fR statement implies a \f(CW\*(C`BEGIN\*(C'\fR block, the importing
+of semantics happens as soon as the \f(CW\*(C`use\*(C'\fR statement is compiled,
+before the rest of the file is compiled.  This is how it is able
+to function as a pragma mechanism, and also how modules are able to
+declare subroutines that are then visible as list or unary operators for
+the rest of the current file.  This will not work if you use \f(CW\*(C`require\*(C'\fR
+instead of \f(CW\*(C`use\*(C'\fR.  With \f(CW\*(C`require\*(C'\fR you can get into this problem:
+.PP
+.Vb 2
+\&    require Cwd;                # make Cwd:: accessible
+\&    $here = Cwd::getcwd();
+\&
+\&    use Cwd;                    # import names from Cwd::
+\&    $here = getcwd();
+\&
+\&    require Cwd;                # make Cwd:: accessible
+\&    $here = getcwd();           # oops! no main::getcwd()
+.Ve
+.PP
+In general, \f(CW\*(C`use Module ()\*(C'\fR is recommended over \f(CW\*(C`require Module\*(C'\fR,
+because it determines module availability at compile time, not in the
+middle of your program's execution.  An exception would be if two modules
+each tried to \f(CW\*(C`use\*(C'\fR each other, and each also called a function from
+that other module.  In that case, it's easy to use \f(CW\*(C`require\*(C'\fR instead.
+.PP
+Perl packages may be nested inside other package names, so we can have
+package names containing \f(CW\*(C`::\*(C'\fR.  But if we used that package name
+directly as a filename it would make for unwieldy or impossible
+filenames on some systems.  Therefore, if a module's name is, say,
+\&\f(CW\*(C`Text::Soundex\*(C'\fR, then its definition is actually found in the library
+file \fIText/Soundex.pm\fR.
+.PP
+Perl modules always have a \fI.pm\fR file, but there may also be
+dynamically linked executables (often ending in \fI.so\fR) or autoloaded
+subroutine definitions (often ending in \fI.al\fR) associated with the
+module.  If so, these will be entirely transparent to the user of
+the module.  It is the responsibility of the \fI.pm\fR file to load
+(or arrange to autoload) any additional functionality.  For example,
+although the POSIX module happens to do both dynamic loading and
+autoloading, the user can say just \f(CW\*(C`use POSIX\*(C'\fR to get it all.
+.SS "Making your module threadsafe"
+.IX Xref "threadsafe thread safe module, threadsafe module, thread safe CLONE CLONE_SKIP thread threads ithread"
+.IX Subsection "Making your module threadsafe"
+Perl supports a type of threads called interpreter threads (ithreads).
+These threads can be used explicitly and implicitly.
+.PP
+Ithreads work by cloning the data tree so that no data is shared
+between different threads. These threads can be used by using the \f(CW\*(C`threads\*(C'\fR
+module or by doing \fBfork()\fR on win32 (fake \fBfork()\fR support). When a
+thread is cloned all Perl data is cloned, however non-Perl data cannot
+be cloned automatically.  Perl after 5.8.0 has support for the \f(CW\*(C`CLONE\*(C'\fR
+special subroutine.  In \f(CW\*(C`CLONE\*(C'\fR you can do whatever
+you need to do,
+like for example handle the cloning of non-Perl data, if necessary.
+\&\f(CW\*(C`CLONE\*(C'\fR will be called once as a class method for every package that has it
+defined (or inherits it).  It will be called in the context of the new thread,
+so all modifications are made in the new area.  Currently CLONE is called with
+no parameters other than the invocant package name, but code should not assume
+that this will remain unchanged, as it is likely that in future extra parameters
+will be passed in to give more information about the state of cloning.
+.PP
+If you want to CLONE all objects you will need to keep track of them per
+package. This is simply done using a hash and \fBScalar::Util::weaken()\fR.
+.PP
+Perl after 5.8.7 has support for the \f(CW\*(C`CLONE_SKIP\*(C'\fR special subroutine.
+Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is called once per package; however, it is
+called just before cloning starts, and in the context of the parent
+thread. If it returns a true value, then no objects of that class will
+be cloned; or rather, they will be copied as unblessed, undef values.
+For example: if in the parent there are two references to a single blessed
+hash, then in the child there will be two references to a single undefined
+scalar value instead.
+This provides a simple mechanism for making a module threadsafe; just add
+\&\f(CW\*(C`sub CLONE_SKIP { 1 }\*(C'\fR at the top of the class, and \f(CWDESTROY()\fR will
+now only be called once per object. Of course, if the child thread needs
+to make use of the objects, then a more sophisticated approach is
+needed.
+.PP
+Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is currently called with no parameters other
+than the invocant package name, although that may change. Similarly, to
+allow for future expansion, the return value should be a single \f(CW0\fR or
+\&\f(CW1\fR value.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See perlmodlib for general style issues related to building Perl
+modules and classes, as well as descriptions of the standard library
+and CPAN, Exporter for how Perl's standard import/export mechanism
+works, perlootut and perlobj for in-depth information on
+creating classes, perlobj for a hard-core reference document on
+objects, perlsub for an explanation of functions and scoping,
+and perlxstut and perlguts for more information on writing
+extension modules.
diff --git a/upstream/mageia-cauldron/man1/perlmodinstall.1 b/upstream/mageia-cauldron/man1/perlmodinstall.1
new file mode 100644
index 00000000..09805279
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmodinstall.1
@@ -0,0 +1,400 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMODINSTALL 1"
+.TH PERLMODINSTALL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmodinstall \- Installing CPAN Modules
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+You can think of a module as the fundamental unit of reusable Perl
+code; see perlmod for details.  Whenever anyone creates a chunk of
+Perl code that they think will be useful to the world, they register
+as a Perl developer at <https://www.cpan.org/modules/04pause.html>
+so that they can then upload their code to the CPAN.  The CPAN is the
+Comprehensive Perl Archive Network and can be accessed at
+<https://www.cpan.org/> , and searched at <https://metacpan.org/> .
+.PP
+This documentation is for people who want to download CPAN modules
+and install them on their own computer.
+.SS PREAMBLE
+.IX Subsection "PREAMBLE"
+First, are you sure that the module isn't already on your system?  Try
+\&\f(CW\*(C`perl \-MFoo \-e 1\*(C'\fR.  (Replace "Foo" with the name of the module; for
+instance, \f(CW\*(C`perl \-MCGI::Carp \-e 1\*(C'\fR.)
+.PP
+If you don't see an error message, you have the module.  (If you do
+see an error message, it's still possible you have the module, but
+that it's not in your path, which you can display with \f(CWperl \-e
+"print qq(@INC)"\fR.)  For the remainder of this document, we'll assume
+that you really honestly truly lack an installed module, but have
+found it on the CPAN.
+.PP
+So now you have a file ending in .tar.gz (or, less often, .zip).  You
+know there's a tasty module inside.  There are four steps you must now
+take:
+.IP "\fBDECOMPRESS\fR the file" 5
+.IX Item "DECOMPRESS the file"
+.PD 0
+.IP "\fBUNPACK\fR the file into a directory" 5
+.IX Item "UNPACK the file into a directory"
+.IP "\fBBUILD\fR the module (sometimes unnecessary)" 5
+.IX Item "BUILD the module (sometimes unnecessary)"
+.IP "\fBINSTALL\fR the module." 5
+.IX Item "INSTALL the module."
+.PD
+.PP
+Here's how to perform each step for each operating system.  This is
+<not> a substitute for reading the README and INSTALL files that
+might have come with your module!
+.PP
+Also note that these instructions are tailored for installing the
+module into your system's repository of Perl modules, but you can
+install modules into any directory you wish.  For instance, where I
+say \f(CW\*(C`perl Makefile.PL\*(C'\fR, you can substitute \f(CW\*(C`perl Makefile.PL
+PREFIX=/my/perl_directory\*(C'\fR to install the modules into
+\&\fI/my/perl_directory\fR.  Then you can use the modules from your Perl
+programs with \f(CW\*(C`use lib "/my/perl_directory/lib/site_perl";\*(C'\fR or
+sometimes just \f(CW\*(C`use "/my/perl_directory";\*(C'\fR.  If you're on a system
+that requires superuser/root access to install modules into the
+directories you see when you type \f(CW\*(C`perl \-e "print qq(@INC)"\*(C'\fR, you'll
+want to install them into a local directory (such as your home
+directory) and use this approach.
+.IP \(bu 4
+\&\fBIf you're on a Unix or Unix-like system,\fR
+.Sp
+You can use Andreas Koenig's CPAN module
+( <https://metacpan.org/release/CPAN> )
+to automate the following steps, from DECOMPRESS through INSTALL.
+.Sp
+A. DECOMPRESS
+.Sp
+Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR
+.Sp
+You can get gzip from <ftp://prep.ai.mit.edu/pub/gnu/>
+.Sp
+Or, you can combine this step with the next to save disk space:
+.Sp
+.Vb 1
+\&     gzip \-dc yourmodule.tar.gz | tar \-xof \-
+.Ve
+.Sp
+B. UNPACK
+.Sp
+Unpack the result with \f(CW\*(C`tar \-xof yourmodule.tar\*(C'\fR
+.Sp
+C. BUILD
+.Sp
+Go into the newly-created directory and type:
+.Sp
+.Vb 2
+\&      perl Makefile.PL
+\&      make test
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&      perl Makefile.PL PREFIX=/my/perl_directory
+.Ve
+.Sp
+to install it locally.  (Remember that if you do this, you'll have to
+put \f(CW\*(C`use lib "/my/perl_directory";\*(C'\fR near the top of the program that
+is to use this module.
+.Sp
+D. INSTALL
+.Sp
+While still in that directory, type:
+.Sp
+.Vb 1
+\&      make install
+.Ve
+.Sp
+Make sure you have the appropriate permissions to install the module
+in your Perl 5 library directory.  Often, you'll need to be root.
+.Sp
+That's all you need to do on Unix systems with dynamic linking.
+Most Unix systems have dynamic linking. If yours doesn't, or if for
+another reason you have a statically-linked perl, \fBand\fR the
+module requires compilation, you'll need to build a new Perl binary
+that includes the module.  Again, you'll probably need to be root.
+.IP \(bu 4
+\&\fBIf you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),\fR
+.Sp
+First, type \f(CW\*(C`ppm\*(C'\fR from a shell and see whether ActiveState's PPM
+repository has your module.  If so, you can install it with \f(CW\*(C`ppm\*(C'\fR and
+you won't have to bother with any of the other steps here.  You might
+be able to use the CPAN instructions from the "Unix or Linux" section
+above as well; give it a try.  Otherwise, you'll have to follow the
+steps below.
+.Sp
+.Vb 1
+\&   A. DECOMPRESS
+.Ve
+.Sp
+You can use the
+open source 7\-zip ( <https://www.7\-zip.org/> )
+or the shareware Winzip ( <https://www.winzip.com> ) to
+decompress and unpack modules.
+.Sp
+.Vb 1
+\&   B. UNPACK
+.Ve
+.Sp
+If you used WinZip, this was already done for you.
+.Sp
+.Vb 1
+\&   C. BUILD
+.Ve
+.Sp
+You'll need either \f(CW\*(C`nmake\*(C'\fR or \f(CW\*(C`gmake\*(C'\fR.
+.Sp
+Does the module require compilation (i.e. does it have files that end
+in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, life is now
+officially tough for you, because you have to compile the module
+yourself (no easy feat on Windows).  You'll need a compiler such as
+Visual C++.  Alternatively, you can download a pre-built PPM package
+from ActiveState.
+<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
+.Sp
+Go into the newly-created directory and type:
+.Sp
+.Vb 2
+\&      perl Makefile.PL
+\&      nmake test
+\&
+\&
+\&   D. INSTALL
+.Ve
+.Sp
+While still in that directory, type:
+.Sp
+.Vb 1
+\&      nmake install
+.Ve
+.IP \(bu 4
+\&\fBIf you're on OS/2,\fR
+.Sp
+Get the EMX development suite and gzip/tar from Hobbes (
+<http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2/dev/emx/v0.9d> ), and then follow
+the instructions for Unix.
+.IP \(bu 4
+\&\fBIf you're on VMS,\fR
+.Sp
+When downloading from CPAN, save your file with a \f(CW\*(C`.tgz\*(C'\fR
+extension instead of \f(CW\*(C`.tar.gz\*(C'\fR.  All other periods in the
+filename should be replaced with underscores.  For example,
+\&\f(CW\*(C`Your\-Module\-1.33.tar.gz\*(C'\fR should be downloaded as
+\&\f(CW\*(C`Your\-Module\-1_33.tgz\*(C'\fR.
+.Sp
+A. DECOMPRESS
+.Sp
+Type
+.Sp
+.Vb 1
+\&    gzip \-d Your\-Module.tgz
+.Ve
+.Sp
+or, for zipped modules, type
+.Sp
+.Vb 1
+\&    unzip Your\-Module.zip
+.Ve
+.Sp
+Executables for gzip, zip, and VMStar:
+.Sp
+.Vb 1
+\&    http://www.hp.com/go/openvms/freeware/
+.Ve
+.Sp
+and their source code:
+.Sp
+.Vb 1
+\&    http://www.fsf.org/order/ftp.html
+.Ve
+.Sp
+Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
+package.  The former is a simple compression tool; the latter permits
+creation of multi-file archives.
+.Sp
+B. UNPACK
+.Sp
+If you're using VMStar:
+.Sp
+.Vb 1
+\&     VMStar xf Your\-Module.tar
+.Ve
+.Sp
+Or, if you're fond of VMS command syntax:
+.Sp
+.Vb 1
+\&     tar/extract/verbose Your_Module.tar
+.Ve
+.Sp
+C. BUILD
+.Sp
+Make sure you have MMS (from Digital) or the freeware MMK ( available
+from MadGoat at <http://www.madgoat.com> ).  Then type this to create
+the DESCRIP.MMS for the module:
+.Sp
+.Vb 1
+\&    perl Makefile.PL
+.Ve
+.Sp
+Now you're ready to build:
+.Sp
+.Vb 1
+\&    mms test
+.Ve
+.Sp
+Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK.
+.Sp
+D. INSTALL
+.Sp
+Type
+.Sp
+.Vb 1
+\&    mms install
+.Ve
+.Sp
+Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK.
+.IP \(bu 4
+\&\fBIf you're on MVS\fR,
+.Sp
+Introduce the \fI.tar.gz\fR file into an HFS as binary; don't translate from
+ASCII to EBCDIC.
+.Sp
+A. DECOMPRESS
+.Sp
+Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR
+.Sp
+You can get gzip from
+<http://www.s390.ibm.com/products/oe/bpxqp1.html>
+.Sp
+B. UNPACK
+.Sp
+Unpack the result with
+.Sp
+.Vb 1
+\&     pax \-o to=IBM\-1047,from=ISO8859\-1 \-r < yourmodule.tar
+.Ve
+.Sp
+The BUILD and INSTALL steps are identical to those for Unix.  Some
+modules generate Makefiles that work better with GNU make, which is
+available from <http://www.mks.com/s390/gnu/>
+.SH PORTABILITY
+.IX Header "PORTABILITY"
+Note that not all modules will work with on all platforms.
+See perlport for more information on portability issues.
+Read the documentation to see if the module will work on your
+system.  There are basically three categories
+of modules that will not work "out of the box" with all
+platforms (with some possibility of overlap):
+.IP \(bu 4
+\&\fBThose that should, but don't.\fR  These need to be fixed; consider
+contacting the author and possibly writing a patch.
+.IP \(bu 4
+\&\fBThose that need to be compiled, where the target platform
+doesn't have compilers readily available.\fR  (These modules contain
+\&\fI.xs\fR or \fI.c\fR files, usually.)  You might be able to find
+existing binaries on the CPAN or elsewhere, or you might
+want to try getting compilers and building it yourself, and then
+release the binary for other poor souls to use.
+.IP \(bu 4
+\&\fBThose that are targeted at a specific platform.\fR
+(Such as the Win32:: modules.)  If the module is targeted
+specifically at a platform other than yours, you're out
+of luck, most likely.
+.PP
+Check the CPAN Testers if a module should work with your platform
+but it doesn't behave as you'd expect, or you aren't sure whether or
+not a module will work under your platform.  If the module you want
+isn't listed there, you can test it yourself and let CPAN Testers know,
+you can join CPAN Testers, or you can request it be tested.
+.PP
+.Vb 1
+\&    https://cpantesters.org/
+.Ve
+.SH HEY
+.IX Header "HEY"
+If you have any suggested changes for this page, let me know.  Please
+don't send me mail asking for help on how to install your modules.
+There are too many modules, and too few Orwants, for me to be able to
+answer or even acknowledge all your questions.  Contact the module
+author instead, ask someone familiar with Perl on your operating
+system, or if all else fails, file a ticket at <https://rt.cpan.org/>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Jon Orwant
+.PP
+orwant@medita.mit.edu
+.PP
+with invaluable help from Chris Nandor, and valuable help from Brandon
+Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
+Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
+J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
+Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
+.PP
+First version July 22, 1998; last revised November 21, 2001.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
+.PP
+This document may be distributed under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlmodlib.1 b/upstream/mageia-cauldron/man1/perlmodlib.1
new file mode 100644
index 00000000..d83803d8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmodlib.1
@@ -0,0 +1,2368 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMODLIB 1"
+.TH PERLMODLIB 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmodlib \- constructing new Perl modules and finding existing ones
+.SH "THE PERL MODULE LIBRARY"
+.IX Header "THE PERL MODULE LIBRARY"
+Many modules are included in the Perl distribution.  These are described
+below, and all end in \fI.pm\fR.  You may discover compiled library
+files (usually ending in \fI.so\fR) or small pieces of modules to be
+autoloaded (ending in \fI.al\fR); these were automatically generated
+by the installation process.  You may also discover files in the
+library directory that end in either \fI.pl\fR or \fI.ph\fR.  These are
+old libraries supplied so that old programs that use them still
+run.  The \fI.pl\fR files will all eventually be converted into standard
+modules, and the \fI.ph\fR files made by \fBh2ph\fR will probably end up
+as extension modules made by \fBh2xs\fR.  (Some \fI.ph\fR values may
+already be available through the POSIX, Errno, or Fcntl modules.)
+The \fBpl2pm\fR file in the distribution may help in your conversion,
+but it's just a mechanical process and therefore far from bulletproof.
+.SS "Pragmatic Modules"
+.IX Subsection "Pragmatic Modules"
+They work somewhat like compiler directives (pragmata) in that they
+tend to affect the compilation of your program, and thus will usually
+work well only when used within a \f(CW\*(C`use\*(C'\fR, or \f(CW\*(C`no\*(C'\fR.  Most of these
+are lexically scoped, so an inner BLOCK may countermand them
+by saying:
+.PP
+.Vb 3
+\&    no integer;
+\&    no strict \*(Aqrefs\*(Aq;
+\&    no warnings;
+.Ve
+.PP
+which lasts until the end of that BLOCK.
+.PP
+Some pragmas are lexically scoped\-\-typically those that affect the
+\&\f(CW$^H\fR hints variable.  Others affect the current package instead,
+like \f(CW\*(C`use vars\*(C'\fR and \f(CW\*(C`use subs\*(C'\fR, which allow you to predeclare a
+variables or subroutines within a particular \fIfile\fR rather than
+just a block.  Such declarations are effective for the entire file
+for which they were declared.  You cannot rescind them with \f(CW\*(C`no
+vars\*(C'\fR or \f(CW\*(C`no subs\*(C'\fR.
+.PP
+The following pragmas are defined (and have their own documentation).
+.IP attributes 12
+.IX Item "attributes"
+Get/set subroutine or variable attributes
+.IP autodie 12
+.IX Item "autodie"
+Replace functions with ones that succeed or die with lexical scope
+.IP autodie::exception 12
+.IX Item "autodie::exception"
+Exceptions from autodying functions.
+.IP autodie::exception::system 12
+.IX Item "autodie::exception::system"
+Exceptions from autodying \fBsystem()\fR.
+.IP autodie::hints 12
+.IX Item "autodie::hints"
+Provide hints about user subroutines to autodie
+.IP autodie::skip 12
+.IX Item "autodie::skip"
+Skip a package when throwing autodie exceptions
+.IP autouse 12
+.IX Item "autouse"
+Postpone load of modules until a function is used
+.IP base 12
+.IX Item "base"
+Establish an ISA relationship with base classes at compile time
+.IP bigfloat 12
+.IX Item "bigfloat"
+Transparent big floating point number support for Perl
+.IP bigint 12
+.IX Item "bigint"
+Transparent big integer support for Perl
+.IP bignum 12
+.IX Item "bignum"
+Transparent big number support for Perl
+.IP bigrat 12
+.IX Item "bigrat"
+Transparent big rational number support for Perl
+.IP blib 12
+.IX Item "blib"
+Use MakeMaker's uninstalled version of a package
+.IP builtin 12
+.IX Item "builtin"
+Import built-in utility functions
+.IP bytes 12
+.IX Item "bytes"
+Expose the individual bytes of characters
+.IP charnames 12
+.IX Item "charnames"
+Access to Unicode character names and named character sequences; also define character names
+.IP constant 12
+.IX Item "constant"
+Declare constants
+.IP deprecate 12
+.IX Item "deprecate"
+Perl pragma for deprecating the inclusion of a module in core
+.IP diagnostics 12
+.IX Item "diagnostics"
+Produce verbose warning diagnostics
+.IP encoding 12
+.IX Item "encoding"
+Allows you to write your script in non-ASCII and non\-UTF\-8
+.IP encoding::warnings 12
+.IX Item "encoding::warnings"
+Warn on implicit encoding conversions
+.IP experimental 12
+.IX Item "experimental"
+Experimental features made easy
+.IP feature 12
+.IX Item "feature"
+Enable new features
+.IP fields 12
+.IX Item "fields"
+Compile-time class fields
+.IP filetest 12
+.IX Item "filetest"
+Control the filetest permission operators
+.IP if 12
+.IX Item "if"
+\&\f(CW\*(C`use\*(C'\fR a Perl module if a condition holds
+.IP integer 12
+.IX Item "integer"
+Use integer arithmetic instead of floating point
+.IP less 12
+.IX Item "less"
+Request less of something
+.IP lib 12
+.IX Item "lib"
+Manipulate \f(CW@INC\fR at compile time
+.IP locale 12
+.IX Item "locale"
+Use or avoid POSIX locales for built-in operations
+.IP mro 12
+.IX Item "mro"
+Method Resolution Order
+.IP ok 12
+.IX Item "ok"
+Alternative to Test::More::use_ok
+.IP open 12
+.IX Item "open"
+Set default PerlIO layers for input and output
+.IP ops 12
+.IX Item "ops"
+Restrict unsafe operations when compiling
+.IP overload 12
+.IX Item "overload"
+Package for overloading Perl operations
+.IP overloading 12
+.IX Item "overloading"
+Lexically control overloading
+.IP parent 12
+.IX Item "parent"
+Establish an ISA relationship with base classes at compile time
+.IP re 12
+.IX Item "re"
+Alter regular expression behaviour
+.IP sigtrap 12
+.IX Item "sigtrap"
+Enable simple signal handling
+.IP sort 12
+.IX Item "sort"
+Control \fBsort()\fR behaviour
+.IP stable 12
+.IX Item "stable"
+Experimental features made easy, once we know they're stable
+.IP strict 12
+.IX Item "strict"
+Restrict unsafe constructs
+.IP subs 12
+.IX Item "subs"
+Predeclare subroutine names
+.IP threads 12
+.IX Item "threads"
+Perl interpreter-based threads
+.IP threads::shared 12
+.IX Item "threads::shared"
+Perl extension for sharing data structures between threads
+.IP utf8 12
+.IX Item "utf8"
+Enable/disable UTF\-8 (or UTF-EBCDIC) in source code
+.IP vars 12
+.IX Item "vars"
+Predeclare global variable names
+.IP version 12
+.IX Item "version"
+Perl extension for Version Objects
+.IP vmsish 12
+.IX Item "vmsish"
+Control VMS-specific language features
+.IP warnings 12
+.IX Item "warnings"
+Control optional warnings
+.IP warnings::register 12
+.IX Item "warnings::register"
+Warnings import function
+.SS "Standard Modules"
+.IX Subsection "Standard Modules"
+Standard, bundled modules are all expected to behave in a well-defined
+manner with respect to namespace pollution because they use the
+Exporter module.  See their own documentation for details.
+.PP
+It's possible that not all modules listed below are installed on your
+system. For example, the GDBM_File module will not be installed if you
+don't have the gdbm library.
+.IP Amiga::ARexx 12
+.IX Item "Amiga::ARexx"
+Perl extension for ARexx support
+.IP Amiga::Exec 12
+.IX Item "Amiga::Exec"
+Perl extension for low level amiga support
+.IP AnyDBM_File 12
+.IX Item "AnyDBM_File"
+Provide framework for multiple DBMs
+.IP App::Cpan 12
+.IX Item "App::Cpan"
+Easily interact with CPAN from the command line
+.IP App::Prove 12
+.IX Item "App::Prove"
+Implements the \f(CW\*(C`prove\*(C'\fR command.
+.IP App::Prove::State 12
+.IX Item "App::Prove::State"
+State storage for the \f(CW\*(C`prove\*(C'\fR command.
+.IP App::Prove::State::Result 12
+.IX Item "App::Prove::State::Result"
+Individual test suite results.
+.IP App::Prove::State::Result::Test 12
+.IX Item "App::Prove::State::Result::Test"
+Individual test results.
+.IP Archive::Tar 12
+.IX Item "Archive::Tar"
+Module for manipulations of tar archives
+.IP Archive::Tar::File 12
+.IX Item "Archive::Tar::File"
+A subclass for in-memory extracted file from Archive::Tar
+.IP Attribute::Handlers 12
+.IX Item "Attribute::Handlers"
+Simpler definition of attribute handlers
+.IP AutoLoader 12
+.IX Item "AutoLoader"
+Load subroutines only on demand
+.IP AutoSplit 12
+.IX Item "AutoSplit"
+Split a package for autoloading
+.IP B 12
+.IX Item "B"
+The Perl Compiler Backend
+.IP B::Concise 12
+.IX Item "B::Concise"
+Walk Perl syntax tree, printing concise info about ops
+.IP B::Deparse 12
+.IX Item "B::Deparse"
+Perl compiler backend to produce perl code
+.IP B::Op_private 12
+.IX Item "B::Op_private"
+OP op_private flag definitions
+.IP B::Showlex 12
+.IX Item "B::Showlex"
+Show lexical variables used in functions or files
+.IP B::Terse 12
+.IX Item "B::Terse"
+Walk Perl syntax tree, printing terse info about ops
+.IP B::Xref 12
+.IX Item "B::Xref"
+Generates cross reference reports for Perl programs
+.IP Benchmark 12
+.IX Item "Benchmark"
+Benchmark running times of Perl code
+.ie n .IP """IO::Socket::IP""" 12
+.el .IP \f(CWIO::Socket::IP\fR 12
+.IX Item "IO::Socket::IP"
+Family-neutral IP socket supporting both IPv4 and IPv6
+.ie n .IP """Socket""" 12
+.el .IP \f(CWSocket\fR 12
+.IX Item "Socket"
+Networking constants and support functions
+.IP CORE 12
+.IX Item "CORE"
+Namespace for Perl's core routines
+.IP CPAN 12
+.IX Item "CPAN"
+Query, download and build perl modules from CPAN sites
+.IP CPAN::API::HOWTO 12
+.IX Item "CPAN::API::HOWTO"
+A recipe book for programming with CPAN.pm
+.IP CPAN::Debug 12
+.IX Item "CPAN::Debug"
+Internal debugging for CPAN.pm
+.IP CPAN::Distroprefs 12
+.IX Item "CPAN::Distroprefs"
+Read and match distroprefs
+.IP CPAN::FirstTime 12
+.IX Item "CPAN::FirstTime"
+Utility for CPAN::Config file Initialization
+.IP CPAN::HandleConfig 12
+.IX Item "CPAN::HandleConfig"
+Internal configuration handling for CPAN.pm
+.IP CPAN::Kwalify 12
+.IX Item "CPAN::Kwalify"
+Interface between CPAN.pm and Kwalify.pm
+.IP CPAN::Meta 12
+.IX Item "CPAN::Meta"
+The distribution metadata for a CPAN dist
+.IP CPAN::Meta::Converter 12
+.IX Item "CPAN::Meta::Converter"
+Convert CPAN distribution metadata structures
+.IP CPAN::Meta::Feature 12
+.IX Item "CPAN::Meta::Feature"
+An optional feature provided by a CPAN distribution
+.IP CPAN::Meta::History 12
+.IX Item "CPAN::Meta::History"
+History of CPAN Meta Spec changes
+.IP CPAN::Meta::History::Meta_1_0 12
+.IX Item "CPAN::Meta::History::Meta_1_0"
+Version 1.0 metadata specification for META.yml
+.IP CPAN::Meta::History::Meta_1_1 12
+.IX Item "CPAN::Meta::History::Meta_1_1"
+Version 1.1 metadata specification for META.yml
+.IP CPAN::Meta::History::Meta_1_2 12
+.IX Item "CPAN::Meta::History::Meta_1_2"
+Version 1.2 metadata specification for META.yml
+.IP CPAN::Meta::History::Meta_1_3 12
+.IX Item "CPAN::Meta::History::Meta_1_3"
+Version 1.3 metadata specification for META.yml
+.IP CPAN::Meta::History::Meta_1_4 12
+.IX Item "CPAN::Meta::History::Meta_1_4"
+Version 1.4 metadata specification for META.yml
+.IP CPAN::Meta::Merge 12
+.IX Item "CPAN::Meta::Merge"
+Merging CPAN Meta fragments
+.IP CPAN::Meta::Prereqs 12
+.IX Item "CPAN::Meta::Prereqs"
+A set of distribution prerequisites by phase and type
+.IP CPAN::Meta::Requirements 12
+.IX Item "CPAN::Meta::Requirements"
+A set of version requirements for a CPAN dist
+.IP CPAN::Meta::Spec 12
+.IX Item "CPAN::Meta::Spec"
+Specification for CPAN distribution metadata
+.IP CPAN::Meta::Validator 12
+.IX Item "CPAN::Meta::Validator"
+Validate CPAN distribution metadata structures
+.IP CPAN::Meta::YAML 12
+.IX Item "CPAN::Meta::YAML"
+Read and write a subset of YAML for CPAN Meta files
+.IP CPAN::Nox 12
+.IX Item "CPAN::Nox"
+Wrapper around CPAN.pm without using any XS module
+.IP CPAN::Plugin 12
+.IX Item "CPAN::Plugin"
+Base class for CPAN shell extensions
+.IP CPAN::Plugin::Specfile 12
+.IX Item "CPAN::Plugin::Specfile"
+Proof of concept implementation of a trivial CPAN::Plugin
+.IP CPAN::Queue 12
+.IX Item "CPAN::Queue"
+Internal queue support for CPAN.pm
+.IP CPAN::Tarzip 12
+.IX Item "CPAN::Tarzip"
+Internal handling of tar archives for CPAN.pm
+.IP CPAN::Version 12
+.IX Item "CPAN::Version"
+Utility functions to compare CPAN versions
+.IP Carp 12
+.IX Item "Carp"
+Alternative warn and die for modules
+.IP Class::Struct 12
+.IX Item "Class::Struct"
+Declare struct-like datatypes as Perl classes
+.IP Compress::Raw::Bzip2 12
+.IX Item "Compress::Raw::Bzip2"
+Low-Level Interface to bzip2 compression library
+.IP Compress::Raw::Zlib 12
+.IX Item "Compress::Raw::Zlib"
+Low-Level Interface to zlib or zlib-ng compression library
+.IP Compress::Zlib 12
+.IX Item "Compress::Zlib"
+Interface to zlib compression library
+.IP Config 12
+.IX Item "Config"
+Access Perl configuration information
+.IP Config::Extensions 12
+.IX Item "Config::Extensions"
+Hash lookup of which core extensions were built.
+.IP Config::Perl::V 12
+.IX Item "Config::Perl::V"
+Structured data retrieval of perl \-V output
+.IP Cwd 12
+.IX Item "Cwd"
+Get pathname of current working directory
+.IP DB 12
+.IX Item "DB"
+Programmatic interface to the Perl debugging API
+.IP DBM_Filter 12
+.IX Item "DBM_Filter"
+Filter DBM keys/values
+.IP DBM_Filter::compress 12
+.IX Item "DBM_Filter::compress"
+Filter for DBM_Filter
+.IP DBM_Filter::encode 12
+.IX Item "DBM_Filter::encode"
+Filter for DBM_Filter
+.IP DBM_Filter::int32 12
+.IX Item "DBM_Filter::int32"
+Filter for DBM_Filter
+.IP DBM_Filter::null 12
+.IX Item "DBM_Filter::null"
+Filter for DBM_Filter
+.IP DBM_Filter::utf8 12
+.IX Item "DBM_Filter::utf8"
+Filter for DBM_Filter
+.IP DB_File 12
+.IX Item "DB_File"
+Perl5 access to Berkeley DB version 1.x
+.IP Data::Dumper 12
+.IX Item "Data::Dumper"
+Stringified perl data structures, suitable for both printing and \f(CW\*(C`eval\*(C'\fR
+.IP Devel::PPPort 12
+.IX Item "Devel::PPPort"
+Perl/Pollution/Portability
+.IP Devel::Peek 12
+.IX Item "Devel::Peek"
+A data debugging tool for the XS programmer
+.IP Devel::SelfStubber 12
+.IX Item "Devel::SelfStubber"
+Generate stubs for a SelfLoading module
+.IP Digest 12
+.IX Item "Digest"
+Modules that calculate message digests
+.IP Digest::MD5 12
+.IX Item "Digest::MD5"
+Perl interface to the MD5 Algorithm
+.IP Digest::SHA 12
+.IX Item "Digest::SHA"
+Perl extension for SHA\-1/224/256/384/512
+.IP Digest::base 12
+.IX Item "Digest::base"
+Digest base class
+.IP Digest::file 12
+.IX Item "Digest::file"
+Calculate digests of files
+.IP DirHandle 12
+.IX Item "DirHandle"
+(obsolete) supply object methods for directory handles
+.IP Dumpvalue 12
+.IX Item "Dumpvalue"
+Provides screen dump of Perl data.
+.IP DynaLoader 12
+.IX Item "DynaLoader"
+Dynamically load C libraries into Perl code
+.IP Encode 12
+.IX Item "Encode"
+Character encodings in Perl
+.IP Encode::Alias 12
+.IX Item "Encode::Alias"
+Alias definitions to encodings
+.IP Encode::Byte 12
+.IX Item "Encode::Byte"
+Single Byte Encodings
+.IP Encode::CJKConstants 12
+.IX Item "Encode::CJKConstants"
+Internally used by Encode::??::ISO_2022_*
+.IP Encode::CN 12
+.IX Item "Encode::CN"
+China-based Chinese Encodings
+.IP Encode::CN::HZ 12
+.IX Item "Encode::CN::HZ"
+Internally used by Encode::CN
+.IP Encode::Config 12
+.IX Item "Encode::Config"
+Internally used by Encode
+.IP Encode::EBCDIC 12
+.IX Item "Encode::EBCDIC"
+EBCDIC Encodings
+.IP Encode::Encoder 12
+.IX Item "Encode::Encoder"
+Object Oriented Encoder
+.IP Encode::Encoding 12
+.IX Item "Encode::Encoding"
+Encode Implementation Base Class
+.IP Encode::GSM0338 12
+.IX Item "Encode::GSM0338"
+ETSI GSM 03.38 Encoding
+.IP Encode::Guess 12
+.IX Item "Encode::Guess"
+Guesses encoding from data
+.IP Encode::JP 12
+.IX Item "Encode::JP"
+Japanese Encodings
+.IP Encode::JP::H2Z 12
+.IX Item "Encode::JP::H2Z"
+Internally used by Encode::JP::2022_JP*
+.IP Encode::JP::JIS7 12
+.IX Item "Encode::JP::JIS7"
+Internally used by Encode::JP
+.IP Encode::KR 12
+.IX Item "Encode::KR"
+Korean Encodings
+.IP Encode::KR::2022_KR 12
+.IX Item "Encode::KR::2022_KR"
+Internally used by Encode::KR
+.IP Encode::MIME::Header 12
+.IX Item "Encode::MIME::Header"
+MIME encoding for an unstructured email header
+.IP Encode::MIME::Name 12
+.IX Item "Encode::MIME::Name"
+Internally used by Encode
+.IP Encode::PerlIO 12
+.IX Item "Encode::PerlIO"
+A detailed document on Encode and PerlIO
+.IP Encode::Supported 12
+.IX Item "Encode::Supported"
+Encodings supported by Encode
+.IP Encode::Symbol 12
+.IX Item "Encode::Symbol"
+Symbol Encodings
+.IP Encode::TW 12
+.IX Item "Encode::TW"
+Taiwan-based Chinese Encodings
+.IP Encode::Unicode 12
+.IX Item "Encode::Unicode"
+Various Unicode Transformation Formats
+.IP Encode::Unicode::UTF7 12
+.IX Item "Encode::Unicode::UTF7"
+UTF\-7 encoding
+.IP English 12
+.IX Item "English"
+Use nice English (or awk) names for ugly punctuation variables
+.IP Env 12
+.IX Item "Env"
+Perl module that imports environment variables as scalars or arrays
+.IP Errno 12
+.IX Item "Errno"
+System errno constants
+.IP Exporter 12
+.IX Item "Exporter"
+Implements default import method for modules
+.IP Exporter::Heavy 12
+.IX Item "Exporter::Heavy"
+Exporter guts
+.IP ExtUtils::CBuilder 12
+.IX Item "ExtUtils::CBuilder"
+Compile and link C code for Perl modules
+.IP ExtUtils::CBuilder::Platform::Windows 12
+.IX Item "ExtUtils::CBuilder::Platform::Windows"
+Builder class for Windows platforms
+.IP ExtUtils::Command 12
+.IX Item "ExtUtils::Command"
+Utilities to replace common UNIX commands in Makefiles etc.
+.IP ExtUtils::Command::MM 12
+.IX Item "ExtUtils::Command::MM"
+Commands for the MM's to use in Makefiles
+.IP ExtUtils::Constant 12
+.IX Item "ExtUtils::Constant"
+Generate XS code to import C header constants
+.IP ExtUtils::Constant::Base 12
+.IX Item "ExtUtils::Constant::Base"
+Base class for ExtUtils::Constant objects
+.IP ExtUtils::Constant::Utils 12
+.IX Item "ExtUtils::Constant::Utils"
+Helper functions for ExtUtils::Constant
+.IP ExtUtils::Constant::XS 12
+.IX Item "ExtUtils::Constant::XS"
+Generate C code for XS modules' constants.
+.IP ExtUtils::Embed 12
+.IX Item "ExtUtils::Embed"
+Utilities for embedding Perl in C/C++ applications
+.IP ExtUtils::Install 12
+.IX Item "ExtUtils::Install"
+Install files from here to there
+.IP ExtUtils::Installed 12
+.IX Item "ExtUtils::Installed"
+Inventory management of installed modules
+.IP ExtUtils::Liblist 12
+.IX Item "ExtUtils::Liblist"
+Determine libraries to use and how to use them
+.IP ExtUtils::MM 12
+.IX Item "ExtUtils::MM"
+OS adjusted ExtUtils::MakeMaker subclass
+.IP ExtUtils::MM::Utils 12
+.IX Item "ExtUtils::MM::Utils"
+ExtUtils::MM methods without dependency on ExtUtils::MakeMaker
+.IP ExtUtils::MM_AIX 12
+.IX Item "ExtUtils::MM_AIX"
+AIX specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_Any 12
+.IX Item "ExtUtils::MM_Any"
+Platform-agnostic MM methods
+.IP ExtUtils::MM_BeOS 12
+.IX Item "ExtUtils::MM_BeOS"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_Cygwin 12
+.IX Item "ExtUtils::MM_Cygwin"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_DOS 12
+.IX Item "ExtUtils::MM_DOS"
+DOS specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_Darwin 12
+.IX Item "ExtUtils::MM_Darwin"
+Special behaviors for OS X
+.IP ExtUtils::MM_MacOS 12
+.IX Item "ExtUtils::MM_MacOS"
+Once produced Makefiles for MacOS Classic
+.IP ExtUtils::MM_NW5 12
+.IX Item "ExtUtils::MM_NW5"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_OS2 12
+.IX Item "ExtUtils::MM_OS2"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_OS390 12
+.IX Item "ExtUtils::MM_OS390"
+OS390 specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_QNX 12
+.IX Item "ExtUtils::MM_QNX"
+QNX specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_UWIN 12
+.IX Item "ExtUtils::MM_UWIN"
+U/WIN specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_Unix 12
+.IX Item "ExtUtils::MM_Unix"
+Methods used by ExtUtils::MakeMaker
+.IP ExtUtils::MM_VMS 12
+.IX Item "ExtUtils::MM_VMS"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_VOS 12
+.IX Item "ExtUtils::MM_VOS"
+VOS specific subclass of ExtUtils::MM_Unix
+.IP ExtUtils::MM_Win32 12
+.IX Item "ExtUtils::MM_Win32"
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+.IP ExtUtils::MM_Win95 12
+.IX Item "ExtUtils::MM_Win95"
+Method to customize MakeMaker for Win9X
+.IP ExtUtils::MY 12
+.IX Item "ExtUtils::MY"
+ExtUtils::MakeMaker subclass for customization
+.IP ExtUtils::MakeMaker 12
+.IX Item "ExtUtils::MakeMaker"
+Create a module Makefile
+.IP ExtUtils::MakeMaker::Config 12
+.IX Item "ExtUtils::MakeMaker::Config"
+Wrapper around Config.pm
+.IP ExtUtils::MakeMaker::FAQ 12
+.IX Item "ExtUtils::MakeMaker::FAQ"
+Frequently Asked Questions About MakeMaker
+.IP ExtUtils::MakeMaker::Locale 12
+.IX Item "ExtUtils::MakeMaker::Locale"
+Bundled Encode::Locale
+.IP ExtUtils::MakeMaker::Tutorial 12
+.IX Item "ExtUtils::MakeMaker::Tutorial"
+Writing a module with MakeMaker
+.IP ExtUtils::Manifest 12
+.IX Item "ExtUtils::Manifest"
+Utilities to write and check a MANIFEST file
+.IP ExtUtils::Miniperl 12
+.IX Item "ExtUtils::Miniperl"
+Write the C code for miniperlmain.c and perlmain.c
+.IP ExtUtils::Mkbootstrap 12
+.IX Item "ExtUtils::Mkbootstrap"
+Make a bootstrap file for use by DynaLoader
+.IP ExtUtils::Mksymlists 12
+.IX Item "ExtUtils::Mksymlists"
+Write linker options files for dynamic extension
+.IP ExtUtils::PL2Bat 12
+.IX Item "ExtUtils::PL2Bat"
+Batch file creation to run perl scripts on Windows
+.IP ExtUtils::Packlist 12
+.IX Item "ExtUtils::Packlist"
+Manage .packlist files
+.IP ExtUtils::ParseXS 12
+.IX Item "ExtUtils::ParseXS"
+Converts Perl XS code into C code
+.IP ExtUtils::ParseXS::Constants 12
+.IX Item "ExtUtils::ParseXS::Constants"
+Initialization values for some globals
+.IP ExtUtils::ParseXS::Eval 12
+.IX Item "ExtUtils::ParseXS::Eval"
+Clean package to evaluate code in
+.IP ExtUtils::ParseXS::Utilities 12
+.IX Item "ExtUtils::ParseXS::Utilities"
+Subroutines used with ExtUtils::ParseXS
+.IP ExtUtils::Typemaps 12
+.IX Item "ExtUtils::Typemaps"
+Read/Write/Modify Perl/XS typemap files
+.IP ExtUtils::Typemaps::Cmd 12
+.IX Item "ExtUtils::Typemaps::Cmd"
+Quick commands for handling typemaps
+.IP ExtUtils::Typemaps::InputMap 12
+.IX Item "ExtUtils::Typemaps::InputMap"
+Entry in the INPUT section of a typemap
+.IP ExtUtils::Typemaps::OutputMap 12
+.IX Item "ExtUtils::Typemaps::OutputMap"
+Entry in the OUTPUT section of a typemap
+.IP ExtUtils::Typemaps::Type 12
+.IX Item "ExtUtils::Typemaps::Type"
+Entry in the TYPEMAP section of a typemap
+.IP ExtUtils::XSSymSet 12
+.IX Item "ExtUtils::XSSymSet"
+Keep sets of symbol names palatable to the VMS linker
+.IP ExtUtils::testlib 12
+.IX Item "ExtUtils::testlib"
+Add blib/* directories to \f(CW@INC\fR
+.IP Fatal 12
+.IX Item "Fatal"
+Replace functions with equivalents which succeed or die
+.IP Fcntl 12
+.IX Item "Fcntl"
+Load the C Fcntl.h defines
+.IP File::Basename 12
+.IX Item "File::Basename"
+Parse file paths into directory, filename and suffix.
+.IP File::Compare 12
+.IX Item "File::Compare"
+Compare files or filehandles
+.IP File::Copy 12
+.IX Item "File::Copy"
+Copy files or filehandles
+.IP File::DosGlob 12
+.IX Item "File::DosGlob"
+DOS like globbing and then some
+.IP File::Fetch 12
+.IX Item "File::Fetch"
+A generic file fetching mechanism
+.IP File::Find 12
+.IX Item "File::Find"
+Traverse a directory tree.
+.IP File::Glob 12
+.IX Item "File::Glob"
+Perl extension for BSD glob routine
+.IP File::GlobMapper 12
+.IX Item "File::GlobMapper"
+Extend File Glob to Allow Input and Output Files
+.IP File::Path 12
+.IX Item "File::Path"
+Create or remove directory trees
+.IP File::Spec 12
+.IX Item "File::Spec"
+Portably perform operations on file names
+.IP File::Spec::AmigaOS 12
+.IX Item "File::Spec::AmigaOS"
+File::Spec for AmigaOS
+.IP File::Spec::Cygwin 12
+.IX Item "File::Spec::Cygwin"
+Methods for Cygwin file specs
+.IP File::Spec::Epoc 12
+.IX Item "File::Spec::Epoc"
+Methods for Epoc file specs
+.IP File::Spec::Functions 12
+.IX Item "File::Spec::Functions"
+Portably perform operations on file names
+.IP File::Spec::Mac 12
+.IX Item "File::Spec::Mac"
+File::Spec for Mac OS (Classic)
+.IP File::Spec::OS2 12
+.IX Item "File::Spec::OS2"
+Methods for OS/2 file specs
+.IP File::Spec::Unix 12
+.IX Item "File::Spec::Unix"
+File::Spec for Unix, base for other File::Spec modules
+.IP File::Spec::VMS 12
+.IX Item "File::Spec::VMS"
+Methods for VMS file specs
+.IP File::Spec::Win32 12
+.IX Item "File::Spec::Win32"
+Methods for Win32 file specs
+.IP File::Temp 12
+.IX Item "File::Temp"
+Return name and handle of a temporary file safely
+.IP File::stat 12
+.IX Item "File::stat"
+By-name interface to Perl's built-in \fBstat()\fR functions
+.IP FileCache 12
+.IX Item "FileCache"
+Keep more files open than the system permits
+.IP FileHandle 12
+.IX Item "FileHandle"
+Supply object methods for filehandles
+.IP Filter::Simple 12
+.IX Item "Filter::Simple"
+Simplified source filtering
+.IP Filter::Util::Call 12
+.IX Item "Filter::Util::Call"
+Perl Source Filter Utility Module
+.IP FindBin 12
+.IX Item "FindBin"
+Locate directory of original perl script
+.IP GDBM_File 12
+.IX Item "GDBM_File"
+Perl5 access to the gdbm library.
+.IP Getopt::Long 12
+.IX Item "Getopt::Long"
+Extended processing of command line options
+.IP Getopt::Std 12
+.IX Item "Getopt::Std"
+Process single-character switches with switch clustering
+.IP HTTP::Tiny 12
+.IX Item "HTTP::Tiny"
+A small, simple, correct HTTP/1.1 client
+.IP Hash::Util 12
+.IX Item "Hash::Util"
+A selection of general-utility hash subroutines
+.IP Hash::Util::FieldHash 12
+.IX Item "Hash::Util::FieldHash"
+Support for Inside-Out Classes
+.IP I18N::Collate 12
+.IX Item "I18N::Collate"
+Compare 8\-bit scalar data according to the current locale
+.IP I18N::LangTags 12
+.IX Item "I18N::LangTags"
+Functions for dealing with RFC3066\-style language tags
+.IP I18N::LangTags::Detect 12
+.IX Item "I18N::LangTags::Detect"
+Detect the user's language preferences
+.IP I18N::LangTags::List 12
+.IX Item "I18N::LangTags::List"
+Tags and names for human languages
+.IP I18N::Langinfo 12
+.IX Item "I18N::Langinfo"
+Query locale information
+.IP IO 12
+.IX Item "IO"
+Load various IO modules
+.IP IO::Compress::Base 12
+.IX Item "IO::Compress::Base"
+Base Class for IO::Compress modules
+.IP IO::Compress::Bzip2 12
+.IX Item "IO::Compress::Bzip2"
+Write bzip2 files/buffers
+.IP IO::Compress::Deflate 12
+.IX Item "IO::Compress::Deflate"
+Write RFC 1950 files/buffers
+.IP IO::Compress::FAQ 12
+.IX Item "IO::Compress::FAQ"
+Frequently Asked Questions about IO::Compress
+.IP IO::Compress::Gzip 12
+.IX Item "IO::Compress::Gzip"
+Write RFC 1952 files/buffers
+.IP IO::Compress::RawDeflate 12
+.IX Item "IO::Compress::RawDeflate"
+Write RFC 1951 files/buffers
+.IP IO::Compress::Zip 12
+.IX Item "IO::Compress::Zip"
+Write zip files/buffers
+.IP IO::Dir 12
+.IX Item "IO::Dir"
+Supply object methods for directory handles
+.IP IO::File 12
+.IX Item "IO::File"
+Supply object methods for filehandles
+.IP IO::Handle 12
+.IX Item "IO::Handle"
+Supply object methods for I/O handles
+.IP IO::Pipe 12
+.IX Item "IO::Pipe"
+Supply object methods for pipes
+.IP IO::Poll 12
+.IX Item "IO::Poll"
+Object interface to system poll call
+.IP IO::Seekable 12
+.IX Item "IO::Seekable"
+Supply seek based methods for I/O objects
+.IP IO::Select 12
+.IX Item "IO::Select"
+OO interface to the select system call
+.IP IO::Socket 12
+.IX Item "IO::Socket"
+Object interface to socket communications
+.IP IO::Socket::INET 12
+.IX Item "IO::Socket::INET"
+Object interface for AF_INET domain sockets
+.IP IO::Socket::UNIX 12
+.IX Item "IO::Socket::UNIX"
+Object interface for AF_UNIX domain sockets
+.IP IO::Uncompress::AnyInflate 12
+.IX Item "IO::Uncompress::AnyInflate"
+Uncompress zlib-based (zip, gzip) file/buffer
+.IP IO::Uncompress::AnyUncompress 12
+.IX Item "IO::Uncompress::AnyUncompress"
+Uncompress gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or lzop file/buffer
+.IP IO::Uncompress::Base 12
+.IX Item "IO::Uncompress::Base"
+Base Class for IO::Uncompress modules
+.IP IO::Uncompress::Bunzip2 12
+.IX Item "IO::Uncompress::Bunzip2"
+Read bzip2 files/buffers
+.IP IO::Uncompress::Gunzip 12
+.IX Item "IO::Uncompress::Gunzip"
+Read RFC 1952 files/buffers
+.IP IO::Uncompress::Inflate 12
+.IX Item "IO::Uncompress::Inflate"
+Read RFC 1950 files/buffers
+.IP IO::Uncompress::RawInflate 12
+.IX Item "IO::Uncompress::RawInflate"
+Read RFC 1951 files/buffers
+.IP IO::Uncompress::Unzip 12
+.IX Item "IO::Uncompress::Unzip"
+Read zip files/buffers
+.IP IO::Zlib 12
+.IX Item "IO::Zlib"
+IO:: style interface to Compress::Zlib
+.IP IPC::Cmd 12
+.IX Item "IPC::Cmd"
+Finding and running system commands made easy
+.IP IPC::Msg 12
+.IX Item "IPC::Msg"
+SysV Msg IPC object class
+.IP IPC::Open2 12
+.IX Item "IPC::Open2"
+Open a process for both reading and writing using \fBopen2()\fR
+.IP IPC::Open3 12
+.IX Item "IPC::Open3"
+Open a process for reading, writing, and error handling using \fBopen3()\fR
+.IP IPC::Semaphore 12
+.IX Item "IPC::Semaphore"
+SysV Semaphore IPC object class
+.IP IPC::SharedMem 12
+.IX Item "IPC::SharedMem"
+SysV Shared Memory IPC object class
+.IP IPC::SysV 12
+.IX Item "IPC::SysV"
+System V IPC constants and system calls
+.IP Internals 12
+.IX Item "Internals"
+Reserved special namespace for internals related functions
+.IP JSON::PP 12
+.IX Item "JSON::PP"
+JSON::XS compatible pure-Perl module.
+.IP JSON::PP::Boolean 12
+.IX Item "JSON::PP::Boolean"
+Dummy module providing JSON::PP::Boolean
+.IP List::Util 12
+.IX Item "List::Util"
+A selection of general-utility list subroutines
+.IP List::Util::XS 12
+.IX Item "List::Util::XS"
+Indicate if List::Util was compiled with a C compiler
+.IP Locale::Maketext 12
+.IX Item "Locale::Maketext"
+Framework for localization
+.IP Locale::Maketext::Cookbook 12
+.IX Item "Locale::Maketext::Cookbook"
+Recipes for using Locale::Maketext
+.IP Locale::Maketext::Guts 12
+.IX Item "Locale::Maketext::Guts"
+Deprecated module to load Locale::Maketext utf8 code
+.IP Locale::Maketext::GutsLoader 12
+.IX Item "Locale::Maketext::GutsLoader"
+Deprecated module to load Locale::Maketext utf8 code
+.IP Locale::Maketext::Simple 12
+.IX Item "Locale::Maketext::Simple"
+Simple interface to Locale::Maketext::Lexicon
+.IP Locale::Maketext::TPJ13 12
+.IX Item "Locale::Maketext::TPJ13"
+Article about software localization
+.IP MIME::Base64 12
+.IX Item "MIME::Base64"
+Encoding and decoding of base64 strings
+.IP MIME::QuotedPrint 12
+.IX Item "MIME::QuotedPrint"
+Encoding and decoding of quoted-printable strings
+.IP Math::BigFloat 12
+.IX Item "Math::BigFloat"
+Arbitrary size floating point math package
+.IP Math::BigInt 12
+.IX Item "Math::BigInt"
+Arbitrary size integer math package
+.IP Math::BigInt::Calc 12
+.IX Item "Math::BigInt::Calc"
+Pure Perl module to support Math::BigInt
+.IP Math::BigInt::FastCalc 12
+.IX Item "Math::BigInt::FastCalc"
+Math::BigInt::Calc with some XS for more speed
+.IP Math::BigInt::Lib 12
+.IX Item "Math::BigInt::Lib"
+Virtual parent class for Math::BigInt libraries
+.IP Math::BigRat 12
+.IX Item "Math::BigRat"
+Arbitrary size rational number math package
+.IP Math::Complex 12
+.IX Item "Math::Complex"
+Complex numbers and associated mathematical functions
+.IP Math::Trig 12
+.IX Item "Math::Trig"
+Trigonometric functions
+.IP Memoize 12
+.IX Item "Memoize"
+Make functions faster by trading space for time
+.IP Memoize::AnyDBM_File 12
+.IX Item "Memoize::AnyDBM_File"
+Glue to provide EXISTS for AnyDBM_File for Storable use
+.IP Memoize::Expire 12
+.IX Item "Memoize::Expire"
+Plug-in module for automatic expiration of memoized values
+.IP Memoize::NDBM_File 12
+.IX Item "Memoize::NDBM_File"
+Glue to provide EXISTS for NDBM_File for Storable use
+.IP Memoize::SDBM_File 12
+.IX Item "Memoize::SDBM_File"
+DEPRECATED compability shim
+.IP Memoize::Storable 12
+.IX Item "Memoize::Storable"
+Store Memoized data in Storable database
+.IP Module::CoreList 12
+.IX Item "Module::CoreList"
+What modules shipped with versions of perl
+.IP Module::CoreList::Utils 12
+.IX Item "Module::CoreList::Utils"
+What utilities shipped with versions of perl
+.IP Module::Load 12
+.IX Item "Module::Load"
+Runtime require of both modules and files
+.IP Module::Load::Conditional 12
+.IX Item "Module::Load::Conditional"
+Looking up module information / loading at runtime
+.IP Module::Loaded 12
+.IX Item "Module::Loaded"
+Mark modules as loaded or unloaded
+.IP Module::Metadata 12
+.IX Item "Module::Metadata"
+Gather package and POD information from perl module files
+.IP NDBM_File 12
+.IX Item "NDBM_File"
+Tied access to ndbm files
+.IP NEXT 12
+.IX Item "NEXT"
+Provide a pseudo-class NEXT (et al) that allows method redispatch
+.IP Net::Cmd 12
+.IX Item "Net::Cmd"
+Network Command class (as used by FTP, SMTP etc)
+.IP Net::Config 12
+.IX Item "Net::Config"
+Local configuration data for libnet
+.IP Net::Domain 12
+.IX Item "Net::Domain"
+Attempt to evaluate the current host's internet name and domain
+.IP Net::FTP 12
+.IX Item "Net::FTP"
+FTP Client class
+.IP Net::FTP::dataconn 12
+.IX Item "Net::FTP::dataconn"
+FTP Client data connection class
+.IP Net::NNTP 12
+.IX Item "Net::NNTP"
+NNTP Client class
+.IP Net::Netrc 12
+.IX Item "Net::Netrc"
+OO interface to users netrc file
+.IP Net::POP3 12
+.IX Item "Net::POP3"
+Post Office Protocol 3 Client class (RFC1939)
+.IP Net::Ping 12
+.IX Item "Net::Ping"
+Check a remote host for reachability
+.IP Net::SMTP 12
+.IX Item "Net::SMTP"
+Simple Mail Transfer Protocol Client
+.IP Net::Time 12
+.IX Item "Net::Time"
+Time and daytime network client interface
+.IP Net::hostent 12
+.IX Item "Net::hostent"
+By-name interface to Perl's built-in gethost*() functions
+.IP Net::libnetFAQ 12
+.IX Item "Net::libnetFAQ"
+Libnet Frequently Asked Questions
+.IP Net::netent 12
+.IX Item "Net::netent"
+By-name interface to Perl's built-in getnet*() functions
+.IP Net::protoent 12
+.IX Item "Net::protoent"
+By-name interface to Perl's built-in getproto*() functions
+.IP Net::servent 12
+.IX Item "Net::servent"
+By-name interface to Perl's built-in getserv*() functions
+.IP O 12
+.IX Item "O"
+Generic interface to Perl Compiler backends
+.IP ODBM_File 12
+.IX Item "ODBM_File"
+Tied access to odbm files
+.IP Opcode 12
+.IX Item "Opcode"
+Disable named opcodes when compiling perl code
+.IP POSIX 12
+.IX Item "POSIX"
+Perl interface to IEEE Std 1003.1
+.IP Params::Check 12
+.IX Item "Params::Check"
+A generic input parsing/checking mechanism.
+.IP Parse::CPAN::Meta 12
+.IX Item "Parse::CPAN::Meta"
+Parse META.yml and META.json CPAN metadata files
+.IP Perl::OSType 12
+.IX Item "Perl::OSType"
+Map Perl operating system names to generic types
+.IP PerlIO 12
+.IX Item "PerlIO"
+On demand loader for PerlIO layers and root of PerlIO::* name space
+.IP PerlIO::encoding 12
+.IX Item "PerlIO::encoding"
+Encoding layer
+.IP PerlIO::mmap 12
+.IX Item "PerlIO::mmap"
+Memory mapped IO
+.IP PerlIO::scalar 12
+.IX Item "PerlIO::scalar"
+In-memory IO, scalar IO
+.IP PerlIO::via 12
+.IX Item "PerlIO::via"
+Helper class for PerlIO layers implemented in perl
+.IP PerlIO::via::QuotedPrint 12
+.IX Item "PerlIO::via::QuotedPrint"
+PerlIO layer for quoted-printable strings
+.IP Pod::Checker 12
+.IX Item "Pod::Checker"
+Check pod documents for syntax errors
+.IP Pod::Escapes 12
+.IX Item "Pod::Escapes"
+For resolving Pod E<...> sequences
+.IP Pod::Functions 12
+.IX Item "Pod::Functions"
+Group Perl's functions a la perlfunc.pod
+.IP Pod::Html 12
+.IX Item "Pod::Html"
+Module to convert pod files to HTML
+.IP Pod::Html::Util 12
+.IX Item "Pod::Html::Util"
+Helper functions for Pod-Html
+.IP Pod::Man 12
+.IX Item "Pod::Man"
+Convert POD data to formatted *roff input
+.IP Pod::ParseLink 12
+.IX Item "Pod::ParseLink"
+Parse an L<> formatting code in POD text
+.IP Pod::Perldoc 12
+.IX Item "Pod::Perldoc"
+Look up Perl documentation in Pod format.
+.IP Pod::Perldoc::BaseTo 12
+.IX Item "Pod::Perldoc::BaseTo"
+Base for Pod::Perldoc formatters
+.IP Pod::Perldoc::GetOptsOO 12
+.IX Item "Pod::Perldoc::GetOptsOO"
+Customized option parser for Pod::Perldoc
+.IP Pod::Perldoc::ToANSI 12
+.IX Item "Pod::Perldoc::ToANSI"
+Render Pod with ANSI color escapes
+.IP Pod::Perldoc::ToChecker 12
+.IX Item "Pod::Perldoc::ToChecker"
+Let Perldoc check Pod for errors
+.IP Pod::Perldoc::ToMan 12
+.IX Item "Pod::Perldoc::ToMan"
+Let Perldoc render Pod as man pages
+.IP Pod::Perldoc::ToNroff 12
+.IX Item "Pod::Perldoc::ToNroff"
+Let Perldoc convert Pod to nroff
+.IP Pod::Perldoc::ToPod 12
+.IX Item "Pod::Perldoc::ToPod"
+Let Perldoc render Pod as ... Pod!
+.IP Pod::Perldoc::ToRtf 12
+.IX Item "Pod::Perldoc::ToRtf"
+Let Perldoc render Pod as RTF
+.IP Pod::Perldoc::ToTerm 12
+.IX Item "Pod::Perldoc::ToTerm"
+Render Pod with terminal escapes
+.IP Pod::Perldoc::ToText 12
+.IX Item "Pod::Perldoc::ToText"
+Let Perldoc render Pod as plaintext
+.IP Pod::Perldoc::ToTk 12
+.IX Item "Pod::Perldoc::ToTk"
+Let Perldoc use Tk::Pod to render Pod
+.IP Pod::Perldoc::ToXml 12
+.IX Item "Pod::Perldoc::ToXml"
+Let Perldoc render Pod as XML
+.IP Pod::Simple 12
+.IX Item "Pod::Simple"
+Framework for parsing Pod
+.IP Pod::Simple::Checker 12
+.IX Item "Pod::Simple::Checker"
+Check the Pod syntax of a document
+.IP Pod::Simple::Debug 12
+.IX Item "Pod::Simple::Debug"
+Put Pod::Simple into trace/debug mode
+.IP Pod::Simple::DumpAsText 12
+.IX Item "Pod::Simple::DumpAsText"
+Dump Pod-parsing events as text
+.IP Pod::Simple::DumpAsXML 12
+.IX Item "Pod::Simple::DumpAsXML"
+Turn Pod into XML
+.IP Pod::Simple::HTML 12
+.IX Item "Pod::Simple::HTML"
+Convert Pod to HTML
+.IP Pod::Simple::HTMLBatch 12
+.IX Item "Pod::Simple::HTMLBatch"
+Convert several Pod files to several HTML files
+.IP Pod::Simple::JustPod 12
+.IX Item "Pod::Simple::JustPod"
+Just the Pod, the whole Pod, and nothing but the Pod
+.IP Pod::Simple::LinkSection 12
+.IX Item "Pod::Simple::LinkSection"
+Represent "section" attributes of L codes
+.IP Pod::Simple::Methody 12
+.IX Item "Pod::Simple::Methody"
+Turn Pod::Simple events into method calls
+.IP Pod::Simple::PullParser 12
+.IX Item "Pod::Simple::PullParser"
+A pull-parser interface to parsing Pod
+.IP Pod::Simple::PullParserEndToken 12
+.IX Item "Pod::Simple::PullParserEndToken"
+End-tokens from Pod::Simple::PullParser
+.IP Pod::Simple::PullParserStartToken 12
+.IX Item "Pod::Simple::PullParserStartToken"
+Start-tokens from Pod::Simple::PullParser
+.IP Pod::Simple::PullParserTextToken 12
+.IX Item "Pod::Simple::PullParserTextToken"
+Text-tokens from Pod::Simple::PullParser
+.IP Pod::Simple::PullParserToken 12
+.IX Item "Pod::Simple::PullParserToken"
+Tokens from Pod::Simple::PullParser
+.IP Pod::Simple::RTF 12
+.IX Item "Pod::Simple::RTF"
+Format Pod as RTF
+.IP Pod::Simple::Search 12
+.IX Item "Pod::Simple::Search"
+Find POD documents in directory trees
+.IP Pod::Simple::SimpleTree 12
+.IX Item "Pod::Simple::SimpleTree"
+Parse Pod into a simple parse tree
+.IP Pod::Simple::Subclassing 12
+.IX Item "Pod::Simple::Subclassing"
+Write a formatter as a Pod::Simple subclass
+.IP Pod::Simple::Text 12
+.IX Item "Pod::Simple::Text"
+Format Pod as plaintext
+.IP Pod::Simple::TextContent 12
+.IX Item "Pod::Simple::TextContent"
+Get the text content of Pod
+.IP Pod::Simple::XHTML 12
+.IX Item "Pod::Simple::XHTML"
+Format Pod as validating XHTML
+.IP Pod::Simple::XMLOutStream 12
+.IX Item "Pod::Simple::XMLOutStream"
+Turn Pod into XML
+.IP Pod::Text 12
+.IX Item "Pod::Text"
+Convert POD data to formatted text
+.IP Pod::Text::Color 12
+.IX Item "Pod::Text::Color"
+Convert POD data to formatted color ASCII text
+.IP Pod::Text::Overstrike 12
+.IX Item "Pod::Text::Overstrike"
+Convert POD data to formatted overstrike text
+.IP Pod::Text::Termcap 12
+.IX Item "Pod::Text::Termcap"
+Convert POD data to ASCII text with format escapes
+.IP Pod::Usage 12
+.IX Item "Pod::Usage"
+Extracts POD documentation and shows usage information
+.IP SDBM_File 12
+.IX Item "SDBM_File"
+Tied access to sdbm files
+.IP Safe 12
+.IX Item "Safe"
+Compile and execute code in restricted compartments
+.IP Scalar::Util 12
+.IX Item "Scalar::Util"
+A selection of general-utility scalar subroutines
+.IP Search::Dict 12
+.IX Item "Search::Dict"
+Look \- search for key in dictionary file
+.IP SelectSaver 12
+.IX Item "SelectSaver"
+Save and restore selected file handle
+.IP SelfLoader 12
+.IX Item "SelfLoader"
+Load functions only on demand
+.IP Storable 12
+.IX Item "Storable"
+Persistence for Perl data structures
+.IP Sub::Util 12
+.IX Item "Sub::Util"
+A selection of utility subroutines for subs and CODE references
+.IP Symbol 12
+.IX Item "Symbol"
+Manipulate Perl symbols and their names
+.IP Sys::Hostname 12
+.IX Item "Sys::Hostname"
+Try every conceivable way to get hostname
+.IP Sys::Syslog 12
+.IX Item "Sys::Syslog"
+Perl interface to the UNIX \fBsyslog\fR\|(3) calls
+.IP Sys::Syslog::Win32 12
+.IX Item "Sys::Syslog::Win32"
+Win32 support for Sys::Syslog
+.IP TAP::Base 12
+.IX Item "TAP::Base"
+Base class that provides common functionality to TAP::Parser
+.IP TAP::Formatter::Base 12
+.IX Item "TAP::Formatter::Base"
+Base class for harness output delegates
+.IP TAP::Formatter::Color 12
+.IX Item "TAP::Formatter::Color"
+Run Perl test scripts with color
+.IP TAP::Formatter::Console 12
+.IX Item "TAP::Formatter::Console"
+Harness output delegate for default console output
+.IP TAP::Formatter::Console::ParallelSession 12
+.IX Item "TAP::Formatter::Console::ParallelSession"
+Harness output delegate for parallel console output
+.IP TAP::Formatter::Console::Session 12
+.IX Item "TAP::Formatter::Console::Session"
+Harness output delegate for default console output
+.IP TAP::Formatter::File 12
+.IX Item "TAP::Formatter::File"
+Harness output delegate for file output
+.IP TAP::Formatter::File::Session 12
+.IX Item "TAP::Formatter::File::Session"
+Harness output delegate for file output
+.IP TAP::Formatter::Session 12
+.IX Item "TAP::Formatter::Session"
+Abstract base class for harness output delegate
+.IP TAP::Harness 12
+.IX Item "TAP::Harness"
+Run test scripts with statistics
+.IP TAP::Harness::Env 12
+.IX Item "TAP::Harness::Env"
+Parsing harness related environmental variables where appropriate
+.IP TAP::Object 12
+.IX Item "TAP::Object"
+Base class that provides common functionality to all \f(CW\*(C`TAP::*\*(C'\fR modules
+.IP TAP::Parser 12
+.IX Item "TAP::Parser"
+Parse TAP output
+.IP TAP::Parser::Aggregator 12
+.IX Item "TAP::Parser::Aggregator"
+Aggregate TAP::Parser results
+.IP TAP::Parser::Grammar 12
+.IX Item "TAP::Parser::Grammar"
+A grammar for the Test Anything Protocol.
+.IP TAP::Parser::Iterator 12
+.IX Item "TAP::Parser::Iterator"
+Base class for TAP source iterators
+.IP TAP::Parser::Iterator::Array 12
+.IX Item "TAP::Parser::Iterator::Array"
+Iterator for array-based TAP sources
+.IP TAP::Parser::Iterator::Process 12
+.IX Item "TAP::Parser::Iterator::Process"
+Iterator for process-based TAP sources
+.IP TAP::Parser::Iterator::Stream 12
+.IX Item "TAP::Parser::Iterator::Stream"
+Iterator for filehandle-based TAP sources
+.IP TAP::Parser::IteratorFactory 12
+.IX Item "TAP::Parser::IteratorFactory"
+Figures out which SourceHandler objects to use for a given Source
+.IP TAP::Parser::Multiplexer 12
+.IX Item "TAP::Parser::Multiplexer"
+Multiplex multiple TAP::Parsers
+.IP TAP::Parser::Result 12
+.IX Item "TAP::Parser::Result"
+Base class for TAP::Parser output objects
+.IP TAP::Parser::Result::Bailout 12
+.IX Item "TAP::Parser::Result::Bailout"
+Bailout result token.
+.IP TAP::Parser::Result::Comment 12
+.IX Item "TAP::Parser::Result::Comment"
+Comment result token.
+.IP TAP::Parser::Result::Plan 12
+.IX Item "TAP::Parser::Result::Plan"
+Plan result token.
+.IP TAP::Parser::Result::Pragma 12
+.IX Item "TAP::Parser::Result::Pragma"
+TAP pragma token.
+.IP TAP::Parser::Result::Test 12
+.IX Item "TAP::Parser::Result::Test"
+Test result token.
+.IP TAP::Parser::Result::Unknown 12
+.IX Item "TAP::Parser::Result::Unknown"
+Unknown result token.
+.IP TAP::Parser::Result::Version 12
+.IX Item "TAP::Parser::Result::Version"
+TAP syntax version token.
+.IP TAP::Parser::Result::YAML 12
+.IX Item "TAP::Parser::Result::YAML"
+YAML result token.
+.IP TAP::Parser::ResultFactory 12
+.IX Item "TAP::Parser::ResultFactory"
+Factory for creating TAP::Parser output objects
+.IP TAP::Parser::Scheduler 12
+.IX Item "TAP::Parser::Scheduler"
+Schedule tests during parallel testing
+.IP TAP::Parser::Scheduler::Job 12
+.IX Item "TAP::Parser::Scheduler::Job"
+A single testing job.
+.IP TAP::Parser::Scheduler::Spinner 12
+.IX Item "TAP::Parser::Scheduler::Spinner"
+A no-op job.
+.IP TAP::Parser::Source 12
+.IX Item "TAP::Parser::Source"
+A TAP source & meta data about it
+.IP TAP::Parser::SourceHandler 12
+.IX Item "TAP::Parser::SourceHandler"
+Base class for different TAP source handlers
+.IP TAP::Parser::SourceHandler::Executable 12
+.IX Item "TAP::Parser::SourceHandler::Executable"
+Stream output from an executable TAP source
+.IP TAP::Parser::SourceHandler::File 12
+.IX Item "TAP::Parser::SourceHandler::File"
+Stream TAP from a text file.
+.IP TAP::Parser::SourceHandler::Handle 12
+.IX Item "TAP::Parser::SourceHandler::Handle"
+Stream TAP from an IO::Handle or a GLOB.
+.IP TAP::Parser::SourceHandler::Perl 12
+.IX Item "TAP::Parser::SourceHandler::Perl"
+Stream TAP from a Perl executable
+.IP TAP::Parser::SourceHandler::RawTAP 12
+.IX Item "TAP::Parser::SourceHandler::RawTAP"
+Stream output from raw TAP in a scalar/array ref.
+.IP TAP::Parser::YAMLish::Reader 12
+.IX Item "TAP::Parser::YAMLish::Reader"
+Read YAMLish data from iterator
+.IP TAP::Parser::YAMLish::Writer 12
+.IX Item "TAP::Parser::YAMLish::Writer"
+Write YAMLish data
+.IP Term::ANSIColor 12
+.IX Item "Term::ANSIColor"
+Color screen output using ANSI escape sequences
+.IP Term::Cap 12
+.IX Item "Term::Cap"
+Perl termcap interface
+.IP Term::Complete 12
+.IX Item "Term::Complete"
+Perl word completion module
+.IP Term::ReadLine 12
+.IX Item "Term::ReadLine"
+Perl interface to various \f(CW\*(C`readline\*(C'\fR packages.
+.IP Test 12
+.IX Item "Test"
+Provides a simple framework for writing test scripts
+.IP Test2 12
+.IX Item "Test2"
+Framework for writing test tools that all work together.
+.IP Test2::API 12
+.IX Item "Test2::API"
+Primary interface for writing Test2 based testing tools.
+.IP Test2::API::Breakage 12
+.IX Item "Test2::API::Breakage"
+What breaks at what version
+.IP Test2::API::Context 12
+.IX Item "Test2::API::Context"
+Object to represent a testing context.
+.IP Test2::API::Instance 12
+.IX Item "Test2::API::Instance"
+Object used by Test2::API under the hood
+.IP Test2::API::InterceptResult 12
+.IX Item "Test2::API::InterceptResult"
+Representation of a list of events.
+.IP Test2::API::InterceptResult::Event 12
+.IX Item "Test2::API::InterceptResult::Event"
+Representation of an event for use in
+.IP Test2::API::InterceptResult::Hub 12
+.IX Item "Test2::API::InterceptResult::Hub"
+Hub used by InterceptResult.
+.IP Test2::API::InterceptResult::Squasher 12
+.IX Item "Test2::API::InterceptResult::Squasher"
+Encapsulation of the algorithm that
+.IP Test2::API::Stack 12
+.IX Item "Test2::API::Stack"
+Object to manage a stack of Test2::Hub
+.IP Test2::Event 12
+.IX Item "Test2::Event"
+Base class for events
+.IP Test2::Event::Bail 12
+.IX Item "Test2::Event::Bail"
+Bailout!
+.IP Test2::Event::Diag 12
+.IX Item "Test2::Event::Diag"
+Diag event type
+.IP Test2::Event::Encoding 12
+.IX Item "Test2::Event::Encoding"
+Set the encoding for the output stream
+.IP Test2::Event::Exception 12
+.IX Item "Test2::Event::Exception"
+Exception event
+.IP Test2::Event::Fail 12
+.IX Item "Test2::Event::Fail"
+Event for a simple failed assertion
+.IP Test2::Event::Generic 12
+.IX Item "Test2::Event::Generic"
+Generic event type.
+.IP Test2::Event::Note 12
+.IX Item "Test2::Event::Note"
+Note event type
+.IP Test2::Event::Ok 12
+.IX Item "Test2::Event::Ok"
+Ok event type
+.IP Test2::Event::Pass 12
+.IX Item "Test2::Event::Pass"
+Event for a simple passing assertion
+.IP Test2::Event::Plan 12
+.IX Item "Test2::Event::Plan"
+The event of a plan
+.IP Test2::Event::Skip 12
+.IX Item "Test2::Event::Skip"
+Skip event type
+.IP Test2::Event::Subtest 12
+.IX Item "Test2::Event::Subtest"
+Event for subtest types
+.IP Test2::Event::TAP::Version 12
+.IX Item "Test2::Event::TAP::Version"
+Event for TAP version.
+.IP Test2::Event::V2 12
+.IX Item "Test2::Event::V2"
+Second generation event.
+.IP Test2::Event::Waiting 12
+.IX Item "Test2::Event::Waiting"
+Tell all procs/threads it is time to be done
+.IP Test2::EventFacet 12
+.IX Item "Test2::EventFacet"
+Base class for all event facets.
+.IP Test2::EventFacet::About 12
+.IX Item "Test2::EventFacet::About"
+Facet with event details.
+.IP Test2::EventFacet::Amnesty 12
+.IX Item "Test2::EventFacet::Amnesty"
+Facet for assertion amnesty.
+.IP Test2::EventFacet::Assert 12
+.IX Item "Test2::EventFacet::Assert"
+Facet representing an assertion.
+.IP Test2::EventFacet::Control 12
+.IX Item "Test2::EventFacet::Control"
+Facet for hub actions and behaviors.
+.IP Test2::EventFacet::Error 12
+.IX Item "Test2::EventFacet::Error"
+Facet for errors that need to be shown.
+.IP Test2::EventFacet::Hub 12
+.IX Item "Test2::EventFacet::Hub"
+Facet for the hubs an event passes through.
+.IP Test2::EventFacet::Info 12
+.IX Item "Test2::EventFacet::Info"
+Facet for information a developer might care about.
+.IP Test2::EventFacet::Info::Table 12
+.IX Item "Test2::EventFacet::Info::Table"
+Intermediary representation of a table.
+.IP Test2::EventFacet::Meta 12
+.IX Item "Test2::EventFacet::Meta"
+Facet for meta-data
+.IP Test2::EventFacet::Parent 12
+.IX Item "Test2::EventFacet::Parent"
+Facet for events contains other events
+.IP Test2::EventFacet::Plan 12
+.IX Item "Test2::EventFacet::Plan"
+Facet for setting the plan
+.IP Test2::EventFacet::Render 12
+.IX Item "Test2::EventFacet::Render"
+Facet that dictates how to render an event.
+.IP Test2::EventFacet::Trace 12
+.IX Item "Test2::EventFacet::Trace"
+Debug information for events
+.IP Test2::Formatter 12
+.IX Item "Test2::Formatter"
+Namespace for formatters.
+.IP Test2::Formatter::TAP 12
+.IX Item "Test2::Formatter::TAP"
+Standard TAP formatter
+.IP Test2::Hub 12
+.IX Item "Test2::Hub"
+The conduit through which all events flow.
+.IP Test2::Hub::Interceptor 12
+.IX Item "Test2::Hub::Interceptor"
+Hub used by interceptor to grab results.
+.IP Test2::Hub::Interceptor::Terminator 12
+.IX Item "Test2::Hub::Interceptor::Terminator"
+Exception class used by
+.IP Test2::Hub::Subtest 12
+.IX Item "Test2::Hub::Subtest"
+Hub used by subtests
+.IP Test2::IPC 12
+.IX Item "Test2::IPC"
+Turn on IPC for threading or forking support.
+.IP Test2::IPC::Driver 12
+.IX Item "Test2::IPC::Driver"
+Base class for Test2 IPC drivers.
+.IP Test2::IPC::Driver::Files 12
+.IX Item "Test2::IPC::Driver::Files"
+Temp dir + Files concurrency model.
+.IP Test2::Tools::Tiny 12
+.IX Item "Test2::Tools::Tiny"
+Tiny set of tools for unfortunate souls who cannot use
+.IP Test2::Transition 12
+.IX Item "Test2::Transition"
+Transition notes when upgrading to Test2
+.IP Test2::Util 12
+.IX Item "Test2::Util"
+Tools used by Test2 and friends.
+.IP Test2::Util::ExternalMeta 12
+.IX Item "Test2::Util::ExternalMeta"
+Allow third party tools to safely attach meta-data
+.IP Test2::Util::Facets2Legacy 12
+.IX Item "Test2::Util::Facets2Legacy"
+Convert facet data to the legacy event API.
+.IP Test2::Util::HashBase 12
+.IX Item "Test2::Util::HashBase"
+Build hash based classes.
+.IP Test2::Util::Trace 12
+.IX Item "Test2::Util::Trace"
+Legacy wrapper fro Test2::EventFacet::Trace.
+.IP Test::Builder 12
+.IX Item "Test::Builder"
+Backend for building test libraries
+.IP Test::Builder::Formatter 12
+.IX Item "Test::Builder::Formatter"
+Test::Builder subclass of Test2::Formatter::TAP
+.IP Test::Builder::IO::Scalar 12
+.IX Item "Test::Builder::IO::Scalar"
+A copy of IO::Scalar for Test::Builder
+.IP Test::Builder::Module 12
+.IX Item "Test::Builder::Module"
+Base class for test modules
+.IP Test::Builder::Tester 12
+.IX Item "Test::Builder::Tester"
+Test testsuites that have been built with
+.IP Test::Builder::Tester::Color 12
+.IX Item "Test::Builder::Tester::Color"
+Turn on colour in Test::Builder::Tester
+.IP Test::Builder::TodoDiag 12
+.IX Item "Test::Builder::TodoDiag"
+Test::Builder subclass of Test2::Event::Diag
+.IP Test::Harness 12
+.IX Item "Test::Harness"
+Run Perl standard test scripts with statistics
+.IP Test::Harness::Beyond 12
+.IX Item "Test::Harness::Beyond"
+Beyond make test
+.IP Test::More 12
+.IX Item "Test::More"
+Yet another framework for writing test scripts
+.IP Test::Simple 12
+.IX Item "Test::Simple"
+Basic utilities for writing tests.
+.IP Test::Tester 12
+.IX Item "Test::Tester"
+Ease testing test modules built with Test::Builder
+.IP Test::Tester::Capture 12
+.IX Item "Test::Tester::Capture"
+Help testing test modules built with Test::Builder
+.IP Test::Tester::CaptureRunner 12
+.IX Item "Test::Tester::CaptureRunner"
+Help testing test modules built with Test::Builder
+.IP Test::Tutorial 12
+.IX Item "Test::Tutorial"
+A tutorial about writing really basic tests
+.IP Test::use::ok 12
+.IX Item "Test::use::ok"
+Alternative to Test::More::use_ok
+.IP Text::Abbrev 12
+.IX Item "Text::Abbrev"
+Abbrev \- create an abbreviation table from a list
+.IP Text::Balanced 12
+.IX Item "Text::Balanced"
+Extract delimited text sequences from strings.
+.IP Text::ParseWords 12
+.IX Item "Text::ParseWords"
+Parse text into an array of tokens or array of arrays
+.IP Text::Tabs 12
+.IX Item "Text::Tabs"
+Expand and unexpand tabs like unix \fBexpand\fR\|(1) and \fBunexpand\fR\|(1)
+.IP Text::Wrap 12
+.IX Item "Text::Wrap"
+Line wrapping to form simple paragraphs
+.IP Thread 12
+.IX Item "Thread"
+Manipulate threads in Perl (for old code only)
+.IP Thread::Queue 12
+.IX Item "Thread::Queue"
+Thread-safe queues
+.IP Thread::Semaphore 12
+.IX Item "Thread::Semaphore"
+Thread-safe semaphores
+.IP Tie::Array 12
+.IX Item "Tie::Array"
+Base class for tied arrays
+.IP Tie::File 12
+.IX Item "Tie::File"
+Access the lines of a disk file via a Perl array
+.IP Tie::Handle 12
+.IX Item "Tie::Handle"
+Base class definitions for tied handles
+.IP Tie::Hash 12
+.IX Item "Tie::Hash"
+Base class definitions for tied hashes
+.IP Tie::Hash::NamedCapture 12
+.IX Item "Tie::Hash::NamedCapture"
+Named regexp capture buffers
+.IP Tie::Memoize 12
+.IX Item "Tie::Memoize"
+Add data to hash when needed
+.IP Tie::RefHash 12
+.IX Item "Tie::RefHash"
+Use references as hash keys
+.IP Tie::Scalar 12
+.IX Item "Tie::Scalar"
+Base class definitions for tied scalars
+.IP Tie::StdHandle 12
+.IX Item "Tie::StdHandle"
+Base class definitions for tied handles
+.IP Tie::SubstrHash 12
+.IX Item "Tie::SubstrHash"
+Fixed-table-size, fixed-key-length hashing
+.IP Time::HiRes 12
+.IX Item "Time::HiRes"
+High resolution alarm, sleep, gettimeofday, interval timers
+.IP Time::Local 12
+.IX Item "Time::Local"
+Efficiently compute time from local and GMT time
+.IP Time::Piece 12
+.IX Item "Time::Piece"
+Object Oriented time objects
+.IP Time::Seconds 12
+.IX Item "Time::Seconds"
+A simple API to convert seconds to other date values
+.IP Time::gmtime 12
+.IX Item "Time::gmtime"
+By-name interface to Perl's built-in \fBgmtime()\fR function
+.IP Time::localtime 12
+.IX Item "Time::localtime"
+By-name interface to Perl's built-in \fBlocaltime()\fR function
+.IP Time::tm 12
+.IX Item "Time::tm"
+Internal object used by Time::gmtime and Time::localtime
+.IP UNIVERSAL 12
+.IX Item "UNIVERSAL"
+Base class for ALL classes (blessed references)
+.IP Unicode::Collate 12
+.IX Item "Unicode::Collate"
+Unicode Collation Algorithm
+.IP Unicode::Collate::CJK::Big5 12
+.IX Item "Unicode::Collate::CJK::Big5"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::CJK::GB2312 12
+.IX Item "Unicode::Collate::CJK::GB2312"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::CJK::JISX0208 12
+.IX Item "Unicode::Collate::CJK::JISX0208"
+Weighting JIS KANJI for Unicode::Collate
+.IP Unicode::Collate::CJK::Korean 12
+.IX Item "Unicode::Collate::CJK::Korean"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::CJK::Pinyin 12
+.IX Item "Unicode::Collate::CJK::Pinyin"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::CJK::Stroke 12
+.IX Item "Unicode::Collate::CJK::Stroke"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::CJK::Zhuyin 12
+.IX Item "Unicode::Collate::CJK::Zhuyin"
+Weighting CJK Unified Ideographs
+.IP Unicode::Collate::Locale 12
+.IX Item "Unicode::Collate::Locale"
+Linguistic tailoring for DUCET via Unicode::Collate
+.IP Unicode::Normalize 12
+.IX Item "Unicode::Normalize"
+Unicode Normalization Forms
+.IP Unicode::UCD 12
+.IX Item "Unicode::UCD"
+Unicode character database
+.IP User::grent 12
+.IX Item "User::grent"
+By-name interface to Perl's built-in getgr*() functions
+.IP User::pwent 12
+.IX Item "User::pwent"
+By-name interface to Perl's built-in getpw*() functions
+.IP VMS::DCLsym 12
+.IX Item "VMS::DCLsym"
+Perl extension to manipulate DCL symbols
+.IP VMS::Filespec 12
+.IX Item "VMS::Filespec"
+Convert between VMS and Unix file specification syntax
+.IP VMS::Stdio 12
+.IX Item "VMS::Stdio"
+Standard I/O functions via VMS extensions
+.IP Win32 12
+.IX Item "Win32"
+Interfaces to some Win32 API Functions
+.IP Win32API::File 12
+.IX Item "Win32API::File"
+Low-level access to Win32 system API calls for files/dirs.
+.IP Win32CORE 12
+.IX Item "Win32CORE"
+Win32 CORE function stubs
+.IP XS::APItest 12
+.IX Item "XS::APItest"
+Test the perl C API
+.IP XS::Typemap 12
+.IX Item "XS::Typemap"
+Module to test the XS typemaps distributed with perl
+.IP XSLoader 12
+.IX Item "XSLoader"
+Dynamically load C libraries into Perl code
+.IP autodie::Scope::Guard 12
+.IX Item "autodie::Scope::Guard"
+Wrapper class for calling subs at end of scope
+.IP autodie::Scope::GuardStack 12
+.IX Item "autodie::Scope::GuardStack"
+Hook stack for managing scopes via %^H
+.IP autodie::Util 12
+.IX Item "autodie::Util"
+Internal Utility subroutines for autodie and Fatal
+.IP version::Internals 12
+.IX Item "version::Internals"
+Perl extension for Version Objects
+.PP
+To find out \fIall\fR modules installed on your system, including
+those without documentation or outside the standard release,
+just use the following command (under the default win32 shell,
+double quotes should be used instead of single quotes).
+.PP
+.Vb 3
+\&    % perl \-MFile::Find=find \-MFile::Spec::Functions \-Tlwe \e
+\&      \*(Aqfind { wanted => sub { print canonpath $_ if /\e.pm\ez/ },
+\&      no_chdir => 1 }, @INC\*(Aq
+.Ve
+.PP
+(The \-T is here to prevent \f(CW@INC\fR from being populated by \f(CW\*(C`PERL5LIB\*(C'\fR,
+\&\f(CW\*(C`PERLLIB\*(C'\fR, and \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR.)
+They should all have their own documentation installed and accessible
+via your system \fBman\fR\|(1) command.  If you do not have a \fBfind\fR
+program, you can use the Perl \fBfind2perl\fR program instead, which
+generates Perl code as output you can run through perl.  If you
+have a \fBman\fR program but it doesn't find your modules, you'll have
+to fix your manpath.  See perl for details.  If you have no
+system \fBman\fR command, you might try the \fBperldoc\fR program.
+.PP
+Note also that the command \f(CW\*(C`perldoc perllocal\*(C'\fR gives you a (possibly
+incomplete) list of the modules that have been further installed on
+your system. (The perllocal.pod file is updated by the standard MakeMaker
+install process.)
+.SS "Extension Modules"
+.IX Subsection "Extension Modules"
+Extension modules are written in C (or a mix of Perl and C).  They
+are usually dynamically loaded into Perl if and when you need them,
+but may also be linked in statically.  Supported extension modules
+include Socket, Fcntl, and POSIX.
+.PP
+Many popular C extension modules do not come bundled (at least, not
+completely) due to their sizes, volatility, or simply lack of time
+for adequate testing and configuration across the multitude of
+platforms on which Perl was beta-tested.  You are encouraged to
+look for them on CPAN (described below), or using web search engines
+like Google or DuckDuckGo.
+.SH CPAN
+.IX Header "CPAN"
+CPAN stands for Comprehensive Perl Archive Network; it's a globally
+replicated trove of Perl materials, including documentation, style
+guides, tricks and traps, alternate ports to non-Unix systems and
+occasional binary distributions for these.   Search engines for
+CPAN can be found at https://www.cpan.org/
+.PP
+Most importantly, CPAN includes around a thousand unbundled modules,
+some of which require a C compiler to build.  Major categories of
+modules are:
+.IP \(bu 4
+Language Extensions and Documentation Tools
+.IP \(bu 4
+Development Support
+.IP \(bu 4
+Operating System Interfaces
+.IP \(bu 4
+Networking, Device Control (modems) and InterProcess Communication
+.IP \(bu 4
+Data Types and Data Type Utilities
+.IP \(bu 4
+Database Interfaces
+.IP \(bu 4
+User Interfaces
+.IP \(bu 4
+Interfaces to / Emulations of Other Programming Languages
+.IP \(bu 4
+File Names, File Systems and File Locking (see also File Handles)
+.IP \(bu 4
+String Processing, Language Text Processing, Parsing, and Searching
+.IP \(bu 4
+Option, Argument, Parameter, and Configuration File Processing
+.IP \(bu 4
+Internationalization and Locale
+.IP \(bu 4
+Authentication, Security, and Encryption
+.IP \(bu 4
+World Wide Web, HTML, HTTP, CGI, MIME
+.IP \(bu 4
+Server and Daemon Utilities
+.IP \(bu 4
+Archiving and Compression
+.IP \(bu 4
+Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
+.IP \(bu 4
+Mail and Usenet News
+.IP \(bu 4
+Control Flow Utilities (callbacks and exceptions etc)
+.IP \(bu 4
+File Handle and Input/Output Stream Utilities
+.IP \(bu 4
+Miscellaneous Modules
+.PP
+You can find the CPAN online at <https://www.cpan.org/>
+.SH "Modules: Creation, Use, and Abuse"
+.IX Header "Modules: Creation, Use, and Abuse"
+(The following section is borrowed directly from Tim Bunce's modules
+file, available at your nearest CPAN site.)
+.PP
+Perl implements a class using a package, but the presence of a
+package doesn't imply the presence of a class.  A package is just a
+namespace.  A class is a package that provides subroutines that can be
+used as methods.  A method is just a subroutine that expects, as its
+first argument, either the name of a package (for "static" methods),
+or a reference to something (for "virtual" methods).
+.PP
+A module is a file that (by convention) provides a class of the same
+name (sans the .pm), plus an import method in that class that can be
+called to fetch exported symbols.  This module may implement some of
+its methods by loading dynamic C or C++ objects, but that should be
+totally transparent to the user of the module.  Likewise, the module
+might set up an AUTOLOAD function to slurp in subroutine definitions on
+demand, but this is also transparent.  Only the \fI.pm\fR file is required to
+exist.  See perlsub, perlobj, and AutoLoader for details about
+the AUTOLOAD mechanism.
+.SS "Guidelines for Module Creation"
+.IX Subsection "Guidelines for Module Creation"
+.IP \(bu 4
+Do similar modules already exist in some form?
+.Sp
+If so, please try to reuse the existing modules either in whole or
+by inheriting useful features into a new class.  If this is not
+practical try to get together with the module authors to work on
+extending or enhancing the functionality of the existing modules.
+A perfect example is the plethora of packages in perl4 for dealing
+with command line options.
+.Sp
+If you are writing a module to expand an already existing set of
+modules, please coordinate with the author of the package.  It
+helps if you follow the same naming scheme and module interaction
+scheme as the original author.
+.IP \(bu 4
+Try to design the new module to be easy to extend and reuse.
+.Sp
+Try to \f(CW\*(C`use warnings;\*(C'\fR (or \f(CW\*(C`use warnings qw(...);\*(C'\fR).
+Remember that you can add \f(CW\*(C`no warnings qw(...);\*(C'\fR to individual blocks
+of code that need less warnings.
+.Sp
+Use blessed references.  Use the two argument form of bless to bless
+into the class name given as the first parameter of the constructor,
+e.g.,:
+.Sp
+.Vb 4
+\& sub new {
+\&     my $class = shift;
+\&     return bless {}, $class;
+\& }
+.Ve
+.Sp
+or even this if you'd like it to be used as either a static
+or a virtual method.
+.Sp
+.Vb 5
+\& sub new {
+\&     my $self  = shift;
+\&     my $class = ref($self) || $self;
+\&     return bless {}, $class;
+\& }
+.Ve
+.Sp
+Pass arrays as references so more parameters can be added later
+(it's also faster).  Convert functions into methods where
+appropriate.  Split large methods into smaller more flexible ones.
+Inherit methods from other modules if appropriate.
+.Sp
+Avoid class name tests like: \f(CW\*(C`die "Invalid" unless ref $ref eq \*(AqFOO\*(Aq\*(C'\fR.
+Generally you can delete the \f(CW\*(C`eq \*(AqFOO\*(Aq\*(C'\fR part with no harm at all.
+Let the objects look after themselves! Generally, avoid hard-wired
+class names as far as possible.
+.Sp
+Avoid \f(CW\*(C`$r\->Class::func()\*(C'\fR where using \f(CW\*(C`@ISA=qw(... Class ...)\*(C'\fR and
+\&\f(CW\*(C`$r\->func()\*(C'\fR would work.
+.Sp
+Use autosplit so little used or newly added functions won't be a
+burden to programs that don't use them. Add test functions to
+the module after _\|_END_\|_ either using AutoSplit or by saying:
+.Sp
+.Vb 1
+\& eval join(\*(Aq\*(Aq,<main::DATA>) || die $@ unless caller();
+.Ve
+.Sp
+Does your module pass the 'empty subclass' test? If you say
+\&\f(CW\*(C`@SUBCLASS::ISA = qw(YOURCLASS);\*(C'\fR your applications should be able
+to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
+does your application still work if you change:  \f(CW\*(C`$obj = YOURCLASS\->new();\*(C'\fR
+into: \f(CW\*(C`$obj = SUBCLASS\->new();\*(C'\fR ?
+.Sp
+Avoid keeping any state information in your packages. It makes it
+difficult for multiple other packages to use yours. Keep state
+information in objects.
+.Sp
+Always use \fB\-w\fR.
+.Sp
+Try to \f(CW\*(C`use strict;\*(C'\fR (or \f(CW\*(C`use strict qw(...);\*(C'\fR).
+Remember that you can add \f(CW\*(C`no strict qw(...);\*(C'\fR to individual blocks
+of code that need less strictness.
+.Sp
+Always use \fB\-w\fR.
+.Sp
+Follow the guidelines in perlstyle.
+.Sp
+Always use \fB\-w\fR.
+.IP \(bu 4
+Some simple style guidelines
+.Sp
+The perlstyle manual supplied with Perl has many helpful points.
+.Sp
+Coding style is a matter of personal taste. Many people evolve their
+style over several years as they learn what helps them write and
+maintain good code.  Here's one set of assorted suggestions that
+seem to be widely used by experienced developers:
+.Sp
+Use underscores to separate words.  It is generally easier to read
+\&\f(CW$var_names_like_this\fR than \f(CW$VarNamesLikeThis\fR, especially for
+non-native speakers of English. It's also a simple rule that works
+consistently with VAR_NAMES_LIKE_THIS.
+.Sp
+Package/Module names are an exception to this rule. Perl informally
+reserves lowercase module names for 'pragma' modules like integer
+and strict. Other modules normally begin with a capital letter and
+use mixed case with no underscores (need to be short and portable).
+.Sp
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
+.Sp
+.Vb 3
+\& $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
+\& $Some_Caps_Here  package\-wide global/static
+\& $no_caps_here    function scope my() or local() variables
+.Ve
+.Sp
+Function and method names seem to work best as all lowercase.
+e.g., \f(CW\*(C`$obj\->as_string()\*(C'\fR.
+.Sp
+You can use a leading underscore to indicate that a variable or
+function should not be used outside the package that defined it.
+.IP \(bu 4
+Select what to export.
+.Sp
+Do NOT export method names!
+.Sp
+Do NOT export anything else by default without a good reason!
+.Sp
+Exports pollute the namespace of the module user.  If you must
+export try to use \f(CW@EXPORT_OK\fR in preference to \f(CW@EXPORT\fR and avoid
+short or common names to reduce the risk of name clashes.
+.Sp
+Generally anything not exported is still accessible from outside the
+module using the ModuleName::item_name (or \f(CW\*(C`$blessed_ref\->method\*(C'\fR)
+syntax.  By convention you can use a leading underscore on names to
+indicate informally that they are 'internal' and not for public use.
+.Sp
+(It is actually possible to get private functions by saying:
+\&\f(CW\*(C`my $subref = sub { ... };  &$subref;\*(C'\fR.  But there's no way to call that
+directly as a method, because a method must have a name in the symbol
+table.)
+.Sp
+As a general rule, if the module is trying to be object oriented
+then export nothing. If it's just a collection of functions then
+\&\f(CW@EXPORT_OK\fR anything but use \f(CW@EXPORT\fR with caution.
+.IP \(bu 4
+Select a name for the module.
+.Sp
+This name should be as descriptive, accurate, and complete as
+possible.  Avoid any risk of ambiguity. Always try to use two or
+more whole words.  Generally the name should reflect what is special
+about what the module does rather than how it does it.  Please use
+nested module names to group informally or categorize a module.
+There should be a very good reason for a module not to have a nested name.
+Module names should begin with a capital letter.
+.Sp
+Having 57 modules all called Sort will not make life easy for anyone
+(though having 23 called Sort::Quick is only marginally better :\-).
+Imagine someone trying to install your module alongside many others.
+.Sp
+If you are developing a suite of related modules/classes it's good
+practice to use nested classes with a common prefix as this will
+avoid namespace clashes. For example: Xyz::Control, Xyz::View,
+Xyz::Model etc. Use the modules in this list as a naming guide.
+.Sp
+If adding a new module to a set, follow the original author's
+standards for naming modules and the interface to methods in
+those modules.
+.Sp
+If developing modules for private internal or project specific use,
+that will never be released to the public, then you should ensure
+that their names will not clash with any future public module. You
+can do this either by using the reserved Local::* category or by
+using a category name that includes an underscore like Foo_Corp::*.
+.Sp
+To be portable each component of a module name should be limited to
+11 characters. If it might be used on MS-DOS then try to ensure each is
+unique in the first 8 characters. Nested modules make this easier.
+.Sp
+For additional guidance on the naming of modules, please consult:
+.Sp
+.Vb 1
+\&    https://pause.perl.org/pause/query?ACTION=pause_namingmodules
+.Ve
+.Sp
+or send mail to the <module\-authors@perl.org> mailing list.
+.IP \(bu 4
+Have you got it right?
+.Sp
+How do you know that you've made the right decisions? Have you
+picked an interface design that will cause problems later? Have
+you picked the most appropriate name? Do you have any questions?
+.Sp
+The best way to know for sure, and pick up many helpful suggestions,
+is to ask someone who knows. The <module\-authors@perl.org> mailing list
+is useful for this purpose; it's also accessible via news interface as
+perl.module\-authors at nntp.perl.org.
+.Sp
+All you need to do is post a short summary of the module, its
+purpose and interfaces. A few lines on each of the main methods is
+probably enough. (If you post the whole module it might be ignored
+by busy people \- generally the very people you want to read it!)
+.Sp
+Don't worry about posting if you can't say when the module will be
+ready \- just say so in the message. It might be worth inviting
+others to help you, they may be able to complete it for you!
+.IP \(bu 4
+README and other Additional Files.
+.Sp
+It's well known that software developers usually fully document the
+software they write. If, however, the world is in urgent need of
+your software and there is not enough time to write the full
+documentation please at least provide a README file containing:
+.RS 4
+.IP \(bu 10
+A description of the module/package/extension etc.
+.IP \(bu 10
+A copyright notice \- see below.
+.IP \(bu 10
+Prerequisites \- what else you may need to have.
+.IP \(bu 10
+How to build it \- possible changes to Makefile.PL etc.
+.IP \(bu 10
+How to install it.
+.IP \(bu 10
+Recent changes in this release, especially incompatibilities
+.IP \(bu 10
+Changes / enhancements you plan to make in the future.
+.RE
+.RS 4
+.Sp
+If the README file seems to be getting too large you may wish to
+split out some of the sections into separate files: INSTALL,
+Copying, ToDo etc.
+.IP \(bu 4
+Adding a Copyright Notice.
+.Sp
+How you choose to license your work is a personal decision.
+The general mechanism is to assert your Copyright and then make
+a declaration of how others may copy/use/modify your work.
+.Sp
+Perl, for example, is supplied with two types of licence: The GNU GPL
+and The Artistic Licence (see the files README, Copying, and Artistic,
+or perlgpl and perlartistic).  Larry has good reasons for NOT
+just using the GNU GPL.
+.Sp
+My personal recommendation, out of respect for Larry, Perl, and the
+Perl community at large is to state something simply like:
+.Sp
+.Vb 3
+\& Copyright (c) 1995 Your Name. All rights reserved.
+\& This program is free software; you can redistribute it and/or
+\& modify it under the same terms as Perl itself.
+.Ve
+.Sp
+This statement should at least appear in the README file. You may
+also wish to include it in a Copying file and your source files.
+Remember to include the other words in addition to the Copyright.
+.IP \(bu 4
+Give the module a version/issue/release number.
+.Sp
+To be fully compatible with the Exporter and MakeMaker modules you
+should store your module's version number in a non-my package
+variable called \f(CW$VERSION\fR.  This should be a positive floating point
+number with at least two digits after the decimal (i.e., hundredths,
+e.g, \f(CW\*(C`$VERSION = "0.01"\*(C'\fR).  Don't use a "1.3.2" style version.
+See Exporter for details.
+.Sp
+It may be handy to add a function or method to retrieve the number.
+Use the number in announcements and archive file names when
+releasing the module (ModuleName\-1.02.tar.Z).
+See perldoc ExtUtils::MakeMaker.pm for details.
+.IP \(bu 4
+How to release and distribute a module.
+.Sp
+If possible, register the module with CPAN. Follow the instructions
+and links on:
+.Sp
+.Vb 1
+\&   https://www.cpan.org/modules/04pause.html
+.Ve
+.Sp
+and upload to:
+.Sp
+.Vb 1
+\&   https://pause.perl.org/
+.Ve
+.Sp
+and notify <modules@perl.org>. This will allow anyone to install
+your module using the \f(CW\*(C`cpan\*(C'\fR tool distributed with Perl.
+.Sp
+By using the WWW interface you can ask the Upload Server to mirror
+your modules from your ftp or WWW site into your own directory on
+CPAN!
+.IP \(bu 4
+Take care when changing a released module.
+.Sp
+Always strive to remain compatible with previous released versions.
+Otherwise try to add a mechanism to revert to the
+old behavior if people rely on it.  Document incompatible changes.
+.RE
+.RS 4
+.RE
+.SS "Guidelines for Converting Perl 4 Library Scripts into Modules"
+.IX Subsection "Guidelines for Converting Perl 4 Library Scripts into Modules"
+.IP \(bu 4
+There is no requirement to convert anything.
+.Sp
+If it ain't broke, don't fix it! Perl 4 library scripts should
+continue to work with no problems. You may need to make some minor
+changes (like escaping non-array @'s in double quoted strings) but
+there is no need to convert a .pl file into a Module for just that.
+.IP \(bu 4
+Consider the implications.
+.Sp
+All Perl applications that make use of the script will need to
+be changed (slightly) if the script is converted into a module.  Is
+it worth it unless you plan to make other changes at the same time?
+.IP \(bu 4
+Make the most of the opportunity.
+.Sp
+If you are going to convert the script to a module you can use the
+opportunity to redesign the interface.  The guidelines for module
+creation above include many of the issues you should consider.
+.IP \(bu 4
+The pl2pm utility will get you started.
+.Sp
+This utility will read *.pl files (given as parameters) and write
+corresponding *.pm files. The pl2pm utilities does the following:
+.RS 4
+.IP \(bu 10
+Adds the standard Module prologue lines
+.IP \(bu 10
+Converts package specifiers from ' to ::
+.IP \(bu 10
+Converts die(...) to croak(...)
+.IP \(bu 10
+Several other minor changes
+.RE
+.RS 4
+.Sp
+Being a mechanical process pl2pm is not bullet proof. The converted
+code will need careful checking, especially any package statements.
+Don't delete the original .pl file till the new .pm one works!
+.RE
+.SS "Guidelines for Reusing Application Code"
+.IX Subsection "Guidelines for Reusing Application Code"
+.IP \(bu 4
+Complete applications rarely belong in the Perl Module Library.
+.IP \(bu 4
+Many applications contain some Perl code that could be reused.
+.Sp
+Help save the world! Share your code in a form that makes it easy
+to reuse.
+.IP \(bu 4
+Break-out the reusable code into one or more separate module files.
+.IP \(bu 4
+Take the opportunity to reconsider and redesign the interfaces.
+.IP \(bu 4
+In some cases the 'application' can then be reduced to a small
+.Sp
+fragment of code built on top of the reusable modules. In these cases
+the application could invoked as:
+.Sp
+.Vb 3
+\&     % perl \-e \*(Aquse Module::Name; method(@ARGV)\*(Aq ...
+\&or
+\&     % perl \-mModule::Name ...    (in perl5.002 or higher)
+.Ve
+.SH NOTE
+.IX Header "NOTE"
+Perl does not enforce private and public parts of its modules as you may
+have been used to in other languages like C++, Ada, or Modula\-17.  Perl
+doesn't have an infatuation with enforced privacy.  It would prefer
+that you stayed out of its living room because you weren't invited, not
+because it has a shotgun.
+.PP
+The module and its user have a contract, part of which is common law,
+and part of which is "written".  Part of the common law contract is
+that a module doesn't pollute any namespace it wasn't asked to.  The
+written contract for the module (A.K.A. documentation) may make other
+provisions.  But then you know when you \f(CW\*(C`use RedefineTheWorld\*(C'\fR that
+you're redefining the world and willing to take the consequences.
diff --git a/upstream/mageia-cauldron/man1/perlmodstyle.1 b/upstream/mageia-cauldron/man1/perlmodstyle.1
new file mode 100644
index 00000000..15616787
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmodstyle.1
@@ -0,0 +1,668 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMODSTYLE 1"
+.TH PERLMODSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmodstyle \- Perl module style guide
+.SH INTRODUCTION
+.IX Header "INTRODUCTION"
+This document attempts to describe the Perl Community's "best practice"
+for writing Perl modules.  It extends the recommendations found in 
+perlstyle , which should be considered required reading
+before reading this document.
+.PP
+While this document is intended to be useful to all module authors, it is
+particularly aimed at authors who wish to publish their modules on CPAN.
+.PP
+The focus is on elements of style which are visible to the users of a 
+module, rather than those parts which are only seen by the module's 
+developers.  However, many of the guidelines presented in this document
+can be extrapolated and applied successfully to a module's internals.
+.PP
+This document differs from perlnewmod in that it is a style guide
+rather than a tutorial on creating CPAN modules.  It provides a
+checklist against which modules can be compared to determine whether
+they conform to best practice, without necessarily describing in detail
+how to achieve this.
+.PP
+All the advice contained in this document has been gleaned from
+extensive conversations with experienced CPAN authors and users.  Every
+piece of advice given here is the result of previous mistakes.  This
+information is here to help you avoid the same mistakes and the extra
+work that would inevitably be required to fix them.
+.PP
+The first section of this document provides an itemized checklist; 
+subsequent sections provide a more detailed discussion of the items on 
+the list.  The final section, "Common Pitfalls", describes some of the 
+most popular mistakes made by CPAN authors.
+.SH "QUICK CHECKLIST"
+.IX Header "QUICK CHECKLIST"
+For more detail on each item in this checklist, see below.
+.SS "Before you start"
+.IX Subsection "Before you start"
+.IP \(bu 4
+Don't re-invent the wheel
+.IP \(bu 4
+Patch, extend or subclass an existing module where possible
+.IP \(bu 4
+Do one thing and do it well
+.IP \(bu 4
+Choose an appropriate name
+.IP \(bu 4
+Get feedback before publishing
+.SS "The API"
+.IX Subsection "The API"
+.IP \(bu 4
+API should be understandable by the average programmer
+.IP \(bu 4
+Simple methods for simple tasks
+.IP \(bu 4
+Separate functionality from output
+.IP \(bu 4
+Consistent naming of subroutines or methods
+.IP \(bu 4
+Use named parameters (a hash or hashref) when there are more than two
+parameters
+.SS Stability
+.IX Subsection "Stability"
+.IP \(bu 4
+Ensure your module works under \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`\-w\*(C'\fR
+.IP \(bu 4
+Stable modules should maintain backwards compatibility
+.SS Documentation
+.IX Subsection "Documentation"
+.IP \(bu 4
+Write documentation in POD
+.IP \(bu 4
+Document purpose, scope and target applications
+.IP \(bu 4
+Document each publicly accessible method or subroutine, including params and return values
+.IP \(bu 4
+Give examples of use in your documentation
+.IP \(bu 4
+Provide a README file and perhaps also release notes, changelog, etc
+.IP \(bu 4
+Provide links to further information (URL, email)
+.SS "Release considerations"
+.IX Subsection "Release considerations"
+.IP \(bu 4
+Specify pre-requisites in Makefile.PL or Build.PL
+.IP \(bu 4
+Specify Perl version requirements with \f(CW\*(C`use\*(C'\fR
+.IP \(bu 4
+Include tests with your module
+.IP \(bu 4
+Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)
+.IP \(bu 4
+Increment the version number for every change, no matter how small
+.IP \(bu 4
+Package the module using "make dist"
+.IP \(bu 4
+Choose an appropriate license (GPL/Artistic is a good default)
+.SH "BEFORE YOU START WRITING A MODULE"
+.IX Header "BEFORE YOU START WRITING A MODULE"
+Try not to launch headlong into developing your module without spending
+some time thinking first.  A little forethought may save you a vast
+amount of effort later on.
+.SS "Has it been done before?"
+.IX Subsection "Has it been done before?"
+You may not even need to write the module.  Check whether it's already 
+been done in Perl, and avoid re-inventing the wheel unless you have a 
+good reason.
+.PP
+Good places to look for pre-existing modules include
+MetaCPAN <https://metacpan.org> and asking on \f(CW\*(C`module\-authors@perl.org\*(C'\fR
+(<https://lists.perl.org/list/module\-authors.html>).
+.PP
+If an existing module \fBalmost\fR does what you want, consider writing a
+patch, writing a subclass, or otherwise extending the existing module
+rather than rewriting it.
+.SS "Do one thing and do it well"
+.IX Subsection "Do one thing and do it well"
+At the risk of stating the obvious, modules are intended to be modular.
+A Perl developer should be able to use modules to put together the
+building blocks of their application.  However, it's important that the
+blocks are the right shape, and that the developer shouldn't have to use
+a big block when all they need is a small one.
+.PP
+Your module should have a clearly defined scope which is no longer than
+a single sentence.  Can your module be broken down into a family of
+related modules?
+.PP
+Bad example:
+.PP
+"FooBar.pm provides an implementation of the FOO protocol and the
+related BAR standard."
+.PP
+Good example:
+.PP
+"Foo.pm provides an implementation of the FOO protocol.  Bar.pm
+implements the related BAR protocol."
+.PP
+This means that if a developer only needs a module for the BAR standard,
+they should not be forced to install libraries for FOO as well.
+.SS "What's in a name?"
+.IX Subsection "What's in a name?"
+Make sure you choose an appropriate name for your module early on.  This
+will help people find and remember your module, and make programming
+with your module more intuitive.
+.PP
+When naming your module, consider the following:
+.IP \(bu 4
+Be descriptive (i.e. accurately describes the purpose of the module).
+.IP \(bu 4
+Be consistent with existing modules.
+.IP \(bu 4
+Reflect the functionality of the module, not the implementation.
+.IP \(bu 4
+Avoid starting a new top-level hierarchy, especially if a suitable
+hierarchy already exists under which you could place your module.
+.SS "Get feedback before publishing"
+.IX Subsection "Get feedback before publishing"
+If you have never uploaded a module to CPAN before (and even if you have),
+you are strongly encouraged to get feedback from people who are already
+familiar with the module's application domain and the CPAN naming system.
+Authors of similar modules, or modules with similar names, may be a good
+place to start, as are community sites like
+Perl Monks <https://www.perlmonks.org>.
+.SH "DESIGNING AND WRITING YOUR MODULE"
+.IX Header "DESIGNING AND WRITING YOUR MODULE"
+Considerations for module design and coding:
+.SS "To OO or not to OO?"
+.IX Subsection "To OO or not to OO?"
+Your module may be object oriented (OO) or not, or it may have both kinds 
+of interfaces available.  There are pros and cons of each technique, which 
+should be considered when you design your API.
+.PP
+In \fIPerl Best Practices\fR (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is the
+right fit for your problem:
+.IP \(bu 4
+The system being designed is large, or is likely to become large.
+.IP \(bu 4
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
+.IP \(bu 4
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
+.IP \(bu 4
+You have a piece of data on which many different operations are
+applied.
+.IP \(bu 4
+You need to perform the same general operations on related types of
+data, but with slight variations depending on the specific type of data
+the operations are applied to.
+.IP \(bu 4
+It's likely you'll have to add new data types later.
+.IP \(bu 4
+The typical interactions between pieces of data are best represented by
+operators.
+.IP \(bu 4
+The implementation of individual components of the system is likely to
+change over time.
+.IP \(bu 4
+The system design is already object-oriented.
+.IP \(bu 4
+Large numbers of other programmers will be using your code modules.
+.PP
+Think carefully about whether OO is appropriate for your module.
+Gratuitous object orientation results in complex APIs which are
+difficult for the average module user to understand or use.
+.SS "Designing your API"
+.IX Subsection "Designing your API"
+Your interfaces should be understandable by an average Perl programmer.  
+The following guidelines may help you judge whether your API is
+sufficiently straightforward:
+.IP "Write simple routines to do simple things." 4
+.IX Item "Write simple routines to do simple things."
+It's better to have numerous simple routines than a few monolithic ones.
+If your routine changes its behaviour significantly based on its
+arguments, it's a sign that you should have two (or more) separate
+routines.
+.IP "Separate functionality from output." 4
+.IX Item "Separate functionality from output."
+Return your results in the most generic form possible and allow the user 
+to choose how to use them.  The most generic form possible is usually a
+Perl data structure which can then be used to generate a text report,
+HTML, XML, a database query, or whatever else your users require.
+.Sp
+If your routine iterates through some kind of list (such as a list of
+files, or records in a database) you may consider providing a callback
+so that users can manipulate each element of the list in turn.
+File::Find provides an example of this with its 
+\&\f(CW\*(C`find(\e&wanted, $dir)\*(C'\fR syntax.
+.IP "Provide sensible shortcuts and defaults." 4
+.IX Item "Provide sensible shortcuts and defaults."
+Don't require every module user to jump through the same hoops to achieve a
+simple result.  You can always include optional parameters or routines for 
+more complex or non-standard behaviour.  If most of your users have to
+type a few almost identical lines of code when they start using your
+module, it's a sign that you should have made that behaviour a default.
+Another good indicator that you should use defaults is if most of your 
+users call your routines with the same arguments.
+.IP "Naming conventions" 4
+.IX Item "Naming conventions"
+Your naming should be consistent.  For instance, it's better to have:
+.Sp
+.Vb 3
+\&        display_day();
+\&        display_week();
+\&        display_year();
+.Ve
+.Sp
+than
+.Sp
+.Vb 3
+\&        display_day();
+\&        week_display();
+\&        show_year();
+.Ve
+.Sp
+This applies equally to method names, parameter names, and anything else
+which is visible to the user (and most things that aren't!)
+.IP "Parameter passing" 4
+.IX Item "Parameter passing"
+Use named parameters.  It's easier to use a hash like this:
+.Sp
+.Vb 5
+\&    $obj\->do_something(
+\&            name => "wibble",
+\&            type => "text",
+\&            size => 1024,
+\&    );
+.Ve
+.Sp
+\&... than to have a long list of unnamed parameters like this:
+.Sp
+.Vb 1
+\&    $obj\->do_something("wibble", "text", 1024);
+.Ve
+.Sp
+While the list of arguments might work fine for one, two or even three
+arguments, any more arguments become hard for the module user to
+remember, and hard for the module author to manage.  If you want to add
+a new parameter you will have to add it to the end of the list for
+backward compatibility, and this will probably make your list order
+unintuitive.  Also, if many elements may be undefined you may see the
+following unattractive method calls:
+.Sp
+.Vb 1
+\&    $obj\->do_something(undef, undef, undef, undef, undef, 1024);
+.Ve
+.Sp
+Provide sensible defaults for parameters which have them.  Don't make
+your users specify parameters which will almost always be the same.
+.Sp
+The issue of whether to pass the arguments in a hash or a hashref is
+largely a matter of personal style.
+.Sp
+The use of hash keys starting with a hyphen (\f(CW\*(C`\-name\*(C'\fR) or entirely in 
+upper case (\f(CW\*(C`NAME\*(C'\fR) is a relic of older versions of Perl in which
+ordinary lower case strings were not handled correctly by the \f(CW\*(C`=>\*(C'\fR
+operator.  While some modules retain uppercase or hyphenated argument
+keys for historical reasons or as a matter of personal style, most new
+modules should use simple lower case keys.  Whatever you choose, be
+consistent!
+.SS "Strictness and warnings"
+.IX Subsection "Strictness and warnings"
+Your module should run successfully under the strict pragma and should
+run without generating any warnings.  Your module should also handle 
+taint-checking where appropriate, though this can cause difficulties in
+many cases.
+.SS "Backwards compatibility"
+.IX Subsection "Backwards compatibility"
+Modules which are "stable" should not break backwards compatibility
+without at least a long transition phase and a major change in version
+number.
+.SS "Error handling and messages"
+.IX Subsection "Error handling and messages"
+When your module encounters an error it should do one or more of:
+.IP \(bu 4
+Return an undefined value.
+.IP \(bu 4
+set \f(CW$Module::errstr\fR or similar (\f(CW\*(C`errstr\*(C'\fR is a common name used by
+DBI and other popular modules; if you choose something else, be sure to
+document it clearly).
+.IP \(bu 4
+\&\f(CWwarn()\fR or \f(CWcarp()\fR a message to STDERR.
+.IP \(bu 4
+\&\f(CWcroak()\fR only when your module absolutely cannot figure out what to
+do.  (\f(CWcroak()\fR is a better version of \f(CWdie()\fR for use within 
+modules, which reports its errors from the perspective of the caller.  
+See Carp for details of \f(CWcroak()\fR, \f(CWcarp()\fR and other useful
+routines.)
+.IP \(bu 4
+As an alternative to the above, you may prefer to throw exceptions using 
+the Error module.
+.PP
+Configurable error handling can be very useful to your users.  Consider
+offering a choice of levels for warning and debug messages, an option to
+send messages to a separate file, a way to specify an error-handling
+routine, or other such features.  Be sure to default all these options
+to the commonest use.
+.SH "DOCUMENTING YOUR MODULE"
+.IX Header "DOCUMENTING YOUR MODULE"
+.SS POD
+.IX Subsection "POD"
+Your module should include documentation aimed at Perl developers.
+You should use Perl's "plain old documentation" (POD) for your general 
+technical documentation, though you may wish to write additional
+documentation (white papers, tutorials, etc) in some other format.  
+You need to cover the following subjects:
+.IP \(bu 4
+A synopsis of the common uses of the module
+.IP \(bu 4
+The purpose, scope and target applications of your module
+.IP \(bu 4
+Use of each publicly accessible method or subroutine, including
+parameters and return values
+.IP \(bu 4
+Examples of use
+.IP \(bu 4
+Sources of further information
+.IP \(bu 4
+A contact email address for the author/maintainer
+.PP
+The level of detail in Perl module documentation generally goes from
+less detailed to more detailed.  Your SYNOPSIS section should contain a
+minimal example of use (perhaps as little as one line of code; skip the
+unusual use cases or anything not needed by most users); the
+DESCRIPTION should describe your module in broad terms, generally in
+just a few paragraphs; more detail of the module's routines or methods,
+lengthy code examples, or other in-depth material should be given in 
+subsequent sections.
+.PP
+Ideally, someone who's slightly familiar with your module should be able
+to refresh their memory without hitting "page down".  As your reader
+continues through the document, they should receive a progressively
+greater amount of knowledge.
+.PP
+The recommended order of sections in Perl module documentation is:
+.IP \(bu 4
+NAME
+.IP \(bu 4
+SYNOPSIS
+.IP \(bu 4
+DESCRIPTION
+.IP \(bu 4
+One or more sections or subsections giving greater detail of available 
+methods and routines and any other relevant information.
+.IP \(bu 4
+BUGS/CAVEATS/etc
+.IP \(bu 4
+AUTHOR
+.IP \(bu 4
+SEE ALSO
+.IP \(bu 4
+COPYRIGHT and LICENSE
+.PP
+Keep your documentation near the code it documents ("inline"
+documentation).  Include POD for a given method right above that 
+method's subroutine.  This makes it easier to keep the documentation up
+to date, and avoids having to document each piece of code twice (once in
+POD and once in comments).
+.SS "README, INSTALL, release notes, changelogs"
+.IX Subsection "README, INSTALL, release notes, changelogs"
+Your module should also include a README file describing the module and
+giving pointers to further information (website, author email).
+.PP
+An INSTALL file should be included, and should contain simple installation 
+instructions.  When using ExtUtils::MakeMaker this will usually be:
+.IP "perl Makefile.PL" 4
+.IX Item "perl Makefile.PL"
+.PD 0
+.IP make 4
+.IX Item "make"
+.IP "make test" 4
+.IX Item "make test"
+.IP "make install" 4
+.IX Item "make install"
+.PD
+.PP
+When using Module::Build, this will usually be:
+.IP "perl Build.PL" 4
+.IX Item "perl Build.PL"
+.PD 0
+.IP "perl Build" 4
+.IX Item "perl Build"
+.IP "perl Build test" 4
+.IX Item "perl Build test"
+.IP "perl Build install" 4
+.IX Item "perl Build install"
+.PD
+.PP
+Release notes or changelogs should be produced for each release of your
+software describing user-visible changes to your module, in terms
+relevant to the user.
+.PP
+Unless you have good reasons for using some other format
+(for example, a format used within your company),
+the convention is to name your changelog file \f(CW\*(C`Changes\*(C'\fR,
+and to follow the simple format described in CPAN::Changes::Spec.
+.SH "RELEASE CONSIDERATIONS"
+.IX Header "RELEASE CONSIDERATIONS"
+.SS "Version numbering"
+.IX Subsection "Version numbering"
+Version numbers should indicate at least major and minor releases, and
+possibly sub-minor releases.  A major release is one in which most of
+the functionality has changed, or in which major new functionality is
+added.  A minor release is one in which a small amount of functionality
+has been added or changed.  Sub-minor version numbers are usually used
+for changes which do not affect functionality, such as documentation
+patches.
+.PP
+The most common CPAN version numbering scheme looks like this:
+.PP
+.Vb 1
+\&    1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
+.Ve
+.PP
+A correct CPAN version number is a floating point number with at least 
+2 digits after the decimal.  You can test whether it conforms to CPAN by 
+using
+.PP
+.Vb 2
+\&    perl \-MExtUtils::MakeMaker \-le \*(Aqprint MM\->parse_version(shift)\*(Aq \e
+\&                                                            \*(AqFoo.pm\*(Aq
+.Ve
+.PP
+If you want to release a 'beta' or 'alpha' version of a module but
+don't want CPAN.pm to list it as most recent use an '_' after the
+regular version number followed by at least 2 digits, eg. 1.20_01.  If
+you do this, the following idiom is recommended:
+.PP
+.Vb 5
+\&  our $VERSION = "1.12_01"; # so CPAN distribution will have
+\&                            # right filename
+\&  our $XS_VERSION = $VERSION; # only needed if you have XS code
+\&  $VERSION = eval $VERSION; # so "use Module 0.002" won\*(Aqt warn on
+\&                            # underscore
+.Ve
+.PP
+With that trick MakeMaker will only read the first line and thus read
+the underscore, while the perl interpreter will evaluate the \f(CW$VERSION\fR
+and convert the string into a number.  Later operations that treat
+\&\f(CW$VERSION\fR as a number will then be able to do so without provoking a
+warning about \f(CW$VERSION\fR not being a number.
+.PP
+Never release anything (even a one-word documentation patch) without
+incrementing the number.  Even a one-word documentation patch should
+result in a change in version at the sub-minor level.
+.PP
+Once picked, it is important to stick to your version scheme, without
+reducing the number of digits.  This is because "downstream" packagers,
+such as the FreeBSD ports system, interpret the version numbers in
+various ways.  If you change the number of digits in your version scheme,
+you can confuse these systems so they get the versions of your module
+out of order, which is obviously bad.
+.SS Pre-requisites
+.IX Subsection "Pre-requisites"
+Module authors should carefully consider whether to rely on other
+modules, and which modules to rely on.
+.PP
+Most importantly, choose modules which are as stable as possible.  In
+order of preference:
+.IP \(bu 4
+Core Perl modules
+.IP \(bu 4
+Stable CPAN modules
+.IP \(bu 4
+Unstable CPAN modules
+.IP \(bu 4
+Modules not available from CPAN
+.PP
+Specify version requirements for other Perl modules in the
+pre-requisites in your Makefile.PL or Build.PL.
+.PP
+Be sure to specify Perl version requirements both in Makefile.PL or
+Build.PL and with \f(CW\*(C`require 5.6.1\*(C'\fR or similar.  See the documentation on
+\&\f(CW\*(C`use VERSION\*(C'\fR for details.
+.SS Testing
+.IX Subsection "Testing"
+All modules should be tested before distribution (using "make disttest"),
+and the tests should also be available to people installing the modules 
+(using "make test").  
+For Module::Build you would use the \f(CW\*(C`make test\*(C'\fR equivalent \f(CW\*(C`perl Build test\*(C'\fR.
+.PP
+The importance of these tests is proportional to the alleged stability of a 
+module.  A module which purports to be
+stable or which hopes to achieve wide 
+use should adhere to as strict a testing regime as possible.
+.PP
+Useful modules to help you write tests (with minimum impact on your 
+development process or your time) include Test::Simple, Carp::Assert 
+and Test::Inline.
+For more sophisticated test suites there are Test::More and Test::MockObject.
+.SS Packaging
+.IX Subsection "Packaging"
+Modules should be packaged using one of the standard packaging tools.
+Currently you have the choice between ExtUtils::MakeMaker and the
+more platform independent Module::Build, allowing modules to be installed in a
+consistent manner.
+When using ExtUtils::MakeMaker, you can use "make dist" to create your
+package.  Tools exist to help you to build your module in a
+MakeMaker-friendly style.  These include ExtUtils::ModuleMaker and h2xs.
+See also perlnewmod.
+.SS Licensing
+.IX Subsection "Licensing"
+Make sure that your module has a license, and that the full text of it
+is included in the distribution (unless it's a common one and the terms
+of the license don't require you to include it).
+.PP
+If you don't know what license to use, dual licensing under the GPL
+and Artistic licenses (the same as Perl itself) is a good idea.
+See perlgpl and perlartistic.
+.SH "COMMON PITFALLS"
+.IX Header "COMMON PITFALLS"
+.SS "Reinventing the wheel"
+.IX Subsection "Reinventing the wheel"
+There are certain application spaces which are already very, very well
+served by CPAN.  One example is templating systems, another is date and
+time modules, and there are many more.  While it is a rite of passage to
+write your own version of these things, please consider carefully
+whether the Perl world really needs you to publish it.
+.SS "Trying to do too much"
+.IX Subsection "Trying to do too much"
+Your module will be part of a developer's toolkit.  It will not, in
+itself, form the \fBentire\fR toolkit.  It's tempting to add extra features
+until your code is a monolithic system rather than a set of modular
+building blocks.
+.SS "Inappropriate documentation"
+.IX Subsection "Inappropriate documentation"
+Don't fall into the trap of writing for the wrong audience.  Your
+primary audience is a reasonably experienced developer with at least 
+a moderate understanding of your module's application domain, who's just 
+downloaded your module and wants to start using it as quickly as possible.
+.PP
+Tutorials, end-user documentation, research papers, FAQs etc are not 
+appropriate in a module's main documentation.  If you really want to 
+write these, include them as sub-documents such as \f(CW\*(C`My::Module::Tutorial\*(C'\fR or
+\&\f(CW\*(C`My::Module::FAQ\*(C'\fR and provide a link in the SEE ALSO section of the
+main documentation.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP perlstyle 4
+.IX Item "perlstyle"
+General Perl style guide
+.IP perlnewmod 4
+.IX Item "perlnewmod"
+How to create a new module
+.IP perlpod 4
+.IX Item "perlpod"
+POD documentation
+.IP podchecker 4
+.IX Item "podchecker"
+Verifies your POD's correctness
+.IP "Packaging Tools" 4
+.IX Item "Packaging Tools"
+ExtUtils::MakeMaker, Module::Build
+.IP "Testing tools" 4
+.IX Item "Testing tools"
+Test::Simple, Test::Inline, Carp::Assert, Test::More, Test::MockObject
+.IP <https://pause.perl.org/> 4
+.IX Item "<https://pause.perl.org/>"
+Perl Authors Upload Server.  Contains links to information for module
+authors.
+.IP "Any good book on software engineering" 4
+.IX Item "Any good book on software engineering"
+.SH AUTHOR
+.IX Header "AUTHOR"
+Kirrily "Skud" Robert <skud@cpan.org>
diff --git a/upstream/mageia-cauldron/man1/perlmroapi.1 b/upstream/mageia-cauldron/man1/perlmroapi.1
new file mode 100644
index 00000000..ab52d2ca
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlmroapi.1
@@ -0,0 +1,155 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLMROAPI 1"
+.TH PERLMROAPI 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlmroapi \- Perl method resolution plugin interface
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+As of Perl 5.10.1 there is a new interface for plugging and using method
+resolution orders other than the default (linear depth first search).
+The C3 method resolution order added in 5.10.0 has been re-implemented as
+a plugin, without changing its Perl-space interface.
+.PP
+Each plugin should register itself by providing
+the following structure
+.PP
+.Vb 7
+\&    struct mro_alg {
+\&        AV *(*resolve)(pTHX_ HV *stash, U32 level);
+\&        const char *name;
+\&        U16 length;
+\&        U16 kflags;
+\&        U32 hash;
+\&    };
+.Ve
+.PP
+and calling \f(CW\*(C`Perl_mro_register\*(C'\fR:
+.PP
+.Vb 1
+\&    Perl_mro_register(aTHX_ &my_mro_alg);
+.Ve
+.IP resolve 4
+.IX Item "resolve"
+Pointer to the linearisation function, described below.
+.IP name 4
+.IX Item "name"
+Name of the MRO, either in ISO\-8859\-1 or UTF\-8.
+.IP length 4
+.IX Item "length"
+Length of the name.
+.IP kflags 4
+.IX Item "kflags"
+If the name is given in UTF\-8, set this to \f(CW\*(C`HVhek_UTF8\*(C'\fR. The value is passed
+direct as the parameter \fIkflags\fR to \f(CWhv_common()\fR.
+.IP hash 4
+.IX Item "hash"
+A precomputed hash value for the MRO's name, or 0.
+.SH Callbacks
+.IX Header "Callbacks"
+The \f(CW\*(C`resolve\*(C'\fR function is called to generate a linearised ISA for the
+given stash, using this MRO. It is called with a pointer to the stash, and
+a \fIlevel\fR of 0. The core always sets \fIlevel\fR to 0 when it calls your
+function \- the parameter is provided to allow your implementation to track
+depth if it needs to recurse.
+.PP
+The function should return a reference to an array containing string SVs
+giving the names of parent classes in order. The names of the classes should
+be the result of calling \f(CWHvENAME()\fR on the stash. In those cases where
+\&\f(CWHvENAME()\fR returns null, \f(CWHvNAME()\fR should be used instead.
+.PP
+The caller is responsible for incrementing the reference count of the array
+returned if it wants to keep the structure. Hence, if you have created a
+temporary value that you keep no pointer to, \f(CWsv_2mortal()\fR to ensure that
+it is disposed of correctly. If you have cached your return value, then
+return a pointer to it without changing the reference count.
+.SH Caching
+.IX Header "Caching"
+Computing MROs can be expensive. The implementation provides a cache, in
+which you can store a single \f(CW\*(C`SV *\*(C'\fR, or anything that can be cast to
+\&\f(CW\*(C`SV *\*(C'\fR, such as \f(CW\*(C`AV *\*(C'\fR. To read your private value, use the macro
+\&\f(CWMRO_GET_PRIVATE_DATA()\fR, passing it the \f(CW\*(C`mro_meta\*(C'\fR structure from the
+stash, and a pointer to your \f(CW\*(C`mro_alg\*(C'\fR structure:
+.PP
+.Vb 2
+\&    meta = HvMROMETA(stash);
+\&    private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);
+.Ve
+.PP
+To set your private value, call \f(CWPerl_mro_set_private_data()\fR:
+.PP
+.Vb 1
+\&    Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv);
+.Ve
+.PP
+The private data cache will take ownership of a reference to private_sv,
+much the same way that \f(CWhv_store()\fR takes ownership of a reference to the
+value that you pass it.
+.SH Examples
+.IX Header "Examples"
+For examples of MRO implementations, see \f(CWS_mro_get_linear_isa_c3()\fR
+and the \f(CW\*(C`BOOT:\*(C'\fR section of \fIext/mro/mro.xs\fR, and
+\&\f(CWS_mro_get_linear_isa_dfs()\fR in \fImro_core.c\fR
+.SH AUTHORS
+.IX Header "AUTHORS"
+The implementation of the C3 MRO and switchable MROs within the perl core was
+written by Brandon L Black. Nicholas Clark created the pluggable interface, 
+refactored Brandon's implementation to work with it, and wrote this document.
diff --git a/upstream/mageia-cauldron/man1/perlnewmod.1 b/upstream/mageia-cauldron/man1/perlnewmod.1
new file mode 100644
index 00000000..315343bb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlnewmod.1
@@ -0,0 +1,319 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLNEWMOD 1"
+.TH PERLNEWMOD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlnewmod \- preparing a new module for distribution
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document gives you some suggestions about how to go about writing
+Perl modules, preparing them for distribution, and making them available
+via CPAN.
+.PP
+One of the things that makes Perl really powerful is the fact that Perl
+hackers tend to want to share the solutions to problems they've faced,
+so you and I don't have to battle with the same problem again.
+.PP
+The main way they do this is by abstracting the solution into a Perl
+module. If you don't know what one of these is, the rest of this
+document isn't going to be much use to you. You're also missing out on
+an awful lot of useful code; consider having a look at perlmod,
+perlmodlib and perlmodinstall before coming back here.
+.PP
+When you've found that there isn't a module available for what you're
+trying to do, and you've had to write the code yourself, consider
+packaging up the solution into a module and uploading it to CPAN so that
+others can benefit.
+.PP
+You should also take a look at perlmodstyle for best practices in
+making a module.
+.SS Warning
+.IX Subsection "Warning"
+We're going to primarily concentrate on Perl-only modules here, rather
+than XS modules. XS modules serve a rather different purpose, and
+you should consider different things before distributing them \- the
+popularity of the library you are gluing, the portability to other
+operating systems, and so on. However, the notes on preparing the Perl
+side of the module and packaging and distributing it will apply equally
+well to an XS module as a pure-Perl one.
+.SS "What should I make into a module?"
+.IX Subsection "What should I make into a module?"
+You should make a module out of any code that you think is going to be
+useful to others. Anything that's likely to fill a hole in the communal
+library and which someone else can slot directly into their program. Any
+part of your code which you can isolate and extract and plug into
+something else is a likely candidate.
+.PP
+Let's take an example. Suppose you're reading in data from a local
+format into a hash-of-hashes in Perl, turning that into a tree, walking
+the tree and then piping each node to an Acme Transmogrifier Server.
+.PP
+Now, quite a few people have the Acme Transmogrifier, and you've had to
+write something to talk the protocol from scratch \- you'd almost
+certainly want to make that into a module. The level at which you pitch
+it is up to you: you might want protocol-level modules analogous to
+Net::SMTP which then talk to higher level modules analogous
+to Mail::Send. The choice is yours, but you do want to get
+a module out for that server protocol.
+.PP
+Nobody else on the planet is going to talk your local data format, so we
+can ignore that. But what about the thing in the middle? Building tree
+structures from Perl variables and then traversing them is a nice,
+general problem, and if nobody's already written a module that does
+that, you might want to modularise that code too.
+.PP
+So hopefully you've now got a few ideas about what's good to modularise.
+Let's now see how it's done.
+.SS "Step-by-step: Preparing the ground"
+.IX Subsection "Step-by-step: Preparing the ground"
+Before we even start scraping out the code, there are a few things we'll
+want to do in advance.
+.IP "Look around" 3
+.IX Item "Look around"
+Dig into a bunch of modules to see how they're written. I'd suggest
+starting with Text::Tabs, since it's in the standard
+library and is nice and simple, and then looking at something a little
+more complex like File::Copy.  For object oriented
+code, WWW::Mechanize or the \f(CW\*(C`Email::*\*(C'\fR modules provide some good
+examples.
+.Sp
+These should give you an overall feel for how modules are laid out and
+written.
+.IP "Check it's new" 3
+.IX Item "Check it's new"
+There are a lot of modules on CPAN, and it's easy to miss one that's
+similar to what you're planning on contributing. Have a good plough
+through <https://metacpan.org> and make sure you're not the one
+reinventing the wheel!
+.IP "Discuss the need" 3
+.IX Item "Discuss the need"
+You might love it. You might feel that everyone else needs it. But there
+might not actually be any real demand for it out there. If you're unsure
+about the demand your module will have, consider asking the
+\&\f(CW\*(C`module\-authors@perl.org\*(C'\fR mailing list (send an email to
+\&\f(CW\*(C`module\-authors\-subscribe@perl.org\*(C'\fR to subscribe; see
+<https://lists.perl.org/list/module\-authors.html> for more information
+and a link to the archives).
+.IP "Choose a name" 3
+.IX Item "Choose a name"
+Perl modules included on CPAN have a naming hierarchy you should try to
+fit in with. See perlmodlib for more details on how this works, and
+browse around CPAN and the modules list to get a feel of it. At the very
+least, remember this: modules should be title capitalised, (This::Thing)
+fit in with a category, and explain their purpose succinctly.
+.IP "Check again" 3
+.IX Item "Check again"
+While you're doing that, make really sure you haven't missed a module
+similar to the one you're about to write.
+.Sp
+When you've got your name sorted out and you're sure that your module is
+wanted and not currently available, it's time to start coding.
+.SS "Step-by-step: Making the module"
+.IX Subsection "Step-by-step: Making the module"
+.IP "Start with \fImodule-starter\fR or \fIh2xs\fR" 3
+.IX Item "Start with module-starter or h2xs"
+The \fImodule-starter\fR utility is distributed as part of the
+Module::Starter CPAN package.  It creates a directory
+with stubs of all the necessary files to start a new module, according
+to recent "best practice" for module development, and is invoked from
+the command line, thus:
+.Sp
+.Vb 2
+\&    module\-starter \-\-module=Foo::Bar \e
+\&       \-\-author="Your Name" \-\-email=yourname@cpan.org
+.Ve
+.Sp
+If you do not wish to install the Module::Starter
+package from CPAN, \fIh2xs\fR is an older tool, originally intended for the
+development of XS modules, which comes packaged with the Perl
+distribution.
+.Sp
+A typical invocation of h2xs for a pure Perl module is:
+.Sp
+.Vb 1
+\&    h2xs \-AX \-\-skip\-exporter \-\-use\-new\-tests \-n Foo::Bar
+.Ve
+.Sp
+The \f(CW\*(C`\-A\*(C'\fR omits the Autoloader code, \f(CW\*(C`\-X\*(C'\fR omits XS elements,
+\&\f(CW\*(C`\-\-skip\-exporter\*(C'\fR omits the Exporter code, \f(CW\*(C`\-\-use\-new\-tests\*(C'\fR sets up a
+modern testing environment, and \f(CW\*(C`\-n\*(C'\fR specifies the name of the module.
+.IP "Use strict and warnings" 3
+.IX Item "Use strict and warnings"
+A module's code has to be warning and strict-clean, since you can't
+guarantee the conditions that it'll be used under. Besides, you wouldn't
+want to distribute code that wasn't warning or strict-clean anyway,
+right?
+.IP "Use Carp" 3
+.IX Item "Use Carp"
+The Carp module allows you to present your error messages from
+the caller's perspective; this gives you a way to signal a problem with
+the caller and not your module. For instance, if you say this:
+.Sp
+.Vb 1
+\&    warn "No hostname given";
+.Ve
+.Sp
+the user will see something like this:
+.Sp
+.Vb 2
+\& No hostname given at
+\& /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.
+.Ve
+.Sp
+which looks like your module is doing something wrong. Instead, you want
+to put the blame on the user, and say this:
+.Sp
+.Vb 1
+\&    No hostname given at bad_code, line 10.
+.Ve
+.Sp
+You do this by using Carp and replacing your \f(CW\*(C`warn\*(C'\fRs with
+\&\f(CW\*(C`carp\*(C'\fRs. If you need to \f(CW\*(C`die\*(C'\fR, say \f(CW\*(C`croak\*(C'\fR instead. However, keep
+\&\f(CW\*(C`warn\*(C'\fR and \f(CW\*(C`die\*(C'\fR in place for your sanity checks \- where it really is
+your module at fault.
+.IP "Use Exporter \- wisely!" 3
+.IX Item "Use Exporter - wisely!"
+Exporter gives you a standard way of exporting symbols and
+subroutines from your module into the caller's namespace. For instance,
+saying \f(CW\*(C`use Net::Acme qw(&frob)\*(C'\fR would import the \f(CW\*(C`frob\*(C'\fR subroutine.
+.Sp
+The package variable \f(CW@EXPORT\fR will determine which symbols will get
+exported when the caller simply says \f(CW\*(C`use Net::Acme\*(C'\fR \- you will hardly
+ever want to put anything in there. \f(CW@EXPORT_OK\fR, on the other hand,
+specifies which symbols you're willing to export. If you do want to
+export a bunch of symbols, use the \f(CW%EXPORT_TAGS\fR and define a standard
+export set \- look at Exporter for more details.
+.IP "Use plain old documentation" 3
+.IX Item "Use plain old documentation"
+The work isn't over until the paperwork is done, and you're going to
+need to put in some time writing some documentation for your module.
+\&\f(CW\*(C`module\-starter\*(C'\fR or \f(CW\*(C`h2xs\*(C'\fR will provide a stub for you to fill in; if
+you're not sure about the format, look at perlpod for an
+introduction. Provide a good synopsis of how your module is used in
+code, a description, and then notes on the syntax and function of the
+individual subroutines or methods. Use Perl comments for developer notes
+and POD for end-user notes.
+.IP "Write tests" 3
+.IX Item "Write tests"
+You're encouraged to create self-tests for your module to ensure it's
+working as intended on the myriad platforms Perl supports; if you upload
+your module to CPAN, a host of testers will build your module and send
+you the results of the tests. Again, \f(CW\*(C`module\-starter\*(C'\fR and \f(CW\*(C`h2xs\*(C'\fR
+provide a test framework which you can extend \- you should do something
+more than just checking your module will compile.
+Test::Simple and Test::More are good
+places to start when writing a test suite.
+.IP "Write the \fIREADME\fR" 3
+.IX Item "Write the README"
+If you're uploading to CPAN, the automated gremlins will extract the
+README file and place that in your CPAN directory. It'll also appear in
+the main \fIby-module\fR and \fIby-category\fR directories if you make it onto
+the modules list. It's a good idea to put here what the module actually
+does in detail.
+.IP "Write \fIChanges\fR" 3
+.IX Item "Write Changes"
+Add any user-visible changes since the last release to your \fIChanges\fR
+file.
+.SS "Step-by-step: Distributing your module"
+.IX Subsection "Step-by-step: Distributing your module"
+.IP "Get a CPAN user ID" 3
+.IX Item "Get a CPAN user ID"
+Every developer publishing modules on CPAN needs a CPAN ID.  Visit
+\&\f(CW\*(C`<https://pause.perl.org/>\*(C'\fR, select "Request PAUSE Account", and wait for
+your request to be approved by the PAUSE administrators.
+.IP "Make the tarball" 3
+.IX Item "Make the tarball"
+Once again, \f(CW\*(C`module\-starter\*(C'\fR or \f(CW\*(C`h2xs\*(C'\fR has done all the work for you.
+They produce the standard \f(CW\*(C`Makefile.PL\*(C'\fR you see when you download and
+install modules, and this produces a Makefile with a \f(CW\*(C`dist\*(C'\fR target.
+.Sp
+.Vb 1
+\&    perl Makefile.PL && make test && make distcheck && make dist
+.Ve
+.Sp
+Once you've ensured that your module passes its own tests \- always a
+good thing to make sure \- you can \f(CW\*(C`make distcheck\*(C'\fR to make sure
+everything looks OK, followed by \f(CW\*(C`make dist\*(C'\fR, and the Makefile will
+hopefully produce you a nice tarball of your module, ready for upload.
+.IP "Upload the tarball" 3
+.IX Item "Upload the tarball"
+The email you got when you received your CPAN ID will tell you how to
+log in to PAUSE, the Perl Authors Upload SErver. From the menus there,
+you can upload your module to CPAN.
+.Sp
+Alternatively you can use the \fIcpan-upload\fR script, part of the
+CPAN::Uploader distribution on CPAN.
+.IP "Fix bugs!" 3
+.IX Item "Fix bugs!"
+Once you start accumulating users, they'll send you bug reports. If
+you're lucky, they'll even send you patches. Welcome to the joys of
+maintaining a software project...
+.SH AUTHOR
+.IX Header "AUTHOR"
+Simon Cozens, \f(CW\*(C`simon@cpan.org\*(C'\fR
+.PP
+Updated by Kirrily "Skud" Robert, \f(CW\*(C`skud@cpan.org\*(C'\fR
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlmod, perlmodlib, perlmodinstall, h2xs, strict,
+Carp, Exporter, perlpod, Test::Simple, Test::More
+ExtUtils::MakeMaker, Module::Build, Module::Starter
+<https://www.cpan.org/>
diff --git a/upstream/mageia-cauldron/man1/perlnumber.1 b/upstream/mageia-cauldron/man1/perlnumber.1
new file mode 100644
index 00000000..2b537163
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlnumber.1
@@ -0,0 +1,244 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLNUMBER 1"
+.TH PERLNUMBER 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlnumber \- semantics of numbers and numeric operations in Perl
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 7
+\&    $n = 1234;              # decimal integer
+\&    $n = 0b1110011;         # binary integer
+\&    $n = 01234;             # octal integer
+\&    $n = 0x1234;            # hexadecimal integer
+\&    $n = 12.34e\-56;         # exponential notation
+\&    $n = "\-12.34e56";       # number specified as a string
+\&    $n = "1234";            # number specified as a string
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes how Perl internally handles numeric values.
+.PP
+Perl's operator overloading facility is completely ignored here.  Operator
+overloading allows user-defined behaviors for numbers, such as operations
+over arbitrarily large integers, floating points numbers with arbitrary
+precision, operations over "exotic" numbers such as modular arithmetic or
+p\-adic arithmetic, and so on.  See overload for details.
+.SH "Storing numbers"
+.IX Header "Storing numbers"
+Perl can internally represent numbers in 3 different ways: as native
+integers, as native floating point numbers, and as decimal strings.
+Decimal strings may have an exponential notation part, as in \f(CW"12.34e\-56"\fR.
+\&\fINative\fR here means "a format supported by the C compiler which was used
+to build perl".
+.PP
+The term "native" does not mean quite as much when we talk about native
+integers, as it does when native floating point numbers are involved.
+The only implication of the term "native" on integers is that the limits for
+the maximal and the minimal supported true integral quantities are close to
+powers of 2.  However, "native" floats have a most fundamental
+restriction: they may represent only those numbers which have a relatively
+"short" representation when converted to a binary fraction.  For example,
+0.9 cannot be represented by a native float, since the binary fraction
+for 0.9 is infinite:
+.PP
+.Vb 1
+\&  binary0.1110011001100...
+.Ve
+.PP
+with the sequence \f(CW1100\fR repeating again and again.  In addition to this
+limitation,  the exponent of the binary number is also restricted when it
+is represented as a floating point number.  On typical hardware, floating
+point values can store numbers with up to 53 binary digits, and with binary
+exponents between \-1024 and 1024.  In decimal representation this is close
+to 16 decimal digits and decimal exponents in the range of \-304..304.
+The upshot of all this is that Perl cannot store a number like
+12345678901234567 as a floating point number on such architectures without
+loss of information.
+.PP
+Similarly, decimal strings can represent only those numbers which have a
+finite decimal expansion.  Being strings, and thus of arbitrary length, there
+is no practical limit for the exponent or number of decimal digits for these
+numbers.  (But realize that what we are discussing the rules for just the
+\&\fIstorage\fR of these numbers.  The fact that you can store such "large" numbers
+does not mean that the \fIoperations\fR over these numbers will use all
+of the significant digits.
+See "Numeric operators and numeric conversions" for details.)
+.PP
+In fact numbers stored in the native integer format may be stored either
+in the signed native form, or in the unsigned native form.  Thus the limits
+for Perl numbers stored as native integers would typically be \-2**31..2**32\-1,
+with appropriate modifications in the case of 64\-bit integers.  Again, this
+does not mean that Perl can do operations only over integers in this range:
+it is possible to store many more integers in floating point format.
+.PP
+Summing up, Perl numeric values can store only those numbers which have
+a finite decimal expansion or a "short" binary expansion.
+.SH "Numeric operators and numeric conversions"
+.IX Header "Numeric operators and numeric conversions"
+As mentioned earlier, Perl can store a number in any one of three formats,
+but most operators typically understand only one of those formats.  When
+a numeric value is passed as an argument to such an operator, it will be
+converted to the format understood by the operator.
+.PP
+Six such conversions are possible:
+.PP
+.Vb 6
+\&  native integer        \-\-> native floating point       (*)
+\&  native integer        \-\-> decimal string
+\&  native floating_point \-\-> native integer              (*)
+\&  native floating_point \-\-> decimal string              (*)
+\&  decimal string        \-\-> native integer
+\&  decimal string        \-\-> native floating point       (*)
+.Ve
+.PP
+These conversions are governed by the following general rules:
+.IP \(bu 4
+If the source number can be represented in the target form, that
+representation is used.
+.IP \(bu 4
+If the source number is outside of the limits representable in the target form,
+a representation of the closest limit is used.  (\fILoss of information\fR)
+.IP \(bu 4
+If the source number is between two numbers representable in the target form,
+a representation of one of these numbers is used.  (\fILoss of information\fR)
+.IP \(bu 4
+In \f(CW\*(C`native floating point \-\-> native integer\*(C'\fR conversions the magnitude
+of the result is less than or equal to the magnitude of the source.
+(\fI"Rounding to zero".\fR)
+.IP \(bu 4
+If the \f(CW\*(C`decimal string \-\-> native integer\*(C'\fR conversion cannot be done
+without loss of information, the result is compatible with the conversion
+sequence \f(CW\*(C`decimal_string \-\-> native_floating_point \-\-> native_integer\*(C'\fR.
+In particular, rounding is strongly biased to 0, though a number like
+\&\f(CW"0.99999999999999999999"\fR has a chance of being rounded to 1.
+.PP
+\&\fBRESTRICTION\fR: The conversions marked with \f(CW\*(C`(*)\*(C'\fR above involve steps
+performed by the C compiler.  In particular, bugs/features of the compiler
+used may lead to breakage of some of the above rules.
+.SH "Flavors of Perl numeric operations"
+.IX Header "Flavors of Perl numeric operations"
+Perl operations which take a numeric argument treat that argument in one of
+four different ways: they may force it to one of the integer, floating, or
+string formats; or they may behave differently depending on the format of the
+operand.  Forcing a numeric value to a particular format does not change the
+number stored in the value.
+.PP
+All the operators which need an argument in the integer format treat the
+argument as in modular arithmetic, e.g., \f(CW\*(C`mod 2**32\*(C'\fR on a 32\-bit
+architecture.  \f(CW\*(C`sprintf "%u", \-1\*(C'\fR therefore provides the same result as
+\&\f(CW\*(C`sprintf "%u", ~0\*(C'\fR.
+.IP "Arithmetic operators" 4
+.IX Item "Arithmetic operators"
+The binary operators \f(CW\*(C`+\*(C'\fR \f(CW\*(C`\-\*(C'\fR \f(CW\*(C`*\*(C'\fR \f(CW\*(C`/\*(C'\fR \f(CW\*(C`%\*(C'\fR \f(CW\*(C`==\*(C'\fR \f(CW\*(C`!=\*(C'\fR \f(CW\*(C`>\*(C'\fR \f(CW\*(C`<\*(C'\fR
+\&\f(CW\*(C`>=\*(C'\fR \f(CW\*(C`<=\*(C'\fR and the unary operators \f(CW\*(C`\-\*(C'\fR \f(CW\*(C`abs\*(C'\fR and \f(CW\*(C`\-\-\*(C'\fR will
+attempt to convert arguments to integers.  If both conversions are possible
+without loss of precision, and the operation can be performed without
+loss of precision then the integer result is used.  Otherwise arguments are
+converted to floating point format and the floating point result is used.
+The caching of conversions (as described above) means that the integer
+conversion does not throw away fractional parts on floating point numbers.
+.IP ++ 4
+\&\f(CW\*(C`++\*(C'\fR behaves as the other operators above, except that if it is a string
+matching the format \f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR the string increment described
+in perlop is used.
+.ie n .IP "Arithmetic operators during ""use integer""" 4
+.el .IP "Arithmetic operators during \f(CWuse integer\fR" 4
+.IX Item "Arithmetic operators during use integer"
+In scopes where \f(CW\*(C`use integer;\*(C'\fR is in force, nearly all the operators listed
+above will force their argument(s) into integer format, and return an integer
+result.  The exceptions, \f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`++\*(C'\fR and \f(CW\*(C`\-\-\*(C'\fR, do not change their
+behavior with \f(CW\*(C`use integer;\*(C'\fR
+.IP "Other mathematical operators" 4
+.IX Item "Other mathematical operators"
+Operators such as \f(CW\*(C`**\*(C'\fR, \f(CW\*(C`sin\*(C'\fR and \f(CW\*(C`exp\*(C'\fR force arguments to floating point
+format.
+.IP "Bitwise operators" 4
+.IX Item "Bitwise operators"
+Arguments are forced into the integer format if not strings.
+.ie n .IP "Bitwise operators during ""use integer""" 4
+.el .IP "Bitwise operators during \f(CWuse integer\fR" 4
+.IX Item "Bitwise operators during use integer"
+forces arguments to integer format. Also shift operations internally use
+signed integers rather than the default unsigned.
+.IP "Operators which expect an integer" 4
+.IX Item "Operators which expect an integer"
+force the argument into the integer format.  This is applicable
+to the third and fourth arguments of \f(CW\*(C`sysread\*(C'\fR, for example.
+.IP "Operators which expect a string" 4
+.IX Item "Operators which expect a string"
+force the argument into the string format.  For example, this is
+applicable to \f(CW\*(C`printf "%s", $value\*(C'\fR.
+.PP
+Though forcing an argument into a particular form does not change the
+stored number, Perl remembers the result of such conversions.  In
+particular, though the first such conversion may be time-consuming,
+repeated operations will not need to redo the conversion.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Ilya Zakharevich \f(CW\*(C`ilya@math.ohio\-state.edu\*(C'\fR
+.PP
+Editorial adjustments by Gurusamy Sarathy <gsar@ActiveState.com>
+.PP
+Updates for 5.8.0 by Nicholas Clark <nick@ccl4.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+overload, perlop
diff --git a/upstream/mageia-cauldron/man1/perlobj.1 b/upstream/mageia-cauldron/man1/perlobj.1
new file mode 100644
index 00000000..0c4d4b89
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlobj.1
@@ -0,0 +1,1203 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOBJ 1"
+.TH PERLOBJ 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlobj \- Perl object reference
+.IX Xref "object OOP"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides a reference for Perl's object orientation
+features. If you're looking for an introduction to object-oriented
+programming in Perl, please see perlootut.
+.PP
+In order to understand Perl objects, you first need to understand
+references in Perl. See perlreftut for details.
+.PP
+This document describes all of Perl's object-oriented (OO) features
+from the ground up. If you're just looking to write some
+object-oriented code of your own, you are probably better served by
+using one of the object systems from CPAN described in perlootut.
+.PP
+If you're looking to write your own object system, or you need to
+maintain code which implements objects from scratch then this document
+will help you understand exactly how Perl does object orientation.
+.PP
+There are a few basic principles which define object oriented Perl:
+.IP 1. 4
+An object is simply a data structure that knows to which class it
+belongs.
+.IP 2. 4
+A class is simply a package. A class provides methods that expect to
+operate on objects.
+.IP 3. 4
+A method is simply a subroutine that expects a reference to an object
+(or a package name, for class methods) as the first argument.
+.PP
+Let's look at each of these principles in depth.
+.SS "An Object is Simply a Data Structure"
+.IX Xref "object bless constructor new"
+.IX Subsection "An Object is Simply a Data Structure"
+Unlike many other languages which support object orientation, Perl does
+not provide any special syntax for constructing an object. Objects are
+merely Perl data structures (hashes, arrays, scalars, filehandles,
+etc.) that have been explicitly associated with a particular class.
+.PP
+That explicit association is created by the built-in \f(CW\*(C`bless\*(C'\fR function,
+which is typically used within the \fIconstructor\fR subroutine of the
+class.
+.PP
+Here is a simple constructor:
+.PP
+.Vb 1
+\&  package File;
+\&
+\&  sub new {
+\&      my $class = shift;
+\&
+\&      return bless {}, $class;
+\&  }
+.Ve
+.PP
+The name \f(CW\*(C`new\*(C'\fR isn't special. We could name our constructor something
+else:
+.PP
+.Vb 1
+\&  package File;
+\&
+\&  sub load {
+\&      my $class = shift;
+\&
+\&      return bless {}, $class;
+\&  }
+.Ve
+.PP
+The modern convention for OO modules is to always use \f(CW\*(C`new\*(C'\fR as the
+name for the constructor, but there is no requirement to do so. Any
+subroutine that blesses a data structure into a class is a valid
+constructor in Perl.
+.PP
+In the previous examples, the \f(CW\*(C`{}\*(C'\fR code creates a reference to an
+empty anonymous hash. The \f(CW\*(C`bless\*(C'\fR function then takes that reference
+and associates the hash with the class in \f(CW$class\fR. In the simplest
+case, the \f(CW$class\fR variable will end up containing the string "File".
+.PP
+We can also use a variable to store a reference to the data structure
+that is being blessed as our object:
+.PP
+.Vb 2
+\&  sub new {
+\&      my $class = shift;
+\&
+\&      my $self = {};
+\&      bless $self, $class;
+\&
+\&      return $self;
+\&  }
+.Ve
+.PP
+Once we've blessed the hash referred to by \f(CW$self\fR we can start
+calling methods on it. This is useful if you want to put object
+initialization in its own separate method:
+.PP
+.Vb 2
+\&  sub new {
+\&      my $class = shift;
+\&
+\&      my $self = {};
+\&      bless $self, $class;
+\&
+\&      $self\->_initialize();
+\&
+\&      return $self;
+\&  }
+.Ve
+.PP
+Since the object is also a hash, you can treat it as one, using it to
+store data associated with the object. Typically, code inside the class
+can treat the hash as an accessible data structure, while code outside
+the class should always treat the object as opaque. This is called
+\&\fBencapsulation\fR. Encapsulation means that the user of an object does
+not have to know how it is implemented. The user simply calls
+documented methods on the object.
+.PP
+Note, however, that (unlike most other OO languages) Perl does not
+ensure or enforce encapsulation in any way. If you want objects to
+actually \fIbe\fR opaque you need to arrange for that yourself. This can
+be done in a variety of ways, including using "Inside-Out objects"
+or modules from CPAN.
+.PP
+\fIObjects Are Blessed; Variables Are Not\fR
+.IX Subsection "Objects Are Blessed; Variables Are Not"
+.PP
+When we bless something, we are not blessing the variable which
+contains a reference to that thing, nor are we blessing the reference
+that the variable stores; we are blessing the thing that the variable
+refers to (sometimes known as the \fIreferent\fR). This is best
+demonstrated with this code:
+.PP
+.Vb 1
+\&  use Scalar::Util \*(Aqblessed\*(Aq;
+\&
+\&  my $foo = {};
+\&  my $bar = $foo;
+\&
+\&  bless $foo, \*(AqClass\*(Aq;
+\&  print blessed( $bar ) // \*(Aqnot blessed\*(Aq;    # prints "Class"
+\&
+\&  $bar = "some other value";
+\&  print blessed( $bar ) // \*(Aqnot blessed\*(Aq;    # prints "not blessed"
+.Ve
+.PP
+When we call \f(CW\*(C`bless\*(C'\fR on a variable, we are actually blessing the
+underlying data structure that the variable refers to. We are not
+blessing the reference itself, nor the variable that contains that
+reference. That's why the second call to \f(CWblessed( $bar )\fR returns
+false. At that point \f(CW$bar\fR is no longer storing a reference to an
+object.
+.PP
+You will sometimes see older books or documentation mention "blessing a
+reference" or describe an object as a "blessed reference", but this is
+incorrect. It isn't the reference that is blessed as an object; it's
+the thing the reference refers to (i.e. the referent).
+.SS "A Class is Simply a Package"
+.IX Xref "class package @ISA inheritance"
+.IX Subsection "A Class is Simply a Package"
+Perl does not provide any special syntax for class definitions. A
+package is simply a namespace containing variables and subroutines. The
+only difference is that in a class, the subroutines may expect a
+reference to an object or the name of a class as the first argument.
+This is purely a matter of convention, so a class may contain both
+methods and subroutines which \fIdon't\fR operate on an object or class.
+.PP
+Each package contains a special array called \f(CW@ISA\fR. The \f(CW@ISA\fR array
+contains a list of that class's parent classes, if any. This array is
+examined when Perl does method resolution, which we will cover later.
+.PP
+Calling methods from a package means it must be loaded, of course, so
+you will often want to load a module and add it to \f(CW@ISA\fR at the same
+time. You can do so in a single step using the parent pragma.
+(In older code you may encounter the base pragma, which is nowadays
+discouraged except when you have to work with the equally discouraged
+fields pragma.)
+.PP
+However the parent classes are set, the package's \f(CW@ISA\fR variable will
+contain a list of those parents. This is simply a list of scalars, each
+of which is a string that corresponds to a package name.
+.PP
+All classes inherit from the UNIVERSAL class implicitly. The
+UNIVERSAL class is implemented by the Perl core, and provides
+several default methods, such as \f(CWisa()\fR, \f(CWcan()\fR, and \f(CWVERSION()\fR.
+The \f(CW\*(C`UNIVERSAL\*(C'\fR class will \fInever\fR appear in a package's \f(CW@ISA\fR
+variable.
+.PP
+Perl \fIonly\fR provides method inheritance as a built-in feature.
+Attribute inheritance is left up the class to implement. See the
+"Writing Accessors" section for details.
+.SS "A Method is Simply a Subroutine"
+.IX Xref "method"
+.IX Subsection "A Method is Simply a Subroutine"
+Perl does not provide any special syntax for defining a method. A
+method is simply a regular subroutine, and is declared with \f(CW\*(C`sub\*(C'\fR.
+What makes a method special is that it expects to receive either an
+object or a class name as its first argument.
+.PP
+Perl \fIdoes\fR provide special syntax for method invocation, the \f(CW\*(C`\->\*(C'\fR operator. We will cover this in more detail later.
+.PP
+Most methods you write will expect to operate on objects:
+.PP
+.Vb 2
+\&  sub save {
+\&      my $self = shift;
+\&
+\&      open my $fh, \*(Aq>\*(Aq, $self\->path() or die $!;
+\&      print {$fh} $self\->data()       or die $!;
+\&      close $fh                       or die $!;
+\&  }
+.Ve
+.SS "Method Invocation"
+.IX Xref "invocation method arrow ->"
+.IX Subsection "Method Invocation"
+Calling a method on an object is written as \f(CW\*(C`$object\->method\*(C'\fR.
+.PP
+The left hand side of the method invocation (or arrow) operator is the
+object (or class name), and the right hand side is the method name.
+.PP
+.Vb 2
+\&  my $pod = File\->new( \*(Aqperlobj.pod\*(Aq, $data );
+\&  $pod\->save();
+.Ve
+.PP
+The \f(CW\*(C`\->\*(C'\fR syntax is also used when dereferencing a reference. It
+looks like the same operator, but these are two different operations.
+.PP
+When you call a method, the thing on the left side of the arrow is
+passed as the first argument to the method. That means when we call \f(CW\*(C`Critter\->new()\*(C'\fR, the \f(CWnew()\fR method receives the string \f(CW"Critter"\fR
+as its first argument. When we call \f(CW\*(C`$fred\->speak()\*(C'\fR, the \f(CW$fred\fR
+variable is passed as the first argument to \f(CWspeak()\fR.
+.PP
+Just as with any Perl subroutine, all of the arguments passed in \f(CW@_\fR
+are aliases to the original argument. This includes the object itself.
+If you assign directly to \f(CW$_[0]\fR you will change the contents of the
+variable that holds the reference to the object. We recommend that you
+don't do this unless you know exactly what you're doing.
+.PP
+Perl knows what package the method is in by looking at the left side of
+the arrow. If the left hand side is a package name, it looks for the
+method in that package. If the left hand side is an object, then Perl
+looks for the method in the package that the object has been blessed
+into.
+.PP
+If the left hand side is neither a package name nor an object, then the
+method call will cause an error, but see the section on "Method Call
+Variations" for more nuances.
+.SS Inheritance
+.IX Xref "inheritance"
+.IX Subsection "Inheritance"
+We already talked about the special \f(CW@ISA\fR array and the parent
+pragma.
+.PP
+When a class inherits from another class, any methods defined in the
+parent class are available to the child class. If you attempt to call a
+method on an object that isn't defined in its own class, Perl will also
+look for that method in any parent classes it may have.
+.PP
+.Vb 2
+\&  package File::MP3;
+\&  use parent \*(AqFile\*(Aq;    # sets @File::MP3::ISA = (\*(AqFile\*(Aq);
+\&
+\&  my $mp3 = File::MP3\->new( \*(AqAndvari.mp3\*(Aq, $data );
+\&  $mp3\->save();
+.Ve
+.PP
+Since we didn't define a \f(CWsave()\fR method in the \f(CW\*(C`File::MP3\*(C'\fR class,
+Perl will look at the \f(CW\*(C`File::MP3\*(C'\fR class's parent classes to find the
+\&\f(CWsave()\fR method. If Perl cannot find a \f(CWsave()\fR method anywhere in
+the inheritance hierarchy, it will die.
+.PP
+In this case, it finds a \f(CWsave()\fR method in the \f(CW\*(C`File\*(C'\fR class. Note
+that the object passed to \f(CWsave()\fR in this case is still a
+\&\f(CW\*(C`File::MP3\*(C'\fR object, even though the method is found in the \f(CW\*(C`File\*(C'\fR
+class.
+.PP
+We can override a parent's method in a child class. When we do so, we
+can still call the parent class's method with the \f(CW\*(C`SUPER\*(C'\fR
+pseudo-class.
+.PP
+.Vb 2
+\&  sub save {
+\&      my $self = shift;
+\&
+\&      say \*(AqPrepare to rock\*(Aq;
+\&      $self\->SUPER::save();
+\&  }
+.Ve
+.PP
+The \f(CW\*(C`SUPER\*(C'\fR modifier can \fIonly\fR be used for method calls. You can't
+use it for regular subroutine calls or class methods:
+.PP
+.Vb 1
+\&  SUPER::save($thing);     # FAIL: looks for save() sub in package SUPER
+\&
+\&  SUPER\->save($thing);     # FAIL: looks for save() method in class
+\&                           #       SUPER
+\&
+\&  $thing\->SUPER::save();   # Okay: looks for save() method in parent
+\&                           #       classes
+.Ve
+.PP
+\fIHow SUPER is Resolved\fR
+.IX Xref "SUPER"
+.IX Subsection "How SUPER is Resolved"
+.PP
+The \f(CW\*(C`SUPER\*(C'\fR pseudo-class is resolved from the package where the call
+is made. It is \fInot\fR resolved based on the object's class. This is
+important, because it lets methods at different levels within a deep
+inheritance hierarchy each correctly call their respective parent
+methods.
+.PP
+.Vb 1
+\&  package A;
+\&
+\&  sub new {
+\&      return bless {}, shift;
+\&  }
+\&
+\&  sub speak {
+\&      my $self = shift;
+\&
+\&      say \*(AqA\*(Aq;
+\&  }
+\&
+\&  package B;
+\&
+\&  use parent \-norequire, \*(AqA\*(Aq;
+\&
+\&  sub speak {
+\&      my $self = shift;
+\&
+\&      $self\->SUPER::speak();
+\&
+\&      say \*(AqB\*(Aq;
+\&  }
+\&
+\&  package C;
+\&
+\&  use parent \-norequire, \*(AqB\*(Aq;
+\&
+\&  sub speak {
+\&      my $self = shift;
+\&
+\&      $self\->SUPER::speak();
+\&
+\&      say \*(AqC\*(Aq;
+\&  }
+\&
+\&  my $c = C\->new();
+\&  $c\->speak();
+.Ve
+.PP
+In this example, we will get the following output:
+.PP
+.Vb 3
+\&  A
+\&  B
+\&  C
+.Ve
+.PP
+This demonstrates how \f(CW\*(C`SUPER\*(C'\fR is resolved. Even though the object is
+blessed into the \f(CW\*(C`C\*(C'\fR class, the \f(CWspeak()\fR method in the \f(CW\*(C`B\*(C'\fR class
+can still call \f(CWSUPER::speak()\fR and expect it to correctly look in the
+parent class of \f(CW\*(C`B\*(C'\fR (i.e the class the method call is in), not in the
+parent class of \f(CW\*(C`C\*(C'\fR (i.e. the class the object belongs to).
+.PP
+There are rare cases where this package-based resolution can be a
+problem. If you copy a subroutine from one package to another, \f(CW\*(C`SUPER\*(C'\fR
+resolution will be done based on the original package.
+.PP
+\fIMultiple Inheritance\fR
+.IX Xref "multiple inheritance"
+.IX Subsection "Multiple Inheritance"
+.PP
+Multiple inheritance often indicates a design problem, but Perl always
+gives you enough rope to hang yourself with if you ask for it.
+.PP
+To declare multiple parents, you simply need to pass multiple class
+names to \f(CW\*(C`use parent\*(C'\fR:
+.PP
+.Vb 1
+\&  package MultiChild;
+\&
+\&  use parent \*(AqParent1\*(Aq, \*(AqParent2\*(Aq;
+.Ve
+.PP
+\fIMethod Resolution Order\fR
+.IX Xref "method resolution order mro"
+.IX Subsection "Method Resolution Order"
+.PP
+Method resolution order only matters in the case of multiple
+inheritance. In the case of single inheritance, Perl simply looks up
+the inheritance chain to find a method:
+.PP
+.Vb 5
+\&  Grandparent
+\&    |
+\&  Parent
+\&    |
+\&  Child
+.Ve
+.PP
+If we call a method on a \f(CW\*(C`Child\*(C'\fR object and that method is not defined
+in the \f(CW\*(C`Child\*(C'\fR class, Perl will look for that method in the \f(CW\*(C`Parent\*(C'\fR
+class and then, if necessary, in the \f(CW\*(C`Grandparent\*(C'\fR class.
+.PP
+If Perl cannot find the method in any of these classes, it will die
+with an error message.
+.PP
+When a class has multiple parents, the method lookup order becomes more
+complicated.
+.PP
+By default, Perl does a depth-first left-to-right search for a method.
+That means it starts with the first parent in the \f(CW@ISA\fR array, and
+then searches all of its parents, grandparents, etc. If it fails to
+find the method, it then goes to the next parent in the original
+class's \f(CW@ISA\fR array and searches from there.
+.PP
+.Vb 7
+\&            SharedGreatGrandParent
+\&            /                    \e
+\&  PaternalGrandparent       MaternalGrandparent
+\&            \e                    /
+\&             Father        Mother
+\&                   \e      /
+\&                    Child
+.Ve
+.PP
+So given the diagram above, Perl will search \f(CW\*(C`Child\*(C'\fR, \f(CW\*(C`Father\*(C'\fR,
+\&\f(CW\*(C`PaternalGrandparent\*(C'\fR, \f(CW\*(C`SharedGreatGrandParent\*(C'\fR, \f(CW\*(C`Mother\*(C'\fR, and
+finally \f(CW\*(C`MaternalGrandparent\*(C'\fR. This may be a problem because now we're
+looking in \f(CW\*(C`SharedGreatGrandParent\*(C'\fR \fIbefore\fR we've checked all its
+derived classes (i.e. before we tried \f(CW\*(C`Mother\*(C'\fR and
+\&\f(CW\*(C`MaternalGrandparent\*(C'\fR).
+.PP
+It is possible to ask for a different method resolution order with the
+mro pragma.
+.PP
+.Vb 1
+\&  package Child;
+\&
+\&  use mro \*(Aqc3\*(Aq;
+\&  use parent \*(AqFather\*(Aq, \*(AqMother\*(Aq;
+.Ve
+.PP
+This pragma lets you switch to the "C3" resolution order. In simple
+terms, "C3" order ensures that shared parent classes are never searched
+before child classes, so Perl will now search: \f(CW\*(C`Child\*(C'\fR, \f(CW\*(C`Father\*(C'\fR,
+\&\f(CW\*(C`PaternalGrandparent\*(C'\fR, \f(CW\*(C`Mother\*(C'\fR \f(CW\*(C`MaternalGrandparent\*(C'\fR, and finally
+\&\f(CW\*(C`SharedGreatGrandParent\*(C'\fR. Note however that this is not
+"breadth-first" searching: All the \f(CW\*(C`Father\*(C'\fR ancestors (except the
+common ancestor) are searched before any of the \f(CW\*(C`Mother\*(C'\fR ancestors are
+considered.
+.PP
+The C3 order also lets you call methods in sibling classes with the
+\&\f(CW\*(C`next\*(C'\fR pseudo-class. See the mro documentation for more details on
+this feature.
+.PP
+\fIMethod Resolution Caching\fR
+.IX Subsection "Method Resolution Caching"
+.PP
+When Perl searches for a method, it caches the lookup so that future
+calls to the method do not need to search for it again. Changing a
+class's parent class or adding subroutines to a class will invalidate
+the cache for that class.
+.PP
+The mro pragma provides some functions for manipulating the method
+cache directly.
+.SS "Writing Constructors"
+.IX Xref "constructor"
+.IX Subsection "Writing Constructors"
+As we mentioned earlier, Perl provides no special constructor syntax.
+This means that a class must implement its own constructor. A
+constructor is simply a class method that returns a reference to a new
+object.
+.PP
+The constructor can also accept additional parameters that define the
+object. Let's write a real constructor for the \f(CW\*(C`File\*(C'\fR class we used
+earlier:
+.PP
+.Vb 1
+\&  package File;
+\&
+\&  sub new {
+\&      my $class = shift;
+\&      my ( $path, $data ) = @_;
+\&
+\&      my $self = bless {
+\&          path => $path,
+\&          data => $data,
+\&      }, $class;
+\&
+\&      return $self;
+\&  }
+.Ve
+.PP
+As you can see, we've stored the path and file data in the object
+itself. Remember, under the hood, this object is still just a hash.
+Later, we'll write accessors to manipulate this data.
+.PP
+For our \f(CW\*(C`File::MP3\*(C'\fR class, we can check to make sure that the path
+we're given ends with ".mp3":
+.PP
+.Vb 1
+\&  package File::MP3;
+\&
+\&  sub new {
+\&      my $class = shift;
+\&      my ( $path, $data ) = @_;
+\&
+\&      die "You cannot create a File::MP3 without an mp3 extension\en"
+\&          unless $path =~ /\e.mp3\ez/;
+\&
+\&      return $class\->SUPER::new(@_);
+\&  }
+.Ve
+.PP
+This constructor lets its parent class do the actual object
+construction.
+.SS Attributes
+.IX Xref "attribute"
+.IX Subsection "Attributes"
+An attribute is a piece of data belonging to a particular object.
+Unlike most object-oriented languages, Perl provides no special syntax
+or support for declaring and manipulating attributes.
+.PP
+Attributes are often stored in the object itself. For example, if the
+object is an anonymous hash, we can store the attribute values in the
+hash using the attribute name as the key.
+.PP
+While it's possible to refer directly to these hash keys outside of the
+class, it's considered a best practice to wrap all access to the
+attribute with accessor methods.
+.PP
+This has several advantages. Accessors make it easier to change the
+implementation of an object later while still preserving the original
+API.
+.PP
+An accessor lets you add additional code around attribute access. For
+example, you could apply a default to an attribute that wasn't set in
+the constructor, or you could validate that a new value for the
+attribute is acceptable.
+.PP
+Finally, using accessors makes inheritance much simpler. Subclasses can
+use the accessors rather than having to know how a parent class is
+implemented internally.
+.PP
+\fIWriting Accessors\fR
+.IX Xref "accessor"
+.IX Subsection "Writing Accessors"
+.PP
+As with constructors, Perl provides no special accessor declaration
+syntax, so classes must provide explicitly written accessor methods.
+There are two common types of accessors, read-only and read-write.
+.PP
+A simple read-only accessor simply gets the value of a single
+attribute:
+.PP
+.Vb 2
+\&  sub path {
+\&      my $self = shift;
+\&
+\&      return $self\->{path};
+\&  }
+.Ve
+.PP
+A read-write accessor will allow the caller to set the value as well as
+get it:
+.PP
+.Vb 2
+\&  sub path {
+\&      my $self = shift;
+\&
+\&      if (@_) {
+\&          $self\->{path} = shift;
+\&      }
+\&
+\&      return $self\->{path};
+\&  }
+.Ve
+.SS "An Aside About Smarter and Safer Code"
+.IX Subsection "An Aside About Smarter and Safer Code"
+Our constructor and accessors are not very smart. They don't check that
+a \f(CW$path\fR is defined, nor do they check that a \f(CW$path\fR is a valid
+filesystem path.
+.PP
+Doing these checks by hand can quickly become tedious. Writing a bunch
+of accessors by hand is also incredibly tedious. There are a lot of
+modules on CPAN that can help you write safer and more concise code,
+including the modules we recommend in perlootut.
+.SS "Method Call Variations"
+.IX Xref "method"
+.IX Subsection "Method Call Variations"
+Perl supports several other ways to call methods besides the \f(CW\*(C`$object\->method()\*(C'\fR usage we've seen so far.
+.PP
+\fIMethod Names with a Fully Qualified Name\fR
+.IX Subsection "Method Names with a Fully Qualified Name"
+.PP
+Perl allows you to call methods using their fully qualified name (the
+package and method name):
+.PP
+.Vb 2
+\&  my $mp3 = File::MP3\->new( \*(AqRegin.mp3\*(Aq, $data );
+\&  $mp3\->File::save();
+.Ve
+.PP
+When you call a fully qualified method name like \f(CW\*(C`File::save\*(C'\fR, the method
+resolution search for the \f(CW\*(C`save\*(C'\fR method starts in the \f(CW\*(C`File\*(C'\fR class,
+skipping any \f(CW\*(C`save\*(C'\fR method the \f(CW\*(C`File::MP3\*(C'\fR class may have defined. It
+still searches the \f(CW\*(C`File\*(C'\fR class's parents if necessary.
+.PP
+While this feature is most commonly used to explicitly call methods
+inherited from an ancestor class, there is no technical restriction
+that enforces this:
+.PP
+.Vb 2
+\&  my $obj = Tree\->new();
+\&  $obj\->Dog::bark();
+.Ve
+.PP
+This calls the \f(CW\*(C`bark\*(C'\fR method from class \f(CW\*(C`Dog\*(C'\fR on an object of class
+\&\f(CW\*(C`Tree\*(C'\fR, even if the two classes are completely unrelated. Use this
+with great care.
+.PP
+The \f(CW\*(C`SUPER\*(C'\fR pseudo-class that was described earlier is \fInot\fR the same
+as calling a method with a fully-qualified name. See the earlier
+"Inheritance" section for details.
+.PP
+\fIMethod Names as Strings\fR
+.IX Subsection "Method Names as Strings"
+.PP
+Perl lets you use a scalar variable containing a string as a method
+name:
+.PP
+.Vb 1
+\&  my $file = File\->new( $path, $data );
+\&
+\&  my $method = \*(Aqsave\*(Aq;
+\&  $file\->$method();
+.Ve
+.PP
+This works exactly like calling \f(CW\*(C`$file\->save()\*(C'\fR. This can be very
+useful for writing dynamic code. For example, it allows you to pass a
+method name to be called as a parameter to another method.
+.PP
+\fIClass Names as Strings\fR
+.IX Subsection "Class Names as Strings"
+.PP
+Perl also lets you use a scalar containing a string as a class name:
+.PP
+.Vb 1
+\&  my $class = \*(AqFile\*(Aq;
+\&
+\&  my $file = $class\->new( $path, $data );
+.Ve
+.PP
+Again, this allows for very dynamic code.
+.PP
+\fISubroutine References as Methods\fR
+.IX Subsection "Subroutine References as Methods"
+.PP
+You can also use a subroutine reference as a method:
+.PP
+.Vb 2
+\&  my $sub = sub {
+\&      my $self = shift;
+\&
+\&      $self\->save();
+\&  };
+\&
+\&  $file\->$sub();
+.Ve
+.PP
+This is exactly equivalent to writing \f(CW$sub\->($file)\fR. You may see
+this idiom in the wild combined with a call to \f(CW\*(C`can\*(C'\fR:
+.PP
+.Vb 3
+\&  if ( my $meth = $object\->can(\*(Aqfoo\*(Aq) ) {
+\&      $object\->$meth();
+\&  }
+.Ve
+.PP
+\fIDereferencing Method Call\fR
+.IX Subsection "Dereferencing Method Call"
+.PP
+Perl also lets you use a dereferenced scalar reference in a method
+call. That's a mouthful, so let's look at some code:
+.PP
+.Vb 4
+\&  $file\->${ \e\*(Aqsave\*(Aq };
+\&  $file\->${ returns_scalar_ref() };
+\&  $file\->${ \e( returns_scalar() ) };
+\&  $file\->${ returns_ref_to_sub_ref() };
+.Ve
+.PP
+This works if the dereference produces a string \fIor\fR a subroutine
+reference.
+.PP
+\fIMethod Calls on Filehandles\fR
+.IX Subsection "Method Calls on Filehandles"
+.PP
+Under the hood, Perl filehandles are instances of the \f(CW\*(C`IO::Handle\*(C'\fR or
+\&\f(CW\*(C`IO::File\*(C'\fR class. Once you have an open filehandle, you can call
+methods on it. Additionally, you can call methods on the \f(CW\*(C`STDIN\*(C'\fR,
+\&\f(CW\*(C`STDOUT\*(C'\fR, and \f(CW\*(C`STDERR\*(C'\fR filehandles.
+.PP
+.Vb 3
+\&  open my $fh, \*(Aq>\*(Aq, \*(Aqpath/to/file\*(Aq;
+\&  $fh\->autoflush();
+\&  $fh\->print(\*(Aqcontent\*(Aq);
+\&
+\&  STDOUT\->autoflush();
+.Ve
+.SS "Invoking Class Methods"
+.IX Xref "invocation"
+.IX Subsection "Invoking Class Methods"
+Because Perl allows you to use barewords for package names and
+subroutine names, it sometimes interprets a bareword's meaning
+incorrectly. For example, the construct \f(CW\*(C`Class\->new()\*(C'\fR can be
+interpreted as either \f(CW\*(C`\*(AqClass\*(Aq\->new()\*(C'\fR or \f(CW\*(C`Class()\->new()\*(C'\fR.
+In English, that second interpretation reads as "call a subroutine
+named \fBClass()\fR, then call \fBnew()\fR as a method on the return value of
+\&\fBClass()\fR". If there is a subroutine named \f(CWClass()\fR in the current
+namespace, Perl will always interpret \f(CW\*(C`Class\->new()\*(C'\fR as the second
+alternative: a call to \f(CWnew()\fR on the object  returned by a call to
+\&\f(CWClass()\fR
+.PP
+You can force Perl to use the first interpretation (i.e. as a method
+call on the class named "Class") in two ways. First, you can append a
+\&\f(CW\*(C`::\*(C'\fR to the class name:
+.PP
+.Vb 1
+\&    Class::\->new()
+.Ve
+.PP
+Perl will always interpret this as a method call.
+.PP
+Alternatively, you can quote the class name:
+.PP
+.Vb 1
+\&    \*(AqClass\*(Aq\->new()
+.Ve
+.PP
+Of course, if the class name is in a scalar Perl will do the right
+thing as well:
+.PP
+.Vb 2
+\&    my $class = \*(AqClass\*(Aq;
+\&    $class\->new();
+.Ve
+.PP
+\fIIndirect Object Syntax\fR
+.IX Xref "indirect object"
+.IX Subsection "Indirect Object Syntax"
+.PP
+\&\fBOutside of the file handle case, use of this syntax is discouraged as
+it can confuse the Perl interpreter. See below for more details.\fR
+.PP
+Perl supports another method invocation syntax called "indirect object"
+notation. This syntax is called "indirect" because the method comes
+before the object it is being invoked on.
+.PP
+This syntax can be used with any class or object method:
+.PP
+.Vb 2
+\&    my $file = new File $path, $data;
+\&    save $file;
+.Ve
+.PP
+We recommend that you avoid this syntax, for several reasons.
+.PP
+First, it can be confusing to read. In the above example, it's not
+clear if \f(CW\*(C`save\*(C'\fR is a method provided by the \f(CW\*(C`File\*(C'\fR class or simply a
+subroutine that expects a file object as its first argument.
+.PP
+When used with class methods, the problem is even worse. Because Perl
+allows subroutine names to be written as barewords, Perl has to guess
+whether the bareword after the method is a class name or subroutine
+name. In other words, Perl can resolve the syntax as either \f(CW\*(C`File\->new( $path, $data )\*(C'\fR \fBor\fR \f(CW\*(C`new( File( $path, $data ) )\*(C'\fR.
+.PP
+To parse this code, Perl uses a heuristic based on what package names
+it has seen, what subroutines exist in the current package, what
+barewords it has previously seen, and other input. Needless to say,
+heuristics can produce very surprising results!
+.PP
+Older documentation (and some CPAN modules) encouraged this syntax,
+particularly for constructors, so you may still find it in the wild.
+However, we encourage you to avoid using it in new code.
+.PP
+You can force Perl to interpret the bareword as a class name by
+appending "::" to it, like we saw earlier:
+.PP
+.Vb 1
+\&  my $file = new File:: $path, $data;
+.Ve
+.PP
+Indirect object syntax is only available when the 
+\&\f(CW"indirect"\fR named feature is enabled.
+This is enabled by default, but can be disabled if requested.  This
+feature is present in older feature version bundles, but was removed
+from the \f(CW\*(C`:5.36\*(C'\fR bundle; so a \f(CW\*(C`use VERSION\*(C'\fR
+declaration of \f(CW\*(C`v5.36\*(C'\fR or above will also disable the feature.
+.PP
+.Vb 2
+\&    use v5.36;
+\&    # indirect object syntax is no longer available
+.Ve
+.ie n .SS """bless"", ""blessed"", and ""ref"""
+.el .SS "\f(CWbless\fP, \f(CWblessed\fP, and \f(CWref\fP"
+.IX Subsection "bless, blessed, and ref"
+As we saw earlier, an object is simply a data structure that has been
+blessed into a class via the \f(CW\*(C`bless\*(C'\fR function. The \f(CW\*(C`bless\*(C'\fR function
+can take either one or two arguments:
+.PP
+.Vb 2
+\&  my $object = bless {}, $class;
+\&  my $object = bless {};
+.Ve
+.PP
+In the first form, the anonymous hash is being blessed into the class
+in \f(CW$class\fR. In the second form, the anonymous hash is blessed into
+the current package.
+.PP
+The second form is strongly discouraged, because it breaks the ability
+of a subclass to reuse the parent's constructor, but you may still run
+across it in existing code.
+.PP
+If you want to know whether a particular scalar refers to an object,
+you can use the \f(CW\*(C`blessed\*(C'\fR function exported by Scalar::Util, which
+is shipped with the Perl core.
+.PP
+.Vb 1
+\&  use Scalar::Util \*(Aqblessed\*(Aq;
+\&
+\&  if ( defined blessed($thing) ) { ... }
+.Ve
+.PP
+If \f(CW$thing\fR refers to an object, then this function returns the name
+of the package the object has been blessed into. If \f(CW$thing\fR doesn't
+contain a reference to a blessed object, the \f(CW\*(C`blessed\*(C'\fR function
+returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+Note that \f(CWblessed($thing)\fR will also return false if \f(CW$thing\fR has
+been blessed into a class named "0". This is a possible, but quite
+pathological. Don't create a class named "0" unless you know what
+you're doing.
+.PP
+Similarly, Perl's built-in \f(CW\*(C`ref\*(C'\fR function treats a reference to a
+blessed object specially. If you call \f(CWref($thing)\fR and \f(CW$thing\fR
+holds a reference to an object, it will return the name of the class
+that the object has been blessed into.
+.PP
+If you simply want to check that a variable contains an object
+reference, we recommend that you use \f(CW\*(C`defined blessed($object)\*(C'\fR, since
+\&\f(CW\*(C`ref\*(C'\fR returns true values for all references, not just objects.
+.SS "The UNIVERSAL Class"
+.IX Xref "UNIVERSAL"
+.IX Subsection "The UNIVERSAL Class"
+All classes automatically inherit from the UNIVERSAL class, which is
+built-in to the Perl core. This class provides a number of methods, all
+of which can be called on either a class or an object. You can also
+choose to override some of these methods in your class. If you do so,
+we recommend that you follow the built-in semantics described below.
+.IP isa($class) 4
+.IX Xref "isa"
+.IX Item "isa($class)"
+The \f(CW\*(C`isa\*(C'\fR method returns \fItrue\fR if the object is a member of the
+class in \f(CW$class\fR, or a member of a subclass of \f(CW$class\fR.
+.Sp
+If you override this method, it should never throw an exception.
+.IP DOES($role) 4
+.IX Xref "DOES"
+.IX Item "DOES($role)"
+The \f(CW\*(C`DOES\*(C'\fR method returns \fItrue\fR if its object claims to perform the
+role \f(CW$role\fR. By default, this is equivalent to \f(CW\*(C`isa\*(C'\fR. This method is
+provided for use by object system extensions that implement roles, like
+\&\f(CW\*(C`Moose\*(C'\fR and \f(CW\*(C`Role::Tiny\*(C'\fR.
+.Sp
+You can also override \f(CW\*(C`DOES\*(C'\fR directly in your own classes. If you
+override this method, it should never throw an exception.
+.IP can($method) 4
+.IX Xref "can"
+.IX Item "can($method)"
+The \f(CW\*(C`can\*(C'\fR method checks to see if the class or object it was called on
+has a method named \f(CW$method\fR. This checks for the method in the class
+and all of its parents. If the method exists, then a reference to the
+subroutine is returned. If it does not then \f(CW\*(C`undef\*(C'\fR is returned.
+.Sp
+If your class responds to method calls via \f(CW\*(C`AUTOLOAD\*(C'\fR, you may want to
+overload \f(CW\*(C`can\*(C'\fR to return a subroutine reference for methods which your
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR method handles.
+.Sp
+If you override this method, it should never throw an exception.
+.IP VERSION($need) 4
+.IX Xref "VERSION"
+.IX Item "VERSION($need)"
+The \f(CW\*(C`VERSION\*(C'\fR method returns the version number of the class
+(package).
+.Sp
+If the \f(CW$need\fR argument is given then it will check that the current
+version (as defined by the \f(CW$VERSION\fR variable in the package) is greater
+than or equal to \f(CW$need\fR; it will die if this is not the case. This
+method is called automatically by the \f(CW\*(C`VERSION\*(C'\fR form of \f(CW\*(C`use\*(C'\fR.
+.Sp
+.Vb 3
+\&    use Package 1.2 qw(some imported subs);
+\&    # implies:
+\&    Package\->VERSION(1.2);
+.Ve
+.Sp
+We recommend that you use this method to access another package's
+version, rather than looking directly at \f(CW$Package::VERSION\fR. The
+package you are looking at could have overridden the \f(CW\*(C`VERSION\*(C'\fR method.
+.Sp
+We also recommend using this method to check whether a module has a
+sufficient version. The internal implementation uses the version
+module to make sure that different types of version numbers are
+compared correctly.
+.SS AUTOLOAD
+.IX Xref "AUTOLOAD"
+.IX Subsection "AUTOLOAD"
+If you call a method that doesn't exist in a class, Perl will throw an
+error. However, if that class or any of its parent classes defines an
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR method, that \f(CW\*(C`AUTOLOAD\*(C'\fR method is called instead.
+.PP
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR is called as a regular method, and the caller will not know
+the difference. Whatever value your \f(CW\*(C`AUTOLOAD\*(C'\fR method returns is
+returned to the caller.
+.PP
+The fully qualified method name that was called is available in the
+\&\f(CW$AUTOLOAD\fR package global for your class. Since this is a global, if
+you want to refer to do it without a package name prefix under \f(CWstrict
+\&\*(Aqvars\*(Aq\fR, you need to declare it.
+.PP
+.Vb 5
+\&  # XXX \- this is a terrible way to implement accessors, but it makes
+\&  # for a simple example.
+\&  our $AUTOLOAD;
+\&  sub AUTOLOAD {
+\&      my $self = shift;
+\&
+\&      # Remove qualifier from original method name...
+\&      my $called =  $AUTOLOAD =~ s/.*:://r;
+\&
+\&      # Is there an attribute of that name?
+\&      die "No such attribute: $called"
+\&          unless exists $self\->{$called};
+\&
+\&      # If so, return it...
+\&      return $self\->{$called};
+\&  }
+\&
+\&  sub DESTROY { } # see below
+.Ve
+.PP
+Without the \f(CW\*(C`our $AUTOLOAD\*(C'\fR declaration, this code will not compile
+under the strict pragma.
+.PP
+As the comment says, this is not a good way to implement accessors.
+It's slow and too clever by far. However, you may see this as a way to
+provide accessors in older Perl code. See perlootut for
+recommendations on OO coding in Perl.
+.PP
+If your class does have an \f(CW\*(C`AUTOLOAD\*(C'\fR method, we strongly recommend
+that you override \f(CW\*(C`can\*(C'\fR in your class as well. Your overridden \f(CW\*(C`can\*(C'\fR
+method should return a subroutine reference for any method that your
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR responds to.
+.SS Destructors
+.IX Xref "destructor DESTROY"
+.IX Subsection "Destructors"
+When the last reference to an object goes away, the object is
+destroyed. If you only have one reference to an object stored in a
+lexical scalar, the object is destroyed when that scalar goes out of
+scope. If you store the object in a package global, that object may not
+go out of scope until the program exits.
+.PP
+If you want to do something when the object is destroyed, you can
+define a \f(CW\*(C`DESTROY\*(C'\fR method in your class. This method will always be
+called by Perl at the appropriate time, unless the method is empty.
+.PP
+This is called just like any other method, with the object as the first
+argument. It does not receive any additional arguments. However, the
+\&\f(CW$_[0]\fR variable will be read-only in the destructor, so you cannot
+assign a value to it.
+.PP
+If your \f(CW\*(C`DESTROY\*(C'\fR method throws an exception, this will not cause
+any control transfer beyond exiting the method.  The exception will be
+reported to \f(CW\*(C`STDERR\*(C'\fR as a warning, marked "(in cleanup)", and Perl will
+continue with whatever it was doing before.
+.PP
+Because \f(CW\*(C`DESTROY\*(C'\fR methods can be called at any time, you should localize
+any global status variables that might be set by anything you do in
+your \f(CW\*(C`DESTROY\*(C'\fR method.  If you are in doubt about a particular status
+variable, it doesn't hurt to localize it.  There are five global status
+variables, and the safest way is to localize all five of them:
+.PP
+.Vb 5
+\&  sub DESTROY {
+\&      local($., $@, $!, $^E, $?);
+\&      my $self = shift;
+\&      ...;
+\&  }
+.Ve
+.PP
+If you define an \f(CW\*(C`AUTOLOAD\*(C'\fR in your class, then Perl will call your
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR to handle the \f(CW\*(C`DESTROY\*(C'\fR method. You can prevent this by
+defining an empty \f(CW\*(C`DESTROY\*(C'\fR, like we did in the autoloading example.
+You can also check the value of \f(CW$AUTOLOAD\fR and return without doing
+anything when called to handle \f(CW\*(C`DESTROY\*(C'\fR.
+.PP
+\fIGlobal Destruction\fR
+.IX Subsection "Global Destruction"
+.PP
+The order in which objects are destroyed during the global destruction
+before the program exits is unpredictable. This means that any objects
+contained by your object may already have been destroyed. You should
+check that a contained object is defined before calling a method on it:
+.PP
+.Vb 2
+\&  sub DESTROY {
+\&      my $self = shift;
+\&
+\&      $self\->{handle}\->close() if $self\->{handle};
+\&  }
+.Ve
+.PP
+You can use the \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable to detect if you are
+currently in the global destruction phase:
+.PP
+.Vb 2
+\&  sub DESTROY {
+\&      my $self = shift;
+\&
+\&      return if ${^GLOBAL_PHASE} eq \*(AqDESTRUCT\*(Aq;
+\&
+\&      $self\->{handle}\->close();
+\&  }
+.Ve
+.PP
+Note that this variable was added in Perl 5.14.0. If you want to detect
+the global destruction phase on older versions of Perl, you can use the
+\&\f(CW\*(C`Devel::GlobalDestruction\*(C'\fR module on CPAN.
+.PP
+If your \f(CW\*(C`DESTROY\*(C'\fR method issues a warning during global destruction,
+the Perl interpreter will append the string " during global
+destruction" to the warning.
+.PP
+During global destruction, Perl will always garbage collect objects
+before unblessed references. See "PERL_DESTRUCT_LEVEL" in perlhacktips
+for more information about global destruction.
+.SS "Non-Hash Objects"
+.IX Subsection "Non-Hash Objects"
+All the examples so far have shown objects based on a blessed hash.
+However, it's possible to bless any type of data structure or referent,
+including scalars, globs, and subroutines. You may see this sort of
+thing when looking at code in the wild.
+.PP
+Here's an example of a module as a blessed scalar:
+.PP
+.Vb 1
+\&  package Time;
+\&
+\&  use v5.36;
+\&
+\&  sub new {
+\&      my $class = shift;
+\&
+\&      my $time = time;
+\&      return bless \e$time, $class;
+\&  }
+\&
+\&  sub epoch {
+\&      my $self = shift;
+\&      return $$self;
+\&  }
+\&
+\&  my $time = Time\->new();
+\&  print $time\->epoch();
+.Ve
+.SS "Inside-Out objects"
+.IX Subsection "Inside-Out objects"
+In the past, the Perl community experimented with a technique called
+"inside-out objects". An inside-out object stores its data outside of
+the object's reference, indexed on a unique property of the object,
+such as its memory address, rather than in the object itself. This has
+the advantage of enforcing the encapsulation of object attributes,
+since their data is not stored in the object itself.
+.PP
+This technique was popular for a while (and was recommended in Damian
+Conway's \fIPerl Best Practices\fR), but never achieved universal
+adoption. The Object::InsideOut module on CPAN provides a
+comprehensive implementation of this technique, and you may see it or
+other inside-out modules in the wild.
+.PP
+Here is a simple example of the technique, using the
+Hash::Util::FieldHash core module. This module was added to the core
+to support inside-out object implementations.
+.PP
+.Vb 1
+\&  package Time;
+\&
+\&  use v5.36;
+\&
+\&  use Hash::Util::FieldHash \*(Aqfieldhash\*(Aq;
+\&
+\&  fieldhash my %time_for;
+\&
+\&  sub new {
+\&      my $class = shift;
+\&
+\&      my $self = bless \e( my $object ), $class;
+\&
+\&      $time_for{$self} = time;
+\&
+\&      return $self;
+\&  }
+\&
+\&  sub epoch {
+\&      my $self = shift;
+\&
+\&      return $time_for{$self};
+\&  }
+\&
+\&  my $time = Time\->new;
+\&  print $time\->epoch;
+.Ve
+.SS Pseudo-hashes
+.IX Subsection "Pseudo-hashes"
+The pseudo-hash feature was an experimental feature introduced in
+earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
+array reference which can be accessed using named keys like a hash. You
+may run in to some code in the wild which uses it. See the fields
+pragma for more information.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+A kinder, gentler tutorial on object-oriented programming in Perl can
+be found in perlootut. You should also check out perlmodlib for
+some style guides on constructing both modules and classes.
diff --git a/upstream/mageia-cauldron/man1/perlootut.1 b/upstream/mageia-cauldron/man1/perlootut.1
new file mode 100644
index 00000000..4f8fb0e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlootut.1
@@ -0,0 +1,785 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOOTUT 1"
+.TH PERLOOTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlootut \- Object\-Oriented Programming in Perl Tutorial
+.SH DATE
+.IX Header "DATE"
+This document was created in February, 2011, and the last major
+revision was in February, 2013.
+.PP
+If you are reading this in the future then it's possible that the state
+of the art has changed. We recommend you start by reading the perlootut
+document in the latest stable release of Perl, rather than this
+version.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides an introduction to object-oriented programming
+in Perl. It begins with a brief overview of the concepts behind object
+oriented design. Then it introduces several different OO systems from
+CPAN <https://www.cpan.org> which build on top of what Perl
+provides.
+.PP
+By default, Perl's built-in OO system is very minimal, leaving you to
+do most of the work. This minimalism made a lot of sense in 1994, but
+in the years since Perl 5.0 we've seen a number of common patterns
+emerge in Perl OO. Fortunately, Perl's flexibility has allowed a rich
+ecosystem of Perl OO systems to flourish.
+.PP
+If you want to know how Perl OO works under the hood, the perlobj
+document explains the nitty gritty details.
+.PP
+This document assumes that you already understand the basics of Perl
+syntax, variable types, operators, and subroutine calls. If you don't
+understand these concepts yet, please read perlintro first. You
+should also read the perlsyn, perlop, and perlsub documents.
+.SH "OBJECT-ORIENTED FUNDAMENTALS"
+.IX Header "OBJECT-ORIENTED FUNDAMENTALS"
+Most object systems share a number of common concepts. You've probably
+heard terms like "class", "object, "method", and "attribute" before.
+Understanding the concepts will make it much easier to read and write
+object-oriented code. If you're already familiar with these terms, you
+should still skim this section, since it explains each concept in terms
+of Perl's OO implementation.
+.PP
+Perl's OO system is class-based. Class-based OO is fairly common. It's
+used by Java, C++, C#, Python, Ruby, and many other languages. There
+are other object orientation paradigms as well. JavaScript is the most
+popular language to use another paradigm. JavaScript's OO system is
+prototype-based.
+.SS Object
+.IX Subsection "Object"
+An \fBobject\fR is a data structure that bundles together data and
+subroutines which operate on that data. An object's data is called
+\&\fBattributes\fR, and its subroutines are called \fBmethods\fR. An object can
+be thought of as a noun (a person, a web service, a computer).
+.PP
+An object represents a single discrete thing. For example, an object
+might represent a file. The attributes for a file object might include
+its path, content, and last modification time. If we created an object
+to represent \fI/etc/hostname\fR on a machine named "foo.example.com",
+that object's path would be "/etc/hostname", its content would be
+"foo\en", and it's last modification time would be 1304974868 seconds
+since the beginning of the epoch.
+.PP
+The methods associated with a file might include \f(CWrename()\fR and
+\&\f(CWwrite()\fR.
+.PP
+In Perl most objects are hashes, but the OO systems we recommend keep
+you from having to worry about this. In practice, it's best to consider
+an object's internal data structure opaque.
+.SS Class
+.IX Subsection "Class"
+A \fBclass\fR defines the behavior of a category of objects. A class is a
+name for a category (like "File"), and a class also defines the
+behavior of objects in that category.
+.PP
+All objects belong to a specific class. For example, our
+\&\fI/etc/hostname\fR object belongs to the \f(CW\*(C`File\*(C'\fR class. When we want to
+create a specific object, we start with its class, and \fBconstruct\fR or
+\&\fBinstantiate\fR an object. A specific object is often referred to as an
+\&\fBinstance\fR of a class.
+.PP
+In Perl, any package can be a class. The difference between a package
+which is a class and one which isn't is based on how the package is
+used. Here's our "class declaration" for the \f(CW\*(C`File\*(C'\fR class:
+.PP
+.Vb 1
+\&  package File;
+.Ve
+.PP
+In Perl, there is no special keyword for constructing an object.
+However, most OO modules on CPAN use a method named \f(CWnew()\fR to
+construct a new object:
+.PP
+.Vb 5
+\&  my $hostname = File\->new(
+\&      path          => \*(Aq/etc/hostname\*(Aq,
+\&      content       => "foo\en",
+\&      last_mod_time => 1304974868,
+\&  );
+.Ve
+.PP
+(Don't worry about that \f(CW\*(C`\->\*(C'\fR operator, it will be explained
+later.)
+.PP
+\fIBlessing\fR
+.IX Subsection "Blessing"
+.PP
+As we said earlier, most Perl objects are hashes, but an object can be
+an instance of any Perl data type (scalar, array, etc.). Turning a
+plain data structure into an object is done by \fBblessing\fR that data
+structure using Perl's \f(CW\*(C`bless\*(C'\fR function.
+.PP
+While we strongly suggest you don't build your objects from scratch,
+you should know the term \fBbless\fR. A \fBblessed\fR data structure (aka "a
+referent") is an object. We sometimes say that an object has been
+"blessed into a class".
+.PP
+Once a referent has been blessed, the \f(CW\*(C`blessed\*(C'\fR function from the
+Scalar::Util core module can tell us its class name. This subroutine
+returns an object's class when passed an object, and false otherwise.
+.PP
+.Vb 1
+\&  use Scalar::Util \*(Aqblessed\*(Aq;
+\&
+\&  print blessed($hash);      # undef
+\&  print blessed($hostname);  # File
+.Ve
+.PP
+\fIConstructor\fR
+.IX Subsection "Constructor"
+.PP
+A \fBconstructor\fR creates a new object. In Perl, a class's constructor
+is just another method, unlike some other languages, which provide
+syntax for constructors. Most Perl classes use \f(CW\*(C`new\*(C'\fR as the name for
+their constructor:
+.PP
+.Vb 1
+\&  my $file = File\->new(...);
+.Ve
+.SS Methods
+.IX Subsection "Methods"
+You already learned that a \fBmethod\fR is a subroutine that operates on
+an object. You can think of a method as the things that an object can
+\&\fIdo\fR. If an object is a noun, then methods are its verbs (save, print,
+open).
+.PP
+In Perl, methods are simply subroutines that live in a class's package.
+Methods are always written to receive the object as their first
+argument:
+.PP
+.Vb 2
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      print "This file is at ", $self\->path, "\en";
+\&  }
+\&
+\&  $file\->print_info;
+\&  # The file is at /etc/hostname
+.Ve
+.PP
+What makes a method special is \fIhow it's called\fR. The arrow operator
+(\f(CW\*(C`\->\*(C'\fR) tells Perl that we are calling a method.
+.PP
+When we make a method call, Perl arranges for the method's \fBinvocant\fR
+to be passed as the first argument. \fBInvocant\fR is a fancy name for the
+thing on the left side of the arrow. The invocant can either be a class
+name or an object. We can also pass additional arguments to the method:
+.PP
+.Vb 3
+\&  sub print_info {
+\&      my $self   = shift;
+\&      my $prefix = shift // "This file is at ";
+\&
+\&      print $prefix, ", ", $self\->path, "\en";
+\&  }
+\&
+\&  $file\->print_info("The file is located at ");
+\&  # The file is located at /etc/hostname
+.Ve
+.SS Attributes
+.IX Subsection "Attributes"
+Each class can define its \fBattributes\fR. When we instantiate an object,
+we assign values to those attributes. For example, every \f(CW\*(C`File\*(C'\fR object
+has a path. Attributes are sometimes called \fBproperties\fR.
+.PP
+Perl has no special syntax for attributes. Under the hood, attributes
+are often stored as keys in the object's underlying hash, but don't
+worry about this.
+.PP
+We recommend that you only access attributes via \fBaccessor\fR methods.
+These are methods that can get or set the value of each attribute. We
+saw this earlier in the \f(CWprint_info()\fR example, which calls \f(CW\*(C`$self\->path\*(C'\fR.
+.PP
+You might also see the terms \fBgetter\fR and \fBsetter\fR. These are two
+types of accessors. A getter gets the attribute's value, while a setter
+sets it. Another term for a setter is \fBmutator\fR
+.PP
+Attributes are typically defined as read-only or read-write. Read-only
+attributes can only be set when the object is first created, while
+read-write attributes can be altered at any time.
+.PP
+The value of an attribute may itself be another object. For example,
+instead of returning its last mod time as a number, the \f(CW\*(C`File\*(C'\fR class
+could return a DateTime object representing that value.
+.PP
+It's possible to have a class that does not expose any publicly
+settable attributes. Not every class has attributes and methods.
+.SS Polymorphism
+.IX Subsection "Polymorphism"
+\&\fBPolymorphism\fR is a fancy way of saying that objects from two
+different classes share an API. For example, we could have \f(CW\*(C`File\*(C'\fR and
+\&\f(CW\*(C`WebPage\*(C'\fR classes which both have a \f(CWprint_content()\fR method. This
+method might produce different output for each class, but they share a
+common interface.
+.PP
+While the two classes may differ in many ways, when it comes to the
+\&\f(CWprint_content()\fR method, they are the same. This means that we can
+try to call the \f(CWprint_content()\fR method on an object of either class,
+and \fBwe don't have to know what class the object belongs to!\fR
+.PP
+Polymorphism is one of the key concepts of object-oriented design.
+.SS Inheritance
+.IX Subsection "Inheritance"
+\&\fBInheritance\fR lets you create a specialized version of an existing
+class. Inheritance lets the new class reuse the methods and attributes
+of another class.
+.PP
+For example, we could create an \f(CW\*(C`File::MP3\*(C'\fR class which \fBinherits\fR
+from \f(CW\*(C`File\*(C'\fR. An \f(CW\*(C`File::MP3\*(C'\fR \fBis-a\fR \fImore specific\fR type of \f(CW\*(C`File\*(C'\fR.
+All mp3 files are files, but not all files are mp3 files.
+.PP
+We often refer to inheritance relationships as \fBparent-child\fR or
+\&\f(CW\*(C`superclass\*(C'\fR/\f(CW\*(C`subclass\*(C'\fR relationships. Sometimes we say that the
+child has an \fBis-a\fR relationship with its parent class.
+.PP
+\&\f(CW\*(C`File\*(C'\fR is a \fBsuperclass\fR of \f(CW\*(C`File::MP3\*(C'\fR, and \f(CW\*(C`File::MP3\*(C'\fR is a
+\&\fBsubclass\fR of \f(CW\*(C`File\*(C'\fR.
+.PP
+.Vb 1
+\&  package File::MP3;
+\&
+\&  use parent \*(AqFile\*(Aq;
+.Ve
+.PP
+The parent module is one of several ways that Perl lets you define
+inheritance relationships.
+.PP
+Perl allows multiple inheritance, which means that a class can inherit
+from multiple parents. While this is possible, we strongly recommend
+against it. Generally, you can use \fBroles\fR to do everything you can do
+with multiple inheritance, but in a cleaner way.
+.PP
+Note that there's nothing wrong with defining multiple subclasses of a
+given class. This is both common and safe. For example, we might define
+\&\f(CW\*(C`File::MP3::FixedBitrate\*(C'\fR and \f(CW\*(C`File::MP3::VariableBitrate\*(C'\fR classes to
+distinguish between different types of mp3 file.
+.PP
+\fIOverriding methods and method resolution\fR
+.IX Subsection "Overriding methods and method resolution"
+.PP
+Inheritance allows two classes to share code. By default, every method
+in the parent class is also available in the child. The child can
+explicitly \fBoverride\fR a parent's method to provide its own
+implementation. For example, if we have an \f(CW\*(C`File::MP3\*(C'\fR object, it has
+the \f(CWprint_info()\fR method from \f(CW\*(C`File\*(C'\fR:
+.PP
+.Vb 6
+\&  my $cage = File::MP3\->new(
+\&      path          => \*(Aqmp3s/My\-Body\-Is\-a\-Cage.mp3\*(Aq,
+\&      content       => $mp3_data,
+\&      last_mod_time => 1304974868,
+\&      title         => \*(AqMy Body Is a Cage\*(Aq,
+\&  );
+\&
+\&  $cage\->print_info;
+\&  # The file is at mp3s/My\-Body\-Is\-a\-Cage.mp3
+.Ve
+.PP
+If we wanted to include the mp3's title in the greeting, we could
+override the method:
+.PP
+.Vb 1
+\&  package File::MP3;
+\&
+\&  use parent \*(AqFile\*(Aq;
+\&
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      print "This file is at ", $self\->path, "\en";
+\&      print "Its title is ", $self\->title, "\en";
+\&  }
+\&
+\&  $cage\->print_info;
+\&  # The file is at mp3s/My\-Body\-Is\-a\-Cage.mp3
+\&  # Its title is My Body Is a Cage
+.Ve
+.PP
+The process of determining what method should be used is called
+\&\fBmethod resolution\fR. What Perl does is look at the object's class
+first (\f(CW\*(C`File::MP3\*(C'\fR in this case). If that class defines the method,
+then that class's version of the method is called. If not, Perl looks
+at each parent class in turn. For \f(CW\*(C`File::MP3\*(C'\fR, its only parent is
+\&\f(CW\*(C`File\*(C'\fR. If \f(CW\*(C`File::MP3\*(C'\fR does not define the method, but \f(CW\*(C`File\*(C'\fR does,
+then Perl calls the method in \f(CW\*(C`File\*(C'\fR.
+.PP
+If \f(CW\*(C`File\*(C'\fR inherited from \f(CW\*(C`DataSource\*(C'\fR, which inherited from \f(CW\*(C`Thing\*(C'\fR,
+then Perl would keep looking "up the chain" if necessary.
+.PP
+It is possible to explicitly call a parent method from a child:
+.PP
+.Vb 1
+\&  package File::MP3;
+\&
+\&  use parent \*(AqFile\*(Aq;
+\&
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      $self\->SUPER::print_info();
+\&      print "Its title is ", $self\->title, "\en";
+\&  }
+.Ve
+.PP
+The \f(CW\*(C`SUPER::\*(C'\fR bit tells Perl to look for the \f(CWprint_info()\fR in the
+\&\f(CW\*(C`File::MP3\*(C'\fR class's inheritance chain. When it finds the parent class
+that implements this method, the method is called.
+.PP
+We mentioned multiple inheritance earlier. The main problem with
+multiple inheritance is that it greatly complicates method resolution.
+See perlobj for more details.
+.SS Encapsulation
+.IX Subsection "Encapsulation"
+\&\fBEncapsulation\fR is the idea that an object is opaque. When another
+developer uses your class, they don't need to know \fIhow\fR it is
+implemented, they just need to know \fIwhat\fR it does.
+.PP
+Encapsulation is important for several reasons. First, it allows you to
+separate the public API from the private implementation. This means you
+can change that implementation without breaking the API.
+.PP
+Second, when classes are well encapsulated, they become easier to
+subclass. Ideally, a subclass uses the same APIs to access object data
+that its parent class uses. In reality, subclassing sometimes involves
+violating encapsulation, but a good API can minimize the need to do
+this.
+.PP
+We mentioned earlier that most Perl objects are implemented as hashes
+under the hood. The principle of encapsulation tells us that we should
+not rely on this. Instead, we should use accessor methods to access the
+data in that hash. The object systems that we recommend below all
+automate the generation of accessor methods. If you use one of them,
+you should never have to access the object as a hash directly.
+.SS Composition
+.IX Subsection "Composition"
+In object-oriented code, we often find that one object references
+another object. This is called \fBcomposition\fR, or a \fBhas-a\fR
+relationship.
+.PP
+Earlier, we mentioned that the \f(CW\*(C`File\*(C'\fR class's \f(CW\*(C`last_mod_time\*(C'\fR
+accessor could return a DateTime object. This is a perfect example
+of composition. We could go even further, and make the \f(CW\*(C`path\*(C'\fR and
+\&\f(CW\*(C`content\*(C'\fR accessors return objects as well. The \f(CW\*(C`File\*(C'\fR class would
+then be \fBcomposed\fR of several other objects.
+.SS Roles
+.IX Subsection "Roles"
+\&\fBRoles\fR are something that a class \fIdoes\fR, rather than something that
+it \fIis\fR. Roles are relatively new to Perl, but have become rather
+popular. Roles are \fBapplied\fR to classes. Sometimes we say that classes
+\&\fBconsume\fR roles.
+.PP
+Roles are an alternative to inheritance for providing polymorphism.
+Let's assume we have two classes, \f(CW\*(C`Radio\*(C'\fR and \f(CW\*(C`Computer\*(C'\fR. Both of
+these things have on/off switches. We want to model that in our class
+definitions.
+.PP
+We could have both classes inherit from a common parent, like
+\&\f(CW\*(C`Machine\*(C'\fR, but not all machines have on/off switches. We could create
+a parent class called \f(CW\*(C`HasOnOffSwitch\*(C'\fR, but that is very artificial.
+Radios and computers are not specializations of this parent. This
+parent is really a rather ridiculous creation.
+.PP
+This is where roles come in. It makes a lot of sense to create a
+\&\f(CW\*(C`HasOnOffSwitch\*(C'\fR role and apply it to both classes. This role would
+define a known API like providing \f(CWturn_on()\fR and \f(CWturn_off()\fR
+methods.
+.PP
+Perl does not have any built-in way to express roles. In the past,
+people just bit the bullet and used multiple inheritance. Nowadays,
+there are several good choices on CPAN for using roles.
+.SS "When to Use OO"
+.IX Subsection "When to Use OO"
+Object Orientation is not the best solution to every problem. In \fIPerl
+Best Practices\fR (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is
+the right fit for your problem:
+.IP \(bu 4
+The system being designed is large, or is likely to become large.
+.IP \(bu 4
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
+.IP \(bu 4
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
+.IP \(bu 4
+You have a piece of data on which many different operations are
+applied.
+.IP \(bu 4
+You need to perform the same general operations on related types of
+data, but with slight variations depending on the specific type of data
+the operations are applied to.
+.IP \(bu 4
+It's likely you'll have to add new data types later.
+.IP \(bu 4
+The typical interactions between pieces of data are best represented by
+operators.
+.IP \(bu 4
+The implementation of individual components of the system is likely to
+change over time.
+.IP \(bu 4
+The system design is already object-oriented.
+.IP \(bu 4
+Large numbers of other programmers will be using your code modules.
+.SH "PERL OO SYSTEMS"
+.IX Header "PERL OO SYSTEMS"
+As we mentioned before, Perl's built-in OO system is very minimal, but
+also quite flexible. Over the years, many people have developed systems
+which build on top of Perl's built-in system to provide more features
+and convenience.
+.PP
+We strongly recommend that you use one of these systems. Even the most
+minimal of them eliminates a lot of repetitive boilerplate. There's
+really no good reason to write your classes from scratch in Perl.
+.PP
+If you are interested in the guts underlying these systems, check out
+perlobj.
+.SS Moose
+.IX Subsection "Moose"
+Moose bills itself as a "postmodern object system for Perl 5". Don't
+be scared, the "postmodern" label is a callback to Larry's description
+of Perl as "the first postmodern computer language".
+.PP
+\&\f(CW\*(C`Moose\*(C'\fR provides a complete, modern OO system. Its biggest influence
+is the Common Lisp Object System, but it also borrows ideas from
+Smalltalk and several other languages. \f(CW\*(C`Moose\*(C'\fR was created by Stevan
+Little, and draws heavily from his work on the Raku OO design.
+.PP
+Here is our \f(CW\*(C`File\*(C'\fR class using \f(CW\*(C`Moose\*(C'\fR:
+.PP
+.Vb 2
+\&  package File;
+\&  use Moose;
+\&
+\&  has path          => ( is => \*(Aqro\*(Aq );
+\&  has content       => ( is => \*(Aqro\*(Aq );
+\&  has last_mod_time => ( is => \*(Aqro\*(Aq );
+\&
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      print "This file is at ", $self\->path, "\en";
+\&  }
+.Ve
+.PP
+\&\f(CW\*(C`Moose\*(C'\fR provides a number of features:
+.IP \(bu 4
+Declarative sugar
+.Sp
+\&\f(CW\*(C`Moose\*(C'\fR provides a layer of declarative "sugar" for defining classes.
+That sugar is just a set of exported functions that make declaring how
+your class works simpler and more palatable.  This lets you describe
+\&\fIwhat\fR your class is, rather than having to tell Perl \fIhow\fR to
+implement your class.
+.Sp
+The \f(CWhas()\fR subroutine declares an attribute, and \f(CW\*(C`Moose\*(C'\fR
+automatically creates accessors for these attributes. It also takes
+care of creating a \f(CWnew()\fR method for you. This constructor knows
+about the attributes you declared, so you can set them when creating a
+new \f(CW\*(C`File\*(C'\fR.
+.IP \(bu 4
+Roles built-in
+.Sp
+\&\f(CW\*(C`Moose\*(C'\fR lets you define roles the same way you define classes:
+.Sp
+.Vb 2
+\&  package HasOnOffSwitch;
+\&  use Moose::Role;
+\&
+\&  has is_on => (
+\&      is  => \*(Aqrw\*(Aq,
+\&      isa => \*(AqBool\*(Aq,
+\&  );
+\&
+\&  sub turn_on {
+\&      my $self = shift;
+\&      $self\->is_on(1);
+\&  }
+\&
+\&  sub turn_off {
+\&      my $self = shift;
+\&      $self\->is_on(0);
+\&  }
+.Ve
+.IP \(bu 4
+A miniature type system
+.Sp
+In the example above, you can see that we passed \f(CW\*(C`isa => \*(AqBool\*(Aq\*(C'\fR
+to \f(CWhas()\fR when creating our \f(CW\*(C`is_on\*(C'\fR attribute. This tells \f(CW\*(C`Moose\*(C'\fR
+that this attribute must be a boolean value. If we try to set it to an
+invalid value, our code will throw an error.
+.IP \(bu 4
+Full introspection and manipulation
+.Sp
+Perl's built-in introspection features are fairly minimal. \f(CW\*(C`Moose\*(C'\fR
+builds on top of them and creates a full introspection layer for your
+classes. This lets you ask questions like "what methods does the File
+class implement?" It also lets you modify your classes
+programmatically.
+.IP \(bu 4
+Self-hosted and extensible
+.Sp
+\&\f(CW\*(C`Moose\*(C'\fR describes itself using its own introspection API. Besides
+being a cool trick, this means that you can extend \f(CW\*(C`Moose\*(C'\fR using
+\&\f(CW\*(C`Moose\*(C'\fR itself.
+.IP \(bu 4
+Rich ecosystem
+.Sp
+There is a rich ecosystem of \f(CW\*(C`Moose\*(C'\fR extensions on CPAN under the
+MooseX <https://metacpan.org/search?q=MooseX>
+namespace. In addition, many modules on CPAN already use \f(CW\*(C`Moose\*(C'\fR,
+providing you with lots of examples to learn from.
+.IP \(bu 4
+Many more features
+.Sp
+\&\f(CW\*(C`Moose\*(C'\fR is a very powerful tool, and we can't cover all of its
+features here. We encourage you to learn more by reading the \f(CW\*(C`Moose\*(C'\fR
+documentation, starting with
+Moose::Manual <https://metacpan.org/pod/Moose::Manual>.
+.PP
+Of course, \f(CW\*(C`Moose\*(C'\fR isn't perfect.
+.PP
+\&\f(CW\*(C`Moose\*(C'\fR can make your code slower to load. \f(CW\*(C`Moose\*(C'\fR itself is not
+small, and it does a \fIlot\fR of code generation when you define your
+class. This code generation means that your runtime code is as fast as
+it can be, but you pay for this when your modules are first loaded.
+.PP
+This load time hit can be a problem when startup speed is important,
+such as with a command-line script or a "plain vanilla" CGI script that
+must be loaded each time it is executed.
+.PP
+Before you panic, know that many people do use \f(CW\*(C`Moose\*(C'\fR for
+command-line tools and other startup-sensitive code. We encourage you
+to try \f(CW\*(C`Moose\*(C'\fR out first before worrying about startup speed.
+.PP
+\&\f(CW\*(C`Moose\*(C'\fR also has several dependencies on other modules. Most of these
+are small stand-alone modules, a number of which have been spun off
+from \f(CW\*(C`Moose\*(C'\fR. \f(CW\*(C`Moose\*(C'\fR itself, and some of its dependencies, require a
+compiler. If you need to install your software on a system without a
+compiler, or if having \fIany\fR dependencies is a problem, then \f(CW\*(C`Moose\*(C'\fR
+may not be right for you.
+.PP
+\fIMoo\fR
+.IX Subsection "Moo"
+.PP
+If you try \f(CW\*(C`Moose\*(C'\fR and find that one of these issues is preventing you
+from using \f(CW\*(C`Moose\*(C'\fR, we encourage you to consider Moo next. \f(CW\*(C`Moo\*(C'\fR
+implements a subset of \f(CW\*(C`Moose\*(C'\fR's functionality in a simpler package.
+For most features that it does implement, the end-user API is
+\&\fIidentical\fR to \f(CW\*(C`Moose\*(C'\fR, meaning you can switch from \f(CW\*(C`Moo\*(C'\fR to
+\&\f(CW\*(C`Moose\*(C'\fR quite easily.
+.PP
+\&\f(CW\*(C`Moo\*(C'\fR does not implement most of \f(CW\*(C`Moose\*(C'\fR's introspection API, so it's
+often faster when loading your modules. Additionally, none of its
+dependencies require XS, so it can be installed on machines without a
+compiler.
+.PP
+One of \f(CW\*(C`Moo\*(C'\fR's most compelling features is its interoperability with
+\&\f(CW\*(C`Moose\*(C'\fR. When someone tries to use \f(CW\*(C`Moose\*(C'\fR's introspection API on a
+\&\f(CW\*(C`Moo\*(C'\fR class or role, it is transparently inflated into a \f(CW\*(C`Moose\*(C'\fR
+class or role. This makes it easier to incorporate \f(CW\*(C`Moo\*(C'\fR\-using code
+into a \f(CW\*(C`Moose\*(C'\fR code base and vice versa.
+.PP
+For example, a \f(CW\*(C`Moose\*(C'\fR class can subclass a \f(CW\*(C`Moo\*(C'\fR class using
+\&\f(CW\*(C`extends\*(C'\fR or consume a \f(CW\*(C`Moo\*(C'\fR role using \f(CW\*(C`with\*(C'\fR.
+.PP
+The \f(CW\*(C`Moose\*(C'\fR authors hope that one day \f(CW\*(C`Moo\*(C'\fR can be made obsolete by
+improving \f(CW\*(C`Moose\*(C'\fR enough, but for now it provides a worthwhile
+alternative to \f(CW\*(C`Moose\*(C'\fR.
+.SS Class::Accessor
+.IX Subsection "Class::Accessor"
+Class::Accessor is the polar opposite of \f(CW\*(C`Moose\*(C'\fR. It provides very
+few features, nor is it self-hosting.
+.PP
+It is, however, very simple, pure Perl, and it has no non-core
+dependencies. It also provides a "Moose-like" API on demand for the
+features it supports.
+.PP
+Even though it doesn't do much, it is still preferable to writing your
+own classes from scratch.
+.PP
+Here's our \f(CW\*(C`File\*(C'\fR class with \f(CW\*(C`Class::Accessor\*(C'\fR:
+.PP
+.Vb 2
+\&  package File;
+\&  use Class::Accessor \*(Aqantlers\*(Aq;
+\&
+\&  has path          => ( is => \*(Aqro\*(Aq );
+\&  has content       => ( is => \*(Aqro\*(Aq );
+\&  has last_mod_time => ( is => \*(Aqro\*(Aq );
+\&
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      print "This file is at ", $self\->path, "\en";
+\&  }
+.Ve
+.PP
+The \f(CW\*(C`antlers\*(C'\fR import flag tells \f(CW\*(C`Class::Accessor\*(C'\fR that you want to
+define your attributes using \f(CW\*(C`Moose\*(C'\fR\-like syntax. The only parameter
+that you can pass to \f(CW\*(C`has\*(C'\fR is \f(CW\*(C`is\*(C'\fR. We recommend that you use this
+Moose-like syntax if you choose \f(CW\*(C`Class::Accessor\*(C'\fR since it means you
+will have a smoother upgrade path if you later decide to move to
+\&\f(CW\*(C`Moose\*(C'\fR.
+.PP
+Like \f(CW\*(C`Moose\*(C'\fR, \f(CW\*(C`Class::Accessor\*(C'\fR generates accessor methods and a
+constructor for your class.
+.SS Class::Tiny
+.IX Subsection "Class::Tiny"
+Finally, we have Class::Tiny. This module truly lives up to its
+name. It has an incredibly minimal API and absolutely no dependencies
+on any recent Perl. Still, we think it's a lot easier to use than
+writing your own OO code from scratch.
+.PP
+Here's our \f(CW\*(C`File\*(C'\fR class once more:
+.PP
+.Vb 2
+\&  package File;
+\&  use Class::Tiny qw( path content last_mod_time );
+\&
+\&  sub print_info {
+\&      my $self = shift;
+\&
+\&      print "This file is at ", $self\->path, "\en";
+\&  }
+.Ve
+.PP
+That's it!
+.PP
+With \f(CW\*(C`Class::Tiny\*(C'\fR, all accessors are read-write. It generates a
+constructor for you, as well as the accessors you define.
+.PP
+You can also use Class::Tiny::Antlers for \f(CW\*(C`Moose\*(C'\fR\-like syntax.
+.SS Role::Tiny
+.IX Subsection "Role::Tiny"
+As we mentioned before, roles provide an alternative to inheritance,
+but Perl does not have any built-in role support. If you choose to use
+Moose, it comes with a full-fledged role implementation. However, if
+you use one of our other recommended OO modules, you can still use
+roles with Role::Tiny
+.PP
+\&\f(CW\*(C`Role::Tiny\*(C'\fR provides some of the same features as Moose's role
+system, but in a much smaller package. Most notably, it doesn't support
+any sort of attribute declaration, so you have to do that by hand.
+Still, it's useful, and works well with \f(CW\*(C`Class::Accessor\*(C'\fR and
+\&\f(CW\*(C`Class::Tiny\*(C'\fR
+.SS "OO System Summary"
+.IX Subsection "OO System Summary"
+Here's a brief recap of the options we covered:
+.IP \(bu 4
+Moose
+.Sp
+\&\f(CW\*(C`Moose\*(C'\fR is the maximal option. It has a lot of features, a big
+ecosystem, and a thriving user base. We also covered Moo briefly.
+\&\f(CW\*(C`Moo\*(C'\fR is \f(CW\*(C`Moose\*(C'\fR lite, and a reasonable alternative when Moose
+doesn't work for your application.
+.IP \(bu 4
+Class::Accessor
+.Sp
+\&\f(CW\*(C`Class::Accessor\*(C'\fR does a lot less than \f(CW\*(C`Moose\*(C'\fR, and is a nice
+alternative if you find \f(CW\*(C`Moose\*(C'\fR overwhelming. It's been around a long
+time and is well battle-tested. It also has a minimal \f(CW\*(C`Moose\*(C'\fR
+compatibility mode which makes moving from \f(CW\*(C`Class::Accessor\*(C'\fR to
+\&\f(CW\*(C`Moose\*(C'\fR easy.
+.IP \(bu 4
+Class::Tiny
+.Sp
+\&\f(CW\*(C`Class::Tiny\*(C'\fR is the absolute minimal option. It has no dependencies,
+and almost no syntax to learn. It's a good option for a super minimal
+environment and for throwing something together quickly without having
+to worry about details.
+.IP \(bu 4
+Role::Tiny
+.Sp
+Use \f(CW\*(C`Role::Tiny\*(C'\fR with \f(CW\*(C`Class::Accessor\*(C'\fR or \f(CW\*(C`Class::Tiny\*(C'\fR if you find
+yourself considering multiple inheritance. If you go with \f(CW\*(C`Moose\*(C'\fR, it
+comes with its own role implementation.
+.SS "Other OO Systems"
+.IX Subsection "Other OO Systems"
+There are literally dozens of other OO-related modules on CPAN besides
+those covered here, and you're likely to run across one or more of them
+if you work with other people's code.
+.PP
+In addition, plenty of code in the wild does all of its OO "by hand",
+using just the Perl built-in OO features. If you need to maintain such
+code, you should read perlobj to understand exactly how Perl's
+built-in OO works.
+.SH CONCLUSION
+.IX Header "CONCLUSION"
+As we said before, Perl's minimal OO system has led to a profusion of
+OO systems on CPAN. While you can still drop down to the bare metal and
+write your classes by hand, there's really no reason to do that with
+modern Perl.
+.PP
+For small systems, Class::Tiny and Class::Accessor both provide
+minimal object systems that take care of basic boilerplate for you.
+.PP
+For bigger projects, Moose provides a rich set of features that will
+let you focus on implementing your business logic. Moo provides a
+nice alternative to Moose when you want a lot of features but need
+faster compile time or to avoid XS.
+.PP
+We encourage you to play with and evaluate Moose, Moo,
+Class::Accessor, and Class::Tiny to see which OO system is right
+for you.
diff --git a/upstream/mageia-cauldron/man1/perlop.1 b/upstream/mageia-cauldron/man1/perlop.1
new file mode 100644
index 00000000..c850b418
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlop.1
@@ -0,0 +1,4136 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOP 1"
+.TH PERLOP 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlop \- Perl operators and precedence
+.IX Xref "operator"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+In Perl, the operator determines what operation is performed,
+independent of the type of the operands.  For example \f(CW\*(C`$x\ +\ $y\*(C'\fR
+is always a numeric addition, and if \f(CW$x\fR or \f(CW$y\fR do not contain
+numbers, an attempt is made to convert them to numbers first.
+.PP
+This is in contrast to many other dynamic languages, where the
+operation is determined by the type of the first argument.  It also
+means that Perl has two versions of some operators, one for numeric
+and one for string comparison.  For example \f(CW\*(C`$x\ ==\ $y\*(C'\fR compares
+two numbers for equality, and \f(CW\*(C`$x\ eq\ $y\*(C'\fR compares two strings.
+.PP
+There are a few exceptions though: \f(CW\*(C`x\*(C'\fR can be either string
+repetition or list repetition, depending on the type of the left
+operand, and \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`~\*(C'\fR can be either string or numeric bit
+operations.
+.SS "Operator Precedence and Associativity"
+.IX Xref "operator, precedence precedence associativity"
+.IX Subsection "Operator Precedence and Associativity"
+Operator precedence and associativity work in Perl more or less like
+they do in mathematics.
+.PP
+\&\fIOperator precedence\fR means some operators group more tightly than others.
+For example, in \f(CW\*(C`2 + 4 * 5\*(C'\fR, the multiplication has higher precedence, so \f(CW\*(C`4
+* 5\*(C'\fR is grouped together as the right-hand operand of the addition, rather
+than \f(CW\*(C`2 + 4\*(C'\fR being grouped together as the left-hand operand of the
+multiplication. It is as if the expression were written \f(CW\*(C`2 + (4 * 5)\*(C'\fR, not
+\&\f(CW\*(C`(2 + 4) * 5\*(C'\fR. So the expression yields \f(CW\*(C`2 + 20 == 22\*(C'\fR, rather than
+\&\f(CW\*(C`6 * 5 == 30\*(C'\fR.
+.PP
+\&\fIOperator associativity\fR defines what happens if a sequence of the same
+operators is used one after another:
+usually that they will be grouped at the left
+or the right. For example, in \f(CW\*(C`9 \- 3 \- 2\*(C'\fR, subtraction is left associative,
+so \f(CW\*(C`9 \- 3\*(C'\fR is grouped together as the left-hand operand of the second
+subtraction, rather than \f(CW\*(C`3 \- 2\*(C'\fR being grouped together as the right-hand
+operand of the first subtraction. It is as if the expression were written
+\&\f(CW\*(C`(9 \- 3) \- 2\*(C'\fR, not \f(CW\*(C`9 \- (3 \- 2)\*(C'\fR. So the expression yields \f(CW\*(C`6 \- 2 == 4\*(C'\fR,
+rather than \f(CW\*(C`9 \- 1 == 8\*(C'\fR.
+.PP
+For simple operators that evaluate all their operands and then combine the
+values in some way, precedence and associativity (and parentheses) imply some
+ordering requirements on those combining operations. For example, in \f(CW2 + 4 *
+5\fR, the grouping implied by precedence means that the multiplication of 4 and
+5 must be performed before the addition of 2 and 20, simply because the result
+of that multiplication is required as one of the operands of the addition. But
+the order of operations is not fully determined by this: in \f(CW\*(C`2 * 2 + 4 * 5\*(C'\fR
+both multiplications must be performed before the addition, but the grouping
+does not say anything about the order in which the two multiplications are
+performed. In fact Perl has a general rule that the operands of an operator
+are evaluated in left-to-right order. A few operators such as \f(CW\*(C`&&=\*(C'\fR have
+special evaluation rules that can result in an operand not being evaluated at
+all; in general, the top-level operator in an expression has control of
+operand evaluation.
+.PP
+Some comparison operators, as their associativity, \fIchain\fR with some
+operators of the same precedence (but never with operators of different
+precedence).  This chaining means that each comparison is performed
+on the two arguments surrounding it, with each interior argument taking
+part in two comparisons, and the comparison results are implicitly ANDed.
+Thus \f(CW"$x\ <\ $y\ <=\ $z"\fR behaves exactly like \f(CW"$x\ <\ $y\ &&\ $y\ <=\ $z"\fR, assuming that \f(CW"$y"\fR is as simple a scalar as
+it looks.  The ANDing short-circuits just like \f(CW"&&"\fR does, stopping
+the sequence of comparisons as soon as one yields false.
+.PP
+In a chained comparison, each argument expression is evaluated at most
+once, even if it takes part in two comparisons, but the result of the
+evaluation is fetched for each comparison.  (It is not evaluated
+at all if the short-circuiting means that it's not required for any
+comparisons.)  This matters if the computation of an interior argument
+is expensive or non-deterministic.  For example,
+.PP
+.Vb 1
+\&    if($x < expensive_sub() <= $z) { ...
+.Ve
+.PP
+is not entirely like
+.PP
+.Vb 1
+\&    if($x < expensive_sub() && expensive_sub() <= $z) { ...
+.Ve
+.PP
+but instead closer to
+.PP
+.Vb 2
+\&    my $tmp = expensive_sub();
+\&    if($x < $tmp && $tmp <= $z) { ...
+.Ve
+.PP
+in that the subroutine is only called once.  However, it's not exactly
+like this latter code either, because the chained comparison doesn't
+actually involve any temporary variable (named or otherwise): there is
+no assignment.  This doesn't make much difference where the expression
+is a call to an ordinary subroutine, but matters more with an lvalue
+subroutine, or if the argument expression yields some unusual kind of
+scalar by other means.  For example, if the argument expression yields
+a tied scalar, then the expression is evaluated to produce that scalar
+at most once, but the value of that scalar may be fetched up to twice,
+once for each comparison in which it is actually used.
+.PP
+In this example, the expression is evaluated only once, and the tied
+scalar (the result of the expression) is fetched for each comparison that
+uses it.
+.PP
+.Vb 1
+\&    if ($x < $tied_scalar < $z) { ...
+.Ve
+.PP
+In the next example, the expression is evaluated only once, and the tied
+scalar is fetched once as part of the operation within the expression.
+The result of that operation is fetched for each comparison, which
+normally doesn't matter unless that expression result is also magical due
+to operator overloading.
+.PP
+.Vb 1
+\&    if ($x < $tied_scalar + 42 < $z) { ...
+.Ve
+.PP
+Some operators are instead non-associative, meaning that it is a syntax
+error to use a sequence of those operators of the same precedence.
+For example, \f(CW"$x\ ..\ $y\ ..\ $z"\fR is an error.
+.PP
+Perl operators have the following associativity and precedence,
+listed from highest precedence to lowest.  Operators borrowed from
+C keep the same precedence relationship with each other, even where
+C's precedence is slightly screwy.  (This makes learning Perl easier
+for C folks.)  With very few exceptions, these all operate on scalar
+values only, not array values.
+.PP
+.Vb 10
+\&    left        terms and list operators (leftward)
+\&    left        \->
+\&    nonassoc    ++ \-\-
+\&    right       **
+\&    right       ! ~ ~. \e and unary + and \-
+\&    left        =~ !~
+\&    left        * / % x
+\&    left        + \- .
+\&    left        << >>
+\&    nonassoc    named unary operators
+\&    nonassoc    isa
+\&    chained     < > <= >= lt gt le ge
+\&    chain/na    == != eq ne <=> cmp ~~
+\&    left        & &.
+\&    left        | |. ^ ^.
+\&    left        &&
+\&    left        || //
+\&    nonassoc    ..  ...
+\&    right       ?:
+\&    right       = += \-= *= etc. goto last next redo dump
+\&    left        , =>
+\&    nonassoc    list operators (rightward)
+\&    right       not
+\&    left        and
+\&    left        or xor
+.Ve
+.PP
+In the following sections, these operators are covered in detail, in the
+same order in which they appear in the table above.
+.PP
+Many operators can be overloaded for objects.  See overload.
+.SS "Terms and List Operators (Leftward)"
+.IX Xref "list operator operator, list term"
+.IX Subsection "Terms and List Operators (Leftward)"
+A TERM has the highest precedence in Perl.  They include variables,
+quote and quote-like operators, any expression in parentheses,
+and any function whose arguments are parenthesized.  Actually, there
+aren't really functions in this sense, just list operators and unary
+operators behaving as functions because you put parentheses around
+the arguments.  These are all documented in perlfunc.
+.PP
+If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
+is followed by a left parenthesis as the next token, the operator and
+arguments within parentheses are taken to be of highest precedence,
+just like a normal function call.
+.PP
+In the absence of parentheses, the precedence of list operators such as
+\&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, or \f(CW\*(C`chmod\*(C'\fR is either very high or very low depending on
+whether you are looking at the left side or the right side of the operator.
+For example, in
+.PP
+.Vb 2
+\&    @ary = (1, 3, sort 4, 2);
+\&    print @ary;         # prints 1324
+.Ve
+.PP
+the commas on the right of the \f(CW\*(C`sort\*(C'\fR are evaluated before the \f(CW\*(C`sort\*(C'\fR,
+but the commas on the left are evaluated after.  In other words,
+list operators tend to gobble up all arguments that follow, and
+then act like a simple TERM with regard to the preceding expression.
+Be careful with parentheses:
+.PP
+.Vb 3
+\&    # These evaluate exit before doing the print:
+\&    print($foo, exit);  # Obviously not what you want.
+\&    print $foo, exit;   # Nor is this.
+\&
+\&    # These do the print before evaluating exit:
+\&    (print $foo), exit; # This is what you want.
+\&    print($foo), exit;  # Or this.
+\&    print ($foo), exit; # Or even this.
+.Ve
+.PP
+Also note that
+.PP
+.Vb 1
+\&    print ($foo & 255) + 1, "\en";
+.Ve
+.PP
+probably doesn't do what you expect at first glance.  The parentheses
+enclose the argument list for \f(CW\*(C`print\*(C'\fR which is evaluated (printing
+the result of \f(CW\*(C`$foo\ &\ 255\*(C'\fR).  Then one is added to the return value
+of \f(CW\*(C`print\*(C'\fR (usually 1).  The result is something like this:
+.PP
+.Vb 1
+\&    1 + 1, "\en";    # Obviously not what you meant.
+.Ve
+.PP
+To do what you meant properly, you must write:
+.PP
+.Vb 1
+\&    print(($foo & 255) + 1, "\en");
+.Ve
+.PP
+See "Named Unary Operators" for more discussion of this.
+.PP
+Also parsed as terms are the \f(CW\*(C`do\ {}\*(C'\fR and \f(CW\*(C`eval\ {}\*(C'\fR constructs, as
+well as subroutine and method calls, and the anonymous
+constructors \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR.
+.PP
+See also "Quote and Quote-like Operators" toward the end of this section,
+as well as "I/O Operators".
+.SS "The Arrow Operator"
+.IX Xref "arrow dereference ->"
+.IX Subsection "The Arrow Operator"
+"\f(CW\*(C`\->\*(C'\fR" is an infix dereference operator, just as it is in C
+and C++.  If the right side is either a \f(CW\*(C`[...]\*(C'\fR, \f(CW\*(C`{...}\*(C'\fR, or a
+\&\f(CW\*(C`(...)\*(C'\fR subscript, then the left side must be either a hard or
+symbolic reference to an array, a hash, or a subroutine respectively.
+(Or technically speaking, a location capable of holding a hard
+reference, if it's an array or hash reference being used for
+assignment.)  See perlreftut and perlref.
+.PP
+Otherwise, the right side is a method name or a simple scalar
+variable containing either the method name or a subroutine reference,
+and (if it is a method name) the left side must be either an object (a
+blessed reference) or a class name (that is, a package name).  See
+perlobj.
+.PP
+The dereferencing cases (as opposed to method-calling cases) are
+somewhat extended by the \f(CW\*(C`postderef\*(C'\fR feature.  For the
+details of that feature, consult "Postfix Dereference Syntax" in perlref.
+.SS "Auto-increment and Auto-decrement"
+.IX Xref "increment auto-increment ++ decrement auto-decrement --"
+.IX Subsection "Auto-increment and Auto-decrement"
+\&\f(CW"++"\fR and \f(CW"\-\-"\fR work as in C.  That is, if placed before a variable,
+they increment or decrement the variable by one before returning the
+value, and if placed after, increment or decrement after returning the
+value.
+.PP
+.Vb 3
+\&    $i = 0;  $j = 0;
+\&    print $i++;  # prints 0
+\&    print ++$j;  # prints 1
+.Ve
+.PP
+Note that just as in C, Perl doesn't define \fBwhen\fR the variable is
+incremented or decremented.  You just know it will be done sometime
+before or after the value is returned.  This also means that modifying
+a variable twice in the same statement will lead to undefined behavior.
+Avoid statements like:
+.PP
+.Vb 2
+\&    $i = $i ++;
+\&    print ++ $i + $i ++;
+.Ve
+.PP
+Perl will not guarantee what the result of the above statements is.
+.PP
+The auto-increment operator has a little extra builtin magic to it.  If
+you increment a variable that is numeric, or that has ever been used in
+a numeric context, you get a normal increment.  If, however, the
+variable has been used in only string contexts since it was set, and
+has a value that is not the empty string and matches the pattern
+\&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the increment is done as a string, preserving each
+character within its range, with carry:
+.PP
+.Vb 4
+\&    print ++($foo = "99");      # prints "100"
+\&    print ++($foo = "a0");      # prints "a1"
+\&    print ++($foo = "Az");      # prints "Ba"
+\&    print ++($foo = "zz");      # prints "aaa"
+.Ve
+.PP
+\&\f(CW\*(C`undef\*(C'\fR is always treated as numeric, and in particular is changed
+to \f(CW0\fR before incrementing (so that a post-increment of an undef value
+will return \f(CW0\fR rather than \f(CW\*(C`undef\*(C'\fR).
+.PP
+The auto-decrement operator is not magical.
+.SS Exponentiation
+.IX Xref "** exponentiation power"
+.IX Subsection "Exponentiation"
+Binary \f(CW"**"\fR is the exponentiation operator.  It binds even more
+tightly than unary minus, so \f(CW\*(C`\-2**4\*(C'\fR is \f(CW\*(C`\-(2**4)\*(C'\fR, not \f(CW\*(C`(\-2)**4\*(C'\fR.
+(This is
+implemented using C's \f(CWpow(3)\fR function, which actually works on doubles
+internally.)
+.PP
+Note that certain exponentiation expressions are ill-defined:
+these include \f(CW\*(C`0**0\*(C'\fR, \f(CW\*(C`1**Inf\*(C'\fR, and \f(CW\*(C`Inf**0\*(C'\fR.  Do not expect
+any particular results from these special cases, the results
+are platform-dependent.
+.SS "Symbolic Unary Operators"
+.IX Xref "unary operator operator, unary"
+.IX Subsection "Symbolic Unary Operators"
+Unary \f(CW"!"\fR performs logical negation, that is, "not".  See also
+\&\f(CW\*(C`not\*(C'\fR for a lower precedence version of this.
+.IX Xref "!"
+.PP
+Unary \f(CW"\-"\fR performs arithmetic negation if the operand is numeric,
+including any string that looks like a number.  If the operand is
+an identifier, a string consisting of a minus sign concatenated
+with the identifier is returned.  Otherwise, if the string starts
+with a plus or minus, a string starting with the opposite sign is
+returned.  One effect of these rules is that \f(CW\*(C`\-bareword\*(C'\fR is equivalent
+to the string \f(CW"\-bareword"\fR.  If, however, the string begins with a
+non-alphabetic character (excluding \f(CW"+"\fR or \f(CW"\-"\fR), Perl will attempt
+to convert
+the string to a numeric, and the arithmetic negation is performed.  If the
+string cannot be cleanly converted to a numeric, Perl will give the warning
+\&\fBArgument "the string" isn't numeric in negation (\-) at ...\fR.
+.IX Xref "- negation, arithmetic"
+.PP
+Unary \f(CW"~"\fR performs bitwise negation, that is, 1's complement.  For
+example, \f(CW\*(C`0666\ &\ ~027\*(C'\fR is 0640.  (See also "Integer Arithmetic" and
+"Bitwise String Operators".)  Note that the width of the result is
+platform-dependent: \f(CW\*(C`~0\*(C'\fR is 32 bits wide on a 32\-bit platform, but 64
+bits wide on a 64\-bit platform, so if you are expecting a certain bit
+width, remember to use the \f(CW"&"\fR operator to mask off the excess bits.
+.IX Xref "~ negation, binary"
+.PP
+Starting in Perl 5.28, it is a fatal error to try to complement a string
+containing a character with an ordinal value above 255.
+.PP
+If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or \f(CW\*(C`use v5.28\*(C'\fR, then unary
+\&\f(CW"~"\fR always treats its argument as a number, and an
+alternate form of the operator, \f(CW"~."\fR, always treats its argument as a
+string.  So \f(CW\*(C`~0\*(C'\fR and \f(CW\*(C`~"0"\*(C'\fR will both give 2**32\-1 on 32\-bit platforms,
+whereas \f(CW\*(C`~.0\*(C'\fR and \f(CW\*(C`~."0"\*(C'\fR will both yield \f(CW"\exff"\fR.  Until Perl 5.28,
+this feature produced a warning in the \f(CW"experimental::bitwise"\fR category.
+.PP
+Unary \f(CW"+"\fR has no effect whatsoever, even on strings.  It is useful
+syntactically for separating a function name from a parenthesized expression
+that would otherwise be interpreted as the complete list of function
+arguments.  (See examples above under "Terms and List Operators (Leftward)".)
+.IX Xref "+"
+.PP
+Unary \f(CW"\e"\fR creates references.  If its operand is a single sigilled
+thing, it creates a reference to that object.  If its operand is a
+parenthesised list, then it creates references to the things mentioned
+in the list.  Otherwise it puts its operand in list context, and creates
+a list of references to the scalars in the list provided by the operand.
+See perlreftut
+and perlref.  Do not confuse this behavior with the behavior of
+backslash within a string, although both forms do convey the notion
+of protecting the next thing from interpolation.
+.IX Xref "\\ reference backslash"
+.SS "Binding Operators"
+.IX Xref "binding operator, binding =~ !~"
+.IX Subsection "Binding Operators"
+Binary \f(CW"=~"\fR binds a scalar expression to a pattern match.  Certain operations
+search or modify the string \f(CW$_\fR by default.  This operator makes that kind
+of operation work on some other string.  The right argument is a search
+pattern, substitution, or transliteration.  The left argument is what is
+supposed to be searched, substituted, or transliterated instead of the default
+\&\f(CW$_\fR.  When used in scalar context, the return value generally indicates the
+success of the operation.  The exceptions are substitution (\f(CW\*(C`s///\*(C'\fR)
+and transliteration (\f(CW\*(C`y///\*(C'\fR) with the \f(CW\*(C`/r\*(C'\fR (non-destructive) option,
+which cause the \fBr\fReturn value to be the result of the substitution.
+Behavior in list context depends on the particular operator.
+See "Regexp Quote-Like Operators" for details and perlretut for
+examples using these operators.
+.PP
+If the right argument is an expression rather than a search pattern,
+substitution, or transliteration, it is interpreted as a search pattern at run
+time.  Note that this means that its
+contents will be interpolated twice, so
+.PP
+.Vb 1
+\&    \*(Aq\e\e\*(Aq =~ q\*(Aq\e\e\*(Aq;
+.Ve
+.PP
+is not ok, as the regex engine will end up trying to compile the
+pattern \f(CW\*(C`\e\*(C'\fR, which it will consider a syntax error.
+.PP
+Binary \f(CW"!~"\fR is just like \f(CW"=~"\fR except the return value is negated in
+the logical sense.
+.PP
+Binary \f(CW"!~"\fR with a non-destructive substitution (\f(CW\*(C`s///r\*(C'\fR) or transliteration
+(\f(CW\*(C`y///r\*(C'\fR) is a syntax error.
+.SS "Multiplicative Operators"
+.IX Xref "operator, multiplicative"
+.IX Subsection "Multiplicative Operators"
+Binary \f(CW"*"\fR multiplies two numbers.
+.IX Xref "*"
+.PP
+Binary \f(CW"/"\fR divides two numbers.
+.IX Xref "slash"
+.PP
+Binary \f(CW"%"\fR is the modulo operator, which computes the division
+remainder of its first argument with respect to its second argument.
+Given integer
+operands \f(CW$m\fR and \f(CW$n\fR: If \f(CW$n\fR is positive, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is
+\&\f(CW$m\fR minus the largest multiple of \f(CW$n\fR less than or equal to
+\&\f(CW$m\fR.  If \f(CW$n\fR is negative, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is \f(CW$m\fR minus the
+smallest multiple of \f(CW$n\fR that is not less than \f(CW$m\fR (that is, the
+result will be less than or equal to zero).  If the operands
+\&\f(CW$m\fR and \f(CW$n\fR are floating point values and the absolute value of
+\&\f(CW$n\fR (that is \f(CWabs($n)\fR) is less than \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, only
+the integer portion of \f(CW$m\fR and \f(CW$n\fR will be used in the operation
+(Note: here \f(CW\*(C`UV_MAX\*(C'\fR means the maximum of the unsigned integer type).
+If the absolute value of the right operand (\f(CWabs($n)\fR) is greater than
+or equal to \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, \f(CW"%"\fR computes the floating-point remainder
+\&\f(CW$r\fR in the equation \f(CW\*(C`($r\ =\ $m\ \-\ $i*$n)\*(C'\fR where \f(CW$i\fR is a certain
+integer that makes \f(CW$r\fR have the same sign as the right operand
+\&\f(CW$n\fR (\fBnot\fR as the left operand \f(CW$m\fR like C function \f(CWfmod()\fR)
+and the absolute value less than that of \f(CW$n\fR.
+Note that when \f(CW\*(C`use\ integer\*(C'\fR is in scope, \f(CW"%"\fR gives you direct access
+to the modulo operator as implemented by your C compiler.  This
+operator is not as well defined for negative operands, but it will
+execute faster.
+.IX Xref "% remainder modulo mod"
+.PP
+Binary \f(CW\*(C`x\*(C'\fR is the repetition operator.  In scalar context, or if the
+left operand is neither enclosed in parentheses nor a \f(CW\*(C`qw//\*(C'\fR list,
+it performs a string repetition.  In that case it supplies scalar
+context to the left operand, and returns a string consisting of the
+left operand string repeated the number of times specified by the right
+operand.  If the \f(CW\*(C`x\*(C'\fR is in list context, and the left operand is either
+enclosed in parentheses or a \f(CW\*(C`qw//\*(C'\fR list, it performs a list repetition.
+In that case it supplies list context to the left operand, and returns
+a list consisting of the left operand list repeated the number of times
+specified by the right operand.
+If the right operand is zero or negative (raising a warning on
+negative), it returns an empty string
+or an empty list, depending on the context.
+.IX Xref "x"
+.PP
+.Vb 1
+\&    print \*(Aq\-\*(Aq x 80;             # print row of dashes
+\&
+\&    print "\et" x ($tab/8), \*(Aq \*(Aq x ($tab%8);      # tab over
+\&
+\&    @ones = (1) x 80;           # a list of 80 1\*(Aqs
+\&    @ones = (5) x @ones;        # set all elements to 5
+.Ve
+.SS "Additive Operators"
+.IX Xref "operator, additive"
+.IX Subsection "Additive Operators"
+Binary \f(CW"+"\fR returns the sum of two numbers.
+.IX Xref "+"
+.PP
+Binary \f(CW"\-"\fR returns the difference of two numbers.
+.IX Xref "-"
+.PP
+Binary \f(CW"."\fR concatenates two strings.
+.IX Xref "string, concatenation concatenation cat concat concatenate ."
+.SS "Shift Operators"
+.IX Xref "shift operator operator, shift << >> right shift left shift bitwise shift shl shr shift, right shift, left"
+.IX Subsection "Shift Operators"
+Binary \f(CW"<<"\fR returns the value of its left argument shifted left by the
+number of bits specified by the right argument.  Arguments should be
+integers.  (See also "Integer Arithmetic".)
+.PP
+Binary \f(CW">>"\fR returns the value of its left argument shifted right by
+the number of bits specified by the right argument.  Arguments should
+be integers.  (See also "Integer Arithmetic".)
+.PP
+If \f(CW\*(C`use\ integer\*(C'\fR (see "Integer Arithmetic") is in force then
+signed C integers are used (\fIarithmetic shift\fR), otherwise unsigned C
+integers are used (\fIlogical shift\fR), even for negative shiftees.
+In arithmetic right shift the sign bit is replicated on the left,
+in logical shift zero bits come in from the left.
+.PP
+Either way, the implementation isn't going to generate results larger
+than the size of the integer type Perl was built with (32 bits or 64 bits).
+.PP
+Shifting by negative number of bits means the reverse shift: left
+shift becomes right shift, right shift becomes left shift.  This is
+unlike in C, where negative shift is undefined.
+.PP
+Shifting by more bits than the size of the integers means most of the
+time zero (all bits fall off), except that under \f(CW\*(C`use\ integer\*(C'\fR
+right overshifting a negative shiftee results in \-1.  This is unlike
+in C, where shifting by too many bits is undefined.  A common C
+behavior is "shift by modulo wordbits", so that for example
+.PP
+.Vb 1
+\&    1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1  # Common C behavior.
+.Ve
+.PP
+but that is completely accidental.
+.PP
+If you get tired of being subject to your platform's native integers,
+the \f(CW\*(C`use\ bigint\*(C'\fR pragma neatly sidesteps the issue altogether:
+.PP
+.Vb 5
+\&    print 20 << 20;  # 20971520
+\&    print 20 << 40;  # 5120 on 32\-bit machines,
+\&                     # 21990232555520 on 64\-bit machines
+\&    use bigint;
+\&    print 20 << 100; # 25353012004564588029934064107520
+.Ve
+.SS "Named Unary Operators"
+.IX Xref "operator, named unary"
+.IX Subsection "Named Unary Operators"
+The various named unary operators are treated as functions with one
+argument, with optional parentheses.
+.PP
+If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
+is followed by a left parenthesis as the next token, the operator and
+arguments within parentheses are taken to be of highest precedence,
+just like a normal function call.  For example,
+because named unary operators are higher precedence than \f(CW\*(C`||\*(C'\fR:
+.PP
+.Vb 4
+\&    chdir $foo    || die;       # (chdir $foo) || die
+\&    chdir($foo)   || die;       # (chdir $foo) || die
+\&    chdir ($foo)  || die;       # (chdir $foo) || die
+\&    chdir +($foo) || die;       # (chdir $foo) || die
+.Ve
+.PP
+but, because \f(CW"*"\fR is higher precedence than named operators:
+.PP
+.Vb 4
+\&    chdir $foo * 20;    # chdir ($foo * 20)
+\&    chdir($foo) * 20;   # (chdir $foo) * 20
+\&    chdir ($foo) * 20;  # (chdir $foo) * 20
+\&    chdir +($foo) * 20; # chdir ($foo * 20)
+\&
+\&    rand 10 * 20;       # rand (10 * 20)
+\&    rand(10) * 20;      # (rand 10) * 20
+\&    rand (10) * 20;     # (rand 10) * 20
+\&    rand +(10) * 20;    # rand (10 * 20)
+.Ve
+.PP
+Regarding precedence, the filetest operators, like \f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, etc. are
+treated like named unary operators, but they don't follow this functional
+parenthesis rule.  That means, for example, that \f(CW\*(C`\-f($file).".bak"\*(C'\fR is
+equivalent to \f(CW\*(C`\-f\ "$file.bak"\*(C'\fR.
+.IX Xref "-X filetest operator, filetest"
+.PP
+See also "Terms and List Operators (Leftward)".
+.SS "Relational Operators"
+.IX Xref "relational operator operator, relational"
+.IX Subsection "Relational Operators"
+Perl operators that return true or false generally return values
+that can be safely used as numbers.  For example, the relational
+operators in this section and the equality operators in the next
+one return \f(CW1\fR for true and a special version of the defined empty
+string, \f(CW""\fR, which counts as a zero but is exempt from warnings
+about improper numeric conversions, just as \f(CW"0\ but\ true"\fR is.
+.PP
+Binary \f(CW"<"\fR returns true if the left argument is numerically less than
+the right argument.
+.IX Xref "<"
+.PP
+Binary \f(CW">"\fR returns true if the left argument is numerically greater
+than the right argument.
+.IX Xref ">"
+.PP
+Binary \f(CW"<="\fR returns true if the left argument is numerically less than
+or equal to the right argument.
+.IX Xref "<="
+.PP
+Binary \f(CW">="\fR returns true if the left argument is numerically greater
+than or equal to the right argument.
+.IX Xref ">="
+.PP
+Binary \f(CW"lt"\fR returns true if the left argument is stringwise less than
+the right argument.
+.IX Xref "lt"
+.PP
+Binary \f(CW"gt"\fR returns true if the left argument is stringwise greater
+than the right argument.
+.IX Xref "gt"
+.PP
+Binary \f(CW"le"\fR returns true if the left argument is stringwise less than
+or equal to the right argument.
+.IX Xref "le"
+.PP
+Binary \f(CW"ge"\fR returns true if the left argument is stringwise greater
+than or equal to the right argument.
+.IX Xref "ge"
+.PP
+A sequence of relational operators, such as \f(CW"$x\ <\ $y\ <=\ $z"\fR, performs chained comparisons, in the manner described above in
+the section "Operator Precedence and Associativity".
+Beware that they do not chain with equality operators, which have lower
+precedence.
+.SS "Equality Operators"
+.IX Xref "equality equal equals operator, equality"
+.IX Subsection "Equality Operators"
+Binary \f(CW"=="\fR returns true if the left argument is numerically equal to
+the right argument.
+.IX Xref "=="
+.PP
+Binary \f(CW"!="\fR returns true if the left argument is numerically not equal
+to the right argument.
+.IX Xref "!="
+.PP
+Binary \f(CW"eq"\fR returns true if the left argument is stringwise equal to
+the right argument.
+.IX Xref "eq"
+.PP
+Binary \f(CW"ne"\fR returns true if the left argument is stringwise not equal
+to the right argument.
+.IX Xref "ne"
+.PP
+A sequence of the above equality operators, such as \f(CW"$x\ ==\ $y\ ==\ $z"\fR, performs chained comparisons, in the manner described above in
+the section "Operator Precedence and Associativity".
+Beware that they do not chain with relational operators, which have
+higher precedence.
+.PP
+Binary \f(CW"<=>"\fR returns \-1, 0, or 1 depending on whether the left
+argument is numerically less than, equal to, or greater than the right
+argument.  If your platform supports \f(CW\*(C`NaN\*(C'\fR's (not-a-numbers) as numeric
+values, using them with \f(CW"<=>"\fR returns undef.  \f(CW\*(C`NaN\*(C'\fR is not
+\&\f(CW"<"\fR, \f(CW"=="\fR, \f(CW">"\fR, \f(CW"<="\fR or \f(CW">="\fR anything
+(even \f(CW\*(C`NaN\*(C'\fR), so those 5 return false.  \f(CW\*(C`NaN\ !=\ NaN\*(C'\fR returns
+true, as does \f(CW\*(C`NaN\ !=\*(C'\fR\ \fIanything\ else\fR.  If your platform doesn't
+support \f(CW\*(C`NaN\*(C'\fR's then \f(CW\*(C`NaN\*(C'\fR is just a string with numeric value 0.
+.IX Xref "<=> spaceship"
+.PP
+.Vb 2
+\&    $ perl \-le \*(Aq$x = "NaN"; print "No NaN support here" if $x == $x\*(Aq
+\&    $ perl \-le \*(Aq$x = "NaN"; print "NaN support here" if $x != $x\*(Aq
+.Ve
+.PP
+(Note that the bigint, bigrat, and bignum pragmas all
+support \f(CW"NaN"\fR.)
+.PP
+Binary \f(CW"cmp"\fR returns \-1, 0, or 1 depending on whether the left
+argument is stringwise less than, equal to, or greater than the right
+argument.
+.PP
+Here we can see the difference between <=> and cmp,
+.PP
+.Vb 2
+\&    print 10 <=> 2 #prints 1
+\&    print 10 cmp 2 #prints \-1
+.Ve
+.PP
+(likewise between gt and >, lt and <, etc.)
+.IX Xref "cmp"
+.PP
+Binary \f(CW"~~"\fR does a smartmatch between its arguments.  Smart matching
+is described in the next section.
+.IX Xref "~~"
+.PP
+The two-sided ordering operators \f(CW"<=>"\fR and \f(CW"cmp"\fR, and the
+smartmatch operator \f(CW"~~"\fR, are non-associative with respect to each
+other and with respect to the equality operators of the same precedence.
+.PP
+\&\f(CW"lt"\fR, \f(CW"le"\fR, \f(CW"ge"\fR, \f(CW"gt"\fR and \f(CW"cmp"\fR use the collation (sort)
+order specified by the current \f(CW\*(C`LC_COLLATE\*(C'\fR locale if a \f(CW\*(C`use\ locale\*(C'\fR form that includes collation is in effect.  See perllocale.
+Do not mix these with Unicode,
+only use them with legacy 8\-bit locale encodings.
+The standard \f(CW\*(C`Unicode::Collate\*(C'\fR and
+\&\f(CW\*(C`Unicode::Collate::Locale\*(C'\fR modules offer much more powerful
+solutions to collation issues.
+.PP
+For case-insensitive comparisons, look at the "fc" in perlfunc case-folding
+function, available in Perl v5.16 or later:
+.PP
+.Vb 1
+\&    if ( fc($x) eq fc($y) ) { ... }
+.Ve
+.SS "Class Instance Operator"
+.IX Xref "isa operator"
+.IX Subsection "Class Instance Operator"
+Binary \f(CW\*(C`isa\*(C'\fR evaluates to true when the left argument is an object instance of
+the class (or a subclass derived from that class) given by the right argument.
+If the left argument is not defined, not a blessed object instance, nor does
+not derive from the class given by the right argument, the operator evaluates
+as false. The right argument may give the class either as a bareword or a
+scalar expression that yields a string class name:
+.PP
+.Vb 1
+\&    if( $obj isa Some::Class ) { ... }
+\&
+\&    if( $obj isa "Different::Class" ) { ... }
+\&    if( $obj isa $name_of_class ) { ... }
+.Ve
+.PP
+This feature is available from Perl 5.31.6 onwards when enabled by
+\&\f(CW\*(C`use feature \*(Aqisa\*(Aq\*(C'\fR. This feature is enabled automatically by a
+\&\f(CW\*(C`use v5.36\*(C'\fR (or higher) declaration in the current scope.
+.SS "Smartmatch Operator"
+.IX Subsection "Smartmatch Operator"
+First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
+binary \f(CW\*(C`~~\*(C'\fR does a "smartmatch" between its arguments.  This is mostly
+used implicitly in the \f(CW\*(C`when\*(C'\fR construct described in perlsyn, although
+not all \f(CW\*(C`when\*(C'\fR clauses call the smartmatch operator.  Unique among all of
+Perl's operators, the smartmatch operator can recurse.  The smartmatch
+operator is experimental and its behavior is
+subject to change.
+.PP
+It is also unique in that all other Perl operators impose a context
+(usually string or numeric context) on their operands, autoconverting
+those operands to those imposed contexts.  In contrast, smartmatch
+\&\fIinfers\fR contexts from the actual types of its operands and uses that
+type information to select a suitable comparison mechanism.
+.PP
+The \f(CW\*(C`~~\*(C'\fR operator compares its operands "polymorphically", determining how
+to compare them according to their actual types (numeric, string, array,
+hash, etc.).  Like the equality operators with which it shares the same
+precedence, \f(CW\*(C`~~\*(C'\fR returns 1 for true and \f(CW""\fR for false.  It is often best
+read aloud as "in", "inside of", or "is contained in", because the left
+operand is often looked for \fIinside\fR the right operand.  That makes the
+order of the operands to the smartmatch operand often opposite that of
+the regular match operator.  In other words, the "smaller" thing is usually
+placed in the left operand and the larger one in the right.
+.PP
+The behavior of a smartmatch depends on what type of things its arguments
+are, as determined by the following table.  The first row of the table
+whose types apply determines the smartmatch behavior.  Because what
+actually happens is mostly determined by the type of the second operand,
+the table is sorted on the right operand instead of on the left.
+.PP
+.Vb 4
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& Any       undef      check whether Any is undefined
+\&                like: !defined Any
+\&
+\& Any       Object     invoke ~~ overloading on Object, or die
+\&
+\& Right operand is an ARRAY:
+\&
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& ARRAY1    ARRAY2     recurse on paired elements of ARRAY1 and ARRAY2[2]
+\&                like: (ARRAY1[0] ~~ ARRAY2[0])
+\&                        && (ARRAY1[1] ~~ ARRAY2[1]) && ...
+\& HASH      ARRAY      any ARRAY elements exist as HASH keys
+\&                like: grep { exists HASH\->{$_} } ARRAY
+\& Regexp    ARRAY      any ARRAY elements pattern match Regexp
+\&                like: grep { /Regexp/ } ARRAY
+\& undef     ARRAY      undef in ARRAY
+\&                like: grep { !defined } ARRAY
+\& Any       ARRAY      smartmatch each ARRAY element[3]
+\&                like: grep { Any ~~ $_ } ARRAY
+\&
+\& Right operand is a HASH:
+\&
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& HASH1     HASH2      all same keys in both HASHes
+\&                like: keys HASH1 ==
+\&                         grep { exists HASH2\->{$_} } keys HASH1
+\& ARRAY     HASH       any ARRAY elements exist as HASH keys
+\&                like: grep { exists HASH\->{$_} } ARRAY
+\& Regexp    HASH       any HASH keys pattern match Regexp
+\&                like: grep { /Regexp/ } keys HASH
+\& undef     HASH       always false (undef cannot be a key)
+\&                like: 0 == 1
+\& Any       HASH       HASH key existence
+\&                like: exists HASH\->{Any}
+\&
+\& Right operand is CODE:
+\&
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& ARRAY     CODE       sub returns true on all ARRAY elements[1]
+\&                like: !grep { !CODE\->($_) } ARRAY
+\& HASH      CODE       sub returns true on all HASH keys[1]
+\&                like: !grep { !CODE\->($_) } keys HASH
+\& Any       CODE       sub passed Any returns true
+\&                like: CODE\->(Any)
+\&
+\& Right operand is a Regexp:
+\&
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& ARRAY     Regexp     any ARRAY elements match Regexp
+\&                like: grep { /Regexp/ } ARRAY
+\& HASH      Regexp     any HASH keys match Regexp
+\&                like: grep { /Regexp/ } keys HASH
+\& Any       Regexp     pattern match
+\&                like: Any =~ /Regexp/
+\&
+\& Other:
+\&
+\& Left      Right      Description and pseudocode
+\& ===============================================================
+\& Object    Any        invoke ~~ overloading on Object,
+\&                      or fall back to...
+\&
+\& Any       Num        numeric equality
+\&                 like: Any == Num
+\& Num       nummy[4]    numeric equality
+\&                 like: Num == nummy
+\& undef     Any        check whether undefined
+\&                 like: !defined(Any)
+\& Any       Any        string equality
+\&                 like: Any eq Any
+.Ve
+.PP
+Notes:
+.IP "1. Empty hashes or arrays match." 4
+.IX Item "1. Empty hashes or arrays match."
+.PD 0
+.IP "2. That is, each element smartmatches the element of the same index in the other array.[3]" 4
+.IX Item "2. That is, each element smartmatches the element of the same index in the other array.[3]"
+.IP "3. If a circular reference is found, fall back to referential equality." 4
+.IX Item "3. If a circular reference is found, fall back to referential equality."
+.IP "4. Either an actual number, or a string that looks like one." 4
+.IX Item "4. Either an actual number, or a string that looks like one."
+.PD
+.PP
+The smartmatch implicitly dereferences any non-blessed hash or array
+reference, so the \f(CW\*(C`\fR\f(CIHASH\fR\f(CW\*(C'\fR and \f(CW\*(C`\fR\f(CIARRAY\fR\f(CW\*(C'\fR entries apply in those cases.
+For blessed references, the \f(CW\*(C`\fR\f(CIObject\fR\f(CW\*(C'\fR entries apply.  Smartmatches
+involving hashes only consider hash keys, never hash values.
+.PP
+The "like" code entry is not always an exact rendition.  For example, the
+smartmatch operator short-circuits whenever possible, but \f(CW\*(C`grep\*(C'\fR does
+not.  Also, \f(CW\*(C`grep\*(C'\fR in scalar context returns the number of matches, but
+\&\f(CW\*(C`~~\*(C'\fR returns only true or false.
+.PP
+Unlike most operators, the smartmatch operator knows to treat \f(CW\*(C`undef\*(C'\fR
+specially:
+.PP
+.Vb 3
+\&    use v5.10.1;
+\&    @array = (1, 2, 3, undef, 4, 5);
+\&    say "some elements undefined" if undef ~~ @array;
+.Ve
+.PP
+Each operand is considered in a modified scalar context, the modification
+being that array and hash variables are passed by reference to the
+operator, which implicitly dereferences them.  Both elements
+of each pair are the same:
+.PP
+.Vb 1
+\&    use v5.10.1;
+\&
+\&    my %hash = (red    => 1, blue   => 2, green  => 3,
+\&                orange => 4, yellow => 5, purple => 6,
+\&                black  => 7, grey   => 8, white  => 9);
+\&
+\&    my @array = qw(red blue green);
+\&
+\&    say "some array elements in hash keys" if  @array ~~  %hash;
+\&    say "some array elements in hash keys" if \e@array ~~ \e%hash;
+\&
+\&    say "red in array" if "red" ~~  @array;
+\&    say "red in array" if "red" ~~ \e@array;
+\&
+\&    say "some keys end in e" if /e$/ ~~  %hash;
+\&    say "some keys end in e" if /e$/ ~~ \e%hash;
+.Ve
+.PP
+Two arrays smartmatch if each element in the first array smartmatches
+(that is, is "in") the corresponding element in the second array,
+recursively.
+.PP
+.Vb 6
+\&    use v5.10.1;
+\&    my @little = qw(red blue green);
+\&    my @bigger = ("red", "blue", [ "orange", "green" ] );
+\&    if (@little ~~ @bigger) {  # true!
+\&        say "little is contained in bigger";
+\&    }
+.Ve
+.PP
+Because the smartmatch operator recurses on nested arrays, this
+will still report that "red" is in the array.
+.PP
+.Vb 4
+\&    use v5.10.1;
+\&    my @array = qw(red blue green);
+\&    my $nested_array = [[[[[[[ @array ]]]]]]];
+\&    say "red in array" if "red" ~~ $nested_array;
+.Ve
+.PP
+If two arrays smartmatch each other, then they are deep
+copies of each others' values, as this example reports:
+.PP
+.Vb 3
+\&    use v5.12.0;
+\&    my @a = (0, 1, 2, [3, [4, 5], 6], 7);
+\&    my @b = (0, 1, 2, [3, [4, 5], 6], 7);
+\&
+\&    if (@a ~~ @b && @b ~~ @a) {
+\&        say "a and b are deep copies of each other";
+\&    }
+\&    elsif (@a ~~ @b) {
+\&        say "a smartmatches in b";
+\&    }
+\&    elsif (@b ~~ @a) {
+\&        say "b smartmatches in a";
+\&    }
+\&    else {
+\&        say "a and b don\*(Aqt smartmatch each other at all";
+\&    }
+.Ve
+.PP
+If you were to set \f(CW\*(C`$b[3]\ =\ 4\*(C'\fR, then instead of reporting that "a and b
+are deep copies of each other", it now reports that \f(CW"b smartmatches in a"\fR.
+That's because the corresponding position in \f(CW@a\fR contains an array that
+(eventually) has a 4 in it.
+.PP
+Smartmatching one hash against another reports whether both contain the
+same keys, no more and no less.  This could be used to see whether two
+records have the same field names, without caring what values those fields
+might have.  For example:
+.PP
+.Vb 3
+\&    use v5.10.1;
+\&    sub make_dogtag {
+\&        state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
+\&
+\&        my ($class, $init_fields) = @_;
+\&
+\&        die "Must supply (only) name, rank, and serial number"
+\&            unless $init_fields ~~ $REQUIRED_FIELDS;
+\&
+\&        ...
+\&    }
+.Ve
+.PP
+However, this only does what you mean if \f(CW$init_fields\fR is indeed a hash
+reference. The condition \f(CW\*(C`$init_fields ~~ $REQUIRED_FIELDS\*(C'\fR also allows the
+strings \f(CW"name"\fR, \f(CW"rank"\fR, \f(CW"serial_num"\fR as well as any array reference
+that contains \f(CW"name"\fR or \f(CW"rank"\fR or \f(CW"serial_num"\fR anywhere to pass
+through.
+.PP
+The smartmatch operator is most often used as the implicit operator of a
+\&\f(CW\*(C`when\*(C'\fR clause.  See the section on "Switch Statements" in perlsyn.
+.PP
+\fISmartmatching of Objects\fR
+.IX Subsection "Smartmatching of Objects"
+.PP
+To avoid relying on an object's underlying representation, if the
+smartmatch's right operand is an object that doesn't overload \f(CW\*(C`~~\*(C'\fR,
+it raises the exception "\f(CW\*(C`Smartmatching a non\-overloaded object
+breaks encapsulation\*(C'\fR".  That's because one has no business digging
+around to see whether something is "in" an object.  These are all
+illegal on objects without a \f(CW\*(C`~~\*(C'\fR overload:
+.PP
+.Vb 3
+\&    %hash ~~ $object
+\&       42 ~~ $object
+\&   "fred" ~~ $object
+.Ve
+.PP
+However, you can change the way an object is smartmatched by overloading
+the \f(CW\*(C`~~\*(C'\fR operator.  This is allowed to
+extend the usual smartmatch semantics.
+For objects that do have an \f(CW\*(C`~~\*(C'\fR overload, see overload.
+.PP
+Using an object as the left operand is allowed, although not very useful.
+Smartmatching rules take precedence over overloading, so even if the
+object in the left operand has smartmatch overloading, this will be
+ignored.  A left operand that is a non-overloaded object falls back on a
+string or numeric comparison of whatever the \f(CW\*(C`ref\*(C'\fR operator returns.  That
+means that
+.PP
+.Vb 1
+\&    $object ~~ X
+.Ve
+.PP
+does \fInot\fR invoke the overload method with \f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR as an argument.
+Instead the above table is consulted as normal, and based on the type of
+\&\f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR, overloading may or may not be invoked.  For simple strings or
+numbers, "in" becomes equivalent to this:
+.PP
+.Vb 2
+\&    $object ~~ $number          ref($object) == $number
+\&    $object ~~ $string          ref($object) eq $string
+.Ve
+.PP
+For example, this reports that the handle smells IOish
+(but please don't really do this!):
+.PP
+.Vb 5
+\&    use IO::Handle;
+\&    my $fh = IO::Handle\->new();
+\&    if ($fh ~~ /\ebIO\eb/) {
+\&        say "handle smells IOish";
+\&    }
+.Ve
+.PP
+That's because it treats \f(CW$fh\fR as a string like
+\&\f(CW"IO::Handle=GLOB(0x8039e0)"\fR, then pattern matches against that.
+.SS "Bitwise And"
+.IX Xref "operator, bitwise, and bitwise and &"
+.IX Subsection "Bitwise And"
+Binary \f(CW"&"\fR returns its operands ANDed together bit by bit.  Although no
+warning is currently raised, the result is not well defined when this operation
+is performed on operands that aren't either numbers (see
+"Integer Arithmetic") nor bitstrings (see "Bitwise String Operators").
+.PP
+Note that \f(CW"&"\fR has lower priority than relational operators, so for example
+the parentheses are essential in a test like
+.PP
+.Vb 1
+\&    print "Even\en" if ($x & 1) == 0;
+.Ve
+.PP
+If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
+\&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
+Before Perl 5.28 this feature produced a warning in the
+\&\f(CW"experimental::bitwise"\fR category.
+.SS "Bitwise Or and Exclusive Or"
+.IX Xref "operator, bitwise, or bitwise or | operator, bitwise, xor bitwise xor ^"
+.IX Subsection "Bitwise Or and Exclusive Or"
+Binary \f(CW"|"\fR returns its operands ORed together bit by bit.
+.PP
+Binary \f(CW"^"\fR returns its operands XORed together bit by bit.
+.PP
+Although no warning is currently raised, the results are not well
+defined when these operations are performed on operands that aren't either
+numbers (see "Integer Arithmetic") nor bitstrings (see "Bitwise String
+Operators").
+.PP
+Note that \f(CW"|"\fR and \f(CW"^"\fR have lower priority than relational operators, so
+for example the parentheses are essential in a test like
+.PP
+.Vb 1
+\&    print "false\en" if (8 | 2) != 10;
+.Ve
+.PP
+If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
+\&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
+Before Perl 5.28. this feature produced a warning in the
+\&\f(CW"experimental::bitwise"\fR category.
+.SS "C\-style Logical And"
+.IX Xref "&& logical and operator, logical, and"
+.IX Subsection "C-style Logical And"
+Binary \f(CW"&&"\fR performs a short-circuit logical AND operation.  That is,
+if the left operand is false, the right operand is not even evaluated.
+Scalar or list context propagates down to the right operand if it
+is evaluated.
+.SS "C\-style Logical Or"
+.IX Xref "|| operator, logical, or"
+.IX Subsection "C-style Logical Or"
+Binary \f(CW"||"\fR performs a short-circuit logical OR operation.  That is,
+if the left operand is true, the right operand is not even evaluated.
+Scalar or list context propagates down to the right operand if it
+is evaluated.
+.SS "Logical Defined-Or"
+.IX Xref "operator, logical, defined-or"
+.IX Subsection "Logical Defined-Or"
+Although it has no direct equivalent in C, Perl's \f(CW\*(C`//\*(C'\fR operator is related
+to its C\-style "or".  In fact, it's exactly the same as \f(CW\*(C`||\*(C'\fR, except that it
+tests the left hand side's definedness instead of its truth.  Thus,
+\&\f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR returns the value of \f(CW\*(C`EXPR1\*(C'\fR if it's defined,
+otherwise, the value of \f(CW\*(C`EXPR2\*(C'\fR is returned.
+(\f(CW\*(C`EXPR1\*(C'\fR is evaluated in scalar context, \f(CW\*(C`EXPR2\*(C'\fR
+in the context of \f(CW\*(C`//\*(C'\fR itself).  Usually,
+this is the same result as \f(CW\*(C`defined(EXPR1)\ ?\ EXPR1\ :\ EXPR2\*(C'\fR (except that
+the ternary-operator form can be used as a lvalue, while \f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR
+cannot).  This is very useful for
+providing default values for variables.  If you actually want to test if
+at least one of \f(CW$x\fR and \f(CW$y\fR is defined, use \f(CW\*(C`defined($x\ //\ $y)\*(C'\fR.
+.PP
+The \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`//\*(C'\fR and \f(CW\*(C`&&\*(C'\fR operators return the last value evaluated
+(unlike C's \f(CW\*(C`||\*(C'\fR and \f(CW\*(C`&&\*(C'\fR, which return 0 or 1).  Thus, a reasonably
+portable way to find out the home directory might be:
+.PP
+.Vb 4
+\&    $home =  $ENV{HOME}
+\&          // $ENV{LOGDIR}
+\&          // (getpwuid($<))[7]
+\&          // die "You\*(Aqre homeless!\en";
+.Ve
+.PP
+In particular, this means that you shouldn't use this
+for selecting between two aggregates for assignment:
+.PP
+.Vb 3
+\&    @a = @b || @c;            # This doesn\*(Aqt do the right thing
+\&    @a = scalar(@b) || @c;    # because it really means this.
+\&    @a = @b ? @b : @c;        # This works fine, though.
+.Ve
+.PP
+As alternatives to \f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR when used for
+control flow, Perl provides the \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR operators (see below).
+The short-circuit behavior is identical.  The precedence of \f(CW"and"\fR
+and \f(CW"or"\fR is much lower, however, so that you can safely use them after a
+list operator without the need for parentheses:
+.PP
+.Vb 2
+\&    unlink "alpha", "beta", "gamma"
+\&            or gripe(), next LINE;
+.Ve
+.PP
+With the C\-style operators that would have been written like this:
+.PP
+.Vb 2
+\&    unlink("alpha", "beta", "gamma")
+\&            || (gripe(), next LINE);
+.Ve
+.PP
+It would be even more readable to write that this way:
+.PP
+.Vb 4
+\&    unless(unlink("alpha", "beta", "gamma")) {
+\&        gripe();
+\&        next LINE;
+\&    }
+.Ve
+.PP
+Using \f(CW"or"\fR for assignment is unlikely to do what you want; see below.
+.SS "Range Operators"
+.IX Xref "operator, range range .. ..."
+.IX Subsection "Range Operators"
+Binary \f(CW".."\fR is the range operator, which is really two different
+operators depending on the context.  In list context, it returns a
+list of values counting (up by ones) from the left value to the right
+value.  If the left value is greater than the right value then it
+returns the empty list.  The range operator is useful for writing
+\&\f(CW\*(C`foreach\ (1..10)\*(C'\fR loops and for doing slice operations on arrays.  In
+the current implementation, no temporary array is created when the
+range operator is used as the expression in \f(CW\*(C`foreach\*(C'\fR loops, but older
+versions of Perl might burn a lot of memory when you write something
+like this:
+.PP
+.Vb 3
+\&    for (1 .. 1_000_000) {
+\&        # code
+\&    }
+.Ve
+.PP
+The range operator also works on strings, using the magical
+auto-increment, see below.
+.PP
+In scalar context, \f(CW".."\fR returns a boolean value.  The operator is
+bistable, like a flip-flop, and emulates the line-range (comma)
+operator of \fBsed\fR, \fBawk\fR, and various editors.  Each \f(CW".."\fR operator
+maintains its own boolean state, even across calls to a subroutine
+that contains it.  It is false as long as its left operand is false.
+Once the left operand is true, the range operator stays true until the
+right operand is true, \fIAFTER\fR which the range operator becomes false
+again.  It doesn't become false till the next time the range operator
+is evaluated.  It can test the right operand and become false on the
+same evaluation it became true (as in \fBawk\fR), but it still returns
+true once.  If you don't want it to test the right operand until the
+next evaluation, as in \fBsed\fR, just use three dots (\f(CW"..."\fR) instead of
+two.  In all other regards, \f(CW"..."\fR behaves just like \f(CW".."\fR does.
+.PP
+The right operand is not evaluated while the operator is in the
+"false" state, and the left operand is not evaluated while the
+operator is in the "true" state.  The precedence is a little lower
+than || and &&.  The value returned is either the empty string for
+false, or a sequence number (beginning with 1) for true.  The sequence
+number is reset for each range encountered.  The final sequence number
+in a range has the string \f(CW"E0"\fR appended to it, which doesn't affect
+its numeric value, but gives you something to search for if you want
+to exclude the endpoint.  You can exclude the beginning point by
+waiting for the sequence number to be greater than 1.
+.PP
+If either operand of scalar \f(CW".."\fR is a constant expression,
+that operand is considered true if it is equal (\f(CW\*(C`==\*(C'\fR) to the current
+input line number (the \f(CW$.\fR variable).
+.PP
+To be pedantic, the comparison is actually \f(CW\*(C`int(EXPR)\ ==\ int(EXPR)\*(C'\fR,
+but that is only an issue if you use a floating point expression; when
+implicitly using \f(CW$.\fR as described in the previous paragraph, the
+comparison is \f(CW\*(C`int(EXPR)\ ==\ int($.)\*(C'\fR which is only an issue when \f(CW$.\fR
+is set to a floating point value and you are not reading from a file.
+Furthermore, \f(CW"span"\ ..\ "spat"\fR or \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will not do what
+you want in scalar context because each of the operands are evaluated
+using their integer representation.
+.PP
+Examples:
+.PP
+As a scalar operator:
+.PP
+.Vb 2
+\&    if (101 .. 200) { print; } # print 2nd hundred lines, short for
+\&                               #  if ($. == 101 .. $. == 200) { print; }
+\&
+\&    next LINE if (1 .. /^$/);  # skip header lines, short for
+\&                               #   next LINE if ($. == 1 .. /^$/);
+\&                               # (typically in a loop labeled LINE)
+\&
+\&    s/^/> / if (/^$/ .. eof());  # quote body
+\&
+\&    # parse mail messages
+\&    while (<>) {
+\&        $in_header =   1  .. /^$/;
+\&        $in_body   = /^$/ .. eof;
+\&        if ($in_header) {
+\&            # do something
+\&        } else { # in body
+\&            # do something else
+\&        }
+\&    } continue {
+\&        close ARGV if eof;             # reset $. each file
+\&    }
+.Ve
+.PP
+Here's a simple example to illustrate the difference between
+the two range operators:
+.PP
+.Vb 4
+\&    @lines = ("   \- Foo",
+\&              "01 \- Bar",
+\&              "1  \- Baz",
+\&              "   \- Quux");
+\&
+\&    foreach (@lines) {
+\&        if (/0/ .. /1/) {
+\&            print "$_\en";
+\&        }
+\&    }
+.Ve
+.PP
+This program will print only the line containing "Bar".  If
+the range operator is changed to \f(CW\*(C`...\*(C'\fR, it will also print the
+"Baz" line.
+.PP
+And now some examples as a list operator:
+.PP
+.Vb 3
+\&    for (101 .. 200) { print }      # print $_ 100 times
+\&    @foo = @foo[0 .. $#foo];        # an expensive no\-op
+\&    @foo = @foo[$#foo\-4 .. $#foo];  # slice last 5 items
+.Ve
+.PP
+Because each operand is evaluated in integer form, \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will
+return two elements in list context.
+.PP
+.Vb 1
+\&    @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
+.Ve
+.PP
+The range operator in list context can make use of the magical
+auto-increment algorithm if both operands are strings, subject to the
+following rules:
+.IP \(bu 4
+With one exception (below), if both strings look like numbers to Perl,
+the magic increment will not be applied, and the strings will be treated
+as numbers (more specifically, integers) instead.
+.Sp
+For example, \f(CW"\-2".."2"\fR is the same as \f(CW\-2..2\fR, and
+\&\f(CW"2.18".."3.14"\fR produces \f(CW\*(C`2, 3\*(C'\fR.
+.IP \(bu 4
+The exception to the above rule is when the left-hand string begins with
+\&\f(CW0\fR and is longer than one character, in this case the magic increment
+\&\fIwill\fR be applied, even though strings like \f(CW"01"\fR would normally look
+like a number to Perl.
+.Sp
+For example, \f(CW"01".."04"\fR produces \f(CW"01", "02", "03", "04"\fR, and
+\&\f(CW"00".."\-1"\fR produces \f(CW"00"\fR through \f(CW"99"\fR \- this may seem
+surprising, but see the following rules for why it works this way.
+To get dates with leading zeros, you can say:
+.Sp
+.Vb 2
+\&    @z2 = ("01" .. "31");
+\&    print $z2[$mday];
+.Ve
+.Sp
+If you want to force strings to be interpreted as numbers, you could say
+.Sp
+.Vb 1
+\&    @numbers = ( 0+$first .. 0+$last );
+.Ve
+.Sp
+\&\fBNote:\fR In Perl versions 5.30 and below, \fIany\fR string on the left-hand
+side beginning with \f(CW"0"\fR, including the string \f(CW"0"\fR itself, would
+cause the magic string increment behavior. This means that on these Perl
+versions, \f(CW"0".."\-1"\fR would produce \f(CW"0"\fR through \f(CW"99"\fR, which was
+inconsistent with \f(CW\*(C`0..\-1\*(C'\fR, which produces the empty list. This also means
+that \f(CW"0".."9"\fR now produces a list of integers instead of a list of
+strings.
+.IP \(bu 4
+If the initial value specified isn't part of a magical increment
+sequence (that is, a non-empty string matching \f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR),
+only the initial value will be returned.
+.Sp
+For example, \f(CW"ax".."az"\fR produces \f(CW"ax", "ay", "az"\fR, but
+\&\f(CW"*x".."az"\fR produces only \f(CW"*x"\fR.
+.IP \(bu 4
+For other initial values that are strings that do follow the rules of the
+magical increment, the corresponding sequence will be returned.
+.Sp
+For example, you can say
+.Sp
+.Vb 1
+\&    @alphabet = ("A" .. "Z");
+.Ve
+.Sp
+to get all normal letters of the English alphabet, or
+.Sp
+.Vb 1
+\&    $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
+.Ve
+.Sp
+to get a hexadecimal digit.
+.IP \(bu 4
+If the final value specified is not in the sequence that the magical
+increment would produce, the sequence goes until the next value would
+be longer than the final value specified. If the length of the final
+string is shorter than the first, the empty list is returned.
+.Sp
+For example, \f(CW"a".."\-\-"\fR is the same as \f(CW"a".."zz"\fR, \f(CW"0".."xx"\fR
+produces \f(CW"0"\fR through \f(CW"99"\fR, and \f(CW"aaa".."\-\-"\fR returns the empty
+list.
+.PP
+As of Perl 5.26, the list-context range operator on strings works as expected
+in the scope of \f(CW"use\ feature\ \*(Aqunicode_strings"\fR. In previous versions, and outside the scope of
+that feature, it exhibits "The "Unicode Bug"" in perlunicode: its behavior
+depends on the internal encoding of the range endpoint.
+.PP
+Because the magical increment only works on non-empty strings matching
+\&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the following will only return an alpha:
+.PP
+.Vb 2
+\&    use charnames "greek";
+\&    my @greek_small =  ("\eN{alpha}" .. "\eN{omega}");
+.Ve
+.PP
+To get the 25 traditional lowercase Greek letters, including both sigmas,
+you could use this instead:
+.PP
+.Vb 5
+\&    use charnames "greek";
+\&    my @greek_small =  map { chr } ( ord("\eN{alpha}")
+\&                                        ..
+\&                                     ord("\eN{omega}")
+\&                                   );
+.Ve
+.PP
+However, because there are \fImany\fR other lowercase Greek characters than
+just those, to match lowercase Greek characters in a regular expression,
+you could use the pattern \f(CW\*(C`/(?:(?=\ep{Greek})\ep{Lower})+/\*(C'\fR (or the
+experimental feature \f(CW\*(C`/(?[\ \ep{Greek}\ &\ \ep{Lower}\ ])+/\*(C'\fR).
+.SS "Conditional Operator"
+.IX Xref "operator, conditional operator, ternary ternary ?:"
+.IX Subsection "Conditional Operator"
+Ternary \f(CW"?:"\fR is the conditional operator, just as in C.  It works much
+like an if-then-else.  If the argument before the \f(CW\*(C`?\*(C'\fR is true, the
+argument before the \f(CW\*(C`:\*(C'\fR is returned, otherwise the argument after the
+\&\f(CW\*(C`:\*(C'\fR is returned.  For example:
+.PP
+.Vb 2
+\&    printf "I have %d dog%s.\en", $n,
+\&            ($n == 1) ? "" : "s";
+.Ve
+.PP
+Scalar or list context propagates downward into the 2nd
+or 3rd argument, whichever is selected.
+.PP
+.Vb 3
+\&    $x = $ok ? $y : $z;  # get a scalar
+\&    @x = $ok ? @y : @z;  # get an array
+\&    $x = $ok ? @y : @z;  # oops, that\*(Aqs just a count!
+.Ve
+.PP
+The operator may be assigned to if both the 2nd and 3rd arguments are
+legal lvalues (meaning that you can assign to them):
+.PP
+.Vb 1
+\&    ($x_or_y ? $x : $y) = $z;
+.Ve
+.PP
+Because this operator produces an assignable result, using assignments
+without parentheses will get you in trouble.  For example, this:
+.PP
+.Vb 1
+\&    $x % 2 ? $x += 10 : $x += 2
+.Ve
+.PP
+Really means this:
+.PP
+.Vb 1
+\&    (($x % 2) ? ($x += 10) : $x) += 2
+.Ve
+.PP
+Rather than this:
+.PP
+.Vb 1
+\&    ($x % 2) ? ($x += 10) : ($x += 2)
+.Ve
+.PP
+That should probably be written more simply as:
+.PP
+.Vb 1
+\&    $x += ($x % 2) ? 10 : 2;
+.Ve
+.SS "Assignment Operators"
+.IX Xref "assignment operator, assignment = **= += *= &= <<= &&= -= = |= >>= ||= = .= %= ^= x= &.= |.= ^.="
+.IX Subsection "Assignment Operators"
+\&\f(CW"="\fR is the ordinary assignment operator.
+.PP
+Assignment operators work as in C.  That is,
+.PP
+.Vb 1
+\&    $x += 2;
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\&    $x = $x + 2;
+.Ve
+.PP
+although without duplicating any side effects that dereferencing the lvalue
+might trigger, such as from \f(CWtie()\fR.  Other assignment operators work similarly.
+The following are recognized:
+.PP
+.Vb 4
+\&    **=    +=    *=    &=    &.=    <<=    &&=
+\&           \-=    /=    |=    |.=    >>=    ||=
+\&           .=    %=    ^=    ^.=           //=
+\&                 x=
+.Ve
+.PP
+Although these are grouped by family, they all have the precedence
+of assignment.  These combined assignment operators can only operate on
+scalars, whereas the ordinary assignment operator can assign to arrays,
+hashes, lists and even references.  (See "Context"
+and "List value constructors" in perldata, and "Assigning to
+References" in perlref.)
+.PP
+Unlike in C, the scalar assignment operator produces a valid lvalue.
+Modifying an assignment is equivalent to doing the assignment and
+then modifying the variable that was assigned to.  This is useful
+for modifying a copy of something, like this:
+.PP
+.Vb 1
+\&    ($tmp = $global) =~ tr/13579/24680/;
+.Ve
+.PP
+Although as of 5.14, that can be also be accomplished this way:
+.PP
+.Vb 2
+\&    use v5.14;
+\&    $tmp = ($global =~  tr/13579/24680/r);
+.Ve
+.PP
+Likewise,
+.PP
+.Vb 1
+\&    ($x += 2) *= 3;
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 2
+\&    $x += 2;
+\&    $x *= 3;
+.Ve
+.PP
+Similarly, a list assignment in list context produces the list of
+lvalues assigned to, and a list assignment in scalar context returns
+the number of elements produced by the expression on the right hand
+side of the assignment.
+.PP
+The three dotted bitwise assignment operators (\f(CW\*(C`&.=\*(C'\fR \f(CW\*(C`|.=\*(C'\fR \f(CW\*(C`^.=\*(C'\fR) are new in
+Perl 5.22.  See "Bitwise String Operators".
+.SS "Comma Operator"
+.IX Xref "comma operator, comma ,"
+.IX Subsection "Comma Operator"
+Binary \f(CW","\fR is the comma operator.  In scalar context it evaluates
+its left argument, throws that value away, then evaluates its right
+argument and returns that value.  This is just like C's comma operator.
+.PP
+In list context, it's just the list argument separator, and inserts
+both its arguments into the list.  These arguments are also evaluated
+from left to right.
+.PP
+The \f(CW\*(C`=>\*(C'\fR operator (sometimes pronounced "fat comma") is a synonym
+for the comma except that it causes a
+word on its left to be interpreted as a string if it begins with a letter
+or underscore and is composed only of letters, digits and underscores.
+This includes operands that might otherwise be interpreted as operators,
+constants, single number v\-strings or function calls.  If in doubt about
+this behavior, the left operand can be quoted explicitly.
+.PP
+Otherwise, the \f(CW\*(C`=>\*(C'\fR operator behaves exactly as the comma operator
+or list argument separator, according to context.
+.PP
+For example:
+.PP
+.Vb 1
+\&    use constant FOO => "something";
+\&
+\&    my %h = ( FOO => 23 );
+.Ve
+.PP
+is equivalent to:
+.PP
+.Vb 1
+\&    my %h = ("FOO", 23);
+.Ve
+.PP
+It is \fINOT\fR:
+.PP
+.Vb 1
+\&    my %h = ("something", 23);
+.Ve
+.PP
+The \f(CW\*(C`=>\*(C'\fR operator is helpful in documenting the correspondence
+between keys and values in hashes, and other paired elements in lists.
+.PP
+.Vb 2
+\&    %hash = ( $key => $value );
+\&    login( $username => $password );
+.Ve
+.PP
+The special quoting behavior ignores precedence, and hence may apply to
+\&\fIpart\fR of the left operand:
+.PP
+.Vb 1
+\&    print time.shift => "bbb";
+.Ve
+.PP
+That example prints something like \f(CW"1314363215shiftbbb"\fR, because the
+\&\f(CW\*(C`=>\*(C'\fR implicitly quotes the \f(CW\*(C`shift\*(C'\fR immediately on its left, ignoring
+the fact that \f(CW\*(C`time.shift\*(C'\fR is the entire left operand.
+.SS "List Operators (Rightward)"
+.IX Xref "operator, list, rightward list operator"
+.IX Subsection "List Operators (Rightward)"
+On the right side of a list operator, the comma has very low precedence,
+such that it controls all comma-separated expressions found there.
+The only operators with lower precedence are the logical operators
+\&\f(CW"and"\fR, \f(CW"or"\fR, and \f(CW"not"\fR, which may be used to evaluate calls to list
+operators without the need for parentheses:
+.PP
+.Vb 2
+\&    open HANDLE, "< :encoding(UTF\-8)", "filename"
+\&        or die "Can\*(Aqt open: $!\en";
+.Ve
+.PP
+However, some people find that code harder to read than writing
+it with parentheses:
+.PP
+.Vb 2
+\&    open(HANDLE, "< :encoding(UTF\-8)", "filename")
+\&        or die "Can\*(Aqt open: $!\en";
+.Ve
+.PP
+in which case you might as well just use the more customary \f(CW"||"\fR operator:
+.PP
+.Vb 2
+\&    open(HANDLE, "< :encoding(UTF\-8)", "filename")
+\&        || die "Can\*(Aqt open: $!\en";
+.Ve
+.PP
+See also discussion of list operators in "Terms and List Operators (Leftward)".
+.SS "Logical Not"
+.IX Xref "operator, logical, not not"
+.IX Subsection "Logical Not"
+Unary \f(CW"not"\fR returns the logical negation of the expression to its right.
+It's the equivalent of \f(CW"!"\fR except for the very low precedence.
+.SS "Logical And"
+.IX Xref "operator, logical, and and"
+.IX Subsection "Logical And"
+Binary \f(CW"and"\fR returns the logical conjunction of the two surrounding
+expressions.  It's equivalent to \f(CW\*(C`&&\*(C'\fR except for the very low
+precedence.  This means that it short-circuits: the right
+expression is evaluated only if the left expression is true.
+.SS "Logical or and Exclusive Or"
+.IX Xref "operator, logical, or operator, logical, xor operator, logical, exclusive or or xor"
+.IX Subsection "Logical or and Exclusive Or"
+Binary \f(CW"or"\fR returns the logical disjunction of the two surrounding
+expressions.  It's equivalent to \f(CW\*(C`||\*(C'\fR except for the very low precedence.
+This makes it useful for control flow:
+.PP
+.Vb 1
+\&    print FH $data              or die "Can\*(Aqt write to FH: $!";
+.Ve
+.PP
+This means that it short-circuits: the right expression is evaluated
+only if the left expression is false.  Due to its precedence, you must
+be careful to avoid using it as replacement for the \f(CW\*(C`||\*(C'\fR operator.
+It usually works out better for flow control than in assignments:
+.PP
+.Vb 3
+\&    $x = $y or $z;              # bug: this is wrong
+\&    ($x = $y) or $z;            # really means this
+\&    $x = $y || $z;              # better written this way
+.Ve
+.PP
+However, when it's a list-context assignment and you're trying to use
+\&\f(CW\*(C`||\*(C'\fR for control flow, you probably need \f(CW"or"\fR so that the assignment
+takes higher precedence.
+.PP
+.Vb 2
+\&    @info = stat($file) || die;     # oops, scalar sense of stat!
+\&    @info = stat($file) or die;     # better, now @info gets its due
+.Ve
+.PP
+Then again, you could always use parentheses.
+.PP
+Binary \f(CW"xor"\fR returns the exclusive-OR of the two surrounding expressions.
+It cannot short-circuit (of course).
+.PP
+There is no low precedence operator for defined-OR.
+.SS "C Operators Missing From Perl"
+.IX Xref "operator, missing from perl & * typecasting (TYPE)"
+.IX Subsection "C Operators Missing From Perl"
+Here is what C has that Perl doesn't:
+.IP "unary &" 8
+.IX Item "unary &"
+Address-of operator.  (But see the \f(CW"\e"\fR operator for taking a reference.)
+.IP "unary *" 8
+.IX Item "unary *"
+Dereference-address operator.  (Perl's prefix dereferencing
+operators are typed: \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`%\*(C'\fR, and \f(CW\*(C`&\*(C'\fR.)
+.IP (TYPE) 8
+.IX Item "(TYPE)"
+Type-casting operator.
+.SS "Quote and Quote-like Operators"
+.IX Xref "operator, quote operator, quote-like q qq qx qw m qr s tr ' '' "" """" ` `` << escape sequence escape"
+.IX Subsection "Quote and Quote-like Operators"
+While we usually think of quotes as literal values, in Perl they
+function as operators, providing various kinds of interpolating and
+pattern matching capabilities.  Perl provides customary quote characters
+for these behaviors, but also provides a way for you to choose your
+quote character for any of them.  In the following table, a \f(CW\*(C`{}\*(C'\fR represents
+any pair of delimiters you choose.
+.PP
+.Vb 11
+\&    Customary  Generic        Meaning        Interpolates
+\&        \*(Aq\*(Aq       q{}          Literal             no
+\&        ""      qq{}          Literal             yes
+\&        \`\`      qx{}          Command             yes*
+\&                qw{}         Word list            no
+\&        //       m{}       Pattern match          yes*
+\&                qr{}          Pattern             yes*
+\&                 s{}{}      Substitution          yes*
+\&                tr{}{}    Transliteration         no (but see below)
+\&                 y{}{}    Transliteration         no (but see below)
+\&        <<EOF                 here\-doc            yes*
+\&
+\&        * unless the delimiter is \*(Aq\*(Aq.
+.Ve
+.PP
+Non-bracketing delimiters use the same character fore and aft, but the four
+sorts of ASCII brackets (round, angle, square, curly) all nest, which means
+that
+.PP
+.Vb 1
+\&    q{foo{bar}baz}
+.Ve
+.PP
+is the same as
+.PP
+.Vb 1
+\&    \*(Aqfoo{bar}baz\*(Aq
+.Ve
+.PP
+Note, however, that this does not always work for quoting Perl code:
+.PP
+.Vb 1
+\&    $s = q{ if($x eq "}") ... }; # WRONG
+.Ve
+.PP
+is a syntax error.  The \f(CW\*(C`Text::Balanced\*(C'\fR module (standard as of v5.8,
+and from CPAN before then) is able to do this properly.
+.PP
+There can (and in some cases, must) be whitespace between the operator
+and the quoting
+characters, except when \f(CW\*(C`#\*(C'\fR is being used as the quoting character.
+\&\f(CW\*(C`q#foo#\*(C'\fR is parsed as the string \f(CW\*(C`foo\*(C'\fR, while \f(CW\*(C`q\ #foo#\*(C'\fR is the
+operator \f(CW\*(C`q\*(C'\fR followed by a comment.  Its argument will be taken
+from the next line.  This allows you to write:
+.PP
+.Vb 2
+\&    s {foo}  # Replace foo
+\&      {bar}  # with bar.
+.Ve
+.PP
+The cases where whitespace must be used are when the quoting character
+is a word character (meaning it matches \f(CW\*(C`/\ew/\*(C'\fR):
+.PP
+.Vb 2
+\&    q XfooX # Works: means the string \*(Aqfoo\*(Aq
+\&    qXfooX  # WRONG!
+.Ve
+.PP
+The following escape sequences are available in constructs that interpolate,
+and in transliterations whose delimiters aren't single quotes (\f(CW"\*(Aq"\fR).
+In all the ones with braces, any number of blanks and/or tabs adjoining
+and within the braces are allowed (and ignored).
+.IX Xref "\\t \\n \\r \\f \\b \\a \\e \\x \\0 \\c \\N \\N{} \\o{}"
+.PP
+.Vb 10
+\&    Sequence     Note  Description
+\&    \et                  tab               (HT, TAB)
+\&    \en                  newline           (NL)
+\&    \er                  return            (CR)
+\&    \ef                  form feed         (FF)
+\&    \eb                  backspace         (BS)
+\&    \ea                  alarm (bell)      (BEL)
+\&    \ee                  escape            (ESC)
+\&    \ex{263A}     [1,8]  hex char          (example shown: SMILEY)
+\&    \ex{ 263A }          Same, but shows optional blanks inside and
+\&                        adjoining the braces
+\&    \ex1b         [2,8]  restricted range hex char (example: ESC)
+\&    \eN{name}     [3]    named Unicode character or character sequence
+\&    \eN{U+263D}   [4,8]  Unicode character (example: FIRST QUARTER MOON)
+\&    \ec[          [5]    control char      (example: chr(27))
+\&    \eo{23072}    [6,8]  octal char        (example: SMILEY)
+\&    \e033         [7,8]  restricted range octal char  (example: ESC)
+.Ve
+.PP
+Note that any escape sequence using braces inside interpolated
+constructs may have optional blanks (tab or space characters) adjoining
+with and inside of the braces, as illustrated above by the second
+\&\f(CW\*(C`\ex{\ }\*(C'\fR example.
+.IP [1] 4
+.IX Item "[1]"
+The result is the character specified by the hexadecimal number between
+the braces.  See "[8]" below for details on which character.
+.Sp
+Blanks (tab or space characters) may separate the number from either or
+both of the braces.
+.Sp
+Otherwise, only hexadecimal digits are valid between the braces.  If an
+invalid character is encountered, a warning will be issued and the
+invalid character and all subsequent characters (valid or invalid)
+within the braces will be discarded.
+.Sp
+If there are no valid digits between the braces, the generated character is
+the NULL character (\f(CW\*(C`\ex{00}\*(C'\fR).  However, an explicit empty brace (\f(CW\*(C`\ex{}\*(C'\fR)
+will not cause a warning (currently).
+.IP [2] 4
+.IX Item "[2]"
+The result is the character specified by the hexadecimal number in the range
+0x00 to 0xFF.  See "[8]" below for details on which character.
+.Sp
+Only hexadecimal digits are valid following \f(CW\*(C`\ex\*(C'\fR.  When \f(CW\*(C`\ex\*(C'\fR is followed
+by fewer than two valid digits, any valid digits will be zero-padded.  This
+means that \f(CW\*(C`\ex7\*(C'\fR will be interpreted as \f(CW\*(C`\ex07\*(C'\fR, and a lone \f(CW"\ex"\fR will be
+interpreted as \f(CW\*(C`\ex00\*(C'\fR.  Except at the end of a string, having fewer than
+two valid digits will result in a warning.  Note that although the warning
+says the illegal character is ignored, it is only ignored as part of the
+escape and will still be used as the subsequent character in the string.
+For example:
+.Sp
+.Vb 5
+\&  Original    Result    Warns?
+\&  "\ex7"       "\ex07"    no
+\&  "\ex"        "\ex00"    no
+\&  "\ex7q"      "\ex07q"   yes
+\&  "\exq"       "\ex00q"   yes
+.Ve
+.IP [3] 4
+.IX Item "[3]"
+The result is the Unicode character or character sequence given by \fIname\fR.
+See charnames.
+.IP [4] 4
+.IX Item "[4]"
+\&\f(CW\*(C`\eN{U+\fR\f(CIhexadecimal\ number\fR\f(CW}\*(C'\fR means the Unicode character whose Unicode code
+point is \fIhexadecimal number\fR.
+.IP [5] 4
+.IX Item "[5]"
+The character following \f(CW\*(C`\ec\*(C'\fR is mapped to some other character as shown in the
+table:
+.Sp
+.Vb 10
+\& Sequence   Value
+\&   \ec@      chr(0)
+\&   \ecA      chr(1)
+\&   \eca      chr(1)
+\&   \ecB      chr(2)
+\&   \ecb      chr(2)
+\&   ...
+\&   \ecZ      chr(26)
+\&   \ecz      chr(26)
+\&   \ec[      chr(27)
+\&                     # See below for chr(28)
+\&   \ec]      chr(29)
+\&   \ec^      chr(30)
+\&   \ec_      chr(31)
+\&   \ec?      chr(127) # (on ASCII platforms; see below for link to
+\&                     #  EBCDIC discussion)
+.Ve
+.Sp
+In other words, it's the character whose code point has had 64 xor'd with
+its uppercase.  \f(CW\*(C`\ec?\*(C'\fR is DELETE on ASCII platforms because
+\&\f(CW\*(C`ord("?")\ ^\ 64\*(C'\fR is 127, and
+\&\f(CW\*(C`\ec@\*(C'\fR is NULL because the ord of \f(CW"@"\fR is 64, so xor'ing 64 itself produces 0.
+.Sp
+Also, \f(CW\*(C`\ec\e\fR\f(CIX\fR\f(CW\*(C'\fR yields \f(CW\*(C`\ chr(28)\ .\ "\fR\f(CIX\fR\f(CW"\*(C'\fR for any \fIX\fR, but cannot come at the
+end of a string, because the backslash would be parsed as escaping the end
+quote.
+.Sp
+On ASCII platforms, the resulting characters from the list above are the
+complete set of ASCII controls.  This isn't the case on EBCDIC platforms; see
+"OPERATOR DIFFERENCES" in perlebcdic for a full discussion of the
+differences between these for ASCII versus EBCDIC platforms.
+.Sp
+Use of any other character following the \f(CW"c"\fR besides those listed above is
+discouraged, and as of Perl v5.20, the only characters actually allowed
+are the printable ASCII ones, minus the left brace \f(CW"{"\fR.  What happens
+for any of the allowed other characters is that the value is derived by
+xor'ing with the seventh bit, which is 64, and a warning raised if
+enabled.  Using the non-allowed characters generates a fatal error.
+.Sp
+To get platform independent controls, you can use \f(CW\*(C`\eN{...}\*(C'\fR.
+.IP [6] 4
+.IX Item "[6]"
+The result is the character specified by the octal number between the braces.
+See "[8]" below for details on which character.
+.Sp
+Blanks (tab or space characters) may separate the number from either or
+both of the braces.
+.Sp
+Otherwise, if a character that isn't an octal digit is encountered, a
+warning is raised, and the value is based on the octal digits before it,
+discarding it and all following characters up to the closing brace.  It
+is a fatal error if there are no octal digits at all.
+.IP [7] 4
+.IX Item "[7]"
+The result is the character specified by the three-digit octal number in the
+range 000 to 777 (but best to not use above 077, see next paragraph).  See
+"[8]" below for details on which character.
+.Sp
+Some contexts allow 2 or even 1 digit, but any usage without exactly
+three digits, the first being a zero, may give unintended results.  (For
+example, in a regular expression it may be confused with a backreference;
+see "Octal escapes" in perlrebackslash.)  Starting in Perl 5.14, you may
+use \f(CW\*(C`\eo{}\*(C'\fR instead, which avoids all these problems.  Otherwise, it is best to
+use this construct only for ordinals \f(CW\*(C`\e077\*(C'\fR and below, remembering to pad to
+the left with zeros to make three digits.  For larger ordinals, either use
+\&\f(CW\*(C`\eo{}\*(C'\fR, or convert to something else, such as to hex and use \f(CW\*(C`\eN{U+}\*(C'\fR
+(which is portable between platforms with different character sets) or
+\&\f(CW\*(C`\ex{}\*(C'\fR instead.
+.IP [8] 4
+.IX Item "[8]"
+Several constructs above specify a character by a number.  That number
+gives the character's position in the character set encoding (indexed from 0).
+This is called synonymously its ordinal, code position, or code point.  Perl
+works on platforms that have a native encoding currently of either ASCII/Latin1
+or EBCDIC, each of which allow specification of 256 characters.  In general, if
+the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
+native encoding.  If the number is 256 (0x100, 0400) or above, Perl interprets
+it as a Unicode code point and the result is the corresponding Unicode
+character.  For example \f(CW\*(C`\ex{50}\*(C'\fR and \f(CW\*(C`\eo{120}\*(C'\fR both are the number 80 in
+decimal, which is less than 256, so the number is interpreted in the native
+character set encoding.  In ASCII the character in the 80th position (indexed
+from 0) is the letter \f(CW"P"\fR, and in EBCDIC it is the ampersand symbol \f(CW"&"\fR.
+\&\f(CW\*(C`\ex{100}\*(C'\fR and \f(CW\*(C`\eo{400}\*(C'\fR are both 256 in decimal, so the number is interpreted
+as a Unicode code point no matter what the native encoding is.  The name of the
+character in the 256th position (indexed by 0) in Unicode is
+\&\f(CW\*(C`LATIN CAPITAL LETTER A WITH MACRON\*(C'\fR.
+.Sp
+An exception to the above rule is that \f(CW\*(C`\eN{U+\fR\f(CIhex\ number\fR\f(CW}\*(C'\fR is
+always interpreted as a Unicode code point, so that \f(CW\*(C`\eN{U+0050}\*(C'\fR is \f(CW"P"\fR even
+on EBCDIC platforms.
+.PP
+\&\fBNOTE\fR: Unlike C and other languages, Perl has no \f(CW\*(C`\ev\*(C'\fR escape sequence for
+the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
+use \f(CW\*(C`\eN{VT}\*(C'\fR, \f(CW\*(C`\eck\*(C'\fR, \f(CW\*(C`\eN{U+0b}\*(C'\fR, or \f(CW\*(C`\ex0b\*(C'\fR.  (\f(CW\*(C`\ev\*(C'\fR
+does have meaning in regular expression patterns in Perl, see perlre.)
+.PP
+The following escape sequences are available in constructs that interpolate,
+but not in transliterations.
+.IX Xref "\\l \\u \\L \\U \\E \\Q \\F"
+.PP
+.Vb 9
+\&    \el          lowercase next character only
+\&    \eu          titlecase (not uppercase!) next character only
+\&    \eL          lowercase all characters till \eE or end of string
+\&    \eU          uppercase all characters till \eE or end of string
+\&    \eF          foldcase all characters till \eE or end of string
+\&    \eQ          quote (disable) pattern metacharacters till \eE or
+\&                end of string
+\&    \eE          end either case modification or quoted section
+\&                (whichever was last seen)
+.Ve
+.PP
+See "quotemeta" in perlfunc for the exact definition of characters that
+are quoted by \f(CW\*(C`\eQ\*(C'\fR.
+.PP
+\&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, and \f(CW\*(C`\eQ\*(C'\fR can stack, in which case you need one
+\&\f(CW\*(C`\eE\*(C'\fR for each.  For example:
+.PP
+.Vb 2
+\& say "This \eQquoting \eubusiness \eUhere isn\*(Aqt quite\eE done yet,\eE is it?";
+\& This quoting\e Business\e HERE\e ISN\e\*(AqT\e QUITE\e done\e yet\e, is it?
+.Ve
+.PP
+If a \f(CW\*(C`use\ locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect (see
+perllocale), the case map used by \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is
+taken from the current locale.  If Unicode (for example, \f(CW\*(C`\eN{}\*(C'\fR or code
+points of 0x100 or beyond) is being used, the case map used by \f(CW\*(C`\el\*(C'\fR,
+\&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is as defined by Unicode.  That means that
+case-mapping a single character can sometimes produce a sequence of
+several characters.
+Under \f(CW\*(C`use\ locale\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR produces the same results as \f(CW\*(C`\eL\*(C'\fR
+for all locales but a UTF\-8 one, where it instead uses the Unicode
+definition.
+.PP
+All systems use the virtual \f(CW"\en"\fR to represent a line terminator,
+called a "newline".  There is no such thing as an unvarying, physical
+newline character.  It is only an illusion that the operating system,
+device drivers, C libraries, and Perl all conspire to preserve.  Not all
+systems read \f(CW"\er"\fR as ASCII CR and \f(CW"\en"\fR as ASCII LF.  For example,
+on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
+and on systems without a line terminator,
+printing \f(CW"\en"\fR might emit no actual data.  In general, use \f(CW"\en"\fR when
+you mean a "newline" for your system, but use the literal ASCII when you
+need an exact character.  For example, most networking protocols expect
+and prefer a CR+LF (\f(CW"\e015\e012"\fR or \f(CW"\ecM\ecJ"\fR) for line terminators,
+and although they often accept just \f(CW"\e012"\fR, they seldom tolerate just
+\&\f(CW"\e015"\fR.  If you get in the habit of using \f(CW"\en"\fR for networking,
+you may be burned some day.
+.IX Xref "newline line terminator eol end of line \\n \\r \\r\\n"
+.PP
+For constructs that do interpolate, variables beginning with "\f(CW\*(C`$\*(C'\fR"
+or "\f(CW\*(C`@\*(C'\fR" are interpolated.  Subscripted variables such as \f(CW$a[3]\fR or
+\&\f(CW\*(C`$href\->{key}[0]\*(C'\fR are also interpolated, as are array and hash slices.
+But method calls such as \f(CW\*(C`$obj\->meth\*(C'\fR are not.
+.PP
+Interpolating an array or slice interpolates the elements in order,
+separated by the value of \f(CW$"\fR, so is equivalent to interpolating
+\&\f(CW\*(C`join\ $",\ @array\*(C'\fR.  "Punctuation" arrays such as \f(CW\*(C`@*\*(C'\fR are usually
+interpolated only if the name is enclosed in braces \f(CW\*(C`@{*}\*(C'\fR, but the
+arrays \f(CW@_\fR, \f(CW\*(C`@+\*(C'\fR, and \f(CW\*(C`@\-\*(C'\fR are interpolated even without braces.
+.PP
+For double-quoted strings, the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after
+interpolation and escapes are processed.
+.PP
+.Vb 1
+\&    "abc\eQfoo\etbar$s\eExyz"
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\&    "abc" . quotemeta("foo\etbar$s") . "xyz"
+.Ve
+.PP
+For the pattern of regex operators (\f(CW\*(C`qr//\*(C'\fR, \f(CW\*(C`m//\*(C'\fR and \f(CW\*(C`s///\*(C'\fR),
+the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after interpolation is processed,
+but before escapes are processed.  This allows the pattern to match
+literally (except for \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR).  For example, the following matches:
+.PP
+.Vb 1
+\&    \*(Aq\es\et\*(Aq =~ /\eQ\es\et/
+.Ve
+.PP
+Because \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR trigger interpolation, you'll need to use something
+like \f(CW\*(C`/\eQuser\eE\e@\eQhost/\*(C'\fR to match them literally.
+.PP
+Patterns are subject to an additional level of interpretation as a
+regular expression.  This is done as a second pass, after variables are
+interpolated, so that regular expressions may be incorporated into the
+pattern from the variables.  If this is not what you want, use \f(CW\*(C`\eQ\*(C'\fR to
+interpolate a variable literally.
+.PP
+Apart from the behavior described above, Perl does not expand
+multiple levels of interpolation.  In particular, contrary to the
+expectations of shell programmers, back-quotes do \fINOT\fR interpolate
+within double quotes, nor do single quotes impede evaluation of
+variables when used within double quotes.
+.SS "Regexp Quote-Like Operators"
+.IX Xref "operator, regexp"
+.IX Subsection "Regexp Quote-Like Operators"
+Here are the quote-like operators that apply to pattern
+matching and related activities.
+.ie n .IP """qr/\fISTRING\fR/msixpodualn""" 8
+.el .IP \f(CWqr/\fR\f(CISTRING\fR\f(CW/msixpodualn\fR 8
+.IX Xref "qr i m o s x p"
+.IX Item "qr/STRING/msixpodualn"
+This operator quotes (and possibly compiles) its \fISTRING\fR as a regular
+expression.  \fISTRING\fR is interpolated the same way as \fIPATTERN\fR
+in \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR.  If \f(CW"\*(Aq"\fR is used as the delimiter, no variable
+interpolation is done.  Returns a Perl value which may be used instead of the
+corresponding \f(CW\*(C`/\fR\f(CISTRING\fR\f(CW/msixpodualn\*(C'\fR expression.  The returned value is a
+normalized version of the original pattern.  It magically differs from
+a string containing the same characters: \f(CWref(qr/x/)\fR returns "Regexp";
+however, dereferencing it is not well defined (you currently get the
+normalized version of the original pattern, but this may change).
+.Sp
+For example,
+.Sp
+.Vb 3
+\&    $rex = qr/my.STRING/is;
+\&    print $rex;                 # prints (?si\-xm:my.STRING)
+\&    s/$rex/foo/;
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 1
+\&    s/my.STRING/foo/is;
+.Ve
+.Sp
+The result may be used as a subpattern in a match:
+.Sp
+.Vb 5
+\&    $re = qr/$pattern/;
+\&    $string =~ /foo${re}bar/;   # can be interpolated in other
+\&                                # patterns
+\&    $string =~ $re;             # or used standalone
+\&    $string =~ /$re/;           # or this way
+.Ve
+.Sp
+Since Perl may compile the pattern at the moment of execution of the \f(CWqr()\fR
+operator, using \f(CWqr()\fR may have speed advantages in some situations,
+notably if the result of \f(CWqr()\fR is used standalone:
+.Sp
+.Vb 11
+\&    sub match {
+\&        my $patterns = shift;
+\&        my @compiled = map qr/$_/i, @$patterns;
+\&        grep {
+\&            my $success = 0;
+\&            foreach my $pat (@compiled) {
+\&                $success = 1, last if /$pat/;
+\&            }
+\&            $success;
+\&        } @_;
+\&    }
+.Ve
+.Sp
+Precompilation of the pattern into an internal representation at
+the moment of \f(CWqr()\fR avoids the need to recompile the pattern every
+time a match \f(CW\*(C`/$pat/\*(C'\fR is attempted.  (Perl has many other internal
+optimizations, but none would be triggered in the above example if
+we did not use \f(CWqr()\fR operator.)
+.Sp
+Options (specified by the following modifiers) are:
+.Sp
+.Vb 10
+\&    m   Treat string as multiple lines.
+\&    s   Treat string as single line. (Make . match a newline)
+\&    i   Do case\-insensitive pattern matching.
+\&    x   Use extended regular expressions; specifying two
+\&        x\*(Aqs means \et and the SPACE character are ignored within
+\&        square\-bracketed character classes
+\&    p   When matching preserve a copy of the matched string so
+\&        that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
+\&        defined (ignored starting in v5.20 as these are always
+\&        defined starting in that release)
+\&    o   Compile pattern only once.
+\&    a   ASCII\-restrict: Use ASCII for \ed, \es, \ew and [[:posix:]]
+\&        character classes; specifying two a\*(Aqs adds the further
+\&        restriction that no ASCII character will match a
+\&        non\-ASCII one under /i.
+\&    l   Use the current run\-time locale\*(Aqs rules.
+\&    u   Use Unicode rules.
+\&    d   Use Unicode or native charset, as in 5.12 and earlier.
+\&    n   Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
+.Ve
+.Sp
+If a precompiled pattern is embedded in a larger pattern then the effect
+of \f(CW"msixpluadn"\fR will be propagated appropriately.  The effect that the
+\&\f(CW\*(C`/o\*(C'\fR modifier has is not propagated, being restricted to those patterns
+explicitly using it.
+.Sp
+The \f(CW\*(C`/a\*(C'\fR, \f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/l\*(C'\fR, and \f(CW\*(C`/u\*(C'\fR modifiers (added in Perl 5.14)
+control the character set rules, but \f(CW\*(C`/a\*(C'\fR is the only one you are likely
+to want to specify explicitly; the other three are selected
+automatically by various pragmas.
+.Sp
+See perlre for additional information on valid syntax for \fISTRING\fR, and
+for a detailed look at the semantics of regular expressions.  In
+particular, all modifiers except the largely obsolete \f(CW\*(C`/o\*(C'\fR are further
+explained in "Modifiers" in perlre.  \f(CW\*(C`/o\*(C'\fR is described in the next section.
+.ie n .IP """m/\fIPATTERN\fR/msixpodualngc""" 8
+.el .IP \f(CWm/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
+.IX Xref "m operator, match regexp, options regexp regex, options regex m s i x p o g c"
+.IX Item "m/PATTERN/msixpodualngc"
+.PD 0
+.ie n .IP """/\fIPATTERN\fR/msixpodualngc""" 8
+.el .IP \f(CW/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
+.IX Item "/PATTERN/msixpodualngc"
+.PD
+Searches a string for a pattern match, and in scalar context returns
+true if it succeeds, false if it fails.  If no string is specified
+via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR string is searched.  (The
+string specified with \f(CW\*(C`=~\*(C'\fR need not be an lvalue\-\-it may be the
+result of an expression evaluation, but remember the \f(CW\*(C`=~\*(C'\fR binds
+rather tightly.)  See also perlre.
+.Sp
+Options are as described in \f(CW\*(C`qr//\*(C'\fR above; in addition, the following match
+process modifiers are available:
+.Sp
+.Vb 3
+\& g  Match globally, i.e., find all occurrences.
+\& c  Do not reset search position on a failed match when /g is
+\&    in effect.
+.Ve
+.Sp
+If \f(CW"/"\fR is the delimiter then the initial \f(CW\*(C`m\*(C'\fR is optional.  With the \f(CW\*(C`m\*(C'\fR
+you can use any pair of non-whitespace (ASCII) characters
+as delimiters.  This is particularly useful for matching path names
+that contain \f(CW"/"\fR, to avoid LTS (leaning toothpick syndrome).  If \f(CW"?"\fR is
+the delimiter, then a match-only-once rule applies,
+described in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR below.  If \f(CW"\*(Aq"\fR (single quote) is the delimiter,
+no variable interpolation is performed on the \fIPATTERN\fR.
+When using a delimiter character valid in an identifier, whitespace is required
+after the \f(CW\*(C`m\*(C'\fR.
+.Sp
+\&\fIPATTERN\fR may contain variables, which will be interpolated
+every time the pattern search is evaluated, except
+for when the delimiter is a single quote.  (Note that \f(CW$(\fR, \f(CW$)\fR, and
+\&\f(CW$|\fR are not interpolated because they look like end-of-string tests.)
+Perl will not recompile the pattern unless an interpolated
+variable that it contains changes.  You can force Perl to skip the
+test and never recompile by adding a \f(CW\*(C`/o\*(C'\fR (which stands for "once")
+after the trailing delimiter.
+Once upon a time, Perl would recompile regular expressions
+unnecessarily, and this modifier was useful to tell it not to do so, in the
+interests of speed.  But now, the only reasons to use \f(CW\*(C`/o\*(C'\fR are one of:
+.RS 8
+.IP 1. 4
+The variables are thousands of characters long and you know that they
+don't change, and you need to wring out the last little bit of speed by
+having Perl skip testing for that.  (There is a maintenance penalty for
+doing this, as mentioning \f(CW\*(C`/o\*(C'\fR constitutes a promise that you won't
+change the variables in the pattern.  If you do change them, Perl won't
+even notice.)
+.IP 2. 4
+you want the pattern to use the initial values of the variables
+regardless of whether they change or not.  (But there are saner ways
+of accomplishing this than using \f(CW\*(C`/o\*(C'\fR.)
+.IP 3. 4
+If the pattern contains embedded code, such as
+.Sp
+.Vb 3
+\&    use re \*(Aqeval\*(Aq;
+\&    $code = \*(Aqfoo(?{ $x })\*(Aq;
+\&    /$code/
+.Ve
+.Sp
+then perl will recompile each time, even though the pattern string hasn't
+changed, to ensure that the current value of \f(CW$x\fR is seen each time.
+Use \f(CW\*(C`/o\*(C'\fR if you want to avoid this.
+.RE
+.RS 8
+.Sp
+The bottom line is that using \f(CW\*(C`/o\*(C'\fR is almost never a good idea.
+.RE
+.ie n .IP "The empty pattern ""//""" 8
+.el .IP "The empty pattern \f(CW//\fR" 8
+.IX Item "The empty pattern //"
+If the \fIPATTERN\fR evaluates to the empty string, the last
+\&\fIsuccessfully\fR matched regular expression is used instead. In this
+case, only the \f(CW\*(C`g\*(C'\fR and \f(CW\*(C`c\*(C'\fR flags on the empty pattern are honored; the
+other flags are taken from the original pattern. If no match has
+previously succeeded, this will (silently) act instead as a genuine
+empty pattern (which will always match).  Using a user supplied string as
+a pattern has the risk that if the string is empty that it triggers the
+"last successful match" behavior, which can be very confusing. In such
+cases you are recommended to replace \f(CW\*(C`m/$pattern/\*(C'\fR with
+\&\f(CW\*(C`m/(?:$pattern)/\*(C'\fR to avoid this behavior.
+.Sp
+The last successful pattern may be accessed as a variable via
+\&\f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR. Matching against it, or the empty
+pattern should have the same effect, with the exception that when there
+is no last successful pattern the empty pattern will silently match,
+whereas using the \f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR variable will produce
+undefined warnings (if warnings are enabled). You can check
+\&\f(CWdefined(${^LAST_SUCCESSFUL_PATTERN})\fR to test if there is a "last
+successful match" in the current scope.
+.Sp
+Note that it's possible to confuse Perl into thinking \f(CW\*(C`//\*(C'\fR (the empty
+regex) is really \f(CW\*(C`//\*(C'\fR (the defined-or operator).  Perl is usually pretty
+good about this, but some pathological cases might trigger this, such as
+\&\f(CW\*(C`$x///\*(C'\fR (is that \f(CW\*(C`($x)\ /\ (//)\*(C'\fR or \f(CW\*(C`$x\ //\ /\*(C'\fR?) and \f(CW\*(C`print\ $fh\ //\*(C'\fR
+(\f(CW\*(C`print\ $fh(//\*(C'\fR or \f(CW\*(C`print($fh\ //\*(C'\fR?).  In all of these examples, Perl
+will assume you meant defined-or.  If you meant the empty regex, just
+use parentheses or spaces to disambiguate, or even prefix the empty
+regex with an \f(CW\*(C`m\*(C'\fR (so \f(CW\*(C`//\*(C'\fR becomes \f(CW\*(C`m//\*(C'\fR).
+.IP "Matching in list context" 8
+.IX Item "Matching in list context"
+If the \f(CW\*(C`/g\*(C'\fR option is not used, \f(CW\*(C`m//\*(C'\fR in list context returns a
+list consisting of the subexpressions matched by the parentheses in the
+pattern, that is, (\f(CW$1\fR, \f(CW$2\fR, \f(CW$3\fR...)  (Note that here \f(CW$1\fR etc. are
+also set).  When there are no parentheses in the pattern, the return
+value is the list \f(CW\*(C`(1)\*(C'\fR for success.
+With or without parentheses, an empty list is returned upon failure.
+.Sp
+Examples:
+.Sp
+.Vb 2
+\& open(TTY, "+</dev/tty")
+\&    || die "can\*(Aqt access /dev/tty: $!";
+\&
+\& <TTY> =~ /^y/i && foo();       # do foo if desired
+\&
+\& if (/Version: *([0\-9.]*)/) { $version = $1; }
+\&
+\& next if m#^/usr/spool/uucp#;
+\&
+\& # poor man\*(Aqs grep
+\& $arg = shift;
+\& while (<>) {
+\&    print if /$arg/o; # compile only once (no longer needed!)
+\& }
+\&
+\& if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
+.Ve
+.Sp
+This last example splits \f(CW$foo\fR into the first two words and the
+remainder of the line, and assigns those three fields to \f(CW$F1\fR, \f(CW$F2\fR, and
+\&\f(CW$Etc\fR.  The conditional is true if any variables were assigned; that is,
+if the pattern matched.
+.Sp
+The \f(CW\*(C`/g\*(C'\fR modifier specifies global pattern matching\-\-that is,
+matching as many times as possible within the string.  How it behaves
+depends on the context.  In list context, it returns a list of the
+substrings matched by any capturing parentheses in the regular
+expression.  If there are no parentheses, it returns a list of all
+the matched strings, as if there were parentheses around the whole
+pattern.
+.Sp
+In scalar context, each execution of \f(CW\*(C`m//g\*(C'\fR finds the next match,
+returning true if it matches, and false if there is no further match.
+The position after the last match can be read or set using the \f(CWpos()\fR
+function; see "pos" in perlfunc.  A failed match normally resets the
+search position to the beginning of the string, but you can avoid that
+by adding the \f(CW\*(C`/c\*(C'\fR modifier (for example, \f(CW\*(C`m//gc\*(C'\fR).  Modifying the target
+string also resets the search position.
+.ie n .IP """\eG \fIassertion\fR""" 8
+.el .IP "\f(CW\eG \fR\f(CIassertion\fR\f(CW\fR" 8
+.IX Item "G assertion"
+You can intermix \f(CW\*(C`m//g\*(C'\fR matches with \f(CW\*(C`m/\eG.../g\*(C'\fR, where \f(CW\*(C`\eG\*(C'\fR is a
+zero-width assertion that matches the exact position where the
+previous \f(CW\*(C`m//g\*(C'\fR, if any, left off.  Without the \f(CW\*(C`/g\*(C'\fR modifier, the
+\&\f(CW\*(C`\eG\*(C'\fR assertion still anchors at \f(CWpos()\fR as it was at the start of
+the operation (see "pos" in perlfunc), but the match is of course only
+attempted once.  Using \f(CW\*(C`\eG\*(C'\fR without \f(CW\*(C`/g\*(C'\fR on a target string that has
+not previously had a \f(CW\*(C`/g\*(C'\fR match applied to it is the same as using
+the \f(CW\*(C`\eA\*(C'\fR assertion to match the beginning of the string.  Note also
+that, currently, \f(CW\*(C`\eG\*(C'\fR is only properly supported when anchored at the
+very beginning of the pattern.
+.Sp
+Examples:
+.Sp
+.Vb 2
+\&    # list context
+\&    ($one,$five,$fifteen) = (\`uptime\` =~ /(\ed+\e.\ed+)/g);
+\&
+\&    # scalar context
+\&    local $/ = "";
+\&    while ($paragraph = <>) {
+\&        while ($paragraph =~ /\ep{Ll}[\*(Aq")]*[.!?]+[\*(Aq")]*\es/g) {
+\&            $sentences++;
+\&        }
+\&    }
+\&    say $sentences;
+.Ve
+.Sp
+Here's another way to check for sentences in a paragraph:
+.Sp
+.Vb 10
+\& my $sentence_rx = qr{
+\&    (?: (?<= ^ ) | (?<= \es ) )  # after start\-of\-string or
+\&                                # whitespace
+\&    \ep{Lu}                      # capital letter
+\&    .*?                         # a bunch of anything
+\&    (?<= \eS )                   # that ends in non\-
+\&                                # whitespace
+\&    (?<! \eb [DMS]r  )           # but isn\*(Aqt a common abbr.
+\&    (?<! \eb Mrs )
+\&    (?<! \eb Sra )
+\&    (?<! \eb St  )
+\&    [.?!]                       # followed by a sentence
+\&                                # ender
+\&    (?= $ | \es )                # in front of end\-of\-string
+\&                                # or whitespace
+\& }sx;
+\& local $/ = "";
+\& while (my $paragraph = <>) {
+\&    say "NEW PARAGRAPH";
+\&    my $count = 0;
+\&    while ($paragraph =~ /($sentence_rx)/g) {
+\&        printf "\etgot sentence %d: <%s>\en", ++$count, $1;
+\&    }
+\& }
+.Ve
+.Sp
+Here's how to use \f(CW\*(C`m//gc\*(C'\fR with \f(CW\*(C`\eG\*(C'\fR:
+.Sp
+.Vb 10
+\&    $_ = "ppooqppqq";
+\&    while ($i++ < 2) {
+\&        print "1: \*(Aq";
+\&        print $1 while /(o)/gc; print "\*(Aq, pos=", pos, "\en";
+\&        print "2: \*(Aq";
+\&        print $1 if /\eG(q)/gc;  print "\*(Aq, pos=", pos, "\en";
+\&        print "3: \*(Aq";
+\&        print $1 while /(p)/gc; print "\*(Aq, pos=", pos, "\en";
+\&    }
+\&    print "Final: \*(Aq$1\*(Aq, pos=",pos,"\en" if /\eG(.)/;
+.Ve
+.Sp
+The last example should print:
+.Sp
+.Vb 7
+\&    1: \*(Aqoo\*(Aq, pos=4
+\&    2: \*(Aqq\*(Aq, pos=5
+\&    3: \*(Aqpp\*(Aq, pos=7
+\&    1: \*(Aq\*(Aq, pos=7
+\&    2: \*(Aqq\*(Aq, pos=8
+\&    3: \*(Aq\*(Aq, pos=8
+\&    Final: \*(Aqq\*(Aq, pos=8
+.Ve
+.Sp
+Notice that the final match matched \f(CW\*(C`q\*(C'\fR instead of \f(CW\*(C`p\*(C'\fR, which a match
+without the \f(CW\*(C`\eG\*(C'\fR anchor would have done.  Also note that the final match
+did not update \f(CW\*(C`pos\*(C'\fR.  \f(CW\*(C`pos\*(C'\fR is only updated on a \f(CW\*(C`/g\*(C'\fR match.  If the
+final match did indeed match \f(CW\*(C`p\*(C'\fR, it's a good bet that you're running an
+ancient (pre\-5.6.0) version of Perl.
+.Sp
+A useful idiom for \f(CW\*(C`lex\*(C'\fR\-like scanners is \f(CW\*(C`/\eG.../gc\*(C'\fR.  You can
+combine several regexps like this to process a string part-by-part,
+doing different actions depending on which regexp matched.  Each
+regexp tries to match where the previous one leaves off.
+.Sp
+.Vb 4
+\& $_ = <<\*(AqEOL\*(Aq;
+\&    $url = URI::URL\->new( "http://example.com/" );
+\&    die if $url eq "xXx";
+\& EOL
+\&
+\& LOOP: {
+\&     print(" digits"),       redo LOOP if /\eG\ed+\eb[,.;]?\es*/gc;
+\&     print(" lowercase"),    redo LOOP
+\&                                    if /\eG\ep{Ll}+\eb[,.;]?\es*/gc;
+\&     print(" UPPERCASE"),    redo LOOP
+\&                                    if /\eG\ep{Lu}+\eb[,.;]?\es*/gc;
+\&     print(" Capitalized"),  redo LOOP
+\&                              if /\eG\ep{Lu}\ep{Ll}+\eb[,.;]?\es*/gc;
+\&     print(" MiXeD"),        redo LOOP if /\eG\epL+\eb[,.;]?\es*/gc;
+\&     print(" alphanumeric"), redo LOOP
+\&                            if /\eG[\ep{Alpha}\epN]+\eb[,.;]?\es*/gc;
+\&     print(" line\-noise"),   redo LOOP if /\eG\eW+/gc;
+\&     print ". That\*(Aqs all!\en";
+\& }
+.Ve
+.Sp
+Here is the output (split into several lines):
+.Sp
+.Vb 4
+\& line\-noise lowercase line\-noise UPPERCASE line\-noise UPPERCASE
+\& line\-noise lowercase line\-noise lowercase line\-noise lowercase
+\& lowercase line\-noise lowercase lowercase line\-noise lowercase
+\& lowercase line\-noise MiXeD line\-noise. That\*(Aqs all!
+.Ve
+.ie n .IP """m?\fIPATTERN\fR?msixpodualngc""" 8
+.el .IP \f(CWm?\fR\f(CIPATTERN\fR\f(CW?msixpodualngc\fR 8
+.IX Xref "? operator, match-once"
+.IX Item "m?PATTERN?msixpodualngc"
+This is just like the \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR search, except that it matches
+only once between calls to the \f(CWreset()\fR operator.  This is a useful
+optimization when you want to see only the first occurrence of
+something in each file of a set of files, for instance.  Only \f(CW\*(C`m??\*(C'\fR
+patterns local to the current package are reset.
+.Sp
+.Vb 7
+\&    while (<>) {
+\&        if (m?^$?) {
+\&                            # blank line between header and body
+\&        }
+\&    } continue {
+\&        reset if eof;       # clear m?? status for next file
+\&    }
+.Ve
+.Sp
+Another example switched the first "latin1" encoding it finds
+to "utf8" in a pod file:
+.Sp
+.Vb 1
+\&    s//utf8/ if m? ^ =encoding \eh+ \eK latin1 ?x;
+.Ve
+.Sp
+The match-once behavior is controlled by the match delimiter being
+\&\f(CW\*(C`?\*(C'\fR; with any other delimiter this is the normal \f(CW\*(C`m//\*(C'\fR operator.
+.Sp
+In the past, the leading \f(CW\*(C`m\*(C'\fR in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR was optional, but omitting it
+would produce a deprecation warning.  As of v5.22.0, omitting it produces a
+syntax error.  If you encounter this construct in older code, you can just add
+\&\f(CW\*(C`m\*(C'\fR.
+.ie n .IP """s/\fIPATTERN\fR/\fIREPLACEMENT\fR/msixpodualngcer""" 8
+.el .IP \f(CWs/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/msixpodualngcer\fR 8
+.IX Xref "s substitute substitution replace regexp, replace regexp, substitute m s i x p o g c e r"
+.IX Item "s/PATTERN/REPLACEMENT/msixpodualngcer"
+Searches a string for a pattern, and if found, replaces that pattern
+with the replacement text and returns the number of substitutions
+made.  Otherwise it returns false (a value that is both an empty string (\f(CW""\fR)
+and numeric zero (\f(CW0\fR) as described in "Relational Operators").
+.Sp
+If the \f(CW\*(C`/r\*(C'\fR (non-destructive) option is used then it runs the
+substitution on a copy of the string and instead of returning the
+number of substitutions, it returns the copy whether or not a
+substitution occurred.  The original string is never changed when
+\&\f(CW\*(C`/r\*(C'\fR is used.  The copy will always be a plain string, even if the
+input is an object or a tied variable.
+.Sp
+If no string is specified via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR
+variable is searched and modified.  Unless the \f(CW\*(C`/r\*(C'\fR option is used,
+the string specified must be a scalar variable, an array element, a
+hash element, or an assignment to one of those; that is, some sort of
+scalar lvalue.
+.Sp
+If the delimiter chosen is a single quote, no variable interpolation is
+done on either the \fIPATTERN\fR or the \fIREPLACEMENT\fR.  Otherwise, if the
+\&\fIPATTERN\fR contains a \f(CW\*(C`$\*(C'\fR that looks like a variable rather than an
+end-of-string test, the variable will be interpolated into the pattern
+at run-time.  If you want the pattern compiled only once the first time
+the variable is interpolated, use the \f(CW\*(C`/o\*(C'\fR option.  If the pattern
+evaluates to the empty string, the last successfully executed regular
+expression is used instead.  See perlre for further explanation on these.
+.Sp
+Options are as with \f(CW\*(C`m//\*(C'\fR with the addition of the following replacement
+specific options:
+.Sp
+.Vb 5
+\&    e   Evaluate the right side as an expression.
+\&    ee  Evaluate the right side as a string then eval the
+\&        result.
+\&    r   Return substitution and leave the original string
+\&        untouched.
+.Ve
+.Sp
+Any non-whitespace delimiter may replace the slashes.  Add space after
+the \f(CW\*(C`s\*(C'\fR when using a character allowed in identifiers.  If single quotes
+are used, no interpretation is done on the replacement string (the \f(CW\*(C`/e\*(C'\fR
+modifier overrides this, however).  Note that Perl treats backticks
+as normal delimiters; the replacement text is not evaluated as a command.
+If the \fIPATTERN\fR is delimited by bracketing quotes, the \fIREPLACEMENT\fR has
+its own pair of quotes, which may or may not be bracketing quotes, for example,
+\&\f(CW\*(C`s(foo)(bar)\*(C'\fR or \f(CW\*(C`s<foo>/bar/\*(C'\fR.  A \f(CW\*(C`/e\*(C'\fR will cause the
+replacement portion to be treated as a full-fledged Perl expression
+and evaluated right then and there.  It is, however, syntax checked at
+compile-time.  A second \f(CW\*(C`e\*(C'\fR modifier will cause the replacement portion
+to be \f(CW\*(C`eval\*(C'\fRed before being run as a Perl expression.
+.Sp
+Examples:
+.Sp
+.Vb 1
+\&    s/\ebgreen\eb/mauve/g;              # don\*(Aqt change wintergreen
+\&
+\&    $path =~ s|/usr/bin|/usr/local/bin|;
+\&
+\&    s/Login: $foo/Login: $bar/; # run\-time pattern
+\&
+\&    ($foo = $bar) =~ s/this/that/;      # copy first, then
+\&                                        # change
+\&    ($foo = "$bar") =~ s/this/that/;    # convert to string,
+\&                                        # copy, then change
+\&    $foo = $bar =~ s/this/that/r;       # Same as above using /r
+\&    $foo = $bar =~ s/this/that/r
+\&                =~ s/that/the other/r;  # Chained substitutes
+\&                                        # using /r
+\&    @foo = map { s/this/that/r } @bar   # /r is very useful in
+\&                                        # maps
+\&
+\&    $count = ($paragraph =~ s/Mister\eb/Mr./g);  # get change\-cnt
+\&
+\&    $_ = \*(Aqabc123xyz\*(Aq;
+\&    s/\ed+/$&*2/e;               # yields \*(Aqabc246xyz\*(Aq
+\&    s/\ed+/sprintf("%5d",$&)/e;  # yields \*(Aqabc  246xyz\*(Aq
+\&    s/\ew/$& x 2/eg;             # yields \*(Aqaabbcc  224466xxyyzz\*(Aq
+\&
+\&    s/%(.)/$percent{$1}/g;      # change percent escapes; no /e
+\&    s/%(.)/$percent{$1} || $&/ge;       # expr now, so /e
+\&    s/^=(\ew+)/pod($1)/ge;       # use function call
+\&
+\&    $_ = \*(Aqabc123xyz\*(Aq;
+\&    $x = s/abc/def/r;           # $x is \*(Aqdef123xyz\*(Aq and
+\&                                # $_ remains \*(Aqabc123xyz\*(Aq.
+\&
+\&    # expand variables in $_, but dynamics only, using
+\&    # symbolic dereferencing
+\&    s/\e$(\ew+)/${$1}/g;
+\&
+\&    # Add one to the value of any numbers in the string
+\&    s/(\ed+)/1 + $1/eg;
+\&
+\&    # Titlecase words in the last 30 characters only (presuming
+\&    # that the substring doesn\*(Aqt start in the middle of a word)
+\&    substr($str, \-30) =~ s/\eb(\ep{Alpha})(\ep{Alpha}*)\eb/\eu$1\eL$2/g;
+\&
+\&    # This will expand any embedded scalar variable
+\&    # (including lexicals) in $_ : First $1 is interpolated
+\&    # to the variable name, and then evaluated
+\&    s/(\e$\ew+)/$1/eeg;
+\&
+\&    # Delete (most) C comments.
+\&    $program =~ s {
+\&        /\e*     # Match the opening delimiter.
+\&        .*?     # Match a minimal number of characters.
+\&        \e*/     # Match the closing delimiter.
+\&    } []gsx;
+\&
+\&    s/^\es*(.*?)\es*$/$1/;        # trim whitespace in $_,
+\&                                # expensively
+\&
+\&    for ($variable) {           # trim whitespace in $variable,
+\&                                # cheap
+\&        s/^\es+//;
+\&        s/\es+$//;
+\&    }
+\&
+\&    s/([^ ]*) *([^ ]*)/$2 $1/;  # reverse 1st two fields
+\&
+\&    $foo !~ s/A/a/g;    # Lowercase all A\*(Aqs in $foo; return
+\&                        # 0 if any were found and changed;
+\&                        # otherwise return 1
+.Ve
+.Sp
+Note the use of \f(CW\*(C`$\*(C'\fR instead of \f(CW\*(C`\e\*(C'\fR in the last example.  Unlike
+\&\fBsed\fR, we use the \e<\fIdigit\fR> form only in the left hand side.
+Anywhere else it's $<\fIdigit\fR>.
+.Sp
+Occasionally, you can't use just a \f(CW\*(C`/g\*(C'\fR to get all the changes
+to occur that you might want.  Here are two common cases:
+.Sp
+.Vb 2
+\&    # put commas in the right places in an integer
+\&    1 while s/(\ed)(\ed\ed\ed)(?!\ed)/$1,$2/g;
+\&
+\&    # expand tabs to 8\-column spacing
+\&    1 while s/\et+/\*(Aq \*(Aq x (length($&)*8 \- length($\`)%8)/e;
+.Ve
+.Sp
+While \f(CW\*(C`s///\*(C'\fR accepts the \f(CW\*(C`/c\*(C'\fR flag, it has no effect beyond
+producing a warning if warnings are enabled.
+.IX Xref " c"
+.SS "Quote-Like Operators"
+.IX Xref "operator, quote-like"
+.IX Subsection "Quote-Like Operators"
+.ie n .IP """q/\fISTRING\fR/""" 4
+.el .IP \f(CWq/\fR\f(CISTRING\fR\f(CW/\fR 4
+.IX Xref "q quote, single ' ''"
+.IX Item "q/STRING/"
+.PD 0
+.ie n .IP \*(Aq\fISTRING\fR\*(Aq 4
+.el .IP \f(CW\*(Aq\fR\f(CISTRING\fR\f(CW\*(Aq\fR 4
+.IX Item "STRING"
+.PD
+A single-quoted, literal string.  A backslash represents a backslash
+unless followed by the delimiter or another backslash, in which case
+the delimiter or backslash is interpolated.
+.Sp
+.Vb 3
+\&    $foo = q!I said, "You said, \*(AqShe said it.\*(Aq"!;
+\&    $bar = q(\*(AqThis is it.\*(Aq);
+\&    $baz = \*(Aq\en\*(Aq;                # a two\-character string
+.Ve
+.ie n .IP """qq/\fISTRING\fR/""" 4
+.el .IP \f(CWqq/\fR\f(CISTRING\fR\f(CW/\fR 4
+.IX Xref "qq quote, double "" """""
+.IX Item "qq/STRING/"
+.PD 0
+.ie n .IP """\fISTRING\fR""" 4
+.el .IP "\f(CW""\fR\f(CISTRING\fR\f(CW""\fR" 4
+.IX Item """STRING"""
+.PD
+A double-quoted, interpolated string.
+.Sp
+.Vb 4
+\&    $_ .= qq
+\&     (*** The previous line contains the naughty word "$1".\en)
+\&                if /\eb(tcl|java|python)\eb/i;      # :\-)
+\&    $baz = "\en";                # a one\-character string
+.Ve
+.ie n .IP """qx/\fISTRING\fR/""" 4
+.el .IP \f(CWqx/\fR\f(CISTRING\fR\f(CW/\fR 4
+.IX Xref "qx ` `` backtick"
+.IX Item "qx/STRING/"
+.PD 0
+.ie n .IP \`\fISTRING\fR\` 4
+.el .IP \f(CW\`\fR\f(CISTRING\fR\f(CW\`\fR 4
+.IX Item "STRING"
+.PD
+A string which is (possibly) interpolated and then executed as a
+system command, via \fI/bin/sh\fR or its equivalent if required.  Shell
+wildcards, pipes, and redirections will be honored.  Similarly to
+\&\f(CW\*(C`system\*(C'\fR, if the string contains no shell metacharacters then it will
+executed directly.  The collected standard output of the command is
+returned; standard error is unaffected.  In scalar context, it comes
+back as a single (potentially multi-line) string, or \f(CW\*(C`undef\*(C'\fR if the
+shell (or command) could not be started.  In list context, returns a
+list of lines (however you've defined lines with \f(CW$/\fR or
+\&\f(CW$INPUT_RECORD_SEPARATOR\fR), or an empty list if the shell (or command)
+could not be started.
+.Sp
+Because backticks do not affect standard error, use shell file descriptor
+syntax (assuming the shell supports this) if you care to address this.
+To capture a command's STDERR and STDOUT together:
+.Sp
+.Vb 1
+\&    $output = \`cmd 2>&1\`;
+.Ve
+.Sp
+To capture a command's STDOUT but discard its STDERR:
+.Sp
+.Vb 1
+\&    $output = \`cmd 2>/dev/null\`;
+.Ve
+.Sp
+To capture a command's STDERR but discard its STDOUT (ordering is
+important here):
+.Sp
+.Vb 1
+\&    $output = \`cmd 2>&1 1>/dev/null\`;
+.Ve
+.Sp
+To exchange a command's STDOUT and STDERR in order to capture the STDERR
+but leave its STDOUT to come out the old STDERR:
+.Sp
+.Vb 1
+\&    $output = \`cmd 3>&1 1>&2 2>&3 3>&\-\`;
+.Ve
+.Sp
+To read both a command's STDOUT and its STDERR separately, it's easiest
+to redirect them separately to files, and then read from those files
+when the program is done:
+.Sp
+.Vb 1
+\&    system("program args 1>program.stdout 2>program.stderr");
+.Ve
+.Sp
+The STDIN filehandle used by the command is inherited from Perl's STDIN.
+For example:
+.Sp
+.Vb 3
+\&    open(SPLAT, "stuff")   || die "can\*(Aqt open stuff: $!";
+\&    open(STDIN, "<&SPLAT") || die "can\*(Aqt dupe SPLAT: $!";
+\&    print STDOUT \`sort\`;
+.Ve
+.Sp
+will print the sorted contents of the file named \fI"stuff"\fR.
+.Sp
+Using single-quote as a delimiter protects the command from Perl's
+double-quote interpolation, passing it on to the shell instead:
+.Sp
+.Vb 2
+\&    $perl_info  = qx(ps $$);            # that\*(Aqs Perl\*(Aqs $$
+\&    $shell_info = qx\*(Aqps $$\*(Aq;            # that\*(Aqs the new shell\*(Aqs $$
+.Ve
+.Sp
+How that string gets evaluated is entirely subject to the command
+interpreter on your system.  On most platforms, you will have to protect
+shell metacharacters if you want them treated literally.  This is in
+practice difficult to do, as it's unclear how to escape which characters.
+See perlsec for a clean and safe example of a manual \f(CWfork()\fR and \f(CWexec()\fR
+to emulate backticks safely.
+.Sp
+On some platforms (notably DOS-like ones), the shell may not be
+capable of dealing with multiline commands, so putting newlines in
+the string may not get you what you want.  You may be able to evaluate
+multiple commands in a single line by separating them with the command
+separator character, if your shell supports that (for example, \f(CW\*(C`;\*(C'\fR on
+many Unix shells and \f(CW\*(C`&\*(C'\fR on the Windows NT \f(CW\*(C`cmd\*(C'\fR shell).
+.Sp
+Perl will attempt to flush all files opened for
+output before starting the child process, but this may not be supported
+on some platforms (see perlport).  To be safe, you may need to set
+\&\f(CW$|\fR (\f(CW$AUTOFLUSH\fR in \f(CW\*(C`English\*(C'\fR) or call the \f(CWautoflush()\fR method of
+\&\f(CW\*(C`IO::Handle\*(C'\fR on any open handles.
+.Sp
+Beware that some command shells may place restrictions on the length
+of the command line.  You must ensure your strings don't exceed this
+limit after any necessary interpolations.  See the platform-specific
+release notes for more details about your particular environment.
+.Sp
+Using this operator can lead to programs that are difficult to port,
+because the shell commands called vary between systems, and may in
+fact not be present at all.  As one example, the \f(CW\*(C`type\*(C'\fR command under
+the POSIX shell is very different from the \f(CW\*(C`type\*(C'\fR command under DOS.
+That doesn't mean you should go out of your way to avoid backticks
+when they're the right way to get something done.  Perl was made to be
+a glue language, and one of the things it glues together is commands.
+Just understand what you're getting yourself into.
+.Sp
+Like \f(CW\*(C`system\*(C'\fR, backticks put the child process exit code in \f(CW$?\fR.
+If you'd like to manually inspect failure, you can check all possible
+failure modes by inspecting \f(CW$?\fR like this:
+.Sp
+.Vb 10
+\&    if ($? == \-1) {
+\&        print "failed to execute: $!\en";
+\&    }
+\&    elsif ($? & 127) {
+\&        printf "child died with signal %d, %s coredump\en",
+\&            ($? & 127),  ($? & 128) ? \*(Aqwith\*(Aq : \*(Aqwithout\*(Aq;
+\&    }
+\&    else {
+\&        printf "child exited with value %d\en", $? >> 8;
+\&    }
+.Ve
+.Sp
+Use the open pragma to control the I/O layers used when reading the
+output of the command, for example:
+.Sp
+.Vb 2
+\&  use open IN => ":encoding(UTF\-8)";
+\&  my $x = \`cmd\-producing\-utf\-8\`;
+.Ve
+.Sp
+\&\f(CW\*(C`qx//\*(C'\fR can also be called like a function with "readpipe" in perlfunc.
+.Sp
+See "I/O Operators" for more discussion.
+.ie n .IP """qw/\fISTRING\fR/""" 4
+.el .IP \f(CWqw/\fR\f(CISTRING\fR\f(CW/\fR 4
+.IX Xref "qw quote, list quote, words"
+.IX Item "qw/STRING/"
+Evaluates to a list of the words extracted out of \fISTRING\fR, using embedded
+whitespace as the word delimiters.  It can be understood as being roughly
+equivalent to:
+.Sp
+.Vb 1
+\&    split(" ", q/STRING/);
+.Ve
+.Sp
+the differences being that it only splits on ASCII whitespace,
+generates a real list at compile time, and
+in scalar context it returns the last element in the list.  So
+this expression:
+.Sp
+.Vb 1
+\&    qw(foo bar baz)
+.Ve
+.Sp
+is semantically equivalent to the list:
+.Sp
+.Vb 1
+\&    "foo", "bar", "baz"
+.Ve
+.Sp
+Some frequently seen examples:
+.Sp
+.Vb 2
+\&    use POSIX qw( setlocale localeconv )
+\&    @EXPORT = qw( foo bar baz );
+.Ve
+.Sp
+A common mistake is to try to separate the words with commas or to
+put comments into a multi-line \f(CW\*(C`qw\*(C'\fR\-string.  For this reason, the
+\&\f(CW\*(C`use\ warnings\*(C'\fR pragma and the \fB\-w\fR switch (that is, the \f(CW$^W\fR variable)
+produces warnings if the \fISTRING\fR contains the \f(CW","\fR or the \f(CW"#"\fR character.
+.ie n .IP """tr/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
+.el .IP \f(CWtr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
+.IX Xref "tr y transliterate c d s"
+.IX Item "tr/SEARCHLIST/REPLACEMENTLIST/cdsr"
+.PD 0
+.ie n .IP """y/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
+.el .IP \f(CWy/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
+.IX Item "y/SEARCHLIST/REPLACEMENTLIST/cdsr"
+.PD
+Transliterates all occurrences of the characters found (or not found
+if the \f(CW\*(C`/c\*(C'\fR modifier is specified) in the search list with the
+positionally corresponding character in the replacement list, possibly
+deleting some, depending on the modifiers specified.  It returns the
+number of characters replaced or deleted.  If no string is specified via
+the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR string is transliterated.
+.Sp
+For \fBsed\fR devotees, \f(CW\*(C`y\*(C'\fR is provided as a synonym for \f(CW\*(C`tr\*(C'\fR.
+.Sp
+If the \f(CW\*(C`/r\*(C'\fR (non-destructive) option is present, a new copy of the string
+is made and its characters transliterated, and this copy is returned no
+matter whether it was modified or not: the original string is always
+left unchanged.  The new copy is always a plain string, even if the input
+string is an object or a tied variable.
+.Sp
+Unless the \f(CW\*(C`/r\*(C'\fR option is used, the string specified with \f(CW\*(C`=~\*(C'\fR must be a
+scalar variable, an array element, a hash element, or an assignment to one
+of those; in other words, an lvalue.
+.Sp
+The characters delimitting \fISEARCHLIST\fR and \fIREPLACEMENTLIST\fR
+can be any printable character, not just forward slashes.  If they
+are single quotes (\f(CW\*(C`tr\*(Aq\fR\f(CISEARCHLIST\fR\f(CW\*(Aq\fR\f(CIREPLACEMENTLIST\fR\f(CW\*(Aq\*(C'\fR), the only
+interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR; so hyphens are
+interpreted literally rather than specifying a character range.
+.Sp
+Otherwise, a character range may be specified with a hyphen, so
+\&\f(CW\*(C`tr/A\-J/0\-9/\*(C'\fR does the same replacement as
+\&\f(CW\*(C`tr/ACEGIBDFHJ/0246813579/\*(C'\fR.
+.Sp
+If the \fISEARCHLIST\fR is delimited by bracketing quotes, the
+\&\fIREPLACEMENTLIST\fR must have its own pair of quotes, which may or may
+not be bracketing quotes; for example, \f(CW\*(C`tr(aeiouy)(yuoiea)\*(C'\fR or
+\&\f(CW\*(C`tr[+\e\-*/]"ABCD"\*(C'\fR.  This final example shows a way to visually clarify
+what is going on for people who are more familiar with regular
+expression patterns than with \f(CW\*(C`tr\*(C'\fR, and who may think forward slash
+delimiters imply that \f(CW\*(C`tr\*(C'\fR is more like a regular expression pattern
+than it actually is.  (Another option might be to use \f(CW\*(C`tr[...][...]\*(C'\fR.)
+.Sp
+\&\f(CW\*(C`tr\*(C'\fR isn't fully like bracketed character classes, just
+(significantly) more like them than it is to full patterns.  For
+example, characters appearing more than once in either list behave
+differently here than in patterns, and \f(CW\*(C`tr\*(C'\fR lists do not allow
+backslashed character classes such as \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`\epL\*(C'\fR, nor variable
+interpolation, so \f(CW"$"\fR and \f(CW"@"\fR are always treated as literals.
+.Sp
+The allowed elements are literals plus \f(CW\*(C`\e\*(Aq\*(C'\fR (meaning a single quote).
+If the delimiters aren't single quotes, also allowed are any of the
+escape sequences accepted in double-quoted strings.  Escape sequence
+details are in the table near the beginning of this section.
+.Sp
+A hyphen at the beginning or end, or preceded by a backslash is also
+always considered a literal.  Precede a delimiter character with a
+backslash to allow it.
+.Sp
+The \f(CW\*(C`tr\*(C'\fR operator is not equivalent to the \f(CWtr(1)\fR utility.
+\&\f(CW\*(C`tr[a\-z][A\-Z]\*(C'\fR will uppercase the 26 letters "a" through "z", but for
+case changing not confined to ASCII, use \f(CW\*(C`lc\*(C'\fR,
+\&\f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR,
+\&\f(CW\*(C`ucfirst\*(C'\fR (all documented in perlfunc), or the
+substitution operator
+\&\f(CW\*(C`s/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/\*(C'\fR
+(with \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, and \f(CW\*(C`\el\*(C'\fR string-interpolation escapes in the
+\&\fIREPLACEMENT\fR portion).
+.Sp
+Most ranges are unportable between character sets, but certain ones
+signal Perl to do special handling to make them portable.  There are two
+classes of portable ranges.  The first are any subsets of the ranges
+\&\f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, and \f(CW\*(C`0\-9\*(C'\fR, when expressed as literal characters.
+.Sp
+.Vb 1
+\&  tr/h\-k/H\-K/
+.Ve
+.Sp
+capitalizes the letters \f(CW"h"\fR, \f(CW"i"\fR, \f(CW"j"\fR, and \f(CW"k"\fR and nothing
+else, no matter what the platform's character set is.  In contrast, all
+of
+.Sp
+.Vb 3
+\&  tr/\ex68\-\ex6B/\ex48\-\ex4B/
+\&  tr/h\-\ex6B/H\-\ex4B/
+\&  tr/\ex68\-k/\ex48\-K/
+.Ve
+.Sp
+do the same capitalizations as the previous example when run on ASCII
+platforms, but something completely different on EBCDIC ones.
+.Sp
+The second class of portable ranges is invoked when one or both of the
+range's end points are expressed as \f(CW\*(C`\eN{...}\*(C'\fR
+.Sp
+.Vb 1
+\& $string =~ tr/\eN{U+20}\-\eN{U+7E}//d;
+.Ve
+.Sp
+removes from \f(CW$string\fR all the platform's characters which are
+equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E.  This
+is a portable range, and has the same effect on every platform it is
+run on.  In this example, these are the ASCII
+printable characters.  So after this is run, \f(CW$string\fR has only
+controls and characters which have no ASCII equivalents.
+.Sp
+But, even for portable ranges, it is not generally obvious what is
+included without having to look things up in the manual.  A sound
+principle is to use only ranges that both begin from, and end at, either
+ASCII alphabetics of equal case (\f(CW\*(C`b\-e\*(C'\fR, \f(CW\*(C`B\-E\*(C'\fR), or digits (\f(CW\*(C`1\-4\*(C'\fR).
+Anything else is unclear (and unportable unless \f(CW\*(C`\eN{...}\*(C'\fR is used).  If
+in doubt, spell out the character sets in full.
+.Sp
+Options:
+.Sp
+.Vb 5
+\&    c   Complement the SEARCHLIST.
+\&    d   Delete found but unreplaced characters.
+\&    r   Return the modified string and leave the original string
+\&        untouched.
+\&    s   Squash duplicate replaced characters.
+.Ve
+.Sp
+If the \f(CW\*(C`/d\*(C'\fR modifier is specified, any characters specified by
+\&\fISEARCHLIST\fR  not found in \fIREPLACEMENTLIST\fR are deleted.  (Note that
+this is slightly more flexible than the behavior of some \fBtr\fR programs,
+which delete anything they find in the \fISEARCHLIST\fR, period.)
+.Sp
+If the \f(CW\*(C`/s\*(C'\fR modifier is specified, sequences of characters, all in a
+row, that were transliterated to the same character are squashed down to
+a single instance of that character.
+.Sp
+.Vb 2
+\& my $a = "aaabbbca";
+\& $a =~ tr/ab/dd/s;     # $a now is "dcd"
+.Ve
+.Sp
+If the \f(CW\*(C`/d\*(C'\fR modifier is used, the \fIREPLACEMENTLIST\fR is always interpreted
+exactly as specified.  Otherwise, if the \fIREPLACEMENTLIST\fR is shorter
+than the \fISEARCHLIST\fR, the final character, if any, is replicated until
+it is long enough.  There won't be a final character if and only if the
+\&\fIREPLACEMENTLIST\fR is empty, in which case \fIREPLACEMENTLIST\fR is
+copied from \fISEARCHLIST\fR.    An empty \fIREPLACEMENTLIST\fR is useful
+for counting characters in a class, or for squashing character sequences
+in a class.
+.Sp
+.Vb 4
+\&    tr/abcd//            tr/abcd/abcd/
+\&    tr/abcd/AB/          tr/abcd/ABBB/
+\&    tr/abcd//d           s/[abcd]//g
+\&    tr/abcd/AB/d         (tr/ab/AB/ + s/[cd]//g)  \- but run together
+.Ve
+.Sp
+If the \f(CW\*(C`/c\*(C'\fR modifier is specified, the characters to be transliterated
+are the ones NOT in \fISEARCHLIST\fR, that is, it is complemented.  If
+\&\f(CW\*(C`/d\*(C'\fR and/or \f(CW\*(C`/s\*(C'\fR are also specified, they apply to the complemented
+\&\fISEARCHLIST\fR.  Recall, that if \fIREPLACEMENTLIST\fR is empty (except
+under \f(CW\*(C`/d\*(C'\fR) a copy of \fISEARCHLIST\fR is used instead.  That copy is made
+after complementing under \f(CW\*(C`/c\*(C'\fR.  \fISEARCHLIST\fR is sorted by code point
+order after complementing, and any \fIREPLACEMENTLIST\fR  is applied to
+that sorted result.  This means that under \f(CW\*(C`/c\*(C'\fR, the order of the
+characters specified in \fISEARCHLIST\fR is irrelevant.  This can
+lead to different results on EBCDIC systems if \fIREPLACEMENTLIST\fR
+contains more than one character, hence it is generally non-portable to
+use \f(CW\*(C`/c\*(C'\fR with such a \fIREPLACEMENTLIST\fR.
+.Sp
+Another way of describing the operation is this:
+If \f(CW\*(C`/c\*(C'\fR is specified, the \fISEARCHLIST\fR is sorted by code point order,
+then complemented.  If \fIREPLACEMENTLIST\fR is empty and \f(CW\*(C`/d\*(C'\fR is not
+specified, \fIREPLACEMENTLIST\fR is replaced by a copy of \fISEARCHLIST\fR (as
+modified under \f(CW\*(C`/c\*(C'\fR), and these potentially modified lists are used as
+the basis for what follows.  Any character in the target string that
+isn't in \fISEARCHLIST\fR is passed through unchanged.  Every other
+character in the target string is replaced by the character in
+\&\fIREPLACEMENTLIST\fR that positionally corresponds to its mate in
+\&\fISEARCHLIST\fR, except that under \f(CW\*(C`/s\*(C'\fR, the 2nd and following characters
+are squeezed out in a sequence of characters in a row that all translate
+to the same character.  If \fISEARCHLIST\fR is longer than
+\&\fIREPLACEMENTLIST\fR, characters in the target string that match a
+character in \fISEARCHLIST\fR that doesn't have a correspondence in
+\&\fIREPLACEMENTLIST\fR are either deleted from the target string if \f(CW\*(C`/d\*(C'\fR is
+specified; or replaced by the final character in \fIREPLACEMENTLIST\fR if
+\&\f(CW\*(C`/d\*(C'\fR isn't specified.
+.Sp
+Some examples:
+.Sp
+.Vb 1
+\& $ARGV[1] =~ tr/A\-Z/a\-z/;   # canonicalize to lower case ASCII
+\&
+\& $cnt = tr/*/*/;            # count the stars in $_
+\& $cnt = tr/*//;             # same thing
+\&
+\& $cnt = $sky =~ tr/*/*/;    # count the stars in $sky
+\& $cnt = $sky =~ tr/*//;     # same thing
+\&
+\& $cnt = $sky =~ tr/*//c;    # count all the non\-stars in $sky
+\& $cnt = $sky =~ tr/*/*/c;   # same, but transliterate each non\-star
+\&                            # into a star, leaving the already\-stars
+\&                            # alone.  Afterwards, everything in $sky
+\&                            # is a star.
+\&
+\& $cnt = tr/0\-9//;           # count the ASCII digits in $_
+\&
+\& tr/a\-zA\-Z//s;              # bookkeeper \-> bokeper
+\& tr/o/o/s;                  # bookkeeper \-> bokkeeper
+\& tr/oe/oe/s;                # bookkeeper \-> bokkeper
+\& tr/oe//s;                  # bookkeeper \-> bokkeper
+\& tr/oe/o/s;                 # bookkeeper \-> bokkopor
+\&
+\& ($HOST = $host) =~ tr/a\-z/A\-Z/;
+\&  $HOST = $host  =~ tr/a\-z/A\-Z/r; # same thing
+\&
+\& $HOST = $host =~ tr/a\-z/A\-Z/r   # chained with s///r
+\&               =~ s/:/ \-p/r;
+\&
+\& tr/a\-zA\-Z/ /cs;                 # change non\-alphas to single space
+\&
+\& @stripped = map tr/a\-zA\-Z/ /csr, @original;
+\&                                 # /r with map
+\&
+\& tr [\e200\-\e377]
+\&    [\e000\-\e177];                 # wickedly delete 8th bit
+\&
+\& $foo !~ tr/A/a/    # transliterate all the A\*(Aqs in $foo to \*(Aqa\*(Aq,
+\&                    # return 0 if any were found and changed.
+\&                    # Otherwise return 1
+.Ve
+.Sp
+If multiple transliterations are given for a character, only the
+first one is used:
+.Sp
+.Vb 1
+\& tr/AAA/XYZ/
+.Ve
+.Sp
+will transliterate any A to X.
+.Sp
+Because the transliteration table is built at compile time, neither
+the \fISEARCHLIST\fR nor the \fIREPLACEMENTLIST\fR are subjected to double quote
+interpolation.  That means that if you want to use variables, you
+must use an \f(CWeval()\fR:
+.Sp
+.Vb 2
+\& eval "tr/$oldlist/$newlist/";
+\& die $@ if $@;
+\&
+\& eval "tr/$oldlist/$newlist/, 1" or die $@;
+.Ve
+.ie n .IP """<<\fIEOF\fR""" 4
+.el .IP \f(CW<<\fR\f(CIEOF\fR\f(CW\fR 4
+.IX Xref "here-doc heredoc here-document <<"
+.IX Item "<<EOF"
+A line-oriented form of quoting is based on the shell "here-document"
+syntax.  Following a \f(CW\*(C`<<\*(C'\fR you specify a string to terminate
+the quoted material, and all lines following the current line down to
+the terminating string are the value of the item.
+.Sp
+Prefixing the terminating string with a \f(CW\*(C`~\*(C'\fR specifies that you
+want to use "Indented Here-docs" (see below).
+.Sp
+The terminating string may be either an identifier (a word), or some
+quoted text.  An unquoted identifier works like double quotes.
+There may not be a space between the \f(CW\*(C`<<\*(C'\fR and the identifier,
+unless the identifier is explicitly quoted.  The terminating string
+must appear by itself (unquoted and with no surrounding whitespace)
+on the terminating line.
+.Sp
+If the terminating string is quoted, the type of quotes used determine
+the treatment of the text.
+.RS 4
+.IP "Double Quotes" 4
+.IX Item "Double Quotes"
+Double quotes indicate that the text will be interpolated using exactly
+the same rules as normal double quoted strings.
+.Sp
+.Vb 3
+\&       print <<EOF;
+\&    The price is $Price.
+\&    EOF
+\&
+\&       print << "EOF"; # same as above
+\&    The price is $Price.
+\&    EOF
+.Ve
+.IP "Single Quotes" 4
+.IX Item "Single Quotes"
+Single quotes indicate the text is to be treated literally with no
+interpolation of its content.  This is similar to single quoted
+strings except that backslashes have no special meaning, with \f(CW\*(C`\e\e\*(C'\fR
+being treated as two backslashes and not one as they would in every
+other quoting construct.
+.Sp
+Just as in the shell, a backslashed bareword following the \f(CW\*(C`<<\*(C'\fR
+means the same thing as a single-quoted string does:
+.Sp
+.Vb 3
+\&        $cost = <<\*(AqVISTA\*(Aq;  # hasta la ...
+\&    That\*(Aqll be $10 please, ma\*(Aqam.
+\&    VISTA
+\&
+\&        $cost = <<\eVISTA;   # Same thing!
+\&    That\*(Aqll be $10 please, ma\*(Aqam.
+\&    VISTA
+.Ve
+.Sp
+This is the only form of quoting in perl where there is no need
+to worry about escaping content, something that code generators
+can and do make good use of.
+.IP Backticks 4
+.IX Item "Backticks"
+The content of the here doc is treated just as it would be if the
+string were embedded in backticks.  Thus the content is interpolated
+as though it were double quoted and then executed via the shell, with
+the results of the execution returned.
+.Sp
+.Vb 3
+\&       print << \`EOC\`; # execute command and get results
+\&    echo hi there
+\&    EOC
+.Ve
+.RE
+.RS 4
+.IP "Indented Here-docs" 4
+.IX Item "Indented Here-docs"
+The here-doc modifier \f(CW\*(C`~\*(C'\fR allows you to indent your here-docs to make
+the code more readable:
+.Sp
+.Vb 5
+\&    if ($some_var) {
+\&      print <<~EOF;
+\&        This is a here\-doc
+\&        EOF
+\&    }
+.Ve
+.Sp
+This will print...
+.Sp
+.Vb 1
+\&    This is a here\-doc
+.Ve
+.Sp
+\&...with no leading whitespace.
+.Sp
+The line containing the delimiter that marks the end of the here-doc
+determines the indentation template for the whole thing.  Compilation
+croaks if any non-empty line inside the here-doc does not begin with the
+precise indentation of the terminating line.  (An empty line consists of
+the single character "\en".)  For example, suppose the terminating line
+begins with a tab character followed by 4 space characters.  Every
+non-empty line in the here-doc must begin with a tab followed by 4
+spaces.  They are stripped from each line, and any leading white space
+remaining on a line serves as the indentation for that line.  Currently,
+only the TAB and SPACE characters are treated as whitespace for this
+purpose.  Tabs and spaces may be mixed, but are matched exactly; tabs
+remain tabs and are not expanded.
+.Sp
+Additional beginning whitespace (beyond what preceded the
+delimiter) will be preserved:
+.Sp
+.Vb 5
+\&    print <<~EOF;
+\&      This text is not indented
+\&        This text is indented with two spaces
+\&                This text is indented with two tabs
+\&      EOF
+.Ve
+.Sp
+Finally, the modifier may be used with all of the forms
+mentioned above:
+.Sp
+.Vb 4
+\&    <<~\eEOF;
+\&    <<~\*(AqEOF\*(Aq
+\&    <<~"EOF"
+\&    <<~\`EOF\`
+.Ve
+.Sp
+And whitespace may be used between the \f(CW\*(C`~\*(C'\fR and quoted delimiters:
+.Sp
+.Vb 1
+\&    <<~ \*(AqEOF\*(Aq; # ... "EOF", \`EOF\`
+.Ve
+.RE
+.RS 4
+.Sp
+It is possible to stack multiple here-docs in a row:
+.Sp
+.Vb 5
+\&       print <<"foo", <<"bar"; # you can stack them
+\&    I said foo.
+\&    foo
+\&    I said bar.
+\&    bar
+\&
+\&       myfunc(<< "THIS", 23, <<\*(AqTHAT\*(Aq);
+\&    Here\*(Aqs a line
+\&    or two.
+\&    THIS
+\&    and here\*(Aqs another.
+\&    THAT
+.Ve
+.Sp
+Just don't forget that you have to put a semicolon on the end
+to finish the statement, as Perl doesn't know you're not going to
+try to do this:
+.Sp
+.Vb 4
+\&       print <<ABC
+\&    179231
+\&    ABC
+\&       + 20;
+.Ve
+.Sp
+If you want to remove the line terminator from your here-docs,
+use \f(CWchomp()\fR.
+.Sp
+.Vb 3
+\&    chomp($string = <<\*(AqEND\*(Aq);
+\&    This is a string.
+\&    END
+.Ve
+.Sp
+If you want your here-docs to be indented with the rest of the code,
+use the \f(CW\*(C`<<~FOO\*(C'\fR construct described under "Indented Here-docs":
+.Sp
+.Vb 4
+\&    $quote = <<~\*(AqFINIS\*(Aq;
+\&       The Road goes ever on and on,
+\&       down from the door where it began.
+\&       FINIS
+.Ve
+.Sp
+If you use a here-doc within a delimited construct, such as in \f(CW\*(C`s///eg\*(C'\fR,
+the quoted material must still come on the line following the
+\&\f(CW\*(C`<<FOO\*(C'\fR marker, which means it may be inside the delimited
+construct:
+.Sp
+.Vb 4
+\&    s/this/<<E . \*(Aqthat\*(Aq
+\&    the other
+\&    E
+\&     . \*(Aqmore \*(Aq/eg;
+.Ve
+.Sp
+It works this way as of Perl 5.18.  Historically, it was inconsistent, and
+you would have to write
+.Sp
+.Vb 4
+\&    s/this/<<E . \*(Aqthat\*(Aq
+\&     . \*(Aqmore \*(Aq/eg;
+\&    the other
+\&    E
+.Ve
+.Sp
+outside of string evals.
+.Sp
+Additionally, quoting rules for the end-of-string identifier are
+unrelated to Perl's quoting rules.  \f(CWq()\fR, \f(CWqq()\fR, and the like are not
+supported in place of \f(CW\*(Aq\*(Aq\fR and \f(CW""\fR, and the only interpolation is for
+backslashing the quoting character:
+.Sp
+.Vb 3
+\&    print << "abc\e"def";
+\&    testing...
+\&    abc"def
+.Ve
+.Sp
+Finally, quoted strings cannot span multiple lines.  The general rule is
+that the identifier must be a string literal.  Stick with that, and you
+should be safe.
+.RE
+.SS "Gory details of parsing quoted constructs"
+.IX Xref "quote, gory details"
+.IX Subsection "Gory details of parsing quoted constructs"
+When presented with something that might have several different
+interpretations, Perl uses the \fBDWIM\fR (that's "Do What I Mean")
+principle to pick the most probable interpretation.  This strategy
+is so successful that Perl programmers often do not suspect the
+ambivalence of what they write.  But from time to time, Perl's
+notions differ substantially from what the author honestly meant.
+.PP
+This section hopes to clarify how Perl handles quoted constructs.
+Although the most common reason to learn this is to unravel labyrinthine
+regular expressions, because the initial steps of parsing are the
+same for all quoting operators, they are all discussed together.
+.PP
+The most important Perl parsing rule is the first one discussed
+below: when processing a quoted construct, Perl first finds the end
+of that construct, then interprets its contents.  If you understand
+this rule, you may skip the rest of this section on the first
+reading.  The other rules are likely to contradict the user's
+expectations much less frequently than this first one.
+.PP
+Some passes discussed below are performed concurrently, but because
+their results are the same, we consider them individually.  For different
+quoting constructs, Perl performs different numbers of passes, from
+one to four, but these passes are always performed in the same order.
+.IP "Finding the end" 4
+.IX Item "Finding the end"
+The first pass is finding the end of the quoted construct.  This results
+in saving to a safe location a copy of the text (between the starting
+and ending delimiters), normalized as necessary to avoid needing to know
+what the original delimiters were.
+.Sp
+If the construct is a here-doc, the ending delimiter is a line
+that has a terminating string as the content.  Therefore \f(CW\*(C`<<EOF\*(C'\fR is
+terminated by \f(CW\*(C`EOF\*(C'\fR immediately followed by \f(CW"\en"\fR and starting
+from the first column of the terminating line.
+When searching for the terminating line of a here-doc, nothing
+is skipped.  In other words, lines after the here-doc syntax
+are compared with the terminating string line by line.
+.Sp
+For the constructs except here-docs, single characters are used as starting
+and ending delimiters.  If the starting delimiter is an opening punctuation
+(that is \f(CW\*(C`(\*(C'\fR, \f(CW\*(C`[\*(C'\fR, \f(CW\*(C`{\*(C'\fR, or \f(CW\*(C`<\*(C'\fR), the ending delimiter is the
+corresponding closing punctuation (that is \f(CW\*(C`)\*(C'\fR, \f(CW\*(C`]\*(C'\fR, \f(CW\*(C`}\*(C'\fR, or \f(CW\*(C`>\*(C'\fR).
+If the starting delimiter is an unpaired character like \f(CW\*(C`/\*(C'\fR or a closing
+punctuation, the ending delimiter is the same as the starting delimiter.
+Therefore a \f(CW\*(C`/\*(C'\fR terminates a \f(CW\*(C`qq//\*(C'\fR construct, while a \f(CW\*(C`]\*(C'\fR terminates
+both \f(CW\*(C`qq[]\*(C'\fR and \f(CW\*(C`qq]]\*(C'\fR constructs.
+.Sp
+When searching for single-character delimiters, escaped delimiters
+and \f(CW\*(C`\e\e\*(C'\fR are skipped.  For example, while searching for terminating \f(CW\*(C`/\*(C'\fR,
+combinations of \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e/\*(C'\fR are skipped.  If the delimiters are
+bracketing, nested pairs are also skipped.  For example, while searching
+for a closing \f(CW\*(C`]\*(C'\fR paired with the opening \f(CW\*(C`[\*(C'\fR, combinations of \f(CW\*(C`\e\e\*(C'\fR, \f(CW\*(C`\e]\*(C'\fR,
+and \f(CW\*(C`\e[\*(C'\fR are all skipped, and nested \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR are skipped as well.
+However, when backslashes are used as the delimiters (like \f(CW\*(C`qq\e\e\*(C'\fR and
+\&\f(CW\*(C`tr\e\e\e\*(C'\fR), nothing is skipped.
+During the search for the end, backslashes that escape delimiters or
+other backslashes are removed (exactly speaking, they are not copied to the
+safe location).
+.Sp
+For constructs with three-part delimiters (\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`y///\*(C'\fR, and
+\&\f(CW\*(C`tr///\*(C'\fR), the search is repeated once more.
+If the first delimiter is not an opening punctuation, the three delimiters must
+be the same, such as \f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`tr)))\*(C'\fR,
+in which case the second delimiter
+terminates the left part and starts the right part at once.
+If the left part is delimited by bracketing punctuation (that is \f(CW\*(C`()\*(C'\fR,
+\&\f(CW\*(C`[]\*(C'\fR, \f(CW\*(C`{}\*(C'\fR, or \f(CW\*(C`<>\*(C'\fR), the right part needs another pair of
+delimiters such as \f(CW\*(C`s(){}\*(C'\fR and \f(CW\*(C`tr[]//\*(C'\fR.  In these cases, whitespace
+and comments are allowed between the two parts, although the comment must follow
+at least one whitespace character; otherwise a character expected as the
+start of the comment may be regarded as the starting delimiter of the right part.
+.Sp
+During this search no attention is paid to the semantics of the construct.
+Thus:
+.Sp
+.Vb 1
+\&    "$hash{"$foo/$bar"}"
+.Ve
+.Sp
+or:
+.Sp
+.Vb 3
+\&    m/
+\&      bar       # NOT a comment, this slash / terminated m//!
+\&     /x
+.Ve
+.Sp
+do not form legal quoted expressions.   The quoted part ends on the
+first \f(CW\*(C`"\*(C'\fR and \f(CW\*(C`/\*(C'\fR, and the rest happens to be a syntax error.
+Because the slash that terminated \f(CW\*(C`m//\*(C'\fR was followed by a \f(CW\*(C`SPACE\*(C'\fR,
+the example above is not \f(CW\*(C`m//x\*(C'\fR, but rather \f(CW\*(C`m//\*(C'\fR with no \f(CW\*(C`/x\*(C'\fR
+modifier.  So the embedded \f(CW\*(C`#\*(C'\fR is interpreted as a literal \f(CW\*(C`#\*(C'\fR.
+.Sp
+Also no attention is paid to \f(CW\*(C`\ec\e\*(C'\fR (multichar control char syntax) during
+this search.  Thus the second \f(CW\*(C`\e\*(C'\fR in \f(CW\*(C`qq/\ec\e/\*(C'\fR is interpreted as a part
+of \f(CW\*(C`\e/\*(C'\fR, and the following \f(CW\*(C`/\*(C'\fR is not recognized as a delimiter.
+Instead, use \f(CW\*(C`\e034\*(C'\fR or \f(CW\*(C`\ex1c\*(C'\fR at the end of quoted constructs.
+.IP Interpolation 4
+.IX Xref "interpolation"
+.IX Item "Interpolation"
+The next step is interpolation in the text obtained, which is now
+delimiter-independent.  There are multiple cases.
+.RS 4
+.ie n .IP """<<\*(AqEOF\*(Aq""" 4
+.el .IP \f(CW<<\*(AqEOF\*(Aq\fR 4
+.IX Item "<<EOF"
+No interpolation is performed.
+Note that the combination \f(CW\*(C`\e\e\*(C'\fR is left intact, since escaped delimiters
+are not available for here-docs.
+.ie n .IP """m\*(Aq\*(Aq"", the pattern of ""s\*(Aq\*(Aq\*(Aq""" 4
+.el .IP "\f(CWm\*(Aq\*(Aq\fR, the pattern of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
+.IX Item "m, the pattern of s"
+No interpolation is performed at this stage.
+Any backslashed sequences including \f(CW\*(C`\e\e\*(C'\fR are treated at the stage
+of "Parsing regular expressions".
+.ie n .IP "\*(Aq\*(Aq, ""q//"", ""tr\*(Aq\*(Aq\*(Aq"", ""y\*(Aq\*(Aq\*(Aq"", the replacement of ""s\*(Aq\*(Aq\*(Aq""" 4
+.el .IP "\f(CW\*(Aq\*(Aq\fR, \f(CWq//\fR, \f(CWtr\*(Aq\*(Aq\*(Aq\fR, \f(CWy\*(Aq\*(Aq\*(Aq\fR, the replacement of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
+.IX Item ", q//, tr, y, the replacement of s"
+The only interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR.
+Therefore \f(CW"\-"\fR in \f(CW\*(C`tr\*(Aq\*(Aq\*(Aq\*(C'\fR and \f(CW\*(C`y\*(Aq\*(Aq\*(Aq\*(C'\fR is treated literally
+as a hyphen and no character range is available.
+\&\f(CW\*(C`\e1\*(C'\fR in the replacement of \f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR does not work as \f(CW$1\fR.
+.ie n .IP """tr///"", ""y///""" 4
+.el .IP "\f(CWtr///\fR, \f(CWy///\fR" 4
+.IX Item "tr///, y///"
+No variable interpolation occurs.  String modifying combinations for
+case and quoting such as \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, and \f(CW\*(C`\eE\*(C'\fR are not recognized.
+The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
+characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are converted to appropriate literals.
+The character \f(CW"\-"\fR is treated specially and therefore \f(CW\*(C`\e\-\*(C'\fR is treated
+as a literal \f(CW"\-"\fR.
+.ie n .IP """"", \`\`, ""qq//"", ""qx//"", ""<file*glob>"", ""<<""EOF""""" 4
+.el .IP "\f(CW""""\fR, \f(CW\`\`\fR, \f(CWqq//\fR, \f(CWqx//\fR, \f(CW<file*glob>\fR, \f(CW<<""EOF""\fR" 4
+.IX Item """"", , qq//, qx//, <file*glob>, <<""EOF"""
+\&\f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR (possibly paired with \f(CW\*(C`\eE\*(C'\fR) are
+converted to corresponding Perl constructs.  Thus, \f(CW"$foo\eQbaz$bar"\fR
+is converted to \f(CW\*(C`$foo\ .\ (quotemeta("baz"\ .\ $bar))\*(C'\fR internally.
+The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
+characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are replaced with appropriate
+expansions.
+.Sp
+Let it be stressed that \fIwhatever falls between \fR\f(CI\*(C`\eQ\*(C'\fR\fI and \fR\f(CI\*(C`\eE\*(C'\fR
+is interpolated in the usual way.  Something like \f(CW"\eQ\e\eE"\fR has
+no \f(CW\*(C`\eE\*(C'\fR inside.  Instead, it has \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\e\e\*(C'\fR, and \f(CW\*(C`E\*(C'\fR, so the
+result is the same as for \f(CW"\e\e\e\eE"\fR.  As a general rule, backslashes
+between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR may lead to counterintuitive results.  So,
+\&\f(CW"\eQ\et\eE"\fR is converted to \f(CWquotemeta("\et")\fR, which is the same
+as \f(CW"\e\e\et"\fR (since TAB is not alphanumeric).  Note also that:
+.Sp
+.Vb 2
+\&  $str = \*(Aq\et\*(Aq;
+\&  return "\eQ$str";
+.Ve
+.Sp
+may be closer to the conjectural \fIintention\fR of the writer of \f(CW"\eQ\et\eE"\fR.
+.Sp
+Interpolated scalars and arrays are converted internally to the \f(CW\*(C`join\*(C'\fR and
+\&\f(CW"."\fR catenation operations.  Thus, \f(CW"$foo\ XXX\ \*(Aq@arr\*(Aq"\fR becomes:
+.Sp
+.Vb 1
+\&  $foo . " XXX \*(Aq" . (join $", @arr) . "\*(Aq";
+.Ve
+.Sp
+All operations above are performed simultaneously, left to right.
+.Sp
+Because the result of \f(CW"\eQ\ \fR\f(CISTRING\fR\f(CW\ \eE"\fR has all metacharacters
+quoted, there is no way to insert a literal \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR inside a
+\&\f(CW\*(C`\eQ\eE\*(C'\fR pair.  If protected by \f(CW\*(C`\e\*(C'\fR, \f(CW\*(C`$\*(C'\fR will be quoted to become
+\&\f(CW"\e\e\e$"\fR; if not, it is interpreted as the start of an interpolated
+scalar.
+.Sp
+Note also that the interpolation code needs to make a decision on
+where the interpolated scalar ends.  For instance, whether
+\&\f(CW"a\ $x\ \->\ {c}"\fR really means:
+.Sp
+.Vb 1
+\&  "a " . $x . " \-> {c}";
+.Ve
+.Sp
+or:
+.Sp
+.Vb 1
+\&  "a " . $x \-> {c};
+.Ve
+.Sp
+Most of the time, the longest possible text that does not include
+spaces between components and which contains matching braces or
+brackets.  because the outcome may be determined by voting based
+on heuristic estimators, the result is not strictly predictable.
+Fortunately, it's usually correct for ambiguous cases.
+.ie n .IP "The replacement of ""s///""" 4
+.el .IP "The replacement of \f(CWs///\fR" 4
+.IX Item "The replacement of s///"
+Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR and interpolation
+happens as with \f(CW\*(C`qq//\*(C'\fR constructs.
+.Sp
+It is at this step that \f(CW\*(C`\e1\*(C'\fR is begrudgingly converted to \f(CW$1\fR in
+the replacement text of \f(CW\*(C`s///\*(C'\fR, in order to correct the incorrigible
+\&\fIsed\fR hackers who haven't picked up the saner idiom yet.  A warning
+is emitted if the \f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR command-line flag
+(that is, the \f(CW$^W\fR variable) was set.
+.ie n .IP """RE"" in ""m?RE?"", ""/RE/"", ""m/RE/"", ""s/RE/foo/""," 4
+.el .IP "\f(CWRE\fR in \f(CWm?RE?\fR, \f(CW/RE/\fR, \f(CWm/RE/\fR, \f(CWs/RE/foo/\fR," 4
+.IX Item "RE in m?RE?, /RE/, m/RE/, s/RE/foo/,"
+Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, \f(CW\*(C`\eE\*(C'\fR,
+and interpolation happens (almost) as with \f(CW\*(C`qq//\*(C'\fR constructs.
+.Sp
+Processing of \f(CW\*(C`\eN{...}\*(C'\fR is also done here, and compiled into an intermediate
+form for the regex compiler.  (This is because, as mentioned below, the regex
+compilation may be done at execution time, and \f(CW\*(C`\eN{...}\*(C'\fR is a compile-time
+construct.)
+.Sp
+However any other combinations of \f(CW\*(C`\e\*(C'\fR followed by a character
+are not substituted but only skipped, in order to parse them
+as regular expressions at the following step.
+As \f(CW\*(C`\ec\*(C'\fR is skipped at this step, \f(CW\*(C`@\*(C'\fR of \f(CW\*(C`\ec@\*(C'\fR in RE is possibly
+treated as an array symbol (for example \f(CW@foo\fR),
+even though the same text in \f(CW\*(C`qq//\*(C'\fR gives interpolation of \f(CW\*(C`\ec@\*(C'\fR.
+.Sp
+Code blocks such as \f(CW\*(C`(?{BLOCK})\*(C'\fR are handled by temporarily passing control
+back to the perl parser, in a similar way that an interpolated array
+subscript expression such as \f(CW"foo$array[1+f("[xyz")]bar"\fR would be.
+.Sp
+Moreover, inside \f(CW\*(C`(?{BLOCK})\*(C'\fR, \f(CW\*(C`(?#\ comment\ )\*(C'\fR, and
+a \f(CW\*(C`#\*(C'\fR\-comment in a \f(CW\*(C`/x\*(C'\fR\-regular expression, no processing is
+performed whatsoever.  This is the first step at which the presence
+of the \f(CW\*(C`/x\*(C'\fR modifier is relevant.
+.Sp
+Interpolation in patterns has several quirks: \f(CW$|\fR, \f(CW$(\fR, \f(CW$)\fR, \f(CW\*(C`@+\*(C'\fR
+and \f(CW\*(C`@\-\*(C'\fR are not interpolated, and constructs \f(CW$var[SOMETHING]\fR are
+voted (by several different estimators) to be either an array element
+or \f(CW$var\fR followed by an RE alternative.  This is where the notation
+\&\f(CW\*(C`${arr[$bar]}\*(C'\fR comes handy: \f(CW\*(C`/${arr[0\-9]}/\*(C'\fR is interpreted as
+array element \f(CW\-9\fR, not as a regular expression from the variable
+\&\f(CW$arr\fR followed by a digit, which would be the interpretation of
+\&\f(CW\*(C`/$arr[0\-9]/\*(C'\fR.  Since voting among different estimators may occur,
+the result is not predictable.
+.Sp
+The lack of processing of \f(CW\*(C`\e\e\*(C'\fR creates specific restrictions on
+the post-processed text.  If the delimiter is \f(CW\*(C`/\*(C'\fR, one cannot get
+the combination \f(CW\*(C`\e/\*(C'\fR into the result of this step.  \f(CW\*(C`/\*(C'\fR will
+finish the regular expression, \f(CW\*(C`\e/\*(C'\fR will be stripped to \f(CW\*(C`/\*(C'\fR on
+the previous step, and \f(CW\*(C`\e\e/\*(C'\fR will be left as is.  Because \f(CW\*(C`/\*(C'\fR is
+equivalent to \f(CW\*(C`\e/\*(C'\fR inside a regular expression, this does not
+matter unless the delimiter happens to be character special to the
+RE engine, such as in \f(CW\*(C`s*foo*bar*\*(C'\fR, \f(CW\*(C`m[foo]\*(C'\fR, or \f(CW\*(C`m?foo?\*(C'\fR; or an
+alphanumeric char, as in:
+.Sp
+.Vb 1
+\&  m m ^ a \es* b mmx;
+.Ve
+.Sp
+In the RE above, which is intentionally obfuscated for illustration, the
+delimiter is \f(CW\*(C`m\*(C'\fR, the modifier is \f(CW\*(C`mx\*(C'\fR, and after delimiter-removal the
+RE is the same as for \f(CW\*(C`m/\ ^\ a\ \es*\ b\ /mx\*(C'\fR.  There's more than one
+reason you're encouraged to restrict your delimiters to non-alphanumeric,
+non-whitespace choices.
+.RE
+.RS 4
+.Sp
+This step is the last one for all constructs except regular expressions,
+which are processed further.
+.RE
+.IP "Parsing regular expressions" 4
+.IX Xref "regexp, parse"
+.IX Item "Parsing regular expressions"
+Previous steps were performed during the compilation of Perl code,
+but this one happens at run time, although it may be optimized to
+be calculated at compile time if appropriate.  After preprocessing
+described above, and possibly after evaluation if concatenation,
+joining, casing translation, or metaquoting are involved, the
+resulting \fIstring\fR is passed to the RE engine for compilation.
+.Sp
+Whatever happens in the RE engine might be better discussed in perlre,
+but for the sake of continuity, we shall do so here.
+.Sp
+This is another step where the presence of the \f(CW\*(C`/x\*(C'\fR modifier is
+relevant.  The RE engine scans the string from left to right and
+converts it into a finite automaton.
+.Sp
+Backslashed characters are either replaced with corresponding
+literal strings (as with \f(CW\*(C`\e{\*(C'\fR), or else they generate special nodes
+in the finite automaton (as with \f(CW\*(C`\eb\*(C'\fR).  Characters special to the
+RE engine (such as \f(CW\*(C`|\*(C'\fR) generate corresponding nodes or groups of
+nodes.  \f(CW\*(C`(?#...)\*(C'\fR comments are ignored.  All the rest is either
+converted to literal strings to match, or else is ignored (as is
+whitespace and \f(CW\*(C`#\*(C'\fR\-style comments if \f(CW\*(C`/x\*(C'\fR is present).
+.Sp
+Parsing of the bracketed character class construct, \f(CW\*(C`[...]\*(C'\fR, is
+rather different than the rule used for the rest of the pattern.
+The terminator of this construct is found using the same rules as
+for finding the terminator of a \f(CW\*(C`{}\*(C'\fR\-delimited construct, the only
+exception being that \f(CW\*(C`]\*(C'\fR immediately following \f(CW\*(C`[\*(C'\fR is treated as
+though preceded by a backslash.
+.Sp
+The terminator of runtime \f(CW\*(C`(?{...})\*(C'\fR is found by temporarily switching
+control to the perl parser, which should stop at the point where the
+logically balancing terminating \f(CW\*(C`}\*(C'\fR is found.
+.Sp
+It is possible to inspect both the string given to RE engine and the
+resulting finite automaton.  See the arguments \f(CW\*(C`debug\*(C'\fR/\f(CW\*(C`debugcolor\*(C'\fR
+in the \f(CW\*(C`use\ re\*(C'\fR pragma, as well as Perl's \fB\-Dr\fR command-line
+switch documented in "Command Switches" in perlrun.
+.IP "Optimization of regular expressions" 4
+.IX Xref "regexp, optimization"
+.IX Item "Optimization of regular expressions"
+This step is listed for completeness only.  Since it does not change
+semantics, details of this step are not documented and are subject
+to change without notice.  This step is performed over the finite
+automaton that was generated during the previous pass.
+.Sp
+It is at this stage that \f(CWsplit()\fR silently optimizes \f(CW\*(C`/^/\*(C'\fR to
+mean \f(CW\*(C`/^/m\*(C'\fR.
+.SS "I/O Operators"
+.IX Xref "operator, i o operator, io io while filehandle <> <<>> @ARGV"
+.IX Subsection "I/O Operators"
+There are several I/O operators you should know about.
+.PP
+A string enclosed by backticks (grave accents) first undergoes
+double-quote interpolation.  It is then interpreted as an external
+command, and the output of that command is the value of the
+backtick string, like in a shell.  In scalar context, a single string
+consisting of all output is returned.  In list context, a list of
+values is returned, one per line of output.  (You can set \f(CW$/\fR to use
+a different line terminator.)  The command is executed each time the
+pseudo-literal is evaluated.  The status value of the command is
+returned in \f(CW$?\fR (see perlvar for the interpretation of \f(CW$?\fR).
+Unlike in \fBcsh\fR, no translation is done on the return data\-\-newlines
+remain newlines.  Unlike in any of the shells, single quotes do not
+hide variable names in the command from interpretation.  To pass a
+literal dollar-sign through to the shell you need to hide it with a
+backslash.  The generalized form of backticks is \f(CW\*(C`qx//\*(C'\fR, or you can
+call the "readpipe" in perlfunc function.  (Because
+backticks always undergo shell expansion as well, see perlsec for
+security concerns.)
+.IX Xref "qx ` `` backtick glob"
+.PP
+In scalar context, evaluating a filehandle in angle brackets yields
+the next line from that file (the newline, if any, included), or
+\&\f(CW\*(C`undef\*(C'\fR at end-of-file or on error.  When \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR
+(sometimes known as file-slurp mode) and the file is empty, it
+returns \f(CW\*(Aq\*(Aq\fR the first time, followed by \f(CW\*(C`undef\*(C'\fR subsequently.
+.PP
+Ordinarily you must assign the returned value to a variable, but
+there is one situation where an automatic assignment happens.  If
+and only if the input symbol is the only thing inside the conditional
+of a \f(CW\*(C`while\*(C'\fR statement (even if disguised as a \f(CWfor(;;)\fR loop),
+the value is automatically assigned to the global variable \f(CW$_\fR,
+destroying whatever was there previously.  (This may seem like an
+odd thing to you, but you'll use the construct in almost every Perl
+script you write.)  The \f(CW$_\fR variable is not implicitly localized.
+You'll have to put a \f(CW\*(C`local\ $_;\*(C'\fR before the loop if you want that
+to happen.  Furthermore, if the input symbol or an explicit assignment
+of the input symbol to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition,
+then the condition actually tests for definedness of the expression's
+value, not for its regular truth value.
+.PP
+Thus the following lines are equivalent:
+.PP
+.Vb 7
+\&    while (defined($_ = <STDIN>)) { print; }
+\&    while ($_ = <STDIN>) { print; }
+\&    while (<STDIN>) { print; }
+\&    for (;<STDIN>;) { print; }
+\&    print while defined($_ = <STDIN>);
+\&    print while ($_ = <STDIN>);
+\&    print while <STDIN>;
+.Ve
+.PP
+This also behaves similarly, but assigns to a lexical variable
+instead of to \f(CW$_\fR:
+.PP
+.Vb 1
+\&    while (my $line = <STDIN>) { print $line }
+.Ve
+.PP
+In these loop constructs, the assigned value (whether assignment
+is automatic or explicit) is then tested to see whether it is
+defined.  The defined test avoids problems where the line has a string
+value that would be treated as false by Perl; for example a "" or
+a \f(CW"0"\fR with no trailing newline.  If you really mean for such values
+to terminate the loop, they should be tested for explicitly:
+.PP
+.Vb 2
+\&    while (($_ = <STDIN>) ne \*(Aq0\*(Aq) { ... }
+\&    while (<STDIN>) { last unless $_; ... }
+.Ve
+.PP
+In other boolean contexts, \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR without an
+explicit \f(CW\*(C`defined\*(C'\fR test or comparison elicits a warning if the
+\&\f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR
+command-line switch (the \f(CW$^W\fR variable) is in effect.
+.PP
+The filehandles STDIN, STDOUT, and STDERR are predefined.  (The
+filehandles \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, and \f(CW\*(C`stderr\*(C'\fR will also work except
+in packages, where they would be interpreted as local identifiers
+rather than global.)  Additional filehandles may be created with
+the \f(CWopen()\fR function, amongst others.  See perlopentut and
+"open" in perlfunc for details on this.
+.IX Xref "stdin stdout sterr"
+.PP
+If a \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR is used in a context that is looking for
+a list, a list comprising all input lines is returned, one line per
+list element.  It's easy to grow to a rather large data space this
+way, so use with care.
+.PP
+\&\f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR  may also be spelled \f(CWreadline(*\fR\f(CIFILEHANDLE\fR\f(CW)\fR.
+See "readline" in perlfunc.
+.PP
+The null filehandle \f(CW\*(C`<>\*(C'\fR (sometimes called the diamond operator) is
+special: it can be used to emulate the
+behavior of \fBsed\fR and \fBawk\fR, and any other Unix filter program
+that takes a list of filenames, doing the same to each line
+of input from all of them.  Input from \f(CW\*(C`<>\*(C'\fR comes either from
+standard input, or from each file listed on the command line.  Here's
+how it works: the first time \f(CW\*(C`<>\*(C'\fR is evaluated, the \f(CW@ARGV\fR array is
+checked, and if it is empty, \f(CW$ARGV[0]\fR is set to \f(CW"\-"\fR, which when opened
+gives you standard input.  The \f(CW@ARGV\fR array is then processed as a list
+of filenames.  The loop
+.PP
+.Vb 3
+\&    while (<>) {
+\&        ...                     # code for each line
+\&    }
+.Ve
+.PP
+is equivalent to the following Perl-like pseudo code:
+.PP
+.Vb 7
+\&    unshift(@ARGV, \*(Aq\-\*(Aq) unless @ARGV;
+\&    while ($ARGV = shift) {
+\&        open(ARGV, $ARGV);
+\&        while (<ARGV>) {
+\&            ...         # code for each line
+\&        }
+\&    }
+.Ve
+.PP
+except that it isn't so cumbersome to say, and will actually work.
+It really does shift the \f(CW@ARGV\fR array and put the current filename
+into the \f(CW$ARGV\fR variable.  It also uses filehandle \fIARGV\fR
+internally.  \f(CW\*(C`<>\*(C'\fR is just a synonym for \f(CW\*(C`<ARGV>\*(C'\fR, which
+is magical.  (The pseudo code above doesn't work because it treats
+\&\f(CW\*(C`<ARGV>\*(C'\fR as non-magical.)
+.PP
+Since the null filehandle uses the two argument form of "open" in perlfunc
+it interprets special characters, so if you have a script like this:
+.PP
+.Vb 3
+\&    while (<>) {
+\&        print;
+\&    }
+.Ve
+.PP
+and call it with \f(CW\*(C`perl\ dangerous.pl\ \*(Aqrm\ \-rfv\ *|\*(Aq\*(C'\fR, it actually opens a
+pipe, executes the \f(CW\*(C`rm\*(C'\fR command and reads \f(CW\*(C`rm\*(C'\fR's output from that pipe.
+If you want all items in \f(CW@ARGV\fR to be interpreted as file names, you
+can use the module \f(CW\*(C`ARGV::readonly\*(C'\fR from CPAN, or use the double
+diamond bracket:
+.PP
+.Vb 3
+\&    while (<<>>) {
+\&        print;
+\&    }
+.Ve
+.PP
+Using double angle brackets inside of a while causes the open to use the
+three argument form (with the second argument being \f(CW\*(C`<\*(C'\fR), so all
+arguments in \f(CW\*(C`ARGV\*(C'\fR are treated as literal filenames (including \f(CW"\-"\fR).
+(Note that for convenience, if you use \f(CW\*(C`<<>>\*(C'\fR and if \f(CW@ARGV\fR is
+empty, it will still read from the standard input.)
+.PP
+You can modify \f(CW@ARGV\fR before the first \f(CW\*(C`<>\*(C'\fR as long as the array ends up
+containing the list of filenames you really want.  Line numbers (\f(CW$.\fR)
+continue as though the input were one big happy file.  See the example
+in "eof" in perlfunc for how to reset line numbers on each file.
+.PP
+If you want to set \f(CW@ARGV\fR to your own list of files, go right ahead.
+This sets \f(CW@ARGV\fR to all plain text files if no \f(CW@ARGV\fR was given:
+.PP
+.Vb 1
+\&    @ARGV = grep { \-f && \-T } glob(\*(Aq*\*(Aq) unless @ARGV;
+.Ve
+.PP
+You can even set them to pipe commands.  For example, this automatically
+filters compressed arguments through \fBgzip\fR:
+.PP
+.Vb 1
+\&    @ARGV = map { /\e.(gz|Z)$/ ? "gzip \-dc < $_ |" : $_ } @ARGV;
+.Ve
+.PP
+If you want to pass switches into your script, you can use one of the
+\&\f(CW\*(C`Getopts\*(C'\fR modules or put a loop on the front like this:
+.PP
+.Vb 7
+\&    while ($_ = $ARGV[0], /^\-/) {
+\&        shift;
+\&        last if /^\-\-$/;
+\&        if (/^\-D(.*)/) { $debug = $1 }
+\&        if (/^\-v/)     { $verbose++  }
+\&        # ...           # other switches
+\&    }
+\&
+\&    while (<>) {
+\&        # ...           # code for each line
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`<>\*(C'\fR symbol will return \f(CW\*(C`undef\*(C'\fR for end-of-file only once.
+If you call it again after this, it will assume you are processing another
+\&\f(CW@ARGV\fR list, and if you haven't set \f(CW@ARGV\fR, will read input from STDIN.
+.PP
+If what the angle brackets contain is a simple scalar variable (for example,
+\&\f(CW$foo\fR), then that variable contains the name of the
+filehandle to input from, or its typeglob, or a reference to the
+same.  For example:
+.PP
+.Vb 2
+\&    $fh = \e*STDIN;
+\&    $line = <$fh>;
+.Ve
+.PP
+If what's within the angle brackets is neither a filehandle nor a simple
+scalar variable containing a filehandle name, typeglob, or typeglob
+reference, it is interpreted as a filename pattern to be globbed, and
+either a list of filenames or the next filename in the list is returned,
+depending on context.  This distinction is determined on syntactic
+grounds alone.  That means \f(CW\*(C`<$x>\*(C'\fR is always a \f(CWreadline()\fR from
+an indirect handle, but \f(CW\*(C`<$hash{key}>\*(C'\fR is always a \f(CWglob()\fR.
+That's because \f(CW$x\fR is a simple scalar variable, but \f(CW$hash{key}\fR is
+not\-\-it's a hash element.  Even \f(CW\*(C`<$x >\*(C'\fR (note the extra space)
+is treated as \f(CW\*(C`glob("$x ")\*(C'\fR, not \f(CWreadline($x)\fR.
+.PP
+One level of double-quote interpretation is done first, but you can't
+say \f(CW\*(C`<$foo>\*(C'\fR because that's an indirect filehandle as explained
+in the previous paragraph.  (In older versions of Perl, programmers
+would insert curly brackets to force interpretation as a filename glob:
+\&\f(CW\*(C`<${foo}>\*(C'\fR.  These days, it's considered cleaner to call the
+internal function directly as \f(CWglob($foo)\fR, which is probably the right
+way to have done it in the first place.)  For example:
+.PP
+.Vb 3
+\&    while (<*.c>) {
+\&        chmod 0644, $_;
+\&    }
+.Ve
+.PP
+is roughly equivalent to:
+.PP
+.Vb 5
+\&    open(FOO, "echo *.c | tr \-s \*(Aq \et\er\ef\*(Aq \*(Aq\e\e012\e\e012\e\e012\e\e012\*(Aq|");
+\&    while (<FOO>) {
+\&        chomp;
+\&        chmod 0644, $_;
+\&    }
+.Ve
+.PP
+except that the globbing is actually done internally using the standard
+\&\f(CW\*(C`File::Glob\*(C'\fR extension.  Of course, the shortest way to do the above is:
+.PP
+.Vb 1
+\&    chmod 0644, <*.c>;
+.Ve
+.PP
+A (file)glob evaluates its (embedded) argument only when it is
+starting a new list.  All values must be read before it will start
+over.  In list context, this isn't important because you automatically
+get them all anyway.  However, in scalar context the operator returns
+the next value each time it's called, or \f(CW\*(C`undef\*(C'\fR when the list has
+run out.  As with filehandle reads, an automatic \f(CW\*(C`defined\*(C'\fR is
+generated when the glob occurs in the test part of a \f(CW\*(C`while\*(C'\fR,
+because legal glob returns (for example,
+a file called \fI0\fR) would otherwise
+terminate the loop.  Again, \f(CW\*(C`undef\*(C'\fR is returned only once.  So if
+you're expecting a single value from a glob, it is much better to
+say
+.PP
+.Vb 1
+\&    ($file) = <blurch*>;
+.Ve
+.PP
+than
+.PP
+.Vb 1
+\&    $file = <blurch*>;
+.Ve
+.PP
+because the latter will alternate between returning a filename and
+returning false.
+.PP
+If you're trying to do variable interpolation, it's definitely better
+to use the \f(CWglob()\fR function, because the older notation can cause people
+to become confused with the indirect filehandle notation.
+.PP
+.Vb 2
+\&    @files = glob("$dir/*.[ch]");
+\&    @files = glob($files[$i]);
+.Ve
+.PP
+If an angle-bracket-based globbing expression is used as the condition of
+a \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`for\*(C'\fR loop, then it will be implicitly assigned to \f(CW$_\fR.
+If either a globbing expression or an explicit assignment of a globbing
+expression to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then
+the condition actually tests for definedness of the expression's value,
+not for its regular truth value.
+.SS "Constant Folding"
+.IX Xref "constant folding folding"
+.IX Subsection "Constant Folding"
+Like C, Perl does a certain amount of expression evaluation at
+compile time whenever it determines that all arguments to an
+operator are static and have no side effects.  In particular, string
+concatenation happens at compile time between literals that don't do
+variable substitution.  Backslash interpolation also happens at
+compile time.  You can say
+.PP
+.Vb 3
+\&      \*(AqNow is the time for all\*(Aq
+\&    . "\en"
+\&    .  \*(Aqgood men to come to.\*(Aq
+.Ve
+.PP
+and this all reduces to one string internally.  Likewise, if
+you say
+.PP
+.Vb 3
+\&    foreach $file (@filenames) {
+\&        if (\-s $file > 5 + 100 * 2**16) {  }
+\&    }
+.Ve
+.PP
+the compiler precomputes the number which that expression
+represents so that the interpreter won't have to.
+.SS No-ops
+.IX Xref "no-op nop"
+.IX Subsection "No-ops"
+Perl doesn't officially have a no-op operator, but the bare constants
+\&\f(CW0\fR and \f(CW1\fR are special-cased not to produce a warning in void
+context, so you can for example safely do
+.PP
+.Vb 1
+\&    1 while foo();
+.Ve
+.SS "Bitwise String Operators"
+.IX Xref "operator, bitwise, string &. |. ^. ~."
+.IX Subsection "Bitwise String Operators"
+Bitstrings of any size may be manipulated by the bitwise operators
+(\f(CW\*(C`~ | & ^\*(C'\fR).
+.PP
+If the operands to a binary bitwise op are strings of different
+sizes, \fB|\fR and \fB^\fR ops act as though the shorter operand had
+additional zero bits on the right, while the \fB&\fR op acts as though
+the longer operand were truncated to the length of the shorter.
+The granularity for such extension or truncation is one or more
+bytes.
+.PP
+.Vb 5
+\&    # ASCII\-based examples
+\&    print "j p \en" ^ " a h";            # prints "JAPH\en"
+\&    print "JA" | "  ph\en";              # prints "japh\en"
+\&    print "japh\enJunk" & \*(Aq_\|_\|_\|_\|_\*(Aq;       # prints "JAPH\en";
+\&    print \*(Aqp N$\*(Aq ^ " E<H\en";            # prints "Perl\en";
+.Ve
+.PP
+If you are intending to manipulate bitstrings, be certain that
+you're supplying bitstrings: If an operand is a number, that will imply
+a \fBnumeric\fR bitwise operation.  You may explicitly show which type of
+operation you intend by using \f(CW""\fR or \f(CW\*(C`0+\*(C'\fR, as in the examples below.
+.PP
+.Vb 4
+\&    $foo =  150  |  105;        # yields 255  (0x96 | 0x69 is 0xFF)
+\&    $foo = \*(Aq150\*(Aq |  105;        # yields 255
+\&    $foo =  150  | \*(Aq105\*(Aq;       # yields 255
+\&    $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq;       # yields string \*(Aq155\*(Aq (under ASCII)
+\&
+\&    $baz = 0+$foo & 0+$bar;     # both ops explicitly numeric
+\&    $biz = "$foo" ^ "$bar";     # both ops explicitly stringy
+.Ve
+.PP
+This somewhat unpredictable behavior can be avoided with the "bitwise"
+feature, new in Perl 5.22.  You can enable it via \f(CWuse\ feature\ \*(Aqbitwise\*(Aq\fR or \f(CW\*(C`use v5.28\*(C'\fR.  Before Perl 5.28, it used to emit a warning
+in the \f(CW"experimental::bitwise"\fR category.  Under this feature, the four
+standard bitwise operators (\f(CW\*(C`~ | & ^\*(C'\fR) are always numeric.  Adding a dot
+after each operator (\f(CW\*(C`~. |. &. ^.\*(C'\fR) forces it to treat its operands as
+strings:
+.PP
+.Vb 9
+\&    use feature "bitwise";
+\&    $foo =  150  |  105;        # yields 255  (0x96 | 0x69 is 0xFF)
+\&    $foo = \*(Aq150\*(Aq |  105;        # yields 255
+\&    $foo =  150  | \*(Aq105\*(Aq;       # yields 255
+\&    $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq;       # yields 255
+\&    $foo =  150  |. 105;        # yields string \*(Aq155\*(Aq
+\&    $foo = \*(Aq150\*(Aq |. 105;        # yields string \*(Aq155\*(Aq
+\&    $foo =  150  |.\*(Aq105\*(Aq;       # yields string \*(Aq155\*(Aq
+\&    $foo = \*(Aq150\*(Aq |.\*(Aq105\*(Aq;       # yields string \*(Aq155\*(Aq
+\&
+\&    $baz = $foo &  $bar;        # both operands numeric
+\&    $biz = $foo ^. $bar;        # both operands stringy
+.Ve
+.PP
+The assignment variants of these operators (\f(CW\*(C`&= |= ^= &.= |.= ^.=\*(C'\fR)
+behave likewise under the feature.
+.PP
+It is a fatal error if an operand contains a character whose ordinal
+value is above 0xFF, and hence not expressible except in UTF\-8.  The
+operation is performed on a non\-UTF\-8 copy for other operands encoded in
+UTF\-8.  See "Byte and Character Semantics" in perlunicode.
+.PP
+See "vec" in perlfunc for information on how to manipulate individual bits
+in a bit vector.
+.SS "Integer Arithmetic"
+.IX Xref "integer"
+.IX Subsection "Integer Arithmetic"
+By default, Perl assumes that it must do most of its arithmetic in
+floating point.  But by saying
+.PP
+.Vb 1
+\&    use integer;
+.Ve
+.PP
+you may tell the compiler to use integer operations
+(see integer for a detailed explanation) from here to the end of
+the enclosing BLOCK.  An inner BLOCK may countermand this by saying
+.PP
+.Vb 1
+\&    no integer;
+.Ve
+.PP
+which lasts until the end of that BLOCK.  Note that this doesn't
+mean everything is an integer, merely that Perl will use integer
+operations for arithmetic, comparison, and bitwise operators.  For
+example, even under \f(CW\*(C`use\ integer\*(C'\fR, if you take the \f(CWsqrt(2)\fR, you'll
+still get \f(CW1.4142135623731\fR or so.
+.PP
+Used on numbers, the bitwise operators (\f(CW\*(C`&\*(C'\fR \f(CW\*(C`|\*(C'\fR \f(CW\*(C`^\*(C'\fR \f(CW\*(C`~\*(C'\fR \f(CW\*(C`<<\*(C'\fR
+\&\f(CW\*(C`>>\*(C'\fR) always produce integral results.  (But see also
+"Bitwise String Operators".)  However, \f(CW\*(C`use\ integer\*(C'\fR still has meaning for
+them.  By default, their results are interpreted as unsigned integers, but
+if \f(CW\*(C`use\ integer\*(C'\fR is in effect, their results are interpreted
+as signed integers.  For example, \f(CW\*(C`~0\*(C'\fR usually evaluates to a large
+integral value.  However, \f(CW\*(C`use\ integer;\ ~0\*(C'\fR is \f(CW\-1\fR on two's-complement
+machines.
+.SS "Floating-point Arithmetic"
+.IX Subsection "Floating-point Arithmetic"
+
+.IX Xref "floating-point floating point float real"
+.PP
+While \f(CW\*(C`use\ integer\*(C'\fR provides integer-only arithmetic, there is no
+analogous mechanism to provide automatic rounding or truncation to a
+certain number of decimal places.  For rounding to a certain number
+of digits, \f(CWsprintf()\fR or \f(CWprintf()\fR is usually the easiest route.
+See perlfaq4.
+.PP
+Floating-point numbers are only approximations to what a mathematician
+would call real numbers.  There are infinitely more reals than floats,
+so some corners must be cut.  For example:
+.PP
+.Vb 2
+\&    printf "%.20g\en", 123456789123456789;
+\&    #        produces 123456789123456784
+.Ve
+.PP
+Testing for exact floating-point equality or inequality is not a
+good idea.  Here's a (relatively expensive) work-around to compare
+whether two floating-point numbers are equal to a particular number of
+decimal places.  See Knuth, volume II, for a more robust treatment of
+this topic.
+.PP
+.Vb 7
+\&    sub fp_equal {
+\&        my ($X, $Y, $POINTS) = @_;
+\&        my ($tX, $tY);
+\&        $tX = sprintf("%.${POINTS}g", $X);
+\&        $tY = sprintf("%.${POINTS}g", $Y);
+\&        return $tX eq $tY;
+\&    }
+.Ve
+.PP
+The POSIX module (part of the standard perl distribution) implements
+\&\f(CWceil()\fR, \f(CWfloor()\fR, and other mathematical and trigonometric functions.
+The \f(CW\*(C`Math::Complex\*(C'\fR module (part of the standard perl distribution)
+defines mathematical functions that work on both the reals and the
+imaginary numbers.  \f(CW\*(C`Math::Complex\*(C'\fR is not as efficient as POSIX, but
+POSIX can't work with complex numbers.
+.PP
+Rounding in financial applications can have serious implications, and
+the rounding method used should be specified precisely.  In these
+cases, it probably pays not to trust whichever system rounding is
+being used by Perl, but to instead implement the rounding function you
+need yourself.
+.SS "Bigger Numbers"
+.IX Xref "number, arbitrary precision"
+.IX Subsection "Bigger Numbers"
+The standard \f(CW\*(C`Math::BigInt\*(C'\fR, \f(CW\*(C`Math::BigRat\*(C'\fR, and
+\&\f(CW\*(C`Math::BigFloat\*(C'\fR modules,
+along with the \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`bigint\*(C'\fR, and \f(CW\*(C`bigrat\*(C'\fR pragmas, provide
+variable-precision arithmetic and overloaded operators, although
+they're currently pretty slow.  At the cost of some space and
+considerable speed, they avoid the normal pitfalls associated with
+limited-precision representations.
+.PP
+.Vb 5
+\&        use 5.010;
+\&        use bigint;  # easy interface to Math::BigInt
+\&        $x = 123456789123456789;
+\&        say $x * $x;
+\&    +15241578780673678515622620750190521
+.Ve
+.PP
+Or with rationals:
+.PP
+.Vb 8
+\&        use 5.010;
+\&        use bigrat;
+\&        $x = 3/22;
+\&        $y = 4/6;
+\&        say "x/y is ", $x/$y;
+\&        say "x*y is ", $x*$y;
+\&        x/y is 9/44
+\&        x*y is 1/11
+.Ve
+.PP
+Several modules let you calculate with unlimited or fixed precision
+(bound only by memory and CPU time).  There
+are also some non-standard modules that
+provide faster implementations via external C libraries.
+.PP
+Here is a short, but incomplete summary:
+.PP
+.Vb 10
+\&  Math::String           treat string sequences like numbers
+\&  Math::FixedPrecision   calculate with a fixed precision
+\&  Math::Currency         for currency calculations
+\&  Bit::Vector            manipulate bit vectors fast (uses C)
+\&  Math::BigIntFast       Bit::Vector wrapper for big numbers
+\&  Math::Pari             provides access to the Pari C library
+\&  Math::Cephes           uses the external Cephes C library (no
+\&                         big numbers)
+\&  Math::Cephes::Fraction fractions via the Cephes library
+\&  Math::GMP              another one using an external C library
+\&  Math::GMPz             an alternative interface to libgmp\*(Aqs big ints
+\&  Math::GMPq             an interface to libgmp\*(Aqs fraction numbers
+\&  Math::GMPf             an interface to libgmp\*(Aqs floating point numbers
+.Ve
+.PP
+Choose wisely.
diff --git a/upstream/mageia-cauldron/man1/perlopenbsd.1 b/upstream/mageia-cauldron/man1/perlopenbsd.1
new file mode 100644
index 00000000..f222a459
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlopenbsd.1
@@ -0,0 +1,84 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOPENBSD 1"
+.TH PERLOPENBSD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlopenbsd \- Perl version 5 on OpenBSD systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of OpenBSD that will affect how Perl
+version 5 (hereafter just Perl) is compiled and/or runs.
+.SS "OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads"
+.IX Subsection "OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads"
+When Perl is configured to use ithreads, it will use re-entrant library calls
+in preference to non-re-entrant versions.  There is an incompatibility in
+OpenBSD's \f(CW\*(C`getprotobyname_r\*(C'\fR and \f(CW\*(C`getservbyname_r\*(C'\fR function in versions 3.7
+and later that will cause a SEGV when called without doing a \f(CW\*(C`bzero\*(C'\fR on
+their return structs prior to calling these functions.  Current Perl's
+should handle this problem correctly.  Older threaded Perls (5.8.6 or earlier)
+will run into this problem.  If you want to run a threaded Perl on OpenBSD
+3.7 or higher, you will need to upgrade to at least Perl 5.8.7.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Steve Peters <steve@fisharerojo.org>
+.PP
+Please report any errors, updates, or suggestions to
+<https://github.com/Perl/perl5/issues>.
diff --git a/upstream/mageia-cauldron/man1/perlopentut.1 b/upstream/mageia-cauldron/man1/perlopentut.1
new file mode 100644
index 00000000..2a4fe8c0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlopentut.1
@@ -0,0 +1,472 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOPENTUT 1"
+.TH PERLOPENTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlopentut \- simple recipes for opening files and pipes in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Whenever you do I/O on a file in Perl, you do so through what in Perl is
+called a \fBfilehandle\fR.  A filehandle is an internal name for an external
+file.  It is the job of the \f(CW\*(C`open\*(C'\fR function to make the association
+between the internal name and the external name, and it is the job
+of the \f(CW\*(C`close\*(C'\fR function to break that association.
+.PP
+For your convenience, Perl sets up a few special filehandles that are
+already open when you run.  These include \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`STDERR\*(C'\fR,
+and \f(CW\*(C`ARGV\*(C'\fR.  Since those are pre-opened, you can use them right away
+without having to go to the trouble of opening them yourself:
+.PP
+.Vb 1
+\&    print STDERR "This is a debugging message.\en";
+\&
+\&    print STDOUT "Please enter something: ";
+\&    $response = <STDIN> // die "how come no input?";
+\&    print STDOUT "Thank you!\en";
+\&
+\&    while (<ARGV>) { ... }
+.Ve
+.PP
+As you see from those examples, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR are output
+handles, and \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`ARGV\*(C'\fR are input handles.  They are
+in all capital letters because they are reserved to Perl, much
+like the \f(CW@ARGV\fR array and the \f(CW%ENV\fR hash are.  Their external
+associations were set up by your shell.
+.PP
+You will need to open every other filehandle on your own. Although there
+are many variants, the most common way to call Perl's \fBopen()\fR function
+is with three arguments and one return value:
+.PP
+\&\f(CW\*(C`    \fR\f(CIOK\fR\f(CW = open(\fR\f(CIHANDLE\fR\f(CW, \fR\f(CIMODE\fR\f(CW, \fR\f(CIPATHNAME\fR\f(CW)\*(C'\fR
+.PP
+Where:
+.IP \fIOK\fR 4
+.IX Item "OK"
+will be some defined value if the open succeeds, but
+\&\f(CW\*(C`undef\*(C'\fR if it fails;
+.IP \fIHANDLE\fR 4
+.IX Item "HANDLE"
+should be an undefined scalar variable to be filled in by the
+\&\f(CW\*(C`open\*(C'\fR function if it succeeds;
+.IP \fIMODE\fR 4
+.IX Item "MODE"
+is the access mode and the encoding format to open the file with;
+.IP \fIPATHNAME\fR 4
+.IX Item "PATHNAME"
+is the external name of the file you want opened.
+.PP
+Most of the complexity of the \f(CW\*(C`open\*(C'\fR function lies in the many
+possible values that the \fIMODE\fR parameter can take on.
+.PP
+One last thing before we show you how to open files: opening
+files does not (usually) automatically lock them in Perl.  See
+perlfaq5 for how to lock.
+.SH "Opening Text Files"
+.IX Header "Opening Text Files"
+.SS "Opening Text Files for Reading"
+.IX Subsection "Opening Text Files for Reading"
+If you want to read from a text file, first open it in
+read-only mode like this:
+.PP
+.Vb 3
+\&    my $filename = "/some/path/to/a/textfile/goes/here";
+\&    my $encoding = ":encoding(UTF\-8)";
+\&    my $handle   = undef;     # this will be filled in on success
+\&
+\&    open($handle, "< $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename for reading: $!";
+.Ve
+.PP
+As with the shell, in Perl the \f(CW"<"\fR is used to open the file in
+read-only mode.  If it succeeds, Perl allocates a brand new filehandle for
+you and fills in your previously undefined \f(CW$handle\fR argument with a
+reference to that handle.
+.PP
+Now you may use functions like \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, and
+\&\f(CW\*(C`sysread\*(C'\fR on that handle.  Probably the most common input function
+is the one that looks like an operator:
+.PP
+.Vb 2
+\&    $line = readline($handle);
+\&    $line = <$handle>;          # same thing
+.Ve
+.PP
+Because the \f(CW\*(C`readline\*(C'\fR function returns \f(CW\*(C`undef\*(C'\fR at end of file or
+upon error, you will sometimes see it used this way:
+.PP
+.Vb 7
+\&    $line = <$handle>;
+\&    if (defined $line) {
+\&        # do something with $line
+\&    }
+\&    else {
+\&        # $line is not valid, so skip it
+\&    }
+.Ve
+.PP
+You can also just quickly \f(CW\*(C`die\*(C'\fR on an undefined value this way:
+.PP
+.Vb 1
+\&    $line = <$handle> // die "no input found";
+.Ve
+.PP
+However, if hitting EOF is an expected and normal event, you do not want to
+exit simply because you have run out of input.  Instead, you probably just want
+to exit an input loop.  You can then test to see if an actual error has caused
+the loop to terminate, and act accordingly:
+.PP
+.Vb 6
+\&    while (<$handle>) {
+\&        # do something with data in $_
+\&    }
+\&    if ($!) {
+\&        die "unexpected error while reading from $filename: $!";
+\&    }
+.Ve
+.PP
+\&\fBA Note on Encodings\fR: Having to specify the text encoding every time
+might seem a bit of a bother.  To set up a default encoding for \f(CW\*(C`open\*(C'\fR so
+that you don't have to supply it each time, you can use the \f(CW\*(C`open\*(C'\fR pragma:
+.PP
+.Vb 1
+\&    use open qw< :encoding(UTF\-8) >;
+.Ve
+.PP
+Once you've done that, you can safely omit the encoding part of the
+open mode:
+.PP
+.Vb 2
+\&    open($handle, "<", $filename)
+\&        || die "$0: can\*(Aqt open $filename for reading: $!";
+.Ve
+.PP
+But never use the bare \f(CW"<"\fR without having set up a default encoding
+first.  Otherwise, Perl cannot know which of the many, many, many possible
+flavors of text file you have, and Perl will have no idea how to correctly
+map the data in your file into actual characters it can work with.  Other
+common encoding formats including \f(CW"ASCII"\fR, \f(CW"ISO\-8859\-1"\fR,
+\&\f(CW"ISO\-8859\-15"\fR, \f(CW"Windows\-1252"\fR, \f(CW"MacRoman"\fR, and even \f(CW"UTF\-16LE"\fR.
+See perlunitut for more about encodings.
+.SS "Opening Text Files for Writing"
+.IX Subsection "Opening Text Files for Writing"
+When you want to write to a file, you first have to decide what to do about
+any existing contents of that file.  You have two basic choices here: to
+preserve or to clobber.
+.PP
+If you want to preserve any existing contents, then you want to open the file
+in append mode.  As in the shell, in Perl you use \f(CW">>"\fR to open an
+existing file in append mode.  \f(CW">>"\fR creates the file if it does not
+already exist.
+.PP
+.Vb 3
+\&    my $handle   = undef;
+\&    my $filename = "/some/path/to/a/textfile/goes/here";
+\&    my $encoding = ":encoding(UTF\-8)";
+\&
+\&    open($handle, ">> $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename for appending: $!";
+.Ve
+.PP
+Now you can write to that filehandle using any of \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`say\*(C'\fR, \f(CW\*(C`write\*(C'\fR, or \f(CW\*(C`syswrite\*(C'\fR.
+.PP
+As noted above, if the file does not already exist, then the append-mode open
+will create it for you.  But if the file does already exist, its contents are
+safe from harm because you will be adding your new text past the end of the
+old text.
+.PP
+On the other hand, sometimes you want to clobber whatever might already be
+there.  To empty out a file before you start writing to it, you can open it
+in write-only mode:
+.PP
+.Vb 3
+\&    my $handle   = undef;
+\&    my $filename = "/some/path/to/a/textfile/goes/here";
+\&    my $encoding = ":encoding(UTF\-8)";
+\&
+\&    open($handle, "> $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename in write\-open mode: $!";
+.Ve
+.PP
+Here again Perl works just like the shell in that the \f(CW">"\fR clobbers
+an existing file.
+.PP
+As with the append mode, when you open a file in write-only mode,
+you can now write to that filehandle using any of \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`say\*(C'\fR, \f(CW\*(C`write\*(C'\fR, or \f(CW\*(C`syswrite\*(C'\fR.
+.PP
+What about read-write mode?  You should probably pretend it doesn't exist,
+because opening text files in read-write mode is unlikely to do what you
+would like.  See perlfaq5 for details.
+.SH "Opening Binary Files"
+.IX Header "Opening Binary Files"
+If the file to be opened contains binary data instead of text characters,
+then the \f(CW\*(C`MODE\*(C'\fR argument to \f(CW\*(C`open\*(C'\fR is a little different.  Instead of
+specifying the encoding, you tell Perl that your data are in raw bytes.
+.PP
+.Vb 3
+\&    my $filename = "/some/path/to/a/binary/file/goes/here";
+\&    my $encoding = ":raw :bytes"
+\&    my $handle   = undef;     # this will be filled in on success
+.Ve
+.PP
+And then open as before, choosing \f(CW"<"\fR, \f(CW">>"\fR, or
+\&\f(CW">"\fR as needed:
+.PP
+.Vb 2
+\&    open($handle, "< $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename for reading: $!";
+\&
+\&    open($handle, ">> $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename for appending: $!";
+\&
+\&    open($handle, "> $encoding", $filename)
+\&        || die "$0: can\*(Aqt open $filename in write\-open mode: $!";
+.Ve
+.PP
+Alternately, you can change to binary mode on an existing handle this way:
+.PP
+.Vb 1
+\&    binmode($handle)    || die "cannot binmode handle";
+.Ve
+.PP
+This is especially handy for the handles that Perl has already opened for you.
+.PP
+.Vb 2
+\&    binmode(STDIN)      || die "cannot binmode STDIN";
+\&    binmode(STDOUT)     || die "cannot binmode STDOUT";
+.Ve
+.PP
+You can also pass \f(CW\*(C`binmode\*(C'\fR an explicit encoding to change it on the fly.
+This isn't exactly "binary" mode, but we still use \f(CW\*(C`binmode\*(C'\fR to do it:
+.PP
+.Vb 2
+\&  binmode(STDIN,  ":encoding(MacRoman)") || die "cannot binmode STDIN";
+\&  binmode(STDOUT, ":encoding(UTF\-8)")    || die "cannot binmode STDOUT";
+.Ve
+.PP
+Once you have your binary file properly opened in the right mode, you can
+use all the same Perl I/O functions as you used on text files.  However,
+you may wish to use the fixed-size \f(CW\*(C`read\*(C'\fR instead of the variable-sized
+\&\f(CW\*(C`readline\*(C'\fR for your input.
+.PP
+Here's an example of how to copy a binary file:
+.PP
+.Vb 3
+\&    my $BUFSIZ   = 64 * (2 ** 10);
+\&    my $name_in  = "/some/input/file";
+\&    my $name_out = "/some/output/flie";
+\&
+\&    my($in_fh, $out_fh, $buffer);
+\&
+\&    open($in_fh,  "<", $name_in)
+\&        || die "$0: cannot open $name_in for reading: $!";
+\&    open($out_fh, ">", $name_out)
+\&        || die "$0: cannot open $name_out for writing: $!";
+\&
+\&    for my $fh ($in_fh, $out_fh)  {
+\&        binmode($fh)               || die "binmode failed";
+\&    }
+\&
+\&    while (read($in_fh, $buffer, $BUFSIZ)) {
+\&        unless (print $out_fh $buffer) {
+\&            die "couldn\*(Aqt write to $name_out: $!";
+\&        }
+\&    }
+\&
+\&    close($in_fh)       || die "couldn\*(Aqt close $name_in: $!";
+\&    close($out_fh)      || die "couldn\*(Aqt close $name_out: $!";
+.Ve
+.SH "Opening Pipes"
+.IX Header "Opening Pipes"
+Perl also lets you open a filehandle into an external program or shell
+command rather than into a file. You can do this in order to pass data
+from your Perl program to an external command for further processing, or
+to receive data from another program for your own Perl program to
+process.
+.PP
+Filehandles into commands are also known as \fIpipes\fR, since they work on
+similar inter-process communication principles as Unix pipelines. Such a
+filehandle has an active program instead of a static file on its
+external end, but in every other sense it works just like a more typical
+file-based filehandle, with all the techniques discussed earlier in this
+article just as applicable.
+.PP
+As such, you open a pipe using the same \f(CW\*(C`open\*(C'\fR call that you use for
+opening files, setting the second (\f(CW\*(C`MODE\*(C'\fR) argument to special
+characters that indicate either an input or an output pipe. Use \f(CW"\-|"\fR for a
+filehandle that will let your Perl program read data from an external
+program, and \f(CW"|\-"\fR for a filehandle that will send data to that
+program instead.
+.SS "Opening a pipe for reading"
+.IX Subsection "Opening a pipe for reading"
+Let's say you'd like your Perl program to process data stored in a nearby
+directory called \f(CW\*(C`unsorted\*(C'\fR, which contains a number of textfiles.
+You'd also like your program to sort all the contents from these files
+into a single, alphabetically sorted list of unique lines before it
+starts processing them.
+.PP
+You could do this through opening an ordinary filehandle into each of
+those files, gradually building up an in-memory array of all the file
+contents you load this way, and finally sorting and filtering that array
+when you've run out of files to load. \fIOr\fR, you could offload all that
+merging and sorting into your operating system's own \f(CW\*(C`sort\*(C'\fR command by
+opening a pipe directly into its output, and get to work that much
+faster.
+.PP
+Here's how that might look:
+.PP
+.Vb 2
+\&    open(my $sort_fh, \*(Aq\-|\*(Aq, \*(Aqsort \-u unsorted/*.txt\*(Aq)
+\&        or die "Couldn\*(Aqt open a pipe into sort: $!";
+\&
+\&    # And right away, we can start reading sorted lines:
+\&    while (my $line = <$sort_fh>) {
+\&        #
+\&        # ... Do something interesting with each $line here ...
+\&        #
+\&    }
+.Ve
+.PP
+The second argument to \f(CW\*(C`open\*(C'\fR, \f(CW"\-|"\fR, makes it a read-pipe into a
+separate program, rather than an ordinary filehandle into a file.
+.PP
+Note that the third argument to \f(CW\*(C`open\*(C'\fR is a string containing the
+program name (\f(CW\*(C`sort\*(C'\fR) plus all its arguments: in this case, \f(CW\*(C`\-u\*(C'\fR to
+specify unqiue sort, and then a fileglob specifying the files to sort.
+The resulting filehandle \f(CW$sort_fh\fR works just like a read-only (\f(CW"<"\fR) filehandle, and your program can subsequently read data
+from it as if it were opened onto an ordinary, single file.
+.SS "Opening a pipe for writing"
+.IX Subsection "Opening a pipe for writing"
+Continuing the previous example, let's say that your program has
+completed its processing, and the results sit in an array called
+\&\f(CW@processed\fR. You want to print these lines to a file called
+\&\f(CW\*(C`numbered.txt\*(C'\fR with a neatly formatted column of line-numbers.
+.PP
+Certainly you could write your own code to do this — or, once again,
+you could kick that work over to another program. In this case, \f(CW\*(C`cat\*(C'\fR,
+running with its own \f(CW\*(C`\-n\*(C'\fR option to activate line numbering, should do
+the trick:
+.PP
+.Vb 2
+\&    open(my $cat_fh, \*(Aq|\-\*(Aq, \*(Aqcat \-n > numbered.txt\*(Aq)
+\&        or die "Couldn\*(Aqt open a pipe into cat: $!";
+\&
+\&    for my $line (@processed) {
+\&        print $cat_fh $line;
+\&    }
+.Ve
+.PP
+Here, we use a second \f(CW\*(C`open\*(C'\fR argument of \f(CW"|\-"\fR, signifying that the
+filehandle assigned to \f(CW$cat_fh\fR should be a write-pipe. We can then
+use it just as we would a write-only ordinary filehandle, including the
+basic function of \f(CW\*(C`print\*(C'\fR\-ing data to it.
+.PP
+Note that the third argument, specifying the command that we wish to
+pipe to, sets up \f(CW\*(C`cat\*(C'\fR to redirect its output via that \f(CW">"\fR
+symbol into the file \f(CW\*(C`numbered.txt\*(C'\fR. This can start to look a little
+tricky, because that same symbol would have meant something
+entirely different had it showed it in the second argument to \f(CW\*(C`open\*(C'\fR!
+But here in the third argument, it's simply part of the shell command that
+Perl will open the pipe into, and Perl itself doesn't invest any special
+meaning to it.
+.SS "Expressing the command as a list"
+.IX Subsection "Expressing the command as a list"
+For opening pipes, Perl offers the option to call \f(CW\*(C`open\*(C'\fR with a list
+comprising the desired command and all its own arguments as separate
+elements, rather than combining them into a single string as in the
+examples above. For instance, we could have phrased the \f(CW\*(C`open\*(C'\fR call in
+the first example like this:
+.PP
+.Vb 2
+\&    open(my $sort_fh, \*(Aq\-|\*(Aq, \*(Aqsort\*(Aq, \*(Aq\-u\*(Aq, glob(\*(Aqunsorted/*.txt\*(Aq))
+\&        or die "Couldn\*(Aqt open a pipe into sort: $!";
+.Ve
+.PP
+When you call \f(CW\*(C`open\*(C'\fR this way, Perl invokes the given command directly,
+bypassing the shell. As such, the shell won't try to interpret any
+special characters within the command's argument list, which might
+overwise have unwanted effects. This can make for safer, less
+error-prone \f(CW\*(C`open\*(C'\fR calls, useful in cases such as passing in variables
+as arguments, or even just referring to filenames with spaces in them.
+.PP
+However, when you \fIdo\fR want to pass a meaningful metacharacter to the
+shell, such with the \f(CW"*"\fR inside that final \f(CW\*(C`unsorted/*.txt\*(C'\fR argument
+here, you can't use this alternate syntax. In this case, we have worked
+around it via Perl's handy \f(CW\*(C`glob\*(C'\fR built-in function, which evaluates
+its argument into a list of filenames — and we can safely pass that
+resulting list right into \f(CW\*(C`open\*(C'\fR, as shown above.
+.PP
+Note also that representing piped-command arguments in list form like
+this doesn't work on every platform. It will work on any Unix-based OS
+that provides a real \f(CW\*(C`fork\*(C'\fR function (e.g. macOS or Linux), as well as
+on Windows when running Perl 5.22 or later.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The full documentation for \f(CW\*(C`open\*(C'\fR
+provides a thorough reference to this function, beyond the best-practice
+basics covered here.
+.SH "AUTHOR and COPYRIGHT"
+.IX Header "AUTHOR and COPYRIGHT"
+Copyright 2013 Tom Christiansen; now maintained by Perl5 Porters
+.PP
+This documentation is free; you can redistribute it and/or modify it under
+the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlos2.1 b/upstream/mageia-cauldron/man1/perlos2.1
new file mode 100644
index 00000000..ab2a20bc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlos2.1
@@ -0,0 +1,2600 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOS2 1"
+.TH PERLOS2 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlos2 \- Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+One can read this document in the following formats:
+.PP
+.Vb 4
+\&        man perlos2
+\&        view perl perlos2
+\&        explorer perlos2.html
+\&        info perlos2
+.Ve
+.PP
+to list some (not all may be available simultaneously), or it may
+be read \fIas is\fR: either as \fIREADME.os2\fR, or \fIpod/perlos2.pod\fR.
+.PP
+To read the \fI.INF\fR version of documentation (\fBvery\fR recommended)
+outside of OS/2, one needs an IBM's reader (may be available on IBM
+ftp sites (?)  (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
+Visual Age C++ 3.5.
+.PP
+A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
+.PP
+.Vb 1
+\&  ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
+.Ve
+.PP
+in \fI?:\eJUST_ADD\eview.exe\fR. This gives one an access to EMX's 
+\&\fI.INF\fR docs as well (text form is available in \fI/emx/doc\fR in 
+EMX's distribution).  There is also a different viewer named xview.
+.PP
+Note that if you have \fIlynx.exe\fR or \fInetscape.exe\fR installed, you can follow WWW links
+from this document in \fI.INF\fR format. If you have EMX docs installed 
+correctly, you can follow library links (you need to have \f(CW\*(C`view emxbook\*(C'\fR
+working by setting \f(CW\*(C`EMXBOOK\*(C'\fR environment variable as it is described
+in EMX docs).
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS Target
+.IX Subsection "Target"
+The target is to make OS/2 one of the best supported platform for
+using/building/developing Perl and \fIPerl applications\fR, as well as
+make Perl the best language to use under OS/2. The secondary target is
+to try to make this work under DOS and Win* as well (but not \fBtoo\fR hard).
+.PP
+The current state is quite close to this target. Known limitations:
+.IP \(bu 5
+Some *nix programs use \fBfork()\fR a lot; with the mostly useful flavors of
+perl for OS/2 (there are several built simultaneously) this is
+supported; but some flavors do not support this (e.g., when Perl is
+called from inside REXX).  Using \fBfork()\fR after
+\&\fIuse\fRing dynamically loading extensions would not work with \fIvery\fR old
+versions of EMX.
+.IP \(bu 5
+You need a separate perl executable \fIperl_\|_.exe\fR (see "perl_\|_.exe")
+if you want to use PM code in your application (as Perl/Tk or OpenGL
+Perl modules do) without having a text-mode window present.
+.Sp
+While using the standard \fIperl.exe\fR from a text-mode window is possible
+too, I have seen cases when this causes degradation of the system stability.
+Using \fIperl_\|_.exe\fR avoids such a degradation.
+.IP \(bu 5
+There is no simple way to access WPS objects. The only way I know
+is via \f(CW\*(C`OS2::REXX\*(C'\fR and \f(CW\*(C`SOM\*(C'\fR extensions (see OS2::REXX, SOM).
+However, we do not have access to
+convenience methods of Object-REXX. (Is it possible at all? I know
+of no Object-REXX API.)  The \f(CW\*(C`SOM\*(C'\fR extension (currently in alpha-text)
+may eventually remove this shortcoming; however, due to the fact that
+DII is not supported by the \f(CW\*(C`SOM\*(C'\fR module, using \f(CW\*(C`SOM\*(C'\fR is not as
+convenient as one would like it.
+.PP
+Please keep this list up-to-date by informing me about other items.
+.SS "Other OSes"
+.IX Subsection "Other OSes"
+Since OS/2 port of perl uses a remarkable EMX environment, it can
+run (and build extensions, and \- possibly \- be built itself) under any
+environment which can run EMX. The current list is DOS,
+DOS\-inside\-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
+only one works, see "\fIperl_.exe\fR".
+.PP
+Note that not all features of Perl are available under these
+environments. This depends on the features the \fIextender\fR \- most
+probably RSX \- decided to implement.
+.PP
+Cf. "Prerequisites".
+.SS Prerequisites
+.IX Subsection "Prerequisites"
+.IP EMX 6
+.IX Item "EMX"
+EMX runtime is required (may be substituted by RSX). Note that
+it is possible to make \fIperl_.exe\fR to run under DOS without any
+external support by binding \fIemx.exe\fR/\fIrsx.exe\fR to it, see \fBemxbind\fR\|(1).
+Note that under DOS for best results one should use RSX runtime, which
+has much more functions working (like \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`popen\*(C'\fR and so on). In
+fact RSX is required if there is no VCPI present. Note the
+RSX requires DPMI.  Many implementations of DPMI are known to be very
+buggy, beware!
+.Sp
+Only the latest runtime is supported, currently \f(CW\*(C`0.9d fix 03\*(C'\fR. Perl may run
+under earlier versions of EMX, but this is not tested.
+.Sp
+One can get different parts of EMX from, say
+.Sp
+.Vb 2
+\&  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/
+\&  http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2/dev/emx/v0.9d/
+.Ve
+.Sp
+The runtime component should have the name \fIemxrt.zip\fR.
+.Sp
+\&\fBNOTE\fR. When using \fIemx.exe\fR/\fIrsx.exe\fR, it is enough to have them on your path. One
+does not need to specify them explicitly (though this
+.Sp
+.Vb 1
+\&  emx perl_.exe \-de 0
+.Ve
+.Sp
+will work as well.)
+.IP RSX 6
+.IX Item "RSX"
+To run Perl on DPMI platforms one needs RSX runtime. This is
+needed under DOS\-inside\-OS/2, Win0.3*, Win0.95 and WinNT (see 
+"Other OSes"). RSX would not work with VCPI
+only, as EMX would, it requires DMPI.
+.Sp
+Having RSX and the latest \fIsh.exe\fR one gets a fully functional
+\&\fB*nix\fR\-ish environment under DOS, say, \f(CW\*(C`fork\*(C'\fR, \f(CW\`\`\fR and
+pipe\-\f(CW\*(C`open\*(C'\fR work. In fact, MakeMaker works (for static build), so one
+can have Perl development environment under DOS.
+.Sp
+One can get RSX from, say
+.Sp
+.Vb 2
+\&  http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
+\&  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/
+.Ve
+.Sp
+Contact the author on \f(CW\*(C`rainer@mathematik.uni\-bielefeld.de\*(C'\fR.
+.Sp
+The latest \fIsh.exe\fR with DOS hooks is available in
+.Sp
+.Vb 1
+\&  http://www.ilyaz.org/software/os2/
+.Ve
+.Sp
+as \fIsh_dos.zip\fR or under similar names starting with \f(CW\*(C`sh\*(C'\fR, \f(CW\*(C`pdksh\*(C'\fR etc.
+.IP HPFS 6
+.IX Item "HPFS"
+Perl does not care about file systems, but the perl library contains
+many files with long names, so to install it intact one needs a file
+system which supports long file names.
+.Sp
+Note that if you do not plan to build the perl itself, it may be
+possible to fool EMX to truncate file names. This is not supported,
+read EMX docs to see how to do it.
+.IP pdksh 6
+.IX Item "pdksh"
+To start external programs with complicated command lines (like with
+pipes in between, and/or quoting of arguments), Perl uses an external
+shell. With EMX port such shell should be named \fIsh.exe\fR, and located
+either in the wired-in-during-compile locations (usually \fIF:/bin\fR),
+or in configurable location (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR").
+.Sp
+For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
+under DOS (with "RSX") as well, see
+.Sp
+.Vb 1
+\&  http://www.ilyaz.org/software/os2/
+.Ve
+.SS "Starting Perl programs under OS/2 (and DOS and...)"
+.IX Subsection "Starting Perl programs under OS/2 (and DOS and...)"
+Start your Perl program \fIfoo.pl\fR with arguments \f(CW\*(C`arg1 arg2 arg3\*(C'\fR the
+same way as on any other platform, by
+.PP
+.Vb 1
+\&        perl foo.pl arg1 arg2 arg3
+.Ve
+.PP
+If you want to specify perl options \f(CW\*(C`\-my_opts\*(C'\fR to the perl itself (as
+opposed to your program), use
+.PP
+.Vb 1
+\&        perl \-my_opts foo.pl arg1 arg2 arg3
+.Ve
+.PP
+Alternately, if you use OS/2\-ish shell, like CMD or 4os2, put
+the following at the start of your perl script:
+.PP
+.Vb 1
+\&        extproc perl \-S \-my_opts
+.Ve
+.PP
+rename your program to \fIfoo.cmd\fR, and start it by typing
+.PP
+.Vb 1
+\&        foo arg1 arg2 arg3
+.Ve
+.PP
+Note that because of stupid OS/2 limitations the full path of the perl
+script is not available when you use \f(CW\*(C`extproc\*(C'\fR, thus you are forced to
+use \f(CW\*(C`\-S\*(C'\fR perl switch, and your script should be on the \f(CW\*(C`PATH\*(C'\fR. As a plus
+side, if you know a full path to your script, you may still start it
+with
+.PP
+.Vb 1
+\&        perl ../../blah/foo.cmd arg1 arg2 arg3
+.Ve
+.PP
+(note that the argument \f(CW\*(C`\-my_opts\*(C'\fR is taken care of by the \f(CW\*(C`extproc\*(C'\fR line
+in your script, see \f(CW"extproc"\fR on the first line).
+.PP
+To understand what the above \fImagic\fR does, read perl docs about \f(CW\*(C`\-S\*(C'\fR
+switch \- see perlrun, and cmdref about \f(CW\*(C`extproc\*(C'\fR:
+.PP
+.Vb 4
+\&        view perl perlrun
+\&        man perlrun
+\&        view cmdref extproc
+\&        help extproc
+.Ve
+.PP
+or whatever method you prefer.
+.PP
+There are also endless possibilities to use \fIexecutable extensions\fR of
+4os2, \fIassociations\fR of WPS and so on... However, if you use
+*nixish shell (like \fIsh.exe\fR supplied in the binary distribution),
+you need to follow the syntax specified in "Command Switches" in perlrun.
+.PP
+Note that \fB\-S\fR switch supports scripts with additional extensions 
+\&\fI.cmd\fR, \fI.btm\fR, \fI.bat\fR, \fI.pl\fR as well.
+.SS "Starting OS/2 (and DOS) programs under Perl"
+.IX Subsection "Starting OS/2 (and DOS) programs under Perl"
+This is what \fBsystem()\fR (see "system" in perlfunc), \f(CW\`\`\fR (see
+"I/O Operators" in perlop), and \fIopen pipe\fR (see "open" in perlfunc)
+are for. (Avoid \fBexec()\fR (see "exec" in perlfunc) unless you know what you
+do).
+.PP
+Note however that to use some of these operators you need to have a
+sh-syntax shell installed (see "Pdksh", 
+"Frequently asked questions"), and perl should be able to find it
+(see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR").
+.PP
+The cases when the shell is used are:
+.IP 1. 4
+One-argument \fBsystem()\fR (see "system" in perlfunc), \fBexec()\fR (see "exec" in perlfunc)
+with redirection or shell meta-characters;
+.IP 2. 4
+Pipe-open (see "open" in perlfunc) with the command which contains redirection 
+or shell meta-characters;
+.IP 3. 4
+Backticks \f(CW\`\`\fR (see "I/O Operators" in perlop) with the command which contains
+redirection or shell meta-characters;
+.IP 4. 4
+If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is a script
+with the "magic" \f(CW\*(C`#!\*(C'\fR line or \f(CW\*(C`extproc\*(C'\fR line which specifies shell;
+.IP 5. 4
+If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is a script
+without "magic" line, and \f(CW$ENV{EXECSHELL}\fR is set to shell;
+.IP 6. 4
+If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is not
+found (is not this remark obsolete?);
+.IP 7. 4
+For globbing (see "glob" in perlfunc, "I/O Operators" in perlop)
+(obsolete? Perl uses builtin globbing nowadays...).
+.PP
+For the sake of speed for a common case, in the above algorithms 
+backslashes in the command name are not considered as shell metacharacters.
+.PP
+Perl starts scripts which begin with cookies
+\&\f(CW\*(C`extproc\*(C'\fR or \f(CW\*(C`#!\*(C'\fR directly, without an intervention of shell.  Perl uses the
+same algorithm to find the executable as \fIpdksh\fR: if the path
+on \f(CW\*(C`#!\*(C'\fR line does not work, and contains \f(CW\*(C`/\*(C'\fR, then the directory
+part of the executable is ignored, and the executable
+is searched in \fI.\fR and on \f(CW\*(C`PATH\*(C'\fR.  To find arguments for these scripts
+Perl uses a different algorithm than \fIpdksh\fR: up to 3 arguments are 
+recognized, and trailing whitespace is stripped.
+.PP
+If a script
+does not contain such a cooky, then to avoid calling \fIsh.exe\fR, Perl uses
+the same algorithm as \fIpdksh\fR: if \f(CW$ENV{EXECSHELL}\fR is set, the
+script is given as the first argument to this command, if not set, then
+\&\f(CW\*(C`$ENV{COMSPEC} /c\*(C'\fR is used (or a hardwired guess if \f(CW$ENV{COMSPEC}\fR is
+not set).
+.PP
+When starting scripts directly, Perl uses exactly the same algorithm as for 
+the search of script given by \fB\-S\fR command-line option: it will look in
+the current directory, then on components of \f(CW$ENV{PATH}\fR using the 
+following order of appended extensions: no extension, \fI.cmd\fR, \fI.btm\fR, 
+\&\fI.bat\fR, \fI.pl\fR.
+.PP
+Note that Perl will start to look for scripts only if OS/2 cannot start the
+specified application, thus \f(CW\*(C`system \*(Aqblah\*(Aq\*(C'\fR will not look for a script if 
+there is an executable file \fIblah.exe\fR \fIanywhere\fR on \f(CW\*(C`PATH\*(C'\fR.  In
+other words, \f(CW\*(C`PATH\*(C'\fR is essentially searched twice: once by the OS for
+an executable, then by Perl for scripts.
+.PP
+Note also that executable files on OS/2 can have an arbitrary extension, but
+\&\fI.exe\fR will be automatically appended if no dot is present in the name.  The
+workaround is as simple as that:  since \fIblah.\fR and \fIblah\fR denote the same
+file (at list on FAT and HPFS file systems), to start an executable residing in
+file \fIn:/bin/blah\fR (no extension) give an argument \f(CW\*(C`n:/bin/blah.\*(C'\fR (dot
+appended) to \fBsystem()\fR.
+.PP
+Perl will start PM programs from VIO (=text\-mode) Perl process in a
+separate PM session;
+the opposite is not true: when you start a non-PM program from a PM
+Perl process, Perl would not run it in a separate session.  If a separate
+session is desired, either ensure
+that shell will be used, as in \f(CW\*(C`system \*(Aqcmd /c myprog\*(Aq\*(C'\fR, or start it using
+optional arguments to \fBsystem()\fR documented in \f(CW\*(C`OS2::Process\*(C'\fR module.  This
+is considered to be a feature.
+.SH "Frequently asked questions"
+.IX Header "Frequently asked questions"
+.SS """It does not work"""
+.IX Subsection """It does not work"""
+Perl binary distributions come with a \fItestperl.cmd\fR script which tries
+to detect common problems with misconfigured installations.  There is a
+pretty large chance it will discover which step of the installation you
+managed to goof.  \f(CW\*(C`;\-)\*(C'\fR
+.SS "I cannot run external programs"
+.IX Subsection "I cannot run external programs"
+.IP \(bu 4
+Did you run your programs with \f(CW\*(C`\-w\*(C'\fR switch? See 
+"Starting OS/2 (and DOS) programs under Perl".
+.IP \(bu 4
+Do you try to run \fIinternal\fR shell commands, like \f(CW\`copy a b\`\fR
+(internal for \fIcmd.exe\fR), or \f(CW\`glob a*b\`\fR (internal for ksh)? You
+need to specify your shell explicitly, like \f(CW\`cmd /c copy a b\`\fR,
+since Perl cannot deduce which commands are internal to your shell.
+.SS "I cannot embed perl into my program, or use \fIperl.dll\fP from my program."
+.IX Subsection "I cannot embed perl into my program, or use perl.dll from my program."
+.ie n .IP "Is your program EMX-compiled with ""\-Zmt \-Zcrtdll""?" 4
+.el .IP "Is your program EMX-compiled with \f(CW\-Zmt \-Zcrtdll\fR?" 4
+.IX Item "Is your program EMX-compiled with -Zmt -Zcrtdll?"
+Well, nowadays Perl DLL should be usable from a differently compiled
+program too...  If you can run Perl code from REXX scripts (see
+OS2::REXX), then there are some other aspect of interaction which
+are overlooked by the current hackish code to support
+differently-compiled principal programs.
+.Sp
+If everything else fails, you need to build a stand-alone DLL for
+perl. Contact me, I did it once. Sockets would not work, as a lot of
+other stuff.
+.IP "Did you use ExtUtils::Embed?" 4
+.IX Item "Did you use ExtUtils::Embed?"
+Some time ago I had reports it does not work.  Nowadays it is checked
+in the Perl test suite, so grep \fI./t\fR subdirectory of the build tree
+(as well as \fI*.t\fR files in the \fI./lib\fR subdirectory) to find how it
+should be done "correctly".
+.ie n .SS "\`\` and pipe\-""open"" do not work under DOS."
+.el .SS "\f(CW\`\`\fP and pipe\-\f(CWopen\fP do not work under DOS."
+.IX Subsection " and pipe-open do not work under DOS."
+This may a variant of just "I cannot run external programs", or a
+deeper problem. Basically: you \fIneed\fR RSX (see "Prerequisites")
+for these commands to work, and you may need a port of \fIsh.exe\fR which
+understands command arguments. One of such ports is listed in
+"Prerequisites" under RSX. Do not forget to set variable
+"\f(CW\*(C`PERL_SH_DIR\*(C'\fR" as well.
+.PP
+DPMI is required for RSX.
+.ie n .SS "Cannot start ""find.exe ""pattern"" file"""
+.el .SS "Cannot start \f(CWfind.exe ""pattern"" file\fP"
+.IX Subsection "Cannot start find.exe ""pattern"" file"
+The whole idea of the "standard C API to start applications" is that
+the forms \f(CW\*(C`foo\*(C'\fR and \f(CW"foo"\fR of program arguments are completely
+interchangeable.  \fIfind\fR breaks this paradigm;
+.PP
+.Vb 2
+\&  find "pattern" file
+\&  find pattern file
+.Ve
+.PP
+are not equivalent; \fIfind\fR cannot be started directly using the above
+API.  One needs a way to surround the doublequotes in some other
+quoting construction, necessarily having an extra non-Unixish shell in
+between.
+.PP
+Use one of
+.PP
+.Vb 2
+\&  system \*(Aqcmd\*(Aq, \*(Aq/c\*(Aq, \*(Aqfind "pattern" file\*(Aq;
+\&  \`cmd /c \*(Aqfind "pattern" file\*(Aq\`
+.Ve
+.PP
+This would start \fIfind.exe\fR via \fIcmd.exe\fR via \f(CW\*(C`sh.exe\*(C'\fR via
+\&\f(CW\*(C`perl.exe\*(C'\fR, but this is a price to pay if you want to use
+non-conforming program.
+.SH INSTALLATION
+.IX Header "INSTALLATION"
+.SS "Automatic binary installation"
+.IX Subsection "Automatic binary installation"
+The most convenient way of installing a binary distribution of perl is via perl installer
+\&\fIinstall.exe\fR. Just follow the instructions, and 99% of the
+installation blues would go away.
+.PP
+Note however, that you need to have \fIunzip.exe\fR on your path, and
+EMX environment \fIrunning\fR. The latter means that if you just
+installed EMX, and made all the needed changes to \fIConfig.sys\fR,
+you may need to reboot in between. Check EMX runtime by running
+.PP
+.Vb 1
+\&        emxrev
+.Ve
+.PP
+Binary installer also creates a folder on your desktop with some useful
+objects.  If you need to change some aspects of the work of the binary
+installer, feel free to edit the file \fIPerl.pkg\fR.  This may be useful
+e.g., if you need to run the installer many times and do not want to
+make many interactive changes in the GUI.
+.PP
+\&\fBThings not taken care of by automatic binary installation:\fR
+.ie n .IP """PERL_BADLANG""" 15
+.el .IP \f(CWPERL_BADLANG\fR 15
+.IX Item "PERL_BADLANG"
+may be needed if you change your codepage \fIafter\fR perl installation,
+and the new value is not supported by EMX. See "\f(CW\*(C`PERL_BADLANG\*(C'\fR".
+.ie n .IP """PERL_BADFREE""" 15
+.el .IP \f(CWPERL_BADFREE\fR 15
+.IX Item "PERL_BADFREE"
+see "\f(CW\*(C`PERL_BADFREE\*(C'\fR".
+.IP \fIConfig.pm\fR 15
+.IX Item "Config.pm"
+This file resides somewhere deep in the location you installed your
+perl library, find it out by
+.Sp
+.Vb 1
+\&  perl \-MConfig \-le "print $INC{\*(AqConfig.pm\*(Aq}"
+.Ve
+.Sp
+While most important values in this file \fIare\fR updated by the binary
+installer, some of them may need to be hand-edited. I know no such
+data, please keep me informed if you find one.  Moreover, manual
+changes to the installed version may need to be accompanied by an edit
+of this file.
+.PP
+\&\fBNOTE\fR. Because of a typo the binary installer of 5.00305
+would install a variable \f(CW\*(C`PERL_SHPATH\*(C'\fR into \fIConfig.sys\fR. Please
+remove this variable and put \f(CW"PERL_SH_DIR"\fR instead.
+.SS "Manual binary installation"
+.IX Subsection "Manual binary installation"
+As of version 5.00305, OS/2 perl binary distribution comes split
+into 11 components. Unfortunately, to enable configurable binary
+installation, the file paths in the zip files are not absolute, but
+relative to some directory.
+.PP
+Note that the extraction with the stored paths is still necessary
+(default with unzip, specify \f(CW\*(C`\-d\*(C'\fR to pkunzip). However, you
+need to know where to extract the files. You need also to manually
+change entries in \fIConfig.sys\fR to reflect where did you put the
+files. Note that if you have some primitive unzipper (like
+\&\f(CW\*(C`pkunzip\*(C'\fR), you may get a lot of warnings/errors during
+unzipping. Upgrade to \f(CW\*(C`(w)unzip\*(C'\fR.
+.PP
+Below is the sample of what to do to reproduce the configuration on my
+machine.  In \fIVIEW.EXE\fR you can press \f(CW\*(C`Ctrl\-Insert\*(C'\fR now, and
+cut-and-paste from the resulting file \- created in the directory you
+started \fIVIEW.EXE\fR from.
+.PP
+For each component, we mention environment variables related to each
+installation directory.  Either choose directories to match your
+values of the variables, or create/append\-to variables to take into
+account the directories.
+.IP "Perl VIO and PM executables (dynamically linked)" 3
+.IX Item "Perl VIO and PM executables (dynamically linked)"
+.Vb 2
+\&  unzip perl_exc.zip *.exe *.ico \-d f:/emx.add/bin
+\&  unzip perl_exc.zip *.dll \-d f:/emx.add/dll
+.Ve
+.Sp
+(have the directories with \f(CW\*(C`*.exe\*(C'\fR on PATH, and \f(CW\*(C`*.dll\*(C'\fR on
+LIBPATH);
+.IP "Perl_ VIO executable (statically linked)" 3
+.IX Item "Perl_ VIO executable (statically linked)"
+.Vb 1
+\&  unzip perl_aou.zip \-d f:/emx.add/bin
+.Ve
+.Sp
+(have the directory on PATH);
+.IP "Executables for Perl utilities" 3
+.IX Item "Executables for Perl utilities"
+.Vb 1
+\&  unzip perl_utl.zip \-d f:/emx.add/bin
+.Ve
+.Sp
+(have the directory on PATH);
+.IP "Main Perl library" 3
+.IX Item "Main Perl library"
+.Vb 1
+\&  unzip perl_mlb.zip \-d f:/perllib/lib
+.Ve
+.Sp
+If this directory is exactly the same as the prefix which was compiled
+into \fIperl.exe\fR, you do not need to change
+anything. However, for perl to find the library if you use a different
+path, you need to
+\&\f(CW\*(C`set PERLLIB_PREFIX\*(C'\fR in \fIConfig.sys\fR, see "\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR".
+.IP "Additional Perl modules" 3
+.IX Item "Additional Perl modules"
+.Vb 1
+\&  unzip perl_ste.zip \-d f:/perllib/lib/site_perl/5.38.2/
+.Ve
+.Sp
+Same remark as above applies.  Additionally, if this directory is not
+one of directories on \f(CW@INC\fR (and \f(CW@INC\fR is influenced by \f(CW\*(C`PERLLIB_PREFIX\*(C'\fR), you
+need to put this
+directory and subdirectory \fI./os2\fR in \f(CW\*(C`PERLLIB\*(C'\fR or \f(CW\*(C`PERL5LIB\*(C'\fR
+variable. Do not use \f(CW\*(C`PERL5LIB\*(C'\fR unless you have it set already. See
+"ENVIRONMENT" in perl.
+.Sp
+\&\fB[Check whether this extraction directory is still applicable with
+the new directory structure layout!]\fR
+.IP "Tools to compile Perl modules" 3
+.IX Item "Tools to compile Perl modules"
+.Vb 1
+\&  unzip perl_blb.zip \-d f:/perllib/lib
+.Ve
+.Sp
+Same remark as for \fIperl_ste.zip\fR.
+.IP "Manpages for Perl and utilities" 3
+.IX Item "Manpages for Perl and utilities"
+.Vb 1
+\&  unzip perl_man.zip \-d f:/perllib/man
+.Ve
+.Sp
+This directory should better be on \f(CW\*(C`MANPATH\*(C'\fR. You need to have a
+working \fIman\fR to access these files.
+.IP "Manpages for Perl modules" 3
+.IX Item "Manpages for Perl modules"
+.Vb 1
+\&  unzip perl_mam.zip \-d f:/perllib/man
+.Ve
+.Sp
+This directory should better be on \f(CW\*(C`MANPATH\*(C'\fR. You need to have a
+working man to access these files.
+.IP "Source for Perl documentation" 3
+.IX Item "Source for Perl documentation"
+.Vb 1
+\&  unzip perl_pod.zip \-d f:/perllib/lib
+.Ve
+.Sp
+This is used by the \f(CW\*(C`perldoc\*(C'\fR program (see perldoc), and may be used to
+generate HTML documentation usable by WWW browsers, and
+documentation in zillions of other formats: \f(CW\*(C`info\*(C'\fR, \f(CW\*(C`LaTeX\*(C'\fR,
+\&\f(CW\*(C`Acrobat\*(C'\fR, \f(CW\*(C`FrameMaker\*(C'\fR and so on.  [Use programs such as
+\&\fIpod2latex\fR etc.]
+.IP "Perl manual in \fI.INF\fR format" 3
+.IX Item "Perl manual in .INF format"
+.Vb 1
+\&  unzip perl_inf.zip \-d d:/os2/book
+.Ve
+.Sp
+This directory should better be on \f(CW\*(C`BOOKSHELF\*(C'\fR.
+.IP Pdksh 3
+.IX Item "Pdksh"
+.Vb 1
+\&  unzip perl_sh.zip \-d f:/bin
+.Ve
+.Sp
+This is used by perl to run external commands which explicitly
+require shell, like the commands using \fIredirection\fR and \fIshell
+metacharacters\fR. It is also used instead of explicit \fI/bin/sh\fR.
+.Sp
+Set \f(CW\*(C`PERL_SH_DIR\*(C'\fR (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR") if you move \fIsh.exe\fR from
+the above location.
+.Sp
+\&\fBNote.\fR It may be possible to use some other sh-compatible shell (untested).
+.PP
+After you installed the components you needed and updated the
+\&\fIConfig.sys\fR correspondingly, you need to hand-edit
+\&\fIConfig.pm\fR. This file resides somewhere deep in the location you
+installed your perl library, find it out by
+.PP
+.Vb 1
+\&  perl \-MConfig \-le "print $INC{\*(AqConfig.pm\*(Aq}"
+.Ve
+.PP
+You need to correct all the entries which look like file paths (they
+currently start with \f(CW\*(C`f:/\*(C'\fR).
+.SS \fBWarning\fP
+.IX Subsection "Warning"
+The automatic and manual perl installation leave precompiled paths
+inside perl executables. While these paths are overwritable (see
+"\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR", "\f(CW\*(C`PERL_SH_DIR\*(C'\fR"), some people may prefer
+binary editing of paths inside the executables/DLLs.
+.SH "Accessing documentation"
+.IX Header "Accessing documentation"
+Depending on how you built/installed perl you may have (otherwise
+identical) Perl documentation in the following formats:
+.SS "OS/2 \fI.INF\fP file"
+.IX Subsection "OS/2 .INF file"
+Most probably the most convenient form. Under OS/2 view it as
+.PP
+.Vb 4
+\&  view perl
+\&  view perl perlfunc
+\&  view perl less
+\&  view perl ExtUtils::MakeMaker
+.Ve
+.PP
+(currently the last two may hit a wrong location, but this may improve
+soon). Under Win* see "SYNOPSIS".
+.PP
+If you want to build the docs yourself, and have \fIOS/2 toolkit\fR, run
+.PP
+.Vb 1
+\&        pod2ipf > perl.ipf
+.Ve
+.PP
+in \fI/perllib/lib/pod\fR directory, then
+.PP
+.Vb 1
+\&        ipfc /inf perl.ipf
+.Ve
+.PP
+(Expect a lot of errors during the both steps.) Now move it on your
+BOOKSHELF path.
+.SS "Plain text"
+.IX Subsection "Plain text"
+If you have perl documentation in the source form, perl utilities
+installed, and GNU groff installed, you may use
+.PP
+.Vb 3
+\&        perldoc perlfunc
+\&        perldoc less
+\&        perldoc ExtUtils::MakeMaker
+.Ve
+.PP
+to access the perl documentation in the text form (note that you may get
+better results using perl manpages).
+.PP
+Alternately, try running pod2text on \fI.pod\fR files.
+.SS Manpages
+.IX Subsection "Manpages"
+If you have \fIman\fR installed on your system, and you installed perl
+manpages, use something like this:
+.PP
+.Vb 3
+\&        man perlfunc
+\&        man 3 less
+\&        man ExtUtils.MakeMaker
+.Ve
+.PP
+to access documentation for different components of Perl. Start with
+.PP
+.Vb 1
+\&        man perl
+.Ve
+.PP
+Note that dot (\fI.\fR) is used as a package separator for documentation
+for packages, and as usual, sometimes you need to give the section \- \f(CW3\fR
+above \- to avoid shadowing by the \fR\f(BIless\fR\fI\|(1) manpage\fR.
+.PP
+Make sure that the directory \fBabove\fR the directory with manpages is
+on our \f(CW\*(C`MANPATH\*(C'\fR, like this
+.PP
+.Vb 1
+\&  set MANPATH=c:/man;f:/perllib/man
+.Ve
+.PP
+for Perl manpages in \f(CW\*(C`f:/perllib/man/man1/\*(C'\fR etc.
+.SS HTML
+.IX Subsection "HTML"
+If you have some WWW browser available, installed the Perl
+documentation in the source form, and Perl utilities, you can build
+HTML docs. Cd to directory with \fI.pod\fR files, and do like this
+.PP
+.Vb 2
+\&        cd f:/perllib/lib/pod
+\&        pod2html
+.Ve
+.PP
+After this you can direct your browser the file \fIperl.html\fR in this
+directory, and go ahead with reading docs, like this:
+.PP
+.Vb 1
+\&        explore file:///f:/perllib/lib/pod/perl.html
+.Ve
+.PP
+Alternatively you may be able to get these docs prebuilt from CPAN.
+.ie n .SS "GNU ""info"" files"
+.el .SS "GNU \f(CWinfo\fP files"
+.IX Subsection "GNU info files"
+Users of Emacs would appreciate it very much, especially with
+\&\f(CW\*(C`CPerl\*(C'\fR mode loaded. You need to get latest \f(CW\*(C`pod2texi\*(C'\fR from \f(CW\*(C`CPAN\*(C'\fR,
+or, alternately, the prebuilt info pages.
+.SS "\fIPDF\fP files"
+.IX Subsection "PDF files"
+for \f(CW\*(C`Acrobat\*(C'\fR are available on CPAN (may be for slightly older version of
+perl).
+.ie n .SS """LaTeX"" docs"
+.el .SS "\f(CWLaTeX\fP docs"
+.IX Subsection "LaTeX docs"
+can be constructed using \f(CW\*(C`pod2latex\*(C'\fR.
+.SH BUILD
+.IX Header "BUILD"
+Here we discuss how to build Perl under OS/2.
+.SS "The short story"
+.IX Subsection "The short story"
+Assume that you are a seasoned porter, so are sure that all the necessary
+tools are already present on your system, and you know how to get the Perl
+source distribution.  Untar it, change to the extract directory, and
+.PP
+.Vb 7
+\&  gnupatch \-p0 < os2\ediff.configure
+\&  sh Configure \-des \-D prefix=f:/perllib
+\&  make
+\&  make test
+\&  make install
+\&  make aout_test
+\&  make aout_install
+.Ve
+.PP
+This puts the executables in f:/perllib/bin.  Manually move them to the
+\&\f(CW\*(C`PATH\*(C'\fR, manually move the built \fIperl*.dll\fR to \f(CW\*(C`LIBPATH\*(C'\fR (here for
+Perl DLL \fI*\fR is a not-very-meaningful hex checksum), and run
+.PP
+.Vb 1
+\&  make installcmd INSTALLCMDDIR=d:/ir/on/path
+.Ve
+.PP
+Assuming that the \f(CW\*(C`man\*(C'\fR\-files were put on an appropriate location,
+this completes the installation of minimal Perl system.  (The binary
+distribution contains also a lot of additional modules, and the
+documentation in INF format.)
+.PP
+What follows is a detailed guide through these steps.
+.SS Prerequisites
+.IX Subsection "Prerequisites"
+You need to have the latest EMX development environment, the full
+GNU tool suite (gawk renamed to awk, and GNU \fIfind.exe\fR
+earlier on path than the OS/2 \fIfind.exe\fR, same with \fIsort.exe\fR, to
+check use
+.PP
+.Vb 2
+\&  find \-\-version
+\&  sort \-\-version
+.Ve
+.PP
+). You need the latest version of \fIpdksh\fR installed as \fIsh.exe\fR.
+.PP
+Check that you have \fBBSD\fR libraries and headers installed, and \- 
+optionally \- Berkeley DB headers and libraries, and crypt.
+.PP
+Possible locations to get the files:
+.PP
+.Vb 4
+\&  ftp://ftp.uni\-heidelberg.de/pub/os2/unix/
+\&  http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2
+\&  http://cd.textfiles.com/hobbesos29804/disk1/DEV32/
+\&  http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
+.Ve
+.PP
+It is reported that the following archives contain enough utils to
+build perl: \fIgnufutil.zip\fR, \fIgnusutil.zip\fR, \fIgnututil.zip\fR, \fIgnused.zip\fR,
+\&\fIgnupatch.zip\fR, \fIgnuawk.zip\fR, \fIgnumake.zip\fR, \fIgnugrep.zip\fR, \fIbsddev.zip\fR and
+\&\fIksh527rt.zip\fR (or a later version).  Note that all these utilities are
+known to be available from LEO:
+.PP
+.Vb 1
+\&  ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/
+.Ve
+.PP
+Note also that the \fIdb.lib\fR and \fIdb.a\fR from the EMX distribution
+are not suitable for multi-threaded compile (even single-threaded
+flavor of Perl uses multi-threaded C RTL, for
+compatibility with XFree86\-OS/2). Get a corrected one from
+.PP
+.Vb 1
+\&  http://www.ilyaz.org/software/os2/db_mt.zip
+.Ve
+.PP
+If you have \fIexactly the same version of Perl\fR installed already,
+make sure that no copies or perl are currently running.  Later steps
+of the build may fail since an older version of \fIperl.dll\fR loaded into
+memory may be found.  Running \f(CW\*(C`make test\*(C'\fR becomes meaningless, since
+the test are checking a previous build of perl (this situation is detected
+and reported by \fIos2/os2_base.t\fR test).  Do not forget to unset
+\&\f(CW\*(C`PERL_EMXLOAD_SEC\*(C'\fR in environment.
+.PP
+Also make sure that you have \fI/tmp\fR directory on the current drive,
+and \fI.\fR directory in your \f(CW\*(C`LIBPATH\*(C'\fR. One may try to correct the
+latter condition by
+.PP
+.Vb 1
+\&  set BEGINLIBPATH .\e.
+.Ve
+.PP
+if you use something like \fICMD.EXE\fR or latest versions of
+\&\fI4os2.exe\fR.  (Setting BEGINLIBPATH to just \f(CW\*(C`.\*(C'\fR is ignored by the
+OS/2 kernel.)
+.PP
+Make sure your gcc is good for \f(CW\*(C`\-Zomf\*(C'\fR linking: run \f(CW\*(C`omflibs\*(C'\fR
+script in \fI/emx/lib\fR directory.
+.PP
+Check that you have link386 installed. It comes standard with OS/2,
+but may be not installed due to customization. If typing
+.PP
+.Vb 1
+\&  link386
+.Ve
+.PP
+shows you do not have it, do \fISelective install\fR, and choose \f(CW\*(C`Link
+object modules\*(C'\fR in \fIOptional system utilities/More\fR. If you get into
+link386 prompts, press \f(CW\*(C`Ctrl\-C\*(C'\fR to exit.
+.SS "Getting perl source"
+.IX Subsection "Getting perl source"
+You need to fetch the latest perl source (including developers
+releases). With some probability it is located in
+.PP
+.Vb 2
+\&  http://www.cpan.org/src/
+\&  http://www.cpan.org/src/unsupported
+.Ve
+.PP
+If not, you may need to dig in the indices to find it in the directory
+of the current maintainer.
+.PP
+Quick cycle of developers release may break the OS/2 build time to
+time, looking into
+.PP
+.Vb 1
+\&  http://www.cpan.org/ports/os2/
+.Ve
+.PP
+may indicate the latest release which was publicly released by the
+maintainer. Note that the release may include some additional patches
+to apply to the current source of perl.
+.PP
+Extract it like this
+.PP
+.Vb 1
+\&  tar vzxf perl5.00409.tar.gz
+.Ve
+.PP
+You may see a message about errors while extracting \fIConfigure\fR. This is
+because there is a conflict with a similarly-named file \fIconfigure\fR.
+.PP
+Change to the directory of extraction.
+.SS "Application of the patches"
+.IX Subsection "Application of the patches"
+You need to apply the patches in \fI./os2/diff.*\fR like this:
+.PP
+.Vb 1
+\&  gnupatch \-p0 < os2\ediff.configure
+.Ve
+.PP
+You may also need to apply the patches supplied with the binary
+distribution of perl.  It also makes sense to look on the
+perl5\-porters mailing list for the latest OS/2\-related patches (see
+<http://www.xray.mpe.mpg.de/mailing\-lists/perl5\-porters/>).  Such
+patches usually contain strings \f(CW\*(C`/os2/\*(C'\fR and \f(CW\*(C`patch\*(C'\fR, so it makes
+sense looking for these strings.
+.SS Hand-editing
+.IX Subsection "Hand-editing"
+You may look into the file \fI./hints/os2.sh\fR and correct anything
+wrong you find there. I do not expect it is needed anywhere.
+.SS Making
+.IX Subsection "Making"
+.Vb 1
+\&  sh Configure \-des \-D prefix=f:/perllib
+.Ve
+.PP
+\&\f(CW\*(C`prefix\*(C'\fR means: where to install the resulting perl library. Giving
+correct prefix you may avoid the need to specify \f(CW\*(C`PERLLIB_PREFIX\*(C'\fR,
+see "\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR".
+.PP
+\&\fIIgnore the message about missing \fR\f(CI\*(C`ln\*(C'\fR\fI, and about \fR\f(CI\*(C`\-c\*(C'\fR\fI option to
+tr\fR. The latter is most probably already fixed, if you see it and can trace
+where the latter spurious warning comes from, please inform me.
+.PP
+Now
+.PP
+.Vb 1
+\&  make
+.Ve
+.PP
+At some moment the built may die, reporting a \fIversion mismatch\fR or
+\&\fIunable to run perl\fR.  This means that you do not have \fI.\fR in
+your LIBPATH, so \fIperl.exe\fR cannot find the needed \fIperl67B2.dll\fR (treat
+these hex digits as line noise).  After this is fixed the build
+should finish without a lot of fuss.
+.SS Testing
+.IX Subsection "Testing"
+Now run
+.PP
+.Vb 1
+\&  make test
+.Ve
+.PP
+All tests should succeed (with some of them skipped).  If you have the
+same version of Perl installed, it is crucial that you have \f(CW\*(C`.\*(C'\fR early
+in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
+probably test the wrong version of Perl.
+.PP
+Some tests may generate extra messages similar to
+.ie n .IP "A lot of ""bad free""" 4
+.el .IP "A lot of \f(CWbad free\fR" 4
+.IX Item "A lot of bad free"
+in database tests related to Berkeley DB. \fIThis should be fixed already.\fR
+If it persists, you may disable this warnings, see "\f(CW\*(C`PERL_BADFREE\*(C'\fR".
+.IP "Process terminated by SIGTERM/SIGINT" 4
+.IX Item "Process terminated by SIGTERM/SIGINT"
+This is a standard message issued by OS/2 applications. *nix
+applications die in silence. It is considered to be a feature. One can
+easily disable this by appropriate sighandlers.
+.Sp
+However the test engine bleeds these message to screen in unexpected
+moments. Two messages of this kind \fIshould\fR be present during
+testing.
+.PP
+To get finer test reports, call
+.PP
+.Vb 1
+\&  perl t/harness
+.Ve
+.PP
+The report with \fIio/pipe.t\fR failing may look like this:
+.PP
+.Vb 6
+\& Failed Test  Status Wstat Total Fail  Failed  List of failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& io/pipe.t                    12    1   8.33%  9
+\& 7 tests skipped, plus 56 subtests skipped.
+\& Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed,
+\&    99.98% okay.
+.Ve
+.PP
+The reasons for most important skipped tests are:
+.IP \fIop/fs.t\fR 8
+.IX Item "op/fs.t"
+.RS 8
+.PD 0
+.IP 18 4
+.IX Item "18"
+.PD
+Checks \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`mtime\*(C'\fR of \f(CWstat()\fR \- unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
+.IP 25 4
+.IX Item "25"
+Checks \f(CWtruncate()\fR on a filehandle just opened for write \- I do not
+know why this should or should not work.
+.RE
+.RS 8
+.RE
+.IP \fIop/stat.t\fR 8
+.IX Item "op/stat.t"
+Checks \f(CWstat()\fR. Tests:
+.RS 8
+.IP 4 4
+.IX Item "4"
+Checks \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`mtime\*(C'\fR of \f(CWstat()\fR \- unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
+.RE
+.RS 8
+.RE
+.SS "Installing the built perl"
+.IX Subsection "Installing the built perl"
+If you haven't yet moved \f(CW\*(C`perl*.dll\*(C'\fR onto LIBPATH, do it now.
+.PP
+Run
+.PP
+.Vb 1
+\&  make install
+.Ve
+.PP
+It would put the generated files into needed locations. Manually put
+\&\fIperl.exe\fR, \fIperl_\|_.exe\fR and \fIperl_\|_\|_.exe\fR to a location on your
+PATH, \fIperl.dll\fR to a location on your LIBPATH.
+.PP
+Run
+.PP
+.Vb 1
+\&  make installcmd INSTALLCMDDIR=d:/ir/on/path
+.Ve
+.PP
+to convert perl utilities to \fI.cmd\fR files and put them on
+PATH. You need to put \fI.EXE\fR\-utilities on path manually. They are
+installed in \f(CW\*(C`$prefix/bin\*(C'\fR, here \f(CW$prefix\fR is what you gave to
+\&\fIConfigure\fR, see "Making".
+.PP
+If you use \f(CW\*(C`man\*(C'\fR, either move the installed \fI*/man/\fR directories to
+your \f(CW\*(C`MANPATH\*(C'\fR, or modify \f(CW\*(C`MANPATH\*(C'\fR to match the location.  (One
+could have avoided this by providing a correct \f(CW\*(C`manpath\*(C'\fR option to
+\&\fI./Configure\fR, or editing \fI./config.sh\fR between configuring and
+making steps.)
+.ie n .SS """a.out""\-style build"
+.el .SS "\f(CWa.out\fP\-style build"
+.IX Subsection "a.out-style build"
+Proceed as above, but make \fIperl_.exe\fR (see "\fIperl_.exe\fR") by
+.PP
+.Vb 1
+\&  make perl_
+.Ve
+.PP
+test and install by
+.PP
+.Vb 2
+\&  make aout_test
+\&  make aout_install
+.Ve
+.PP
+Manually put \fIperl_.exe\fR to a location on your PATH.
+.PP
+\&\fBNote.\fR The build process for \f(CW\*(C`perl_\*(C'\fR \fIdoes not know\fR about all the
+dependencies, so you should make sure that anything is up-to-date,
+say, by doing
+.PP
+.Vb 1
+\&  make perl_dll
+.Ve
+.PP
+first.
+.SH "Building a binary distribution"
+.IX Header "Building a binary distribution"
+[This section provides a short overview only...]
+.PP
+Building should proceed differently depending on whether the version of perl
+you install is already present and used on your system, or is a new version
+not yet used.  The description below assumes that the version is new, so
+installing its DLLs and \fI.pm\fR files will not disrupt the operation of your
+system even if some intermediate steps are not yet fully working.
+.PP
+The other cases require a little bit more convoluted procedures.  Below I
+suppose that the current version of Perl is \f(CW5.8.2\fR, so the executables are
+named accordingly.
+.IP 1. 4
+Fully build and test the Perl distribution.  Make sure that no tests are
+failing with \f(CW\*(C`test\*(C'\fR and \f(CW\*(C`aout_test\*(C'\fR targets; fix the bugs in Perl and
+the Perl test suite detected by these tests.  Make sure that \f(CW\*(C`all_test\*(C'\fR
+make target runs as clean as possible.  Check that \fIos2/perlrexx.cmd\fR
+runs fine.
+.IP 2. 4
+Fully install Perl, including \f(CW\*(C`installcmd\*(C'\fR target.  Copy the generated DLLs
+to \f(CW\*(C`LIBPATH\*(C'\fR; copy the numbered Perl executables (as in \fIperl5.8.2.exe\fR)
+to \f(CW\*(C`PATH\*(C'\fR; copy \f(CW\*(C`perl_.exe\*(C'\fR to \f(CW\*(C`PATH\*(C'\fR as \f(CW\*(C`perl_5.8.2.exe\*(C'\fR.  Think whether
+you need backward-compatibility DLLs.  In most cases you do not need to install
+them yet; but sometime this may simplify the following steps.
+.IP 3. 4
+Make sure that \f(CW\*(C`CPAN.pm\*(C'\fR can download files from CPAN.  If not, you may need
+to manually install \f(CW\*(C`Net::FTP\*(C'\fR.
+.IP 4. 4
+Install the bundle \f(CW\*(C`Bundle::OS2_default\*(C'\fR
+.Sp
+.Vb 1
+\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
+.Ve
+.Sp
+This may take a couple of hours on 1GHz processor (when run the first time).
+And this should not be necessarily a smooth procedure.  Some modules may not
+specify required dependencies, so one may need to repeat this procedure several
+times until the results stabilize.
+.Sp
+.Vb 2
+\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
+\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
+.Ve
+.Sp
+Even after they stabilize, some tests may fail.
+.Sp
+Fix as many discovered bugs as possible.  Document all the bugs which are not
+fixed, and all the failures with unknown reasons.  Inspect the produced logs
+\&\fI00cpan_i_1\fR to find suspiciously skipped tests, and other fishy events.
+.Sp
+Keep in mind that \fIinstallation\fR of some modules may fail too: for example,
+the DLLs to update may be already loaded by \fICPAN.pm\fR.  Inspect the \f(CW\*(C`install\*(C'\fR
+logs (in the example above \fI00cpan_i_1\fR etc) for errors, and install things
+manually, as in
+.Sp
+.Vb 2
+\&  cd $CPANHOME/.cpan/build/Digest\-MD5\-2.31
+\&  make install
+.Ve
+.Sp
+Some distributions may fail some tests, but you may want to install them
+anyway (as above, or via \f(CW\*(C`force install\*(C'\fR command of \f(CW\*(C`CPAN.pm\*(C'\fR shell-mode).
+.Sp
+Since this procedure may take quite a long time to complete, it makes sense
+to "freeze" your CPAN configuration by disabling periodic updates of the
+local copy of CPAN index: set \f(CW\*(C`index_expire\*(C'\fR to some big value (I use 365),
+then save the settings
+.Sp
+.Vb 2
+\&  CPAN> o conf index_expire 365
+\&  CPAN> o conf commit
+.Ve
+.Sp
+Reset back to the default value \f(CW1\fR when you are finished.
+.IP 5. 4
+When satisfied with the results, rerun the \f(CW\*(C`installcmd\*(C'\fR target.  Now you
+can copy \f(CW\*(C`perl5.8.2.exe\*(C'\fR to \f(CW\*(C`perl.exe\*(C'\fR, and install the other OMF-build
+executables: \f(CW\*(C`perl_\|_.exe\*(C'\fR etc.  They are ready to be used.
+.IP 6. 4
+Change to the \f(CW\*(C`./pod\*(C'\fR directory of the build tree, download the Perl logo
+\&\fICamelGrayBig.BMP\fR, and run
+.Sp
+.Vb 2
+\&  ( perl2ipf > perl.ipf ) |& tee 00ipf
+\&  ipfc /INF perl.ipf |& tee 00inf
+.Ve
+.Sp
+This produces the Perl docs online book \f(CW\*(C`perl.INF\*(C'\fR.  Install in on
+\&\f(CW\*(C`BOOKSHELF\*(C'\fR path.
+.IP 7. 4
+Now is the time to build statically linked executable \fIperl_.exe\fR which
+includes newly-installed via \f(CW\*(C`Bundle::OS2_default\*(C'\fR modules.  Doing testing
+via \f(CW\*(C`CPAN.pm\*(C'\fR is going to be painfully slow, since it statically links
+a new executable per XS extension.
+.Sp
+Here is a possible workaround: create a toplevel \fIMakefile.PL\fR in
+\&\fR\f(CI$CPANHOME\fR\fI/.cpan/build/\fR with contents being (compare with "Making
+executables with a custom collection of statically loaded extensions")
+.Sp
+.Vb 2
+\&  use ExtUtils::MakeMaker;
+\&  WriteMakefile NAME => \*(Aqdummy\*(Aq;
+.Ve
+.Sp
+execute this as
+.Sp
+.Vb 2
+\&  perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
+\&  make \-k all test <nul |& 00aout_t1
+.Ve
+.Sp
+Again, this procedure should not be absolutely smooth.  Some \f(CW\*(C`Makefile.PL\*(C'\fR's
+in subdirectories may be buggy, and would not run as "child" scripts.  The
+interdependency of modules can strike you; however, since non-XS modules
+are already installed, the prerequisites of most modules have a very good
+chance to be present.
+.Sp
+If you discover some glitches, move directories of problematic modules to a
+different location; if these modules are non-XS modules, you may just ignore
+them \- they are already installed; the remaining, XS, modules you need to
+install manually one by one.
+.Sp
+After each such removal you need to rerun the \f(CW\*(C`Makefile.PL\*(C'\fR/\f(CW\*(C`make\*(C'\fR process;
+usually this procedure converges soon.  (But be sure to convert all the
+necessary external C libraries from \fI.lib\fR format to \fI.a\fR format: run one of
+.Sp
+.Vb 2
+\&  emxaout foo.lib
+\&  emximp \-o foo.a foo.lib
+.Ve
+.Sp
+whichever is appropriate.)  Also, make sure that the DLLs for external
+libraries are usable with executables compiled without \f(CW\*(C`\-Zmtd\*(C'\fR options.
+.Sp
+When you are sure that only a few subdirectories
+lead to failures, you may want to add \f(CW\*(C`\-j4\*(C'\fR option to \f(CW\*(C`make\*(C'\fR to speed up
+skipping subdirectories with already finished build.
+.Sp
+When you are satisfied with the results of tests, install the build C libraries
+for extensions:
+.Sp
+.Vb 1
+\&  make install |& tee 00aout_i
+.Ve
+.Sp
+Now you can rename the file \fI./perl.exe\fR generated during the last phase
+to \fIperl_5.8.2.exe\fR; place it on \f(CW\*(C`PATH\*(C'\fR; if there is an inter-dependency
+between some XS modules, you may need to repeat the \f(CW\*(C`test\*(C'\fR/\f(CW\*(C`install\*(C'\fR loop
+with this new executable and some excluded modules \- until the procedure
+converges.
+.Sp
+Now you have all the necessary \fI.a\fR libraries for these Perl modules in the
+places where Perl builder can find it.  Use the perl builder: change to an
+empty directory, create a "dummy" \fIMakefile.PL\fR again, and run
+.Sp
+.Vb 2
+\&  perl_5.8.2.exe Makefile.PL |& tee 00c
+\&  make perl                  |& tee 00p
+.Ve
+.Sp
+This should create an executable \fI./perl.exe\fR with all the statically loaded
+extensions built in.  Compare the generated \fIperlmain.c\fR files to make sure
+that during the iterations the number of loaded extensions only increases.
+Rename \fI./perl.exe\fR to \fIperl_5.8.2.exe\fR on \f(CW\*(C`PATH\*(C'\fR.
+.Sp
+When it converges, you got a functional variant of \fIperl_5.8.2.exe\fR; copy it
+to \f(CW\*(C`perl_.exe\*(C'\fR.  You are done with generation of the local Perl installation.
+.IP 8. 4
+Make sure that the installed modules are actually installed in the location
+of the new Perl, and are not inherited from entries of \f(CW@INC\fR given for
+inheritance from the older versions of Perl: set \f(CW\*(C`PERLLIB_582_PREFIX\*(C'\fR to
+redirect the new version of Perl to a new location, and copy the installed
+files to this new location.  Redo the tests to make sure that the versions of
+modules inherited from older versions of Perl are not needed.
+.Sp
+Actually, the log output of \fBpod2ipf\fR\|(1) during the step 6 gives a very detailed
+info about which modules are loaded from which place; so you may use it as
+an additional verification tool.
+.Sp
+Check that some temporary files did not make into the perl install tree.
+Run something like this
+.Sp
+.Vb 1
+\&  pfind . \-f "!(/\e.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\ew+$/") | less
+.Ve
+.Sp
+in the install tree (both top one and \fIsitelib\fR one).
+.Sp
+Compress all the DLLs with \fIlxlite\fR.  The tiny \fI.exe\fR can be compressed with
+\&\f(CW\*(C`/c:max\*(C'\fR (the bug only appears when there is a fixup in the last 6 bytes of a
+page (?); since the tiny executables are much smaller than a page, the bug
+will not hit).  Do not compress \f(CW\*(C`perl_.exe\*(C'\fR \- it would not work under DOS.
+.IP 9. 4
+Now you can generate the binary distribution.  This is done by running the
+test of the CPAN distribution \f(CW\*(C`OS2::SoftInstaller\*(C'\fR.  Tune up the file
+\&\fItest.pl\fR to suit the layout of current version of Perl first.  Do not
+forget to pack the necessary external DLLs accordingly.  Include the
+description of the bugs and test suite failures you could not fix.  Include
+the small-stack versions of Perl executables from Perl build directory.
+.Sp
+Include \fIperl5.def\fR so that people can relink the perl DLL preserving
+the binary compatibility, or can create compatibility DLLs.  Include the diff
+files (\f(CW\*(C`diff \-pu old new\*(C'\fR) of fixes you did so that people can rebuild your
+version.  Include \fIperl5.map\fR so that one can use remote debugging.
+.IP 10. 4
+Share what you did with the other people.  Relax.  Enjoy fruits of your work.
+.IP 11. 4
+Brace yourself for thanks, bug reports, hate mail and spam coming as result
+of the previous step.  No good deed should remain unpunished!
+.SH "Building custom \fI.EXE\fP files"
+.IX Header "Building custom .EXE files"
+The Perl executables can be easily rebuilt at any moment.  Moreover, one can
+use the \fIembedding\fR interface (see perlembed) to make very customized
+executables.
+.SS "Making executables with a custom collection of statically loaded extensions"
+.IX Subsection "Making executables with a custom collection of statically loaded extensions"
+It is a little bit easier to do so while \fIdecreasing\fR the list of statically
+loaded extensions.  We discuss this case only here.
+.IP 1. 4
+Change to an empty directory, and create a placeholder <Makefile.PL>:
+.Sp
+.Vb 2
+\&  use ExtUtils::MakeMaker;
+\&  WriteMakefile NAME => \*(Aqdummy\*(Aq;
+.Ve
+.IP 2. 4
+Run it with the flavor of Perl (\fIperl.exe\fR or \fIperl_.exe\fR) you want to
+rebuild.
+.Sp
+.Vb 1
+\&  perl_ Makefile.PL
+.Ve
+.IP 3. 4
+Ask it to create new Perl executable:
+.Sp
+.Vb 1
+\&  make perl
+.Ve
+.Sp
+(you may need to manually add \f(CW\*(C`PERLTYPE=\-DPERL_CORE\*(C'\fR to this commandline on
+some versions of Perl; the symptom is that the command-line globbing does not
+work from OS/2 shells with the newly-compiled executable; check with
+.Sp
+.Vb 1
+\&  .\eperl.exe \-wle "print for @ARGV" *
+.Ve
+.Sp
+).
+.IP 4. 4
+The previous step created \fIperlmain.c\fR which contains a list of \fBnewXS()\fR calls
+near the end.  Removing unnecessary calls, and rerunning
+.Sp
+.Vb 1
+\&  make perl
+.Ve
+.Sp
+will produce a customized executable.
+.SS "Making executables with a custom search-paths"
+.IX Subsection "Making executables with a custom search-paths"
+The default perl executable is flexible enough to support most usages.
+However, one may want something yet more flexible; for example, one may want
+to find Perl DLL relatively to the location of the EXE file; or one may want
+to ignore the environment when setting the Perl-library search patch, etc.
+.PP
+If you fill comfortable with \fIembedding\fR interface (see perlembed), such
+things are easy to do repeating the steps outlined in "Making
+executables with a custom collection of statically loaded extensions", and
+doing more comprehensive edits to \fBmain()\fR of \fIperlmain.c\fR.  The people with
+little desire to understand Perl can just rename \fBmain()\fR, and do necessary
+modification in a custom \fBmain()\fR which calls the renamed function in appropriate
+time.
+.PP
+However, there is a third way: perl DLL exports the \fBmain()\fR function and several
+callbacks to customize the search path.  Below is a complete example of a
+"Perl loader" which
+.IP 1. 4
+Looks for Perl DLL in the directory \f(CW\*(C`$exedir/../dll\*(C'\fR;
+.IP 2. 4
+Prepends the above directory to \f(CW\*(C`BEGINLIBPATH\*(C'\fR;
+.IP 3. 4
+Fails if the Perl DLL found via \f(CW\*(C`BEGINLIBPATH\*(C'\fR is different from what was
+loaded on step 1; e.g., another process could have loaded it from \f(CW\*(C`LIBPATH\*(C'\fR
+or from a different value of \f(CW\*(C`BEGINLIBPATH\*(C'\fR.  In these cases one needs to
+modify the setting of the system so that this other process either does not
+run, or loads the DLL from \f(CW\*(C`BEGINLIBPATH\*(C'\fR with \f(CW\*(C`LIBPATHSTRICT=T\*(C'\fR (available
+with kernels after September 2000).
+.IP 4. 4
+Loads Perl library from \f(CW\*(C`$exedir/../dll/lib/\*(C'\fR.
+.IP 5. 4
+Uses Bourne shell from \f(CW\*(C`$exedir/../dll/sh/ksh.exe\*(C'\fR.
+.PP
+For best results compile the C file below with the same options as the Perl
+DLL.  However, a lot of functionality will work even if the executable is not
+an EMX applications, e.g., if compiled with
+.PP
+.Vb 2
+\&  gcc \-Wall \-DDOSISH \-DOS2=1 \-O2 \-s \-Zomf \-Zsys perl\-starter.c \e
+\&    \-DPERL_DLL_BASENAME=\e"perl312F\e" \-Zstack 8192 \-Zlinker /PM:VIO
+.Ve
+.PP
+Here is the sample C file:
+.PP
+.Vb 6
+\& #define INCL_DOS
+\& #define INCL_NOPM
+\& /* These are needed for compile if os2.h includes os2tk.h, not
+\&  * os2emx.h */
+\& #define INCL_DOSPROCESS
+\& #include <os2.h>
+\&
+\& #include "EXTERN.h"
+\& #define PERL_IN_MINIPERLMAIN_C
+\& #include "perl.h"
+\&
+\& static char *me;
+\& HMODULE handle;
+\&
+\& static void
+\& die_with(char *msg1, char *msg2, char *msg3, char *msg4)
+\& {
+\&    ULONG c;
+\&    char *s = " error: ";
+\&
+\&    DosWrite(2, me, strlen(me), &c);
+\&    DosWrite(2, s, strlen(s), &c);
+\&    DosWrite(2, msg1, strlen(msg1), &c);
+\&    DosWrite(2, msg2, strlen(msg2), &c);
+\&    DosWrite(2, msg3, strlen(msg3), &c);
+\&    DosWrite(2, msg4, strlen(msg4), &c);
+\&    DosWrite(2, "\er\en", 2, &c);
+\&    exit(255);
+\& }
+\&
+\& typedef ULONG (*fill_extLibpath_t)(int type,
+\&                                    char *pre,
+\&                                    char *post,
+\&                                    int replace,
+\&                                    char *msg);
+\& typedef int (*main_t)(int type, char *argv[], char *env[]);
+\& typedef int (*handler_t)(void* data, int which);
+\&
+\& #ifndef PERL_DLL_BASENAME
+\& #  define PERL_DLL_BASENAME "perl"
+\& #endif
+\&
+\& static HMODULE
+\& load_perl_dll(char *basename)
+\& {
+\&     char buf[300], fail[260];
+\&     STRLEN l, dirl;
+\&     fill_extLibpath_t f;
+\&     ULONG rc_fullname;
+\&     HMODULE handle, handle1;
+\&
+\&     if (_execname(buf, sizeof(buf) \- 13) != 0)
+\&         die_with("Can\*(Aqt find full path: ", strerror(errno), "", "");
+\&     /* XXXX Fill \*(Aqme\*(Aq with new value */
+\&     l = strlen(buf);
+\&     while (l && buf[l\-1] != \*(Aq/\*(Aq && buf[l\-1] != \*(Aq\e\e\*(Aq)
+\&         l\-\-;
+\&     dirl = l \- 1;
+\&     strcpy(buf + l, basename);
+\&     l += strlen(basename);
+\&     strcpy(buf + l, ".dll");
+\&     if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle))
+\&                                                                    != 0
+\&          && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
+\&         die_with("Can\*(Aqt load DLL ", buf, "", "");
+\&     if (rc_fullname)
+\&         return handle;    /* was loaded with short name; all is fine */
+\&     if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
+\&         die_with(buf,
+\&                  ": DLL exports no symbol ",
+\&                  "fill_extLibpath",
+\&                  "");
+\&     buf[dirl] = 0;
+\&     if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
+\&           0 /* keep old value */, me))
+\&         die_with(me, ": prepending BEGINLIBPATH", "", "");
+\&     if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
+\&         die_with(me,
+\&                  ": finding perl DLL again via BEGINLIBPATH",
+\&                  "",
+\&                  "");
+\&     buf[dirl] = \*(Aq\e\e\*(Aq;
+\&     if (handle1 != handle) {
+\&         if (DosQueryModuleName(handle1, sizeof(fail), fail))
+\&             strcpy(fail, "???");
+\&         die_with(buf,
+\&                  ":\en\etperl DLL via BEGINLIBPATH is different: \en\et",
+\&                  fail,
+\&                  "\en\etYou may need to manipulate global BEGINLIBPATH"
+\&                     " and LIBPATHSTRICT"
+\&                     "\en\etso that the other copy is loaded via"
+\&                     BEGINLIBPATH.");
+\&     }
+\&     return handle;
+\& }
+\&
+\& int
+\& main(int argc, char **argv, char **env)
+\& {
+\&     main_t f;
+\&     handler_t h;
+\&
+\&     me = argv[0];
+\&     /**/
+\&     handle = load_perl_dll(PERL_DLL_BASENAME);
+\&
+\&     if (DosQueryProcAddr(handle,
+\&                          0,
+\&                          "Perl_OS2_handler_install",
+\&                          (PFN*)&h))
+\&         die_with(PERL_DLL_BASENAME,
+\&                  ": DLL exports no symbol ",
+\&                  "Perl_OS2_handler_install",
+\&                  "");
+\&     if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
+\&          || !h((void *)"~dll", Perlos2_handler_perllib_to)
+\&          || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
+\&         die_with(PERL_DLL_BASENAME,
+\&                  ": Can\*(Aqt install @INC manglers",
+\&                  "",
+\&                  "");
+\&     if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
+\&         die_with(PERL_DLL_BASENAME,
+\&                  ": DLL exports no symbol ",
+\&                  "dll_perlmain",
+\&                  "");
+\&     return f(argc, argv, env);
+\& }
+.Ve
+.SH "Build FAQ"
+.IX Header "Build FAQ"
+.ie n .SS "Some ""/"" became ""\e"" in pdksh."
+.el .SS "Some \f(CW/\fP became \f(CW\e\fP in pdksh."
+.IX Subsection "Some / became in pdksh."
+You have a very old pdksh. See "Prerequisites".
+.ie n .SS "\*(Aqerrno\*(Aq \- unresolved external"
+.el .SS "\f(CW\*(Aqerrno\*(Aq\fP \- unresolved external"
+.IX Subsection "errno - unresolved external"
+You do not have MT-safe \fIdb.lib\fR. See "Prerequisites".
+.SS "Problems with tr or sed"
+.IX Subsection "Problems with tr or sed"
+reported with very old version of tr and sed.
+.SS "Some problem (forget which ;\-)"
+.IX Subsection "Some problem (forget which ;-)"
+You have an older version of \fIperl.dll\fR on your LIBPATH, which
+broke the build of extensions.
+.SS "Library ... not found"
+.IX Subsection "Library ... not found"
+You did not run \f(CW\*(C`omflibs\*(C'\fR. See "Prerequisites".
+.SS "Segfault in make"
+.IX Subsection "Segfault in make"
+You use an old version of GNU make. See "Prerequisites".
+.SS "op/sprintf test failure"
+.IX Subsection "op/sprintf test failure"
+This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
+.SH "Specific (mis)features of OS/2 port"
+.IX Header "Specific (mis)features of OS/2 port"
+.ie n .SS """setpriority"", ""getpriority"""
+.el .SS "\f(CWsetpriority\fP, \f(CWgetpriority\fP"
+.IX Subsection "setpriority, getpriority"
+Note that these functions are compatible with *nix, not with the older
+ports of '94 \- 95. The priorities are absolute, go from 32 to \-95,
+lower is quicker. 0 is the default priority.
+.PP
+\&\fBWARNING\fR.  Calling \f(CW\*(C`getpriority\*(C'\fR on a non-existing process could lock
+the system before Warp3 fixpak22.  Starting with Warp3, Perl will use
+a workaround: it aborts \fBgetpriority()\fR if the process is not present.
+This is not possible on older versions \f(CW\*(C`2.*\*(C'\fR, and has a race
+condition anyway.
+.ie n .SS system()
+.el .SS \f(CWsystem()\fP
+.IX Subsection "system()"
+Multi-argument form of \f(CWsystem()\fR allows an additional numeric
+argument. The meaning of this argument is described in
+OS2::Process.
+.PP
+When finding a program to run, Perl first asks the OS to look for executables
+on \f(CW\*(C`PATH\*(C'\fR (OS/2 adds extension \fI.exe\fR if no extension is present).
+If not found, it looks for a script with possible extensions 
+added in this order: no extension, \fI.cmd\fR, \fI.btm\fR, 
+\&\fI.bat\fR, \fI.pl\fR.  If found, Perl checks the start of the file for magic
+strings \f(CW"#!"\fR and \f(CW"extproc "\fR.  If found, Perl uses the rest of the
+first line as the beginning of the command line to run this script.  The
+only mangling done to the first line is extraction of arguments (currently
+up to 3), and ignoring of the path-part of the "interpreter" name if it can't
+be found using the full path.
+.PP
+E.g., \f(CW\*(C`system \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq\*(C'\fR may lead Perl to finding
+\&\fIC:/emx/bin/foo.cmd\fR with the first line being
+.PP
+.Vb 1
+\& extproc /bin/bash    \-x   \-c
+.Ve
+.PP
+If \fI/bin/bash.exe\fR is not found, then Perl looks for an executable \fIbash.exe\fR on
+\&\f(CW\*(C`PATH\*(C'\fR.  If found in \fIC:/emx.add/bin/bash.exe\fR, then the above \fBsystem()\fR is
+translated to
+.PP
+.Vb 1
+\&  system qw(C:/emx.add/bin/bash.exe \-x \-c C:/emx/bin/foo.cmd bar baz)
+.Ve
+.PP
+One additional translation is performed: instead of \fI/bin/sh\fR Perl uses
+the hardwired-or-customized shell (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR").
+.PP
+The above search for "interpreter" is recursive: if \fIbash\fR executable is not
+found, but \fIbash.btm\fR is found, Perl will investigate its first line etc.
+The only hardwired limit on the recursion depth is implicit: there is a limit
+4 on the number of additional arguments inserted before the actual arguments
+given to \fBsystem()\fR.  In particular, if no additional arguments are specified
+on the "magic" first lines, then the limit on the depth is 4.
+.PP
+If Perl finds that the found executable is of PM type when the
+current session is not, it will start the new process in a separate session of
+necessary type.  Call via \f(CW\*(C`OS2::Process\*(C'\fR to disable this magic.
+.PP
+\&\fBWARNING\fR.  Due to the described logic, you need to explicitly
+specify \fI.com\fR extension if needed.  Moreover, if the executable
+\&\fIperl5.6.1\fR is requested, Perl will not look for \fIperl5.6.1.exe\fR.
+[This may change in the future.]
+.ie n .SS """extproc"" on the first line"
+.el .SS "\f(CWextproc\fP on the first line"
+.IX Subsection "extproc on the first line"
+If the first chars of a Perl script are \f(CW"extproc "\fR, this line is treated
+as \f(CW\*(C`#!\*(C'\fR\-line, thus all the switches on this line are processed (twice
+if script was started via cmd.exe).  See "DESCRIPTION" in perlrun.
+.SS "Additional modules:"
+.IX Subsection "Additional modules:"
+OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These
+modules provide access to additional numeric argument for \f(CW\*(C`system\*(C'\fR
+and to the information about the running process,
+to DLLs having functions with REXX signature and to the REXX runtime, to
+OS/2 databases in the \fI.INI\fR format, and to Extended Attributes.
+.PP
+Two additional extensions by Andreas Kaiser, \f(CW\*(C`OS2::UPM\*(C'\fR, and
+\&\f(CW\*(C`OS2::FTP\*(C'\fR, are included into \f(CW\*(C`ILYAZ\*(C'\fR directory, mirrored on CPAN.
+Other OS/2\-related extensions are available too.
+.SS "Prebuilt methods:"
+.IX Subsection "Prebuilt methods:"
+.ie n .IP """File::Copy::syscopy""" 4
+.el .IP \f(CWFile::Copy::syscopy\fR 4
+.IX Item "File::Copy::syscopy"
+used by \f(CW\*(C`File::Copy::copy\*(C'\fR, see File::Copy.
+.ie n .IP """DynaLoader::mod2fname""" 4
+.el .IP \f(CWDynaLoader::mod2fname\fR 4
+.IX Item "DynaLoader::mod2fname"
+used by \f(CW\*(C`DynaLoader\*(C'\fR for DLL name mangling.
+.ie n .IP Cwd::current_drive() 4
+.el .IP \f(CWCwd::current_drive()\fR 4
+.IX Item "Cwd::current_drive()"
+Self explanatory.
+.ie n .IP Cwd::sys_chdir(name) 4
+.el .IP \f(CWCwd::sys_chdir(name)\fR 4
+.IX Item "Cwd::sys_chdir(name)"
+leaves drive as it is.
+.ie n .IP Cwd::change_drive(name) 4
+.el .IP \f(CWCwd::change_drive(name)\fR 4
+.IX Item "Cwd::change_drive(name)"
+changes the "current" drive.
+.ie n .IP Cwd::sys_is_absolute(name) 4
+.el .IP \f(CWCwd::sys_is_absolute(name)\fR 4
+.IX Item "Cwd::sys_is_absolute(name)"
+means has drive letter and is_rooted.
+.ie n .IP Cwd::sys_is_rooted(name) 4
+.el .IP \f(CWCwd::sys_is_rooted(name)\fR 4
+.IX Item "Cwd::sys_is_rooted(name)"
+means has leading \f(CW\*(C`[/\e\e]\*(C'\fR (maybe after a drive-letter:).
+.ie n .IP Cwd::sys_is_relative(name) 4
+.el .IP \f(CWCwd::sys_is_relative(name)\fR 4
+.IX Item "Cwd::sys_is_relative(name)"
+means changes with current dir.
+.ie n .IP Cwd::sys_cwd(name) 4
+.el .IP \f(CWCwd::sys_cwd(name)\fR 4
+.IX Item "Cwd::sys_cwd(name)"
+Interface to cwd from EMX. Used by \f(CW\*(C`Cwd::cwd\*(C'\fR.
+.ie n .IP """Cwd::sys_abspath(name, dir)""" 4
+.el .IP "\f(CWCwd::sys_abspath(name, dir)\fR" 4
+.IX Item "Cwd::sys_abspath(name, dir)"
+Really really odious function to implement. Returns absolute name of
+file which would have \f(CW\*(C`name\*(C'\fR if CWD were \f(CW\*(C`dir\*(C'\fR.  \f(CW\*(C`Dir\*(C'\fR defaults to the
+current dir.
+.ie n .IP Cwd::extLibpath([type]) 4
+.el .IP \f(CWCwd::extLibpath([type])\fR 4
+.IX Item "Cwd::extLibpath([type])"
+Get current value of extended library search path. If \f(CW\*(C`type\*(C'\fR is
+present and positive, works with \f(CW\*(C`END_LIBPATH\*(C'\fR, if negative, works
+with \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, otherwise with \f(CW\*(C`BEGIN_LIBPATH\*(C'\fR.
+.ie n .IP """Cwd::extLibpath_set( path [, type ] )""" 4
+.el .IP "\f(CWCwd::extLibpath_set( path [, type ] )\fR" 4
+.IX Item "Cwd::extLibpath_set( path [, type ] )"
+Set current value of extended library search path. If \f(CW\*(C`type\*(C'\fR is
+present and positive, works with <END_LIBPATH>, if negative, works
+with \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, otherwise with \f(CW\*(C`BEGIN_LIBPATH\*(C'\fR.
+.ie n .IP """OS2::Error(do_harderror,do_exception)""" 4
+.el .IP \f(CWOS2::Error(do_harderror,do_exception)\fR 4
+.IX Item "OS2::Error(do_harderror,do_exception)"
+Returns	\f(CW\*(C`undef\*(C'\fR if it was not called yet, otherwise bit 1 is
+set if on the previous call do_harderror was enabled, bit
+2 is set if on previous call do_exception was enabled.
+.Sp
+This function enables/disables error popups associated with 
+hardware errors (Disk not ready etc.) and software exceptions.
+.Sp
+I know of no way to find out the state of popups \fIbefore\fR the first call
+to this function.
+.ie n .IP OS2::Errors2Drive(drive) 4
+.el .IP \f(CWOS2::Errors2Drive(drive)\fR 4
+.IX Item "OS2::Errors2Drive(drive)"
+Returns \f(CW\*(C`undef\*(C'\fR if it was not called yet, otherwise return false if errors
+were not requested to be written to a hard drive, or the drive letter if
+this was requested.
+.Sp
+This function may redirect error popups associated with hardware errors
+(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
+the root directory of the specified drive.  Overrides \fBOS2::Error()\fR specified
+by individual programs.  Given argument undef will disable redirection.
+.Sp
+Has global effect, persists after the application exits.
+.Sp
+I know of no way to find out the state of redirection of popups to the disk
+\&\fIbefore\fR the first call to this function.
+.IP \fBOS2::SysInfo()\fR 4
+.IX Item "OS2::SysInfo()"
+Returns a hash with system information. The keys of the hash are
+.Sp
+.Vb 8
+\&        MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
+\&        MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
+\&        MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
+\&        VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
+\&        MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
+\&        TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
+\&        MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
+\&        FOREGROUND_PROCESS
+.Ve
+.IP \fBOS2::BootDrive()\fR 4
+.IX Item "OS2::BootDrive()"
+Returns a letter without colon.
+.ie n .IP "OS2::MorphPM(serve), OS2::UnMorphPM(serve)" 4
+.el .IP "\f(CWOS2::MorphPM(serve)\fR, \f(CWOS2::UnMorphPM(serve)\fR" 4
+.IX Item "OS2::MorphPM(serve), OS2::UnMorphPM(serve)"
+Transforms the current application into a PM application and back.
+The argument true means that a real message loop is going to be served.
+\&\fBOS2::MorphPM()\fR returns the PM message queue handle as an integer.
+.Sp
+See "Centralized management of resources" for additional details.
+.ie n .IP OS2::Serve_Messages(force) 4
+.el .IP \f(CWOS2::Serve_Messages(force)\fR 4
+.IX Item "OS2::Serve_Messages(force)"
+Fake on-demand retrieval of outstanding PM messages.  If \f(CW\*(C`force\*(C'\fR is false,
+will not dispatch messages if a real message loop is known to
+be present.  Returns number of messages retrieved.
+.Sp
+Dies with "QUITing..." if WM_QUIT message is obtained.
+.ie n .IP """OS2::Process_Messages(force [, cnt])""" 4
+.el .IP "\f(CWOS2::Process_Messages(force [, cnt])\fR" 4
+.IX Item "OS2::Process_Messages(force [, cnt])"
+Retrieval of PM messages until window creation/destruction.  
+If \f(CW\*(C`force\*(C'\fR is false, will not dispatch messages if a real message loop
+is known to be present.
+.Sp
+Returns change in number of windows.  If \f(CW\*(C`cnt\*(C'\fR is given,
+it is incremented by the number of messages retrieved.
+.Sp
+Dies with "QUITing..." if WM_QUIT message is obtained.
+.ie n .IP """OS2::_control87(new,mask)""" 4
+.el .IP \f(CWOS2::_control87(new,mask)\fR 4
+.IX Item "OS2::_control87(new,mask)"
+the same as \fB_control87\fR\|(3) of EMX.  Takes integers as arguments, returns
+the previous coprocessor control word as an integer.  Only bits in \f(CW\*(C`new\*(C'\fR which
+are present in \f(CW\*(C`mask\*(C'\fR are changed in the control word.
+.IP \fBOS2::get_control87()\fR 4
+.IX Item "OS2::get_control87()"
+gets the coprocessor control word as an integer.
+.ie n .IP """OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)""" 4
+.el .IP \f(CWOS2::set_control87_em(new=MCW_EM,mask=MCW_EM)\fR 4
+.IX Item "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
+The variant of \fBOS2::_control87()\fR with default values good for
+handling exception mask: if no \f(CW\*(C`mask\*(C'\fR, uses exception mask part of \f(CW\*(C`new\*(C'\fR
+only.  If no \f(CW\*(C`new\*(C'\fR, disables all the floating point exceptions.
+.Sp
+See "Misfeatures" for details.
+.ie n .IP """OS2::DLLname([how [, \e&xsub]])""" 4
+.el .IP "\f(CWOS2::DLLname([how [, \e&xsub]])\fR" 4
+.IX Item "OS2::DLLname([how [, &xsub]])"
+Gives the information about the Perl DLL or the DLL containing the C
+function bound to by \f(CW&xsub\fR.  The meaning of \f(CW\*(C`how\*(C'\fR is: default (2):
+full name; 0: handle; 1: module name.
+.PP
+(Note that some of these may be moved to different libraries \-
+eventually).
+.SS "Prebuilt variables:"
+.IX Subsection "Prebuilt variables:"
+.ie n .IP $OS2::emx_rev 4
+.el .IP \f(CW$OS2::emx_rev\fR 4
+.IX Item "$OS2::emx_rev"
+numeric value is the same as _emx_rev of EMX, a string value the same
+as _emx_vprt (similar to \f(CW\*(C`0.9c\*(C'\fR).
+.ie n .IP $OS2::emx_env 4
+.el .IP \f(CW$OS2::emx_env\fR 4
+.IX Item "$OS2::emx_env"
+same as _emx_env of EMX, a number similar to 0x8001.
+.ie n .IP $OS2::os_ver 4
+.el .IP \f(CW$OS2::os_ver\fR 4
+.IX Item "$OS2::os_ver"
+a number \f(CW\*(C`OS_MAJOR + 0.001 * OS_MINOR\*(C'\fR.
+.ie n .IP $OS2::is_aout 4
+.el .IP \f(CW$OS2::is_aout\fR 4
+.IX Item "$OS2::is_aout"
+true if the Perl library was compiled in AOUT format.
+.ie n .IP $OS2::can_fork 4
+.el .IP \f(CW$OS2::can_fork\fR 4
+.IX Item "$OS2::can_fork"
+true if the current executable is an AOUT EMX executable, so Perl can
+fork.  Do not use this, use the portable check for
+\&\f(CW$Config::Config\fR{dfork}.
+.ie n .IP $OS2::nsyserror 4
+.el .IP \f(CW$OS2::nsyserror\fR 4
+.IX Item "$OS2::nsyserror"
+This variable (default is 1) controls whether to enforce the contents
+of $^E to start with \f(CW\*(C`SYS0003\*(C'\fR\-like id.  If set to 0, then the string
+value of $^E is what is available from the OS/2 message file.  (Some
+messages in this file have an \f(CW\*(C`SYS0003\*(C'\fR\-like id prepended, some not.)
+.SS Misfeatures
+.IX Subsection "Misfeatures"
+.IP \(bu 4
+Since \fBflock\fR\|(3) is present in EMX, but is not functional, it is 
+emulated by perl.  To disable the emulations, set environment variable
+\&\f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR.
+.IP \(bu 4
+Here is the list of things which may be "broken" on
+EMX (from EMX docs):
+.RS 4
+.IP \(bu 4
+The functions \fBrecvmsg\fR\|(3), \fBsendmsg\fR\|(3), and \fBsocketpair\fR\|(3) are not
+implemented.
+.IP \(bu 4
+\&\fBsock_init\fR\|(3) is not required and not implemented.
+.IP \(bu 4
+\&\fBflock\fR\|(3) is not yet implemented (dummy function).  (Perl has a workaround.)
+.IP \(bu 4
+\&\fBkill\fR\|(3):  Special treatment of PID=0, PID=1 and PID=\-1 is not implemented.
+.IP \(bu 4
+\&\fBwaitpid\fR\|(3):
+.Sp
+.Vb 3
+\&      WUNTRACED
+\&              Not implemented.
+\&      waitpid() is not implemented for negative values of PID.
+.Ve
+.RE
+.RS 4
+.Sp
+Note that \f(CW\*(C`kill \-9\*(C'\fR does not work with the current version of EMX.
+.RE
+.IP \(bu 4
+See "Text-mode filehandles".
+.IP \(bu 4
+Unix-domain sockets on OS/2 live in a pseudo-file-system \f(CW\*(C`/sockets/...\*(C'\fR.
+To avoid a failure to create a socket with a name of a different form,
+\&\f(CW"/socket/"\fR is prepended to the socket name (unless it starts with this
+already).
+.Sp
+This may lead to problems later in case the socket is accessed via the
+"usual" file-system calls using the "initial" name.
+.IP \(bu 4
+Apparently, IBM used a compiler (for some period of time around '95?) which
+changes FP mask right and left.  This is not \fIthat\fR bad for IBM's
+programs, but the same compiler was used for DLLs which are used with
+general-purpose applications.  When these DLLs are used, the state of
+floating-point flags in the application is not predictable.
+.Sp
+What is much worse, some DLLs change the floating point flags when in
+\&\fB_DLLInitTerm()\fR (e.g., \fITCP32IP\fR).  This means that even if you do not \fIcall\fR
+any function in the DLL, just the act of loading this DLL will reset your
+flags.  What is worse, the same compiler was used to compile some HOOK DLLs.
+Given that HOOK dlls are executed in the context of \fIall\fR the applications
+in the system, this means a complete unpredictability of floating point
+flags on systems using such HOOK DLLs.  E.g., \fIGAMESRVR.DLL\fR of \fBDIVE\fR
+origin changes the floating point flags on each write to the TTY of a VIO
+(windowed text-mode) applications.
+.Sp
+Some other (not completely debugged) situations when FP flags change include
+some video drivers (?), and some operations related to creation of the windows.
+People who code \fBOpenGL\fR may have more experience on this.
+.Sp
+Perl is generally used in the situation when all the floating-point
+exceptions are ignored, as is the default under EMX.  If they are not ignored,
+some benign Perl programs would get a \f(CW\*(C`SIGFPE\*(C'\fR and would die a horrible death.
+.Sp
+To circumvent this, Perl uses two hacks.  They help against \fIone\fR type of
+damage only: FP flags changed when loading a DLL.
+.Sp
+One of the hacks is to disable floating point exceptions on Perl startup (as
+is the default with EMX).  This helps only with compile-time-linked DLLs
+changing the flags before \fBmain()\fR had a chance to be called.
+.Sp
+The other hack is to restore FP flags after a call to \fBdlopen()\fR.  This helps
+against similar damage done by DLLs \fB_DLLInitTerm()\fR at runtime.  Currently
+no way to switch these hacks off is provided.
+.SS Modifications
+.IX Subsection "Modifications"
+Perl modifies some standard C library calls in the following ways:
+.ie n .IP """popen""" 9
+.el .IP \f(CWpopen\fR 9
+.IX Item "popen"
+\&\f(CW\*(C`my_popen\*(C'\fR uses \fIsh.exe\fR if shell is required, cf. "\f(CW\*(C`PERL_SH_DIR\*(C'\fR".
+.ie n .IP """tmpnam""" 9
+.el .IP \f(CWtmpnam\fR 9
+.IX Item "tmpnam"
+is created using \f(CW\*(C`TMP\*(C'\fR or \f(CW\*(C`TEMP\*(C'\fR environment variable, via
+\&\f(CW\*(C`tempnam\*(C'\fR.
+.ie n .IP """tmpfile""" 9
+.el .IP \f(CWtmpfile\fR 9
+.IX Item "tmpfile"
+If the current directory is not writable, file is created using modified
+\&\f(CW\*(C`tmpnam\*(C'\fR, so there may be a race condition.
+.ie n .IP """ctermid""" 9
+.el .IP \f(CWctermid\fR 9
+.IX Item "ctermid"
+a dummy implementation.
+.ie n .IP """stat""" 9
+.el .IP \f(CWstat\fR 9
+.IX Item "stat"
+\&\f(CW\*(C`os2_stat\*(C'\fR special-cases \fI/dev/tty\fR and \fI/dev/con\fR.
+.ie n .IP """mkdir"", ""rmdir""" 9
+.el .IP "\f(CWmkdir\fR, \f(CWrmdir\fR" 9
+.IX Item "mkdir, rmdir"
+these EMX functions do not work if the path contains a trailing \f(CW\*(C`/\*(C'\fR.
+Perl contains a workaround for this.
+.ie n .IP """flock""" 9
+.el .IP \f(CWflock\fR 9
+.IX Item "flock"
+Since \fBflock\fR\|(3) is present in EMX, but is not functional, it is 
+emulated by perl.  To disable the emulations, set environment variable
+\&\f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR.
+.SS "Identifying DLLs"
+.IX Subsection "Identifying DLLs"
+All the DLLs built with the current versions of Perl have ID strings
+identifying the name of the extension, its version, and the version
+of Perl required for this DLL.  Run \f(CW\*(C`bldlevel DLL\-name\*(C'\fR to find this
+info.
+.SS "Centralized management of resources"
+.IX Subsection "Centralized management of resources"
+Since to call certain OS/2 API one needs to have a correctly initialized
+\&\f(CW\*(C`Win\*(C'\fR subsystem, OS/2\-specific extensions may require getting \f(CW\*(C`HAB\*(C'\fRs and
+\&\f(CW\*(C`HMQ\*(C'\fRs.  If an extension would do it on its own, another extension could
+fail to initialize.
+.PP
+Perl provides a centralized management of these resources:
+.ie n .IP """HAB""" 4
+.el .IP \f(CWHAB\fR 4
+.IX Item "HAB"
+To get the HAB, the extension should call \f(CW\*(C`hab = perl_hab_GET()\*(C'\fR in C.  After
+this call is performed, \f(CW\*(C`hab\*(C'\fR may be accessed as \f(CW\*(C`Perl_hab\*(C'\fR.  There is
+no need to release the HAB after it is used.
+.Sp
+If by some reasons \fIperl.h\fR cannot be included, use
+.Sp
+.Vb 1
+\&  extern int Perl_hab_GET(void);
+.Ve
+.Sp
+instead.
+.ie n .IP """HMQ""" 4
+.el .IP \f(CWHMQ\fR 4
+.IX Item "HMQ"
+There are two cases:
+.RS 4
+.IP \(bu 4
+the extension needs an \f(CW\*(C`HMQ\*(C'\fR only because some API will not work otherwise.
+Use \f(CW\*(C`serve = 0\*(C'\fR below.
+.IP \(bu 4
+the extension needs an \f(CW\*(C`HMQ\*(C'\fR since it wants to engage in a PM event loop.
+Use \f(CW\*(C`serve = 1\*(C'\fR below.
+.RE
+.RS 4
+.Sp
+To get an \f(CW\*(C`HMQ\*(C'\fR, the extension should call \f(CW\*(C`hmq = perl_hmq_GET(serve)\*(C'\fR in C.
+After this call is performed, \f(CW\*(C`hmq\*(C'\fR may be accessed as \f(CW\*(C`Perl_hmq\*(C'\fR.
+.Sp
+To signal to Perl that HMQ is not needed any more, call
+\&\f(CWperl_hmq_UNSET(serve)\fR.  Perl process will automatically morph/unmorph itself
+into/from a PM process if HMQ is needed/not\-needed.  Perl will automatically
+enable/disable \f(CW\*(C`WM_QUIT\*(C'\fR message during shutdown if the message queue is
+served/not\-served.
+.Sp
+\&\fBNOTE\fR.  If during a shutdown there is a message queue which did not disable
+WM_QUIT, and which did not process the received WM_QUIT message, the
+shutdown will be automatically cancelled.  Do not call \f(CWperl_hmq_GET(1)\fR
+unless you are going to process messages on an orderly basis.
+.RE
+.IP "Treating errors reported by OS/2 API" 4
+.IX Item "Treating errors reported by OS/2 API"
+There are two principal conventions (it is useful to call them \f(CW\*(C`Dos*\*(C'\fR
+and \f(CW\*(C`Win*\*(C'\fR \- though this part of the function signature is not always
+determined by the name of the API) of reporting the error conditions
+of OS/2 API.  Most of \f(CW\*(C`Dos*\*(C'\fR APIs report the error code as the result
+of the call (so 0 means success, and there are many types of errors).
+Most of \f(CW\*(C`Win*\*(C'\fR API report success/fail via the result being
+\&\f(CW\*(C`TRUE\*(C'\fR/\f(CW\*(C`FALSE\*(C'\fR; to find the reason for the failure one should call
+\&\fBWinGetLastError()\fR API.
+.Sp
+Some \f(CW\*(C`Win*\*(C'\fR entry points also overload a "meaningful" return value
+with the error indicator; having a 0 return value indicates an error.
+Yet some other \f(CW\*(C`Win*\*(C'\fR entry points overload things even more, and 0
+return value may mean a successful call returning a valid value 0, as
+well as an error condition; in the case of a 0 return value one should
+call \fBWinGetLastError()\fR API to distinguish a successful call from a
+failing one.
+.Sp
+By convention, all the calls to OS/2 API should indicate their
+failures by resetting $^E.  All the Perl-accessible functions which
+call OS/2 API may be broken into two classes: some \fBdie()\fRs when an API
+error is encountered, the other report the error via a false return
+value (of course, this does not concern Perl-accessible functions
+which \fIexpect\fR a failure of the OS/2 API call, having some workarounds
+coded).
+.Sp
+Obviously, in the situation of the last type of the signature of an OS/2
+API, it is must more convenient for the users if the failure is
+indicated by \fBdie()\fRing: one does not need to check $^E to know that
+something went wrong.  If, however, this solution is not desirable by
+some reason, the code in question should reset $^E to 0 before making
+this OS/2 API call, so that the caller of this Perl-accessible
+function has a chance to distinguish a success\-but\-0\-return value from
+a failure.  (One may return undef as an alternative way of reporting
+an error.)
+.Sp
+The macros to simplify this type of error propagation are
+.RS 4
+.ie n .IP CheckOSError(expr) 4
+.el .IP \f(CWCheckOSError(expr)\fR 4
+.IX Item "CheckOSError(expr)"
+Returns true on error, sets $^E.  Expects \fBexpr()\fR be a call of
+\&\f(CW\*(C`Dos*\*(C'\fR\-style API.
+.ie n .IP CheckWinError(expr) 4
+.el .IP \f(CWCheckWinError(expr)\fR 4
+.IX Item "CheckWinError(expr)"
+Returns true on error, sets $^E.  Expects \fBexpr()\fR be a call of
+\&\f(CW\*(C`Win*\*(C'\fR\-style API.
+.ie n .IP SaveWinError(expr) 4
+.el .IP \f(CWSaveWinError(expr)\fR 4
+.IX Item "SaveWinError(expr)"
+Returns \f(CW\*(C`expr\*(C'\fR, sets $^E from \fBWinGetLastError()\fR if \f(CW\*(C`expr\*(C'\fR is false.
+.ie n .IP """SaveCroakWinError(expr,die,name1,name2)""" 4
+.el .IP \f(CWSaveCroakWinError(expr,die,name1,name2)\fR 4
+.IX Item "SaveCroakWinError(expr,die,name1,name2)"
+Returns \f(CW\*(C`expr\*(C'\fR, sets $^E from \fBWinGetLastError()\fR if \f(CW\*(C`expr\*(C'\fR is false,
+and \fBdie()\fRs if \f(CW\*(C`die\*(C'\fR and $^E are true.  The message to die is the
+concatenated strings \f(CW\*(C`name1\*(C'\fR and \f(CW\*(C`name2\*(C'\fR, separated by \f(CW": "\fR from
+the contents of $^E.
+.ie n .IP """WinError_2_Perl_rc""" 4
+.el .IP \f(CWWinError_2_Perl_rc\fR 4
+.IX Item "WinError_2_Perl_rc"
+Sets \f(CW\*(C`Perl_rc\*(C'\fR to the return value of \fBWinGetLastError()\fR.
+.ie n .IP """FillWinError""" 4
+.el .IP \f(CWFillWinError\fR 4
+.IX Item "FillWinError"
+Sets \f(CW\*(C`Perl_rc\*(C'\fR to the return value of \fBWinGetLastError()\fR, and sets $^E
+to the corresponding value.
+.ie n .IP FillOSError(rc) 4
+.el .IP \f(CWFillOSError(rc)\fR 4
+.IX Item "FillOSError(rc)"
+Sets \f(CW\*(C`Perl_rc\*(C'\fR to \f(CW\*(C`rc\*(C'\fR, and sets $^E to the corresponding value.
+.RE
+.RS 4
+.RE
+.IP "Loading DLLs and ordinals in DLLs" 4
+.IX Item "Loading DLLs and ordinals in DLLs"
+Some DLLs are only present in some versions of OS/2, or in some
+configurations of OS/2.  Some exported entry points are present only
+in DLLs shipped with some versions of OS/2.  If these DLLs and entry
+points were linked directly for a Perl executable/DLL or from a Perl
+extensions, this binary would work only with the specified
+versions/setups.  Even if these entry points were not needed, the
+\&\fIload\fR of the executable (or DLL) would fail.
+.Sp
+For example, many newer useful APIs are not present in OS/2 v2; many
+PM-related APIs require DLLs not available on floppy-boot setup.
+.Sp
+To make these calls fail \fIonly when the calls are executed\fR, one
+should call these API via a dynamic linking API.  There is a subsystem
+in Perl to simplify such type of calls.  A large number of entry
+points available for such linking is provided (see \f(CW\*(C`entries_ordinals\*(C'\fR
+\&\- and also \f(CW\*(C`PMWIN_entries\*(C'\fR \- in \fIos2ish.h\fR).  These ordinals can be
+accessed via the APIs:
+.Sp
+.Vb 6
+\& CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
+\& DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
+\& DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
+\& DeclWinFuncByORD_CACHE_resetError_survive(),
+\& DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
+\& DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
+.Ve
+.Sp
+See the header files and the C code in the supplied OS/2\-related
+modules for the details on usage of these functions.
+.Sp
+Some of these functions also combine dynaloading semantic with the
+error-propagation semantic discussed above.
+.SH "Perl flavors"
+.IX Header "Perl flavors"
+Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
+same basket (though EMX environment tries hard to overcome this
+limitations, so the situation may somehow improve). There are 4
+executables for Perl provided by the distribution:
+.SS \fIperl.exe\fP
+.IX Subsection "perl.exe"
+The main workhorse. This is a chimera executable: it is compiled as an
+\&\f(CW\*(C`a.out\*(C'\fR\-style executable, but is linked with \f(CW\*(C`omf\*(C'\fR\-style dynamic
+library \fIperl.dll\fR, and with dynamic CRT DLL. This executable is a
+VIO application.
+.PP
+It can load perl dynamic extensions, and it can \fBfork()\fR.
+.PP
+\&\fBNote.\fR Keep in mind that \fBfork()\fR is needed to open a pipe to yourself.
+.SS \fIperl_.exe\fP
+.IX Subsection "perl_.exe"
+This is a statically linked \f(CW\*(C`a.out\*(C'\fR\-style executable. It cannot
+load dynamic Perl extensions. The executable supplied in binary
+distributions has a lot of extensions prebuilt, thus the above restriction is 
+important only if you use custom-built extensions. This executable is a VIO
+application.
+.PP
+\&\fIThis is the only executable with does not require OS/2.\fR The
+friends locked into \f(CW\*(C`M$\*(C'\fR world would appreciate the fact that this
+executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
+appropriate extender. See "Other OSes".
+.SS \fIperl_\|_.exe\fP
+.IX Subsection "perl__.exe"
+This is the same executable as \fIperl_\|_\|_.exe\fR, but it is a PM
+application.
+.PP
+\&\fBNote.\fR Usually (unless explicitly redirected during the startup)
+STDIN, STDERR, and STDOUT of a PM
+application are redirected to \fInul\fR. However, it is possible to \fIsee\fR
+them if you start \f(CW\*(C`perl_\|_.exe\*(C'\fR from a PM program which emulates a
+console window, like \fIShell mode\fR of Emacs or EPM. Thus it \fIis
+possible\fR to use Perl debugger (see perldebug) to debug your PM
+application (but beware of the message loop lockups \- this will not
+work if you have a message queue to serve, unless you hook the serving
+into the \fBgetc()\fR function of the debugger).
+.PP
+Another way to see the output of a PM program is to run it as
+.PP
+.Vb 1
+\&  pm_prog args 2>&1 | cat \-
+.Ve
+.PP
+with a shell \fIdifferent\fR from \fIcmd.exe\fR, so that it does not create
+a link between a VIO session and the session of \f(CW\*(C`pm_porg\*(C'\fR.  (Such a link
+closes the VIO window.)  E.g., this works with \fIsh.exe\fR \- or with Perl!
+.PP
+.Vb 2
+\&  open P, \*(Aqpm_prog args 2>&1 |\*(Aq or die;
+\&  print while <P>;
+.Ve
+.PP
+The flavor \fIperl_\|_.exe\fR is required if you want to start your program without
+a VIO window present, but not \f(CW\*(C`detach\*(C'\fRed (run \f(CW\*(C`help detach\*(C'\fR for more info).
+Very useful for extensions which use PM, like \f(CW\*(C`Perl/Tk\*(C'\fR or \f(CW\*(C`OpenGL\*(C'\fR.
+.PP
+Note also that the differences between PM and VIO executables are only
+in the \fIdefault\fR behaviour.  One can start \fIany\fR executable in
+\&\fIany\fR kind of session by using the arguments \f(CW\*(C`/fs\*(C'\fR, \f(CW\*(C`/pm\*(C'\fR or
+\&\f(CW\*(C`/win\*(C'\fR switches of the command \f(CW\*(C`start\*(C'\fR (of \fICMD.EXE\fR or a similar
+shell).  Alternatively, one can use the numeric first argument of the
+\&\f(CW\*(C`system\*(C'\fR Perl function (see OS2::Process).
+.SS \fIperl_\|_\|_.exe\fP
+.IX Subsection "perl___.exe"
+This is an \f(CW\*(C`omf\*(C'\fR\-style executable which is dynamically linked to
+\&\fIperl.dll\fR and CRT DLL. I know no advantages of this executable
+over \f(CW\*(C`perl.exe\*(C'\fR, but it cannot \fBfork()\fR at all. Well, one advantage is
+that the build process is not so convoluted as with \f(CW\*(C`perl.exe\*(C'\fR.
+.PP
+It is a VIO application.
+.SS "Why strange names?"
+.IX Subsection "Why strange names?"
+Since Perl processes the \f(CW\*(C`#!\*(C'\fR\-line (cf. 
+"DESCRIPTION" in perlrun, "Command Switches" in perlrun,
+"No Perl script found in input" in perldiag), it should know when a
+program \fIis a Perl\fR. There is some naming convention which allows
+Perl to distinguish correct lines from wrong ones. The above names are
+almost the only names allowed by this convention which do not contain
+digits (which have absolutely different semantics).
+.SS "Why dynamic linking?"
+.IX Subsection "Why dynamic linking?"
+Well, having several executables dynamically linked to the same huge
+library has its advantages, but this would not substantiate the
+additional work to make it compile. The reason is the complicated-to-developers
+but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
+.PP
+There are two distinctive features of the dyna-linking model of OS/2:
+first, all the references to external functions are resolved at the compile time;
+second, there is no runtime fixup of the DLLs after they are loaded into memory.
+The first feature is an enormous advantage over other models: it avoids
+conflicts when several DLLs used by an application export entries with
+the same name.  In such cases "other" models of dyna-linking just choose
+between these two entry points using some random criterion \- with predictable
+disasters as results.  But it is the second feature which requires the build
+of \fIperl.dll\fR.
+.PP
+The address tables of DLLs are patched only once, when they are
+loaded. The addresses of the entry points into DLLs are guaranteed to be
+the same for all the programs which use the same DLL.  This removes the
+runtime fixup \- once DLL is loaded, its code is read-only.
+.PP
+While this allows some (significant?) performance advantages, this makes life
+much harder for developers, since the above scheme makes it impossible
+for a DLL to be "linked" to a symbol in the \fI.EXE\fR file.  Indeed, this
+would need a DLL to have different relocations tables for the
+(different) executables which use this DLL.
+.PP
+However, a dynamically loaded Perl extension is forced to use some symbols
+from the perl
+executable, e.g., to know how to find the arguments to the functions:
+the arguments live on the perl
+internal evaluation stack. The solution is to put the main code of
+the interpreter into a DLL, and make the \fI.EXE\fR file which just loads
+this DLL into memory and supplies command-arguments.  The extension DLL
+cannot link to symbols in \fI.EXE\fR, but it has no problem linking
+to symbols in the \fI.DLL\fR.
+.PP
+This \fIgreatly\fR increases the load time for the application (as well as
+complexity of the compilation). Since interpreter is in a DLL,
+the C RTL is basically forced to reside in a DLL as well (otherwise
+extensions would not be able to use CRT).  There are some advantages if
+you use different flavors of perl, such as running \fIperl.exe\fR and
+\&\fIperl_\|_.exe\fR simultaneously: they share the memory of \fIperl.dll\fR.
+.PP
+\&\fBNOTE\fR.  There is one additional effect which makes DLLs more wasteful:
+DLLs are loaded in the shared memory region, which is a scarse resource
+given the 512M barrier of the "standard" OS/2 virtual memory.  The code of
+\&\fI.EXE\fR files is also shared by all the processes which use the particular
+\&\fI.EXE\fR, but they are "shared in the private address space of the process";
+this is possible because the address at which different sections
+of the \fI.EXE\fR file are loaded is decided at compile-time, thus all the
+processes have these sections loaded at same addresses, and no fixup
+of internal links inside the \fI.EXE\fR is needed.
+.PP
+Since DLLs may be loaded at run time, to have the same mechanism for DLLs
+one needs to have the address range of \fIany of the loaded\fR DLLs in the
+system to be available \fIin all the processes\fR which did not load a particular
+DLL yet.  This is why the DLLs are mapped to the shared memory region.
+.SS "Why chimera build?"
+.IX Subsection "Why chimera build?"
+Current EMX environment does not allow DLLs compiled using Unixish
+\&\f(CW\*(C`a.out\*(C'\fR format to export symbols for data (or at least some types of
+data). This forces \f(CW\*(C`omf\*(C'\fR\-style compile of \fIperl.dll\fR.
+.PP
+Current EMX environment does not allow \fI.EXE\fR files compiled in
+\&\f(CW\*(C`omf\*(C'\fR format to \fBfork()\fR. \fBfork()\fR is needed for exactly three Perl
+operations:
+.IP \(bu 4
+explicit \fBfork()\fR in the script,
+.IP \(bu 4
+\&\f(CW\*(C`open FH, "|\-"\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`open FH, "\-|"\*(C'\fR, in other words, opening pipes to itself.
+.PP
+While these operations are not questions of life and death, they are
+needed for a lot of
+useful scripts. This forces \f(CW\*(C`a.out\*(C'\fR\-style compile of
+\&\fIperl.exe\fR.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+Here we list environment variables with are either OS/2\- and DOS\- and
+Win*\-specific, or are more important under OS/2 than under other OSes.
+.ie n .SS """PERLLIB_PREFIX"""
+.el .SS \f(CWPERLLIB_PREFIX\fP
+.IX Subsection "PERLLIB_PREFIX"
+Specific for EMX port. Should have the form
+.PP
+.Vb 1
+\&  path1;path2
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&  path1 path2
+.Ve
+.PP
+If the beginning of some prebuilt path matches \fIpath1\fR, it is
+substituted with \fIpath2\fR.
+.PP
+Should be used if the perl library is moved from the default
+location in preference to \f(CW\*(C`PERL(5)LIB\*(C'\fR, since this would not leave wrong
+entries in \f(CW@INC\fR.  For example, if the compiled version of perl looks for \f(CW@INC\fR
+in \fIf:/perllib/lib\fR, and you want to install the library in
+\&\fIh:/opt/gnu\fR, do
+.PP
+.Vb 1
+\&  set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
+.Ve
+.PP
+This will cause Perl with the prebuilt \f(CW@INC\fR of
+.PP
+.Vb 5
+\&  f:/perllib/lib/5.00553/os2
+\&  f:/perllib/lib/5.00553
+\&  f:/perllib/lib/site_perl/5.00553/os2
+\&  f:/perllib/lib/site_perl/5.00553
+\&  .
+.Ve
+.PP
+to use the following \f(CW@INC:\fR
+.PP
+.Vb 5
+\&  h:/opt/gnu/5.00553/os2
+\&  h:/opt/gnu/5.00553
+\&  h:/opt/gnu/site_perl/5.00553/os2
+\&  h:/opt/gnu/site_perl/5.00553
+\&  .
+.Ve
+.ie n .SS """PERL_BADLANG"""
+.el .SS \f(CWPERL_BADLANG\fP
+.IX Subsection "PERL_BADLANG"
+If 0, perl ignores \fBsetlocale()\fR failing. May be useful with some
+strange \fIlocale\fRs.
+.ie n .SS """PERL_BADFREE"""
+.el .SS \f(CWPERL_BADFREE\fP
+.IX Subsection "PERL_BADFREE"
+If 0, perl would not warn of in case of unwarranted \fBfree()\fR. With older
+perls this might be
+useful in conjunction with the module DB_File, which was buggy when
+dynamically linked and OMF-built.
+.PP
+Should not be set with newer Perls, since this may hide some \fIreal\fR problems.
+.ie n .SS """PERL_SH_DIR"""
+.el .SS \f(CWPERL_SH_DIR\fP
+.IX Subsection "PERL_SH_DIR"
+Specific for EMX port. Gives the directory part of the location for
+\&\fIsh.exe\fR.
+.ie n .SS """USE_PERL_FLOCK"""
+.el .SS \f(CWUSE_PERL_FLOCK\fP
+.IX Subsection "USE_PERL_FLOCK"
+Specific for EMX port. Since \fBflock\fR\|(3) is present in EMX, but is not 
+functional, it is emulated by perl.  To disable the emulations, set 
+environment variable \f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR.
+.ie n .SS """TMP"" or ""TEMP"""
+.el .SS "\f(CWTMP\fP or \f(CWTEMP\fP"
+.IX Subsection "TMP or TEMP"
+Specific for EMX port. Used as storage place for temporary files.
+.SH Evolution
+.IX Header "Evolution"
+Here we list major changes which could make you by surprise.
+.SS "Text-mode filehandles"
+.IX Subsection "Text-mode filehandles"
+Starting from version 5.8, Perl uses a builtin translation layer for
+text-mode files.  This replaces the efficient well-tested EMX layer by
+some code which should be best characterized as a "quick hack".
+.PP
+In addition to possible bugs and an inability to follow changes to the
+translation policy with off/on switches of TERMIO translation, this
+introduces a serious incompatible change: before \fBsysread()\fR on
+text-mode filehandles would go through the translation layer, now it
+would not.
+.SS Priorities
+.IX Subsection "Priorities"
+\&\f(CW\*(C`setpriority\*(C'\fR and \f(CW\*(C`getpriority\*(C'\fR are not compatible with earlier
+ports by Andreas Kaiser. See "setpriority, getpriority".
+.SS "DLL name mangling: pre 5.6.2"
+.IX Subsection "DLL name mangling: pre 5.6.2"
+With the release 5.003_01 the dynamically loadable libraries
+should be rebuilt when a different version of Perl is compiled. In particular,
+DLLs (including \fIperl.dll\fR) are now created with the names
+which contain a checksum, thus allowing workaround for OS/2 scheme of
+caching DLLs.
+.PP
+It may be possible to code a simple workaround which would
+.IP \(bu 4
+find the old DLLs looking through the old \f(CW@INC\fR;
+.IP \(bu 4
+mangle the names according to the scheme of new perl and copy the DLLs to
+these names;
+.IP \(bu 4
+edit the internal \f(CW\*(C`LX\*(C'\fR tables of DLL to reflect the change of the name
+(probably not needed for Perl extension DLLs, since the internally coded names
+are not used for "specific" DLLs, they used only for "global" DLLs).
+.IP \(bu 4
+edit the internal \f(CW\*(C`IMPORT\*(C'\fR tables and change the name of the "old"
+\&\fIperl????.dll\fR to the "new" \fIperl????.dll\fR.
+.SS "DLL name mangling: 5.6.2 and beyond"
+.IX Subsection "DLL name mangling: 5.6.2 and beyond"
+In fact mangling of \fIextension\fR DLLs was done due to misunderstanding
+of the OS/2 dynaloading model.  OS/2 (effectively) maintains two
+different tables of loaded DLL:
+.IP "Global DLLs" 4
+.IX Item "Global DLLs"
+those loaded by the base name from \f(CW\*(C`LIBPATH\*(C'\fR; including those
+associated at link time;
+.IP "specific DLLs" 4
+.IX Item "specific DLLs"
+loaded by the full name.
+.PP
+When resolving a request for a global DLL, the table of already-loaded
+specific DLLs is (effectively) ignored; moreover, specific DLLs are
+\&\fIalways\fR loaded from the prescribed path.
+.PP
+There is/was a minor twist which makes this scheme fragile: what to do
+with DLLs loaded from
+.ie n .IP """BEGINLIBPATH"" and ""ENDLIBPATH""" 4
+.el .IP "\f(CWBEGINLIBPATH\fR and \f(CWENDLIBPATH\fR" 4
+.IX Item "BEGINLIBPATH and ENDLIBPATH"
+(which depend on the process)
+.ie n .IP "\fI.\fR from ""LIBPATH""" 4
+.el .IP "\fI.\fR from \f(CWLIBPATH\fR" 4
+.IX Item ". from LIBPATH"
+which \fIeffectively\fR depends on the process (although \f(CW\*(C`LIBPATH\*(C'\fR is the
+same for all the processes).
+.PP
+Unless \f(CW\*(C`LIBPATHSTRICT\*(C'\fR is set to \f(CW\*(C`T\*(C'\fR (and the kernel is after
+2000/09/01), such DLLs are considered to be global.  When loading a
+global DLL it is first looked in the table of already-loaded global
+DLLs.  Because of this the fact that one executable loaded a DLL from
+\&\f(CW\*(C`BEGINLIBPATH\*(C'\fR and \f(CW\*(C`ENDLIBPATH\*(C'\fR, or \fI.\fR from \f(CW\*(C`LIBPATH\*(C'\fR may affect
+\&\fIwhich\fR DLL is loaded when \fIanother\fR executable requests a DLL with
+the same name.  \fIThis\fR is the reason for version-specific mangling of
+the DLL name for perl DLL.
+.PP
+Since the Perl extension DLLs are always loaded with the full path,
+there is no need to mangle their names in a version-specific ways:
+their directory already reflects the corresponding version of perl,
+and \f(CW@INC\fR takes into account binary compatibility with older version.
+Starting from \f(CW5.6.2\fR the name mangling scheme is fixed to be the
+same as for Perl 5.005_53 (same as in a popular binary release).  Thus
+new Perls will be able to \fIresolve the names\fR of old extension DLLs
+if \f(CW@INC\fR allows finding their directories.
+.PP
+However, this still does not guarantee that these DLL may be loaded.
+The reason is the mangling of the name of the \fIPerl DLL\fR.  And since
+the extension DLLs link with the Perl DLL, extension DLLs for older
+versions would load an older Perl DLL, and would most probably
+segfault (since the data in this DLL is not properly initialized).
+.PP
+There is a partial workaround (which can be made complete with newer
+OS/2 kernels): create a forwarder DLL with the same name as the DLL of
+the older version of Perl, which forwards the entry points to the
+newer Perl's DLL.  Make this DLL accessible on (say) the \f(CW\*(C`BEGINLIBPATH\*(C'\fR of
+the new Perl executable.  When the new executable accesses old Perl's
+extension DLLs, they would request the old Perl's DLL by name, get the
+forwarder instead, so effectively will link with the currently running
+(new) Perl DLL.
+.PP
+This may break in two ways:
+.IP \(bu 4
+Old perl executable is started when a new executable is running has
+loaded an extension compiled for the old executable (ouph!).  In this
+case the old executable will get a forwarder DLL instead of the old
+perl DLL, so would link with the new perl DLL.  While not directly
+fatal, it will behave the same as new executable.  This beats the whole
+purpose of explicitly starting an old executable.
+.IP \(bu 4
+A new executable loads an extension compiled for the old executable
+when an old perl executable is running.  In this case the extension
+will not pick up the forwarder \- with fatal results.
+.PP
+With support for \f(CW\*(C`LIBPATHSTRICT\*(C'\fR this may be circumvented \- unless
+one of DLLs is started from \fI.\fR from \f(CW\*(C`LIBPATH\*(C'\fR (I do not know
+whether \f(CW\*(C`LIBPATHSTRICT\*(C'\fR affects this case).
+.PP
+\&\fBREMARK\fR.  Unless newer kernels allow \fI.\fR in \f(CW\*(C`BEGINLIBPATH\*(C'\fR (older
+do not), this mess cannot be completely cleaned.  (It turns out that
+as of the beginning of 2002, \fI.\fR is not allowed, but \fI.\e.\fR is \- and
+it has the same effect.)
+.PP
+\&\fBREMARK\fR.  \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, \f(CW\*(C`BEGINLIBPATH\*(C'\fR and \f(CW\*(C`ENDLIBPATH\*(C'\fR are
+not environment variables, although \fIcmd.exe\fR emulates them on \f(CW\*(C`SET
+\&...\*(C'\fR lines.  From Perl they may be accessed by
+Cwd::extLibpath and
+Cwd::extLibpath_set.
+.SS "DLL forwarder generation"
+.IX Subsection "DLL forwarder generation"
+Assume that the old DLL is named \fIperlE0AC.dll\fR (as is one for
+5.005_53), and the new version is 5.6.1.  Create a file
+\&\fIperl5shim.def\-leader\fR with
+.PP
+.Vb 5
+\&  LIBRARY \*(AqperlE0AC\*(Aq INITINSTANCE TERMINSTANCE
+\&  DESCRIPTION \*(Aq@#perl5\-porters@perl.org:5.006001#@ Perl module for 5.00553 \-> Perl 5.6.1 forwarder\*(Aq
+\&  CODE LOADONCALL
+\&  DATA LOADONCALL NONSHARED MULTIPLE
+\&  EXPORTS
+.Ve
+.PP
+modifying the versions/names as needed.  Run
+.PP
+.Vb 2
+\& perl \-wnle "next if 0../EXPORTS/; print qq(  \e"$1\e")
+\&                                          if /\e"(\ew+)\e"/" perl5.def >lst
+.Ve
+.PP
+in the Perl build directory (to make the DLL smaller replace perl5.def
+with the definition file for the older version of Perl if present).
+.PP
+.Vb 2
+\& cat perl5shim.def\-leader lst >perl5shim.def
+\& gcc \-Zomf \-Zdll \-o perlE0AC.dll perl5shim.def \-s \-llibperl
+.Ve
+.PP
+(ignore multiple \f(CW\*(C`warning L4085\*(C'\fR).
+.SS Threading
+.IX Subsection "Threading"
+As of release 5.003_01 perl is linked to multithreaded C RTL
+DLL.  If perl itself is not compiled multithread-enabled, so will not be perl's
+\&\fBmalloc()\fR. However, extensions may use multiple thread on their own
+risk.
+.PP
+This was needed to compile \f(CW\*(C`Perl/Tk\*(C'\fR for XFree86\-OS/2 out-of-the-box, and
+link with DLLs for other useful libraries, which typically are compiled
+with \f(CW\*(C`\-Zmt \-Zcrtdll\*(C'\fR.
+.SS "Calls to external programs"
+.IX Subsection "Calls to external programs"
+Due to a popular demand the perl external program calling has been
+changed wrt Andreas Kaiser's port.  \fIIf\fR perl needs to call an
+external program \fIvia shell\fR, the \fIf:/bin/sh.exe\fR will be called, or
+whatever is the override, see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR".
+.PP
+Thus means that you need to get some copy of a \fIsh.exe\fR as well (I
+use one from pdksh). The path \fIF:/bin\fR above is set up automatically during
+the build to a correct value on the builder machine, but is
+overridable at runtime,
+.PP
+\&\fBReasons:\fR a consensus on \f(CW\*(C`perl5\-porters\*(C'\fR was that perl should use
+one non-overridable shell per platform. The obvious choices for OS/2
+are \fIcmd.exe\fR and \fIsh.exe\fR. Having perl build itself would be impossible
+with \fIcmd.exe\fR as a shell, thus I picked up \f(CW\*(C`sh.exe\*(C'\fR. This assures almost
+100% compatibility with the scripts coming from *nix. As an added benefit 
+this works as well under DOS if you use DOS-enabled port of pdksh 
+(see "Prerequisites").
+.PP
+\&\fBDisadvantages:\fR currently \fIsh.exe\fR of pdksh calls external programs
+via \fBfork()\fR/\fBexec()\fR, and there is \fIno\fR functioning \fBexec()\fR on
+OS/2. \fBexec()\fR is emulated by EMX by an asynchronous call while the caller
+waits for child completion (to pretend that the \f(CW\*(C`pid\*(C'\fR did not change). This
+means that 1 \fIextra\fR copy of \fIsh.exe\fR is made active via \fBfork()\fR/\fBexec()\fR,
+which may lead to some resources taken from the system (even if we do
+not count extra work needed for \fBfork()\fRing).
+.PP
+Note that this a lesser issue now when we do not spawn \fIsh.exe\fR
+unless needed (metachars found).
+.PP
+One can always start \fIcmd.exe\fR explicitly via
+.PP
+.Vb 1
+\&  system \*(Aqcmd\*(Aq, \*(Aq/c\*(Aq, \*(Aqmycmd\*(Aq, \*(Aqarg1\*(Aq, \*(Aqarg2\*(Aq, ...
+.Ve
+.PP
+If you need to use \fIcmd.exe\fR, and do not want to hand-edit thousands of your
+scripts, the long-term solution proposed on p5\-p is to have a directive
+.PP
+.Vb 1
+\&  use OS2::Cmd;
+.Ve
+.PP
+which will override \fBsystem()\fR, \fBexec()\fR, \f(CW\`\`\fR, and
+\&\f(CW\*(C`open(,\*(Aq...|\*(Aq)\*(C'\fR. With current perl you may override only \fBsystem()\fR,
+\&\fBreadpipe()\fR \- the explicit version of \f(CW\`\`\fR, and maybe \fBexec()\fR. The code
+will substitute the one-argument call to \fBsystem()\fR by
+\&\f(CW\*(C`CORE::system(\*(Aqcmd.exe\*(Aq, \*(Aq/c\*(Aq, shift)\*(C'\fR.
+.PP
+If you have some working code for \f(CW\*(C`OS2::Cmd\*(C'\fR, please send it to me,
+I will include it into distribution. I have no need for such a module, so
+cannot test it.
+.PP
+For the details of the current situation with calling external programs,
+see "Starting OS/2 (and DOS) programs under Perl".  Set us
+mention a couple of features:
+.IP \(bu 4
+External scripts may be called by their basename.  Perl will try the same
+extensions as when processing \fB\-S\fR command-line switch.
+.IP \(bu 4
+External scripts starting with \f(CW\*(C`#!\*(C'\fR or \f(CW\*(C`extproc \*(C'\fR will be executed directly,
+without calling the shell, by calling the program specified on the rest of
+the first line.
+.SS "Memory allocation"
+.IX Subsection "Memory allocation"
+Perl uses its own \fBmalloc()\fR under OS/2 \- interpreters are usually malloc-bound
+for speed, but perl is not, since its malloc is lightning-fast.
+Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
+than EMX one.  I do not have convincing data about memory footprint, but
+a (pretty random) benchmark showed that Perl's one is 5% better.
+.PP
+Combination of perl's \fBmalloc()\fR and rigid DLL name resolution creates
+a special problem with library functions which expect their return value to
+be \fBfree()\fRd by system's \fBfree()\fR. To facilitate extensions which need to call 
+such functions, system memory-allocation functions are still available with
+the prefix \f(CW\*(C`emx_\*(C'\fR added. (Currently only DLL perl has this, it should 
+propagate to \fIperl_.exe\fR shortly.)
+.SS Threads
+.IX Subsection "Threads"
+One can build perl with thread support enabled by providing \f(CW\*(C`\-D usethreads\*(C'\fR
+option to \fIConfigure\fR.  Currently OS/2 support of threads is very 
+preliminary.
+.PP
+Most notable problems:
+.ie n .IP """COND_WAIT""" 4
+.el .IP \f(CWCOND_WAIT\fR 4
+.IX Item "COND_WAIT"
+may have a race condition (but probably does not due to edge-triggered
+nature of OS/2 Event semaphores).  (Needs a reimplementation (in terms of chaining
+waiting threads, with the linked list stored in per-thread structure?)?)
+.IP \fIos2.c\fR 4
+.IX Item "os2.c"
+has a couple of static variables used in OS/2\-specific functions.  (Need to be
+moved to per-thread structure, or serialized?)
+.PP
+Note that these problems should not discourage experimenting, since they
+have a low probability of affecting small programs.
+.SH BUGS
+.IX Header "BUGS"
+This description is not updated often (since 5.6.1?), see \fI./os2/Changes\fR
+for more info.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Ilya Zakharevich, cpan@ilyaz.org
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1).
diff --git a/upstream/mageia-cauldron/man1/perlos390.1 b/upstream/mageia-cauldron/man1/perlos390.1
new file mode 100644
index 00000000..ac742398
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlos390.1
@@ -0,0 +1,506 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOS390 1"
+.TH PERLOS390 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlos390 \- building and installing Perl for z/OS (previously called OS/390)
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+This document will help you Configure, build, test and install Perl
+on z/OS Unix System Services.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and
+should work fine with z/OS 2.5.
+It may work on other versions or releases, but those are
+the ones it has been tested on.
+.PP
+The native character set for z/OS is EBCDIC, but it can also run in ASCII mode.
+Perl can support either, but you have to compile it explicitly for one or the
+other.  You could have both an ASCII perl, and an EBCDIC perl on the same
+machine.  If you use ASCII mode and an ASCII perl, the Encode module shipped
+with perl can be used to translate files from various EBCDIC code pages for
+handling by perl, and then back on output
+.PP
+This document describes how to build a 64\-bit Dynamic Perl, either ASCII or
+EBCDIC.  You can interactively choose other configurations, as well as many
+other options in the Configure script that is run as part of the build
+process.  You may need to carry out some system configuration tasks before
+running Configure, as detailed below.
+.SS Tools
+.IX Subsection "Tools"
+You will want to get GNU make 4.1 or later. GNU make can be downloaded from a
+port that Rocket Software provides.  You will need the z/OS c99 compiler from
+IBM (though xlc in c99 mode without optimization turned on works in EBCDIC).
+.PP
+If you want the latest development version of Perl, you will need git.
+You can use git on another platform and transfer the result via sftp or ftp to
+z/OS.  But there is a z/OS native git client port available through Rocket
+Software.
+.PP
+You may also need the gunzip client port that Rocket Software provides to unzip
+any zipped tarball you upload to z/OS.
+.SS "Building a 64\-bit Dynamic ASCII Perl"
+.IX Subsection "Building a 64-bit Dynamic ASCII Perl"
+For building from an official stable release of Perl, go to
+<https://www.perl.org/get.html> and choose any one of the
+"Download latest stable source" buttons.  This will get you a tarball.  The
+name of that tarball will be something like 'perl\-V.R.M,tar,gz', where V.R.M is
+the version/release/modification of the perl you are downloading. Do
+.PP
+.Vb 1
+\&  gunzip perl\-V.R.M.tar.gz
+.Ve
+.PP
+Then one of:
+.PP
+.Vb 1
+\&  tar \-xvf perl\-V.R.M.tar
+\&
+\&  pax \-r \-f perl\-V.R.M.tar
+.Ve
+.PP
+Either of these will create the source directory.  You can rename it to
+whatever you like; for these instructions, 'perl' is assumed to be the name.
+.PP
+If instead you want the latest unstable development release, using the native
+git on z/OS, clone Perl:
+.PP
+.Vb 1
+\&  git clone https://github.com/Perl/perl5.git perl
+.Ve
+.PP
+Either way, once you have a 'perl' directory containing the source, cd into it,
+and tag all the code as ASCII:
+.PP
+.Vb 2
+\&  cd perl
+\&  chtag \-R \-h \-t \-cISO8859\-1 *
+.Ve
+.PP
+Configure the build environment as 64\-bit, Dynamic, ASCII, development,
+deploying it to \fI/usr/local/perl/ascii\fR:
+.PP
+.Vb 4
+\&  export PATH=$PWD:$PATH
+\&  export LIBPATH=$PWD:$PATH
+\&  ./Configure \-Dprefix=/usr/local/perl/ascii \-des \-Dusedevel \e
+\&        \-Duse64bitall \-Dusedl
+.Ve
+.PP
+If you are building from a stable source, you don't need "\-Dusedevel".
+(If you run Configure without options, it will interactively ask you about
+every possible option based on its probing of what's available on your
+particular machine, so you can choose as you go along.)
+.PP
+Run GNU make to build Perl
+.PP
+.Vb 1
+\&  make
+.Ve
+.PP
+Run tests to ensure Perl is working correctly. Currently, there are about a
+dozen failing tests out of nearly 2500
+.PP
+.Vb 1
+\&  make test_harness
+.Ve
+.PP
+Install Perl into \fI/usr/local/perl/ascii\fR:
+.PP
+.Vb 1
+\&  make install
+.Ve
+.SS "Building a 64\-bit Dynamic EBCDIC Perl"
+.IX Subsection "Building a 64-bit Dynamic EBCDIC Perl"
+You will need a working perl on some box with connectivity to the destination
+machine.  On z/OS, it could be an ASCII perl, or a previous EBCDIC one.
+Many machines will already have a pre-built perl already running, or one can
+easily be downloaded from <https://www.perl.org/get.html>.
+.PP
+Follow the directions above in "Building a 64\-bit Dynamic ASCII Perl" as far as
+getting a populated 'perl' directory.  Then come back here to proceed.
+.PP
+The downloaded perl will need to be converted to 1047 EBCDIC.  To do this:
+.PP
+.Vb 2
+\&  cd perl
+\&  Porting/makerel \-e
+.Ve
+.PP
+If the Porting/makerel step fails with an error that it can not issue the tar
+command, proceed to issue the command interactively, where V.R.M is the
+version/release/modification of Perl you are uploading:
+.PP
+.Vb 2
+\&  cd ../
+\&  tar cf \-  \-\-format=ustar perl\-V.R.M | gzip \-\-best > perl\-V.R.M.tar.gz
+.Ve
+.PP
+Use sftp to upload the zipped tar file to z/OS:
+.PP
+.Vb 3
+\&  sftp <your system>
+\&  cd /tmp
+\&  put perl\-V.R.M.tar.gz
+.Ve
+.PP
+Unzip and untar the zipped tar file on z/OS:
+.PP
+.Vb 2
+\&  cd /tmp
+\&  gunzip perl\-V.R.M.tar.gz
+.Ve
+.PP
+Then one of:
+.PP
+.Vb 1
+\&  tar \-xvf perl\-V.R.M.tar
+\&
+\&  pax \-r \-f perl\-V.R.M.tar
+.Ve
+.PP
+You now have the source code for the EBCDIC Perl on z/OS and can proceed to
+build it. This is analagous to how you would build the code for ASCII, but
+note: you \fBshould not\fR tag the code but instead leave it untagged.
+.PP
+Configure the build environment as 64\-bit, Dynamic, native, development,
+deploying it to \fI/usr/local/perl/ebcdic\fR:
+.PP
+.Vb 4
+\&  export PATH=$PWD:$PATH
+\&  export LIBPATH=$PWD:$PATH
+\&  ./Configure \-Dprefix=/usr/local/perl/ebcdic \-des \-Dusedevel \e
+\&        \-Duse64bitall \-Dusedl
+.Ve
+.PP
+If you are building from a stable source, you don't need "\-Dusedevel".
+(If you run Configure without options, it will interactively ask you about
+every possible option based on its probing of what's available on your
+particular machine, so you can choose as you go along.)
+.PP
+Run GNU make to build Perl
+.PP
+.Vb 1
+\&  make
+.Ve
+.PP
+Run tests to ensure Perl is working correctly.
+.PP
+.Vb 1
+\&  make test_harness
+.Ve
+.PP
+You might also want to have GNU groff for OS/390 installed before
+running the "make install" step for Perl.
+.PP
+Install Perl into \fI/usr/local/perl/ebcdic\fR:
+.PP
+.Vb 1
+\&  make install
+.Ve
+.PP
+EBCDIC Perl is still a work in progress.  All the core code works as far as we
+know, but various modules you might want to download from CPAN do not.  The
+failures range from very minor to catastrophic.  Many of them are simply bugs
+in the tests, with the module actually working properly.  This happens because,
+for example, the test is coded to expect a certain character ASCII code point;
+when it gets the EBCDIC value back instead, it complains.  But the code
+actually worked.  Other potential failures that aren't really failures stem
+from checksums coming out differently, since \f(CW\*(C`A\*(C'\fR, for example, has a different
+bit representation between the character sets.  A test that is expecting the
+ASCII value will show failure, even if the module is working perfectly.  Also
+in sorting, uppercase letters come before lowercase letters on ASCII systems;
+the reverse on EBCDIC.
+.PP
+Some CPAN modules come bundled with the downloaded perl.  And a few of those
+have yet to be fixed to pass on EBCDIC platforms.  As a result they are skipped
+when you run 'make test'.  The current list is:
+.PP
+.Vb 10
+\& Archive::Tar
+\& Config::Perl::V
+\& CPAN::Meta
+\& CPAN::Meta::YAML
+\& Digest::MD5
+\& Digest::SHA
+\& Encode
+\& ExtUtils::MakeMaker
+\& ExtUtils::Manifest
+\& HTTP::Tiny
+\& IO::Compress
+\& IPC::Cmd
+\& JSON::PP
+\& libnet
+\& MIME::Base64
+\& Module::Metadata
+\& PerlIO::via\-QuotedPrint
+\& Pod::Checker
+\& podlators
+\& Pod::Simple
+\& Socket
+\& Test::Harness
+.Ve
+.PP
+See also \fIhints/os390.sh\fR for other potential gotchas.
+.SS "Setup and utilities for Perl on OS/390"
+.IX Subsection "Setup and utilities for Perl on OS/390"
+This may also be a good time to ensure that your \fI/etc/protocol\fR file
+and either your \fI/etc/resolv.conf\fR or \fI/etc/hosts\fR files are in place.
+The IBM document that describes such USS system setup issues is
+"z/OS UNIX System Services Planning"
+.PP
+For successful testing you may need to turn on the sticky bit for your
+world readable /tmp directory if you have not already done so (see man chmod).
+.SS "Useful files for trouble-shooting"
+.IX Subsection "Useful files for trouble-shooting"
+If your configuration is failing, read hints/os390.sh
+This file provides z/OS specific options to direct the build process.
+.PP
+\fIShell\fR
+.IX Subsection "Shell"
+.PP
+A message of the form:
+.PP
+.Vb 3
+\& (I see you are using the Korn shell.  Some ksh\*(Aqs blow up on Configure,
+\& mainly on older exotic systems.  If yours does, try the Bourne shell
+\& instead.)
+.Ve
+.PP
+is nothing to worry about at all.
+.PP
+\fIDynamic loading\fR
+.IX Subsection "Dynamic loading"
+.PP
+Dynamic loading is required if you want to use XS modules from CPAN (like
+DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from
+CPAN with newer versions (like Encode) without rebuilding all of the perl
+binary.
+.PP
+The instructions above will create a dynamic Perl. If you do not want to
+use dynamic loading, remove the \-Dusedl option.
+See the comments in hints/os390.sh for more information on dynamic loading.
+.PP
+\fIOptimizing\fR
+.IX Subsection "Optimizing"
+.PP
+Optimization has not been turned on yet. There may be issues if Perl
+is optimized.
+.SS "Build Anomalies with Perl on OS/390"
+.IX Subsection "Build Anomalies with Perl on OS/390"
+"Out of memory!" messages during the build of Perl are most often fixed
+by re building the GNU make utility for OS/390 from a source code kit.
+.PP
+Within USS your \fI/etc/profile\fR or \fR\f(CI$HOME\fR\fI/.profile\fR may limit your ulimit
+settings.  Check that the following command returns reasonable values:
+.PP
+.Vb 1
+\&    ulimit \-a
+.Ve
+.PP
+To conserve memory you should have your compiler modules loaded into the
+Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
+.PP
+If the compiler complains of syntax errors during the build of the
+Socket extension then be sure to fix the syntax error in the system
+header /usr/include/sys/socket.h.
+.SS "Testing Anomalies with Perl on OS/390"
+.IX Subsection "Testing Anomalies with Perl on OS/390"
+The "make test" step runs a Perl Verification Procedure, usually before
+installation.  You might encounter STDERR messages even during a successful
+run of "make test".  Here is a guide to some of the more commonly seen
+anomalies:
+.PP
+\fIOut of Memory (31\-bit only)\fR
+.IX Subsection "Out of Memory (31-bit only)"
+.PP
+Out of memory problems should not be an issue, unless you are attempting to build
+a 31\-bit Perl.
+.PP
+If you _are_ building a 31\-bit Perl, the constrained environment may mean you
+need to change memory options for Perl.
+In addition to the comments
+above on memory limitations it is also worth checking for _CEE_RUNOPTS
+in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31\-bit only
+to set CEE run options, but the environment variable wins.
+.PP
+The 31\-bit C code asks for:
+.PP
+.Vb 1
+\& #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
+.Ve
+.PP
+The important parts of that are the second argument (the increment) to HEAP,
+and allowing the stack to be "Above the (16M) line". If the heap
+increment is too small then when perl (for example loading unicode/Name.pl) tries
+to create a "big" (400K+) string it cannot fit in a single segment
+and you get "Out of Memory!" \- even if there is still plenty of memory
+available.
+.PP
+A related issue is use with perl's malloc. Perl's malloc uses \f(CWsbrk()\fR
+to get memory, and \f(CWsbrk()\fR is limited to the first allocation so in this
+case something like:
+.PP
+.Vb 1
+\&  HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
+.Ve
+.PP
+is needed to get through the test suite.
+.SS "Usage Hints for Perl on z/OS"
+.IX Subsection "Usage Hints for Perl on z/OS"
+When using Perl on z/OS please keep in mind that the EBCDIC and ASCII
+character sets are different.  See perlebcdic for more on such character
+set issues.  Perl builtin functions that may behave differently under
+EBCDIC are also mentioned in the perlport.pod document.
+.PP
+If you are having trouble with square brackets then consider switching your
+rlogin or telnet client.  Try to avoid older 3270 emulators and ISHELL for
+working with Perl on USS.
+.SS "Modules and Extensions for Perl on z/OS (Static Only)"
+.IX Subsection "Modules and Extensions for Perl on z/OS (Static Only)"
+Pure Perl (that is non XS) modules may be installed via the usual:
+.PP
+.Vb 4
+\&    perl Makefile.PL
+\&    make
+\&    make test
+\&    make install
+.Ve
+.PP
+If you built perl with dynamic loading capability then that would also
+be the way to build XS based extensions.  However, if you built perl with
+static linking you can still build XS based extensions for z/OS
+but you will need to follow the instructions in ExtUtils::MakeMaker for
+building statically linked perl binaries.  In the simplest configurations
+building a static perl + XS extension boils down to:
+.PP
+.Vb 6
+\&    perl Makefile.PL
+\&    make
+\&    make perl
+\&    make test
+\&    make install
+\&    make \-f Makefile.aperl inst_perl MAP_TARGET=perl
+.Ve
+.SS "Running Perl on z/OS"
+.IX Subsection "Running Perl on z/OS"
+To run the 64\-bit Dynamic Perl environment, update your PATH and LIBPATH
+to include the location you installed Perl into, and then run the perl you
+installed as perlV.R.M where V/R/M is the Version/Release/Modification level
+of the current development level.
+If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to
+set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl
+source code you run is tagged appropriately as ASCII or EBCDIC using
+"chtag \-t \-c<CCSID>":
+.IP "For ASCII Only:" 4
+.IX Item "For ASCII Only:"
+.Vb 5
+\& export _BPXK_AUTOCVT=ON
+\& export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)"
+\& export _TAG_REDIR_ERR="txt"
+\& export _TAG_REDIR_IN="txt"
+\& export _TAG_REDIR_OUT="txt"
+.Ve
+.IP "For ASCII or EBCDIC:" 4
+.IX Item "For ASCII or EBCDIC:"
+.Vb 3
+\& export PATH=/usr/local/perl/ascii:$PATH
+\& export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH
+\& perlV.R.M args
+.Ve
+.PP
+If tcsh is your login shell then use the setenv command.
+.SH AUTHORS
+.IX Header "AUTHORS"
+David Fiander and Peter Prymmer with thanks to Dennis Longnecker
+and William Raffloer for valuable reports, LPAR and PTF feedback.
+Thanks to Mike MacIsaac and Egon Terwedow for SG24\-5944\-00.
+Thanks to Ignasi Roca for pointing out the floating point problems.
+Thanks to John Goodyear for dynamic loading help.
+.PP
+Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64\-bit and
+ASCII/EBCDIC Bi-Modal support
+.SH "OTHER SITES"
+.IX Header "OTHER SITES"
+<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools
+for building various z/OS Perl configurations and has some useful tools in the
+\&'bin' directory you may want to use for building z/OS Perl yourself.
+.SH HISTORY
+.IX Header "HISTORY"
+Updated 24 December 2021 to enable initial ASCII support
+.PP
+Updated 03 October  2019 for perl\-5.33.3+
+.PP
+Updated 28 November 2001 for broken URLs.
+.PP
+Updated 12 March    2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
+.PP
+Updated 24 January  2001 to mention dynamic loading.
+.PP
+Updated 15 January  2001 for the 5.7.1 release of Perl.
+.PP
+Updated 12 November 2000 for the 5.7.1 release of Perl.
+.PP
+This document was podified for the 5.005_03 release of Perl 11 March 1999.
+.PP
+This document was originally written by David Fiander for the 5.005
+release of Perl.
diff --git a/upstream/mageia-cauldron/man1/perlos400.1 b/upstream/mageia-cauldron/man1/perlos400.1
new file mode 100644
index 00000000..286a5610
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlos400.1
@@ -0,0 +1,175 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLOS400 1"
+.TH PERLOS400 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlos400 \- Perl version 5 on OS/400
+.PP
+This document needs to be updated, but we don't know what it should say.
+Please submit comments to <https://github.com/Perl/perl5/issues>.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of IBM's OS/400 operating
+system that will affect how Perl version 5 (hereafter just Perl) is
+compiled and/or runs.
+.PP
+By far the easiest way to build Perl for OS/400 is to use the PASE
+(Portable Application Solutions Environment), for more information see
+<http://www.iseries.ibm.com/developer/factory/pase/index.html>
+This environment allows one to use AIX APIs while programming, and it
+provides a runtime that allows AIX binaries to execute directly on the
+PowerPC iSeries.
+.SS "Compiling Perl for OS/400 PASE"
+.IX Subsection "Compiling Perl for OS/400 PASE"
+The recommended way to build Perl for the OS/400 PASE is to build the
+Perl 5 source code (release 5.8.1 or later) under AIX.
+.PP
+The trick is to give a special parameter to the Configure shell script
+when running it on AIX:
+.PP
+.Vb 1
+\&  sh Configure \-DPASE ...
+.Ve
+.PP
+The default installation directory of Perl under PASE is /QOpenSys/perl.
+This can be modified if needed with Configure parameter \-Dprefix=/some/dir.
+.PP
+Starting from OS/400 V5R2 the IBM Visual Age compiler is supported
+on OS/400 PASE, so it is possible to build Perl natively on OS/400.  
+The easier way, however, is to compile in AIX, as just described.
+.PP
+If you don't want to install the compiled Perl in AIX into /QOpenSys
+(for packaging it before copying it to PASE), you can use a Configure
+parameter: \-Dinstallprefix=/tmp/QOpenSys/perl.  This will cause the
+"make install" to install everything into that directory, while the
+installed files still think they are (will be) in /QOpenSys/perl.
+.PP
+If building natively on PASE, please do the build under the /QOpenSys
+directory, since Perl is happier when built on a case sensitive filesystem.
+.SS "Installing Perl in OS/400 PASE"
+.IX Subsection "Installing Perl in OS/400 PASE"
+If you are compiling on AIX, simply do a "make install" on the AIX box.
+Once the install finishes, tar up the /QOpenSys/perl directory.  Transfer
+the tarball to the OS/400 using FTP with the following commands:
+.PP
+.Vb 3
+\&  > binary
+\&  > site namefmt 1
+\&  > put perl.tar /QOpenSys
+.Ve
+.PP
+Once you have it on, simply bring up a PASE shell and extract the tarball.
+.PP
+If you are compiling in PASE, then "make install" is the only thing you
+will need to do.
+.PP
+The default path for perl binary is /QOpenSys/perl/bin/perl.  You'll
+want to symlink /QOpenSys/usr/bin/perl to this file so you don't have
+to modify your path.
+.SS "Using Perl in OS/400 PASE"
+.IX Subsection "Using Perl in OS/400 PASE"
+Perl in PASE may be used in the same manner as you would use Perl on AIX.
+.PP
+Scripts starting with #!/usr/bin/perl should work if you have
+/QOpenSys/usr/bin/perl symlinked to your perl binary.  This will not
+work if you've done a setuid/setgid or have environment variable
+PASE_EXEC_QOPENSYS="N".  If you have V5R1, you'll need to get the
+latest PTFs to have this feature.  Scripts starting with
+#!/QOpenSys/perl/bin/perl should always work.
+.SS "Known Problems"
+.IX Subsection "Known Problems"
+When compiling in PASE, there is no "oslevel" command.  Therefore,
+you may want to create a script called "oslevel" that echoes the
+level of AIX that your version of PASE runtime supports.  If you're
+unsure, consult your documentation or use "4.3.3.0".
+.PP
+If you have test cases that fail, check for the existence of spool files.
+The test case may be trying to use a syscall that is not implemented
+in PASE.  To avoid the SIGILL, try setting the PASE_SYSCALL_NOSIGILL
+environment variable or have a handler for the SIGILL.  If you can
+compile programs for PASE, run the config script and edit config.sh
+when it gives you the option.  If you want to remove \fBfchdir()\fR, which
+isn't implement in V5R1, simply change the line that says:
+.PP
+d_fchdir='define'
+.PP
+to
+.PP
+d_fchdir='undef'
+.PP
+and then compile Perl.  The places where \fBfchdir()\fR is used have
+alternatives for systems that do not have \fBfchdir()\fR available.
+.SS "Perl on ILE"
+.IX Subsection "Perl on ILE"
+There exists a port of Perl to the ILE environment.  This port, however,
+is based quite an old release of Perl, Perl 5.00502 (August 1998).
+(As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1
+has been out since April 2001.)  If you need to run Perl on ILE, though,
+you may need this older port: <http://www.cpan.org/ports/#os400>
+Note that any Perl release later than 5.00502 has not been ported to ILE.
+.PP
+If you need to use Perl in the ILE environment, you may want to consider
+using \fBQp2RunPase()\fR to call the PASE version of Perl.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Jarkko Hietaniemi <jhi@iki.fi>
+Bryan Logan <bryanlog@us.ibm.com>
+David Larson <larson1@us.ibm.com>
diff --git a/upstream/mageia-cauldron/man1/perlpacktut.1 b/upstream/mageia-cauldron/man1/perlpacktut.1
new file mode 100644
index 00000000..a271e879
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpacktut.1
@@ -0,0 +1,1413 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPACKTUT 1"
+.TH PERLPACKTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpacktut \- tutorial on "pack" and "unpack"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR are two functions for transforming data according
+to a user-defined template, between the guarded way Perl stores values
+and some well-defined representation as might be required in the 
+environment of a Perl program. Unfortunately, they're also two of 
+the most misunderstood and most often overlooked functions that Perl
+provides. This tutorial will demystify them for you.
+.SH "The Basic Principle"
+.IX Header "The Basic Principle"
+Most programming languages don't shelter the memory where variables are
+stored. In C, for instance, you can take the address of some variable,
+and the \f(CW\*(C`sizeof\*(C'\fR operator tells you how many bytes are allocated to
+the variable. Using the address and the size, you may access the storage
+to your heart's content.
+.PP
+In Perl, you just can't access memory at random, but the structural and
+representational conversion provided by \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR is an
+excellent alternative. The \f(CW\*(C`pack\*(C'\fR function converts values to a byte
+sequence containing representations according to a given specification,
+the so-called "template" argument. \f(CW\*(C`unpack\*(C'\fR is the reverse process,
+deriving some values from the contents of a string of bytes. (Be cautioned,
+however, that not all that has been packed together can be neatly unpacked \- 
+a very common experience as seasoned travellers are likely to confirm.)
+.PP
+Why, you may ask, would you need a chunk of memory containing some values
+in binary representation? One good reason is input and output accessing
+some file, a device, or a network connection, whereby this binary
+representation is either forced on you or will give you some benefit
+in processing. Another cause is passing data to some system call that
+is not available as a Perl function: \f(CW\*(C`syscall\*(C'\fR requires you to provide
+parameters stored in the way it happens in a C program. Even text processing 
+(as shown in the next section) may be simplified with judicious usage 
+of these two functions.
+.PP
+To see how (un)packing works, we'll start with a simple template
+code where the conversion is in low gear: between the contents of a byte
+sequence and a string of hexadecimal digits. Let's use \f(CW\*(C`unpack\*(C'\fR, since
+this is likely to remind you of a dump program, or some desperate last
+message unfortunate programs are wont to throw at you before they expire
+into the wild blue yonder. Assuming that the variable \f(CW$mem\fR holds a 
+sequence of bytes that we'd like to inspect without assuming anything 
+about its meaning, we can write
+.PP
+.Vb 2
+\&   my( $hex ) = unpack( \*(AqH*\*(Aq, $mem );
+\&   print "$hex\en";
+.Ve
+.PP
+whereupon we might see something like this, with each pair of hex digits
+corresponding to a byte:
+.PP
+.Vb 1
+\&   41204d414e204120504c414e20412043414e414c2050414e414d41
+.Ve
+.PP
+What was in this chunk of memory? Numbers, characters, or a mixture of
+both? Assuming that we're on a computer where ASCII (or some similar)
+encoding is used: hexadecimal values in the range \f(CW0x40\fR \- \f(CW0x5A\fR
+indicate an uppercase letter, and \f(CW0x20\fR encodes a space. So we might
+assume it is a piece of text, which some are able to read like a tabloid;
+but others will have to get hold of an ASCII table and relive that
+firstgrader feeling. Not caring too much about which way to read this,
+we note that \f(CW\*(C`unpack\*(C'\fR with the template code \f(CW\*(C`H\*(C'\fR converts the contents
+of a sequence of bytes into the customary hexadecimal notation. Since
+"a sequence of" is a pretty vague indication of quantity, \f(CW\*(C`H\*(C'\fR has been
+defined to convert just a single hexadecimal digit unless it is followed
+by a repeat count. An asterisk for the repeat count means to use whatever
+remains.
+.PP
+The inverse operation \- packing byte contents from a string of hexadecimal
+digits \- is just as easily written. For instance:
+.PP
+.Vb 2
+\&   my $s = pack( \*(AqH2\*(Aq x 10, 30..39 );
+\&   print "$s\en";
+.Ve
+.PP
+Since we feed a list of ten 2\-digit hexadecimal strings to \f(CW\*(C`pack\*(C'\fR, the
+pack template should contain ten pack codes. If this is run on a computer
+with ASCII character coding, it will print \f(CW0123456789\fR.
+.SH "Packing Text"
+.IX Header "Packing Text"
+Let's suppose you've got to read in a data file like this:
+.PP
+.Vb 4
+\&    Date      |Description                | Income|Expenditure
+\&    01/24/2001 Zed\*(Aqs Camel Emporium                    1147.99
+\&    01/28/2001 Flea spray                                24.99
+\&    01/29/2001 Camel rides to tourists      235.00
+.Ve
+.PP
+How do we do it? You might think first to use \f(CW\*(C`split\*(C'\fR; however, since
+\&\f(CW\*(C`split\*(C'\fR collapses blank fields, you'll never know whether a record was
+income or expenditure. Oops. Well, you could always use \f(CW\*(C`substr\*(C'\fR:
+.PP
+.Vb 7
+\&    while (<>) { 
+\&        my $date   = substr($_,  0, 11);
+\&        my $desc   = substr($_, 12, 27);
+\&        my $income = substr($_, 40,  7);
+\&        my $expend = substr($_, 52,  7);
+\&        ...
+\&    }
+.Ve
+.PP
+It's not really a barrel of laughs, is it? In fact, it's worse than it
+may seem; the eagle-eyed may notice that the first field should only be
+10 characters wide, and the error has propagated right through the other
+numbers \- which we've had to count by hand. So it's error-prone as well
+as horribly unfriendly.
+.PP
+Or maybe we could use regular expressions:
+.PP
+.Vb 5
+\&    while (<>) { 
+\&        my($date, $desc, $income, $expend) = 
+\&            m|(\ed\ed/\ed\ed/\ed{4}) (.{27}) (.{7})(.*)|;
+\&        ...
+\&    }
+.Ve
+.PP
+Urgh. Well, it's a bit better, but \- well, would you want to maintain
+that?
+.PP
+Hey, isn't Perl supposed to make this sort of thing easy? Well, it does,
+if you use the right tools. \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR are designed to help
+you out when dealing with fixed-width data like the above. Let's have a
+look at a solution with \f(CW\*(C`unpack\*(C'\fR:
+.PP
+.Vb 4
+\&    while (<>) { 
+\&        my($date, $desc, $income, $expend) = unpack("A10xA27xA7A*", $_);
+\&        ...
+\&    }
+.Ve
+.PP
+That looks a bit nicer; but we've got to take apart that weird template.
+Where did I pull that out of?
+.PP
+OK, let's have a look at some of our data again; in fact, we'll include
+the headers, and a handy ruler so we can keep track of where we are.
+.PP
+.Vb 5
+\&             1         2         3         4         5        
+\&    1234567890123456789012345678901234567890123456789012345678
+\&    Date      |Description                | Income|Expenditure
+\&    01/28/2001 Flea spray                                24.99
+\&    01/29/2001 Camel rides to tourists      235.00
+.Ve
+.PP
+From this, we can see that the date column stretches from column 1 to
+column 10 \- ten characters wide. The \f(CW\*(C`pack\*(C'\fR\-ese for "character" is
+\&\f(CW\*(C`A\*(C'\fR, and ten of them are \f(CW\*(C`A10\*(C'\fR. So if we just wanted to extract the
+dates, we could say this:
+.PP
+.Vb 1
+\&    my($date) = unpack("A10", $_);
+.Ve
+.PP
+OK, what's next? Between the date and the description is a blank column;
+we want to skip over that. The \f(CW\*(C`x\*(C'\fR template means "skip forward", so we
+want one of those. Next, we have another batch of characters, from 12 to
+38. That's 27 more characters, hence \f(CW\*(C`A27\*(C'\fR. (Don't make the fencepost
+error \- there are 27 characters between 12 and 38, not 26. Count 'em!)
+.PP
+Now we skip another character and pick up the next 7 characters:
+.PP
+.Vb 1
+\&    my($date,$description,$income) = unpack("A10xA27xA7", $_);
+.Ve
+.PP
+Now comes the clever bit. Lines in our ledger which are just income and
+not expenditure might end at column 46. Hence, we don't want to tell our
+\&\f(CW\*(C`unpack\*(C'\fR pattern that we \fBneed\fR to find another 12 characters; we'll
+just say "if there's anything left, take it". As you might guess from
+regular expressions, that's what the \f(CW\*(C`*\*(C'\fR means: "use everything
+remaining".
+.IP \(bu 3
+Be warned, though, that unlike regular expressions, if the \f(CW\*(C`unpack\*(C'\fR
+template doesn't match the incoming data, Perl will scream and die.
+.PP
+Hence, putting it all together:
+.PP
+.Vb 2
+\&    my ($date, $description, $income, $expend) =
+\&        unpack("A10xA27xA7xA*", $_);
+.Ve
+.PP
+Now, that's our data parsed. I suppose what we might want to do now is
+total up our income and expenditure, and add another line to the end of
+our ledger \- in the same format \- saying how much we've brought in and
+how much we've spent:
+.PP
+.Vb 6
+\&    while (<>) {
+\&        my ($date, $desc, $income, $expend) =
+\&            unpack("A10xA27xA7xA*", $_);
+\&        $tot_income += $income;
+\&        $tot_expend += $expend;
+\&    }
+\&
+\&    $tot_income = sprintf("%.2f", $tot_income); # Get them into 
+\&    $tot_expend = sprintf("%.2f", $tot_expend); # "financial" format
+\&
+\&    $date = POSIX::strftime("%m/%d/%Y", localtime); 
+\&
+\&    # OK, let\*(Aqs go:
+\&
+\&    print pack("A10xA27xA7xA*", $date, "Totals",
+\&        $tot_income, $tot_expend);
+.Ve
+.PP
+Oh, hmm. That didn't quite work. Let's see what happened:
+.PP
+.Vb 4
+\&    01/24/2001 Zed\*(Aqs Camel Emporium                     1147.99
+\&    01/28/2001 Flea spray                                 24.99
+\&    01/29/2001 Camel rides to tourists     1235.00
+\&    03/23/2001Totals                     1235.001172.98
+.Ve
+.PP
+OK, it's a start, but what happened to the spaces? We put \f(CW\*(C`x\*(C'\fR, didn't
+we? Shouldn't it skip forward? Let's look at what "pack" in perlfunc says:
+.PP
+.Vb 1
+\&    x   A null byte.
+.Ve
+.PP
+Urgh. No wonder. There's a big difference between "a null byte",
+character zero, and "a space", character 32. Perl's put something
+between the date and the description \- but unfortunately, we can't see
+it!
+.PP
+What we actually need to do is expand the width of the fields. The \f(CW\*(C`A\*(C'\fR
+format pads any non-existent characters with spaces, so we can use the
+additional spaces to line up our fields, like this:
+.PP
+.Vb 2
+\&    print pack("A11 A28 A8 A*", $date, "Totals",
+\&        $tot_income, $tot_expend);
+.Ve
+.PP
+(Note that you can put spaces in the template to make it more readable,
+but they don't translate to spaces in the output.) Here's what we got
+this time:
+.PP
+.Vb 4
+\&    01/24/2001 Zed\*(Aqs Camel Emporium                     1147.99
+\&    01/28/2001 Flea spray                                 24.99
+\&    01/29/2001 Camel rides to tourists     1235.00
+\&    03/23/2001 Totals                      1235.00 1172.98
+.Ve
+.PP
+That's a bit better, but we still have that last column which needs to
+be moved further over. There's an easy way to fix this up:
+unfortunately, we can't get \f(CW\*(C`pack\*(C'\fR to right-justify our fields, but we
+can get \f(CW\*(C`sprintf\*(C'\fR to do it:
+.PP
+.Vb 5
+\&    $tot_income = sprintf("%.2f", $tot_income); 
+\&    $tot_expend = sprintf("%12.2f", $tot_expend);
+\&    $date = POSIX::strftime("%m/%d/%Y", localtime); 
+\&    print pack("A11 A28 A8 A*", $date, "Totals",
+\&        $tot_income, $tot_expend);
+.Ve
+.PP
+This time we get the right answer:
+.PP
+.Vb 3
+\&    01/28/2001 Flea spray                                 24.99
+\&    01/29/2001 Camel rides to tourists     1235.00
+\&    03/23/2001 Totals                      1235.00      1172.98
+.Ve
+.PP
+So that's how we consume and produce fixed-width data. Let's recap what
+we've seen of \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR so far:
+.IP \(bu 3
+Use \f(CW\*(C`pack\*(C'\fR to go from several pieces of data to one fixed-width
+version; use \f(CW\*(C`unpack\*(C'\fR to turn a fixed-width-format string into several
+pieces of data.
+.IP \(bu 3
+The pack format \f(CW\*(C`A\*(C'\fR means "any character"; if you're \f(CW\*(C`pack\*(C'\fRing and
+you've run out of things to pack, \f(CW\*(C`pack\*(C'\fR will fill the rest up with
+spaces.
+.IP \(bu 3
+\&\f(CW\*(C`x\*(C'\fR means "skip a byte" when \f(CW\*(C`unpack\*(C'\fRing; when \f(CW\*(C`pack\*(C'\fRing, it means
+"introduce a null byte" \- that's probably not what you mean if you're
+dealing with plain text.
+.IP \(bu 3
+You can follow the formats with numbers to say how many characters
+should be affected by that format: \f(CW\*(C`A12\*(C'\fR means "take 12 characters";
+\&\f(CW\*(C`x6\*(C'\fR means "skip 6 bytes" or "character 0, 6 times".
+.IP \(bu 3
+Instead of a number, you can use \f(CW\*(C`*\*(C'\fR to mean "consume everything else
+left".
+.Sp
+\&\fBWarning\fR: when packing multiple pieces of data, \f(CW\*(C`*\*(C'\fR only means
+"consume all of the current piece of data". That's to say
+.Sp
+.Vb 1
+\&    pack("A*A*", $one, $two)
+.Ve
+.Sp
+packs all of \f(CW$one\fR into the first \f(CW\*(C`A*\*(C'\fR and then all of \f(CW$two\fR into
+the second. This is a general principle: each format character
+corresponds to one piece of data to be \f(CW\*(C`pack\*(C'\fRed.
+.SH "Packing Numbers"
+.IX Header "Packing Numbers"
+So much for textual data. Let's get onto the meaty stuff that \f(CW\*(C`pack\*(C'\fR
+and \f(CW\*(C`unpack\*(C'\fR are best at: handling binary formats for numbers. There is,
+of course, not just one binary format  \- life would be too simple \- but
+Perl will do all the finicky labor for you.
+.SS Integers
+.IX Subsection "Integers"
+Packing and unpacking numbers implies conversion to and from some
+\&\fIspecific\fR binary representation. Leaving floating point numbers
+aside for the moment, the salient properties of any such representation
+are:
+.IP \(bu 4
+the number of bytes used for storing the integer,
+.IP \(bu 4
+whether the contents are interpreted as a signed or unsigned number,
+.IP \(bu 4
+the byte ordering: whether the first byte is the least or most
+significant byte (or: little-endian or big-endian, respectively).
+.PP
+So, for instance, to pack 20302 to a signed 16 bit integer in your
+computer's representation you write
+.PP
+.Vb 1
+\&   my $ps = pack( \*(Aqs\*(Aq, 20302 );
+.Ve
+.PP
+Again, the result is a string, now containing 2 bytes. If you print 
+this string (which is, generally, not recommended) you might see
+\&\f(CW\*(C`ON\*(C'\fR or \f(CW\*(C`NO\*(C'\fR (depending on your system's byte ordering) \- or something
+entirely different if your computer doesn't use ASCII character encoding.
+Unpacking \f(CW$ps\fR with the same template returns the original integer value:
+.PP
+.Vb 1
+\&   my( $s ) = unpack( \*(Aqs\*(Aq, $ps );
+.Ve
+.PP
+This is true for all numeric template codes. But don't expect miracles:
+if the packed value exceeds the allotted byte capacity, high order bits
+are silently discarded, and unpack certainly won't be able to pull them
+back out of some magic hat. And, when you pack using a signed template
+code such as \f(CW\*(C`s\*(C'\fR, an excess value may result in the sign bit
+getting set, and unpacking this will smartly return a negative value.
+.PP
+16 bits won't get you too far with integers, but there is \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`L\*(C'\fR
+for signed and unsigned 32\-bit integers. And if this is not enough and
+your system supports 64 bit integers you can push the limits much closer
+to infinity with pack codes \f(CW\*(C`q\*(C'\fR and \f(CW\*(C`Q\*(C'\fR. A notable exception is provided
+by pack codes \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`I\*(C'\fR for signed and unsigned integers of the 
+"local custom" variety: Such an integer will take up as many bytes as
+a local C compiler returns for \f(CWsizeof(int)\fR, but it'll use \fIat least\fR
+32 bits.
+.PP
+Each of the integer pack codes \f(CW\*(C`sSlLqQ\*(C'\fR results in a fixed number of bytes,
+no matter where you execute your program. This may be useful for some 
+applications, but it does not provide for a portable way to pass data 
+structures between Perl and C programs (bound to happen when you call 
+XS extensions or the Perl function \f(CW\*(C`syscall\*(C'\fR), or when you read or
+write binary files. What you'll need in this case are template codes that
+depend on what your local C compiler compiles when you code \f(CW\*(C`short\*(C'\fR or
+\&\f(CW\*(C`unsigned long\*(C'\fR, for instance. These codes and their corresponding
+byte lengths are shown in the table below.  Since the C standard leaves
+much leeway with respect to the relative sizes of these data types, actual
+values may vary, and that's why the values are given as expressions in
+C and Perl. (If you'd like to use values from \f(CW%Config\fR in your program
+you have to import it with \f(CW\*(C`use Config\*(C'\fR.)
+.PP
+.Vb 5
+\&   signed unsigned  byte length in C   byte length in Perl       
+\&     s!     S!      sizeof(short)      $Config{shortsize}
+\&     i!     I!      sizeof(int)        $Config{intsize}
+\&     l!     L!      sizeof(long)       $Config{longsize}
+\&     q!     Q!      sizeof(long long)  $Config{longlongsize}
+.Ve
+.PP
+The \f(CW\*(C`i!\*(C'\fR and \f(CW\*(C`I!\*(C'\fR codes aren't different from \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`I\*(C'\fR; they are
+tolerated for completeness' sake.
+.SS "Unpacking a Stack Frame"
+.IX Subsection "Unpacking a Stack Frame"
+Requesting a particular byte ordering may be necessary when you work with
+binary data coming from some specific architecture whereas your program could
+run on a totally different system. As an example, assume you have 24 bytes
+containing a stack frame as it happens on an Intel 8086:
+.PP
+.Vb 11
+\&      +\-\-\-\-\-\-\-\-\-+        +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+\& TOS: |   IP    |  TOS+4:| FL | FH | FLAGS  TOS+14:|   SI    |
+\&      +\-\-\-\-\-\-\-\-\-+        +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+\&      |   CS    |        | AL | AH | AX            |   DI    |
+\&      +\-\-\-\-\-\-\-\-\-+        +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+\&                         | BL | BH | BX            |   BP    |
+\&                         +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+\&                         | CL | CH | CX            |   DS    |
+\&                         +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+\&                         | DL | DH | DX            |   ES    |
+\&                         +\-\-\-\-+\-\-\-\-+               +\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+First, we note that this time-honored 16\-bit CPU uses little-endian order,
+and that's why the low order byte is stored at the lower address. To
+unpack such a (unsigned) short we'll have to use code \f(CW\*(C`v\*(C'\fR. A repeat
+count unpacks all 12 shorts:
+.PP
+.Vb 2
+\&   my( $ip, $cs, $flags, $ax, $bx, $cx, $dx, $si, $di, $bp, $ds, $es ) =
+\&     unpack( \*(Aqv12\*(Aq, $frame );
+.Ve
+.PP
+Alternatively, we could have used \f(CW\*(C`C\*(C'\fR to unpack the individually
+accessible byte registers FL, FH, AL, AH, etc.:
+.PP
+.Vb 2
+\&   my( $fl, $fh, $al, $ah, $bl, $bh, $cl, $ch, $dl, $dh ) =
+\&     unpack( \*(AqC10\*(Aq, substr( $frame, 4, 10 ) );
+.Ve
+.PP
+It would be nice if we could do this in one fell swoop: unpack a short,
+back up a little, and then unpack 2 bytes. Since Perl \fIis\fR nice, it
+proffers the template code \f(CW\*(C`X\*(C'\fR to back up one byte. Putting this all
+together, we may now write:
+.PP
+.Vb 5
+\&   my( $ip, $cs,
+\&       $flags,$fl,$fh,
+\&       $ax,$al,$ah, $bx,$bl,$bh, $cx,$cl,$ch, $dx,$dl,$dh, 
+\&       $si, $di, $bp, $ds, $es ) =
+\&   unpack( \*(Aqv2\*(Aq . (\*(AqvXXCC\*(Aq x 5) . \*(Aqv5\*(Aq, $frame );
+.Ve
+.PP
+(The clumsy construction of the template can be avoided \- just read on!)
+.PP
+We've taken some pains to construct the template so that it matches
+the contents of our frame buffer. Otherwise we'd either get undefined values,
+or \f(CW\*(C`unpack\*(C'\fR could not unpack all. If \f(CW\*(C`pack\*(C'\fR runs out of items, it will
+supply null strings (which are coerced into zeroes whenever the pack code
+says so).
+.SS "How to Eat an Egg on a Net"
+.IX Subsection "How to Eat an Egg on a Net"
+The pack code for big-endian (high order byte at the lowest address) is
+\&\f(CW\*(C`n\*(C'\fR for 16 bit and \f(CW\*(C`N\*(C'\fR for 32 bit integers. You use these codes
+if you know that your data comes from a compliant architecture, but,
+surprisingly enough, you should also use these pack codes if you
+exchange binary data, across the network, with some system that you
+know next to nothing about. The simple reason is that this
+order has been chosen as the \fInetwork order\fR, and all standard-fearing
+programs ought to follow this convention. (This is, of course, a stern
+backing for one of the Lilliputian parties and may well influence the
+political development there.) So, if the protocol expects you to send
+a message by sending the length first, followed by just so many bytes,
+you could write:
+.PP
+.Vb 1
+\&   my $buf = pack( \*(AqN\*(Aq, length( $msg ) ) . $msg;
+.Ve
+.PP
+or even:
+.PP
+.Vb 1
+\&   my $buf = pack( \*(AqNA*\*(Aq, length( $msg ), $msg );
+.Ve
+.PP
+and pass \f(CW$buf\fR to your send routine. Some protocols demand that the
+count should include the length of the count itself: then just add 4
+to the data length. (But make sure to read "Lengths and Widths" before
+you really code this!)
+.SS "Byte-order modifiers"
+.IX Subsection "Byte-order modifiers"
+In the previous sections we've learned how to use \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`N\*(C'\fR, \f(CW\*(C`v\*(C'\fR and
+\&\f(CW\*(C`V\*(C'\fR to pack and unpack integers with big\- or little-endian byte-order.
+While this is nice, it's still rather limited because it leaves out all
+kinds of signed integers as well as 64\-bit integers. For example, if you
+wanted to unpack a sequence of signed big-endian 16\-bit integers in a
+platform-independent way, you would have to write:
+.PP
+.Vb 1
+\&   my @data = unpack \*(Aqs*\*(Aq, pack \*(AqS*\*(Aq, unpack \*(Aqn*\*(Aq, $buf;
+.Ve
+.PP
+This is ugly. As of Perl 5.9.2, there's a much nicer way to express your
+desire for a certain byte-order: the \f(CW\*(C`>\*(C'\fR and \f(CW\*(C`<\*(C'\fR modifiers.
+\&\f(CW\*(C`>\*(C'\fR is the big-endian modifier, while \f(CW\*(C`<\*(C'\fR is the little-endian
+modifier. Using them, we could rewrite the above code as:
+.PP
+.Vb 1
+\&   my @data = unpack \*(Aqs>*\*(Aq, $buf;
+.Ve
+.PP
+As you can see, the "big end" of the arrow touches the \f(CW\*(C`s\*(C'\fR, which is a
+nice way to remember that \f(CW\*(C`>\*(C'\fR is the big-endian modifier. The same
+obviously works for \f(CW\*(C`<\*(C'\fR, where the "little end" touches the code.
+.PP
+You will probably find these modifiers even more useful if you have
+to deal with big\- or little-endian C structures. Be sure to read
+"Packing and Unpacking C Structures" for more on that.
+.SS "Floating point Numbers"
+.IX Subsection "Floating point Numbers"
+For packing floating point numbers you have the choice between the
+pack codes \f(CW\*(C`f\*(C'\fR, \f(CW\*(C`d\*(C'\fR, \f(CW\*(C`F\*(C'\fR and \f(CW\*(C`D\*(C'\fR. \f(CW\*(C`f\*(C'\fR and \f(CW\*(C`d\*(C'\fR pack into (or unpack
+from) single-precision or double-precision representation as it is provided
+by your system. If your systems supports it, \f(CW\*(C`D\*(C'\fR can be used to pack and
+unpack (\f(CW\*(C`long double\*(C'\fR) values, which can offer even more resolution
+than \f(CW\*(C`f\*(C'\fR or \f(CW\*(C`d\*(C'\fR.  \fBNote that there are different long double formats.\fR
+.PP
+\&\f(CW\*(C`F\*(C'\fR packs an \f(CW\*(C`NV\*(C'\fR, which is the floating point type used by Perl
+internally.
+.PP
+There is no such thing as a network representation for reals, so if
+you want to send your real numbers across computer boundaries, you'd
+better stick to text representation, possibly using the hexadecimal
+float format (avoiding the decimal conversion loss), unless you're
+absolutely sure what's on the other end of the line. For the even more
+adventuresome, you can use the byte-order modifiers from the previous
+section also on floating point codes.
+.SH "Exotic Templates"
+.IX Header "Exotic Templates"
+.SS "Bit Strings"
+.IX Subsection "Bit Strings"
+Bits are the atoms in the memory world. Access to individual bits may
+have to be used either as a last resort or because it is the most
+convenient way to handle your data. Bit string (un)packing converts
+between strings containing a series of \f(CW0\fR and \f(CW1\fR characters and
+a sequence of bytes each containing a group of 8 bits. This is almost
+as simple as it sounds, except that there are two ways the contents of
+a byte may be written as a bit string. Let's have a look at an annotated
+byte:
+.PP
+.Vb 5
+\&     7 6 5 4 3 2 1 0
+\&   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\&   | 1 0 0 0 1 1 0 0 |
+\&   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\&    MSB           LSB
+.Ve
+.PP
+It's egg-eating all over again: Some think that as a bit string this should
+be written "10001100" i.e. beginning with the most significant bit, others
+insist on "00110001". Well, Perl isn't biased, so that's why we have two bit
+string codes:
+.PP
+.Vb 2
+\&   $byte = pack( \*(AqB8\*(Aq, \*(Aq10001100\*(Aq ); # start with MSB
+\&   $byte = pack( \*(Aqb8\*(Aq, \*(Aq00110001\*(Aq ); # start with LSB
+.Ve
+.PP
+It is not possible to pack or unpack bit fields \- just integral bytes.
+\&\f(CW\*(C`pack\*(C'\fR always starts at the next byte boundary and "rounds up" to the
+next multiple of 8 by adding zero bits as required. (If you do want bit
+fields, there is "vec" in perlfunc. Or you could implement bit field 
+handling at the character string level, using split, substr, and
+concatenation on unpacked bit strings.)
+.PP
+To illustrate unpacking for bit strings, we'll decompose a simple
+status register (a "\-" stands for a "reserved" bit):
+.PP
+.Vb 4
+\&   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\&   | S Z \- A \- P \- C | \- \- \- \- O D I T |
+\&   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\&    MSB           LSB MSB           LSB
+.Ve
+.PP
+Converting these two bytes to a string can be done with the unpack 
+template \f(CW\*(Aqb16\*(Aq\fR. To obtain the individual bit values from the bit
+string we use \f(CW\*(C`split\*(C'\fR with the "empty" separator pattern which dissects
+into individual characters. Bit values from the "reserved" positions are
+simply assigned to \f(CW\*(C`undef\*(C'\fR, a convenient notation for "I don't care where
+this goes".
+.PP
+.Vb 3
+\&   ($carry, undef, $parity, undef, $auxcarry, undef, $zero, $sign,
+\&    $trace, $interrupt, $direction, $overflow) =
+\&      split( //, unpack( \*(Aqb16\*(Aq, $status ) );
+.Ve
+.PP
+We could have used an unpack template \f(CW\*(Aqb12\*(Aq\fR just as well, since the
+last 4 bits can be ignored anyway.
+.SS Uuencoding
+.IX Subsection "Uuencoding"
+Another odd-man-out in the template alphabet is \f(CW\*(C`u\*(C'\fR, which packs a
+"uuencoded string". ("uu" is short for Unix-to-Unix.) Chances are that
+you won't ever need this encoding technique which was invented to overcome
+the shortcomings of old-fashioned transmission mediums that do not support
+other than simple ASCII data. The essential recipe is simple: Take three 
+bytes, or 24 bits. Split them into 4 six-packs, adding a space (0x20) to 
+each. Repeat until all of the data is blended. Fold groups of 4 bytes into 
+lines no longer than 60 and garnish them in front with the original byte count 
+(incremented by 0x20) and a \f(CW"\en"\fR at the end. \- The \f(CW\*(C`pack\*(C'\fR chef will
+prepare this for you, a la minute, when you select pack code \f(CW\*(C`u\*(C'\fR on the menu:
+.PP
+.Vb 1
+\&   my $uubuf = pack( \*(Aqu\*(Aq, $bindat );
+.Ve
+.PP
+A repeat count after \f(CW\*(C`u\*(C'\fR sets the number of bytes to put into an
+uuencoded line, which is the maximum of 45 by default, but could be
+set to some (smaller) integer multiple of three. \f(CW\*(C`unpack\*(C'\fR simply ignores
+the repeat count.
+.SS "Doing Sums"
+.IX Subsection "Doing Sums"
+An even stranger template code is \f(CW\*(C`%\*(C'\fR<\fInumber\fR>. First, because 
+it's used as a prefix to some other template code. Second, because it
+cannot be used in \f(CW\*(C`pack\*(C'\fR at all, and third, in \f(CW\*(C`unpack\*(C'\fR, doesn't return the
+data as defined by the template code it precedes. Instead it'll give you an
+integer of \fInumber\fR bits that is computed from the data value by 
+doing sums. For numeric unpack codes, no big feat is achieved:
+.PP
+.Vb 2
+\&    my $buf = pack( \*(Aqiii\*(Aq, 100, 20, 3 );
+\&    print unpack( \*(Aq%32i3\*(Aq, $buf ), "\en";  # prints 123
+.Ve
+.PP
+For string values, \f(CW\*(C`%\*(C'\fR returns the sum of the byte values saving
+you the trouble of a sum loop with \f(CW\*(C`substr\*(C'\fR and \f(CW\*(C`ord\*(C'\fR:
+.PP
+.Vb 1
+\&    print unpack( \*(Aq%32A*\*(Aq, "\ex01\ex10" ), "\en";  # prints 17
+.Ve
+.PP
+Although the \f(CW\*(C`%\*(C'\fR code is documented as returning a "checksum":
+don't put your trust in such values! Even when applied to a small number
+of bytes, they won't guarantee a noticeable Hamming distance.
+.PP
+In connection with \f(CW\*(C`b\*(C'\fR or \f(CW\*(C`B\*(C'\fR, \f(CW\*(C`%\*(C'\fR simply adds bits, and this can be put
+to good use to count set bits efficiently:
+.PP
+.Vb 1
+\&    my $bitcount = unpack( \*(Aq%32b*\*(Aq, $mask );
+.Ve
+.PP
+And an even parity bit can be determined like this:
+.PP
+.Vb 1
+\&    my $evenparity = unpack( \*(Aq%1b*\*(Aq, $mask );
+.Ve
+.SS Unicode
+.IX Subsection "Unicode"
+Unicode is a character set that can represent most characters in most of
+the world's languages, providing room for over one million different
+characters. Unicode 3.1 specifies 94,140 characters: The Basic Latin
+characters are assigned to the numbers 0 \- 127. The Latin\-1 Supplement with
+characters that are used in several European languages is in the next
+range, up to 255. After some more Latin extensions we find the character
+sets from languages using non-Roman alphabets, interspersed with a
+variety of symbol sets such as currency symbols, Zapf Dingbats or Braille.
+(You might want to visit <https://www.unicode.org/> for a look at some of
+them \- my personal favourites are Telugu and Kannada.)
+.PP
+The Unicode character sets associates characters with integers. Encoding
+these numbers in an equal number of bytes would more than double the
+requirements for storing texts written in Latin alphabets.
+The UTF\-8 encoding avoids this by storing the most common (from a western
+point of view) characters in a single byte while encoding the rarer
+ones in three or more bytes.
+.PP
+Perl uses UTF\-8, internally, for most Unicode strings.
+.PP
+So what has this got to do with \f(CW\*(C`pack\*(C'\fR? Well, if you want to compose a
+Unicode string (that is internally encoded as UTF\-8), you can do so by
+using template code \f(CW\*(C`U\*(C'\fR. As an example, let's produce the Euro currency
+symbol (code number 0x20AC):
+.PP
+.Vb 2
+\&   $UTF8{Euro} = pack( \*(AqU\*(Aq, 0x20AC );
+\&   # Equivalent to: $UTF8{Euro} = "\ex{20ac}";
+.Ve
+.PP
+Inspecting \f(CW$UTF8{Euro}\fR shows that it contains 3 bytes:
+"\exe2\ex82\exac". However, it contains only 1 character, number 0x20AC.
+The round trip can be completed with \f(CW\*(C`unpack\*(C'\fR:
+.PP
+.Vb 1
+\&   $Unicode{Euro} = unpack( \*(AqU\*(Aq, $UTF8{Euro} );
+.Ve
+.PP
+Unpacking using the \f(CW\*(C`U\*(C'\fR template code also works on UTF\-8 encoded byte
+strings.
+.PP
+Usually you'll want to pack or unpack UTF\-8 strings:
+.PP
+.Vb 3
+\&   # pack and unpack the Hebrew alphabet
+\&   my $alefbet = pack( \*(AqU*\*(Aq, 0x05d0..0x05ea );
+\&   my @hebrew = unpack( \*(AqU*\*(Aq, $utf );
+.Ve
+.PP
+Please note: in the general case, you're better off using
+\&\f(CW\*(C`Encode::decode(\*(AqUTF\-8\*(Aq, $utf)\*(C'\fR to decode a UTF\-8
+encoded byte string to a Perl Unicode string, and
+\&\f(CW\*(C`Encode::encode(\*(AqUTF\-8\*(Aq, $str)\*(C'\fR to encode a Perl Unicode
+string to UTF\-8 bytes. These functions provide means of handling invalid byte
+sequences and generally have a friendlier interface.
+.SS "Another Portable Binary Encoding"
+.IX Subsection "Another Portable Binary Encoding"
+The pack code \f(CW\*(C`w\*(C'\fR has been added to support a portable binary data
+encoding scheme that goes way beyond simple integers. (Details can
+be found at <https://github.com/mworks\-project/mw_scarab/blob/master/Scarab\-0.1.00d19/doc/binary\-serialization.txt>,
+the Scarab project.)  A BER (Binary Encoded
+Representation) compressed unsigned integer stores base 128
+digits, most significant digit first, with as few digits as possible.
+Bit eight (the high bit) is set on each byte except the last. There
+is no size limit to BER encoding, but Perl won't go to extremes.
+.PP
+.Vb 1
+\&   my $berbuf = pack( \*(Aqw*\*(Aq, 1, 128, 128+1, 128*128+127 );
+.Ve
+.PP
+A hex dump of \f(CW$berbuf\fR, with spaces inserted at the right places,
+shows 01 8100 8101 81807F. Since the last byte is always less than
+128, \f(CW\*(C`unpack\*(C'\fR knows where to stop.
+.SH "Template Grouping"
+.IX Header "Template Grouping"
+Prior to Perl 5.8, repetitions of templates had to be made by
+\&\f(CW\*(C`x\*(C'\fR\-multiplication of template strings. Now there is a better way as
+we may use the pack codes \f(CW\*(C`(\*(C'\fR and \f(CW\*(C`)\*(C'\fR combined with a repeat count.
+The \f(CW\*(C`unpack\*(C'\fR template from the Stack Frame example can simply
+be written like this:
+.PP
+.Vb 1
+\&   unpack( \*(Aqv2 (vXXCC)5 v5\*(Aq, $frame )
+.Ve
+.PP
+Let's explore this feature a little more. We'll begin with the equivalent of
+.PP
+.Vb 1
+\&   join( \*(Aq\*(Aq, map( substr( $_, 0, 1 ), @str ) )
+.Ve
+.PP
+which returns a string consisting of the first character from each string.
+Using pack, we can write
+.PP
+.Vb 1
+\&   pack( \*(Aq(A)\*(Aq.@str, @str )
+.Ve
+.PP
+or, because a repeat count \f(CW\*(C`*\*(C'\fR means "repeat as often as required",
+simply
+.PP
+.Vb 1
+\&   pack( \*(Aq(A)*\*(Aq, @str )
+.Ve
+.PP
+(Note that the template \f(CW\*(C`A*\*(C'\fR would only have packed \f(CW$str[0]\fR in full
+length.)
+.PP
+To pack dates stored as triplets ( day, month, year ) in an array \f(CW@dates\fR
+into a sequence of byte, byte, short integer we can write
+.PP
+.Vb 1
+\&   $pd = pack( \*(Aq(CCS)*\*(Aq, map( @$_, @dates ) );
+.Ve
+.PP
+To swap pairs of characters in a string (with even length) one could use
+several techniques. First, let's use \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`X\*(C'\fR to skip forward and back:
+.PP
+.Vb 1
+\&   $s = pack( \*(Aq(A)*\*(Aq, unpack( \*(Aq(xAXXAx)*\*(Aq, $s ) );
+.Ve
+.PP
+We can also use \f(CW\*(C`@\*(C'\fR to jump to an offset, with 0 being the position where
+we were when the last \f(CW\*(C`(\*(C'\fR was encountered:
+.PP
+.Vb 1
+\&   $s = pack( \*(Aq(A)*\*(Aq, unpack( \*(Aq(@1A @0A @2)*\*(Aq, $s ) );
+.Ve
+.PP
+Finally, there is also an entirely different approach by unpacking big
+endian shorts and packing them in the reverse byte order:
+.PP
+.Vb 1
+\&   $s = pack( \*(Aq(v)*\*(Aq, unpack( \*(Aq(n)*\*(Aq, $s );
+.Ve
+.SH "Lengths and Widths"
+.IX Header "Lengths and Widths"
+.SS "String Lengths"
+.IX Subsection "String Lengths"
+In the previous section we've seen a network message that was constructed
+by prefixing the binary message length to the actual message. You'll find
+that packing a length followed by so many bytes of data is a 
+frequently used recipe since appending a null byte won't work
+if a null byte may be part of the data. Here is an example where both
+techniques are used: after two null terminated strings with source and
+destination address, a Short Message (to a mobile phone) is sent after
+a length byte:
+.PP
+.Vb 1
+\&   my $msg = pack( \*(AqZ*Z*CA*\*(Aq, $src, $dst, length( $sm ), $sm );
+.Ve
+.PP
+Unpacking this message can be done with the same template:
+.PP
+.Vb 1
+\&   ( $src, $dst, $len, $sm ) = unpack( \*(AqZ*Z*CA*\*(Aq, $msg );
+.Ve
+.PP
+There's a subtle trap lurking in the offing: Adding another field after
+the Short Message (in variable \f(CW$sm\fR) is all right when packing, but this
+cannot be unpacked naively:
+.PP
+.Vb 2
+\&   # pack a message
+\&   my $msg = pack( \*(AqZ*Z*CA*C\*(Aq, $src, $dst, length( $sm ), $sm, $prio );
+\&
+\&   # unpack fails \- $prio remains undefined!
+\&   ( $src, $dst, $len, $sm, $prio ) = unpack( \*(AqZ*Z*CA*C\*(Aq, $msg );
+.Ve
+.PP
+The pack code \f(CW\*(C`A*\*(C'\fR gobbles up all remaining bytes, and \f(CW$prio\fR remains
+undefined! Before we let disappointment dampen the morale: Perl's got
+the trump card to make this trick too, just a little further up the sleeve.
+Watch this:
+.PP
+.Vb 2
+\&   # pack a message: ASCIIZ, ASCIIZ, length/string, byte
+\&   my $msg = pack( \*(AqZ* Z* C/A* C\*(Aq, $src, $dst, $sm, $prio );
+\&
+\&   # unpack
+\&   ( $src, $dst, $sm, $prio ) = unpack( \*(AqZ* Z* C/A* C\*(Aq, $msg );
+.Ve
+.PP
+Combining two pack codes with a slash (\f(CW\*(C`/\*(C'\fR) associates them with a single
+value from the argument list. In \f(CW\*(C`pack\*(C'\fR, the length of the argument is
+taken and packed according to the first code while the argument itself
+is added after being converted with the template code after the slash.
+This saves us the trouble of inserting the \f(CW\*(C`length\*(C'\fR call, but it is 
+in \f(CW\*(C`unpack\*(C'\fR where we really score: The value of the length byte marks the
+end of the string to be taken from the buffer. Since this combination
+doesn't make sense except when the second pack code isn't \f(CW\*(C`a*\*(C'\fR, \f(CW\*(C`A*\*(C'\fR
+or \f(CW\*(C`Z*\*(C'\fR, Perl won't let you.
+.PP
+The pack code preceding \f(CW\*(C`/\*(C'\fR may be anything that's fit to represent a
+number: All the numeric binary pack codes, and even text codes such as
+\&\f(CW\*(C`A4\*(C'\fR or \f(CW\*(C`Z*\*(C'\fR:
+.PP
+.Vb 4
+\&   # pack/unpack a string preceded by its length in ASCII
+\&   my $buf = pack( \*(AqA4/A*\*(Aq, "Humpty\-Dumpty" );
+\&   # unpack $buf: \*(Aq13  Humpty\-Dumpty\*(Aq
+\&   my $txt = unpack( \*(AqA4/A*\*(Aq, $buf );
+.Ve
+.PP
+\&\f(CW\*(C`/\*(C'\fR is not implemented in Perls before 5.6, so if your code is required to
+work on ancient Perls you'll need to \f(CW\*(C`unpack( \*(AqZ* Z* C\*(Aq)\*(C'\fR to get the length,
+then use it to make a new unpack string. For example
+.PP
+.Vb 3
+\&   # pack a message: ASCIIZ, ASCIIZ, length, string, byte
+\&   # (5.005 compatible)
+\&   my $msg = pack( \*(AqZ* Z* C A* C\*(Aq, $src, $dst, length $sm, $sm, $prio );
+\&
+\&   # unpack
+\&   ( undef, undef, $len) = unpack( \*(AqZ* Z* C\*(Aq, $msg );
+\&   ($src, $dst, $sm, $prio) = unpack ( "Z* Z* x A$len C", $msg );
+.Ve
+.PP
+But that second \f(CW\*(C`unpack\*(C'\fR is rushing ahead. It isn't using a simple literal
+string for the template. So maybe we should introduce...
+.SS "Dynamic Templates"
+.IX Subsection "Dynamic Templates"
+So far, we've seen literals used as templates. If the list of pack
+items doesn't have fixed length, an expression constructing the
+template is required (whenever, for some reason, \f(CW\*(C`()*\*(C'\fR cannot be used).
+Here's an example: To store named string values in a way that can be
+conveniently parsed by a C program, we create a sequence of names and
+null terminated ASCII strings, with \f(CW\*(C`=\*(C'\fR between the name and the value,
+followed by an additional delimiting null byte. Here's how:
+.PP
+.Vb 2
+\&   my $env = pack( \*(Aq(A*A*Z*)\*(Aq . keys( %Env ) . \*(AqC\*(Aq,
+\&                   map( { ( $_, \*(Aq=\*(Aq, $Env{$_} ) } keys( %Env ) ), 0 );
+.Ve
+.PP
+Let's examine the cogs of this byte mill, one by one. There's the \f(CW\*(C`map\*(C'\fR
+call, creating the items we intend to stuff into the \f(CW$env\fR buffer:
+to each key (in \f(CW$_\fR) it adds the \f(CW\*(C`=\*(C'\fR separator and the hash entry value.
+Each triplet is packed with the template code sequence \f(CW\*(C`A*A*Z*\*(C'\fR that
+is repeated according to the number of keys. (Yes, that's what the \f(CW\*(C`keys\*(C'\fR
+function returns in scalar context.) To get the very last null byte,
+we add a \f(CW0\fR at the end of the \f(CW\*(C`pack\*(C'\fR list, to be packed with \f(CW\*(C`C\*(C'\fR.
+(Attentive readers may have noticed that we could have omitted the 0.)
+.PP
+For the reverse operation, we'll have to determine the number of items
+in the buffer before we can let \f(CW\*(C`unpack\*(C'\fR rip it apart:
+.PP
+.Vb 2
+\&   my $n = $env =~ tr/\e0// \- 1;
+\&   my %env = map( split( /=/, $_ ), unpack( "(Z*)$n", $env ) );
+.Ve
+.PP
+The \f(CW\*(C`tr\*(C'\fR counts the null bytes. The \f(CW\*(C`unpack\*(C'\fR call returns a list of
+name-value pairs each of which is taken apart in the \f(CW\*(C`map\*(C'\fR block.
+.SS "Counting Repetitions"
+.IX Subsection "Counting Repetitions"
+Rather than storing a sentinel at the end of a data item (or a list of items),
+we could precede the data with a count. Again, we pack keys and values of
+a hash, preceding each with an unsigned short length count, and up front
+we store the number of pairs:
+.PP
+.Vb 1
+\&   my $env = pack( \*(AqS(S/A* S/A*)*\*(Aq, scalar keys( %Env ), %Env );
+.Ve
+.PP
+This simplifies the reverse operation as the number of repetitions can be
+unpacked with the \f(CW\*(C`/\*(C'\fR code:
+.PP
+.Vb 1
+\&   my %env = unpack( \*(AqS/(S/A* S/A*)\*(Aq, $env );
+.Ve
+.PP
+Note that this is one of the rare cases where you cannot use the same
+template for \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR because \f(CW\*(C`pack\*(C'\fR can't determine
+a repeat count for a \f(CW\*(C`()\*(C'\fR\-group.
+.SS "Intel HEX"
+.IX Subsection "Intel HEX"
+Intel HEX is a file format for representing binary data, mostly for
+programming various chips, as a text file. (See
+<https://en.wikipedia.org/wiki/.hex> for a detailed description, and
+<https://en.wikipedia.org/wiki/SREC_(file_format)> for the Motorola
+S\-record format, which can be unravelled using the same technique.)
+Each line begins with a colon (':') and is followed by a sequence of
+hexadecimal characters, specifying a byte count \fIn\fR (8 bit),
+an address (16 bit, big endian), a record type (8 bit), \fIn\fR data bytes
+and a checksum (8 bit) computed as the least significant byte of the two's
+complement sum of the preceding bytes. Example: \f(CW\*(C`:0300300002337A1E\*(C'\fR.
+.PP
+The first step of processing such a line is the conversion, to binary,
+of the hexadecimal data, to obtain the four fields, while checking the
+checksum. No surprise here: we'll start with a simple \f(CW\*(C`pack\*(C'\fR call to 
+convert everything to binary:
+.PP
+.Vb 1
+\&   my $binrec = pack( \*(AqH*\*(Aq, substr( $hexrec, 1 ) );
+.Ve
+.PP
+The resulting byte sequence is most convenient for checking the checksum.
+Don't slow your program down with a for loop adding the \f(CW\*(C`ord\*(C'\fR values
+of this string's bytes \- the \f(CW\*(C`unpack\*(C'\fR code \f(CW\*(C`%\*(C'\fR is the thing to use
+for computing the 8\-bit sum of all bytes, which must be equal to zero:
+.PP
+.Vb 1
+\&   die unless unpack( "%8C*", $binrec ) == 0;
+.Ve
+.PP
+Finally, let's get those four fields. By now, you shouldn't have any
+problems with the first three fields \- but how can we use the byte count
+of the data in the first field as a length for the data field? Here
+the codes \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`X\*(C'\fR come to the rescue, as they permit jumping
+back and forth in the string to unpack.
+.PP
+.Vb 1
+\&   my( $addr, $type, $data ) = unpack( "x n C X4 C x3 /a", $bin );
+.Ve
+.PP
+Code \f(CW\*(C`x\*(C'\fR skips a byte, since we don't need the count yet. Code \f(CW\*(C`n\*(C'\fR takes
+care of the 16\-bit big-endian integer address, and \f(CW\*(C`C\*(C'\fR unpacks the
+record type. Being at offset 4, where the data begins, we need the count.
+\&\f(CW\*(C`X4\*(C'\fR brings us back to square one, which is the byte at offset 0.
+Now we pick up the count, and zoom forth to offset 4, where we are
+now fully furnished to extract the exact number of data bytes, leaving
+the trailing checksum byte alone.
+.SH "Packing and Unpacking C Structures"
+.IX Header "Packing and Unpacking C Structures"
+In previous sections we have seen how to pack numbers and character
+strings. If it were not for a couple of snags we could conclude this
+section right away with the terse remark that C structures don't
+contain anything else, and therefore you already know all there is to it.
+Sorry, no: read on, please.
+.PP
+If you have to deal with a lot of C structures, and don't want to
+hack all your template strings manually, you'll probably want to have
+a look at the CPAN module \f(CW\*(C`Convert::Binary::C\*(C'\fR. Not only can it parse
+your C source directly, but it also has built-in support for all the
+odds and ends described further on in this section.
+.SS "The Alignment Pit"
+.IX Subsection "The Alignment Pit"
+In the consideration of speed against memory requirements the balance
+has been tilted in favor of faster execution. This has influenced the
+way C compilers allocate memory for structures: On architectures
+where a 16\-bit or 32\-bit operand can be moved faster between places in
+memory, or to or from a CPU register, if it is aligned at an even or 
+multiple-of-four or even at a multiple-of eight address, a C compiler
+will give you this speed benefit by stuffing extra bytes into structures.
+If you don't cross the C shoreline this is not likely to cause you any
+grief (although you should care when you design large data structures,
+or you want your code to be portable between architectures (you do want
+that, don't you?)).
+.PP
+To see how this affects \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR, we'll compare these two
+C structures:
+.PP
+.Vb 6
+\&   typedef struct {
+\&     char     c1;
+\&     short    s;
+\&     char     c2;
+\&     long     l;
+\&   } gappy_t;
+\&
+\&   typedef struct {
+\&     long     l;
+\&     short    s;
+\&     char     c1;
+\&     char     c2;
+\&   } dense_t;
+.Ve
+.PP
+Typically, a C compiler allocates 12 bytes to a \f(CW\*(C`gappy_t\*(C'\fR variable, but
+requires only 8 bytes for a \f(CW\*(C`dense_t\*(C'\fR. After investigating this further,
+we can draw memory maps, showing where the extra 4 bytes are hidden:
+.PP
+.Vb 5
+\&   0           +4          +8          +12
+\&   +\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+
+\&   |c1|xx|  s  |c2|xx|xx|xx|     l     |    xx = fill byte
+\&   +\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+
+\&   gappy_t
+\&
+\&   0           +4          +8
+\&   +\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+
+\&   |     l     |  h  |c1|c2|
+\&   +\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+\-\-+
+\&   dense_t
+.Ve
+.PP
+And that's where the first quirk strikes: \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR
+templates have to be stuffed with \f(CW\*(C`x\*(C'\fR codes to get those extra fill bytes.
+.PP
+The natural question: "Why can't Perl compensate for the gaps?" warrants
+an answer. One good reason is that C compilers might provide (non-ANSI)
+extensions permitting all sorts of fancy control over the way structures
+are aligned, even at the level of an individual structure field. And, if
+this were not enough, there is an insidious thing called \f(CW\*(C`union\*(C'\fR where
+the amount of fill bytes cannot be derived from the alignment of the next
+item alone.
+.PP
+OK, so let's bite the bullet. Here's one way to get the alignment right
+by inserting template codes \f(CW\*(C`x\*(C'\fR, which don't take a corresponding item 
+from the list:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aqcxs cxxx l!\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+Note the \f(CW\*(C`!\*(C'\fR after \f(CW\*(C`l\*(C'\fR: We want to make sure that we pack a long
+integer as it is compiled by our C compiler. And even now, it will only
+work for the platforms where the compiler aligns things as above.
+And somebody somewhere has a platform where it doesn't.
+[Probably a Cray, where \f(CW\*(C`short\*(C'\fRs, \f(CW\*(C`int\*(C'\fRs and \f(CW\*(C`long\*(C'\fRs are all 8 bytes. :\-)]
+.PP
+Counting bytes and watching alignments in lengthy structures is bound to 
+be a drag. Isn't there a way we can create the template with a simple
+program? Here's a C program that does the trick:
+.PP
+.Vb 2
+\&   #include <stdio.h>
+\&   #include <stddef.h>
+\&
+\&   typedef struct {
+\&     char     fc1;
+\&     short    fs;
+\&     char     fc2;
+\&     long     fl;
+\&   } gappy_t;
+\&
+\&   #define Pt(struct,field,tchar) \e
+\&     printf( "@%d%s ", offsetof(struct,field), # tchar );
+\&
+\&   int main() {
+\&     Pt( gappy_t, fc1, c  );
+\&     Pt( gappy_t, fs,  s! );
+\&     Pt( gappy_t, fc2, c  );
+\&     Pt( gappy_t, fl,  l! );
+\&     printf( "\en" );
+\&   }
+.Ve
+.PP
+The output line can be used as a template in a \f(CW\*(C`pack\*(C'\fR or \f(CW\*(C`unpack\*(C'\fR call:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aq@0c @2s! @4c @8l!\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+Gee, yet another template code \- as if we hadn't plenty. But 
+\&\f(CW\*(C`@\*(C'\fR saves our day by enabling us to specify the offset from the beginning
+of the pack buffer to the next item: This is just the value
+the \f(CW\*(C`offsetof\*(C'\fR macro (defined in \f(CW\*(C`<stddef.h>\*(C'\fR) returns when
+given a \f(CW\*(C`struct\*(C'\fR type and one of its field names ("member-designator" in 
+C standardese).
+.PP
+Neither using offsets nor adding \f(CW\*(C`x\*(C'\fR's to bridge the gaps is satisfactory.
+(Just imagine what happens if the structure changes.) What we really need
+is a way of saying "skip as many bytes as required to the next multiple of N".
+In fluent templates, you say this with \f(CW\*(C`x!N\*(C'\fR where N is replaced by the
+appropriate value. Here's the next version of our struct packaging:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aqc x!2 s c x!4 l!\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+That's certainly better, but we still have to know how long all the
+integers are, and portability is far away. Rather than \f(CW2\fR,
+for instance, we want to say "however long a short is". But this can be
+done by enclosing the appropriate pack code in brackets: \f(CW\*(C`[s]\*(C'\fR. So, here's
+the very best we can do:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aqc x![s] s c x![l!] l!\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.SS "Dealing with Endian-ness"
+.IX Subsection "Dealing with Endian-ness"
+Now, imagine that we want to pack the data for a machine with a
+different byte-order. First, we'll have to figure out how big the data
+types on the target machine really are. Let's assume that the longs are
+32 bits wide and the shorts are 16 bits wide. You can then rewrite the
+template as:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aqc x![s] s c x![l] l\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+If the target machine is little-endian, we could write:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aqc x![s] s< c x![l] l<\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+This forces the short and the long members to be little-endian, and is
+just fine if you don't have too many struct members. But we could also
+use the byte-order modifier on a group and write the following:
+.PP
+.Vb 1
+\&  my $gappy = pack( \*(Aq( c x![s] s c x![l] l )<\*(Aq, $c1, $s, $c2, $l );
+.Ve
+.PP
+This is not as short as before, but it makes it more obvious that we
+intend to have little-endian byte-order for a whole group, not only
+for individual template codes. It can also be more readable and easier
+to maintain.
+.SS "Alignment, Take 2"
+.IX Subsection "Alignment, Take 2"
+I'm afraid that we're not quite through with the alignment catch yet. The
+hydra raises another ugly head when you pack arrays of structures:
+.PP
+.Vb 4
+\&   typedef struct {
+\&     short    count;
+\&     char     glyph;
+\&   } cell_t;
+\&
+\&   typedef cell_t buffer_t[BUFLEN];
+.Ve
+.PP
+Where's the catch? Padding is neither required before the first field \f(CW\*(C`count\*(C'\fR,
+nor between this and the next field \f(CW\*(C`glyph\*(C'\fR, so why can't we simply pack
+like this:
+.PP
+.Vb 3
+\&   # something goes wrong here:
+\&   pack( \*(Aqs!a\*(Aq x @buffer,
+\&         map{ ( $_\->{count}, $_\->{glyph} ) } @buffer );
+.Ve
+.PP
+This packs \f(CW\*(C`3*@buffer\*(C'\fR bytes, but it turns out that the size of 
+\&\f(CW\*(C`buffer_t\*(C'\fR is four times \f(CW\*(C`BUFLEN\*(C'\fR! The moral of the story is that
+the required alignment of a structure or array is propagated to the
+next higher level where we have to consider padding \fIat the end\fR
+of each component as well. Thus the correct template is:
+.PP
+.Vb 2
+\&   pack( \*(Aqs!ax\*(Aq x @buffer,
+\&         map{ ( $_\->{count}, $_\->{glyph} ) } @buffer );
+.Ve
+.SS "Alignment, Take 3"
+.IX Subsection "Alignment, Take 3"
+And even if you take all the above into account, ANSI still lets this:
+.PP
+.Vb 3
+\&   typedef struct {
+\&     char     foo[2];
+\&   } foo_t;
+.Ve
+.PP
+vary in size. The alignment constraint of the structure can be greater than
+any of its elements. [And if you think that this doesn't affect anything
+common, dismember the next cellphone that you see. Many have ARM cores, and
+the ARM structure rules make \f(CW\*(C`sizeof (foo_t)\*(C'\fR == 4]
+.SS "Pointers for How to Use Them"
+.IX Subsection "Pointers for How to Use Them"
+The title of this section indicates the second problem you may run into
+sooner or later when you pack C structures. If the function you intend
+to call expects a, say, \f(CW\*(C`void *\*(C'\fR value, you \fIcannot\fR simply take
+a reference to a Perl variable. (Although that value certainly is a
+memory address, it's not the address where the variable's contents are
+stored.)
+.PP
+Template code \f(CW\*(C`P\*(C'\fR promises to pack a "pointer to a fixed length string".
+Isn't this what we want? Let's try:
+.PP
+.Vb 3
+\&    # allocate some storage and pack a pointer to it
+\&    my $memory = "\ex00" x $size;
+\&    my $memptr = pack( \*(AqP\*(Aq, $memory );
+.Ve
+.PP
+But wait: doesn't \f(CW\*(C`pack\*(C'\fR just return a sequence of bytes? How can we pass this
+string of bytes to some C code expecting a pointer which is, after all,
+nothing but a number? The answer is simple: We have to obtain the numeric
+address from the bytes returned by \f(CW\*(C`pack\*(C'\fR.
+.PP
+.Vb 1
+\&    my $ptr = unpack( \*(AqL!\*(Aq, $memptr );
+.Ve
+.PP
+Obviously this assumes that it is possible to typecast a pointer
+to an unsigned long and vice versa, which frequently works but should not
+be taken as a universal law. \- Now that we have this pointer the next question
+is: How can we put it to good use? We need a call to some C function
+where a pointer is expected. The \fBread\fR\|(2) system call comes to mind:
+.PP
+.Vb 1
+\&    ssize_t read(int fd, void *buf, size_t count);
+.Ve
+.PP
+After reading perlfunc explaining how to use \f(CW\*(C`syscall\*(C'\fR we can write
+this Perl function copying a file to standard output:
+.PP
+.Vb 12
+\&    require \*(Aqsyscall.ph\*(Aq; # run h2ph to generate this file
+\&    sub cat($){
+\&        my $path = shift();
+\&        my $size = \-s $path;
+\&        my $memory = "\ex00" x $size;  # allocate some memory
+\&        my $ptr = unpack( \*(AqL\*(Aq, pack( \*(AqP\*(Aq, $memory ) );
+\&        open( F, $path ) || die( "$path: cannot open ($!)\en" );
+\&        my $fd = fileno(F);
+\&        my $res = syscall( &SYS_read, fileno(F), $ptr, $size );
+\&        print $memory;
+\&        close( F );
+\&    }
+.Ve
+.PP
+This is neither a specimen of simplicity nor a paragon of portability but
+it illustrates the point: We are able to sneak behind the scenes and
+access Perl's otherwise well-guarded memory! (Important note: Perl's
+\&\f(CW\*(C`syscall\*(C'\fR does \fInot\fR require you to construct pointers in this roundabout
+way. You simply pass a string variable, and Perl forwards the address.)
+.PP
+How does \f(CW\*(C`unpack\*(C'\fR with \f(CW\*(C`P\*(C'\fR work? Imagine some pointer in the buffer
+about to be unpacked: If it isn't the null pointer (which will smartly
+produce the \f(CW\*(C`undef\*(C'\fR value) we have a start address \- but then what?
+Perl has no way of knowing how long this "fixed length string" is, so
+it's up to you to specify the actual size as an explicit length after \f(CW\*(C`P\*(C'\fR.
+.PP
+.Vb 2
+\&   my $mem = "abcdefghijklmn";
+\&   print unpack( \*(AqP5\*(Aq, pack( \*(AqP\*(Aq, $mem ) ); # prints "abcde"
+.Ve
+.PP
+As a consequence, \f(CW\*(C`pack\*(C'\fR ignores any number or \f(CW\*(C`*\*(C'\fR after \f(CW\*(C`P\*(C'\fR.
+.PP
+Now that we have seen \f(CW\*(C`P\*(C'\fR at work, we might as well give \f(CW\*(C`p\*(C'\fR a whirl.
+Why do we need a second template code for packing pointers at all? The 
+answer lies behind the simple fact that an \f(CW\*(C`unpack\*(C'\fR with \f(CW\*(C`p\*(C'\fR promises
+a null-terminated string starting at the address taken from the buffer,
+and that implies a length for the data item to be returned:
+.PP
+.Vb 2
+\&   my $buf = pack( \*(Aqp\*(Aq, "abc\ex00efhijklmn" );
+\&   print unpack( \*(Aqp\*(Aq, $buf );    # prints "abc"
+.Ve
+.PP
+Albeit this is apt to be confusing: As a consequence of the length being
+implied by the string's length, a number after pack code \f(CW\*(C`p\*(C'\fR is a repeat
+count, not a length as after \f(CW\*(C`P\*(C'\fR.
+.PP
+Using \f(CW\*(C`pack(..., $x)\*(C'\fR with \f(CW\*(C`P\*(C'\fR or \f(CW\*(C`p\*(C'\fR to get the address where \f(CW$x\fR is
+actually stored must be used with circumspection. Perl's internal machinery
+considers the relation between a variable and that address as its very own 
+private matter and doesn't really care that we have obtained a copy. Therefore:
+.IP \(bu 4
+Do not use \f(CW\*(C`pack\*(C'\fR with \f(CW\*(C`p\*(C'\fR or \f(CW\*(C`P\*(C'\fR to obtain the address of variable
+that's bound to go out of scope (and thereby freeing its memory) before you
+are done with using the memory at that address.
+.IP \(bu 4
+Be very careful with Perl operations that change the value of the
+variable. Appending something to the variable, for instance, might require
+reallocation of its storage, leaving you with a pointer into no-man's land.
+.IP \(bu 4
+Don't think that you can get the address of a Perl variable
+when it is stored as an integer or double number! \f(CW\*(C`pack(\*(AqP\*(Aq, $x)\*(C'\fR will
+force the variable's internal representation to string, just as if you
+had written something like \f(CW\*(C`$x .= \*(Aq\*(Aq\*(C'\fR.
+.PP
+It's safe, however, to P\- or p\-pack a string literal, because Perl simply
+allocates an anonymous variable.
+.SH "Pack Recipes"
+.IX Header "Pack Recipes"
+Here are a collection of (possibly) useful canned recipes for \f(CW\*(C`pack\*(C'\fR
+and \f(CW\*(C`unpack\*(C'\fR:
+.PP
+.Vb 2
+\&    # Convert IP address for socket functions
+\&    pack( "C4", split /\e./, "123.4.5.6" ); 
+\&
+\&    # Count the bits in a chunk of memory (e.g. a select vector)
+\&    unpack( \*(Aq%32b*\*(Aq, $mask );
+\&
+\&    # Determine the endianness of your system
+\&    $is_little_endian = unpack( \*(Aqc\*(Aq, pack( \*(Aqs\*(Aq, 1 ) );
+\&    $is_big_endian = unpack( \*(Aqxc\*(Aq, pack( \*(Aqs\*(Aq, 1 ) );
+\&
+\&    # Determine the number of bits in a native integer
+\&    $bits = unpack( \*(Aq%32I!\*(Aq, ~0 );
+\&
+\&    # Prepare argument for the nanosleep system call
+\&    my $timespec = pack( \*(AqL!L!\*(Aq, $secs, $nanosecs );
+.Ve
+.PP
+For a simple memory dump we unpack some bytes into just as 
+many pairs of hex digits, and use \f(CW\*(C`map\*(C'\fR to handle the traditional
+spacing \- 16 bytes to a line:
+.PP
+.Vb 4
+\&    my $i;
+\&    print map( ++$i % 16 ? "$_ " : "$_\en",
+\&               unpack( \*(AqH2\*(Aq x length( $mem ), $mem ) ),
+\&          length( $mem ) % 16 ? "\en" : \*(Aq\*(Aq;
+.Ve
+.SH "Funnies Section"
+.IX Header "Funnies Section"
+.Vb 5
+\&    # Pulling digits out of nowhere...
+\&    print unpack( \*(AqC\*(Aq, pack( \*(Aqx\*(Aq ) ),
+\&          unpack( \*(Aq%B*\*(Aq, pack( \*(AqA\*(Aq ) ),
+\&          unpack( \*(AqH\*(Aq, pack( \*(AqA\*(Aq ) ),
+\&          unpack( \*(AqA\*(Aq, unpack( \*(AqC\*(Aq, pack( \*(AqA\*(Aq ) ) ), "\en";
+\&
+\&    # One for the road ;\-)
+\&    my $advice = pack( \*(Aqall u can in a van\*(Aq );
+.Ve
+.SH Authors
+.IX Header "Authors"
+Simon Cozens and Wolfgang Laun.
diff --git a/upstream/mageia-cauldron/man1/perlperf.1 b/upstream/mageia-cauldron/man1/perlperf.1
new file mode 100644
index 00000000..cf1390a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlperf.1
@@ -0,0 +1,1292 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPERF 1"
+.TH PERLPERF 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlperf \- Perl Performance and Optimization Techniques
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is an introduction to the use of performance and optimization techniques
+which can be used with particular reference to perl programs.  While many perl
+developers have come from other languages, and can use their prior knowledge
+where appropriate, there are many other people who might benefit from a few
+perl specific pointers.  If you want the condensed version, perhaps the best
+advice comes from the renowned Japanese Samurai, Miyamoto Musashi, who said:
+.PP
+.Vb 1
+\& "Do Not Engage in Useless Activity"
+.Ve
+.PP
+in 1645.
+.SH OVERVIEW
+.IX Header "OVERVIEW"
+Perhaps the most common mistake programmers make is to attempt to optimize
+their code before a program actually does anything useful \- this is a bad idea.
+There's no point in having an extremely fast program that doesn't work.  The
+first job is to get a program to \fIcorrectly\fR do something \fBuseful\fR, (not to
+mention ensuring the test suite is fully functional), and only then to consider
+optimizing it.  Having decided to optimize existing working code, there are
+several simple but essential steps to consider which are intrinsic to any
+optimization process.
+.SS "ONE STEP SIDEWAYS"
+.IX Subsection "ONE STEP SIDEWAYS"
+Firstly, you need to establish a baseline time for the existing code, which
+timing needs to be reliable and repeatable.  You'll probably want to use the
+\&\f(CW\*(C`Benchmark\*(C'\fR or \f(CW\*(C`Devel::NYTProf\*(C'\fR modules, or something similar, for this step,
+or perhaps the Unix system \f(CW\*(C`time\*(C'\fR utility, whichever is appropriate.  See the
+base of this document for a longer list of benchmarking and profiling modules,
+and recommended further reading.
+.SS "ONE STEP FORWARD"
+.IX Subsection "ONE STEP FORWARD"
+Next, having examined the program for \fIhot spots\fR, (places where the code
+seems to run slowly), change the code with the intention of making it run
+faster.  Using version control software, like \f(CW\*(C`subversion\*(C'\fR, will ensure no
+changes are irreversible.  It's too easy to fiddle here and fiddle there \-
+don't change too much at any one time or you might not discover which piece of
+code \fBreally\fR was the slow bit.
+.SS "ANOTHER STEP SIDEWAYS"
+.IX Subsection "ANOTHER STEP SIDEWAYS"
+It's not enough to say: "that will make it run faster", you have to check it.
+Rerun the code under control of the benchmarking or profiling modules, from the
+first step above, and check that the new code executed the \fBsame task\fR in
+\&\fIless time\fR.  Save your work and repeat...
+.SH "GENERAL GUIDELINES"
+.IX Header "GENERAL GUIDELINES"
+The critical thing when considering performance is to remember there is no such
+thing as a \f(CW\*(C`Golden Bullet\*(C'\fR, which is why there are no rules, only guidelines.
+.PP
+It is clear that inline code is going to be faster than subroutine or method
+calls, because there is less overhead, but this approach has the disadvantage
+of being less maintainable and comes at the cost of greater memory usage \-
+there is no such thing as a free lunch.  If you are searching for an element in
+a list, it can be more efficient to store the data in a hash structure, and
+then simply look to see whether the key is defined, rather than to loop through
+the entire array using \fBgrep()\fR for instance.  \fBsubstr()\fR may be (a lot) faster
+than \fBgrep()\fR but not as flexible, so you have another trade-off to access.  Your
+code may contain a line which takes 0.01 of a second to execute which if you
+call it 1,000 times, quite likely in a program parsing even medium sized files
+for instance, you already have a 10 second delay, in just one single code
+location, and if you call that line 100,000 times, your entire program will
+slow down to an unbearable crawl.
+.PP
+Using a subroutine as part of your sort is a powerful way to get exactly what
+you want, but will usually be slower than the built-in \fIalphabetic\fR \f(CW\*(C`cmp\*(C'\fR and
+\&\fInumeric\fR \f(CW\*(C`<=>\*(C'\fR sort operators.  It is possible to make multiple
+passes over your data, building indices to make the upcoming sort more
+efficient, and to use what is known as the \f(CW\*(C`OM\*(C'\fR (Orcish Maneuver) to cache the
+sort keys in advance.  The cache lookup, while a good idea, can itself be a
+source of slowdown by enforcing a double pass over the data \- once to setup the
+cache, and once to sort the data.  Using \f(CWpack()\fR to extract the required sort
+key into a consistent string can be an efficient way to build a single string
+to compare, instead of using multiple sort keys, which makes it possible to use
+the standard, written in \f(CW\*(C`c\*(C'\fR and fast, perl \f(CWsort()\fR function on the output,
+and is the basis of the \f(CW\*(C`GRT\*(C'\fR (Guttman Rossler Transform).  Some string
+combinations can slow the \f(CW\*(C`GRT\*(C'\fR down, by just being too plain complex for its
+own good.
+.PP
+For applications using database backends, the standard \f(CW\*(C`DBIx\*(C'\fR namespace has
+tries to help with keeping things nippy, not least because it tries to \fInot\fR
+query the database until the latest possible moment, but always read the docs
+which come with your choice of libraries.  Among the many issues facing
+developers dealing with databases should remain aware of is to always use
+\&\f(CW\*(C`SQL\*(C'\fR placeholders and to consider pre-fetching data sets when this might
+prove advantageous.  Splitting up a large file by assigning multiple processes
+to parsing a single file, using say \f(CW\*(C`POE\*(C'\fR, \f(CW\*(C`threads\*(C'\fR or \f(CW\*(C`fork\*(C'\fR can also be a
+useful way of optimizing your usage of the available \f(CW\*(C`CPU\*(C'\fR resources, though
+this technique is fraught with concurrency issues and demands high attention to
+detail.
+.PP
+Every case has a specific application and one or more exceptions, and there is
+no replacement for running a few tests and finding out which method works best
+for your particular environment, this is why writing optimal code is not an
+exact science, and why we love using Perl so much \- TMTOWTDI.
+.SH BENCHMARKS
+.IX Header "BENCHMARKS"
+Here are a few examples to demonstrate usage of Perl's benchmarking tools.
+.SS "Assigning and Dereferencing Variables."
+.IX Subsection "Assigning and Dereferencing Variables."
+I'm sure most of us have seen code which looks like, (or worse than), this:
+.PP
+.Vb 2
+\& if ( $obj\->{_ref}\->{_myscore} >= $obj\->{_ref}\->{_yourscore} ) {
+\&     ...
+.Ve
+.PP
+This sort of code can be a real eyesore to read, as well as being very
+sensitive to typos, and it's much clearer to dereference the variable
+explicitly.  We're side-stepping the issue of working with object-oriented
+programming techniques to encapsulate variable access via methods, only
+accessible through an object.  Here we're just discussing the technical
+implementation of choice, and whether this has an effect on performance.  We
+can see whether this dereferencing operation, has any overhead by putting
+comparative code in a file and running a \f(CW\*(C`Benchmark\*(C'\fR test.
+.PP
+# dereference
+.PP
+.Vb 1
+\& #!/usr/bin/perl
+\&
+\& use v5.36;
+\&
+\& use Benchmark;
+\&
+\& my $ref = {
+\&         \*(Aqref\*(Aq   => {
+\&             _myscore    => \*(Aq100 + 1\*(Aq,
+\&             _yourscore  => \*(Aq102 \- 1\*(Aq,
+\&         },
+\& };
+\&
+\& timethese(1000000, {
+\&         \*(Aqdirect\*(Aq       => sub {
+\&           my $x = $ref\->{ref}\->{_myscore} . $ref\->{ref}\->{_yourscore} ;
+\&         },
+\&         \*(Aqdereference\*(Aq  => sub {
+\&             my $ref  = $ref\->{ref};
+\&             my $myscore = $ref\->{_myscore};
+\&             my $yourscore = $ref\->{_yourscore};
+\&             my $x = $myscore . $yourscore;
+\&         },
+\& });
+.Ve
+.PP
+It's essential to run any timing measurements a sufficient number of times so
+the numbers settle on a numerical average, otherwise each run will naturally
+fluctuate due to variations in the environment, to reduce the effect of
+contention for \f(CW\*(C`CPU\*(C'\fR resources and network bandwidth for instance.  Running
+the above code for one million iterations, we can take a look at the report
+output by the \f(CW\*(C`Benchmark\*(C'\fR module, to see which approach is the most effective.
+.PP
+.Vb 1
+\& $> perl dereference
+\&
+\& Benchmark: timing 1000000 iterations of dereference, direct...
+\& dereference:  2 wallclock secs ( 1.59 usr +  0.00 sys =  1.59 CPU) @ 628930.82/s (n=1000000)
+\&     direct:  1 wallclock secs ( 1.20 usr +  0.00 sys =  1.20 CPU) @ 833333.33/s (n=1000000)
+.Ve
+.PP
+The difference is clear to see and the dereferencing approach is slower.  While
+it managed to execute an average of 628,930 times a second during our test, the
+direct approach managed to run an additional 204,403 times, unfortunately.
+Unfortunately, because there are many examples of code written using the
+multiple layer direct variable access, and it's usually horrible.  It is,
+however, minusculy faster.  The question remains whether the minute gain is
+actually worth the eyestrain, or the loss of maintainability.
+.SS "Search and replace or tr"
+.IX Subsection "Search and replace or tr"
+If we have a string which needs to be modified, while a regex will almost
+always be much more flexible, \f(CW\*(C`tr\*(C'\fR, an oft underused tool, can still be a
+useful.  One scenario might be replace all vowels with another character.  The
+regex solution might look like this:
+.PP
+.Vb 1
+\& $str =~ s/[aeiou]/x/g
+.Ve
+.PP
+The \f(CW\*(C`tr\*(C'\fR alternative might look like this:
+.PP
+.Vb 1
+\& $str =~ tr/aeiou/xxxxx/
+.Ve
+.PP
+We can put that into a test file which we can run to check which approach is
+the fastest, using a global \f(CW$STR\fR variable to assign to the \f(CW\*(C`my $str\*(C'\fR
+variable so as to avoid perl trying to optimize any of the work away by
+noticing it's assigned only the once.
+.PP
+# regex-transliterate
+.PP
+.Vb 1
+\& #!/usr/bin/perl
+\&
+\& use v5.36;
+\&
+\& use Benchmark;
+\&
+\& my $STR = "$$\-this and that";
+\&
+\& timethese( 1000000, {
+\& \*(Aqsr\*(Aq  => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return $str; },
+\& \*(Aqtr\*(Aq  => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return $str; },
+\& });
+.Ve
+.PP
+Running the code gives us our results:
+.PP
+.Vb 1
+\& $> perl regex\-transliterate
+\&
+\& Benchmark: timing 1000000 iterations of sr, tr...
+\&         sr:  2 wallclock secs ( 1.19 usr +  0.00 sys =  1.19 CPU) @ 840336.13/s (n=1000000)
+\&         tr:  0 wallclock secs ( 0.49 usr +  0.00 sys =  0.49 CPU) @ 2040816.33/s (n=1000000)
+.Ve
+.PP
+The \f(CW\*(C`tr\*(C'\fR version is a clear winner.  One solution is flexible, the other is
+fast \- and it's appropriately the programmer's choice which to use.
+.PP
+Check the \f(CW\*(C`Benchmark\*(C'\fR docs for further useful techniques.
+.SH "PROFILING TOOLS"
+.IX Header "PROFILING TOOLS"
+A slightly larger piece of code will provide something on which a profiler can
+produce more extensive reporting statistics.  This example uses the simplistic
+\&\f(CW\*(C`wordmatch\*(C'\fR program which parses a given input file and spews out a short
+report on the contents.
+.PP
+# wordmatch
+.PP
+.Vb 1
+\& #!/usr/bin/perl
+\&
+\& use v5.36;
+\&
+\& =head1 NAME
+\&
+\& filewords \- word analysis of input file
+\&
+\& =head1 SYNOPSIS
+\&
+\&     filewords \-f inputfilename [\-d]
+\&
+\& =head1 DESCRIPTION
+\&
+\& This program parses the given filename, specified with C<\-f>, and
+\& displays a simple analysis of the words found therein.  Use the C<\-d>
+\& switch to enable debugging messages.
+\&
+\& =cut
+\&
+\& use FileHandle;
+\& use Getopt::Long;
+\&
+\& my $debug   =  0;
+\& my $file    = \*(Aq\*(Aq;
+\&
+\& my $result = GetOptions (
+\&     \*(Aqdebug\*(Aq         => \e$debug,
+\&     \*(Aqfile=s\*(Aq        => \e$file,
+\& );
+\& die("invalid args") unless $result;
+\&
+\& unless ( \-f $file ) {
+\&     die("Usage: $0 \-f filename [\-d]");
+\& }
+\& my $FH = FileHandle\->new("< $file")
+\&                               or die("unable to open file($file): $!");
+\&
+\& my $i_LINES = 0;
+\& my $i_WORDS = 0;
+\& my %count   = ();
+\&
+\& my @lines = <$FH>;
+\& foreach my $line ( @lines ) {
+\&     $i_LINES++;
+\&     $line =~ s/\en//;
+\&     my @words = split(/ +/, $line);
+\&     my $i_words = scalar(@words);
+\&     $i_WORDS = $i_WORDS + $i_words;
+\&     debug("line: $i_LINES supplying $i_words words: @words");
+\&     my $i_word = 0;
+\&     foreach my $word ( @words ) {
+\&         $i_word++;
+\&         $count{$i_LINES}{spec} += matches($i_word, $word,
+\&                                           \*(Aq[^a\-zA\-Z0\-9]\*(Aq);
+\&         $count{$i_LINES}{only} += matches($i_word, $word,
+\&                                           \*(Aq^[^a\-zA\-Z0\-9]+$\*(Aq);
+\&         $count{$i_LINES}{cons} += matches($i_word, $word,
+\&                                     \*(Aq^[(?i:bcdfghjklmnpqrstvwxyz)]+$\*(Aq);
+\&         $count{$i_LINES}{vows} += matches($i_word, $word,
+\&                                           \*(Aq^[(?i:aeiou)]+$\*(Aq);
+\&         $count{$i_LINES}{caps} += matches($i_word, $word,
+\&                                           \*(Aq^[(A\-Z)]+$\*(Aq);
+\&     }
+\& }
+\&
+\& print report( %count );
+\&
+\& sub matches {
+\&     my $i_wd  = shift;
+\&     my $word  = shift;
+\&     my $regex = shift;
+\&     my $has = 0;
+\&
+\&     if ( $word =~ /($regex)/ ) {
+\&         $has++ if $1;
+\&     }
+\&
+\&     debug( "word: $i_wd "
+\&           . ($has ? \*(Aqmatches\*(Aq : \*(Aqdoes not match\*(Aq)
+\&           . " chars: /$regex/");
+\&
+\&     return $has;
+\& }
+\&
+\& sub report {
+\&     my %report = @_;
+\&     my %rep;
+\&
+\&     foreach my $line ( keys %report ) {
+\&         foreach my $key ( keys $report{$line}\->%* ) {
+\&             $rep{$key} += $report{$line}{$key};
+\&         }
+\&     }
+\&
+\&     my $report = qq|
+\& $0 report for $file:
+\& lines in file: $i_LINES
+\& words in file: $i_WORDS
+\& words with special (non\-word) characters: $i_spec
+\& words with only special (non\-word) characters: $i_only
+\& words with only consonants: $i_cons
+\& words with only capital letters: $i_caps
+\& words with only vowels: $i_vows
+\& |;
+\&
+\&     return $report;
+\& }
+\&
+\& sub debug {
+\&     my $message = shift;
+\&
+\&     if ( $debug ) {
+\&         print STDERR "DBG: $message\en";
+\&     }
+\& }
+\&
+\& exit 0;
+.Ve
+.SS Devel::DProf
+.IX Subsection "Devel::DProf"
+This venerable module has been the de-facto standard for Perl code profiling
+for more than a decade, but has been replaced by a number of other modules
+which have brought us back to the 21st century.  Although you're recommended to
+evaluate your tool from the several mentioned here and from the CPAN list at
+the base of this document, (and currently Devel::NYTProf seems to be the
+weapon of choice \- see below), we'll take a quick look at the output from
+Devel::DProf first, to set a baseline for Perl profiling tools.  Run the
+above program under the control of \f(CW\*(C`Devel::DProf\*(C'\fR by using the \f(CW\*(C`\-d\*(C'\fR switch on
+the command-line.
+.PP
+.Vb 1
+\& $> perl \-d:DProf wordmatch \-f perl5db.pl
+\&
+\& <...multiple lines snipped...>
+\&
+\& wordmatch report for perl5db.pl:
+\& lines in file: 9428
+\& words in file: 50243
+\& words with special (non\-word) characters: 20480
+\& words with only special (non\-word) characters: 7790
+\& words with only consonants: 4801
+\& words with only capital letters: 1316
+\& words with only vowels: 1701
+.Ve
+.PP
+\&\f(CW\*(C`Devel::DProf\*(C'\fR produces a special file, called \fItmon.out\fR by default, and
+this file is read by the \f(CW\*(C`dprofpp\*(C'\fR program, which is already installed as part
+of the \f(CW\*(C`Devel::DProf\*(C'\fR distribution.  If you call \f(CW\*(C`dprofpp\*(C'\fR with no options,
+it will read the \fItmon.out\fR file in the current directory and produce a human
+readable statistics report of the run of your program.  Note that this may take
+a little time.
+.PP
+.Vb 1
+\& $> dprofpp
+\&
+\& Total Elapsed Time = 2.951677 Seconds
+\&   User+System Time = 2.871677 Seconds
+\& Exclusive Times
+\& %Time ExclSec CumulS #Calls sec/call Csec/c  Name
+\&  102.   2.945  3.003 251215   0.0000 0.0000  main::matches
+\&  2.40   0.069  0.069 260643   0.0000 0.0000  main::debug
+\&  1.74   0.050  0.050      1   0.0500 0.0500  main::report
+\&  1.04   0.030  0.049      4   0.0075 0.0123  main::BEGIN
+\&  0.35   0.010  0.010      3   0.0033 0.0033  Exporter::as_heavy
+\&  0.35   0.010  0.010      7   0.0014 0.0014  IO::File::BEGIN
+\&  0.00       \- \-0.000      1        \-      \-  Getopt::Long::FindOption
+\&  0.00       \- \-0.000      1        \-      \-  Symbol::BEGIN
+\&  0.00       \- \-0.000      1        \-      \-  Fcntl::BEGIN
+\&  0.00       \- \-0.000      1        \-      \-  Fcntl::bootstrap
+\&  0.00       \- \-0.000      1        \-      \-  warnings::BEGIN
+\&  0.00       \- \-0.000      1        \-      \-  IO::bootstrap
+\&  0.00       \- \-0.000      1        \-      \-  Getopt::Long::ConfigDefaults
+\&  0.00       \- \-0.000      1        \-      \-  Getopt::Long::Configure
+\&  0.00       \- \-0.000      1        \-      \-  Symbol::gensym
+.Ve
+.PP
+\&\f(CW\*(C`dprofpp\*(C'\fR will produce some quite detailed reporting on the activity of the
+\&\f(CW\*(C`wordmatch\*(C'\fR program.  The wallclock, user and system, times are at the top of
+the analysis, and after this are the main columns defining which define the
+report.  Check the \f(CW\*(C`dprofpp\*(C'\fR docs for details of the many options it supports.
+.PP
+See also \f(CW\*(C`Apache::DProf\*(C'\fR which hooks \f(CW\*(C`Devel::DProf\*(C'\fR into \f(CW\*(C`mod_perl\*(C'\fR.
+.SS Devel::Profiler
+.IX Subsection "Devel::Profiler"
+Let's take a look at the same program using a different profiler:
+\&\f(CW\*(C`Devel::Profiler\*(C'\fR, a drop-in Perl-only replacement for \f(CW\*(C`Devel::DProf\*(C'\fR.  The
+usage is very slightly different in that instead of using the special \f(CW\*(C`\-d:\*(C'\fR
+flag, you pull \f(CW\*(C`Devel::Profiler\*(C'\fR in directly as a module using \f(CW\*(C`\-M\*(C'\fR.
+.PP
+.Vb 1
+\& $> perl \-MDevel::Profiler wordmatch \-f perl5db.pl
+\&
+\& <...multiple lines snipped...>
+\&
+\& wordmatch report for perl5db.pl:
+\& lines in file: 9428
+\& words in file: 50243
+\& words with special (non\-word) characters: 20480
+\& words with only special (non\-word) characters: 7790
+\& words with only consonants: 4801
+\& words with only capital letters: 1316
+\& words with only vowels: 1701
+.Ve
+.PP
+\&\f(CW\*(C`Devel::Profiler\*(C'\fR generates a tmon.out file which is compatible with the
+\&\f(CW\*(C`dprofpp\*(C'\fR program, thus saving the construction of a dedicated statistics
+reader program.  \f(CW\*(C`dprofpp\*(C'\fR usage is therefore identical to the above example.
+.PP
+.Vb 1
+\& $> dprofpp
+\&
+\& Total Elapsed Time =   20.984 Seconds
+\&   User+System Time =   19.981 Seconds
+\& Exclusive Times
+\& %Time ExclSec CumulS #Calls sec/call Csec/c  Name
+\&  49.0   9.792 14.509 251215   0.0000 0.0001  main::matches
+\&  24.4   4.887  4.887 260643   0.0000 0.0000  main::debug
+\&  0.25   0.049  0.049      1   0.0490 0.0490  main::report
+\&  0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::GetOptions
+\&  0.00   0.000  0.000      2   0.0000 0.0000  Getopt::Long::ParseOptionSpec
+\&  0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::FindOption
+\&  0.00   0.000  0.000      1   0.0000 0.0000  IO::File::new
+\&  0.00   0.000  0.000      1   0.0000 0.0000  IO::Handle::new
+\&  0.00   0.000  0.000      1   0.0000 0.0000  Symbol::gensym
+\&  0.00   0.000  0.000      1   0.0000 0.0000  IO::File::open
+.Ve
+.PP
+Interestingly we get slightly different results, which is mostly because the
+algorithm which generates the report is different, even though the output file
+format was allegedly identical.  The elapsed, user and system times are clearly
+showing the time it took for \f(CW\*(C`Devel::Profiler\*(C'\fR to execute its own run, but
+the column listings feel more accurate somehow than the ones we had earlier
+from \f(CW\*(C`Devel::DProf\*(C'\fR.  The 102% figure has disappeared, for example.  This is
+where we have to use the tools at our disposal, and recognise their pros and
+cons, before using them.  Interestingly, the numbers of calls for each
+subroutine are identical in the two reports, it's the percentages which differ.
+As the author of \f(CW\*(C`Devel::Profiler\*(C'\fR writes:
+.PP
+.Vb 6
+\& ...running HTML::Template\*(Aqs test suite under Devel::DProf shows
+\& output() taking NO time but Devel::Profiler shows around 10% of the
+\& time is in output().  I don\*(Aqt know which to trust but my gut tells me
+\& something is wrong with Devel::DProf.  HTML::Template::output() is a
+\& big routine that\*(Aqs called for every test. Either way, something needs
+\& fixing.
+.Ve
+.PP
+YMMV.
+.PP
+See also \f(CW\*(C`Devel::Apache::Profiler\*(C'\fR which hooks \f(CW\*(C`Devel::Profiler\*(C'\fR
+into \f(CW\*(C`mod_perl\*(C'\fR.
+.SS Devel::SmallProf
+.IX Subsection "Devel::SmallProf"
+The \f(CW\*(C`Devel::SmallProf\*(C'\fR profiler examines the runtime of your Perl program and
+produces a line-by-line listing to show how many times each line was called,
+and how long each line took to execute.  It is called by supplying the familiar
+\&\f(CW\*(C`\-d\*(C'\fR flag to Perl at runtime.
+.PP
+.Vb 1
+\& $> perl \-d:SmallProf wordmatch \-f perl5db.pl
+\&
+\& <...multiple lines snipped...>
+\&
+\& wordmatch report for perl5db.pl:
+\& lines in file: 9428
+\& words in file: 50243
+\& words with special (non\-word) characters: 20480
+\& words with only special (non\-word) characters: 7790
+\& words with only consonants: 4801
+\& words with only capital letters: 1316
+\& words with only vowels: 1701
+.Ve
+.PP
+\&\f(CW\*(C`Devel::SmallProf\*(C'\fR writes its output into a file called \fIsmallprof.out\fR, by
+default.  The format of the file looks like this:
+.PP
+.Vb 1
+\& <num> <time> <ctime> <line>:<text>
+.Ve
+.PP
+When the program has terminated, the output may be examined and sorted using
+any standard text filtering utilities.  Something like the following may be
+sufficient:
+.PP
+.Vb 1
+\& $> cat smallprof.out | grep \ed*: | sort \-k3 | tac | head \-n20
+\&
+\& 251215   1.65674   7.68000    75: if ( $word =~ /($regex)/ ) {
+\& 251215   0.03264   4.40000    79: debug("word: $i_wd ".($has ? \*(Aqmatches\*(Aq :
+\& 251215   0.02693   4.10000    81: return $has;
+\& 260643   0.02841   4.07000   128: if ( $debug ) {
+\& 260643   0.02601   4.04000   126: my $message = shift;
+\& 251215   0.02641   3.91000    73: my $has = 0;
+\& 251215   0.03311   3.71000    70: my $i_wd  = shift;
+\& 251215   0.02699   3.69000    72: my $regex = shift;
+\& 251215   0.02766   3.68000    71: my $word  = shift;
+\&  50243   0.59726   1.00000    59:  $count{$i_LINES}{cons} =
+\&  50243   0.48175   0.92000    61:  $count{$i_LINES}{spec} =
+\&  50243   0.00644   0.89000    56:  my $i_cons = matches($i_word, $word,
+\&  50243   0.48837   0.88000    63:  $count{$i_LINES}{caps} =
+\&  50243   0.00516   0.88000    58:  my $i_caps = matches($i_word, $word, \*(Aq^[(A\-
+\&  50243   0.00631   0.81000    54:  my $i_spec = matches($i_word, $word, \*(Aq[^a\-
+\&  50243   0.00496   0.80000    57:  my $i_vows = matches($i_word, $word,
+\&  50243   0.00688   0.80000    53:  $i_word++;
+\&  50243   0.48469   0.79000    62:  $count{$i_LINES}{only} =
+\&  50243   0.48928   0.77000    60:  $count{$i_LINES}{vows} =
+\&  50243   0.00683   0.75000    55:  my $i_only = matches($i_word, $word, \*(Aq^[^a\-
+.Ve
+.PP
+You can immediately see a slightly different focus to the subroutine profiling
+modules, and we start to see exactly which line of code is taking the most
+time.  That regex line is looking a bit suspicious, for example.  Remember that
+these tools are supposed to be used together, there is no single best way to
+profile your code, you need to use the best tools for the job.
+.PP
+See also \f(CW\*(C`Apache::SmallProf\*(C'\fR which hooks \f(CW\*(C`Devel::SmallProf\*(C'\fR into
+\&\f(CW\*(C`mod_perl\*(C'\fR.
+.SS Devel::FastProf
+.IX Subsection "Devel::FastProf"
+\&\f(CW\*(C`Devel::FastProf\*(C'\fR is another Perl line profiler.  This was written with a view
+to getting a faster line profiler, than is possible with for example
+\&\f(CW\*(C`Devel::SmallProf\*(C'\fR, because it's written in \f(CW\*(C`C\*(C'\fR.  To use \f(CW\*(C`Devel::FastProf\*(C'\fR,
+supply the \f(CW\*(C`\-d\*(C'\fR argument to Perl:
+.PP
+.Vb 1
+\& $> perl \-d:FastProf wordmatch \-f perl5db.pl
+\&
+\& <...multiple lines snipped...>
+\&
+\& wordmatch report for perl5db.pl:
+\& lines in file: 9428
+\& words in file: 50243
+\& words with special (non\-word) characters: 20480
+\& words with only special (non\-word) characters: 7790
+\& words with only consonants: 4801
+\& words with only capital letters: 1316
+\& words with only vowels: 1701
+.Ve
+.PP
+\&\f(CW\*(C`Devel::FastProf\*(C'\fR writes statistics to the file \fIfastprof.out\fR in the current
+directory.  The output file, which can be specified, can be interpreted by using
+the \f(CW\*(C`fprofpp\*(C'\fR command-line program.
+.PP
+.Vb 1
+\& $> fprofpp | head \-n20
+\&
+\& # fprofpp output format is:
+\& # filename:line time count: source
+\& wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) {
+\& wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ? \*(Aqmatches\*(Aq : \*(Aqdoes not match\*(Aq)." chars: /$regex/");
+\& wordmatch:81 1.47604 251215: return $has;
+\& wordmatch:126 1.43441 260643: my $message = shift;
+\& wordmatch:128 1.42156 260643: if ( $debug ) {
+\& wordmatch:70 1.36824 251215: my $i_wd  = shift;
+\& wordmatch:71 1.36739 251215: my $word  = shift;
+\& wordmatch:72 1.35939 251215: my $regex = shift;
+.Ve
+.PP
+Straightaway we can see that the number of times each line has been called is
+identical to the \f(CW\*(C`Devel::SmallProf\*(C'\fR output, and the sequence is only very
+slightly different based on the ordering of the amount of time each line took
+to execute, \f(CW\*(C`if ( $debug ) { \*(C'\fR and \f(CW\*(C`my $message = shift;\*(C'\fR, for example.  The
+differences in the actual times recorded might be in the algorithm used
+internally, or it could be due to system resource limitations or contention.
+.PP
+See also the DBIx::Profile which will profile database queries running
+under the \f(CW\*(C`DBIx::*\*(C'\fR namespace.
+.SS Devel::NYTProf
+.IX Subsection "Devel::NYTProf"
+\&\f(CW\*(C`Devel::NYTProf\*(C'\fR is the \fBnext generation\fR of Perl code profiler, fixing many
+shortcomings in other tools and implementing many cool features.  First of all it
+can be used as either a \fIline\fR profiler, a \fIblock\fR or a \fIsubroutine\fR
+profiler, all at once.  It can also use sub-microsecond (100ns) resolution on
+systems which provide \f(CWclock_gettime()\fR.  It can be started and stopped even
+by the program being profiled.  It's a one-line entry to profile \f(CW\*(C`mod_perl\*(C'\fR
+applications.  It's written in \f(CW\*(C`c\*(C'\fR and is probably the fastest profiler
+available for Perl.  The list of coolness just goes on.  Enough of that, let's
+see how to it works \- just use the familiar \f(CW\*(C`\-d\*(C'\fR switch to plug it in and run
+the code.
+.PP
+.Vb 1
+\& $> perl \-d:NYTProf wordmatch \-f perl5db.pl
+\&
+\& wordmatch report for perl5db.pl:
+\& lines in file: 9427
+\& words in file: 50243
+\& words with special (non\-word) characters: 20480
+\& words with only special (non\-word) characters: 7790
+\& words with only consonants: 4801
+\& words with only capital letters: 1316
+\& words with only vowels: 1701
+.Ve
+.PP
+\&\f(CW\*(C`NYTProf\*(C'\fR will generate a report database into the file \fInytprof.out\fR by
+default.  Human readable reports can be generated from here by using the
+supplied \f(CW\*(C`nytprofhtml\*(C'\fR (HTML output) and \f(CW\*(C`nytprofcsv\*(C'\fR (CSV output) programs.
+We've used the Unix system \f(CW\*(C`html2text\*(C'\fR utility to convert the
+\&\fInytprof/index.html\fR file for convenience here.
+.PP
+.Vb 1
+\& $> html2text nytprof/index.html
+\&
+\& Performance Profile Index
+\& For wordmatch
+\&   Run on Fri Sep 26 13:46:39 2008
+\& Reported on Fri Sep 26 13:47:23 2008
+\&
+\&          Top 15 Subroutines \-\- ordered by exclusive time
+\& |Calls |P |F |Inclusive|Exclusive|Subroutine                          |
+\& |      |  |  |Time     |Time     |                                    |
+\& |251215|5 |1 |13.09263 |10.47692 |main::              |matches        |
+\& |260642|2 |1 |2.71199  |2.71199  |main::              |debug          |
+\& |1     |1 |1 |0.21404  |0.21404  |main::              |report         |
+\& |2     |2 |2 |0.00511  |0.00511  |XSLoader::          |load (xsub)    |
+\& |14    |14|7 |0.00304  |0.00298  |Exporter::          |import         |
+\& |3     |1 |1 |0.00265  |0.00254  |Exporter::          |as_heavy       |
+\& |10    |10|4 |0.00140  |0.00140  |vars::              |import         |
+\& |13    |13|1 |0.00129  |0.00109  |constant::          |import         |
+\& |1     |1 |1 |0.00360  |0.00096  |FileHandle::        |import         |
+\& |3     |3 |3 |0.00086  |0.00074  |warnings::register::|import         |
+\& |9     |3 |1 |0.00036  |0.00036  |strict::            |bits           |
+\& |13    |13|13|0.00032  |0.00029  |strict::            |import         |
+\& |2     |2 |2 |0.00020  |0.00020  |warnings::          |import         |
+\& |2     |1 |1 |0.00020  |0.00020  |Getopt::Long::      |ParseOptionSpec|
+\& |7     |7 |6 |0.00043  |0.00020  |strict::            |unimport       |
+\&
+\& For more information see the full list of 189 subroutines.
+.Ve
+.PP
+The first part of the report already shows the critical information regarding
+which subroutines are using the most time.  The next gives some statistics
+about the source files profiled.
+.PP
+.Vb 10
+\&         Source Code Files \-\- ordered by exclusive time then name
+\& |Stmts  |Exclusive|Avg.   |Reports                     |Source File         |
+\& |       |Time     |       |                            |                    |
+\& |2699761|15.66654 |6e\-06  |line   .    block   .    sub|wordmatch           |
+\& |35     |0.02187  |0.00062|line   .    block   .    sub|IO/Handle.pm        |
+\& |274    |0.01525  |0.00006|line   .    block   .    sub|Getopt/Long.pm      |
+\& |20     |0.00585  |0.00029|line   .    block   .    sub|Fcntl.pm            |
+\& |128    |0.00340  |0.00003|line   .    block   .    sub|Exporter/Heavy.pm   |
+\& |42     |0.00332  |0.00008|line   .    block   .    sub|IO/File.pm          |
+\& |261    |0.00308  |0.00001|line   .    block   .    sub|Exporter.pm         |
+\& |323    |0.00248  |8e\-06  |line   .    block   .    sub|constant.pm         |
+\& |12     |0.00246  |0.00021|line   .    block   .    sub|File/Spec/Unix.pm   |
+\& |191    |0.00240  |0.00001|line   .    block   .    sub|vars.pm             |
+\& |77     |0.00201  |0.00003|line   .    block   .    sub|FileHandle.pm       |
+\& |12     |0.00198  |0.00016|line   .    block   .    sub|Carp.pm             |
+\& |14     |0.00175  |0.00013|line   .    block   .    sub|Symbol.pm           |
+\& |15     |0.00130  |0.00009|line   .    block   .    sub|IO.pm               |
+\& |22     |0.00120  |0.00005|line   .    block   .    sub|IO/Seekable.pm      |
+\& |198    |0.00085  |4e\-06  |line   .    block   .    sub|warnings/register.pm|
+\& |114    |0.00080  |7e\-06  |line   .    block   .    sub|strict.pm           |
+\& |47     |0.00068  |0.00001|line   .    block   .    sub|warnings.pm         |
+\& |27     |0.00054  |0.00002|line   .    block   .    sub|overload.pm         |
+\& |9      |0.00047  |0.00005|line   .    block   .    sub|SelectSaver.pm      |
+\& |13     |0.00045  |0.00003|line   .    block   .    sub|File/Spec.pm        |
+\& |2701595|15.73869 |       |Total                       |
+\& |128647 |0.74946  |       |Average                     |
+\& |       |0.00201  |0.00003|Median                      |
+\& |       |0.00121  |0.00003|Deviation                   |
+\&
+\& Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce and
+\& Adam Kaplan.
+.Ve
+.PP
+At this point, if you're using the \fIhtml\fR report, you can click through the
+various links to bore down into each subroutine and each line of code.  Because
+we're using the text reporting here, and there's a whole directory full of
+reports built for each source file, we'll just display a part of the
+corresponding \fIwordmatch\-line.html\fR file, sufficient to give an idea of the
+sort of output you can expect from this cool tool.
+.PP
+.Vb 1
+\& $> html2text nytprof/wordmatch\-line.html
+\&
+\& Performance Profile \-\- \-block view\-.\-line view\-.\-sub view\-
+\& For wordmatch
+\& Run on Fri Sep 26 13:46:39 2008
+\& Reported on Fri Sep 26 13:47:22 2008
+\&
+\& File wordmatch
+\&
+\&  Subroutines \-\- ordered by exclusive time
+\& |Calls |P|F|Inclusive|Exclusive|Subroutine    |
+\& |      | | |Time     |Time     |              |
+\& |251215|5|1|13.09263 |10.47692 |main::|matches|
+\& |260642|2|1|2.71199  |2.71199  |main::|debug  |
+\& |1     |1|1|0.21404  |0.21404  |main::|report |
+\& |0     |0|0|0        |0        |main::|BEGIN  |
+\&
+\&
+\& |Line|Stmts.|Exclusive|Avg.   |Code                                           |
+\& |    |      |Time     |       |                                               |
+\& |1   |      |         |       |#!/usr/bin/perl                                |
+\& |2   |      |         |       |                                               |
+\& |    |      |         |       |use strict;                                    |
+\& |3   |3     |0.00086  |0.00029|# spent 0.00003s making 1 calls to strict::    |
+\& |    |      |         |       |import                                         |
+\& |    |      |         |       |use warnings;                                  |
+\& |4   |3     |0.01563  |0.00521|# spent 0.00012s making 1 calls to warnings::  |
+\& |    |      |         |       |import                                         |
+\& |5   |      |         |       |                                               |
+\& |6   |      |         |       |=head1 NAME                                    |
+\& |7   |      |         |       |                                               |
+\& |8   |      |         |       |filewords \- word analysis of input file        |
+\& <...snip...>
+\& |62  |1     |0.00445  |0.00445|print report( %count );                        |
+\& |    |      |         |       |# spent 0.21404s making 1 calls to main::report|
+\& |63  |      |         |       |                                               |
+\& |    |      |         |       |# spent 23.56955s (10.47692+2.61571) within    |
+\& |    |      |         |       |main::matches which was called 251215 times,   |
+\& |    |      |         |       |avg 0.00005s/call: # 50243 times               |
+\& |    |      |         |       |(2.12134+0.51939s) at line 57 of wordmatch, avg|
+\& |    |      |         |       |0.00005s/call # 50243 times (2.17735+0.54550s) |
+\& |64  |      |         |       |at line 56 of wordmatch, avg 0.00005s/call #   |
+\& |    |      |         |       |50243 times (2.10992+0.51797s) at line 58 of   |
+\& |    |      |         |       |wordmatch, avg 0.00005s/call # 50243 times     |
+\& |    |      |         |       |(2.12696+0.51598s) at line 55 of wordmatch, avg|
+\& |    |      |         |       |0.00005s/call # 50243 times (1.94134+0.51687s) |
+\& |    |      |         |       |at line 54 of wordmatch, avg 0.00005s/call     |
+\& |    |      |         |       |sub matches {                                  |
+\& <...snip...>
+\& |102 |      |         |       |                                               |
+\& |    |      |         |       |# spent 2.71199s within main::debug which was  |
+\& |    |      |         |       |called 260642 times, avg 0.00001s/call: #      |
+\& |    |      |         |       |251215 times (2.61571+0s) by main::matches at  |
+\& |103 |      |         |       |line 74 of wordmatch, avg 0.00001s/call # 9427 |
+\& |    |      |         |       |times (0.09628+0s) at line 50 of wordmatch, avg|
+\& |    |      |         |       |0.00001s/call                                  |
+\& |    |      |         |       |sub debug {                                    |
+\& |104 |260642|0.58496  |2e\-06  |my $message = shift;                           |
+\& |105 |      |         |       |                                               |
+\& |106 |260642|1.09917  |4e\-06  |if ( $debug ) {                                |
+\& |107 |      |         |       |print STDERR "DBG: $message\en";                |
+\& |108 |      |         |       |}                                              |
+\& |109 |      |         |       |}                                              |
+\& |110 |      |         |       |                                               |
+\& |111 |1     |0.01501  |0.01501|exit 0;                                        |
+\& |112 |      |         |       |                                               |
+.Ve
+.PP
+Oodles of very useful information in there \- this seems to be the way forward.
+.PP
+See also \f(CW\*(C`Devel::NYTProf::Apache\*(C'\fR which hooks \f(CW\*(C`Devel::NYTProf\*(C'\fR into
+\&\f(CW\*(C`mod_perl\*(C'\fR.
+.SH SORTING
+.IX Header "SORTING"
+Perl modules are not the only tools a performance analyst has at their
+disposal, system tools like \f(CW\*(C`time\*(C'\fR should not be overlooked as the next
+example shows, where we take a quick look at sorting.  Many books, theses and
+articles, have been written about efficient sorting algorithms, and this is not
+the place to repeat such work, there's several good sorting modules which
+deserve taking a look at too: \f(CW\*(C`Sort::Maker\*(C'\fR, \f(CW\*(C`Sort::Key\*(C'\fR spring to mind.
+However, it's still possible to make some observations on certain Perl specific
+interpretations on issues relating to sorting data sets and give an example or
+two with regard to how sorting large data volumes can effect performance.
+Firstly, an often overlooked point when sorting large amounts of data, one can
+attempt to reduce the data set to be dealt with and in many cases \f(CWgrep()\fR can
+be quite useful as a simple filter:
+.PP
+.Vb 1
+\& @data = sort grep { /$filter/ } @incoming
+.Ve
+.PP
+A command such as this can vastly reduce the volume of material to actually
+sort through in the first place, and should not be too lightly disregarded
+purely on the basis of its simplicity.  The \f(CW\*(C`KISS\*(C'\fR principle is too often
+overlooked \- the next example uses the simple system \f(CW\*(C`time\*(C'\fR utility to
+demonstrate.  Let's take a look at an actual example of sorting the contents of
+a large file, an apache logfile would do.  This one has over a quarter of a
+million lines, is 50M in size, and a snippet of it looks like this:
+.PP
+# logfile
+.PP
+.Vb 10
+\& 188.209\-65\-87.adsl\-dyn.isp.belgacom.be \- \- [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "\-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& 188.209\-65\-87.adsl\-dyn.isp.belgacom.be \- \- [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "\-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& 151.56.71.198 \- \- [08/Feb/2007:12:57:41 +0000] "GET /suse\-on\-vaio.html HTTP/1.1" 200 2858 "http://www.linux\-on\-laptops.com/sony.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en\-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+\& 151.56.71.198 \- \- [08/Feb/2007:12:57:42 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse\-on\-vaio.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en\-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+\& 151.56.71.198 \- \- [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "\-" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en\-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+\& 217.113.68.60 \- \- [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1" 304 \- "\-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& 217.113.68.60 \- \- [08/Feb/2007:13:02:16 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& debora.to.isac.cnr.it \- \- [08/Feb/2007:13:03:58 +0000] "GET /suse\-on\-vaio.html HTTP/1.1" 200 2858 "http://www.linux\-on\-laptops.com/sony.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+\& debora.to.isac.cnr.it \- \- [08/Feb/2007:13:03:58 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse\-on\-vaio.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+\& debora.to.isac.cnr.it \- \- [08/Feb/2007:13:03:58 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "\-" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+\& 195.24.196.99 \- \- [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0" 200 3309 "\-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+\& 195.24.196.99 \- \- [08/Feb/2007:13:26:58 +0000] "GET /data/css HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+\& 195.24.196.99 \- \- [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico HTTP/1.0" 404 209 "\-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+\& crawl1.cosmixcorp.com \- \- [08/Feb/2007:13:27:57 +0000] "GET /robots.txt HTTP/1.0" 200 179 "\-" "voyager/1.0"
+\& crawl1.cosmixcorp.com \- \- [08/Feb/2007:13:28:25 +0000] "GET /links.html HTTP/1.0" 200 3413 "\-" "voyager/1.0"
+\& fhm226.internetdsl.tpnet.pl \- \- [08/Feb/2007:13:37:32 +0000] "GET /suse\-on\-vaio.html HTTP/1.1" 200 2858 "http://www.linux\-on\-laptops.com/sony.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& fhm226.internetdsl.tpnet.pl \- \- [08/Feb/2007:13:37:34 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse\-on\-vaio.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+\& 80.247.140.134 \- \- [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1" 200 3309 "\-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
+\& 80.247.140.134 \- \- [08/Feb/2007:13:57:37 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
+\& pop.compuscan.co.za \- \- [08/Feb/2007:14:10:43 +0000] "GET / HTTP/1.1" 200 3309 "\-" "www.clamav.net"
+\& livebot\-207\-46\-98\-57.search.live.com \- \- [08/Feb/2007:14:12:04 +0000] "GET /robots.txt HTTP/1.0" 200 179 "\-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
+\& livebot\-207\-46\-98\-57.search.live.com \- \- [08/Feb/2007:14:12:04 +0000] "GET /html/oracle.html HTTP/1.0" 404 214 "\-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
+\& dslb\-088\-064\-005\-154.pools.arcor\-ip.net \- \- [08/Feb/2007:14:12:15 +0000] "GET / HTTP/1.1" 200 3309 "\-" "www.clamav.net"
+\& 196.201.92.41 \- \- [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1" 200 3309 "\-" "MOT\-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP\-2.0 Configuration/CLDC\-1.1"
+.Ve
+.PP
+The specific task here is to sort the 286,525 lines of this file by Response
+Code, Query, Browser, Referring Url, and lastly Date.  One solution might be to
+use the following code, which iterates over the files given on the
+command-line.
+.PP
+# sort-apache-log
+.PP
+.Vb 1
+\& #!/usr/bin/perl \-n
+\&
+\& use v5.36;
+\&
+\& my @data;
+\&
+\& LINE:
+\& while ( <> ) {
+\&     my $line = $_;
+\&     if (
+\&         $line =~ m/^(
+\&             ([\ew\e.\e\-]+)             # client
+\&             \es*\-\es*\-\es*\e[
+\&             ([^]]+)                 # date
+\&             \e]\es*"\ew+\es*
+\&             (\eS+)                   # query
+\&             [^"]+"\es*
+\&             (\ed+)                   # status
+\&             \es+\eS+\es+"[^"]*"\es+"
+\&             ([^"]*)                 # browser
+\&             "
+\&             .*
+\&         )$/x
+\&     ) {
+\&         my @chunks = split(/ +/, $line);
+\&         my $ip      = $1;
+\&         my $date    = $2;
+\&         my $query   = $3;
+\&         my $status  = $4;
+\&         my $browser = $5;
+\&
+\&         push(@data, [$ip, $date, $query, $status, $browser, $line]);
+\&     }
+\& }
+\&
+\& my @sorted = sort {
+\&     $a\->[3] cmp $b\->[3]
+\&             ||
+\&     $a\->[2] cmp $b\->[2]
+\&             ||
+\&     $a\->[0] cmp $b\->[0]
+\&             ||
+\&     $a\->[1] cmp $b\->[1]
+\&             ||
+\&     $a\->[4] cmp $b\->[4]
+\& } @data;
+\&
+\& foreach my $data ( @sorted ) {
+\&     print $data\->[5];
+\& }
+\&
+\& exit 0;
+.Ve
+.PP
+When running this program, redirect \f(CW\*(C`STDOUT\*(C'\fR so it is possible to check the
+output is correct from following test runs and use the system \f(CW\*(C`time\*(C'\fR utility
+to check the overall runtime.
+.PP
+.Vb 1
+\& $> time ./sort\-apache\-log logfile > out\-sort
+\&
+\& real    0m17.371s
+\& user    0m15.757s
+\& sys     0m0.592s
+.Ve
+.PP
+The program took just over 17 wallclock seconds to run.  Note the different
+values \f(CW\*(C`time\*(C'\fR outputs, it's important to always use the same one, and to not
+confuse what each one means.
+.IP "Elapsed Real Time" 4
+.IX Item "Elapsed Real Time"
+The overall, or wallclock, time between when \f(CW\*(C`time\*(C'\fR was called, and when it
+terminates.  The elapsed time includes both user and system times, and time
+spent waiting for other users and processes on the system.  Inevitably, this is
+the most approximate of the measurements given.
+.IP "User CPU Time" 4
+.IX Item "User CPU Time"
+The user time is the amount of time the entire process spent on behalf of the
+user on this system executing this program.
+.IP "System CPU Time" 4
+.IX Item "System CPU Time"
+The system time is the amount of time the kernel itself spent executing
+routines, or system calls, on behalf of this process user.
+.PP
+Running this same process as a \f(CW\*(C`Schwarzian Transform\*(C'\fR it is possible to
+eliminate the input and output arrays for storing all the data, and work on the
+input directly as it arrives too.  Otherwise, the code looks fairly similar:
+.PP
+# sort-apache-log-schwarzian
+.PP
+.Vb 1
+\& #!/usr/bin/perl \-n
+\&
+\& use v5.36;
+\&
+\& print
+\&
+\&     map $_\->[0] =>
+\&
+\&     sort {
+\&         $a\->[4] cmp $b\->[4]
+\&                 ||
+\&         $a\->[3] cmp $b\->[3]
+\&                 ||
+\&         $a\->[1] cmp $b\->[1]
+\&                 ||
+\&         $a\->[2] cmp $b\->[2]
+\&                 ||
+\&         $a\->[5] cmp $b\->[5]
+\&     }
+\&     map  [ $_, m/^(
+\&         ([\ew\e.\e\-]+)             # client
+\&         \es*\-\es*\-\es*\e[
+\&         ([^]]+)                 # date
+\&         \e]\es*"\ew+\es*
+\&         (\eS+)                   # query
+\&         [^"]+"\es*
+\&         (\ed+)                   # status
+\&         \es+\eS+\es+"[^"]*"\es+"
+\&         ([^"]*)                 # browser
+\&         "
+\&         .*
+\&     )$/xo ]
+\&
+\&     => <>;
+\&
+\& exit 0;
+.Ve
+.PP
+Run the new code against the same logfile, as above, to check the new time.
+.PP
+.Vb 1
+\& $> time ./sort\-apache\-log\-schwarzian logfile > out\-schwarz
+\&
+\& real    0m9.664s
+\& user    0m8.873s
+\& sys     0m0.704s
+.Ve
+.PP
+The time has been cut in half, which is a respectable speed improvement by any
+standard.  Naturally, it is important to check the output is consistent with
+the first program run, this is where the Unix system \f(CW\*(C`cksum\*(C'\fR utility comes in.
+.PP
+.Vb 3
+\& $> cksum out\-sort out\-schwarz
+\& 3044173777 52029194 out\-sort
+\& 3044173777 52029194 out\-schwarz
+.Ve
+.PP
+BTW. Beware too of pressure from managers who see you speed a program up by 50%
+of the runtime once, only to get a request one month later to do the same again
+(true story) \- you'll just have to point out you're only human, even if you are a
+Perl programmer, and you'll see what you can do...
+.SH LOGGING
+.IX Header "LOGGING"
+An essential part of any good development process is appropriate error handling
+with appropriately informative messages, however there exists a school of
+thought which suggests that log files should be \fIchatty\fR, as if the chain of
+unbroken output somehow ensures the survival of the program.  If speed is in
+any way an issue, this approach is wrong.
+.PP
+A common sight is code which looks something like this:
+.PP
+.Vb 2
+\& logger\->debug( "A logging message via process\-id: $$ INC: "
+\&                                                       . Dumper(\e%INC) )
+.Ve
+.PP
+The problem is that this code will always be parsed and executed, even when the
+debug level set in the logging configuration file is zero.  Once the \fBdebug()\fR
+subroutine has been entered, and the internal \f(CW$debug\fR variable confirmed to
+be zero, for example, the message which has been sent in will be discarded and
+the program will continue.  In the example given though, the \f(CW\*(C`\e%INC\*(C'\fR hash will
+already have been dumped, and the message string constructed, all of which work
+could be bypassed by a debug variable at the statement level, like this:
+.PP
+.Vb 2
+\& logger\->debug( "A logging message via process\-id: $$ INC: "
+\&                                            . Dumper(\e%INC) ) if $DEBUG;
+.Ve
+.PP
+This effect can be demonstrated by setting up a test script with both forms,
+including a \f(CWdebug()\fR subroutine to emulate typical \f(CWlogger()\fR functionality.
+.PP
+# ifdebug
+.PP
+.Vb 1
+\& #!/usr/bin/perl
+\&
+\& use v5.36;
+\&
+\& use Benchmark;
+\& use Data::Dumper;
+\& my $DEBUG = 0;
+\&
+\& sub debug {
+\&     my $msg = shift;
+\&
+\&     if ( $DEBUG ) {
+\&         print "DEBUG: $msg\en";
+\&     }
+\& };
+\&
+\& timethese(100000, {
+\&         \*(Aqdebug\*(Aq       => sub {
+\&             debug( "A $0 logging message via process\-id: $$" . Dumper(\e%INC) )
+\&         },
+\&         \*(Aqifdebug\*(Aq  => sub {
+\&             debug( "A $0 logging message via process\-id: $$" . Dumper(\e%INC) ) if $DEBUG
+\&         },
+\& });
+.Ve
+.PP
+Let's see what \f(CW\*(C`Benchmark\*(C'\fR makes of this:
+.PP
+.Vb 5
+\& $> perl ifdebug
+\& Benchmark: timing 100000 iterations of constant, sub...
+\&    ifdebug:  0 wallclock secs ( 0.01 usr +  0.00 sys =  0.01 CPU) @ 10000000.00/s (n=100000)
+\&             (warning: too few iterations for a reliable count)
+\&      debug: 14 wallclock secs (13.18 usr +  0.04 sys = 13.22 CPU) @ 7564.30/s (n=100000)
+.Ve
+.PP
+In the one case the code, which does exactly the same thing as far as
+outputting any debugging information is concerned, in other words nothing,
+takes 14 seconds, and in the other case the code takes one hundredth of a
+second.  Looks fairly definitive.  Use a \f(CW$DEBUG\fR variable BEFORE you call the
+subroutine, rather than relying on the smart functionality inside it.
+.SS "Logging if DEBUG (constant)"
+.IX Subsection "Logging if DEBUG (constant)"
+It's possible to take the previous idea a little further, by using a compile
+time \f(CW\*(C`DEBUG\*(C'\fR constant.
+.PP
+# ifdebug-constant
+.PP
+.Vb 1
+\& #!/usr/bin/perl
+\&
+\& use v5.36;
+\&
+\& use Benchmark;
+\& use Data::Dumper;
+\& use constant
+\&     DEBUG => 0
+\& ;
+\&
+\& sub debug {
+\&     if ( DEBUG ) {
+\&         my $msg = shift;
+\&         print "DEBUG: $msg\en";
+\&     }
+\& };
+\&
+\& timethese(100000, {
+\&         \*(Aqdebug\*(Aq       => sub {
+\&             debug( "A $0 logging message via process\-id: $$" . Dumper(\e%INC) )
+\&         },
+\&         \*(Aqconstant\*(Aq  => sub {
+\&             debug( "A $0 logging message via process\-id: $$" . Dumper(\e%INC) ) if DEBUG
+\&         },
+\& });
+.Ve
+.PP
+Running this program produces the following output:
+.PP
+.Vb 5
+\& $> perl ifdebug\-constant
+\& Benchmark: timing 100000 iterations of constant, sub...
+\&   constant:  0 wallclock secs (\-0.00 usr +  0.00 sys = \-0.00 CPU) @ \-7205759403792793600000.00/s (n=100000)
+\&             (warning: too few iterations for a reliable count)
+\&        sub: 14 wallclock secs (13.09 usr +  0.00 sys = 13.09 CPU) @ 7639.42/s (n=100000)
+.Ve
+.PP
+The \f(CW\*(C`DEBUG\*(C'\fR constant wipes the floor with even the \f(CW$debug\fR variable,
+clocking in at minus zero seconds, and generates a "warning: too few iterations
+for a reliable count" message into the bargain.  To see what is really going
+on, and why we had too few iterations when we thought we asked for 100000, we
+can use the very useful \f(CW\*(C`B::Deparse\*(C'\fR to inspect the new code:
+.PP
+.Vb 1
+\& $> perl \-MO=Deparse ifdebug\-constant
+\&
+\& use Benchmark;
+\& use Data::Dumper;
+\& use constant (\*(AqDEBUG\*(Aq, 0);
+\& sub debug {
+\&     use warnings;
+\&     use strict \*(Aqrefs\*(Aq;
+\&     0;
+\& }
+\& use warnings;
+\& use strict \*(Aqrefs\*(Aq;
+\& timethese(100000, {\*(Aqsub\*(Aq, sub {
+\&     debug "A $0 logging message via process\-id: $$" . Dumper(\e%INC);
+\& }
+\& , \*(Aqconstant\*(Aq, sub {
+\&     0;
+\& }
+\& });
+\& ifdebug\-constant syntax OK
+.Ve
+.PP
+The output shows the \fBconstant()\fR subroutine we're testing being replaced with
+the value of the \f(CW\*(C`DEBUG\*(C'\fR constant: zero.  The line to be tested has been
+completely optimized away, and you can't get much more efficient than that.
+.SH POSTSCRIPT
+.IX Header "POSTSCRIPT"
+This document has provided several way to go about identifying hot-spots, and
+checking whether any modifications have improved the runtime of the code.
+.PP
+As a final thought, remember that it's not (at the time of writing) possible to
+produce a useful program which will run in zero or negative time and this basic
+principle can be written as: \fIuseful programs are slow\fR by their very
+definition.  It is of course possible to write a nearly instantaneous program,
+but it's not going to do very much, here's a very efficient one:
+.PP
+.Vb 1
+\& $> perl \-e 0
+.Ve
+.PP
+Optimizing that any further is a job for \f(CW\*(C`p5p\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Further reading can be found using the modules and links below.
+.SS PERLDOCS
+.IX Subsection "PERLDOCS"
+For example: \f(CW\*(C`perldoc \-f sort\*(C'\fR.
+.PP
+perlfaq4.
+.PP
+perlfork, perlfunc, perlretut, perlthrtut.
+.PP
+threads.
+.SS "MAN PAGES"
+.IX Subsection "MAN PAGES"
+\&\f(CW\*(C`time\*(C'\fR.
+.SS MODULES
+.IX Subsection "MODULES"
+It's not possible to individually showcase all the performance related code for
+Perl here, naturally, but here's a short list of modules from the CPAN which
+deserve further attention.
+.PP
+.Vb 10
+\& Apache::DProf
+\& Apache::SmallProf
+\& Benchmark
+\& DBIx::Profile
+\& Devel::AutoProfiler
+\& Devel::DProf
+\& Devel::DProfLB
+\& Devel::FastProf
+\& Devel::GraphVizProf
+\& Devel::NYTProf
+\& Devel::NYTProf::Apache
+\& Devel::Profiler
+\& Devel::Profile
+\& Devel::Profit
+\& Devel::SmallProf
+\& Devel::WxProf
+\& POE::Devel::Profiler
+\& Sort::Key
+\& Sort::Maker
+.Ve
+.SS URLS
+.IX Subsection "URLS"
+Very useful online reference material:
+.PP
+.Vb 1
+\& https://web.archive.org/web/20120515021937/http://www.ccl4.org/~nick/P/Fast_Enough/
+\&
+\& https://web.archive.org/web/20050706081718/http://www\-106.ibm.com/developerworks/library/l\-optperl.html
+\&
+\& https://perlbuzz.com/2007/11/14/bind_output_variables_in_dbi_for_speed_and_safety/
+\&
+\& http://en.wikipedia.org/wiki/Performance_analysis
+\&
+\& http://apache.perl.org/docs/1.0/guide/performance.html
+\&
+\& http://perlgolf.sourceforge.net/
+\&
+\& http://www.sysarch.com/Perl/sort_paper.html
+.Ve
+.SH AUTHOR
+.IX Header "AUTHOR"
+Richard Foley <richard.foley@rfi.net> Copyright (c) 2008
diff --git a/upstream/mageia-cauldron/man1/perlplan9.1 b/upstream/mageia-cauldron/man1/perlplan9.1
new file mode 100644
index 00000000..b4bb0a9c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlplan9.1
@@ -0,0 +1,206 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPLAN9 1"
+.TH PERLPLAN9 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlplan9 \- Plan 9\-specific documentation for Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+These are a few notes describing features peculiar to
+Plan 9 Perl. As such, it is not intended to be a replacement
+for the rest of the Perl 5 documentation (which is both 
+copious and excellent). If you have any questions to 
+which you can't find answers in these man pages, contact 
+Luther Huffman at lutherh@stratcom.com and we'll try to 
+answer them.
+.SS "Invoking Perl"
+.IX Subsection "Invoking Perl"
+Perl is invoked from the command line as described in 
+perl. Most perl scripts, however, do have a first line 
+such as "#!/usr/local/bin/perl". This is known as a shebang 
+(shell-bang) statement and tells the OS shell where to find 
+the perl interpreter. In Plan 9 Perl this statement should be 
+"#!/bin/perl" if you wish to be able to directly invoke the 
+script by its name.
+     Alternatively, you may invoke perl with the command "Perl"
+instead of "perl". This will produce Acme-friendly error
+messages of the form "filename:18".
+.PP
+Some scripts, usually identified with a *.PL extension, are 
+self-configuring and are able to correctly create their own 
+shebang path from config information located in Plan 9 
+Perl. These you won't need to be worried about.
+.SS "What's in Plan 9 Perl"
+.IX Subsection "What's in Plan 9 Perl"
+Although Plan 9 Perl currently only  provides static 
+loading, it is built with a number of useful extensions. 
+These include Opcode, FileHandle, Fcntl, and POSIX. Expect 
+to see others (and DynaLoading!) in the future.
+.SS "What's not in Plan 9 Perl"
+.IX Subsection "What's not in Plan 9 Perl"
+As mentioned previously, dynamic loading isn't currently 
+available nor is MakeMaker. Both are high-priority items.
+.SS "Perl5 Functions not currently supported in Plan 9 Perl"
+.IX Subsection "Perl5 Functions not currently supported in Plan 9 Perl"
+Some, such as \f(CW\*(C`chown\*(C'\fR and \f(CW\*(C`umask\*(C'\fR aren't provided 
+because the concept does not exist within Plan 9. Others,
+such as some of the socket-related functions, simply
+haven't been written yet. Many in the latter category 
+may be supported in the future.
+.PP
+The functions not currently implemented include:
+.PP
+.Vb 5
+\&    chown, chroot, dbmclose, dbmopen, getsockopt, 
+\&    setsockopt, recvmsg, sendmsg, getnetbyname, 
+\&    getnetbyaddr, getnetent, getprotoent, getservent, 
+\&    sethostent, setnetent, setprotoent, setservent, 
+\&    endservent, endnetent, endprotoent, umask
+.Ve
+.PP
+There may be several other functions that have undefined 
+behavior so this list shouldn't be considered complete.
+.SS "Signals in Plan 9 Perl"
+.IX Subsection "Signals in Plan 9 Perl"
+For compatibility with perl scripts written for the Unix 
+environment, Plan 9 Perl uses the POSIX signal emulation
+provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
+isn't supported. The signals provided are:
+.PP
+.Vb 4
+\&    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
+\&    SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM, 
+\&    SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
+\&    SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU
+.Ve
+.SH "COMPILING AND INSTALLING PERL ON PLAN 9"
+.IX Header "COMPILING AND INSTALLING PERL ON PLAN 9"
+WELCOME to Plan 9 Perl, brave soul!
+.PP
+.Vb 5
+\&   This is a preliminary alpha version of Plan 9 Perl. Still to be
+\&implemented are MakeMaker and DynaLoader. Many perl commands are
+\&missing or currently behave in an inscrutable manner. These gaps will,
+\&with perseverance and a modicum of luck, be remedied in the near
+\&future.To install this software:
+.Ve
+.PP
+1. Create the source directories and libraries for perl by running the
+plan9/setup.rc command (i.e., located in the plan9 subdirectory).
+Note: the setup routine assumes that you haven't dearchived these
+files into /sys/src/cmd/perl. After running setup.rc you may delete
+the copy of the source you originally detarred, as source code has now
+been installed in /sys/src/cmd/perl. If you plan on installing perl
+binaries for all architectures, run "setup.rc \-a".
+.PP
+2. After making sure that you have adequate privileges to build system
+software, from /sys/src/cmd/perl/5.00301 (adjust version
+appropriately) run:
+.PP
+.Vb 1
+\&        mk install
+.Ve
+.PP
+If you wish to install perl versions for all architectures (68020,
+mips, sparc and 386) run:
+.PP
+.Vb 1
+\&        mk installall
+.Ve
+.PP
+3. Wait. The build process will take a *long* time because perl
+bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30
+minutes to build the distribution from scratch.
+.SS "Installing Perl Documentation on Plan 9"
+.IX Subsection "Installing Perl Documentation on Plan 9"
+This perl distribution comes with a tremendous amount of
+documentation. To add these to the built-in manuals that come with
+Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately)
+run:
+.PP
+.Vb 1
+\&        mk man
+.Ve
+.PP
+To begin your reading, start with:
+.PP
+.Vb 1
+\&        man perl
+.Ve
+.PP
+This is a good introduction and will direct you towards other man
+pages that may interest you.
+.PP
+(Note: "mk man" may produce some extraneous noise. Fear not.)
+.SH BUGS
+.IX Header "BUGS"
+"As many as there are grains of sand on all the beaches of the 
+world . . ." \- Carl Sagan
+.SH "Revision date"
+.IX Header "Revision date"
+This document was revised 09\-October\-1996 for Perl 5.003_7.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Direct questions, comments, and the unlikely bug report (ahem) direct
+comments toward:
+.PP
+Luther Huffman, lutherh@stratcom.com, 
+Strategic Computer Solutions, Inc.
diff --git a/upstream/mageia-cauldron/man1/perlpod.1 b/upstream/mageia-cauldron/man1/perlpod.1
new file mode 100644
index 00000000..c608433f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpod.1
@@ -0,0 +1,831 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPOD 1"
+.TH PERLPOD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpod \- the Plain Old Documentation format
+.IX Xref "POD plain old documentation"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Pod is a simple-to-use markup language used for writing documentation
+for Perl, Perl programs, and Perl modules.
+.PP
+Translators are available for converting Pod to various formats
+like plain text, HTML, man pages, and more.
+.PP
+Pod markup consists of three basic kinds of paragraphs:
+ordinary,
+verbatim, and 
+command.
+.SS "Ordinary Paragraph"
+.IX Xref "POD, ordinary paragraph"
+.IX Subsection "Ordinary Paragraph"
+Most paragraphs in your documentation will be ordinary blocks
+of text, like this one.  You can simply type in your text without
+any markup whatsoever, and with just a blank line before and
+after.  When it gets formatted, it will undergo minimal formatting, 
+like being rewrapped, probably put into a proportionally spaced
+font, and maybe even justified.
+.PP
+You can use formatting codes in ordinary paragraphs, for \fBbold\fR,
+\&\fIitalic\fR, \f(CW\*(C`code\-style\*(C'\fR, hyperlinks, and more.  Such
+codes are explained in the "Formatting Codes"
+section, below.
+.SS "Verbatim Paragraph"
+.IX Xref "POD, verbatim paragraph verbatim"
+.IX Subsection "Verbatim Paragraph"
+Verbatim paragraphs are usually used for presenting a codeblock or
+other text which does not require any special parsing or formatting,
+and which shouldn't be wrapped.
+.PP
+A verbatim paragraph is distinguished by having its first character
+be a space or a tab.  (And commonly, all its lines begin with spaces
+and/or tabs.)  It should be reproduced exactly, with tabs assumed to
+be on 8\-column boundaries.  There are no special formatting codes,
+so you can't italicize or anything like that.  A \e means \e, and
+nothing else.
+.SS "Command Paragraph"
+.IX Xref "POD, command"
+.IX Subsection "Command Paragraph"
+A command paragraph is used for special treatment of whole chunks
+of text, usually as headings or parts of lists.
+.PP
+All command paragraphs (which are typically only one line long) start
+with "=", followed by an identifier, followed by arbitrary text that
+the command can use however it pleases.  Currently recognized commands
+are
+.PP
+.Vb 10
+\&    =pod
+\&    =head1 Heading Text
+\&    =head2 Heading Text
+\&    =head3 Heading Text
+\&    =head4 Heading Text
+\&    =head5 Heading Text
+\&    =head6 Heading Text
+\&    =over indentlevel
+\&    =item stuff
+\&    =back
+\&    =begin format
+\&    =end format
+\&    =for format text...
+\&    =encoding type
+\&    =cut
+.Ve
+.PP
+To explain them each in detail:
+.ie n .IP """=head1 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head1 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Xref "=head1 =head2 =head3 =head4 =head5 =head6 head1 head2 head3 head4 head5 head6"
+.IX Item "=head1 Heading Text"
+.PD 0
+.ie n .IP """=head2 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head2 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Item "=head2 Heading Text"
+.ie n .IP """=head3 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head3 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Item "=head3 Heading Text"
+.ie n .IP """=head4 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head4 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Item "=head4 Heading Text"
+.ie n .IP """=head5 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head5 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Item "=head5 Heading Text"
+.ie n .IP """=head6 \fIHeading Text\fR""" 4
+.el .IP "\f(CW=head6 \fR\f(CIHeading Text\fR\f(CW\fR" 4
+.IX Item "=head6 Heading Text"
+.PD
+Head1 through head6 produce headings, head1 being the highest
+level.  The text in the rest of this paragraph is the content of the
+heading.  For example:
+.Sp
+.Vb 1
+\&  =head2 Object Attributes
+.Ve
+.Sp
+The text "Object Attributes" comprises the heading there.
+The text in these heading commands can use formatting codes, as seen here:
+.Sp
+.Vb 1
+\&  =head2 Possible Values for C<$/>
+.Ve
+.Sp
+Such commands are explained in the
+"Formatting Codes" section, below.
+.Sp
+Note that \f(CW\*(C`head5\*(C'\fR and \f(CW\*(C`head6\*(C'\fR were introduced in 2020 and in
+Pod::Simple 3.41, released in October 2020, so they might not be
+supported on the Pod parser you use.
+.ie n .IP """=over \fIindentlevel\fR""" 4
+.el .IP "\f(CW=over \fR\f(CIindentlevel\fR\f(CW\fR" 4
+.IX Xref "=over =item =back over item back"
+.IX Item "=over indentlevel"
+.PD 0
+.ie n .IP """=item \fIstuff...\fR""" 4
+.el .IP "\f(CW=item \fR\f(CIstuff...\fR\f(CW\fR" 4
+.IX Item "=item stuff..."
+.ie n .IP """=back""" 4
+.el .IP \f(CW=back\fR 4
+.IX Item "=back"
+.PD
+Item, over, and back require a little more explanation:  "=over" starts
+a region specifically for the generation of a list using "=item"
+commands, or for indenting (groups of) normal paragraphs.  At the end
+of your list, use "=back" to end it.  The \fIindentlevel\fR option to
+"=over" indicates how far over to indent, generally in ems (where
+one em is the width of an "M" in the document's base font) or roughly
+comparable units; if there is no \fIindentlevel\fR option, it defaults
+to four.  (And some formatters may just ignore whatever \fIindentlevel\fR
+you provide.)  In the \fIstuff\fR in \f(CW\*(C`=item \fR\f(CIstuff...\fR\f(CW\*(C'\fR, you may
+use formatting codes, as seen here:
+.Sp
+.Vb 1
+\&  =item Using C<$|> to Control Buffering
+.Ve
+.Sp
+Such commands are explained in the
+"Formatting Codes" section, below.
+.Sp
+Note also that there are some basic rules to using "=over" ...
+"=back" regions:
+.RS 4
+.IP \(bu 4
+Don't use "=item"s outside of an "=over" ... "=back" region.
+.IP \(bu 4
+The first thing after the "=over" command should be an "=item", unless
+there aren't going to be any items at all in this "=over" ... "=back"
+region.
+.IP \(bu 4
+Don't put "=head\fIn\fR" commands inside an "=over" ... "=back" region.
+.IP \(bu 4
+And perhaps most importantly, keep the items consistent: either use
+"=item *" for all of them, to produce bullets; or use "=item 1.",
+"=item 2.", etc., to produce numbered lists; or use "=item foo",
+"=item bar", etc.\-\-namely, things that look nothing like bullets or
+numbers.  (If you have a list that contains both: 1) things that don't
+look like bullets nor numbers,  plus 2) things that do, you should
+preface the bullet\- or number-like items with \f(CW\*(C`Z<>\*(C'\fR.  See
+Z<>
+below for an example.)
+.Sp
+If you start with bullets or numbers, stick with them, as
+formatters use the first "=item" type to decide how to format the
+list.
+.RE
+.RS 4
+.RE
+.ie n .IP """=cut""" 4
+.el .IP \f(CW=cut\fR 4
+.IX Xref "=cut cut"
+.IX Item "=cut"
+To end a Pod block, use a blank line,
+then a line beginning with "=cut", and a blank
+line after it.  This lets Perl (and the Pod formatter) know that
+this is where Perl code is resuming.  (The blank line before the "=cut"
+is not technically necessary, but many older Pod processors require it.)
+.ie n .IP """=pod""" 4
+.el .IP \f(CW=pod\fR 4
+.IX Xref "=pod pod"
+.IX Item "=pod"
+The "=pod" command by itself doesn't do much of anything, but it
+signals to Perl (and Pod formatters) that a Pod block starts here.  A
+Pod block starts with \fIany\fR command paragraph, so a "=pod" command is
+usually used just when you want to start a Pod block with an ordinary
+paragraph or a verbatim paragraph.  For example:
+.Sp
+.Vb 1
+\&  =item stuff()
+\&
+\&  This function does stuff.
+\&
+\&  =cut
+\&
+\&  sub stuff {
+\&    ...
+\&  }
+\&
+\&  =pod
+\&
+\&  Remember to check its return value, as in:
+\&
+\&    stuff() || die "Couldn\*(Aqt do stuff!";
+\&
+\&  =cut
+.Ve
+.ie n .IP """=begin \fIformatname\fR""" 4
+.el .IP "\f(CW=begin \fR\f(CIformatname\fR\f(CW\fR" 4
+.IX Xref "=begin =end =for begin end for"
+.IX Item "=begin formatname"
+.PD 0
+.ie n .IP """=end \fIformatname\fR""" 4
+.el .IP "\f(CW=end \fR\f(CIformatname\fR\f(CW\fR" 4
+.IX Item "=end formatname"
+.ie n .IP """=for \fIformatname\fR \fItext...\fR""" 4
+.el .IP "\f(CW=for \fR\f(CIformatname\fR\f(CW \fR\f(CItext...\fR\f(CW\fR" 4
+.IX Item "=for formatname text..."
+.PD
+For, begin, and end will let you have regions of text/code/data that
+are not generally interpreted as normal Pod text, but are passed
+directly to particular formatters, or are otherwise special.  A
+formatter that can use that format will use the region, otherwise it
+will be completely ignored.
+.Sp
+A command "=begin \fIformatname\fR", some paragraphs, and a
+command "=end \fIformatname\fR", mean that the text/data in between
+is meant for formatters that understand the special format
+called \fIformatname\fR.  For example,
+.Sp
+.Vb 1
+\&  =begin html
+\&
+\&  <hr> <img src="thang.png">
+\&  <p> This is a raw HTML paragraph </p>
+\&
+\&  =end html
+.Ve
+.Sp
+The command "=for \fIformatname\fR \fItext...\fR"
+specifies that the remainder of just this paragraph (starting
+right after \fIformatname\fR) is in that special format.
+.Sp
+.Vb 2
+\&  =for html <hr> <img src="thang.png">
+\&  <p> This is a raw HTML paragraph </p>
+.Ve
+.Sp
+This means the same thing as the above "=begin html" ... "=end html"
+region.
+.Sp
+That is, with "=for", you can have only one paragraph's worth
+of text (i.e., the text in "=foo targetname text..."), but with
+"=begin targetname" ... "=end targetname", you can have any amount
+of stuff in between.  (Note that there still must be a blank line
+after the "=begin" command and a blank line before the "=end"
+command.)
+.Sp
+Here are some examples of how to use these:
+.Sp
+.Vb 1
+\&  =begin html
+\&
+\&  <br>Figure 1.<br><IMG SRC="figure1.png"><br>
+\&
+\&  =end html
+\&
+\&  =begin text
+\&
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    |  foo        |
+\&    |        bar  |
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&
+\&  ^^^^ Figure 1. ^^^^
+\&
+\&  =end text
+.Ve
+.Sp
+Some format names that formatters currently are known to accept
+include "roff", "man", "latex", "tex", "text", and "html".  (Some
+formatters will treat some of these as synonyms.)
+.Sp
+A format name of "comment" is common for just making notes (presumably
+to yourself) that won't appear in any formatted version of the Pod
+document:
+.Sp
+.Vb 2
+\&  =for comment
+\&  Make sure that all the available options are documented!
+.Ve
+.Sp
+Some \fIformatnames\fR will require a leading colon (as in
+\&\f(CW"=for :formatname"\fR, or
+\&\f(CW"=begin :formatname" ... "=end :formatname"\fR),
+to signal that the text is not raw data, but instead \fIis\fR Pod text
+(i.e., possibly containing formatting codes) that's just not for
+normal formatting (e.g., may not be a normal-use paragraph, but might
+be for formatting as a footnote).
+.ie n .IP """=encoding \fIencodingname\fR""" 4
+.el .IP "\f(CW=encoding \fR\f(CIencodingname\fR\f(CW\fR" 4
+.IX Xref "=encoding encoding"
+.IX Item "=encoding encodingname"
+This command is used for declaring the encoding of a document.  Most
+users won't need this; but if your encoding isn't US-ASCII,
+then put a \f(CW\*(C`=encoding \fR\f(CIencodingname\fR\f(CW\*(C'\fR command very early in the document so
+that pod formatters will know how to decode the document.  For
+\&\fIencodingname\fR, use a name recognized by the Encode::Supported
+module.  Some pod formatters may try to guess between a Latin\-1 or
+CP\-1252 versus
+UTF\-8 encoding, but they may guess wrong.  It's best to be explicit if
+you use anything besides strict ASCII.  Examples:
+.Sp
+.Vb 1
+\&  =encoding latin1
+\&
+\&  =encoding utf8
+\&
+\&  =encoding koi8\-r
+\&
+\&  =encoding ShiftJIS
+\&
+\&  =encoding big5
+.Ve
+.Sp
+\&\f(CW\*(C`=encoding\*(C'\fR affects the whole document, and must occur only once.
+.PP
+And don't forget, all commands but \f(CW\*(C`=encoding\*(C'\fR last up
+until the end of its \fIparagraph\fR, not its line.  So in the
+examples below, you can see that every command needs the blank
+line after it, to end its paragraph.  (And some older Pod translators
+may require the \f(CW\*(C`=encoding\*(C'\fR line to have a following blank line as
+well, even though it should be legal to omit.)
+.PP
+Some examples of lists include:
+.PP
+.Vb 1
+\&  =over
+\&
+\&  =item *
+\&
+\&  First item
+\&
+\&  =item *
+\&
+\&  Second item
+\&
+\&  =back
+\&
+\&  =over
+\&
+\&  =item Foo()
+\&
+\&  Description of Foo function
+\&
+\&  =item Bar()
+\&
+\&  Description of Bar function
+\&
+\&  =back
+.Ve
+.SS "Formatting Codes"
+.IX Xref "POD, formatting code formatting code POD, interior sequence interior sequence"
+.IX Subsection "Formatting Codes"
+In ordinary paragraphs and in some command paragraphs, various
+formatting codes (a.k.a. "interior sequences") can be used:
+.ie n .IP """I<text>"" \-\- italic text" 4
+.el .IP "\f(CWI<text>\fR \-\- italic text" 4
+.IX Xref "I I<> POD, formatting code, italic italic"
+.IX Item "I<text> -- italic text"
+Used for emphasis ("\f(CW\*(C`be I<careful!>\*(C'\fR") and parameters
+("\f(CW\*(C`redo I<LABEL>\*(C'\fR")
+.ie n .IP """B<text>"" \-\- bold text" 4
+.el .IP "\f(CWB<text>\fR \-\- bold text" 4
+.IX Xref "B B<> POD, formatting code, bold bold"
+.IX Item "B<text> -- bold text"
+Used for switches ("\f(CW\*(C`perl\*(Aqs B<\-n> switch\*(C'\fR"), programs
+("\f(CW\*(C`some systems provide a B<chfn> for that\*(C'\fR"),
+emphasis ("\f(CW\*(C`be B<careful!>\*(C'\fR"), and so on
+("\f(CW\*(C`and that feature is known as B<autovivification>\*(C'\fR").
+.ie n .IP """C<code>"" \-\- code text" 4
+.el .IP "\f(CWC<code>\fR \-\- code text" 4
+.IX Xref "C C<> POD, formatting code, code code"
+.IX Item "C<code> -- code text"
+Renders code in a typewriter font, or gives some other indication that
+this represents program text ("\f(CW\*(C`C<gmtime($^T)>\*(C'\fR") or some other
+form of computerese ("\f(CW\*(C`C<drwxr\-xr\-x>\*(C'\fR").
+.ie n .IP """L<name>"" \-\- a hyperlink" 4
+.el .IP "\f(CWL<name>\fR \-\- a hyperlink" 4
+.IX Xref "L L<> POD, formatting code, hyperlink hyperlink"
+.IX Item "L<name> -- a hyperlink"
+There are various syntaxes, listed below.  In the syntaxes given,
+\&\f(CW\*(C`text\*(C'\fR, \f(CW\*(C`name\*(C'\fR, and \f(CW\*(C`section\*(C'\fR cannot contain the characters
+\&'/' and '|'; and any '<' or '>' should be matched.
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`L<name>\*(C'\fR
+.Sp
+Link to a Perl manual page (e.g., \f(CW\*(C`L<Net::Ping>\*(C'\fR).  Note
+that \f(CW\*(C`name\*(C'\fR should not contain spaces.  This syntax
+is also occasionally used for references to Unix man pages, as in
+\&\f(CW\*(C`L<crontab(5)>\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`L<name/"sec">\*(C'\fR or \f(CW\*(C`L<name/sec>\*(C'\fR
+.Sp
+Link to a section in other manual page.  E.g.,
+\&\f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`L</"sec">\*(C'\fR or \f(CW\*(C`L</sec>\*(C'\fR
+.Sp
+Link to a section in this manual page.  E.g.,
+\&\f(CW\*(C`L</"Object Methods">\*(C'\fR
+.RE
+.RS 4
+.Sp
+A section is started by the named heading or item.  For
+example, \f(CW\*(C`L<perlvar/$.>\*(C'\fR or \f(CW\*(C`L<perlvar/"$.">\*(C'\fR both
+link to the section started by "\f(CW\*(C`=item $.\*(C'\fR" in perlvar.  And
+\&\f(CW\*(C`L<perlsyn/For Loops>\*(C'\fR or \f(CW\*(C`L<perlsyn/"For Loops">\*(C'\fR
+both link to the section started by "\f(CW\*(C`=head2 For Loops\*(C'\fR"
+in perlsyn.
+.Sp
+To control what text is used for display, you
+use "\f(CW\*(C`L<text|...>\*(C'\fR", as in:
+.IP \(bu 4
+\&\f(CW\*(C`L<text|name>\*(C'\fR
+.Sp
+Link this text to that manual page.  E.g.,
+\&\f(CW\*(C`L<Perl Error Messages|perldiag>\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`L<text|name/"sec">\*(C'\fR or \f(CW\*(C`L<text|name/sec>\*(C'\fR
+.Sp
+Link this text to that section in that manual page.  E.g.,
+\&\f(CW\*(C`L<postfix "if"|perlsyn/"Statement Modifiers">\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`L<text|/"sec">\*(C'\fR or \f(CW\*(C`L<text|/sec>\*(C'\fR
+or \f(CW\*(C`L<text|"sec">\*(C'\fR
+.Sp
+Link this text to that section in this manual page.  E.g.,
+\&\f(CW\*(C`L<the various attributes|/"Member Data">\*(C'\fR
+.RE
+.RS 4
+.Sp
+Or you can link to a web page:
+.IP \(bu 4
+\&\f(CW\*(C`L<scheme:...>\*(C'\fR
+.Sp
+\&\f(CW\*(C`L<text|scheme:...>\*(C'\fR
+.Sp
+Links to an absolute URL.  For example, \f(CW\*(C`L<http://www.perl.org/>\*(C'\fR or
+\&\f(CW\*(C`L<The Perl Home Page|http://www.perl.org/>\*(C'\fR.
+.RE
+.RS 4
+.RE
+.ie n .IP """E<escape>"" \-\- a character escape" 4
+.el .IP "\f(CWE<escape>\fR \-\- a character escape" 4
+.IX Xref "E E<> POD, formatting code, escape escape"
+.IX Item "E<escape> -- a character escape"
+Very similar to HTML/XML \f(CW\*(C`&\fR\f(CIfoo\fR\f(CW;\*(C'\fR "entity references":
+.RS 4
+.IP \(bu 4
+\&\f(CW\*(C`E<lt>\*(C'\fR \-\- a literal < (less than)
+.IP \(bu 4
+\&\f(CW\*(C`E<gt>\*(C'\fR \-\- a literal > (greater than)
+.IP \(bu 4
+\&\f(CW\*(C`E<verbar>\*(C'\fR \-\- a literal | (\fIver\fRtical \fIbar\fR)
+.IP \(bu 4
+\&\f(CW\*(C`E<sol>\*(C'\fR \-\- a literal / (\fIsol\fRidus)
+.Sp
+The above four are optional except in other formatting codes,
+notably \f(CW\*(C`L<...>\*(C'\fR, and when preceded by a
+capital letter.
+.IP \(bu 4
+\&\f(CW\*(C`E<htmlname>\*(C'\fR
+.Sp
+Some non-numeric HTML entity name, such as \f(CW\*(C`E<eacute>\*(C'\fR,
+meaning the same thing as \f(CW\*(C`&eacute;\*(C'\fR in HTML \-\- i.e., a lowercase
+e with an acute (/\-shaped) accent.
+.IP \(bu 4
+\&\f(CW\*(C`E<number>\*(C'\fR
+.Sp
+The ASCII/Latin\-1/Unicode character with that number.  A
+leading "0x" means that \fInumber\fR is hex, as in
+\&\f(CW\*(C`E<0x201E>\*(C'\fR.  A leading "0" means that \fInumber\fR is octal,
+as in \f(CW\*(C`E<075>\*(C'\fR.  Otherwise \fInumber\fR is interpreted as being
+in decimal, as in \f(CW\*(C`E<181>\*(C'\fR.
+.Sp
+Note that older Pod formatters might not recognize octal or
+hex numeric escapes, and that many formatters cannot reliably
+render characters above 255.  (Some formatters may even have
+to use compromised renderings of Latin\-1/CP\-1252 characters, like
+rendering \f(CW\*(C`E<eacute>\*(C'\fR as just a plain "e".)
+.RE
+.RS 4
+.RE
+.ie n .IP """F<filename>"" \-\- used for filenames" 4
+.el .IP "\f(CWF<filename>\fR \-\- used for filenames" 4
+.IX Xref "F F<> POD, formatting code, filename filename"
+.IX Item "F<filename> -- used for filenames"
+Typically displayed in italics.  Example: "\f(CW\*(C`F<.cshrc>\*(C'\fR"
+.ie n .IP """S<text>"" \-\- text contains non-breaking spaces" 4
+.el .IP "\f(CWS<text>\fR \-\- text contains non-breaking spaces" 4
+.IX Xref "S S<> POD, formatting code, non-breaking space non-breaking space"
+.IX Item "S<text> -- text contains non-breaking spaces"
+This means that the words in \fItext\fR should not be broken
+across lines.  Example: \f(CW\*(C`S<$x\ ?\ $y\ :\ $z>\*(C'\fR.
+.ie n .IP """X<topic name>"" \-\- an index entry" 4
+.el .IP "\f(CWX<topic name>\fR \-\- an index entry" 4
+.IX Xref "X X<> POD, formatting code, index entry index entry"
+.IX Item "X<topic name> -- an index entry"
+This is ignored by most formatters, but some may use it for building
+indexes.  It always renders as empty-string.
+Example: \f(CW\*(C`X<absolutizing relative URLs>\*(C'\fR
+.ie n .IP """Z<>"" \-\- a null (zero-effect) formatting code" 4
+.el .IP "\f(CWZ<>\fR \-\- a null (zero-effect) formatting code" 4
+.IX Xref "Z Z<> POD, formatting code, null null"
+.IX Item "Z<> -- a null (zero-effect) formatting code"
+This is rarely used.  It's one way to get around using an
+E<...> code sometimes.  For example, instead of
+"\f(CW\*(C`NE<lt>3\*(C'\fR" (for "N<3") you could write
+"\f(CW\*(C`NZ<><3\*(C'\fR" (the "Z<>" breaks up the "N" and
+the "<" so they can't be considered
+the part of a (fictitious) "N<...>" code).
+.Sp
+Another use is to indicate that \fIstuff\fR in \f(CW\*(C`=item Z<>\fR\f(CIstuff...\fR\f(CW\*(C'\fR
+is not to be considered to be a bullet or number.  For example,
+without the \f(CW\*(C`Z<>\*(C'\fR, the line
+.Sp
+.Vb 1
+\& =item Z<>500 Server error
+.Ve
+.Sp
+could possibly be parsed as an item in a numbered list when it isn't
+meant to be.
+.Sp
+Still another use is to maintain visual space between \f(CW\*(C`=item\*(C'\fR lines.
+If you specify
+.Sp
+.Vb 1
+\& =item foo
+\&
+\& =item bar
+.Ve
+.Sp
+it will typically get rendered as
+.Sp
+.Vb 2
+\& foo
+\& bar
+.Ve
+.Sp
+That may be what you want, but if what you really want is
+.Sp
+.Vb 1
+\& foo
+\&
+\& bar
+.Ve
+.Sp
+you can use \f(CW\*(C`Z<>\*(C'\fR to accomplish that
+.Sp
+.Vb 1
+\& =item foo
+\&
+\& Z<>
+\&
+\& =item bar
+.Ve
+.PP
+Most of the time, you will need only a single set of angle brackets to
+delimit the beginning and end of formatting codes.  However,
+sometimes you will want to put a real right angle bracket (a
+greater-than sign, '>') inside of a formatting code.  This is particularly
+common when using a formatting code to provide a different font-type for a
+snippet of code.  As with all things in Perl, there is more than
+one way to do it.  One way is to simply escape the closing bracket
+using an \f(CW\*(C`E\*(C'\fR code:
+.PP
+.Vb 1
+\&    C<$a E<lt>=E<gt> $b>
+.Ve
+.PP
+This will produce: "\f(CW\*(C`$a <=> $b\*(C'\fR"
+.PP
+A more readable, and perhaps more "plain" way is to use an alternate
+set of delimiters that doesn't require a single ">" to be escaped.
+Doubled angle brackets ("<<" and ">>") may be used \fIif and only if there is
+whitespace right after the opening delimiter and whitespace right
+before the closing delimiter!\fR  For example, the following will
+do the trick:
+.IX Xref "POD, formatting code, escaping with multiple brackets"
+.PP
+.Vb 1
+\&    C<< $a <=> $b >>
+.Ve
+.PP
+In fact, you can use as many repeated angle-brackets as you like so
+long as you have the same number of them in the opening and closing
+delimiters, and make sure that whitespace immediately follows the last
+\&'<' of the opening delimiter, and immediately precedes the first '>'
+of the closing delimiter.  (The whitespace is ignored.)  So the
+following will also work:
+.IX Xref "POD, formatting code, escaping with multiple brackets"
+.PP
+.Vb 2
+\&    C<<< $a <=> $b >>>
+\&    C<<<<  $a <=> $b     >>>>
+.Ve
+.PP
+And they all mean exactly the same as this:
+.PP
+.Vb 1
+\&    C<$a E<lt>=E<gt> $b>
+.Ve
+.PP
+The multiple-bracket form does not affect the interpretation of the contents of
+the formatting code, only how it must end.  That means that the examples above
+are also exactly the same as this:
+.PP
+.Vb 1
+\&    C<< $a E<lt>=E<gt> $b >>
+.Ve
+.PP
+As a further example, this means that if you wanted to put these bits of
+code in \f(CW\*(C`C\*(C'\fR (code) style:
+.PP
+.Vb 2
+\&    open(X, ">>thing.dat") || die $!
+\&    $foo\->bar();
+.Ve
+.PP
+you could do it like so:
+.PP
+.Vb 2
+\&    C<<< open(X, ">>thing.dat") || die $! >>>
+\&    C<< $foo\->bar(); >>
+.Ve
+.PP
+which is presumably easier to read than the old way:
+.PP
+.Vb 2
+\&    C<open(X, "E<gt>E<gt>thing.dat") || die $!>
+\&    C<$foo\-E<gt>bar();>
+.Ve
+.PP
+This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
+and any other pod2xxx or Pod::Xxxx translators that use
+Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
+.SS "The Intent"
+.IX Xref "POD, intent of"
+.IX Subsection "The Intent"
+The intent is simplicity of use, not power of expression.  Paragraphs
+look like paragraphs (block format), so that they stand out
+visually, and so that I could run them through \f(CW\*(C`fmt\*(C'\fR easily to reformat
+them (that's F7 in my version of \fBvi\fR, or Esc Q in my version of
+\&\fBemacs\fR).  I wanted the translator to always leave the \f(CW\*(C`\*(Aq\*(C'\fR and \f(CW\*(C`\`\*(C'\fR and
+\&\f(CW\*(C`"\*(C'\fR quotes alone, in verbatim mode, so I could slurp in a
+working program, shift it over four spaces, and have it print out, er,
+verbatim.  And presumably in a monospace font.
+.PP
+The Pod format is not necessarily sufficient for writing a book.  Pod
+is just meant to be an idiot-proof common source for nroff, HTML,
+TeX, and other markup languages, as used for online
+documentation.  Translators exist for \fBpod2text\fR, \fBpod2html\fR,
+\&\fBpod2man\fR (that's for \fBnroff\fR\|(1) and \fBtroff\fR\|(1)), \fBpod2latex\fR, and
+\&\fBpod2fm\fR.  Various others are available in CPAN.
+.SS "Embedding Pods in Perl Modules"
+.IX Xref "POD, embedding"
+.IX Subsection "Embedding Pods in Perl Modules"
+You can embed Pod documentation in your Perl modules and scripts.  Start
+your documentation with an empty line, a "=head1" command at the
+beginning, and end it with a "=cut" command and an empty line.  The
+\&\fBperl\fR executable will ignore the Pod text.  You can place a Pod
+statement where \fBperl\fR expects the beginning of a new statement, but
+not within a statement, as that would result in an error.  See any of
+the supplied library modules for examples.
+.PP
+If you're going to put your Pod at the end of the file, and you're using
+an \f(CW\*(C`_\|_END_\|_\*(C'\fR or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR cut mark, make sure to put an empty line there
+before the first Pod command.
+.PP
+.Vb 1
+\&  _\|_END_\|_
+\&
+\&  =head1 NAME
+\&
+\&  Time::Local \- efficiently compute time from local and GMT time
+.Ve
+.PP
+Without that empty line before the "=head1", many translators wouldn't
+have recognized the "=head1" as starting a Pod block.
+.SS "Hints for Writing Pod"
+.IX Subsection "Hints for Writing Pod"
+.IP \(bu 4
+
+.IX Xref "podchecker POD, validating"
+.Sp
+The \fBpodchecker\fR command is provided for checking Pod syntax for errors
+and warnings.  For example, it checks for completely blank lines in
+Pod blocks and for unknown commands and formatting codes.  You should
+still also pass your document through one or more translators and proofread
+the result, or print out the result and proofread that.  Some of the
+problems found may be bugs in the translators, which you may or may not
+wish to work around.
+.IP \(bu 4
+If you're more familiar with writing in HTML than with writing in Pod, you
+can try your hand at writing documentation in simple HTML, and converting
+it to Pod with the experimental Pod::HTML2Pod module,
+(available in CPAN), and looking at the resulting code.  The experimental
+Pod::PXML module in CPAN might also be useful.
+.IP \(bu 4
+Many older Pod translators require the lines before every Pod
+command and after every Pod command (including "=cut"!) to be a blank
+line.  Having something like this:
+.Sp
+.Vb 2
+\& # \- \- \- \- \- \- \- \- \- \- \- \-
+\& =item $firecracker\->boom()
+\&
+\& This noisily detonates the firecracker object.
+\& =cut
+\& sub boom {
+\& ...
+.Ve
+.Sp
+\&...will make such Pod translators completely fail to see the Pod block
+at all.
+.Sp
+Instead, have it like this:
+.Sp
+.Vb 1
+\& # \- \- \- \- \- \- \- \- \- \- \- \-
+\&
+\& =item $firecracker\->boom()
+\&
+\& This noisily detonates the firecracker object.
+\&
+\& =cut
+\&
+\& sub boom {
+\& ...
+.Ve
+.IP \(bu 4
+Some older Pod translators require paragraphs (including command
+paragraphs like "=head2 Functions") to be separated by \fIcompletely\fR
+empty lines.  If you have an apparently empty line with some spaces
+on it, this might not count as a separator for those translators, and
+that could cause odd formatting.
+.IP \(bu 4
+Older translators might add wording around an L<> link, so that
+\&\f(CW\*(C`L<Foo::Bar>\*(C'\fR may become "the Foo::Bar manpage", for example.
+So you shouldn't write things like \f(CW\*(C`the L<foo>
+documentation\*(C'\fR, if you want the translated document to read sensibly.
+Instead, write \f(CW\*(C`the L<Foo::Bar|Foo::Bar> documentation\*(C'\fR or
+\&\f(CW\*(C`L<the Foo::Bar documentation|Foo::Bar>\*(C'\fR, to control how the
+link comes out.
+.IP \(bu 4
+Going past the 70th column in a verbatim block might be ungracefully
+wrapped by some formatters.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlpodspec, "PODs: Embedded Documentation" in perlsyn,
+perlnewmod, perldoc, pod2html, pod2man, podchecker.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall, Sean M. Burke
diff --git a/upstream/mageia-cauldron/man1/perlpodspec.1 b/upstream/mageia-cauldron/man1/perlpodspec.1
new file mode 100644
index 00000000..e8315446
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpodspec.1
@@ -0,0 +1,1884 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPODSPEC 1"
+.TH PERLPODSPEC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpodspec \- Plain Old Documentation: format specification and notes
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is detailed notes on the Pod markup language.  Most
+people will only have to read perlpod to know how to write
+in Pod, but this document may answer some incidental questions to do
+with parsing and rendering Pod.
+.PP
+In this document, "must" / "must not", "should" /
+"should not", and "may" have their conventional (cf. RFC 2119)
+meanings: "X must do Y" means that if X doesn't do Y, it's against
+this specification, and should really be fixed.  "X should do Y"
+means that it's recommended, but X may fail to do Y, if there's a
+good reason.  "X may do Y" is merely a note that X can do Y at
+will (although it is up to the reader to detect any connotation of
+"and I think it would be \fInice\fR if X did Y" versus "it wouldn't
+really \fIbother\fR me if X did Y").
+.PP
+Notably, when I say "the parser should do Y", the
+parser may fail to do Y, if the calling application explicitly
+requests that the parser \fInot\fR do Y.  I often phrase this as
+"the parser should, by default, do Y."  This doesn't \fIrequire\fR
+the parser to provide an option for turning off whatever
+feature Y is (like expanding tabs in verbatim paragraphs), although
+it implicates that such an option \fImay\fR be provided.
+.SH "Pod Definitions"
+.IX Header "Pod Definitions"
+Pod is embedded in files, typically Perl source files, although you
+can write a file that's nothing but Pod.
+.PP
+A \fBline\fR in a file consists of zero or more non-newline characters,
+terminated by either a newline or the end of the file.
+.PP
+A \fBnewline sequence\fR is usually a platform-dependent concept, but
+Pod parsers should understand it to mean any of CR (ASCII 13), LF
+(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in
+addition to any other system-specific meaning.  The first CR/CRLF/LF
+sequence in the file may be used as the basis for identifying the
+newline sequence for parsing the rest of the file.
+.PP
+A \fBblank line\fR is a line consisting entirely of zero or more spaces
+(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file.
+A \fBnon-blank line\fR is a line containing one or more characters other
+than space or tab (and terminated by a newline or end-of-file).
+.PP
+(\fINote:\fR Many older Pod parsers did not accept a line consisting of
+spaces/tabs and then a newline as a blank line. The only lines they
+considered blank were lines consisting of \fIno characters at all\fR,
+terminated by a newline.)
+.PP
+\&\fBWhitespace\fR is used in this document as a blanket term for spaces,
+tabs, and newline sequences.  (By itself, this term usually refers
+to literal whitespace.  That is, sequences of whitespace characters
+in Pod source, as opposed to "E<32>", which is a formatting
+code that \fIdenotes\fR a whitespace character.)
+.PP
+A \fBPod parser\fR is a module meant for parsing Pod (regardless of
+whether this involves calling callbacks or building a parse tree or
+directly formatting it).  A \fBPod formatter\fR (or \fBPod translator\fR)
+is a module or program that converts Pod to some other format (HTML,
+plaintext, TeX, PostScript, RTF).  A \fBPod processor\fR might be a
+formatter or translator, or might be a program that does something
+else with the Pod (like counting words, scanning for index points,
+etc.).
+.PP
+Pod content is contained in \fBPod blocks\fR.  A Pod block starts with a
+line that matches \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR, and continues up to the next line
+that matches \f(CW\*(C`m/\eA=cut/\*(C'\fR or up to the end of the file if there is
+no \f(CW\*(C`m/\eA=cut/\*(C'\fR line.
+.PP
+Note that a parser is not expected to distinguish between something that
+looks like pod, but is in a quoted string, such as a here document.
+.PP
+Within a Pod block, there are \fBPod paragraphs\fR.  A Pod paragraph
+consists of non-blank lines of text, separated by one or more blank
+lines.
+.PP
+For purposes of Pod processing, there are four types of paragraphs in
+a Pod block:
+.IP \(bu 4
+A command paragraph (also called a "directive").  The first line of
+this paragraph must match \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR.  Command paragraphs are
+typically one line, as in:
+.Sp
+.Vb 1
+\&  =head1 NOTES
+\&
+\&  =item *
+.Ve
+.Sp
+But they may span several (non-blank) lines:
+.Sp
+.Vb 3
+\&  =for comment
+\&  Hm, I wonder what it would look like if
+\&  you tried to write a BNF for Pod from this.
+\&
+\&  =head3 Dr. Strangelove, or: How I Learned to
+\&  Stop Worrying and Love the Bomb
+.Ve
+.Sp
+\&\fISome\fR command paragraphs allow formatting codes in their content
+(i.e., after the part that matches \f(CW\*(C`m/\eA=[a\-zA\-Z]\eS*\es*/\*(C'\fR), as in:
+.Sp
+.Vb 1
+\&  =head1 Did You Remember to C<use strict;>?
+.Ve
+.Sp
+In other words, the Pod processing handler for "head1" will apply the
+same processing to "Did You Remember to C<use strict;>?" that it
+would to an ordinary paragraph (i.e., formatting codes like
+"C<...>") are parsed and presumably formatted appropriately, and
+whitespace in the form of literal spaces and/or tabs is not
+significant.
+.IP \(bu 4
+A \fBverbatim paragraph\fR.  The first line of this paragraph must be a
+literal space or tab, and this paragraph must not be inside a "=begin
+\&\fIidentifier\fR", ... "=end \fIidentifier\fR" sequence unless
+"\fIidentifier\fR" begins with a colon (":").  That is, if a paragraph
+starts with a literal space or tab, but \fIis\fR inside a
+"=begin \fIidentifier\fR", ... "=end \fIidentifier\fR" region, then it's
+a data paragraph, unless "\fIidentifier\fR" begins with a colon.
+.Sp
+Whitespace \fIis\fR significant in verbatim paragraphs (although, in
+processing, tabs are probably expanded).
+.IP \(bu 4
+An \fBordinary paragraph\fR.  A paragraph is an ordinary paragraph
+if its first line matches neither \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR nor
+\&\f(CW\*(C`m/\eA[ \et]/\*(C'\fR, \fIand\fR if it's not inside a "=begin \fIidentifier\fR",
+\&... "=end \fIidentifier\fR" sequence unless "\fIidentifier\fR" begins with
+a colon (":").
+.IP \(bu 4
+A \fBdata paragraph\fR.  This is a paragraph that \fIis\fR inside a "=begin
+\&\fIidentifier\fR" ... "=end \fIidentifier\fR" sequence where
+"\fIidentifier\fR" does \fInot\fR begin with a literal colon (":").  In
+some sense, a data paragraph is not part of Pod at all (i.e.,
+effectively it's "out-of-band"), since it's not subject to most kinds
+of Pod parsing; but it is specified here, since Pod
+parsers need to be able to call an event for it, or store it in some
+form in a parse tree, or at least just parse \fIaround\fR it.
+.PP
+For example: consider the following paragraphs:
+.PP
+.Vb 1
+\&  # <\- that\*(Aqs the 0th column
+\&
+\&  =head1 Foo
+\&
+\&  Stuff
+\&
+\&    $foo\->bar
+\&
+\&  =cut
+.Ve
+.PP
+Here, "=head1 Foo" and "=cut" are command paragraphs because the first
+line of each matches \f(CW\*(C`m/\eA=[a\-zA\-Z]/\*(C'\fR.  "\fI[space][space]\fR\f(CW$foo\fR\->bar"
+is a verbatim paragraph, because its first line starts with a literal
+whitespace character (and there's no "=begin"..."=end" region around).
+.PP
+The "=begin \fIidentifier\fR" ... "=end \fIidentifier\fR" commands stop
+paragraphs that they surround from being parsed as ordinary or verbatim
+paragraphs, if \fIidentifier\fR doesn't begin with a colon.  This
+is discussed in detail in the section
+"About Data Paragraphs and "=begin/=end" Regions".
+.SH "Pod Commands"
+.IX Header "Pod Commands"
+This section is intended to supplement and clarify the discussion in
+"Command Paragraph" in perlpod.  These are the currently recognized
+Pod commands:
+.IP """=head1"", ""=head2"", ""=head3"", ""=head4"", ""=head5"", ""=head6""" 4
+.IX Item """=head1"", ""=head2"", ""=head3"", ""=head4"", ""=head5"", ""=head6"""
+This command indicates that the text in the remainder of the paragraph
+is a heading.  That text may contain formatting codes.  Examples:
+.Sp
+.Vb 1
+\&  =head1 Object Attributes
+\&
+\&  =head3 What B<Not> to Do!
+.Ve
+.Sp
+Both \f(CW\*(C`=head5\*(C'\fR and \f(CW\*(C`=head6\*(C'\fR were added in 2020 and might not be
+supported on all Pod parsers. Pod::Simple 3.41 was released on October
+2020 and supports both of these providing support for all
+Pod::Simple\-based Pod parsers.
+.IP """=pod""" 4
+.IX Item """=pod"""
+This command indicates that this paragraph begins a Pod block.  (If we
+are already in the middle of a Pod block, this command has no effect at
+all.)  If there is any text in this command paragraph after "=pod",
+it must be ignored.  Examples:
+.Sp
+.Vb 1
+\&  =pod
+\&
+\&  This is a plain Pod paragraph.
+\&
+\&  =pod This text is ignored.
+.Ve
+.IP """=cut""" 4
+.IX Item """=cut"""
+This command indicates that this line is the end of this previously
+started Pod block.  If there is any text after "=cut" on the line, it must be
+ignored.  Examples:
+.Sp
+.Vb 1
+\&  =cut
+\&
+\&  =cut The documentation ends here.
+\&
+\&  =cut
+\&  # This is the first line of program text.
+\&  sub foo { # This is the second.
+.Ve
+.Sp
+It is an error to try to \fIstart\fR a Pod block with a "=cut" command.  In
+that case, the Pod processor must halt parsing of the input file, and
+must by default emit a warning.
+.IP """=over""" 4
+.IX Item """=over"""
+This command indicates that this is the start of a list/indent
+region.  If there is any text following the "=over", it must consist
+of only a nonzero positive numeral.  The semantics of this numeral is
+explained in the "About =over...=back Regions" section, further
+below.  Formatting codes are not expanded.  Examples:
+.Sp
+.Vb 1
+\&  =over 3
+\&
+\&  =over 3.5
+\&
+\&  =over
+.Ve
+.IP """=item""" 4
+.IX Item """=item"""
+This command indicates that an item in a list begins here.  Formatting
+codes are processed.  The semantics of the (optional) text in the
+remainder of this paragraph are
+explained in the "About =over...=back Regions" section, further
+below.  Examples:
+.Sp
+.Vb 1
+\&  =item
+\&
+\&  =item *
+\&
+\&  =item      *    
+\&
+\&  =item 14
+\&
+\&  =item   3.
+\&
+\&  =item C<< $thing\->stuff(I<dodad>) >>
+\&
+\&  =item For transporting us beyond seas to be tried for pretended
+\&  offenses
+\&
+\&  =item He is at this time transporting large armies of foreign
+\&  mercenaries to complete the works of death, desolation and
+\&  tyranny, already begun with circumstances of cruelty and perfidy
+\&  scarcely paralleled in the most barbarous ages, and totally
+\&  unworthy the head of a civilized nation.
+.Ve
+.IP """=back""" 4
+.IX Item """=back"""
+This command indicates that this is the end of the region begun
+by the most recent "=over" command.  It permits no text after the
+"=back" command.
+.IP """=begin formatname""" 4
+.IX Item """=begin formatname"""
+.PD 0
+.IP """=begin formatname parameter""" 4
+.IX Item """=begin formatname parameter"""
+.PD
+This marks the following paragraphs (until the matching "=end
+formatname") as being for some special kind of processing.  Unless
+"formatname" begins with a colon, the contained non-command
+paragraphs are data paragraphs.  But if "formatname" \fIdoes\fR begin
+with a colon, then non-command paragraphs are ordinary paragraphs
+or data paragraphs.  This is discussed in detail in the section
+"About Data Paragraphs and "=begin/=end" Regions".
+.Sp
+It is advised that formatnames match the regexp
+\&\f(CW\*(C`m/\eA:?[\-a\-zA\-Z0\-9_]+\ez/\*(C'\fR.  Everything following whitespace after the
+formatname is a parameter that may be used by the formatter when dealing
+with this region.  This parameter must not be repeated in the "=end"
+paragraph.  Implementors should anticipate future expansion in the
+semantics and syntax of the first parameter to "=begin"/"=end"/"=for".
+.IP """=end formatname""" 4
+.IX Item """=end formatname"""
+This marks the end of the region opened by the matching
+"=begin formatname" region.  If "formatname" is not the formatname
+of the most recent open "=begin formatname" region, then this
+is an error, and must generate an error message.  This
+is discussed in detail in the section
+"About Data Paragraphs and "=begin/=end" Regions".
+.IP """=for formatname text...""" 4
+.IX Item """=for formatname text..."""
+This is synonymous with:
+.Sp
+.Vb 1
+\&     =begin formatname
+\&
+\&     text...
+\&
+\&     =end formatname
+.Ve
+.Sp
+That is, it creates a region consisting of a single paragraph; that
+paragraph is to be treated as a normal paragraph if "formatname"
+begins with a ":"; if "formatname" \fIdoesn't\fR begin with a colon,
+then "text..." will constitute a data paragraph.  There is no way
+to use "=for formatname text..." to express "text..." as a verbatim
+paragraph.
+.IP """=encoding encodingname""" 4
+.IX Item """=encoding encodingname"""
+This command, which should occur early in the document (at least
+before any non-US-ASCII data!), declares that this document is
+encoded in the encoding \fIencodingname\fR, which must be
+an encoding name that Encode recognizes.  (Encode's list
+of supported encodings, in Encode::Supported, is useful here.)
+If the Pod parser cannot decode the declared encoding, it 
+should emit a warning and may abort parsing the document
+altogether.
+.Sp
+A document having more than one "=encoding" line should be
+considered an error.  Pod processors may silently tolerate this if
+the not-first "=encoding" lines are just duplicates of the
+first one (e.g., if there's a "=encoding utf8" line, and later on
+another "=encoding utf8" line).  But Pod processors should complain if
+there are contradictory "=encoding" lines in the same document
+(e.g., if there is a "=encoding utf8" early in the document and
+"=encoding big5" later).  Pod processors that recognize BOMs
+may also complain if they see an "=encoding" line
+that contradicts the BOM (e.g., if a document with a UTF\-16LE
+BOM has an "=encoding shiftjis" line).
+.PP
+If a Pod processor sees any command other than the ones listed
+above (like "=head", or "=haed1", or "=stuff", or "=cuttlefish",
+or "=w123"), that processor must by default treat this as an
+error.  It must not process the paragraph beginning with that
+command, must by default warn of this as an error, and may
+abort the parse.  A Pod parser may allow a way for particular
+applications to add to the above list of known commands, and to
+stipulate, for each additional command, whether formatting
+codes should be processed.
+.PP
+Future versions of this specification may add additional
+commands.
+.SH "Pod Formatting Codes"
+.IX Header "Pod Formatting Codes"
+(Note that in previous drafts of this document and of perlpod,
+formatting codes were referred to as "interior sequences", and
+this term may still be found in the documentation for Pod parsers,
+and in error messages from Pod processors.)
+.PP
+There are two syntaxes for formatting codes:
+.IP \(bu 4
+A formatting code starts with a capital letter (just US-ASCII [A\-Z])
+followed by a "<", any number of characters, and ending with the first
+matching ">".  Examples:
+.Sp
+.Vb 1
+\&    That\*(Aqs what I<you> think!
+\&
+\&    What\*(Aqs C<CORE::dump()> for?
+\&
+\&    X<C<chmod> and C<unlink()> Under Different Operating Systems>
+.Ve
+.IP \(bu 4
+A formatting code starts with a capital letter (just US-ASCII [A\-Z])
+followed by two or more "<"'s, one or more whitespace characters,
+any number of characters, one or more whitespace characters,
+and ending with the first matching sequence of two or more ">"'s, where
+the number of ">"'s equals the number of "<"'s in the opening of this
+formatting code.  Examples:
+.Sp
+.Vb 1
+\&    That\*(Aqs what I<< you >> think!
+\&
+\&    C<<< open(X, ">>thing.dat") || die $! >>>
+\&
+\&    B<< $foo\->bar(); >>
+.Ve
+.Sp
+With this syntax, the whitespace character(s) after the "C<<<"
+and before the ">>>" (or whatever letter) are \fInot\fR renderable. They
+do not signify whitespace, are merely part of the formatting codes
+themselves.  That is, these are all synonymous:
+.Sp
+.Vb 7
+\&    C<thing>
+\&    C<< thing >>
+\&    C<<           thing     >>
+\&    C<<<   thing >>>
+\&    C<<<<
+\&    thing
+\&               >>>>
+.Ve
+.Sp
+and so on.
+.Sp
+Finally, the multiple-angle-bracket form does \fInot\fR alter the interpretation
+of nested formatting codes, meaning that the following four example lines are
+identical in meaning:
+.Sp
+.Vb 1
+\&  B<example: C<$a E<lt>=E<gt> $b>>
+\&
+\&  B<example: C<< $a <=> $b >>>
+\&
+\&  B<example: C<< $a E<lt>=E<gt> $b >>>
+\&
+\&  B<<< example: C<< $a E<lt>=E<gt> $b >> >>>
+.Ve
+.PP
+In parsing Pod, a notably tricky part is the correct parsing of
+(potentially nested!) formatting codes.  Implementors should
+consult the code in the \f(CW\*(C`parse_text\*(C'\fR routine in Pod::Parser as an
+example of a correct implementation.
+.ie n .IP """I<text>"" \-\- italic text" 4
+.el .IP "\f(CWI<text>\fR \-\- italic text" 4
+.IX Item "I<text> -- italic text"
+See the brief discussion in "Formatting Codes" in perlpod.
+.ie n .IP """B<text>"" \-\- bold text" 4
+.el .IP "\f(CWB<text>\fR \-\- bold text" 4
+.IX Item "B<text> -- bold text"
+See the brief discussion in "Formatting Codes" in perlpod.
+.ie n .IP """C<code>"" \-\- code text" 4
+.el .IP "\f(CWC<code>\fR \-\- code text" 4
+.IX Item "C<code> -- code text"
+See the brief discussion in "Formatting Codes" in perlpod.
+.ie n .IP """F<filename>"" \-\- style for filenames" 4
+.el .IP "\f(CWF<filename>\fR \-\- style for filenames" 4
+.IX Item "F<filename> -- style for filenames"
+See the brief discussion in "Formatting Codes" in perlpod.
+.ie n .IP """X<topic name>"" \-\- an index entry" 4
+.el .IP "\f(CWX<topic name>\fR \-\- an index entry" 4
+.IX Item "X<topic name> -- an index entry"
+See the brief discussion in "Formatting Codes" in perlpod.
+.Sp
+This code is unusual in that most formatters completely discard
+this code and its content.  Other formatters will render it with
+invisible codes that can be used in building an index of
+the current document.
+.ie n .IP """Z<>"" \-\- a null (zero-effect) formatting code" 4
+.el .IP "\f(CWZ<>\fR \-\- a null (zero-effect) formatting code" 4
+.IX Item "Z<> -- a null (zero-effect) formatting code"
+Discussed briefly in "Formatting Codes" in perlpod.
+.Sp
+This code is unusual in that it should have no content.  That is,
+a processor may complain if it sees \f(CW\*(C`Z<potatoes>\*(C'\fR.  Whether
+or not it complains, the \fIpotatoes\fR text should ignored.
+.ie n .IP """L<name>"" \-\- a hyperlink" 4
+.el .IP "\f(CWL<name>\fR \-\- a hyperlink" 4
+.IX Item "L<name> -- a hyperlink"
+The complicated syntaxes of this code are discussed at length in
+"Formatting Codes" in perlpod, and implementation details are
+discussed below, in "About L<...> Codes".  Parsing the
+contents of L<content> is tricky.  Notably, the content has to be
+checked for whether it looks like a URL, or whether it has to be split
+on literal "|" and/or "/" (in the right order!), and so on,
+\&\fIbefore\fR E<...> codes are resolved.
+.ie n .IP """E<escape>"" \-\- a character escape" 4
+.el .IP "\f(CWE<escape>\fR \-\- a character escape" 4
+.IX Item "E<escape> -- a character escape"
+See "Formatting Codes" in perlpod, and several points in
+"Notes on Implementing Pod Processors".
+.ie n .IP """S<text>"" \-\- text contains non-breaking spaces" 4
+.el .IP "\f(CWS<text>\fR \-\- text contains non-breaking spaces" 4
+.IX Item "S<text> -- text contains non-breaking spaces"
+This formatting code is syntactically simple, but semantically
+complex.  What it means is that each space in the printable
+content of this code signifies a non-breaking space.
+.Sp
+Consider:
+.Sp
+.Vb 1
+\&    C<$x ? $y    :  $z>
+\&
+\&    S<C<$x ? $y     :  $z>>
+.Ve
+.Sp
+Both signify the monospace (c[ode] style) text consisting of
+"$x", one space, "?", one space, ":", one space, "$z".  The
+difference is that in the latter, with the S code, those spaces
+are not "normal" spaces, but instead are non-breaking spaces.
+.PP
+If a Pod processor sees any formatting code other than the ones
+listed above (as in "N<...>", or "Q<...>", etc.), that
+processor must by default treat this as an error.
+A Pod parser may allow a way for particular
+applications to add to the above list of known formatting codes;
+a Pod parser might even allow a way to stipulate, for each additional
+command, whether it requires some form of special processing, as
+L<...> does.
+.PP
+Future versions of this specification may add additional
+formatting codes.
+.PP
+Historical note:  A few older Pod processors would not see a ">" as
+closing a "C<" code, if the ">" was immediately preceded by
+a "\-".  This was so that this:
+.PP
+.Vb 1
+\&    C<$foo\->bar>
+.Ve
+.PP
+would parse as equivalent to this:
+.PP
+.Vb 1
+\&    C<$foo\-E<gt>bar>
+.Ve
+.PP
+instead of as equivalent to a "C" formatting code containing 
+only "$foo\-", and then a "bar>" outside the "C" formatting code.  This
+problem has since been solved by the addition of syntaxes like this:
+.PP
+.Vb 1
+\&    C<< $foo\->bar >>
+.Ve
+.PP
+Compliant parsers must not treat "\->" as special.
+.PP
+Formatting codes absolutely cannot span paragraphs.  If a code is
+opened in one paragraph, and no closing code is found by the end of
+that paragraph, the Pod parser must close that formatting code,
+and should complain (as in "Unterminated I code in the paragraph
+starting at line 123: 'Time objects are not...'").  So these
+two paragraphs:
+.PP
+.Vb 1
+\&  I<I told you not to do this!
+\&
+\&  Don\*(Aqt make me say it again!>
+.Ve
+.PP
+\&...must \fInot\fR be parsed as two paragraphs in italics (with the I
+code starting in one paragraph and starting in another.)  Instead,
+the first paragraph should generate a warning, but that aside, the
+above code must parse as if it were:
+.PP
+.Vb 1
+\&  I<I told you not to do this!>
+\&
+\&  Don\*(Aqt make me say it again!E<gt>
+.Ve
+.PP
+(In SGMLish jargon, all Pod commands are like block-level
+elements, whereas all Pod formatting codes are like inline-level
+elements.)
+.SH "Notes on Implementing Pod Processors"
+.IX Header "Notes on Implementing Pod Processors"
+The following is a long section of miscellaneous requirements
+and suggestions to do with Pod processing.
+.IP \(bu 4
+Pod formatters should tolerate lines in verbatim blocks that are of
+any length, even if that means having to break them (possibly several
+times, for very long lines) to avoid text running off the side of the
+page.  Pod formatters may warn of such line-breaking.  Such warnings
+are particularly appropriate for lines are over 100 characters long, which
+are usually not intentional.
+.IP \(bu 4
+Pod parsers must recognize \fIall\fR of the three well-known newline
+formats: CR, LF, and CRLF.  See perlport.
+.IP \(bu 4
+Pod parsers should accept input lines that are of any length.
+.IP \(bu 4
+Since Perl recognizes a Unicode Byte Order Mark at the start of files
+as signaling that the file is Unicode encoded as in UTF\-16 (whether
+big-endian or little-endian) or UTF\-8, Pod parsers should do the
+same.  Otherwise, the character encoding should be understood as
+being UTF\-8 if the first highbit byte sequence in the file seems
+valid as a UTF\-8 sequence, or otherwise as CP\-1252 (earlier versions of
+this specification used Latin\-1 instead of CP\-1252).
+.Sp
+Future versions of this specification may specify
+how Pod can accept other encodings.  Presumably treatment of other
+encodings in Pod parsing would be as in XML parsing: whatever the
+encoding declared by a particular Pod file, content is to be
+stored in memory as Unicode characters.
+.IP \(bu 4
+The well known Unicode Byte Order Marks are as follows:  if the
+file begins with the two literal byte values 0xFE 0xFF, this is
+the BOM for big-endian UTF\-16.  If the file begins with the two
+literal byte value 0xFF 0xFE, this is the BOM for little-endian
+UTF\-16.  On an ASCII platform, if the file begins with the three literal
+byte values
+0xEF 0xBB 0xBF, this is the BOM for UTF\-8.
+A mechanism portable to EBCDIC platforms is to:
+.Sp
+.Vb 2
+\&  my $utf8_bom = "\ex{FEFF}";
+\&  utf8::encode($utf8_bom);
+.Ve
+.IP \(bu 4
+A naive, but often sufficient heuristic on ASCII platforms, for testing
+the first highbit
+byte-sequence in a BOM-less file (whether in code or in Pod!), to see
+whether that sequence is valid as UTF\-8 (RFC 2279) is to check whether
+that the first byte in the sequence is in the range 0xC2 \- 0xFD
+\&\fIand\fR whether the next byte is in the range
+0x80 \- 0xBF.  If so, the parser may conclude that this file is in
+UTF\-8, and all highbit sequences in the file should be assumed to
+be UTF\-8.  Otherwise the parser should treat the file as being
+in CP\-1252.  (A better check, and which works on EBCDIC platforms as
+well, is to pass a copy of the sequence to
+\&\fButf8::decode()\fR which performs a full validity check on the
+sequence and returns TRUE if it is valid UTF\-8, FALSE otherwise.  This
+function is always pre-loaded, is fast because it is written in C, and
+will only get called at most once, so you don't need to avoid it out of
+performance concerns.)
+In the unlikely circumstance that the first highbit
+sequence in a truly non\-UTF\-8 file happens to appear to be UTF\-8, one
+can cater to our heuristic (as well as any more intelligent heuristic)
+by prefacing that line with a comment line containing a highbit
+sequence that is clearly \fInot\fR valid as UTF\-8.  A line consisting
+of simply "#", an e\-acute, and any non-highbit byte,
+is sufficient to establish this file's encoding.
+.IP \(bu 4
+Pod processors must treat a "=for [label] [content...]" paragraph as
+meaning the same thing as a "=begin [label]" paragraph, content, and
+an "=end [label]" paragraph.  (The parser may conflate these two
+constructs, or may leave them distinct, in the expectation that the
+formatter will nevertheless treat them the same.)
+.IP \(bu 4
+When rendering Pod to a format that allows comments (i.e., to nearly
+any format other than plaintext), a Pod formatter must insert comment
+text identifying its name and version number, and the name and
+version numbers of any modules it might be using to process the Pod.
+Minimal examples:
+.Sp
+.Vb 1
+\& %% POD::Pod2PS v3.14159, using POD::Parser v1.92
+\&
+\& <!\-\- Pod::HTML v3.14159, using POD::Parser v1.92 \-\->
+\&
+\& {\edoccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
+\&
+\& .\e" Pod::Man version 3.14159, using POD::Parser version 1.92
+.Ve
+.Sp
+Formatters may also insert additional comments, including: the
+release date of the Pod formatter program, the contact address for
+the author(s) of the formatter, the current time, the name of input
+file, the formatting options in effect, version of Perl used, etc.
+.Sp
+Formatters may also choose to note errors/warnings as comments,
+besides or instead of emitting them otherwise (as in messages to
+STDERR, or \f(CW\*(C`die\*(C'\fRing).
+.IP \(bu 4
+Pod parsers \fImay\fR emit warnings or error messages ("Unknown E code
+E<zslig>!") to STDERR (whether through printing to STDERR, or
+\&\f(CW\*(C`warn\*(C'\fRing/\f(CW\*(C`carp\*(C'\fRing, or \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing), but \fImust\fR allow
+suppressing all such STDERR output, and instead allow an option for
+reporting errors/warnings
+in some other way, whether by triggering a callback, or noting errors
+in some attribute of the document object, or some similarly unobtrusive
+mechanism \-\- or even by appending a "Pod Errors" section to the end of
+the parsed form of the document.
+.IP \(bu 4
+In cases of exceptionally aberrant documents, Pod parsers may abort the
+parse.  Even then, using \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing is to be avoided; where
+possible, the parser library may simply close the input file
+and add text like "*** Formatting Aborted ***" to the end of the
+(partial) in-memory document.
+.IP \(bu 4
+In paragraphs where formatting codes (like E<...>, B<...>)
+are understood (i.e., \fInot\fR verbatim paragraphs, but \fIincluding\fR
+ordinary paragraphs, and command paragraphs that produce renderable
+text, like "=head1"), literal whitespace should generally be considered
+"insignificant", in that one literal space has the same meaning as any
+(nonzero) number of literal spaces, literal newlines, and literal tabs
+(as long as this produces no blank lines, since those would terminate
+the paragraph).  Pod parsers should compact literal whitespace in each
+processed paragraph, but may provide an option for overriding this
+(since some processing tasks do not require it), or may follow
+additional special rules (for example, specially treating
+period-space-space or period-newline sequences).
+.IP \(bu 4
+Pod parsers should not, by default, try to coerce apostrophe (') and
+quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to
+turn backtick (`) into anything else but a single backtick character
+(distinct from an open quote character!), nor "\-\-" into anything but
+two minus signs.  They \fImust never\fR do any of those things to text
+in C<...> formatting codes, and never \fIever\fR to text in verbatim
+paragraphs.
+.IP \(bu 4
+When rendering Pod to a format that has two kinds of hyphens (\-), one
+that's a non-breaking hyphen, and another that's a breakable hyphen
+(as in "object-oriented", which can be split across lines as
+"object\-", newline, "oriented"), formatters are encouraged to
+generally translate "\-" to non-breaking hyphen, but may apply
+heuristics to convert some of these to breaking hyphens.
+.IP \(bu 4
+Pod formatters should make reasonable efforts to keep words of Perl
+code from being broken across lines.  For example, "Foo::Bar" in some
+formatting systems is seen as eligible for being broken across lines
+as "Foo::" newline "Bar" or even "Foo::\-" newline "Bar".  This should
+be avoided where possible, either by disabling all line-breaking in
+mid-word, or by wrapping particular words with internal punctuation
+in "don't break this across lines" codes (which in some formats may
+not be a single code, but might be a matter of inserting non-breaking
+zero-width spaces between every pair of characters in a word.)
+.IP \(bu 4
+Pod parsers should, by default, expand tabs in verbatim paragraphs as
+they are processed, before passing them to the formatter or other
+processor.  Parsers may also allow an option for overriding this.
+.IP \(bu 4
+Pod parsers should, by default, remove newlines from the end of
+ordinary and verbatim paragraphs before passing them to the
+formatter.  For example, while the paragraph you're reading now
+could be considered, in Pod source, to end with (and contain)
+the newline(s) that end it, it should be processed as ending with
+(and containing) the period character that ends this sentence.
+.IP \(bu 4
+Pod parsers, when reporting errors, should make some effort to report
+an approximate line number ("Nested E<>'s in Paragraph #52, near
+line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph
+number ("Nested E<>'s in Paragraph #52 of Thing/Foo.pm!").  Where
+this is problematic, the paragraph number should at least be
+accompanied by an excerpt from the paragraph ("Nested E<>'s in
+Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for
+the C<interest rate> attribute...'").
+.IP \(bu 4
+Pod parsers, when processing a series of verbatim paragraphs one
+after another, should consider them to be one large verbatim
+paragraph that happens to contain blank lines.  I.e., these two
+lines, which have a blank line between them:
+.Sp
+.Vb 1
+\&        use Foo;
+\&
+\&        print Foo\->VERSION
+.Ve
+.Sp
+should be unified into one paragraph ("\etuse Foo;\en\en\etprint
+Foo\->VERSION") before being passed to the formatter or other
+processor.  Parsers may also allow an option for overriding this.
+.Sp
+While this might be too cumbersome to implement in event-based Pod
+parsers, it is straightforward for parsers that return parse trees.
+.IP \(bu 4
+Pod formatters, where feasible, are advised to avoid splitting short
+verbatim paragraphs (under twelve lines, say) across pages.
+.IP \(bu 4
+Pod parsers must treat a line with only spaces and/or tabs on it as a
+"blank line" such as separates paragraphs.  (Some older parsers
+recognized only two adjacent newlines as a "blank line" but would not
+recognize a newline, a space, and a newline, as a blank line.  This
+is noncompliant behavior.)
+.IP \(bu 4
+Authors of Pod formatters/processors should make every effort to
+avoid writing their own Pod parser.  There are already several in
+CPAN, with a wide range of interface styles \-\- and one of them,
+Pod::Simple, comes with modern versions of Perl.
+.IP \(bu 4
+Characters in Pod documents may be conveyed either as literals, or by
+number in E<n> codes, or by an equivalent mnemonic, as in
+E<eacute> which is exactly equivalent to E<233>.  The numbers
+are the Latin1/Unicode values, even on EBCDIC platforms.
+.Sp
+When referring to characters by using a E<n> numeric code, numbers
+in the range 32\-126 refer to those well known US-ASCII characters (also
+defined there by Unicode, with the same meaning), which all Pod
+formatters must render faithfully.  Characters whose E<> numbers
+are in the ranges 0\-31 and 127\-159 should not be used (neither as
+literals,
+nor as E<number> codes), except for the literal byte-sequences for
+newline (ASCII 13, ASCII 13 10, or ASCII 10), and tab (ASCII 9).
+.Sp
+Numbers in the range 160\-255 refer to Latin\-1 characters (also
+defined there by Unicode, with the same meaning).  Numbers above
+255 should be understood to refer to Unicode characters.
+.IP \(bu 4
+Be warned
+that some formatters cannot reliably render characters outside 32\-126;
+and many are able to handle 32\-126 and 160\-255, but nothing above
+255.
+.IP \(bu 4
+Besides the well-known "E<lt>" and "E<gt>" codes for
+less-than and greater-than, Pod parsers must understand "E<sol>"
+for "/" (solidus, slash), and "E<verbar>" for "|" (vertical bar,
+pipe).  Pod parsers should also understand "E<lchevron>" and
+"E<rchevron>" as legacy codes for characters 171 and 187, i.e.,
+"left-pointing double angle quotation mark" = "left pointing
+guillemet" and "right-pointing double angle quotation mark" = "right
+pointing guillemet".  (These look like little "<<" and ">>", and they
+are now preferably expressed with the HTML/XHTML codes "E<laquo>"
+and "E<raquo>".)
+.IP \(bu 4
+Pod parsers should understand all "E<html>" codes as defined
+in the entity declarations in the most recent XHTML specification at
+\&\f(CW\*(C`www.W3.org\*(C'\fR.  Pod parsers must understand at least the entities
+that define characters in the range 160\-255 (Latin\-1).  Pod parsers,
+when faced with some unknown "E<\fIidentifier\fR>" code,
+shouldn't simply replace it with nullstring (by default, at least),
+but may pass it through as a string consisting of the literal characters
+E, less-than, \fIidentifier\fR, greater-than.  Or Pod parsers may offer the
+alternative option of processing such unknown
+"E<\fIidentifier\fR>" codes by firing an event especially
+for such codes, or by adding a special node-type to the in-memory
+document tree.  Such "E<\fIidentifier\fR>" may have special meaning
+to some processors, or some processors may choose to add them to
+a special error report.
+.IP \(bu 4
+Pod parsers must also support the XHTML codes "E<quot>" for
+character 34 (doublequote, "), "E<amp>" for character 38
+(ampersand, &), and "E<apos>" for character 39 (apostrophe, ').
+.IP \(bu 4
+Note that in all cases of "E<whatever>", \fIwhatever\fR (whether
+an htmlname, or a number in any base) must consist only of
+alphanumeric characters \-\- that is, \fIwhatever\fR must match
+\&\f(CW\*(C`m/\eA\ew+\ez/\*(C'\fR.  So "E<\ 0\ 1\ 2\ 3\ >" is invalid, because
+it contains spaces, which aren't alphanumeric characters.  This
+presumably does not \fIneed\fR special treatment by a Pod processor;
+"\ 0\ 1\ 2\ 3\ " doesn't look like a number in any base, so it would
+presumably be looked up in the table of HTML-like names.  Since
+there isn't (and cannot be) an HTML-like entity called "\ 0\ 1\ 2\ 3\ ",
+this will be treated as an error.  However, Pod processors may
+treat "E<\ 0\ 1\ 2\ 3\ >" or "E<e\-acute>" as \fIsyntactically\fR
+invalid, potentially earning a different error message than the
+error message (or warning, or event) generated by a merely unknown
+(but theoretically valid) htmlname, as in "E<qacute>"
+[sic].  However, Pod parsers are not required to make this
+distinction.
+.IP \(bu 4
+Note that E<number> \fImust not\fR be interpreted as simply
+"codepoint \fInumber\fR in the current/native character set".  It always
+means only "the character represented by codepoint \fInumber\fR in
+Unicode."  (This is identical to the semantics of &#\fInumber\fR; in XML.)
+.Sp
+This will likely require many formatters to have tables mapping from
+treatable Unicode codepoints (such as the "\exE9" for the e\-acute
+character) to the escape sequences or codes necessary for conveying
+such sequences in the target output format.  A converter to *roff
+would, for example know that "\exE9" (whether conveyed literally, or via
+a E<...> sequence) is to be conveyed as "e\e\e*'".
+Similarly, a program rendering Pod in a Mac OS application window, would
+presumably need to know that "\exE9" maps to codepoint 142 in MacRoman
+encoding that (at time of writing) is native for Mac OS.  Such
+Unicode2whatever mappings are presumably already widely available for
+common output formats.  (Such mappings may be incomplete!  Implementers
+are not expected to bend over backwards in an attempt to render
+Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
+of the other weird things that Unicode can encode.)  And
+if a Pod document uses a character not found in such a mapping, the
+formatter should consider it an unrenderable character.
+.IP \(bu 4
+If, surprisingly, the implementor of a Pod formatter can't find a
+satisfactory pre-existing table mapping from Unicode characters to
+escapes in the target format (e.g., a decent table of Unicode
+characters to *roff escapes), it will be necessary to build such a
+table.  If you are in this circumstance, you should begin with the
+characters in the range 0x00A0 \- 0x00FF, which is mostly the heavily
+used accented characters.  Then proceed (as patience permits and
+fastidiousness compels) through the characters that the (X)HTML
+standards groups judged important enough to merit mnemonics
+for.  These are declared in the (X)HTML specifications at the
+www.W3.org site.  At time of writing (September 2001), the most recent
+entity declaration files are:
+.Sp
+.Vb 3
+\&  http://www.w3.org/TR/xhtml1/DTD/xhtml\-lat1.ent
+\&  http://www.w3.org/TR/xhtml1/DTD/xhtml\-special.ent
+\&  http://www.w3.org/TR/xhtml1/DTD/xhtml\-symbol.ent
+.Ve
+.Sp
+Then you can progress through any remaining notable Unicode characters
+in the range 0x2000\-0x204D (consult the character tables at
+www.unicode.org), and whatever else strikes your fancy.  For example,
+in \fIxhtml\-symbol.ent\fR, there is the entry:
+.Sp
+.Vb 1
+\&  <!ENTITY infin    "&#8734;"> <!\-\- infinity, U+221E ISOtech \-\->
+.Ve
+.Sp
+While the mapping "infin" to the character "\ex{221E}" will (hopefully)
+have been already handled by the Pod parser, the presence of the
+character in this file means that it's reasonably important enough to
+include in a formatter's table that maps from notable Unicode characters
+to the codes necessary for rendering them.  So for a Unicode\-to\-*roff
+mapping, for example, this would merit the entry:
+.Sp
+.Vb 1
+\&  "\ex{221E}" => \*(Aq\e(in\*(Aq,
+.Ve
+.Sp
+It is eagerly hoped that in the future, increasing numbers of formats
+(and formatters) will support Unicode characters directly (as (X)HTML
+does with \f(CW\*(C`&infin;\*(C'\fR, \f(CW\*(C`&#8734;\*(C'\fR, or \f(CW\*(C`&#x221E;\*(C'\fR), reducing the need
+for idiosyncratic mappings of Unicode\-to\-\fImy_escapes\fR.
+.IP \(bu 4
+It is up to individual Pod formatter to display good judgement when
+confronted with an unrenderable character (which is distinct from an
+unknown E<thing> sequence that the parser couldn't resolve to
+anything, renderable or not).  It is good practice to map Latin letters
+with diacritics (like "E<eacute>"/"E<233>") to the corresponding
+unaccented US-ASCII letters (like a simple character 101, "e"), but
+clearly this is often not feasible, and an unrenderable character may
+be represented as "?", or the like.  In attempting a sane fallback
+(as from E<233> to "e"), Pod formatters may use the
+\&\f(CW%Latin1Code_to_fallback\fR table in Pod::Escapes, or
+Text::Unidecode, if available.
+.Sp
+For example, this Pod text:
+.Sp
+.Vb 1
+\&  magic is enabled if you set C<$Currency> to \*(AqE<euro>\*(Aq.
+.Ve
+.Sp
+may be rendered as:
+"magic is enabled if you set \f(CW$Currency\fR to '\fI?\fR'" or as
+"magic is enabled if you set \f(CW$Currency\fR to '\fB[euro]\fR'", or as
+"magic is enabled if you set \f(CW$Currency\fR to '[x20AC]', etc.
+.Sp
+A Pod formatter may also note, in a comment or warning, a list of what
+unrenderable characters were encountered.
+.IP \(bu 4
+E<...> may freely appear in any formatting code (other than
+in another E<...> or in an Z<>).  That is, "X<The
+E<euro>1,000,000 Solution>" is valid, as is "L<The
+E<euro>1,000,000 Solution|Million::Euros>".
+.IP \(bu 4
+Some Pod formatters output to formats that implement non-breaking
+spaces as an individual character (which I'll call "NBSP"), and
+others output to formats that implement non-breaking spaces just as
+spaces wrapped in a "don't break this across lines" code.  Note that
+at the level of Pod, both sorts of codes can occur: Pod can contain a
+NBSP character (whether as a literal, or as a "E<160>" or
+"E<nbsp>" code); and Pod can contain "S<foo
+I<bar> baz>" codes, where "mere spaces" (character 32) in
+such codes are taken to represent non-breaking spaces.  Pod
+parsers should consider supporting the optional parsing of "S<foo
+I<bar> baz>" as if it were
+"foo\fINBSP\fRI<bar>\fINBSP\fRbaz", and, going the other way, the
+optional parsing of groups of words joined by NBSP's as if each group
+were in a S<...> code, so that formatters may use the
+representation that maps best to what the output format demands.
+.IP \(bu 4
+Some processors may find that the \f(CW\*(C`S<...>\*(C'\fR code is easiest to
+implement by replacing each space in the parse tree under the content
+of the S, with an NBSP.  But note: the replacement should apply \fInot\fR to
+spaces in \fIall\fR text, but \fIonly\fR to spaces in \fIprintable\fR text.  (This
+distinction may or may not be evident in the particular tree/event
+model implemented by the Pod parser.)  For example, consider this
+unusual case:
+.Sp
+.Vb 1
+\&   S<L</Autoloaded Functions>>
+.Ve
+.Sp
+This means that the space in the middle of the visible link text must
+not be broken across lines.  In other words, it's the same as this:
+.Sp
+.Vb 1
+\&   L<"AutoloadedE<160>Functions"/Autoloaded Functions>
+.Ve
+.Sp
+However, a misapplied space-to-NBSP replacement could (wrongly)
+produce something equivalent to this:
+.Sp
+.Vb 1
+\&   L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
+.Ve
+.Sp
+\&...which is almost definitely not going to work as a hyperlink (assuming
+this formatter outputs a format supporting hypertext).
+.Sp
+Formatters may choose to just not support the S format code,
+especially in cases where the output format simply has no NBSP
+character/code and no code for "don't break this stuff across lines".
+.IP \(bu 4
+Besides the NBSP character discussed above, implementors are reminded
+of the existence of the other "special" character in Latin\-1, the
+"soft hyphen" character, also known as "discretionary hyphen",
+i.e. \f(CW\*(C`E<173>\*(C'\fR = \f(CW\*(C`E<0xAD>\*(C'\fR =
+\&\f(CW\*(C`E<shy>\*(C'\fR).  This character expresses an optional hyphenation
+point.  That is, it normally renders as nothing, but may render as a
+"\-" if a formatter breaks the word at that point.  Pod formatters
+should, as appropriate, do one of the following:  1) render this with
+a code with the same meaning (e.g., "\e\-" in RTF), 2) pass it through
+in the expectation that the formatter understands this character as
+such, or 3) delete it.
+.Sp
+For example:
+.Sp
+.Vb 3
+\&  sigE<shy>action
+\&  manuE<shy>script
+\&  JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi
+.Ve
+.Sp
+These signal to a formatter that if it is to hyphenate "sigaction"
+or "manuscript", then it should be done as
+"sig\-\fI[linebreak]\fRaction" or "manu\-\fI[linebreak]\fRscript"
+(and if it doesn't hyphenate it, then the \f(CW\*(C`E<shy>\*(C'\fR doesn't
+show up at all).  And if it is
+to hyphenate "Jarkko" and/or "Hietaniemi", it can do
+so only at the points where there is a \f(CW\*(C`E<shy>\*(C'\fR code.
+.Sp
+In practice, it is anticipated that this character will not be used
+often, but formatters should either support it, or delete it.
+.IP \(bu 4
+If you think that you want to add a new command to Pod (like, say, a
+"=biblio" command), consider whether you could get the same
+effect with a for or begin/end sequence: "=for biblio ..." or "=begin
+biblio" ... "=end biblio".  Pod processors that don't understand
+"=for biblio", etc, will simply ignore it, whereas they may complain
+loudly if they see "=biblio".
+.IP \(bu 4
+Throughout this document, "Pod" has been the preferred spelling for
+the name of the documentation format.  One may also use "POD" or
+"pod".  For the documentation that is (typically) in the Pod
+format, you may use "pod", or "Pod", or "POD".  Understanding these
+distinctions is useful; but obsessing over how to spell them, usually
+is not.
+.SH "About L<...> Codes"
+.IX Header "About L<...> Codes"
+As you can tell from a glance at perlpod, the L<...>
+code is the most complex of the Pod formatting codes.  The points below
+will hopefully clarify what it means and how processors should deal
+with it.
+.IP \(bu 4
+In parsing an L<...> code, Pod parsers must distinguish at least
+four attributes:
+.RS 4
+.IP First: 4
+.IX Item "First:"
+The link-text.  If there is none, this must be \f(CW\*(C`undef\*(C'\fR.  (E.g., in
+"L<Perl Functions|perlfunc>", the link-text is "Perl Functions".
+In "L<Time::HiRes>" and even "L<|Time::HiRes>", there is no
+link text.  Note that link text may contain formatting.)
+.IP Second: 4
+.IX Item "Second:"
+The possibly inferred link-text; i.e., if there was no real link
+text, then this is the text that we'll infer in its place.  (E.g., for
+"L<Getopt::Std>", the inferred link text is "Getopt::Std".)
+.IP Third: 4
+.IX Item "Third:"
+The name or URL, or \f(CW\*(C`undef\*(C'\fR if none.  (E.g., in "L<Perl
+Functions|perlfunc>", the name (also sometimes called the page)
+is "perlfunc".  In "L</CAVEATS>", the name is \f(CW\*(C`undef\*(C'\fR.)
+.IP Fourth: 4
+.IX Item "Fourth:"
+The section (AKA "item" in older perlpods), or \f(CW\*(C`undef\*(C'\fR if none.  E.g.,
+in "L<Getopt::Std/DESCRIPTION>", "DESCRIPTION" is the section.  (Note
+that this is not the same as a manpage section like the "5" in "man 5
+crontab".  "Section Foo" in the Pod sense means the part of the text
+that's introduced by the heading or item whose text is "Foo".)
+.RE
+.RS 4
+.Sp
+Pod parsers may also note additional attributes including:
+.IP Fifth: 4
+.IX Item "Fifth:"
+A flag for whether item 3 (if present) is a URL (like
+"http://lists.perl.org" is), in which case there should be no section
+attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or
+possibly a man page name (like "\fBcrontab\fR\|(5)" is).
+.IP Sixth: 4
+.IX Item "Sixth:"
+The raw original L<...> content, before text is split on
+"|", "/", etc, and before E<...> codes are expanded.
+.RE
+.RS 4
+.Sp
+(The above were numbered only for concise reference below.  It is not
+a requirement that these be passed as an actual list or array.)
+.Sp
+For example:
+.Sp
+.Vb 7
+\&  L<Foo::Bar>
+\&    =>  undef,                         # link text
+\&        "Foo::Bar",                    # possibly inferred link text
+\&        "Foo::Bar",                    # name
+\&        undef,                         # section
+\&        \*(Aqpod\*(Aq,                         # what sort of link
+\&        "Foo::Bar"                     # original content
+\&
+\&  L<Perlport\*(Aqs section on NL\*(Aqs|perlport/Newlines>
+\&    =>  "Perlport\*(Aqs section on NL\*(Aqs",  # link text
+\&        "Perlport\*(Aqs section on NL\*(Aqs",  # possibly inferred link text
+\&        "perlport",                    # name
+\&        "Newlines",                    # section
+\&        \*(Aqpod\*(Aq,                         # what sort of link
+\&        "Perlport\*(Aqs section on NL\*(Aqs|perlport/Newlines"
+\&                                       # original content
+\&
+\&  L<perlport/Newlines>
+\&    =>  undef,                         # link text
+\&        \*(Aq"Newlines" in perlport\*(Aq,      # possibly inferred link text
+\&        "perlport",                    # name
+\&        "Newlines",                    # section
+\&        \*(Aqpod\*(Aq,                         # what sort of link
+\&        "perlport/Newlines"            # original content
+\&
+\&  L<crontab(5)/"DESCRIPTION">
+\&    =>  undef,                         # link text
+\&        \*(Aq"DESCRIPTION" in crontab(5)\*(Aq, # possibly inferred link text
+\&        "crontab(5)",                  # name
+\&        "DESCRIPTION",                 # section
+\&        \*(Aqman\*(Aq,                         # what sort of link
+\&        \*(Aqcrontab(5)/"DESCRIPTION"\*(Aq     # original content
+\&
+\&  L</Object Attributes>
+\&    =>  undef,                         # link text
+\&        \*(Aq"Object Attributes"\*(Aq,         # possibly inferred link text
+\&        undef,                         # name
+\&        "Object Attributes",           # section
+\&        \*(Aqpod\*(Aq,                         # what sort of link
+\&        "/Object Attributes"           # original content
+\&
+\&  L<https://www.perl.org/>
+\&    =>  undef,                         # link text
+\&        "https://www.perl.org/",       # possibly inferred link text
+\&        "https://www.perl.org/",       # name
+\&        undef,                         # section
+\&        \*(Aqurl\*(Aq,                         # what sort of link
+\&        "https://www.perl.org/"         # original content
+\&
+\&  L<Perl.org|https://www.perl.org/>
+\&    =>  "Perl.org",                    # link text
+\&        "https://www.perl.org/",       # possibly inferred link text
+\&        "https://www.perl.org/",       # name
+\&        undef,                         # section
+\&        \*(Aqurl\*(Aq,                         # what sort of link
+\&        "Perl.org|https://www.perl.org/" # original content
+.Ve
+.Sp
+Note that you can distinguish URL-links from anything else by the
+fact that they match \f(CW\*(C`m/\eA\ew+:[^:\es]\eS*\ez/\*(C'\fR.  So
+\&\f(CW\*(C`L<http://www.perl.com>\*(C'\fR is a URL, but
+\&\f(CW\*(C`L<HTTP::Response>\*(C'\fR isn't.
+.RE
+.IP \(bu 4
+In case of L<...> codes with no "text|" part in them,
+older formatters have exhibited great variation in actually displaying
+the link or cross reference.  For example, L<\fBcrontab\fR\|(5)> would render
+as "the \f(CWcrontab(5)\fR manpage", or "in the \f(CWcrontab(5)\fR manpage"
+or just "\f(CWcrontab(5)\fR".
+.Sp
+Pod processors must now treat "text|"\-less links as follows:
+.Sp
+.Vb 3
+\&  L<name>         =>  L<name|name>
+\&  L</section>     =>  L<"section"|/section>
+\&  L<name/section> =>  L<"section" in name|name/section>
+.Ve
+.IP \(bu 4
+Note that section names might contain markup.  I.e., if a section
+starts with:
+.Sp
+.Vb 1
+\&  =head2 About the C<\-M> Operator
+.Ve
+.Sp
+or with:
+.Sp
+.Vb 1
+\&  =item About the C<\-M> Operator
+.Ve
+.Sp
+then a link to it would look like this:
+.Sp
+.Vb 1
+\&  L<somedoc/About the C<\-M> Operator>
+.Ve
+.Sp
+Formatters may choose to ignore the markup for purposes of resolving
+the link and use only the renderable characters in the section name,
+as in:
+.Sp
+.Vb 2
+\&  <h1><a name="About_the_\-M_Operator">About the <code>\-M</code>
+\&  Operator</h1>
+\&
+\&  ...
+\&
+\&  <a href="somedoc#About_the_\-M_Operator">About the <code>\-M</code>
+\&  Operator" in somedoc</a>
+.Ve
+.IP \(bu 4
+Previous versions of perlpod distinguished \f(CW\*(C`L<name/"section">\*(C'\fR
+links from \f(CW\*(C`L<name/item>\*(C'\fR links (and their targets).  These
+have been merged syntactically and semantically in the current
+specification, and \fIsection\fR can refer either to a "=head\fIn\fR Heading
+Content" command or to a "=item Item Content" command.  This
+specification does not specify what behavior should be in the case
+of a given document having several things all seeming to produce the
+same \fIsection\fR identifier (e.g., in HTML, several things all producing
+the same \fIanchorname\fR in <a name="\fIanchorname\fR">...</a>
+elements).  Where Pod processors can control this behavior, they should
+use the first such anchor.  That is, \f(CW\*(C`L<Foo/Bar>\*(C'\fR refers to the
+\&\fIfirst\fR "Bar" section in Foo.
+.Sp
+But for some processors/formats this cannot be easily controlled; as
+with the HTML example, the behavior of multiple ambiguous
+<a name="\fIanchorname\fR">...</a> is most easily just left up to
+browsers to decide.
+.IP \(bu 4
+In a \f(CW\*(C`L<text|...>\*(C'\fR code, text may contain formatting codes
+for formatting or for E<...> escapes, as in:
+.Sp
+.Vb 1
+\&  L<B<ummE<234>stuff>|...>
+.Ve
+.Sp
+For \f(CW\*(C`L<...>\*(C'\fR codes without a "name|" part, only
+\&\f(CW\*(C`E<...>\*(C'\fR and \f(CW\*(C`Z<>\*(C'\fR codes may occur.  That is,
+authors should not use "\f(CW\*(C`L<B<Foo::Bar>>\*(C'\fR".
+.Sp
+Note, however, that formatting codes and Z<>'s can occur in any
+and all parts of an L<...> (i.e., in \fIname\fR, \fIsection\fR, \fItext\fR,
+and \fIurl\fR).
+.Sp
+Authors must not nest L<...> codes.  For example, "L<The
+L<Foo::Bar> man page>" should be treated as an error.
+.IP \(bu 4
+Note that Pod authors may use formatting codes inside the "text"
+part of "L<text|name>" (and so on for L<text|/"sec">).
+.Sp
+In other words, this is valid:
+.Sp
+.Vb 1
+\&  Go read L<the docs on C<$.>|perlvar/"$.">
+.Ve
+.Sp
+Some output formats that do allow rendering "L<...>" codes as
+hypertext, might not allow the link-text to be formatted; in
+that case, formatters will have to just ignore that formatting.
+.IP \(bu 4
+At time of writing, \f(CW\*(C`L<name>\*(C'\fR values are of two types:
+either the name of a Pod page like \f(CW\*(C`L<Foo::Bar>\*(C'\fR (which
+might be a real Perl module or program in an \f(CW@INC\fR / PATH
+directory, or a .pod file in those places); or the name of a Unix
+man page, like \f(CW\*(C`L<crontab(5)>\*(C'\fR.  In theory, \f(CW\*(C`L<chmod>\*(C'\fR
+is ambiguous between a Pod page called "chmod", or the Unix man page
+"chmod" (in whatever man-section).  However, the presence of a string
+in parens, as in "\fBcrontab\fR\|(5)", is sufficient to signal that what
+is being discussed is not a Pod page, and so is presumably a
+Unix man page.  The distinction is of no importance to many
+Pod processors, but some processors that render to hypertext formats
+may need to distinguish them in order to know how to render a
+given \f(CW\*(C`L<foo>\*(C'\fR code.
+.IP \(bu 4
+Previous versions of perlpod allowed for a \f(CW\*(C`L<section>\*(C'\fR syntax (as in
+\&\f(CW\*(C`L<Object Attributes>\*(C'\fR), which was not easily distinguishable from
+\&\f(CW\*(C`L<name>\*(C'\fR syntax and for \f(CW\*(C`L<"section">\*(C'\fR which was only
+slightly less ambiguous.  This syntax is no longer in the specification, and
+has been replaced by the \f(CW\*(C`L</section>\*(C'\fR syntax (where the slash was
+formerly optional).  Pod parsers should tolerate the \f(CW\*(C`L<"section">\*(C'\fR
+syntax, for a while at least.  The suggested heuristic for distinguishing
+\&\f(CW\*(C`L<section>\*(C'\fR from \f(CW\*(C`L<name>\*(C'\fR is that if it contains any
+whitespace, it's a \fIsection\fR.  Pod processors should warn about this being
+deprecated syntax.
+.SH "About =over...=back Regions"
+.IX Header "About =over...=back Regions"
+"=over"..."=back" regions are used for various kinds of list-like
+structures.  (I use the term "region" here simply as a collective
+term for everything from the "=over" to the matching "=back".)
+.IP \(bu 4
+The non-zero numeric \fIindentlevel\fR in "=over \fIindentlevel\fR" ...
+"=back" is used for giving the formatter a clue as to how many
+"spaces" (ems, or roughly equivalent units) it should tab over,
+although many formatters will have to convert this to an absolute
+measurement that may not exactly match with the size of spaces (or M's)
+in the document's base font.  Other formatters may have to completely
+ignore the number.  The lack of any explicit \fIindentlevel\fR parameter is
+equivalent to an \fIindentlevel\fR value of 4.  Pod processors may
+complain if \fIindentlevel\fR is present but is not a positive number
+matching \f(CW\*(C`m/\eA(\ed*\e.)?\ed+\ez/\*(C'\fR.
+.IP \(bu 4
+Authors of Pod formatters are reminded that "=over" ... "=back" may
+map to several different constructs in your output format.  For
+example, in converting Pod to (X)HTML, it can map to any of
+<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or
+<blockquote>...</blockquote>.  Similarly, "=item" can map to <li> or
+<dt>.
+.IP \(bu 4
+Each "=over" ... "=back" region should be one of the following:
+.RS 4
+.IP \(bu 4
+An "=over" ... "=back" region containing only "=item *" commands,
+each followed by some number of ordinary/verbatim paragraphs, other
+nested "=over" ... "=back" regions, "=for..." paragraphs, and
+"=begin"..."=end" regions.
+.Sp
+(Pod processors must tolerate a bare "=item" as if it were "=item
+*".)  Whether "*" is rendered as a literal asterisk, an "o", or as
+some kind of real bullet character, is left up to the Pod formatter,
+and may depend on the level of nesting.
+.IP \(bu 4
+An "=over" ... "=back" region containing only
+\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR paragraphs, each one (or each group of them)
+followed by some number of ordinary/verbatim paragraphs, other nested
+"=over" ... "=back" regions, "=for..." paragraphs, and/or
+"=begin"..."=end" codes.  Note that the numbers must start at 1
+in each section, and must proceed in order and without skipping
+numbers.
+.Sp
+(Pod processors must tolerate lines like "=item 1" as if they were
+"=item 1.", with the period.)
+.IP \(bu 4
+An "=over" ... "=back" region containing only "=item [text]"
+commands, each one (or each group of them) followed by some number of
+ordinary/verbatim paragraphs, other nested "=over" ... "=back"
+regions, or "=for..." paragraphs, and "=begin"..."=end" regions.
+.Sp
+The "=item [text]" paragraph should not match
+\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR or \f(CW\*(C`m/\eA=item\es+\e*\es*\ez/\*(C'\fR, nor should it
+match just \f(CW\*(C`m/\eA=item\es*\ez/\*(C'\fR.
+.IP \(bu 4
+An "=over" ... "=back" region containing no "=item" paragraphs at
+all, and containing only some number of 
+ordinary/verbatim paragraphs, and possibly also some nested "=over"
+\&... "=back" regions, "=for..." paragraphs, and "=begin"..."=end"
+regions.  Such an itemless "=over" ... "=back" region in Pod is
+equivalent in meaning to a "<blockquote>...</blockquote>" element in
+HTML.
+.RE
+.RS 4
+.Sp
+Note that with all the above cases, you can determine which type of
+"=over" ... "=back" you have, by examining the first (non\-"=cut", 
+non\-"=pod") Pod paragraph after the "=over" command.
+.RE
+.IP \(bu 4
+Pod formatters \fImust\fR tolerate arbitrarily large amounts of text
+in the "=item \fItext...\fR" paragraph.  In practice, most such
+paragraphs are short, as in:
+.Sp
+.Vb 1
+\&  =item For cutting off our trade with all parts of the world
+.Ve
+.Sp
+But they may be arbitrarily long:
+.Sp
+.Vb 2
+\&  =item For transporting us beyond seas to be tried for pretended
+\&  offenses
+\&
+\&  =item He is at this time transporting large armies of foreign
+\&  mercenaries to complete the works of death, desolation and
+\&  tyranny, already begun with circumstances of cruelty and perfidy
+\&  scarcely paralleled in the most barbarous ages, and totally
+\&  unworthy the head of a civilized nation.
+.Ve
+.IP \(bu 4
+Pod processors should tolerate "=item *" / "=item \fInumber\fR" commands
+with no accompanying paragraph.  The middle item is an example:
+.Sp
+.Vb 1
+\&  =over
+\&
+\&  =item 1
+\&
+\&  Pick up dry cleaning.
+\&
+\&  =item 2
+\&
+\&  =item 3
+\&
+\&  Stop by the store.  Get Abba Zabas, Stoli, and cheap lawn chairs.
+\&
+\&  =back
+.Ve
+.IP \(bu 4
+No "=over" ... "=back" region can contain headings.  Processors may
+treat such a heading as an error.
+.IP \(bu 4
+Note that an "=over" ... "=back" region should have some
+content.  That is, authors should not have an empty region like this:
+.Sp
+.Vb 1
+\&  =over
+\&
+\&  =back
+.Ve
+.Sp
+Pod processors seeing such a contentless "=over" ... "=back" region,
+may ignore it, or may report it as an error.
+.IP \(bu 4
+Processors must tolerate an "=over" list that goes off the end of the
+document (i.e., which has no matching "=back"), but they may warn
+about such a list.
+.IP \(bu 4
+Authors of Pod formatters should note that this construct:
+.Sp
+.Vb 1
+\&  =item Neque
+\&
+\&  =item Porro
+\&
+\&  =item Quisquam Est
+\&
+\&  Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci 
+\&  velit, sed quia non numquam eius modi tempora incidunt ut
+\&  labore et dolore magnam aliquam quaerat voluptatem.
+\&
+\&  =item Ut Enim
+.Ve
+.Sp
+is semantically ambiguous, in a way that makes formatting decisions
+a bit difficult.  On the one hand, it could be mention of an item
+"Neque", mention of another item "Porro", and mention of another
+item "Quisquam Est", with just the last one requiring the explanatory
+paragraph "Qui dolorem ipsum quia dolor..."; and then an item
+"Ut Enim".  In that case, you'd want to format it like so:
+.Sp
+.Vb 1
+\&  Neque
+\&
+\&  Porro
+\&
+\&  Quisquam Est
+\&    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
+\&    velit, sed quia non numquam eius modi tempora incidunt ut
+\&    labore et dolore magnam aliquam quaerat voluptatem.
+\&
+\&  Ut Enim
+.Ve
+.Sp
+But it could equally well be a discussion of three (related or equivalent)
+items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph
+explaining them all, and then a new item "Ut Enim".  In that case, you'd
+probably want to format it like so:
+.Sp
+.Vb 6
+\&  Neque
+\&  Porro
+\&  Quisquam Est
+\&    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
+\&    velit, sed quia non numquam eius modi tempora incidunt ut
+\&    labore et dolore magnam aliquam quaerat voluptatem.
+\&
+\&  Ut Enim
+.Ve
+.Sp
+But (for the foreseeable future), Pod does not provide any way for Pod
+authors to distinguish which grouping is meant by the above
+"=item"\-cluster structure.  So formatters should format it like so:
+.Sp
+.Vb 1
+\&  Neque
+\&
+\&  Porro
+\&
+\&  Quisquam Est
+\&
+\&    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
+\&    velit, sed quia non numquam eius modi tempora incidunt ut
+\&    labore et dolore magnam aliquam quaerat voluptatem.
+\&
+\&  Ut Enim
+.Ve
+.Sp
+That is, there should be (at least roughly) equal spacing between
+items as between paragraphs (although that spacing may well be less
+than the full height of a line of text).  This leaves it to the reader
+to use (con)textual cues to figure out whether the "Qui dolorem
+ipsum..." paragraph applies to the "Quisquam Est" item or to all three
+items "Neque", "Porro", and "Quisquam Est".  While not an ideal
+situation, this is preferable to providing formatting cues that may
+be actually contrary to the author's intent.
+.SH "About Data Paragraphs and ""=begin/=end"" Regions"
+.IX Header "About Data Paragraphs and ""=begin/=end"" Regions"
+Data paragraphs are typically used for inlining non-Pod data that is
+to be used (typically passed through) when rendering the document to
+a specific format:
+.PP
+.Vb 1
+\&  =begin rtf
+\&
+\&  \epar{\epard\eqr\esa4500{\ei Printed\e~\echdate\e~\echtime}\epar}
+\&
+\&  =end rtf
+.Ve
+.PP
+The exact same effect could, incidentally, be achieved with a single
+"=for" paragraph:
+.PP
+.Vb 1
+\&  =for rtf \epar{\epard\eqr\esa4500{\ei Printed\e~\echdate\e~\echtime}\epar}
+.Ve
+.PP
+(Although that is not formally a data paragraph, it has the same
+meaning as one, and Pod parsers may parse it as one.)
+.PP
+Another example of a data paragraph:
+.PP
+.Vb 1
+\&  =begin html
+\&
+\&  I like <em>PIE</em>!
+\&
+\&  <hr>Especially pecan pie!
+\&
+\&  =end html
+.Ve
+.PP
+If these were ordinary paragraphs, the Pod parser would try to
+expand the "E</em>" (in the first paragraph) as a formatting
+code, just like "E<lt>" or "E<eacute>".  But since this
+is in a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR" region \fIand\fR
+the identifier "html" doesn't begin have a ":" prefix, the contents
+of this region are stored as data paragraphs, instead of being
+processed as ordinary paragraphs (or if they began with a spaces
+and/or tabs, as verbatim paragraphs).
+.PP
+As a further example: At time of writing, no "biblio" identifier is
+supported, but suppose some processor were written to recognize it as
+a way of (say) denoting a bibliographic reference (necessarily
+containing formatting codes in ordinary paragraphs).  The fact that
+"biblio" paragraphs were meant for ordinary processing would be
+indicated by prefacing each "biblio" identifier with a colon:
+.PP
+.Vb 1
+\&  =begin :biblio
+\&
+\&  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
+\&  Programs.>  Prentice\-Hall, Englewood Cliffs, NJ.
+\&
+\&  =end :biblio
+.Ve
+.PP
+This would signal to the parser that paragraphs in this begin...end
+region are subject to normal handling as ordinary/verbatim paragraphs
+(while still tagged as meant only for processors that understand the
+"biblio" identifier).  The same effect could be had with:
+.PP
+.Vb 3
+\&  =for :biblio
+\&  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
+\&  Programs.>  Prentice\-Hall, Englewood Cliffs, NJ.
+.Ve
+.PP
+The ":" on these identifiers means simply "process this stuff
+normally, even though the result will be for some special target".
+I suggest that parser APIs report "biblio" as the target identifier,
+but also report that it had a ":" prefix.  (And similarly, with the
+above "html", report "html" as the target identifier, and note the
+\&\fIlack\fR of a ":" prefix.)
+.PP
+Note that a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR" region where
+\&\fIidentifier\fR begins with a colon, \fIcan\fR contain commands.  For example:
+.PP
+.Vb 1
+\&  =begin :biblio
+\&
+\&  Wirth\*(Aqs classic is available in several editions, including:
+\&
+\&  =for comment
+\&   hm, check abebooks.com for how much used copies cost.
+\&
+\&  =over
+\&
+\&  =item
+\&
+\&  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
+\&  Teubner, Stuttgart.  [Yes, it\*(Aqs in German.]
+\&
+\&  =item
+\&
+\&  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
+\&  Programs.>  Prentice\-Hall, Englewood Cliffs, NJ.
+\&
+\&  =back
+\&
+\&  =end :biblio
+.Ve
+.PP
+Note, however, a "=begin \fIidentifier\fR"..."=end \fIidentifier\fR"
+region where \fIidentifier\fR does \fInot\fR begin with a colon, should not
+directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back",
+nor "=item".  For example, this may be considered invalid:
+.PP
+.Vb 1
+\&  =begin somedata
+\&
+\&  This is a data paragraph.
+\&
+\&  =head1 Don\*(Aqt do this!
+\&
+\&  This is a data paragraph too.
+\&
+\&  =end somedata
+.Ve
+.PP
+A Pod processor may signal that the above (specifically the "=head1"
+paragraph) is an error.  Note, however, that the following should
+\&\fInot\fR be treated as an error:
+.PP
+.Vb 1
+\&  =begin somedata
+\&
+\&  This is a data paragraph.
+\&
+\&  =cut
+\&
+\&  # Yup, this isn\*(Aqt Pod anymore.
+\&  sub excl { (rand() > .5) ? "hoo!" : "hah!" }
+\&
+\&  =pod
+\&
+\&  This is a data paragraph too.
+\&
+\&  =end somedata
+.Ve
+.PP
+And this too is valid:
+.PP
+.Vb 1
+\&  =begin someformat
+\&
+\&  This is a data paragraph.
+\&
+\&    And this is a data paragraph.
+\&
+\&  =begin someotherformat
+\&
+\&  This is a data paragraph too.
+\&
+\&    And this is a data paragraph too.
+\&
+\&  =begin :yetanotherformat
+\&
+\&  =head2 This is a command paragraph!
+\&
+\&  This is an ordinary paragraph!
+\&
+\&    And this is a verbatim paragraph!
+\&
+\&  =end :yetanotherformat
+\&
+\&  =end someotherformat
+\&
+\&  Another data paragraph!
+\&
+\&  =end someformat
+.Ve
+.PP
+The contents of the above "=begin :yetanotherformat" ...
+"=end :yetanotherformat" region \fIaren't\fR data paragraphs, because
+the immediately containing region's identifier (":yetanotherformat")
+begins with a colon.  In practice, most regions that contain
+data paragraphs will contain \fIonly\fR data paragraphs; however, 
+the above nesting is syntactically valid as Pod, even if it is
+rare.  However, the handlers for some formats, like "html",
+will accept only data paragraphs, not nested regions; and they may
+complain if they see (targeted for them) nested regions, or commands,
+other than "=end", "=pod", and "=cut".
+.PP
+Also consider this valid structure:
+.PP
+.Vb 1
+\&  =begin :biblio
+\&
+\&  Wirth\*(Aqs classic is available in several editions, including:
+\&
+\&  =over
+\&
+\&  =item
+\&
+\&  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
+\&  Teubner, Stuttgart.  [Yes, it\*(Aqs in German.]
+\&
+\&  =item
+\&
+\&  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
+\&  Programs.>  Prentice\-Hall, Englewood Cliffs, NJ.
+\&
+\&  =back
+\&
+\&  Buy buy buy!
+\&
+\&  =begin html
+\&
+\&  <img src=\*(Aqwirth_spokesmodeling_book.png\*(Aq>
+\&
+\&  <hr>
+\&
+\&  =end html
+\&
+\&  Now now now!
+\&
+\&  =end :biblio
+.Ve
+.PP
+There, the "=begin html"..."=end html" region is nested inside
+the larger "=begin :biblio"..."=end :biblio" region.  Note that the
+content of the "=begin html"..."=end html" region is data
+paragraph(s), because the immediately containing region's identifier
+("html") \fIdoesn't\fR begin with a colon.
+.PP
+Pod parsers, when processing a series of data paragraphs one
+after another (within a single region), should consider them to
+be one large data paragraph that happens to contain blank lines.  So
+the content of the above "=begin html"..."=end html" \fImay\fR be stored
+as two data paragraphs (one consisting of
+"<img src='wirth_spokesmodeling_book.png'>\en"
+and another consisting of "<hr>\en"), but \fIshould\fR be stored as
+a single data paragraph (consisting of 
+"<img src='wirth_spokesmodeling_book.png'>\en\en<hr>\en").
+.PP
+Pod processors should tolerate empty
+"=begin \fIsomething\fR"..."=end \fIsomething\fR" regions,
+empty "=begin :\fIsomething\fR"..."=end :\fIsomething\fR" regions, and
+contentless "=for \fIsomething\fR" and "=for :\fIsomething\fR"
+paragraphs.  I.e., these should be tolerated:
+.PP
+.Vb 1
+\&  =for html
+\&
+\&  =begin html
+\&
+\&  =end html
+\&
+\&  =begin :biblio
+\&
+\&  =end :biblio
+.Ve
+.PP
+Incidentally, note that there's no easy way to express a data
+paragraph starting with something that looks like a command.  Consider:
+.PP
+.Vb 1
+\&  =begin stuff
+\&
+\&  =shazbot
+\&
+\&  =end stuff
+.Ve
+.PP
+There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
+paragraph "=shazbot\en".  However, you can express a data paragraph consisting
+of "=shazbot\en" using this code:
+.PP
+.Vb 1
+\&  =for stuff =shazbot
+.Ve
+.PP
+The situation where this is necessary, is presumably quite rare.
+.PP
+Note that =end commands must match the currently open =begin command.  That
+is, they must properly nest.  For example, this is valid:
+.PP
+.Vb 1
+\&  =begin outer
+\&
+\&  X
+\&
+\&  =begin inner
+\&
+\&  Y
+\&
+\&  =end inner
+\&
+\&  Z
+\&
+\&  =end outer
+.Ve
+.PP
+while this is invalid:
+.PP
+.Vb 1
+\&  =begin outer
+\&
+\&  X
+\&
+\&  =begin inner
+\&
+\&  Y
+\&
+\&  =end outer
+\&
+\&  Z
+\&
+\&  =end inner
+.Ve
+.PP
+This latter is improper because when the "=end outer" command is seen, the
+currently open region has the formatname "inner", not "outer".  (It just
+happens that "outer" is the format name of a higher-up region.)  This is
+an error.  Processors must by default report this as an error, and may halt
+processing the document containing that error.  A corollary of this is that
+regions cannot "overlap". That is, the latter block above does not represent
+a region called "outer" which contains X and Y, overlapping a region called
+"inner" which contains Y and Z.  But because it is invalid (as all
+apparently overlapping regions would be), it doesn't represent that, or
+anything at all.
+.PP
+Similarly, this is invalid:
+.PP
+.Vb 1
+\&  =begin thing
+\&
+\&  =end hting
+.Ve
+.PP
+This is an error because the region is opened by "thing", and the "=end"
+tries to close "hting" [sic].
+.PP
+This is also invalid:
+.PP
+.Vb 1
+\&  =begin thing
+\&
+\&  =end
+.Ve
+.PP
+This is invalid because every "=end" command must have a formatname
+parameter.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlpod, "PODs: Embedded Documentation" in perlsyn,
+podchecker
+.SH AUTHOR
+.IX Header "AUTHOR"
+Sean M. Burke
diff --git a/upstream/mageia-cauldron/man1/perlpodstyle.1 b/upstream/mageia-cauldron/man1/perlpodstyle.1
new file mode 100644
index 00000000..eb054a6f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpodstyle.1
@@ -0,0 +1,346 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPODSTYLE 1"
+.TH PERLPODSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpodstyle \- Perl POD style guide
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+These are general guidelines for how to write POD documentation for Perl
+scripts and modules, based on general guidelines for writing good UNIX man
+pages.  All of these guidelines are, of course, optional, but following
+them will make your documentation more consistent with other documentation
+on the system.
+.PP
+The name of the program being documented is conventionally written in bold
+(using B<>) wherever it occurs, as are all program options.
+Arguments should be written in italics (I<>).  Function names are
+traditionally written in italics; if you write a function as \fBfunction()\fR,
+Pod::Man will take care of this for you.  Literal code or commands should
+be in C<>.  References to other man pages should be in the form
+\&\f(CWmanpage(section)\fR or \f(CW\*(C`L<manpage(section)>\*(C'\fR, and Pod::Man will
+automatically format those appropriately.  The second form, with
+L<>, is used to request that a POD formatter make a link to the
+man page if possible.  As an exception, one normally omits the section
+when referring to module documentation since it's not clear what section
+module documentation will be in; use \f(CW\*(C`L<Module::Name>\*(C'\fR for module
+references instead.
+.PP
+References to other programs or functions are normally in the form of man
+page references so that cross-referencing tools can provide the user with
+links and the like.  It's possible to overdo this, though, so be careful not
+to clutter your documentation with too much markup.  References to other
+programs that are not given as man page references should be enclosed in
+B<>.
+.PP
+The major headers should be set out using a \f(CW\*(C`=head1\*(C'\fR directive, and are
+historically written in the rather startling ALL UPPER CASE format; this
+is not mandatory, but it's strongly recommended so that sections have
+consistent naming across different software packages.  Minor headers may
+be included using \f(CW\*(C`=head2\*(C'\fR, and are typically in mixed case.
+.PP
+The standard sections of a manual page are:
+.IP NAME 4
+.IX Item "NAME"
+Mandatory section; should be a comma-separated list of programs or
+functions documented by this POD page, such as:
+.Sp
+.Vb 1
+\&    foo, bar \- programs to do something
+.Ve
+.Sp
+Manual page indexers are often extremely picky about the format of this
+section, so don't put anything in it except this line.  Every program or
+function documented by this POD page should be listed, separated by a
+comma and a space.  For a Perl module, just give the module name.  A
+single dash, and only a single dash, should separate the list of programs
+or functions from the description.  Do not use any markup such as
+C<> or B<> anywhere in this line.  Functions should not be
+qualified with \f(CW\*(C`()\*(C'\fR or the like.  The description should ideally fit on a
+single line, even if a man program replaces the dash with a few tabs.
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+A short usage summary for programs and functions.  This section is
+mandatory for section 3 pages.  For Perl module documentation, it's
+usually convenient to have the contents of this section be a verbatim
+block showing some (brief) examples of typical ways the module is used.
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+Extended description and discussion of the program or functions, or the
+body of the documentation for man pages that document something else.  If
+particularly long, it's a good idea to break this up into subsections
+\&\f(CW\*(C`=head2\*(C'\fR directives like:
+.Sp
+.Vb 1
+\&    =head2 Normal Usage
+\&
+\&    =head2 Advanced Features
+\&
+\&    =head2 Writing Configuration Files
+.Ve
+.Sp
+or whatever is appropriate for your documentation.
+.Sp
+For a module, this is generally where the documentation of the interfaces
+provided by the module goes, usually in the form of a list with an
+\&\f(CW\*(C`=item\*(C'\fR for each interface.  Depending on how many interfaces there are,
+you may want to put that documentation in separate METHODS, FUNCTIONS,
+CLASS METHODS, or INSTANCE METHODS sections instead and save the
+DESCRIPTION section for an overview.
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+Detailed description of each of the command-line options taken by the
+program.  This should be separate from the description for the use of
+parsers like Pod::Usage.  This is normally presented as a list, with
+each option as a separate \f(CW\*(C`=item\*(C'\fR.  The specific option string should be
+enclosed in B<>.  Any values that the option takes should be
+enclosed in I<>.  For example, the section for the option
+\&\fB\-\-section\fR=\fImanext\fR would be introduced with:
+.Sp
+.Vb 1
+\&    =item B<\-\-section>=I<manext>
+.Ve
+.Sp
+Synonymous options (like both the short and long forms) are separated by a
+comma and a space on the same \f(CW\*(C`=item\*(C'\fR line, or optionally listed as their
+own item with a reference to the canonical name.  For example, since
+\&\fB\-\-section\fR can also be written as \fB\-s\fR, the above would be:
+.Sp
+.Vb 1
+\&    =item B<\-s> I<manext>, B<\-\-section>=I<manext>
+.Ve
+.Sp
+Writing the short option first is recommended because it's easier to read.
+The long option is long enough to draw the eye to it anyway and the short
+option can otherwise get lost in visual noise.
+.IP "RETURN VALUE" 4
+.IX Item "RETURN VALUE"
+What the program or function returns, if successful.  This section can be
+omitted for programs whose precise exit codes aren't important, provided
+they return 0 on success and non-zero on failure as is standard.  It
+should always be present for functions.  For modules, it may be useful to
+summarize return values from the module interface here, or it may be more
+useful to discuss return values separately in the documentation of each
+function or method the module provides.
+.IP ERRORS 4
+.IX Item "ERRORS"
+Exceptions, error return codes, exit statuses, and errno settings.
+Typically used for function or module documentation; program documentation
+uses DIAGNOSTICS instead.  The general rule of thumb is that errors
+printed to \f(CW\*(C`STDOUT\*(C'\fR or \f(CW\*(C`STDERR\*(C'\fR and intended for the end user are
+documented in DIAGNOSTICS while errors passed internal to the calling
+program and intended for other programmers are documented in ERRORS.  When
+documenting a function that sets errno, a full list of the possible errno
+values should be given here.
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+All possible messages the program can print out and what they mean.  You
+may wish to follow the same documentation style as the Perl documentation;
+see \fBperldiag\fR\|(1) for more details (and look at the POD source as well).
+.Sp
+If applicable, please include details on what the user should do to
+correct the error; documenting an error as indicating "the input buffer is
+too small" without telling the user how to increase the size of the input
+buffer (or at least telling them that it isn't possible) aren't very
+useful.
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+Give some example uses of the program or function.  Don't skimp; users
+often find this the most useful part of the documentation.  The examples
+are generally given as verbatim paragraphs.
+.Sp
+Don't just present an example without explaining what it does.  Adding a
+short paragraph saying what the example will do can increase the value of
+the example immensely.
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+Environment variables that the program cares about, normally presented as
+a list using \f(CW\*(C`=over\*(C'\fR, \f(CW\*(C`=item\*(C'\fR, and \f(CW\*(C`=back\*(C'\fR.  For example:
+.Sp
+.Vb 1
+\&    =over 6
+\&
+\&    =item HOME
+\&
+\&    Used to determine the user\*(Aqs home directory.  F<.foorc> in this
+\&    directory is read for configuration details, if it exists.
+\&
+\&    =back
+.Ve
+.Sp
+Since environment variables are normally in all uppercase, no additional
+special formatting is generally needed; they're glaring enough as it is.
+.IP FILES 4
+.IX Item "FILES"
+All files used by the program or function, normally presented as a list,
+and what it uses them for.  File names should be enclosed in F<>.
+It's particularly important to document files that will be potentially
+modified.
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+Things to take special care with, sometimes called WARNINGS.
+.IP BUGS 4
+.IX Item "BUGS"
+Things that are broken or just don't work quite right.
+.IP RESTRICTIONS 4
+.IX Item "RESTRICTIONS"
+Bugs you don't plan to fix.  :\-)
+.IP NOTES 4
+.IX Item "NOTES"
+Miscellaneous commentary.
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+Who wrote it (use AUTHORS for multiple people).  It's a good idea to
+include your current e\-mail address (or some e\-mail address to which bug
+reports should be sent) or some other contact information so that users
+have a way of contacting you.  Remember that program documentation tends
+to roam the wild for far longer than you expect and pick a contact method
+that's likely to last.
+.IP HISTORY 4
+.IX Item "HISTORY"
+Programs derived from other sources sometimes have this.  Some people keep
+a modification log here, but that usually gets long and is normally better
+maintained in a separate file.
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+For copyright
+.Sp
+.Vb 1
+\&    Copyright YEAR(s) YOUR NAME(s)
+.Ve
+.Sp
+(No, (C) is not needed.  No, "all rights reserved" is not needed.)
+.Sp
+For licensing the easiest way is to use the same licensing as Perl itself:
+.Sp
+.Vb 2
+\&    This library is free software; you may redistribute it and/or
+\&    modify it under the same terms as Perl itself.
+.Ve
+.Sp
+This makes it easy for people to use your module with Perl.  Note that
+this licensing example is neither an endorsement or a requirement, you are
+of course free to choose any licensing.
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+Other man pages to check out, like \fBman\fR\|(1), \fBman\fR\|(7), \fBmakewhatis\fR\|(8), or
+\&\fBcatman\fR\|(8).  Normally a simple list of man pages separated by commas, or a
+paragraph giving the name of a reference work.  Man page references, if
+they use the standard \f(CWname(section)\fR form, don't have to be enclosed in
+L<> (although it's recommended), but other things in this section
+probably should be when appropriate.
+.Sp
+If the package has a mailing list, include a URL or subscription
+instructions here.
+.Sp
+If the package has a web site, include a URL here.
+.PP
+Documentation of object-oriented libraries or modules may want to use
+CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS
+sections, for detailed documentation of the parts of the library and save
+the DESCRIPTION section for an overview.  Large modules with a function
+interface may want to use FUNCTIONS for similar reasons.  Some people use
+OVERVIEW to summarize the description if it's quite long.
+.PP
+Section ordering varies, although NAME must always be the first section
+(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
+DESCRIPTION, and OPTIONS generally always occur first and in that order if
+present.  In general, SEE ALSO, AUTHOR, and similar material should be
+left for last.  Some systems also move WARNINGS and NOTES to last.  The
+order given above should be reasonable for most purposes.
+.PP
+Some systems use CONFORMING TO to note conformance to relevant standards
+and MT-LEVEL to note safeness for use in threaded programs or signal
+handlers.  These headings are primarily useful when documenting parts of a
+C library.
+.PP
+Finally, as a general note, try not to use an excessive amount of markup.
+As documented here and in Pod::Man, you can safely leave Perl
+variables, function names, man page references, and the like unadorned by
+markup and the POD translators will figure it out for you.  This makes it
+much easier to later edit the documentation.  Note that many existing
+translators will do the wrong thing with e\-mail addresses when wrapped in
+L<>, so don't do that.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Russ Allbery <rra@cpan.org>, with large portions of this documentation
+taken from the documentation of the original \fBpod2man\fR implementation by
+Larry Wall and Tom Christiansen.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015, 2018 Russ
+Allbery <rra@cpan.org>
+.PP
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
+.PP
+SPDX-License-Identifier: FSFAP
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+For additional information that may be more accurate for your specific
+system, see either \fBman\fR\|(5) or \fBman\fR\|(7) depending on your system manual
+section numbering conventions.
+.PP
+This documentation is maintained as part of the podlators distribution.
+The current version is always available from its web site at
+<https://www.eyrie.org/~eagle/software/podlators/>.
diff --git a/upstream/mageia-cauldron/man1/perlpolicy.1 b/upstream/mageia-cauldron/man1/perlpolicy.1
new file mode 100644
index 00000000..8d1ed725
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpolicy.1
@@ -0,0 +1,573 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPOLICY 1"
+.TH PERLPOLICY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpolicy \- Various and sundry policies and commitments related to the Perl core
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is the master document which records all written
+policies about how the Perl 5 Porters collectively develop and maintain
+the Perl core.
+.SH GOVERNANCE
+.IX Header "GOVERNANCE"
+.SS "Perl 5 Porters"
+.IX Subsection "Perl 5 Porters"
+Subscribers to perl5\-porters (the porters themselves) come in several flavours.
+Some are quiet curious lurkers, who rarely pitch in and instead watch
+the ongoing development to ensure they're forewarned of new changes or
+features in Perl.  Some are representatives of vendors, who are there
+to make sure that Perl continues to compile and work on their
+platforms.  Some patch any reported bug that they know how to fix,
+some are actively patching their pet area (threads, Win32, the regexp
+\&\-engine), while others seem to do nothing but complain.  In other
+words, it's your usual mix of technical people.
+.PP
+Among these people are the core Perl team.  These are trusted volunteers
+involved in the ongoing development of the Perl language and interpreter.
+They are not required to be language developers or committers.
+.PP
+Over this group of porters presides Larry Wall.  He has the final word
+in what does and does not change in any of the Perl programming languages.
+These days, Larry spends most of his time on Raku, while Perl 5 is
+shepherded by a steering council of porters responsible for deciding what
+goes into each release and ensuring that releases happen on a regular
+basis.
+.PP
+Larry sees Perl development along the lines of the US government:
+there's the Legislature (the porters, represented by the core team), the
+Executive branch (the steering council), and the Supreme Court (Larry).
+The legislature can discuss and submit patches to the executive branch
+all they like, but the executive branch is free to veto them.  Rarely,
+the Supreme Court will side with the executive branch over the
+legislature, or the legislature over the executive branch.  Mostly,
+however, the legislature and the executive branch are supposed to get
+along and work out their differences without impeachment or court cases.
+.PP
+You might sometimes see reference to Rule 1 and Rule 2.  Larry's power
+as Supreme Court is expressed in The Rules:
+.IP 1. 4
+Larry is always by definition right about how Perl should behave.
+This means he has final veto power on the core functionality.
+.IP 2. 4
+Larry is allowed to change his mind about any matter at a later date,
+regardless of whether he previously invoked Rule 1.
+.PP
+Got that?  Larry is always right, even when he was wrong.  It's rare
+to see either Rule exercised, but they are often alluded to.
+.PP
+For the specifics on how the members of the core team and steering
+council are elected or rotated, consult perlgov, which spells it all
+out in detail.
+.SH "MAINTENANCE AND SUPPORT"
+.IX Header "MAINTENANCE AND SUPPORT"
+Perl 5 is developed by a community, not a corporate entity. Every change
+contributed to the Perl core is the result of a donation. Typically, these
+donations are contributions of code or time by individual members of our
+community. On occasion, these donations come in the form of corporate
+or organizational sponsorship of a particular individual or project.
+.PP
+As a volunteer organization, the commitments we make are heavily dependent
+on the goodwill and hard work of individuals who have no obligation to
+contribute to Perl.
+.PP
+That being said, we value Perl's stability and security and have long
+had an unwritten covenant with the broader Perl community to support
+and maintain releases of Perl.
+.PP
+This document codifies the support and maintenance commitments that
+the Perl community should expect from Perl's developers:
+.IP \(bu 4
+We "officially" support the two most recent stable release series.  5.30.x
+and earlier are now out of support.  As of the release of 5.36.0, we will
+"officially" end support for Perl 5.32.x, other than providing security
+updates as described below.
+.IP \(bu 4
+To the best of our ability, we will attempt to fix critical issues
+in the two most recent stable 5.x release series.  Fixes for the
+current release series take precedence over fixes for the previous
+release series.
+.IP \(bu 4
+To the best of our ability, we will provide "critical" security patches
+/ releases for any major version of Perl whose 5.x.0 release was within
+the past three years.  We can only commit to providing these for the
+most recent .y release in any 5.x.y series.
+.IP \(bu 4
+We will not provide security updates or bug fixes for development
+releases of Perl.
+.IP \(bu 4
+We encourage vendors to ship the most recent supported release of
+Perl at the time of their code freeze.
+.IP \(bu 4
+As a vendor, you may have a requirement to backport security fixes
+beyond our 3 year support commitment.  We can provide limited support and
+advice to you as you do so and, where possible will try to apply
+those patches to the relevant \-maint branches in git, though we may or
+may not choose to make numbered releases or "official" patches
+available. See "SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec
+for details on how to begin that process.
+.SH "BACKWARD COMPATIBILITY AND DEPRECATION"
+.IX Header "BACKWARD COMPATIBILITY AND DEPRECATION"
+Our community has a long-held belief that backward-compatibility is a
+virtue, even when the functionality in question is a design flaw.
+.PP
+We would all love to unmake some mistakes we've made over the past
+decades.  Living with every design error we've ever made can lead
+to painful stagnation.  Unwinding our mistakes is very, very
+difficult.  Doing so without actively harming our users is
+nearly impossible.
+.PP
+Lately, ignoring or actively opposing compatibility with earlier versions
+of Perl has come into vogue.  Sometimes, a change is proposed which
+wants to usurp syntax which previously had another meaning.  Sometimes,
+a change wants to improve previously-crazy semantics.
+.PP
+Down this road lies madness.
+.PP
+Requiring end-user programmers to change just a few language constructs,
+even language constructs which no well-educated developer would ever
+intentionally use is tantamount to saying "you should not upgrade to
+a new release of Perl unless you have 100% test coverage and can do a
+full manual audit of your codebase."  If we were to have tools capable of
+reliably upgrading Perl source code from one version of Perl to another,
+this concern could be significantly mitigated.
+.PP
+We want to ensure that Perl continues to grow and flourish in the coming
+years and decades, but not at the expense of our user community.
+.PP
+Existing syntax and semantics should only be marked for destruction in
+very limited circumstances.  If they are believed to be very rarely used,
+stand in the way of actual improvement to the Perl language or perl
+interpreter, and if affected code can be easily updated to continue
+working, they may be considered for removal.  When in doubt, caution
+dictates that we will favor backward compatibility.  When a feature is
+deprecated, a statement of reasoning describing the decision process
+will be posted, and a link to it will be provided in the relevant
+perldelta documents.
+.PP
+Using a lexical pragma to enable or disable legacy behavior should be
+considered when appropriate, and in the absence of any pragma legacy
+behavior should be enabled.  Which backward-incompatible changes are
+controlled implicitly by a 'use v5.x.y' is a decision which should be
+made by the steering council in consultation with the community.
+.PP
+Historically, we've held ourselves to a far higher standard than
+backward-compatibility \-\- bugward-compatibility.  Any accident of
+implementation or unintentional side-effect of running some bit of code
+has been considered to be a feature of the language to be defended with
+the same zeal as any other feature or functionality.  No matter how
+frustrating these unintentional features may be to us as we continue
+to improve Perl, these unintentional features often deserve our
+protection.  It is very important that existing software written in
+Perl continue to work correctly.  If end-user developers have adopted a
+bug as a feature, we need to treat it as such.
+.PP
+New syntax and semantics which don't break existing language constructs
+and syntax have a much lower bar.  They merely need to prove themselves
+to be useful, elegant, well designed, and well tested.  In most cases,
+these additions will be marked as \fIexperimental\fR for some time.  See
+below for more on that.
+.SS Terminology
+.IX Subsection "Terminology"
+To make sure we're talking about the same thing when we discuss the removal
+of features or functionality from the Perl core, we have specific definitions
+for a few words and phrases.
+.IP experimental 4
+.IX Item "experimental"
+If something in the Perl core is marked as \fBexperimental\fR, we may change
+its behaviour, deprecate or remove it without notice. While we'll always
+do our best to smooth the transition path for users of experimental
+features, you should contact the perl5\-porters mailinglist if you find
+an experimental feature useful and want to help shape its future.
+.Sp
+Experimental features must be experimental in two stable releases before being
+marked non-experimental.  Experimental features will only have their
+experimental status revoked when they no longer have any design-changing bugs
+open against them and when they have remained unchanged in behavior for the
+entire length of a development cycle.  In other words, a feature present in
+v5.20.0 may be marked no longer experimental in v5.22.0 if and only if its
+behavior is unchanged throughout all of v5.21.
+.IP deprecated 4
+.IX Item "deprecated"
+If something in the Perl core is marked as \fBdeprecated\fR, we may remove it
+from the core in the future, though we might not.  Generally, backward
+incompatible changes will have deprecation warnings for two release
+cycles before being removed, but may be removed after just one cycle if
+the risk seems quite low or the benefits quite high.
+.Sp
+As of
+Perl 5.12, deprecated features and modules warn the user as they're used.
+When a module is deprecated, it will also be made available on CPAN.
+Installing it from CPAN will silence deprecation warnings for that module.
+.Sp
+If you use a deprecated feature or module and believe that its removal from
+the Perl core would be a mistake, please contact the perl5\-porters
+mailinglist and plead your case.  We don't deprecate things without a good
+reason, but sometimes there's a counterargument we haven't considered.
+Historically, we did not distinguish between "deprecated" and "discouraged"
+features.
+.IP discouraged 4
+.IX Item "discouraged"
+From time to time, we may mark language constructs and features which we
+consider to have been mistakes as \fBdiscouraged\fR.  Discouraged features
+aren't currently candidates for removal, but
+we may later deprecate them if they're found to stand in the way of a
+significant improvement to the Perl core.
+.IP removed 4
+.IX Item "removed"
+Once a feature, construct or module has been marked as deprecated, we
+may remove it from the Perl core.  Unsurprisingly,
+we say we've \fBremoved\fR these things.  When a module is removed, it will
+no longer ship with Perl, but will continue to be available on CPAN.
+.SH "MAINTENANCE BRANCHES"
+.IX Header "MAINTENANCE BRANCHES"
+New releases of maintenance branches should only contain changes that fall into
+one of the "acceptable" categories set out below, but must not contain any
+changes that fall into one of the "unacceptable" categories.  (For example, a
+fix for a crashing bug must not be included if it breaks binary compatibility.)
+.PP
+It is not necessary to include every change meeting these criteria, and in
+general the focus should be on addressing security issues, crashing bugs,
+regressions and serious installation issues.  The temptation to include a
+plethora of minor changes that don't affect the installation or execution of
+perl (e.g. spelling corrections in documentation) should be resisted in order
+to reduce the overall risk of overlooking something.  The intention is to
+create maintenance releases which are both worthwhile and which users can have
+full confidence in the stability of.  (A secondary concern is to avoid burning
+out the maint-release manager or overwhelming other committers voting on
+changes to be included (see "Getting changes into a maint branch"
+below).)
+.PP
+The following types of change may be considered acceptable, as long as they do
+not also fall into any of the "unacceptable" categories set out below:
+.IP \(bu 4
+Patches that fix CVEs or security issues.  These changes should
+be passed using the security reporting mechanism rather than applied
+directly; see "SECURITY VULNERABILITY CONTACT INFORMATION" in perlsec.
+.IP \(bu 4
+Patches that fix crashing bugs, assertion failures and
+memory corruption but which do not otherwise change perl's
+functionality or negatively impact performance.
+.IP \(bu 4
+Patches that fix regressions in perl's behavior relative to previous
+releases, no matter how old the regression, since some people may
+upgrade from very old versions of perl to the latest version.
+.IP \(bu 4
+Patches that fix bugs in features that were new in the corresponding 5.x.0
+stable release.
+.IP \(bu 4
+Patches that fix anything which prevents or seriously impacts the build
+or installation of perl.
+.IP \(bu 4
+Portability fixes, such as changes to Configure and the files in
+the hints/ folder.
+.IP \(bu 4
+Minimal patches that fix platform-specific test failures.
+.IP \(bu 4
+Documentation updates that correct factual errors, explain significant
+bugs or deficiencies in the current implementation, or fix broken markup.
+.IP \(bu 4
+Updates to dual-life modules should consist of minimal patches to
+fix crashing bugs or security issues (as above).  Any changes made to
+dual-life modules for which CPAN is canonical should be coordinated with
+the upstream author.
+.PP
+The following types of change are NOT acceptable:
+.IP \(bu 4
+Patches that break binary compatibility.  (Please talk to the steering
+council.)
+.IP \(bu 4
+Patches that add or remove features.
+.IP \(bu 4
+Patches that add new warnings or errors or deprecate features.
+.IP \(bu 4
+Ports of Perl to a new platform, architecture or OS release that
+involve changes to the implementation.
+.IP \(bu 4
+New versions of dual-life modules should NOT be imported into maint.
+Those belong in the next stable series.
+.PP
+If there is any question about whether a given patch might merit
+inclusion in a maint release, then it almost certainly should not
+be included.
+.SS "Getting changes into a maint branch"
+.IX Subsection "Getting changes into a maint branch"
+Historically, only the single-person project manager cherry-picked
+changes from bleadperl into maintperl.  This has scaling problems.  At
+the same time, maintenance branches of stable versions of Perl need to
+be treated with great care.  To that end, as of Perl 5.12, we have a new
+process for maint branches.
+.PP
+Any committer may cherry-pick any commit from blead to a maint branch by
+first adding an entry to the relevant voting file in the maint-votes branch
+announcing the commit as a candidate for back-porting, and then waiting for
+at least two other committers to add their votes in support of this (i.e. a
+total of at least three votes is required before a commit may be back-ported).
+.PP
+Most of the work involved in both rounding up a suitable set of candidate
+commits and cherry-picking those for which three votes have been cast will
+be done by the maint branch release manager, but anyone else is free to add
+other proposals if they're keen to ensure certain fixes don't get overlooked
+or fear they already have been.
+.PP
+Other voting mechanisms may also be used instead (e.g. sending mail to
+perl5\-porters and at least two other committers responding to the list
+giving their assent), as long as the same number of votes is gathered in a
+transparent manner.  Specifically, proposals of which changes to cherry-pick
+must be visible to everyone on perl5\-porters so that the views of everyone
+interested may be heard.
+.PP
+It is not necessary for voting to be held on cherry-picking perldelta
+entries associated with changes that have already been cherry-picked, nor
+for the maint-release manager to obtain votes on changes required by the
+\&\fIPorting/release_managers_guide.pod\fR where such changes can be applied by
+the means of cherry-picking from blead.
+.SH "CONTRIBUTED MODULES"
+.IX Header "CONTRIBUTED MODULES"
+.SS "A Social Contract about Artistic Control"
+.IX Subsection "A Social Contract about Artistic Control"
+What follows is a statement about artistic control, defined as the ability
+of authors of packages to guide the future of their code and maintain
+control over their work.  It is a recognition that authors should have
+control over their work, and that it is a responsibility of the rest of
+the Perl community to ensure that they retain this control.  It is an
+attempt to document the standards to which we, as Perl developers, intend
+to hold ourselves.  It is an attempt to write down rough guidelines about
+the respect we owe each other as Perl developers.
+.PP
+This statement is not a legal contract.  This statement is not a legal
+document in any way, shape, or form.  Perl is distributed under the GNU
+Public License and under the Artistic License; those are the precise legal
+terms.  This statement isn't about the law or licenses.  It's about
+community, mutual respect, trust, and good-faith cooperation.
+.PP
+We recognize that the Perl core, defined as the software distributed with
+the heart of Perl itself, is a joint project on the part of all of us.
+From time to time, a script, module, or set of modules (hereafter referred
+to simply as a "module") will prove so widely useful and/or so integral to
+the correct functioning of Perl itself that it should be distributed with
+the Perl core.  This should never be done without the author's explicit
+consent, and a clear recognition on all parts that this means the module
+is being distributed under the same terms as Perl itself.  A module author
+should realize that inclusion of a module into the Perl core will
+necessarily mean some loss of control over it, since changes may
+occasionally have to be made on short notice or for consistency with the
+rest of Perl.
+.PP
+Once a module has been included in the Perl core, however, everyone
+involved in maintaining Perl should be aware that the module is still the
+property of the original author unless the original author explicitly
+gives up their ownership of it.  In particular:
+.IP \(bu 4
+The version of the module in the Perl core should still be considered the
+work of the original author.  All patches, bug reports, and so
+forth should be fed back to them.  Their development directions
+should be respected whenever possible.
+.IP \(bu 4
+Patches may be applied by the steering council without the explicit
+cooperation of the module author if and only if they are very minor,
+time-critical in some fashion (such as urgent security fixes), or if
+the module author cannot be reached.  Those patches must still be
+given back to the author when possible, and if the author decides on
+an alternate fix in their version, that fix should be strongly
+preferred unless there is a serious problem with it.  Any changes not
+endorsed by the author should be marked as such, and the contributor
+of the change acknowledged.
+.IP \(bu 4
+The version of the module distributed with Perl should, whenever
+possible, be the latest version of the module as distributed by the
+author (the latest non-beta version in the case of public Perl
+releases), although the steering council may hold off on upgrading the
+version of the module distributed with Perl to the latest version
+until the latest version has had sufficient testing.
+.PP
+In other words, the author of a module should be considered to have final
+say on modifications to their module whenever possible (bearing in mind
+that it's expected that everyone involved will work together and arrive at
+reasonable compromises when there are disagreements).
+.PP
+As a last resort, however:
+.PP
+If the author's vision of the future of their module is sufficiently
+different from the vision of the steering council and perl5\-porters as a
+whole so as to cause serious problems for Perl, the steering council may
+choose to formally fork the version of the module in the Perl core from the
+one maintained by the author.  This should not be done lightly and
+should \fBalways\fR if at all possible be done only after direct input
+from Larry.  If this is done, it must then be made explicit in the
+module as distributed with the Perl core that it is a forked version and
+that while it is based on the original author's work, it is no longer
+maintained by them.  This must be noted in both the documentation and
+in the comments in the source of the module.
+.PP
+Again, this should be a last resort only.  Ideally, this should never
+happen, and every possible effort at cooperation and compromise should be
+made before doing this.  If it does prove necessary to fork a module for
+the overall health of Perl, proper credit must be given to the original
+author in perpetuity and the decision should be constantly re-evaluated to
+see if a remerging of the two branches is possible down the road.
+.PP
+In all dealings with contributed modules, everyone maintaining Perl should
+keep in mind that the code belongs to the original author, that they may
+not be on perl5\-porters at any given time, and that a patch is not
+official unless it has been integrated into the author's copy of the
+module.  To aid with this, and with points #1, #2, and #3 above, contact
+information for the authors of all contributed modules should be kept with
+the Perl distribution.
+.PP
+Finally, the Perl community as a whole recognizes that respect for
+ownership of code, respect for artistic control, proper credit, and active
+effort to prevent unintentional code skew or communication gaps is vital
+to the health of the community and Perl itself.  Members of a community
+should not normally have to resort to rules and laws to deal with each
+other, and this document, although it contains rules so as to be clear, is
+about an attitude and general approach.  The first step in any dispute
+should be open communication, respect for opposing views, and an attempt
+at a compromise.  In nearly every circumstance nothing more will be
+necessary, and certainly no more drastic measure should be used until
+every avenue of communication and discussion has failed.
+.SH DOCUMENTATION
+.IX Header "DOCUMENTATION"
+Perl's documentation is an important resource for our users. It's
+incredibly important for Perl's documentation to be reasonably coherent
+and to accurately reflect the current implementation.
+.PP
+Just as P5P collectively maintains the codebase, we collectively
+maintain the documentation.  Writing a particular bit of documentation
+doesn't give an author control of the future of that documentation.
+At the same time, just as source code changes should match the style
+of their surrounding blocks, so should documentation changes.
+.PP
+Examples in documentation should be illustrative of the concept
+they're explaining.  Sometimes, the best way to show how a
+language feature works is with a small program the reader can
+run without modification.  More often, examples will consist
+of a snippet of code containing only the "important" bits.
+The definition of "important" varies from snippet to snippet.
+Sometimes it's important to declare \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR,
+initialize all variables and fully catch every error condition.
+More often than not, though, those things obscure the lesson
+the example was intended to teach.
+.PP
+As Perl is developed by a global team of volunteers, our
+documentation often contains spellings which look funny
+to \fIsomebody\fR.  Choice of American/British/Other spellings
+is left as an exercise for the author of each bit of
+documentation.  When patching documentation, try to emulate
+the documentation around you, rather than changing the existing
+prose.
+.PP
+In general, documentation should describe what Perl does "now" rather
+than what it used to do.  It's perfectly reasonable to include notes
+in documentation about how behaviour has changed from previous releases,
+but, with very few exceptions, documentation isn't "dual-life" \-\-
+it doesn't need to fully describe how all old versions used to work.
+.SH "STANDARDS OF CONDUCT"
+.IX Header "STANDARDS OF CONDUCT"
+The official forum for the development of perl is the perl5\-porters mailing
+list, mentioned above, and its bugtracker at GitHub.  Posting to the
+list and the bugtracker is not a right: all participants in discussion are
+expected to adhere to a standard of conduct.
+.IP \(bu 4
+Always be civil.
+.IP \(bu 4
+Heed the moderators.
+.PP
+Civility is simple: stick to the facts while avoiding demeaning remarks,
+belittling other individuals, sarcasm, or a presumption of bad faith. It is
+not enough to be factual.  You must also be civil.  Responding in kind to
+incivility is not acceptable.  If you relay otherwise-unposted comments to
+the list from a third party, you take responsibility for the content of
+those comments, and you must therefore ensure that they are civil.
+.PP
+While civility is required, kindness is encouraged; if you have any doubt about
+whether you are being civil, simply ask yourself, "Am I being kind?" and aspire
+to that.
+.PP
+If the list moderators tell you that you are not being civil, carefully
+consider how your words have appeared before responding in any way.  Were they
+kind?  You may protest, but repeated protest in the face of a repeatedly
+reaffirmed decision is not acceptable.  Repeatedly protesting about the
+moderators' decisions regarding a third party is also unacceptable, as is
+continuing to initiate off-list contact with the moderators about their
+decisions.
+.PP
+Unacceptable behavior will result in a public and clearly identified
+warning.  A second instance of unacceptable behavior from the same
+individual will result in removal from the mailing list and GitHub issue
+tracker, for a period of one calendar month.  The rationale for this is to
+provide an opportunity for the person to change the way they act.
+.PP
+After the time-limited ban has been lifted, a third instance of
+unacceptable behavior will result in a further public warning.  A fourth
+or subsequent instance will result in an indefinite ban.  The rationale
+is that, in the face of an apparent refusal to change behavior, we must
+protect other community members from future unacceptable actions.  The
+moderators may choose to lift an indefinite ban if the person in
+question affirms they will not transgress again.
+.PP
+Removals, like warnings, are public.
+.PP
+The list of moderators will be public knowledge.  At present, it is:
+Karen Etheridge, Neil Bowers, Nicholas Clark, Ricardo Signes, Todd Rinaldo.
+.SH CREDITS
+.IX Header "CREDITS"
+"Social Contract about Contributed Modules" originally by Russ Allbery <rra@stanford.edu> and the perl5\-porters.
diff --git a/upstream/mageia-cauldron/man1/perlport.1 b/upstream/mageia-cauldron/man1/perlport.1
new file mode 100644
index 00000000..20012c74
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlport.1
@@ -0,0 +1,2552 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPORT 1"
+.TH PERLPORT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlport \- Writing portable Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl runs on numerous operating systems.  While most of them share
+much in common, they also have their own unique features.
+.PP
+This document is meant to help you to find out what constitutes portable
+Perl code.  That way once you make a decision to write portably,
+you know where the lines are drawn, and you can stay within them.
+.PP
+There is a tradeoff between taking full advantage of one particular
+type of computer and taking advantage of a full range of them.
+Naturally, as you broaden your range and become more diverse, the
+common factors drop, and you are left with an increasingly smaller
+area of common ground in which you can operate to accomplish a
+particular task.  Thus, when you begin attacking a problem, it is
+important to consider under which part of the tradeoff curve you
+want to operate.  Specifically, you must decide whether it is
+important that the task that you are coding has the full generality
+of being portable, or whether to just get the job done right now.
+This is the hardest choice to be made.  The rest is easy, because
+Perl provides many choices, whichever way you want to approach your
+problem.
+.PP
+Looking at it another way, writing portable code is usually about
+willfully limiting your available choices.  Naturally, it takes
+discipline and sacrifice to do that.  The product of portability
+and convenience may be a constant.  You have been warned.
+.PP
+Be aware of two important points:
+.IP "Not all Perl programs have to be portable" 4
+.IX Item "Not all Perl programs have to be portable"
+There is no reason you should not use Perl as a language to glue Unix
+tools together, or to prototype a Macintosh application, or to manage the
+Windows registry.  If it makes no sense to aim for portability for one
+reason or another in a given program, then don't bother.
+.IP "Nearly all of Perl already \fIis\fR portable" 4
+.IX Item "Nearly all of Perl already is portable"
+Don't be fooled into thinking that it is hard to create portable Perl
+code.  It isn't.  Perl tries its level-best to bridge the gaps between
+what's available on different platforms, and all the means available to
+use those features.  Thus almost all Perl code runs on any machine
+without modification.  But there are some significant issues in
+writing portable code, and this document is entirely about those issues.
+.PP
+Here's the general rule: When you approach a task commonly done
+using a whole range of platforms, think about writing portable
+code.  That way, you don't sacrifice much by way of the implementation
+choices you can avail yourself of, and at the same time you can give
+your users lots of platform choices.  On the other hand, when you have to
+take advantage of some unique feature of a particular platform, as is
+often the case with systems programming (whether for Unix, Windows,
+VMS, etc.), consider writing platform-specific code.
+.PP
+When the code will run on only two or three operating systems, you
+may need to consider only the differences of those particular systems.
+The important thing is to decide where the code will run and to be
+deliberate in your decision.
+.PP
+The material below is separated into three main sections: main issues of
+portability ("ISSUES"), platform-specific issues ("PLATFORMS"), and
+built-in Perl functions that behave differently on various ports
+("FUNCTION IMPLEMENTATIONS").
+.PP
+This information should not be considered complete; it includes possibly
+transient information about idiosyncrasies of some of the ports, almost
+all of which are in a state of constant evolution.  Thus, this material
+should be considered a perpetual work in progress
+(\f(CW\*(C`<IMG SRC="yellow_sign.gif" ALT="Under Construction">\*(C'\fR).
+.SH ISSUES
+.IX Header "ISSUES"
+.SS Newlines
+.IX Subsection "Newlines"
+In most operating systems, lines in files are terminated by newlines.
+Just what is used as a newline may vary from OS to OS.  Unix
+traditionally uses \f(CW\*(C`\e012\*(C'\fR, one type of DOSish I/O uses \f(CW\*(C`\e015\e012\*(C'\fR,
+Mac\ OS uses \f(CW\*(C`\e015\*(C'\fR, and z/OS uses \f(CW\*(C`\e025\*(C'\fR.
+.PP
+Perl uses \f(CW\*(C`\en\*(C'\fR to represent the "logical" newline, where what is
+logical may depend on the platform in use.  In MacPerl, \f(CW\*(C`\en\*(C'\fR always
+means \f(CW\*(C`\e015\*(C'\fR.  On EBCDIC platforms, \f(CW\*(C`\en\*(C'\fR could be \f(CW\*(C`\e025\*(C'\fR or \f(CW\*(C`\e045\*(C'\fR.
+In DOSish perls, \f(CW\*(C`\en\*(C'\fR usually means \f(CW\*(C`\e012\*(C'\fR, but when
+accessing a file in "text" mode, perl uses the \f(CW\*(C`:crlf\*(C'\fR layer that
+translates it to (or from) \f(CW\*(C`\e015\e012\*(C'\fR, depending on whether you're
+reading or writing. Unix does the same thing on ttys in canonical
+mode.  \f(CW\*(C`\e015\e012\*(C'\fR is commonly referred to as CRLF.
+.PP
+To trim trailing newlines from text lines use
+\&\f(CW\*(C`chomp\*(C'\fR.  With default settings that function
+looks for a trailing \f(CW\*(C`\en\*(C'\fR character and thus trims in a portable way.
+.PP
+When dealing with binary files (or text files in binary mode) be sure
+to explicitly set \f(CW$/\fR to the appropriate value for
+your file format before using \f(CW\*(C`chomp\*(C'\fR.
+.PP
+Because of the "text" mode translation, DOSish perls have limitations in
+using \f(CW\*(C`seek\*(C'\fR and
+\&\f(CW\*(C`tell\*(C'\fR on a file accessed in "text" mode.
+Stick to \f(CW\*(C`seek\*(C'\fR\-ing to
+locations you got from \f(CW\*(C`tell\*(C'\fR (and no
+others), and you are usually free to use
+\&\f(CW\*(C`seek\*(C'\fR and
+\&\f(CW\*(C`tell\*(C'\fR even in "text" mode.  Using
+\&\f(CW\*(C`seek\*(C'\fR or
+\&\f(CW\*(C`tell\*(C'\fR or other file operations may be
+non-portable.  If you use \f(CW\*(C`binmode\*(C'\fR on a
+file, however, you can usually
+\&\f(CW\*(C`seek\*(C'\fR and
+\&\f(CW\*(C`tell\*(C'\fR with arbitrary values safely.
+.PP
+A common misconception in socket programming is that \f(CW\*(C`\en\ eq\ \e012\*(C'\fR
+everywhere.  When using protocols such as common Internet protocols,
+\&\f(CW\*(C`\e012\*(C'\fR and \f(CW\*(C`\e015\*(C'\fR are called for specifically, and the values of
+the logical \f(CW\*(C`\en\*(C'\fR and \f(CW\*(C`\er\*(C'\fR (carriage return) are not reliable.
+.PP
+.Vb 2
+\&    print $socket "Hi there, client!\er\en";      # WRONG
+\&    print $socket "Hi there, client!\e015\e012";  # RIGHT
+.Ve
+.PP
+However, using \f(CW\*(C`\e015\e012\*(C'\fR (or \f(CW\*(C`\ecM\ecJ\*(C'\fR, or \f(CW\*(C`\ex0D\ex0A\*(C'\fR) can be tedious
+and unsightly, as well as confusing to those maintaining the code.  As
+such, the \f(CW\*(C`Socket\*(C'\fR module supplies the Right Thing for those
+who want it.
+.PP
+.Vb 2
+\&    use Socket qw(:DEFAULT :crlf);
+\&    print $socket "Hi there, client!$CRLF"      # RIGHT
+.Ve
+.PP
+When reading from a socket, remember that the default input record
+separator \f(CW$/\fR is \f(CW\*(C`\en\*(C'\fR, but robust socket code
+will recognize as either \f(CW\*(C`\e012\*(C'\fR or \f(CW\*(C`\e015\e012\*(C'\fR as end of line:
+.PP
+.Vb 3
+\&    while (<$socket>) {  # NOT ADVISABLE!
+\&        # ...
+\&    }
+.Ve
+.PP
+Because both CRLF and LF end in LF, the input record separator can
+be set to LF and any CR stripped later.  Better to write:
+.PP
+.Vb 2
+\&    use Socket qw(:DEFAULT :crlf);
+\&    local($/) = LF;      # not needed if $/ is already \e012
+\&
+\&    while (<$socket>) {
+\&        s/$CR?$LF/\en/;   # not sure if socket uses LF or CRLF, OK
+\&    #   s/\e015?\e012/\en/; # same thing
+\&    }
+.Ve
+.PP
+This example is preferred over the previous one\-\-even for Unix
+platforms\-\-because now any \f(CW\*(C`\e015\*(C'\fR's (\f(CW\*(C`\ecM\*(C'\fR's) are stripped out
+(and there was much rejoicing).
+.PP
+Similarly, functions that return text data\-\-such as a function that
+fetches a web page\-\-should sometimes translate newlines before
+returning the data, if they've not yet been translated to the local
+newline representation.  A single line of code will often suffice:
+.PP
+.Vb 2
+\&    $data =~ s/\e015?\e012/\en/g;
+\&    return $data;
+.Ve
+.PP
+Some of this may be confusing.  Here's a handy reference to the ASCII CR
+and LF characters.  You can print it out and stick it in your wallet.
+.PP
+.Vb 2
+\&    LF  eq  \e012  eq  \ex0A  eq  \ecJ  eq  chr(10)  eq  ASCII 10
+\&    CR  eq  \e015  eq  \ex0D  eq  \ecM  eq  chr(13)  eq  ASCII 13
+\&
+\&             | Unix | DOS  | Mac  |
+\&        \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&        \en   |  LF  |  LF  |  CR  |
+\&        \er   |  CR  |  CR  |  LF  |
+\&        \en * |  LF  | CRLF |  CR  |
+\&        \er * |  CR  |  CR  |  LF  |
+\&        \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&        * text\-mode STDIO
+.Ve
+.PP
+The Unix column assumes that you are not accessing a serial line
+(like a tty) in canonical mode.  If you are, then CR on input becomes
+"\en", and "\en" on output becomes CRLF.
+.PP
+These are just the most common definitions of \f(CW\*(C`\en\*(C'\fR and \f(CW\*(C`\er\*(C'\fR in Perl.
+There may well be others.  For example, on an EBCDIC implementation
+such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based)
+the above material is similar to "Unix" but the code numbers change:
+.PP
+.Vb 4
+\&    LF  eq  \e025  eq  \ex15  eq  \ecU  eq  chr(21)  eq  CP\-1047 21
+\&    LF  eq  \e045  eq  \ex25  eq           chr(37)  eq  CP\-0037 37
+\&    CR  eq  \e015  eq  \ex0D  eq  \ecM  eq  chr(13)  eq  CP\-1047 13
+\&    CR  eq  \e015  eq  \ex0D  eq  \ecM  eq  chr(13)  eq  CP\-0037 13
+\&
+\&             | z/OS | OS/400 |
+\&        \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&        \en   |  LF  |  LF    |
+\&        \er   |  CR  |  CR    |
+\&        \en * |  LF  |  LF    |
+\&        \er * |  CR  |  CR    |
+\&        \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&        * text\-mode STDIO
+.Ve
+.SS "Numbers endianness and Width"
+.IX Subsection "Numbers endianness and Width"
+Different CPUs store integers and floating point numbers in different
+orders (called \fIendianness\fR) and widths (32\-bit and 64\-bit being the
+most common today).  This affects your programs when they attempt to transfer
+numbers in binary format from one CPU architecture to another,
+usually either "live" via network connection, or by storing the
+numbers to secondary storage such as a disk file or tape.
+.PP
+Conflicting storage orders make an utter mess out of the numbers.  If a
+little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
+decimal), a big-endian host (Motorola, Sparc, PA) reads it as
+0x78563412 (2018915346 in decimal).  Alpha and MIPS can be either:
+Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
+them in big-endian mode.  To avoid this problem in network (socket)
+connections use the \f(CW\*(C`pack\*(C'\fR and
+\&\f(CW\*(C`unpack\*(C'\fR formats \f(CW\*(C`n\*(C'\fR and \f(CW\*(C`N\*(C'\fR, the
+"network" orders.  These are guaranteed to be portable.
+.PP
+As of Perl 5.10.0, you can also use the \f(CW\*(C`>\*(C'\fR and \f(CW\*(C`<\*(C'\fR modifiers
+to force big\- or little-endian byte-order.  This is useful if you want
+to store signed integers or 64\-bit integers, for example.
+.PP
+You can explore the endianness of your platform by unpacking a
+data structure packed in native format such as:
+.PP
+.Vb 3
+\&    print unpack("h*", pack("s2", 1, 2)), "\en";
+\&    # \*(Aq10002000\*(Aq on e.g. Intel x86 or Alpha 21064 in little\-endian mode
+\&    # \*(Aq00100020\*(Aq on e.g. Motorola 68040
+.Ve
+.PP
+If you need to distinguish between endian architectures you could use
+either of the variables set like so:
+.PP
+.Vb 2
+\&    $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
+\&    $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
+.Ve
+.PP
+Differing widths can cause truncation even between platforms of equal
+endianness.  The platform of shorter width loses the upper parts of the
+number.  There is no good solution for this problem except to avoid
+transferring or storing raw binary numbers.
+.PP
+One can circumnavigate both these problems in two ways.  Either
+transfer and store numbers always in text format, instead of raw
+binary, or else consider using modules like
+\&\f(CW\*(C`Data::Dumper\*(C'\fR and \f(CW\*(C`Storable\*(C'\fR (included as
+of Perl 5.8).  Keeping all data as text significantly simplifies matters.
+.SS "Files and Filesystems"
+.IX Subsection "Files and Filesystems"
+Most platforms these days structure files in a hierarchical fashion.
+So, it is reasonably safe to assume that all platforms support the
+notion of a "path" to uniquely identify a file on the system.  How
+that path is really written, though, differs considerably.
+.PP
+Although similar, file path specifications differ between Unix,
+Windows, Mac\ OS, OS/2, VMS, VOS, RISC\ OS, and probably others.
+Unix, for example, is one of the few OSes that has the elegant idea
+of a single root directory.
+.PP
+DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with \f(CW\*(C`/\*(C'\fR
+as path separator, or in their own idiosyncratic ways (such as having
+several root directories and various "unrooted" device files such NIL:
+and LPT:).
+.PP
+Mac\ OS 9 and earlier used \f(CW\*(C`:\*(C'\fR as a path separator instead of \f(CW\*(C`/\*(C'\fR.
+.PP
+The filesystem may support neither hard links
+(\f(CW\*(C`link\*(C'\fR) nor symbolic links
+(\f(CW\*(C`symlink\*(C'\fR,
+\&\f(CW\*(C`readlink\*(C'\fR,
+\&\f(CW\*(C`lstat\*(C'\fR).
+.PP
+The filesystem may support neither access timestamp nor change
+timestamp (meaning that about the only portable timestamp is the
+modification timestamp), or one second granularity of any timestamps
+(e.g. the FAT filesystem limits the time granularity to two seconds).
+.PP
+The "inode change timestamp" (the \f(CW\*(C`\-C\*(C'\fR
+filetest) may really be the "creation timestamp" (which it is not in
+Unix).
+.PP
+VOS perl can emulate Unix filenames with \f(CW\*(C`/\*(C'\fR as path separator.  The
+native pathname characters greater-than, less-than, number-sign, and
+percent-sign are always accepted.
+.PP
+RISC\ OS perl can emulate Unix filenames with \f(CW\*(C`/\*(C'\fR as path
+separator, or go native and use \f(CW\*(C`.\*(C'\fR for path separator and \f(CW\*(C`:\*(C'\fR to
+signal filesystems and disk names.
+.PP
+Don't assume Unix filesystem access semantics: that read, write,
+and execute are all the permissions there are, and even if they exist,
+that their semantics (for example what do \f(CW\*(C`r\*(C'\fR, \f(CW\*(C`w\*(C'\fR, and \f(CW\*(C`x\*(C'\fR mean on
+a directory) are the Unix ones.  The various Unix/POSIX compatibility
+layers usually try to make interfaces like \f(CW\*(C`chmod\*(C'\fR
+work, but sometimes there simply is no good mapping.
+.PP
+The \f(CW\*(C`File::Spec\*(C'\fR modules provide methods to manipulate path
+specifications and return the results in native format for each
+platform.  This is often unnecessary as Unix-style paths are
+understood by Perl on every supported platform, but if you need to
+produce native paths for a native utility that does not understand
+Unix syntax, or if you are operating on paths or path components
+in unknown (and thus possibly native) syntax, \f(CW\*(C`File::Spec\*(C'\fR
+is your friend.  Here are two brief examples:
+.PP
+.Vb 2
+\&    use File::Spec::Functions;
+\&    chdir(updir());        # go up one directory
+\&
+\&    # Concatenate a path from its components
+\&    my $file = catfile(updir(), \*(Aqtemp\*(Aq, \*(Aqfile.txt\*(Aq);
+\&    # on Unix:    \*(Aq../temp/file.txt\*(Aq
+\&    # on Win32:   \*(Aq..\etemp\efile.txt\*(Aq
+\&    # on VMS:     \*(Aq[\-.temp]file.txt\*(Aq
+.Ve
+.PP
+In general, production code should not have file paths hardcoded.
+Making them user-supplied or read from a configuration file is
+better, keeping in mind that file path syntax varies on different
+machines.
+.PP
+This is especially noticeable in scripts like Makefiles and test suites,
+which often assume \f(CW\*(C`/\*(C'\fR as a path separator for subdirectories.
+.PP
+Also of use is \f(CW\*(C`File::Basename\*(C'\fR from the standard
+distribution, which splits a pathname into pieces (base filename, full
+path to directory, and file suffix).
+.PP
+Even when on a single platform (if you can call Unix a single platform),
+remember not to count on the existence or the contents of particular
+system-specific files or directories, like \fI/etc/passwd\fR,
+\&\fI/etc/sendmail.conf\fR, \fI/etc/resolv.conf\fR, or even \fI/tmp/\fR.  For
+example, \fI/etc/passwd\fR may exist but not contain the encrypted
+passwords, because the system is using some form of enhanced security.
+Or it may not contain all the accounts, because the system is using NIS.
+If code does need to rely on such a file, include a description of the
+file and its format in the code's documentation, then make it easy for
+the user to override the default location of the file.
+.PP
+Don't assume a text file will end with a newline.  They should,
+but people forget.
+.PP
+Do not have two files or directories of the same name with different
+case, like \fItest.pl\fR and \fITest.pl\fR, as many platforms have
+case-insensitive (or at least case-forgiving) filenames.  Also, try
+not to have non-word characters (except for \f(CW\*(C`.\*(C'\fR) in the names, and
+keep them to the 8.3 convention, for maximum portability, onerous a
+burden though this may appear.
+.PP
+Likewise, when using the \f(CW\*(C`AutoSplit\*(C'\fR module, try to keep
+your functions to 8.3 naming and case-insensitive conventions; or, at the
+least, make it so the resulting files have a unique (case-insensitively)
+first 8 characters.
+.PP
+Whitespace in filenames is tolerated on most systems, but not all,
+and even on systems where it might be tolerated, some utilities
+might become confused by such whitespace.
+.PP
+Many systems (DOS, VMS ODS\-2) cannot have more than one \f(CW\*(C`.\*(C'\fR in their
+filenames.
+.PP
+Don't assume \f(CW\*(C`>\*(C'\fR won't be the first character of a filename.
+Always use the three-arg version of
+\&\f(CW\*(C`open\*(C'\fR:
+.PP
+.Vb 1
+\&    open my $fh, \*(Aq<\*(Aq, $existing_file) or die $!;
+.Ve
+.PP
+Two-arg \f(CW\*(C`open\*(C'\fR is magic and can
+translate characters like \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`<\*(C'\fR, and \f(CW\*(C`|\*(C'\fR in filenames,
+which is usually the wrong thing to do.
+\&\f(CW\*(C`sysopen\*(C'\fR and three-arg
+\&\f(CW\*(C`open\*(C'\fR don't have this problem.
+.PP
+Don't use \f(CW\*(C`:\*(C'\fR as a part of a filename since many systems use that for
+their own semantics (Mac OS Classic for separating pathname components,
+many networking schemes and utilities for separating the nodename and
+the pathname, and so on).  For the same reasons, avoid \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`;\*(C'\fR and
+\&\f(CW\*(C`|\*(C'\fR.
+.PP
+Don't assume that in pathnames you can collapse two leading slashes
+\&\f(CW\*(C`//\*(C'\fR into one: some networking and clustering filesystems have special
+semantics for that.  Let the operating system sort it out.
+.PP
+The \fIportable filename characters\fR as defined by ANSI C are
+.PP
+.Vb 4
+\& a b c d e f g h i j k l m n o p q r s t u v w x y z
+\& A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
+\& 0 1 2 3 4 5 6 7 8 9
+\& . _ \-
+.Ve
+.PP
+and \f(CW\*(C`\-\*(C'\fR shouldn't be the first character.  If you want to be
+hypercorrect, stay case-insensitive and within the 8.3 naming
+convention (all the files and directories have to be unique within one
+directory if their names are lowercased and truncated to eight
+characters before the \f(CW\*(C`.\*(C'\fR, if any, and to three characters after the
+\&\f(CW\*(C`.\*(C'\fR, if any).  (And do not use \f(CW\*(C`.\*(C'\fRs in directory names.)
+.SS "System Interaction"
+.IX Subsection "System Interaction"
+Not all platforms provide a command line.  These are usually platforms
+that rely primarily on a Graphical User Interface (GUI) for user
+interaction.  A program requiring a command line interface might
+not work everywhere.  This is probably for the user of the program
+to deal with, so don't stay up late worrying about it.
+.PP
+Some platforms can't delete or rename files held open by the system,
+this limitation may also apply to changing filesystem metainformation
+like file permissions or owners.  Remember to
+\&\f(CW\*(C`close\*(C'\fR files when you are done with them.
+Don't \f(CW\*(C`unlink\*(C'\fR or
+\&\f(CW\*(C`rename\*(C'\fR an open file.  Don't
+\&\f(CW\*(C`tie\*(C'\fR or
+\&\f(CW\*(C`open\*(C'\fR a file already tied or opened;
+\&\f(CW\*(C`untie\*(C'\fR or
+\&\f(CW\*(C`close\*(C'\fR it first.
+.PP
+Don't open the same file more than once at a time for writing, as some
+operating systems put mandatory locks on such files.
+.PP
+Don't assume that write/modify permission on a directory gives the
+right to add or delete files/directories in that directory.  That is
+filesystem specific: in some filesystems you need write/modify
+permission also (or even just) in the file/directory itself.  In some
+filesystems (AFS, DFS) the permission to add/delete directory entries
+is a completely separate permission.
+.PP
+Don't assume that a single \f(CW\*(C`unlink\*(C'\fR completely
+gets rid of the file: some filesystems (most notably the ones in VMS) have
+versioned filesystems, and \f(CW\*(C`unlink\*(C'\fR removes only
+the most recent one (it doesn't remove all the versions because by default
+the native tools on those platforms remove just the most recent version,
+too).  The portable idiom to remove all the versions of a file is
+.PP
+.Vb 1
+\&    1 while unlink "file";
+.Ve
+.PP
+This will terminate if the file is undeletable for some reason
+(protected, not there, and so on).
+.PP
+Don't count on a specific environment variable existing in
+\&\f(CW%ENV\fR.  Don't count on \f(CW%ENV\fR entries
+being case-sensitive, or even case-preserving.  Don't try to clear
+\&\f(CW%ENV\fR by saying \f(CW\*(C`%ENV = ();\*(C'\fR, or, if you really have
+to, make it conditional on \f(CW\*(C`$^O ne \*(AqVMS\*(Aq\*(C'\fR since in VMS the
+\&\f(CW%ENV\fR table is much more than a per-process key-value
+string table.
+.PP
+On VMS, some entries in the \f(CW%ENV\fR hash are dynamically
+created when their key is used on a read if they did not previously
+exist.  The values for \f(CW$ENV{HOME}\fR, \f(CW$ENV{TERM}\fR, \f(CW$ENV{PATH}\fR, and
+\&\f(CW$ENV{USER}\fR, are known to be dynamically generated.  The specific names
+that are dynamically generated may vary with the version of the C library
+on VMS, and more may exist than are documented.
+.PP
+On VMS by default, changes to the \f(CW%ENV\fR hash persist
+after perl exits.  Subsequent invocations of perl in the same process can
+inadvertently inherit environment settings that were meant to be
+temporary.
+.PP
+Don't count on signals or \f(CW%SIG\fR for anything.
+.PP
+Don't count on filename globbing.  Use
+\&\f(CW\*(C`opendir\*(C'\fR,
+\&\f(CW\*(C`readdir\*(C'\fR, and
+\&\f(CW\*(C`closedir\*(C'\fR instead.
+.PP
+Don't count on per-program environment variables, or per-program current
+directories.
+.PP
+Don't count on specific values of \f(CW$!\fR, neither numeric nor
+especially the string values. Users may switch their locales causing
+error messages to be translated into their languages.  If you can
+trust a POSIXish environment, you can portably use the symbols defined
+by the \f(CW\*(C`Errno\*(C'\fR module, like \f(CW\*(C`ENOENT\*(C'\fR.  And don't trust on the
+values of \f(CW$!\fR at all except immediately after a failed
+system call.
+.SS "Command names versus file pathnames"
+.IX Subsection "Command names versus file pathnames"
+Don't assume that the name used to invoke a command or program with
+\&\f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR can
+also be used to test for the existence of the file that holds the
+executable code for that command or program.
+First, many systems have "internal" commands that are built-in to the
+shell or OS and while these commands can be invoked, there is no
+corresponding file.  Second, some operating systems (e.g., Cygwin,
+OS/2, and VOS) have required suffixes for executable files;
+these suffixes are generally permitted on the command name but are not
+required.  Thus, a command like \f(CW\*(C`perl\*(C'\fR might exist in a file named
+\&\fIperl\fR, \fIperl.exe\fR, or \fIperl.pm\fR, depending on the operating system.
+The variable \f(CW$Config{_exe}\fR in the
+\&\f(CW\*(C`Config\*(C'\fR module holds the executable suffix, if any.  Third,
+the VMS port carefully sets up \f(CW$^X\fR and
+\&\f(CW$Config{perlpath}\fR so that no further processing
+is required.  This is just as well, because the matching regular
+expression used below would then have to deal with a possible trailing
+version number in the VMS file name.
+.PP
+To convert \f(CW$^X\fR to a file pathname, taking account of
+the requirements of the various operating system possibilities, say:
+.PP
+.Vb 6
+\& use Config;
+\& my $thisperl = $^X;
+\& if ($^O ne \*(AqVMS\*(Aq) {
+\&     $thisperl .= $Config{_exe}
+\&         unless $thisperl =~ m/\eQ$Config{_exe}\eE$/i;
+\& }
+.Ve
+.PP
+To convert \f(CW$Config{perlpath}\fR to a file pathname, say:
+.PP
+.Vb 6
+\& use Config;
+\& my $thisperl = $Config{perlpath};
+\& if ($^O ne \*(AqVMS\*(Aq) {
+\&     $thisperl .= $Config{_exe}
+\&         unless $thisperl =~ m/\eQ$Config{_exe}\eE$/i;
+\& }
+.Ve
+.SS Networking
+.IX Subsection "Networking"
+Don't assume that you can reach the public Internet.
+.PP
+Don't assume that there is only one way to get through firewalls
+to the public Internet.
+.PP
+Don't assume that you can reach outside world through any other port
+than 80, or some web proxy.  ftp is blocked by many firewalls.
+.PP
+Don't assume that you can send email by connecting to the local SMTP port.
+.PP
+Don't assume that you can reach yourself or any node by the name
+\&'localhost'.  The same goes for '127.0.0.1'.  You will have to try both.
+.PP
+Don't assume that the host has only one network card, or that it
+can't bind to many virtual IP addresses.
+.PP
+Don't assume a particular network device name.
+.PP
+Don't assume a particular set of
+\&\f(CW\*(C`ioctl\*(C'\fRs will work.
+.PP
+Don't assume that you can ping hosts and get replies.
+.PP
+Don't assume that any particular port (service) will respond.
+.PP
+Don't assume that \f(CW\*(C`Sys::Hostname\*(C'\fR (or any other API or
+command) returns either a fully qualified hostname or a non-qualified
+hostname: it all depends on how the system had been configured.  Also
+remember that for things such as DHCP and NAT, the hostname you get back
+might not be very useful.
+.PP
+All the above \fIdon't\fRs may look daunting, and they are, but the key
+is to degrade gracefully if one cannot reach the particular network
+service one wants.  Croaking or hanging do not look very professional.
+.SS "Interprocess Communication (IPC)"
+.IX Subsection "Interprocess Communication (IPC)"
+In general, don't directly access the system in code meant to be
+portable.  That means, no \f(CW\*(C`system\*(C'\fR,
+\&\f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`fork\*(C'\fR,
+\&\f(CW\*(C`pipe\*(C'\fR,
+\&\f(CW\`\`\fR or \f(CW\*(C`qx//\*(C'\fR,
+\&\f(CW\*(C`open\*(C'\fR with a \f(CW\*(C`|\*(C'\fR, nor any of the other
+things that makes being a Perl hacker worth being.
+.PP
+Commands that launch external processes are generally supported on
+most platforms (though many of them do not support any type of
+forking).  The problem with using them arises from what you invoke
+them on.  External tools are often named differently on different
+platforms, may not be available in the same location, might accept
+different arguments, can behave differently, and often present their
+results in a platform-dependent way.  Thus, you should seldom depend
+on them to produce consistent results.  (Then again, if you're calling
+\&\f(CW\*(C`netstat \-a\*(C'\fR, you probably don't expect it to run on both Unix and CP/M.)
+.PP
+One especially common bit of Perl code is opening a pipe to \fBsendmail\fR:
+.PP
+.Vb 2
+\&    open(my $mail, \*(Aq|\-\*(Aq, \*(Aq/usr/lib/sendmail \-t\*(Aq)
+\&        or die "cannot fork sendmail: $!";
+.Ve
+.PP
+This is fine for systems programming when sendmail is known to be
+available.  But it is not fine for many non-Unix systems, and even
+some Unix systems that may not have sendmail installed.  If a portable
+solution is needed, see the various distributions on CPAN that deal
+with it.  \f(CW\*(C`Mail::Mailer\*(C'\fR and \f(CW\*(C`Mail::Send\*(C'\fR
+in the \f(CW\*(C`MailTools\*(C'\fR distribution are commonly used, and provide several
+mailing methods, including \f(CW\*(C`mail\*(C'\fR, \f(CW\*(C`sendmail\*(C'\fR, and direct SMTP (via
+\&\f(CW\*(C`Net::SMTP\*(C'\fR) if a mail transfer agent is not available.
+\&\f(CW\*(C`Mail::Sendmail\*(C'\fR is a standalone module that provides
+simple, platform-independent mailing.
+.PP
+The Unix System V IPC (\f(CW\*(C`msg*(), sem*(), shm*()\*(C'\fR) is not available
+even on all Unix platforms.
+.PP
+Do not use either the bare result of \f(CW\*(C`pack("N", 10, 20, 30, 40)\*(C'\fR or
+bare v\-strings (such as \f(CW\*(C`v10.20.30.40\*(C'\fR) to represent IPv4 addresses:
+both forms just pack the four bytes into network order.  That this
+would be equal to the C language \f(CW\*(C`in_addr\*(C'\fR struct (which is what the
+socket code internally uses) is not guaranteed.  To be portable use
+the routines of the \f(CW\*(C`Socket\*(C'\fR module, such as
+\&\f(CW\*(C`inet_aton\*(C'\fR,
+\&\f(CW\*(C`inet_ntoa\*(C'\fR, and
+\&\f(CW\*(C`sockaddr_in\*(C'\fR.
+.PP
+The rule of thumb for portable code is: Do it all in portable Perl, or
+use a module (that may internally implement it with platform-specific
+code, but exposes a common interface).
+.SS "External Subroutines (XS)"
+.IX Subsection "External Subroutines (XS)"
+XS code can usually be made to work with any platform, but dependent
+libraries, header files, etc., might not be readily available or
+portable, or the XS code itself might be platform-specific, just as Perl
+code might be.  If the libraries and headers are portable, then it is
+normally reasonable to make sure the XS code is portable, too.
+.PP
+A different type of portability issue arises when writing XS code:
+availability of a C compiler on the end-user's system.  C brings
+with it its own portability issues, and writing XS code will expose
+you to some of those.  Writing purely in Perl is an easier way to
+achieve portability.
+.SS "Standard Modules"
+.IX Subsection "Standard Modules"
+In general, the standard modules work across platforms.  Notable
+exceptions are the \f(CW\*(C`CPAN\*(C'\fR module (which currently makes
+connections to external programs that may not be available),
+platform-specific modules (like \f(CW\*(C`ExtUtils::MM_VMS\*(C'\fR),
+and DBM modules.
+.PP
+There is no one DBM module available on all platforms.
+\&\f(CW\*(C`SDBM_File\*(C'\fR and the others are generally available on all
+Unix and DOSish ports, but not in MacPerl, where only
+\&\f(CW\*(C`NDBM_File\*(C'\fR and \f(CW\*(C`DB_File\*(C'\fR are available.
+.PP
+The good news is that at least some DBM module should be available, and
+\&\f(CW\*(C`AnyDBM_File\*(C'\fR will use whichever module it can find.  Of
+course, then the code needs to be fairly strict, dropping to the greatest
+common factor (e.g., not exceeding 1K for each record), so that it will
+work with any DBM module.  See AnyDBM_File for more details.
+.SS "Time and Date"
+.IX Subsection "Time and Date"
+The system's notion of time of day and calendar date is controlled in
+widely different ways.  Don't assume the timezone is stored in \f(CW$ENV{TZ}\fR,
+and even if it is, don't assume that you can control the timezone through
+that variable.  Don't assume anything about the three-letter timezone
+abbreviations (for example that MST would be the Mountain Standard Time,
+it's been known to stand for Moscow Standard Time).  If you need to
+use timezones, express them in some unambiguous format like the
+exact number of minutes offset from UTC, or the POSIX timezone
+format.
+.PP
+Don't assume that the epoch starts at 00:00:00, January 1, 1970,
+because that is OS\- and implementation-specific.  It is better to
+store a date in an unambiguous representation.  The ISO 8601 standard
+defines YYYY-MM-DD as the date format, or YYYY\-MM\-DDTHH:MM:SS
+(that's a literal "T" separating the date from the time).
+Please do use the ISO 8601 instead of making us guess what
+date 02/03/04 might be.  ISO 8601 even sorts nicely as-is.
+A text representation (like "1987\-12\-18") can be easily converted
+into an OS-specific value using a module like
+\&\f(CW\*(C`Time::Piece\*(C'\fR (see "Date Parsing" in Time::Piece) or
+\&\f(CW\*(C`Date::Parse\*(C'\fR.  An array of values, such as those
+returned by \f(CW\*(C`localtime\*(C'\fR, can be converted to an OS-specific
+representation using \f(CW\*(C`Time::Local\*(C'\fR.
+.PP
+When calculating specific times, such as for tests in time or date modules,
+it may be appropriate to calculate an offset for the epoch.
+.PP
+.Vb 2
+\&    use Time::Local qw(timegm);
+\&    my $offset = timegm(0, 0, 0, 1, 0, 1970);
+.Ve
+.PP
+The value for \f(CW$offset\fR in Unix will be \f(CW0\fR, but in Mac OS Classic
+will be some large number.  \f(CW$offset\fR can then be added to a Unix time
+value to get what should be the proper value on any system.
+.SS "Character sets and character encoding"
+.IX Subsection "Character sets and character encoding"
+Assume very little about character sets.
+.PP
+Assume nothing about numerical values (\f(CW\*(C`ord\*(C'\fR,
+\&\f(CW\*(C`chr\*(C'\fR) of characters.
+Do not use explicit code point ranges (like \f(CW\*(C`\exHH\-\exHH)\*(C'\fR.  However,
+starting in Perl v5.22, regular expression pattern bracketed character
+class ranges specified like \f(CW\*(C`qr/[\eN{U+HH}\-\eN{U+HH}]/\*(C'\fR are portable,
+and starting in Perl v5.24, the same ranges are portable in
+\&\f(CW\*(C`tr///\*(C'\fR.
+You can portably use symbolic character classes like \f(CW\*(C`[:print:]\*(C'\fR.
+.PP
+Do not assume that the alphabetic characters are encoded contiguously
+(in the numeric sense).  There may be gaps.  Special coding in Perl,
+however, guarantees that all subsets of \f(CW\*(C`qr/[A\-Z]/\*(C'\fR, \f(CW\*(C`qr/[a\-z]/\*(C'\fR, and
+\&\f(CW\*(C`qr/[0\-9]/\*(C'\fR behave as expected.
+\&\f(CW\*(C`tr///\*(C'\fR
+behaves the same for these ranges.  In patterns, any ranges specified with
+end points using the \f(CW\*(C`\eN{...}\*(C'\fR notations ensures character set
+portability, but it is a bug in Perl v5.22 that this isn't true of
+\&\f(CW\*(C`tr///\*(C'\fR,
+fixed in v5.24.
+.PP
+Do not assume anything about the ordering of the characters.
+The lowercase letters may come before or after the uppercase letters;
+the lowercase and uppercase may be interlaced so that both "a" and "A"
+come before "b"; the accented and other international characters may
+be interlaced so that ä comes before "b".
+Unicode::Collate can be used to sort this all out.
+.SS Internationalisation
+.IX Subsection "Internationalisation"
+If you may assume POSIX (a rather large assumption), you may read
+more about the POSIX locale system from perllocale.  The locale
+system at least attempts to make things a little bit more portable,
+or at least more convenient and native-friendly for non-English
+users.  The system affects character sets and encoding, and date
+and time formatting\-\-amongst other things.
+.PP
+If you really want to be international, you should consider Unicode.
+See perluniintro and perlunicode for more information.
+.PP
+By default Perl assumes your source code is written in an 8\-bit ASCII
+superset. To embed Unicode characters in your strings and regexes, you can
+use the \f(CW\*(C`\ex{HH}\*(C'\fR or (more portably) \f(CW\*(C`\eN{U+HH}\*(C'\fR
+notations. You can also use the
+\&\f(CW\*(C`utf8\*(C'\fR pragma and write your code in UTF\-8, which lets you use
+Unicode characters directly (not just in quoted constructs but also in
+identifiers).
+.SS "System Resources"
+.IX Subsection "System Resources"
+If your code is destined for systems with severely constrained (or
+missing!) virtual memory systems then you want to be \fIespecially\fR mindful
+of avoiding wasteful constructs such as:
+.PP
+.Vb 1
+\&    my @lines = <$very_large_file>;            # bad
+\&
+\&    while (<$fh>) {$file .= $_}                # sometimes bad
+\&    my $file = join(\*(Aq\*(Aq, <$fh>);                # better
+.Ve
+.PP
+The last two constructs may appear unintuitive to most people.  The
+first repeatedly grows a string, whereas the second allocates a
+large chunk of memory in one go.  On some systems, the second is
+more efficient than the first.
+.SS Security
+.IX Subsection "Security"
+Most multi-user platforms provide basic levels of security, usually
+implemented at the filesystem level.  Some, however, unfortunately do
+not.  Thus the notion of user id, or "home" directory,
+or even the state of being logged-in, may be unrecognizable on many
+platforms.  If you write programs that are security-conscious, it
+is usually best to know what type of system you will be running
+under so that you can write code explicitly for that platform (or
+class of platforms).
+.PP
+Don't assume the Unix filesystem access semantics: the operating
+system or the filesystem may be using some ACL systems, which are
+richer languages than the usual \f(CW\*(C`rwx\*(C'\fR.  Even if the \f(CW\*(C`rwx\*(C'\fR exist,
+their semantics might be different.
+.PP
+(From the security viewpoint, testing for permissions before attempting to
+do something is silly anyway: if one tries this, there is potential
+for race conditions. Someone or something might change the
+permissions between the permissions check and the actual operation.
+Just try the operation.)
+.PP
+Don't assume the Unix user and group semantics: especially, don't
+expect \f(CW$<\fR and \f(CW$>\fR (or
+\&\f(CW$(\fR and \f(CW$)\fR) to work for switching
+identities (or memberships).
+.PP
+Don't assume set-uid and set-gid semantics.  (And even if you do,
+think twice: set-uid and set-gid are a known can of security worms.)
+.SS Style
+.IX Subsection "Style"
+For those times when it is necessary to have platform-specific code,
+consider keeping the platform-specific code in one place, making porting
+to other platforms easier.  Use the \f(CW\*(C`Config\*(C'\fR module and the
+special variable \f(CW$^O\fR to differentiate platforms, as
+described in "PLATFORMS".
+.PP
+Beware of the "else syndrome":
+.PP
+.Vb 5
+\&  if ($^O eq \*(AqMSWin32\*(Aq) {
+\&    # code that assumes Windows
+\&  } else {
+\&    # code that assumes Linux
+\&  }
+.Ve
+.PP
+The \f(CW\*(C`else\*(C'\fR branch should be used for the really ultimate fallback,
+not for code specific to some platform.
+.PP
+Be careful in the tests you supply with your module or programs.
+Module code may be fully portable, but its tests might not be.  This
+often happens when tests spawn off other processes or call external
+programs to aid in the testing, or when (as noted above) the tests
+assume certain things about the filesystem and paths.  Be careful not
+to depend on a specific output style for errors, such as when checking
+\&\f(CW$!\fR after a failed system call.  Using
+\&\f(CW$!\fR for anything else than displaying it as output is
+doubtful (though see the \f(CW\*(C`Errno\*(C'\fR module for testing reasonably
+portably for error value). Some platforms expect a certain output format,
+and Perl on those platforms may have been adjusted accordingly.  Most
+specifically, don't anchor a regex when testing an error value.
+.SH "CPAN Testers"
+.IX Header "CPAN Testers"
+Modules uploaded to CPAN are tested by a variety of volunteers on
+different platforms.  These CPAN testers are notified by mail of each
+new upload, and reply to the list with PASS, FAIL, NA (not applicable to
+this platform), or UNKNOWN (unknown), along with any relevant notations.
+.PP
+The purpose of the testing is twofold: one, to help developers fix any
+problems in their code that crop up because of lack of testing on other
+platforms; two, to provide users with information about whether
+a given module works on a given platform.
+.PP
+Also see:
+.IP \(bu 4
+Mailing list: cpan\-testers\-discuss@perl.org
+.IP \(bu 4
+Testing results: <https://www.cpantesters.org/>
+.SH PLATFORMS
+.IX Header "PLATFORMS"
+Perl is built with a \f(CW$^O\fR variable that indicates the
+operating system it was built on.  This was implemented
+to help speed up code that would otherwise have to \f(CW\*(C`use Config\*(C'\fR
+and use the value of \f(CW$Config{osname}\fR.  Of course,
+to get more detailed information about the system, looking into
+\&\f(CW%Config\fR is certainly recommended.
+.PP
+\&\f(CW%Config\fR cannot always be trusted, however,
+because it was built at compile time.  If perl was built in one place,
+then transferred elsewhere, some values may be wrong.  The values may
+even have been edited after the fact.
+.SS Unix
+.IX Subsection "Unix"
+Perl works on a bewildering variety of Unix and Unix-like platforms (see
+e.g. most of the files in the \fIhints/\fR directory in the source code kit).
+On most of these systems, the value of \f(CW$^O\fR (hence
+\&\f(CW$Config{osname}\fR, too) is determined either by
+lowercasing and stripping punctuation from the first field of the string
+returned by typing \f(CW\*(C`uname \-a\*(C'\fR (or a similar command) at the shell prompt
+or by testing the file system for the presence of uniquely named files
+such as a kernel or header file.  Here, for example, are a few of the
+more popular Unix flavors:
+.PP
+.Vb 10
+\&    uname         $^O        $Config{archname}
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    AIX           aix        aix
+\&    BSD/OS        bsdos      i386\-bsdos
+\&    Darwin        darwin     darwin
+\&    DYNIX/ptx     dynixptx   i386\-dynixptx
+\&    FreeBSD       freebsd    freebsd\-i386
+\&    Haiku         haiku      BePC\-haiku
+\&    Linux         linux      arm\-linux
+\&    Linux         linux      armv5tel\-linux
+\&    Linux         linux      i386\-linux
+\&    Linux         linux      i586\-linux
+\&    Linux         linux      ppc\-linux
+\&    HP\-UX         hpux       PA\-RISC1.1
+\&    IRIX          irix       irix
+\&    Mac OS X      darwin     darwin
+\&    NeXT 3        next       next\-fat
+\&    NeXT 4        next       OPENSTEP\-Mach
+\&    openbsd       openbsd    i386\-openbsd
+\&    OSF1          dec_osf    alpha\-dec_osf
+\&    reliantunix\-n svr4       RM400\-svr4
+\&    SCO_SV        sco_sv     i386\-sco_sv
+\&    SINIX\-N       svr4       RM400\-svr4
+\&    sn4609        unicos     CRAY_C90\-unicos
+\&    sn6521        unicosmk   t3e\-unicosmk
+\&    sn9617        unicos     CRAY_J90\-unicos
+\&    SunOS         solaris    sun4\-solaris
+\&    SunOS         solaris    i86pc\-solaris
+\&    SunOS4        sunos      sun4\-sunos
+.Ve
+.PP
+Because the value of \f(CW$Config{archname}\fR may
+depend on the hardware architecture, it can vary more than the value of
+\&\f(CW$^O\fR.
+.SS "DOS and Derivatives"
+.IX Subsection "DOS and Derivatives"
+Perl has long been ported to Intel-style microcomputers running under
+systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
+bring yourself to mention (except for Windows CE, if you count that).
+Users familiar with \fICOMMAND.COM\fR or \fICMD.EXE\fR style shells should
+be aware that each of these file specifications may have subtle
+differences:
+.PP
+.Vb 4
+\&    my $filespec0 = "c:/foo/bar/file.txt";
+\&    my $filespec1 = "c:\e\efoo\e\ebar\e\efile.txt";
+\&    my $filespec2 = \*(Aqc:\efoo\ebar\efile.txt\*(Aq;
+\&    my $filespec3 = \*(Aqc:\e\efoo\e\ebar\e\efile.txt\*(Aq;
+.Ve
+.PP
+System calls accept either \f(CW\*(C`/\*(C'\fR or \f(CW\*(C`\e\*(C'\fR as the path separator.
+However, many command-line utilities of DOS vintage treat \f(CW\*(C`/\*(C'\fR as
+the option prefix, so may get confused by filenames containing \f(CW\*(C`/\*(C'\fR.
+Aside from calling any external programs, \f(CW\*(C`/\*(C'\fR will work just fine,
+and probably better, as it is more consistent with popular usage,
+and avoids the problem of remembering what to backwhack and what
+not to.
+.PP
+The DOS FAT filesystem can accommodate only "8.3" style filenames.  Under
+the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
+filesystems you may have to be careful about case returned with functions
+like \f(CW\*(C`readdir\*(C'\fR or used with functions like
+\&\f(CW\*(C`open\*(C'\fR or
+\&\f(CW\*(C`opendir\*(C'\fR.
+.PP
+DOS also treats several filenames as special, such as \fIAUX\fR, \fIPRN\fR,
+\&\fINUL\fR, \fICON\fR, \fICOM1\fR, \fILPT1\fR, \fILPT2\fR, etc.  Unfortunately, sometimes
+these filenames won't even work if you include an explicit directory
+prefix.  It is best to avoid such filenames, if you want your code to be
+portable to DOS and its derivatives.  It's hard to know what these all
+are, unfortunately.
+.PP
+Users of these operating systems may also wish to make use of
+scripts such as \fIpl2bat.bat\fR to put wrappers around your scripts.
+.PP
+Newline (\f(CW\*(C`\en\*(C'\fR) is translated as \f(CW\*(C`\e015\e012\*(C'\fR by the I/O system when
+reading from and writing to files (see "Newlines").
+\&\f(CWbinmode($filehandle)\fR will keep \f(CW\*(C`\en\*(C'\fR translated as \f(CW\*(C`\e012\*(C'\fR for that
+filehandle.
+\&\f(CW\*(C`binmode\*(C'\fR should always be used for code
+that deals with binary data.  That's assuming you realize in advance that
+your data is in binary.  General-purpose programs should often assume
+nothing about their data.
+.PP
+The \f(CW$^O\fR variable and the
+\&\f(CW$Config{archname}\fR values for various DOSish
+perls are as follows:
+.PP
+.Vb 10
+\&    OS             $^O       $Config{archname}  ID    Version
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    MS\-DOS         dos       ?
+\&    PC\-DOS         dos       ?
+\&    OS/2           os2       ?
+\&    Windows 3.1    ?         ?                  0     3 01
+\&    Windows 95     MSWin32   MSWin32\-x86        1     4 00
+\&    Windows 98     MSWin32   MSWin32\-x86        1     4 10
+\&    Windows ME     MSWin32   MSWin32\-x86        1     ?
+\&    Windows NT     MSWin32   MSWin32\-x86        2     4 xx
+\&    Windows NT     MSWin32   MSWin32\-ALPHA      2     4 xx
+\&    Windows NT     MSWin32   MSWin32\-ppc        2     4 xx
+\&    Windows 2000   MSWin32   MSWin32\-x86        2     5 00
+\&    Windows XP     MSWin32   MSWin32\-x86        2     5 01
+\&    Windows 2003   MSWin32   MSWin32\-x86        2     5 02
+\&    Windows Vista  MSWin32   MSWin32\-x86        2     6 00
+\&    Windows 7      MSWin32   MSWin32\-x86        2     6 01
+\&    Windows 7      MSWin32   MSWin32\-x64        2     6 01
+\&    Windows 2008   MSWin32   MSWin32\-x86        2     6 01
+\&    Windows 2008   MSWin32   MSWin32\-x64        2     6 01
+\&    Windows CE     MSWin32   ?                  3
+\&    Cygwin         cygwin    cygwin
+.Ve
+.PP
+The various MSWin32 Perl's can distinguish the OS they are running on
+via the value of the fifth element of the list returned from
+\&\f(CWWin32::GetOSVersion()\fR.  For example:
+.PP
+.Vb 4
+\&    if ($^O eq \*(AqMSWin32\*(Aq) {
+\&        my @os_version_info = Win32::GetOSVersion();
+\&        print +(\*(Aq3.1\*(Aq,\*(Aq95\*(Aq,\*(AqNT\*(Aq)[$os_version_info[4]],"\en";
+\&    }
+.Ve
+.PP
+There are also \f(CW\*(C`Win32::IsWinNT()|Win32/Win32::IsWinNT()\*(C'\fR,
+\&\f(CW\*(C`Win32::IsWin95()|Win32/Win32::IsWin95()\*(C'\fR, and
+\&\f(CWWin32::GetOSName()\fR; try
+\&\f(CW\*(C`perldoc Win32\*(C'\fR.
+The very portable \f(CWPOSIX::uname()\fR will work too:
+.PP
+.Vb 2
+\&    c:\e> perl \-MPOSIX \-we "print join \*(Aq|\*(Aq, uname"
+\&    Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
+.Ve
+.PP
+Errors set by Winsock functions are now put directly into \f(CW$^E\fR,
+and the relevant \f(CW\*(C`WSAE*\*(C'\fR error codes are now exported from the
+Errno and POSIX modules for testing this against.
+.PP
+The previous behavior of putting the errors (converted to POSIX-style
+\&\f(CW\*(C`E*\*(C'\fR error codes since Perl 5.20.0) into \f(CW$!\fR was buggy due to
+the non-equivalence of like-named Winsock and POSIX error constants,
+a relationship between which has unfortunately been established
+in one way or another since Perl 5.8.0.
+.PP
+The new behavior provides a much more robust solution for checking
+Winsock errors in portable software without accidentally matching
+POSIX tests that were intended for other OSes and may have different
+meanings for Winsock.
+.PP
+The old behavior is currently retained, warts and all, for backwards
+compatibility, but users are encouraged to change any code that
+tests \f(CW$!\fR against \f(CW\*(C`E*\*(C'\fR constants for Winsock errors to instead
+test \f(CW$^E\fR against \f(CW\*(C`WSAE*\*(C'\fR constants.  After a suitable deprecation
+period, which started with Perl 5.24, the old behavior may be
+removed, leaving \f(CW$!\fR unchanged after Winsock function calls, to
+avoid any possible confusion over which error variable to check.
+.PP
+Also see:
+.IP \(bu 4
+The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
+<ftp://hobbes.nmsu.edu/pub/os2/dev/emx/>  Also perlos2.
+.IP \(bu 4
+Build instructions for Win32 in perlwin32, or under the Cygnus environment
+in perlcygwin.
+.IP \(bu 4
+The \f(CW\*(C`Win32::*\*(C'\fR modules in Win32.
+.IP \(bu 4
+The ActiveState Pages, <https://www.activestate.com/>
+.IP \(bu 4
+The Cygwin environment for Win32; \fIREADME.cygwin\fR (installed
+as perlcygwin), <https://www.cygwin.com/>
+.IP \(bu 4
+Build instructions for OS/2, perlos2
+.SS VMS
+.IX Subsection "VMS"
+Perl on VMS is discussed in perlvms in the Perl distribution.
+.PP
+The official name of VMS as of this writing is OpenVMS.
+.PP
+Interacting with Perl from the Digital Command Language (DCL) shell
+often requires a different set of quotation marks than Unix shells do.
+For example:
+.PP
+.Vb 2
+\&    $ perl \-e "print ""Hello, world.\en"""
+\&    Hello, world.
+.Ve
+.PP
+There are several ways to wrap your Perl scripts in DCL \fI.COM\fR files, if
+you are so inclined.  For example:
+.PP
+.Vb 6
+\&    $ write sys$output "Hello from DCL!"
+\&    $ if p1 .eqs. ""
+\&    $ then perl \-x \*(Aqf$environment("PROCEDURE")
+\&    $ else perl \-x \- \*(Aqp1 \*(Aqp2 \*(Aqp3 \*(Aqp4 \*(Aqp5 \*(Aqp6 \*(Aqp7 \*(Aqp8
+\&    $ deck/dollars="_\|_END_\|_"
+\&    #!/usr/bin/perl
+\&
+\&    print "Hello from Perl!\en";
+\&
+\&    _\|_END_\|_
+\&    $ endif
+.Ve
+.PP
+Do take care with \f(CW\*(C`$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT\*(C'\fR if your
+Perl-in-DCL script expects to do things like \f(CW\*(C`$read = <STDIN>;\*(C'\fR.
+.PP
+The VMS operating system has two filesystems, designated by their
+on-disk structure (ODS) level: ODS\-2 and its successor ODS\-5.  The
+initial port of Perl to VMS pre-dates ODS\-5, but all current testing and
+development assumes ODS\-5 and its capabilities, including case
+preservation, extended characters in filespecs, and names up to 8192
+bytes long.
+.PP
+Perl on VMS can accept either VMS\- or Unix-style file
+specifications as in either of the following:
+.PP
+.Vb 2
+\&    $ perl \-ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
+\&    $ perl \-ne "print if /perl_setup/i" /sys$login/login.com
+.Ve
+.PP
+but not a mixture of both as in:
+.PP
+.Vb 2
+\&    $ perl \-ne "print if /perl_setup/i" sys$login:/login.com
+\&    Can\*(Aqt open sys$login:/login.com: file specification syntax error
+.Ve
+.PP
+In general, the easiest path to portability is always to specify
+filenames in Unix format unless they will need to be processed by native
+commands or utilities.  Because of this latter consideration, the
+File::Spec module by default returns native format specifications
+regardless of input format.  This default may be reversed so that
+filenames are always reported in Unix format by specifying the
+\&\f(CW\*(C`DECC$FILENAME_UNIX_REPORT\*(C'\fR feature logical in the environment.
+.PP
+The file type, or extension, is always present in a VMS-format file
+specification even if it's zero-length.  This means that, by default,
+\&\f(CW\*(C`readdir\*(C'\fR will return a trailing dot on a
+file with no extension, so where you would see \f(CW"a"\fR on Unix you'll see
+\&\f(CW"a."\fR on VMS.  However, the trailing dot may be suppressed by enabling
+the \f(CW\*(C`DECC$READDIR_DROPDOTNOTYPE\*(C'\fR feature in the environment (see the CRTL
+documentation on feature logical names).
+.PP
+What \f(CW\*(C`\en\*(C'\fR represents depends on the type of file opened.  It usually
+represents \f(CW\*(C`\e012\*(C'\fR but it could also be \f(CW\*(C`\e015\*(C'\fR, \f(CW\*(C`\e012\*(C'\fR, \f(CW\*(C`\e015\e012\*(C'\fR,
+\&\f(CW\*(C`\e000\*(C'\fR, \f(CW\*(C`\e040\*(C'\fR, or nothing depending on the file organization and
+record format.  The \f(CW\*(C`VMS::Stdio\*(C'\fR module provides access to
+the special \f(CWfopen()\fR requirements of files with unusual attributes on
+VMS.
+.PP
+The value of \f(CW$^O\fR on OpenVMS is "VMS".  To determine the
+architecture that you are running on refer to
+\&\f(CW$Config{archname}\fR.
+.PP
+On VMS, perl determines the UTC offset from the \f(CW\*(C`SYS$TIMEZONE_DIFFERENTIAL\*(C'\fR
+logical name.  Although the VMS epoch began at 17\-NOV\-1858 00:00:00.00,
+calls to \f(CW\*(C`localtime\*(C'\fR are adjusted to count
+offsets from 01\-JAN\-1970 00:00:00.00, just like Unix.
+.PP
+Also see:
+.IP \(bu 4
+\&\fIREADME.vms\fR (installed as \fIREADME_vms\fR), perlvms
+.IP \(bu 4
+vmsperl list, vmsperl\-subscribe@perl.org
+.IP \(bu 4
+vmsperl on the web, <http://www.sidhe.org/vmsperl/index.html>
+.IP \(bu 4
+VMS Software Inc. web site, <http://www.vmssoftware.com>
+.SS VOS
+.IX Subsection "VOS"
+Perl on VOS (also known as OpenVOS) is discussed in \fIREADME.vos\fR
+in the Perl distribution (installed as perlvos).  Perl on VOS
+can accept either VOS\- or Unix-style file specifications as in
+either of the following:
+.PP
+.Vb 2
+\&    $ perl \-ne "print if /perl_setup/i" >system>notices
+\&    $ perl \-ne "print if /perl_setup/i" /system/notices
+.Ve
+.PP
+or even a mixture of both as in:
+.PP
+.Vb 1
+\&    $ perl \-ne "print if /perl_setup/i" >system/notices
+.Ve
+.PP
+Even though VOS allows the slash character to appear in object
+names, because the VOS port of Perl interprets it as a pathname
+delimiting character, VOS files, directories, or links whose
+names contain a slash character cannot be processed.  Such files
+must be renamed before they can be processed by Perl.
+.PP
+Older releases of VOS (prior to OpenVOS Release 17.0) limit file
+names to 32 or fewer characters, prohibit file names from
+starting with a \f(CW\*(C`\-\*(C'\fR character, and prohibit file names from
+containing \f(CW\*(C` \*(C'\fR (space) or any character from the set \f(CW\*(C`!#%&\*(Aq()*;<=>?\*(C'\fR.
+.PP
+Newer releases of VOS (OpenVOS Release 17.0 or later) support a
+feature known as extended names.  On these releases, file names
+can contain up to 255 characters, are prohibited from starting
+with a \f(CW\*(C`\-\*(C'\fR character, and the set of prohibited characters is
+reduced to \f(CW\*(C`#%*<>?\*(C'\fR.  There are
+restrictions involving spaces and apostrophes:  these characters
+must not begin or end a name, nor can they immediately precede or
+follow a period.  Additionally, a space must not immediately
+precede another space or hyphen.  Specifically, the following
+character combinations are prohibited:  space-space,
+space-hyphen, period-space, space-period, period-apostrophe,
+apostrophe-period, leading or trailing space, and leading or
+trailing apostrophe.  Although an extended file name is limited
+to 255 characters, a path name is still limited to 256
+characters.
+.PP
+The value of \f(CW$^O\fR on VOS is "vos".  To determine the
+architecture that you are running on refer to
+\&\f(CW$Config{archname}\fR.
+.PP
+Also see:
+.IP \(bu 4
+\&\fIREADME.vos\fR (installed as perlvos)
+.IP \(bu 4
+The VOS mailing list.
+.Sp
+There is no specific mailing list for Perl on VOS.  You can contact
+the Stratus Technologies Customer Assistance Center (CAC) for your
+region, or you can use the contact information located in the
+distribution files on the Stratus Anonymous FTP site.
+.IP \(bu 4
+Stratus Technologies on the web at <http://www.stratus.com>
+.IP \(bu 4
+VOS Open-Source Software on the web at <http://ftp.stratus.com/pub/vos/vos.html>
+.SS "EBCDIC Platforms"
+.IX Subsection "EBCDIC Platforms"
+v5.22 core Perl runs on z/OS (formerly OS/390).  Theoretically it could
+run on the successors of OS/400 on AS/400 minicomputers as well as
+VM/ESA, and BS2000 for S/390 Mainframes.  Such computers use EBCDIC
+character sets internally (usually Character Code Set ID 0037 for OS/400
+and either 1047 or POSIX-BC for S/390 systems).
+.PP
+The rest of this section may need updating, but we don't know what it
+should say.  Please submit comments to
+<https://github.com/Perl/perl5/issues>.
+.PP
+On the mainframe Perl currently works under the "Unix system
+services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
+the BS200 POSIX-BC system (BS2000 is supported in Perl 5.6 and greater).
+See perlos390 for details.  Note that for OS/400 there is also a port of
+Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as opposed to
+ILE which is EBCDIC-based), see perlos400.
+.PP
+As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
+sub-systems do not support the \f(CW\*(C`#!\*(C'\fR shebang trick for script invocation.
+Hence, on OS/390 and VM/ESA Perl scripts can be executed with a header
+similar to the following simple script:
+.PP
+.Vb 4
+\&    : # use perl
+\&        eval \*(Aqexec /usr/local/bin/perl \-S $0 ${1+"$@"}\*(Aq
+\&            if 0;
+\&    #!/usr/local/bin/perl     # just a comment really
+\&
+\&    print "Hello from perl!\en";
+.Ve
+.PP
+OS/390 will support the \f(CW\*(C`#!\*(C'\fR shebang trick in release 2.8 and beyond.
+Calls to \f(CW\*(C`system\*(C'\fR and backticks can use POSIX
+shell syntax on all S/390 systems.
+.PP
+On the AS/400, if PERL5 is in your library list, you may need
+to wrap your Perl scripts in a CL procedure to invoke them like so:
+.PP
+.Vb 3
+\&    BEGIN
+\&      CALL PGM(PERL5/PERL) PARM(\*(Aq/QOpenSys/hello.pl\*(Aq)
+\&    ENDPGM
+.Ve
+.PP
+This will invoke the Perl script \fIhello.pl\fR in the root of the
+QOpenSys file system.  On the AS/400 calls to
+\&\f(CW\*(C`system\*(C'\fR or backticks must use CL syntax.
+.PP
+On these platforms, bear in mind that the EBCDIC character set may have
+an effect on what happens with some Perl functions (such as
+\&\f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`pack\*(C'\fR,
+\&\f(CW\*(C`print\*(C'\fR,
+\&\f(CW\*(C`printf\*(C'\fR,
+\&\f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`sort\*(C'\fR,
+\&\f(CW\*(C`sprintf\*(C'\fR,
+\&\f(CW\*(C`unpack\*(C'\fR), as
+well as bit-fiddling with ASCII constants using operators like
+\&\f(CW\*(C`^\*(C'\fR, \f(CW\*(C`&\*(C'\fR and \f(CW\*(C`|\*(C'\fR, not to mention
+dealing with socket interfaces to ASCII computers (see "Newlines").
+.PP
+Fortunately, most web servers for the mainframe will correctly
+translate the \f(CW\*(C`\en\*(C'\fR in the following statement to its ASCII equivalent
+(\f(CW\*(C`\er\*(C'\fR is the same under both Unix and z/OS):
+.PP
+.Vb 1
+\&    print "Content\-type: text/html\er\en\er\en";
+.Ve
+.PP
+The values of \f(CW$^O\fR on some of these platforms include:
+.PP
+.Vb 5
+\&    uname         $^O        $Config{archname}
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    OS/390        os390      os390
+\&    OS400         os400      os400
+\&    POSIX\-BC      posix\-bc   BS2000\-posix\-bc
+.Ve
+.PP
+Some simple tricks for determining if you are running on an EBCDIC
+platform could include any of the following (perhaps all):
+.PP
+.Vb 1
+\&    if ("\et" eq "\e005")  { print "EBCDIC may be spoken here!\en"; }
+\&
+\&    if (ord(\*(AqA\*(Aq) == 193) { print "EBCDIC may be spoken here!\en"; }
+\&
+\&    if (chr(169) eq \*(Aqz\*(Aq) { print "EBCDIC may be spoken here!\en"; }
+.Ve
+.PP
+One thing you may not want to rely on is the EBCDIC encoding
+of punctuation characters since these may differ from code page to code
+page (and once your module or script is rumoured to work with EBCDIC,
+folks will want it to work with all EBCDIC character sets).
+.PP
+Also see:
+.IP \(bu 4
+perlos390, perlos400, perlbs2000, perlebcdic.
+.IP \(bu 4
+The perl\-mvs@perl.org list is for discussion of porting issues as well as
+general usage issues for all EBCDIC Perls.  Send a message body of
+"subscribe perl-mvs" to majordomo@perl.org.
+.IP \(bu 4
+AS/400 Perl information at
+<http://as400.rochester.ibm.com/>
+as well as on CPAN in the \fIports/\fR directory.
+.SS "Acorn RISC OS"
+.IX Subsection "Acorn RISC OS"
+Because Acorns use ASCII with newlines (\f(CW\*(C`\en\*(C'\fR) in text files as \f(CW\*(C`\e012\*(C'\fR like
+Unix, and because Unix filename emulation is turned on by default,
+most simple scripts will probably work "out of the box".  The native
+filesystem is modular, and individual filesystems are free to be
+case-sensitive or insensitive, and are usually case-preserving.  Some
+native filesystems have name length limits, which file and directory
+names are silently truncated to fit.  Scripts should be aware that the
+standard filesystem currently has a name length limit of \fB10\fR
+characters, with up to 77 items in a directory, but other filesystems
+may not impose such limitations.
+.PP
+Native filenames are of the form
+.PP
+.Vb 1
+\&    Filesystem#Special_Field::DiskName.$.Directory.Directory.File
+.Ve
+.PP
+where
+.PP
+.Vb 8
+\&    Special_Field is not usually present, but may contain . and $ .
+\&    Filesystem =~ m|[A\-Za\-z0\-9_]|
+\&    DsicName   =~ m|[A\-Za\-z0\-9_/]|
+\&    $ represents the root directory
+\&    . is the path separator
+\&    @ is the current directory (per filesystem but machine global)
+\&    ^ is the parent directory
+\&    Directory and File =~ m|[^\e0\- "\e.\e$\e%\e&:\e@\e\e^\e|\e177]+|
+.Ve
+.PP
+The default filename translation is roughly \f(CW\*(C`tr|/.|./|\*(C'\fR, swapping dots
+and slashes.
+.PP
+Note that \f(CW\*(C`"ADFS::HardDisk.$.File" ne \*(AqADFS::HardDisk.$.File\*(Aq\*(C'\fR and that
+the second stage of \f(CW\*(C`$\*(C'\fR interpolation in regular expressions will fall
+foul of the \f(CW$.\fR variable if scripts are not careful.
+.PP
+Logical paths specified by system variables containing comma-separated
+search lists are also allowed; hence \f(CW\*(C`System:Modules\*(C'\fR is a valid
+filename, and the filesystem will prefix \f(CW\*(C`Modules\*(C'\fR with each section of
+\&\f(CW\*(C`System$Path\*(C'\fR until a name is made that points to an object on disk.
+Writing to a new file \f(CW\*(C`System:Modules\*(C'\fR would be allowed only if
+\&\f(CW\*(C`System$Path\*(C'\fR contains a single item list.  The filesystem will also
+expand system variables in filenames if enclosed in angle brackets, so
+\&\f(CW\*(C`<System$Dir>.Modules\*(C'\fR would look for the file
+\&\f(CW\*(C`$ENV{\*(AqSystem$Dir\*(Aq}\ .\ \*(AqModules\*(Aq\*(C'\fR.  The obvious implication of this is
+that \fBfully qualified filenames can start with \fR\f(CB\*(C`<>\*(C'\fR and the
+three-argument form of \f(CW\*(C`open\*(C'\fR should
+always be used.
+.PP
+Because \f(CW\*(C`.\*(C'\fR was in use as a directory separator and filenames could not
+be assumed to be unique after 10 characters, Acorn implemented the C
+compiler to strip the trailing \f(CW\*(C`.c\*(C'\fR \f(CW\*(C`.h\*(C'\fR \f(CW\*(C`.s\*(C'\fR and \f(CW\*(C`.o\*(C'\fR suffix from
+filenames specified in source code and store the respective files in
+subdirectories named after the suffix.  Hence files are translated:
+.PP
+.Vb 6
+\&    foo.h           h.foo
+\&    C:foo.h         C:h.foo        (logical path variable)
+\&    sys/os.h        sys.h.os       (C compiler groks Unix\-speak)
+\&    10charname.c    c.10charname
+\&    10charname.o    o.10charname
+\&    11charname_.c   c.11charname   (assuming filesystem truncates at 10)
+.Ve
+.PP
+The Unix emulation library's translation of filenames to native assumes
+that this sort of translation is required, and it allows a user-defined list
+of known suffixes that it will transpose in this fashion.  This may
+seem transparent, but consider that with these rules \fIfoo/bar/baz.h\fR
+and \fIfoo/bar/h/baz\fR both map to \fIfoo.bar.h.baz\fR, and that
+\&\f(CW\*(C`readdir\*(C'\fR and \f(CW\*(C`glob\*(C'\fR
+cannot and do not attempt to emulate the reverse mapping.  Other
+\&\f(CW\*(C`.\*(C'\fR's in filenames are translated to \f(CW\*(C`/\*(C'\fR.
+.PP
+As implied above, the environment accessed through
+\&\f(CW%ENV\fR is global, and the convention is that program
+specific environment variables are of the form \f(CW\*(C`Program$Name\*(C'\fR.
+Each filesystem maintains a current directory,
+and the current filesystem's current directory is the \fBglobal\fR current
+directory.  Consequently, sociable programs don't change the current
+directory but rely on full pathnames, and programs (and Makefiles) cannot
+assume that they can spawn a child process which can change the current
+directory without affecting its parent (and everyone else for that
+matter).
+.PP
+Because native operating system filehandles are global and are currently
+allocated down from 255, with 0 being a reserved value, the Unix emulation
+library emulates Unix filehandles.  Consequently, you can't rely on
+passing \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, or \f(CW\*(C`STDERR\*(C'\fR to your children.
+.PP
+The desire of users to express filenames of the form
+\&\f(CW\*(C`<Foo$Dir>.Bar\*(C'\fR on the command line unquoted causes problems,
+too: \f(CW\`\`\fR command output capture has
+to perform a guessing game.  It assumes that a string \f(CW\*(C`<[^<>]+\e$[^<>]>\*(C'\fR
+is a reference to an environment variable, whereas anything else involving
+\&\f(CW\*(C`<\*(C'\fR or \f(CW\*(C`>\*(C'\fR is redirection, and generally manages to be 99%
+right.  Of course, the problem remains that scripts cannot rely on any
+Unix tools being available, or that any tools found have Unix-like command
+line arguments.
+.PP
+Extensions and XS are, in theory, buildable by anyone using free
+tools.  In practice, many don't, as users of the Acorn platform are
+used to binary distributions.  MakeMaker does run, but no available
+make currently copes with MakeMaker's makefiles; even if and when
+this should be fixed, the lack of a Unix-like shell will cause
+problems with makefile rules, especially lines of the form
+\&\f(CW\*(C`cd sdbm && make all\*(C'\fR, and anything using quoting.
+.PP
+"RISC\ OS" is the proper name for the operating system, but the value
+in \f(CW$^O\fR is "riscos" (because we don't like shouting).
+.SS "Other perls"
+.IX Subsection "Other perls"
+Perl has been ported to many platforms that do not fit into any of
+the categories listed above.  Some, such as AmigaOS,
+QNX, Plan 9, and VOS, have been well-integrated into the standard
+Perl source code kit.  You may need to see the \fIports/\fR directory
+on CPAN for information, and possibly binaries, for the likes of:
+aos, Atari ST, lynxos, riscos, Novell Netware, Tandem Guardian,
+\&\fIetc.\fR  (Yes, we know that some of these OSes may fall under the
+Unix category, but we are not a standards body.)
+.PP
+Some approximate operating system names and their \f(CW$^O\fR
+values in the "OTHER" category include:
+.PP
+.Vb 3
+\&    OS            $^O        $Config{archname}
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    Amiga DOS     amigaos    m68k\-amigos
+.Ve
+.PP
+See also:
+.IP \(bu 4
+Amiga, \fIREADME.amiga\fR (installed as perlamiga).
+.IP \(bu 4
+Plan\ 9, \fIREADME.plan9\fR
+.SH "FUNCTION IMPLEMENTATIONS"
+.IX Header "FUNCTION IMPLEMENTATIONS"
+Listed below are functions that are either completely unimplemented
+or else have been implemented differently on various platforms.
+Preceding each description will be, in parentheses, a list of
+platforms that the description applies to.
+.PP
+The list may well be incomplete, or even wrong in some places.  When
+in doubt, consult the platform-specific README files in the Perl
+source distribution, and any other documentation resources accompanying
+a given port.
+.PP
+Be aware, moreover, that even among Unix-ish systems there are variations.
+.PP
+For many functions, you can also query \f(CW%Config\fR,
+exported by default from the \f(CW\*(C`Config\*(C'\fR module.  For example, to
+check whether the platform has the \f(CW\*(C`lstat\*(C'\fR
+call, check \f(CW$Config{d_lstat}\fR.  See Config for a
+full description of available variables.
+.SS "Alphabetical Listing of Perl Functions"
+.IX Subsection "Alphabetical Listing of Perl Functions"
+.IP \-X 8
+.IX Item "-X"
+(Win32)
+\&\f(CW\*(C`\-w\*(C'\fR only inspects the read-only file attribute (FILE_ATTRIBUTE_READONLY),
+which determines whether the directory can be deleted, not whether it can
+be written to. Directories always have read and write access unless denied
+by discretionary access control lists (DACLs).
+.Sp
+(VMS)
+\&\f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and \f(CW\*(C`\-o\*(C'\fR tell whether the file is accessible,
+which may not reflect UIC-based file protections.
+.Sp
+(RISC\ OS)
+\&\f(CW\*(C`\-s\*(C'\fR by name on an open file will return the space reserved on disk,
+rather than the current extent.  \f(CW\*(C`\-s\*(C'\fR on an open filehandle returns the
+current size.
+.Sp
+(Win32, VMS, RISC\ OS)
+\&\f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, \f(CW\*(C`\-X\*(C'\fR, \f(CW\*(C`\-O\*(C'\fR are indistinguishable from \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR,
+\&\f(CW\*(C`\-x\*(C'\fR, \f(CW\*(C`\-o\*(C'\fR.
+.Sp
+(Win32, VMS, RISC\ OS)
+\&\f(CW\*(C`\-g\*(C'\fR, \f(CW\*(C`\-k\*(C'\fR, \f(CW\*(C`\-l\*(C'\fR, \f(CW\*(C`\-u\*(C'\fR, \f(CW\*(C`\-A\*(C'\fR are not particularly meaningful.
+.Sp
+(Win32)
+\&\f(CW\*(C`\-l\*(C'\fR returns true for both symlinks and directory junctions.
+.Sp
+(VMS, RISC\ OS)
+\&\f(CW\*(C`\-p\*(C'\fR is not particularly meaningful.
+.Sp
+(VMS)
+\&\f(CW\*(C`\-d\*(C'\fR is true if passed a device spec without an explicit directory.
+.Sp
+(Win32)
+\&\f(CW\*(C`\-x\*(C'\fR (or \f(CW\*(C`\-X\*(C'\fR) determine if a file ends in one of the executable
+suffixes.  \f(CW\*(C`\-S\*(C'\fR is meaningless.
+.Sp
+(RISC\ OS)
+\&\f(CW\*(C`\-x\*(C'\fR (or \f(CW\*(C`\-X\*(C'\fR) determine if a file has an executable file type.
+.IP alarm 8
+.IX Item "alarm"
+(Win32)
+Emulated using timers that must be explicitly polled whenever Perl
+wants to dispatch "safe signals" and therefore cannot interrupt
+blocking system calls.
+.IP atan2 8
+.IX Item "atan2"
+(Tru64, HP-UX 10.20)
+Due to issues with various CPUs, math libraries, compilers, and standards,
+results for \f(CW\*(C`atan2\*(C'\fR may vary depending on any combination of the above.
+Perl attempts to conform to the Open Group/IEEE standards for the results
+returned from \f(CW\*(C`atan2\*(C'\fR, but cannot force the issue if the system Perl is
+run on does not allow it.
+.Sp
+The current version of the standards for \f(CW\*(C`atan2\*(C'\fR is available at
+<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
+.IP binmode 8
+.IX Item "binmode"
+(RISC\ OS)
+Meaningless.
+.Sp
+(VMS)
+Reopens file and restores pointer; if function fails, underlying
+filehandle may be closed, or pointer may be in a different position.
+.Sp
+(Win32)
+The value returned by \f(CW\*(C`tell\*(C'\fR may be affected
+after the call, and the filehandle may be flushed.
+.IP chdir 8
+.IX Item "chdir"
+(Win32)
+The current directory reported by the system may include any symbolic
+links specified to \fBchdir()\fR.
+.IP chmod 8
+.IX Item "chmod"
+(Win32)
+Only good for changing "owner" read-write access; "group" and "other"
+bits are meaningless.
+.Sp
+(RISC\ OS)
+Only good for changing "owner" and "other" read-write access.
+.Sp
+(VOS)
+Access permissions are mapped onto VOS access-control list changes.
+.Sp
+(Cygwin)
+The actual permissions set depend on the value of the \f(CW\*(C`CYGWIN\*(C'\fR variable
+in the SYSTEM environment settings.
+.Sp
+(Android)
+Setting the exec bit on some locations (generally \fI/sdcard\fR) will return true
+but not actually set the bit.
+.Sp
+(VMS)
+A mode argument of zero sets permissions to the user's default permission mask
+rather than disabling all permissions.
+.IP chown 8
+.IX Item "chown"
+(Plan\ 9, RISC\ OS)
+Not implemented.
+.Sp
+(Win32)
+Does nothing, but won't fail.
+.Sp
+(VOS)
+A little funky, because VOS's notion of ownership is a little funky.
+.IP chroot 8
+.IX Item "chroot"
+(Win32, VMS, Plan\ 9, RISC\ OS, VOS)
+Not implemented.
+.IP crypt 8
+.IX Item "crypt"
+(Win32)
+May not be available if library or source was not provided when building
+perl.
+.Sp
+(Android)
+Not implemented.
+.IP dbmclose 8
+.IX Item "dbmclose"
+(VMS, Plan\ 9, VOS)
+Not implemented.
+.IP dbmopen 8
+.IX Item "dbmopen"
+(VMS, Plan\ 9, VOS)
+Not implemented.
+.IP dump 8
+.IX Item "dump"
+(RISC\ OS)
+Not useful.
+.Sp
+(Cygwin, Win32)
+Not supported.
+.Sp
+(VMS)
+Invokes VMS debugger.
+.IP exec 8
+.IX Item "exec"
+(Win32)
+\&\f(CW\*(C`exec LIST\*(C'\fR without the use of indirect object syntax (\f(CW\*(C`exec PROGRAM LIST\*(C'\fR)
+may fall back to trying the shell if the first \f(CWspawn()\fR fails.
+.Sp
+Note that the list form of \fBexec()\fR is emulated since the Win32 API
+\&\fBCreateProcess()\fR accepts a simple string rather than an array of
+command-line arguments.  This may have security implications for your
+code.
+.Sp
+(SunOS, Solaris, HP-UX)
+Does not automatically flush output handles on some platforms.
+.IP exit 8
+.IX Item "exit"
+(VMS)
+Emulates Unix \f(CW\*(C`exit\*(C'\fR (which considers \f(CW\*(C`exit 1\*(C'\fR to indicate an error) by
+mapping the \f(CW1\fR to \f(CW\*(C`SS$_ABORT\*(C'\fR (\f(CW44\fR).  This behavior may be overridden
+with the pragma \f(CW\*(C`use vmsish \*(Aqexit\*(Aq\*(C'\fR.  As with
+the CRTL's \f(CWexit()\fR function, \f(CW\*(C`exit 0\*(C'\fR is also mapped to an exit status
+of \f(CW\*(C`SS$_NORMAL\*(C'\fR (\f(CW1\fR); this mapping cannot be overridden.  Any other
+argument to \f(CW\*(C`exit\*(C'\fR
+is used directly as Perl's exit status.  On VMS, unless the future
+POSIX_EXIT mode is enabled, the exit code should always be a valid
+VMS exit code and not a generic number.  When the POSIX_EXIT mode is
+enabled, a generic number will be encoded in a method compatible with
+the C library _POSIX_EXIT macro so that it can be decoded by other
+programs, particularly ones written in C, like the GNV package.
+.Sp
+(Solaris)
+\&\f(CW\*(C`exit\*(C'\fR resets file pointers, which is a problem when called
+from a child process (created by \f(CW\*(C`fork\*(C'\fR) in
+\&\f(CW\*(C`BEGIN\*(C'\fR.
+A workaround is to use \f(CW\*(C`POSIX::_exit\*(C'\fR.
+.Sp
+.Vb 3
+\&    exit unless $Config{archname} =~ /\ebsolaris\eb/;
+\&    require POSIX;
+\&    POSIX::_exit(0);
+.Ve
+.IP fcntl 8
+.IX Item "fcntl"
+(Win32)
+Not implemented.
+.Sp
+(VMS)
+Some functions available based on the version of VMS.
+.IP flock 8
+.IX Item "flock"
+(VMS, RISC\ OS, VOS)
+Not implemented.
+.IP fork 8
+.IX Item "fork"
+(AmigaOS, RISC\ OS, VMS)
+Not implemented.
+.Sp
+(Win32)
+Emulated using multiple interpreters.  See perlfork.
+.Sp
+(SunOS, Solaris, HP-UX)
+Does not automatically flush output handles on some platforms.
+.IP getlogin 8
+.IX Item "getlogin"
+(RISC\ OS)
+Not implemented.
+.IP getpgrp 8
+.IX Item "getpgrp"
+(Win32, VMS, RISC\ OS)
+Not implemented.
+.IP getppid 8
+.IX Item "getppid"
+(Win32, RISC\ OS)
+Not implemented.
+.IP getpriority 8
+.IX Item "getpriority"
+(Win32, VMS, RISC\ OS, VOS)
+Not implemented.
+.IP getpwnam 8
+.IX Item "getpwnam"
+(Win32)
+Not implemented.
+.Sp
+(RISC\ OS)
+Not useful.
+.IP getgrnam 8
+.IX Item "getgrnam"
+(Win32, VMS, RISC\ OS)
+Not implemented.
+.IP getnetbyname 8
+.IX Item "getnetbyname"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP getpwuid 8
+.IX Item "getpwuid"
+(Win32)
+Not implemented.
+.Sp
+(RISC\ OS)
+Not useful.
+.IP getgrgid 8
+.IX Item "getgrgid"
+(Win32, VMS, RISC\ OS)
+Not implemented.
+.IP getnetbyaddr 8
+.IX Item "getnetbyaddr"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP getprotobynumber 8
+.IX Item "getprotobynumber"
+(Android)
+Not implemented.
+.IP getpwent 8
+.IX Item "getpwent"
+(Android, Win32)
+Not implemented.
+.IP getgrent 8
+.IX Item "getgrent"
+(Android, Win32, VMS)
+Not implemented.
+.IP gethostbyname 8
+.IX Item "gethostbyname"
+(Irix\ 5)
+\&\f(CWgethostbyname(\*(Aqlocalhost\*(Aq)\fR does not work everywhere: you may have
+to use \f(CWgethostbyname(\*(Aq127.0.0.1\*(Aq)\fR.
+.IP gethostent 8
+.IX Item "gethostent"
+(Win32)
+Not implemented.
+.IP getnetent 8
+.IX Item "getnetent"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP getprotoent 8
+.IX Item "getprotoent"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP getservent 8
+.IX Item "getservent"
+(Win32, Plan\ 9)
+Not implemented.
+.IP seekdir 8
+.IX Item "seekdir"
+(Android)
+Not implemented.
+.IP sethostent 8
+.IX Item "sethostent"
+(Android, Win32, Plan\ 9, RISC\ OS)
+Not implemented.
+.IP setnetent 8
+.IX Item "setnetent"
+(Win32, Plan\ 9, RISC\ OS)
+Not implemented.
+.IP setprotoent 8
+.IX Item "setprotoent"
+(Android, Win32, Plan\ 9, RISC\ OS)
+Not implemented.
+.IP setservent 8
+.IX Item "setservent"
+(Plan\ 9, Win32, RISC\ OS)
+Not implemented.
+.IP endpwent 8
+.IX Item "endpwent"
+(Win32)
+Not implemented.
+.Sp
+(Android)
+Either not implemented or a no-op.
+.IP endgrent 8
+.IX Item "endgrent"
+(Android, RISC\ OS, VMS, Win32)
+Not implemented.
+.IP endhostent 8
+.IX Item "endhostent"
+(Android, Win32)
+Not implemented.
+.IP endnetent 8
+.IX Item "endnetent"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP endprotoent 8
+.IX Item "endprotoent"
+(Android, Win32, Plan\ 9)
+Not implemented.
+.IP endservent 8
+.IX Item "endservent"
+(Plan\ 9, Win32)
+Not implemented.
+.IP getsockopt 8
+.IX Item "getsockopt"
+(Plan\ 9)
+Not implemented.
+.IP glob 8
+.IX Item "glob"
+This operator is implemented via the \f(CW\*(C`File::Glob\*(C'\fR extension
+on most platforms.  See File::Glob for portability information.
+.IP gmtime 8
+.IX Item "gmtime"
+In theory, \f(CW\*(C`gmtime\*(C'\fR is reliable from \-2**63 to 2**63\-1.  However,
+because work-arounds in the implementation use floating point numbers,
+it will become inaccurate as the time gets larger.  This is a bug and
+will be fixed in the future.
+.Sp
+(VOS)
+Time values are 32\-bit quantities.
+.IP ioctl 8
+.IX Item "ioctl"
+(VMS)
+Not implemented.
+.Sp
+(Win32)
+Available only for socket handles, and it does what the \f(CWioctlsocket()\fR call
+in the Winsock API does.
+.Sp
+(RISC\ OS)
+Available only for socket handles.
+.IP kill 8
+.IX Item "kill"
+(RISC\ OS)
+Not implemented, hence not useful for taint checking.
+.Sp
+(Win32)
+\&\f(CW\*(C`kill\*(C'\fR doesn't send a signal to the identified process like it does on
+Unix platforms.  Instead \f(CW\*(C`kill($sig, $pid)\*(C'\fR terminates the process
+identified by \f(CW$pid\fR, and makes it exit immediately with exit status
+\&\f(CW$sig\fR.  As in Unix, if \f(CW$sig\fR is 0 and the specified process exists, it
+returns true without actually terminating it.
+.Sp
+(Win32)
+\&\f(CW\*(C`kill(\-9, $pid)\*(C'\fR will terminate the process specified by \f(CW$pid\fR and
+recursively all child processes owned by it.  This is different from
+the Unix semantics, where the signal will be delivered to all
+processes in the same process group as the process specified by
+\&\f(CW$pid\fR.
+.Sp
+(VMS)
+A pid of \-1 indicating all processes on the system is not currently
+supported.
+.IP link 8
+.IX Item "link"
+(RISC\ OS, VOS)
+Not implemented.
+.Sp
+(AmigaOS)
+Link count not updated because hard links are not quite that hard
+(They are sort of half-way between hard and soft links).
+.Sp
+(Win32)
+Hard links are implemented on Win32 under NTFS only. They are
+natively supported on Windows 2000 and later.  On Windows NT they
+are implemented using the Windows POSIX subsystem support and the
+Perl process will need Administrator or Backup Operator privileges
+to create hard links.
+.Sp
+(VMS)
+Available on 64 bit OpenVMS 8.2 and later.
+.IP localtime 8
+.IX Item "localtime"
+\&\f(CW\*(C`localtime\*(C'\fR has the same range as "gmtime", but because time zone
+rules change, its accuracy for historical and future times may degrade
+but usually by no more than an hour.
+.IP lstat 8
+.IX Item "lstat"
+(RISC\ OS)
+Not implemented.
+.Sp
+(Win32)
+Treats directory junctions as symlinks.
+.IP msgctl 8
+.IX Item "msgctl"
+.PD 0
+.IP msgget 8
+.IX Item "msgget"
+.IP msgsnd 8
+.IX Item "msgsnd"
+.IP msgrcv 8
+.IX Item "msgrcv"
+.PD
+(Android, Win32, VMS, Plan\ 9, RISC\ OS, VOS)
+Not implemented.
+.IP open 8
+.IX Item "open"
+(RISC\ OS)
+Open modes \f(CW\*(C`|\-\*(C'\fR and \f(CW\*(C`\-|\*(C'\fR are unsupported.
+.Sp
+(SunOS, Solaris, HP-UX)
+Opening a process does not automatically flush output handles on some
+platforms.
+.Sp
+(Win32)
+Both of modes \f(CW\*(C`|\-\*(C'\fR and \f(CW\*(C`\-|\*(C'\fR are supported, but the list form is
+emulated since the Win32 API \fBCreateProcess()\fR accepts a simple string
+rather than an array of arguments.  This may have security
+implications for your code.
+.IP readlink 8
+.IX Item "readlink"
+(VMS, RISC\ OS)
+Not implemented.
+.Sp
+(Win32)
+\&\fBreadlink()\fR on a directory junction returns the object name, not a
+simple path.
+.IP rename 8
+.IX Item "rename"
+(Win32)
+Can't move directories between directories on different logical volumes.
+.IP rewinddir 8
+.IX Item "rewinddir"
+(Win32)
+Will not cause \f(CW\*(C`readdir\*(C'\fR to re-read the
+directory stream.  The entries already read before the \f(CW\*(C`rewinddir\*(C'\fR call
+will just be returned again from a cache buffer.
+.IP select 8
+.IX Item "select"
+(Win32, VMS)
+Only implemented on sockets.
+.Sp
+(RISC\ OS)
+Only reliable on sockets.
+.Sp
+Note that the \f(CW\*(C`select FILEHANDLE\*(C'\fR form is
+generally portable.
+.IP semctl 8
+.IX Item "semctl"
+.PD 0
+.IP semget 8
+.IX Item "semget"
+.IP semop 8
+.IX Item "semop"
+.PD
+(Android, Win32, VMS, RISC\ OS)
+Not implemented.
+.IP setgrent 8
+.IX Item "setgrent"
+(Android, VMS, Win32, RISC\ OS)
+Not implemented.
+.IP setpgrp 8
+.IX Item "setpgrp"
+(Win32, VMS, RISC\ OS, VOS)
+Not implemented.
+.IP setpriority 8
+.IX Item "setpriority"
+(Win32, VMS, RISC\ OS, VOS)
+Not implemented.
+.IP setpwent 8
+.IX Item "setpwent"
+(Android, Win32, RISC\ OS)
+Not implemented.
+.IP setsockopt 8
+.IX Item "setsockopt"
+(Plan\ 9)
+Not implemented.
+.IP shmctl 8
+.IX Item "shmctl"
+.PD 0
+.IP shmget 8
+.IX Item "shmget"
+.IP shmread 8
+.IX Item "shmread"
+.IP shmwrite 8
+.IX Item "shmwrite"
+.PD
+(Android, Win32, VMS, RISC\ OS)
+Not implemented.
+.IP sleep 8
+.IX Item "sleep"
+(Win32)
+Emulated using synchronization functions such that it can be
+interrupted by \f(CW\*(C`alarm\*(C'\fR, and limited to a
+maximum of 4294967 seconds, approximately 49 days.
+.IP socketpair 8
+.IX Item "socketpair"
+(RISC\ OS)
+Not implemented.
+.Sp
+(VMS)
+Available on 64 bit OpenVMS 8.2 and later.
+.IP stat 8
+.IX Item "stat"
+Platforms that do not have \f(CW\*(C`rdev\*(C'\fR, \f(CW\*(C`blksize\*(C'\fR, or \f(CW\*(C`blocks\*(C'\fR will return
+these as \f(CW\*(Aq\*(Aq\fR, so numeric comparison or manipulation of these fields may
+cause 'not numeric' warnings.
+.Sp
+(Mac\ OS\ X)
+\&\f(CW\*(C`ctime\*(C'\fR not supported on UFS.
+.Sp
+(Win32)
+\&\f(CW\*(C`ctime\*(C'\fR is creation time instead of inode change time.
+.Sp
+(VMS)
+\&\f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`ino\*(C'\fR are not necessarily reliable.
+.Sp
+(RISC\ OS)
+\&\f(CW\*(C`mtime\*(C'\fR, \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`ctime\*(C'\fR all return the last modification time.
+\&\f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`ino\*(C'\fR are not necessarily reliable.
+.Sp
+(OS/2)
+\&\f(CW\*(C`dev\*(C'\fR, \f(CW\*(C`rdev\*(C'\fR, \f(CW\*(C`blksize\*(C'\fR, and \f(CW\*(C`blocks\*(C'\fR are not available.  \f(CW\*(C`ino\*(C'\fR is not
+meaningful and will differ between stat calls on the same file.
+.Sp
+(Cygwin)
+Some versions of cygwin when doing a \f(CWstat("foo")\fR and not finding it
+may then attempt to \f(CWstat("foo.exe")\fR.
+.IP symlink 8
+.IX Item "symlink"
+(RISC\ OS)
+Not implemented.
+.Sp
+(Win32)
+Requires either elevated permissions or developer mode and a
+sufficiently recent version of Windows 10. You can check whether the current
+process has the required privileges using the
+\&\fBWin32::IsSymlinkCreationAllowed()\fR
+function.
+.Sp
+Since Windows needs to know whether the target is a directory or not when
+creating the link the target Perl will only create the link as a directory
+link when the target exists and is a directory.
+.Sp
+Windows does not recognize forward slashes as path separators in
+symbolic links.  Hence on Windows, any \f(CW\*(C`/\*(C'\fR in the \fIOLDFILE\fR
+parameter to \fBsymlink()\fR are converted to \f(CW\*(C`\e\*(C'\fR.  This is reflected in
+the result returned by \fBreadlink()\fR, the \f(CW\*(C`\e\*(C'\fR in the result are not
+converted back to \f(CW\*(C`/\*(C'\fR.
+.Sp
+(VMS)
+Implemented on 64 bit VMS 8.3.  VMS requires the symbolic link to be in Unix
+syntax if it is intended to resolve to a valid path.
+.IP syscall 8
+.IX Item "syscall"
+(Win32, VMS, RISC\ OS, VOS)
+Not implemented.
+.IP sysopen 8
+.IX Item "sysopen"
+(Mac\ OS, OS/390)
+The traditional \f(CW0\fR, \f(CW1\fR, and \f(CW2\fR MODEs are implemented with different
+numeric values on some systems.  The flags exported by \f(CW\*(C`Fcntl\*(C'\fR
+(\f(CW\*(C`O_RDONLY\*(C'\fR, \f(CW\*(C`O_WRONLY\*(C'\fR, \f(CW\*(C`O_RDWR\*(C'\fR) should work everywhere though.
+.IP system 8
+.IX Item "system"
+(Win32)
+As an optimization, may not call the command shell specified in
+\&\f(CW$ENV{PERL5SHELL}\fR.  \f(CW\*(C`system(1, @args)\*(C'\fR spawns an external
+process and immediately returns its process designator, without
+waiting for it to terminate.  Return value may be used subsequently
+in \f(CW\*(C`wait\*(C'\fR or \f(CW\*(C`waitpid\*(C'\fR.
+Failure to \f(CWspawn()\fR a subprocess is indicated by setting
+\&\f(CW$?\fR to \f(CW\*(C`255 << 8\*(C'\fR.  \f(CW$?\fR is set in a
+way compatible with Unix (i.e. the exit status of the subprocess is
+obtained by \f(CW\*(C`$? >> 8\*(C'\fR, as described in the documentation).
+.Sp
+Note that the list form of \fBsystem()\fR is emulated since the Win32 API
+\&\fBCreateProcess()\fR accepts a simple string rather than an array of
+command-line arguments.  This may have security implications for your
+code.
+.Sp
+(RISC\ OS)
+There is no shell to process metacharacters, and the native standard is
+to pass a command line terminated by "\en" "\er" or "\e0" to the spawned
+program.  Redirection such as \f(CW\*(C`> foo\*(C'\fR is performed (if at all) by
+the run time library of the spawned program.  \f(CW\*(C`system LIST\*(C'\fR will call
+the Unix emulation library's \f(CW\*(C`exec\*(C'\fR emulation,
+which attempts to provide emulation of the stdin, stdout, stderr in force
+in the parent, provided the child program uses a compatible version of the
+emulation library.  \f(CW\*(C`system SCALAR\*(C'\fR will call the native command line
+directly and no such emulation of a child Unix program will occur.
+Mileage \fBwill\fR vary.
+.Sp
+(Win32)
+\&\f(CW\*(C`system LIST\*(C'\fR without the use of indirect object syntax (\f(CW\*(C`system PROGRAM LIST\*(C'\fR)
+may fall back to trying the shell if the first \f(CWspawn()\fR fails.
+.Sp
+(SunOS, Solaris, HP-UX)
+Does not automatically flush output handles on some platforms.
+.Sp
+(VMS)
+As with Win32, \f(CW\*(C`system(1, @args)\*(C'\fR spawns an external process and
+immediately returns its process designator without waiting for the
+process to terminate.  In this case the return value may be used subsequently
+in \f(CW\*(C`wait\*(C'\fR or \f(CW\*(C`waitpid\*(C'\fR.
+Otherwise the return value is POSIX-like (shifted up by 8 bits), which only
+allows room for a made-up value derived from the severity bits of the native
+32\-bit condition code (unless overridden by
+\&\f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR).  If the native
+condition code is one that has a POSIX value encoded, the POSIX value will
+be decoded to extract the expected exit value.  For more details see
+"$?" in perlvms.
+.IP telldir 8
+.IX Item "telldir"
+(Android)
+Not implemented.
+.IP times 8
+.IX Item "times"
+(Win32)
+"Cumulative" times will be bogus.  On anything other than Windows NT
+or Windows 2000, "system" time will be bogus, and "user" time is
+actually the time returned by the \f(CWclock()\fR function in the C
+runtime library.
+.Sp
+(RISC\ OS)
+Not useful.
+.IP truncate 8
+.IX Item "truncate"
+(Older versions of VMS)
+Not implemented.
+.Sp
+(VOS)
+Truncation to same-or-shorter lengths only.
+.Sp
+(Win32)
+If a FILEHANDLE is supplied, it must be writable and opened in append
+mode (i.e., use \f(CW\*(C`open(my $fh, \*(Aq>>\*(Aq, \*(Aqfilename\*(Aq)\*(C'\fR
+or \f(CW\*(C`sysopen(my $fh, ..., O_APPEND|O_RDWR)\*(C'\fR.  If a filename is supplied, it
+should not be held open elsewhere.
+.IP umask 8
+.IX Item "umask"
+Returns \f(CW\*(C`undef\*(C'\fR where unavailable.
+.Sp
+(AmigaOS)
+\&\f(CW\*(C`umask\*(C'\fR works but the correct permissions are set only when the file
+is finally closed.
+.IP utime 8
+.IX Item "utime"
+(VMS, RISC\ OS)
+Only the modification time is updated.
+.Sp
+(Win32)
+May not behave as expected.  Behavior depends on the C runtime
+library's implementation of \f(CWutime()\fR, and the filesystem
+being used.  The FAT filesystem typically does not support an "access
+time" field, and it may limit timestamps to a granularity of two seconds.
+.IP wait 8
+.IX Item "wait"
+.PD 0
+.IP waitpid 8
+.IX Item "waitpid"
+.PD
+(Win32)
+Can only be applied to process handles returned for processes spawned
+using \f(CW\*(C`system(1, ...)\*(C'\fR or pseudo processes created with
+\&\f(CW\*(C`fork\*(C'\fR.
+.Sp
+(RISC\ OS)
+Not useful.
+.SH "Supported Platforms"
+.IX Header "Supported Platforms"
+The following platforms are known to build Perl 5.12 (as of April 2010,
+its release date) from the standard source code distribution available
+at <http://www.cpan.org/src>
+.IP "Linux (x86, ARM, IA64)" 4
+.IX Item "Linux (x86, ARM, IA64)"
+.PD 0
+.IP HP-UX 4
+.IX Item "HP-UX"
+.IP AIX 4
+.IX Item "AIX"
+.IP Win32 4
+.IX Item "Win32"
+.RS 4
+.IP "Windows 2000" 4
+.IX Item "Windows 2000"
+.IP "Windows XP" 4
+.IX Item "Windows XP"
+.IP "Windows Server 2003" 4
+.IX Item "Windows Server 2003"
+.IP "Windows Vista" 4
+.IX Item "Windows Vista"
+.IP "Windows Server 2008" 4
+.IX Item "Windows Server 2008"
+.IP "Windows 7" 4
+.IX Item "Windows 7"
+.RE
+.RS 4
+.RE
+.IP Cygwin 4
+.IX Item "Cygwin"
+.PD
+Some tests are known to fail:
+.RS 4
+.IP \(bu 4
+\&\fIext/XS\-APItest/t/call_checker.t\fR \- see
+<https://github.com/Perl/perl5/issues/10750>
+.IP \(bu 4
+\&\fIdist/I18N\-Collate/t/I18N\-Collate.t\fR
+.IP \(bu 4
+\&\fIext/Win32CORE/t/win32core.t\fR \- may fail on recent cygwin installs.
+.RE
+.RS 4
+.RE
+.IP "Solaris (x86, SPARC)" 4
+.IX Item "Solaris (x86, SPARC)"
+.PD 0
+.IP OpenVMS 4
+.IX Item "OpenVMS"
+.RS 4
+.IP "Alpha (7.2 and later)" 4
+.IX Item "Alpha (7.2 and later)"
+.IP "I64 (8.2 and later)" 4
+.IX Item "I64 (8.2 and later)"
+.RE
+.RS 4
+.RE
+.IP NetBSD 4
+.IX Item "NetBSD"
+.IP FreeBSD 4
+.IX Item "FreeBSD"
+.IP "Debian GNU/kFreeBSD" 4
+.IX Item "Debian GNU/kFreeBSD"
+.IP Haiku 4
+.IX Item "Haiku"
+.IP "Irix (6.5. What else?)" 4
+.IX Item "Irix (6.5. What else?)"
+.IP OpenBSD 4
+.IX Item "OpenBSD"
+.IP "Dragonfly BSD" 4
+.IX Item "Dragonfly BSD"
+.IP "Midnight BSD" 4
+.IX Item "Midnight BSD"
+.IP "QNX Neutrino RTOS (6.5.0)" 4
+.IX Item "QNX Neutrino RTOS (6.5.0)"
+.IP "MirOS BSD" 4
+.IX Item "MirOS BSD"
+.IP "Stratus OpenVOS (17.0 or later)" 4
+.IX Item "Stratus OpenVOS (17.0 or later)"
+.PD
+Caveats:
+.RS 4
+.IP "time_t issues that may or may not be fixed" 4
+.IX Item "time_t issues that may or may not be fixed"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Stratus VOS / OpenVOS" 4
+.IX Item "Stratus VOS / OpenVOS"
+.IP AIX 4
+.IX Item "AIX"
+.IP Android 4
+.IX Item "Android"
+.IP FreeMINT 4
+.IX Item "FreeMINT"
+.PD
+Perl now builds with FreeMiNT/Atari. It fails a few tests, that needs
+some investigation.
+.Sp
+The FreeMiNT port uses GNU dld for loadable module capabilities. So
+ensure you have that library installed when building perl.
+.SH "EOL Platforms"
+.IX Header "EOL Platforms"
+.SS "(Perl 5.37.1)"
+.IX Subsection "(Perl 5.37.1)"
+The following platforms were supported by a previous version of
+Perl but have been officially removed from Perl's source code
+as of 5.37.1:
+.IP Ultrix 4
+.IX Item "Ultrix"
+.SS "(Perl 5.36)"
+.IX Subsection "(Perl 5.36)"
+The following platforms were supported by a previous version of
+Perl but have been officially removed from Perl's source code
+as of 5.36:
+.IP NetWare 4
+.IX Item "NetWare"
+.PD 0
+.IP DOS/DJGPP 4
+.IX Item "DOS/DJGPP"
+.IP "AT&T UWIN" 4
+.IX Item "AT&T UWIN"
+.PD
+.SS "(Perl 5.20)"
+.IX Subsection "(Perl 5.20)"
+The following platforms were supported by a previous version of
+Perl but have been officially removed from Perl's source code
+as of 5.20:
+.IP "AT&T 3b1" 4
+.IX Item "AT&T 3b1"
+.SS "(Perl 5.14)"
+.IX Subsection "(Perl 5.14)"
+The following platforms were supported up to 5.10.  They may still
+have worked in 5.12, but supporting code has been removed for 5.14:
+.IP "Windows 95" 4
+.IX Item "Windows 95"
+.PD 0
+.IP "Windows 98" 4
+.IX Item "Windows 98"
+.IP "Windows ME" 4
+.IX Item "Windows ME"
+.IP "Windows NT4" 4
+.IX Item "Windows NT4"
+.PD
+.SS "(Perl 5.12)"
+.IX Subsection "(Perl 5.12)"
+The following platforms were supported by a previous version of
+Perl but have been officially removed from Perl's source code
+as of 5.12:
+.IP "Atari MiNT" 4
+.IX Item "Atari MiNT"
+.PD 0
+.IP "Apollo Domain/OS" 4
+.IX Item "Apollo Domain/OS"
+.IP "Apple Mac OS 8/9" 4
+.IX Item "Apple Mac OS 8/9"
+.IP "Tenon Machten" 4
+.IX Item "Tenon Machten"
+.PD
+.SH "Supported Platforms (Perl 5.8)"
+.IX Header "Supported Platforms (Perl 5.8)"
+As of July 2002 (the Perl release 5.8.0), the following platforms were
+able to build Perl from the standard source code distribution
+available at <http://www.cpan.org/src/>
+.PP
+.Vb 10
+\&        AIX
+\&        BeOS
+\&        BSD/OS          (BSDi)
+\&        Cygwin
+\&        DG/UX
+\&        DOS DJGPP       1)
+\&        DYNIX/ptx
+\&        EPOC R5
+\&        FreeBSD
+\&        HI\-UXMPP        (Hitachi) (5.8.0 worked but we didn\*(Aqt know it)
+\&        HP\-UX
+\&        IRIX
+\&        Linux
+\&        Mac OS Classic
+\&        Mac OS X        (Darwin)
+\&        MPE/iX
+\&        NetBSD
+\&        NetWare
+\&        NonStop\-UX
+\&        ReliantUNIX     (formerly SINIX)
+\&        OpenBSD
+\&        OpenVMS         (formerly VMS)
+\&        Open UNIX       (Unixware) (since Perl 5.8.1/5.9.0)
+\&        OS/2
+\&        OS/400          (using the PASE) (since Perl 5.8.1/5.9.0)
+\&        POSIX\-BC        (formerly BS2000)
+\&        QNX
+\&        Solaris
+\&        SunOS 4
+\&        SUPER\-UX        (NEC)
+\&        Tru64 UNIX      (formerly DEC OSF/1, Digital UNIX)
+\&        UNICOS
+\&        UNICOS/mk
+\&        UTS
+\&        VOS / OpenVOS
+\&        Win95/98/ME/2K/XP 2)
+\&        WinCE
+\&        z/OS            (formerly OS/390)
+\&        VM/ESA
+\&
+\&        1) in DOS mode either the DOS or OS/2 ports can be used
+\&        2) compilers: Borland, MinGW (GCC), VC6
+.Ve
+.PP
+The following platforms worked with the previous releases (5.6 and
+5.7), but we did not manage either to fix or to test these in time
+for the 5.8.0 release.  There is a very good chance that many of these
+will work fine with the 5.8.0.
+.PP
+.Vb 10
+\&        BSD/OS
+\&        DomainOS
+\&        Hurd
+\&        LynxOS
+\&        MachTen
+\&        PowerMAX
+\&        SCO SV
+\&        SVR4
+\&        Unixware
+\&        Windows 3.1
+.Ve
+.PP
+Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
+.PP
+.Vb 1
+\&        AmigaOS 3
+.Ve
+.PP
+The following platforms have been known to build Perl from source in
+the past (5.005_03 and earlier), but we haven't been able to verify
+their status for the current release, either because the
+hardware/software platforms are rare or because we don't have an
+active champion on these platforms\-\-or both.  They used to work,
+though, so go ahead and try compiling them, and let
+<https://github.com/Perl/perl5/issues> know
+of any trouble.
+.PP
+.Vb 10
+\&        3b1
+\&        A/UX
+\&        ConvexOS
+\&        CX/UX
+\&        DC/OSx
+\&        DDE SMES
+\&        DOS EMX
+\&        Dynix
+\&        EP/IX
+\&        ESIX
+\&        FPS
+\&        GENIX
+\&        Greenhills
+\&        ISC
+\&        MachTen 68k
+\&        MPC
+\&        NEWS\-OS
+\&        NextSTEP
+\&        OpenSTEP
+\&        Opus
+\&        Plan 9
+\&        RISC/os
+\&        SCO ODT/OSR
+\&        Stellar
+\&        SVR2
+\&        TI1500
+\&        TitanOS
+\&        Unisys Dynix
+.Ve
+.PP
+The following platforms have their own source code distributions and
+binaries available via <http://www.cpan.org/ports/>
+.PP
+.Vb 1
+\&                                Perl release
+\&
+\&        OS/400 (ILE)            5.005_02
+\&        Tandem Guardian         5.004
+.Ve
+.PP
+The following platforms have only binaries available via
+<http://www.cpan.org/ports/index.html> :
+.PP
+.Vb 1
+\&                                Perl release
+\&
+\&        Acorn RISCOS            5.005_02
+\&        AOS                     5.002
+\&        LynxOS                  5.004_02
+.Ve
+.PP
+Although we do suggest that you always build your own Perl from
+the source code, both for maximal configurability and for security,
+in case you are in a hurry you can check
+<http://www.cpan.org/ports/index.html> for binary distributions.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlaix, perlamiga, perlbs2000,
+perlcygwin,
+perlebcdic, perlfreebsd, perlhurd, perlhpux, perlirix,
+perlmacosx,
+perlos2, perlos390, perlos400,
+perlplan9, perlqnx, perlsolaris, perltru64,
+perlunicode, perlvms, perlvos, perlwin32, and Win32.
+.SH "AUTHORS / CONTRIBUTORS"
+.IX Header "AUTHORS / CONTRIBUTORS"
+Abigail <abigail@abigail.be>,
+Charles Bailey <bailey@newman.upenn.edu>,
+Graham Barr <gbarr@pobox.com>,
+Tom Christiansen <tchrist@perl.com>,
+Nicholas Clark <nick@ccl4.org>,
+Thomas Dorner <Thomas.Dorner@start.de>,
+Andy Dougherty <doughera@lafayette.edu>,
+Dominic Dunlop <domo@computer.org>,
+Neale Ferguson <neale@vma.tabnsw.com.au>,
+David J. Fiander <davidf@mks.com>,
+Paul Green <Paul.Green@stratus.com>,
+M.J.T. Guy <mjtg@cam.ac.uk>,
+Jarkko Hietaniemi <jhi@iki.fi>,
+Luther Huffman <lutherh@stratcom.com>,
+Nick Ing-Simmons <nick@ing\-simmons.net>,
+Andreas J. König <a.koenig@mind.de>,
+Markus Laker <mlaker@contax.co.uk>,
+Andrew M. Langmead <aml@world.std.com>,
+Lukas Mai <l.mai@web.de>,
+Larry Moore <ljmoore@freespace.net>,
+Paul Moore <Paul.Moore@uk.origin\-it.com>,
+Chris Nandor <pudge@pobox.com>,
+Matthias Neeracher <neeracher@mac.com>,
+Philip Newton <pne@cpan.org>,
+Gary Ng <71564.1743@CompuServe.COM>,
+Tom Phoenix <rootbeer@teleport.com>,
+André Pirard <A.Pirard@ulg.ac.be>,
+Peter Prymmer <pvhp@forte.com>,
+Hugo van der Sanden <hv@crypt0.demon.co.uk>,
+Gurusamy Sarathy <gsar@activestate.com>,
+Paul J. Schinder <schinder@pobox.com>,
+Michael G Schwern <schwern@pobox.com>,
+Dan Sugalski <dan@sidhe.org>,
+Nathan Torkington <gnat@frii.com>,
+John Malmberg <wb8tyw@qsl.net>
diff --git a/upstream/mageia-cauldron/man1/perlpragma.1 b/upstream/mageia-cauldron/man1/perlpragma.1
new file mode 100644
index 00000000..bc9afc5f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlpragma.1
@@ -0,0 +1,230 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLPRAGMA 1"
+.TH PERLPRAGMA 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlpragma \- how to write a user pragma
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A pragma is a module which influences some aspect of the compile time or run
+time behaviour of Perl, such as \f(CW\*(C`strict\*(C'\fR or \f(CW\*(C`warnings\*(C'\fR. With Perl 5.10 you
+are no longer limited to the built in pragmata; you can now create user
+pragmata that modify the behaviour of user functions within a lexical scope.
+.SH "A basic example"
+.IX Header "A basic example"
+For example, say you need to create a class implementing overloaded
+mathematical operators, and would like to provide your own pragma that
+functions much like \f(CW\*(C`use integer;\*(C'\fR You'd like this code
+.PP
+.Vb 1
+\&    use MyMaths;
+\&
+\&    my $l = MyMaths\->new(1.2);
+\&    my $r = MyMaths\->new(3.4);
+\&
+\&    print "A: ", $l + $r, "\en";
+\&
+\&    use myint;
+\&    print "B: ", $l + $r, "\en";
+\&
+\&    {
+\&        no myint;
+\&        print "C: ", $l + $r, "\en";
+\&    }
+\&
+\&    print "D: ", $l + $r, "\en";
+\&
+\&    no myint;
+\&    print "E: ", $l + $r, "\en";
+.Ve
+.PP
+to give the output
+.PP
+.Vb 5
+\&    A: 4.6
+\&    B: 4
+\&    C: 4.6
+\&    D: 4
+\&    E: 4.6
+.Ve
+.PP
+\&\fIi.e.\fR, where \f(CW\*(C`use myint;\*(C'\fR is in effect, addition operations are forced
+to integer, whereas by default they are not, with the default behaviour being
+restored via \f(CW\*(C`no myint;\*(C'\fR
+.PP
+The minimal implementation of the package \f(CW\*(C`MyMaths\*(C'\fR would be something like
+this:
+.PP
+.Vb 12
+\&    package MyMaths;
+\&    use v5.36;
+\&    use myint();
+\&    use overload \*(Aq+\*(Aq => sub {
+\&        my ($l, $r) = @_;
+\&        # Pass 1 to check up one call level from here
+\&        if (myint::in_effect(1)) {
+\&            int($$l) + int($$r);
+\&        } else {
+\&            $$l + $$r;
+\&        }
+\&    };
+\&
+\&    sub new {
+\&        my ($class, $value) = @_;
+\&        bless \e$value, $class;
+\&    }
+\&
+\&    1;
+.Ve
+.PP
+Note how we load the user pragma \f(CW\*(C`myint\*(C'\fR with an empty list \f(CW\*(C`()\*(C'\fR to
+prevent its \f(CW\*(C`import\*(C'\fR being called.
+.PP
+The interaction with the Perl compilation happens inside package \f(CW\*(C`myint\*(C'\fR:
+.PP
+.Vb 1
+\&    package myint;
+\&
+\&    use v5.36;
+\&
+\&    sub import {
+\&        $^H{"myint/in_effect"} = 1;
+\&    }
+\&
+\&    sub unimport {
+\&        $^H{"myint/in_effect"} = 0;
+\&    }
+\&
+\&    sub in_effect {
+\&        my $level = shift // 0;
+\&        my $hinthash = (caller($level))[10];
+\&        return $hinthash\->{"myint/in_effect"};
+\&    }
+\&
+\&    1;
+.Ve
+.PP
+As pragmata are implemented as modules, like any other module, \f(CW\*(C`use myint;\*(C'\fR
+becomes
+.PP
+.Vb 4
+\&    BEGIN {
+\&        require myint;
+\&        myint\->import();
+\&    }
+.Ve
+.PP
+and \f(CW\*(C`no myint;\*(C'\fR is
+.PP
+.Vb 4
+\&    BEGIN {
+\&        require myint;
+\&        myint\->unimport();
+\&    }
+.Ve
+.PP
+Hence the \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`unimport\*(C'\fR routines are called at \fBcompile time\fR
+for the user's code.
+.PP
+User pragmata store their state by writing to the magical hash \f(CW\*(C`%^H\*(C'\fR,
+hence these two routines manipulate it. The state information in \f(CW\*(C`%^H\*(C'\fR is
+stored in the optree, and can be retrieved read-only at runtime with \f(CWcaller()\fR,
+at index 10 of the list of returned results. In the example pragma, retrieval
+is encapsulated into the routine \f(CWin_effect()\fR, which takes as parameter
+the number of call frames to go up to find the value of the pragma in the
+user's script. This uses \f(CWcaller()\fR to determine the value of
+\&\f(CW$^H{"myint/in_effect"}\fR when each line of the user's script was called, and
+therefore provide the correct semantics in the subroutine implementing the
+overloaded addition.
+.SH "Key naming"
+.IX Header "Key naming"
+There is only a single \f(CW\*(C`%^H\*(C'\fR, but arbitrarily many modules that want
+to use its scoping semantics.  To avoid stepping on each other's toes,
+they need to be sure to use different keys in the hash.  It is therefore
+conventional for a module to use only keys that begin with the module's
+name (the name of its main package) and a "/" character.  After this
+module-identifying prefix, the rest of the key is entirely up to the
+module: it may include any characters whatsoever.  For example, a module
+\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR and \f(CW\*(C`Foo::Bar/$%/_!\*(C'\fR.
+Modules following this convention all play nicely with each other.
+.PP
+The Perl core uses a handful of keys in \f(CW\*(C`%^H\*(C'\fR which do not follow this
+convention, because they predate it.  Keys that follow the convention
+won't conflict with the core's historical keys.
+.SH "Implementation details"
+.IX Header "Implementation details"
+The optree is shared between threads.  This means there is a possibility that
+the optree will outlive the particular thread (and therefore the interpreter
+instance) that created it, so true Perl scalars cannot be stored in the
+optree.  Instead a compact form is used, which can only store values that are
+integers (signed and unsigned), strings or \f(CW\*(C`undef\*(C'\fR \- references and
+floating point values are stringified.  If you need to store multiple values
+or complex structures, you should serialise them, for example with \f(CW\*(C`pack\*(C'\fR.
+The deletion of a hash key from \f(CW\*(C`%^H\*(C'\fR is recorded, and as ever can be
+distinguished from the existence of a key with value \f(CW\*(C`undef\*(C'\fR with
+\&\f(CW\*(C`exists\*(C'\fR.
+.PP
+\&\fBDon't\fR attempt to store references to data structures as integers which
+are retrieved via \f(CW\*(C`caller\*(C'\fR and converted back, as this will not be threadsafe.
+Accesses would be to the structure without locking (which is not safe for
+Perl's scalars), and either the structure has to leak, or it has to be
+freed when its creating thread terminates, which may be before the optree
+referencing it is deleted, if other threads outlive it.
diff --git a/upstream/mageia-cauldron/man1/perlqnx.1 b/upstream/mageia-cauldron/man1/perlqnx.1
new file mode 100644
index 00000000..2553dc25
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlqnx.1
@@ -0,0 +1,251 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLQNX 1"
+.TH PERLQNX 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlqnx \- Perl version 5 on QNX
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+As of perl5.7.2 all tests pass under:
+.PP
+.Vb 3
+\&  QNX 4.24G
+\&  Watcom 10.6 with Beta/970211.wcc.update.tar.F
+\&  socket3r.lib Nov21 1996.
+.Ve
+.PP
+As of perl5.8.1 there is at least one test still failing.
+.PP
+Some tests may complain under known circumstances.
+.PP
+See below and hints/qnx.sh for more information.
+.PP
+Under QNX 6.2.0 there are still a few tests which fail.
+See below and hints/qnx.sh for more information.
+.SS "Required Software for Compiling Perl on QNX4"
+.IX Subsection "Required Software for Compiling Perl on QNX4"
+As with many unix ports, this one depends on a few "standard"
+unix utilities which are not necessarily standard for QNX4.
+.IP /bin/sh 4
+.IX Item "/bin/sh"
+This is used heavily by Configure and then by
+perl itself. QNX4's version is fine, but Configure
+will choke on the 16\-bit version, so if you are
+running QNX 4.22, link /bin/sh to /bin32/ksh
+.IP ar 4
+.IX Item "ar"
+This is the standard unix library builder.
+We use wlib. With Watcom 10.6, when wlib is
+linked as "ar", it behaves like ar and all is
+fine. Under 9.5, a cover is required. One is
+included in ../qnx
+.IP nm 4
+.IX Item "nm"
+This is used (optionally) by configure to list
+the contents of libraries. I will generate
+a cover function on the fly in the UU directory.
+.IP cpp 4
+.IX Item "cpp"
+Configure and perl need a way to invoke a C
+preprocessor. I have created a simple cover
+for cc which does the right thing. Without this,
+Configure will create its own wrapper which works,
+but it doesn't handle some of the command line arguments
+that perl will throw at it.
+.IP make 4
+.IX Item "make"
+You really need GNU make to compile this. GNU make
+ships by default with QNX 4.23, but you can get it
+from quics for earlier versions.
+.SS "Outstanding Issues with Perl on QNX4"
+.IX Subsection "Outstanding Issues with Perl on QNX4"
+There is no support for dynamically linked libraries in QNX4.
+.PP
+If you wish to compile with the Socket extension, you need
+to have the TCP/IP toolkit, and you need to make sure that
+\&\-lsocket locates the correct copy of socket3r.lib. Beware
+that the Watcom compiler ships with a stub version of
+socket3r.lib which has very little functionality. Also
+beware the order in which wlink searches directories for
+libraries. You may have /usr/lib/socket3r.lib pointing to
+the correct library, but wlink may pick up
+/usr/watcom/10.6/usr/lib/socket3r.lib instead. Make sure
+they both point to the correct library, that is,
+/usr/tcptk/current/usr/lib/socket3r.lib.
+.PP
+The following tests may report errors under QNX4:
+.PP
+dist/Cwd/Cwd.t will complain if `pwd` and cwd don't give
+the same results. cwd calls `fullpath \-t`, so if you
+cd `fullpath \-t` before running the test, it will
+pass.
+.PP
+lib/File/Find/taint.t will complain if '.' is in your
+PATH. The PATH test is triggered because cwd calls
+`fullpath \-t`.
+.PP
+ext/IO/lib/IO/t/io_sock.t: Subtests 14 and 22 are skipped due to
+the fact that the functionality to read back the non-blocking
+status of a socket is not implemented in QNX's TCP/IP. This has
+been reported to QNX and it may work with later versions of
+TCP/IP.
+.PP
+t/io/tell.t: Subtest 27 is failing. We are still investigating.
+.SS "QNX auxiliary files"
+.IX Subsection "QNX auxiliary files"
+The files in the "qnx" directory are:
+.IP qnx/ar 4
+.IX Item "qnx/ar"
+A script that emulates the standard unix archive (aka library)
+utility.  Under Watcom 10.6, ar is linked to wlib and provides the
+expected interface. With Watcom 9.5, a cover function is
+required. This one is fairly crude but has proved adequate for
+compiling perl.
+.IP qnx/cpp 4
+.IX Item "qnx/cpp"
+A script that provides C preprocessing functionality.  Configure can
+generate a similar cover, but it doesn't handle all the command-line
+options that perl throws at it. This might be reasonably placed in
+/usr/local/bin.
+.SS "Outstanding issues with perl under QNX6"
+.IX Subsection "Outstanding issues with perl under QNX6"
+The following tests are still failing for Perl 5.8.1 under QNX 6.2.0:
+.PP
+.Vb 2
+\&  op/sprintf.........................FAILED at test 91
+\&  lib/Benchmark......................FAILED at test 26
+.Ve
+.PP
+This is due to a bug in the C library's printf routine.
+printf("'%e'", 0. ) produces '0.000000e+0', but ANSI requires
+\&'0.000000e+00'. QNX has acknowledged the bug.
+.SS Cross-compilation
+.IX Subsection "Cross-compilation"
+Perl supports cross-compiling to QNX NTO through the
+Native Development Kit (NDK) for the Blackberry 10.  This means that you
+can cross-compile for both ARM and x86 versions of the platform.
+.PP
+\fISetting up a cross-compilation environment\fR
+.IX Subsection "Setting up a cross-compilation environment"
+.PP
+You can download the NDK from
+<http://developer.blackberry.com/native/downloads/>.
+.PP
+See
+<http://developer.blackberry.com/native/documentation/cascades/getting_started/setting_up.html>
+for instructions to set up your device prior to attempting anything else.
+.PP
+Once you've installed the NDK and set up your device, all that's
+left to do is setting up the device and the cross-compilation
+environment.  Blackberry provides a script, \f(CW\*(C`bbndk\-env.sh\*(C'\fR (occasionally
+named something like \f(CW\*(C`bbndk\-env_10_1_0_4828.sh\*(C'\fR) which can be used
+to do this.  However, there's a bit of a snag that we have to work through:
+The script modifies PATH so that 'gcc' or 'ar' point to their
+cross-compilation equivalents, which screws over the build process.
+.PP
+So instead you'll want to do something like this:
+.PP
+.Vb 3
+\&    $ orig_path=$PATH
+\&    $ source $location_of_bbndk/bbndk\-env*.sh
+\&    $ export PATH="$orig_path:$PATH"
+.Ve
+.PP
+Besides putting the cross-compiler and the rest of the toolchain in your
+PATH, this will also provide the QNX_TARGET variable, which
+we will pass to Configure through \-Dsysroot.
+.PP
+\fIPreparing the target system\fR
+.IX Subsection "Preparing the target system"
+.PP
+It's quite possible that the target system doesn't have a readily
+available /tmp, so it's generally safer to do something like this:
+.PP
+.Vb 3
+\& $ ssh $TARGETUSER@$TARGETHOST \*(Aqrm \-rf perl; mkdir perl; mkdir perl/tmp\*(Aq
+\& $ export TARGETDIR=\`ssh $TARGETUSER@$TARGETHOST pwd\`/perl
+\& $ export TARGETENV="export TMPDIR=$TARGETDIR/tmp; "
+.Ve
+.PP
+Later on, we'll pass this to Configure through \-Dtargetenv
+.PP
+\fICalling Configure\fR
+.IX Subsection "Calling Configure"
+.PP
+If you are targetting an ARM device \-\- which currently includes the vast 
+majority of phones and tablets \-\- you'll want to pass
+\&\-Dcc=arm\-unknown\-nto\-qnx8.0.0eabi\-gcc to Configure.  Alternatively, if you 
+are targetting an x86 device, or using the simulator provided with the NDK,
+you should specify \-Dcc=ntox86\-gcc instead.
+.PP
+A sample Configure invocation looks something like this:
+.PP
+.Vb 6
+\&    ./Configure \-des \-Dusecrosscompile \e
+\&        \-Dsysroot=$QNX_TARGET          \e
+\&        \-Dtargetdir=$TARGETDIR         \e
+\&        \-Dtargetenv="$TARGETENV"       \e
+\&        \-Dcc=ntox86\-gcc                \e
+\&        \-Dtarghost=... # Usual cross\-compilation options
+.Ve
+.SH AUTHOR
+.IX Header "AUTHOR"
+Norton T. Allen (allen@huarp.harvard.edu)
diff --git a/upstream/mageia-cauldron/man1/perlre.1 b/upstream/mageia-cauldron/man1/perlre.1
new file mode 100644
index 00000000..71dd726c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlre.1
@@ -0,0 +1,3711 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLRE 1"
+.TH PERLRE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlre \- Perl regular expressions
+.IX Xref "regular expression regex regexp"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This page describes the syntax of regular expressions in Perl.
+.PP
+If you haven't used regular expressions before, a tutorial introduction
+is available in perlretut.  If you know just a little about them,
+a quick-start introduction is available in perlrequick.
+.PP
+Except for "The Basics" section, this page assumes you are familiar
+with regular expression basics, like what is a "pattern", what does it
+look like, and how it is basically used.  For a reference on how they
+are used, plus various examples of the same, see discussions of \f(CW\*(C`m//\*(C'\fR,
+\&\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR and \f(CW"??"\fR in "Regexp Quote-Like Operators" in perlop.
+.PP
+New in v5.22, \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR applies stricter
+rules than otherwise when compiling regular expression patterns.  It can
+find things that, while legal, may not be what you intended.
+.SS "The Basics"
+.IX Xref "regular expression, version 8 regex, version 8 regexp, version 8"
+.IX Subsection "The Basics"
+Regular expressions are strings with the very particular syntax and
+meaning described in this document and auxiliary documents referred to
+by this one.  The strings are called "patterns".  Patterns are used to
+determine if some other string, called the "target", has (or doesn't
+have) the characteristics specified by the pattern.  We call this
+"matching" the target string against the pattern.  Usually the match is
+done by having the target be the first operand, and the pattern be the
+second operand, of one of the two binary operators \f(CW\*(C`=~\*(C'\fR and \f(CW\*(C`!~\*(C'\fR,
+listed in "Binding Operators" in perlop; and the pattern will have been
+converted from an ordinary string by one of the operators in
+"Regexp Quote-Like Operators" in perlop, like so:
+.PP
+.Vb 1
+\& $foo =~ m/abc/
+.Ve
+.PP
+This evaluates to true if and only if the string in the variable \f(CW$foo\fR
+contains somewhere in it, the sequence of characters "a", "b", then "c".
+(The \f(CW\*(C`=~ m\*(C'\fR, or match operator, is described in
+"m/PATTERN/msixpodualngc" in perlop.)
+.PP
+Patterns that aren't already stored in some variable must be delimited,
+at both ends, by delimiter characters.  These are often, as in the
+example above, forward slashes, and the typical way a pattern is written
+in documentation is with those slashes.  In most cases, the delimiter
+is the same character, fore and aft, but there are a few cases where a
+character looks like it has a mirror-image mate, where the opening
+version is the beginning delimiter, and the closing one is the ending
+delimiter, like
+.PP
+.Vb 1
+\& $foo =~ m<abc>
+.Ve
+.PP
+Most times, the pattern is evaluated in double-quotish context, but it
+is possible to choose delimiters to force single-quotish, like
+.PP
+.Vb 1
+\& $foo =~ m\*(Aqabc\*(Aq
+.Ve
+.PP
+If the pattern contains its delimiter within it, that delimiter must be
+escaped.  Prefixing it with a backslash (\fIe.g.\fR, \f(CW"/foo\e/bar/"\fR)
+serves this purpose.
+.PP
+Any single character in a pattern matches that same character in the
+target string, unless the character is a \fImetacharacter\fR with a special
+meaning described in this document.  A sequence of non-metacharacters
+matches the same sequence in the target string, as we saw above with
+\&\f(CW\*(C`m/abc/\*(C'\fR.
+.PP
+Only a few characters (all of them being ASCII punctuation characters)
+are metacharacters.  The most commonly used one is a dot \f(CW"."\fR, which
+normally matches almost any character (including a dot itself).
+.PP
+You can cause characters that normally function as metacharacters to be
+interpreted literally by prefixing them with a \f(CW"\e"\fR, just like the
+pattern's delimiter must be escaped if it also occurs within the
+pattern.  Thus, \f(CW"\e."\fR matches just a literal dot, \f(CW"."\fR instead of
+its normal meaning.  This means that the backslash is also a
+metacharacter, so \f(CW"\e\e"\fR matches a single \f(CW"\e"\fR.  And a sequence that
+contains an escaped metacharacter matches the same sequence (but without
+the escape) in the target string.  So, the pattern \f(CW\*(C`/blur\e\efl/\*(C'\fR would
+match any target string that contains the sequence \f(CW"blur\efl"\fR.
+.PP
+The metacharacter \f(CW"|"\fR is used to match one thing or another.  Thus
+.PP
+.Vb 1
+\& $foo =~ m/this|that/
+.Ve
+.PP
+is TRUE if and only if \f(CW$foo\fR contains either the sequence \f(CW"this"\fR or
+the sequence \f(CW"that"\fR.  Like all metacharacters, prefixing the \f(CW"|"\fR
+with a backslash makes it match the plain punctuation character; in its
+case, the VERTICAL LINE.
+.PP
+.Vb 1
+\& $foo =~ m/this\e|that/
+.Ve
+.PP
+is TRUE if and only if \f(CW$foo\fR contains the sequence \f(CW"this|that"\fR.
+.PP
+You aren't limited to just a single \f(CW"|"\fR.
+.PP
+.Vb 1
+\& $foo =~ m/fee|fie|foe|fum/
+.Ve
+.PP
+is TRUE if and only if \f(CW$foo\fR contains any of those 4 sequences from
+the children's story "Jack and the Beanstalk".
+.PP
+As you can see, the \f(CW"|"\fR binds less tightly than a sequence of
+ordinary characters.  We can override this by using the grouping
+metacharacters, the parentheses \f(CW"("\fR and \f(CW")"\fR.
+.PP
+.Vb 1
+\& $foo =~ m/th(is|at) thing/
+.Ve
+.PP
+is TRUE if and only if \f(CW$foo\fR contains either the sequence \f(CW"this\ thing"\fR or the sequence \f(CW"that\ thing"\fR.  The portions of the string
+that match the portions of the pattern enclosed in parentheses are
+normally made available separately for use later in the pattern,
+substitution, or program.  This is called "capturing", and it can get
+complicated.  See "Capture groups".
+.PP
+The first alternative includes everything from the last pattern
+delimiter (\f(CW"("\fR, \f(CW"(?:"\fR (described later), \fIetc\fR. or the beginning
+of the pattern) up to the first \f(CW"|"\fR, and the last alternative
+contains everything from the last \f(CW"|"\fR to the next closing pattern
+delimiter.  That's why it's common practice to include alternatives in
+parentheses: to minimize confusion about where they start and end.
+.PP
+Alternatives are tried from left to right, so the first
+alternative found for which the entire expression matches, is the one that
+is chosen. This means that alternatives are not necessarily greedy. For
+example: when matching \f(CW\*(C`foo|foot\*(C'\fR against \f(CW"barefoot"\fR, only the \f(CW"foo"\fR
+part will match, as that is the first alternative tried, and it successfully
+matches the target string. (This might not seem important, but it is
+important when you are capturing matched text using parentheses.)
+.PP
+Besides taking away the special meaning of a metacharacter, a prefixed
+backslash changes some letter and digit characters away from matching
+just themselves to instead have special meaning.  These are called
+"escape sequences", and all such are described in perlrebackslash.  A
+backslash sequence (of a letter or digit) that doesn't currently have
+special meaning to Perl will raise a warning if warnings are enabled,
+as those are reserved for potential future use.
+.PP
+One such sequence is \f(CW\*(C`\eb\*(C'\fR, which matches a boundary of some sort.
+\&\f(CW\*(C`\eb{wb}\*(C'\fR and a few others give specialized types of boundaries.
+(They are all described in detail starting at
+"\eb{}, \eb, \eB{}, \eB" in perlrebackslash.)  Note that these don't match
+characters, but the zero-width spaces between characters.  They are an
+example of a zero-width assertion.  Consider again,
+.PP
+.Vb 1
+\& $foo =~ m/fee|fie|foe|fum/
+.Ve
+.PP
+It evaluates to TRUE if, besides those 4 words, any of the sequences
+"feed", "field", "Defoe", "fume", and many others are in \f(CW$foo\fR.  By
+judicious use of \f(CW\*(C`\eb\*(C'\fR (or better (because it is designed to handle
+natural language) \f(CW\*(C`\eb{wb}\*(C'\fR), we can make sure that only the Giant's
+words are matched:
+.PP
+.Vb 2
+\& $foo =~ m/\eb(fee|fie|foe|fum)\eb/
+\& $foo =~ m/\eb{wb}(fee|fie|foe|fum)\eb{wb}/
+.Ve
+.PP
+The final example shows that the characters \f(CW"{"\fR and \f(CW"}"\fR are
+metacharacters.
+.PP
+Another use for escape sequences is to specify characters that cannot
+(or which you prefer not to) be written literally.  These are described
+in detail in "Character Escapes" in perlrebackslash, but the next three
+paragraphs briefly describe some of them.
+.PP
+Various control characters can be written in C language style: \f(CW"\en"\fR
+matches a newline, \f(CW"\et"\fR a tab, \f(CW"\er"\fR a carriage return, \f(CW"\ef"\fR a
+form feed, \fIetc\fR.
+.PP
+More generally, \f(CW\*(C`\e\fR\f(CInnn\fR\f(CW\*(C'\fR, where \fInnn\fR is a string of three octal
+digits, matches the character whose native code point is \fInnn\fR.  You
+can easily run into trouble if you don't have exactly three digits.  So
+always use three, or since Perl 5.14, you can use \f(CW\*(C`\eo{...}\*(C'\fR to specify
+any number of octal digits.
+.PP
+Similarly, \f(CW\*(C`\ex\fR\f(CInn\fR\f(CW\*(C'\fR, where \fInn\fR are hexadecimal digits, matches the
+character whose native ordinal is \fInn\fR.  Again, not using exactly two
+digits is a recipe for disaster, but you can use \f(CW\*(C`\ex{...}\*(C'\fR to specify
+any number of hex digits.
+.PP
+Besides being a metacharacter, the \f(CW"."\fR is an example of a "character
+class", something that can match any single character of a given set of
+them.  In its case, the set is just about all possible characters.  Perl
+predefines several character classes besides the \f(CW"."\fR; there is a
+separate reference page about just these, perlrecharclass.
+.PP
+You can define your own custom character classes, by putting into your
+pattern in the appropriate place(s), a list of all the characters you
+want in the set.  You do this by enclosing the list within \f(CW\*(C`[]\*(C'\fR bracket
+characters.  These are called "bracketed character classes" when we are
+being precise, but often the word "bracketed" is dropped.  (Dropping it
+usually doesn't cause confusion.)  This means that the \f(CW"["\fR character
+is another metacharacter.  It doesn't match anything just by itself; it
+is used only to tell Perl that what follows it is a bracketed character
+class.  If you want to match a literal left square bracket, you must
+escape it, like \f(CW"\e["\fR.  The matching \f(CW"]"\fR is also a metacharacter;
+again it doesn't match anything by itself, but just marks the end of
+your custom class to Perl.  It is an example of a "sometimes
+metacharacter".  It isn't a metacharacter if there is no corresponding
+\&\f(CW"["\fR, and matches its literal self:
+.PP
+.Vb 1
+\& print "]" =~ /]/;  # prints 1
+.Ve
+.PP
+The list of characters within the character class gives the set of
+characters matched by the class.  \f(CW"[abc]"\fR matches a single "a" or "b"
+or "c".  But if the first character after the \f(CW"["\fR is \f(CW"^"\fR, the
+class instead matches any character not in the list.  Within a list, the
+\&\f(CW"\-"\fR character specifies a range of characters, so that \f(CW\*(C`a\-z\*(C'\fR
+represents all characters between "a" and "z", inclusive.  If you want
+either \f(CW"\-"\fR or \f(CW"]"\fR itself to be a member of a class, put it at the
+start of the list (possibly after a \f(CW"^"\fR), or escape it with a
+backslash.  \f(CW"\-"\fR is also taken literally when it is at the end of the
+list, just before the closing \f(CW"]"\fR.  (The following all specify the
+same class of three characters: \f(CW\*(C`[\-az]\*(C'\fR, \f(CW\*(C`[az\-]\*(C'\fR, and \f(CW\*(C`[a\e\-z]\*(C'\fR.  All
+are different from \f(CW\*(C`[a\-z]\*(C'\fR, which specifies a class containing
+twenty-six characters, even on EBCDIC-based character sets.)
+.PP
+There is lots more to bracketed character classes; full details are in
+"Bracketed Character Classes" in perlrecharclass.
+.PP
+\fIMetacharacters\fR
+.IX Xref "metacharacter \\ ^ . $ | ( () [ []"
+.IX Subsection "Metacharacters"
+.PP
+"The Basics" introduced some of the metacharacters.  This section
+gives them all.  Most of them have the same meaning as in the \fIegrep\fR
+command.
+.PP
+Only the \f(CW"\e"\fR is always a metacharacter.  The others are metacharacters
+just sometimes.  The following tables lists all of them, summarizes
+their use, and gives the contexts where they are metacharacters.
+Outside those contexts or if prefixed by a \f(CW"\e"\fR, they match their
+corresponding punctuation character.  In some cases, their meaning
+varies depending on various pattern modifiers that alter the default
+behaviors.  See "Modifiers".
+.PP
+.Vb 10
+\&            PURPOSE                                  WHERE
+\& \e   Escape the next character                    Always, except when
+\&                                                  escaped by another \e
+\& ^   Match the beginning of the string            Not in []
+\&       (or line, if /m is used)
+\& ^   Complement the [] class                      At the beginning of []
+\& .   Match any single character except newline    Not in []
+\&       (under /s, includes newline)
+\& $   Match the end of the string                  Not in [], but can
+\&       (or before newline at the end of the       mean interpolate a
+\&       string; or before any newline if /m is     scalar
+\&       used)
+\& |   Alternation                                  Not in []
+\& ()  Grouping                                     Not in []
+\& [   Start Bracketed Character class              Not in []
+\& ]   End Bracketed Character class                Only in [], and
+\&                                                    not first
+\& *   Matches the preceding element 0 or more      Not in []
+\&       times
+\& +   Matches the preceding element 1 or more      Not in []
+\&       times
+\& ?   Matches the preceding element 0 or 1         Not in []
+\&       times
+\& {   Starts a sequence that gives number(s)       Not in []
+\&       of times the preceding element can be
+\&       matched
+\& {   when following certain escape sequences
+\&       starts a modifier to the meaning of the
+\&       sequence
+\& }   End sequence started by {
+\& \-   Indicates a range                            Only in [] interior
+\& #   Beginning of comment, extends to line end    Only with /x modifier
+.Ve
+.PP
+Notice that most of the metacharacters lose their special meaning when
+they occur in a bracketed character class, except \f(CW"^"\fR has a different
+meaning when it is at the beginning of such a class.  And \f(CW"\-"\fR and \f(CW"]"\fR
+are metacharacters only at restricted positions within bracketed
+character classes; while \f(CW"}"\fR is a metacharacter only when closing a
+special construct started by \f(CW"{"\fR.
+.PP
+In double-quotish context, as is usually the case,  you need to be
+careful about \f(CW"$"\fR and the non-metacharacter \f(CW"@"\fR.  Those could
+interpolate variables, which may or may not be what you intended.
+.PP
+These rules were designed for compactness of expression, rather than
+legibility and maintainability.  The "/x and /xx" pattern
+modifiers allow you to insert white space to improve readability.  And
+use of \f(CW\*(C`re\ \*(Aqstrict\*(Aq\*(C'\fR adds extra checking to
+catch some typos that might silently compile into something unintended.
+.PP
+By default, the \f(CW"^"\fR character is guaranteed to match only the
+beginning of the string, the \f(CW"$"\fR character only the end (or before the
+newline at the end), and Perl does certain optimizations with the
+assumption that the string contains only one line.  Embedded newlines
+will not be matched by \f(CW"^"\fR or \f(CW"$"\fR.  You may, however, wish to treat a
+string as a multi-line buffer, such that the \f(CW"^"\fR will match after any
+newline within the string (except if the newline is the last character in
+the string), and \f(CW"$"\fR will match before any newline.  At the
+cost of a little more overhead, you can do this by using the
+\&\f(CW"/m"\fR modifier on the pattern match operator.  (Older programs
+did this by setting \f(CW$*\fR, but this option was removed in perl 5.10.)
+.IX Xref "^ $ m"
+.PP
+To simplify multi-line substitutions, the \f(CW"."\fR character never matches a
+newline unless you use the \f(CW\*(C`/s\*(C'\fR modifier, which in effect tells
+Perl to pretend the string is a single line\-\-even if it isn't.
+.IX Xref ". s"
+.SS Modifiers
+.IX Subsection "Modifiers"
+\fIOverview\fR
+.IX Subsection "Overview"
+.PP
+The default behavior for matching can be changed, using various
+modifiers.  Modifiers that relate to the interpretation of the pattern
+are listed just below.  Modifiers that alter the way a pattern is used
+by Perl are detailed in "Regexp Quote-Like Operators" in perlop and
+"Gory details of parsing quoted constructs" in perlop.  Modifiers can be added
+dynamically; see "Extended Patterns" below.
+.ie n .IP "\fR\fB""m""\fR\fB\fR" 4
+.el .IP \fR\f(CBm\fR\fB\fR 4
+.IX Xref " m regex, multiline regexp, multiline regular expression, multiline"
+.IX Item "m"
+Treat the string being matched against as multiple lines.  That is, change \f(CW"^"\fR and \f(CW"$"\fR from matching
+the start of the string's first line and the end of its last line to
+matching the start and end of each line within the string.
+.ie n .IP "\fR\fB""s""\fR\fB\fR" 4
+.el .IP \fR\f(CBs\fR\fB\fR 4
+.IX Xref " s regex, single-line regexp, single-line regular expression, single-line"
+.IX Item "s"
+Treat the string as single line.  That is, change \f(CW"."\fR to match any character
+whatsoever, even a newline, which normally it would not match.
+.Sp
+Used together, as \f(CW\*(C`/ms\*(C'\fR, they let the \f(CW"."\fR match any character whatsoever,
+while still allowing \f(CW"^"\fR and \f(CW"$"\fR to match, respectively, just after
+and just before newlines within the string.
+.ie n .IP "\fR\fB""i""\fR\fB\fR" 4
+.el .IP \fR\f(CBi\fR\fB\fR 4
+.IX Xref " i regex, case-insensitive regexp, case-insensitive regular expression, case-insensitive"
+.IX Item "i"
+Do case-insensitive pattern matching.  For example, "A" will match "a"
+under \f(CW\*(C`/i\*(C'\fR.
+.Sp
+If locale matching rules are in effect, the case map is taken from the
+current
+locale for code points less than 255, and from Unicode rules for larger
+code points.  However, matches that would cross the Unicode
+rules/non\-Unicode rules boundary (ords 255/256) will not succeed, unless
+the locale is a UTF\-8 one.  See perllocale.
+.Sp
+There are a number of Unicode characters that match a sequence of
+multiple characters under \f(CW\*(C`/i\*(C'\fR.  For example,
+\&\f(CW\*(C`LATIN SMALL LIGATURE FI\*(C'\fR should match the sequence \f(CW\*(C`fi\*(C'\fR.  Perl is not
+currently able to do this when the multiple characters are in the pattern and
+are split between groupings, or when one or more are quantified.  Thus
+.Sp
+.Vb 3
+\& "\eN{LATIN SMALL LIGATURE FI}" =~ /fi/i;          # Matches
+\& "\eN{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i;    # Doesn\*(Aqt match!
+\& "\eN{LATIN SMALL LIGATURE FI}" =~ /fi*/i;         # Doesn\*(Aqt match!
+\&
+\& # The below doesn\*(Aqt match, and it isn\*(Aqt clear what $1 and $2 would
+\& # be even if it did!!
+\& "\eN{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i;      # Doesn\*(Aqt match!
+.Ve
+.Sp
+Perl doesn't match multiple characters in a bracketed
+character class unless the character that maps to them is explicitly
+mentioned, and it doesn't match them at all if the character class is
+inverted, which otherwise could be highly confusing.  See
+"Bracketed Character Classes" in perlrecharclass, and
+"Negation" in perlrecharclass.
+.ie n .IP "\fR\fB""x""\fR\fB\fR and \fB\fR\fB""xx""\fR\fB\fR" 4
+.el .IP "\fR\f(CBx\fR\fB\fR and \fB\fR\f(CBxx\fR\fB\fR" 4
+.IX Xref " x"
+.IX Item "x and xx"
+Extend your pattern's legibility by permitting whitespace and comments.
+Details in "/x and  /xx"
+.ie n .IP "\fR\fB""p""\fR\fB\fR" 4
+.el .IP \fR\f(CBp\fR\fB\fR 4
+.IX Xref " p regex, preserve regexp, preserve"
+.IX Item "p"
+Preserve the string matched such that \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR, and
+\&\f(CW\*(C`${^POSTMATCH}\*(C'\fR are available for use after matching.
+.Sp
+In Perl 5.20 and higher this is ignored. Due to a new copy-on-write
+mechanism, \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR will be available
+after the match regardless of the modifier.
+.ie n .IP "\fR\fB""a""\fR\fB\fR, \fB\fR\fB""d""\fR\fB\fR, \fB\fR\fB""l""\fR\fB\fR, and \fB\fR\fB""u""\fR\fB\fR" 4
+.el .IP "\fR\f(CBa\fR\fB\fR, \fB\fR\f(CBd\fR\fB\fR, \fB\fR\f(CBl\fR\fB\fR, and \fB\fR\f(CBu\fR\fB\fR" 4
+.IX Xref " a d l u"
+.IX Item "a, d, l, and u"
+These modifiers, all new in 5.14, affect which character-set rules
+(Unicode, \fIetc\fR.) are used, as described below in
+"Character set modifiers".
+.ie n .IP "\fR\fB""n""\fR\fB\fR" 4
+.el .IP \fR\f(CBn\fR\fB\fR 4
+.IX Xref " n regex, non-capture regexp, non-capture regular expression, non-capture"
+.IX Item "n"
+Prevent the grouping metacharacters \f(CW\*(C`()\*(C'\fR from capturing. This modifier,
+new in 5.22, will stop \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR... from being filled in.
+.Sp
+.Vb 2
+\&  "hello" =~ /(hi|hello)/;   # $1 is "hello"
+\&  "hello" =~ /(hi|hello)/n;  # $1 is undef
+.Ve
+.Sp
+This is equivalent to putting \f(CW\*(C`?:\*(C'\fR at the beginning of every capturing group:
+.Sp
+.Vb 1
+\&  "hello" =~ /(?:hi|hello)/; # $1 is undef
+.Ve
+.Sp
+\&\f(CW\*(C`/n\*(C'\fR can be negated on a per-group basis. Alternatively, named captures
+may still be used.
+.Sp
+.Vb 3
+\&  "hello" =~ /(?\-n:(hi|hello))/n;   # $1 is "hello"
+\&  "hello" =~ /(?<greet>hi|hello)/n; # $1 is "hello", $+{greet} is
+\&                                    # "hello"
+.Ve
+.IP "Other Modifiers" 4
+.IX Item "Other Modifiers"
+There are a number of flags that can be found at the end of regular
+expression constructs that are \fInot\fR generic regular expression flags, but
+apply to the operation being performed, like matching or substitution (\f(CW\*(C`m//\*(C'\fR
+or \f(CW\*(C`s///\*(C'\fR respectively).
+.Sp
+Flags described further in
+"Using regular expressions in Perl" in perlretut are:
+.Sp
+.Vb 2
+\&  c  \- keep the current position during repeated matching
+\&  g  \- globally match the pattern repeatedly in the string
+.Ve
+.Sp
+Substitution-specific modifiers described in
+"s/PATTERN/REPLACEMENT/msixpodualngcer" in perlop are:
+.Sp
+.Vb 4
+\&  e  \- evaluate the right\-hand side as an expression
+\&  ee \- evaluate the right side as a string then eval the result
+\&  o  \- pretend to optimize your code, but actually introduce bugs
+\&  r  \- perform non\-destructive substitution and return the new value
+.Ve
+.PP
+Regular expression modifiers are usually written in documentation
+as \fIe.g.\fR, "the \f(CW\*(C`/x\*(C'\fR modifier", even though the delimiter
+in question might not really be a slash.  The modifiers \f(CW\*(C`/imnsxadlup\*(C'\fR
+may also be embedded within the regular expression itself using
+the \f(CW\*(C`(?...)\*(C'\fR construct, see "Extended Patterns" below.
+.PP
+\fIDetails on some modifiers\fR
+.IX Subsection "Details on some modifiers"
+.PP
+Some of the modifiers require more explanation than given in the
+"Overview" above.
+.PP
+\f(CW\*(C`/x\*(C'\fR and  \f(CW\*(C`/xx\*(C'\fR
+.IX Subsection "/x and /xx"
+.PP
+A single \f(CW\*(C`/x\*(C'\fR tells
+the regular expression parser to ignore most whitespace that is neither
+backslashed nor within a bracketed character class, nor within the characters
+of a multi-character metapattern like \f(CW\*(C`(?i: ... )\*(C'\fR.  You can use this to
+break up your regular expression into more readable parts.
+Also, the \f(CW"#"\fR character is treated as a metacharacter introducing a
+comment that runs up to the pattern's closing delimiter, or to the end
+of the current line if the pattern extends onto the next line.  Hence,
+this is very much like an ordinary Perl code comment.  (You can include
+the closing delimiter within the comment only if you precede it with a
+backslash, so be careful!)
+.PP
+Use of \f(CW\*(C`/x\*(C'\fR means that if you want real
+whitespace or \f(CW"#"\fR characters in the pattern (outside a bracketed character
+class, which is unaffected by \f(CW\*(C`/x\*(C'\fR), then you'll either have to
+escape them (using backslashes or \f(CW\*(C`\eQ...\eE\*(C'\fR) or encode them using octal,
+hex, or \f(CW\*(C`\eN{}\*(C'\fR or \f(CW\*(C`\ep{name=...}\*(C'\fR escapes.
+It is ineffective to try to continue a comment onto the next line by
+escaping the \f(CW\*(C`\en\*(C'\fR with a backslash or \f(CW\*(C`\eQ\*(C'\fR.
+.PP
+You can use "(?#text)" to create a comment that ends earlier than the
+end of the current line, but \f(CW\*(C`text\*(C'\fR also can't contain the closing
+delimiter unless escaped with a backslash.
+.PP
+A common pitfall is to forget that \f(CW"#"\fR characters (outside a
+bracketed character class) begin a comment under \f(CW\*(C`/x\*(C'\fR and are not
+matched literally.  Just keep that in mind when trying to puzzle out why
+a particular \f(CW\*(C`/x\*(C'\fR pattern isn't working as expected.
+Inside a bracketed character class, \f(CW"#"\fR retains its non-special,
+literal meaning.
+.PP
+Starting in Perl v5.26, if the modifier has a second \f(CW"x"\fR within it,
+the effect of a single \f(CW\*(C`/x\*(C'\fR is increased.  The only difference is that
+inside bracketed character classes, non-escaped (by a backslash) SPACE
+and TAB characters are not added to the class, and hence can be inserted
+to make the classes more readable:
+.PP
+.Vb 2
+\&    / [d\-e g\-i 3\-7]/xx
+\&    /[ ! @ " # $ % ^ & * () = ? <> \*(Aq ]/xx
+.Ve
+.PP
+may be easier to grasp than the squashed equivalents
+.PP
+.Vb 2
+\&    /[d\-eg\-i3\-7]/
+\&    /[!@"#$%^&*()=?<>\*(Aq]/
+.Ve
+.PP
+Note that this unfortunately doesn't mean that your bracketed classes
+can contain comments or extend over multiple lines.  A \f(CW\*(C`#\*(C'\fR inside a
+character class is still just a literal \f(CW\*(C`#\*(C'\fR, and doesn't introduce a
+comment.  And, unless the closing bracket is on the same line as the
+opening one, the newline character (and everything on the next line(s)
+until terminated by a \f(CW\*(C`]\*(C'\fR will be part of the class, just as if you'd
+written \f(CW\*(C`\en\*(C'\fR.
+.PP
+Taken together, these features go a long way towards
+making Perl's regular expressions more readable.  Here's an example:
+.PP
+.Vb 6
+\&    # Delete (most) C comments.
+\&    $program =~ s {
+\&        /\e*     # Match the opening delimiter.
+\&        .*?     # Match a minimal number of characters.
+\&        \e*/     # Match the closing delimiter.
+\&    } []gsx;
+.Ve
+.PP
+Note that anything inside
+a \f(CW\*(C`\eQ...\eE\*(C'\fR stays unaffected by \f(CW\*(C`/x\*(C'\fR.  And note that \f(CW\*(C`/x\*(C'\fR doesn't affect
+space interpretation within a single multi-character construct.  For
+example \f(CW\*(C`(?:...)\*(C'\fR can't have a space between the \f(CW"("\fR,
+\&\f(CW"?"\fR, and \f(CW":"\fR.  Within any delimiters for such a construct, allowed
+spaces are not affected by \f(CW\*(C`/x\*(C'\fR, and depend on the construct.  For
+example, all constructs using curly braces as delimiters, such as
+\&\f(CW\*(C`\ex{...}\*(C'\fR can have blanks within but adjacent to the braces, but not
+elsewhere, and no non-blank space characters.  An exception are Unicode
+properties which follow Unicode rules, for which see
+"Properties accessible through \ep{} and \eP{}" in perluniprops.
+.IX Xref " x"
+.PP
+The set of characters that are deemed whitespace are those that Unicode
+calls "Pattern White Space", namely:
+.PP
+.Vb 11
+\& U+0009 CHARACTER TABULATION
+\& U+000A LINE FEED
+\& U+000B LINE TABULATION
+\& U+000C FORM FEED
+\& U+000D CARRIAGE RETURN
+\& U+0020 SPACE
+\& U+0085 NEXT LINE
+\& U+200E LEFT\-TO\-RIGHT MARK
+\& U+200F RIGHT\-TO\-LEFT MARK
+\& U+2028 LINE SEPARATOR
+\& U+2029 PARAGRAPH SEPARATOR
+.Ve
+.PP
+Character set modifiers
+.IX Subsection "Character set modifiers"
+.PP
+\&\f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, \f(CW\*(C`/a\*(C'\fR, and \f(CW\*(C`/l\*(C'\fR, available starting in 5.14, are called
+the character set modifiers; they affect the character set rules
+used for the regular expression.
+.PP
+The \f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, and \f(CW\*(C`/l\*(C'\fR modifiers are not likely to be of much use
+to you, and so you need not worry about them very much.  They exist for
+Perl's internal use, so that complex regular expression data structures
+can be automatically serialized and later exactly reconstituted,
+including all their nuances.  But, since Perl can't keep a secret, and
+there may be rare instances where they are useful, they are documented
+here.
+.PP
+The \f(CW\*(C`/a\*(C'\fR modifier, on the other hand, may be useful.  Its purpose is to
+allow code that is to work mostly on ASCII data to not have to concern
+itself with Unicode.
+.PP
+Briefly, \f(CW\*(C`/l\*(C'\fR sets the character set to that of whatever \fBL\fRocale is in
+effect at the time of the execution of the pattern match.
+.PP
+\&\f(CW\*(C`/u\*(C'\fR sets the character set to \fBU\fRnicode.
+.PP
+\&\f(CW\*(C`/a\*(C'\fR also sets the character set to Unicode, BUT adds several
+restrictions for \fBA\fRSCII-safe matching.
+.PP
+\&\f(CW\*(C`/d\*(C'\fR is the old, problematic, pre\-5.14 \fBD\fRefault character set
+behavior.  Its only use is to force that old behavior.
+.PP
+At any given time, exactly one of these modifiers is in effect.  Their
+existence allows Perl to keep the originally compiled behavior of a
+regular expression, regardless of what rules are in effect when it is
+actually executed.  And if it is interpolated into a larger regex, the
+original's rules continue to apply to it, and don't affect the other
+parts.
+.PP
+The \f(CW\*(C`/l\*(C'\fR and \f(CW\*(C`/u\*(C'\fR modifiers are automatically selected for
+regular expressions compiled within the scope of various pragmas,
+and we recommend that in general, you use those pragmas instead of
+specifying these modifiers explicitly.  For one thing, the modifiers
+affect only pattern matching, and do not extend to even any replacement
+done, whereas using the pragmas gives consistent results for all
+appropriate operations within their scopes.  For example,
+.PP
+.Vb 1
+\& s/foo/\eUbar/il
+.Ve
+.PP
+will match "foo" using the locale's rules for case-insensitive matching,
+but the \f(CW\*(C`/l\*(C'\fR does not affect how the \f(CW\*(C`\eU\*(C'\fR operates.  Most likely you
+want both of them to use locale rules.  To do this, instead compile the
+regular expression within the scope of \f(CW\*(C`use locale\*(C'\fR.  This both
+implicitly adds the \f(CW\*(C`/l\*(C'\fR, and applies locale rules to the \f(CW\*(C`\eU\*(C'\fR.   The
+lesson is to \f(CW\*(C`use locale\*(C'\fR, and not \f(CW\*(C`/l\*(C'\fR explicitly.
+.PP
+Similarly, it would be better to use \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR
+instead of,
+.PP
+.Vb 1
+\& s/foo/\eLbar/iu
+.Ve
+.PP
+to get Unicode rules, as the \f(CW\*(C`\eL\*(C'\fR in the former (but not necessarily
+the latter) would also use Unicode rules.
+.PP
+More detail on each of the modifiers follows.  Most likely you don't
+need to know this detail for \f(CW\*(C`/l\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, and \f(CW\*(C`/d\*(C'\fR, and can skip ahead
+to /a.
+.PP
+/l
+.IX Subsection "/l"
+.PP
+means to use the current locale's rules (see perllocale) when pattern
+matching.  For example, \f(CW\*(C`\ew\*(C'\fR will match the "word" characters of that
+locale, and \f(CW"/i"\fR case-insensitive matching will match according to
+the locale's case folding rules.  The locale used will be the one in
+effect at the time of execution of the pattern match.  This may not be
+the same as the compilation-time locale, and can differ from one match
+to another if there is an intervening call of the
+\&\fBsetlocale()\fR function.
+.PP
+Prior to v5.20, Perl did not support multi-byte locales.  Starting then,
+UTF\-8 locales are supported.  No other multi byte locales are ever
+likely to be supported.  However, in all locales, one can have code
+points above 255 and these will always be treated as Unicode no matter
+what locale is in effect.
+.PP
+Under Unicode rules, there are a few case-insensitive matches that cross
+the 255/256 boundary.  Except for UTF\-8 locales in Perls v5.20 and
+later, these are disallowed under \f(CW\*(C`/l\*(C'\fR.  For example, 0xFF (on ASCII
+platforms) does not caselessly match the character at 0x178, \f(CW\*(C`LATIN
+CAPITAL LETTER Y WITH DIAERESIS\*(C'\fR, because 0xFF may not be \f(CW\*(C`LATIN SMALL
+LETTER Y WITH DIAERESIS\*(C'\fR in the current locale, and Perl has no way of
+knowing if that character even exists in the locale, much less what code
+point it is.
+.PP
+In a UTF\-8 locale in v5.20 and later, the only visible difference
+between locale and non-locale in regular expressions should be tainting,
+if your perl supports taint checking (see perlsec).
+.PP
+This modifier may be specified to be the default by \f(CW\*(C`use locale\*(C'\fR, but
+see "Which character set modifier is in effect?".
+.IX Xref " l"
+.PP
+/u
+.IX Subsection "/u"
+.PP
+means to use Unicode rules when pattern matching.  On ASCII platforms,
+this means that the code points between 128 and 255 take on their
+Latin\-1 (ISO\-8859\-1) meanings (which are the same as Unicode's).
+(Otherwise Perl considers their meanings to be undefined.)  Thus,
+under this modifier, the ASCII platform effectively becomes a Unicode
+platform; and hence, for example, \f(CW\*(C`\ew\*(C'\fR will match any of the more than
+100_000 word characters in Unicode.
+.PP
+Unlike most locales, which are specific to a language and country pair,
+Unicode classifies all the characters that are letters \fIsomewhere\fR in
+the world as
+\&\f(CW\*(C`\ew\*(C'\fR.  For example, your locale might not think that \f(CW\*(C`LATIN SMALL
+LETTER ETH\*(C'\fR is a letter (unless you happen to speak Icelandic), but
+Unicode does.  Similarly, all the characters that are decimal digits
+somewhere in the world will match \f(CW\*(C`\ed\*(C'\fR; this is hundreds, not 10,
+possible matches.  And some of those digits look like some of the 10
+ASCII digits, but mean a different number, so a human could easily think
+a number is a different quantity than it really is.  For example,
+\&\f(CW\*(C`BENGALI DIGIT FOUR\*(C'\fR (U+09EA) looks very much like an
+\&\f(CW\*(C`ASCII DIGIT EIGHT\*(C'\fR (U+0038), and \f(CW\*(C`LEPCHA DIGIT SIX\*(C'\fR (U+1C46) looks
+very much like an \f(CW\*(C`ASCII DIGIT FIVE\*(C'\fR (U+0035).  And, \f(CW\*(C`\ed+\*(C'\fR, may match
+strings of digits that are a mixture from different writing systems,
+creating a security issue.  A fraudulent website, for example, could
+display the price of something using U+1C46, and it would appear to the
+user that something cost 500 units, but it really costs 600.  A browser
+that enforced script runs ("Script Runs") would prevent that
+fraudulent display.  "\fBnum()\fR" in Unicode::UCD can also be used to sort this
+out.  Or the \f(CW\*(C`/a\*(C'\fR modifier can be used to force \f(CW\*(C`\ed\*(C'\fR to match just the
+ASCII 0 through 9.
+.PP
+Also, under this modifier, case-insensitive matching works on the full
+set of Unicode
+characters.  The \f(CW\*(C`KELVIN SIGN\*(C'\fR, for example matches the letters "k" and
+"K"; and \f(CW\*(C`LATIN SMALL LIGATURE FF\*(C'\fR matches the sequence "ff", which,
+if you're not prepared, might make it look like a hexadecimal constant,
+presenting another potential security issue.  See
+<https://unicode.org/reports/tr36> for a detailed discussion of Unicode
+security issues.
+.PP
+This modifier may be specified to be the default by \f(CW\*(C`use feature
+\&\*(Aqunicode_strings\*(C'\fR, \f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR, or
+\&\f(CW\*(C`use v5.12\*(C'\fR (or higher),
+but see "Which character set modifier is in effect?".
+.IX Xref " u"
+.PP
+/d
+.IX Subsection "/d"
+.PP
+\&\fBIMPORTANT:\fR Because of the unpredictable behaviors this
+modifier causes, only use it to maintain weird backward compatibilities.
+Use the
+\&\f(CW\*(C`unicode_strings\*(C'\fR
+feature
+in new code to avoid inadvertently enabling this modifier by default.
+.PP
+What does this modifier do? It "Depends"!
+.PP
+This modifier means to use platform-native matching rules
+except when there is cause to use Unicode rules instead, as follows:
+.IP 1. 4
+the target string's UTF8 flag
+(see below) is set; or
+.IP 2. 4
+the pattern's UTF8 flag
+(see below) is set; or
+.IP 3. 4
+the pattern explicitly mentions a code point that is above 255 (say by
+\&\f(CW\*(C`\ex{100}\*(C'\fR); or
+.IP 4. 4
+the pattern uses a Unicode name (\f(CW\*(C`\eN{...}\*(C'\fR);  or
+.IP 5. 4
+the pattern uses a Unicode property (\f(CW\*(C`\ep{...}\*(C'\fR or \f(CW\*(C`\eP{...}\*(C'\fR); or
+.IP 6. 4
+the pattern uses a Unicode break (\f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR); or
+.IP 7. 4
+the pattern uses \f(CW"(?[ ])"\fR
+.IP 8. 4
+the pattern uses \f(CW\*(C`(*script_run: ...)\*(C'\fR
+.PP
+Regarding the "UTF8 flag" references above: normally Perl applications
+shouldn't think about that flag. It's part of Perl's internals,
+so it can change whenever Perl wants. \f(CW\*(C`/d\*(C'\fR may thus cause unpredictable
+results. See "The "Unicode Bug"" in perlunicode. This bug
+has become rather infamous, leading to yet other (without swearing) names
+for this modifier like "Dicey" and "Dodgy".
+.PP
+Here are some examples of how that works on an ASCII platform:
+.PP
+.Vb 3
+\& $str =  "\exDF";        #
+\& utf8::downgrade($str); # $str is not UTF8\-flagged.
+\& $str =~ /^\ew/;         # No match, since no UTF8 flag.
+\&
+\& $str .= "\ex{0e0b}";    # Now $str is UTF8\-flagged.
+\& $str =~ /^\ew/;         # Match! $str is now UTF8\-flagged.
+\& chop $str;
+\& $str =~ /^\ew/;         # Still a match! $str retains its UTF8 flag.
+.Ve
+.PP
+Under Perl's default configuration this modifier is automatically
+selected by default when none of the others are, so yet another name
+for it (unfortunately) is "Default".
+.PP
+Whenever you can, use the
+\&\f(CW\*(C`unicode_strings\*(C'\fR
+to cause  to be the default instead.
+.IX Xref " u"
+.PP
+/a (and /aa)
+.IX Subsection "/a (and /aa)"
+.PP
+This modifier stands for ASCII-restrict (or ASCII-safe).  This modifier
+may be doubled-up to increase its effect.
+.PP
+When it appears singly, it causes the sequences \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, and
+the Posix character classes to match only in the ASCII range.  They thus
+revert to their pre\-5.6, pre-Unicode meanings.  Under \f(CW\*(C`/a\*(C'\fR,  \f(CW\*(C`\ed\*(C'\fR
+always means precisely the digits \f(CW"0"\fR to \f(CW"9"\fR; \f(CW\*(C`\es\*(C'\fR means the five
+characters \f(CW\*(C`[ \ef\en\er\et]\*(C'\fR, and starting in Perl v5.18, the vertical tab;
+\&\f(CW\*(C`\ew\*(C'\fR means the 63 characters
+\&\f(CW\*(C`[A\-Za\-z0\-9_]\*(C'\fR; and likewise, all the Posix classes such as
+\&\f(CW\*(C`[[:print:]]\*(C'\fR match only the appropriate ASCII-range characters.
+.PP
+This modifier is useful for people who only incidentally use Unicode,
+and who do not wish to be burdened with its complexities and security
+concerns.
+.PP
+With \f(CW\*(C`/a\*(C'\fR, one can write \f(CW\*(C`\ed\*(C'\fR with confidence that it will only match
+ASCII characters, and should the need arise to match beyond ASCII, you
+can instead use \f(CW\*(C`\ep{Digit}\*(C'\fR (or \f(CW\*(C`\ep{Word}\*(C'\fR for \f(CW\*(C`\ew\*(C'\fR).  There are
+similar \f(CW\*(C`\ep{...}\*(C'\fR constructs that can match beyond ASCII both white
+space (see "Whitespace" in perlrecharclass), and Posix classes (see
+"POSIX Character Classes" in perlrecharclass).  Thus, this modifier
+doesn't mean you can't use Unicode, it means that to get Unicode
+matching you must explicitly use a construct (\f(CW\*(C`\ep{}\*(C'\fR, \f(CW\*(C`\eP{}\*(C'\fR) that
+signals Unicode.
+.PP
+As you would expect, this modifier causes, for example, \f(CW\*(C`\eD\*(C'\fR to mean
+the same thing as \f(CW\*(C`[^0\-9]\*(C'\fR; in fact, all non-ASCII characters match
+\&\f(CW\*(C`\eD\*(C'\fR, \f(CW\*(C`\eS\*(C'\fR, and \f(CW\*(C`\eW\*(C'\fR.  \f(CW\*(C`\eb\*(C'\fR still means to match at the boundary
+between \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eW\*(C'\fR, using the \f(CW\*(C`/a\*(C'\fR definitions of them (similarly
+for \f(CW\*(C`\eB\*(C'\fR).
+.PP
+Otherwise, \f(CW\*(C`/a\*(C'\fR behaves like the \f(CW\*(C`/u\*(C'\fR modifier, in that
+case-insensitive matching uses Unicode rules; for example, "k" will
+match the Unicode \f(CW\*(C`\eN{KELVIN SIGN}\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching, and code
+points in the Latin1 range, above ASCII will have Unicode rules when it
+comes to case-insensitive matching.
+.PP
+To forbid ASCII/non\-ASCII matches (like "k" with \f(CW\*(C`\eN{KELVIN SIGN}\*(C'\fR),
+specify the \f(CW"a"\fR twice, for example \f(CW\*(C`/aai\*(C'\fR or \f(CW\*(C`/aia\*(C'\fR.  (The first
+occurrence of \f(CW"a"\fR restricts the \f(CW\*(C`\ed\*(C'\fR, \fIetc\fR., and the second occurrence
+adds the \f(CW\*(C`/i\*(C'\fR restrictions.)  But, note that code points outside the
+ASCII range will use Unicode rules for \f(CW\*(C`/i\*(C'\fR matching, so the modifier
+doesn't really restrict things to just ASCII; it just forbids the
+intermixing of ASCII and non-ASCII.
+.PP
+To summarize, this modifier provides protection for applications that
+don't wish to be exposed to all of Unicode.  Specifying it twice
+gives added protection.
+.PP
+This modifier may be specified to be the default by \f(CW\*(C`use re \*(Aq/a\*(Aq\*(C'\fR
+or \f(CW\*(C`use re \*(Aq/aa\*(Aq\*(C'\fR.  If you do so, you may actually have occasion to use
+the \f(CW\*(C`/u\*(C'\fR modifier explicitly if there are a few regular expressions
+where you do want full Unicode rules (but even here, it's best if
+everything were under feature \f(CW"unicode_strings"\fR, along with the
+\&\f(CW\*(C`use re \*(Aq/aa\*(Aq\*(C'\fR).  Also see "Which character set modifier is in
+effect?".
+.IX Xref " a aa"
+.PP
+Which character set modifier is in effect?
+.IX Subsection "Which character set modifier is in effect?"
+.PP
+Which of these modifiers is in effect at any given point in a regular
+expression depends on a fairly complex set of interactions.  These have
+been designed so that in general you don't have to worry about it, but
+this section gives the gory details.  As
+explained below in "Extended Patterns" it is possible to explicitly
+specify modifiers that apply only to portions of a regular expression.
+The innermost always has priority over any outer ones, and one applying
+to the whole expression has priority over any of the default settings that are
+described in the remainder of this section.
+.PP
+The \f(CW\*(C`use re \*(Aq/foo\*(Aq\*(C'\fR pragma can be used to set
+default modifiers (including these) for regular expressions compiled
+within its scope.  This pragma has precedence over the other pragmas
+listed below that also change the defaults.
+.PP
+Otherwise, \f(CW\*(C`use locale\*(C'\fR sets the default modifier to \f(CW\*(C`/l\*(C'\fR;
+and \f(CW\*(C`use feature \*(Aqunicode_strings\*(C'\fR, or
+\&\f(CW\*(C`use v5.12\*(C'\fR (or higher) set the default to
+\&\f(CW\*(C`/u\*(C'\fR when not in the same scope as either \f(CW\*(C`use locale\*(C'\fR
+or \f(CW\*(C`use bytes\*(C'\fR.
+(\f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR also
+sets the default to \f(CW\*(C`/u\*(C'\fR, overriding any plain \f(CW\*(C`use locale\*(C'\fR.)
+Unlike the mechanisms mentioned above, these
+affect operations besides regular expressions pattern matching, and so
+give more consistent results with other operators, including using
+\&\f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \fIetc\fR. in substitution replacements.
+.PP
+If none of the above apply, for backwards compatibility reasons, the
+\&\f(CW\*(C`/d\*(C'\fR modifier is the one in effect by default.  As this can lead to
+unexpected results, it is best to specify which other rule set should be
+used.
+.PP
+Character set modifier behavior prior to Perl 5.14
+.IX Subsection "Character set modifier behavior prior to Perl 5.14"
+.PP
+Prior to 5.14, there were no explicit modifiers, but \f(CW\*(C`/l\*(C'\fR was implied
+for regexes compiled within the scope of \f(CW\*(C`use locale\*(C'\fR, and \f(CW\*(C`/d\*(C'\fR was
+implied otherwise.  However, interpolating a regex into a larger regex
+would ignore the original compilation in favor of whatever was in effect
+at the time of the second compilation.  There were a number of
+inconsistencies (bugs) with the \f(CW\*(C`/d\*(C'\fR modifier, where Unicode rules
+would be used when inappropriate, and vice versa.  \f(CW\*(C`\ep{}\*(C'\fR did not imply
+Unicode rules, and neither did all occurrences of \f(CW\*(C`\eN{}\*(C'\fR, until 5.12.
+.SS "Regular Expressions"
+.IX Subsection "Regular Expressions"
+\fIQuantifiers\fR
+.IX Subsection "Quantifiers"
+.PP
+Quantifiers are used when a particular portion of a pattern needs to
+match a certain number (or numbers) of times.  If there isn't a
+quantifier the number of times to match is exactly one.  The following
+standard quantifiers are recognized:
+.IX Xref "metacharacter quantifier * + ? {n} {n,} {n,m}"
+.PP
+.Vb 7
+\&    *           Match 0 or more times
+\&    +           Match 1 or more times
+\&    ?           Match 1 or 0 times
+\&    {n}         Match exactly n times
+\&    {n,}        Match at least n times
+\&    {,n}        Match at most n times
+\&    {n,m}       Match at least n but not more than m times
+.Ve
+.PP
+(If a non-escaped curly bracket occurs in a context other than one of
+the quantifiers listed above, where it does not form part of a
+backslashed sequence like \f(CW\*(C`\ex{...}\*(C'\fR, it is either a fatal syntax error,
+or treated as a regular character, generally with a deprecation warning
+raised.  To escape it, you can precede it with a backslash (\f(CW"\e{"\fR) or
+enclose it within square brackets  (\f(CW"[{]"\fR).
+This change will allow for future syntax extensions (like making the
+lower bound of a quantifier optional), and better error checking of
+quantifiers).
+.PP
+The \f(CW"*"\fR quantifier is equivalent to \f(CW\*(C`{0,}\*(C'\fR, the \f(CW"+"\fR
+quantifier to \f(CW\*(C`{1,}\*(C'\fR, and the \f(CW"?"\fR quantifier to \f(CW\*(C`{0,1}\*(C'\fR.  \fIn\fR and \fIm\fR are limited
+to non-negative integral values less than a preset limit defined when perl is built.
+This is usually 65534 on the most common platforms.  The actual limit can
+be seen in the error message generated by code such as this:
+.PP
+.Vb 1
+\&    $_ **= $_ , / {$_} / for 2 .. 42;
+.Ve
+.PP
+By default, a quantified subpattern is "greedy", that is, it will match as
+many times as possible (given a particular starting location) while still
+allowing the rest of the pattern to match.  If you want it to match the
+minimum number of times possible, follow the quantifier with a \f(CW"?"\fR.  Note
+that the meanings don't change, just the "greediness":
+.IX Xref "metacharacter greedy greediness ? *? +? ?? {n}? {n,}? {,n}? {n,m}?"
+.PP
+.Vb 7
+\&    *?        Match 0 or more times, not greedily
+\&    +?        Match 1 or more times, not greedily
+\&    ??        Match 0 or 1 time, not greedily
+\&    {n}?      Match exactly n times, not greedily (redundant)
+\&    {n,}?     Match at least n times, not greedily
+\&    {,n}?     Match at most n times, not greedily
+\&    {n,m}?    Match at least n but not more than m times, not greedily
+.Ve
+.PP
+Normally when a quantified subpattern does not allow the rest of the
+overall pattern to match, Perl will backtrack. However, this behaviour is
+sometimes undesirable. Thus Perl provides the "possessive" quantifier form
+as well.
+.PP
+.Vb 7
+\& *+     Match 0 or more times and give nothing back
+\& ++     Match 1 or more times and give nothing back
+\& ?+     Match 0 or 1 time and give nothing back
+\& {n}+   Match exactly n times and give nothing back (redundant)
+\& {n,}+  Match at least n times and give nothing back
+\& {,n}+  Match at most n times and give nothing back
+\& {n,m}+ Match at least n but not more than m times and give nothing back
+.Ve
+.PP
+For instance,
+.PP
+.Vb 1
+\&   \*(Aqaaaa\*(Aq =~ /a++a/
+.Ve
+.PP
+will never match, as the \f(CW\*(C`a++\*(C'\fR will gobble up all the \f(CW"a"\fR's in the
+string and won't leave any for the remaining part of the pattern. This
+feature can be extremely useful to give perl hints about where it
+shouldn't backtrack. For instance, the typical "match a double-quoted
+string" problem can be most efficiently performed when written as:
+.PP
+.Vb 1
+\&   /"(?:[^"\e\e]++|\e\e.)*+"/
+.Ve
+.PP
+as we know that if the final quote does not match, backtracking will not
+help. See the independent subexpression
+\&\f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR for more details;
+possessive quantifiers are just syntactic sugar for that construct. For
+instance the above example could also be written as follows:
+.PP
+.Vb 1
+\&   /"(?>(?:(?>[^"\e\e]+)|\e\e.)*)"/
+.Ve
+.PP
+Note that the possessive quantifier modifier can not be combined
+with the non-greedy modifier. This is because it would make no sense.
+Consider the follow equivalency table:
+.PP
+.Vb 5
+\&    Illegal         Legal
+\&    \-\-\-\-\-\-\-\-\-\-\-\-    \-\-\-\-\-\-
+\&    X??+            X{0}
+\&    X+?+            X{1}
+\&    X{min,max}?+    X{min}
+.Ve
+.PP
+\fIEscape sequences\fR
+.IX Subsection "Escape sequences"
+.PP
+Because patterns are processed as double-quoted strings, the following
+also work:
+.PP
+.Vb 10
+\& \et          tab                   (HT, TAB)
+\& \en          newline               (LF, NL)
+\& \er          return                (CR)
+\& \ef          form feed             (FF)
+\& \ea          alarm (bell)          (BEL)
+\& \ee          escape (think troff)  (ESC)
+\& \ecK         control char          (example: VT)
+\& \ex{}, \ex00  character whose ordinal is the given hexadecimal number
+\& \eN{name}    named Unicode character or character sequence
+\& \eN{U+263D}  Unicode character     (example: FIRST QUARTER MOON)
+\& \eo{}, \e000  character whose ordinal is the given octal number
+\& \el          lowercase next char (think vi)
+\& \eu          uppercase next char (think vi)
+\& \eL          lowercase until \eE (think vi)
+\& \eU          uppercase until \eE (think vi)
+\& \eQ          quote (disable) pattern metacharacters until \eE
+\& \eE          end either case modification or quoted section, think vi
+.Ve
+.PP
+Details are in "Quote and Quote-like Operators" in perlop.
+.PP
+\fICharacter Classes and other Special Escapes\fR
+.IX Subsection "Character Classes and other Special Escapes"
+.PP
+In addition, Perl defines the following:
+.IX Xref "\\g \\k \\K backreference"
+.PP
+.Vb 10
+\& Sequence   Note    Description
+\&  [...]     [1]  Match a character according to the rules of the
+\&                   bracketed character class defined by the "...".
+\&                   Example: [a\-z] matches "a" or "b" or "c" ... or "z"
+\&  [[:...:]] [2]  Match a character according to the rules of the POSIX
+\&                   character class "..." within the outer bracketed
+\&                   character class.  Example: [[:upper:]] matches any
+\&                   uppercase character.
+\&  (?[...])  [8]  Extended bracketed character class
+\&  \ew        [3]  Match a "word" character (alphanumeric plus "_", plus
+\&                   other connector punctuation chars plus Unicode
+\&                   marks)
+\&  \eW        [3]  Match a non\-"word" character
+\&  \es        [3]  Match a whitespace character
+\&  \eS        [3]  Match a non\-whitespace character
+\&  \ed        [3]  Match a decimal digit character
+\&  \eD        [3]  Match a non\-digit character
+\&  \epP       [3]  Match P, named property.  Use \ep{Prop} for longer names
+\&  \ePP       [3]  Match non\-P
+\&  \eX        [4]  Match Unicode "eXtended grapheme cluster"
+\&  \e1        [5]  Backreference to a specific capture group or buffer.
+\&                   \*(Aq1\*(Aq may actually be any positive integer.
+\&  \eg1       [5]  Backreference to a specific or previous group,
+\&  \eg{\-1}    [5]  The number may be negative indicating a relative
+\&                   previous group and may optionally be wrapped in
+\&                   curly brackets for safer parsing.
+\&  \eg{name}  [5]  Named backreference
+\&  \ek<name>  [5]  Named backreference
+\&  \ek\*(Aqname\*(Aq  [5]  Named backreference
+\&  \ek{name}  [5]  Named backreference
+\&  \eK        [6]  Keep the stuff left of the \eK, don\*(Aqt include it in $&
+\&  \eN        [7]  Any character but \en.  Not affected by /s modifier
+\&  \ev        [3]  Vertical whitespace
+\&  \eV        [3]  Not vertical whitespace
+\&  \eh        [3]  Horizontal whitespace
+\&  \eH        [3]  Not horizontal whitespace
+\&  \eR        [4]  Linebreak
+.Ve
+.IP [1] 4
+.IX Item "[1]"
+See "Bracketed Character Classes" in perlrecharclass for details.
+.IP [2] 4
+.IX Item "[2]"
+See "POSIX Character Classes" in perlrecharclass for details.
+.IP [3] 4
+.IX Item "[3]"
+See "Unicode Character Properties" in perlunicode for details
+.IP [4] 4
+.IX Item "[4]"
+See "Misc" in perlrebackslash for details.
+.IP [5] 4
+.IX Item "[5]"
+See "Capture groups" below for details.
+.IP [6] 4
+.IX Item "[6]"
+See "Extended Patterns" below for details.
+.IP [7] 4
+.IX Item "[7]"
+Note that \f(CW\*(C`\eN\*(C'\fR has two meanings.  When of the form \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR, it
+matches the character or character sequence whose name is \fINAME\fR; and
+similarly
+when of the form \f(CW\*(C`\eN{U+\fR\f(CIhex\fR\f(CW}\*(C'\fR, it matches the character whose Unicode
+code point is \fIhex\fR.  Otherwise it matches any character but \f(CW\*(C`\en\*(C'\fR.
+.IP [8] 4
+.IX Item "[8]"
+See "Extended Bracketed Character Classes" in perlrecharclass for details.
+.PP
+\fIAssertions\fR
+.IX Subsection "Assertions"
+.PP
+Besides \f(CW"^"\fR and \f(CW"$"\fR, Perl defines the following
+zero-width assertions:
+.IX Xref "zero-width assertion assertion regex, zero-width assertion regexp, zero-width assertion regular expression, zero-width assertion \\b \\B \\A \\Z \\z \\G"
+.PP
+.Vb 9
+\& \eb{}   Match at Unicode boundary of specified type
+\& \eB{}   Match where corresponding \eb{} doesn\*(Aqt match
+\& \eb     Match a \ew\eW or \eW\ew boundary
+\& \eB     Match except at a \ew\eW or \eW\ew boundary
+\& \eA     Match only at beginning of string
+\& \eZ     Match only at end of string, or before newline at the end
+\& \ez     Match only at end of string
+\& \eG     Match only at pos() (e.g. at the end\-of\-match position
+\&        of prior m//g)
+.Ve
+.PP
+A Unicode boundary (\f(CW\*(C`\eb{}\*(C'\fR), available starting in v5.22, is a spot
+between two characters, or before the first character in the string, or
+after the final character in the string where certain criteria defined
+by Unicode are met.  See "\eb{}, \eb, \eB{}, \eB" in perlrebackslash for
+details.
+.PP
+A word boundary (\f(CW\*(C`\eb\*(C'\fR) is a spot between two characters
+that has a \f(CW\*(C`\ew\*(C'\fR on one side of it and a \f(CW\*(C`\eW\*(C'\fR on the other side
+of it (in either order), counting the imaginary characters off the
+beginning and end of the string as matching a \f(CW\*(C`\eW\*(C'\fR.  (Within
+character classes \f(CW\*(C`\eb\*(C'\fR represents backspace rather than a word
+boundary, just as it normally does in any double-quoted string.)
+The \f(CW\*(C`\eA\*(C'\fR and \f(CW\*(C`\eZ\*(C'\fR are just like \f(CW"^"\fR and \f(CW"$"\fR, except that they
+won't match multiple times when the \f(CW\*(C`/m\*(C'\fR modifier is used, while
+\&\f(CW"^"\fR and \f(CW"$"\fR will match at every internal line boundary.  To match
+the actual end of the string and not ignore an optional trailing
+newline, use \f(CW\*(C`\ez\*(C'\fR.
+.IX Xref "\\b \\A \\Z \\z m"
+.PP
+The \f(CW\*(C`\eG\*(C'\fR assertion can be used to chain global matches (using
+\&\f(CW\*(C`m//g\*(C'\fR), as described in "Regexp Quote-Like Operators" in perlop.
+It is also useful when writing \f(CW\*(C`lex\*(C'\fR\-like scanners, when you have
+several patterns that you want to match against consequent substrings
+of your string; see the previous reference.  The actual location
+where \f(CW\*(C`\eG\*(C'\fR will match can also be influenced by using \f(CWpos()\fR as
+an lvalue: see "pos" in perlfunc. Note that the rule for zero-length
+matches (see "Repeated Patterns Matching a Zero-length Substring")
+is modified somewhat, in that contents to the left of \f(CW\*(C`\eG\*(C'\fR are
+not counted when determining the length of the match. Thus the following
+will not match forever:
+.IX Xref "\\G"
+.PP
+.Vb 5
+\&     my $string = \*(AqABC\*(Aq;
+\&     pos($string) = 1;
+\&     while ($string =~ /(.\eG)/g) {
+\&         print $1;
+\&     }
+.Ve
+.PP
+It will print 'A' and then terminate, as it considers the match to
+be zero-width, and thus will not match at the same position twice in a
+row.
+.PP
+It is worth noting that \f(CW\*(C`\eG\*(C'\fR improperly used can result in an infinite
+loop. Take care when using patterns that include \f(CW\*(C`\eG\*(C'\fR in an alternation.
+.PP
+Note also that \f(CW\*(C`s///\*(C'\fR will refuse to overwrite part of a substitution
+that has already been replaced; so for example this will stop after the
+first iteration, rather than iterating its way backwards through the
+string:
+.PP
+.Vb 4
+\&    $_ = "123456789";
+\&    pos = 6;
+\&    s/.(?=.\eG)/X/g;
+\&    print;      # prints 1234X6789, not XXXXX6789
+.Ve
+.PP
+\fICapture groups\fR
+.IX Subsection "Capture groups"
+.PP
+The grouping construct \f(CW\*(C`( ... )\*(C'\fR creates capture groups (also referred to as
+capture buffers). To refer to the current contents of a group later on, within
+the same pattern, use \f(CW\*(C`\eg1\*(C'\fR (or \f(CW\*(C`\eg{1}\*(C'\fR) for the first, \f(CW\*(C`\eg2\*(C'\fR (or \f(CW\*(C`\eg{2}\*(C'\fR)
+for the second, and so on.
+This is called a \fIbackreference\fR.
+ 
+ 
+ 
+ 
+    
+ 
+ 
+  
+There is no limit to the number of captured substrings that you may use.
+Groups are numbered with the leftmost open parenthesis being number 1, \fIetc\fR.  If
+a group did not match, the associated backreference won't match either. (This
+can happen if the group is optional, or in a different branch of an
+alternation.)
+You can omit the \f(CW"g"\fR, and write \f(CW"\e1"\fR, \fIetc\fR, but there are some issues with
+this form, described below.
+.IX Xref "regex, capture buffer regexp, capture buffer regex, capture group regexp, capture group regular expression, capture buffer backreference regular expression, capture group backreference \\g{1} \\g{-1} \\g{name} relative backreference named backreference named capture buffer regular expression, named capture buffer named capture group regular expression, named capture group %+ $+{name} \\k<name>"
+.PP
+You can also refer to capture groups relatively, by using a negative number, so
+that \f(CW\*(C`\eg\-1\*(C'\fR and \f(CW\*(C`\eg{\-1}\*(C'\fR both refer to the immediately preceding capture
+group, and \f(CW\*(C`\eg\-2\*(C'\fR and \f(CW\*(C`\eg{\-2}\*(C'\fR both refer to the group before it.  For
+example:
+.PP
+.Vb 8
+\&        /
+\&         (Y)            # group 1
+\&         (              # group 2
+\&            (X)         # group 3
+\&            \eg{\-1}      # backref to group 3
+\&            \eg{\-3}      # backref to group 1
+\&         )
+\&        /x
+.Ve
+.PP
+would match the same as \f(CW\*(C`/(Y) ( (X) \eg3 \eg1 )/x\*(C'\fR.  This allows you to
+interpolate regexes into larger regexes and not have to worry about the
+capture groups being renumbered.
+.PP
+You can dispense with numbers altogether and create named capture groups.
+The notation is \f(CW\*(C`(?<\fR\f(CIname\fR\f(CW>...)\*(C'\fR to declare and \f(CW\*(C`\eg{\fR\f(CIname\fR\f(CW}\*(C'\fR to
+reference.  (To be compatible with .Net regular expressions, \f(CW\*(C`\eg{\fR\f(CIname\fR\f(CW}\*(C'\fR may
+also be written as \f(CW\*(C`\ek{\fR\f(CIname\fR\f(CW}\*(C'\fR, \f(CW\*(C`\ek<\fR\f(CIname\fR\f(CW>\*(C'\fR or \f(CW\*(C`\ek\*(Aq\fR\f(CIname\fR\f(CW\*(Aq\*(C'\fR.)
+\&\fIname\fR must not begin with a number, nor contain hyphens.
+When different groups within the same pattern have the same name, any reference
+to that name assumes the leftmost defined group.  Named groups count in
+absolute and relative numbering, and so can also be referred to by those
+numbers.
+(It's possible to do things with named capture groups that would otherwise
+require \f(CW\*(C`(??{})\*(C'\fR.)
+.PP
+Capture group contents are dynamically scoped and available to you outside the
+pattern until the end of the enclosing block or until the next successful
+match in the same scope, whichever comes first.
+See "Compound Statements" in perlsyn and
+"Scoping Rules of Regex Variables" in perlvar for more details.
+.PP
+You can access the contents of a capture group by absolute number (using
+\&\f(CW"$1"\fR instead of \f(CW"\eg1"\fR, \fIetc\fR); or by name via the \f(CW\*(C`%+\*(C'\fR hash,
+using \f(CW"$+{\fR\f(CIname\fR\f(CW}"\fR.
+.PP
+Braces are required in referring to named capture groups, but are optional for
+absolute or relative numbered ones.  Braces are safer when creating a regex by
+concatenating smaller strings.  For example if you have \f(CW\*(C`qr/$a$b/\*(C'\fR, and \f(CW$a\fR
+contained \f(CW"\eg1"\fR, and \f(CW$b\fR contained \f(CW"37"\fR, you would get \f(CW\*(C`/\eg137/\*(C'\fR which
+is probably not what you intended.
+.PP
+If you use braces, you may also optionally add any number of blank
+(space or tab) characters within but adjacent to the braces, like
+\&\f(CW\*(C`\eg{\ \-1\ }\*(C'\fR, or \f(CW\*(C`\ek{\ \fR\f(CIname\fR\f(CW\ }\*(C'\fR.
+.PP
+The \f(CW\*(C`\eg\*(C'\fR and \f(CW\*(C`\ek\*(C'\fR notations were introduced in Perl 5.10.0.  Prior to that
+there were no named nor relative numbered capture groups.  Absolute numbered
+groups were referred to using \f(CW\*(C`\e1\*(C'\fR,
+\&\f(CW\*(C`\e2\*(C'\fR, \fIetc\fR., and this notation is still
+accepted (and likely always will be).  But it leads to some ambiguities if
+there are more than 9 capture groups, as \f(CW\*(C`\e10\*(C'\fR could mean either the tenth
+capture group, or the character whose ordinal in octal is 010 (a backspace in
+ASCII).  Perl resolves this ambiguity by interpreting \f(CW\*(C`\e10\*(C'\fR as a backreference
+only if at least 10 left parentheses have opened before it.  Likewise \f(CW\*(C`\e11\*(C'\fR is
+a backreference only if at least 11 left parentheses have opened before it.
+And so on.  \f(CW\*(C`\e1\*(C'\fR through \f(CW\*(C`\e9\*(C'\fR are always interpreted as backreferences.
+There are several examples below that illustrate these perils.  You can avoid
+the ambiguity by always using \f(CW\*(C`\eg{}\*(C'\fR or \f(CW\*(C`\eg\*(C'\fR if you mean capturing groups;
+and for octal constants always using \f(CW\*(C`\eo{}\*(C'\fR, or for \f(CW\*(C`\e077\*(C'\fR and below, using 3
+digits padded with leading zeros, since a leading zero implies an octal
+constant.
+.PP
+The \f(CW\*(C`\e\fR\f(CIdigit\fR\f(CW\*(C'\fR notation also works in certain circumstances outside
+the pattern.  See "Warning on \e1 Instead of \f(CW$1\fR" below for details.
+.PP
+Examples:
+.PP
+.Vb 1
+\&    s/^([^ ]*) *([^ ]*)/$2 $1/;     # swap first two words
+\&
+\&    /(.)\eg1/                        # find first doubled char
+\&         and print "\*(Aq$1\*(Aq is the first doubled character\en";
+\&
+\&    /(?<char>.)\ek<char>/            # ... a different way
+\&         and print "\*(Aq$+{char}\*(Aq is the first doubled character\en";
+\&
+\&    /(?\*(Aqchar\*(Aq.)\eg1/                 # ... mix and match
+\&         and print "\*(Aq$1\*(Aq is the first doubled character\en";
+\&
+\&    if (/Time: (..):(..):(..)/) {   # parse out values
+\&        $hours = $1;
+\&        $minutes = $2;
+\&        $seconds = $3;
+\&    }
+\&
+\&    /(.)(.)(.)(.)(.)(.)(.)(.)(.)\eg10/   # \eg10 is a backreference
+\&    /(.)(.)(.)(.)(.)(.)(.)(.)(.)\e10/    # \e10 is octal
+\&    /((.)(.)(.)(.)(.)(.)(.)(.)(.))\e10/  # \e10 is a backreference
+\&    /((.)(.)(.)(.)(.)(.)(.)(.)(.))\e010/ # \e010 is octal
+\&
+\&    $a = \*(Aq(.)\e1\*(Aq;        # Creates problems when concatenated.
+\&    $b = \*(Aq(.)\eg{1}\*(Aq;     # Avoids the problems.
+\&    "aa" =~ /${a}/;      # True
+\&    "aa" =~ /${b}/;      # True
+\&    "aa0" =~ /${a}0/;    # False!
+\&    "aa0" =~ /${b}0/;    # True
+\&    "aa\ex08" =~ /${a}0/;  # True!
+\&    "aa\ex08" =~ /${b}0/;  # False
+.Ve
+.PP
+Several special variables also refer back to portions of the previous
+match.  \f(CW$+\fR returns whatever the last bracket match matched.
+\&\f(CW$&\fR returns the entire matched string.  (At one point \f(CW$0\fR did
+also, but now it returns the name of the program.)  \f(CW\*(C`$\`\*(C'\fR returns
+everything before the matched string.  \f(CW\*(C`$\*(Aq\*(C'\fR returns everything
+after the matched string. And \f(CW$^N\fR contains whatever was matched by
+the most-recently closed group (submatch). \f(CW$^N\fR can be used in
+extended patterns (see below), for example to assign a submatch to a
+variable.
+.IX Xref "$+ $^N $& $` $'"
+.PP
+These special variables, like the \f(CW\*(C`%+\*(C'\fR hash and the numbered match variables
+(\f(CW$1\fR, \f(CW$2\fR, \f(CW$3\fR, \fIetc\fR.) are dynamically scoped
+until the end of the enclosing block or until the next successful
+match, whichever comes first.  (See "Compound Statements" in perlsyn.)
+.IX Xref "$+ $^N $& $` $' $1 $2 $3 $4 $5 $6 $7 $8 $9 @{^CAPTURE}"
+.PP
+The \f(CW\*(C`@{^CAPTURE}\*(C'\fR array may be used to access ALL of the capture buffers
+as an array without needing to know how many there are. For instance
+.PP
+.Vb 1
+\&    $string=~/$pattern/ and @captured = @{^CAPTURE};
+.Ve
+.PP
+will place a copy of each capture variable, \f(CW$1\fR, \f(CW$2\fR etc, into the
+\&\f(CW@captured\fR array.
+.PP
+Be aware that when interpolating a subscript of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR
+array you must use demarcated curly brace notation:
+.PP
+.Vb 1
+\&    print "@{^CAPTURE[0]}";
+.Ve
+.PP
+See "Demarcated variable names using braces" in perldata for more on
+this notation.
+.PP
+\&\fBNOTE\fR: Failed matches in Perl do not reset the match variables,
+which makes it easier to write code that tests for a series of more
+specific cases and remembers the best match.
+.PP
+\&\fBWARNING\fR: If your code is to run on Perl 5.16 or earlier,
+beware that once Perl sees that you need one of \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR, or
+\&\f(CW\*(C`$\*(Aq\*(C'\fR anywhere in the program, it has to provide them for every
+pattern match.  This may substantially slow your program.
+.PP
+Perl uses the same mechanism to produce \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR, so you also
+pay a price for each pattern that contains capturing parentheses.
+(To avoid this cost while retaining the grouping behaviour, use the
+extended regular expression \f(CW\*(C`(?: ... )\*(C'\fR instead.)  But if you never
+use \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR or \f(CW\*(C`$\*(Aq\*(C'\fR, then patterns \fIwithout\fR capturing
+parentheses will not be penalized.  So avoid \f(CW$&\fR, \f(CW\*(C`$\*(Aq\*(C'\fR, and \f(CW\*(C`$\`\*(C'\fR
+if you can, but if you can't (and some algorithms really appreciate
+them), once you've used them once, use them at will, because you've
+already paid the price.
+.IX Xref "$& $` $'"
+.PP
+Perl 5.16 introduced a slightly more efficient mechanism that notes
+separately whether each of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR, and \f(CW\*(C`$\*(Aq\*(C'\fR have been seen, and
+thus may only need to copy part of the string.  Perl 5.20 introduced a
+much more efficient copy-on-write mechanism which eliminates any slowdown.
+.PP
+As another workaround for this problem, Perl 5.10.0 introduced \f(CW\*(C`${^PREMATCH}\*(C'\fR,
+\&\f(CW\*(C`${^MATCH}\*(C'\fR and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, which are equivalent to \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR
+and \f(CW\*(C`$\*(Aq\*(C'\fR, \fBexcept\fR that they are only guaranteed to be defined after a
+successful match that was executed with the \f(CW\*(C`/p\*(C'\fR (preserve) modifier.
+The use of these variables incurs no global performance penalty, unlike
+their punctuation character equivalents, however at the trade-off that you
+have to tell perl when you want to use them.  As of Perl 5.20, these three
+variables are equivalent to \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR and \f(CW\*(C`$\*(Aq\*(C'\fR, and \f(CW\*(C`/p\*(C'\fR is ignored.
+.IX Xref " p p modifier"
+.SS "Quoting metacharacters"
+.IX Subsection "Quoting metacharacters"
+Backslashed metacharacters in Perl are alphanumeric, such as \f(CW\*(C`\eb\*(C'\fR,
+\&\f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\en\*(C'\fR.  Unlike some other regular expression languages, there
+are no backslashed symbols that aren't alphanumeric.  So anything
+that looks like \f(CW\*(C`\e\e\*(C'\fR, \f(CW\*(C`\e(\*(C'\fR, \f(CW\*(C`\e)\*(C'\fR, \f(CW\*(C`\e[\*(C'\fR, \f(CW\*(C`\e]\*(C'\fR, \f(CW\*(C`\e{\*(C'\fR, or \f(CW\*(C`\e}\*(C'\fR is
+always
+interpreted as a literal character, not a metacharacter.  This was
+once used in a common idiom to disable or quote the special meanings
+of regular expression metacharacters in a string that you want to
+use for a pattern. Simply quote all non\-"word" characters:
+.PP
+.Vb 1
+\&    $pattern =~ s/(\eW)/\e\e$1/g;
+.Ve
+.PP
+(If \f(CW\*(C`use locale\*(C'\fR is set, then this depends on the current locale.)
+Today it is more common to use the \f(CWquotemeta()\fR
+function or the \f(CW\*(C`\eQ\*(C'\fR metaquoting escape sequence to disable all
+metacharacters' special meanings like this:
+.PP
+.Vb 1
+\&    /$unquoted\eQ$quoted\eE$unquoted/
+.Ve
+.PP
+Beware that if you put literal backslashes (those not inside
+interpolated variables) between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR, double-quotish
+backslash interpolation may lead to confusing results.  If you
+\&\fIneed\fR to use literal backslashes within \f(CW\*(C`\eQ...\eE\*(C'\fR,
+consult "Gory details of parsing quoted constructs" in perlop.
+.PP
+\&\f(CWquotemeta()\fR and \f(CW\*(C`\eQ\*(C'\fR are fully described in "quotemeta" in perlfunc.
+.SS "Extended Patterns"
+.IX Subsection "Extended Patterns"
+Perl also defines a consistent extension syntax for features not
+found in standard tools like \fBawk\fR and
+\&\fBlex\fR.  The syntax for most of these is a
+pair of parentheses with a question mark as the first thing within
+the parentheses.  The character after the question mark indicates
+the extension.
+.PP
+A question mark was chosen for this and for the minimal-matching
+construct because 1) question marks are rare in older regular
+expressions, and 2) whenever you see one, you should stop and
+"question" exactly what is going on.  That's psychology....
+.ie n .IP """(?#\fItext\fR)""" 4
+.el .IP \f(CW(?#\fR\f(CItext\fR\f(CW)\fR 4
+.IX Xref "(?#)"
+.IX Item "(?#text)"
+A comment.  The \fItext\fR is ignored.
+Note that Perl closes
+the comment as soon as it sees a \f(CW")"\fR, so there is no way to put a literal
+\&\f(CW")"\fR in the comment.  The pattern's closing delimiter must be escaped by
+a backslash if it appears in the comment.
+.Sp
+See "/x" for another way to have comments in patterns.
+.Sp
+Note that a comment can go just about anywhere, except in the middle of
+an escape sequence.   Examples:
+.Sp
+.Vb 1
+\& qr/foo(?#comment)bar/\*(Aq  # Matches \*(Aqfoobar\*(Aq
+\&
+\& # The pattern below matches \*(Aqabcd\*(Aq, \*(Aqabccd\*(Aq, or \*(Aqabcccd\*(Aq
+\& qr/abc(?#comment between literal and its quantifier){1,3}d/
+\&
+\& # The pattern below generates a syntax error, because the \*(Aq\ep\*(Aq must
+\& # be followed immediately by a \*(Aq{\*(Aq.
+\& qr/\ep(?#comment between \ep and its property name){Any}/
+\&
+\& # The pattern below generates a syntax error, because the initial
+\& # \*(Aq\e(\*(Aq is a literal opening parenthesis, and so there is nothing
+\& # for the  closing \*(Aq)\*(Aq to match
+\& qr/\e(?#the backslash means this isn\*(Aqt a comment)p{Any}/
+\&
+\& # Comments can be used to fold long patterns into multiple lines
+\& qr/First part of a long regex(?#
+\&   )remaining part/
+.Ve
+.ie n .IP """(?adlupimnsx\-imnsx)""" 4
+.el .IP \f(CW(?adlupimnsx\-imnsx)\fR 4
+.IX Item "(?adlupimnsx-imnsx)"
+.PD 0
+.ie n .IP """(?^alupimnsx)""" 4
+.el .IP \f(CW(?^alupimnsx)\fR 4
+.IX Xref "(?) (?^)"
+.IX Item "(?^alupimnsx)"
+.PD
+Zero or more embedded pattern-match modifiers, to be turned on (or
+turned off if preceded by \f(CW"\-"\fR) for the remainder of the pattern or
+the remainder of the enclosing pattern group (if any).
+.Sp
+This is particularly useful for dynamically-generated patterns,
+such as those read in from a
+configuration file, taken from an argument, or specified in a table
+somewhere.  Consider the case where some patterns want to be
+case-sensitive and some do not:  The case-insensitive ones merely need to
+include \f(CW\*(C`(?i)\*(C'\fR at the front of the pattern.  For example:
+.Sp
+.Vb 2
+\&    $pattern = "foobar";
+\&    if ( /$pattern/i ) { }
+\&
+\&    # more flexible:
+\&
+\&    $pattern = "(?i)foobar";
+\&    if ( /$pattern/ ) { }
+.Ve
+.Sp
+These modifiers are restored at the end of the enclosing group. For example,
+.Sp
+.Vb 1
+\&    ( (?i) blah ) \es+ \eg1
+.Ve
+.Sp
+will match \f(CW\*(C`blah\*(C'\fR in any case, some spaces, and an exact (\fIincluding the case\fR!)
+repetition of the previous word, assuming the \f(CW\*(C`/x\*(C'\fR modifier, and no \f(CW\*(C`/i\*(C'\fR
+modifier outside this group.
+.Sp
+These modifiers do not carry over into named subpatterns called in the
+enclosing group. In other words, a pattern such as \f(CW\*(C`((?i)(?&\fR\f(CINAME\fR\f(CW))\*(C'\fR does not
+change the case-sensitivity of the \fINAME\fR pattern.
+.Sp
+A modifier is overridden by later occurrences of this construct in the
+same scope containing the same modifier, so that
+.Sp
+.Vb 1
+\&    /((?im)foo(?\-m)bar)/
+.Ve
+.Sp
+matches all of \f(CW\*(C`foobar\*(C'\fR case insensitively, but uses \f(CW\*(C`/m\*(C'\fR rules for
+only the \f(CW\*(C`foo\*(C'\fR portion.  The \f(CW"a"\fR flag overrides \f(CW\*(C`aa\*(C'\fR as well;
+likewise \f(CW\*(C`aa\*(C'\fR overrides \f(CW"a"\fR.  The same goes for \f(CW"x"\fR and \f(CW\*(C`xx\*(C'\fR.
+Hence, in
+.Sp
+.Vb 1
+\&    /(?\-x)foo/xx
+.Ve
+.Sp
+both \f(CW\*(C`/x\*(C'\fR and \f(CW\*(C`/xx\*(C'\fR are turned off during matching \f(CW\*(C`foo\*(C'\fR.  And in
+.Sp
+.Vb 1
+\&    /(?x)foo/x
+.Ve
+.Sp
+\&\f(CW\*(C`/x\*(C'\fR but NOT \f(CW\*(C`/xx\*(C'\fR is turned on for matching \f(CW\*(C`foo\*(C'\fR.  (One might
+mistakenly think that since the inner \f(CW\*(C`(?x)\*(C'\fR is already in the scope of
+\&\f(CW\*(C`/x\*(C'\fR, that the result would effectively be the sum of them, yielding
+\&\f(CW\*(C`/xx\*(C'\fR.  It doesn't work that way.)  Similarly, doing something like
+\&\f(CW\*(C`(?xx\-x)foo\*(C'\fR turns off all \f(CW"x"\fR behavior for matching \f(CW\*(C`foo\*(C'\fR, it is not
+that you subtract 1 \f(CW"x"\fR from 2 to get 1 \f(CW"x"\fR remaining.
+.Sp
+Any of these modifiers can be set to apply globally to all regular
+expressions compiled within the scope of a \f(CW\*(C`use re\*(C'\fR.  See
+"'/flags' mode" in re.
+.Sp
+Starting in Perl 5.14, a \f(CW"^"\fR (caret or circumflex accent) immediately
+after the \f(CW"?"\fR is a shorthand equivalent to \f(CW\*(C`d\-imnsx\*(C'\fR.  Flags (except
+\&\f(CW"d"\fR) may follow the caret to override it.
+But a minus sign is not legal with it.
+.Sp
+Note that the \f(CW"a"\fR, \f(CW"d"\fR, \f(CW"l"\fR, \f(CW"p"\fR, and \f(CW"u"\fR modifiers are special in
+that they can only be enabled, not disabled, and the \f(CW"a"\fR, \f(CW"d"\fR, \f(CW"l"\fR, and
+\&\f(CW"u"\fR modifiers are mutually exclusive: specifying one de-specifies the
+others, and a maximum of one (or two \f(CW"a"\fR's) may appear in the
+construct.  Thus, for
+example, \f(CW\*(C`(?\-p)\*(C'\fR will warn when compiled under \f(CW\*(C`use warnings\*(C'\fR;
+\&\f(CW\*(C`(?\-d:...)\*(C'\fR and \f(CW\*(C`(?dl:...)\*(C'\fR are fatal errors.
+.Sp
+Note also that the \f(CW"p"\fR modifier is special in that its presence
+anywhere in a pattern has a global effect.
+.Sp
+Having zero modifiers makes this a no-op (so why did you specify it,
+unless it's generated code), and starting in v5.30, warns under \f(CW\*(C`use
+re \*(Aqstrict\*(Aq\*(C'\fR.
+.ie n .IP """(?:\fIpattern\fR)""" 4
+.el .IP \f(CW(?:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?:)"
+.IX Item "(?:pattern)"
+.PD 0
+.ie n .IP """(?adluimnsx\-imnsx:\fIpattern\fR)""" 4
+.el .IP \f(CW(?adluimnsx\-imnsx:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?adluimnsx-imnsx:pattern)"
+.ie n .IP """(?^aluimnsx:\fIpattern\fR)""" 4
+.el .IP \f(CW(?^aluimnsx:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?^:)"
+.IX Item "(?^aluimnsx:pattern)"
+.PD
+This is for clustering, not capturing; it groups subexpressions like
+\&\f(CW"()"\fR, but doesn't make backreferences as \f(CW"()"\fR does.  So
+.Sp
+.Vb 1
+\&    @fields = split(/\eb(?:a|b|c)\eb/)
+.Ve
+.Sp
+matches the same field delimiters as
+.Sp
+.Vb 1
+\&    @fields = split(/\eb(a|b|c)\eb/)
+.Ve
+.Sp
+but doesn't spit out the delimiters themselves as extra fields (even though
+that's the behaviour of "split" in perlfunc when its pattern contains capturing
+groups).  It's also cheaper not to capture
+characters if you don't need to.
+.Sp
+Any letters between \f(CW"?"\fR and \f(CW":"\fR act as flags modifiers as with
+\&\f(CW\*(C`(?adluimnsx\-imnsx)\*(C'\fR.  For example,
+.Sp
+.Vb 1
+\&    /(?s\-i:more.*than).*million/i
+.Ve
+.Sp
+is equivalent to the more verbose
+.Sp
+.Vb 1
+\&    /(?:(?s\-i)more.*than).*million/i
+.Ve
+.Sp
+Note that any \f(CW\*(C`()\*(C'\fR constructs enclosed within this one will still
+capture unless the \f(CW\*(C`/n\*(C'\fR modifier is in effect.
+.Sp
+Like the "(?adlupimnsx\-imnsx)" construct, \f(CW\*(C`aa\*(C'\fR and \f(CW"a"\fR override each
+other, as do \f(CW\*(C`xx\*(C'\fR and \f(CW"x"\fR.  They are not additive.  So, doing
+something like \f(CW\*(C`(?xx\-x:foo)\*(C'\fR turns off all \f(CW"x"\fR behavior for matching
+\&\f(CW\*(C`foo\*(C'\fR.
+.Sp
+Starting in Perl 5.14, a \f(CW"^"\fR (caret or circumflex accent) immediately
+after the \f(CW"?"\fR is a shorthand equivalent to \f(CW\*(C`d\-imnsx\*(C'\fR.  Any positive
+flags (except \f(CW"d"\fR) may follow the caret, so
+.Sp
+.Vb 1
+\&    (?^x:foo)
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 1
+\&    (?x\-imns:foo)
+.Ve
+.Sp
+The caret tells Perl that this cluster doesn't inherit the flags of any
+surrounding pattern, but uses the system defaults (\f(CW\*(C`d\-imnsx\*(C'\fR),
+modified by any flags specified.
+.Sp
+The caret allows for simpler stringification of compiled regular
+expressions.  These look like
+.Sp
+.Vb 1
+\&    (?^:pattern)
+.Ve
+.Sp
+with any non-default flags appearing between the caret and the colon.
+A test that looks at such stringification thus doesn't need to have the
+system default flags hard-coded in it, just the caret.  If new flags are
+added to Perl, the meaning of the caret's expansion will change to include
+the default for those flags, so the test will still work, unchanged.
+.Sp
+Specifying a negative flag after the caret is an error, as the flag is
+redundant.
+.Sp
+Mnemonic for \f(CW\*(C`(?^...)\*(C'\fR:  A fresh beginning since the usual use of a caret is
+to match at the beginning.
+.ie n .IP """(?|\fIpattern\fR)""" 4
+.el .IP \f(CW(?|\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?|) Branch reset"
+.IX Item "(?|pattern)"
+This is the "branch reset" pattern, which has the special property
+that the capture groups are numbered from the same starting point
+in each alternation branch. It is available starting from perl 5.10.0.
+.Sp
+Capture groups are numbered from left to right, but inside this
+construct the numbering is restarted for each branch.
+.Sp
+The numbering within each branch will be as normal, and any groups
+following this construct will be numbered as though the construct
+contained only one branch, that being the one with the most capture
+groups in it.
+.Sp
+This construct is useful when you want to capture one of a
+number of alternative matches.
+.Sp
+Consider the following pattern.  The numbers underneath show in
+which group the captured content will be stored.
+.Sp
+.Vb 3
+\&    # before  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-branch\-reset\-\-\-\-\-\-\-\-\-\-\- after
+\&    / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
+\&    # 1            2         2  3        2     3     4
+.Ve
+.Sp
+Be careful when using the branch reset pattern in combination with
+named captures. Named captures are implemented as being aliases to
+numbered groups holding the captures, and that interferes with the
+implementation of the branch reset pattern. If you are using named
+captures in a branch reset pattern, it's best to use the same names,
+in the same order, in each of the alternations:
+.Sp
+.Vb 2
+\&   /(?|  (?<a> x ) (?<b> y )
+\&      |  (?<a> z ) (?<b> w )) /x
+.Ve
+.Sp
+Not doing so may lead to surprises:
+.Sp
+.Vb 3
+\&  "12" =~ /(?| (?<a> \ed+ ) | (?<b> \eD+))/x;
+\&  say $+{a};    # Prints \*(Aq12\*(Aq
+\&  say $+{b};    # *Also* prints \*(Aq12\*(Aq.
+.Ve
+.Sp
+The problem here is that both the group named \f(CW\*(C`a\*(C'\fR and the group
+named \f(CW\*(C`b\*(C'\fR are aliases for the group belonging to \f(CW$1\fR.
+.IP "Lookaround Assertions" 4
+.IX Xref "look-around assertion lookaround assertion look-around lookaround"
+.IX Item "Lookaround Assertions"
+Lookaround assertions are zero-width patterns which match a specific
+pattern without including it in \f(CW$&\fR. Positive assertions match when
+their subpattern matches, negative assertions match when their subpattern
+fails. Lookbehind matches text up to the current match position,
+lookahead matches text following the current match position.
+.RS 4
+.ie n .IP """(?=\fIpattern\fR)""" 4
+.el .IP \f(CW(?=\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?=pattern)"
+.PD 0
+.ie n .IP """(*pla:\fIpattern\fR)""" 4
+.el .IP \f(CW(*pla:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(*pla:pattern)"
+.ie n .IP """(*positive_lookahead:\fIpattern\fR)""" 4
+.el .IP \f(CW(*positive_lookahead:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?=) (*pla (*positive_lookahead look-ahead, positive lookahead, positive"
+.IX Item "(*positive_lookahead:pattern)"
+.PD
+A zero-width positive lookahead assertion.  For example, \f(CW\*(C`/\ew+(?=\et)/\*(C'\fR
+matches a word followed by a tab, without including the tab in \f(CW$&\fR.
+.ie n .IP """(?!\fIpattern\fR)""" 4
+.el .IP \f(CW(?!\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?!pattern)"
+.PD 0
+.ie n .IP """(*nla:\fIpattern\fR)""" 4
+.el .IP \f(CW(*nla:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(*nla:pattern)"
+.ie n .IP """(*negative_lookahead:\fIpattern\fR)""" 4
+.el .IP \f(CW(*negative_lookahead:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?!) (*nla (*negative_lookahead look-ahead, negative lookahead, negative"
+.IX Item "(*negative_lookahead:pattern)"
+.PD
+A zero-width negative lookahead assertion.  For example \f(CW\*(C`/foo(?!bar)/\*(C'\fR
+matches any occurrence of "foo" that isn't followed by "bar".  Note
+however that lookahead and lookbehind are NOT the same thing.  You cannot
+use this for lookbehind.
+.Sp
+If you are looking for a "bar" that isn't preceded by a "foo", \f(CW\*(C`/(?!foo)bar/\*(C'\fR
+will not do what you want.  That's because the \f(CW\*(C`(?!foo)\*(C'\fR is just saying that
+the next thing cannot be "foo"\-\-and it's not, it's a "bar", so "foobar" will
+match.  Use lookbehind instead (see below).
+.ie n .IP """(?<=\fIpattern\fR)""" 4
+.el .IP \f(CW(?<=\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?<=pattern)"
+.PD 0
+.ie n .IP """\eK""" 4
+.el .IP \f(CW\eK\fR 4
+.IX Item "K"
+.ie n .IP """(*plb:\fIpattern\fR)""" 4
+.el .IP \f(CW(*plb:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(*plb:pattern)"
+.ie n .IP """(*positive_lookbehind:\fIpattern\fR)""" 4
+.el .IP \f(CW(*positive_lookbehind:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?<=) (*plb (*positive_lookbehind look-behind, positive lookbehind, positive \\K"
+.IX Item "(*positive_lookbehind:pattern)"
+.PD
+A zero-width positive lookbehind assertion.  For example, \f(CW\*(C`/(?<=\et)\ew+/\*(C'\fR
+matches a word that follows a tab, without including the tab in \f(CW$&\fR.
+.Sp
+Prior to Perl 5.30, it worked only for fixed-width lookbehind, but
+starting in that release, it can handle variable lengths from 1 to 255
+characters as an experimental feature.  The feature is enabled
+automatically if you use a variable length positive lookbehind assertion.
+.Sp
+In Perl 5.35.10 the scope of the experimental nature of this construct
+has been reduced, and experimental warnings will only be produced when
+the construct contains capturing parenthesis. The warnings will be
+raised at pattern compilation time, unless turned off, in the
+\&\f(CW\*(C`experimental::vlb\*(C'\fR category.  This is to warn you that the exact
+contents of capturing buffers in a variable length positive lookbehind
+is not well defined and is subject to change in a future release of perl.
+.Sp
+Currently if you use capture buffers inside of a positive variable length
+lookbehind the result will be the longest and thus leftmost match possible.
+This means that
+.Sp
+.Vb 4
+\&    "aax" =~ /(?=x)(?<=(a|aa))/
+\&    "aax" =~ /(?=x)(?<=(aa|a))/
+\&    "aax" =~ /(?=x)(?<=(a{1,2}?)/
+\&    "aax" =~ /(?=x)(?<=(a{1,2})/
+.Ve
+.Sp
+will all result in \f(CW$1\fR containing \f(CW"aa"\fR. It is possible in a future
+release of perl we will change this behavior.
+.Sp
+There is a special form of this construct, called \f(CW\*(C`\eK\*(C'\fR
+(available since Perl 5.10.0), which causes the
+regex engine to "keep" everything it had matched prior to the \f(CW\*(C`\eK\*(C'\fR and
+not include it in \f(CW$&\fR. This effectively provides non-experimental
+variable-length lookbehind of any length.
+.Sp
+And, there is a technique that can be used to handle variable length
+lookbehinds on earlier releases, and longer than 255 characters.  It is
+described in
+<http://www.drregex.com/2019/02/variable\-length\-lookbehinds\-actually.html>.
+.Sp
+Note that under \f(CW\*(C`/i\*(C'\fR, a few single characters match two or three other
+characters.  This makes them variable length, and the 255 length applies
+to the maximum number of characters in the match.  For
+example \f(CW\*(C`qr/\eN{LATIN SMALL LETTER SHARP S}/i\*(C'\fR matches the sequence
+\&\f(CW"ss"\fR.  Your lookbehind assertion could contain 127 Sharp S
+characters under \f(CW\*(C`/i\*(C'\fR, but adding a 128th would generate a compilation
+error, as that could match 256 \f(CW"s"\fR characters in a row.
+.Sp
+The use of \f(CW\*(C`\eK\*(C'\fR inside of another lookaround assertion
+is allowed, but the behaviour is currently not well defined.
+.Sp
+For various reasons \f(CW\*(C`\eK\*(C'\fR may be significantly more efficient than the
+equivalent \f(CW\*(C`(?<=...)\*(C'\fR construct, and it is especially useful in
+situations where you want to efficiently remove something following
+something else in a string. For instance
+.Sp
+.Vb 1
+\&  s/(foo)bar/$1/g;
+.Ve
+.Sp
+can be rewritten as the much more efficient
+.Sp
+.Vb 1
+\&  s/foo\eKbar//g;
+.Ve
+.Sp
+Use of the non-greedy modifier \f(CW"?"\fR may not give you the expected
+results if it is within a capturing group within the construct.
+.ie n .IP """(?<!\fIpattern\fR)""" 4
+.el .IP \f(CW(?<!\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?<!pattern)"
+.PD 0
+.ie n .IP """(*nlb:\fIpattern\fR)""" 4
+.el .IP \f(CW(*nlb:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(*nlb:pattern)"
+.ie n .IP """(*negative_lookbehind:\fIpattern\fR)""" 4
+.el .IP \f(CW(*negative_lookbehind:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?<!) (*nlb (*negative_lookbehind look-behind, negative lookbehind, negative"
+.IX Item "(*negative_lookbehind:pattern)"
+.PD
+A zero-width negative lookbehind assertion.  For example \f(CW\*(C`/(?<!bar)foo/\*(C'\fR
+matches any occurrence of "foo" that does not follow "bar".
+.Sp
+Prior to Perl 5.30, it worked only for fixed-width lookbehind, but
+starting in that release, it can handle variable lengths from 1 to 255
+characters as an experimental feature.  The feature is enabled
+automatically if you use a variable length negative lookbehind assertion.
+.Sp
+In Perl 5.35.10 the scope of the experimental nature of this construct
+has been reduced, and experimental warnings will only be produced when
+the construct contains capturing parentheses. The warnings will be
+raised at pattern compilation time, unless turned off, in the
+\&\f(CW\*(C`experimental::vlb\*(C'\fR category.  This is to warn you that the exact
+contents of capturing buffers in a variable length negative lookbehind
+is not well defined and is subject to change in a future release of perl.
+.Sp
+Currently if you use capture buffers inside of a negative variable length
+lookbehind the result may not be what you expect, for instance:
+.Sp
+.Vb 1
+\&    say "axfoo"=~/(?=foo)(?<!(a|ax)(?{ say $1 }))/ ? "y" : "n";
+.Ve
+.Sp
+will output the following:
+.Sp
+.Vb 2
+\&    a
+\&    no
+.Ve
+.Sp
+which does not make sense as this should print out "ax" as the "a" does
+not line up at the correct place. Another example would be:
+.Sp
+.Vb 1
+\&    say "yes: \*(Aq$1\-$2\*(Aq" if "aayfoo"=~/(?=foo)(?<!(a|aa)(a|aa)x)/;
+.Ve
+.Sp
+will output the following:
+.Sp
+.Vb 1
+\&    yes: \*(Aqaa\-a\*(Aq
+.Ve
+.Sp
+It is possible in a future release of perl we will change this behavior
+so both of these examples produced more reasonable output.
+.Sp
+Note that we are confident that the construct will match and reject
+patterns appropriately, the undefined behavior strictly relates to the
+value of the capture buffer during or after matching.
+.Sp
+There is a technique that can be used to handle variable length
+lookbehind on earlier releases, and longer than 255 characters.  It is
+described in
+<http://www.drregex.com/2019/02/variable\-length\-lookbehinds\-actually.html>.
+.Sp
+Note that under \f(CW\*(C`/i\*(C'\fR, a few single characters match two or three other
+characters.  This makes them variable length, and the 255 length applies
+to the maximum number of characters in the match.  For
+example \f(CW\*(C`qr/\eN{LATIN SMALL LETTER SHARP S}/i\*(C'\fR matches the sequence
+\&\f(CW"ss"\fR.  Your lookbehind assertion could contain 127 Sharp S
+characters under \f(CW\*(C`/i\*(C'\fR, but adding a 128th would generate a compilation
+error, as that could match 256 \f(CW"s"\fR characters in a row.
+.Sp
+Use of the non-greedy modifier \f(CW"?"\fR may not give you the expected
+results if it is within a capturing group within the construct.
+.RE
+.RS 4
+.RE
+.ie n .IP """(?<\fINAME\fR>\fIpattern\fR)""" 4
+.el .IP \f(CW(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?<NAME>pattern)"
+.PD 0
+.ie n .IP """(?\*(Aq\fINAME\fR\*(Aq\fIpattern\fR)""" 4
+.el .IP \f(CW(?\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?<NAME>) (?'NAME') named capture capture"
+.IX Item "(?NAMEpattern)"
+.PD
+A named capture group. Identical in every respect to normal capturing
+parentheses \f(CW\*(C`()\*(C'\fR but for the additional fact that the group
+can be referred to by name in various regular expression
+constructs (like \f(CW\*(C`\eg{\fR\f(CINAME\fR\f(CW}\*(C'\fR) and can be accessed by name
+after a successful match via \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR. See perlvar
+for more details on the \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR hashes.
+.Sp
+If multiple distinct capture groups have the same name, then
+\&\f(CW$+{\fR\f(CINAME\fR\f(CW}\fR will refer to the leftmost defined group in the match.
+.Sp
+The forms \f(CW\*(C`(?\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR\f(CIpattern\fR\f(CW)\*(C'\fR and \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR
+are equivalent.
+.Sp
+\&\fBNOTE:\fR While the notation of this construct is the same as the similar
+function in .NET regexes, the behavior is not. In Perl the groups are
+numbered sequentially regardless of being named or not. Thus in the
+pattern
+.Sp
+.Vb 1
+\&  /(x)(?<foo>y)(z)/
+.Ve
+.Sp
+\&\f(CW$+{foo}\fR will be the same as \f(CW$2\fR, and \f(CW$3\fR will contain 'z' instead of
+the opposite which is what a .NET regex hacker might expect.
+.Sp
+Currently \fINAME\fR is restricted to simple identifiers only.
+In other words, it must match \f(CW\*(C`/^[_A\-Za\-z][_A\-Za\-z0\-9]*\ez/\*(C'\fR or
+its Unicode extension (see utf8),
+though it isn't extended by the locale (see perllocale).
+.Sp
+\&\fBNOTE:\fR In order to make things easier for programmers with experience
+with the Python or PCRE regex engines, the pattern \f(CW\*(C`(?P<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR
+may be used instead of \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR; however this form does not
+support the use of single quotes as a delimiter for the name.
+.ie n .IP """\ek<\fINAME\fR>""" 4
+.el .IP \f(CW\ek<\fR\f(CINAME\fR\f(CW>\fR 4
+.IX Item "k<NAME>"
+.PD 0
+.ie n .IP """\ek\*(Aq\fINAME\fR\*(Aq""" 4
+.el .IP \f(CW\ek\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR 4
+.IX Item "kNAME"
+.ie n .IP """\ek{\fINAME\fR}""" 4
+.el .IP \f(CW\ek{\fR\f(CINAME\fR\f(CW}\fR 4
+.IX Item "k{NAME}"
+.PD
+Named backreference. Similar to numeric backreferences, except that
+the group is designated by name and not number. If multiple groups
+have the same name then it refers to the leftmost defined group in
+the current match.
+.Sp
+It is an error to refer to a name not defined by a \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>)\*(C'\fR
+earlier in the pattern.
+.Sp
+All three forms are equivalent, although with \f(CW\*(C`\ek{ \fR\f(CINAME\fR\f(CW }\*(C'\fR,
+you may optionally have blanks within but adjacent to the braces, as
+shown.
+.Sp
+\&\fBNOTE:\fR In order to make things easier for programmers with experience
+with the Python or PCRE regex engines, the pattern \f(CW\*(C`(?P=\fR\f(CINAME\fR\f(CW)\*(C'\fR
+may be used instead of \f(CW\*(C`\ek<\fR\f(CINAME\fR\f(CW>\*(C'\fR.
+.ie n .IP """(?{ \fIcode\fR })""" 4
+.el .IP "\f(CW(?{ \fR\f(CIcode\fR\f(CW })\fR" 4
+.IX Xref "(?{}) regex, code in regexp, code in regular expression, code in"
+.IX Item "(?{ code })"
+\&\fBWARNING\fR: Using this feature safely requires that you understand its
+limitations.  Code executed that has side effects may not perform identically
+from version to version due to the effect of future optimisations in the regex
+engine.  For more information on this, see "Embedded Code Execution
+Frequency".
+.Sp
+This zero-width assertion executes any embedded Perl code.  It always
+succeeds, and its return value is set as \f(CW$^R\fR.
+.Sp
+In literal patterns, the code is parsed at the same time as the
+surrounding code. While within the pattern, control is passed temporarily
+back to the perl parser, until the logically-balancing closing brace is
+encountered. This is similar to the way that an array index expression in
+a literal string is handled, for example
+.Sp
+.Vb 1
+\&    "abc$array[ 1 + f(\*(Aq[\*(Aq) + g()]def"
+.Ve
+.Sp
+In particular, braces do not need to be balanced:
+.Sp
+.Vb 1
+\&    s/abc(?{ f(\*(Aq{\*(Aq); })/def/
+.Ve
+.Sp
+Even in a pattern that is interpolated and compiled at run-time, literal
+code blocks will be compiled once, at perl compile time; the following
+prints "ABCD":
+.Sp
+.Vb 5
+\&    print "D";
+\&    my $qr = qr/(?{ BEGIN { print "A" } })/;
+\&    my $foo = "foo";
+\&    /$foo$qr(?{ BEGIN { print "B" } })/;
+\&    BEGIN { print "C" }
+.Ve
+.Sp
+In patterns where the text of the code is derived from run-time
+information rather than appearing literally in a source code /pattern/,
+the code is compiled at the same time that the pattern is compiled, and
+for reasons of security, \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR must be in scope. This is to
+stop user-supplied patterns containing code snippets from being
+executable.
+.Sp
+In situations where you need to enable this with \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR, you should
+also have taint checking enabled, if your perl supports it.
+Better yet, use the carefully constrained evaluation within a Safe compartment.
+See perlsec for details about both these mechanisms.
+.Sp
+From the viewpoint of parsing, lexical variable scope and closures,
+.Sp
+.Vb 1
+\&    /AAA(?{ BBB })CCC/
+.Ve
+.Sp
+behaves approximately like
+.Sp
+.Vb 1
+\&    /AAA/ && do { BBB } && /CCC/
+.Ve
+.Sp
+Similarly,
+.Sp
+.Vb 1
+\&    qr/AAA(?{ BBB })CCC/
+.Ve
+.Sp
+behaves approximately like
+.Sp
+.Vb 1
+\&    sub { /AAA/ && do { BBB } && /CCC/ }
+.Ve
+.Sp
+In particular:
+.Sp
+.Vb 3
+\&    { my $i = 1; $r = qr/(?{ print $i })/ }
+\&    my $i = 2;
+\&    /$r/; # prints "1"
+.Ve
+.Sp
+Inside a \f(CW\*(C`(?{...})\*(C'\fR block, \f(CW$_\fR refers to the string the regular
+expression is matching against. You can also use \f(CWpos()\fR to know what is
+the current position of matching within this string.
+.Sp
+The code block introduces a new scope from the perspective of lexical
+variable declarations, but \fBnot\fR from the perspective of \f(CW\*(C`local\*(C'\fR and
+similar localizing behaviours. So later code blocks within the same
+pattern will still see the values which were localized in earlier blocks.
+These accumulated localizations are undone either at the end of a
+successful match, or if the assertion is backtracked (compare
+"Backtracking"). For example,
+.Sp
+.Vb 10
+\&  $_ = \*(Aqa\*(Aq x 8;
+\&  m<
+\&     (?{ $cnt = 0 })               # Initialize $cnt.
+\&     (
+\&       a
+\&       (?{
+\&           local $cnt = $cnt + 1;  # Update $cnt,
+\&                                   # backtracking\-safe.
+\&       })
+\&     )*
+\&     aaaa
+\&     (?{ $res = $cnt })            # On success copy to
+\&                                   # non\-localized location.
+\&   >x;
+.Ve
+.Sp
+will initially increment \f(CW$cnt\fR up to 8; then during backtracking, its
+value will be unwound back to 4, which is the value assigned to \f(CW$res\fR.
+At the end of the regex execution, \f(CW$cnt\fR will be wound back to its initial
+value of 0.
+.Sp
+This assertion may be used as the condition in a
+.Sp
+.Vb 1
+\&    (?(condition)yes\-pattern|no\-pattern)
+.Ve
+.Sp
+switch.  If \fInot\fR used in this way, the result of evaluation of \fIcode\fR
+is put into the special variable \f(CW$^R\fR.  This happens immediately, so
+\&\f(CW$^R\fR can be used from other \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR assertions inside the same
+regular expression.
+.Sp
+The assignment to \f(CW$^R\fR above is properly localized, so the old
+value of \f(CW$^R\fR is restored if the assertion is backtracked; compare
+"Backtracking".
+.Sp
+Note that the special variable \f(CW$^N\fR  is particularly useful with code
+blocks to capture the results of submatches in variables without having to
+keep track of the number of nested parentheses. For example:
+.Sp
+.Vb 3
+\&  $_ = "The brown fox jumps over the lazy dog";
+\&  /the (\eS+)(?{ $color = $^N }) (\eS+)(?{ $animal = $^N })/i;
+\&  print "color = $color, animal = $animal\en";
+.Ve
+.Sp
+The use of this construct disables some optimisations globally in the
+pattern, and the pattern may execute much slower as a consequence.
+Use a \f(CW\*(C`*\*(C'\fR instead of the \f(CW\*(C`?\*(C'\fR block to create an optimistic form of
+this construct. \f(CW\*(C`(*{ ... })\*(C'\fR should not disable any optimisations.
+.ie n .IP """(*{ \fIcode\fR })""" 4
+.el .IP "\f(CW(*{ \fR\f(CIcode\fR\f(CW })\fR" 4
+.IX Xref "(*{}) regex, optimistic code"
+.IX Item "(*{ code })"
+This is *exactly* the same as \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR with the exception
+that it does not disable \fBany\fR optimisations at all in the regex engine.
+How often it is executed may vary from perl release to perl release.
+In a failing match it may not even be executed at all.
+.ie n .IP """(??{ \fIcode\fR })""" 4
+.el .IP "\f(CW(??{ \fR\f(CIcode\fR\f(CW })\fR" 4
+.IX Xref "(??{}) regex, postponed regexp, postponed regular expression, postponed"
+.IX Item "(??{ code })"
+\&\fBWARNING\fR: Using this feature safely requires that you understand its
+limitations.  Code executed that has side effects may not perform
+identically from version to version due to the effect of future
+optimisations in the regex engine.  For more information on this, see
+"Embedded Code Execution Frequency".
+.Sp
+This is a "postponed" regular subexpression.  It behaves in \fIexactly\fR the
+same way as a \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR code block as described above, except that
+its return value, rather than being assigned to \f(CW$^R\fR, is treated as a
+pattern, compiled if it's a string (or used as-is if its a qr// object),
+then matched as if it were inserted instead of this construct.
+.Sp
+During the matching of this sub-pattern, it has its own set of
+captures which are valid during the sub-match, but are discarded once
+control returns to the main pattern. For example, the following matches,
+with the inner pattern capturing "B" and matching "BB", while the outer
+pattern captures "A";
+.Sp
+.Vb 3
+\&    my $inner = \*(Aq(.)\e1\*(Aq;
+\&    "ABBA" =~ /^(.)(??{ $inner })\e1/;
+\&    print $1; # prints "A";
+.Ve
+.Sp
+Note that this means that  there is no way for the inner pattern to refer
+to a capture group defined outside.  (The code block itself can use \f(CW$1\fR,
+\&\fIetc\fR., to refer to the enclosing pattern's capture groups.)  Thus, although
+.Sp
+.Vb 1
+\&    (\*(Aqa\*(Aq x 100)=~/(??{\*(Aq(.)\*(Aq x 100})/
+.Ve
+.Sp
+\&\fIwill\fR match, it will \fInot\fR set \f(CW$1\fR on exit.
+.Sp
+The following pattern matches a parenthesized group:
+.Sp
+.Vb 9
+\& $re = qr{
+\&            \e(
+\&            (?:
+\&               (?> [^()]+ )  # Non\-parens without backtracking
+\&             |
+\&               (??{ $re })   # Group with matching parens
+\&            )*
+\&            \e)
+\&         }x;
+.Ve
+.Sp
+See also
+\&\f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR
+for a different, more efficient way to accomplish
+the same task.
+.Sp
+Executing a postponed regular expression too many times without
+consuming any input string will also result in a fatal error.  The depth
+at which that happens is compiled into perl, so it can be changed with a
+custom build.
+.Sp
+The use of this construct disables some optimisations globally in the pattern,
+and the pattern may execute much slower as a consequence.
+.ie n .IP """(?\fIPARNO\fR)"" ""(?\-\fIPARNO\fR)"" ""(?+\fIPARNO\fR)"" ""(?R)"" ""(?0)""" 4
+.el .IP "\f(CW(?\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?\-\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?+\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?R)\fR \f(CW(?0)\fR" 4
+.IX Xref "(?PARNO) (?1) (?R) (?0) (?-1) (?+1) (?-PARNO) (?+PARNO) regex, recursive regexp, recursive regular expression, recursive regex, relative recursion GOSUB GOSTART"
+.IX Item "(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)"
+Recursive subpattern. Treat the contents of a given capture buffer in the
+current pattern as an independent subpattern and attempt to match it at
+the current position in the string. Information about capture state from
+the caller for things like backreferences is available to the subpattern,
+but capture buffers set by the subpattern are not visible to the caller.
+.Sp
+Similar to \f(CW\*(C`(??{ \fR\f(CIcode\fR\f(CW })\*(C'\fR except that it does not involve executing any
+code or potentially compiling a returned pattern string; instead it treats
+the part of the current pattern contained within a specified capture group
+as an independent pattern that must match at the current position. Also
+different is the treatment of capture buffers, unlike \f(CW\*(C`(??{ \fR\f(CIcode\fR\f(CW })\*(C'\fR
+recursive patterns have access to their caller's match state, so one can
+use backreferences safely.
+.Sp
+\&\fIPARNO\fR is a sequence of digits (not starting with 0) whose value reflects
+the paren-number of the capture group to recurse to. \f(CW\*(C`(?R)\*(C'\fR recurses to
+the beginning of the whole pattern. \f(CW\*(C`(?0)\*(C'\fR is an alternate syntax for
+\&\f(CW\*(C`(?R)\*(C'\fR. If \fIPARNO\fR is preceded by a plus or minus sign then it is assumed
+to be relative, with negative numbers indicating preceding capture groups
+and positive ones following. Thus \f(CW\*(C`(?\-1)\*(C'\fR refers to the most recently
+declared group, and \f(CW\*(C`(?+1)\*(C'\fR indicates the next group to be declared.
+Note that the counting for relative recursion differs from that of
+relative backreferences, in that with recursion unclosed groups \fBare\fR
+included.
+.Sp
+The following pattern matches a function \f(CWfoo()\fR which may contain
+balanced parentheses as the argument.
+.Sp
+.Vb 10
+\&  $re = qr{ (                   # paren group 1 (full function)
+\&              foo
+\&              (                 # paren group 2 (parens)
+\&                \e(
+\&                  (             # paren group 3 (contents of parens)
+\&                  (?:
+\&                   (?> [^()]+ ) # Non\-parens without backtracking
+\&                  |
+\&                   (?2)         # Recurse to start of paren group 2
+\&                  )*
+\&                  )
+\&                \e)
+\&              )
+\&            )
+\&          }x;
+.Ve
+.Sp
+If the pattern was used as follows
+.Sp
+.Vb 4
+\&    \*(Aqfoo(bar(baz)+baz(bop))\*(Aq=~/$re/
+\&        and print "\e$1 = $1\en",
+\&                  "\e$2 = $2\en",
+\&                  "\e$3 = $3\en";
+.Ve
+.Sp
+the output produced should be the following:
+.Sp
+.Vb 3
+\&    $1 = foo(bar(baz)+baz(bop))
+\&    $2 = (bar(baz)+baz(bop))
+\&    $3 = bar(baz)+baz(bop)
+.Ve
+.Sp
+If there is no corresponding capture group defined, then it is a
+fatal error.  Recursing deeply without consuming any input string will
+also result in a fatal error.  The depth at which that happens is
+compiled into perl, so it can be changed with a custom build.
+.Sp
+The following shows how using negative indexing can make it
+easier to embed recursive patterns inside of a \f(CW\*(C`qr//\*(C'\fR construct
+for later use:
+.Sp
+.Vb 4
+\&    my $parens = qr/(\e((?:[^()]++|(?\-1))*+\e))/;
+\&    if (/foo $parens \es+ \e+ \es+ bar $parens/x) {
+\&       # do something here...
+\&    }
+.Ve
+.Sp
+\&\fBNote\fR that this pattern does not behave the same way as the equivalent
+PCRE or Python construct of the same form. In Perl you can backtrack into
+a recursed group, in PCRE and Python the recursed into group is treated
+as atomic. Also, modifiers are resolved at compile time, so constructs
+like \f(CW\*(C`(?i:(?1))\*(C'\fR or \f(CW\*(C`(?:(?i)(?1))\*(C'\fR do not affect how the sub-pattern will
+be processed.
+.ie n .IP """(?&\fINAME\fR)""" 4
+.el .IP \f(CW(?&\fR\f(CINAME\fR\f(CW)\fR 4
+.IX Xref "(?&NAME)"
+.IX Item "(?&NAME)"
+Recurse to a named subpattern. Identical to \f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR except that the
+parenthesis to recurse to is determined by name. If multiple parentheses have
+the same name, then it recurses to the leftmost.
+.Sp
+It is an error to refer to a name that is not declared somewhere in the
+pattern.
+.Sp
+\&\fBNOTE:\fR In order to make things easier for programmers with experience
+with the Python or PCRE regex engines the pattern \f(CW\*(C`(?P>\fR\f(CINAME\fR\f(CW)\*(C'\fR
+may be used instead of \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR.
+.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR|\fIno\-pattern\fR)""" 4
+.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\fR 4
+.IX Xref "(?()"
+.IX Item "(?(condition)yes-pattern|no-pattern)"
+.PD 0
+.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR)""" 4
+.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW)\fR 4
+.IX Item "(?(condition)yes-pattern)"
+.PD
+Conditional expression. Matches \fIyes-pattern\fR if \fIcondition\fR yields
+a true value, matches \fIno-pattern\fR otherwise. A missing pattern always
+matches.
+.Sp
+\&\f(CW\*(C`(\fR\f(CIcondition\fR\f(CW)\*(C'\fR should be one of:
+.RS 4
+.IP "an integer in parentheses" 4
+.IX Item "an integer in parentheses"
+(which is valid if the corresponding pair of parentheses
+matched);
+.IP "a lookahead/lookbehind/evaluate zero-width assertion;" 4
+.IX Item "a lookahead/lookbehind/evaluate zero-width assertion;"
+.PD 0
+.IP "a name in angle brackets or single quotes" 4
+.IX Item "a name in angle brackets or single quotes"
+.PD
+(which is valid if a group with the given name matched);
+.ie n .IP "the special symbol ""(R)""" 4
+.el .IP "the special symbol \f(CW(R)\fR" 4
+.IX Item "the special symbol (R)"
+(true when evaluated inside of recursion or eval).  Additionally the
+\&\f(CW"R"\fR may be
+followed by a number, (which will be true when evaluated when recursing
+inside of the appropriate group), or by \f(CW\*(C`&\fR\f(CINAME\fR\f(CW\*(C'\fR, in which case it will
+be true only when evaluated during recursion in the named group.
+.RE
+.RS 4
+.Sp
+Here's a summary of the possible predicates:
+.ie n .IP """(1)"" ""(2)"" ..." 4
+.el .IP "\f(CW(1)\fR \f(CW(2)\fR ..." 4
+.IX Item "(1) (2) ..."
+Checks if the numbered capturing group has matched something.
+Full syntax: \f(CW\*(C`(?(1)then|else)\*(C'\fR
+.ie n .IP """(<\fINAME\fR>)"" ""(\*(Aq\fINAME\fR\*(Aq)""" 4
+.el .IP "\f(CW(<\fR\f(CINAME\fR\f(CW>)\fR \f(CW(\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq)\fR" 4
+.IX Item "(<NAME>) (NAME)"
+Checks if a group with the given name has matched something.
+Full syntax: \f(CW\*(C`(?(<name>)then|else)\*(C'\fR
+.ie n .IP """(?=...)"" ""(?!...)"" ""(?<=...)"" ""(?<!...)""" 4
+.el .IP "\f(CW(?=...)\fR \f(CW(?!...)\fR \f(CW(?<=...)\fR \f(CW(?<!...)\fR" 4
+.IX Item "(?=...) (?!...) (?<=...) (?<!...)"
+Checks whether the pattern matches (or does not match, for the \f(CW"!"\fR
+variants).
+Full syntax: \f(CW\*(C`(?(?=\fR\f(CIlookahead\fR\f(CW)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.ie n .IP """(?{ \fICODE\fR })""" 4
+.el .IP "\f(CW(?{ \fR\f(CICODE\fR\f(CW })\fR" 4
+.IX Item "(?{ CODE })"
+Treats the return value of the code block as the condition.
+Full syntax: \f(CW\*(C`(?(?{ \fR\f(CICODE\fR\f(CW })\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.Sp
+Note use of this construct may globally affect the performance
+of the pattern. Consider using \f(CW\*(C`(*{ \fR\f(CICODE\fR\f(CW })\*(C'\fR
+.ie n .IP """(*{ \fICODE\fR })""" 4
+.el .IP "\f(CW(*{ \fR\f(CICODE\fR\f(CW })\fR" 4
+.IX Item "(*{ CODE })"
+Treats the return value of the code block as the condition.
+Full syntax: \f(CW\*(C`(?(*{ \fR\f(CICODE\fR\f(CW })\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.ie n .IP """(R)""" 4
+.el .IP \f(CW(R)\fR 4
+.IX Item "(R)"
+Checks if the expression has been evaluated inside of recursion.
+Full syntax: \f(CW\*(C`(?(R)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.ie n .IP """(R1)"" ""(R2)"" ..." 4
+.el .IP "\f(CW(R1)\fR \f(CW(R2)\fR ..." 4
+.IX Item "(R1) (R2) ..."
+Checks if the expression has been evaluated while executing directly
+inside of the n\-th capture group. This check is the regex equivalent of
+.Sp
+.Vb 1
+\&  if ((caller(0))[3] eq \*(Aqsubname\*(Aq) { ... }
+.Ve
+.Sp
+In other words, it does not check the full recursion stack.
+.Sp
+Full syntax: \f(CW\*(C`(?(R1)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.ie n .IP """(R&\fINAME\fR)""" 4
+.el .IP \f(CW(R&\fR\f(CINAME\fR\f(CW)\fR 4
+.IX Item "(R&NAME)"
+Similar to \f(CW\*(C`(R1)\*(C'\fR, this predicate checks to see if we're executing
+directly inside of the leftmost group with a given name (this is the same
+logic used by \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR to disambiguate). It does not check the full
+stack, but only the name of the innermost active recursion.
+Full syntax: \f(CW\*(C`(?(R&\fR\f(CIname\fR\f(CW)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR
+.ie n .IP """(DEFINE)""" 4
+.el .IP \f(CW(DEFINE)\fR 4
+.IX Item "(DEFINE)"
+In this case, the yes-pattern is never directly executed, and no
+no-pattern is allowed. Similar in spirit to \f(CW\*(C`(?{0})\*(C'\fR but more efficient.
+See below for details.
+Full syntax: \f(CW\*(C`(?(DEFINE)\fR\f(CIdefinitions\fR\f(CW...)\*(C'\fR
+.RE
+.RS 4
+.Sp
+For example:
+.Sp
+.Vb 4
+\&    m{ ( \e( )?
+\&       [^()]+
+\&       (?(1) \e) )
+\&     }x
+.Ve
+.Sp
+matches a chunk of non-parentheses, possibly included in parentheses
+themselves.
+.Sp
+A special form is the \f(CW\*(C`(DEFINE)\*(C'\fR predicate, which never executes its
+yes-pattern directly, and does not allow a no-pattern. This allows one to
+define subpatterns which will be executed only by the recursion mechanism.
+This way, you can define a set of regular expression rules that can be
+bundled into any pattern you choose.
+.Sp
+It is recommended that for this usage you put the DEFINE block at the
+end of the pattern, and that you name any subpatterns defined within it.
+.Sp
+Also, it's worth noting that patterns defined this way probably will
+not be as efficient, as the optimizer is not very clever about
+handling them.
+.Sp
+An example of how this might be used is as follows:
+.Sp
+.Vb 5
+\&  /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
+\&   (?(DEFINE)
+\&     (?<NAME_PAT>....)
+\&     (?<ADDRESS_PAT>....)
+\&   )/x
+.Ve
+.Sp
+Note that capture groups matched inside of recursion are not accessible
+after the recursion returns, so the extra layer of capturing groups is
+necessary. Thus \f(CW$+{NAME_PAT}\fR would not be defined even though
+\&\f(CW$+{NAME}\fR would be.
+.Sp
+Finally, keep in mind that subpatterns created inside a DEFINE block
+count towards the absolute and relative number of captures, so this:
+.Sp
+.Vb 5
+\&    my @captures = "a" =~ /(.)                  # First capture
+\&                           (?(DEFINE)
+\&                               (?<EXAMPLE> 1 )  # Second capture
+\&                           )/x;
+\&    say scalar @captures;
+.Ve
+.Sp
+Will output 2, not 1. This is particularly important if you intend to
+compile the definitions with the \f(CW\*(C`qr//\*(C'\fR operator, and later
+interpolate them in another pattern.
+.RE
+.ie n .IP """(?>\fIpattern\fR)""" 4
+.el .IP \f(CW(?>\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?>pattern)"
+.PD 0
+.ie n .IP """(*atomic:\fIpattern\fR)""" 4
+.el .IP \f(CW(*atomic:\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Xref "(?>pattern) (*atomic backtrack backtracking atomic possessive"
+.IX Item "(*atomic:pattern)"
+.PD
+An "independent" subexpression, one which matches the substring
+that a standalone \fIpattern\fR would match if anchored at the given
+position, and it matches \fInothing other than this substring\fR.  This
+construct is useful for optimizations of what would otherwise be
+"eternal" matches, because it will not backtrack (see "Backtracking").
+It may also be useful in places where the "grab all you can, and do not
+give anything back" semantic is desirable.
+.Sp
+For example: \f(CW\*(C`^(?>a*)ab\*(C'\fR will never match, since \f(CW\*(C`(?>a*)\*(C'\fR
+(anchored at the beginning of string, as above) will match \fIall\fR
+characters \f(CW"a"\fR at the beginning of string, leaving no \f(CW"a"\fR for
+\&\f(CW\*(C`ab\*(C'\fR to match.  In contrast, \f(CW\*(C`a*ab\*(C'\fR will match the same as \f(CW\*(C`a+b\*(C'\fR,
+since the match of the subgroup \f(CW\*(C`a*\*(C'\fR is influenced by the following
+group \f(CW\*(C`ab\*(C'\fR (see "Backtracking").  In particular, \f(CW\*(C`a*\*(C'\fR inside
+\&\f(CW\*(C`a*ab\*(C'\fR will match fewer characters than a standalone \f(CW\*(C`a*\*(C'\fR, since
+this makes the tail match.
+.Sp
+\&\f(CW\*(C`(?>\fR\f(CIpattern\fR\f(CW)\*(C'\fR does not disable backtracking altogether once it has
+matched. It is still possible to backtrack past the construct, but not
+into it. So \f(CW\*(C`((?>a*)|(?>b*))ar\*(C'\fR will still match "bar".
+.Sp
+An effect similar to \f(CW\*(C`(?>\fR\f(CIpattern\fR\f(CW)\*(C'\fR may be achieved by writing
+\&\f(CW\*(C`(?=(\fR\f(CIpattern\fR\f(CW))\eg{\-1}\*(C'\fR.  This matches the same substring as a standalone
+\&\f(CW\*(C`a+\*(C'\fR, and the following \f(CW\*(C`\eg{\-1}\*(C'\fR eats the matched string; it therefore
+makes a zero-length assertion into an analogue of \f(CW\*(C`(?>...)\*(C'\fR.
+(The difference between these two constructs is that the second one
+uses a capturing group, thus shifting ordinals of backreferences
+in the rest of a regular expression.)
+.Sp
+Consider this pattern:
+.Sp
+.Vb 8
+\&    m{ \e(
+\&          (
+\&            [^()]+           # x+
+\&          |
+\&            \e( [^()]* \e)
+\&          )+
+\&       \e)
+\&     }x
+.Ve
+.Sp
+That will efficiently match a nonempty group with matching parentheses
+two levels deep or less.  However, if there is no such group, it
+will take virtually forever on a long string.  That's because there
+are so many different ways to split a long string into several
+substrings.  This is what \f(CW\*(C`(.+)+\*(C'\fR is doing, and \f(CW\*(C`(.+)+\*(C'\fR is similar
+to a subpattern of the above pattern.  Consider how the pattern
+above detects no-match on \f(CW\*(C`((()aaaaaaaaaaaaaaaaaa\*(C'\fR in several
+seconds, but that each extra letter doubles this time.  This
+exponential performance will make it appear that your program has
+hung.  However, a tiny change to this pattern
+.Sp
+.Vb 8
+\&    m{ \e(
+\&          (
+\&            (?> [^()]+ )        # change x+ above to (?> x+ )
+\&          |
+\&            \e( [^()]* \e)
+\&          )+
+\&       \e)
+\&     }x
+.Ve
+.Sp
+which uses \f(CW\*(C`(?>...)\*(C'\fR matches exactly when the one above does (verifying
+this yourself would be a productive exercise), but finishes in a fourth
+the time when used on a similar string with 1000000 \f(CW"a"\fRs.  Be aware,
+however, that, when this construct is followed by a
+quantifier, it currently triggers a warning message under
+the \f(CW\*(C`use warnings\*(C'\fR pragma or \fB\-w\fR switch saying it
+\&\f(CW"matches null string many times in regex"\fR.
+.Sp
+On simple groups, such as the pattern \f(CW\*(C`(?> [^()]+ )\*(C'\fR, a comparable
+effect may be achieved by negative lookahead, as in \f(CW\*(C`[^()]+ (?! [^()] )\*(C'\fR.
+This was only 4 times slower on a string with 1000000 \f(CW"a"\fRs.
+.Sp
+The "grab all you can, and do not give anything back" semantic is desirable
+in many situations where on the first sight a simple \f(CW\*(C`()*\*(C'\fR looks like
+the correct solution.  Suppose we parse text with comments being delimited
+by \f(CW"#"\fR followed by some optional (horizontal) whitespace.  Contrary to
+its appearance, \f(CW\*(C`#[ \et]*\*(C'\fR \fIis not\fR the correct subexpression to match
+the comment delimiter, because it may "give up" some whitespace if
+the remainder of the pattern can be made to match that way.  The correct
+answer is either one of these:
+.Sp
+.Vb 2
+\&    (?>#[ \et]*)
+\&    #[ \et]*(?![ \et])
+.Ve
+.Sp
+For example, to grab non-empty comments into \f(CW$1\fR, one should use either
+one of these:
+.Sp
+.Vb 2
+\&    / (?> \e# [ \et]* ) (        .+ ) /x;
+\&    /     \e# [ \et]*   ( [^ \et] .* ) /x;
+.Ve
+.Sp
+Which one you pick depends on which of these expressions better reflects
+the above specification of comments.
+.Sp
+In some literature this construct is called "atomic matching" or
+"possessive matching".
+.Sp
+Possessive quantifiers are equivalent to putting the item they are applied
+to inside of one of these constructs. The following equivalences apply:
+.Sp
+.Vb 6
+\&    Quantifier Form     Bracketing Form
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    PAT*+               (?>PAT*)
+\&    PAT++               (?>PAT+)
+\&    PAT?+               (?>PAT?)
+\&    PAT{min,max}+       (?>PAT{min,max})
+.Ve
+.Sp
+Nested \f(CW\*(C`(?>...)\*(C'\fR constructs are not no-ops, even if at first glance
+they might seem to be.  This is because the nested \f(CW\*(C`(?>...)\*(C'\fR can
+restrict internal backtracking that otherwise might occur.  For example,
+.Sp
+.Vb 1
+\& "abc" =~ /(?>a[bc]*c)/
+.Ve
+.Sp
+matches, but
+.Sp
+.Vb 1
+\& "abc" =~ /(?>a(?>[bc]*)c)/
+.Ve
+.Sp
+does not.
+.ie n .IP """(?[ ])""" 4
+.el .IP "\f(CW(?[ ])\fR" 4
+.IX Item "(?[ ])"
+See "Extended Bracketed Character Classes" in perlrecharclass.
+.SS Backtracking
+.IX Xref "backtrack backtracking"
+.IX Subsection "Backtracking"
+NOTE: This section presents an abstract approximation of regular
+expression behavior.  For a more rigorous (and complicated) view of
+the rules involved in selecting a match among possible alternatives,
+see "Combining RE Pieces".
+.PP
+A fundamental feature of regular expression matching involves the
+notion called \fIbacktracking\fR, which is currently used (when needed)
+by all regular non-possessive expression quantifiers, namely \f(CW"*"\fR,
+\&\f(CW\*(C`*?\*(C'\fR, \f(CW"+"\fR, \f(CW\*(C`+?\*(C'\fR, \f(CW\*(C`{n,m}\*(C'\fR, and \f(CW\*(C`{n,m}?\*(C'\fR.  Backtracking is often
+optimized internally, but the general principle outlined here is valid.
+.PP
+For a regular expression to match, the \fIentire\fR regular expression must
+match, not just part of it.  So if the beginning of a pattern containing a
+quantifier succeeds in a way that causes later parts in the pattern to
+fail, the matching engine backs up and recalculates the beginning
+part\-\-that's why it's called backtracking.
+.PP
+Here is an example of backtracking:  Let's say you want to find the
+word following "foo" in the string "Food is on the foo table.":
+.PP
+.Vb 4
+\&    $_ = "Food is on the foo table.";
+\&    if ( /\eb(foo)\es+(\ew+)/i ) {
+\&        print "$2 follows $1.\en";
+\&    }
+.Ve
+.PP
+When the match runs, the first part of the regular expression (\f(CW\*(C`\eb(foo)\*(C'\fR)
+finds a possible match right at the beginning of the string, and loads up
+\&\f(CW$1\fR with "Foo".  However, as soon as the matching engine sees that there's
+no whitespace following the "Foo" that it had saved in \f(CW$1\fR, it realizes its
+mistake and starts over again one character after where it had the
+tentative match.  This time it goes all the way until the next occurrence
+of "foo". The complete regular expression matches this time, and you get
+the expected output of "table follows foo."
+.PP
+Sometimes minimal matching can help a lot.  Imagine you'd like to match
+everything between "foo" and "bar".  Initially, you write something
+like this:
+.PP
+.Vb 4
+\&    $_ =  "The food is under the bar in the barn.";
+\&    if ( /foo(.*)bar/ ) {
+\&        print "got <$1>\en";
+\&    }
+.Ve
+.PP
+Which perhaps unexpectedly yields:
+.PP
+.Vb 1
+\&  got <d is under the bar in the >
+.Ve
+.PP
+That's because \f(CW\*(C`.*\*(C'\fR was greedy, so you get everything between the
+\&\fIfirst\fR "foo" and the \fIlast\fR "bar".  Here it's more effective
+to use minimal matching to make sure you get the text between a "foo"
+and the first "bar" thereafter.
+.PP
+.Vb 2
+\&    if ( /foo(.*?)bar/ ) { print "got <$1>\en" }
+\&  got <d is under the >
+.Ve
+.PP
+Here's another example. Let's say you'd like to match a number at the end
+of a string, and you also want to keep the preceding part of the match.
+So you write this:
+.PP
+.Vb 4
+\&    $_ = "I have 2 numbers: 53147";
+\&    if ( /(.*)(\ed*)/ ) {                                # Wrong!
+\&        print "Beginning is <$1>, number is <$2>.\en";
+\&    }
+.Ve
+.PP
+That won't work at all, because \f(CW\*(C`.*\*(C'\fR was greedy and gobbled up the
+whole string. As \f(CW\*(C`\ed*\*(C'\fR can match on an empty string the complete
+regular expression matched successfully.
+.PP
+.Vb 1
+\&    Beginning is <I have 2 numbers: 53147>, number is <>.
+.Ve
+.PP
+Here are some variants, most of which don't work:
+.PP
+.Vb 11
+\&    $_ = "I have 2 numbers: 53147";
+\&    @pats = qw{
+\&        (.*)(\ed*)
+\&        (.*)(\ed+)
+\&        (.*?)(\ed*)
+\&        (.*?)(\ed+)
+\&        (.*)(\ed+)$
+\&        (.*?)(\ed+)$
+\&        (.*)\eb(\ed+)$
+\&        (.*\eD)(\ed+)$
+\&    };
+\&
+\&    for $pat (@pats) {
+\&        printf "%\-12s ", $pat;
+\&        if ( /$pat/ ) {
+\&            print "<$1> <$2>\en";
+\&        } else {
+\&            print "FAIL\en";
+\&        }
+\&    }
+.Ve
+.PP
+That will print out:
+.PP
+.Vb 8
+\&    (.*)(\ed*)    <I have 2 numbers: 53147> <>
+\&    (.*)(\ed+)    <I have 2 numbers: 5314> <7>
+\&    (.*?)(\ed*)   <> <>
+\&    (.*?)(\ed+)   <I have > <2>
+\&    (.*)(\ed+)$   <I have 2 numbers: 5314> <7>
+\&    (.*?)(\ed+)$  <I have 2 numbers: > <53147>
+\&    (.*)\eb(\ed+)$ <I have 2 numbers: > <53147>
+\&    (.*\eD)(\ed+)$ <I have 2 numbers: > <53147>
+.Ve
+.PP
+As you see, this can be a bit tricky.  It's important to realize that a
+regular expression is merely a set of assertions that gives a definition
+of success.  There may be 0, 1, or several different ways that the
+definition might succeed against a particular string.  And if there are
+multiple ways it might succeed, you need to understand backtracking to
+know which variety of success you will achieve.
+.PP
+When using lookahead assertions and negations, this can all get even
+trickier.  Imagine you'd like to find a sequence of non-digits not
+followed by "123".  You might try to write that as
+.PP
+.Vb 4
+\&    $_ = "ABC123";
+\&    if ( /^\eD*(?!123)/ ) {                # Wrong!
+\&        print "Yup, no 123 in $_\en";
+\&    }
+.Ve
+.PP
+But that isn't going to match; at least, not the way you're hoping.  It
+claims that there is no 123 in the string.  Here's a clearer picture of
+why that pattern matches, contrary to popular expectations:
+.PP
+.Vb 2
+\&    $x = \*(AqABC123\*(Aq;
+\&    $y = \*(AqABC445\*(Aq;
+\&
+\&    print "1: got $1\en" if $x =~ /^(ABC)(?!123)/;
+\&    print "2: got $1\en" if $y =~ /^(ABC)(?!123)/;
+\&
+\&    print "3: got $1\en" if $x =~ /^(\eD*)(?!123)/;
+\&    print "4: got $1\en" if $y =~ /^(\eD*)(?!123)/;
+.Ve
+.PP
+This prints
+.PP
+.Vb 3
+\&    2: got ABC
+\&    3: got AB
+\&    4: got ABC
+.Ve
+.PP
+You might have expected test 3 to fail because it seems to a more
+general purpose version of test 1.  The important difference between
+them is that test 3 contains a quantifier (\f(CW\*(C`\eD*\*(C'\fR) and so can use
+backtracking, whereas test 1 will not.  What's happening is
+that you've asked "Is it true that at the start of \f(CW$x\fR, following 0 or more
+non-digits, you have something that's not 123?"  If the pattern matcher had
+let \f(CW\*(C`\eD*\*(C'\fR expand to "ABC", this would have caused the whole pattern to
+fail.
+.PP
+The search engine will initially match \f(CW\*(C`\eD*\*(C'\fR with "ABC".  Then it will
+try to match \f(CW\*(C`(?!123)\*(C'\fR with "123", which fails.  But because
+a quantifier (\f(CW\*(C`\eD*\*(C'\fR) has been used in the regular expression, the
+search engine can backtrack and retry the match differently
+in the hope of matching the complete regular expression.
+.PP
+The pattern really, \fIreally\fR wants to succeed, so it uses the
+standard pattern back-off-and-retry and lets \f(CW\*(C`\eD*\*(C'\fR expand to just "AB" this
+time.  Now there's indeed something following "AB" that is not
+"123".  It's "C123", which suffices.
+.PP
+We can deal with this by using both an assertion and a negation.
+We'll say that the first part in \f(CW$1\fR must be followed both by a digit
+and by something that's not "123".  Remember that the lookaheads
+are zero-width expressions\-\-they only look, but don't consume any
+of the string in their match.  So rewriting this way produces what
+you'd expect; that is, case 5 will fail, but case 6 succeeds:
+.PP
+.Vb 2
+\&    print "5: got $1\en" if $x =~ /^(\eD*)(?=\ed)(?!123)/;
+\&    print "6: got $1\en" if $y =~ /^(\eD*)(?=\ed)(?!123)/;
+\&
+\&    6: got ABC
+.Ve
+.PP
+In other words, the two zero-width assertions next to each other work as though
+they're ANDed together, just as you'd use any built-in assertions:  \f(CW\*(C`/^$/\*(C'\fR
+matches only if you're at the beginning of the line AND the end of the
+line simultaneously.  The deeper underlying truth is that juxtaposition in
+regular expressions always means AND, except when you write an explicit OR
+using the vertical bar.  \f(CW\*(C`/ab/\*(C'\fR means match "a" AND (then) match "b",
+although the attempted matches are made at different positions because "a"
+is not a zero-width assertion, but a one-width assertion.
+.PP
+\&\fBWARNING\fR: Particularly complicated regular expressions can take
+exponential time to solve because of the immense number of possible
+ways they can use backtracking to try for a match.  For example, without
+internal optimizations done by the regular expression engine, this will
+take a painfully long time to run:
+.PP
+.Vb 1
+\&    \*(Aqaaaaaaaaaaaa\*(Aq =~ /((a{0,5}){0,5})*[c]/
+.Ve
+.PP
+And if you used \f(CW"*"\fR's in the internal groups instead of limiting them
+to 0 through 5 matches, then it would take forever\-\-or until you ran
+out of stack space.  Moreover, these internal optimizations are not
+always applicable.  For example, if you put \f(CW\*(C`{0,5}\*(C'\fR instead of \f(CW"*"\fR
+on the external group, no current optimization is applicable, and the
+match takes a long time to finish.
+.PP
+A powerful tool for optimizing such beasts is what is known as an
+"independent group",
+which does not backtrack (see \f(CW"(?>pattern)"\fR).  Note also that
+zero-length lookahead/lookbehind assertions will not backtrack to make
+the tail match, since they are in "logical" context: only
+whether they match is considered relevant.  For an example
+where side-effects of lookahead \fImight\fR have influenced the
+following match, see \f(CW"(?>pattern)"\fR.
+.SS "Script Runs"
+.IX Xref "(*script_run:...) (sr:...) (*atomic_script_run:...) (asr:...)"
+.IX Subsection "Script Runs"
+A script run is basically a sequence of characters, all from the same
+Unicode script (see "Scripts" in perlunicode), such as Latin or Greek.  In
+most places a single word would never be written in multiple scripts,
+unless it is a spoofing attack.  An infamous example, is
+.PP
+.Vb 1
+\& paypal.com
+.Ve
+.PP
+Those letters could all be Latin (as in the example just above), or they
+could be all Cyrillic (except for the dot), or they could be a mixture
+of the two.  In the case of an internet address the \f(CW\*(C`.com\*(C'\fR would be in
+Latin, And any Cyrillic ones would cause it to be a mixture, not a
+script run.  Someone clicking on such a link would not be directed to
+the real Paypal website, but an attacker would craft a look-alike one to
+attempt to gather sensitive information from the person.
+.PP
+Starting in Perl 5.28, it is now easy to detect strings that aren't
+script runs.  Simply enclose just about any pattern like either of
+these:
+.PP
+.Vb 2
+\& (*script_run:pattern)
+\& (*sr:pattern)
+.Ve
+.PP
+What happens is that after \fIpattern\fR succeeds in matching, it is
+subjected to the additional criterion that every character in it must be
+from the same script (see exceptions below).  If this isn't true,
+backtracking occurs until something all in the same script is found that
+matches, or all possibilities are exhausted.  This can cause a lot of
+backtracking, but generally, only malicious input will result in this,
+though the slow down could cause a denial of service attack.  If your
+needs permit, it is best to make the pattern atomic to cut down on the
+amount of backtracking.  This is so likely to be what you want, that
+instead of writing this:
+.PP
+.Vb 1
+\& (*script_run:(?>pattern))
+.Ve
+.PP
+you can write either of these:
+.PP
+.Vb 2
+\& (*atomic_script_run:pattern)
+\& (*asr:pattern)
+.Ve
+.PP
+(See \f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR.)
+.PP
+In Taiwan, Japan, and Korea, it is common for text to have a mixture of
+characters from their native scripts and base Chinese.  Perl follows
+Unicode's UTS 39 (<https://unicode.org/reports/tr39/>) Unicode Security
+Mechanisms in allowing such mixtures.  For example, the Japanese scripts
+Katakana and Hiragana are commonly mixed together in practice, along
+with some Chinese characters, and hence are treated as being in a single
+script run by Perl.
+.PP
+The rules used for matching decimal digits are slightly stricter.  Many
+scripts have their own sets of digits equivalent to the Western \f(CW0\fR
+through \f(CW9\fR ones.  A few, such as Arabic, have more than one set.  For
+a string to be considered a script run, all digits in it must come from
+the same set of ten, as determined by the first digit encountered.
+As an example,
+.PP
+.Vb 1
+\& qr/(*script_run: \ed+ \eb )/x
+.Ve
+.PP
+guarantees that the digits matched will all be from the same set of 10.
+You won't get a look-alike digit from a different script that has a
+different value than what it appears to be.
+.PP
+Unicode has three pseudo scripts that are handled specially.
+.PP
+"Unknown" is applied to code points whose meaning has yet to be
+determined.  Perl currently will match as a script run, any single
+character string consisting of one of these code points.  But any string
+longer than one code point containing one of these will not be
+considered a script run.
+.PP
+"Inherited" is applied to characters that modify another, such as an
+accent of some type.  These are considered to be in the script of the
+master character, and so never cause a script run to not match.
+.PP
+The other one is "Common".  This consists of mostly punctuation, emoji,
+characters used in mathematics and music, the ASCII digits \f(CW0\fR
+through \f(CW9\fR, and full-width forms of these digits.  These characters
+can appear intermixed in text in many of the world's scripts.  These
+also don't cause a script run to not match.  But like other scripts, all
+digits in a run must come from the same set of 10.
+.PP
+This construct is non-capturing.  You can add parentheses to \fIpattern\fR
+to capture, if desired.  You will have to do this if you plan to use
+"(*ACCEPT) (*ACCEPT:arg)" and not have it bypass the script run
+checking.
+.PP
+The \f(CW\*(C`Script_Extensions\*(C'\fR property as modified by UTS 39
+(<https://unicode.org/reports/tr39/>) is used as the basis for this
+feature.
+.PP
+To summarize,
+.IP \(bu 4
+All length 0 or length 1 sequences are script runs.
+.IP \(bu 4
+A longer sequence is a script run if and only if \fBall\fR of the following
+conditions are met:
+.Sp
+
+.RS 4
+.IP 1. 4
+No code point in the sequence has the \f(CW\*(C`Script_Extension\*(C'\fR property of
+\&\f(CW\*(C`Unknown\*(C'\fR.
+.Sp
+This currently means that all code points in the sequence have been
+assigned by Unicode to be characters that aren't private use nor
+surrogate code points.
+.IP 2. 4
+All characters in the sequence come from the Common script and/or the
+Inherited script and/or a single other script.
+.Sp
+The script of a character is determined by the \f(CW\*(C`Script_Extensions\*(C'\fR
+property as modified by UTS 39 (<https://unicode.org/reports/tr39/>), as
+described above.
+.IP 3. 4
+All decimal digits in the sequence come from the same block of 10
+consecutive digits.
+.RE
+.RS 4
+.RE
+.SS "Special Backtracking Control Verbs"
+.IX Subsection "Special Backtracking Control Verbs"
+These special patterns are generally of the form \f(CW\*(C`(*\fR\f(CIVERB\fR\f(CW:\fR\f(CIarg\fR\f(CW)\*(C'\fR. Unless
+otherwise stated the \fIarg\fR argument is optional; in some cases, it is
+mandatory.
+.PP
+Any pattern containing a special backtracking verb that allows an argument
+has the special behaviour that when executed it sets the current package's
+\&\f(CW$REGERROR\fR and \f(CW$REGMARK\fR variables. When doing so the following
+rules apply:
+.PP
+On failure, the \f(CW$REGERROR\fR variable will be set to the \fIarg\fR value of the
+verb pattern, if the verb was involved in the failure of the match. If the
+\&\fIarg\fR part of the pattern was omitted, then \f(CW$REGERROR\fR will be set to the
+name of the last \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern executed, or to TRUE if there was
+none. Also, the \f(CW$REGMARK\fR variable will be set to FALSE.
+.PP
+On a successful match, the \f(CW$REGERROR\fR variable will be set to FALSE, and
+the \f(CW$REGMARK\fR variable will be set to the name of the last
+\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern executed.  See the explanation for the
+\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR verb below for more details.
+.PP
+\&\fBNOTE:\fR \f(CW$REGERROR\fR and \f(CW$REGMARK\fR are not magic variables like \f(CW$1\fR
+and most other regex-related variables. They are not local to a scope, nor
+readonly, but instead are volatile package variables similar to \f(CW$AUTOLOAD\fR.
+They are set in the package containing the code that \fIexecuted\fR the regex
+(rather than the one that compiled it, where those differ).  If necessary, you
+can use \f(CW\*(C`local\*(C'\fR to localize changes to these variables to a specific scope
+before executing a regex.
+.PP
+If a pattern does not contain a special backtracking verb that allows an
+argument, then \f(CW$REGERROR\fR and \f(CW$REGMARK\fR are not touched at all.
+.IP Verbs 3
+.IX Item "Verbs"
+.RS 3
+.PD 0
+.ie n .IP """(*PRUNE)"" ""(*PRUNE:\fINAME\fR)""" 4
+.el .IP "\f(CW(*PRUNE)\fR \f(CW(*PRUNE:\fR\f(CINAME\fR\f(CW)\fR" 4
+.IX Xref "(*PRUNE) (*PRUNE:NAME)"
+.IX Item "(*PRUNE) (*PRUNE:NAME)"
+.PD
+This zero-width pattern prunes the backtracking tree at the current point
+when backtracked into on failure. Consider the pattern \f(CW\*(C`/\fR\f(CIA\fR\f(CW (*PRUNE) \fR\f(CIB\fR\f(CW/\*(C'\fR,
+where \fIA\fR and \fIB\fR are complex patterns. Until the \f(CW\*(C`(*PRUNE)\*(C'\fR verb is reached,
+\&\fIA\fR may backtrack as necessary to match. Once it is reached, matching
+continues in \fIB\fR, which may also backtrack as necessary; however, should B
+not match, then no further backtracking will take place, and the pattern
+will fail outright at the current starting position.
+.Sp
+The following example counts all the possible matching strings in a
+pattern (without actually matching any of them).
+.Sp
+.Vb 2
+\&    \*(Aqaaab\*(Aq =~ /a+b?(?{print "$&\en"; $count++})(*FAIL)/;
+\&    print "Count=$count\en";
+.Ve
+.Sp
+which produces:
+.Sp
+.Vb 10
+\&    aaab
+\&    aaa
+\&    aa
+\&    a
+\&    aab
+\&    aa
+\&    a
+\&    ab
+\&    a
+\&    Count=9
+.Ve
+.Sp
+If we add a \f(CW\*(C`(*PRUNE)\*(C'\fR before the count like the following
+.Sp
+.Vb 2
+\&    \*(Aqaaab\*(Aq =~ /a+b?(*PRUNE)(?{print "$&\en"; $count++})(*FAIL)/;
+\&    print "Count=$count\en";
+.Ve
+.Sp
+we prevent backtracking and find the count of the longest matching string
+at each matching starting point like so:
+.Sp
+.Vb 4
+\&    aaab
+\&    aab
+\&    ab
+\&    Count=3
+.Ve
+.Sp
+Any number of \f(CW\*(C`(*PRUNE)\*(C'\fR assertions may be used in a pattern.
+.Sp
+See also \f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR and possessive quantifiers for
+other ways to
+control backtracking. In some cases, the use of \f(CW\*(C`(*PRUNE)\*(C'\fR can be
+replaced with a \f(CW\*(C`(?>pattern)\*(C'\fR with no functional difference; however,
+\&\f(CW\*(C`(*PRUNE)\*(C'\fR can be used to handle cases that cannot be expressed using a
+\&\f(CW\*(C`(?>pattern)\*(C'\fR alone.
+.ie n .IP """(*SKIP)"" ""(*SKIP:\fINAME\fR)""" 4
+.el .IP "\f(CW(*SKIP)\fR \f(CW(*SKIP:\fR\f(CINAME\fR\f(CW)\fR" 4
+.IX Xref "(*SKIP)"
+.IX Item "(*SKIP) (*SKIP:NAME)"
+This zero-width pattern is similar to \f(CW\*(C`(*PRUNE)\*(C'\fR, except that on
+failure it also signifies that whatever text that was matched leading up
+to the \f(CW\*(C`(*SKIP)\*(C'\fR pattern being executed cannot be part of \fIany\fR match
+of this pattern. This effectively means that the regex engine "skips" forward
+to this position on failure and tries to match again, (assuming that
+there is sufficient room to match).
+.Sp
+The name of the \f(CW\*(C`(*SKIP:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern has special significance. If a
+\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR was encountered while matching, then it is that position
+which is used as the "skip point". If no \f(CW\*(C`(*MARK)\*(C'\fR of that name was
+encountered, then the \f(CW\*(C`(*SKIP)\*(C'\fR operator has no effect. When used
+without a name the "skip point" is where the match point was when
+executing the \f(CW\*(C`(*SKIP)\*(C'\fR pattern.
+.Sp
+Compare the following to the examples in \f(CW\*(C`(*PRUNE)\*(C'\fR; note the string
+is twice as long:
+.Sp
+.Vb 2
+\& \*(Aqaaabaaab\*(Aq =~ /a+b?(*SKIP)(?{print "$&\en"; $count++})(*FAIL)/;
+\& print "Count=$count\en";
+.Ve
+.Sp
+outputs
+.Sp
+.Vb 3
+\&    aaab
+\&    aaab
+\&    Count=2
+.Ve
+.Sp
+Once the 'aaab' at the start of the string has matched, and the \f(CW\*(C`(*SKIP)\*(C'\fR
+executed, the next starting point will be where the cursor was when the
+\&\f(CW\*(C`(*SKIP)\*(C'\fR was executed.
+.ie n .IP """(*MARK:\fINAME\fR)"" ""(*:\fINAME\fR)""" 4
+.el .IP "\f(CW(*MARK:\fR\f(CINAME\fR\f(CW)\fR \f(CW(*:\fR\f(CINAME\fR\f(CW)\fR" 4
+.IX Xref "(*MARK) (*MARK:NAME) (*:NAME)"
+.IX Item "(*MARK:NAME) (*:NAME)"
+This zero-width pattern can be used to mark the point reached in a string
+when a certain part of the pattern has been successfully matched. This
+mark may be given a name. A later \f(CW\*(C`(*SKIP)\*(C'\fR pattern will then skip
+forward to that point if backtracked into on failure. Any number of
+\&\f(CW\*(C`(*MARK)\*(C'\fR patterns are allowed, and the \fINAME\fR portion may be duplicated.
+.Sp
+In addition to interacting with the \f(CW\*(C`(*SKIP)\*(C'\fR pattern, \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR
+can be used to "label" a pattern branch, so that after matching, the
+program can determine which branches of the pattern were involved in the
+match.
+.Sp
+When a match is successful, the \f(CW$REGMARK\fR variable will be set to the
+name of the most recently executed \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR that was involved
+in the match.
+.Sp
+This can be used to determine which branch of a pattern was matched
+without using a separate capture group for each branch, which in turn
+can result in a performance improvement, as perl cannot optimize
+\&\f(CW\*(C`/(?:(x)|(y)|(z))/\*(C'\fR as efficiently as something like
+\&\f(CW\*(C`/(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/\*(C'\fR.
+.Sp
+When a match has failed, and unless another verb has been involved in
+failing the match and has provided its own name to use, the \f(CW$REGERROR\fR
+variable will be set to the name of the most recently executed
+\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR.
+.Sp
+See "(*SKIP)" for more details.
+.Sp
+As a shortcut \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR can be written \f(CW\*(C`(*:\fR\f(CINAME\fR\f(CW)\*(C'\fR.
+.ie n .IP """(*THEN)"" ""(*THEN:\fINAME\fR)""" 4
+.el .IP "\f(CW(*THEN)\fR \f(CW(*THEN:\fR\f(CINAME\fR\f(CW)\fR" 4
+.IX Item "(*THEN) (*THEN:NAME)"
+This is similar to the "cut group" operator \f(CW\*(C`::\*(C'\fR from Raku.  Like
+\&\f(CW\*(C`(*PRUNE)\*(C'\fR, this verb always matches, and when backtracked into on
+failure, it causes the regex engine to try the next alternation in the
+innermost enclosing group (capturing or otherwise) that has alternations.
+The two branches of a \f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\*(C'\fR do not
+count as an alternation, as far as \f(CW\*(C`(*THEN)\*(C'\fR is concerned.
+.Sp
+Its name comes from the observation that this operation combined with the
+alternation operator (\f(CW"|"\fR) can be used to create what is essentially a
+pattern-based if/then/else block:
+.Sp
+.Vb 1
+\&  ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ )
+.Ve
+.Sp
+Note that if this operator is used and NOT inside of an alternation then
+it acts exactly like the \f(CW\*(C`(*PRUNE)\*(C'\fR operator.
+.Sp
+.Vb 1
+\&  / A (*PRUNE) B /
+.Ve
+.Sp
+is the same as
+.Sp
+.Vb 1
+\&  / A (*THEN) B /
+.Ve
+.Sp
+but
+.Sp
+.Vb 1
+\&  / ( A (*THEN) B | C ) /
+.Ve
+.Sp
+is not the same as
+.Sp
+.Vb 1
+\&  / ( A (*PRUNE) B | C ) /
+.Ve
+.Sp
+as after matching the \fIA\fR but failing on the \fIB\fR the \f(CW\*(C`(*THEN)\*(C'\fR verb will
+backtrack and try \fIC\fR; but the \f(CW\*(C`(*PRUNE)\*(C'\fR verb will simply fail.
+.ie n .IP """(*COMMIT)"" ""(*COMMIT:\fIarg\fR)""" 4
+.el .IP "\f(CW(*COMMIT)\fR \f(CW(*COMMIT:\fR\f(CIarg\fR\f(CW)\fR" 4
+.IX Xref "(*COMMIT)"
+.IX Item "(*COMMIT) (*COMMIT:arg)"
+This is the Raku "commit pattern" \f(CW\*(C`<commit>\*(C'\fR or \f(CW\*(C`:::\*(C'\fR. It's a
+zero-width pattern similar to \f(CW\*(C`(*SKIP)\*(C'\fR, except that when backtracked
+into on failure it causes the match to fail outright. No further attempts
+to find a valid match by advancing the start pointer will occur again.
+For example,
+.Sp
+.Vb 2
+\& \*(Aqaaabaaab\*(Aq =~ /a+b?(*COMMIT)(?{print "$&\en"; $count++})(*FAIL)/;
+\& print "Count=$count\en";
+.Ve
+.Sp
+outputs
+.Sp
+.Vb 2
+\&    aaab
+\&    Count=1
+.Ve
+.Sp
+In other words, once the \f(CW\*(C`(*COMMIT)\*(C'\fR has been entered, and if the pattern
+does not match, the regex engine will not try any further matching on the
+rest of the string.
+.ie n .IP """(*FAIL)"" ""(*F)"" ""(*FAIL:\fIarg\fR)""" 4
+.el .IP "\f(CW(*FAIL)\fR \f(CW(*F)\fR \f(CW(*FAIL:\fR\f(CIarg\fR\f(CW)\fR" 4
+.IX Xref "(*FAIL) (*F)"
+.IX Item "(*FAIL) (*F) (*FAIL:arg)"
+This pattern matches nothing and always fails. It can be used to force the
+engine to backtrack. It is equivalent to \f(CW\*(C`(?!)\*(C'\fR, but easier to read. In
+fact, \f(CW\*(C`(?!)\*(C'\fR gets optimised into \f(CW\*(C`(*FAIL)\*(C'\fR internally. You can provide
+an argument so that if the match fails because of this \f(CW\*(C`FAIL\*(C'\fR directive
+the argument can be obtained from \f(CW$REGERROR\fR.
+.Sp
+It is probably useful only when combined with \f(CW\*(C`(?{})\*(C'\fR or \f(CW\*(C`(??{})\*(C'\fR.
+.ie n .IP """(*ACCEPT)"" ""(*ACCEPT:\fIarg\fR)""" 4
+.el .IP "\f(CW(*ACCEPT)\fR \f(CW(*ACCEPT:\fR\f(CIarg\fR\f(CW)\fR" 4
+.IX Xref "(*ACCEPT)"
+.IX Item "(*ACCEPT) (*ACCEPT:arg)"
+This pattern matches nothing and causes the end of successful matching at
+the point at which the \f(CW\*(C`(*ACCEPT)\*(C'\fR pattern was encountered, regardless of
+whether there is actually more to match in the string. When inside of a
+nested pattern, such as recursion, or in a subpattern dynamically generated
+via \f(CW\*(C`(??{})\*(C'\fR, only the innermost pattern is ended immediately.
+.Sp
+If the \f(CW\*(C`(*ACCEPT)\*(C'\fR is inside of capturing groups then the groups are
+marked as ended at the point at which the \f(CW\*(C`(*ACCEPT)\*(C'\fR was encountered.
+For instance:
+.Sp
+.Vb 1
+\&  \*(AqAB\*(Aq =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
+.Ve
+.Sp
+will match, and \f(CW$1\fR will be \f(CW\*(C`AB\*(C'\fR and \f(CW$2\fR will be \f(CW"B"\fR, \f(CW$3\fR will not
+be set. If another branch in the inner parentheses was matched, such as in the
+string 'ACDE', then the \f(CW"D"\fR and \f(CW"E"\fR would have to be matched as well.
+.Sp
+You can provide an argument, which will be available in the var
+\&\f(CW$REGMARK\fR after the match completes.
+.RE
+.RS 3
+.RE
+.ie n .SS "Warning on ""\e1"" Instead of $1"
+.el .SS "Warning on \f(CW\e1\fP Instead of \f(CW$1\fP"
+.IX Subsection "Warning on 1 Instead of $1"
+Some people get too used to writing things like:
+.PP
+.Vb 1
+\&    $pattern =~ s/(\eW)/\e\e\e1/g;
+.Ve
+.PP
+This is grandfathered (for \e1 to \e9) for the RHS of a substitute to avoid
+shocking the
+\&\fBsed\fR addicts, but it's a dirty habit to get into.  That's because in
+PerlThink, the righthand side of an \f(CW\*(C`s///\*(C'\fR is a double-quoted string.  \f(CW\*(C`\e1\*(C'\fR in
+the usual double-quoted string means a control-A.  The customary Unix
+meaning of \f(CW\*(C`\e1\*(C'\fR is kludged in for \f(CW\*(C`s///\*(C'\fR.  However, if you get into the habit
+of doing that, you get yourself into trouble if you then add an \f(CW\*(C`/e\*(C'\fR
+modifier.
+.PP
+.Vb 1
+\&    s/(\ed+)/ \e1 + 1 /eg;            # causes warning under \-w
+.Ve
+.PP
+Or if you try to do
+.PP
+.Vb 1
+\&    s/(\ed+)/\e1000/;
+.Ve
+.PP
+You can't disambiguate that by saying \f(CW\*(C`\e{1}000\*(C'\fR, whereas you can fix it with
+\&\f(CW\*(C`${1}000\*(C'\fR.  The operation of interpolation should not be confused
+with the operation of matching a backreference.  Certainly they mean two
+different things on the \fIleft\fR side of the \f(CW\*(C`s///\*(C'\fR.
+.SS "Repeated Patterns Matching a Zero-length Substring"
+.IX Subsection "Repeated Patterns Matching a Zero-length Substring"
+\&\fBWARNING\fR: Difficult material (and prose) ahead.  This section needs a rewrite.
+.PP
+Regular expressions provide a terse and powerful programming language.  As
+with most other power tools, power comes together with the ability
+to wreak havoc.
+.PP
+A common abuse of this power stems from the ability to make infinite
+loops using regular expressions, with something as innocuous as:
+.PP
+.Vb 1
+\&    \*(Aqfoo\*(Aq =~ m{ ( o? )* }x;
+.Ve
+.PP
+The \f(CW\*(C`o?\*(C'\fR matches at the beginning of "\f(CW\*(C`foo\*(C'\fR", and since the position
+in the string is not moved by the match, \f(CW\*(C`o?\*(C'\fR would match again and again
+because of the \f(CW"*"\fR quantifier.  Another common way to create a similar cycle
+is with the looping modifier \f(CW\*(C`/g\*(C'\fR:
+.PP
+.Vb 1
+\&    @matches = ( \*(Aqfoo\*(Aq =~ m{ o? }xg );
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    print "match: <$&>\en" while \*(Aqfoo\*(Aq =~ m{ o? }xg;
+.Ve
+.PP
+or the loop implied by \f(CWsplit()\fR.
+.PP
+However, long experience has shown that many programming tasks may
+be significantly simplified by using repeated subexpressions that
+may match zero-length substrings.  Here's a simple example being:
+.PP
+.Vb 2
+\&    @chars = split //, $string;           # // is not magic in split
+\&    ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
+.Ve
+.PP
+Thus Perl allows such constructs, by \fIforcefully breaking
+the infinite loop\fR.  The rules for this are different for lower-level
+loops given by the greedy quantifiers \f(CW\*(C`*+{}\*(C'\fR, and for higher-level
+ones like the \f(CW\*(C`/g\*(C'\fR modifier or \f(CWsplit()\fR operator.
+.PP
+The lower-level loops are \fIinterrupted\fR (that is, the loop is
+broken) when Perl detects that a repeated expression matched a
+zero-length substring.   Thus
+.PP
+.Vb 1
+\&   m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
+.Ve
+.PP
+is made equivalent to
+.PP
+.Vb 1
+\&   m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x;
+.Ve
+.PP
+For example, this program
+.PP
+.Vb 12
+\&   #!perl \-l
+\&   "aaaaab" =~ /
+\&     (?:
+\&        a                 # non\-zero
+\&        |                 # or
+\&       (?{print "hello"}) # print hello whenever this
+\&                          #    branch is tried
+\&       (?=(b))            # zero\-width assertion
+\&     )*  # any number of times
+\&    /x;
+\&   print $&;
+\&   print $1;
+.Ve
+.PP
+prints
+.PP
+.Vb 3
+\&   hello
+\&   aaaaa
+\&   b
+.Ve
+.PP
+Notice that "hello" is only printed once, as when Perl sees that the sixth
+iteration of the outermost \f(CW\*(C`(?:)*\*(C'\fR matches a zero-length string, it stops
+the \f(CW"*"\fR.
+.PP
+The higher-level loops preserve an additional state between iterations:
+whether the last match was zero-length.  To break the loop, the following
+match after a zero-length match is prohibited to have a length of zero.
+This prohibition interacts with backtracking (see "Backtracking"),
+and so the \fIsecond best\fR match is chosen if the \fIbest\fR match is of
+zero length.
+.PP
+For example:
+.PP
+.Vb 2
+\&    $_ = \*(Aqbar\*(Aq;
+\&    s/\ew??/<$&>/g;
+.Ve
+.PP
+results in \f(CW\*(C`<><b><><a><><r><>\*(C'\fR.  At each position of the string the best
+match given by non-greedy \f(CW\*(C`??\*(C'\fR is the zero-length match, and the \fIsecond
+best\fR match is what is matched by \f(CW\*(C`\ew\*(C'\fR.  Thus zero-length matches
+alternate with one-character-long matches.
+.PP
+Similarly, for repeated \f(CW\*(C`m/()/g\*(C'\fR the second-best match is the match at the
+position one notch further in the string.
+.PP
+The additional state of being \fImatched with zero-length\fR is associated with
+the matched string, and is reset by each assignment to \f(CWpos()\fR.
+Zero-length matches at the end of the previous match are ignored
+during \f(CW\*(C`split\*(C'\fR.
+.SS "Combining RE Pieces"
+.IX Subsection "Combining RE Pieces"
+Each of the elementary pieces of regular expressions which were described
+before (such as \f(CW\*(C`ab\*(C'\fR or \f(CW\*(C`\eZ\*(C'\fR) could match at most one substring
+at the given position of the input string.  However, in a typical regular
+expression these elementary pieces are combined into more complicated
+patterns using combining operators \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`S|T\*(C'\fR, \f(CW\*(C`S*\*(C'\fR \fIetc\fR.
+(in these examples \f(CW"S"\fR and \f(CW"T"\fR are regular subexpressions).
+.PP
+Such combinations can include alternatives, leading to a problem of choice:
+if we match a regular expression \f(CW\*(C`a|ab\*(C'\fR against \f(CW"abc"\fR, will it match
+substring \f(CW"a"\fR or \f(CW"ab"\fR?  One way to describe which substring is
+actually matched is the concept of backtracking (see "Backtracking").
+However, this description is too low-level and makes you think
+in terms of a particular implementation.
+.PP
+Another description starts with notions of "better"/"worse".  All the
+substrings which may be matched by the given regular expression can be
+sorted from the "best" match to the "worst" match, and it is the "best"
+match which is chosen.  This substitutes the question of "what is chosen?"
+by the question of "which matches are better, and which are worse?".
+.PP
+Again, for elementary pieces there is no such question, since at most
+one match at a given position is possible.  This section describes the
+notion of better/worse for combining operators.  In the description
+below \f(CW"S"\fR and \f(CW"T"\fR are regular subexpressions.
+.ie n .IP """ST""" 4
+.el .IP \f(CWST\fR 4
+.IX Item "ST"
+Consider two possible matches, \f(CW\*(C`AB\*(C'\fR and \f(CW\*(C`A\*(AqB\*(Aq\*(C'\fR, \f(CW"A"\fR and \f(CW\*(C`A\*(Aq\*(C'\fR are
+substrings which can be matched by \f(CW"S"\fR, \f(CW"B"\fR and \f(CW\*(C`B\*(Aq\*(C'\fR are substrings
+which can be matched by \f(CW"T"\fR.
+.Sp
+If \f(CW"A"\fR is a better match for \f(CW"S"\fR than \f(CW\*(C`A\*(Aq\*(C'\fR, \f(CW\*(C`AB\*(C'\fR is a better
+match than \f(CW\*(C`A\*(AqB\*(Aq\*(C'\fR.
+.Sp
+If \f(CW"A"\fR and \f(CW\*(C`A\*(Aq\*(C'\fR coincide: \f(CW\*(C`AB\*(C'\fR is a better match than \f(CW\*(C`AB\*(Aq\*(C'\fR if
+\&\f(CW"B"\fR is a better match for \f(CW"T"\fR than \f(CW\*(C`B\*(Aq\*(C'\fR.
+.ie n .IP """S|T""" 4
+.el .IP \f(CWS|T\fR 4
+.IX Item "S|T"
+When \f(CW"S"\fR can match, it is a better match than when only \f(CW"T"\fR can match.
+.Sp
+Ordering of two matches for \f(CW"S"\fR is the same as for \f(CW"S"\fR.  Similar for
+two matches for \f(CW"T"\fR.
+.ie n .IP """S{REPEAT_COUNT}""" 4
+.el .IP \f(CWS{REPEAT_COUNT}\fR 4
+.IX Item "S{REPEAT_COUNT}"
+Matches as \f(CW\*(C`SSS...S\*(C'\fR (repeated as many times as necessary).
+.ie n .IP """S{min,max}""" 4
+.el .IP \f(CWS{min,max}\fR 4
+.IX Item "S{min,max}"
+Matches as \f(CW\*(C`S{max}|S{max\-1}|...|S{min+1}|S{min}\*(C'\fR.
+.ie n .IP """S{min,max}?""" 4
+.el .IP \f(CWS{min,max}?\fR 4
+.IX Item "S{min,max}?"
+Matches as \f(CW\*(C`S{min}|S{min+1}|...|S{max\-1}|S{max}\*(C'\fR.
+.ie n .IP """S?"", ""S*"", ""S+""" 4
+.el .IP "\f(CWS?\fR, \f(CWS*\fR, \f(CWS+\fR" 4
+.IX Item "S?, S*, S+"
+Same as \f(CW\*(C`S{0,1}\*(C'\fR, \f(CW\*(C`S{0,BIG_NUMBER}\*(C'\fR, \f(CW\*(C`S{1,BIG_NUMBER}\*(C'\fR respectively.
+.ie n .IP """S??"", ""S*?"", ""S+?""" 4
+.el .IP "\f(CWS??\fR, \f(CWS*?\fR, \f(CWS+?\fR" 4
+.IX Item "S??, S*?, S+?"
+Same as \f(CW\*(C`S{0,1}?\*(C'\fR, \f(CW\*(C`S{0,BIG_NUMBER}?\*(C'\fR, \f(CW\*(C`S{1,BIG_NUMBER}?\*(C'\fR respectively.
+.ie n .IP """(?>S)""" 4
+.el .IP \f(CW(?>S)\fR 4
+.IX Item "(?>S)"
+Matches the best match for \f(CW"S"\fR and only that.
+.ie n .IP """(?=S)"", ""(?<=S)""" 4
+.el .IP "\f(CW(?=S)\fR, \f(CW(?<=S)\fR" 4
+.IX Item "(?=S), (?<=S)"
+Only the best match for \f(CW"S"\fR is considered.  (This is important only if
+\&\f(CW"S"\fR has capturing parentheses, and backreferences are used somewhere
+else in the whole regular expression.)
+.ie n .IP """(?!S)"", ""(?<!S)""" 4
+.el .IP "\f(CW(?!S)\fR, \f(CW(?<!S)\fR" 4
+.IX Item "(?!S), (?<!S)"
+For this grouping operator there is no need to describe the ordering, since
+only whether or not \f(CW"S"\fR can match is important.
+.ie n .IP """(??{ \fIEXPR\fR })"", ""(?\fIPARNO\fR)""" 4
+.el .IP "\f(CW(??{ \fR\f(CIEXPR\fR\f(CW })\fR, \f(CW(?\fR\f(CIPARNO\fR\f(CW)\fR" 4
+.IX Item "(??{ EXPR }), (?PARNO)"
+The ordering is the same as for the regular expression which is
+the result of \fIEXPR\fR, or the pattern contained by capture group \fIPARNO\fR.
+.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR|\fIno\-pattern\fR)""" 4
+.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\fR 4
+.IX Item "(?(condition)yes-pattern|no-pattern)"
+Recall that which of \fIyes-pattern\fR or \fIno-pattern\fR actually matches is
+already determined.  The ordering of the matches is the same as for the
+chosen subexpression.
+.PP
+The above recipes describe the ordering of matches \fIat a given position\fR.
+One more rule is needed to understand how a match is determined for the
+whole regular expression: a match at an earlier position is always better
+than a match at a later position.
+.SS "Creating Custom RE Engines"
+.IX Subsection "Creating Custom RE Engines"
+As of Perl 5.10.0, one can create custom regular expression engines.  This
+is not for the faint of heart, as they have to plug in at the C level.  See
+perlreapi for more details.
+.PP
+As an alternative, overloaded constants (see overload) provide a simple
+way to extend the functionality of the RE engine, by substituting one
+pattern for another.
+.PP
+Suppose that we want to enable a new RE escape-sequence \f(CW\*(C`\eY|\*(C'\fR which
+matches at a boundary between whitespace characters and non-whitespace
+characters.  Note that \f(CW\*(C`(?=\eS)(?<!\eS)|(?!\eS)(?<=\eS)\*(C'\fR matches exactly
+at these positions, so we want to have each \f(CW\*(C`\eY|\*(C'\fR in the place of the
+more complicated version.  We can create a module \f(CW\*(C`customre\*(C'\fR to do
+this:
+.PP
+.Vb 2
+\&    package customre;
+\&    use overload;
+\&
+\&    sub import {
+\&      shift;
+\&      die "No argument to customre::import allowed" if @_;
+\&      overload::constant \*(Aqqr\*(Aq => \e&convert;
+\&    }
+\&
+\&    sub invalid { die "/$_[0]/: invalid escape \*(Aq\e\e$_[1]\*(Aq"}
+\&
+\&    # We must also take care of not escaping the legitimate \e\eY|
+\&    # sequence, hence the presence of \*(Aq\e\e\*(Aq in the conversion rules.
+\&    my %rules = ( \*(Aq\e\e\*(Aq => \*(Aq\e\e\e\e\*(Aq,
+\&                  \*(AqY|\*(Aq => qr/(?=\eS)(?<!\eS)|(?!\eS)(?<=\eS)/ );
+\&    sub convert {
+\&      my $re = shift;
+\&      $re =~ s{
+\&                \e\e ( \e\e | Y . )
+\&              }
+\&              { $rules{$1} or invalid($re,$1) }sgex;
+\&      return $re;
+\&    }
+.Ve
+.PP
+Now \f(CW\*(C`use customre\*(C'\fR enables the new escape in constant regular
+expressions, \fIi.e.\fR, those without any runtime variable interpolations.
+As documented in overload, this conversion will work only over
+literal parts of regular expressions.  For \f(CW\*(C`\eY|$re\eY|\*(C'\fR the variable
+part of this regular expression needs to be converted explicitly
+(but only if the special meaning of \f(CW\*(C`\eY|\*(C'\fR should be enabled inside \f(CW$re\fR):
+.PP
+.Vb 5
+\&    use customre;
+\&    $re = <>;
+\&    chomp $re;
+\&    $re = customre::convert $re;
+\&    /\eY|$re\eY|/;
+.Ve
+.SS "Embedded Code Execution Frequency"
+.IX Subsection "Embedded Code Execution Frequency"
+The exact rules for how often \f(CW\*(C`(?{})\*(C'\fR and \f(CW\*(C`(??{})\*(C'\fR are executed in a pattern
+are unspecified, and this is even more true of \f(CW\*(C`(*{})\*(C'\fR.
+In the case of a successful match you can assume that they DWIM and
+will be executed in left to right order the appropriate number of times in the
+accepting path of the pattern as would any other meta-pattern. How non\-
+accepting pathways and match failures affect the number of times a pattern is
+executed is specifically unspecified and may vary depending on what
+optimizations can be applied to the pattern and is likely to change from
+version to version.
+.PP
+For instance in
+.PP
+.Vb 1
+\&  "aaabcdeeeee"=~/a(?{print "a"})b(?{print "b"})cde/;
+.Ve
+.PP
+the exact number of times "a" or "b" are printed out is unspecified for
+failure, but you may assume they will be printed at least once during
+a successful match, additionally you may assume that if "b" is printed,
+it will be preceded by at least one "a".
+.PP
+In the case of branching constructs like the following:
+.PP
+.Vb 1
+\&  /a(b|(?{ print "a" }))c(?{ print "c" })/;
+.Ve
+.PP
+you can assume that the input "ac" will output "ac", and that "abc"
+will output only "c".
+.PP
+When embedded code is quantified, successful matches will call the
+code once for each matched iteration of the quantifier.  For
+example:
+.PP
+.Vb 1
+\&  "good" =~ /g(?:o(?{print "o"}))*d/;
+.Ve
+.PP
+will output "o" twice.
+.PP
+For historical and consistency reasons the use of normal code blocks
+anywhere in a pattern will disable certain optimisations. As of 5.37.7
+you can use an "optimistic" codeblock, \f(CW\*(C`(*{ ... })\*(C'\fR as a replacement
+for \f(CW\*(C`(?{ ... })\*(C'\fR, if you do *not* wish to disable these optimisations.
+This may result in the code block being called less often than it might
+have been had they not been optimistic.
+.SS "PCRE/Python Support"
+.IX Subsection "PCRE/Python Support"
+As of Perl 5.10.0, Perl supports several Python/PCRE\-specific extensions
+to the regex syntax. While Perl programmers are encouraged to use the
+Perl-specific syntax, the following are also accepted:
+.ie n .IP """(?P<\fINAME\fR>\fIpattern\fR)""" 4
+.el .IP \f(CW(?P<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\fR 4
+.IX Item "(?P<NAME>pattern)"
+Define a named capture group. Equivalent to \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR.
+.ie n .IP """(?P=\fINAME\fR)""" 4
+.el .IP \f(CW(?P=\fR\f(CINAME\fR\f(CW)\fR 4
+.IX Item "(?P=NAME)"
+Backreference to a named capture group. Equivalent to \f(CW\*(C`\eg{\fR\f(CINAME\fR\f(CW}\*(C'\fR.
+.ie n .IP """(?P>\fINAME\fR)""" 4
+.el .IP \f(CW(?P>\fR\f(CINAME\fR\f(CW)\fR 4
+.IX Item "(?P>NAME)"
+Subroutine call to a named capture group. Equivalent to \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR.
+.SH BUGS
+.IX Header "BUGS"
+There are a number of issues with regard to case-insensitive matching
+in Unicode rules.  See \f(CW"i"\fR under "Modifiers" above.
+.PP
+This document varies from difficult to understand to completely
+and utterly opaque.  The wandering prose riddled with jargon is
+hard to fathom in several places.
+.PP
+This document needs a rewrite that separates the tutorial content
+from the reference content.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The syntax of patterns used in Perl pattern matching evolved from those
+supplied in the Bell Labs Research Unix 8th Edition (Version 8) regex
+routines.  (The code is actually derived (distantly) from Henry
+Spencer's freely redistributable reimplementation of those V8 routines.)
+.PP
+perlrequick.
+.PP
+perlretut.
+.PP
+"Regexp Quote-Like Operators" in perlop.
+.PP
+"Gory details of parsing quoted constructs" in perlop.
+.PP
+perlfaq6.
+.PP
+"pos" in perlfunc.
+.PP
+perllocale.
+.PP
+perlebcdic.
+.PP
+\&\fIMastering Regular Expressions\fR by Jeffrey Friedl, published
+by O'Reilly and Associates.
diff --git a/upstream/mageia-cauldron/man1/perlreapi.1 b/upstream/mageia-cauldron/man1/perlreapi.1
new file mode 100644
index 00000000..00c33c40
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlreapi.1
@@ -0,0 +1,925 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREAPI 1"
+.TH PERLREAPI 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlreapi \- Perl regular expression plugin interface
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+As of Perl 5.9.5 there is a new interface for plugging and using
+regular expression engines other than the default one.
+.PP
+Each engine is supposed to provide access to a constant structure of the
+following format:
+.PP
+.Vb 10
+\&    typedef struct regexp_engine {
+\&        REGEXP* (*comp) (pTHX_
+\&                         const SV * const pattern, const U32 flags);
+\&        I32     (*exec) (pTHX_
+\&                         REGEXP * const rx,
+\&                         char* stringarg,
+\&                         char* strend, char* strbeg,
+\&                         SSize_t minend, SV* sv,
+\&                         void* data, U32 flags);
+\&        char*   (*intuit) (pTHX_
+\&                           REGEXP * const rx, SV *sv,
+\&                           const char * const strbeg,
+\&                           char *strpos, char *strend, U32 flags,
+\&                           struct re_scream_pos_data_s *data);
+\&        SV*     (*checkstr) (pTHX_ REGEXP * const rx);
+\&        void    (*free) (pTHX_ REGEXP * const rx);
+\&        void    (*numbered_buff_FETCH) (pTHX_
+\&                                        REGEXP * const rx,
+\&                                        const I32 paren,
+\&                                        SV * const sv);
+\&        void    (*numbered_buff_STORE) (pTHX_
+\&                                        REGEXP * const rx,
+\&                                        const I32 paren,
+\&                                        SV const * const value);
+\&        I32     (*numbered_buff_LENGTH) (pTHX_
+\&                                         REGEXP * const rx,
+\&                                         const SV * const sv,
+\&                                         const I32 paren);
+\&        SV*     (*named_buff) (pTHX_
+\&                               REGEXP * const rx,
+\&                               SV * const key,
+\&                               SV * const value,
+\&                               U32 flags);
+\&        SV*     (*named_buff_iter) (pTHX_
+\&                                    REGEXP * const rx,
+\&                                    const SV * const lastkey,
+\&                                    const U32 flags);
+\&        SV*     (*qr_package)(pTHX_ REGEXP * const rx);
+\&    #ifdef USE_ITHREADS
+\&        void*   (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
+\&    #endif
+\&        REGEXP* (*op_comp) (...);
+.Ve
+.PP
+When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at
+the appropriate structure, so that when it needs to be used Perl can find
+the right routines to do so.
+.PP
+In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set
+to an integer which (when casted appropriately) resolves to one of these
+structures.  When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the
+resulting \f(CW\*(C`regexp\*(C'\fR structure's engine field is expected to point back at
+the same structure.
+.PP
+The pTHX_ symbol in the definition is a macro used by Perl under threading
+to provide an extra argument to the routine holding a pointer back to
+the interpreter that is executing the regexp. So under threading all
+routines get an extra argument.
+.SH Callbacks
+.IX Header "Callbacks"
+.SS comp
+.IX Subsection "comp"
+.Vb 1
+\&    REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);
+.Ve
+.PP
+Compile the pattern stored in \f(CW\*(C`pattern\*(C'\fR using the given \f(CW\*(C`flags\*(C'\fR and
+return a pointer to a prepared \f(CW\*(C`REGEXP\*(C'\fR structure that can perform
+the match.  See "The REGEXP structure" below for an explanation of
+the individual fields in the REGEXP struct.
+.PP
+The \f(CW\*(C`pattern\*(C'\fR parameter is the scalar that was used as the
+pattern.  Previous versions of Perl would pass two \f(CW\*(C`char*\*(C'\fR indicating
+the start and end of the stringified pattern; the following snippet can
+be used to get the old parameters:
+.PP
+.Vb 3
+\&    STRLEN plen;
+\&    char*  exp = SvPV(pattern, plen);
+\&    char* xend = exp + plen;
+.Ve
+.PP
+Since any scalar can be passed as a pattern, it's possible to implement
+an engine that does something with an array (\f(CW\*(C`"ook" =~ [ qw/ eek
+hlagh / ]\*(C'\fR) or with the non-stringified form of a compiled regular
+expression (\f(CW\*(C`"ook" =~ qr/eek/\*(C'\fR).  Perl's own engine will always
+stringify everything using the snippet above, but that doesn't mean
+other engines have to.
+.PP
+The \f(CW\*(C`flags\*(C'\fR parameter is a bitfield which indicates which of the
+\&\f(CW\*(C`msixpn\*(C'\fR flags the regex was compiled with.  It also contains
+additional info, such as if \f(CW\*(C`use locale\*(C'\fR is in effect.
+.PP
+The \f(CW\*(C`eogc\*(C'\fR flags are stripped out before being passed to the comp
+routine.  The regex engine does not need to know if any of these
+are set, as those flags should only affect what Perl does with the
+pattern and its match variables, not how it gets compiled and
+executed.
+.PP
+By the time the comp callback is called, some of these flags have
+already had effect (noted below where applicable).  However most of
+their effect occurs after the comp callback has run, in routines that
+read the \f(CW\*(C`rx\->extflags\*(C'\fR field which it populates.
+.PP
+In general the flags should be preserved in \f(CW\*(C`rx\->extflags\*(C'\fR after
+compilation, although the regex engine might want to add or delete
+some of them to invoke or disable some special behavior in Perl.  The
+flags along with any special behavior they cause are documented below:
+.PP
+The pattern modifiers:
+.ie n .IP """/m"" \- RXf_PMf_MULTILINE" 4
+.el .IP "\f(CW/m\fR \- RXf_PMf_MULTILINE" 4
+.IX Item "/m - RXf_PMf_MULTILINE"
+If this is in \f(CW\*(C`rx\->extflags\*(C'\fR it will be passed to
+\&\f(CW\*(C`Perl_fbm_instr\*(C'\fR by \f(CW\*(C`pp_split\*(C'\fR which will treat the subject string
+as a multi-line string.
+.ie n .IP """/s"" \- RXf_PMf_SINGLELINE" 4
+.el .IP "\f(CW/s\fR \- RXf_PMf_SINGLELINE" 4
+.IX Item "/s - RXf_PMf_SINGLELINE"
+.PD 0
+.ie n .IP """/i"" \- RXf_PMf_FOLD" 4
+.el .IP "\f(CW/i\fR \- RXf_PMf_FOLD" 4
+.IX Item "/i - RXf_PMf_FOLD"
+.ie n .IP """/x"" \- RXf_PMf_EXTENDED" 4
+.el .IP "\f(CW/x\fR \- RXf_PMf_EXTENDED" 4
+.IX Item "/x - RXf_PMf_EXTENDED"
+.PD
+If present on a regex, \f(CW"#"\fR comments will be handled differently by the
+tokenizer in some cases.
+.Sp
+TODO: Document those cases.
+.ie n .IP """/p"" \- RXf_PMf_KEEPCOPY" 4
+.el .IP "\f(CW/p\fR \- RXf_PMf_KEEPCOPY" 4
+.IX Item "/p - RXf_PMf_KEEPCOPY"
+TODO: Document this
+.IP "Character set" 4
+.IX Item "Character set"
+The character set rules are determined by an enum that is contained
+in this field.  This is still experimental and subject to change, but
+the current interface returns the rules by use of the in-line function
+\&\f(CW\*(C`get_regex_charset(const U32 flags)\*(C'\fR.  The only currently documented
+value returned from it is REGEX_LOCALE_CHARSET, which is set if
+\&\f(CW\*(C`use locale\*(C'\fR is in effect. If present in \f(CW\*(C`rx\->extflags\*(C'\fR,
+\&\f(CW\*(C`split\*(C'\fR will use the locale dependent definition of whitespace
+when RXf_SKIPWHITE or RXf_WHITE is in effect.  ASCII whitespace
+is defined as per isSPACE, and by the internal
+macros \f(CW\*(C`is_utf8_space\*(C'\fR under UTF\-8, and \f(CW\*(C`isSPACE_LC\*(C'\fR under \f(CW\*(C`use
+locale\*(C'\fR.
+.PP
+Additional flags:
+.IP RXf_SPLIT 4
+.IX Item "RXf_SPLIT"
+This flag was removed in perl 5.18.0.  \f(CW\*(C`split \*(Aq \*(Aq\*(C'\fR is now special-cased
+solely in the parser.  RXf_SPLIT is still #defined, so you can test for it.
+This is how it used to work:
+.Sp
+If \f(CW\*(C`split\*(C'\fR is invoked as \f(CW\*(C`split \*(Aq \*(Aq\*(C'\fR or with no arguments (which
+really means \f(CW\*(C`split(\*(Aq \*(Aq, $_)\*(C'\fR, see split), Perl will
+set this flag.  The regex engine can then check for it and set the
+SKIPWHITE and WHITE extflags.  To do this, the Perl engine does:
+.Sp
+.Vb 2
+\&    if (flags & RXf_SPLIT && r\->prelen == 1 && r\->precomp[0] == \*(Aq \*(Aq)
+\&        r\->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
+.Ve
+.PP
+These flags can be set during compilation to enable optimizations in
+the \f(CW\*(C`split\*(C'\fR operator.
+.IP RXf_SKIPWHITE 4
+.IX Item "RXf_SKIPWHITE"
+This flag was removed in perl 5.18.0.  It is still #defined, so you can
+set it, but doing so will have no effect.  This is how it used to work:
+.Sp
+If the flag is present in \f(CW\*(C`rx\->extflags\*(C'\fR \f(CW\*(C`split\*(C'\fR will delete
+whitespace from the start of the subject string before it's operated
+on.  What is considered whitespace depends on if the subject is a
+UTF\-8 string and if the \f(CW\*(C`RXf_PMf_LOCALE\*(C'\fR flag is set.
+.Sp
+If RXf_WHITE is set in addition to this flag, \f(CW\*(C`split\*(C'\fR will behave like
+\&\f(CW\*(C`split " "\*(C'\fR under the Perl engine.
+.IP RXf_START_ONLY 4
+.IX Item "RXf_START_ONLY"
+Tells the split operator to split the target string on newlines
+(\f(CW\*(C`\en\*(C'\fR) without invoking the regex engine.
+.Sp
+Perl's engine sets this if the pattern is \f(CW\*(C`/^/\*(C'\fR (\f(CW\*(C`plen == 1 && *exp
+== \*(Aq^\*(Aq\*(C'\fR), even under \f(CW\*(C`/^/s\*(C'\fR; see split.  Of course a
+different regex engine might want to use the same optimizations
+with a different syntax.
+.IP RXf_WHITE 4
+.IX Item "RXf_WHITE"
+Tells the split operator to split the target string on whitespace
+without invoking the regex engine.  The definition of whitespace varies
+depending on if the target string is a UTF\-8 string and on
+if RXf_PMf_LOCALE is set.
+.Sp
+Perl's engine sets this flag if the pattern is \f(CW\*(C`\es+\*(C'\fR.
+.IP RXf_NULL 4
+.IX Item "RXf_NULL"
+Tells the split operator to split the target string on
+characters.  The definition of character varies depending on if
+the target string is a UTF\-8 string.
+.Sp
+Perl's engine sets this flag on empty patterns, this optimization
+makes \f(CW\*(C`split //\*(C'\fR much faster than it would otherwise be.  It's even
+faster than \f(CW\*(C`unpack\*(C'\fR.
+.IP RXf_NO_INPLACE_SUBST 4
+.IX Item "RXf_NO_INPLACE_SUBST"
+Added in perl 5.18.0, this flag indicates that a regular expression might
+perform an operation that would interfere with inplace substitution. For
+instance it might contain lookbehind, or assign to non-magical variables
+(such as \f(CW$REGMARK\fR and \f(CW$REGERROR\fR) during matching.  \f(CW\*(C`s///\*(C'\fR will skip
+certain optimisations when this is set.
+.SS exec
+.IX Subsection "exec"
+.Vb 4
+\&    I32 exec(pTHX_ REGEXP * const rx,
+\&             char *stringarg, char* strend, char* strbeg,
+\&             SSize_t minend, SV* sv,
+\&             void* data, U32 flags);
+.Ve
+.PP
+Execute a regexp. The arguments are
+.IP rx 4
+.IX Item "rx"
+The regular expression to execute.
+.IP sv 4
+.IX Item "sv"
+This is the SV to be matched against.  Note that the
+actual char array to be matched against is supplied by the arguments
+described below; the SV is just used to determine UTF8ness, \f(CWpos()\fR etc.
+.IP strbeg 4
+.IX Item "strbeg"
+Pointer to the physical start of the string.
+.IP strend 4
+.IX Item "strend"
+Pointer to the character following the physical end of the string (i.e.
+the \f(CW\*(C`\e0\*(C'\fR, if any).
+.IP stringarg 4
+.IX Item "stringarg"
+Pointer to the position in the string where matching should start; it might
+not be equal to \f(CW\*(C`strbeg\*(C'\fR (for example in a later iteration of \f(CW\*(C`/.../g\*(C'\fR).
+.IP minend 4
+.IX Item "minend"
+Minimum length of string (measured in bytes from \f(CW\*(C`stringarg\*(C'\fR) that must
+match; if the engine reaches the end of the match but hasn't reached this
+position in the string, it should fail.
+.IP data 4
+.IX Item "data"
+Optimisation data; subject to change.
+.IP flags 4
+.IX Item "flags"
+Optimisation flags; subject to change.
+.SS intuit
+.IX Subsection "intuit"
+.Vb 8
+\&    char* intuit(pTHX_
+\&                REGEXP * const rx,
+\&                SV *sv,
+\&                const char * const strbeg,
+\&                char *strpos,
+\&                char *strend,
+\&                const U32 flags,
+\&                struct re_scream_pos_data_s *data);
+.Ve
+.PP
+Find the start position where a regex match should be attempted,
+or possibly if the regex engine should not be run because the
+pattern can't match.  This is called, as appropriate, by the core,
+depending on the values of the \f(CW\*(C`extflags\*(C'\fR member of the \f(CW\*(C`regexp\*(C'\fR
+structure.
+.PP
+Arguments:
+.PP
+.Vb 11
+\&    rx:     the regex to match against
+\&    sv:     the SV being matched: only used for utf8 flag; the string
+\&            itself is accessed via the pointers below. Note that on
+\&            something like an overloaded SV, SvPOK(sv) may be false
+\&            and the string pointers may point to something unrelated to
+\&            the SV itself.
+\&    strbeg: real beginning of string
+\&    strpos: the point in the string at which to begin matching
+\&    strend: pointer to the byte following the last char of the string
+\&    flags   currently unused; set to 0
+\&    data:   currently unused; set to NULL
+.Ve
+.SS checkstr
+.IX Subsection "checkstr"
+.Vb 1
+\&    SV* checkstr(pTHX_ REGEXP * const rx);
+.Ve
+.PP
+Return a SV containing a string that must appear in the pattern. Used
+by \f(CW\*(C`split\*(C'\fR for optimising matches.
+.SS free
+.IX Subsection "free"
+.Vb 1
+\&    void free(pTHX_ REGEXP * const rx);
+.Ve
+.PP
+Called by Perl when it is freeing a regexp pattern so that the engine
+can release any resources pointed to by the \f(CW\*(C`pprivate\*(C'\fR member of the
+\&\f(CW\*(C`regexp\*(C'\fR structure.  This is only responsible for freeing private data;
+Perl will handle releasing anything else contained in the \f(CW\*(C`regexp\*(C'\fR structure.
+.SS "Numbered capture callbacks"
+.IX Subsection "Numbered capture callbacks"
+Called to get/set the value of \f(CW\*(C`$\`\*(C'\fR, \f(CW\*(C`$\*(Aq\*(C'\fR, \f(CW$&\fR and their named
+equivalents, ${^PREMATCH}, ${^POSTMATCH} and ${^MATCH}, as well as the
+numbered capture groups (\f(CW$1\fR, \f(CW$2\fR, ...).
+.PP
+The \f(CW\*(C`paren\*(C'\fR parameter will be \f(CW1\fR for \f(CW$1\fR, \f(CW2\fR for \f(CW$2\fR and so
+forth, and have these symbolic values for the special variables:
+.PP
+.Vb 6
+\&    ${^PREMATCH}  RX_BUFF_IDX_CARET_PREMATCH
+\&    ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
+\&    ${^MATCH}     RX_BUFF_IDX_CARET_FULLMATCH
+\&    $\`            RX_BUFF_IDX_PREMATCH
+\&    $\*(Aq            RX_BUFF_IDX_POSTMATCH
+\&    $&            RX_BUFF_IDX_FULLMATCH
+.Ve
+.PP
+Note that in Perl 5.17.3 and earlier, the last three constants were also
+used for the caret variants of the variables.
+.PP
+The names have been chosen by analogy with Tie::Scalar methods
+names with an additional \fBLENGTH\fR callback for efficiency.  However
+named capture variables are currently not tied internally but
+implemented via magic.
+.PP
+\fInumbered_buff_FETCH\fR
+.IX Subsection "numbered_buff_FETCH"
+.PP
+.Vb 2
+\&    void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
+\&                             SV * const sv);
+.Ve
+.PP
+Fetch a specified numbered capture.  \f(CW\*(C`sv\*(C'\fR should be set to the scalar
+to return, the scalar is passed as an argument rather than being
+returned from the function because when it's called Perl already has a
+scalar to store the value, creating another one would be
+redundant.  The scalar can be set with \f(CW\*(C`sv_setsv\*(C'\fR, \f(CW\*(C`sv_setpvn\*(C'\fR and
+friends, see perlapi.
+.PP
+This callback is where Perl untaints its own capture variables under
+taint mode (see perlsec).  See the \f(CW\*(C`Perl_reg_numbered_buff_fetch\*(C'\fR
+function in \fIregcomp.c\fR for how to untaint capture variables if
+that's something you'd like your engine to do as well.
+.PP
+\fInumbered_buff_STORE\fR
+.IX Subsection "numbered_buff_STORE"
+.PP
+.Vb 4
+\&    void    (*numbered_buff_STORE) (pTHX_
+\&                                    REGEXP * const rx,
+\&                                    const I32 paren,
+\&                                    SV const * const value);
+.Ve
+.PP
+Set the value of a numbered capture variable.  \f(CW\*(C`value\*(C'\fR is the scalar
+that is to be used as the new value.  It's up to the engine to make
+sure this is used as the new value (or reject it).
+.PP
+Example:
+.PP
+.Vb 4
+\&    if ("ook" =~ /(o*)/) {
+\&        # \*(Aqparen\*(Aq will be \*(Aq1\*(Aq and \*(Aqvalue\*(Aq will be \*(Aqee\*(Aq
+\&        $1 =~ tr/o/e/;
+\&    }
+.Ve
+.PP
+Perl's own engine will croak on any attempt to modify the capture
+variables, to do this in another engine use the following callback
+(copied from \f(CW\*(C`Perl_reg_numbered_buff_store\*(C'\fR):
+.PP
+.Vb 9
+\&    void
+\&    Example_reg_numbered_buff_store(pTHX_
+\&                                    REGEXP * const rx,
+\&                                    const I32 paren,
+\&                                    SV const * const value)
+\&    {
+\&        PERL_UNUSED_ARG(rx);
+\&        PERL_UNUSED_ARG(paren);
+\&        PERL_UNUSED_ARG(value);
+\&
+\&        if (!PL_localizing)
+\&            Perl_croak(aTHX_ PL_no_modify);
+\&    }
+.Ve
+.PP
+Actually Perl will not \fIalways\fR croak in a statement that looks
+like it would modify a numbered capture variable.  This is because the
+STORE callback will not be called if Perl can determine that it
+doesn't have to modify the value.  This is exactly how tied variables
+behave in the same situation:
+.PP
+.Vb 2
+\&    package CaptureVar;
+\&    use parent \*(AqTie::Scalar\*(Aq;
+\&
+\&    sub TIESCALAR { bless [] }
+\&    sub FETCH { undef }
+\&    sub STORE { die "This doesn\*(Aqt get called" }
+\&
+\&    package main;
+\&
+\&    tie my $sv => "CaptureVar";
+\&    $sv =~ y/a/b/;
+.Ve
+.PP
+Because \f(CW$sv\fR is \f(CW\*(C`undef\*(C'\fR when the \f(CW\*(C`y///\*(C'\fR operator is applied to it,
+the transliteration won't actually execute and the program won't
+\&\f(CW\*(C`die\*(C'\fR.  This is different to how 5.8 and earlier versions behaved
+since the capture variables were READONLY variables then; now they'll
+just die when assigned to in the default engine.
+.PP
+\fInumbered_buff_LENGTH\fR
+.IX Subsection "numbered_buff_LENGTH"
+.PP
+.Vb 4
+\&    I32 numbered_buff_LENGTH (pTHX_
+\&                              REGEXP * const rx,
+\&                              const SV * const sv,
+\&                              const I32 paren);
+.Ve
+.PP
+Get the \f(CW\*(C`length\*(C'\fR of a capture variable.  There's a special callback
+for this so that Perl doesn't have to do a FETCH and run \f(CW\*(C`length\*(C'\fR on
+the result, since the length is (in Perl's case) known from an offset
+stored in \f(CW\*(C`rx\->offs\*(C'\fR, this is much more efficient:
+.PP
+.Vb 3
+\&    I32 s1  = rx\->offs[paren].start;
+\&    I32 s2  = rx\->offs[paren].end;
+\&    I32 len = t1 \- s1;
+.Ve
+.PP
+This is a little bit more complex in the case of UTF\-8, see what
+\&\f(CW\*(C`Perl_reg_numbered_buff_length\*(C'\fR does with
+is_utf8_string_loclen.
+.SS "Named capture callbacks"
+.IX Subsection "Named capture callbacks"
+Called to get/set the value of \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR, as well as by some
+utility functions in re.
+.PP
+There are two callbacks, \f(CW\*(C`named_buff\*(C'\fR is called in all the cases the
+FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR Tie::Hash callbacks
+would be on changes to \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`named_buff_iter\*(C'\fR in the
+same cases as FIRSTKEY and NEXTKEY.
+.PP
+The \f(CW\*(C`flags\*(C'\fR parameter can be used to determine which of these
+operations the callbacks should respond to.  The following flags are
+currently defined:
+.PP
+Which Tie::Hash operation is being performed from the Perl level on
+\&\f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%+\*(C'\fR, if any:
+.PP
+.Vb 8
+\&    RXapif_FETCH
+\&    RXapif_STORE
+\&    RXapif_DELETE
+\&    RXapif_CLEAR
+\&    RXapif_EXISTS
+\&    RXapif_SCALAR
+\&    RXapif_FIRSTKEY
+\&    RXapif_NEXTKEY
+.Ve
+.PP
+If \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR is being operated on, if any.
+.PP
+.Vb 2
+\&    RXapif_ONE /* %+ */
+\&    RXapif_ALL /* %\- */
+.Ve
+.PP
+If this is being called as \f(CW\*(C`re::regname\*(C'\fR, \f(CW\*(C`re::regnames\*(C'\fR or
+\&\f(CW\*(C`re::regnames_count\*(C'\fR, if any.  The first two will be combined with
+\&\f(CW\*(C`RXapif_ONE\*(C'\fR or \f(CW\*(C`RXapif_ALL\*(C'\fR.
+.PP
+.Vb 3
+\&    RXapif_REGNAME
+\&    RXapif_REGNAMES
+\&    RXapif_REGNAMES_COUNT
+.Ve
+.PP
+Internally \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR are implemented with a real tied interface
+via Tie::Hash::NamedCapture.  The methods in that package will call
+back into these functions.  However the usage of
+Tie::Hash::NamedCapture for this purpose might change in future
+releases.  For instance this might be implemented by magic instead
+(would need an extension to mgvtbl).
+.PP
+\fInamed_buff\fR
+.IX Subsection "named_buff"
+.PP
+.Vb 2
+\&    SV*     (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
+\&                           SV * const value, U32 flags);
+.Ve
+.PP
+\fInamed_buff_iter\fR
+.IX Subsection "named_buff_iter"
+.PP
+.Vb 4
+\&    SV*     (*named_buff_iter) (pTHX_
+\&                                REGEXP * const rx,
+\&                                const SV * const lastkey,
+\&                                const U32 flags);
+.Ve
+.SS qr_package
+.IX Subsection "qr_package"
+.Vb 1
+\&    SV* qr_package(pTHX_ REGEXP * const rx);
+.Ve
+.PP
+The package the qr// magic object is blessed into (as seen by \f(CW\*(C`ref
+qr//\*(C'\fR).  It is recommended that engines change this to their package
+name for identification regardless of if they implement methods
+on the object.
+.PP
+The package this method returns should also have the internal
+\&\f(CW\*(C`Regexp\*(C'\fR package in its \f(CW@ISA\fR.  \f(CW\*(C`qr//\->isa("Regexp")\*(C'\fR should always
+be true regardless of what engine is being used.
+.PP
+Example implementation might be:
+.PP
+.Vb 6
+\&    SV*
+\&    Example_qr_package(pTHX_ REGEXP * const rx)
+\&    {
+\&        PERL_UNUSED_ARG(rx);
+\&        return newSVpvs("re::engine::Example");
+\&    }
+.Ve
+.PP
+Any method calls on an object created with \f(CW\*(C`qr//\*(C'\fR will be dispatched to the
+package as a normal object.
+.PP
+.Vb 3
+\&    use re::engine::Example;
+\&    my $re = qr//;
+\&    $re\->meth; # dispatched to re::engine::Example::meth()
+.Ve
+.PP
+To retrieve the \f(CW\*(C`REGEXP\*(C'\fR object from the scalar in an XS function use
+the \f(CW\*(C`SvRX\*(C'\fR macro, see "REGEXP Functions" in perlapi.
+.PP
+.Vb 3
+\&    void meth(SV * rv)
+\&    PPCODE:
+\&        REGEXP * re = SvRX(sv);
+.Ve
+.SS dupe
+.IX Subsection "dupe"
+.Vb 1
+\&    void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
+.Ve
+.PP
+On threaded builds a regexp may need to be duplicated so that the pattern
+can be used by multiple threads.  This routine is expected to handle the
+duplication of any private data pointed to by the \f(CW\*(C`pprivate\*(C'\fR member of
+the \f(CW\*(C`regexp\*(C'\fR structure.  It will be called with the preconstructed new
+\&\f(CW\*(C`regexp\*(C'\fR structure as an argument, the \f(CW\*(C`pprivate\*(C'\fR member will point at
+the \fBold\fR private structure, and it is this routine's responsibility to
+construct a copy and return a pointer to it (which Perl will then use to
+overwrite the field as passed to this routine.)
+.PP
+This allows the engine to dupe its private data but also if necessary
+modify the final structure if it really must.
+.PP
+On unthreaded builds this field doesn't exist.
+.SS op_comp
+.IX Subsection "op_comp"
+This is private to the Perl core and subject to change. Should be left
+null.
+.SH "The REGEXP structure"
+.IX Header "The REGEXP structure"
+The REGEXP struct is defined in \fIregexp.h\fR.
+All regex engines must be able to
+correctly build such a structure in their "comp" routine.
+.PP
+The REGEXP structure contains all the data that Perl needs to be aware of
+to properly work with the regular expression.  It includes data about
+optimisations that Perl can use to determine if the regex engine should
+really be used, and various other control info that is needed to properly
+execute patterns in various contexts, such as if the pattern anchored in
+some way, or what flags were used during the compile, or if the
+program contains special constructs that Perl needs to be aware of.
+.PP
+In addition it contains two fields that are intended for the private
+use of the regex engine that compiled the pattern.  These are the
+\&\f(CW\*(C`intflags\*(C'\fR and \f(CW\*(C`pprivate\*(C'\fR members.  \f(CW\*(C`pprivate\*(C'\fR is a void pointer to
+an arbitrary structure, whose use and management is the responsibility
+of the compiling engine.  Perl will never modify either of these
+values.
+.PP
+.Vb 3
+\&    typedef struct regexp {
+\&        /* what engine created this regexp? */
+\&        const struct regexp_engine* engine;
+\&
+\&        /* what re is this a lightweight copy of? */
+\&        struct regexp* mother_re;
+\&
+\&        /* Information about the match that the Perl core uses to manage
+\&         * things */
+\&        U32 extflags;   /* Flags used both externally and internally */
+\&        I32 minlen;     /* mininum possible number of chars in */
+\&                           string to match */
+\&        I32 minlenret;  /* mininum possible number of chars in $& */
+\&        U32 gofs;       /* chars left of pos that we search from */
+\&
+\&        /* substring data about strings that must appear
+\&           in the final match, used for optimisations */
+\&        struct reg_substr_data *substrs;
+\&
+\&        U32 nparens;  /* number of capture groups */
+\&
+\&        /* private engine specific data */
+\&        U32 intflags;   /* Engine Specific Internal flags */
+\&        void *pprivate; /* Data private to the regex engine which 
+\&                           created this object. */
+\&
+\&        /* Data about the last/current match. These are modified during
+\&         * matching*/
+\&        U32 lastparen;            /* highest close paren matched ($+) */
+\&        U32 lastcloseparen;       /* last close paren matched ($^N) */
+\&        regexp_paren_pair *offs;  /* Array of offsets for (@\-) and
+\&                                     (@+) */
+\&
+\&        char *subbeg;  /* saved or original string so \edigit works
+\&                          forever. */
+\&        SV_SAVED_COPY  /* If non\-NULL, SV which is COW from original */
+\&        I32 sublen;    /* Length of string pointed by subbeg */
+\&        I32 suboffset;  /* byte offset of subbeg from logical start of
+\&                           str */
+\&        I32 subcoffset; /* suboffset equiv, but in chars (for @\-/@+) */
+\&
+\&        /* Information about the match that isn\*(Aqt often used */
+\&        I32 prelen;           /* length of precomp */
+\&        const char *precomp;  /* pre\-compilation regular expression */
+\&
+\&        char *wrapped;  /* wrapped version of the pattern */
+\&        I32 wraplen;    /* length of wrapped */
+\&
+\&        I32 seen_evals;   /* number of eval groups in the pattern \- for
+\&                             security checks */
+\&        HV *paren_names;  /* Optional hash of paren names */
+\&
+\&        /* Refcount of this regexp */
+\&        I32 refcnt;             /* Refcount of this regexp */
+\&    } regexp;
+.Ve
+.PP
+The fields are discussed in more detail below:
+.ie n .SS """engine"""
+.el .SS \f(CWengine\fP
+.IX Subsection "engine"
+This field points at a \f(CW\*(C`regexp_engine\*(C'\fR structure which contains pointers
+to the subroutines that are to be used for performing a match.  It
+is the compiling routine's responsibility to populate this field before
+returning the regexp object.
+.PP
+Internally this is set to \f(CW\*(C`NULL\*(C'\fR unless a custom engine is specified in
+\&\f(CW$^H{regcomp}\fR, Perl's own set of callbacks can be accessed in the struct
+pointed to by \f(CW\*(C`RE_ENGINE_PTR\*(C'\fR.
+.ie n .SS """mother_re"""
+.el .SS \f(CWmother_re\fP
+.IX Subsection "mother_re"
+TODO, see commit 28d8d7f41a.
+.ie n .SS """extflags"""
+.el .SS \f(CWextflags\fP
+.IX Subsection "extflags"
+This will be used by Perl to see what flags the regexp was compiled
+with, this will normally be set to the value of the flags parameter by
+the comp callback.  See the comp documentation for
+valid flags.
+.ie n .SS """minlen"" ""minlenret"""
+.el .SS "\f(CWminlen\fP \f(CWminlenret\fP"
+.IX Subsection "minlen minlenret"
+The minimum string length (in characters) required for the pattern to match.
+This is used to
+prune the search space by not bothering to match any closer to the end of a
+string than would allow a match.  For instance there is no point in even
+starting the regex engine if the minlen is 10 but the string is only 5
+characters long.  There is no way that the pattern can match.
+.PP
+\&\f(CW\*(C`minlenret\*(C'\fR is the minimum length (in characters) of the string that would
+be found in $& after a match.
+.PP
+The difference between \f(CW\*(C`minlen\*(C'\fR and \f(CW\*(C`minlenret\*(C'\fR can be seen in the
+following pattern:
+.PP
+.Vb 1
+\&    /ns(?=\ed)/
+.Ve
+.PP
+where the \f(CW\*(C`minlen\*(C'\fR would be 3 but \f(CW\*(C`minlenret\*(C'\fR would only be 2 as the \ed is
+required to match but is not actually
+included in the matched content.  This
+distinction is particularly important as the substitution logic uses the
+\&\f(CW\*(C`minlenret\*(C'\fR to tell if it can do in-place substitutions (these can
+result in considerable speed-up).
+.ie n .SS """gofs"""
+.el .SS \f(CWgofs\fP
+.IX Subsection "gofs"
+Left offset from \fBpos()\fR to start match at.
+.ie n .SS """substrs"""
+.el .SS \f(CWsubstrs\fP
+.IX Subsection "substrs"
+Substring data about strings that must appear in the final match.  This
+is currently only used internally by Perl's engine, but might be
+used in the future for all engines for optimisations.
+.ie n .SS """nparens"", ""lastparen"", and ""lastcloseparen"""
+.el .SS "\f(CWnparens\fP, \f(CWlastparen\fP, and \f(CWlastcloseparen\fP"
+.IX Subsection "nparens, lastparen, and lastcloseparen"
+These fields are used to keep track of: how many paren capture groups
+there are in the pattern; which was the highest paren to be closed (see
+"$+" in perlvar); and which was the most recent paren to be closed (see
+"$^N" in perlvar).
+.ie n .SS """intflags"""
+.el .SS \f(CWintflags\fP
+.IX Subsection "intflags"
+The engine's private copy of the flags the pattern was compiled with. Usually
+this is the same as \f(CW\*(C`extflags\*(C'\fR unless the engine chose to modify one of them.
+.ie n .SS """pprivate"""
+.el .SS \f(CWpprivate\fP
+.IX Subsection "pprivate"
+A void* pointing to an engine-defined
+data structure.  The Perl engine uses the
+\&\f(CW\*(C`regexp_internal\*(C'\fR structure (see "Base Structures" in perlreguts) but a custom
+engine should use something else.
+.ie n .SS """offs"""
+.el .SS \f(CWoffs\fP
+.IX Subsection "offs"
+A \f(CW\*(C`regexp_paren_pair\*(C'\fR structure which defines offsets into the string being
+matched which correspond to the \f(CW$&\fR and \f(CW$1\fR, \f(CW$2\fR etc. captures, the
+\&\f(CW\*(C`regexp_paren_pair\*(C'\fR struct is defined as follows:
+.PP
+.Vb 4
+\&    typedef struct regexp_paren_pair {
+\&        I32 start;
+\&        I32 end;
+\&    } regexp_paren_pair;
+.Ve
+.PP
+If \f(CW\*(C`\->offs[num].start\*(C'\fR or \f(CW\*(C`\->offs[num].end\*(C'\fR is \f(CW\-1\fR then that
+capture group did not match.
+\&\f(CW\*(C`\->offs[0].start/end\*(C'\fR represents \f(CW$&\fR (or
+\&\f(CW\*(C`${^MATCH}\*(C'\fR under \f(CW\*(C`/p\*(C'\fR) and \f(CW\*(C`\->offs[paren].end\*(C'\fR matches \f(CW$$paren\fR where
+\&\f(CW$paren \fR= 1>.
+.ie n .SS """precomp"" ""prelen"""
+.el .SS "\f(CWprecomp\fP \f(CWprelen\fP"
+.IX Subsection "precomp prelen"
+Used for optimisations.  \f(CW\*(C`precomp\*(C'\fR holds a copy of the pattern that
+was compiled and \f(CW\*(C`prelen\*(C'\fR its length.  When a new pattern is to be
+compiled (such as inside a loop) the internal \f(CW\*(C`regcomp\*(C'\fR operator
+checks if the last compiled \f(CW\*(C`REGEXP\*(C'\fR's \f(CW\*(C`precomp\*(C'\fR and \f(CW\*(C`prelen\*(C'\fR
+are equivalent to the new one, and if so uses the old pattern instead
+of compiling a new one.
+.PP
+The relevant snippet from \f(CW\*(C`Perl_pp_regcomp\*(C'\fR:
+.PP
+.Vb 3
+\&        if (!re || !re\->precomp || re\->prelen != (I32)len ||
+\&            memNE(re\->precomp, t, len))
+\&        /* Compile a new pattern */
+.Ve
+.ie n .SS """paren_names"""
+.el .SS \f(CWparen_names\fP
+.IX Subsection "paren_names"
+This is a hash used internally to track named capture groups and their
+offsets.  The keys are the names of the buffers the values are dualvars,
+with the IV slot holding the number of buffers with the given name and the
+pv being an embedded array of I32.  The values may also be contained
+independently in the data array in cases where named backreferences are
+used.
+.ie n .SS """substrs"""
+.el .SS \f(CWsubstrs\fP
+.IX Subsection "substrs"
+Holds information on the longest string that must occur at a fixed
+offset from the start of the pattern, and the longest string that must
+occur at a floating offset from the start of the pattern.  Used to do
+Fast-Boyer-Moore searches on the string to find out if its worth using
+the regex engine at all, and if so where in the string to search.
+.ie n .SS """subbeg"" ""sublen"" ""saved_copy"" ""suboffset"" ""subcoffset"""
+.el .SS "\f(CWsubbeg\fP \f(CWsublen\fP \f(CWsaved_copy\fP \f(CWsuboffset\fP \f(CWsubcoffset\fP"
+.IX Subsection "subbeg sublen saved_copy suboffset subcoffset"
+Used during the execution phase for managing search and replace patterns,
+and for providing the text for \f(CW$&\fR, \f(CW$1\fR etc. \f(CW\*(C`subbeg\*(C'\fR points to a
+buffer (either the original string, or a copy in the case of
+\&\f(CWRX_MATCH_COPIED(rx)\fR), and \f(CW\*(C`sublen\*(C'\fR is the length of the buffer.  The
+\&\f(CW\*(C`RX_OFFS\*(C'\fR start and end indices index into this buffer.
+.PP
+In the presence of the \f(CW\*(C`REXEC_COPY_STR\*(C'\fR flag, but with the addition of
+the \f(CW\*(C`REXEC_COPY_SKIP_PRE\*(C'\fR or \f(CW\*(C`REXEC_COPY_SKIP_POST\*(C'\fR flags, an engine
+can choose not to copy the full buffer (although it must still do so in
+the presence of \f(CW\*(C`RXf_PMf_KEEPCOPY\*(C'\fR or the relevant bits being set in
+\&\f(CW\*(C`PL_sawampersand\*(C'\fR).  In this case, it may set \f(CW\*(C`suboffset\*(C'\fR to indicate the
+number of bytes from the logical start of the buffer to the physical start
+(i.e. \f(CW\*(C`subbeg\*(C'\fR).  It should also set \f(CW\*(C`subcoffset\*(C'\fR, the number of
+characters in the offset. The latter is needed to support \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR
+which work in characters, not bytes.
+.ie n .SS """wrapped"" ""wraplen"""
+.el .SS "\f(CWwrapped\fP \f(CWwraplen\fP"
+.IX Subsection "wrapped wraplen"
+Stores the string \f(CW\*(C`qr//\*(C'\fR stringifies to. The Perl engine for example
+stores \f(CW\*(C`(?^:eek)\*(C'\fR in the case of \f(CW\*(C`qr/eek/\*(C'\fR.
+.PP
+When using a custom engine that doesn't support the \f(CW\*(C`(?:)\*(C'\fR construct
+for inline modifiers, it's probably best to have \f(CW\*(C`qr//\*(C'\fR stringify to
+the supplied pattern, note that this will create undesired patterns in
+cases such as:
+.PP
+.Vb 3
+\&    my $x = qr/a|b/;  # "a|b"
+\&    my $y = qr/c/i;   # "c"
+\&    my $z = qr/$x$y/; # "a|bc"
+.Ve
+.PP
+There's no solution for this problem other than making the custom
+engine understand a construct like \f(CW\*(C`(?:)\*(C'\fR.
+.ie n .SS """seen_evals"""
+.el .SS \f(CWseen_evals\fP
+.IX Subsection "seen_evals"
+This stores the number of eval groups in
+the pattern.  This is used for security
+purposes when embedding compiled regexes into larger patterns with \f(CW\*(C`qr//\*(C'\fR.
+.ie n .SS """refcnt"""
+.el .SS \f(CWrefcnt\fP
+.IX Subsection "refcnt"
+The number of times the structure is referenced.  When
+this falls to 0, the regexp is automatically freed
+by a call to \f(CW\*(C`pregfree\*(C'\fR.  This should be set to 1 in
+each engine's "comp" routine.
+.SH HISTORY
+.IX Header "HISTORY"
+Originally part of perlreguts.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Originally written by Yves Orton, expanded by Ævar Arnfjörð
+Bjarmason.
+.SH LICENSE
+.IX Header "LICENSE"
+Copyright 2006 Yves Orton and 2007 Ævar Arnfjörð Bjarmason.
+.PP
+This program is free software; you can redistribute it and/or modify it under
+the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perlrebackslash.1 b/upstream/mageia-cauldron/man1/perlrebackslash.1
new file mode 100644
index 00000000..c109cd0f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlrebackslash.1
@@ -0,0 +1,859 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREBACKSLASH 1"
+.TH PERLREBACKSLASH 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlrebackslash \- Perl Regular Expression Backslash Sequences and Escapes
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The top level documentation about Perl regular expressions
+is found in perlre.
+.PP
+This document describes all backslash and escape sequences. After
+explaining the role of the backslash, it lists all the sequences that have
+a special meaning in Perl regular expressions (in alphabetical order),
+then describes each of them.
+.PP
+Most sequences are described in detail in different documents; the primary
+purpose of this document is to have a quick reference guide describing all
+backslash and escape sequences.
+.SS "The backslash"
+.IX Subsection "The backslash"
+In a regular expression, the backslash can perform one of two tasks:
+it either takes away the special meaning of the character following it
+(for instance, \f(CW\*(C`\e|\*(C'\fR matches a vertical bar, it's not an alternation),
+or it is the start of a backslash or escape sequence.
+.PP
+The rules determining what it is are quite simple: if the character
+following the backslash is an ASCII punctuation (non-word) character (that is,
+anything that is not a letter, digit, or underscore), then the backslash just
+takes away any special meaning of the character following it.
+.PP
+If the character following the backslash is an ASCII letter or an ASCII digit,
+then the sequence may be special; if so, it's listed below. A few letters have
+not been used yet, so escaping them with a backslash doesn't change them to be
+special.  A future version of Perl may assign a special meaning to them, so if
+you have warnings turned on, Perl issues a warning if you use such a
+sequence.  [1].
+.PP
+It is however guaranteed that backslash or escape sequences never have a
+punctuation character following the backslash, not now, and not in a future
+version of Perl 5. So it is safe to put a backslash in front of a non-word
+character.
+.PP
+Note that the backslash itself is special; if you want to match a backslash,
+you have to escape the backslash with a backslash: \f(CW\*(C`/\e\e/\*(C'\fR matches a single
+backslash.
+.IP [1] 4
+.IX Item "[1]"
+There is one exception. If you use an alphanumeric character as the
+delimiter of your pattern (which you probably shouldn't do for readability
+reasons), you have to escape the delimiter if you want to match
+it. Perl won't warn then. See also "Gory details of parsing
+quoted constructs" in perlop.
+.SS "All the sequences and escapes"
+.IX Subsection "All the sequences and escapes"
+Those not usable within a bracketed character class (like \f(CW\*(C`[\eda\-z]\*(C'\fR) are marked
+as \f(CW\*(C`Not in [].\*(C'\fR
+.PP
+.Vb 10
+\& \e000              Octal escape sequence.  See also \eo{}.
+\& \e1                Absolute backreference.  Not in [].
+\& \ea                Alarm or bell.
+\& \eA                Beginning of string.  Not in [].
+\& \eb{}, \eb          Boundary. (\eb is a backspace in []).
+\& \eB{}, \eB          Not a boundary.  Not in [].
+\& \ecX               Control\-X.
+\& \ed                Match any digit character.
+\& \eD                Match any character that isn\*(Aqt a digit.
+\& \ee                Escape character.
+\& \eE                Turn off \eQ, \eL and \eU processing.  Not in [].
+\& \ef                Form feed.
+\& \eF                Foldcase till \eE.  Not in [].
+\& \eg{}, \eg1         Named, absolute or relative backreference.
+\&                   Not in [].
+\& \eG                Pos assertion.  Not in [].
+\& \eh                Match any horizontal whitespace character.
+\& \eH                Match any character that isn\*(Aqt horizontal whitespace.
+\& \ek{}, \ek<>, \ek\*(Aq\*(Aq  Named backreference.  Not in [].
+\& \eK                Keep the stuff left of \eK.  Not in [].
+\& \el                Lowercase next character.  Not in [].
+\& \eL                Lowercase till \eE.  Not in [].
+\& \en                (Logical) newline character.
+\& \eN                Match any character but newline.  Not in [].
+\& \eN{}              Named or numbered (Unicode) character or sequence.
+\& \eo{}              Octal escape sequence.
+\& \ep{}, \epP         Match any character with the given Unicode property.
+\& \eP{}, \ePP         Match any character without the given property.
+\& \eQ                Quote (disable) pattern metacharacters till \eE.  Not
+\&                   in [].
+\& \er                Return character.
+\& \eR                Generic new line.  Not in [].
+\& \es                Match any whitespace character.
+\& \eS                Match any character that isn\*(Aqt a whitespace.
+\& \et                Tab character.
+\& \eu                Titlecase next character.  Not in [].
+\& \eU                Uppercase till \eE.  Not in [].
+\& \ev                Match any vertical whitespace character.
+\& \eV                Match any character that isn\*(Aqt vertical whitespace
+\& \ew                Match any word character.
+\& \eW                Match any character that isn\*(Aqt a word character.
+\& \ex{}, \ex00        Hexadecimal escape sequence.
+\& \eX                Unicode "extended grapheme cluster".  Not in [].
+\& \ez                End of string.  Not in [].
+\& \eZ                End of string.  Not in [].
+.Ve
+.SS "Character Escapes"
+.IX Subsection "Character Escapes"
+\fIFixed characters\fR
+.IX Subsection "Fixed characters"
+.PP
+A handful of characters have a dedicated \fIcharacter escape\fR. The following
+table shows them, along with their ASCII code points (in decimal and hex),
+their ASCII name, the control escape on ASCII platforms and a short
+description.  (For EBCDIC platforms, see "OPERATOR DIFFERENCES" in perlebcdic.)
+.PP
+.Vb 9
+\& Seq.  Code Point  ASCII   Cntrl   Description.
+\&       Dec    Hex
+\&  \ea     7     07    BEL    \ecG    alarm or bell
+\&  \eb     8     08     BS    \ecH    backspace [1]
+\&  \ee    27     1B    ESC    \ec[    escape character
+\&  \ef    12     0C     FF    \ecL    form feed
+\&  \en    10     0A     LF    \ecJ    line feed [2]
+\&  \er    13     0D     CR    \ecM    carriage return
+\&  \et     9     09    TAB    \ecI    tab
+.Ve
+.IP [1] 4
+.IX Item "[1]"
+\&\f(CW\*(C`\eb\*(C'\fR is the backspace character only inside a character class. Outside a
+character class, \f(CW\*(C`\eb\*(C'\fR alone is a word\-character/non\-word\-character
+boundary, and \f(CW\*(C`\eb{}\*(C'\fR is some other type of boundary.
+.IP [2] 4
+.IX Item "[2]"
+\&\f(CW\*(C`\en\*(C'\fR matches a logical newline. Perl converts between \f(CW\*(C`\en\*(C'\fR and your
+OS's native newline character when reading from or writing to text files.
+.PP
+Example
+.IX Subsection "Example"
+.PP
+.Vb 1
+\& $str =~ /\et/;   # Matches if $str contains a (horizontal) tab.
+.Ve
+.PP
+\fIControl characters\fR
+.IX Subsection "Control characters"
+.PP
+\&\f(CW\*(C`\ec\*(C'\fR is used to denote a control character; the character following \f(CW\*(C`\ec\*(C'\fR
+determines the value of the construct.  For example the value of \f(CW\*(C`\ecA\*(C'\fR is
+\&\f(CWchr(1)\fR, and the value of \f(CW\*(C`\ecb\*(C'\fR is \f(CWchr(2)\fR, etc.
+The gory details are in "Regexp Quote-Like Operators" in perlop.  A complete
+list of what \f(CWchr(1)\fR, etc. means for ASCII and EBCDIC platforms is in
+"OPERATOR DIFFERENCES" in perlebcdic.
+.PP
+Note that \f(CW\*(C`\ec\e\*(C'\fR alone at the end of a regular expression (or doubled-quoted
+string) is not valid.  The backslash must be followed by another character.
+That is, \f(CW\*(C`\ec\e\fR\f(CIX\fR\f(CW\*(C'\fR means \f(CW\*(C`chr(28) . \*(Aq\fR\f(CIX\fR\f(CW\*(Aq\*(C'\fR for all characters \fIX\fR.
+.PP
+To write platform-independent code, you must use \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR instead, like
+\&\f(CW\*(C`\eN{ESCAPE}\*(C'\fR or \f(CW\*(C`\eN{U+001B}\*(C'\fR, see charnames.
+.PP
+Mnemonic: \fIc\fRontrol character.
+.PP
+Example
+.IX Subsection "Example"
+.PP
+.Vb 1
+\& $str =~ /\ecK/;  # Matches if $str contains a vertical tab (control\-K).
+.Ve
+.PP
+\fINamed or numbered characters and character sequences\fR
+.IX Subsection "Named or numbered characters and character sequences"
+.PP
+Unicode characters have a Unicode name and numeric code point (ordinal)
+value.  Use the
+\&\f(CW\*(C`\eN{}\*(C'\fR construct to specify a character by either of these values.
+Certain sequences of characters also have names.
+.PP
+To specify by name, the name of the character or character sequence goes
+between the curly braces.
+.PP
+To specify a character by Unicode code point, use the form \f(CW\*(C`\eN{U+\fR\f(CIcode
+point\fR\f(CW}\*(C'\fR, where \fIcode point\fR is a number in hexadecimal that gives the
+code point that Unicode has assigned to the desired character.  It is
+customary but not required to use leading zeros to pad the number to 4
+digits.  Thus \f(CW\*(C`\eN{U+0041}\*(C'\fR means \f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR, and you will
+rarely see it written without the two leading zeros.  \f(CW\*(C`\eN{U+0041}\*(C'\fR means
+"A" even on EBCDIC machines (where the ordinal value of "A" is not 0x41).
+.PP
+Blanks may freely be inserted adjacent to but within the braces
+enclosing the name or code point.  So \f(CW\*(C`\eN{\ U+0041\ }\*(C'\fR is perfectly
+legal.
+.PP
+It is even possible to give your own names to characters and character
+sequences by using the charnames module.  These custom names are
+lexically scoped, and so a given code point may have different names
+in different scopes.  The name used is what is in effect at the time the
+\&\f(CW\*(C`\eN{}\*(C'\fR is expanded.  For patterns in double-quotish context, that means
+at the time the pattern is parsed.  But for patterns that are delimitted
+by single quotes, the expansion is deferred until pattern compilation
+time, which may very well have a different \f(CW\*(C`charnames\*(C'\fR translator in
+effect.
+.PP
+(There is an expanded internal form that you may see in debug output:
+\&\f(CW\*(C`\eN{U+\fR\f(CIcode point\fR\f(CW.\fR\f(CIcode point\fR\f(CW...}\*(C'\fR.
+The \f(CW\*(C`...\*(C'\fR means any number of these \fIcode point\fRs separated by dots.
+This represents the sequence formed by the characters.  This is an internal
+form only, subject to change, and you should not try to use it yourself.)
+.PP
+Mnemonic: \fIN\fRamed character.
+.PP
+Note that a character or character sequence expressed as a named
+or numbered character is considered a character without special
+meaning by the regex engine, and will match "as is".
+.PP
+Example
+.IX Subsection "Example"
+.PP
+.Vb 1
+\& $str =~ /\eN{THAI CHARACTER SO SO}/;  # Matches the Thai SO SO character
+\&
+\& use charnames \*(AqCyrillic\*(Aq;            # Loads Cyrillic names.
+\& $str =~ /\eN{ZHE}\eN{KA}/;             # Match "ZHE" followed by "KA".
+.Ve
+.PP
+\fIOctal escapes\fR
+.IX Subsection "Octal escapes"
+.PP
+There are two forms of octal escapes.  Each is used to specify a character by
+its code point specified in base 8.
+.PP
+One form, available starting in Perl 5.14 looks like \f(CW\*(C`\eo{...}\*(C'\fR, where the dots
+represent one or more octal digits.  It can be used for any Unicode character.
+.PP
+It was introduced to avoid the potential problems with the other form,
+available in all Perls.  That form consists of a backslash followed by three
+octal digits.  One problem with this form is that it can look exactly like an
+old-style backreference (see
+"Disambiguation rules between old-style octal escapes and backreferences"
+below.)  You can avoid this by making the first of the three digits always a
+zero, but that makes \e077 the largest code point specifiable.
+.PP
+In some contexts, a backslash followed by two or even one octal digits may be
+interpreted as an octal escape, sometimes with a warning, and because of some
+bugs, sometimes with surprising results.  Also, if you are creating a regex
+out of smaller snippets concatenated together, and you use fewer than three
+digits, the beginning of one snippet may be interpreted as adding digits to the
+ending of the snippet before it.  See "Absolute referencing" for more
+discussion and examples of the snippet problem.
+.PP
+Note that a character expressed as an octal escape is considered
+a character without special meaning by the regex engine, and will match
+"as is".
+.PP
+To summarize, the \f(CW\*(C`\eo{}\*(C'\fR form is always safe to use, and the other form is
+safe to use for code points through \e077 when you use exactly three digits to
+specify them.
+.PP
+Mnemonic: \fI0\fRctal or \fIo\fRctal.
+.PP
+Examples (assuming an ASCII platform)
+.IX Subsection "Examples (assuming an ASCII platform)"
+.PP
+.Vb 12
+\& $str = "Perl";
+\& $str =~ /\eo{120}/;  # Match, "\e120" is "P".
+\& $str =~ /\e120/;     # Same.
+\& $str =~ /\eo{120}+/; # Match, "\e120" is "P",
+\&                     # it\*(Aqs repeated at least once.
+\& $str =~ /\e120+/;    # Same.
+\& $str =~ /P\e053/;    # No match, "\e053" is "+" and taken literally.
+\& /\eo{23073}/         # Black foreground, white background smiling face.
+\& /\eo{4801234567}/    # Raises a warning, and yields chr(4).
+\& /\eo{ 400}/          # LATIN CAPITAL LETTER A WITH MACRON
+\& /\eo{ 400 }/         # Same. These show blanks are allowed adjacent to
+\&                     # the braces
+.Ve
+.PP
+Disambiguation rules between old-style octal escapes and backreferences
+.IX Subsection "Disambiguation rules between old-style octal escapes and backreferences"
+.PP
+Octal escapes of the \f(CW\*(C`\e000\*(C'\fR form outside of bracketed character classes
+potentially clash with old-style backreferences (see "Absolute referencing"
+below).  They both consist of a backslash followed by numbers.  So Perl has to
+use heuristics to determine whether it is a backreference or an octal escape.
+Perl uses the following rules to disambiguate:
+.IP 1. 4
+If the backslash is followed by a single digit, it's a backreference.
+.IP 2. 4
+If the first digit following the backslash is a 0, it's an octal escape.
+.IP 3. 4
+If the number following the backslash is N (in decimal), and Perl already
+has seen N capture groups, Perl considers this a backreference.  Otherwise,
+it considers it an octal escape. If N has more than three digits, Perl
+takes only the first three for the octal escape; the rest are matched as is.
+.Sp
+.Vb 6
+\& my $pat  = "(" x 999;
+\&    $pat .= "a";
+\&    $pat .= ")" x 999;
+\& /^($pat)\e1000$/;   #  Matches \*(Aqaa\*(Aq; there are 1000 capture groups.
+\& /^$pat\e1000$/;     #  Matches \*(Aqa@0\*(Aq; there are 999 capture groups
+\&                    #  and \e1000 is seen as \e100 (a \*(Aq@\*(Aq) and a \*(Aq0\*(Aq.
+.Ve
+.PP
+You can force a backreference interpretation always by using the \f(CW\*(C`\eg{...}\*(C'\fR
+form.  You can the force an octal interpretation always by using the \f(CW\*(C`\eo{...}\*(C'\fR
+form, or for numbers up through \e077 (= 63 decimal), by using three digits,
+beginning with a "0".
+.PP
+\fIHexadecimal escapes\fR
+.IX Subsection "Hexadecimal escapes"
+.PP
+Like octal escapes, there are two forms of hexadecimal escapes, but both start
+with the sequence \f(CW\*(C`\ex\*(C'\fR.  This is followed by either exactly two hexadecimal
+digits forming a number, or a hexadecimal number of arbitrary length surrounded
+by curly braces. The hexadecimal number is the code point of the character you
+want to express.
+.PP
+Note that a character expressed as one of these escapes is considered a
+character without special meaning by the regex engine, and will match
+"as is".
+.PP
+Mnemonic: he\fIx\fRadecimal.
+.PP
+Examples (assuming an ASCII platform)
+.IX Subsection "Examples (assuming an ASCII platform)"
+.PP
+.Vb 4
+\& $str = "Perl";
+\& $str =~ /\ex50/;    # Match, "\ex50" is "P".
+\& $str =~ /\ex50+/;   # Match, "\ex50" is "P", it is repeated at least once
+\& $str =~ /P\ex2B/;   # No match, "\ex2B" is "+" and taken literally.
+\&
+\& /\ex{2603}\ex{2602}/ # Snowman with an umbrella.
+\&                    # The Unicode character 2603 is a snowman,
+\&                    # the Unicode character 2602 is an umbrella.
+\& /\ex{263B}/         # Black smiling face.
+\& /\ex{263b}/         # Same, the hex digits A \- F are case insensitive.
+\& /\ex{ 263b }/       # Same, showing optional blanks adjacent to the
+\&                    # braces
+.Ve
+.SS Modifiers
+.IX Subsection "Modifiers"
+A number of backslash sequences have to do with changing the character,
+or characters following them. \f(CW\*(C`\el\*(C'\fR will lowercase the character following
+it, while \f(CW\*(C`\eu\*(C'\fR will uppercase (or, more accurately, titlecase) the
+character following it. They provide functionality similar to the
+functions \f(CW\*(C`lcfirst\*(C'\fR and \f(CW\*(C`ucfirst\*(C'\fR.
+.PP
+To uppercase or lowercase several characters, one might want to use
+\&\f(CW\*(C`\eL\*(C'\fR or \f(CW\*(C`\eU\*(C'\fR, which will lowercase/uppercase all characters following
+them, until either the end of the pattern or the next occurrence of
+\&\f(CW\*(C`\eE\*(C'\fR, whichever comes first. They provide functionality similar to what
+the functions \f(CW\*(C`lc\*(C'\fR and \f(CW\*(C`uc\*(C'\fR provide.
+.PP
+\&\f(CW\*(C`\eQ\*(C'\fR is used to quote (disable) pattern metacharacters, up to the next
+\&\f(CW\*(C`\eE\*(C'\fR or the end of the pattern. \f(CW\*(C`\eQ\*(C'\fR adds a backslash to any character
+that could have special meaning to Perl.  In the ASCII range, it quotes
+every character that isn't a letter, digit, or underscore.  See
+"quotemeta" in perlfunc for details on what gets quoted for non-ASCII
+code points.  Using this ensures that any character between \f(CW\*(C`\eQ\*(C'\fR and
+\&\f(CW\*(C`\eE\*(C'\fR will be matched literally, not interpreted as a metacharacter by
+the regex engine.
+.PP
+\&\f(CW\*(C`\eF\*(C'\fR can be used to casefold all characters following, up to the next \f(CW\*(C`\eE\*(C'\fR
+or the end of the pattern. It provides the functionality similar to
+the \f(CW\*(C`fc\*(C'\fR function.
+.PP
+Mnemonic: \fIL\fRowercase, \fIU\fRppercase, \fIF\fRold-case, \fIQ\fRuotemeta, \fIE\fRnd.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 7
+\& $sid     = "sid";
+\& $greg    = "GrEg";
+\& $miranda = "(Miranda)";
+\& $str     =~ /\eu$sid/;        # Matches \*(AqSid\*(Aq
+\& $str     =~ /\eL$greg/;       # Matches \*(Aqgreg\*(Aq
+\& $str     =~ /\eQ$miranda\eE/;  # Matches \*(Aq(Miranda)\*(Aq, as if the pattern
+\&                              #   had been written as /\e(Miranda\e)/
+.Ve
+.SS "Character classes"
+.IX Subsection "Character classes"
+Perl regular expressions have a large range of character classes. Some of
+the character classes are written as a backslash sequence. We will briefly
+discuss those here; full details of character classes can be found in
+perlrecharclass.
+.PP
+\&\f(CW\*(C`\ew\*(C'\fR is a character class that matches any single \fIword\fR character
+(letters, digits, Unicode marks, and connector punctuation (like the
+underscore)).  \f(CW\*(C`\ed\*(C'\fR is a character class that matches any decimal
+digit, while the character class \f(CW\*(C`\es\*(C'\fR matches any whitespace character.
+New in perl 5.10.0 are the classes \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ev\*(C'\fR which match horizontal
+and vertical whitespace characters.
+.PP
+The exact set of characters matched by \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\es\*(C'\fR, and \f(CW\*(C`\ew\*(C'\fR varies
+depending on various pragma and regular expression modifiers.  It is
+possible to restrict the match to the ASCII range by using the \f(CW\*(C`/a\*(C'\fR
+regular expression modifier.  See perlrecharclass.
+.PP
+The uppercase variants (\f(CW\*(C`\eW\*(C'\fR, \f(CW\*(C`\eD\*(C'\fR, \f(CW\*(C`\eS\*(C'\fR, \f(CW\*(C`\eH\*(C'\fR, and \f(CW\*(C`\eV\*(C'\fR) are
+character classes that match, respectively, any character that isn't a
+word character, digit, whitespace, horizontal whitespace, or vertical
+whitespace.
+.PP
+Mnemonics: \fIw\fRord, \fId\fRigit, \fIs\fRpace, \fIh\fRorizontal, \fIv\fRertical.
+.PP
+\fIUnicode classes\fR
+.IX Subsection "Unicode classes"
+.PP
+\&\f(CW\*(C`\epP\*(C'\fR (where \f(CW\*(C`P\*(C'\fR is a single letter) and \f(CW\*(C`\ep{Property}\*(C'\fR are used to
+match a character that matches the given Unicode property; properties
+include things like "letter", or "thai character". Capitalizing the
+sequence to \f(CW\*(C`\ePP\*(C'\fR and \f(CW\*(C`\eP{Property}\*(C'\fR make the sequence match a character
+that doesn't match the given Unicode property. For more details, see
+"Backslash sequences" in perlrecharclass and
+"Unicode Character Properties" in perlunicode.
+.PP
+Mnemonic: \fIp\fRroperty.
+.SS Referencing
+.IX Subsection "Referencing"
+If capturing parenthesis are used in a regular expression, we can refer
+to the part of the source string that was matched, and match exactly the
+same thing. There are three ways of referring to such \fIbackreference\fR:
+absolutely, relatively, and by name.
+.PP
+\fIAbsolute referencing\fR
+.IX Subsection "Absolute referencing"
+.PP
+Either \f(CW\*(C`\eg\fR\f(CIN\fR\f(CW\*(C'\fR (starting in Perl 5.10.0), or \f(CW\*(C`\e\fR\f(CIN\fR\f(CW\*(C'\fR (old-style) where \fIN\fR
+is a positive (unsigned) decimal number of any length is an absolute reference
+to a capturing group.
+.PP
+\&\fIN\fR refers to the Nth set of parentheses, so \f(CW\*(C`\eg\fR\f(CIN\fR\f(CW\*(C'\fR refers to whatever has
+been matched by that set of parentheses.  Thus \f(CW\*(C`\eg1\*(C'\fR refers to the first
+capture group in the regex.
+.PP
+The \f(CW\*(C`\eg\fR\f(CIN\fR\f(CW\*(C'\fR form can be equivalently written as \f(CW\*(C`\eg{\fR\f(CIN\fR\f(CW}\*(C'\fR
+which avoids ambiguity when building a regex by concatenating shorter
+strings.  Otherwise if you had a regex \f(CW\*(C`qr/$a$b/\*(C'\fR, and \f(CW$a\fR contained
+\&\f(CW"\eg1"\fR, and \f(CW$b\fR contained \f(CW"37"\fR, you would get \f(CW\*(C`/\eg137/\*(C'\fR which is
+probably not what you intended.
+.PP
+In the \f(CW\*(C`\e\fR\f(CIN\fR\f(CW\*(C'\fR form, \fIN\fR must not begin with a "0", and there must be at
+least \fIN\fR capturing groups, or else \fIN\fR is considered an octal escape
+(but something like \f(CW\*(C`\e18\*(C'\fR is the same as \f(CW\*(C`\e0018\*(C'\fR; that is, the octal escape
+\&\f(CW"\e001"\fR followed by a literal digit \f(CW"8"\fR).
+.PP
+Mnemonic: \fIg\fRroup.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 5
+\& /(\ew+) \eg1/;    # Finds a duplicated word, (e.g. "cat cat").
+\& /(\ew+) \e1/;     # Same thing; written old\-style.
+\& /(\ew+) \eg{1}/;  # Same, using the safer braced notation
+\& /(\ew+) \eg{ 1 }/;# Same, showing optional blanks adjacent to the braces
+\& /(.)(.)\eg2\eg1/; # Match a four letter palindrome (e.g. "ABBA").
+.Ve
+.PP
+\fIRelative referencing\fR
+.IX Subsection "Relative referencing"
+.PP
+\&\f(CW\*(C`\eg\-\fR\f(CIN\fR\f(CW\*(C'\fR (starting in Perl 5.10.0) is used for relative addressing.  (It can
+be written as \f(CW\*(C`\eg{\-\fR\f(CIN\fR\f(CW}\*(C'\fR.)  It refers to the \fIN\fRth group before the
+\&\f(CW\*(C`\eg{\-\fR\f(CIN\fR\f(CW}\*(C'\fR.
+.PP
+The big advantage of this form is that it makes it much easier to write
+patterns with references that can be interpolated in larger patterns,
+even if the larger pattern also contains capture groups.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 8
+\& /(A)        # Group 1
+\&  (          # Group 2
+\&    (B)      # Group 3
+\&    \eg{\-1}   # Refers to group 3 (B)
+\&    \eg{\-3}   # Refers to group 1 (A)
+\&    \eg{ \-3 } # Same, showing optional blanks adjacent to the braces
+\&  )
+\& /x;         # Matches "ABBA".
+\&
+\& my $qr = qr /(.)(.)\eg{\-2}\eg{\-1}/;  # Matches \*(Aqabab\*(Aq, \*(Aqcdcd\*(Aq, etc.
+\& /$qr$qr/                           # Matches \*(Aqababcdcd\*(Aq.
+.Ve
+.PP
+\fINamed referencing\fR
+.IX Subsection "Named referencing"
+.PP
+\&\f(CW\*(C`\eg{\fR\f(CIname\fR\f(CW}\*(C'\fR (starting in Perl 5.10.0) can be used to back refer to a
+named capture group, dispensing completely with having to think about capture
+buffer positions.
+.PP
+To be compatible with .Net regular expressions, \f(CW\*(C`\eg{name}\*(C'\fR may also be
+written as \f(CW\*(C`\ek{name}\*(C'\fR, \f(CW\*(C`\ek<name>\*(C'\fR or \f(CW\*(C`\ek\*(Aqname\*(Aq\*(C'\fR.
+.PP
+To prevent any ambiguity, \fIname\fR must not start with a digit nor contain a
+hyphen.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 10
+\& /(?<word>\ew+) \eg{word}/   # Finds duplicated word, (e.g. "cat cat")
+\& /(?<word>\ew+) \ek{word}/   # Same.
+\& /(?<word>\ew+) \eg{ word }/ # Same, showing optional blanks adjacent to
+\&                           # the braces
+\& /(?<word>\ew+) \ek{ word }/ # Same.
+\& /(?<word>\ew+) \ek<word>/   # Same.  There are no braces, so no blanks
+\&                           # are permitted
+\& /(?<letter1>.)(?<letter2>.)\eg{letter2}\eg{letter1}/
+\&                           # Match a four letter palindrome (e.g.
+\&                           # "ABBA")
+.Ve
+.SS Assertions
+.IX Subsection "Assertions"
+Assertions are conditions that have to be true; they don't actually
+match parts of the substring. There are six assertions that are written as
+backslash sequences.
+.IP \eA 4
+.IX Item "A"
+\&\f(CW\*(C`\eA\*(C'\fR only matches at the beginning of the string. If the \f(CW\*(C`/m\*(C'\fR modifier
+isn't used, then \f(CW\*(C`/\eA/\*(C'\fR is equivalent to \f(CW\*(C`/^/\*(C'\fR. However, if the \f(CW\*(C`/m\*(C'\fR
+modifier is used, then \f(CW\*(C`/^/\*(C'\fR matches internal newlines, but the meaning
+of \f(CW\*(C`/\eA/\*(C'\fR isn't changed by the \f(CW\*(C`/m\*(C'\fR modifier. \f(CW\*(C`\eA\*(C'\fR matches at the beginning
+of the string regardless whether the \f(CW\*(C`/m\*(C'\fR modifier is used.
+.IP "\ez, \eZ" 4
+.IX Item "z, Z"
+\&\f(CW\*(C`\ez\*(C'\fR and \f(CW\*(C`\eZ\*(C'\fR match at the end of the string. If the \f(CW\*(C`/m\*(C'\fR modifier isn't
+used, then \f(CW\*(C`/\eZ/\*(C'\fR is equivalent to \f(CW\*(C`/$/\*(C'\fR; that is, it matches at the
+end of the string, or one before the newline at the end of the string. If the
+\&\f(CW\*(C`/m\*(C'\fR modifier is used, then \f(CW\*(C`/$/\*(C'\fR matches at internal newlines, but the
+meaning of \f(CW\*(C`/\eZ/\*(C'\fR isn't changed by the \f(CW\*(C`/m\*(C'\fR modifier. \f(CW\*(C`\eZ\*(C'\fR matches at
+the end of the string (or just before a trailing newline) regardless whether
+the \f(CW\*(C`/m\*(C'\fR modifier is used.
+.Sp
+\&\f(CW\*(C`\ez\*(C'\fR is just like \f(CW\*(C`\eZ\*(C'\fR, except that it does not match before a trailing
+newline. \f(CW\*(C`\ez\*(C'\fR matches at the end of the string only, regardless of the
+modifiers used, and not just before a newline.  It is how to anchor the
+match to the true end of the string under all conditions.
+.IP \eG 4
+.IX Item "G"
+\&\f(CW\*(C`\eG\*(C'\fR is usually used only in combination with the \f(CW\*(C`/g\*(C'\fR modifier. If the
+\&\f(CW\*(C`/g\*(C'\fR modifier is used and the match is done in scalar context, Perl
+remembers where in the source string the last match ended, and the next time,
+it will start the match from where it ended the previous time.
+.Sp
+\&\f(CW\*(C`\eG\*(C'\fR matches the point where the previous match on that string ended,
+or the beginning of that string if there was no previous match.
+.Sp
+Mnemonic: \fIG\fRlobal.
+.IP "\eb{}, \eb, \eB{}, \eB" 4
+.IX Item "b{}, b, B{}, B"
+\&\f(CW\*(C`\eb{...}\*(C'\fR, available starting in v5.22, matches a boundary (between two
+characters, or before the first character of the string, or after the
+final character of the string) based on the Unicode rules for the
+boundary type specified inside the braces.  The boundary
+types are given a few paragraphs below.  \f(CW\*(C`\eB{...}\*(C'\fR matches at any place
+between characters where \f(CW\*(C`\eb{...}\*(C'\fR of the same type doesn't match.
+.Sp
+\&\f(CW\*(C`\eb\*(C'\fR when not immediately followed by a \f(CW"{"\fR is available in all
+Perls.  It matches at any place
+between a word (something matched by \f(CW\*(C`\ew\*(C'\fR) and a non-word character
+(\f(CW\*(C`\eW\*(C'\fR); \f(CW\*(C`\eB\*(C'\fR when not immediately followed by a \f(CW"{"\fR matches at any
+place between characters where \f(CW\*(C`\eb\*(C'\fR doesn't match.  To get better
+word matching of natural language text, see "\eb{wb}" below.
+.Sp
+\&\f(CW\*(C`\eb\*(C'\fR
+and \f(CW\*(C`\eB\*(C'\fR assume there's a non-word character before the beginning and after
+the end of the source string; so \f(CW\*(C`\eb\*(C'\fR will match at the beginning (or end)
+of the source string if the source string begins (or ends) with a word
+character. Otherwise, \f(CW\*(C`\eB\*(C'\fR will match.
+.Sp
+Do not use something like \f(CW\*(C`\eb=head\ed\eb\*(C'\fR and expect it to match the
+beginning of a line.  It can't, because for there to be a boundary before
+the non-word "=", there must be a word character immediately previous.
+All plain \f(CW\*(C`\eb\*(C'\fR and \f(CW\*(C`\eB\*(C'\fR boundary determinations look for word
+characters alone, not for
+non-word characters nor for string ends.  It may help to understand how
+\&\f(CW\*(C`\eb\*(C'\fR and \f(CW\*(C`\eB\*(C'\fR work by equating them as follows:
+.Sp
+.Vb 2
+\&    \eb  really means    (?:(?<=\ew)(?!\ew)|(?<!\ew)(?=\ew))
+\&    \eB  really means    (?:(?<=\ew)(?=\ew)|(?<!\ew)(?!\ew))
+.Ve
+.Sp
+In contrast, \f(CW\*(C`\eb{...}\*(C'\fR and \f(CW\*(C`\eB{...}\*(C'\fR may or may not match at the
+beginning and end of the line, depending on the boundary type.  These
+implement the Unicode default boundaries, specified in
+<https://www.unicode.org/reports/tr14/> and
+<https://www.unicode.org/reports/tr29/>.
+The boundary types are:
+.RS 4
+.ie n .IP """\eb{gcb}"" or ""\eb{g}""" 4
+.el .IP "\f(CW\eb{gcb}\fR or \f(CW\eb{g}\fR" 4
+.IX Item "b{gcb} or b{g}"
+This matches a Unicode "Grapheme Cluster Boundary".  (Actually Perl
+always uses the improved "extended" grapheme cluster").  These are
+explained below under \f(CW"\eX"\fR.  In fact, \f(CW\*(C`\eX\*(C'\fR is another way to get
+the same functionality.  It is equivalent to \f(CW\*(C`/.+?\eb{gcb}/\*(C'\fR.  Use
+whichever is most convenient for your situation.
+.ie n .IP """\eb{lb}""" 4
+.el .IP \f(CW\eb{lb}\fR 4
+.IX Item "b{lb}"
+This matches according to the default Unicode Line Breaking Algorithm
+(<https://www.unicode.org/reports/tr14/>), as customized in that
+document
+(Example 7 of revision 35 <https://www.unicode.org/reports/tr14/tr14-35.html#Example7>)
+for better handling of numeric expressions.
+.Sp
+This is suitable for many purposes, but the Unicode::LineBreak module
+is available on CPAN that provides many more features, including
+customization.
+.ie n .IP """\eb{sb}""" 4
+.el .IP \f(CW\eb{sb}\fR 4
+.IX Item "b{sb}"
+This matches a Unicode "Sentence Boundary".  This is an aid to parsing
+natural language sentences.  It gives good, but imperfect results.  For
+example, it thinks that "Mr. Smith" is two sentences.  More details are
+at <https://www.unicode.org/reports/tr29/>.  Note also that it thinks
+that anything matching "\eR" (except form feed and vertical tab) is a
+sentence boundary.  \f(CW\*(C`\eb{sb}\*(C'\fR works with text designed for
+word-processors which wrap lines
+automatically for display, but hard-coded line boundaries are considered
+to be essentially the ends of text blocks (paragraphs really), and hence
+the ends of sentences.  \f(CW\*(C`\eb{sb}\*(C'\fR doesn't do well with text containing
+embedded newlines, like the source text of the document you are reading.
+Such text needs to be preprocessed to get rid of the line separators
+before looking for sentence boundaries.  Some people view this as a bug
+in the Unicode standard, and this behavior is quite subject to change in
+future Perl versions.
+.ie n .IP """\eb{wb}""" 4
+.el .IP \f(CW\eb{wb}\fR 4
+.IX Item "b{wb}"
+This matches a Unicode "Word Boundary", but tailored to Perl
+expectations.  This gives better (though not
+perfect) results for natural language processing than plain \f(CW\*(C`\eb\*(C'\fR
+(without braces) does.  For example, it understands that apostrophes can
+be in the middle of words and that parentheses aren't (see the examples
+below).  More details are at <https://www.unicode.org/reports/tr29/>.
+.Sp
+The current Unicode definition of a Word Boundary matches between every
+white space character.  Perl tailors this, starting in version 5.24, to
+generally not break up spans of white space, just as plain \f(CW\*(C`\eb\*(C'\fR has
+always functioned.  This allows \f(CW\*(C`\eb{wb}\*(C'\fR to be a drop-in replacement for
+\&\f(CW\*(C`\eb\*(C'\fR, but with generally better results for natural language
+processing.  (The exception to this tailoring is when a span of white
+space is immediately followed by something like U+0303, COMBINING TILDE.
+If the final space character in the span is a horizontal white space, it
+is broken out so that it attaches instead to the combining character.
+To be precise, if a span of white space that ends in a horizontal space
+has the character immediately following it have any of the Word
+Boundary property values "Extend", "Format" or "ZWJ", the boundary between the
+final horizontal space character and the rest of the span matches
+\&\f(CW\*(C`\eb{wb}\*(C'\fR.  In all other cases the boundary between two white space
+characters matches \f(CW\*(C`\eB{wb}\*(C'\fR.)
+.RE
+.RS 4
+.Sp
+It is important to realize when you use these Unicode boundaries,
+that you are taking a risk that a future version of Perl which contains
+a later version of the Unicode Standard will not work precisely the same
+way as it did when your code was written.  These rules are not
+considered stable and have been somewhat more subject to change than the
+rest of the Standard.  Unicode reserves the right to change them at
+will, and Perl reserves the right to update its implementation to
+Unicode's new rules.  In the past, some changes have been because new
+characters have been added to the Standard which have different
+characteristics than all previous characters, so new rules are
+formulated for handling them.  These should not cause any backward
+compatibility issues.  But some changes have changed the treatment of
+existing characters because the Unicode Technical Committee has decided
+that the change is warranted for whatever reason.  This could be to fix
+a bug, or because they think better results are obtained with the new
+rule.
+.Sp
+It is also important to realize that these are default boundary
+definitions, and that implementations may wish to tailor the results for
+particular purposes and locales.  For example, some languages, such as
+Japanese and Thai, require dictionary lookup to accurately determine
+word boundaries.
+.Sp
+Mnemonic: \fIb\fRoundary.
+.RE
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 4
+\&  "cat"   =~ /\eAcat/;     # Match.
+\&  "cat"   =~ /cat\eZ/;     # Match.
+\&  "cat\en" =~ /cat\eZ/;     # Match.
+\&  "cat\en" =~ /cat\ez/;     # No match.
+\&
+\&  "cat"   =~ /\ebcat\eb/;   # Matches.
+\&  "cats"  =~ /\ebcat\eb/;   # No match.
+\&  "cat"   =~ /\ebcat\eB/;   # No match.
+\&  "cats"  =~ /\ebcat\eB/;   # Match.
+\&
+\&  while ("cat dog" =~ /(\ew+)/g) {
+\&      print $1;           # Prints \*(Aqcatdog\*(Aq
+\&  }
+\&  while ("cat dog" =~ /\eG(\ew+)/g) {
+\&      print $1;           # Prints \*(Aqcat\*(Aq
+\&  }
+\&
+\&  my $s = "He said, \e"Is pi 3.14? (I\*(Aqm not sure).\e"";
+\&  print join("|", $s =~ m/ ( .+? \eb     ) /xg), "\en";
+\&  print join("|", $s =~ m/ ( .+? \eb{wb} ) /xg), "\en";
+\& prints
+\&  He| |said|, "|Is| |pi| |3|.|14|? (|I|\*(Aq|m| |not| |sure
+\&  He| |said|,| |"|Is| |pi| |3.14|?| |(|I\*(Aqm| |not| |sure|)|.|"
+.Ve
+.SS Misc
+.IX Subsection "Misc"
+Here we document the backslash sequences that don't fall in one of the
+categories above. These are:
+.IP \eK 4
+.IX Item "K"
+This appeared in perl 5.10.0. Anything matched left of \f(CW\*(C`\eK\*(C'\fR is
+not included in \f(CW$&\fR, and will not be replaced if the pattern is
+used in a substitution. This lets you write \f(CW\*(C`s/PAT1 \eK PAT2/REPL/x\*(C'\fR
+instead of \f(CW\*(C`s/(PAT1) PAT2/${1}REPL/x\*(C'\fR or \f(CW\*(C`s/(?<=PAT1) PAT2/REPL/x\*(C'\fR.
+.Sp
+Mnemonic: \fIK\fReep.
+.IP \eN 4
+.IX Item "N"
+This feature, available starting in v5.12,  matches any character
+that is \fBnot\fR a newline.  It is a short-hand for writing \f(CW\*(C`[^\en]\*(C'\fR, and is
+identical to the \f(CW\*(C`.\*(C'\fR metasymbol, except under the \f(CW\*(C`/s\*(C'\fR flag, which changes
+the meaning of \f(CW\*(C`.\*(C'\fR, but not \f(CW\*(C`\eN\*(C'\fR.
+.Sp
+Note that \f(CW\*(C`\eN{...}\*(C'\fR can mean a
+named or numbered character
+\&.
+.Sp
+Mnemonic: Complement of \fI\en\fR.
+.IP \eR 4
+.IX Xref "\\R"
+.IX Item "R"
+\&\f(CW\*(C`\eR\*(C'\fR matches a \fIgeneric newline\fR; that is, anything considered a
+linebreak sequence by Unicode. This includes all characters matched by
+\&\f(CW\*(C`\ev\*(C'\fR (vertical whitespace), and the multi character sequence \f(CW"\ex0D\ex0A"\fR
+(carriage return followed by a line feed, sometimes called the network
+newline; it's the end of line sequence used in Microsoft text files opened
+in binary mode). \f(CW\*(C`\eR\*(C'\fR is equivalent to \f(CW\*(C`(?>\ex0D\ex0A|\ev)\*(C'\fR.  (The
+reason it doesn't backtrack is that the sequence is considered
+inseparable.  That means that
+.Sp
+.Vb 1
+\& "\ex0D\ex0A" =~ /^\eR\ex0A$/   # No match
+.Ve
+.Sp
+fails, because the \f(CW\*(C`\eR\*(C'\fR matches the entire string, and won't backtrack
+to match just the \f(CW"\ex0D"\fR.)  Since
+\&\f(CW\*(C`\eR\*(C'\fR can match a sequence of more than one character, it cannot be put
+inside a bracketed character class; \f(CW\*(C`/[\eR]/\*(C'\fR is an error; use \f(CW\*(C`\ev\*(C'\fR
+instead.  \f(CW\*(C`\eR\*(C'\fR was introduced in perl 5.10.0.
+.Sp
+Note that this does not respect any locale that might be in effect; it
+matches according to the platform's native character set.
+.Sp
+Mnemonic: none really. \f(CW\*(C`\eR\*(C'\fR was picked because PCRE already uses \f(CW\*(C`\eR\*(C'\fR,
+and more importantly because Unicode recommends such a regular expression
+metacharacter, and suggests \f(CW\*(C`\eR\*(C'\fR as its notation.
+.IP \eX 4
+.IX Xref "\\X"
+.IX Item "X"
+This matches a Unicode \fIextended grapheme cluster\fR.
+.Sp
+\&\f(CW\*(C`\eX\*(C'\fR matches quite well what normal (non-Unicode-programmer) usage
+would consider a single character.  As an example, consider a G with some sort
+of diacritic mark, such as an arrow.  There is no such single character in
+Unicode, but one can be composed by using a G followed by a Unicode "COMBINING
+UPWARDS ARROW BELOW", and would be displayed by Unicode-aware software as if it
+were a single character.
+.Sp
+The match is greedy and non-backtracking, so that the cluster is never
+broken up into smaller components.
+.Sp
+See also \f(CW\*(C`\eb{gcb}\*(C'\fR.
+.Sp
+Mnemonic: e\fIX\fRtended Unicode character.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 2
+\& $str =~ s/foo\eKbar/baz/g; # Change any \*(Aqbar\*(Aq following a \*(Aqfoo\*(Aq to \*(Aqbaz\*(Aq
+\& $str =~ s/(.)\eK\eg1//g;    # Delete duplicated characters.
+\&
+\& "\en"   =~ /^\eR$/;         # Match, \en   is a generic newline.
+\& "\er"   =~ /^\eR$/;         # Match, \er   is a generic newline.
+\& "\er\en" =~ /^\eR$/;         # Match, \er\en is a generic newline.
+\&
+\& "P\ex{307}" =~ /^\eX$/     # \eX matches a P with a dot above.
+.Ve
diff --git a/upstream/mageia-cauldron/man1/perlrecharclass.1 b/upstream/mageia-cauldron/man1/perlrecharclass.1
new file mode 100644
index 00000000..83c9dbea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlrecharclass.1
@@ -0,0 +1,1301 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLRECHARCLASS 1"
+.TH PERLRECHARCLASS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlrecharclass \- Perl Regular Expression Character Classes
+.IX Xref "character class"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The top level documentation about Perl regular expressions
+is found in perlre.
+.PP
+This manual page discusses the syntax and use of character
+classes in Perl regular expressions.
+.PP
+A character class is a way of denoting a set of characters
+in such a way that one character of the set is matched.
+It's important to remember that: matching a character class
+consumes exactly one character in the source string. (The source
+string is the string the regular expression is matched against.)
+.PP
+There are three types of character classes in Perl regular
+expressions: the dot, backslash sequences, and the form enclosed in square
+brackets.  Keep in mind, though, that often the term "character class" is used
+to mean just the bracketed form.  Certainly, most Perl documentation does that.
+.SS "The dot"
+.IX Subsection "The dot"
+The dot (or period), \f(CW\*(C`.\*(C'\fR is probably the most used, and certainly
+the most well-known character class. By default, a dot matches any
+character, except for the newline. That default can be changed to
+add matching the newline by using the \fIsingle line\fR modifier:
+for the entire regular expression with the \f(CW\*(C`/s\*(C'\fR modifier, or
+locally with \f(CW\*(C`(?s)\*(C'\fR  (and even globally within the scope of
+\&\f(CW\*(C`use re \*(Aq/s\*(Aq\*(C'\fR).  (The \f(CW"\eN"\fR backslash
+sequence, described
+below, matches any character except newline without regard to the
+\&\fIsingle line\fR modifier.)
+.PP
+Here are some examples:
+.PP
+.Vb 7
+\& "a"  =~  /./       # Match
+\& "."  =~  /./       # Match
+\& ""   =~  /./       # No match (dot has to match a character)
+\& "\en" =~  /./       # No match (dot does not match a newline)
+\& "\en" =~  /./s      # Match (global \*(Aqsingle line\*(Aq modifier)
+\& "\en" =~  /(?s:.)/  # Match (local \*(Aqsingle line\*(Aq modifier)
+\& "ab" =~  /^.$/     # No match (dot matches one character)
+.Ve
+.SS "Backslash sequences"
+.IX Xref "\\w \\W \\s \\S \\d \\D \\p \\P \\N \\v \\V \\h \\H word whitespace"
+.IX Subsection "Backslash sequences"
+A backslash sequence is a sequence of characters, the first one of which is a
+backslash.  Perl ascribes special meaning to many such sequences, and some of
+these are character classes.  That is, they match a single character each,
+provided that the character belongs to the specific set of characters defined
+by the sequence.
+.PP
+Here's a list of the backslash sequences that are character classes.  They
+are discussed in more detail below.  (For the backslash sequences that aren't
+character classes, see perlrebackslash.)
+.PP
+.Vb 10
+\& \ed             Match a decimal digit character.
+\& \eD             Match a non\-decimal\-digit character.
+\& \ew             Match a "word" character.
+\& \eW             Match a non\-"word" character.
+\& \es             Match a whitespace character.
+\& \eS             Match a non\-whitespace character.
+\& \eh             Match a horizontal whitespace character.
+\& \eH             Match a character that isn\*(Aqt horizontal whitespace.
+\& \ev             Match a vertical whitespace character.
+\& \eV             Match a character that isn\*(Aqt vertical whitespace.
+\& \eN             Match a character that isn\*(Aqt a newline.
+\& \epP, \ep{Prop}  Match a character that has the given Unicode property.
+\& \ePP, \eP{Prop}  Match a character that doesn\*(Aqt have the Unicode property
+.Ve
+.PP
+\fI\eN\fR
+.IX Subsection "N"
+.PP
+\&\f(CW\*(C`\eN\*(C'\fR, available starting in v5.12, like the dot, matches any
+character that is not a newline. The difference is that \f(CW\*(C`\eN\*(C'\fR is not influenced
+by the \fIsingle line\fR regular expression modifier (see "The dot" above).  Note
+that the form \f(CW\*(C`\eN{...}\*(C'\fR may mean something completely different.  When the
+\&\f(CW\*(C`{...}\*(C'\fR is a quantifier, it means to match a non-newline
+character that many times.  For example, \f(CW\*(C`\eN{3}\*(C'\fR means to match 3
+non-newlines; \f(CW\*(C`\eN{5,}\*(C'\fR means to match 5 or more non-newlines.  But if \f(CW\*(C`{...}\*(C'\fR
+is not a legal quantifier, it is presumed to be a named character.  See
+charnames for those.  For example, none of \f(CW\*(C`\eN{COLON}\*(C'\fR, \f(CW\*(C`\eN{4F}\*(C'\fR, and
+\&\f(CW\*(C`\eN{F4}\*(C'\fR contain legal quantifiers, so Perl will try to find characters whose
+names are respectively \f(CW\*(C`COLON\*(C'\fR, \f(CW\*(C`4F\*(C'\fR, and \f(CW\*(C`F4\*(C'\fR.
+.PP
+\fIDigits\fR
+.IX Subsection "Digits"
+.PP
+\&\f(CW\*(C`\ed\*(C'\fR matches a single character considered to be a decimal \fIdigit\fR.
+If the \f(CW\*(C`/a\*(C'\fR regular expression modifier is in effect, it matches [0\-9].
+Otherwise, it
+matches anything that is matched by \f(CW\*(C`\ep{Digit}\*(C'\fR, which includes [0\-9].
+(An unlikely possible exception is that under locale matching rules, the
+current locale might not have \f(CW\*(C`[0\-9]\*(C'\fR matched by \f(CW\*(C`\ed\*(C'\fR, and/or might match
+other characters whose code point is less than 256.  The only such locale
+definitions that are legal would be to match \f(CW\*(C`[0\-9]\*(C'\fR plus another set of
+10 consecutive digit characters;  anything else would be in violation of
+the C language standard, but Perl doesn't currently assume anything in
+regard to this.)
+.PP
+What this means is that unless the \f(CW\*(C`/a\*(C'\fR modifier is in effect \f(CW\*(C`\ed\*(C'\fR not
+only matches the digits '0' \- '9', but also Arabic, Devanagari, and
+digits from other languages.  This may cause some confusion, and some
+security issues.
+.PP
+Some digits that \f(CW\*(C`\ed\*(C'\fR matches look like some of the [0\-9] ones, but
+have different values.  For example, BENGALI DIGIT FOUR (U+09EA) looks
+very much like an ASCII DIGIT EIGHT (U+0038), and LEPCHA DIGIT SIX
+(U+1C46) looks very much like an ASCII DIGIT FIVE (U+0035).  An
+application that
+is expecting only the ASCII digits might be misled, or if the match is
+\&\f(CW\*(C`\ed+\*(C'\fR, the matched string might contain a mixture of digits from
+different writing systems that look like they signify a number different
+than they actually do.  "\fBnum()\fR" in Unicode::UCD can
+be used to safely
+calculate the value, returning \f(CW\*(C`undef\*(C'\fR if the input string contains
+such a mixture.  Otherwise, for example, a displayed price might be
+deliberately different than it appears.
+.PP
+What \f(CW\*(C`\ep{Digit}\*(C'\fR means (and hence \f(CW\*(C`\ed\*(C'\fR except under the \f(CW\*(C`/a\*(C'\fR
+modifier) is \f(CW\*(C`\ep{General_Category=Decimal_Number}\*(C'\fR, or synonymously,
+\&\f(CW\*(C`\ep{General_Category=Digit}\*(C'\fR.  Starting with Unicode version 4.1, this
+is the same set of characters matched by \f(CW\*(C`\ep{Numeric_Type=Decimal}\*(C'\fR.
+But Unicode also has a different property with a similar name,
+\&\f(CW\*(C`\ep{Numeric_Type=Digit}\*(C'\fR, which matches a completely different set of
+characters.  These characters are things such as \f(CW\*(C`CIRCLED DIGIT ONE\*(C'\fR
+or subscripts, or are from writing systems that lack all ten digits.
+.PP
+The design intent is for \f(CW\*(C`\ed\*(C'\fR to exactly match the set of characters
+that can safely be used with "normal" big-endian positional decimal
+syntax, where, for example 123 means one 'hundred', plus two 'tens',
+plus three 'ones'.  This positional notation does not necessarily apply
+to characters that match the other type of "digit",
+\&\f(CW\*(C`\ep{Numeric_Type=Digit}\*(C'\fR, and so \f(CW\*(C`\ed\*(C'\fR doesn't match them.
+.PP
+The Tamil digits (U+0BE6 \- U+0BEF) can also legally be
+used in old-style Tamil numbers in which they would appear no more than
+one in a row, separated by characters that mean "times 10", "times 100",
+etc.  (See <https://www.unicode.org/notes/tn21>.)
+.PP
+Any character not matched by \f(CW\*(C`\ed\*(C'\fR is matched by \f(CW\*(C`\eD\*(C'\fR.
+.PP
+\fIWord characters\fR
+.IX Subsection "Word characters"
+.PP
+A \f(CW\*(C`\ew\*(C'\fR matches a single alphanumeric character (an alphabetic character, or a
+decimal digit); or a connecting punctuation character, such as an
+underscore ("_"); or a "mark" character (like some sort of accent) that
+attaches to one of those.  It does not match a whole word.  To match a
+whole word, use \f(CW\*(C`\ew+\*(C'\fR.  This isn't the same thing as matching an
+English word, but in the ASCII range it is the same as a string of
+Perl-identifier characters.
+.ie n .IP "If the ""/a"" modifier is in effect ..." 4
+.el .IP "If the \f(CW/a\fR modifier is in effect ..." 4
+.IX Item "If the /a modifier is in effect ..."
+\&\f(CW\*(C`\ew\*(C'\fR matches the 63 characters [a\-zA\-Z0\-9_].
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+.RS 4
+.PD 0
+.IP "For code points above 255 ..." 4
+.IX Item "For code points above 255 ..."
+.PD
+\&\f(CW\*(C`\ew\*(C'\fR matches the same as \f(CW\*(C`\ep{Word}\*(C'\fR matches in this range.  That is,
+it matches Thai letters, Greek letters, etc.  This includes connector
+punctuation (like the underscore) which connect two words together, or
+diacritics, such as a \f(CW\*(C`COMBINING TILDE\*(C'\fR and the modifier letters, which
+are generally used to add auxiliary markings to letters.
+.IP "For code points below 256 ..." 4
+.IX Item "For code points below 256 ..."
+.RS 4
+.PD 0
+.IP "if locale rules are in effect ..." 4
+.IX Item "if locale rules are in effect ..."
+.PD
+\&\f(CW\*(C`\ew\*(C'\fR matches the platform's native underscore character plus whatever
+the locale considers to be alphanumeric.
+.IP "if, instead, Unicode rules are in effect ..." 4
+.IX Item "if, instead, Unicode rules are in effect ..."
+\&\f(CW\*(C`\ew\*(C'\fR matches exactly what \f(CW\*(C`\ep{Word}\*(C'\fR matches.
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+\&\f(CW\*(C`\ew\*(C'\fR matches [a\-zA\-Z0\-9_].
+.RE
+.RS 4
+.RE
+.RE
+.RS 4
+.RE
+.PP
+Which rules apply are determined as described in "Which character set modifier is in effect?" in perlre.
+.PP
+There are a number of security issues with the full Unicode list of word
+characters.  See <http://unicode.org/reports/tr36>.
+.PP
+Also, for a somewhat finer-grained set of characters that are in programming
+language identifiers beyond the ASCII range, you may wish to instead use the
+more customized "Unicode Properties", \f(CW\*(C`\ep{ID_Start}\*(C'\fR,
+\&\f(CW\*(C`\ep{ID_Continue}\*(C'\fR, \f(CW\*(C`\ep{XID_Start}\*(C'\fR, and \f(CW\*(C`\ep{XID_Continue}\*(C'\fR.  See
+<http://unicode.org/reports/tr31>.
+.PP
+Any character not matched by \f(CW\*(C`\ew\*(C'\fR is matched by \f(CW\*(C`\eW\*(C'\fR.
+.PP
+\fIWhitespace\fR
+.IX Subsection "Whitespace"
+.PP
+\&\f(CW\*(C`\es\*(C'\fR matches any single character considered whitespace.
+.ie n .IP "If the ""/a"" modifier is in effect ..." 4
+.el .IP "If the \f(CW/a\fR modifier is in effect ..." 4
+.IX Item "If the /a modifier is in effect ..."
+In all Perl versions, \f(CW\*(C`\es\*(C'\fR matches the 5 characters [\et\en\ef\er ]; that
+is, the horizontal tab,
+the newline, the form feed, the carriage return, and the space.
+Starting in Perl v5.18, it also matches the vertical tab, \f(CW\*(C`\ecK\*(C'\fR.
+See note \f(CW\*(C`[1]\*(C'\fR below for a discussion of this.
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+.RS 4
+.PD 0
+.IP "For code points above 255 ..." 4
+.IX Item "For code points above 255 ..."
+.PD
+\&\f(CW\*(C`\es\*(C'\fR matches exactly the code points above 255 shown with an "s" column
+in the table below.
+.IP "For code points below 256 ..." 4
+.IX Item "For code points below 256 ..."
+.RS 4
+.PD 0
+.IP "if locale rules are in effect ..." 4
+.IX Item "if locale rules are in effect ..."
+.PD
+\&\f(CW\*(C`\es\*(C'\fR matches whatever the locale considers to be whitespace.
+.IP "if, instead, Unicode rules are in effect ..." 4
+.IX Item "if, instead, Unicode rules are in effect ..."
+\&\f(CW\*(C`\es\*(C'\fR matches exactly the characters shown with an "s" column in the
+table below.
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+\&\f(CW\*(C`\es\*(C'\fR matches [\et\en\ef\er ] and, starting in Perl
+v5.18, the vertical tab, \f(CW\*(C`\ecK\*(C'\fR.
+(See note \f(CW\*(C`[1]\*(C'\fR below for a discussion of this.)
+Note that this list doesn't include the non-breaking space.
+.RE
+.RS 4
+.RE
+.RE
+.RS 4
+.RE
+.PP
+Which rules apply are determined as described in "Which character set modifier is in effect?" in perlre.
+.PP
+Any character not matched by \f(CW\*(C`\es\*(C'\fR is matched by \f(CW\*(C`\eS\*(C'\fR.
+.PP
+\&\f(CW\*(C`\eh\*(C'\fR matches any character considered horizontal whitespace;
+this includes the platform's space and tab characters and several others
+listed in the table below.  \f(CW\*(C`\eH\*(C'\fR matches any character
+not considered horizontal whitespace.  They use the platform's native
+character set, and do not consider any locale that may otherwise be in
+use.
+.PP
+\&\f(CW\*(C`\ev\*(C'\fR matches any character considered vertical whitespace;
+this includes the platform's carriage return and line feed characters (newline)
+plus several other characters, all listed in the table below.
+\&\f(CW\*(C`\eV\*(C'\fR matches any character not considered vertical whitespace.
+They use the platform's native character set, and do not consider any
+locale that may otherwise be in use.
+.PP
+\&\f(CW\*(C`\eR\*(C'\fR matches anything that can be considered a newline under Unicode
+rules. It can match a multi-character sequence. It cannot be used inside
+a bracketed character class; use \f(CW\*(C`\ev\*(C'\fR instead (vertical whitespace).
+It uses the platform's
+native character set, and does not consider any locale that may
+otherwise be in use.
+Details are discussed in perlrebackslash.
+.PP
+Note that unlike \f(CW\*(C`\es\*(C'\fR (and \f(CW\*(C`\ed\*(C'\fR and \f(CW\*(C`\ew\*(C'\fR), \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ev\*(C'\fR always match
+the same characters, without regard to other factors, such as the active
+locale or whether the source string is in UTF\-8 format.
+.PP
+One might think that \f(CW\*(C`\es\*(C'\fR is equivalent to \f(CW\*(C`[\eh\ev]\*(C'\fR. This is indeed true
+starting in Perl v5.18, but prior to that, the sole difference was that the
+vertical tab (\f(CW"\ecK"\fR) was not matched by \f(CW\*(C`\es\*(C'\fR.
+.PP
+The following table is a complete listing of characters matched by
+\&\f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ev\*(C'\fR as of Unicode 14.0.
+.PP
+The first column gives the Unicode code point of the character (in hex format),
+the second column gives the (Unicode) name. The third column indicates
+by which class(es) the character is matched (assuming no locale is in
+effect that changes the \f(CW\*(C`\es\*(C'\fR matching).
+.PP
+.Vb 10
+\& 0x0009        CHARACTER TABULATION   h s
+\& 0x000a              LINE FEED (LF)    vs
+\& 0x000b             LINE TABULATION    vs  [1]
+\& 0x000c              FORM FEED (FF)    vs
+\& 0x000d        CARRIAGE RETURN (CR)    vs
+\& 0x0020                       SPACE   h s
+\& 0x0085             NEXT LINE (NEL)    vs  [2]
+\& 0x00a0              NO\-BREAK SPACE   h s  [2]
+\& 0x1680            OGHAM SPACE MARK   h s
+\& 0x2000                     EN QUAD   h s
+\& 0x2001                     EM QUAD   h s
+\& 0x2002                    EN SPACE   h s
+\& 0x2003                    EM SPACE   h s
+\& 0x2004          THREE\-PER\-EM SPACE   h s
+\& 0x2005           FOUR\-PER\-EM SPACE   h s
+\& 0x2006            SIX\-PER\-EM SPACE   h s
+\& 0x2007                FIGURE SPACE   h s
+\& 0x2008           PUNCTUATION SPACE   h s
+\& 0x2009                  THIN SPACE   h s
+\& 0x200a                  HAIR SPACE   h s
+\& 0x2028              LINE SEPARATOR    vs
+\& 0x2029         PARAGRAPH SEPARATOR    vs
+\& 0x202f       NARROW NO\-BREAK SPACE   h s
+\& 0x205f   MEDIUM MATHEMATICAL SPACE   h s
+\& 0x3000           IDEOGRAPHIC SPACE   h s
+.Ve
+.IP [1] 4
+.IX Item "[1]"
+Prior to Perl v5.18, \f(CW\*(C`\es\*(C'\fR did not match the vertical tab.
+\&\f(CW\*(C`[^\eS\ecK]\*(C'\fR (obscurely) matches what \f(CW\*(C`\es\*(C'\fR traditionally did.
+.IP [2] 4
+.IX Item "[2]"
+NEXT LINE and NO-BREAK SPACE may or may not match \f(CW\*(C`\es\*(C'\fR depending
+on the rules in effect.  See
+the beginning of this section.
+.PP
+\fIUnicode Properties\fR
+.IX Subsection "Unicode Properties"
+.PP
+\&\f(CW\*(C`\epP\*(C'\fR and \f(CW\*(C`\ep{Prop}\*(C'\fR are character classes to match characters that fit given
+Unicode properties.  One letter property names can be used in the \f(CW\*(C`\epP\*(C'\fR form,
+with the property name following the \f(CW\*(C`\ep\*(C'\fR, otherwise, braces are required.
+When using braces, there is a single form, which is just the property name
+enclosed in the braces, and a compound form which looks like \f(CW\*(C`\ep{name=value}\*(C'\fR,
+which means to match if the property "name" for the character has that particular
+"value".
+For instance, a match for a number can be written as \f(CW\*(C`/\epN/\*(C'\fR or as
+\&\f(CW\*(C`/\ep{Number}/\*(C'\fR, or as \f(CW\*(C`/\ep{Number=True}/\*(C'\fR.
+Lowercase letters are matched by the property \fILowercase_Letter\fR which
+has the short form \fILl\fR. They need the braces, so are written as \f(CW\*(C`/\ep{Ll}/\*(C'\fR or
+\&\f(CW\*(C`/\ep{Lowercase_Letter}/\*(C'\fR, or \f(CW\*(C`/\ep{General_Category=Lowercase_Letter}/\*(C'\fR
+(the underscores are optional).
+\&\f(CW\*(C`/\epLl/\*(C'\fR is valid, but means something different.
+It matches a two character string: a letter (Unicode property \f(CW\*(C`\epL\*(C'\fR),
+followed by a lowercase \f(CW\*(C`l\*(C'\fR.
+.PP
+What a Unicode property matches is never subject to locale rules, and
+if locale rules are not otherwise in effect, the use of a Unicode
+property will force the regular expression into using Unicode rules, if
+it isn't already.
+.PP
+Note that almost all properties are immune to case-insensitive matching.
+That is, adding a \f(CW\*(C`/i\*(C'\fR regular expression modifier does not change what
+they match.  But there are two sets that are affected.  The first set is
+\&\f(CW\*(C`Uppercase_Letter\*(C'\fR,
+\&\f(CW\*(C`Lowercase_Letter\*(C'\fR,
+and \f(CW\*(C`Titlecase_Letter\*(C'\fR,
+all of which match \f(CW\*(C`Cased_Letter\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
+The second set is
+\&\f(CW\*(C`Uppercase\*(C'\fR,
+\&\f(CW\*(C`Lowercase\*(C'\fR,
+and \f(CW\*(C`Titlecase\*(C'\fR,
+all of which match \f(CW\*(C`Cased\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
+(The difference between these sets is that some things, such as Roman
+numerals, come in both upper and lower case, so they are \f(CW\*(C`Cased\*(C'\fR, but
+aren't considered to be letters, so they aren't \f(CW\*(C`Cased_Letter\*(C'\fRs. They're
+actually \f(CW\*(C`Letter_Number\*(C'\fRs.)
+This set also includes its subsets \f(CW\*(C`PosixUpper\*(C'\fR and \f(CW\*(C`PosixLower\*(C'\fR, both
+of which under \f(CW\*(C`/i\*(C'\fR match \f(CW\*(C`PosixAlpha\*(C'\fR.
+.PP
+For more details on Unicode properties, see "Unicode
+Character Properties" in perlunicode; for a
+complete list of possible properties, see
+"Properties accessible through \ep{} and \eP{}" in perluniprops,
+which notes all forms that have \f(CW\*(C`/i\*(C'\fR differences.
+It is also possible to define your own properties. This is discussed in
+"User-Defined Character Properties" in perlunicode.
+.PP
+Unicode properties are defined (surprise!) only on Unicode code points.
+Starting in v5.20, when matching against \f(CW\*(C`\ep\*(C'\fR and \f(CW\*(C`\eP\*(C'\fR, Perl treats
+non-Unicode code points (those above the legal Unicode maximum of
+0x10FFFF) as if they were typical unassigned Unicode code points.
+.PP
+Prior to v5.20, Perl raised a warning and made all matches fail on
+non-Unicode code points.  This could be somewhat surprising:
+.PP
+.Vb 3
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=True}     # Fails on Perls < v5.20.
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=False}    # Also fails on Perls
+\&                                               # < v5.20
+.Ve
+.PP
+Even though these two matches might be thought of as complements, until
+v5.20 they were so only on Unicode code points.
+.PP
+Starting in perl v5.30, wildcards are allowed in Unicode property
+values.  See "Wildcards in Property Values" in perlunicode.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 8
+\& "a"  =~  /\ew/      # Match, "a" is a \*(Aqword\*(Aq character.
+\& "7"  =~  /\ew/      # Match, "7" is a \*(Aqword\*(Aq character as well.
+\& "a"  =~  /\ed/      # No match, "a" isn\*(Aqt a digit.
+\& "7"  =~  /\ed/      # Match, "7" is a digit.
+\& " "  =~  /\es/      # Match, a space is whitespace.
+\& "a"  =~  /\eD/      # Match, "a" is a non\-digit.
+\& "7"  =~  /\eD/      # No match, "7" is not a non\-digit.
+\& " "  =~  /\eS/      # No match, a space is not non\-whitespace.
+\&
+\& " "  =~  /\eh/      # Match, space is horizontal whitespace.
+\& " "  =~  /\ev/      # No match, space is not vertical whitespace.
+\& "\er" =~  /\ev/      # Match, a return is vertical whitespace.
+\&
+\& "a"  =~  /\epL/     # Match, "a" is a letter.
+\& "a"  =~  /\ep{Lu}/  # No match, /\ep{Lu}/ matches upper case letters.
+\&
+\& "\ex{0e0b}" =~ /\ep{Thai}/  # Match, \ex{0e0b} is the character
+\&                           # \*(AqTHAI CHARACTER SO SO\*(Aq, and that\*(Aqs in
+\&                           # Thai Unicode class.
+\& "a"  =~  /\eP{Lao}/ # Match, as "a" is not a Laotian character.
+.Ve
+.PP
+It is worth emphasizing that \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, etc, match single characters, not
+complete numbers or words. To match a number (that consists of digits),
+use \f(CW\*(C`\ed+\*(C'\fR; to match a word, use \f(CW\*(C`\ew+\*(C'\fR.  But be aware of the security
+considerations in doing so, as mentioned above.
+.SS "Bracketed Character Classes"
+.IX Subsection "Bracketed Character Classes"
+The third form of character class you can use in Perl regular expressions
+is the bracketed character class.  In its simplest form, it lists the characters
+that may be matched, surrounded by square brackets, like this: \f(CW\*(C`[aeiou]\*(C'\fR.
+This matches one of \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`e\*(C'\fR, \f(CW\*(C`i\*(C'\fR, \f(CW\*(C`o\*(C'\fR or \f(CW\*(C`u\*(C'\fR.  Like the other
+character classes, exactly one character is matched.* To match
+a longer string consisting of characters mentioned in the character
+class, follow the character class with a quantifier.  For
+instance, \f(CW\*(C`[aeiou]+\*(C'\fR matches one or more lowercase English vowels.
+.PP
+Repeating a character in a character class has no
+effect; it's considered to be in the set only once.
+.PP
+Examples:
+.PP
+.Vb 5
+\& "e"  =~  /[aeiou]/        # Match, as "e" is listed in the class.
+\& "p"  =~  /[aeiou]/        # No match, "p" is not listed in the class.
+\& "ae" =~  /^[aeiou]$/      # No match, a character class only matches
+\&                           # a single character.
+\& "ae" =~  /^[aeiou]+$/     # Match, due to the quantifier.
+\&
+\& \-\-\-\-\-\-\-
+.Ve
+.PP
+* There are two exceptions to a bracketed character class matching a
+single character only.  Each requires special handling by Perl to make
+things work:
+.IP \(bu 4
+When the class is to match caselessly under \f(CW\*(C`/i\*(C'\fR matching rules, and a
+character that is explicitly mentioned inside the class matches a
+multiple-character sequence caselessly under Unicode rules, the class
+will also match that sequence.  For example, Unicode says that the
+letter \f(CW\*(C`LATIN SMALL LETTER SHARP S\*(C'\fR should match the sequence \f(CW\*(C`ss\*(C'\fR
+under \f(CW\*(C`/i\*(C'\fR rules.  Thus,
+.Sp
+.Vb 2
+\& \*(Aqss\*(Aq =~ /\eA\eN{LATIN SMALL LETTER SHARP S}\ez/i             # Matches
+\& \*(Aqss\*(Aq =~ /\eA[aeioust\eN{LATIN SMALL LETTER SHARP S}]\ez/i    # Matches
+.Ve
+.Sp
+For this to happen, the class must not be inverted (see "Negation")
+and the character must be explicitly specified, and not be part of a
+multi-character range (not even as one of its endpoints).  ("Character
+Ranges" will be explained shortly.) Therefore,
+.Sp
+.Vb 6
+\& \*(Aqss\*(Aq =~ /\eA[\e0\-\ex{ff}]\ez/ui       # Doesn\*(Aqt match
+\& \*(Aqss\*(Aq =~ /\eA[\e0\-\eN{LATIN SMALL LETTER SHARP S}]\ez/ui   # No match
+\& \*(Aqss\*(Aq =~ /\eA[\exDF\-\exDF]\ez/ui   # Matches on ASCII platforms, since
+\&                               # \exDF is LATIN SMALL LETTER SHARP S,
+\&                               # and the range is just a single
+\&                               # element
+.Ve
+.Sp
+Note that it isn't a good idea to specify these types of ranges anyway.
+.IP \(bu 4
+Some names known to \f(CW\*(C`\eN{...}\*(C'\fR refer to a sequence of multiple characters,
+instead of the usual single character.  When one of these is included in
+the class, the entire sequence is matched.  For example,
+.Sp
+.Vb 2
+\&  "\eN{TAMIL LETTER KA}\eN{TAMIL VOWEL SIGN AU}"
+\&                              =~ / ^ [\eN{TAMIL SYLLABLE KAU}]  $ /x;
+.Ve
+.Sp
+matches, because \f(CW\*(C`\eN{TAMIL SYLLABLE KAU}\*(C'\fR is a named sequence
+consisting of the two characters matched against.  Like the other
+instance where a bracketed class can match multiple characters, and for
+similar reasons, the class must not be inverted, and the named sequence
+may not appear in a range, even one where it is both endpoints.  If
+these happen, it is a fatal error if the character class is within the
+scope of \f(CW\*(C`use re \*(Aqstrict\*(C'\fR, or within an extended
+\&\f(CW\*(C`(?[...])\*(C'\fR class; otherwise
+only the first code point is used (with a \f(CW\*(C`regexp\*(C'\fR\-type warning
+raised).
+.PP
+\fISpecial Characters Inside a Bracketed Character Class\fR
+.IX Subsection "Special Characters Inside a Bracketed Character Class"
+.PP
+Most characters that are meta characters in regular expressions (that
+is, characters that carry a special meaning like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`*\*(C'\fR, or \f(CW\*(C`(\*(C'\fR) lose
+their special meaning and can be used inside a character class without
+the need to escape them. For instance, \f(CW\*(C`[()]\*(C'\fR matches either an opening
+parenthesis, or a closing parenthesis, and the parens inside the character
+class don't group or capture.  Be aware that, unless the pattern is
+evaluated in single-quotish context, variable interpolation will take
+place before the bracketed class is parsed:
+.PP
+.Vb 6
+\& $, = "\et| ";
+\& $a =~ m\*(Aq[$,]\*(Aq;        # single\-quotish: matches \*(Aq$\*(Aq or \*(Aq,\*(Aq
+\& $a =~ q{[$,]}\*(Aq        # same
+\& $a =~ m/[$,]/;        # double\-quotish: Because we made an
+\&                       #   assignment to $, above, this now
+\&                       #   matches "\et", "|", or " "
+.Ve
+.PP
+Characters that may carry a special meaning inside a character class are:
+\&\f(CW\*(C`\e\*(C'\fR, \f(CW\*(C`^\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR, and are discussed below. They can be
+escaped with a backslash, although this is sometimes not needed, in which
+case the backslash may be omitted.
+.PP
+The sequence \f(CW\*(C`\eb\*(C'\fR is special inside a bracketed character class. While
+outside the character class, \f(CW\*(C`\eb\*(C'\fR is an assertion indicating a point
+that does not have either two word characters or two non-word characters
+on either side, inside a bracketed character class, \f(CW\*(C`\eb\*(C'\fR matches a
+backspace character.
+.PP
+The sequences
+\&\f(CW\*(C`\ea\*(C'\fR,
+\&\f(CW\*(C`\ec\*(C'\fR,
+\&\f(CW\*(C`\ee\*(C'\fR,
+\&\f(CW\*(C`\ef\*(C'\fR,
+\&\f(CW\*(C`\en\*(C'\fR,
+\&\f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR,
+\&\f(CW\*(C`\eN{U+\fR\f(CIhex char\fR\f(CW}\*(C'\fR,
+\&\f(CW\*(C`\er\*(C'\fR,
+\&\f(CW\*(C`\et\*(C'\fR,
+and
+\&\f(CW\*(C`\ex\*(C'\fR
+are also special and have the same meanings as they do outside a
+bracketed character class.
+.PP
+Also, a backslash followed by two or three octal digits is considered an octal
+number.
+.PP
+A \f(CW\*(C`[\*(C'\fR is not special inside a character class, unless it's the start of a
+POSIX character class (see "POSIX Character Classes" below). It normally does
+not need escaping.
+.PP
+A \f(CW\*(C`]\*(C'\fR is normally either the end of a POSIX character class (see
+"POSIX Character Classes" below), or it signals the end of the bracketed
+character class.  If you want to include a \f(CW\*(C`]\*(C'\fR in the set of characters, you
+must generally escape it.
+.PP
+However, if the \f(CW\*(C`]\*(C'\fR is the \fIfirst\fR (or the second if the first
+character is a caret) character of a bracketed character class, it
+does not denote the end of the class (as you cannot have an empty class)
+and is considered part of the set of characters that can be matched without
+escaping.
+.PP
+Examples:
+.PP
+.Vb 8
+\& "+"   =~ /[+?*]/     #  Match, "+" in a character class is not special.
+\& "\ecH" =~ /[\eb]/      #  Match, \eb inside in a character class
+\&                      #  is equivalent to a backspace.
+\& "]"   =~ /[][]/      #  Match, as the character class contains
+\&                      #  both [ and ].
+\& "[]"  =~ /[[]]/      #  Match, the pattern contains a character class
+\&                      #  containing just [, and the character class is
+\&                      #  followed by a ].
+.Ve
+.PP
+\fIBracketed Character Classes and the \fR\f(CI\*(C`/xx\*(C'\fR\fI pattern modifier\fR
+.IX Subsection "Bracketed Character Classes and the /xx pattern modifier"
+.PP
+Normally SPACE and TAB characters have no special meaning inside a
+bracketed character class; they are just added to the list of characters
+matched by the class.  But if the \f(CW\*(C`/xx\*(C'\fR
+pattern modifier is in effect, they are generally ignored and can be
+added to improve readability.  They can't be added in the middle of a
+single construct:
+.PP
+.Vb 1
+\& / [ \ex{10 FFFF} ] /xx  # WRONG!
+.Ve
+.PP
+The SPACE in the middle of the hex constant is illegal.
+.PP
+To specify a literal SPACE character, you can escape it with a
+backslash, like:
+.PP
+.Vb 1
+\& /[ a e i o u \e  ]/xx
+.Ve
+.PP
+This matches the English vowels plus the SPACE character.
+.PP
+For clarity, you should already have been using \f(CW\*(C`\et\*(C'\fR to specify a
+literal tab, and \f(CW\*(C`\et\*(C'\fR is unaffected by \f(CW\*(C`/xx\*(C'\fR.
+.PP
+\fICharacter Ranges\fR
+.IX Subsection "Character Ranges"
+.PP
+It is not uncommon to want to match a range of characters. Luckily, instead
+of listing all characters in the range, one may use the hyphen (\f(CW\*(C`\-\*(C'\fR).
+If inside a bracketed character class you have two characters separated
+by a hyphen, it's treated as if all characters between the two were in
+the class. For instance, \f(CW\*(C`[0\-9]\*(C'\fR matches any ASCII digit, and \f(CW\*(C`[a\-m]\*(C'\fR
+matches any lowercase letter from the first half of the ASCII alphabet.
+.PP
+Note that the two characters on either side of the hyphen are not
+necessarily both letters or both digits. Any character is possible,
+although not advisable.  \f(CW\*(C`[\*(Aq\-?]\*(C'\fR contains a range of characters, but
+most people will not know which characters that means.  Furthermore,
+such ranges may lead to portability problems if the code has to run on
+a platform that uses a different character set, such as EBCDIC.
+.PP
+If a hyphen in a character class cannot syntactically be part of a range, for
+instance because it is the first or the last character of the character class,
+or if it immediately follows a range, the hyphen isn't special, and so is
+considered a character to be matched literally.  If you want a hyphen in
+your set of characters to be matched and its position in the class is such
+that it could be considered part of a range, you must escape that hyphen
+with a backslash.
+.PP
+Examples:
+.PP
+.Vb 12
+\& [a\-z]       #  Matches a character that is a lower case ASCII letter.
+\& [a\-fz]      #  Matches any letter between \*(Aqa\*(Aq and \*(Aqf\*(Aq (inclusive) or
+\&             #  the letter \*(Aqz\*(Aq.
+\& [\-z]        #  Matches either a hyphen (\*(Aq\-\*(Aq) or the letter \*(Aqz\*(Aq.
+\& [a\-f\-m]     #  Matches any letter between \*(Aqa\*(Aq and \*(Aqf\*(Aq (inclusive), the
+\&             #  hyphen (\*(Aq\-\*(Aq), or the letter \*(Aqm\*(Aq.
+\& [\*(Aq\-?]       #  Matches any of the characters  \*(Aq()*+,\-./0123456789:;<=>?
+\&             #  (But not on an EBCDIC platform).
+\& [\eN{APOSTROPHE}\-\eN{QUESTION MARK}]
+\&             #  Matches any of the characters  \*(Aq()*+,\-./0123456789:;<=>?
+\&             #  even on an EBCDIC platform.
+\& [\eN{U+27}\-\eN{U+3F}] # Same. (U+27 is "\*(Aq", and U+3F is "?")
+.Ve
+.PP
+As the final two examples above show, you can achieve portability to
+non-ASCII platforms by using the \f(CW\*(C`\eN{...}\*(C'\fR form for the range
+endpoints.  These indicate that the specified range is to be interpreted
+using Unicode values, so \f(CW\*(C`[\eN{U+27}\-\eN{U+3F}]\*(C'\fR means to match
+\&\f(CW\*(C`\eN{U+27}\*(C'\fR, \f(CW\*(C`\eN{U+28}\*(C'\fR, \f(CW\*(C`\eN{U+29}\*(C'\fR, ..., \f(CW\*(C`\eN{U+3D}\*(C'\fR, \f(CW\*(C`\eN{U+3E}\*(C'\fR,
+and \f(CW\*(C`\eN{U+3F}\*(C'\fR, whatever the native code point versions for those are.
+These are called "Unicode" ranges.  If either end is of the \f(CW\*(C`\eN{...}\*(C'\fR
+form, the range is considered Unicode.  A \f(CW\*(C`regexp\*(C'\fR warning is raised
+under \f(CW"use\ re\ \*(Aqstrict\*(Aq"\fR if the other endpoint is specified
+non-portably:
+.PP
+.Vb 2
+\& [\eN{U+00}\-\ex09]    # Warning under re \*(Aqstrict\*(Aq; \ex09 is non\-portable
+\& [\eN{U+00}\-\et]      # No warning;
+.Ve
+.PP
+Both of the above match the characters \f(CW\*(C`\eN{U+00}\*(C'\fR \f(CW\*(C`\eN{U+01}\*(C'\fR, ...
+\&\f(CW\*(C`\eN{U+08}\*(C'\fR, \f(CW\*(C`\eN{U+09}\*(C'\fR, but the \f(CW\*(C`\ex09\*(C'\fR looks like it could be a
+mistake so the warning is raised (under \f(CW\*(C`re \*(Aqstrict\*(Aq\*(C'\fR) for it.
+.PP
+Perl also guarantees that the ranges \f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, \f(CW\*(C`0\-9\*(C'\fR, and any
+subranges of these match what an English-only speaker would expect them
+to match on any platform.  That is, \f(CW\*(C`[A\-Z]\*(C'\fR matches the 26 ASCII
+uppercase letters;
+\&\f(CW\*(C`[a\-z]\*(C'\fR matches the 26 lowercase letters; and \f(CW\*(C`[0\-9]\*(C'\fR matches the 10
+digits.  Subranges, like \f(CW\*(C`[h\-k]\*(C'\fR, match correspondingly, in this case
+just the four letters \f(CW"h"\fR, \f(CW"i"\fR, \f(CW"j"\fR, and \f(CW"k"\fR.  This is the
+natural behavior on ASCII platforms where the code points (ordinal
+values) for \f(CW"h"\fR through \f(CW"k"\fR are consecutive integers (0x68 through
+0x6B).  But special handling to achieve this may be needed on platforms
+with a non-ASCII native character set.  For example, on EBCDIC
+platforms, the code point for \f(CW"h"\fR is 0x88, \f(CW"i"\fR is 0x89, \f(CW"j"\fR is
+0x91, and \f(CW"k"\fR is 0x92.   Perl specially treats \f(CW\*(C`[h\-k]\*(C'\fR to exclude the
+seven code points in the gap: 0x8A through 0x90.  This special handling is
+only invoked when the range is a subrange of one of the ASCII uppercase,
+lowercase, and digit ranges, AND each end of the range is expressed
+either as a literal, like \f(CW"A"\fR, or as a named character (\f(CW\*(C`\eN{...}\*(C'\fR,
+including the \f(CW\*(C`\eN{U+...\*(C'\fR form).
+.PP
+EBCDIC Examples:
+.PP
+.Vb 10
+\& [i\-j]               #  Matches either "i" or "j"
+\& [i\-\eN{LATIN SMALL LETTER J}]  # Same
+\& [i\-\eN{U+6A}]        #  Same
+\& [\eN{U+69}\-\eN{U+6A}] #  Same
+\& [\ex{89}\-\ex{91}]     #  Matches 0x89 ("i"), 0x8A .. 0x90, 0x91 ("j")
+\& [i\-\ex{91}]          #  Same
+\& [\ex{89}\-j]          #  Same
+\& [i\-J]               #  Matches, 0x89 ("i") .. 0xC1 ("J"); special
+\&                     #  handling doesn\*(Aqt apply because range is mixed
+\&                     #  case
+.Ve
+.PP
+\fINegation\fR
+.IX Subsection "Negation"
+.PP
+It is also possible to instead list the characters you do not want to
+match. You can do so by using a caret (\f(CW\*(C`^\*(C'\fR) as the first character in the
+character class. For instance, \f(CW\*(C`[^a\-z]\*(C'\fR matches any character that is not a
+lowercase ASCII letter, which therefore includes more than a million
+Unicode code points.  The class is said to be "negated" or "inverted".
+.PP
+This syntax make the caret a special character inside a bracketed character
+class, but only if it is the first character of the class. So if you want
+the caret as one of the characters to match, either escape the caret or
+else don't list it first.
+.PP
+In inverted bracketed character classes, Perl ignores the Unicode rules
+that normally say that named sequence, and certain characters should
+match a sequence of multiple characters use under caseless \f(CW\*(C`/i\*(C'\fR
+matching.  Following those rules could lead to highly confusing
+situations:
+.PP
+.Vb 1
+\& "ss" =~ /^[^\exDF]+$/ui;   # Matches!
+.Ve
+.PP
+This should match any sequences of characters that aren't \f(CW\*(C`\exDF\*(C'\fR nor
+what \f(CW\*(C`\exDF\*(C'\fR matches under \f(CW\*(C`/i\*(C'\fR.  \f(CW"s"\fR isn't \f(CW\*(C`\exDF\*(C'\fR, but Unicode
+says that \f(CW"ss"\fR is what \f(CW\*(C`\exDF\*(C'\fR matches under \f(CW\*(C`/i\*(C'\fR.  So which one
+"wins"? Do you fail the match because the string has \f(CW\*(C`ss\*(C'\fR or accept it
+because it has an \f(CW\*(C`s\*(C'\fR followed by another \f(CW\*(C`s\*(C'\fR?  Perl has chosen the
+latter.  (See note in "Bracketed Character Classes" above.)
+.PP
+Examples:
+.PP
+.Vb 4
+\& "e"  =~  /[^aeiou]/   #  No match, the \*(Aqe\*(Aq is listed.
+\& "x"  =~  /[^aeiou]/   #  Match, as \*(Aqx\*(Aq isn\*(Aqt a lowercase vowel.
+\& "^"  =~  /[^^]/       #  No match, matches anything that isn\*(Aqt a caret.
+\& "^"  =~  /[x^]/       #  Match, caret is not special here.
+.Ve
+.PP
+\fIBackslash Sequences\fR
+.IX Subsection "Backslash Sequences"
+.PP
+You can put any backslash sequence character class (with the exception of
+\&\f(CW\*(C`\eN\*(C'\fR and \f(CW\*(C`\eR\*(C'\fR) inside a bracketed character class, and it will act just
+as if you had put all characters matched by the backslash sequence inside the
+character class. For instance, \f(CW\*(C`[a\-f\ed]\*(C'\fR matches any decimal digit, or any
+of the lowercase letters between 'a' and 'f' inclusive.
+.PP
+\&\f(CW\*(C`\eN\*(C'\fR within a bracketed character class must be of the forms \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR
+or \f(CW\*(C`\eN{U+\fR\f(CIhex char\fR\f(CW}\*(C'\fR, and NOT be the form that matches non-newlines,
+for the same reason that a dot \f(CW\*(C`.\*(C'\fR inside a bracketed character class loses
+its special meaning: it matches nearly anything, which generally isn't what you
+want to happen.
+.PP
+Examples:
+.PP
+.Vb 4
+\& /[\ep{Thai}\ed]/     # Matches a character that is either a Thai
+\&                    # character, or a digit.
+\& /[^\ep{Arabic}()]/  # Matches a character that is neither an Arabic
+\&                    # character, nor a parenthesis.
+.Ve
+.PP
+Backslash sequence character classes cannot form one of the endpoints
+of a range.  Thus, you can't say:
+.PP
+.Vb 1
+\& /[\ep{Thai}\-\ed]/     # Wrong!
+.Ve
+.PP
+\fIPOSIX Character Classes\fR
+.IX Xref "character class \\p \\p{} alpha alnum ascii blank cntrl digit graph lower print punct space upper word xdigit"
+.IX Subsection "POSIX Character Classes"
+.PP
+POSIX character classes have the form \f(CW\*(C`[:class:]\*(C'\fR, where \fIclass\fR is the
+name, and the \f(CW\*(C`[:\*(C'\fR and \f(CW\*(C`:]\*(C'\fR delimiters. POSIX character classes only appear
+\&\fIinside\fR bracketed character classes, and are a convenient and descriptive
+way of listing a group of characters.
+.PP
+Be careful about the syntax,
+.PP
+.Vb 2
+\& # Correct:
+\& $string =~ /[[:alpha:]]/
+\&
+\& # Incorrect (will warn):
+\& $string =~ /[:alpha:]/
+.Ve
+.PP
+The latter pattern would be a character class consisting of a colon,
+and the letters \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`l\*(C'\fR, \f(CW\*(C`p\*(C'\fR and \f(CW\*(C`h\*(C'\fR.
+.PP
+POSIX character classes can be part of a larger bracketed character class.
+For example,
+.PP
+.Vb 1
+\& [01[:alpha:]%]
+.Ve
+.PP
+is valid and matches '0', '1', any alphabetic character, and the percent sign.
+.PP
+Perl recognizes the following POSIX character classes:
+.PP
+.Vb 10
+\& alpha  Any alphabetical character (e.g., [A\-Za\-z]).
+\& alnum  Any alphanumeric character (e.g., [A\-Za\-z0\-9]).
+\& ascii  Any character in the ASCII character set.
+\& blank  A GNU extension, equal to a space or a horizontal tab ("\et").
+\& cntrl  Any control character.  See Note [2] below.
+\& digit  Any decimal digit (e.g., [0\-9]), equivalent to "\ed".
+\& graph  Any printable character, excluding a space.  See Note [3] below.
+\& lower  Any lowercase character (e.g., [a\-z]).
+\& print  Any printable character, including a space.  See Note [4] below.
+\& punct  Any graphical character excluding "word" characters.  Note [5].
+\& space  Any whitespace character. "\es" including the vertical tab
+\&        ("\ecK").
+\& upper  Any uppercase character (e.g., [A\-Z]).
+\& word   A Perl extension (e.g., [A\-Za\-z0\-9_]), equivalent to "\ew".
+\& xdigit Any hexadecimal digit (e.g., [0\-9a\-fA\-F]).  Note [7].
+.Ve
+.PP
+Like the Unicode properties, most of the POSIX
+properties match the same regardless of whether case-insensitive (\f(CW\*(C`/i\*(C'\fR)
+matching is in effect or not.  The two exceptions are \f(CW\*(C`[:upper:]\*(C'\fR and
+\&\f(CW\*(C`[:lower:]\*(C'\fR.  Under \f(CW\*(C`/i\*(C'\fR, they each match the union of \f(CW\*(C`[:upper:]\*(C'\fR and
+\&\f(CW\*(C`[:lower:]\*(C'\fR.
+.PP
+Most POSIX character classes have two Unicode-style \f(CW\*(C`\ep\*(C'\fR property
+counterparts.  (They are not official Unicode properties, but Perl extensions
+derived from official Unicode properties.)  The table below shows the relation
+between POSIX character classes and these counterparts.
+.PP
+One counterpart, in the column labelled "ASCII-range Unicode" in
+the table, matches only characters in the ASCII character set.
+.PP
+The other counterpart, in the column labelled "Full-range Unicode", matches any
+appropriate characters in the full Unicode character set.  For example,
+\&\f(CW\*(C`\ep{Alpha}\*(C'\fR matches not just the ASCII alphabetic characters, but any
+character in the entire Unicode character set considered alphabetic.
+An entry in the column labelled "backslash sequence" is a (short)
+equivalent.
+.PP
+.Vb 10
+\& [[:...:]]      ASCII\-range          Full\-range  backslash  Note
+\&                 Unicode              Unicode     sequence
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&   alpha      \ep{PosixAlpha}       \ep{XPosixAlpha}
+\&   alnum      \ep{PosixAlnum}       \ep{XPosixAlnum}
+\&   ascii      \ep{ASCII}
+\&   blank      \ep{PosixBlank}       \ep{XPosixBlank}  \eh      [1]
+\&                                   or \ep{HorizSpace}        [1]
+\&   cntrl      \ep{PosixCntrl}       \ep{XPosixCntrl}          [2]
+\&   digit      \ep{PosixDigit}       \ep{XPosixDigit}  \ed
+\&   graph      \ep{PosixGraph}       \ep{XPosixGraph}          [3]
+\&   lower      \ep{PosixLower}       \ep{XPosixLower}
+\&   print      \ep{PosixPrint}       \ep{XPosixPrint}          [4]
+\&   punct      \ep{PosixPunct}       \ep{XPosixPunct}          [5]
+\&              \ep{PerlSpace}        \ep{XPerlSpace}   \es      [6]
+\&   space      \ep{PosixSpace}       \ep{XPosixSpace}          [6]
+\&   upper      \ep{PosixUpper}       \ep{XPosixUpper}
+\&   word       \ep{PosixWord}        \ep{XPosixWord}   \ew
+\&   xdigit     \ep{PosixXDigit}      \ep{XPosixXDigit}         [7]
+.Ve
+.IP [1] 4
+.IX Item "[1]"
+\&\f(CW\*(C`\ep{Blank}\*(C'\fR and \f(CW\*(C`\ep{HorizSpace}\*(C'\fR are synonyms.
+.IP [2] 4
+.IX Item "[2]"
+Control characters don't produce output as such, but instead usually control
+the terminal somehow: for example, newline and backspace are control characters.
+On ASCII platforms, in the ASCII range, characters whose code points are
+between 0 and 31 inclusive, plus 127 (\f(CW\*(C`DEL\*(C'\fR) are control characters; on
+EBCDIC platforms, their counterparts are control characters.
+.IP [3] 4
+.IX Item "[3]"
+Any character that is \fIgraphical\fR, that is, visible. This class consists
+of all alphanumeric characters and all punctuation characters.
+.IP [4] 4
+.IX Item "[4]"
+All printable characters, which is the set of all graphical characters
+plus those whitespace characters which are not also controls.
+.IP [5] 4
+.IX Item "[5]"
+\&\f(CW\*(C`\ep{PosixPunct}\*(C'\fR and \f(CW\*(C`[[:punct:]]\*(C'\fR in the ASCII range match all
+non-controls, non-alphanumeric, non-space characters:
+\&\f(CW\*(C`[\-!"#$%&\*(Aq()*+,./:;<=>?@[\e\e\e]^_\`{|}~]\*(C'\fR (although if a locale is in effect,
+it could alter the behavior of \f(CW\*(C`[[:punct:]]\*(C'\fR).
+.Sp
+The similarly named property, \f(CW\*(C`\ep{Punct}\*(C'\fR, matches a somewhat different
+set in the ASCII range, namely
+\&\f(CW\*(C`[\-!"#%&\*(Aq()*,./:;?@[\e\e\e]_{}]\*(C'\fR.  That is, it is missing the nine
+characters \f(CW\*(C`[$+<=>^\`|~]\*(C'\fR.
+This is because Unicode splits what POSIX considers to be punctuation into two
+categories, Punctuation and Symbols.
+.Sp
+\&\f(CW\*(C`\ep{XPosixPunct}\*(C'\fR and (under Unicode rules) \f(CW\*(C`[[:punct:]]\*(C'\fR, match what
+\&\f(CW\*(C`\ep{PosixPunct}\*(C'\fR matches in the ASCII range, plus what \f(CW\*(C`\ep{Punct}\*(C'\fR
+matches.  This is different than strictly matching according to
+\&\f(CW\*(C`\ep{Punct}\*(C'\fR.  Another way to say it is that
+if Unicode rules are in effect, \f(CW\*(C`[[:punct:]]\*(C'\fR matches all characters
+that Unicode considers punctuation, plus all ASCII-range characters that
+Unicode considers symbols.
+.IP [6] 4
+.IX Item "[6]"
+\&\f(CW\*(C`\ep{XPerlSpace}\*(C'\fR and \f(CW\*(C`\ep{Space}\*(C'\fR match identically starting with Perl
+v5.18.  In earlier versions, these differ only in that in non-locale
+matching, \f(CW\*(C`\ep{XPerlSpace}\*(C'\fR did not match the vertical tab, \f(CW\*(C`\ecK\*(C'\fR.
+Same for the two ASCII-only range forms.
+.IP [7] 4
+.IX Item "[7]"
+Unlike \f(CW\*(C`[[:digit:]]\*(C'\fR which matches digits in many writing systems, such
+as Thai and Devanagari, there are currently only two sets of hexadecimal
+digits, and it is unlikely that more will be added.  This is because you
+not only need the ten digits, but also the six \f(CW\*(C`[A\-F]\*(C'\fR (and \f(CW\*(C`[a\-f]\*(C'\fR)
+to correspond.  That means only the Latin script is suitable for these,
+and Unicode has only two sets of these, the familiar ASCII set, and the
+fullwidth forms starting at U+FF10 (FULLWIDTH DIGIT ZERO).
+.PP
+There are various other synonyms that can be used besides the names
+listed in the table.  For example, \f(CW\*(C`\ep{XPosixAlpha}\*(C'\fR can be written as
+\&\f(CW\*(C`\ep{Alpha}\*(C'\fR.  All are listed in
+"Properties accessible through \ep{} and \eP{}" in perluniprops.
+.PP
+Both the \f(CW\*(C`\ep\*(C'\fR counterparts always assume Unicode rules are in effect.
+On ASCII platforms, this means they assume that the code points from 128
+to 255 are Latin\-1, and that means that using them under locale rules is
+unwise unless the locale is guaranteed to be Latin\-1 or UTF\-8.  In contrast, the
+POSIX character classes are useful under locale rules.  They are
+affected by the actual rules in effect, as follows:
+.ie n .IP "If the ""/a"" modifier, is in effect ..." 4
+.el .IP "If the \f(CW/a\fR modifier, is in effect ..." 4
+.IX Item "If the /a modifier, is in effect ..."
+Each of the POSIX classes matches exactly the same as their ASCII-range
+counterparts.
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+.RS 4
+.PD 0
+.IP "For code points above 255 ..." 4
+.IX Item "For code points above 255 ..."
+.PD
+The POSIX class matches the same as its Full-range counterpart.
+.IP "For code points below 256 ..." 4
+.IX Item "For code points below 256 ..."
+.RS 4
+.PD 0
+.IP "if locale rules are in effect ..." 4
+.IX Item "if locale rules are in effect ..."
+.PD
+The POSIX class matches according to the locale, except:
+.RS 4
+.ie n .IP """word""" 4
+.el .IP \f(CWword\fR 4
+.IX Item "word"
+also includes the platform's native underscore character, no matter what
+the locale is.
+.ie n .IP """ascii""" 4
+.el .IP \f(CWascii\fR 4
+.IX Item "ascii"
+on platforms that don't have the POSIX \f(CW\*(C`ascii\*(C'\fR extension, this matches
+just the platform's native ASCII-range characters.
+.ie n .IP """blank""" 4
+.el .IP \f(CWblank\fR 4
+.IX Item "blank"
+on platforms that don't have the POSIX \f(CW\*(C`blank\*(C'\fR extension, this matches
+just the platform's native tab and space characters.
+.RE
+.RS 4
+.RE
+.IP "if, instead, Unicode rules are in effect ..." 4
+.IX Item "if, instead, Unicode rules are in effect ..."
+The POSIX class matches the same as the Full-range counterpart.
+.IP "otherwise ..." 4
+.IX Item "otherwise ..."
+The POSIX class matches the same as the ASCII range counterpart.
+.RE
+.RS 4
+.RE
+.RE
+.RS 4
+.RE
+.PP
+Which rules apply are determined as described in
+"Which character set modifier is in effect?" in perlre.
+.PP
+Negation of POSIX character classes
+.IX Xref "character class, negation"
+.IX Subsection "Negation of POSIX character classes"
+.PP
+A Perl extension to the POSIX character class is the ability to
+negate it. This is done by prefixing the class name with a caret (\f(CW\*(C`^\*(C'\fR).
+Some examples:
+.PP
+.Vb 7
+\&     POSIX         ASCII\-range     Full\-range  backslash
+\&                    Unicode         Unicode    sequence
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& [[:^digit:]]   \eP{PosixDigit}  \eP{XPosixDigit}   \eD
+\& [[:^space:]]   \eP{PosixSpace}  \eP{XPosixSpace}
+\&                \eP{PerlSpace}   \eP{XPerlSpace}    \eS
+\& [[:^word:]]    \eP{PerlWord}    \eP{XPosixWord}    \eW
+.Ve
+.PP
+The backslash sequence can mean either ASCII\- or Full-range Unicode,
+depending on various factors as described in "Which character set modifier is in effect?" in perlre.
+.PP
+[= =] and [. .]
+.IX Subsection "[= =] and [. .]"
+.PP
+Perl recognizes the POSIX character classes \f(CW\*(C`[=class=]\*(C'\fR and
+\&\f(CW\*(C`[.class.]\*(C'\fR, but does not (yet?) support them.  Any attempt to use
+either construct raises an exception.
+.PP
+Examples
+.IX Subsection "Examples"
+.PP
+.Vb 12
+\& /[[:digit:]]/            # Matches a character that is a digit.
+\& /[01[:lower:]]/          # Matches a character that is either a
+\&                          # lowercase letter, or \*(Aq0\*(Aq or \*(Aq1\*(Aq.
+\& /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
+\&                          # except the letters \*(Aqa\*(Aq to \*(Aqf\*(Aq and \*(AqA\*(Aq to
+\&                          # \*(AqF\*(Aq.  This is because the main character
+\&                          # class is composed of two POSIX character
+\&                          # classes that are ORed together, one that
+\&                          # matches any digit, and the other that
+\&                          # matches anything that isn\*(Aqt a hex digit.
+\&                          # The OR adds the digits, leaving only the
+\&                          # letters \*(Aqa\*(Aq to \*(Aqf\*(Aq and \*(AqA\*(Aq to \*(AqF\*(Aq excluded.
+.Ve
+.PP
+\fIExtended Bracketed Character Classes\fR
+.IX Xref "character class set operations"
+.IX Subsection "Extended Bracketed Character Classes"
+.PP
+This is a fancy bracketed character class that can be used for more
+readable and less error-prone classes, and to perform set operations,
+such as intersection. An example is
+.PP
+.Vb 1
+\& /(?[ \ep{Thai} & \ep{Digit} ])/
+.Ve
+.PP
+This will match all the digit characters that are in the Thai script.
+.PP
+This feature became available in Perl 5.18, as experimental; accepted in
+5.36.
+.PP
+The rules used by \f(CW\*(C`use re \*(Aqstrict\*(C'\fR apply to this
+construct.
+.PP
+We can extend the example above:
+.PP
+.Vb 1
+\& /(?[ ( \ep{Thai} + \ep{Lao} ) & \ep{Digit} ])/
+.Ve
+.PP
+This matches digits that are in either the Thai or Laotian scripts.
+.PP
+Notice the white space in these examples.  This construct always has
+the \f(CW\*(C`/xx\*(C'\fR modifier turned on within it.
+.PP
+The available binary operators are:
+.PP
+.Vb 10
+\& &    intersection
+\& +    union
+\& |    another name for \*(Aq+\*(Aq, hence means union
+\& \-    subtraction (the result matches the set consisting of those
+\&      code points matched by the first operand, excluding any that
+\&      are also matched by the second operand)
+\& ^    symmetric difference (the union minus the intersection).  This
+\&      is like an exclusive or, in that the result is the set of code
+\&      points that are matched by either, but not both, of the
+\&      operands.
+.Ve
+.PP
+There is one unary operator:
+.PP
+.Vb 1
+\& !    complement
+.Ve
+.PP
+All the binary operators left associate; \f(CW"&"\fR is higher precedence
+than the others, which all have equal precedence.  The unary operator
+right associates, and has highest precedence.  Thus this follows the
+normal Perl precedence rules for logical operators.  Use parentheses to
+override the default precedence and associativity.
+.PP
+The main restriction is that everything is a metacharacter.  Thus,
+you cannot refer to single characters by doing something like this:
+.PP
+.Vb 1
+\& /(?[ a + b ])/ # Syntax error!
+.Ve
+.PP
+The easiest way to specify an individual typable character is to enclose
+it in brackets:
+.PP
+.Vb 1
+\& /(?[ [a] + [b] ])/
+.Ve
+.PP
+(This is the same thing as \f(CW\*(C`[ab]\*(C'\fR.)  You could also have said the
+equivalent:
+.PP
+.Vb 1
+\& /(?[[ a b ]])/
+.Ve
+.PP
+(You can, of course, specify single characters by using, \f(CW\*(C`\ex{...}\*(C'\fR,
+\&\f(CW\*(C`\eN{...}\*(C'\fR, etc.)
+.PP
+This last example shows the use of this construct to specify an ordinary
+bracketed character class without additional set operations.  Note the
+white space within it.  This is allowed because \f(CW\*(C`/xx\*(C'\fR is
+automatically turned on within this construct.
+.PP
+All the other escapes accepted by normal bracketed character classes are
+accepted here as well.
+.PP
+Because this construct compiles under
+\&\f(CW\*(C`use re \*(Aqstrict\*(C'\fR,  unrecognized escapes that
+generate warnings in normal classes are fatal errors here, as well as
+all other warnings from these class elements, as well as some
+practices that don't currently warn outside \f(CW\*(C`re \*(Aqstrict\*(Aq\*(C'\fR.  For example
+you cannot say
+.PP
+.Vb 1
+\& /(?[ [ \exF ] ])/     # Syntax error!
+.Ve
+.PP
+You have to have two hex digits after a braceless \f(CW\*(C`\ex\*(C'\fR (use a leading
+zero to make two).  These restrictions are to lower the incidence of
+typos causing the class to not match what you thought it would.
+.PP
+If a regular bracketed character class contains a \f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR and
+is matched against a non-Unicode code point, a warning may be
+raised, as the result is not Unicode-defined.  No such warning will come
+when using this extended form.
+.PP
+The final difference between regular bracketed character classes and
+these, is that it is not possible to get these to match a
+multi-character fold.  Thus,
+.PP
+.Vb 1
+\& /(?[ [\exDF] ])/iu
+.Ve
+.PP
+does not match the string \f(CW\*(C`ss\*(C'\fR.
+.PP
+You don't have to enclose POSIX class names inside double brackets,
+hence both of the following work:
+.PP
+.Vb 2
+\& /(?[ [:word:] \- [:lower:] ])/
+\& /(?[ [[:word:]] \- [[:lower:]] ])/
+.Ve
+.PP
+Any contained POSIX character classes, including things like \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eD\*(C'\fR
+respect the \f(CW\*(C`/a\*(C'\fR (and \f(CW\*(C`/aa\*(C'\fR) modifiers.
+.PP
+Note that \f(CW\*(C`(?[ ])\*(C'\fR is a regex-compile-time construct.  Any attempt
+to use something which isn't knowable at the time the containing regular
+expression is compiled is a fatal error.  In practice, this means
+just three limitations:
+.IP 1. 4
+When compiled within the scope of \f(CW\*(C`use locale\*(C'\fR (or the \f(CW\*(C`/l\*(C'\fR regex
+modifier), this construct assumes that the execution-time locale will be
+a UTF\-8 one, and the generated pattern always uses Unicode rules.  What
+gets matched or not thus isn't dependent on the actual runtime locale, so
+tainting is not enabled.  But a \f(CW\*(C`locale\*(C'\fR category warning is raised
+if the runtime locale turns out to not be UTF\-8.
+.IP 2. 4
+Any
+user-defined property
+used must be already defined by the time the regular expression is
+compiled (but note that this construct can be used instead of such
+properties).
+.IP 3. 4
+A regular expression that otherwise would compile
+using \f(CW\*(C`/d\*(C'\fR rules, and which uses this construct will instead
+use \f(CW\*(C`/u\*(C'\fR.  Thus this construct tells Perl that you don't want
+\&\f(CW\*(C`/d\*(C'\fR rules for the entire regular expression containing it.
+.PP
+Note that skipping white space applies only to the interior of this
+construct.  There must not be any space between any of the characters
+that form the initial \f(CW\*(C`(?[\*(C'\fR.  Nor may there be space between the
+closing \f(CW\*(C`])\*(C'\fR characters.
+.PP
+Just as in all regular expressions, the pattern can be built up by
+including variables that are interpolated at regex compilation time.
+But currently each such sub-component should be an already-compiled
+extended bracketed character class.
+.PP
+.Vb 3
+\& my $thai_or_lao = qr/(?[ \ep{Thai} + \ep{Lao} ])/;
+\& ...
+\& qr/(?[ \ep{Digit} & $thai_or_lao ])/;
+.Ve
+.PP
+If you interpolate something else, the pattern may still compile (or it
+may die), but if it compiles, it very well may not behave as you would
+expect:
+.PP
+.Vb 2
+\& my $thai_or_lao = \*(Aq\ep{Thai} + \ep{Lao}\*(Aq;
+\& qr/(?[ \ep{Digit} & $thai_or_lao ])/;
+.Ve
+.PP
+compiles to
+.PP
+.Vb 1
+\& qr/(?[ \ep{Digit} & \ep{Thai} + \ep{Lao} ])/;
+.Ve
+.PP
+This does not have the effect that someone reading the source code
+would likely expect, as the intersection applies just to \f(CW\*(C`\ep{Thai}\*(C'\fR,
+excluding the Laotian.
+.PP
+Due to the way that Perl parses things, your parentheses and brackets
+may need to be balanced, even including comments.  If you run into any
+examples, please submit them to <https://github.com/Perl/perl5/issues>,
+so that we can have a concrete example for this man page.
diff --git a/upstream/mageia-cauldron/man1/perlref.1 b/upstream/mageia-cauldron/man1/perlref.1
new file mode 100644
index 00000000..3ad05236
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlref.1
@@ -0,0 +1,1123 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREF 1"
+.TH PERLREF 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlref \- Perl references and nested data structures
+.IX Xref "reference pointer data structure structure struct"
+.SH NOTE
+.IX Header "NOTE"
+This is complete documentation about all aspects of references.
+For a shorter, tutorial introduction to just the essential features,
+see perlreftut.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Before release 5 of Perl it was difficult to represent complex data
+structures, because all references had to be symbolic\-\-and even then
+it was difficult to refer to a variable instead of a symbol table entry.
+Perl now not only makes it easier to use symbolic references to variables,
+but also lets you have "hard" references to any piece of data or code.
+Any scalar may hold a hard reference.  Because arrays and hashes contain
+scalars, you can now easily build arrays of arrays, arrays of hashes,
+hashes of arrays, arrays of hashes of functions, and so on.
+.PP
+Hard references are smart\-\-they keep track of reference counts for you,
+automatically freeing the thing referred to when its reference count goes
+to zero.  (Reference counts for values in self-referential or
+cyclic data structures may not go to zero without a little help; see
+"Circular References" for a detailed explanation.)
+If that thing happens to be an object, the object is destructed.  See
+perlobj for more about objects.  (In a sense, everything in Perl is an
+object, but we usually reserve the word for references to objects that
+have been officially "blessed" into a class package.)
+.PP
+Symbolic references are names of variables or other objects, just as a
+symbolic link in a Unix filesystem contains merely the name of a file.
+The \f(CW*glob\fR notation is something of a symbolic reference.  (Symbolic
+references are sometimes called "soft references", but please don't call
+them that; references are confusing enough without useless synonyms.)
+.IX Xref "reference, symbolic reference, soft symbolic reference soft reference"
+.PP
+In contrast, hard references are more like hard links in a Unix file
+system: They are used to access an underlying object without concern for
+what its (other) name is.  When the word "reference" is used without an
+adjective, as in the following paragraph, it is usually talking about a
+hard reference.
+.IX Xref "reference, hard hard reference"
+.PP
+References are easy to use in Perl.  There is just one overriding
+principle: in general, Perl does no implicit referencing or dereferencing.
+When a scalar is holding a reference, it always behaves as a simple scalar.
+It doesn't magically start being an array or hash or subroutine; you have to
+tell it explicitly to do so, by dereferencing it.
+.SS "Making References"
+.IX Xref "reference, creation referencing"
+.IX Subsection "Making References"
+References can be created in several ways.
+.PP
+\fIBackslash Operator\fR
+.IX Xref "\\ backslash"
+.IX Subsection "Backslash Operator"
+.PP
+By using the backslash operator on a variable, subroutine, or value.
+(This works much like the & (address-of) operator in C.)
+This typically creates \fIanother\fR reference to a variable, because
+there's already a reference to the variable in the symbol table.  But
+the symbol table reference might go away, and you'll still have the
+reference that the backslash returned.  Here are some examples:
+.PP
+.Vb 5
+\&    $scalarref = \e$foo;
+\&    $arrayref  = \e@ARGV;
+\&    $hashref   = \e%ENV;
+\&    $coderef   = \e&handler;
+\&    $globref   = \e*foo;
+.Ve
+.PP
+It isn't possible to create a true reference to an IO handle (filehandle
+or dirhandle) using the backslash operator.  The most you can get is a
+reference to a typeglob, which is actually a complete symbol table entry.
+But see the explanation of the \f(CW*foo{THING}\fR syntax below.  However,
+you can still use type globs and globrefs as though they were IO handles.
+.PP
+\fISquare Brackets\fR
+.IX Xref "array, anonymous [ [] square bracket bracket, square arrayref array reference reference, array"
+.IX Subsection "Square Brackets"
+.PP
+A reference to an anonymous array can be created using square
+brackets:
+.PP
+.Vb 1
+\&    $arrayref = [1, 2, [\*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq]];
+.Ve
+.PP
+Here we've created a reference to an anonymous array of three elements
+whose final element is itself a reference to another anonymous array of three
+elements.  (The multidimensional syntax described later can be used to
+access this.  For example, after the above, \f(CW\*(C`$arrayref\->[2][1]\*(C'\fR would have
+the value "b".)
+.PP
+Taking a reference to an enumerated list is not the same
+as using square brackets\-\-instead it's the same as creating
+a list of references!
+.PP
+.Vb 2
+\&    @list = (\e$a, \e@b, \e%c);
+\&    @list = \e($a, @b, %c);      # same thing!
+.Ve
+.PP
+As a special case, \f(CW\*(C`\e(@foo)\*(C'\fR returns a list of references to the contents
+of \f(CW@foo\fR, not a reference to \f(CW@foo\fR itself.  Likewise for \f(CW%foo\fR,
+except that the key references are to copies (since the keys are just
+strings rather than full-fledged scalars).
+.PP
+\fICurly Brackets\fR
+.IX Xref "hash, anonymous { {} curly bracket bracket, curly brace hashref hash reference reference, hash"
+.IX Subsection "Curly Brackets"
+.PP
+A reference to an anonymous hash can be created using curly
+brackets:
+.PP
+.Vb 4
+\&    $hashref = {
+\&        \*(AqAdam\*(Aq  => \*(AqEve\*(Aq,
+\&        \*(AqClyde\*(Aq => \*(AqBonnie\*(Aq,
+\&    };
+.Ve
+.PP
+Anonymous hash and array composers like these can be intermixed freely to
+produce as complicated a structure as you want.  The multidimensional
+syntax described below works for these too.  The values above are
+literals, but variables and expressions would work just as well, because
+assignment operators in Perl (even within \fBlocal()\fR or \fBmy()\fR) are executable
+statements, not compile-time declarations.
+.PP
+Because curly brackets (braces) are used for several other things
+including BLOCKs, you may occasionally have to disambiguate braces at the
+beginning of a statement by putting a \f(CW\*(C`+\*(C'\fR or a \f(CW\*(C`return\*(C'\fR in front so
+that Perl realizes the opening brace isn't starting a BLOCK.  The economy and
+mnemonic value of using curlies is deemed worth this occasional extra
+hassle.
+.PP
+For example, if you wanted a function to make a new hash and return a
+reference to it, you have these options:
+.PP
+.Vb 3
+\&    sub hashem {        { @_ } }   # silently wrong
+\&    sub hashem {       +{ @_ } }   # ok
+\&    sub hashem { return { @_ } }   # ok
+.Ve
+.PP
+On the other hand, if you want the other meaning, you can do this:
+.PP
+.Vb 4
+\&    sub showem {        { @_ } }   # ambiguous (currently ok,
+\&                                   # but may change)
+\&    sub showem {       {; @_ } }   # ok
+\&    sub showem { { return @_ } }   # ok
+.Ve
+.PP
+The leading \f(CW\*(C`+{\*(C'\fR and \f(CW\*(C`{;\*(C'\fR always serve to disambiguate
+the expression to mean either the HASH reference, or the BLOCK.
+.PP
+\fIAnonymous Subroutines\fR
+.IX Xref "subroutine, anonymous subroutine, reference reference, subroutine scope, lexical closure lexical lexical scope"
+.IX Subsection "Anonymous Subroutines"
+.PP
+A reference to an anonymous subroutine can be created by using
+\&\f(CW\*(C`sub\*(C'\fR without a subname:
+.PP
+.Vb 1
+\&    $coderef = sub { print "Boink!\en" };
+.Ve
+.PP
+Note the semicolon.  Except for the code
+inside not being immediately executed, a \f(CW\*(C`sub {}\*(C'\fR is not so much a
+declaration as it is an operator, like \f(CW\*(C`do{}\*(C'\fR or \f(CW\*(C`eval{}\*(C'\fR.  (However, no
+matter how many times you execute that particular line (unless you're in an
+\&\f(CWeval("...")\fR), \f(CW$coderef\fR will still have a reference to the \fIsame\fR
+anonymous subroutine.)
+.PP
+Anonymous subroutines act as closures with respect to \fBmy()\fR variables,
+that is, variables lexically visible within the current scope.  Closure
+is a notion out of the Lisp world that says if you define an anonymous
+function in a particular lexical context, it pretends to run in that
+context even when it's called outside the context.
+.PP
+In human terms, it's a funny way of passing arguments to a subroutine when
+you define it as well as when you call it.  It's useful for setting up
+little bits of code to run later, such as callbacks.  You can even
+do object-oriented stuff with it, though Perl already provides a different
+mechanism to do that\-\-see perlobj.
+.PP
+You might also think of closure as a way to write a subroutine
+template without using \fBeval()\fR.  Here's a small example of how
+closures work:
+.PP
+.Vb 6
+\&    sub newprint {
+\&        my $x = shift;
+\&        return sub { my $y = shift; print "$x, $y!\en"; };
+\&    }
+\&    $h = newprint("Howdy");
+\&    $g = newprint("Greetings");
+\&
+\&    # Time passes...
+\&
+\&    &$h("world");
+\&    &$g("earthlings");
+.Ve
+.PP
+This prints
+.PP
+.Vb 2
+\&    Howdy, world!
+\&    Greetings, earthlings!
+.Ve
+.PP
+Note particularly that \f(CW$x\fR continues to refer to the value passed
+into \fBnewprint()\fR \fIdespite\fR "my \f(CW$x\fR" having gone out of scope by the
+time the anonymous subroutine runs.  That's what a closure is all
+about.
+.PP
+This applies only to lexical variables, by the way.  Dynamic variables
+continue to work as they have always worked.  Closure is not something
+that most Perl programmers need trouble themselves about to begin with.
+.PP
+\fIConstructors\fR
+.IX Xref "constructor new"
+.IX Subsection "Constructors"
+.PP
+References are often returned by special subroutines called constructors.  Perl
+objects are just references to a special type of object that happens to know
+which package it's associated with.  Constructors are just special subroutines
+that know how to create that association.  They do so by starting with an
+ordinary reference, and it remains an ordinary reference even while it's also
+being an object.  Constructors are often named \f(CWnew()\fR.  You \fIcan\fR call them
+indirectly:
+.PP
+.Vb 1
+\&    $objref = new Doggie( Tail => \*(Aqshort\*(Aq, Ears => \*(Aqlong\*(Aq );
+.Ve
+.PP
+But that can produce ambiguous syntax in certain cases, so it's often
+better to use the direct method invocation approach:
+.PP
+.Vb 1
+\&    $objref   = Doggie\->new(Tail => \*(Aqshort\*(Aq, Ears => \*(Aqlong\*(Aq);
+\&
+\&    use Term::Cap;
+\&    $terminal = Term::Cap\->Tgetent( { OSPEED => 9600 });
+\&
+\&    use Tk;
+\&    $main    = MainWindow\->new();
+\&    $menubar = $main\->Frame(\-relief              => "raised",
+\&                            \-borderwidth         => 2)
+.Ve
+.PP
+This indirect object syntax is only available when
+\&\f(CW\*(C`use feature "indirect"\*(C'\fR is in effect,
+and that is not the case when \f(CW\*(C`use v5.36\*(C'\fR (or
+higher) is requested, it is best to avoid indirect object syntax entirely.
+.PP
+\fIAutovivification\fR
+.IX Xref "autovivification"
+.IX Subsection "Autovivification"
+.PP
+References of the appropriate type can spring into existence if you
+dereference them in a context that assumes they exist.  Because we haven't
+talked about dereferencing yet, we can't show you any examples yet.
+.PP
+\fITypeglob Slots\fR
+.IX Xref "*foo{THING} *"
+.IX Subsection "Typeglob Slots"
+.PP
+A reference can be created by using a special syntax, lovingly known as
+the *foo{THING} syntax.  *foo{THING} returns a reference to the THING
+slot in *foo (which is the symbol table entry which holds everything
+known as foo).
+.PP
+.Vb 9
+\&    $scalarref = *foo{SCALAR};
+\&    $arrayref  = *ARGV{ARRAY};
+\&    $hashref   = *ENV{HASH};
+\&    $coderef   = *handler{CODE};
+\&    $ioref     = *STDIN{IO};
+\&    $globref   = *foo{GLOB};
+\&    $formatref = *foo{FORMAT};
+\&    $globname  = *foo{NAME};    # "foo"
+\&    $pkgname   = *foo{PACKAGE}; # "main"
+.Ve
+.PP
+Most of these are self-explanatory, but \f(CW*foo{IO}\fR
+deserves special attention.  It returns
+the IO handle, used for file handles ("open" in perlfunc), sockets
+("socket" in perlfunc and "socketpair" in perlfunc), and directory
+handles ("opendir" in perlfunc).  For compatibility with previous
+versions of Perl, \f(CW*foo{FILEHANDLE}\fR is a synonym for \f(CW*foo{IO}\fR, though it
+is discouraged, to encourage a consistent use of one name: IO.  On perls
+between v5.8 and v5.22, it will issue a deprecation warning, but this
+deprecation has since been rescinded.
+.PP
+\&\f(CW*foo{THING}\fR returns undef if that particular THING hasn't been used yet,
+except in the case of scalars.  \f(CW*foo{SCALAR}\fR returns a reference to an
+anonymous scalar if \f(CW$foo\fR hasn't been used yet.  This might change in a
+future release.
+.PP
+\&\f(CW*foo{NAME}\fR and \f(CW*foo{PACKAGE}\fR are the exception, in that they return
+strings, rather than references.  These return the package and name of the
+typeglob itself, rather than one that has been assigned to it.  So, after
+\&\f(CW\*(C`*foo=*Foo::bar\*(C'\fR, \f(CW*foo\fR will become "*Foo::bar" when used as a string,
+but \f(CW*foo{PACKAGE}\fR and \f(CW*foo{NAME}\fR will continue to produce "main" and
+"foo", respectively.
+.PP
+\&\f(CW*foo{IO}\fR is an alternative to the \f(CW*HANDLE\fR mechanism given in
+"Typeglobs and Filehandles" in perldata for passing filehandles
+into or out of subroutines, or storing into larger data structures.
+Its disadvantage is that it won't create a new filehandle for you.
+Its advantage is that you have less risk of clobbering more than
+you want to with a typeglob assignment.  (It still conflates file
+and directory handles, though.)  However, if you assign the incoming
+value to a scalar instead of a typeglob as we do in the examples
+below, there's no risk of that happening.
+.PP
+.Vb 2
+\&    splutter(*STDOUT);          # pass the whole glob
+\&    splutter(*STDOUT{IO});      # pass both file and dir handles
+\&
+\&    sub splutter {
+\&        my $fh = shift;
+\&        print $fh "her um well a hmmm\en";
+\&    }
+\&
+\&    $rec = get_rec(*STDIN);     # pass the whole glob
+\&    $rec = get_rec(*STDIN{IO}); # pass both file and dir handles
+\&
+\&    sub get_rec {
+\&        my $fh = shift;
+\&        return scalar <$fh>;
+\&    }
+.Ve
+.SS "Using References"
+.IX Xref "reference, use dereferencing dereference"
+.IX Subsection "Using References"
+That's it for creating references.  By now you're probably dying to
+know how to use references to get back to your long-lost data.  There
+are several basic methods.
+.PP
+\fISimple Scalar\fR
+.IX Subsection "Simple Scalar"
+.PP
+Anywhere you'd put an identifier (or chain of identifiers) as part
+of a variable or subroutine name, you can replace the identifier with
+a simple scalar variable containing a reference of the correct type:
+.PP
+.Vb 6
+\&    $bar = $$scalarref;
+\&    push(@$arrayref, $filename);
+\&    $$arrayref[0] = "January";
+\&    $$hashref{"KEY"} = "VALUE";
+\&    &$coderef(1,2,3);
+\&    print $globref "output\en";
+.Ve
+.PP
+It's important to understand that we are specifically \fInot\fR dereferencing
+\&\f(CW$arrayref[0]\fR or \f(CW$hashref{"KEY"}\fR there.  The dereference of the
+scalar variable happens \fIbefore\fR it does any key lookups.  Anything more
+complicated than a simple scalar variable must use methods 2 or 3 below.
+However, a "simple scalar" includes an identifier that itself uses method
+1 recursively.  Therefore, the following prints "howdy".
+.PP
+.Vb 2
+\&    $refrefref = \e\e\e"howdy";
+\&    print $$$$refrefref;
+.Ve
+.PP
+\fIBlock\fR
+.IX Subsection "Block"
+.PP
+Anywhere you'd put an identifier (or chain of identifiers) as part of a
+variable or subroutine name, you can replace the identifier with a
+BLOCK returning a reference of the correct type.  In other words, the
+previous examples could be written like this:
+.PP
+.Vb 6
+\&    $bar = ${$scalarref};
+\&    push(@{$arrayref}, $filename);
+\&    ${$arrayref}[0] = "January";
+\&    ${$hashref}{"KEY"} = "VALUE";
+\&    &{$coderef}(1,2,3);
+\&    $globref\->print("output\en");  # iff IO::Handle is loaded
+.Ve
+.PP
+Admittedly, it's a little silly to use the curlies in this case, but
+the BLOCK can contain any arbitrary expression, in particular,
+subscripted expressions:
+.PP
+.Vb 1
+\&    &{ $dispatch{$index} }(1,2,3);      # call correct routine
+.Ve
+.PP
+Because of being able to omit the curlies for the simple case of \f(CW$$x\fR,
+people often make the mistake of viewing the dereferencing symbols as
+proper operators, and wonder about their precedence.  If they were,
+though, you could use parentheses instead of braces.  That's not the case.
+Consider the difference below; case 0 is a short-hand version of case 1,
+\&\fInot\fR case 2:
+.PP
+.Vb 4
+\&    $$hashref{"KEY"}   = "VALUE";       # CASE 0
+\&    ${$hashref}{"KEY"} = "VALUE";       # CASE 1
+\&    ${$hashref{"KEY"}} = "VALUE";       # CASE 2
+\&    ${$hashref\->{"KEY"}} = "VALUE";     # CASE 3
+.Ve
+.PP
+Case 2 is also deceptive in that you're accessing a variable
+called \f(CW%hashref\fR, not dereferencing through \f(CW$hashref\fR to the hash
+it's presumably referencing.  That would be case 3.
+.PP
+\fIArrow Notation\fR
+.IX Subsection "Arrow Notation"
+.PP
+Subroutine calls and lookups of individual array elements arise often
+enough that it gets cumbersome to use method 2.  As a form of
+syntactic sugar, the examples for method 2 may be written:
+.PP
+.Vb 3
+\&    $arrayref\->[0] = "January";   # Array element
+\&    $hashref\->{"KEY"} = "VALUE";  # Hash element
+\&    $coderef\->(1,2,3);            # Subroutine call
+.Ve
+.PP
+The left side of the arrow can be any expression returning a reference,
+including a previous dereference.  Note that \f(CW$array[$x]\fR is \fInot\fR the
+same thing as \f(CW\*(C`$array\->[$x]\*(C'\fR here:
+.PP
+.Vb 1
+\&    $array[$x]\->{"foo"}\->[0] = "January";
+.Ve
+.PP
+This is one of the cases we mentioned earlier in which references could
+spring into existence when in an lvalue context.  Before this
+statement, \f(CW$array[$x]\fR may have been undefined.  If so, it's
+automatically defined with a hash reference so that we can look up
+\&\f(CW\*(C`{"foo"}\*(C'\fR in it.  Likewise \f(CW\*(C`$array[$x]\->{"foo"}\*(C'\fR will automatically get
+defined with an array reference so that we can look up \f(CW\*(C`[0]\*(C'\fR in it.
+This process is called \fIautovivification\fR.
+.PP
+One more thing here.  The arrow is optional \fIbetween\fR brackets
+subscripts, so you can shrink the above down to
+.PP
+.Vb 1
+\&    $array[$x]{"foo"}[0] = "January";
+.Ve
+.PP
+Which, in the degenerate case of using only ordinary arrays, gives you
+multidimensional arrays just like C's:
+.PP
+.Vb 1
+\&    $score[$x][$y][$z] += 42;
+.Ve
+.PP
+Well, okay, not entirely like C's arrays, actually.  C doesn't know how
+to grow its arrays on demand.  Perl does.
+.PP
+\fIObjects\fR
+.IX Subsection "Objects"
+.PP
+If a reference happens to be a reference to an object, then there are
+probably methods to access the things referred to, and you should probably
+stick to those methods unless you're in the class package that defines the
+object's methods.  In other words, be nice, and don't violate the object's
+encapsulation without a very good reason.  Perl does not enforce
+encapsulation.  We are not totalitarians here.  We do expect some basic
+civility though.
+.PP
+\fIMiscellaneous Usage\fR
+.IX Subsection "Miscellaneous Usage"
+.PP
+Using a string or number as a reference produces a symbolic reference,
+as explained above.  Using a reference as a number produces an
+integer representing its storage location in memory.  The only
+useful thing to be done with this is to compare two references
+numerically to see whether they refer to the same location.
+.IX Xref "reference, numeric context"
+.PP
+.Vb 3
+\&    if ($ref1 == $ref2) {  # cheap numeric compare of references
+\&        print "refs 1 and 2 refer to the same thing\en";
+\&    }
+.Ve
+.PP
+Using a reference as a string produces both its referent's type,
+including any package blessing as described in perlobj, as well
+as the numeric address expressed in hex.  The \fBref()\fR operator returns
+just the type of thing the reference is pointing to, without the
+address.  See "ref" in perlfunc for details and examples of its use.
+.IX Xref "reference, string context"
+.PP
+The \fBbless()\fR operator may be used to associate the object a reference
+points to with a package functioning as an object class.  See perlobj.
+.PP
+A typeglob may be dereferenced the same way a reference can, because
+the dereference syntax always indicates the type of reference desired.
+So \f(CW\*(C`${*foo}\*(C'\fR and \f(CW\*(C`${\e$foo}\*(C'\fR both indicate the same scalar variable.
+.PP
+Here's a trick for interpolating a subroutine call into a string:
+.PP
+.Vb 1
+\&    print "My sub returned @{[mysub(1,2,3)]} that time.\en";
+.Ve
+.PP
+The way it works is that when the \f(CW\*(C`@{...}\*(C'\fR is seen in the double-quoted
+string, it's evaluated as a block.  The block creates a reference to an
+anonymous array containing the results of the call to \f(CW\*(C`mysub(1,2,3)\*(C'\fR.  So
+the whole block returns a reference to an array, which is then
+dereferenced by \f(CW\*(C`@{...}\*(C'\fR and stuck into the double-quoted string. This
+chicanery is also useful for arbitrary expressions:
+.PP
+.Vb 1
+\&    print "That yields @{[$n + 5]} widgets\en";
+.Ve
+.PP
+Similarly, an expression that returns a reference to a scalar can be
+dereferenced via \f(CW\*(C`${...}\*(C'\fR. Thus, the above expression may be written
+as:
+.PP
+.Vb 1
+\&    print "That yields ${\e($n + 5)} widgets\en";
+.Ve
+.SS "Circular References"
+.IX Xref "circular reference reference, circular"
+.IX Subsection "Circular References"
+It is possible to create a "circular reference" in Perl, which can lead
+to memory leaks. A circular reference occurs when two references
+contain a reference to each other, like this:
+.PP
+.Vb 3
+\&    my $foo = {};
+\&    my $bar = { foo => $foo };
+\&    $foo\->{bar} = $bar;
+.Ve
+.PP
+You can also create a circular reference with a single variable:
+.PP
+.Vb 2
+\&    my $foo;
+\&    $foo = \e$foo;
+.Ve
+.PP
+In this case, the reference count for the variables will never reach 0,
+and the references will never be garbage-collected. This can lead to
+memory leaks.
+.PP
+Because objects in Perl are implemented as references, it's possible to
+have circular references with objects as well. Imagine a TreeNode class
+where each node references its parent and child nodes. Any node with a
+parent will be part of a circular reference.
+.PP
+You can break circular references by creating a "weak reference". A
+weak reference does not increment the reference count for a variable,
+which means that the object can go out of scope and be destroyed. You
+can weaken a reference with the \f(CW\*(C`weaken\*(C'\fR function exported by the
+Scalar::Util module, or available as \f(CW\*(C`builtin::weaken\*(C'\fR directly in
+Perl version 5.35.7 or later.
+.PP
+Here's how we can make the first example safer:
+.PP
+.Vb 1
+\&    use Scalar::Util \*(Aqweaken\*(Aq;
+\&
+\&    my $foo = {};
+\&    my $bar = { foo => $foo };
+\&    $foo\->{bar} = $bar;
+\&
+\&    weaken $foo\->{bar};
+.Ve
+.PP
+The reference from \f(CW$foo\fR to \f(CW$bar\fR has been weakened. When the
+\&\f(CW$bar\fR variable goes out of scope, it will be garbage-collected. The
+next time you look at the value of the \f(CW\*(C`$foo\->{bar}\*(C'\fR key, it will
+be \f(CW\*(C`undef\*(C'\fR.
+.PP
+This action at a distance can be confusing, so you should be careful
+with your use of weaken. You should weaken the reference in the
+variable that will go out of scope \fIfirst\fR. That way, the longer-lived
+variable will contain the expected reference until it goes out of
+scope.
+.SS "Symbolic references"
+.IX Xref "reference, symbolic reference, soft symbolic reference soft reference"
+.IX Subsection "Symbolic references"
+We said that references spring into existence as necessary if they are
+undefined, but we didn't say what happens if a value used as a
+reference is already defined, but \fIisn't\fR a hard reference.  If you
+use it as a reference, it'll be treated as a symbolic
+reference.  That is, the value of the scalar is taken to be the \fIname\fR
+of a variable, rather than a direct link to a (possibly) anonymous
+value.
+.PP
+People frequently expect it to work like this.  So it does.
+.PP
+.Vb 9
+\&    $name = "foo";
+\&    $$name = 1;                 # Sets $foo
+\&    ${$name} = 2;               # Sets $foo
+\&    ${$name x 2} = 3;           # Sets $foofoo
+\&    $name\->[0] = 4;             # Sets $foo[0]
+\&    @$name = ();                # Clears @foo
+\&    &$name();                   # Calls &foo()
+\&    $pack = "THAT";
+\&    ${"${pack}::$name"} = 5;    # Sets $THAT::foo without eval
+.Ve
+.PP
+This is powerful, and slightly dangerous, in that it's possible
+to intend (with the utmost sincerity) to use a hard reference, and
+accidentally use a symbolic reference instead.  To protect against
+that, you can say
+.PP
+.Vb 1
+\&    use strict \*(Aqrefs\*(Aq;
+.Ve
+.PP
+and then only hard references will be allowed for the rest of the enclosing
+block.  An inner block may countermand that with
+.PP
+.Vb 1
+\&    no strict \*(Aqrefs\*(Aq;
+.Ve
+.PP
+Only package variables (globals, even if localized) are visible to
+symbolic references.  Lexical variables (declared with \fBmy()\fR) aren't in
+a symbol table, and thus are invisible to this mechanism.  For example:
+.PP
+.Vb 6
+\&    local $value = 10;
+\&    $ref = "value";
+\&    {
+\&        my $value = 20;
+\&        print $$ref;
+\&    }
+.Ve
+.PP
+This will still print 10, not 20.  Remember that \fBlocal()\fR affects package
+variables, which are all "global" to the package.
+.SS "Not-so-symbolic references"
+.IX Subsection "Not-so-symbolic references"
+Brackets around a symbolic reference can simply
+serve to isolate an identifier or variable name from the rest of an
+expression, just as they always have within a string.  For example,
+.PP
+.Vb 2
+\&    $push = "pop on ";
+\&    print "${push}over";
+.Ve
+.PP
+has always meant to print "pop on over", even though push is
+a reserved word.  This is generalized to work the same
+without the enclosing double quotes, so that
+.PP
+.Vb 1
+\&    print ${push} . "over";
+.Ve
+.PP
+and even
+.PP
+.Vb 1
+\&    print ${ push } . "over";
+.Ve
+.PP
+will have the same effect.  This
+construct is \fInot\fR considered to be a symbolic reference when you're
+using strict refs:
+.PP
+.Vb 3
+\&    use strict \*(Aqrefs\*(Aq;
+\&    ${ bareword };      # Okay, means $bareword.
+\&    ${ "bareword" };    # Error, symbolic reference.
+.Ve
+.PP
+Similarly, because of all the subscripting that is done using single words,
+the same rule applies to any bareword that is used for subscripting a hash.
+So now, instead of writing
+.PP
+.Vb 1
+\&    $hash{ "aaa" }{ "bbb" }{ "ccc" }
+.Ve
+.PP
+you can write just
+.PP
+.Vb 1
+\&    $hash{ aaa }{ bbb }{ ccc }
+.Ve
+.PP
+and not worry about whether the subscripts are reserved words.  In the
+rare event that you do wish to do something like
+.PP
+.Vb 1
+\&    $hash{ shift }
+.Ve
+.PP
+you can force interpretation as a reserved word by adding anything that
+makes it more than a bareword:
+.PP
+.Vb 3
+\&    $hash{ shift() }
+\&    $hash{ +shift }
+\&    $hash{ shift @_ }
+.Ve
+.PP
+The \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR switch will warn you if it
+interprets a reserved word as a string.
+But it will no longer warn you about using lowercase words, because the
+string is effectively quoted.
+.SS "Pseudo-hashes: Using an array as a hash"
+.IX Xref "pseudo-hash pseudo hash pseudohash"
+.IX Subsection "Pseudo-hashes: Using an array as a hash"
+Pseudo-hashes have been removed from Perl.  The 'fields' pragma
+remains available.
+.SS "Function Templates"
+.IX Xref "scope, lexical closure lexical lexical scope subroutine, nested sub, nested subroutine, local sub, local"
+.IX Subsection "Function Templates"
+As explained above, an anonymous function with access to the lexical
+variables visible when that function was compiled, creates a closure.  It
+retains access to those variables even though it doesn't get run until
+later, such as in a signal handler or a Tk callback.
+.PP
+Using a closure as a function template allows us to generate many functions
+that act similarly.  Suppose you wanted functions named after the colors
+that generated HTML font changes for the various colors:
+.PP
+.Vb 1
+\&    print "Be ", red("careful"), "with that ", green("light");
+.Ve
+.PP
+The \fBred()\fR and \fBgreen()\fR functions would be similar.  To create these,
+we'll assign a closure to a typeglob of the name of the function we're
+trying to build.
+.PP
+.Vb 5
+\&    @colors = qw(red blue green yellow orange purple violet);
+\&    for my $name (@colors) {
+\&        no strict \*(Aqrefs\*(Aq;       # allow symbol table manipulation
+\&        *$name = *{uc $name} = sub { "<FONT COLOR=\*(Aq$name\*(Aq>@_</FONT>" };
+\&    }
+.Ve
+.PP
+Now all those different functions appear to exist independently.  You can
+call \fBred()\fR, \fBRED()\fR, \fBblue()\fR, \fBBLUE()\fR, \fBgreen()\fR, etc.  This technique saves on
+both compile time and memory use, and is less error-prone as well, since
+syntax checks happen at compile time.  It's critical that any variables in
+the anonymous subroutine be lexicals in order to create a proper closure.
+That's the reasons for the \f(CW\*(C`my\*(C'\fR on the loop iteration variable.
+.PP
+This is one of the only places where giving a prototype to a closure makes
+much sense.  If you wanted to impose scalar context on the arguments of
+these functions (probably not a wise idea for this particular example),
+you could have written it this way instead:
+.PP
+.Vb 1
+\&    *$name = sub ($) { "<FONT COLOR=\*(Aq$name\*(Aq>$_[0]</FONT>" };
+.Ve
+.PP
+However, since prototype checking happens at compile time, the assignment
+above happens too late to be of much use.  You could address this by
+putting the whole loop of assignments within a BEGIN block, forcing it
+to occur during compilation.
+.PP
+Access to lexicals that change over time\-\-like those in the \f(CW\*(C`for\*(C'\fR loop
+above, basically aliases to elements from the surrounding lexical scopes\-\-
+only works with anonymous subs, not with named subroutines. Generally
+said, named subroutines do not nest properly and should only be declared
+in the main package scope.
+.PP
+This is because named subroutines are created at compile time so their
+lexical variables get assigned to the parent lexicals from the first
+execution of the parent block. If a parent scope is entered a second
+time, its lexicals are created again, while the nested subs still
+reference the old ones.
+.PP
+Anonymous subroutines get to capture each time you execute the \f(CW\*(C`sub\*(C'\fR
+operator, as they are created on the fly. If you are accustomed to using
+nested subroutines in other programming languages with their own private
+variables, you'll have to work at it a bit in Perl.  The intuitive coding
+of this type of thing incurs mysterious warnings about "will not stay
+shared" due to the reasons explained above.
+For example, this won't work:
+.PP
+.Vb 5
+\&    sub outer {
+\&        my $x = $_[0] + 35;
+\&        sub inner { return $x * 19 }   # WRONG
+\&        return $x + inner();
+\&    }
+.Ve
+.PP
+A work-around is the following:
+.PP
+.Vb 5
+\&    sub outer {
+\&        my $x = $_[0] + 35;
+\&        local *inner = sub { return $x * 19 };
+\&        return $x + inner();
+\&    }
+.Ve
+.PP
+Now \fBinner()\fR can only be called from within \fBouter()\fR, because of the
+temporary assignments of the anonymous subroutine. But when it does,
+it has normal access to the lexical variable \f(CW$x\fR from the scope of
+\&\fBouter()\fR at the time outer is invoked.
+.PP
+This has the interesting effect of creating a function local to another
+function, something not normally supported in Perl.
+.SS "Postfix Dereference Syntax"
+.IX Subsection "Postfix Dereference Syntax"
+Beginning in v5.20.0, a postfix syntax for using references is
+available.  It behaves as described in "Using References", but instead
+of a prefixed sigil, a postfixed sigil-and-star is used.
+.PP
+For example:
+.PP
+.Vb 2
+\&    $r = \e@a;
+\&    @b = $r\->@*; # equivalent to @$r or @{ $r }
+\&
+\&    $r = [ 1, [ 2, 3 ], 4 ];
+\&    $r\->[1]\->@*;  # equivalent to @{ $r\->[1] }
+.Ve
+.PP
+In Perl 5.20 and 5.22, this syntax must be enabled with \f(CWuse feature
+\&\*(Aqpostderef\*(Aq\fR. As of Perl 5.24, no feature declarations are required to make
+it available.
+.PP
+Postfix dereference should work in all circumstances where block
+(circumfix) dereference worked, and should be entirely equivalent.  This
+syntax allows dereferencing to be written and read entirely
+left-to-right.  The following equivalencies are defined:
+.PP
+.Vb 6
+\&  $sref\->$*;  # same as  ${ $sref }
+\&  $aref\->@*;  # same as  @{ $aref }
+\&  $aref\->$#*; # same as $#{ $aref }
+\&  $href\->%*;  # same as  %{ $href }
+\&  $cref\->&*;  # same as  &{ $cref }
+\&  $gref\->**;  # same as  *{ $gref }
+.Ve
+.PP
+Note especially that \f(CW\*(C`$cref\->&*\*(C'\fR is \fInot\fR equivalent to \f(CW$cref\->()\fR, and can serve different purposes.
+.PP
+Glob elements can be extracted through the postfix dereferencing feature:
+.PP
+.Vb 1
+\&  $gref\->*{SCALAR}; # same as *{ $gref }{SCALAR}
+.Ve
+.PP
+Postfix array and scalar dereferencing \fIcan\fR be used in interpolating
+strings (double quotes or the \f(CW\*(C`qq\*(C'\fR operator), but only if the
+\&\f(CW\*(C`postderef_qq\*(C'\fR feature is enabled. Interpolation of postfix array highest index
+access (\f(CW\*(C`\->$#*\*(C'\fR) is also supported when the \f(CW\*(C`postderef_qq\*(C'\fR feature is
+enabled.
+.SS "Postfix Reference Slicing"
+.IX Subsection "Postfix Reference Slicing"
+Value slices of arrays and hashes may also be taken with postfix
+dereferencing notation, with the following equivalencies:
+.PP
+.Vb 2
+\&  $aref\->@[ ... ];  # same as @$aref[ ... ]
+\&  $href\->@{ ... };  # same as @$href{ ... }
+.Ve
+.PP
+Postfix key/value pair slicing, added in 5.20.0 and documented in
+the Key/Value Hash Slices section of perldata, also behaves as expected:
+.PP
+.Vb 2
+\&  $aref\->%[ ... ];  # same as %$aref[ ... ]
+\&  $href\->%{ ... };  # same as %$href{ ... }
+.Ve
+.PP
+As with postfix array, postfix value slice dereferencing \fIcan\fR be used
+in interpolating strings (double quotes or the \f(CW\*(C`qq\*(C'\fR operator), but only
+if the \f(CW\*(C`postderef_qq\*(C'\fR feature is enabled.
+.SS "Assigning to References"
+.IX Subsection "Assigning to References"
+Beginning in v5.22.0, the referencing operator can be assigned to.  It
+performs an aliasing operation, so that the variable name referenced on the
+left-hand side becomes an alias for the thing referenced on the right-hand
+side:
+.PP
+.Vb 2
+\&    \e$a = \e$b; # $a and $b now point to the same scalar
+\&    \e&foo = \e&bar; # foo() now means bar()
+.Ve
+.PP
+This syntax must be enabled with \f(CW\*(C`use feature \*(Aqrefaliasing\*(Aq\*(C'\fR.  It is
+experimental, and will warn by default unless \f(CWno warnings
+\&\*(Aqexperimental::refaliasing\*(Aq\fR is in effect.
+.PP
+These forms may be assigned to, and cause the right-hand side to be
+evaluated in scalar context:
+.PP
+.Vb 10
+\&    \e$scalar
+\&    \e@array
+\&    \e%hash
+\&    \e&sub
+\&    \emy $scalar
+\&    \emy @array
+\&    \emy %hash
+\&    \estate $scalar # or @array, etc.
+\&    \eour $scalar   # etc.
+\&    \elocal $scalar # etc.
+\&    \elocal our $scalar # etc.
+\&    \e$some_array[$index]
+\&    \e$some_hash{$key}
+\&    \elocal $some_array[$index]
+\&    \elocal $some_hash{$key}
+\&    condition ? \e$this : \e$that[0] # etc.
+.Ve
+.PP
+Slicing operations and parentheses cause
+the right-hand side to be evaluated in
+list context:
+.PP
+.Vb 10
+\&    \e@array[5..7]
+\&    (\e@array[5..7])
+\&    \e(@array[5..7])
+\&    \e@hash{\*(Aqfoo\*(Aq,\*(Aqbar\*(Aq}
+\&    (\e@hash{\*(Aqfoo\*(Aq,\*(Aqbar\*(Aq})
+\&    \e(@hash{\*(Aqfoo\*(Aq,\*(Aqbar\*(Aq})
+\&    (\e$scalar)
+\&    \e($scalar)
+\&    \e(my $scalar)
+\&    \emy($scalar)
+\&    (\e@array)
+\&    (\e%hash)
+\&    (\e&sub)
+\&    \e(&sub)
+\&    \e($foo, @bar, %baz)
+\&    (\e$foo, \e@bar, \e%baz)
+.Ve
+.PP
+Each element on the right-hand side must be a reference to a datum of the
+right type.  Parentheses immediately surrounding an array (and possibly
+also \f(CW\*(C`my\*(C'\fR/\f(CW\*(C`state\*(C'\fR/\f(CW\*(C`our\*(C'\fR/\f(CW\*(C`local\*(C'\fR) will make each element of the array an
+alias to the corresponding scalar referenced on the right-hand side:
+.PP
+.Vb 5
+\&    \e(@a) = \e(@b); # @a and @b now have the same elements
+\&    \emy(@a) = \e(@b); # likewise
+\&    \e(my @a) = \e(@b); # likewise
+\&    push @a, 3; # but now @a has an extra element that @b lacks
+\&    \e(@a) = (\e$a, \e$b, \e$c); # @a now contains $a, $b, and $c
+.Ve
+.PP
+Combining that form with \f(CW\*(C`local\*(C'\fR and putting parentheses immediately
+around a hash are forbidden (because it is not clear what they should do):
+.PP
+.Vb 2
+\&    \elocal(@array) = foo(); # WRONG
+\&    \e(%hash)       = bar(); # WRONG
+.Ve
+.PP
+Assignment to references and non-references may be combined in lists and
+conditional ternary expressions, as long as the values on the right-hand
+side are the right type for each element on the left, though this may make
+for obfuscated code:
+.PP
+.Vb 4
+\&    (my $tom, \emy $dick, \emy @harry) = (\e1, \e2, [1..3]);
+\&    # $tom is now \e1
+\&    # $dick is now 2 (read\-only)
+\&    # @harry is (1,2,3)
+\&
+\&    my $type = ref $thingy;
+\&    ($type ? $type eq \*(AqARRAY\*(Aq ? \e@foo : \e$bar : $baz) = $thingy;
+.Ve
+.PP
+The \f(CW\*(C`foreach\*(C'\fR loop can also take a reference constructor for its loop
+variable, though the syntax is limited to one of the following, with an
+optional \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`state\*(C'\fR, or \f(CW\*(C`our\*(C'\fR after the backslash:
+.PP
+.Vb 4
+\&    \e$s
+\&    \e@a
+\&    \e%h
+\&    \e&c
+.Ve
+.PP
+No parentheses are permitted.  This feature is particularly useful for
+arrays-of-arrays, or arrays-of-hashes:
+.PP
+.Vb 3
+\&    foreach \emy @a (@array_of_arrays) {
+\&        frobnicate($a[0], $a[\-1]);
+\&    }
+\&
+\&    foreach \emy %h (@array_of_hashes) {
+\&        $h{gelastic}++ if $h{type} eq \*(Aqfunny\*(Aq;
+\&    }
+.Ve
+.PP
+\&\fBCAVEAT:\fR Aliasing does not work correctly with closures.  If you try to
+alias lexical variables from an inner subroutine or \f(CW\*(C`eval\*(C'\fR, the aliasing
+will only be visible within that inner sub, and will not affect the outer
+subroutine where the variables are declared.  This bizarre behavior is
+subject to change.
+.SS "Declaring a Reference to a Variable"
+.IX Subsection "Declaring a Reference to a Variable"
+Beginning in v5.26.0, the referencing operator can come after \f(CW\*(C`my\*(C'\fR,
+\&\f(CW\*(C`state\*(C'\fR, \f(CW\*(C`our\*(C'\fR, or \f(CW\*(C`local\*(C'\fR.  This syntax must be enabled with \f(CW\*(C`use
+feature \*(Aqdeclared_refs\*(Aq\*(C'\fR.  It is experimental, and will warn by default
+unless \f(CW\*(C`no warnings \*(Aqexperimental::refaliasing\*(Aq\*(C'\fR is in effect.
+.PP
+This feature makes these:
+.PP
+.Vb 2
+\&    my \e$x;
+\&    our \e$y;
+.Ve
+.PP
+equivalent to:
+.PP
+.Vb 2
+\&    \emy $x;
+\&    \eour $x;
+.Ve
+.PP
+It is intended mainly for use in assignments to references (see
+"Assigning to References", above).  It also allows the backslash to be
+used on just some items in a list of declared variables:
+.PP
+.Vb 1
+\&    my ($foo, \e@bar, \e%baz); # equivalent to:  my $foo, \emy(@bar, %baz);
+.Ve
+.SH "WARNING: Don't use references as hash keys"
+.IX Xref "reference, string context reference, use as hash key"
+.IX Header "WARNING: Don't use references as hash keys"
+You may not (usefully) use a reference as the key to a hash.  It will be
+converted into a string:
+.PP
+.Vb 1
+\&    $x{ \e$a } = $a;
+.Ve
+.PP
+If you try to dereference the key, it won't do a hard dereference, and
+you won't accomplish what you're attempting.  You might want to do something
+more like
+.PP
+.Vb 2
+\&    $r = \e@a;
+\&    $x{ $r } = $r;
+.Ve
+.PP
+And then at least you can use the \fBvalues()\fR, which will be
+real refs, instead of the \fBkeys()\fR, which won't.
+.PP
+The standard Tie::RefHash module provides a convenient workaround to this.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Besides the obvious documents, source code can be instructive.
+Some pathological examples of the use of references can be found
+in the \fIt/op/ref.t\fR regression test in the Perl source directory.
+.PP
+See also perldsc and perllol for how to use references to create
+complex data structures, and perlootut and perlobj
+for how to use them to create objects.
diff --git a/upstream/mageia-cauldron/man1/perlreftut.1 b/upstream/mageia-cauldron/man1/perlreftut.1
new file mode 100644
index 00000000..7d1442aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlreftut.1
@@ -0,0 +1,594 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREFTUT 1"
+.TH PERLREFTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlreftut \- Mark's very short tutorial about references
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+One of the most important new features in Perl 5 was the capability to
+manage complicated data structures like multidimensional arrays and
+nested hashes.  To enable these, Perl 5 introduced a feature called
+\&\fIreferences\fR, and using references is the key to managing complicated,
+structured data in Perl.  Unfortunately, there's a lot of funny syntax
+to learn, and the main manual page can be hard to follow.  The manual
+is quite complete, and sometimes people find that a problem, because
+it can be hard to tell what is important and what isn't.
+.PP
+Fortunately, you only need to know 10% of what's in the main page to get
+90% of the benefit.  This page will show you that 10%.
+.SH "Who Needs Complicated Data Structures?"
+.IX Header "Who Needs Complicated Data Structures?"
+One problem that comes up all the time is needing a hash whose values are
+lists.  Perl has hashes, of course, but the values have to be scalars;
+they can't be lists.
+.PP
+Why would you want a hash of lists?  Let's take a simple example: You
+have a file of city and country names, like this:
+.PP
+.Vb 6
+\&        Chicago, USA
+\&        Frankfurt, Germany
+\&        Berlin, Germany
+\&        Washington, USA
+\&        Helsinki, Finland
+\&        New York, USA
+.Ve
+.PP
+and you want to produce an output like this, with each country mentioned
+once, and then an alphabetical list of the cities in that country:
+.PP
+.Vb 3
+\&        Finland: Helsinki.
+\&        Germany: Berlin, Frankfurt.
+\&        USA:  Chicago, New York, Washington.
+.Ve
+.PP
+The natural way to do this is to have a hash whose keys are country
+names.  Associated with each country name key is a list of the cities in
+that country.  Each time you read a line of input, split it into a country
+and a city, look up the list of cities already known to be in that
+country, and append the new city to the list.  When you're done reading
+the input, iterate over the hash as usual, sorting each list of cities
+before you print it out.
+.PP
+If hash values couldn't be lists, you lose.  You'd probably have to
+combine all the cities into a single string somehow, and then when
+time came to write the output, you'd have to break the string into a
+list, sort the list, and turn it back into a string.  This is messy
+and error-prone.  And it's frustrating, because Perl already has
+perfectly good lists that would solve the problem if only you could
+use them.
+.SH "The Solution"
+.IX Header "The Solution"
+By the time Perl 5 rolled around, we were already stuck with this
+design: Hash values must be scalars.  The solution to this is
+references.
+.PP
+A reference is a scalar value that \fIrefers to\fR an entire array or an
+entire hash (or to just about anything else).  Names are one kind of
+reference that you're already familiar with.  Each human being is a
+messy, inconvenient collection of cells. But to refer to a particular
+human, for instance the first computer programmer, it isn't necessary to
+describe each of their cells; all you need is the easy, convenient
+scalar string "Ada Lovelace".
+.PP
+References in Perl are like names for arrays and hashes.  They're
+Perl's private, internal names, so you can be sure they're
+unambiguous.  Unlike a human name, a reference only refers to one
+thing, and you always know what it refers to.  If you have a reference
+to an array, you can recover the entire array from it.  If you have a
+reference to a hash, you can recover the entire hash.  But the
+reference is still an easy, compact scalar value.
+.PP
+You can't have a hash whose values are arrays; hash values can only be
+scalars.  We're stuck with that.  But a single reference can refer to
+an entire array, and references are scalars, so you can have a hash of
+references to arrays, and it'll act a lot like a hash of arrays, and
+it'll be just as useful as a hash of arrays.
+.PP
+We'll come back to this city-country problem later, after we've seen
+some syntax for managing references.
+.SH Syntax
+.IX Header "Syntax"
+There are just two ways to make a reference, and just two ways to use
+it once you have it.
+.SS "Making References"
+.IX Subsection "Making References"
+\fR\f(BIMake Rule 1\fR\fI\fR
+.IX Subsection "Make Rule 1"
+.PP
+If you put a \f(CW\*(C`\e\*(C'\fR in front of a variable, you get a
+reference to that variable.
+.PP
+.Vb 2
+\&    $aref = \e@array;         # $aref now holds a reference to @array
+\&    $href = \e%hash;          # $href now holds a reference to %hash
+.Ve
+.PP
+Once the reference is stored in a variable like \f(CW$aref\fR or \f(CW$href\fR, you
+can copy it or store it just the same as any other scalar value:
+.PP
+.Vb 3
+\&    $xy = $aref;             # $xy now holds a reference to @array
+\&    $p[3] = $href;           # $p[3] now holds a reference to %hash
+\&    $z = $p[3];              # $z now holds a reference to %hash
+.Ve
+.PP
+These examples show how to make references to variables with names.
+Sometimes you want to make an array or a hash that doesn't have a
+name.  This is analogous to the way you like to be able to use the
+string \f(CW"\en"\fR or the number 80 without having to store it in a named
+variable first.
+.PP
+\fR\f(BIMake Rule 2\fR\fI\fR
+.IX Subsection "Make Rule 2"
+.PP
+\&\f(CW\*(C`[ ITEMS ]\*(C'\fR makes a new, anonymous array, and returns a reference to
+that array.  \f(CW\*(C`{ ITEMS }\*(C'\fR makes a new, anonymous hash, and returns a
+reference to that hash.
+.PP
+.Vb 2
+\&    $aref = [ 1, "foo", undef, 13 ];
+\&    # $aref now holds a reference to an array
+\&
+\&    $href = { APR => 4, AUG => 8 };
+\&    # $href now holds a reference to a hash
+.Ve
+.PP
+The references you get from rule 2 are the same kind of
+references that you get from rule 1:
+.PP
+.Vb 2
+\&        # This:
+\&        $aref = [ 1, 2, 3 ];
+\&
+\&        # Does the same as this:
+\&        @array = (1, 2, 3);
+\&        $aref = \e@array;
+.Ve
+.PP
+The first line is an abbreviation for the following two lines, except
+that it doesn't create the superfluous array variable \f(CW@array\fR.
+.PP
+If you write just \f(CW\*(C`[]\*(C'\fR, you get a new, empty anonymous array.
+If you write just \f(CW\*(C`{}\*(C'\fR, you get a new, empty anonymous hash.
+.SS "Using References"
+.IX Subsection "Using References"
+What can you do with a reference once you have it?  It's a scalar
+value, and we've seen that you can store it as a scalar and get it back
+again just like any scalar.  There are just two more ways to use it:
+.PP
+\fR\f(BIUse Rule 1\fR\fI\fR
+.IX Subsection "Use Rule 1"
+.PP
+You can always use an array reference, in curly braces, in place of
+the name of an array.  For example, \f(CW\*(C`@{$aref}\*(C'\fR instead of \f(CW@array\fR.
+.PP
+Here are some examples of that:
+.PP
+Arrays:
+.PP
+.Vb 4
+\&        @a              @{$aref}                An array
+\&        reverse @a      reverse @{$aref}        Reverse the array
+\&        $a[3]           ${$aref}[3]             An element of the array
+\&        $a[3] = 17;     ${$aref}[3] = 17        Assigning an element
+.Ve
+.PP
+On each line are two expressions that do the same thing.  The
+left-hand versions operate on the array \f(CW@a\fR.  The right-hand
+versions operate on the array that is referred to by \f(CW$aref\fR.  Once
+they find the array they're operating on, both versions do the same
+things to the arrays.
+.PP
+Using a hash reference is \fIexactly\fR the same:
+.PP
+.Vb 4
+\&        %h              %{$href}              A hash
+\&        keys %h         keys %{$href}         Get the keys from the hash
+\&        $h{\*(Aqred\*(Aq}       ${$href}{\*(Aqred\*(Aq}       An element of the hash
+\&        $h{\*(Aqred\*(Aq} = 17  ${$href}{\*(Aqred\*(Aq} = 17  Assigning an element
+.Ve
+.PP
+Whatever you want to do with a reference, \fBUse Rule 1\fR tells you how
+to do it.  You just write the Perl code that you would have written
+for doing the same thing to a regular array or hash, and then replace
+the array or hash name with \f(CW\*(C`{$reference}\*(C'\fR.  "How do I loop over an
+array when all I have is a reference?"  Well, to loop over an array, you
+would write
+.PP
+.Vb 3
+\&        for my $element (@array) {
+\&          ...
+\&        }
+.Ve
+.PP
+so replace the array name, \f(CW@array\fR, with the reference:
+.PP
+.Vb 3
+\&        for my $element (@{$aref}) {
+\&          ...
+\&        }
+.Ve
+.PP
+"How do I print out the contents of a hash when all I have is a
+reference?"  First write the code for printing out a hash:
+.PP
+.Vb 3
+\&        for my $key (keys %hash) {
+\&          print "$key => $hash{$key}\en";
+\&        }
+.Ve
+.PP
+And then replace the hash name with the reference:
+.PP
+.Vb 3
+\&        for my $key (keys %{$href}) {
+\&          print "$key => ${$href}{$key}\en";
+\&        }
+.Ve
+.PP
+\fR\f(BIUse Rule 2\fR\fI\fR
+.IX Subsection "Use Rule 2"
+.PP
+\&\fBUse Rule 1\fR is all you really need, because it tells
+you how to do absolutely everything you ever need to do with references.
+But the most common thing to do with an array or a hash is to extract a
+single element, and the \fBUse Rule 1\fR notation is
+cumbersome.  So there is an abbreviation.
+.PP
+\&\f(CW\*(C`${$aref}[3]\*(C'\fR is too hard to read, so you can write \f(CW\*(C`$aref\->[3]\*(C'\fR
+instead.
+.PP
+\&\f(CW\*(C`${$href}{red}\*(C'\fR is too hard to read, so you can write
+\&\f(CW\*(C`$href\->{red}\*(C'\fR instead.
+.PP
+If \f(CW$aref\fR holds a reference to an array, then \f(CW\*(C`$aref\->[3]\*(C'\fR is
+the fourth element of the array.  Don't confuse this with \f(CW$aref[3]\fR,
+which is the fourth element of a totally different array, one
+deceptively named \f(CW@aref\fR.  \f(CW$aref\fR and \f(CW@aref\fR are unrelated the
+same way that \f(CW$item\fR and \f(CW@item\fR are.
+.PP
+Similarly, \f(CW\*(C`$href\->{\*(Aqred\*(Aq}\*(C'\fR is part of the hash referred to by
+the scalar variable \f(CW$href\fR, perhaps even one with no name.
+\&\f(CW$href{\*(Aqred\*(Aq}\fR is part of the deceptively named \f(CW%href\fR hash.  It's
+easy to forget to leave out the \f(CW\*(C`\->\*(C'\fR, and if you do, you'll get
+bizarre results when your program gets array and hash elements out of
+totally unexpected hashes and arrays that weren't the ones you wanted
+to use.
+.SS "An Example"
+.IX Subsection "An Example"
+Let's see a quick example of how all this is useful.
+.PP
+First, remember that \f(CW\*(C`[1, 2, 3]\*(C'\fR makes an anonymous array containing
+\&\f(CW\*(C`(1, 2, 3)\*(C'\fR, and gives you a reference to that array.
+.PP
+Now think about
+.PP
+.Vb 4
+\&        @a = ( [1, 2, 3],
+\&               [4, 5, 6],
+\&               [7, 8, 9]
+\&             );
+.Ve
+.PP
+\&\f(CW@a\fR is an array with three elements, and each one is a reference to
+another array.
+.PP
+\&\f(CW$a[1]\fR is one of these references.  It refers to an array, the array
+containing \f(CW\*(C`(4, 5, 6)\*(C'\fR, and because it is a reference to an array,
+\&\fBUse Rule 2\fR says that we can write \f(CW\*(C`$a[1]\->[2]\*(C'\fR
+to get the third element from that array.  \f(CW\*(C`$a[1]\->[2]\*(C'\fR is the 6.
+Similarly, \f(CW\*(C`$a[0]\->[1]\*(C'\fR is the 2.  What we have here is like a
+two-dimensional array; you can write \f(CW\*(C`$a[ROW]\->[COLUMN]\*(C'\fR to get or
+set the element in any row and any column of the array.
+.PP
+The notation still looks a little cumbersome, so there's one more
+abbreviation:
+.SS "Arrow Rule"
+.IX Subsection "Arrow Rule"
+In between two \fBsubscripts\fR, the arrow is optional.
+.PP
+Instead of \f(CW\*(C`$a[1]\->[2]\*(C'\fR, we can write \f(CW\*(C`$a[1][2]\*(C'\fR; it means the
+same thing.  Instead of \f(CW\*(C`$a[0]\->[1] = 23\*(C'\fR, we can write
+\&\f(CW\*(C`$a[0][1] = 23\*(C'\fR; it means the same thing.
+.PP
+Now it really looks like two-dimensional arrays!
+.PP
+You can see why the arrows are important.  Without them, we would have
+had to write \f(CW\*(C`${$a[1]}[2]\*(C'\fR instead of \f(CW\*(C`$a[1][2]\*(C'\fR.  For
+three-dimensional arrays, they let us write \f(CW\*(C`$x[2][3][5]\*(C'\fR instead of
+the unreadable \f(CW\*(C`${${$x[2]}[3]}[5]\*(C'\fR.
+.SH Solution
+.IX Header "Solution"
+Here's the answer to the problem I posed earlier, of reformatting a
+file of city and country names.
+.PP
+.Vb 1
+\&    1   my %table;
+\&
+\&    2   while (<>) {
+\&    3     chomp;
+\&    4     my ($city, $country) = split /, /;
+\&    5     $table{$country} = [] unless exists $table{$country};
+\&    6     push @{$table{$country}}, $city;
+\&    7   }
+\&
+\&    8   for my $country (sort keys %table) {
+\&    9     print "$country: ";
+\&   10     my @cities = @{$table{$country}};
+\&   11     print join \*(Aq, \*(Aq, sort @cities;
+\&   12     print ".\en";
+\&   13   }
+.Ve
+.PP
+The program has two pieces: Lines 2\-7 read the input and build a data
+structure, and lines 8\-13 analyze the data and print out the report.
+We're going to have a hash, \f(CW%table\fR, whose keys are country names,
+and whose values are references to arrays of city names.  The data
+structure will look like this:
+.PP
+.Vb 10
+\&           %table
+\&        +\-\-\-\-\-\-\-+\-\-\-+
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+
+\&        |Germany| *\-\-\-\->| Frankfurt | Berlin |
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+
+\&        +\-\-\-\-\-\-\-+\-\-\-+
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-\-+
+\&        |Finland| *\-\-\-\->| Helsinki |
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-\-+
+\&        +\-\-\-\-\-\-\-+\-\-\-+
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
+\&        |  USA  | *\-\-\-\->| Chicago | Washington | New York |
+\&        |       |   |   +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
+\&        +\-\-\-\-\-\-\-+\-\-\-+
+.Ve
+.PP
+We'll look at output first.  Supposing we already have this structure,
+how do we print it out?
+.PP
+.Vb 6
+\&    8   for my $country (sort keys %table) {
+\&    9     print "$country: ";
+\&   10     my @cities = @{$table{$country}};
+\&   11     print join \*(Aq, \*(Aq, sort @cities;
+\&   12     print ".\en";
+\&   13   }
+.Ve
+.PP
+\&\f(CW%table\fR is an ordinary hash, and we get a list of keys from it, sort
+the keys, and loop over the keys as usual.  The only use of references
+is in line 10.  \f(CW$table{$country}\fR looks up the key \f(CW$country\fR in the
+hash and gets the value, which is a reference to an array of cities in
+that country.  \fBUse Rule 1\fR says that we can recover
+the array by saying \f(CW\*(C`@{$table{$country}}\*(C'\fR.  Line 10 is just like
+.PP
+.Vb 1
+\&        @cities = @array;
+.Ve
+.PP
+except that the name \f(CW\*(C`array\*(C'\fR has been replaced by the reference
+\&\f(CW\*(C`{$table{$country}}\*(C'\fR.  The \f(CW\*(C`@\*(C'\fR tells Perl to get the entire array.
+Having gotten the list of cities, we sort it, join it, and print it
+out as usual.
+.PP
+Lines 2\-7 are responsible for building the structure in the first
+place.  Here they are again:
+.PP
+.Vb 6
+\&    2   while (<>) {
+\&    3     chomp;
+\&    4     my ($city, $country) = split /, /;
+\&    5     $table{$country} = [] unless exists $table{$country};
+\&    6     push @{$table{$country}}, $city;
+\&    7   }
+.Ve
+.PP
+Lines 2\-4 acquire a city and country name.  Line 5 looks to see if the
+country is already present as a key in the hash.  If it's not, the
+program uses the \f(CW\*(C`[]\*(C'\fR notation (\fBMake Rule 2\fR) to
+manufacture a new, empty anonymous array of cities, and installs a
+reference to it into the hash under the appropriate key.
+.PP
+Line 6 installs the city name into the appropriate array.
+\&\f(CW$table{$country}\fR now holds a reference to the array of cities seen
+in that country so far.  Line 6 is exactly like
+.PP
+.Vb 1
+\&        push @array, $city;
+.Ve
+.PP
+except that the name \f(CW\*(C`array\*(C'\fR has been replaced by the reference
+\&\f(CW\*(C`{$table{$country}}\*(C'\fR.  The \f(CW\*(C`push\*(C'\fR adds a
+city name to the end of the referred-to array.
+.PP
+There's one fine point I skipped.  Line 5 is unnecessary, and we can
+get rid of it.
+.PP
+.Vb 6
+\&    2   while (<>) {
+\&    3     chomp;
+\&    4     my ($city, $country) = split /, /;
+\&    5   ####  $table{$country} = [] unless exists $table{$country};
+\&    6     push @{$table{$country}}, $city;
+\&    7   }
+.Ve
+.PP
+If there's already an entry in \f(CW%table\fR for the current \f(CW$country\fR,
+then nothing is different.  Line 6 will locate the value in
+\&\f(CW$table{$country}\fR, which is a reference to an array, and push \f(CW$city\fR
+into the array.  But what does it do when \f(CW$country\fR holds a key, say
+\&\f(CW\*(C`Greece\*(C'\fR, that is not yet in \f(CW%table\fR?
+.PP
+This is Perl, so it does the exact right thing.  It sees that you want
+to push \f(CW\*(C`Athens\*(C'\fR onto an array that doesn't exist, so it helpfully
+makes a new, empty, anonymous array for you, installs it into
+\&\f(CW%table\fR, and then pushes \f(CW\*(C`Athens\*(C'\fR onto it.  This is called
+\&\fIautovivification\fR\-\-bringing things to life automatically.  Perl saw
+that the key wasn't in the hash, so it created a new hash entry
+automatically. Perl saw that you wanted to use the hash value as an
+array, so it created a new empty array and installed a reference to it
+in the hash automatically.  And as usual, Perl made the array one
+element longer to hold the new city name.
+.SH "The Rest"
+.IX Header "The Rest"
+I promised to give you 90% of the benefit with 10% of the details, and
+that means I left out 90% of the details.  Now that you have an
+overview of the important parts, it should be easier to read the
+perlref manual page, which discusses 100% of the details.
+.PP
+Some of the highlights of perlref:
+.IP \(bu 4
+You can make references to anything, including scalars, functions, and
+other references.
+.IP \(bu 4
+In \fBUse Rule 1\fR, you can omit the curly brackets
+whenever the thing inside them is an atomic scalar variable like
+\&\f(CW$aref\fR.  For example, \f(CW@$aref\fR is the same as \f(CW\*(C`@{$aref}\*(C'\fR, and
+\&\f(CW$$aref[1]\fR is the same as \f(CW\*(C`${$aref}[1]\*(C'\fR.  If you're just starting
+out, you may want to adopt the habit of always including the curly
+brackets.
+.IP \(bu 4
+This doesn't copy the underlying array:
+.Sp
+.Vb 1
+\&        $aref2 = $aref1;
+.Ve
+.Sp
+You get two references to the same array.  If you modify
+\&\f(CW\*(C`$aref1\->[23]\*(C'\fR and then look at
+\&\f(CW\*(C`$aref2\->[23]\*(C'\fR you'll see the change.
+.Sp
+To copy the array, use
+.Sp
+.Vb 1
+\&        $aref2 = [@{$aref1}];
+.Ve
+.Sp
+This uses \f(CW\*(C`[...]\*(C'\fR notation to create a new anonymous array, and
+\&\f(CW$aref2\fR is assigned a reference to the new array.  The new array is
+initialized with the contents of the array referred to by \f(CW$aref1\fR.
+.Sp
+Similarly, to copy an anonymous hash, you can use
+.Sp
+.Vb 1
+\&        $href2 = {%{$href1}};
+.Ve
+.IP \(bu 4
+To see if a variable contains a reference, use the
+\&\f(CW\*(C`ref\*(C'\fR function.  It returns true if its argument
+is a reference.  Actually it's a little better than that: It returns
+\&\f(CW\*(C`HASH\*(C'\fR for hash references and \f(CW\*(C`ARRAY\*(C'\fR for array references.
+.IP \(bu 4
+If you try to use a reference like a string, you get strings like
+.Sp
+.Vb 1
+\&        ARRAY(0x80f5dec)   or    HASH(0x826afc0)
+.Ve
+.Sp
+If you ever see a string that looks like this, you'll know you
+printed out a reference by mistake.
+.Sp
+A side effect of this representation is that you can use
+\&\f(CW\*(C`eq\*(C'\fR to see if two references refer to the
+same thing.  (But you should usually use
+\&\f(CW\*(C`==\*(C'\fR instead because it's much faster.)
+.IP \(bu 4
+You can use a string as if it were a reference.  If you use the string
+\&\f(CW"foo"\fR as an array reference, it's taken to be a reference to the
+array \f(CW@foo\fR.  This is called a \fIsymbolic reference\fR.  The declaration
+\&\f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR disables this feature, which can cause
+all sorts of trouble if you use it by accident.
+.PP
+You might prefer to go on to perllol instead of perlref; it
+discusses lists of lists and multidimensional arrays in detail.  After
+that, you should move on to perldsc; it's a Data Structure Cookbook
+that shows recipes for using and printing out arrays of hashes, hashes
+of arrays, and other kinds of data.
+.SH Summary
+.IX Header "Summary"
+Everyone needs compound data structures, and in Perl the way you get
+them is with references.  There are four important rules for managing
+references: Two for making references and two for using them.  Once
+you know these rules you can do most of the important things you need
+to do with references.
+.SH Credits
+.IX Header "Credits"
+Author: Mark Jason Dominus, Plover Systems (\f(CW\*(C`mjd\-perl\-ref+@plover.com\*(C'\fR)
+.PP
+This article originally appeared in \fIThe Perl Journal\fR
+( <http://www.tpj.com/> ) volume 3, #2.  Reprinted with permission.
+.PP
+The original title was \fIUnderstand References Today\fR.
+.SS "Distribution Conditions"
+.IX Subsection "Distribution Conditions"
+Copyright 1998 The Perl Journal.
+.PP
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Irrespective of its distribution, all code examples in these files are
+hereby placed into the public domain.  You are permitted and
+encouraged to use this code in your own programs for fun or for profit
+as you see fit.  A simple comment in the code giving credit would be
+courteous but is not required.
diff --git a/upstream/mageia-cauldron/man1/perlreguts.1 b/upstream/mageia-cauldron/man1/perlreguts.1
new file mode 100644
index 00000000..82ef741d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlreguts.1
@@ -0,0 +1,1092 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREGUTS 1"
+.TH PERLREGUTS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlreguts \- Description of the Perl regular expression engine.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is an attempt to shine some light on the guts of the regex
+engine and how it works. The regex engine represents a significant chunk
+of the perl codebase, but is relatively poorly understood. This document
+is a meagre attempt at addressing this situation. It is derived from the
+author's experience, comments in the source code, other papers on the
+regex engine, feedback on the perl5\-porters mail list, and no doubt other
+places as well.
+.PP
+\&\fBNOTICE!\fR It should be clearly understood that the behavior and
+structures discussed in this represents the state of the engine as the
+author understood it at the time of writing. It is \fBNOT\fR an API
+definition, it is purely an internals guide for those who want to hack
+the regex engine, or understand how the regex engine works. Readers of
+this document are expected to understand perl's regex syntax and its
+usage in detail. If you want to learn about the basics of Perl's
+regular expressions, see perlre. And if you want to replace the
+regex engine with your own, see perlreapi.
+.SH OVERVIEW
+.IX Header "OVERVIEW"
+.SS "A quick note on terms"
+.IX Subsection "A quick note on terms"
+There is some debate as to whether to say "regexp" or "regex". In this
+document we will use the term "regex" unless there is a special reason
+not to, in which case we will explain why.
+.PP
+When speaking about regexes we need to distinguish between their source
+code form and their internal form. In this document we will use the term
+"pattern" when we speak of their textual, source code form, and the term
+"program" when we speak of their internal representation. These
+correspond to the terms \fIS\-regex\fR and \fIB\-regex\fR that Mark Jason
+Dominus employs in his paper on "Rx" ([1] in "REFERENCES").
+.SS "What is a regular expression engine?"
+.IX Subsection "What is a regular expression engine?"
+A regular expression engine is a program that takes a set of constraints
+specified in a mini-language, and then applies those constraints to a
+target string, and determines whether or not the string satisfies the
+constraints. See perlre for a full definition of the language.
+.PP
+In less grandiose terms, the first part of the job is to turn a pattern into
+something the computer can efficiently use to find the matching point in
+the string, and the second part is performing the search itself.
+.PP
+To do this we need to produce a program by parsing the text. We then
+need to execute the program to find the point in the string that
+matches. And we need to do the whole thing efficiently.
+.SS "Structure of a Regexp Program"
+.IX Subsection "Structure of a Regexp Program"
+\fIHigh Level\fR
+.IX Subsection "High Level"
+.PP
+Although it is a bit confusing and some people object to the terminology, it
+is worth taking a look at a comment that has
+been in \fIregexp.h\fR for years:
+.PP
+\&\fIThis is essentially a linear encoding of a nondeterministic
+finite-state machine (aka syntax charts or "railroad normal form" in
+parsing technology).\fR
+.PP
+The term "railroad normal form" is a bit esoteric, with "syntax
+diagram/charts", or "railroad diagram/charts" being more common terms.
+Nevertheless it provides a useful mental image of a regex program: each
+node can be thought of as a unit of track, with a single entry and in
+most cases a single exit point (there are pieces of track that fork, but
+statistically not many), and the whole forms a layout with a
+single entry and single exit point. The matching process can be thought
+of as a car that moves along the track, with the particular route through
+the system being determined by the character read at each possible
+connector point. A car can fall off the track at any point but it may
+only proceed as long as it matches the track.
+.PP
+Thus the pattern \f(CW\*(C`/foo(?:\ew+|\ed+|\es+)bar/\*(C'\fR can be thought of as the
+following chart:
+.PP
+.Vb 10
+\&                      [start]
+\&                         |
+\&                       <foo>
+\&                         |
+\&                   +\-\-\-\-\-+\-\-\-\-\-+
+\&                   |     |     |
+\&                 <\ew+> <\ed+> <\es+>
+\&                   |     |     |
+\&                   +\-\-\-\-\-+\-\-\-\-\-+
+\&                         |
+\&                       <bar>
+\&                         |
+\&                       [end]
+.Ve
+.PP
+The truth of the matter is that perl's regular expressions these days are
+much more complex than this kind of structure, but visualising it this way
+can help when trying to get your bearings, and it matches the
+current implementation pretty closely.
+.PP
+To be more precise, we will say that a regex program is an encoding
+of a graph. Each node in the graph corresponds to part of
+the original regex pattern, such as a literal string or a branch,
+and has a pointer to the nodes representing the next component
+to be matched. Since "node" and "opcode" already have other meanings in the
+perl source, we will call the nodes in a regex program "regops".
+.PP
+The program is represented by an array of \f(CW\*(C`regnode\*(C'\fR structures, one or
+more of which represent a single regop of the program. Struct
+\&\f(CW\*(C`regnode\*(C'\fR is the smallest struct needed, and has a field structure which is
+shared with all the other larger structures.  (Outside this document, the term
+"regnode" is sometimes used to mean "regop", which could be confusing.)
+.PP
+The "next" pointers of all regops except \f(CW\*(C`BRANCH\*(C'\fR implement concatenation;
+a "next" pointer with a \f(CW\*(C`BRANCH\*(C'\fR on both ends of it is connecting two
+alternatives.  [Here we have one of the subtle syntax dependencies: an
+individual \f(CW\*(C`BRANCH\*(C'\fR (as opposed to a collection of them) is never
+concatenated with anything because of operator precedence.]
+.PP
+The operand of some types of regop is a literal string; for others,
+it is a regop leading into a sub-program.  In particular, the operand
+of a \f(CW\*(C`BRANCH\*(C'\fR node is the first regop of the branch.
+.PP
+\&\fBNOTE\fR: As the railroad metaphor suggests, this is \fBnot\fR a tree
+structure:  the tail of the branch connects to the thing following the
+set of \f(CW\*(C`BRANCH\*(C'\fRes.  It is a like a single line of railway track that
+splits as it goes into a station or railway yard and rejoins as it comes
+out the other side.
+.PP
+\fIRegops\fR
+.IX Subsection "Regops"
+.PP
+The base structure of a regop is defined in \fIregexp.h\fR as follows:
+.PP
+.Vb 5
+\&    struct regnode {
+\&        U8  flags;    /* Various purposes, sometimes overridden */
+\&        U8  type;     /* Opcode value as specified by regnodes.h */
+\&        U16 next_off; /* Offset in size regnode */
+\&    };
+.Ve
+.PP
+Other larger \f(CW\*(C`regnode\*(C'\fR\-like structures are defined in \fIregcomp.h\fR. They
+are almost like subclasses in that they have the same fields as
+\&\f(CW\*(C`regnode\*(C'\fR, with possibly additional fields following in
+the structure, and in some cases the specific meaning (and name)
+of some of base fields are overridden. The following is a more
+complete description.
+.ie n .IP """regnode_1""" 4
+.el .IP \f(CWregnode_1\fR 4
+.IX Item "regnode_1"
+.PD 0
+.ie n .IP """regnode_2""" 4
+.el .IP \f(CWregnode_2\fR 4
+.IX Item "regnode_2"
+.PD
+\&\f(CW\*(C`regnode_1\*(C'\fR structures have the same header, followed by a single
+four-byte argument; \f(CW\*(C`regnode_2\*(C'\fR structures contain two two-byte
+arguments instead:
+.Sp
+.Vb 2
+\&    regnode_1                U32 arg1;
+\&    regnode_2                U16 arg1;  U16 arg2;
+.Ve
+.ie n .IP """regnode_string""" 4
+.el .IP \f(CWregnode_string\fR 4
+.IX Item "regnode_string"
+\&\f(CW\*(C`regnode_string\*(C'\fR structures, used for literal strings, follow the header
+with a one-byte length and then the string data. Strings are padded on
+the tail end with zero bytes so that the total length of the node is a
+multiple of four bytes:
+.Sp
+.Vb 2
+\&    regnode_string           char string[1];
+\&                             U8 str_len; /* overrides flags */
+.Ve
+.ie n .IP """regnode_charclass""" 4
+.el .IP \f(CWregnode_charclass\fR 4
+.IX Item "regnode_charclass"
+Bracketed character classes are represented by \f(CW\*(C`regnode_charclass\*(C'\fR
+structures, which have a four-byte argument and then a 32\-byte (256\-bit)
+bitmap indicating which characters in the Latin1 range are included in
+the class.
+.Sp
+.Vb 2
+\&    regnode_charclass        U32 arg1;
+\&                             char bitmap[ANYOF_BITMAP_SIZE];
+.Ve
+.Sp
+Various flags whose names begin with \f(CW\*(C`ANYOF_\*(C'\fR are used for special
+situations.  Above Latin1 matches and things not known until run-time
+are stored in "Perl's pprivate structure".
+.ie n .IP """regnode_charclass_posixl""" 4
+.el .IP \f(CWregnode_charclass_posixl\fR 4
+.IX Item "regnode_charclass_posixl"
+There is also a larger form of a char class structure used to represent
+POSIX char classes under \f(CW\*(C`/l\*(C'\fR matching,
+called \f(CW\*(C`regnode_charclass_posixl\*(C'\fR which has an
+additional 32\-bit bitmap indicating which POSIX char classes
+have been included.
+.Sp
+.Vb 3
+\&   regnode_charclass_posixl U32 arg1;
+\&                            char bitmap[ANYOF_BITMAP_SIZE];
+\&                            U32 classflags;
+.Ve
+.PP
+\&\fIregnodes.h\fR defines an array called \f(CW\*(C`PL_regnode_arg_len[]\*(C'\fR which gives the size
+of each opcode in units of \f(CW\*(C`size regnode\*(C'\fR (4\-byte). A macro is used
+to calculate the size of an \f(CW\*(C`EXACT\*(C'\fR node based on its \f(CW\*(C`str_len\*(C'\fR field.
+.PP
+The regops are defined in \fIregnodes.h\fR which is generated from
+\&\fIregcomp.sym\fR by \fIregcomp.pl\fR. Currently the maximum possible number
+of distinct regops is restricted to 256, with about a quarter already
+used.
+.PP
+A set of macros makes accessing the fields
+easier and more consistent. These include \f(CWOP()\fR, which is used to determine
+the type of a \f(CW\*(C`regnode\*(C'\fR\-like structure; \f(CWNEXT_OFF()\fR, which is the offset to
+the next node (more on this later); \f(CWARG()\fR, \f(CWARG1()\fR, \f(CWARG2()\fR, \f(CWARG_SET()\fR,
+and equivalents for reading and setting the arguments; and \f(CWSTR_LEN()\fR,
+\&\f(CWSTRING()\fR and \f(CWOPERAND()\fR for manipulating strings and regop bearing
+types.
+.PP
+\fIWhat regnode is next?\fR
+.IX Subsection "What regnode is next?"
+.PP
+There are two distinct concepts of "next regnode" in the regex engine,
+and it is important to keep them distinct in your thinking as they
+overlap conceptually in many places, but where they don't overlap the
+difference is critical. For the majority of regnode types the two
+concepts are (nearly) identical in practice. The two types are
+\&\f(CW\*(C`REGNODE_AFTER\*(C'\fR which is used heavily during compilation but only
+occasionally during execution and \f(CW\*(C`regnext\*(C'\fR which is used heavily
+during execution, and only occasionally during compilation.
+.IP """REGNODE_AFTER""" 4
+.IX Item """REGNODE_AFTER"""
+This is the "positionally next regnode" in the compiled regex program.
+For the smaller regnode types it is \f(CW\*(C`regnode_ptr+1\*(C'\fR under the hood, but
+as regnode sizes vary and can change over time we offer macros which
+hide the gory details.
+.Sp
+It is heavily used in the compiler phase but is only used by a few
+select regnode types in the execution phase. It is also heavily used in
+the code for dumping the regexp program for debugging.
+.Sp
+There are a selection of macros which can be used to compute this as
+efficiently as possible depending on the circumstances. The canonical
+macro is \f(CWREGNODE_AFTER()\fR, which is the most powerful and should handle
+any case we have, but is also potentially the slowest. There are two
+additional macros for the special case that you KNOW the current regnode
+size is constant, and you know its type or opcode. In which case you can
+use \f(CWREGNODE_AFTER_opcode()\fR or \f(CWREGNODE_AFTER_type()\fR.
+.Sp
+In older versions of the regex engine \f(CWREGNODE_AFTER()\fR was called
+\&\f(CW\*(C`NEXTOPER\*(C'\fR but this was found to be confusing and it was renamed. There
+is also a \f(CWREGNODE_BEFORE()\fR, but it is unsafe and should not be used
+in new code.
+.IP """regnext""" 4
+.IX Item """regnext"""
+This is the regnode which can be reached by jumping forward by the value
+of the \f(CWNEXT_OFF()\fR member of the regnode, or in a few cases for longer
+jumps by the \f(CW\*(C`arg1\*(C'\fR field of the \f(CW\*(C`regnode_1\*(C'\fR structure. The subroutine
+\&\f(CWregnext()\fR handles this transparently. In the majority of cases the
+\&\f(CW\*(C`regnext\*(C'\fR for a regnode is the regnode which should be executed after the
+current one has successfully matched, but in some cases this may not be
+true. In loop control and branch control regnode types the regnext may
+signify something special, for BRANCH nodes \f(CW\*(C`regnext\*(C'\fR is the
+next BRANCH that should be executed if the current one fails execution,
+and some loop control regnodes set the regnext to be the end of the loop
+so they can jump to their cleanup if the current iteration fails to match.
+.PP
+Most regnode types do not create a branch in the execution flow, and
+leaving aside optimizations the two concepts of "next" are the same.
+For instance the \f(CW\*(C`regnext\*(C'\fR and \f(CW\*(C`REGNODE_AFTER\*(C'\fR of a SBOL opcode are
+the same during compilation phase. The main place this is not true is
+\&\f(CW\*(C`BRANCH\*(C'\fR regnodes where the \f(CW\*(C`REGNODE_AFTER\*(C'\fR represents the start of
+the pattern in the branch and the \f(CW\*(C`regnext\*(C'\fR represents the linkage to
+the next BRANCH should this one fail to match, or 0 if it is the last
+branch. The looping logic for quantifiers also makes similar use of
+the distinction between the two types, with \f(CW\*(C`REGNODE_AFTER\*(C'\fR being the
+inside of the loop construct, and the \f(CW\*(C`regnext\*(C'\fR pointing at the end
+of the loop.
+.PP
+During compilation the engine may not know what the regnext is for a
+given node, so during compilation \f(CW\*(C`regnext\*(C'\fR is only used where it must
+be used and is known to be correct. At the very end of the compilation
+phase we walk the regex program and correct the regnext data as
+appropriate, and also perform various optimizations which may result in
+regnodes that were required during construction becoming redundant, or
+we may replace a large regnode with a much smaller one and filling in the
+gap with OPTIMIZED regnodes. Thus we might start with something like
+this:
+.PP
+.Vb 5
+\&    BRANCH
+\&      EXACT "foo"
+\&    BRANCH
+\&      EXACT "bar"
+\&    EXACT "!"
+.Ve
+.PP
+and replace it with something like:
+.PP
+.Vb 5
+\&    TRIE foo|bar
+\&    OPTIMIZED
+\&    OPTIMIZED
+\&    OPTIMIZED
+\&    EXACT "!"
+.Ve
+.PP
+the \f(CW\*(C`REGNODE_AFTER\*(C'\fR for the \f(CW\*(C`TRIE\*(C'\fR node would be an \f(CW\*(C`OPTIMIZED\*(C'\fR
+regnode, and in theory the \f(CW\*(C`regnext\*(C'\fR would be the same as the
+\&\f(CW\*(C`REGNODE_AFTER\*(C'\fR. But it would be inefficient to execute the OPTIMIZED
+regnode as a noop three times, so the optimizer fixes the \f(CW\*(C`regnext\*(C'\fR so
+such nodes are skipped during execution phase.
+.PP
+During execution phases we use the \f(CWregnext()\fR almost exclusively, and
+only use \f(CW\*(C`REGNODE_AFTER\*(C'\fR in special cases where it has a well defined
+meaning for a given regnode type. For instance /x+/ results in
+.PP
+.Vb 3
+\&    PLUS
+\&        EXACT "x"
+\&    END
+.Ve
+.PP
+the \f(CW\*(C`regnext\*(C'\fR of the \f(CW\*(C`PLUS\*(C'\fR regnode is the \f(CW\*(C`END\*(C'\fR regnode, and the
+\&\f(CW\*(C`REGNODE_AFTER\*(C'\fR of the \f(CW\*(C`PLUS\*(C'\fR regnode is the \f(CW\*(C`EXACT\*(C'\fR regnode. The
+\&\f(CW\*(C`regnext\*(C'\fR and \f(CW\*(C`REGNODE_AFTER\*(C'\fR of the \f(CW\*(C`EXACT\*(C'\fR regnode is the
+\&\f(CW\*(C`END\*(C'\fR regnode.
+.SH "Process Overview"
+.IX Header "Process Overview"
+Broadly speaking, performing a match of a string against a pattern
+involves the following steps:
+.IP "A. Compilation" 5
+.IX Item "A. Compilation"
+.RS 5
+.PD 0
+.IP "1. Parsing" 5
+.IX Item "1. Parsing"
+.IP "2. Peep-hole optimisation and analysis" 5
+.IX Item "2. Peep-hole optimisation and analysis"
+.RE
+.RS 5
+.RE
+.IP "B. Execution" 5
+.IX Item "B. Execution"
+.RS 5
+.IP "3. Start position and no-match optimisations" 5
+.IX Item "3. Start position and no-match optimisations"
+.IP "4. Program execution" 5
+.IX Item "4. Program execution"
+.RE
+.RS 5
+.RE
+.PD
+.PP
+Where these steps occur in the actual execution of a perl program is
+determined by whether the pattern involves interpolating any string
+variables. If interpolation occurs, then compilation happens at run time. If it
+does not, then compilation is performed at compile time. (The \f(CW\*(C`/o\*(C'\fR modifier changes this,
+as does \f(CW\*(C`qr//\*(C'\fR to a certain extent.) The engine doesn't really care that
+much.
+.SS Compilation
+.IX Subsection "Compilation"
+This code resides primarily in \fIregcomp.c\fR, along with the header files
+\&\fIregcomp.h\fR, \fIregexp.h\fR and \fIregnodes.h\fR.
+.PP
+Compilation starts with \f(CWpregcomp()\fR, which is mostly an initialisation
+wrapper which farms work out to two other routines for the heavy lifting: the
+first is \f(CWreg()\fR, which is the start point for parsing; the second,
+\&\f(CWstudy_chunk()\fR, is responsible for optimisation.
+.PP
+Initialisation in \f(CWpregcomp()\fR mostly involves the creation and data-filling
+of a special structure, \f(CW\*(C`RExC_state_t\*(C'\fR (defined in \fIregcomp.c\fR).
+Almost all internally-used routines in \fIregcomp.h\fR take a pointer to one
+of these structures as their first argument, with the name \f(CW\*(C`pRExC_state\*(C'\fR.
+This structure is used to store the compilation state and contains many
+fields. Likewise there are many macros which operate on this
+variable: anything that looks like \f(CW\*(C`RExC_xxxx\*(C'\fR is a macro that operates on
+this pointer/structure.
+.PP
+\&\f(CWreg()\fR is the start of the parse process. It is responsible for
+parsing an arbitrary chunk of pattern up to either the end of the
+string, or the first closing parenthesis it encounters in the pattern.
+This means it can be used to parse the top-level regex, or any section
+inside of a grouping parenthesis. It also handles the "special parens"
+that perl's regexes have. For instance when parsing \f(CW\*(C`/x(?:foo)y/\*(C'\fR,
+\&\f(CWreg()\fR will at one point be called to parse from the "?" symbol up to
+and including the ")".
+.PP
+Additionally, \f(CWreg()\fR is responsible for parsing the one or more
+branches from the pattern, and for "finishing them off" by correctly
+setting their next pointers. In order to do the parsing, it repeatedly
+calls out to \f(CWregbranch()\fR, which is responsible for handling up to the
+first \f(CW\*(C`|\*(C'\fR symbol it sees.
+.PP
+\&\f(CWregbranch()\fR in turn calls \f(CWregpiece()\fR which
+handles "things" followed by a quantifier. In order to parse the
+"things", \f(CWregatom()\fR is called. This is the lowest level routine, which
+parses out constant strings, character classes, and the
+various special symbols like \f(CW\*(C`$\*(C'\fR. If \f(CWregatom()\fR encounters a "("
+character it in turn calls \f(CWreg()\fR.
+.PP
+There used to be two main passes involved in parsing, the first to
+calculate the size of the compiled program, and the second to actually
+compile it.  But now there is only one main pass, with an initial crude
+guess based on the length of the input pattern, which is increased if
+necessary as parsing proceeds, and afterwards, trimmed to the actual
+amount used.
+.PP
+However, it may happen that parsing must be restarted at the beginning
+when various circumstances occur along the way.  An example is if the
+program turns out to be so large that there are jumps in it that won't
+fit in the normal 16 bits available.  There are two special regops that
+can hold bigger jump destinations, BRANCHJ and LONGBRANCH.  The parse is
+restarted, and these are used instead of the normal shorter ones.
+Whenever restarting the parse is required, the function returns failure
+and sets a flag as to what needs to be done.  This is passed up to the
+top level routine which takes the appropriate action and restarts from
+scratch.  In the case of needing longer jumps, the \f(CW\*(C`RExC_use_BRANCHJ\*(C'\fR
+flag is set in the \f(CW\*(C`RExC_state_t\*(C'\fR structure, which the functions know
+to inspect before deciding how to do branches.
+.PP
+In most instances, the function that discovers the issue sets the causal
+flag and returns failure immediately.  "Parsing complications"
+contains an explicit example of how this works.  In other cases, such as
+a forward reference to a numbered parenthetical grouping, we need to
+finish the parse to know if that numbered grouping actually appears in
+the pattern.  In those cases, the parse is just redone at the end, with
+the knowledge of how many groupings occur in it.
+.PP
+The routine \f(CWregtail()\fR is called by both \f(CWreg()\fR and \f(CWregbranch()\fR
+in order to "set the tail pointer" correctly. When executing and
+we get to the end of a branch, we need to go to the node following the
+grouping parens. When parsing, however, we don't know where the end will
+be until we get there, so when we do we must go back and update the
+offsets as appropriate. \f(CW\*(C`regtail\*(C'\fR is used to make this easier.
+.PP
+A subtlety of the parsing process means that a regex like \f(CW\*(C`/foo/\*(C'\fR is
+originally parsed into an alternation with a single branch. It is only
+afterwards that the optimiser converts single branch alternations into the
+simpler form.
+.PP
+\fIParse Call Graph and a Grammar\fR
+.IX Subsection "Parse Call Graph and a Grammar"
+.PP
+The call graph looks like this:
+.PP
+.Vb 10
+\& reg()                        # parse a top level regex, or inside of
+\&                              # parens
+\&     regbranch()              # parse a single branch of an alternation
+\&         regpiece()           # parse a pattern followed by a quantifier
+\&             regatom()        # parse a simple pattern
+\&                 regclass()   #   used to handle a class
+\&                 reg()        #   used to handle a parenthesised
+\&                              #   subpattern
+\&                 ....
+\&         ...
+\&         regtail()            # finish off the branch
+\&     ...
+\&     regtail()                # finish off the branch sequence. Tie each
+\&                              # branch\*(Aqs tail to the tail of the
+\&                              # sequence
+\&                              # (NEW) In Debug mode this is
+\&                              # regtail_study().
+.Ve
+.PP
+A grammar form might be something like this:
+.PP
+.Vb 11
+\&    atom  : constant | class
+\&    quant : \*(Aq*\*(Aq | \*(Aq+\*(Aq | \*(Aq?\*(Aq | \*(Aq{min,max}\*(Aq
+\&    _branch: piece
+\&           | piece _branch
+\&           | nothing
+\&    branch: _branch
+\&          | _branch \*(Aq|\*(Aq branch
+\&    group : \*(Aq(\*(Aq branch \*(Aq)\*(Aq
+\&    _piece: atom | group
+\&    piece : _piece
+\&          | _piece quant
+.Ve
+.PP
+\fIParsing complications\fR
+.IX Subsection "Parsing complications"
+.PP
+The implication of the above description is that a pattern containing nested
+parentheses will result in a call graph which cycles through \f(CWreg()\fR,
+\&\f(CWregbranch()\fR, \f(CWregpiece()\fR, \f(CWregatom()\fR, \f(CWreg()\fR, \f(CWregbranch()\fR \fIetc\fR
+multiple times, until the deepest level of nesting is reached. All the above
+routines return a pointer to a \f(CW\*(C`regnode\*(C'\fR, which is usually the last regnode
+added to the program. However, one complication is that \fBreg()\fR returns NULL
+for parsing \f(CW\*(C`(?:)\*(C'\fR syntax for embedded modifiers, setting the flag
+\&\f(CW\*(C`TRYAGAIN\*(C'\fR. The \f(CW\*(C`TRYAGAIN\*(C'\fR propagates upwards until it is captured, in
+some cases by \f(CWregatom()\fR, but otherwise unconditionally by
+\&\f(CWregbranch()\fR. Hence it will never be returned by \f(CWregbranch()\fR to
+\&\f(CWreg()\fR. This flag permits patterns such as \f(CW\*(C`(?i)+\*(C'\fR to be detected as
+errors (\fIQuantifier follows nothing in regex; marked by <\-\- HERE in m/(?i)+
+<\-\- HERE /\fR).
+.PP
+Another complication is that the representation used for the program differs
+if it needs to store Unicode, but it's not always possible to know for sure
+whether it does until midway through parsing. The Unicode representation for
+the program is larger, and cannot be matched as efficiently. (See "Unicode
+and Localisation Support" below for more details as to why.)  If the pattern
+contains literal Unicode, it's obvious that the program needs to store
+Unicode. Otherwise, the parser optimistically assumes that the more
+efficient representation can be used, and starts sizing on this basis.
+However, if it then encounters something in the pattern which must be stored
+as Unicode, such as an \f(CW\*(C`\ex{...}\*(C'\fR escape sequence representing a character
+literal, then this means that all previously calculated sizes need to be
+redone, using values appropriate for the Unicode representation.  This
+is another instance where the parsing needs to be restarted, and it can
+and is done immediately.  The function returns failure, and sets the
+flag \f(CW\*(C`RESTART_UTF8\*(C'\fR (encapsulated by using the macro \f(CW\*(C`REQUIRE_UTF8\*(C'\fR).
+This restart request is propagated up the call chain in a similar
+fashion, until it is "caught" in \f(CWPerl_re_op_compile()\fR, which marks
+the pattern as containing Unicode, and restarts the sizing pass. It is
+also possible for constructions within run-time code blocks to turn out
+to need Unicode representation., which is signalled by
+\&\f(CWS_compile_runtime_code()\fR returning false to \f(CWPerl_re_op_compile()\fR.
+.PP
+The restart was previously implemented using a \f(CW\*(C`longjmp\*(C'\fR in \f(CWregatom()\fR
+back to a \f(CW\*(C`setjmp\*(C'\fR in \f(CWPerl_re_op_compile()\fR, but this proved to be
+problematic as the latter is a large function containing many automatic
+variables, which interact badly with the emergent control flow of \f(CW\*(C`setjmp\*(C'\fR.
+.PP
+\fIDebug Output\fR
+.IX Subsection "Debug Output"
+.PP
+Starting in the 5.9.x development version of perl you can \f(CW\*(C`use re
+Debug => \*(AqPARSE\*(Aq\*(C'\fR to see some trace information about the parse
+process. We will start with some simple patterns and build up to more
+complex patterns.
+.PP
+So when we parse \f(CW\*(C`/foo/\*(C'\fR we see something like the following table. The
+left shows what is being parsed, and the number indicates where the next regop
+would go. The stuff on the right is the trace output of the graph. The
+names are chosen to be short to make it less dense on the screen. 'tsdy'
+is a special form of \f(CWregtail()\fR which does some extra analysis.
+.PP
+.Vb 6
+\& >foo<             1    reg
+\&                          brnc
+\&                            piec
+\&                              atom
+\& ><                4      tsdy~ EXACT <foo> (EXACT) (1)
+\&                              ~ attach to END (3) offset to 2
+.Ve
+.PP
+The resulting program then looks like:
+.PP
+.Vb 2
+\&   1: EXACT <foo>(3)
+\&   3: END(0)
+.Ve
+.PP
+As you can see, even though we parsed out a branch and a piece, it was ultimately
+only an atom. The final program shows us how things work. We have an \f(CW\*(C`EXACT\*(C'\fR regop,
+followed by an \f(CW\*(C`END\*(C'\fR regop. The number in parens indicates where the \f(CW\*(C`regnext\*(C'\fR of
+the node goes. The \f(CW\*(C`regnext\*(C'\fR of an \f(CW\*(C`END\*(C'\fR regop is unused, as \f(CW\*(C`END\*(C'\fR regops mean
+we have successfully matched. The number on the left indicates the position of
+the regop in the regnode array.
+.PP
+Now let's try a harder pattern. We will add a quantifier, so now we have the pattern
+\&\f(CW\*(C`/foo+/\*(C'\fR. We will see that \f(CWregbranch()\fR calls \f(CWregpiece()\fR twice.
+.PP
+.Vb 10
+\& >foo+<            1    reg
+\&                          brnc
+\&                            piec
+\&                              atom
+\& >o+<              3        piec
+\&                              atom
+\& ><                6        tail~ EXACT <fo> (1)
+\&                   7      tsdy~ EXACT <fo> (EXACT) (1)
+\&                              ~ PLUS (END) (3)
+\&                              ~ attach to END (6) offset to 3
+.Ve
+.PP
+And we end up with the program:
+.PP
+.Vb 4
+\&   1: EXACT <fo>(3)
+\&   3: PLUS(6)
+\&   4:   EXACT <o>(0)
+\&   6: END(0)
+.Ve
+.PP
+Now we have a special case. The \f(CW\*(C`EXACT\*(C'\fR regop has a \f(CW\*(C`regnext\*(C'\fR of 0. This is
+because if it matches it should try to match itself again. The \f(CW\*(C`PLUS\*(C'\fR regop
+handles the actual failure of the \f(CW\*(C`EXACT\*(C'\fR regop and acts appropriately (going
+to regnode 6 if the \f(CW\*(C`EXACT\*(C'\fR matched at least once, or failing if it didn't).
+.PP
+Now for something much more complex: \f(CW\*(C`/x(?:foo*|b[a][rR])(foo|bar)$/\*(C'\fR
+.PP
+.Vb 10
+\& >x(?:foo*|b...    1    reg
+\&                          brnc
+\&                            piec
+\&                              atom
+\& >(?:foo*|b[...    3        piec
+\&                              atom
+\& >?:foo*|b[a...                 reg
+\& >foo*|b[a][...                   brnc
+\&                                    piec
+\&                                      atom
+\& >o*|b[a][rR...    5                piec
+\&                                      atom
+\& >|b[a][rR])...    8                tail~ EXACT <fo> (3)
+\& >b[a][rR])(...    9              brnc
+\&                  10                piec
+\&                                      atom
+\& >[a][rR])(f...   12                piec
+\&                                      atom
+\& >a][rR])(fo...                         clas
+\& >[rR])(foo|...   14                tail~ EXACT <b> (10)
+\&                                    piec
+\&                                      atom
+\& >rR])(foo|b...                         clas
+\& >)(foo|bar)...   25                tail~ EXACT <a> (12)
+\&                                  tail~ BRANCH (3)
+\&                  26              tsdy~ BRANCH (END) (9)
+\&                                      ~ attach to TAIL (25) offset to 16
+\&                                  tsdy~ EXACT <fo> (EXACT) (4)
+\&                                      ~ STAR (END) (6)
+\&                                      ~ attach to TAIL (25) offset to 19
+\&                                  tsdy~ EXACT <b> (EXACT) (10)
+\&                                      ~ EXACT <a> (EXACT) (12)
+\&                                      ~ ANYOF[Rr] (END) (14)
+\&                                      ~ attach to TAIL (25) offset to 11
+\& >(foo|bar)$<               tail~ EXACT <x> (1)
+\&                            piec
+\&                              atom
+\& >foo|bar)$<                    reg
+\&                  28              brnc
+\&                                    piec
+\&                                      atom
+\& >|bar)$<         31              tail~ OPEN1 (26)
+\& >bar)$<                          brnc
+\&                  32                piec
+\&                                      atom
+\& >)$<             34              tail~ BRANCH (28)
+\&                  36              tsdy~ BRANCH (END) (31)
+\&                                     ~ attach to CLOSE1 (34) offset to 3
+\&                                  tsdy~ EXACT <foo> (EXACT) (29)
+\&                                     ~ attach to CLOSE1 (34) offset to 5
+\&                                  tsdy~ EXACT <bar> (EXACT) (32)
+\&                                     ~ attach to CLOSE1 (34) offset to 2
+\& >$<                        tail~ BRANCH (3)
+\&                                ~ BRANCH (9)
+\&                                ~ TAIL (25)
+\&                            piec
+\&                              atom
+\& ><               37        tail~ OPEN1 (26)
+\&                                ~ BRANCH (28)
+\&                                ~ BRANCH (31)
+\&                                ~ CLOSE1 (34)
+\&                  38      tsdy~ EXACT <x> (EXACT) (1)
+\&                              ~ BRANCH (END) (3)
+\&                              ~ BRANCH (END) (9)
+\&                              ~ TAIL (END) (25)
+\&                              ~ OPEN1 (END) (26)
+\&                              ~ BRANCH (END) (28)
+\&                              ~ BRANCH (END) (31)
+\&                              ~ CLOSE1 (END) (34)
+\&                              ~ EOL (END) (36)
+\&                              ~ attach to END (37) offset to 1
+.Ve
+.PP
+Resulting in the program
+.PP
+.Vb 10
+\&   1: EXACT <x>(3)
+\&   3: BRANCH(9)
+\&   4:   EXACT <fo>(6)
+\&   6:   STAR(26)
+\&   7:     EXACT <o>(0)
+\&   9: BRANCH(25)
+\&  10:   EXACT <ba>(14)
+\&  12:   OPTIMIZED (2 nodes)
+\&  14:   ANYOF[Rr](26)
+\&  25: TAIL(26)
+\&  26: OPEN1(28)
+\&  28:   TRIE\-EXACT(34)
+\&        [StS:1 Wds:2 Cs:6 Uq:5 #Sts:7 Mn:3 Mx:3 Stcls:bf]
+\&          <foo>
+\&          <bar>
+\&  30:   OPTIMIZED (4 nodes)
+\&  34: CLOSE1(36)
+\&  36: EOL(37)
+\&  37: END(0)
+.Ve
+.PP
+Here we can see a much more complex program, with various optimisations in
+play. At regnode 10 we see an example where a character class with only
+one character in it was turned into an \f(CW\*(C`EXACT\*(C'\fR node. We can also see where
+an entire alternation was turned into a \f(CW\*(C`TRIE\-EXACT\*(C'\fR node. As a consequence,
+some of the regnodes have been marked as optimised away. We can see that
+the \f(CW\*(C`$\*(C'\fR symbol has been converted into an \f(CW\*(C`EOL\*(C'\fR regop, a special piece of
+code that looks for \f(CW\*(C`\en\*(C'\fR or the end of the string.
+.PP
+The next pointer for \f(CW\*(C`BRANCH\*(C'\fRes is interesting in that it points at where
+execution should go if the branch fails. When executing, if the engine
+tries to traverse from a branch to a \f(CW\*(C`regnext\*(C'\fR that isn't a branch then
+the engine will know that the entire set of branches has failed.
+.PP
+\fIPeep-hole Optimisation and Analysis\fR
+.IX Subsection "Peep-hole Optimisation and Analysis"
+.PP
+The regular expression engine can be a weighty tool to wield. On long
+strings and complex patterns it can end up having to do a lot of work
+to find a match, and even more to decide that no match is possible.
+Consider a situation like the following pattern.
+.PP
+.Vb 1
+\&   \*(Aqababababababababababab\*(Aq =~ /(a|b)*z/
+.Ve
+.PP
+The \f(CW\*(C`(a|b)*\*(C'\fR part can match at every char in the string, and then fail
+every time because there is no \f(CW\*(C`z\*(C'\fR in the string. So obviously we can
+avoid using the regex engine unless there is a \f(CW\*(C`z\*(C'\fR in the string.
+Likewise in a pattern like:
+.PP
+.Vb 1
+\&   /foo(\ew+)bar/
+.Ve
+.PP
+In this case we know that the string must contain a \f(CW\*(C`foo\*(C'\fR which must be
+followed by \f(CW\*(C`bar\*(C'\fR. We can use Fast Boyer-Moore matching as implemented
+in \f(CWfbm_instr()\fR to find the location of these strings. If they don't exist
+then we don't need to resort to the much more expensive regex engine.
+Even better, if they do exist then we can use their positions to
+reduce the search space that the regex engine needs to cover to determine
+if the entire pattern matches.
+.PP
+There are various aspects of the pattern that can be used to facilitate
+optimisations along these lines:
+.IP \(bu 5
+anchored fixed strings
+.IP \(bu 5
+floating fixed strings
+.IP \(bu 5
+minimum and maximum length requirements
+.IP \(bu 5
+start class
+.IP \(bu 5
+Beginning/End of line positions
+.PP
+Another form of optimisation that can occur is the post-parse "peep-hole"
+optimisation, where inefficient constructs are replaced by more efficient
+constructs. The \f(CW\*(C`TAIL\*(C'\fR regops which are used during parsing to mark the end
+of branches and the end of groups are examples of this. These regops are used
+as place-holders during construction and "always match" so they can be
+"optimised away" by making the things that point to the \f(CW\*(C`TAIL\*(C'\fR point to the
+thing that \f(CW\*(C`TAIL\*(C'\fR points to, thus "skipping" the node.
+.PP
+Another optimisation that can occur is that of "\f(CW\*(C`EXACT\*(C'\fR merging" which is
+where two consecutive \f(CW\*(C`EXACT\*(C'\fR nodes are merged into a single
+regop. An even more aggressive form of this is that a branch
+sequence of the form \f(CW\*(C`EXACT BRANCH ... EXACT\*(C'\fR can be converted into a
+\&\f(CW\*(C`TRIE\-EXACT\*(C'\fR regop.
+.PP
+All of this occurs in the routine \f(CWstudy_chunk()\fR which uses a special
+structure \f(CW\*(C`scan_data_t\*(C'\fR to store the analysis that it has performed, and
+does the "peep-hole" optimisations as it goes.
+.PP
+The code involved in \f(CWstudy_chunk()\fR is extremely cryptic. Be careful. :\-)
+.SS Execution
+.IX Subsection "Execution"
+Execution of a regex generally involves two phases, the first being
+finding the start point in the string where we should match from,
+and the second being running the regop interpreter.
+.PP
+If we can tell that there is no valid start point then we don't bother running
+the interpreter at all. Likewise, if we know from the analysis phase that we
+cannot detect a short-cut to the start position, we go straight to the
+interpreter.
+.PP
+The two entry points are \f(CWre_intuit_start()\fR and \f(CWpregexec()\fR. These routines
+have a somewhat incestuous relationship with overlap between their functions,
+and \f(CWpregexec()\fR may even call \f(CWre_intuit_start()\fR on its own. Nevertheless
+other parts of the perl source code may call into either, or both.
+.PP
+Execution of the interpreter itself used to be recursive, but thanks to the
+efforts of Dave Mitchell in the 5.9.x development track, that has changed: now an
+internal stack is maintained on the heap and the routine is fully
+iterative. This can make it tricky as the code is quite conservative
+about what state it stores, with the result that two consecutive lines in the
+code can actually be running in totally different contexts due to the
+simulated recursion.
+.PP
+\fIStart position and no-match optimisations\fR
+.IX Subsection "Start position and no-match optimisations"
+.PP
+\&\f(CWre_intuit_start()\fR is responsible for handling start points and no-match
+optimisations as determined by the results of the analysis done by
+\&\f(CWstudy_chunk()\fR (and described in "Peep-hole Optimisation and Analysis").
+.PP
+The basic structure of this routine is to try to find the start\- and/or
+end-points of where the pattern could match, and to ensure that the string
+is long enough to match the pattern. It tries to use more efficient
+methods over less efficient methods and may involve considerable
+cross-checking of constraints to find the place in the string that matches.
+For instance it may try to determine that a given fixed string must be
+not only present but a certain number of chars before the end of the
+string, or whatever.
+.PP
+It calls several other routines, such as \f(CWfbm_instr()\fR which does
+Fast Boyer Moore matching and \f(CWfind_byclass()\fR which is responsible for
+finding the start using the first mandatory regop in the program.
+.PP
+When the optimisation criteria have been satisfied, \f(CWreg_try()\fR is called
+to perform the match.
+.PP
+\fIProgram execution\fR
+.IX Subsection "Program execution"
+.PP
+\&\f(CWpregexec()\fR is the main entry point for running a regex. It contains
+support for initialising the regex interpreter's state, running
+\&\f(CWre_intuit_start()\fR if needed, and running the interpreter on the string
+from various start positions as needed. When it is necessary to use
+the regex interpreter \f(CWpregexec()\fR calls \f(CWregtry()\fR.
+.PP
+\&\f(CWregtry()\fR is the entry point into the regex interpreter. It expects
+as arguments a pointer to a \f(CW\*(C`regmatch_info\*(C'\fR structure and a pointer to
+a string.  It returns an integer 1 for success and a 0 for failure.
+It is basically a set-up wrapper around \f(CWregmatch()\fR.
+.PP
+\&\f(CW\*(C`regmatch\*(C'\fR is the main "recursive loop" of the interpreter. It is
+basically a giant switch statement that implements a state machine, where
+the possible states are the regops themselves, plus a number of additional
+intermediate and failure states. A few of the states are implemented as
+subroutines but the bulk are inline code.
+.SH MISCELLANEOUS
+.IX Header "MISCELLANEOUS"
+.SS "Unicode and Localisation Support"
+.IX Subsection "Unicode and Localisation Support"
+When dealing with strings containing characters that cannot be represented
+using an eight-bit character set, perl uses an internal representation
+that is a permissive version of Unicode's UTF\-8 encoding[2]. This uses single
+bytes to represent characters from the ASCII character set, and sequences
+of two or more bytes for all other characters. (See perlunitut
+for more information about the relationship between UTF\-8 and perl's
+encoding, utf8. The difference isn't important for this discussion.)
+.PP
+No matter how you look at it, Unicode support is going to be a pain in a
+regex engine. Tricks that might be fine when you have 256 possible
+characters often won't scale to handle the size of the UTF\-8 character
+set.  Things you can take for granted with ASCII may not be true with
+Unicode. For instance, in ASCII, it is safe to assume that
+\&\f(CW\*(C`sizeof(char1) == sizeof(char2)\*(C'\fR, but in UTF\-8 it isn't. Unicode case folding is
+vastly more complex than the simple rules of ASCII, and even when not
+using Unicode but only localised single byte encodings, things can get
+tricky (for example, \fBLATIN SMALL LETTER SHARP S\fR (U+00DF, ß)
+should match 'SS' in localised case-insensitive matching).
+.PP
+Making things worse is that UTF\-8 support was a later addition to the
+regex engine (as it was to perl) and this necessarily  made things a lot
+more complicated. Obviously it is easier to design a regex engine with
+Unicode support in mind from the beginning than it is to retrofit it to
+one that wasn't.
+.PP
+Nearly all regops that involve looking at the input string have
+two cases, one for UTF\-8, and one not. In fact, it's often more complex
+than that, as the pattern may be UTF\-8 as well.
+.PP
+Care must be taken when making changes to make sure that you handle
+UTF\-8 properly, both at compile time and at execution time, including
+when the string and pattern are mismatched.
+.SS "Base Structures"
+.IX Subsection "Base Structures"
+The \f(CW\*(C`regexp\*(C'\fR structure described in perlreapi is common to all
+regex engines. Two of its fields are intended for the private use
+of the regex engine that compiled the pattern. These are the
+\&\f(CW\*(C`intflags\*(C'\fR and pprivate members. The \f(CW\*(C`pprivate\*(C'\fR is a void pointer to
+an arbitrary structure whose use and management is the responsibility
+of the compiling engine. perl will never modify either of these
+values. In the case of the stock engine the structure pointed to by
+\&\f(CW\*(C`pprivate\*(C'\fR is called \f(CW\*(C`regexp_internal\*(C'\fR.
+.PP
+Its \f(CW\*(C`pprivate\*(C'\fR and \f(CW\*(C`intflags\*(C'\fR fields contain data
+specific to each engine.
+.PP
+There are two structures used to store a compiled regular expression.
+One, the \f(CW\*(C`regexp\*(C'\fR structure described in perlreapi is populated by
+the engine currently being used and some of its fields read by perl to
+implement things such as the stringification of \f(CW\*(C`qr//\*(C'\fR.
+.PP
+The other structure is pointed to by the \f(CW\*(C`regexp\*(C'\fR struct's
+\&\f(CW\*(C`pprivate\*(C'\fR and is in addition to \f(CW\*(C`intflags\*(C'\fR in the same struct
+considered to be the property of the regex engine which compiled the
+regular expression;
+.PP
+The regexp structure contains all the data that perl needs to be aware of
+to properly work with the regular expression. It includes data about
+optimisations that perl can use to determine if the regex engine should
+really be used, and various other control info that is needed to properly
+execute patterns in various contexts such as is the pattern anchored in
+some way, or what flags were used during the compile, or whether the
+program contains special constructs that perl needs to be aware of.
+.PP
+In addition it contains two fields that are intended for the private use
+of the regex engine that compiled the pattern. These are the \f(CW\*(C`intflags\*(C'\fR
+and pprivate members. The \f(CW\*(C`pprivate\*(C'\fR is a void pointer to an arbitrary
+structure whose use and management is the responsibility of the compiling
+engine. perl will never modify either of these values.
+.PP
+As mentioned earlier, in the case of the default engines, the \f(CW\*(C`pprivate\*(C'\fR
+will be a pointer to a regexp_internal structure which holds the compiled
+program and any additional data that is private to the regex engine
+implementation.
+.PP
+\fIPerl's \fR\f(CI\*(C`pprivate\*(C'\fR\fI structure\fR
+.IX Subsection "Perl's pprivate structure"
+.PP
+The following structure is used as the \f(CW\*(C`pprivate\*(C'\fR struct by perl's
+regex engine. Since it is specific to perl it is only of curiosity
+value to other engine implementations.
+.PP
+.Vb 8
+\&    typedef struct regexp_internal {
+\&        regnode *regstclass;
+\&        struct reg_data *data;
+\&        struct reg_code_blocks *code_blocks;
+\&        U32 proglen;
+\&        U32 name_list_idx;
+\&        regnode program[1];
+\&    } regexp_internal;
+.Ve
+.PP
+Description of the attributes is as follows:
+.ie n .IP """regstclass""" 5
+.el .IP \f(CWregstclass\fR 5
+.IX Item "regstclass"
+Special regop that is used by \f(CWre_intuit_start()\fR to check if a pattern
+can match at a certain position. For instance if the regex engine knows
+that the pattern must start with a 'Z' then it can scan the string until
+it finds one and then launch the regex engine from there. The routine
+that handles this is called \f(CWfind_by_class()\fR. Sometimes this field
+points at a regop embedded in the program, and sometimes it points at
+an independent synthetic regop that has been constructed by the optimiser.
+.ie n .IP """data""" 5
+.el .IP \f(CWdata\fR 5
+.IX Item "data"
+This field points at a \f(CW\*(C`reg_data\*(C'\fR structure, which is defined as follows
+.Sp
+.Vb 5
+\&    struct reg_data {
+\&        U32 count;
+\&        U8 *what;
+\&        void* data[1];
+\&    };
+.Ve
+.Sp
+This structure is used for handling data structures that the regex engine
+needs to handle specially during a clone or free operation on the compiled
+product. Each element in the data array has a corresponding element in the
+what array. During compilation regops that need special structures stored
+will add an element to each array using the \fBadd_data()\fR routine and then store
+the index in the regop.
+.Sp
+In modern perls the 0th element of this structure is reserved and is NEVER
+used to store anything of use. This is to allow things that need to index
+into this array to represent "no value".
+.ie n .IP """code_blocks""" 5
+.el .IP \f(CWcode_blocks\fR 5
+.IX Item "code_blocks"
+This optional structure is used to manage \f(CW\*(C`(?{})\*(C'\fR constructs in the
+pattern.  It is made up of the following structures.
+.Sp
+.Vb 7
+\&    /* record the position of a (?{...}) within a pattern */
+\&    struct reg_code_block {
+\&        STRLEN start;
+\&        STRLEN end;
+\&        OP     *block;
+\&        REGEXP *src_regex;
+\&    };
+\&
+\&    /* array of reg_code_block\*(Aqs plus header info */
+\&    struct reg_code_blocks {
+\&        int refcnt; /* we may be pointed to from a regex
+\&                       and from the savestack */
+\&        int  count; /* how many code blocks */
+\&        struct reg_code_block *cb; /* array of reg_code_block\*(Aqs */
+\&    };
+.Ve
+.ie n .IP """proglen""" 5
+.el .IP \f(CWproglen\fR 5
+.IX Item "proglen"
+Stores the length of the compiled program in units of regops.
+.ie n .IP """name_list_idx""" 5
+.el .IP \f(CWname_list_idx\fR 5
+.IX Item "name_list_idx"
+This is the index into the data array where an AV is stored that contains
+the names of any named capture buffers in the pattern, should there be
+any. This is only used in the debugging version of the regex engine and
+when RXp_PAREN_NAMES(prog) is true. It will be 0 if there is no such data.
+.ie n .IP """program""" 5
+.el .IP \f(CWprogram\fR 5
+.IX Item "program"
+Compiled program. Inlined into the structure so the entire struct can be
+treated as a single blob.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlreapi
+.PP
+perlre
+.PP
+perlunitut
+.SH AUTHOR
+.IX Header "AUTHOR"
+by Yves Orton, 2006.
+.PP
+With excerpts from Perl, and contributions and suggestions from
+Ronald J. Kimball, Dave Mitchell, Dominic Dunlop, Mark Jason Dominus,
+Stephen McCamant, and David Landgren.
+.PP
+Now maintained by Perl 5 Porters.
+.SH LICENCE
+.IX Header "LICENCE"
+Same terms as Perl.
+.SH REFERENCES
+.IX Header "REFERENCES"
+[1] <https://perl.plover.com/Rx/paper/>
+.PP
+[2] <https://www.unicode.org/>
diff --git a/upstream/mageia-cauldron/man1/perlrepository.1 b/upstream/mageia-cauldron/man1/perlrepository.1
new file mode 100644
index 00000000..5cdd3d36
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlrepository.1
@@ -0,0 +1,76 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREPOSITORY 1"
+.TH PERLREPOSITORY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlrepository \- Links to current information on the Perl source repository
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl's source code is stored in a Git repository.
+.PP
+See perlhack for an explanation of Perl development, including the
+Super Quick Patch Guide for making and
+submitting a small patch.
+.PP
+See perlgit for detailed information about Perl's Git repository.
+.PP
+(The above documents supersede the information that was formerly here in
+perlrepository.)
diff --git a/upstream/mageia-cauldron/man1/perlrequick.1 b/upstream/mageia-cauldron/man1/perlrequick.1
new file mode 100644
index 00000000..ca69e13b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlrequick.1
@@ -0,0 +1,651 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREQUICK 1"
+.TH PERLREQUICK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlrequick \- Perl regular expressions quick start
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This page covers the very basics of understanding, creating and
+using regular expressions ('regexes') in Perl.
+.SH "The Guide"
+.IX Header "The Guide"
+This page assumes you already know things, like what a "pattern" is, and
+the basic syntax of using them.  If you don't, see perlretut.
+.SS "Simple word matching"
+.IX Subsection "Simple word matching"
+The simplest regex is simply a word, or more generally, a string of
+characters.  A regex consisting of a word matches any string that
+contains that word:
+.PP
+.Vb 1
+\&    "Hello World" =~ /World/;  # matches
+.Ve
+.PP
+In this statement, \f(CW\*(C`World\*(C'\fR is a regex and the \f(CW\*(C`//\*(C'\fR enclosing
+\&\f(CW\*(C`/World/\*(C'\fR tells Perl to search a string for a match.  The operator
+\&\f(CW\*(C`=~\*(C'\fR associates the string with the regex match and produces a true
+value if the regex matched, or false if the regex did not match.  In
+our case, \f(CW\*(C`World\*(C'\fR matches the second word in \f(CW"Hello World"\fR, so the
+expression is true.  This idea has several variations.
+.PP
+Expressions like this are useful in conditionals:
+.PP
+.Vb 1
+\&    print "It matches\en" if "Hello World" =~ /World/;
+.Ve
+.PP
+The sense of the match can be reversed by using \f(CW\*(C`!~\*(C'\fR operator:
+.PP
+.Vb 1
+\&    print "It doesn\*(Aqt match\en" if "Hello World" !~ /World/;
+.Ve
+.PP
+The literal string in the regex can be replaced by a variable:
+.PP
+.Vb 2
+\&    $greeting = "World";
+\&    print "It matches\en" if "Hello World" =~ /$greeting/;
+.Ve
+.PP
+If you're matching against \f(CW$_\fR, the \f(CW\*(C`$_ =~\*(C'\fR part can be omitted:
+.PP
+.Vb 2
+\&    $_ = "Hello World";
+\&    print "It matches\en" if /World/;
+.Ve
+.PP
+Finally, the \f(CW\*(C`//\*(C'\fR default delimiters for a match can be changed to
+arbitrary delimiters by putting an \f(CW\*(Aqm\*(Aq\fR out front:
+.PP
+.Vb 4
+\&    "Hello World" =~ m!World!;   # matches, delimited by \*(Aq!\*(Aq
+\&    "Hello World" =~ m{World};   # matches, note the matching \*(Aq{}\*(Aq
+\&    "/usr/bin/perl" =~ m"/perl"; # matches after \*(Aq/usr/bin\*(Aq,
+\&                                 # \*(Aq/\*(Aq becomes an ordinary char
+.Ve
+.PP
+Regexes must match a part of the string \fIexactly\fR in order for the
+statement to be true:
+.PP
+.Vb 3
+\&    "Hello World" =~ /world/;  # doesn\*(Aqt match, case sensitive
+\&    "Hello World" =~ /o W/;    # matches, \*(Aq \*(Aq is an ordinary char
+\&    "Hello World" =~ /World /; # doesn\*(Aqt match, no \*(Aq \*(Aq at end
+.Ve
+.PP
+Perl will always match at the earliest possible point in the string:
+.PP
+.Vb 2
+\&    "Hello World" =~ /o/;       # matches \*(Aqo\*(Aq in \*(AqHello\*(Aq
+\&    "That hat is red" =~ /hat/; # matches \*(Aqhat\*(Aq in \*(AqThat\*(Aq
+.Ve
+.PP
+Not all characters can be used 'as is' in a match.  Some characters,
+called \fBmetacharacters\fR, are considered special, and reserved for use
+in regex notation.  The metacharacters are
+.PP
+.Vb 1
+\&    {}[]()^$.|*+?\e
+.Ve
+.PP
+A metacharacter can be matched literally by putting a backslash before
+it:
+.PP
+.Vb 4
+\&    "2+2=4" =~ /2+2/;    # doesn\*(Aqt match, + is a metacharacter
+\&    "2+2=4" =~ /2\e+2/;   # matches, \e+ is treated like an ordinary +
+\&    \*(AqC:\eWIN32\*(Aq =~ /C:\e\eWIN/;                       # matches
+\&    "/usr/bin/perl" =~ /\e/usr\e/bin\e/perl/;  # matches
+.Ve
+.PP
+In the last regex, the forward slash \f(CW\*(Aq/\*(Aq\fR is also backslashed,
+because it is used to delimit the regex.
+.PP
+Most of the metacharacters aren't always special, and other characters
+(such as the ones delimiting the pattern) become special under various
+circumstances.  This can be confusing and lead to unexpected results.
+\&\f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR can notify you of potential
+pitfalls.
+.PP
+Non-printable ASCII characters are represented by \fBescape sequences\fR.
+Common examples are \f(CW\*(C`\et\*(C'\fR for a tab, \f(CW\*(C`\en\*(C'\fR for a newline, and \f(CW\*(C`\er\*(C'\fR
+for a carriage return.  Arbitrary bytes are represented by octal
+escape sequences, e.g., \f(CW\*(C`\e033\*(C'\fR, or hexadecimal escape sequences,
+e.g., \f(CW\*(C`\ex1B\*(C'\fR:
+.PP
+.Vb 3
+\&    "1000\et2000" =~ m(0\et2)  # matches
+\&    "cat" =~ /\e143\ex61\ex74/  # matches in ASCII, but
+\&                             # a weird way to spell cat
+.Ve
+.PP
+Regexes are treated mostly as double-quoted strings, so variable
+substitution works:
+.PP
+.Vb 3
+\&    $foo = \*(Aqhouse\*(Aq;
+\&    \*(Aqcathouse\*(Aq =~ /cat$foo/;   # matches
+\&    \*(Aqhousecat\*(Aq =~ /${foo}cat/; # matches
+.Ve
+.PP
+With all of the regexes above, if the regex matched anywhere in the
+string, it was considered a match.  To specify \fIwhere\fR it should
+match, we would use the \fBanchor\fR metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR.  The
+anchor \f(CW\*(C`^\*(C'\fR means match at the beginning of the string and the anchor
+\&\f(CW\*(C`$\*(C'\fR means match at the end of the string, or before a newline at the
+end of the string.  Some examples:
+.PP
+.Vb 5
+\&    "housekeeper" =~ /keeper/;         # matches
+\&    "housekeeper" =~ /^keeper/;        # doesn\*(Aqt match
+\&    "housekeeper" =~ /keeper$/;        # matches
+\&    "housekeeper\en" =~ /keeper$/;      # matches
+\&    "housekeeper" =~ /^housekeeper$/;  # matches
+.Ve
+.SS "Using character classes"
+.IX Subsection "Using character classes"
+A \fBcharacter class\fR allows a set of possible characters, rather than
+just a single character, to match at a particular point in a regex.
+There are a number of different types of character classes, but usually
+when people use this term, they are referring to the type described in
+this section, which are technically called "Bracketed character
+classes", because they are denoted by brackets \f(CW\*(C`[...]\*(C'\fR, with the set of
+characters to be possibly matched inside.  But we'll drop the "bracketed"
+below to correspond with common usage.  Here are some examples of
+(bracketed) character classes:
+.PP
+.Vb 3
+\&    /cat/;            # matches \*(Aqcat\*(Aq
+\&    /[bcr]at/;        # matches \*(Aqbat\*(Aq, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+\&    "abc" =~ /[cab]/; # matches \*(Aqa\*(Aq
+.Ve
+.PP
+In the last statement, even though \f(CW\*(Aqc\*(Aq\fR is the first character in
+the class, the earliest point at which the regex can match is \f(CW\*(Aqa\*(Aq\fR.
+.PP
+.Vb 3
+\&    /[yY][eE][sS]/; # match \*(Aqyes\*(Aq in a case\-insensitive way
+\&                    # \*(Aqyes\*(Aq, \*(AqYes\*(Aq, \*(AqYES\*(Aq, etc.
+\&    /yes/i;         # also match \*(Aqyes\*(Aq in a case\-insensitive way
+.Ve
+.PP
+The last example shows a match with an \f(CW\*(Aqi\*(Aq\fR \fBmodifier\fR, which makes
+the match case-insensitive.
+.PP
+Character classes also have ordinary and special characters, but the
+sets of ordinary and special characters inside a character class are
+different than those outside a character class.  The special
+characters for a character class are \f(CW\*(C`\-]\e^$\*(C'\fR and are matched using an
+escape:
+.PP
+.Vb 5
+\&   /[\e]c]def/; # matches \*(Aq]def\*(Aq or \*(Aqcdef\*(Aq
+\&   $x = \*(Aqbcr\*(Aq;
+\&   /[$x]at/;   # matches \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+\&   /[\e$x]at/;  # matches \*(Aq$at\*(Aq or \*(Aqxat\*(Aq
+\&   /[\e\e$x]at/; # matches \*(Aq\eat\*(Aq, \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+.Ve
+.PP
+The special character \f(CW\*(Aq\-\*(Aq\fR acts as a range operator within character
+classes, so that the unwieldy \f(CW\*(C`[0123456789]\*(C'\fR and \f(CW\*(C`[abc...xyz]\*(C'\fR
+become the svelte \f(CW\*(C`[0\-9]\*(C'\fR and \f(CW\*(C`[a\-z]\*(C'\fR:
+.PP
+.Vb 2
+\&    /item[0\-9]/;  # matches \*(Aqitem0\*(Aq or ... or \*(Aqitem9\*(Aq
+\&    /[0\-9a\-fA\-F]/;  # matches a hexadecimal digit
+.Ve
+.PP
+If \f(CW\*(Aq\-\*(Aq\fR is the first or last character in a character class, it is
+treated as an ordinary character.
+.PP
+The special character \f(CW\*(C`^\*(C'\fR in the first position of a character class
+denotes a \fBnegated character class\fR, which matches any character but
+those in the brackets.  Both \f(CW\*(C`[...]\*(C'\fR and \f(CW\*(C`[^...]\*(C'\fR must match a
+character, or the match fails.  Then
+.PP
+.Vb 4
+\&    /[^a]at/;  # doesn\*(Aqt match \*(Aqaat\*(Aq or \*(Aqat\*(Aq, but matches
+\&               # all other \*(Aqbat\*(Aq, \*(Aqcat, \*(Aq0at\*(Aq, \*(Aq%at\*(Aq, etc.
+\&    /[^0\-9]/;  # matches a non\-numeric character
+\&    /[a^]at/;  # matches \*(Aqaat\*(Aq or \*(Aq^at\*(Aq; here \*(Aq^\*(Aq is ordinary
+.Ve
+.PP
+Perl has several abbreviations for common character classes. (These
+definitions are those that Perl uses in ASCII-safe mode with the \f(CW\*(C`/a\*(C'\fR modifier.
+Otherwise they could match many more non-ASCII Unicode characters as
+well.  See "Backslash sequences" in perlrecharclass for details.)
+.IP \(bu 4
+\&\ed is a digit and represents
+.Sp
+.Vb 1
+\&    [0\-9]
+.Ve
+.IP \(bu 4
+\&\es is a whitespace character and represents
+.Sp
+.Vb 1
+\&    [\e \et\er\en\ef]
+.Ve
+.IP \(bu 4
+\&\ew is a word character (alphanumeric or _) and represents
+.Sp
+.Vb 1
+\&    [0\-9a\-zA\-Z_]
+.Ve
+.IP \(bu 4
+\&\eD is a negated \ed; it represents any character but a digit
+.Sp
+.Vb 1
+\&    [^0\-9]
+.Ve
+.IP \(bu 4
+\&\eS is a negated \es; it represents any non-whitespace character
+.Sp
+.Vb 1
+\&    [^\es]
+.Ve
+.IP \(bu 4
+\&\eW is a negated \ew; it represents any non-word character
+.Sp
+.Vb 1
+\&    [^\ew]
+.Ve
+.IP \(bu 4
+The period '.' matches any character but "\en"
+.PP
+The \f(CW\*(C`\ed\es\ew\eD\eS\eW\*(C'\fR abbreviations can be used both inside and outside
+of character classes.  Here are some in use:
+.PP
+.Vb 7
+\&    /\ed\ed:\ed\ed:\ed\ed/; # matches a hh:mm:ss time format
+\&    /[\ed\es]/;         # matches any digit or whitespace character
+\&    /\ew\eW\ew/;         # matches a word char, followed by a
+\&                      # non\-word char, followed by a word char
+\&    /..rt/;           # matches any two chars, followed by \*(Aqrt\*(Aq
+\&    /end\e./;          # matches \*(Aqend.\*(Aq
+\&    /end[.]/;         # same thing, matches \*(Aqend.\*(Aq
+.Ve
+.PP
+The \fBword\ anchor\fR\  \f(CW\*(C`\eb\*(C'\fR matches a boundary between a word
+character and a non-word character \f(CW\*(C`\ew\eW\*(C'\fR or \f(CW\*(C`\eW\ew\*(C'\fR:
+.PP
+.Vb 4
+\&    $x = "Housecat catenates house and cat";
+\&    $x =~ /\ebcat/;  # matches cat in \*(Aqcatenates\*(Aq
+\&    $x =~ /cat\eb/;  # matches cat in \*(Aqhousecat\*(Aq
+\&    $x =~ /\ebcat\eb/;  # matches \*(Aqcat\*(Aq at end of string
+.Ve
+.PP
+In the last example, the end of the string is considered a word
+boundary.
+.PP
+For natural language processing (so that, for example, apostrophes are
+included in words), use instead \f(CW\*(C`\eb{wb}\*(C'\fR
+.PP
+.Vb 1
+\&    "don\*(Aqt" =~ / .+? \eb{wb} /x;  # matches the whole string
+.Ve
+.SS "Matching this or that"
+.IX Subsection "Matching this or that"
+We can match different character strings with the \fBalternation\fR
+metacharacter \f(CW\*(Aq|\*(Aq\fR.  To match \f(CW\*(C`dog\*(C'\fR or \f(CW\*(C`cat\*(C'\fR, we form the regex
+\&\f(CW\*(C`dog|cat\*(C'\fR.  As before, Perl will try to match the regex at the
+earliest possible point in the string.  At each character position,
+Perl will first try to match the first alternative, \f(CW\*(C`dog\*(C'\fR.  If
+\&\f(CW\*(C`dog\*(C'\fR doesn't match, Perl will then try the next alternative, \f(CW\*(C`cat\*(C'\fR.
+If \f(CW\*(C`cat\*(C'\fR doesn't match either, then the match fails and Perl moves to
+the next position in the string.  Some examples:
+.PP
+.Vb 2
+\&    "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
+\&    "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"
+.Ve
+.PP
+Even though \f(CW\*(C`dog\*(C'\fR is the first alternative in the second regex,
+\&\f(CW\*(C`cat\*(C'\fR is able to match earlier in the string.
+.PP
+.Vb 2
+\&    "cats"          =~ /c|ca|cat|cats/; # matches "c"
+\&    "cats"          =~ /cats|cat|ca|c/; # matches "cats"
+.Ve
+.PP
+At a given character position, the first alternative that allows the
+regex match to succeed will be the one that matches. Here, all the
+alternatives match at the first string position, so the first matches.
+.SS "Grouping things and hierarchical matching"
+.IX Subsection "Grouping things and hierarchical matching"
+The \fBgrouping\fR metacharacters \f(CW\*(C`()\*(C'\fR allow a part of a regex to be
+treated as a single unit.  Parts of a regex are grouped by enclosing
+them in parentheses.  The regex \f(CWhouse(cat|keeper)\fR means match
+\&\f(CW\*(C`house\*(C'\fR followed by either \f(CW\*(C`cat\*(C'\fR or \f(CW\*(C`keeper\*(C'\fR.  Some more examples
+are
+.PP
+.Vb 2
+\&    /(a|b)b/;    # matches \*(Aqab\*(Aq or \*(Aqbb\*(Aq
+\&    /(^a|b)c/;   # matches \*(Aqac\*(Aq at start of string or \*(Aqbc\*(Aq anywhere
+\&
+\&    /house(cat|)/;  # matches either \*(Aqhousecat\*(Aq or \*(Aqhouse\*(Aq
+\&    /house(cat(s|)|)/;  # matches either \*(Aqhousecats\*(Aq or \*(Aqhousecat\*(Aq or
+\&                        # \*(Aqhouse\*(Aq.  Note groups can be nested.
+\&
+\&    "20" =~ /(19|20|)\ed\ed/;  # matches the null alternative \*(Aq()\ed\ed\*(Aq,
+\&                             # because \*(Aq20\ed\ed\*(Aq can\*(Aqt match
+.Ve
+.SS "Extracting matches"
+.IX Subsection "Extracting matches"
+The grouping metacharacters \f(CW\*(C`()\*(C'\fR also allow the extraction of the
+parts of a string that matched.  For each grouping, the part that
+matched inside goes into the special variables \f(CW$1\fR, \f(CW$2\fR, etc.
+They can be used just as ordinary variables:
+.PP
+.Vb 5
+\&    # extract hours, minutes, seconds
+\&    $time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/;  # match hh:mm:ss format
+\&    $hours = $1;
+\&    $minutes = $2;
+\&    $seconds = $3;
+.Ve
+.PP
+In list context, a match \f(CW\*(C`/regex/\*(C'\fR with groupings will return the
+list of matched values \f(CW\*(C`($1,$2,...)\*(C'\fR.  So we could rewrite it as
+.PP
+.Vb 1
+\&    ($hours, $minutes, $second) = ($time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/);
+.Ve
+.PP
+If the groupings in a regex are nested, \f(CW$1\fR gets the group with the
+leftmost opening parenthesis, \f(CW$2\fR the next opening parenthesis,
+etc.  For example, here is a complex regex and the matching variables
+indicated below it:
+.PP
+.Vb 2
+\&    /(ab(cd|ef)((gi)|j))/;
+\&     1  2      34
+.Ve
+.PP
+Associated with the matching variables \f(CW$1\fR, \f(CW$2\fR, ... are
+the \fBbackreferences\fR \f(CW\*(C`\eg1\*(C'\fR, \f(CW\*(C`\eg2\*(C'\fR, ...  Backreferences are
+matching variables that can be used \fIinside\fR a regex:
+.PP
+.Vb 1
+\&    /(\ew\ew\ew)\es\eg1/; # find sequences like \*(Aqthe the\*(Aq in string
+.Ve
+.PP
+\&\f(CW$1\fR, \f(CW$2\fR, ... should only be used outside of a regex, and \f(CW\*(C`\eg1\*(C'\fR,
+\&\f(CW\*(C`\eg2\*(C'\fR, ... only inside a regex.
+.SS "Matching repetitions"
+.IX Subsection "Matching repetitions"
+The \fBquantifier\fR metacharacters \f(CW\*(C`?\*(C'\fR, \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`+\*(C'\fR, and \f(CW\*(C`{}\*(C'\fR allow us
+to determine the number of repeats of a portion of a regex we
+consider to be a match.  Quantifiers are put immediately after the
+character, character class, or grouping that we want to specify.  They
+have the following meanings:
+.IP \(bu 4
+\&\f(CW\*(C`a?\*(C'\fR = match 'a' 1 or 0 times
+.IP \(bu 4
+\&\f(CW\*(C`a*\*(C'\fR = match 'a' 0 or more times, i.e., any number of times
+.IP \(bu 4
+\&\f(CW\*(C`a+\*(C'\fR = match 'a' 1 or more times, i.e., at least once
+.IP \(bu 4
+\&\f(CW\*(C`a{n,m}\*(C'\fR = match at least \f(CW\*(C`n\*(C'\fR times, but not more than \f(CW\*(C`m\*(C'\fR
+times.
+.IP \(bu 4
+\&\f(CW\*(C`a{n,}\*(C'\fR = match at least \f(CW\*(C`n\*(C'\fR or more times
+.IP \(bu 4
+\&\f(CW\*(C`a{,n}\*(C'\fR = match \f(CW\*(C`n\*(C'\fR times or fewer
+.IP \(bu 4
+\&\f(CW\*(C`a{n}\*(C'\fR = match exactly \f(CW\*(C`n\*(C'\fR times
+.PP
+Here are some examples:
+.PP
+.Vb 6
+\&    /[a\-z]+\es+\ed*/;  # match a lowercase word, at least some space, and
+\&                     # any number of digits
+\&    /(\ew+)\es+\eg1/;    # match doubled words of arbitrary length
+\&    $year =~ /^\ed{2,4}$/;  # make sure year is at least 2 but not more
+\&                           # than 4 digits
+\&    $year =~ /^\ed{ 4 }$|^\ed{2}$/; # better match; throw out 3 digit dates
+.Ve
+.PP
+These quantifiers will try to match as much of the string as possible,
+while still allowing the regex to match.  So we have
+.PP
+.Vb 5
+\&    $x = \*(Aqthe cat in the hat\*(Aq;
+\&    $x =~ /^(.*)(at)(.*)$/; # matches,
+\&                            # $1 = \*(Aqthe cat in the h\*(Aq
+\&                            # $2 = \*(Aqat\*(Aq
+\&                            # $3 = \*(Aq\*(Aq   (0 matches)
+.Ve
+.PP
+The first quantifier \f(CW\*(C`.*\*(C'\fR grabs as much of the string as possible
+while still having the regex match. The second quantifier \f(CW\*(C`.*\*(C'\fR has
+no string left to it, so it matches 0 times.
+.SS "More matching"
+.IX Subsection "More matching"
+There are a few more things you might want to know about matching
+operators.
+The global modifier \f(CW\*(C`/g\*(C'\fR allows the matching operator to match
+within a string as many times as possible.  In scalar context,
+successive matches against a string will have \f(CW\*(C`/g\*(C'\fR jump from match
+to match, keeping track of position in the string as it goes along.
+You can get or set the position with the \f(CWpos()\fR function.
+For example,
+.PP
+.Vb 4
+\&    $x = "cat dog house"; # 3 words
+\&    while ($x =~ /(\ew+)/g) {
+\&        print "Word is $1, ends at position ", pos $x, "\en";
+\&    }
+.Ve
+.PP
+prints
+.PP
+.Vb 3
+\&    Word is cat, ends at position 3
+\&    Word is dog, ends at position 7
+\&    Word is house, ends at position 13
+.Ve
+.PP
+A failed match or changing the target string resets the position.  If
+you don't want the position reset after failure to match, add the
+\&\f(CW\*(C`/c\*(C'\fR, as in \f(CW\*(C`/regex/gc\*(C'\fR.
+.PP
+In list context, \f(CW\*(C`/g\*(C'\fR returns a list of matched groupings, or if
+there are no groupings, a list of matches to the whole regex.  So
+.PP
+.Vb 4
+\&    @words = ($x =~ /(\ew+)/g);  # matches,
+\&                                # $word[0] = \*(Aqcat\*(Aq
+\&                                # $word[1] = \*(Aqdog\*(Aq
+\&                                # $word[2] = \*(Aqhouse\*(Aq
+.Ve
+.SS "Search and replace"
+.IX Subsection "Search and replace"
+Search and replace is performed using \f(CW\*(C`s/regex/replacement/modifiers\*(C'\fR.
+The \f(CW\*(C`replacement\*(C'\fR is a Perl double-quoted string that replaces in the
+string whatever is matched with the \f(CW\*(C`regex\*(C'\fR.  The operator \f(CW\*(C`=~\*(C'\fR is
+also used here to associate a string with \f(CW\*(C`s///\*(C'\fR.  If matching
+against \f(CW$_\fR, the \f(CW\*(C`$_\ =~\*(C'\fR can be dropped.  If there is a match,
+\&\f(CW\*(C`s///\*(C'\fR returns the number of substitutions made; otherwise it returns
+false.  Here are a few examples:
+.PP
+.Vb 5
+\&    $x = "Time to feed the cat!";
+\&    $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
+\&    $y = "\*(Aqquoted words\*(Aq";
+\&    $y =~ s/^\*(Aq(.*)\*(Aq$/$1/;  # strip single quotes,
+\&                           # $y contains "quoted words"
+.Ve
+.PP
+With the \f(CW\*(C`s///\*(C'\fR operator, the matched variables \f(CW$1\fR, \f(CW$2\fR, etc.
+are immediately available for use in the replacement expression. With
+the global modifier, \f(CW\*(C`s///g\*(C'\fR will search and replace all occurrences
+of the regex in the string:
+.PP
+.Vb 4
+\&    $x = "I batted 4 for 4";
+\&    $x =~ s/4/four/;   # $x contains "I batted four for 4"
+\&    $x = "I batted 4 for 4";
+\&    $x =~ s/4/four/g;  # $x contains "I batted four for four"
+.Ve
+.PP
+The non-destructive modifier \f(CW\*(C`s///r\*(C'\fR causes the result of the substitution
+to be returned instead of modifying \f(CW$_\fR (or whatever variable the
+substitute was bound to with \f(CW\*(C`=~\*(C'\fR):
+.PP
+.Vb 3
+\&    $x = "I like dogs.";
+\&    $y = $x =~ s/dogs/cats/r;
+\&    print "$x $y\en"; # prints "I like dogs. I like cats."
+\&
+\&    $x = "Cats are great.";
+\&    print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~
+\&        s/Frogs/Hedgehogs/r, "\en";
+\&    # prints "Hedgehogs are great."
+\&
+\&    @foo = map { s/[a\-z]/X/r } qw(a b c 1 2 3);
+\&    # @foo is now qw(X X X 1 2 3)
+.Ve
+.PP
+The evaluation modifier \f(CW\*(C`s///e\*(C'\fR wraps an \f(CW\*(C`eval{...}\*(C'\fR around the
+replacement string and the evaluated result is substituted for the
+matched substring.  Some examples:
+.PP
+.Vb 3
+\&    # reverse all the words in a string
+\&    $x = "the cat in the hat";
+\&    $x =~ s/(\ew+)/reverse $1/ge;   # $x contains "eht tac ni eht tah"
+\&
+\&    # convert percentage to decimal
+\&    $x = "A 39% hit rate";
+\&    $x =~ s!(\ed+)%!$1/100!e;       # $x contains "A 0.39 hit rate"
+.Ve
+.PP
+The last example shows that \f(CW\*(C`s///\*(C'\fR can use other delimiters, such as
+\&\f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`s{}{}\*(C'\fR, and even \f(CW\*(C`s{}//\*(C'\fR.  If single quotes are used
+\&\f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR, then the regex and replacement are treated as single-quoted
+strings.
+.SS "The split operator"
+.IX Subsection "The split operator"
+\&\f(CW\*(C`split /regex/, string\*(C'\fR splits \f(CW\*(C`string\*(C'\fR into a list of substrings
+and returns that list.  The regex determines the character sequence
+that \f(CW\*(C`string\*(C'\fR is split with respect to.  For example, to split a
+string into words, use
+.PP
+.Vb 4
+\&    $x = "Calvin and Hobbes";
+\&    @word = split /\es+/, $x;  # $word[0] = \*(AqCalvin\*(Aq
+\&                              # $word[1] = \*(Aqand\*(Aq
+\&                              # $word[2] = \*(AqHobbes\*(Aq
+.Ve
+.PP
+To extract a comma-delimited list of numbers, use
+.PP
+.Vb 4
+\&    $x = "1.618,2.718,   3.142";
+\&    @const = split /,\es*/, $x;  # $const[0] = \*(Aq1.618\*(Aq
+\&                                # $const[1] = \*(Aq2.718\*(Aq
+\&                                # $const[2] = \*(Aq3.142\*(Aq
+.Ve
+.PP
+If the empty regex \f(CW\*(C`//\*(C'\fR is used, the string is split into individual
+characters.  If the regex has groupings, then the list produced contains
+the matched substrings from the groupings as well:
+.PP
+.Vb 6
+\&    $x = "/usr/bin";
+\&    @parts = split m!(/)!, $x;  # $parts[0] = \*(Aq\*(Aq
+\&                                # $parts[1] = \*(Aq/\*(Aq
+\&                                # $parts[2] = \*(Aqusr\*(Aq
+\&                                # $parts[3] = \*(Aq/\*(Aq
+\&                                # $parts[4] = \*(Aqbin\*(Aq
+.Ve
+.PP
+Since the first character of \f(CW$x\fR matched the regex, \f(CW\*(C`split\*(C'\fR prepended
+an empty initial element to the list.
+.ie n .SS """use re \*(Aqstrict\*(Aq"""
+.el .SS "\f(CWuse re \*(Aqstrict\*(Aq\fP"
+.IX Subsection "use re strict"
+New in v5.22, this applies stricter rules than otherwise when compiling
+regular expression patterns.  It can find things that, while legal, may
+not be what you intended.
+.PP
+See 'strict' in re.
+.SH BUGS
+.IX Header "BUGS"
+None.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+This is just a quick start guide.  For a more in-depth tutorial on
+regexes, see perlretut and for the reference page, see perlre.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 2000 Mark Kvale
+All rights reserved.
+.PP
+This document may be distributed under the same terms as Perl itself.
+.SS Acknowledgments
+.IX Subsection "Acknowledgments"
+The author would like to thank Mark-Jason Dominus, Tom Christiansen,
+Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful
+comments.
diff --git a/upstream/mageia-cauldron/man1/perlreref.1 b/upstream/mageia-cauldron/man1/perlreref.1
new file mode 100644
index 00000000..b96f213e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlreref.1
@@ -0,0 +1,476 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLREREF 1"
+.TH PERLREREF 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlreref \- Perl Regular Expressions Reference
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a quick reference to Perl's regular expressions.
+For full information see perlre and perlop, as well
+as the "SEE ALSO" section in this document.
+.SS OPERATORS
+.IX Subsection "OPERATORS"
+\&\f(CW\*(C`=~\*(C'\fR determines to which variable the regex is applied.
+In its absence, \f(CW$_\fR is used.
+.PP
+.Vb 1
+\&    $var =~ /foo/;
+.Ve
+.PP
+\&\f(CW\*(C`!~\*(C'\fR determines to which variable the regex is applied,
+and negates the result of the match; it returns
+false if the match succeeds, and true if it fails.
+.PP
+.Vb 1
+\&    $var !~ /foo/;
+.Ve
+.PP
+\&\f(CW\*(C`m/pattern/msixpogcdualn\*(C'\fR searches a string for a pattern match,
+applying the given options.
+.PP
+.Vb 10
+\&    m  Multiline mode \- ^ and $ match internal lines
+\&    s  match as a Single line \- . matches \en
+\&    i  case\-Insensitive
+\&    x  eXtended legibility \- free whitespace and comments
+\&    p  Preserve a copy of the matched string \-
+\&       ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
+\&    o  compile pattern Once
+\&    g  Global \- all occurrences
+\&    c  don\*(Aqt reset pos on failed matches when using /g
+\&    a  restrict \ed, \es, \ew and [:posix:] to match ASCII only
+\&    aa (two a\*(Aqs) also /i matches exclude ASCII/non\-ASCII
+\&    l  match according to current locale
+\&    u  match according to Unicode rules
+\&    d  match according to native rules unless something indicates
+\&       Unicode
+\&    n  Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
+.Ve
+.PP
+If 'pattern' is an empty string, the last \fIsuccessfully\fR matched
+regex is used. Delimiters other than '/' may be used for both this
+operator and the following ones. The leading \f(CW\*(C`m\*(C'\fR can be omitted
+if the delimiter is '/'.
+.PP
+\&\f(CW\*(C`qr/pattern/msixpodualn\*(C'\fR lets you store a regex in a variable,
+or pass one around. Modifiers as for \f(CW\*(C`m//\*(C'\fR, and are stored
+within the regex.
+.PP
+\&\f(CW\*(C`s/pattern/replacement/msixpogcedual\*(C'\fR substitutes matches of
+\&'pattern' with 'replacement'. Modifiers as for \f(CW\*(C`m//\*(C'\fR,
+with two additions:
+.PP
+.Vb 2
+\&    e  Evaluate \*(Aqreplacement\*(Aq as an expression
+\&    r  Return substitution and leave the original string untouched.
+.Ve
+.PP
+\&'e' may be specified multiple times. 'replacement' is interpreted
+as a double quoted string unless a single-quote (\f(CW\*(C`\*(Aq\*(C'\fR) is the delimiter.
+.PP
+\&\f(CW\*(C`m?pattern?\*(C'\fR is like \f(CW\*(C`m/pattern/\*(C'\fR but matches only once. No alternate
+delimiters can be used.  Must be reset with \fBreset()\fR.
+.SS SYNTAX
+.IX Subsection "SYNTAX"
+.Vb 10
+\& \e       Escapes the character immediately following it
+\& .       Matches any single character except a newline (unless /s is
+\&           used)
+\& ^       Matches at the beginning of the string (or line, if /m is used)
+\& $       Matches at the end of the string (or line, if /m is used)
+\& *       Matches the preceding element 0 or more times
+\& +       Matches the preceding element 1 or more times
+\& ?       Matches the preceding element 0 or 1 times
+\& {...}   Specifies a range of occurrences for the element preceding it
+\& [...]   Matches any one of the characters contained within the brackets
+\& (...)   Groups subexpressions for capturing to $1, $2...
+\& (?:...) Groups subexpressions without capturing (cluster)
+\& |       Matches either the subexpression preceding or following it
+\& \eg1 or \eg{1}, \eg2 ...    Matches the text from the Nth group
+\& \e1, \e2, \e3 ...           Matches the text from the Nth group
+\& \eg\-1 or \eg{\-1}, \eg\-2 ... Matches the text from the Nth previous group
+\& \eg{name}     Named backreference
+\& \ek<name>     Named backreference
+\& \ek\*(Aqname\*(Aq     Named backreference
+\& (?P=name)    Named backreference (python syntax)
+.Ve
+.SS "ESCAPE SEQUENCES"
+.IX Subsection "ESCAPE SEQUENCES"
+These work as in normal strings.
+.PP
+.Vb 10
+\&   \ea       Alarm (beep)
+\&   \ee       Escape
+\&   \ef       Formfeed
+\&   \en       Newline
+\&   \er       Carriage return
+\&   \et       Tab
+\&   \e037     Char whose ordinal is the 3 octal digits, max \e777
+\&   \eo{2307} Char whose ordinal is the octal number, unrestricted
+\&   \ex7f     Char whose ordinal is the 2 hex digits, max \exFF
+\&   \ex{263a} Char whose ordinal is the hex number, unrestricted
+\&   \ecx      Control\-x
+\&   \eN{name} A named Unicode character or character sequence
+\&   \eN{U+263D} A Unicode character by hex ordinal
+\&
+\&   \el  Lowercase next character
+\&   \eu  Titlecase next character
+\&   \eL  Lowercase until \eE
+\&   \eU  Uppercase until \eE
+\&   \eF  Foldcase until \eE
+\&   \eQ  Disable pattern metacharacters until \eE
+\&   \eE  End modification
+.Ve
+.PP
+For Titlecase, see "Titlecase".
+.PP
+This one works differently from normal strings:
+.PP
+.Vb 1
+\&   \eb  An assertion, not backspace, except in a character class
+.Ve
+.SS "CHARACTER CLASSES"
+.IX Subsection "CHARACTER CLASSES"
+.Vb 4
+\&   [amy]    Match \*(Aqa\*(Aq, \*(Aqm\*(Aq or \*(Aqy\*(Aq
+\&   [f\-j]    Dash specifies "range"
+\&   [f\-j\-]   Dash escaped or at start or end means \*(Aqdash\*(Aq
+\&   [^f\-j]   Caret indicates "match any character _except_ these"
+.Ve
+.PP
+The following sequences (except \f(CW\*(C`\eN\*(C'\fR) work within or without a character class.
+The first six are locale aware, all are Unicode aware. See perllocale
+and perlunicode for details.
+.PP
+.Vb 10
+\&   \ed      A digit
+\&   \eD      A nondigit
+\&   \ew      A word character
+\&   \eW      A non\-word character
+\&   \es      A whitespace character
+\&   \eS      A non\-whitespace character
+\&   \eh      A horizontal whitespace
+\&   \eH      A non horizontal whitespace
+\&   \eN      A non newline (when not followed by \*(Aq{NAME}\*(Aq;;
+\&           not valid in a character class; equivalent to [^\en]; it\*(Aqs
+\&           like \*(Aq.\*(Aq without /s modifier)
+\&   \ev      A vertical whitespace
+\&   \eV      A non vertical whitespace
+\&   \eR      A generic newline           (?>\ev|\ex0D\ex0A)
+\&
+\&   \epP     Match P\-named (Unicode) property
+\&   \ep{...} Match Unicode property with name longer than 1 character
+\&   \ePP     Match non\-P
+\&   \eP{...} Match lack of Unicode property with name longer than 1 char
+\&   \eX      Match Unicode extended grapheme cluster
+.Ve
+.PP
+POSIX character classes and their Unicode and Perl equivalents:
+.PP
+.Vb 3
+\&            ASCII\-         Full\-
+\&   POSIX    range          range    backslash
+\& [[:...:]]  \ep{...}        \ep{...}   sequence    Description
+\&
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& alnum   PosixAlnum       XPosixAlnum            \*(Aqalpha\*(Aq plus \*(Aqdigit\*(Aq
+\& alpha   PosixAlpha       XPosixAlpha            Alphabetic characters
+\& ascii   ASCII                                   Any ASCII character
+\& blank   PosixBlank       XPosixBlank   \eh       Horizontal whitespace;
+\&                                                   full\-range also
+\&                                                   written as
+\&                                                   \ep{HorizSpace} (GNU
+\&                                                   extension)
+\& cntrl   PosixCntrl       XPosixCntrl            Control characters
+\& digit   PosixDigit       XPosixDigit   \ed       Decimal digits
+\& graph   PosixGraph       XPosixGraph            \*(Aqalnum\*(Aq plus \*(Aqpunct\*(Aq
+\& lower   PosixLower       XPosixLower            Lowercase characters
+\& print   PosixPrint       XPosixPrint            \*(Aqgraph\*(Aq plus \*(Aqspace\*(Aq,
+\&                                                   but not any Controls
+\& punct   PosixPunct       XPosixPunct            Punctuation and Symbols
+\&                                                   in ASCII\-range; just
+\&                                                   punct outside it
+\& space   PosixSpace       XPosixSpace   \es       Whitespace
+\& upper   PosixUpper       XPosixUpper            Uppercase characters
+\& word    PosixWord        XPosixWord    \ew       \*(Aqalnum\*(Aq + Unicode marks
+\&                                                    + connectors, like
+\&                                                    \*(Aq_\*(Aq (Perl extension)
+\& xdigit  ASCII_Hex_Digit  XPosixDigit            Hexadecimal digit,
+\&                                                    ASCII\-range is
+\&                                                    [0\-9A\-Fa\-f]
+.Ve
+.PP
+Also, various synonyms like \f(CW\*(C`\ep{Alpha}\*(C'\fR for \f(CW\*(C`\ep{XPosixAlpha}\*(C'\fR; all listed
+in "Properties accessible through \ep{} and \eP{}" in perluniprops
+.PP
+Within a character class:
+.PP
+.Vb 3
+\&    POSIX      traditional   Unicode
+\&  [:digit:]       \ed        \ep{Digit}
+\&  [:^digit:]      \eD        \eP{Digit}
+.Ve
+.SS ANCHORS
+.IX Subsection "ANCHORS"
+All are zero-width assertions.
+.PP
+.Vb 11
+\&   ^  Match string start (or line, if /m is used)
+\&   $  Match string end (or line, if /m is used) or before newline
+\&   \eb{} Match boundary of type specified within the braces
+\&   \eB{} Match wherever \eb{} doesn\*(Aqt match
+\&   \eb Match word boundary (between \ew and \eW)
+\&   \eB Match except at word boundary (between \ew and \ew or \eW and \eW)
+\&   \eA Match string start (regardless of /m)
+\&   \eZ Match string end (before optional newline)
+\&   \ez Match absolute string end
+\&   \eG Match where previous m//g left off
+\&   \eK Keep the stuff left of the \eK, don\*(Aqt include it in $&
+.Ve
+.SS QUANTIFIERS
+.IX Subsection "QUANTIFIERS"
+Quantifiers are greedy by default and match the \fBlongest\fR leftmost.
+.PP
+.Vb 10
+\&   Maximal Minimal Possessive Allowed range
+\&   \-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-
+\&   {n,m}   {n,m}?  {n,m}+     Must occur at least n times
+\&                              but no more than m times
+\&   {n,}    {n,}?   {n,}+      Must occur at least n times
+\&   {,n}    {,n}?   {,n}+      Must occur at most n times
+\&   {n}     {n}?    {n}+       Must occur exactly n times
+\&   *       *?      *+         0 or more times (same as {0,})
+\&   +       +?      ++         1 or more times (same as {1,})
+\&   ?       ??      ?+         0 or 1 time (same as {0,1})
+.Ve
+.PP
+The possessive forms (new in Perl 5.10) prevent backtracking: what gets
+matched by a pattern with a possessive quantifier will not be backtracked
+into, even if that causes the whole match to fail.
+.SS "EXTENDED CONSTRUCTS"
+.IX Subsection "EXTENDED CONSTRUCTS"
+.Vb 10
+\&   (?#text)          A comment
+\&   (?:...)           Groups subexpressions without capturing (cluster)
+\&   (?pimsx\-imsx:...) Enable/disable option (as per m// modifiers)
+\&   (?=...)           Zero\-width positive lookahead assertion
+\&   (*pla:...)        Same, starting in 5.32; experimentally in 5.28
+\&   (*positive_lookahead:...) Same, same versions as *pla
+\&   (?!...)           Zero\-width negative lookahead assertion
+\&   (*nla:...)        Same, starting in 5.32; experimentally in 5.28
+\&   (*negative_lookahead:...) Same, same versions as *nla
+\&   (?<=...)          Zero\-width positive lookbehind assertion
+\&   (*plb:...)        Same, starting in 5.32; experimentally in 5.28
+\&   (*positive_lookbehind:...) Same, same versions as *plb
+\&   (?<!...)          Zero\-width negative lookbehind assertion
+\&   (*nlb:...)        Same, starting in 5.32; experimentally in 5.28
+\&   (*negative_lookbehind:...) Same, same versions as *plb
+\&   (?>...)           Grab what we can, prohibit backtracking
+\&   (*atomic:...)     Same, starting in 5.32; experimentally in 5.28
+\&   (?|...)           Branch reset
+\&   (?<name>...)      Named capture
+\&   (?\*(Aqname\*(Aq...)      Named capture
+\&   (?P<name>...)     Named capture (python syntax)
+\&   (?[...])          Extended bracketed character class
+\&   (?{ code })       Embedded code, return value becomes $^R
+\&   (??{ code })      Dynamic regex, return value used as regex
+\&   (?N)              Recurse into subpattern number N
+\&   (?\-N), (?+N)      Recurse into Nth previous/next subpattern
+\&   (?R), (?0)        Recurse at the beginning of the whole pattern
+\&   (?&name)          Recurse into a named subpattern
+\&   (?P>name)         Recurse into a named subpattern (python syntax)
+\&   (?(cond)yes|no)
+\&   (?(cond)yes)      Conditional expression, where "(cond)" can be:
+\&                     (?=pat)   lookahead; also (*pla:pat)
+\&                               (*positive_lookahead:pat)
+\&                     (?!pat)   negative lookahead; also (*nla:pat)
+\&                               (*negative_lookahead:pat)
+\&                     (?<=pat)  lookbehind; also (*plb:pat)
+\&                               (*lookbehind:pat)
+\&                     (?<!pat)  negative lookbehind; also (*nlb:pat)
+\&                               (*negative_lookbehind:pat)
+\&                     (N)       subpattern N has matched something
+\&                     (<name>)  named subpattern has matched something
+\&                     (\*(Aqname\*(Aq)  named subpattern has matched something
+\&                     (?{code}) code condition
+\&                     (R)       true if recursing
+\&                     (RN)      true if recursing into Nth subpattern
+\&                     (R&name)  true if recursing into named subpattern
+\&                     (DEFINE)  always false, no no\-pattern allowed
+.Ve
+.SS VARIABLES
+.IX Subsection "VARIABLES"
+.Vb 1
+\&   $_    Default variable for operators to use
+\&
+\&   $\`    Everything prior to matched string
+\&   $&    Entire matched string
+\&   $\*(Aq    Everything after to matched string
+\&
+\&   ${^PREMATCH}   Everything prior to matched string
+\&   ${^MATCH}      Entire matched string
+\&   ${^POSTMATCH}  Everything after to matched string
+.Ve
+.PP
+Note to those still using Perl 5.18 or earlier:
+The use of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR or \f(CW\*(C`$\*(Aq\*(C'\fR will slow down \fBall\fR regex use
+within your program. Consult perlvar for \f(CW\*(C`@\-\*(C'\fR
+to see equivalent expressions that won't cause slow down.
+See also Devel::SawAmpersand. Starting with Perl 5.10, you
+can also use the equivalent variables \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR
+and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, but for them to be defined, you have to
+specify the \f(CW\*(C`/p\*(C'\fR (preserve) modifier on your regular expression.
+In Perl 5.20, the use of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR and \f(CW\*(C`$\*(Aq\*(C'\fR makes no speed difference.
+.PP
+.Vb 8
+\&   $1, $2 ...  hold the Xth captured expr
+\&   $+    Last parenthesized pattern match
+\&   $^N   Holds the most recently closed capture
+\&   $^R   Holds the result of the last (?{...}) expr
+\&   @\-    Offsets of starts of groups. $\-[0] holds start of whole match
+\&   @+    Offsets of ends of groups. $+[0] holds end of whole match
+\&   %+    Named capture groups
+\&   %\-    Named capture groups, as array refs
+.Ve
+.PP
+Captured groups are numbered according to their \fIopening\fR paren.
+.SS FUNCTIONS
+.IX Subsection "FUNCTIONS"
+.Vb 5
+\&   lc          Lowercase a string
+\&   lcfirst     Lowercase first char of a string
+\&   uc          Uppercase a string
+\&   ucfirst     Titlecase first char of a string
+\&   fc          Foldcase a string
+\&
+\&   pos         Return or set current match position
+\&   quotemeta   Quote metacharacters
+\&   reset       Reset m?pattern? status
+\&   study       Analyze string for optimizing matching
+\&
+\&   split       Use a regex to split a string into parts
+.Ve
+.PP
+The first five of these are like the escape sequences \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR,
+\&\f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eF\*(C'\fR.  For Titlecase, see "Titlecase"; For
+Foldcase, see "Foldcase".
+.SS TERMINOLOGY
+.IX Subsection "TERMINOLOGY"
+\fITitlecase\fR
+.IX Subsection "Titlecase"
+.PP
+Unicode concept which most often is equal to uppercase, but for
+certain characters like the German "sharp s" there is a difference.
+.PP
+\fIFoldcase\fR
+.IX Subsection "Foldcase"
+.PP
+Unicode form that is useful when comparing strings regardless of case,
+as certain characters have complex one-to-many case mappings. Primarily a
+variant of lowercase.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Iain Truskett. Updated by the Perl 5 Porters.
+.PP
+This document may be distributed under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP \(bu 4
+perlretut for a tutorial on regular expressions.
+.IP \(bu 4
+perlrequick for a rapid tutorial.
+.IP \(bu 4
+perlre for more details.
+.IP \(bu 4
+perlvar for details on the variables.
+.IP \(bu 4
+perlop for details on the operators.
+.IP \(bu 4
+perlfunc for details on the functions.
+.IP \(bu 4
+perlfaq6 for FAQs on regular expressions.
+.IP \(bu 4
+perlrebackslash for a reference on backslash sequences.
+.IP \(bu 4
+perlrecharclass for a reference on character classes.
+.IP \(bu 4
+The re module to alter behaviour and aid
+debugging.
+.IP \(bu 4
+"Debugging Regular Expressions" in perldebug
+.IP \(bu 4
+perluniintro, perlunicode, charnames and perllocale
+for details on regexes and internationalisation.
+.IP \(bu 4
+\&\fIMastering Regular Expressions\fR by Jeffrey Friedl
+(<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and
+reference on the topic.
+.SH THANKS
+.IX Header "THANKS"
+David P.C. Wollmann,
+Richard Soderberg,
+Sean M. Burke,
+Tom Christiansen,
+Jim Cromie,
+and
+Jeffrey Goff
+for useful advice.
diff --git a/upstream/mageia-cauldron/man1/perlretut.1 b/upstream/mageia-cauldron/man1/perlretut.1
new file mode 100644
index 00000000..b24096d0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlretut.1
@@ -0,0 +1,3219 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLRETUT 1"
+.TH PERLRETUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlretut \- Perl regular expressions tutorial
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This page provides a basic tutorial on understanding, creating and
+using regular expressions in Perl.  It serves as a complement to the
+reference page on regular expressions perlre.  Regular expressions
+are an integral part of the \f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR and \f(CW\*(C`split\*(C'\fR
+operators and so this tutorial also overlaps with
+"Regexp Quote-Like Operators" in perlop and "split" in perlfunc.
+.PP
+Perl is widely renowned for excellence in text processing, and regular
+expressions are one of the big factors behind this fame.  Perl regular
+expressions display an efficiency and flexibility unknown in most
+other computer languages.  Mastering even the basics of regular
+expressions will allow you to manipulate text with surprising ease.
+.PP
+What is a regular expression?  At its most basic, a regular expression
+is a template that is used to determine if a string has certain
+characteristics.  The string is most often some text, such as a line,
+sentence, web page, or even a whole book, but it doesn't have to be.  It
+could be binary data, for example.  Biologists often use Perl to look
+for patterns in long DNA sequences.
+.PP
+Suppose we want to determine if the text in variable, \f(CW$var\fR contains
+the sequence of characters \f(CW\*(C`m\ u\ s\ h\ r\ o\ o\ m\*(C'\fR
+(blanks added for legibility).  We can write in Perl
+.PP
+.Vb 1
+\& $var =~ m/mushroom/
+.Ve
+.PP
+The value of this expression will be TRUE if \f(CW$var\fR contains that
+sequence of characters anywhere within it, and FALSE otherwise.  The
+portion enclosed in \f(CW\*(Aq/\*(Aq\fR characters denotes the characteristic we
+are looking for.
+We use the term \fIpattern\fR for it.  The process of looking to see if the
+pattern occurs in the string is called \fImatching\fR, and the \f(CW"=~"\fR
+operator along with the \f(CW\*(C`m//\*(C'\fR tell Perl to try to match the pattern
+against the string.  Note that the pattern is also a string, but a very
+special kind of one, as we will see.  Patterns are in common use these
+days;
+examples are the patterns typed into a search engine to find web pages
+and the patterns used to list files in a directory, \fIe.g.\fR, "\f(CW\*(C`ls *.txt\*(C'\fR"
+or "\f(CW\*(C`dir *.*\*(C'\fR".  In Perl, the patterns described by regular expressions
+are used not only to search strings, but to also extract desired parts
+of strings, and to do search and replace operations.
+.PP
+Regular expressions have the undeserved reputation of being abstract
+and difficult to understand.  This really stems simply because the
+notation used to express them tends to be terse and dense, and not
+because of inherent complexity.  We recommend using the \f(CW\*(C`/x\*(C'\fR regular
+expression modifier (described below) along with plenty of white space
+to make them less dense, and easier to read.  Regular expressions are
+constructed using
+simple concepts like conditionals and loops and are no more difficult
+to understand than the corresponding \f(CW\*(C`if\*(C'\fR conditionals and \f(CW\*(C`while\*(C'\fR
+loops in the Perl language itself.
+.PP
+This tutorial flattens the learning curve by discussing regular
+expression concepts, along with their notation, one at a time and with
+many examples.  The first part of the tutorial will progress from the
+simplest word searches to the basic regular expression concepts.  If
+you master the first part, you will have all the tools needed to solve
+about 98% of your needs.  The second part of the tutorial is for those
+comfortable with the basics, and hungry for more power tools.  It
+discusses the more advanced regular expression operators and
+introduces the latest cutting-edge innovations.
+.PP
+A note: to save time, "regular expression" is often abbreviated as
+regexp or regex.  Regexp is a more natural abbreviation than regex, but
+is harder to pronounce.  The Perl pod documentation is evenly split on
+regexp vs regex; in Perl, there is more than one way to abbreviate it.
+We'll use regexp in this tutorial.
+.PP
+New in v5.22, \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR applies stricter
+rules than otherwise when compiling regular expression patterns.  It can
+find things that, while legal, may not be what you intended.
+.SH "Part 1: The basics"
+.IX Header "Part 1: The basics"
+.SS "Simple word matching"
+.IX Subsection "Simple word matching"
+The simplest regexp is simply a word, or more generally, a string of
+characters.  A regexp consisting of just a word matches any string that
+contains that word:
+.PP
+.Vb 1
+\&    "Hello World" =~ /World/;  # matches
+.Ve
+.PP
+What is this Perl statement all about? \f(CW"Hello World"\fR is a simple
+double-quoted string.  \f(CW\*(C`World\*(C'\fR is the regular expression and the
+\&\f(CW\*(C`//\*(C'\fR enclosing \f(CW\*(C`/World/\*(C'\fR tells Perl to search a string for a match.
+The operator \f(CW\*(C`=~\*(C'\fR associates the string with the regexp match and
+produces a true value if the regexp matched, or false if the regexp
+did not match.  In our case, \f(CW\*(C`World\*(C'\fR matches the second word in
+\&\f(CW"Hello World"\fR, so the expression is true.  Expressions like this
+are useful in conditionals:
+.PP
+.Vb 6
+\&    if ("Hello World" =~ /World/) {
+\&        print "It matches\en";
+\&    }
+\&    else {
+\&        print "It doesn\*(Aqt match\en";
+\&    }
+.Ve
+.PP
+There are useful variations on this theme.  The sense of the match can
+be reversed by using the \f(CW\*(C`!~\*(C'\fR operator:
+.PP
+.Vb 6
+\&    if ("Hello World" !~ /World/) {
+\&        print "It doesn\*(Aqt match\en";
+\&    }
+\&    else {
+\&        print "It matches\en";
+\&    }
+.Ve
+.PP
+The literal string in the regexp can be replaced by a variable:
+.PP
+.Vb 7
+\&    my $greeting = "World";
+\&    if ("Hello World" =~ /$greeting/) {
+\&        print "It matches\en";
+\&    }
+\&    else {
+\&        print "It doesn\*(Aqt match\en";
+\&    }
+.Ve
+.PP
+If you're matching against the special default variable \f(CW$_\fR, the
+\&\f(CW\*(C`$_ =~\*(C'\fR part can be omitted:
+.PP
+.Vb 7
+\&    $_ = "Hello World";
+\&    if (/World/) {
+\&        print "It matches\en";
+\&    }
+\&    else {
+\&        print "It doesn\*(Aqt match\en";
+\&    }
+.Ve
+.PP
+And finally, the \f(CW\*(C`//\*(C'\fR default delimiters for a match can be changed
+to arbitrary delimiters by putting an \f(CW\*(Aqm\*(Aq\fR out front:
+.PP
+.Vb 4
+\&    "Hello World" =~ m!World!;   # matches, delimited by \*(Aq!\*(Aq
+\&    "Hello World" =~ m{World};   # matches, note the paired \*(Aq{}\*(Aq
+\&    "/usr/bin/perl" =~ m"/perl"; # matches after \*(Aq/usr/bin\*(Aq,
+\&                                 # \*(Aq/\*(Aq becomes an ordinary char
+.Ve
+.PP
+\&\f(CW\*(C`/World/\*(C'\fR, \f(CW\*(C`m!World!\*(C'\fR, and \f(CW\*(C`m{World}\*(C'\fR all represent the
+same thing.  When, \fIe.g.\fR, the quote (\f(CW\*(Aq"\*(Aq\fR) is used as a delimiter, the forward
+slash \f(CW\*(Aq/\*(Aq\fR becomes an ordinary character and can be used in this regexp
+without trouble.
+.PP
+Let's consider how different regexps would match \f(CW"Hello World"\fR:
+.PP
+.Vb 4
+\&    "Hello World" =~ /world/;  # doesn\*(Aqt match
+\&    "Hello World" =~ /o W/;    # matches
+\&    "Hello World" =~ /oW/;     # doesn\*(Aqt match
+\&    "Hello World" =~ /World /; # doesn\*(Aqt match
+.Ve
+.PP
+The first regexp \f(CW\*(C`world\*(C'\fR doesn't match because regexps are by default
+case-sensitive.  The second regexp matches because the substring
+\&\f(CW\*(Aqo\ W\*(Aq\fR occurs in the string \f(CW"Hello\ World"\fR.  The space
+character \f(CW\*(Aq \*(Aq\fR is treated like any other character in a regexp and is
+needed to match in this case.  The lack of a space character is the
+reason the third regexp \f(CW\*(AqoW\*(Aq\fR doesn't match.  The fourth regexp
+"\f(CW\*(C`World \*(C'\fR" doesn't match because there is a space at the end of the
+regexp, but not at the end of the string.  The lesson here is that
+regexps must match a part of the string \fIexactly\fR in order for the
+statement to be true.
+.PP
+If a regexp matches in more than one place in the string, Perl will
+always match at the earliest possible point in the string:
+.PP
+.Vb 2
+\&    "Hello World" =~ /o/;       # matches \*(Aqo\*(Aq in \*(AqHello\*(Aq
+\&    "That hat is red" =~ /hat/; # matches \*(Aqhat\*(Aq in \*(AqThat\*(Aq
+.Ve
+.PP
+With respect to character matching, there are a few more points you
+need to know about.   First of all, not all characters can be used
+"as-is" in a match.  Some characters, called \fImetacharacters\fR, are
+generally reserved for use in regexp notation.  The metacharacters are
+.PP
+.Vb 1
+\&    {}[]()^$.|*+?\-#\e
+.Ve
+.PP
+This list is not as definitive as it may appear (or be claimed to be in
+other documentation).  For example, \f(CW"#"\fR is a metacharacter only when
+the \f(CW\*(C`/x\*(C'\fR pattern modifier (described below) is used, and both \f(CW"}"\fR
+and \f(CW"]"\fR are metacharacters only when paired with opening \f(CW"{"\fR or
+\&\f(CW"["\fR respectively; other gotchas apply.
+.PP
+The significance of each of these will be explained
+in the rest of the tutorial, but for now, it is important only to know
+that a metacharacter can be matched as-is by putting a backslash before
+it:
+.PP
+.Vb 5
+\&    "2+2=4" =~ /2+2/;    # doesn\*(Aqt match, + is a metacharacter
+\&    "2+2=4" =~ /2\e+2/;   # matches, \e+ is treated like an ordinary +
+\&    "The interval is [0,1)." =~ /[0,1)./     # is a syntax error!
+\&    "The interval is [0,1)." =~ /\e[0,1\e)\e./  # matches
+\&    "#!/usr/bin/perl" =~ /#!\e/usr\e/bin\e/perl/;  # matches
+.Ve
+.PP
+In the last regexp, the forward slash \f(CW\*(Aq/\*(Aq\fR is also backslashed,
+because it is used to delimit the regexp.  This can lead to LTS
+(leaning toothpick syndrome), however, and it is often more readable
+to change delimiters.
+.PP
+.Vb 1
+\&    "#!/usr/bin/perl" =~ m!#\e!/usr/bin/perl!;  # easier to read
+.Ve
+.PP
+The backslash character \f(CW\*(Aq\e\*(Aq\fR is a metacharacter itself and needs to
+be backslashed:
+.PP
+.Vb 1
+\&    \*(AqC:\eWIN32\*(Aq =~ /C:\e\eWIN/;   # matches
+.Ve
+.PP
+In situations where it doesn't make sense for a particular metacharacter
+to mean what it normally does, it automatically loses its
+metacharacter-ness and becomes an ordinary character that is to be
+matched literally.  For example, the \f(CW\*(Aq}\*(Aq\fR is a metacharacter only when
+it is the mate of a \f(CW\*(Aq{\*(Aq\fR metacharacter.  Otherwise it is treated as a
+literal RIGHT CURLY BRACKET.  This may lead to unexpected results.
+\&\f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR can catch some of these.
+.PP
+In addition to the metacharacters, there are some ASCII characters
+which don't have printable character equivalents and are instead
+represented by \fIescape sequences\fR.  Common examples are \f(CW\*(C`\et\*(C'\fR for a
+tab, \f(CW\*(C`\en\*(C'\fR for a newline, \f(CW\*(C`\er\*(C'\fR for a carriage return and \f(CW\*(C`\ea\*(C'\fR for a
+bell (or alert).  If your string is better thought of as a sequence of arbitrary
+bytes, the octal escape sequence, \fIe.g.\fR, \f(CW\*(C`\e033\*(C'\fR, or hexadecimal escape
+sequence, \fIe.g.\fR, \f(CW\*(C`\ex1B\*(C'\fR may be a more natural representation for your
+bytes.  Here are some examples of escapes:
+.PP
+.Vb 5
+\&    "1000\et2000" =~ m(0\et2)   # matches
+\&    "1000\en2000" =~ /0\en20/   # matches
+\&    "1000\et2000" =~ /\e000\et2/ # doesn\*(Aqt match, "0" ne "\e000"
+\&    "cat"   =~ /\eo{143}\ex61\ex74/ # matches in ASCII, but a weird way
+\&                                 # to spell cat
+.Ve
+.PP
+If you've been around Perl a while, all this talk of escape sequences
+may seem familiar.  Similar escape sequences are used in double-quoted
+strings and in fact the regexps in Perl are mostly treated as
+double-quoted strings.  This means that variables can be used in
+regexps as well.  Just like double-quoted strings, the values of the
+variables in the regexp will be substituted in before the regexp is
+evaluated for matching purposes.  So we have:
+.PP
+.Vb 4
+\&    $foo = \*(Aqhouse\*(Aq;
+\&    \*(Aqhousecat\*(Aq =~ /$foo/;      # matches
+\&    \*(Aqcathouse\*(Aq =~ /cat$foo/;   # matches
+\&    \*(Aqhousecat\*(Aq =~ /${foo}cat/; # matches
+.Ve
+.PP
+So far, so good.  With the knowledge above you can already perform
+searches with just about any literal string regexp you can dream up.
+Here is a \fIvery simple\fR emulation of the Unix grep program:
+.PP
+.Vb 7
+\&    % cat > simple_grep
+\&    #!/usr/bin/perl
+\&    $regexp = shift;
+\&    while (<>) {
+\&        print if /$regexp/;
+\&    }
+\&    ^D
+\&
+\&    % chmod +x simple_grep
+\&
+\&    % simple_grep abba /usr/dict/words
+\&    Babbage
+\&    cabbage
+\&    cabbages
+\&    sabbath
+\&    Sabbathize
+\&    Sabbathizes
+\&    sabbatical
+\&    scabbard
+\&    scabbards
+.Ve
+.PP
+This program is easy to understand.  \f(CW\*(C`#!/usr/bin/perl\*(C'\fR is the standard
+way to invoke a perl program from the shell.
+\&\f(CW\*(C`$regexp\ =\ shift;\*(C'\fR saves the first command line argument as the
+regexp to be used, leaving the rest of the command line arguments to
+be treated as files.  \f(CW\*(C`while\ (<>)\*(C'\fR loops over all the lines in
+all the files.  For each line, \f(CW\*(C`print\ if\ /$regexp/;\*(C'\fR prints the
+line if the regexp matches the line.  In this line, both \f(CW\*(C`print\*(C'\fR and
+\&\f(CW\*(C`/$regexp/\*(C'\fR use the default variable \f(CW$_\fR implicitly.
+.PP
+With all of the regexps above, if the regexp matched anywhere in the
+string, it was considered a match.  Sometimes, however, we'd like to
+specify \fIwhere\fR in the string the regexp should try to match.  To do
+this, we would use the \fIanchor\fR metacharacters \f(CW\*(Aq^\*(Aq\fR and \f(CW\*(Aq$\*(Aq\fR.  The
+anchor \f(CW\*(Aq^\*(Aq\fR means match at the beginning of the string and the anchor
+\&\f(CW\*(Aq$\*(Aq\fR means match at the end of the string, or before a newline at the
+end of the string.  Here is how they are used:
+.PP
+.Vb 4
+\&    "housekeeper" =~ /keeper/;    # matches
+\&    "housekeeper" =~ /^keeper/;   # doesn\*(Aqt match
+\&    "housekeeper" =~ /keeper$/;   # matches
+\&    "housekeeper\en" =~ /keeper$/; # matches
+.Ve
+.PP
+The second regexp doesn't match because \f(CW\*(Aq^\*(Aq\fR constrains \f(CW\*(C`keeper\*(C'\fR to
+match only at the beginning of the string, but \f(CW"housekeeper"\fR has
+keeper starting in the middle.  The third regexp does match, since the
+\&\f(CW\*(Aq$\*(Aq\fR constrains \f(CW\*(C`keeper\*(C'\fR to match only at the end of the string.
+.PP
+When both \f(CW\*(Aq^\*(Aq\fR and \f(CW\*(Aq$\*(Aq\fR are used at the same time, the regexp has to
+match both the beginning and the end of the string, \fIi.e.\fR, the regexp
+matches the whole string.  Consider
+.PP
+.Vb 3
+\&    "keeper" =~ /^keep$/;      # doesn\*(Aqt match
+\&    "keeper" =~ /^keeper$/;    # matches
+\&    ""       =~ /^$/;          # ^$ matches an empty string
+.Ve
+.PP
+The first regexp doesn't match because the string has more to it than
+\&\f(CW\*(C`keep\*(C'\fR.  Since the second regexp is exactly the string, it
+matches.  Using both \f(CW\*(Aq^\*(Aq\fR and \f(CW\*(Aq$\*(Aq\fR in a regexp forces the complete
+string to match, so it gives you complete control over which strings
+match and which don't.  Suppose you are looking for a fellow named
+bert, off in a string by himself:
+.PP
+.Vb 1
+\&    "dogbert" =~ /bert/;   # matches, but not what you want
+\&
+\&    "dilbert" =~ /^bert/;  # doesn\*(Aqt match, but ..
+\&    "bertram" =~ /^bert/;  # matches, so still not good enough
+\&
+\&    "bertram" =~ /^bert$/; # doesn\*(Aqt match, good
+\&    "dilbert" =~ /^bert$/; # doesn\*(Aqt match, good
+\&    "bert"    =~ /^bert$/; # matches, perfect
+.Ve
+.PP
+Of course, in the case of a literal string, one could just as easily
+use the string comparison \f(CW\*(C`$string\ eq\ \*(Aqbert\*(Aq\*(C'\fR and it would be
+more efficient.   The  \f(CW\*(C`^...$\*(C'\fR regexp really becomes useful when we
+add in the more powerful regexp tools below.
+.SS "Using character classes"
+.IX Subsection "Using character classes"
+Although one can already do quite a lot with the literal string
+regexps above, we've only scratched the surface of regular expression
+technology.  In this and subsequent sections we will introduce regexp
+concepts (and associated metacharacter notations) that will allow a
+regexp to represent not just a single character sequence, but a \fIwhole
+class\fR of them.
+.PP
+One such concept is that of a \fIcharacter class\fR.  A character class
+allows a set of possible characters, rather than just a single
+character, to match at a particular point in a regexp.  You can define
+your own custom character classes.  These
+are denoted by brackets \f(CW\*(C`[...]\*(C'\fR, with the set of characters
+to be possibly matched inside.  Here are some examples:
+.PP
+.Vb 4
+\&    /cat/;       # matches \*(Aqcat\*(Aq
+\&    /[bcr]at/;   # matches \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+\&    /item[0123456789]/;  # matches \*(Aqitem0\*(Aq or ... or \*(Aqitem9\*(Aq
+\&    "abc" =~ /[cab]/;    # matches \*(Aqa\*(Aq
+.Ve
+.PP
+In the last statement, even though \f(CW\*(Aqc\*(Aq\fR is the first character in
+the class, \f(CW\*(Aqa\*(Aq\fR matches because the first character position in the
+string is the earliest point at which the regexp can match.
+.PP
+.Vb 2
+\&    /[yY][eE][sS]/;      # match \*(Aqyes\*(Aq in a case\-insensitive way
+\&                         # \*(Aqyes\*(Aq, \*(AqYes\*(Aq, \*(AqYES\*(Aq, etc.
+.Ve
+.PP
+This regexp displays a common task: perform a case-insensitive
+match.  Perl provides a way of avoiding all those brackets by simply
+appending an \f(CW\*(Aqi\*(Aq\fR to the end of the match.  Then \f(CW\*(C`/[yY][eE][sS]/;\*(C'\fR
+can be rewritten as \f(CW\*(C`/yes/i;\*(C'\fR.  The \f(CW\*(Aqi\*(Aq\fR stands for
+case-insensitive and is an example of a \fImodifier\fR of the matching
+operation.  We will meet other modifiers later in the tutorial.
+.PP
+We saw in the section above that there were ordinary characters, which
+represented themselves, and special characters, which needed a
+backslash \f(CW\*(Aq\e\*(Aq\fR to represent themselves.  The same is true in a
+character class, but the sets of ordinary and special characters
+inside a character class are different than those outside a character
+class.  The special characters for a character class are \f(CW\*(C`\-]\e^$\*(C'\fR (and
+the pattern delimiter, whatever it is).
+\&\f(CW\*(Aq]\*(Aq\fR is special because it denotes the end of a character class.  \f(CW\*(Aq$\*(Aq\fR is
+special because it denotes a scalar variable.  \f(CW\*(Aq\e\*(Aq\fR is special because
+it is used in escape sequences, just like above.  Here is how the
+special characters \f(CW\*(C`]$\e\*(C'\fR are handled:
+.PP
+.Vb 5
+\&   /[\e]c]def/; # matches \*(Aq]def\*(Aq or \*(Aqcdef\*(Aq
+\&   $x = \*(Aqbcr\*(Aq;
+\&   /[$x]at/;   # matches \*(Aqbat\*(Aq, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+\&   /[\e$x]at/;  # matches \*(Aq$at\*(Aq or \*(Aqxat\*(Aq
+\&   /[\e\e$x]at/; # matches \*(Aq\eat\*(Aq, \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
+.Ve
+.PP
+The last two are a little tricky.  In \f(CW\*(C`[\e$x]\*(C'\fR, the backslash protects
+the dollar sign, so the character class has two members \f(CW\*(Aq$\*(Aq\fR and \f(CW\*(Aqx\*(Aq\fR.
+In \f(CW\*(C`[\e\e$x]\*(C'\fR, the backslash is protected, so \f(CW$x\fR is treated as a
+variable and substituted in double quote fashion.
+.PP
+The special character \f(CW\*(Aq\-\*(Aq\fR acts as a range operator within character
+classes, so that a contiguous set of characters can be written as a
+range.  With ranges, the unwieldy \f(CW\*(C`[0123456789]\*(C'\fR and \f(CW\*(C`[abc...xyz]\*(C'\fR
+become the svelte \f(CW\*(C`[0\-9]\*(C'\fR and \f(CW\*(C`[a\-z]\*(C'\fR.  Some examples are
+.PP
+.Vb 6
+\&    /item[0\-9]/;  # matches \*(Aqitem0\*(Aq or ... or \*(Aqitem9\*(Aq
+\&    /[0\-9bx\-z]aa/;  # matches \*(Aq0aa\*(Aq, ..., \*(Aq9aa\*(Aq,
+\&                    # \*(Aqbaa\*(Aq, \*(Aqxaa\*(Aq, \*(Aqyaa\*(Aq, or \*(Aqzaa\*(Aq
+\&    /[0\-9a\-fA\-F]/;  # matches a hexadecimal digit
+\&    /[0\-9a\-zA\-Z_]/; # matches a "word" character,
+\&                    # like those in a Perl variable name
+.Ve
+.PP
+If \f(CW\*(Aq\-\*(Aq\fR is the first or last character in a character class, it is
+treated as an ordinary character; \f(CW\*(C`[\-ab]\*(C'\fR, \f(CW\*(C`[ab\-]\*(C'\fR and \f(CW\*(C`[a\e\-b]\*(C'\fR are
+all equivalent.
+.PP
+The special character \f(CW\*(Aq^\*(Aq\fR in the first position of a character class
+denotes a \fInegated character class\fR, which matches any character but
+those in the brackets.  Both \f(CW\*(C`[...]\*(C'\fR and \f(CW\*(C`[^...]\*(C'\fR must match a
+character, or the match fails.  Then
+.PP
+.Vb 4
+\&    /[^a]at/;  # doesn\*(Aqt match \*(Aqaat\*(Aq or \*(Aqat\*(Aq, but matches
+\&               # all other \*(Aqbat\*(Aq, \*(Aqcat, \*(Aq0at\*(Aq, \*(Aq%at\*(Aq, etc.
+\&    /[^0\-9]/;  # matches a non\-numeric character
+\&    /[a^]at/;  # matches \*(Aqaat\*(Aq or \*(Aq^at\*(Aq; here \*(Aq^\*(Aq is ordinary
+.Ve
+.PP
+Now, even \f(CW\*(C`[0\-9]\*(C'\fR can be a bother to write multiple times, so in the
+interest of saving keystrokes and making regexps more readable, Perl
+has several abbreviations for common character classes, as shown below.
+Since the introduction of Unicode, unless the \f(CW\*(C`/a\*(C'\fR modifier is in
+effect, these character classes match more than just a few characters in
+the ASCII range.
+.IP \(bu 4
+\&\f(CW\*(C`\ed\*(C'\fR matches a digit, not just \f(CW\*(C`[0\-9]\*(C'\fR but also digits from non-roman scripts
+.IP \(bu 4
+\&\f(CW\*(C`\es\*(C'\fR matches a whitespace character, the set \f(CW\*(C`[\e \et\er\en\ef]\*(C'\fR and others
+.IP \(bu 4
+\&\f(CW\*(C`\ew\*(C'\fR matches a word character (alphanumeric or \f(CW\*(Aq_\*(Aq\fR), not just \f(CW\*(C`[0\-9a\-zA\-Z_]\*(C'\fR
+but also digits and characters from non-roman scripts
+.IP \(bu 4
+\&\f(CW\*(C`\eD\*(C'\fR is a negated \f(CW\*(C`\ed\*(C'\fR; it represents any other character than a digit, or \f(CW\*(C`[^\ed]\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\eS\*(C'\fR is a negated \f(CW\*(C`\es\*(C'\fR; it represents any non-whitespace character \f(CW\*(C`[^\es]\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`\eW\*(C'\fR is a negated \f(CW\*(C`\ew\*(C'\fR; it represents any non-word character \f(CW\*(C`[^\ew]\*(C'\fR
+.IP \(bu 4
+The period \f(CW\*(Aq.\*(Aq\fR matches any character but \f(CW"\en"\fR (unless the modifier \f(CW\*(C`/s\*(C'\fR is
+in effect, as explained below).
+.IP \(bu 4
+\&\f(CW\*(C`\eN\*(C'\fR, like the period, matches any character but \f(CW"\en"\fR, but it does so
+regardless of whether the modifier \f(CW\*(C`/s\*(C'\fR is in effect.
+.PP
+The \f(CW\*(C`/a\*(C'\fR modifier, available starting in Perl 5.14,  is used to
+restrict the matches of \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\es\*(C'\fR, and \f(CW\*(C`\ew\*(C'\fR to just those in the ASCII range.
+It is useful to keep your program from being needlessly exposed to full
+Unicode (and its accompanying security considerations) when all you want
+is to process English-like text.  (The "a" may be doubled, \f(CW\*(C`/aa\*(C'\fR, to
+provide even more restrictions, preventing case-insensitive matching of
+ASCII with non-ASCII characters; otherwise a Unicode "Kelvin Sign"
+would caselessly match a "k" or "K".)
+.PP
+The \f(CW\*(C`\ed\es\ew\eD\eS\eW\*(C'\fR abbreviations can be used both inside and outside
+of bracketed character classes.  Here are some in use:
+.PP
+.Vb 7
+\&    /\ed\ed:\ed\ed:\ed\ed/; # matches a hh:mm:ss time format
+\&    /[\ed\es]/;         # matches any digit or whitespace character
+\&    /\ew\eW\ew/;         # matches a word char, followed by a
+\&                      # non\-word char, followed by a word char
+\&    /..rt/;           # matches any two chars, followed by \*(Aqrt\*(Aq
+\&    /end\e./;          # matches \*(Aqend.\*(Aq
+\&    /end[.]/;         # same thing, matches \*(Aqend.\*(Aq
+.Ve
+.PP
+Because a period is a metacharacter, it needs to be escaped to match
+as an ordinary period. Because, for example, \f(CW\*(C`\ed\*(C'\fR and \f(CW\*(C`\ew\*(C'\fR are sets
+of characters, it is incorrect to think of \f(CW\*(C`[^\ed\ew]\*(C'\fR as \f(CW\*(C`[\eD\eW]\*(C'\fR; in
+fact \f(CW\*(C`[^\ed\ew]\*(C'\fR is the same as \f(CW\*(C`[^\ew]\*(C'\fR, which is the same as
+\&\f(CW\*(C`[\eW]\*(C'\fR. Think De Morgan's laws.
+.PP
+In actuality, the period and \f(CW\*(C`\ed\es\ew\eD\eS\eW\*(C'\fR abbreviations are
+themselves types of character classes, so the ones surrounded by
+brackets are just one type of character class.  When we need to make a
+distinction, we refer to them as "bracketed character classes."
+.PP
+An anchor useful in basic regexps is the \fIword anchor\fR
+\&\f(CW\*(C`\eb\*(C'\fR.  This matches a boundary between a word character and a non-word
+character \f(CW\*(C`\ew\eW\*(C'\fR or \f(CW\*(C`\eW\ew\*(C'\fR:
+.PP
+.Vb 5
+\&    $x = "Housecat catenates house and cat";
+\&    $x =~ /cat/;    # matches cat in \*(Aqhousecat\*(Aq
+\&    $x =~ /\ebcat/;  # matches cat in \*(Aqcatenates\*(Aq
+\&    $x =~ /cat\eb/;  # matches cat in \*(Aqhousecat\*(Aq
+\&    $x =~ /\ebcat\eb/;  # matches \*(Aqcat\*(Aq at end of string
+.Ve
+.PP
+Note in the last example, the end of the string is considered a word
+boundary.
+.PP
+For natural language processing (so that, for example, apostrophes are
+included in words), use instead \f(CW\*(C`\eb{wb}\*(C'\fR
+.PP
+.Vb 1
+\&    "don\*(Aqt" =~ / .+? \eb{wb} /x;  # matches the whole string
+.Ve
+.PP
+You might wonder why \f(CW\*(Aq.\*(Aq\fR matches everything but \f(CW"\en"\fR \- why not
+every character? The reason is that often one is matching against
+lines and would like to ignore the newline characters.  For instance,
+while the string \f(CW"\en"\fR represents one line, we would like to think
+of it as empty.  Then
+.PP
+.Vb 2
+\&    ""   =~ /^$/;    # matches
+\&    "\en" =~ /^$/;    # matches, $ anchors before "\en"
+\&
+\&    ""   =~ /./;      # doesn\*(Aqt match; it needs a char
+\&    ""   =~ /^.$/;    # doesn\*(Aqt match; it needs a char
+\&    "\en" =~ /^.$/;    # doesn\*(Aqt match; it needs a char other than "\en"
+\&    "a"  =~ /^.$/;    # matches
+\&    "a\en"  =~ /^.$/;  # matches, $ anchors before "\en"
+.Ve
+.PP
+This behavior is convenient, because we usually want to ignore
+newlines when we count and match characters in a line.  Sometimes,
+however, we want to keep track of newlines.  We might even want \f(CW\*(Aq^\*(Aq\fR
+and \f(CW\*(Aq$\*(Aq\fR to anchor at the beginning and end of lines within the
+string, rather than just the beginning and end of the string.  Perl
+allows us to choose between ignoring and paying attention to newlines
+by using the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR modifiers.  \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR stand for
+single line and multi-line and they determine whether a string is to
+be treated as one continuous string, or as a set of lines.  The two
+modifiers affect two aspects of how the regexp is interpreted: 1) how
+the \f(CW\*(Aq.\*(Aq\fR character class is defined, and 2) where the anchors \f(CW\*(Aq^\*(Aq\fR
+and \f(CW\*(Aq$\*(Aq\fR are able to match.  Here are the four possible combinations:
+.IP \(bu 4
+no modifiers: Default behavior.  \f(CW\*(Aq.\*(Aq\fR matches any character
+except \f(CW"\en"\fR.  \f(CW\*(Aq^\*(Aq\fR matches only at the beginning of the string and
+\&\f(CW\*(Aq$\*(Aq\fR matches only at the end or before a newline at the end.
+.IP \(bu 4
+s modifier (\f(CW\*(C`/s\*(C'\fR): Treat string as a single long line.  \f(CW\*(Aq.\*(Aq\fR matches
+any character, even \f(CW"\en"\fR.  \f(CW\*(Aq^\*(Aq\fR matches only at the beginning of
+the string and \f(CW\*(Aq$\*(Aq\fR matches only at the end or before a newline at the
+end.
+.IP \(bu 4
+m modifier (\f(CW\*(C`/m\*(C'\fR): Treat string as a set of multiple lines.  \f(CW\*(Aq.\*(Aq\fR
+matches any character except \f(CW"\en"\fR.  \f(CW\*(Aq^\*(Aq\fR and \f(CW\*(Aq$\*(Aq\fR are able to match
+at the start or end of \fIany\fR line within the string.
+.IP \(bu 4
+both s and m modifiers (\f(CW\*(C`/sm\*(C'\fR): Treat string as a single long line, but
+detect multiple lines.  \f(CW\*(Aq.\*(Aq\fR matches any character, even
+\&\f(CW"\en"\fR.  \f(CW\*(Aq^\*(Aq\fR and \f(CW\*(Aq$\*(Aq\fR, however, are able to match at the start or end
+of \fIany\fR line within the string.
+.PP
+Here are examples of \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR in action:
+.PP
+.Vb 1
+\&    $x = "There once was a girl\enWho programmed in Perl\en";
+\&
+\&    $x =~ /^Who/;   # doesn\*(Aqt match, "Who" not at start of string
+\&    $x =~ /^Who/s;  # doesn\*(Aqt match, "Who" not at start of string
+\&    $x =~ /^Who/m;  # matches, "Who" at start of second line
+\&    $x =~ /^Who/sm; # matches, "Who" at start of second line
+\&
+\&    $x =~ /girl.Who/;   # doesn\*(Aqt match, "." doesn\*(Aqt match "\en"
+\&    $x =~ /girl.Who/s;  # matches, "." matches "\en"
+\&    $x =~ /girl.Who/m;  # doesn\*(Aqt match, "." doesn\*(Aqt match "\en"
+\&    $x =~ /girl.Who/sm; # matches, "." matches "\en"
+.Ve
+.PP
+Most of the time, the default behavior is what is wanted, but \f(CW\*(C`/s\*(C'\fR and
+\&\f(CW\*(C`/m\*(C'\fR are occasionally very useful.  If \f(CW\*(C`/m\*(C'\fR is being used, the start
+of the string can still be matched with \f(CW\*(C`\eA\*(C'\fR and the end of the string
+can still be matched with the anchors \f(CW\*(C`\eZ\*(C'\fR (matches both the end and
+the newline before, like \f(CW\*(Aq$\*(Aq\fR), and \f(CW\*(C`\ez\*(C'\fR (matches only the end):
+.PP
+.Vb 2
+\&    $x =~ /^Who/m;   # matches, "Who" at start of second line
+\&    $x =~ /\eAWho/m;  # doesn\*(Aqt match, "Who" is not at start of string
+\&
+\&    $x =~ /girl$/m;  # matches, "girl" at end of first line
+\&    $x =~ /girl\eZ/m; # doesn\*(Aqt match, "girl" is not at end of string
+\&
+\&    $x =~ /Perl\eZ/m; # matches, "Perl" is at newline before end
+\&    $x =~ /Perl\ez/m; # doesn\*(Aqt match, "Perl" is not at end of string
+.Ve
+.PP
+We now know how to create choices among classes of characters in a
+regexp.  What about choices among words or character strings? Such
+choices are described in the next section.
+.SS "Matching this or that"
+.IX Subsection "Matching this or that"
+Sometimes we would like our regexp to be able to match different
+possible words or character strings.  This is accomplished by using
+the \fIalternation\fR metacharacter \f(CW\*(Aq|\*(Aq\fR.  To match \f(CW\*(C`dog\*(C'\fR or \f(CW\*(C`cat\*(C'\fR, we
+form the regexp \f(CW\*(C`dog|cat\*(C'\fR.  As before, Perl will try to match the
+regexp at the earliest possible point in the string.  At each
+character position, Perl will first try to match the first
+alternative, \f(CW\*(C`dog\*(C'\fR.  If \f(CW\*(C`dog\*(C'\fR doesn't match, Perl will then try the
+next alternative, \f(CW\*(C`cat\*(C'\fR.  If \f(CW\*(C`cat\*(C'\fR doesn't match either, then the
+match fails and Perl moves to the next position in the string.  Some
+examples:
+.PP
+.Vb 2
+\&    "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
+\&    "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"
+.Ve
+.PP
+Even though \f(CW\*(C`dog\*(C'\fR is the first alternative in the second regexp,
+\&\f(CW\*(C`cat\*(C'\fR is able to match earlier in the string.
+.PP
+.Vb 2
+\&    "cats"          =~ /c|ca|cat|cats/; # matches "c"
+\&    "cats"          =~ /cats|cat|ca|c/; # matches "cats"
+.Ve
+.PP
+Here, all the alternatives match at the first string position, so the
+first alternative is the one that matches.  If some of the
+alternatives are truncations of the others, put the longest ones first
+to give them a chance to match.
+.PP
+.Vb 2
+\&    "cab" =~ /a|b|c/ # matches "c"
+\&                     # /a|b|c/ == /[abc]/
+.Ve
+.PP
+The last example points out that character classes are like
+alternations of characters.  At a given character position, the first
+alternative that allows the regexp match to succeed will be the one
+that matches.
+.SS "Grouping things and hierarchical matching"
+.IX Subsection "Grouping things and hierarchical matching"
+Alternation allows a regexp to choose among alternatives, but by
+itself it is unsatisfying.  The reason is that each alternative is a whole
+regexp, but sometime we want alternatives for just part of a
+regexp.  For instance, suppose we want to search for housecats or
+housekeepers.  The regexp \f(CW\*(C`housecat|housekeeper\*(C'\fR fits the bill, but is
+inefficient because we had to type \f(CW\*(C`house\*(C'\fR twice.  It would be nice to
+have parts of the regexp be constant, like \f(CW\*(C`house\*(C'\fR, and some
+parts have alternatives, like \f(CW\*(C`cat|keeper\*(C'\fR.
+.PP
+The \fIgrouping\fR metacharacters \f(CW\*(C`()\*(C'\fR solve this problem.  Grouping
+allows parts of a regexp to be treated as a single unit.  Parts of a
+regexp are grouped by enclosing them in parentheses.  Thus we could solve
+the \f(CW\*(C`housecat|housekeeper\*(C'\fR by forming the regexp as
+\&\f(CWhouse(cat|keeper)\fR.  The regexp \f(CWhouse(cat|keeper)\fR means match
+\&\f(CW\*(C`house\*(C'\fR followed by either \f(CW\*(C`cat\*(C'\fR or \f(CW\*(C`keeper\*(C'\fR.  Some more examples
+are
+.PP
+.Vb 4
+\&    /(a|b)b/;    # matches \*(Aqab\*(Aq or \*(Aqbb\*(Aq
+\&    /(ac|b)b/;   # matches \*(Aqacb\*(Aq or \*(Aqbb\*(Aq
+\&    /(^a|b)c/;   # matches \*(Aqac\*(Aq at start of string or \*(Aqbc\*(Aq anywhere
+\&    /(a|[bc])d/; # matches \*(Aqad\*(Aq, \*(Aqbd\*(Aq, or \*(Aqcd\*(Aq
+\&
+\&    /house(cat|)/;  # matches either \*(Aqhousecat\*(Aq or \*(Aqhouse\*(Aq
+\&    /house(cat(s|)|)/;  # matches either \*(Aqhousecats\*(Aq or \*(Aqhousecat\*(Aq or
+\&                        # \*(Aqhouse\*(Aq.  Note groups can be nested.
+\&
+\&    /(19|20|)\ed\ed/;  # match years 19xx, 20xx, or the Y2K problem, xx
+\&    "20" =~ /(19|20|)\ed\ed/;  # matches the null alternative \*(Aq()\ed\ed\*(Aq,
+\&                             # because \*(Aq20\ed\ed\*(Aq can\*(Aqt match
+.Ve
+.PP
+Alternations behave the same way in groups as out of them: at a given
+string position, the leftmost alternative that allows the regexp to
+match is taken.  So in the last example at the first string position,
+\&\f(CW"20"\fR matches the second alternative, but there is nothing left over
+to match the next two digits \f(CW\*(C`\ed\ed\*(C'\fR.  So Perl moves on to the next
+alternative, which is the null alternative and that works, since
+\&\f(CW"20"\fR is two digits.
+.PP
+The process of trying one alternative, seeing if it matches, and
+moving on to the next alternative, while going back in the string
+from where the previous alternative was tried, if it doesn't, is called
+\&\fIbacktracking\fR.  The term "backtracking" comes from the idea that
+matching a regexp is like a walk in the woods.  Successfully matching
+a regexp is like arriving at a destination.  There are many possible
+trailheads, one for each string position, and each one is tried in
+order, left to right.  From each trailhead there may be many paths,
+some of which get you there, and some which are dead ends.  When you
+walk along a trail and hit a dead end, you have to backtrack along the
+trail to an earlier point to try another trail.  If you hit your
+destination, you stop immediately and forget about trying all the
+other trails.  You are persistent, and only if you have tried all the
+trails from all the trailheads and not arrived at your destination, do
+you declare failure.  To be concrete, here is a step-by-step analysis
+of what Perl does when it tries to match the regexp
+.PP
+.Vb 1
+\&    "abcde" =~ /(abd|abc)(df|d|de)/;
+.Ve
+.IP 1. 4
+Start with the first letter in the string \f(CW\*(Aqa\*(Aq\fR.
+.IP 2. 4
+Try the first alternative in the first group \f(CW\*(Aqabd\*(Aq\fR.
+.IP 3. 4
+Match \f(CW\*(Aqa\*(Aq\fR followed by \f(CW\*(Aqb\*(Aq\fR. So far so good.
+.IP 4. 4
+\&\f(CW\*(Aqd\*(Aq\fR in the regexp doesn't match \f(CW\*(Aqc\*(Aq\fR in the string \- a
+dead end.  So backtrack two characters and pick the second alternative
+in the first group \f(CW\*(Aqabc\*(Aq\fR.
+.IP 5. 4
+Match \f(CW\*(Aqa\*(Aq\fR followed by \f(CW\*(Aqb\*(Aq\fR followed by \f(CW\*(Aqc\*(Aq\fR.  We are on a roll
+and have satisfied the first group. Set \f(CW$1\fR to \f(CW\*(Aqabc\*(Aq\fR.
+.IP 6. 4
+Move on to the second group and pick the first alternative \f(CW\*(Aqdf\*(Aq\fR.
+.IP 7. 4
+Match the \f(CW\*(Aqd\*(Aq\fR.
+.IP 8. 4
+\&\f(CW\*(Aqf\*(Aq\fR in the regexp doesn't match \f(CW\*(Aqe\*(Aq\fR in the string, so a dead
+end.  Backtrack one character and pick the second alternative in the
+second group \f(CW\*(Aqd\*(Aq\fR.
+.IP 9. 4
+\&\f(CW\*(Aqd\*(Aq\fR matches. The second grouping is satisfied, so set
+\&\f(CW$2\fR to \f(CW\*(Aqd\*(Aq\fR.
+.IP 10. 4
+We are at the end of the regexp, so we are done! We have
+matched \f(CW\*(Aqabcd\*(Aq\fR out of the string \f(CW"abcde"\fR.
+.PP
+There are a couple of things to note about this analysis.  First, the
+third alternative in the second group \f(CW\*(Aqde\*(Aq\fR also allows a match, but we
+stopped before we got to it \- at a given character position, leftmost
+wins.  Second, we were able to get a match at the first character
+position of the string \f(CW\*(Aqa\*(Aq\fR.  If there were no matches at the first
+position, Perl would move to the second character position \f(CW\*(Aqb\*(Aq\fR and
+attempt the match all over again.  Only when all possible paths at all
+possible character positions have been exhausted does Perl give
+up and declare \f(CW\*(C`$string\ =~\ /(abd|abc)(df|d|de)/;\*(C'\fR to be false.
+.PP
+Even with all this work, regexp matching happens remarkably fast.  To
+speed things up, Perl compiles the regexp into a compact sequence of
+opcodes that can often fit inside a processor cache.  When the code is
+executed, these opcodes can then run at full throttle and search very
+quickly.
+.SS "Extracting matches"
+.IX Subsection "Extracting matches"
+The grouping metacharacters \f(CW\*(C`()\*(C'\fR also serve another completely
+different function: they allow the extraction of the parts of a string
+that matched.  This is very useful to find out what matched and for
+text processing in general.  For each grouping, the part that matched
+inside goes into the special variables \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR.  They can be
+used just as ordinary variables:
+.PP
+.Vb 6
+\&    # extract hours, minutes, seconds
+\&    if ($time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/) {    # match hh:mm:ss format
+\&        $hours = $1;
+\&        $minutes = $2;
+\&        $seconds = $3;
+\&    }
+.Ve
+.PP
+Now, we know that in scalar context,
+\&\f(CW\*(C`$time\ =~\ /(\ed\ed):(\ed\ed):(\ed\ed)/\*(C'\fR returns a true or false
+value.  In list context, however, it returns the list of matched values
+\&\f(CW\*(C`($1,$2,$3)\*(C'\fR.  So we could write the code more compactly as
+.PP
+.Vb 2
+\&    # extract hours, minutes, seconds
+\&    ($hours, $minutes, $second) = ($time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/);
+.Ve
+.PP
+If the groupings in a regexp are nested, \f(CW$1\fR gets the group with the
+leftmost opening parenthesis, \f(CW$2\fR the next opening parenthesis,
+\&\fIetc\fR.  Here is a regexp with nested groups:
+.PP
+.Vb 2
+\&    /(ab(cd|ef)((gi)|j))/;
+\&     1  2      34
+.Ve
+.PP
+If this regexp matches, \f(CW$1\fR contains a string starting with
+\&\f(CW\*(Aqab\*(Aq\fR, \f(CW$2\fR is either set to \f(CW\*(Aqcd\*(Aq\fR or \f(CW\*(Aqef\*(Aq\fR, \f(CW$3\fR equals either
+\&\f(CW\*(Aqgi\*(Aq\fR or \f(CW\*(Aqj\*(Aq\fR, and \f(CW$4\fR is either set to \f(CW\*(Aqgi\*(Aq\fR, just like \f(CW$3\fR,
+or it remains undefined.
+.PP
+For convenience, Perl sets \f(CW$+\fR to the string held by the highest numbered
+\&\f(CW$1\fR, \f(CW$2\fR,... that got assigned (and, somewhat related, \f(CW$^N\fR to the
+value of the \f(CW$1\fR, \f(CW$2\fR,... most-recently assigned; \fIi.e.\fR the \f(CW$1\fR,
+\&\f(CW$2\fR,... associated with the rightmost closing parenthesis used in the
+match).
+.SS Backreferences
+.IX Subsection "Backreferences"
+Closely associated with the matching variables \f(CW$1\fR, \f(CW$2\fR, ... are
+the \fIbackreferences\fR \f(CW\*(C`\eg1\*(C'\fR, \f(CW\*(C`\eg2\*(C'\fR,...  Backreferences are simply
+matching variables that can be used \fIinside\fR a regexp.  This is a
+really nice feature; what matches later in a regexp is made to depend on
+what matched earlier in the regexp.  Suppose we wanted to look
+for doubled words in a text, like "the the".  The following regexp finds
+all 3\-letter doubles with a space in between:
+.PP
+.Vb 1
+\&    /\eb(\ew\ew\ew)\es\eg1\eb/;
+.Ve
+.PP
+The grouping assigns a value to \f(CW\*(C`\eg1\*(C'\fR, so that the same 3\-letter sequence
+is used for both parts.
+.PP
+A similar task is to find words consisting of two identical parts:
+.PP
+.Vb 7
+\&    % simple_grep \*(Aq^(\ew\ew\ew\ew|\ew\ew\ew|\ew\ew|\ew)\eg1$\*(Aq /usr/dict/words
+\&    beriberi
+\&    booboo
+\&    coco
+\&    mama
+\&    murmur
+\&    papa
+.Ve
+.PP
+The regexp has a single grouping which considers 4\-letter
+combinations, then 3\-letter combinations, \fIetc\fR., and uses \f(CW\*(C`\eg1\*(C'\fR to look for
+a repeat.  Although \f(CW$1\fR and \f(CW\*(C`\eg1\*(C'\fR represent the same thing, care should be
+taken to use matched variables \f(CW$1\fR, \f(CW$2\fR,... only \fIoutside\fR a regexp
+and backreferences \f(CW\*(C`\eg1\*(C'\fR, \f(CW\*(C`\eg2\*(C'\fR,... only \fIinside\fR a regexp; not doing
+so may lead to surprising and unsatisfactory results.
+.SS "Relative backreferences"
+.IX Subsection "Relative backreferences"
+Counting the opening parentheses to get the correct number for a
+backreference is error-prone as soon as there is more than one
+capturing group.  A more convenient technique became available
+with Perl 5.10: relative backreferences. To refer to the immediately
+preceding capture group one now may write \f(CW\*(C`\eg\-1\*(C'\fR or \f(CW\*(C`\eg{\-1}\*(C'\fR, the next but
+last is available via \f(CW\*(C`\eg\-2\*(C'\fR or \f(CW\*(C`\eg{\-2}\*(C'\fR, and so on.
+.PP
+Another good reason in addition to readability and maintainability
+for using relative backreferences is illustrated by the following example,
+where a simple pattern for matching peculiar strings is used:
+.PP
+.Vb 1
+\&    $a99a = \*(Aq([a\-z])(\ed)\eg2\eg1\*(Aq;   # matches a11a, g22g, x33x, etc.
+.Ve
+.PP
+Now that we have this pattern stored as a handy string, we might feel
+tempted to use it as a part of some other pattern:
+.PP
+.Vb 6
+\&    $line = "code=e99e";
+\&    if ($line =~ /^(\ew+)=$a99a$/){   # unexpected behavior!
+\&        print "$1 is valid\en";
+\&    } else {
+\&        print "bad line: \*(Aq$line\*(Aq\en";
+\&    }
+.Ve
+.PP
+But this doesn't match, at least not the way one might expect. Only
+after inserting the interpolated \f(CW$a99a\fR and looking at the resulting
+full text of the regexp is it obvious that the backreferences have
+backfired. The subexpression \f(CW\*(C`(\ew+)\*(C'\fR has snatched number 1 and
+demoted the groups in \f(CW$a99a\fR by one rank. This can be avoided by
+using relative backreferences:
+.PP
+.Vb 1
+\&    $a99a = \*(Aq([a\-z])(\ed)\eg{\-1}\eg{\-2}\*(Aq;  # safe for being interpolated
+.Ve
+.SS "Named backreferences"
+.IX Subsection "Named backreferences"
+Perl 5.10 also introduced named capture groups and named backreferences.
+To attach a name to a capturing group, you write either
+\&\f(CW\*(C`(?<name>...)\*(C'\fR or \f(CW\*(C`(?\*(Aqname\*(Aq...)\*(C'\fR.  The backreference may
+then be written as \f(CW\*(C`\eg{name}\*(C'\fR.  It is permissible to attach the
+same name to more than one group, but then only the leftmost one of the
+eponymous set can be referenced.  Outside of the pattern a named
+capture group is accessible through the \f(CW\*(C`%+\*(C'\fR hash.
+.PP
+Assuming that we have to match calendar dates which may be given in one
+of the three formats yyyy-mm-dd, mm/dd/yyyy or dd.mm.yyyy, we can write
+three suitable patterns where we use \f(CW\*(Aqd\*(Aq\fR, \f(CW\*(Aqm\*(Aq\fR and \f(CW\*(Aqy\*(Aq\fR respectively as the
+names of the groups capturing the pertaining components of a date. The
+matching operation combines the three patterns as alternatives:
+.PP
+.Vb 8
+\&    $fmt1 = \*(Aq(?<y>\ed\ed\ed\ed)\-(?<m>\ed\ed)\-(?<d>\ed\ed)\*(Aq;
+\&    $fmt2 = \*(Aq(?<m>\ed\ed)/(?<d>\ed\ed)/(?<y>\ed\ed\ed\ed)\*(Aq;
+\&    $fmt3 = \*(Aq(?<d>\ed\ed)\e.(?<m>\ed\ed)\e.(?<y>\ed\ed\ed\ed)\*(Aq;
+\&    for my $d (qw(2006\-10\-21 15.01.2007 10/31/2005)) {
+\&        if ( $d =~ m{$fmt1|$fmt2|$fmt3} ){
+\&            print "day=$+{d} month=$+{m} year=$+{y}\en";
+\&        }
+\&    }
+.Ve
+.PP
+If any of the alternatives matches, the hash \f(CW\*(C`%+\*(C'\fR is bound to contain the
+three key-value pairs.
+.SS "Alternative capture group numbering"
+.IX Subsection "Alternative capture group numbering"
+Yet another capturing group numbering technique (also as from Perl 5.10)
+deals with the problem of referring to groups within a set of alternatives.
+Consider a pattern for matching a time of the day, civil or military style:
+.PP
+.Vb 3
+\&    if ( $time =~ /(\ed\ed|\ed):(\ed\ed)|(\ed\ed)(\ed\ed)/ ){
+\&        # process hour and minute
+\&    }
+.Ve
+.PP
+Processing the results requires an additional if statement to determine
+whether \f(CW$1\fR and \f(CW$2\fR or \f(CW$3\fR and \f(CW$4\fR contain the goodies. It would
+be easier if we could use group numbers 1 and 2 in second alternative as
+well, and this is exactly what the parenthesized construct \f(CW\*(C`(?|...)\*(C'\fR,
+set around an alternative achieves. Here is an extended version of the
+previous pattern:
+.PP
+.Vb 3
+\&  if($time =~ /(?|(\ed\ed|\ed):(\ed\ed)|(\ed\ed)(\ed\ed))\es+([A\-Z][A\-Z][A\-Z])/){
+\&      print "hour=$1 minute=$2 zone=$3\en";
+\&  }
+.Ve
+.PP
+Within the alternative numbering group, group numbers start at the same
+position for each alternative. After the group, numbering continues
+with one higher than the maximum reached across all the alternatives.
+.SS "Position information"
+.IX Subsection "Position information"
+In addition to what was matched, Perl also provides the
+positions of what was matched as contents of the \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR
+arrays. \f(CW\*(C`$\-[0]\*(C'\fR is the position of the start of the entire match and
+\&\f(CW$+[0]\fR is the position of the end. Similarly, \f(CW\*(C`$\-[n]\*(C'\fR is the
+position of the start of the \f(CW$n\fR match and \f(CW$+[n]\fR is the position
+of the end. If \f(CW$n\fR is undefined, so are \f(CW\*(C`$\-[n]\*(C'\fR and \f(CW$+[n]\fR. Then
+this code
+.PP
+.Vb 6
+\&    $x = "Mmm...donut, thought Homer";
+\&    $x =~ /^(Mmm|Yech)\e.\e.\e.(donut|peas)/; # matches
+\&    foreach $exp (1..$#\-) {
+\&        no strict \*(Aqrefs\*(Aq;
+\&        print "Match $exp: \*(Aq$$exp\*(Aq at position ($\-[$exp],$+[$exp])\en";
+\&    }
+.Ve
+.PP
+prints
+.PP
+.Vb 2
+\&    Match 1: \*(AqMmm\*(Aq at position (0,3)
+\&    Match 2: \*(Aqdonut\*(Aq at position (6,11)
+.Ve
+.PP
+Even if there are no groupings in a regexp, it is still possible to
+find out what exactly matched in a string.  If you use them, Perl
+will set \f(CW\*(C`$\`\*(C'\fR to the part of the string before the match, will set \f(CW$&\fR
+to the part of the string that matched, and will set \f(CW\*(C`$\*(Aq\*(C'\fR to the part
+of the string after the match.  An example:
+.PP
+.Vb 3
+\&    $x = "the cat caught the mouse";
+\&    $x =~ /cat/;  # $\` = \*(Aqthe \*(Aq, $& = \*(Aqcat\*(Aq, $\*(Aq = \*(Aq caught the mouse\*(Aq
+\&    $x =~ /the/;  # $\` = \*(Aq\*(Aq, $& = \*(Aqthe\*(Aq, $\*(Aq = \*(Aq cat caught the mouse\*(Aq
+.Ve
+.PP
+In the second match, \f(CW\*(C`$\`\*(C'\fR equals \f(CW\*(Aq\*(Aq\fR because the regexp matched at the
+first character position in the string and stopped; it never saw the
+second "the".
+.PP
+If your code is to run on Perl versions earlier than
+5.20, it is worthwhile to note that using \f(CW\*(C`$\`\*(C'\fR and \f(CW\*(C`$\*(Aq\*(C'\fR
+slows down regexp matching quite a bit, while \f(CW$&\fR slows it down to a
+lesser extent, because if they are used in one regexp in a program,
+they are generated for \fIall\fR regexps in the program.  So if raw
+performance is a goal of your application, they should be avoided.
+If you need to extract the corresponding substrings, use \f(CW\*(C`@\-\*(C'\fR and
+\&\f(CW\*(C`@+\*(C'\fR instead:
+.PP
+.Vb 3
+\&    $\` is the same as substr( $x, 0, $\-[0] )
+\&    $& is the same as substr( $x, $\-[0], $+[0]\-$\-[0] )
+\&    $\*(Aq is the same as substr( $x, $+[0] )
+.Ve
+.PP
+As of Perl 5.10, the \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR and \f(CW\*(C`${^POSTMATCH}\*(C'\fR
+variables may be used.  These are only set if the \f(CW\*(C`/p\*(C'\fR modifier is
+present.  Consequently they do not penalize the rest of the program.  In
+Perl 5.20, \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR and \f(CW\*(C`${^POSTMATCH}\*(C'\fR are available
+whether the \f(CW\*(C`/p\*(C'\fR has been used or not (the modifier is ignored), and
+\&\f(CW\*(C`$\`\*(C'\fR, \f(CW\*(C`$\*(Aq\*(C'\fR and \f(CW$&\fR do not cause any speed difference.
+.SS "Non-capturing groupings"
+.IX Subsection "Non-capturing groupings"
+A group that is required to bundle a set of alternatives may or may not be
+useful as a capturing group.  If it isn't, it just creates a superfluous
+addition to the set of available capture group values, inside as well as
+outside the regexp.  Non-capturing groupings, denoted by \f(CW\*(C`(?:regexp)\*(C'\fR,
+still allow the regexp to be treated as a single unit, but don't establish
+a capturing group at the same time.  Both capturing and non-capturing
+groupings are allowed to co-exist in the same regexp.  Because there is
+no extraction, non-capturing groupings are faster than capturing
+groupings.  Non-capturing groupings are also handy for choosing exactly
+which parts of a regexp are to be extracted to matching variables:
+.PP
+.Vb 2
+\&    # match a number, $1\-$4 are set, but we only want $1
+\&    /([+\-]?\e *(\ed+(\e.\ed*)?|\e.\ed+)([eE][+\-]?\ed+)?)/;
+\&
+\&    # match a number faster , only $1 is set
+\&    /([+\-]?\e *(?:\ed+(?:\e.\ed*)?|\e.\ed+)(?:[eE][+\-]?\ed+)?)/;
+\&
+\&    # match a number, get $1 = whole number, $2 = exponent
+\&    /([+\-]?\e *(?:\ed+(?:\e.\ed*)?|\e.\ed+)(?:[eE]([+\-]?\ed+))?)/;
+.Ve
+.PP
+Non-capturing groupings are also useful for removing nuisance
+elements gathered from a split operation where parentheses are
+required for some reason:
+.PP
+.Vb 3
+\&    $x = \*(Aq12aba34ba5\*(Aq;
+\&    @num = split /(a|b)+/, $x;    # @num = (\*(Aq12\*(Aq,\*(Aqa\*(Aq,\*(Aq34\*(Aq,\*(Aqa\*(Aq,\*(Aq5\*(Aq)
+\&    @num = split /(?:a|b)+/, $x;  # @num = (\*(Aq12\*(Aq,\*(Aq34\*(Aq,\*(Aq5\*(Aq)
+.Ve
+.PP
+In Perl 5.22 and later, all groups within a regexp can be set to
+non-capturing by using the new \f(CW\*(C`/n\*(C'\fR flag:
+.PP
+.Vb 1
+\&    "hello" =~ /(hi|hello)/n; # $1 is not set!
+.Ve
+.PP
+See "n" in perlre for more information.
+.SS "Matching repetitions"
+.IX Subsection "Matching repetitions"
+The examples in the previous section display an annoying weakness.  We
+were only matching 3\-letter words, or chunks of words of 4 letters or
+less.  We'd like to be able to match words or, more generally, strings
+of any length, without writing out tedious alternatives like
+\&\f(CW\*(C`\ew\ew\ew\ew|\ew\ew\ew|\ew\ew|\ew\*(C'\fR.
+.PP
+This is exactly the problem the \fIquantifier\fR metacharacters \f(CW\*(Aq?\*(Aq\fR,
+\&\f(CW\*(Aq*\*(Aq\fR, \f(CW\*(Aq+\*(Aq\fR, and \f(CW\*(C`{}\*(C'\fR were created for.  They allow us to delimit the
+number of repeats for a portion of a regexp we consider to be a
+match.  Quantifiers are put immediately after the character, character
+class, or grouping that we want to specify.  They have the following
+meanings:
+.IP \(bu 4
+\&\f(CW\*(C`a?\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 1 or 0 times
+.IP \(bu 4
+\&\f(CW\*(C`a*\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 0 or more times, \fIi.e.\fR, any number of times
+.IP \(bu 4
+\&\f(CW\*(C`a+\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 1 or more times, \fIi.e.\fR, at least once
+.IP \(bu 4
+\&\f(CW\*(C`a{n,m}\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR times, but not more than \f(CW\*(C`m\*(C'\fR
+times.
+.IP \(bu 4
+\&\f(CW\*(C`a{n,}\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR or more times
+.IP \(bu 4
+\&\f(CW\*(C`a{,n}\*(C'\fR means: match at most \f(CW\*(C`n\*(C'\fR times, or fewer
+.IP \(bu 4
+\&\f(CW\*(C`a{n}\*(C'\fR means: match exactly \f(CW\*(C`n\*(C'\fR times
+.PP
+If you like, you can add blanks (tab or space characters) within the
+braces, but adjacent to them, and/or next to the comma (if any).
+.PP
+Here are some examples:
+.PP
+.Vb 10
+\&    /[a\-z]+\es+\ed*/;  # match a lowercase word, at least one space, and
+\&                     # any number of digits
+\&    /(\ew+)\es+\eg1/;    # match doubled words of arbitrary length
+\&    /y(es)?/i;       # matches \*(Aqy\*(Aq, \*(AqY\*(Aq, or a case\-insensitive \*(Aqyes\*(Aq
+\&    $year =~ /^\ed{2,4}$/;  # make sure year is at least 2 but not more
+\&                           # than 4 digits
+\&    $year =~ /^\ed{ 2, 4 }$/;    # Same; for those who like wide open
+\&                                # spaces.
+\&    $year =~ /^\ed{2, 4}$/;      # Same.
+\&    $year =~ /^\ed{4}$|^\ed{2}$/; # better match; throw out 3\-digit dates
+\&    $year =~ /^\ed{2}(\ed{2})?$/; # same thing written differently.
+\&                                # However, this captures the last two
+\&                                # digits in $1 and the other does not.
+\&
+\&    % simple_grep \*(Aq^(\ew+)\eg1$\*(Aq /usr/dict/words   # isn\*(Aqt this easier?
+\&    beriberi
+\&    booboo
+\&    coco
+\&    mama
+\&    murmur
+\&    papa
+.Ve
+.PP
+For all of these quantifiers, Perl will try to match as much of the
+string as possible, while still allowing the regexp to succeed.  Thus
+with \f(CW\*(C`/a?.../\*(C'\fR, Perl will first try to match the regexp with the \f(CW\*(Aqa\*(Aq\fR
+present; if that fails, Perl will try to match the regexp without the
+\&\f(CW\*(Aqa\*(Aq\fR present.  For the quantifier \f(CW\*(Aq*\*(Aq\fR, we get the following:
+.PP
+.Vb 5
+\&    $x = "the cat in the hat";
+\&    $x =~ /^(.*)(cat)(.*)$/; # matches,
+\&                             # $1 = \*(Aqthe \*(Aq
+\&                             # $2 = \*(Aqcat\*(Aq
+\&                             # $3 = \*(Aq in the hat\*(Aq
+.Ve
+.PP
+Which is what we might expect, the match finds the only \f(CW\*(C`cat\*(C'\fR in the
+string and locks onto it.  Consider, however, this regexp:
+.PP
+.Vb 4
+\&    $x =~ /^(.*)(at)(.*)$/; # matches,
+\&                            # $1 = \*(Aqthe cat in the h\*(Aq
+\&                            # $2 = \*(Aqat\*(Aq
+\&                            # $3 = \*(Aq\*(Aq   (0 characters match)
+.Ve
+.PP
+One might initially guess that Perl would find the \f(CW\*(C`at\*(C'\fR in \f(CW\*(C`cat\*(C'\fR and
+stop there, but that wouldn't give the longest possible string to the
+first quantifier \f(CW\*(C`.*\*(C'\fR.  Instead, the first quantifier \f(CW\*(C`.*\*(C'\fR grabs as
+much of the string as possible while still having the regexp match.  In
+this example, that means having the \f(CW\*(C`at\*(C'\fR sequence with the final \f(CW\*(C`at\*(C'\fR
+in the string.  The other important principle illustrated here is that,
+when there are two or more elements in a regexp, the \fIleftmost\fR
+quantifier, if there is one, gets to grab as much of the string as
+possible, leaving the rest of the regexp to fight over scraps.  Thus in
+our example, the first quantifier \f(CW\*(C`.*\*(C'\fR grabs most of the string, while
+the second quantifier \f(CW\*(C`.*\*(C'\fR gets the empty string.   Quantifiers that
+grab as much of the string as possible are called \fImaximal match\fR or
+\&\fIgreedy\fR quantifiers.
+.PP
+When a regexp can match a string in several different ways, we can use
+the principles above to predict which way the regexp will match:
+.IP \(bu 4
+Principle 0: Taken as a whole, any regexp will be matched at the
+earliest possible position in the string.
+.IP \(bu 4
+Principle 1: In an alternation \f(CW\*(C`a|b|c...\*(C'\fR, the leftmost alternative
+that allows a match for the whole regexp will be the one used.
+.IP \(bu 4
+Principle 2: The maximal matching quantifiers \f(CW\*(Aq?\*(Aq\fR, \f(CW\*(Aq*\*(Aq\fR, \f(CW\*(Aq+\*(Aq\fR and
+\&\f(CW\*(C`{n,m}\*(C'\fR will in general match as much of the string as possible while
+still allowing the whole regexp to match.
+.IP \(bu 4
+Principle 3: If there are two or more elements in a regexp, the
+leftmost greedy quantifier, if any, will match as much of the string
+as possible while still allowing the whole regexp to match.  The next
+leftmost greedy quantifier, if any, will try to match as much of the
+string remaining available to it as possible, while still allowing the
+whole regexp to match.  And so on, until all the regexp elements are
+satisfied.
+.PP
+As we have seen above, Principle 0 overrides the others. The regexp
+will be matched as early as possible, with the other principles
+determining how the regexp matches at that earliest character
+position.
+.PP
+Here is an example of these principles in action:
+.PP
+.Vb 5
+\&    $x = "The programming republic of Perl";
+\&    $x =~ /^(.+)(e|r)(.*)$/;  # matches,
+\&                              # $1 = \*(AqThe programming republic of Pe\*(Aq
+\&                              # $2 = \*(Aqr\*(Aq
+\&                              # $3 = \*(Aql\*(Aq
+.Ve
+.PP
+This regexp matches at the earliest string position, \f(CW\*(AqT\*(Aq\fR.  One
+might think that \f(CW\*(Aqe\*(Aq\fR, being leftmost in the alternation, would be
+matched, but \f(CW\*(Aqr\*(Aq\fR produces the longest string in the first quantifier.
+.PP
+.Vb 3
+\&    $x =~ /(m{1,2})(.*)$/;  # matches,
+\&                            # $1 = \*(Aqmm\*(Aq
+\&                            # $2 = \*(Aqing republic of Perl\*(Aq
+.Ve
+.PP
+Here, The earliest possible match is at the first \f(CW\*(Aqm\*(Aq\fR in
+\&\f(CW\*(C`programming\*(C'\fR. \f(CW\*(C`m{1,2}\*(C'\fR is the first quantifier, so it gets to match
+a maximal \f(CW\*(C`mm\*(C'\fR.
+.PP
+.Vb 3
+\&    $x =~ /.*(m{1,2})(.*)$/;  # matches,
+\&                              # $1 = \*(Aqm\*(Aq
+\&                              # $2 = \*(Aqing republic of Perl\*(Aq
+.Ve
+.PP
+Here, the regexp matches at the start of the string. The first
+quantifier \f(CW\*(C`.*\*(C'\fR grabs as much as possible, leaving just a single
+\&\f(CW\*(Aqm\*(Aq\fR for the second quantifier \f(CW\*(C`m{1,2}\*(C'\fR.
+.PP
+.Vb 4
+\&    $x =~ /(.?)(m{1,2})(.*)$/;  # matches,
+\&                                # $1 = \*(Aqa\*(Aq
+\&                                # $2 = \*(Aqmm\*(Aq
+\&                                # $3 = \*(Aqing republic of Perl\*(Aq
+.Ve
+.PP
+Here, \f(CW\*(C`.?\*(C'\fR eats its maximal one character at the earliest possible
+position in the string, \f(CW\*(Aqa\*(Aq\fR in \f(CW\*(C`programming\*(C'\fR, leaving \f(CW\*(C`m{1,2}\*(C'\fR
+the opportunity to match both \f(CW\*(Aqm\*(Aq\fR's. Finally,
+.PP
+.Vb 1
+\&    "aXXXb" =~ /(X*)/; # matches with $1 = \*(Aq\*(Aq
+.Ve
+.PP
+because it can match zero copies of \f(CW\*(AqX\*(Aq\fR at the beginning of the
+string.  If you definitely want to match at least one \f(CW\*(AqX\*(Aq\fR, use
+\&\f(CW\*(C`X+\*(C'\fR, not \f(CW\*(C`X*\*(C'\fR.
+.PP
+Sometimes greed is not good.  At times, we would like quantifiers to
+match a \fIminimal\fR piece of string, rather than a maximal piece.  For
+this purpose, Larry Wall created the \fIminimal match\fR or
+\&\fInon-greedy\fR quantifiers \f(CW\*(C`??\*(C'\fR, \f(CW\*(C`*?\*(C'\fR, \f(CW\*(C`+?\*(C'\fR, and \f(CW\*(C`{}?\*(C'\fR.  These are
+the usual quantifiers with a \f(CW\*(Aq?\*(Aq\fR appended to them.  They have the
+following meanings:
+.IP \(bu 4
+\&\f(CW\*(C`a??\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 0 or 1 times. Try 0 first, then 1.
+.IP \(bu 4
+\&\f(CW\*(C`a*?\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 0 or more times, \fIi.e.\fR, any number of times,
+but as few times as possible
+.IP \(bu 4
+\&\f(CW\*(C`a+?\*(C'\fR means: match \f(CW\*(Aqa\*(Aq\fR 1 or more times, \fIi.e.\fR, at least once, but
+as few times as possible
+.IP \(bu 4
+\&\f(CW\*(C`a{n,m}?\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR times, not more than \f(CW\*(C`m\*(C'\fR
+times, as few times as possible
+.IP \(bu 4
+\&\f(CW\*(C`a{n,}?\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR times, but as few times as
+possible
+.IP \(bu 4
+\&\f(CW\*(C`a{,n}?\*(C'\fR means: match at most \f(CW\*(C`n\*(C'\fR times, but as few times as
+possible
+.IP \(bu 4
+\&\f(CW\*(C`a{n}?\*(C'\fR means: match exactly \f(CW\*(C`n\*(C'\fR times.  Because we match exactly
+\&\f(CW\*(C`n\*(C'\fR times, \f(CW\*(C`a{n}?\*(C'\fR is equivalent to \f(CW\*(C`a{n}\*(C'\fR and is just there for
+notational consistency.
+.PP
+Let's look at the example above, but with minimal quantifiers:
+.PP
+.Vb 5
+\&    $x = "The programming republic of Perl";
+\&    $x =~ /^(.+?)(e|r)(.*)$/; # matches,
+\&                              # $1 = \*(AqTh\*(Aq
+\&                              # $2 = \*(Aqe\*(Aq
+\&                              # $3 = \*(Aq programming republic of Perl\*(Aq
+.Ve
+.PP
+The minimal string that will allow both the start of the string \f(CW\*(Aq^\*(Aq\fR
+and the alternation to match is \f(CW\*(C`Th\*(C'\fR, with the alternation \f(CW\*(C`e|r\*(C'\fR
+matching \f(CW\*(Aqe\*(Aq\fR.  The second quantifier \f(CW\*(C`.*\*(C'\fR is free to gobble up the
+rest of the string.
+.PP
+.Vb 3
+\&    $x =~ /(m{1,2}?)(.*?)$/;  # matches,
+\&                              # $1 = \*(Aqm\*(Aq
+\&                              # $2 = \*(Aqming republic of Perl\*(Aq
+.Ve
+.PP
+The first string position that this regexp can match is at the first
+\&\f(CW\*(Aqm\*(Aq\fR in \f(CW\*(C`programming\*(C'\fR. At this position, the minimal \f(CW\*(C`m{1,2}?\*(C'\fR
+matches just one \f(CW\*(Aqm\*(Aq\fR.  Although the second quantifier \f(CW\*(C`.*?\*(C'\fR would
+prefer to match no characters, it is constrained by the end-of-string
+anchor \f(CW\*(Aq$\*(Aq\fR to match the rest of the string.
+.PP
+.Vb 4
+\&    $x =~ /(.*?)(m{1,2}?)(.*)$/;  # matches,
+\&                                  # $1 = \*(AqThe progra\*(Aq
+\&                                  # $2 = \*(Aqm\*(Aq
+\&                                  # $3 = \*(Aqming republic of Perl\*(Aq
+.Ve
+.PP
+In this regexp, you might expect the first minimal quantifier \f(CW\*(C`.*?\*(C'\fR
+to match the empty string, because it is not constrained by a \f(CW\*(Aq^\*(Aq\fR
+anchor to match the beginning of the word.  Principle 0 applies here,
+however.  Because it is possible for the whole regexp to match at the
+start of the string, it \fIwill\fR match at the start of the string.  Thus
+the first quantifier has to match everything up to the first \f(CW\*(Aqm\*(Aq\fR.  The
+second minimal quantifier matches just one \f(CW\*(Aqm\*(Aq\fR and the third
+quantifier matches the rest of the string.
+.PP
+.Vb 4
+\&    $x =~ /(.??)(m{1,2})(.*)$/;  # matches,
+\&                                 # $1 = \*(Aqa\*(Aq
+\&                                 # $2 = \*(Aqmm\*(Aq
+\&                                 # $3 = \*(Aqing republic of Perl\*(Aq
+.Ve
+.PP
+Just as in the previous regexp, the first quantifier \f(CW\*(C`.??\*(C'\fR can match
+earliest at position \f(CW\*(Aqa\*(Aq\fR, so it does.  The second quantifier is
+greedy, so it matches \f(CW\*(C`mm\*(C'\fR, and the third matches the rest of the
+string.
+.PP
+We can modify principle 3 above to take into account non-greedy
+quantifiers:
+.IP \(bu 4
+Principle 3: If there are two or more elements in a regexp, the
+leftmost greedy (non-greedy) quantifier, if any, will match as much
+(little) of the string as possible while still allowing the whole
+regexp to match.  The next leftmost greedy (non-greedy) quantifier, if
+any, will try to match as much (little) of the string remaining
+available to it as possible, while still allowing the whole regexp to
+match.  And so on, until all the regexp elements are satisfied.
+.PP
+Just like alternation, quantifiers are also susceptible to
+backtracking.  Here is a step-by-step analysis of the example
+.PP
+.Vb 5
+\&    $x = "the cat in the hat";
+\&    $x =~ /^(.*)(at)(.*)$/; # matches,
+\&                            # $1 = \*(Aqthe cat in the h\*(Aq
+\&                            # $2 = \*(Aqat\*(Aq
+\&                            # $3 = \*(Aq\*(Aq   (0 matches)
+.Ve
+.IP 1. 4
+Start with the first letter in the string \f(CW\*(Aqt\*(Aq\fR.
+.IP 2. 4
+The first quantifier \f(CW\*(Aq.*\*(Aq\fR starts out by matching the whole
+string \f(CW"the cat in the hat"\fR.
+.IP 3. 4
+\&\f(CW\*(Aqa\*(Aq\fR in the regexp element \f(CW\*(Aqat\*(Aq\fR doesn't match the end
+of the string.  Backtrack one character.
+.IP 4. 4
+\&\f(CW\*(Aqa\*(Aq\fR in the regexp element \f(CW\*(Aqat\*(Aq\fR still doesn't match
+the last letter of the string \f(CW\*(Aqt\*(Aq\fR, so backtrack one more character.
+.IP 5. 4
+Now we can match the \f(CW\*(Aqa\*(Aq\fR and the \f(CW\*(Aqt\*(Aq\fR.
+.IP 6. 4
+Move on to the third element \f(CW\*(Aq.*\*(Aq\fR.  Since we are at the
+end of the string and \f(CW\*(Aq.*\*(Aq\fR can match 0 times, assign it the empty
+string.
+.IP 7. 4
+We are done!
+.PP
+Most of the time, all this moving forward and backtracking happens
+quickly and searching is fast. There are some pathological regexps,
+however, whose execution time exponentially grows with the size of the
+string.  A typical structure that blows up in your face is of the form
+.PP
+.Vb 1
+\&    /(a|b+)*/;
+.Ve
+.PP
+The problem is the nested indeterminate quantifiers.  There are many
+different ways of partitioning a string of length n between the \f(CW\*(Aq+\*(Aq\fR
+and \f(CW\*(Aq*\*(Aq\fR: one repetition with \f(CW\*(C`b+\*(C'\fR of length n, two repetitions with
+the first \f(CW\*(C`b+\*(C'\fR length k and the second with length n\-k, m repetitions
+whose bits add up to length n, \fIetc\fR.  In fact there are an exponential
+number of ways to partition a string as a function of its length.  A
+regexp may get lucky and match early in the process, but if there is
+no match, Perl will try \fIevery\fR possibility before giving up.  So be
+careful with nested \f(CW\*(Aq*\*(Aq\fR's, \f(CW\*(C`{n,m}\*(C'\fR's, and \f(CW\*(Aq+\*(Aq\fR's.  The book
+\&\fIMastering Regular Expressions\fR by Jeffrey Friedl gives a wonderful
+discussion of this and other efficiency issues.
+.SS "Possessive quantifiers"
+.IX Subsection "Possessive quantifiers"
+Backtracking during the relentless search for a match may be a waste
+of time, particularly when the match is bound to fail.  Consider
+the simple pattern
+.PP
+.Vb 1
+\&    /^\ew+\es+\ew+$/; # a word, spaces, a word
+.Ve
+.PP
+Whenever this is applied to a string which doesn't quite meet the
+pattern's expectations such as \f(CW"abc\ \ "\fR or \f(CW"abc\ \ def\ "\fR,
+the regexp engine will backtrack, approximately once for each character
+in the string.  But we know that there is no way around taking \fIall\fR
+of the initial word characters to match the first repetition, that \fIall\fR
+spaces must be eaten by the middle part, and the same goes for the second
+word.
+.PP
+With the introduction of the \fIpossessive quantifiers\fR in Perl 5.10, we
+have a way of instructing the regexp engine not to backtrack, with the
+usual quantifiers with a \f(CW\*(Aq+\*(Aq\fR appended to them.  This makes them greedy as
+well as stingy; once they succeed they won't give anything back to permit
+another solution. They have the following meanings:
+.IP \(bu 4
+\&\f(CW\*(C`a{n,m}+\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR times, not more than \f(CW\*(C`m\*(C'\fR times,
+as many times as possible, and don't give anything up. \f(CW\*(C`a?+\*(C'\fR is short
+for \f(CW\*(C`a{0,1}+\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`a{n,}+\*(C'\fR means: match at least \f(CW\*(C`n\*(C'\fR times, but as many times as possible,
+and don't give anything up. \f(CW\*(C`a++\*(C'\fR is short for \f(CW\*(C`a{1,}+\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`a{,n}+\*(C'\fR means: match as many times as possible up to at most \f(CW\*(C`n\*(C'\fR
+times, and don't give anything up. \f(CW\*(C`a*+\*(C'\fR is short for \f(CW\*(C`a{0,}+\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`a{n}+\*(C'\fR means: match exactly \f(CW\*(C`n\*(C'\fR times.  It is just there for
+notational consistency.
+.PP
+These possessive quantifiers represent a special case of a more general
+concept, the \fIindependent subexpression\fR, see below.
+.PP
+As an example where a possessive quantifier is suitable we consider
+matching a quoted string, as it appears in several programming languages.
+The backslash is used as an escape character that indicates that the
+next character is to be taken literally, as another character for the
+string.  Therefore, after the opening quote, we expect a (possibly
+empty) sequence of alternatives: either some character except an
+unescaped quote or backslash or an escaped character.
+.PP
+.Vb 1
+\&    /"(?:[^"\e\e]++|\e\e.)*+"/;
+.Ve
+.SS "Building a regexp"
+.IX Subsection "Building a regexp"
+At this point, we have all the basic regexp concepts covered, so let's
+give a more involved example of a regular expression.  We will build a
+regexp that matches numbers.
+.PP
+The first task in building a regexp is to decide what we want to match
+and what we want to exclude.  In our case, we want to match both
+integers and floating point numbers and we want to reject any string
+that isn't a number.
+.PP
+The next task is to break the problem down into smaller problems that
+are easily converted into a regexp.
+.PP
+The simplest case is integers.  These consist of a sequence of digits,
+with an optional sign in front.  The digits we can represent with
+\&\f(CW\*(C`\ed+\*(C'\fR and the sign can be matched with \f(CW\*(C`[+\-]\*(C'\fR.  Thus the integer
+regexp is
+.PP
+.Vb 1
+\&    /[+\-]?\ed+/;  # matches integers
+.Ve
+.PP
+A floating point number potentially has a sign, an integral part, a
+decimal point, a fractional part, and an exponent.  One or more of these
+parts is optional, so we need to check out the different
+possibilities.  Floating point numbers which are in proper form include
+123., 0.345, .34, \-1e6, and 25.4E\-72.  As with integers, the sign out
+front is completely optional and can be matched by \f(CW\*(C`[+\-]?\*(C'\fR.  We can
+see that if there is no exponent, floating point numbers must have a
+decimal point, otherwise they are integers.  We might be tempted to
+model these with \f(CW\*(C`\ed*\e.\ed*\*(C'\fR, but this would also match just a single
+decimal point, which is not a number.  So the three cases of floating
+point number without exponent are
+.PP
+.Vb 3
+\&   /[+\-]?\ed+\e./;  # 1., 321., etc.
+\&   /[+\-]?\e.\ed+/;  # .1, .234, etc.
+\&   /[+\-]?\ed+\e.\ed+/;  # 1.0, 30.56, etc.
+.Ve
+.PP
+These can be combined into a single regexp with a three-way alternation:
+.PP
+.Vb 1
+\&   /[+\-]?(\ed+\e.\ed+|\ed+\e.|\e.\ed+)/;  # floating point, no exponent
+.Ve
+.PP
+In this alternation, it is important to put \f(CW\*(Aq\ed+\e.\ed+\*(Aq\fR before
+\&\f(CW\*(Aq\ed+\e.\*(Aq\fR.  If \f(CW\*(Aq\ed+\e.\*(Aq\fR were first, the regexp would happily match that
+and ignore the fractional part of the number.
+.PP
+Now consider floating point numbers with exponents.  The key
+observation here is that \fIboth\fR integers and numbers with decimal
+points are allowed in front of an exponent.  Then exponents, like the
+overall sign, are independent of whether we are matching numbers with
+or without decimal points, and can be "decoupled" from the
+mantissa.  The overall form of the regexp now becomes clear:
+.PP
+.Vb 1
+\&    /^(optional sign)(integer | f.p. mantissa)(optional exponent)$/;
+.Ve
+.PP
+The exponent is an \f(CW\*(Aqe\*(Aq\fR or \f(CW\*(AqE\*(Aq\fR, followed by an integer.  So the
+exponent regexp is
+.PP
+.Vb 1
+\&   /[eE][+\-]?\ed+/;  # exponent
+.Ve
+.PP
+Putting all the parts together, we get a regexp that matches numbers:
+.PP
+.Vb 1
+\&   /^[+\-]?(\ed+\e.\ed+|\ed+\e.|\e.\ed+|\ed+)([eE][+\-]?\ed+)?$/;  # Ta da!
+.Ve
+.PP
+Long regexps like this may impress your friends, but can be hard to
+decipher.  In complex situations like this, the \f(CW\*(C`/x\*(C'\fR modifier for a
+match is invaluable.  It allows one to put nearly arbitrary whitespace
+and comments into a regexp without affecting their meaning.  Using it,
+we can rewrite our "extended" regexp in the more pleasing form
+.PP
+.Vb 10
+\&   /^
+\&      [+\-]?         # first, match an optional sign
+\&      (             # then match integers or f.p. mantissas:
+\&          \ed+\e.\ed+  # mantissa of the form a.b
+\&         |\ed+\e.     # mantissa of the form a.
+\&         |\e.\ed+     # mantissa of the form .b
+\&         |\ed+       # integer of the form a
+\&      )
+\&      ( [eE] [+\-]? \ed+ )?  # finally, optionally match an exponent
+\&   $/x;
+.Ve
+.PP
+If whitespace is mostly irrelevant, how does one include space
+characters in an extended regexp? The answer is to backslash it
+\&\f(CW\*(Aq\e\ \*(Aq\fR or put it in a character class \f(CW\*(C`[\ ]\*(C'\fR.  The same thing
+goes for pound signs: use \f(CW\*(C`\e#\*(C'\fR or \f(CW\*(C`[#]\*(C'\fR.  For instance, Perl allows
+a space between the sign and the mantissa or integer, and we could add
+this to our regexp as follows:
+.PP
+.Vb 10
+\&   /^
+\&      [+\-]?\e *      # first, match an optional sign *and space*
+\&      (             # then match integers or f.p. mantissas:
+\&          \ed+\e.\ed+  # mantissa of the form a.b
+\&         |\ed+\e.     # mantissa of the form a.
+\&         |\e.\ed+     # mantissa of the form .b
+\&         |\ed+       # integer of the form a
+\&      )
+\&      ( [eE] [+\-]? \ed+ )?  # finally, optionally match an exponent
+\&   $/x;
+.Ve
+.PP
+In this form, it is easier to see a way to simplify the
+alternation.  Alternatives 1, 2, and 4 all start with \f(CW\*(C`\ed+\*(C'\fR, so it
+could be factored out:
+.PP
+.Vb 11
+\&   /^
+\&      [+\-]?\e *      # first, match an optional sign
+\&      (             # then match integers or f.p. mantissas:
+\&          \ed+       # start out with a ...
+\&          (
+\&              \e.\ed* # mantissa of the form a.b or a.
+\&          )?        # ? takes care of integers of the form a
+\&         |\e.\ed+     # mantissa of the form .b
+\&      )
+\&      ( [eE] [+\-]? \ed+ )?  # finally, optionally match an exponent
+\&   $/x;
+.Ve
+.PP
+Starting in Perl v5.26, specifying \f(CW\*(C`/xx\*(C'\fR changes the square-bracketed
+portions of a pattern to ignore tabs and space characters unless they
+are escaped by preceding them with a backslash.  So, we could write
+.PP
+.Vb 11
+\&   /^
+\&      [ + \- ]?\e *   # first, match an optional sign
+\&      (             # then match integers or f.p. mantissas:
+\&          \ed+       # start out with a ...
+\&          (
+\&              \e.\ed* # mantissa of the form a.b or a.
+\&          )?        # ? takes care of integers of the form a
+\&         |\e.\ed+     # mantissa of the form .b
+\&      )
+\&      ( [ e E ] [ + \- ]? \ed+ )?  # finally, optionally match an exponent
+\&   $/xx;
+.Ve
+.PP
+This doesn't really improve the legibility of this example, but it's
+available in case you want it.  Squashing the pattern down to the
+compact form, we have
+.PP
+.Vb 1
+\&    /^[+\-]?\e *(\ed+(\e.\ed*)?|\e.\ed+)([eE][+\-]?\ed+)?$/;
+.Ve
+.PP
+This is our final regexp.  To recap, we built a regexp by
+.IP \(bu 4
+specifying the task in detail,
+.IP \(bu 4
+breaking down the problem into smaller parts,
+.IP \(bu 4
+translating the small parts into regexps,
+.IP \(bu 4
+combining the regexps,
+.IP \(bu 4
+and optimizing the final combined regexp.
+.PP
+These are also the typical steps involved in writing a computer
+program.  This makes perfect sense, because regular expressions are
+essentially programs written in a little computer language that specifies
+patterns.
+.SS "Using regular expressions in Perl"
+.IX Subsection "Using regular expressions in Perl"
+The last topic of Part 1 briefly covers how regexps are used in Perl
+programs.  Where do they fit into Perl syntax?
+.PP
+We have already introduced the matching operator in its default
+\&\f(CW\*(C`/regexp/\*(C'\fR and arbitrary delimiter \f(CW\*(C`m!regexp!\*(C'\fR forms.  We have used
+the binding operator \f(CW\*(C`=~\*(C'\fR and its negation \f(CW\*(C`!~\*(C'\fR to test for string
+matches.  Associated with the matching operator, we have discussed the
+single line \f(CW\*(C`/s\*(C'\fR, multi-line \f(CW\*(C`/m\*(C'\fR, case-insensitive \f(CW\*(C`/i\*(C'\fR and
+extended \f(CW\*(C`/x\*(C'\fR modifiers.  There are a few more things you might
+want to know about matching operators.
+.PP
+\fIProhibiting substitution\fR
+.IX Subsection "Prohibiting substitution"
+.PP
+If you change \f(CW$pattern\fR after the first substitution happens, Perl
+will ignore it.  If you don't want any substitutions at all, use the
+special delimiter \f(CW\*(C`m\*(Aq\*(Aq\*(C'\fR:
+.PP
+.Vb 4
+\&    @pattern = (\*(AqSeuss\*(Aq);
+\&    while (<>) {
+\&        print if m\*(Aq@pattern\*(Aq;  # matches literal \*(Aq@pattern\*(Aq, not \*(AqSeuss\*(Aq
+\&    }
+.Ve
+.PP
+Similar to strings, \f(CW\*(C`m\*(Aq\*(Aq\*(C'\fR acts like apostrophes on a regexp; all other
+\&\f(CW\*(Aqm\*(Aq\fR delimiters act like quotes.  If the regexp evaluates to the empty string,
+the regexp in the \fIlast successful match\fR is used instead.  So we have
+.PP
+.Vb 2
+\&    "dog" =~ /d/;  # \*(Aqd\*(Aq matches
+\&    "dogbert" =~ //;  # this matches the \*(Aqd\*(Aq regexp used before
+.Ve
+.PP
+\fIGlobal matching\fR
+.IX Subsection "Global matching"
+.PP
+The final two modifiers we will discuss here,
+\&\f(CW\*(C`/g\*(C'\fR and \f(CW\*(C`/c\*(C'\fR, concern multiple matches.
+The modifier \f(CW\*(C`/g\*(C'\fR stands for global matching and allows the
+matching operator to match within a string as many times as possible.
+In scalar context, successive invocations against a string will have
+\&\f(CW\*(C`/g\*(C'\fR jump from match to match, keeping track of position in the
+string as it goes along.  You can get or set the position with the
+\&\f(CWpos()\fR function.
+.PP
+The use of \f(CW\*(C`/g\*(C'\fR is shown in the following example.  Suppose we have
+a string that consists of words separated by spaces.  If we know how
+many words there are in advance, we could extract the words using
+groupings:
+.PP
+.Vb 5
+\&    $x = "cat dog house"; # 3 words
+\&    $x =~ /^\es*(\ew+)\es+(\ew+)\es+(\ew+)\es*$/; # matches,
+\&                                           # $1 = \*(Aqcat\*(Aq
+\&                                           # $2 = \*(Aqdog\*(Aq
+\&                                           # $3 = \*(Aqhouse\*(Aq
+.Ve
+.PP
+But what if we had an indeterminate number of words? This is the sort
+of task \f(CW\*(C`/g\*(C'\fR was made for.  To extract all words, form the simple
+regexp \f(CW\*(C`(\ew+)\*(C'\fR and loop over all matches with \f(CW\*(C`/(\ew+)/g\*(C'\fR:
+.PP
+.Vb 3
+\&    while ($x =~ /(\ew+)/g) {
+\&        print "Word is $1, ends at position ", pos $x, "\en";
+\&    }
+.Ve
+.PP
+prints
+.PP
+.Vb 3
+\&    Word is cat, ends at position 3
+\&    Word is dog, ends at position 7
+\&    Word is house, ends at position 13
+.Ve
+.PP
+A failed match or changing the target string resets the position.  If
+you don't want the position reset after failure to match, add the
+\&\f(CW\*(C`/c\*(C'\fR, as in \f(CW\*(C`/regexp/gc\*(C'\fR.  The current position in the string is
+associated with the string, not the regexp.  This means that different
+strings have different positions and their respective positions can be
+set or read independently.
+.PP
+In list context, \f(CW\*(C`/g\*(C'\fR returns a list of matched groupings, or if
+there are no groupings, a list of matches to the whole regexp.  So if
+we wanted just the words, we could use
+.PP
+.Vb 4
+\&    @words = ($x =~ /(\ew+)/g);  # matches,
+\&                                # $words[0] = \*(Aqcat\*(Aq
+\&                                # $words[1] = \*(Aqdog\*(Aq
+\&                                # $words[2] = \*(Aqhouse\*(Aq
+.Ve
+.PP
+Closely associated with the \f(CW\*(C`/g\*(C'\fR modifier is the \f(CW\*(C`\eG\*(C'\fR anchor.  The
+\&\f(CW\*(C`\eG\*(C'\fR anchor matches at the point where the previous \f(CW\*(C`/g\*(C'\fR match left
+off.  \f(CW\*(C`\eG\*(C'\fR allows us to easily do context-sensitive matching:
+.PP
+.Vb 12
+\&    $metric = 1;  # use metric units
+\&    ...
+\&    $x = <FILE>;  # read in measurement
+\&    $x =~ /^([+\-]?\ed+)\es*/g;  # get magnitude
+\&    $weight = $1;
+\&    if ($metric) { # error checking
+\&        print "Units error!" unless $x =~ /\eGkg\e./g;
+\&    }
+\&    else {
+\&        print "Units error!" unless $x =~ /\eGlbs\e./g;
+\&    }
+\&    $x =~ /\eG\es+(widget|sprocket)/g;  # continue processing
+.Ve
+.PP
+The combination of \f(CW\*(C`/g\*(C'\fR and \f(CW\*(C`\eG\*(C'\fR allows us to process the string a
+bit at a time and use arbitrary Perl logic to decide what to do next.
+Currently, the \f(CW\*(C`\eG\*(C'\fR anchor is only fully supported when used to anchor
+to the start of the pattern.
+.PP
+\&\f(CW\*(C`\eG\*(C'\fR is also invaluable in processing fixed-length records with
+regexps.  Suppose we have a snippet of coding region DNA, encoded as
+base pair letters \f(CW\*(C`ATCGTTGAAT...\*(C'\fR and we want to find all the stop
+codons \f(CW\*(C`TGA\*(C'\fR.  In a coding region, codons are 3\-letter sequences, so
+we can think of the DNA snippet as a sequence of 3\-letter records.  The
+naive regexp
+.PP
+.Vb 3
+\&    # expanded, this is "ATC GTT GAA TGC AAA TGA CAT GAC"
+\&    $dna = "ATCGTTGAATGCAAATGACATGAC";
+\&    $dna =~ /TGA/;
+.Ve
+.PP
+doesn't work; it may match a \f(CW\*(C`TGA\*(C'\fR, but there is no guarantee that
+the match is aligned with codon boundaries, \fIe.g.\fR, the substring
+\&\f(CW\*(C`GTT\ GAA\*(C'\fR gives a match.  A better solution is
+.PP
+.Vb 3
+\&    while ($dna =~ /(\ew\ew\ew)*?TGA/g) {  # note the minimal *?
+\&        print "Got a TGA stop codon at position ", pos $dna, "\en";
+\&    }
+.Ve
+.PP
+which prints
+.PP
+.Vb 2
+\&    Got a TGA stop codon at position 18
+\&    Got a TGA stop codon at position 23
+.Ve
+.PP
+Position 18 is good, but position 23 is bogus.  What happened?
+.PP
+The answer is that our regexp works well until we get past the last
+real match.  Then the regexp will fail to match a synchronized \f(CW\*(C`TGA\*(C'\fR
+and start stepping ahead one character position at a time, not what we
+want.  The solution is to use \f(CW\*(C`\eG\*(C'\fR to anchor the match to the codon
+alignment:
+.PP
+.Vb 3
+\&    while ($dna =~ /\eG(\ew\ew\ew)*?TGA/g) {
+\&        print "Got a TGA stop codon at position ", pos $dna, "\en";
+\&    }
+.Ve
+.PP
+This prints
+.PP
+.Vb 1
+\&    Got a TGA stop codon at position 18
+.Ve
+.PP
+which is the correct answer.  This example illustrates that it is
+important not only to match what is desired, but to reject what is not
+desired.
+.PP
+(There are other regexp modifiers that are available, such as
+\&\f(CW\*(C`/o\*(C'\fR, but their specialized uses are beyond the
+scope of this introduction.  )
+.PP
+\fISearch and replace\fR
+.IX Subsection "Search and replace"
+.PP
+Regular expressions also play a big role in \fIsearch and replace\fR
+operations in Perl.  Search and replace is accomplished with the
+\&\f(CW\*(C`s///\*(C'\fR operator.  The general form is
+\&\f(CW\*(C`s/regexp/replacement/modifiers\*(C'\fR, with everything we know about
+regexps and modifiers applying in this case as well.  The
+\&\fIreplacement\fR is a Perl double-quoted string that replaces in the
+string whatever is matched with the \f(CW\*(C`regexp\*(C'\fR.  The operator \f(CW\*(C`=~\*(C'\fR is
+also used here to associate a string with \f(CW\*(C`s///\*(C'\fR.  If matching
+against \f(CW$_\fR, the \f(CW\*(C`$_\ =~\*(C'\fR can be dropped.  If there is a match,
+\&\f(CW\*(C`s///\*(C'\fR returns the number of substitutions made; otherwise it returns
+false.  Here are a few examples:
+.PP
+.Vb 8
+\&    $x = "Time to feed the cat!";
+\&    $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
+\&    if ($x =~ s/^(Time.*hacker)!$/$1 now!/) {
+\&        $more_insistent = 1;
+\&    }
+\&    $y = "\*(Aqquoted words\*(Aq";
+\&    $y =~ s/^\*(Aq(.*)\*(Aq$/$1/;  # strip single quotes,
+\&                           # $y contains "quoted words"
+.Ve
+.PP
+In the last example, the whole string was matched, but only the part
+inside the single quotes was grouped.  With the \f(CW\*(C`s///\*(C'\fR operator, the
+matched variables \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR. are immediately available for use
+in the replacement expression, so we use \f(CW$1\fR to replace the quoted
+string with just what was quoted.  With the global modifier, \f(CW\*(C`s///g\*(C'\fR
+will search and replace all occurrences of the regexp in the string:
+.PP
+.Vb 6
+\&    $x = "I batted 4 for 4";
+\&    $x =~ s/4/four/;   # doesn\*(Aqt do it all:
+\&                       # $x contains "I batted four for 4"
+\&    $x = "I batted 4 for 4";
+\&    $x =~ s/4/four/g;  # does it all:
+\&                       # $x contains "I batted four for four"
+.Ve
+.PP
+If you prefer "regex" over "regexp" in this tutorial, you could use
+the following program to replace it:
+.PP
+.Vb 9
+\&    % cat > simple_replace
+\&    #!/usr/bin/perl
+\&    $regexp = shift;
+\&    $replacement = shift;
+\&    while (<>) {
+\&        s/$regexp/$replacement/g;
+\&        print;
+\&    }
+\&    ^D
+\&
+\&    % simple_replace regexp regex perlretut.pod
+.Ve
+.PP
+In \f(CW\*(C`simple_replace\*(C'\fR we used the \f(CW\*(C`s///g\*(C'\fR modifier to replace all
+occurrences of the regexp on each line.  (Even though the regular
+expression appears in a loop, Perl is smart enough to compile it
+only once.)  As with \f(CW\*(C`simple_grep\*(C'\fR, both the
+\&\f(CW\*(C`print\*(C'\fR and the \f(CW\*(C`s/$regexp/$replacement/g\*(C'\fR use \f(CW$_\fR implicitly.
+.PP
+If you don't want \f(CW\*(C`s///\*(C'\fR to change your original variable you can use
+the non-destructive substitute modifier, \f(CW\*(C`s///r\*(C'\fR.  This changes the
+behavior so that \f(CW\*(C`s///r\*(C'\fR returns the final substituted string
+(instead of the number of substitutions):
+.PP
+.Vb 3
+\&    $x = "I like dogs.";
+\&    $y = $x =~ s/dogs/cats/r;
+\&    print "$x $y\en";
+.Ve
+.PP
+That example will print "I like dogs. I like cats". Notice the original
+\&\f(CW$x\fR variable has not been affected. The overall
+result of the substitution is instead stored in \f(CW$y\fR. If the
+substitution doesn't affect anything then the original string is
+returned:
+.PP
+.Vb 3
+\&    $x = "I like dogs.";
+\&    $y = $x =~ s/elephants/cougars/r;
+\&    print "$x $y\en"; # prints "I like dogs. I like dogs."
+.Ve
+.PP
+One other interesting thing that the \f(CW\*(C`s///r\*(C'\fR flag allows is chaining
+substitutions:
+.PP
+.Vb 4
+\&    $x = "Cats are great.";
+\&    print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~
+\&        s/Frogs/Hedgehogs/r, "\en";
+\&    # prints "Hedgehogs are great."
+.Ve
+.PP
+A modifier available specifically to search and replace is the
+\&\f(CW\*(C`s///e\*(C'\fR evaluation modifier.  \f(CW\*(C`s///e\*(C'\fR treats the
+replacement text as Perl code, rather than a double-quoted
+string.  The value that the code returns is substituted for the
+matched substring.  \f(CW\*(C`s///e\*(C'\fR is useful if you need to do a bit of
+computation in the process of replacing text.  This example counts
+character frequencies in a line:
+.PP
+.Vb 4
+\&    $x = "Bill the cat";
+\&    $x =~ s/(.)/$chars{$1}++;$1/eg; # final $1 replaces char with itself
+\&    print "frequency of \*(Aq$_\*(Aq is $chars{$_}\en"
+\&        foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars);
+.Ve
+.PP
+This prints
+.PP
+.Vb 9
+\&    frequency of \*(Aq \*(Aq is 2
+\&    frequency of \*(Aqt\*(Aq is 2
+\&    frequency of \*(Aql\*(Aq is 2
+\&    frequency of \*(AqB\*(Aq is 1
+\&    frequency of \*(Aqc\*(Aq is 1
+\&    frequency of \*(Aqe\*(Aq is 1
+\&    frequency of \*(Aqh\*(Aq is 1
+\&    frequency of \*(Aqi\*(Aq is 1
+\&    frequency of \*(Aqa\*(Aq is 1
+.Ve
+.PP
+As with the match \f(CW\*(C`m//\*(C'\fR operator, \f(CW\*(C`s///\*(C'\fR can use other delimiters,
+such as \f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`s{}{}\*(C'\fR, and even \f(CW\*(C`s{}//\*(C'\fR.  If single quotes are
+used \f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR, then the regexp and replacement are
+treated as single-quoted strings and there are no
+variable substitutions.  \f(CW\*(C`s///\*(C'\fR in list context
+returns the same thing as in scalar context, \fIi.e.\fR, the number of
+matches.
+.PP
+\fIThe split function\fR
+.IX Subsection "The split function"
+.PP
+The \f(CWsplit()\fR function is another place where a regexp is used.
+\&\f(CW\*(C`split /regexp/, string, limit\*(C'\fR separates the \f(CW\*(C`string\*(C'\fR operand into
+a list of substrings and returns that list.  The regexp must be designed
+to match whatever constitutes the separators for the desired substrings.
+The \f(CW\*(C`limit\*(C'\fR, if present, constrains splitting into no more than \f(CW\*(C`limit\*(C'\fR
+number of strings.  For example, to split a string into words, use
+.PP
+.Vb 4
+\&    $x = "Calvin and Hobbes";
+\&    @words = split /\es+/, $x;  # $word[0] = \*(AqCalvin\*(Aq
+\&                               # $word[1] = \*(Aqand\*(Aq
+\&                               # $word[2] = \*(AqHobbes\*(Aq
+.Ve
+.PP
+If the empty regexp \f(CW\*(C`//\*(C'\fR is used, the regexp always matches and
+the string is split into individual characters.  If the regexp has
+groupings, then the resulting list contains the matched substrings from the
+groupings as well.  For instance,
+.PP
+.Vb 12
+\&    $x = "/usr/bin/perl";
+\&    @dirs = split m!/!, $x;  # $dirs[0] = \*(Aq\*(Aq
+\&                             # $dirs[1] = \*(Aqusr\*(Aq
+\&                             # $dirs[2] = \*(Aqbin\*(Aq
+\&                             # $dirs[3] = \*(Aqperl\*(Aq
+\&    @parts = split m!(/)!, $x;  # $parts[0] = \*(Aq\*(Aq
+\&                                # $parts[1] = \*(Aq/\*(Aq
+\&                                # $parts[2] = \*(Aqusr\*(Aq
+\&                                # $parts[3] = \*(Aq/\*(Aq
+\&                                # $parts[4] = \*(Aqbin\*(Aq
+\&                                # $parts[5] = \*(Aq/\*(Aq
+\&                                # $parts[6] = \*(Aqperl\*(Aq
+.Ve
+.PP
+Since the first character of \f(CW$x\fR matched the regexp, \f(CW\*(C`split\*(C'\fR prepended
+an empty initial element to the list.
+.PP
+If you have read this far, congratulations! You now have all the basic
+tools needed to use regular expressions to solve a wide range of text
+processing problems.  If this is your first time through the tutorial,
+why not stop here and play around with regexps a while....  Part\ 2
+concerns the more esoteric aspects of regular expressions and those
+concepts certainly aren't needed right at the start.
+.SH "Part 2: Power tools"
+.IX Header "Part 2: Power tools"
+OK, you know the basics of regexps and you want to know more.  If
+matching regular expressions is analogous to a walk in the woods, then
+the tools discussed in Part 1 are analogous to topo maps and a
+compass, basic tools we use all the time.  Most of the tools in part 2
+are analogous to flare guns and satellite phones.  They aren't used
+too often on a hike, but when we are stuck, they can be invaluable.
+.PP
+What follows are the more advanced, less used, or sometimes esoteric
+capabilities of Perl regexps.  In Part 2, we will assume you are
+comfortable with the basics and concentrate on the advanced features.
+.SS "More on characters, strings, and character classes"
+.IX Subsection "More on characters, strings, and character classes"
+There are a number of escape sequences and character classes that we
+haven't covered yet.
+.PP
+There are several escape sequences that convert characters or strings
+between upper and lower case, and they are also available within
+patterns.  \f(CW\*(C`\el\*(C'\fR and \f(CW\*(C`\eu\*(C'\fR convert the next character to lower or
+upper case, respectively:
+.PP
+.Vb 4
+\&    $x = "perl";
+\&    $string =~ /\eu$x/;  # matches \*(AqPerl\*(Aq in $string
+\&    $x = "M(rs?|s)\e\e."; # note the double backslash
+\&    $string =~ /\el$x/;  # matches \*(Aqmr.\*(Aq, \*(Aqmrs.\*(Aq, and \*(Aqms.\*(Aq,
+.Ve
+.PP
+A \f(CW\*(C`\eL\*(C'\fR or \f(CW\*(C`\eU\*(C'\fR indicates a lasting conversion of case, until
+terminated by \f(CW\*(C`\eE\*(C'\fR or thrown over by another \f(CW\*(C`\eU\*(C'\fR or \f(CW\*(C`\eL\*(C'\fR:
+.PP
+.Vb 4
+\&    $x = "This word is in lower case:\eL SHOUT\eE";
+\&    $x =~ /shout/;       # matches
+\&    $x = "I STILL KEYPUNCH CARDS FOR MY 360";
+\&    $x =~ /\eUkeypunch/;  # matches punch card string
+.Ve
+.PP
+If there is no \f(CW\*(C`\eE\*(C'\fR, case is converted until the end of the
+string. The regexps \f(CW\*(C`\eL\eu$word\*(C'\fR or \f(CW\*(C`\eu\eL$word\*(C'\fR convert the first
+character of \f(CW$word\fR to uppercase and the rest of the characters to
+lowercase.  (Beyond ASCII characters, it gets somewhat more complicated;
+\&\f(CW\*(C`\eu\*(C'\fR actually performs \fItitlecase\fR mapping, which for most characters
+is the same as uppercase, but not for all; see
+<https://unicode.org/faq/casemap_charprop.html#4>.)
+.PP
+Control characters can be escaped with \f(CW\*(C`\ec\*(C'\fR, so that a control-Z
+character would be matched with \f(CW\*(C`\ecZ\*(C'\fR.  The escape sequence
+\&\f(CW\*(C`\eQ\*(C'\fR...\f(CW\*(C`\eE\*(C'\fR quotes, or protects most non-alphabetic characters.   For
+instance,
+.PP
+.Vb 2
+\&    $x = "\eQThat !^*&%~& cat!";
+\&    $x =~ /\eQ!^*&%~&\eE/;  # check for rough language
+.Ve
+.PP
+It does not protect \f(CW\*(Aq$\*(Aq\fR or \f(CW\*(Aq@\*(Aq\fR, so that variables can still be
+substituted.
+.PP
+\&\f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR are actually part of
+double-quotish syntax, and not part of regexp syntax proper.  They will
+work if they appear in a regular expression embedded directly in a
+program, but not when contained in a string that is interpolated in a
+pattern.
+.PP
+Perl regexps can handle more than just the
+standard ASCII character set.  Perl supports \fIUnicode\fR, a standard
+for representing the alphabets from virtually all of the world's written
+languages, and a host of symbols.  Perl's text strings are Unicode strings, so
+they can contain characters with a value (codepoint or character number) higher
+than 255.
+.PP
+What does this mean for regexps? Well, regexp users don't need to know
+much about Perl's internal representation of strings.  But they do need
+to know 1) how to represent Unicode characters in a regexp and 2) that
+a matching operation will treat the string to be searched as a sequence
+of characters, not bytes.  The answer to 1) is that Unicode characters
+greater than \f(CWchr(255)\fR are represented using the \f(CW\*(C`\ex{hex}\*(C'\fR notation, because
+\&\f(CW\*(C`\ex\*(C'\fR\fIXY\fR (without curly braces and \fIXY\fR are two hex digits) doesn't
+go further than 255.  (Starting in Perl 5.14, if you're an octal fan,
+you can also use \f(CW\*(C`\eo{oct}\*(C'\fR.)
+.PP
+.Vb 2
+\&    /\ex{263a}/;   # match a Unicode smiley face :)
+\&    /\ex{ 263a }/; # Same
+.Ve
+.PP
+\&\fBNOTE\fR: In Perl 5.6.0 it used to be that one needed to say \f(CW\*(C`use
+utf8\*(C'\fR to use any Unicode features.  This is no longer the case: for
+almost all Unicode processing, the explicit \f(CW\*(C`utf8\*(C'\fR pragma is not
+needed.  (The only case where it matters is if your Perl script is in
+Unicode and encoded in UTF\-8, then an explicit \f(CW\*(C`use utf8\*(C'\fR is needed.)
+.PP
+Figuring out the hexadecimal sequence of a Unicode character you want
+or deciphering someone else's hexadecimal Unicode regexp is about as
+much fun as programming in machine code.  So another way to specify
+Unicode characters is to use the \fInamed character\fR escape
+sequence \f(CW\*(C`\eN{\fR\f(CIname\fR\f(CW}\*(C'\fR.  \fIname\fR is a name for the Unicode character, as
+specified in the Unicode standard.  For instance, if we wanted to
+represent or match the astrological sign for the planet Mercury, we
+could use
+.PP
+.Vb 3
+\&    $x = "abc\eN{MERCURY}def";
+\&    $x =~ /\eN{MERCURY}/;   # matches
+\&    $x =~ /\eN{ MERCURY }/; # Also matches
+.Ve
+.PP
+One can also use "short" names:
+.PP
+.Vb 2
+\&    print "\eN{GREEK SMALL LETTER SIGMA} is called sigma.\en";
+\&    print "\eN{greek:Sigma} is an upper\-case sigma.\en";
+.Ve
+.PP
+You can also restrict names to a certain alphabet by specifying the
+charnames pragma:
+.PP
+.Vb 2
+\&    use charnames qw(greek);
+\&    print "\eN{sigma} is Greek sigma\en";
+.Ve
+.PP
+An index of character names is available on-line from the Unicode
+Consortium, <https://www.unicode.org/charts/charindex.html>; explanatory
+material with links to other resources at
+<https://www.unicode.org/standard/where>.
+.PP
+Starting in Perl v5.32, an alternative to \f(CW\*(C`\eN{...}\*(C'\fR for full names is
+available, and that is to say
+.PP
+.Vb 1
+\& /\ep{Name=greek small letter sigma}/
+.Ve
+.PP
+The casing of the character name is irrelevant when used in \f(CW\*(C`\ep{}\*(C'\fR, as
+are most spaces, underscores and hyphens.  (A few outlier characters
+cause problems with ignoring all of them always.  The details (which you
+can look up when you get more proficient, and if ever needed) are in
+<https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>).
+.PP
+The answer to requirement 2) is that a regexp (mostly)
+uses Unicode characters.  The "mostly" is for messy backward
+compatibility reasons, but starting in Perl 5.14, any regexp compiled in
+the scope of a \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR (which is automatically
+turned on within the scope of a \f(CW\*(C`use v5.12\*(C'\fR or higher) will turn that
+"mostly" into "always".  If you want to handle Unicode properly, you
+should ensure that \f(CW\*(Aqunicode_strings\*(Aq\fR is turned on.
+Internally, this is encoded to bytes using either UTF\-8 or a native 8
+bit encoding, depending on the history of the string, but conceptually
+it is a sequence of characters, not bytes. See perlunitut for a
+tutorial about that.
+.PP
+Let us now discuss Unicode character classes, most usually called
+"character properties".  These are represented by the \f(CW\*(C`\ep{\fR\f(CIname\fR\f(CW}\*(C'\fR
+escape sequence.  The negation of this is \f(CW\*(C`\eP{\fR\f(CIname\fR\f(CW}\*(C'\fR.  For example,
+to match lower and uppercase characters,
+.PP
+.Vb 5
+\&    $x = "BOB";
+\&    $x =~ /^\ep{IsUpper}/;   # matches, uppercase char class
+\&    $x =~ /^\eP{IsUpper}/;   # doesn\*(Aqt match, char class sans uppercase
+\&    $x =~ /^\ep{IsLower}/;   # doesn\*(Aqt match, lowercase char class
+\&    $x =~ /^\eP{IsLower}/;   # matches, char class sans lowercase
+.Ve
+.PP
+(The "\f(CW\*(C`Is\*(C'\fR" is optional.)
+.PP
+There are many, many Unicode character properties.  For the full list
+see perluniprops.  Most of them have synonyms with shorter names,
+also listed there.  Some synonyms are a single character.  For these,
+you can drop the braces.  For instance, \f(CW\*(C`\epM\*(C'\fR is the same thing as
+\&\f(CW\*(C`\ep{Mark}\*(C'\fR, meaning things like accent marks.
+.PP
+The Unicode \f(CW\*(C`\ep{Script}\*(C'\fR and \f(CW\*(C`\ep{Script_Extensions}\*(C'\fR properties are
+used to categorize every Unicode character into the language script it
+is written in.  For example,
+English, French, and a bunch of other European languages are written in
+the Latin script.  But there is also the Greek script, the Thai script,
+the Katakana script, \fIetc\fR.  (\f(CW\*(C`Script\*(C'\fR is an older, less advanced,
+form of \f(CW\*(C`Script_Extensions\*(C'\fR, retained only for backwards
+compatibility.)  You can test whether a character is in a particular
+script  with, for example \f(CW\*(C`\ep{Latin}\*(C'\fR, \f(CW\*(C`\ep{Greek}\*(C'\fR, or
+\&\f(CW\*(C`\ep{Katakana}\*(C'\fR.  To test if it isn't in the Balinese script, you would
+use \f(CW\*(C`\eP{Balinese}\*(C'\fR.  (These all use \f(CW\*(C`Script_Extensions\*(C'\fR under the
+hood, as that gives better results.)
+.PP
+What we have described so far is the single form of the \f(CW\*(C`\ep{...}\*(C'\fR character
+classes.  There is also a compound form which you may run into.  These
+look like \f(CW\*(C`\ep{\fR\f(CIname\fR\f(CW=\fR\f(CIvalue\fR\f(CW}\*(C'\fR or \f(CW\*(C`\ep{\fR\f(CIname\fR\f(CW:\fR\f(CIvalue\fR\f(CW}\*(C'\fR (the equals sign and colon
+can be used interchangeably).  These are more general than the single form,
+and in fact most of the single forms are just Perl-defined shortcuts for common
+compound forms.  For example, the script examples in the previous paragraph
+could be written equivalently as \f(CW\*(C`\ep{Script_Extensions=Latin}\*(C'\fR, \f(CW\*(C`\ep{Script_Extensions:Greek}\*(C'\fR,
+\&\f(CW\*(C`\ep{script_extensions=katakana}\*(C'\fR, and \f(CW\*(C`\eP{script_extensions=balinese}\*(C'\fR (case is irrelevant
+between the \f(CW\*(C`{}\*(C'\fR braces).  You may
+never have to use the compound forms, but sometimes it is necessary, and their
+use can make your code easier to understand.
+.PP
+\&\f(CW\*(C`\eX\*(C'\fR is an abbreviation for a character class that comprises
+a Unicode \fIextended grapheme cluster\fR.  This represents a "logical character":
+what appears to be a single character, but may be represented internally by more
+than one.  As an example, using the Unicode full names, \fIe.g.\fR, "A\ +\ COMBINING\ RING" is a grapheme cluster with base character "A" and combining character
+"COMBINING\ RING, which translates in Danish to "A" with the circle atop it,
+as in the word Ã…ngstrom.
+.PP
+For the full and latest information about Unicode see the latest
+Unicode standard, or the Unicode Consortium's website <https://www.unicode.org>
+.PP
+As if all those classes weren't enough, Perl also defines POSIX-style
+character classes.  These have the form \f(CW\*(C`[:\fR\f(CIname\fR\f(CW:]\*(C'\fR, with \fIname\fR the
+name of the POSIX class.  The POSIX classes are \f(CW\*(C`alpha\*(C'\fR, \f(CW\*(C`alnum\*(C'\fR,
+\&\f(CW\*(C`ascii\*(C'\fR, \f(CW\*(C`cntrl\*(C'\fR, \f(CW\*(C`digit\*(C'\fR, \f(CW\*(C`graph\*(C'\fR, \f(CW\*(C`lower\*(C'\fR, \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`punct\*(C'\fR,
+\&\f(CW\*(C`space\*(C'\fR, \f(CW\*(C`upper\*(C'\fR, and \f(CW\*(C`xdigit\*(C'\fR, and two extensions, \f(CW\*(C`word\*(C'\fR (a Perl
+extension to match \f(CW\*(C`\ew\*(C'\fR), and \f(CW\*(C`blank\*(C'\fR (a GNU extension).  The \f(CW\*(C`/a\*(C'\fR
+modifier restricts these to matching just in the ASCII range; otherwise
+they can match the same as their corresponding Perl Unicode classes:
+\&\f(CW\*(C`[:upper:]\*(C'\fR is the same as \f(CW\*(C`\ep{IsUpper}\*(C'\fR, \fIetc\fR.  (There are some
+exceptions and gotchas with this; see perlrecharclass for a full
+discussion.) The \f(CW\*(C`[:digit:]\*(C'\fR, \f(CW\*(C`[:word:]\*(C'\fR, and
+\&\f(CW\*(C`[:space:]\*(C'\fR correspond to the familiar \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, and \f(CW\*(C`\es\*(C'\fR
+character classes.  To negate a POSIX class, put a \f(CW\*(Aq^\*(Aq\fR in front of
+the name, so that, \fIe.g.\fR, \f(CW\*(C`[:^digit:]\*(C'\fR corresponds to \f(CW\*(C`\eD\*(C'\fR and, under
+Unicode, \f(CW\*(C`\eP{IsDigit}\*(C'\fR.  The Unicode and POSIX character classes can
+be used just like \f(CW\*(C`\ed\*(C'\fR, with the exception that POSIX character
+classes can only be used inside of a character class:
+.PP
+.Vb 6
+\&    /\es+[abc[:digit:]xyz]\es*/;  # match a,b,c,x,y,z, or a digit
+\&    /^=item\es[[:digit:]]/;      # match \*(Aq=item\*(Aq,
+\&                                # followed by a space and a digit
+\&    /\es+[abc\ep{IsDigit}xyz]\es+/;  # match a,b,c,x,y,z, or a digit
+\&    /^=item\es\ep{IsDigit}/;        # match \*(Aq=item\*(Aq,
+\&                                  # followed by a space and a digit
+.Ve
+.PP
+Whew! That is all the rest of the characters and character classes.
+.SS "Compiling and saving regular expressions"
+.IX Subsection "Compiling and saving regular expressions"
+In Part 1 we mentioned that Perl compiles a regexp into a compact
+sequence of opcodes.  Thus, a compiled regexp is a data structure
+that can be stored once and used again and again.  The regexp quote
+\&\f(CW\*(C`qr//\*(C'\fR does exactly that: \f(CW\*(C`qr/string/\*(C'\fR compiles the \f(CW\*(C`string\*(C'\fR as a
+regexp and transforms the result into a form that can be assigned to a
+variable:
+.PP
+.Vb 1
+\&    $reg = qr/foo+bar?/;  # reg contains a compiled regexp
+.Ve
+.PP
+Then \f(CW$reg\fR can be used as a regexp:
+.PP
+.Vb 3
+\&    $x = "fooooba";
+\&    $x =~ $reg;     # matches, just like /foo+bar?/
+\&    $x =~ /$reg/;   # same thing, alternate form
+.Ve
+.PP
+\&\f(CW$reg\fR can also be interpolated into a larger regexp:
+.PP
+.Vb 1
+\&    $x =~ /(abc)?$reg/;  # still matches
+.Ve
+.PP
+As with the matching operator, the regexp quote can use different
+delimiters, \fIe.g.\fR, \f(CW\*(C`qr!!\*(C'\fR, \f(CW\*(C`qr{}\*(C'\fR or \f(CW\*(C`qr~~\*(C'\fR.  Apostrophes
+as delimiters (\f(CW\*(C`qr\*(Aq\*(Aq\*(C'\fR) inhibit any interpolation.
+.PP
+Pre-compiled regexps are useful for creating dynamic matches that
+don't need to be recompiled each time they are encountered.  Using
+pre-compiled regexps, we write a \f(CW\*(C`grep_step\*(C'\fR program which greps
+for a sequence of patterns, advancing to the next pattern as soon
+as one has been satisfied.
+.PP
+.Vb 4
+\&    % cat > grep_step
+\&    #!/usr/bin/perl
+\&    # grep_step \- match <number> regexps, one after the other
+\&    # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
+\&
+\&    $number = shift;
+\&    $regexp[$_] = shift foreach (0..$number\-1);
+\&    @compiled = map qr/$_/, @regexp;
+\&    while ($line = <>) {
+\&        if ($line =~ /$compiled[0]/) {
+\&            print $line;
+\&            shift @compiled;
+\&            last unless @compiled;
+\&        }
+\&    }
+\&    ^D
+\&
+\&    % grep_step 3 shift print last grep_step
+\&    $number = shift;
+\&            print $line;
+\&            last unless @compiled;
+.Ve
+.PP
+Storing pre-compiled regexps in an array \f(CW@compiled\fR allows us to
+simply loop through the regexps without any recompilation, thus gaining
+flexibility without sacrificing speed.
+.SS "Composing regular expressions at runtime"
+.IX Subsection "Composing regular expressions at runtime"
+Backtracking is more efficient than repeated tries with different regular
+expressions.  If there are several regular expressions and a match with
+any of them is acceptable, then it is possible to combine them into a set
+of alternatives.  If the individual expressions are input data, this
+can be done by programming a join operation.  We'll exploit this idea in
+an improved version of the \f(CW\*(C`simple_grep\*(C'\fR program: a program that matches
+multiple patterns:
+.PP
+.Vb 4
+\&    % cat > multi_grep
+\&    #!/usr/bin/perl
+\&    # multi_grep \- match any of <number> regexps
+\&    # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
+\&
+\&    $number = shift;
+\&    $regexp[$_] = shift foreach (0..$number\-1);
+\&    $pattern = join \*(Aq|\*(Aq, @regexp;
+\&
+\&    while ($line = <>) {
+\&        print $line if $line =~ /$pattern/;
+\&    }
+\&    ^D
+\&
+\&    % multi_grep 2 shift for multi_grep
+\&    $number = shift;
+\&    $regexp[$_] = shift foreach (0..$number\-1);
+.Ve
+.PP
+Sometimes it is advantageous to construct a pattern from the \fIinput\fR
+that is to be analyzed and use the permissible values on the left
+hand side of the matching operations.  As an example for this somewhat
+paradoxical situation, let's assume that our input contains a command
+verb which should match one out of a set of available command verbs,
+with the additional twist that commands may be abbreviated as long as
+the given string is unique. The program below demonstrates the basic
+algorithm.
+.PP
+.Vb 10
+\&    % cat > keymatch
+\&    #!/usr/bin/perl
+\&    $kwds = \*(Aqcopy compare list print\*(Aq;
+\&    while( $cmd = <> ){
+\&        $cmd =~ s/^\es+|\es+$//g;  # trim leading and trailing spaces
+\&        if( ( @matches = $kwds =~ /\eb$cmd\ew*/g ) == 1 ){
+\&            print "command: \*(Aq@matches\*(Aq\en";
+\&        } elsif( @matches == 0 ){
+\&            print "no such command: \*(Aq$cmd\*(Aq\en";
+\&        } else {
+\&            print "not unique: \*(Aq$cmd\*(Aq (could be one of: @matches)\en";
+\&        }
+\&    }
+\&    ^D
+\&
+\&    % keymatch
+\&    li
+\&    command: \*(Aqlist\*(Aq
+\&    co
+\&    not unique: \*(Aqco\*(Aq (could be one of: copy compare)
+\&    printer
+\&    no such command: \*(Aqprinter\*(Aq
+.Ve
+.PP
+Rather than trying to match the input against the keywords, we match the
+combined set of keywords against the input.  The pattern matching
+operation \f(CW\*(C`$kwds\ =~\ /\eb($cmd\ew*)/g\*(C'\fR does several things at the
+same time. It makes sure that the given command begins where a keyword
+begins (\f(CW\*(C`\eb\*(C'\fR). It tolerates abbreviations due to the added \f(CW\*(C`\ew*\*(C'\fR. It
+tells us the number of matches (\f(CW\*(C`scalar @matches\*(C'\fR) and all the keywords
+that were actually matched.  You could hardly ask for more.
+.SS "Embedding comments and modifiers in a regular expression"
+.IX Subsection "Embedding comments and modifiers in a regular expression"
+Starting with this section, we will be discussing Perl's set of
+\&\fIextended patterns\fR.  These are extensions to the traditional regular
+expression syntax that provide powerful new tools for pattern
+matching.  We have already seen extensions in the form of the minimal
+matching constructs \f(CW\*(C`??\*(C'\fR, \f(CW\*(C`*?\*(C'\fR, \f(CW\*(C`+?\*(C'\fR, \f(CW\*(C`{n,m}?\*(C'\fR, \f(CW\*(C`{n,}?\*(C'\fR, and
+\&\f(CW\*(C`{,n}?\*(C'\fR.  Most of the extensions below have the form \f(CW\*(C`(?char...)\*(C'\fR,
+where the \f(CW\*(C`char\*(C'\fR is a character that determines the type of extension.
+.PP
+The first extension is an embedded comment \f(CW\*(C`(?#text)\*(C'\fR.  This embeds a
+comment into the regular expression without affecting its meaning.  The
+comment should not have any closing parentheses in the text.  An
+example is
+.PP
+.Vb 1
+\&    /(?# Match an integer:)[+\-]?\ed+/;
+.Ve
+.PP
+This style of commenting has been largely superseded by the raw,
+freeform commenting that is allowed with the \f(CW\*(C`/x\*(C'\fR modifier.
+.PP
+Most modifiers, such as \f(CW\*(C`/i\*(C'\fR, \f(CW\*(C`/m\*(C'\fR, \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/x\*(C'\fR (or any
+combination thereof) can also be embedded in
+a regexp using \f(CW\*(C`(?i)\*(C'\fR, \f(CW\*(C`(?m)\*(C'\fR, \f(CW\*(C`(?s)\*(C'\fR, and \f(CW\*(C`(?x)\*(C'\fR.  For instance,
+.PP
+.Vb 7
+\&    /(?i)yes/;  # match \*(Aqyes\*(Aq case insensitively
+\&    /yes/i;     # same thing
+\&    /(?x)(          # freeform version of an integer regexp
+\&             [+\-]?  # match an optional sign
+\&             \ed+    # match a sequence of digits
+\&         )
+\&    /x;
+.Ve
+.PP
+Embedded modifiers can have two important advantages over the usual
+modifiers.  Embedded modifiers allow a custom set of modifiers for
+\&\fIeach\fR regexp pattern.  This is great for matching an array of regexps
+that must have different modifiers:
+.PP
+.Vb 8
+\&    $pattern[0] = \*(Aq(?i)doctor\*(Aq;
+\&    $pattern[1] = \*(AqJohnson\*(Aq;
+\&    ...
+\&    while (<>) {
+\&        foreach $patt (@pattern) {
+\&            print if /$patt/;
+\&        }
+\&    }
+.Ve
+.PP
+The second advantage is that embedded modifiers (except \f(CW\*(C`/p\*(C'\fR, which
+modifies the entire regexp) only affect the regexp
+inside the group the embedded modifier is contained in.  So grouping
+can be used to localize the modifier's effects:
+.PP
+.Vb 1
+\&    /Answer: ((?i)yes)/;  # matches \*(AqAnswer: yes\*(Aq, \*(AqAnswer: YES\*(Aq, etc.
+.Ve
+.PP
+Embedded modifiers can also turn off any modifiers already present
+by using, \fIe.g.\fR, \f(CW\*(C`(?\-i)\*(C'\fR.  Modifiers can also be combined into
+a single expression, \fIe.g.\fR, \f(CW\*(C`(?s\-i)\*(C'\fR turns on single line mode and
+turns off case insensitivity.
+.PP
+Embedded modifiers may also be added to a non-capturing grouping.
+\&\f(CW\*(C`(?i\-m:regexp)\*(C'\fR is a non-capturing grouping that matches \f(CW\*(C`regexp\*(C'\fR
+case insensitively and turns off multi-line mode.
+.SS "Looking ahead and looking behind"
+.IX Subsection "Looking ahead and looking behind"
+This section concerns the lookahead and lookbehind assertions.  First,
+a little background.
+.PP
+In Perl regular expressions, most regexp elements "eat up" a certain
+amount of string when they match.  For instance, the regexp element
+\&\f(CW\*(C`[abc]\*(C'\fR eats up one character of the string when it matches, in the
+sense that Perl moves to the next character position in the string
+after the match.  There are some elements, however, that don't eat up
+characters (advance the character position) if they match.  The examples
+we have seen so far are the anchors.  The anchor \f(CW\*(Aq^\*(Aq\fR matches the
+beginning of the line, but doesn't eat any characters.  Similarly, the
+word boundary anchor \f(CW\*(C`\eb\*(C'\fR matches wherever a character matching \f(CW\*(C`\ew\*(C'\fR
+is next to a character that doesn't, but it doesn't eat up any
+characters itself.  Anchors are examples of \fIzero-width assertions\fR:
+zero-width, because they consume
+no characters, and assertions, because they test some property of the
+string.  In the context of our walk in the woods analogy to regexp
+matching, most regexp elements move us along a trail, but anchors have
+us stop a moment and check our surroundings.  If the local environment
+checks out, we can proceed forward.  But if the local environment
+doesn't satisfy us, we must backtrack.
+.PP
+Checking the environment entails either looking ahead on the trail,
+looking behind, or both.  \f(CW\*(Aq^\*(Aq\fR looks behind, to see that there are no
+characters before.  \f(CW\*(Aq$\*(Aq\fR looks ahead, to see that there are no
+characters after.  \f(CW\*(C`\eb\*(C'\fR looks both ahead and behind, to see if the
+characters on either side differ in their "word-ness".
+.PP
+The lookahead and lookbehind assertions are generalizations of the
+anchor concept.  Lookahead and lookbehind are zero-width assertions
+that let us specify which characters we want to test for.  The
+lookahead assertion is denoted by \f(CW\*(C`(?=regexp)\*(C'\fR or (starting in 5.32,
+experimentally in 5.28) \f(CW\*(C`(*pla:regexp)\*(C'\fR or
+\&\f(CW\*(C`(*positive_lookahead:regexp)\*(C'\fR; and the lookbehind assertion is denoted
+by \f(CW\*(C`(?<=fixed\-regexp)\*(C'\fR or (starting in 5.32, experimentally in
+5.28) \f(CW\*(C`(*plb:fixed\-regexp)\*(C'\fR or \f(CW\*(C`(*positive_lookbehind:fixed\-regexp)\*(C'\fR.
+Some examples are
+.PP
+.Vb 8
+\&    $x = "I catch the housecat \*(AqTom\-cat\*(Aq with catnip";
+\&    $x =~ /cat(*pla:\es)/;   # matches \*(Aqcat\*(Aq in \*(Aqhousecat\*(Aq
+\&    @catwords = ($x =~ /(?<=\es)cat\ew+/g);  # matches,
+\&                                           # $catwords[0] = \*(Aqcatch\*(Aq
+\&                                           # $catwords[1] = \*(Aqcatnip\*(Aq
+\&    $x =~ /\ebcat\eb/;  # matches \*(Aqcat\*(Aq in \*(AqTom\-cat\*(Aq
+\&    $x =~ /(?<=\es)cat(?=\es)/; # doesn\*(Aqt match; no isolated \*(Aqcat\*(Aq in
+\&                              # middle of $x
+.Ve
+.PP
+Note that the parentheses in these are
+non-capturing, since these are zero-width assertions.  Thus in the
+second regexp, the substrings captured are those of the whole regexp
+itself.  Lookahead can match arbitrary regexps, but
+lookbehind prior to 5.30 \f(CW\*(C`(?<=fixed\-regexp)\*(C'\fR only works for regexps
+of fixed width, \fIi.e.\fR, a fixed number of characters long.  Thus
+\&\f(CW\*(C`(?<=(ab|bc))\*(C'\fR is fine, but \f(CW\*(C`(?<=(ab)*)\*(C'\fR prior to 5.30 is not.
+.PP
+The negated versions of the lookahead and lookbehind assertions are
+denoted by \f(CW\*(C`(?!regexp)\*(C'\fR and \f(CW\*(C`(?<!fixed\-regexp)\*(C'\fR respectively.
+Or, starting in 5.32 (experimentally in 5.28), \f(CW\*(C`(*nla:regexp)\*(C'\fR,
+\&\f(CW\*(C`(*negative_lookahead:regexp)\*(C'\fR, \f(CW\*(C`(*nlb:regexp)\*(C'\fR, or
+\&\f(CW\*(C`(*negative_lookbehind:regexp)\*(C'\fR.
+They evaluate true if the regexps do \fInot\fR match:
+.PP
+.Vb 4
+\&    $x = "foobar";
+\&    $x =~ /foo(?!bar)/;  # doesn\*(Aqt match, \*(Aqbar\*(Aq follows \*(Aqfoo\*(Aq
+\&    $x =~ /foo(?!baz)/;  # matches, \*(Aqbaz\*(Aq doesn\*(Aqt follow \*(Aqfoo\*(Aq
+\&    $x =~ /(?<!\es)foo/;  # matches, there is no \es before \*(Aqfoo\*(Aq
+.Ve
+.PP
+Here is an example where a string containing blank-separated words,
+numbers and single dashes is to be split into its components.
+Using \f(CW\*(C`/\es+/\*(C'\fR alone won't work, because spaces are not required between
+dashes, or a word or a dash. Additional places for a split are established
+by looking ahead and behind:
+.PP
+.Vb 5
+\&    $str = "one two \- \-\-6\-8";
+\&    @toks = split / \es+              # a run of spaces
+\&                  | (?<=\eS) (?=\-)    # any non\-space followed by \*(Aq\-\*(Aq
+\&                  | (?<=\-)  (?=\eS)   # a \*(Aq\-\*(Aq followed by any non\-space
+\&                  /x, $str;          # @toks = qw(one two \- \- \- 6 \- 8)
+.Ve
+.SS "Using independent subexpressions to prevent backtracking"
+.IX Subsection "Using independent subexpressions to prevent backtracking"
+\&\fIIndependent subexpressions\fR (or atomic subexpressions) are regular
+expressions, in the context of a larger regular expression, that
+function independently of the larger regular expression.  That is, they
+consume as much or as little of the string as they wish without regard
+for the ability of the larger regexp to match.  Independent
+subexpressions are represented by
+\&\f(CW\*(C`(?>regexp)\*(C'\fR or (starting in 5.32, experimentally in 5.28)
+\&\f(CW\*(C`(*atomic:regexp)\*(C'\fR.  We can illustrate their behavior by first
+considering an ordinary regexp:
+.PP
+.Vb 2
+\&    $x = "ab";
+\&    $x =~ /a*ab/;  # matches
+.Ve
+.PP
+This obviously matches, but in the process of matching, the
+subexpression \f(CW\*(C`a*\*(C'\fR first grabbed the \f(CW\*(Aqa\*(Aq\fR.  Doing so, however,
+wouldn't allow the whole regexp to match, so after backtracking, \f(CW\*(C`a*\*(C'\fR
+eventually gave back the \f(CW\*(Aqa\*(Aq\fR and matched the empty string.  Here, what
+\&\f(CW\*(C`a*\*(C'\fR matched was \fIdependent\fR on what the rest of the regexp matched.
+.PP
+Contrast that with an independent subexpression:
+.PP
+.Vb 1
+\&    $x =~ /(?>a*)ab/;  # doesn\*(Aqt match!
+.Ve
+.PP
+The independent subexpression \f(CW\*(C`(?>a*)\*(C'\fR doesn't care about the rest
+of the regexp, so it sees an \f(CW\*(Aqa\*(Aq\fR and grabs it.  Then the rest of the
+regexp \f(CW\*(C`ab\*(C'\fR cannot match.  Because \f(CW\*(C`(?>a*)\*(C'\fR is independent, there
+is no backtracking and the independent subexpression does not give
+up its \f(CW\*(Aqa\*(Aq\fR.  Thus the match of the regexp as a whole fails.  A similar
+behavior occurs with completely independent regexps:
+.PP
+.Vb 3
+\&    $x = "ab";
+\&    $x =~ /a*/g;   # matches, eats an \*(Aqa\*(Aq
+\&    $x =~ /\eGab/g; # doesn\*(Aqt match, no \*(Aqa\*(Aq available
+.Ve
+.PP
+Here \f(CW\*(C`/g\*(C'\fR and \f(CW\*(C`\eG\*(C'\fR create a "tag team" handoff of the string from
+one regexp to the other.  Regexps with an independent subexpression are
+much like this, with a handoff of the string to the independent
+subexpression, and a handoff of the string back to the enclosing
+regexp.
+.PP
+The ability of an independent subexpression to prevent backtracking
+can be quite useful.  Suppose we want to match a non-empty string
+enclosed in parentheses up to two levels deep.  Then the following
+regexp matches:
+.PP
+.Vb 2
+\&    $x = "abc(de(fg)h";  # unbalanced parentheses
+\&    $x =~ /\e( ( [ ^ () ]+ | \e( [ ^ () ]* \e) )+ \e)/xx;
+.Ve
+.PP
+The regexp matches an open parenthesis, one or more copies of an
+alternation, and a close parenthesis.  The alternation is two-way, with
+the first alternative \f(CW\*(C`[^()]+\*(C'\fR matching a substring with no
+parentheses and the second alternative \f(CW\*(C`\e([^()]*\e)\*(C'\fR  matching a
+substring delimited by parentheses.  The problem with this regexp is
+that it is pathological: it has nested indeterminate quantifiers
+of the form \f(CW\*(C`(a+|b)+\*(C'\fR.  We discussed in Part 1 how nested quantifiers
+like this could take an exponentially long time to execute if there
+is no match possible.  To prevent the exponential blowup, we need to
+prevent useless backtracking at some point.  This can be done by
+enclosing the inner quantifier as an independent subexpression:
+.PP
+.Vb 1
+\&    $x =~ /\e( ( (?> [ ^ () ]+ ) | \e([ ^ () ]* \e) )+ \e)/xx;
+.Ve
+.PP
+Here, \f(CW\*(C`(?>[^()]+)\*(C'\fR breaks the degeneracy of string partitioning
+by gobbling up as much of the string as possible and keeping it.   Then
+match failures fail much more quickly.
+.SS "Conditional expressions"
+.IX Subsection "Conditional expressions"
+A \fIconditional expression\fR is a form of if-then-else statement
+that allows one to choose which patterns are to be matched, based on
+some condition.  There are two types of conditional expression:
+\&\f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-regexp\fR\f(CW)\*(C'\fR and
+\&\f(CW\*(C`(?(condition)\fR\f(CIyes\-regexp\fR\f(CW|\fR\f(CIno\-regexp\fR\f(CW)\*(C'\fR.
+\&\f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-regexp\fR\f(CW)\*(C'\fR is
+like an \f(CW\*(Aqif\ ()\ {}\*(Aq\fR statement in Perl.  If the \fIcondition\fR is true,
+the \fIyes-regexp\fR will be matched.  If the \fIcondition\fR is false, the
+\&\fIyes-regexp\fR will be skipped and Perl will move onto the next regexp
+element.  The second form is like an \f(CW\*(Aqif\ ()\ {}\ else\ {}\*(Aq\fR statement
+in Perl.  If the \fIcondition\fR is true, the \fIyes-regexp\fR will be
+matched, otherwise the \fIno-regexp\fR will be matched.
+.PP
+The \fIcondition\fR can have several forms.  The first form is simply an
+integer in parentheses \f(CW\*(C`(\fR\f(CIinteger\fR\f(CW)\*(C'\fR.  It is true if the corresponding
+backreference \f(CW\*(C`\e\fR\f(CIinteger\fR\f(CW\*(C'\fR matched earlier in the regexp.  The same
+thing can be done with a name associated with a capture group, written
+as \f(CW\*(C`(<\fR\f(CIname\fR\f(CW>)\*(C'\fR or \f(CW\*(C`(\*(Aq\fR\f(CIname\fR\f(CW\*(Aq)\*(C'\fR.  The second form is a bare
+zero-width assertion \f(CW\*(C`(?...)\*(C'\fR, either a lookahead, a lookbehind, or a
+code assertion (discussed in the next section).  The third set of forms
+provides tests that return true if the expression is executed within
+a recursion (\f(CW\*(C`(R)\*(C'\fR) or is being called from some capturing group,
+referenced either by number (\f(CW\*(C`(R1)\*(C'\fR, \f(CW\*(C`(R2)\*(C'\fR,...) or by name
+(\f(CW\*(C`(R&\fR\f(CIname\fR\f(CW)\*(C'\fR).
+.PP
+The integer or name form of the \f(CW\*(C`condition\*(C'\fR allows us to choose,
+with more flexibility, what to match based on what matched earlier in the
+regexp. This searches for words of the form \f(CW"$x$x"\fR or \f(CW"$x$y$y$x"\fR:
+.PP
+.Vb 9
+\&    % simple_grep \*(Aq^(\ew+)(\ew+)?(?(2)\eg2\eg1|\eg1)$\*(Aq /usr/dict/words
+\&    beriberi
+\&    coco
+\&    couscous
+\&    deed
+\&    ...
+\&    toot
+\&    toto
+\&    tutu
+.Ve
+.PP
+The lookbehind \f(CW\*(C`condition\*(C'\fR allows, along with backreferences,
+an earlier part of the match to influence a later part of the
+match.  For instance,
+.PP
+.Vb 1
+\&    /[ATGC]+(?(?<=AA)G|C)$/;
+.Ve
+.PP
+matches a DNA sequence such that it either ends in \f(CW\*(C`AAG\*(C'\fR, or some
+other base pair combination and \f(CW\*(AqC\*(Aq\fR.  Note that the form is
+\&\f(CW\*(C`(?(?<=AA)G|C)\*(C'\fR and not \f(CW\*(C`(?((?<=AA))G|C)\*(C'\fR; for the
+lookahead, lookbehind or code assertions, the parentheses around the
+conditional are not needed.
+.SS "Defining named patterns"
+.IX Subsection "Defining named patterns"
+Some regular expressions use identical subpatterns in several places.
+Starting with Perl 5.10, it is possible to define named subpatterns in
+a section of the pattern so that they can be called up by name
+anywhere in the pattern.  This syntactic pattern for this definition
+group is \f(CW\*(C`(?(DEFINE)(?<\fR\f(CIname\fR\f(CW>\fR\f(CIpattern\fR\f(CW)...)\*(C'\fR.  An insertion
+of a named pattern is written as \f(CW\*(C`(?&\fR\f(CIname\fR\f(CW)\*(C'\fR.
+.PP
+The example below illustrates this feature using the pattern for
+floating point numbers that was presented earlier on.  The three
+subpatterns that are used more than once are the optional sign, the
+digit sequence for an integer and the decimal fraction.  The \f(CW\*(C`DEFINE\*(C'\fR
+group at the end of the pattern contains their definition.  Notice
+that the decimal fraction pattern is the first place where we can
+reuse the integer pattern.
+.PP
+.Vb 8
+\&   /^ (?&osg)\e * ( (?&int)(?&dec)? | (?&dec) )
+\&      (?: [eE](?&osg)(?&int) )?
+\&    $
+\&    (?(DEFINE)
+\&      (?<osg>[\-+]?)         # optional sign
+\&      (?<int>\ed++)          # integer
+\&      (?<dec>\e.(?&int))     # decimal fraction
+\&    )/x
+.Ve
+.SS "Recursive patterns"
+.IX Subsection "Recursive patterns"
+This feature (introduced in Perl 5.10) significantly extends the
+power of Perl's pattern matching.  By referring to some other
+capture group anywhere in the pattern with the construct
+\&\f(CW\*(C`(?\fR\f(CIgroup\-ref\fR\f(CW)\*(C'\fR, the \fIpattern\fR within the referenced group is used
+as an independent subpattern in place of the group reference itself.
+Because the group reference may be contained \fIwithin\fR the group it
+refers to, it is now possible to apply pattern matching to tasks that
+hitherto required a recursive parser.
+.PP
+To illustrate this feature, we'll design a pattern that matches if
+a string contains a palindrome. (This is a word or a sentence that,
+while ignoring spaces, interpunctuation and case, reads the same backwards
+as forwards. We begin by observing that the empty string or a string
+containing just one word character is a palindrome. Otherwise it must
+have a word character up front and the same at its end, with another
+palindrome in between.
+.PP
+.Vb 1
+\& /(?: (\ew) (?...Here be a palindrome...) \eg{ \-1 } | \ew? )/x
+.Ve
+.PP
+Adding \f(CW\*(C`\eW*\*(C'\fR at either end to eliminate what is to be ignored, we already
+have the full pattern:
+.PP
+.Vb 4
+\&    my $pp = qr/^(\eW* (?: (\ew) (?1) \eg{\-1} | \ew? ) \eW*)$/ix;
+\&    for $s ( "saippuakauppias", "A man, a plan, a canal: Panama!" ){
+\&        print "\*(Aq$s\*(Aq is a palindrome\en" if $s =~ /$pp/;
+\&    }
+.Ve
+.PP
+In \f(CW\*(C`(?...)\*(C'\fR both absolute and relative backreferences may be used.
+The entire pattern can be reinserted with \f(CW\*(C`(?R)\*(C'\fR or \f(CW\*(C`(?0)\*(C'\fR.
+If you prefer to name your groups, you can use \f(CW\*(C`(?&\fR\f(CIname\fR\f(CW)\*(C'\fR to
+recurse into that group.
+.SS "A bit of magic: executing Perl code in a regular expression"
+.IX Subsection "A bit of magic: executing Perl code in a regular expression"
+Normally, regexps are a part of Perl expressions.
+\&\fICode evaluation\fR expressions turn that around by allowing
+arbitrary Perl code to be a part of a regexp.  A code evaluation
+expression is denoted \f(CW\*(C`(?{\fR\f(CIcode\fR\f(CW})\*(C'\fR, with \fIcode\fR a string of Perl
+statements.
+.PP
+Code expressions are zero-width assertions, and the value they return
+depends on their environment.  There are two possibilities: either the
+code expression is used as a conditional in a conditional expression
+\&\f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)...)\*(C'\fR, or it is not.  If the code expression is a
+conditional, the code is evaluated and the result (\fIi.e.\fR, the result of
+the last statement) is used to determine truth or falsehood.  If the
+code expression is not used as a conditional, the assertion always
+evaluates true and the result is put into the special variable
+\&\f(CW$^R\fR.  The variable \f(CW$^R\fR can then be used in code expressions later
+in the regexp.  Here are some silly examples:
+.PP
+.Vb 5
+\&    $x = "abcdef";
+\&    $x =~ /abc(?{print "Hi Mom!";})def/; # matches,
+\&                                         # prints \*(AqHi Mom!\*(Aq
+\&    $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn\*(Aqt match,
+\&                                         # no \*(AqHi Mom!\*(Aq
+.Ve
+.PP
+Pay careful attention to the next example:
+.PP
+.Vb 3
+\&    $x =~ /abc(?{print "Hi Mom!";})ddd/; # doesn\*(Aqt match,
+\&                                         # no \*(AqHi Mom!\*(Aq
+\&                                         # but why not?
+.Ve
+.PP
+At first glance, you'd think that it shouldn't print, because obviously
+the \f(CW\*(C`ddd\*(C'\fR isn't going to match the target string. But look at this
+example:
+.PP
+.Vb 2
+\&    $x =~ /abc(?{print "Hi Mom!";})[dD]dd/; # doesn\*(Aqt match,
+\&                                            # but _does_ print
+.Ve
+.PP
+Hmm. What happened here? If you've been following along, you know that
+the above pattern should be effectively (almost) the same as the last one;
+enclosing the \f(CW\*(Aqd\*(Aq\fR in a character class isn't going to change what it
+matches. So why does the first not print while the second one does?
+.PP
+The answer lies in the optimizations the regexp engine makes. In the first
+case, all the engine sees are plain old characters (aside from the
+\&\f(CW\*(C`?{}\*(C'\fR construct). It's smart enough to realize that the string \f(CW\*(Aqddd\*(Aq\fR
+doesn't occur in our target string before actually running the pattern
+through. But in the second case, we've tricked it into thinking that our
+pattern is more complicated. It takes a look, sees our
+character class, and decides that it will have to actually run the
+pattern to determine whether or not it matches, and in the process of
+running it hits the print statement before it discovers that we don't
+have a match.
+.PP
+To take a closer look at how the engine does optimizations, see the
+section "Pragmas and debugging" below.
+.PP
+More fun with \f(CW\*(C`?{}\*(C'\fR:
+.PP
+.Vb 6
+\&    $x =~ /(?{print "Hi Mom!";})/;         # matches,
+\&                                           # prints \*(AqHi Mom!\*(Aq
+\&    $x =~ /(?{$c = 1;})(?{print "$c";})/;  # matches,
+\&                                           # prints \*(Aq1\*(Aq
+\&    $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches,
+\&                                           # prints \*(Aq1\*(Aq
+.Ve
+.PP
+The bit of magic mentioned in the section title occurs when the regexp
+backtracks in the process of searching for a match.  If the regexp
+backtracks over a code expression and if the variables used within are
+localized using \f(CW\*(C`local\*(C'\fR, the changes in the variables produced by the
+code expression are undone! Thus, if we wanted to count how many times
+a character got matched inside a group, we could use, \fIe.g.\fR,
+.PP
+.Vb 11
+\&    $x = "aaaa";
+\&    $count = 0;  # initialize \*(Aqa\*(Aq count
+\&    $c = "bob";  # test if $c gets clobbered
+\&    $x =~ /(?{local $c = 0;})         # initialize count
+\&           ( a                        # match \*(Aqa\*(Aq
+\&             (?{local $c = $c + 1;})  # increment count
+\&           )*                         # do this any number of times,
+\&           aa                         # but match \*(Aqaa\*(Aq at the end
+\&           (?{$count = $c;})          # copy local $c var into $count
+\&          /x;
+\&    print "\*(Aqa\*(Aq count is $count, \e$c variable is \*(Aq$c\*(Aq\en";
+.Ve
+.PP
+This prints
+.PP
+.Vb 1
+\&    \*(Aqa\*(Aq count is 2, $c variable is \*(Aqbob\*(Aq
+.Ve
+.PP
+If we replace the \f(CW\*(C`\ (?{local\ $c\ =\ $c\ +\ 1;})\*(C'\fR with
+\&\f(CW\*(C`\ (?{$c\ =\ $c\ +\ 1;})\*(C'\fR, the variable changes are \fInot\fR undone
+during backtracking, and we get
+.PP
+.Vb 1
+\&    \*(Aqa\*(Aq count is 4, $c variable is \*(Aqbob\*(Aq
+.Ve
+.PP
+Note that only localized variable changes are undone.  Other side
+effects of code expression execution are permanent.  Thus
+.PP
+.Vb 2
+\&    $x = "aaaa";
+\&    $x =~ /(a(?{print "Yow\en";}))*aa/;
+.Ve
+.PP
+produces
+.PP
+.Vb 4
+\&   Yow
+\&   Yow
+\&   Yow
+\&   Yow
+.Ve
+.PP
+The result \f(CW$^R\fR is automatically localized, so that it will behave
+properly in the presence of backtracking.
+.PP
+This example uses a code expression in a conditional to match a
+definite article, either \f(CW\*(Aqthe\*(Aq\fR in English or \f(CW\*(Aqder|die|das\*(Aq\fR in
+German:
+.PP
+.Vb 11
+\&    $lang = \*(AqDE\*(Aq;  # use German
+\&    ...
+\&    $text = "das";
+\&    print "matched\en"
+\&        if $text =~ /(?(?{
+\&                          $lang eq \*(AqEN\*(Aq; # is the language English?
+\&                         })
+\&                       the |             # if so, then match \*(Aqthe\*(Aq
+\&                       (der|die|das)     # else, match \*(Aqder|die|das\*(Aq
+\&                     )
+\&                    /xi;
+.Ve
+.PP
+Note that the syntax here is \f(CW\*(C`(?(?{...})\fR\f(CIyes\-regexp\fR\f(CW|\fR\f(CIno\-regexp\fR\f(CW)\*(C'\fR, not
+\&\f(CW\*(C`(?((?{...}))\fR\f(CIyes\-regexp\fR\f(CW|\fR\f(CIno\-regexp\fR\f(CW)\*(C'\fR.  In other words, in the case of a
+code expression, we don't need the extra parentheses around the
+conditional.
+.PP
+If you try to use code expressions where the code text is contained within
+an interpolated variable, rather than appearing literally in the pattern,
+Perl may surprise you:
+.PP
+.Vb 5
+\&    $bar = 5;
+\&    $pat = \*(Aq(?{ 1 })\*(Aq;
+\&    /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
+\&    /foo(?{ 1 })$bar/;   # compiles ok, $bar interpolated
+\&    /foo${pat}bar/;      # compile error!
+\&
+\&    $pat = qr/(?{ $foo = 1 })/;  # precompile code regexp
+\&    /foo${pat}bar/;      # compiles ok
+.Ve
+.PP
+If a regexp has a variable that interpolates a code expression, Perl
+treats the regexp as an error. If the code expression is precompiled into
+a variable, however, interpolating is ok. The question is, why is this an
+error?
+.PP
+The reason is that variable interpolation and code expressions
+together pose a security risk.  The combination is dangerous because
+many programmers who write search engines often take user input and
+plug it directly into a regexp:
+.PP
+.Vb 3
+\&    $regexp = <>;       # read user\-supplied regexp
+\&    $chomp $regexp;     # get rid of possible newline
+\&    $text =~ /$regexp/; # search $text for the $regexp
+.Ve
+.PP
+If the \f(CW$regexp\fR variable contains a code expression, the user could
+then execute arbitrary Perl code.  For instance, some joker could
+search for \f(CW\*(C`system(\*(Aqrm\ \-rf\ *\*(Aq);\*(C'\fR to erase your files.  In this
+sense, the combination of interpolation and code expressions \fItaints\fR
+your regexp.  So by default, using both interpolation and code
+expressions in the same regexp is not allowed.  If you're not
+concerned about malicious users, it is possible to bypass this
+security check by invoking \f(CW\*(C`use\ re\ \*(Aqeval\*(Aq\*(C'\fR:
+.PP
+.Vb 4
+\&    use re \*(Aqeval\*(Aq;       # throw caution out the door
+\&    $bar = 5;
+\&    $pat = \*(Aq(?{ 1 })\*(Aq;
+\&    /foo${pat}bar/;      # compiles ok
+.Ve
+.PP
+Another form of code expression is the \fIpattern code expression\fR.
+The pattern code expression is like a regular code expression, except
+that the result of the code evaluation is treated as a regular
+expression and matched immediately.  A simple example is
+.PP
+.Vb 4
+\&    $length = 5;
+\&    $char = \*(Aqa\*(Aq;
+\&    $x = \*(Aqaaaaabb\*(Aq;
+\&    $x =~ /(??{$char x $length})/x; # matches, there are 5 of \*(Aqa\*(Aq
+.Ve
+.PP
+This final example contains both ordinary and pattern code
+expressions.  It detects whether a binary string \f(CW1101010010001...\fR has a
+Fibonacci spacing 0,1,1,2,3,5,...  of the \f(CW\*(Aq1\*(Aq\fR's:
+.PP
+.Vb 12
+\&    $x = "1101010010001000001";
+\&    $z0 = \*(Aq\*(Aq; $z1 = \*(Aq0\*(Aq;   # initial conditions
+\&    print "It is a Fibonacci sequence\en"
+\&        if $x =~ /^1         # match an initial \*(Aq1\*(Aq
+\&                    (?:
+\&                       ((??{ $z0 })) # match some \*(Aq0\*(Aq
+\&                       1             # and then a \*(Aq1\*(Aq
+\&                       (?{ $z0 = $z1; $z1 .= $^N; })
+\&                    )+   # repeat as needed
+\&                  $      # that is all there is
+\&                 /x;
+\&    printf "Largest sequence matched was %d\en", length($z1)\-length($z0);
+.Ve
+.PP
+Remember that \f(CW$^N\fR is set to whatever was matched by the last
+completed capture group. This prints
+.PP
+.Vb 2
+\&    It is a Fibonacci sequence
+\&    Largest sequence matched was 5
+.Ve
+.PP
+Ha! Try that with your garden variety regexp package...
+.PP
+Note that the variables \f(CW$z0\fR and \f(CW$z1\fR are not substituted when the
+regexp is compiled, as happens for ordinary variables outside a code
+expression.  Rather, the whole code block is parsed as perl code at the
+same time as perl is compiling the code containing the literal regexp
+pattern.
+.PP
+This regexp without the \f(CW\*(C`/x\*(C'\fR modifier is
+.PP
+.Vb 1
+\&    /^1(?:((??{ $z0 }))1(?{ $z0 = $z1; $z1 .= $^N; }))+$/
+.Ve
+.PP
+which shows that spaces are still possible in the code parts. Nevertheless,
+when working with code and conditional expressions, the extended form of
+regexps is almost necessary in creating and debugging regexps.
+.SS "Backtracking control verbs"
+.IX Subsection "Backtracking control verbs"
+Perl 5.10 introduced a number of control verbs intended to provide
+detailed control over the backtracking process, by directly influencing
+the regexp engine and by providing monitoring techniques.  See
+"Special Backtracking Control Verbs" in perlre for a detailed
+description.
+.PP
+Below is just one example, illustrating the control verb \f(CW\*(C`(*FAIL)\*(C'\fR,
+which may be abbreviated as \f(CW\*(C`(*F)\*(C'\fR. If this is inserted in a regexp
+it will cause it to fail, just as it would at some
+mismatch between the pattern and the string. Processing
+of the regexp continues as it would after any "normal"
+failure, so that, for instance, the next position in the string or another
+alternative will be tried. As failing to match doesn't preserve capture
+groups or produce results, it may be necessary to use this in
+combination with embedded code.
+.PP
+.Vb 4
+\&   %count = ();
+\&   "supercalifragilisticexpialidocious" =~
+\&       /([aeiou])(?{ $count{$1}++; })(*FAIL)/i;
+\&   printf "%3d \*(Aq%s\*(Aq\en", $count{$_}, $_ for (sort keys %count);
+.Ve
+.PP
+The pattern begins with a class matching a subset of letters.  Whenever
+this matches, a statement like \f(CW\*(C`$count{\*(Aqa\*(Aq}++;\*(C'\fR is executed, incrementing
+the letter's counter. Then \f(CW\*(C`(*FAIL)\*(C'\fR does what it says, and
+the regexp engine proceeds according to the book: as long as the end of
+the string hasn't been reached, the position is advanced before looking
+for another vowel. Thus, match or no match makes no difference, and the
+regexp engine proceeds until the entire string has been inspected.
+(It's remarkable that an alternative solution using something like
+.PP
+.Vb 2
+\&   $count{lc($_)}++ for split(\*(Aq\*(Aq, "supercalifragilisticexpialidocious");
+\&   printf "%3d \*(Aq%s\*(Aq\en", $count2{$_}, $_ for ( qw{ a e i o u } );
+.Ve
+.PP
+is considerably slower.)
+.SS "Pragmas and debugging"
+.IX Subsection "Pragmas and debugging"
+Speaking of debugging, there are several pragmas available to control
+and debug regexps in Perl.  We have already encountered one pragma in
+the previous section, \f(CW\*(C`use\ re\ \*(Aqeval\*(Aq;\*(C'\fR, that allows variable
+interpolation and code expressions to coexist in a regexp.  The other
+pragmas are
+.PP
+.Vb 3
+\&    use re \*(Aqtaint\*(Aq;
+\&    $tainted = <>;
+\&    @parts = ($tainted =~ /(\ew+)\es+(\ew+)/; # @parts is now tainted
+.Ve
+.PP
+The \f(CW\*(C`taint\*(C'\fR pragma causes any substrings from a match with a tainted
+variable to be tainted as well, if your perl supports tainting
+(see perlsec).  This is not normally the case, as
+regexps are often used to extract the safe bits from a tainted
+variable.  Use \f(CW\*(C`taint\*(C'\fR when you are not extracting safe bits, but are
+performing some other processing.  Both \f(CW\*(C`taint\*(C'\fR and \f(CW\*(C`eval\*(C'\fR pragmas
+are lexically scoped, which means they are in effect only until
+the end of the block enclosing the pragmas.
+.PP
+.Vb 2
+\&    use re \*(Aq/m\*(Aq;  # or any other flags
+\&    $multiline_string =~ /^foo/; # /m is implied
+.Ve
+.PP
+The \f(CW\*(C`re \*(Aq/flags\*(Aq\*(C'\fR pragma (introduced in Perl
+5.14) turns on the given regular expression flags
+until the end of the lexical scope.  See
+"'/flags' mode" in re for more
+detail.
+.PP
+.Vb 2
+\&    use re \*(Aqdebug\*(Aq;
+\&    /^(.*)$/s;       # output debugging info
+\&
+\&    use re \*(Aqdebugcolor\*(Aq;
+\&    /^(.*)$/s;       # output debugging info in living color
+.Ve
+.PP
+The global \f(CW\*(C`debug\*(C'\fR and \f(CW\*(C`debugcolor\*(C'\fR pragmas allow one to get
+detailed debugging info about regexp compilation and
+execution.  \f(CW\*(C`debugcolor\*(C'\fR is the same as debug, except the debugging
+information is displayed in color on terminals that can display
+termcap color sequences.  Here is example output:
+.PP
+.Vb 10
+\&    % perl \-e \*(Aquse re "debug"; "abc" =~ /a*b+c/;\*(Aq
+\&    Compiling REx \*(Aqa*b+c\*(Aq
+\&    size 9 first at 1
+\&       1: STAR(4)
+\&       2:   EXACT <a>(0)
+\&       4: PLUS(7)
+\&       5:   EXACT <b>(0)
+\&       7: EXACT <c>(9)
+\&       9: END(0)
+\&    floating \*(Aqbc\*(Aq at 0..2147483647 (checking floating) minlen 2
+\&    Guessing start of match, REx \*(Aqa*b+c\*(Aq against \*(Aqabc\*(Aq...
+\&    Found floating substr \*(Aqbc\*(Aq at offset 1...
+\&    Guessed: match at offset 0
+\&    Matching REx \*(Aqa*b+c\*(Aq against \*(Aqabc\*(Aq
+\&      Setting an EVAL scope, savestack=3
+\&       0 <> <abc>           |  1:  STAR
+\&                             EXACT <a> can match 1 times out of 32767...
+\&      Setting an EVAL scope, savestack=3
+\&       1 <a> <bc>           |  4:    PLUS
+\&                             EXACT <b> can match 1 times out of 32767...
+\&      Setting an EVAL scope, savestack=3
+\&       2 <ab> <c>           |  7:      EXACT <c>
+\&       3 <abc> <>           |  9:      END
+\&    Match successful!
+\&    Freeing REx: \*(Aqa*b+c\*(Aq
+.Ve
+.PP
+If you have gotten this far into the tutorial, you can probably guess
+what the different parts of the debugging output tell you.  The first
+part
+.PP
+.Vb 8
+\&    Compiling REx \*(Aqa*b+c\*(Aq
+\&    size 9 first at 1
+\&       1: STAR(4)
+\&       2:   EXACT <a>(0)
+\&       4: PLUS(7)
+\&       5:   EXACT <b>(0)
+\&       7: EXACT <c>(9)
+\&       9: END(0)
+.Ve
+.PP
+describes the compilation stage.  \f(CWSTAR(4)\fR means that there is a
+starred object, in this case \f(CW\*(Aqa\*(Aq\fR, and if it matches, goto line 4,
+\&\fIi.e.\fR, \f(CWPLUS(7)\fR.  The middle lines describe some heuristics and
+optimizations performed before a match:
+.PP
+.Vb 4
+\&    floating \*(Aqbc\*(Aq at 0..2147483647 (checking floating) minlen 2
+\&    Guessing start of match, REx \*(Aqa*b+c\*(Aq against \*(Aqabc\*(Aq...
+\&    Found floating substr \*(Aqbc\*(Aq at offset 1...
+\&    Guessed: match at offset 0
+.Ve
+.PP
+Then the match is executed and the remaining lines describe the
+process:
+.PP
+.Vb 12
+\&    Matching REx \*(Aqa*b+c\*(Aq against \*(Aqabc\*(Aq
+\&      Setting an EVAL scope, savestack=3
+\&       0 <> <abc>           |  1:  STAR
+\&                             EXACT <a> can match 1 times out of 32767...
+\&      Setting an EVAL scope, savestack=3
+\&       1 <a> <bc>           |  4:    PLUS
+\&                             EXACT <b> can match 1 times out of 32767...
+\&      Setting an EVAL scope, savestack=3
+\&       2 <ab> <c>           |  7:      EXACT <c>
+\&       3 <abc> <>           |  9:      END
+\&    Match successful!
+\&    Freeing REx: \*(Aqa*b+c\*(Aq
+.Ve
+.PP
+Each step is of the form \f(CW\*(C`n\ <x>\ <y>\*(C'\fR, with \f(CW\*(C`<x>\*(C'\fR the
+part of the string matched and \f(CW\*(C`<y>\*(C'\fR the part not yet
+matched.  The \f(CW\*(C`|\ \ 1:\ \ STAR\*(C'\fR says that Perl is at line number 1
+in the compilation list above.  See
+"Debugging Regular Expressions" in perldebguts for much more detail.
+.PP
+An alternative method of debugging regexps is to embed \f(CW\*(C`print\*(C'\fR
+statements within the regexp.  This provides a blow-by-blow account of
+the backtracking in an alternation:
+.PP
+.Vb 12
+\&    "that this" =~ m@(?{print "Start at position ", pos, "\en";})
+\&                     t(?{print "t1\en";})
+\&                     h(?{print "h1\en";})
+\&                     i(?{print "i1\en";})
+\&                     s(?{print "s1\en";})
+\&                         |
+\&                     t(?{print "t2\en";})
+\&                     h(?{print "h2\en";})
+\&                     a(?{print "a2\en";})
+\&                     t(?{print "t2\en";})
+\&                     (?{print "Done at position ", pos, "\en";})
+\&                    @x;
+.Ve
+.PP
+prints
+.PP
+.Vb 8
+\&    Start at position 0
+\&    t1
+\&    h1
+\&    t2
+\&    h2
+\&    a2
+\&    t2
+\&    Done at position 4
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+This is just a tutorial.  For the full story on Perl regular
+expressions, see the perlre regular expressions reference page.
+.PP
+For more information on the matching \f(CW\*(C`m//\*(C'\fR and substitution \f(CW\*(C`s///\*(C'\fR
+operators, see "Regexp Quote-Like Operators" in perlop.  For
+information on the \f(CW\*(C`split\*(C'\fR operation, see "split" in perlfunc.
+.PP
+For an excellent all-around resource on the care and feeding of
+regular expressions, see the book \fIMastering Regular Expressions\fR by
+Jeffrey Friedl (published by O'Reilly, ISBN 1556592\-257\-3).
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (c) 2000 Mark Kvale.
+All rights reserved.
+Now maintained by Perl porters.
+.PP
+This document may be distributed under the same terms as Perl itself.
+.SS Acknowledgments
+.IX Subsection "Acknowledgments"
+The inspiration for the stop codon DNA example came from the ZIP
+code example in chapter 7 of \fIMastering Regular Expressions\fR.
+.PP
+The author would like to thank Jeff Pinyan, Andrew Johnson, Peter
+Haworth, Ronald J Kimball, and Joe Smith for all their helpful
+comments.
diff --git a/upstream/mageia-cauldron/man1/perlriscos.1 b/upstream/mageia-cauldron/man1/perlriscos.1
new file mode 100644
index 00000000..4e0c7173
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlriscos.1
@@ -0,0 +1,109 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLRISCOS 1"
+.TH PERLRISCOS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlriscos \- Perl version 5 for RISC OS
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document gives instructions for building Perl for RISC OS. It is
+complicated by the need to cross compile. There is a binary version of
+perl available from <http://www.cp15.org/perl/> which you may wish to
+use instead of trying to compile it yourself.
+.SH BUILD
+.IX Header "BUILD"
+You need an installed and working gccsdk cross compiler
+<http://gccsdk.riscos.info/> and REXEN
+<http://www.cp15.org/programming/>
+.PP
+Firstly, copy the source and build a native copy of perl for your host
+system.
+Then, in the source to be cross compiled:
+.IP 1. 4
+.Vb 1
+\&    $ ./Configure
+.Ve
+.IP 2. 4
+Select the riscos hint file. The default answers for the rest of the
+questions are usually sufficient.
+.Sp
+Note that, if you wish to run Configure non-interactively (see the INSTALL
+document for details), to have it select the correct hint file, you'll
+need to provide the argument \-Dhintfile=riscos on the Configure
+command-line.
+.IP 3. 4
+.Vb 1
+\&    $ make miniperl
+.Ve
+.IP 4. 4
+This should build miniperl and then fail when it tries to run it.
+.IP 5. 4
+Copy the miniperl executable from the native build done earlier to
+replace the cross compiled miniperl.
+.IP 6. 4
+.Vb 1
+\&    $ make
+.Ve
+.IP 7. 4
+This will use miniperl to complete the rest of the build.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Alex Waugh <alex@alexwaugh.com>
diff --git a/upstream/mageia-cauldron/man1/perlrun.1 b/upstream/mageia-cauldron/man1/perlrun.1
new file mode 100644
index 00000000..0301f67a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlrun.1
@@ -0,0 +1,1630 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLRUN 1"
+.TH PERLRUN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlrun \- how to execute the Perl interpreter
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBperl\fR	[\ \fB\-gsTtuUWX\fR\ ]
+	[\ \fB\-h?v\fR\ ]\ [\ \fB\-V\fR[:\fIconfigvar\fR]\ ]
+	[\ \fB\-cw\fR\ ]\ [\ \fB\-d\fR[\fBt\fR][:\fIdebugger\fR]\ ]\ [\ \fB\-D\fR[\fInumber/list\fR]\ ]
+	[\ \fB\-pna\fR\ ]\ [\ \fB\-F\fR\fIpattern\fR\ ]\ [\ \fB\-l\fR[\fIoctal\fR]\ ]\ [\ \fB\-0\fR[\fIoctal/hexadecimal\fR]\ ]
+	[\ \fB\-I\fR\fIdir\fR\ ]\ [\ \fB\-m\fR[\fB\-\fR]\fImodule\fR\ ]\ [\ \fB\-M\fR[\fB\-\fR]\fI'module...'\fR\ ]\ [\ \fB\-f\fR\ ]
+	[\ \fB\-C\ [\fR\f(BInumber/list\fR\fB]\ \fR]
+	[\ \fB\-S\fR\ ]
+	[\ \fB\-x\fR[\fIdir\fR]\ ]
+	[\ \fB\-i\fR[\fIextension\fR]\ ]
+	[\ [\fB\-e\fR|\fB\-E\fR]\ \fI'command'\fR\ ]\ [\ \fB\-\-\fR\ ]\ [\ \fIprogramfile\fR\ ]\ [\ \fIargument\fR\ ]...
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The normal way to run a Perl program is by making it directly
+executable, or else by passing the name of the source file as an
+argument on the command line.  (An interactive Perl environment
+is also possible\-\-see perldebug for details on how to do that.)
+Upon startup, Perl looks for your program in one of the following
+places:
+.IP 1. 4
+Specified line by line via \-e or \-E
+switches on the command line.
+.IP 2. 4
+Contained in the file specified by the first filename on the command line.
+(Note that systems supporting the \f(CW\*(C`#!\*(C'\fR notation invoke interpreters this
+way. See "Location of Perl".)
+.IP 3. 4
+Passed in implicitly via standard input.  This works only if there are
+no filename arguments\-\-to pass arguments to a STDIN-read program you
+must explicitly specify a "\-" for the program name.
+.PP
+With methods 2 and 3, Perl starts parsing the input file from the
+beginning, unless you've specified a "\-x" switch, in which case it
+scans for the first line starting with \f(CW\*(C`#!\*(C'\fR and containing the word
+"perl", and starts there instead.  This is useful for running a program
+embedded in a larger message.  (In this case you would indicate the end
+of the program using the \f(CW\*(C`_\|_END_\|_\*(C'\fR token.)
+.PP
+The \f(CW\*(C`#!\*(C'\fR line is always examined for switches as the line is being
+parsed.  Thus, if you're on a machine that allows only one argument
+with the \f(CW\*(C`#!\*(C'\fR line, or worse, doesn't even recognize the \f(CW\*(C`#!\*(C'\fR line, you
+still can get consistent switch behaviour regardless of how Perl was
+invoked, even if "\-x" was used to find the beginning of the program.
+.PP
+Because historically some operating systems silently chopped off
+kernel interpretation of the \f(CW\*(C`#!\*(C'\fR line after 32 characters, some
+switches may be passed in on the command line, and some may not;
+you could even get a "\-" without its letter, if you're not careful.
+You probably want to make sure that all your switches fall either
+before or after that 32\-character boundary.  Most switches don't
+actually care if they're processed redundantly, but getting a "\-"
+instead of a complete switch could cause Perl to try to execute
+standard input instead of your program.  And a partial \-I
+switch could also cause odd results.
+.PP
+Some switches do care if they are processed twice, for instance
+combinations of \-l and \-0.
+Either put all the switches after the 32\-character boundary (if
+applicable), or replace the use of \fB\-0\fR\fIdigits\fR by
+\&\f(CW\*(C`BEGIN{ $/ = "\e0digits"; }\*(C'\fR.
+.PP
+Parsing of the \f(CW\*(C`#!\*(C'\fR switches starts wherever "perl" is mentioned in the line.
+The sequences "\-*" and "\- " are specifically ignored so that you could,
+if you were so inclined, say
+.PP
+.Vb 4
+\&    #!/bin/sh
+\&    #! \-*\- perl \-*\- \-p
+\&    eval \*(Aqexec perl \-x \-wS $0 ${1+"$@"}\*(Aq
+\&        if 0;
+.Ve
+.PP
+to let Perl see the "\-p" switch.
+.PP
+A similar trick involves the \fIenv\fR program, if you have it.
+.PP
+.Vb 1
+\&    #!/usr/bin/env perl
+.Ve
+.PP
+The examples above use a relative path to the perl interpreter,
+getting whatever version is first in the user's path.  If you want
+a specific version of Perl, say, perl5.14.1, you should place
+that directly in the \f(CW\*(C`#!\*(C'\fR line's path.
+.PP
+If the \f(CW\*(C`#!\*(C'\fR line does not contain the word "perl" nor the word "indir",
+the program named after the \f(CW\*(C`#!\*(C'\fR is executed instead of the Perl
+interpreter.  This is slightly bizarre, but it helps people on machines
+that don't do \f(CW\*(C`#!\*(C'\fR, because they can tell a program that their SHELL is
+\&\fI/usr/bin/perl\fR, and Perl will then dispatch the program to the correct
+interpreter for them.
+.PP
+After locating your program, Perl compiles the entire program to an
+internal form.  If there are any compilation errors, execution of the
+program is not attempted.  (This is unlike the typical shell script,
+which might run part-way through before finding a syntax error.)
+.PP
+If the program is syntactically correct, it is executed.  If the program
+runs off the end without hitting an \fBexit()\fR or \fBdie()\fR operator, an implicit
+\&\f(CWexit(0)\fR is provided to indicate successful completion.
+.SS "#! and quoting on non-Unix systems"
+.IX Xref "hashbang #!"
+.IX Subsection "#! and quoting on non-Unix systems"
+Unix's \f(CW\*(C`#!\*(C'\fR technique can be simulated on other systems:
+.IP OS/2 4
+.IX Item "OS/2"
+Put
+.Sp
+.Vb 1
+\&    extproc perl \-S \-your_switches
+.Ve
+.Sp
+as the first line in \f(CW\*(C`*.cmd\*(C'\fR file ("\-S" due to a bug in cmd.exe's
+`extproc' handling).
+.IP MS-DOS 4
+.IX Item "MS-DOS"
+Create a batch file to run your program, and codify it in
+\&\f(CW\*(C`ALTERNATE_SHEBANG\*(C'\fR (see the \fIdosish.h\fR file in the source
+distribution for more information).
+.IP Win95/NT 4
+.IX Item "Win95/NT"
+The Win95/NT installation, when using the ActiveState installer for Perl,
+will modify the Registry to associate the \fI.pl\fR extension with the perl
+interpreter.  If you install Perl by other means (including building from
+the sources), you may have to modify the Registry yourself.  Note that
+this means you can no longer tell the difference between an executable
+Perl program and a Perl library file.
+.IP VMS 4
+.IX Item "VMS"
+Put
+.Sp
+.Vb 2
+\& $ perl \-mysw \*(Aqf$env("procedure")\*(Aq \*(Aqp1\*(Aq \*(Aqp2\*(Aq \*(Aqp3\*(Aq \*(Aqp4\*(Aq \*(Aqp5\*(Aq \*(Aqp6\*(Aq \*(Aqp7\*(Aq \*(Aqp8\*(Aq !
+\& $ exit++ + ++$status != 0 and $exit = $status = undef;
+.Ve
+.Sp
+at the top of your program, where \fB\-mysw\fR are any command line switches you
+want to pass to Perl.  You can now invoke the program directly, by saying
+\&\f(CW\*(C`perl program\*(C'\fR, or as a DCL procedure, by saying \f(CW@program\fR (or implicitly
+via \fIDCL$PATH\fR by just using the name of the program).
+.Sp
+This incantation is a bit much to remember, but Perl will display it for
+you if you say \f(CW\*(C`perl "\-V:startperl"\*(C'\fR.
+.PP
+Command-interpreters on non-Unix systems have rather different ideas
+on quoting than Unix shells.  You'll need to learn the special
+characters in your command-interpreter (\f(CW\*(C`*\*(C'\fR, \f(CW\*(C`\e\*(C'\fR and \f(CW\*(C`"\*(C'\fR are
+common) and how to protect whitespace and these characters to run
+one-liners (see \-e below).
+.PP
+On some systems, you may have to change single-quotes to double ones,
+which you must \fInot\fR do on Unix or Plan 9 systems.  You might also
+have to change a single % to a %%.
+.PP
+For example:
+.PP
+.Vb 2
+\&    # Unix
+\&    perl \-e \*(Aqprint "Hello world\en"\*(Aq
+\&
+\&    # MS\-DOS, etc.
+\&    perl \-e "print \e"Hello world\en\e""
+\&
+\&    # VMS
+\&    perl \-e "print ""Hello world\en"""
+.Ve
+.PP
+The problem is that none of this is reliable: it depends on the
+command and it is entirely possible neither works.  If \fI4DOS\fR were
+the command shell, this would probably work better:
+.PP
+.Vb 1
+\&    perl \-e "print <Ctrl\-x>"Hello world\en<Ctrl\-x>""
+.Ve
+.PP
+\&\fBCMD.EXE\fR in Windows NT slipped a lot of standard Unix functionality in
+when nobody was looking, but just try to find documentation for its
+quoting rules.
+.PP
+There is no general solution to all of this.  It's just a mess.
+.SS "Location of Perl"
+.IX Xref "perl, location of interpreter"
+.IX Subsection "Location of Perl"
+It may seem obvious to say, but Perl is useful only when users can
+easily find it.  When possible, it's good for both \fI/usr/bin/perl\fR
+and \fI/usr/local/bin/perl\fR to be symlinks to the actual binary.  If
+that can't be done, system administrators are strongly encouraged
+to put (symlinks to) perl and its accompanying utilities into a
+directory typically found along a user's PATH, or in some other
+obvious and convenient place.
+.PP
+In this documentation, \f(CW\*(C`#!/usr/bin/perl\*(C'\fR on the first line of the program
+will stand in for whatever method works on your system.  You are
+advised to use a specific path if you care about a specific version.
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl5.14
+.Ve
+.PP
+or if you just want to be running at least version, place a statement
+like this at the top of your program:
+.PP
+.Vb 1
+\&    use v5.14;
+.Ve
+.SS "Command Switches"
+.IX Xref "perl, command switches command switches"
+.IX Subsection "Command Switches"
+As with all standard commands, a single-character switch may be
+clustered with the following switch, if any.
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-spi.orig   # same as \-s \-p \-i.orig
+.Ve
+.PP
+A \f(CW\*(C`\-\-\*(C'\fR signals the end of options and disables further option processing. Any
+arguments after the \f(CW\*(C`\-\-\*(C'\fR are treated as filenames and arguments.
+.PP
+Switches include:
+.IP \fB\-0\fR[\fIoctal/hexadecimal\fR] 5
+.IX Xref "-0 $"
+.IX Item "-0[octal/hexadecimal]"
+specifies the input record separator (\f(CW$/\fR) as an octal or
+hexadecimal number.  If there are no digits, the null character is the
+separator.  Other switches may precede or follow the digits.  For
+example, if you have a version of \fIfind\fR which can print filenames
+terminated by the null character, you can say this:
+.Sp
+.Vb 1
+\&    find . \-name \*(Aq*.orig\*(Aq \-print0 | perl \-n0e unlink
+.Ve
+.Sp
+The special value 00 will cause Perl to slurp files in paragraph mode.
+.Sp
+Any value 0400 or above will cause Perl to slurp files whole, but by convention
+the value 0777 is the one normally used for this purpose. The "\-g" flag
+is a simpler alias for it.
+.Sp
+You can also specify the separator character using hexadecimal notation:
+\&\fB\-0x\fR\f(BIHHH...\fR, where the \f(CW\*(C`\fR\f(CIH\fR\f(CW\*(C'\fR are valid hexadecimal digits.  Unlike
+the octal form, this one may be used to specify any Unicode character, even
+those beyond 0xFF.  So if you \fIreally\fR want a record separator of 0777,
+specify it as \fB\-0x1FF\fR.  (This means that you cannot use the "\-x" option
+with a directory name that consists of hexadecimal digits, or else Perl
+will think you have specified a hex number to \fB\-0\fR.)
+.IP \fB\-a\fR 5
+.IX Xref "-a autosplit"
+.IX Item "-a"
+turns on autosplit mode when used with a "\-n" or "\-p".  An implicit
+split command to the \f(CW@F\fR array is done as the first thing inside the
+implicit while loop produced by the "\-n" or "\-p".
+.Sp
+.Vb 1
+\&    perl \-ane \*(Aqprint pop(@F), "\en";\*(Aq
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 4
+\&    while (<>) {
+\&        @F = split(\*(Aq \*(Aq);
+\&        print pop(@F), "\en";
+\&    }
+.Ve
+.Sp
+An alternate delimiter may be specified using \-F.
+.Sp
+\&\fB\-a\fR implicitly sets "\-n".
+.IP "\fB\-C [\fR\f(BInumber/list\fR\fB]\fR" 5
+.IX Xref "-C"
+.IX Item "-C [number/list]"
+The \fB\-C\fR flag controls some of the Perl Unicode features.
+.Sp
+As of 5.8.1, the \fB\-C\fR can be followed either by a number or a list
+of option letters.  The letters, their numeric values, and effects
+are as follows; listing the letters is equal to summing the numbers.
+.Sp
+.Vb 10
+\&    I     1   STDIN is assumed to be in UTF\-8
+\&    O     2   STDOUT will be in UTF\-8
+\&    E     4   STDERR will be in UTF\-8
+\&    S     7   I + O + E
+\&    i     8   UTF\-8 is the default PerlIO layer for input streams
+\&    o    16   UTF\-8 is the default PerlIO layer for output streams
+\&    D    24   i + o
+\&    A    32   the @ARGV elements are expected to be strings encoded
+\&              in UTF\-8
+\&    L    64   normally the "IOEioA" are unconditional, the L makes
+\&              them conditional on the locale environment variables
+\&              (the LC_ALL, LC_CTYPE, and LANG, in the order of
+\&              decreasing precedence) \-\- if the variables indicate
+\&              UTF\-8, then the selected "IOEioA" are in effect
+\&    a   256   Set ${^UTF8CACHE} to \-1, to run the UTF\-8 caching
+\&              code in debugging mode.
+.Ve
+.Sp
+For example, \fB\-COE\fR and \fB\-C6\fR will both turn on UTF\-8\-ness on both
+STDOUT and STDERR.  Repeating letters is just redundant, not cumulative
+nor toggling.
+.Sp
+The \f(CW\*(C`io\*(C'\fR options mean that any subsequent \fBopen()\fR (or similar I/O
+operations) in main program scope will have the \f(CW\*(C`:utf8\*(C'\fR PerlIO layer
+implicitly applied to them, in other words, UTF\-8 is expected from any
+input stream, and UTF\-8 is produced to any output stream.  This is just
+the default set via \f(CW\*(C`${^OPEN}\*(C'\fR,
+with explicit layers in \fBopen()\fR and with \fBbinmode()\fR one can
+manipulate streams as usual.  This has no effect on code run in modules.
+.Sp
+\&\fB\-C\fR on its own (not followed by any number or option list), or the
+empty string \f(CW""\fR for the "PERL_UNICODE" environment variable, has the
+same effect as \fB\-CSDL\fR.  In other words, the standard I/O handles and
+the default \f(CWopen()\fR layer are UTF\-8\-fied \fIbut\fR only if the locale
+environment variables indicate a UTF\-8 locale.  This behaviour follows
+the \fIimplicit\fR (and problematic) UTF\-8 behaviour of Perl 5.8.0.
+(See "UTF\-8 no longer default under UTF\-8 locales" in perl581delta.)
+.Sp
+You can use \fB\-C0\fR (or \f(CW"0"\fR for \f(CW\*(C`PERL_UNICODE\*(C'\fR) to explicitly
+disable all the above Unicode features.
+.Sp
+The read-only magic variable \f(CW\*(C`${^UNICODE}\*(C'\fR reflects the numeric value
+of this setting.  This variable is set during Perl startup and is
+thereafter read-only.  If you want runtime effects, use the three-arg
+\&\fBopen()\fR (see "open" in perlfunc), the two-arg \fBbinmode()\fR (see "binmode" in perlfunc),
+and the \f(CW\*(C`open\*(C'\fR pragma (see open).
+.Sp
+(In Perls earlier than 5.8.1 the \fB\-C\fR switch was a Win32\-only switch
+that enabled the use of Unicode-aware "wide system call" Win32 APIs.
+This feature was practically unused, however, and the command line
+switch was therefore "recycled".)
+.Sp
+\&\fBNote:\fR Since perl 5.10.1, if the \fB\-C\fR option is used on the \f(CW\*(C`#!\*(C'\fR line,
+it must be specified on the command line as well, since the standard streams
+are already set up at this point in the execution of the perl interpreter.
+You can also use \fBbinmode()\fR to set the encoding of an I/O stream.
+.IP \fB\-c\fR 5
+.IX Xref "-c"
+.IX Item "-c"
+causes Perl to check the syntax of the program and then exit without
+executing it.  Actually, it \fIwill\fR execute any \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR,
+or \f(CW\*(C`CHECK\*(C'\fR blocks and any \f(CW\*(C`use\*(C'\fR statements: these are considered as
+occurring outside the execution of your program.  \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR
+blocks, however, will be skipped.
+.IP \fB\-d\fR 5
+.IX Xref "-d -dt"
+.IX Item "-d"
+.PD 0
+.IP \fB\-dt\fR 5
+.IX Item "-dt"
+.PD
+runs the program under the Perl debugger.  See perldebug.
+If \fBt\fR is specified, it indicates to the debugger that threads
+will be used in the code being debugged.
+.IP \fB\-d:\fR\fIMOD[=bar,baz]\fR 5
+.IX Xref "-d -dt"
+.IX Item "-d:MOD[=bar,baz]"
+.PD 0
+.IP \fB\-dt:\fR\fIMOD[=bar,baz]\fR 5
+.IX Item "-dt:MOD[=bar,baz]"
+.PD
+runs the program under the control of a debugging, profiling, or tracing
+module installed as \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW\*(C'\fR. E.g., \fB\-d:DProf\fR executes the
+program using the \f(CW\*(C`Devel::DProf\*(C'\fR profiler.  As with the \-M
+flag, options may be passed to the \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW\*(C'\fR package where they will
+be received and interpreted by the \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW::import\*(C'\fR routine.  Again,
+like \fB\-M\fR, use \-\fB\-d:\-\fR\f(BIMOD\fR to call \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW::unimport\*(C'\fR instead of
+import.  The comma-separated list of options must follow a \f(CW\*(C`=\*(C'\fR character.
+If \fBt\fR is specified, it indicates to the debugger that threads will be used
+in the code being debugged.  See perldebug.
+.IP \fB\-D\fR\fIletters\fR 5
+.IX Xref "-D DEBUGGING -DDEBUGGING"
+.IX Item "-Dletters"
+.PD 0
+.IP \fB\-D\fR\fInumber\fR 5
+.IX Item "-Dnumber"
+.PD
+sets debugging flags. This switch is enabled only if your perl binary has
+been built with debugging enabled: normal production perls won't have
+been.
+.Sp
+For example, to watch how perl executes your program, use \fB\-Dtls\fR.
+Another nice value is \fB\-Dx\fR, which lists your compiled syntax tree, and
+\&\fB\-Dr\fR displays compiled regular expressions; the format of the output is
+explained in perldebguts.
+.Sp
+As an alternative, specify a number instead of list of letters (e.g.,
+\&\fB\-D14\fR is equivalent to \fB\-Dtls\fR):
+.Sp
+.Vb 10
+\&         1  p  Tokenizing and parsing (with v, displays parse
+\&               stack)
+\&         2  s  Stack snapshots (with v, displays all stacks)
+\&         4  l  Context (loop) stack processing
+\&         8  t  Trace execution
+\&        16  o  Method and overloading resolution
+\&        32  c  String/numeric conversions
+\&        64  P  Print profiling info, source file input state
+\&       128  m  Memory and SV allocation
+\&       256  f  Format processing
+\&       512  r  Regular expression parsing and execution
+\&      1024  x  Syntax tree dump
+\&      2048  u  Tainting checks
+\&      4096  U  Unofficial, User hacking (reserved for private,
+\&               unreleased use)
+\&      8192  h  Show hash randomization debug output (changes to
+\&               PL_hash_rand_bits and their origin)
+\&     16384  X  Scratchpad allocation
+\&     32768  D  Cleaning up
+\&     65536  S  Op slab allocation
+\&    131072  T  Tokenizing
+\&    262144  R  Include reference counts of dumped variables
+\&               (eg when using \-Ds)
+\&    524288  J  show s,t,P\-debug (don\*(Aqt Jump over) on opcodes within
+\&               package DB
+\&   1048576  v  Verbose: use in conjunction with other flags to
+\&               increase the verbosity of the output.  Is a no\-op on
+\&               many of the other flags
+\&   2097152  C  Copy On Write
+\&   4194304  A  Consistency checks on internal structures
+\&   8388608  q  quiet \- currently only suppresses the "EXECUTING"
+\&               message
+\&  16777216  M  trace smart match resolution
+\&  33554432  B  dump suBroutine definitions, including special
+\&               Blocks like BEGIN
+\&  67108864  L  trace Locale\-related info; what gets output is very
+\&               subject to change
+\& 134217728  i  trace PerlIO layer processing.  Set PERLIO_DEBUG to
+\&               the filename to trace to.
+\& 268435456  y  trace y///, tr/// compilation and execution
+.Ve
+.Sp
+All these flags require \fB\-DDEBUGGING\fR when you compile the Perl
+executable (but see \f(CW\*(C`:opd\*(C'\fR in Devel::Peek or "'debug' mode" in re
+which may change this).
+See the INSTALL file in the Perl source distribution
+for how to do this.
+.Sp
+If you're just trying to get a print out of each line of Perl code
+as it executes, the way that \f(CW\*(C`sh \-x\*(C'\fR provides for shell scripts,
+you can't use Perl's \fB\-D\fR switch.  Instead do this
+.Sp
+.Vb 2
+\&  # If you have "env" utility
+\&  env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl \-dS program
+\&
+\&  # Bourne shell syntax
+\&  $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl \-dS program
+\&
+\&  # csh syntax
+\&  % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl \-dS program)
+.Ve
+.Sp
+See perldebug for details and variations.
+.IP "\fB\-e\fR \fIcommandline\fR" 5
+.IX Xref "-e"
+.IX Item "-e commandline"
+may be used to enter one line of program.  If \fB\-e\fR is given, Perl
+will not look for a filename in the argument list.  Multiple \fB\-e\fR
+commands may be given to build up a multi-line script.  Make sure
+to use semicolons where you would in a normal program.
+.IP "\fB\-E\fR \fIcommandline\fR" 5
+.IX Xref "-E"
+.IX Item "-E commandline"
+behaves just like \-e, except that it implicitly
+enables all optional features (in the main compilation unit). See
+feature.
+.IP \fB\-f\fR 5
+.IX Xref "-f sitecustomize sitecustomize.pl"
+.IX Item "-f"
+Disable executing \fR\f(CI$Config\fR\fI{sitelib}/sitecustomize.pl\fR at startup.
+.Sp
+Perl can be built so that it by default will try to execute
+\&\fR\f(CI$Config\fR\fI{sitelib}/sitecustomize.pl\fR at startup (in a BEGIN block).
+This is a hook that allows the sysadmin to customize how Perl behaves.
+It can for instance be used to add entries to the \f(CW@INC\fR array to make Perl
+find modules in non-standard locations.
+.Sp
+Perl actually inserts the following code:
+.Sp
+.Vb 4
+\&    BEGIN {
+\&        do { local $!; \-f "$Config{sitelib}/sitecustomize.pl"; }
+\&            && do "$Config{sitelib}/sitecustomize.pl";
+\&    }
+.Ve
+.Sp
+Since it is an actual \f(CW\*(C`do\*(C'\fR (not a \f(CW\*(C`require\*(C'\fR), \fIsitecustomize.pl\fR
+doesn't need to return a true value. The code is run in package \f(CW\*(C`main\*(C'\fR,
+in its own lexical scope. However, if the script dies, \f(CW$@\fR will not
+be set.
+.Sp
+The value of \f(CW$Config{sitelib}\fR is also determined in C code and not
+read from \f(CW\*(C`Config.pm\*(C'\fR, which is not loaded.
+.Sp
+The code is executed \fIvery\fR early. For example, any changes made to
+\&\f(CW@INC\fR will show up in the output of `perl \-V`. Of course, \f(CW\*(C`END\*(C'\fR
+blocks will be likewise executed very late.
+.Sp
+To determine at runtime if this capability has been compiled in your
+perl, you can check the value of \f(CW$Config{usesitecustomize}\fR.
+.IP \fB\-F\fR\fIpattern\fR 5
+.IX Xref "-F"
+.IX Item "-Fpattern"
+specifies the pattern to split on for "\-a". The pattern may be
+surrounded by \f(CW\*(C`//\*(C'\fR, \f(CW""\fR, or \f(CW\*(Aq\*(Aq\fR, otherwise it will be put in single
+quotes. You can't use literal whitespace or NUL characters in the pattern.
+.Sp
+\&\fB\-F\fR implicitly sets both "\-a" and "\-n".
+.IP \fB\-g\fR 5
+.IX Xref "-g"
+.IX Item "-g"
+undefines the input record separator (\f(CW$/\fR) and thus
+enables the slurp mode. In other words, it causes Perl to read whole
+files at once, instead of line by line.
+.Sp
+This flag is a simpler alias for \-0777.
+.Sp
+Mnemonics: gobble, grab, gulp.
+.IP \fB\-h\fR 5
+.IX Xref "-h"
+.IX Item "-h"
+prints a summary of the options.
+.IP \fB\-?\fR 5
+.IX Xref "-?"
+.IX Item "-?"
+synonym for \fB\-h\fR: prints a summary of the options.
+.IP \fB\-i\fR[\fIextension\fR] 5
+.IX Xref "-i in-place"
+.IX Item "-i[extension]"
+specifies that files processed by the \f(CW\*(C`<>\*(C'\fR construct are to be
+edited in-place.  It does this by renaming the input file, opening the
+output file by the original name, and selecting that output file as the
+default for \fBprint()\fR statements.  The extension, if supplied, is used to
+modify the name of the old file to make a backup copy, following these
+rules:
+.Sp
+If no extension is supplied, and your system supports it, the original
+\&\fIfile\fR is kept open without a name while the output is redirected to
+a new file with the original \fIfilename\fR.  When perl exits, cleanly or not,
+the original \fIfile\fR is unlinked.
+.Sp
+If the extension doesn't contain a \f(CW\*(C`*\*(C'\fR, then it is appended to the
+end of the current filename as a suffix.  If the extension does
+contain one or more \f(CW\*(C`*\*(C'\fR characters, then each \f(CW\*(C`*\*(C'\fR is replaced
+with the current filename.  In Perl terms, you could think of this
+as:
+.Sp
+.Vb 1
+\&    ($backup = $extension) =~ s/\e*/$file_name/g;
+.Ve
+.Sp
+This allows you to add a prefix to the backup file, instead of (or in
+addition to) a suffix:
+.Sp
+.Vb 2
+\& $ perl \-pi\*(Aqorig_*\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA  # backup to
+\&                                           # \*(Aqorig_fileA\*(Aq
+.Ve
+.Sp
+Or even to place backup copies of the original files into another
+directory (provided the directory already exists):
+.Sp
+.Vb 2
+\& $ perl \-pi\*(Aqold/*.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA  # backup to
+\&                                               # \*(Aqold/fileA.orig\*(Aq
+.Ve
+.Sp
+These sets of one-liners are equivalent:
+.Sp
+.Vb 2
+\& $ perl \-pi \-e \*(Aqs/bar/baz/\*(Aq fileA          # overwrite current file
+\& $ perl \-pi\*(Aq*\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA       # overwrite current file
+\&
+\& $ perl \-pi\*(Aq.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA   # backup to \*(AqfileA.orig\*(Aq
+\& $ perl \-pi\*(Aq*.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA  # backup to \*(AqfileA.orig\*(Aq
+.Ve
+.Sp
+From the shell, saying
+.Sp
+.Vb 1
+\&    $ perl \-p \-i.orig \-e "s/foo/bar/; ... "
+.Ve
+.Sp
+is the same as using the program:
+.Sp
+.Vb 2
+\&    #!/usr/bin/perl \-pi.orig
+\&    s/foo/bar/;
+.Ve
+.Sp
+which is equivalent to
+.Sp
+.Vb 10
+\&    #!/usr/bin/perl
+\&    $extension = \*(Aq.orig\*(Aq;
+\&    LINE: while (<>) {
+\&        if ($ARGV ne $oldargv) {
+\&            if ($extension !~ /\e*/) {
+\&                $backup = $ARGV . $extension;
+\&            }
+\&            else {
+\&                ($backup = $extension) =~ s/\e*/$ARGV/g;
+\&            }
+\&            rename($ARGV, $backup);
+\&            open(ARGVOUT, ">$ARGV");
+\&            select(ARGVOUT);
+\&            $oldargv = $ARGV;
+\&        }
+\&        s/foo/bar/;
+\&    }
+\&    continue {
+\&        print;  # this prints to original filename
+\&    }
+\&    select(STDOUT);
+.Ve
+.Sp
+except that the \fB\-i\fR form doesn't need to compare \f(CW$ARGV\fR to \f(CW$oldargv\fR to
+know when the filename has changed.  It does, however, use ARGVOUT for
+the selected filehandle.  Note that STDOUT is restored as the default
+output filehandle after the loop.
+.Sp
+As shown above, Perl creates the backup file whether or not any output
+is actually changed.  So this is just a fancy way to copy files:
+.Sp
+.Vb 3
+\&    $ perl \-p \-i\*(Aq/some/file/path/*\*(Aq \-e 1 file1 file2 file3...
+\&or
+\&    $ perl \-p \-i\*(Aq.orig\*(Aq \-e 1 file1 file2 file3...
+.Ve
+.Sp
+You can use \f(CW\*(C`eof\*(C'\fR without parentheses to locate the end of each input
+file, in case you want to append to each file, or reset line numbering
+(see example in "eof" in perlfunc).
+.Sp
+If, for a given file, Perl is unable to create the backup file as
+specified in the extension then it will skip that file and continue on
+with the next one (if it exists).
+.Sp
+For a discussion of issues surrounding file permissions and \fB\-i\fR, see
+"Why does Perl let me delete read-only files?  Why does \-i clobber
+protected files?  Isn't this a bug in Perl?" in perlfaq5.
+.Sp
+You cannot use \fB\-i\fR to create directories or to strip extensions from
+files.
+.Sp
+Perl does not expand \f(CW\*(C`~\*(C'\fR in filenames, which is good, since some
+folks use it for their backup files:
+.Sp
+.Vb 1
+\&    $ perl \-pi~ \-e \*(Aqs/foo/bar/\*(Aq file1 file2 file3...
+.Ve
+.Sp
+Note that because \fB\-i\fR renames or deletes the original file before
+creating a new file of the same name, Unix-style soft and hard links will
+not be preserved.
+.Sp
+Finally, the \fB\-i\fR switch does not impede execution when no
+files are given on the command line.  In this case, no backup is made
+(the original file cannot, of course, be determined) and processing
+proceeds from STDIN to STDOUT as might be expected.
+.IP \fB\-I\fR\fIdirectory\fR 5
+.IX Xref "-I @INC"
+.IX Item "-Idirectory"
+Directories specified by \fB\-I\fR are prepended to the search path for
+modules (\f(CW@INC\fR).
+.IP \fB\-l\fR[\fIoctnum\fR] 5
+.IX Xref "-l $ $\\"
+.IX Item "-l[octnum]"
+enables automatic line-ending processing.  It has two separate
+effects.  First, it automatically chomps \f(CW$/\fR (the input record
+separator) when used with "\-n" or "\-p".  Second, it assigns \f(CW\*(C`$\e\*(C'\fR
+(the output record separator) to have the value of \fIoctnum\fR so
+that any print statements will have that separator added back on.
+If \fIoctnum\fR is omitted, sets \f(CW\*(C`$\e\*(C'\fR to the current value of
+\&\f(CW$/\fR.  For instance, to trim lines to 80 columns:
+.Sp
+.Vb 1
+\&    perl \-lpe \*(Aqsubstr($_, 80) = ""\*(Aq
+.Ve
+.Sp
+Note that the assignment \f(CW\*(C`$\e = $/\*(C'\fR is done when the switch is processed,
+so the input record separator can be different than the output record
+separator if the \fB\-l\fR switch is followed by a
+\&\-0 switch:
+.Sp
+.Vb 1
+\&    gnufind / \-print0 | perl \-ln0e \*(Aqprint "found $_" if \-p\*(Aq
+.Ve
+.Sp
+This sets \f(CW\*(C`$\e\*(C'\fR to newline and then sets \f(CW$/\fR to the null character.
+.IP \fB\-m\fR[\fB\-\fR]\fImodule\fR 5
+.IX Xref "-m -M"
+.IX Item "-m[-]module"
+.PD 0
+.IP \fB\-M\fR[\fB\-\fR]\fImodule\fR 5
+.IX Item "-M[-]module"
+.IP "\fB\-M\fR[\fB\-\fR]\fI'module ...'\fR" 5
+.IX Item "-M[-]'module ...'"
+.IP \fB\-[mM]\fR[\fB\-\fR]\fImodule=arg[,arg]...\fR 5
+.IX Item "-[mM][-]module=arg[,arg]..."
+.PD
+\&\fB\-m\fR\fImodule\fR executes \f(CW\*(C`use\*(C'\fR \fImodule\fR \f(CW\*(C`();\*(C'\fR before executing your
+program.  This loads the module, but does not call its \f(CW\*(C`import\*(C'\fR method,
+so does not import subroutines and does not give effect to a pragma.
+.Sp
+\&\fB\-M\fR\fImodule\fR executes \f(CW\*(C`use\*(C'\fR \fImodule\fR \f(CW\*(C`;\*(C'\fR before executing your
+program.  This loads the module and calls its \f(CW\*(C`import\*(C'\fR method, causing
+the module to have its default effect, typically importing subroutines
+or giving effect to a pragma.
+You can use quotes to add extra code after the module name,
+e.g., \f(CW\*(Aq\-M\fR\f(CIMODULE\fR\f(CW qw(foo bar)\*(Aq\fR.
+.Sp
+If the first character after the \fB\-M\fR or \fB\-m\fR is a dash (\fB\-\fR)
+then the 'use' is replaced with 'no'.
+This makes no difference for \fB\-m\fR.
+.Sp
+A little builtin syntactic sugar means you can also say
+\&\fB\-m\fR\f(BIMODULE\fR\fB=foo,bar\fR or \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR as a shortcut for
+\&\fB'\-M\fR\f(BIMODULE\fR\fB qw(foo bar)'\fR.  This avoids the need to use quotes when
+importing symbols.  The actual code generated by \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR is
+\&\f(CW\*(C`use module split(/,/,q{foo,bar})\*(C'\fR.  Note that the \f(CW\*(C`=\*(C'\fR form
+removes the distinction between \fB\-m\fR and \fB\-M\fR; that is,
+\&\fB\-m\fR\f(BIMODULE\fR\fB=foo,bar\fR is the same as \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR.
+.Sp
+A consequence of the \f(CW\*(C`split\*(C'\fR formulation
+is that \fB\-M\fR\f(BIMODULE\fR\fB=number\fR never does a version check,
+unless \f(CW\*(C`\fR\f(CIMODULE\fR\f(CW::import()\*(C'\fR itself is set up to do a version check, which
+could happen for example if \fIMODULE\fR inherits from Exporter.
+.IP \fB\-n\fR 5
+.IX Xref "-n"
+.IX Item "-n"
+causes Perl to assume the following loop around your program, which
+makes it iterate over filename arguments somewhat like \fIsed \-n\fR or
+\&\fIawk\fR:
+.Sp
+.Vb 4
+\&  LINE:
+\&    while (<>) {
+\&        ...             # your program goes here
+\&    }
+.Ve
+.Sp
+Note that the lines are not printed by default.  See "\-p" to have
+lines printed.  If a file named by an argument cannot be opened for
+some reason, Perl warns you about it and moves on to the next file.
+.Sp
+Also note that \f(CW\*(C`<>\*(C'\fR passes command line arguments to
+"open" in perlfunc, which doesn't necessarily interpret them as file names.
+See  perlop for possible security implications.
+.Sp
+Here is an efficient way to delete all files that haven't been modified for
+at least a week:
+.Sp
+.Vb 1
+\&    find . \-mtime +7 \-print | perl \-nle unlink
+.Ve
+.Sp
+This is faster than using the \fB\-exec\fR switch of \fIfind\fR because you don't
+have to start a process on every filename found (but it's not faster
+than using the \fB\-delete\fR switch available in newer versions of \fIfind\fR.
+It does suffer from the bug of mishandling newlines in pathnames, which
+you can fix if you follow the example under
+\&\-0.
+.Sp
+\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`END\*(C'\fR blocks may be used to capture control before or after
+the implicit program loop, just as in \fIawk\fR.
+.IP \fB\-p\fR 5
+.IX Xref "-p"
+.IX Item "-p"
+causes Perl to assume the following loop around your program, which
+makes it iterate over filename arguments somewhat like \fIsed\fR:
+.Sp
+.Vb 6
+\&  LINE:
+\&    while (<>) {
+\&        ...             # your program goes here
+\&    } continue {
+\&        print or die "\-p destination: $!\en";
+\&    }
+.Ve
+.Sp
+If a file named by an argument cannot be opened for some reason, Perl
+warns you about it, and moves on to the next file.  Note that the
+lines are printed automatically.  An error occurring during printing is
+treated as fatal.  To suppress printing use the "\-n" switch.  A \fB\-p\fR
+overrides a \fB\-n\fR switch.
+.Sp
+\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`END\*(C'\fR blocks may be used to capture control before or after
+the implicit loop, just as in \fIawk\fR.
+.IP \fB\-s\fR 5
+.IX Xref "-s"
+.IX Item "-s"
+enables rudimentary switch parsing for switches on the command
+line after the program name but before any filename arguments (or before
+an argument of \fB\-\-\fR).  Any switch found there is removed from \f(CW@ARGV\fR and sets the
+corresponding variable in the Perl program, in the main package.  The following program
+prints "1" if the program is invoked with a \fB\-xyz\fR switch, and "abc"
+if it is invoked with \fB\-xyz=abc\fR.
+.Sp
+.Vb 2
+\&    #!/usr/bin/perl \-s
+\&    if ($xyz) { print "$xyz\en" }
+.Ve
+.Sp
+Do note that a switch like \fB\-\-help\fR creates the variable \f(CW\*(C`${\-help}\*(C'\fR, which is
+not compliant with \f(CW\*(C`use strict "refs"\*(C'\fR.  Also, when using this option on a
+script with warnings enabled you may get a lot of spurious "used only once"
+warnings. For these reasons, use of \fB\-s\fR is discouraged. See Getopt::Long
+for much more flexible switch parsing.
+.IP \fB\-S\fR 5
+.IX Xref "-S"
+.IX Item "-S"
+makes Perl use the "PATH" environment variable to search for the
+program unless the name of the program contains path separators.
+.Sp
+On some platforms, this also makes Perl append suffixes to the
+filename while searching for it.  For example, on Win32 platforms,
+the ".bat" and ".cmd" suffixes are appended if a lookup for the
+original name fails, and if the name does not already end in one
+of those suffixes.  If your Perl was compiled with \f(CW\*(C`DEBUGGING\*(C'\fR turned
+on, using the \-Dp switch to Perl shows how the search
+progresses.
+.Sp
+Typically this is used to emulate \f(CW\*(C`#!\*(C'\fR startup on platforms that don't
+support \f(CW\*(C`#!\*(C'\fR.  It's also convenient when debugging a script that uses \f(CW\*(C`#!\*(C'\fR,
+and is thus normally found by the shell's \f(CW$PATH\fR search mechanism.
+.Sp
+This example works on many platforms that have a shell compatible with
+Bourne shell:
+.Sp
+.Vb 3
+\&    #!/usr/bin/perl
+\&    eval \*(Aqexec /usr/bin/perl \-wS $0 ${1+"$@"}\*(Aq
+\&            if 0; # ^ Run only under a shell
+.Ve
+.Sp
+The system ignores the first line and feeds the program to \fI/bin/sh\fR,
+which proceeds to try to execute the Perl program as a shell script.
+The shell executes the second line as a normal shell command, and thus
+starts up the Perl interpreter.  On some systems \f(CW$0\fR doesn't always
+contain the full pathname, so the "\-S" tells Perl to search for the
+program if necessary.  After Perl locates the program, it parses the
+lines and ignores them because the check 'if 0' is never true.
+If the program will be interpreted by csh, you will need
+to replace \f(CW\*(C`${1+"$@"}\*(C'\fR with \f(CW$*\fR, even though that doesn't understand
+embedded spaces (and such) in the argument list.  To start up \fIsh\fR rather
+than \fIcsh\fR, some systems may have to replace the \f(CW\*(C`#!\*(C'\fR line with a line
+containing just a colon, which will be politely ignored by Perl.  Other
+systems can't control that, and need a totally devious construct that
+will work under any of \fIcsh\fR, \fIsh\fR, or Perl, such as the following:
+.Sp
+.Vb 3
+\&        eval \*(Aq(exit $?0)\*(Aq && eval \*(Aqexec perl \-wS $0 ${1+"$@"}\*(Aq
+\&        & eval \*(Aqexec /usr/bin/perl \-wS $0 $argv:q\*(Aq
+\&                if 0; # ^ Run only under a shell
+.Ve
+.Sp
+If the filename supplied contains directory separators (and so is an
+absolute or relative pathname), and if that file is not found,
+platforms that append file extensions will do so and try to look
+for the file with those extensions added, one by one.
+.Sp
+On DOS-like platforms, if the program does not contain directory
+separators, it will first be searched for in the current directory
+before being searched for on the PATH.  On Unix platforms, the
+program will be searched for strictly on the PATH.
+.IP \fB\-t\fR 5
+.IX Xref "-t"
+.IX Item "-t"
+Like "\-T", but taint checks will issue warnings rather than fatal
+errors.  These warnings can now be controlled normally with \f(CWno warnings
+qw(taint)\fR.
+.Sp
+\&\fBNote: This is not a substitute for \fR\f(CB\*(C`\-T\*(C'\fR\fB!\fR This is meant to be
+used \fIonly\fR as a temporary development aid while securing legacy code:
+for real production code and for new secure code written from scratch,
+always use the real "\-T".
+.Sp
+This has no effect if your perl was built without taint support.
+.IP \fB\-T\fR 5
+.IX Xref "-T"
+.IX Item "-T"
+turns on "taint" so you can test them.  Ordinarily
+these checks are done only when running setuid or setgid.  It's a
+good idea to turn them on explicitly for programs that run on behalf
+of someone else whom you might not necessarily trust, such as CGI
+programs or any internet servers you might write in Perl.  See
+perlsec for details.  For security reasons, this option must be
+seen by Perl quite early; usually this means it must appear early
+on the command line or in the \f(CW\*(C`#!\*(C'\fR line for systems which support
+that construct.
+.IP \fB\-u\fR 5
+.IX Xref "-u"
+.IX Item "-u"
+This switch causes Perl to dump core after compiling your
+program.  You can then in theory take this core dump and turn it
+into an executable file by using the \fIundump\fR program (not supplied).
+This speeds startup at the expense of some disk space (which you
+can minimize by stripping the executable).  (Still, a "hello world"
+executable comes out to about 200K on my machine.)  If you want to
+execute a portion of your program before dumping, use the \f(CWCORE::dump()\fR
+function instead.  Note: availability of \fIundump\fR is platform
+specific and may not be available for a specific port of Perl.
+.IP \fB\-U\fR 5
+.IX Xref "-U"
+.IX Item "-U"
+allows Perl to do unsafe operations.  Currently the only "unsafe"
+operations are attempting to unlink directories while running as superuser
+and running setuid programs with fatal taint checks turned into warnings.
+Note that warnings must be enabled along with this option to actually
+\&\fIgenerate\fR the taint-check warnings.
+.IP \fB\-v\fR 5
+.IX Xref "-v"
+.IX Item "-v"
+prints the version and patchlevel of your perl executable.
+.IP \fB\-V\fR 5
+.IX Xref "-V"
+.IX Item "-V"
+prints summary of the major perl configuration values and the current
+values of \f(CW@INC\fR.
+.IP \fB\-V:\fR\fIconfigvar\fR 5
+.IX Item "-V:configvar"
+Prints to STDOUT the value of the named configuration variable(s),
+with multiples when your \f(CW\*(C`\fR\f(CIconfigvar\fR\f(CW\*(C'\fR argument looks like a regex (has
+non-letters).  For example:
+.Sp
+.Vb 12
+\&    $ perl \-V:libc
+\&        libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq;
+\&    $ perl \-V:lib.
+\&        libs=\*(Aq\-lnsl \-lgdbm \-ldb \-ldl \-lm \-lcrypt \-lutil \-lc\*(Aq;
+\&        libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq;
+\&    $ perl \-V:lib.*
+\&        libpth=\*(Aq/usr/local/lib /lib /usr/lib\*(Aq;
+\&        libs=\*(Aq\-lnsl \-lgdbm \-ldb \-ldl \-lm \-lcrypt \-lutil \-lc\*(Aq;
+\&        lib_ext=\*(Aq.a\*(Aq;
+\&        libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq;
+\&        libperl=\*(Aqlibperl.a\*(Aq;
+\&        ....
+.Ve
+.Sp
+Additionally, extra colons can be used to control formatting.  A
+trailing colon suppresses the linefeed and terminator ";", allowing
+you to embed queries into shell commands.  (mnemonic: PATH separator
+":".)
+.Sp
+.Vb 2
+\&    $ echo "compression\-vars: " \`perl \-V:z.*: \` " are here !"
+\&    compression\-vars:  zcat=\*(Aq\*(Aq zip=\*(Aqzip\*(Aq  are here !
+.Ve
+.Sp
+A leading colon removes the "name=" part of the response, this allows
+you to map to the name you need.  (mnemonic: empty label)
+.Sp
+.Vb 2
+\&    $ echo "goodvfork="\`./perl \-Ilib \-V::usevfork\`
+\&    goodvfork=false;
+.Ve
+.Sp
+Leading and trailing colons can be used together if you need
+positional parameter values without the names.  Note that in the case
+below, the \f(CW\*(C`PERL_API\*(C'\fR params are returned in alphabetical order.
+.Sp
+.Vb 2
+\&    $ echo building_on \`perl \-V::osname: \-V::PERL_API_.*:\` now
+\&    building_on \*(Aqlinux\*(Aq \*(Aq5\*(Aq \*(Aq1\*(Aq \*(Aq9\*(Aq now
+.Ve
+.IP \fB\-w\fR 5
+.IX Xref "-w"
+.IX Item "-w"
+prints warnings about dubious constructs, such as variable names
+mentioned only once and scalar variables used
+before being set; redefined subroutines; references to undefined
+filehandles; filehandles opened read-only that you are attempting
+to write on; values used as a number that don't \fIlook\fR like numbers;
+using an array as though it were a scalar; if your subroutines
+recurse more than 100 deep; and innumerable other things.
+.Sp
+This switch really just enables the global \f(CW$^W\fR variable; normally,
+the lexically scoped \f(CW\*(C`use warnings\*(C'\fR pragma is preferred. You
+can disable or promote into fatal errors specific warnings using
+\&\f(CW\*(C`_\|_WARN_\|_\*(C'\fR hooks, as described in perlvar and "warn" in perlfunc.
+See also perldiag and perltrap.  A fine-grained warning
+facility is also available if you want to manipulate entire classes
+of warnings; see warnings.
+.IP \fB\-W\fR 5
+.IX Xref "-W"
+.IX Item "-W"
+Enables all warnings regardless of \f(CW\*(C`no warnings\*(C'\fR or \f(CW$^W\fR.
+See warnings.
+.IP \fB\-X\fR 5
+.IX Xref "-X"
+.IX Item "-X"
+Disables all warnings regardless of \f(CW\*(C`use warnings\*(C'\fR or \f(CW$^W\fR.
+See warnings.
+.Sp
+Forbidden in \f(CW"PERL5OPT"\fR.
+.IP \fB\-x\fR 5
+.IX Xref "-x"
+.IX Item "-x"
+.PD 0
+.IP \fB\-x\fR\fIdirectory\fR 5
+.IX Item "-xdirectory"
+.PD
+tells Perl that the program is embedded in a larger chunk of unrelated
+text, such as in a mail message.  Leading garbage will be
+discarded until the first line that starts with \f(CW\*(C`#!\*(C'\fR and contains the
+string "perl".  Any meaningful switches on that line will be applied.
+.Sp
+All references to line numbers by the program (warnings, errors, ...)
+will treat the \f(CW\*(C`#!\*(C'\fR line as the first line.
+Thus a warning on the 2nd line of the program, which is on the 100th
+line in the file will be reported as line 2, not as line 100.
+This can be overridden by using the \f(CW\*(C`#line\*(C'\fR directive.
+(See "Plain Old Comments (Not!)" in perlsyn)
+.Sp
+If a directory name is specified, Perl will switch to that directory
+before running the program.  The \fB\-x\fR switch controls only the
+disposal of leading garbage.  The program must be terminated with
+\&\f(CW\*(C`_\|_END_\|_\*(C'\fR if there is trailing garbage to be ignored;  the program
+can process any or all of the trailing garbage via the \f(CW\*(C`DATA\*(C'\fR filehandle
+if desired.
+.Sp
+The directory, if specified, must appear immediately following the \fB\-x\fR
+with no intervening whitespace.
+.SH ENVIRONMENT
+.IX Xref "perl, environment variables"
+.IX Header "ENVIRONMENT"
+.IP HOME 12
+.IX Xref "HOME"
+.IX Item "HOME"
+Used if \f(CW\*(C`chdir\*(C'\fR has no argument.
+.IP LOGDIR 12
+.IX Xref "LOGDIR"
+.IX Item "LOGDIR"
+Used if \f(CW\*(C`chdir\*(C'\fR has no argument and "HOME" is not set.
+.IP PATH 12
+.IX Xref "PATH"
+.IX Item "PATH"
+Used in executing subprocesses, and in finding the program if "\-S" is
+used.
+.IP PERL5LIB 12
+.IX Xref "PERL5LIB"
+.IX Item "PERL5LIB"
+A list of directories in which to look for Perl library files before
+looking in the standard library.
+Any architecture-specific and version-specific directories,
+such as \fIversion/archname/\fR, \fIversion/\fR, or \fIarchname/\fR under the
+specified locations are automatically included if they exist, with this
+lookup done at interpreter startup time.  In addition, any directories
+matching the entries in \f(CW$Config{inc_version_list}\fR are added.
+(These typically would be for older compatible perl versions installed
+in the same directory tree.)
+.Sp
+If PERL5LIB is not defined, "PERLLIB" is used.  Directories are separated
+(like in PATH) by a colon on Unixish platforms and by a semicolon on
+Windows (the proper path separator being given by the command \f(CW\*(C`perl
+\&\-V:\fR\f(CIpath_sep\fR\f(CW\*(C'\fR).
+.Sp
+When running taint checks, either because the program was running setuid or
+setgid, or the "\-T" or "\-t" switch was specified, neither PERL5LIB nor
+"PERLLIB" is consulted. The program should instead say:
+.Sp
+.Vb 1
+\&    use lib "/my/directory";
+.Ve
+.IP PERL5OPT 12
+.IX Xref "PERL5OPT"
+.IX Item "PERL5OPT"
+Command-line options (switches).  Switches in this variable are treated
+as if they were on every Perl command line.  Only the \fB\-[CDIMTUWdmtw]\fR
+switches are allowed.  When running taint checks (either because the
+program was running setuid or setgid, or because the "\-T" or "\-t"
+switch was used), this variable is ignored.  If PERL5OPT begins with
+\&\fB\-T\fR, tainting will be enabled and subsequent options ignored.  If
+PERL5OPT begins with \fB\-t\fR, tainting will be enabled, a writable dot
+removed from \f(CW@INC\fR, and subsequent options honored.
+.IP PERLIO 12
+.IX Xref "PERLIO"
+.IX Item "PERLIO"
+A space (or colon) separated list of PerlIO layers. If perl is built
+to use PerlIO system for IO (the default) these layers affect Perl's IO.
+.Sp
+It is conventional to start layer names with a colon (for example, \f(CW\*(C`:perlio\*(C'\fR) to
+emphasize their similarity to variable "attributes". But the code that parses
+layer specification strings, which is also used to decode the PERLIO
+environment variable, treats the colon as a separator.
+.Sp
+An unset or empty PERLIO is equivalent to the default set of layers for
+your platform; for example, \f(CW\*(C`:unix:perlio\*(C'\fR on Unix-like systems
+and \f(CW\*(C`:unix:crlf\*(C'\fR on Windows and other DOS-like systems.
+.Sp
+The list becomes the default for \fIall\fR Perl's IO. Consequently only built-in
+layers can appear in this list, as external layers (such as \f(CW:encoding()\fR) need
+IO in order to load them!  See "open pragma" for how to add external
+encodings as defaults.
+.Sp
+Layers it makes sense to include in the PERLIO environment
+variable are briefly summarized below. For more details see PerlIO.
+.RS 12
+.IP :crlf 8
+.IX Xref ":crlf"
+.IX Item ":crlf"
+A layer which does CRLF to \f(CW"\en"\fR translation distinguishing "text" and
+"binary" files in the manner of MS-DOS and similar operating systems,
+and also provides buffering similar to \f(CW\*(C`:perlio\*(C'\fR on these architectures.
+.IP :perlio 8
+.IX Xref ":perlio"
+.IX Item ":perlio"
+This is a re-implementation of stdio-like buffering written as a
+PerlIO layer.  As such it will call whatever layer is below it for
+its operations, typically \f(CW\*(C`:unix\*(C'\fR.
+.IP :stdio 8
+.IX Xref ":stdio"
+.IX Item ":stdio"
+This layer provides a PerlIO interface by wrapping system's ANSI C "stdio"
+library calls. The layer provides both buffering and IO.
+Note that the \f(CW\*(C`:stdio\*(C'\fR layer does \fInot\fR do CRLF translation even if that
+is the platform's normal behaviour. You will need a \f(CW\*(C`:crlf\*(C'\fR layer above it
+to do that.
+.IP :unix 8
+.IX Xref ":unix"
+.IX Item ":unix"
+Low-level layer that calls \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`write\*(C'\fR, \f(CW\*(C`lseek\*(C'\fR, etc.
+.RE
+.RS 12
+.Sp
+The default set of layers should give acceptable results on all platforms.
+.Sp
+For Unix platforms that will be the equivalent of ":unix:perlio" or ":stdio".
+Configure is set up to prefer the ":stdio" implementation if the system's library
+provides for fast access to the buffer (not common on modern architectures);
+otherwise, it uses the ":unix:perlio" implementation.
+.Sp
+On Win32 the default in this release (5.30) is ":unix:crlf". Win32's ":stdio"
+has a number of bugs/mis\-features for Perl IO which are somewhat depending
+on the version and vendor of the C compiler. Using our own \f(CW\*(C`:crlf\*(C'\fR layer as
+the buffer avoids those issues and makes things more uniform.
+.Sp
+This release (5.30) uses \f(CW\*(C`:unix\*(C'\fR as the bottom layer on Win32, and so still
+uses the C compiler's numeric file descriptor routines.
+.Sp
+The PERLIO environment variable is completely ignored when Perl
+is run in taint mode.
+.RE
+.IP PERLIO_DEBUG 12
+.IX Xref "PERLIO_DEBUG"
+.IX Item "PERLIO_DEBUG"
+If set to the name of a file or device when Perl is run with the
+\&\-Di command-line switch, the logging of certain operations
+of the PerlIO subsystem will be redirected to the specified file rather
+than going to stderr, which is the default. The file is opened in append
+mode. Typical uses are in Unix:
+.Sp
+.Vb 1
+\&   % env PERLIO_DEBUG=/tmp/perlio.log perl \-Di script ...
+.Ve
+.Sp
+and under Win32, the approximately equivalent:
+.Sp
+.Vb 2
+\&   > set PERLIO_DEBUG=CON
+\&   perl \-Di script ...
+.Ve
+.Sp
+This functionality is disabled for setuid scripts, for scripts run
+with "\-T", and for scripts run on a Perl built without \f(CW\*(C`\-DDEBUGGING\*(C'\fR
+support.
+.IP PERLLIB 12
+.IX Xref "PERLLIB"
+.IX Item "PERLLIB"
+A list of directories in which to look for Perl library
+files before looking in the standard library.
+If "PERL5LIB" is defined, PERLLIB is not used.
+.Sp
+The PERLLIB environment variable is completely ignored when Perl
+is run in taint mode.
+.IP PERL5DB 12
+.IX Xref "PERL5DB"
+.IX Item "PERL5DB"
+The command used to load the debugger code.  The default is:
+.Sp
+.Vb 1
+\&        BEGIN { require "perl5db.pl" }
+.Ve
+.Sp
+The PERL5DB environment variable is only used when Perl is started with
+a bare "\-d" switch.
+.IP PERL5DB_THREADED 12
+.IX Xref "PERL5DB_THREADED"
+.IX Item "PERL5DB_THREADED"
+If set to a true value, indicates to the debugger that the code being
+debugged uses threads.
+.IP "PERL5SHELL (specific to the Win32 port)" 12
+.IX Xref "PERL5SHELL"
+.IX Item "PERL5SHELL (specific to the Win32 port)"
+On Win32 ports only, may be set to an alternative shell that Perl must use
+internally for executing "backtick" commands or \fBsystem()\fR.  Default is
+\&\f(CW\*(C`cmd.exe /x/d/c\*(C'\fR on WindowsNT and \f(CW\*(C`command.com /c\*(C'\fR on Windows95.  The
+value is considered space-separated.  Precede any character that
+needs to be protected, like a space or backslash, with another backslash.
+.Sp
+Note that Perl doesn't use COMSPEC for this purpose because
+COMSPEC has a high degree of variability among users, leading to
+portability concerns.  Besides, Perl can use a shell that may not be
+fit for interactive use, and setting COMSPEC to such a shell may
+interfere with the proper functioning of other programs (which usually
+look in COMSPEC to find a shell fit for interactive use).
+.Sp
+Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
+when running external commands.  It is recommended that
+you explicitly set (or delete) \f(CW$ENV{PERL5SHELL}\fR when running
+in taint mode under Windows.
+.IP "PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)" 12
+.IX Xref "PERL_ALLOW_NON_IFS_LSP"
+.IX Item "PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)"
+Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers).
+Perl normally searches for an IFS-compatible LSP because this is required
+for its emulation of Windows sockets as real filehandles.  However, this may
+cause problems if you have a firewall such as \fIMcAfee Guardian\fR, which requires
+that all applications use its LSP but which is not IFS-compatible, because clearly
+Perl will normally avoid using such an LSP.
+.Sp
+Setting this environment variable to 1 means that Perl will simply use the
+first suitable LSP enumerated in the catalog, which keeps \fIMcAfee Guardian\fR
+happy\-\-and in that particular case Perl still works too because \fIMcAfee
+Guardian\fR's LSP actually plays other games which allow applications
+requiring IFS compatibility to work.
+.IP PERL_DEBUG_MSTATS 12
+.IX Xref "PERL_DEBUG_MSTATS"
+.IX Item "PERL_DEBUG_MSTATS"
+Relevant only if Perl is compiled with the \f(CW\*(C`malloc\*(C'\fR included with the Perl
+distribution; that is, if \f(CW\*(C`perl \-V:d_mymalloc\*(C'\fR is "define".
+.Sp
+If set, this dumps out memory statistics after execution.  If set
+to an integer greater than one, also dumps out memory statistics
+after compilation.
+.IP PERL_DESTRUCT_LEVEL 12
+.IX Xref "PERL_DESTRUCT_LEVEL"
+.IX Item "PERL_DESTRUCT_LEVEL"
+Controls the behaviour of global destruction of objects and other
+references.  See "PERL_DESTRUCT_LEVEL" in perlhacktips for more information.
+.IP PERL_DL_NONLAZY 12
+.IX Xref "PERL_DL_NONLAZY"
+.IX Item "PERL_DL_NONLAZY"
+Set to \f(CW"1"\fR to have Perl resolve \fIall\fR undefined symbols when it loads
+a dynamic library.  The default behaviour is to resolve symbols when
+they are used.  Setting this variable is useful during testing of
+extensions, as it ensures that you get an error on misspelled function
+names even if the test suite doesn't call them.
+.IP PERL_ENCODING 12
+.IX Xref "PERL_ENCODING"
+.IX Item "PERL_ENCODING"
+If using the \f(CW\*(C`use encoding\*(C'\fR pragma without an explicit encoding name, the
+PERL_ENCODING environment variable is consulted for an encoding name.
+.IP PERL_HASH_SEED 12
+.IX Xref "PERL_HASH_SEED"
+.IX Item "PERL_HASH_SEED"
+(Since Perl 5.8.1, new semantics in Perl 5.18.0)  Used to override
+the randomization of Perl's internal hash function. The value is expressed
+in hexadecimal, and may include a leading 0x. Truncated patterns
+are treated as though they are suffixed with sufficient 0's as required.
+.Sp
+If the option is provided, and \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR is NOT set, then
+a value of '0' implies \f(CW\*(C`PERL_PERTURB_KEYS=0\*(C'\fR/\f(CW\*(C`PERL_PERTURB_KEYS=NO\*(C'\fR
+and any other value implies
+\&\f(CW\*(C`PERL_PERTURB_KEYS=2\*(C'\fR/\f(CW\*(C`PERL_PERTURB_KEYS=DETERMINISTIC\*(C'\fR. See the
+documentation for PERL_PERTURB_KEYS for important
+caveats regarding the \f(CW\*(C`DETERMINISTIC\*(C'\fR mode.
+.Sp
+\&\fBPLEASE NOTE: The hash seed is sensitive information\fR. Hashes are
+randomized to protect against local and remote attacks against Perl
+code. By manually setting a seed, this protection may be partially or
+completely lost.
+.Sp
+See "Algorithmic Complexity Attacks" in perlsec, "PERL_PERTURB_KEYS", and
+"PERL_HASH_SEED_DEBUG" for more information.
+.IP PERL_PERTURB_KEYS 12
+.IX Xref "PERL_PERTURB_KEYS"
+.IX Item "PERL_PERTURB_KEYS"
+(Since Perl 5.18.0)  Set to \f(CW"0"\fR or \f(CW"NO"\fR then traversing keys
+will be repeatable from run to run for the same \f(CW\*(C`PERL_HASH_SEED\*(C'\fR.
+Insertion into a hash will not change the order, except to provide
+for more space in the hash. When combined with setting PERL_HASH_SEED
+this mode is as close to pre 5.18 behavior as you can get.
+.Sp
+When set to \f(CW"1"\fR or \f(CW"RANDOM"\fR then traversing keys will be randomized.
+Every time a hash is inserted into the key order will change in a random
+fashion. The order may not be repeatable in a following program run
+even if the PERL_HASH_SEED has been specified. This is the default
+mode for perl when no PERL_HASH_SEED has been explicitly provided.
+.Sp
+When set to \f(CW"2"\fR or \f(CW"DETERMINISTIC"\fR then inserting keys into a hash
+will cause the key order to change, but in a way that is repeatable from
+program run to program run, provided that the same hash seed is used,
+and that the code does not itself perform any non-deterministic
+operations and also provided exactly the same environment context.
+Adding or removing an environment variable may and likely will change
+the key order. If any part of the code builds a hash using non\-
+deterministic keys, for instance a hash keyed by the stringified form of
+a reference, or the address of the objects it contains, then this may
+and likely will have a global effect on the key order of *every* hash in
+the process. To work properly this setting MUST be coupled with the
+PERL_HASH_SEED to produce deterministic results,
+and in fact, if you do set the \f(CW\*(C`PERL_HASH_SEED\*(C'\fR explicitly you do not
+need to set this as well, it will be automatically set to this mode.
+.Sp
+\&\fBNOTE:\fR Use of this option is considered insecure, and is intended only
+for debugging non-deterministic behavior in Perl's hash function. Do
+not use it in production.
+.Sp
+See "Algorithmic Complexity Attacks" in perlsec and "PERL_HASH_SEED"
+and "PERL_HASH_SEED_DEBUG" for more information. You can get and set the
+key traversal mask for a specific hash by using the \f(CWhash_traversal_mask()\fR
+function from Hash::Util.
+.IP PERL_HASH_SEED_DEBUG 12
+.IX Xref "PERL_HASH_SEED_DEBUG"
+.IX Item "PERL_HASH_SEED_DEBUG"
+(Since Perl 5.8.1.)  Set to \f(CW"1"\fR to display (to STDERR) information
+about the hash function, seed, and what type of key traversal
+randomization is in effect at the beginning of execution.  This, combined
+with "PERL_HASH_SEED" and "PERL_PERTURB_KEYS" is intended to aid in
+debugging nondeterministic behaviour caused by hash randomization.
+.Sp
+\&\fBNote\fR that any information about the hash function, especially the hash
+seed is \fBsensitive information\fR: by knowing it, one can craft a denial-of-service
+attack against Perl code, even remotely; see "Algorithmic Complexity Attacks" in perlsec
+for more information. \fBDo not disclose the hash seed\fR to people who
+don't need to know it. See also \f(CWhash_seed()\fR and
+\&\f(CWhash_traversal_mask()\fR.
+.Sp
+An example output might be:
+.Sp
+.Vb 1
+\& HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
+.Ve
+.IP PERL_MEM_LOG 12
+.IX Xref "PERL_MEM_LOG"
+.IX Item "PERL_MEM_LOG"
+If your Perl was configured with \fB\-Accflags=\-DPERL_MEM_LOG\fR, setting
+the environment variable \f(CW\*(C`PERL_MEM_LOG\*(C'\fR enables logging debug
+messages. The value has the form \f(CW\*(C`<\fR\f(CInumber\fR\f(CW>[m][s][t]\*(C'\fR, where
+\&\f(CW\*(C`\fR\f(CInumber\fR\f(CW\*(C'\fR is the file descriptor number you want to write to (2 is
+default), and the combination of letters specifies that you want
+information about (m)emory and/or (s)v, optionally with
+(t)imestamps. For example, \f(CW\*(C`PERL_MEM_LOG=1mst\*(C'\fR logs all
+information to stdout. You can write to other opened file descriptors
+in a variety of ways:
+.Sp
+.Vb 1
+\&  $ 3>foo3 PERL_MEM_LOG=3m perl ...
+.Ve
+.IP "PERL_ROOT (specific to the VMS port)" 12
+.IX Xref "PERL_ROOT"
+.IX Item "PERL_ROOT (specific to the VMS port)"
+A translation-concealed rooted logical name that contains Perl and the
+logical device for the \f(CW@INC\fR path on VMS only.  Other logical names that
+affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and
+SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in
+perlvms and in \fIREADME.vms\fR in the Perl source distribution.
+.IP PERL_SIGNALS 12
+.IX Xref "PERL_SIGNALS"
+.IX Item "PERL_SIGNALS"
+Available in Perls 5.8.1 and later.  If set to \f(CW"unsafe"\fR, the pre\-Perl\-5.8.0
+signal behaviour (which is immediate but unsafe) is restored.  If set
+to \f(CW\*(C`safe\*(C'\fR, then safe (but deferred) signals are used.  See
+"Deferred Signals (Safe Signals)" in perlipc.
+.IP PERL_UNICODE 12
+.IX Xref "PERL_UNICODE"
+.IX Item "PERL_UNICODE"
+Equivalent to the \-C command-line switch.  Note
+that this is not a boolean variable. Setting this to \f(CW"1"\fR is not the
+right way to "enable Unicode" (whatever that would mean).  You can use
+\&\f(CW"0"\fR to "disable Unicode", though (or alternatively unset PERL_UNICODE
+in your shell before starting Perl).  See the description of the
+\&\-C switch for more information.
+.IP PERL_USE_UNSAFE_INC 12
+.IX Xref "PERL_USE_UNSAFE_INC"
+.IX Item "PERL_USE_UNSAFE_INC"
+If perl has been configured to not have the current directory in
+\&\f(CW@INC\fR by default, this variable can be set to \f(CW"1"\fR
+to reinstate it.  It's primarily intended for use while building and
+testing modules that have not been updated to deal with "." not being in
+\&\f(CW@INC\fR and should not be set in the environment for day-to-day use.
+.IP "SYS$LOGIN (specific to the VMS port)" 12
+.IX Xref "SYS$LOGIN"
+.IX Item "SYS$LOGIN (specific to the VMS port)"
+Used if chdir has no argument and "HOME" and "LOGDIR" are not set.
+.IP PERL_INTERNAL_RAND_SEED 12
+.IX Xref "PERL_INTERNAL_RAND_SEED"
+.IX Item "PERL_INTERNAL_RAND_SEED"
+Set to a non-negative integer to seed the random number generator used
+internally by perl for a variety of purposes.
+.Sp
+Ignored if perl is run setuid or setgid.  Used only for some limited
+startup randomization (hash keys) if \f(CW\*(C`\-T\*(C'\fR or \f(CW\*(C`\-t\*(C'\fR perl is started
+with tainting enabled.
+.Sp
+Perl may be built to ignore this variable.
+.IP PERL_RAND_SEED 12
+.IX Xref "PERL_RAND_SEED"
+.IX Item "PERL_RAND_SEED"
+When set to an integer value this value will be used to seed the perl
+internal random number generator used for \f(CWrand()\fR when it is used
+without an explicit \f(CWsrand()\fR call or for when an explicit no-argument
+\&\f(CWsrand()\fR call is made.
+.Sp
+Normally calling \f(CWrand()\fR prior to calling \f(CWsrand()\fR or calling
+\&\f(CWsrand()\fR explicitly with no arguments should result in the random
+number generator using "best efforts" to seed the generator state with a
+relatively high quality random seed. When this environment variable is
+set then the seeds used will be deterministically computed from the
+value provided in the env var in such a way that the application process
+and any forks or threads should continue to have their own unique seed but
+that the program may be run twice with identical results as far as
+\&\f(CWrand()\fR goes (assuming all else is equal).
+.Sp
+PERL_RAND_SEED is intended for performance measurements and debugging
+and is explicitly NOT intended for stable testing. The only guarantee is
+that a specific perl executable will produce the same results twice in a
+row, there is no guarantee that the results will be the same between
+perl releases or on different architectures.
+.Sp
+Ignored if perl is run setuid or setgid.
+.PP
+Perl also has environment variables that control how Perl handles data
+specific to particular natural languages; see perllocale.
+.PP
+Perl and its various modules and components, including its test frameworks,
+may sometimes make use of certain other environment variables.  Some of
+these are specific to a particular platform.  Please consult the
+appropriate module documentation and any documentation for your platform
+(like perlsolaris, perllinux, perlmacosx, perlwin32, etc) for
+variables peculiar to those specific situations.
+.PP
+Perl makes all environment variables available to the program being
+executed, and passes these along to any child processes it starts.
+However, programs running setuid would do well to execute the following
+lines before doing anything else, just to keep people honest:
+.PP
+.Vb 3
+\&    $ENV{PATH}  = "/bin:/usr/bin";    # or whatever you need
+\&    $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
+\&    delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
+.Ve
+.SH "ORDER OF APPLICATION"
+.IX Header "ORDER OF APPLICATION"
+Some options, in particular \f(CW\*(C`\-I\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`PERL5OPT\*(C'\fR can
+interact, and the order in which they are applied is important.
+.PP
+Note that this section does not document what \fIactually\fR happens inside the
+perl interpreter, it documents what \fIeffectively\fR happens.
+.IP \-I 4
+.IX Item "-I"
+The effect of multiple \f(CW\*(C`\-I\*(C'\fR options is to \f(CW\*(C`unshift\*(C'\fR them onto \f(CW@INC\fR
+from right to left. So for example:
+.Sp
+.Vb 1
+\&    perl \-I 1 \-I 2 \-I 3
+.Ve
+.Sp
+will first prepend \f(CW3\fR onto the front of \f(CW@INC\fR, then prepend \f(CW2\fR, and
+then prepend \f(CW1\fR. The result is that \f(CW@INC\fR begins with:
+.Sp
+.Vb 1
+\&    qw(1 2 3)
+.Ve
+.IP \-M 4
+.IX Item "-M"
+Multiple \f(CW\*(C`\-M\*(C'\fR options are processed from left to right. So this:
+.Sp
+.Vb 1
+\&    perl \-Mlib=1 \-Mlib=2 \-Mlib=3
+.Ve
+.Sp
+will first use the lib pragma to prepend \f(CW1\fR to \f(CW@INC\fR, then
+it will prepend \f(CW2\fR, then it will prepend \f(CW3\fR, resulting in an \f(CW@INC\fR
+that begins with:
+.Sp
+.Vb 1
+\&    qw(3 2 1)
+.Ve
+.IP "the PERL5LIB environment variable" 4
+.IX Item "the PERL5LIB environment variable"
+This contains a list of directories, separated by colons. The entire list
+is prepended to \f(CW@INC\fR in one go. This:
+.Sp
+.Vb 1
+\&    PERL5LIB=1:2:3 perl
+.Ve
+.Sp
+will result in an \f(CW@INC\fR that begins with:
+.Sp
+.Vb 1
+\&    qw(1 2 3)
+.Ve
+.IP "combinations of \-I, \-M and PERL5LIB" 4
+.IX Item "combinations of -I, -M and PERL5LIB"
+\&\f(CW\*(C`PERL5LIB\*(C'\fR is applied first, then all the \f(CW\*(C`\-I\*(C'\fR arguments, then all the
+\&\f(CW\*(C`\-M\*(C'\fR arguments. This:
+.Sp
+.Vb 1
+\&    PERL5LIB=e1:e2 perl \-I i1 \-Mlib=m1 \-I i2 \-Mlib=m2
+.Ve
+.Sp
+will result in an \f(CW@INC\fR that begins with:
+.Sp
+.Vb 1
+\&    qw(m2 m1 i1 i2 e1 e2)
+.Ve
+.IP "the PERL5OPT environment variable" 4
+.IX Item "the PERL5OPT environment variable"
+This contains a space separated list of switches. We only consider the
+effects of \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-I\*(C'\fR in this section.
+.Sp
+After normal processing of \f(CW\*(C`\-I\*(C'\fR switches from the command line, all
+the \f(CW\*(C`\-I\*(C'\fR switches in \f(CW\*(C`PERL5OPT\*(C'\fR are extracted. They are processed from
+left to right instead of from right to left. Also note that while
+whitespace is allowed between a \f(CW\*(C`\-I\*(C'\fR and its directory on the command
+line, it is not allowed in \f(CW\*(C`PERL5OPT\*(C'\fR.
+.Sp
+After normal processing of \f(CW\*(C`\-M\*(C'\fR switches from the command line, all
+the \f(CW\*(C`\-M\*(C'\fR switches in \f(CW\*(C`PERL5OPT\*(C'\fR are extracted. They are processed from
+left to right, \fIi.e.\fR the same as those on the command line.
+.Sp
+An example may make this clearer:
+.Sp
+.Vb 3
+\&    export PERL5OPT="\-Mlib=optm1 \-Iopti1 \-Mlib=optm2 \-Iopti2"
+\&    export PERL5LIB=e1:e2
+\&    perl \-I i1 \-Mlib=m1 \-I i2 \-Mlib=m2
+.Ve
+.Sp
+will result in an \f(CW@INC\fR that begins with:
+.Sp
+.Vb 3
+\&    qw(
+\&        optm2
+\&        optm1
+\&
+\&        m2
+\&        m1
+\&
+\&        opti2
+\&        opti1
+\&
+\&        i1
+\&        i2
+\&
+\&        e1
+\&        e2
+\&    )
+.Ve
+.IP "Other complications" 4
+.IX Item "Other complications"
+There are some complications that are ignored in the examples above:
+.RS 4
+.IP "arch and version subdirs" 4
+.IX Item "arch and version subdirs"
+All of \f(CW\*(C`\-I\*(C'\fR, \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`use lib\*(C'\fR will also prepend arch and version
+subdirs if they are present
+.IP sitecustomize.pl 4
+.IX Item "sitecustomize.pl"
+.RE
+.RS 4
+.RE
diff --git a/upstream/mageia-cauldron/man1/perlsec.1 b/upstream/mageia-cauldron/man1/perlsec.1
new file mode 100644
index 00000000..08d811b4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsec.1
@@ -0,0 +1,673 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSEC 1"
+.TH PERLSEC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsec \- Perl security
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl is designed to make it easy to program securely even when running
+with extra privileges, like setuid or setgid programs.  Unlike most
+command line shells, which are based on multiple substitution passes on
+each line of the script, Perl uses a more conventional evaluation scheme
+with fewer hidden snags.  Additionally, because the language has more
+builtin functionality, it can rely less upon external (and possibly
+untrustworthy) programs to accomplish its purposes.
+.SH "SECURITY VULNERABILITY CONTACT INFORMATION"
+.IX Header "SECURITY VULNERABILITY CONTACT INFORMATION"
+If you believe you have found a security vulnerability in the Perl
+interpreter or modules maintained in the core Perl codebase,
+email the details to
+perl\-security@perl.org <mailto:perl-security@perl.org>.
+This address is a closed membership mailing list monitored by the Perl
+security team.
+.PP
+See perlsecpolicy for additional information.
+.SH "SECURITY MECHANISMS AND CONCERNS"
+.IX Header "SECURITY MECHANISMS AND CONCERNS"
+.SS "Taint mode"
+.IX Subsection "Taint mode"
+By default,
+Perl automatically enables a set of special security checks, called \fItaint
+mode\fR, when it detects its program running with differing real and effective
+user or group IDs.  The setuid bit in Unix permissions is mode 04000, the
+setgid bit mode 02000; either or both may be set.  You can also enable taint
+mode explicitly by using the \fB\-T\fR command line flag.  This flag is
+\&\fIstrongly\fR suggested for server programs and any program run on behalf of
+someone else, such as a CGI script.  Once taint mode is on, it's on for
+the remainder of your script.
+.PP
+While in this mode, Perl takes special precautions called \fItaint
+checks\fR to prevent both obvious and subtle traps.  Some of these checks
+are reasonably simple, such as verifying that path directories aren't
+writable by others; careful programmers have always used checks like
+these.  Other checks, however, are best supported by the language itself,
+and it is these checks especially that contribute to making a set-id Perl
+program more secure than the corresponding C program.
+.PP
+You may not use data derived from outside your program to affect
+something else outside your program\-\-at least, not by accident.  All
+command line arguments, environment variables, locale information (see
+perllocale), results of certain system calls (\f(CWreaddir()\fR,
+\&\f(CWreadlink()\fR, the variable of \f(CWshmread()\fR, the messages returned by
+\&\f(CWmsgrcv()\fR, the password, gcos and shell fields returned by the
+\&\f(CWgetpwxxx()\fR calls), and all file input are marked as "tainted".
+Tainted data may not be used directly or indirectly in any command
+that invokes a sub-shell, nor in any command that modifies files,
+directories, or processes, \fBwith the following exceptions\fR:
+.PP
+Support for taint checks adds an overhead to all Perl programs,
+whether or not you're using the taint features.
+Perl 5.18 introduced C preprocessor symbols that can
+be used to disable the taint features.
+.IP \(bu 4
+Arguments to \f(CW\*(C`print\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR are \fBnot\fR checked for taintedness.
+.IP \(bu 4
+Symbolic methods
+.Sp
+.Vb 1
+\&    $obj\->$method(@args);
+.Ve
+.Sp
+and symbolic sub references
+.Sp
+.Vb 2
+\&    &{$foo}(@args);
+\&    $foo\->(@args);
+.Ve
+.Sp
+are not checked for taintedness.  This requires extra carefulness
+unless you want external data to affect your control flow.  Unless
+you carefully limit what these symbolic values are, people are able
+to call functions \fBoutside\fR your Perl code, such as POSIX::system,
+in which case they are able to run arbitrary external code.
+.IP \(bu 4
+Hash keys are \fBnever\fR tainted.
+.PP
+For efficiency reasons, Perl takes a conservative view of
+whether data is tainted.  If an expression contains tainted data,
+any subexpression may be considered tainted, even if the value
+of the subexpression is not itself affected by the tainted data.
+.PP
+Because taintedness is associated with each scalar value, some
+elements of an array or hash can be tainted and others not.
+The keys of a hash are \fBnever\fR tainted.
+.PP
+For example:
+.PP
+.Vb 8
+\&    $arg = shift;               # $arg is tainted
+\&    $hid = $arg . \*(Aqbar\*(Aq;        # $hid is also tainted
+\&    $line = <>;                 # Tainted
+\&    $line = <STDIN>;            # Also tainted
+\&    open FOO, "/home/me/bar" or die $!;
+\&    $line = <FOO>;              # Still tainted
+\&    $path = $ENV{\*(AqPATH\*(Aq};       # Tainted, but see below
+\&    $data = \*(Aqabc\*(Aq;              # Not tainted
+\&
+\&    system "echo $arg";         # Insecure
+\&    system "/bin/echo", $arg;   # Considered insecure
+\&                                # (Perl doesn\*(Aqt know about /bin/echo)
+\&    system "echo $hid";         # Insecure
+\&    system "echo $data";        # Insecure until PATH set
+\&
+\&    $path = $ENV{\*(AqPATH\*(Aq};       # $path now tainted
+\&
+\&    $ENV{\*(AqPATH\*(Aq} = \*(Aq/bin:/usr/bin\*(Aq;
+\&    delete @ENV{\*(AqIFS\*(Aq, \*(AqCDPATH\*(Aq, \*(AqENV\*(Aq, \*(AqBASH_ENV\*(Aq};
+\&
+\&    $path = $ENV{\*(AqPATH\*(Aq};       # $path now NOT tainted
+\&    system "echo $data";        # Is secure now!
+\&
+\&    open(FOO, "< $arg");        # OK \- read\-only file
+\&    open(FOO, "> $arg");        # Not OK \- trying to write
+\&
+\&    open(FOO,"echo $arg|");     # Not OK
+\&    open(FOO,"\-|")
+\&        or exec \*(Aqecho\*(Aq, $arg;   # Also not OK
+\&
+\&    $shout = \`echo $arg\`;       # Insecure, $shout now tainted
+\&
+\&    unlink $data, $arg;         # Insecure
+\&    umask $arg;                 # Insecure
+\&
+\&    exec "echo $arg";           # Insecure
+\&    exec "echo", $arg;          # Insecure
+\&    exec "sh", \*(Aq\-c\*(Aq, $arg;      # Very insecure!
+\&
+\&    @files = <*.c>;             # insecure (uses readdir() or similar)
+\&    @files = glob(\*(Aq*.c\*(Aq);       # insecure (uses readdir() or similar)
+\&
+\&    # In either case, the results of glob are tainted, since the list of
+\&    # filenames comes from outside of the program.
+\&
+\&    $bad = ($arg, 23);          # $bad will be tainted
+\&    $arg, \`true\`;               # Insecure (although it isn\*(Aqt really)
+.Ve
+.PP
+If you try to do something insecure, you will get a fatal error saying
+something like "Insecure dependency" or "Insecure \f(CW$ENV\fR{PATH}".
+.PP
+The exception to the principle of "one tainted value taints the whole
+expression" is with the ternary conditional operator \f(CW\*(C`?:\*(C'\fR.  Since code
+with a ternary conditional
+.PP
+.Vb 1
+\&    $result = $tainted_value ? "Untainted" : "Also untainted";
+.Ve
+.PP
+is effectively
+.PP
+.Vb 5
+\&    if ( $tainted_value ) {
+\&        $result = "Untainted";
+\&    } else {
+\&        $result = "Also untainted";
+\&    }
+.Ve
+.PP
+it doesn't make sense for \f(CW$result\fR to be tainted.
+.SS "Laundering and Detecting Tainted Data"
+.IX Subsection "Laundering and Detecting Tainted Data"
+To test whether a variable contains tainted data, and whose use would
+thus trigger an "Insecure dependency" message, you can use the
+\&\f(CWtainted()\fR function of the Scalar::Util module, available in your
+nearby CPAN mirror, and included in Perl starting from the release 5.8.0.
+Or you may be able to use the following \f(CWis_tainted()\fR function.
+.PP
+.Vb 4
+\&    sub is_tainted {
+\&        local $@;   # Don\*(Aqt pollute caller\*(Aqs value.
+\&        return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
+\&    }
+.Ve
+.PP
+This function makes use of the fact that the presence of tainted data
+anywhere within an expression renders the entire expression tainted.  It
+would be inefficient for every operator to test every argument for
+taintedness.  Instead, the slightly more efficient and conservative
+approach is used that if any tainted value has been accessed within the
+same expression, the whole expression is considered tainted.
+.PP
+But testing for taintedness gets you only so far.  Sometimes you have just
+to clear your data's taintedness.  Values may be untainted by using them
+as keys in a hash; otherwise the only way to bypass the tainting
+mechanism is by referencing subpatterns from a regular expression match.
+Perl presumes that if you reference a substring using \f(CW$1\fR, \f(CW$2\fR, etc. in a
+non-tainting pattern, that
+you knew what you were doing when you wrote that pattern.  That means using
+a bit of thought\-\-don't just blindly untaint anything, or you defeat the
+entire mechanism.  It's better to verify that the variable has only good
+characters (for certain values of "good") rather than checking whether it
+has any bad characters.  That's because it's far too easy to miss bad
+characters that you never thought of.
+.PP
+Here's a test to make sure that the data contains nothing but "word"
+characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
+or a dot.
+.PP
+.Vb 5
+\&    if ($data =~ /^([\-\e@\ew.]+)$/) {
+\&        $data = $1;                     # $data now untainted
+\&    } else {
+\&        die "Bad data in \*(Aq$data\*(Aq";      # log this somewhere
+\&    }
+.Ve
+.PP
+This is fairly secure because \f(CW\*(C`/\ew+/\*(C'\fR doesn't normally match shell
+metacharacters, nor are dot, dash, or at going to mean something special
+to the shell.  Use of \f(CW\*(C`/.+/\*(C'\fR would have been insecure in theory because
+it lets everything through, but Perl doesn't check for that.  The lesson
+is that when untainting, you must be exceedingly careful with your patterns.
+Laundering data using regular expression is the \fIonly\fR mechanism for
+untainting dirty data, unless you use the strategy detailed below to fork
+a child of lesser privilege.
+.PP
+The example does not untaint \f(CW$data\fR if \f(CW\*(C`use locale\*(C'\fR is in effect,
+because the characters matched by \f(CW\*(C`\ew\*(C'\fR are determined by the locale.
+Perl considers that locale definitions are untrustworthy because they
+contain data from outside the program.  If you are writing a
+locale-aware program, and want to launder data with a regular expression
+containing \f(CW\*(C`\ew\*(C'\fR, put \f(CW\*(C`no locale\*(C'\fR ahead of the expression in the same
+block.  See "SECURITY" in perllocale for further discussion and examples.
+.SS "Switches On the ""#!"" Line"
+.IX Subsection "Switches On the ""#!"" Line"
+When you make a script executable, in order to make it usable as a
+command, the system will pass switches to perl from the script's #!
+line.  Perl checks that any command line switches given to a setuid
+(or setgid) script actually match the ones set on the #! line.  Some
+Unix and Unix-like environments impose a one-switch limit on the #!
+line, so you may need to use something like \f(CW\*(C`\-wU\*(C'\fR instead of \f(CW\*(C`\-w \-U\*(C'\fR
+under such systems.  (This issue should arise only in Unix or
+Unix-like environments that support #! and setuid or setgid scripts.)
+.ie n .SS "Taint mode and @INC"
+.el .SS "Taint mode and \f(CW@INC\fP"
+.IX Subsection "Taint mode and @INC"
++When the taint mode (\f(CW\*(C`\-T\*(C'\fR) is in effect, the environment variables
++\f(CW\*(C`PERL5LIB\*(C'\fR, \f(CW\*(C`PERLLIB\*(C'\fR, and \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR
+are ignored by Perl.  You can still adjust \f(CW@INC\fR from outside the
+program by using the \f(CW\*(C`\-I\*(C'\fR command line option as explained in
+perlrun.  The two environment variables are
+ignored because they are obscured, and a user running a program could
+be unaware that they are set, whereas the \f(CW\*(C`\-I\*(C'\fR option is clearly
+visible and therefore permitted.
+.PP
+Another way to modify \f(CW@INC\fR without modifying the program, is to use
+the \f(CW\*(C`lib\*(C'\fR pragma, e.g.:
+.PP
+.Vb 1
+\&  perl \-Mlib=/foo program
+.Ve
+.PP
+The benefit of using \f(CW\*(C`\-Mlib=/foo\*(C'\fR over \f(CW\*(C`\-I/foo\*(C'\fR, is that the former
+will automagically remove any duplicated directories, while the latter
+will not.
+.PP
+Note that if a tainted string is added to \f(CW@INC\fR, the following
+problem will be reported:
+.PP
+.Vb 1
+\&  Insecure dependency in require while running with \-T switch
+.Ve
+.PP
+On versions of Perl before 5.26, activating taint mode will also remove
+the current directory (".") from the default value of \f(CW@INC\fR. Since
+version 5.26, the current directory isn't included in \f(CW@INC\fR by
+default.
+.SS "Cleaning Up Your Path"
+.IX Subsection "Cleaning Up Your Path"
+For "Insecure \f(CW$ENV{PATH}\fR" messages, you need to set \f(CW$ENV{\*(AqPATH\*(Aq}\fR to
+a known value, and each directory in the path must be absolute and
+non-writable by others than its owner and group.  You may be surprised to
+get this message even if the pathname to your executable is fully
+qualified.  This is \fInot\fR generated because you didn't supply a full path
+to the program; instead, it's generated because you never set your PATH
+environment variable, or you didn't set it to something that was safe.
+Because Perl can't guarantee that the executable in question isn't itself
+going to turn around and execute some other program that is dependent on
+your PATH, it makes sure you set the PATH.
+.PP
+The PATH isn't the only environment variable which can cause problems.
+Because some shells may use the variables IFS, CDPATH, ENV, and
+BASH_ENV, Perl checks that those are either empty or untainted when
+starting subprocesses.  You may wish to add something like this to your
+setid and taint-checking scripts.
+.PP
+.Vb 1
+\&    delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};   # Make %ENV safer
+.Ve
+.PP
+It's also possible to get into trouble with other operations that don't
+care whether they use tainted values.  Make judicious use of the file
+tests in dealing with any user-supplied filenames.  When possible, do
+opens and such \fBafter\fR properly dropping any special user (or group!)
+privileges.  Perl doesn't prevent you from
+opening tainted filenames for reading,
+so be careful what you print out.  The tainting mechanism is intended to
+prevent stupid mistakes, not to remove the need for thought.
+.PP
+Perl does not call the shell to expand wild cards when you pass \f(CW\*(C`system\*(C'\fR
+and \f(CW\*(C`exec\*(C'\fR explicit parameter lists instead of strings with possible shell
+wildcards in them.  Unfortunately, the \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, and
+backtick functions provide no such alternate calling convention, so more
+subterfuge will be required.
+.PP
+Perl provides a reasonably safe way to open a file or pipe from a setuid
+or setgid program: just create a child process with reduced privilege who
+does the dirty work for you.  First, fork a child using the special
+\&\f(CW\*(C`open\*(C'\fR syntax that connects the parent and child by a pipe.  Now the
+child resets its ID set and any other per-process attributes, like
+environment variables, umasks, current working directories, back to the
+originals or known safe values.  Then the child process, which no longer
+has any special permissions, does the \f(CW\*(C`open\*(C'\fR or other system call.
+Finally, the child passes the data it managed to access back to the
+parent.  Because the file or pipe was opened in the child while running
+under less privilege than the parent, it's not apt to be tricked into
+doing something it shouldn't.
+.PP
+Here's a way to do backticks reasonably safely.  Notice how the \f(CW\*(C`exec\*(C'\fR is
+not called with a string that the shell could expand.  This is by far the
+best way to call something that might be subjected to shell escapes: just
+never call the shell at all.
+.PP
+.Vb 10
+\&        use English;
+\&        die "Can\*(Aqt fork: $!" unless defined($pid = open(KID, "\-|"));
+\&        if ($pid) {           # parent
+\&            while (<KID>) {
+\&                # do something
+\&            }
+\&            close KID;
+\&        } else {
+\&            my @temp     = ($EUID, $EGID);
+\&            my $orig_uid = $UID;
+\&            my $orig_gid = $GID;
+\&            $EUID = $UID;
+\&            $EGID = $GID;
+\&            # Drop privileges
+\&            $UID  = $orig_uid;
+\&            $GID  = $orig_gid;
+\&            # Make sure privs are really gone
+\&            ($EUID, $EGID) = @temp;
+\&            die "Can\*(Aqt drop privileges"
+\&                unless $UID == $EUID  && $GID eq $EGID;
+\&            $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
+\&            # Consider sanitizing the environment even more.
+\&            exec \*(Aqmyprog\*(Aq, \*(Aqarg1\*(Aq, \*(Aqarg2\*(Aq
+\&                or die "can\*(Aqt exec myprog: $!";
+\&        }
+.Ve
+.PP
+A similar strategy would work for wildcard expansion via \f(CW\*(C`glob\*(C'\fR, although
+you can use \f(CW\*(C`readdir\*(C'\fR instead.
+.PP
+Taint checking is most useful when although you trust yourself not to have
+written a program to give away the farm, you don't necessarily trust those
+who end up using it not to try to trick it into doing something bad.  This
+is the kind of security checking that's useful for set-id programs and
+programs launched on someone else's behalf, like CGI programs.
+.PP
+This is quite different, however, from not even trusting the writer of the
+code not to try to do something evil.  That's the kind of trust needed
+when someone hands you a program you've never seen before and says, "Here,
+run this."  For that kind of safety, you might want to check out the Safe
+module, included standard in the Perl distribution.  This module allows the
+programmer to set up special compartments in which all system operations
+are trapped and namespace access is carefully controlled.  Safe should
+not be considered bullet-proof, though: it will not prevent the foreign
+code to set up infinite loops, allocate gigabytes of memory, or even
+abusing perl bugs to make the host interpreter crash or behave in
+unpredictable ways.  In any case it's better avoided completely if you're
+really concerned about security.
+.SS "Shebang Race Condition"
+.IX Subsection "Shebang Race Condition"
+Beyond the obvious problems that stem from giving special privileges to
+systems as flexible as scripts, on many versions of Unix, set-id scripts
+are inherently insecure right from the start.  The problem is a race
+condition in the kernel.  Between the time the kernel opens the file to
+see which interpreter to run and when the (now-set-id) interpreter turns
+around and reopens the file to interpret it, the file in question may have
+changed, especially if you have symbolic links on your system.
+.PP
+Some Unixes, especially more recent ones, are free of this
+inherent security bug.  On such systems, when the kernel passes the name
+of the set-id script to open to the interpreter, rather than using a
+pathname subject to meddling, it instead passes \fI/dev/fd/3\fR.  This is a
+special file already opened on the script, so that there can be no race
+condition for evil scripts to exploit.  On these systems, Perl should be
+compiled with \f(CW\*(C`\-DSETUID_SCRIPTS_ARE_SECURE_NOW\*(C'\fR.  The \fIConfigure\fR
+program that builds Perl tries to figure this out for itself, so you
+should never have to specify this yourself.  Most modern releases of
+SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
+.PP
+If you don't have the safe version of set-id scripts, all is not lost.
+Sometimes this kernel "feature" can be disabled, so that the kernel
+either doesn't run set-id scripts with the set-id or doesn't run them
+at all.  Either way avoids the exploitability of the race condition,
+but doesn't help in actually running scripts set-id.
+.PP
+If the kernel set-id script feature isn't disabled, then any set-id
+script provides an exploitable vulnerability.  Perl can't avoid being
+exploitable, but will point out vulnerable scripts where it can.  If Perl
+detects that it is being applied to a set-id script then it will complain
+loudly that your set-id script is insecure, and won't run it.  When Perl
+complains, you need to remove the set-id bit from the script to eliminate
+the vulnerability.  Refusing to run the script doesn't in itself close
+the vulnerability; it is just Perl's way of encouraging you to do this.
+.PP
+To actually run a script set-id, if you don't have the safe version of
+set-id scripts, you'll need to put a C wrapper around
+the script.  A C wrapper is just a compiled program that does nothing
+except call your Perl program.   Compiled programs are not subject to the
+kernel bug that plagues set-id scripts.  Here's a simple wrapper, written
+in C:
+.PP
+.Vb 4
+\&    #include <unistd.h>
+\&    #include <stdio.h>
+\&    #include <string.h>
+\&    #include <errno.h>
+\&
+\&    #define REAL_PATH "/path/to/script"
+\&
+\&    int main(int argc, char **argv)
+\&    {
+\&        execv(REAL_PATH, argv);
+\&        fprintf(stderr, "%s: %s: %s\en",
+\&                        argv[0], REAL_PATH, strerror(errno));
+\&        return 127;
+\&    }
+.Ve
+.PP
+Compile this wrapper into a binary executable and then make \fIit\fR rather
+than your script setuid or setgid.  Note that this wrapper isn't doing
+anything to sanitise the execution environment other than ensuring
+that a safe path to the script is used.  It only avoids the shebang
+race condition.  It relies on Perl's own features, and on the script
+itself being careful, to make it safe enough to run the script set-id.
+.SS "Protecting Your Programs"
+.IX Subsection "Protecting Your Programs"
+There are a number of ways to hide the source to your Perl programs,
+with varying levels of "security".
+.PP
+First of all, however, you \fIcan't\fR take away read permission, because
+the source code has to be readable in order to be compiled and
+interpreted.  (That doesn't mean that a CGI script's source is
+readable by people on the web, though.)  So you have to leave the
+permissions at the socially friendly 0755 level.  This lets 
+people on your local system only see your source.
+.PP
+Some people mistakenly regard this as a security problem.  If your program does
+insecure things, and relies on people not knowing how to exploit those
+insecurities, it is not secure.  It is often possible for someone to
+determine the insecure things and exploit them without viewing the
+source.  Security through obscurity, the name for hiding your bugs
+instead of fixing them, is little security indeed.
+.PP
+You can try using encryption via source filters (Filter::* from CPAN,
+or Filter::Util::Call and Filter::Simple since Perl 5.8).
+But crackers might be able to decrypt it.  You can try using the byte
+code compiler and interpreter described below, but crackers might be
+able to de-compile it.  You can try using the native-code compiler
+described below, but crackers might be able to disassemble it.  These
+pose varying degrees of difficulty to people wanting to get at your
+code, but none can definitively conceal it (this is true of every
+language, not just Perl).
+.PP
+If you're concerned about people profiting from your code, then the
+bottom line is that nothing but a restrictive license will give you
+legal security.  License your software and pepper it with threatening
+statements like "This is unpublished proprietary software of XYZ Corp.
+Your access to it does not give you permission to use it blah blah
+blah."  You should see a lawyer to be sure your license's wording will
+stand up in court.
+.SS Unicode
+.IX Subsection "Unicode"
+Unicode is a new and complex technology and one may easily overlook
+certain security pitfalls.  See perluniintro for an overview and
+perlunicode for details, and "Security Implications
+of Unicode" in perlunicode for security implications in particular.
+.SS "Algorithmic Complexity Attacks"
+.IX Subsection "Algorithmic Complexity Attacks"
+Certain internal algorithms used in the implementation of Perl can
+be attacked by choosing the input carefully to consume large amounts
+of either time or space or both.  This can lead into the so-called
+\&\fIDenial of Service\fR (DoS) attacks.
+.IP \(bu 4
+Hash Algorithm \- Hash algorithms like the one used in Perl are well
+known to be vulnerable to collision attacks on their hash function.
+Such attacks involve constructing a set of keys which collide into
+the same bucket producing inefficient behavior.  Such attacks often
+depend on discovering the seed of the hash function used to map the
+keys to buckets.  That seed is then used to brute-force a key set which
+can be used to mount a denial of service attack.  In Perl 5.8.1 changes
+were introduced to harden Perl to such attacks, and then later in
+Perl 5.18.0 these features were enhanced and additional protections
+added.
+.Sp
+At the time of this writing, Perl 5.18.0 is considered to be
+well-hardened against algorithmic complexity attacks on its hash
+implementation.  This is largely owed to the following measures
+mitigate attacks:
+.RS 4
+.IP "Hash Seed Randomization" 4
+.IX Item "Hash Seed Randomization"
+In order to make it impossible to know what seed to generate an attack
+key set for, this seed is randomly initialized at process start.  This
+may be overridden by using the PERL_HASH_SEED environment variable, see
+"PERL_HASH_SEED" in perlrun.  This environment variable controls how
+items are actually stored, not how they are presented via
+\&\f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR and \f(CW\*(C`each\*(C'\fR.
+.IP "Hash Traversal Randomization" 4
+.IX Item "Hash Traversal Randomization"
+Independent of which seed is used in the hash function, \f(CW\*(C`keys\*(C'\fR,
+\&\f(CW\*(C`values\*(C'\fR, and \f(CW\*(C`each\*(C'\fR return items in a per-hash randomized order.
+Modifying a hash by insertion will change the iteration order of that hash.
+This behavior can be overridden by using \f(CWhash_traversal_mask()\fR from
+Hash::Util or by using the PERL_PERTURB_KEYS environment variable,
+see "PERL_PERTURB_KEYS" in perlrun.  Note that this feature controls the
+"visible" order of the keys, and not the actual order they are stored in.
+.IP "Bucket Order Perturbance" 4
+.IX Item "Bucket Order Perturbance"
+When items collide into a given hash bucket the order they are stored in
+the chain is no longer predictable in Perl 5.18.  This
+has the intention to make it harder to observe a
+collision.  This behavior can be overridden by using
+the PERL_PERTURB_KEYS environment variable, see "PERL_PERTURB_KEYS" in perlrun.
+.IP "New Default Hash Function" 4
+.IX Item "New Default Hash Function"
+The default hash function has been modified with the intention of making
+it harder to infer the hash seed.
+.IP "Alternative Hash Functions" 4
+.IX Item "Alternative Hash Functions"
+The source code includes multiple hash algorithms to choose from.  While we
+believe that the default perl hash is robust to attack, we have included the
+hash function Siphash as a fall-back option.  At the time of release of
+Perl 5.18.0 Siphash is believed to be of cryptographic strength.  This is
+not the default as it is much slower than the default hash.
+.RE
+.RS 4
+.Sp
+Without compiling a special Perl, there is no way to get the exact same
+behavior of any versions prior to Perl 5.18.0.  The closest one can get
+is by setting PERL_PERTURB_KEYS to 0 and setting the PERL_HASH_SEED
+to a known value.  We do not advise those settings for production use
+due to the above security considerations.
+.Sp
+\&\fBPerl has never guaranteed any ordering of the hash keys\fR, and
+the ordering has already changed several times during the lifetime of
+Perl 5.  Also, the ordering of hash keys has always been, and continues
+to be, affected by the insertion order and the history of changes made
+to the hash over its lifetime.
+.Sp
+Also note that while the order of the hash elements might be
+randomized, this "pseudo-ordering" should \fBnot\fR be used for
+applications like shuffling a list randomly (use \f(CWList::Util::shuffle()\fR
+for that, see List::Util, a standard core module since Perl 5.8.0;
+or the CPAN module \f(CW\*(C`Algorithm::Numerical::Shuffle\*(C'\fR), or for generating
+permutations (use e.g. the CPAN modules \f(CW\*(C`Algorithm::Permute\*(C'\fR or
+\&\f(CW\*(C`Algorithm::FastPermute\*(C'\fR), or for any cryptographic applications.
+.Sp
+Tied hashes may have their own ordering and algorithmic complexity
+attacks.
+.RE
+.IP \(bu 4
+Regular expressions \- Perl's regular expression engine is so called NFA
+(Non-deterministic Finite Automaton), which among other things means that
+it can rather easily consume large amounts of both time and space if the
+regular expression may match in several ways.  Careful crafting of the
+regular expressions can help but quite often there really isn't much
+one can do (the book "Mastering Regular Expressions" is required
+reading, see perlfaq2).  Running out of space manifests itself by
+Perl running out of memory.
+.IP \(bu 4
+Sorting \- the quicksort algorithm used in Perls before 5.8.0 to
+implement the \fBsort()\fR function was very easy to trick into misbehaving
+so that it consumes a lot of time.  Starting from Perl 5.8.0 a different
+sorting algorithm, mergesort, is used by default.  Mergesort cannot
+misbehave on any input.
+.PP
+See <https://www.usenix.org/legacy/events/sec03/tech/full_papers/crosby/crosby.pdf> for more information,
+and any computer science textbook on algorithmic complexity.
+.SS "Using Sudo"
+.IX Subsection "Using Sudo"
+The popular tool \f(CW\*(C`sudo\*(C'\fR provides a controlled way for users to be able
+to run programs as other users.  It sanitises the execution environment
+to some extent, and will avoid the shebang race condition.  If you don't have the safe version of set-id scripts,
+then \f(CW\*(C`sudo\*(C'\fR may be a more convenient way of executing a script as
+another user than writing a C wrapper would be.
+.PP
+However, \f(CW\*(C`sudo\*(C'\fR sets the real user or group ID to that of the target
+identity, not just the effective ID as set-id bits do.  As a result, Perl
+can't detect that it is running under \f(CW\*(C`sudo\*(C'\fR, and so won't automatically
+take its own security precautions such as turning on taint mode.  Where
+\&\f(CW\*(C`sudo\*(C'\fR configuration dictates exactly which command can be run, the
+approved command may include a \f(CW\*(C`\-T\*(C'\fR option to perl to enable taint mode.
+.PP
+In general, it is necessary to evaluate the suitability of a script to
+run under \f(CW\*(C`sudo\*(C'\fR specifically with that kind of execution environment
+in mind.  It is neither necessary nor sufficient for the same script to
+be suitable to run in a traditional set-id arrangement, though many of
+the issues overlap.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+"ENVIRONMENT" in perlrun for its description of cleaning up environment
+variables.
diff --git a/upstream/mageia-cauldron/man1/perlsecpolicy.1 b/upstream/mageia-cauldron/man1/perlsecpolicy.1
new file mode 100644
index 00000000..cf3a8ecf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsecpolicy.1
@@ -0,0 +1,537 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSECPOLICY 1"
+.TH PERLSECPOLICY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsecpolicy \- Perl security report handling policy
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The Perl project takes security issues seriously.
+.PP
+The responsibility for handling security reports in a timely and
+effective manner has been delegated to a security team composed
+of a subset of the Perl core developers.
+.PP
+This document describes how the Perl security team operates and
+how the team evaluates new security reports.
+.SH "REPORTING SECURITY ISSUES IN PERL"
+.IX Header "REPORTING SECURITY ISSUES IN PERL"
+If you believe you have found a security vulnerability in the Perl
+interpreter or modules maintained in the core Perl codebase,
+email the details to
+perl\-security@perl.org <mailto:perl-security@perl.org>.
+This address is a closed membership mailing list monitored by the Perl
+security team.
+.PP
+You should receive an initial response to your report within 72 hours.
+If you do not receive a response in that time, please contact
+the Perl Steering Council <mailto:steering-council@perl.org>.
+.PP
+When members of the security team reply to your messages, they will
+generally include the perl\-security@perl.org address in the "To" or "CC"
+fields of the response. This allows all of the security team to follow
+the discussion and chime in as needed. Use the "Reply-all" functionality
+of your email client when you send subsequent responses so that the
+entire security team receives the message.
+.PP
+The security team will evaluate your report and make an initial
+determination of whether it is likely to fit the scope of issues the
+team handles. General guidelines about how this is determined are
+detailed in the "WHAT ARE SECURITY ISSUES" section.
+.PP
+If your report meets the team's criteria, an issue will be opened in the
+team's private issue tracker and you will be provided the issue's ID number.
+Issue identifiers have the form perl\-security#NNN. Include this identifier
+with any subsequent messages you send.
+.PP
+The security team will send periodic updates about the status of your
+issue and guide you through any further action that is required to complete
+the vulnerability remediation process. The stages vulnerabilities typically
+go through are explained in the "HOW WE DEAL WITH SECURITY ISSUES"
+section.
+.SH "WHAT ARE SECURITY ISSUES"
+.IX Header "WHAT ARE SECURITY ISSUES"
+A vulnerability is a behavior of a software system that compromises the
+system's expected confidentiality, integrity or availability protections.
+.PP
+A security issue is a bug in one or more specific components of a software
+system that creates a vulnerability.
+.PP
+Software written in the Perl programming language is typically composed
+of many layers of software written by many different groups. It can be
+very complicated to determine which specific layer of a complex real-world
+application was responsible for preventing a vulnerable behavior, but this
+is an essential part of fixing the vulnerability.
+.SS "Software covered by the Perl security team"
+.IX Subsection "Software covered by the Perl security team"
+The Perl security team handles security issues in:
+.IP \(bu 4
+The Perl interpreter
+.IP \(bu 4
+The Perl modules shipped with the interpreter that are developed in the core
+Perl repository
+.IP \(bu 4
+The command line tools shipped with the interpreter that are developed in the
+core Perl repository
+.PP
+Files under the \fIcpan/\fR directory in Perl's repository and release tarballs are
+developed and maintained independently. The Perl security team does not
+directly handle security issues for these modules, but since this code is
+bundled with Perl, we will assist in forwarding the issue to the relevant
+maintainer(s) and you can still report these issues to us in secrecy.
+.SS "Bugs that may qualify as security issues in Perl"
+.IX Subsection "Bugs that may qualify as security issues in Perl"
+Perl is designed to be a fast and flexible general purpose programming
+language. The Perl interpreter and Perl modules make writing safe and
+secure applications easy, but they do have limitations.
+.PP
+As a general rule, a bug in Perl needs to meet all of the following
+criteria to be considered a security issue:
+.IP \(bu 4
+The vulnerable behavior is not mentioned in Perl's documentation
+or public issue tracker.
+.IP \(bu 4
+The vulnerable behavior is not implied by an expected behavior.
+.IP \(bu 4
+The vulnerable behavior is not a generally accepted limitation of
+the implementation.
+.IP \(bu 4
+The vulnerable behavior is likely to be exposed to attack in
+otherwise secure applications written in Perl.
+.IP \(bu 4
+The vulnerable behavior provides a specific tangible benefit
+to an attacker that triggers the behavior.
+.SS "Bugs that do not qualify as security issues in Perl"
+.IX Subsection "Bugs that do not qualify as security issues in Perl"
+There are certain categories of bugs that are frequently reported to
+the security team that do not meet the criteria listed above.
+.PP
+The following is a list of commonly reported bugs that are not
+handled as security issues.
+.PP
+\fIFeeding untrusted code to the interpreter\fR
+.IX Subsection "Feeding untrusted code to the interpreter"
+.PP
+The Perl parser is not designed to evaluate untrusted code.
+If your application requires the evaluation of untrusted code, it
+should rely on an operating system level sandbox for its security.
+.PP
+\fIStack overflows due to excessive recursion\fR
+.IX Subsection "Stack overflows due to excessive recursion"
+.PP
+Excessive recursion is often caused by code that does
+not enforce limits on inputs. The Perl interpreter assumes limits
+on recursion will be enforced by the application.
+.PP
+\fIOut of memory errors\fR
+.IX Subsection "Out of memory errors"
+.PP
+Common Perl constructs such as \f(CW\*(C`pack\*(C'\fR, the \f(CW\*(C`x\*(C'\fR operator,
+and regular expressions accept numeric quantifiers that control how
+much memory will be allocated to store intermediate values or results.
+If you allow an attacker to supply these quantifiers and consume all
+available memory, the Perl interpreter will not prevent it.
+.PP
+\fIEscape from a Safe compartment\fR
+.IX Subsection "Escape from a Safe compartment"
+.PP
+Opcode restrictions and Safe compartments are not supported as
+security mechanisms. The Perl parser is not designed to evaluate
+untrusted code.
+.PP
+\fIUse of the \fR\f(CI\*(C`p\*(C'\fR\fI and \fR\f(CI\*(C`P\*(C'\fR\fI pack templates\fR
+.IX Subsection "Use of the p and P pack templates"
+.PP
+These templates are unsafe by design.
+.PP
+\fIStack not reference-counted issues\fR
+.IX Subsection "Stack not reference-counted issues"
+.PP
+These bugs typically present as use-after-free errors or as assertion
+failures on the type of a \f(CW\*(C`SV\*(C'\fR. Stack not reference-counted
+crashes usually occur because code is both modifying a reference or
+glob and using the values referenced by that glob or reference.
+.PP
+This type of bug is a long standing issue with the Perl interpreter
+that seldom occurs in normal code. Examples of this type of bug
+generally assume that attacker-supplied code will be evaluated by
+the Perl interpreter.
+.PP
+\fIThawing attacker-supplied data with Storable\fR
+.IX Subsection "Thawing attacker-supplied data with Storable"
+.PP
+Storable is designed to be a very fast serialization format.
+It is not designed to be safe for deserializing untrusted inputs.
+.PP
+\fIUsing attacker supplied SDBM_File databases\fR
+.IX Subsection "Using attacker supplied SDBM_File databases"
+.PP
+The SDBM_File module is not intended for use with untrusted SDBM
+databases.
+.PP
+\fIBadly encoded UTF\-8 flagged scalars\fR
+.IX Subsection "Badly encoded UTF-8 flagged scalars"
+.PP
+This type of bug occurs when the \f(CW\*(C`:utf8\*(C'\fR PerlIO layer is used to
+read badly encoded data, or other mechanisms are used to directly
+manipulate the UTF\-8 flag on an SV.
+.PP
+A badly encoded UTF\-8 flagged SV is not a valid SV. Code that
+creates SV's in this fashion is corrupting Perl's internal state.
+.PP
+\fIIssues that exist only in blead, or in a release candidate\fR
+.IX Subsection "Issues that exist only in blead, or in a release candidate"
+.PP
+The blead branch and Perl release candidates do not receive security
+support. Security defects that are present only in pre-release
+versions of Perl are handled through the normal bug reporting and
+resolution process.
+.PP
+\fICPAN modules or other Perl project resources\fR
+.IX Subsection "CPAN modules or other Perl project resources"
+.PP
+The Perl security team is focused on the Perl interpreter and modules
+maintained in the core Perl codebase. The team has no special access
+to fix CPAN modules, applications written in Perl, Perl project websites,
+Perl mailing lists or the Perl IRC servers.
+.PP
+\fIEmulated POSIX behaviors on Windows systems\fR
+.IX Subsection "Emulated POSIX behaviors on Windows systems"
+.PP
+The Perl interpreter attempts to emulate \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`exec\*(C'\fR
+and other POSIX behaviors on Windows systems. This emulation has many
+quirks that are extensively documented in Perl's public issue tracker.
+Changing these behaviors would cause significant disruption for existing
+users on Windows.
+.SS "Bugs that require special categorization"
+.IX Subsection "Bugs that require special categorization"
+Some bugs in the Perl interpreter occur in areas of the codebase that are
+both security sensitive and prone to failure during normal usage.
+.PP
+\fIRegular expressions\fR
+.IX Subsection "Regular expressions"
+.PP
+Untrusted regular expressions are generally safe to compile and match against
+with several caveats. The following behaviors of Perl's regular expression
+engine are the developer's responsibility to constrain.
+.PP
+The evaluation of untrusted regular expressions while \f(CW\*(C`use re \*(Aqeval\*(Aq;\*(C'\fR is
+in effect is never safe.
+.PP
+Regular expressions are not guaranteed to compile or evaluate in any specific
+finite time frame.
+.PP
+Regular expressions may consume all available system memory when they are
+compiled or evaluated.
+.PP
+Regular expressions may cause excessive recursion that halts the perl
+interpreter.
+.PP
+As a general rule, do not expect Perl's regular expression engine to
+be resistant to denial of service attacks.
+.PP
+\fIDB_File, ODBM_File, or GDBM_File databases\fR
+.IX Subsection "DB_File, ODBM_File, or GDBM_File databases"
+.PP
+These modules rely on external libraries to interact with database files.
+.PP
+Bugs caused by reading and writing these file formats are generally caused
+by the underlying library implementation and are not security issues in
+Perl.
+.PP
+Bugs where Perl mishandles unexpected valid return values from the underlying
+libraries may qualify as security issues in Perl.
+.PP
+\fIAlgorithmic complexity attacks\fR
+.IX Subsection "Algorithmic complexity attacks"
+.PP
+The perl interpreter is reasonably robust to algorithmic complexity
+attacks. It is not immune to them.
+.PP
+Algorithmic complexity bugs that depend on the interpreter processing
+extremely large amounts of attacker supplied data are not generally handled
+as security issues.
+.PP
+See "Algorithmic Complexity Attacks" in perlsec for additional information.
+.SH "HOW WE DEAL WITH SECURITY ISSUES"
+.IX Header "HOW WE DEAL WITH SECURITY ISSUES"
+The Perl security team follows responsible disclosure practices. Security issues
+are kept secret until a fix is readily available for most users. This minimizes
+inherent risks users face from vulnerabilities in Perl.
+.PP
+Hiding problems from the users temporarily is a necessary trade-off to keep
+them safe. Hiding problems from users permanently is not the goal.
+.PP
+When you report a security issue privately to the
+perl\-security@perl.org <mailto:perl-security@perl.org> contact address, we
+normally expect you to follow responsible disclosure practices in the handling
+of the report. If you are unable or unwilling to keep the issue secret until
+a fix is available to users you should state this clearly in the initial
+report.
+.PP
+The security team's vulnerability remediation workflow is intended to be as
+open and transparent as possible about the state of your security report.
+.SS "Perl's vulnerability remediation workflow"
+.IX Subsection "Perl's vulnerability remediation workflow"
+\fIInitial contact\fR
+.IX Subsection "Initial contact"
+.PP
+New vulnerability reports will receive an initial reply within 72 hours
+from the time they arrive at the security team's mailing list. If you do
+not receive any response in that time, contact the
+Perl Steering Council <mailto:steering-council@perl.org>.
+.PP
+The initial response sent by the security team will confirm your message was
+received and provide an estimated time frame for the security team's
+triage analysis.
+.PP
+\fIInitial triage\fR
+.IX Subsection "Initial triage"
+.PP
+The security team will evaluate the report and determine whether or not
+it is likely to meet the criteria for handling as a security issue.
+.PP
+The security team aims to complete the initial report triage within
+two weeks' time. Complex issues that require significant discussion or
+research may take longer.
+.PP
+If the security report cannot be reproduced or does not meet the team's
+criteria for handling as a security issue, you will be notified by email
+and given an opportunity to respond.
+.PP
+\fIIssue ID assignment\fR
+.IX Subsection "Issue ID assignment"
+.PP
+Security reports that pass initial triage analysis are turned into issues
+in the security team's private issue tracker. When a report progresses to
+this point you will be provided the issue ID for future reference. These
+identifiers have the format perl\-security#NNN or Perl/perl\-security#NNN.
+.PP
+The assignment of an issue ID does not confirm that a security report
+represents a vulnerability in Perl. Many reports require further analysis
+to reach that determination.
+.PP
+Issues in the security team's private tracker are used to collect details
+about the problem and track progress towards a resolution. These notes and
+other details are not made public when the issue is resolved. Keeping the
+issue notes private allows the security team to freely discuss attack
+methods, attack tools, and other related private issues.
+.PP
+\fIDevelopment of patches\fR
+.IX Subsection "Development of patches"
+.PP
+Members of the security team will inspect the report and related code in
+detail to produce fixes for supported versions of Perl.
+.PP
+If the team discovers that the reported issue does not meet the team's
+criteria at this stage, you will be notified by email and given an
+opportunity to respond before the issue is closed.
+.PP
+The team may discuss potential fixes with you or provide you with
+patches for testing purposes during this time frame. No information
+should be shared publicly at this stage.
+.PP
+\fICVE ID assignment\fR
+.IX Subsection "CVE ID assignment"
+.PP
+Once an issue is fully confirmed and a potential fix has been found,
+the security team will request a CVE identifier for the issue to use
+in public announcements.
+.PP
+Details like the range of vulnerable Perl versions and identities
+of the people that discovered the flaw need to be collected to submit
+the CVE ID request.
+.PP
+The security team may ask you to clarify the exact name we should use
+when crediting discovery of the issue. The
+"Vulnerability credit and bounties" section of this document
+explains our preferred format for this credit.
+.PP
+Once a CVE ID has been assigned, you will be notified by email.
+The vulnerability should not be discussed publicly at this stage.
+.PP
+\fIPre-release notifications\fR
+.IX Subsection "Pre-release notifications"
+.PP
+When the security team is satisfied that the fix for a security issue
+is ready to release publicly, a pre-release notification
+announcement is sent to the major redistributors of Perl.
+.PP
+This pre-release announcement includes a list of Perl versions that
+are affected by the flaw, an analysis of the risks to users, patches
+the security team has produced, and any information about mitigations
+or backporting fixes to older versions of Perl that the security team
+has available.
+.PP
+The pre-release announcement will include a specific target date
+when the issue will be announced publicly. The time frame between
+the pre-release announcement and the release date allows redistributors
+to prepare and test their own updates and announcements. During this
+period the vulnerability details and fixes are embargoed and should not
+be shared publicly. This embargo period may be extended further if
+problems are discovered during testing.
+.PP
+You will be sent the portions of pre-release announcements that are
+relevant to the specific issue you reported. This email will include
+the target release date. Additional updates will be sent if the
+target release date changes.
+.PP
+\fIPre-release testing\fR
+.IX Subsection "Pre-release testing"
+.PP
+The Perl security team does not directly produce official Perl
+releases. The team releases security fixes by placing commits
+in Perl's public git repository and sending announcements.
+.PP
+Many users and redistributors prefer using official Perl releases
+rather than applying patches to an older release. The security
+team works with Perl's release managers to make this possible.
+.PP
+New official releases of Perl are generally produced and tested
+on private systems during the pre-release embargo period.
+.PP
+\fIRelease of fixes and announcements\fR
+.IX Subsection "Release of fixes and announcements"
+.PP
+At the end of the embargo period the security fixes will be
+committed to Perl's public git repository and announcements will be
+sent to the perl5\-porters <https://lists.perl.org/list/perl5-porters.html>
+and oss-security <https://oss-security.openwall.org/wiki/mailing-lists/oss-security>
+mailing lists.
+.PP
+If official Perl releases are ready, they will be published at this time
+and announced on the perl5\-porters <https://lists.perl.org/list/perl5-porters.html>
+mailing list.
+.PP
+The security team will send a follow-up notification to everyone that
+participated in the pre-release embargo period once the release process is
+finished. Vulnerability reporters and Perl redistributors should not publish
+their own announcements or fixes until the Perl security team's release process
+is complete.
+.SS "Publicly known and zero-day security issues"
+.IX Subsection "Publicly known and zero-day security issues"
+The security team's vulnerability remediation workflow assumes that issues
+are reported privately and kept secret until they are resolved. This isn't
+always the case and information occasionally leaks out before a fix is ready.
+.PP
+In these situations the team must decide whether operating in secret increases
+or decreases the risk to users of Perl. In some cases being open about
+the risk a security issue creates will allow users to defend against it,
+in other cases calling attention to an unresolved security issue will
+make it more likely to be misused.
+.PP
+\fIZero-day security issues\fR
+.IX Subsection "Zero-day security issues"
+.PP
+If an unresolved critical security issue in Perl is being actively abused to
+attack systems the security team will send out announcements as rapidly as
+possible with any mitigations the team has available.
+.PP
+Perl's public defect tracker will be used to handle the issue so that additional
+information, fixes, and CVE IDs are visible to affected users as rapidly as
+possible.
+.PP
+\fIOther leaks of security issue information\fR
+.IX Subsection "Other leaks of security issue information"
+.PP
+Depending on the prominence of the information revealed about a security
+issue and the issue's risk of becoming a zero-day attack, the security team may
+skip all or part of its normal remediation workflow.
+.PP
+If the security team learns of a significant security issue after it has been
+identified and resolved in Perl's public issue tracker, the team will
+request a CVE ID and send an announcement to inform users.
+.SS "Vulnerability credit and bounties"
+.IX Subsection "Vulnerability credit and bounties"
+The Perl project appreciates the effort security researchers
+invest in making Perl safe and secure.
+.PP
+Since much of this work is hidden from the public, crediting
+researchers publicly is an important part of the vulnerability
+remediation process.
+.PP
+\fICredits in vulnerability announcements\fR
+.IX Subsection "Credits in vulnerability announcements"
+.PP
+When security issues are fixed we will attempt to credit the specific
+researcher(s) that discovered the flaw in our announcements.
+.PP
+Credits are announced using the researcher's preferred full name.
+.PP
+If the researcher's contributions were funded by a specific company or
+part of an organized vulnerability research project, we will include
+a short name for this group at the researcher's request.
+.PP
+Perl's announcements are written in the English language using the 7bit
+ASCII character set to be reproducible in a variety of formats. We
+do not include hyperlinks, domain names or marketing material with these
+acknowledgments.
+.PP
+In the event that proper credit for vulnerability discovery cannot be
+established or there is a disagreement between the Perl security team
+and the researcher about how the credit should be given, it will be
+omitted from announcements.
+.PP
+\fIBounties for Perl vulnerabilities\fR
+.IX Subsection "Bounties for Perl vulnerabilities"
+.PP
+The Perl project is a non-profit volunteer effort. We do not provide
+any monetary rewards for reporting security issues in Perl.
diff --git a/upstream/mageia-cauldron/man1/perlsolaris.1 b/upstream/mageia-cauldron/man1/perlsolaris.1
new file mode 100644
index 00000000..16b4da38
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsolaris.1
@@ -0,0 +1,784 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSOLARIS 1"
+.TH PERLSOLARIS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsolaris \- Perl version 5 on Solaris systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of Sun's Solaris operating system
+that will affect how Perl version 5 (hereafter just perl) is
+compiled and/or runs.  Some issues relating to the older SunOS 4.x are
+also discussed, though they may be out of date.
+.PP
+For the most part, everything should just work.
+.PP
+Starting with Solaris 8, perl5.00503 (or higher) is supplied with the
+operating system, so you might not even need to build a newer version
+of perl at all.  The Sun-supplied version is installed in /usr/perl5
+with \fI/usr/bin/perl\fR pointing to \fI/usr/perl5/bin/perl\fR.  Do not disturb
+that installation unless you really know what you are doing.  If you
+remove the perl supplied with the OS, you will render some bits of
+your system inoperable.  If you wish to install a newer version of perl,
+install it under a different prefix from /usr/perl5.  Common prefixes
+to use are /usr/local and /opt/perl.
+.PP
+You may wish to put your version of perl in the PATH of all users by
+changing the link \fI/usr/bin/perl\fR.  This is probably OK, as most perl
+scripts shipped with Solaris use an explicit path.  (There are a few
+exceptions, such as \fI/usr/bin/rpm2cpio\fR and \fI/etc/rcm/scripts/README\fR, but
+these are also sufficiently generic that the actual version of perl
+probably doesn't matter too much.)
+.PP
+Solaris ships with a range of Solaris-specific modules.  If you choose
+to install your own version of perl you will find the source of many of
+these modules is available on CPAN under the Sun::Solaris:: namespace.
+.PP
+Solaris may include two versions of perl, e.g. Solaris 9 includes
+both 5.005_03 and 5.6.1.  This is to provide stability across Solaris
+releases, in cases where a later perl version has incompatibilities
+with the version included in the preceding Solaris release.  The
+default perl version will always be the most recent, and in general
+the old version will only be retained for one Solaris release.  Note
+also that the default perl will NOT be configured to search for modules
+in the older version, again due to compatibility/stability concerns.
+As a consequence if you upgrade Solaris, you will have to
+rebuild/reinstall any additional CPAN modules that you installed for
+the previous Solaris version.  See the CPAN manpage under 'autobundle'
+for a quick way of doing this.
+.PP
+As an interim measure, you may either change the #! line of your
+scripts to specifically refer to the old perl version, e.g. on
+Solaris 9 use #!/usr/perl5/5.00503/bin/perl to use the perl version
+that was the default for Solaris 8, or if you have a large number of
+scripts it may be more convenient to make the old version of perl the
+default on your system.  You can do this by changing the appropriate
+symlinks under /usr/perl5 as follows (example for Solaris 9):
+.PP
+.Vb 7
+\& # cd /usr/perl5
+\& # rm bin man pod
+\& # ln \-s ./5.00503/bin
+\& # ln \-s ./5.00503/man
+\& # ln \-s ./5.00503/lib/pod
+\& # rm /usr/bin/perl
+\& # ln \-s ../perl5/5.00503/bin/perl /usr/bin/perl
+.Ve
+.PP
+In both cases this should only be considered to be a temporary
+measure \- you should upgrade to the later version of perl as soon as
+is practicable.
+.PP
+Note also that the perl command-line utilities (e.g. perldoc) and any
+that are added by modules that you install will be under
+/usr/perl5/bin, so that directory should be added to your PATH.
+.SS "Solaris Version Numbers."
+.IX Subsection "Solaris Version Numbers."
+For consistency with common usage, perl's Configure script performs
+some minor manipulations on the operating system name and version
+number as reported by uname.  Here's a partial translation table:
+.PP
+.Vb 7
+\&          Sun:                      perl\*(Aqs Configure:
+\& uname    uname \-r   Name           osname     osvers
+\& SunOS    4.1.3     Solaris 1.1     sunos      4.1.3
+\& SunOS    5.6       Solaris 2.6     solaris    2.6
+\& SunOS    5.8       Solaris 8       solaris    2.8
+\& SunOS    5.9       Solaris 9       solaris    2.9
+\& SunOS    5.10      Solaris 10      solaris    2.10
+.Ve
+.PP
+The complete table can be found in the Sun Managers' FAQ
+<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq> under
+"9.1) Which Sun models run which versions of SunOS?".
+.SH RESOURCES
+.IX Header "RESOURCES"
+There are many, many sources for Solaris information.  A few of the
+important ones for perl:
+.IP "Solaris FAQ" 4
+.IX Item "Solaris FAQ"
+The Solaris FAQ is available at
+<http://www.science.uva.nl/pub/solaris/solaris2.html>.
+.Sp
+The Sun Managers' FAQ is available at
+<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq>
+.IP "Precompiled Binaries" 4
+.IX Item "Precompiled Binaries"
+Precompiled binaries, links to many sites, and much, much more are
+available at <http://www.sunfreeware.com/> and
+<http://www.blastwave.org/>.
+.IP "Solaris Documentation" 4
+.IX Item "Solaris Documentation"
+All Solaris documentation is available on-line at <http://docs.sun.com/>.
+.SH "SETTING UP"
+.IX Header "SETTING UP"
+.SS "File Extraction Problems on Solaris."
+.IX Subsection "File Extraction Problems on Solaris."
+Be sure to use a tar program compiled under Solaris (not SunOS 4.x)
+to extract the perl\-5.x.x.tar.gz file.  Do not use GNU tar compiled
+for SunOS4 on Solaris.  (GNU tar compiled for Solaris should be fine.)
+When you run SunOS4 binaries on Solaris, the run-time system magically
+alters pathnames matching m#lib/locale# so that when tar tries to create
+lib/locale.pm, a file named lib/oldlocale.pm gets created instead.
+If you found this advice too late and used a SunOS4\-compiled tar
+anyway, you must find the incorrectly renamed file and move it back
+to lib/locale.pm.
+.SS "Compiler and Related Tools on Solaris."
+.IX Subsection "Compiler and Related Tools on Solaris."
+You must use an ANSI C compiler to build perl.  Perl can be compiled
+with either Sun's add-on C compiler or with gcc.  The C compiler that
+shipped with SunOS4 will not do.
+.PP
+\fIInclude /usr/ccs/bin/ in your PATH.\fR
+.IX Subsection "Include /usr/ccs/bin/ in your PATH."
+.PP
+Several tools needed to build perl are located in /usr/ccs/bin/:  ar,
+as, ld, and make.  Make sure that /usr/ccs/bin/ is in your PATH.
+.PP
+On all the released versions of Solaris (8, 9 and 10) you need to make sure the following packages are installed (this info is extracted from the Solaris FAQ):
+.PP
+for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool,
+SUNWsprot, SUNWtoo
+.PP
+for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh,
+SUNWcg6h, SUNWxwinc
+.PP
+Additionally, on Solaris 8 and 9 you also need:
+.PP
+for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux,
+SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
+.PP
+And only on Solaris 8 you also need:
+.PP
+for libraries & headers: SUNWolinc
+.PP
+If you are in doubt which package contains a file you are missing,
+try to find an installation that has that file. Then do a
+.PP
+.Vb 1
+\& $ grep /my/missing/file /var/sadm/install/contents
+.Ve
+.PP
+This will display a line like this:
+.PP
+/usr/include/sys/errno.h f none 0644 root bin 7471 37605 956241356 SUNWhea
+.PP
+The last item listed (SUNWhea in this example) is the package you need.
+.PP
+\fIAvoid /usr/ucb/cc.\fR
+.IX Subsection "Avoid /usr/ucb/cc."
+.PP
+You don't need to have /usr/ucb/ in your PATH to build perl.  If you
+want /usr/ucb/ in your PATH anyway, make sure that /usr/ucb/ is NOT
+in your PATH before the directory containing the right C compiler.
+.PP
+\fISun's C Compiler\fR
+.IX Subsection "Sun's C Compiler"
+.PP
+If you use Sun's C compiler, make sure the correct directory
+(usually /opt/SUNWspro/bin/) is in your PATH (before /usr/ucb/).
+.PP
+\fIGCC\fR
+.IX Subsection "GCC"
+.PP
+If you use gcc, make sure your installation is recent and complete.
+perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >=
+2.6.
+.PP
+You must Configure perl with
+.PP
+.Vb 1
+\& $ sh Configure \-Dcc=gcc
+.Ve
+.PP
+If you don't, you may experience strange build errors.
+.PP
+If you have updated your Solaris version, you may also have to update
+your gcc.  For example, if you are running Solaris 2.6 and your gcc is
+installed under /usr/local, check in /usr/local/lib/gcc\-lib and make
+sure you have the appropriate directory, sparc\-sun\-solaris2.6/ or
+i386\-pc\-solaris2.6/.  If gcc's directory is for a different version of
+Solaris than you are running, then you will need to rebuild gcc for
+your new version of Solaris.
+.PP
+You can get a precompiled version of gcc from
+<http://www.sunfreeware.com/> or <http://www.blastwave.org/>. Make
+sure you pick up the package for your Solaris release.
+.PP
+If you wish to use gcc to build add-on modules for use with the perl
+shipped with Solaris, you should use the Solaris::PerlGcc module
+which is available from CPAN.  The perl shipped with Solaris
+is configured and built with the Sun compilers, and the compiler
+configuration information stored in Config.pm is therefore only
+relevant to the Sun compilers.  The Solaris:PerlGcc module contains a
+replacement Config.pm that is correct for gcc \- see the module for
+details.
+.PP
+\fIGNU as and GNU ld\fR
+.IX Subsection "GNU as and GNU ld"
+.PP
+The following information applies to gcc version 2.  Volunteers to
+update it as appropriately for gcc version 3 would be appreciated.
+.PP
+The versions of as and ld supplied with Solaris work fine for building
+perl.  There is normally no need to install the GNU versions to
+compile perl.
+.PP
+If you decide to ignore this advice and use the GNU versions anyway,
+then be sure that they are relatively recent.  Versions newer than 2.7
+are apparently new enough.  Older versions may have trouble with
+dynamic loading.
+.PP
+If you wish to use GNU ld, then you need to pass it the \-Wl,\-E flag.
+The hints/solaris_2.sh file tries to do this automatically by setting
+the following Configure variables:
+.PP
+.Vb 2
+\& ccdlflags="$ccdlflags \-Wl,\-E"
+\& lddlflags="$lddlflags \-Wl,\-E \-G"
+.Ve
+.PP
+However, over the years, changes in gcc, GNU ld, and Solaris ld have made
+it difficult to automatically detect which ld ultimately gets called.
+You may have to manually edit config.sh and add the \-Wl,\-E flags
+yourself, or else run Configure interactively and add the flags at the
+appropriate prompts.
+.PP
+If your gcc is configured to use GNU as and ld but you want to use the
+Solaris ones instead to build perl, then you'll need to add
+\&\-B/usr/ccs/bin/ to the gcc command line.  One convenient way to do
+that is with
+.PP
+.Vb 1
+\& $ sh Configure \-Dcc=\*(Aqgcc \-B/usr/ccs/bin/\*(Aq
+.Ve
+.PP
+Note that the trailing slash is required.  This will result in some
+harmless warnings as Configure is run:
+.PP
+.Vb 1
+\& gcc: file path prefix \`/usr/ccs/bin/\*(Aq never used
+.Ve
+.PP
+These messages may safely be ignored.
+(Note that for a SunOS4 system, you must use \-B/bin/ instead.)
+.PP
+Alternatively, you can use the GCC_EXEC_PREFIX environment variable to
+ensure that Sun's as and ld are used.  Consult your gcc documentation
+for further information on the \-B option and the GCC_EXEC_PREFIX variable.
+.PP
+\fISun and GNU make\fR
+.IX Subsection "Sun and GNU make"
+.PP
+The make under /usr/ccs/bin works fine for building perl.  If you
+have the Sun C compilers, you will also have a parallel version of
+make (dmake).  This works fine to build perl, but can sometimes cause
+problems when running 'make test' due to underspecified dependencies
+between the different test harness files.  The same problem can also
+affect the building of some add-on modules, so in those cases either
+specify '\-m serial' on the dmake command line, or use
+/usr/ccs/bin/make instead.  If you wish to use GNU make, be sure that
+the set-group-id bit is not set.  If it is, then arrange your PATH so
+that /usr/ccs/bin/make is before GNU make or else have the system
+administrator disable the set-group-id bit on GNU make.
+.PP
+\fIAvoid libucb.\fR
+.IX Subsection "Avoid libucb."
+.PP
+Solaris provides some BSD-compatibility functions in /usr/ucblib/libucb.a.
+Perl will not build and run correctly if linked against \-lucb since it
+contains routines that are incompatible with the standard Solaris libc.
+Normally this is not a problem since the solaris hints file prevents
+Configure from even looking in /usr/ucblib for libraries, and also
+explicitly omits \-lucb.
+.SS "Environment for Compiling perl on Solaris"
+.IX Subsection "Environment for Compiling perl on Solaris"
+\fIPATH\fR
+.IX Subsection "PATH"
+.PP
+Make sure your PATH includes the compiler (/opt/SUNWspro/bin/ if you're
+using Sun's compiler) as well as /usr/ccs/bin/ to pick up the other
+development tools (such as make, ar, as, and ld).  Make sure your path
+either doesn't include /usr/ucb or that it includes it after the
+compiler and compiler tools and other standard Solaris directories.
+You definitely don't want /usr/ucb/cc.
+.PP
+\fILD_LIBRARY_PATH\fR
+.IX Subsection "LD_LIBRARY_PATH"
+.PP
+If you have the LD_LIBRARY_PATH environment variable set, be sure that
+it does NOT include /lib or /usr/lib.  If you will be building
+extensions that call third-party shared libraries (e.g. Berkeley DB)
+then make sure that your LD_LIBRARY_PATH environment variable includes
+the directory with that library (e.g. /usr/local/lib).
+.PP
+If you get an error message
+.PP
+.Vb 1
+\& dlopen: stub interception failed
+.Ve
+.PP
+it is probably because your LD_LIBRARY_PATH environment variable
+includes a directory which is a symlink to /usr/lib (such as /lib).
+The reason this causes a problem is quite subtle.  The file
+libdl.so.1.0 actually *only* contains functions which generate 'stub
+interception failed' errors!  The runtime linker intercepts links to
+"/usr/lib/libdl.so.1.0" and links in internal implementations of those
+functions instead.  [Thanks to Tim Bunce for this explanation.]
+.SH "RUN CONFIGURE."
+.IX Header "RUN CONFIGURE."
+See the INSTALL file for general information regarding Configure.
+Only Solaris-specific issues are discussed here.  Usually, the
+defaults should be fine.
+.SS "64\-bit perl on Solaris."
+.IX Subsection "64-bit perl on Solaris."
+See the INSTALL file for general information regarding 64\-bit compiles.
+In general, the defaults should be fine for most people.
+.PP
+By default, perl\-5.6.0 (or later) is compiled as a 32\-bit application
+with largefile and long-long support.
+.PP
+\fIGeneral 32\-bit vs. 64\-bit issues.\fR
+.IX Subsection "General 32-bit vs. 64-bit issues."
+.PP
+Solaris 7 and above will run in either 32 bit or 64 bit mode on SPARC
+CPUs, via a reboot. You can build 64 bit apps whilst running 32 bit
+mode and vice-versa. 32 bit apps will run under Solaris running in
+either 32 or 64 bit mode.  64 bit apps require Solaris to be running
+64 bit mode.
+.PP
+Existing 32 bit apps are properly known as LP32, i.e. Longs and
+Pointers are 32 bit.  64\-bit apps are more properly known as LP64.
+The discriminating feature of a LP64 bit app is its ability to utilise a
+64\-bit address space.  It is perfectly possible to have a LP32 bit app
+that supports both 64\-bit integers (long long) and largefiles (> 2GB),
+and this is the default for perl\-5.6.0.
+.PP
+For a more complete explanation of 64\-bit issues, see the
+"Solaris 64\-bit Developer's Guide" at <http://docs.sun.com/>
+.PP
+You can detect the OS mode using "isainfo \-v", e.g.
+.PP
+.Vb 3
+\& $ isainfo \-v   # Ultra 30 in 64 bit mode
+\& 64\-bit sparcv9 applications
+\& 32\-bit sparc applications
+.Ve
+.PP
+By default, perl will be compiled as a 32\-bit application.  Unless
+you want to allocate more than ~ 4GB of memory inside perl, or unless
+you need more than 255 open file descriptors, you probably don't need
+perl to be a 64\-bit app.
+.PP
+\fILarge File Support\fR
+.IX Subsection "Large File Support"
+.PP
+For Solaris 2.6 and onwards, there are two different ways for 32\-bit
+applications to manipulate large files (files whose size is > 2GByte).
+(A 64\-bit application automatically has largefile support built in
+by default.)
+.PP
+First is the "transitional compilation environment", described in
+\&\fBlfcompile64\fR\|(5).  According to the man page,
+.PP
+.Vb 7
+\& The transitional compilation  environment  exports  all  the
+\& explicit 64\-bit functions (xxx64()) and types in addition to
+\& all the regular functions (xxx()) and types. Both xxx()  and
+\& xxx64()  functions  are  available to the program source.  A
+\& 32\-bit application must use the xxx64() functions in  order
+\& to  access  large  files.  See the lf64(5) manual page for a
+\& complete listing of the 64\-bit transitional interfaces.
+.Ve
+.PP
+The transitional compilation environment is obtained with the
+following compiler and linker flags:
+.PP
+.Vb 3
+\& getconf LFS64_CFLAGS        \-D_LARGEFILE64_SOURCE
+\& getconf LFS64_LDFLAG        # nothing special needed
+\& getconf LFS64_LIBS          # nothing special needed
+.Ve
+.PP
+Second is the "large file compilation environment", described in
+\&\fBlfcompile\fR\|(5).  According to the man page,
+.PP
+.Vb 5
+\& Each interface named xxx() that needs to access 64\-bit entities
+\& to  access  large  files maps to a xxx64() call in the
+\& resulting binary. All relevant data types are defined to  be
+\& of correct size (for example, off_t has a typedef definition
+\& for a 64\-bit entity).
+\&
+\& An application compiled in this environment is able  to  use
+\& the  xxx()  source interfaces to access both large and small
+\& files, rather than having to explicitly utilize the  transitional
+\& xxx64()  interface  calls to access large files.
+.Ve
+.PP
+Two exceptions are \fBfseek()\fR and \fBftell()\fR.  32\-bit applications should
+use fseeko(3C) and ftello(3C).  These will get automatically mapped
+to \fBfseeko64()\fR and \fBftello64()\fR.
+.PP
+The large file compilation environment is obtained with
+.PP
+.Vb 3
+\& getconf LFS_CFLAGS      \-D_LARGEFILE_SOURCE \-D_FILE_OFFSET_BITS=64
+\& getconf LFS_LDFLAGS     # nothing special needed
+\& getconf LFS_LIBS        # nothing special needed
+.Ve
+.PP
+By default, perl uses the large file compilation environment and
+relies on Solaris to do the underlying mapping of interfaces.
+.PP
+\fIBuilding an LP64 perl\fR
+.IX Subsection "Building an LP64 perl"
+.PP
+To compile a 64\-bit application on an UltraSparc with a recent Sun Compiler,
+you need to use the flag "\-xarch=v9".  \fBgetconf\fR\|(1) will tell you this, e.g.
+.PP
+.Vb 10
+\& $ getconf \-a | grep v9
+\& XBS5_LP64_OFF64_CFLAGS:         \-xarch=v9
+\& XBS5_LP64_OFF64_LDFLAGS:        \-xarch=v9
+\& XBS5_LP64_OFF64_LINTFLAGS:      \-xarch=v9
+\& XBS5_LPBIG_OFFBIG_CFLAGS:       \-xarch=v9
+\& XBS5_LPBIG_OFFBIG_LDFLAGS:      \-xarch=v9
+\& XBS5_LPBIG_OFFBIG_LINTFLAGS:    \-xarch=v9
+\& _XBS5_LP64_OFF64_CFLAGS:        \-xarch=v9
+\& _XBS5_LP64_OFF64_LDFLAGS:       \-xarch=v9
+\& _XBS5_LP64_OFF64_LINTFLAGS:     \-xarch=v9
+\& _XBS5_LPBIG_OFFBIG_CFLAGS:      \-xarch=v9
+\& _XBS5_LPBIG_OFFBIG_LDFLAGS:     \-xarch=v9
+\& _XBS5_LPBIG_OFFBIG_LINTFLAGS:   \-xarch=v9
+.Ve
+.PP
+This flag is supported in Sun WorkShop Compilers 5.0 and onwards
+(now marketed under the name Forte) when used on Solaris 7 or later on
+UltraSparc systems.
+.PP
+If you are using gcc, you would need to use \-mcpu=v9 \-m64 instead.  This
+option is not yet supported as of gcc 2.95.2; from install/SPECIFIC
+in that release:
+.PP
+.Vb 5
+\& GCC version 2.95 is not able to compile code correctly for sparc64
+\& targets. Users of the Linux kernel, at least, can use the sparc32
+\& program to start up a new shell invocation with an environment that
+\& causes configure to recognize (via uname \-a) the system as sparc\-*\-*
+\& instead.
+.Ve
+.PP
+All this should be handled automatically by the hints file, if
+requested.
+.PP
+\fILong Doubles.\fR
+.IX Subsection "Long Doubles."
+.PP
+As of 5.8.1, long doubles are working if you use the Sun compilers
+(needed for additional math routines not included in libm).
+.SS "Threads in perl on Solaris."
+.IX Subsection "Threads in perl on Solaris."
+It is possible to build a threaded version of perl on Solaris.  The entire
+perl thread implementation is still experimental, however, so beware.
+.SS "Malloc Issues with perl on Solaris."
+.IX Subsection "Malloc Issues with perl on Solaris."
+Starting from perl 5.7.1 perl uses the Solaris malloc, since the perl
+malloc breaks when dealing with more than 2GB of memory, and the Solaris
+malloc also seems to be faster.
+.PP
+If you for some reason (such as binary backward compatibility) really
+need to use perl's malloc, you can rebuild perl from the sources
+and Configure the build with
+.PP
+.Vb 1
+\& $ sh Configure \-Dusemymalloc
+.Ve
+.PP
+You should not use perl's malloc if you are building with gcc.  There
+are reports of core dumps, especially in the PDL module.  The problem
+appears to go away under \-DDEBUGGING, so it has been difficult to
+track down.  Sun's compiler appears to be okay with or without perl's
+malloc. [XXX further investigation is needed here.]
+.SH "MAKE PROBLEMS."
+.IX Header "MAKE PROBLEMS."
+.IP "Dynamic Loading Problems With GNU as and GNU ld" 4
+.IX Item "Dynamic Loading Problems With GNU as and GNU ld"
+If you have problems with dynamic loading using gcc on SunOS or
+Solaris, and you are using GNU as and GNU ld, see the section
+"GNU as and GNU ld" above.
+.IP "ld.so.1: ./perl: fatal: relocation error:" 4
+.IX Item "ld.so.1: ./perl: fatal: relocation error:"
+If you get this message on SunOS or Solaris, and you're using gcc,
+it's probably the GNU as or GNU ld problem in the previous item
+"GNU as and GNU ld".
+.IP "dlopen: stub interception failed" 4
+.IX Item "dlopen: stub interception failed"
+The primary cause of the 'dlopen: stub interception failed' message is
+that the LD_LIBRARY_PATH environment variable includes a directory
+which is a symlink to /usr/lib (such as /lib).  See
+"LD_LIBRARY_PATH" above.
+.IP "#error ""No DATAMODEL_NATIVE specified""" 4
+.IX Item "#error ""No DATAMODEL_NATIVE specified"""
+This is a common error when trying to build perl on Solaris 2.6 with a
+gcc installation from Solaris 2.5 or 2.5.1.  The Solaris header files
+changed, so you need to update your gcc installation.  You can either
+rerun the fixincludes script from gcc or take the opportunity to
+update your gcc installation.
+.IP "sh: ar: not found" 4
+.IX Item "sh: ar: not found"
+This is a message from your shell telling you that the command 'ar'
+was not found.  You need to check your PATH environment variable to
+make sure that it includes the directory with the 'ar' command.  This
+is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin/
+directory.
+.SH "MAKE TEST"
+.IX Header "MAKE TEST"
+.SS "op/stat.t test 4 in Solaris"
+.IX Subsection "op/stat.t test 4 in Solaris"
+\&\fIop/stat.t\fR test 4 may fail if you are on a tmpfs of some sort.
+Building in /tmp sometimes shows this behavior.  The
+test suite detects if you are building in /tmp, but it may not be able
+to catch all tmpfs situations.
+.SS "nss_delete core dump from op/pwent or op/grent"
+.IX Subsection "nss_delete core dump from op/pwent or op/grent"
+See "nss_delete core dump from op/pwent or op/grent" in perlhpux.
+.SH CROSS-COMPILATION
+.IX Header "CROSS-COMPILATION"
+Nothing too unusual here.  You can easily do this if you have a 
+cross-compiler available;  A usual Configure invocation when targetting a
+Solaris x86 looks something like this:
+.PP
+.Vb 5
+\&    sh ./Configure \-des \-Dusecrosscompile \e
+\&        \-Dcc=i386\-pc\-solaris2.11\-gcc      \e
+\&        \-Dsysroot=$SYSROOT                \e
+\&        \-Alddlflags=" \-Wl,\-z,notext"      \e
+\&        \-Dtargethost=... # The usual cross\-compilation options
+.Ve
+.PP
+The lddlflags addition is the only abnormal bit.
+.SH "PREBUILT BINARIES OF PERL FOR SOLARIS."
+.IX Header "PREBUILT BINARIES OF PERL FOR SOLARIS."
+You can pick up prebuilt binaries for Solaris from
+<http://www.sunfreeware.com/>, <http://www.blastwave.org>,
+ActiveState <http://www.activestate.com/>, and
+<http://www.perl.com/> under the Binaries list at the top of the
+page.  There are probably other sources as well.  Please note that
+these sites are under the control of their respective owners, not the
+perl developers.
+.SH "RUNTIME ISSUES FOR PERL ON SOLARIS."
+.IX Header "RUNTIME ISSUES FOR PERL ON SOLARIS."
+.SS "Limits on Numbers of Open Files on Solaris."
+.IX Subsection "Limits on Numbers of Open Files on Solaris."
+The stdio(3C) manpage notes that for LP32 applications, only 255
+files may be opened using \fBfopen()\fR, and only file descriptors 0
+through 255 can be used in a stream.  Since perl calls \fBopen()\fR and
+then fdopen(3C) with the resulting file descriptor, perl is limited
+to 255 simultaneous open files, even if \fBsysopen()\fR is used.  If this
+proves to be an insurmountable problem, you can compile perl as a
+LP64 application, see "Building an LP64 perl" for details.  Note
+also that the default resource limit for open file descriptors on
+Solaris is 255, so you will have to modify your ulimit or rctl
+(Solaris 9 onwards) appropriately.
+.SH "SOLARIS-SPECIFIC MODULES."
+.IX Header "SOLARIS-SPECIFIC MODULES."
+See the modules under the Solaris:: and Sun::Solaris namespaces on CPAN,
+see <http://www.cpan.org/modules/by\-module/Solaris/> and
+<http://www.cpan.org/modules/by\-module/Sun/>.
+.SH "SOLARIS-SPECIFIC PROBLEMS WITH MODULES."
+.IX Header "SOLARIS-SPECIFIC PROBLEMS WITH MODULES."
+.SS "Proc::ProcessTable on Solaris"
+.IX Subsection "Proc::ProcessTable on Solaris"
+Proc::ProcessTable does not compile on Solaris with perl5.6.0 and higher
+if you have LARGEFILES defined.  Since largefile support is the
+default in 5.6.0 and later, you have to take special steps to use this
+module.
+.PP
+The problem is that various structures visible via procfs use off_t,
+and if you compile with largefile support these change from 32 bits to
+64 bits.  Thus what you get back from procfs doesn't match up with
+the structures in perl, resulting in garbage.  See \fBproc\fR\|(4) for further
+discussion.
+.PP
+A fix for Proc::ProcessTable is to edit Makefile to
+explicitly remove the largefile flags from the ones MakeMaker picks up
+from Config.pm.  This will result in Proc::ProcessTable being built
+under the correct environment.  Everything should then be OK as long as
+Proc::ProcessTable doesn't try to share off_t's with the rest of perl,
+or if it does they should be explicitly specified as off64_t.
+.SS "BSD::Resource on Solaris"
+.IX Subsection "BSD::Resource on Solaris"
+BSD::Resource versions earlier than 1.09 do not compile on Solaris
+with perl 5.6.0 and higher, for the same reasons as Proc::ProcessTable.
+BSD::Resource versions starting from 1.09 have a workaround for the problem.
+.SS "Net::SSLeay on Solaris"
+.IX Subsection "Net::SSLeay on Solaris"
+Net::SSLeay requires a /dev/urandom to be present. This device is
+available from Solaris 9 onwards.  For earlier Solaris versions you
+can either get the package SUNWski (packaged with several Sun
+software products, for example the Sun WebServer, which is part of
+the Solaris Server Intranet Extension, or the Sun Directory Services,
+part of Solaris for ISPs) or download the ANDIrand package from
+<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a
+symbolic link /dev/urandom pointing to /dev/random.  For more details,
+see Document ID27606 entitled "Differing /dev/random support requirements
+within Solaris[TM] Operating Environments", available at
+<http://sunsolve.sun.com> .
+.PP
+It may be possible to use the Entropy Gathering Daemon (written in
+Perl!), available from <http://www.lothar.com/tech/crypto/>.
+.SH "SunOS 4.x"
+.IX Header "SunOS 4.x"
+In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld,
+since the more recent versions of GNU ld (like 2.13) do not seem to
+work for building Perl anymore.  When linking the extensions, the
+GNU ld gets very unhappy and spews a lot of errors like this
+.PP
+.Vb 1
+\&  ... relocation truncated to fit: BASE13 ...
+.Ve
+.PP
+and dies.  Therefore the SunOS 4.1 hints file explicitly sets the
+ld to be \fI/usr/bin/ld\fR.
+.PP
+As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader)
+also seems to have become broken in in SunOS 4.x.  Therefore the default
+is to build Perl statically.
+.PP
+Running the test suite in SunOS 4.1 is a bit tricky since the
+\&\fIdist/Tie\-File/t/09_gen_rs.t\fR test hangs (subtest #51, FWIW) for some
+unknown reason.  Just stop the test and kill that particular Perl
+process.
+.PP
+There are various other failures, that as of SunOS 4.1.4 and gcc 3.2.2
+look a lot like gcc bugs.  Many of the failures happen in the Encode
+tests, where for example when the test expects "0" you get "&#48;"
+which should after a little squinting look very odd indeed.
+Another example is earlier in \fIt/run/fresh_perl\fR where \fBchr\fR\|(0xff) is
+expected but the test fails because the result is \fBchr\fR\|(0xff).  Exactly.
+.PP
+This is the "make test" result from the said combination:
+.PP
+.Vb 1
+\&  Failed 27 test scripts out of 745, 96.38% okay.
+.Ve
+.PP
+Running the \f(CW\*(C`harness\*(C'\fR is painful because of the many failing
+Unicode-related tests will output megabytes of failure messages,
+but if one patiently waits, one gets these results:
+.PP
+.Vb 10
+\& Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& ...
+\& ../ext/Encode/t/at\-cn.t            4  1024    29    4  13.79%  14\-17
+\& ../ext/Encode/t/at\-tw.t           10  2560    17   10  58.82%  2 4 6 8 10 12
+\&                                                                14\-17
+\& ../ext/Encode/t/enc_data.t        29  7424    ??   ??       %  ??
+\& ../ext/Encode/t/enc_eucjp.t       29  7424    ??   ??       %  ??
+\& ../ext/Encode/t/enc_module.t      29  7424    ??   ??       %  ??
+\& ../ext/Encode/t/encoding.t        29  7424    ??   ??       %  ??
+\& ../ext/Encode/t/grow.t            12  3072    24   12  50.00%  2 4 6 8 10 12 14
+\&                                                                16 18 20 22 24
+\&  Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& ../ext/Encode/t/guess.t          255 65280    29   40 137.93%  10\-29
+\& ../ext/Encode/t/jperl.t           29  7424    15   30 200.00%  1\-15
+\& ../ext/Encode/t/mime\-header.t      2   512    10    2  20.00%  2\-3
+\& ../ext/Encode/t/perlio.t          22  5632    38   22  57.89%  1\-4 9\-16 19\-20
+\&                                                                23\-24 27\-32
+\& ../ext/List/Util/t/shuffle.t       0   139    ??   ??       %  ??
+\& ../ext/PerlIO/t/encoding.t                    14    1   7.14%  11
+\& ../ext/PerlIO/t/fallback.t                     9    2  22.22%  3 5
+\& ../ext/Socket/t/socketpair.t       0     2    45   70 155.56%  11\-45
+\& ../lib/CPAN/t/vcmp.t                          30    1   3.33%  25
+\& ../lib/Tie/File/t/09_gen_rs.t      0    15    ??   ??       %  ??
+\& ../lib/Unicode/Collate/t/test.t              199   30  15.08%  7 26\-27 71\-75
+\&                                                                81\-88 95 101
+\&                                                                103\-104 106 108\-
+\&                                                                109 122 124 161
+\&                                                                169\-172
+\& ../lib/sort.t                      0   139   119   26  21.85%  107\-119
+\& op/alarm.t                                     4    1  25.00%  4
+\& op/utfhash.t                                  97    1   1.03%  31
+\& run/fresh_perl.t                              91    1   1.10%  32
+\& uni/tr_7jis.t                                 ??   ??       %  ??
+\& uni/tr_eucjp.t                    29  7424     6   12 200.00%  1\-6
+\& uni/tr_sjis.t                     29  7424     6   12 200.00%  1\-6
+\& 56 tests and 467 subtests skipped.
+\& Failed 27/811 test scripts, 96.67% okay. 1383/75399 subtests failed,
+\&   98.17% okay.
+.Ve
+.PP
+The \fBalarm()\fR test failure is caused by \fBsystem()\fR apparently blocking
+\&\fBalarm()\fR.  That is probably a libc bug, and given that SunOS 4.x
+has been end-of-lifed years ago, don't hold your breath for a fix.
+In addition to that, don't try anything too Unicode-y, especially
+with Encode, and you should be fine in SunOS 4.x.
+.SH AUTHOR
+.IX Header "AUTHOR"
+The original was written by Andy Dougherty \fIdoughera@lafayette.edu\fR
+drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce,
+and many other Solaris users over the years.
+.PP
+Please report any errors, updates, or suggestions to
+<https://github.com/Perl/perl5/issues>.
diff --git a/upstream/mageia-cauldron/man1/perlsource.1 b/upstream/mageia-cauldron/man1/perlsource.1
new file mode 100644
index 00000000..53509dcf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsource.1
@@ -0,0 +1,270 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSOURCE 1"
+.TH PERLSOURCE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsource \- A guide to the Perl source tree
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes the layout of the Perl source tree. If you're
+hacking on the Perl core, this will help you find what you're looking
+for.
+.SH "FINDING YOUR WAY AROUND"
+.IX Header "FINDING YOUR WAY AROUND"
+The Perl source tree is big. Here's some of the thing you'll find in
+it:
+.SS "C code"
+.IX Subsection "C code"
+The C source code and header files mostly live in the root of the
+source tree. There are a few platform-specific directories which
+contain C code. In addition, some of the modules shipped with Perl
+include C or XS code.
+.PP
+See perlinterp for more details on the files that make up the Perl
+interpreter, as well as details on how it works.
+.SS "Core modules"
+.IX Subsection "Core modules"
+Modules shipped as part of the Perl core live in four subdirectories.
+Two of these directories contain modules that live in the core, and two
+contain modules that can also be released separately on CPAN. Modules
+which can be released on cpan are known as "dual-life" modules.
+.IP \(bu 4
+\&\fIlib/\fR
+.Sp
+This directory contains pure-Perl modules which are only released as
+part of the core. This directory contains \fIall\fR of the modules and
+their tests, unlike other core modules.
+.IP \(bu 4
+\&\fIext/\fR
+.Sp
+Like \fIlib/\fR, this directory contains modules which are only released
+as part of the core.  Unlike \fIlib/\fR, however, a module under \fIext/\fR
+generally has a CPAN-style directory\- and file-layout and its own
+\&\fIMakefile.PL\fR.  There is no expectation that a module under \fIext/\fR
+will work with earlier versions of Perl 5.  Hence, such a module may
+take full advantage of syntactical and other improvements in Perl 5
+blead.
+.IP \(bu 4
+\&\fIdist/\fR
+.Sp
+This directory is for dual-life modules where the blead source is
+canonical. Note that some modules in this directory may not yet have
+been released separately on CPAN.  Modules under \fIdist/\fR should make
+an effort to work with earlier versions of Perl 5.
+.IP \(bu 4
+\&\fIcpan/\fR
+.Sp
+This directory contains dual-life modules where the CPAN module is
+canonical. Do not patch these modules directly! Changes to these
+modules should be submitted to the maintainer of the CPAN module. Once
+those changes are applied and released, the new version of the module
+will be incorporated into the core.
+.PP
+For some dual-life modules, it has not yet been determined if the CPAN
+version or the blead source is canonical. Until that is done, those
+modules should be in \fIcpan/\fR.
+.SS Tests
+.IX Subsection "Tests"
+The Perl core has an extensive test suite. If you add new tests (or new
+modules with tests), you may need to update the \fIt/TEST\fR file so that
+the tests are run.
+.IP \(bu 4
+Module tests
+.Sp
+Tests for core modules in the \fIlib/\fR directory are right next to the
+module itself. For example, we have \fIlib/strict.pm\fR and
+\&\fIlib/strict.t\fR.
+.Sp
+Tests for modules in \fIext/\fR and the dual-life modules are in \fIt/\fR
+subdirectories for each module, like a standard CPAN distribution.
+.IP \(bu 4
+\&\fIt/base/\fR
+.Sp
+Tests for the absolute basic functionality of Perl. This includes
+\&\f(CW\*(C`if\*(C'\fR, basic file reads and writes, simple regexes, etc. These are run
+first in the test suite and if any of them fail, something is \fIreally\fR
+broken.
+.IP \(bu 4
+\&\fIt/cmd/\fR
+.Sp
+Tests for basic control structures, \f(CW\*(C`if\*(C'\fR/\f(CW\*(C`else\*(C'\fR, \f(CW\*(C`while\*(C'\fR, subroutines,
+etc.
+.IP \(bu 4
+\&\fIt/comp/\fR
+.Sp
+Tests for basic issues of how Perl parses and compiles itself.
+.IP \(bu 4
+\&\fIt/io/\fR
+.Sp
+Tests for built-in IO functions, including command line arguments.
+.IP \(bu 4
+\&\fIt/mro/\fR
+.Sp
+Tests for perl's method resolution order implementations (see mro).
+.IP \(bu 4
+\&\fIt/op/\fR
+.Sp
+Tests for perl's built in functions that don't fit into any of the
+other directories.
+.IP \(bu 4
+\&\fIt/opbasic/\fR
+.Sp
+Tests for perl's built in functions which, like those in \fIt/op/\fR, do
+not fit into any of the other directories, but which, in addition,
+cannot use \fIt/test.pl\fR,as that program depends on functionality which
+the test file itself is testing.
+.IP \(bu 4
+\&\fIt/re/\fR
+.Sp
+Tests for regex related functions or behaviour. (These used to live in
+t/op).
+.IP \(bu 4
+\&\fIt/run/\fR
+.Sp
+Tests for features of how perl actually runs, including exit codes and
+handling of PERL* environment variables.
+.IP \(bu 4
+\&\fIt/uni/\fR
+.Sp
+Tests for the core support of Unicode.
+.IP \(bu 4
+\&\fIt/win32/\fR
+.Sp
+Windows-specific tests.
+.IP \(bu 4
+\&\fIt/porting/\fR
+.Sp
+Tests the state of the source tree for various common errors. For
+example, it tests that everyone who is listed in the git log has a
+corresponding entry in the \fIAUTHORS\fR file.
+.IP \(bu 4
+\&\fIt/lib/\fR
+.Sp
+The old home for the module tests, you shouldn't put anything new in
+here. There are still some bits and pieces hanging around in here that
+need to be moved. Perhaps you could move them?  Thanks!
+.SS Documentation
+.IX Subsection "Documentation"
+All of the core documentation intended for end users lives in \fIpod/\fR.
+Individual modules in \fIlib/\fR, \fIext/\fR, \fIdist/\fR, and \fIcpan/\fR usually
+have their own documentation, either in the \fIModule.pm\fR file or an
+accompanying \fIModule.pod\fR file.
+.PP
+Finally, documentation intended for core Perl developers lives in the
+\&\fIPorting/\fR directory.
+.SS "Hacking tools and documentation"
+.IX Subsection "Hacking tools and documentation"
+The \fIPorting\fR directory contains a grab bag of code and documentation
+intended to help porters work on Perl. Some of the highlights include:
+.IP \(bu 4
+\&\fIcheck*\fR
+.Sp
+These are scripts which will check the source things like ANSI C
+violations, POD encoding issues, etc.
+.IP \(bu 4
+\&\fIMaintainers\fR, \fIMaintainers.pl\fR, and \fIMaintainers.pm\fR
+.Sp
+These files contain information on who maintains which modules. Run
+\&\f(CW\*(C`perl Porting/Maintainers \-M Module::Name\*(C'\fR to find out more
+information about a dual-life module.
+.IP \(bu 4
+\&\fIpodtidy\fR
+.Sp
+Tidies a pod file. It's a good idea to run this on a pod file you've
+patched.
+.SS "Build system"
+.IX Subsection "Build system"
+The Perl build system on *nix\-like systems starts with the \fIConfigure\fR
+script in the root directory.
+.PP
+Platform-specific pieces of the build system also live in
+platform-specific directories like \fIwin32/\fR, \fIvms/\fR, etc.
+Windows and VMS have their own Configure-like scripts, in their
+respective directories.
+.PP
+The \fIConfigure\fR script (or a platform-specific similar script) is
+ultimately responsible for generating a \fIMakefile\fR from \fIMakefile.SH\fR.
+.PP
+The build system that Perl uses is called metaconfig. This system is
+maintained separately from the Perl core, and knows about the
+platform-specific Configure-like scripts, as well as \fIConfigure\fR
+itself.
+.PP
+The metaconfig system has its own git repository. Please see its README
+file in <https://github.com/Perl/metaconfig> for more details.
+.PP
+The \fICross\fR directory contains various files related to
+cross-compiling Perl. See \fICross/README\fR for more details.
+.SS \fIAUTHORS\fP
+.IX Subsection "AUTHORS"
+This file lists everyone who's contributed to Perl. If you submit a
+patch, you should add your name to this file as part of the patch.
+.SS \fIMANIFEST\fP
+.IX Subsection "MANIFEST"
+The \fIMANIFEST\fR file in the root of the source tree contains a list of
+every file in the Perl core, as well as a brief description of each
+file.
+.PP
+You can get an overview of all the files with this command:
+.PP
+.Vb 1
+\&  % perl \-lne \*(Aqprint if /^[^\e/]+\e.[ch]\es+/\*(Aq MANIFEST
+.Ve
diff --git a/upstream/mageia-cauldron/man1/perlstyle.1 b/upstream/mageia-cauldron/man1/perlstyle.1
new file mode 100644
index 00000000..4b909a3c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlstyle.1
@@ -0,0 +1,312 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSTYLE 1"
+.TH PERLSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlstyle \- Perl style guide
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Each programmer will, of course, have his or her own preferences in
+regards to formatting, but there are some general guidelines that will
+make your programs easier to read, understand, and maintain.
+.PP
+The most important thing is to use strict and warnings in all your
+code or know the reason why not to.  You may turn them off explicitly for
+particular portions of code via \f(CW\*(C`no warnings\*(C'\fR or \f(CW\*(C`no strict\*(C'\fR, and this
+can be limited to the specific warnings or strict features you wish to
+disable.  The \fB\-w\fR flag and \f(CW$^W\fR variable should not be used for this
+purpose since they can affect code you use but did not write, such as
+modules from core or CPAN.
+.PP
+A concise way to arrange for this is to use the
+\&\f(CW\*(C`use VERSION\*(C'\fR syntax, requesting a version 5.36
+or above, which will enable both the \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmata (as
+well as several other useful named features).
+.PP
+.Vb 1
+\&    use v5.36;
+.Ve
+.PP
+Regarding aesthetics of code layout, about the only thing Larry
+cares strongly about is that the closing curly bracket of
+a multi-line BLOCK should line up with the keyword that started the construct.
+Beyond that, he has other preferences that aren't so strong:
+.IP \(bu 4
+4\-column indent.
+.IP \(bu 4
+Opening curly on same line as keyword, if possible, otherwise line up.
+.IP \(bu 4
+Space before the opening curly of a multi-line BLOCK.
+.IP \(bu 4
+One-line BLOCK may be put on one line, including curlies.
+.IP \(bu 4
+No space before the semicolon.
+.IP \(bu 4
+Semicolon omitted in "short" one-line BLOCK.
+.IP \(bu 4
+Space around most operators.
+.IP \(bu 4
+Space around a "complex" subscript (inside brackets).
+.IP \(bu 4
+Blank lines between chunks that do different things.
+.IP \(bu 4
+Uncuddled elses.
+.IP \(bu 4
+No space between function name and its opening parenthesis.
+.IP \(bu 4
+Space after each comma.
+.IP \(bu 4
+Long lines broken after an operator (except \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR).
+.IP \(bu 4
+Space after last parenthesis matching on current line.
+.IP \(bu 4
+Line up corresponding items vertically.
+.IP \(bu 4
+Omit redundant punctuation as long as clarity doesn't suffer.
+.PP
+Larry has his reasons for each of these things, but he doesn't claim that
+everyone else's mind works the same as his does.
+.PP
+Here are some other more substantive style issues to think about:
+.IP \(bu 4
+Just because you \fICAN\fR do something a particular way doesn't mean that
+you \fISHOULD\fR do it that way.  Perl is designed to give you several
+ways to do anything, so consider picking the most readable one.  For
+instance
+.Sp
+.Vb 1
+\&    open(my $fh, \*(Aq<\*(Aq, $foo) || die "Can\*(Aqt open $foo: $!";
+.Ve
+.Sp
+is better than
+.Sp
+.Vb 1
+\&    die "Can\*(Aqt open $foo: $!" unless open(my $fh, \*(Aq<\*(Aq, $foo);
+.Ve
+.Sp
+because the second way hides the main point of the statement in a
+modifier.  On the other hand
+.Sp
+.Vb 1
+\&    print "Starting analysis\en" if $verbose;
+.Ve
+.Sp
+is better than
+.Sp
+.Vb 1
+\&    $verbose && print "Starting analysis\en";
+.Ve
+.Sp
+because the main point isn't whether the user typed \fB\-v\fR or not.
+.Sp
+Similarly, just because an operator lets you assume default arguments
+doesn't mean that you have to make use of the defaults.  The defaults
+are there for lazy systems programmers writing one-shot programs.  If
+you want your program to be readable, consider supplying the argument.
+.Sp
+Along the same lines, just because you \fICAN\fR omit parentheses in many
+places doesn't mean that you ought to:
+.Sp
+.Vb 2
+\&    return print reverse sort num values %array;
+\&    return print(reverse(sort num (values(%array))));
+.Ve
+.Sp
+When in doubt, parenthesize.  At the very least it will let some poor
+schmuck bounce on the % key in \fBvi\fR.
+.Sp
+Even if you aren't in doubt, consider the mental welfare of the person
+who has to maintain the code after you, and who will probably put
+parentheses in the wrong place.
+.IP \(bu 4
+Don't go through silly contortions to exit a loop at the top or the
+bottom, when Perl provides the \f(CW\*(C`last\*(C'\fR operator so you can exit in
+the middle.  Just "outdent" it a little to make it more visible:
+.Sp
+.Vb 7
+\&    LINE:
+\&        for (;;) {
+\&            statements;
+\&          last LINE if $foo;
+\&            next LINE if /^#/;
+\&            statements;
+\&        }
+.Ve
+.IP \(bu 4
+Don't be afraid to use loop labels\-\-they're there to enhance
+readability as well as to allow multilevel loop breaks.  See the
+previous example.
+.IP \(bu 4
+Avoid using \f(CWgrep()\fR (or \f(CWmap()\fR) or `backticks` in a void context, that is,
+when you just throw away their return values.  Those functions all
+have return values, so use them.  Otherwise use a \f(CWforeach()\fR loop or
+the \f(CWsystem()\fR function instead.
+.IP \(bu 4
+For portability, when using features that may not be implemented on
+every machine, test the construct in an eval to see if it fails.  If
+you know what version or patchlevel a particular feature was
+implemented, you can test \f(CW$]\fR (\f(CW$PERL_VERSION\fR in \f(CW\*(C`English\*(C'\fR) to see if it
+will be there.  The \f(CW\*(C`Config\*(C'\fR module will also let you interrogate values
+determined by the \fBConfigure\fR program when Perl was installed.
+.IP \(bu 4
+Choose mnemonic identifiers.  If you can't remember what mnemonic means,
+you've got a problem.
+.IP \(bu 4
+While short identifiers like \f(CW$gotit\fR are probably ok, use underscores to
+separate words in longer identifiers.  It is generally easier to read
+\&\f(CW$var_names_like_this\fR than \f(CW$VarNamesLikeThis\fR, especially for
+non-native speakers of English. It's also a simple rule that works
+consistently with \f(CW\*(C`VAR_NAMES_LIKE_THIS\*(C'\fR.
+.Sp
+Package names are sometimes an exception to this rule.  Perl informally
+reserves lowercase module names for "pragma" modules like \f(CW\*(C`integer\*(C'\fR and
+\&\f(CW\*(C`strict\*(C'\fR.  Other modules should begin with a capital letter and use mixed
+case, but probably without underscores due to limitations in primitive
+file systems' representations of module names as files that must fit into a
+few sparse bytes.
+.IP \(bu 4
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
+.Sp
+.Vb 3
+\&    $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
+\&    $Some_Caps_Here  package\-wide global/static
+\&    $no_caps_here    function scope my() or local() variables
+.Ve
+.Sp
+Function and method names seem to work best as all lowercase.
+E.g., \f(CW\*(C`$obj\->as_string()\*(C'\fR.
+.Sp
+You can use a leading underscore to indicate that a variable or
+function should not be used outside the package that defined it.
+.IP \(bu 4
+If you have a really hairy regular expression, use the \f(CW\*(C`/x\*(C'\fR  or \f(CW\*(C`/xx\*(C'\fR
+modifiers and put in some whitespace to make it look a little less like
+line noise.
+Don't use slash as a delimiter when your regexp has slashes or backslashes.
+.IP \(bu 4
+Use the \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR operators to avoid having to parenthesize
+list operators so much, and to reduce the incidence of punctuation
+operators like \f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR.  Call your subroutines as if they were
+functions or list operators to avoid excessive ampersands and parentheses.
+.IP \(bu 4
+Use here documents instead of repeated \f(CWprint()\fR statements.
+.IP \(bu 4
+Line up corresponding things vertically, especially if it'd be too long
+to fit on one line anyway.
+.Sp
+.Vb 4
+\&    $IDX = $ST_MTIME;
+\&    $IDX = $ST_ATIME       if $opt_u;
+\&    $IDX = $ST_CTIME       if $opt_c;
+\&    $IDX = $ST_SIZE        if $opt_s;
+\&
+\&    mkdir $tmpdir, 0700 or die "can\*(Aqt mkdir $tmpdir: $!";
+\&    chdir($tmpdir)      or die "can\*(Aqt chdir $tmpdir: $!";
+\&    mkdir \*(Aqtmp\*(Aq,   0777 or die "can\*(Aqt mkdir $tmpdir/tmp: $!";
+.Ve
+.IP \(bu 4
+Always check the return codes of system calls.  Good error messages should
+go to \f(CW\*(C`STDERR\*(C'\fR, include which program caused the problem, what the failed
+system call and arguments were, and (VERY IMPORTANT) should contain the
+standard system error message for what went wrong.  Here's a simple but
+sufficient example:
+.Sp
+.Vb 1
+\&    opendir(my $dh, $dir)        or die "can\*(Aqt opendir $dir: $!";
+.Ve
+.IP \(bu 4
+Line up your transliterations when it makes sense:
+.Sp
+.Vb 2
+\&    tr [abc]
+\&       [xyz];
+.Ve
+.IP \(bu 4
+Think about reusability.  Why waste brainpower on a one-shot when you
+might want to do something like it again?  Consider generalizing your
+code.  Consider writing a module or object class.  Consider making your
+code run cleanly with \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR in
+effect.  Consider giving away your code.  Consider changing your whole
+world view.  Consider... oh, never mind.
+.IP \(bu 4
+Try to document your code and use Pod formatting in a consistent way. Here
+are commonly expected conventions:
+.RS 4
+.IP \(bu 4
+use \f(CW\*(C`C<>\*(C'\fR for function, variable and module names (and more
+generally anything that can be considered part of code, like filehandles
+or specific values). Note that function names are considered more readable
+with parentheses after their name, that is \f(CWfunction()\fR.
+.IP \(bu 4
+use \f(CW\*(C`B<>\*(C'\fR for commands names like \fBcat\fR or \fBgrep\fR.
+.IP \(bu 4
+use \f(CW\*(C`F<>\*(C'\fR or \f(CW\*(C`C<>\*(C'\fR for file names. \f(CW\*(C`F<>\*(C'\fR should
+be the only Pod code for file names, but as most Pod formatters render it
+as italic, Unix and Windows paths with their slashes and backslashes may
+be less readable, and better rendered with \f(CW\*(C`C<>\*(C'\fR.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Be consistent.
+.IP \(bu 4
+Be nice.
diff --git a/upstream/mageia-cauldron/man1/perlsub.1 b/upstream/mageia-cauldron/man1/perlsub.1
new file mode 100644
index 00000000..681a4981
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsub.1
@@ -0,0 +1,2352 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSUB 1"
+.TH PERLSUB 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsub \- Perl subroutines
+.IX Xref "subroutine function"
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+To declare subroutines:
+.IX Xref "subroutine, declaration sub"
+.PP
+.Vb 4
+\&    sub NAME;                       # A "forward" declaration.
+\&    sub NAME(PROTO);                #  ditto, but with prototypes
+\&    sub NAME : ATTRS;               #  with attributes
+\&    sub NAME(PROTO) : ATTRS;        #  with attributes and prototypes
+\&
+\&    sub NAME BLOCK                  # A declaration and a definition.
+\&    sub NAME(PROTO) BLOCK           #  ditto, but with prototypes
+\&    sub NAME : ATTRS BLOCK          #  with attributes
+\&    sub NAME(PROTO) : ATTRS BLOCK   #  with prototypes and attributes
+\&
+\&    use feature \*(Aqsignatures\*(Aq;
+\&    sub NAME(SIG) BLOCK                     # with signature
+\&    sub NAME :ATTRS (SIG) BLOCK             # with signature, attributes
+\&    sub NAME :prototype(PROTO) (SIG) BLOCK  # with signature, prototype
+.Ve
+.PP
+To define an anonymous subroutine at runtime:
+.IX Xref "subroutine, anonymous"
+.PP
+.Vb 4
+\&    $subref = sub BLOCK;                    # no proto
+\&    $subref = sub (PROTO) BLOCK;            # with proto
+\&    $subref = sub : ATTRS BLOCK;            # with attributes
+\&    $subref = sub (PROTO) : ATTRS BLOCK;    # with proto and attributes
+\&
+\&    use feature \*(Aqsignatures\*(Aq;
+\&    $subref = sub (SIG) BLOCK;          # with signature
+\&    $subref = sub : ATTRS(SIG) BLOCK;   # with signature, attributes
+.Ve
+.PP
+To import subroutines:
+.IX Xref "import"
+.PP
+.Vb 1
+\&    use MODULE qw(NAME1 NAME2 NAME3);
+.Ve
+.PP
+To call subroutines:
+.IX Xref "subroutine, call call"
+.PP
+.Vb 4
+\&    NAME(LIST);     # & is optional with parentheses.
+\&    NAME LIST;      # Parentheses optional if predeclared/imported.
+\&    &NAME(LIST);    # Circumvent prototypes.
+\&    &NAME;          # Makes current @_ visible to called subroutine.
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Like many languages, Perl provides for user-defined subroutines.
+These may be located anywhere in the main program, loaded in from
+other files via the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR keywords, or
+generated on the fly using \f(CW\*(C`eval\*(C'\fR or anonymous subroutines.
+You can even call a function indirectly using a variable containing
+its name or a CODE reference.
+.PP
+The Perl model for function call and return values is simple: all
+functions are passed as parameters one single flat list of scalars, and
+all functions likewise return to their caller one single flat list of
+scalars.  Any arrays or hashes in these call and return lists will
+collapse, losing their identities\-\-but you may always use
+pass-by-reference instead to avoid this.  Both call and return lists may
+contain as many or as few scalar elements as you'd like.  (Often a
+function without an explicit return statement is called a subroutine, but
+there's really no difference from Perl's perspective.)
+.IX Xref "subroutine, parameter parameter"
+.PP
+In a subroutine that uses signatures (see "Signatures" below),
+arguments are assigned into lexical variables introduced by the
+signature.  In the current implementation of Perl they are also
+accessible in the \f(CW@_\fR array in the same way as for non-signature
+subroutines, but accessing them in this manner is now discouraged inside
+such a signature-using subroutine.
+.PP
+In a subroutine that does not use signatures, any arguments passed in
+show up in the array \f(CW@_\fR.  Therefore, if you called a function with
+two arguments, those would be stored in \f(CW$_[0]\fR and \f(CW$_[1]\fR.  The
+array \f(CW@_\fR is a local array, but its elements are aliases for the
+actual scalar parameters.  In particular, if an element \f(CW$_[0]\fR is
+updated, the corresponding argument is updated (or an error occurs if it
+is not updatable).  If an argument is an array or hash element which did
+not exist when the function was called, that element is created only
+when (and if) it is modified or a reference to it is taken.  (Some
+earlier versions of Perl created the element whether or not the element
+was assigned to.) Assigning to the whole array \f(CW@_\fR removes that
+aliasing, and does not update any arguments.
+.IX Xref "subroutine, argument argument @_"
+.PP
+When not using signatures, Perl does not otherwise provide a means to
+create named formal parameters. In practice all you do is assign to a
+\&\f(CWmy()\fR list of these.  Variables that aren't declared to be private are
+global variables.  For gory details on creating private variables, see
+"Private Variables via \fBmy()\fR" and "Temporary Values via \fBlocal()\fR".
+To create protected environments for a set of functions in a separate
+package (and probably a separate file), see "Packages" in perlmod.
+.PP
+A \f(CW\*(C`return\*(C'\fR statement may be used to exit a subroutine, optionally
+specifying the returned value, which will be evaluated in the
+appropriate context (list, scalar, or void) depending on the context of
+the subroutine call.  If you specify no return value, the subroutine
+returns an empty list in list context, the undefined value in scalar
+context, or nothing in void context.  If you return one or more
+aggregates (arrays and hashes), these will be flattened together into
+one large indistinguishable list.
+.PP
+If no \f(CW\*(C`return\*(C'\fR is found and if the last statement is an expression, its
+value is returned.  If the last statement is a loop control structure
+like a \f(CW\*(C`foreach\*(C'\fR or a \f(CW\*(C`while\*(C'\fR, the returned value is unspecified.  The
+empty sub returns the empty list.
+.IX Xref "subroutine, return value return value return"
+.PP
+Example:
+.PP
+.Vb 8
+\&    sub max {
+\&        my $max = shift(@_);
+\&        foreach $foo (@_) {
+\&            $max = $foo if $max < $foo;
+\&        }
+\&        return $max;
+\&    }
+\&    $bestday = max($mon,$tue,$wed,$thu,$fri);
+.Ve
+.PP
+Example:
+.PP
+.Vb 2
+\&    # get a line, combining continuation lines
+\&    #  that start with whitespace
+\&
+\&    sub get_line {
+\&        $thisline = $lookahead;  # global variables!
+\&        LINE: while (defined($lookahead = <STDIN>)) {
+\&            if ($lookahead =~ /^[ \et]/) {
+\&                $thisline .= $lookahead;
+\&            }
+\&            else {
+\&                last LINE;
+\&            }
+\&        }
+\&        return $thisline;
+\&    }
+\&
+\&    $lookahead = <STDIN>;       # get first line
+\&    while (defined($line = get_line())) {
+\&        ...
+\&    }
+.Ve
+.PP
+Assigning to a list of private variables to name your arguments:
+.PP
+.Vb 4
+\&    sub maybeset {
+\&        my($key, $value) = @_;
+\&        $Foo{$key} = $value unless $Foo{$key};
+\&    }
+.Ve
+.PP
+Because the assignment copies the values, this also has the effect
+of turning call-by-reference into call-by-value.  Otherwise a
+function is free to do in-place modifications of \f(CW@_\fR and change
+its caller's values.
+.IX Xref "call-by-reference call-by-value"
+.PP
+.Vb 4
+\&    upcase_in($v1, $v2);  # this changes $v1 and $v2
+\&    sub upcase_in {
+\&        for (@_) { tr/a\-z/A\-Z/ }
+\&    }
+.Ve
+.PP
+You aren't allowed to modify constants in this way, of course.  If an
+argument were actually literal and you tried to change it, you'd take a
+(presumably fatal) exception.   For example, this won't work:
+.IX Xref "call-by-reference call-by-value"
+.PP
+.Vb 1
+\&    upcase_in("frederick");
+.Ve
+.PP
+It would be much safer if the \f(CWupcase_in()\fR function
+were written to return a copy of its parameters instead
+of changing them in place:
+.PP
+.Vb 7
+\&    ($v3, $v4) = upcase($v1, $v2);  # this doesn\*(Aqt change $v1 and $v2
+\&    sub upcase {
+\&        return unless defined wantarray;  # void context, do nothing
+\&        my @parms = @_;
+\&        for (@parms) { tr/a\-z/A\-Z/ }
+\&        return wantarray ? @parms : $parms[0];
+\&    }
+.Ve
+.PP
+Notice how this (unprototyped) function doesn't care whether it was
+passed real scalars or arrays.  Perl sees all arguments as one big,
+long, flat parameter list in \f(CW@_\fR.  This is one area where
+Perl's simple argument-passing style shines.  The \f(CWupcase()\fR
+function would work perfectly well without changing the \f(CWupcase()\fR
+definition even if we fed it things like this:
+.PP
+.Vb 2
+\&    @newlist   = upcase(@list1, @list2);
+\&    @newlist   = upcase( split /:/, $var );
+.Ve
+.PP
+Do not, however, be tempted to do this:
+.PP
+.Vb 1
+\&    (@x, @y)   = upcase(@list1, @list2);
+.Ve
+.PP
+Like the flattened incoming parameter list, the return list is also
+flattened on return.  So all you have managed to do here is stored
+everything in \f(CW@x\fR and made \f(CW@y\fR empty.  See
+"Pass by Reference" for alternatives.
+.PP
+A subroutine may be called using an explicit \f(CW\*(C`&\*(C'\fR prefix.  The
+\&\f(CW\*(C`&\*(C'\fR is optional in modern Perl, as are parentheses if the
+subroutine has been predeclared.  The \f(CW\*(C`&\*(C'\fR is \fInot\fR optional
+when just naming the subroutine, such as when it's used as
+an argument to \fBdefined()\fR or \fBundef()\fR.  Nor is it optional when you
+want to do an indirect subroutine call with a subroutine name or
+reference using the \f(CW&$subref()\fR or \f(CW\*(C`&{$subref}()\*(C'\fR constructs,
+although the \f(CW$subref\->()\fR notation solves that problem.
+See perlref for more about all that.
+.IX Xref "&"
+.PP
+Subroutines may be called recursively.  If a subroutine is called
+using the \f(CW\*(C`&\*(C'\fR form, the argument list is optional, and if omitted,
+no \f(CW@_\fR array is set up for the subroutine: the \f(CW@_\fR array at the
+time of the call is visible to subroutine instead.  This is an
+efficiency mechanism that new users may wish to avoid.
+.IX Xref "recursion"
+.PP
+.Vb 2
+\&    &foo(1,2,3);        # pass three arguments
+\&    foo(1,2,3);         # the same
+\&
+\&    foo();              # pass a null list
+\&    &foo();             # the same
+\&
+\&    &foo;               # foo() get current args, like foo(@_) !!
+\&    use strict \*(Aqsubs\*(Aq;
+\&    foo;                # like foo() iff sub foo predeclared, else
+\&                        # a compile\-time error
+\&    no strict \*(Aqsubs\*(Aq;
+\&    foo;                # like foo() iff sub foo predeclared, else
+\&                        # a literal string "foo"
+.Ve
+.PP
+Not only does the \f(CW\*(C`&\*(C'\fR form make the argument list optional, it also
+disables any prototype checking on arguments you do provide.  This
+is partly for historical reasons, and partly for having a convenient way
+to cheat if you know what you're doing.  See "Prototypes" below.
+.IX Xref "&"
+.PP
+Since Perl 5.16.0, the \f(CW\*(C`_\|_SUB_\|_\*(C'\fR token is available under \f(CWuse feature
+\&\*(Aqcurrent_sub\*(Aq\fR and \f(CW\*(C`use v5.16\*(C'\fR.  It will evaluate to a reference to the
+currently-running sub, which allows for recursive calls without knowing
+your subroutine's name.
+.PP
+.Vb 6
+\&    use v5.16;
+\&    my $factorial = sub {
+\&        my ($x) = @_;
+\&        return 1 if $x == 1;
+\&        return($x * _\|_SUB_\|_\->( $x \- 1 ) );
+\&    };
+.Ve
+.PP
+The behavior of \f(CW\*(C`_\|_SUB_\|_\*(C'\fR within a regex code block (such as \f(CW\*(C`/(?{...})/\*(C'\fR)
+is subject to change.
+.PP
+Subroutines whose names are in all upper case are reserved to the Perl
+core, as are modules whose names are in all lower case.  A subroutine in
+all capitals is a loosely-held convention meaning it will be called
+indirectly by the run-time system itself, usually due to a triggered event.
+Subroutines whose name start with a left parenthesis are also reserved the
+same way.  The following is a list of some subroutines that currently do
+special, pre-defined things.
+.IP "documented later in this document" 4
+.IX Item "documented later in this document"
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR
+.IP "documented in perlmod" 4
+.IX Item "documented in perlmod"
+\&\f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR
+.IP "documented in perlobj" 4
+.IX Item "documented in perlobj"
+\&\f(CW\*(C`DESTROY\*(C'\fR, \f(CW\*(C`DOES\*(C'\fR
+.IP "documented in perltie" 4
+.IX Item "documented in perltie"
+\&\f(CW\*(C`BINMODE\*(C'\fR, \f(CW\*(C`CLEAR\*(C'\fR, \f(CW\*(C`CLOSE\*(C'\fR, \f(CW\*(C`DELETE\*(C'\fR, \f(CW\*(C`DESTROY\*(C'\fR, \f(CW\*(C`EOF\*(C'\fR, \f(CW\*(C`EXISTS\*(C'\fR,
+\&\f(CW\*(C`EXTEND\*(C'\fR, \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`FETCHSIZE\*(C'\fR, \f(CW\*(C`FILENO\*(C'\fR, \f(CW\*(C`FIRSTKEY\*(C'\fR, \f(CW\*(C`GETC\*(C'\fR,
+\&\f(CW\*(C`NEXTKEY\*(C'\fR, \f(CW\*(C`OPEN\*(C'\fR, \f(CW\*(C`POP\*(C'\fR, \f(CW\*(C`PRINT\*(C'\fR, \f(CW\*(C`PRINTF\*(C'\fR, \f(CW\*(C`PUSH\*(C'\fR, \f(CW\*(C`READ\*(C'\fR,
+\&\f(CW\*(C`READLINE\*(C'\fR, \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`SEEK\*(C'\fR, \f(CW\*(C`SHIFT\*(C'\fR, \f(CW\*(C`SPLICE\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR,
+\&\f(CW\*(C`STORESIZE\*(C'\fR, \f(CW\*(C`TELL\*(C'\fR, \f(CW\*(C`TIEARRAY\*(C'\fR, \f(CW\*(C`TIEHANDLE\*(C'\fR, \f(CW\*(C`TIEHASH\*(C'\fR,
+\&\f(CW\*(C`TIESCALAR\*(C'\fR, \f(CW\*(C`UNSHIFT\*(C'\fR, \f(CW\*(C`UNTIE\*(C'\fR, \f(CW\*(C`WRITE\*(C'\fR
+.IP "documented in PerlIO::via" 4
+.IX Item "documented in PerlIO::via"
+\&\f(CW\*(C`BINMODE\*(C'\fR, \f(CW\*(C`CLEARERR\*(C'\fR, \f(CW\*(C`CLOSE\*(C'\fR, \f(CW\*(C`EOF\*(C'\fR, \f(CW\*(C`ERROR\*(C'\fR, \f(CW\*(C`FDOPEN\*(C'\fR, \f(CW\*(C`FILENO\*(C'\fR,
+\&\f(CW\*(C`FILL\*(C'\fR, \f(CW\*(C`FLUSH\*(C'\fR, \f(CW\*(C`OPEN\*(C'\fR, \f(CW\*(C`POPPED\*(C'\fR, \f(CW\*(C`PUSHED\*(C'\fR, \f(CW\*(C`READ\*(C'\fR, \f(CW\*(C`SEEK\*(C'\fR,
+\&\f(CW\*(C`SETLINEBUF\*(C'\fR, \f(CW\*(C`SYSOPEN\*(C'\fR, \f(CW\*(C`TELL\*(C'\fR, \f(CW\*(C`UNREAD\*(C'\fR, \f(CW\*(C`UTF8\*(C'\fR, \f(CW\*(C`WRITE\*(C'\fR
+.IP "documented in perlfunc" 4
+.IX Item "documented in perlfunc"
+\&\f(CW\*(C`import\*(C'\fR, \f(CW\*(C`unimport\*(C'\fR,
+\&\f(CW\*(C`INC\*(C'\fR
+.IP "documented in UNIVERSAL" 4
+.IX Item "documented in UNIVERSAL"
+\&\f(CW\*(C`VERSION\*(C'\fR
+.IP "documented in perldebguts" 4
+.IX Item "documented in perldebguts"
+\&\f(CW\*(C`DB::DB\*(C'\fR, \f(CW\*(C`DB::sub\*(C'\fR, \f(CW\*(C`DB::lsub\*(C'\fR, \f(CW\*(C`DB::goto\*(C'\fR, \f(CW\*(C`DB::postponed\*(C'\fR
+.IP "undocumented, used internally by the overload feature" 4
+.IX Item "undocumented, used internally by the overload feature"
+any starting with \f(CW\*(C`(\*(C'\fR
+.PP
+The \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR subroutines
+are not so much subroutines as named special code blocks, of which you
+can have more than one in a package, and which you can \fBnot\fR call
+explicitly.  See "BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod
+.SS Signatures
+.IX Subsection "Signatures"
+
+.IX Xref "formal parameter parameter, formal"
+.PP
+Perl has a facility to allow a subroutine's formal parameters to be
+declared by special syntax, separate from the procedural code of the
+subroutine body.  The formal parameter list is known as a \fIsignature\fR.
+.PP
+This facility must be enabled before it can be used. It is enabled
+automatically by a \f(CW\*(C`use v5.36\*(C'\fR (or higher) declaration, or more
+directly by \f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR, in the current scope.
+.PP
+The signature is part of a subroutine's body.  Normally the body of a
+subroutine is simply a braced block of code, but when using a signature,
+the signature is a parenthesised list that goes immediately before the
+block, after any name or attributes.
+.PP
+For example,
+.PP
+.Vb 1
+\&    sub foo :lvalue ($x, $y = 1, @z) { .... }
+.Ve
+.PP
+The signature declares lexical variables that are
+in scope for the block.  When the subroutine is called, the signature
+takes control first.  It populates the signature variables from the
+list of arguments that were passed.  If the argument list doesn't meet
+the requirements of the signature, then it will throw an exception.
+When the signature processing is complete, control passes to the block.
+.PP
+Positional parameters are handled by simply naming scalar variables in
+the signature.  For example,
+.PP
+.Vb 3
+\&    sub foo ($left, $right) {
+\&        return $left + $right;
+\&    }
+.Ve
+.PP
+takes two positional parameters, which must be filled at runtime by
+two arguments.  By default the parameters are mandatory, and it is
+not permitted to pass more arguments than expected.  So the above is
+equivalent to
+.PP
+.Vb 7
+\&    sub foo {
+\&        die "Too many arguments for subroutine" unless @_ <= 2;
+\&        die "Too few arguments for subroutine" unless @_ >= 2;
+\&        my $left = $_[0];
+\&        my $right = $_[1];
+\&        return $left + $right;
+\&    }
+.Ve
+.PP
+An argument can be ignored by omitting the main part of the name from
+a parameter declaration, leaving just a bare \f(CW\*(C`$\*(C'\fR sigil.  For example,
+.PP
+.Vb 3
+\&    sub foo ($first, $, $third) {
+\&        return "first=$first, third=$third";
+\&    }
+.Ve
+.PP
+Although the ignored argument doesn't go into a variable, it is still
+mandatory for the caller to pass it.
+.PP
+A positional parameter is made optional by giving a default value,
+separated from the parameter name by \f(CW\*(C`=\*(C'\fR:
+.PP
+.Vb 3
+\&    sub foo ($left, $right = 0) {
+\&        return $left + $right;
+\&    }
+.Ve
+.PP
+The above subroutine may be called with either one or two arguments.
+The default value expression is evaluated when the subroutine is called,
+so it may provide different default values for different calls.  It is
+only evaluated if the argument was actually omitted from the call.
+For example,
+.PP
+.Vb 4
+\&    my $auto_id = 0;
+\&    sub foo ($thing, $id = $auto_id++) {
+\&        print "$thing has ID $id";
+\&    }
+.Ve
+.PP
+automatically assigns distinct sequential IDs to things for which no
+ID was supplied by the caller.  A default value expression may also
+refer to parameters earlier in the signature, making the default for
+one parameter vary according to the earlier parameters.  For example,
+.PP
+.Vb 3
+\&    sub foo ($first_name, $surname, $nickname = $first_name) {
+\&        print "$first_name $surname is known as \e"$nickname\e"";
+\&    }
+.Ve
+.PP
+A default value expression can also be written using the \f(CW\*(C`//=\*(C'\fR operator,
+where it will be evaluated and used if the caller omitted a value or the
+value provided was \f(CW\*(C`undef\*(C'\fR.
+.PP
+.Vb 3
+\&    sub foo ($name //= "world") {
+\&        print "Hello, $name";
+\&    }
+\&
+\&    foo(undef);  # will print "Hello, world"
+.Ve
+.PP
+Similarly, the \f(CW\*(C`||=\*(C'\fR operator can be used to provide a default
+expression to be used whenever the caller provided a false value (and
+remember that a missing or \f(CW\*(C`undef\*(C'\fR value are also false).
+.PP
+.Vb 3
+\&    sub foo ($x ||= 10) {
+\&        return 5 + $x;
+\&    }
+.Ve
+.PP
+An optional parameter can be nameless just like a mandatory parameter.
+For example,
+.PP
+.Vb 3
+\&    sub foo ($thing, $ = 1) {
+\&        print $thing;
+\&    }
+.Ve
+.PP
+The parameter's default value will still be evaluated if the corresponding
+argument isn't supplied, even though the value won't be stored anywhere.
+This is in case evaluating it has important side effects.  However, it
+will be evaluated in void context, so if it doesn't have side effects
+and is not trivial it will generate a warning if the "void" warning
+category is enabled.  If a nameless optional parameter's default value
+is not important, it may be omitted just as the parameter's name was:
+.PP
+.Vb 3
+\&    sub foo ($thing, $=) {
+\&        print $thing;
+\&    }
+.Ve
+.PP
+Optional positional parameters must come after all mandatory positional
+parameters.  (If there are no mandatory positional parameters then an
+optional positional parameters can be the first thing in the signature.)
+If there are multiple optional positional parameters and not enough
+arguments are supplied to fill them all, they will be filled from left
+to right.
+.PP
+After positional parameters, additional arguments may be captured in a
+slurpy parameter.  The simplest form of this is just an array variable:
+.PP
+.Vb 3
+\&    sub foo ($filter, @inputs) {
+\&        print $filter\->($_) foreach @inputs;
+\&    }
+.Ve
+.PP
+With a slurpy parameter in the signature, there is no upper limit on how
+many arguments may be passed.  A slurpy array parameter may be nameless
+just like a positional parameter, in which case its only effect is to
+turn off the argument limit that would otherwise apply:
+.PP
+.Vb 3
+\&    sub foo ($thing, @) {
+\&        print $thing;
+\&    }
+.Ve
+.PP
+A slurpy parameter may instead be a hash, in which case the arguments
+available to it are interpreted as alternating keys and values.
+There must be as many keys as values: if there is an odd argument then
+an exception will be thrown.  Keys will be stringified, and if there are
+duplicates then the later instance takes precedence over the earlier,
+as with standard hash construction.
+.PP
+.Vb 3
+\&    sub foo ($filter, %inputs) {
+\&        print $filter\->($_, $inputs{$_}) foreach sort keys %inputs;
+\&    }
+.Ve
+.PP
+A slurpy hash parameter may be nameless just like other kinds of
+parameter.  It still insists that the number of arguments available to
+it be even, even though they're not being put into a variable.
+.PP
+.Vb 3
+\&    sub foo ($thing, %) {
+\&        print $thing;
+\&    }
+.Ve
+.PP
+A slurpy parameter, either array or hash, must be the last thing in the
+signature.  It may follow mandatory and optional positional parameters;
+it may also be the only thing in the signature.  Slurpy parameters cannot
+have default values: if no arguments are supplied for them then you get
+an empty array or empty hash.
+.PP
+A signature may be entirely empty, in which case all it does is check
+that the caller passed no arguments:
+.PP
+.Vb 3
+\&    sub foo () {
+\&        return 123;
+\&    }
+.Ve
+.PP
+Prior to Perl 5.36 these were considered experimental, and emitted a
+warning in the \f(CW\*(C`experimental::signatures\*(C'\fR category. From Perl 5.36
+onwards this no longer happens, though the warning category still exists
+for back-compatibility with code that attempts to disable it with a
+statement such as:
+.PP
+.Vb 1
+\&    no warnings \*(Aqexperimental::signatures\*(Aq;
+.Ve
+.PP
+In the current Perl implementation, when using a signature the arguments
+are still also available in the special array variable \f(CW@_\fR.  However,
+accessing them via this array is now discouraged, and should not be
+relied upon in newly-written code as this ability may change in a future
+version.  Code that attempts to access the \f(CW@_\fR array will produce
+warnings in the \f(CW\*(C`experimental::args_array_with_signatures\*(C'\fR category when
+compiled:
+.PP
+.Vb 4
+\&    sub f ($x) {
+\&        # This line emits the warning seen below
+\&        print "Arguments are @_";
+\&    }
+.Ve
+.PP
+
+.PP
+.Vb 2
+\&    Use of @_ in join or string with signatured subroutine is
+\&    experimental at ...
+.Ve
+.PP
+There is a difference between the two ways of accessing the arguments:
+\&\f(CW@_\fR \fIaliases\fR the arguments, but the signature variables get
+\&\fIcopies\fR of the arguments.  So writing to a signature variable only
+changes that variable, and has no effect on the caller's variables, but
+writing to an element of \f(CW@_\fR modifies whatever the caller used to
+supply that argument.
+.PP
+There is a potential syntactic ambiguity between signatures and prototypes
+(see "Prototypes"), because both start with an opening parenthesis and
+both can appear in some of the same places, such as just after the name
+in a subroutine declaration.  For historical reasons, when signatures
+are not enabled, any opening parenthesis in such a context will trigger
+very forgiving prototype parsing.  Most signatures will be interpreted
+as prototypes in those circumstances, but won't be valid prototypes.
+(A valid prototype cannot contain any alphabetic character.)  This will
+lead to somewhat confusing error messages.
+.PP
+To avoid ambiguity, when signatures are enabled the special syntax
+for prototypes is disabled.  There is no attempt to guess whether a
+parenthesised group was intended to be a prototype or a signature.
+To give a subroutine a prototype under these circumstances, use a
+prototype attribute.  For example,
+.PP
+.Vb 1
+\&    sub foo :prototype($) { $_[0] }
+.Ve
+.PP
+It is entirely possible for a subroutine to have both a prototype and
+a signature.  They do different jobs: the prototype affects compilation
+of calls to the subroutine, and the signature puts argument values into
+lexical variables at runtime.  You can therefore write
+.PP
+.Vb 3
+\&    sub foo :prototype($$) ($left, $right) {
+\&        return $left + $right;
+\&    }
+.Ve
+.PP
+The prototype attribute, and any other attributes, must come before
+the signature.  The signature always immediately precedes the block of
+the subroutine's body.
+.SS "Private Variables via \fBmy()\fP"
+.IX Xref "my variable, lexical lexical lexical variable scope, lexical lexical scope attributes, my"
+.IX Subsection "Private Variables via my()"
+Synopsis:
+.PP
+.Vb 5
+\&    my $foo;            # declare $foo lexically local
+\&    my (@wid, %get);    # declare list of variables local
+\&    my $foo = "flurp";  # declare $foo lexical, and init it
+\&    my @oof = @bar;     # declare @oof lexical, and init it
+\&    my $x : Foo = $y;   # similar, with an attribute applied
+.Ve
+.PP
+\&\fBWARNING\fR: The use of attribute lists on \f(CW\*(C`my\*(C'\fR declarations is still
+evolving.  The current semantics and interface are subject to change.
+See attributes and Attribute::Handlers.
+.PP
+The \f(CW\*(C`my\*(C'\fR operator declares the listed variables to be lexically
+confined to the enclosing block, conditional
+(\f(CW\*(C`if\*(C'\fR/\f(CW\*(C`unless\*(C'\fR/\f(CW\*(C`elsif\*(C'\fR/\f(CW\*(C`else\*(C'\fR), loop
+(\f(CW\*(C`for\*(C'\fR/\f(CW\*(C`foreach\*(C'\fR/\f(CW\*(C`while\*(C'\fR/\f(CW\*(C`until\*(C'\fR/\f(CW\*(C`continue\*(C'\fR), subroutine, \f(CW\*(C`eval\*(C'\fR,
+or \f(CW\*(C`do\*(C'\fR/\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`use\*(C'\fR'd file.  If more than one value is listed, the
+list must be placed in parentheses.  All listed elements must be
+legal lvalues.  Only alphanumeric identifiers may be lexically
+scoped\-\-magical built-ins like \f(CW$/\fR must currently be \f(CW\*(C`local\*(C'\fRized
+with \f(CW\*(C`local\*(C'\fR instead.
+.PP
+Unlike dynamic variables created by the \f(CW\*(C`local\*(C'\fR operator, lexical
+variables declared with \f(CW\*(C`my\*(C'\fR are totally hidden from the outside
+world, including any called subroutines.  This is true if it's the
+same subroutine called from itself or elsewhere\-\-every call gets
+its own copy.
+.IX Xref "local"
+.PP
+This doesn't mean that a \f(CW\*(C`my\*(C'\fR variable declared in a statically
+enclosing lexical scope would be invisible.  Only dynamic scopes
+are cut off.   For example, the \f(CWbumpx()\fR function below has access
+to the lexical \f(CW$x\fR variable because both the \f(CW\*(C`my\*(C'\fR and the \f(CW\*(C`sub\*(C'\fR
+occurred at the same scope, presumably file scope.
+.PP
+.Vb 2
+\&    my $x = 10;
+\&    sub bumpx { $x++ }
+.Ve
+.PP
+An \f(CWeval()\fR, however, can see lexical variables of the scope it is
+being evaluated in, so long as the names aren't hidden by declarations within
+the \f(CWeval()\fR itself.  See perlref.
+.IX Xref "eval, scope of"
+.PP
+The parameter list to \fBmy()\fR may be assigned to if desired, which allows you
+to initialize your variables.  (If no initializer is given for a
+particular variable, it is created with the undefined value.)  Commonly
+this is used to name input parameters to a subroutine.  Examples:
+.PP
+.Vb 4
+\&    $arg = "fred";          # "global" variable
+\&    $n = cube_root(27);
+\&    print "$arg thinks the root is $n\en";
+\&    # outputs: fred thinks the root is 3
+\&
+\&    sub cube_root {
+\&        my $arg = shift;  # name doesn\*(Aqt matter
+\&        $arg **= 1/3;
+\&        return $arg;
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`my\*(C'\fR is simply a modifier on something you might assign to.  So when
+you do assign to variables in its argument list, \f(CW\*(C`my\*(C'\fR doesn't
+change whether those variables are viewed as a scalar or an array.  So
+.PP
+.Vb 2
+\&    my ($foo) = <STDIN>;                # WRONG?
+\&    my @FOO = <STDIN>;
+.Ve
+.PP
+both supply a list context to the right-hand side, while
+.PP
+.Vb 1
+\&    my $foo = <STDIN>;
+.Ve
+.PP
+supplies a scalar context.  But the following declares only one variable:
+.PP
+.Vb 1
+\&    my $foo, $bar = 1;                  # WRONG
+.Ve
+.PP
+That has the same effect as
+.PP
+.Vb 2
+\&    my $foo;
+\&    $bar = 1;
+.Ve
+.PP
+The declared variable is not introduced (is not visible) until after
+the current statement.  Thus,
+.PP
+.Vb 1
+\&    my $x = $x;
+.Ve
+.PP
+can be used to initialize a new \f(CW$x\fR with the value of the old \f(CW$x\fR, and
+the expression
+.PP
+.Vb 1
+\&    my $x = 123 and $x == 123
+.Ve
+.PP
+is false unless the old \f(CW$x\fR happened to have the value \f(CW123\fR.
+.PP
+Lexical scopes of control structures are not bounded precisely by the
+braces that delimit their controlled blocks; control expressions are
+part of that scope, too.  Thus in the loop
+.PP
+.Vb 5
+\&    while (my $line = <>) {
+\&        $line = lc $line;
+\&    } continue {
+\&        print $line;
+\&    }
+.Ve
+.PP
+the scope of \f(CW$line\fR extends from its declaration throughout the rest of
+the loop construct (including the \f(CW\*(C`continue\*(C'\fR clause), but not beyond
+it.  Similarly, in the conditional
+.PP
+.Vb 8
+\&    if ((my $answer = <STDIN>) =~ /^yes$/i) {
+\&        user_agrees();
+\&    } elsif ($answer =~ /^no$/i) {
+\&        user_disagrees();
+\&    } else {
+\&        chomp $answer;
+\&        die "\*(Aq$answer\*(Aq is neither \*(Aqyes\*(Aq nor \*(Aqno\*(Aq";
+\&    }
+.Ve
+.PP
+the scope of \f(CW$answer\fR extends from its declaration through the rest
+of that conditional, including any \f(CW\*(C`elsif\*(C'\fR and \f(CW\*(C`else\*(C'\fR clauses,
+but not beyond it.  See "Simple Statements" in perlsyn for information
+on the scope of variables in statements with modifiers.
+.PP
+The \f(CW\*(C`foreach\*(C'\fR loop defaults to scoping its index variable dynamically
+in the manner of \f(CW\*(C`local\*(C'\fR.  However, if the index variable is
+prefixed with the keyword \f(CW\*(C`my\*(C'\fR, or if there is already a lexical
+by that name in scope, then a new lexical is created instead.  Thus
+in the loop
+.IX Xref "foreach for"
+.PP
+.Vb 3
+\&    for my $i (1, 2, 3) {
+\&        some_function();
+\&    }
+.Ve
+.PP
+the scope of \f(CW$i\fR extends to the end of the loop, but not beyond it,
+rendering the value of \f(CW$i\fR inaccessible within \f(CWsome_function()\fR.
+.IX Xref "foreach for"
+.PP
+Some users may wish to encourage the use of lexically scoped variables.
+As an aid to catching implicit uses to package variables,
+which are always global, if you say
+.PP
+.Vb 1
+\&    use strict \*(Aqvars\*(Aq;
+.Ve
+.PP
+then any variable mentioned from there to the end of the enclosing
+block must either refer to a lexical variable, be predeclared via
+\&\f(CW\*(C`our\*(C'\fR or \f(CW\*(C`use vars\*(C'\fR, or else must be fully qualified with the package name.
+A compilation error results otherwise.  An inner block may countermand
+this with \f(CW\*(C`no strict \*(Aqvars\*(Aq\*(C'\fR.
+.PP
+A \f(CW\*(C`my\*(C'\fR has both a compile-time and a run-time effect.  At compile
+time, the compiler takes notice of it.  The principal usefulness
+of this is to quiet \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR, but it is also essential
+for generation of closures as detailed in perlref.  Actual
+initialization is delayed until run time, though, so it gets executed
+at the appropriate time, such as each time through a loop, for
+example.
+.PP
+Variables declared with \f(CW\*(C`my\*(C'\fR are not part of any package and are therefore
+never fully qualified with the package name.  In particular, you're not
+allowed to try to make a package variable (or other global) lexical:
+.PP
+.Vb 1
+\&    my $pack::var;      # ERROR!  Illegal syntax
+.Ve
+.PP
+In fact, a dynamic variable (also known as package or global variables)
+are still accessible using the fully qualified \f(CW\*(C`::\*(C'\fR notation even while a
+lexical of the same name is also visible:
+.PP
+.Vb 4
+\&    package main;
+\&    local $x = 10;
+\&    my    $x = 20;
+\&    print "$x and $::x\en";
+.Ve
+.PP
+That will print out \f(CW20\fR and \f(CW10\fR.
+.PP
+You may declare \f(CW\*(C`my\*(C'\fR variables at the outermost scope of a file
+to hide any such identifiers from the world outside that file.  This
+is similar in spirit to C's static variables when they are used at
+the file level.  To do this with a subroutine requires the use of
+a closure (an anonymous function that accesses enclosing lexicals).
+If you want to create a private subroutine that cannot be called
+from outside that block, it can declare a lexical variable containing
+an anonymous sub reference:
+.PP
+.Vb 3
+\&    my $secret_version = \*(Aq1.001\-beta\*(Aq;
+\&    my $secret_sub = sub { print $secret_version };
+\&    &$secret_sub();
+.Ve
+.PP
+As long as the reference is never returned by any function within the
+module, no outside module can see the subroutine, because its name is not in
+any package's symbol table.  Remember that it's not \fIREALLY\fR called
+\&\f(CW$some_pack::secret_version\fR or anything; it's just \f(CW$secret_version\fR,
+unqualified and unqualifiable.
+.PP
+This does not work with object methods, however; all object methods
+have to be in the symbol table of some package to be found.  See
+"Function Templates" in perlref for something of a work-around to
+this.
+.SS "Persistent Private Variables"
+.IX Xref "state state variable static variable, persistent variable, static closure"
+.IX Subsection "Persistent Private Variables"
+There are two ways to build persistent private variables in Perl 5.10.
+First, you can simply use the \f(CW\*(C`state\*(C'\fR feature.  Or, you can use closures,
+if you want to stay compatible with releases older than 5.10.
+.PP
+\fIPersistent variables via \fR\f(BIstate()\fR
+.IX Subsection "Persistent variables via state()"
+.PP
+Beginning with Perl 5.10.0, you can declare variables with the \f(CW\*(C`state\*(C'\fR
+keyword in place of \f(CW\*(C`my\*(C'\fR.  For that to work, though, you must have
+enabled that feature beforehand, either by using the \f(CW\*(C`feature\*(C'\fR pragma, or
+by using \f(CW\*(C`\-E\*(C'\fR on one-liners (see feature).  Beginning with Perl 5.16,
+the \f(CW\*(C`CORE::state\*(C'\fR form does not require the
+\&\f(CW\*(C`feature\*(C'\fR pragma.
+.PP
+The \f(CW\*(C`state\*(C'\fR keyword creates a lexical variable (following the same scoping
+rules as \f(CW\*(C`my\*(C'\fR) that persists from one subroutine call to the next.  If a
+state variable resides inside an anonymous subroutine, then each copy of
+the subroutine has its own copy of the state variable.  However, the value
+of the state variable will still persist between calls to the same copy of
+the anonymous subroutine.  (Don't forget that \f(CW\*(C`sub { ... }\*(C'\fR creates a new
+subroutine each time it is executed.)
+.PP
+For example, the following code maintains a private counter, incremented
+each time the \fBgimme_another()\fR function is called:
+.PP
+.Vb 2
+\&    use feature \*(Aqstate\*(Aq;
+\&    sub gimme_another { state $x; return ++$x }
+.Ve
+.PP
+And this example uses anonymous subroutines to create separate counters:
+.PP
+.Vb 4
+\&    use feature \*(Aqstate\*(Aq;
+\&    sub create_counter {
+\&        return sub { state $x; return ++$x }
+\&    }
+.Ve
+.PP
+Also, since \f(CW$x\fR is lexical, it can't be reached or modified by any Perl
+code outside.
+.PP
+When combined with variable declaration, simple assignment to \f(CW\*(C`state\*(C'\fR
+variables (as in \f(CW\*(C`state $x = 42\*(C'\fR) is executed only the first time.  When such
+statements are evaluated subsequent times, the assignment is ignored.  The
+behavior of assignment to \f(CW\*(C`state\*(C'\fR declarations where the left hand side
+of the assignment involves any parentheses is currently undefined.
+.PP
+\fIPersistent variables with closures\fR
+.IX Subsection "Persistent variables with closures"
+.PP
+Just because a lexical variable is lexically (also called statically)
+scoped to its enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do\*(C'\fR FILE, this doesn't mean that
+within a function it works like a C static.  It normally works more
+like a C auto, but with implicit garbage collection.
+.PP
+Unlike local variables in C or C++, Perl's lexical variables don't
+necessarily get recycled just because their scope has exited.
+If something more permanent is still aware of the lexical, it will
+stick around.  So long as something else references a lexical, that
+lexical won't be freed\-\-which is as it should be.  You wouldn't want
+memory being free until you were done using it, or kept around once you
+were done.  Automatic garbage collection takes care of this for you.
+.PP
+This means that you can pass back or save away references to lexical
+variables, whereas to return a pointer to a C auto is a grave error.
+It also gives us a way to simulate C's function statics.  Here's a
+mechanism for giving a function private variables with both lexical
+scoping and a static lifetime.  If you do want to create something like
+C's static variables, just enclose the whole function in an extra block,
+and put the static variable outside the function but in the block.
+.PP
+.Vb 8
+\&    {
+\&        my $secret_val = 0;
+\&        sub gimme_another {
+\&            return ++$secret_val;
+\&        }
+\&    }
+\&    # $secret_val now becomes unreachable by the outside
+\&    # world, but retains its value between calls to gimme_another
+.Ve
+.PP
+If this function is being sourced in from a separate file
+via \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR, then this is probably just fine.  If it's
+all in the main program, you'll need to arrange for the \f(CW\*(C`my\*(C'\fR
+to be executed early, either by putting the whole block above
+your main program, or more likely, placing merely a \f(CW\*(C`BEGIN\*(C'\fR
+code block around it to make sure it gets executed before your program
+starts to run:
+.PP
+.Vb 6
+\&    BEGIN {
+\&        my $secret_val = 0;
+\&        sub gimme_another {
+\&            return ++$secret_val;
+\&        }
+\&    }
+.Ve
+.PP
+See "BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod about the
+special triggered code blocks, \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR,
+\&\f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR.
+.PP
+If declared at the outermost scope (the file scope), then lexicals
+work somewhat like C's file statics.  They are available to all
+functions in that same file declared below them, but are inaccessible
+from outside that file.  This strategy is sometimes used in modules
+to create private variables that the whole module can see.
+.SS "Temporary Values via \fBlocal()\fP"
+.IX Xref "local scope, dynamic dynamic scope variable, local variable, temporary"
+.IX Subsection "Temporary Values via local()"
+\&\fBWARNING\fR: In general, you should be using \f(CW\*(C`my\*(C'\fR instead of \f(CW\*(C`local\*(C'\fR, because
+it's faster and safer.  Exceptions to this include the global punctuation
+variables, global filehandles and formats, and direct manipulation of the
+Perl symbol table itself.  \f(CW\*(C`local\*(C'\fR is mostly used when the current value
+of a variable must be visible to called subroutines.
+.PP
+Synopsis:
+.PP
+.Vb 1
+\&    # localization of values
+\&
+\&    local $foo;                # make $foo dynamically local
+\&    local (@wid, %get);        # make list of variables local
+\&    local $foo = "flurp";      # make $foo dynamic, and init it
+\&    local @oof = @bar;        # make @oof dynamic, and init it
+\&
+\&    local $hash{key} = "val";  # sets a local value for this hash entry
+\&    delete local $hash{key};   # delete this entry for the current block
+\&    local ($cond ? $v1 : $v2); # several types of lvalues support
+\&                               # localization
+\&
+\&    # localization of symbols
+\&
+\&    local *FH;                 # localize $FH, @FH, %FH, &FH  ...
+\&    local *merlyn = *randal;   # now $merlyn is really $randal, plus
+\&                               #     @merlyn is really @randal, etc
+\&    local *merlyn = \*(Aqrandal\*(Aq;  # SAME THING: promote \*(Aqrandal\*(Aq to *randal
+\&    local *merlyn = \e$randal;  # just alias $merlyn, not @merlyn etc
+.Ve
+.PP
+A \f(CW\*(C`local\*(C'\fR modifies its listed variables to be "local" to the
+enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do FILE\*(C'\fR\-\-and to \fIany subroutine
+called from within that block\fR.  A \f(CW\*(C`local\*(C'\fR just gives temporary
+values to global (meaning package) variables.  It does \fInot\fR create
+a local variable.  This is known as dynamic scoping.  Lexical scoping
+is done with \f(CW\*(C`my\*(C'\fR, which works more like C's auto declarations.
+.PP
+Some types of lvalues can be localized as well: hash and array elements
+and slices, conditionals (provided that their result is always
+localizable), and symbolic references.  As for simple variables, this
+creates new, dynamically scoped values.
+.PP
+If more than one variable or expression is given to \f(CW\*(C`local\*(C'\fR, they must be
+placed in parentheses.  This operator works
+by saving the current values of those variables in its argument list on a
+hidden stack and restoring them upon exiting the block, subroutine, or
+eval.  This means that called subroutines can also reference the local
+variable, but not the global one.  The argument list may be assigned to if
+desired, which allows you to initialize your local variables.  (If no
+initializer is given for a particular variable, it is created with an
+undefined value.)
+.PP
+Because \f(CW\*(C`local\*(C'\fR is a run-time operator, it gets executed each time
+through a loop.  Consequently, it's more efficient to localize your
+variables outside the loop.
+.PP
+\fIGrammatical note on \fR\f(BIlocal()\fR
+.IX Xref "local, context"
+.IX Subsection "Grammatical note on local()"
+.PP
+A \f(CW\*(C`local\*(C'\fR is simply a modifier on an lvalue expression.  When you assign to
+a \f(CW\*(C`local\*(C'\fRized variable, the \f(CW\*(C`local\*(C'\fR doesn't change whether its list is
+viewed as a scalar or an array.  So
+.PP
+.Vb 2
+\&    local($foo) = <STDIN>;
+\&    local @FOO = <STDIN>;
+.Ve
+.PP
+both supply a list context to the right-hand side, while
+.PP
+.Vb 1
+\&    local $foo = <STDIN>;
+.Ve
+.PP
+supplies a scalar context.
+.PP
+\fILocalization of special variables\fR
+.IX Xref "local, special variable"
+.IX Subsection "Localization of special variables"
+.PP
+If you localize a special variable, you'll be giving a new value to it,
+but its magic won't go away.  That means that all side-effects related
+to this magic still work with the localized value.
+.PP
+This feature allows code like this to work :
+.PP
+.Vb 2
+\&    # Read the whole contents of FILE in $slurp
+\&    { local $/ = undef; $slurp = <FILE>; }
+.Ve
+.PP
+Note, however, that this restricts localization of some values ; for
+example, the following statement dies, as of Perl 5.10.0, with an error
+\&\fIModification of a read-only value attempted\fR, because the \f(CW$1\fR variable is
+magical and read-only :
+.PP
+.Vb 1
+\&    local $1 = 2;
+.Ve
+.PP
+One exception is the default scalar variable: starting with Perl 5.14
+\&\f(CWlocal($_)\fR will always strip all magic from \f(CW$_\fR, to make it possible
+to safely reuse \f(CW$_\fR in a subroutine.
+.PP
+\&\fBWARNING\fR: Localization of tied arrays and hashes does not currently
+work as described.
+This will be fixed in a future release of Perl; in the meantime, avoid
+code that relies on any particular behavior of localising tied arrays
+or hashes (localising individual elements is still okay).
+See "Localising Tied Arrays and Hashes Is Broken" in perl58delta for more
+details.
+.IX Xref "local, tie"
+.PP
+\fILocalization of globs\fR
+.IX Xref "local, glob glob"
+.IX Subsection "Localization of globs"
+.PP
+The construct
+.PP
+.Vb 1
+\&    local *name;
+.Ve
+.PP
+creates a whole new symbol table entry for the glob \f(CW\*(C`name\*(C'\fR in the
+current package.  That means that all variables in its glob slot ($name,
+\&\f(CW@name\fR, \f(CW%name\fR, &name, and the \f(CW\*(C`name\*(C'\fR filehandle) are dynamically reset.
+.PP
+This implies, among other things, that any magic eventually carried by
+those variables is locally lost.  In other words, saying \f(CW\*(C`local */\*(C'\fR
+will not have any effect on the internal value of the input record
+separator.
+.PP
+\fILocalization of elements of composite types\fR
+.IX Xref "local, composite type element local, array element local, hash element"
+.IX Subsection "Localization of elements of composite types"
+.PP
+It's also worth taking a moment to explain what happens when you
+\&\f(CW\*(C`local\*(C'\fRize a member of a composite type (i.e. an array or hash element).
+In this case, the element is \f(CW\*(C`local\*(C'\fRized \fIby name\fR.  This means that
+when the scope of the \f(CWlocal()\fR ends, the saved value will be
+restored to the hash element whose key was named in the \f(CWlocal()\fR, or
+the array element whose index was named in the \f(CWlocal()\fR.  If that
+element was deleted while the \f(CWlocal()\fR was in effect (e.g. by a
+\&\f(CWdelete()\fR from a hash or a \f(CWshift()\fR of an array), it will spring
+back into existence, possibly extending an array and filling in the
+skipped elements with \f(CW\*(C`undef\*(C'\fR.  For instance, if you say
+.PP
+.Vb 10
+\&    %hash = ( \*(AqThis\*(Aq => \*(Aqis\*(Aq, \*(Aqa\*(Aq => \*(Aqtest\*(Aq );
+\&    @ary  = ( 0..5 );
+\&    {
+\&        local($ary[5]) = 6;
+\&        local($hash{\*(Aqa\*(Aq}) = \*(Aqdrill\*(Aq;
+\&        while (my $e = pop(@ary)) {
+\&            print "$e . . .\en";
+\&            last unless $e > 3;
+\&        }
+\&        if (@ary) {
+\&            $hash{\*(Aqonly a\*(Aq} = \*(Aqtest\*(Aq;
+\&            delete $hash{\*(Aqa\*(Aq};
+\&        }
+\&    }
+\&    print join(\*(Aq \*(Aq, map { "$_ $hash{$_}" } sort keys %hash),".\en";
+\&    print "The array has ",scalar(@ary)," elements: ",
+\&        join(\*(Aq, \*(Aq, map { defined $_ ? $_ : \*(Aqundef\*(Aq } @ary),"\en";
+.Ve
+.PP
+Perl will print
+.PP
+.Vb 5
+\&    6 . . .
+\&    4 . . .
+\&    3 . . .
+\&    This is a test only a test.
+\&    The array has 6 elements: 0, 1, 2, undef, undef, 5
+.Ve
+.PP
+The behavior of \fBlocal()\fR on non-existent members of composite
+types is subject to change in future. The behavior of \fBlocal()\fR
+on array elements specified using negative indexes is particularly
+surprising, and is very likely to change.
+.PP
+\fILocalized deletion of elements of composite types\fR
+.IX Xref "delete local, composite type element local, array element local, hash element"
+.IX Subsection "Localized deletion of elements of composite types"
+.PP
+You can use the \f(CW\*(C`delete local $array[$idx]\*(C'\fR and \f(CW\*(C`delete local $hash{key}\*(C'\fR
+constructs to delete a composite type entry for the current block and restore
+it when it ends.  They return the array/hash value before the localization,
+which means that they are respectively equivalent to
+.PP
+.Vb 6
+\&    do {
+\&        my $val = $array[$idx];
+\&        local  $array[$idx];
+\&        delete $array[$idx];
+\&        $val
+\&    }
+.Ve
+.PP
+and
+.PP
+.Vb 6
+\&    do {
+\&        my $val = $hash{key};
+\&        local  $hash{key};
+\&        delete $hash{key};
+\&        $val
+\&    }
+.Ve
+.PP
+except that for those the \f(CW\*(C`local\*(C'\fR is
+scoped to the \f(CW\*(C`do\*(C'\fR block.  Slices are
+also accepted.
+.PP
+.Vb 4
+\&    my %hash = (
+\&        a => [ 7, 8, 9 ],
+\&        b => 1,
+\&    )
+\&
+\&    {
+\&        my $x = delete local $hash{a};
+\&        # $x is [ 7, 8, 9 ]
+\&        # %hash is (b => 1)
+\&
+\&        {
+\&            my @nums = delete local @$x[0, 2]
+\&            # @nums is (7, 9)
+\&            # $x is [ undef, 8 ]
+\&
+\&            $x[0] = 999; # will be erased when the scope ends
+\&        }
+\&        # $x is back to [ 7, 8, 9 ]
+\&
+\&    }
+\&    # %hash is back to its original state
+.Ve
+.PP
+This construct is supported since Perl v5.12.
+.SS "Lvalue subroutines"
+.IX Xref "lvalue subroutine, lvalue"
+.IX Subsection "Lvalue subroutines"
+It is possible to return a modifiable value from a subroutine.
+To do this, you have to declare the subroutine to return an lvalue.
+.PP
+.Vb 7
+\&    my $val;
+\&    sub canmod : lvalue {
+\&        $val;  # or:  return $val;
+\&    }
+\&    sub nomod {
+\&        $val;
+\&    }
+\&
+\&    canmod() = 5;   # assigns to $val
+\&    nomod()  = 5;   # ERROR
+.Ve
+.PP
+The scalar/list context for the subroutine and for the right-hand
+side of assignment is determined as if the subroutine call is replaced
+by a scalar.  For example, consider:
+.PP
+.Vb 1
+\&    data(2,3) = get_data(3,4);
+.Ve
+.PP
+Both subroutines here are called in a scalar context, while in:
+.PP
+.Vb 1
+\&    (data(2,3)) = get_data(3,4);
+.Ve
+.PP
+and in:
+.PP
+.Vb 1
+\&    (data(2),data(3)) = get_data(3,4);
+.Ve
+.PP
+all the subroutines are called in a list context.
+.PP
+Lvalue subroutines are convenient, but you have to keep in mind that,
+when used with objects, they may violate encapsulation.  A normal
+mutator can check the supplied argument before setting the attribute
+it is protecting, an lvalue subroutine cannot.  If you require any
+special processing when storing and retrieving the values, consider
+using the CPAN module Sentinel or something similar.
+.SS "Lexical Subroutines"
+.IX Xref "my sub state sub our sub subroutine, lexical"
+.IX Subsection "Lexical Subroutines"
+Beginning with Perl 5.18, you can declare a private subroutine with \f(CW\*(C`my\*(C'\fR
+or \f(CW\*(C`state\*(C'\fR.  As with state variables, the \f(CW\*(C`state\*(C'\fR keyword is only
+available under \f(CW\*(C`use feature \*(Aqstate\*(Aq\*(C'\fR or \f(CW\*(C`use v5.10\*(C'\fR or higher.
+.PP
+Prior to Perl 5.26, lexical subroutines were deemed experimental and were
+available only under the \f(CW\*(C`use feature \*(Aqlexical_subs\*(Aq\*(C'\fR pragma.  They also
+produced a warning unless the "experimental::lexical_subs" warnings
+category was disabled.
+.PP
+These subroutines are only visible within the block in which they are
+declared, and only after that declaration:
+.PP
+.Vb 4
+\&    # Include these two lines if your code is intended to run under Perl
+\&    # versions earlier than 5.26.
+\&    no warnings "experimental::lexical_subs";
+\&    use feature \*(Aqlexical_subs\*(Aq;
+\&
+\&    foo();              # calls the package/global subroutine
+\&    state sub foo {
+\&        foo();          # also calls the package subroutine
+\&    }
+\&    foo();              # calls "state" sub
+\&    my $ref = \e&foo;    # take a reference to "state" sub
+\&
+\&    my sub bar { ... }
+\&    bar();              # calls "my" sub
+.Ve
+.PP
+You can't (directly) write a recursive lexical subroutine:
+.PP
+.Vb 4
+\&    # WRONG
+\&    my sub baz {
+\&        baz();
+\&    }
+.Ve
+.PP
+This example fails because \f(CWbaz()\fR refers to the package/global subroutine
+\&\f(CW\*(C`baz\*(C'\fR, not the lexical subroutine currently being defined.
+.PP
+The solution is to use \f(CW\*(C`_\|_SUB_\|_\*(C'\fR:
+.PP
+.Vb 3
+\&    my sub baz {
+\&        _\|_SUB_\|_\->();    # calls itself
+\&    }
+.Ve
+.PP
+It is possible to predeclare a lexical subroutine.  The \f(CW\*(C`sub foo {...}\*(C'\fR
+subroutine definition syntax respects any previous \f(CW\*(C`my sub;\*(C'\fR or \f(CW\*(C`state sub;\*(C'\fR
+declaration.  Using this to define recursive subroutines is a bad idea,
+however:
+.PP
+.Vb 4
+\&    my sub baz;         # predeclaration
+\&    sub baz {           # define the "my" sub
+\&        baz();          # WRONG: calls itself, but leaks memory
+\&    }
+.Ve
+.PP
+Just like \f(CW\*(C`my $f; $f = sub { $f\->() }\*(C'\fR, this example leaks memory.  The
+name \f(CW\*(C`baz\*(C'\fR is a reference to the subroutine, and the subroutine uses the name
+\&\f(CW\*(C`baz\*(C'\fR; they keep each other alive (see "Circular References" in perlref).
+.PP
+\fR\f(CI\*(C`state sub\*(C'\fR\fI vs \fR\f(CI\*(C`my sub\*(C'\fR\fI\fR
+.IX Subsection "state sub vs my sub"
+.PP
+What is the difference between "state" subs and "my" subs?  Each time that
+execution enters a block when "my" subs are declared, a new copy of each
+sub is created.  "State" subroutines persist from one execution of the
+containing block to the next.
+.PP
+So, in general, "state" subroutines are faster.  But "my" subs are
+necessary if you want to create closures:
+.PP
+.Vb 7
+\&    sub whatever {
+\&        my $x = shift;
+\&        my sub inner {
+\&            ... do something with $x ...
+\&        }
+\&        inner();
+\&    }
+.Ve
+.PP
+In this example, a new \f(CW$x\fR is created when \f(CW\*(C`whatever\*(C'\fR is called, and
+also a new \f(CW\*(C`inner\*(C'\fR, which can see the new \f(CW$x\fR.  A "state" sub will only
+see the \f(CW$x\fR from the first call to \f(CW\*(C`whatever\*(C'\fR.
+.PP
+\fR\f(CI\*(C`our\*(C'\fR\fI subroutines\fR
+.IX Subsection "our subroutines"
+.PP
+Like \f(CW\*(C`our $variable\*(C'\fR, \f(CW\*(C`our sub\*(C'\fR creates a lexical alias to the package
+subroutine of the same name.
+.PP
+The two main uses for this are to switch back to using the package sub
+inside an inner scope:
+.PP
+.Vb 1
+\&    sub foo { ... }
+\&
+\&    sub bar {
+\&        my sub foo { ... }
+\&        {
+\&            # need to use the outer foo here
+\&            our sub foo;
+\&            foo();
+\&        }
+\&    }
+.Ve
+.PP
+and to make a subroutine visible to other packages in the same scope:
+.PP
+.Vb 1
+\&    package MySneakyModule;
+\&
+\&    our sub do_something { ... }
+\&
+\&    sub do_something_with_caller {
+\&        package DB;
+\&        () = caller 1;          # sets @DB::args
+\&        do_something(@args);    # uses MySneakyModule::do_something
+\&    }
+.Ve
+.SS "Passing Symbol Table Entries (typeglobs)"
+.IX Xref "typeglob *"
+.IX Subsection "Passing Symbol Table Entries (typeglobs)"
+\&\fBWARNING\fR: The mechanism described in this section was originally
+the only way to simulate pass-by-reference in older versions of
+Perl.  While it still works fine in modern versions, the new reference
+mechanism is generally easier to work with.  See below.
+.PP
+Sometimes you don't want to pass the value of an array to a subroutine
+but rather the name of it, so that the subroutine can modify the global
+copy of it rather than working with a local copy.  In Perl you can
+refer to all objects of a particular name by prefixing the name
+with a star: \f(CW*foo\fR.  This is often known as a "typeglob", because the
+star on the front can be thought of as a wildcard match for all the
+funny prefix characters on variables and subroutines and such.
+.PP
+When evaluated, the typeglob produces a scalar value that represents
+all the objects of that name, including any filehandle, format, or
+subroutine.  When assigned to, it causes the name mentioned to refer to
+whatever \f(CW\*(C`*\*(C'\fR value was assigned to it.  Example:
+.PP
+.Vb 8
+\&    sub doubleary {
+\&        local(*someary) = @_;
+\&        foreach $elem (@someary) {
+\&            $elem *= 2;
+\&        }
+\&    }
+\&    doubleary(*foo);
+\&    doubleary(*bar);
+.Ve
+.PP
+Scalars are already passed by reference, so you can modify
+scalar arguments without using this mechanism by referring explicitly
+to \f(CW$_[0]\fR etc.  You can modify all the elements of an array by passing
+all the elements as scalars, but you have to use the \f(CW\*(C`*\*(C'\fR mechanism (or
+the equivalent reference mechanism) to \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, or change the size of
+an array.  It will certainly be faster to pass the typeglob (or reference).
+.PP
+Even if you don't want to modify an array, this mechanism is useful for
+passing multiple arrays in a single LIST, because normally the LIST
+mechanism will merge all the array values so that you can't extract out
+the individual arrays.  For more on typeglobs, see
+"Typeglobs and Filehandles" in perldata.
+.SS "When to Still Use \fBlocal()\fP"
+.IX Xref "local variable, local"
+.IX Subsection "When to Still Use local()"
+Despite the existence of \f(CW\*(C`my\*(C'\fR, there are still three places where the
+\&\f(CW\*(C`local\*(C'\fR operator still shines.  In fact, in these three places, you
+\&\fImust\fR use \f(CW\*(C`local\*(C'\fR instead of \f(CW\*(C`my\*(C'\fR.
+.IP 1. 4
+You need to give a global variable a temporary value, especially \f(CW$_\fR.
+.Sp
+The global variables, like \f(CW@ARGV\fR or the punctuation variables, must be
+\&\f(CW\*(C`local\*(C'\fRized with \f(CWlocal()\fR.  This block reads in \fI/etc/motd\fR, and splits
+it up into chunks separated by lines of equal signs, which are placed
+in \f(CW@Fields\fR.
+.Sp
+.Vb 6
+\&    {
+\&        local @ARGV = ("/etc/motd");
+\&        local $/ = undef;
+\&        local $_ = <>;
+\&        @Fields = split /^\es*=+\es*$/;
+\&    }
+.Ve
+.Sp
+It particular, it's important to \f(CW\*(C`local\*(C'\fRize \f(CW$_\fR in any routine that assigns
+to it.  Look out for implicit assignments in \f(CW\*(C`while\*(C'\fR conditionals.
+.IP 2. 4
+You need to create a local file or directory handle or a local function.
+.Sp
+A function that needs a filehandle of its own must use
+\&\f(CWlocal()\fR on a complete typeglob.   This can be used to create new symbol
+table entries:
+.Sp
+.Vb 6
+\&    sub ioqueue {
+\&        local  (*READER, *WRITER);    # not my!
+\&        pipe    (READER,  WRITER)     or die "pipe: $!";
+\&        return (*READER, *WRITER);
+\&    }
+\&    ($head, $tail) = ioqueue();
+.Ve
+.Sp
+See the Symbol module for a way to create anonymous symbol table
+entries.
+.Sp
+Because assignment of a reference to a typeglob creates an alias, this
+can be used to create what is effectively a local function, or at least,
+a local alias.
+.Sp
+.Vb 6
+\&    {
+\&        local *grow = \e&shrink; # only until this block exits
+\&        grow();                # really calls shrink()
+\&        move();                # if move() grow()s, it shrink()s too
+\&    }
+\&    grow();                    # get the real grow() again
+.Ve
+.Sp
+See "Function Templates" in perlref for more about manipulating
+functions by name in this way.
+.IP 3. 4
+You want to temporarily change just one element of an array or hash.
+.Sp
+You can \f(CW\*(C`local\*(C'\fRize just one element of an aggregate.  Usually this
+is done on dynamics:
+.Sp
+.Vb 5
+\&    {
+\&        local $SIG{INT} = \*(AqIGNORE\*(Aq;
+\&        funct();                            # uninterruptible
+\&    }
+\&    # interruptibility automatically restored here
+.Ve
+.Sp
+But it also works on lexically declared aggregates.
+.SS "Pass by Reference"
+.IX Xref "pass by reference pass-by-reference reference"
+.IX Subsection "Pass by Reference"
+If you want to pass more than one array or hash into a function\-\-or
+return them from it\-\-and have them maintain their integrity, then
+you're going to have to use an explicit pass-by-reference.  Before you
+do that, you need to understand references as detailed in perlref.
+This section may not make much sense to you otherwise.
+.PP
+Here are a few simple examples.  First, let's pass in several arrays
+to a function and have it \f(CW\*(C`pop\*(C'\fR all of then, returning a new list
+of all their former last elements:
+.PP
+.Vb 1
+\&    @tailings = popmany ( \e@w, \e@x, \e@y, \e@z );
+\&
+\&    sub popmany {
+\&        my $aref;
+\&        my @retlist;
+\&        foreach $aref ( @_ ) {
+\&            push @retlist, pop @$aref;
+\&        }
+\&        return @retlist;
+\&    }
+.Ve
+.PP
+Here's how you might write a function that returns a
+list of keys occurring in all the hashes passed to it:
+.PP
+.Vb 10
+\&    @common = inter( \e%foo, \e%bar, \e%joe );
+\&    sub inter {
+\&        my ($k, $href, %seen); # locals
+\&        foreach $href (@_) {
+\&            while ( $k = each %$href ) {
+\&                $seen{$k}++;
+\&            }
+\&        }
+\&        return grep { $seen{$_} == @_ } keys %seen;
+\&    }
+.Ve
+.PP
+So far, we're using just the normal list return mechanism.
+What happens if you want to pass or return a hash?  Well,
+if you're using only one of them, or you don't mind them
+concatenating, then the normal calling convention is ok, although
+a little expensive.
+.PP
+Where people get into trouble is here:
+.PP
+.Vb 3
+\&    (@w, @x) = func(@y, @z);
+\&or
+\&    (%w, %x) = func(%y, %z);
+.Ve
+.PP
+That syntax simply won't work.  It sets just \f(CW@w\fR or \f(CW%w\fR and
+clears the \f(CW@x\fR or \f(CW%x\fR.  Plus the function didn't get passed
+into two separate arrays or hashes: it got one long list in \f(CW@_\fR,
+as always.
+.PP
+If you can arrange for everyone to deal with this through references, it's
+cleaner code, although not so nice to look at.  Here's a function that
+takes two array references as arguments, returning the two array elements
+in order of how many elements they have in them:
+.PP
+.Vb 10
+\&    ($wref, $xref) = func(\e@y, \e@z);
+\&    print "@$wref has more than @$xref\en";
+\&    sub func {
+\&        my ($yref, $zref) = @_;
+\&        if (@$yref > @$zref) {
+\&            return ($yref, $zref);
+\&        } else {
+\&            return ($zref, $yref);
+\&        }
+\&    }
+.Ve
+.PP
+It turns out that you can actually do this also:
+.PP
+.Vb 10
+\&    (*w, *x) = func(\e@y, \e@z);
+\&    print "@w has more than @x\en";
+\&    sub func {
+\&        local (*y, *z) = @_;
+\&        if (@y > @z) {
+\&            return (\e@y, \e@z);
+\&        } else {
+\&            return (\e@z, \e@y);
+\&        }
+\&    }
+.Ve
+.PP
+Here we're using the typeglobs to do symbol table aliasing.  It's
+a tad subtle, though, and also won't work if you're using \f(CW\*(C`my\*(C'\fR
+variables, because only globals (even in disguise as \f(CW\*(C`local\*(C'\fRs)
+are in the symbol table.
+.PP
+If you're passing around filehandles, you could usually just use the bare
+typeglob, like \f(CW*STDOUT\fR, but typeglobs references work, too.
+For example:
+.PP
+.Vb 5
+\&    splutter(\e*STDOUT);
+\&    sub splutter {
+\&        my $fh = shift;
+\&        print $fh "her um well a hmmm\en";
+\&    }
+\&
+\&    $rec = get_rec(\e*STDIN);
+\&    sub get_rec {
+\&        my $fh = shift;
+\&        return scalar <$fh>;
+\&    }
+.Ve
+.PP
+If you're planning on generating new filehandles, you could do this.
+Notice to pass back just the bare *FH, not its reference.
+.PP
+.Vb 5
+\&    sub openit {
+\&        my $path = shift;
+\&        local *FH;
+\&        return open (FH, $path) ? *FH : undef;
+\&    }
+.Ve
+.SS Prototypes
+.IX Xref "prototype subroutine, prototype"
+.IX Subsection "Prototypes"
+Perl supports a very limited kind of compile-time argument checking
+using function prototyping.  This can be declared in either the PROTO
+section or with a prototype attribute.
+If you declare either of
+.PP
+.Vb 2
+\&    sub mypush (\e@@)
+\&    sub mypush :prototype(\e@@)
+.Ve
+.PP
+then \f(CWmypush()\fR takes arguments exactly like \f(CWpush()\fR does.
+.PP
+If subroutine signatures are enabled (see "Signatures"), then
+the shorter PROTO syntax is unavailable, because it would clash with
+signatures.  In that case, a prototype can only be declared in the form
+of an attribute.
+.PP
+The
+function declaration must be visible at compile time.  The prototype
+affects only interpretation of new-style calls to the function,
+where new-style is defined as not using the \f(CW\*(C`&\*(C'\fR character.  In
+other words, if you call it like a built-in function, then it behaves
+like a built-in function.  If you call it like an old-fashioned
+subroutine, then it behaves like an old-fashioned subroutine.  It
+naturally falls out from this rule that prototypes have no influence
+on subroutine references like \f(CW\*(C`\e&foo\*(C'\fR or on indirect subroutine
+calls like \f(CW\*(C`&{$subref}\*(C'\fR or \f(CW$subref\->()\fR.
+.PP
+Method calls are not influenced by prototypes either, because the
+function to be called is indeterminate at compile time, since
+the exact code called depends on inheritance.
+.PP
+Because the intent of this feature is primarily to let you define
+subroutines that work like built-in functions, here are prototypes
+for some other functions that parse almost exactly like the
+corresponding built-in.
+.PP
+.Vb 1
+\&    Declared as             Called as
+\&
+\&    sub mylink ($$)         mylink $old, $new
+\&    sub myvec ($$$)         myvec $var, $offset, 1
+\&    sub myindex ($$;$)      myindex &getstring, "substr"
+\&    sub mysyswrite ($$$;$)  mysyswrite $buf, 0, length($buf) \- $off, $off
+\&    sub myreverse (@)       myreverse $x, $y, $z
+\&    sub myjoin ($@)         myjoin ":", $x, $y, $z
+\&    sub mypop (\e@)          mypop @array
+\&    sub mysplice (\e@$$@)    mysplice @array, 0, 2, @pushme
+\&    sub mykeys (\e[%@])      mykeys $hashref\->%*
+\&    sub myopen (*;$)        myopen HANDLE, $name
+\&    sub mypipe (**)         mypipe READHANDLE, WRITEHANDLE
+\&    sub mygrep (&@)         mygrep { /foo/ } $x, $y, $z
+\&    sub myrand (;$)         myrand 42
+\&    sub mytime ()           mytime
+.Ve
+.PP
+Any backslashed prototype character represents an actual argument
+that must start with that character (optionally preceded by \f(CW\*(C`my\*(C'\fR,
+\&\f(CW\*(C`our\*(C'\fR or \f(CW\*(C`local\*(C'\fR), with the exception of \f(CW\*(C`$\*(C'\fR, which will
+accept any scalar lvalue expression, such as \f(CW\*(C`$foo = 7\*(C'\fR or
+\&\f(CW\*(C`my_function()\->[0]\*(C'\fR.  The value passed as part of \f(CW@_\fR will be a
+reference to the actual argument given in the subroutine call,
+obtained by applying \f(CW\*(C`\e\*(C'\fR to that argument.
+.PP
+You can use the \f(CW\*(C`\e[]\*(C'\fR backslash group notation to specify more than one
+allowed argument type.  For example:
+.PP
+.Vb 1
+\&    sub myref (\e[$@%&*])
+.Ve
+.PP
+will allow calling \fBmyref()\fR as
+.PP
+.Vb 5
+\&    myref $var
+\&    myref @array
+\&    myref %hash
+\&    myref &sub
+\&    myref *glob
+.Ve
+.PP
+and the first argument of \fBmyref()\fR will be a reference to
+a scalar, an array, a hash, a code, or a glob.
+.PP
+Unbackslashed prototype characters have special meanings.  Any
+unbackslashed \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR eats all remaining arguments, and forces
+list context.  An argument represented by \f(CW\*(C`$\*(C'\fR forces scalar context.  An
+\&\f(CW\*(C`&\*(C'\fR requires an anonymous subroutine, which, if passed as the first
+argument, does not require the \f(CW\*(C`sub\*(C'\fR keyword or a subsequent comma.
+.PP
+A \f(CW\*(C`*\*(C'\fR allows the subroutine to accept a bareword, constant, scalar expression,
+typeglob, or a reference to a typeglob in that slot.  The value will be
+available to the subroutine either as a simple scalar, or (in the latter
+two cases) as a reference to the typeglob.  If you wish to always convert
+such arguments to a typeglob reference, use \fBSymbol::qualify_to_ref()\fR as
+follows:
+.PP
+.Vb 1
+\&    use Symbol \*(Aqqualify_to_ref\*(Aq;
+\&
+\&    sub foo (*) {
+\&        my $fh = qualify_to_ref(shift, caller);
+\&        ...
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`+\*(C'\fR prototype is a special alternative to \f(CW\*(C`$\*(C'\fR that will act like
+\&\f(CW\*(C`\e[@%]\*(C'\fR when given a literal array or hash variable, but will otherwise
+force scalar context on the argument.  This is useful for functions which
+should accept either a literal array or an array reference as the argument:
+.PP
+.Vb 5
+\&    sub mypush (+@) {
+\&        my $aref = shift;
+\&        die "Not an array or arrayref" unless ref $aref eq \*(AqARRAY\*(Aq;
+\&        push @$aref, @_;
+\&    }
+.Ve
+.PP
+When using the \f(CW\*(C`+\*(C'\fR prototype, your function must check that the argument
+is of an acceptable type.
+.PP
+A semicolon (\f(CW\*(C`;\*(C'\fR) separates mandatory arguments from optional arguments.
+It is redundant before \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, which gobble up everything else.
+.PP
+As the last character of a prototype, or just before a semicolon, a \f(CW\*(C`@\*(C'\fR
+or a \f(CW\*(C`%\*(C'\fR, you can use \f(CW\*(C`_\*(C'\fR in place of \f(CW\*(C`$\*(C'\fR: if this argument is not
+provided, \f(CW$_\fR will be used instead.
+.PP
+Note how the last three examples in the table above are treated
+specially by the parser.  \f(CWmygrep()\fR is parsed as a true list
+operator, \f(CWmyrand()\fR is parsed as a true unary operator with unary
+precedence the same as \f(CWrand()\fR, and \f(CWmytime()\fR is truly without
+arguments, just like \f(CWtime()\fR.  That is, if you say
+.PP
+.Vb 1
+\&    mytime +2;
+.Ve
+.PP
+you'll get \f(CW\*(C`mytime() + 2\*(C'\fR, not \f(CWmytime(2)\fR, which is how it would be parsed
+without a prototype.  If you want to force a unary function to have the
+same precedence as a list operator, add \f(CW\*(C`;\*(C'\fR to the end of the prototype:
+.PP
+.Vb 2
+\&    sub mygetprotobynumber($;);
+\&    mygetprotobynumber $x > $y; # parsed as mygetprotobynumber($x > $y)
+.Ve
+.PP
+The interesting thing about \f(CW\*(C`&\*(C'\fR is that you can generate new syntax with it,
+provided it's in the initial position:
+.IX Xref "&"
+.PP
+.Vb 9
+\&    sub try (&@) {
+\&        my($try,$catch) = @_;
+\&        eval { &$try };
+\&        if ($@) {
+\&            local $_ = $@;
+\&            &$catch;
+\&        }
+\&    }
+\&    sub catch (&) { $_[0] }
+\&
+\&    try {
+\&        die "phooey";
+\&    } catch {
+\&        /phooey/ and print "unphooey\en";
+\&    };
+.Ve
+.PP
+That prints \f(CW"unphooey"\fR.  (Yes, there are still unresolved
+issues having to do with visibility of \f(CW@_\fR.  I'm ignoring that
+question for the moment.  (But note that if we make \f(CW@_\fR lexically
+scoped, those anonymous subroutines can act like closures... (Gee,
+is this sounding a little Lispish?  (Never mind.))))
+.PP
+And here's a reimplementation of the Perl \f(CW\*(C`grep\*(C'\fR operator:
+.IX Xref "grep"
+.PP
+.Vb 8
+\&    sub mygrep (&@) {
+\&        my $code = shift;
+\&        my @result;
+\&        foreach $_ (@_) {
+\&            push(@result, $_) if &$code;
+\&        }
+\&        @result;
+\&    }
+.Ve
+.PP
+Some folks would prefer full alphanumeric prototypes.  Alphanumerics have
+been intentionally left out of prototypes for the express purpose of
+someday in the future adding named, formal parameters.  The current
+mechanism's main goal is to let module writers provide better diagnostics
+for module users.  Larry feels the notation quite understandable to Perl
+programmers, and that it will not intrude greatly upon the meat of the
+module, nor make it harder to read.  The line noise is visually
+encapsulated into a small pill that's easy to swallow.
+.PP
+If you try to use an alphanumeric sequence in a prototype you will
+generate an optional warning \- "Illegal character in prototype...".
+Unfortunately earlier versions of Perl allowed the prototype to be
+used as long as its prefix was a valid prototype.  The warning may be
+upgraded to a fatal error in a future version of Perl once the
+majority of offending code is fixed.
+.PP
+It's probably best to prototype new functions, not retrofit prototyping
+into older ones.  That's because you must be especially careful about
+silent impositions of differing list versus scalar contexts.  For example,
+if you decide that a function should take just one parameter, like this:
+.PP
+.Vb 4
+\&    sub func ($) {
+\&        my $n = shift;
+\&        print "you gave me $n\en";
+\&    }
+.Ve
+.PP
+and someone has been calling it with an array or expression
+returning a list:
+.PP
+.Vb 2
+\&    func(@foo);
+\&    func( $text =~ /\ew+/g );
+.Ve
+.PP
+Then you've just supplied an automatic \f(CW\*(C`scalar\*(C'\fR in front of their
+argument, which can be more than a bit surprising.  The old \f(CW@foo\fR
+which used to hold one thing doesn't get passed in.  Instead,
+\&\f(CWfunc()\fR now gets passed in a \f(CW1\fR; that is, the number of elements
+in \f(CW@foo\fR.  And the \f(CW\*(C`m//g\*(C'\fR gets called in scalar context so instead of a
+list of words it returns a boolean result and advances \f(CWpos($text)\fR.  Ouch!
+.PP
+If a sub has both a PROTO and a BLOCK, the prototype is not applied
+until after the BLOCK is completely defined.  This means that a recursive
+function with a prototype has to be predeclared for the prototype to take
+effect, like so:
+.PP
+.Vb 4
+\&    sub foo($$);
+\&    sub foo($$) {
+\&        foo 1, 2;
+\&    }
+.Ve
+.PP
+This is all very powerful, of course, and should be used only in moderation
+to make the world a better place.
+.SS "Constant Functions"
+.IX Xref "constant"
+.IX Subsection "Constant Functions"
+Functions with a prototype of \f(CW\*(C`()\*(C'\fR are potential candidates for
+inlining.  If the result after optimization and constant folding
+is either a constant or a lexically-scoped scalar which has no other
+references, then it will be used in place of function calls made
+without \f(CW\*(C`&\*(C'\fR.  Calls made using \f(CW\*(C`&\*(C'\fR are never inlined.  (See
+constant for an easy way to declare most constants.)
+.PP
+The following functions would all be inlined:
+.PP
+.Vb 5
+\&    sub pi ()           { 3.14159 }             # Not exact, but close.
+\&    sub PI ()           { 4 * atan2 1, 1 }      # As good as it gets,
+\&                                                # and it\*(Aqs inlined, too!
+\&    sub ST_DEV ()       { 0 }
+\&    sub ST_INO ()       { 1 }
+\&
+\&    sub FLAG_FOO ()     { 1 << 8 }
+\&    sub FLAG_BAR ()     { 1 << 9 }
+\&    sub FLAG_MASK ()    { FLAG_FOO | FLAG_BAR }
+\&
+\&    sub OPT_BAZ ()      { not (0x1B58 & FLAG_MASK) }
+\&
+\&    sub N () { int(OPT_BAZ) / 3 }
+\&
+\&    sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
+\&    sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
+.Ve
+.PP
+(Be aware that the last example was not always inlined in Perl 5.20 and
+earlier, which did not behave consistently with subroutines containing
+inner scopes.)  You can countermand inlining by using an explicit
+\&\f(CW\*(C`return\*(C'\fR:
+.PP
+.Vb 9
+\&    sub baz_val () {
+\&        if (OPT_BAZ) {
+\&            return 23;
+\&        }
+\&        else {
+\&            return 42;
+\&        }
+\&    }
+\&    sub bonk_val () { return 12345 }
+.Ve
+.PP
+As alluded to earlier you can also declare inlined subs dynamically at
+BEGIN time if their body consists of a lexically-scoped scalar which
+has no other references.  Only the first example here will be inlined:
+.PP
+.Vb 5
+\&    BEGIN {
+\&        my $var = 1;
+\&        no strict \*(Aqrefs\*(Aq;
+\&        *INLINED = sub () { $var };
+\&    }
+\&
+\&    BEGIN {
+\&        my $var = 1;
+\&        my $ref = \e$var;
+\&        no strict \*(Aqrefs\*(Aq;
+\&        *NOT_INLINED = sub () { $var };
+\&    }
+.Ve
+.PP
+A not so obvious caveat with this (see [RT #79908]) is what happens if the
+variable is potentially modifiable. For example:
+.PP
+.Vb 6
+\&    BEGIN {
+\&        my $x = 10;
+\&        *FOO = sub () { $x };
+\&        $x++;
+\&    }
+\&    print FOO(); # printed 10 prior to 5.32.0
+.Ve
+.PP
+From Perl 5.22 onwards this gave a deprecation warning, and from Perl 5.32
+onwards it became a run-time error. Previously the variable was
+immediately inlined, and stopped behaving like a normal lexical variable;
+so it printed \f(CW10\fR, not \f(CW11\fR.
+.PP
+If you still want such a subroutine to be inlined (with no warning), make
+sure the variable is not used in a context where it could be modified
+aside from where it is declared.
+.PP
+.Vb 11
+\&    # Fine, no warning
+\&    BEGIN {
+\&        my $x = 54321;
+\&        *INLINED = sub () { $x };
+\&    }
+\&    # Error
+\&    BEGIN {
+\&        my $x;
+\&        $x = 54321;
+\&        *ALSO_INLINED = sub () { $x };
+\&    }
+.Ve
+.PP
+Perl 5.22 also introduces the experimental "const" attribute as an
+alternative.  (Disable the "experimental::const_attr" warnings if you want
+to use it.)  When applied to an anonymous subroutine, it forces the sub to
+be called when the \f(CW\*(C`sub\*(C'\fR expression is evaluated.  The return value is
+captured and turned into a constant subroutine:
+.PP
+.Vb 3
+\&    my $x = 54321;
+\&    *INLINED = sub : const { $x };
+\&    $x++;
+.Ve
+.PP
+The return value of \f(CW\*(C`INLINED\*(C'\fR in this example will always be 54321,
+regardless of later modifications to \f(CW$x\fR.  You can also put any arbitrary
+code inside the sub, at it will be executed immediately and its return
+value captured the same way.
+.PP
+If you really want a subroutine with a \f(CW\*(C`()\*(C'\fR prototype that returns a
+lexical variable you can easily force it to not be inlined by adding
+an explicit \f(CW\*(C`return\*(C'\fR:
+.PP
+.Vb 6
+\&    BEGIN {
+\&        my $x = 10;
+\&        *FOO = sub () { return $x };
+\&        $x++;
+\&    }
+\&    print FOO(); # prints 11
+.Ve
+.PP
+The easiest way to tell if a subroutine was inlined is by using
+B::Deparse.  Consider this example of two subroutines returning
+\&\f(CW1\fR, one with a \f(CW\*(C`()\*(C'\fR prototype causing it to be inlined, and one
+without (with deparse output truncated for clarity):
+.PP
+.Vb 7
+\&    $ perl \-MO=Deparse \-e \*(Aqsub ONE { 1 } if (ONE) { print ONE if ONE }\*(Aq
+\&    sub ONE {
+\&        1;
+\&    }
+\&    if (ONE ) {
+\&        print ONE() if ONE ;
+\&    }
+\&
+\&    $ perl \-MO=Deparse \-e \*(Aqsub ONE () { 1 } if (ONE) { print ONE if ONE }\*(Aq
+\&    sub ONE () { 1 }
+\&    do {
+\&        print 1
+\&    };
+.Ve
+.PP
+If you redefine a subroutine that was eligible for inlining, you'll
+get a warning by default.  You can use this warning to tell whether or
+not a particular subroutine is considered inlinable, since it's
+different than the warning for overriding non-inlined subroutines:
+.PP
+.Vb 4
+\&    $ perl \-e \*(Aqsub one () {1} sub one () {2}\*(Aq
+\&    Constant subroutine one redefined at \-e line 1.
+\&    $ perl \-we \*(Aqsub one {1} sub one {2}\*(Aq
+\&    Subroutine one redefined at \-e line 1.
+.Ve
+.PP
+The warning is considered severe enough not to be affected by the
+\&\fB\-w\fR switch (or its absence) because previously compiled invocations
+of the function will still be using the old value of the function.  If
+you need to be able to redefine the subroutine, you need to ensure
+that it isn't inlined, either by dropping the \f(CW\*(C`()\*(C'\fR prototype (which
+changes calling semantics, so beware) or by thwarting the inlining
+mechanism in some other way, e.g. by adding an explicit \f(CW\*(C`return\*(C'\fR, as
+mentioned above:
+.PP
+.Vb 1
+\&    sub not_inlined () { return 23 }
+.Ve
+.SS "Overriding Built-in Functions"
+.IX Xref "built-in override CORE CORE::GLOBAL"
+.IX Subsection "Overriding Built-in Functions"
+Many built-in functions may be overridden, though this should be tried
+only occasionally and for good reason.  Typically this might be
+done by a package attempting to emulate missing built-in functionality
+on a non-Unix system.
+.PP
+Overriding may be done only by importing the name from a module at
+compile time\-\-ordinary predeclaration isn't good enough.  However, the
+\&\f(CW\*(C`use subs\*(C'\fR pragma lets you, in effect, predeclare subs
+via the import syntax, and these names may then override built-in ones:
+.PP
+.Vb 3
+\&    use subs \*(Aqchdir\*(Aq, \*(Aqchroot\*(Aq, \*(Aqchmod\*(Aq, \*(Aqchown\*(Aq;
+\&    chdir $somewhere;
+\&    sub chdir { ... }
+.Ve
+.PP
+To unambiguously refer to the built-in form, precede the
+built-in name with the special package qualifier \f(CW\*(C`CORE::\*(C'\fR.  For example,
+saying \f(CWCORE::open()\fR always refers to the built-in \f(CWopen()\fR, even
+if the current package has imported some other subroutine called
+\&\f(CW&open()\fR from elsewhere.  Even though it looks like a regular
+function call, it isn't: the \f(CW\*(C`CORE::\*(C'\fR prefix in that case is part of Perl's
+syntax, and works for any keyword, regardless of what is in the \f(CW\*(C`CORE\*(C'\fR
+package.  Taking a reference to it, that is, \f(CW\*(C`\e&CORE::open\*(C'\fR, only works
+for some keywords.  See CORE.
+.PP
+Library modules should not in general export built-in names like \f(CW\*(C`open\*(C'\fR
+or \f(CW\*(C`chdir\*(C'\fR as part of their default \f(CW@EXPORT\fR list, because these may
+sneak into someone else's namespace and change the semantics unexpectedly.
+Instead, if the module adds that name to \f(CW@EXPORT_OK\fR, then it's
+possible for a user to import the name explicitly, but not implicitly.
+That is, they could say
+.PP
+.Vb 1
+\&    use Module \*(Aqopen\*(Aq;
+.Ve
+.PP
+and it would import the \f(CW\*(C`open\*(C'\fR override.  But if they said
+.PP
+.Vb 1
+\&    use Module;
+.Ve
+.PP
+they would get the default imports without overrides.
+.PP
+The foregoing mechanism for overriding built-in is restricted, quite
+deliberately, to the package that requests the import.  There is a second
+method that is sometimes applicable when you wish to override a built-in
+everywhere, without regard to namespace boundaries.  This is achieved by
+importing a sub into the special namespace \f(CW\*(C`CORE::GLOBAL::\*(C'\fR.  Here is an
+example that quite brazenly replaces the \f(CW\*(C`glob\*(C'\fR operator with something
+that understands regular expressions.
+.PP
+.Vb 4
+\&    package REGlob;
+\&    require Exporter;
+\&    @ISA = \*(AqExporter\*(Aq;
+\&    @EXPORT_OK = \*(Aqglob\*(Aq;
+\&
+\&    sub import {
+\&        my $pkg = shift;
+\&        return unless @_;
+\&        my $sym = shift;
+\&        my $where = ($sym =~ s/^GLOBAL_// ? \*(AqCORE::GLOBAL\*(Aq : caller(0));
+\&        $pkg\->export($where, $sym, @_);
+\&    }
+\&
+\&    sub glob {
+\&        my $pat = shift;
+\&        my @got;
+\&        if (opendir my $d, \*(Aq.\*(Aq) {
+\&            @got = grep /$pat/, readdir $d;
+\&            closedir $d;
+\&        }
+\&        return @got;
+\&    }
+\&    1;
+.Ve
+.PP
+And here's how it could be (ab)used:
+.PP
+.Vb 4
+\&    #use REGlob \*(AqGLOBAL_glob\*(Aq;      # override glob() in ALL namespaces
+\&    package Foo;
+\&    use REGlob \*(Aqglob\*(Aq;              # override glob() in Foo:: only
+\&    print for <^[a\-z_]+\e.pm\e$>;     # show all pragmatic modules
+.Ve
+.PP
+The initial comment shows a contrived, even dangerous example.
+By overriding \f(CW\*(C`glob\*(C'\fR globally, you would be forcing the new (and
+subversive) behavior for the \f(CW\*(C`glob\*(C'\fR operator for \fIevery\fR namespace,
+without the complete cognizance or cooperation of the modules that own
+those namespaces.  Naturally, this should be done with extreme caution\-\-if
+it must be done at all.
+.PP
+The \f(CW\*(C`REGlob\*(C'\fR example above does not implement all the support needed to
+cleanly override Perl's \f(CW\*(C`glob\*(C'\fR operator.  The built-in \f(CW\*(C`glob\*(C'\fR has
+different behaviors depending on whether it appears in a scalar or list
+context, but our \f(CW\*(C`REGlob\*(C'\fR doesn't.  Indeed, many Perl built-ins have such
+context sensitive behaviors, and these must be adequately supported by
+a properly written override.  For a fully functional example of overriding
+\&\f(CW\*(C`glob\*(C'\fR, study the implementation of \f(CW\*(C`File::DosGlob\*(C'\fR in the standard
+library.
+.PP
+When you override a built-in, your replacement should be consistent (if
+possible) with the built-in native syntax.  You can achieve this by using
+a suitable prototype.  To get the prototype of an overridable built-in,
+use the \f(CW\*(C`prototype\*(C'\fR function with an argument of \f(CW"CORE::builtin_name"\fR
+(see "prototype" in perlfunc).
+.PP
+Note however that some built-ins can't have their syntax expressed by a
+prototype (such as \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`chomp\*(C'\fR).  If you override them you won't
+be able to fully mimic their original syntax.
+.PP
+The built-ins \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`glob\*(C'\fR can also be overridden, but due
+to special magic, their original syntax is preserved, and you don't have
+to define a prototype for their replacements.  (You can't override the
+\&\f(CW\*(C`do BLOCK\*(C'\fR syntax, though).
+.PP
+\&\f(CW\*(C`require\*(C'\fR has special additional dark magic: if you invoke your
+\&\f(CW\*(C`require\*(C'\fR replacement as \f(CW\*(C`require Foo::Bar\*(C'\fR, it will actually receive
+the argument \f(CW"Foo/Bar.pm"\fR in \f(CW@_\fR.  See "require" in perlfunc.
+.PP
+And, as you'll have noticed from the previous example, if you override
+\&\f(CW\*(C`glob\*(C'\fR, the \f(CW\*(C`<*>\*(C'\fR glob operator is overridden as well.
+.PP
+In a similar fashion, overriding the \f(CW\*(C`readline\*(C'\fR function also overrides
+the equivalent I/O operator \f(CW\*(C`<FILEHANDLE>\*(C'\fR.  Also, overriding
+\&\f(CW\*(C`readpipe\*(C'\fR also overrides the operators \f(CW\`\`\fR and \f(CW\*(C`qx//\*(C'\fR.
+.PP
+Finally, some built-ins (e.g. \f(CW\*(C`exists\*(C'\fR or \f(CW\*(C`grep\*(C'\fR) can't be overridden.
+.SS Autoloading
+.IX Xref "autoloading AUTOLOAD"
+.IX Subsection "Autoloading"
+If you call a subroutine that is undefined, you would ordinarily
+get an immediate, fatal error complaining that the subroutine doesn't
+exist.  (Likewise for subroutines being used as methods, when the
+method doesn't exist in any base class of the class's package.)
+However, if an \f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is defined in the package or
+packages used to locate the original subroutine, then that
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is called with the arguments that would have
+been passed to the original subroutine.  The fully qualified name
+of the original subroutine magically appears in the global \f(CW$AUTOLOAD\fR
+variable of the same package as the \f(CW\*(C`AUTOLOAD\*(C'\fR routine.  The name
+is not passed as an ordinary argument because, er, well, just
+because, that's why.  (As an exception, a method call to a nonexistent
+\&\f(CW\*(C`import\*(C'\fR or \f(CW\*(C`unimport\*(C'\fR method is just skipped instead.  Also, if
+the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
+subroutine name.  See "Autoloading with XSUBs" in perlguts for details.)
+.PP
+Many \f(CW\*(C`AUTOLOAD\*(C'\fR routines load in a definition for the requested
+subroutine using \fBeval()\fR, then execute that subroutine using a special
+form of \fBgoto()\fR that erases the stack frame of the \f(CW\*(C`AUTOLOAD\*(C'\fR routine
+without a trace.  (See the source to the standard module documented
+in AutoLoader, for example.)  But an \f(CW\*(C`AUTOLOAD\*(C'\fR routine can
+also just emulate the routine and never define it.   For example,
+let's pretend that a function that wasn't defined should just invoke
+\&\f(CW\*(C`system\*(C'\fR with those arguments.  All you'd do is:
+.PP
+.Vb 9
+\&    sub AUTOLOAD {
+\&        our $AUTOLOAD;              # keep \*(Aquse strict\*(Aq happy
+\&        my $program = $AUTOLOAD;
+\&        $program =~ s/.*:://;
+\&        system($program, @_);
+\&    }
+\&    date();
+\&    who();
+\&    ls(\*(Aq\-l\*(Aq);
+.Ve
+.PP
+In fact, if you predeclare functions you want to call that way, you don't
+even need parentheses:
+.PP
+.Vb 4
+\&    use subs qw(date who ls);
+\&    date;
+\&    who;
+\&    ls \*(Aq\-l\*(Aq;
+.Ve
+.PP
+A more complete example of this is the Shell module on CPAN, which
+can treat undefined subroutine calls as calls to external programs.
+.PP
+Mechanisms are available to help modules writers split their modules
+into autoloadable files.  See the standard AutoLoader module
+described in AutoLoader and in AutoSplit, the standard
+SelfLoader modules in SelfLoader, and the document on adding C
+functions to Perl code in perlxs.
+.SS "Subroutine Attributes"
+.IX Xref "attribute subroutine, attribute attrs"
+.IX Subsection "Subroutine Attributes"
+A subroutine declaration or definition may have a list of attributes
+associated with it.  If such an attribute list is present, it is
+broken up at space or colon boundaries and treated as though a
+\&\f(CW\*(C`use attributes\*(C'\fR had been seen.  See attributes for details
+about what attributes are currently supported.
+Unlike the limitation with the obsolescent \f(CW\*(C`use attrs\*(C'\fR, the
+\&\f(CW\*(C`sub : ATTRLIST\*(C'\fR syntax works to associate the attributes with
+a pre-declaration, and not just with a subroutine definition.
+.PP
+The attributes must be valid as simple identifier names (without any
+punctuation other than the '_' character).  They may have a parameter
+list appended, which is only checked for whether its parentheses ('(',')')
+nest properly.
+.PP
+Examples of valid syntax (even though the attributes are unknown):
+.PP
+.Vb 3
+\&    sub fnord (&\e%) : switch(10,foo(7,3))  :  expensive;
+\&    sub plugh () : Ugly(\*(Aq\e(") :Bad;
+\&    sub xyzzy : _5x5 { ... }
+.Ve
+.PP
+Examples of invalid syntax:
+.PP
+.Vb 5
+\&    sub fnord : switch(10,foo();    # ()\-string not balanced
+\&    sub snoid : Ugly(\*(Aq(\*(Aq);          # ()\-string not balanced
+\&    sub xyzzy : 5x5;                # "5x5" not a valid identifier
+\&    sub plugh : Y2::north;          # "Y2::north" not a simple identifier
+\&    sub snurt : foo + bar;          # "+" not a colon or space
+.Ve
+.PP
+The attribute list is passed as a list of constant strings to the code
+which associates them with the subroutine.  In particular, the second example
+of valid syntax above currently looks like this in terms of how it's
+parsed and invoked:
+.PP
+.Vb 1
+\&    use attributes _\|_PACKAGE_\|_, \e&plugh, q[Ugly(\*(Aq\e(")], \*(AqBad\*(Aq;
+.Ve
+.PP
+For further details on attribute lists and their manipulation,
+see attributes and Attribute::Handlers.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See "Function Templates" in perlref for more about references and closures.
+See perlxs if you'd like to learn about calling C subroutines from Perl.
+See perlembed if you'd like to learn about calling Perl subroutines from C.
+See perlmod to learn about bundling up your functions in separate files.
+See perlmodlib to learn what library modules come standard on your system.
+See perlootut to learn how to make object method calls.
diff --git a/upstream/mageia-cauldron/man1/perlsyn.1 b/upstream/mageia-cauldron/man1/perlsyn.1
new file mode 100644
index 00000000..7703eac2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsyn.1
@@ -0,0 +1,1630 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSYN 1"
+.TH PERLSYN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsyn \- Perl syntax
+.IX Xref "syntax"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A Perl program consists of a sequence of declarations and statements
+which run from the top to the bottom.  Loops, subroutines, and other
+control structures allow you to jump around within the code.
+.PP
+Perl is a \fBfree-form\fR language: you can format and indent it however
+you like.  Whitespace serves mostly to separate tokens, unlike
+languages like Python where it is an important part of the syntax,
+or Fortran where it is immaterial.
+.PP
+Many of Perl's syntactic elements are \fBoptional\fR.  Rather than
+requiring you to put parentheses around every function call and
+declare every variable, you can often leave such explicit elements off
+and Perl will figure out what you meant.  This is known as \fBDo What I
+Mean\fR, abbreviated \fBDWIM\fR.  It allows programmers to be \fBlazy\fR and to
+code in a style with which they are comfortable.
+.PP
+Perl \fBborrows syntax\fR and concepts from many languages: awk, sed, C,
+Bourne Shell, Smalltalk, Lisp and even English.  Other
+languages have borrowed syntax from Perl, particularly its regular
+expression extensions.  So if you have programmed in another language
+you will see familiar pieces in Perl.  They often work the same, but
+see perltrap for information about how they differ.
+.SS Declarations
+.IX Xref "declaration undef undefined uninitialized"
+.IX Subsection "Declarations"
+The only things you need to declare in Perl are report formats and
+subroutines (and sometimes not even subroutines).  A scalar variable holds
+the undefined value (\f(CW\*(C`undef\*(C'\fR) until it has been assigned a defined
+value, which is anything other than \f(CW\*(C`undef\*(C'\fR.  When used as a number,
+\&\f(CW\*(C`undef\*(C'\fR is treated as \f(CW0\fR; when used as a string, it is treated as
+the empty string, \f(CW""\fR; and when used as a reference that isn't being
+assigned to, it is treated as an error.  If you enable warnings,
+you'll be notified of an uninitialized value whenever you treat
+\&\f(CW\*(C`undef\*(C'\fR as a string or a number.  Well, usually.  Boolean contexts,
+such as:
+.PP
+.Vb 1
+\&    if ($a) {}
+.Ve
+.PP
+are exempt from warnings (because they care about truth rather than
+definedness).  Operators such as \f(CW\*(C`++\*(C'\fR, \f(CW\*(C`\-\-\*(C'\fR, \f(CW\*(C`+=\*(C'\fR,
+\&\f(CW\*(C`\-=\*(C'\fR, and \f(CW\*(C`.=\*(C'\fR, that operate on undefined variables such as:
+.PP
+.Vb 2
+\&    undef $a;
+\&    $a++;
+.Ve
+.PP
+are also always exempt from such warnings.
+.PP
+A declaration can be put anywhere a statement can, but has no effect on
+the execution of the primary sequence of statements: declarations all
+take effect at compile time.  All declarations are typically put at
+the beginning or the end of the script.  However, if you're using
+lexically-scoped private variables created with \f(CWmy()\fR,
+\&\f(CWstate()\fR, or \f(CWour()\fR, you'll have to make sure
+your format or subroutine definition is within the same block scope
+as the my if you expect to be able to access those private variables.
+.PP
+Declaring a subroutine allows a subroutine name to be used as if it were a
+list operator from that point forward in the program.  You can declare a
+subroutine without defining it by saying \f(CW\*(C`sub name\*(C'\fR, thus:
+.IX Xref "subroutine, declaration"
+.PP
+.Vb 2
+\&    sub myname;
+\&    $me = myname $0             or die "can\*(Aqt get myname";
+.Ve
+.PP
+A bare declaration like that declares the function to be a list operator,
+not a unary operator, so you have to be careful to use parentheses (or
+\&\f(CW\*(C`or\*(C'\fR instead of \f(CW\*(C`||\*(C'\fR.)  The \f(CW\*(C`||\*(C'\fR operator binds too tightly to use after
+list operators; it becomes part of the last element.  You can always use
+parentheses around the list operators arguments to turn the list operator
+back into something that behaves more like a function call.  Alternatively,
+you can use the prototype \f(CW\*(C`($)\*(C'\fR to turn the subroutine into a unary
+operator:
+.PP
+.Vb 2
+\&  sub myname ($);
+\&  $me = myname $0             || die "can\*(Aqt get myname";
+.Ve
+.PP
+That now parses as you'd expect, but you still ought to get in the habit of
+using parentheses in that situation.  For more on prototypes, see
+perlsub.
+.PP
+Subroutines declarations can also be loaded up with the \f(CW\*(C`require\*(C'\fR statement
+or both loaded and imported into your namespace with a \f(CW\*(C`use\*(C'\fR statement.
+See perlmod for details on this.
+.PP
+A statement sequence may contain declarations of lexically-scoped
+variables, but apart from declaring a variable name, the declaration acts
+like an ordinary statement, and is elaborated within the sequence of
+statements as if it were an ordinary statement.  That means it actually
+has both compile-time and run-time effects.
+.SS Comments
+.IX Xref "comment #"
+.IX Subsection "Comments"
+Text from a \f(CW"#"\fR character until the end of the line is a comment,
+and is ignored.  Exceptions include \f(CW"#"\fR inside a string or regular
+expression.
+.SS "Simple Statements"
+.IX Xref "statement semicolon expression ;"
+.IX Subsection "Simple Statements"
+The only kind of simple statement is an expression evaluated for its
+side-effects.  Every simple statement must be terminated with a
+semicolon, unless it is the final statement in a block, in which case
+the semicolon is optional.  But put the semicolon in anyway if the
+block takes up more than one line, because you may eventually add
+another line.  Note that there are operators like \f(CW\*(C`eval {}\*(C'\fR, \f(CW\*(C`sub {}\*(C'\fR, and
+\&\f(CW\*(C`do {}\*(C'\fR that \fIlook\fR like compound statements, but aren't\-\-they're just
+TERMs in an expression\-\-and thus need an explicit termination when used
+as the last item in a statement.
+.SS "Statement Modifiers"
+.IX Xref "statement modifier modifier if unless while until when foreach for"
+.IX Subsection "Statement Modifiers"
+Any simple statement may optionally be followed by a \fISINGLE\fR modifier,
+just before the terminating semicolon (or block ending).  The possible
+modifiers are:
+.PP
+.Vb 7
+\&    if EXPR
+\&    unless EXPR
+\&    while EXPR
+\&    until EXPR
+\&    for LIST
+\&    foreach LIST
+\&    when EXPR
+.Ve
+.PP
+The \f(CW\*(C`EXPR\*(C'\fR following the modifier is referred to as the "condition".
+Its truth or falsehood determines how the modifier will behave.
+.PP
+\&\f(CW\*(C`if\*(C'\fR executes the statement once \fIif\fR and only if the condition is
+true.  \f(CW\*(C`unless\*(C'\fR is the opposite, it executes the statement \fIunless\fR
+the condition is true (that is, if the condition is false).  See
+"Scalar values" in perldata for definitions of true and false.
+.PP
+.Vb 2
+\&    print "Basset hounds got long ears" if length $ear >= 10;
+\&    go_outside() and play() unless $is_raining;
+.Ve
+.PP
+The \f(CWfor(each)\fR modifier is an iterator: it executes the statement once
+for each item in the LIST (with \f(CW$_\fR aliased to each item in turn).
+There is no syntax to specify a C\-style for loop or a lexically scoped
+iteration variable in this form.
+.PP
+.Vb 1
+\&    print "Hello $_!\en" for qw(world Dolly nurse);
+.Ve
+.PP
+\&\f(CW\*(C`while\*(C'\fR repeats the statement \fIwhile\fR the condition is true.
+Postfix \f(CW\*(C`while\*(C'\fR has the same magic treatment of some kinds of condition
+that prefix \f(CW\*(C`while\*(C'\fR has.
+\&\f(CW\*(C`until\*(C'\fR does the opposite, it repeats the statement \fIuntil\fR the
+condition is true (or while the condition is false):
+.PP
+.Vb 3
+\&    # Both of these count from 0 to 10.
+\&    print $i++ while $i <= 10;
+\&    print $j++ until $j >  10;
+.Ve
+.PP
+The \f(CW\*(C`while\*(C'\fR and \f(CW\*(C`until\*(C'\fR modifiers have the usual "\f(CW\*(C`while\*(C'\fR loop"
+semantics (conditional evaluated first), except when applied to a
+\&\f(CW\*(C`do\*(C'\fR\-BLOCK (or to the Perl4 \f(CW\*(C`do\*(C'\fR\-SUBROUTINE statement), in
+which case the block executes once before the conditional is
+evaluated.
+.PP
+This is so that you can write loops like:
+.PP
+.Vb 4
+\&    do {
+\&        $line = <STDIN>;
+\&        ...
+\&    } until !defined($line) || $line eq ".\en"
+.Ve
+.PP
+See "do" in perlfunc.  Note also that the loop control statements described
+later will \fINOT\fR work in this construct, because modifiers don't take
+loop labels.  Sorry.  You can always put another block inside of it
+(for \f(CW\*(C`next\*(C'\fR/\f(CW\*(C`redo\*(C'\fR) or around it (for \f(CW\*(C`last\*(C'\fR) to do that sort of thing.
+.IX Xref "next last redo"
+.PP
+For \f(CW\*(C`next\*(C'\fR or \f(CW\*(C`redo\*(C'\fR, just double the braces:
+.PP
+.Vb 4
+\&    do {{
+\&        next if $x == $y;
+\&        # do something here
+\&    }} until $x++ > $z;
+.Ve
+.PP
+For \f(CW\*(C`last\*(C'\fR, you have to be more elaborate and put braces around it:
+.IX Xref "last"
+.PP
+.Vb 6
+\&    {
+\&        do {
+\&            last if $x == $y**2;
+\&            # do something here
+\&        } while $x++ <= $z;
+\&    }
+.Ve
+.PP
+If you need both \f(CW\*(C`next\*(C'\fR and \f(CW\*(C`last\*(C'\fR, you have to do both and also use a
+loop label:
+.PP
+.Vb 7
+\&    LOOP: {
+\&        do {{
+\&            next if $x == $y;
+\&            last LOOP if $x == $y**2;
+\&            # do something here
+\&        }} until $x++ > $z;
+\&    }
+.Ve
+.PP
+\&\fBNOTE:\fR The behaviour of a \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`state\*(C'\fR, or
+\&\f(CW\*(C`our\*(C'\fR modified with a statement modifier conditional
+or loop construct (for example, \f(CW\*(C`my $x if ...\*(C'\fR) is
+\&\fBundefined\fR.  The value of the \f(CW\*(C`my\*(C'\fR variable may be \f(CW\*(C`undef\*(C'\fR, any
+previously assigned value, or possibly anything else.  Don't rely on
+it.  Future versions of perl might do something different from the
+version of perl you try it out on.  Here be dragons.
+.IX Xref "my"
+.PP
+The \f(CW\*(C`when\*(C'\fR modifier is an experimental feature that first appeared in Perl
+5.14.  To use it, you should include a \f(CW\*(C`use v5.14\*(C'\fR declaration.
+(Technically, it requires only the \f(CW\*(C`switch\*(C'\fR feature, but that aspect of it
+was not available before 5.14.)  Operative only from within a \f(CW\*(C`foreach\*(C'\fR
+loop or a \f(CW\*(C`given\*(C'\fR block, it executes the statement only if the smartmatch
+\&\f(CW\*(C`$_ ~~ \fR\f(CIEXPR\fR\f(CW\*(C'\fR is true.  If the statement executes, it is followed by
+a \f(CW\*(C`next\*(C'\fR from inside a \f(CW\*(C`foreach\*(C'\fR and \f(CW\*(C`break\*(C'\fR from inside a \f(CW\*(C`given\*(C'\fR.
+.PP
+Under the current implementation, the \f(CW\*(C`foreach\*(C'\fR loop can be
+anywhere within the \f(CW\*(C`when\*(C'\fR modifier's dynamic scope, but must be
+within the \f(CW\*(C`given\*(C'\fR block's lexical scope.  This restriction may
+be relaxed in a future release.  See "Switch Statements" below.
+.SS "Compound Statements"
+.IX Xref "statement, compound block bracket, curly curly bracket brace { } if unless given while until foreach for continue"
+.IX Subsection "Compound Statements"
+In Perl, a sequence of statements that defines a scope is called a block.
+Sometimes a block is delimited by the file containing it (in the case
+of a required file, or the program as a whole), and sometimes a block
+is delimited by the extent of a string (in the case of an eval).
+.PP
+But generally, a block is delimited by curly brackets, also known as
+braces.  We will call this syntactic construct a BLOCK.  Because enclosing
+braces are also the syntax for hash reference constructor expressions
+(see perlref), you may occasionally need to disambiguate by placing a
+\&\f(CW\*(C`;\*(C'\fR immediately after an opening brace so that Perl realises the brace
+is the start of a block.  You will more frequently need to disambiguate
+the other way, by placing a \f(CW\*(C`+\*(C'\fR immediately before an opening brace to
+force it to be interpreted as a hash reference constructor expression.
+It is considered good style to use these disambiguating mechanisms
+liberally, not only when Perl would otherwise guess incorrectly.
+.PP
+The following compound statements may be used to control flow:
+.PP
+.Vb 4
+\&    if (EXPR) BLOCK
+\&    if (EXPR) BLOCK else BLOCK
+\&    if (EXPR) BLOCK elsif (EXPR) BLOCK ...
+\&    if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+\&
+\&    unless (EXPR) BLOCK
+\&    unless (EXPR) BLOCK else BLOCK
+\&    unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
+\&    unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+\&
+\&    given (EXPR) BLOCK
+\&
+\&    LABEL while (EXPR) BLOCK
+\&    LABEL while (EXPR) BLOCK continue BLOCK
+\&
+\&    LABEL until (EXPR) BLOCK
+\&    LABEL until (EXPR) BLOCK continue BLOCK
+\&
+\&    LABEL for (EXPR; EXPR; EXPR) BLOCK
+\&    LABEL for VAR (LIST) BLOCK
+\&    LABEL for VAR (LIST) BLOCK continue BLOCK
+\&
+\&    LABEL foreach (EXPR; EXPR; EXPR) BLOCK
+\&    LABEL foreach VAR (LIST) BLOCK
+\&    LABEL foreach VAR (LIST) BLOCK continue BLOCK
+\&
+\&    LABEL BLOCK
+\&    LABEL BLOCK continue BLOCK
+\&
+\&    PHASE BLOCK
+.Ve
+.PP
+As of Perl 5.36, you can iterate over multiple values at a time by specifying
+a list of lexicals within parentheses:
+.PP
+.Vb 5
+\&    no warnings "experimental::for_list";
+\&    LABEL for my (VAR, VAR) (LIST) BLOCK
+\&    LABEL for my (VAR, VAR) (LIST) BLOCK continue BLOCK
+\&    LABEL foreach my (VAR, VAR) (LIST) BLOCK
+\&    LABEL foreach my (VAR, VAR) (LIST) BLOCK continue BLOCK
+.Ve
+.PP
+If enabled by the experimental \f(CW\*(C`try\*(C'\fR feature, the following may also be used
+.PP
+.Vb 2
+\&    try BLOCK catch (VAR) BLOCK
+\&    try BLOCK catch (VAR) BLOCK finally BLOCK
+.Ve
+.PP
+The experimental \f(CW\*(C`given\*(C'\fR statement is \fInot automatically enabled\fR; see
+"Switch Statements" below for how to do so, and the attendant caveats.
+.PP
+Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
+not statements.  This means that the curly brackets are \fIrequired\fR\-\-no
+dangling statements allowed.  If you want to write conditionals without
+curly brackets, there are several other ways to do it.  The following
+all do the same thing:
+.PP
+.Vb 5
+\&    if (!open(FOO)) { die "Can\*(Aqt open $FOO: $!" }
+\&    die "Can\*(Aqt open $FOO: $!" unless open(FOO);
+\&    open(FOO)  || die "Can\*(Aqt open $FOO: $!";
+\&    open(FOO) ? () : die "Can\*(Aqt open $FOO: $!";
+\&        # a bit exotic, that last one
+.Ve
+.PP
+The \f(CW\*(C`if\*(C'\fR statement is straightforward.  Because BLOCKs are always
+bounded by curly brackets, there is never any ambiguity about which
+\&\f(CW\*(C`if\*(C'\fR an \f(CW\*(C`else\*(C'\fR goes with.  If you use \f(CW\*(C`unless\*(C'\fR in place of \f(CW\*(C`if\*(C'\fR,
+the sense of the test is reversed.  Like \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`unless\*(C'\fR can be followed
+by \f(CW\*(C`else\*(C'\fR.  \f(CW\*(C`unless\*(C'\fR can even be followed by one or more \f(CW\*(C`elsif\*(C'\fR
+statements, though you may want to think twice before using that particular
+language construct, as everyone reading your code will have to think at least
+twice before they can understand what's going on.
+.PP
+The \f(CW\*(C`while\*(C'\fR statement executes the block as long as the expression is
+true.
+The \f(CW\*(C`until\*(C'\fR statement executes the block as long as the expression is
+false.
+The LABEL is optional, and if present, consists of an identifier followed
+by a colon.  The LABEL identifies the loop for the loop control
+statements \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, and \f(CW\*(C`redo\*(C'\fR.
+If the LABEL is omitted, the loop control statement
+refers to the innermost enclosing loop.  This may include dynamically
+searching through your call-stack at run time to find the LABEL.  Such
+desperate behavior triggers a warning if you use the \f(CW\*(C`use warnings\*(C'\fR
+pragma or the \fB\-w\fR flag.
+.PP
+If the condition expression of a \f(CW\*(C`while\*(C'\fR statement is based
+on any of a group of iterative expression types then it gets
+some magic treatment.  The affected iterative expression types
+are \f(CW\*(C`readline\*(C'\fR, the \f(CW\*(C`<FILEHANDLE>\*(C'\fR input operator, \f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, the \f(CW\*(C`<PATTERN>\*(C'\fR globbing operator, and \f(CW\*(C`each\*(C'\fR.  If the condition expression is one of these expression types, then
+the value yielded by the iterative operator will be implicitly assigned
+to \f(CW$_\fR.  If the condition expression is one of these expression types
+or an explicit assignment of one of them to a scalar, then the condition
+actually tests for definedness of the expression's value, not for its
+regular truth value.
+.PP
+If there is a \f(CW\*(C`continue\*(C'\fR BLOCK, it is always executed just before the
+conditional is about to be evaluated again.  Thus it can be used to
+increment a loop variable, even when the loop has been continued via
+the \f(CW\*(C`next\*(C'\fR statement.
+.PP
+When a block is preceded by a compilation phase keyword such as \f(CW\*(C`BEGIN\*(C'\fR,
+\&\f(CW\*(C`END\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, or \f(CW\*(C`UNITCHECK\*(C'\fR, then the block will run only
+during the corresponding phase of execution.  See perlmod for more details.
+.PP
+Extension modules can also hook into the Perl parser to define new
+kinds of compound statements.  These are introduced by a keyword which
+the extension recognizes, and the syntax following the keyword is
+defined entirely by the extension.  If you are an implementor, see
+"PL_keyword_plugin" in perlapi for the mechanism.  If you are using such
+a module, see the module's documentation for details of the syntax that
+it defines.
+.SS "Loop Control"
+.IX Xref "loop control loop, control next last redo continue"
+.IX Subsection "Loop Control"
+The \f(CW\*(C`next\*(C'\fR command starts the next iteration of the loop:
+.PP
+.Vb 4
+\&    LINE: while (<STDIN>) {
+\&        next LINE if /^#/;      # discard comments
+\&        ...
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`last\*(C'\fR command immediately exits the loop in question.  The
+\&\f(CW\*(C`continue\*(C'\fR block, if any, is not executed:
+.PP
+.Vb 4
+\&    LINE: while (<STDIN>) {
+\&        last LINE if /^$/;      # exit when done with header
+\&        ...
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`redo\*(C'\fR command restarts the loop block without evaluating the
+conditional again.  The \f(CW\*(C`continue\*(C'\fR block, if any, is \fInot\fR executed.
+This command is normally used by programs that want to lie to themselves
+about what was just input.
+.PP
+For example, when processing a file like \fI/etc/termcap\fR.
+If your input lines might end in backslashes to indicate continuation, you
+want to skip ahead and get the next record.
+.PP
+.Vb 8
+\&    while (<>) {
+\&        chomp;
+\&        if (s/\e\e$//) {
+\&            $_ .= <>;
+\&            redo unless eof();
+\&        }
+\&        # now process $_
+\&    }
+.Ve
+.PP
+which is Perl shorthand for the more explicitly written version:
+.PP
+.Vb 8
+\&    LINE: while (defined($line = <ARGV>)) {
+\&        chomp($line);
+\&        if ($line =~ s/\e\e$//) {
+\&            $line .= <ARGV>;
+\&            redo LINE unless eof(); # not eof(ARGV)!
+\&        }
+\&        # now process $line
+\&    }
+.Ve
+.PP
+Note that if there were a \f(CW\*(C`continue\*(C'\fR block on the above code, it would
+get executed only on lines discarded by the regex (since redo skips the
+continue block).  A continue block is often used to reset line counters
+or \f(CW\*(C`m?pat?\*(C'\fR one-time matches:
+.PP
+.Vb 10
+\&    # inspired by :1,$g/fred/s//WILMA/
+\&    while (<>) {
+\&        m?(fred)?    && s//WILMA $1 WILMA/;
+\&        m?(barney)?  && s//BETTY $1 BETTY/;
+\&        m?(homer)?   && s//MARGE $1 MARGE/;
+\&    } continue {
+\&        print "$ARGV $.: $_";
+\&        close ARGV  if eof;             # reset $.
+\&        reset       if eof;             # reset ?pat?
+\&    }
+.Ve
+.PP
+If the word \f(CW\*(C`while\*(C'\fR is replaced by the word \f(CW\*(C`until\*(C'\fR, the sense of the
+test is reversed, but the conditional is still tested before the first
+iteration.
+.PP
+Loop control statements don't work in an \f(CW\*(C`if\*(C'\fR or \f(CW\*(C`unless\*(C'\fR, since
+they aren't loops.  You can double the braces to make them such, though.
+.PP
+.Vb 6
+\&    if (/pattern/) {{
+\&        last if /fred/;
+\&        next if /barney/; # same effect as "last",
+\&                          # but doesn\*(Aqt document as well
+\&        # do something here
+\&    }}
+.Ve
+.PP
+This is caused by the fact that a block by itself acts as a loop that
+executes once, see "Basic BLOCKs".
+.PP
+The form \f(CW\*(C`while/if BLOCK BLOCK\*(C'\fR, available in Perl 4, is no longer
+available.  Replace any occurrence of \f(CW\*(C`if BLOCK\*(C'\fR by \f(CW\*(C`if (do BLOCK)\*(C'\fR.
+.SS "For Loops"
+.IX Xref "for foreach"
+.IX Subsection "For Loops"
+Perl's C\-style \f(CW\*(C`for\*(C'\fR loop works like the corresponding \f(CW\*(C`while\*(C'\fR loop;
+that means that this:
+.PP
+.Vb 3
+\&    for ($i = 1; $i < 10; $i++) {
+\&        ...
+\&    }
+.Ve
+.PP
+is the same as this:
+.PP
+.Vb 6
+\&    $i = 1;
+\&    while ($i < 10) {
+\&        ...
+\&    } continue {
+\&        $i++;
+\&    }
+.Ve
+.PP
+There is one minor difference: if variables are declared with \f(CW\*(C`my\*(C'\fR
+in the initialization section of the \f(CW\*(C`for\*(C'\fR, the lexical scope of
+those variables is exactly the \f(CW\*(C`for\*(C'\fR loop (the body of the loop
+and the control sections).  To illustrate:
+.IX Xref "my"
+.PP
+.Vb 5
+\&    my $i = \*(Aqsamba\*(Aq;
+\&    for (my $i = 1; $i <= 4; $i++) {
+\&        print "$i\en";
+\&    }
+\&    print "$i\en";
+.Ve
+.PP
+when executed, gives:
+.PP
+.Vb 5
+\&    1
+\&    2
+\&    3
+\&    4
+\&    samba
+.Ve
+.PP
+As a special case, if the test in the \f(CW\*(C`for\*(C'\fR loop (or the corresponding
+\&\f(CW\*(C`while\*(C'\fR loop) is empty, it is treated as true.  That is, both
+.PP
+.Vb 3
+\&    for (;;) {
+\&        ...
+\&    }
+.Ve
+.PP
+and
+.PP
+.Vb 3
+\&    while () {
+\&        ...
+\&    }
+.Ve
+.PP
+are treated as infinite loops.
+.PP
+Besides the normal array index looping, \f(CW\*(C`for\*(C'\fR can lend itself
+to many other interesting applications.  Here's one that avoids the
+problem you get into if you explicitly test for end-of-file on
+an interactive file descriptor causing your program to appear to
+hang.
+.IX Xref "eof end-of-file end of file"
+.PP
+.Vb 5
+\&    $on_a_tty = \-t STDIN && \-t STDOUT;
+\&    sub prompt { print "yes? " if $on_a_tty }
+\&    for ( prompt(); <STDIN>; prompt() ) {
+\&        # do something
+\&    }
+.Ve
+.PP
+The condition expression of a \f(CW\*(C`for\*(C'\fR loop gets the same magic treatment of
+\&\f(CW\*(C`readline\*(C'\fR et al that the condition expression of a \f(CW\*(C`while\*(C'\fR loop gets.
+.SS "Foreach Loops"
+.IX Xref "for foreach"
+.IX Subsection "Foreach Loops"
+The \f(CW\*(C`foreach\*(C'\fR loop iterates over a normal list value and sets the scalar
+variable VAR to be each element of the list in turn.  If the variable
+is preceded with the keyword \f(CW\*(C`my\*(C'\fR, then it is lexically scoped, and
+is therefore visible only within the loop.  Otherwise, the variable is
+implicitly local to the loop and regains its former value upon exiting
+the loop.  If the variable was previously declared with \f(CW\*(C`my\*(C'\fR, it uses
+that variable instead of the global one, but it's still localized to
+the loop.  This implicit localization occurs \fIonly\fR for non C\-style
+loops.
+.IX Xref "my local"
+.PP
+The \f(CW\*(C`foreach\*(C'\fR keyword is actually a synonym for the \f(CW\*(C`for\*(C'\fR keyword, so
+you can use either.  If VAR is omitted, \f(CW$_\fR is set to each value.
+.IX Xref "$_"
+.PP
+If any element of LIST is an lvalue, you can modify it by modifying
+VAR inside the loop.  Conversely, if any element of LIST is NOT an
+lvalue, any attempt to modify that element will fail.  In other words,
+the \f(CW\*(C`foreach\*(C'\fR loop index variable is an implicit alias for each item
+in the list that you're looping over.
+.IX Xref "alias"
+.PP
+If any part of LIST is an array, \f(CW\*(C`foreach\*(C'\fR will get very confused if
+you add or remove elements within the loop body, for example with
+\&\f(CW\*(C`splice\*(C'\fR.  So don't do that.
+.IX Xref "splice"
+.PP
+\&\f(CW\*(C`foreach\*(C'\fR probably won't do what you expect if VAR is a tied or other
+special variable.  Don't do that either.
+.PP
+As of Perl 5.22, there is an experimental variant of this loop that accepts
+a variable preceded by a backslash for VAR, in which case the items in the
+LIST must be references.  The backslashed variable will become an alias
+to each referenced item in the LIST, which must be of the correct type.
+The variable needn't be a scalar in this case, and the backslash may be
+followed by \f(CW\*(C`my\*(C'\fR.  To use this form, you must enable the \f(CW\*(C`refaliasing\*(C'\fR
+feature via \f(CW\*(C`use feature\*(C'\fR.  (See feature.  See also "Assigning
+to References" in perlref.)
+.PP
+As of Perl 5.36, you can iterate over multiple values at a time.
+You can only iterate with lexical scalars as the iterator variables \- unlike
+list assignment, it's not possible to use \f(CW\*(C`undef\*(C'\fR to signify a value that
+isn't wanted.  This is a limitation of the current implementation, and might
+be changed in the future.
+.PP
+If the size of the LIST is not an exact multiple of the number of iterator
+variables, then on the last iteration the "excess" iterator variables are
+aliases to \f(CW\*(C`undef\*(C'\fR, as if the LIST had \f(CW\*(C`, undef\*(C'\fR appended as many times as
+needed for its length to become an exact multiple.  This happens whether
+LIST is a literal LIST or an array \- ie arrays are not extended if their
+size is not a multiple of the iteration size, consistent with iterating an
+array one-at-a-time.  As these padding elements are not lvalues, attempting
+to modify them will fail, consistent with the behaviour when iterating a
+list with literal \f(CW\*(C`undef\*(C'\fRs.  If this is not the behaviour you desire, then
+before the loop starts either explicitly extend your array to be an exact
+multiple, or explicitly throw an exception.
+.PP
+Examples:
+.PP
+.Vb 1
+\&    for (@ary) { s/foo/bar/ }
+\&
+\&    for my $elem (@elements) {
+\&        $elem *= 2;
+\&    }
+\&
+\&    for $count (reverse(1..10), "BOOM") {
+\&        print $count, "\en";
+\&        sleep(1);
+\&    }
+\&
+\&    for (1..15) { print "Merry Christmas\en"; }
+\&
+\&    foreach $item (split(/:[\e\e\en:]*/, $ENV{TERMCAP})) {
+\&        print "Item: $item\en";
+\&    }
+\&
+\&    use feature "refaliasing";
+\&    no warnings "experimental::refaliasing";
+\&    foreach \emy %hash (@array_of_hash_references) {
+\&        # do something with each %hash
+\&    }
+\&
+\&    foreach my ($foo, $bar, $baz) (@list) {
+\&        # do something three\-at\-a\-time
+\&    }
+\&
+\&    foreach my ($key, $value) (%hash) {
+\&        # iterate over the hash
+\&        # The hash is immediately copied to a flat list before the loop
+\&        # starts. The list contains copies of keys but aliases of values.
+\&        # This is the same behaviour as for $var (%hash) {...}
+\&    }
+.Ve
+.PP
+Here's how a C programmer might code up a particular algorithm in Perl:
+.PP
+.Vb 9
+\&    for (my $i = 0; $i < @ary1; $i++) {
+\&        for (my $j = 0; $j < @ary2; $j++) {
+\&            if ($ary1[$i] > $ary2[$j]) {
+\&                last; # can\*(Aqt go to outer :\-(
+\&            }
+\&            $ary1[$i] += $ary2[$j];
+\&        }
+\&        # this is where that last takes me
+\&    }
+.Ve
+.PP
+Whereas here's how a Perl programmer more comfortable with the idiom might
+do it:
+.PP
+.Vb 6
+\&    OUTER: for my $wid (@ary1) {
+\&    INNER:   for my $jet (@ary2) {
+\&                next OUTER if $wid > $jet;
+\&                $wid += $jet;
+\&             }
+\&          }
+.Ve
+.PP
+See how much easier this is?  It's cleaner, safer, and faster.  It's
+cleaner because it's less noisy.  It's safer because if code gets added
+between the inner and outer loops later on, the new code won't be
+accidentally executed.  The \f(CW\*(C`next\*(C'\fR explicitly iterates the other loop
+rather than merely terminating the inner one.  And it's faster because
+Perl executes a \f(CW\*(C`foreach\*(C'\fR statement more rapidly than it would the
+equivalent C\-style \f(CW\*(C`for\*(C'\fR loop.
+.PP
+Perceptive Perl hackers may have noticed that a \f(CW\*(C`for\*(C'\fR loop has a return
+value, and that this value can be captured by wrapping the loop in a \f(CW\*(C`do\*(C'\fR
+block.  The reward for this discovery is this cautionary advice:  The
+return value of a \f(CW\*(C`for\*(C'\fR loop is unspecified and may change without notice.
+Do not rely on it.
+.SS "Try Catch Exception Handling"
+.IX Xref "try catch finally"
+.IX Subsection "Try Catch Exception Handling"
+The \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR syntax provides control flow relating to exception
+handling. The \f(CW\*(C`try\*(C'\fR keyword introduces a block which will be executed when it
+is encountered, and the \f(CW\*(C`catch\*(C'\fR block provides code to handle any exception
+that may be thrown by the first.
+.PP
+.Vb 9
+\&    try {
+\&        my $x = call_a_function();
+\&        $x < 100 or die "Too big";
+\&        send_output($x);
+\&    }
+\&    catch ($e) {
+\&        warn "Unable to output a value; $e";
+\&    }
+\&    print "Finished\en";
+.Ve
+.PP
+Here, the body of the \f(CW\*(C`catch\*(C'\fR block (i.e. the \f(CW\*(C`warn\*(C'\fR statement) will be
+executed if the initial block invokes the conditional \f(CW\*(C`die\*(C'\fR, or if either of
+the functions it invokes throws an uncaught exception. The \f(CW\*(C`catch\*(C'\fR block can
+inspect the \f(CW$e\fR lexical variable in this case to see what the exception was.
+If no exception was thrown then the \f(CW\*(C`catch\*(C'\fR block does not happen. In either
+case, execution will then continue from the following statement \- in this
+example the \f(CW\*(C`print\*(C'\fR.
+.PP
+The \f(CW\*(C`catch\*(C'\fR keyword must be immediately followed by a variable declaration in
+parentheses, which introduces a new variable visible to the body of the
+subsequent block. Inside the block this variable will contain the exception
+value that was thrown by the code in the \f(CW\*(C`try\*(C'\fR block. It is not necessary
+to use the \f(CW\*(C`my\*(C'\fR keyword to declare this variable; this is implied (similar
+as it is for subroutine signatures).
+.PP
+Both the \f(CW\*(C`try\*(C'\fR and the \f(CW\*(C`catch\*(C'\fR blocks are permitted to contain control-flow
+expressions, such as \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`goto\*(C'\fR, or \f(CW\*(C`next\*(C'\fR/\f(CW\*(C`last\*(C'\fR/\f(CW\*(C`redo\*(C'\fR. In all
+cases they behave as expected without warnings. In particular, a \f(CW\*(C`return\*(C'\fR
+expression inside the \f(CW\*(C`try\*(C'\fR block will make its entire containing function
+return \- this is in contrast to its behaviour inside an \f(CW\*(C`eval\*(C'\fR block, where
+it would only make that block return.
+.PP
+Like other control-flow syntax, \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR will yield the last
+evaluated value when placed as the final statement in a function or a \f(CW\*(C`do\*(C'\fR
+block. This permits the syntax to be used to create a value. In this case
+remember not to use the \f(CW\*(C`return\*(C'\fR expression, or that will cause the
+containing function to return.
+.PP
+.Vb 9
+\&    my $value = do {
+\&        try {
+\&            get_thing(@args);
+\&        }
+\&        catch ($e) {
+\&            warn "Unable to get thing \- $e";
+\&            $DEFAULT_THING;
+\&        }
+\&    };
+.Ve
+.PP
+As with other control-flow syntax, \f(CW\*(C`try\*(C'\fR blocks are not visible to
+\&\f(CWcaller()\fR (just as for example, \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`foreach\*(C'\fR loops are not).
+Successive levels of the \f(CW\*(C`caller\*(C'\fR result can see subroutine calls and
+\&\f(CW\*(C`eval\*(C'\fR blocks, because those affect the way that \f(CW\*(C`return\*(C'\fR would work. Since
+\&\f(CW\*(C`try\*(C'\fR blocks do not intercept \f(CW\*(C`return\*(C'\fR, they are not of interest to
+\&\f(CW\*(C`caller\*(C'\fR.
+.PP
+The \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR blocks may optionally be followed by a third block
+introduced by the \f(CW\*(C`finally\*(C'\fR keyword. This third block is executed after the
+rest of the construct has finished.
+.PP
+.Vb 9
+\&    try {
+\&        call_a_function();
+\&    }
+\&    catch ($e) {
+\&        warn "Unable to call; $e";
+\&    }
+\&    finally {
+\&        print "Finished\en";
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`finally\*(C'\fR block is equivalent to using a \f(CW\*(C`defer\*(C'\fR block and will be
+invoked in the same situations; whether the \f(CW\*(C`try\*(C'\fR block completes
+successfully, throws an exception, or transfers control elsewhere by using
+\&\f(CW\*(C`return\*(C'\fR, a loop control, or \f(CW\*(C`goto\*(C'\fR.
+.PP
+Unlike the \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR blocks, a \f(CW\*(C`finally\*(C'\fR block is not permitted to
+\&\f(CW\*(C`return\*(C'\fR, \f(CW\*(C`goto\*(C'\fR or use any loop controls. The final expression value is
+ignored, and does not affect the return value of the containing function even
+if it is placed last in the function.
+.PP
+This syntax is currently experimental and must be enabled with
+\&\f(CW\*(C`use feature \*(Aqtry\*(Aq\*(C'\fR. It emits a warning in the \f(CW\*(C`experimental::try\*(C'\fR category.
+.SS "Basic BLOCKs"
+.IX Xref "block"
+.IX Subsection "Basic BLOCKs"
+A BLOCK by itself (labeled or not) is semantically equivalent to a
+loop that executes once.  Thus you can use any of the loop control
+statements in it to leave or restart the block.  (Note that this is
+\&\fINOT\fR true in \f(CW\*(C`eval{}\*(C'\fR, \f(CW\*(C`sub{}\*(C'\fR, or contrary to popular belief
+\&\f(CW\*(C`do{}\*(C'\fR blocks, which do \fINOT\fR count as loops.)  The \f(CW\*(C`continue\*(C'\fR
+block is optional.
+.PP
+The BLOCK construct can be used to emulate case structures.
+.PP
+.Vb 6
+\&    SWITCH: {
+\&        if (/^abc/) { $abc = 1; last SWITCH; }
+\&        if (/^def/) { $def = 1; last SWITCH; }
+\&        if (/^xyz/) { $xyz = 1; last SWITCH; }
+\&        $nothing = 1;
+\&    }
+.Ve
+.PP
+You'll also find that \f(CW\*(C`foreach\*(C'\fR loop used to create a topicalizer
+and a switch:
+.PP
+.Vb 7
+\&    SWITCH:
+\&    for ($var) {
+\&        if (/^abc/) { $abc = 1; last SWITCH; }
+\&        if (/^def/) { $def = 1; last SWITCH; }
+\&        if (/^xyz/) { $xyz = 1; last SWITCH; }
+\&        $nothing = 1;
+\&    }
+.Ve
+.PP
+Such constructs are quite frequently used, both because older versions of
+Perl had no official \f(CW\*(C`switch\*(C'\fR statement, and also because the new version
+described immediately below remains experimental and can sometimes be confusing.
+.SS "defer blocks"
+.IX Xref "defer"
+.IX Subsection "defer blocks"
+A block prefixed by the \f(CW\*(C`defer\*(C'\fR modifier provides a section of code which
+runs at a later time during scope exit.
+.PP
+A \f(CW\*(C`defer\*(C'\fR block can appear at any point where a regular block or other
+statement is permitted. If the flow of execution reaches this statement, the
+body of the block is stored for later, but not invoked immediately. When the
+flow of control leaves the containing block for any reason, this stored block
+is executed on the way past. It provides a means of deferring execution until
+a later time. This acts similarly to syntax provided by some other languages,
+often using keywords named \f(CW\*(C`try / finally\*(C'\fR.
+.PP
+This syntax is available if enabled by the \f(CW\*(C`defer\*(C'\fR named feature, and is
+currently experimental. If experimental warnings are enabled it will emit a
+warning when used.
+.PP
+.Vb 1
+\&    use feature \*(Aqdefer\*(Aq;
+\&
+\&    {
+\&        say "This happens first";
+\&        defer { say "This happens last"; }
+\&
+\&        say "And this happens inbetween";
+\&    }
+.Ve
+.PP
+If multiple \f(CW\*(C`defer\*(C'\fR blocks are contained in a single scope, they are
+executed in LIFO order; the last one reached is the first one executed.
+.PP
+The code stored by the \f(CW\*(C`defer\*(C'\fR block will be invoked when control leaves
+its containing block due to regular fallthrough, explicit \f(CW\*(C`return\*(C'\fR,
+exceptions thrown by \f(CW\*(C`die\*(C'\fR or propagated by functions called by it, \f(CW\*(C`goto\*(C'\fR,
+or any of the loop control statements \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR or \f(CW\*(C`redo\*(C'\fR.
+.PP
+If the flow of control does not reach the \f(CW\*(C`defer\*(C'\fR statement itself then its
+body is not stored for later execution. (This is in direct contrast to the
+code provided by an \f(CW\*(C`END\*(C'\fR phaser block, which is always enqueued by the
+compiler, regardless of whether execution ever reached the line it was given
+on.)
+.PP
+.Vb 1
+\&    use feature \*(Aqdefer\*(Aq;
+\&
+\&    {
+\&        defer { say "This will run"; }
+\&        return;
+\&        defer { say "This will not"; }
+\&    }
+.Ve
+.PP
+Exceptions thrown by code inside a \f(CW\*(C`defer\*(C'\fR block will propagate to the
+caller in the same way as any other exception thrown by normal code.
+.PP
+If the \f(CW\*(C`defer\*(C'\fR block is being executed due to a thrown exception and throws
+another one it is not specified what happens, beyond that the caller will
+definitely receive an exception.
+.PP
+Besides throwing an exception, a \f(CW\*(C`defer\*(C'\fR block is not permitted to
+otherwise alter the control flow of its surrounding code. In particular, it
+may not cause its containing function to \f(CW\*(C`return\*(C'\fR, nor may it \f(CW\*(C`goto\*(C'\fR a
+label, or control a containing loop using \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR or \f(CW\*(C`redo\*(C'\fR. These
+constructions are however, permitted entirely within the body of the
+\&\f(CW\*(C`defer\*(C'\fR.
+.PP
+.Vb 1
+\&    use feature \*(Aqdefer\*(Aq;
+\&
+\&    {
+\&        defer {
+\&            foreach ( 1 .. 5 ) {
+\&                last if $_ == 3;     # this is permitted
+\&            }
+\&        }
+\&    }
+\&
+\&    {
+\&        foreach ( 6 .. 10 ) {
+\&            defer {
+\&                last if $_ == 8;     # this is not
+\&            }
+\&        }
+\&    }
+.Ve
+.SS "Switch Statements"
+.IX Subsection "Switch Statements"
+
+.IX Xref "switch case given when default"
+.PP
+Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work
+right), you can say
+.PP
+.Vb 1
+\&    use feature "switch";
+.Ve
+.PP
+to enable an experimental switch feature.  This is loosely based on an
+old version of a Raku proposal, but it no longer resembles the Raku
+construct.  You also get the switch feature whenever you declare that your
+code prefers to run under a version of Perl between 5.10 and 5.34.  For
+example:
+.PP
+.Vb 1
+\&    use v5.14;
+.Ve
+.PP
+Under the "switch" feature, Perl gains the experimental keywords
+\&\f(CW\*(C`given\*(C'\fR, \f(CW\*(C`when\*(C'\fR, \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`continue\*(C'\fR, and \f(CW\*(C`break\*(C'\fR.
+Starting from Perl 5.16, one can prefix the switch
+keywords with \f(CW\*(C`CORE::\*(C'\fR to access the feature without a \f(CW\*(C`use feature\*(C'\fR
+statement.  The keywords \f(CW\*(C`given\*(C'\fR and
+\&\f(CW\*(C`when\*(C'\fR are analogous to \f(CW\*(C`switch\*(C'\fR and
+\&\f(CW\*(C`case\*(C'\fR in other languages \-\- though \f(CW\*(C`continue\*(C'\fR is not \-\- so the code
+in the previous section could be rewritten as
+.PP
+.Vb 7
+\&    use v5.10.1;
+\&    for ($var) {
+\&        when (/^abc/) { $abc = 1 }
+\&        when (/^def/) { $def = 1 }
+\&        when (/^xyz/) { $xyz = 1 }
+\&        default       { $nothing = 1 }
+\&    }
+.Ve
+.PP
+The \f(CW\*(C`foreach\*(C'\fR is the non-experimental way to set a topicalizer.
+If you wish to use the highly experimental \f(CW\*(C`given\*(C'\fR, that could be
+written like this:
+.PP
+.Vb 7
+\&    use v5.10.1;
+\&    given ($var) {
+\&        when (/^abc/) { $abc = 1 }
+\&        when (/^def/) { $def = 1 }
+\&        when (/^xyz/) { $xyz = 1 }
+\&        default       { $nothing = 1 }
+\&    }
+.Ve
+.PP
+As of 5.14, that can also be written this way:
+.PP
+.Vb 7
+\&    use v5.14;
+\&    for ($var) {
+\&        $abc = 1 when /^abc/;
+\&        $def = 1 when /^def/;
+\&        $xyz = 1 when /^xyz/;
+\&        default { $nothing = 1 }
+\&    }
+.Ve
+.PP
+Or if you don't care to play it safe, like this:
+.PP
+.Vb 7
+\&    use v5.14;
+\&    given ($var) {
+\&        $abc = 1 when /^abc/;
+\&        $def = 1 when /^def/;
+\&        $xyz = 1 when /^xyz/;
+\&        default { $nothing = 1 }
+\&    }
+.Ve
+.PP
+The arguments to \f(CW\*(C`given\*(C'\fR and \f(CW\*(C`when\*(C'\fR are in scalar context,
+and \f(CW\*(C`given\*(C'\fR assigns the \f(CW$_\fR variable its topic value.
+.PP
+Exactly what the \fIEXPR\fR argument to \f(CW\*(C`when\*(C'\fR does is hard to describe
+precisely, but in general, it tries to guess what you want done.  Sometimes
+it is interpreted as \f(CW\*(C`$_ ~~ \fR\f(CIEXPR\fR\f(CW\*(C'\fR, and sometimes it is not.  It
+also behaves differently when lexically enclosed by a \f(CW\*(C`given\*(C'\fR block than
+it does when dynamically enclosed by a \f(CW\*(C`foreach\*(C'\fR loop.  The rules are far
+too difficult to understand to be described here.  See "Experimental Details
+on given and when" later on.
+.PP
+Due to an unfortunate bug in how \f(CW\*(C`given\*(C'\fR was implemented between Perl 5.10
+and 5.16, under those implementations the version of \f(CW$_\fR governed by
+\&\f(CW\*(C`given\*(C'\fR is merely a lexically scoped copy of the original, not a
+dynamically scoped alias to the original, as it would be if it were a
+\&\f(CW\*(C`foreach\*(C'\fR or under both the original and the current Raku language
+specification.  This bug was fixed in Perl 5.18 (and lexicalized \f(CW$_\fR itself
+was removed in Perl 5.24).
+.PP
+If your code still needs to run on older versions,
+stick to \f(CW\*(C`foreach\*(C'\fR for your topicalizer and
+you will be less unhappy.
+.SS Goto
+.IX Xref "goto"
+.IX Subsection "Goto"
+Although not for the faint of heart, Perl does support a \f(CW\*(C`goto\*(C'\fR
+statement.  There are three forms: \f(CW\*(C`goto\*(C'\fR\-LABEL, \f(CW\*(C`goto\*(C'\fR\-EXPR, and
+\&\f(CW\*(C`goto\*(C'\fR\-&NAME.  A loop's LABEL is not actually a valid target for
+a \f(CW\*(C`goto\*(C'\fR; it's just the name of the loop.
+.PP
+The \f(CW\*(C`goto\*(C'\fR\-LABEL form finds the statement labeled with LABEL and resumes
+execution there.  It may not be used to go into any construct that
+requires initialization, such as a subroutine or a \f(CW\*(C`foreach\*(C'\fR loop.  It
+also can't be used to go into a construct that is optimized away.  It
+can be used to go almost anywhere else within the dynamic scope,
+including out of subroutines, but it's usually better to use some other
+construct such as \f(CW\*(C`last\*(C'\fR or \f(CW\*(C`die\*(C'\fR.  The author of Perl has never felt the
+need to use this form of \f(CW\*(C`goto\*(C'\fR (in Perl, that is\-\-C is another matter).
+.PP
+The \f(CW\*(C`goto\*(C'\fR\-EXPR form expects a label name, whose scope will be resolved
+dynamically.  This allows for computed \f(CW\*(C`goto\*(C'\fRs per FORTRAN, but isn't
+necessarily recommended if you're optimizing for maintainability:
+.PP
+.Vb 1
+\&    goto(("FOO", "BAR", "GLARCH")[$i]);
+.Ve
+.PP
+The \f(CW\*(C`goto\*(C'\fR\-&NAME form is highly magical, and substitutes a call to the
+named subroutine for the currently running subroutine.  This is used by
+\&\f(CWAUTOLOAD()\fR subroutines that wish to load another subroutine and then
+pretend that the other subroutine had been called in the first place
+(except that any modifications to \f(CW@_\fR in the current subroutine are
+propagated to the other subroutine.)  After the \f(CW\*(C`goto\*(C'\fR, not even \f(CWcaller()\fR
+will be able to tell that this routine was called first.
+.PP
+In almost all cases like this, it's usually a far, far better idea to use the
+structured control flow mechanisms of \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, or \f(CW\*(C`redo\*(C'\fR instead of
+resorting to a \f(CW\*(C`goto\*(C'\fR.  For certain applications, the catch and throw pair of
+\&\f(CW\*(C`eval{}\*(C'\fR and \fBdie()\fR for exception processing can also be a prudent approach.
+.SS "The Ellipsis Statement"
+.IX Xref "... ... statement ellipsis operator elliptical statement unimplemented statement unimplemented operator yada-yada yada-yada operator ... operator whatever operator triple-dot operator"
+.IX Subsection "The Ellipsis Statement"
+Beginning in Perl 5.12, Perl accepts an ellipsis, "\f(CW\*(C`...\*(C'\fR", as a
+placeholder for code that you haven't implemented yet.
+When Perl 5.12 or later encounters an ellipsis statement, it parses this
+without error, but if and when you should actually try to execute it, Perl
+throws an exception with the text \f(CW\*(C`Unimplemented\*(C'\fR:
+.PP
+.Vb 6
+\&    use v5.12;
+\&    sub unimplemented { ... }
+\&    eval { unimplemented() };
+\&    if ($@ =~ /^Unimplemented at /) {
+\&        say "I found an ellipsis!";
+\&    }
+.Ve
+.PP
+You can only use the elliptical statement to stand in for a complete
+statement.  Syntactically, "\f(CW\*(C`...;\*(C'\fR" is a complete statement, but,
+as with other kinds of semicolon-terminated statement, the semicolon
+may be omitted if "\f(CW\*(C`...\*(C'\fR" appears immediately before a closing brace.
+These examples show how the ellipsis works:
+.PP
+.Vb 10
+\&    use v5.12;
+\&    { ... }
+\&    sub foo { ... }
+\&    ...;
+\&    eval { ... };
+\&    sub somemeth {
+\&        my $self = shift;
+\&        ...;
+\&    }
+\&    $x = do {
+\&        my $n;
+\&        ...;
+\&        say "Hurrah!";
+\&        $n;
+\&    };
+.Ve
+.PP
+The elliptical statement cannot stand in for an expression that
+is part of a larger statement.
+These examples of attempts to use an ellipsis are syntax errors:
+.PP
+.Vb 1
+\&    use v5.12;
+\&
+\&    print ...;
+\&    open(my $fh, ">", "/dev/passwd") or ...;
+\&    if ($condition && ... ) { say "Howdy" };
+\&    ... if $a > $b;
+\&    say "Cromulent" if ...;
+\&    $flub = 5 + ...;
+.Ve
+.PP
+There are some cases where Perl can't immediately tell the difference
+between an expression and a statement.  For instance, the syntax for a
+block and an anonymous hash reference constructor look the same unless
+there's something in the braces to give Perl a hint.  The ellipsis is a
+syntax error if Perl doesn't guess that the \f(CW\*(C`{ ... }\*(C'\fR is a block.
+Inside your block, you can use a \f(CW\*(C`;\*(C'\fR before the ellipsis to denote that the
+\&\f(CW\*(C`{ ... }\*(C'\fR is a block and not a hash reference constructor.
+.PP
+Note: Some folks colloquially refer to this bit of punctuation as a
+"yada-yada" or "triple-dot", but its true name
+is actually an ellipsis.
+.SS "PODs: Embedded Documentation"
+.IX Xref "POD documentation"
+.IX Subsection "PODs: Embedded Documentation"
+Perl has a mechanism for intermixing documentation with source code.
+While it's expecting the beginning of a new statement, if the compiler
+encounters a line that begins with an equal sign and a word, like this
+.PP
+.Vb 1
+\&    =head1 Here There Be Pods!
+.Ve
+.PP
+Then that text and all remaining text up through and including a line
+beginning with \f(CW\*(C`=cut\*(C'\fR will be ignored.  The format of the intervening
+text is described in perlpod.
+.PP
+This allows you to intermix your source code
+and your documentation text freely, as in
+.PP
+.Vb 1
+\&    =item snazzle($)
+\&
+\&    The snazzle() function will behave in the most spectacular
+\&    form that you can possibly imagine, not even excepting
+\&    cybernetic pyrotechnics.
+\&
+\&    =cut back to the compiler, nuff of this pod stuff!
+\&
+\&    sub snazzle($) {
+\&        my $thingie = shift;
+\&        .........
+\&    }
+.Ve
+.PP
+Note that pod translators should look at only paragraphs beginning
+with a pod directive (it makes parsing easier), whereas the compiler
+actually knows to look for pod escapes even in the middle of a
+paragraph.  This means that the following secret stuff will be
+ignored by both the compiler and the translators.
+.PP
+.Vb 5
+\&    $a=3;
+\&    =secret stuff
+\&     warn "Neither POD nor CODE!?"
+\&    =cut back
+\&    print "got $a\en";
+.Ve
+.PP
+You probably shouldn't rely upon the \f(CWwarn()\fR being podded out forever.
+Not all pod translators are well-behaved in this regard, and perhaps
+the compiler will become pickier.
+.PP
+One may also use pod directives to quickly comment out a section
+of code.
+.SS "Plain Old Comments (Not!)"
+.IX Xref "comment line # preprocessor eval"
+.IX Subsection "Plain Old Comments (Not!)"
+Perl can process line directives, much like the C preprocessor.  Using
+this, one can control Perl's idea of filenames and line numbers in
+error or warning messages (especially for strings that are processed
+with \f(CWeval()\fR).  The syntax for this mechanism is almost the same as for
+most C preprocessors: it matches the regular expression
+.PP
+.Vb 5
+\&    # example: \*(Aq# line 42 "new_filename.plx"\*(Aq
+\&    /^\e#   \es*
+\&      line \es+ (\ed+)   \es*
+\&      (?:\es("?)([^"]+)\eg2)? \es*
+\&     $/x
+.Ve
+.PP
+with \f(CW$1\fR being the line number for the next line, and \f(CW$3\fR being
+the optional filename (specified with or without quotes).  Note that
+no whitespace may precede the \f(CW\*(C`#\*(C'\fR, unlike modern C preprocessors.
+.PP
+There is a fairly obvious gotcha included with the line directive:
+Debuggers and profilers will only show the last source line to appear
+at a particular line number in a given file.  Care should be taken not
+to cause line number collisions in code you'd like to debug later.
+.PP
+Here are some examples that you should be able to type into your command
+shell:
+.PP
+.Vb 6
+\&    % perl
+\&    # line 200 "bzzzt"
+\&    # the \*(Aq#\*(Aq on the previous line must be the first char on line
+\&    die \*(Aqfoo\*(Aq;
+\&    _\|_END_\|_
+\&    foo at bzzzt line 201.
+\&
+\&    % perl
+\&    # line 200 "bzzzt"
+\&    eval qq[\en#line 2001 ""\endie \*(Aqfoo\*(Aq]; print $@;
+\&    _\|_END_\|_
+\&    foo at \- line 2001.
+\&
+\&    % perl
+\&    eval qq[\en#line 200 "foo bar"\endie \*(Aqfoo\*(Aq]; print $@;
+\&    _\|_END_\|_
+\&    foo at foo bar line 200.
+\&
+\&    % perl
+\&    # line 345 "goop"
+\&    eval "\en#line " . _\|_LINE_\|_ . \*(Aq "\*(Aq . _\|_FILE_\|_ ."\e"\endie \*(Aqfoo\*(Aq";
+\&    print $@;
+\&    _\|_END_\|_
+\&    foo at goop line 345.
+.Ve
+.SS "Experimental Details on given and when"
+.IX Subsection "Experimental Details on given and when"
+As previously mentioned, the "switch" feature is considered highly
+experimental (it is also scheduled to be removed in perl 5.42.0);
+it is subject to change with little notice.  In particular,
+\&\f(CW\*(C`when\*(C'\fR has tricky behaviours that are expected to change to become less
+tricky in the future.  Do not rely upon its current (mis)implementation.
+Before Perl 5.18, \f(CW\*(C`given\*(C'\fR also had tricky behaviours that you should still
+beware of if your code must run on older versions of Perl.
+.PP
+Here is a longer example of \f(CW\*(C`given\*(C'\fR:
+.PP
+.Vb 10
+\&    use feature ":5.10";
+\&    given ($foo) {
+\&        when (undef) {
+\&            say \*(Aq$foo is undefined\*(Aq;
+\&        }
+\&        when ("foo") {
+\&            say \*(Aq$foo is the string "foo"\*(Aq;
+\&        }
+\&        when ([1,3,5,7,9]) {
+\&            say \*(Aq$foo is an odd digit\*(Aq;
+\&            continue; # Fall through
+\&        }
+\&        when ($_ < 100) {
+\&            say \*(Aq$foo is numerically less than 100\*(Aq;
+\&        }
+\&        when (\e&complicated_check) {
+\&            say \*(Aqa complicated check for $foo is true\*(Aq;
+\&        }
+\&        default {
+\&            die q(I don\*(Aqt know what to do with $foo);
+\&        }
+\&    }
+.Ve
+.PP
+Before Perl 5.18, \f(CWgiven(EXPR)\fR assigned the value of \fIEXPR\fR to
+merely a lexically scoped \fR\f(BIcopy\fR\fI\fR (!) of \f(CW$_\fR, not a dynamically
+scoped alias the way \f(CW\*(C`foreach\*(C'\fR does.  That made it similar to
+.PP
+.Vb 1
+\&        do { my $_ = EXPR; ... }
+.Ve
+.PP
+except that the block was automatically broken out of by a successful
+\&\f(CW\*(C`when\*(C'\fR or an explicit \f(CW\*(C`break\*(C'\fR.  Because it was only a copy, and because
+it was only lexically scoped, not dynamically scoped, you could not do the
+things with it that you are used to in a \f(CW\*(C`foreach\*(C'\fR loop.  In particular,
+it did not work for arbitrary function calls if those functions might try
+to access \f(CW$_\fR.  Best stick to \f(CW\*(C`foreach\*(C'\fR for that.
+.PP
+Most of the power comes from the implicit smartmatching that can
+sometimes apply.  Most of the time, \f(CWwhen(EXPR)\fR is treated as an
+implicit smartmatch of \f(CW$_\fR, that is, \f(CW\*(C`$_ ~~ EXPR\*(C'\fR.  (See
+"Smartmatch Operator" in perlop for more information on smartmatching.)
+But when \fIEXPR\fR is one of the 10 exceptional cases (or things like them)
+listed below, it is used directly as a boolean.
+.IP 1. 4
+.IX Item "1."
+A user-defined subroutine call or a method invocation.
+.IP 2. 4
+.IX Item "2."
+A regular expression match in the form of \f(CW\*(C`/REGEX/\*(C'\fR, \f(CW\*(C`$foo =~ /REGEX/\*(C'\fR,
+or \f(CW\*(C`$foo =~ EXPR\*(C'\fR.  Also, a negated regular expression match in
+the form \f(CW\*(C`!/REGEX/\*(C'\fR, \f(CW\*(C`$foo !~ /REGEX/\*(C'\fR, or \f(CW\*(C`$foo !~ EXPR\*(C'\fR.
+.IP 3. 4
+.IX Item "3."
+A smart match that uses an explicit \f(CW\*(C`~~\*(C'\fR operator, such as \f(CW\*(C`EXPR ~~ EXPR\*(C'\fR.
+.Sp
+\&\fBNOTE:\fR You will often have to use \f(CW\*(C`$c ~~ $_\*(C'\fR because the default case
+uses \f(CW\*(C`$_ ~~ $c\*(C'\fR , which is frequently the opposite of what you want.
+.IP 4. 4
+.IX Item "4."
+A boolean comparison operator such as \f(CW\*(C`$_ < 10\*(C'\fR or \f(CW\*(C`$x eq "abc"\*(C'\fR.  The
+relational operators that this applies to are the six numeric comparisons
+(\f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`<=\*(C'\fR, \f(CW\*(C`>=\*(C'\fR, \f(CW\*(C`==\*(C'\fR, and \f(CW\*(C`!=\*(C'\fR), and
+the six string comparisons (\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, \f(CW\*(C`le\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, \f(CW\*(C`eq\*(C'\fR, and \f(CW\*(C`ne\*(C'\fR).
+.IP 5. 4
+.IX Item "5."
+At least the three builtin functions \f(CWdefined(...)\fR, \f(CWexists(...)\fR, and
+\&\f(CWeof(...)\fR.  We might someday add more of these later if we think of them.
+.IP 6. 4
+.IX Item "6."
+A negated expression, whether \f(CW\*(C`!(EXPR)\*(C'\fR or \f(CWnot(EXPR)\fR, or a logical
+exclusive-or, \f(CW\*(C`(EXPR1) xor (EXPR2)\*(C'\fR.  The bitwise versions (\f(CW\*(C`~\*(C'\fR and \f(CW\*(C`^\*(C'\fR)
+are not included.
+.IP 7. 4
+.IX Item "7."
+A filetest operator, with exactly 4 exceptions: \f(CW\*(C`\-s\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, \f(CW\*(C`\-A\*(C'\fR, and
+\&\f(CW\*(C`\-C\*(C'\fR, as these return numerical values, not boolean ones.  The \f(CW\*(C`\-z\*(C'\fR
+filetest operator is not included in the exception list.
+.IP 8. 4
+.IX Item "8."
+The \f(CW\*(C`..\*(C'\fR and \f(CW\*(C`...\*(C'\fR flip-flop operators.  Note that the \f(CW\*(C`...\*(C'\fR flip-flop
+operator is completely different from the \f(CW\*(C`...\*(C'\fR elliptical statement
+just described.
+.PP
+In those 8 cases above, the value of EXPR is used directly as a boolean, so
+no smartmatching is done.  You may think of \f(CW\*(C`when\*(C'\fR as a smartsmartmatch.
+.PP
+Furthermore, Perl inspects the operands of logical operators to
+decide whether to use smartmatching for each one by applying the
+above test to the operands:
+.IP 9. 4
+.IX Item "9."
+If EXPR is \f(CW\*(C`EXPR1 && EXPR2\*(C'\fR or \f(CW\*(C`EXPR1 and EXPR2\*(C'\fR, the test is applied
+\&\fIrecursively\fR to both EXPR1 and EXPR2.
+Only if \fIboth\fR operands also pass the
+test, \fIrecursively\fR, will the expression be treated as boolean.  Otherwise,
+smartmatching is used.
+.IP 10. 4
+.IX Item "10."
+If EXPR is \f(CW\*(C`EXPR1 || EXPR2\*(C'\fR, \f(CW\*(C`EXPR1 // EXPR2\*(C'\fR, or \f(CW\*(C`EXPR1 or EXPR2\*(C'\fR, the
+test is applied \fIrecursively\fR to EXPR1 only (which might itself be a
+higher-precedence AND operator, for example, and thus subject to the
+previous rule), not to EXPR2.  If EXPR1 is to use smartmatching, then EXPR2
+also does so, no matter what EXPR2 contains.  But if EXPR2 does not get to
+use smartmatching, then the second argument will not be either.  This is
+quite different from the \f(CW\*(C`&&\*(C'\fR case just described, so be careful.
+.PP
+These rules are complicated, but the goal is for them to do what you want
+(even if you don't quite understand why they are doing it).  For example:
+.PP
+.Vb 1
+\&    when (/^\ed+$/ && $_ < 75) { ... }
+.Ve
+.PP
+will be treated as a boolean match because the rules say both
+a regex match and an explicit test on \f(CW$_\fR will be treated
+as boolean.
+.PP
+Also:
+.PP
+.Vb 1
+\&    when ([qw(foo bar)] && /baz/) { ... }
+.Ve
+.PP
+will use smartmatching because only \fIone\fR of the operands is a boolean:
+the other uses smartmatching, and that wins.
+.PP
+Further:
+.PP
+.Vb 1
+\&    when ([qw(foo bar)] || /^baz/) { ... }
+.Ve
+.PP
+will use smart matching (only the first operand is considered), whereas
+.PP
+.Vb 1
+\&    when (/^baz/ || [qw(foo bar)]) { ... }
+.Ve
+.PP
+will test only the regex, which causes both operands to be
+treated as boolean.  Watch out for this one, then, because an
+arrayref is always a true value, which makes it effectively
+redundant.  Not a good idea.
+.PP
+Tautologous boolean operators are still going to be optimized
+away.  Don't be tempted to write
+.PP
+.Vb 1
+\&    when ("foo" or "bar") { ... }
+.Ve
+.PP
+This will optimize down to \f(CW"foo"\fR, so \f(CW"bar"\fR will never be considered (even
+though the rules say to use a smartmatch
+on \f(CW"foo"\fR).  For an alternation like
+this, an array ref will work, because this will instigate smartmatching:
+.PP
+.Vb 1
+\&    when ([qw(foo bar)] { ... }
+.Ve
+.PP
+This is somewhat equivalent to the C\-style switch statement's fallthrough
+functionality (not to be confused with \fIPerl's\fR fallthrough
+functionality\-\-see below), wherein the same block is used for several
+\&\f(CW\*(C`case\*(C'\fR statements.
+.PP
+Another useful shortcut is that, if you use a literal array or hash as the
+argument to \f(CW\*(C`given\*(C'\fR, it is turned into a reference.  So \f(CWgiven(@foo)\fR is
+the same as \f(CWgiven(\e@foo)\fR, for example.
+.PP
+\&\f(CW\*(C`default\*(C'\fR behaves exactly like \f(CW\*(C`when(1 == 1)\*(C'\fR, which is
+to say that it always matches.
+.PP
+\fIBreaking out\fR
+.IX Subsection "Breaking out"
+.PP
+You can use the \f(CW\*(C`break\*(C'\fR keyword to break out of the enclosing
+\&\f(CW\*(C`given\*(C'\fR block.  Every \f(CW\*(C`when\*(C'\fR block is implicitly ended with
+a \f(CW\*(C`break\*(C'\fR.
+.PP
+\fIFall-through\fR
+.IX Subsection "Fall-through"
+.PP
+You can use the \f(CW\*(C`continue\*(C'\fR keyword to fall through from one
+case to the next immediate \f(CW\*(C`when\*(C'\fR or \f(CW\*(C`default\*(C'\fR:
+.PP
+.Vb 5
+\&    given($foo) {
+\&        when (/x/) { say \*(Aq$foo contains an x\*(Aq; continue }
+\&        when (/y/) { say \*(Aq$foo contains a y\*(Aq            }
+\&        default    { say \*(Aq$foo does not contain a y\*(Aq    }
+\&    }
+.Ve
+.PP
+\fIReturn value\fR
+.IX Subsection "Return value"
+.PP
+When a \f(CW\*(C`given\*(C'\fR statement is also a valid expression (for example,
+when it's the last statement of a block), it evaluates to:
+.IP \(bu 4
+An empty list as soon as an explicit \f(CW\*(C`break\*(C'\fR is encountered.
+.IP \(bu 4
+The value of the last evaluated expression of the successful
+\&\f(CW\*(C`when\*(C'\fR/\f(CW\*(C`default\*(C'\fR clause, if there happens to be one.
+.IP \(bu 4
+The value of the last evaluated expression of the \f(CW\*(C`given\*(C'\fR block if no
+condition is true.
+.PP
+In both last cases, the last expression is evaluated in the context that
+was applied to the \f(CW\*(C`given\*(C'\fR block.
+.PP
+Note that, unlike \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR, failed \f(CW\*(C`when\*(C'\fR statements always
+evaluate to an empty list.
+.PP
+.Vb 8
+\&    my $price = do {
+\&        given ($item) {
+\&            when (["pear", "apple"]) { 1 }
+\&            break when "vote";      # My vote cannot be bought
+\&            1e10  when /Mona Lisa/;
+\&            "unknown";
+\&        }
+\&    };
+.Ve
+.PP
+Currently, \f(CW\*(C`given\*(C'\fR blocks can't always
+be used as proper expressions.  This
+may be addressed in a future version of Perl.
+.PP
+\fISwitching in a loop\fR
+.IX Subsection "Switching in a loop"
+.PP
+Instead of using \f(CWgiven()\fR, you can use a \f(CWforeach()\fR loop.
+For example, here's one way to count how many times a particular
+string occurs in an array:
+.PP
+.Vb 6
+\&    use v5.10.1;
+\&    my $count = 0;
+\&    for (@array) {
+\&        when ("foo") { ++$count }
+\&    }
+\&    print "\e@array contains $count copies of \*(Aqfoo\*(Aq\en";
+.Ve
+.PP
+Or in a more recent version:
+.PP
+.Vb 6
+\&    use v5.14;
+\&    my $count = 0;
+\&    for (@array) {
+\&        ++$count when "foo";
+\&    }
+\&    print "\e@array contains $count copies of \*(Aqfoo\*(Aq\en";
+.Ve
+.PP
+At the end of all \f(CW\*(C`when\*(C'\fR blocks, there is an implicit \f(CW\*(C`next\*(C'\fR.
+You can override that with an explicit \f(CW\*(C`last\*(C'\fR if you're
+interested in only the first match alone.
+.PP
+This doesn't work if you explicitly specify a loop variable, as
+in \f(CW\*(C`for $item (@array)\*(C'\fR.  You have to use the default variable \f(CW$_\fR.
+.PP
+\fIDifferences from Raku\fR
+.IX Subsection "Differences from Raku"
+.PP
+The Perl 5 smartmatch and \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR constructs are not compatible
+with their Raku analogues.  The most visible difference and least
+important difference is that, in Perl 5, parentheses are required around
+the argument to \f(CWgiven()\fR and \f(CWwhen()\fR (except when this last one is used
+as a statement modifier).  Parentheses in Raku are always optional in a
+control construct such as \f(CWif()\fR, \f(CWwhile()\fR, or \f(CWwhen()\fR; they can't be
+made optional in Perl 5 without a great deal of potential confusion,
+because Perl 5 would parse the expression
+.PP
+.Vb 3
+\&    given $foo {
+\&        ...
+\&    }
+.Ve
+.PP
+as though the argument to \f(CW\*(C`given\*(C'\fR were an element of the hash
+\&\f(CW%foo\fR, interpreting the braces as hash-element syntax.
+.PP
+However, their are many, many other differences.  For example,
+this works in Perl 5:
+.PP
+.Vb 2
+\&    use v5.12;
+\&    my @primary = ("red", "blue", "green");
+\&
+\&    if (@primary ~~ "red") {
+\&        say "primary smartmatches red";
+\&    }
+\&
+\&    if ("red" ~~ @primary) {
+\&        say "red smartmatches primary";
+\&    }
+\&
+\&    say "that\*(Aqs all, folks!";
+.Ve
+.PP
+But it doesn't work at all in Raku.  Instead, you should
+use the (parallelizable) \f(CW\*(C`any\*(C'\fR operator:
+.PP
+.Vb 3
+\&   if any(@primary) eq "red" {
+\&       say "primary smartmatches red";
+\&   }
+\&
+\&   if "red" eq any(@primary) {
+\&       say "red smartmatches primary";
+\&   }
+.Ve
+.PP
+The table of smartmatches in "Smartmatch Operator" in perlop is not
+identical to that proposed by the Raku specification, mainly due to
+differences between Raku's and Perl 5's data models, but also because
+the Raku spec has changed since Perl 5 rushed into early adoption.
+.PP
+In Raku, \f(CWwhen()\fR will always do an implicit smartmatch with its
+argument, while in Perl 5 it is convenient (albeit potentially confusing) to
+suppress this implicit smartmatch in various rather loosely-defined
+situations, as roughly outlined above.  (The difference is largely because
+Perl 5 does not have, even internally, a boolean type.)
diff --git a/upstream/mageia-cauldron/man1/perlsynology.1 b/upstream/mageia-cauldron/man1/perlsynology.1
new file mode 100644
index 00000000..dad0067b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlsynology.1
@@ -0,0 +1,373 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSYNOLOGY 1"
+.TH PERLSYNOLOGY 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlsynology \- Perl 5 on Synology DSM systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Synology manufactures a vast number of Network Attached Storage (NAS)
+devices that are very popular in large organisations as well as small
+businesses and homes.
+.PP
+The NAS systems are equipped with Synology Disk Storage Manager (DSM),
+which is a trimmed-down Linux system enhanced with several tools for
+managing the NAS. There are several flavours of hardware: Marvell
+Armada (ARMv5tel, ARMv7l), Intel Atom (i686, x86_64), Freescale QorIQ
+(PPC), and more. For a full list see the
+Synology FAQ <https://kb.synology.com/en-global/DSM/tutorial/What_kind_of_CPU_does_my_NAS_have>.
+.PP
+Since it is based on Linux, the NAS can run many popular Linux
+software packages, including Perl. In fact, Synology provides a
+ready-to-install package for Perl, depending on the version of DSM
+the installed perl ranges from 5.8.6 on DSM\-4.3 to 5.28.1 on DSM\-7.1.
+.PP
+There is an active user community that provides many software packages
+for the Synology DSM systems; at the time of writing this document
+they provide Perl version 5.28.1.
+.PP
+This document describes various features of Synology DSM operating
+system that will affect how Perl 5 (hereafter just Perl) is
+configured, compiled and/or runs. It has been compiled and verified by
+Johan Vromans for the Synology DS413 (QorIQ), with feedback from
+H.Merijn Brand (DS213: ARMv5tel, RS815: Intel Atom x64, and DS218+:
+Celeron J3355).
+.SS "Setting up the build environment"
+.IX Subsection "Setting up the build environment"
+\fIDSM 7\fR
+.IX Subsection "DSM 7"
+.PP
+For a comfortable development environment, Entware is currently the only
+viable solution. Just follow the detailed instructions on
+Install Entware on Synology NAS <https://github.com/Entware/Entware/wiki/Install-on-Synology-NAS>.
+supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64.
+Check here <https://pkg.entware.net/binaries/> for supported platforms.
+.PP
+That github link also shows what environments should be supported.
+.PP
+It was tested on DSM\-7.1 by H.Merijn Brand on a DS218+ and a DS220+ (both
+Intel x64).
+.PP
+Entware comes with a precompiled 5.26.1 (Jan 2018) that allowes
+building shared XS code. Note that this installation does \fBnot\fR use
+a site_perl folder. The available \f(CW\*(C`cpan\*(C'\fR works. If all required
+development packages are installed too, also for XS.
+.PP
+Installing perl from the Community package center:
+.IP \(bu 4
+Using your favourite browser open the DSM management page and start
+the Package Center.
+.IP \(bu 4
+In Settings, add the following Package Sources:
+.Sp
+.Vb 2
+\&  Name:     Community
+\&  Location: https://synopackage.com/repository/spk/All
+.Ve
+.IP \(bu 4
+Still in Settings, in Channel Update, select Beta Channel.
+.PP
+To complete the development environment, install make and gcc
+.PP
+.Vb 1
+\& ds220# opkg install make gcc
+.Ve
+.PP
+Then, optionally, make sure you use the more recent bash and gawk.
+.PP
+.Vb 4
+\& ds220# opkg install bash gawk
+\& ds220# cd /usr/bin
+\& ds220# mv bash bash.syno
+\& ds220# ln \-s /opt/bin/bash .
+.Ve
+.PP
+In order to have Configure find the required libraries
+.PP
+.Vb 8
+\& ds220# cd /opt/lib
+\& ds220# ln \-s libcrypt.so.?       libcrypt.so
+\& ds220# ln \-s libdl.so.?          libdl.so
+\& ds220# ln \-s libgdbm.so.?        libgdbm.so
+\& ds220# ln \-s libgdbm_compat.so.? libgdbm_compat.so
+\& ds220# ln \-s libm.so.?           libm.so
+\& ds220# ln \-s libpthread.so.?     libpthread.so
+\& ds220# ln \-s libutil.so.?        libutil.so
+.Ve
+.PP
+\fIDSM 6\fR
+.IX Subsection "DSM 6"
+.PP
+Using iPkg has been deprecated on DSM 6, but an alternative is available
+for DSM 6: entware/opkg. For instructions on how to use that, please read
+Install Entware-ng on Synology NAS <https://github.com/Entware-ng/Entware-ng/wiki/Install-on-Synology-NAS>
+.PP
+That sadly does not (yet) work on QorIQ. At the moment of writing, the
+supported architectures are armv5, armv7, mipsel, wl500g, x86_32, and x86_64.
+Check here <https://pkg.entware.net/binaries/> for supported platforms.
+.PP
+Entware-ng comes with a precompiled 5.24.1 (June 2017) that allowes
+building shared XS code. Note that this installation does \fBnot\fR use
+a site_perl folder. The available \f(CW\*(C`cpan\*(C'\fR works. If all required
+development packages are installed too, also for XS.
+.PP
+\fIDSM 5\fR
+.IX Subsection "DSM 5"
+.PP
+As DSM is a trimmed-down Linux system, it lacks many of the tools and
+libraries commonly found on Linux. The basic tools like sh, cp, rm,
+etc. are implemented using
+BusyBox <https://en.wikipedia.org/wiki/BusyBox>.
+.IP \(bu 4
+Using your favourite browser open the DSM management page and start
+the Package Center.
+.IP \(bu 4
+If you want to smoke test Perl, install \f(CW\*(C`Perl\*(C'\fR.
+.IP \(bu 4
+In Settings, add the following Package Sources:
+.Sp
+.Vb 2
+\&  https://www.cphub.net
+\&  http://packages.quadrat4.de
+.Ve
+.Sp
+As these two are both discontinued, it is unlikely you will be able
+to set up a build environment on DSM 5.
+.IP \(bu 4
+Still in Settings, in Channel Update, select Beta Channel.
+.IP \(bu 4
+Press Refresh. In the left panel the item "Community" will appear.
+Click it. Select "Bootstrap Installer Beta" and install it.
+.IP \(bu 4
+Likewise, install "iPKGui Beta".
+.Sp
+The application window should now show an icon for iPKGui.
+.IP \(bu 4
+Start iPKGui. Install the packages \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`gcc\*(C'\fR and \f(CW\*(C`coreutils\*(C'\fR.
+.Sp
+If you want to smoke test Perl, install \f(CW\*(C`patch\*(C'\fR.
+.PP
+The next step is to add some symlinks to system libraries. For
+example, the development software expect a library \f(CW\*(C`libm.so\*(C'\fR that
+normally is a symlink to \f(CW\*(C`libm.so.6\*(C'\fR. Synology only provides the
+latter and not the symlink.
+.PP
+Here the actual architecture of the Synology system matters. You have
+to find out where the gcc libraries have been installed. Look in /opt
+for a directory similar to arm-none-linux-gnueab or
+powerpc-linux-gnuspe. In the instructions below I'll use
+powerpc-linux-gnuspe as an example.
+.IP \(bu 4
+On the DSM management page start the Control Panel.
+.IP \(bu 4
+Click Terminal, and enable SSH service.
+.IP \(bu 4
+Close Terminal and the Control Panel.
+.IP \(bu 4
+Open a shell on the Synology using ssh and become root.
+.IP \(bu 4
+Execute the following commands:
+.Sp
+.Vb 7
+\&  cd /lib
+\&  ln \-s libm.so.6 libm.so
+\&  ln \-s libcrypt.so.1 libcrypt.so
+\&  ln \-s libdl.so.2 libdl.so
+\&  cd /opt/powerpc\-linux\-gnuspe/lib  (or
+\&                                    /opt/arm\-none\-linux\-gnueabi/lib)
+\&  ln \-s /lib/libdl.so.2 libdl.so
+.Ve
+.PP
+\&\fBWARNING:\fR When you perform a system software upgrade, these links
+will disappear and need to be re-established.
+.SS "Compiling Perl 5"
+.IX Subsection "Compiling Perl 5"
+When the build environment has been set up, building and testing Perl
+is straightforward. The only thing you need to do is download the
+sources as usual, and add a file Policy.sh as follows:
+.PP
+.Vb 2
+\&  # Administrivia.
+\&  perladmin="your.email@goes.here"
+\&
+\&  # Install Perl in a tree in /opt/perl instead of /opt/bin.
+\&  prefix=/opt/perl
+\&
+\&  # Select the compiler. Note that there is no \*(Aqcc\*(Aq alias or link
+\&  # on older DSM versions
+\&  cc=gcc
+\&  awk=/opt/bin/gawk
+\&
+\&  # Build flags. Optional
+\&  ccflags="\-DDEBUGGING"
+\&
+\&  # Library and include paths.
+\&  locincpth="/opt/include"
+\&  loclibpth="/opt/lib /usr/local/lib /usr/lib"
+\&  libpth="/opt/lib /usr/local/lib /usr/lib"
+.Ve
+.PP
+You may want to create the destination directory and give it the right
+permissions before installing, thus eliminating the need to build Perl
+as a super user.
+.PP
+In the directory where you unpacked the sources, issue the familiar
+commands:
+.PP
+.Vb 4
+\&  $ bash ./Configure \-Dusedevel \-Duseshrplib \-Duse64bitall \-des
+\&  $ make \-j2
+\&  $ env TEST_JOBS=2 make test_harness
+\&  $ make install
+.Ve
+.SS "Known problems"
+.IX Subsection "Known problems"
+\fIConfigure\fR
+.IX Subsection "Configure"
+.PP
+The GNU C\-compiler might spit out unexpected stuff under \-v, which
+causes the analysis of cppsymbols to fail because of unmatched quotes.
+.PP
+You'll note if config.sh fails with a syntax error.
+.PP
+\fIBuild\fR
+.IX Subsection "Build"
+.IP "Error message ""No error definitions found""." 4
+.IX Item "Error message ""No error definitions found""."
+This error is generated when it is not possible to find the local
+definitions for error codes, due to the uncommon structure of the
+Synology file system.
+.Sp
+This error was fixed in the Perl development git for version 5.19,
+commit 7a8f1212e5482613c8a5b0402528e3105b26ff24.
+.PP
+\fIFailing tests\fR
+.IX Subsection "Failing tests"
+.IP \fIext/DynaLoader/t/DynaLoader.t\fR 4
+.IX Item "ext/DynaLoader/t/DynaLoader.t"
+One subtest fails due to the uncommon structure of the Synology file
+system. The file \fI/lib/glibc.so\fR is missing.
+.Sp
+\&\fBWARNING:\fR Do not symlink \fI/lib/glibc.so.6\fR to \fI/lib/glibc.so\fR or
+some system components will start to fail.
+.SS "Smoke testing Perl"
+.IX Subsection "Smoke testing Perl"
+If building completes successfully, you can set up smoke testing as
+described in the Test::Smoke documentation.
+.PP
+For smoke testing you need a running Perl. You can either install the
+Synology supplied package for Perl 5.8.6, or build and install your
+own, much more recent version.
+.PP
+Note that I could not run successful smokes when initiated by the
+Synology Task Scheduler. I resorted to initiating the smokes via a
+cron job run on another system, using ssh:
+.PP
+.Vb 1
+\&  ssh nas1 wrk/Test\-Smoke/smoke/smokecurrent.sh
+.Ve
+.PP
+\fILocal patches\fR
+.IX Subsection "Local patches"
+.PP
+When local patches are applied with smoke testing, the test driver
+will automatically request regeneration of certain tables after the
+patches are applied. The Synology supplied Perl 5.8.6 (at least on the
+DS413) \fBis NOT capable\fR of generating these tables. It will generate
+opcodes with bogus values, causing the build to fail.
+.PP
+You can prevent regeneration by adding the setting
+.PP
+.Vb 1
+\&  \*(Aqflags\*(Aq => 0,
+.Ve
+.PP
+to the smoke config, or by adding another patch that inserts
+.PP
+.Vb 1
+\&  exit 0 if $] == 5.008006;
+.Ve
+.PP
+in the beginning of the \f(CW\*(C`regen.pl\*(C'\fR program.
+.SS "Adding libraries"
+.IX Subsection "Adding libraries"
+The above procedure describes a basic environment and hence results in
+a basic Perl. If you want to add additional libraries to Perl, you may
+need some extra settings.
+.PP
+For example, the basic Perl does not have any of the DB libraries (db,
+dbm, ndbm, gdsm). You can add these using iPKGui, however, you need to
+set environment variable LD_LIBRARY_PATH to the appropriate value:
+.PP
+.Vb 2
+\&  LD_LIBRARY_PATH=/lib:/opt/lib
+\&  export LD_LIBRARY_PATH
+.Ve
+.PP
+This setting needs to be in effect while Perl is built, but also when
+the programs are run.
+.SH REVISION
+.IX Header "REVISION"
+July 2022, for DSM 5.1.5022 and DSM 6.1\-15101\-4, and DSM\-7.1\-42661\-3.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Johan Vromans <jvromans@squirrel.nl>
+H. Merijn Brand <cpan@tux.freedom.nl>
diff --git a/upstream/mageia-cauldron/man1/perlthanks.1 b/upstream/mageia-cauldron/man1/perlthanks.1
new file mode 100644
index 00000000..2999f89a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlthanks.1
@@ -0,0 +1,331 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLBUG 1"
+.TH PERLBUG 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlbug \- how to submit bug reports on Perl
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBperlbug\fR
+.PP
+\&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-a\fR\ \fIaddress\fR\ ] [\ \fB\-s\fR\ \fIsubject\fR\ ]
+[\ \fB\-b\fR\ \fIbody\fR\ |\ \fB\-f\fR\ \fIinputfile\fR\ ] [\ \fB\-F\fR\ \fIoutputfile\fR\ ]
+[\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
+[\ \fB\-e\fR\ \fIeditor\fR\ ] [\ \fB\-c\fR\ \fIadminaddress\fR\ |\ \fB\-C\fR\ ]
+[\ \fB\-S\fR\ ] [\ \fB\-t\fR\ ]  [\ \fB\-d\fR\ ]  [\ \fB\-h\fR\ ] [\ \fB\-T\fR\ ]
+.PP
+\&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
+ [\ \fB\-ok\fR\ |\ \fB\-okay\fR\ |\ \fB\-nok\fR\ |\ \fB\-nokay\fR\ ]
+.PP
+\&\fBperlthanks\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This program is designed to help you generate bug reports
+(and thank-you notes) about perl5 and the modules which ship with it.
+.PP
+In most cases, you can just run it interactively from a command
+line without any special arguments and follow the prompts.
+.PP
+If you have found a bug with a non-standard port (one that was not
+part of the \fIstandard distribution\fR), a binary distribution, or a
+non-core module (such as Tk, DBI, etc), then please see the
+documentation that came with that distribution to determine the
+correct place to report bugs.
+.PP
+Bug reports should be submitted to the GitHub issue tracker at
+<https://github.com/Perl/perl5/issues>. The \fBperlbug@perl.org\fR
+address no longer automatically opens tickets. You can use this tool
+to compose your report and save it to a file which you can then submit
+to the issue tracker.
+.PP
+In extreme cases, \fBperlbug\fR may not work well enough on your system
+to guide you through composing a bug report. In those cases, you
+may be able to use \fBperlbug \-d\fR or \fBperl \-V\fR to get system
+configuration information to include in your issue report.
+.PP
+When reporting a bug, please run through this checklist:
+.IP "What version of Perl you are running?" 4
+.IX Item "What version of Perl you are running?"
+Type \f(CW\*(C`perl \-v\*(C'\fR at the command line to find out.
+.IP "Are you running the latest released version of perl?" 4
+.IX Item "Are you running the latest released version of perl?"
+Look at <http://www.perl.org/> to find out.  If you are not using the
+latest released version, please try to replicate your bug on the
+latest stable release.
+.Sp
+Note that reports about bugs in old versions of Perl, especially
+those which indicate you haven't also tested the current stable
+release of Perl, are likely to receive less attention from the
+volunteers who build and maintain Perl than reports about bugs in
+the current release.
+.IP "Are you sure what you have is a bug?" 4
+.IX Item "Are you sure what you have is a bug?"
+A significant number of the bug reports we get turn out to be
+documented features in Perl.  Make sure the issue you've run into
+isn't intentional by glancing through the documentation that comes
+with the Perl distribution.
+.Sp
+Given the sheer volume of Perl documentation, this isn't a trivial
+undertaking, but if you can point to documentation that suggests
+the behaviour you're seeing is \fIwrong\fR, your issue is likely to
+receive more attention. You may want to start with \fBperldoc\fR
+perltrap for pointers to common traps that new (and experienced)
+Perl programmers run into.
+.Sp
+If you're unsure of the meaning of an error message you've run
+across, \fBperldoc\fR perldiag for an explanation.  If the message
+isn't in perldiag, it probably isn't generated by Perl.  You may
+have luck consulting your operating system documentation instead.
+.Sp
+If you are on a non-UNIX platform \fBperldoc\fR perlport, as some
+features may be unimplemented or work differently.
+.Sp
+You may be able to figure out what's going wrong using the Perl
+debugger.  For information about how to use the debugger \fBperldoc\fR
+perldebug.
+.IP "Do you have a proper test case?" 4
+.IX Item "Do you have a proper test case?"
+The easier it is to reproduce your bug, the more likely it will be
+fixed \-\- if nobody can duplicate your problem, it probably won't be 
+addressed.
+.Sp
+A good test case has most of these attributes: short, simple code;
+few dependencies on external commands, modules, or libraries; no
+platform-dependent code (unless it's a platform-specific bug);
+clear, simple documentation.
+.Sp
+A good test case is almost always a good candidate to be included in
+Perl's test suite.  If you have the time, consider writing your test case so
+that it can be easily included into the standard test suite.
+.IP "Have you included all relevant information?" 4
+.IX Item "Have you included all relevant information?"
+Be sure to include the \fBexact\fR error messages, if any.
+"Perl gave an error" is not an exact error message.
+.Sp
+If you get a core dump (or equivalent), you may use a debugger
+(\fBdbx\fR, \fBgdb\fR, etc) to produce a stack trace to include in the bug
+report.
+.Sp
+NOTE: unless your Perl has been compiled with debug info
+(often \fB\-g\fR), the stack trace is likely to be somewhat hard to use
+because it will most probably contain only the function names and not
+their arguments.  If possible, recompile your Perl with debug info and
+reproduce the crash and the stack trace.
+.IP "Can you describe the bug in plain English?" 4
+.IX Item "Can you describe the bug in plain English?"
+The easier it is to understand a reproducible bug, the more likely
+it will be fixed.  Any insight you can provide into the problem
+will help a great deal.  In other words, try to analyze the problem
+(to the extent you can) and report your discoveries.
+.IP "Can you fix the bug yourself?" 4
+.IX Item "Can you fix the bug yourself?"
+If so, that's great news; bug reports with patches are likely to
+receive significantly more attention and interest than those without
+patches.  Please submit your patch via the GitHub Pull Request workflow
+as described in \fBperldoc\fR perlhack.  You may also send patches to
+\&\fBperl5\-porters@perl.org\fR.  When sending a patch, create it using
+\&\f(CW\*(C`git format\-patch\*(C'\fR if possible, though a unified diff created with
+\&\f(CW\*(C`diff \-pu\*(C'\fR will do nearly as well.
+.Sp
+Your patch may be returned with requests for changes, or requests for more
+detailed explanations about your fix.
+.Sp
+Here are a few hints for creating high-quality patches:
+.Sp
+Make sure the patch is not reversed (the first argument to diff is
+typically the original file, the second argument your changed file).
+Make sure you test your patch by applying it with \f(CW\*(C`git am\*(C'\fR or the
+\&\f(CW\*(C`patch\*(C'\fR program before you send it on its way.  Try to follow the
+same style as the code you are trying to patch.  Make sure your patch
+really does work (\f(CW\*(C`make test\*(C'\fR, if the thing you're patching is covered
+by Perl's test suite).
+.ie n .IP "Can you use ""perlbug"" to submit a thank-you note?" 4
+.el .IP "Can you use \f(CWperlbug\fR to submit a thank-you note?" 4
+.IX Item "Can you use perlbug to submit a thank-you note?"
+Yes, you can do this by either using the \f(CW\*(C`\-T\*(C'\fR option, or by invoking
+the program as \f(CW\*(C`perlthanks\*(C'\fR. Thank-you notes are good. It makes people
+smile.
+.PP
+Please make your issue title informative.  "a bug" is not informative.
+Neither is "perl crashes" nor is "HELP!!!".  These don't help.  A compact
+description of what's wrong is fine.
+.PP
+Having done your bit, please be prepared to wait, to be told the
+bug is in your code, or possibly to get no reply at all.  The
+volunteers who maintain Perl are busy folks, so if your problem is
+an obvious bug in your own code, is difficult to understand or is
+a duplicate of an existing report, you may not receive a personal
+reply.
+.PP
+If it is important to you that your bug be fixed, do monitor the
+issue tracker (you will be subscribed to notifications for issues you
+submit or comment on) and the commit logs to development
+versions of Perl, and encourage the maintainers with kind words or
+offers of frosty beverages.  (Please do be kind to the maintainers.
+Harassing or flaming them is likely to have the opposite effect of the
+one you want.)
+.PP
+Feel free to update the ticket about your bug on
+<https://github.com/Perl/perl5/issues>
+if a new version of Perl is released and your bug is still present.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \fB\-a\fR 8
+.IX Item "-a"
+Address to send the report to instead of saving to a file.
+.IP \fB\-b\fR 8
+.IX Item "-b"
+Body of the report.  If not included on the command line, or
+in a file with \fB\-f\fR, you will get a chance to edit the report.
+.IP \fB\-C\fR 8
+.IX Item "-C"
+Don't send copy to administrator when sending report by mail.
+.IP \fB\-c\fR 8
+.IX Item "-c"
+Address to send copy of report to when sending report by mail.
+Defaults to the address of the
+local perl administrator (recorded when perl was built).
+.IP \fB\-d\fR 8
+.IX Item "-d"
+Data mode (the default if you redirect or pipe output).  This prints out
+your configuration data, without saving or mailing anything.  You can use
+this with \fB\-v\fR to get more complete data.
+.IP \fB\-e\fR 8
+.IX Item "-e"
+Editor to use.
+.IP \fB\-f\fR 8
+.IX Item "-f"
+File containing the body of the report.  Use this to quickly send a
+prepared report.
+.IP \fB\-F\fR 8
+.IX Item "-F"
+File to output the results to.  Defaults to \fBperlbug.rep\fR.
+.IP \fB\-h\fR 8
+.IX Item "-h"
+Prints a brief summary of the options.
+.IP \fB\-ok\fR 8
+.IX Item "-ok"
+Report successful build on this system to perl porters. Forces \fB\-S\fR
+and \fB\-C\fR. Forces and supplies values for \fB\-s\fR and \fB\-b\fR. Only
+prompts for a return address if it cannot guess it (for use with
+\&\fBmake\fR). Honors return address specified with \fB\-r\fR.  You can use this
+with \fB\-v\fR to get more complete data.   Only makes a report if this
+system is less than 60 days old.
+.IP \fB\-okay\fR 8
+.IX Item "-okay"
+As \fB\-ok\fR except it will report on older systems.
+.IP \fB\-nok\fR 8
+.IX Item "-nok"
+Report unsuccessful build on this system.  Forces \fB\-C\fR.  Forces and
+supplies a value for \fB\-s\fR, then requires you to edit the report
+and say what went wrong.  Alternatively, a prepared report may be
+supplied using \fB\-f\fR.  Only prompts for a return address if it
+cannot guess it (for use with \fBmake\fR). Honors return address
+specified with \fB\-r\fR.  You can use this with \fB\-v\fR to get more
+complete data.  Only makes a report if this system is less than 60
+days old.
+.IP \fB\-nokay\fR 8
+.IX Item "-nokay"
+As \fB\-nok\fR except it will report on older systems.
+.IP \fB\-p\fR 8
+.IX Item "-p"
+The names of one or more patch files or other text attachments to be
+included with the report.  Multiple files must be separated with commas.
+.IP \fB\-r\fR 8
+.IX Item "-r"
+Your return address.  The program will ask you to confirm its default
+if you don't use this option.
+.IP \fB\-S\fR 8
+.IX Item "-S"
+Save or send the report without asking for confirmation.
+.IP \fB\-s\fR 8
+.IX Item "-s"
+Subject to include with the report.  You will be prompted if you don't
+supply one on the command line.
+.IP \fB\-t\fR 8
+.IX Item "-t"
+Test mode.  Makes it possible to command perlbug from a pipe or file, for
+testing purposes.
+.IP \fB\-T\fR 8
+.IX Item "-T"
+Send a thank-you note instead of a bug report.
+.IP \fB\-v\fR 8
+.IX Item "-v"
+Include verbose configuration data in the report.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Kenneth Albanowski (<kjahds@kjahds.com>), subsequently
+\&\fIdoc\fRtored by Gurusamy Sarathy (<gsar@activestate.com>),
+Tom Christiansen (<tchrist@perl.com>), Nathan Torkington
+(<gnat@frii.com>), Charles F. Randall (<cfr@pobox.com>),
+Mike Guy (<mjtg@cam.ac.uk>), Dominic Dunlop
+(<domo@computer.org>), Hugo van der Sanden (<hv@crypt.org>),
+Jarkko Hietaniemi (<jhi@iki.fi>), Chris Nandor
+(<pudge@pobox.com>), Jon Orwant (<orwant@media.mit.edu>,
+Richard Foley (<richard.foley@rfi.net>), Jesse Vincent
+(<jesse@bestpractical.com>), and Craig A. Berry (<craigberry@mac.com>).
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1), \fBperldebug\fR\|(1), \fBperldiag\fR\|(1), \fBperlport\fR\|(1), \fBperltrap\fR\|(1),
+\&\fBdiff\fR\|(1), \fBpatch\fR\|(1), \fBdbx\fR\|(1), \fBgdb\fR\|(1)
+.SH BUGS
+.IX Header "BUGS"
+None known (guess what must have been used to report them?)
diff --git a/upstream/mageia-cauldron/man1/perlthrtut.1 b/upstream/mageia-cauldron/man1/perlthrtut.1
new file mode 100644
index 00000000..507c70c4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlthrtut.1
@@ -0,0 +1,1232 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTHRTUT 1"
+.TH PERLTHRTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlthrtut \- Tutorial on threads in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This tutorial describes the use of Perl interpreter threads (sometimes
+referred to as \fIithreads\fR).  In this
+model, each thread runs in its own Perl interpreter, and any data sharing
+between threads must be explicit.  The user-level interface for \fIithreads\fR
+uses the threads class.
+.PP
+\&\fBNOTE\fR: There was another older Perl threading flavor called the 5.005 model
+that used the threads class.  This old model was known to have problems, is
+deprecated, and was removed for release 5.10.  You are
+strongly encouraged to migrate any existing 5.005 threads code to the new
+model as soon as possible.
+.PP
+You can see which (or neither) threading flavour you have by
+running \f(CW\*(C`perl \-V\*(C'\fR and looking at the \f(CW\*(C`Platform\*(C'\fR section.
+If you have \f(CW\*(C`useithreads=define\*(C'\fR you have ithreads, if you
+have \f(CW\*(C`use5005threads=define\*(C'\fR you have 5.005 threads.
+If you have neither, you don't have any thread support built in.
+If you have both, you are in trouble.
+.PP
+The threads and threads::shared modules are included in the core Perl
+distribution.  Additionally, they are maintained as a separate modules on
+CPAN, so you can check there for any updates.
+.SH "What Is A Thread Anyway?"
+.IX Header "What Is A Thread Anyway?"
+A thread is a flow of control through a program with a single
+execution point.
+.PP
+Sounds an awful lot like a process, doesn't it? Well, it should.
+Threads are one of the pieces of a process.  Every process has at least
+one thread and, up until now, every process running Perl had only one
+thread.  With 5.8, though, you can create extra threads.  We're going
+to show you how, when, and why.
+.SH "Threaded Program Models"
+.IX Header "Threaded Program Models"
+There are three basic ways that you can structure a threaded
+program.  Which model you choose depends on what you need your program
+to do.  For many non-trivial threaded programs, you'll need to choose
+different models for different pieces of your program.
+.SS Boss/Worker
+.IX Subsection "Boss/Worker"
+The boss/worker model usually has one \fIboss\fR thread and one or more
+\&\fIworker\fR threads.  The boss thread gathers or generates tasks that need
+to be done, then parcels those tasks out to the appropriate worker
+thread.
+.PP
+This model is common in GUI and server programs, where a main thread
+waits for some event and then passes that event to the appropriate
+worker threads for processing.  Once the event has been passed on, the
+boss thread goes back to waiting for another event.
+.PP
+The boss thread does relatively little work.  While tasks aren't
+necessarily performed faster than with any other method, it tends to
+have the best user-response times.
+.SS "Work Crew"
+.IX Subsection "Work Crew"
+In the work crew model, several threads are created that do
+essentially the same thing to different pieces of data.  It closely
+mirrors classical parallel processing and vector processors, where a
+large array of processors do the exact same thing to many pieces of
+data.
+.PP
+This model is particularly useful if the system running the program
+will distribute multiple threads across different processors.  It can
+also be useful in ray tracing or rendering engines, where the
+individual threads can pass on interim results to give the user visual
+feedback.
+.SS Pipeline
+.IX Subsection "Pipeline"
+The pipeline model divides up a task into a series of steps, and
+passes the results of one step on to the thread processing the
+next.  Each thread does one thing to each piece of data and passes the
+results to the next thread in line.
+.PP
+This model makes the most sense if you have multiple processors so two
+or more threads will be executing in parallel, though it can often
+make sense in other contexts as well.  It tends to keep the individual
+tasks small and simple, as well as allowing some parts of the pipeline
+to block (on I/O or system calls, for example) while other parts keep
+going.  If you're running different parts of the pipeline on different
+processors you may also take advantage of the caches on each
+processor.
+.PP
+This model is also handy for a form of recursive programming where,
+rather than having a subroutine call itself, it instead creates
+another thread.  Prime and Fibonacci generators both map well to this
+form of the pipeline model. (A version of a prime number generator is
+presented later on.)
+.SH "What kind of threads are Perl threads?"
+.IX Header "What kind of threads are Perl threads?"
+If you have experience with other thread implementations, you might
+find that things aren't quite what you expect.  It's very important to
+remember when dealing with Perl threads that \fIPerl Threads Are Not X
+Threads\fR for all values of X.  They aren't POSIX threads, or
+DecThreads, or Java's Green threads, or Win32 threads.  There are
+similarities, and the broad concepts are the same, but if you start
+looking for implementation details you're going to be either
+disappointed or confused.  Possibly both.
+.PP
+This is not to say that Perl threads are completely different from
+everything that's ever come before. They're not.  Perl's threading
+model owes a lot to other thread models, especially POSIX.  Just as
+Perl is not C, though, Perl threads are not POSIX threads.  So if you
+find yourself looking for mutexes, or thread priorities, it's time to
+step back a bit and think about what you want to do and how Perl can
+do it.
+.PP
+However, it is important to remember that Perl threads cannot magically
+do things unless your operating system's threads allow it. So if your
+system blocks the entire process on \f(CWsleep()\fR, Perl usually will, as well.
+.PP
+\&\fBPerl Threads Are Different.\fR
+.SH "Thread-Safe Modules"
+.IX Header "Thread-Safe Modules"
+The addition of threads has changed Perl's internals
+substantially. There are implications for people who write
+modules with XS code or external libraries. However, since Perl data is
+not shared among threads by default, Perl modules stand a high chance of
+being thread-safe or can be made thread-safe easily.  Modules that are not
+tagged as thread-safe should be tested or code reviewed before being used
+in production code.
+.PP
+Not all modules that you might use are thread-safe, and you should
+always assume a module is unsafe unless the documentation says
+otherwise.  This includes modules that are distributed as part of the
+core.  Threads are a relatively new feature, and even some of the standard
+modules aren't thread-safe.
+.PP
+Even if a module is thread-safe, it doesn't mean that the module is optimized
+to work well with threads. A module could possibly be rewritten to utilize
+the new features in threaded Perl to increase performance in a threaded
+environment.
+.PP
+If you're using a module that's not thread-safe for some reason, you
+can protect yourself by using it from one, and only one thread at all.
+If you need multiple threads to access such a module, you can use semaphores and
+lots of programming discipline to control access to it.  Semaphores
+are covered in "Basic semaphores".
+.PP
+See also "Thread-Safety of System Libraries".
+.SH "Thread Basics"
+.IX Header "Thread Basics"
+The threads module provides the basic functions you need to write
+threaded programs.  In the following sections, we'll cover the basics,
+showing you what you need to do to create a threaded program.   After
+that, we'll go over some of the features of the threads module that
+make threaded programming easier.
+.SS "Basic Thread Support"
+.IX Subsection "Basic Thread Support"
+Thread support is a Perl compile-time option. It's something that's
+turned on or off when Perl is built at your site, rather than when
+your programs are compiled. If your Perl wasn't compiled with thread
+support enabled, then any attempt to use threads will fail.
+.PP
+Your programs can use the Config module to check whether threads are
+enabled. If your program can't run without them, you can say something
+like:
+.PP
+.Vb 3
+\&    use Config;
+\&    $Config{useithreads} or
+\&        die(\*(AqRecompile Perl with threads to run this program.\*(Aq);
+.Ve
+.PP
+A possibly-threaded program using a possibly-threaded module might
+have code like this:
+.PP
+.Vb 2
+\&    use Config;
+\&    use MyMod;
+\&
+\&    BEGIN {
+\&        if ($Config{useithreads}) {
+\&            # We have threads
+\&            require MyMod_threaded;
+\&            import MyMod_threaded;
+\&        } else {
+\&            require MyMod_unthreaded;
+\&            import MyMod_unthreaded;
+\&        }
+\&    }
+.Ve
+.PP
+Since code that runs both with and without threads is usually pretty
+messy, it's best to isolate the thread-specific code in its own
+module.  In our example above, that's what \f(CW\*(C`MyMod_threaded\*(C'\fR is, and it's
+only imported if we're running on a threaded Perl.
+.SS "A Note about the Examples"
+.IX Subsection "A Note about the Examples"
+In a real situation, care should be taken that all threads are finished
+executing before the program exits.  That care has \fBnot\fR been taken in these
+examples in the interest of simplicity.  Running these examples \fIas is\fR will
+produce error messages, usually caused by the fact that there are still
+threads running when the program exits.  You should not be alarmed by this.
+.SS "Creating Threads"
+.IX Subsection "Creating Threads"
+The threads module provides the tools you need to create new
+threads.  Like any other module, you need to tell Perl that you want to use
+it; \f(CW\*(C`use threads;\*(C'\fR imports all the pieces you need to create basic
+threads.
+.PP
+The simplest, most straightforward way to create a thread is with \f(CWcreate()\fR:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        print("In the thread\en");
+\&    }
+.Ve
+.PP
+The \f(CWcreate()\fR method takes a reference to a subroutine and creates a new
+thread that starts executing in the referenced subroutine.  Control
+then passes both to the subroutine and the caller.
+.PP
+If you need to, your program can pass parameters to the subroutine as
+part of the thread startup.  Just include the list of parameters as
+part of the \f(CW\*(C`threads\->create()\*(C'\fR call, like this:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $Param3 = \*(Aqfoo\*(Aq;
+\&    my $thr1 = threads\->create(\e&sub1, \*(AqParam 1\*(Aq, \*(AqParam 2\*(Aq, $Param3);
+\&    my @ParamList = (42, \*(AqHello\*(Aq, 3.14);
+\&    my $thr2 = threads\->create(\e&sub1, @ParamList);
+\&    my $thr3 = threads\->create(\e&sub1, qw(Param1 Param2 Param3));
+\&
+\&    sub sub1 {
+\&        my @InboundParameters = @_;
+\&        print("In the thread\en");
+\&        print(\*(AqGot parameters >\*(Aq, join(\*(Aq<>\*(Aq,@InboundParameters), "<\en");
+\&    }
+.Ve
+.PP
+The last example illustrates another feature of threads.  You can spawn
+off several threads using the same subroutine.  Each thread executes
+the same subroutine, but in a separate thread with a separate
+environment and potentially separate arguments.
+.PP
+\&\f(CWnew()\fR is a synonym for \f(CWcreate()\fR.
+.SS "Waiting For A Thread To Exit"
+.IX Subsection "Waiting For A Thread To Exit"
+Since threads are also subroutines, they can return values.  To wait
+for a thread to exit and extract any values it might return, you can
+use the \f(CWjoin()\fR method:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my ($thr) = threads\->create(\e&sub1);
+\&
+\&    my @ReturnData = $thr\->join();
+\&    print(\*(AqThread returned \*(Aq, join(\*(Aq, \*(Aq, @ReturnData), "\en");
+\&
+\&    sub sub1 { return (\*(AqFifty\-six\*(Aq, \*(Aqfoo\*(Aq, 2); }
+.Ve
+.PP
+In the example above, the \f(CWjoin()\fR method returns as soon as the thread
+ends.  In addition to waiting for a thread to finish and gathering up
+any values that the thread might have returned, \f(CWjoin()\fR also performs
+any OS cleanup necessary for the thread.  That cleanup might be
+important, especially for long-running programs that spawn lots of
+threads.  If you don't want the return values and don't want to wait
+for the thread to finish, you should call the \f(CWdetach()\fR method
+instead, as described next.
+.PP
+NOTE: In the example above, the thread returns a list, thus necessitating
+that the thread creation call be made in list context (i.e., \f(CW\*(C`my ($thr)\*(C'\fR).
+See "$thr\->\fBjoin()\fR" in threads and "THREAD CONTEXT" in threads for more
+details on thread context and return values.
+.SS "Ignoring A Thread"
+.IX Subsection "Ignoring A Thread"
+\&\f(CWjoin()\fR does three things: it waits for a thread to exit, cleans up
+after it, and returns any data the thread may have produced.  But what
+if you're not interested in the thread's return values, and you don't
+really care when the thread finishes? All you want is for the thread
+to get cleaned up after when it's done.
+.PP
+In this case, you use the \f(CWdetach()\fR method.  Once a thread is detached,
+it'll run until it's finished; then Perl will clean up after it
+automatically.
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);   # Spawn the thread
+\&
+\&    $thr\->detach();   # Now we officially don\*(Aqt care any more
+\&
+\&    sleep(15);        # Let thread run for awhile
+\&
+\&    sub sub1 {
+\&        my $count = 0;
+\&        while (1) {
+\&            $count++;
+\&            print("\e$count is $count\en");
+\&            sleep(1);
+\&        }
+\&    }
+.Ve
+.PP
+Once a thread is detached, it may not be joined, and any return data
+that it might have produced (if it was done and waiting for a join) is
+lost.
+.PP
+\&\f(CWdetach()\fR can also be called as a class method to allow a thread to
+detach itself:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        threads\->detach();
+\&        # Do more work
+\&    }
+.Ve
+.SS "Process and Thread Termination"
+.IX Subsection "Process and Thread Termination"
+With threads one must be careful to make sure they all have a chance to
+run to completion, assuming that is what you want.
+.PP
+An action that terminates a process will terminate \fIall\fR running
+threads.  \fBdie()\fR and \fBexit()\fR have this property,
+and perl does an exit when the main thread exits,
+perhaps implicitly by falling off the end of your code,
+even if that's not what you want.
+.PP
+As an example of this case, this code prints the message
+"Perl exited with active threads: 2 running and unjoined":
+.PP
+.Vb 8
+\&    use threads;
+\&    my $thr1 = threads\->new(\e&thrsub, "test1");
+\&    my $thr2 = threads\->new(\e&thrsub, "test2");
+\&    sub thrsub {
+\&       my ($message) = @_;
+\&       sleep 1;
+\&       print "thread $message\en";
+\&    }
+.Ve
+.PP
+But when the following lines are added at the end:
+.PP
+.Vb 2
+\&    $thr1\->join();
+\&    $thr2\->join();
+.Ve
+.PP
+it prints two lines of output, a perhaps more useful outcome.
+.SH "Threads And Data"
+.IX Header "Threads And Data"
+Now that we've covered the basics of threads, it's time for our next
+topic: Data.  Threading introduces a couple of complications to data
+access that non-threaded programs never need to worry about.
+.SS "Shared And Unshared Data"
+.IX Subsection "Shared And Unshared Data"
+The biggest difference between Perl \fIithreads\fR and the old 5.005 style
+threading, or for that matter, to most other threading systems out there,
+is that by default, no data is shared. When a new Perl thread is created,
+all the data associated with the current thread is copied to the new
+thread, and is subsequently private to that new thread!
+This is similar in feel to what happens when a Unix process forks,
+except that in this case, the data is just copied to a different part of
+memory within the same process rather than a real fork taking place.
+.PP
+To make use of threading, however, one usually wants the threads to share
+at least some data between themselves. This is done with the
+threads::shared module and the \f(CW\*(C`:shared\*(C'\fR attribute:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $foo :shared = 1;
+\&    my $bar = 1;
+\&    threads\->create(sub { $foo++; $bar++; })\->join();
+\&
+\&    print("$foo\en");  # Prints 2 since $foo is shared
+\&    print("$bar\en");  # Prints 1 since $bar is not shared
+.Ve
+.PP
+In the case of a shared array, all the array's elements are shared, and for
+a shared hash, all the keys and values are shared. This places
+restrictions on what may be assigned to shared array and hash elements: only
+simple values or references to shared variables are allowed \- this is
+so that a private variable can't accidentally become shared. A bad
+assignment will cause the thread to die. For example:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $var          = 1;
+\&    my $svar :shared = 2;
+\&    my %hash :shared;
+\&
+\&    ... create some threads ...
+\&
+\&    $hash{a} = 1;       # All threads see exists($hash{a})
+\&                        # and $hash{a} == 1
+\&    $hash{a} = $var;    # okay \- copy\-by\-value: same effect as previous
+\&    $hash{a} = $svar;   # okay \- copy\-by\-value: same effect as previous
+\&    $hash{a} = \e$svar;  # okay \- a reference to a shared variable
+\&    $hash{a} = \e$var;   # This will die
+\&    delete($hash{a});   # okay \- all threads will see !exists($hash{a})
+.Ve
+.PP
+Note that a shared variable guarantees that if two or more threads try to
+modify it at the same time, the internal state of the variable will not
+become corrupted. However, there are no guarantees beyond this, as
+explained in the next section.
+.SS "Thread Pitfalls: Races"
+.IX Subsection "Thread Pitfalls: Races"
+While threads bring a new set of useful tools, they also bring a
+number of pitfalls.  One pitfall is the race condition:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $x :shared = 1;
+\&    my $thr1 = threads\->create(\e&sub1);
+\&    my $thr2 = threads\->create(\e&sub2);
+\&
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    print("$x\en");
+\&
+\&    sub sub1 { my $foo = $x; $x = $foo + 1; }
+\&    sub sub2 { my $bar = $x; $x = $bar + 1; }
+.Ve
+.PP
+What do you think \f(CW$x\fR will be? The answer, unfortunately, is \fIit
+depends\fR. Both \f(CWsub1()\fR and \f(CWsub2()\fR access the global variable \f(CW$x\fR, once
+to read and once to write.  Depending on factors ranging from your
+thread implementation's scheduling algorithm to the phase of the moon,
+\&\f(CW$x\fR can be 2 or 3.
+.PP
+Race conditions are caused by unsynchronized access to shared
+data.  Without explicit synchronization, there's no way to be sure that
+nothing has happened to the shared data between the time you access it
+and the time you update it.  Even this simple code fragment has the
+possibility of error:
+.PP
+.Vb 8
+\&    use threads;
+\&    my $x :shared = 2;
+\&    my $y :shared;
+\&    my $z :shared;
+\&    my $thr1 = threads\->create(sub { $y = $x; $x = $y + 1; });
+\&    my $thr2 = threads\->create(sub { $z = $x; $x = $z + 1; });
+\&    $thr1\->join();
+\&    $thr2\->join();
+.Ve
+.PP
+Two threads both access \f(CW$x\fR.  Each thread can potentially be interrupted
+at any point, or be executed in any order.  At the end, \f(CW$x\fR could be 3
+or 4, and both \f(CW$y\fR and \f(CW$z\fR could be 2 or 3.
+.PP
+Even \f(CW\*(C`$x += 5\*(C'\fR or \f(CW\*(C`$x++\*(C'\fR are not guaranteed to be atomic.
+.PP
+Whenever your program accesses data or resources that can be accessed
+by other threads, you must take steps to coordinate access or risk
+data inconsistency and race conditions. Note that Perl will protect its
+internals from your race conditions, but it won't protect you from you.
+.SH "Synchronization and control"
+.IX Header "Synchronization and control"
+Perl provides a number of mechanisms to coordinate the interactions
+between themselves and their data, to avoid race conditions and the like.
+Some of these are designed to resemble the common techniques used in thread
+libraries such as \f(CW\*(C`pthreads\*(C'\fR; others are Perl-specific. Often, the
+standard techniques are clumsy and difficult to get right (such as
+condition waits). Where possible, it is usually easier to use Perlish
+techniques such as queues, which remove some of the hard work involved.
+.SS "Controlling access: \fBlock()\fP"
+.IX Subsection "Controlling access: lock()"
+The \f(CWlock()\fR function takes a shared variable and puts a lock on it.
+No other thread may lock the variable until the variable is unlocked
+by the thread holding the lock. Unlocking happens automatically
+when the locking thread exits the block that contains the call to the
+\&\f(CWlock()\fR function.  Using \f(CWlock()\fR is straightforward: This example has
+several threads doing some calculations in parallel, and occasionally
+updating a running total:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $total :shared = 0;
+\&
+\&    sub calc {
+\&        while (1) {
+\&            my $result;
+\&            # (... do some calculations and set $result ...)
+\&            {
+\&                lock($total);  # Block until we obtain the lock
+\&                $total += $result;
+\&            } # Lock implicitly released at end of scope
+\&            last if $result == 0;
+\&        }
+\&    }
+\&
+\&    my $thr1 = threads\->create(\e&calc);
+\&    my $thr2 = threads\->create(\e&calc);
+\&    my $thr3 = threads\->create(\e&calc);
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    $thr3\->join();
+\&    print("total=$total\en");
+.Ve
+.PP
+\&\f(CWlock()\fR blocks the thread until the variable being locked is
+available.  When \f(CWlock()\fR returns, your thread can be sure that no other
+thread can lock that variable until the block containing the
+lock exits.
+.PP
+It's important to note that locks don't prevent access to the variable
+in question, only lock attempts.  This is in keeping with Perl's
+longstanding tradition of courteous programming, and the advisory file
+locking that \f(CWflock()\fR gives you.
+.PP
+You may lock arrays and hashes as well as scalars.  Locking an array,
+though, will not block subsequent locks on array elements, just lock
+attempts on the array itself.
+.PP
+Locks are recursive, which means it's okay for a thread to
+lock a variable more than once.  The lock will last until the outermost
+\&\f(CWlock()\fR on the variable goes out of scope. For example:
+.PP
+.Vb 2
+\&    my $x :shared;
+\&    doit();
+\&
+\&    sub doit {
+\&        {
+\&            {
+\&                lock($x); # Wait for lock
+\&                lock($x); # NOOP \- we already have the lock
+\&                {
+\&                    lock($x); # NOOP
+\&                    {
+\&                        lock($x); # NOOP
+\&                        lockit_some_more();
+\&                    }
+\&                }
+\&            } # *** Implicit unlock here ***
+\&        }
+\&    }
+\&
+\&    sub lockit_some_more {
+\&        lock($x); # NOOP
+\&    } # Nothing happens here
+.Ve
+.PP
+Note that there is no \f(CWunlock()\fR function \- the only way to unlock a
+variable is to allow it to go out of scope.
+.PP
+A lock can either be used to guard the data contained within the variable
+being locked, or it can be used to guard something else, like a section
+of code. In this latter case, the variable in question does not hold any
+useful data, and exists only for the purpose of being locked. In this
+respect, the variable behaves like the mutexes and basic semaphores of
+traditional thread libraries.
+.SS "A Thread Pitfall: Deadlocks"
+.IX Subsection "A Thread Pitfall: Deadlocks"
+Locks are a handy tool to synchronize access to data, and using them
+properly is the key to safe shared data.  Unfortunately, locks aren't
+without their dangers, especially when multiple locks are involved.
+Consider the following code:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $x :shared = 4;
+\&    my $y :shared = \*(Aqfoo\*(Aq;
+\&    my $thr1 = threads\->create(sub {
+\&        lock($x);
+\&        sleep(20);
+\&        lock($y);
+\&    });
+\&    my $thr2 = threads\->create(sub {
+\&        lock($y);
+\&        sleep(20);
+\&        lock($x);
+\&    });
+.Ve
+.PP
+This program will probably hang until you kill it.  The only way it
+won't hang is if one of the two threads acquires both locks
+first.  A guaranteed-to-hang version is more complicated, but the
+principle is the same.
+.PP
+The first thread will grab a lock on \f(CW$x\fR, then, after a pause during which
+the second thread has probably had time to do some work, try to grab a
+lock on \f(CW$y\fR.  Meanwhile, the second thread grabs a lock on \f(CW$y\fR, then later
+tries to grab a lock on \f(CW$x\fR.  The second lock attempt for both threads will
+block, each waiting for the other to release its lock.
+.PP
+This condition is called a deadlock, and it occurs whenever two or
+more threads are trying to get locks on resources that the others
+own.  Each thread will block, waiting for the other to release a lock
+on a resource.  That never happens, though, since the thread with the
+resource is itself waiting for a lock to be released.
+.PP
+There are a number of ways to handle this sort of problem.  The best
+way is to always have all threads acquire locks in the exact same
+order.  If, for example, you lock variables \f(CW$x\fR, \f(CW$y\fR, and \f(CW$z\fR, always lock
+\&\f(CW$x\fR before \f(CW$y\fR, and \f(CW$y\fR before \f(CW$z\fR.  It's also best to hold on to locks for
+as short a period of time to minimize the risks of deadlock.
+.PP
+The other synchronization primitives described below can suffer from
+similar problems.
+.SS "Queues: Passing Data Around"
+.IX Subsection "Queues: Passing Data Around"
+A queue is a special thread-safe object that lets you put data in one
+end and take it out the other without having to worry about
+synchronization issues.  They're pretty straightforward, and look like
+this:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Queue;
+\&
+\&    my $DataQueue = Thread::Queue\->new();
+\&    my $thr = threads\->create(sub {
+\&        while (my $DataElement = $DataQueue\->dequeue()) {
+\&            print("Popped $DataElement off the queue\en");
+\&        }
+\&    });
+\&
+\&    $DataQueue\->enqueue(12);
+\&    $DataQueue\->enqueue("A", "B", "C");
+\&    sleep(10);
+\&    $DataQueue\->enqueue(undef);
+\&    $thr\->join();
+.Ve
+.PP
+You create the queue with \f(CW\*(C`Thread::Queue\->new()\*(C'\fR.  Then you can
+add lists of scalars onto the end with \f(CWenqueue()\fR, and pop scalars off
+the front of it with \f(CWdequeue()\fR.  A queue has no fixed size, and can grow
+as needed to hold everything pushed on to it.
+.PP
+If a queue is empty, \f(CWdequeue()\fR blocks until another thread enqueues
+something.  This makes queues ideal for event loops and other
+communications between threads.
+.SS "Semaphores: Synchronizing Data Access"
+.IX Subsection "Semaphores: Synchronizing Data Access"
+Semaphores are a kind of generic locking mechanism. In their most basic
+form, they behave very much like lockable scalars, except that they
+can't hold data, and that they must be explicitly unlocked. In their
+advanced form, they act like a kind of counter, and can allow multiple
+threads to have the \fIlock\fR at any one time.
+.SS "Basic semaphores"
+.IX Subsection "Basic semaphores"
+Semaphores have two methods, \f(CWdown()\fR and \f(CWup()\fR: \f(CWdown()\fR decrements the resource
+count, while \f(CWup()\fR increments it. Calls to \f(CWdown()\fR will block if the
+semaphore's current count would decrement below zero.  This program
+gives a quick demonstration:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Semaphore;
+\&
+\&    my $semaphore = Thread::Semaphore\->new();
+\&    my $GlobalVariable :shared = 0;
+\&
+\&    $thr1 = threads\->create(\e&sample_sub, 1);
+\&    $thr2 = threads\->create(\e&sample_sub, 2);
+\&    $thr3 = threads\->create(\e&sample_sub, 3);
+\&
+\&    sub sample_sub {
+\&        my $SubNumber = shift(@_);
+\&        my $TryCount = 10;
+\&        my $LocalCopy;
+\&        sleep(1);
+\&        while ($TryCount\-\-) {
+\&            $semaphore\->down();
+\&            $LocalCopy = $GlobalVariable;
+\&            print("$TryCount tries left for sub $SubNumber "
+\&                 ."(\e$GlobalVariable is $GlobalVariable)\en");
+\&            sleep(2);
+\&            $LocalCopy++;
+\&            $GlobalVariable = $LocalCopy;
+\&            $semaphore\->up();
+\&        }
+\&    }
+\&
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    $thr3\->join();
+.Ve
+.PP
+The three invocations of the subroutine all operate in sync.  The
+semaphore, though, makes sure that only one thread is accessing the
+global variable at once.
+.SS "Advanced Semaphores"
+.IX Subsection "Advanced Semaphores"
+By default, semaphores behave like locks, letting only one thread
+\&\f(CWdown()\fR them at a time.  However, there are other uses for semaphores.
+.PP
+Each semaphore has a counter attached to it. By default, semaphores are
+created with the counter set to one, \f(CWdown()\fR decrements the counter by
+one, and \f(CWup()\fR increments by one. However, we can override any or all
+of these defaults simply by passing in different values:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Semaphore;
+\&
+\&    my $semaphore = Thread::Semaphore\->new(5);
+\&                    # Creates a semaphore with the counter set to five
+\&
+\&    my $thr1 = threads\->create(\e&sub1);
+\&    my $thr2 = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        $semaphore\->down(5); # Decrements the counter by five
+\&        # Do stuff here
+\&        $semaphore\->up(5); # Increment the counter by five
+\&    }
+\&
+\&    $thr1\->detach();
+\&    $thr2\->detach();
+.Ve
+.PP
+If \f(CWdown()\fR attempts to decrement the counter below zero, it blocks until
+the counter is large enough.  Note that while a semaphore can be created
+with a starting count of zero, any \f(CWup()\fR or \f(CWdown()\fR always changes the
+counter by at least one, and so \f(CW\*(C`$semaphore\->down(0)\*(C'\fR is the same as
+\&\f(CW\*(C`$semaphore\->down(1)\*(C'\fR.
+.PP
+The question, of course, is why would you do something like this? Why
+create a semaphore with a starting count that's not one, or why
+decrement or increment it by more than one? The answer is resource
+availability.  Many resources that you want to manage access for can be
+safely used by more than one thread at once.
+.PP
+For example, let's take a GUI driven program.  It has a semaphore that
+it uses to synchronize access to the display, so only one thread is
+ever drawing at once.  Handy, but of course you don't want any thread
+to start drawing until things are properly set up.  In this case, you
+can create a semaphore with a counter set to zero, and up it when
+things are ready for drawing.
+.PP
+Semaphores with counters greater than one are also useful for
+establishing quotas.  Say, for example, that you have a number of
+threads that can do I/O at once.  You don't want all the threads
+reading or writing at once though, since that can potentially swamp
+your I/O channels, or deplete your process's quota of filehandles.  You
+can use a semaphore initialized to the number of concurrent I/O
+requests (or open files) that you want at any one time, and have your
+threads quietly block and unblock themselves.
+.PP
+Larger increments or decrements are handy in those cases where a
+thread needs to check out or return a number of resources at once.
+.SS "Waiting for a Condition"
+.IX Subsection "Waiting for a Condition"
+The functions \f(CWcond_wait()\fR and \f(CWcond_signal()\fR
+can be used in conjunction with locks to notify
+co-operating threads that a resource has become available. They are
+very similar in use to the functions found in \f(CW\*(C`pthreads\*(C'\fR. However
+for most purposes, queues are simpler to use and more intuitive. See
+threads::shared for more details.
+.SS "Giving up control"
+.IX Subsection "Giving up control"
+There are times when you may find it useful to have a thread
+explicitly give up the CPU to another thread.  You may be doing something
+processor-intensive and want to make sure that the user-interface thread
+gets called frequently.  Regardless, there are times that you might want
+a thread to give up the processor.
+.PP
+Perl's threading package provides the \f(CWyield()\fR function that does
+this. \f(CWyield()\fR is pretty straightforward, and works like this:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    sub loop {
+\&        my $thread = shift;
+\&        my $foo = 50;
+\&        while($foo\-\-) { print("In thread $thread\en"); }
+\&        threads\->yield();
+\&        $foo = 50;
+\&        while($foo\-\-) { print("In thread $thread\en"); }
+\&    }
+\&
+\&    my $thr1 = threads\->create(\e&loop, \*(Aqfirst\*(Aq);
+\&    my $thr2 = threads\->create(\e&loop, \*(Aqsecond\*(Aq);
+\&    my $thr3 = threads\->create(\e&loop, \*(Aqthird\*(Aq);
+.Ve
+.PP
+It is important to remember that \f(CWyield()\fR is only a hint to give up the CPU,
+it depends on your hardware, OS and threading libraries what actually happens.
+\&\fBOn many operating systems, yield() is a no-op.\fR  Therefore it is important
+to note that one should not build the scheduling of the threads around
+\&\f(CWyield()\fR calls. It might work on your platform but it won't work on another
+platform.
+.SH "General Thread Utility Routines"
+.IX Header "General Thread Utility Routines"
+We've covered the workhorse parts of Perl's threading package, and
+with these tools you should be well on your way to writing threaded
+code and packages.  There are a few useful little pieces that didn't
+really fit in anyplace else.
+.SS "What Thread Am I In?"
+.IX Subsection "What Thread Am I In?"
+The \f(CW\*(C`threads\->self()\*(C'\fR class method provides your program with a way to
+get an object representing the thread it's currently in.  You can use this
+object in the same way as the ones returned from thread creation.
+.SS "Thread IDs"
+.IX Subsection "Thread IDs"
+\&\f(CWtid()\fR is a thread object method that returns the thread ID of the
+thread the object represents.  Thread IDs are integers, with the main
+thread in a program being 0.  Currently Perl assigns a unique TID to
+every thread ever created in your program, assigning the first thread
+to be created a TID of 1, and increasing the TID by 1 for each new
+thread that's created.  When used as a class method, \f(CW\*(C`threads\->tid()\*(C'\fR
+can be used by a thread to get its own TID.
+.SS "Are These Threads The Same?"
+.IX Subsection "Are These Threads The Same?"
+The \f(CWequal()\fR method takes two thread objects and returns true
+if the objects represent the same thread, and false if they don't.
+.PP
+Thread objects also have an overloaded \f(CW\*(C`==\*(C'\fR comparison so that you can do
+comparison on them as you would with normal objects.
+.SS "What Threads Are Running?"
+.IX Subsection "What Threads Are Running?"
+\&\f(CW\*(C`threads\->list()\*(C'\fR returns a list of thread objects, one for each thread
+that's currently running and not detached.  Handy for a number of things,
+including cleaning up at the end of your program (from the main Perl thread,
+of course):
+.PP
+.Vb 4
+\&    # Loop through all the threads
+\&    foreach my $thr (threads\->list()) {
+\&        $thr\->join();
+\&    }
+.Ve
+.PP
+If some threads have not finished running when the main Perl thread
+ends, Perl will warn you about it and die, since it is impossible for Perl
+to clean up itself while other threads are running.
+.PP
+NOTE:  The main Perl thread (thread 0) is in a \fIdetached\fR state, and so
+does not appear in the list returned by \f(CW\*(C`threads\->list()\*(C'\fR.
+.SH "A Complete Example"
+.IX Header "A Complete Example"
+Confused yet? It's time for an example program to show some of the
+things we've covered.  This program finds prime numbers using threads.
+.PP
+.Vb 10
+\&   1 #!/usr/bin/perl
+\&   2 # prime\-pthread, courtesy of Tom Christiansen
+\&   3
+\&   4 use v5.36;
+\&   5
+\&   6 use threads;
+\&   7 use Thread::Queue;
+\&   8
+\&   9 sub check_num ($upstream, $cur_prime) {
+\&  10     my $kid;
+\&  11     my $downstream = Thread::Queue\->new();
+\&  12     while (my $num = $upstream\->dequeue()) {
+\&  13         next unless ($num % $cur_prime);
+\&  14         if ($kid) {
+\&  15             $downstream\->enqueue($num);
+\&  16         } else {
+\&  17             print("Found prime: $num\en");
+\&  18             $kid = threads\->create(\e&check_num, $downstream, $num);
+\&  19             if (! $kid) {
+\&  20                 warn("Sorry.  Ran out of threads.\en");
+\&  21                 last;
+\&  22             }
+\&  23         }
+\&  24     }
+\&  25     if ($kid) {
+\&  26         $downstream\->enqueue(undef);
+\&  27         $kid\->join();
+\&  28     }
+\&  29 }
+\&  30
+\&  31 my $stream = Thread::Queue\->new(3..1000, undef);
+\&  32 check_num($stream, 2);
+.Ve
+.PP
+This program uses the pipeline model to generate prime numbers.  Each
+thread in the pipeline has an input queue that feeds numbers to be
+checked, a prime number that it's responsible for, and an output queue
+into which it funnels numbers that have failed the check.  If the thread
+has a number that's failed its check and there's no child thread, then
+the thread must have found a new prime number.  In that case, a new
+child thread is created for that prime and stuck on the end of the
+pipeline.
+.PP
+This probably sounds a bit more confusing than it really is, so let's
+go through this program piece by piece and see what it does.  (For
+those of you who might be trying to remember exactly what a prime
+number is, it's a number that's only evenly divisible by itself and 1.)
+.PP
+The bulk of the work is done by the \f(CWcheck_num()\fR subroutine, which
+takes a reference to its input queue and a prime number that it's
+responsible for.  We create a new queue (line 11) and reserve a scalar
+for the thread that we're likely to create later (line 10).
+.PP
+The while loop from line 12 to line 24 grabs a scalar off the input
+queue and checks against the prime this thread is responsible
+for.  Line 13 checks to see if there's a remainder when we divide the
+number to be checked by our prime.  If there is one, the number
+must not be evenly divisible by our prime, so we need to either pass
+it on to the next thread if we've created one (line 15) or create a
+new thread if we haven't.
+.PP
+The new thread creation is line 18.  We pass on to it a reference to
+the queue we've created, and the prime number we've found.  In lines 19
+through 22, we check to make sure that our new thread got created, and
+if not, we stop checking any remaining numbers in the queue.
+.PP
+Finally, once the loop terminates (because we got a 0 or \f(CW\*(C`undef\*(C'\fR in the
+queue, which serves as a note to terminate), we pass on the notice to our
+child, and wait for it to exit if we've created a child (lines 25 and
+28).
+.PP
+Meanwhile, back in the main thread, we first create a queue (line 31) and
+queue up all the numbers from 3 to 1000 for checking, plus a termination
+notice.  Then all we have to do to get the ball rolling is pass the queue
+and the first prime to the \f(CWcheck_num()\fR subroutine (line 32).
+.PP
+That's how it works.  It's pretty simple; as with many Perl programs,
+the explanation is much longer than the program.
+.SH "Different implementations of threads"
+.IX Header "Different implementations of threads"
+Some background on thread implementations from the operating system
+viewpoint.  There are three basic categories of threads: user-mode threads,
+kernel threads, and multiprocessor kernel threads.
+.PP
+User-mode threads are threads that live entirely within a program and
+its libraries.  In this model, the OS knows nothing about threads.  As
+far as it's concerned, your process is just a process.
+.PP
+This is the easiest way to implement threads, and the way most OSes
+start.  The big disadvantage is that, since the OS knows nothing about
+threads, if one thread blocks they all do.  Typical blocking activities
+include most system calls, most I/O, and things like \f(CWsleep()\fR.
+.PP
+Kernel threads are the next step in thread evolution.  The OS knows
+about kernel threads, and makes allowances for them.  The main
+difference between a kernel thread and a user-mode thread is
+blocking.  With kernel threads, things that block a single thread don't
+block other threads.  This is not the case with user-mode threads,
+where the kernel blocks at the process level and not the thread level.
+.PP
+This is a big step forward, and can give a threaded program quite a
+performance boost over non-threaded programs.  Threads that block
+performing I/O, for example, won't block threads that are doing other
+things.  Each process still has only one thread running at once,
+though, regardless of how many CPUs a system might have.
+.PP
+Since kernel threading can interrupt a thread at any time, they will
+uncover some of the implicit locking assumptions you may make in your
+program.  For example, something as simple as \f(CW\*(C`$x = $x + 2\*(C'\fR can behave
+unpredictably with kernel threads if \f(CW$x\fR is visible to other
+threads, as another thread may have changed \f(CW$x\fR between the time it
+was fetched on the right hand side and the time the new value is
+stored.
+.PP
+Multiprocessor kernel threads are the final step in thread
+support.  With multiprocessor kernel threads on a machine with multiple
+CPUs, the OS may schedule two or more threads to run simultaneously on
+different CPUs.
+.PP
+This can give a serious performance boost to your threaded program,
+since more than one thread will be executing at the same time.  As a
+tradeoff, though, any of those nagging synchronization issues that
+might not have shown with basic kernel threads will appear with a
+vengeance.
+.PP
+In addition to the different levels of OS involvement in threads,
+different OSes (and different thread implementations for a particular
+OS) allocate CPU cycles to threads in different ways.
+.PP
+Cooperative multitasking systems have running threads give up control
+if one of two things happen.  If a thread calls a yield function, it
+gives up control.  It also gives up control if the thread does
+something that would cause it to block, such as perform I/O.  In a
+cooperative multitasking implementation, one thread can starve all the
+others for CPU time if it so chooses.
+.PP
+Preemptive multitasking systems interrupt threads at regular intervals
+while the system decides which thread should run next.  In a preemptive
+multitasking system, one thread usually won't monopolize the CPU.
+.PP
+On some systems, there can be cooperative and preemptive threads
+running simultaneously. (Threads running with realtime priorities
+often behave cooperatively, for example, while threads running at
+normal priorities behave preemptively.)
+.PP
+Most modern operating systems support preemptive multitasking nowadays.
+.SH "Performance considerations"
+.IX Header "Performance considerations"
+The main thing to bear in mind when comparing Perl's \fIithreads\fR to other threading
+models is the fact that for each new thread created, a complete copy of
+all the variables and data of the parent thread has to be taken. Thus,
+thread creation can be quite expensive, both in terms of memory usage and
+time spent in creation. The ideal way to reduce these costs is to have a
+relatively short number of long-lived threads, all created fairly early
+on (before the base thread has accumulated too much data). Of course, this
+may not always be possible, so compromises have to be made. However, after
+a thread has been created, its performance and extra memory usage should
+be little different than ordinary code.
+.PP
+Also note that under the current implementation, shared variables
+use a little more memory and are a little slower than ordinary variables.
+.SH "Process-scope Changes"
+.IX Header "Process-scope Changes"
+Note that while threads themselves are separate execution threads and
+Perl data is thread-private unless explicitly shared, the threads can
+affect process-scope state, affecting all the threads.
+.PP
+The most common example of this is changing the current working
+directory using \f(CWchdir()\fR.  One thread calls \f(CWchdir()\fR, and the working
+directory of all the threads changes.
+.PP
+Even more drastic example of a process-scope change is \f(CWchroot()\fR:
+the root directory of all the threads changes, and no thread can
+undo it (as opposed to \f(CWchdir()\fR).
+.PP
+Further examples of process-scope changes include \f(CWumask()\fR and
+changing uids and gids.
+.PP
+Thinking of mixing \f(CWfork()\fR and threads?  Please lie down and wait
+until the feeling passes.  Be aware that the semantics of \f(CWfork()\fR vary
+between platforms.  For example, some Unix systems copy all the current
+threads into the child process, while others only copy the thread that
+called \f(CWfork()\fR. You have been warned!
+.PP
+Similarly, mixing signals and threads may be problematic.
+Implementations are platform-dependent, and even the POSIX
+semantics may not be what you expect (and Perl doesn't even
+give you the full POSIX API).  For example, there is no way to
+guarantee that a signal sent to a multi-threaded Perl application
+will get intercepted by any particular thread.  (However, a recently
+added feature does provide the capability to send signals between
+threads.  See "THREAD SIGNALLING" in threads for more details.)
+.SH "Thread-Safety of System Libraries"
+.IX Header "Thread-Safety of System Libraries"
+Whether various library calls are thread-safe is outside the control
+of Perl.  Calls often suffering from not being thread-safe include:
+\&\f(CWlocaltime()\fR, \f(CWgmtime()\fR,  functions fetching user, group and
+network information (such as \f(CWgetgrent()\fR, \f(CWgethostent()\fR,
+\&\f(CWgetnetent()\fR and so on), \f(CWreaddir()\fR, \f(CWrand()\fR, and \f(CWsrand()\fR. In
+general, calls that depend on some global external state.
+.PP
+If the system Perl is compiled in has thread-safe variants of such
+calls, they will be used.  Beyond that, Perl is at the mercy of
+the thread-safety or \-unsafety of the calls.  Please consult your
+C library call documentation.
+.PP
+On some platforms the thread-safe library interfaces may fail if the
+result buffer is too small (for example the user group databases may
+be rather large, and the reentrant interfaces may have to carry around
+a full snapshot of those databases).  Perl will start with a small
+buffer, but keep retrying and growing the result buffer
+until the result fits.  If this limitless growing sounds bad for
+security or memory consumption reasons you can recompile Perl with
+\&\f(CW\*(C`PERL_REENTRANT_MAXSIZE\*(C'\fR defined to the maximum number of bytes you will
+allow.
+.SH Conclusion
+.IX Header "Conclusion"
+A complete thread tutorial could fill a book (and has, many times),
+but with what we've covered in this introduction, you should be well
+on your way to becoming a threaded Perl expert.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Annotated POD for threads:
+<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads>
+.PP
+Latest version of threads on CPAN:
+<https://metacpan.org/pod/threads>
+.PP
+Annotated POD for threads::shared:
+<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared>
+.PP
+Latest version of threads::shared on CPAN:
+<https://metacpan.org/pod/threads::shared>
+.PP
+Perl threads mailing list:
+<https://lists.perl.org/list/ithreads.html>
+.SH Bibliography
+.IX Header "Bibliography"
+Here's a short bibliography courtesy of Jürgen Christoffel:
+.SS "Introductory Texts"
+.IX Subsection "Introductory Texts"
+Birrell, Andrew D. An Introduction to Programming with
+Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
+#35 online as
+<https://www.hpl.hp.com/techreports/Compaq\-DEC/SRC\-RR\-35.pdf>
+(highly recommended)
+.PP
+Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
+Guide to Concurrency, Communication, and
+Multithreading. Prentice-Hall, 1996.
+.PP
+Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
+Pthreads. Prentice Hall, 1997, ISBN 0\-13\-443698\-9 (a well-written
+introduction to threads).
+.PP
+Nelson, Greg (editor). Systems Programming with Modula\-3.  Prentice
+Hall, 1991, ISBN 0\-13\-590464\-1.
+.PP
+Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
+Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592\-115\-1
+(covers POSIX threads).
+.SS "OS-Related References"
+.IX Subsection "OS-Related References"
+Boykin, Joseph, David Kirschen, Alan Langerman, and Susan
+LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN
+0\-201\-52739\-1.
+.PP
+Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
+1995, ISBN 0\-13\-219908\-4 (great textbook).
+.PP
+Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
+4th ed. Addison-Wesley, 1995, ISBN 0\-201\-59292\-4
+.SS "Other References"
+.IX Subsection "Other References"
+Arnold, Ken and James Gosling. The Java Programming Language, 2nd
+ed. Addison-Wesley, 1998, ISBN 0\-201\-31006\-6.
+.PP
+comp.programming.threads FAQ,
+<http://www.serpentine.com/~bos/threads\-faq/>
+.PP
+Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
+Collection on Virtually Shared Memory Architectures" in Memory
+Management: Proc. of the International Workshop IWMM 92, St. Malo,
+France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
+1992, ISBN 3540\-55940\-X (real-life thread applications).
+.PP
+Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002,
+<http://www.perl.com/pub/a/2002/06/11/threads.html>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
+Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
+Pritikin, and Alan Burlison, for their help in reality-checking and
+polishing this article.  Big thanks to Tom Christiansen for his rewrite
+of the prime number generator.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Dan Sugalski <dan@sidhe.org>
+.PP
+Slightly modified by Arthur Bergman to fit the new thread model/module.
+.PP
+Reworked slightly by Jörg Walter <jwalt@cpan.org> to be more concise
+about thread-safety of Perl code.
+.PP
+Rearranged slightly by Elizabeth Mattijsen <liz@dijkmat.nl> to put
+less emphasis on \fByield()\fR.
+.SH Copyrights
+.IX Header "Copyrights"
+The original version of this article originally appeared in The Perl
+Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy
+of Jon Orwant and The Perl Journal.  This document may be distributed
+under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perltie.1 b/upstream/mageia-cauldron/man1/perltie.1
new file mode 100644
index 00000000..8a83d1c7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltie.1
@@ -0,0 +1,1361 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTIE 1"
+.TH PERLTIE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltie \- how to hide an object class in a simple variable
+.IX Xref "tie"
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& tie VARIABLE, CLASSNAME, LIST
+\&
+\& $object = tied VARIABLE
+\&
+\& untie VARIABLE
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Prior to release 5.0 of Perl, a programmer could use \fBdbmopen()\fR
+to connect an on-disk database in the standard Unix \fBdbm\fR\|(3x)
+format magically to a \f(CW%HASH\fR in their program.  However, their Perl was either
+built with one particular dbm library or another, but not both, and
+you couldn't extend this mechanism to other packages or types of variables.
+.PP
+Now you can.
+.PP
+The \fBtie()\fR function binds a variable to a class (package) that will provide
+the implementation for access methods for that variable.  Once this magic
+has been performed, accessing a tied variable automatically triggers
+method calls in the proper class.  The complexity of the class is
+hidden behind magic methods calls.  The method names are in ALL CAPS,
+which is a convention that Perl uses to indicate that they're called
+implicitly rather than explicitly\-\-just like the \fBBEGIN()\fR and \fBEND()\fR
+functions.
+.PP
+In the \fBtie()\fR call, \f(CW\*(C`VARIABLE\*(C'\fR is the name of the variable to be
+enchanted.  \f(CW\*(C`CLASSNAME\*(C'\fR is the name of a class implementing objects of
+the correct type.  Any additional arguments in the \f(CW\*(C`LIST\*(C'\fR are passed to
+the appropriate constructor method for that class\-\-meaning \fBTIESCALAR()\fR,
+\&\fBTIEARRAY()\fR, \fBTIEHASH()\fR, or \fBTIEHANDLE()\fR.  (Typically these are arguments
+such as might be passed to the \fBdbminit()\fR function of C.) The object
+returned by the "new" method is also returned by the \fBtie()\fR function,
+which would be useful if you wanted to access other methods in
+\&\f(CW\*(C`CLASSNAME\*(C'\fR. (You don't actually have to return a reference to a right
+"type" (e.g., HASH or \f(CW\*(C`CLASSNAME\*(C'\fR) so long as it's a properly blessed
+object.)  You can also retrieve a reference to the underlying object
+using the \fBtied()\fR function.
+.PP
+Unlike \fBdbmopen()\fR, the \fBtie()\fR function will not \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR a module
+for you\-\-you need to do that explicitly yourself.
+.SS "Tying Scalars"
+.IX Xref "scalar, tying"
+.IX Subsection "Tying Scalars"
+A class implementing a tied scalar should define the following methods:
+TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
+.PP
+Let's look at each in turn, using as an example a tie class for
+scalars that allows the user to do something like:
+.PP
+.Vb 2
+\&    tie $his_speed, \*(AqNice\*(Aq, getppid();
+\&    tie $my_speed,  \*(AqNice\*(Aq, $$;
+.Ve
+.PP
+And now whenever either of those variables is accessed, its current
+system priority is retrieved and returned.  If those variables are set,
+then the process's priority is changed!
+.PP
+We'll use Jarkko Hietaniemi <\fIjhi@iki.fi\fR>'s BSD::Resource class (not
+included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants
+from your system, as well as the \fBgetpriority()\fR and \fBsetpriority()\fR system
+calls.  Here's the preamble of the class.
+.PP
+.Vb 5
+\&    package Nice;
+\&    use Carp;
+\&    use BSD::Resource;
+\&    use strict;
+\&    $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
+.Ve
+.IP "TIESCALAR classname, LIST" 4
+.IX Xref "TIESCALAR"
+.IX Item "TIESCALAR classname, LIST"
+This is the constructor for the class.  That means it is
+expected to return a blessed reference to a new scalar
+(probably anonymous) that it's creating.  For example:
+.Sp
+.Vb 3
+\& sub TIESCALAR {
+\&     my $class = shift;
+\&     my $pid = shift || $$; # 0 means me
+\&
+\&     if ($pid !~ /^\ed+$/) {
+\&         carp "Nice::Tie::Scalar got non\-numeric pid $pid" if $^W;
+\&         return undef;
+\&     }
+\&
+\&     unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
+\&         carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
+\&         return undef;
+\&     }
+\&
+\&     return bless \e$pid, $class;
+\& }
+.Ve
+.Sp
+This tie class has chosen to return an error rather than raising an
+exception if its constructor should fail.  While this is how \fBdbmopen()\fR works,
+other classes may well not wish to be so forgiving.  It checks the global
+variable \f(CW$^W\fR to see whether to emit a bit of noise anyway.
+.IP "FETCH this" 4
+.IX Xref "FETCH"
+.IX Item "FETCH this"
+This method will be triggered every time the tied variable is accessed
+(read).  It takes no arguments beyond its self reference, which is the
+object representing the scalar we're dealing with.  Because in this case
+we're using just a SCALAR ref for the tied scalar object, a simple $$self
+allows the method to get at the real value stored there.  In our example
+below, that real value is the process ID to which we've tied our variable.
+.Sp
+.Vb 10
+\&    sub FETCH {
+\&        my $self = shift;
+\&        confess "wrong type" unless ref $self;
+\&        croak "usage error" if @_;
+\&        my $nicety;
+\&        local($!) = 0;
+\&        $nicety = getpriority(PRIO_PROCESS, $$self);
+\&        if ($!) { croak "getpriority failed: $!" }
+\&        return $nicety;
+\&    }
+.Ve
+.Sp
+This time we've decided to blow up (raise an exception) if the renice
+fails\-\-there's no place for us to return an error otherwise, and it's
+probably the right thing to do.
+.IP "STORE this, value" 4
+.IX Xref "STORE"
+.IX Item "STORE this, value"
+This method will be triggered every time the tied variable is set
+(assigned).  Beyond its self reference, it also expects one (and only one)
+argument: the new value the user is trying to assign. Don't worry about
+returning a value from STORE; the semantic of assignment returning the
+assigned value is implemented with FETCH.
+.Sp
+.Vb 5
+\& sub STORE {
+\&     my $self = shift;
+\&     confess "wrong type" unless ref $self;
+\&     my $new_nicety = shift;
+\&     croak "usage error" if @_;
+\&
+\&     if ($new_nicety < PRIO_MIN) {
+\&         carp sprintf
+\&           "WARNING: priority %d less than minimum system priority %d",
+\&               $new_nicety, PRIO_MIN if $^W;
+\&         $new_nicety = PRIO_MIN;
+\&     }
+\&
+\&     if ($new_nicety > PRIO_MAX) {
+\&         carp sprintf
+\&           "WARNING: priority %d greater than maximum system priority %d",
+\&               $new_nicety, PRIO_MAX if $^W;
+\&         $new_nicety = PRIO_MAX;
+\&     }
+\&
+\&     unless (defined setpriority(PRIO_PROCESS,
+\&                                 $$self,
+\&                                 $new_nicety))
+\&     {
+\&         confess "setpriority failed: $!";
+\&     }
+\& }
+.Ve
+.IP "UNTIE this" 4
+.IX Xref "UNTIE"
+.IX Item "UNTIE this"
+This method will be triggered when the \f(CW\*(C`untie\*(C'\fR occurs. This can be useful
+if the class needs to know when no further calls will be made. (Except DESTROY
+of course.) See "The \f(CW\*(C`untie\*(C'\fR Gotcha" below for more details.
+.IP "DESTROY this" 4
+.IX Xref "DESTROY"
+.IX Item "DESTROY this"
+This method will be triggered when the tied variable needs to be destructed.
+As with other object classes, such a method is seldom necessary, because Perl
+deallocates its moribund object's memory for you automatically\-\-this isn't
+C++, you know.  We'll use a DESTROY method here for debugging purposes only.
+.Sp
+.Vb 5
+\&    sub DESTROY {
+\&        my $self = shift;
+\&        confess "wrong type" unless ref $self;
+\&        carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
+\&    }
+.Ve
+.PP
+That's about all there is to it.  Actually, it's more than all there
+is to it, because we've done a few nice things here for the sake
+of completeness, robustness, and general aesthetics.  Simpler
+TIESCALAR classes are certainly possible.
+.SS "Tying Arrays"
+.IX Xref "array, tying"
+.IX Subsection "Tying Arrays"
+A class implementing a tied ordinary array should define the following
+methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR
+and perhaps UNTIE and/or DESTROY.
+.PP
+FETCHSIZE and STORESIZE are used to provide \f(CW$#array\fR and
+equivalent \f(CWscalar(@array)\fR access.
+.PP
+The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
+required if the perl operator with the corresponding (but lowercase) name
+is to operate on the tied array. The \fBTie::Array\fR class can be used as a
+base class to implement the first five of these in terms of the basic
+methods above.  The default implementations of DELETE and EXISTS in
+\&\fBTie::Array\fR simply \f(CW\*(C`croak\*(C'\fR.
+.PP
+In addition EXTEND will be called when perl would have pre-extended
+allocation in a real array.
+.PP
+For this discussion, we'll implement an array whose elements are a fixed
+size at creation.  If you try to create an element larger than the fixed
+size, you'll take an exception.  For example:
+.PP
+.Vb 4
+\&    use FixedElem_Array;
+\&    tie @array, \*(AqFixedElem_Array\*(Aq, 3;
+\&    $array[0] = \*(Aqcat\*(Aq;  # ok.
+\&    $array[1] = \*(Aqdogs\*(Aq; # exception, length(\*(Aqdogs\*(Aq) > 3.
+.Ve
+.PP
+The preamble code for the class is as follows:
+.PP
+.Vb 3
+\&    package FixedElem_Array;
+\&    use Carp;
+\&    use strict;
+.Ve
+.IP "TIEARRAY classname, LIST" 4
+.IX Xref "TIEARRAY"
+.IX Item "TIEARRAY classname, LIST"
+This is the constructor for the class.  That means it is expected to
+return a blessed reference through which the new array (probably an
+anonymous ARRAY ref) will be accessed.
+.Sp
+In our example, just to show you that you don't \fIreally\fR have to return an
+ARRAY reference, we'll choose a HASH reference to represent our object.
+A HASH works out well as a generic record type: the \f(CW\*(C`{ELEMSIZE}\*(C'\fR field will
+store the maximum element size allowed, and the \f(CW\*(C`{ARRAY}\*(C'\fR field will hold the
+true ARRAY ref.  If someone outside the class tries to dereference the
+object returned (doubtless thinking it an ARRAY ref), they'll blow up.
+This just goes to show you that you should respect an object's privacy.
+.Sp
+.Vb 11
+\&    sub TIEARRAY {
+\&      my $class    = shift;
+\&      my $elemsize = shift;
+\&      if ( @_ || $elemsize =~ /\eD/ ) {
+\&        croak "usage: tie ARRAY, \*(Aq" . _\|_PACKAGE_\|_ . "\*(Aq, elem_size";
+\&      }
+\&      return bless {
+\&        ELEMSIZE => $elemsize,
+\&        ARRAY    => [],
+\&      }, $class;
+\&    }
+.Ve
+.IP "FETCH this, index" 4
+.IX Xref "FETCH"
+.IX Item "FETCH this, index"
+This method will be triggered every time an individual element the tied array
+is accessed (read).  It takes one argument beyond its self reference: the
+index whose value we're trying to fetch.
+.Sp
+.Vb 5
+\&    sub FETCH {
+\&      my $self  = shift;
+\&      my $index = shift;
+\&      return $self\->{ARRAY}\->[$index];
+\&    }
+.Ve
+.Sp
+If a negative array index is used to read from an array, the index
+will be translated to a positive one internally by calling FETCHSIZE
+before being passed to FETCH.  You may disable this feature by
+assigning a true value to the variable \f(CW$NEGATIVE_INDICES\fR in the
+tied array class.
+.Sp
+As you may have noticed, the name of the FETCH method (et al.) is the same
+for all accesses, even though the constructors differ in names (TIESCALAR
+vs TIEARRAY).  While in theory you could have the same class servicing
+several tied types, in practice this becomes cumbersome, and it's easiest
+to keep them at simply one tie type per class.
+.IP "STORE this, index, value" 4
+.IX Xref "STORE"
+.IX Item "STORE this, index, value"
+This method will be triggered every time an element in the tied array is set
+(written).  It takes two arguments beyond its self reference: the index at
+which we're trying to store something and the value we're trying to put
+there.
+.Sp
+In our example, \f(CW\*(C`undef\*(C'\fR is really \f(CW\*(C`$self\->{ELEMSIZE}\*(C'\fR number of
+spaces so we have a little more work to do here:
+.Sp
+.Vb 11
+\& sub STORE {
+\&   my $self = shift;
+\&   my( $index, $value ) = @_;
+\&   if ( length $value > $self\->{ELEMSIZE} ) {
+\&     croak "length of $value is greater than $self\->{ELEMSIZE}";
+\&   }
+\&   # fill in the blanks
+\&   $self\->STORESIZE( $index ) if $index > $self\->FETCHSIZE();
+\&   # right justify to keep element size for smaller elements
+\&   $self\->{ARRAY}\->[$index] = sprintf "%$self\->{ELEMSIZE}s", $value;
+\& }
+.Ve
+.Sp
+Negative indexes are treated the same as with FETCH.
+.IP "FETCHSIZE this" 4
+.IX Xref "FETCHSIZE"
+.IX Item "FETCHSIZE this"
+Returns the total number of items in the tied array associated with
+object \fIthis\fR. (Equivalent to \f(CWscalar(@array)\fR).  For example:
+.Sp
+.Vb 4
+\&    sub FETCHSIZE {
+\&      my $self = shift;
+\&      return scalar $self\->{ARRAY}\->@*;
+\&    }
+.Ve
+.IP "STORESIZE this, count" 4
+.IX Xref "STORESIZE"
+.IX Item "STORESIZE this, count"
+Sets the total number of items in the tied array associated with
+object \fIthis\fR to be \fIcount\fR. If this makes the array larger then
+class's mapping of \f(CW\*(C`undef\*(C'\fR should be returned for new positions.
+If the array becomes smaller then entries beyond count should be
+deleted.
+.Sp
+In our example, 'undef' is really an element containing
+\&\f(CW\*(C`$self\->{ELEMSIZE}\*(C'\fR number of spaces.  Observe:
+.Sp
+.Vb 10
+\&    sub STORESIZE {
+\&      my $self  = shift;
+\&      my $count = shift;
+\&      if ( $count > $self\->FETCHSIZE() ) {
+\&        foreach ( $count \- $self\->FETCHSIZE() .. $count ) {
+\&          $self\->STORE( $_, \*(Aq\*(Aq );
+\&        }
+\&      } elsif ( $count < $self\->FETCHSIZE() ) {
+\&        foreach ( 0 .. $self\->FETCHSIZE() \- $count \- 2 ) {
+\&          $self\->POP();
+\&        }
+\&      }
+\&    }
+.Ve
+.IP "EXTEND this, count" 4
+.IX Xref "EXTEND"
+.IX Item "EXTEND this, count"
+Informative call that array is likely to grow to have \fIcount\fR entries.
+Can be used to optimize allocation. This method need do nothing.
+.Sp
+In our example there is no reason to implement this method, so we leave
+it as a no-op. This method is only relevant to tied array implementations
+where there is the possibility of having the allocated size of the array
+be larger than is visible to a perl programmer inspecting the size of the
+array. Many tied array implementations will have no reason to implement it.
+.Sp
+.Vb 5
+\&    sub EXTEND {   
+\&      my $self  = shift;
+\&      my $count = shift;
+\&      # nothing to see here, move along.
+\&    }
+.Ve
+.Sp
+\&\fBNOTE:\fR It is generally an error to make this equivalent to STORESIZE.
+Perl may from time to time call EXTEND without wanting to actually change
+the array size directly. Any tied array should function correctly if this
+method is a no-op, even if perhaps they might not be as efficient as they
+would if this method was implemented.
+.IP "EXISTS this, key" 4
+.IX Xref "EXISTS"
+.IX Item "EXISTS this, key"
+Verify that the element at index \fIkey\fR exists in the tied array \fIthis\fR.
+.Sp
+In our example, we will determine that if an element consists of
+\&\f(CW\*(C`$self\->{ELEMSIZE}\*(C'\fR spaces only, it does not exist:
+.Sp
+.Vb 7
+\& sub EXISTS {
+\&   my $self  = shift;
+\&   my $index = shift;
+\&   return 0 if ! defined $self\->{ARRAY}\->[$index] ||
+\&               $self\->{ARRAY}\->[$index] eq \*(Aq \*(Aq x $self\->{ELEMSIZE};
+\&   return 1;
+\& }
+.Ve
+.IP "DELETE this, key" 4
+.IX Xref "DELETE"
+.IX Item "DELETE this, key"
+Delete the element at index \fIkey\fR from the tied array \fIthis\fR.
+.Sp
+In our example, a deleted item is \f(CW\*(C`$self\->{ELEMSIZE}\*(C'\fR spaces:
+.Sp
+.Vb 5
+\&    sub DELETE {
+\&      my $self  = shift;
+\&      my $index = shift;
+\&      return $self\->STORE( $index, \*(Aq\*(Aq );
+\&    }
+.Ve
+.IP "CLEAR this" 4
+.IX Xref "CLEAR"
+.IX Item "CLEAR this"
+Clear (remove, delete, ...) all values from the tied array associated with
+object \fIthis\fR.  For example:
+.Sp
+.Vb 4
+\&    sub CLEAR {
+\&      my $self = shift;
+\&      return $self\->{ARRAY} = [];
+\&    }
+.Ve
+.IP "PUSH this, LIST" 4
+.IX Xref "PUSH"
+.IX Item "PUSH this, LIST"
+Append elements of \fILIST\fR to the array.  For example:
+.Sp
+.Vb 7
+\&    sub PUSH {  
+\&      my $self = shift;
+\&      my @list = @_;
+\&      my $last = $self\->FETCHSIZE();
+\&      $self\->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
+\&      return $self\->FETCHSIZE();
+\&    }
+.Ve
+.IP "POP this" 4
+.IX Xref "POP"
+.IX Item "POP this"
+Remove last element of the array and return it.  For example:
+.Sp
+.Vb 4
+\&    sub POP {
+\&      my $self = shift;
+\&      return pop $self\->{ARRAY}\->@*;
+\&    }
+.Ve
+.IP "SHIFT this" 4
+.IX Xref "SHIFT"
+.IX Item "SHIFT this"
+Remove the first element of the array (shifting other elements down)
+and return it.  For example:
+.Sp
+.Vb 4
+\&    sub SHIFT {
+\&      my $self = shift;
+\&      return shift $self\->{ARRAY}\->@*;
+\&    }
+.Ve
+.IP "UNSHIFT this, LIST" 4
+.IX Xref "UNSHIFT"
+.IX Item "UNSHIFT this, LIST"
+Insert LIST elements at the beginning of the array, moving existing elements
+up to make room.  For example:
+.Sp
+.Vb 9
+\&    sub UNSHIFT {
+\&      my $self = shift;
+\&      my @list = @_;
+\&      my $size = scalar( @list );
+\&      # make room for our list
+\&      $self\->{ARRAY}[ $size .. $self\->{ARRAY}\->$#* + $size ]\->@*
+\&       = $self\->{ARRAY}\->@*
+\&      $self\->STORE( $_, $list[$_] ) foreach 0 .. $#list;
+\&    }
+.Ve
+.IP "SPLICE this, offset, length, LIST" 4
+.IX Xref "SPLICE"
+.IX Item "SPLICE this, offset, length, LIST"
+Perform the equivalent of \f(CW\*(C`splice\*(C'\fR on the array.
+.Sp
+\&\fIoffset\fR is optional and defaults to zero, negative values count back 
+from the end of the array.
+.Sp
+\&\fIlength\fR is optional and defaults to rest of the array.
+.Sp
+\&\fILIST\fR may be empty.
+.Sp
+Returns a list of the original \fIlength\fR elements at \fIoffset\fR.
+.Sp
+In our example, we'll use a little shortcut if there is a \fILIST\fR:
+.Sp
+.Vb 11
+\&    sub SPLICE {
+\&      my $self   = shift;
+\&      my $offset = shift || 0;
+\&      my $length = shift || $self\->FETCHSIZE() \- $offset;
+\&      my @list   = (); 
+\&      if ( @_ ) {
+\&        tie @list, _\|_PACKAGE_\|_, $self\->{ELEMSIZE};
+\&        @list   = @_;
+\&      }
+\&      return splice $self\->{ARRAY}\->@*, $offset, $length, @list;
+\&    }
+.Ve
+.IP "UNTIE this" 4
+.IX Xref "UNTIE"
+.IX Item "UNTIE this"
+Will be called when \f(CW\*(C`untie\*(C'\fR happens. (See "The \f(CW\*(C`untie\*(C'\fR Gotcha" below.)
+.IP "DESTROY this" 4
+.IX Xref "DESTROY"
+.IX Item "DESTROY this"
+This method will be triggered when the tied variable needs to be destructed.
+As with the scalar tie class, this is almost never needed in a
+language that does its own garbage collection, so this time we'll
+just leave it out.
+.SS "Tying Hashes"
+.IX Xref "hash, tying"
+.IX Subsection "Tying Hashes"
+Hashes were the first Perl data type to be tied (see \fBdbmopen()\fR).  A class
+implementing a tied hash should define the following methods: TIEHASH is
+the constructor.  FETCH and STORE access the key and value pairs.  EXISTS
+reports whether a key is present in the hash, and DELETE deletes one.
+CLEAR empties the hash by deleting all the key and value pairs.  FIRSTKEY
+and NEXTKEY implement the \fBkeys()\fR and \fBeach()\fR functions to iterate over all
+the keys. SCALAR is triggered when the tied hash is evaluated in scalar 
+context, and in 5.28 onwards, by \f(CW\*(C`keys\*(C'\fR in boolean context. UNTIE is
+called when \f(CW\*(C`untie\*(C'\fR happens, and DESTROY is called when the tied variable
+is garbage collected.
+.PP
+If this seems like a lot, then feel free to inherit from merely the
+standard Tie::StdHash module for most of your methods, redefining only the
+interesting ones.  See Tie::Hash for details.
+.PP
+Remember that Perl distinguishes between a key not existing in the hash,
+and the key existing in the hash but having a corresponding value of
+\&\f(CW\*(C`undef\*(C'\fR.  The two possibilities can be tested with the \f(CWexists()\fR and
+\&\f(CWdefined()\fR functions.
+.PP
+Here's an example of a somewhat interesting tied hash class:  it gives you
+a hash representing a particular user's dot files.  You index into the hash
+with the name of the file (minus the dot) and you get back that dot file's
+contents.  For example:
+.PP
+.Vb 8
+\&    use DotFiles;
+\&    tie %dot, \*(AqDotFiles\*(Aq;
+\&    if ( $dot{profile} =~ /MANPATH/ ||
+\&         $dot{login}   =~ /MANPATH/ ||
+\&         $dot{cshrc}   =~ /MANPATH/    )
+\&    {
+\&        print "you seem to set your MANPATH\en";
+\&    }
+.Ve
+.PP
+Or here's another sample of using our tied class:
+.PP
+.Vb 5
+\&    tie %him, \*(AqDotFiles\*(Aq, \*(Aqdaemon\*(Aq;
+\&    foreach $f ( keys %him ) {
+\&        printf "daemon dot file %s is size %d\en",
+\&            $f, length $him{$f};
+\&    }
+.Ve
+.PP
+In our tied hash DotFiles example, we use a regular
+hash for the object containing several important
+fields, of which only the \f(CW\*(C`{LIST}\*(C'\fR field will be what the
+user thinks of as the real hash.
+.IP USER 5
+.IX Item "USER"
+whose dot files this object represents
+.IP HOME 5
+.IX Item "HOME"
+where those dot files live
+.IP CLOBBER 5
+.IX Item "CLOBBER"
+whether we should try to change or remove those dot files
+.IP LIST 5
+.IX Item "LIST"
+the hash of dot file names and content mappings
+.PP
+Here's the start of \fIDotfiles.pm\fR:
+.PP
+.Vb 5
+\&    package DotFiles;
+\&    use Carp;
+\&    sub whowasi { (caller(1))[3] . \*(Aq()\*(Aq }
+\&    my $DEBUG = 0;
+\&    sub debug { $DEBUG = @_ ? shift : 1 }
+.Ve
+.PP
+For our example, we want to be able to emit debugging info to help in tracing
+during development.  We keep also one convenience function around
+internally to help print out warnings; \fBwhowasi()\fR returns the function name
+that calls it.
+.PP
+Here are the methods for the DotFiles tied hash.
+.IP "TIEHASH classname, LIST" 4
+.IX Xref "TIEHASH"
+.IX Item "TIEHASH classname, LIST"
+This is the constructor for the class.  That means it is expected to
+return a blessed reference through which the new object (probably but not
+necessarily an anonymous hash) will be accessed.
+.Sp
+Here's the constructor:
+.Sp
+.Vb 9
+\&    sub TIEHASH {
+\&        my $class = shift;
+\&        my $user = shift || $>;
+\&        my $dotdir = shift || \*(Aq\*(Aq;
+\&        croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
+\&        $user = getpwuid($user) if $user =~ /^\ed+$/;
+\&        my $dir = (getpwnam($user))[7]
+\&                || croak "@{[&whowasi]}: no user $user";
+\&        $dir .= "/$dotdir" if $dotdir;
+\&
+\&        my $node = {
+\&            USER    => $user,
+\&            HOME    => $dir,
+\&            LIST    => {},
+\&            CLOBBER => 0,
+\&        };
+\&
+\&        opendir(DIR, $dir)
+\&                || croak "@{[&whowasi]}: can\*(Aqt opendir $dir: $!";
+\&        foreach $dot ( grep /^\e./ && \-f "$dir/$_", readdir(DIR)) {
+\&            $dot =~ s/^\e.//;
+\&            $node\->{LIST}{$dot} = undef;
+\&        }
+\&        closedir DIR;
+\&        return bless $node, $class;
+\&    }
+.Ve
+.Sp
+It's probably worth mentioning that if you're going to filetest the
+return values out of a readdir, you'd better prepend the directory
+in question.  Otherwise, because we didn't \fBchdir()\fR there, it would
+have been testing the wrong file.
+.IP "FETCH this, key" 4
+.IX Xref "FETCH"
+.IX Item "FETCH this, key"
+This method will be triggered every time an element in the tied hash is
+accessed (read).  It takes one argument beyond its self reference: the key
+whose value we're trying to fetch.
+.Sp
+Here's the fetch for our DotFiles example.
+.Sp
+.Vb 6
+\&    sub FETCH {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        my $dot = shift;
+\&        my $dir = $self\->{HOME};
+\&        my $file = "$dir/.$dot";
+\&
+\&        unless (exists $self\->{LIST}\->{$dot} || \-f $file) {
+\&            carp "@{[&whowasi]}: no $dot file" if $DEBUG;
+\&            return undef;
+\&        }
+\&
+\&        if (defined $self\->{LIST}\->{$dot}) {
+\&            return $self\->{LIST}\->{$dot};
+\&        } else {
+\&            return $self\->{LIST}\->{$dot} = \`cat $dir/.$dot\`;
+\&        }
+\&    }
+.Ve
+.Sp
+It was easy to write by having it call the Unix \fBcat\fR\|(1) command, but it
+would probably be more portable to open the file manually (and somewhat
+more efficient).  Of course, because dot files are a Unixy concept, we're
+not that concerned.
+.IP "STORE this, key, value" 4
+.IX Xref "STORE"
+.IX Item "STORE this, key, value"
+This method will be triggered every time an element in the tied hash is set
+(written).  It takes two arguments beyond its self reference: the index at
+which we're trying to store something, and the value we're trying to put
+there.
+.Sp
+Here in our DotFiles example, we'll be careful not to let
+them try to overwrite the file unless they've called the \fBclobber()\fR
+method on the original object reference returned by \fBtie()\fR.
+.Sp
+.Vb 7
+\&    sub STORE {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        my $dot = shift;
+\&        my $value = shift;
+\&        my $file = $self\->{HOME} . "/.$dot";
+\&        my $user = $self\->{USER};
+\&
+\&        croak "@{[&whowasi]}: $file not clobberable"
+\&            unless $self\->{CLOBBER};
+\&
+\&        open(my $f, \*(Aq>\*(Aq, $file) || croak "can\*(Aqt open $file: $!";
+\&        print $f $value;
+\&        close($f);
+\&    }
+.Ve
+.Sp
+If they wanted to clobber something, they might say:
+.Sp
+.Vb 3
+\&    $ob = tie %daemon_dots, \*(Aqdaemon\*(Aq;
+\&    $ob\->clobber(1);
+\&    $daemon_dots{signature} = "A true daemon\en";
+.Ve
+.Sp
+Another way to lay hands on a reference to the underlying object is to
+use the \fBtied()\fR function, so they might alternately have set clobber
+using:
+.Sp
+.Vb 2
+\&    tie %daemon_dots, \*(Aqdaemon\*(Aq;
+\&    tied(%daemon_dots)\->clobber(1);
+.Ve
+.Sp
+The clobber method is simply:
+.Sp
+.Vb 4
+\&    sub clobber {
+\&        my $self = shift;
+\&        $self\->{CLOBBER} = @_ ? shift : 1;
+\&    }
+.Ve
+.IP "DELETE this, key" 4
+.IX Xref "DELETE"
+.IX Item "DELETE this, key"
+This method is triggered when we remove an element from the hash,
+typically by using the \fBdelete()\fR function.  Again, we'll
+be careful to check whether they really want to clobber files.
+.Sp
+.Vb 2
+\& sub DELETE   {
+\&     carp &whowasi if $DEBUG;
+\&
+\&     my $self = shift;
+\&     my $dot = shift;
+\&     my $file = $self\->{HOME} . "/.$dot";
+\&     croak "@{[&whowasi]}: won\*(Aqt remove file $file"
+\&         unless $self\->{CLOBBER};
+\&     delete $self\->{LIST}\->{$dot};
+\&     my $success = unlink($file);
+\&     carp "@{[&whowasi]}: can\*(Aqt unlink $file: $!" unless $success;
+\&     $success;
+\& }
+.Ve
+.Sp
+The value returned by DELETE becomes the return value of the call
+to \fBdelete()\fR.  If you want to emulate the normal behavior of \fBdelete()\fR,
+you should return whatever FETCH would have returned for this key.
+In this example, we have chosen instead to return a value which tells
+the caller whether the file was successfully deleted.
+.IP "CLEAR this" 4
+.IX Xref "CLEAR"
+.IX Item "CLEAR this"
+This method is triggered when the whole hash is to be cleared, usually by
+assigning the empty list to it.
+.Sp
+In our example, that would remove all the user's dot files!  It's such a
+dangerous thing that they'll have to set CLOBBER to something higher than
+1 to make it happen.
+.Sp
+.Vb 10
+\& sub CLEAR    {
+\&     carp &whowasi if $DEBUG;
+\&     my $self = shift;
+\&     croak "@{[&whowasi]}: won\*(Aqt remove all dot files for $self\->{USER}"
+\&         unless $self\->{CLOBBER} > 1;
+\&     my $dot;
+\&     foreach $dot ( keys $self\->{LIST}\->%* ) {
+\&         $self\->DELETE($dot);
+\&     }
+\& }
+.Ve
+.IP "EXISTS this, key" 4
+.IX Xref "EXISTS"
+.IX Item "EXISTS this, key"
+This method is triggered when the user uses the \fBexists()\fR function
+on a particular hash.  In our example, we'll look at the \f(CW\*(C`{LIST}\*(C'\fR
+hash element for this:
+.Sp
+.Vb 6
+\&    sub EXISTS   {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        my $dot = shift;
+\&        return exists $self\->{LIST}\->{$dot};
+\&    }
+.Ve
+.IP "FIRSTKEY this" 4
+.IX Xref "FIRSTKEY"
+.IX Item "FIRSTKEY this"
+This method will be triggered when the user is going
+to iterate through the hash, such as via a \fBkeys()\fR, \fBvalues()\fR, or \fBeach()\fR call.
+.Sp
+.Vb 6
+\&    sub FIRSTKEY {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        my $a = keys $self\->{LIST}\->%*;  # reset each() iterator
+\&        each $self\->{LIST}\->%*
+\&    }
+.Ve
+.Sp
+FIRSTKEY is always called in scalar context and it should just
+return the first key.  \fBvalues()\fR, and \fBeach()\fR in list context,
+will call FETCH for the returned keys.
+.IP "NEXTKEY this, lastkey" 4
+.IX Xref "NEXTKEY"
+.IX Item "NEXTKEY this, lastkey"
+This method gets triggered during a \fBkeys()\fR, \fBvalues()\fR, or \fBeach()\fR iteration.  It has a
+second argument which is the last key that had been accessed.  This is
+useful if you're caring about ordering or calling the iterator from more
+than one sequence, or not really storing things in a hash anywhere.
+.Sp
+NEXTKEY is always called in scalar context and it should just
+return the next key.  \fBvalues()\fR, and \fBeach()\fR in list context,
+will call FETCH for the returned keys.
+.Sp
+For our example, we're using a real hash so we'll do just the simple
+thing, but we'll have to go through the LIST field indirectly.
+.Sp
+.Vb 5
+\&    sub NEXTKEY  {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        return each $self\->{LIST}\->%*
+\&    }
+.Ve
+.Sp
+If the object underlying your tied hash isn't a real hash and you don't have
+\&\f(CW\*(C`each\*(C'\fR available, then you should return \f(CW\*(C`undef\*(C'\fR or the empty list once you've
+reached the end of your list of keys. See \f(CW\*(C`each\*(Aqs own documentation\*(C'\fR
+for more details.
+.IP "SCALAR this" 4
+.IX Xref "SCALAR"
+.IX Item "SCALAR this"
+This is called when the hash is evaluated in scalar context, and in 5.28
+onwards, by \f(CW\*(C`keys\*(C'\fR in boolean context. In order to mimic the behaviour of
+untied hashes, this method must return a value which when used as boolean,
+indicates whether the tied hash is considered empty. If this method does
+not exist, perl will make some educated guesses and return true when
+the hash is inside an iteration. If this isn't the case, FIRSTKEY is
+called, and the result will be a false value if FIRSTKEY returns the empty
+list, true otherwise.
+.Sp
+However, you should \fBnot\fR blindly rely on perl always doing the right 
+thing. Particularly, perl will mistakenly return true when you clear the 
+hash by repeatedly calling DELETE until it is empty. You are therefore 
+advised to supply your own SCALAR method when you want to be absolutely 
+sure that your hash behaves nicely in scalar context.
+.Sp
+In our example we can just call \f(CW\*(C`scalar\*(C'\fR on the underlying hash
+referenced by \f(CW\*(C`$self\->{LIST}\*(C'\fR:
+.Sp
+.Vb 5
+\&    sub SCALAR {
+\&        carp &whowasi if $DEBUG;
+\&        my $self = shift;
+\&        return scalar $self\->{LIST}\->%*
+\&    }
+.Ve
+.Sp
+NOTE: In perl 5.25 the behavior of scalar \f(CW%hash\fR on an untied hash changed
+to return the count of keys. Prior to this it returned a string containing
+information about the bucket setup of the hash. See
+"bucket_ratio" in Hash::Util for a backwards compatibility path.
+.IP "UNTIE this" 4
+.IX Xref "UNTIE"
+.IX Item "UNTIE this"
+This is called when \f(CW\*(C`untie\*(C'\fR occurs.  See "The \f(CW\*(C`untie\*(C'\fR Gotcha" below.
+.IP "DESTROY this" 4
+.IX Xref "DESTROY"
+.IX Item "DESTROY this"
+This method is triggered when a tied hash is about to go out of
+scope.  You don't really need it unless you're trying to add debugging
+or have auxiliary state to clean up.  Here's a very simple function:
+.Sp
+.Vb 3
+\&    sub DESTROY  {
+\&        carp &whowasi if $DEBUG;
+\&    }
+.Ve
+.PP
+Note that functions such as \fBkeys()\fR and \fBvalues()\fR may return huge lists
+when used on large objects, like DBM files.  You may prefer to use the
+\&\fBeach()\fR function to iterate over such.  Example:
+.PP
+.Vb 7
+\&    # print out history file offsets
+\&    use NDBM_File;
+\&    tie(%HIST, \*(AqNDBM_File\*(Aq, \*(Aq/usr/lib/news/history\*(Aq, 1, 0);
+\&    while (($key,$val) = each %HIST) {
+\&        print $key, \*(Aq = \*(Aq, unpack(\*(AqL\*(Aq,$val), "\en";
+\&    }
+\&    untie(%HIST);
+.Ve
+.SS "Tying FileHandles"
+.IX Xref "filehandle, tying"
+.IX Subsection "Tying FileHandles"
+This is partially implemented now.
+.PP
+A class implementing a tied filehandle should define the following
+methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
+READ, and possibly CLOSE, UNTIE and DESTROY.  The class can also provide: BINMODE,
+OPEN, EOF, FILENO, SEEK, TELL \- if the corresponding perl operators are
+used on the handle.
+.PP
+When STDERR is tied, its PRINT method will be called to issue warnings
+and error messages.  This feature is temporarily disabled during the call, 
+which means you can use \f(CWwarn()\fR inside PRINT without starting a recursive
+loop.  And just like \f(CW\*(C`_\|_WARN_\|_\*(C'\fR and \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handlers, STDERR's PRINT
+method may be called to report parser errors, so the caveats mentioned under 
+"%SIG" in perlvar apply.
+.PP
+All of this is especially useful when perl is embedded in some other 
+program, where output to STDOUT and STDERR may have to be redirected 
+in some special way.  See nvi and the Apache module for examples.
+.PP
+When tying a handle, the first argument to \f(CW\*(C`tie\*(C'\fR should begin with an
+asterisk.  So, if you are tying STDOUT, use \f(CW*STDOUT\fR.  If you have
+assigned it to a scalar variable, say \f(CW$handle\fR, use \f(CW*$handle\fR.
+\&\f(CW\*(C`tie $handle\*(C'\fR ties the scalar variable \f(CW$handle\fR, not the handle inside
+it.
+.PP
+In our example we're going to create a shouting handle.
+.PP
+.Vb 1
+\&    package Shout;
+.Ve
+.IP "TIEHANDLE classname, LIST" 4
+.IX Xref "TIEHANDLE"
+.IX Item "TIEHANDLE classname, LIST"
+This is the constructor for the class.  That means it is expected to
+return a blessed reference of some sort. The reference can be used to
+hold some internal information.
+.Sp
+.Vb 1
+\&    sub TIEHANDLE { print "<shout>\en"; my $i; bless \e$i, shift }
+.Ve
+.IP "WRITE this, LIST" 4
+.IX Xref "WRITE"
+.IX Item "WRITE this, LIST"
+This method will be called when the handle is written to via the
+\&\f(CW\*(C`syswrite\*(C'\fR function.
+.Sp
+.Vb 5
+\& sub WRITE {
+\&     $r = shift;
+\&     my($buf,$len,$offset) = @_;
+\&     print "WRITE called, \e$buf=$buf, \e$len=$len, \e$offset=$offset";
+\& }
+.Ve
+.IP "PRINT this, LIST" 4
+.IX Xref "PRINT"
+.IX Item "PRINT this, LIST"
+This method will be triggered every time the tied handle is printed to
+with the \f(CWprint()\fR or \f(CWsay()\fR functions.  Beyond its self reference
+it also expects the list that was passed to the print function.
+.Sp
+.Vb 1
+\&  sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\e }
+.Ve
+.Sp
+\&\f(CWsay()\fR acts just like \f(CWprint()\fR except $\e will be localized to \f(CW\*(C`\en\*(C'\fR so
+you need do nothing special to handle \f(CWsay()\fR in \f(CWPRINT()\fR.
+.IP "PRINTF this, LIST" 4
+.IX Xref "PRINTF"
+.IX Item "PRINTF this, LIST"
+This method will be triggered every time the tied handle is printed to
+with the \f(CWprintf()\fR function.
+Beyond its self reference it also expects the format and list that was
+passed to the printf function.
+.Sp
+.Vb 5
+\&    sub PRINTF {
+\&        shift;
+\&        my $fmt = shift;
+\&        print sprintf($fmt, @_);
+\&    }
+.Ve
+.IP "READ this, LIST" 4
+.IX Xref "READ"
+.IX Item "READ this, LIST"
+This method will be called when the handle is read from via the \f(CW\*(C`read\*(C'\fR
+or \f(CW\*(C`sysread\*(C'\fR functions.
+.Sp
+.Vb 8
+\& sub READ {
+\&   my $self = shift;
+\&   my $bufref = \e$_[0];
+\&   my(undef,$len,$offset) = @_;
+\&   print "READ called, \e$buf=$bufref, \e$len=$len, \e$offset=$offset";
+\&   # add to $$bufref, set $len to number of characters read
+\&   $len;
+\& }
+.Ve
+.IP "READLINE this" 4
+.IX Xref "READLINE"
+.IX Item "READLINE this"
+This method is called when the handle is read via \f(CW\*(C`<HANDLE>\*(C'\fR
+or \f(CW\*(C`readline HANDLE\*(C'\fR.
+.Sp
+As per \f(CW\*(C`readline\*(C'\fR, in scalar context it should return
+the next line, or \f(CW\*(C`undef\*(C'\fR for no more data.  In list context it should
+return all remaining lines, or an empty list for no more data.  The strings
+returned should include the input record separator \f(CW$/\fR (see perlvar),
+unless it is \f(CW\*(C`undef\*(C'\fR (which means "slurp" mode).
+.Sp
+.Vb 10
+\&    sub READLINE {
+\&      my $r = shift;
+\&      if (wantarray) {
+\&        return ("all remaining\en",
+\&                "lines up\en",
+\&                "to eof\en");
+\&      } else {
+\&        return "READLINE called " . ++$$r . " times\en";
+\&      }
+\&    }
+.Ve
+.IP "GETC this" 4
+.IX Xref "GETC"
+.IX Item "GETC this"
+This method will be called when the \f(CW\*(C`getc\*(C'\fR function is called.
+.Sp
+.Vb 1
+\&    sub GETC { print "Don\*(Aqt GETC, Get Perl"; return "a"; }
+.Ve
+.IP "EOF this" 4
+.IX Xref "EOF"
+.IX Item "EOF this"
+This method will be called when the \f(CW\*(C`eof\*(C'\fR function is called.
+.Sp
+Starting with Perl 5.12, an additional integer parameter will be passed.  It
+will be zero if \f(CW\*(C`eof\*(C'\fR is called without parameter; \f(CW1\fR if \f(CW\*(C`eof\*(C'\fR is given
+a filehandle as a parameter, e.g. \f(CWeof(FH)\fR; and \f(CW2\fR in the very special
+case that the tied filehandle is \f(CW\*(C`ARGV\*(C'\fR and \f(CW\*(C`eof\*(C'\fR is called with an empty
+parameter list, e.g. \f(CWeof()\fR.
+.Sp
+.Vb 1
+\&    sub EOF { not length $stringbuf }
+.Ve
+.IP "CLOSE this" 4
+.IX Xref "CLOSE"
+.IX Item "CLOSE this"
+This method will be called when the handle is closed via the \f(CW\*(C`close\*(C'\fR
+function.
+.Sp
+.Vb 1
+\&    sub CLOSE { print "CLOSE called.\en" }
+.Ve
+.IP "UNTIE this" 4
+.IX Xref "UNTIE"
+.IX Item "UNTIE this"
+As with the other types of ties, this method will be called when \f(CW\*(C`untie\*(C'\fR happens.
+It may be appropriate to "auto CLOSE" when this occurs.  See
+"The \f(CW\*(C`untie\*(C'\fR Gotcha" below.
+.IP "DESTROY this" 4
+.IX Xref "DESTROY"
+.IX Item "DESTROY this"
+As with the other types of ties, this method will be called when the
+tied handle is about to be destroyed. This is useful for debugging and
+possibly cleaning up.
+.Sp
+.Vb 1
+\&    sub DESTROY { print "</shout>\en" }
+.Ve
+.PP
+Here's how to use our little example:
+.PP
+.Vb 5
+\&    tie(*FOO,\*(AqShout\*(Aq);
+\&    print FOO "hello\en";
+\&    $a = 4; $b = 6;
+\&    print FOO $a, " plus ", $b, " equals ", $a + $b, "\en";
+\&    print <FOO>;
+.Ve
+.SS "UNTIE this"
+.IX Xref "UNTIE"
+.IX Subsection "UNTIE this"
+You can define for all tie types an UNTIE method that will be called
+at \fBuntie()\fR.  See "The \f(CW\*(C`untie\*(C'\fR Gotcha" below.
+.ie n .SS "The ""untie"" Gotcha"
+.el .SS "The \f(CWuntie\fP Gotcha"
+.IX Xref "untie"
+.IX Subsection "The untie Gotcha"
+If you intend making use of the object returned from either \fBtie()\fR or
+\&\fBtied()\fR, and if the tie's target class defines a destructor, there is a
+subtle gotcha you \fImust\fR guard against.
+.PP
+As setup, consider this (admittedly rather contrived) example of a
+tie; all it does is use a file to keep a log of the values assigned to
+a scalar.
+.PP
+.Vb 1
+\&    package Remember;
+\&
+\&    use v5.36;
+\&    use IO::File;
+\&
+\&    sub TIESCALAR {
+\&        my $class = shift;
+\&        my $filename = shift;
+\&        my $handle = IO::File\->new( "> $filename" )
+\&                         or die "Cannot open $filename: $!\en";
+\&
+\&        print $handle "The Start\en";
+\&        bless {FH => $handle, Value => 0}, $class;
+\&    }
+\&
+\&    sub FETCH {
+\&        my $self = shift;
+\&        return $self\->{Value};
+\&    }
+\&
+\&    sub STORE {
+\&        my $self = shift;
+\&        my $value = shift;
+\&        my $handle = $self\->{FH};
+\&        print $handle "$value\en";
+\&        $self\->{Value} = $value;
+\&    }
+\&
+\&    sub DESTROY {
+\&        my $self = shift;
+\&        my $handle = $self\->{FH};
+\&        print $handle "The End\en";
+\&        close $handle;
+\&    }
+\&
+\&    1;
+.Ve
+.PP
+Here is an example that makes use of this tie:
+.PP
+.Vb 2
+\&    use strict;
+\&    use Remember;
+\&
+\&    my $fred;
+\&    tie $fred, \*(AqRemember\*(Aq, \*(Aqmyfile.txt\*(Aq;
+\&    $fred = 1;
+\&    $fred = 4;
+\&    $fred = 5;
+\&    untie $fred;
+\&    system "cat myfile.txt";
+.Ve
+.PP
+This is the output when it is executed:
+.PP
+.Vb 5
+\&    The Start
+\&    1
+\&    4
+\&    5
+\&    The End
+.Ve
+.PP
+So far so good.  Those of you who have been paying attention will have
+spotted that the tied object hasn't been used so far.  So lets add an
+extra method to the Remember class to allow comments to be included in
+the file; say, something like this:
+.PP
+.Vb 6
+\&    sub comment {
+\&        my $self = shift;
+\&        my $text = shift;
+\&        my $handle = $self\->{FH};
+\&        print $handle $text, "\en";
+\&    }
+.Ve
+.PP
+And here is the previous example modified to use the \f(CW\*(C`comment\*(C'\fR method
+(which requires the tied object):
+.PP
+.Vb 2
+\&    use strict;
+\&    use Remember;
+\&
+\&    my ($fred, $x);
+\&    $x = tie $fred, \*(AqRemember\*(Aq, \*(Aqmyfile.txt\*(Aq;
+\&    $fred = 1;
+\&    $fred = 4;
+\&    comment $x "changing...";
+\&    $fred = 5;
+\&    untie $fred;
+\&    system "cat myfile.txt";
+.Ve
+.PP
+When this code is executed there is no output.  Here's why:
+.PP
+When a variable is tied, it is associated with the object which is the
+return value of the TIESCALAR, TIEARRAY, or TIEHASH function.  This
+object normally has only one reference, namely, the implicit reference
+from the tied variable.  When \fBuntie()\fR is called, that reference is
+destroyed.  Then, as in the first example above, the object's
+destructor (DESTROY) is called, which is normal for objects that have
+no more valid references; and thus the file is closed.
+.PP
+In the second example, however, we have stored another reference to
+the tied object in \f(CW$x\fR.  That means that when \fBuntie()\fR gets called
+there will still be a valid reference to the object in existence, so
+the destructor is not called at that time, and thus the file is not
+closed.  The reason there is no output is because the file buffers
+have not been flushed to disk.
+.PP
+Now that you know what the problem is, what can you do to avoid it?
+Prior to the introduction of the optional UNTIE method the only way
+was the good old \f(CW\*(C`\-w\*(C'\fR flag. Which will spot any instances where you call
+\&\fBuntie()\fR and there are still valid references to the tied object.  If
+the second script above this near the top \f(CW\*(C`use warnings \*(Aquntie\*(Aq\*(C'\fR
+or was run with the \f(CW\*(C`\-w\*(C'\fR flag, Perl prints this
+warning message:
+.PP
+.Vb 1
+\&    untie attempted while 1 inner references still exist
+.Ve
+.PP
+To get the script to work properly and silence the warning make sure
+there are no valid references to the tied object \fIbefore\fR \fBuntie()\fR is
+called:
+.PP
+.Vb 2
+\&    undef $x;
+\&    untie $fred;
+.Ve
+.PP
+Now that UNTIE exists the class designer can decide which parts of the
+class functionality are really associated with \f(CW\*(C`untie\*(C'\fR and which with
+the object being destroyed. What makes sense for a given class depends
+on whether the inner references are being kept so that non-tie-related
+methods can be called on the object. But in most cases it probably makes
+sense to move the functionality that would have been in DESTROY to the UNTIE
+method.
+.PP
+If the UNTIE method exists then the warning above does not occur. Instead the
+UNTIE method is passed the count of "extra" references and can issue its own
+warning if appropriate. e.g. to replicate the no UNTIE case this method can
+be used:
+.PP
+.Vb 6
+\& sub UNTIE
+\& {
+\&  my ($obj,$count) = @_;
+\&  carp "untie attempted while $count inner references still exist"
+\&                                                              if $count;
+\& }
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See DB_File or Config for some interesting \fBtie()\fR implementations.
+A good starting point for many \fBtie()\fR implementations is with one of the
+modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
+.SH BUGS
+.IX Header "BUGS"
+The normal return provided by \f(CWscalar(%hash)\fR is not
+available.  What this means is that using \f(CW%tied_hash\fR in boolean
+context doesn't work right (currently this always tests false,
+regardless of whether the hash is empty or hash elements).
+[ This paragraph needs review in light of changes in 5.25 ]
+.PP
+Localizing tied arrays or hashes does not work.  After exiting the
+scope the arrays or the hashes are not restored.
+.PP
+Counting the number of entries in a hash via \f(CW\*(C`scalar(keys(%hash))\*(C'\fR
+or \f(CWscalar(values(%hash)\fR) is inefficient since it needs to iterate
+through all the entries with FIRSTKEY/NEXTKEY.
+.PP
+Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
+tie methods for slice operations.
+.PP
+You cannot easily tie a multilevel data structure (such as a hash of
+hashes) to a dbm file.  The first problem is that all but GDBM and
+Berkeley DB have size limitations, but beyond that, you also have problems
+with how references are to be represented on disk.  One
+module that does attempt to address this need is DBM::Deep.  Check your
+nearest CPAN site as described in perlmodlib for source code.  Note
+that despite its name, DBM::Deep does not use dbm.  Another earlier attempt
+at solving the problem is MLDBM, which is also available on the CPAN, but
+which has some fairly serious limitations.
+.PP
+Tied filehandles are still incomplete.  \fBsysopen()\fR, \fBtruncate()\fR,
+\&\fBflock()\fR, \fBfcntl()\fR, \fBstat()\fR and \-X can't currently be trapped.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen
+.PP
+TIEHANDLE by Sven Verdoolaege <\fIskimo@dns.ufsia.ac.be\fR> and Doug MacEachern <\fIdougm@osf.org\fR>
+.PP
+UNTIE by Nick Ing-Simmons <\fInick@ing\-simmons.net\fR>
+.PP
+SCALAR by Tassilo von Parseval <\fItassilo.von.parseval@rwth\-aachen.de\fR>
+.PP
+Tying Arrays by Casey West <\fIcasey@geeknest.com\fR>
diff --git a/upstream/mageia-cauldron/man1/perltoc.1 b/upstream/mageia-cauldron/man1/perltoc.1
new file mode 100644
index 00000000..3b6d3319
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltoc.1
@@ -0,0 +1,37640 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTOC 1"
+.TH PERLTOC 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltoc \- perl documentation table of contents
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This page provides a brief table of contents for the rest of the Perl
+documentation set.  It is meant to be scanned quickly or grepped
+through to locate the proper section you're looking for.
+.SH "BASIC DOCUMENTATION"
+.IX Header "BASIC DOCUMENTATION"
+.SS "perl \- The Perl 5 language interpreter"
+.IX Subsection "perl - The Perl 5 language interpreter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "GETTING HELP" 4
+.IX Item "GETTING HELP"
+.RS 4
+.IP Overview 4
+.IX Item "Overview"
+.IP Tutorials 4
+.IX Item "Tutorials"
+.IP "Reference Manual" 4
+.IX Item "Reference Manual"
+.IP "Internals and C Language Interface" 4
+.IX Item "Internals and C Language Interface"
+.IP History 4
+.IX Item "History"
+.IP Miscellaneous 4
+.IX Item "Miscellaneous"
+.IP Language-Specific 4
+.IX Item "Language-Specific"
+.IP Platform-Specific 4
+.IX Item "Platform-Specific"
+.IP "Stubs for Deleted Documents" 4
+.IX Item "Stubs for Deleted Documents"
+.RE
+.RS 4
+.RE
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AVAILABILITY 4
+.IX Item "AVAILABILITY"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP FILES 4
+.IX Item "FILES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP NOTES 4
+.IX Item "NOTES"
+.PD
+.SS "perlintro \- a brief introduction and overview of Perl"
+.IX Subsection "perlintro - a brief introduction and overview of Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "What is Perl?" 4
+.IX Item "What is Perl?"
+.IP "Running Perl programs" 4
+.IX Item "Running Perl programs"
+.IP "Safety net" 4
+.IX Item "Safety net"
+.IP "Basic syntax overview" 4
+.IX Item "Basic syntax overview"
+.IP "Perl variable types" 4
+.IX Item "Perl variable types"
+.PD
+Scalars, Arrays, Hashes
+.IP "Variable scoping" 4
+.IX Item "Variable scoping"
+.PD 0
+.IP "Conditional and looping constructs" 4
+.IX Item "Conditional and looping constructs"
+.PD
+if, while, for, foreach
+.IP "Builtin operators and functions" 4
+.IX Item "Builtin operators and functions"
+Arithmetic, Numeric comparison, String comparison, Boolean logic,
+Miscellaneous
+.IP "Files and I/O" 4
+.IX Item "Files and I/O"
+.PD 0
+.IP "Regular expressions" 4
+.IX Item "Regular expressions"
+.PD
+Simple matching, Simple substitution, More complex regular expressions,
+Parentheses for capturing, Other regexp features
+.IP "Writing subroutines" 4
+.IX Item "Writing subroutines"
+.PD 0
+.IP "OO Perl" 4
+.IX Item "OO Perl"
+.IP "Using Perl modules" 4
+.IX Item "Using Perl modules"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlrun \- how to execute the Perl interpreter"
+.IX Subsection "perlrun - how to execute the Perl interpreter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "#! and quoting on non-Unix systems" 4
+.IX Xref "hashbang #!"
+.IX Item "#! and quoting on non-Unix systems"
+.PD
+OS/2, MS-DOS, Win95/NT, VMS
+.IP "Location of Perl" 4
+.IX Xref "perl, location of interpreter"
+.IX Item "Location of Perl"
+.PD 0
+.IP "Command Switches" 4
+.IX Xref "perl, command switches command switches"
+.IX Item "Command Switches"
+.PD
+\&\fB\-0\fR[\fIoctal/hexadecimal\fR]  , \fB\-a\fR  , \fB\-C
+[\fR\f(BInumber/list\fR\fB]\fR , \fB\-c\fR , \fB\-d\fR  , \fB\-dt\fR,
+\&\fB\-d:\fR\fIMOD[=bar,baz]\fR  , \fB\-dt:\fR\fIMOD[=bar,baz]\fR,
+\&\fB\-D\fR\fIletters\fR   , \fB\-D\fR\fInumber\fR, \fB\-e\fR
+\&\fIcommandline\fR , \fB\-E\fR \fIcommandline\fR , \fB\-f\fR 
+ , \fB\-F\fR\fIpattern\fR , \fB\-g\fR ,
+\&\fB\-h\fR , \fB\-?\fR , \fB\-i\fR[\fIextension\fR]  ,
+\&\fB\-I\fR\fIdirectory\fR  , \fB\-l\fR[\fIoctnum\fR]   ,
+\&\fB\-m\fR[\fB\-\fR]\fImodule\fR  , \fB\-M\fR[\fB\-\fR]\fImodule\fR,
+\&\fB\-M\fR[\fB\-\fR]\fI'module ...'\fR, \fB\-[mM]\fR[\fB\-\fR]\fImodule=arg[,arg]...\fR, \fB\-n\fR
+, \fB\-p\fR , \fB\-s\fR , \fB\-S\fR , \fB\-t\fR , \fB\-T\fR ,
+\&\fB\-u\fR , \fB\-U\fR , \fB\-v\fR , \fB\-V\fR , \fB\-V:\fR\fIconfigvar\fR,
+\&\fB\-w\fR , \fB\-W\fR , \fB\-X\fR , \fB\-x\fR , \fB\-x\fR\fIdirectory\fR
+.IX Xref "-0 $ -a autosplit -C -c -d -dt -d -dt -D DEBUGGING -DDEBUGGING -e -E -f sitecustomize sitecustomize.pl -F -g -h -? -i in-place -I @INC -l $ $\\ -m -M -n -p -s -S -t -T -u -U -v -V -w -W -X -x"
+.RE
+.RS 4
+.RE
+.IP ENVIRONMENT 4
+.IX Xref "perl, environment variables"
+.IX Item "ENVIRONMENT"
+HOME , LOGDIR , PATH , PERL5LIB ,
+PERL5OPT , PERLIO , :crlf , :perlio ,
+:stdio , :unix , PERLIO_DEBUG , PERLLIB
+, PERL5DB , PERL5DB_THREADED ,
+PERL5SHELL (specific to the Win32 port) ,
+PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
+, PERL_DEBUG_MSTATS ,
+PERL_DESTRUCT_LEVEL , PERL_DL_NONLAZY
+, PERL_ENCODING , PERL_HASH_SEED
+, PERL_PERTURB_KEYS ,
+PERL_HASH_SEED_DEBUG , PERL_MEM_LOG ,
+PERL_ROOT (specific to the VMS port) , PERL_SIGNALS
+, PERL_UNICODE , PERL_USE_UNSAFE_INC
+, SYS$LOGIN (specific to the VMS port) ,
+PERL_INTERNAL_RAND_SEED , PERL_RAND_SEED
+.IX Xref "HOME LOGDIR PATH PERL5LIB PERL5OPT PERLIO :crlf :perlio :stdio :unix PERLIO_DEBUG PERLLIB PERL5DB PERL5DB_THREADED PERL5SHELL PERL_ALLOW_NON_IFS_LSP PERL_DEBUG_MSTATS PERL_DESTRUCT_LEVEL PERL_DL_NONLAZY PERL_ENCODING PERL_HASH_SEED PERL_PERTURB_KEYS PERL_HASH_SEED_DEBUG PERL_MEM_LOG PERL_ROOT PERL_SIGNALS PERL_UNICODE PERL_USE_UNSAFE_INC SYS$LOGIN PERL_INTERNAL_RAND_SEED PERL_RAND_SEED"
+.IP "ORDER OF APPLICATION" 4
+.IX Item "ORDER OF APPLICATION"
+\&\-I, \-M, the PERL5LIB environment variable, combinations of \-I, \-M and
+PERL5LIB, the PERL5OPT environment variable, Other complications, arch and
+version subdirs, sitecustomize.pl
+.SS "perlreftut \- Mark's very short tutorial about references"
+.IX Subsection "perlreftut - Mark's very short tutorial about references"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Who Needs Complicated Data Structures?" 4
+.IX Item "Who Needs Complicated Data Structures?"
+.IP "The Solution" 4
+.IX Item "The Solution"
+.IP Syntax 4
+.IX Item "Syntax"
+.RS 4
+.IP "Making References" 4
+.IX Item "Making References"
+.IP "Using References" 4
+.IX Item "Using References"
+.IP "An Example" 4
+.IX Item "An Example"
+.IP "Arrow Rule" 4
+.IX Item "Arrow Rule"
+.RE
+.RS 4
+.RE
+.IP Solution 4
+.IX Item "Solution"
+.IP "The Rest" 4
+.IX Item "The Rest"
+.IP Summary 4
+.IX Item "Summary"
+.IP Credits 4
+.IX Item "Credits"
+.RS 4
+.IP "Distribution Conditions" 4
+.IX Item "Distribution Conditions"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perldsc \- Perl Data Structures Cookbook"
+.IX Subsection "perldsc - Perl Data Structures Cookbook"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes,
+more elaborate constructs
+.IP REFERENCES 4
+.IX Xref "reference dereference dereferencing pointer"
+.IX Item "REFERENCES"
+.PD 0
+.IP "COMMON MISTAKES" 4
+.IX Item "COMMON MISTAKES"
+.IP "CAVEAT ON PRECEDENCE" 4
+.IX Xref "dereference, precedence dereferencing, precedence"
+.IX Item "CAVEAT ON PRECEDENCE"
+.ie n .IP "WHY YOU SHOULD ALWAYS ""use VERSION""" 4
+.el .IP "WHY YOU SHOULD ALWAYS \f(CWuse VERSION\fR" 4
+.IX Item "WHY YOU SHOULD ALWAYS use VERSION"
+.IP DEBUGGING 4
+.IX Xref "data structure, debugging complex data structure, debugging AoA, debugging HoA, debugging AoH, debugging HoH, debugging array of arrays, debugging hash of arrays, debugging array of hashes, debugging hash of hashes, debugging"
+.IX Item "DEBUGGING"
+.IP "CODE EXAMPLES" 4
+.IX Item "CODE EXAMPLES"
+.IP "ARRAYS OF ARRAYS" 4
+.IX Xref "array of arrays AoA"
+.IX Item "ARRAYS OF ARRAYS"
+.RS 4
+.IP "Declaration of an ARRAY OF ARRAYS" 4
+.IX Item "Declaration of an ARRAY OF ARRAYS"
+.IP "Generation of an ARRAY OF ARRAYS" 4
+.IX Item "Generation of an ARRAY OF ARRAYS"
+.IP "Access and Printing of an ARRAY OF ARRAYS" 4
+.IX Item "Access and Printing of an ARRAY OF ARRAYS"
+.RE
+.RS 4
+.RE
+.IP "HASHES OF ARRAYS" 4
+.IX Xref "hash of arrays HoA"
+.IX Item "HASHES OF ARRAYS"
+.RS 4
+.IP "Declaration of a HASH OF ARRAYS" 4
+.IX Item "Declaration of a HASH OF ARRAYS"
+.IP "Generation of a HASH OF ARRAYS" 4
+.IX Item "Generation of a HASH OF ARRAYS"
+.IP "Access and Printing of a HASH OF ARRAYS" 4
+.IX Item "Access and Printing of a HASH OF ARRAYS"
+.RE
+.RS 4
+.RE
+.IP "ARRAYS OF HASHES" 4
+.IX Xref "array of hashes AoH"
+.IX Item "ARRAYS OF HASHES"
+.RS 4
+.IP "Declaration of an ARRAY OF HASHES" 4
+.IX Item "Declaration of an ARRAY OF HASHES"
+.IP "Generation of an ARRAY OF HASHES" 4
+.IX Item "Generation of an ARRAY OF HASHES"
+.IP "Access and Printing of an ARRAY OF HASHES" 4
+.IX Item "Access and Printing of an ARRAY OF HASHES"
+.RE
+.RS 4
+.RE
+.IP "HASHES OF HASHES" 4
+.IX Xref "hash of hashes HoH"
+.IX Item "HASHES OF HASHES"
+.RS 4
+.IP "Declaration of a HASH OF HASHES" 4
+.IX Item "Declaration of a HASH OF HASHES"
+.IP "Generation of a HASH OF HASHES" 4
+.IX Item "Generation of a HASH OF HASHES"
+.IP "Access and Printing of a HASH OF HASHES" 4
+.IX Item "Access and Printing of a HASH OF HASHES"
+.RE
+.RS 4
+.RE
+.IP "MORE ELABORATE RECORDS" 4
+.IX Xref "record structure struct"
+.IX Item "MORE ELABORATE RECORDS"
+.RS 4
+.IP "Declaration of MORE ELABORATE RECORDS" 4
+.IX Item "Declaration of MORE ELABORATE RECORDS"
+.IP "Declaration of a HASH OF COMPLEX RECORDS" 4
+.IX Item "Declaration of a HASH OF COMPLEX RECORDS"
+.IP "Generation of a HASH OF COMPLEX RECORDS" 4
+.IX Item "Generation of a HASH OF COMPLEX RECORDS"
+.RE
+.RS 4
+.RE
+.IP "Database Ties" 4
+.IX Item "Database Ties"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perllol \- Manipulating Arrays of Arrays in Perl"
+.IX Subsection "perllol - Manipulating Arrays of Arrays in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Declaration and Access of Arrays of Arrays" 4
+.IX Item "Declaration and Access of Arrays of Arrays"
+.IP "Growing Your Own" 4
+.IX Item "Growing Your Own"
+.IP "Access and Printing" 4
+.IX Item "Access and Printing"
+.IP Slices 4
+.IX Item "Slices"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlrequick \- Perl regular expressions quick start"
+.IX Subsection "perlrequick - Perl regular expressions quick start"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "The Guide" 4
+.IX Item "The Guide"
+.RS 4
+.IP "Simple word matching" 4
+.IX Item "Simple word matching"
+.IP "Using character classes" 4
+.IX Item "Using character classes"
+.IP "Matching this or that" 4
+.IX Item "Matching this or that"
+.IP "Grouping things and hierarchical matching" 4
+.IX Item "Grouping things and hierarchical matching"
+.IP "Extracting matches" 4
+.IX Item "Extracting matches"
+.IP "Matching repetitions" 4
+.IX Item "Matching repetitions"
+.IP "More matching" 4
+.IX Item "More matching"
+.IP "Search and replace" 4
+.IX Item "Search and replace"
+.IP "The split operator" 4
+.IX Item "The split operator"
+.ie n .IP """use re \*(Aqstrict\*(Aq""" 4
+.el .IP "\f(CWuse re \*(Aqstrict\*(Aq\fR" 4
+.IX Item "use re strict"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.RS 4
+.IP Acknowledgments 4
+.IX Item "Acknowledgments"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlretut \- Perl regular expressions tutorial"
+.IX Subsection "perlretut - Perl regular expressions tutorial"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Part 1: The basics" 4
+.IX Item "Part 1: The basics"
+.RS 4
+.IP "Simple word matching" 4
+.IX Item "Simple word matching"
+.IP "Using character classes" 4
+.IX Item "Using character classes"
+.IP "Matching this or that" 4
+.IX Item "Matching this or that"
+.IP "Grouping things and hierarchical matching" 4
+.IX Item "Grouping things and hierarchical matching"
+.IP "Extracting matches" 4
+.IX Item "Extracting matches"
+.IP Backreferences 4
+.IX Item "Backreferences"
+.IP "Relative backreferences" 4
+.IX Item "Relative backreferences"
+.IP "Named backreferences" 4
+.IX Item "Named backreferences"
+.IP "Alternative capture group numbering" 4
+.IX Item "Alternative capture group numbering"
+.IP "Position information" 4
+.IX Item "Position information"
+.IP "Non-capturing groupings" 4
+.IX Item "Non-capturing groupings"
+.IP "Matching repetitions" 4
+.IX Item "Matching repetitions"
+.IP "Possessive quantifiers" 4
+.IX Item "Possessive quantifiers"
+.IP "Building a regexp" 4
+.IX Item "Building a regexp"
+.IP "Using regular expressions in Perl" 4
+.IX Item "Using regular expressions in Perl"
+.RE
+.RS 4
+.RE
+.IP "Part 2: Power tools" 4
+.IX Item "Part 2: Power tools"
+.RS 4
+.IP "More on characters, strings, and character classes" 4
+.IX Item "More on characters, strings, and character classes"
+.IP "Compiling and saving regular expressions" 4
+.IX Item "Compiling and saving regular expressions"
+.IP "Composing regular expressions at runtime" 4
+.IX Item "Composing regular expressions at runtime"
+.IP "Embedding comments and modifiers in a regular expression" 4
+.IX Item "Embedding comments and modifiers in a regular expression"
+.IP "Looking ahead and looking behind" 4
+.IX Item "Looking ahead and looking behind"
+.IP "Using independent subexpressions to prevent backtracking" 4
+.IX Item "Using independent subexpressions to prevent backtracking"
+.IP "Conditional expressions" 4
+.IX Item "Conditional expressions"
+.IP "Defining named patterns" 4
+.IX Item "Defining named patterns"
+.IP "Recursive patterns" 4
+.IX Item "Recursive patterns"
+.IP "A bit of magic: executing Perl code in a regular expression" 4
+.IX Item "A bit of magic: executing Perl code in a regular expression"
+.IP "Backtracking control verbs" 4
+.IX Item "Backtracking control verbs"
+.IP "Pragmas and debugging" 4
+.IX Item "Pragmas and debugging"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.RS 4
+.IP Acknowledgments 4
+.IX Item "Acknowledgments"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlootut \- Object-Oriented Programming in Perl Tutorial"
+.IX Subsection "perlootut - Object-Oriented Programming in Perl Tutorial"
+.IP DATE 4
+.IX Item "DATE"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OBJECT-ORIENTED FUNDAMENTALS" 4
+.IX Item "OBJECT-ORIENTED FUNDAMENTALS"
+.RS 4
+.IP Object 4
+.IX Item "Object"
+.IP Class 4
+.IX Item "Class"
+.IP Methods 4
+.IX Item "Methods"
+.IP Attributes 4
+.IX Item "Attributes"
+.IP Polymorphism 4
+.IX Item "Polymorphism"
+.IP Inheritance 4
+.IX Item "Inheritance"
+.IP Encapsulation 4
+.IX Item "Encapsulation"
+.IP Composition 4
+.IX Item "Composition"
+.IP Roles 4
+.IX Item "Roles"
+.IP "When to Use OO" 4
+.IX Item "When to Use OO"
+.RE
+.RS 4
+.RE
+.IP "PERL OO SYSTEMS" 4
+.IX Item "PERL OO SYSTEMS"
+.RS 4
+.IP Moose 4
+.IX Item "Moose"
+.PD
+Declarative sugar, Roles built-in, A miniature type system, Full
+introspection and manipulation, Self-hosted and extensible, Rich ecosystem,
+Many more features
+.IP Class::Accessor 4
+.IX Item "Class::Accessor"
+.PD 0
+.IP Class::Tiny 4
+.IX Item "Class::Tiny"
+.IP Role::Tiny 4
+.IX Item "Role::Tiny"
+.IP "OO System Summary" 4
+.IX Item "OO System Summary"
+.PD
+Moose, Class::Accessor, Class::Tiny, Role::Tiny
+.IP "Other OO Systems" 4
+.IX Item "Other OO Systems"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP CONCLUSION 4
+.IX Item "CONCLUSION"
+.PD
+.SS "perlperf \- Perl Performance and Optimization Techniques"
+.IX Subsection "perlperf - Perl Performance and Optimization Techniques"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP OVERVIEW 4
+.IX Item "OVERVIEW"
+.RS 4
+.IP "ONE STEP SIDEWAYS" 4
+.IX Item "ONE STEP SIDEWAYS"
+.IP "ONE STEP FORWARD" 4
+.IX Item "ONE STEP FORWARD"
+.IP "ANOTHER STEP SIDEWAYS" 4
+.IX Item "ANOTHER STEP SIDEWAYS"
+.RE
+.RS 4
+.RE
+.IP "GENERAL GUIDELINES" 4
+.IX Item "GENERAL GUIDELINES"
+.IP BENCHMARKS 4
+.IX Item "BENCHMARKS"
+.RS 4
+.IP "Assigning and Dereferencing Variables." 4
+.IX Item "Assigning and Dereferencing Variables."
+.IP "Search and replace or tr" 4
+.IX Item "Search and replace or tr"
+.RE
+.RS 4
+.RE
+.IP "PROFILING TOOLS" 4
+.IX Item "PROFILING TOOLS"
+.RS 4
+.IP Devel::DProf 4
+.IX Item "Devel::DProf"
+.IP Devel::Profiler 4
+.IX Item "Devel::Profiler"
+.IP Devel::SmallProf 4
+.IX Item "Devel::SmallProf"
+.IP Devel::FastProf 4
+.IX Item "Devel::FastProf"
+.IP Devel::NYTProf 4
+.IX Item "Devel::NYTProf"
+.RE
+.RS 4
+.RE
+.IP SORTING 4
+.IX Item "SORTING"
+.PD
+Elapsed Real Time, User CPU Time, System CPU Time
+.IP LOGGING 4
+.IX Item "LOGGING"
+.RS 4
+.PD 0
+.IP "Logging if DEBUG (constant)" 4
+.IX Item "Logging if DEBUG (constant)"
+.RE
+.RS 4
+.RE
+.IP POSTSCRIPT 4
+.IX Item "POSTSCRIPT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP PERLDOCS 4
+.IX Item "PERLDOCS"
+.IP "MAN PAGES" 4
+.IX Item "MAN PAGES"
+.IP MODULES 4
+.IX Item "MODULES"
+.IP URLS 4
+.IX Item "URLS"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlstyle \- Perl style guide"
+.IX Subsection "perlstyle - Perl style guide"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "perlcheat \- Perl 5 Cheat Sheet"
+.IX Subsection "perlcheat - Perl 5 Cheat Sheet"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "The sheet" 4
+.IX Item "The sheet"
+.RE
+.RS 4
+.RE
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perltrap \- Perl traps for the unwary"
+.IX Subsection "perltrap - Perl traps for the unwary"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Awk Traps" 4
+.IX Item "Awk Traps"
+.IP "C/C++ Traps" 4
+.IX Item "C/C++ Traps"
+.IP "JavaScript Traps" 4
+.IX Item "JavaScript Traps"
+.IP "Sed Traps" 4
+.IX Item "Sed Traps"
+.IP "Shell Traps" 4
+.IX Item "Shell Traps"
+.IP "Perl Traps" 4
+.IX Item "Perl Traps"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perldebtut \- Perl debugging tutorial"
+.IX Subsection "perldebtut - Perl debugging tutorial"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "use strict" 4
+.IX Item "use strict"
+.IP "Looking at data and \-w and v" 4
+.IX Item "Looking at data and -w and v"
+.IP help 4
+.IX Item "help"
+.IP "Stepping through code" 4
+.IX Item "Stepping through code"
+.IP "Placeholder for a, w, t, T" 4
+.IX Item "Placeholder for a, w, t, T"
+.IP "REGULAR EXPRESSIONS" 4
+.IX Item "REGULAR EXPRESSIONS"
+.IP "OUTPUT TIPS" 4
+.IX Item "OUTPUT TIPS"
+.IP CGI 4
+.IX Item "CGI"
+.IP GUIs 4
+.IX Item "GUIs"
+.IP SUMMARY 4
+.IX Item "SUMMARY"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.PD
+.SS "perlfaq \- Frequently asked questions about Perl"
+.IX Subsection "perlfaq - Frequently asked questions about Perl"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Where to find the perlfaq" 4
+.IX Item "Where to find the perlfaq"
+.IP "How to use the perlfaq" 4
+.IX Item "How to use the perlfaq"
+.IP "How to contribute to the perlfaq" 4
+.IX Item "How to contribute to the perlfaq"
+.IP "What if my question isn't answered in the FAQ?" 4
+.IX Item "What if my question isn't answered in the FAQ?"
+.RE
+.RS 4
+.RE
+.IP "TABLE OF CONTENTS" 4
+.IX Item "TABLE OF CONTENTS"
+.PD
+perlfaq1 \- General Questions About Perl, perlfaq2 \- Obtaining and Learning
+about Perl, perlfaq3 \- Programming Tools, perlfaq4 \- Data Manipulation,
+perlfaq5 \- Files and Formats, perlfaq6 \- Regular Expressions, perlfaq7 \-
+General Perl Language Issues, perlfaq8 \- System Interaction, perlfaq9 \-
+Web, Email and Networking
+.IP "THE QUESTIONS" 4
+.IX Item "THE QUESTIONS"
+.RS 4
+.PD 0
+.IP "perlfaq1: General Questions About Perl" 4
+.IX Item "perlfaq1: General Questions About Perl"
+.IP "perlfaq2: Obtaining and Learning about Perl" 4
+.IX Item "perlfaq2: Obtaining and Learning about Perl"
+.IP "perlfaq3: Programming Tools" 4
+.IX Item "perlfaq3: Programming Tools"
+.IP "perlfaq4: Data Manipulation" 4
+.IX Item "perlfaq4: Data Manipulation"
+.IP "perlfaq5: Files and Formats" 4
+.IX Item "perlfaq5: Files and Formats"
+.IP "perlfaq6: Regular Expressions" 4
+.IX Item "perlfaq6: Regular Expressions"
+.IP "perlfaq7: General Perl Language Issues" 4
+.IX Item "perlfaq7: General Perl Language Issues"
+.IP "perlfaq8: System Interaction" 4
+.IX Item "perlfaq8: System Interaction"
+.IP "perlfaq9: Web, Email and Networking" 4
+.IX Item "perlfaq9: Web, Email and Networking"
+.RE
+.RS 4
+.RE
+.IP CREDITS 4
+.IX Item "CREDITS"
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq1 \- General Questions About Perl"
+.IX Subsection "perlfaq1 - General Questions About Perl"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "What is Perl?" 4
+.IX Item "What is Perl?"
+.IP "Who supports Perl? Who develops it? Why is it free?" 4
+.IX Item "Who supports Perl? Who develops it? Why is it free?"
+.IP "Which version of Perl should I use?" 4
+.IX Item "Which version of Perl should I use?"
+.IP "What are Perl 4, Perl 5, or Raku (Perl 6)?" 4
+.IX Item "What are Perl 4, Perl 5, or Raku (Perl 6)?"
+.IP "What is Raku (Perl 6)?" 4
+.IX Item "What is Raku (Perl 6)?"
+.IP "How stable is Perl?" 4
+.IX Item "How stable is Perl?"
+.IP "How often are new versions of Perl released?" 4
+.IX Item "How often are new versions of Perl released?"
+.IP "Is Perl difficult to learn?" 4
+.IX Item "Is Perl difficult to learn?"
+.IP "How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?" 4
+.IX Item "How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?"
+.IP "Can I do [task] in Perl?" 4
+.IX Item "Can I do [task] in Perl?"
+.IP "When shouldn't I program in Perl?" 4
+.IX Item "When shouldn't I program in Perl?"
+.IP "What's the difference between ""perl"" and ""Perl""?" 4
+.IX Item "What's the difference between ""perl"" and ""Perl""?"
+.IP "What is a JAPH?" 4
+.IX Item "What is a JAPH?"
+.IP "How can I convince others to use Perl?" 4
+.IX Item "How can I convince others to use Perl?"
+.PD
+<http://www.perl.org/about.html>,
+<http://perltraining.com.au/whyperl.html>
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.SS "perlfaq2 \- Obtaining and Learning about Perl"
+.IX Subsection "perlfaq2 - Obtaining and Learning about Perl"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "What machines support Perl? Where do I get it?" 4
+.IX Item "What machines support Perl? Where do I get it?"
+.IP "How can I get a binary version of Perl?" 4
+.IX Item "How can I get a binary version of Perl?"
+.IP "I don't have a C compiler. How can I build my own Perl interpreter?" 4
+.IX Item "I don't have a C compiler. How can I build my own Perl interpreter?"
+.IP "I copied the Perl binary from one machine to another, but scripts don't work." 4
+.IX Item "I copied the Perl binary from one machine to another, but scripts don't work."
+.IP "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?" 4
+.IX Item "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?"
+.IP "What modules and extensions are available for Perl? What is CPAN?" 4
+.IX Item "What modules and extensions are available for Perl? What is CPAN?"
+.IP "Where can I get information on Perl?" 4
+.IX Item "Where can I get information on Perl?"
+.PD
+<http://www.perl.org/>, <http://perldoc.perl.org/>,
+<http://learn.perl.org/>
+.IP "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?" 4
+.IX Item "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?"
+<http://www.perl.org/>, <http://learn.perl.org/>,
+<http://jobs.perl.org/>, <http://lists.perl.org/>
+.IP "Where can I post questions?" 4
+.IX Item "Where can I post questions?"
+.PD 0
+.IP "Perl Books" 4
+.IX Item "Perl Books"
+.IP "Which magazines have Perl content?" 4
+.IX Item "Which magazines have Perl content?"
+.IP "Which Perl blogs should I read?" 4
+.IX Item "Which Perl blogs should I read?"
+.IP "What mailing lists are there for Perl?" 4
+.IX Item "What mailing lists are there for Perl?"
+.IP "Where can I buy a commercial version of Perl?" 4
+.IX Item "Where can I buy a commercial version of Perl?"
+.IP "Where do I send bug reports?" 4
+.IX Item "Where do I send bug reports?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq3 \- Programming Tools"
+.IX Subsection "perlfaq3 - Programming Tools"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How do I do (anything)?" 4
+.IX Item "How do I do (anything)?"
+.PD
+Basics, perldata \- Perl data types, perlvar \- Perl pre-defined
+variables, perlsyn \- Perl syntax, perlop \- Perl operators and
+precedence, perlsub \- Perl subroutines, Execution, perlrun \- how to
+execute the Perl interpreter, perldebug \- Perl debugging, Functions,
+perlfunc \- Perl builtin functions, Objects, perlref \- Perl references
+and nested data structures, perlmod \- Perl modules (packages and symbol
+tables), perlobj \- Perl objects, perltie \- how to hide an object
+class in a simple variable, Data Structures, perlref \- Perl references
+and nested data structures, perllol \- Manipulating arrays of arrays in
+Perl, perldsc \- Perl Data Structures Cookbook, Modules, perlmod \-
+Perl modules (packages and symbol tables), perlmodlib \- constructing new
+Perl modules and finding existing ones, Regexes, perlre \- Perl regular
+expressions, perlfunc \- Perl builtin functions>, perlop \- Perl
+operators and precedence, perllocale \- Perl locale handling
+(internationalization and localization), Moving to perl5, perltrap \-
+Perl traps for the unwary, perl, Linking with C, perlxstut \- Tutorial
+for writing XSUBs, perlxs \- XS language reference manual, perlcall \-
+Perl calling conventions from C, perlguts \- Introduction to the Perl
+API, perlembed \- how to embed perl in your C program, Various
+.IP "How can I use Perl interactively?" 4
+.IX Item "How can I use Perl interactively?"
+.PD 0
+.IP "How do I find which modules are installed on my system?" 4
+.IX Item "How do I find which modules are installed on my system?"
+.IP "How do I debug my Perl programs?" 4
+.IX Item "How do I debug my Perl programs?"
+.IP "How do I profile my Perl programs?" 4
+.IX Item "How do I profile my Perl programs?"
+.IP "How do I cross-reference my Perl programs?" 4
+.IX Item "How do I cross-reference my Perl programs?"
+.IP "Is there a pretty-printer (formatter) for Perl?" 4
+.IX Item "Is there a pretty-printer (formatter) for Perl?"
+.IP "Is there an IDE or Windows Perl Editor?" 4
+.IX Item "Is there an IDE or Windows Perl Editor?"
+.PD
+Eclipse, Enginsite, IntelliJ IDEA, Kephra, Komodo, Notepad++, Open Perl
+IDE, OptiPerl, Padre, PerlBuilder, visiPerl+, Visual Perl, Zeus, GNU Emacs,
+MicroEMACS, XEmacs, Jed, Vim, Vile, MultiEdit, SlickEdit, ConTEXT, bash,
+zsh, BBEdit and TextWrangler
+.IP "Where can I get Perl macros for vi?" 4
+.IX Item "Where can I get Perl macros for vi?"
+.PD 0
+.IP "Where can I get perl-mode or cperl-mode for emacs?" 4
+.IX Xref "emacs"
+.IX Item "Where can I get perl-mode or cperl-mode for emacs?"
+.IP "How can I use curses with Perl?" 4
+.IX Item "How can I use curses with Perl?"
+.IP "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?" 4
+.IX Xref "GUI Tk Wx WxWidgets Gtk Gtk2 CamelBones Qt"
+.IX Item "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?"
+.PD
+Tk, Wx, Gtk and Gtk2, Win32::GUI, CamelBones, Qt, Athena
+.IP "How can I make my Perl program run faster?" 4
+.IX Item "How can I make my Perl program run faster?"
+.PD 0
+.IP "How can I make my Perl program take less memory?" 4
+.IX Item "How can I make my Perl program take less memory?"
+.PD
+Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and
+stringification, Pass by reference, Tie large variables to disk
+.IP "Is it safe to return a reference to local or lexical data?" 4
+.IX Item "Is it safe to return a reference to local or lexical data?"
+.PD 0
+.IP "How can I free an array or hash so my program shrinks?" 4
+.IX Item "How can I free an array or hash so my program shrinks?"
+.IP "How can I make my CGI script more efficient?" 4
+.IX Item "How can I make my CGI script more efficient?"
+.IP "How can I hide the source for my Perl program?" 4
+.IX Item "How can I hide the source for my Perl program?"
+.IP "How can I compile my Perl program into byte code or C?" 4
+.IX Item "How can I compile my Perl program into byte code or C?"
+.ie n .IP "How can I get ""#!perl"" to work on [MS\-DOS,NT,...]?" 4
+.el .IP "How can I get \f(CW#!perl\fR to work on [MS\-DOS,NT,...]?" 4
+.IX Item "How can I get #!perl to work on [MS-DOS,NT,...]?"
+.IP "Can I write useful Perl programs on the command line?" 4
+.IX Item "Can I write useful Perl programs on the command line?"
+.IP "Why don't Perl one-liners work on my DOS/Mac/VMS system?" 4
+.IX Item "Why don't Perl one-liners work on my DOS/Mac/VMS system?"
+.IP "Where can I learn about CGI or Web programming in Perl?" 4
+.IX Item "Where can I learn about CGI or Web programming in Perl?"
+.IP "Where can I learn about object-oriented Perl programming?" 4
+.IX Item "Where can I learn about object-oriented Perl programming?"
+.IP "Where can I learn about linking C with Perl?" 4
+.IX Item "Where can I learn about linking C with Perl?"
+.IP "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?" 4
+.IX Item "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?"
+.IP "When I tried to run my script, I got this message. What does it mean?" 4
+.IX Item "When I tried to run my script, I got this message. What does it mean?"
+.IP "What's MakeMaker?" 4
+.IX Item "What's MakeMaker?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq4 \- Data Manipulation"
+.IX Subsection "perlfaq4 - Data Manipulation"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Data: Numbers" 4
+.IX Item "Data: Numbers"
+.RS 4
+.IP "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?" 4
+.IX Item "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?"
+.IP "Why is \fBint()\fR broken?" 4
+.IX Item "Why is int() broken?"
+.IP "Why isn't my octal data interpreted correctly?" 4
+.IX Item "Why isn't my octal data interpreted correctly?"
+.IP "Does Perl have a \fBround()\fR function? What about \fBceil()\fR and \fBfloor()\fR? Trig functions?" 4
+.IX Item "Does Perl have a round() function? What about ceil() and floor()? Trig functions?"
+.IP "How do I convert between numeric representations/bases/radixes?" 4
+.IX Item "How do I convert between numeric representations/bases/radixes?"
+.PD
+How do I convert hexadecimal into decimal, How do I convert from decimal to
+hexadecimal, How do I convert from octal to decimal, How do I convert from
+decimal to octal, How do I convert from binary to decimal, How do I convert
+from decimal to binary
+.IP "Why doesn't & work the way I want it to?" 4
+.IX Item "Why doesn't & work the way I want it to?"
+.PD 0
+.IP "How do I multiply matrices?" 4
+.IX Item "How do I multiply matrices?"
+.IP "How do I perform an operation on a series of integers?" 4
+.IX Item "How do I perform an operation on a series of integers?"
+.IP "How can I output Roman numerals?" 4
+.IX Item "How can I output Roman numerals?"
+.IP "Why aren't my random numbers random?" 4
+.IX Item "Why aren't my random numbers random?"
+.IP "How do I get a random number between X and Y?" 4
+.IX Item "How do I get a random number between X and Y?"
+.RE
+.RS 4
+.RE
+.IP "Data: Dates" 4
+.IX Item "Data: Dates"
+.RS 4
+.IP "How do I find the day or week of the year?" 4
+.IX Item "How do I find the day or week of the year?"
+.IP "How do I find the current century or millennium?" 4
+.IX Item "How do I find the current century or millennium?"
+.IP "How can I compare two dates and find the difference?" 4
+.IX Item "How can I compare two dates and find the difference?"
+.IP "How can I take a string and turn it into epoch seconds?" 4
+.IX Item "How can I take a string and turn it into epoch seconds?"
+.IP "How can I find the Julian Day?" 4
+.IX Item "How can I find the Julian Day?"
+.IP "How do I find yesterday's date?" 4
+.IX Xref "date yesterday DateTime Date::Calc Time::Local daylight saving time day Today_and_Now localtime timelocal"
+.IX Item "How do I find yesterday's date?"
+.IP "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?" 4
+.IX Item "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?"
+.RE
+.RS 4
+.RE
+.IP "Data: Strings" 4
+.IX Item "Data: Strings"
+.RS 4
+.IP "How do I validate input?" 4
+.IX Item "How do I validate input?"
+.IP "How do I unescape a string?" 4
+.IX Item "How do I unescape a string?"
+.IP "How do I remove consecutive pairs of characters?" 4
+.IX Item "How do I remove consecutive pairs of characters?"
+.IP "How do I expand function calls in a string?" 4
+.IX Item "How do I expand function calls in a string?"
+.IP "How do I find matching/nesting anything?" 4
+.IX Item "How do I find matching/nesting anything?"
+.IP "How do I reverse a string?" 4
+.IX Item "How do I reverse a string?"
+.IP "How do I expand tabs in a string?" 4
+.IX Item "How do I expand tabs in a string?"
+.IP "How do I reformat a paragraph?" 4
+.IX Item "How do I reformat a paragraph?"
+.IP "How can I access or change N characters of a string?" 4
+.IX Item "How can I access or change N characters of a string?"
+.IP "How do I change the Nth occurrence of something?" 4
+.IX Item "How do I change the Nth occurrence of something?"
+.IP "How can I count the number of occurrences of a substring within a string?" 4
+.IX Item "How can I count the number of occurrences of a substring within a string?"
+.IP "How do I capitalize all the words on one line?" 4
+.IX Xref "Text::Autoformat capitalize case, title case, sentence"
+.IX Item "How do I capitalize all the words on one line?"
+.IP "How can I split a [character]\-delimited string except when inside [character]?" 4
+.IX Item "How can I split a [character]-delimited string except when inside [character]?"
+.IP "How do I strip blank space from the beginning/end of a string?" 4
+.IX Item "How do I strip blank space from the beginning/end of a string?"
+.IP "How do I pad a string with blanks or pad a number with zeroes?" 4
+.IX Item "How do I pad a string with blanks or pad a number with zeroes?"
+.IP "How do I extract selected columns from a string?" 4
+.IX Item "How do I extract selected columns from a string?"
+.IP "How do I find the soundex value of a string?" 4
+.IX Item "How do I find the soundex value of a string?"
+.IP "How can I expand variables in text strings?" 4
+.IX Item "How can I expand variables in text strings?"
+.IP "Does Perl have anything like Ruby's #{} or Python's f string?" 4
+.IX Item "Does Perl have anything like Ruby's #{} or Python's f string?"
+.IP "What's wrong with always quoting ""$vars""?" 4
+.IX Item "What's wrong with always quoting ""$vars""?"
+.IP "Why don't my <<HERE documents work?" 4
+.IX Item "Why don't my <<HERE documents work?"
+.PD
+There must be no space after the << part, There (probably) should
+be a semicolon at the end of the opening token, You can't (easily) have any
+space in front of the tag, There needs to be at least a line separator
+after the end token
+.RE
+.RS 4
+.RE
+.IP "Data: Arrays" 4
+.IX Item "Data: Arrays"
+.RS 4
+.PD 0
+.IP "What is the difference between a list and an array?" 4
+.IX Item "What is the difference between a list and an array?"
+.ie n .IP "What is the difference between $array[1] and @array[1]?" 4
+.el .IP "What is the difference between \f(CW$array\fR[1] and \f(CW@array\fR[1]?" 4
+.IX Item "What is the difference between $array[1] and @array[1]?"
+.IP "How can I remove duplicate elements from a list or array?" 4
+.IX Item "How can I remove duplicate elements from a list or array?"
+.IP "How can I tell whether a certain element is contained in a list or array?" 4
+.IX Item "How can I tell whether a certain element is contained in a list or array?"
+.IP "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?" 4
+.IX Item "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?"
+.IP "How do I test whether two arrays or hashes are equal?" 4
+.IX Item "How do I test whether two arrays or hashes are equal?"
+.IP "How do I find the first array element for which a condition is true?" 4
+.IX Item "How do I find the first array element for which a condition is true?"
+.IP "How do I handle linked lists?" 4
+.IX Item "How do I handle linked lists?"
+.IP "How do I handle circular lists?" 4
+.IX Xref "circular array Tie::Cycle Array::Iterator::Circular cycle modulus"
+.IX Item "How do I handle circular lists?"
+.IP "How do I shuffle an array randomly?" 4
+.IX Item "How do I shuffle an array randomly?"
+.IP "How do I process/modify each element of an array?" 4
+.IX Item "How do I process/modify each element of an array?"
+.IP "How do I select a random element from an array?" 4
+.IX Item "How do I select a random element from an array?"
+.IP "How do I permute N elements of a list?" 4
+.IX Xref "List::Permutor permute Algorithm::Loops Knuth The Art of Computer Programming Fischer-Krause"
+.IX Item "How do I permute N elements of a list?"
+.IP "How do I sort an array by (anything)?" 4
+.IX Item "How do I sort an array by (anything)?"
+.IP "How do I manipulate arrays of bits?" 4
+.IX Item "How do I manipulate arrays of bits?"
+.IP "Why does \fBdefined()\fR return true on empty arrays and hashes?" 4
+.IX Item "Why does defined() return true on empty arrays and hashes?"
+.RE
+.RS 4
+.RE
+.IP "Data: Hashes (Associative Arrays)" 4
+.IX Item "Data: Hashes (Associative Arrays)"
+.RS 4
+.IP "How do I process an entire hash?" 4
+.IX Item "How do I process an entire hash?"
+.IP "How do I merge two hashes?" 4
+.IX Xref "hash merge slice, hash"
+.IX Item "How do I merge two hashes?"
+.IP "What happens if I add or remove keys from a hash while iterating over it?" 4
+.IX Item "What happens if I add or remove keys from a hash while iterating over it?"
+.IP "How do I look up a hash element by value?" 4
+.IX Item "How do I look up a hash element by value?"
+.IP "How can I know how many entries are in a hash?" 4
+.IX Item "How can I know how many entries are in a hash?"
+.IP "How do I sort a hash (optionally by value instead of key)?" 4
+.IX Item "How do I sort a hash (optionally by value instead of key)?"
+.IP "How can I always keep my hash sorted?" 4
+.IX Xref "hash tie sort DB_File Tie::IxHash"
+.IX Item "How can I always keep my hash sorted?"
+.IP "What's the difference between ""delete"" and ""undef"" with hashes?" 4
+.IX Item "What's the difference between ""delete"" and ""undef"" with hashes?"
+.IP "Why don't my tied hashes make the defined/exists distinction?" 4
+.IX Item "Why don't my tied hashes make the defined/exists distinction?"
+.IP "How do I reset an \fBeach()\fR operation part-way through?" 4
+.IX Item "How do I reset an each() operation part-way through?"
+.IP "How can I get the unique keys from two hashes?" 4
+.IX Item "How can I get the unique keys from two hashes?"
+.IP "How can I store a multidimensional array in a DBM file?" 4
+.IX Item "How can I store a multidimensional array in a DBM file?"
+.IP "How can I make my hash remember the order I put elements into it?" 4
+.IX Item "How can I make my hash remember the order I put elements into it?"
+.IP "Why does passing a subroutine an undefined element in a hash create it?" 4
+.IX Item "Why does passing a subroutine an undefined element in a hash create it?"
+.IP "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?" 4
+.IX Item "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?"
+.IP "How can I use a reference as a hash key?" 4
+.IX Item "How can I use a reference as a hash key?"
+.IP "How can I check if a key exists in a multilevel hash?" 4
+.IX Item "How can I check if a key exists in a multilevel hash?"
+.IP "How can I prevent addition of unwanted keys into a hash?" 4
+.IX Item "How can I prevent addition of unwanted keys into a hash?"
+.RE
+.RS 4
+.RE
+.IP "Data: Misc" 4
+.IX Item "Data: Misc"
+.RS 4
+.IP "How do I handle binary data correctly?" 4
+.IX Item "How do I handle binary data correctly?"
+.IP "How do I determine whether a scalar is a number/whole/integer/float?" 4
+.IX Item "How do I determine whether a scalar is a number/whole/integer/float?"
+.IP "How do I keep persistent data across program calls?" 4
+.IX Item "How do I keep persistent data across program calls?"
+.IP "How do I print out or copy a recursive data structure?" 4
+.IX Item "How do I print out or copy a recursive data structure?"
+.IP "How do I define methods for every class/object?" 4
+.IX Item "How do I define methods for every class/object?"
+.IP "How do I verify a credit card checksum?" 4
+.IX Item "How do I verify a credit card checksum?"
+.IP "How do I pack arrays of doubles or floats for XS code?" 4
+.IX Item "How do I pack arrays of doubles or floats for XS code?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq5 \- Files and Formats"
+.IX Subsection "perlfaq5 - Files and Formats"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How do I flush/unbuffer an output filehandle? Why must I do this?" 4
+.IX Xref "flush buffer unbuffer autoflush"
+.IX Item "How do I flush/unbuffer an output filehandle? Why must I do this?"
+.IP "How do I change, delete, or insert a line in a file, or append to the beginning of a file?" 4
+.IX Xref "file, editing"
+.IX Item "How do I change, delete, or insert a line in a file, or append to the beginning of a file?"
+.IP "How do I count the number of lines in a file?" 4
+.IX Xref "file, counting lines lines line"
+.IX Item "How do I count the number of lines in a file?"
+.IP "How do I delete the last N lines from a file?" 4
+.IX Xref "lines file"
+.IX Item "How do I delete the last N lines from a file?"
+.ie n .IP "How can I use Perl's ""\-i"" option from within a program?" 4
+.el .IP "How can I use Perl's \f(CW\-i\fR option from within a program?" 4
+.IX Xref "-i in-place"
+.IX Item "How can I use Perl's -i option from within a program?"
+.IP "How can I copy a file?" 4
+.IX Xref "copy file, copy File::Copy"
+.IX Item "How can I copy a file?"
+.IP "How do I make a temporary file name?" 4
+.IX Xref "file, temporary"
+.IX Item "How do I make a temporary file name?"
+.IP "How can I manipulate fixed-record-length files?" 4
+.IX Xref "fixed-length file, fixed-length records"
+.IX Item "How can I manipulate fixed-record-length files?"
+.IP "How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?" 4
+.IX Xref "filehandle, local filehandle, passing filehandle, reference"
+.IX Item "How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?"
+.IP "How can I use a filehandle indirectly?" 4
+.IX Xref "filehandle, indirect"
+.IX Item "How can I use a filehandle indirectly?"
+.IP "How can I open a filehandle to a string?" 4
+.IX Xref "string open IO::String filehandle"
+.IX Item "How can I open a filehandle to a string?"
+.IP "How can I set up a footer format to be used with \fBwrite()\fR?" 4
+.IX Xref "footer"
+.IX Item "How can I set up a footer format to be used with write()?"
+.IP "How can I \fBwrite()\fR into a string?" 4
+.IX Xref "write, into a string"
+.IX Item "How can I write() into a string?"
+.IP "How can I output my numbers with commas added?" 4
+.IX Xref "number, commify"
+.IX Item "How can I output my numbers with commas added?"
+.IP "How can I translate tildes (~) in a filename?" 4
+.IX Xref "tilde tilde expansion"
+.IX Item "How can I translate tildes (~) in a filename?"
+.IP "How come when I open a file read-write it wipes it out?" 4
+.IX Xref "clobber read-write clobbering truncate truncating"
+.IX Item "How come when I open a file read-write it wipes it out?"
+.IP "Why do I sometimes get an ""Argument list too long"" when I use <*>?" 4
+.IX Xref "argument list too long"
+.IX Item "Why do I sometimes get an ""Argument list too long"" when I use <*>?"
+.IP "How can I open a file named with a leading "">"" or trailing blanks?" 4
+.IX Xref "filename, special characters"
+.IX Item "How can I open a file named with a leading "">"" or trailing blanks?"
+.IP "How can I reliably rename a file?" 4
+.IX Xref "rename mv move file, rename"
+.IX Item "How can I reliably rename a file?"
+.IP "How can I lock a file?" 4
+.IX Xref "lock file, lock flock"
+.IX Item "How can I lock a file?"
+.IP "Why can't I just open(FH, "">file.lock"")?" 4
+.IX Xref "lock, lockfile race condition"
+.IX Item "Why can't I just open(FH, "">file.lock"")?"
+.IP "I still don't get locking. I just want to increment the number in the file. How can I do this?" 4
+.IX Xref "counter file, counter"
+.IX Item "I still don't get locking. I just want to increment the number in the file. How can I do this?"
+.IP "All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?" 4
+.IX Xref "append file, append"
+.IX Item "All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?"
+.IP "How do I randomly update a binary file?" 4
+.IX Xref "file, binary patch"
+.IX Item "How do I randomly update a binary file?"
+.IP "How do I get a file's timestamp in perl?" 4
+.IX Xref "timestamp file, timestamp"
+.IX Item "How do I get a file's timestamp in perl?"
+.IP "How do I set a file's timestamp in perl?" 4
+.IX Xref "timestamp file, timestamp"
+.IX Item "How do I set a file's timestamp in perl?"
+.IP "How do I print to more than one file at once?" 4
+.IX Xref "print, to multiple files"
+.IX Item "How do I print to more than one file at once?"
+.IP "How can I read in an entire file all at once?" 4
+.IX Xref "slurp file, slurping"
+.IX Item "How can I read in an entire file all at once?"
+.IP "How can I read in a file by paragraphs?" 4
+.IX Xref "file, reading by paragraphs"
+.IX Item "How can I read in a file by paragraphs?"
+.IP "How can I read a single character from a file? From the keyboard?" 4
+.IX Xref "getc file, reading one character at a time"
+.IX Item "How can I read a single character from a file? From the keyboard?"
+.IP "How can I tell whether there's a character waiting on a filehandle?" 4
+.IX Item "How can I tell whether there's a character waiting on a filehandle?"
+.ie n .IP "How do I do a ""tail \-f"" in perl?" 4
+.el .IP "How do I do a \f(CWtail \-f\fR in perl?" 4
+.IX Xref "tail IO::Handle File::Tail clearerr"
+.IX Item "How do I do a tail -f in perl?"
+.IP "How do I \fBdup()\fR a filehandle in Perl?" 4
+.IX Xref "dup"
+.IX Item "How do I dup() a filehandle in Perl?"
+.IP "How do I close a file descriptor by number?" 4
+.IX Xref "file, closing file descriptors POSIX close"
+.IX Item "How do I close a file descriptor by number?"
+.IP "Why can't I use ""C:\etemp\efoo"" in DOS paths? Why doesn't `C:\etemp\efoo.exe` work?" 4
+.IX Xref "filename, DOS issues"
+.IX Item "Why can't I use ""C:tempfoo"" in DOS paths? Why doesn't `C:tempfoo.exe` work?"
+.IP "Why doesn't glob(""*.*"") get all the files?" 4
+.IX Xref "glob"
+.IX Item "Why doesn't glob(""*.*"") get all the files?"
+.ie n .IP "Why does Perl let me delete read-only files? Why does ""\-i"" clobber protected files? Isn't this a bug in Perl?" 4
+.el .IP "Why does Perl let me delete read-only files? Why does \f(CW\-i\fR clobber protected files? Isn't this a bug in Perl?" 4
+.IX Item "Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?"
+.IP "How do I select a random line from a file?" 4
+.IX Xref "file, selecting a random line"
+.IX Item "How do I select a random line from a file?"
+.IP "Why do I get weird spaces when I print an array of lines?" 4
+.IX Item "Why do I get weird spaces when I print an array of lines?"
+.IP "How do I traverse a directory tree?" 4
+.IX Item "How do I traverse a directory tree?"
+.IP "How do I delete a directory tree?" 4
+.IX Item "How do I delete a directory tree?"
+.IP "How do I copy an entire directory?" 4
+.IX Item "How do I copy an entire directory?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq6 \- Regular Expressions"
+.IX Subsection "perlfaq6 - Regular Expressions"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How can I hope to use regular expressions without creating illegible and unmaintainable code?" 4
+.IX Xref "regex, legibility regexp, legibility regular expression, legibility x"
+.IX Item "How can I hope to use regular expressions without creating illegible and unmaintainable code?"
+.PD
+Comments Outside the Regex, Comments Inside the Regex, Different Delimiters
+.IP "I'm having trouble matching over more than one line. What's wrong?" 4
+.IX Xref "regex, multiline regexp, multiline regular expression, multiline"
+.IX Item "I'm having trouble matching over more than one line. What's wrong?"
+.PD 0
+.IP "How can I pull out lines between two patterns that are themselves on different lines?" 4
+.IX Xref ".."
+.IX Item "How can I pull out lines between two patterns that are themselves on different lines?"
+.IP "How do I match XML, HTML, or other nasty, ugly things with a regex?" 4
+.IX Xref "regex, XML regex, HTML XML HTML pain frustration sucking out, will to live"
+.IX Item "How do I match XML, HTML, or other nasty, ugly things with a regex?"
+.IP "I put a regular expression into $/ but it didn't work. What's wrong?" 4
+.IX Xref "$ , regexes in $INPUT_RECORD_SEPARATOR, regexes in $RS, regexes in"
+.IX Item "I put a regular expression into $/ but it didn't work. What's wrong?"
+.IP "How do I substitute case-insensitively on the LHS while preserving case on the RHS?" 4
+.IX Xref "replace, case preserving substitute, case preserving substitution, case preserving s, case preserving"
+.IX Item "How do I substitute case-insensitively on the LHS while preserving case on the RHS?"
+.ie n .IP "How can I make ""\ew"" match national character sets?" 4
+.el .IP "How can I make \f(CW\ew\fR match national character sets?" 4
+.IX Xref "\\w"
+.IX Item "How can I make w match national character sets?"
+.ie n .IP "How can I match a locale-smart version of ""/[a\-zA\-Z]/""?" 4
+.el .IP "How can I match a locale-smart version of \f(CW/[a\-zA\-Z]/\fR?" 4
+.IX Xref "alpha"
+.IX Item "How can I match a locale-smart version of /[a-zA-Z]/?"
+.IP "How can I quote a variable to use in a regex?" 4
+.IX Xref "regex, escaping regexp, escaping regular expression, escaping"
+.IX Item "How can I quote a variable to use in a regex?"
+.ie n .IP "What is ""/o"" really for?" 4
+.el .IP "What is \f(CW/o\fR really for?" 4
+.IX Xref " o, regular expressions compile, regular expressions"
+.IX Item "What is /o really for?"
+.IP "How do I use a regular expression to strip C\-style comments from a file?" 4
+.IX Item "How do I use a regular expression to strip C-style comments from a file?"
+.IP "Can I use Perl regular expressions to match balanced text?" 4
+.IX Xref "regex, matching balanced test regexp, matching balanced test regular expression, matching balanced test possessive PARNO Text::Balanced Regexp::Common backtracking recursion"
+.IX Item "Can I use Perl regular expressions to match balanced text?"
+.IP "What does it mean that regexes are greedy? How can I get around it?" 4
+.IX Xref "greedy greediness"
+.IX Item "What does it mean that regexes are greedy? How can I get around it?"
+.IP "How do I process each word on each line?" 4
+.IX Xref "word"
+.IX Item "How do I process each word on each line?"
+.IP "How can I print out a word-frequency or line-frequency summary?" 4
+.IX Item "How can I print out a word-frequency or line-frequency summary?"
+.IP "How can I do approximate matching?" 4
+.IX Xref "match, approximate matching, approximate"
+.IX Item "How can I do approximate matching?"
+.IP "How do I efficiently match many regular expressions at once?" 4
+.IX Xref "regex, efficiency regexp, efficiency regular expression, efficiency"
+.IX Item "How do I efficiently match many regular expressions at once?"
+.ie n .IP "Why don't word-boundary searches with ""\eb"" work for me?" 4
+.el .IP "Why don't word-boundary searches with \f(CW\eb\fR work for me?" 4
+.IX Xref "\\b"
+.IX Item "Why don't word-boundary searches with b work for me?"
+.IP "Why does using $&, $`, or $' slow my program down?" 4
+.IX Xref "$MATCH $& $POSTMATCH $' $PREMATCH $`"
+.IX Item "Why does using $&, $`, or $' slow my program down?"
+.ie n .IP "What good is ""\eG"" in a regular expression?" 4
+.el .IP "What good is \f(CW\eG\fR in a regular expression?" 4
+.IX Xref "\\G"
+.IX Item "What good is G in a regular expression?"
+.IP "Are Perl regexes DFAs or NFAs? Are they POSIX compliant?" 4
+.IX Xref "DFA NFA POSIX"
+.IX Item "Are Perl regexes DFAs or NFAs? Are they POSIX compliant?"
+.IP "What's wrong with using grep in a void context?" 4
+.IX Xref "grep"
+.IX Item "What's wrong with using grep in a void context?"
+.IP "How can I match strings with multibyte characters?" 4
+.IX Xref "regex, and multibyte characters regexp, and multibyte characters regular expression, and multibyte characters martian encoding, Martian"
+.IX Item "How can I match strings with multibyte characters?"
+.IP "How do I match a regular expression that's in a variable?" 4
+.IX Xref "regex, in variable eval regex quotemeta \\Q, regex \\E, regex qr"
+.IX Item "How do I match a regular expression that's in a variable?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq7 \- General Perl Language Issues"
+.IX Subsection "perlfaq7 - General Perl Language Issues"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Can I get a BNF/yacc/RE for the Perl language?" 4
+.IX Item "Can I get a BNF/yacc/RE for the Perl language?"
+.IP "What are all these $@%&* punctuation signs, and how do I know when to use them?" 4
+.IX Item "What are all these $@%&* punctuation signs, and how do I know when to use them?"
+.IP "Do I always/never have to quote my strings or use semicolons and commas?" 4
+.IX Item "Do I always/never have to quote my strings or use semicolons and commas?"
+.IP "How do I skip some return values?" 4
+.IX Item "How do I skip some return values?"
+.IP "How do I temporarily block warnings?" 4
+.IX Item "How do I temporarily block warnings?"
+.IP "What's an extension?" 4
+.IX Item "What's an extension?"
+.IP "Why do Perl operators have different precedence than C operators?" 4
+.IX Item "Why do Perl operators have different precedence than C operators?"
+.IP "How do I declare/create a structure?" 4
+.IX Item "How do I declare/create a structure?"
+.IP "How do I create a module?" 4
+.IX Item "How do I create a module?"
+.IP "How do I adopt or take over a module already on CPAN?" 4
+.IX Item "How do I adopt or take over a module already on CPAN?"
+.IP "How do I create a class?" 4
+.IX Xref "class, creation package"
+.IX Item "How do I create a class?"
+.IP "How can I tell if a variable is tainted?" 4
+.IX Item "How can I tell if a variable is tainted?"
+.IP "What's a closure?" 4
+.IX Item "What's a closure?"
+.IP "What is variable suicide and how can I prevent it?" 4
+.IX Item "What is variable suicide and how can I prevent it?"
+.IP "How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?" 4
+.IX Item "How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?"
+.PD
+Passing Variables and Functions, Passing Filehandles, Passing Regexes,
+Passing Methods
+.IP "How do I create a static variable?" 4
+.IX Item "How do I create a static variable?"
+.PD 0
+.IP "What's the difference between dynamic and lexical (static) scoping? Between \fBlocal()\fR and \fBmy()\fR?" 4
+.IX Item "What's the difference between dynamic and lexical (static) scoping? Between local() and my()?"
+.IP "How can I access a dynamic variable while a similarly named lexical is in scope?" 4
+.IX Item "How can I access a dynamic variable while a similarly named lexical is in scope?"
+.IP "What's the difference between deep and shallow binding?" 4
+.IX Item "What's the difference between deep and shallow binding?"
+.IP "Why doesn't ""my($foo) = <$fh>;"" work right?" 4
+.IX Item "Why doesn't ""my($foo) = <$fh>;"" work right?"
+.IP "How do I redefine a builtin function, operator, or method?" 4
+.IX Item "How do I redefine a builtin function, operator, or method?"
+.IP "What's the difference between calling a function as &foo and \fBfoo()\fR?" 4
+.IX Item "What's the difference between calling a function as &foo and foo()?"
+.IP "How do I create a switch or case statement?" 4
+.IX Item "How do I create a switch or case statement?"
+.IP "How can I catch accesses to undefined variables, functions, or methods?" 4
+.IX Item "How can I catch accesses to undefined variables, functions, or methods?"
+.IP "Why can't a method included in this same file be found?" 4
+.IX Item "Why can't a method included in this same file be found?"
+.IP "How can I find out my current or calling package?" 4
+.IX Item "How can I find out my current or calling package?"
+.IP "How can I comment out a large block of Perl code?" 4
+.IX Item "How can I comment out a large block of Perl code?"
+.IP "How do I clear a package?" 4
+.IX Item "How do I clear a package?"
+.IP "How can I use a variable as a variable name?" 4
+.IX Item "How can I use a variable as a variable name?"
+.IP "What does ""bad interpreter"" mean?" 4
+.IX Item "What does ""bad interpreter"" mean?"
+.IP "Do I need to recompile XS modules when there is a change in the C library?" 4
+.IX Item "Do I need to recompile XS modules when there is a change in the C library?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq8 \- System Interaction"
+.IX Subsection "perlfaq8 - System Interaction"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How do I find out which operating system I'm running under?" 4
+.IX Item "How do I find out which operating system I'm running under?"
+.IP "How come \fBexec()\fR doesn't return?" 4
+.IX Xref "exec system fork open pipe"
+.IX Item "How come exec() doesn't return?"
+.IP "How do I do fancy stuff with the keyboard/screen/mouse?" 4
+.IX Item "How do I do fancy stuff with the keyboard/screen/mouse?"
+.PD
+Keyboard, Screen, Mouse
+.IP "How do I print something out in color?" 4
+.IX Item "How do I print something out in color?"
+.PD 0
+.IP "How do I read just one key without waiting for a return key?" 4
+.IX Item "How do I read just one key without waiting for a return key?"
+.IP "How do I check whether input is ready on the keyboard?" 4
+.IX Item "How do I check whether input is ready on the keyboard?"
+.IP "How do I clear the screen?" 4
+.IX Item "How do I clear the screen?"
+.IP "How do I get the screen size?" 4
+.IX Item "How do I get the screen size?"
+.IP "How do I ask the user for a password?" 4
+.IX Item "How do I ask the user for a password?"
+.IP "How do I read and write the serial port?" 4
+.IX Item "How do I read and write the serial port?"
+.PD
+lockfiles, open mode, end of line, flushing output, non-blocking input
+.IP "How do I decode encrypted password files?" 4
+.IX Item "How do I decode encrypted password files?"
+.PD 0
+.IP "How do I start a process in the background?" 4
+.IX Item "How do I start a process in the background?"
+.PD
+STDIN, STDOUT, and STDERR are shared, Signals, Zombies
+.IP "How do I trap control characters/signals?" 4
+.IX Item "How do I trap control characters/signals?"
+.PD 0
+.IP "How do I modify the shadow password file on a Unix system?" 4
+.IX Item "How do I modify the shadow password file on a Unix system?"
+.IP "How do I set the time and date?" 4
+.IX Item "How do I set the time and date?"
+.IP "How can I \fBsleep()\fR or \fBalarm()\fR for under a second?" 4
+.IX Xref "Time::HiRes BSD::Itimer sleep select"
+.IX Item "How can I sleep() or alarm() for under a second?"
+.IP "How can I measure time under a second?" 4
+.IX Xref "Time::HiRes BSD::Itimer sleep select"
+.IX Item "How can I measure time under a second?"
+.IP "How can I do an \fBatexit()\fR or \fBsetjmp()\fR/\fBlongjmp()\fR? (Exception handling)" 4
+.IX Item "How can I do an atexit() or setjmp()/longjmp()? (Exception handling)"
+.IP "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?" 4
+.IX Item "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?"
+.IP "How can I call my system's unique C functions from Perl?" 4
+.IX Item "How can I call my system's unique C functions from Perl?"
+.IP "Where do I get the include files to do \fBioctl()\fR or \fBsyscall()\fR?" 4
+.IX Item "Where do I get the include files to do ioctl() or syscall()?"
+.IP "Why do setuid perl scripts complain about kernel problems?" 4
+.IX Item "Why do setuid perl scripts complain about kernel problems?"
+.IP "How can I open a pipe both to and from a command?" 4
+.IX Item "How can I open a pipe both to and from a command?"
+.IP "Why can't I get the output of a command with \fBsystem()\fR?" 4
+.IX Item "Why can't I get the output of a command with system()?"
+.IP "How can I capture STDERR from an external command?" 4
+.IX Item "How can I capture STDERR from an external command?"
+.IP "Why doesn't \fBopen()\fR return an error when a pipe open fails?" 4
+.IX Item "Why doesn't open() return an error when a pipe open fails?"
+.IP "What's wrong with using backticks in a void context?" 4
+.IX Item "What's wrong with using backticks in a void context?"
+.IP "How can I call backticks without shell processing?" 4
+.IX Item "How can I call backticks without shell processing?"
+.IP "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?" 4
+.IX Item "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?"
+.IP "How can I convert my shell script to perl?" 4
+.IX Item "How can I convert my shell script to perl?"
+.IP "Can I use perl to run a telnet or ftp session?" 4
+.IX Item "Can I use perl to run a telnet or ftp session?"
+.IP "How can I write expect in Perl?" 4
+.IX Item "How can I write expect in Perl?"
+.IP "Is there a way to hide perl's command line from programs such as ""ps""?" 4
+.IX Item "Is there a way to hide perl's command line from programs such as ""ps""?"
+.IP "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?" 4
+.IX Item "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?"
+.PD
+Unix
+.IP "How do I close a process's filehandle without waiting for it to complete?" 4
+.IX Item "How do I close a process's filehandle without waiting for it to complete?"
+.PD 0
+.IP "How do I fork a daemon process?" 4
+.IX Item "How do I fork a daemon process?"
+.IP "How do I find out if I'm running interactively or not?" 4
+.IX Item "How do I find out if I'm running interactively or not?"
+.IP "How do I timeout a slow event?" 4
+.IX Item "How do I timeout a slow event?"
+.IP "How do I set CPU limits?" 4
+.IX Xref "BSD::Resource limit CPU"
+.IX Item "How do I set CPU limits?"
+.IP "How do I avoid zombies on a Unix system?" 4
+.IX Item "How do I avoid zombies on a Unix system?"
+.IP "How do I use an SQL database?" 4
+.IX Item "How do I use an SQL database?"
+.IP "How do I make a \fBsystem()\fR exit on control-C?" 4
+.IX Item "How do I make a system() exit on control-C?"
+.IP "How do I open a file without blocking?" 4
+.IX Item "How do I open a file without blocking?"
+.IP "How do I tell the difference between errors from the shell and perl?" 4
+.IX Item "How do I tell the difference between errors from the shell and perl?"
+.IP "How do I install a module from CPAN?" 4
+.IX Item "How do I install a module from CPAN?"
+.IP "What's the difference between require and use?" 4
+.IX Item "What's the difference between require and use?"
+.IP "How do I keep my own module/library directory?" 4
+.IX Item "How do I keep my own module/library directory?"
+.IP "How do I add the directory my program lives in to the module/library search path?" 4
+.IX Item "How do I add the directory my program lives in to the module/library search path?"
+.IP "How do I add a directory to my include path (@INC) at runtime?" 4
+.IX Item "How do I add a directory to my include path (@INC) at runtime?"
+.PD
+the \f(CW\*(C`PERLLIB\*(C'\fR environment variable, the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable,
+the \f(CW\*(C`perl \-Idir\*(C'\fR command line flag, the \f(CW\*(C`lib\*(C'\fR pragma:, the local::lib
+module:
+.IP "Where are modules installed?" 4
+.IX Item "Where are modules installed?"
+.PD 0
+.IP "What is socket.ph and where do I get it?" 4
+.IX Item "What is socket.ph and where do I get it?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlfaq9 \- Web, Email and Networking"
+.IX Subsection "perlfaq9 - Web, Email and Networking"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Should I use a web framework?" 4
+.IX Item "Should I use a web framework?"
+.IP "Which web framework should I use?" 4
+.IX Xref "framework CGI.pm CGI Catalyst Dancer"
+.IX Item "Which web framework should I use?"
+.PD
+Catalyst, Dancer2, Mojolicious, Web::Simple
+.IP "What is Plack and PSGI?" 4
+.IX Item "What is Plack and PSGI?"
+.PD 0
+.IP "How do I remove HTML from a string?" 4
+.IX Item "How do I remove HTML from a string?"
+.IP "How do I extract URLs?" 4
+.IX Item "How do I extract URLs?"
+.IP "How do I fetch an HTML file?" 4
+.IX Item "How do I fetch an HTML file?"
+.IP "How do I automate an HTML form submission?" 4
+.IX Item "How do I automate an HTML form submission?"
+.IP "How do I decode or create those %\-encodings on the web?" 4
+.IX Xref "URI URI::Escape RFC 2396"
+.IX Item "How do I decode or create those %-encodings on the web?"
+.IP "How do I redirect to another page?" 4
+.IX Item "How do I redirect to another page?"
+.IP "How do I put a password on my web pages?" 4
+.IX Item "How do I put a password on my web pages?"
+.IP "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?" 4
+.IX Item "How do I make sure users can't enter values into a form that causes my CGI script to do bad things?"
+.IP "How do I parse a mail header?" 4
+.IX Item "How do I parse a mail header?"
+.IP "How do I check a valid mail address?" 4
+.IX Item "How do I check a valid mail address?"
+.IP "How do I decode a MIME/BASE64 string?" 4
+.IX Item "How do I decode a MIME/BASE64 string?"
+.IP "How do I find the user's mail address?" 4
+.IX Item "How do I find the user's mail address?"
+.IP "How do I send email?" 4
+.IX Item "How do I send email?"
+.PD
+Email::Sender::Transport::Sendmail, Email::Sender::Transport::SMTP
+.IP "How do I use MIME to make an attachment to a mail message?" 4
+.IX Item "How do I use MIME to make an attachment to a mail message?"
+.PD 0
+.IP "How do I read email?" 4
+.IX Item "How do I read email?"
+.IP "How do I find out my hostname, domainname, or IP address?" 4
+.IX Xref "hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa, gethostbyname, Socket, Net::Domain, Sys::Hostname"
+.IX Item "How do I find out my hostname, domainname, or IP address?"
+.IP "How do I fetch/put an (S)FTP file?" 4
+.IX Item "How do I fetch/put an (S)FTP file?"
+.IP "How can I do RPC in Perl?" 4
+.IX Item "How can I do RPC in Perl?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "perlsyn \- Perl syntax"
+.IX Subsection "perlsyn - Perl syntax"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP Declarations 4
+.IX Xref "declaration undef undefined uninitialized"
+.IX Item "Declarations"
+.IP Comments 4
+.IX Xref "comment #"
+.IX Item "Comments"
+.IP "Simple Statements" 4
+.IX Xref "statement semicolon expression ;"
+.IX Item "Simple Statements"
+.IP "Statement Modifiers" 4
+.IX Xref "statement modifier modifier if unless while until when foreach for"
+.IX Item "Statement Modifiers"
+.IP "Compound Statements" 4
+.IX Xref "statement, compound block bracket, curly curly bracket brace { } if unless given while until foreach for continue"
+.IX Item "Compound Statements"
+.IP "Loop Control" 4
+.IX Xref "loop control loop, control next last redo continue"
+.IX Item "Loop Control"
+.IP "For Loops" 4
+.IX Xref "for foreach"
+.IX Item "For Loops"
+.IP "Foreach Loops" 4
+.IX Xref "for foreach"
+.IX Item "Foreach Loops"
+.IP "Try Catch Exception Handling" 4
+.IX Xref "try catch finally"
+.IX Item "Try Catch Exception Handling"
+.IP "Basic BLOCKs" 4
+.IX Xref "block"
+.IX Item "Basic BLOCKs"
+.IP "defer blocks" 4
+.IX Xref "defer"
+.IX Item "defer blocks"
+.IP "Switch Statements" 4
+.IX Item "Switch Statements"
+.IP Goto 4
+.IX Xref "goto"
+.IX Item "Goto"
+.IP "The Ellipsis Statement" 4
+.IX Xref "... ... statement ellipsis operator elliptical statement unimplemented statement unimplemented operator yada-yada yada-yada operator ... operator whatever operator triple-dot operator"
+.IX Item "The Ellipsis Statement"
+.IP "PODs: Embedded Documentation" 4
+.IX Xref "POD documentation"
+.IX Item "PODs: Embedded Documentation"
+.IP "Plain Old Comments (Not!)" 4
+.IX Xref "comment line # preprocessor eval"
+.IX Item "Plain Old Comments (Not!)"
+.IP "Experimental Details on given and when" 4
+.IX Item "Experimental Details on given and when"
+.PD
+1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+.RE
+.RS 4
+.RE
+.SS "perldata \- Perl data types"
+.IX Subsection "perldata - Perl data types"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Variable names" 4
+.IX Xref "variable, name variable name data type type"
+.IX Item "Variable names"
+.IP "Identifier parsing" 4
+.IX Xref "identifiers"
+.IX Item "Identifier parsing"
+.IP Context 4
+.IX Xref "context scalar context list context"
+.IX Item "Context"
+.IP "Scalar values" 4
+.IX Xref "scalar number string reference"
+.IX Item "Scalar values"
+.IP "Scalar value constructors" 4
+.IX Xref "scalar, literal scalar, constant"
+.IX Item "Scalar value constructors"
+.IP "List value constructors" 4
+.IX Xref "list"
+.IX Item "List value constructors"
+.IP Subscripts 4
+.IX Item "Subscripts"
+.IP "Multi-dimensional array emulation" 4
+.IX Item "Multi-dimensional array emulation"
+.IP Slices 4
+.IX Xref "slice array, slice hash, slice"
+.IX Item "Slices"
+.IP "Typeglobs and Filehandles" 4
+.IX Xref "typeglob filehandle *"
+.IX Item "Typeglobs and Filehandles"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlop \- Perl operators and precedence"
+.IX Subsection "perlop - Perl operators and precedence"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Operator Precedence and Associativity" 4
+.IX Xref "operator, precedence precedence associativity"
+.IX Item "Operator Precedence and Associativity"
+.IP "Terms and List Operators (Leftward)" 4
+.IX Xref "list operator operator, list term"
+.IX Item "Terms and List Operators (Leftward)"
+.IP "The Arrow Operator" 4
+.IX Xref "arrow dereference ->"
+.IX Item "The Arrow Operator"
+.IP "Auto-increment and Auto-decrement" 4
+.IX Xref "increment auto-increment ++ decrement auto-decrement --"
+.IX Item "Auto-increment and Auto-decrement"
+.IP Exponentiation 4
+.IX Xref "** exponentiation power"
+.IX Item "Exponentiation"
+.IP "Symbolic Unary Operators" 4
+.IX Xref "unary operator operator, unary"
+.IX Item "Symbolic Unary Operators"
+.IP "Binding Operators" 4
+.IX Xref "binding operator, binding =~ !~"
+.IX Item "Binding Operators"
+.IP "Multiplicative Operators" 4
+.IX Xref "operator, multiplicative"
+.IX Item "Multiplicative Operators"
+.IP "Additive Operators" 4
+.IX Xref "operator, additive"
+.IX Item "Additive Operators"
+.IP "Shift Operators" 4
+.IX Xref "shift operator operator, shift << >> right shift left shift bitwise shift shl shr shift, right shift, left"
+.IX Item "Shift Operators"
+.IP "Named Unary Operators" 4
+.IX Xref "operator, named unary"
+.IX Item "Named Unary Operators"
+.IP "Relational Operators" 4
+.IX Xref "relational operator operator, relational"
+.IX Item "Relational Operators"
+.IP "Equality Operators" 4
+.IX Xref "equality equal equals operator, equality"
+.IX Item "Equality Operators"
+.IP "Class Instance Operator" 4
+.IX Xref "isa operator"
+.IX Item "Class Instance Operator"
+.IP "Smartmatch Operator" 4
+.IX Item "Smartmatch Operator"
+.PD
+1. Empty hashes or arrays match, 2. That is, each element smartmatches the
+element of the same index in the other array.[3], 3. If a circular
+reference is found, fall back to referential equality, 4. Either an actual
+number, or a string that looks like one
+.IP "Bitwise And" 4
+.IX Xref "operator, bitwise, and bitwise and &"
+.IX Item "Bitwise And"
+.PD 0
+.IP "Bitwise Or and Exclusive Or" 4
+.IX Xref "operator, bitwise, or bitwise or | operator, bitwise, xor bitwise xor ^"
+.IX Item "Bitwise Or and Exclusive Or"
+.IP "C\-style Logical And" 4
+.IX Xref "&& logical and operator, logical, and"
+.IX Item "C-style Logical And"
+.IP "C\-style Logical Or" 4
+.IX Xref "|| operator, logical, or"
+.IX Item "C-style Logical Or"
+.IP "Logical Defined-Or" 4
+.IX Xref "operator, logical, defined-or"
+.IX Item "Logical Defined-Or"
+.IP "Range Operators" 4
+.IX Xref "operator, range range .. ..."
+.IX Item "Range Operators"
+.IP "Conditional Operator" 4
+.IX Xref "operator, conditional operator, ternary ternary ?:"
+.IX Item "Conditional Operator"
+.IP "Assignment Operators" 4
+.IX Xref "assignment operator, assignment = **= += *= &= <<= &&= -= = |= >>= ||= = .= %= ^= x= &.= |.= ^.="
+.IX Item "Assignment Operators"
+.IP "Comma Operator" 4
+.IX Xref "comma operator, comma ,"
+.IX Item "Comma Operator"
+.IP "List Operators (Rightward)" 4
+.IX Xref "operator, list, rightward list operator"
+.IX Item "List Operators (Rightward)"
+.IP "Logical Not" 4
+.IX Xref "operator, logical, not not"
+.IX Item "Logical Not"
+.IP "Logical And" 4
+.IX Xref "operator, logical, and and"
+.IX Item "Logical And"
+.IP "Logical or and Exclusive Or" 4
+.IX Xref "operator, logical, or operator, logical, xor operator, logical, exclusive or or xor"
+.IX Item "Logical or and Exclusive Or"
+.IP "C Operators Missing From Perl" 4
+.IX Xref "operator, missing from perl & * typecasting (TYPE)"
+.IX Item "C Operators Missing From Perl"
+.PD
+unary &, unary *, (TYPE)
+.IP "Quote and Quote-like Operators" 4
+.IX Xref "operator, quote operator, quote-like q qq qx qw m qr s tr ' '' "" """" ` `` << escape sequence escape"
+.IX Item "Quote and Quote-like Operators"
+[1], [2], [3], [4], [5], [6], [7], [8]
+.IP "Regexp Quote-Like Operators" 4
+.IX Xref "operator, regexp"
+.IX Item "Regexp Quote-Like Operators"
+\&\f(CW\*(C`qr/\fR\f(CISTRING\fR\f(CW/msixpodualn\*(C'\fR       ,
+\&\f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\*(C'\fR   
+        
+ , \f(CW\*(C`/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\*(C'\fR, The empty pattern \f(CW\*(C`//\*(C'\fR,
+Matching in list context, \f(CW\*(C`\eG \fR\f(CIassertion\fR\f(CW\*(C'\fR, \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?msixpodualngc\*(C'\fR
+ ,
+\&\f(CW\*(C`s/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/msixpodualngcer\*(C'\fR
+.IX Xref "qr i m o s x p m operator, match regexp, options regexp regex, options regex m s i x p o g c ? operator, match-once s substitute substitution replace regexp, replace regexp, substitute m s i x p o g c e r"
+.IP "Quote-Like Operators" 4
+.IX Xref "operator, quote-like"
+.IX Item "Quote-Like Operators"
+\&\f(CW\*(C`q/\fR\f(CISTRING\fR\f(CW/\*(C'\fR    , \f(CW\*(Aq\fR\f(CISTRING\fR\f(CW\*(Aq\fR,
+\&\f(CW\*(C`qq/\fR\f(CISTRING\fR\f(CW/\*(C'\fR    , \f(CW"\fR\f(CISTRING\fR\f(CW"\fR,
+\&\f(CW\*(C`qx/\fR\f(CISTRING\fR\f(CW/\*(C'\fR    , \f(CW\`\fR\f(CISTRING\fR\f(CW\`\fR,
+\&\f(CW\*(C`qw/\fR\f(CISTRING\fR\f(CW/\*(C'\fR   ,
+\&\f(CW\*(C`tr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\*(C'\fR   
+  , \f(CW\*(C`y/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\*(C'\fR, \f(CW\*(C`<<\fR\f(CIEOF\fR\f(CW\*(C'\fR    , Double Quotes,
+Single Quotes, Backticks, Indented Here-docs
+.IX Xref "q quote, single ' '' qq quote, double "" """" qx ` `` backtick qw quote, list quote, words tr y transliterate c d s here-doc heredoc here-document <<"
+.IP "Gory details of parsing quoted constructs" 4
+.IX Xref "quote, gory details"
+.IX Item "Gory details of parsing quoted constructs"
+Finding the end, Interpolation , \f(CW\*(C`<<\*(AqEOF\*(Aq\*(C'\fR,  \f(CW\*(C`m\*(Aq\*(Aq\*(C'\fR, the
+pattern of \f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR, \f(CW\*(Aq\*(Aq\fR, \f(CW\*(C`q//\*(C'\fR, \f(CW\*(C`tr\*(Aq\*(Aq\*(Aq\*(C'\fR, \f(CW\*(C`y\*(Aq\*(Aq\*(Aq\*(C'\fR, the replacement of
+\&\f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR, \f(CW\*(C`y///\*(C'\fR, \f(CW""\fR, \f(CW\`\`\fR, \f(CW\*(C`qq//\*(C'\fR, \f(CW\*(C`qx//\*(C'\fR, \f(CW\*(C`<file*glob>\*(C'\fR, \f(CW\*(C`<<"EOF"\*(C'\fR, The replacement of \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`RE\*(C'\fR in \f(CW\*(C`m?RE?\*(C'\fR, \f(CW\*(C`/RE/\*(C'\fR,
+\&\f(CW\*(C`m/RE/\*(C'\fR, \f(CW\*(C`s/RE/foo/\*(C'\fR,, Parsing regular expressions ,
+Optimization of regular expressions
+.IX Xref "interpolation regexp, parse regexp, optimization"
+.IP "I/O Operators" 4
+.IX Xref "operator, i o operator, io io while filehandle <> <<>> @ARGV"
+.IX Item "I/O Operators"
+.PD 0
+.IP "Constant Folding" 4
+.IX Xref "constant folding folding"
+.IX Item "Constant Folding"
+.IP No-ops 4
+.IX Xref "no-op nop"
+.IX Item "No-ops"
+.IP "Bitwise String Operators" 4
+.IX Xref "operator, bitwise, string &. |. ^. ~."
+.IX Item "Bitwise String Operators"
+.IP "Integer Arithmetic" 4
+.IX Xref "integer"
+.IX Item "Integer Arithmetic"
+.IP "Floating-point Arithmetic" 4
+.IX Item "Floating-point Arithmetic"
+.IP "Bigger Numbers" 4
+.IX Xref "number, arbitrary precision"
+.IX Item "Bigger Numbers"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlsub \- Perl subroutines"
+.IX Subsection "perlsub - Perl subroutines"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+documented later in this document, documented in perlmod, documented in
+perlobj, documented in perltie, documented in PerlIO::via,
+documented in perlfunc, documented in UNIVERSAL, documented in
+perldebguts, undocumented, used internally by the overload feature
+.RS 4
+.IP Signatures 4
+.IX Item "Signatures"
+.PD 0
+.IP "Private Variables via \fBmy()\fR" 4
+.IX Xref "my variable, lexical lexical lexical variable scope, lexical lexical scope attributes, my"
+.IX Item "Private Variables via my()"
+.IP "Persistent Private Variables" 4
+.IX Xref "state state variable static variable, persistent variable, static closure"
+.IX Item "Persistent Private Variables"
+.IP "Temporary Values via \fBlocal()\fR" 4
+.IX Xref "local scope, dynamic dynamic scope variable, local variable, temporary"
+.IX Item "Temporary Values via local()"
+.IP "Lvalue subroutines" 4
+.IX Xref "lvalue subroutine, lvalue"
+.IX Item "Lvalue subroutines"
+.IP "Lexical Subroutines" 4
+.IX Xref "my sub state sub our sub subroutine, lexical"
+.IX Item "Lexical Subroutines"
+.IP "Passing Symbol Table Entries (typeglobs)" 4
+.IX Xref "typeglob *"
+.IX Item "Passing Symbol Table Entries (typeglobs)"
+.IP "When to Still Use \fBlocal()\fR" 4
+.IX Xref "local variable, local"
+.IX Item "When to Still Use local()"
+.IP "Pass by Reference" 4
+.IX Xref "pass by reference pass-by-reference reference"
+.IX Item "Pass by Reference"
+.IP Prototypes 4
+.IX Xref "prototype subroutine, prototype"
+.IX Item "Prototypes"
+.IP "Constant Functions" 4
+.IX Xref "constant"
+.IX Item "Constant Functions"
+.IP "Overriding Built-in Functions" 4
+.IX Xref "built-in override CORE CORE::GLOBAL"
+.IX Item "Overriding Built-in Functions"
+.IP Autoloading 4
+.IX Xref "autoloading AUTOLOAD"
+.IX Item "Autoloading"
+.IP "Subroutine Attributes" 4
+.IX Xref "attribute subroutine, attribute attrs"
+.IX Item "Subroutine Attributes"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlfunc \- Perl builtin functions"
+.IX Subsection "perlfunc - Perl builtin functions"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Perl Functions by Category" 4
+.IX Xref "function"
+.IX Item "Perl Functions by Category"
+.PD
+Functions for SCALARs or strings   , Regular
+expressions and pattern matching   ,
+Numeric functions    ,
+Functions for real \f(CW@ARRAYs\fR , Functions for list data ,
+Functions for real \f(CW%HASHes\fR , Input and output functions 
+  , Functions for fixed-length data or records,
+Functions for filehandles, files, or directories  
+   , Keywords related to the control
+flow of your Perl program , Keywords related to scoping,
+Miscellaneous functions, Functions for processes and process groups
+  , Keywords related to Perl modules
+, Keywords related to classes and object-orientation 
+ , Low-level socket functions  , System V
+interprocess communication functions   
+  , Fetching user and group info 
+      , Fetching
+network info      
+, Time-related functions  , Non-function keywords
+.IX Xref "scalar string character regular expression regex regexp numeric number trigonometric trigonometry array list hash I O input output dbm file filehandle directory pipe link symlink control flow process pid process id module object class package socket sock IPC System V semaphore shared memory memory message user group password uid gid passwd etc passwd network protocol host hostname IP address service time date"
+.IP Portability 4
+.IX Xref "portability Unix portable"
+.IX Item "Portability"
+.PD 0
+.IP "Alphabetical Listing of Perl Functions" 4
+.IX Item "Alphabetical Listing of Perl Functions"
+.PD
+\&\-\fIX\fR FILEHANDLE
+
+, \-\fIX\fR EXPR,
+\&\-\fIX\fR DIRHANDLE, \-\fIX\fR, abs VALUE  , abs, accept
+NEWSOCKET,GENERICSOCKET , alarm SECONDS  
+, alarm, atan2 Y,X    , bind
+SOCKET,NAME , binmode FILEHANDLE, LAYER   
+ , binmode FILEHANDLE, bless REF,CLASSNAME , bless
+REF, Bless the referred-to item into a specific package (recommended
+form):, Bless the referred-to item into package \f(CW\*(C`main\*(C'\fR:, Bless the
+referred-to item into the current package (not inheritable):, break, caller
+EXPR    , caller, chdir EXPR
+  , chdir FILEHANDLE, chdir DIRHANDLE,
+chdir, chmod LIST   , chomp VARIABLE 
+   , chomp( LIST ), chomp,
+chop VARIABLE , chop( LIST ), chop, chown LIST  
+ , chr NUMBER    , chr,
+chroot FILENAME  , chroot, class NAMESPACE, class NAMESPACE
+VERSION, class NAMESPACE BLOCK, class NAMESPACE VERSION BLOCK, close
+FILEHANDLE , close, closedir DIRHANDLE , connect
+SOCKET,NAME , continue BLOCK , continue, cos EXPR
+   , cos, crypt PLAINTEXT,SALT 
+     
+  , dbmclose HASH , dbmopen
+HASH,DBNAME,MASK     , defined EXPR
+  , defined, delete EXPR , die LIST
+     , do BLOCK 
+, do EXPR , dump LABEL   , dump EXPR,
+dump, each HASH  , each ARRAY ,
+eof FILEHANDLE   , eof (), eof, eval EXPR
+      
+, eval BLOCK, eval, String eval, Under the
+\&\f(CW"unicode_eval"\fR feature, Outside the \f(CW"unicode_eval"\fR feature, If upgraded, \f(CW$v\fR will
+be \f(CW"\exc4\ex80"\fR (i.e., the \f(CW\*(C`use utf8\*(C'\fR has no effect.), If non-upgraded,
+\&\f(CW$v\fR will be \f(CW"\ex{100}"\fR, Block eval, evalbytes EXPR ,
+evalbytes, exec LIST  , exec PROGRAM LIST, exists EXPR
+ , exit EXPR   ,
+exit, exp EXPR     , exp,
+fc EXPR     , fc, fcntl
+FILEHANDLE,FUNCTION,SCALAR , _\|_FILE_\|_ , field VARNAME
+, fileno FILEHANDLE , fileno DIRHANDLE, flock
+FILEHANDLE,OPERATION   , fork  
+, format , formline PICTURE,LIST , getc
+FILEHANDLE    , getc, getlogin
+ , getpeername SOCKET  , getpgrp
+PID  , getppid   , getpriority
+WHICH,WHO   , getpwnam NAME 
+    
+   
+    
+    
+    
+    ,
+getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname NAME,
+getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr
+ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER,
+getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent,
+getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent
+STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent,
+endhostent, endnetent, endprotoent, endservent, getsockname SOCKET
+, getsockopt SOCKET,LEVEL,OPTNAME , glob EXPR
+   , glob, gmtime EXPR
+  , gmtime, goto LABEL   ,
+goto EXPR, goto &NAME, grep BLOCK LIST , grep EXPR,LIST, hex EXPR
+ , hex, import LIST , index
+STR,SUBSTR,POSITION   , index STR,SUBSTR, int
+EXPR     , int, ioctl
+FILEHANDLE,FUNCTION,SCALAR , join EXPR,LIST , keys HASH
+ , keys ARRAY, kill SIGNAL, LIST, kill SIGNAL 
+, last LABEL  , last EXPR, last, lc EXPR 
+, lc, If \f(CW\*(C`use bytes\*(C'\fR is in effect:, Otherwise, if \f(CW\*(C`use
+locale\*(C'\fR for \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect:, Otherwise, If EXPR has the UTF8 flag
+set:, Otherwise, if \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR or \f(CWuse locale
+\&\*(Aq:not_characters\*(Aq\fR is in effect:, Otherwise:, lcfirst EXPR 
+, lcfirst, length EXPR  , length, _\|_LINE_\|_
+, link OLDFILE,NEWFILE , listen SOCKET,QUEUESIZE
+, local EXPR , localtime EXPR  ,
+localtime, lock THING , log EXPR    
+, log, lstat FILEHANDLE , lstat EXPR, lstat DIRHANDLE,
+lstat, m//, map BLOCK LIST , map EXPR,LIST, method NAME BLOCK
+, method NAME : ATTRS BLOCK, mkdir FILENAME,MODE  
+, mkdir FILENAME, mkdir, msgctl ID,CMD,ARG ,
+msgget KEY,FLAGS , msgrcv ID,VAR,SIZE,TYPE,FLAGS , msgsnd
+ID,MSG,FLAGS , my VARLIST , my TYPE VARLIST, my VARLIST :
+ATTRS, my TYPE VARLIST : ATTRS, next LABEL  , next EXPR,
+next, no MODULE VERSION LIST  , no MODULE
+VERSION, no MODULE LIST, no MODULE, no VERSION, oct EXPR  
+   , oct, open FILEHANDLE,MODE,EXPR
+   , open FILEHANDLE,MODE,EXPR,LIST,
+open FILEHANDLE,MODE,REFERENCE, open FILEHANDLE,EXPR, open FILEHANDLE,
+Working with files, Simple examples, About filehandles, About modes,
+Checking the return value, Specifying I/O layers in MODE, Using \f(CW\*(C`undef\*(C'\fR
+for temporary files, Opening a filehandle into an in-memory scalar, Opening
+a filehandle into a command, Duping filehandles, Legacy usage, Specifying
+mode and filename as a single argument, Calling \f(CW\*(C`open\*(C'\fR with one argument
+via global variables, Assigning a filehandle to a bareword, Other
+considerations, Automatic filehandle closure, Automatic pipe flushing,
+Direct versus by-reference assignment of filehandles, Whitespace and
+special characters in the filename argument, Invoking C\-style \f(CW\*(C`open\*(C'\fR,
+Portability issues, opendir DIRHANDLE,EXPR , ord EXPR 
+, ord, our VARLIST  , our TYPE VARLIST, our
+VARLIST : ATTRS, our TYPE VARLIST : ATTRS, pack TEMPLATE,LIST ,
+package NAMESPACE, package NAMESPACE VERSION  
+ , package NAMESPACE BLOCK, package NAMESPACE VERSION
+BLOCK    , _\|_PACKAGE_\|_
+, pipe READHANDLE,WRITEHANDLE , pop ARRAY 
+, pop, pos SCALAR  , pos, print FILEHANDLE
+LIST , print FILEHANDLE, print LIST, print, printf FILEHANDLE
+FORMAT, LIST , printf FILEHANDLE, printf FORMAT, LIST, printf,
+prototype FUNCTION , prototype, push ARRAY,LIST 
+, q/STRING/, qq/STRING/, qw/STRING/, qx/STRING/, qr/STRING/,
+quotemeta EXPR  , quotemeta, rand EXPR 
+, rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET  , read FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE ,
+readline EXPR, readline   , readlink EXPR
+, readlink, readpipe EXPR, readpipe , recv
+SOCKET,SCALAR,LENGTH,FLAGS , redo LABEL , redo EXPR, redo,
+ref EXPR  , ref, rename OLDNAME,NEWNAME  
+ , require VERSION , require EXPR, require, reset EXPR
+, reset, return EXPR , return, reverse LIST 
+ , rewinddir DIRHANDLE , rindex
+STR,SUBSTR,POSITION , rindex STR,SUBSTR, rmdir FILENAME 
+ , rmdir, s///, say FILEHANDLE LIST , say
+FILEHANDLE, say LIST, say, scalar EXPR  , seek
+FILEHANDLE,POSITION,WHENCE   ,
+seekdir DIRHANDLE,POS , select FILEHANDLE  , select, select RBITS,WBITS,EBITS,TIMEOUT , semctl
+ID,SEMNUM,CMD,ARG , semget KEY,NSEMS,FLAGS , semop
+KEY,OPSTRING , send SOCKET,MSG,FLAGS,TO , send
+SOCKET,MSG,FLAGS, setpgrp PID,PGRP  , setpriority
+WHICH,WHO,PRIORITY    , setsockopt
+SOCKET,LEVEL,OPTNAME,OPTVAL , shift ARRAY , shift,
+shmctl ID,CMD,ARG , shmget KEY,SIZE,FLAGS , shmread
+ID,VAR,POS,SIZE  , shmwrite ID,STRING,POS,SIZE,
+shutdown SOCKET,HOW , sin EXPR   
+, sin, sleep EXPR  , sleep, socket
+SOCKET,DOMAIN,TYPE,PROTOCOL , socketpair
+SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL , sort SUBNAME LIST
+, sort BLOCK LIST, sort LIST, splice ARRAY,OFFSET,LENGTH,LIST
+, splice ARRAY,OFFSET,LENGTH, splice ARRAY,OFFSET, splice ARRAY,
+split /PATTERN/,EXPR,LIMIT , split /PATTERN/,EXPR, split /PATTERN/,
+split, sprintf FORMAT, LIST , format parameter index, flags,
+vector flag, (minimum) width, precision, or maximum width ,
+size, order of arguments, sqrt EXPR   , sqrt,
+srand EXPR   , srand, stat FILEHANDLE 
+ , stat EXPR, stat DIRHANDLE, stat, state VARLIST
+, state TYPE VARLIST, state VARLIST : ATTRS, state TYPE VARLIST :
+ATTRS, study SCALAR , study, sub NAME BLOCK , sub NAME
+(PROTO) BLOCK, sub NAME : ATTRS BLOCK, sub NAME (PROTO) : ATTRS BLOCK,
+_\|_SUB_\|_ , substr EXPR,OFFSET,LENGTH,REPLACEMENT 
+   , substr EXPR,OFFSET,LENGTH, substr
+EXPR,OFFSET, symlink OLDFILE,NEWFILE   
+, syscall NUMBER, LIST  , sysopen
+FILEHANDLE,FILENAME,MODE , sysopen
+FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+, sysread FILEHANDLE,SCALAR,LENGTH, sysseek
+FILEHANDLE,POSITION,WHENCE  , system LIST 
+, system PROGRAM LIST, syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+, syswrite FILEHANDLE,SCALAR,LENGTH, syswrite FILEHANDLE,SCALAR,
+tell FILEHANDLE , tell, telldir DIRHANDLE , tie
+VARIABLE,CLASSNAME,LIST , tied VARIABLE , time 
+, times , tr///, truncate FILEHANDLE,LENGTH ,
+truncate EXPR,LENGTH, uc EXPR   , uc, ucfirst
+EXPR  , ucfirst, umask EXPR , umask, undef
+EXPR  , undef, unlink LIST   
+ , unlink, unpack TEMPLATE,EXPR , unpack TEMPLATE,
+unshift ARRAY,LIST , untie VARIABLE , use Module VERSION
+LIST   , use Module VERSION, use Module LIST, use
+Module, use VERSION, utime LIST , values HASH , values
+ARRAY, vec EXPR,OFFSET,BITS   , wait ,
+waitpid PID,FLAGS , wantarray  , warn LIST
+  , write FILEHANDLE , write EXPR, write,
+y///
+.IX Xref "-r -w -x -o -R -W -X -O -e -z -s -f -d -l -p -S -b -c -t -u -g -k -T -B -M -A -C abs absolute accept alarm SIGALRM timer atan2 arctangent tan tangent bind binmode binary text DOS Windows bless caller call stack stack stack trace chdir cd directory, change chmod permission mode chomp INPUT_RECORD_SEPARATOR $ newline eol chop chown owner user group chr character ASCII Unicode chroot root close closedir connect continue cos cosine acos arccosine crypt digest hash salt plaintext password decrypt cryptography passwd encrypt dbmclose dbmopen dbm ndbm sdbm gdbm defined undef undefined delete die throw exception raise $@ abort do block do dump core undump each hash, iterator array, iterator eof end of file end-of-file eval try catch evaluate parse execute error, handling exception, handling evalbytes exec execute exists autovivification exit terminate abort exp exponential antilog antilogarithm e fc foldcase casefold fold-case case-fold fcntl __FILE__ field fileno flock lock locking fork child parent format formline getc getchar character file, read getlogin login getpeername peer getpgrp group getppid parent pid getpriority priority nice getpwnam getgrnam gethostbyname getnetbyname getprotobyname getpwuid getgrgid getservbyname gethostbyaddr getnetbyaddr getprotobynumber getservbyport getpwent getgrent gethostent getnetent getprotoent getservent setpwent setgrent sethostent setnetent setprotoent setservent endpwent endgrent endhostent endnetent endprotoent endservent getsockname getsockopt glob wildcard filename, expansion expand gmtime UTC Greenwich goto jump jmp grep hex hexadecimal import index indexOf InStr int integer truncate trunc floor ioctl join keys key kill signal last break lc lowercase lcfirst lowercase length size __LINE__ link listen local localtime ctime lock log logarithm e ln base lstat map method mkdir md directory, create msgctl msgget msgrcv msgsnd my next continue no declarations unimporting oct octal hex hexadecimal binary bin open pipe file, open fopen opendir ord encoding our global pack package module namespace version package module namespace version __PACKAGE__ pipe pop stack pos match, position print printf prototype push stack quotemeta metacharacter rand random read file, read readdir readline gets fgets readlink readpipe recv redo ref reference rename move mv ren require reset return reverse rev invert rewinddir rindex rmdir rd directory, remove say scalar context seek fseek filehandle, position seekdir select filehandle, default select semctl semget semop send setpgrp group setpriority priority nice renice setsockopt shift shmctl shmget shmread shmwrite shutdown sin sine asin arcsine sleep pause socket socketpair sort splice split sprintf precision sqrt root square root srand seed randseed stat file, status ctime state study sub __SUB__ substr substring mid left right symlink link symbolic link link, symbolic syscall system call sysopen sysread sysseek lseek system shell syswrite tell telldir tie tied time epoch times truncate uc uppercase toupper ucfirst uppercase umask undef undefine unlink delete remove rm del unpack unshift untie use module import utime values vec bit bit vector wait waitpid wantarray context warn warning STDERR write"
+.IP "Non-function Keywords by Cross-reference" 4
+.IX Item "Non-function Keywords by Cross-reference"
+_\|_DATA_\|_, _\|_END_\|_, BEGIN, CHECK, END, INIT, UNITCHECK, DESTROY, and, cmp,
+eq, ge, gt, isa, le, lt, ne, not, or, x, xor, AUTOLOAD, else, elsif, for,
+foreach, if, unless, until, while, elseif, default, given, when, try,
+catch, finally, defer, ADJUST
+.RE
+.RS 4
+.RE
+.SS "perlopentut \- simple recipes for opening files and pipes in Perl"
+.IX Subsection "perlopentut - simple recipes for opening files and pipes in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+\&\fIOK\fR, \fIHANDLE\fR, \fIMODE\fR, \fIPATHNAME\fR
+.IP "Opening Text Files" 4
+.IX Item "Opening Text Files"
+.RS 4
+.PD 0
+.IP "Opening Text Files for Reading" 4
+.IX Item "Opening Text Files for Reading"
+.IP "Opening Text Files for Writing" 4
+.IX Item "Opening Text Files for Writing"
+.RE
+.RS 4
+.RE
+.IP "Opening Binary Files" 4
+.IX Item "Opening Binary Files"
+.IP "Opening Pipes" 4
+.IX Item "Opening Pipes"
+.RS 4
+.IP "Opening a pipe for reading" 4
+.IX Item "Opening a pipe for reading"
+.IP "Opening a pipe for writing" 4
+.IX Item "Opening a pipe for writing"
+.IP "Expressing the command as a list" 4
+.IX Item "Expressing the command as a list"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "AUTHOR and COPYRIGHT" 4
+.IX Item "AUTHOR and COPYRIGHT"
+.PD
+.ie n .SS "perlpacktut \- tutorial on ""pack"" and ""unpack"""
+.el .SS "perlpacktut \- tutorial on \f(CWpack\fP and \f(CWunpack\fP"
+.IX Subsection "perlpacktut - tutorial on pack and unpack"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "The Basic Principle" 4
+.IX Item "The Basic Principle"
+.IP "Packing Text" 4
+.IX Item "Packing Text"
+.IP "Packing Numbers" 4
+.IX Item "Packing Numbers"
+.RS 4
+.IP Integers 4
+.IX Item "Integers"
+.IP "Unpacking a Stack Frame" 4
+.IX Item "Unpacking a Stack Frame"
+.IP "How to Eat an Egg on a Net" 4
+.IX Item "How to Eat an Egg on a Net"
+.IP "Byte-order modifiers" 4
+.IX Item "Byte-order modifiers"
+.IP "Floating point Numbers" 4
+.IX Item "Floating point Numbers"
+.RE
+.RS 4
+.RE
+.IP "Exotic Templates" 4
+.IX Item "Exotic Templates"
+.RS 4
+.IP "Bit Strings" 4
+.IX Item "Bit Strings"
+.IP Uuencoding 4
+.IX Item "Uuencoding"
+.IP "Doing Sums" 4
+.IX Item "Doing Sums"
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "Another Portable Binary Encoding" 4
+.IX Item "Another Portable Binary Encoding"
+.RE
+.RS 4
+.RE
+.IP "Template Grouping" 4
+.IX Item "Template Grouping"
+.IP "Lengths and Widths" 4
+.IX Item "Lengths and Widths"
+.RS 4
+.IP "String Lengths" 4
+.IX Item "String Lengths"
+.IP "Dynamic Templates" 4
+.IX Item "Dynamic Templates"
+.IP "Counting Repetitions" 4
+.IX Item "Counting Repetitions"
+.IP "Intel HEX" 4
+.IX Item "Intel HEX"
+.RE
+.RS 4
+.RE
+.IP "Packing and Unpacking C Structures" 4
+.IX Item "Packing and Unpacking C Structures"
+.RS 4
+.IP "The Alignment Pit" 4
+.IX Item "The Alignment Pit"
+.IP "Dealing with Endian-ness" 4
+.IX Item "Dealing with Endian-ness"
+.IP "Alignment, Take 2" 4
+.IX Item "Alignment, Take 2"
+.IP "Alignment, Take 3" 4
+.IX Item "Alignment, Take 3"
+.IP "Pointers for How to Use Them" 4
+.IX Item "Pointers for How to Use Them"
+.RE
+.RS 4
+.RE
+.IP "Pack Recipes" 4
+.IX Item "Pack Recipes"
+.IP "Funnies Section" 4
+.IX Item "Funnies Section"
+.IP Authors 4
+.IX Item "Authors"
+.PD
+.SS "perlpod \- the Plain Old Documentation format"
+.IX Subsection "perlpod - the Plain Old Documentation format"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Ordinary Paragraph" 4
+.IX Xref "POD, ordinary paragraph"
+.IX Item "Ordinary Paragraph"
+.IP "Verbatim Paragraph" 4
+.IX Xref "POD, verbatim paragraph verbatim"
+.IX Item "Verbatim Paragraph"
+.IP "Command Paragraph" 4
+.IX Xref "POD, command"
+.IX Item "Command Paragraph"
+.PD
+\&\f(CW\*(C`=head1 \fR\f(CIHeading Text\fR\f(CW\*(C'\fR     
+      , \f(CW\*(C`=head2
+\&\fR\f(CIHeading Text\fR\f(CW\*(C'\fR, \f(CW\*(C`=head3 \fR\f(CIHeading Text\fR\f(CW\*(C'\fR, \f(CW\*(C`=head4 \fR\f(CIHeading Text\fR\f(CW\*(C'\fR,
+\&\f(CW\*(C`=head5 \fR\f(CIHeading Text\fR\f(CW\*(C'\fR, \f(CW\*(C`=head6 \fR\f(CIHeading Text\fR\f(CW\*(C'\fR, \f(CW\*(C`=over
+\&\fR\f(CIindentlevel\fR\f(CW\*(C'\fR      , \f(CW\*(C`=item
+\&\fR\f(CIstuff...\fR\f(CW\*(C'\fR, \f(CW\*(C`=back\*(C'\fR, \f(CW\*(C`=cut\*(C'\fR  , \f(CW\*(C`=pod\*(C'\fR  ,
+\&\f(CW\*(C`=begin \fR\f(CIformatname\fR\f(CW\*(C'\fR      ,
+\&\f(CW\*(C`=end \fR\f(CIformatname\fR\f(CW\*(C'\fR, \f(CW\*(C`=for \fR\f(CIformatname\fR\f(CW \fR\f(CItext...\fR\f(CW\*(C'\fR, \f(CW\*(C`=encoding
+\&\fR\f(CIencodingname\fR\f(CW\*(C'\fR
+.IX Xref "=head1 =head2 =head3 =head4 =head5 =head6 head1 head2 head3 head4 head5 head6 =over =item =back over item back =cut cut =pod pod =begin =end =for begin end for =encoding encoding"
+.IP "Formatting Codes" 4
+.IX Xref "POD, formatting code formatting code POD, interior sequence interior sequence"
+.IX Item "Formatting Codes"
+\&\f(CW\*(C`I<text>\*(C'\fR \-\- italic text    , \f(CW\*(C`B<text>\*(C'\fR \-\- bold text  
+ , \f(CW\*(C`C<code>\*(C'\fR \-\- code text 
+  , \f(CW\*(C`L<name>\*(C'\fR \-\-
+a hyperlink   
+, \f(CW\*(C`E<escape>\*(C'\fR \-\- a character escape  
+ , \f(CW\*(C`F<filename>\*(C'\fR \-\- used
+for filenames   
+, \f(CW\*(C`S<text>\*(C'\fR \-\- text contains non-breaking spaces 
+   , \f(CW\*(C`X<topic name>\*(C'\fR \-\- an index entry  
+ , \f(CW\*(C`Z<>\*(C'\fR \-\- a
+null (zero-effect) formatting code
+.IX Xref "I I<> POD, formatting code, italic italic B B<> POD, formatting code, bold bold C C<> POD, formatting code, code code L L<> POD, formatting code, hyperlink hyperlink E E<> POD, formatting code, escape escape F F<> POD, formatting code, filename filename S S<> POD, formatting code, non-breaking space non-breaking space X X<> POD, formatting code, index entry index entry Z Z<> POD, formatting code, null null"
+.IP "The Intent" 4
+.IX Xref "POD, intent of"
+.IX Item "The Intent"
+.PD 0
+.IP "Embedding Pods in Perl Modules" 4
+.IX Xref "POD, embedding"
+.IX Item "Embedding Pods in Perl Modules"
+.IP "Hints for Writing Pod" 4
+.IX Item "Hints for Writing Pod"
+.PD
+
+.IX Xref "podchecker POD, validating"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlpodspec \- Plain Old Documentation: format specification and notes"
+.IX Subsection "perlpodspec - Plain Old Documentation: format specification and notes"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Pod Definitions" 4
+.IX Item "Pod Definitions"
+.IP "Pod Commands" 4
+.IX Item "Pod Commands"
+.PD
+"=head1", "=head2", "=head3", "=head4", "=head5", "=head6", "=pod", "=cut",
+"=over", "=item", "=back", "=begin formatname", "=begin formatname
+parameter", "=end formatname", "=for formatname text...", "=encoding
+encodingname"
+.IP "Pod Formatting Codes" 4
+.IX Item "Pod Formatting Codes"
+\&\f(CW\*(C`I<text>\*(C'\fR \-\- italic text, \f(CW\*(C`B<text>\*(C'\fR \-\- bold text,
+\&\f(CW\*(C`C<code>\*(C'\fR \-\- code text, \f(CW\*(C`F<filename>\*(C'\fR \-\- style for
+filenames, \f(CW\*(C`X<topic name>\*(C'\fR \-\- an index entry, \f(CW\*(C`Z<>\*(C'\fR \-\- a
+null (zero-effect) formatting code, \f(CW\*(C`L<name>\*(C'\fR \-\- a hyperlink,
+\&\f(CW\*(C`E<escape>\*(C'\fR \-\- a character escape, \f(CW\*(C`S<text>\*(C'\fR \-\- text
+contains non-breaking spaces
+.IP "Notes on Implementing Pod Processors" 4
+.IX Item "Notes on Implementing Pod Processors"
+.PD 0
+.IP "About L<...> Codes" 4
+.IX Item "About L<...> Codes"
+.PD
+First:, Second:, Third:, Fourth:, Fifth:, Sixth:
+.IP "About =over...=back Regions" 4
+.IX Item "About =over...=back Regions"
+.PD 0
+.IP "About Data Paragraphs and ""=begin/=end"" Regions" 4
+.IX Item "About Data Paragraphs and ""=begin/=end"" Regions"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perldocstyle \- A style guide for writing Perl's documentation"
+.IX Subsection "perldocstyle - A style guide for writing Perl's documentation"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Purpose of this guide" 4
+.IX Item "Purpose of this guide"
+.IP "Intended audience" 4
+.IX Item "Intended audience"
+.IP "Status of this document" 4
+.IX Item "Status of this document"
+.RE
+.RS 4
+.RE
+.IP FUNDAMENTALS 4
+.IX Item "FUNDAMENTALS"
+.RS 4
+.IP "Choice of markup: Pod" 4
+.IX Item "Choice of markup: Pod"
+.IP "Choice of language: American English" 4
+.IX Item "Choice of language: American English"
+.IP "Choice of encoding: UTF\-8" 4
+.IX Item "Choice of encoding: UTF-8"
+.IP "Choice of underlying style guide: CMOS" 4
+.IX Item "Choice of underlying style guide: CMOS"
+.IP "Contributing to Perl's documentation" 4
+.IX Item "Contributing to Perl's documentation"
+.RE
+.RS 4
+.RE
+.IP "FORMATTING AND STRUCTURE" 4
+.IX Item "FORMATTING AND STRUCTURE"
+.RS 4
+.IP "Document structure" 4
+.IX Item "Document structure"
+.IP "Formatting rules" 4
+.IX Item "Formatting rules"
+.IP "Adding comments" 4
+.IX Item "Adding comments"
+.IP "Perlfunc has special rules" 4
+.IX Item "Perlfunc has special rules"
+.RE
+.RS 4
+.RE
+.IP "TONE AND STYLE" 4
+.IX Item "TONE AND STYLE"
+.RS 4
+.IP "Apply one of the four documentation modes" 4
+.IX Item "Apply one of the four documentation modes"
+.IP "Assume readers' intelligence, but not their knowledge" 4
+.IX Item "Assume readers' intelligence, but not their knowledge"
+.IP "Use meaningful variable and symbol names in examples" 4
+.IX Item "Use meaningful variable and symbol names in examples"
+.IP "Write in English, but not just for English-speakers" 4
+.IX Item "Write in English, but not just for English-speakers"
+.IP "Omit placeholder text or commentary" 4
+.IX Item "Omit placeholder text or commentary"
+.IP "Apply section-breaks and examples generously" 4
+.IX Item "Apply section-breaks and examples generously"
+.IP "Lead with common cases and best practices" 4
+.IX Item "Lead with common cases and best practices"
+.IP "Document Perl's present" 4
+.IX Item "Document Perl's present"
+.IP "The documentation speaks with one voice" 4
+.IX Item "The documentation speaks with one voice"
+.RE
+.RS 4
+.RE
+.IP "INDEX OF PREFERRED TERMS" 4
+.IX Item "INDEX OF PREFERRED TERMS"
+.PD
+built-in function, Darwin, macOS, man page, Perl; perl, Perl 5, Perl 6,
+Perl 5 Porters, the; porters, the; p5p, program, Raku, script, semicolon,
+Unix
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlpodstyle \- Perl POD style guide"
+.IX Subsection "perlpodstyle - Perl POD style guide"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS,
+EXAMPLES, ENVIRONMENT, FILES, CAVEATS, BUGS, RESTRICTIONS, NOTES, AUTHOR,
+HISTORY, COPYRIGHT AND LICENSE, SEE ALSO
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perldiag \- various Perl diagnostics"
+.IX Subsection "perldiag - various Perl diagnostics"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perldeprecation \- list Perl deprecations"
+.IX Subsection "perldeprecation - list Perl deprecations"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Unscheduled Deprecations" 4
+.IX Item "Unscheduled Deprecations"
+.IP "Perl 5.42" 4
+.IX Item "Perl 5.42"
+.IP "Perl 5.40" 4
+.IX Item "Perl 5.40"
+.IP "Perl 5.38" 4
+.IX Item "Perl 5.38"
+.IP "Perl 5.34" 4
+.IX Item "Perl 5.34"
+.IP "Perl 5.32" 4
+.IX Item "Perl 5.32"
+.IP "Perl 5.30" 4
+.IX Item "Perl 5.30"
+.IP "Perl 5.28" 4
+.IX Item "Perl 5.28"
+.IP "Perl 5.26" 4
+.IX Item "Perl 5.26"
+.IP "Perl 5.24" 4
+.IX Item "Perl 5.24"
+.IP "Perl 5.16" 4
+.IX Item "Perl 5.16"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perllexwarn \- Perl Lexical Warnings"
+.IX Subsection "perllexwarn - Perl Lexical Warnings"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "perldebug \- Perl debugging"
+.IX Subsection "perldebug - Perl debugging"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "The Perl Debugger" 4
+.IX Item "The Perl Debugger"
+.RS 4
+.IP "Calling the Debugger" 4
+.IX Item "Calling the Debugger"
+.PD
+perl \-d program_name, perl \-d \-e 0, perl \-d:ptkdb program_name, perl \-dt
+threaded_program_name
+.IP "Debugger Commands" 4
+.IX Item "Debugger Commands"
+h , h [command], h h, p expr ,
+x [maxdepth] expr , V [pkg [vars]] , X [vars] , y [level [vars]] , T   , s
+[expr]  , n [expr] , r
+, <CR>, c [line|sub] , l
+, l min+incr, l min-max, l line, l subname, \-
+, v [line] , . , f filename , /pattern/, ?pattern?, L
+[abw] , S [[!]regex] , t [n]
+, t [n] expr , b 
+, b [line] [condition]  , b [file]:[line] [condition]  , b subname [condition]  , b postpone
+subname [condition]  , b load filename
+ , b compile subname 
+, B line  , B *
+ , disable [file]:[line] 
+ , disable [line] 
+ , enable [file]:[line] 
+ , enable [line] 
+ , a [line] command , A line , A * , w
+expr , W expr , W * , o , o booloption ... , o anyoption? ... , o option=value ... , < ? , < [ command ] , < * , << command , > ? , > command , > * , >> command , { ? , { [ command ], { * , {{ command , ! number , ! \-number , ! pattern , !! cmd , source file , H \-number , q or ^D  , R , |dbcmd
+, ||dbcmd , command, m expr
+, M , man [manpage]
+.IX Xref "debugger command, h debugger command, p debugger command, x debugger command, V debugger command, X debugger command, y debugger command, T backtrace stack, backtrace debugger command, s step debugger command, n debugger command, r debugger command, c debugger command, l debugger command, - debugger command, v debugger command, . debugger command, f debugger command, L debugger command, S debugger command, t debugger command, t breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, b breakpoint debugger command, B breakpoint debugger command, B breakpoint debugger command, disable disable breakpoint debugger command, disable disable breakpoint debugger command, disable disable breakpoint debugger command, disable disable debugger command, a debugger command, A debugger command, A debugger command, w debugger command, W debugger command, W debugger command, o debugger command, o debugger command, o debugger command, o debugger command, < debugger command, < debugger command, < debugger command, << debugger command, > debugger command, > debugger command, > debugger command, >> debugger command, { debugger command, { debugger command, {{ debugger command, ! debugger command, ! debugger command, ! debugger command, !! debugger command, source debugger command, H debugger command, q debugger command, ^D debugger command, R debugger command, | debugger command, || debugger command, m debugger command, M debugger command, man"
+.IP "Configurable Options" 4
+.IX Item "Configurable Options"
+\&\f(CW\*(C`recallCommand\*(C'\fR, \f(CW\*(C`ShellBang\*(C'\fR  , \f(CW\*(C`pager\*(C'\fR , \f(CW\*(C`tkRunning\*(C'\fR
+, \f(CW\*(C`signalLevel\*(C'\fR, \f(CW\*(C`warnLevel\*(C'\fR, \f(CW\*(C`dieLevel\*(C'\fR
+  , \f(CW\*(C`AutoTrace\*(C'\fR , \f(CW\*(C`LineInfo\*(C'\fR
+, \f(CW\*(C`inhibit_exit\*(C'\fR , \f(CW\*(C`PrintRet\*(C'\fR , \f(CW\*(C`ornaments\*(C'\fR
+, \f(CW\*(C`frame\*(C'\fR ,
+\&\f(CW\*(C`maxTraceLen\*(C'\fR , \f(CW\*(C`windowSize\*(C'\fR , \f(CW\*(C`arrayDepth\*(C'\fR, \f(CW\*(C`hashDepth\*(C'\fR  , \f(CW\*(C`dumpDepth\*(C'\fR , \f(CW\*(C`compactDump\*(C'\fR, \f(CW\*(C`veryCompact\*(C'\fR 
+, \f(CW\*(C`globPrint\*(C'\fR , \f(CW\*(C`DumpDBFiles\*(C'\fR , \f(CW\*(C`DumpPackages\*(C'\fR
+, \f(CW\*(C`DumpReused\*(C'\fR , \f(CW\*(C`quote\*(C'\fR, \f(CW\*(C`HighBit\*(C'\fR, \f(CW\*(C`undefPrint\*(C'\fR 
+ , \f(CW\*(C`UsageOnly\*(C'\fR
+, \f(CW\*(C`HistFile\*(C'\fR , \f(CW\*(C`HistSize\*(C'\fR , \f(CW\*(C`TTY\*(C'\fR
+, \f(CW\*(C`noTTY\*(C'\fR , \f(CW\*(C`ReadLine\*(C'\fR
+, \f(CW\*(C`NonStop\*(C'\fR
+.IX Xref "debugger option, recallCommand debugger option, ShellBang debugger option, pager debugger option, tkRunning debugger option, signalLevel debugger option, warnLevel debugger option, dieLevel debugger option, AutoTrace debugger option, LineInfo debugger option, inhibit_exit debugger option, PrintRet debugger option, ornaments debugger option, frame debugger option, maxTraceLen debugger option, windowSize debugger option, arrayDepth debugger option, hashDepth debugger option, dumpDepth debugger option, compactDump debugger option, veryCompact debugger option, globPrint debugger option, DumpDBFiles debugger option, DumpPackages debugger option, DumpReused debugger option, quote debugger option, HighBit debugger option, undefPrint debugger option, UsageOnly debugger option, history, HistFile debugger option, history, HistSize debugger option, TTY debugger option, noTTY debugger option, ReadLine debugger option, NonStop"
+.IP "Debugger Input/Output" 4
+.IX Item "Debugger Input/Output"
+Prompt, Multiline commands, Stack backtrace  , Line Listing Format, Frame listing
+.IX Xref "backtrace stack, backtrace"
+.IP "Debugging Compile-Time Statements" 4
+.IX Item "Debugging Compile-Time Statements"
+.PD 0
+.IP "Debugger Customization" 4
+.IX Item "Debugger Customization"
+.IP "Readline Support / History in the Debugger" 4
+.IX Item "Readline Support / History in the Debugger"
+.IP "Editor Support for Debugging" 4
+.IX Item "Editor Support for Debugging"
+.IP "The Perl Profiler" 4
+.IX Xref "profile profiling profiler"
+.IX Item "The Perl Profiler"
+.RE
+.RS 4
+.RE
+.IP "Debugging Regular Expressions" 4
+.IX Xref "regular expression, debugging regex, debugging regexp, debugging"
+.IX Item "Debugging Regular Expressions"
+.IP "Debugging Memory Usage" 4
+.IX Xref "memory usage"
+.IX Item "Debugging Memory Usage"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+.SS "perlvar \- Perl predefined variables"
+.IX Subsection "perlvar - Perl predefined variables"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The Syntax of Variable Names" 4
+.IX Item "The Syntax of Variable Names"
+.RE
+.RS 4
+.RE
+.IP "SPECIAL VARIABLES" 4
+.IX Item "SPECIAL VARIABLES"
+.RS 4
+.IP "General Variables" 4
+.IX Item "General Variables"
+.PD
+\&\f(CW$ARG\fR, \f(CW$_\fR  , \f(CW@ARG\fR, \f(CW@_\fR  , \f(CW$LIST_SEPARATOR\fR, $" 
+, \f(CW$PROCESS_ID\fR, \f(CW$PID\fR, $$   ,
+\&\f(CW$PROGRAM_NAME\fR, \f(CW$0\fR  , \f(CW$REAL_GROUP_ID\fR, \f(CW$GID\fR, $( 
+ , \f(CW$EFFECTIVE_GROUP_ID\fR, \f(CW$EGID\fR, $)  
+, \f(CW$REAL_USER_ID\fR, \f(CW$UID\fR, $<  
+, \f(CW$EFFECTIVE_USER_ID\fR, \f(CW$EUID\fR, $>  
+, \f(CW$SUBSCRIPT_SEPARATOR\fR, \f(CW$SUBSEP\fR, $;  
+, \f(CW$a\fR, \f(CW$b\fR  , \f(CW%ENV\fR ,
+\&\f(CW$OLD_PERL_VERSION\fR, $]  , \f(CW$SYSTEM_FD_MAX\fR, $^F
+ , \f(CW@F\fR , \f(CW@INC\fR , \f(CW%INC\fR , \f(CW$INC\fR
+, \f(CW$INPLACE_EDIT\fR, $^I  , \f(CW@ISA\fR , $^M
+, ${^MAX_NESTED_EVAL_BEGIN_BLOCKS}, \f(CW$OSNAME\fR, $^O  ,
+\&\f(CW%SIG\fR , %{^HOOK} , require_\|_before, require_\|_after,
+\&\f(CW$BASETIME\fR, $^T  , \f(CW$PERL_VERSION\fR, $^V 
+, \f(CW$EXECUTABLE_NAME\fR, $^X
+.IX Xref "$_ $ARG @_ @ARG $"" $LIST_SEPARATOR $$ $PID $PROCESS_ID $0 $PROGRAM_NAME $( $GID $REAL_GROUP_ID $) $EGID $EFFECTIVE_GROUP_ID $< $UID $REAL_USER_ID $> $EUID $EFFECTIVE_USER_ID $; $SUBSEP SUBSCRIPT_SEPARATOR $a $b %ENV $] $OLD_PERL_VERSION $^F $SYSTEM_FD_MAX @F @INC %INC $INC $^I $INPLACE_EDIT @ISA $^M $^O $OSNAME %SIG %{^HOOK} $^T $BASETIME $^V $PERL_VERSION $^X $EXECUTABLE_NAME"
+.IP "Variables related to regular expressions" 4
+.IX Item "Variables related to regular expressions"
+$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)    , @{^CAPTURE}
+ , \f(CW$MATCH\fR, $&  , ${^MATCH}
+, \f(CW$PREMATCH\fR, $`  , ${^PREMATCH}
+, \f(CW$POSTMATCH\fR, $'   , ${^POSTMATCH}
+, \f(CW$LAST_PAREN_MATCH\fR, $+  ,
+\&\f(CW$LAST_SUBMATCH_RESULT\fR, $^N  ,
+\&\f(CW@LAST_MATCH_END\fR, @+  , %{^CAPTURE},
+\&\f(CW%LAST_PAREN_MATCH\fR, %+   ,
+\&\f(CW@LAST_MATCH_START\fR, @\-  , \f(CW\*(C`$\`\*(C'\fR is the same as
+\&\f(CW\*(C`substr($var, 0, $\-[0])\*(C'\fR, \f(CW$&\fR is the same as \f(CW\*(C`substr($var, $\-[0], $+[0]
+\&\- $\-[0])\*(C'\fR, \f(CW\*(C`$\*(Aq\*(C'\fR is the same as \f(CW\*(C`substr($var, $+[0])\*(C'\fR, \f(CW$1\fR is the same
+as \f(CW\*(C`substr($var, $\-[1], $+[1] \- $\-[1])\*(C'\fR, \f(CW$2\fR is the same as
+\&\f(CW\*(C`substr($var, $\-[2], $+[2] \- $\-[2])\*(C'\fR, \f(CW$3\fR is the same as \f(CW\*(C`substr($var,
+$\-[3], $+[3] \- $\-[3])\*(C'\fR, %{^CAPTURE_ALL} , %\- ,
+${^LAST_SUCCESSFUL_PATTERN}, \f(CW$LAST_REGEXP_CODE_RESULT\fR, $^R 
+, ${^RE_COMPILE_RECURSION_LIMIT}
+, ${^RE_DEBUG_FLAGS}
+, ${^RE_TRIE_MAXBUF}
+.IX Xref "$1 $2 $3 $\\f(ISdigits\\f(IE @{^CAPTURE} @^CAPTURE $& $MATCH ${^MATCH} $` $PREMATCH ${^PREMATCH} $' $POSTMATCH @- ${^POSTMATCH} $+ $LAST_PAREN_MATCH $^N $LAST_SUBMATCH_RESULT @+ @LAST_MATCH_END %+ %LAST_PAREN_MATCH %{^CAPTURE} @- @LAST_MATCH_START %{^CAPTURE_ALL} %- $^R $LAST_REGEXP_CODE_RESULT ${^RE_COMPILE_RECURSION_LIMIT} ${^RE_DEBUG_FLAGS} ${^RE_TRIE_MAXBUF}"
+.IP "Variables related to filehandles" 4
+.IX Item "Variables related to filehandles"
+\&\f(CW$ARGV\fR , \f(CW@ARGV\fR , ARGV , ARGVOUT ,
+IO::Handle\->output_field_separator( EXPR ), \f(CW$OUTPUT_FIELD_SEPARATOR\fR, \f(CW$OFS\fR,
+$,   , HANDLE\->input_line_number(
+EXPR ), \f(CW$INPUT_LINE_NUMBER\fR, \f(CW$NR\fR, $.   
+, IO::Handle\->input_record_separator( EXPR ),
+\&\f(CW$INPUT_RECORD_SEPARATOR\fR, \f(CW$RS\fR, $/   ,
+IO::Handle\->output_record_separator( EXPR ), \f(CW$OUTPUT_RECORD_SEPARATOR\fR,
+\&\f(CW$ORS\fR, $\e   , HANDLE\->autoflush( EXPR
+), \f(CW$OUTPUT_AUTOFLUSH\fR, $|    ,
+${^LAST_FH} , \f(CW$ACCUMULATOR\fR, $^A  ,
+IO::Handle\->format_formfeed(EXPR), \f(CW$FORMAT_FORMFEED\fR, $^L 
+, HANDLE\->format_page_number(EXPR), \f(CW$FORMAT_PAGE_NUMBER\fR,
+$%  , HANDLE\->format_lines_left(EXPR),
+\&\f(CW$FORMAT_LINES_LEFT\fR, $\-  ,
+IO::Handle\->format_line_break_characters EXPR,
+\&\f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR, \f(CW$:\fR  ,
+HANDLE\->format_lines_per_page(EXPR), \f(CW$FORMAT_LINES_PER_PAGE\fR, $= 
+, HANDLE\->format_top_name(EXPR), \f(CW$FORMAT_TOP_NAME\fR,
+$^  , HANDLE\->format_name(EXPR), \f(CW$FORMAT_NAME\fR, $~
+.IX Xref "$ARGV @ARGV ARGV ARGVOUT $, $OFS $OUTPUT_FIELD_SEPARATOR $. $NR $INPUT_LINE_NUMBER line number $ $RS $INPUT_RECORD_SEPARATOR $\\ $ORS $OUTPUT_RECORD_SEPARATOR $| autoflush flush $OUTPUT_AUTOFLUSH ${^LAST_FH} $^A $ACCUMULATOR $^L $FORMAT_FORMFEED $% $FORMAT_PAGE_NUMBER $- $FORMAT_LINES_LEFT $: FORMAT_LINE_BREAK_CHARACTERS $= $FORMAT_LINES_PER_PAGE $^ $FORMAT_TOP_NAME $~ $FORMAT_NAME"
+.IP "Error Variables" 4
+.IX Xref "error exception"
+.IX Item "Error Variables"
+${^CHILD_ERROR_NATIVE} , \f(CW$EXTENDED_OS_ERROR\fR, $^E
+ , \f(CW$EXCEPTIONS_BEING_CAUGHT\fR, $^S 
+, \f(CW$WARNING\fR, $^W  ,
+${^WARNING_BITS} , \f(CW$OS_ERROR\fR, \f(CW$ERRNO\fR, $!  
+, \f(CW%OS_ERROR\fR, \f(CW%ERRNO\fR, %!   ,
+\&\f(CW$CHILD_ERROR\fR, $?  , \f(CW$EVAL_ERROR\fR, $@
+.IX Xref "$^CHILD_ERROR_NATIVE $^E $EXTENDED_OS_ERROR $^S $EXCEPTIONS_BEING_CAUGHT $^W $WARNING ${^WARNING_BITS} $! $ERRNO $OS_ERROR %! %OS_ERROR %ERRNO $? $CHILD_ERROR $@ $EVAL_ERROR"
+.IP "Variables related to the interpreter state" 4
+.IX Item "Variables related to the interpreter state"
+\&\f(CW$COMPILING\fR, $^C  , \f(CW$DEBUGGING\fR, $^D  ,
+${^GLOBAL_PHASE} , CONSTRUCT, START, CHECK, INIT, RUN,
+END, DESTRUCT, $^H , %^H , ${^OPEN} , \f(CW$PERLDB\fR, $^P
+ , 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x100,
+0x200, 0x400, 0x800, 0x1000, ${^TAINT} , ${^SAFE_LOCALES}
+, ${^UNICODE} , ${^UTF8CACHE}
+, ${^UTF8LOCALE}
+.IX Xref "$^C $COMPILING $^D $DEBUGGING ${^GLOBAL_PHASE} $^H %^H ${^OPEN} $^P $PERLDB ${^TAINT} ${^SAFE_LOCALES} ${^UNICODE} ${^UTF8CACHE} ${^UTF8LOCALE}"
+.IP "Deprecated and removed variables" 4
+.IX Item "Deprecated and removed variables"
+$# , $* , $[ , ${^ENCODING} ,
+${^WIN32_SLOPPY_STAT}
+.IX Xref "$# $* $[ ${^ENCODING} ${^WIN32_SLOPPY_STAT} sitecustomize sitecustomize.pl"
+.RE
+.RS 4
+.RE
+.SS "perlre \- Perl regular expressions"
+.IX Subsection "perlre - Perl regular expressions"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The Basics" 4
+.IX Xref "regular expression, version 8 regex, version 8 regexp, version 8"
+.IX Item "The Basics"
+.IP Modifiers 4
+.IX Item "Modifiers"
+.PD
+\&\fR\f(CB\*(C`m\*(C'\fR\fB\fR    , \fB\fR\f(CB\*(C`s\*(C'\fR\fB\fR    , \fB\fR\f(CB\*(C`i\*(C'\fR\fB\fR    , \fB\fR\f(CB\*(C`x\*(C'\fR\fB\fR and \fB\fR\f(CB\*(C`xx\*(C'\fR\fB\fR , \fB\fR\f(CB\*(C`p\*(C'\fR\fB\fR   , \fB\fR\f(CB\*(C`a\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`d\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`l\*(C'\fR\fB\fR, and \fB\fR\f(CB\*(C`u\*(C'\fR\fB\fR 
+  , \fB\fR\f(CB\*(C`n\*(C'\fR\fB\fR    , Other Modifiers
+.IX Xref " m regex, multiline regexp, multiline regular expression, multiline s regex, single-line regexp, single-line regular expression, single-line i regex, case-insensitive regexp, case-insensitive regular expression, case-insensitive x p regex, preserve regexp, preserve a d l u n regex, non-capture regexp, non-capture regular expression, non-capture"
+.IP "Regular Expressions" 4
+.IX Item "Regular Expressions"
+[1], [2], [3], [4], [5], [6], [7], [8]
+.IP "Quoting metacharacters" 4
+.IX Item "Quoting metacharacters"
+.PD 0
+.IP "Extended Patterns" 4
+.IX Item "Extended Patterns"
+.PD
+\&\f(CW\*(C`(?#\fR\f(CItext\fR\f(CW)\*(C'\fR , \f(CW\*(C`(?adlupimnsx\-imnsx)\*(C'\fR, \f(CW\*(C`(?^alupimnsx)\*(C'\fR 
+, \f(CW\*(C`(?:\fR\f(CIpattern\fR\f(CW)\*(C'\fR , \f(CW\*(C`(?adluimnsx\-imnsx:\fR\f(CIpattern\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(?^aluimnsx:\fR\f(CIpattern\fR\f(CW)\*(C'\fR , \f(CW\*(C`(?|\fR\f(CIpattern\fR\f(CW)\*(C'\fR  , Lookaround Assertions    , \f(CW\*(C`(?=\fR\f(CIpattern\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(*pla:\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(*positive_lookahead:\fR\f(CIpattern\fR\f(CW)\*(C'\fR  
+  ,
+\&\f(CW\*(C`(?!\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(*nla:\fR\f(CIpattern\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(*negative_lookahead:\fR\f(CIpattern\fR\f(CW)\*(C'\fR  
+  ,
+\&\f(CW\*(C`(?<=\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`\eK\*(C'\fR, \f(CW\*(C`(*plb:\fR\f(CIpattern\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(*positive_lookbehind:\fR\f(CIpattern\fR\f(CW)\*(C'\fR  
+  
+, \f(CW\*(C`(?<!\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(*nlb:\fR\f(CIpattern\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(*negative_lookbehind:\fR\f(CIpattern\fR\f(CW)\*(C'\fR  
+  ,
+\&\f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(?\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR\f(CIpattern\fR\f(CW)\*(C'\fR 
+  , \f(CW\*(C`\ek<\fR\f(CINAME\fR\f(CW>\*(C'\fR, \f(CW\*(C`\ek\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\*(C'\fR, \f(CW\*(C`\ek{\fR\f(CINAME\fR\f(CW}\*(C'\fR, \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR    , \f(CW\*(C`(*{ \fR\f(CIcode\fR\f(CW
+})\*(C'\fR  , \f(CW\*(C`(??{ \fR\f(CIcode\fR\f(CW })\*(C'\fR 
+  ,
+\&\f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR \f(CW\*(C`(?\-\fR\f(CIPARNO\fR\f(CW)\*(C'\fR \f(CW\*(C`(?+\fR\f(CIPARNO\fR\f(CW)\*(C'\fR \f(CW\*(C`(?R)\*(C'\fR \f(CW\*(C`(?0)\*(C'\fR 
+      
+  
+  , \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR
+, \f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\*(C'\fR ,
+\&\f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW)\*(C'\fR, an integer in parentheses, a
+lookahead/lookbehind/evaluate zero-width assertion;, a name in angle
+brackets or single quotes, the special symbol \f(CW\*(C`(R)\*(C'\fR, \f(CW\*(C`(1)\*(C'\fR \f(CW\*(C`(2)\*(C'\fR ..,
+\&\f(CW\*(C`(<\fR\f(CINAME\fR\f(CW>)\*(C'\fR \f(CW\*(C`(\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq)\*(C'\fR, \f(CW\*(C`(?=...)\*(C'\fR \f(CW\*(C`(?!...)\*(C'\fR \f(CW\*(C`(?<=...)\*(C'\fR
+\&\f(CW\*(C`(?<!...)\*(C'\fR, \f(CW\*(C`(?{ \fR\f(CICODE\fR\f(CW })\*(C'\fR, \f(CW\*(C`(*{ \fR\f(CICODE\fR\f(CW })\*(C'\fR, \f(CW\*(C`(R)\*(C'\fR, \f(CW\*(C`(R1)\*(C'\fR \f(CW\*(C`(R2)\*(C'\fR
+\&.., \f(CW\*(C`(R&\fR\f(CINAME\fR\f(CW)\*(C'\fR, \f(CW\*(C`(DEFINE)\*(C'\fR, \f(CW\*(C`(?>\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(*atomic:\fR\f(CIpattern\fR\f(CW)\*(C'\fR   
+  , \f(CW\*(C`(?[ ])\*(C'\fR
+.IX Xref "(?#) (?) (?^) (?:) (?^:) (?|) Branch reset look-around assertion lookaround assertion look-around lookaround (?=) (*pla (*positive_lookahead look-ahead, positive lookahead, positive (?!) (*nla (*negative_lookahead look-ahead, negative lookahead, negative (?<=) (*plb (*positive_lookbehind look-behind, positive lookbehind, positive \\K (?<!) (*nlb (*negative_lookbehind look-behind, negative lookbehind, negative (?<NAME>) (?'NAME') named capture capture (?{}) regex, code in regexp, code in regular expression, code in (*{}) regex, optimistic code (??{}) regex, postponed regexp, postponed regular expression, postponed (?PARNO) (?1) (?R) (?0) (?-1) (?+1) (?-PARNO) (?+PARNO) regex, recursive regexp, recursive regular expression, recursive regex, relative recursion GOSUB GOSTART (?&NAME) (?() (?>pattern) (*atomic backtrack backtracking atomic possessive"
+.IP Backtracking 4
+.IX Xref "backtrack backtracking"
+.IX Item "Backtracking"
+.PD 0
+.IP "Script Runs" 4
+.IX Xref "(*script_run:...) (sr:...) (*atomic_script_run:...) (asr:...)"
+.IX Item "Script Runs"
+.IP "Special Backtracking Control Verbs" 4
+.IX Item "Special Backtracking Control Verbs"
+.PD
+Verbs, \f(CW\*(C`(*PRUNE)\*(C'\fR \f(CW\*(C`(*PRUNE:\fR\f(CINAME\fR\f(CW)\*(C'\fR  ,
+\&\f(CW\*(C`(*SKIP)\*(C'\fR \f(CW\*(C`(*SKIP:\fR\f(CINAME\fR\f(CW)\*(C'\fR , \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR \f(CW\*(C`(*:\fR\f(CINAME\fR\f(CW)\*(C'\fR
+  , \f(CW\*(C`(*THEN)\*(C'\fR \f(CW\*(C`(*THEN:\fR\f(CINAME\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(*COMMIT)\*(C'\fR \f(CW\*(C`(*COMMIT:\fR\f(CIarg\fR\f(CW)\*(C'\fR , \f(CW\*(C`(*FAIL)\*(C'\fR \f(CW\*(C`(*F)\*(C'\fR
+\&\f(CW\*(C`(*FAIL:\fR\f(CIarg\fR\f(CW)\*(C'\fR  , \f(CW\*(C`(*ACCEPT)\*(C'\fR \f(CW\*(C`(*ACCEPT:\fR\f(CIarg\fR\f(CW)\*(C'\fR
+.IX Xref "(*PRUNE) (*PRUNE:NAME) (*SKIP) (*MARK) (*MARK:NAME) (*:NAME) (*COMMIT) (*FAIL) (*F) (*ACCEPT)"
+.ie n .IP "Warning on ""\e1"" Instead of $1" 4
+.el .IP "Warning on \f(CW\e1\fR Instead of \f(CW$1\fR" 4
+.IX Item "Warning on 1 Instead of $1"
+.PD 0
+.IP "Repeated Patterns Matching a Zero-length Substring" 4
+.IX Item "Repeated Patterns Matching a Zero-length Substring"
+.IP "Combining RE Pieces" 4
+.IX Item "Combining RE Pieces"
+.PD
+\&\f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`S|T\*(C'\fR, \f(CW\*(C`S{REPEAT_COUNT}\*(C'\fR, \f(CW\*(C`S{min,max}\*(C'\fR, \f(CW\*(C`S{min,max}?\*(C'\fR, \f(CW\*(C`S?\*(C'\fR,
+\&\f(CW\*(C`S*\*(C'\fR, \f(CW\*(C`S+\*(C'\fR, \f(CW\*(C`S??\*(C'\fR, \f(CW\*(C`S*?\*(C'\fR, \f(CW\*(C`S+?\*(C'\fR, \f(CW\*(C`(?>S)\*(C'\fR, \f(CW\*(C`(?=S)\*(C'\fR, \f(CW\*(C`(?<=S)\*(C'\fR,
+\&\f(CW\*(C`(?!S)\*(C'\fR, \f(CW\*(C`(?<!S)\*(C'\fR, \f(CW\*(C`(??{ \fR\f(CIEXPR\fR\f(CW })\*(C'\fR, \f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR,
+\&\f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\*(C'\fR
+.IP "Creating Custom RE Engines" 4
+.IX Item "Creating Custom RE Engines"
+.PD 0
+.IP "Embedded Code Execution Frequency" 4
+.IX Item "Embedded Code Execution Frequency"
+.IP "PCRE/Python Support" 4
+.IX Item "PCRE/Python Support"
+.PD
+\&\f(CW\*(C`(?P<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR, \f(CW\*(C`(?P=\fR\f(CINAME\fR\f(CW)\*(C'\fR, \f(CW\*(C`(?P>\fR\f(CINAME\fR\f(CW)\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlrebackslash \- Perl Regular Expression Backslash Sequences and Escapes"
+.IX Subsection "perlrebackslash - Perl Regular Expression Backslash Sequences and Escapes"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The backslash" 4
+.IX Item "The backslash"
+.PD
+[1]
+.IP "All the sequences and escapes" 4
+.IX Item "All the sequences and escapes"
+.PD 0
+.IP "Character Escapes" 4
+.IX Item "Character Escapes"
+.PD
+[1], [2]
+.IP Modifiers 4
+.IX Item "Modifiers"
+.PD 0
+.IP "Character classes" 4
+.IX Item "Character classes"
+.IP Referencing 4
+.IX Item "Referencing"
+.IP Assertions 4
+.IX Item "Assertions"
+.PD
+\&\eA, \ez, \eZ, \eG, \eb{}, \eb, \eB{}, \eB, \f(CW\*(C`\eb{gcb}\*(C'\fR or \f(CW\*(C`\eb{g}\*(C'\fR, \f(CW\*(C`\eb{lb}\*(C'\fR,
+\&\f(CW\*(C`\eb{sb}\*(C'\fR, \f(CW\*(C`\eb{wb}\*(C'\fR
+.IP Misc 4
+.IX Item "Misc"
+\&\eK, \eN, \eR , \eX
+.IX Xref "\\R \\X"
+.RE
+.RS 4
+.RE
+.SS "perlrecharclass \- Perl Regular Expression Character Classes"
+.IX Subsection "perlrecharclass - Perl Regular Expression Character Classes"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The dot" 4
+.IX Item "The dot"
+.IP "Backslash sequences" 4
+.IX Xref "\\w \\W \\s \\S \\d \\D \\p \\P \\N \\v \\V \\h \\H word whitespace"
+.IX Item "Backslash sequences"
+.PD
+If the \f(CW\*(C`/a\*(C'\fR modifier is in effect .., otherwise .., For code points above
+255 .., For code points below 256 .., if locale rules are in effect .., if,
+instead, Unicode rules are in effect .., otherwise .., If the \f(CW\*(C`/a\*(C'\fR
+modifier is in effect .., otherwise .., For code points above 255 .., For
+code points below 256 .., if locale rules are in effect .., if, instead,
+Unicode rules are in effect .., otherwise .., [1], [2]
+.IP "Bracketed Character Classes" 4
+.IX Item "Bracketed Character Classes"
+[1], [2], [3], [4], [5], [6], [7], If the \f(CW\*(C`/a\*(C'\fR modifier, is in effect ..,
+otherwise .., For code points above 255 .., For code points below 256 ..,
+if locale rules are in effect .., \f(CW\*(C`word\*(C'\fR, \f(CW\*(C`ascii\*(C'\fR, \f(CW\*(C`blank\*(C'\fR, if, instead,
+Unicode rules are in effect .., otherwise ..
+.RE
+.RS 4
+.RE
+.SS "perlreref \- Perl Regular Expressions Reference"
+.IX Subsection "perlreref - Perl Regular Expressions Reference"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP OPERATORS 4
+.IX Item "OPERATORS"
+.IP SYNTAX 4
+.IX Item "SYNTAX"
+.IP "ESCAPE SEQUENCES" 4
+.IX Item "ESCAPE SEQUENCES"
+.IP "CHARACTER CLASSES" 4
+.IX Item "CHARACTER CLASSES"
+.IP ANCHORS 4
+.IX Item "ANCHORS"
+.IP QUANTIFIERS 4
+.IX Item "QUANTIFIERS"
+.IP "EXTENDED CONSTRUCTS" 4
+.IX Item "EXTENDED CONSTRUCTS"
+.IP VARIABLES 4
+.IX Item "VARIABLES"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP THANKS 4
+.IX Item "THANKS"
+.PD
+.SS "perlref \- Perl references and nested data structures"
+.IX Subsection "perlref - Perl references and nested data structures"
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Making References" 4
+.IX Xref "reference, creation referencing"
+.IX Item "Making References"
+.IP "Using References" 4
+.IX Xref "reference, use dereferencing dereference"
+.IX Item "Using References"
+.IP "Circular References" 4
+.IX Xref "circular reference reference, circular"
+.IX Item "Circular References"
+.IP "Symbolic references" 4
+.IX Xref "reference, symbolic reference, soft symbolic reference soft reference"
+.IX Item "Symbolic references"
+.IP "Not-so-symbolic references" 4
+.IX Item "Not-so-symbolic references"
+.IP "Pseudo-hashes: Using an array as a hash" 4
+.IX Xref "pseudo-hash pseudo hash pseudohash"
+.IX Item "Pseudo-hashes: Using an array as a hash"
+.IP "Function Templates" 4
+.IX Xref "scope, lexical closure lexical lexical scope subroutine, nested sub, nested subroutine, local sub, local"
+.IX Item "Function Templates"
+.IP "Postfix Dereference Syntax" 4
+.IX Item "Postfix Dereference Syntax"
+.IP "Postfix Reference Slicing" 4
+.IX Item "Postfix Reference Slicing"
+.IP "Assigning to References" 4
+.IX Item "Assigning to References"
+.IP "Declaring a Reference to a Variable" 4
+.IX Item "Declaring a Reference to a Variable"
+.RE
+.RS 4
+.RE
+.IP "WARNING: Don't use references as hash keys" 4
+.IX Xref "reference, string context reference, use as hash key"
+.IX Item "WARNING: Don't use references as hash keys"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlform \- Perl formats"
+.IX Subsection "perlform - Perl formats"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Text Fields" 4
+.IX Xref "format, text field"
+.IX Item "Text Fields"
+.IP "Numeric Fields" 4
+.IX Xref "# format, numeric field"
+.IX Item "Numeric Fields"
+.IP "The Field @* for Variable-Width Multi-Line Text" 4
+.IX Xref "@*"
+.IX Item "The Field @* for Variable-Width Multi-Line Text"
+.IP "The Field ^* for Variable-Width One-line-at-a-time Text" 4
+.IX Xref "^*"
+.IX Item "The Field ^* for Variable-Width One-line-at-a-time Text"
+.IP "Specifying Values" 4
+.IX Xref "format, specifying values"
+.IX Item "Specifying Values"
+.IP "Using Fill Mode" 4
+.IX Xref "format, fill mode"
+.IX Item "Using Fill Mode"
+.IP "Suppressing Lines Where All Fields Are Void" 4
+.IX Xref "format, suppressing lines"
+.IX Item "Suppressing Lines Where All Fields Are Void"
+.IP "Repeating Format Lines" 4
+.IX Xref "format, repeating lines"
+.IX Item "Repeating Format Lines"
+.IP "Top of Form Processing" 4
+.IX Xref "format, top of form top header"
+.IX Item "Top of Form Processing"
+.IP "Format Variables" 4
+.IX Xref "format variables format, variables"
+.IX Item "Format Variables"
+.RE
+.RS 4
+.RE
+.IP NOTES 4
+.IX Item "NOTES"
+.RS 4
+.IP Footers 4
+.IX Xref "format, footer footer"
+.IX Item "Footers"
+.IP "Accessing Formatting Internals" 4
+.IX Xref "format, internals"
+.IX Item "Accessing Formatting Internals"
+.RE
+.RS 4
+.RE
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+.PD
+.SS "perlobj \- Perl object reference"
+.IX Subsection "perlobj - Perl object reference"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "An Object is Simply a Data Structure" 4
+.IX Xref "object bless constructor new"
+.IX Item "An Object is Simply a Data Structure"
+.IP "A Class is Simply a Package" 4
+.IX Xref "class package @ISA inheritance"
+.IX Item "A Class is Simply a Package"
+.IP "A Method is Simply a Subroutine" 4
+.IX Xref "method"
+.IX Item "A Method is Simply a Subroutine"
+.IP "Method Invocation" 4
+.IX Xref "invocation method arrow ->"
+.IX Item "Method Invocation"
+.IP Inheritance 4
+.IX Xref "inheritance"
+.IX Item "Inheritance"
+.IP "Writing Constructors" 4
+.IX Xref "constructor"
+.IX Item "Writing Constructors"
+.IP Attributes 4
+.IX Xref "attribute"
+.IX Item "Attributes"
+.IP "An Aside About Smarter and Safer Code" 4
+.IX Item "An Aside About Smarter and Safer Code"
+.IP "Method Call Variations" 4
+.IX Xref "method"
+.IX Item "Method Call Variations"
+.IP "Invoking Class Methods" 4
+.IX Xref "invocation"
+.IX Item "Invoking Class Methods"
+.ie n .IP """bless"", ""blessed"", and ""ref""" 4
+.el .IP "\f(CWbless\fR, \f(CWblessed\fR, and \f(CWref\fR" 4
+.IX Item "bless, blessed, and ref"
+.IP "The UNIVERSAL Class" 4
+.IX Xref "UNIVERSAL"
+.IX Item "The UNIVERSAL Class"
+.PD
+isa($class) , DOES($role) , can($method) ,
+VERSION($need)
+.IX Xref "isa DOES can VERSION"
+.IP AUTOLOAD 4
+.IX Xref "AUTOLOAD"
+.IX Item "AUTOLOAD"
+.PD 0
+.IP Destructors 4
+.IX Xref "destructor DESTROY"
+.IX Item "Destructors"
+.IP "Non-Hash Objects" 4
+.IX Item "Non-Hash Objects"
+.IP "Inside-Out objects" 4
+.IX Item "Inside-Out objects"
+.IP Pseudo-hashes 4
+.IX Item "Pseudo-hashes"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perltie \- how to hide an object class in a simple variable"
+.IX Subsection "perltie - how to hide an object class in a simple variable"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Tying Scalars" 4
+.IX Xref "scalar, tying"
+.IX Item "Tying Scalars"
+.PD
+TIESCALAR classname, LIST , FETCH this , STORE this,
+value , UNTIE this , DESTROY this
+.IX Xref "TIESCALAR FETCH STORE UNTIE DESTROY"
+.IP "Tying Arrays" 4
+.IX Xref "array, tying"
+.IX Item "Tying Arrays"
+TIEARRAY classname, LIST , FETCH this, index , STORE
+this, index, value , FETCHSIZE this , STORESIZE this,
+count , EXTEND this, count , EXISTS this, key
+, DELETE this, key , CLEAR this , PUSH this, LIST
+ , POP this , SHIFT this , UNSHIFT this, LIST 
+, SPLICE this, offset, length, LIST , UNTIE this
+, DESTROY this
+.IX Xref "TIEARRAY FETCH STORE FETCHSIZE STORESIZE EXTEND EXISTS DELETE CLEAR PUSH POP SHIFT UNSHIFT SPLICE UNTIE DESTROY"
+.IP "Tying Hashes" 4
+.IX Xref "hash, tying"
+.IX Item "Tying Hashes"
+USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST , FETCH this,
+key , STORE this, key, value , DELETE this, key ,
+CLEAR this , EXISTS this, key , FIRSTKEY this ,
+NEXTKEY this, lastkey , SCALAR this , UNTIE this
+, DESTROY this
+.IX Xref "TIEHASH FETCH STORE DELETE CLEAR EXISTS FIRSTKEY NEXTKEY SCALAR UNTIE DESTROY"
+.IP "Tying FileHandles" 4
+.IX Xref "filehandle, tying"
+.IX Item "Tying FileHandles"
+TIEHANDLE classname, LIST , WRITE this, LIST , PRINT
+this, LIST , PRINTF this, LIST , READ this, LIST ,
+READLINE this , GETC this , EOF this , CLOSE this
+, UNTIE this , DESTROY this
+.IX Xref "TIEHANDLE WRITE PRINT PRINTF READ READLINE GETC EOF CLOSE UNTIE DESTROY"
+.IP "UNTIE this" 4
+.IX Xref "UNTIE"
+.IX Item "UNTIE this"
+.PD 0
+.ie n .IP "The ""untie"" Gotcha" 4
+.el .IP "The \f(CWuntie\fR Gotcha" 4
+.IX Xref "untie"
+.IX Item "The untie Gotcha"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlclass \- Perl class syntax reference"
+.IX Subsection "perlclass - Perl class syntax reference"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP History 4
+.IX Item "History"
+.RE
+.RS 4
+.RE
+.IP KEYWORDS 4
+.IX Item "KEYWORDS"
+.RS 4
+.IP class 4
+.IX Item "class"
+.IP field 4
+.IX Item "field"
+.IP method 4
+.IX Item "method"
+.RE
+.RS 4
+.RE
+.IP ATTRIBUTES 4
+.IX Item "ATTRIBUTES"
+.RS 4
+.IP "Class attributes" 4
+.IX Item "Class attributes"
+.IP "Field attributes" 4
+.IX Item "Field attributes"
+.IP "Method attributes" 4
+.IX Item "Method attributes"
+.RE
+.RS 4
+.RE
+.IP "OBJECT LIFECYCLE" 4
+.IX Item "OBJECT LIFECYCLE"
+.RS 4
+.IP Construction 4
+.IX Item "Construction"
+.IP Adjustment 4
+.IX Item "Adjustment"
+.IP Lifetime 4
+.IX Item "Lifetime"
+.IP Destruction 4
+.IX Item "Destruction"
+.RE
+.RS 4
+.RE
+.IP TODO 4
+.IX Item "TODO"
+.PD
+Roles, Parameters to ADJUST blocks, ADJUST blocks as true blocks, Accessor
+generator attributes, Metaprogramming, Extension Customisation
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.SS "perldbmfilter \- Perl DBM Filters"
+.IX Subsection "perldbmfilter - Perl DBM Filters"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBfilter_store_key\fR, \fBfilter_store_value\fR, \fBfilter_fetch_key\fR,
+\&\fBfilter_fetch_value\fR
+.RS 4
+.IP "The Filter" 4
+.IX Item "The Filter"
+.PD 0
+.IP "An Example: the NULL termination problem." 4
+.IX Item "An Example: the NULL termination problem."
+.IP "Another Example: Key is a C int." 4
+.IX Item "Another Example: Key is a C int."
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlipc \- Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)"
+.IX Subsection "perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Signals 4
+.IX Item "Signals"
+.RS 4
+.IP "Handling the SIGHUP Signal in Daemons" 4
+.IX Item "Handling the SIGHUP Signal in Daemons"
+.IP "Deferred Signals (Safe Signals)" 4
+.IX Item "Deferred Signals (Safe Signals)"
+.PD
+Long-running opcodes, Interrupting IO, Restartable system calls, Signals as
+"faults", Signals triggered by operating system state
+.RE
+.RS 4
+.RE
+.IP "Named Pipes" 4
+.IX Item "Named Pipes"
+.PD 0
+.IP "Using \fBopen()\fR for IPC" 4
+.IX Item "Using open() for IPC"
+.RS 4
+.IP Filehandles 4
+.IX Item "Filehandles"
+.IP "Background Processes" 4
+.IX Item "Background Processes"
+.IP "Complete Dissociation of Child from Parent" 4
+.IX Item "Complete Dissociation of Child from Parent"
+.IP "Safe Pipe Opens" 4
+.IX Item "Safe Pipe Opens"
+.IP "Avoiding Pipe Deadlocks" 4
+.IX Item "Avoiding Pipe Deadlocks"
+.IP "Bidirectional Communication with Another Process" 4
+.IX Item "Bidirectional Communication with Another Process"
+.IP "Bidirectional Communication with Yourself" 4
+.IX Item "Bidirectional Communication with Yourself"
+.RE
+.RS 4
+.RE
+.IP "Sockets: Client/Server Communication" 4
+.IX Item "Sockets: Client/Server Communication"
+.RS 4
+.IP "Internet Line Terminators" 4
+.IX Item "Internet Line Terminators"
+.IP "Internet TCP Clients and Servers" 4
+.IX Item "Internet TCP Clients and Servers"
+.IP "Unix-Domain TCP Clients and Servers" 4
+.IX Item "Unix-Domain TCP Clients and Servers"
+.RE
+.RS 4
+.RE
+.IP "TCP Clients with IO::Socket" 4
+.IX Item "TCP Clients with IO::Socket"
+.RS 4
+.IP "A Simple Client" 4
+.IX Item "A Simple Client"
+.PD
+\&\f(CW\*(C`Proto\*(C'\fR, \f(CW\*(C`PeerAddr\*(C'\fR, \f(CW\*(C`PeerPort\*(C'\fR
+.IP "A Webget Client" 4
+.IX Item "A Webget Client"
+.PD 0
+.IP "Interactive Client with IO::Socket" 4
+.IX Item "Interactive Client with IO::Socket"
+.RE
+.RS 4
+.RE
+.IP "TCP Servers with IO::Socket" 4
+.IX Item "TCP Servers with IO::Socket"
+.PD
+Proto, LocalPort, Listen, Reuse
+.IP "UDP: Message Passing" 4
+.IX Item "UDP: Message Passing"
+.PD 0
+.IP "SysV IPC" 4
+.IX Item "SysV IPC"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlfork \- Perl's \fBfork()\fP emulation"
+.IX Subsection "perlfork - Perl's fork() emulation"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Behavior of other Perl features in forked pseudo-processes" 4
+.IX Item "Behavior of other Perl features in forked pseudo-processes"
+.PD
+$$ or \f(CW$PROCESS_ID\fR, \f(CW%ENV\fR, \fBchdir()\fR and all other builtins that accept
+filenames, \fBwait()\fR and \fBwaitpid()\fR, \fBkill()\fR, \fBexec()\fR, \fBexit()\fR, Open handles to
+files, directories and network sockets
+.IP "Resource limits" 4
+.IX Item "Resource limits"
+.PD 0
+.IP "Killing the parent process" 4
+.IX Item "Killing the parent process"
+.IP "Lifetime of the parent process and pseudo-processes" 4
+.IX Item "Lifetime of the parent process and pseudo-processes"
+.RE
+.RS 4
+.RE
+.IP "CAVEATS AND LIMITATIONS" 4
+.IX Item "CAVEATS AND LIMITATIONS"
+.PD
+BEGIN blocks, Open filehandles, Open directory handles, Forking pipe \fBopen()\fR
+not yet implemented, Global state maintained by XSUBs, Interpreter embedded
+in larger application, Thread-safety of extensions
+.IP "PORTABILITY CAVEATS" 4
+.IX Item "PORTABILITY CAVEATS"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlnumber \- semantics of numbers and numeric operations in Perl"
+.IX Subsection "perlnumber - semantics of numbers and numeric operations in Perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Storing numbers" 4
+.IX Item "Storing numbers"
+.IP "Numeric operators and numeric conversions" 4
+.IX Item "Numeric operators and numeric conversions"
+.IP "Flavors of Perl numeric operations" 4
+.IX Item "Flavors of Perl numeric operations"
+.PD
+Arithmetic operators, ++, Arithmetic operators during \f(CW\*(C`use integer\*(C'\fR, Other
+mathematical operators, Bitwise operators, Bitwise operators during \f(CW\*(C`use
+integer\*(C'\fR, Operators which expect an integer, Operators which expect a
+string
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlthrtut \- Tutorial on threads in Perl"
+.IX Subsection "perlthrtut - Tutorial on threads in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "What Is A Thread Anyway?" 4
+.IX Item "What Is A Thread Anyway?"
+.IP "Threaded Program Models" 4
+.IX Item "Threaded Program Models"
+.RS 4
+.IP Boss/Worker 4
+.IX Item "Boss/Worker"
+.IP "Work Crew" 4
+.IX Item "Work Crew"
+.IP Pipeline 4
+.IX Item "Pipeline"
+.RE
+.RS 4
+.RE
+.IP "What kind of threads are Perl threads?" 4
+.IX Item "What kind of threads are Perl threads?"
+.IP "Thread-Safe Modules" 4
+.IX Item "Thread-Safe Modules"
+.IP "Thread Basics" 4
+.IX Item "Thread Basics"
+.RS 4
+.IP "Basic Thread Support" 4
+.IX Item "Basic Thread Support"
+.IP "A Note about the Examples" 4
+.IX Item "A Note about the Examples"
+.IP "Creating Threads" 4
+.IX Item "Creating Threads"
+.IP "Waiting For A Thread To Exit" 4
+.IX Item "Waiting For A Thread To Exit"
+.IP "Ignoring A Thread" 4
+.IX Item "Ignoring A Thread"
+.IP "Process and Thread Termination" 4
+.IX Item "Process and Thread Termination"
+.RE
+.RS 4
+.RE
+.IP "Threads And Data" 4
+.IX Item "Threads And Data"
+.RS 4
+.IP "Shared And Unshared Data" 4
+.IX Item "Shared And Unshared Data"
+.IP "Thread Pitfalls: Races" 4
+.IX Item "Thread Pitfalls: Races"
+.RE
+.RS 4
+.RE
+.IP "Synchronization and control" 4
+.IX Item "Synchronization and control"
+.RS 4
+.IP "Controlling access: \fBlock()\fR" 4
+.IX Item "Controlling access: lock()"
+.IP "A Thread Pitfall: Deadlocks" 4
+.IX Item "A Thread Pitfall: Deadlocks"
+.IP "Queues: Passing Data Around" 4
+.IX Item "Queues: Passing Data Around"
+.IP "Semaphores: Synchronizing Data Access" 4
+.IX Item "Semaphores: Synchronizing Data Access"
+.IP "Basic semaphores" 4
+.IX Item "Basic semaphores"
+.IP "Advanced Semaphores" 4
+.IX Item "Advanced Semaphores"
+.IP "Waiting for a Condition" 4
+.IX Item "Waiting for a Condition"
+.IP "Giving up control" 4
+.IX Item "Giving up control"
+.RE
+.RS 4
+.RE
+.IP "General Thread Utility Routines" 4
+.IX Item "General Thread Utility Routines"
+.RS 4
+.IP "What Thread Am I In?" 4
+.IX Item "What Thread Am I In?"
+.IP "Thread IDs" 4
+.IX Item "Thread IDs"
+.IP "Are These Threads The Same?" 4
+.IX Item "Are These Threads The Same?"
+.IP "What Threads Are Running?" 4
+.IX Item "What Threads Are Running?"
+.RE
+.RS 4
+.RE
+.IP "A Complete Example" 4
+.IX Item "A Complete Example"
+.IP "Different implementations of threads" 4
+.IX Item "Different implementations of threads"
+.IP "Performance considerations" 4
+.IX Item "Performance considerations"
+.IP "Process-scope Changes" 4
+.IX Item "Process-scope Changes"
+.IP "Thread-Safety of System Libraries" 4
+.IX Item "Thread-Safety of System Libraries"
+.IP Conclusion 4
+.IX Item "Conclusion"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP Bibliography 4
+.IX Item "Bibliography"
+.RS 4
+.IP "Introductory Texts" 4
+.IX Item "Introductory Texts"
+.IP "OS-Related References" 4
+.IX Item "OS-Related References"
+.IP "Other References" 4
+.IX Item "Other References"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP Copyrights 4
+.IX Item "Copyrights"
+.PD
+.SS "perlport \- Writing portable Perl"
+.IX Subsection "perlport - Writing portable Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+Not all Perl programs have to be portable, Nearly all of Perl already \fIis\fR
+portable
+.IP ISSUES 4
+.IX Item "ISSUES"
+.RS 4
+.PD 0
+.IP Newlines 4
+.IX Item "Newlines"
+.IP "Numbers endianness and Width" 4
+.IX Item "Numbers endianness and Width"
+.IP "Files and Filesystems" 4
+.IX Item "Files and Filesystems"
+.IP "System Interaction" 4
+.IX Item "System Interaction"
+.IP "Command names versus file pathnames" 4
+.IX Item "Command names versus file pathnames"
+.IP Networking 4
+.IX Item "Networking"
+.IP "Interprocess Communication (IPC)" 4
+.IX Item "Interprocess Communication (IPC)"
+.IP "External Subroutines (XS)" 4
+.IX Item "External Subroutines (XS)"
+.IP "Standard Modules" 4
+.IX Item "Standard Modules"
+.IP "Time and Date" 4
+.IX Item "Time and Date"
+.IP "Character sets and character encoding" 4
+.IX Item "Character sets and character encoding"
+.IP Internationalisation 4
+.IX Item "Internationalisation"
+.IP "System Resources" 4
+.IX Item "System Resources"
+.IP Security 4
+.IX Item "Security"
+.IP Style 4
+.IX Item "Style"
+.RE
+.RS 4
+.RE
+.IP "CPAN Testers" 4
+.IX Item "CPAN Testers"
+.IP PLATFORMS 4
+.IX Item "PLATFORMS"
+.RS 4
+.IP Unix 4
+.IX Item "Unix"
+.IP "DOS and Derivatives" 4
+.IX Item "DOS and Derivatives"
+.IP VMS 4
+.IX Item "VMS"
+.IP VOS 4
+.IX Item "VOS"
+.IP "EBCDIC Platforms" 4
+.IX Item "EBCDIC Platforms"
+.IP "Acorn RISC OS" 4
+.IX Item "Acorn RISC OS"
+.IP "Other perls" 4
+.IX Item "Other perls"
+.RE
+.RS 4
+.RE
+.IP "FUNCTION IMPLEMENTATIONS" 4
+.IX Item "FUNCTION IMPLEMENTATIONS"
+.RS 4
+.IP "Alphabetical Listing of Perl Functions" 4
+.IX Item "Alphabetical Listing of Perl Functions"
+.PD
+\&\-\fIX\fR, alarm, atan2, binmode, chdir, chmod, chown, chroot, crypt, dbmclose,
+dbmopen, dump, exec, exit, fcntl, flock, fork, getlogin, getpgrp, getppid,
+getpriority, getpwnam, getgrnam, getnetbyname, getpwuid, getgrgid,
+getnetbyaddr, getprotobynumber, getpwent, getgrent, gethostbyname,
+gethostent, getnetent, getprotoent, getservent, seekdir, sethostent,
+setnetent, setprotoent, setservent, endpwent, endgrent, endhostent,
+endnetent, endprotoent, endservent, getsockopt, glob, gmtime, ioctl, kill,
+link, localtime, lstat, msgctl, msgget, msgsnd, msgrcv, open, readlink,
+rename, rewinddir, select, semctl, semget, semop, setgrent, setpgrp,
+setpriority, setpwent, setsockopt, shmctl, shmget, shmread, shmwrite,
+sleep, socketpair, stat, symlink, syscall, sysopen, system, telldir, times,
+truncate, umask, utime, wait, waitpid
+.RE
+.RS 4
+.RE
+.IP "Supported Platforms" 4
+.IX Item "Supported Platforms"
+Linux (x86, ARM, IA64), HP-UX, AIX, Win32, Windows 2000, Windows XP,
+Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, Cygwin,
+Solaris (x86, SPARC), OpenVMS, Alpha (7.2 and later), I64 (8.2 and later),
+NetBSD, FreeBSD, Debian GNU/kFreeBSD, Haiku, Irix (6.5. What else?),
+OpenBSD, Dragonfly BSD, Midnight BSD, QNX Neutrino RTOS (6.5.0), MirOS BSD,
+Stratus OpenVOS (17.0 or later), time_t issues that may or may not be
+fixed, Stratus VOS / OpenVOS, AIX, Android, FreeMINT
+.IP "EOL Platforms" 4
+.IX Item "EOL Platforms"
+.RS 4
+.PD 0
+.IP "(Perl 5.37.1)" 4
+.IX Item "(Perl 5.37.1)"
+.PD
+Ultrix
+.IP "(Perl 5.36)" 4
+.IX Item "(Perl 5.36)"
+NetWare, DOS/DJGPP, AT&T UWIN
+.IP "(Perl 5.20)" 4
+.IX Item "(Perl 5.20)"
+AT&T 3b1
+.IP "(Perl 5.14)" 4
+.IX Item "(Perl 5.14)"
+Windows 95, Windows 98, Windows ME, Windows NT4
+.IP "(Perl 5.12)" 4
+.IX Item "(Perl 5.12)"
+Atari MiNT, Apollo Domain/OS, Apple Mac OS 8/9, Tenon Machten
+.RE
+.RS 4
+.RE
+.IP "Supported Platforms (Perl 5.8)" 4
+.IX Item "Supported Platforms (Perl 5.8)"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "AUTHORS / CONTRIBUTORS" 4
+.IX Item "AUTHORS / CONTRIBUTORS"
+.PD
+.SS "perllocale \- Perl locale handling (internationalization and localization)"
+.IX Subsection "perllocale - Perl locale handling (internationalization and localization)"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "WHAT IS A LOCALE" 4
+.IX Item "WHAT IS A LOCALE"
+.PD
+Category \f(CW\*(C`LC_NUMERIC\*(C'\fR: Numeric formatting, Category \f(CW\*(C`LC_MONETARY\*(C'\fR:
+Formatting of monetary amounts, Category \f(CW\*(C`LC_TIME\*(C'\fR: Date/Time formatting,
+Category \f(CW\*(C`LC_MESSAGES\*(C'\fR: Error and other messages, Category \f(CW\*(C`LC_COLLATE\*(C'\fR:
+Collation, Category \f(CW\*(C`LC_CTYPE\*(C'\fR: Character Types, Other categories
+.IP "PREPARING TO USE LOCALES" 4
+.IX Item "PREPARING TO USE LOCALES"
+.PD 0
+.IP "USING LOCALES" 4
+.IX Item "USING LOCALES"
+.RS 4
+.ie n .IP "The ""use locale"" pragma" 4
+.el .IP "The \f(CW""use locale""\fR pragma" 4
+.IX Item "The ""use locale"" pragma"
+.PD
+\&\fBNot within the scope of \fR\f(CB"use locale"\fR, \fBLingering effects of \fR\f(CB\*(C`use\ locale\*(C'\fR\fB\fR, \fBUnder \fR\f(CB\*(C`"use locale";\*(C'\fR\fB\fR
+.IP "The setlocale function" 4
+.IX Item "The setlocale function"
+.PD 0
+.IP "Multi-threaded operation" 4
+.IX Item "Multi-threaded operation"
+.IP "Finding locales" 4
+.IX Item "Finding locales"
+.IP "LOCALE PROBLEMS" 4
+.IX Item "LOCALE PROBLEMS"
+.IP "Testing for broken locales" 4
+.IX Item "Testing for broken locales"
+.IP "Temporarily fixing locale problems" 4
+.IX Item "Temporarily fixing locale problems"
+.IP "Permanently fixing locale problems" 4
+.IX Item "Permanently fixing locale problems"
+.IP "Permanently fixing your system's locale configuration" 4
+.IX Item "Permanently fixing your system's locale configuration"
+.IP "Fixing system locale configuration" 4
+.IX Item "Fixing system locale configuration"
+.IP "The localeconv function" 4
+.IX Item "The localeconv function"
+.IP I18N::Langinfo 4
+.IX Item "I18N::Langinfo"
+.RE
+.RS 4
+.RE
+.IP "LOCALE CATEGORIES" 4
+.IX Item "LOCALE CATEGORIES"
+.RS 4
+.ie n .IP "Category ""LC_COLLATE"": Collation: Text Comparisons and Sorting" 4
+.el .IP "Category \f(CWLC_COLLATE\fR: Collation: Text Comparisons and Sorting" 4
+.IX Item "Category LC_COLLATE: Collation: Text Comparisons and Sorting"
+.ie n .IP "Category ""LC_CTYPE"": Character Types" 4
+.el .IP "Category \f(CWLC_CTYPE\fR: Character Types" 4
+.IX Item "Category LC_CTYPE: Character Types"
+.ie n .IP "Category ""LC_NUMERIC"": Numeric Formatting" 4
+.el .IP "Category \f(CWLC_NUMERIC\fR: Numeric Formatting" 4
+.IX Item "Category LC_NUMERIC: Numeric Formatting"
+.ie n .IP "Category ""LC_MONETARY"": Formatting of monetary amounts" 4
+.el .IP "Category \f(CWLC_MONETARY\fR: Formatting of monetary amounts" 4
+.IX Item "Category LC_MONETARY: Formatting of monetary amounts"
+.ie n .IP "Category ""LC_TIME"": Respresentation of time" 4
+.el .IP "Category \f(CWLC_TIME\fR: Respresentation of time" 4
+.IX Item "Category LC_TIME: Respresentation of time"
+.IP "Other categories" 4
+.IX Item "Other categories"
+.RE
+.RS 4
+.RE
+.IP SECURITY 4
+.IX Item "SECURITY"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.PD
+PERL_SKIP_LOCALE_INIT, PERL_BADLANG, \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LANGUAGE\*(C'\fR, \f(CW\*(C`LC_CTYPE\*(C'\fR,
+\&\f(CW\*(C`LC_COLLATE\*(C'\fR, \f(CW\*(C`LC_MONETARY\*(C'\fR, \f(CW\*(C`LC_NUMERIC\*(C'\fR, \f(CW\*(C`LC_TIME\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR
+.RS 4
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP NOTES 4
+.IX Item "NOTES"
+.RS 4
+.ie n .IP "String ""eval"" and ""LC_NUMERIC""" 4
+.el .IP "String \f(CWeval\fR and \f(CWLC_NUMERIC\fR" 4
+.IX Item "String eval and LC_NUMERIC"
+.IP "Backward compatibility" 4
+.IX Item "Backward compatibility"
+.IP "I18N:Collate obsolete" 4
+.IX Item "I18N:Collate obsolete"
+.IP "Sort speed and memory use impacts" 4
+.IX Item "Sort speed and memory use impacts"
+.IP "Freely available locale definitions" 4
+.IX Item "Freely available locale definitions"
+.IP "I18n and l10n" 4
+.IX Item "I18n and l10n"
+.IP "An imperfect standard" 4
+.IX Item "An imperfect standard"
+.RE
+.RS 4
+.RE
+.IP "Unicode and UTF\-8" 4
+.IX Item "Unicode and UTF-8"
+.IP BUGS 4
+.IX Item "BUGS"
+.RS 4
+.ie n .IP "Collation of strings containing embedded ""NUL"" characters" 4
+.el .IP "Collation of strings containing embedded \f(CWNUL\fR characters" 4
+.IX Item "Collation of strings containing embedded NUL characters"
+.IP Multi-threaded 4
+.IX Item "Multi-threaded"
+.IP "Broken systems" 4
+.IX Item "Broken systems"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perluniintro \- Perl Unicode introduction"
+.IX Subsection "perluniintro - Perl Unicode introduction"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "Perl's Unicode Support" 4
+.IX Item "Perl's Unicode Support"
+.IP "Perl's Unicode Model" 4
+.IX Item "Perl's Unicode Model"
+.IP "Unicode and EBCDIC" 4
+.IX Item "Unicode and EBCDIC"
+.IP "Creating Unicode" 4
+.IX Item "Creating Unicode"
+.IP "Handling Unicode" 4
+.IX Item "Handling Unicode"
+.IP "Legacy Encodings" 4
+.IX Item "Legacy Encodings"
+.IP "Unicode I/O" 4
+.IX Item "Unicode I/O"
+.IP "Displaying Unicode As Text" 4
+.IX Item "Displaying Unicode As Text"
+.IP "Special Cases" 4
+.IX Item "Special Cases"
+.IP "Advanced Topics" 4
+.IX Item "Advanced Topics"
+.IP Miscellaneous 4
+.IX Item "Miscellaneous"
+.IP "Questions With Answers" 4
+.IX Item "Questions With Answers"
+.IP "Hexadecimal Notation" 4
+.IX Item "Hexadecimal Notation"
+.IP "Further Resources" 4
+.IX Item "Further Resources"
+.RE
+.RS 4
+.RE
+.IP "UNICODE IN OLDER PERLS" 4
+.IX Item "UNICODE IN OLDER PERLS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP ACKNOWLEDGMENTS 4
+.IX Item "ACKNOWLEDGMENTS"
+.IP "AUTHOR, COPYRIGHT, AND LICENSE" 4
+.IX Item "AUTHOR, COPYRIGHT, AND LICENSE"
+.PD
+.SS "perlunicode \- Unicode support in Perl"
+.IX Subsection "perlunicode - Unicode support in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Important Caveats" 4
+.IX Item "Important Caveats"
+.PD
+Safest if you \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR, Input and Output Layers,
+You must convert your non-ASCII, non\-UTF\-8 Perl scripts to be UTF\-8, \f(CW\*(C`use
+utf8\*(C'\fR still needed to enable UTF\-8 in
+scripts, UTF\-16 scripts autodetected
+.IP "Byte and Character Semantics" 4
+.IX Item "Byte and Character Semantics"
+.PD 0
+.IP "ASCII Rules versus Unicode Rules" 4
+.IX Item "ASCII Rules versus Unicode Rules"
+.PD
+When the string has been upgraded to UTF\-8, There are additional methods
+for regular expression patterns
+.IP "Extended Grapheme Clusters (Logical characters)" 4
+.IX Item "Extended Grapheme Clusters (Logical characters)"
+.PD 0
+.IP "Unicode Character Properties" 4
+.IX Item "Unicode Character Properties"
+.PD
+\&\fR\f(CB\*(C`\ep{All}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Alnum}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Any}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{ASCII}\*(C'\fR\fB\fR,
+\&\fB\fR\f(CB\*(C`\ep{Assigned}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Blank}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Decomposition_Type:
+Non_Canonical}\*(C'\fR\fB\fR    (Short: \f(CW\*(C`\ep{Dt=NonCanon}\*(C'\fR), \fB\fR\f(CB\*(C`\ep{Graph}\*(C'\fR\fB\fR,
+\&\fB\fR\f(CB\*(C`\ep{HorizSpace}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{In=*}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{PerlSpace}\*(C'\fR\fB\fR,
+\&\fB\fR\f(CB\*(C`\ep{PerlWord}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Posix...}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Present_In: *}\*(C'\fR\fB\fR    (Short:
+\&\f(CW\*(C`\ep{In=*}\*(C'\fR), \fB\fR\f(CB\*(C`\ep{Print}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{SpacePerl}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Title}\*(C'\fR\fB\fR and 
+\&\fB\fR\f(CB\*(C`\ep{Titlecase}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{Unicode}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{VertSpace}\*(C'\fR\fB\fR,
+\&\fB\fR\f(CB\*(C`\ep{Word}\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`\ep{XPosix...}\*(C'\fR\fB\fR
+.ie n .IP "Comparison of ""\eN{...}"" and ""\ep{name=...}""" 4
+.el .IP "Comparison of \f(CW\eN{...}\fR and \f(CW\ep{name=...}\fR" 4
+.IX Item "Comparison of N{...} and p{name=...}"
+[1], [2], [3], [4], [5]
+.IP "Wildcards in Property Values" 4
+.IX Item "Wildcards in Property Values"
+.PD 0
+.IP "User-Defined Character Properties" 4
+.IX Item "User-Defined Character Properties"
+.IP "User-Defined Case Mappings (for serious hackers only)" 4
+.IX Item "User-Defined Case Mappings (for serious hackers only)"
+.IP "Character Encodings for Input and Output" 4
+.IX Item "Character Encodings for Input and Output"
+.IP "Unicode Regular Expression Support Level" 4
+.IX Item "Unicode Regular Expression Support Level"
+.PD
+[1] \f(CW\*(C`\eN{U+...}\*(C'\fR and \f(CW\*(C`\ex{...}\*(C'\fR, [2] \f(CW\*(C`\ep{...}\*(C'\fR \f(CW\*(C`\eP{...}\*(C'\fR.  This
+requirement is for a minimal list of properties.  Perl supports these.	See
+R2.7 for other properties, [3], [4], [5] \f(CW\*(C`\eb\*(C'\fR \f(CW\*(C`\eB\*(C'\fR meet most, but not
+all, the details of this requirement, but \f(CW\*(C`\eb{wb}\*(C'\fR and \f(CW\*(C`\eB{wb}\*(C'\fR do, as
+well as the stricter R2.3, [6], [7], [8] UTF\-8/UTF\-EBDDIC used in Perl
+allows not only \f(CW\*(C`U+10000\*(C'\fR to \f(CW\*(C`U+10FFFF\*(C'\fR but also beyond \f(CW\*(C`U+10FFFF\*(C'\fR, [9]
+Unicode has rewritten this portion of UTS#18 to say that getting canonical
+equivalence (see UAX#15 "Unicode Normalization
+Forms" <https://www.unicode.org/reports/tr15>) is basically to be done at
+the programmer level.  Use NFD to write both your regular expressions and
+text to match them against (you can use Unicode::Normalize), [10] Perl
+has \f(CW\*(C`\eX\*(C'\fR and \f(CW\*(C`\eb{gcb}\*(C'\fR.  Unicode has retracted their "Grapheme Cluster
+Mode", and recently added string properties, which Perl does not yet
+support, [11] see UAX#29 "Unicode Text
+Segmentation" <https://www.unicode.org/reports/tr29>,, [12] see
+"Wildcards in Property Values" in perlunicode above, [13] Perl supports all
+the properties in the Unicode Character Database (UCD).  It does not yet
+support the listed properties that come from other Unicode sources, [14]
+The only optional property that Perl supports is Named Sequence.  None of
+these properties are in the UCD
+.IP "Unicode Encodings" 4
+.IX Item "Unicode Encodings"
+.PD 0
+.IP "Noncharacter code points" 4
+.IX Item "Noncharacter code points"
+.IP "Beyond Unicode code points" 4
+.IX Item "Beyond Unicode code points"
+.IP "Security Implications of Unicode" 4
+.IX Item "Security Implications of Unicode"
+.IP "Unicode in Perl on EBCDIC" 4
+.IX Item "Unicode in Perl on EBCDIC"
+.IP Locales 4
+.IX Item "Locales"
+.IP "When Unicode Does Not Happen" 4
+.IX Item "When Unicode Does Not Happen"
+.IP "The ""Unicode Bug""" 4
+.IX Item "The ""Unicode Bug"""
+.IP "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)" 4
+.IX Item "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)"
+.IP "Using Unicode in XS" 4
+.IX Item "Using Unicode in XS"
+.IP "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)" 4
+.IX Item "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)"
+.IP "Porting code from perl\-5.6.X" 4
+.IX Item "Porting code from perl-5.6.X"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.RS 4
+.IP "Interaction with Extensions" 4
+.IX Item "Interaction with Extensions"
+.IP Speed 4
+.IX Item "Speed"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlunicook \- cookbookish examples of handling Unicode in Perl"
+.IX Subsection "perlunicook - cookbookish examples of handling Unicode in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "â„ž 0: Standard preamble" 4
+.IX Item "â„ž 0: Standard preamble"
+.IP "â„ž 1: Generic Unicode-savvy filter" 4
+.IX Item "â„ž 1: Generic Unicode-savvy filter"
+.IP "â„ž 2: Fine-tuning Unicode warnings" 4
+.IX Item "â„ž 2: Fine-tuning Unicode warnings"
+.IP "â„ž 3: Declare source in utf8 for identifiers and literals" 4
+.IX Item "â„ž 3: Declare source in utf8 for identifiers and literals"
+.IP "â„ž 4: Characters and their numbers" 4
+.IX Item "â„ž 4: Characters and their numbers"
+.IP "â„ž 5: Unicode literals by character number" 4
+.IX Item "â„ž 5: Unicode literals by character number"
+.IP "â„ž 6: Get character name by number" 4
+.IX Item "â„ž 6: Get character name by number"
+.IP "â„ž 7: Get character number by name" 4
+.IX Item "â„ž 7: Get character number by name"
+.IP "â„ž 8: Unicode named characters" 4
+.IX Item "â„ž 8: Unicode named characters"
+.IP "â„ž 9: Unicode named sequences" 4
+.IX Item "â„ž 9: Unicode named sequences"
+.IP "â„ž 10: Custom named characters" 4
+.IX Item "â„ž 10: Custom named characters"
+.IP "â„ž 11: Names of CJK codepoints" 4
+.IX Item "â„ž 11: Names of CJK codepoints"
+.IP "â„ž 12: Explicit encode/decode" 4
+.IX Item "â„ž 12: Explicit encode/decode"
+.IP "â„ž 13: Decode program arguments as utf8" 4
+.IX Item "â„ž 13: Decode program arguments as utf8"
+.IP "â„ž 14: Decode program arguments as locale encoding" 4
+.IX Item "â„ž 14: Decode program arguments as locale encoding"
+.IP "â„ž 15: Declare STD{IN,OUT,ERR} to be utf8" 4
+.IX Item "â„ž 15: Declare STD{IN,OUT,ERR} to be utf8"
+.IP "â„ž 16: Declare STD{IN,OUT,ERR} to be in locale encoding" 4
+.IX Item "â„ž 16: Declare STD{IN,OUT,ERR} to be in locale encoding"
+.IP "â„ž 17: Make file I/O default to utf8" 4
+.IX Item "â„ž 17: Make file I/O default to utf8"
+.IP "â„ž 18: Make all I/O and args default to utf8" 4
+.IX Item "â„ž 18: Make all I/O and args default to utf8"
+.IP "â„ž 19: Open file with specific encoding" 4
+.IX Item "â„ž 19: Open file with specific encoding"
+.IP "â„ž 20: Unicode casing" 4
+.IX Item "â„ž 20: Unicode casing"
+.IP "â„ž 21: Unicode case-insensitive comparisons" 4
+.IX Item "â„ž 21: Unicode case-insensitive comparisons"
+.IP "â„ž 22: Match Unicode linebreak sequence in regex" 4
+.IX Item "â„ž 22: Match Unicode linebreak sequence in regex"
+.IP "â„ž 23: Get character category" 4
+.IX Item "â„ž 23: Get character category"
+.IP "â„ž 24: Disabling Unicode-awareness in builtin charclasses" 4
+.IX Item "â„ž 24: Disabling Unicode-awareness in builtin charclasses"
+.IP "â„ž 25: Match Unicode properties in regex with \ep, \eP" 4
+.IX Item "â„ž 25: Match Unicode properties in regex with p, P"
+.IP "â„ž 26: Custom character properties" 4
+.IX Item "â„ž 26: Custom character properties"
+.IP "â„ž 27: Unicode normalization" 4
+.IX Item "â„ž 27: Unicode normalization"
+.IP "â„ž 28: Convert non-ASCII Unicode numerics" 4
+.IX Item "â„ž 28: Convert non-ASCII Unicode numerics"
+.IP "â„ž 29: Match Unicode grapheme cluster in regex" 4
+.IX Item "â„ž 29: Match Unicode grapheme cluster in regex"
+.IP "â„ž 30: Extract by grapheme instead of by codepoint (regex)" 4
+.IX Item "â„ž 30: Extract by grapheme instead of by codepoint (regex)"
+.IP "â„ž 31: Extract by grapheme instead of by codepoint (substr)" 4
+.IX Item "â„ž 31: Extract by grapheme instead of by codepoint (substr)"
+.IP "â„ž 32: Reverse string by grapheme" 4
+.IX Item "â„ž 32: Reverse string by grapheme"
+.IP "â„ž 33: String length in graphemes" 4
+.IX Item "â„ž 33: String length in graphemes"
+.IP "â„ž 34: Unicode column-width for printing" 4
+.IX Item "â„ž 34: Unicode column-width for printing"
+.IP "â„ž 35: Unicode collation" 4
+.IX Item "â„ž 35: Unicode collation"
+.IP "â„ž 36: Case\- \fIand\fR accent-insensitive Unicode sort" 4
+.IX Item "â„ž 36: Case- and accent-insensitive Unicode sort"
+.IP "â„ž 37: Unicode locale collation" 4
+.IX Item "â„ž 37: Unicode locale collation"
+.ie n .IP "â„ž 38: Making ""cmp"" work on text instead of codepoints" 4
+.el .IP "â„ž 38: Making \f(CWcmp\fR work on text instead of codepoints" 4
+.IX Item "â„ž 38: Making cmp work on text instead of codepoints"
+.IP "â„ž 39: Case\- \fIand\fR accent-insensitive comparisons" 4
+.IX Item "â„ž 39: Case- and accent-insensitive comparisons"
+.IP "â„ž 40: Case\- \fIand\fR accent-insensitive locale comparisons" 4
+.IX Item "â„ž 40: Case- and accent-insensitive locale comparisons"
+.IP "â„ž 41: Unicode linebreaking" 4
+.IX Item "â„ž 41: Unicode linebreaking"
+.IP "â„ž 42: Unicode text in DBM hashes, the tedious way" 4
+.IX Item "â„ž 42: Unicode text in DBM hashes, the tedious way"
+.IP "â„ž 43: Unicode text in DBM hashes, the easy way" 4
+.IX Item "â„ž 43: Unicode text in DBM hashes, the easy way"
+.IP "â„ž 44: PROGRAM: Demo of Unicode collation and printing" 4
+.IX Item "â„ž 44: PROGRAM: Demo of Unicode collation and printing"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+§3.13 Default Case Algorithms, page 113; §4.2  Case, pages 120–122;
+Case Mappings, page 166–172, especially Caseless Matching starting on
+page 170, UAX #44: Unicode Character Database, UTS #18: Unicode Regular
+Expressions, UAX #15: Unicode Normalization Forms, UTS #10: Unicode
+Collation Algorithm, UAX #29: Unicode Text Segmentation, UAX #14: Unicode
+Line Breaking Algorithm, UAX #11: East Asian Width
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "COPYRIGHT AND LICENCE" 4
+.IX Item "COPYRIGHT AND LICENCE"
+.IP "REVISION HISTORY" 4
+.IX Item "REVISION HISTORY"
+.PD
+.SS "perlunifaq \- Perl Unicode FAQ"
+.IX Subsection "perlunifaq - Perl Unicode FAQ"
+.IP "Q and A" 4
+.IX Item "Q and A"
+.RS 4
+.PD 0
+.IP "perlunitut isn't really a Unicode tutorial, is it?" 4
+.IX Item "perlunitut isn't really a Unicode tutorial, is it?"
+.IP "What character encodings does Perl support?" 4
+.IX Item "What character encodings does Perl support?"
+.IP "Which version of perl should I use?" 4
+.IX Item "Which version of perl should I use?"
+.IP "What about binary data, like images?" 4
+.IX Item "What about binary data, like images?"
+.IP "When should I decode or encode?" 4
+.IX Item "When should I decode or encode?"
+.IP "What if I don't decode?" 4
+.IX Item "What if I don't decode?"
+.IP "What if I don't encode?" 4
+.IX Item "What if I don't encode?"
+.PD
+If the string's characters are all code point 255 or lower, Perl outputs
+bytes that match those code points. This is what happens with encoded
+strings. It can also, though, happen with unencoded strings that happen to
+be all code point 255 or lower, Otherwise, Perl outputs the string encoded
+as UTF\-8. This only happens with strings you neglected to encode. Since
+that should not happen, Perl also throws a "wide character" warning in this
+case
+.IP "Is there a way to automatically decode or encode?" 4
+.IX Item "Is there a way to automatically decode or encode?"
+.PD 0
+.IP "What if I don't know which encoding was used?" 4
+.IX Item "What if I don't know which encoding was used?"
+.IP "Can I use Unicode in my Perl sources?" 4
+.IX Item "Can I use Unicode in my Perl sources?"
+.IP "Data::Dumper doesn't restore the UTF8 flag; is it broken?" 4
+.IX Item "Data::Dumper doesn't restore the UTF8 flag; is it broken?"
+.IP "Why do regex character classes sometimes match only in the ASCII range?" 4
+.IX Item "Why do regex character classes sometimes match only in the ASCII range?"
+.IP "Why do some characters not uppercase or lowercase correctly?" 4
+.IX Item "Why do some characters not uppercase or lowercase correctly?"
+.IP "How can I determine if a string is a text string or a binary string?" 4
+.IX Item "How can I determine if a string is a text string or a binary string?"
+.IP "How do I convert from encoding FOO to encoding BAR?" 4
+.IX Item "How do I convert from encoding FOO to encoding BAR?"
+.ie n .IP "What are ""decode_utf8"" and ""encode_utf8""?" 4
+.el .IP "What are \f(CWdecode_utf8\fR and \f(CWencode_utf8\fR?" 4
+.IX Item "What are decode_utf8 and encode_utf8?"
+.IP "What is a ""wide character""?" 4
+.IX Item "What is a ""wide character""?"
+.RE
+.RS 4
+.RE
+.IP INTERNALS 4
+.IX Item "INTERNALS"
+.RS 4
+.IP "What is ""the UTF8 flag""?" 4
+.IX Item "What is ""the UTF8 flag""?"
+.ie n .IP "What about the ""use bytes"" pragma?" 4
+.el .IP "What about the \f(CWuse bytes\fR pragma?" 4
+.IX Item "What about the use bytes pragma?"
+.ie n .IP "What about the ""use encoding"" pragma?" 4
+.el .IP "What about the \f(CWuse encoding\fR pragma?" 4
+.IX Item "What about the use encoding pragma?"
+.ie n .IP "What is the difference between "":encoding"" and "":utf8""?" 4
+.el .IP "What is the difference between \f(CW:encoding\fR and \f(CW:utf8\fR?" 4
+.IX Item "What is the difference between :encoding and :utf8?"
+.ie n .IP "What's the difference between ""UTF\-8"" and ""utf8""?" 4
+.el .IP "What's the difference between \f(CWUTF\-8\fR and \f(CWutf8\fR?" 4
+.IX Item "What's the difference between UTF-8 and utf8?"
+.IP "I lost track; what encoding is the internal format really?" 4
+.IX Item "I lost track; what encoding is the internal format really?"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perluniprops \- Index of Unicode Version 15.0.0 character properties in Perl"
+.IX Subsection "perluniprops - Index of Unicode Version 15.0.0 character properties in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.ie n .IP "Properties accessible through ""\ep{}"" and ""\eP{}""" 4
+.el .IP "Properties accessible through \f(CW\ep{}\fR and \f(CW\eP{}\fR" 4
+.IX Item "Properties accessible through p{} and P{}"
+.PD
+Single form (\f(CW\*(C`\ep{name}\*(C'\fR) tighter rules:, white space adjacent to a
+non-word character, underscores separating digits in numbers, Compound form
+(\f(CW\*(C`\ep{name=value}\*(C'\fR or \f(CW\*(C`\ep{name:value}\*(C'\fR) tighter rules:, Stabilized,
+Deprecated, Obsolete, Discouraged, \fB*\fR is a wild-card, \fB(\ed+)\fR in the
+info column gives the number of Unicode code points matched by this
+property, \fBD\fR means this is deprecated, \fBO\fR means this is obsolete, \fBS\fR
+means this is stabilized, \fBT\fR means tighter (stricter) name matching
+applies, \fBX\fR means use of this form is discouraged, and may not be stable
+.RS 4
+.ie n .IP "Legal ""\ep{}"" and ""\eP{}"" constructs that match no characters" 4
+.el .IP "Legal \f(CW\ep{}\fR and \f(CW\eP{}\fR constructs that match no characters" 4
+.IX Item "Legal p{} and P{} constructs that match no characters"
+\&\ep{Canonical_Combining_Class=Attached_Below_Left},
+\&\ep{Canonical_Combining_Class=CCC133}, \ep{Grapheme_Cluster_Break=E_Base},
+\&\ep{Grapheme_Cluster_Break=E_Base_GAZ},
+\&\ep{Grapheme_Cluster_Break=E_Modifier},
+\&\ep{Grapheme_Cluster_Break=Glue_After_Zwj}, \ep{Word_Break=E_Base},
+\&\ep{Word_Break=E_Base_GAZ}, \ep{Word_Break=E_Modifier},
+\&\ep{Word_Break=Glue_After_Zwj}
+.RE
+.RS 4
+.RE
+.IP "Properties accessible through Unicode::UCD" 4
+.IX Item "Properties accessible through Unicode::UCD"
+.PD 0
+.IP "Properties accessible through other means" 4
+.IX Item "Properties accessible through other means"
+.IP "Unicode character properties that are NOT accepted by Perl" 4
+.IX Item "Unicode character properties that are NOT accepted by Perl"
+.PD
+\&\fIExpands_On_NFC\fR (XO_NFC), \fIExpands_On_NFD\fR (XO_NFD), \fIExpands_On_NFKC\fR
+(XO_NFKC), \fIExpands_On_NFKD\fR (XO_NFKD), \fIGrapheme_Link\fR (Gr_Link),
+\&\fIJamo_Short_Name\fR (JSN), \fIOther_Alphabetic\fR (OAlpha),
+\&\fIOther_Default_Ignorable_Code_Point\fR (ODI), \fIOther_Grapheme_Extend\fR
+(OGr_Ext), \fIOther_ID_Continue\fR (OIDC), \fIOther_ID_Start\fR (OIDS),
+\&\fIOther_Lowercase\fR (OLower), \fIOther_Math\fR (OMath), \fIOther_Uppercase\fR
+(OUpper), \fIScript=Katakana_Or_Hiragana\fR (sc=Hrkt),
+\&\fIScript_Extensions=Katakana_Or_Hiragana\fR (scx=Hrkt)
+.IP "Other information in the Unicode data base" 4
+.IX Item "Other information in the Unicode data base"
+\&\fIauxiliary/GraphemeBreakTest.html\fR, \fIauxiliary/LineBreakTest.html\fR,
+\&\fIauxiliary/SentenceBreakTest.html\fR, \fIauxiliary/WordBreakTest.html\fR,
+\&\fIBidiCharacterTest.txt\fR, \fIBidiTest.txt\fR, \fICJKRadicals.txt\fR,
+\&\fIconfusables.txt\fR, \fIconfusablesSummary.txt\fR, \fIintentional.txt\fR,
+\&\fIemoji/ReadMe.txt\fR, \fIReadMe.txt\fR, \fIEmojiSources.txt\fR,
+\&\fIextracted/DName.txt\fR, \fIIndex.txt\fR, \fINamedSqProv.txt\fR,
+\&\fINamesList.html\fR, \fINamesList.txt\fR, \fINormalizationCorrections.txt\fR,
+\&\fINushuSources.txt\fR, \fIStandardizedVariants.html\fR,
+\&\fIStandardizedVariants.txt\fR, \fITangutSources.txt\fR, \fIUSourceData.txt\fR,
+\&\fIUSourceGlyphs.pdf\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "perlunitut \- Perl Unicode Tutorial"
+.IX Subsection "perlunitut - Perl Unicode Tutorial"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Definitions 4
+.IX Item "Definitions"
+.IP "Your new toolkit" 4
+.IX Item "Your new toolkit"
+.IP "I/O flow (the actual 5 minute tutorial)" 4
+.IX Item "I/O flow (the actual 5 minute tutorial)"
+.RE
+.RS 4
+.RE
+.IP SUMMARY 4
+.IX Item "SUMMARY"
+.IP "Q and A (or FAQ)" 4
+.IX Item "Q and A (or FAQ)"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlebcdic \- Considerations for running Perl on EBCDIC platforms"
+.IX Subsection "perlebcdic - Considerations for running Perl on EBCDIC platforms"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "COMMON CHARACTER CODE SETS" 4
+.IX Item "COMMON CHARACTER CODE SETS"
+.RS 4
+.IP ASCII 4
+.IX Item "ASCII"
+.IP "ISO 8859" 4
+.IX Item "ISO 8859"
+.IP "Latin 1 (ISO 8859\-1)" 4
+.IX Item "Latin 1 (ISO 8859-1)"
+.IP EBCDIC 4
+.IX Item "EBCDIC"
+.PD
+\&\fB0037\fR, \fB1047\fR, \fBPOSIX-BC\fR
+.IP "Unicode code points versus EBCDIC code points" 4
+.IX Item "Unicode code points versus EBCDIC code points"
+.PD 0
+.IP "Unicode and UTF" 4
+.IX Item "Unicode and UTF"
+.IP "Using Encode" 4
+.IX Item "Using Encode"
+.RE
+.RS 4
+.RE
+.IP "SINGLE OCTET TABLES" 4
+.IX Item "SINGLE OCTET TABLES"
+.PD
+recipe 0, recipe 1, recipe 2, recipe 3, recipe 4, recipe 5, recipe 6
+.RS 4
+.IP "Table in hex, sorted in 1047 order" 4
+.IX Item "Table in hex, sorted in 1047 order"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "IDENTIFYING CHARACTER CODE SETS" 4
+.IX Item "IDENTIFYING CHARACTER CODE SETS"
+.IP CONVERSIONS 4
+.IX Item "CONVERSIONS"
+.RS 4
+.ie n .IP "utf8::unicode_to_native() and utf8::native_to_unicode()" 4
+.el .IP "\f(CWutf8::unicode_to_native()\fR and \f(CWutf8::native_to_unicode()\fR" 4
+.IX Item "utf8::unicode_to_native() and utf8::native_to_unicode()"
+.IP tr/// 4
+.IX Item "tr///"
+.IP iconv 4
+.IX Item "iconv"
+.IP "C RTL" 4
+.IX Item "C RTL"
+.RE
+.RS 4
+.RE
+.IP "OPERATOR DIFFERENCES" 4
+.IX Item "OPERATOR DIFFERENCES"
+.IP "FUNCTION DIFFERENCES" 4
+.IX Item "FUNCTION DIFFERENCES"
+.PD
+\&\f(CWchr()\fR, \f(CWord()\fR, \f(CWpack()\fR, \f(CWprint()\fR, \f(CWprintf()\fR, \f(CWsort()\fR,
+\&\f(CWsprintf()\fR, \f(CWunpack()\fR
+.IP "REGULAR EXPRESSION DIFFERENCES" 4
+.IX Item "REGULAR EXPRESSION DIFFERENCES"
+.PD 0
+.IP SOCKETS 4
+.IX Item "SOCKETS"
+.IP SORTING 4
+.IX Item "SORTING"
+.RS 4
+.IP "Ignore ASCII vs. EBCDIC sort differences." 4
+.IX Item "Ignore ASCII vs. EBCDIC sort differences."
+.IP "Use a sort helper function" 4
+.IX Item "Use a sort helper function"
+.IP "MONO CASE then sort data (for non-digits, non-underscore)" 4
+.IX Item "MONO CASE then sort data (for non-digits, non-underscore)"
+.IP "Perform sorting on one type of platform only." 4
+.IX Item "Perform sorting on one type of platform only."
+.RE
+.RS 4
+.RE
+.IP "TRANSFORMATION FORMATS" 4
+.IX Item "TRANSFORMATION FORMATS"
+.RS 4
+.IP "URL decoding and encoding" 4
+.IX Item "URL decoding and encoding"
+.IP "uu encoding and decoding" 4
+.IX Item "uu encoding and decoding"
+.IP "Quoted-Printable encoding and decoding" 4
+.IX Item "Quoted-Printable encoding and decoding"
+.IP "Caesarean ciphers" 4
+.IX Item "Caesarean ciphers"
+.RE
+.RS 4
+.RE
+.IP "Hashing order and checksums" 4
+.IX Item "Hashing order and checksums"
+.IP "I18N AND L10N" 4
+.IX Item "I18N AND L10N"
+.IP "MULTI-OCTET CHARACTER SETS" 4
+.IX Item "MULTI-OCTET CHARACTER SETS"
+.IP "OS ISSUES" 4
+.IX Item "OS ISSUES"
+.RS 4
+.IP OS/400 4
+.IX Item "OS/400"
+.PD
+PASE, IFS access
+.IP "OS/390, z/OS" 4
+.IX Item "OS/390, z/OS"
+\&\f(CW\*(C`sigaction\*(C'\fR, \f(CW\*(C`chcp\*(C'\fR, dataset access, \f(CW\*(C`iconv\*(C'\fR, locales
+.IP POSIX-BC? 4
+.IX Item "POSIX-BC?"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP REFERENCES 4
+.IX Item "REFERENCES"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlsec \- Perl security"
+.IX Subsection "perlsec - Perl security"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "SECURITY VULNERABILITY CONTACT INFORMATION" 4
+.IX Item "SECURITY VULNERABILITY CONTACT INFORMATION"
+.IP "SECURITY MECHANISMS AND CONCERNS" 4
+.IX Item "SECURITY MECHANISMS AND CONCERNS"
+.RS 4
+.IP "Taint mode" 4
+.IX Item "Taint mode"
+.IP "Laundering and Detecting Tainted Data" 4
+.IX Item "Laundering and Detecting Tainted Data"
+.IP "Switches On the ""#!"" Line" 4
+.IX Item "Switches On the ""#!"" Line"
+.ie n .IP "Taint mode and @INC" 4
+.el .IP "Taint mode and \f(CW@INC\fR" 4
+.IX Item "Taint mode and @INC"
+.IP "Cleaning Up Your Path" 4
+.IX Item "Cleaning Up Your Path"
+.IP "Shebang Race Condition" 4
+.IX Item "Shebang Race Condition"
+.IP "Protecting Your Programs" 4
+.IX Item "Protecting Your Programs"
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "Algorithmic Complexity Attacks" 4
+.IX Item "Algorithmic Complexity Attacks"
+.PD
+Hash Seed Randomization, Hash Traversal Randomization, Bucket Order
+Perturbance, New Default Hash Function, Alternative Hash Functions
+.IP "Using Sudo" 4
+.IX Item "Using Sudo"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlsecpolicy \- Perl security report handling policy"
+.IX Subsection "perlsecpolicy - Perl security report handling policy"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "REPORTING SECURITY ISSUES IN PERL" 4
+.IX Item "REPORTING SECURITY ISSUES IN PERL"
+.IP "WHAT ARE SECURITY ISSUES" 4
+.IX Item "WHAT ARE SECURITY ISSUES"
+.RS 4
+.IP "Software covered by the Perl security team" 4
+.IX Item "Software covered by the Perl security team"
+.IP "Bugs that may qualify as security issues in Perl" 4
+.IX Item "Bugs that may qualify as security issues in Perl"
+.IP "Bugs that do not qualify as security issues in Perl" 4
+.IX Item "Bugs that do not qualify as security issues in Perl"
+.IP "Bugs that require special categorization" 4
+.IX Item "Bugs that require special categorization"
+.RE
+.RS 4
+.RE
+.IP "HOW WE DEAL WITH SECURITY ISSUES" 4
+.IX Item "HOW WE DEAL WITH SECURITY ISSUES"
+.RS 4
+.IP "Perl's vulnerability remediation workflow" 4
+.IX Item "Perl's vulnerability remediation workflow"
+.IP "Publicly known and zero-day security issues" 4
+.IX Item "Publicly known and zero-day security issues"
+.IP "Vulnerability credit and bounties" 4
+.IX Item "Vulnerability credit and bounties"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlmod \- Perl modules (packages and symbol tables)"
+.IX Subsection "perlmod - Perl modules (packages and symbol tables)"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Is this the document you were after?" 4
+.IX Item "Is this the document you were after?"
+.PD
+This doc, perlnewmod, perlmodstyle
+.IP Packages 4
+.IX Xref "package namespace variable, global global variable global"
+.IX Item "Packages"
+.PD 0
+.IP "Symbol Tables" 4
+.IX Xref "symbol table stash %:: %main:: typeglob glob alias"
+.IX Item "Symbol Tables"
+.IP "BEGIN, UNITCHECK, CHECK, INIT and END" 4
+.IX Xref "BEGIN UNITCHECK CHECK INIT END"
+.IX Item "BEGIN, UNITCHECK, CHECK, INIT and END"
+.IP "Perl Classes" 4
+.IX Xref "class @ISA"
+.IX Item "Perl Classes"
+.IP "Perl Modules" 4
+.IX Xref "module"
+.IX Item "Perl Modules"
+.IP "Making your module threadsafe" 4
+.IX Xref "threadsafe thread safe module, threadsafe module, thread safe CLONE CLONE_SKIP thread threads ithread"
+.IX Item "Making your module threadsafe"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlmodlib \- constructing new Perl modules and finding existing ones"
+.IX Subsection "perlmodlib - constructing new Perl modules and finding existing ones"
+.IP "THE PERL MODULE LIBRARY" 4
+.IX Item "THE PERL MODULE LIBRARY"
+.RS 4
+.PD 0
+.IP "Pragmatic Modules" 4
+.IX Item "Pragmatic Modules"
+.PD
+attributes, autodie, autodie::exception, autodie::exception::system,
+autodie::hints, autodie::skip, autouse, base, bigfloat, bigint, bignum,
+bigrat, blib, builtin, bytes, charnames, constant, deprecate, diagnostics,
+encoding, encoding::warnings, experimental, feature, fields, filetest, if,
+integer, less, lib, locale, mro, ok, open, ops, overload, overloading,
+parent, re, sigtrap, sort, stable, strict, subs, threads, threads::shared,
+utf8, vars, version, vmsish, warnings, warnings::register
+.IP "Standard Modules" 4
+.IX Item "Standard Modules"
+Amiga::ARexx, Amiga::Exec, AnyDBM_File, App::Cpan, App::Prove,
+App::Prove::State, App::Prove::State::Result,
+App::Prove::State::Result::Test, Archive::Tar, Archive::Tar::File,
+Attribute::Handlers, AutoLoader, AutoSplit, B, B::Concise, B::Deparse,
+B::Op_private, B::Showlex, B::Terse, B::Xref, Benchmark, \f(CW\*(C`IO::Socket::IP\*(C'\fR,
+\&\f(CW\*(C`Socket\*(C'\fR, CORE, CPAN, CPAN::API::HOWTO, CPAN::Debug, CPAN::Distroprefs,
+CPAN::FirstTime, CPAN::HandleConfig, CPAN::Kwalify, CPAN::Meta,
+CPAN::Meta::Converter, CPAN::Meta::Feature, CPAN::Meta::History,
+CPAN::Meta::History::Meta_1_0, CPAN::Meta::History::Meta_1_1,
+CPAN::Meta::History::Meta_1_2, CPAN::Meta::History::Meta_1_3,
+CPAN::Meta::History::Meta_1_4, CPAN::Meta::Merge, CPAN::Meta::Prereqs,
+CPAN::Meta::Requirements, CPAN::Meta::Spec, CPAN::Meta::Validator,
+CPAN::Meta::YAML, CPAN::Nox, CPAN::Plugin, CPAN::Plugin::Specfile,
+CPAN::Queue, CPAN::Tarzip, CPAN::Version, Carp, Class::Struct,
+Compress::Raw::Bzip2, Compress::Raw::Zlib, Compress::Zlib, Config,
+Config::Extensions, Config::Perl::V, Cwd, DB, DBM_Filter,
+DBM_Filter::compress, DBM_Filter::encode, DBM_Filter::int32,
+DBM_Filter::null, DBM_Filter::utf8, DB_File, Data::Dumper, Devel::PPPort,
+Devel::Peek, Devel::SelfStubber, Digest, Digest::MD5, Digest::SHA,
+Digest::base, Digest::file, DirHandle, Dumpvalue, DynaLoader, Encode,
+Encode::Alias, Encode::Byte, Encode::CJKConstants, Encode::CN,
+Encode::CN::HZ, Encode::Config, Encode::EBCDIC, Encode::Encoder,
+Encode::Encoding, Encode::GSM0338, Encode::Guess, Encode::JP,
+Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR, Encode::KR::2022_KR,
+Encode::MIME::Header, Encode::MIME::Name, Encode::PerlIO,
+Encode::Supported, Encode::Symbol, Encode::TW, Encode::Unicode,
+Encode::Unicode::UTF7, English, Env, Errno, Exporter, Exporter::Heavy,
+ExtUtils::CBuilder, ExtUtils::CBuilder::Platform::Windows,
+ExtUtils::Command, ExtUtils::Command::MM, ExtUtils::Constant,
+ExtUtils::Constant::Base, ExtUtils::Constant::Utils,
+ExtUtils::Constant::XS, ExtUtils::Embed, ExtUtils::Install,
+ExtUtils::Installed, ExtUtils::Liblist, ExtUtils::MM, ExtUtils::MM::Utils,
+ExtUtils::MM_AIX, ExtUtils::MM_Any, ExtUtils::MM_BeOS, ExtUtils::MM_Cygwin,
+ExtUtils::MM_DOS, ExtUtils::MM_Darwin, ExtUtils::MM_MacOS,
+ExtUtils::MM_NW5, ExtUtils::MM_OS2, ExtUtils::MM_OS390, ExtUtils::MM_QNX,
+ExtUtils::MM_UWIN, ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_VOS,
+ExtUtils::MM_Win32, ExtUtils::MM_Win95, ExtUtils::MY, ExtUtils::MakeMaker,
+ExtUtils::MakeMaker::Config, ExtUtils::MakeMaker::FAQ,
+ExtUtils::MakeMaker::Locale, ExtUtils::MakeMaker::Tutorial,
+ExtUtils::Manifest, ExtUtils::Miniperl, ExtUtils::Mkbootstrap,
+ExtUtils::Mksymlists, ExtUtils::PL2Bat, ExtUtils::Packlist,
+ExtUtils::ParseXS, ExtUtils::ParseXS::Constants, ExtUtils::ParseXS::Eval,
+ExtUtils::ParseXS::Utilities, ExtUtils::Typemaps, ExtUtils::Typemaps::Cmd,
+ExtUtils::Typemaps::InputMap, ExtUtils::Typemaps::OutputMap,
+ExtUtils::Typemaps::Type, ExtUtils::XSSymSet, ExtUtils::testlib, Fatal,
+Fcntl, File::Basename, File::Compare, File::Copy, File::DosGlob,
+File::Fetch, File::Find, File::Glob, File::GlobMapper, File::Path,
+File::Spec, File::Spec::AmigaOS, File::Spec::Cygwin, File::Spec::Epoc,
+File::Spec::Functions, File::Spec::Mac, File::Spec::OS2, File::Spec::Unix,
+File::Spec::VMS, File::Spec::Win32, File::Temp, File::stat, FileCache,
+FileHandle, Filter::Simple, Filter::Util::Call, FindBin, GDBM_File,
+Getopt::Long, Getopt::Std, HTTP::Tiny, Hash::Util, Hash::Util::FieldHash,
+I18N::Collate, I18N::LangTags, I18N::LangTags::Detect,
+I18N::LangTags::List, I18N::Langinfo, IO, IO::Compress::Base,
+IO::Compress::Bzip2, IO::Compress::Deflate, IO::Compress::FAQ,
+IO::Compress::Gzip, IO::Compress::RawDeflate, IO::Compress::Zip, IO::Dir,
+IO::File, IO::Handle, IO::Pipe, IO::Poll, IO::Seekable, IO::Select,
+IO::Socket, IO::Socket::INET, IO::Socket::UNIX, IO::Uncompress::AnyInflate,
+IO::Uncompress::AnyUncompress, IO::Uncompress::Base,
+IO::Uncompress::Bunzip2, IO::Uncompress::Gunzip, IO::Uncompress::Inflate,
+IO::Uncompress::RawInflate, IO::Uncompress::Unzip, IO::Zlib, IPC::Cmd,
+IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, IPC::SharedMem,
+IPC::SysV, Internals, JSON::PP, JSON::PP::Boolean, List::Util,
+List::Util::XS, Locale::Maketext, Locale::Maketext::Cookbook,
+Locale::Maketext::Guts, Locale::Maketext::GutsLoader,
+Locale::Maketext::Simple, Locale::Maketext::TPJ13, MIME::Base64,
+MIME::QuotedPrint, Math::BigFloat, Math::BigInt, Math::BigInt::Calc,
+Math::BigInt::FastCalc, Math::BigInt::Lib, Math::BigRat, Math::Complex,
+Math::Trig, Memoize, Memoize::AnyDBM_File, Memoize::Expire,
+Memoize::NDBM_File, Memoize::SDBM_File, Memoize::Storable,
+Module::CoreList, Module::CoreList::Utils, Module::Load,
+Module::Load::Conditional, Module::Loaded, Module::Metadata, NDBM_File,
+NEXT, Net::Cmd, Net::Config, Net::Domain, Net::FTP, Net::FTP::dataconn,
+Net::NNTP, Net::Netrc, Net::POP3, Net::Ping, Net::SMTP, Net::Time,
+Net::hostent, Net::libnetFAQ, Net::netent, Net::protoent, Net::servent, O,
+ODBM_File, Opcode, POSIX, Params::Check, Parse::CPAN::Meta, Perl::OSType,
+PerlIO, PerlIO::encoding, PerlIO::mmap, PerlIO::scalar, PerlIO::via,
+PerlIO::via::QuotedPrint, Pod::Checker, Pod::Escapes, Pod::Functions,
+Pod::Html, Pod::Html::Util, Pod::Man, Pod::ParseLink, Pod::Perldoc,
+Pod::Perldoc::BaseTo, Pod::Perldoc::GetOptsOO, Pod::Perldoc::ToANSI,
+Pod::Perldoc::ToChecker, Pod::Perldoc::ToMan, Pod::Perldoc::ToNroff,
+Pod::Perldoc::ToPod, Pod::Perldoc::ToRtf, Pod::Perldoc::ToTerm,
+Pod::Perldoc::ToText, Pod::Perldoc::ToTk, Pod::Perldoc::ToXml, Pod::Simple,
+Pod::Simple::Checker, Pod::Simple::Debug, Pod::Simple::DumpAsText,
+Pod::Simple::DumpAsXML, Pod::Simple::HTML, Pod::Simple::HTMLBatch,
+Pod::Simple::JustPod, Pod::Simple::LinkSection, Pod::Simple::Methody,
+Pod::Simple::PullParser, Pod::Simple::PullParserEndToken,
+Pod::Simple::PullParserStartToken, Pod::Simple::PullParserTextToken,
+Pod::Simple::PullParserToken, Pod::Simple::RTF, Pod::Simple::Search,
+Pod::Simple::SimpleTree, Pod::Simple::Subclassing, Pod::Simple::Text,
+Pod::Simple::TextContent, Pod::Simple::XHTML, Pod::Simple::XMLOutStream,
+Pod::Text, Pod::Text::Color, Pod::Text::Overstrike, Pod::Text::Termcap,
+Pod::Usage, SDBM_File, Safe, Scalar::Util, Search::Dict, SelectSaver,
+SelfLoader, Storable, Sub::Util, Symbol, Sys::Hostname, Sys::Syslog,
+Sys::Syslog::Win32, TAP::Base, TAP::Formatter::Base, TAP::Formatter::Color,
+TAP::Formatter::Console, TAP::Formatter::Console::ParallelSession,
+TAP::Formatter::Console::Session, TAP::Formatter::File,
+TAP::Formatter::File::Session, TAP::Formatter::Session, TAP::Harness,
+TAP::Harness::Env, TAP::Object, TAP::Parser, TAP::Parser::Aggregator,
+TAP::Parser::Grammar, TAP::Parser::Iterator, TAP::Parser::Iterator::Array,
+TAP::Parser::Iterator::Process, TAP::Parser::Iterator::Stream,
+TAP::Parser::IteratorFactory, TAP::Parser::Multiplexer,
+TAP::Parser::Result, TAP::Parser::Result::Bailout,
+TAP::Parser::Result::Comment, TAP::Parser::Result::Plan,
+TAP::Parser::Result::Pragma, TAP::Parser::Result::Test,
+TAP::Parser::Result::Unknown, TAP::Parser::Result::Version,
+TAP::Parser::Result::YAML, TAP::Parser::ResultFactory,
+TAP::Parser::Scheduler, TAP::Parser::Scheduler::Job,
+TAP::Parser::Scheduler::Spinner, TAP::Parser::Source,
+TAP::Parser::SourceHandler, TAP::Parser::SourceHandler::Executable,
+TAP::Parser::SourceHandler::File, TAP::Parser::SourceHandler::Handle,
+TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::RawTAP,
+TAP::Parser::YAMLish::Reader, TAP::Parser::YAMLish::Writer,
+Term::ANSIColor, Term::Cap, Term::Complete, Term::ReadLine, Test, Test2,
+Test2::API, Test2::API::Breakage, Test2::API::Context,
+Test2::API::Instance, Test2::API::InterceptResult,
+Test2::API::InterceptResult::Event, Test2::API::InterceptResult::Hub,
+Test2::API::InterceptResult::Squasher, Test2::API::Stack, Test2::Event,
+Test2::Event::Bail, Test2::Event::Diag, Test2::Event::Encoding,
+Test2::Event::Exception, Test2::Event::Fail, Test2::Event::Generic,
+Test2::Event::Note, Test2::Event::Ok, Test2::Event::Pass,
+Test2::Event::Plan, Test2::Event::Skip, Test2::Event::Subtest,
+Test2::Event::TAP::Version, Test2::Event::V2, Test2::Event::Waiting,
+Test2::EventFacet, Test2::EventFacet::About, Test2::EventFacet::Amnesty,
+Test2::EventFacet::Assert, Test2::EventFacet::Control,
+Test2::EventFacet::Error, Test2::EventFacet::Hub, Test2::EventFacet::Info,
+Test2::EventFacet::Info::Table, Test2::EventFacet::Meta,
+Test2::EventFacet::Parent, Test2::EventFacet::Plan,
+Test2::EventFacet::Render, Test2::EventFacet::Trace, Test2::Formatter,
+Test2::Formatter::TAP, Test2::Hub, Test2::Hub::Interceptor,
+Test2::Hub::Interceptor::Terminator, Test2::Hub::Subtest, Test2::IPC,
+Test2::IPC::Driver, Test2::IPC::Driver::Files, Test2::Tools::Tiny,
+Test2::Transition, Test2::Util, Test2::Util::ExternalMeta,
+Test2::Util::Facets2Legacy, Test2::Util::HashBase, Test2::Util::Trace,
+Test::Builder, Test::Builder::Formatter, Test::Builder::IO::Scalar,
+Test::Builder::Module, Test::Builder::Tester, Test::Builder::Tester::Color,
+Test::Builder::TodoDiag, Test::Harness, Test::Harness::Beyond, Test::More,
+Test::Simple, Test::Tester, Test::Tester::Capture,
+Test::Tester::CaptureRunner, Test::Tutorial, Test::use::ok, Text::Abbrev,
+Text::Balanced, Text::ParseWords, Text::Tabs, Text::Wrap, Thread,
+Thread::Queue, Thread::Semaphore, Tie::Array, Tie::File, Tie::Handle,
+Tie::Hash, Tie::Hash::NamedCapture, Tie::Memoize, Tie::RefHash,
+Tie::Scalar, Tie::StdHandle, Tie::SubstrHash, Time::HiRes, Time::Local,
+Time::Piece, Time::Seconds, Time::gmtime, Time::localtime, Time::tm,
+UNIVERSAL, Unicode::Collate, Unicode::Collate::CJK::Big5,
+Unicode::Collate::CJK::GB2312, Unicode::Collate::CJK::JISX0208,
+Unicode::Collate::CJK::Korean, Unicode::Collate::CJK::Pinyin,
+Unicode::Collate::CJK::Stroke, Unicode::Collate::CJK::Zhuyin,
+Unicode::Collate::Locale, Unicode::Normalize, Unicode::UCD, User::grent,
+User::pwent, VMS::DCLsym, VMS::Filespec, VMS::Stdio, Win32, Win32API::File,
+Win32CORE, XS::APItest, XS::Typemap, XSLoader, autodie::Scope::Guard,
+autodie::Scope::GuardStack, autodie::Util, version::Internals
+.IP "Extension Modules" 4
+.IX Item "Extension Modules"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP CPAN 4
+.IX Item "CPAN"
+.IP "Modules: Creation, Use, and Abuse" 4
+.IX Item "Modules: Creation, Use, and Abuse"
+.RS 4
+.IP "Guidelines for Module Creation" 4
+.IX Item "Guidelines for Module Creation"
+.IP "Guidelines for Converting Perl 4 Library Scripts into Modules" 4
+.IX Item "Guidelines for Converting Perl 4 Library Scripts into Modules"
+.IP "Guidelines for Reusing Application Code" 4
+.IX Item "Guidelines for Reusing Application Code"
+.RE
+.RS 4
+.RE
+.IP NOTE 4
+.IX Item "NOTE"
+.PD
+.SS "perlmodstyle \- Perl module style guide"
+.IX Subsection "perlmodstyle - Perl module style guide"
+.IP INTRODUCTION 4
+.IX Item "INTRODUCTION"
+.PD 0
+.IP "QUICK CHECKLIST" 4
+.IX Item "QUICK CHECKLIST"
+.RS 4
+.IP "Before you start" 4
+.IX Item "Before you start"
+.IP "The API" 4
+.IX Item "The API"
+.IP Stability 4
+.IX Item "Stability"
+.IP Documentation 4
+.IX Item "Documentation"
+.IP "Release considerations" 4
+.IX Item "Release considerations"
+.RE
+.RS 4
+.RE
+.IP "BEFORE YOU START WRITING A MODULE" 4
+.IX Item "BEFORE YOU START WRITING A MODULE"
+.RS 4
+.IP "Has it been done before?" 4
+.IX Item "Has it been done before?"
+.IP "Do one thing and do it well" 4
+.IX Item "Do one thing and do it well"
+.IP "What's in a name?" 4
+.IX Item "What's in a name?"
+.IP "Get feedback before publishing" 4
+.IX Item "Get feedback before publishing"
+.RE
+.RS 4
+.RE
+.IP "DESIGNING AND WRITING YOUR MODULE" 4
+.IX Item "DESIGNING AND WRITING YOUR MODULE"
+.RS 4
+.IP "To OO or not to OO?" 4
+.IX Item "To OO or not to OO?"
+.IP "Designing your API" 4
+.IX Item "Designing your API"
+.PD
+Write simple routines to do simple things, Separate functionality from
+output, Provide sensible shortcuts and defaults, Naming conventions,
+Parameter passing
+.IP "Strictness and warnings" 4
+.IX Item "Strictness and warnings"
+.PD 0
+.IP "Backwards compatibility" 4
+.IX Item "Backwards compatibility"
+.IP "Error handling and messages" 4
+.IX Item "Error handling and messages"
+.RE
+.RS 4
+.RE
+.IP "DOCUMENTING YOUR MODULE" 4
+.IX Item "DOCUMENTING YOUR MODULE"
+.RS 4
+.IP POD 4
+.IX Item "POD"
+.IP "README, INSTALL, release notes, changelogs" 4
+.IX Item "README, INSTALL, release notes, changelogs"
+.PD
+perl Makefile.PL, make, make test, make install, perl Build.PL, perl Build,
+perl Build test, perl Build install
+.RE
+.RS 4
+.RE
+.IP "RELEASE CONSIDERATIONS" 4
+.IX Item "RELEASE CONSIDERATIONS"
+.RS 4
+.PD 0
+.IP "Version numbering" 4
+.IX Item "Version numbering"
+.IP Pre-requisites 4
+.IX Item "Pre-requisites"
+.IP Testing 4
+.IX Item "Testing"
+.IP Packaging 4
+.IX Item "Packaging"
+.IP Licensing 4
+.IX Item "Licensing"
+.RE
+.RS 4
+.RE
+.IP "COMMON PITFALLS" 4
+.IX Item "COMMON PITFALLS"
+.RS 4
+.IP "Reinventing the wheel" 4
+.IX Item "Reinventing the wheel"
+.IP "Trying to do too much" 4
+.IX Item "Trying to do too much"
+.IP "Inappropriate documentation" 4
+.IX Item "Inappropriate documentation"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+perlstyle, perlnewmod, perlpod, podchecker, Packaging Tools,
+Testing tools, <https://pause.perl.org/>, Any good book on software
+engineering
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "perlmodinstall \- Installing CPAN Modules"
+.IX Subsection "perlmodinstall - Installing CPAN Modules"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP PREAMBLE 4
+.IX Item "PREAMBLE"
+.PD
+\&\fBDECOMPRESS\fR the file, \fBUNPACK\fR the file into a directory, \fBBUILD\fR the
+module (sometimes unnecessary), \fBINSTALL\fR the module
+.RE
+.RS 4
+.RE
+.IP PORTABILITY 4
+.IX Item "PORTABILITY"
+.PD 0
+.IP HEY 4
+.IX Item "HEY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "perlnewmod \- preparing a new module for distribution"
+.IX Subsection "perlnewmod - preparing a new module for distribution"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP Warning 4
+.IX Item "Warning"
+.IP "What should I make into a module?" 4
+.IX Item "What should I make into a module?"
+.IP "Step-by-step: Preparing the ground" 4
+.IX Item "Step-by-step: Preparing the ground"
+.PD
+Look around, Check it's new, Discuss the need, Choose a name, Check again
+.IP "Step-by-step: Making the module" 4
+.IX Item "Step-by-step: Making the module"
+Start with \fImodule-starter\fR or \fIh2xs\fR, Use strict and
+warnings, Use Carp, Use Exporter \- wisely!,
+Use plain old documentation, Write tests, Write the \fIREADME\fR,
+Write \fIChanges\fR
+.IP "Step-by-step: Distributing your module" 4
+.IX Item "Step-by-step: Distributing your module"
+Get a CPAN user ID, Make the tarball, Upload the tarball, Fix bugs!
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlpragma \- how to write a user pragma"
+.IX Subsection "perlpragma - how to write a user pragma"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "A basic example" 4
+.IX Item "A basic example"
+.IP "Key naming" 4
+.IX Item "Key naming"
+.IP "Implementation details" 4
+.IX Item "Implementation details"
+.PD
+.SS "perlutil \- utilities packaged with the Perl distribution"
+.IX Subsection "perlutil - utilities packaged with the Perl distribution"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "LIST OF UTILITIES" 4
+.IX Item "LIST OF UTILITIES"
+.RS 4
+.IP Documentation 4
+.IX Item "Documentation"
+.PD
+perldoc, pod2man, pod2text, pod2html, pod2usage,
+podchecker, splain, \fIroffitall\fR
+.IP Converters 4
+.IX Item "Converters"
+pl2pm
+.IP Administration 4
+.IX Item "Administration"
+libnetcfg, perlivp
+.IP Development 4
+.IX Item "Development"
+perlbug, perlthanks, h2ph, h2xs, enc2xs, xsubpp,
+prove, corelist
+.IP "General tools" 4
+.IX Item "General tools"
+encguess, json_pp, piconv, ptar, ptardiff, ptargrep,
+shasum, streamzip, zipdetails
+.IP Installation 4
+.IX Item "Installation"
+cpan, instmodsh
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "perlfilter \- Source Filters"
+.IX Subsection "perlfilter - Source Filters"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONCEPTS 4
+.IX Item "CONCEPTS"
+.IP "USING FILTERS" 4
+.IX Item "USING FILTERS"
+.IP "WRITING A SOURCE FILTER" 4
+.IX Item "WRITING A SOURCE FILTER"
+.IP "WRITING A SOURCE FILTER IN C" 4
+.IX Item "WRITING A SOURCE FILTER IN C"
+.PD
+\&\fBDecryption Filters\fR
+.IP "CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE" 4
+.IX Item "CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE"
+.PD 0
+.IP "WRITING A SOURCE FILTER IN PERL" 4
+.IX Item "WRITING A SOURCE FILTER IN PERL"
+.IP "USING CONTEXT: THE DEBUG FILTER" 4
+.IX Item "USING CONTEXT: THE DEBUG FILTER"
+.IP CONCLUSION 4
+.IX Item "CONCLUSION"
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP "THINGS TO LOOK OUT FOR" 4
+.IX Item "THINGS TO LOOK OUT FOR"
+.PD
+Some Filters Clobber the \f(CW\*(C`DATA\*(C'\fR Handle
+.IP REQUIREMENTS 4
+.IX Item "REQUIREMENTS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP Copyrights 4
+.IX Item "Copyrights"
+.PD
+.SS "perldtrace \- Perl's support for DTrace"
+.IX Subsection "perldtrace - Perl's support for DTrace"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP PROBES 4
+.IX Item "PROBES"
+.PD
+sub\-entry(SUBNAME, FILE, LINE, PACKAGE), sub\-return(SUBNAME, FILE, LINE,
+PACKAGE), phase\-change(NEWPHASE, OLDPHASE), op\-entry(OPNAME),
+loading\-file(FILENAME), loaded\-file(FILENAME)
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+Most frequently called functions, Trace function calls, Function calls
+during interpreter cleanup, System calls at compile time, Perl functions
+that execute the most opcodes
+.IP REFERENCES 4
+.IX Item "REFERENCES"
+DTrace Dynamic Tracing Guide, DTrace: Dynamic Tracing in Oracle Solaris,
+Mac OS X and FreeBSD
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+Devel::DTrace::Provider
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.SS "perlglossary \- Perl Glossary"
+.IX Subsection "perlglossary - Perl Glossary"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP A 4
+.IX Item "A"
+.PD
+accessor methods, actual arguments, address operator, algorithm, alias,
+alphabetic, alternatives, anonymous, application, architecture, argument,
+ARGV, arithmetical operator, array, array context, Artistic License, ASCII,
+assertion, assignment, assignment operator, associative array,
+associativity, asynchronous, atom, atomic operation, attribute,
+autogeneration, autoincrement, autoload, autosplit, autovivification, AV,
+awk
+.IP B 4
+.IX Item "B"
+backreference, backtracking, backward compatibility, bareword, base class,
+big-endian, binary, binary operator, bind, bit, bit shift, bit string,
+bless, block, BLOCK, block buffering, Boolean, Boolean context, breakpoint,
+broadcast, BSD, bucket, buffer, built-in, bundle, byte, bytecode
+.IP C 4
+.IX Item "C"
+C, cache, callback, call by reference, call by value, canonical, capture
+variables, capturing, cargo cult, case, casefolding, casemapping,
+character, character class, character property, circumfix operator, class,
+class method, client, closure, cluster, CODE, code generator, codepoint,
+code subpattern, collating sequence, co-maintainer, combining character,
+command, command buffering, command-line arguments, command name, comment,
+compilation unit, compile, compile phase, compiler, compile time, composer,
+concatenation, conditional, connection, construct, constructor, context,
+continuation, core dump, CPAN, C preprocessor, cracker, currently selected
+output channel, current package, current working directory, CV
+.IP D 4
+.IX Item "D"
+dangling statement, datagram, data structure, data type, DBM, declaration,
+declarator, decrement, default, defined, delimiter, dereference, derived
+class, descriptor, destroy, destructor, device, directive, directory,
+directory handle, discipline, dispatch, distribution, dual-lived, dweomer,
+dwimmer, dynamic scoping
+.IP E 4
+.IX Item "E"
+eclectic, element, embedding, empty subclass test, encapsulation, endian,
+en passant, environment, environment variable, EOF, errno, error, escape
+sequence, exception, exception handling, exec, executable file, execute,
+execute bit, exit status, exploit, export, expression, extension
+.IP F 4
+.IX Item "F"
+false, FAQ, fatal error, feeping creaturism, field, FIFO, file, file
+descriptor, fileglob, filehandle, filename, filesystem, file test operator,
+filter, first-come, flag, floating point, flush, FMTEYEWTK, foldcase, fork,
+formal arguments, format, freely available, freely redistributable,
+freeware, function, funny character
+.IP G 4
+.IX Item "G"
+garbage collection, GID, glob, global, global destruction, glue language,
+granularity, grapheme, greedy, grep, group, GV
+.IP H 4
+.IX Item "H"
+hacker, handler, hard reference, hash, hash table, header file, here
+document, hexadecimal, home directory, host, hubris, HV
+.IP I 4
+.IX Item "I"
+identifier, impatience, implementation, import, increment, indexing,
+indirect filehandle, indirection, indirect object, indirect object slot,
+infix, inheritance, instance, instance data, instance method, instance
+variable, integer, interface, interpolation, interpreter, invocant,
+invocation, I/O, IO, I/O layer, IPA, IP, IPC, is-a, iteration, iterator, IV
+.IP J 4
+.IX Item "J"
+JAPH
+.IP K 4
+.IX Item "K"
+key, keyword
+.IP L 4
+.IX Item "L"
+label, laziness, leftmost longest, left shift, lexeme, lexer, lexical
+analysis, lexical scoping, lexical variable, library, LIFO, line,
+linebreak, line buffering, line number, link, LIST, list, list context,
+list operator, list value, literal, little-endian, local, logical operator,
+lookahead, lookbehind, loop, loop control statement, loop label, lowercase,
+lvaluable, lvalue, lvalue modifier
+.IP M 4
+.IX Item "M"
+magic, magical increment, magical variables, Makefile, man, manpage,
+matching, member data, memory, metacharacter, metasymbol, method, method
+resolution order, minicpan, minimalism, mode, modifier, module, modulus,
+mojibake, monger, mortal, mro, multidimensional array, multiple inheritance
+.IP N 4
+.IX Item "N"
+named pipe, namespace, NaN, network address, newline, NFS, normalization,
+null character, null list, null string, numeric context, numification, NV,
+nybble
+.IP O 4
+.IX Item "O"
+object, octal, offset, one-liner, open source software, operand, operating
+system, operator, operator overloading, options, ordinal, overloading,
+overriding, owner
+.IP P 4
+.IX Item "P"
+package, pad, parameter, parent class, parse tree, parsing, patch, PATH,
+pathname, pattern, pattern matching, PAUSE, Perl mongers, permission bits,
+Pern, pipe, pipeline, platform, pod, pod command, pointer, polymorphism,
+port, portable, porter, possessive, POSIX, postfix, pp, pragma, precedence,
+prefix, preprocessing, primary maintainer, procedure, process, program,
+program generator, progressive matching, property, protocol, prototype,
+pseudofunction, pseudohash, pseudoliteral, public domain, pumpkin,
+pumpking, PV
+.IP Q 4
+.IX Item "Q"
+qualified, quantifier
+.IP R 4
+.IX Item "R"
+race condition, readable, reaping, record, recursion, reference, referent,
+regex, regular expression, regular expression modifier, regular file,
+relational operator, reserved words, return value, RFC, right shift, role,
+root, RTFM, run phase, runtime, runtime pattern, RV, rvalue
+.IP S 4
+.IX Item "S"
+sandbox, scalar, scalar context, scalar literal, scalar value, scalar
+variable, scope, scratchpad, script, script kiddie, sed, semaphore,
+separator, serialization, server, service, setgid, setuid, shared memory,
+shebang, shell, side effects, sigil, signal, signal handler, single
+inheritance, slice, slurp, socket, soft reference, source filter, stack,
+standard, standard error, standard input, standard I/O, Standard Library,
+standard output, statement, statement modifier, static, static method,
+static scoping, static variable, stat structure, status, STDERR, STDIN,
+STDIO, STDOUT, stream, string, string context, stringification, struct,
+structure, subclass, subpattern, subroutine, subscript, substitution,
+substring, superclass, superuser, SV, switch, switch cluster, switch
+statement, symbol, symbolic debugger, symbolic link, symbolic reference,
+symbol table, synchronous, syntactic sugar, syntax, syntax tree, syscall
+.IP T 4
+.IX Item "T"
+taint checks, tainted, taint mode, TCP, term, terminator, ternary, text,
+thread, tie, titlecase, TMTOWTDI, token, tokener, tokenizing, toolbox
+approach, topic, transliterate, trigger, trinary, troff, true, truncating,
+type, type casting, typedef, typed lexical, typeglob, typemap
+.IP U 4
+.IX Item "U"
+UDP, UID, umask, unary operator, Unicode, Unix, uppercase
+.IP V 4
+.IX Item "V"
+value, variable, variable interpolation, variadic, vector, virtual, void
+context, v\-string
+.IP W 4
+.IX Item "W"
+warning, watch expression, weak reference, whitespace, word, working
+directory, wrapper, WYSIWYG
+.IP X 4
+.IX Item "X"
+XS, XSUB
+.IP Y 4
+.IX Item "Y"
+yacc
+.IP Z 4
+.IX Item "Z"
+zero width, zombie
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.SS "perlembed \- how to embed perl in your C program"
+.IX Subsection "perlembed - how to embed perl in your C program"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP PREAMBLE 4
+.IX Item "PREAMBLE"
+.PD
+\&\fBUse C from Perl?\fR, \fBUse a Unix program from Perl?\fR, \fBUse Perl from
+Perl?\fR, \fBUse C from C?\fR, \fBUse Perl from C?\fR
+.IP ROADMAP 4
+.IX Item "ROADMAP"
+.PD 0
+.IP "Compiling your C program" 4
+.IX Item "Compiling your C program"
+.IP "Adding a Perl interpreter to your C program" 4
+.IX Item "Adding a Perl interpreter to your C program"
+.IP "Calling a Perl subroutine from your C program" 4
+.IX Item "Calling a Perl subroutine from your C program"
+.IP "Evaluating a Perl statement from your C program" 4
+.IX Item "Evaluating a Perl statement from your C program"
+.IP "Performing Perl pattern matches and substitutions from your C program" 4
+.IX Item "Performing Perl pattern matches and substitutions from your C program"
+.IP "Fiddling with the Perl stack from your C program" 4
+.IX Item "Fiddling with the Perl stack from your C program"
+.IP "Maintaining a persistent interpreter" 4
+.IX Item "Maintaining a persistent interpreter"
+.IP "Execution of END blocks" 4
+.IX Item "Execution of END blocks"
+.ie n .IP "$0 assignments" 4
+.el .IP "\f(CW$0\fR assignments" 4
+.IX Item "$0 assignments"
+.IP "Maintaining multiple interpreter instances" 4
+.IX Item "Maintaining multiple interpreter instances"
+.IP "Using Perl modules, which themselves use C libraries, from your C program" 4
+.IX Item "Using Perl modules, which themselves use C libraries, from your C program"
+.IP "Using embedded Perl with POSIX locales" 4
+.IX Item "Using embedded Perl with POSIX locales"
+.RE
+.RS 4
+.RE
+.IP "Hiding Perl_" 4
+.IX Item "Hiding Perl_"
+.IP MORAL 4
+.IX Item "MORAL"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "perldebguts \- Guts of Perl debugging"
+.IX Subsection "perldebguts - Guts of Perl debugging"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Debugger Internals" 4
+.IX Item "Debugger Internals"
+.RS 4
+.IP "Writing Your Own Debugger" 4
+.IX Item "Writing Your Own Debugger"
+.RE
+.RS 4
+.RE
+.IP "Frame Listing Output Examples" 4
+.IX Item "Frame Listing Output Examples"
+.IP "Debugging Regular Expressions" 4
+.IX Item "Debugging Regular Expressions"
+.RS 4
+.IP "Compile-time Output" 4
+.IX Item "Compile-time Output"
+.PD
+\&\f(CW\*(C`anchored\*(C'\fR \fISTRING\fR \f(CW\*(C`at\*(C'\fR \fIPOS\fR, \f(CW\*(C`floating\*(C'\fR \fISTRING\fR \f(CW\*(C`at\*(C'\fR
+\&\fIPOS1..POS2\fR, \f(CW\*(C`matching floating/anchored\*(C'\fR, \f(CW\*(C`minlen\*(C'\fR, \f(CW\*(C`stclass\*(C'\fR
+\&\fITYPE\fR, \f(CW\*(C`noscan\*(C'\fR, \f(CW\*(C`isall\*(C'\fR, \f(CW\*(C`GPOS\*(C'\fR, \f(CW\*(C`plus\*(C'\fR, \f(CW\*(C`implicit\*(C'\fR, \f(CW\*(C`with eval\*(C'\fR,
+\&\f(CWanchored(TYPE)\fR
+.IP "Types of Nodes" 4
+.IX Item "Types of Nodes"
+.PD 0
+.IP "Run-time Output" 4
+.IX Item "Run-time Output"
+.RE
+.RS 4
+.RE
+.IP "Debugging Perl Memory Usage" 4
+.IX Item "Debugging Perl Memory Usage"
+.RS 4
+.ie n .IP "Using $ENV{PERL_DEBUG_MSTATS}" 4
+.el .IP "Using \f(CW$ENV{PERL_DEBUG_MSTATS}\fR" 4
+.IX Item "Using $ENV{PERL_DEBUG_MSTATS}"
+.PD
+\&\f(CW\*(C`buckets SMALLEST(APPROX)..GREATEST(APPROX)\*(C'\fR, Free/Used, \f(CW\*(C`Total sbrk():
+SBRKed/SBRKs:CONTINUOUS\*(C'\fR, \f(CW\*(C`pad: 0\*(C'\fR, \f(CW\*(C`heads: 2192\*(C'\fR, \f(CW\*(C`chain: 0\*(C'\fR, \f(CWtail:
+6144\fR
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "perlxstut \- Tutorial for writing XSUBs"
+.IX Subsection "perlxstut - Tutorial for writing XSUBs"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SPECIAL NOTES" 4
+.IX Item "SPECIAL NOTES"
+.RS 4
+.IP make 4
+.IX Item "make"
+.IP "Version caveat" 4
+.IX Item "Version caveat"
+.IP "Dynamic Loading versus Static Loading" 4
+.IX Item "Dynamic Loading versus Static Loading"
+.IP "Threads and PERL_NO_GET_CONTEXT" 4
+.IX Item "Threads and PERL_NO_GET_CONTEXT"
+.RE
+.RS 4
+.RE
+.IP TUTORIAL 4
+.IX Item "TUTORIAL"
+.RS 4
+.IP "EXAMPLE 1" 4
+.IX Item "EXAMPLE 1"
+.IP "EXAMPLE 2" 4
+.IX Item "EXAMPLE 2"
+.IP "What has gone on?" 4
+.IX Item "What has gone on?"
+.IP "Writing good test scripts" 4
+.IX Item "Writing good test scripts"
+.IP "EXAMPLE 3" 4
+.IX Item "EXAMPLE 3"
+.IP "What's new here?" 4
+.IX Item "What's new here?"
+.IP "Input and Output Parameters" 4
+.IX Item "Input and Output Parameters"
+.IP "The XSUBPP Program" 4
+.IX Item "The XSUBPP Program"
+.IP "The TYPEMAP file" 4
+.IX Item "The TYPEMAP file"
+.IP "Warning about Output Arguments" 4
+.IX Item "Warning about Output Arguments"
+.IP "EXAMPLE 4" 4
+.IX Item "EXAMPLE 4"
+.IP "What has happened here?" 4
+.IX Item "What has happened here?"
+.IP "Anatomy of .xs file" 4
+.IX Item "Anatomy of .xs file"
+.IP "Getting the fat out of XSUBs" 4
+.IX Item "Getting the fat out of XSUBs"
+.IP "More about XSUB arguments" 4
+.IX Item "More about XSUB arguments"
+.IP "The Argument Stack" 4
+.IX Item "The Argument Stack"
+.IP "Extending your Extension" 4
+.IX Item "Extending your Extension"
+.IP "Documenting your Extension" 4
+.IX Item "Documenting your Extension"
+.IP "Installing your Extension" 4
+.IX Item "Installing your Extension"
+.IP "EXAMPLE 5" 4
+.IX Item "EXAMPLE 5"
+.IP "New Things in this Example" 4
+.IX Item "New Things in this Example"
+.IP "EXAMPLE 6" 4
+.IX Item "EXAMPLE 6"
+.IP "New Things in this Example" 4
+.IX Item "New Things in this Example"
+.IP "EXAMPLE 7 (Coming Soon)" 4
+.IX Item "EXAMPLE 7 (Coming Soon)"
+.IP "EXAMPLE 8 (Coming Soon)" 4
+.IX Item "EXAMPLE 8 (Coming Soon)"
+.IP "EXAMPLE 9 Passing open files to XSes" 4
+.IX Item "EXAMPLE 9 Passing open files to XSes"
+.IP "Troubleshooting these Examples" 4
+.IX Item "Troubleshooting these Examples"
+.RE
+.RS 4
+.RE
+.IP "See also" 4
+.IX Item "See also"
+.IP Author 4
+.IX Item "Author"
+.RS 4
+.IP "Last Changed" 4
+.IX Item "Last Changed"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlxs \- XS language reference manual"
+.IX Subsection "perlxs - XS language reference manual"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP Introduction 4
+.IX Item "Introduction"
+.IP "On The Road" 4
+.IX Item "On The Road"
+.IP "The Anatomy of an XSUB" 4
+.IX Item "The Anatomy of an XSUB"
+.IP "The Argument Stack" 4
+.IX Item "The Argument Stack"
+.IP "The RETVAL Variable" 4
+.IX Item "The RETVAL Variable"
+.IP "Returning SVs, AVs and HVs through RETVAL" 4
+.IX Item "Returning SVs, AVs and HVs through RETVAL"
+.IP "The MODULE Keyword" 4
+.IX Item "The MODULE Keyword"
+.IP "The PACKAGE Keyword" 4
+.IX Item "The PACKAGE Keyword"
+.IP "The PREFIX Keyword" 4
+.IX Item "The PREFIX Keyword"
+.IP "The OUTPUT: Keyword" 4
+.IX Item "The OUTPUT: Keyword"
+.IP "The NO_OUTPUT Keyword" 4
+.IX Item "The NO_OUTPUT Keyword"
+.IP "The CODE: Keyword" 4
+.IX Item "The CODE: Keyword"
+.IP "The INIT: Keyword" 4
+.IX Item "The INIT: Keyword"
+.IP "The NO_INIT Keyword" 4
+.IX Item "The NO_INIT Keyword"
+.IP "The TYPEMAP: Keyword" 4
+.IX Item "The TYPEMAP: Keyword"
+.IP "Initializing Function Parameters" 4
+.IX Item "Initializing Function Parameters"
+.IP "Default Parameter Values" 4
+.IX Item "Default Parameter Values"
+.IP "The PREINIT: Keyword" 4
+.IX Item "The PREINIT: Keyword"
+.IP "The SCOPE: Keyword" 4
+.IX Item "The SCOPE: Keyword"
+.IP "The INPUT: Keyword" 4
+.IX Item "The INPUT: Keyword"
+.IP "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords" 4
+.IX Item "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords"
+.ie n .IP "The length(NAME) Keyword" 4
+.el .IP "The \f(CWlength(NAME)\fR Keyword" 4
+.IX Item "The length(NAME) Keyword"
+.IP "Variable-length Parameter Lists" 4
+.IX Item "Variable-length Parameter Lists"
+.IP "The C_ARGS: Keyword" 4
+.IX Item "The C_ARGS: Keyword"
+.IP "The PPCODE: Keyword" 4
+.IX Item "The PPCODE: Keyword"
+.IP "Returning Undef And Empty Lists" 4
+.IX Item "Returning Undef And Empty Lists"
+.IP "The REQUIRE: Keyword" 4
+.IX Item "The REQUIRE: Keyword"
+.IP "The CLEANUP: Keyword" 4
+.IX Item "The CLEANUP: Keyword"
+.IP "The POSTCALL: Keyword" 4
+.IX Item "The POSTCALL: Keyword"
+.IP "The BOOT: Keyword" 4
+.IX Item "The BOOT: Keyword"
+.IP "The VERSIONCHECK: Keyword" 4
+.IX Item "The VERSIONCHECK: Keyword"
+.IP "The PROTOTYPES: Keyword" 4
+.IX Item "The PROTOTYPES: Keyword"
+.IP "The PROTOTYPE: Keyword" 4
+.IX Item "The PROTOTYPE: Keyword"
+.IP "The ALIAS: Keyword" 4
+.IX Item "The ALIAS: Keyword"
+.IP "The OVERLOAD: Keyword" 4
+.IX Item "The OVERLOAD: Keyword"
+.IP "The FALLBACK: Keyword" 4
+.IX Item "The FALLBACK: Keyword"
+.IP "The INTERFACE: Keyword" 4
+.IX Item "The INTERFACE: Keyword"
+.IP "The INTERFACE_MACRO: Keyword" 4
+.IX Item "The INTERFACE_MACRO: Keyword"
+.IP "The INCLUDE: Keyword" 4
+.IX Item "The INCLUDE: Keyword"
+.IP "The INCLUDE_COMMAND: Keyword" 4
+.IX Item "The INCLUDE_COMMAND: Keyword"
+.IP "The CASE: Keyword" 4
+.IX Item "The CASE: Keyword"
+.IP "The EXPORT_XSUB_SYMBOLS: Keyword" 4
+.IX Item "The EXPORT_XSUB_SYMBOLS: Keyword"
+.IP "The & Unary Operator" 4
+.IX Item "The & Unary Operator"
+.IP "Inserting POD, Comments and C Preprocessor Directives" 4
+.IX Item "Inserting POD, Comments and C Preprocessor Directives"
+.IP "Using XS With C++" 4
+.IX Item "Using XS With C++"
+.IP "Interface Strategy" 4
+.IX Item "Interface Strategy"
+.IP "Perl Objects And C Structures" 4
+.IX Item "Perl Objects And C Structures"
+.IP "Safely Storing Static Data in XS" 4
+.IX Item "Safely Storing Static Data in XS"
+.PD
+MY_CXT_KEY, typedef my_cxt_t, START_MY_CXT, MY_CXT_INIT, dMY_CXT, MY_CXT,
+aMY_CXT/pMY_CXT, MY_CXT_CLONE, MY_CXT_INIT_INTERP(my_perl),
+dMY_CXT_INTERP(my_perl)
+.IP "Thread-aware system interfaces" 4
+.IX Item "Thread-aware system interfaces"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+Non-locale-aware XS code, Locale-aware XS code
+.IP "XS VERSION" 4
+.IX Item "XS VERSION"
+.PD 0
+.IP "AUTHOR DIAGNOSTICS" 4
+.IX Item "AUTHOR DIAGNOSTICS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlxstypemap \- Perl XS C/Perl type mapping"
+.IX Subsection "perlxstypemap - Perl XS C/Perl type mapping"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Anatomy of a typemap" 4
+.IX Item "Anatomy of a typemap"
+.IP "The Role of the typemap File in Your Distribution" 4
+.IX Item "The Role of the typemap File in Your Distribution"
+.IP "Sharing typemaps Between CPAN Distributions" 4
+.IX Item "Sharing typemaps Between CPAN Distributions"
+.IP "Writing typemap Entries" 4
+.IX Item "Writing typemap Entries"
+.IP "Full Listing of Core Typemaps" 4
+.IX Item "Full Listing of Core Typemaps"
+.PD
+T_SV, T_SVREF, T_SVREF_FIXED, T_AVREF, T_AVREF_REFCOUNT_FIXED, T_HVREF,
+T_HVREF_REFCOUNT_FIXED, T_CVREF, T_CVREF_REFCOUNT_FIXED, T_SYSRET, T_UV,
+T_IV, T_INT, T_ENUM, T_BOOL, T_U_INT, T_SHORT, T_U_SHORT, T_LONG, T_U_LONG,
+T_CHAR, T_U_CHAR, T_FLOAT, T_NV, T_DOUBLE, T_PV, T_PTR, T_PTRREF, T_PTROBJ,
+T_REF_IV_REF, T_REF_IV_PTR, T_PTRDESC, T_REFREF, T_REFOBJ, T_OPAQUEPTR,
+T_OPAQUE, Implicit array, T_PACKED, T_PACKEDARRAY, T_DATAUNIT, T_CALLBACK,
+T_ARRAY, T_STDIO, T_INOUT, T_IN, T_OUT
+.RE
+.RS 4
+.RE
+.SS "perlclib \- Internal replacements for standard C library functions"
+.IX Subsection "perlclib - Internal replacements for standard C library functions"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP Conventions 4
+.IX Item "Conventions"
+.PD
+\&\f(CW\*(C`t\*(C'\fR, \f(CW\*(C`p\*(C'\fR, \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`s\*(C'\fR
+.IP "File Operations" 4
+.IX Item "File Operations"
+.PD 0
+.IP "File Input and Output" 4
+.IX Item "File Input and Output"
+.IP "File Positioning" 4
+.IX Item "File Positioning"
+.IP "Memory Management and String Handling" 4
+.IX Item "Memory Management and String Handling"
+.IP "Character Class Tests" 4
+.IX Item "Character Class Tests"
+.IP "\fIstdlib.h\fR functions" 4
+.IX Item "stdlib.h functions"
+.IP "Miscellaneous functions" 4
+.IX Item "Miscellaneous functions"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlguts \- Introduction to the Perl API"
+.IX Subsection "perlguts - Introduction to the Perl API"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Variables 4
+.IX Item "Variables"
+.RS 4
+.IP Datatypes 4
+.IX Item "Datatypes"
+.IP "What is an ""IV""?" 4
+.IX Item "What is an ""IV""?"
+.IP "Working with SVs" 4
+.IX Item "Working with SVs"
+.PD
+\&\f(CWSvIV(SV*)\fR (\f(CW\*(C`IV\*(C'\fR) and \f(CWSvUV(SV*)\fR (\f(CW\*(C`UV\*(C'\fR), \f(CWSvNV(SV*)\fR (\f(CW\*(C`double\*(C'\fR),
+Strings are a bit complicated:, Byte string: \f(CW\*(C`SvPVbyte(SV*, STRLEN len)\*(C'\fR
+or \f(CWSvPVbyte_nolen(SV*)\fR, UTF\-8 string: \f(CW\*(C`SvPVutf8(SV*, STRLEN len)\*(C'\fR or
+\&\f(CWSvPVutf8_nolen(SV*)\fR, You can also use \f(CW\*(C`SvPV(SV*, STRLEN len)\*(C'\fR or
+\&\f(CWSvPV_nolen(SV*)\fR to fetch the SV's raw internal buffer. This is tricky,
+though; if your Perl string is \f(CW"\exff\exff"\fR, then depending on the SV's
+internal encoding you might get back a 2\-byte \fBOR\fR a 4\-byte \f(CW\*(C`char*\*(C'\fR.
+Moreover, if it's the 4\-byte string, that could come from either Perl
+\&\f(CW"\exff\exff"\fR stored UTF\-8 encoded, or Perl \f(CW"\exc3\exbf\exc3\exbf"\fR stored as
+raw octets. To differentiate between these you \fBMUST\fR look up the SV's
+UTF8 bit (cf. \f(CW\*(C`SvUTF8\*(C'\fR) to know whether the source Perl string is 2
+characters (\f(CW\*(C`SvUTF8\*(C'\fR would be on) or 4 characters (\f(CW\*(C`SvUTF8\*(C'\fR would be off)
+.IP Offsets 4
+.IX Item "Offsets"
+.PD 0
+.IP "What's Really Stored in an SV?" 4
+.IX Item "What's Really Stored in an SV?"
+.IP "Working with AVs" 4
+.IX Item "Working with AVs"
+.PD
+\&\f(CW\*(C`av_store_simple\*(C'\fR, \f(CW\*(C`av_fetch_simple\*(C'\fR, \f(CW\*(C`av_push_simple\*(C'\fR, are not magical,
+are not readonly, are "real" (refcounted) AVs, have an av_top_index value >
+\&\-2
+.IP "Working with HVs" 4
+.IX Item "Working with HVs"
+.PD 0
+.IP "Hash API Extensions" 4
+.IX Item "Hash API Extensions"
+.IP "AVs, HVs and undefined values" 4
+.IX Item "AVs, HVs and undefined values"
+.IP References 4
+.IX Item "References"
+.IP "Blessed References and Class Objects" 4
+.IX Item "Blessed References and Class Objects"
+.IP "Creating New Variables" 4
+.IX Item "Creating New Variables"
+.PD
+GV_ADDMULTI, GV_ADDWARN
+.IP "Reference Counts and Mortality" 4
+.IX Item "Reference Counts and Mortality"
+.PD 0
+.IP "Stashes and Globs" 4
+.IX Item "Stashes and Globs"
+.IP "I/O Handles" 4
+.IX Item "I/O Handles"
+.IP "Double-Typed SVs" 4
+.IX Item "Double-Typed SVs"
+.IP "Read-Only Values" 4
+.IX Item "Read-Only Values"
+.IP "Copy on Write" 4
+.IX Item "Copy on Write"
+.IP "Magic Variables" 4
+.IX Item "Magic Variables"
+.IP "Assigning Magic" 4
+.IX Item "Assigning Magic"
+.IP "Magic Virtual Tables" 4
+.IX Item "Magic Virtual Tables"
+.IP "Finding Magic" 4
+.IX Item "Finding Magic"
+.IP "Understanding the Magic of Tied Hashes and Arrays" 4
+.IX Item "Understanding the Magic of Tied Hashes and Arrays"
+.IP "Localizing changes" 4
+.IX Item "Localizing changes"
+.PD
+\&\f(CW\*(C`SAVEINT(int i)\*(C'\fR, \f(CW\*(C`SAVEIV(IV i)\*(C'\fR, \f(CW\*(C`SAVEI32(I32 i)\*(C'\fR, \f(CW\*(C`SAVELONG(long i)\*(C'\fR,
+\&\f(CW\*(C`SAVEI8(I8 i)\*(C'\fR, \f(CW\*(C`SAVEI16(I16 i)\*(C'\fR, \f(CW\*(C`SAVEBOOL(int i)\*(C'\fR, \f(CW\*(C`SAVESTRLEN(STRLEN
+i)\*(C'\fR, \f(CWSAVESPTR(s)\fR, \f(CWSAVEPPTR(p)\fR, \f(CW\*(C`SAVERCPV(char **ppv)\*(C'\fR,
+\&\f(CW\*(C`SAVEGENERICSV(SV **psv)\*(C'\fR, \f(CW\*(C`SAVEFREESV(SV *sv)\*(C'\fR, \f(CW\*(C`SAVEMORTALIZESV(SV
+*sv)\*(C'\fR, \f(CW\*(C`SAVEFREEOP(OP *op)\*(C'\fR, \f(CWSAVEFREEPV(p)\fR, \f(CW\*(C`SAVEFREERCPV(char *pv)\*(C'\fR,
+\&\f(CW\*(C`SAVECLEARSV(SV *sv)\*(C'\fR, \f(CW\*(C`SAVEDELETE(HV *hv, char *key, I32 length)\*(C'\fR,
+\&\f(CW\*(C`SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)\*(C'\fR,
+\&\f(CW\*(C`SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)\*(C'\fR, \f(CW\*(C`MORTALSVFUNC_X(SVFUNC_t
+f, SV *sv)\*(C'\fR, \f(CW\*(C`MORTALDESTRUCTOR_SV(SV *coderef, SV *args)\*(C'\fR,
+\&\f(CWSAVESTACK_POS()\fR, \f(CW\*(C`SV* save_scalar(GV *gv)\*(C'\fR, \f(CW\*(C`AV* save_ary(GV *gv)\*(C'\fR,
+\&\f(CW\*(C`HV* save_hash(GV *gv)\*(C'\fR, \f(CW\*(C`void save_item(SV *item)\*(C'\fR, \f(CW\*(C`SV* save_svref(SV
+**sptr)\*(C'\fR, \f(CW\*(C`void save_aptr(AV **aptr)\*(C'\fR, \f(CW\*(C`void save_hptr(HV **hptr)\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP Subroutines 4
+.IX Item "Subroutines"
+.RS 4
+.PD 0
+.IP "XSUBs and the Argument Stack" 4
+.IX Item "XSUBs and the Argument Stack"
+.IP "Autoloading with XSUBs" 4
+.IX Item "Autoloading with XSUBs"
+.IP "Calling Perl Routines from within C Programs" 4
+.IX Item "Calling Perl Routines from within C Programs"
+.IP "Putting a C value on Perl stack" 4
+.IX Item "Putting a C value on Perl stack"
+.IP Scratchpads 4
+.IX Item "Scratchpads"
+.IP "Scratchpads and recursion" 4
+.IX Item "Scratchpads and recursion"
+.RE
+.RS 4
+.RE
+.IP "Memory Allocation" 4
+.IX Item "Memory Allocation"
+.RS 4
+.IP Allocation 4
+.IX Item "Allocation"
+.IP Reallocation 4
+.IX Item "Reallocation"
+.IP Moving 4
+.IX Item "Moving"
+.RE
+.RS 4
+.RE
+.IP PerlIO 4
+.IX Item "PerlIO"
+.IP "Compiled code" 4
+.IX Item "Compiled code"
+.RS 4
+.IP "Code tree" 4
+.IX Item "Code tree"
+.IP "Examining the tree" 4
+.IX Item "Examining the tree"
+.IP "Compile pass 1: check routines" 4
+.IX Item "Compile pass 1: check routines"
+.IP "Compile pass 1a: constant folding" 4
+.IX Item "Compile pass 1a: constant folding"
+.IP "Compile pass 2: context propagation" 4
+.IX Item "Compile pass 2: context propagation"
+.IP "Compile pass 3: peephole optimization" 4
+.IX Item "Compile pass 3: peephole optimization"
+.IP "Pluggable runops" 4
+.IX Item "Pluggable runops"
+.IP "Compile-time scope hooks" 4
+.IX Item "Compile-time scope hooks"
+.PD
+\&\f(CW\*(C`void bhk_start(pTHX_ int full)\*(C'\fR, \f(CW\*(C`void bhk_pre_end(pTHX_ OP **o)\*(C'\fR,
+\&\f(CW\*(C`void bhk_post_end(pTHX_ OP **o)\*(C'\fR, \f(CW\*(C`void bhk_eval(pTHX_ OP *const o)\*(C'\fR
+.RE
+.RS 4
+.RE
+.ie n .IP "Examining internal data structures with the ""dump"" functions" 4
+.el .IP "Examining internal data structures with the \f(CWdump\fR functions" 4
+.IX Item "Examining internal data structures with the dump functions"
+.PD 0
+.IP "How multiple interpreters and concurrency are supported" 4
+.IX Item "How multiple interpreters and concurrency are supported"
+.RS 4
+.IP "Background and MULTIPLICITY" 4
+.IX Item "Background and MULTIPLICITY"
+.IP "So what happened to dTHR?" 4
+.IX Item "So what happened to dTHR?"
+.IP "How do I use all this in extensions?" 4
+.IX Item "How do I use all this in extensions?"
+.IP "Should I do anything special if I call perl from multiple threads?" 4
+.IX Item "Should I do anything special if I call perl from multiple threads?"
+.IP "Future Plans and PERL_IMPLICIT_SYS" 4
+.IX Item "Future Plans and PERL_IMPLICIT_SYS"
+.RE
+.RS 4
+.RE
+.IP "Internal Functions" 4
+.IX Item "Internal Functions"
+.RS 4
+.IP "Formatted Printing of IVs, UVs, and NVs" 4
+.IX Item "Formatted Printing of IVs, UVs, and NVs"
+.IP "Formatted Printing of SVs" 4
+.IX Item "Formatted Printing of SVs"
+.IP "Formatted Printing of Strings" 4
+.IX Item "Formatted Printing of Strings"
+.RE
+.RS 4
+.RE
+.ie n .IP "Formatted Printing of ""Size_t"" and ""SSize_t""" 4
+.el .IP "Formatted Printing of \f(CWSize_t\fR and \f(CWSSize_t\fR" 4
+.IX Item "Formatted Printing of Size_t and SSize_t"
+.ie n .IP "Formatted Printing of ""Ptrdiff_t"", ""intmax_t"", ""short"" and other special sizes" 4
+.el .IP "Formatted Printing of \f(CWPtrdiff_t\fR, \f(CWintmax_t\fR, \f(CWshort\fR and other special sizes" 4
+.IX Item "Formatted Printing of Ptrdiff_t, intmax_t, short and other special sizes"
+.IP "Pointer-To-Integer and Integer-To-Pointer" 4
+.IX Item "Pointer-To-Integer and Integer-To-Pointer"
+.IP "Exception Handling" 4
+.IX Item "Exception Handling"
+.IP "Source Documentation" 4
+.IX Item "Source Documentation"
+.IP "Backwards compatibility" 4
+.IX Item "Backwards compatibility"
+.IP "Unicode Support" 4
+.IX Item "Unicode Support"
+.RS 4
+.IP "What \fBis\fR Unicode, anyway?" 4
+.IX Item "What is Unicode, anyway?"
+.IP "How can I recognise a UTF\-8 string?" 4
+.IX Item "How can I recognise a UTF-8 string?"
+.IP "How does UTF\-8 represent Unicode characters?" 4
+.IX Item "How does UTF-8 represent Unicode characters?"
+.IP "How does Perl store UTF\-8 strings?" 4
+.IX Item "How does Perl store UTF-8 strings?"
+.IP "How do I pass a Perl string to a C library?" 4
+.IX Item "How do I pass a Perl string to a C library?"
+.PD
+bytes: 0x64 0x78 0x8c, UTF\-8: 0x64 0x78 0xc2 0x8c
+.IP "How do I convert a string to UTF\-8?" 4
+.IX Item "How do I convert a string to UTF-8?"
+.PD 0
+.IP "How do I compare strings?" 4
+.IX Item "How do I compare strings?"
+.IP "Is there anything else I need to know?" 4
+.IX Item "Is there anything else I need to know?"
+.RE
+.RS 4
+.RE
+.IP "Custom Operators" 4
+.IX Item "Custom Operators"
+.PD
+xop_name, xop_desc, xop_class, OA_BASEOP, OA_UNOP, OA_BINOP, OA_LOGOP,
+OA_LISTOP, OA_PMOP, OA_SVOP, OA_PADOP, OA_PVOP_OR_SVOP, OA_LOOP, OA_COP,
+xop_peep
+.IP Stacks 4
+.IX Item "Stacks"
+.RS 4
+.PD 0
+.IP "Value Stack" 4
+.IX Item "Value Stack"
+.IP "Mark Stack" 4
+.IX Item "Mark Stack"
+.IP "Temporaries Stack" 4
+.IX Item "Temporaries Stack"
+.IP "Save Stack" 4
+.IX Item "Save Stack"
+.IP "Scope Stack" 4
+.IX Item "Scope Stack"
+.RE
+.RS 4
+.RE
+.IP "Dynamic Scope and the Context Stack" 4
+.IX Item "Dynamic Scope and the Context Stack"
+.RS 4
+.IP "Introduction to the context stack" 4
+.IX Item "Introduction to the context stack"
+.IP "Pushing contexts" 4
+.IX Item "Pushing contexts"
+.IP "Popping contexts" 4
+.IX Item "Popping contexts"
+.IP "Redoing contexts" 4
+.IX Item "Redoing contexts"
+.RE
+.RS 4
+.RE
+.IP "Slab-based operator allocation" 4
+.IX Item "Slab-based operator allocation"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlcall \- Perl calling conventions from C"
+.IX Subsection "perlcall - Perl calling conventions from C"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+An Error Handler, An Event-Driven Program
+.IP "THE CALL_ FUNCTIONS" 4
+.IX Item "THE CALL_ FUNCTIONS"
+call_sv, call_pv, call_method, call_argv
+.IP "FLAG VALUES" 4
+.IX Item "FLAG VALUES"
+.RS 4
+.PD 0
+.IP G_VOID 4
+.IX Item "G_VOID"
+.IP G_SCALAR 4
+.IX Item "G_SCALAR"
+.IP G_LIST 4
+.IX Item "G_LIST"
+.IP G_DISCARD 4
+.IX Item "G_DISCARD"
+.IP G_NOARGS 4
+.IX Item "G_NOARGS"
+.IP G_EVAL 4
+.IX Item "G_EVAL"
+.IP G_KEEPERR 4
+.IX Item "G_KEEPERR"
+.IP "Determining the Context" 4
+.IX Item "Determining the Context"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "No Parameters, Nothing Returned" 4
+.IX Item "No Parameters, Nothing Returned"
+.IP "Passing Parameters" 4
+.IX Item "Passing Parameters"
+.IP "Returning a Scalar" 4
+.IX Item "Returning a Scalar"
+.IP "Returning a List of Values" 4
+.IX Item "Returning a List of Values"
+.IP "Returning a List in Scalar Context" 4
+.IX Item "Returning a List in Scalar Context"
+.IP "Returning Data from Perl via the Parameter List" 4
+.IX Item "Returning Data from Perl via the Parameter List"
+.IP "Using G_EVAL" 4
+.IX Item "Using G_EVAL"
+.IP "Using G_KEEPERR" 4
+.IX Item "Using G_KEEPERR"
+.IP "Using call_sv" 4
+.IX Item "Using call_sv"
+.IP "Using call_argv" 4
+.IX Item "Using call_argv"
+.IP "Using call_method" 4
+.IX Item "Using call_method"
+.IP "Using GIMME_V" 4
+.IX Item "Using GIMME_V"
+.IP "Using Perl to Dispose of Temporaries" 4
+.IX Item "Using Perl to Dispose of Temporaries"
+.IP "Strategies for Storing Callback Context Information" 4
+.IX Item "Strategies for Storing Callback Context Information"
+.PD
+1. Ignore the problem \- Allow only 1 callback, 2. Create a sequence of
+callbacks \- hard wired limit, 3. Use a parameter to map to the Perl
+callback
+.IP "Alternate Stack Manipulation" 4
+.IX Item "Alternate Stack Manipulation"
+.PD 0
+.IP "Creating and Calling an Anonymous Subroutine in C" 4
+.IX Item "Creating and Calling an Anonymous Subroutine in C"
+.RE
+.RS 4
+.RE
+.IP "LIGHTWEIGHT CALLBACKS" 4
+.IX Item "LIGHTWEIGHT CALLBACKS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP DATE 4
+.IX Item "DATE"
+.PD
+.SS "perlmroapi \- Perl method resolution plugin interface"
+.IX Subsection "perlmroapi - Perl method resolution plugin interface"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+resolve, name, length, kflags, hash
+.IP Callbacks 4
+.IX Item "Callbacks"
+.PD 0
+.IP Caching 4
+.IX Item "Caching"
+.IP Examples 4
+.IX Item "Examples"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "perlreapi \- Perl regular expression plugin interface"
+.IX Subsection "perlreapi - Perl regular expression plugin interface"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Callbacks 4
+.IX Item "Callbacks"
+.RS 4
+.IP comp 4
+.IX Item "comp"
+.PD
+\&\f(CW\*(C`/m\*(C'\fR \- RXf_PMf_MULTILINE, \f(CW\*(C`/s\*(C'\fR \- RXf_PMf_SINGLELINE, \f(CW\*(C`/i\*(C'\fR \-
+RXf_PMf_FOLD, \f(CW\*(C`/x\*(C'\fR \- RXf_PMf_EXTENDED, \f(CW\*(C`/p\*(C'\fR \- RXf_PMf_KEEPCOPY, Character
+set, RXf_SPLIT, RXf_SKIPWHITE, RXf_START_ONLY, RXf_WHITE, RXf_NULL,
+RXf_NO_INPLACE_SUBST
+.IP exec 4
+.IX Item "exec"
+rx, sv, strbeg, strend, stringarg, minend, data, flags
+.IP intuit 4
+.IX Item "intuit"
+.PD 0
+.IP checkstr 4
+.IX Item "checkstr"
+.IP free 4
+.IX Item "free"
+.IP "Numbered capture callbacks" 4
+.IX Item "Numbered capture callbacks"
+.IP "Named capture callbacks" 4
+.IX Item "Named capture callbacks"
+.IP qr_package 4
+.IX Item "qr_package"
+.IP dupe 4
+.IX Item "dupe"
+.IP op_comp 4
+.IX Item "op_comp"
+.RE
+.RS 4
+.RE
+.IP "The REGEXP structure" 4
+.IX Item "The REGEXP structure"
+.RS 4
+.ie n .IP """engine""" 4
+.el .IP \f(CWengine\fR 4
+.IX Item "engine"
+.ie n .IP """mother_re""" 4
+.el .IP \f(CWmother_re\fR 4
+.IX Item "mother_re"
+.ie n .IP """extflags""" 4
+.el .IP \f(CWextflags\fR 4
+.IX Item "extflags"
+.ie n .IP """minlen"" ""minlenret""" 4
+.el .IP "\f(CWminlen\fR \f(CWminlenret\fR" 4
+.IX Item "minlen minlenret"
+.ie n .IP """gofs""" 4
+.el .IP \f(CWgofs\fR 4
+.IX Item "gofs"
+.ie n .IP """substrs""" 4
+.el .IP \f(CWsubstrs\fR 4
+.IX Item "substrs"
+.ie n .IP """nparens"", ""lastparen"", and ""lastcloseparen""" 4
+.el .IP "\f(CWnparens\fR, \f(CWlastparen\fR, and \f(CWlastcloseparen\fR" 4
+.IX Item "nparens, lastparen, and lastcloseparen"
+.ie n .IP """intflags""" 4
+.el .IP \f(CWintflags\fR 4
+.IX Item "intflags"
+.ie n .IP """pprivate""" 4
+.el .IP \f(CWpprivate\fR 4
+.IX Item "pprivate"
+.ie n .IP """offs""" 4
+.el .IP \f(CWoffs\fR 4
+.IX Item "offs"
+.ie n .IP """precomp"" ""prelen""" 4
+.el .IP "\f(CWprecomp\fR \f(CWprelen\fR" 4
+.IX Item "precomp prelen"
+.ie n .IP """paren_names""" 4
+.el .IP \f(CWparen_names\fR 4
+.IX Item "paren_names"
+.ie n .IP """substrs""" 4
+.el .IP \f(CWsubstrs\fR 4
+.IX Item "substrs"
+.ie n .IP """subbeg"" ""sublen"" ""saved_copy"" ""suboffset"" ""subcoffset""" 4
+.el .IP "\f(CWsubbeg\fR \f(CWsublen\fR \f(CWsaved_copy\fR \f(CWsuboffset\fR \f(CWsubcoffset\fR" 4
+.IX Item "subbeg sublen saved_copy suboffset subcoffset"
+.ie n .IP """wrapped"" ""wraplen""" 4
+.el .IP "\f(CWwrapped\fR \f(CWwraplen\fR" 4
+.IX Item "wrapped wraplen"
+.ie n .IP """seen_evals""" 4
+.el .IP \f(CWseen_evals\fR 4
+.IX Item "seen_evals"
+.ie n .IP """refcnt""" 4
+.el .IP \f(CWrefcnt\fR 4
+.IX Item "refcnt"
+.RE
+.RS 4
+.RE
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "perlreguts \- Description of the Perl regular expression engine."
+.IX Subsection "perlreguts - Description of the Perl regular expression engine."
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP OVERVIEW 4
+.IX Item "OVERVIEW"
+.RS 4
+.IP "A quick note on terms" 4
+.IX Item "A quick note on terms"
+.IP "What is a regular expression engine?" 4
+.IX Item "What is a regular expression engine?"
+.IP "Structure of a Regexp Program" 4
+.IX Item "Structure of a Regexp Program"
+.PD
+\&\f(CW\*(C`regnode_1\*(C'\fR, \f(CW\*(C`regnode_2\*(C'\fR, \f(CW\*(C`regnode_string\*(C'\fR, \f(CW\*(C`regnode_charclass\*(C'\fR,
+\&\f(CW\*(C`regnode_charclass_posixl\*(C'\fR, "REGNODE_AFTER", "regnext"
+.RE
+.RS 4
+.RE
+.IP "Process Overview" 4
+.IX Item "Process Overview"
+A. Compilation, 1. Parsing, 2. Peep-hole optimisation and analysis, B.
+Execution, 3. Start position and no-match optimisations, 4. Program
+execution
+.RS 4
+.IP Compilation 4
+.IX Item "Compilation"
+anchored fixed strings, floating fixed strings, minimum and maximum length
+requirements, start class, Beginning/End of line positions
+.IP Execution 4
+.IX Item "Execution"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP MISCELLANEOUS 4
+.IX Item "MISCELLANEOUS"
+.RS 4
+.IP "Unicode and Localisation Support" 4
+.IX Item "Unicode and Localisation Support"
+.IP "Base Structures" 4
+.IX Item "Base Structures"
+.PD
+\&\f(CW\*(C`regstclass\*(C'\fR, \f(CW\*(C`data\*(C'\fR, \f(CW\*(C`code_blocks\*(C'\fR, \f(CW\*(C`proglen\*(C'\fR, \f(CW\*(C`name_list_idx\*(C'\fR,
+\&\f(CW\*(C`program\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP REFERENCES 4
+.IX Item "REFERENCES"
+.PD
+.ie n .SS "perlclassguts \- Internals of how ""feature \*(Aqclass\*(Aq"" and class syntax works"
+.el .SS "perlclassguts \- Internals of how \f(CWfeature \*(Aqclass\*(Aq\fP and class syntax works"
+.IX Subsection "perlclassguts - Internals of how feature class and class syntax works"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "DATA STORAGE" 4
+.IX Item "DATA STORAGE"
+.RS 4
+.IP Classes 4
+.IX Item "Classes"
+.IP Fields 4
+.IX Item "Fields"
+.IP Methods 4
+.IX Item "Methods"
+.IP Instances 4
+.IX Item "Instances"
+.RE
+.RS 4
+.RE
+.IP API 4
+.IX Item "API"
+.RS 4
+.IP "Class Manipulation" 4
+.IX Item "Class Manipulation"
+.IP "Field Manipulation" 4
+.IX Item "Field Manipulation"
+.IP "Method Manipulation" 4
+.IX Item "Method Manipulation"
+.IP "Object Instances" 4
+.IX Item "Object Instances"
+.RE
+.RS 4
+.RE
+.IP OPCODES 4
+.IX Item "OPCODES"
+.RS 4
+.IP OP_METHSTART 4
+.IX Item "OP_METHSTART"
+.IP OP_INITFIELD 4
+.IX Item "OP_INITFIELD"
+.RE
+.RS 4
+.RE
+.IP "COMPILE-TIME BEHAVIOUR" 4
+.IX Item "COMPILE-TIME BEHAVIOUR"
+.RS 4
+.ie n .IP """ADJUST"" Phasers" 4
+.el .IP "\f(CWADJUST\fR Phasers" 4
+.IX Item "ADJUST Phasers"
+.IP Attributes 4
+.IX Item "Attributes"
+.IP "Field Initializing Expressions" 4
+.IX Item "Field Initializing Expressions"
+.RE
+.RS 4
+.RE
+.IP "RUNTIME BEHAVIOUR" 4
+.IX Item "RUNTIME BEHAVIOUR"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.ie n .IP "$self Access During Methods" 4
+.el .IP "\f(CW$self\fR Access During Methods" 4
+.IX Item "$self Access During Methods"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "perlapi \- autogenerated documentation for the perl public API"
+.IX Subsection "perlapi - autogenerated documentation for the perl public API"
+.IP DESCRIPTION 4
+.IX Xref "Perl API API api"
+.IX Item "DESCRIPTION"
+"AV Handling" in perlapi, "Callback Functions" in perlapi, "Casting" in perlapi,
+"Character case changing" in perlapi, "Character classification" in perlapi,
+"Compiler and Preprocessor information" in perlapi, "Compiler
+directives" in perlapi, "Compile-time scope hooks" in perlapi, "Concurrency" in perlapi,
+"COPs and Hint Hashes" in perlapi, "Custom Operators" in perlapi, "CV
+Handling" in perlapi, "Debugging" in perlapi, "Display functions" in perlapi,
+"Embedding, Threads, and Interpreter Cloning" in perlapi, "Errno" in perlapi,
+"Exception Handling (simple) Macros" in perlapi, "Filesystem
+configuration values" in perlapi, "Floating point" in perlapi, "General
+Configuration" in perlapi, "Global Variables" in perlapi, "GV Handling and
+Stashes" in perlapi, "Hook manipulation" in perlapi, "HV Handling" in perlapi,
+"Input/Output" in perlapi, "Integer" in perlapi, "I/O Formats" in perlapi,
+"Lexer interface" in perlapi, "Locales" in perlapi, "Magic" in perlapi,
+"Memory Management" in perlapi, "MRO" in perlapi, "Multicall
+Functions" in perlapi, "Numeric Functions" in perlapi, "Optrees" in perlapi,
+"Pack and Unpack" in perlapi, "Pad Data Structures" in perlapi,
+"Password and Group access" in perlapi, "Paths to system commands" in perlapi,
+"Prototype information" in perlapi, "REGEXP Functions" in perlapi,
+"Reports and Formats" in perlapi, "Signals" in perlapi, "Site
+configuration" in perlapi, "Sockets configuration values" in perlapi, "Source
+Filters" in perlapi, "Stack Manipulation Macros" in perlapi, "String Handling" in perlapi,
+"SV Flags" in perlapi, "SV Handling" in perlapi, "Tainting" in perlapi,
+"Time" in perlapi, "Typedef names" in perlapi, "Unicode Support" in perlapi,
+"Utility Functions" in perlapi, "Versioning" in perlapi, "Warning and
+Dieing" in perlapi, "XS" in perlapi, "Undocumented elements" in perlapi
+.IP "AV Handling" 4
+.IX Item "AV Handling"
+\&\f(CW\*(C`AV\*(C'\fR, \f(CW\*(C`AvALLOC\*(C'\fR, \f(CW\*(C`AvARRAY\*(C'\fR , \f(CW\*(C`av_clear\*(C'\fR ,
+\&\f(CW\*(C`av_count\*(C'\fR , \f(CW\*(C`av_create_and_push\*(C'\fR ,
+\&\f(CW\*(C`av_create_and_unshift_one\*(C'\fR , \f(CW\*(C`av_delete\*(C'\fR
+, \f(CW\*(C`av_exists\*(C'\fR , \f(CW\*(C`av_extend\*(C'\fR ,
+\&\f(CW\*(C`av_fetch\*(C'\fR , \f(CW\*(C`AvFILL\*(C'\fR , \f(CW\*(C`av_fill\*(C'\fR ,
+\&\f(CW\*(C`av_len\*(C'\fR , \f(CW\*(C`av_make\*(C'\fR , \f(CW\*(C`av_pop\*(C'\fR , \f(CW\*(C`av_push\*(C'\fR
+, \f(CW\*(C`av_push_simple\*(C'\fR , \f(CW\*(C`av_shift\*(C'\fR ,
+\&\f(CW\*(C`av_store\*(C'\fR , \f(CW\*(C`av_tindex\*(C'\fR, \f(CW\*(C`av_top_index\*(C'\fR
+, \f(CW\*(C`av_undef\*(C'\fR , \f(CW\*(C`av_unshift\*(C'\fR
+, \f(CW\*(C`get_av\*(C'\fR , \f(CW\*(C`newAV\*(C'\fR, \f(CW\*(C`newAV_alloc_x\*(C'\fR,
+\&\f(CW\*(C`newAV_alloc_xz\*(C'\fR , \f(CW\*(C`newAV\*(C'\fR form,
+\&\f(CW\*(C`newAV_alloc_x\*(C'\fR form, \f(CW\*(C`newAV_alloc_xz\*(C'\fR form, \f(CW\*(C`newAVav\*(C'\fR ,
+\&\f(CW\*(C`newAVhv\*(C'\fR , \f(CW\*(C`Nullav\*(C'\fR
+.IX Xref "AvARRAY av_clear av_count av_create_and_push av_create_and_unshift_one av_delete av_exists av_extend av_fetch AvFILL av_fill av_len av_make av_pop av_push av_push_simple av_shift av_store av_tindex av_top_index av_undef av_unshift get_av newAV newAV_alloc_x newAV_alloc_xz newAVav newAVhv Nullav"
+.IP "Callback Functions" 4
+.IX Xref "G_METHOD G_METHOD_NAMED G_RETHROW SAVEf_KEEPOLDELEM SAVEf_SETMAGI C"
+.IX Item "Callback Functions"
+\&\f(CW\*(C`call_argv\*(C'\fR , \f(CW\*(C`call_method\*(C'\fR , \f(CW\*(C`call_pv\*(C'\fR
+, \f(CW\*(C`call_sv\*(C'\fR , \f(CW\*(C`DESTRUCTORFUNC_NOCONTEXT_t\*(C'\fR,
+\&\f(CW\*(C`DESTRUCTORFUNC_t\*(C'\fR, \f(CW\*(C`ENTER\*(C'\fR , \f(CW\*(C`ENTER_with_name\*(C'\fR
+, \f(CW\*(C`eval_pv\*(C'\fR , \f(CW\*(C`eval_sv\*(C'\fR ,
+\&\f(CW\*(C`FREETMPS\*(C'\fR , \f(CW\*(C`G_DISCARD\*(C'\fR, \f(CW\*(C`G_EVAL\*(C'\fR, \f(CW\*(C`GIMME\*(C'\fR ,
+\&\f(CW\*(C`GIMME_V\*(C'\fR , \f(CW\*(C`G_KEEPERR\*(C'\fR, \f(CW\*(C`G_LIST\*(C'\fR, \f(CW\*(C`G_NOARGS\*(C'\fR, \f(CW\*(C`G_SCALAR\*(C'\fR,
+\&\f(CW\*(C`G_VOID\*(C'\fR, \f(CW\*(C`is_lvalue_sub\*(C'\fR , \f(CW\*(C`LEAVE\*(C'\fR ,
+\&\f(CW\*(C`LEAVE_with_name\*(C'\fR , \f(CW\*(C`MORTALDESTRUCTOR_SV\*(C'\fR,
+\&\f(CW\*(C`mortal_destructor_sv\*(C'\fR , \f(CW\*(C`MORTALDESTRUCTOR_X\*(C'\fR,
+\&\f(CW\*(C`PL_errgv\*(C'\fR, \f(CW\*(C`save_aelem\*(C'\fR, \f(CW\*(C`save_aelem_flags\*(C'\fR
+, \f(CW\*(C`save_aptr\*(C'\fR, \f(CW\*(C`save_ary\*(C'\fR, \f(CW\*(C`SAVEBOOL\*(C'\fR,
+\&\f(CW\*(C`SAVEDELETE\*(C'\fR, \f(CW\*(C`SAVEDESTRUCTOR\*(C'\fR, \f(CW\*(C`SAVEDESTRUCTOR_X\*(C'\fR, \f(CW\*(C`SAVEFREEOP\*(C'\fR,
+\&\f(CW\*(C`SAVEFREEPV\*(C'\fR, \f(CW\*(C`SAVEFREERCPV\*(C'\fR, \f(CW\*(C`SAVEFREESV\*(C'\fR, \f(CW\*(C`SAVEGENERICSV\*(C'\fR,
+\&\f(CW\*(C`save_hash\*(C'\fR, \f(CW\*(C`save_helem\*(C'\fR, \f(CW\*(C`save_helem_flags\*(C'\fR
+, \f(CW\*(C`save_hptr\*(C'\fR, \f(CW\*(C`SAVEINT\*(C'\fR, \f(CW\*(C`save_item\*(C'\fR,
+\&\f(CW\*(C`SAVEIV\*(C'\fR, \f(CW\*(C`SAVEI8\*(C'\fR, \f(CW\*(C`SAVEI16\*(C'\fR, \f(CW\*(C`SAVEI32\*(C'\fR, \f(CW\*(C`SAVELONG\*(C'\fR,
+\&\f(CW\*(C`SAVEMORTALIZESV\*(C'\fR, \f(CW\*(C`SAVEPPTR\*(C'\fR, \f(CW\*(C`SAVERCPV\*(C'\fR, \f(CW\*(C`save_scalar\*(C'\fR, \f(CW\*(C`SAVESPTR\*(C'\fR,
+\&\f(CW\*(C`SAVESTACK_POS\*(C'\fR, \f(CW\*(C`SAVESTRLEN\*(C'\fR, \f(CW\*(C`save_svref\*(C'\fR, \f(CW\*(C`SAVETMPS\*(C'\fR
+.IX Xref "call_argv call_method call_pv call_sv ENTER ENTER_with_name eval_pv eval_sv FREETMPS GIMME GIMME_V is_lvalue_sub LEAVE LEAVE_with_name mortal_destructor_sv save_aelem save_aelem_flags save_helem save_helem_flags SAVETMPS"
+.IP Casting 4
+.IX Item "Casting"
+\&\f(CW\*(C`Atof\*(C'\fR , \f(CW\*(C`cBOOL\*(C'\fR , \f(CW\*(C`INT2PTR\*(C'\fR, \f(CW\*(C`I_V\*(C'\fR , \f(CW\*(C`I_32\*(C'\fR
+, \f(CW\*(C`PTR2IV\*(C'\fR, \f(CW\*(C`PTR2nat\*(C'\fR, \f(CW\*(C`PTR2NV\*(C'\fR, \f(CW\*(C`PTR2ul\*(C'\fR, \f(CW\*(C`PTR2UV\*(C'\fR, \f(CW\*(C`PTRV\*(C'\fR,
+\&\f(CW\*(C`U_V\*(C'\fR , \f(CW\*(C`U_32\*(C'\fR
+.IX Xref "Atof cBOOL I_V I_32 U_V U_32"
+.IP "Character case changing" 4
+.IX Item "Character case changing"
+\&\f(CW\*(C`toFOLD\*(C'\fR, \f(CW\*(C`toFOLD_A\*(C'\fR, \f(CW\*(C`toFOLD_utf8\*(C'\fR, \f(CW\*(C`toFOLD_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`toFOLD_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`toLOWER\*(C'\fR, \f(CW\*(C`toLOWER_A\*(C'\fR, \f(CW\*(C`toLOWER_LATIN1\*(C'\fR, \f(CW\*(C`toLOWER_LC\*(C'\fR, \f(CW\*(C`toLOWER_L1\*(C'\fR,
+\&\f(CW\*(C`toLOWER_utf8\*(C'\fR, \f(CW\*(C`toLOWER_utf8_safe\*(C'\fR, \f(CW\*(C`toLOWER_uvchr\*(C'\fR
+, \f(CW\*(C`toTITLE\*(C'\fR, \f(CW\*(C`toTITLE_A\*(C'\fR,
+\&\f(CW\*(C`toTITLE_utf8\*(C'\fR, \f(CW\*(C`toTITLE_utf8_safe\*(C'\fR, \f(CW\*(C`toTITLE_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`toUPPER\*(C'\fR, \f(CW\*(C`toUPPER_A\*(C'\fR, \f(CW\*(C`toUPPER_utf8\*(C'\fR, \f(CW\*(C`toUPPER_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`toUPPER_uvchr\*(C'\fR
+.IX Xref "toFOLD toFOLD_A toFOLD_utf8 toFOLD_utf8_safe toFOLD_uvchr toLOWER toLOWER_A toLOWER_LATIN1 toLOWER_LC toLOWER_L1 toLOWER_ utf8 toLOWER_utf8_safe toLOWER_uvchr toTITLE toTITLE_A toTITLE_utf8 toTITLE_utf8_safe toTITLE_uvchr toUPPER toUPPER_A toUPPER_utf8 toUPPER_utf8_safe toUPPER_uvchr"
+.IP "Character classification" 4
+.IX Item "Character classification"
+\&\f(CW\*(C`isALNUM\*(C'\fR, \f(CW\*(C`isALNUM_A\*(C'\fR, \f(CW\*(C`isALNUM_LC\*(C'\fR, \f(CW\*(C`isALNUM_LC_uvchr\*(C'\fR
+, \f(CW\*(C`isALNUMC\*(C'\fR,
+\&\f(CW\*(C`isALNUMC_A\*(C'\fR, \f(CW\*(C`isALNUMC_LC\*(C'\fR, \f(CW\*(C`isALNUMC_LC_uvchr\*(C'\fR, \f(CW\*(C`isALNUMC_L1\*(C'\fR
+,
+\&\f(CW\*(C`isALPHA\*(C'\fR, \f(CW\*(C`isALPHA_A\*(C'\fR, \f(CW\*(C`isALPHA_LC\*(C'\fR, \f(CW\*(C`isALPHA_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isALPHA_LC_uvchr\*(C'\fR, \f(CW\*(C`isALPHA_L1\*(C'\fR, \f(CW\*(C`isALPHA_utf8\*(C'\fR, \f(CW\*(C`isALPHA_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isALPHA_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isALPHANUMERIC\*(C'\fR, \f(CW\*(C`isALPHANUMERIC_A\*(C'\fR, \f(CW\*(C`isALPHANUMERIC_LC\*(C'\fR,
+\&\f(CW\*(C`isALPHANUMERIC_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isALPHANUMERIC_LC_uvchr\*(C'\fR,
+\&\f(CW\*(C`isALPHANUMERIC_L1\*(C'\fR, \f(CW\*(C`isALPHANUMERIC_utf8\*(C'\fR, \f(CW\*(C`isALPHANUMERIC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isALPHANUMERIC_uvchr\*(C'\fR
+, \f(CW\*(C`isASCII\*(C'\fR,
+\&\f(CW\*(C`isASCII_A\*(C'\fR, \f(CW\*(C`isASCII_LC\*(C'\fR, \f(CW\*(C`isASCII_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isASCII_LC_uvchr\*(C'\fR,
+\&\f(CW\*(C`isASCII_L1\*(C'\fR, \f(CW\*(C`isASCII_utf8\*(C'\fR, \f(CW\*(C`isASCII_utf8_safe\*(C'\fR, \f(CW\*(C`isASCII_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isBLANK\*(C'\fR, \f(CW\*(C`isBLANK_A\*(C'\fR, \f(CW\*(C`isBLANK_LC\*(C'\fR, \f(CW\*(C`isBLANK_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isBLANK_LC_uvchr\*(C'\fR, \f(CW\*(C`isBLANK_L1\*(C'\fR, \f(CW\*(C`isBLANK_utf8\*(C'\fR, \f(CW\*(C`isBLANK_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isBLANK_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isCNTRL\*(C'\fR, \f(CW\*(C`isCNTRL_A\*(C'\fR, \f(CW\*(C`isCNTRL_LC\*(C'\fR, \f(CW\*(C`isCNTRL_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isCNTRL_LC_uvchr\*(C'\fR, \f(CW\*(C`isCNTRL_L1\*(C'\fR, \f(CW\*(C`isCNTRL_utf8\*(C'\fR, \f(CW\*(C`isCNTRL_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isCNTRL_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isDIGIT\*(C'\fR, \f(CW\*(C`isDIGIT_A\*(C'\fR, \f(CW\*(C`isDIGIT_LC\*(C'\fR, \f(CW\*(C`isDIGIT_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_LC_uvchr\*(C'\fR, \f(CW\*(C`isDIGIT_L1\*(C'\fR, \f(CW\*(C`isDIGIT_utf8\*(C'\fR, \f(CW\*(C`isDIGIT_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isGRAPH\*(C'\fR, \f(CW\*(C`isGRAPH_A\*(C'\fR, \f(CW\*(C`isGRAPH_LC\*(C'\fR, \f(CW\*(C`isGRAPH_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isGRAPH_LC_uvchr\*(C'\fR, \f(CW\*(C`isGRAPH_L1\*(C'\fR, \f(CW\*(C`isGRAPH_utf8\*(C'\fR, \f(CW\*(C`isGRAPH_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isGRAPH_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isIDCONT\*(C'\fR, \f(CW\*(C`isIDCONT_A\*(C'\fR, \f(CW\*(C`isIDCONT_LC\*(C'\fR, \f(CW\*(C`isIDCONT_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isIDCONT_LC_uvchr\*(C'\fR, \f(CW\*(C`isIDCONT_L1\*(C'\fR, \f(CW\*(C`isIDCONT_utf8\*(C'\fR,
+\&\f(CW\*(C`isIDCONT_utf8_safe\*(C'\fR, \f(CW\*(C`isIDCONT_uvchr\*(C'\fR
+
+, \f(CW\*(C`isIDFIRST\*(C'\fR, \f(CW\*(C`isIDFIRST_A\*(C'\fR, \f(CW\*(C`isIDFIRST_LC\*(C'\fR, \f(CW\*(C`isIDFIRST_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isIDFIRST_LC_uvchr\*(C'\fR, \f(CW\*(C`isIDFIRST_L1\*(C'\fR, \f(CW\*(C`isIDFIRST_utf8\*(C'\fR,
+\&\f(CW\*(C`isIDFIRST_utf8_safe\*(C'\fR, \f(CW\*(C`isIDFIRST_uvchr\*(C'\fR
+, \f(CW\*(C`isLOWER\*(C'\fR, \f(CW\*(C`isLOWER_A\*(C'\fR, \f(CW\*(C`isLOWER_LC\*(C'\fR,
+\&\f(CW\*(C`isLOWER_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isLOWER_LC_uvchr\*(C'\fR, \f(CW\*(C`isLOWER_L1\*(C'\fR,
+\&\f(CW\*(C`isLOWER_utf8\*(C'\fR, \f(CW\*(C`isLOWER_utf8_safe\*(C'\fR, \f(CW\*(C`isLOWER_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isOCTAL\*(C'\fR, \f(CW\*(C`isOCTAL_A\*(C'\fR, \f(CW\*(C`isOCTAL_L1\*(C'\fR
+, \f(CW\*(C`isPRINT\*(C'\fR, \f(CW\*(C`isPRINT_A\*(C'\fR,
+\&\f(CW\*(C`isPRINT_LC\*(C'\fR, \f(CW\*(C`isPRINT_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isPRINT_LC_uvchr\*(C'\fR, \f(CW\*(C`isPRINT_L1\*(C'\fR,
+\&\f(CW\*(C`isPRINT_utf8\*(C'\fR, \f(CW\*(C`isPRINT_utf8_safe\*(C'\fR, \f(CW\*(C`isPRINT_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isPSXSPC\*(C'\fR, \f(CW\*(C`isPSXSPC_A\*(C'\fR, \f(CW\*(C`isPSXSPC_LC\*(C'\fR, \f(CW\*(C`isPSXSPC_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isPSXSPC_LC_uvchr\*(C'\fR, \f(CW\*(C`isPSXSPC_L1\*(C'\fR, \f(CW\*(C`isPSXSPC_utf8\*(C'\fR,
+\&\f(CW\*(C`isPSXSPC_utf8_safe\*(C'\fR, \f(CW\*(C`isPSXSPC_uvchr\*(C'\fR
+
+, \f(CW\*(C`isPUNCT\*(C'\fR, \f(CW\*(C`isPUNCT_A\*(C'\fR, \f(CW\*(C`isPUNCT_LC\*(C'\fR, \f(CW\*(C`isPUNCT_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isPUNCT_LC_uvchr\*(C'\fR, \f(CW\*(C`isPUNCT_L1\*(C'\fR, \f(CW\*(C`isPUNCT_utf8\*(C'\fR, \f(CW\*(C`isPUNCT_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isPUNCT_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isSPACE\*(C'\fR, \f(CW\*(C`isSPACE_A\*(C'\fR, \f(CW\*(C`isSPACE_LC\*(C'\fR, \f(CW\*(C`isSPACE_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isSPACE_LC_uvchr\*(C'\fR, \f(CW\*(C`isSPACE_L1\*(C'\fR, \f(CW\*(C`isSPACE_utf8\*(C'\fR, \f(CW\*(C`isSPACE_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isSPACE_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isUPPER\*(C'\fR, \f(CW\*(C`isUPPER_A\*(C'\fR, \f(CW\*(C`isUPPER_LC\*(C'\fR, \f(CW\*(C`isUPPER_LC_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isUPPER_LC_uvchr\*(C'\fR, \f(CW\*(C`isUPPER_L1\*(C'\fR, \f(CW\*(C`isUPPER_utf8\*(C'\fR, \f(CW\*(C`isUPPER_utf8_safe\*(C'\fR,
+\&\f(CW\*(C`isUPPER_uvchr\*(C'\fR
+,
+\&\f(CW\*(C`isWORDCHAR\*(C'\fR, \f(CW\*(C`isWORDCHAR_A\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC\*(C'\fR,
+\&\f(CW\*(C`isWORDCHAR_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_uvchr\*(C'\fR, \f(CW\*(C`isWORDCHAR_L1\*(C'\fR,
+\&\f(CW\*(C`isWORDCHAR_utf8\*(C'\fR, \f(CW\*(C`isWORDCHAR_utf8_safe\*(C'\fR, \f(CW\*(C`isWORDCHAR_uvchr\*(C'\fR
+X
+<isWORDCHAR_uvchr>, \f(CW\*(C`isXDIGIT\*(C'\fR, \f(CW\*(C`isXDIGIT_A\*(C'\fR, \f(CW\*(C`isXDIGIT_LC\*(C'\fR,
+\&\f(CW\*(C`isXDIGIT_LC_utf8_safe\*(C'\fR, \f(CW\*(C`isXDIGIT_LC_uvchr\*(C'\fR, \f(CW\*(C`isXDIGIT_L1\*(C'\fR,
+\&\f(CW\*(C`isXDIGIT_utf8\*(C'\fR, \f(CW\*(C`isXDIGIT_utf8_safe\*(C'\fR, \f(CW\*(C`isXDIGIT_uvchr\*(C'\fR
+.IX Xref "isALNUM isALNUM_A isALNUM_LC isALNUM_LC_uvchr isALNUMC isALNUMC_A isALNUMC_LC isALNUMC_LC_uvchr isALNUMC_L1 isALPHA isALPHA_A isALPHA_LC isALPHA_LC_utf8_safe isALPHA_LC_uvch r isALPHA_L1 isALPHA_utf8 isALPHA_utf8_safe isALPHA_uvchr isALPHANUMERIC isALPHANUMERIC_A isALPHANUMERIC_LC isALPHANUMERIC_LC _utf8_safe isALPHANUMERIC_LC_uvchr isALPHANUMERIC_L1 isALPHANUMERIC_u tf8 isALPHANUMERIC_utf8_safe isALPHANUMERIC_uvchr isASCII isASCII_A isASCII_LC isASCII_LC_utf8_safe isASCII_LC_uvch r isASCII_L1 isASCII_utf8 isASCII_utf8_safe isASCII_uvchr isBLANK isBLANK_A isBLANK_LC isBLANK_LC_utf8_safe isBLANK_LC_uvch r isBLANK_L1 isBLANK_utf8 isBLANK_utf8_safe isBLANK_uvchr isCNTRL isCNTRL_A isCNTRL_LC isCNTRL_LC_utf8_safe isCNTRL_LC_uvch r isCNTRL_L1 isCNTRL_utf8 isCNTRL_utf8_safe isCNTRL_uvchr isDIGIT isDIGIT_A isDIGIT_LC isDIGIT_LC_utf8_safe isDIGIT_LC_uvch r isDIGIT_L1 isDIGIT_utf8 isDIGIT_utf8_safe isDIGIT_uvchr isGRAPH isGRAPH_A isGRAPH_LC isGRAPH_LC_utf8_safe isGRAPH_LC_uvch r isGRAPH_L1 isGRAPH_utf8 isGRAPH_utf8_safe isGRAPH_uvchr isIDCONT isIDCONT_A isIDCONT_LC isIDCONT_LC_utf8_safe isIDCONT_LC _uvchr isIDCONT_L1 isIDCONT_utf8 isIDCONT_utf8_safe isIDCONT_uvchr isIDFIRST isIDFIRST_A isIDFIRST_LC isIDFIRST_LC_utf8_safe isIDFIR ST_LC_uvchr isIDFIRST_L1 isIDFIRST_utf8 isIDFIRST_utf8_safe isIDFIR ST_uvchr isLOWER isLOWER_A isLOWER_LC isLOWER_LC_utf8_safe isLOWER_LC_uvch r isLOWER_L1 isLOWER_utf8 isLOWER_utf8_safe isLOWER_uvchr isOCTAL isOCTAL_A isOCTAL_L1 isPRINT isPRINT_A isPRINT_LC isPRINT_LC_utf8_safe isPRINT_LC_uvch r isPRINT_L1 isPRINT_utf8 isPRINT_utf8_safe isPRINT_uvchr isPSXSPC isPSXSPC_A isPSXSPC_LC isPSXSPC_LC_utf8_safe isPSXSPC_LC _uvchr isPSXSPC_L1 isPSXSPC_utf8 isPSXSPC_utf8_safe isPSXSPC_uvchr isPUNCT isPUNCT_A isPUNCT_LC isPUNCT_LC_utf8_safe isPUNCT_LC_uvch r isPUNCT_L1 isPUNCT_utf8 isPUNCT_utf8_safe isPUNCT_uvchr isSPACE isSPACE_A isSPACE_LC isSPACE_LC_utf8_safe isSPACE_LC_uvch r isSPACE_L1 isSPACE_utf8 isSPACE_utf8_safe isSPACE_uvchr isUPPER isUPPER_A isUPPER_LC isUPPER_LC_utf8_safe isUPPER_LC_uvch r isUPPER_L1 isUPPER_utf8 isUPPER_utf8_safe isUPPER_uvchr isWORDCHAR isWORDCHAR_A isWORDCHAR_LC isWORDCHAR_LC_utf8_safe isW ORDCHAR_LC_uvchr isWORDCHAR_L1 isWORDCHAR_utf8 isWORDCHAR_utf8_safe isXDIGIT isXDIGIT_A isXDIGIT_LC isXDIGIT_LC_utf8_safe isXDIGIT_LC _uvchr isXDIGIT_L1 isXDIGIT_utf8 isXDIGIT_utf8_safe isXDIGIT_uvchr"
+.IP "Compiler and Preprocessor information" 4
+.IX Item "Compiler and Preprocessor information"
+\&\f(CW\*(C`CPPLAST\*(C'\fR , \f(CW\*(C`CPPMINUS\*(C'\fR , \f(CW\*(C`CPPRUN\*(C'\fR ,
+\&\f(CW\*(C`CPPSTDIN\*(C'\fR , \f(CW\*(C`HASATTRIBUTE_ALWAYS_INLINE\*(C'\fR
+, \f(CW\*(C`HASATTRIBUTE_DEPRECATED\*(C'\fR
+, \f(CW\*(C`HASATTRIBUTE_FORMAT\*(C'\fR ,
+\&\f(CW\*(C`HASATTRIBUTE_NONNULL\*(C'\fR , \f(CW\*(C`HASATTRIBUTE_NORETURN\*(C'\fR
+, \f(CW\*(C`HASATTRIBUTE_PURE\*(C'\fR ,
+\&\f(CW\*(C`HASATTRIBUTE_UNUSED\*(C'\fR , \f(CW\*(C`HASATTRIBUTE_VISIBILITY\*(C'\fR
+, \f(CW\*(C`HASATTRIBUTE_WARN_UNUSED_RESULT\*(C'\fR
+, \f(CW\*(C`HAS_BUILTIN_ADD_OVERFLOW\*(C'\fR
+, \f(CW\*(C`HAS_BUILTIN_CHOOSE_EXPR\*(C'\fR
+, \f(CW\*(C`HAS_BUILTIN_EXPECT\*(C'\fR ,
+\&\f(CW\*(C`HAS_BUILTIN_MUL_OVERFLOW\*(C'\fR ,
+\&\f(CW\*(C`HAS_BUILTIN_SUB_OVERFLOW\*(C'\fR ,
+\&\f(CW\*(C`HAS_C99_VARIADIC_MACROS\*(C'\fR , \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR
+, \f(CW\*(C`MEM_ALIGNBYTES\*(C'\fR ,
+\&\f(CW\*(C`PERL_STATIC_INLINE\*(C'\fR , \f(CW\*(C`PERL_THREAD_LOCAL\*(C'\fR
+, \f(CW\*(C`U32_ALIGNMENT_REQUIRED\*(C'\fR
+.IX Xref "CPPLAST CPPMINUS CPPRUN CPPSTDIN HASATTRIBUTE_ALWAYS_INLINE HASATTRIBUTE_DEPRECATED HASATTRIBUTE_FORMAT HASATTRIBUTE_NONNULL HASATTRIBUTE_NORETURN HASATTRIBUTE_PURE HASATTRIBUTE_UNUSED HASATTRIBUTE_VISIBILITY HASATTRIBUTE_WARN_UNUSED_RESULT HAS_BUILTIN_ADD_OVERFLOW HAS_BUILTIN_CHOOSE_EXPR HAS_BUILTIN_EXPECT HAS_BUILTIN_MUL_OVERFLOW HAS_BUILTIN_SUB_OVERFLOW HAS_C99_VARIADIC_MACROS HAS_STATIC_INLINE MEM_ALIGNBYTES PERL_STATIC_INLINE PERL_THREAD_LOCAL U32_ALIGNMENT_REQUIRED"
+.IP "Compiler directives" 4
+.IX Item "Compiler directives"
+\&\f(CW\*(C`_\|_ASSERT_\*(C'\fR , \f(CW\*(C`ASSUME\*(C'\fR , \f(CW\*(C`dNOOP\*(C'\fR ,
+\&\f(CW\*(C`END_EXTERN_C\*(C'\fR , \f(CW\*(C`EXTERN_C\*(C'\fR , \f(CW\*(C`LIKELY\*(C'\fR
+, \f(CW\*(C`NOOP\*(C'\fR , \f(CW\*(C`PERL_UNUSED_ARG\*(C'\fR ,
+\&\f(CW\*(C`PERL_UNUSED_CONTEXT\*(C'\fR , \f(CW\*(C`PERL_UNUSED_DECL\*(C'\fR
+, \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR ,
+\&\f(CW\*(C`PERL_UNUSED_VAR\*(C'\fR , \f(CW\*(C`START_EXTERN_C\*(C'\fR ,
+\&\f(CW\*(C`STATIC\*(C'\fR, \f(CW\*(C`STMT_END\*(C'\fR, \f(CW\*(C`STMT_START\*(C'\fR , \f(CW\*(C`UNLIKELY\*(C'\fR
+.IX Xref "__ASSERT_ ASSUME dNOOP END_EXTERN_C EXTERN_C LIKELY NOOP PERL_UNUSED_ARG PERL_UNUSED_CONTEXT PERL_UNUSED_DECL PERL_UNUSED_RESULT PERL_UNUSED_VAR START_EXTERN_C STMT_END STMT_START UNLIKELY"
+.IP "Compile-time scope hooks" 4
+.IX Item "Compile-time scope hooks"
+\&\f(CW\*(C`BhkDISABLE\*(C'\fR , \f(CW\*(C`BhkENABLE\*(C'\fR , \f(CW\*(C`BhkENTRY_set\*(C'\fR
+, \f(CW\*(C`blockhook_register\*(C'\fR
+.IX Xref "BhkDISABLE BhkENABLE BhkENTRY_set blockhook_register"
+.IP Concurrency 4
+.IX Item "Concurrency"
+\&\f(CW\*(C`aTHX\*(C'\fR, \f(CW\*(C`aTHX_\*(C'\fR, \f(CW\*(C`CPERLscope\*(C'\fR , \f(CW\*(C`dTHR\*(C'\fR, \f(CW\*(C`dTHX\*(C'\fR, \f(CW\*(C`dTHXa\*(C'\fR
+, \f(CW\*(C`dTHXoa\*(C'\fR , \f(CW\*(C`dVAR\*(C'\fR ,
+\&\f(CW\*(C`GETENV_PRESERVES_OTHER_THREAD\*(C'\fR ,
+\&\f(CW\*(C`HAS_PTHREAD_ATFORK\*(C'\fR , \f(CW\*(C`HAS_PTHREAD_ATTR_SETSCOPE\*(C'\fR
+, \f(CW\*(C`HAS_PTHREAD_YIELD\*(C'\fR ,
+\&\f(CW\*(C`HAS_SCHED_YIELD\*(C'\fR , \f(CW\*(C`I_MACH_CTHREADS\*(C'\fR
+, \f(CW\*(C`I_PTHREAD\*(C'\fR , \f(CW\*(C`MULTIPLICITY\*(C'\fR,
+\&\f(CW\*(C`OLD_PTHREAD_CREATE_JOINABLE\*(C'\fR ,
+\&\f(CW\*(C`OLD_PTHREADS_API\*(C'\fR , \f(CW\*(C`PERL_IMPLICIT_CONTEXT\*(C'\fR,
+\&\f(CW\*(C`PERL_NO_GET_CONTEXT\*(C'\fR, \f(CW\*(C`pTHX\*(C'\fR, \f(CW\*(C`pTHX_\*(C'\fR, \f(CW\*(C`SCHED_YIELD\*(C'\fR
+.IX Xref "CPERLscope dTHXa dTHXoa dVAR GETENV_PRESERVES_OTHER_THREAD HAS_PTHREAD_ATFORK HAS_PTHREAD_ATTR_SETSCOPE HAS_PTHREAD_YIELD HAS_SCHED_YIELD I_MACH_CTHREADS I_PTHREAD OLD_PTHREAD_CREATE_JOINABLE OLD_PTHREADS_API SCHED_YIELD"
+.IP "COPs and Hint Hashes" 4
+.IX Xref "COPHH_KEY_UTF8"
+.IX Item "COPs and Hint Hashes"
+\&\f(CW\*(C`cop_fetch_label\*(C'\fR , \f(CW\*(C`CopFILE\*(C'\fR , \f(CW\*(C`CopFILEAV\*(C'\fR
+, \f(CW\*(C`CopFILEAVn\*(C'\fR , \f(CW\*(C`CopFILE_copy\*(C'\fR ,
+\&\f(CW\*(C`CopFILE_free\*(C'\fR , \f(CW\*(C`CopFILEGV\*(C'\fR ,
+\&\f(CW\*(C`CopFILEGV_set\*(C'\fR , \f(CW\*(C`CopFILE_LEN\*(C'\fR ,
+\&\f(CW\*(C`CopFILE_set\*(C'\fR , \f(CW\*(C`CopFILE_setn\*(C'\fR ,
+\&\f(CW\*(C`CopFILESV\*(C'\fR , \f(CW\*(C`cophh_copy\*(C'\fR , \f(CW\*(C`cophh_delete_pv\*(C'\fR,
+\&\f(CW\*(C`cophh_delete_pvn\*(C'\fR, \f(CW\*(C`cophh_delete_pvs\*(C'\fR, \f(CW\*(C`cophh_delete_sv\*(C'\fR
+,
+\&\f(CW\*(C`cophh_exists_pvn\*(C'\fR , \f(CW\*(C`cophh_fetch_pv\*(C'\fR,
+\&\f(CW\*(C`cophh_fetch_pvn\*(C'\fR, \f(CW\*(C`cophh_fetch_pvs\*(C'\fR, \f(CW\*(C`cophh_fetch_sv\*(C'\fR
+,
+\&\f(CW\*(C`cophh_free\*(C'\fR , \f(CW\*(C`cophh_2hv\*(C'\fR , \f(CW\*(C`cophh_new_empty\*(C'\fR
+, \f(CW\*(C`cophh_store_pv\*(C'\fR, \f(CW\*(C`cophh_store_pvn\*(C'\fR,
+\&\f(CW\*(C`cophh_store_pvs\*(C'\fR, \f(CW\*(C`cophh_store_sv\*(C'\fR
+,
+\&\f(CW\*(C`cop_hints_exists_pv\*(C'\fR, \f(CW\*(C`cop_hints_exists_pvn\*(C'\fR, \f(CW\*(C`cop_hints_exists_pvs\*(C'\fR,
+\&\f(CW\*(C`cop_hints_exists_sv\*(C'\fR
+, \f(CW\*(C`cop_hints_fetch_pv\*(C'\fR, \f(CW\*(C`cop_hints_fetch_pvn\*(C'\fR,
+\&\f(CW\*(C`cop_hints_fetch_pvs\*(C'\fR, \f(CW\*(C`cop_hints_fetch_sv\*(C'\fR
+, \f(CW\*(C`cop_hints_2hv\*(C'\fR , \f(CW\*(C`CopLABEL\*(C'\fR,
+\&\f(CW\*(C`CopLABEL_len\*(C'\fR, \f(CW\*(C`CopLABEL_len_flags\*(C'\fR
+, \f(CW\*(C`CopLINE\*(C'\fR ,
+\&\f(CW\*(C`CopSTASH\*(C'\fR , \f(CW\*(C`CopSTASH_eq\*(C'\fR , \f(CW\*(C`CopSTASHPV\*(C'\fR
+, \f(CW\*(C`CopSTASHPV_set\*(C'\fR , \f(CW\*(C`CopSTASH_set\*(C'\fR
+, \f(CW\*(C`cop_store_label\*(C'\fR , \f(CW\*(C`PERL_SI\*(C'\fR
+, \f(CW\*(C`PL_curcop\*(C'\fR , \f(CW\*(C`RCPV_LEN\*(C'\fR ,
+\&\f(CW\*(C`RCPV_REFCNT_dec\*(C'\fR , \f(CW\*(C`RCPV_REFCNT_inc\*(C'\fR
+, \f(CW\*(C`RCPV_REFCOUNT\*(C'\fR , \f(CW\*(C`RCPVx\*(C'\fR
+.IX Xref "cop_fetch_label CopFILE CopFILEAV CopFILEAVn CopFILE_copy CopFILE_free CopFILEGV CopFILEGV_set CopFILE_LEN CopFILE_set CopFILE_setn CopFILESV cophh_copy cophh_delete_pv cophh_delete_pvn cophh_delete_pvs cophh_delete_sv cophh_exists_pvn cophh_fetch_pv cophh_fetch_pvn cophh_fetch_pvs cophh_fetch_sv cophh_free cophh_2hv cophh_new_empty cophh_store_pv cophh_store_pvn cophh_store_pvs cophh_store_sv cop_hints_exists_pv cop_hints_exists_pvn cop_hints_exists_pvs cop_h ints_exists_sv cop_hints_fetch_pv cop_hints_fetch_pvn cop_hints_fetch_pvs cop_hint s_fetch_sv cop_hints_2hv CopLABEL CopLABEL_len CopLABEL_len_flags CopLINE CopSTASH CopSTASH_eq CopSTASHPV CopSTASHPV_set CopSTASH_set cop_store_label PERL_SI PL_curcop RCPV_LEN RCPV_REFCNT_dec RCPV_REFCNT_inc RCPV_REFCOUNT RCPVx"
+.IP "Custom Operators" 4
+.IX Item "Custom Operators"
+\&\f(CW\*(C`custom_op_register\*(C'\fR , \f(CW\*(C`Perl_custom_op_xop\*(C'\fR
+, \f(CW\*(C`XopDISABLE\*(C'\fR , \f(CW\*(C`XopENABLE\*(C'\fR
+, \f(CW\*(C`XopENTRY\*(C'\fR , \f(CW\*(C`XopENTRYCUSTOM\*(C'\fR ,
+\&\f(CW\*(C`XopENTRY_set\*(C'\fR , \f(CW\*(C`XopFLAGS\*(C'\fR
+.IX Xref "custom_op_register Perl_custom_op_xop XopDISABLE XopENABLE XopENTRY XopENTRYCUSTOM XopENTRY_set XopFLAGS"
+.IP "CV Handling" 4
+.IX Xref "CV GV_ADD"
+.IX Item "CV Handling"
+\&\f(CW\*(C`caller_cx\*(C'\fR , \f(CW\*(C`CvDEPTH\*(C'\fR , \f(CW\*(C`CvGV\*(C'\fR ,
+\&\f(CW\*(C`CvSTASH\*(C'\fR , \f(CW\*(C`find_runcv\*(C'\fR , \f(CW\*(C`get_cv\*(C'\fR,
+\&\f(CW\*(C`get_cvn_flags\*(C'\fR, \f(CW\*(C`get_cvs\*(C'\fR , \f(CW\*(C`Nullcv\*(C'\fR
+.IX Xref "caller_cx CvDEPTH CvGV CvSTASH find_runcv get_cv get_cvn_flags get_cvs Nullcv"
+.IP Debugging 4
+.IX Item "Debugging"
+\&\f(CW\*(C`av_dump\*(C'\fR , \f(CW\*(C`deb\*(C'\fR, \f(CW\*(C`deb_nocontext\*(C'\fR ,
+\&\f(CW\*(C`debstack\*(C'\fR , \f(CW\*(C`dump_all\*(C'\fR , \f(CW\*(C`dump_c_backtrace\*(C'\fR
+, \f(CW\*(C`dump_eval\*(C'\fR, \f(CW\*(C`dump_form\*(C'\fR ,
+\&\f(CW\*(C`dump_packsubs\*(C'\fR , \f(CW\*(C`dump_sub\*(C'\fR, \f(CW\*(C`get_c_backtrace_dump\*(C'\fR
+, \f(CW\*(C`gv_dump\*(C'\fR , \f(CW\*(C`HAS_BACKTRACE\*(C'\fR
+, \f(CW\*(C`hv_dump\*(C'\fR , \f(CW\*(C`magic_dump\*(C'\fR ,
+\&\f(CW\*(C`op_class\*(C'\fR , \f(CW\*(C`op_dump\*(C'\fR , \f(CW\*(C`PL_op\*(C'\fR, \f(CW\*(C`PL_runops\*(C'\fR,
+\&\f(CW\*(C`PL_sv_serial\*(C'\fR, \f(CW\*(C`pmop_dump\*(C'\fR , \f(CW\*(C`sv_dump\*(C'\fR ,
+\&\f(CW\*(C`sv_dump_depth\*(C'\fR , \f(CW\*(C`vdeb\*(C'\fR
+.IX Xref "av_dump deb deb_nocontext debstack dump_all dump_c_backtrace dump_form dump_packsubs get_c_backtrace_dump gv_dump HAS_BACKTRACE hv_dump magic_dump op_class op_dump pmop_dump sv_dump sv_dump_depth vdeb"
+.IP "Display functions" 4
+.IX Xref "PERL_PV_ESCAPE_ALL PERL_PV_ESCAPE_FIRSTCHAR PERL_PV_ESCAPE_NOBACKSLAS H PERL_PV_ESCAPE_NOCLEAR PERL_PV_ESCAPE_NONASCII PERL_PV_ESCAPE_NON_W C PERL_PV_ESCAPE_QUOTE PERL_PV_ESCAPE_RE PERL_PV_ESCAPE_UNI PERL_PV _ESCAPE_UNI_DETECT PERL_PV_PRETTY_ELLIPSES PERL_PV_PRETTY_LTGT PERL_P V_PRETTY_QUOTE"
+.IX Item "Display functions"
+\&\f(CW\*(C`form\*(C'\fR, \f(CW\*(C`form_nocontext\*(C'\fR , \f(CW\*(C`mess\*(C'\fR,
+\&\f(CW\*(C`mess_nocontext\*(C'\fR , \f(CW\*(C`mess_sv\*(C'\fR ,
+\&\f(CW\*(C`pv_display\*(C'\fR , \f(CW\*(C`pv_escape\*(C'\fR , \f(CW\*(C`pv_pretty\*(C'\fR
+, \f(CW\*(C`vform\*(C'\fR , \f(CW\*(C`vmess\*(C'\fR
+.IX Xref "form form_nocontext mess mess_nocontext mess_sv pv_display pv_escape pv_pretty vform vmess"
+.IP "Embedding, Threads, and Interpreter Cloning" 4
+.IX Xref "CV_NAME_NOTQUAL PADNAMEf_OUTER PERL_EXIT_ABORT PERL_EXIT_DESTRUCT_E ND PERL_EXIT_EXPECTED PERL_EXIT_WARN PERL_LOADMOD_DENY PERL_LOADMOD _IMPORT_OPS PERL_LOADMOD_NOIMPORT"
+.IX Item "Embedding, Threads, and Interpreter Cloning"
+\&\f(CW\*(C`call_atexit\*(C'\fR , \f(CW\*(C`cv_clone\*(C'\fR , \f(CW\*(C`cv_name\*(C'\fR
+, \f(CW\*(C`cv_undef\*(C'\fR , \f(CW\*(C`find_rundefsv\*(C'\fR ,
+\&\f(CW\*(C`get_op_descs\*(C'\fR , \f(CW\*(C`get_op_names\*(C'\fR ,
+\&\f(CW\*(C`HAS_SKIP_LOCALE_INIT\*(C'\fR, \f(CW\*(C`intro_my\*(C'\fR , \f(CW\*(C`load_module\*(C'\fR,
+\&\f(CW\*(C`load_module_nocontext\*(C'\fR , \f(CW\*(C`my_exit\*(C'\fR
+, \f(CW\*(C`my_failure_exit\*(C'\fR , \f(CW\*(C`my_strlcat\*(C'\fR
+, \f(CW\*(C`my_strlcpy\*(C'\fR , \f(CW\*(C`newPADNAMELIST\*(C'\fR
+, \f(CW\*(C`newPADNAMEouter\*(C'\fR , \f(CW\*(C`newPADNAMEpvn\*(C'\fR
+, \f(CW\*(C`nothreadhook\*(C'\fR , \f(CW\*(C`pad_add_anon\*(C'\fR
+, \f(CW\*(C`pad_add_name_pv\*(C'\fR , \f(CW\*(C`pad_add_name_pvn\*(C'\fR
+, \f(CW\*(C`pad_add_name_sv\*(C'\fR , \f(CW\*(C`pad_alloc\*(C'\fR
+, \f(CW\*(C`pad_findmy_pv\*(C'\fR , \f(CW\*(C`pad_findmy_pvn\*(C'\fR
+, \f(CW\*(C`pad_findmy_sv\*(C'\fR , \f(CW\*(C`padnamelist_fetch\*(C'\fR
+, \f(CW\*(C`padnamelist_store\*(C'\fR ,
+\&\f(CW\*(C`pad_tidy\*(C'\fR , \f(CW\*(C`perl_alloc\*(C'\fR , \f(CW\*(C`PERL_ASYNC_CHECK\*(C'\fR,
+\&\f(CW\*(C`perl_clone\*(C'\fR , \f(CW\*(C`perl_construct\*(C'\fR ,
+\&\f(CW\*(C`perl_destruct\*(C'\fR , \f(CW\*(C`perl_free\*(C'\fR ,
+\&\f(CW\*(C`PERL_GET_CONTEXT\*(C'\fR, \f(CW\*(C`PerlInterpreter\*(C'\fR, \f(CW\*(C`perl_parse\*(C'\fR ,
+\&\f(CW\*(C`perl_run\*(C'\fR , \f(CW\*(C`PERL_SET_CONTEXT\*(C'\fR, \f(CW\*(C`PERL_SYS_INIT\*(C'\fR,
+\&\f(CW\*(C`PERL_SYS_INIT3\*(C'\fR , \f(CW\*(C`PERL_SYS_TERM\*(C'\fR
+, \f(CW\*(C`PL_exit_flags\*(C'\fR ,
+\&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR, \f(CW\*(C`PERL_EXIT_ABORT\*(C'\fR, \f(CW\*(C`PERL_EXIT_WARN\*(C'\fR,
+\&\f(CW\*(C`PERL_EXIT_EXPECTED\*(C'\fR, \f(CW\*(C`PL_origalen\*(C'\fR, \f(CW\*(C`PL_perl_destruct_level\*(C'\fR
+, 0 \- none, 1 \- full, 2 or greater \- full with
+checks, \f(CW\*(C`ptr_table_fetch\*(C'\fR , \f(CW\*(C`ptr_table_free\*(C'\fR
+, \f(CW\*(C`ptr_table_new\*(C'\fR , \f(CW\*(C`ptr_table_split\*(C'\fR
+, \f(CW\*(C`ptr_table_store\*(C'\fR , \f(CW\*(C`require_pv\*(C'\fR
+, \f(CW\*(C`vload_module\*(C'\fR
+.IX Xref "call_atexit cv_clone cv_name cv_undef find_rundefsv get_op_descs get_op_names intro_my load_module load_module_nocontext my_exit my_failure_exit my_strlcat my_strlcpy newPADNAMELIST newPADNAMEouter newPADNAMEpvn nothreadhook pad_add_anon pad_add_name_pv pad_add_name_pvn pad_add_name_sv pad_alloc pad_findmy_pv pad_findmy_pvn pad_findmy_sv padnamelist_fetch padnamelist_store pad_tidy perl_alloc perl_clone perl_construct perl_destruct perl_free perl_parse perl_run PERL_SYS_INIT PERL_SYS_INIT3 PERL_SYS_TERM PL_exit_flags PL_perl_destruct_level ptr_table_fetch ptr_table_free ptr_table_new ptr_table_split ptr_table_store require_pv vload_module"
+.IP Errno 4
+.IX Item "Errno"
+\&\f(CW\*(C`sv_string_from_errnum\*(C'\fR
+.IX Xref "sv_string_from_errnum"
+.IP "Exception Handling (simple) Macros" 4
+.IX Item "Exception Handling (simple) Macros"
+\&\f(CW\*(C`dXCPT\*(C'\fR , \f(CW\*(C`JMPENV_JUMP\*(C'\fR, \f(CW\*(C`JMPENV_PUSH\*(C'\fR, \f(CW\*(C`PL_restartop\*(C'\fR,
+\&\f(CW\*(C`XCPT_CATCH\*(C'\fR , \f(CW\*(C`XCPT_RETHROW\*(C'\fR ,
+\&\f(CW\*(C`XCPT_TRY_END\*(C'\fR , \f(CW\*(C`XCPT_TRY_START\*(C'\fR
+.IX Xref "dXCPT XCPT_CATCH XCPT_RETHROW XCPT_TRY_END XCPT_TRY_START"
+.IP "Filesystem configuration values" 4
+.IX Item "Filesystem configuration values"
+\&\f(CW\*(C`DIRNAMLEN\*(C'\fR , \f(CW\*(C`DOSUID\*(C'\fR , \f(CW\*(C`EOF_NONBLOCK\*(C'\fR
+, \f(CW\*(C`FCNTL_CAN_LOCK\*(C'\fR , \f(CW\*(C`FFLUSH_ALL\*(C'\fR
+, \f(CW\*(C`FFLUSH_NULL\*(C'\fR , \f(CW\*(C`FILE_base\*(C'\fR ,
+\&\f(CW\*(C`FILE_bufsiz\*(C'\fR , \f(CW\*(C`FILE_cnt\*(C'\fR , \f(CW\*(C`FILE_ptr\*(C'\fR
+, \f(CW\*(C`FLEXFILENAMES\*(C'\fR , \f(CW\*(C`HAS_DIR_DD_FD\*(C'\fR
+, \f(CW\*(C`HAS_DUP2\*(C'\fR , \f(CW\*(C`HAS_DUP3\*(C'\fR ,
+\&\f(CW\*(C`HAS_FAST_STDIO\*(C'\fR , \f(CW\*(C`HAS_FCHDIR\*(C'\fR ,
+\&\f(CW\*(C`HAS_FCNTL\*(C'\fR , \f(CW\*(C`HAS_FDCLOSE\*(C'\fR , \f(CW\*(C`HAS_FPATHCONF\*(C'\fR
+, \f(CW\*(C`HAS_FPOS64_T\*(C'\fR , \f(CW\*(C`HAS_FSTATFS\*(C'\fR
+, \f(CW\*(C`HAS_FSTATVFS\*(C'\fR , \f(CW\*(C`HAS_GETFSSTAT\*(C'\fR
+, \f(CW\*(C`HAS_GETMNT\*(C'\fR , \f(CW\*(C`HAS_GETMNTENT\*(C'\fR
+, \f(CW\*(C`HAS_HASMNTOPT\*(C'\fR , \f(CW\*(C`HAS_LSEEK_PROTO\*(C'\fR
+, \f(CW\*(C`HAS_MKDIR\*(C'\fR , \f(CW\*(C`HAS_OFF64_T\*(C'\fR
+, \f(CW\*(C`HAS_OPENAT\*(C'\fR , \f(CW\*(C`HAS_OPEN3\*(C'\fR ,
+\&\f(CW\*(C`HAS_POLL\*(C'\fR , \f(CW\*(C`HAS_READDIR\*(C'\fR , \f(CW\*(C`HAS_READDIR64_R\*(C'\fR
+, \f(CW\*(C`HAS_REWINDDIR\*(C'\fR , \f(CW\*(C`HAS_RMDIR\*(C'\fR
+, \f(CW\*(C`HAS_SEEKDIR\*(C'\fR , \f(CW\*(C`HAS_SELECT\*(C'\fR ,
+\&\f(CW\*(C`HAS_SETVBUF\*(C'\fR , \f(CW\*(C`HAS_STDIO_STREAM_ARRAY\*(C'\fR
+, \f(CW\*(C`HAS_STRUCT_FS_DATA\*(C'\fR ,
+\&\f(CW\*(C`HAS_STRUCT_STATFS\*(C'\fR , \f(CW\*(C`HAS_STRUCT_STATFS_F_FLAGS\*(C'\fR
+, \f(CW\*(C`HAS_TELLDIR\*(C'\fR , \f(CW\*(C`HAS_USTAT\*(C'\fR
+, \f(CW\*(C`I_FCNTL\*(C'\fR , \f(CW\*(C`I_SYS_DIR\*(C'\fR ,
+\&\f(CW\*(C`I_SYS_FILE\*(C'\fR , \f(CW\*(C`I_SYS_NDIR\*(C'\fR , \f(CW\*(C`I_SYS_STATFS\*(C'\fR
+, \f(CW\*(C`LSEEKSIZE\*(C'\fR , \f(CW\*(C`RD_NODATA\*(C'\fR ,
+\&\f(CW\*(C`READDIR64_R_PROTO\*(C'\fR , \f(CW\*(C`STDCHAR\*(C'\fR ,
+\&\f(CW\*(C`STDIO_CNT_LVALUE\*(C'\fR , \f(CW\*(C`STDIO_PTR_LVAL_NOCHANGE_CNT\*(C'\fR
+, \f(CW\*(C`STDIO_PTR_LVAL_SETS_CNT\*(C'\fR
+, \f(CW\*(C`STDIO_PTR_LVALUE\*(C'\fR ,
+\&\f(CW\*(C`STDIO_STREAM_ARRAY\*(C'\fR , \f(CW\*(C`ST_INO_SIGN\*(C'\fR ,
+\&\f(CW\*(C`ST_INO_SIZE\*(C'\fR , \f(CW\*(C`VAL_EAGAIN\*(C'\fR ,
+\&\f(CW\*(C`VAL_O_NONBLOCK\*(C'\fR , \f(CW\*(C`VOID_CLOSEDIR\*(C'\fR
+.IX Xref "DIRNAMLEN DOSUID EOF_NONBLOCK FCNTL_CAN_LOCK FFLUSH_ALL FFLUSH_NULL FILE_base FILE_bufsiz FILE_cnt FILE_ptr FLEXFILENAMES HAS_DIR_DD_FD HAS_DUP2 HAS_DUP3 HAS_FAST_STDIO HAS_FCHDIR HAS_FCNTL HAS_FDCLOSE HAS_FPATHCONF HAS_FPOS64_T HAS_FSTATFS HAS_FSTATVFS HAS_GETFSSTAT HAS_GETMNT HAS_GETMNTENT HAS_HASMNTOPT HAS_LSEEK_PROTO HAS_MKDIR HAS_OFF64_T HAS_OPENAT HAS_OPEN3 HAS_POLL HAS_READDIR HAS_READDIR64_R HAS_REWINDDIR HAS_RMDIR HAS_SEEKDIR HAS_SELECT HAS_SETVBUF HAS_STDIO_STREAM_ARRAY HAS_STRUCT_FS_DATA HAS_STRUCT_STATFS HAS_STRUCT_STATFS_F_FLAGS HAS_TELLDIR HAS_USTAT I_FCNTL I_SYS_DIR I_SYS_FILE I_SYS_NDIR I_SYS_STATFS LSEEKSIZE RD_NODATA READDIR64_R_PROTO STDCHAR STDIO_CNT_LVALUE STDIO_PTR_LVAL_NOCHANGE_CNT STDIO_PTR_LVAL_SETS_CNT STDIO_PTR_LVALUE STDIO_STREAM_ARRAY ST_INO_SIGN ST_INO_SIZE VAL_EAGAIN VAL_O_NONBLOCK VOID_CLOSEDIR"
+.IP "Floating point" 4
+.IX Item "Floating point"
+\&\f(CW\*(C`CASTFLAGS\*(C'\fR , \f(CW\*(C`CASTNEGFLOAT\*(C'\fR ,
+\&\f(CW\*(C`DOUBLE_HAS_INF\*(C'\fR , \f(CW\*(C`DOUBLE_HAS_NAN\*(C'\fR ,
+\&\f(CW\*(C`DOUBLE_HAS_NEGATIVE_ZERO\*(C'\fR ,
+\&\f(CW\*(C`DOUBLE_HAS_SUBNORMALS\*(C'\fR , \f(CW\*(C`DOUBLEINFBYTES\*(C'\fR
+, \f(CW\*(C`DOUBLEKIND\*(C'\fR , \f(CW\*(C`DOUBLEMANTBITS\*(C'\fR
+, \f(CW\*(C`DOUBLENANBYTES\*(C'\fR , \f(CW\*(C`DOUBLESIZE\*(C'\fR
+, \f(CW\*(C`DOUBLE_STYLE_CRAY\*(C'\fR ,
+\&\f(CW\*(C`DOUBLE_STYLE_IBM\*(C'\fR , \f(CW\*(C`DOUBLE_STYLE_IEEE\*(C'\fR
+, \f(CW\*(C`DOUBLE_STYLE_VAX\*(C'\fR , \f(CW\*(C`HAS_ATOLF\*(C'\fR
+, \f(CW\*(C`HAS_CLASS\*(C'\fR , \f(CW\*(C`HAS_FINITE\*(C'\fR ,
+\&\f(CW\*(C`HAS_FINITEL\*(C'\fR , \f(CW\*(C`HAS_FPCLASS\*(C'\fR ,
+\&\f(CW\*(C`HAS_FP_CLASS\*(C'\fR , \f(CW\*(C`HAS_FPCLASSIFY\*(C'\fR ,
+\&\f(CW\*(C`HAS_FP_CLASSIFY\*(C'\fR , \f(CW\*(C`HAS_FPCLASSL\*(C'\fR ,
+\&\f(CW\*(C`HAS_FP_CLASSL\*(C'\fR , \f(CW\*(C`HAS_FPGETROUND\*(C'\fR ,
+\&\f(CW\*(C`HAS_FREXPL\*(C'\fR , \f(CW\*(C`HAS_ILOGB\*(C'\fR , \f(CW\*(C`HAS_ISFINITE\*(C'\fR
+, \f(CW\*(C`HAS_ISFINITEL\*(C'\fR , \f(CW\*(C`HAS_ISINF\*(C'\fR
+, \f(CW\*(C`HAS_ISINFL\*(C'\fR , \f(CW\*(C`HAS_ISNAN\*(C'\fR ,
+\&\f(CW\*(C`HAS_ISNANL\*(C'\fR , \f(CW\*(C`HAS_ISNORMAL\*(C'\fR , \f(CW\*(C`HAS_J0L\*(C'\fR
+, \f(CW\*(C`HAS_J0\*(C'\fR , \f(CW\*(C`HAS_LDBL_DIG\*(C'\fR ,
+\&\f(CW\*(C`HAS_LDEXPL\*(C'\fR , \f(CW\*(C`HAS_LLRINT\*(C'\fR , \f(CW\*(C`HAS_LLRINTL\*(C'\fR
+, \f(CW\*(C`HAS_LLROUNDL\*(C'\fR , \f(CW\*(C`HAS_LONG_DOUBLE\*(C'\fR
+, \f(CW\*(C`HAS_LRINT\*(C'\fR , \f(CW\*(C`HAS_LRINTL\*(C'\fR ,
+\&\f(CW\*(C`HAS_LROUNDL\*(C'\fR , \f(CW\*(C`HAS_MODFL\*(C'\fR , \f(CW\*(C`HAS_NAN\*(C'\fR
+, \f(CW\*(C`HAS_NEXTTOWARD\*(C'\fR , \f(CW\*(C`HAS_REMAINDER\*(C'\fR
+, \f(CW\*(C`HAS_SCALBN\*(C'\fR , \f(CW\*(C`HAS_SIGNBIT\*(C'\fR
+, \f(CW\*(C`HAS_SQRTL\*(C'\fR , \f(CW\*(C`HAS_STRTOD_L\*(C'\fR ,
+\&\f(CW\*(C`HAS_STRTOLD\*(C'\fR , \f(CW\*(C`HAS_STRTOLD_L\*(C'\fR ,
+\&\f(CW\*(C`HAS_TRUNC\*(C'\fR , \f(CW\*(C`HAS_UNORDERED\*(C'\fR , \f(CW\*(C`I_FENV\*(C'\fR
+, \f(CW\*(C`I_QUADMATH\*(C'\fR , \f(CW\*(C`LONGDBLINFBYTES\*(C'\fR
+, \f(CW\*(C`LONGDBLMANTBITS\*(C'\fR ,
+\&\f(CW\*(C`LONGDBLNANBYTES\*(C'\fR , \f(CW\*(C`LONG_DOUBLEKIND\*(C'\fR
+, \f(CW\*(C`LONG_DOUBLESIZE\*(C'\fR ,
+\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE\*(C'\fR ,
+\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\*(C'\fR
+, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_EXTENDED\*(C'\fR
+, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_STD\*(C'\fR
+, \f(CW\*(C`LONG_DOUBLE_STYLE_VAX\*(C'\fR
+, \f(CW\*(C`NV\*(C'\fR, \f(CW\*(C`NVMANTBITS\*(C'\fR ,
+\&\f(CW\*(C`NV_OVERFLOWS_INTEGERS_AT\*(C'\fR , \f(CW\*(C`NV_PRESERVES_UV\*(C'\fR
+, \f(CW\*(C`NV_PRESERVES_UV_BITS\*(C'\fR ,
+\&\f(CW\*(C`NVSIZE\*(C'\fR , \f(CW\*(C`NVTYPE\*(C'\fR , \f(CW\*(C`NV_ZERO_IS_ALLBITS_ZERO\*(C'\fR
+.IX Xref "CASTFLAGS CASTNEGFLOAT DOUBLE_HAS_INF DOUBLE_HAS_NAN DOUBLE_HAS_NEGATIVE_ZERO DOUBLE_HAS_SUBNORMALS DOUBLEINFBYTES DOUBLEKIND DOUBLEMANTBITS DOUBLENANBYTES DOUBLESIZE DOUBLE_STYLE_CRAY DOUBLE_STYLE_IBM DOUBLE_STYLE_IEEE DOUBLE_STYLE_VAX HAS_ATOLF HAS_CLASS HAS_FINITE HAS_FINITEL HAS_FPCLASS HAS_FP_CLASS HAS_FPCLASSIFY HAS_FP_CLASSIFY HAS_FPCLASSL HAS_FP_CLASSL HAS_FPGETROUND HAS_FREXPL HAS_ILOGB HAS_ISFINITE HAS_ISFINITEL HAS_ISINF HAS_ISINFL HAS_ISNAN HAS_ISNANL HAS_ISNORMAL HAS_J0L HAS_J0 HAS_LDBL_DIG HAS_LDEXPL HAS_LLRINT HAS_LLRINTL HAS_LLROUNDL HAS_LONG_DOUBLE HAS_LRINT HAS_LRINTL HAS_LROUNDL HAS_MODFL HAS_NAN HAS_NEXTTOWARD HAS_REMAINDER HAS_SCALBN HAS_SIGNBIT HAS_SQRTL HAS_STRTOD_L HAS_STRTOLD HAS_STRTOLD_L HAS_TRUNC HAS_UNORDERED I_FENV I_QUADMATH LONGDBLINFBYTES LONGDBLMANTBITS LONGDBLNANBYTES LONG_DOUBLEKIND LONG_DOUBLESIZE LONG_DOUBLE_STYLE_IEEE LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE LONG_DOUBLE_STYLE_IEEE_EXTENDED LONG_DOUBLE_STYLE_IEEE_STD LONG_DOUBLE_STYLE_VAX NVMANTBITS NV_OVERFLOWS_INTEGERS_AT NV_PRESERVES_UV NV_PRESERVES_UV_BITS NVSIZE NVTYPE NV_ZERO_IS_ALLBITS_ZERO"
+.IP "General Configuration" 4
+.IX Xref "PERL_GCC_BRACE_GROUPS_FORBIDDEN"
+.IX Item "General Configuration"
+\&\f(CW\*(C`ASCIIish\*(C'\fR , \f(CW\*(C`BYTEORDER\*(C'\fR , \f(CW\*(C`CHARBITS\*(C'\fR
+, \f(CW\*(C`DB_VERSION_MAJOR_CFG\*(C'\fR ,
+\&\f(CW\*(C`DB_VERSION_MINOR_CFG\*(C'\fR , \f(CW\*(C`DB_VERSION_PATCH_CFG\*(C'\fR
+, \f(CW\*(C`DEFAULT_INC_EXCLUDES_DOT\*(C'\fR
+, \f(CW\*(C`DLSYM_NEEDS_UNDERSCORE\*(C'\fR
+, \f(CW\*(C`EBCDIC\*(C'\fR , \f(CW\*(C`HAS_CSH\*(C'\fR ,
+\&\f(CW\*(C`HAS_GETHOSTNAME\*(C'\fR , \f(CW\*(C`HAS_GNULIBC\*(C'\fR ,
+\&\f(CW\*(C`HAS_LGAMMA\*(C'\fR , \f(CW\*(C`HAS_LGAMMA_R\*(C'\fR ,
+\&\f(CW\*(C`HAS_NON_INT_BITFIELDS\*(C'\fR , \f(CW\*(C`HAS_PRCTL_SET_NAME\*(C'\fR
+, \f(CW\*(C`HAS_PROCSELFEXE\*(C'\fR ,
+\&\f(CW\*(C`HAS_PSEUDOFORK\*(C'\fR , \f(CW\*(C`HAS_REGCOMP\*(C'\fR ,
+\&\f(CW\*(C`HAS_SETPGID\*(C'\fR , \f(CW\*(C`HAS_SIGSETJMP\*(C'\fR ,
+\&\f(CW\*(C`HAS_STRUCT_CMSGHDR\*(C'\fR , \f(CW\*(C`HAS_STRUCT_MSGHDR\*(C'\fR
+, \f(CW\*(C`HAS_TGAMMA\*(C'\fR , \f(CW\*(C`HAS_UNAME\*(C'\fR
+, \f(CW\*(C`HAS_UNION_SEMUN\*(C'\fR , \f(CW\*(C`I_DIRENT\*(C'\fR
+, \f(CW\*(C`I_POLL\*(C'\fR , \f(CW\*(C`I_SYS_RESOURCE\*(C'\fR ,
+\&\f(CW\*(C`LIBM_LIB_VERSION\*(C'\fR , \f(CW\*(C`NEED_VA_COPY\*(C'\fR, \f(CW\*(C`OSNAME\*(C'\fR
+, \f(CW\*(C`OSVERS\*(C'\fR , \f(CW\*(C`PERL_USE_GCC_BRACE_GROUPS\*(C'\fR
+, \f(CW\*(C`PHOSTNAME\*(C'\fR ,
+\&\f(CW\*(C`PROCSELFEXE_PATH\*(C'\fR , \f(CW\*(C`PTRSIZE\*(C'\fR , \f(CW\*(C`RANDBITS\*(C'\fR
+, \f(CW\*(C`SELECT_MIN_BITS\*(C'\fR ,
+\&\f(CW\*(C`SETUID_SCRIPTS_ARE_SECURE_NOW\*(C'\fR ,
+\&\f(CW\*(C`ST_DEV_SIGN\*(C'\fR , \f(CW\*(C`ST_DEV_SIZE\*(C'\fR
+.IX Xref "ASCIIish BYTEORDER CHARBITS DB_VERSION_MAJOR_CFG DB_VERSION_MINOR_CFG DB_VERSION_PATCH_CFG DEFAULT_INC_EXCLUDES_DOT DLSYM_NEEDS_UNDERSCORE EBCDIC HAS_CSH HAS_GETHOSTNAME HAS_GNULIBC HAS_LGAMMA HAS_LGAMMA_R HAS_NON_INT_BITFIELDS HAS_PRCTL_SET_NAME HAS_PROCSELFEXE HAS_PSEUDOFORK HAS_REGCOMP HAS_SETPGID HAS_SIGSETJMP HAS_STRUCT_CMSGHDR HAS_STRUCT_MSGHDR HAS_TGAMMA HAS_UNAME HAS_UNION_SEMUN I_DIRENT I_POLL I_SYS_RESOURCE LIBM_LIB_VERSION OSNAME OSVERS PERL_USE_GCC_BRACE_GROUPS PHOSTNAME PROCSELFEXE_PATH PTRSIZE RANDBITS SELECT_MIN_BITS SETUID_SCRIPTS_ARE_SECURE_NOW ST_DEV_SIGN ST_DEV_SIZE"
+.RS 4
+.ie n .IP "List of capability ""HAS_\fIfoo\fR"" symbols" 4
+.el .IP "List of capability \f(CWHAS_\fR\f(CIfoo\fR\f(CW\fR symbols" 4
+.IX Item "List of capability HAS_foo symbols"
+.PD 0
+.ie n .IP "List of ""#include"" needed symbols" 4
+.el .IP "List of \f(CW#include\fR needed symbols" 4
+.IX Item "List of #include needed symbols"
+.RE
+.RS 4
+.RE
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.PD
+\&\f(CW\*(C`PL_check\*(C'\fR , \f(CW\*(C`PL_infix_plugin\*(C'\fR ,
+\&\f(CW\*(C`PL_keyword_plugin\*(C'\fR , \f(CW\*(C`PL_phase\*(C'\fR
+.IX Xref "PL_check PL_infix_plugin PL_keyword_plugin PL_phase"
+.IP "GV Handling and Stashes" 4
+.IX Xref "GV GV_ADD GV_ADDMG GV_ADDMULTI GV_ADDWARN GV_NOADD_NOINIT GV_ NOEXPAND GV_NOINIT GV_NOTQUAL GV_NO_SVGMAGIC GV_SUPER SVf_UTF8"
+.IX Item "GV Handling and Stashes"
+\&\f(CW\*(C`amagic_call\*(C'\fR , \f(CW\*(C`AMGf_noleft\*(C'\fR, \f(CW\*(C`AMGf_noright\*(C'\fR,
+\&\f(CW\*(C`AMGf_unary\*(C'\fR, \f(CW\*(C`AMGf_assign\*(C'\fR, \f(CW\*(C`amagic_deref_call\*(C'\fR ,
+\&\f(CW\*(C`gv_add_by_type\*(C'\fR , \f(CW\*(C`Gv_AMupdate\*(C'\fR , 1 on
+success and there is some overload, 0 if there is no overload, \-1 if some
+error occurred and it couldn't croak (because \f(CW\*(C`destructing\*(C'\fR is true),
+\&\f(CW\*(C`gv_autoload_pv\*(C'\fR, \f(CW\*(C`gv_autoload_pvn\*(C'\fR, \f(CW\*(C`gv_autoload_sv\*(C'\fR
+, \f(CW\*(C`gv_autoload4\*(C'\fR
+, \f(CW\*(C`GvAV\*(C'\fR , \f(CW\*(C`gv_AVadd\*(C'\fR, \f(CW\*(C`gv_HVadd\*(C'\fR, \f(CW\*(C`gv_IOadd\*(C'\fR,
+\&\f(CW\*(C`gv_SVadd\*(C'\fR , \f(CW\*(C`gv_const_sv\*(C'\fR
+, \f(CW\*(C`GvCV\*(C'\fR , \f(CW\*(C`gv_efullname3\*(C'\fR, \f(CW\*(C`gv_efullname4\*(C'\fR,
+\&\f(CW\*(C`gv_fullname3\*(C'\fR, \f(CW\*(C`gv_fullname4\*(C'\fR
+,
+\&\f(CW\*(C`gv_fetchfile\*(C'\fR, \f(CW\*(C`gv_fetchfile_flags\*(C'\fR
+, \f(CW\*(C`gv_fetchmeth\*(C'\fR, \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR,
+\&\f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR, \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR
+,
+\&\f(CW\*(C`gv_fetchmeth_autoload\*(C'\fR , \f(CW\*(C`gv_fetchmethod\*(C'\fR
+, \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR ,
+\&\f(CW\*(C`gv_fetchmeth_pv_autoload\*(C'\fR ,
+\&\f(CW\*(C`gv_fetchmeth_pvn_autoload\*(C'\fR ,
+\&\f(CW\*(C`gv_fetchmeth_sv_autoload\*(C'\fR , \f(CW\*(C`gv_fetchpv\*(C'\fR,
+\&\f(CW\*(C`gv_fetchpvn\*(C'\fR, \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR, \f(CW\*(C`gv_fetchpvs\*(C'\fR, \f(CW\*(C`gv_fetchsv\*(C'\fR,
+\&\f(CW\*(C`gv_fetchsv_nomg\*(C'\fR
+X
+<gv_fetchsv_nomg>, \f(CW\*(C`GvHV\*(C'\fR , \f(CW\*(C`gv_init\*(C'\fR , \f(CW\*(C`gv_init_pv\*(C'\fR
+, \f(CW\*(C`gv_init_pvn\*(C'\fR , \f(CW\*(C`gv_init_sv\*(C'\fR ,
+\&\f(CW\*(C`gv_name_set\*(C'\fR , \f(CW\*(C`gv_stashpv\*(C'\fR , \f(CW\*(C`gv_stashpvn\*(C'\fR
+, \f(CW\*(C`gv_stashpvs\*(C'\fR , \f(CW\*(C`gv_stashsv\*(C'\fR ,
+\&\f(CW\*(C`GvSV\*(C'\fR , \f(CW\*(C`GvSVn\*(C'\fR , \f(CW\*(C`newGVgen\*(C'\fR, \f(CW\*(C`newGVgen_flags\*(C'\fR
+, \f(CW\*(C`PL_curstash\*(C'\fR , \f(CW\*(C`PL_defgv\*(C'\fR
+, \f(CW\*(C`PL_defoutgv\*(C'\fR , \f(CW\*(C`PL_defstash\*(C'\fR, \f(CW\*(C`save_gp\*(C'\fR
+, \f(CW\*(C`setdefout\*(C'\fR
+.IX Xref "amagic_call amagic_deref_call gv_add_by_type Gv_AMupdate gv_autoload_pv gv_autoload_pvn gv_autoload_sv gv_autoload4 GvAV gv_AVadd gv_HVadd gv_IOadd gv_SVadd gv_const_sv GvCV gv_efullname3 gv_efullname4 gv_fullname3 gv_fullname4 gv_fetchfile gv_fetchfile_flags gv_fetchmeth gv_fetchmeth_pv gv_fetchmeth_pvn gv_fetchmeth_sv gv_fetchmeth_autoload gv_fetchmethod gv_fetchmethod_autoload gv_fetchmeth_pv_autoload gv_fetchmeth_pvn_autoload gv_fetchmeth_sv_autoload gv_fetchpv gv_fetchpvn gv_fetchpvn_flags gv_fetchpvs gv_fetchsv GvHV gv_init gv_init_pv gv_init_pvn gv_init_sv gv_name_set gv_stashpv gv_stashpvn gv_stashpvs gv_stashsv GvSV GvSVn newGVgen newGVgen_flags PL_curstash PL_defgv PL_defoutgv save_gp setdefout"
+.IP "Hook manipulation" 4
+.IX Item "Hook manipulation"
+\&\f(CW\*(C`rcpv_copy\*(C'\fR , \f(CW\*(C`rcpv_free\*(C'\fR , \f(CW\*(C`rcpv_new\*(C'\fR
+, \f(CW\*(C`wrap_op_checker\*(C'\fR
+.IX Xref "rcpv_copy rcpv_free rcpv_new wrap_op_checker"
+.IP "HV Handling" 4
+.IX Xref "HV_ITERNEXT_WANTPLACEHOLDERS HV_NAME_SETALL HvNAMELEN_get"
+.IX Item "HV Handling"
+\&\f(CW\*(C`get_hv\*(C'\fR , \f(CW\*(C`HE\*(C'\fR, \f(CW\*(C`HEf_SVKEY\*(C'\fR , \f(CW\*(C`HeHASH\*(C'\fR ,
+\&\f(CW\*(C`HeKEY\*(C'\fR , \f(CW\*(C`HeKLEN\*(C'\fR , \f(CW\*(C`HePV\*(C'\fR , \f(CW\*(C`HeSVKEY\*(C'\fR
+, \f(CW\*(C`HeSVKEY_force\*(C'\fR , \f(CW\*(C`HeSVKEY_set\*(C'\fR
+, \f(CW\*(C`HeUTF8\*(C'\fR , \f(CW\*(C`HeVAL\*(C'\fR , \f(CW\*(C`HV\*(C'\fR, \f(CW\*(C`hv_assert\*(C'\fR
+, \f(CW\*(C`hv_bucket_ratio\*(C'\fR , \f(CW\*(C`hv_clear\*(C'\fR
+, \f(CW\*(C`hv_clear_placeholders\*(C'\fR ,
+\&\f(CW\*(C`hv_copy_hints_hv\*(C'\fR , \f(CW\*(C`hv_delete\*(C'\fR ,
+\&\f(CW\*(C`hv_delete_ent\*(C'\fR , \f(CW\*(C`HvENAME\*(C'\fR , \f(CW\*(C`HvENAMELEN\*(C'\fR
+, \f(CW\*(C`HvENAMEUTF8\*(C'\fR , \f(CW\*(C`hv_exists\*(C'\fR ,
+\&\f(CW\*(C`hv_exists_ent\*(C'\fR , \f(CW\*(C`hv_fetch\*(C'\fR , \f(CW\*(C`hv_fetch_ent\*(C'\fR
+, \f(CW\*(C`hv_fetchs\*(C'\fR , \f(CW\*(C`HvFILL\*(C'\fR ,
+\&\f(CW\*(C`HvHasAUX\*(C'\fR , \f(CW\*(C`hv_iterinit\*(C'\fR , \f(CW\*(C`hv_iterkey\*(C'\fR
+, \f(CW\*(C`hv_iterkeysv\*(C'\fR , \f(CW\*(C`hv_iternext\*(C'\fR
+, \f(CW\*(C`hv_iternext_flags\*(C'\fR , \f(CW\*(C`hv_iternextsv\*(C'\fR
+, \f(CW\*(C`hv_iterval\*(C'\fR , \f(CW\*(C`hv_ksplit\*(C'\fR ,
+\&\f(CW\*(C`hv_magic\*(C'\fR , \f(CW\*(C`HvNAME\*(C'\fR , \f(CW\*(C`HvNAMELEN\*(C'\fR ,
+\&\f(CW\*(C`hv_name_set\*(C'\fR, \f(CW\*(C`hv_name_sets\*(C'\fR ,
+\&\f(CW\*(C`HvNAMEUTF8\*(C'\fR , \f(CW\*(C`hv_scalar\*(C'\fR , \f(CW\*(C`hv_store\*(C'\fR,
+\&\f(CW\*(C`hv_stores\*(C'\fR , \f(CW\*(C`hv_store_ent\*(C'\fR ,
+\&\f(CW\*(C`hv_undef\*(C'\fR , \f(CW\*(C`newHV\*(C'\fR , \f(CW\*(C`newHVhv\*(C'\fR ,
+\&\f(CW\*(C`Nullhv\*(C'\fR , \f(CW\*(C`PERL_HASH\*(C'\fR, \f(CW\*(C`PL_modglobal\*(C'\fR
+.IX Xref "get_hv HEf_SVKEY HeHASH HeKEY HeKLEN HePV HeSVKEY HeSVKEY_force HeSVKEY_set HeUTF8 HeVAL hv_assert hv_bucket_ratio hv_clear hv_clear_placeholders hv_copy_hints_hv hv_delete hv_delete_ent HvENAME HvENAMELEN HvENAMEUTF8 hv_exists hv_exists_ent hv_fetch hv_fetch_ent hv_fetchs HvFILL HvHasAUX hv_iterinit hv_iterkey hv_iterkeysv hv_iternext hv_iternext_flags hv_iternextsv hv_iterval hv_ksplit hv_magic HvNAME HvNAMELEN hv_name_set hv_name_sets HvNAMEUTF8 hv_scalar hv_store hv_stores hv_store_ent hv_undef newHV newHVhv Nullhv PL_modglobal"
+.IP Input/Output 4
+.IX Item "Input/Output"
+\&\f(CW\*(C`do_close\*(C'\fR , \f(CW\*(C`IoDIRP\*(C'\fR, \f(CW\*(C`IOf_FLUSH\*(C'\fR, \f(CW\*(C`IoFLAGS\*(C'\fR,
+\&\f(CW\*(C`IOf_UNTAINT\*(C'\fR, \f(CW\*(C`IoIFP\*(C'\fR, \f(CW\*(C`IoOFP\*(C'\fR, \f(CW\*(C`IoTYPE\*(C'\fR, \f(CW\*(C`my_chsize\*(C'\fR ,
+\&\f(CW\*(C`my_dirfd\*(C'\fR , \f(CW\*(C`my_pclose\*(C'\fR , \f(CW\*(C`my_popen\*(C'\fR
+, \f(CW\*(C`newIO\*(C'\fR , \f(CW\*(C`PERL_FLUSHALL_FOR_CHILD\*(C'\fR
+, \f(CW\*(C`PerlIO_apply_layers\*(C'\fR, \f(CW\*(C`PerlIO_binmode\*(C'\fR,
+\&\f(CW\*(C`PerlIO_canset_cnt\*(C'\fR, \f(CW\*(C`PerlIO_clearerr\*(C'\fR, \f(CW\*(C`PerlIO_close\*(C'\fR, \f(CW\*(C`PerlIO_debug\*(C'\fR,
+\&\f(CW\*(C`PerlIO_eof\*(C'\fR, \f(CW\*(C`PerlIO_error\*(C'\fR, \f(CW\*(C`PerlIO_exportFILE\*(C'\fR, \f(CW\*(C`PerlIO_fast_gets\*(C'\fR,
+\&\f(CW\*(C`PerlIO_fdopen\*(C'\fR, \f(CW\*(C`PerlIO_fileno\*(C'\fR, \f(CW\*(C`PerlIO_fill\*(C'\fR, \f(CW\*(C`PerlIO_findFILE\*(C'\fR,
+\&\f(CW\*(C`PerlIO_flush\*(C'\fR, \f(CW\*(C`PerlIO_get_base\*(C'\fR, \f(CW\*(C`PerlIO_get_bufsiz\*(C'\fR,
+\&\f(CW\*(C`PerlIO_get_cnt\*(C'\fR, \f(CW\*(C`PerlIO_get_ptr\*(C'\fR, \f(CW\*(C`PerlIO_getc\*(C'\fR, \f(CW\*(C`PerlIO_getpos\*(C'\fR,
+\&\f(CW\*(C`PerlIO_has_base\*(C'\fR, \f(CW\*(C`PerlIO_has_cntptr\*(C'\fR, \f(CW\*(C`PerlIO_importFILE\*(C'\fR,
+\&\f(CW\*(C`PerlIO_open\*(C'\fR, \f(CW\*(C`PerlIO_printf\*(C'\fR, \f(CW\*(C`PerlIO_putc\*(C'\fR, \f(CW\*(C`PerlIO_puts\*(C'\fR,
+\&\f(CW\*(C`PerlIO_read\*(C'\fR, \f(CW\*(C`PerlIO_releaseFILE\*(C'\fR, \f(CW\*(C`PerlIO_reopen\*(C'\fR, \f(CW\*(C`PerlIO_rewind\*(C'\fR,
+\&\f(CW\*(C`PerlIO_seek\*(C'\fR, \f(CW\*(C`PerlIO_set_cnt\*(C'\fR, \f(CW\*(C`PerlIO_set_ptrcnt\*(C'\fR,
+\&\f(CW\*(C`PerlIO_setlinebuf\*(C'\fR, \f(CW\*(C`PerlIO_setpos\*(C'\fR, \f(CW\*(C`PerlIO_stderr\*(C'\fR, \f(CW\*(C`PerlIO_stdin\*(C'\fR,
+\&\f(CW\*(C`PerlIO_stdout\*(C'\fR, \f(CW\*(C`PerlIO_stdoutf\*(C'\fR, \f(CW\*(C`PerlIO_tell\*(C'\fR, \f(CW\*(C`PerlIO_ungetc\*(C'\fR,
+\&\f(CW\*(C`PerlIO_unread\*(C'\fR, \f(CW\*(C`PerlIO_vprintf\*(C'\fR, \f(CW\*(C`PerlIO_write\*(C'\fR, \f(CW\*(C`PERLIO_F_APPEND\*(C'\fR,
+\&\f(CW\*(C`PERLIO_F_CANREAD\*(C'\fR, \f(CW\*(C`PERLIO_F_CANWRITE\*(C'\fR, \f(CW\*(C`PERLIO_F_CRLF\*(C'\fR,
+\&\f(CW\*(C`PERLIO_F_EOF\*(C'\fR, \f(CW\*(C`PERLIO_F_ERROR\*(C'\fR, \f(CW\*(C`PERLIO_F_FASTGETS\*(C'\fR,
+\&\f(CW\*(C`PERLIO_F_LINEBUF\*(C'\fR, \f(CW\*(C`PERLIO_F_OPEN\*(C'\fR, \f(CW\*(C`PERLIO_F_RDBUF\*(C'\fR, \f(CW\*(C`PERLIO_F_TEMP\*(C'\fR,
+\&\f(CW\*(C`PERLIO_F_TRUNCATE\*(C'\fR, \f(CW\*(C`PERLIO_F_UNBUF\*(C'\fR, \f(CW\*(C`PERLIO_F_UTF8\*(C'\fR,
+\&\f(CW\*(C`PERLIO_F_WRBUF\*(C'\fR, \f(CW\*(C`PERLIO_FUNCS_CAST\*(C'\fR ,
+\&\f(CW\*(C`PERLIO_FUNCS_DECL\*(C'\fR , \f(CW\*(C`PERLIO_K_BUFFERED\*(C'\fR,
+\&\f(CW\*(C`PERLIO_K_CANCRLF\*(C'\fR, \f(CW\*(C`PERLIO_K_FASTGETS\*(C'\fR, \f(CW\*(C`PERLIO_K_MULTIARG\*(C'\fR,
+\&\f(CW\*(C`PERLIO_K_RAW\*(C'\fR, \f(CW\*(C`PERLIO_NOT_STDIO\*(C'\fR, \f(CW\*(C`PL_maxsysfd\*(C'\fR, \f(CW\*(C`repeatcpy\*(C'\fR
+, \f(CW\*(C`USE_STDIO\*(C'\fR
+.IX Xref "do_close my_chsize my_dirfd my_pclose my_popen newIO PERL_FLUSHALL_FOR_CHILD PERLIO_FUNCS_CAST PERLIO_FUNCS_DECL repeatcpy"
+.IP Integer 4
+.IX Item "Integer"
+\&\f(CW\*(C`CASTI32\*(C'\fR , \f(CW\*(C`HAS_INT64_T\*(C'\fR , \f(CW\*(C`HAS_LONG_LONG\*(C'\fR
+, \f(CW\*(C`HAS_QUAD\*(C'\fR , \f(CW\*(C`I32df\*(C'\fR , \f(CW\*(C`INT16_C\*(C'\fR,
+\&\f(CW\*(C`INT32_C\*(C'\fR, \f(CW\*(C`INT64_C\*(C'\fR , \f(CW\*(C`INTMAX_C\*(C'\fR
+, \f(CW\*(C`INTSIZE\*(C'\fR , \f(CW\*(C`I8SIZE\*(C'\fR , \f(CW\*(C`I16SIZE\*(C'\fR
+, \f(CW\*(C`I32SIZE\*(C'\fR , \f(CW\*(C`I64SIZE\*(C'\fR , \f(CW\*(C`I8TYPE\*(C'\fR
+, \f(CW\*(C`I16TYPE\*(C'\fR , \f(CW\*(C`I32TYPE\*(C'\fR , \f(CW\*(C`I64TYPE\*(C'\fR
+, \f(CW\*(C`IV\*(C'\fR, \f(CW\*(C`I8\*(C'\fR, \f(CW\*(C`I16\*(C'\fR, \f(CW\*(C`I32\*(C'\fR, \f(CW\*(C`I64\*(C'\fR, \f(CW\*(C`IV_MAX\*(C'\fR ,
+\&\f(CW\*(C`IV_MIN\*(C'\fR , \f(CW\*(C`IVSIZE\*(C'\fR , \f(CW\*(C`IVTYPE\*(C'\fR , \f(CW\*(C`line_t\*(C'\fR
+, \f(CW\*(C`LONGLONGSIZE\*(C'\fR , \f(CW\*(C`LONGSIZE\*(C'\fR ,
+\&\f(CW\*(C`memzero\*(C'\fR , \f(CW\*(C`PERL_INT_FAST8_T\*(C'\fR, \f(CW\*(C`PERL_INT_FAST16_T\*(C'\fR,
+\&\f(CW\*(C`PERL_UINT_FAST8_T\*(C'\fR, \f(CW\*(C`PERL_UINT_FAST16_T\*(C'\fR
+, \f(CW\*(C`PERL_INT_MAX\*(C'\fR, \f(CW\*(C`PERL_INT_MIN\*(C'\fR, \f(CW\*(C`PERL_LONG_MAX\*(C'\fR,
+\&\f(CW\*(C`PERL_LONG_MIN\*(C'\fR, \f(CW\*(C`PERL_QUAD_MAX\*(C'\fR, \f(CW\*(C`PERL_QUAD_MIN\*(C'\fR, \f(CW\*(C`PERL_SHORT_MAX\*(C'\fR,
+\&\f(CW\*(C`PERL_SHORT_MIN\*(C'\fR, \f(CW\*(C`PERL_UCHAR_MAX\*(C'\fR, \f(CW\*(C`PERL_UCHAR_MIN\*(C'\fR, \f(CW\*(C`PERL_UINT_MAX\*(C'\fR,
+\&\f(CW\*(C`PERL_UINT_MIN\*(C'\fR, \f(CW\*(C`PERL_ULONG_MAX\*(C'\fR, \f(CW\*(C`PERL_ULONG_MIN\*(C'\fR, \f(CW\*(C`PERL_UQUAD_MAX\*(C'\fR,
+\&\f(CW\*(C`PERL_UQUAD_MIN\*(C'\fR, \f(CW\*(C`PERL_USHORT_MAX\*(C'\fR, \f(CW\*(C`PERL_USHORT_MIN\*(C'\fR
+,
+\&\f(CW\*(C`SHORTSIZE\*(C'\fR , \f(CW\*(C`UINT16_C\*(C'\fR, \f(CW\*(C`UINT32_C\*(C'\fR, \f(CW\*(C`UINT64_C\*(C'\fR
+, \f(CW\*(C`UINTMAX_C\*(C'\fR , \f(CW\*(C`U32of\*(C'\fR
+, \f(CW\*(C`U8SIZE\*(C'\fR , \f(CW\*(C`U16SIZE\*(C'\fR , \f(CW\*(C`U32SIZE\*(C'\fR
+, \f(CW\*(C`U64SIZE\*(C'\fR , \f(CW\*(C`U8TYPE\*(C'\fR , \f(CW\*(C`U16TYPE\*(C'\fR
+, \f(CW\*(C`U32TYPE\*(C'\fR , \f(CW\*(C`U64TYPE\*(C'\fR , \f(CW\*(C`U32uf\*(C'\fR
+, \f(CW\*(C`UV\*(C'\fR, \f(CW\*(C`U8\*(C'\fR, \f(CW\*(C`U16\*(C'\fR, \f(CW\*(C`U32\*(C'\fR, \f(CW\*(C`U64\*(C'\fR, \f(CW\*(C`UV_MAX\*(C'\fR ,
+\&\f(CW\*(C`UV_MIN\*(C'\fR , \f(CW\*(C`UVSIZE\*(C'\fR , \f(CW\*(C`UVTYPE\*(C'\fR , \f(CW\*(C`U32Xf\*(C'\fR
+, \f(CW\*(C`U32xf\*(C'\fR , \f(CW\*(C`WIDEST_UTYPE\*(C'\fR
+.IX Xref "CASTI32 HAS_INT64_T HAS_LONG_LONG HAS_QUAD I32df INT16_C INT32_C INT64_C INTMAX_C INTSIZE I8SIZE I16SIZE I32SIZE I64SIZE I8TYPE I16TYPE I32TYPE I64TYPE IV_MAX IV_MIN IVSIZE IVTYPE line_t LONGLONGSIZE LONGSIZE memzero PERL_INT_FAST8_T PERL_INT_FAST16_T PERL_UINT_FAST8_T PERL_UINT_FAST 16_T PERL_INT_MAX PERL_INT_MIN PERL_LONG_MAX PERL_LONG_MIN PERL_QUAD_M AX PERL_QUAD_MIN PERL_SHORT_MAX PERL_SHORT_MIN PERL_UCHAR_MAX PER L_UCHAR_MIN PERL_UINT_MAX PERL_UINT_MIN PERL_ULONG_MAX PERL_ULONG_M IN PERL_UQUAD_MAX PERL_UQUAD_MIN PERL_USHORT_MAX PERL_USHORT_MIN SHORTSIZE UINT16_C UINT32_C UINT64_C UINTMAX_C U32of U8SIZE U16SIZE U32SIZE U64SIZE U8TYPE U16TYPE U32TYPE U64TYPE U32uf UV_MAX UV_MIN UVSIZE UVTYPE U32Xf U32xf WIDEST_UTYPE"
+.IP "I/O Formats" 4
+.IX Item "I/O Formats"
+\&\f(CW\*(C`HvNAMEf\*(C'\fR, \f(CW\*(C`HvNAMEf_QUOTEDPREFIX\*(C'\fR, \f(CW\*(C`IVdf\*(C'\fR , \f(CW\*(C`NVef\*(C'\fR ,
+\&\f(CW\*(C`NVff\*(C'\fR , \f(CW\*(C`NVgf\*(C'\fR , \f(CW\*(C`PERL_PRIeldbl\*(C'\fR ,
+\&\f(CW\*(C`PERL_PRIfldbl\*(C'\fR , \f(CW\*(C`PERL_PRIgldbl\*(C'\fR ,
+\&\f(CW\*(C`PERL_SCNfldbl\*(C'\fR , \f(CW\*(C`PRINTF_FORMAT_NULL_OK\*(C'\fR
+, \f(CW\*(C`SVf\*(C'\fR, \f(CW\*(C`SVfARG\*(C'\fR, \f(CW\*(C`SVf_QUOTEDPREFIX\*(C'\fR, \f(CW\*(C`UTF8f\*(C'\fR,
+\&\f(CW\*(C`UTF8fARG\*(C'\fR, \f(CW\*(C`UTF8f_QUOTEDPREFIX\*(C'\fR, \f(CW\*(C`UVf\*(C'\fR , \f(CW\*(C`UVof\*(C'\fR , \f(CW\*(C`UVuf\*(C'\fR
+, \f(CW\*(C`UVXf\*(C'\fR , \f(CW\*(C`UVxf\*(C'\fR
+.IX Xref "IVdf NVef NVff NVgf PERL_PRIeldbl PERL_PRIfldbl PERL_PRIgldbl PERL_SCNfldbl PRINTF_FORMAT_NULL_OK UVf UVof UVuf UVXf UVxf"
+.IP "Lexer interface" 4
+.IX Xref "LEX_KEEP_PREVIOUS LEX_STUFF_UTF8 PARSE_OPTIONAL"
+.IX Item "Lexer interface"
+\&\f(CW\*(C`BHK\*(C'\fR, \f(CW\*(C`lex_bufutf8\*(C'\fR , \f(CW\*(C`lex_discard_to\*(C'\fR ,
+\&\f(CW\*(C`lex_grow_linestr\*(C'\fR , \f(CW\*(C`lex_next_chunk\*(C'\fR
+, \f(CW\*(C`lex_peek_unichar\*(C'\fR ,
+\&\f(CW\*(C`lex_read_space\*(C'\fR , \f(CW\*(C`lex_read_to\*(C'\fR ,
+\&\f(CW\*(C`lex_read_unichar\*(C'\fR , \f(CW\*(C`lex_start\*(C'\fR ,
+\&\f(CW\*(C`lex_stuff_pv\*(C'\fR , \f(CW\*(C`lex_stuff_pvn\*(C'\fR ,
+\&\f(CW\*(C`lex_stuff_pvs\*(C'\fR , \f(CW\*(C`lex_stuff_sv\*(C'\fR ,
+\&\f(CW\*(C`lex_unstuff\*(C'\fR , \f(CW\*(C`parse_arithexpr\*(C'\fR ,
+\&\f(CW\*(C`parse_barestmt\*(C'\fR , \f(CW\*(C`parse_block\*(C'\fR ,
+\&\f(CW\*(C`parse_fullexpr\*(C'\fR , \f(CW\*(C`parse_fullstmt\*(C'\fR ,
+\&\f(CW\*(C`parse_label\*(C'\fR , \f(CW\*(C`parse_listexpr\*(C'\fR ,
+\&\f(CW\*(C`parse_stmtseq\*(C'\fR , \f(CW\*(C`parse_subsignature\*(C'\fR
+, \f(CW\*(C`parse_termexpr\*(C'\fR , \f(CW\*(C`PL_parser\*(C'\fR
+, \f(CW\*(C`PL_parser\->bufend\*(C'\fR ,
+\&\f(CW\*(C`PL_parser\->bufptr\*(C'\fR ,
+\&\f(CW\*(C`PL_parser\->linestart\*(C'\fR ,
+\&\f(CW\*(C`PL_parser\->linestr\*(C'\fR , \f(CW\*(C`suspend_compcv\*(C'\fR
+, \f(CW\*(C`wrap_infix_plugin\*(C'\fR ,
+\&\f(CW\*(C`wrap_keyword_plugin\*(C'\fR
+.IX Xref "lex_bufutf8 lex_discard_to lex_grow_linestr lex_next_chunk lex_peek_unichar lex_read_space lex_read_to lex_read_unichar lex_start lex_stuff_pv lex_stuff_pvn lex_stuff_pvs lex_stuff_sv lex_unstuff parse_arithexpr parse_barestmt parse_block parse_fullexpr parse_fullstmt parse_label parse_listexpr parse_stmtseq parse_subsignature parse_termexpr PL_parser PL_parser->bufend PL_parser->bufptr PL_parser->linestart PL_parser->linestr suspend_compcv wrap_infix_plugin wrap_keyword_plugin"
+.IP Locales 4
+.IX Item "Locales"
+\&\f(CW\*(C`DECLARATION_FOR_LC_NUMERIC_MANIPULATION\*(C'\fR
+, \f(CW\*(C`foldEQ_locale\*(C'\fR
+, \f(CW\*(C`HAS_DUPLOCALE\*(C'\fR , \f(CW\*(C`HAS_FREELOCALE\*(C'\fR
+, \f(CW\*(C`HAS_LC_MONETARY_2008\*(C'\fR ,
+\&\f(CW\*(C`HAS_LOCALECONV\*(C'\fR , \f(CW\*(C`HAS_LOCALECONV_L\*(C'\fR
+, \f(CW\*(C`HAS_NEWLOCALE\*(C'\fR , \f(CW\*(C`HAS_NL_LANGINFO\*(C'\fR
+, \f(CW\*(C`HAS_NL_LANGINFO_L\*(C'\fR ,
+\&\f(CW\*(C`HAS_QUERYLOCALE\*(C'\fR , \f(CW\*(C`HAS_SETLOCALE\*(C'\fR ,
+\&\f(CW\*(C`HAS_SETLOCALE_R\*(C'\fR , \f(CW\*(C`HAS_THREAD_SAFE_NL_LANGINFO_L\*(C'\fR
+, \f(CW\*(C`HAS_USELOCALE\*(C'\fR ,
+\&\f(CW\*(C`I_LANGINFO\*(C'\fR , \f(CW\*(C`I_LOCALE\*(C'\fR , \f(CW\*(C`IN_LOCALE\*(C'\fR
+, \f(CW\*(C`IN_LOCALE_COMPILETIME\*(C'\fR ,
+\&\f(CW\*(C`IN_LOCALE_RUNTIME\*(C'\fR , \f(CW\*(C`I_XLOCALE\*(C'\fR ,
+\&\f(CW\*(C`NEED_XLOCALE_H\*(C'\fR , \f(CW\*(C`Perl_langinfo\*(C'\fR, \f(CW\*(C`Perl_langinfo8\*(C'\fR
+, a, b, c, d, e, \f(CW\*(C`Perl_localeconv\*(C'\fR
+, \f(CW\*(C`Perl_setlocale\*(C'\fR ,
+\&\f(CW\*(C`RESTORE_LC_NUMERIC\*(C'\fR ,
+\&\f(CW\*(C`SETLOCALE_ACCEPTS_ANY_LOCALE_NAME\*(C'\fR ,
+\&\f(CW\*(C`STORE_LC_NUMERIC_FORCE_TO_UNDERLYING\*(C'\fR
+, \f(CW\*(C`STORE_LC_NUMERIC_SET_TO_NEEDED\*(C'\fR
+, \f(CW\*(C`STORE_LC_NUMERIC_SET_TO_NEEDED_IN\*(C'\fR
+, \f(CW\*(C`WITH_LC_NUMERIC_SET_TO_NEEDED\*(C'\fR
+, \f(CW\*(C`WITH_LC_NUMERIC_SET_TO_NEEDED_IN\*(C'\fR
+.IX Xref "DECLARATION_FOR_LC_NUMERIC_MANIPULATION foldEQ_locale HAS_DUPLOCALE HAS_FREELOCALE HAS_LC_MONETARY_2008 HAS_LOCALECONV HAS_LOCALECONV_L HAS_NEWLOCALE HAS_NL_LANGINFO HAS_NL_LANGINFO_L HAS_QUERYLOCALE HAS_SETLOCALE HAS_SETLOCALE_R HAS_THREAD_SAFE_NL_LANGINFO_L HAS_USELOCALE I_LANGINFO I_LOCALE IN_LOCALE IN_LOCALE_COMPILETIME IN_LOCALE_RUNTIME I_XLOCALE NEED_XLOCALE_H Perl_langinfo Perl_langinfo8 Perl_localeconv Perl_setlocale RESTORE_LC_NUMERIC SETLOCALE_ACCEPTS_ANY_LOCALE_NAME STORE_LC_NUMERIC_FORCE_TO_UNDERLYING STORE_LC_NUMERIC_SET_TO_NEEDED STORE_LC_NUMERIC_SET_TO_NEEDED_IN WITH_LC_NUMERIC_SET_TO_NEEDED WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
+.IP Magic 4
+.IX Xref "MAGIC"
+.IX Item "Magic"
+\&\f(CW\*(C`mg_clear\*(C'\fR , \f(CW\*(C`mg_copy\*(C'\fR , \f(CW\*(C`MGf_COPY\*(C'\fR, \f(CW\*(C`MGf_DUP\*(C'\fR,
+\&\f(CW\*(C`MGf_LOCAL\*(C'\fR, \f(CW\*(C`mg_find\*(C'\fR , \f(CW\*(C`mg_findext\*(C'\fR ,
+\&\f(CW\*(C`mg_free\*(C'\fR , \f(CW\*(C`mg_freeext\*(C'\fR , \f(CW\*(C`mg_free_type\*(C'\fR
+, \f(CW\*(C`mg_get\*(C'\fR , \f(CW\*(C`mg_magical\*(C'\fR ,
+\&\f(CW\*(C`mg_set\*(C'\fR , \f(CW\*(C`MGVTBL\*(C'\fR, \f(CW\*(C`PERL_MAGIC_arylen\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_arylen_p\*(C'\fR, \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR, \f(CW\*(C`PERL_MAGIC_bm\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_checkcall\*(C'\fR, \f(CW\*(C`PERL_MAGIC_collxfrm\*(C'\fR, \f(CW\*(C`PERL_MAGIC_dbfile\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_dbline\*(C'\fR, \f(CW\*(C`PERL_MAGIC_debugvar\*(C'\fR, \f(CW\*(C`PERL_MAGIC_defelem\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_destruct\*(C'\fR, \f(CW\*(C`PERL_MAGIC_env\*(C'\fR, \f(CW\*(C`PERL_MAGIC_envelem\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_ext\*(C'\fR, \f(CW\*(C`PERL_MAGIC_extvalue\*(C'\fR, \f(CW\*(C`PERL_MAGIC_fm\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_hints\*(C'\fR, \f(CW\*(C`PERL_MAGIC_hintselem\*(C'\fR, \f(CW\*(C`PERL_MAGIC_hook\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_hookelem\*(C'\fR, \f(CW\*(C`PERL_MAGIC_isa\*(C'\fR, \f(CW\*(C`PERL_MAGIC_isaelem\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_lvref\*(C'\fR, \f(CW\*(C`PERL_MAGIC_nkeys\*(C'\fR, \f(CW\*(C`PERL_MAGIC_nonelem\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_overload_table\*(C'\fR, \f(CW\*(C`PERL_MAGIC_pos\*(C'\fR, \f(CW\*(C`PERL_MAGIC_qr\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_regdata\*(C'\fR, \f(CW\*(C`PERL_MAGIC_regdatum\*(C'\fR, \f(CW\*(C`PERL_MAGIC_regex_global\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_rhash\*(C'\fR, \f(CW\*(C`PERL_MAGIC_shared\*(C'\fR, \f(CW\*(C`PERL_MAGIC_shared_scalar\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_sig\*(C'\fR, \f(CW\*(C`PERL_MAGIC_sigelem\*(C'\fR, \f(CW\*(C`PERL_MAGIC_substr\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_sv\*(C'\fR, \f(CW\*(C`PERL_MAGIC_symtab\*(C'\fR, \f(CW\*(C`PERL_MAGIC_taint\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_tied\*(C'\fR, \f(CW\*(C`PERL_MAGIC_tiedelem\*(C'\fR, \f(CW\*(C`PERL_MAGIC_tiedscalar\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_utf8\*(C'\fR, \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR, \f(CW\*(C`PERL_MAGIC_uvar_elem\*(C'\fR,
+\&\f(CW\*(C`PERL_MAGIC_vec\*(C'\fR, \f(CW\*(C`PERL_MAGIC_vstring\*(C'\fR, \f(CW\*(C`SvTIED_obj\*(C'\fR
+.IX Xref "mg_clear mg_copy mg_find mg_findext mg_free mg_freeext mg_free_type mg_get mg_magical mg_set"
+.IP "Memory Management" 4
+.IX Item "Memory Management"
+\&\f(CW\*(C`dump_mstats\*(C'\fR , \f(CW\*(C`HASATTRIBUTE_MALLOC\*(C'\fR
+, \f(CW\*(C`HAS_MALLOC_GOOD_SIZE\*(C'\fR ,
+\&\f(CW\*(C`HAS_MALLOC_SIZE\*(C'\fR , \f(CW\*(C`I_MALLOCMALLOC\*(C'\fR ,
+\&\f(CW\*(C`MYMALLOC\*(C'\fR , \f(CW\*(C`Newx\*(C'\fR, \f(CW\*(C`safemalloc\*(C'\fR ,
+\&\f(CW\*(C`Newxc\*(C'\fR , \f(CW\*(C`Newxz\*(C'\fR, \f(CW\*(C`safecalloc\*(C'\fR ,
+\&\f(CW\*(C`PERL_MALLOC_WRAP\*(C'\fR , \f(CW\*(C`Renew\*(C'\fR, \f(CW\*(C`saferealloc\*(C'\fR
+, \f(CW\*(C`Renewc\*(C'\fR , \f(CW\*(C`Safefree\*(C'\fR ,
+\&\f(CW\*(C`safesyscalloc\*(C'\fR , \f(CW\*(C`safesysfree\*(C'\fR ,
+\&\f(CW\*(C`safesysmalloc\*(C'\fR , \f(CW\*(C`safesysrealloc\*(C'\fR
+.IX Xref "dump_mstats HASATTRIBUTE_MALLOC HAS_MALLOC_GOOD_SIZE HAS_MALLOC_SIZE I_MALLOCMALLOC MYMALLOC Newx safemalloc Newxc Newxz safecalloc PERL_MALLOC_WRAP Renew saferealloc Renewc Safefree safesyscalloc safesysfree safesysmalloc safesysrealloc"
+.IP MRO 4
+.IX Item "MRO"
+\&\f(CW\*(C`HvMROMETA\*(C'\fR, \f(CW\*(C`mro_get_from_name\*(C'\fR ,
+\&\f(CW\*(C`mro_get_linear_isa\*(C'\fR , \f(CW\*(C`MRO_GET_PRIVATE_DATA\*(C'\fR,
+\&\f(CW\*(C`mro_method_changed_in\*(C'\fR , \f(CW\*(C`mro_register\*(C'\fR
+, \f(CW\*(C`mro_set_mro\*(C'\fR , \f(CW\*(C`mro_set_private_data\*(C'\fR
+.IX Xref "mro_get_from_name mro_get_linear_isa mro_method_changed_in mro_register mro_set_mro"
+.IP "Multicall Functions" 4
+.IX Item "Multicall Functions"
+\&\f(CW\*(C`dMULTICALL\*(C'\fR , \f(CW\*(C`MULTICALL\*(C'\fR , \f(CW\*(C`POP_MULTICALL\*(C'\fR
+, \f(CW\*(C`PUSH_MULTICALL\*(C'\fR
+.IX Xref "dMULTICALL MULTICALL POP_MULTICALL PUSH_MULTICALL"
+.IP "Numeric Functions" 4
+.IX Xref "IS_NUMBER_GREATER_THAN_UV_MAX IS_NUMBER_INFINITY IS_NUMBER_IN_UV IS _NUMBER_NAN IS_NUMBER_NEG IS_NUMBER_NOT_INT PERL_SCAN_ALLOW_UNDERSCOR ES PERL_SCAN_DISALLOW_PREFIX PERL_SCAN_GREATER_THAN_UV_MAX PERL_SCAN_ SILENT_ILLDIGIT PERL_SCAN_TRAILING"
+.IX Item "Numeric Functions"
+\&\f(CW\*(C`Atol\*(C'\fR, \f(CW\*(C`Atoul\*(C'\fR, \f(CW\*(C`Drand01\*(C'\fR , \f(CW\*(C`Gconvert\*(C'\fR ,
+\&\f(CW\*(C`grok_atoUV\*(C'\fR , \f(CW\*(C`grok_bin\*(C'\fR , \f(CW\*(C`grok_hex\*(C'\fR
+, \f(CW\*(C`grok_infnan\*(C'\fR , \f(CW\*(C`grok_number\*(C'\fR ,
+\&\f(CW\*(C`grok_number_flags\*(C'\fR , \f(CW\*(C`GROK_NUMERIC_RADIX\*(C'\fR
+, \f(CW\*(C`grok_numeric_radix\*(C'\fR ,
+\&\f(CW\*(C`grok_oct\*(C'\fR , \f(CW\*(C`isinfnan\*(C'\fR , \f(CW\*(C`my_atof\*(C'\fR ,
+\&\f(CW\*(C`my_strtod\*(C'\fR , \f(CW\*(C`PERL_ABS\*(C'\fR , \f(CW\*(C`Perl_acos\*(C'\fR,
+\&\f(CW\*(C`Perl_asin\*(C'\fR, \f(CW\*(C`Perl_atan\*(C'\fR, \f(CW\*(C`Perl_atan2\*(C'\fR, \f(CW\*(C`Perl_ceil\*(C'\fR, \f(CW\*(C`Perl_cos\*(C'\fR,
+\&\f(CW\*(C`Perl_cosh\*(C'\fR, \f(CW\*(C`Perl_exp\*(C'\fR, \f(CW\*(C`Perl_floor\*(C'\fR, \f(CW\*(C`Perl_fmod\*(C'\fR, \f(CW\*(C`Perl_frexp\*(C'\fR,
+\&\f(CW\*(C`Perl_isfinite\*(C'\fR, \f(CW\*(C`Perl_isinf\*(C'\fR, \f(CW\*(C`Perl_isnan\*(C'\fR, \f(CW\*(C`Perl_ldexp\*(C'\fR, \f(CW\*(C`Perl_log\*(C'\fR,
+\&\f(CW\*(C`Perl_log10\*(C'\fR, \f(CW\*(C`Perl_modf\*(C'\fR, \f(CW\*(C`Perl_pow\*(C'\fR, \f(CW\*(C`Perl_sin\*(C'\fR, \f(CW\*(C`Perl_sinh\*(C'\fR,
+\&\f(CW\*(C`Perl_sqrt\*(C'\fR, \f(CW\*(C`Perl_tan\*(C'\fR, \f(CW\*(C`Perl_tanh\*(C'\fR
+X
+<Perl_isinf>X
+<Perl_pow>,
+\&\f(CW\*(C`Perl_signbit\*(C'\fR , \f(CW\*(C`PL_hexdigit\*(C'\fR ,
+\&\f(CW\*(C`READ_XDIGIT\*(C'\fR , \f(CW\*(C`scan_bin\*(C'\fR , \f(CW\*(C`scan_hex\*(C'\fR
+, \f(CW\*(C`scan_oct\*(C'\fR , \f(CW\*(C`seedDrand01\*(C'\fR ,
+\&\f(CW\*(C`Strtod\*(C'\fR , \f(CW\*(C`Strtol\*(C'\fR , \f(CW\*(C`Strtoul\*(C'\fR
+.IX Xref "Drand01 Gconvert grok_atoUV grok_bin grok_hex grok_infnan grok_number grok_number_flags GROK_NUMERIC_RADIX grok_numeric_radix grok_oct isinfnan my_atof my_strtod PERL_ABS Perl_acos Perl_asin Perl_atan Perl_atan2 Perl_ceil Perl_cos P erl_cosh Perl_exp Perl_floor Perl_fmod Perl_frexp Perl_isfinite Perl_isnan Perl_ldexp Perl_log Perl_log10 Perl_modf Perl_sin Perl_sinh Perl_sqrt Perl_tan Perl_tanh Perl_signbit PL_hexdigit READ_XDIGIT scan_bin scan_hex scan_oct seedDrand01 Strtod Strtol Strtoul"
+.IP Optrees 4
+.IX Xref "CALL_CHECKER_REQUIRE_GV OPf_KIDS OPpEARLY_CV OPpENTERSUB_AMPER RV 2CVOPCV_MARK_EARLY RV2CVOPCV_RETURN_NAME_GV"
+.IX Item "Optrees"
+\&\f(CW\*(C`alloccopstash\*(C'\fR , \f(CW\*(C`BINOP\*(C'\fR, \f(CW\*(C`block_end\*(C'\fR ,
+\&\f(CW\*(C`block_start\*(C'\fR , \f(CW\*(C`ck_entersub_args_list\*(C'\fR
+, \f(CW\*(C`ck_entersub_args_proto\*(C'\fR
+, \f(CW\*(C`ck_entersub_args_proto_or_list\*(C'\fR
+, \f(CW\*(C`cv_const_sv\*(C'\fR ,
+\&\f(CW\*(C`cv_get_call_checker\*(C'\fR , \f(CW\*(C`cv_get_call_checker_flags\*(C'\fR
+, \f(CW\*(C`cv_set_call_checker\*(C'\fR
+, \f(CW\*(C`cv_set_call_checker_flags\*(C'\fR
+, \f(CW\*(C`finalize_optree\*(C'\fR ,
+\&\f(CW\*(C`forbid_outofblock_ops\*(C'\fR , \f(CW\*(C`LINKLIST\*(C'\fR ,
+\&\f(CW\*(C`LISTOP\*(C'\fR, \f(CW\*(C`LOGOP\*(C'\fR, \f(CW\*(C`LOOP\*(C'\fR, \f(CW\*(C`newARGDEFELEMOP\*(C'\fR ,
+\&\f(CW\*(C`newASSIGNOP\*(C'\fR , \f(CW\*(C`newATTRSUB\*(C'\fR , \f(CW\*(C`newBINOP\*(C'\fR
+, \f(CW\*(C`newCONDOP\*(C'\fR , \f(CW\*(C`newCONSTSUB\*(C'\fR ,
+\&\f(CW\*(C`newCONSTSUB_flags\*(C'\fR , \f(CW\*(C`newDEFEROP\*(C'\fR ,
+\&\f(CW\*(C`newDEFSVOP\*(C'\fR , \f(CW\*(C`newFOROP\*(C'\fR , \f(CW\*(C`newGIVENOP\*(C'\fR
+, \f(CW\*(C`newGVOP\*(C'\fR , \f(CW\*(C`newLISTOP\*(C'\fR ,
+\&\f(CW\*(C`newLOGOP\*(C'\fR , \f(CW\*(C`newLOOPEX\*(C'\fR , \f(CW\*(C`newLOOPOP\*(C'\fR
+, \f(CW\*(C`newMETHOP\*(C'\fR , \f(CW\*(C`newMETHOP_named\*(C'\fR
+, \f(CW\*(C`newNULLLIST\*(C'\fR , \f(CW\*(C`newOP\*(C'\fR ,
+\&\f(CW\*(C`newPADOP\*(C'\fR , \f(CW\*(C`newPMOP\*(C'\fR , \f(CW\*(C`newPVOP\*(C'\fR ,
+\&\f(CW\*(C`newRANGE\*(C'\fR , \f(CW\*(C`newSLICEOP\*(C'\fR , \f(CW\*(C`newSTATEOP\*(C'\fR
+, \f(CW\*(C`newSUB\*(C'\fR , \f(CW\*(C`newSVOP\*(C'\fR , \f(CW\*(C`newTRYCATCHOP\*(C'\fR
+, \f(CW\*(C`newUNOP\*(C'\fR , \f(CW\*(C`newUNOP_AUX\*(C'\fR ,
+\&\f(CW\*(C`newWHENOP\*(C'\fR , \f(CW\*(C`newWHILEOP\*(C'\fR , \f(CW\*(C`newXS\*(C'\fR ,
+\&\f(CW\*(C`OA_BASEOP\*(C'\fR, \f(CW\*(C`OA_BINOP\*(C'\fR, \f(CW\*(C`OA_COP\*(C'\fR, \f(CW\*(C`OA_LISTOP\*(C'\fR, \f(CW\*(C`OA_LOGOP\*(C'\fR,
+\&\f(CW\*(C`OA_LOOP\*(C'\fR, \f(CW\*(C`OA_PADOP\*(C'\fR, \f(CW\*(C`OA_PMOP\*(C'\fR, \f(CW\*(C`OA_PVOP_OR_SVOP\*(C'\fR, \f(CW\*(C`OA_SVOP\*(C'\fR,
+\&\f(CW\*(C`OA_UNOP\*(C'\fR, \f(CW\*(C`OP\*(C'\fR, \f(CW\*(C`op_append_elem\*(C'\fR , \f(CW\*(C`op_append_list\*(C'\fR
+, \f(CW\*(C`OP_CLASS\*(C'\fR , \f(CW\*(C`op_contextualize\*(C'\fR
+, \f(CW\*(C`op_convert_list\*(C'\fR , \f(CW\*(C`OP_DESC\*(C'\fR
+, \f(CW\*(C`op_force_list\*(C'\fR , \f(CW\*(C`op_free\*(C'\fR ,
+\&\f(CW\*(C`OpHAS_SIBLING\*(C'\fR , \f(CW\*(C`OpLASTSIB_set\*(C'\fR ,
+\&\f(CW\*(C`op_linklist\*(C'\fR , \f(CW\*(C`op_lvalue\*(C'\fR , \f(CW\*(C`OpMAYBESIB_set\*(C'\fR
+, \f(CW\*(C`OpMORESIB_set\*(C'\fR , \f(CW\*(C`OP_NAME\*(C'\fR
+, \f(CW\*(C`op_null\*(C'\fR , \f(CW\*(C`op_parent\*(C'\fR ,
+\&\f(CW\*(C`op_prepend_elem\*(C'\fR , \f(CW\*(C`op_scope\*(C'\fR ,
+\&\f(CW\*(C`OpSIBLING\*(C'\fR , \f(CW\*(C`op_sibling_splice\*(C'\fR ,
+\&\f(CW\*(C`optimize_optree\*(C'\fR , \f(CW\*(C`OP_TYPE_IS\*(C'\fR ,
+\&\f(CW\*(C`OP_TYPE_IS_OR_WAS\*(C'\fR , \f(CW\*(C`op_wrap_finally\*(C'\fR
+, \f(CW\*(C`peep_t\*(C'\fR, \f(CW\*(C`Perl_cpeep_t\*(C'\fR, \f(CW\*(C`PL_opfreehook\*(C'\fR
+, \f(CW\*(C`PL_peepp\*(C'\fR , \f(CW\*(C`PL_rpeepp\*(C'\fR ,
+\&\f(CW\*(C`PMOP\*(C'\fR, \f(CW\*(C`rv2cv_op_cv\*(C'\fR , \f(CW\*(C`UNOP\*(C'\fR, \f(CW\*(C`XOP\*(C'\fR
+.IX Xref "alloccopstash block_end block_start ck_entersub_args_list ck_entersub_args_proto ck_entersub_args_proto_or_list cv_const_sv cv_get_call_checker cv_get_call_checker_flags cv_set_call_checker cv_set_call_checker_flags finalize_optree forbid_outofblock_ops LINKLIST newARGDEFELEMOP newASSIGNOP newATTRSUB newBINOP newCONDOP newCONSTSUB newCONSTSUB_flags newDEFEROP newDEFSVOP newFOROP newGIVENOP newGVOP newLISTOP newLOGOP newLOOPEX newLOOPOP newMETHOP newMETHOP_named newNULLLIST newOP newPADOP newPMOP newPVOP newRANGE newSLICEOP newSTATEOP newSUB newSVOP newTRYCATCHOP newUNOP newUNOP_AUX newWHENOP newWHILEOP newXS op_append_elem op_append_list OP_CLASS op_contextualize op_convert_list OP_DESC op_force_list op_free OpHAS_SIBLING OpLASTSIB_set op_linklist op_lvalue OpMAYBESIB_set OpMORESIB_set OP_NAME op_null op_parent op_prepend_elem op_scope OpSIBLING op_sibling_splice optimize_optree OP_TYPE_IS OP_TYPE_IS_OR_WAS op_wrap_finally PL_opfreehook PL_peepp PL_rpeepp rv2cv_op_cv"
+.IP "Pack and Unpack" 4
+.IX Item "Pack and Unpack"
+\&\f(CW\*(C`packlist\*(C'\fR , \f(CW\*(C`unpackstring\*(C'\fR
+.IX Xref "packlist unpackstring"
+.IP "Pad Data Structures" 4
+.IX Xref "SVs_PADSTALE"
+.IX Item "Pad Data Structures"
+\&\f(CW\*(C`CvPADLIST\*(C'\fR , \f(CW\*(C`pad_add_name_pvs\*(C'\fR ,
+\&\f(CW\*(C`PadARRAY\*(C'\fR , \f(CW\*(C`pad_findmy_pvs\*(C'\fR ,
+\&\f(CW\*(C`PadlistARRAY\*(C'\fR , \f(CW\*(C`PadlistMAX\*(C'\fR ,
+\&\f(CW\*(C`PadlistNAMES\*(C'\fR , \f(CW\*(C`PadlistNAMESARRAY\*(C'\fR ,
+\&\f(CW\*(C`PadlistNAMESMAX\*(C'\fR , \f(CW\*(C`PadlistREFCNT\*(C'\fR ,
+\&\f(CW\*(C`PadMAX\*(C'\fR , \f(CW\*(C`PadnameLEN\*(C'\fR , \f(CW\*(C`PadnamelistARRAY\*(C'\fR
+, \f(CW\*(C`PadnamelistMAX\*(C'\fR ,
+\&\f(CW\*(C`PadnamelistREFCNT\*(C'\fR , \f(CW\*(C`PadnamelistREFCNT_dec\*(C'\fR
+, \f(CW\*(C`PadnamePV\*(C'\fR , \f(CW\*(C`PadnameREFCNT\*(C'\fR
+, \f(CW\*(C`PadnameREFCNT_dec\*(C'\fR ,
+\&\f(CW\*(C`PadnameREFCNT_inc\*(C'\fR , \f(CW\*(C`PadnameSV\*(C'\fR ,
+\&\f(CW\*(C`PadnameUTF8\*(C'\fR , \f(CW\*(C`pad_new\*(C'\fR , \f(CW\*(C`PL_comppad\*(C'\fR
+, \f(CW\*(C`PL_comppad_name\*(C'\fR , \f(CW\*(C`PL_curpad\*(C'\fR
+, \f(CW\*(C`SVs_PADMY\*(C'\fR, \f(CW\*(C`SVs_PADTMP\*(C'\fR
+.IX Xref "CvPADLIST pad_add_name_pvs PadARRAY pad_findmy_pvs PadlistARRAY PadlistMAX PadlistNAMES PadlistNAMESARRAY PadlistNAMESMAX PadlistREFCNT PadMAX PadnameLEN PadnamelistARRAY PadnamelistMAX PadnamelistREFCNT PadnamelistREFCNT_dec PadnamePV PadnameREFCNT PadnameREFCNT_dec PadnameREFCNT_inc PadnameSV PadnameUTF8 pad_new PL_comppad PL_comppad_name PL_curpad"
+.IP "Password and Group access" 4
+.IX Item "Password and Group access"
+\&\f(CW\*(C`GRPASSWD\*(C'\fR , \f(CW\*(C`HAS_ENDGRENT\*(C'\fR , \f(CW\*(C`HAS_ENDGRENT_R\*(C'\fR
+, \f(CW\*(C`HAS_ENDPWENT\*(C'\fR , \f(CW\*(C`HAS_ENDPWENT_R\*(C'\fR
+, \f(CW\*(C`HAS_GETGRENT\*(C'\fR , \f(CW\*(C`HAS_GETGRENT_R\*(C'\fR
+, \f(CW\*(C`HAS_GETPWENT\*(C'\fR , \f(CW\*(C`HAS_GETPWENT_R\*(C'\fR
+, \f(CW\*(C`HAS_SETGRENT\*(C'\fR , \f(CW\*(C`HAS_SETGRENT_R\*(C'\fR
+, \f(CW\*(C`HAS_SETPWENT\*(C'\fR , \f(CW\*(C`HAS_SETPWENT_R\*(C'\fR
+, \f(CW\*(C`PWAGE\*(C'\fR , \f(CW\*(C`PWCHANGE\*(C'\fR , \f(CW\*(C`PWCLASS\*(C'\fR
+, \f(CW\*(C`PWCOMMENT\*(C'\fR , \f(CW\*(C`PWEXPIRE\*(C'\fR , \f(CW\*(C`PWGECOS\*(C'\fR
+, \f(CW\*(C`PWPASSWD\*(C'\fR , \f(CW\*(C`PWQUOTA\*(C'\fR
+.IX Xref "GRPASSWD HAS_ENDGRENT HAS_ENDGRENT_R HAS_ENDPWENT HAS_ENDPWENT_R HAS_GETGRENT HAS_GETGRENT_R HAS_GETPWENT HAS_GETPWENT_R HAS_SETGRENT HAS_SETGRENT_R HAS_SETPWENT HAS_SETPWENT_R PWAGE PWCHANGE PWCLASS PWCOMMENT PWEXPIRE PWGECOS PWPASSWD PWQUOTA"
+.IP "Paths to system commands" 4
+.IX Item "Paths to system commands"
+\&\f(CW\*(C`CSH\*(C'\fR , \f(CW\*(C`LOC_SED\*(C'\fR , \f(CW\*(C`SH_PATH\*(C'\fR
+.IX Xref "CSH LOC_SED SH_PATH"
+.IP "Prototype information" 4
+.IX Item "Prototype information"
+\&\f(CW\*(C`CRYPT_R_PROTO\*(C'\fR , \f(CW\*(C`CTERMID_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`DRAND48_R_PROTO\*(C'\fR , \f(CW\*(C`ENDGRENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`ENDHOSTENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`ENDNETENT_R_PROTO\*(C'\fR , \f(CW\*(C`ENDPROTOENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`ENDPWENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`ENDSERVENT_R_PROTO\*(C'\fR , \f(CW\*(C`GDBMNDBM_H_USES_PROTOTYPES\*(C'\fR
+, \f(CW\*(C`GDBM_NDBM_H_USES_PROTOTYPES\*(C'\fR
+, \f(CW\*(C`GETGRENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETGRGID_R_PROTO\*(C'\fR , \f(CW\*(C`GETGRNAM_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETHOSTBYADDR_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETHOSTBYNAME_R_PROTO\*(C'\fR , \f(CW\*(C`GETHOSTENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETLOGIN_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETNETBYADDR_R_PROTO\*(C'\fR , \f(CW\*(C`GETNETBYNAME_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETNETENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETPROTOBYNAME_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETPROTOBYNUMBER_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETPROTOENT_R_PROTO\*(C'\fR , \f(CW\*(C`GETPWENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETPWNAM_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETPWUID_R_PROTO\*(C'\fR , \f(CW\*(C`GETSERVBYNAME_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETSERVBYPORT_R_PROTO\*(C'\fR
+, \f(CW\*(C`GETSERVENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GETSPNAM_R_PROTO\*(C'\fR , \f(CW\*(C`HAS_DBMINIT_PROTO\*(C'\fR
+, \f(CW\*(C`HAS_DRAND48_PROTO\*(C'\fR ,
+\&\f(CW\*(C`HAS_FLOCK_PROTO\*(C'\fR , \f(CW\*(C`HAS_GETHOST_PROTOS\*(C'\fR
+, \f(CW\*(C`HAS_GETNET_PROTOS\*(C'\fR ,
+\&\f(CW\*(C`HAS_GETPROTO_PROTOS\*(C'\fR , \f(CW\*(C`HAS_GETSERV_PROTOS\*(C'\fR
+, \f(CW\*(C`HAS_MODFL_PROTO\*(C'\fR ,
+\&\f(CW\*(C`HAS_SBRK_PROTO\*(C'\fR , \f(CW\*(C`HAS_SETRESGID_PROTO\*(C'\fR
+, \f(CW\*(C`HAS_SETRESUID_PROTO\*(C'\fR ,
+\&\f(CW\*(C`HAS_SHMAT_PROTOTYPE\*(C'\fR , \f(CW\*(C`HAS_SOCKATMARK_PROTO\*(C'\fR
+, \f(CW\*(C`HAS_SYSCALL_PROTO\*(C'\fR ,
+\&\f(CW\*(C`HAS_TELLDIR_PROTO\*(C'\fR , \f(CW\*(C`NDBM_H_USES_PROTOTYPES\*(C'\fR
+, \f(CW\*(C`RANDOM_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`READDIR_R_PROTO\*(C'\fR , \f(CW\*(C`SETGRENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`SETHOSTENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`SETLOCALE_R_PROTO\*(C'\fR , \f(CW\*(C`SETNETENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`SETPROTOENT_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`SETPWENT_R_PROTO\*(C'\fR , \f(CW\*(C`SETSERVENT_R_PROTO\*(C'\fR
+, \f(CW\*(C`SRANDOM_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`SRAND48_R_PROTO\*(C'\fR , \f(CW\*(C`STRERROR_R_PROTO\*(C'\fR
+, \f(CW\*(C`TMPNAM_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`TTYNAME_R_PROTO\*(C'\fR
+.IX Xref "CRYPT_R_PROTO CTERMID_R_PROTO DRAND48_R_PROTO ENDGRENT_R_PROTO ENDHOSTENT_R_PROTO ENDNETENT_R_PROTO ENDPROTOENT_R_PROTO ENDPWENT_R_PROTO ENDSERVENT_R_PROTO GDBMNDBM_H_USES_PROTOTYPES GDBM_NDBM_H_USES_PROTOTYPES GETGRENT_R_PROTO GETGRGID_R_PROTO GETGRNAM_R_PROTO GETHOSTBYADDR_R_PROTO GETHOSTBYNAME_R_PROTO GETHOSTENT_R_PROTO GETLOGIN_R_PROTO GETNETBYADDR_R_PROTO GETNETBYNAME_R_PROTO GETNETENT_R_PROTO GETPROTOBYNAME_R_PROTO GETPROTOBYNUMBER_R_PROTO GETPROTOENT_R_PROTO GETPWENT_R_PROTO GETPWNAM_R_PROTO GETPWUID_R_PROTO GETSERVBYNAME_R_PROTO GETSERVBYPORT_R_PROTO GETSERVENT_R_PROTO GETSPNAM_R_PROTO HAS_DBMINIT_PROTO HAS_DRAND48_PROTO HAS_FLOCK_PROTO HAS_GETHOST_PROTOS HAS_GETNET_PROTOS HAS_GETPROTO_PROTOS HAS_GETSERV_PROTOS HAS_MODFL_PROTO HAS_SBRK_PROTO HAS_SETRESGID_PROTO HAS_SETRESUID_PROTO HAS_SHMAT_PROTOTYPE HAS_SOCKATMARK_PROTO HAS_SYSCALL_PROTO HAS_TELLDIR_PROTO NDBM_H_USES_PROTOTYPES RANDOM_R_PROTO READDIR_R_PROTO SETGRENT_R_PROTO SETHOSTENT_R_PROTO SETLOCALE_R_PROTO SETNETENT_R_PROTO SETPROTOENT_R_PROTO SETPWENT_R_PROTO SETSERVENT_R_PROTO SRANDOM_R_PROTO SRAND48_R_PROTO STRERROR_R_PROTO TMPNAM_R_PROTO TTYNAME_R_PROTO"
+.IP "REGEXP Functions" 4
+.IX Item "REGEXP Functions"
+\&\f(CW\*(C`pregcomp\*(C'\fR, \f(CW\*(C`pregexec\*(C'\fR, \f(CW\*(C`re_compile\*(C'\fR , \f(CW\*(C`re_dup_guts\*(C'\fR
+, \f(CW\*(C`REGEX_LOCALE_CHARSET\*(C'\fR, \f(CW\*(C`REGEXP\*(C'\fR, \f(CW\*(C`regexp_engine\*(C'\fR
+, \f(CW\*(C`regexp_paren_pair\*(C'\fR, \f(CW\*(C`regmatch_info\*(C'\fR ,
+\&\f(CW\*(C`REXEC_COPY_SKIP_POST\*(C'\fR, \f(CW\*(C`REXEC_COPY_SKIP_PRE\*(C'\fR, \f(CW\*(C`REXEC_COPY_STR\*(C'\fR,
+\&\f(CW\*(C`RXapif_ALL\*(C'\fR, \f(CW\*(C`RXapif_CLEAR\*(C'\fR, \f(CW\*(C`RXapif_DELETE\*(C'\fR, \f(CW\*(C`RXapif_EXISTS\*(C'\fR,
+\&\f(CW\*(C`RXapif_FETCH\*(C'\fR, \f(CW\*(C`RXapif_FIRSTKEY\*(C'\fR, \f(CW\*(C`RXapif_NEXTKEY\*(C'\fR, \f(CW\*(C`RXapif_ONE\*(C'\fR,
+\&\f(CW\*(C`RXapif_REGNAME\*(C'\fR, \f(CW\*(C`RXapif_REGNAMES\*(C'\fR, \f(CW\*(C`RXapif_REGNAMES_COUNT\*(C'\fR,
+\&\f(CW\*(C`RXapif_SCALAR\*(C'\fR, \f(CW\*(C`RXapif_STORE\*(C'\fR, \f(CW\*(C`RX_BUFF_IDX_CARET_FULLMATCH\*(C'\fR,
+\&\f(CW\*(C`RX_BUFF_IDX_CARET_POSTMATCH\*(C'\fR, \f(CW\*(C`RX_BUFF_IDX_CARET_PREMATCH\*(C'\fR,
+\&\f(CW\*(C`RX_BUFF_IDX_FULLMATCH\*(C'\fR, \f(CW\*(C`RX_BUFF_IDX_POSTMATCH\*(C'\fR,
+\&\f(CW\*(C`RX_BUFF_IDX_PREMATCH\*(C'\fR, \f(CW\*(C`RXf_NO_INPLACE_SUBST\*(C'\fR, \f(CW\*(C`RXf_NULL\*(C'\fR,
+\&\f(CW\*(C`RXf_SKIPWHITE\*(C'\fR, \f(CW\*(C`RXf_SPLIT\*(C'\fR, \f(CW\*(C`RXf_START_ONLY\*(C'\fR, \f(CW\*(C`RXf_WHITE\*(C'\fR,
+\&\f(CW\*(C`RXf_PMf_EXTENDED\*(C'\fR, \f(CW\*(C`RXf_PMf_FOLD\*(C'\fR, \f(CW\*(C`RXf_PMf_KEEPCOPY\*(C'\fR,
+\&\f(CW\*(C`RXf_PMf_MULTILINE\*(C'\fR, \f(CW\*(C`RXf_PMf_SINGLELINE\*(C'\fR, \f(CW\*(C`RX_MATCH_COPIED\*(C'\fR,
+\&\f(CW\*(C`RX_OFFS\*(C'\fR, \f(CW\*(C`SvRX\*(C'\fR , \f(CW\*(C`SvRXOK\*(C'\fR , \f(CW\*(C`SV_SAVED_COPY\*(C'\fR
+.IX Xref "re_compile re_dup_guts regexp_engine regmatch_info SvRX SvRXOK"
+.IP "Reports and Formats" 4
+.IX Item "Reports and Formats"
+\&\f(CW\*(C`IoBOTTOM_GV\*(C'\fR, \f(CW\*(C`IoBOTTOM_NAME\*(C'\fR, \f(CW\*(C`IoFMT_GV\*(C'\fR, \f(CW\*(C`IoFMT_NAME\*(C'\fR, \f(CW\*(C`IoLINES\*(C'\fR,
+\&\f(CW\*(C`IoLINES_LEFT\*(C'\fR, \f(CW\*(C`IoPAGE\*(C'\fR, \f(CW\*(C`IoPAGE_LEN\*(C'\fR, \f(CW\*(C`IoTOP_GV\*(C'\fR, \f(CW\*(C`IoTOP_NAME\*(C'\fR
+.IP Signals 4
+.IX Item "Signals"
+\&\f(CW\*(C`HAS_SIGINFO_SI_ADDR\*(C'\fR , \f(CW\*(C`HAS_SIGINFO_SI_BAND\*(C'\fR
+, \f(CW\*(C`HAS_SIGINFO_SI_ERRNO\*(C'\fR ,
+\&\f(CW\*(C`HAS_SIGINFO_SI_PID\*(C'\fR , \f(CW\*(C`HAS_SIGINFO_SI_STATUS\*(C'\fR
+, \f(CW\*(C`HAS_SIGINFO_SI_UID\*(C'\fR ,
+\&\f(CW\*(C`HAS_SIGINFO_SI_VALUE\*(C'\fR ,
+\&\f(CW\*(C`PERL_SIGNALS_UNSAFE_FLAG\*(C'\fR , \f(CW\*(C`rsignal\*(C'\fR
+, \f(CW\*(C`rsignal_state\*(C'\fR , \f(CW\*(C`Sigjmp_buf\*(C'\fR ,
+\&\f(CW\*(C`Siglongjmp\*(C'\fR , \f(CW\*(C`SIG_NAME\*(C'\fR , \f(CW\*(C`SIG_NUM\*(C'\fR
+, \f(CW\*(C`Sigsetjmp\*(C'\fR , \f(CW\*(C`SIG_SIZE\*(C'\fR ,
+\&\f(CW\*(C`whichsig\*(C'\fR, \f(CW\*(C`whichsig_pv\*(C'\fR, \f(CW\*(C`whichsig_pvn\*(C'\fR, \f(CW\*(C`whichsig_sv\*(C'\fR
+.IX Xref "HAS_SIGINFO_SI_ADDR HAS_SIGINFO_SI_BAND HAS_SIGINFO_SI_ERRNO HAS_SIGINFO_SI_PID HAS_SIGINFO_SI_STATUS HAS_SIGINFO_SI_UID HAS_SIGINFO_SI_VALUE PERL_SIGNALS_UNSAFE_FLAG rsignal rsignal_state Sigjmp_buf Siglongjmp SIG_NAME SIG_NUM Sigsetjmp SIG_SIZE whichsig whichsig_pv whichsig_pvn whichsig_sv"
+.IP "Site configuration" 4
+.IX Item "Site configuration"
+\&\f(CW\*(C`ARCHLIB\*(C'\fR , \f(CW\*(C`ARCHLIB_EXP\*(C'\fR , \f(CW\*(C`ARCHNAME\*(C'\fR
+, \f(CW\*(C`BIN\*(C'\fR , \f(CW\*(C`BIN_EXP\*(C'\fR , \f(CW\*(C`INSTALL_USR_BIN_PERL\*(C'\fR
+, \f(CW\*(C`MULTIARCH\*(C'\fR ,
+\&\f(CW\*(C`PERL_INC_VERSION_LIST\*(C'\fR , \f(CW\*(C`PERL_OTHERLIBDIRS\*(C'\fR
+, \f(CW\*(C`PERL_RELOCATABLE_INC\*(C'\fR ,
+\&\f(CW\*(C`PERL_TARGETARCH\*(C'\fR , \f(CW\*(C`PERL_USE_DEVEL\*(C'\fR ,
+\&\f(CW\*(C`PERL_VENDORARCH\*(C'\fR , \f(CW\*(C`PERL_VENDORARCH_EXP\*(C'\fR
+, \f(CW\*(C`PERL_VENDORLIB_EXP\*(C'\fR ,
+\&\f(CW\*(C`PERL_VENDORLIB_STEM\*(C'\fR , \f(CW\*(C`PRIVLIB\*(C'\fR ,
+\&\f(CW\*(C`PRIVLIB_EXP\*(C'\fR , \f(CW\*(C`SITEARCH\*(C'\fR , \f(CW\*(C`SITEARCH_EXP\*(C'\fR
+, \f(CW\*(C`SITELIB\*(C'\fR , \f(CW\*(C`SITELIB_EXP\*(C'\fR ,
+\&\f(CW\*(C`SITELIB_STEM\*(C'\fR , \f(CW\*(C`STARTPERL\*(C'\fR ,
+\&\f(CW\*(C`USE_64_BIT_ALL\*(C'\fR , \f(CW\*(C`USE_64_BIT_INT\*(C'\fR ,
+\&\f(CW\*(C`USE_BSD_GETPGRP\*(C'\fR , \f(CW\*(C`USE_BSD_SETPGRP\*(C'\fR
+, \f(CW\*(C`USE_C_BACKTRACE\*(C'\fR , \f(CW\*(C`USE_CPLUSPLUS\*(C'\fR
+, \f(CW\*(C`USE_CROSS_COMPILE\*(C'\fR , \f(CW\*(C`USE_DTRACE\*(C'\fR
+, \f(CW\*(C`USE_DYNAMIC_LOADING\*(C'\fR ,
+\&\f(CW\*(C`USE_FAST_STDIO\*(C'\fR , \f(CW\*(C`USE_ITHREADS\*(C'\fR ,
+\&\f(CW\*(C`USE_KERN_PROC_PATHNAME\*(C'\fR , \f(CW\*(C`USE_LARGE_FILES\*(C'\fR
+, \f(CW\*(C`USE_LONG_DOUBLE\*(C'\fR , \f(CW\*(C`USE_MORE_BITS\*(C'\fR
+, \f(CW\*(C`USE_NSGETEXECUTABLEPATH\*(C'\fR ,
+\&\f(CW\*(C`USE_PERLIO\*(C'\fR , \f(CW\*(C`USE_QUADMATH\*(C'\fR ,
+\&\f(CW\*(C`USE_REENTRANT_API\*(C'\fR , \f(CW\*(C`USE_SEMCTL_SEMID_DS\*(C'\fR
+, \f(CW\*(C`USE_SEMCTL_SEMUN\*(C'\fR ,
+\&\f(CW\*(C`USE_SITECUSTOMIZE\*(C'\fR , \f(CW\*(C`USE_SOCKS\*(C'\fR ,
+\&\f(CW\*(C`USE_STAT_BLOCKS\*(C'\fR , \f(CW\*(C`USE_STDIO_BASE\*(C'\fR ,
+\&\f(CW\*(C`USE_STDIO_PTR\*(C'\fR , \f(CW\*(C`USE_STRICT_BY_DEFAULT\*(C'\fR
+, \f(CW\*(C`USE_THREADS\*(C'\fR
+.IX Xref "ARCHLIB ARCHLIB_EXP ARCHNAME BIN BIN_EXP INSTALL_USR_BIN_PERL MULTIARCH PERL_INC_VERSION_LIST PERL_OTHERLIBDIRS PERL_RELOCATABLE_INC PERL_TARGETARCH PERL_USE_DEVEL PERL_VENDORARCH PERL_VENDORARCH_EXP PERL_VENDORLIB_EXP PERL_VENDORLIB_STEM PRIVLIB PRIVLIB_EXP SITEARCH SITEARCH_EXP SITELIB SITELIB_EXP SITELIB_STEM STARTPERL USE_64_BIT_ALL USE_64_BIT_INT USE_BSD_GETPGRP USE_BSD_SETPGRP USE_C_BACKTRACE USE_CPLUSPLUS USE_CROSS_COMPILE USE_DTRACE USE_DYNAMIC_LOADING USE_FAST_STDIO USE_ITHREADS USE_KERN_PROC_PATHNAME USE_LARGE_FILES USE_LONG_DOUBLE USE_MORE_BITS USE_NSGETEXECUTABLEPATH USE_PERLIO USE_QUADMATH USE_REENTRANT_API USE_SEMCTL_SEMID_DS USE_SEMCTL_SEMUN USE_SITECUSTOMIZE USE_SOCKS USE_STAT_BLOCKS USE_STDIO_BASE USE_STDIO_PTR USE_STRICT_BY_DEFAULT USE_THREADS"
+.IP "Sockets configuration values" 4
+.IX Item "Sockets configuration values"
+\&\f(CW\*(C`HAS_SOCKADDR_IN6\*(C'\fR , \f(CW\*(C`HAS_SOCKADDR_SA_LEN\*(C'\fR
+, \f(CW\*(C`HAS_SOCKADDR_STORAGE\*(C'\fR ,
+\&\f(CW\*(C`HAS_SOCKATMARK\*(C'\fR , \f(CW\*(C`HAS_SOCKET\*(C'\fR ,
+\&\f(CW\*(C`HAS_SOCKETPAIR\*(C'\fR , \f(CW\*(C`HAS_SOCKS5_INIT\*(C'\fR ,
+\&\f(CW\*(C`I_SOCKS\*(C'\fR , \f(CW\*(C`I_SYS_SOCKIO\*(C'\fR
+.IX Xref "HAS_SOCKADDR_IN6 HAS_SOCKADDR_SA_LEN HAS_SOCKADDR_STORAGE HAS_SOCKATMARK HAS_SOCKET HAS_SOCKETPAIR HAS_SOCKS5_INIT I_SOCKS I_SYS_SOCKIO"
+.IP "Source Filters" 4
+.IX Item "Source Filters"
+\&\f(CW\*(C`apply_builtin_cv_attributes\*(C'\fR ,
+\&\f(CW\*(C`filter_add\*(C'\fR, \f(CW\*(C`filter_del\*(C'\fR , \f(CW\*(C`filter_read\*(C'\fR, \f(CW\*(C`scan_vstring\*(C'\fR
+, \f(CW\*(C`start_subparse\*(C'\fR
+.IX Xref "apply_builtin_cv_attributes filter_del scan_vstring start_subparse"
+.IP "Stack Manipulation Macros" 4
+.IX Item "Stack Manipulation Macros"
+\&\f(CW\*(C`dMARK\*(C'\fR , \f(CW\*(C`dORIGMARK\*(C'\fR , \f(CW\*(C`dSP\*(C'\fR , \f(CW\*(C`dTARGET\*(C'\fR
+, \f(CW\*(C`EXTEND\*(C'\fR , \f(CW\*(C`MARK\*(C'\fR , \f(CW\*(C`mPUSHi\*(C'\fR ,
+\&\f(CW\*(C`mPUSHn\*(C'\fR , \f(CW\*(C`mPUSHp\*(C'\fR , \f(CW\*(C`mPUSHpvs\*(C'\fR ,
+\&\f(CW\*(C`mPUSHs\*(C'\fR , \f(CW\*(C`mPUSHu\*(C'\fR , \f(CW\*(C`mXPUSHi\*(C'\fR , \f(CW\*(C`mXPUSHn\*(C'\fR
+, \f(CW\*(C`mXPUSHp\*(C'\fR , \f(CW\*(C`mXPUSHpvs\*(C'\fR , \f(CW\*(C`mXPUSHs\*(C'\fR
+, \f(CW\*(C`mXPUSHu\*(C'\fR , \f(CW\*(C`newXSproto\*(C'\fR , \f(CW\*(C`ORIGMARK\*(C'\fR
+, \f(CW\*(C`PL_markstack\*(C'\fR, \f(CW\*(C`PL_markstack_ptr\*(C'\fR, \f(CW\*(C`PL_savestack\*(C'\fR,
+\&\f(CW\*(C`PL_savestack_ix\*(C'\fR, \f(CW\*(C`PL_scopestack\*(C'\fR, \f(CW\*(C`PL_scopestack_ix\*(C'\fR,
+\&\f(CW\*(C`PL_scopestack_name\*(C'\fR, \f(CW\*(C`PL_stack_base\*(C'\fR, \f(CW\*(C`PL_stack_sp\*(C'\fR, \f(CW\*(C`PL_tmps_floor\*(C'\fR,
+\&\f(CW\*(C`PL_tmps_ix\*(C'\fR, \f(CW\*(C`PL_tmps_stack\*(C'\fR, \f(CW\*(C`POPi\*(C'\fR , \f(CW\*(C`POPl\*(C'\fR , \f(CW\*(C`POPn\*(C'\fR
+, \f(CW\*(C`POPp\*(C'\fR , \f(CW\*(C`POPpbytex\*(C'\fR , \f(CW\*(C`POPpx\*(C'\fR ,
+\&\f(CW\*(C`POPs\*(C'\fR , \f(CW\*(C`POPu\*(C'\fR , \f(CW\*(C`POPul\*(C'\fR , \f(CW\*(C`PUSHi\*(C'\fR ,
+\&\f(CW\*(C`PUSHMARK\*(C'\fR , \f(CW\*(C`PUSHmortal\*(C'\fR , \f(CW\*(C`PUSHn\*(C'\fR ,
+\&\f(CW\*(C`PUSHp\*(C'\fR , \f(CW\*(C`PUSHpvs\*(C'\fR , \f(CW\*(C`PUSHs\*(C'\fR , \f(CW\*(C`PUSHu\*(C'\fR
+, \f(CW\*(C`PUTBACK\*(C'\fR , \f(CW\*(C`SAVEt_INT\*(C'\fR, \f(CW\*(C`SP\*(C'\fR , \f(CW\*(C`SPAGAIN\*(C'\fR
+, \f(CW\*(C`SSNEW\*(C'\fR, \f(CW\*(C`SSNEWa\*(C'\fR, \f(CW\*(C`SSNEWat\*(C'\fR, \f(CW\*(C`SSNEWt\*(C'\fR
+, \f(CW\*(C`SSPTR\*(C'\fR, \f(CW\*(C`SSPTRt\*(C'\fR
+, \f(CW\*(C`TARG\*(C'\fR , \f(CW\*(C`TOPs\*(C'\fR, \f(CW\*(C`XPUSHi\*(C'\fR ,
+\&\f(CW\*(C`XPUSHmortal\*(C'\fR , \f(CW\*(C`XPUSHn\*(C'\fR , \f(CW\*(C`XPUSHp\*(C'\fR ,
+\&\f(CW\*(C`XPUSHpvs\*(C'\fR , \f(CW\*(C`XPUSHs\*(C'\fR , \f(CW\*(C`XPUSHu\*(C'\fR ,
+\&\f(CW\*(C`XS_APIVERSION_BOOTCHECK\*(C'\fR , \f(CW\*(C`XSRETURN\*(C'\fR
+, \f(CW\*(C`XSRETURN_EMPTY\*(C'\fR , \f(CW\*(C`XSRETURN_IV\*(C'\fR
+, \f(CW\*(C`XSRETURN_NO\*(C'\fR , \f(CW\*(C`XSRETURN_NV\*(C'\fR
+, \f(CW\*(C`XSRETURN_PV\*(C'\fR , \f(CW\*(C`XSRETURN_UNDEF\*(C'\fR
+, \f(CW\*(C`XSRETURN_UV\*(C'\fR , \f(CW\*(C`XSRETURN_YES\*(C'\fR
+, \f(CW\*(C`XST_mIV\*(C'\fR , \f(CW\*(C`XST_mNO\*(C'\fR , \f(CW\*(C`XST_mNV\*(C'\fR
+, \f(CW\*(C`XST_mPV\*(C'\fR , \f(CW\*(C`XST_mUNDEF\*(C'\fR , \f(CW\*(C`XST_mUV\*(C'\fR
+, \f(CW\*(C`XST_mYES\*(C'\fR , \f(CW\*(C`XS_VERSION\*(C'\fR ,
+\&\f(CW\*(C`XS_VERSION_BOOTCHECK\*(C'\fR
+.IX Xref "dMARK dORIGMARK dSP dTARGET EXTEND MARK mPUSHi mPUSHn mPUSHp mPUSHpvs mPUSHs mPUSHu mXPUSHi mXPUSHn mXPUSHp mXPUSHpvs mXPUSHs mXPUSHu newXSproto ORIGMARK POPi POPl POPn POPp POPpbytex POPpx POPs POPu POPul PUSHi PUSHMARK PUSHmortal PUSHn PUSHp PUSHpvs PUSHs PUSHu PUTBACK SP SPAGAIN SSNEW SSNEWa SSNEWat SSNEWt SSPTR SSPTRt TARG XPUSHi XPUSHmortal XPUSHn XPUSHp XPUSHpvs XPUSHs XPUSHu XS_APIVERSION_BOOTCHECK XSRETURN XSRETURN_EMPTY XSRETURN_IV XSRETURN_NO XSRETURN_NV XSRETURN_PV XSRETURN_UNDEF XSRETURN_UV XSRETURN_YES XST_mIV XST_mNO XST_mNV XST_mPV XST_mUNDEF XST_mUV XST_mYES XS_VERSION XS_VERSION_BOOTCHECK"
+.IP "String Handling" 4
+.IX Item "String Handling"
+\&\f(CW\*(C`CAT2\*(C'\fR , \f(CW\*(C`Copy\*(C'\fR, \f(CW\*(C`CopyD\*(C'\fR , \f(CW\*(C`delimcpy\*(C'\fR
+, \f(CW\*(C`do_join\*(C'\fR , \f(CW\*(C`do_sprintf\*(C'\fR ,
+\&\f(CW\*(C`fbm_compile\*(C'\fR , \f(CW\*(C`fbm_instr\*(C'\fR , \f(CW\*(C`foldEQ\*(C'\fR
+, \f(CW\*(C`ibcmp\*(C'\fR , \f(CW\*(C`ibcmp_locale\*(C'\fR ,
+\&\f(CW\*(C`ibcmp_utf8\*(C'\fR , \f(CW\*(C`instr\*(C'\fR , \f(CW\*(C`memCHRs\*(C'\fR ,
+\&\f(CW\*(C`memEQ\*(C'\fR , \f(CW\*(C`memEQs\*(C'\fR , \f(CW\*(C`memNE\*(C'\fR , \f(CW\*(C`memNEs\*(C'\fR
+, \f(CW\*(C`Move\*(C'\fR, \f(CW\*(C`MoveD\*(C'\fR , \f(CW\*(C`my_snprintf\*(C'\fR
+, \f(CW\*(C`my_sprintf\*(C'\fR , \f(CW\*(C`my_strnlen\*(C'\fR ,
+\&\f(CW\*(C`my_vsnprintf\*(C'\fR , \f(CW\*(C`NewCopy\*(C'\fR , \f(CW\*(C`ninstr\*(C'\fR
+, \f(CW\*(C`Nullch\*(C'\fR , \f(CW\*(C`PL_na\*(C'\fR , \f(CW\*(C`rninstr\*(C'\fR ,
+\&\f(CW\*(C`savepv\*(C'\fR , \f(CW\*(C`savepvn\*(C'\fR , \f(CW\*(C`savepvs\*(C'\fR ,
+\&\f(CW\*(C`savesharedpv\*(C'\fR , \f(CW\*(C`savesharedpvn\*(C'\fR ,
+\&\f(CW\*(C`savesharedpvs\*(C'\fR , \f(CW\*(C`savesharedsvpv\*(C'\fR ,
+\&\f(CW\*(C`savesvpv\*(C'\fR , \f(CW\*(C`strEQ\*(C'\fR , \f(CW\*(C`strGE\*(C'\fR , \f(CW\*(C`strGT\*(C'\fR
+, \f(CW\*(C`STRINGIFY\*(C'\fR , \f(CW\*(C`strLE\*(C'\fR , \f(CW\*(C`STRLEN\*(C'\fR, \f(CW\*(C`strLT\*(C'\fR
+, \f(CW\*(C`strNE\*(C'\fR , \f(CW\*(C`strnEQ\*(C'\fR , \f(CW\*(C`strnNE\*(C'\fR ,
+\&\f(CW\*(C`STR_WITH_LEN\*(C'\fR , \f(CW\*(C`Zero\*(C'\fR, \f(CW\*(C`ZeroD\*(C'\fR
+.IX Xref "CAT2 Copy CopyD delimcpy do_join do_sprintf fbm_compile fbm_instr foldEQ ibcmp ibcmp_locale ibcmp_utf8 instr memCHRs memEQ memEQs memNE memNEs Move MoveD my_snprintf my_sprintf my_strnlen my_vsnprintf NewCopy ninstr Nullch PL_na rninstr savepv savepvn savepvs savesharedpv savesharedpvn savesharedpvs savesharedsvpv savesvpv strEQ strGE strGT STRINGIFY strLE strLT strNE strnEQ strnNE STR_WITH_LEN Zero ZeroD"
+.IP "SV Flags" 4
+.IX Item "SV Flags"
+\&\f(CW\*(C`SVt_IV\*(C'\fR , \f(CW\*(C`SVt_NULL\*(C'\fR , \f(CW\*(C`SVt_NV\*(C'\fR ,
+\&\f(CW\*(C`SVt_PV\*(C'\fR , \f(CW\*(C`SVt_PVAV\*(C'\fR , \f(CW\*(C`SVt_PVCV\*(C'\fR ,
+\&\f(CW\*(C`SVt_PVFM\*(C'\fR , \f(CW\*(C`SVt_PVGV\*(C'\fR , \f(CW\*(C`SVt_PVHV\*(C'\fR ,
+\&\f(CW\*(C`SVt_PVIO\*(C'\fR , \f(CW\*(C`SVt_PVIV\*(C'\fR , \f(CW\*(C`SVt_PVLV\*(C'\fR ,
+\&\f(CW\*(C`SVt_PVMG\*(C'\fR , \f(CW\*(C`SVt_PVNV\*(C'\fR , \f(CW\*(C`SVt_PVOBJ\*(C'\fR
+, \f(CW\*(C`SVt_REGEXP\*(C'\fR , \f(CW\*(C`svtype\*(C'\fR
+.IX Xref "SVt_IV SVt_NULL SVt_NV SVt_PV SVt_PVAV SVt_PVCV SVt_PVFM SVt_PVGV SVt_PVHV SVt_PVIO SVt_PVIV SVt_PVLV SVt_PVMG SVt_PVNV SVt_PVOBJ SVt_REGEXP svtype"
+.IP "SV Handling" 4
+.IX Xref "SV_CATBYTES SV_CATUTF8 SV_COW_DROP_PV SV_FORCE_UTF8_UPGRADE SV_GM AGIC SV_HAS_TRAILING_NUL SV_IMMEDIATE_UNREF SV_NOSTEAL SV_SMAGIC SV_UTF8_NO_ENCODING SVs_TEMP"
+.IX Item "SV Handling"
+\&\f(CW\*(C`AV_FROM_REF\*(C'\fR, \f(CW\*(C`CV_FROM_REF\*(C'\fR, \f(CW\*(C`HV_FROM_REF\*(C'\fR
+, \f(CW\*(C`BOOL_INTERNALS_sv_isbool\*(C'\fR
+, \f(CW\*(C`BOOL_INTERNALS_sv_isbool_false\*(C'\fR
+, \f(CW\*(C`BOOL_INTERNALS_sv_isbool_true\*(C'\fR
+, \f(CW\*(C`boolSV\*(C'\fR , \f(CW\*(C`croak_xs_usage\*(C'\fR
+, \f(CW\*(C`DEFSV\*(C'\fR , \f(CW\*(C`DEFSV_set\*(C'\fR , \f(CW\*(C`get_sv\*(C'\fR
+, \f(CW\*(C`isGV_with_GP\*(C'\fR , \f(CW\*(C`looks_like_number\*(C'\fR
+, \f(CW\*(C`MUTABLE_AV\*(C'\fR, \f(CW\*(C`MUTABLE_CV\*(C'\fR, \f(CW\*(C`MUTABLE_GV\*(C'\fR,
+\&\f(CW\*(C`MUTABLE_HV\*(C'\fR, \f(CW\*(C`MUTABLE_IO\*(C'\fR, \f(CW\*(C`MUTABLE_PTR\*(C'\fR, \f(CW\*(C`MUTABLE_SV\*(C'\fR
+, \f(CW\*(C`newRV\*(C'\fR, \f(CW\*(C`newRV_inc\*(C'\fR ,
+\&\f(CW\*(C`newRV_noinc\*(C'\fR , \f(CW\*(C`newSV\*(C'\fR , \f(CW\*(C`newSVbool\*(C'\fR
+, \f(CW\*(C`newSV_false\*(C'\fR , \f(CW\*(C`newSVhek\*(C'\fR ,
+\&\f(CW\*(C`newSVhek_mortal\*(C'\fR , \f(CW\*(C`newSViv\*(C'\fR , \f(CW\*(C`newSVnv\*(C'\fR
+, \f(CW\*(C`newSVpadname\*(C'\fR , \f(CW\*(C`newSVpv\*(C'\fR ,
+\&\f(CW\*(C`newSVpvf\*(C'\fR , \f(CW\*(C`newSVpvf_nocontext\*(C'\fR ,
+\&\f(CW\*(C`newSVpvn\*(C'\fR , \f(CW\*(C`newSVpvn_flags\*(C'\fR ,
+\&\f(CW\*(C`newSVpvn_share\*(C'\fR , \f(CW\*(C`newSVpvn_utf8\*(C'\fR ,
+\&\f(CW\*(C`newSVpvs\*(C'\fR , \f(CW\*(C`newSVpvs_flags\*(C'\fR ,
+\&\f(CW\*(C`newSVpv_share\*(C'\fR , \f(CW\*(C`newSVpvs_share\*(C'\fR ,
+\&\f(CW\*(C`newSVrv\*(C'\fR , \f(CW\*(C`newSVsv\*(C'\fR, \f(CW\*(C`newSVsv_flags\*(C'\fR, \f(CW\*(C`newSVsv_nomg\*(C'\fR
+, \f(CW\*(C`newSV_true\*(C'\fR ,
+\&\f(CW\*(C`newSV_type\*(C'\fR , \f(CW\*(C`newSV_type_mortal\*(C'\fR ,
+\&\f(CW\*(C`newSVuv\*(C'\fR , \f(CW\*(C`Nullsv\*(C'\fR , \f(CW\*(C`PL_sv_no\*(C'\fR ,
+\&\f(CW\*(C`PL_sv_undef\*(C'\fR , \f(CW\*(C`PL_sv_yes\*(C'\fR , \f(CW\*(C`PL_sv_zero\*(C'\fR
+, \f(CW\*(C`SAVE_DEFSV\*(C'\fR , \f(CW\*(C`sortsv\*(C'\fR ,
+\&\f(CW\*(C`sortsv_flags\*(C'\fR , \f(CW\*(C`SV\*(C'\fR, \f(CW\*(C`SvAMAGIC\*(C'\fR ,
+\&\f(CW\*(C`SvAMAGIC_off\*(C'\fR , \f(CW\*(C`SvAMAGIC_on\*(C'\fR ,
+\&\f(CW\*(C`sv_backoff\*(C'\fR , \f(CW\*(C`sv_bless\*(C'\fR , \f(CW\*(C`SvBoolFlagsOK\*(C'\fR
+, \f(CW\*(C`sv_catpv\*(C'\fR, \f(CW\*(C`sv_catpv_flags\*(C'\fR, \f(CW\*(C`sv_catpv_mg\*(C'\fR,
+\&\f(CW\*(C`sv_catpv_nomg\*(C'\fR
+, \f(CW\*(C`sv_catpvf\*(C'\fR,
+\&\f(CW\*(C`sv_catpvf_mg\*(C'\fR, \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR, \f(CW\*(C`sv_catpvf_nocontext\*(C'\fR
+,
+\&\f(CW\*(C`sv_catpvn\*(C'\fR, \f(CW\*(C`sv_catpvn_flags\*(C'\fR, \f(CW\*(C`sv_catpvn_mg\*(C'\fR, \f(CW\*(C`sv_catpvn_nomg\*(C'\fR
+,
+\&\f(CW\*(C`sv_catpvs\*(C'\fR , \f(CW\*(C`sv_catpvs_flags\*(C'\fR ,
+\&\f(CW\*(C`sv_catpvs_mg\*(C'\fR , \f(CW\*(C`sv_catpvs_nomg\*(C'\fR ,
+\&\f(CW\*(C`sv_catsv\*(C'\fR, \f(CW\*(C`sv_catsv_flags\*(C'\fR, \f(CW\*(C`sv_catsv_mg\*(C'\fR, \f(CW\*(C`sv_catsv_nomg\*(C'\fR
+,
+\&\f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR ,
+\&\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR , \f(CW\*(C`sv_chop\*(C'\fR
+, \f(CW\*(C`sv_clear\*(C'\fR , \f(CW\*(C`sv_cmp\*(C'\fR , \f(CW\*(C`sv_cmp_flags\*(C'\fR
+, \f(CW\*(C`sv_cmp_locale\*(C'\fR , \f(CW\*(C`sv_cmp_locale_flags\*(C'\fR
+, \f(CW\*(C`sv_collxfrm\*(C'\fR , \f(CW\*(C`sv_collxfrm_flags\*(C'\fR
+, \f(CW\*(C`sv_copypv\*(C'\fR, \f(CW\*(C`sv_copypv_flags\*(C'\fR, \f(CW\*(C`sv_copypv_nomg\*(C'\fR
+, \f(CW\*(C`SvCUR\*(C'\fR ,
+\&\f(CW\*(C`SvCUR_set\*(C'\fR , \f(CW\*(C`sv_2cv\*(C'\fR , \f(CW\*(C`sv_dec\*(C'\fR, \f(CW\*(C`sv_dec_nomg\*(C'\fR
+, \f(CW\*(C`sv_derived_from\*(C'\fR ,
+\&\f(CW\*(C`sv_derived_from_hv\*(C'\fR , \f(CW\*(C`sv_derived_from_pv\*(C'\fR
+, \f(CW\*(C`sv_derived_from_pvn\*(C'\fR ,
+\&\f(CW\*(C`sv_derived_from_sv\*(C'\fR , \f(CW\*(C`sv_does\*(C'\fR ,
+\&\f(CW\*(C`sv_does_pv\*(C'\fR , \f(CW\*(C`sv_does_pvn\*(C'\fR , \f(CW\*(C`sv_does_sv\*(C'\fR
+, \f(CW\*(C`SvEND\*(C'\fR , \f(CW\*(C`sv_eq\*(C'\fR , \f(CW\*(C`sv_eq_flags\*(C'\fR
+, \f(CW\*(C`sv_force_normal\*(C'\fR ,
+\&\f(CW\*(C`sv_force_normal_flags\*(C'\fR , \f(CW\*(C`sv_free\*(C'\fR ,
+\&\f(CW\*(C`SvGAMAGIC\*(C'\fR , \f(CW\*(C`sv_get_backrefs\*(C'\fR ,
+\&\f(CW\*(C`SvGETMAGIC\*(C'\fR , \f(CW\*(C`sv_gets\*(C'\fR , \f(CW\*(C`SvGROW\*(C'\fR ,
+\&\f(CW\*(C`SvIandPOK\*(C'\fR , \f(CW\*(C`SvIandPOK_off\*(C'\fR ,
+\&\f(CW\*(C`SvIandPOK_on\*(C'\fR , \f(CW\*(C`sv_inc\*(C'\fR, \f(CW\*(C`sv_inc_nomg\*(C'\fR
+, \f(CW\*(C`sv_insert\*(C'\fR , \f(CW\*(C`sv_insert_flags\*(C'\fR
+, \f(CW\*(C`sv_2io\*(C'\fR , \f(CW\*(C`SvIOK\*(C'\fR , \f(CW\*(C`SvIOK_notUV\*(C'\fR
+, \f(CW\*(C`SvIOK_off\*(C'\fR , \f(CW\*(C`SvIOK_on\*(C'\fR ,
+\&\f(CW\*(C`SvIOK_only\*(C'\fR , \f(CW\*(C`SvIOK_only_UV\*(C'\fR , \f(CW\*(C`SvIOKp\*(C'\fR
+, \f(CW\*(C`SvIOK_UV\*(C'\fR , \f(CW\*(C`sv_isa\*(C'\fR , \f(CW\*(C`sv_isa_sv\*(C'\fR
+, \f(CW\*(C`SvIsBOOL\*(C'\fR , \f(CW\*(C`SvIsCOW\*(C'\fR ,
+\&\f(CW\*(C`SvIsCOW_shared_hash\*(C'\fR , \f(CW\*(C`sv_isobject\*(C'\fR
+, \f(CW\*(C`SvIV\*(C'\fR, \f(CW\*(C`SvIV_nomg\*(C'\fR, \f(CW\*(C`SvIVx\*(C'\fR
+, \f(CW\*(C`sv_2iv_flags\*(C'\fR , \f(CW\*(C`SvIV_set\*(C'\fR
+, \f(CW\*(C`SvIVX\*(C'\fR , \f(CW\*(C`SvLEN\*(C'\fR , \f(CW\*(C`sv_len\*(C'\fR ,
+\&\f(CW\*(C`SvLEN_set\*(C'\fR , \f(CW\*(C`sv_len_utf8\*(C'\fR, \f(CW\*(C`sv_len_utf8_nomg\*(C'\fR
+, \f(CW\*(C`SvLOCK\*(C'\fR , \f(CW\*(C`sv_magic\*(C'\fR
+, \f(CW\*(C`sv_magicext\*(C'\fR , \f(CW\*(C`SvMAGIC_set\*(C'\fR ,
+\&\f(CW\*(C`sv_2mortal\*(C'\fR , \f(CW\*(C`sv_mortalcopy\*(C'\fR ,
+\&\f(CW\*(C`sv_mortalcopy_flags\*(C'\fR , \f(CW\*(C`sv_newmortal\*(C'\fR
+, \f(CW\*(C`SvNIOK\*(C'\fR , \f(CW\*(C`SvNIOK_off\*(C'\fR ,
+\&\f(CW\*(C`SvNIOKp\*(C'\fR , \f(CW\*(C`SvNOK\*(C'\fR , \f(CW\*(C`SvNOK_off\*(C'\fR ,
+\&\f(CW\*(C`SvNOK_on\*(C'\fR , \f(CW\*(C`SvNOK_only\*(C'\fR , \f(CW\*(C`SvNOKp\*(C'\fR ,
+\&\f(CW\*(C`sv_nolocking\*(C'\fR , \f(CW\*(C`sv_nounlocking\*(C'\fR ,
+\&\f(CW\*(C`sv_numeq\*(C'\fR , \f(CW\*(C`sv_numeq_flags\*(C'\fR , \f(CW\*(C`SvNV\*(C'\fR,
+\&\f(CW\*(C`SvNV_nomg\*(C'\fR, \f(CW\*(C`SvNVx\*(C'\fR , \f(CW\*(C`sv_2nv_flags\*(C'\fR
+, \f(CW\*(C`SvNV_set\*(C'\fR , \f(CW\*(C`SvNVX\*(C'\fR , \f(CW\*(C`SvOK\*(C'\fR
+, \f(CW\*(C`SvOOK\*(C'\fR , \f(CW\*(C`SvOOK_off\*(C'\fR , \f(CW\*(C`SvOOK_offset\*(C'\fR
+, \f(CW\*(C`SvPOK\*(C'\fR , \f(CW\*(C`SvPOK_off\*(C'\fR , \f(CW\*(C`SvPOK_on\*(C'\fR
+, \f(CW\*(C`SvPOK_only\*(C'\fR , \f(CW\*(C`SvPOK_only_UTF8\*(C'\fR
+, \f(CW\*(C`SvPOKp\*(C'\fR , \f(CW\*(C`sv_pos_b2u\*(C'\fR ,
+\&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR , \f(CW\*(C`sv_pos_u2b\*(C'\fR ,
+\&\f(CW\*(C`sv_pos_u2b_flags\*(C'\fR , \f(CW\*(C`SvPV\*(C'\fR, \f(CW\*(C`SvPV_const\*(C'\fR,
+\&\f(CW\*(C`SvPV_flags\*(C'\fR, \f(CW\*(C`SvPV_flags_const\*(C'\fR, \f(CW\*(C`SvPV_flags_mutable\*(C'\fR, \f(CW\*(C`SvPV_mutable\*(C'\fR,
+\&\f(CW\*(C`SvPV_nolen\*(C'\fR, \f(CW\*(C`SvPV_nolen_const\*(C'\fR, \f(CW\*(C`SvPV_nomg\*(C'\fR, \f(CW\*(C`SvPV_nomg_const\*(C'\fR,
+\&\f(CW\*(C`SvPV_nomg_const_nolen\*(C'\fR, \f(CW\*(C`SvPV_nomg_nolen\*(C'\fR, \f(CW\*(C`SvPVbyte\*(C'\fR,
+\&\f(CW\*(C`SvPVbyte_nolen\*(C'\fR, \f(CW\*(C`SvPVbyte_nomg\*(C'\fR, \f(CW\*(C`SvPVbyte_or_null\*(C'\fR,
+\&\f(CW\*(C`SvPVbyte_or_null_nomg\*(C'\fR, \f(CW\*(C`SvPVbytex\*(C'\fR, \f(CW\*(C`SvPVbytex_nolen\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR,
+\&\f(CW\*(C`SvPVutf8_nolen\*(C'\fR, \f(CW\*(C`SvPVutf8_nomg\*(C'\fR, \f(CW\*(C`SvPVutf8_or_null\*(C'\fR,
+\&\f(CW\*(C`SvPVutf8_or_null_nomg\*(C'\fR, \f(CW\*(C`SvPVutf8x\*(C'\fR, \f(CW\*(C`SvPVx\*(C'\fR, \f(CW\*(C`SvPVx_const\*(C'\fR,
+\&\f(CW\*(C`SvPVx_nolen\*(C'\fR, \f(CW\*(C`SvPVx_nolen_const\*(C'\fR
+
+, \f(CW\*(C`sv_2pv\*(C'\fR, \f(CW\*(C`sv_2pv_flags\*(C'\fR ,
+\&\f(CW\*(C`sv_2pvbyte\*(C'\fR, \f(CW\*(C`sv_2pvbyte_flags\*(C'\fR ,
+\&\f(CW\*(C`SvPVCLEAR\*(C'\fR , \f(CW\*(C`SvPVCLEAR_FRESH\*(C'\fR ,
+\&\f(CW\*(C`SvPV_force\*(C'\fR, \f(CW\*(C`SvPV_force_flags\*(C'\fR, \f(CW\*(C`SvPV_force_flags_mutable\*(C'\fR,
+\&\f(CW\*(C`SvPV_force_flags_nolen\*(C'\fR, \f(CW\*(C`SvPV_force_mutable\*(C'\fR, \f(CW\*(C`SvPV_force_nolen\*(C'\fR,
+\&\f(CW\*(C`SvPV_force_nomg\*(C'\fR, \f(CW\*(C`SvPV_force_nomg_nolen\*(C'\fR, \f(CW\*(C`SvPVbyte_force\*(C'\fR,
+\&\f(CW\*(C`SvPVbytex_force\*(C'\fR, \f(CW\*(C`SvPVutf8_force\*(C'\fR, \f(CW\*(C`SvPVutf8x_force\*(C'\fR, \f(CW\*(C`SvPVx_force\*(C'\fR
+, \f(CW\*(C`SvPV_free\*(C'\fR , \f(CW\*(C`sv_pvn_force_flags\*(C'\fR
+, \f(CW\*(C`SvPV_renew\*(C'\fR , \f(CW\*(C`SvPV_set\*(C'\fR
+, \f(CW\*(C`SvPV_shrink_to_cur\*(C'\fR , \f(CW\*(C`sv_2pvutf8\*(C'\fR,
+\&\f(CW\*(C`sv_2pvutf8_flags\*(C'\fR , \f(CW\*(C`SvPVX\*(C'\fR,
+\&\f(CW\*(C`SvPVX_const\*(C'\fR, \f(CW\*(C`SvPVX_mutable\*(C'\fR, \f(CW\*(C`SvPVXx\*(C'\fR
+, \f(CW\*(C`SvPVXtrue\*(C'\fR ,
+\&\f(CW\*(C`SvREADONLY\*(C'\fR , \f(CW\*(C`SvREADONLY_off\*(C'\fR ,
+\&\f(CW\*(C`SvREADONLY_on\*(C'\fR , \f(CW\*(C`sv_ref\*(C'\fR , \f(CW\*(C`SvREFCNT\*(C'\fR
+, \f(CW\*(C`SvREFCNT_dec\*(C'\fR, \f(CW\*(C`SvREFCNT_dec_set_NULL\*(C'\fR,
+\&\f(CW\*(C`SvREFCNT_dec_ret_NULL\*(C'\fR, \f(CW\*(C`SvREFCNT_dec_NN\*(C'\fR
+, \f(CW\*(C`SvREFCNT_inc\*(C'\fR, \f(CW\*(C`SvREFCNT_inc_NN\*(C'\fR, \f(CW\*(C`SvREFCNT_inc_simple\*(C'\fR,
+\&\f(CW\*(C`SvREFCNT_inc_simple_NN\*(C'\fR, \f(CW\*(C`SvREFCNT_inc_simple_void\*(C'\fR,
+\&\f(CW\*(C`SvREFCNT_inc_simple_void_NN\*(C'\fR, \f(CW\*(C`SvREFCNT_inc_void\*(C'\fR,
+\&\f(CW\*(C`SvREFCNT_inc_void_NN\*(C'\fR
+, \f(CW\*(C`sv_reftype\*(C'\fR , \f(CW\*(C`sv_replace\*(C'\fR
+, \f(CW\*(C`sv_report_used\*(C'\fR , \f(CW\*(C`sv_reset\*(C'\fR
+, \f(CW\*(C`SvROK\*(C'\fR , \f(CW\*(C`SvROK_off\*(C'\fR , \f(CW\*(C`SvROK_on\*(C'\fR
+, \f(CW\*(C`SvRV\*(C'\fR , \f(CW\*(C`SvRV_set\*(C'\fR , \f(CW\*(C`sv_rvunweaken\*(C'\fR
+, \f(CW\*(C`sv_rvweaken\*(C'\fR , \f(CW\*(C`sv_setbool\*(C'\fR,
+\&\f(CW\*(C`sv_setbool_mg\*(C'\fR , \f(CW\*(C`sv_set_bool\*(C'\fR
+, \f(CW\*(C`sv_set_false\*(C'\fR , \f(CW\*(C`sv_setiv\*(C'\fR,
+\&\f(CW\*(C`sv_setiv_mg\*(C'\fR , \f(CW\*(C`SvSETMAGIC\*(C'\fR ,
+\&\f(CW\*(C`SvSetMagicSV\*(C'\fR, \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR, \f(CW\*(C`SvSetSV\*(C'\fR, \f(CW\*(C`SvSetSV_nosteal\*(C'\fR
+,
+\&\f(CW\*(C`sv_setnv\*(C'\fR, \f(CW\*(C`sv_setnv_mg\*(C'\fR , \f(CW\*(C`sv_setpv\*(C'\fR,
+\&\f(CW\*(C`sv_setpv_mg\*(C'\fR, \f(CW\*(C`sv_setpvn\*(C'\fR, \f(CW\*(C`sv_setpvn_fresh\*(C'\fR, \f(CW\*(C`sv_setpvn_mg\*(C'\fR,
+\&\f(CW\*(C`sv_setpvs\*(C'\fR, \f(CW\*(C`sv_setpvs_mg\*(C'\fR
+, \f(CW\*(C`sv_setpv_bufsize\*(C'\fR ,
+\&\f(CW\*(C`sv_setpvf\*(C'\fR, \f(CW\*(C`sv_setpvf_mg\*(C'\fR, \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR,
+\&\f(CW\*(C`sv_setpvf_nocontext\*(C'\fR
+,
+\&\f(CW\*(C`sv_setref_iv\*(C'\fR , \f(CW\*(C`sv_setref_nv\*(C'\fR ,
+\&\f(CW\*(C`sv_setref_pv\*(C'\fR , \f(CW\*(C`sv_setref_pvn\*(C'\fR ,
+\&\f(CW\*(C`sv_setref_pvs\*(C'\fR , \f(CW\*(C`sv_setref_uv\*(C'\fR ,
+\&\f(CW\*(C`sv_setrv_inc\*(C'\fR, \f(CW\*(C`sv_setrv_inc_mg\*(C'\fR ,
+\&\f(CW\*(C`sv_setrv_noinc\*(C'\fR, \f(CW\*(C`sv_setrv_noinc_mg\*(C'\fR
+, \f(CW\*(C`sv_setsv\*(C'\fR, \f(CW\*(C`sv_setsv_flags\*(C'\fR,
+\&\f(CW\*(C`sv_setsv_mg\*(C'\fR, \f(CW\*(C`sv_setsv_nomg\*(C'\fR
+, \f(CW\*(C`sv_set_true\*(C'\fR
+, \f(CW\*(C`sv_set_undef\*(C'\fR , \f(CW\*(C`sv_setuv\*(C'\fR,
+\&\f(CW\*(C`sv_setuv_mg\*(C'\fR , \f(CW\*(C`SvSHARE\*(C'\fR ,
+\&\f(CW\*(C`SvSHARED_HASH\*(C'\fR , \f(CW\*(C`SvSTASH\*(C'\fR , \f(CW\*(C`SvSTASH_set\*(C'\fR
+, \f(CW\*(C`sv_streq\*(C'\fR , \f(CW\*(C`sv_streq_flags\*(C'\fR
+, \f(CW\*(C`SvTRUE\*(C'\fR, \f(CW\*(C`SvTRUE_NN\*(C'\fR, \f(CW\*(C`SvTRUE_nomg\*(C'\fR,
+\&\f(CW\*(C`SvTRUE_nomg_NN\*(C'\fR, \f(CW\*(C`SvTRUEx\*(C'\fR
+, \f(CW\*(C`SvTYPE\*(C'\fR
+, \f(CW\*(C`SvUNLOCK\*(C'\fR , \f(CW\*(C`sv_unmagic\*(C'\fR ,
+\&\f(CW\*(C`sv_unmagicext\*(C'\fR , \f(CW\*(C`sv_unref\*(C'\fR ,
+\&\f(CW\*(C`sv_unref_flags\*(C'\fR , \f(CW\*(C`SvUOK\*(C'\fR , \f(CW\*(C`SvUPGRADE\*(C'\fR
+, \f(CW\*(C`sv_upgrade\*(C'\fR , \f(CW\*(C`sv_usepvn\*(C'\fR,
+\&\f(CW\*(C`sv_usepvn_flags\*(C'\fR, \f(CW\*(C`sv_usepvn_mg\*(C'\fR
+, \f(CW\*(C`sv_utf8_decode\*(C'\fR
+, \f(CW\*(C`sv_utf8_downgrade\*(C'\fR, \f(CW\*(C`sv_utf8_downgrade_flags\*(C'\fR,
+\&\f(CW\*(C`sv_utf8_downgrade_nomg\*(C'\fR
+,
+\&\f(CW\*(C`sv_utf8_encode\*(C'\fR , \f(CW\*(C`SvUTF8_off\*(C'\fR ,
+\&\f(CW\*(C`SvUTF8_on\*(C'\fR , \f(CW\*(C`sv_utf8_upgrade\*(C'\fR, \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR,
+\&\f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR, \f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR
+, \f(CW\*(C`SvUTF8\*(C'\fR , \f(CW\*(C`SvUV\*(C'\fR, \f(CW\*(C`SvUV_nomg\*(C'\fR, \f(CW\*(C`SvUVx\*(C'\fR
+, \f(CW\*(C`sv_2uv_flags\*(C'\fR , \f(CW\*(C`SvUV_set\*(C'\fR
+, \f(CW\*(C`SvUVX\*(C'\fR , \f(CW\*(C`SvUVXx\*(C'\fR , \f(CW\*(C`sv_vcatpvf\*(C'\fR,
+\&\f(CW\*(C`sv_vcatpvf_mg\*(C'\fR , \f(CW\*(C`sv_vcatpvfn\*(C'\fR,
+\&\f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR , \f(CW\*(C`SvVOK\*(C'\fR ,
+\&\f(CW\*(C`sv_vsetpvf\*(C'\fR, \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR ,
+\&\f(CW\*(C`sv_vsetpvfn\*(C'\fR , \f(CW\*(C`SvVSTRING_mg\*(C'\fR ,
+\&\f(CW\*(C`vnewSVpvf\*(C'\fR
+.IX Xref "AV_FROM_REF CV_FROM_REF HV_FROM_REF BOOL_INTERNALS_sv_isbool BOOL_INTERNALS_sv_isbool_false BOOL_INTERNALS_sv_isbool_true boolSV croak_xs_usage DEFSV DEFSV_set get_sv isGV_with_GP looks_like_number MUTABLE_AV MUTABLE_CV MUTABLE_GV MUTABLE_HV MUTABLE_IO MUTABLE_ PTR MUTABLE_SV newRV newRV_inc newRV_noinc newSV newSVbool newSV_false newSVhek newSVhek_mortal newSViv newSVnv newSVpadname newSVpv newSVpvf newSVpvf_nocontext newSVpvn newSVpvn_flags newSVpvn_share newSVpvn_utf8 newSVpvs newSVpvs_flags newSVpv_share newSVpvs_share newSVrv newSVsv newSVsv_flags newSVsv_nomg newSV_true newSV_type newSV_type_mortal newSVuv Nullsv PL_sv_no PL_sv_undef PL_sv_yes PL_sv_zero SAVE_DEFSV sortsv sortsv_flags SvAMAGIC SvAMAGIC_off SvAMAGIC_on sv_backoff sv_bless SvBoolFlagsOK sv_catpv sv_catpv_flags sv_catpv_mg sv_catpv_nomg sv_catpvf sv_catpvf_mg sv_catpvf_mg_nocontext sv_catpvf_nocontext sv_catpvn sv_catpvn_flags sv_catpvn_mg sv_catpvn_nomg sv_catpvs sv_catpvs_flags sv_catpvs_mg sv_catpvs_nomg sv_catsv sv_catsv_flags sv_catsv_mg sv_catsv_nomg SV_CHECK_THINKFIRST SV_CHECK_THINKFIRST_COW_DROP sv_chop sv_clear sv_cmp sv_cmp_flags sv_cmp_locale sv_cmp_locale_flags sv_collxfrm sv_collxfrm_flags sv_copypv sv_copypv_flags sv_copypv_nomg SvCUR SvCUR_set sv_2cv sv_dec sv_dec_nomg sv_derived_from sv_derived_from_hv sv_derived_from_pv sv_derived_from_pvn sv_derived_from_sv sv_does sv_does_pv sv_does_pvn sv_does_sv SvEND sv_eq sv_eq_flags sv_force_normal sv_force_normal_flags sv_free SvGAMAGIC sv_get_backrefs SvGETMAGIC sv_gets SvGROW SvIandPOK SvIandPOK_off SvIandPOK_on sv_inc sv_inc_nomg sv_insert sv_insert_flags sv_2io SvIOK SvIOK_notUV SvIOK_off SvIOK_on SvIOK_only SvIOK_only_UV SvIOKp SvIOK_UV sv_isa sv_isa_sv SvIsBOOL SvIsCOW SvIsCOW_shared_hash sv_isobject SvIV SvIV_nomg SvIVx sv_2iv_flags SvIV_set SvIVX SvLEN sv_len SvLEN_set sv_len_utf8 sv_len_utf8_nomg SvLOCK sv_magic sv_magicext SvMAGIC_set sv_2mortal sv_mortalcopy sv_mortalcopy_flags sv_newmortal SvNIOK SvNIOK_off SvNIOKp SvNOK SvNOK_off SvNOK_on SvNOK_only SvNOKp sv_nolocking sv_nounlocking sv_numeq sv_numeq_flags SvNV SvNV_nomg SvNVx sv_2nv_flags SvNV_set SvNVX SvOK SvOOK SvOOK_off SvOOK_offset SvPOK SvPOK_off SvPOK_on SvPOK_only SvPOK_only_UTF8 SvPOKp sv_pos_b2u sv_pos_b2u_flags sv_pos_u2b sv_pos_u2b_flags SvPV SvPV_const SvPV_flags SvPV_flags_const SvPV_flags_mutable SvPV_mutable SvPV_nolen SvPV_nolen_const SvPV_nomg SvPV_nomg_const SvPV_nomg_const_nolen SvPV_nomg_nolen SvPVbyte SvPVbyte_nolen SvP Vbyte_nomg SvPVbyte_or_null SvPVbyte_or_null_nomg SvPVbytex SvPVbyt ex_nolen SvPVutf8 SvPVutf8_nolen SvPVutf8_nomg SvPVutf8_or_null S vPVutf8_or_null_nomg SvPVutf8x SvPVx SvPVx_const SvPVx_nolen SvPV x_nolen_const sv_2pv sv_2pv_flags sv_2pvbyte sv_2pvbyte_flags SvPVCLEAR SvPVCLEAR_FRESH SvPV_force SvPV_force_flags SvPV_force_flags_mutable SvPV_force_fla gs_nolen SvPV_force_mutable SvPV_force_nolen SvPV_force_nomg SvPV_f orce_nomg_nolen SvPVbyte_force SvPVbytex_force SvPVutf8_force SvPVu tf8x_force SvPVx_force SvPV_free sv_pvn_force_flags SvPV_renew SvPV_set SvPV_shrink_to_cur sv_2pvutf8 sv_2pvutf8_flags SvPVX SvPVX_const SvPVX_mutable SvPVXx SvPVXtrue SvREADONLY SvREADONLY_off SvREADONLY_on sv_ref SvREFCNT SvREFCNT_dec SvREFCNT_dec_set_NULL SvREFCNT_dec_ret_NULL SvREFCNT_d ec_NN SvREFCNT_inc SvREFCNT_inc_NN SvREFCNT_inc_simple SvREFCNT_inc_simpl e_NN SvREFCNT_inc_simple_void SvREFCNT_inc_simple_void_NN SvREFCNT_in c_void SvREFCNT_inc_void_NN sv_reftype sv_replace sv_report_used sv_reset SvROK SvROK_off SvROK_on SvRV SvRV_set sv_rvunweaken sv_rvweaken sv_setbool sv_setbool_mg sv_set_bool sv_set_false sv_setiv sv_setiv_mg SvSETMAGIC SvSetMagicSV SvSetMagicSV_nosteal SvSetSV SvSetSV_nosteal sv_setnv sv_setnv_mg sv_setpv sv_setpv_mg sv_setpvn sv_setpvn_fresh sv_setpvn_mg sv_ setpvs sv_setpvs_mg sv_setpv_bufsize sv_setpvf sv_setpvf_mg sv_setpvf_mg_nocontext sv_setpvf_nocontext sv_setref_iv sv_setref_nv sv_setref_pv sv_setref_pvn sv_setref_pvs sv_setref_uv sv_setrv_inc sv_setrv_inc_mg sv_setrv_noinc sv_setrv_noinc_mg sv_setsv sv_setsv_flags sv_setsv_mg sv_setsv_nomg sv_set_true sv_set_undef sv_setuv sv_setuv_mg SvSHARE SvSHARED_HASH SvSTASH SvSTASH_set sv_streq sv_streq_flags SvTRUE SvTRUE_NN SvTRUE_nomg SvTRUE_nomg_NN SvTRUEx SvTYPE SvUNLOCK sv_unmagic sv_unmagicext sv_unref sv_unref_flags SvUOK SvUPGRADE sv_upgrade sv_usepvn sv_usepvn_flags sv_usepvn_mg sv_utf8_decode sv_utf8_downgrade sv_utf8_downgrade_flags sv_utf8_downgrade_nomg sv_utf8_encode SvUTF8_off SvUTF8_on sv_utf8_upgrade sv_utf8_upgrade_flags sv_utf8_upgrade_flags_grow sv _utf8_upgrade_nomg SvUTF8 SvUV SvUV_nomg SvUVx sv_2uv_flags SvUV_set SvUVX SvUVXx sv_vcatpvf sv_vcatpvf_mg sv_vcatpvfn sv_vcatpvfn_flags SvVOK sv_vsetpvf sv_vsetpvf_mg sv_vsetpvfn SvVSTRING_mg vnewSVpvf"
+.IP Tainting 4
+.IX Item "Tainting"
+\&\f(CW\*(C`SvTAINT\*(C'\fR , \f(CW\*(C`SvTAINTED\*(C'\fR , \f(CW\*(C`SvTAINTED_off\*(C'\fR
+, \f(CW\*(C`SvTAINTED_on\*(C'\fR
+.IX Xref "SvTAINT SvTAINTED SvTAINTED_off SvTAINTED_on"
+.IP Time 4
+.IX Item "Time"
+\&\f(CW\*(C`ASCTIME_R_PROTO\*(C'\fR , \f(CW\*(C`CTIME_R_PROTO\*(C'\fR ,
+\&\f(CW\*(C`GMTIME_MAX\*(C'\fR , \f(CW\*(C`GMTIME_MIN\*(C'\fR , \f(CW\*(C`GMTIME_R_PROTO\*(C'\fR
+, \f(CW\*(C`HAS_ASCTIME_R\*(C'\fR , \f(CW\*(C`HAS_ASCTIME64\*(C'\fR
+, \f(CW\*(C`HAS_CTIME_R\*(C'\fR , \f(CW\*(C`HAS_CTIME64\*(C'\fR
+, \f(CW\*(C`HAS_DIFFTIME\*(C'\fR , \f(CW\*(C`HAS_DIFFTIME64\*(C'\fR
+, \f(CW\*(C`HAS_FUTIMES\*(C'\fR , \f(CW\*(C`HAS_GETITIMER\*(C'\fR
+, \f(CW\*(C`HAS_GETTIMEOFDAY\*(C'\fR , \f(CW\*(C`HAS_GMTIME_R\*(C'\fR
+, \f(CW\*(C`HAS_GMTIME64\*(C'\fR , \f(CW\*(C`HAS_LOCALTIME_R\*(C'\fR
+, \f(CW\*(C`HAS_LOCALTIME64\*(C'\fR , \f(CW\*(C`HAS_MKTIME\*(C'\fR
+, \f(CW\*(C`HAS_MKTIME64\*(C'\fR , \f(CW\*(C`HAS_NANOSLEEP\*(C'\fR
+, \f(CW\*(C`HAS_SETITIMER\*(C'\fR , \f(CW\*(C`HAS_STRFTIME\*(C'\fR
+, \f(CW\*(C`HAS_TIME\*(C'\fR , \f(CW\*(C`HAS_TIMEGM\*(C'\fR ,
+\&\f(CW\*(C`HAS_TIMES\*(C'\fR , \f(CW\*(C`HAS_TM_TM_GMTOFF\*(C'\fR ,
+\&\f(CW\*(C`HAS_TM_TM_ZONE\*(C'\fR , \f(CW\*(C`HAS_TZNAME\*(C'\fR ,
+\&\f(CW\*(C`HAS_USLEEP\*(C'\fR , \f(CW\*(C`HAS_USLEEP_PROTO\*(C'\fR ,
+\&\f(CW\*(C`I_TIME\*(C'\fR , \f(CW\*(C`I_UTIME\*(C'\fR , \f(CW\*(C`LOCALTIME_MAX\*(C'\fR
+, \f(CW\*(C`LOCALTIME_MIN\*(C'\fR ,
+\&\f(CW\*(C`LOCALTIME_R_NEEDS_TZSET\*(C'\fR , \f(CW\*(C`LOCALTIME_R_PROTO\*(C'\fR
+, \f(CW\*(C`L_R_TZSET\*(C'\fR , \f(CW\*(C`mini_mktime\*(C'\fR
+, \f(CW\*(C`my_strftime\*(C'\fR , \f(CW\*(C`switch_to_global_locale\*(C'\fR
+, POSIX::localeconv,
+I18N::Langinfo, items \f(CW\*(C`CRNCYSTR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR,
+"Perl_langinfo" in perlapi, items \f(CW\*(C`CRNCYSTR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR, \f(CW\*(C`sync_locale\*(C'\fR
+.IX Xref "ASCTIME_R_PROTO CTIME_R_PROTO GMTIME_MAX GMTIME_MIN GMTIME_R_PROTO HAS_ASCTIME_R HAS_ASCTIME64 HAS_CTIME_R HAS_CTIME64 HAS_DIFFTIME HAS_DIFFTIME64 HAS_FUTIMES HAS_GETITIMER HAS_GETTIMEOFDAY HAS_GMTIME_R HAS_GMTIME64 HAS_LOCALTIME_R HAS_LOCALTIME64 HAS_MKTIME HAS_MKTIME64 HAS_NANOSLEEP HAS_SETITIMER HAS_STRFTIME HAS_TIME HAS_TIMEGM HAS_TIMES HAS_TM_TM_GMTOFF HAS_TM_TM_ZONE HAS_TZNAME HAS_USLEEP HAS_USLEEP_PROTO I_TIME I_UTIME LOCALTIME_MAX LOCALTIME_MIN LOCALTIME_R_NEEDS_TZSET LOCALTIME_R_PROTO L_R_TZSET mini_mktime my_strftime switch_to_global_locale sync_locale"
+.IP "Typedef names" 4
+.IX Item "Typedef names"
+\&\f(CW\*(C`DB_Hash_t\*(C'\fR , \f(CW\*(C`DB_Prefix_t\*(C'\fR , \f(CW\*(C`Direntry_t\*(C'\fR
+, \f(CW\*(C`Fpos_t\*(C'\fR , \f(CW\*(C`Free_t\*(C'\fR , \f(CW\*(C`Gid_t\*(C'\fR ,
+\&\f(CW\*(C`Gid_t_f\*(C'\fR , \f(CW\*(C`Gid_t_sign\*(C'\fR , \f(CW\*(C`Gid_t_size\*(C'\fR
+, \f(CW\*(C`Groups_t\*(C'\fR , \f(CW\*(C`Malloc_t\*(C'\fR , \f(CW\*(C`Mmap_t\*(C'\fR
+, \f(CW\*(C`Mode_t\*(C'\fR , \f(CW\*(C`Netdb_hlen_t\*(C'\fR ,
+\&\f(CW\*(C`Netdb_host_t\*(C'\fR , \f(CW\*(C`Netdb_name_t\*(C'\fR ,
+\&\f(CW\*(C`Netdb_net_t\*(C'\fR , \f(CW\*(C`Off_t\*(C'\fR , \f(CW\*(C`Off_t_size\*(C'\fR
+, \f(CW\*(C`Pid_t\*(C'\fR , \f(CW\*(C`Rand_seed_t\*(C'\fR ,
+\&\f(CW\*(C`Select_fd_set_t\*(C'\fR , \f(CW\*(C`Shmat_t\*(C'\fR , \f(CW\*(C`Signal_t\*(C'\fR
+, \f(CW\*(C`Size_t\*(C'\fR , \f(CW\*(C`Size_t_size\*(C'\fR ,
+\&\f(CW\*(C`Sock_size_t\*(C'\fR , \f(CW\*(C`SSize_t\*(C'\fR , \f(CW\*(C`Time_t\*(C'\fR ,
+\&\f(CW\*(C`Uid_t\*(C'\fR , \f(CW\*(C`Uid_t_f\*(C'\fR , \f(CW\*(C`Uid_t_sign\*(C'\fR ,
+\&\f(CW\*(C`Uid_t_size\*(C'\fR
+.IX Xref "DB_Hash_t DB_Prefix_t Direntry_t Fpos_t Free_t Gid_t Gid_t_f Gid_t_sign Gid_t_size Groups_t Malloc_t Mmap_t Mode_t Netdb_hlen_t Netdb_host_t Netdb_name_t Netdb_net_t Off_t Off_t_size Pid_t Rand_seed_t Select_fd_set_t Shmat_t Signal_t Size_t Size_t_size Sock_size_t SSize_t Time_t Uid_t Uid_t_f Uid_t_sign Uid_t_size"
+.IP "Unicode Support X <UNICODE_DISALLOW_ILLEGAL_INTERCHANGE>" 4
+.IX Xref "UNICODE_DISALLOW_ABOVE_31_BIT UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE UNICODE_DISALLOW_NONCHAR UNICODE_ DISALLOW_PERL_EXTENDED UNICODE_DISALLOW_SUPER UNICODE_DISALLOW_SURROGAT E UNICODE_WARN_ABOVE_31_BIT UNICODE_WARN_ILLEGAL_C9_INTERCHANGE UNICO DE_WARN_ILLEGAL_INTERCHANGE UNICODE_WARN_NONCHAR UNICODE_WARN_PERL_EXTE NDED UNICODE_WARN_SUPER UNICODE_WARN_SURROGATE UNI_DISPLAY_BACKSLASH UNI_DISPLAY_BACKSPACE UNI_DISPLAY_ISPRINT UNI_DISPLAY_QQ UNI_DISPLA Y_REGEX UTF8_CHECK_ONLY UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE UTF8_DIS ALLOW_ILLEGAL_INTERCHANGE UTF8_DISALLOW_NONCHAR UTF8_DISALLOW_PERL_EXTE NDED UTF8_DISALLOW_SUPER UTF8_DISALLOW_SURROGATE UTF8_GOT_CONTINUATIO N UTF8_GOT_EMPTY UTF8_GOT_LONG UTF8_GOT_NONCHAR UTF8_GOT_NON_CONTIN UATION UTF8_GOT_OVERFLOW UTF8_GOT_PERL_EXTENDED UTF8_GOT_SHORT UTF8 _GOT_SUPER UTF8_GOT_SURROGATE UTF8_WARN_ILLEGAL_C9_INTERCHANGE UTF8_W ARN_ILLEGAL_INTERCHANGE UTF8_WARN_NONCHAR UTF8_WARN_PERL_EXTENDED UTF 8_WARN_SUPER UTF8_WARN_SURROGATE"
+.IX Item "Unicode Support X <UNICODE_DISALLOW_ILLEGAL_INTERCHANGE>"
+\&\f(CW\*(C`BOM_UTF8\*(C'\fR , \f(CW\*(C`bytes_cmp_utf8\*(C'\fR ,
+\&\f(CW\*(C`bytes_from_utf8\*(C'\fR , \f(CW\*(C`bytes_to_utf8\*(C'\fR ,
+\&\f(CW\*(C`DO_UTF8\*(C'\fR , \f(CW\*(C`foldEQ_utf8\*(C'\fR , \f(CW\*(C`is_ascii_string\*(C'\fR
+, \f(CW\*(C`isC9_STRICT_UTF8_CHAR\*(C'\fR ,
+\&\f(CW\*(C`is_c9strict_utf8_string\*(C'\fR ,
+\&\f(CW\*(C`is_c9strict_utf8_string_loc\*(C'\fR ,
+\&\f(CW\*(C`is_c9strict_utf8_string_loclen\*(C'\fR ,
+\&\f(CW\*(C`is_invariant_string\*(C'\fR , \f(CW\*(C`isSTRICT_UTF8_CHAR\*(C'\fR
+, \f(CW\*(C`is_strict_utf8_string\*(C'\fR ,
+\&\f(CW\*(C`is_strict_utf8_string_loc\*(C'\fR ,
+\&\f(CW\*(C`is_strict_utf8_string_loclen\*(C'\fR ,
+\&\f(CW\*(C`isUTF8_CHAR\*(C'\fR , \f(CW\*(C`is_utf8_char_buf\*(C'\fR ,
+\&\f(CW\*(C`isUTF8_CHAR_flags\*(C'\fR , \f(CW\*(C`is_utf8_fixed_width_buf_flags\*(C'\fR
+, \f(CW\*(C`is_utf8_fixed_width_buf_loc_flags\*(C'\fR
+,
+\&\f(CW\*(C`is_utf8_fixed_width_buf_loclen_flags\*(C'\fR
+, \f(CW\*(C`is_utf8_invariant_string\*(C'\fR
+, \f(CW\*(C`is_utf8_invariant_string_loc\*(C'\fR
+, \f(CW\*(C`is_utf8_string\*(C'\fR ,
+\&\f(CW\*(C`is_utf8_string_flags\*(C'\fR , \f(CW\*(C`is_utf8_string_loc\*(C'\fR
+, \f(CW\*(C`is_utf8_string_loc_flags\*(C'\fR
+, \f(CW\*(C`is_utf8_string_loclen\*(C'\fR
+, \f(CW\*(C`is_utf8_string_loclen_flags\*(C'\fR
+, \f(CW\*(C`is_utf8_valid_partial_char\*(C'\fR
+, \f(CW\*(C`is_utf8_valid_partial_char_flags\*(C'\fR
+, \f(CW\*(C`LATIN1_TO_NATIVE\*(C'\fR
+, \f(CW\*(C`NATIVE_TO_LATIN1\*(C'\fR ,
+\&\f(CW\*(C`NATIVE_TO_UNI\*(C'\fR , \f(CW\*(C`pv_uni_display\*(C'\fR ,
+\&\f(CW\*(C`REPLACEMENT_CHARACTER_UTF8\*(C'\fR ,
+\&\f(CW\*(C`sv_cat_decode\*(C'\fR , \f(CW\*(C`sv_recode_to_utf8\*(C'\fR
+, \f(CW\*(C`sv_uni_display\*(C'\fR ,
+\&\f(CW\*(C`UNICODE_IS_NONCHAR\*(C'\fR , \f(CW\*(C`UNICODE_IS_REPLACEMENT\*(C'\fR
+, \f(CW\*(C`UNICODE_IS_SUPER\*(C'\fR ,
+\&\f(CW\*(C`UNICODE_IS_SURROGATE\*(C'\fR , \f(CW\*(C`UNICODE_REPLACEMENT\*(C'\fR
+, \f(CW\*(C`UNI_TO_NATIVE\*(C'\fR , \f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR
+, \f(CW\*(C`utf8_distance\*(C'\fR , \f(CW\*(C`utf8_hop\*(C'\fR
+, \f(CW\*(C`utf8_hop_back\*(C'\fR , \f(CW\*(C`utf8_hop_forward\*(C'\fR
+, \f(CW\*(C`utf8_hop_safe\*(C'\fR ,
+\&\f(CW\*(C`UTF8_IS_INVARIANT\*(C'\fR , \f(CW\*(C`UTF8_IS_NONCHAR\*(C'\fR
+, \f(CW\*(C`UTF8_IS_REPLACEMENT\*(C'\fR ,
+\&\f(CW\*(C`UTF8_IS_SUPER\*(C'\fR , \f(CW\*(C`UTF8_IS_SURROGATE\*(C'\fR
+, \f(CW\*(C`utf8_length\*(C'\fR , \f(CW\*(C`UTF8_MAXBYTES\*(C'\fR
+, \f(CW\*(C`UTF8_MAXBYTES_CASE\*(C'\fR ,
+\&\f(CW\*(C`utf8ness_t\*(C'\fR , \f(CW\*(C`UTF8NESS_YES\*(C'\fR, \f(CW\*(C`UTF8NESS_NO\*(C'\fR,
+\&\f(CW\*(C`UTF8NESS_IMMATERIAL\*(C'\fR, \f(CW\*(C`UTF8NESS_UNKNOWN\*(C'\fR, \f(CW\*(C`0\ <=\ \fR\f(CIenum\ value\fR\f(CW\ <=\ UTF8NESS_IMMATERIAL\*(C'\fR, \f(CW\*(C`UTF8NESS_IMMATERIAL\ <=\ <\fR\f(CIenum\ value\fR\f(CW\*(C'\fR, \f(CW\*(C`utf8n_to_uvchr\*(C'\fR , \f(CW\*(C`utf8n_to_uvchr_error\*(C'\fR
+, \f(CW\*(C`UTF8_GOT_PERL_EXTENDED\*(C'\fR,
+\&\f(CW\*(C`UTF8_GOT_CONTINUATION\*(C'\fR, \f(CW\*(C`UTF8_GOT_EMPTY\*(C'\fR, \f(CW\*(C`UTF8_GOT_LONG\*(C'\fR,
+\&\f(CW\*(C`UTF8_GOT_NONCHAR\*(C'\fR, \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR, \f(CW\*(C`UTF8_GOT_OVERFLOW\*(C'\fR,
+\&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR, \f(CW\*(C`UTF8_GOT_SUPER\*(C'\fR, \f(CW\*(C`UTF8_GOT_SURROGATE\*(C'\fR,
+\&\f(CW\*(C`utf8n_to_uvchr_msgs\*(C'\fR , \f(CW\*(C`text\*(C'\fR, \f(CW\*(C`warn_categories\*(C'\fR,
+\&\f(CW\*(C`flag\*(C'\fR, \f(CW\*(C`UTF8_SAFE_SKIP\*(C'\fR , \f(CW\*(C`UTF8SKIP\*(C'\fR ,
+\&\f(CW\*(C`"UTF8_SAFE_SKIP" in perlapi\*(C'\fR if you know the maximum ending pointer in the
+buffer pointed to by \f(CW\*(C`s\*(C'\fR; or, \f(CW\*(C`"UTF8_CHK_SKIP" in perlapi\*(C'\fR if you don't
+know it, \f(CW\*(C`UTF8_SKIP\*(C'\fR , \f(CW\*(C`utf8_to_bytes\*(C'\fR ,
+\&\f(CW\*(C`utf8_to_uvchr\*(C'\fR , \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR
+, \f(CW\*(C`UVCHR_IS_INVARIANT\*(C'\fR ,
+\&\f(CW\*(C`UVCHR_SKIP\*(C'\fR , \f(CW\*(C`uvchr_to_utf8_flags\*(C'\fR ,
+\&\f(CW\*(C`uvchr_to_utf8_flags_msgs\*(C'\fR , \f(CW\*(C`text\*(C'\fR,
+\&\f(CW\*(C`warn_categories\*(C'\fR, \f(CW\*(C`flag\*(C'\fR, \f(CW\*(C`uvchr_to_utf8\*(C'\fR
+.IX Xref "BOM_UTF8 bytes_cmp_utf8 bytes_from_utf8 bytes_to_utf8 DO_UTF8 foldEQ_utf8 is_ascii_string isC9_STRICT_UTF8_CHAR is_c9strict_utf8_string is_c9strict_utf8_string_loc is_c9strict_utf8_string_loclen is_invariant_string isSTRICT_UTF8_CHAR is_strict_utf8_string is_strict_utf8_string_loc is_strict_utf8_string_loclen isUTF8_CHAR is_utf8_char_buf isUTF8_CHAR_flags is_utf8_fixed_width_buf_flags is_utf8_fixed_width_buf_loc_flags is_utf8_fixed_width_buf_loclen_flags is_utf8_invariant_string is_utf8_invariant_string_loc is_utf8_string is_utf8_string_flags is_utf8_string_loc is_utf8_string_loc_flags is_utf8_string_loclen is_utf8_string_loclen_flags is_utf8_valid_partial_char is_utf8_valid_partial_char_flags LATIN1_TO_NATIVE NATIVE_TO_LATIN1 NATIVE_TO_UNI pv_uni_display REPLACEMENT_CHARACTER_UTF8 sv_cat_decode sv_recode_to_utf8 sv_uni_display UNICODE_IS_NONCHAR UNICODE_IS_REPLACEMENT UNICODE_IS_SUPER UNICODE_IS_SURROGATE UNICODE_REPLACEMENT UNI_TO_NATIVE UTF8_CHK_SKIP utf8_distance utf8_hop utf8_hop_back utf8_hop_forward utf8_hop_safe UTF8_IS_INVARIANT UTF8_IS_NONCHAR UTF8_IS_REPLACEMENT UTF8_IS_SUPER UTF8_IS_SURROGATE utf8_length UTF8_MAXBYTES UTF8_MAXBYTES_CASE utf8ness_t utf8n_to_uvchr utf8n_to_uvchr_error utf8n_to_uvchr_msgs UTF8_SAFE_SKIP UTF8SKIP UTF8_SKIP utf8_to_bytes utf8_to_uvchr utf8_to_uvchr_buf UVCHR_IS_INVARIANT UVCHR_SKIP uvchr_to_utf8_flags uvchr_to_utf8_flags_msgs uvchr_to_utf8"
+.IP "Utility Functions" 4
+.IX Item "Utility Functions"
+\&\f(CW\*(C`C_ARRAY_END\*(C'\fR , \f(CW\*(C`C_ARRAY_LENGTH\*(C'\fR ,
+\&\f(CW\*(C`getcwd_sv\*(C'\fR , \f(CW\*(C`IN_PERL_COMPILETIME\*(C'\fR ,
+\&\f(CW\*(C`IN_PERL_RUNTIME\*(C'\fR , \f(CW\*(C`IS_SAFE_SYSCALL\*(C'\fR
+, \f(CW\*(C`is_safe_syscall\*(C'\fR , \f(CW\*(C`my_setenv\*(C'\fR
+, \f(CW\*(C`newPADxVOP\*(C'\fR , \f(CW\*(C`phase_name\*(C'\fR ,
+\&\f(CW\*(C`Poison\*(C'\fR , \f(CW\*(C`PoisonFree\*(C'\fR , \f(CW\*(C`PoisonNew\*(C'\fR
+, \f(CW\*(C`PoisonWith\*(C'\fR , \f(CW\*(C`StructCopy\*(C'\fR ,
+\&\f(CW\*(C`sv_destroyable\*(C'\fR , \f(CW\*(C`sv_nosharing\*(C'\fR
+.IX Xref "C_ARRAY_END C_ARRAY_LENGTH getcwd_sv IN_PERL_COMPILETIME IN_PERL_RUNTIME IS_SAFE_SYSCALL is_safe_syscall my_setenv newPADxVOP phase_name Poison PoisonFree PoisonNew PoisonWith StructCopy sv_destroyable sv_nosharing"
+.IP Versioning 4
+.IX Item "Versioning"
+\&\f(CW\*(C`new_version\*(C'\fR , \f(CW\*(C`PERL_REVISION\*(C'\fR ,
+\&\f(CW\*(C`PERL_SUBVERSION\*(C'\fR , \f(CW\*(C`PERL_VERSION\*(C'\fR ,
+\&\f(CW\*(C`PERL_VERSION_EQ\*(C'\fR, \f(CW\*(C`PERL_VERSION_GE\*(C'\fR, \f(CW\*(C`PERL_VERSION_GT\*(C'\fR,
+\&\f(CW\*(C`PERL_VERSION_LE\*(C'\fR, \f(CW\*(C`PERL_VERSION_LT\*(C'\fR, \f(CW\*(C`PERL_VERSION_NE\*(C'\fR
+, \f(CW\*(C`prescan_version\*(C'\fR ,
+\&\f(CW\*(C`scan_version\*(C'\fR , \f(CW\*(C`upg_version\*(C'\fR , \f(CW\*(C`vcmp\*(C'\fR
+, \f(CW\*(C`vnormal\*(C'\fR , \f(CW\*(C`vnumify\*(C'\fR , \f(CW\*(C`vstringify\*(C'\fR
+, \f(CW\*(C`vverify\*(C'\fR , The SV is an HV or a reference to an
+HV, The hash contains a "version" key, The "version" key has a reference to
+an AV as its value
+.IX Xref "new_version PERL_REVISION PERL_SUBVERSION PERL_VERSION PERL_VERSION_EQ PERL_VERSION_GE PERL_VERSION_GT PERL_VERSION_LE P ERL_VERSION_LT PERL_VERSION_NE prescan_version scan_version upg_version vcmp vnormal vnumify vstringify vverify"
+.IP "Warning and Dieing" 4
+.IX Xref "WARN_ALL WARN_AMBIGUOUS WARN_BAREWORD WARN_CLOSED WARN_CLOSURE WARN_DEBUGGING WARN_DEPRECATED WARN_DEPRECATED__APOSTROPHE_AS_PACKAGE_S EPARATOR WARN_DEPRECATED__DELIMITER_WILL_BE_PAIRED WARN_DEPRECATED__DOT _IN_INC WARN_DEPRECATED__GOTO_CONSTRUCT WARN_DEPRECATED__SMARTMATCH W ARN_DEPRECATED__UNICODE_PROPERTY_NAME WARN_DEPRECATED__VERSION_DOWNGRADE WARN_DIGIT WARN_EXEC WARN_EXITING WARN_EXPERIMENTAL WARN_EXPERIME NTAL__ARGS_ARRAY_WITH_SIGNATURES WARN_EXPERIMENTAL__BUILTIN WARN_EXPERI MENTAL__CLASS WARN_EXPERIMENTAL__CONST_ATTR WARN_EXPERIMENTAL__DECLARED _REFS WARN_EXPERIMENTAL__DEFER WARN_EXPERIMENTAL__EXTRA_PAIRED_DELIMITE RS WARN_EXPERIMENTAL__FOR_LIST WARN_EXPERIMENTAL__PRIVATE_USE WARN_EX PERIMENTAL__REFALIASING WARN_EXPERIMENTAL__REGEX_SETS WARN_EXPERIMENTAL __RE_STRICT WARN_EXPERIMENTAL__TRY WARN_EXPERIMENTAL__UNIPROP_WILDCARDS WARN_EXPERIMENTAL__VLB WARN_GLOB WARN_ILLEGALPROTO WARN_IMPRECISIO N WARN_INPLACE WARN_INTERNAL WARN_IO WARN_LAYER WARN_LOCALE WAR N_MALLOC WARN_MISC WARN_MISSING WARN_NEWLINE WARN_NONCHAR WARN_NO N_UNICODE WARN_NUMERIC WARN_ONCE WARN_OVERFLOW WARN_PACK WARN_PAR ENTHESIS WARN_PIPE WARN_PORTABLE WARN_PRECEDENCE WARN_PRINTF WARN _PROTOTYPE WARN_QW WARN_RECURSION WARN_REDEFINE WARN_REDUNDANT WA RN_REGEXP WARN_RESERVED WARN_SCALAR WARN_SEMICOLON WARN_SEVERE WA RN_SHADOW WARN_SIGNAL WARN_SUBSTR WARN_SURROGATE WARN_SYNTAX WARN _SYSCALLS WARN_TAINT WARN_THREADS WARN_UNINITIALIZED WARN_UNOPENED WARN_UNPACK WARN_UNTIE WARN_UTF8 WARN_VOID"
+.IX Item "Warning and Dieing"
+\&\f(CW\*(C`ckWARN\*(C'\fR, \f(CW\*(C`ckWARN2\*(C'\fR, \f(CW\*(C`ckWARN3\*(C'\fR, \f(CW\*(C`ckWARN4\*(C'\fR
+, \f(CW\*(C`ckWARN_d\*(C'\fR, \f(CW\*(C`ckWARN2_d\*(C'\fR,
+\&\f(CW\*(C`ckWARN3_d\*(C'\fR, \f(CW\*(C`ckWARN4_d\*(C'\fR ,
+\&\f(CW\*(C`ck_warner\*(C'\fR, \f(CW\*(C`ck_warner_d\*(C'\fR , \f(CW\*(C`CLEAR_ERRSV\*(C'\fR
+, \f(CW\*(C`croak\*(C'\fR, \f(CW\*(C`croak_nocontext\*(C'\fR ,
+\&\f(CW\*(C`croak_no_modify\*(C'\fR , \f(CW\*(C`croak_sv\*(C'\fR , \f(CW\*(C`die\*(C'\fR,
+\&\f(CW\*(C`die_nocontext\*(C'\fR , \f(CW\*(C`die_sv\*(C'\fR , \f(CW\*(C`ERRSV\*(C'\fR
+, \f(CW\*(C`packWARN\*(C'\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR, \f(CW\*(C`packWARN4\*(C'\fR
+, \f(CW\*(C`SANE_ERRSV\*(C'\fR
+, \f(CW\*(C`vcroak\*(C'\fR , \f(CW\*(C`vwarn\*(C'\fR , \f(CW\*(C`vwarner\*(C'\fR
+, \f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`warn_nocontext\*(C'\fR , \f(CW\*(C`warner\*(C'\fR,
+\&\f(CW\*(C`warner_nocontext\*(C'\fR , \f(CW\*(C`warn_sv\*(C'\fR
+.IX Xref "ckWARN ckWARN2 ckWARN3 ckWARN4 ckWARN_d ckWARN2_d ckWARN3_d ckWARN4_d ck_warner ck_warner_d CLEAR_ERRSV croak croak_nocontext croak_no_modify croak_sv die die_nocontext die_sv ERRSV packWARN packWARN2 packWARN3 packWARN4 SANE_ERRSV vcroak vwarn vwarner warn warn_nocontext warner warner_nocontext warn_sv"
+.IP XS 4
+.IX Item "XS"
+\&\f(CW\*(C`aMY_CXT\*(C'\fR, \f(CW\*(C`_aMY_CXT\*(C'\fR, \f(CW\*(C`aMY_CXT_\*(C'\fR, \f(CW\*(C`ax\*(C'\fR , \f(CW\*(C`CLASS\*(C'\fR ,
+\&\f(CW\*(C`dAX\*(C'\fR , \f(CW\*(C`dAXMARK\*(C'\fR , \f(CW\*(C`dITEMS\*(C'\fR , \f(CW\*(C`dMY_CXT\*(C'\fR,
+\&\f(CW\*(C`dMY_CXT_SV\*(C'\fR , \f(CW\*(C`dUNDERBAR\*(C'\fR , \f(CW\*(C`dXSARGS\*(C'\fR
+, \f(CW\*(C`dXSI32\*(C'\fR , \f(CW\*(C`items\*(C'\fR , \f(CW\*(C`ix\*(C'\fR , \f(CW\*(C`MY_CXT\*(C'\fR,
+\&\f(CW\*(C`MY_CXT_CLONE\*(C'\fR, \f(CW\*(C`MY_CXT_INIT\*(C'\fR, \f(CW\*(C`pMY_CXT\*(C'\fR, \f(CW\*(C`_pMY_CXT\*(C'\fR, \f(CW\*(C`pMY_CXT_\*(C'\fR,
+\&\f(CW\*(C`RETVAL\*(C'\fR , \f(CW\*(C`ST\*(C'\fR , \f(CW\*(C`START_MY_CXT\*(C'\fR, \f(CW\*(C`THIS\*(C'\fR ,
+\&\f(CW\*(C`UNDERBAR\*(C'\fR , \f(CW\*(C`XS\*(C'\fR , \f(CW\*(C`XS_EXTERNAL\*(C'\fR ,
+\&\f(CW\*(C`XS_INTERNAL\*(C'\fR , \f(CW\*(C`XSPROTO\*(C'\fR
+.IX Xref "ax CLASS dAX dAXMARK dITEMS dMY_CXT_SV dUNDERBAR dXSARGS dXSI32 items ix RETVAL ST THIS UNDERBAR XS XS_EXTERNAL XS_INTERNAL XSPROTO"
+.IP "Undocumented elements" 4
+.IX Item "Undocumented elements"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlintern \- autogenerated documentation of purely \fBinternal\fP Perl functions"
+.IX Subsection "perlintern - autogenerated documentation of purely internal Perl functions"
+.IP DESCRIPTION 4
+.IX Xref "internal Perl functions interpreter functions"
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "AV Handling" 4
+.IX Item "AV Handling"
+.PD
+\&\f(CW\*(C`av_fetch_simple\*(C'\fR , \f(CW\*(C`AvFILLp\*(C'\fR ,
+\&\f(CW\*(C`av_new_alloc\*(C'\fR , \f(CW\*(C`av_store_simple\*(C'\fR
+.IX Xref "av_fetch_simple AvFILLp av_new_alloc av_store_simple"
+.IP "Callback Functions" 4
+.IX Item "Callback Functions"
+\&\f(CW\*(C`dowantarray\*(C'\fR , \f(CW\*(C`leave_scope\*(C'\fR ,
+\&\f(CW\*(C`magic_freedestruct\*(C'\fR , \f(CW\*(C`mortal_svfunc_x\*(C'\fR
+, \f(CW\*(C`pop_scope\*(C'\fR , \f(CW\*(C`push_scope\*(C'\fR ,
+\&\f(CW\*(C`save_adelete\*(C'\fR , \f(CW\*(C`save_freercpv\*(C'\fR ,
+\&\f(CW\*(C`save_generic_pvref\*(C'\fR , \f(CW\*(C`save_generic_svref\*(C'\fR
+, \f(CW\*(C`save_hdelete\*(C'\fR , \f(CW\*(C`save_hints\*(C'\fR
+, \f(CW\*(C`save_op\*(C'\fR , \f(CW\*(C`save_padsv_and_mortalize\*(C'\fR
+, \f(CW\*(C`save_pushptr\*(C'\fR , \f(CW\*(C`save_rcpv\*(C'\fR
+, \f(CW\*(C`save_scalar_at\*(C'\fR , \f(CW\*(C`save_set_svflags\*(C'\fR
+, \f(CW\*(C`save_shared_pvref\*(C'\fR ,
+\&\f(CW\*(C`save_vptr\*(C'\fR
+.IX Xref "dowantarray leave_scope magic_freedestruct mortal_svfunc_x pop_scope push_scope save_adelete save_freercpv save_generic_pvref save_generic_svref save_hdelete save_hints save_op save_padsv_and_mortalize save_pushptr save_rcpv save_scalar_at save_set_svflags save_shared_pvref save_vptr"
+.IP Casting 4
+.IX Xref "NUM2PTR"
+.IX Item "Casting"
+.PD 0
+.IP "Character case changing" 4
+.IX Item "Character case changing"
+.IP "Character classification" 4
+.IX Item "Character classification"
+.IP "Compiler and Preprocessor information" 4
+.IX Item "Compiler and Preprocessor information"
+.IP "Compiler directives" 4
+.IX Item "Compiler directives"
+.IP "Compile-time scope hooks" 4
+.IX Item "Compile-time scope hooks"
+.PD
+\&\f(CW\*(C`BhkENTRY\*(C'\fR , \f(CW\*(C`BhkFLAGS\*(C'\fR , \f(CW\*(C`CALL_BLOCK_HOOKS\*(C'\fR
+.IX Xref "BhkENTRY BhkFLAGS CALL_BLOCK_HOOKS"
+.IP Concurrency 4
+.IX Item "Concurrency"
+\&\f(CW\*(C`CVf_SLABBED\*(C'\fR, \f(CW\*(C`CvROOT\*(C'\fR, \f(CW\*(C`CvSTART\*(C'\fR, \f(CW\*(C`CX_CUR\*(C'\fR, \f(CW\*(C`CXINC\*(C'\fR,
+\&\f(CW\*(C`CX_LEAVE_SCOPE\*(C'\fR, \f(CW\*(C`CX_POP\*(C'\fR, \f(CW\*(C`cxstack\*(C'\fR, \f(CW\*(C`cxstack_ix\*(C'\fR, \f(CW\*(C`CXt_BLOCK\*(C'\fR,
+\&\f(CW\*(C`CXt_EVAL\*(C'\fR, \f(CW\*(C`CXt_FORMAT\*(C'\fR, \f(CW\*(C`CXt_GIVEN\*(C'\fR, \f(CW\*(C`CXt_LOOP_ARY\*(C'\fR,
+\&\f(CW\*(C`CXt_LOOP_LAZYIV\*(C'\fR, \f(CW\*(C`CXt_LOOP_LAZYSV\*(C'\fR, \f(CW\*(C`CXt_LOOP_LIST\*(C'\fR,
+\&\f(CW\*(C`CXt_LOOP_PLAIN\*(C'\fR, \f(CW\*(C`CXt_NULL\*(C'\fR, \f(CW\*(C`CXt_SUB\*(C'\fR, \f(CW\*(C`CXt_SUBST\*(C'\fR, \f(CW\*(C`CXt_WHEN\*(C'\fR,
+\&\f(CW\*(C`cx_type\*(C'\fR, \f(CW\*(C`dounwind\*(C'\fR, \f(CW\*(C`my_fork\*(C'\fR , \f(CW\*(C`PERL_CONTEXT\*(C'\fR
+.IX Xref "my_fork"
+.IP "COPs and Hint Hashes" 4
+.IX Item "COPs and Hint Hashes"
+.PD 0
+.IP "Custom Operators" 4
+.IX Item "Custom Operators"
+.PD
+\&\f(CW\*(C`core_prototype\*(C'\fR
+.IX Xref "core_prototype"
+.IP "CV Handling" 4
+.IX Item "CV Handling"
+\&\f(CW\*(C`CvREFCOUNTED_ANYSV\*(C'\fR , \f(CW\*(C`CvREFCOUNTED_ANYSV_off\*(C'\fR
+, \f(CW\*(C`CvREFCOUNTED_ANYSV_on\*(C'\fR
+, \f(CW\*(C`CvWEAKOUTSIDE\*(C'\fR , \f(CW\*(C`docatch\*(C'\fR
+.IX Xref "CvREFCOUNTED_ANYSV CvREFCOUNTED_ANYSV_off CvREFCOUNTED_ANYSV_on CvWEAKOUTSIDE docatch"
+.IP Debugging 4
+.IX Item "Debugging"
+\&\f(CW\*(C`comma_aDEPTH\*(C'\fR , \f(CW\*(C`comma_pDEPTH\*(C'\fR , \f(CW\*(C`debop\*(C'\fR
+, \f(CW\*(C`debprof\*(C'\fR , \f(CW\*(C`debprofdump\*(C'\fR ,
+\&\f(CW\*(C`debug_aDEPTH\*(C'\fR , \f(CW\*(C`debug_pDEPTH\*(C'\fR ,
+\&\f(CW\*(C`free_c_backtrace\*(C'\fR , \f(CW\*(C`get_c_backtrace\*(C'\fR
+, \f(CW\*(C`PL_DBsingle\*(C'\fR , \f(CW\*(C`PL_DBsub\*(C'\fR ,
+\&\f(CW\*(C`PL_DBtrace\*(C'\fR , \f(CW\*(C`runops_debug\*(C'\fR, \f(CW\*(C`runops_standard\*(C'\fR
+.IX Xref "comma_aDEPTH comma_pDEPTH debop debprof debprofdump debug_aDEPTH debug_pDEPTH free_c_backtrace get_c_backtrace PL_DBsingle PL_DBsub PL_DBtrace"
+.IP "Display functions" 4
+.IX Xref "PERL_PV_PRETTY_DUMP PERL_PV_PRETTY_NOCLEAR PERL_PV_PRETTY_REGPROP"
+.IX Item "Display functions"
+\&\f(CW\*(C`sv_peek\*(C'\fR
+.IX Xref "sv_peek"
+.IP "Embedding, Threads, and Interpreter Cloning" 4
+.IX Item "Embedding, Threads, and Interpreter Cloning"
+\&\f(CW\*(C`cv_dump\*(C'\fR , \f(CW\*(C`cv_forget_slab\*(C'\fR , \f(CW\*(C`do_dump_pad\*(C'\fR
+, \f(CW\*(C`get_context\*(C'\fR , \f(CW\*(C`pad_alloc_name\*(C'\fR
+, \f(CW\*(C`pad_block_start\*(C'\fR , \f(CW\*(C`pad_check_dup\*(C'\fR
+, \f(CW\*(C`pad_findlex\*(C'\fR , \f(CW\*(C`pad_fixup_inner_anons\*(C'\fR
+, \f(CW\*(C`pad_free\*(C'\fR , \f(CW\*(C`pad_leavemy\*(C'\fR
+, \f(CW\*(C`padlist_dup\*(C'\fR , \f(CW\*(C`padname_dup\*(C'\fR
+, \f(CW\*(C`padnamelist_dup\*(C'\fR , \f(CW\*(C`pad_push\*(C'\fR
+, \f(CW\*(C`pad_reset\*(C'\fR , \f(CW\*(C`pad_setsv\*(C'\fR ,
+\&\f(CW\*(C`pad_sv\*(C'\fR , \f(CW\*(C`pad_swipe\*(C'\fR , \f(CW\*(C`set_context\*(C'\fR
+, \f(CW\*(C`si_dup\*(C'\fR , \f(CW\*(C`ss_dup\*(C'\fR
+.IX Xref "cv_dump cv_forget_slab do_dump_pad get_context pad_alloc_name pad_block_start pad_check_dup pad_findlex pad_fixup_inner_anons pad_free pad_leavemy padlist_dup padname_dup padnamelist_dup pad_push pad_reset pad_setsv pad_sv pad_swipe set_context si_dup ss_dup"
+.IP Errno 4
+.IX Item "Errno"
+\&\f(CW\*(C`dSAVEDERRNO\*(C'\fR , \f(CW\*(C`dSAVE_ERRNO\*(C'\fR ,
+\&\f(CW\*(C`RESTORE_ERRNO\*(C'\fR , \f(CW\*(C`SAVE_ERRNO\*(C'\fR , \f(CW\*(C`SETERRNO\*(C'\fR
+.IX Xref "dSAVEDERRNO dSAVE_ERRNO RESTORE_ERRNO SAVE_ERRNO SETERRNO"
+.IP "Exception Handling (simple) Macros" 4
+.IX Item "Exception Handling (simple) Macros"
+.PD 0
+.IP "Filesystem configuration values" 4
+.IX Item "Filesystem configuration values"
+.IP "Floating point" 4
+.IX Item "Floating point"
+.IP "General Configuration" 4
+.IX Item "General Configuration"
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.IP "GV Handling and Stashes" 4
+.IX Xref "GV_CACHE_ONLY"
+.IX Item "GV Handling and Stashes"
+.PD
+\&\f(CW\*(C`amagic_applies\*(C'\fR , \f(CW\*(C`gp_dup\*(C'\fR , \f(CW\*(C`gv_handler\*(C'\fR
+, \f(CW\*(C`gv_stashsvpvn_cached\*(C'\fR ,
+\&\f(CW\*(C`gv_try_downgrade\*(C'\fR
+.IX Xref "amagic_applies gp_dup gv_handler gv_stashsvpvn_cached gv_try_downgrade"
+.IP "Hook manipulation" 4
+.IX Item "Hook manipulation"
+.PD 0
+.IP "HV Handling" 4
+.IX Xref "HvNAME_get"
+.IX Item "HV Handling"
+.PD
+\&\f(CW\*(C`hv_eiter_p\*(C'\fR , \f(CW\*(C`hv_eiter_set\*(C'\fR ,
+\&\f(CW\*(C`hv_ename_add\*(C'\fR , \f(CW\*(C`hv_ename_delete\*(C'\fR ,
+\&\f(CW\*(C`hv_fill\*(C'\fR , \f(CW\*(C`hv_placeholders_get\*(C'\fR ,
+\&\f(CW\*(C`hv_placeholders_set\*(C'\fR , \f(CW\*(C`hv_riter_p\*(C'\fR ,
+\&\f(CW\*(C`hv_riter_set\*(C'\fR , \f(CW\*(C`refcounted_he_chain_2hv\*(C'\fR
+, \f(CW\*(C`refcounted_he_fetch_pv\*(C'\fR
+, \f(CW\*(C`refcounted_he_fetch_pvn\*(C'\fR
+, \f(CW\*(C`refcounted_he_fetch_pvs\*(C'\fR
+, \f(CW\*(C`refcounted_he_fetch_sv\*(C'\fR
+, \f(CW\*(C`refcounted_he_free\*(C'\fR ,
+\&\f(CW\*(C`refcounted_he_inc\*(C'\fR , \f(CW\*(C`refcounted_he_new_pv\*(C'\fR
+, \f(CW\*(C`refcounted_he_new_pvn\*(C'\fR ,
+\&\f(CW\*(C`refcounted_he_new_pvs\*(C'\fR , \f(CW\*(C`refcounted_he_new_sv\*(C'\fR
+, \f(CW\*(C`unsharepvn\*(C'\fR
+.IX Xref "hv_eiter_p hv_eiter_set hv_ename_add hv_ename_delete hv_fill hv_placeholders_get hv_placeholders_set hv_riter_p hv_riter_set refcounted_he_chain_2hv refcounted_he_fetch_pv refcounted_he_fetch_pvn refcounted_he_fetch_pvs refcounted_he_fetch_sv refcounted_he_free refcounted_he_inc refcounted_he_new_pv refcounted_he_new_pvn refcounted_he_new_pvs refcounted_he_new_sv unsharepvn"
+.IP Input/Output 4
+.IX Item "Input/Output"
+\&\f(CW\*(C`dirp_dup\*(C'\fR , \f(CW\*(C`fp_dup\*(C'\fR , \f(CW\*(C`my_fflush_all\*(C'\fR
+, \f(CW\*(C`my_mkostemp\*(C'\fR , \f(CW\*(C`my_mkstemp\*(C'\fR
+, \f(CW\*(C`PL_last_in_gv\*(C'\fR , \f(CW\*(C`PL_ofsgv\*(C'\fR ,
+\&\f(CW\*(C`PL_rs\*(C'\fR , \f(CW\*(C`start_glob\*(C'\fR
+.IX Xref "dirp_dup fp_dup my_fflush_all my_mkostemp my_mkstemp PL_last_in_gv PL_ofsgv PL_rs start_glob"
+.IP Integer 4
+.IX Item "Integer"
+.PD 0
+.IP "I/O Formats" 4
+.IX Item "I/O Formats"
+.IP "Lexer interface" 4
+.IX Item "Lexer interface"
+.PD
+\&\f(CW\*(C`resume_compcv_and_save\*(C'\fR , \f(CW\*(C`resume_compcv_final\*(C'\fR
+, \f(CW\*(C`validate_proto\*(C'\fR
+.IX Xref "resume_compcv_and_save resume_compcv_final validate_proto"
+.IP Locales 4
+.IX Item "Locales"
+.PD 0
+.IP Magic 4
+.IX Item "Magic"
+.PD
+\&\f(CW\*(C`magic_clearhint\*(C'\fR , \f(CW\*(C`magic_clearhints\*(C'\fR
+, \f(CW\*(C`magic_methcall\*(C'\fR , \f(CW\*(C`magic_sethint\*(C'\fR
+, \f(CW\*(C`mg_dup\*(C'\fR , \f(CW\*(C`mg_localize\*(C'\fR
+.IX Xref "magic_clearhint magic_clearhints magic_methcall magic_sethint mg_dup mg_localize"
+.IP "Memory Management" 4
+.IX Item "Memory Management"
+\&\f(CW\*(C`calloc\*(C'\fR , \f(CW\*(C`malloc\*(C'\fR , \f(CW\*(C`mfree\*(C'\fR , \f(CW\*(C`realloc\*(C'\fR
+.IX Xref "calloc malloc mfree realloc"
+.IP MRO 4
+.IX Item "MRO"
+\&\f(CW\*(C`mro_get_linear_isa_dfs\*(C'\fR , \f(CW\*(C`mro_isa_changed_in\*(C'\fR
+, \f(CW\*(C`mro_package_moved\*(C'\fR
+.IX Xref "mro_get_linear_isa_dfs mro_isa_changed_in mro_package_moved"
+.IP "Multicall Functions" 4
+.IX Item "Multicall Functions"
+.PD 0
+.IP "Numeric Functions" 4
+.IX Item "Numeric Functions"
+.PD
+\&\f(CW\*(C`isinfnansv\*(C'\fR
+.IX Xref "isinfnansv"
+.IP Optrees 4
+.IX Item "Optrees"
+\&\f(CW\*(C`newATTRSUB_x\*(C'\fR , \f(CW\*(C`newXS_len_flags\*(C'\fR ,
+\&\f(CW\*(C`op_refcnt_lock\*(C'\fR , \f(CW\*(C`op_refcnt_unlock\*(C'\fR
+, \f(CW\*(C`traverse_op_tree\*(C'\fR
+.IX Xref "newATTRSUB_x newXS_len_flags op_refcnt_lock op_refcnt_unlock traverse_op_tree"
+.IP "Pack and Unpack" 4
+.IX Item "Pack and Unpack"
+.PD 0
+.IP "Pad Data Structures" 4
+.IX Item "Pad Data Structures"
+.PD
+\&\f(CW\*(C`CX_CURPAD_SAVE\*(C'\fR , \f(CW\*(C`CX_CURPAD_SV\*(C'\fR ,
+\&\f(CW\*(C`PAD_BASE_SV\*(C'\fR , \f(CW\*(C`PAD_CLONE_VARS\*(C'\fR ,
+\&\f(CW\*(C`PAD_COMPNAME_FLAGS\*(C'\fR , \f(CW\*(C`PAD_COMPNAME_GEN\*(C'\fR
+, \f(CW\*(C`PAD_COMPNAME_GEN_set\*(C'\fR ,
+\&\f(CW\*(C`PAD_COMPNAME_OURSTASH\*(C'\fR , \f(CW\*(C`PAD_COMPNAME_PV\*(C'\fR
+, \f(CW\*(C`PAD_COMPNAME_TYPE\*(C'\fR ,
+\&\f(CW\*(C`PadnameIsFIELD\*(C'\fR , \f(CW\*(C`PadnameIsOUR\*(C'\fR ,
+\&\f(CW\*(C`PadnameIsSTATE\*(C'\fR , \f(CW\*(C`PadnameOURSTASH\*(C'\fR ,
+\&\f(CW\*(C`PadnameOUTER\*(C'\fR , \f(CW\*(C`PadnameTYPE\*(C'\fR ,
+\&\f(CW\*(C`PAD_RESTORE_LOCAL\*(C'\fR , \f(CW\*(C`PAD_SAVE_LOCAL\*(C'\fR
+, \f(CW\*(C`PAD_SAVE_SETNULLPAD\*(C'\fR ,
+\&\f(CW\*(C`PAD_SET_CUR\*(C'\fR , \f(CW\*(C`PAD_SET_CUR_NOSAVE\*(C'\fR ,
+\&\f(CW\*(C`PAD_SETSV\*(C'\fR , \f(CW\*(C`PAD_SV\*(C'\fR , \f(CW\*(C`PAD_SVl\*(C'\fR ,
+\&\f(CW\*(C`SAVECLEARSV\*(C'\fR , \f(CW\*(C`SAVECOMPPAD\*(C'\fR , \f(CW\*(C`SAVEPADSV\*(C'\fR
+.IX Xref "CX_CURPAD_SAVE CX_CURPAD_SV PAD_BASE_SV PAD_CLONE_VARS PAD_COMPNAME_FLAGS PAD_COMPNAME_GEN PAD_COMPNAME_GEN_set PAD_COMPNAME_OURSTASH PAD_COMPNAME_PV PAD_COMPNAME_TYPE PadnameIsFIELD PadnameIsOUR PadnameIsSTATE PadnameOURSTASH PadnameOUTER PadnameTYPE PAD_RESTORE_LOCAL PAD_SAVE_LOCAL PAD_SAVE_SETNULLPAD PAD_SET_CUR PAD_SET_CUR_NOSAVE PAD_SETSV PAD_SV PAD_SVl SAVECLEARSV SAVECOMPPAD SAVEPADSV"
+.IP "Password and Group access" 4
+.IX Item "Password and Group access"
+.PD 0
+.IP "Paths to system commands" 4
+.IX Item "Paths to system commands"
+.IP "Prototype information" 4
+.IX Item "Prototype information"
+.IP "REGEXP Functions" 4
+.IX Item "REGEXP Functions"
+.PD
+\&\f(CW\*(C`regnode\*(C'\fR
+.IP "Reports and Formats" 4
+.IX Item "Reports and Formats"
+.PD 0
+.IP Signals 4
+.IX Item "Signals"
+.IP "Site configuration" 4
+.IX Item "Site configuration"
+.IP "Sockets configuration values" 4
+.IX Item "Sockets configuration values"
+.IP "Source Filters" 4
+.IX Item "Source Filters"
+.IP "Stack Manipulation Macros" 4
+.IX Item "Stack Manipulation Macros"
+.PD
+\&\f(CW\*(C`djSP\*(C'\fR , \f(CW\*(C`LVRET\*(C'\fR , \f(CW\*(C`save_alloc\*(C'\fR
+.IX Xref "djSP LVRET save_alloc"
+.IP "String Handling" 4
+.IX Item "String Handling"
+\&\f(CW\*(C`delimcpy_no_escape\*(C'\fR , \f(CW\*(C`my_cxt_init\*(C'\fR ,
+\&\f(CW\*(C`quadmath_format_needed\*(C'\fR ,
+\&\f(CW\*(C`quadmath_format_valid\*(C'\fR
+.IX Xref "delimcpy_no_escape my_cxt_init quadmath_format_needed quadmath_format_valid"
+.IP "SV Flags" 4
+.IX Item "SV Flags"
+\&\f(CW\*(C`SVt_INVLIST\*(C'\fR
+.IX Xref "SVt_INVLIST"
+.IP "SV Handling" 4
+.IX Item "SV Handling"
+\&\f(CW\*(C`PL_Sv\*(C'\fR , \f(CW\*(C`sv_add_arena\*(C'\fR , \f(CW\*(C`sv_2bool\*(C'\fR
+, \f(CW\*(C`sv_2bool_flags\*(C'\fR , \f(CW\*(C`sv_clean_all\*(C'\fR
+, \f(CW\*(C`sv_clean_objs\*(C'\fR , \f(CW\*(C`sv_free_arenas\*(C'\fR
+, \f(CW\*(C`sv_grow\*(C'\fR , \f(CW\*(C`sv_grow_fresh\*(C'\fR
+, \f(CW\*(C`sv_newref\*(C'\fR , \f(CW\*(C`sv_2num\*(C'\fR ,
+\&\f(CW\*(C`sv_pv\*(C'\fR , \f(CW\*(C`sv_pvbyte\*(C'\fR , \f(CW\*(C`sv_pvbyten_force\*(C'\fR
+, \f(CW\*(C`sv_2pvbyte_nolen\*(C'\fR ,
+\&\f(CW\*(C`sv_pvn_force\*(C'\fR , \f(CW\*(C`sv_2pv_nolen\*(C'\fR ,
+\&\f(CW\*(C`sv_pvutf8n_force\*(C'\fR , \f(CW\*(C`sv_2pvutf8_nolen\*(C'\fR
+, \f(CW\*(C`sv_pvutf8\*(C'\fR , \f(CW\*(C`sv_tainted\*(C'\fR
+, \f(CW\*(C`SvTHINKFIRST\*(C'\fR , \f(CW\*(C`sv_true\*(C'\fR ,
+\&\f(CW\*(C`sv_untaint\*(C'\fR
+.IX Xref "PL_Sv sv_add_arena sv_2bool sv_2bool_flags sv_clean_all sv_clean_objs sv_free_arenas sv_grow sv_grow_fresh sv_newref sv_2num sv_pv sv_pvbyte sv_pvbyten_force sv_2pvbyte_nolen sv_pvn_force sv_2pv_nolen sv_pvutf8n_force sv_2pvutf8_nolen sv_pvutf8 sv_tainted SvTHINKFIRST sv_true sv_untaint"
+.IP Tainting 4
+.IX Item "Tainting"
+\&\f(CW\*(C`sv_taint\*(C'\fR , \f(CW\*(C`TAINT\*(C'\fR , \f(CW\*(C`TAINT_ENV\*(C'\fR ,
+\&\f(CW\*(C`taint_env\*(C'\fR , \f(CW\*(C`TAINT_get\*(C'\fR , \f(CW\*(C`TAINT_IF\*(C'\fR
+, \f(CW\*(C`TAINTING_get\*(C'\fR , \f(CW\*(C`TAINTING_set\*(C'\fR
+, \f(CW\*(C`TAINT_NOT\*(C'\fR , \f(CW\*(C`TAINT_PROPER\*(C'\fR
+, \f(CW\*(C`taint_proper\*(C'\fR , \f(CW\*(C`TAINT_set\*(C'\fR
+, \f(CW\*(C`TAINT_WARN_get\*(C'\fR , \f(CW\*(C`TAINT_WARN_set\*(C'\fR
+.IX Xref "sv_taint TAINT TAINT_ENV taint_env TAINT_get TAINT_IF TAINTING_get TAINTING_set TAINT_NOT TAINT_PROPER taint_proper TAINT_set TAINT_WARN_get TAINT_WARN_set"
+.IP Time 4
+.IX Item "Time"
+.PD 0
+.IP "Typedef names" 4
+.IX Item "Typedef names"
+.IP "Unicode Support" 4
+.IX Xref "FOLDEQ_LOCALE FOLDEQ_S1_ALREADY_FOLDED FOLDEQ_S1_FOLDS_SANE FOLDEQ_ S2_ALREADY_FOLDED FOLDEQ_S2_FOLDS_SANE FOLDEQ_UTF8_NOMIX_ASCII"
+.IX Item "Unicode Support"
+.PD
+\&\f(CW\*(C`bytes_from_utf8_loc\*(C'\fR , \f(CW\*(C`find_uninit_var\*(C'\fR
+, \f(CW\*(C`isSCRIPT_RUN\*(C'\fR ,
+\&\f(CW\*(C`is_utf8_non_invariant_string\*(C'\fR ,
+\&\f(CW\*(C`utf8n_to_uvuni\*(C'\fR , \f(CW\*(C`utf8_to_uvuni\*(C'\fR ,
+\&\f(CW\*(C`uvoffuni_to_utf8_flags\*(C'\fR , \f(CW\*(C`valid_utf8_to_uvchr\*(C'\fR
+, \f(CW\*(C`variant_under_utf8_count\*(C'\fR
+.IX Xref "bytes_from_utf8_loc find_uninit_var isSCRIPT_RUN is_utf8_non_invariant_string utf8n_to_uvuni utf8_to_uvuni uvoffuni_to_utf8_flags valid_utf8_to_uvchr variant_under_utf8_count"
+.IP "Utility Functions" 4
+.IX Item "Utility Functions"
+\&\f(CW\*(C`my_popen_list\*(C'\fR , \f(CW\*(C`my_socketpair\*(C'\fR
+.IX Xref "my_popen_list my_socketpair"
+.IP Versioning 4
+.IX Item "Versioning"
+.PD 0
+.IP "Warning and Dieing" 4
+.IX Item "Warning and Dieing"
+.PD
+\&\f(CW\*(C`deprecate\*(C'\fR , \f(CW\*(C`deprecate_disappears_in\*(C'\fR
+, \f(CW\*(C`deprecate_fatal_in\*(C'\fR ,
+\&\f(CW\*(C`PL_dowarn\*(C'\fR , \f(CW\*(C`report_uninit\*(C'\fR
+.IX Xref "deprecate deprecate_disappears_in deprecate_fatal_in PL_dowarn report_uninit"
+.IP XS 4
+.IX Item "XS"
+.PD 0
+.IP "Undocumented elements" 4
+.IX Item "Undocumented elements"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perliol \- C API for Perl's implementation of IO in Layers."
+.IX Subsection "perliol - C API for Perl's implementation of IO in Layers."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "History and Background" 4
+.IX Item "History and Background"
+.IP "Basic Structure" 4
+.IX Item "Basic Structure"
+.IP "Layers vs Disciplines" 4
+.IX Item "Layers vs Disciplines"
+.IP "Data Structures" 4
+.IX Item "Data Structures"
+.IP "Functions and Attributes" 4
+.IX Item "Functions and Attributes"
+.IP "Per-instance Data" 4
+.IX Item "Per-instance Data"
+.IP "Layers in action." 4
+.IX Item "Layers in action."
+.IP "Per-instance flag bits" 4
+.IX Item "Per-instance flag bits"
+.PD
+PERLIO_F_EOF, PERLIO_F_CANWRITE,  PERLIO_F_CANREAD, PERLIO_F_ERROR,
+PERLIO_F_TRUNCATE, PERLIO_F_APPEND, PERLIO_F_CRLF, PERLIO_F_UTF8,
+PERLIO_F_UNBUF, PERLIO_F_WRBUF, PERLIO_F_RDBUF, PERLIO_F_LINEBUF,
+PERLIO_F_TEMP, PERLIO_F_OPEN, PERLIO_F_FASTGETS
+.IP "Methods in Detail" 4
+.IX Item "Methods in Detail"
+fsize, name, size, kind, PERLIO_K_BUFFERED, PERLIO_K_RAW, PERLIO_K_CANCRLF,
+PERLIO_K_FASTGETS, PERLIO_K_MULTIARG, Pushed, Popped, Open, Binmode,
+Getarg, Fileno, Dup, Read, Write, Seek, Tell, Close, Flush, Fill, Eof,
+Error,	Clearerr, Setlinebuf, Get_base, Get_bufsiz, Get_ptr, Get_cnt,
+Set_ptrcnt
+.IP Utilities 4
+.IX Item "Utilities"
+.PD 0
+.IP "Implementing PerlIO Layers" 4
+.IX Item "Implementing PerlIO Layers"
+.PD
+C implementations, Perl implementations
+.IP "Core Layers" 4
+.IX Item "Core Layers"
+"unix", "perlio", "stdio", "crlf", "mmap", "pending", "raw", "utf8"
+.IP "Extension Layers" 4
+.IX Item "Extension Layers"
+":encoding", ":scalar", ":via"
+.RE
+.RS 4
+.RE
+.IP TODO 4
+.IX Item "TODO"
+.SS "perlapio \- perl's IO abstraction interface."
+.IX Subsection "perlapio - perl's IO abstraction interface."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+1. USE_STDIO, 2. USE_PERLIO, \fBPerlIO_stdin()\fR, \fBPerlIO_stdout()\fR,
+\&\fBPerlIO_stderr()\fR, \fBPerlIO_open(path, mode)\fR, \fBPerlIO_fdopen(fd,mode)\fR,
+\&\fBPerlIO_reopen(path,mode,f)\fR, \fBPerlIO_printf(f,fmt,...)\fR,
+\&\fBPerlIO_vprintf(f,fmt,a)\fR, \fBPerlIO_stdoutf(fmt,...)\fR,
+\&\fBPerlIO_read(f,buf,count)\fR, \fBPerlIO_write(f,buf,count)\fR,
+\&\fBPerlIO_fill(f)\fR, \fBPerlIO_close(f)\fR, \fBPerlIO_puts(f,s)\fR,
+\&\fBPerlIO_putc(f,c)\fR, \fBPerlIO_ungetc(f,c)\fR, \fBPerlIO_unread(f,buf,count)\fR,
+\&\fBPerlIO_getc(f)\fR, \fBPerlIO_eof(f)\fR, \fBPerlIO_error(f)\fR,
+\&\fBPerlIO_fileno(f)\fR, \fBPerlIO_clearerr(f)\fR, \fBPerlIO_flush(f)\fR,
+\&\fBPerlIO_seek(f,offset,whence)\fR, \fBPerlIO_tell(f)\fR, \fBPerlIO_getpos(f,p)\fR,
+\&\fBPerlIO_setpos(f,p)\fR, \fBPerlIO_rewind(f)\fR, \fBPerlIO_tmpfile()\fR,
+\&\fBPerlIO_setlinebuf(f)\fR
+.RS 4
+.IP "Co-existence with stdio" 4
+.IX Item "Co-existence with stdio"
+\&\fBPerlIO_importFILE(f,mode)\fR, \fBPerlIO_exportFILE(f,mode)\fR,
+\&\fBPerlIO_releaseFILE(p,f)\fR, \fBPerlIO_findFILE(f)\fR
+.IP """Fast gets"" Functions" 4
+.IX Item """Fast gets"" Functions"
+\&\fBPerlIO_fast_gets(f)\fR, \fBPerlIO_has_cntptr(f)\fR, \fBPerlIO_get_cnt(f)\fR,
+\&\fBPerlIO_get_ptr(f)\fR, \fBPerlIO_set_ptrcnt(f,p,c)\fR, \fBPerlIO_canset_cnt(f)\fR,
+\&\fBPerlIO_set_cnt(f,c)\fR, \fBPerlIO_has_base(f)\fR, \fBPerlIO_get_base(f)\fR,
+\&\fBPerlIO_get_bufsiz(f)\fR
+.IP "Other Functions" 4
+.IX Item "Other Functions"
+PerlIO_apply_layers(aTHX_ f,mode,layers), PerlIO_binmode(aTHX_
+f,ptype,imode,layers), '<' read, '>' write, '+' read/write,
+PerlIO_debug(fmt,...)
+.RE
+.RS 4
+.RE
+.SS "perlhack \- How to hack on Perl"
+.IX Subsection "perlhack - How to hack on Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "SUPER QUICK PATCH GUIDE" 4
+.IX Item "SUPER QUICK PATCH GUIDE"
+.PD
+Check out the source repository, Ensure you're following the latest advice,
+Create a branch for your change, Make your change, Test your change, Commit
+your change, Send your change to the Perl issue tracker, Thank you,
+Acknowledgement, Next time
+.IP "BUG REPORTING" 4
+.IX Item "BUG REPORTING"
+.PD 0
+.IP "PERL 5 PORTERS" 4
+.IX Item "PERL 5 PORTERS"
+.RS 4
+.IP "perl-changes mailing list" 4
+.IX Item "perl-changes mailing list"
+.IP "#p5p on IRC" 4
+.IX Item "#p5p on IRC"
+.RE
+.RS 4
+.RE
+.IP "GETTING THE PERL SOURCE" 4
+.IX Item "GETTING THE PERL SOURCE"
+.RS 4
+.IP "Read access via Git" 4
+.IX Item "Read access via Git"
+.IP "Read access via the web" 4
+.IX Item "Read access via the web"
+.IP "Write access via git" 4
+.IX Item "Write access via git"
+.RE
+.RS 4
+.RE
+.IP "PATCHING PERL" 4
+.IX Item "PATCHING PERL"
+.RS 4
+.IP "Submitting patches" 4
+.IX Item "Submitting patches"
+.IP "Getting your patch accepted" 4
+.IX Item "Getting your patch accepted"
+.PD
+Why, What, How
+.IP "Patching a core module" 4
+.IX Item "Patching a core module"
+.PD 0
+.IP "Updating perldelta" 4
+.IX Item "Updating perldelta"
+.IP "What makes for a good patch?" 4
+.IX Item "What makes for a good patch?"
+.RE
+.RS 4
+.RE
+.IP TESTING 4
+.IX Item "TESTING"
+.PD
+\&\fIt/base\fR, \fIt/comp\fR and \fIt/opbasic\fR, All other subdirectories of \fIt/\fR,
+Test files not found under \fIt/\fR
+.RS 4
+.ie n .IP "Special ""make test"" targets" 4
+.el .IP "Special \f(CWmake test\fR targets" 4
+.IX Item "Special make test targets"
+test_porting, minitest, test.valgrind check.valgrind, test_harness,
+test-notty test_notty
+.IP "Parallel tests" 4
+.IX Item "Parallel tests"
+.PD 0
+.IP "Running tests by hand" 4
+.IX Item "Running tests by hand"
+.IP "Using \fIt/harness\fR for testing" 4
+.IX Item "Using t/harness for testing"
+.PD
+\&\-v, \-torture, \-re=PATTERN, \-re LIST OF PATTERNS, PERL_CORE=1,
+PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST, PERL_TEST_Net_Ping,
+PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS, PERL_TEST_MEMORY
+.IP "Performance testing" 4
+.IX Item "Performance testing"
+.PD 0
+.IP "Building perl at older commits" 4
+.IX Item "Building perl at older commits"
+.RE
+.RS 4
+.RE
+.IP "MORE READING FOR GUTS HACKERS" 4
+.IX Item "MORE READING FOR GUTS HACKERS"
+.PD
+perlsource, perlinterp, perlhacktut, perlhacktips, perlguts,
+perlxstut and perlxs, perlapi, \fIPorting/pumpkin.pod\fR
+.IP "CPAN TESTERS AND PERL SMOKERS" 4
+.IX Item "CPAN TESTERS AND PERL SMOKERS"
+.PD 0
+.IP "WHAT NEXT?" 4
+.IX Item "WHAT NEXT?"
+.RS 4
+.IP """The Road goes ever on and on, down from the door where it began.""" 4
+.IX Item """The Road goes ever on and on, down from the door where it began."""
+.IP "Metaphoric Quotations" 4
+.IX Item "Metaphoric Quotations"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlsource \- A guide to the Perl source tree"
+.IX Subsection "perlsource - A guide to the Perl source tree"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "FINDING YOUR WAY AROUND" 4
+.IX Item "FINDING YOUR WAY AROUND"
+.RS 4
+.IP "C code" 4
+.IX Item "C code"
+.IP "Core modules" 4
+.IX Item "Core modules"
+.PD
+\&\fIlib/\fR, \fIext/\fR, \fIdist/\fR, \fIcpan/\fR
+.IP Tests 4
+.IX Item "Tests"
+Module tests, \fIt/base/\fR, \fIt/cmd/\fR, \fIt/comp/\fR, \fIt/io/\fR, \fIt/mro/\fR,
+\&\fIt/op/\fR, \fIt/opbasic/\fR, \fIt/re/\fR, \fIt/run/\fR, \fIt/uni/\fR, \fIt/win32/\fR,
+\&\fIt/porting/\fR, \fIt/lib/\fR
+.IP Documentation 4
+.IX Item "Documentation"
+.PD 0
+.IP "Hacking tools and documentation" 4
+.IX Item "Hacking tools and documentation"
+.PD
+\&\fIcheck*\fR, \fIMaintainers\fR, \fIMaintainers.pl\fR, and \fIMaintainers.pm\fR,
+\&\fIpodtidy\fR
+.IP "Build system" 4
+.IX Item "Build system"
+.PD 0
+.IP \fIAUTHORS\fR 4
+.IX Item "AUTHORS"
+.IP \fIMANIFEST\fR 4
+.IX Item "MANIFEST"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlinterp \- An overview of the Perl interpreter"
+.IX Subsection "perlinterp - An overview of the Perl interpreter"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "ELEMENTS OF THE INTERPRETER" 4
+.IX Item "ELEMENTS OF THE INTERPRETER"
+.RS 4
+.IP Startup 4
+.IX Item "Startup"
+.IP Parsing 4
+.IX Item "Parsing"
+.IP Optimization 4
+.IX Item "Optimization"
+.IP Running 4
+.IX Item "Running"
+.IP "Exception handing" 4
+.IX Item "Exception handing"
+.PD
+level 2: perl-level \fBexit()\fR and internals \fBmy_exit()\fR, level 3: perl-level
+\&\fBdie()\fR and internals \fBcroak()\fR, level 1: unused, level 0: normal return
+.IP "INTERNAL VARIABLE TYPES" 4
+.IX Item "INTERNAL VARIABLE TYPES"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OP TREES" 4
+.IX Item "OP TREES"
+.IP STACKS 4
+.IX Item "STACKS"
+.RS 4
+.IP "Argument stack" 4
+.IX Item "Argument stack"
+.IP "Mark stack" 4
+.IX Item "Mark stack"
+.IP "Save stack" 4
+.IX Item "Save stack"
+.RE
+.RS 4
+.RE
+.IP "MILLIONS OF MACROS" 4
+.IX Item "MILLIONS OF MACROS"
+.IP "FURTHER READING" 4
+.IX Item "FURTHER READING"
+.PD
+.SS "perlhacktut \- Walk through the creation of a simple C code patch"
+.IX Subsection "perlhacktut - Walk through the creation of a simple C code patch"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "EXAMPLE OF A SIMPLE PATCH" 4
+.IX Item "EXAMPLE OF A SIMPLE PATCH"
+.RS 4
+.IP "Writing the patch" 4
+.IX Item "Writing the patch"
+.IP "Testing the patch" 4
+.IX Item "Testing the patch"
+.IP "Documenting the patch" 4
+.IX Item "Documenting the patch"
+.IP Submit 4
+.IX Item "Submit"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlhacktips \- Tips for Perl core C code hacking"
+.IX Subsection "perlhacktips - Tips for Perl core C code hacking"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "COMMON PROBLEMS" 4
+.IX Item "COMMON PROBLEMS"
+.RS 4
+.IP "Perl environment problems" 4
+.IX Item "Perl environment problems"
+.IP C99 4
+.IX Item "C99"
+.PD
+AIX, HP/UX, Solaris
+.IP "Symbol Names and Namespace Pollution" 4
+.IX Item "Symbol Names and Namespace Pollution"
+\&\fBDon't begin a symbol name with an underscore\fR; (\fIe.g.\fR, don't use:
+\&\f(CW\*(C`_FOOBAR\*(C'\fR), \fBDon't use two consecutive underscores in a symbol name\fR;
+(\fIe.g.\fR, don't use \f(CW\*(C`FOO_\|_BAR\*(C'\fR)
+.IP "Writing safer macros" 4
+.IX Item "Writing safer macros"
+.PD 0
+.IP "Portability problems" 4
+.IX Item "Portability problems"
+.IP "Problematic System Interfaces" 4
+.IX Item "Problematic System Interfaces"
+.IP "Security problems" 4
+.IX Item "Security problems"
+.RE
+.RS 4
+.RE
+.IP DEBUGGING 4
+.IX Item "DEBUGGING"
+.RS 4
+.IP "Poking at Perl" 4
+.IX Item "Poking at Perl"
+.IP "Using a source-level debugger" 4
+.IX Item "Using a source-level debugger"
+.PD
+run [args], break function_name, break source.c:xxx, step, next, continue,
+finish, 'enter', ptype, print
+.IP "gdb macro support" 4
+.IX Item "gdb macro support"
+.PD 0
+.IP "Dumping Perl Data Structures" 4
+.IX Item "Dumping Perl Data Structures"
+.IP "Using gdb to look at specific parts of a program" 4
+.IX Item "Using gdb to look at specific parts of a program"
+.IP "Using gdb to look at what the parser/lexer are doing" 4
+.IX Item "Using gdb to look at what the parser/lexer are doing"
+.RE
+.RS 4
+.RE
+.IP "SOURCE CODE STATIC ANALYSIS" 4
+.IX Item "SOURCE CODE STATIC ANALYSIS"
+.RS 4
+.IP lint 4
+.IX Item "lint"
+.IP Coverity 4
+.IX Item "Coverity"
+.IP "HP-UX cadvise (Code Advisor)" 4
+.IX Item "HP-UX cadvise (Code Advisor)"
+.IP "cpd (cut-and-paste detector)" 4
+.IX Item "cpd (cut-and-paste detector)"
+.IP "gcc warnings" 4
+.IX Item "gcc warnings"
+.IP "Warnings of other C compilers" 4
+.IX Item "Warnings of other C compilers"
+.RE
+.RS 4
+.RE
+.IP "MEMORY DEBUGGERS" 4
+.IX Item "MEMORY DEBUGGERS"
+.RS 4
+.IP valgrind 4
+.IX Item "valgrind"
+.IP AddressSanitizer 4
+.IX Item "AddressSanitizer"
+.PD
+\&\-Dcc=clang, \-Accflags=\-fsanitize=address, \-Aldflags=\-fsanitize=address,
+\&\-Alddlflags=\-shared\e \-fsanitize=address,
+\&\-fsanitize\-blacklist=`pwd`/asan_ignore
+.RE
+.RS 4
+.RE
+.IP PROFILING 4
+.IX Item "PROFILING"
+.RS 4
+.PD 0
+.IP "Gprof Profiling" 4
+.IX Item "Gprof Profiling"
+.PD
+\&\-a, \-b, \-e routine, \-f routine, \-s, \-z
+.IP "GCC gcov Profiling" 4
+.IX Item "GCC gcov Profiling"
+.PD 0
+.IP "callgrind profiling" 4
+.IX Item "callgrind profiling"
+.PD
+\&\-\-threshold, \-\-auto
+.RE
+.RS 4
+.RE
+.IP "MISCELLANEOUS TRICKS" 4
+.IX Item "MISCELLANEOUS TRICKS"
+.RS 4
+.PD 0
+.IP PERL_DESTRUCT_LEVEL 4
+.IX Item "PERL_DESTRUCT_LEVEL"
+.IP PERL_MEM_LOG 4
+.IX Item "PERL_MEM_LOG"
+.IP "DDD over gdb" 4
+.IX Item "DDD over gdb"
+.IP "C backtrace" 4
+.IX Item "C backtrace"
+.PD
+Linux, OS X, get_c_backtrace, free_c_backtrace, get_c_backtrace_dump,
+dump_c_backtrace
+.IP Poison 4
+.IX Item "Poison"
+.PD 0
+.IP "Read-only optrees" 4
+.IX Item "Read-only optrees"
+.IP "When is a bool not a bool?" 4
+.IX Item "When is a bool not a bool?"
+.IP "Finding unsafe truncations" 4
+.IX Item "Finding unsafe truncations"
+.IP "The .i Targets" 4
+.IX Item "The .i Targets"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlpolicy \- Various and sundry policies and commitments related to the Perl core"
+.IX Subsection "perlpolicy - Various and sundry policies and commitments related to the Perl core"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP GOVERNANCE 4
+.IX Item "GOVERNANCE"
+.RS 4
+.IP "Perl 5 Porters" 4
+.IX Item "Perl 5 Porters"
+.RE
+.RS 4
+.RE
+.IP "MAINTENANCE AND SUPPORT" 4
+.IX Item "MAINTENANCE AND SUPPORT"
+.IP "BACKWARD COMPATIBILITY AND DEPRECATION" 4
+.IX Item "BACKWARD COMPATIBILITY AND DEPRECATION"
+.RS 4
+.IP Terminology 4
+.IX Item "Terminology"
+.PD
+experimental, deprecated, discouraged, removed
+.RE
+.RS 4
+.RE
+.IP "MAINTENANCE BRANCHES" 4
+.IX Item "MAINTENANCE BRANCHES"
+.RS 4
+.PD 0
+.IP "Getting changes into a maint branch" 4
+.IX Item "Getting changes into a maint branch"
+.RE
+.RS 4
+.RE
+.IP "CONTRIBUTED MODULES" 4
+.IX Item "CONTRIBUTED MODULES"
+.RS 4
+.IP "A Social Contract about Artistic Control" 4
+.IX Item "A Social Contract about Artistic Control"
+.RE
+.RS 4
+.RE
+.IP DOCUMENTATION 4
+.IX Item "DOCUMENTATION"
+.IP "STANDARDS OF CONDUCT" 4
+.IX Item "STANDARDS OF CONDUCT"
+.IP CREDITS 4
+.IX Item "CREDITS"
+.PD
+.SS "perlgov \- Perl Rules of Governance"
+.IX Subsection "perlgov - Perl Rules of Governance"
+.IP PREAMBLE 4
+.IX Item "PREAMBLE"
+.PD 0
+.IP Mandate 4
+.IX Item "Mandate"
+.IP Definitions 4
+.IX Item "Definitions"
+.PD
+"Core Team", "Steering Council", "Vote Administrator"
+.RS 4
+.IP "The Core Team" 4
+.IX Item "The Core Team"
+.PD 0
+.IP "The Steering Council" 4
+.IX Item "The Steering Council"
+.IP "The Vote Administrator" 4
+.IX Item "The Vote Administrator"
+.RE
+.RS 4
+.RE
+.IP "Steering Council and Core Team Members" 4
+.IX Item "Steering Council and Core Team Members"
+.IP "Steering Council Members" 4
+.IX Item "Steering Council Members"
+.PD
+Paul Evans, Philippe Bruhat, Ricardo Signes
+.IP "Core Team Members" 4
+.IX Item "Core Team Members"
+.RS 4
+.PD 0
+.IP "Active Members" 4
+.IX Item "Active Members"
+.PD
+Chad Granum <exodist7@gmail.com>, Chris 'BinGOs' Williams
+<chris@bingosnet.co.uk>, Craig Berry <craigberry@mac.com>, Dagfinn Ilmari
+Mannsåker <ilmari@ilmari.org>, David Mitchell <davem@iabyn.com>, Graham
+Knop <haarg@haarg.org>, H. Merijn Brand <perl5@tux.freedom.nl>, Hugo van
+der Sanden <hv@crypt.org>, James E Keenan <jkeenan@cpan.org>, Karen
+Etheridge <ether@cpan.org>, Karl Williamson <khw@cpan.org>, Leon Timmermans
+<fawaka@gmail.com>, Matthew Horsfall <wolfsage@gmail.com>, Max Maischein
+<cpan@corion.net>, Neil Bowers <neilb@neilb.org>, Nicholas Clark
+<nick@ccl4.org>, Nicolas R <atoomic@cpan.org>, Paul "LeoNerd" Evans
+<leonerd@leonerd.org.uk>, Philippe "BooK" Bruhat <book@cpan.org>, Ricardo
+Signes <rjbs@semiotic.systems>, Steve Hay <steve.m.hay@googlemail.com>,
+Stuart Mackintosh <stuart@perlfoundation.org>, Todd Rinaldo
+<toddr@cpanel.net>, Tony Cook <tony@develop\-help.com>, Yves Orton
+<demerphq@gmail.com>
+.IP "Inactive Members" 4
+.IX Item "Inactive Members"
+Abhijit Menon-Sen <ams@toroid.org>, Andy Dougherty
+<doughera@lafayette.edu>, David Golden <xdg@xdg.me>, Jan Dubois
+<jan@jandubois.com>, Jason McIntosh <jmac@jmac.org>, Jesse Vincent
+<jesse@fsck.com>
+.RE
+.RS 4
+.RE
+.SS "perlgit \- Detailed information about git and the Perl repository"
+.IX Subsection "perlgit - Detailed information about git and the Perl repository"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "CLONING THE REPOSITORY" 4
+.IX Item "CLONING THE REPOSITORY"
+.IP "WORKING WITH THE REPOSITORY" 4
+.IX Item "WORKING WITH THE REPOSITORY"
+.RS 4
+.IP "Finding out your status" 4
+.IX Item "Finding out your status"
+.IP "Patch workflow" 4
+.IX Item "Patch workflow"
+.IP "A note on derived files" 4
+.IX Item "A note on derived files"
+.IP "Cleaning a working directory" 4
+.IX Item "Cleaning a working directory"
+.IP Bisecting 4
+.IX Item "Bisecting"
+.IP "Topic branches and rewriting history" 4
+.IX Item "Topic branches and rewriting history"
+.IP Grafts 4
+.IX Item "Grafts"
+.RE
+.RS 4
+.RE
+.IP "WRITE ACCESS TO THE GIT REPOSITORY" 4
+.IX Item "WRITE ACCESS TO THE GIT REPOSITORY"
+.RS 4
+.IP "Working with Github pull requests" 4
+.IX Item "Working with Github pull requests"
+.IP "Accepting a patch" 4
+.IX Item "Accepting a patch"
+.IP "Committing to blead" 4
+.IX Item "Committing to blead"
+.IP "On merging and rebasing" 4
+.IX Item "On merging and rebasing"
+.IP "Committing to maintenance versions" 4
+.IX Item "Committing to maintenance versions"
+.IP "Using a smoke-me branch to test changes" 4
+.IX Item "Using a smoke-me branch to test changes"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlhist \- the Perl history records"
+.IX Subsection "perlhist - the Perl history records"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP INTRODUCTION 4
+.IX Item "INTRODUCTION"
+.IP "THE KEEPERS OF THE PUMPKIN" 4
+.IX Item "THE KEEPERS OF THE PUMPKIN"
+.RS 4
+.IP PUMPKIN? 4
+.IX Item "PUMPKIN?"
+.RE
+.RS 4
+.RE
+.IP "THE RECORDS" 4
+.IX Item "THE RECORDS"
+.RS 4
+.IP "SELECTED RELEASE SIZES" 4
+.IX Item "SELECTED RELEASE SIZES"
+.IP "SELECTED PATCH SIZES" 4
+.IX Item "SELECTED PATCH SIZES"
+.RE
+.RS 4
+.RE
+.IP "THE KEEPERS OF THE RECORDS" 4
+.IX Item "THE KEEPERS OF THE RECORDS"
+.PD
+.SS "perldelta \- what is new for perl v5.38.2"
+.IX Subsection "perldelta - what is new for perl v5.38.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5382delta, perldelta \- what is new for perl v5.38.2"
+.IX Subsection "perl5382delta, perldelta - what is new for perl v5.38.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5381delta \- what is new for perl v5.38.1"
+.IX Subsection "perl5381delta - what is new for perl v5.38.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5380delta \- what is new for perl v5.38.0"
+.IX Subsection "perl5380delta - what is new for perl v5.38.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP "New ""class"" Feature" 4
+.el .IP "New \f(CWclass\fR Feature" 4
+.IX Item "New class Feature"
+.IP "Unicode 15.0 is supported" 4
+.IX Item "Unicode 15.0 is supported"
+.IP "Deprecation warnings now have specific subcategories" 4
+.IX Item "Deprecation warnings now have specific subcategories"
+.IP "%{^HOOK} API introduced" 4
+.IX Item "%{^HOOK} API introduced"
+.IP PERL_RAND_SEED 4
+.IX Item "PERL_RAND_SEED"
+.IP "Defined-or and logical-or assignment default expressions in signatures" 4
+.IX Item "Defined-or and logical-or assignment default expressions in signatures"
+.ie n .IP "@INC Hook Enhancements and $INC and INCDIR" 4
+.el .IP "\f(CW@INC\fR Hook Enhancements and \f(CW$INC\fR and INCDIR" 4
+.IX Item "@INC Hook Enhancements and $INC and INCDIR"
+.ie n .IP "Forbidden control flow out of ""defer"" or ""finally"" now detected at compile-time" 4
+.el .IP "Forbidden control flow out of \f(CWdefer\fR or \f(CWfinally\fR now detected at compile-time" 4
+.IX Item "Forbidden control flow out of defer or finally now detected at compile-time"
+.IP "Optimistic Eval in Patterns" 4
+.IX Item "Optimistic Eval in Patterns"
+.IP "REG_INF has been raised from 65,536 to 2,147,483,647" 4
+.IX Item "REG_INF has been raised from 65,536 to 2,147,483,647"
+.IP "New API functions optimize_optree and finalize_optree" 4
+.IX Item "New API functions optimize_optree and finalize_optree"
+.ie n .IP "Some ""goto""s are now permitted in ""defer"" and ""finally"" blocks" 4
+.el .IP "Some \f(CWgoto\fRs are now permitted in \f(CWdefer\fR and \f(CWfinally\fR blocks" 4
+.IX Item "Some gotos are now permitted in defer and finally blocks"
+.IP "New regexp variable ${^LAST_SUCCESSFUL_PATTERN}" 4
+.IX Item "New regexp variable ${^LAST_SUCCESSFUL_PATTERN}"
+.IP "Locale category LC_NAME now supported on participating platforms" 4
+.IX Item "Locale category LC_NAME now supported on participating platforms"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "\fBreadline()\fR no longer clears the stream error and eof flags" 4
+.IX Item "readline() no longer clears the stream error and eof flags"
+.ie n .IP """INIT"" blocks no longer run after an exit() in ""BEGIN""" 4
+.el .IP "\f(CWINIT\fR blocks no longer run after an \f(CWexit()\fR in \f(CWBEGIN\fR" 4
+.IX Item "INIT blocks no longer run after an exit() in BEGIN"
+.IP "Syntax errors no longer produce ""phantom error messages""" 4
+.IX Item "Syntax errors no longer produce ""phantom error messages"""
+.ie n .IP utf8::upgrade() 4
+.el .IP \f(CWutf8::upgrade()\fR 4
+.IX Item "utf8::upgrade()"
+.IP "Changes to ""thread-safe"" locales" 4
+.IX Item "Changes to ""thread-safe"" locales"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP "Use of ""\*(Aq"" as a package name separator is deprecated" 4
+.el .IP "Use of \f(CW\*(Aq\fR as a package name separator is deprecated" 4
+.IX Item "Use of as a package name separator is deprecated"
+.IP "Switch and Smart Match operator" 4
+.IX Item "Switch and Smart Match operator"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.PD
+Ultrix
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+DragonflyBSD, FreeBSD, Solaris, Synology, Windows
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+\&\f(CW\*(C`newSVbool(const bool bool_val)\*(C'\fR,
+\&\f(CWnewSV_true()\fR,
+\&\f(CWnewSV_false()\fR, \f(CW\*(C`sv_set_true(SV
+*sv)\*(C'\fR, \f(CW\*(C`sv_set_false(SV
+*sv)\*(C'\fR, \f(CW\*(C`sv_set_bool(SV *sv, const bool
+bool_val)\*(C'\fR, \f(CWSvIandPOK(sv)\fR,
+\&\f(CWSvIandPOK_off(sv)\fR,
+\&\f(CW\*(C`SvIandPOK_on\*(C'\fR, I32df \-\- Like \f(CW%d\fR, U32of \-\- Like
+\&\f(CW%o\fR, U32uf \-\- Like \f(CW%u\fR, U32xf \-\- Like \f(CW%x\fR, U32Xf \-\- Like \f(CW%X\fR
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5363delta \- what is new for perl v5.36.3"
+.IX Subsection "perl5363delta - what is new for perl v5.36.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5362delta \- what is new for perl v5.36.2"
+.IX Subsection "perl5362delta - what is new for perl v5.36.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5361delta \- what is new for perl v5.36.1"
+.IX Subsection "perl5361delta - what is new for perl v5.36.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5360delta \- what is new for perl v5.36.0"
+.IX Subsection "perl5360delta - what is new for perl v5.36.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP """use v5.36""" 4
+.el .IP "\f(CWuse v5.36\fR" 4
+.IX Item "use v5.36"
+.IP "\-g command-line flag" 4
+.IX Item "-g command-line flag"
+.IP "Unicode 14.0 is supported" 4
+.IX Item "Unicode 14.0 is supported"
+.IP "regex sets are no longer considered experimental" 4
+.IX Item "regex sets are no longer considered experimental"
+.IP "Variable length lookbehind is mostly no longer considered experimental" 4
+.IX Item "Variable length lookbehind is mostly no longer considered experimental"
+.IP "SIGFPE no longer deferred" 4
+.IX Item "SIGFPE no longer deferred"
+.IP "Stable boolean tracking" 4
+.IX Item "Stable boolean tracking"
+.IP "iterating over multiple values at a time (experimental)" 4
+.IX Item "iterating over multiple values at a time (experimental)"
+.IP "builtin functions (experimental)" 4
+.IX Item "builtin functions (experimental)"
+.PD
+builtin::trim, builtin::indexed, builtin::true, builtin::false,
+builtin::is_bool, builtin::weaken, builtin::unweaken, builtin::is_weak,
+builtin::blessed, builtin::refaddr, builtin::reftype, builtin::ceil,
+builtin::floor
+.ie n .IP """defer"" blocks (experimental)" 4
+.el .IP "\f(CWdefer\fR blocks (experimental)" 4
+.IX Item "defer blocks (experimental)"
+.PD 0
+.ie n .IP "try/catch can now have a ""finally"" block (experimental)" 4
+.el .IP "try/catch can now have a \f(CWfinally\fR block (experimental)" 4
+.IX Item "try/catch can now have a finally block (experimental)"
+.IP "non-ASCII delimiters for quote-like operators (experimental)" 4
+.IX Item "non-ASCII delimiters for quote-like operators (experimental)"
+.ie n .IP "@_ is now experimental within signatured subs" 4
+.el .IP "\f(CW@_\fR is now experimental within signatured subs" 4
+.IX Item "@_ is now experimental within signatured subs"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "A physically empty sort is now a compile-time error" 4
+.IX Item "A physically empty sort is now a compile-time error"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP """use VERSION"" (where VERSION is below v5.11) after ""use v5.11"" is deprecated" 4
+.el .IP "\f(CWuse VERSION\fR (where VERSION is below v5.11) after \f(CWuse v5.11\fR is deprecated" 4
+.IX Item "use VERSION (where VERSION is below v5.11) after use v5.11 is deprecated"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP Windows 4
+.IX Item "Windows"
+.IP VMS 4
+.IX Item "VMS"
+.PD
+\&\f(CW\*(C`keys %ENV\*(C'\fR on VMS returns consistent results
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+AT&T UWIN, DOS/DJGPP, NetWare
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+z/OS
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Errata From Previous Releases" 4
+.IX Item "Errata From Previous Releases"
+.IP Obituaries 4
+.IX Item "Obituaries"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5343delta \- what is new for perl v5.34.3"
+.IX Subsection "perl5343delta - what is new for perl v5.34.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5342delta \- what is new for perl v5.34.2"
+.IX Subsection "perl5342delta - what is new for perl v5.34.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2023\-47038 \- Write past buffer end via illegal user-defined Unicode property" 4
+.IX Item "CVE-2023-47038 - Write past buffer end via illegal user-defined Unicode property"
+.IP "CVE\-2023\-47039 \- Perl for Windows binary hijacking vulnerability" 4
+.IX Item "CVE-2023-47039 - Perl for Windows binary hijacking vulnerability"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5341delta \- what is new for perl v5.34.1"
+.IX Subsection "perl5341delta - what is new for perl v5.34.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Windows
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5340delta \- what is new for perl v5.34.0"
+.IX Subsection "perl5340delta - what is new for perl v5.34.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Experimental Try/Catch Syntax" 4
+.IX Item "Experimental Try/Catch Syntax"
+.ie n .IP """qr/{,n}/"" is now accepted" 4
+.el .IP "\f(CWqr/{,n}/\fR is now accepted" 4
+.IX Item "qr/{,n}/ is now accepted"
+.RE
+.RS 4
+.RE
+.IP "Blanks freely allowed within but adjacent to curly braces" 4
+.IX Item "Blanks freely allowed within but adjacent to curly braces"
+.ie n .IP "New octal syntax ""0o\fIddddd\fR""" 4
+.el .IP "New octal syntax \f(CW0o\fR\f(CIddddd\fR\f(CW\fR" 4
+.IX Item "New octal syntax 0oddddd"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "perl5db.pl (the debugger)" 4
+.IX Item "perl5db.pl (the debugger)"
+.PD
+New option: \f(CW\*(C`HistItemMinLength\*(C'\fR, Fix to \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`l\*(C'\fR commands
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+stadtx hash support has been removed, Configure, \f(CW\*(C`\-Dusedefaultstrict\*(C'\fR
+.IP Testing 4
+.IX Item "Testing"
+.PD 0
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.PD
+9front
+.IP "Updated Platforms" 4
+.IX Item "Updated Platforms"
+Plan9, MacOS (Darwin)
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+Symbian
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+DragonFlyBSD, Mac OS X, Windows, z/OS
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD
+pack/unpack format 'D' now works on all systems that could support it
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.PD 0
+.IP "Errata From Previous Releases" 4
+.IX Item "Errata From Previous Releases"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5321delta \- what is new for perl v5.32.1"
+.IX Subsection "perl5321delta - what is new for perl v5.32.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+MacOS (Darwin), Minix
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5320delta \- what is new for perl v5.32.0"
+.IX Subsection "perl5320delta - what is new for perl v5.32.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "The isa Operator" 4
+.IX Item "The isa Operator"
+.IP "Unicode 13.0 is supported" 4
+.IX Item "Unicode 13.0 is supported"
+.IP "Chained comparisons capability" 4
+.IX Item "Chained comparisons capability"
+.ie n .IP "New Unicode properties ""Identifier_Status"" and ""Identifier_Type"" supported" 4
+.el .IP "New Unicode properties \f(CWIdentifier_Status\fR and \f(CWIdentifier_Type\fR supported" 4
+.IX Item "New Unicode properties Identifier_Status and Identifier_Type supported"
+.ie n .IP "It is now possible to write ""qr/\ep{Name=...}/"", or ""qr!\ep{na=/(SMILING|GRINNING) FACE/}!""" 4
+.el .IP "It is now possible to write \f(CWqr/\ep{Name=...}/\fR, or \f(CWqr!\ep{na=/(SMILING|GRINNING) FACE/}!\fR" 4
+.IX Item "It is now possible to write qr/p{Name=...}/, or qr!p{na=/(SMILING|GRINNING) FACE/}!"
+.ie n .IP "Improvement of POSIX::mblen(), ""mbtowc"", and ""wctomb""" 4
+.el .IP "Improvement of \f(CWPOSIX::mblen()\fR, \f(CWmbtowc\fR, and \f(CWwctomb\fR" 4
+.IX Item "Improvement of POSIX::mblen(), mbtowc, and wctomb"
+.IP "Alpha assertions are no longer experimental" 4
+.IX Item "Alpha assertions are no longer experimental"
+.IP "Script runs are no longer experimental" 4
+.IX Item "Script runs are no longer experimental"
+.IP "Feature checks are now faster" 4
+.IX Item "Feature checks are now faster"
+.IP "Perl is now developed on GitHub" 4
+.IX Item "Perl is now developed on GitHub"
+.IP "Compiled patterns can now be dumped before optimization" 4
+.IX Item "Compiled patterns can now be dumped before optimization"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+.IP "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression" 4
+.IX Item "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IP "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+.IP "Additional Note" 4
+.IX Item "Additional Note"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Certain pattern matching features are now prohibited in compiling Unicode property value wildcard subpatterns" 4
+.IX Item "Certain pattern matching features are now prohibited in compiling Unicode property value wildcard subpatterns"
+.ie n .IP "Unused functions ""POSIX::mbstowcs"" and ""POSIX::wcstombs"" are removed" 4
+.el .IP "Unused functions \f(CWPOSIX::mbstowcs\fR and \f(CWPOSIX::wcstombs\fR are removed" 4
+.IX Item "Unused functions POSIX::mbstowcs and POSIX::wcstombs are removed"
+.ie n .IP "A bug fix for ""(?[...])"" may have caused some patterns to no longer compile" 4
+.el .IP "A bug fix for \f(CW(?[...])\fR may have caused some patterns to no longer compile" 4
+.IX Item "A bug fix for (?[...]) may have caused some patterns to no longer compile"
+.ie n .IP """\ep{\fIuser\-defined\fR}"" properties now always override official Unicode ones" 4
+.el .IP "\f(CW\ep{\fR\f(CIuser\-defined\fR\f(CW}\fR properties now always override official Unicode ones" 4
+.IX Item "p{user-defined} properties now always override official Unicode ones"
+.IP "Modifiable variables are no longer permitted in constants" 4
+.IX Item "Modifiable variables are no longer permitted in constants"
+.ie n .IP "Use of ""vec"" on strings with code points above 0xFF is forbidden" 4
+.el .IP "Use of \f(CWvec\fR on strings with code points above 0xFF is forbidden" 4
+.IX Item "Use of vec on strings with code points above 0xFF is forbidden"
+.IP "Use of code points over 0xFF in string bitwise operators" 4
+.IX Item "Use of code points over 0xFF in string bitwise operators"
+.ie n .IP "Sys::Hostname::hostname() does not accept arguments" 4
+.el .IP "\f(CWSys::Hostname::hostname()\fR does not accept arguments" 4
+.IX Item "Sys::Hostname::hostname() does not accept arguments"
+.IP "Plain ""0"" string now treated as a number for range operator" 4
+.IX Item "Plain ""0"" string now treated as a number for range operator"
+.ie n .IP """\eK"" now disallowed in look-ahead and look-behind assertions" 4
+.el .IP "\f(CW\eK\fR now disallowed in look-ahead and look-behind assertions" 4
+.IX Item "K now disallowed in look-ahead and look-behind assertions"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.PD
+\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`_\|_FILE_\|_\*(C'\fR, \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`open\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.PD 0
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP perlbug 4
+.IX Item "perlbug"
+.PD
+The bug tracker homepage URL now points to GitHub
+.IP streamzip 4
+.IX Item "streamzip"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.RS 4
+.IP \fIConfigure\fR 4
+.IX Item "Configure"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.PD
+Windows CE
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+Linux, NetBSD 8.0, Windows, Solaris, VMS, z/OS
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5303delta \- what is new for perl v5.30.3"
+.IX Subsection "perl5303delta - what is new for perl v5.30.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+.IP "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression" 4
+.IX Item "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IP "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+.IP "Additional Note" 4
+.IX Item "Additional Note"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5302delta \- what is new for perl v5.30.2"
+.IX Subsection "perl5302delta - what is new for perl v5.30.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Windows
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5301delta \- what is new for perl v5.30.1"
+.IX Subsection "perl5301delta - what is new for perl v5.30.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Win32
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5300delta \- what is new for perl v5.30.0"
+.IX Subsection "perl5300delta - what is new for perl v5.30.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Notice 4
+.IX Item "Notice"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Limited variable length lookbehind in regular expression pattern matching is now experimentally supported" 4
+.IX Item "Limited variable length lookbehind in regular expression pattern matching is now experimentally supported"
+.ie n .IP "The upper limit ""n"" specifiable in a regular expression quantifier of the form ""{m,n}"" has been doubled to 65534" 4
+.el .IP "The upper limit \f(CW""n""\fR specifiable in a regular expression quantifier of the form \f(CW""{m,n}""\fR has been doubled to 65534" 4
+.IX Item "The upper limit ""n"" specifiable in a regular expression quantifier of the form ""{m,n}"" has been doubled to 65534"
+.IP "Unicode 12.1 is supported" 4
+.IX Item "Unicode 12.1 is supported"
+.IP "Wildcards in Unicode property value specifications are now partially supported" 4
+.IX Item "Wildcards in Unicode property value specifications are now partially supported"
+.IP "qr'\eN{name}' is now supported" 4
+.IX Item "qr'N{name}' is now supported"
+.IP "Turkic UTF\-8 locales are now seamlessly supported" 4
+.IX Item "Turkic UTF-8 locales are now seamlessly supported"
+.IP "It is now possible to compile perl to always use thread-safe locale operations." 4
+.IX Item "It is now possible to compile perl to always use thread-safe locale operations."
+.IP "Eliminate opASSIGN macro usage from core" 4
+.IX Item "Eliminate opASSIGN macro usage from core"
+.ie n .IP """\-Drv"" now means something on ""\-DDEBUGGING"" builds" 4
+.el .IP "\f(CW\-Drv\fR now means something on \f(CW\-DDEBUGGING\fR builds" 4
+.IX Item "-Drv now means something on -DDEBUGGING builds"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.ie n .IP "Assigning non-zero to $[ is fatal" 4
+.el .IP "Assigning non-zero to \f(CW$[\fR is fatal" 4
+.IX Item "Assigning non-zero to $[ is fatal"
+.IP "Delimiters must now be graphemes" 4
+.IX Item "Delimiters must now be graphemes"
+.ie n .IP "Some formerly deprecated uses of an unescaped left brace ""{"" in regular expression patterns are now illegal" 4
+.el .IP "Some formerly deprecated uses of an unescaped left brace \f(CW""{""\fR in regular expression patterns are now illegal" 4
+.IX Item "Some formerly deprecated uses of an unescaped left brace ""{"" in regular expression patterns are now illegal"
+.IP "Previously deprecated \fBsysread()\fR/\fBsyswrite()\fR on :utf8 handles is now fatal" 4
+.IX Item "Previously deprecated sysread()/syswrite() on :utf8 handles is now fatal"
+.IP "\fBmy()\fR in false conditional prohibited" 4
+.IX Item "my() in false conditional prohibited"
+.IP "Fatalize $* and $#" 4
+.IX Item "Fatalize $* and $#"
+.IP "Fatalize unqualified use of \fBdump()\fR" 4
+.IX Item "Fatalize unqualified use of dump()"
+.IP "Remove \fBFile::Glob::glob()\fR" 4
+.IX Item "Remove File::Glob::glob()"
+.ie n .IP "pack() no longer can return malformed UTF\-8" 4
+.el .IP "\f(CWpack()\fR no longer can return malformed UTF\-8" 4
+.IX Item "pack() no longer can return malformed UTF-8"
+.IP "Any set of digits in the Common script are legal in a script run of another script" 4
+.IX Item "Any set of digits in the Common script are legal in a script run of another script"
+.IP "JSON::PP enables allow_nonref by default" 4
+.IX Item "JSON::PP enables allow_nonref by default"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.IP "In XS code, use of various macros dealing with UTF\-8." 4
+.IX Item "In XS code, use of various macros dealing with UTF-8."
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP xsubpp 4
+.IX Item "xsubpp"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+HP-UX 11.11, Mac OS X, Minix3, Cygwin, Win32 Mingw, Windows
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5283delta \- what is new for perl v5.28.3"
+.IX Subsection "perl5283delta - what is new for perl v5.28.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2020\-10543] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-10543] Buffer overflow caused by a crafted regular expression"
+.IP "[CVE\-2020\-10878] Integer overflow via malformed bytecode produced by a crafted regular expression" 4
+.IX Item "[CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression"
+.IP "[CVE\-2020\-12723] Buffer overflow caused by a crafted regular expression" 4
+.IX Item "[CVE-2020-12723] Buffer overflow caused by a crafted regular expression"
+.IP "Additional Note" 4
+.IX Item "Additional Note"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5282delta \- what is new for perl v5.28.2"
+.IX Subsection "perl5282delta - what is new for perl v5.28.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Any set of digits in the Common script are legal in a script run of another script" 4
+.IX Item "Any set of digits in the Common script are legal in a script run of another script"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Windows, Mac OS X
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5281delta \- what is new for perl v5.28.1"
+.IX Subsection "perl5281delta - what is new for perl v5.28.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2018\-18311] Integer overflow leading to buffer overflow and segmentation fault" 4
+.IX Item "[CVE-2018-18311] Integer overflow leading to buffer overflow and segmentation fault"
+.IP "[CVE\-2018\-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)" 4
+.IX Item "[CVE-2018-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5280delta \- what is new for perl v5.28.0"
+.IX Subsection "perl5280delta - what is new for perl v5.28.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Unicode 10.0 is supported" 4
+.IX Item "Unicode 10.0 is supported"
+.ie n .IP """delete"" on key/value hash slices" 4
+.el .IP "\f(CWdelete\fR on key/value hash slices" 4
+.IX Item "delete on key/value hash slices"
+.IP "Experimentally, there are now alphabetic synonyms for some regular expression assertions" 4
+.IX Item "Experimentally, there are now alphabetic synonyms for some regular expression assertions"
+.IP "Mixed Unicode scripts are now detectable" 4
+.IX Item "Mixed Unicode scripts are now detectable"
+.ie n .IP "In-place editing with ""perl \-i"" is now safer" 4
+.el .IP "In-place editing with \f(CWperl \-i\fR is now safer" 4
+.IX Item "In-place editing with perl -i is now safer"
+.IP "Initialisation of aggregate state variables" 4
+.IX Item "Initialisation of aggregate state variables"
+.IP "Full-size inode numbers" 4
+.IX Item "Full-size inode numbers"
+.ie n .IP "The ""sprintf"" %j format size modifier is now available with pre\-C99 compilers" 4
+.el .IP "The \f(CWsprintf\fR \f(CW%j\fR format size modifier is now available with pre\-C99 compilers" 4
+.IX Item "The sprintf %j format size modifier is now available with pre-C99 compilers"
+.IP "Close-on-exec flag set atomically" 4
+.IX Item "Close-on-exec flag set atomically"
+.IP "String\- and number-specific bitwise ops are no longer experimental" 4
+.IX Item "String- and number-specific bitwise ops are no longer experimental"
+.IP "Locales are now thread-safe on systems that support them" 4
+.IX Item "Locales are now thread-safe on systems that support them"
+.ie n .IP "New read-only predefined variable ""${^SAFE_LOCALES}""" 4
+.el .IP "New read-only predefined variable \f(CW${^SAFE_LOCALES}\fR" 4
+.IX Item "New read-only predefined variable ${^SAFE_LOCALES}"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler" 4
+.IX Item "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+.IP "[CVE\-2017\-12883] Buffer over-read in regular expression parser" 4
+.IX Item "[CVE-2017-12883] Buffer over-read in regular expression parser"
+.ie n .IP "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows" 4
+.el .IP "[CVE\-2017\-12814] \f(CW$ENV{$key}\fR stack buffer overflow on Windows" 4
+.IX Item "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+.IP "Default Hash Function Change" 4
+.IX Item "Default Hash Function Change"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Subroutine attribute and signature order" 4
+.IX Item "Subroutine attribute and signature order"
+.IP "Comma-less variable lists in formats are no longer allowed" 4
+.IX Item "Comma-less variable lists in formats are no longer allowed"
+.ie n .IP "The "":locked"" and "":unique"" attributes have been removed" 4
+.el .IP "The \f(CW:locked\fR and \f(CW:unique\fR attributes have been removed" 4
+.IX Item "The :locked and :unique attributes have been removed"
+.ie n .IP """\eN{}"" with nothing between the braces is now illegal" 4
+.el .IP "\f(CW\eN{}\fR with nothing between the braces is now illegal" 4
+.IX Item "N{} with nothing between the braces is now illegal"
+.IP "Opening the same symbol as both a file and directory handle is no longer allowed" 4
+.IX Item "Opening the same symbol as both a file and directory handle is no longer allowed"
+.ie n .IP "Use of bare ""<<"" to mean ""<<"""""" is no longer allowed" 4
+.el .IP "Use of bare \f(CW<<\fR to mean \f(CW<<""""\fR is no longer allowed" 4
+.IX Item "Use of bare << to mean <<"""" is no longer allowed"
+.IP "Setting $/ to a reference to a non-positive integer no longer allowed" 4
+.IX Item "Setting $/ to a reference to a non-positive integer no longer allowed"
+.ie n .IP "Unicode code points with values exceeding ""IV_MAX"" are now fatal" 4
+.el .IP "Unicode code points with values exceeding \f(CWIV_MAX\fR are now fatal" 4
+.IX Item "Unicode code points with values exceeding IV_MAX are now fatal"
+.ie n .IP "The ""B::OP::terse"" method has been removed" 4
+.el .IP "The \f(CWB::OP::terse\fR method has been removed" 4
+.IX Item "The B::OP::terse method has been removed"
+.IP "Use of inherited AUTOLOAD for non-methods is no longer allowed" 4
+.IX Item "Use of inherited AUTOLOAD for non-methods is no longer allowed"
+.IP "Use of strings with code points over 0xFF is not allowed for bitwise string operators" 4
+.IX Item "Use of strings with code points over 0xFF is not allowed for bitwise string operators"
+.ie n .IP "Setting ""${^ENCODING}"" to a defined value is now illegal" 4
+.el .IP "Setting \f(CW${^ENCODING}\fR to a defined value is now illegal" 4
+.IX Item "Setting ${^ENCODING} to a defined value is now illegal"
+.ie n .IP "Backslash no longer escapes colon in PATH for the ""\-S"" switch" 4
+.el .IP "Backslash no longer escapes colon in PATH for the \f(CW\-S\fR switch" 4
+.IX Item "Backslash no longer escapes colon in PATH for the -S switch"
+.IP "the \-DH (DEBUG_H) misfeature has been removed" 4
+.IX Item "the -DH (DEBUG_H) misfeature has been removed"
+.IP "Yada-yada is now strictly a statement" 4
+.IX Item "Yada-yada is now strictly a statement"
+.IP "Sort algorithm can no longer be specified" 4
+.IX Item "Sort algorithm can no longer be specified"
+.IP "Over-radix digits in floating point literals" 4
+.IX Item "Over-radix digits in floating point literals"
+.ie n .IP "Return type of unpackstring()" 4
+.el .IP "Return type of \f(CWunpackstring()\fR" 4
+.IX Item "Return type of unpackstring()"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP "Use of ""vec"" on strings with code points above 0xFF is deprecated" 4
+.el .IP "Use of \f(CWvec\fR on strings with code points above 0xFF is deprecated" 4
+.IX Item "Use of vec on strings with code points above 0xFF is deprecated"
+.ie n .IP "Some uses of unescaped ""{"" in regexes are no longer fatal" 4
+.el .IP "Some uses of unescaped \f(CW""{""\fR in regexes are no longer fatal" 4
+.IX Item "Some uses of unescaped ""{"" in regexes are no longer fatal"
+.ie n .IP "Use of unescaped ""{"" immediately after a ""("" in regular expression patterns is deprecated" 4
+.el .IP "Use of unescaped \f(CW""{""\fR immediately after a \f(CW""(""\fR in regular expression patterns is deprecated" 4
+.IX Item "Use of unescaped ""{"" immediately after a ""("" in regular expression patterns is deprecated"
+.ie n .IP "Assignment to $[ will be fatal in Perl 5.30" 4
+.el .IP "Assignment to \f(CW$[\fR will be fatal in Perl 5.30" 4
+.IX Item "Assignment to $[ will be fatal in Perl 5.30"
+.IP "\fBhostname()\fR won't accept arguments in Perl 5.32" 4
+.IX Item "hostname() won't accept arguments in Perl 5.32"
+.IP "Module removals" 4
+.IX Item "Module removals"
+.PD
+B::Debug, Locale::Codes and its associated Country, Currency and
+Language modules
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Removal of use vars" 4
+.IX Item "Removal of use vars"
+.IP "Use of DynaLoader changed to XSLoader in many modules" 4
+.IX Item "Use of DynaLoader changed to XSLoader in many modules"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.PD
+"Variable length lookbehind not implemented in regex
+m/%s/" in perldiag, "Use of state \f(CW$_\fR is experimental" in perldiag
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.PD 0
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP perlbug 4
+.IX Item "perlbug"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.PD
+C89 requirement, New probes, HAS_BUILTIN_ADD_OVERFLOW,
+HAS_BUILTIN_MUL_OVERFLOW, HAS_BUILTIN_SUB_OVERFLOW,
+HAS_THREAD_SAFE_NL_LANGINFO_L, HAS_LOCALECONV_L, HAS_MBRLEN, HAS_MBRTOWC,
+HAS_MEMRCHR, HAS_NANOSLEEP, HAS_STRNLEN, HAS_STRTOLD_L, I_WCHAR
+.IP Testing 4
+.IX Item "Testing"
+.PD 0
+.IP Packaging 4
+.IX Item "Packaging"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.PD
+PowerUX / Power MAX OS
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+CentOS, Cygwin, Darwin, FreeBSD, VMS, Windows
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5263delta \- what is new for perl v5.26.3"
+.IX Subsection "perl5263delta - what is new for perl v5.26.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2018\-12015] Directory traversal in module Archive::Tar" 4
+.IX Item "[CVE-2018-12015] Directory traversal in module Archive::Tar"
+.IP "[CVE\-2018\-18311] Integer overflow leading to buffer overflow and segmentation fault" 4
+.IX Item "[CVE-2018-18311] Integer overflow leading to buffer overflow and segmentation fault"
+.IP "[CVE\-2018\-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)" 4
+.IX Item "[CVE-2018-18312] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.IP "[CVE\-2018\-18313] Heap-buffer-overflow read in S_grok_bslash_N (regcomp.c)" 4
+.IX Item "[CVE-2018-18313] Heap-buffer-overflow read in S_grok_bslash_N (regcomp.c)"
+.IP "[CVE\-2018\-18314] Heap-buffer-overflow write in S_regatom (regcomp.c)" 4
+.IX Item "[CVE-2018-18314] Heap-buffer-overflow write in S_regatom (regcomp.c)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5262delta \- what is new for perl v5.26.2"
+.IX Subsection "perl5262delta - what is new for perl v5.26.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2018\-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)" 4
+.IX Item "[CVE-2018-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+.IP "[CVE\-2018\-6798] Heap-buffer-overflow in Perl_\|_byte_dump_string (utf8.c)" 4
+.IX Item "[CVE-2018-6798] Heap-buffer-overflow in Perl__byte_dump_string (utf8.c)"
+.IP "[CVE\-2018\-6913] heap-buffer-overflow in S_pack_rec" 4
+.IX Item "[CVE-2018-6913] heap-buffer-overflow in S_pack_rec"
+.IP "Assertion failure in Perl_\|_core_swash_init (utf8.c)" 4
+.IX Item "Assertion failure in Perl__core_swash_init (utf8.c)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Windows
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5261delta \- what is new for perl v5.26.1"
+.IX Subsection "perl5261delta - what is new for perl v5.26.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler" 4
+.IX Item "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+.IP "[CVE\-2017\-12883] Buffer over-read in regular expression parser" 4
+.IX Item "[CVE-2017-12883] Buffer over-read in regular expression parser"
+.ie n .IP "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows" 4
+.el .IP "[CVE\-2017\-12814] \f(CW$ENV{$key}\fR stack buffer overflow on Windows" 4
+.IX Item "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+FreeBSD, Windows
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5260delta \- what is new for perl v5.26.0"
+.IX Subsection "perl5260delta - what is new for perl v5.26.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Notice 4
+.IX Item "Notice"
+.PD
+\&\f(CW"."\fR no longer in \f(CW@INC\fR, \f(CW\*(C`do\*(C'\fR may now warn, In regular expression
+patterns, a literal left brace \f(CW"{"\fR should be escaped
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.PD 0
+.IP "Lexical subroutines are no longer experimental" 4
+.IX Item "Lexical subroutines are no longer experimental"
+.IP "Indented Here-documents" 4
+.IX Item "Indented Here-documents"
+.ie n .IP "New regular expression modifier ""/xx""" 4
+.el .IP "New regular expression modifier \f(CW/xx\fR" 4
+.IX Item "New regular expression modifier /xx"
+.ie n .IP """@{^CAPTURE}"", ""%{^CAPTURE}"", and ""%{^CAPTURE_ALL}""" 4
+.el .IP "\f(CW@{^CAPTURE}\fR, \f(CW%{^CAPTURE}\fR, and \f(CW%{^CAPTURE_ALL}\fR" 4
+.IX Item "@{^CAPTURE}, %{^CAPTURE}, and %{^CAPTURE_ALL}"
+.IP "Declaring a reference to a variable" 4
+.IX Item "Declaring a reference to a variable"
+.IP "Unicode 9.0 is now supported" 4
+.IX Item "Unicode 9.0 is now supported"
+.ie n .IP "Use of ""\ep{\fIscript\fR}"" uses the improved Script_Extensions property" 4
+.el .IP "Use of \f(CW\ep{\fR\f(CIscript\fR\f(CW}\fR uses the improved Script_Extensions property" 4
+.IX Item "Use of p{script} uses the improved Script_Extensions property"
+.IP "Perl can now do default collation in UTF\-8 locales on platforms that support it" 4
+.IX Item "Perl can now do default collation in UTF-8 locales on platforms that support it"
+.ie n .IP "Better locale collation of strings containing embedded ""NUL"" characters" 4
+.el .IP "Better locale collation of strings containing embedded \f(CWNUL\fR characters" 4
+.IX Item "Better locale collation of strings containing embedded NUL characters"
+.ie n .IP """CORE"" subroutines for hash and array functions callable via reference" 4
+.el .IP "\f(CWCORE\fR subroutines for hash and array functions callable via reference" 4
+.IX Item "CORE subroutines for hash and array functions callable via reference"
+.IP "New Hash Function For 64\-bit Builds" 4
+.IX Item "New Hash Function For 64-bit Builds"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Removal of the current directory (""."") from @INC" 4
+.el .IP "Removal of the current directory (\f(CW"".""\fR) from \f(CW@INC\fR" 4
+.IX Item "Removal of the current directory (""."") from @INC"
+.PD
+\&\fIConfigure \-Udefault_inc_excludes_dot\fR, \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR, A new
+deprecation warning issued by \f(CW\*(C`do\*(C'\fR, Script authors, Installing and using
+CPAN modules, Module Authors
+.IP "Escaped colons and relative paths in PATH" 4
+.IX Item "Escaped colons and relative paths in PATH"
+.PD 0
+.ie n .IP "New ""\-Di"" switch is now required for PerlIO debugging output" 4
+.el .IP "New \f(CW\-Di\fR switch is now required for PerlIO debugging output" 4
+.IX Item "New -Di switch is now required for PerlIO debugging output"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.ie n .IP "Unescaped literal ""{"" characters in regular expression patterns are no longer permissible" 4
+.el .IP "Unescaped literal \f(CW""{""\fR characters in regular expression patterns are no longer permissible" 4
+.IX Item "Unescaped literal ""{"" characters in regular expression patterns are no longer permissible"
+.ie n .IP "scalar(%hash) return signature changed" 4
+.el .IP "\f(CWscalar(%hash)\fR return signature changed" 4
+.IX Item "scalar(%hash) return signature changed"
+.ie n .IP """keys"" returned from an lvalue subroutine" 4
+.el .IP "\f(CWkeys\fR returned from an lvalue subroutine" 4
+.IX Item "keys returned from an lvalue subroutine"
+.ie n .IP "The ""${^ENCODING}"" facility has been removed" 4
+.el .IP "The \f(CW${^ENCODING}\fR facility has been removed" 4
+.IX Item "The ${^ENCODING} facility has been removed"
+.ie n .IP "POSIX::tmpnam() has been removed" 4
+.el .IP "\f(CWPOSIX::tmpnam()\fR has been removed" 4
+.IX Item "POSIX::tmpnam() has been removed"
+.IP "require ::Foo::Bar is now illegal." 4
+.IX Item "require ::Foo::Bar is now illegal."
+.IP "Literal control character variable names are no longer permissible" 4
+.IX Item "Literal control character variable names are no longer permissible"
+.ie n .IP """NBSP"" is no longer permissible in ""\eN{...}""" 4
+.el .IP "\f(CWNBSP\fR is no longer permissible in \f(CW\eN{...}\fR" 4
+.IX Item "NBSP is no longer permissible in N{...}"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.IP "String delimiters that aren't stand-alone graphemes are now deprecated" 4
+.IX Item "String delimiters that aren't stand-alone graphemes are now deprecated"
+.ie n .IP """\ec\fIX\fR"" that maps to a printable is no longer deprecated" 4
+.el .IP "\f(CW\ec\fR\f(CIX\fR\f(CW\fR that maps to a printable is no longer deprecated" 4
+.IX Item "cX that maps to a printable is no longer deprecated"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.PD
+New Faster Hash Function on 64 bit builds, readline is faster
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.PD 0
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "\fIc2ph\fR and \fIpstruct\fR" 4
+.IX Item "c2ph and pstruct"
+.IP \fIPorting/pod_lib.pl\fR 4
+.IX Item "Porting/pod_lib.pl"
+.IP \fIPorting/sync\-with\-cpan\fR 4
+.IX Item "Porting/sync-with-cpan"
+.IP \fIperf/benchmarks\fR 4
+.IX Item "perf/benchmarks"
+.IP \fIPorting/checkAUTHORS.pl\fR 4
+.IX Item "Porting/checkAUTHORS.pl"
+.IP \fIt/porting/regen.t\fR 4
+.IX Item "t/porting/regen.t"
+.IP \fIutils/h2xs.PL\fR 4
+.IX Item "utils/h2xs.PL"
+.IP perlbug 4
+.IX Item "perlbug"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.PD
+NetBSD/VAX
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+Darwin, EBCDIC, HP-UX, Hurd, VAX, VMS, Windows, Linux, OpenBSD 6, FreeBSD,
+DragonFly BSD
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Errata From Previous Releases" 4
+.IX Item "Errata From Previous Releases"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "Give Thanks" 4
+.IX Item "Give Thanks"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5244delta \- what is new for perl v5.24.4"
+.IX Subsection "perl5244delta - what is new for perl v5.24.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2018\-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)" 4
+.IX Item "[CVE-2018-6797] heap-buffer-overflow (WRITE of size 1) in S_regatom (regcomp.c)"
+.IP "[CVE\-2018\-6798] Heap-buffer-overflow in Perl_\|_byte_dump_string (utf8.c)" 4
+.IX Item "[CVE-2018-6798] Heap-buffer-overflow in Perl__byte_dump_string (utf8.c)"
+.IP "[CVE\-2018\-6913] heap-buffer-overflow in S_pack_rec" 4
+.IX Item "[CVE-2018-6913] heap-buffer-overflow in S_pack_rec"
+.IP "Assertion failure in Perl_\|_core_swash_init (utf8.c)" 4
+.IX Item "Assertion failure in Perl__core_swash_init (utf8.c)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5243delta \- what is new for perl v5.24.3"
+.IX Subsection "perl5243delta - what is new for perl v5.24.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "[CVE\-2017\-12837] Heap buffer overflow in regular expression compiler" 4
+.IX Item "[CVE-2017-12837] Heap buffer overflow in regular expression compiler"
+.IP "[CVE\-2017\-12883] Buffer over-read in regular expression parser" 4
+.IX Item "[CVE-2017-12883] Buffer over-read in regular expression parser"
+.ie n .IP "[CVE\-2017\-12814] $ENV{$key} stack buffer overflow on Windows" 4
+.el .IP "[CVE\-2017\-12814] \f(CW$ENV{$key}\fR stack buffer overflow on Windows" 4
+.IX Item "[CVE-2017-12814] $ENV{$key} stack buffer overflow on Windows"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+VMS, Windows
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5242delta \- what is new for perl v5.24.2"
+.IX Subsection "perl5242delta - what is new for perl v5.24.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Improved handling of '.' in @INC in base.pm" 4
+.el .IP "Improved handling of '.' in \f(CW@INC\fR in base.pm" 4
+.IX Item "Improved handling of '.' in @INC in base.pm"
+.IP """Escaped"" colons and relative paths in PATH" 4
+.IX Item """Escaped"" colons and relative paths in PATH"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5241delta \- what is new for perl v5.24.1"
+.IX Subsection "perl5241delta - what is new for perl v5.24.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "\fB\-Di\fR switch is now required for PerlIO debugging output" 4
+.IX Item "-Di switch is now required for PerlIO debugging output"
+.IP "Core modules and tools no longer search \fI"".""\fR for optional modules" 4
+.IX Item "Core modules and tools no longer search ""."" for optional modules"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5240delta \- what is new for perl v5.24.0"
+.IX Subsection "perl5240delta - what is new for perl v5.24.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Postfix dereferencing is no longer experimental" 4
+.IX Item "Postfix dereferencing is no longer experimental"
+.IP "Unicode 8.0 is now supported" 4
+.IX Item "Unicode 8.0 is now supported"
+.IP "perl will now croak when closing an in-place output file fails" 4
+.IX Item "perl will now croak when closing an in-place output file fails"
+.ie n .IP "New ""\eb{lb}"" boundary in regular expressions" 4
+.el .IP "New \f(CW\eb{lb}\fR boundary in regular expressions" 4
+.IX Item "New b{lb} boundary in regular expressions"
+.ie n .IP """qr/(?[ ])/"" now works in UTF\-8 locales" 4
+.el .IP "\f(CWqr/(?[ ])/\fR now works in UTF\-8 locales" 4
+.IX Item "qr/(?[ ])/ now works in UTF-8 locales"
+.ie n .IP "Integer shift (""<<"" and "">>"") now more explicitly defined" 4
+.el .IP "Integer shift (\f(CW<<\fR and \f(CW>>\fR) now more explicitly defined" 4
+.IX Item "Integer shift (<< and >>) now more explicitly defined"
+.IP "printf and sprintf now allow reordered precision arguments" 4
+.IX Item "printf and sprintf now allow reordered precision arguments"
+.ie n .IP "More fields provided to ""sigaction"" callback with ""SA_SIGINFO""" 4
+.el .IP "More fields provided to \f(CWsigaction\fR callback with \f(CWSA_SIGINFO\fR" 4
+.IX Item "More fields provided to sigaction callback with SA_SIGINFO"
+.IP "Hashbang redirection to Perl 6" 4
+.IX Item "Hashbang redirection to Perl 6"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Set proper umask before calling mkstemp(3)" 4
+.el .IP "Set proper umask before calling \f(CWmkstemp(3)\fR" 4
+.IX Item "Set proper umask before calling mkstemp(3)"
+.IP "Fix out of boundary access in Win32 path handling" 4
+.IX Item "Fix out of boundary access in Win32 path handling"
+.IP "Fix loss of taint in canonpath" 4
+.IX Item "Fix loss of taint in canonpath"
+.ie n .IP "Avoid accessing uninitialized memory in win32 crypt()" 4
+.el .IP "Avoid accessing uninitialized memory in win32 \f(CWcrypt()\fR" 4
+.IX Item "Avoid accessing uninitialized memory in win32 crypt()"
+.ie n .IP "Remove duplicate environment variables from ""environ""" 4
+.el .IP "Remove duplicate environment variables from \f(CWenviron\fR" 4
+.IX Item "Remove duplicate environment variables from environ"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.ie n .IP "The ""autoderef"" feature has been removed" 4
+.el .IP "The \f(CWautoderef\fR feature has been removed" 4
+.IX Item "The autoderef feature has been removed"
+.ie n .IP "Lexical $_ has been removed" 4
+.el .IP "Lexical \f(CW$_\fR has been removed" 4
+.IX Item "Lexical $_ has been removed"
+.ie n .IP """qr/\eb{wb}/"" is now tailored to Perl expectations" 4
+.el .IP "\f(CWqr/\eb{wb}/\fR is now tailored to Perl expectations" 4
+.IX Item "qr/b{wb}/ is now tailored to Perl expectations"
+.IP "Regular expression compilation errors" 4
+.IX Item "Regular expression compilation errors"
+.ie n .IP """qr/\eN{}/"" now disallowed under ""use re ""strict""""" 4
+.el .IP "\f(CWqr/\eN{}/\fR now disallowed under \f(CWuse re ""strict""\fR" 4
+.IX Item "qr/N{}/ now disallowed under use re ""strict"""
+.IP "Nested declarations are now disallowed" 4
+.IX Item "Nested declarations are now disallowed"
+.ie n .IP "The ""/\eC/"" character class has been removed." 4
+.el .IP "The \f(CW/\eC/\fR character class has been removed." 4
+.IX Item "The /C/ character class has been removed."
+.ie n .IP "chdir(\*(Aq\*(Aq) no longer chdirs home" 4
+.el .IP "\f(CWchdir(\*(Aq\*(Aq)\fR no longer chdirs home" 4
+.IX Item "chdir() no longer chdirs home"
+.IP "ASCII characters in variable names must now be all visible" 4
+.IX Item "ASCII characters in variable names must now be all visible"
+.ie n .IP "An off by one issue in $Carp::MaxArgNums has been fixed" 4
+.el .IP "An off by one issue in \f(CW$Carp::MaxArgNums\fR has been fixed" 4
+.IX Item "An off by one issue in $Carp::MaxArgNums has been fixed"
+.ie n .IP "Only blanks and tabs are now allowed within ""[...]"" within ""(?[...])""." 4
+.el .IP "Only blanks and tabs are now allowed within \f(CW[...]\fR within \f(CW(?[...])\fR." 4
+.IX Item "Only blanks and tabs are now allowed within [...] within (?[...])."
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP "Using code points above the platform's ""IV_MAX"" is now deprecated" 4
+.el .IP "Using code points above the platform's \f(CWIV_MAX\fR is now deprecated" 4
+.IX Item "Using code points above the platform's IV_MAX is now deprecated"
+.IP "Doing bitwise operations on strings containing code points above 0xFF is deprecated" 4
+.IX Item "Doing bitwise operations on strings containing code points above 0xFF is deprecated"
+.ie n .IP "sysread(), syswrite(), recv() and send() are deprecated on :utf8 handles" 4
+.el .IP "\f(CWsysread()\fR, \f(CWsyswrite()\fR, \f(CWrecv()\fR and \f(CWsend()\fR are deprecated on :utf8 handles" 4
+.IX Item "sysread(), syswrite(), recv() and send() are deprecated on :utf8 handles"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+AmigaOS, Cygwin, EBCDIC, UTF-EBCDIC extended, EBCDIC \f(CWcmp()\fR and \f(CWsort()\fR
+fixed for UTF-EBCDIC strings, EBCDIC \f(CW\*(C`tr///\*(C'\fR and \f(CW\*(C`y///\*(C'\fR fixed for
+\&\f(CW\*(C`\eN{}\*(C'\fR, and \f(CW\*(C`use\ utf8\*(C'\fR ranges, FreeBSD, IRIX, MacOS X, Solaris, Tru64,
+VMS, Win32, ppc64el, floating point
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5224delta \- what is new for perl v5.22.4"
+.IX Subsection "perl5224delta - what is new for perl v5.22.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Improved handling of '.' in @INC in base.pm" 4
+.el .IP "Improved handling of '.' in \f(CW@INC\fR in base.pm" 4
+.IX Item "Improved handling of '.' in @INC in base.pm"
+.IP """Escaped"" colons and relative paths in PATH" 4
+.IX Item """Escaped"" colons and relative paths in PATH"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5223delta \- what is new for perl v5.22.3"
+.IX Subsection "perl5223delta - what is new for perl v5.22.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "\fB\-Di\fR switch is now required for PerlIO debugging output" 4
+.IX Item "-Di switch is now required for PerlIO debugging output"
+.IP "Core modules and tools no longer search \fI"".""\fR for optional modules" 4
+.IX Item "Core modules and tools no longer search ""."" for optional modules"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5222delta \- what is new for perl v5.22.2"
+.IX Subsection "perl5222delta - what is new for perl v5.22.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "Fix out of boundary access in Win32 path handling" 4
+.IX Item "Fix out of boundary access in Win32 path handling"
+.ie n .IP "Fix loss of taint in canonpath()" 4
+.el .IP "Fix loss of taint in \f(CWcanonpath()\fR" 4
+.IX Item "Fix loss of taint in canonpath()"
+.ie n .IP "Set proper umask before calling mkstemp(3)" 4
+.el .IP "Set proper umask before calling \f(CWmkstemp(3)\fR" 4
+.IX Item "Set proper umask before calling mkstemp(3)"
+.ie n .IP "Avoid accessing uninitialized memory in Win32 crypt()" 4
+.el .IP "Avoid accessing uninitialized memory in Win32 \f(CWcrypt()\fR" 4
+.IX Item "Avoid accessing uninitialized memory in Win32 crypt()"
+.ie n .IP "Remove duplicate environment variables from ""environ""" 4
+.el .IP "Remove duplicate environment variables from \f(CWenviron\fR" 4
+.IX Item "Remove duplicate environment variables from environ"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Darwin, OS X/Darwin, ppc64el, Tru64
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5221delta \- what is new for perl v5.22.1"
+.IX Subsection "perl5221delta - what is new for perl v5.22.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Bounds Checking Constructs" 4
+.IX Item "Bounds Checking Constructs"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+IRIX
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5220delta \- what is new for perl v5.22.0"
+.IX Subsection "perl5220delta - what is new for perl v5.22.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "New bitwise operators" 4
+.IX Item "New bitwise operators"
+.IP "New double-diamond operator" 4
+.IX Item "New double-diamond operator"
+.ie n .IP "New ""\eb"" boundaries in regular expressions" 4
+.el .IP "New \f(CW\eb\fR boundaries in regular expressions" 4
+.IX Item "New b boundaries in regular expressions"
+.IP "Non-Capturing Regular Expression Flag" 4
+.IX Item "Non-Capturing Regular Expression Flag"
+.ie n .IP """use re \*(Aqstrict\*(Aq""" 4
+.el .IP "\f(CWuse re \*(Aqstrict\*(Aq\fR" 4
+.IX Item "use re strict"
+.IP "Unicode 7.0 (with correction) is now supported" 4
+.IX Item "Unicode 7.0 (with correction) is now supported"
+.ie n .IP """use\ locale"" can restrict which locale categories are affected" 4
+.el .IP "\f(CWuse\ locale\fR can restrict which locale categories are affected" 4
+.IX Item "use locale can restrict which locale categories are affected"
+.IP "Perl now supports POSIX 2008 locale currency additions" 4
+.IX Item "Perl now supports POSIX 2008 locale currency additions"
+.IP "Better heuristics on older platforms for determining locale UTF\-8ness" 4
+.IX Item "Better heuristics on older platforms for determining locale UTF-8ness"
+.IP "Aliasing via reference" 4
+.IX Item "Aliasing via reference"
+.ie n .IP """prototype"" with no arguments" 4
+.el .IP "\f(CWprototype\fR with no arguments" 4
+.IX Item "prototype with no arguments"
+.ie n .IP "New "":const"" subroutine attribute" 4
+.el .IP "New \f(CW:const\fR subroutine attribute" 4
+.IX Item "New :const subroutine attribute"
+.ie n .IP """fileno"" now works on directory handles" 4
+.el .IP "\f(CWfileno\fR now works on directory handles" 4
+.IX Item "fileno now works on directory handles"
+.IP "List form of pipe open implemented for Win32" 4
+.IX Item "List form of pipe open implemented for Win32"
+.IP "Assignment to list repetition" 4
+.IX Item "Assignment to list repetition"
+.IP "Infinity and NaN (not-a-number) handling improved" 4
+.IX Item "Infinity and NaN (not-a-number) handling improved"
+.IP "Floating point parsing has been improved" 4
+.IX Item "Floating point parsing has been improved"
+.IP "Packing infinity or not-a-number into a character is now fatal" 4
+.IX Item "Packing infinity or not-a-number into a character is now fatal"
+.IP "Experimental C Backtrace API" 4
+.IX Item "Experimental C Backtrace API"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Perl is now compiled with ""\-fstack\-protector\-strong"" if available" 4
+.el .IP "Perl is now compiled with \f(CW\-fstack\-protector\-strong\fR if available" 4
+.IX Item "Perl is now compiled with -fstack-protector-strong if available"
+.IP "The Safe module could allow outside packages to be replaced" 4
+.IX Item "The Safe module could allow outside packages to be replaced"
+.ie n .IP "Perl is now always compiled with ""\-D_FORTIFY_SOURCE=2"" if available" 4
+.el .IP "Perl is now always compiled with \f(CW\-D_FORTIFY_SOURCE=2\fR if available" 4
+.IX Item "Perl is now always compiled with -D_FORTIFY_SOURCE=2 if available"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Subroutine signatures moved before attributes" 4
+.IX Item "Subroutine signatures moved before attributes"
+.ie n .IP """&"" and ""\e&"" prototypes accepts only subs" 4
+.el .IP "\f(CW&\fR and \f(CW\e&\fR prototypes accepts only subs" 4
+.IX Item "& and & prototypes accepts only subs"
+.ie n .IP """use encoding"" is now lexical" 4
+.el .IP "\f(CWuse encoding\fR is now lexical" 4
+.IX Item "use encoding is now lexical"
+.IP "List slices returning empty lists" 4
+.IX Item "List slices returning empty lists"
+.ie n .IP """\eN{}"" with a sequence of multiple spaces is now a fatal error" 4
+.el .IP "\f(CW\eN{}\fR with a sequence of multiple spaces is now a fatal error" 4
+.IX Item "N{} with a sequence of multiple spaces is now a fatal error"
+.ie n .IP """use\ UNIVERSAL\ \*(Aq...\*(Aq"" is now a fatal error" 4
+.el .IP "\f(CWuse\ UNIVERSAL\ \*(Aq...\*(Aq\fR is now a fatal error" 4
+.IX Item "use UNIVERSAL ... is now a fatal error"
+.ie n .IP "In double-quotish ""\ec\fIX\fR"", \fIX\fR must now be a printable ASCII character" 4
+.el .IP "In double-quotish \f(CW\ec\fR\f(CIX\fR\f(CW\fR, \fIX\fR must now be a printable ASCII character" 4
+.IX Item "In double-quotish cX, X must now be a printable ASCII character"
+.ie n .IP "Splitting the tokens ""(?"" and ""(*"" in regular expressions is now a fatal compilation error." 4
+.el .IP "Splitting the tokens \f(CW(?\fR and \f(CW(*\fR in regular expressions is now a fatal compilation error." 4
+.IX Item "Splitting the tokens (? and (* in regular expressions is now a fatal compilation error."
+.ie n .IP """qr/foo/x"" now ignores all Unicode pattern white space" 4
+.el .IP "\f(CWqr/foo/x\fR now ignores all Unicode pattern white space" 4
+.IX Item "qr/foo/x now ignores all Unicode pattern white space"
+.ie n .IP "Comment lines within ""(?[\ ])"" are now ended only by a ""\en""" 4
+.el .IP "Comment lines within \f(CW(?[\ ])\fR are now ended only by a \f(CW\en\fR" 4
+.IX Item "Comment lines within (?[ ]) are now ended only by a n"
+.ie n .IP """(?[...])"" operators now follow standard Perl precedence" 4
+.el .IP "\f(CW(?[...])\fR operators now follow standard Perl precedence" 4
+.IX Item "(?[...]) operators now follow standard Perl precedence"
+.ie n .IP "Omitting ""%"" and ""@"" on hash and array names is no longer permitted" 4
+.el .IP "Omitting \f(CW%\fR and \f(CW@\fR on hash and array names is no longer permitted" 4
+.IX Item "Omitting % and @ on hash and array names is no longer permitted"
+.ie n .IP """$!"" text is now in English outside the scope of ""use locale""" 4
+.el .IP "\f(CW""$!""\fR text is now in English outside the scope of \f(CWuse locale\fR" 4
+.IX Item """$!"" text is now in English outside the scope of use locale"
+.ie n .IP """$!"" text will be returned in UTF\-8 when appropriate" 4
+.el .IP "\f(CW""$!""\fR text will be returned in UTF\-8 when appropriate" 4
+.IX Item """$!"" text will be returned in UTF-8 when appropriate"
+.ie n .IP "Support for ""?PATTERN?"" without explicit operator has been removed" 4
+.el .IP "Support for \f(CW?PATTERN?\fR without explicit operator has been removed" 4
+.IX Item "Support for ?PATTERN? without explicit operator has been removed"
+.ie n .IP "defined(@array) and defined(%hash) are now fatal errors" 4
+.el .IP "\f(CWdefined(@array)\fR and \f(CWdefined(%hash)\fR are now fatal errors" 4
+.IX Item "defined(@array) and defined(%hash) are now fatal errors"
+.IP "Using a hash or an array as a reference are now fatal errors" 4
+.IX Item "Using a hash or an array as a reference are now fatal errors"
+.ie n .IP "Changes to the ""*"" prototype" 4
+.el .IP "Changes to the \f(CW*\fR prototype" 4
+.IX Item "Changes to the * prototype"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP "Setting ""${^ENCODING}"" to anything but ""undef""" 4
+.el .IP "Setting \f(CW${^ENCODING}\fR to anything but \f(CWundef\fR" 4
+.IX Item "Setting ${^ENCODING} to anything but undef"
+.IP "Use of non-graphic characters in single-character variable names" 4
+.IX Item "Use of non-graphic characters in single-character variable names"
+.ie n .IP "Inlining of ""sub () { $var }"" with observable side-effects" 4
+.el .IP "Inlining of \f(CWsub () { $var }\fR with observable side-effects" 4
+.IX Item "Inlining of sub () { $var } with observable side-effects"
+.ie n .IP "Use of multiple ""/x"" regexp modifiers" 4
+.el .IP "Use of multiple \f(CW/x\fR regexp modifiers" 4
+.IX Item "Use of multiple /x regexp modifiers"
+.ie n .IP "Using a NO-BREAK space in a character alias for ""\eN{...}"" is now deprecated" 4
+.el .IP "Using a NO-BREAK space in a character alias for \f(CW\eN{...}\fR is now deprecated" 4
+.IX Item "Using a NO-BREAK space in a character alias for N{...} is now deprecated"
+.ie n .IP "A literal ""{"" should now be escaped in a pattern" 4
+.el .IP "A literal \f(CW""{""\fR should now be escaped in a pattern" 4
+.IX Item "A literal ""{"" should now be escaped in a pattern"
+.IP "Making all warnings fatal is discouraged" 4
+.IX Item "Making all warnings fatal is discouraged"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.IP "Diagnostic Removals" 4
+.IX Item "Diagnostic Removals"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "\fIfind2perl\fR, \fIs2p\fR and \fIa2p\fR removal" 4
+.IX Item "find2perl, s2p and a2p removal"
+.IP h2ph 4
+.IX Item "h2ph"
+.IP encguess 4
+.IX Item "encguess"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Regained Platforms" 4
+.IX Item "Regained Platforms"
+.PD
+IRIX and Tru64 platforms are working again, z/OS running EBCDIC Code Page
+1047
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+NeXTSTEP/OPENSTEP
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+EBCDIC, HP-UX, Android, VMS, Win32, OpenBSD, Solaris
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5203delta \- what is new for perl v5.20.3"
+.IX Subsection "perl5203delta - what is new for perl v5.20.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP h2ph 4
+.IX Item "h2ph"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Win32
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5202delta \- what is new for perl v5.20.2"
+.IX Subsection "perl5202delta - what is new for perl v5.20.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Regained Platforms" 4
+.IX Item "Regained Platforms"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Errata From Previous Releases" 4
+.IX Item "Errata From Previous Releases"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5201delta \- what is new for perl v5.20.1"
+.IX Subsection "perl5201delta - what is new for perl v5.20.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Android, OpenBSD, Solaris, VMS, Windows
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5200delta \- what is new for perl v5.20.0"
+.IX Subsection "perl5200delta - what is new for perl v5.20.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Experimental Subroutine signatures" 4
+.IX Item "Experimental Subroutine signatures"
+.ie n .IP """sub""s now take a ""prototype"" attribute" 4
+.el .IP "\f(CWsub\fRs now take a \f(CWprototype\fR attribute" 4
+.IX Item "subs now take a prototype attribute"
+.IP "More consistent prototype parsing" 4
+.IX Item "More consistent prototype parsing"
+.ie n .IP """rand"" now uses a consistent random number generator" 4
+.el .IP "\f(CWrand\fR now uses a consistent random number generator" 4
+.IX Item "rand now uses a consistent random number generator"
+.IP "New slice syntax" 4
+.IX Item "New slice syntax"
+.IP "Experimental Postfix Dereferencing" 4
+.IX Item "Experimental Postfix Dereferencing"
+.IP "Unicode 6.3 now supported" 4
+.IX Item "Unicode 6.3 now supported"
+.ie n .IP "New ""\ep{Unicode}"" regular expression pattern property" 4
+.el .IP "New \f(CW\ep{Unicode}\fR regular expression pattern property" 4
+.IX Item "New p{Unicode} regular expression pattern property"
+.IP "Better 64\-bit support" 4
+.IX Item "Better 64-bit support"
+.ie n .IP """use\ locale"" now works on UTF\-8 locales" 4
+.el .IP "\f(CWuse\ locale\fR now works on UTF\-8 locales" 4
+.IX Item "use locale now works on UTF-8 locales"
+.ie n .IP """use\ locale"" now compiles on systems without locale ability" 4
+.el .IP "\f(CWuse\ locale\fR now compiles on systems without locale ability" 4
+.IX Item "use locale now compiles on systems without locale ability"
+.IP "More locale initialization fallback options" 4
+.IX Item "More locale initialization fallback options"
+.ie n .IP """\-DL"" runtime option now added for tracing locale setting" 4
+.el .IP "\f(CW\-DL\fR runtime option now added for tracing locale setting" 4
+.IX Item "-DL runtime option now added for tracing locale setting"
+.IP "\fB\-F\fR now implies \fB\-a\fR and \fB\-a\fR implies \fB\-n\fR" 4
+.IX Item "-F now implies -a and -a implies -n"
+.ie n .IP "$a and $b warnings exemption" 4
+.el .IP "\f(CW$a\fR and \f(CW$b\fR warnings exemption" 4
+.IX Item "$a and $b warnings exemption"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "Avoid possible read of \fBfree()\fRd memory during parsing" 4
+.IX Item "Avoid possible read of free()d memory during parsing"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.ie n .IP """do"" can no longer be used to call subroutines" 4
+.el .IP "\f(CWdo\fR can no longer be used to call subroutines" 4
+.IX Item "do can no longer be used to call subroutines"
+.IP "Quote-like escape changes" 4
+.IX Item "Quote-like escape changes"
+.IP "Tainting happens under more circumstances; now conforms to documentation" 4
+.IX Item "Tainting happens under more circumstances; now conforms to documentation"
+.ie n .IP """\ep{}"", ""\eP{}"" matching has changed for non-Unicode code points." 4
+.el .IP "\f(CW\ep{}\fR, \f(CW\eP{}\fR matching has changed for non-Unicode code points." 4
+.IX Item "p{}, P{} matching has changed for non-Unicode code points."
+.ie n .IP """\ep{All}"" has been expanded to match all possible code points" 4
+.el .IP "\f(CW\ep{All}\fR has been expanded to match all possible code points" 4
+.IX Item "p{All} has been expanded to match all possible code points"
+.IP "Data::Dumper's output may change" 4
+.IX Item "Data::Dumper's output may change"
+.ie n .IP "Locale decimal point character no longer leaks outside of ""use\ locale"" scope" 4
+.el .IP "Locale decimal point character no longer leaks outside of \f(CWuse\ locale\fR scope" 4
+.IX Item "Locale decimal point character no longer leaks outside of use locale scope"
+.IP "Assignments of Windows sockets error codes to $! now prefer \fIerrno.h\fR values over \fBWSAGetLastError()\fR values" 4
+.IX Item "Assignments of Windows sockets error codes to $! now prefer errno.h values over WSAGetLastError() values"
+.ie n .IP "Functions ""PerlIO_vsprintf"" and ""PerlIO_sprintf"" have been removed" 4
+.el .IP "Functions \f(CWPerlIO_vsprintf\fR and \f(CWPerlIO_sprintf\fR have been removed" 4
+.IX Item "Functions PerlIO_vsprintf and PerlIO_sprintf have been removed"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.ie n .IP "The ""/\eC/"" character class" 4
+.el .IP "The \f(CW/\eC/\fR character class" 4
+.IX Item "The /C/ character class"
+.IP "Literal control characters in variable names" 4
+.IX Item "Literal control characters in variable names"
+.ie n .IP "References to non-integers and non-positive integers in $/" 4
+.el .IP "References to non-integers and non-positive integers in \f(CW$/\fR" 4
+.IX Item "References to non-integers and non-positive integers in $/"
+.IP "Character matching routines in POSIX" 4
+.IX Item "Character matching routines in POSIX"
+.IP "Interpreter-based threads are now \fIdiscouraged\fR" 4
+.IX Item "Interpreter-based threads are now discouraged"
+.IP "Module removals" 4
+.IX Item "Module removals"
+.PD
+CGI and its associated CGI:: packages, inc::latest,
+Package::Constants, Module::Build and its associated Module::Build::
+packages
+.IP "Utility removals" 4
+.IX Item "Utility removals"
+find2perl, s2p, a2p
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.PD
+Android, Bitrig, FreeMiNT, Synology
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+\&\f(CW\*(C`sfio\*(C'\fR, AT&T 3b1, DG/UX, EBCDIC
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+Cygwin, GNU/Hurd, Linux, Mac OS, MidnightBSD, Mixed-endian platforms, VMS,
+Win32, WinCE
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP "Regular Expressions" 4
+.IX Item "Regular Expressions"
+.IP "Perl 5 Debugger and \-d" 4
+.IX Item "Perl 5 Debugger and -d"
+.IP "Lexical Subroutines" 4
+.IX Item "Lexical Subroutines"
+.IP "Everything Else" 4
+.IX Item "Everything Else"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5184delta \- what is new for perl v5.18.4"
+.IX Subsection "perl5184delta - what is new for perl v5.18.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+Win32
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5182delta \- what is new for perl v5.18.2"
+.IX Subsection "perl5182delta - what is new for perl v5.18.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5181delta \- what is new for perl v5.18.1"
+.IX Subsection "perl5181delta - what is new for perl v5.18.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+AIX, MidnightBSD
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5180delta \- what is new for perl v5.18.0"
+.IX Subsection "perl5180delta - what is new for perl v5.18.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "New mechanism for experimental features" 4
+.IX Item "New mechanism for experimental features"
+.IP "Hash overhaul" 4
+.IX Item "Hash overhaul"
+.IP "Upgrade to Unicode 6.2" 4
+.IX Item "Upgrade to Unicode 6.2"
+.IP "Character name aliases may now include non\-Latin1\-range characters" 4
+.IX Item "Character name aliases may now include non-Latin1-range characters"
+.IP "New DTrace probes" 4
+.IX Item "New DTrace probes"
+.ie n .IP """${^LAST_FH}""" 4
+.el .IP \f(CW${^LAST_FH}\fR 4
+.IX Item "${^LAST_FH}"
+.IP "Regular Expression Set Operations" 4
+.IX Item "Regular Expression Set Operations"
+.IP "Lexical subroutines" 4
+.IX Item "Lexical subroutines"
+.IP "Computed Labels" 4
+.IX Item "Computed Labels"
+.IP "More CORE:: subs" 4
+.IX Item "More CORE:: subs"
+.ie n .IP """kill"" with negative signal names" 4
+.el .IP "\f(CWkill\fR with negative signal names" 4
+.IX Item "kill with negative signal names"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "See also: hash overhaul" 4
+.IX Item "See also: hash overhaul"
+.ie n .IP """Storable"" security warning in documentation" 4
+.el .IP "\f(CWStorable\fR security warning in documentation" 4
+.IX Item "Storable security warning in documentation"
+.ie n .IP """Locale::Maketext"" allowed code injection via a malicious template" 4
+.el .IP "\f(CWLocale::Maketext\fR allowed code injection via a malicious template" 4
+.IX Item "Locale::Maketext allowed code injection via a malicious template"
+.IP "Avoid calling memset with a negative count" 4
+.IX Item "Avoid calling memset with a negative count"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "See also: hash overhaul" 4
+.IX Item "See also: hash overhaul"
+.ie n .IP "An unknown character name in ""\eN{...}"" is now a syntax error" 4
+.el .IP "An unknown character name in \f(CW\eN{...}\fR is now a syntax error" 4
+.IX Item "An unknown character name in N{...} is now a syntax error"
+.ie n .IP "Formerly deprecated characters in ""\eN{}"" character name aliases are now errors." 4
+.el .IP "Formerly deprecated characters in \f(CW\eN{}\fR character name aliases are now errors." 4
+.IX Item "Formerly deprecated characters in N{} character name aliases are now errors."
+.ie n .IP """\eN{BELL}"" now refers to U+1F514 instead of U+0007" 4
+.el .IP "\f(CW\eN{BELL}\fR now refers to U+1F514 instead of U+0007" 4
+.IX Item "N{BELL} now refers to U+1F514 instead of U+0007"
+.IP "New Restrictions in Multi-Character Case-Insensitive Matching in Regular Expression Bracketed Character Classes" 4
+.IX Item "New Restrictions in Multi-Character Case-Insensitive Matching in Regular Expression Bracketed Character Classes"
+.IP "Explicit rules for variable names and identifiers" 4
+.IX Item "Explicit rules for variable names and identifiers"
+.IP "Vertical tabs are now whitespace" 4
+.IX Item "Vertical tabs are now whitespace"
+.ie n .IP """/(?{})/"" and ""/(??{})/"" have been heavily reworked" 4
+.el .IP "\f(CW/(?{})/\fR and \f(CW/(??{})/\fR have been heavily reworked" 4
+.IX Item "/(?{})/ and /(??{})/ have been heavily reworked"
+.IP "Stricter parsing of substitution replacement" 4
+.IX Item "Stricter parsing of substitution replacement"
+.ie n .IP """given"" now aliases the global $_" 4
+.el .IP "\f(CWgiven\fR now aliases the global \f(CW$_\fR" 4
+.IX Item "given now aliases the global $_"
+.IP "The smartmatch family of features are now experimental" 4
+.IX Item "The smartmatch family of features are now experimental"
+.ie n .IP "Lexical $_ is now experimental" 4
+.el .IP "Lexical \f(CW$_\fR is now experimental" 4
+.IX Item "Lexical $_ is now experimental"
+.ie n .IP "\fBreadline()\fR with ""$/ = \eN"" now reads N characters, not N bytes" 4
+.el .IP "\fBreadline()\fR with \f(CW$/ = \eN\fR now reads N characters, not N bytes" 4
+.IX Item "readline() with $/ = N now reads N characters, not N bytes"
+.ie n .IP "Overridden ""glob"" is now passed one argument" 4
+.el .IP "Overridden \f(CWglob\fR is now passed one argument" 4
+.IX Item "Overridden glob is now passed one argument"
+.IP "Here doc parsing" 4
+.IX Item "Here doc parsing"
+.IP "Alphanumeric operators must now be separated from the closing delimiter of regular expressions" 4
+.IX Item "Alphanumeric operators must now be separated from the closing delimiter of regular expressions"
+.IP "qw(...) can no longer be used as parentheses" 4
+.IX Item "qw(...) can no longer be used as parentheses"
+.IP "Interaction of lexical and default warnings" 4
+.IX Item "Interaction of lexical and default warnings"
+.ie n .IP """state sub"" and ""our sub""" 4
+.el .IP "\f(CWstate sub\fR and \f(CWour sub\fR" 4
+.IX Item "state sub and our sub"
+.IP "Defined values stored in environment are forced to byte strings" 4
+.IX Item "Defined values stored in environment are forced to byte strings"
+.ie n .IP """require"" dies for unreadable files" 4
+.el .IP "\f(CWrequire\fR dies for unreadable files" 4
+.IX Item "require dies for unreadable files"
+.ie n .IP """gv_fetchmeth_*"" and SUPER" 4
+.el .IP "\f(CWgv_fetchmeth_*\fR and SUPER" 4
+.IX Item "gv_fetchmeth_* and SUPER"
+.ie n .IP """split""'s first argument is more consistently interpreted" 4
+.el .IP "\f(CWsplit\fR's first argument is more consistently interpreted" 4
+.IX Item "split's first argument is more consistently interpreted"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.IP "Module removals" 4
+.IX Item "Module removals"
+.PD
+encoding, Archive::Extract, B::Lint, B::Lint::Debug,
+CPANPLUS and all included \f(CW\*(C`CPANPLUS::*\*(C'\fR modules,
+Devel::InnerPackage, Log::Message, Log::Message::Config,
+Log::Message::Handlers, Log::Message::Item, Log::Message::Simple,
+Module::Pluggable, Module::Pluggable::Object, Object::Accessor,
+Pod::LaTeX, Term::UI, Term::UI::History
+.IP "Deprecated Utilities" 4
+.IX Item "Deprecated Utilities"
+cpanp, \f(CW\*(C`cpanp\-run\-perl\*(C'\fR, cpan2dist, pod2latex
+.IP PL_sv_objcount 4
+.IX Item "PL_sv_objcount"
+.PD 0
+.ie n .IP "Five additional characters should be escaped in patterns with ""/x""" 4
+.el .IP "Five additional characters should be escaped in patterns with \f(CW/x\fR" 4
+.IX Item "Five additional characters should be escaped in patterns with /x"
+.IP "User-defined charnames with surprising whitespace" 4
+.IX Item "User-defined charnames with surprising whitespace"
+.IP "Various XS-callable functions are now deprecated" 4
+.IX Item "Various XS-callable functions are now deprecated"
+.IP "Certain rare uses of backslashes within regexes are now deprecated" 4
+.IX Item "Certain rare uses of backslashes within regexes are now deprecated"
+.ie n .IP "Splitting the tokens ""(?"" and ""(*"" in regular expressions" 4
+.el .IP "Splitting the tokens \f(CW(?\fR and \f(CW(*\fR in regular expressions" 4
+.IX Item "Splitting the tokens (? and (* in regular expressions"
+.IP "Pre-PerlIO IO implementations" 4
+.IX Item "Pre-PerlIO IO implementations"
+.RE
+.RS 4
+.RE
+.IP "Future Deprecations" 4
+.IX Item "Future Deprecations"
+.PD
+DG/UX, NeXT
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.PD
+BeOS, UTS Global, VM/ESA, MPE/IX, EPOC, Rhapsody
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5163delta \- what is new for perl v5.16.3"
+.IX Subsection "perl5163delta - what is new for perl v5.16.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2013\-1667: memory exhaustion with arbitrary hash keys" 4
+.IX Item "CVE-2013-1667: memory exhaustion with arbitrary hash keys"
+.IP "wrap-around with IO on long strings" 4
+.IX Item "wrap-around with IO on long strings"
+.IP "memory leak in Encode" 4
+.IX Item "memory leak in Encode"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5162delta \- what is new for perl v5.16.2"
+.IX Subsection "perl5162delta - what is new for perl v5.16.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.PD
+configuration should no longer be confused by ls colorization
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.PD 0
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+AIX
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+fix /\eh/ equivalence with /[\eh]/
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5161delta \- what is new for perl v5.16.1"
+.IX Subsection "perl5161delta - what is new for perl v5.16.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "an off-by-two error in Scalar-List-Util has been fixed" 4
+.IX Item "an off-by-two error in Scalar-List-Util has been fixed"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+VMS
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5160delta \- what is new for perl v5.16.0"
+.IX Subsection "perl5160delta - what is new for perl v5.16.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Notice 4
+.IX Item "Notice"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP """use \fIVERSION\fR""" 4
+.el .IP "\f(CWuse \fR\f(CIVERSION\fR\f(CW\fR" 4
+.IX Item "use VERSION"
+.ie n .IP """_\|_SUB_\|_""" 4
+.el .IP \f(CW_\|_SUB_\|_\fR 4
+.IX Item "__SUB__"
+.IP "New and Improved Built-ins" 4
+.IX Item "New and Improved Built-ins"
+.IP "Unicode Support" 4
+.IX Item "Unicode Support"
+.IP "XS Changes" 4
+.IX Item "XS Changes"
+.IP "Changes to Special Variables" 4
+.IX Item "Changes to Special Variables"
+.IP "Debugger Changes" 4
+.IX Item "Debugger Changes"
+.ie n .IP "The ""CORE"" Namespace" 4
+.el .IP "The \f(CWCORE\fR Namespace" 4
+.IX Item "The CORE Namespace"
+.IP "Other Changes" 4
+.IX Item "Other Changes"
+.RE
+.RS 4
+.RE
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "Use is_utf8_char_buf() and not is_utf8_char()" 4
+.el .IP "Use \f(CWis_utf8_char_buf()\fR and not \f(CWis_utf8_char()\fR" 4
+.IX Item "Use is_utf8_char_buf() and not is_utf8_char()"
+.IP "Malformed UTF\-8 input could cause attempts to read beyond the end of the buffer" 4
+.IX Item "Malformed UTF-8 input could cause attempts to read beyond the end of the buffer"
+.ie n .IP "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.el .IP "\f(CWFile::Glob::bsd_glob()\fR memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.IX Item "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+.ie n .IP "Privileges are now set correctly when assigning to $(" 4
+.el .IP "Privileges are now set correctly when assigning to \f(CW$(\fR" 4
+.IX Item "Privileges are now set correctly when assigning to $("
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.IP "Don't read the Unicode data base files in \fIlib/unicore\fR" 4
+.IX Item "Don't read the Unicode data base files in lib/unicore"
+.ie n .IP "XS functions is_utf8_char(), utf8_to_uvchr() and utf8_to_uvuni()" 4
+.el .IP "XS functions \f(CWis_utf8_char()\fR, \f(CWutf8_to_uvchr()\fR and \f(CWutf8_to_uvuni()\fR" 4
+.IX Item "XS functions is_utf8_char(), utf8_to_uvchr() and utf8_to_uvuni()"
+.RE
+.RS 4
+.RE
+.IP "Future Deprecations" 4
+.IX Item "Future Deprecations"
+.RS 4
+.IP "Core Modules" 4
+.IX Item "Core Modules"
+.IP "Platforms with no supporting programmers" 4
+.IX Item "Platforms with no supporting programmers"
+.IP "Other Future Deprecations" 4
+.IX Item "Other Future Deprecations"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Special blocks called in void context" 4
+.IX Item "Special blocks called in void context"
+.ie n .IP "The ""overloading"" pragma and regexp objects" 4
+.el .IP "The \f(CWoverloading\fR pragma and regexp objects" 4
+.IX Item "The overloading pragma and regexp objects"
+.IP "Two XS typemap Entries removed" 4
+.IX Item "Two XS typemap Entries removed"
+.IP "Unicode 6.1 has incompatibilities with Unicode 6.0" 4
+.IX Item "Unicode 6.1 has incompatibilities with Unicode 6.0"
+.IP "Borland compiler" 4
+.IX Item "Borland compiler"
+.IP "Certain deprecated Unicode properties are no longer supported by default" 4
+.IX Item "Certain deprecated Unicode properties are no longer supported by default"
+.IP "Dereferencing IO thingies as typeglobs" 4
+.IX Item "Dereferencing IO thingies as typeglobs"
+.IP "User-defined case-changing operations" 4
+.IX Item "User-defined case-changing operations"
+.IP "XSUBs are now 'static'" 4
+.IX Item "XSUBs are now 'static'"
+.IP "Weakening read-only references" 4
+.IX Item "Weakening read-only references"
+.IP "Tying scalars that hold typeglobs" 4
+.IX Item "Tying scalars that hold typeglobs"
+.ie n .IP "IPC::Open3 no longer provides xfork(), xclose_on_exec() and xpipe_anon()" 4
+.el .IP "IPC::Open3 no longer provides \f(CWxfork()\fR, \f(CWxclose_on_exec()\fR and \f(CWxpipe_anon()\fR" 4
+.IX Item "IPC::Open3 no longer provides xfork(), xclose_on_exec() and xpipe_anon()"
+.ie n .IP "$$ no longer caches PID" 4
+.el .IP "\f(CW$$\fR no longer caches PID" 4
+.IX Item "$$ no longer caches PID"
+.ie n .IP "$$ and getppid() no longer emulate POSIX semantics under LinuxThreads" 4
+.el .IP "\f(CW$$\fR and \f(CWgetppid()\fR no longer emulate POSIX semantics under LinuxThreads" 4
+.IX Item "$$ and getppid() no longer emulate POSIX semantics under LinuxThreads"
+.ie n .IP "$<, $>, $( and $) are no longer cached" 4
+.el .IP "\f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR are no longer cached" 4
+.IX Item "$<, $>, $( and $) are no longer cached"
+.ie n .IP "Which Non-ASCII characters get quoted by ""quotemeta"" and ""\eQ"" has changed" 4
+.el .IP "Which Non-ASCII characters get quoted by \f(CWquotemeta\fR and \f(CW\eQ\fR has changed" 4
+.IX Item "Which Non-ASCII characters get quoted by quotemeta and Q has changed"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Deprecated Modules" 4
+.IX Item "Deprecated Modules"
+.PD
+Version::Requirements
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.PD 0
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.IP "Removed Documentation" 4
+.IX Item "Removed Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Removed Errors" 4
+.IX Item "Removed Errors"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP "Array and hash" 4
+.IX Item "Array and hash"
+.IP "C API fixes" 4
+.IX Item "C API fixes"
+.IP "Compile-time hints" 4
+.IX Item "Compile-time hints"
+.IP "Copy-on-write scalars" 4
+.IX Item "Copy-on-write scalars"
+.IP "The debugger" 4
+.IX Item "The debugger"
+.IP "Dereferencing operators" 4
+.IX Item "Dereferencing operators"
+.IP "Filehandle, last-accessed" 4
+.IX Item "Filehandle, last-accessed"
+.ie n .IP "Filetests and ""stat""" 4
+.el .IP "Filetests and \f(CWstat\fR" 4
+.IX Item "Filetests and stat"
+.IP Formats 4
+.IX Item "Formats"
+.ie n .IP """given"" and ""when""" 4
+.el .IP "\f(CWgiven\fR and \f(CWwhen\fR" 4
+.IX Item "given and when"
+.ie n .IP "The ""glob"" operator" 4
+.el .IP "The \f(CWglob\fR operator" 4
+.IX Item "The glob operator"
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+.IP Overloading 4
+.IX Item "Overloading"
+.IP "Prototypes of built-in keywords" 4
+.IX Item "Prototypes of built-in keywords"
+.IP "Regular expressions" 4
+.IX Item "Regular expressions"
+.IP Smartmatching 4
+.IX Item "Smartmatching"
+.ie n .IP "The ""sort"" operator" 4
+.el .IP "The \f(CWsort\fR operator" 4
+.IX Item "The sort operator"
+.ie n .IP "The ""substr"" operator" 4
+.el .IP "The \f(CWsubstr\fR operator" 4
+.IX Item "The substr operator"
+.IP "Support for embedded nulls" 4
+.IX Item "Support for embedded nulls"
+.IP "Threading bugs" 4
+.IX Item "Threading bugs"
+.IP "Tied variables" 4
+.IX Item "Tied variables"
+.IP "Version objects and vstrings" 4
+.IX Item "Version objects and vstrings"
+.IP "Warnings, redefinition" 4
+.IX Item "Warnings, redefinition"
+.IP "Warnings, ""Uninitialized""" 4
+.IX Item "Warnings, ""Uninitialized"""
+.IP "Weak references" 4
+.IX Item "Weak references"
+.IP "Other notable fixes" 4
+.IX Item "Other notable fixes"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5144delta \- what is new for perl v5.14.4"
+.IX Subsection "perl5144delta - what is new for perl v5.14.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "CVE\-2013\-1667: memory exhaustion with arbitrary hash keys" 4
+.IX Item "CVE-2013-1667: memory exhaustion with arbitrary hash keys"
+.IP "memory leak in Encode" 4
+.IX Item "memory leak in Encode"
+.IP "[perl #111594] Socket::unpack_sockaddr_un heap-buffer-overflow" 4
+.IX Item "[perl #111594] Socket::unpack_sockaddr_un heap-buffer-overflow"
+.IP "[perl #111586] SDBM_File: fix off-by-one access to global "".dir""" 4
+.IX Item "[perl #111586] SDBM_File: fix off-by-one access to global "".dir"""
+.IP "off-by-two error in List::Util" 4
+.IX Item "off-by-two error in List::Util"
+.IP "[perl #115994] fix segv in regcomp.\fBc:S_join_exact()\fR" 4
+.IX Item "[perl #115994] fix segv in regcomp.c:S_join_exact()"
+.IP "[perl #115992] PL_eval_start use-after-free" 4
+.IX Item "[perl #115992] PL_eval_start use-after-free"
+.IP "wrap-around with IO on long strings" 4
+.IX Item "wrap-around with IO on long strings"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.PD
+Socket, SDBM_File, List::Util
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+VMS
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5143delta \- what is new for perl v5.14.3"
+.IX Subsection "perl5143delta - what is new for perl v5.14.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP """Digest"" unsafe use of eval (CVE\-2011\-3597)" 4
+.el .IP "\f(CWDigest\fR unsafe use of eval (CVE\-2011\-3597)" 4
+.IX Item "Digest unsafe use of eval (CVE-2011-3597)"
+.IP "Heap buffer overrun in 'x' string repeat operator (CVE\-2012\-5195)" 4
+.IX Item "Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+FreeBSD, Solaris and NetBSD, HP-UX, Linux, Mac OS X, GNU/Hurd, NetBSD
+.RE
+.RS 4
+.RE
+.IP "Bug Fixes" 4
+.IX Item "Bug Fixes"
+.PD 0
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5142delta \- what is new for perl v5.14.2"
+.IX Subsection "perl5142delta - what is new for perl v5.14.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.el .IP "\f(CWFile::Glob::bsd_glob()\fR memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.IX Item "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+.ie n .IP """Encode"" decode_xs n\-byte heap-overflow (CVE\-2011\-2939)" 4
+.el .IP "\f(CWEncode\fR decode_xs n\-byte heap-overflow (CVE\-2011\-2939)" 4
+.IX Item "Encode decode_xs n-byte heap-overflow (CVE-2011-2939)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.PD
+HP-UX PA\-RISC/64 now supports gcc\-4.x, Building on OS X 10.7 Lion and Xcode
+4 works again
+.RE
+.RS 4
+.RE
+.IP "Bug Fixes" 4
+.IX Item "Bug Fixes"
+.PD 0
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5141delta \- what is new for perl v5.14.1"
+.IX Subsection "perl5141delta - what is new for perl v5.14.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP Security 4
+.IX Item "Security"
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragmata" 4
+.IX Item "Updated Modules and Pragmata"
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP Testing 4
+.IX Item "Testing"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.RE
+.RS 4
+.RE
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.IP "Bug Fixes" 4
+.IX Item "Bug Fixes"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5140delta \- what is new for perl v5.14.0"
+.IX Subsection "perl5140delta - what is new for perl v5.14.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Notice 4
+.IX Item "Notice"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP Unicode 4
+.IX Item "Unicode"
+.IP "Regular Expressions" 4
+.IX Item "Regular Expressions"
+.IP "Syntactical Enhancements" 4
+.IX Item "Syntactical Enhancements"
+.IP "Exception Handling" 4
+.IX Item "Exception Handling"
+.IP "Other Enhancements" 4
+.IX Item "Other Enhancements"
+.PD
+\&\f(CW\*(C`\-d:\-foo\*(C'\fR, \f(CW\*(C`\-d:\-foo=bar\*(C'\fR
+.IP "New C APIs" 4
+.IX Item "New C APIs"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.IP "User-defined regular expression properties" 4
+.IX Item "User-defined regular expression properties"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Regular Expressions and String Escapes" 4
+.IX Item "Regular Expressions and String Escapes"
+.IP "Stashes and Package Variables" 4
+.IX Item "Stashes and Package Variables"
+.IP "Changes to Syntax or to Perl Operators" 4
+.IX Item "Changes to Syntax or to Perl Operators"
+.IP "Threads and Processes" 4
+.IX Item "Threads and Processes"
+.IP Configuration 4
+.IX Item "Configuration"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RS 4
+.IP "Omitting a space between a regular expression and subsequent word" 4
+.IX Item "Omitting a space between a regular expression and subsequent word"
+.ie n .IP """\ec\fIX\fR""" 4
+.el .IP \f(CW\ec\fR\f(CIX\fR\f(CW\fR 4
+.IX Item "cX"
+.ie n .IP """\eb{"" and ""\eB{""" 4
+.el .IP "\f(CW""\eb{""\fR and \f(CW""\eB{""\fR" 4
+.IX Item """b{"" and ""B{"""
+.IP "Perl 4\-era .pl libraries" 4
+.IX Item "Perl 4-era .pl libraries"
+.ie n .IP "List assignment to $[" 4
+.el .IP "List assignment to \f(CW$[\fR" 4
+.IX Item "List assignment to $["
+.IP "Use of qw(...) as parentheses" 4
+.IX Item "Use of qw(...) as parentheses"
+.ie n .IP """\eN{BELL}""" 4
+.el .IP \f(CW\eN{BELL}\fR 4
+.IX Item "N{BELL}"
+.ie n .IP """?PATTERN?""" 4
+.el .IP \f(CW?PATTERN?\fR 4
+.IX Item "?PATTERN?"
+.IP "Tie functions on scalars holding typeglobs" 4
+.IX Item "Tie functions on scalars holding typeglobs"
+.IP "User-defined case-mapping" 4
+.IX Item "User-defined case-mapping"
+.IP "Deprecated modules" 4
+.IX Item "Deprecated modules"
+.PD
+Devel::DProf
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.RS 4
+.PD 0
+.IP """Safe signals"" optimisation" 4
+.IX Item """Safe signals"" optimisation"
+.IP "Optimisation of \fBshift()\fR and \fBpop()\fR calls without arguments" 4
+.IX Item "Optimisation of shift() and pop() calls without arguments"
+.IP "Optimisation of regexp engine string comparison work" 4
+.IX Item "Optimisation of regexp engine string comparison work"
+.IP "Regular expression compilation speed-up" 4
+.IX Item "Regular expression compilation speed-up"
+.IP "String appending is 100 times faster" 4
+.IX Item "String appending is 100 times faster"
+.ie n .IP "Eliminate ""PL_*"" accessor functions under ithreads" 4
+.el .IP "Eliminate \f(CWPL_*\fR accessor functions under ithreads" 4
+.IX Item "Eliminate PL_* accessor functions under ithreads"
+.IP "Freeing weak references" 4
+.IX Item "Freeing weak references"
+.IP "Lexical array and hash assignments" 4
+.IX Item "Lexical array and hash assignments"
+.ie n .IP "@_ uses less memory" 4
+.el .IP "\f(CW@_\fR uses less memory" 4
+.IX Item "@_ uses less memory"
+.IP "Size optimisations to SV and HV structures" 4
+.IX Item "Size optimisations to SV and HV structures"
+.IP "Memory consumption improvements to Exporter" 4
+.IX Item "Memory consumption improvements to Exporter"
+.IP "Memory savings for weak references" 4
+.IX Item "Memory savings for weak references"
+.ie n .IP """%+"" and ""%\-"" use less memory" 4
+.el .IP "\f(CW%+\fR and \f(CW%\-\fR use less memory" 4
+.IX Item "%+ and %- use less memory"
+.IP "Multiple small improvements to threads" 4
+.IX Item "Multiple small improvements to threads"
+.IP "Adjacent pairs of nextstate opcodes are now optimized away" 4
+.IX Item "Adjacent pairs of nextstate opcodes are now optimized away"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated Modules and Pragma" 4
+.IX Item "Updated Modules and Pragma"
+.PD
+much less configuration dialog hassle, support for \fIMETA/MYMETA.json\fR,
+support for local::lib, support for HTTP::Tiny to reduce the
+dependency on FTP sites, automatic mirror selection, iron out all known
+bugs in configure_requires, support for distributions compressed with
+\&\fBbzip2\fR\|(1), allow \fIFoo/Bar.pm\fR on the command line to mean \f(CW\*(C`Foo::Bar\*(C'\fR,
+\&\fBcharinfo()\fR, \fBcharscript()\fR, \fBcharblock()\fR
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.PD
+Closure prototype called, Insecure user-defined property \f(CW%s\fR, panic: gp_free
+failed to free glob pointer \- something is repeatedly re-creating entries,
+Parsing code internal error (%s), refcnt: fd \f(CW%d\fR%s, Regexp modifier "/%c"
+may not appear twice, Regexp modifiers "/%c" and "/%c" are mutually
+exclusive, Using !~ with \f(CW%s\fR doesn't make sense, "\eb{" is deprecated; use
+"\eb\e{" instead, "\eB{" is deprecated; use "\eB\e{" instead, Operation "%s"
+returns its argument for .., Use of qw(...) as parentheses is deprecated
+.IP "Changes to Existing Diagnostics" 4
+.IX Item "Changes to Existing Diagnostics"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Configuration and Compilation" 4
+.IX Item "Configuration and Compilation"
+.IP "Platform Support" 4
+.IX Item "Platform Support"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.PD
+AIX
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+Apollo DomainOS, MacOS Classic
+.IP "Platform-Specific Notes" 4
+.IX Item "Platform-Specific Notes"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.RS 4
+.IP "New APIs" 4
+.IX Item "New APIs"
+.IP "C API Changes" 4
+.IX Item "C API Changes"
+.IP "Deprecated C APIs" 4
+.IX Item "Deprecated C APIs"
+.PD
+\&\f(CW\*(C`Perl_ptr_table_clear\*(C'\fR, \f(CW\*(C`sv_compile_2op\*(C'\fR, \f(CW\*(C`find_rundefsvoffset\*(C'\fR,
+\&\f(CW\*(C`CALL_FPTR\*(C'\fR and \f(CW\*(C`CPERLscope\*(C'\fR
+.IP "Other Internal Changes" 4
+.IX Item "Other Internal Changes"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP I/O 4
+.IX Item "I/O"
+.IP "Regular Expression Bug Fixes" 4
+.IX Item "Regular Expression Bug Fixes"
+.IP "Syntax/Parsing Bugs" 4
+.IX Item "Syntax/Parsing Bugs"
+.IP "Stashes, Globs and Method Lookup" 4
+.IX Item "Stashes, Globs and Method Lookup"
+.PD
+Aliasing packages by assigning to globs [perl #77358], Deleting packages by
+deleting their containing stash elements, Undefining the glob containing a
+package (\f(CW\*(C`undef *Foo::\*(C'\fR), Undefining an ISA glob (\f(CW\*(C`undef *Foo::ISA\*(C'\fR),
+Deleting an ISA stash element (\f(CW\*(C`delete $Foo::{ISA}\*(C'\fR), Sharing \f(CW@ISA\fR arrays
+between classes (via \f(CW\*(C`*Foo::ISA = \e@Bar::ISA\*(C'\fR or \f(CW\*(C`*Foo::ISA = *Bar::ISA\*(C'\fR)
+[perl #77238]
+.IP Unicode 4
+.IX Item "Unicode"
+.PD 0
+.IP "Ties, Overloading and Other Magic" 4
+.IX Item "Ties, Overloading and Other Magic"
+.IP "The Debugger" 4
+.IX Item "The Debugger"
+.IP Threads 4
+.IX Item "Threads"
+.IP "Scoping and Subroutines" 4
+.IX Item "Scoping and Subroutines"
+.IP Signals 4
+.IX Item "Signals"
+.IP "Miscellaneous Memory Leaks" 4
+.IX Item "Miscellaneous Memory Leaks"
+.IP "Memory Corruption and Crashes" 4
+.IX Item "Memory Corruption and Crashes"
+.IP "Fixes to Various Perl Operators" 4
+.IX Item "Fixes to Various Perl Operators"
+.IP "Bugs Relating to the C API" 4
+.IX Item "Bugs Relating to the C API"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Errata 4
+.IX Item "Errata"
+.RS 4
+.IP "\fBkeys()\fR, \fBvalues()\fR, and \fBeach()\fR work on arrays" 4
+.IX Item "keys(), values(), and each() work on arrays"
+.ie n .IP "\fBsplit()\fR and @_" 4
+.el .IP "\fBsplit()\fR and \f(CW@_\fR" 4
+.IX Item "split() and @_"
+.RE
+.RS 4
+.RE
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5125delta \- what is new for perl v5.12.5"
+.IX Subsection "perl5125delta - what is new for perl v5.12.5"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Security 4
+.IX Item "Security"
+.RS 4
+.ie n .IP """Encode"" decode_xs n\-byte heap-overflow (CVE\-2011\-2939)" 4
+.el .IP "\f(CWEncode\fR decode_xs n\-byte heap-overflow (CVE\-2011\-2939)" 4
+.IX Item "Encode decode_xs n-byte heap-overflow (CVE-2011-2939)"
+.ie n .IP "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.el .IP "\f(CWFile::Glob::bsd_glob()\fR memory error with GLOB_ALTDIRFUNC (CVE\-2011\-2728)." 4
+.IX Item "File::Glob::bsd_glob() memory error with GLOB_ALTDIRFUNC (CVE-2011-2728)."
+.IP "Heap buffer overrun in 'x' string repeat operator (CVE\-2012\-5195)" 4
+.IX Item "Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+.RE
+.RS 4
+.RE
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RS 4
+.IP perlebcdic 4
+.IX Item "perlebcdic"
+.IP perlunicode 4
+.IX Item "perlunicode"
+.IP perluniprops 4
+.IX Item "perluniprops"
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Platform Specific Changes" 4
+.IX Item "Platform Specific Changes"
+.PD
+Mac OS X, NetBSD
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP Errata 4
+.IX Item "Errata"
+.RS 4
+.ie n .IP "\fBsplit()\fR and @_" 4
+.el .IP "\fBsplit()\fR and \f(CW@_\fR" 4
+.IX Item "split() and @_"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5124delta \- what is new for perl v5.12.4"
+.IX Subsection "perl5124delta - what is new for perl v5.12.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.IP Testing 4
+.IX Item "Testing"
+.IP Documentation 4
+.IX Item "Documentation"
+.IP "Platform Specific Notes" 4
+.IX Item "Platform Specific Notes"
+.PD
+Linux
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.PD 0
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5123delta \- what is new for perl v5.12.3"
+.IX Subsection "perl5123delta - what is new for perl v5.12.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP """keys"", ""values"" work on arrays" 4
+.el .IP "\f(CWkeys\fR, \f(CWvalues\fR work on arrays" 4
+.IX Item "keys, values work on arrays"
+.RE
+.RS 4
+.RE
+.IP "Bug Fixes" 4
+.IX Item "Bug Fixes"
+.IP "Platform Specific Notes" 4
+.IX Item "Platform Specific Notes"
+.PD
+Solaris, VMS, VOS
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.PD 0
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5122delta \- what is new for perl v5.12.2"
+.IX Subsection "perl5122delta - what is new for perl v5.12.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Pragmata Changes" 4
+.IX Item "Pragmata Changes"
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+.PD
+\&\f(CW\*(C`Carp\*(C'\fR, \f(CW\*(C`CPANPLUS\*(C'\fR, \f(CW\*(C`File::Glob\*(C'\fR, \f(CW\*(C`File::Copy\*(C'\fR, \f(CW\*(C`File::Spec\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.PD 0
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Configuration improvements" 4
+.IX Item "Configuration improvements"
+.IP "Compilation improvements" 4
+.IX Item "Compilation improvements"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Platform Specific Notes" 4
+.IX Item "Platform Specific Notes"
+.RS 4
+.IP AIX 4
+.IX Item "AIX"
+.IP Windows 4
+.IX Item "Windows"
+.IP VMS 4
+.IX Item "VMS"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5121delta \- what is new for perl v5.12.1"
+.IX Subsection "perl5121delta - what is new for perl v5.12.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Pragmata Changes" 4
+.IX Item "Pragmata Changes"
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+.RE
+.RS 4
+.RE
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.IP Testing 4
+.IX Item "Testing"
+.RS 4
+.IP "Testing Improvements" 4
+.IX Item "Testing Improvements"
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Configuration improvements" 4
+.IX Item "Configuration improvements"
+.RE
+.RS 4
+.RE
+.IP "Bug Fixes" 4
+.IX Item "Bug Fixes"
+.IP "Platform Specific Notes" 4
+.IX Item "Platform Specific Notes"
+.RS 4
+.IP HP-UX 4
+.IX Item "HP-UX"
+.IP AIX 4
+.IX Item "AIX"
+.IP "FreeBSD 7" 4
+.IX Item "FreeBSD 7"
+.IP VMS 4
+.IX Item "VMS"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5120delta \- what is new for perl v5.12.0"
+.IX Subsection "perl5120delta - what is new for perl v5.12.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP "New ""package NAME VERSION"" syntax" 4
+.el .IP "New \f(CWpackage NAME VERSION\fR syntax" 4
+.IX Item "New package NAME VERSION syntax"
+.ie n .IP "The ""..."" operator" 4
+.el .IP "The \f(CW...\fR operator" 4
+.IX Item "The ... operator"
+.IP "Implicit strictures" 4
+.IX Item "Implicit strictures"
+.IP "Unicode improvements" 4
+.IX Item "Unicode improvements"
+.IP "Y2038 compliance" 4
+.IX Item "Y2038 compliance"
+.IP "qr overloading" 4
+.IX Item "qr overloading"
+.IP "Pluggable keywords" 4
+.IX Item "Pluggable keywords"
+.IP "APIs for more internals" 4
+.IX Item "APIs for more internals"
+.IP "Overridable function lookup" 4
+.IX Item "Overridable function lookup"
+.IP "A proper interface for pluggable Method Resolution Orders" 4
+.IX Item "A proper interface for pluggable Method Resolution Orders"
+.ie n .IP """\eN"" experimental regex escape" 4
+.el .IP "\f(CW\eN\fR experimental regex escape" 4
+.IX Item "N experimental regex escape"
+.IP "DTrace support" 4
+.IX Item "DTrace support"
+.ie n .IP "Support for ""configure_requires"" in CPAN module metadata" 4
+.el .IP "Support for \f(CWconfigure_requires\fR in CPAN module metadata" 4
+.IX Item "Support for configure_requires in CPAN module metadata"
+.ie n .IP """each"", ""keys"", ""values"" are now more flexible" 4
+.el .IP "\f(CWeach\fR, \f(CWkeys\fR, \f(CWvalues\fR are now more flexible" 4
+.IX Item "each, keys, values are now more flexible"
+.ie n .IP """when"" as a statement modifier" 4
+.el .IP "\f(CWwhen\fR as a statement modifier" 4
+.IX Item "when as a statement modifier"
+.ie n .IP "$, flexibility" 4
+.el .IP "\f(CW$,\fR flexibility" 4
+.IX Item "$, flexibility"
+.IP "// in when clauses" 4
+.IX Item "// in when clauses"
+.IP "Enabling warnings from your shell environment" 4
+.IX Item "Enabling warnings from your shell environment"
+.ie n .IP """delete local""" 4
+.el .IP "\f(CWdelete local\fR" 4
+.IX Item "delete local"
+.IP "New support for Abstract namespace sockets" 4
+.IX Item "New support for Abstract namespace sockets"
+.IP "32\-bit limit on substr arguments removed" 4
+.IX Item "32-bit limit on substr arguments removed"
+.RE
+.RS 4
+.RE
+.IP "Potentially Incompatible Changes" 4
+.IX Item "Potentially Incompatible Changes"
+.RS 4
+.IP "Deprecations warn by default" 4
+.IX Item "Deprecations warn by default"
+.IP "Version number formats" 4
+.IX Item "Version number formats"
+.ie n .IP "@INC reorganization" 4
+.el .IP "\f(CW@INC\fR reorganization" 4
+.IX Item "@INC reorganization"
+.IP "REGEXPs are now first class" 4
+.IX Item "REGEXPs are now first class"
+.IP "Switch statement changes" 4
+.IX Item "Switch statement changes"
+.PD
+flip-flop operators, defined-or operator
+.IP "Smart match changes" 4
+.IX Item "Smart match changes"
+.PD 0
+.IP "Other potentially incompatible changes" 4
+.IX Item "Other potentially incompatible changes"
+.RE
+.RS 4
+.RE
+.IP Deprecations 4
+.IX Item "Deprecations"
+.PD
+suidperl, Use of \f(CW\*(C`:=\*(C'\fR to mean an empty attribute list, \f(CW\*(C`UNIVERSAL\->import()\*(C'\fR, Use of "goto" to jump into a construct, Custom
+character names in \eN{name} that don't look like names, Deprecated Modules,
+Class::ISA, Pod::Plainer, Shell, Switch, Assignment to $[, Use
+of the attribute :locked on subroutines, Use of "locked" with the
+attributes pragma, Use of "unique" with the attributes pragma, Perl_pmflag,
+Numerous Perl 4\-era libraries
+.IP "Unicode overhaul" 4
+.IX Item "Unicode overhaul"
+.PD 0
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.PD
+\&\f(CW\*(C`autodie\*(C'\fR, \f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR, \f(CW\*(C`overloading\*(C'\fR, \f(CW\*(C`parent\*(C'\fR,
+\&\f(CW\*(C`Parse::CPAN::Meta\*(C'\fR, \f(CW\*(C`VMS::DCLsym\*(C'\fR, \f(CW\*(C`VMS::Stdio\*(C'\fR,
+\&\f(CW\*(C`XS::APItest::KeywordRPN\*(C'\fR
+.IP "Updated Pragmata" 4
+.IX Item "Updated Pragmata"
+\&\f(CW\*(C`base\*(C'\fR, \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`charnames\*(C'\fR, \f(CW\*(C`constant\*(C'\fR, \f(CW\*(C`diagnostics\*(C'\fR, \f(CW\*(C`feature\*(C'\fR,
+\&\f(CW\*(C`less\*(C'\fR, \f(CW\*(C`lib\*(C'\fR, \f(CW\*(C`mro\*(C'\fR, \f(CW\*(C`overload\*(C'\fR, \f(CW\*(C`threads\*(C'\fR, \f(CW\*(C`threads::shared\*(C'\fR,
+\&\f(CW\*(C`version\*(C'\fR, \f(CW\*(C`warnings\*(C'\fR
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+\&\f(CW\*(C`Archive::Extract\*(C'\fR, \f(CW\*(C`Archive::Tar\*(C'\fR, \f(CW\*(C`Attribute::Handlers\*(C'\fR,
+\&\f(CW\*(C`AutoLoader\*(C'\fR, \f(CW\*(C`B::Concise\*(C'\fR, \f(CW\*(C`B::Debug\*(C'\fR, \f(CW\*(C`B::Deparse\*(C'\fR, \f(CW\*(C`B::Lint\*(C'\fR,
+\&\f(CW\*(C`CGI\*(C'\fR, \f(CW\*(C`Class::ISA\*(C'\fR, \f(CW\*(C`Compress::Raw::Zlib\*(C'\fR, \f(CW\*(C`CPAN\*(C'\fR, \f(CW\*(C`CPANPLUS\*(C'\fR,
+\&\f(CW\*(C`CPANPLUS::Dist::Build\*(C'\fR, \f(CW\*(C`Data::Dumper\*(C'\fR, \f(CW\*(C`DB_File\*(C'\fR, \f(CW\*(C`Devel::PPPort\*(C'\fR,
+\&\f(CW\*(C`Digest\*(C'\fR, \f(CW\*(C`Digest::MD5\*(C'\fR, \f(CW\*(C`Digest::SHA\*(C'\fR, \f(CW\*(C`Encode\*(C'\fR, \f(CW\*(C`Exporter\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::CBuilder\*(C'\fR, \f(CW\*(C`ExtUtils::Command\*(C'\fR, \f(CW\*(C`ExtUtils::Constant\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::Install\*(C'\fR, \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR, \f(CW\*(C`ExtUtils::Manifest\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR, \f(CW\*(C`File::Fetch\*(C'\fR, \f(CW\*(C`File::Path\*(C'\fR, \f(CW\*(C`File::Temp\*(C'\fR,
+\&\f(CW\*(C`Filter::Simple\*(C'\fR, \f(CW\*(C`Filter::Util::Call\*(C'\fR, \f(CW\*(C`Getopt::Long\*(C'\fR, \f(CW\*(C`IO\*(C'\fR,
+\&\f(CW\*(C`IO::Zlib\*(C'\fR, \f(CW\*(C`IPC::Cmd\*(C'\fR, \f(CW\*(C`IPC::SysV\*(C'\fR, \f(CW\*(C`Locale::Maketext\*(C'\fR,
+\&\f(CW\*(C`Locale::Maketext::Simple\*(C'\fR, \f(CW\*(C`Log::Message\*(C'\fR, \f(CW\*(C`Log::Message::Simple\*(C'\fR,
+\&\f(CW\*(C`Math::BigInt\*(C'\fR, \f(CW\*(C`Math::BigInt::FastCalc\*(C'\fR, \f(CW\*(C`Math::BigRat\*(C'\fR,
+\&\f(CW\*(C`Math::Complex\*(C'\fR, \f(CW\*(C`Memoize\*(C'\fR, \f(CW\*(C`MIME::Base64\*(C'\fR, \f(CW\*(C`Module::Build\*(C'\fR,
+\&\f(CW\*(C`Module::CoreList\*(C'\fR, \f(CW\*(C`Module::Load\*(C'\fR, \f(CW\*(C`Module::Load::Conditional\*(C'\fR,
+\&\f(CW\*(C`Module::Loaded\*(C'\fR, \f(CW\*(C`Module::Pluggable\*(C'\fR, \f(CW\*(C`Net::Ping\*(C'\fR, \f(CW\*(C`NEXT\*(C'\fR,
+\&\f(CW\*(C`Object::Accessor\*(C'\fR, \f(CW\*(C`Package::Constants\*(C'\fR, \f(CW\*(C`PerlIO\*(C'\fR, \f(CW\*(C`Pod::Parser\*(C'\fR,
+\&\f(CW\*(C`Pod::Perldoc\*(C'\fR, \f(CW\*(C`Pod::Plainer\*(C'\fR, \f(CW\*(C`Pod::Simple\*(C'\fR, \f(CW\*(C`Safe\*(C'\fR, \f(CW\*(C`SelfLoader\*(C'\fR,
+\&\f(CW\*(C`Storable\*(C'\fR, \f(CW\*(C`Switch\*(C'\fR, \f(CW\*(C`Sys::Syslog\*(C'\fR, \f(CW\*(C`Term::ANSIColor\*(C'\fR, \f(CW\*(C`Term::UI\*(C'\fR,
+\&\f(CW\*(C`Test\*(C'\fR, \f(CW\*(C`Test::Harness\*(C'\fR, \f(CW\*(C`Test::Simple\*(C'\fR, \f(CW\*(C`Text::Balanced\*(C'\fR,
+\&\f(CW\*(C`Text::ParseWords\*(C'\fR, \f(CW\*(C`Text::Soundex\*(C'\fR, \f(CW\*(C`Thread::Queue\*(C'\fR,
+\&\f(CW\*(C`Thread::Semaphore\*(C'\fR, \f(CW\*(C`Tie::RefHash\*(C'\fR, \f(CW\*(C`Time::HiRes\*(C'\fR, \f(CW\*(C`Time::Local\*(C'\fR,
+\&\f(CW\*(C`Time::Piece\*(C'\fR, \f(CW\*(C`Unicode::Collate\*(C'\fR, \f(CW\*(C`Unicode::Normalize\*(C'\fR, \f(CW\*(C`Win32\*(C'\fR,
+\&\f(CW\*(C`Win32API::File\*(C'\fR, \f(CW\*(C`XSLoader\*(C'\fR
+.IP "Removed Modules and Pragmata" 4
+.IX Item "Removed Modules and Pragmata"
+\&\f(CW\*(C`attrs\*(C'\fR, \f(CW\*(C`CPAN::API::HOWTO\*(C'\fR, \f(CW\*(C`CPAN::DeferedCode\*(C'\fR, \f(CW\*(C`CPANPLUS::inc\*(C'\fR,
+\&\f(CW\*(C`DCLsym\*(C'\fR, \f(CW\*(C`ExtUtils::MakeMaker::bytes\*(C'\fR, \f(CW\*(C`ExtUtils::MakeMaker::vmsish\*(C'\fR,
+\&\f(CW\*(C`Stdio\*(C'\fR, \f(CW\*(C`Test::Harness::Assert\*(C'\fR, \f(CW\*(C`Test::Harness::Iterator\*(C'\fR,
+\&\f(CW\*(C`Test::Harness::Point\*(C'\fR, \f(CW\*(C`Test::Harness::Results\*(C'\fR,
+\&\f(CW\*(C`Test::Harness::Straps\*(C'\fR, \f(CW\*(C`Test::Harness::Util\*(C'\fR, \f(CW\*(C`XSSymSet\*(C'\fR
+.IP "Deprecated Modules and Pragmata" 4
+.IX Item "Deprecated Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Documentation 4
+.IX Item "Documentation"
+.RS 4
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.RE
+.RS 4
+.RE
+.IP "Selected Performance Enhancements" 4
+.IX Item "Selected Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Internal Changes" 4
+.IX Item "Internal Changes"
+.IP Testing 4
+.IX Item "Testing"
+.RS 4
+.IP "Testing improvements" 4
+.IX Item "Testing improvements"
+.PD
+Parallel tests, Test harness flexibility, Test watchdog
+.IP "New Tests" 4
+.IX Item "New Tests"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.RS 4
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.IP "Changed Diagnostics" 4
+.IX Item "Changed Diagnostics"
+.PD
+\&\f(CW\*(C`Illegal character in prototype for %s : %s\*(C'\fR, \f(CW\*(C`Prototype after \*(Aq%c\*(Aq for
+%s : %s\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "Platform Specific Changes" 4
+.IX Item "Platform Specific Changes"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.PD
+Haiku, MirOS BSD
+.IP "Discontinued Platforms" 4
+.IX Item "Discontinued Platforms"
+Domain/OS, MiNT, Tenon MachTen
+.IP "Updated Platforms" 4
+.IX Item "Updated Platforms"
+AIX, Cygwin, Darwin (Mac OS X), DragonFly BSD, FreeBSD, Irix, NetBSD,
+OpenVMS, Stratus VOS, Symbian, Windows
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.PD 0
+.IP Errata 4
+.IX Item "Errata"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5101delta \- what is new for perl v5.10.1"
+.IX Subsection "perl5101delta - what is new for perl v5.10.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Switch statement changes" 4
+.IX Item "Switch statement changes"
+.PD
+flip-flop operators, defined-or operator
+.IP "Smart match changes" 4
+.IX Item "Smart match changes"
+.PD 0
+.IP "Other incompatible changes" 4
+.IX Item "Other incompatible changes"
+.RE
+.RS 4
+.RE
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Unicode Character Database 5.1.0" 4
+.IX Item "Unicode Character Database 5.1.0"
+.IP "A proper interface for pluggable Method Resolution Orders" 4
+.IX Item "A proper interface for pluggable Method Resolution Orders"
+.ie n .IP "The ""overloading"" pragma" 4
+.el .IP "The \f(CWoverloading\fR pragma" 4
+.IX Item "The overloading pragma"
+.IP "Parallel tests" 4
+.IX Item "Parallel tests"
+.IP "DTrace support" 4
+.IX Item "DTrace support"
+.ie n .IP "Support for ""configure_requires"" in CPAN module metadata" 4
+.el .IP "Support for \f(CWconfigure_requires\fR in CPAN module metadata" 4
+.IX Item "Support for configure_requires in CPAN module metadata"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.PD
+\&\f(CW\*(C`autodie\*(C'\fR, \f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR, \f(CW\*(C`parent\*(C'\fR, \f(CW\*(C`Parse::CPAN::Meta\*(C'\fR
+.IP "Pragmata Changes" 4
+.IX Item "Pragmata Changes"
+\&\f(CW\*(C`attributes\*(C'\fR, \f(CW\*(C`attrs\*(C'\fR, \f(CW\*(C`base\*(C'\fR, \f(CW\*(C`bigint\*(C'\fR, \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`bigrat\*(C'\fR,
+\&\f(CW\*(C`charnames\*(C'\fR, \f(CW\*(C`constant\*(C'\fR, \f(CW\*(C`feature\*(C'\fR, \f(CW\*(C`fields\*(C'\fR, \f(CW\*(C`lib\*(C'\fR, \f(CW\*(C`open\*(C'\fR,
+\&\f(CW\*(C`overload\*(C'\fR, \f(CW\*(C`overloading\*(C'\fR, \f(CW\*(C`version\*(C'\fR
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+\&\f(CW\*(C`Archive::Extract\*(C'\fR, \f(CW\*(C`Archive::Tar\*(C'\fR, \f(CW\*(C`Attribute::Handlers\*(C'\fR,
+\&\f(CW\*(C`AutoLoader\*(C'\fR, \f(CW\*(C`AutoSplit\*(C'\fR, \f(CW\*(C`B\*(C'\fR, \f(CW\*(C`B::Debug\*(C'\fR, \f(CW\*(C`B::Deparse\*(C'\fR, \f(CW\*(C`B::Lint\*(C'\fR,
+\&\f(CW\*(C`B::Xref\*(C'\fR, \f(CW\*(C`Benchmark\*(C'\fR, \f(CW\*(C`Carp\*(C'\fR, \f(CW\*(C`CGI\*(C'\fR, \f(CW\*(C`Compress::Zlib\*(C'\fR, \f(CW\*(C`CPAN\*(C'\fR,
+\&\f(CW\*(C`CPANPLUS\*(C'\fR, \f(CW\*(C`CPANPLUS::Dist::Build\*(C'\fR, \f(CW\*(C`Cwd\*(C'\fR, \f(CW\*(C`Data::Dumper\*(C'\fR, \f(CW\*(C`DB\*(C'\fR,
+\&\f(CW\*(C`DB_File\*(C'\fR, \f(CW\*(C`Devel::PPPort\*(C'\fR, \f(CW\*(C`Digest::MD5\*(C'\fR, \f(CW\*(C`Digest::SHA\*(C'\fR, \f(CW\*(C`DirHandle\*(C'\fR,
+\&\f(CW\*(C`Dumpvalue\*(C'\fR, \f(CW\*(C`DynaLoader\*(C'\fR, \f(CW\*(C`Encode\*(C'\fR, \f(CW\*(C`Errno\*(C'\fR, \f(CW\*(C`Exporter\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::CBuilder\*(C'\fR, \f(CW\*(C`ExtUtils::Command\*(C'\fR, \f(CW\*(C`ExtUtils::Constant\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::Embed\*(C'\fR, \f(CW\*(C`ExtUtils::Install\*(C'\fR, \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR,
+\&\f(CW\*(C`ExtUtils::Manifest\*(C'\fR, \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR, \f(CW\*(C`Fatal\*(C'\fR, \f(CW\*(C`File::Basename\*(C'\fR,
+\&\f(CW\*(C`File::Compare\*(C'\fR, \f(CW\*(C`File::Copy\*(C'\fR, \f(CW\*(C`File::Fetch\*(C'\fR, \f(CW\*(C`File::Find\*(C'\fR,
+\&\f(CW\*(C`File::Path\*(C'\fR, \f(CW\*(C`File::Spec\*(C'\fR, \f(CW\*(C`File::stat\*(C'\fR, \f(CW\*(C`File::Temp\*(C'\fR, \f(CW\*(C`FileCache\*(C'\fR,
+\&\f(CW\*(C`FileHandle\*(C'\fR, \f(CW\*(C`Filter::Simple\*(C'\fR, \f(CW\*(C`Filter::Util::Call\*(C'\fR, \f(CW\*(C`FindBin\*(C'\fR,
+\&\f(CW\*(C`GDBM_File\*(C'\fR, \f(CW\*(C`Getopt::Long\*(C'\fR, \f(CW\*(C`Hash::Util::FieldHash\*(C'\fR, \f(CW\*(C`I18N::Collate\*(C'\fR,
+\&\f(CW\*(C`IO\*(C'\fR, \f(CW\*(C`IO::Compress::*\*(C'\fR, \f(CW\*(C`IO::Dir\*(C'\fR, \f(CW\*(C`IO::Handle\*(C'\fR, \f(CW\*(C`IO::Socket\*(C'\fR,
+\&\f(CW\*(C`IO::Zlib\*(C'\fR, \f(CW\*(C`IPC::Cmd\*(C'\fR, \f(CW\*(C`IPC::Open3\*(C'\fR, \f(CW\*(C`IPC::SysV\*(C'\fR, \f(CW\*(C`lib\*(C'\fR,
+\&\f(CW\*(C`List::Util\*(C'\fR, \f(CW\*(C`Locale::MakeText\*(C'\fR, \f(CW\*(C`Log::Message\*(C'\fR, \f(CW\*(C`Math::BigFloat\*(C'\fR,
+\&\f(CW\*(C`Math::BigInt\*(C'\fR, \f(CW\*(C`Math::BigInt::FastCalc\*(C'\fR, \f(CW\*(C`Math::BigRat\*(C'\fR,
+\&\f(CW\*(C`Math::Complex\*(C'\fR, \f(CW\*(C`Math::Trig\*(C'\fR, \f(CW\*(C`Memoize\*(C'\fR, \f(CW\*(C`Module::Build\*(C'\fR,
+\&\f(CW\*(C`Module::CoreList\*(C'\fR, \f(CW\*(C`Module::Load\*(C'\fR, \f(CW\*(C`Module::Load::Conditional\*(C'\fR,
+\&\f(CW\*(C`Module::Loaded\*(C'\fR, \f(CW\*(C`Module::Pluggable\*(C'\fR, \f(CW\*(C`NDBM_File\*(C'\fR, \f(CW\*(C`Net::Ping\*(C'\fR,
+\&\f(CW\*(C`NEXT\*(C'\fR, \f(CW\*(C`Object::Accessor\*(C'\fR, \f(CW\*(C`OS2::REXX\*(C'\fR, \f(CW\*(C`Package::Constants\*(C'\fR,
+\&\f(CW\*(C`PerlIO\*(C'\fR, \f(CW\*(C`PerlIO::via\*(C'\fR, \f(CW\*(C`Pod::Man\*(C'\fR, \f(CW\*(C`Pod::Parser\*(C'\fR, \f(CW\*(C`Pod::Simple\*(C'\fR,
+\&\f(CW\*(C`Pod::Text\*(C'\fR, \f(CW\*(C`POSIX\*(C'\fR, \f(CW\*(C`Safe\*(C'\fR, \f(CW\*(C`Scalar::Util\*(C'\fR, \f(CW\*(C`SelectSaver\*(C'\fR,
+\&\f(CW\*(C`SelfLoader\*(C'\fR, \f(CW\*(C`Socket\*(C'\fR, \f(CW\*(C`Storable\*(C'\fR, \f(CW\*(C`Switch\*(C'\fR, \f(CW\*(C`Symbol\*(C'\fR,
+\&\f(CW\*(C`Sys::Syslog\*(C'\fR, \f(CW\*(C`Term::ANSIColor\*(C'\fR, \f(CW\*(C`Term::ReadLine\*(C'\fR, \f(CW\*(C`Term::UI\*(C'\fR,
+\&\f(CW\*(C`Test::Harness\*(C'\fR, \f(CW\*(C`Test::Simple\*(C'\fR, \f(CW\*(C`Text::ParseWords\*(C'\fR, \f(CW\*(C`Text::Tabs\*(C'\fR,
+\&\f(CW\*(C`Text::Wrap\*(C'\fR, \f(CW\*(C`Thread::Queue\*(C'\fR, \f(CW\*(C`Thread::Semaphore\*(C'\fR, \f(CW\*(C`threads\*(C'\fR,
+\&\f(CW\*(C`threads::shared\*(C'\fR, \f(CW\*(C`Tie::RefHash\*(C'\fR, \f(CW\*(C`Tie::StdHandle\*(C'\fR, \f(CW\*(C`Time::HiRes\*(C'\fR,
+\&\f(CW\*(C`Time::Local\*(C'\fR, \f(CW\*(C`Time::Piece\*(C'\fR, \f(CW\*(C`Unicode::Normalize\*(C'\fR, \f(CW\*(C`Unicode::UCD\*(C'\fR,
+\&\f(CW\*(C`UNIVERSAL\*(C'\fR, \f(CW\*(C`Win32\*(C'\fR, \f(CW\*(C`Win32API::File\*(C'\fR, \f(CW\*(C`XSLoader\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+\&\fIh2ph\fR, \fIh2xs\fR, \fIperl5db.pl\fR, \fIperlthanks\fR
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+perlhaiku, perlmroapi, perlperf, perlrepository, perlthanks
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.PD 0
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "\fIext/\fR reorganisation" 4
+.IX Item "ext/ reorganisation"
+.IP "Configuration improvements" 4
+.IX Item "Configuration improvements"
+.IP "Compilation improvements" 4
+.IX Item "Compilation improvements"
+.IP "Platform Specific Changes" 4
+.IX Item "Platform Specific Changes"
+.PD
+AIX, Cygwin, FreeBSD, Irix, Haiku, MirOS BSD, NetBSD, Stratus VOS, Symbian,
+Win32, VMS
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.PD
+\&\f(CW\*(C`panic: sv_chop %s\*(C'\fR, \f(CW\*(C`Can\*(Aqt locate package %s for the parents of %s\*(C'\fR,
+\&\f(CW\*(C`v\-string in use/require is non\-portable\*(C'\fR, \f(CWDeep recursion on subroutine
+"%s"\fR
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+\&\f(CW\*(C`SVf_UTF8\*(C'\fR, \f(CW\*(C`SVs_TEMP\*(C'\fR
+.IP "New Tests" 4
+.IX Item "New Tests"
+t/comp/retainedlines.t, t/io/perlio_fail.t, t/io/perlio_leaks.t,
+t/io/perlio_open.t, t/io/perlio.t, t/io/pvbm.t, t/mro/package_aliases.t,
+t/op/dbm.t, t/op/index_thr.t, t/op/pat_thr.t, t/op/qr_gc.t,
+t/op/reg_email_thr.t, t/op/regexp_qr_embed_thr.t,
+t/op/regexp_unicode_prop.t, t/op/regexp_unicode_prop_thr.t,
+t/op/reg_nc_tie.t, t/op/reg_posixcc.t, t/op/re.t, t/op/setpgrpstack.t,
+t/op/substr_thr.t, t/op/upgrade.t, t/uni/lex_utf8.t, t/uni/tie.t
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.PD 0
+.IP Deprecations 4
+.IX Item "Deprecations"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl5100delta \- what is new for perl 5.10.0"
+.IX Subsection "perl5100delta - what is new for perl 5.10.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.ie n .IP "The ""feature"" pragma" 4
+.el .IP "The \f(CWfeature\fR pragma" 4
+.IX Item "The feature pragma"
+.IP "New \fB\-E\fR command-line switch" 4
+.IX Item "New -E command-line switch"
+.IP "Defined-or operator" 4
+.IX Item "Defined-or operator"
+.IP "Switch and Smart Match operator" 4
+.IX Item "Switch and Smart Match operator"
+.IP "Regular expressions" 4
+.IX Item "Regular expressions"
+.PD
+Recursive Patterns, Named Capture Buffers, Possessive Quantifiers,
+Backtracking control verbs, Relative backreferences, \f(CW\*(C`\eK\*(C'\fR escape, Vertical
+and horizontal whitespace, and linebreak, Optional pre-match and post-match
+captures with the /p flag
+.ie n .IP say() 4
+.el .IP \f(CWsay()\fR 4
+.IX Item "say()"
+.PD 0
+.ie n .IP "Lexical $_" 4
+.el .IP "Lexical \f(CW$_\fR" 4
+.IX Item "Lexical $_"
+.ie n .IP "The ""_"" prototype" 4
+.el .IP "The \f(CW_\fR prototype" 4
+.IX Item "The _ prototype"
+.IP "UNITCHECK blocks" 4
+.IX Item "UNITCHECK blocks"
+.ie n .IP "New Pragma, ""mro""" 4
+.el .IP "New Pragma, \f(CWmro\fR" 4
+.IX Item "New Pragma, mro"
+.IP "\fBreaddir()\fR may return a ""short filename"" on Windows" 4
+.IX Item "readdir() may return a ""short filename"" on Windows"
+.IP "\fBreadpipe()\fR is now overridable" 4
+.IX Item "readpipe() is now overridable"
+.IP "Default argument for \fBreadline()\fR" 4
+.IX Item "Default argument for readline()"
+.IP "\fBstate()\fR variables" 4
+.IX Item "state() variables"
+.IP "Stacked filetest operators" 4
+.IX Item "Stacked filetest operators"
+.IP \fBUNIVERSAL::DOES()\fR 4
+.IX Item "UNIVERSAL::DOES()"
+.IP Formats 4
+.IX Item "Formats"
+.IP "Byte-order modifiers for \fBpack()\fR and \fBunpack()\fR" 4
+.IX Item "Byte-order modifiers for pack() and unpack()"
+.ie n .IP """no VERSION""" 4
+.el .IP "\f(CWno VERSION\fR" 4
+.IX Item "no VERSION"
+.ie n .IP """chdir"", ""chmod"" and ""chown"" on filehandles" 4
+.el .IP "\f(CWchdir\fR, \f(CWchmod\fR and \f(CWchown\fR on filehandles" 4
+.IX Item "chdir, chmod and chown on filehandles"
+.IP "OS groups" 4
+.IX Item "OS groups"
+.IP "Recursive sort subs" 4
+.IX Item "Recursive sort subs"
+.IP "Exceptions in constant folding" 4
+.IX Item "Exceptions in constant folding"
+.ie n .IP "Source filters in @INC" 4
+.el .IP "Source filters in \f(CW@INC\fR" 4
+.IX Item "Source filters in @INC"
+.IP "New internal variables" 4
+.IX Item "New internal variables"
+.PD
+\&\f(CW\*(C`${^RE_DEBUG_FLAGS}\*(C'\fR, \f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR, \f(CW\*(C`${^RE_TRIE_MAXBUF}\*(C'\fR,
+\&\f(CW\*(C`${^WIN32_SLOPPY_STAT}\*(C'\fR
+.IP Miscellaneous 4
+.IX Item "Miscellaneous"
+.PD 0
+.IP "UCD 5.0.0" 4
+.IX Item "UCD 5.0.0"
+.IP MAD 4
+.IX Item "MAD"
+.IP "\fBkill()\fR on Windows" 4
+.IX Item "kill() on Windows"
+.RE
+.RS 4
+.RE
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Packing and UTF\-8 strings" 4
+.IX Item "Packing and UTF-8 strings"
+.IP "Byte/character count feature in \fBunpack()\fR" 4
+.IX Item "Byte/character count feature in unpack()"
+.ie n .IP "The $* and $# variables have been removed" 4
+.el .IP "The \f(CW$*\fR and \f(CW$#\fR variables have been removed" 4
+.IX Item "The $* and $# variables have been removed"
+.IP "\fBsubstr()\fR lvalues are no longer fixed-length" 4
+.IX Item "substr() lvalues are no longer fixed-length"
+.ie n .IP "Parsing of ""\-f _""" 4
+.el .IP "Parsing of \f(CW\-f _\fR" 4
+.IX Item "Parsing of -f _"
+.ie n .IP """:unique""" 4
+.el .IP \f(CW:unique\fR 4
+.IX Item ":unique"
+.IP "Effect of pragmas in eval" 4
+.IX Item "Effect of pragmas in eval"
+.IP "chdir FOO" 4
+.IX Item "chdir FOO"
+.IP "Handling of .pmc files" 4
+.IX Item "Handling of .pmc files"
+.ie n .IP "$^V is now a ""version"" object instead of a v\-string" 4
+.el .IP "$^V is now a \f(CWversion\fR object instead of a v\-string" 4
+.IX Item "$^V is now a version object instead of a v-string"
+.IP "@\- and @+ in patterns" 4
+.IX Item "@- and @+ in patterns"
+.ie n .IP "$AUTOLOAD can now be tainted" 4
+.el .IP "\f(CW$AUTOLOAD\fR can now be tainted" 4
+.IX Item "$AUTOLOAD can now be tainted"
+.IP "Tainting and printf" 4
+.IX Item "Tainting and printf"
+.IP "undef and signal handlers" 4
+.IX Item "undef and signal handlers"
+.IP "strictures and dereferencing in \fBdefined()\fR" 4
+.IX Item "strictures and dereferencing in defined()"
+.ie n .IP """(?p{})"" has been removed" 4
+.el .IP "\f(CW(?p{})\fR has been removed" 4
+.IX Item "(?p{}) has been removed"
+.IP "Pseudo-hashes have been removed" 4
+.IX Item "Pseudo-hashes have been removed"
+.IP "Removal of the bytecode compiler and of perlcc" 4
+.IX Item "Removal of the bytecode compiler and of perlcc"
+.IP "Removal of the JPL" 4
+.IX Item "Removal of the JPL"
+.IP "Recursive inheritance detected earlier" 4
+.IX Item "Recursive inheritance detected earlier"
+.IP "warnings::enabled and warnings::warnif changed to favor users of modules" 4
+.IX Item "warnings::enabled and warnings::warnif changed to favor users of modules"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Upgrading individual core modules" 4
+.IX Item "Upgrading individual core modules"
+.IP "Pragmata Changes" 4
+.IX Item "Pragmata Changes"
+.PD
+\&\f(CW\*(C`feature\*(C'\fR, \f(CW\*(C`mro\*(C'\fR, Scoping of the \f(CW\*(C`sort\*(C'\fR pragma, Scoping of \f(CW\*(C`bignum\*(C'\fR,
+\&\f(CW\*(C`bigint\*(C'\fR, \f(CW\*(C`bigrat\*(C'\fR, \f(CW\*(C`base\*(C'\fR, \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR, \f(CW\*(C`version\*(C'\fR,
+\&\f(CW\*(C`warnings\*(C'\fR, \f(CW\*(C`less\*(C'\fR
+.IP "New modules" 4
+.IX Item "New modules"
+.PD 0
+.IP "Selected Changes to Core Modules" 4
+.IX Item "Selected Changes to Core Modules"
+.PD
+\&\f(CW\*(C`Attribute::Handlers\*(C'\fR, \f(CW\*(C`B::Lint\*(C'\fR, \f(CW\*(C`B\*(C'\fR, \f(CW\*(C`Thread\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+perl \-d, ptar, ptardiff, shasum, corelist, h2ph and h2xs, perlivp,
+find2perl, config_data, cpanp, cpan2dist, pod2html
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.PD 0
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.RS 4
+.IP "In-place sorting" 4
+.IX Item "In-place sorting"
+.IP "Lexical array access" 4
+.IX Item "Lexical array access"
+.IP "XS-assisted SWASHGET" 4
+.IX Item "XS-assisted SWASHGET"
+.IP "Constant subroutines" 4
+.IX Item "Constant subroutines"
+.ie n .IP """PERL_DONT_CREATE_GVSV""" 4
+.el .IP \f(CWPERL_DONT_CREATE_GVSV\fR 4
+.IX Item "PERL_DONT_CREATE_GVSV"
+.IP "Weak references are cheaper" 4
+.IX Item "Weak references are cheaper"
+.IP "\fBsort()\fR enhancements" 4
+.IX Item "sort() enhancements"
+.IP "Memory optimisations" 4
+.IX Item "Memory optimisations"
+.IP "UTF\-8 cache optimisation" 4
+.IX Item "UTF-8 cache optimisation"
+.IP "Sloppy stat on Windows" 4
+.IX Item "Sloppy stat on Windows"
+.IP "Regular expressions optimisations" 4
+.IX Item "Regular expressions optimisations"
+.PD
+Engine de-recursivised, Single char char-classes treated as literals, Trie
+optimisation of literal string alternations, Aho-Corasick start-point
+optimisation
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.PD 0
+.IP "Configuration improvements" 4
+.IX Item "Configuration improvements"
+.PD
+\&\f(CW\*(C`\-Dusesitecustomize\*(C'\fR, Relocatable installations, \fBstrlcat()\fR and \fBstrlcpy()\fR,
+\&\f(CW\*(C`d_pseudofork\*(C'\fR and \f(CW\*(C`d_printf_format_null\*(C'\fR, Configure help
+.IP "Compilation improvements" 4
+.IX Item "Compilation improvements"
+Parallel build, Borland's compilers support, Static build on Windows,
+ppport.h files, C++ compatibility, Support for Microsoft 64\-bit compiler,
+Visual C++, Win32 builds
+.IP "Installation improvements" 4
+.IX Item "Installation improvements"
+Module auxiliary files
+.IP "New Or Improved Platforms" 4
+.IX Item "New Or Improved Platforms"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD
+strictures in regexp-eval blocks, Calling \fBCORE::require()\fR, Subscripts of
+slices, \f(CW\*(C`no warnings \*(Aqcategory\*(Aq\*(C'\fR works correctly with \-w, threads
+improvements, \fBchr()\fR and negative values, PERL5SHELL and tainting, Using
+*FILE{IO}, Overloading and reblessing, Overloading and UTF\-8, eval memory
+leaks fixed, Random device on Windows, PERLIO_DEBUG, PerlIO::scalar and
+read-only scalars, \fBstudy()\fR and UTF\-8, Critical signals, \f(CW@INC\fR\-hook fix,
+\&\f(CW\*(C`\-t\*(C'\fR switch fix, Duping UTF\-8 filehandles, Localisation of hash elements
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+Use of uninitialized value, Deprecated use of \fBmy()\fR in false conditional,
+!=~ should be !~, Newline in left-justified string, Too late for "\-T"
+option, "%s" variable \f(CW%s\fR masks earlier declaration,
+\&\fBreaddir()\fR/\fBclosedir()\fR/etc. attempted on invalid dirhandle, Opening
+dirhandle/filehandle \f(CW%s\fR also as a file/directory, Use of \-P is deprecated,
+v\-string in use/require is non-portable, perl \-V
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.RS 4
+.PD 0
+.IP "Reordering of SVt_* constants" 4
+.IX Item "Reordering of SVt_* constants"
+.IP "Elimination of SVt_PVBM" 4
+.IX Item "Elimination of SVt_PVBM"
+.IP "New type SVt_BIND" 4
+.IX Item "New type SVt_BIND"
+.IP "Removal of CPP symbols" 4
+.IX Item "Removal of CPP symbols"
+.IP "Less space is used by ops" 4
+.IX Item "Less space is used by ops"
+.IP "New parser" 4
+.IX Item "New parser"
+.ie n .IP "Use of ""const""" 4
+.el .IP "Use of \f(CWconst\fR" 4
+.IX Item "Use of const"
+.IP Mathoms 4
+.IX Item "Mathoms"
+.ie n .IP """AvFLAGS"" has been removed" 4
+.el .IP "\f(CWAvFLAGS\fR has been removed" 4
+.IX Item "AvFLAGS has been removed"
+.ie n .IP """av_*"" changes" 4
+.el .IP "\f(CWav_*\fR changes" 4
+.IX Item "av_* changes"
+.IP "$^H and %^H" 4
+.IX Item "$^H and %^H"
+.IP "B:: modules inheritance changed" 4
+.IX Item "B:: modules inheritance changed"
+.IP "Anonymous hash and array constructors" 4
+.IX Item "Anonymous hash and array constructors"
+.RE
+.RS 4
+.RE
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.RS 4
+.IP "UTF\-8 problems" 4
+.IX Item "UTF-8 problems"
+.RE
+.RS 4
+.RE
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl589delta \- what is new for perl v5.8.9"
+.IX Subsection "perl589delta - what is new for perl v5.8.9"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Notice 4
+.IX Item "Notice"
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Unicode Character Database 5.1.0." 4
+.IX Item "Unicode Character Database 5.1.0."
+.IP "stat and \-X on directory handles" 4
+.IX Item "stat and -X on directory handles"
+.ie n .IP "Source filters in @INC" 4
+.el .IP "Source filters in \f(CW@INC\fR" 4
+.IX Item "Source filters in @INC"
+.IP "Exceptions in constant folding" 4
+.IX Item "Exceptions in constant folding"
+.ie n .IP """no VERSION""" 4
+.el .IP "\f(CWno VERSION\fR" 4
+.IX Item "no VERSION"
+.IP "Improved internal UTF\-8 caching code" 4
+.IX Item "Improved internal UTF-8 caching code"
+.IP "Runtime relocatable installations" 4
+.IX Item "Runtime relocatable installations"
+.IP "New internal variables" 4
+.IX Item "New internal variables"
+.PD
+\&\f(CW\*(C`${^CHILD_ERROR_NATIVE}\*(C'\fR, \f(CW\*(C`${^UTF8CACHE}\*(C'\fR
+.ie n .IP """readpipe"" is now overridable" 4
+.el .IP "\f(CWreadpipe\fR is now overridable" 4
+.IX Item "readpipe is now overridable"
+.PD 0
+.IP "simple exception handling macros" 4
+.IX Item "simple exception handling macros"
+.IP "\-D option enhancements" 4
+.IX Item "-D option enhancements"
+.IP "XS-assisted SWASHGET" 4
+.IX Item "XS-assisted SWASHGET"
+.IP "Constant subroutines" 4
+.IX Item "Constant subroutines"
+.RE
+.RS 4
+.RE
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules" 4
+.IX Item "New Modules"
+.IP "Updated Modules" 4
+.IX Item "Updated Modules"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "debugger upgraded to version 1.31" 4
+.IX Item "debugger upgraded to version 1.31"
+.IP \fIperlthanks\fR 4
+.IX Item "perlthanks"
+.IP \fIperlbug\fR 4
+.IX Item "perlbug"
+.IP \fIh2xs\fR 4
+.IX Item "h2xs"
+.IP \fIh2ph\fR 4
+.IX Item "h2ph"
+.RE
+.RS 4
+.RE
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Changes to Existing Documentation" 4
+.IX Item "Changes to Existing Documentation"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Relocatable installations" 4
+.IX Item "Relocatable installations"
+.IP "Configuration improvements" 4
+.IX Item "Configuration improvements"
+.IP "Compilation improvements" 4
+.IX Item "Compilation improvements"
+.IP "Installation improvements." 4
+.IX Item "Installation improvements."
+.IP "Platform Specific Changes" 4
+.IX Item "Platform Specific Changes"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP Unicode 4
+.IX Item "Unicode"
+.IP PerlIO 4
+.IX Item "PerlIO"
+.IP Magic 4
+.IX Item "Magic"
+.IP "Reblessing overloaded objects now works" 4
+.IX Item "Reblessing overloaded objects now works"
+.ie n .IP """strict"" now propagates correctly into string evals" 4
+.el .IP "\f(CWstrict\fR now propagates correctly into string evals" 4
+.IX Item "strict now propagates correctly into string evals"
+.IP "Other fixes" 4
+.IX Item "Other fixes"
+.IP "Platform Specific Fixes" 4
+.IX Item "Platform Specific Fixes"
+.IP "Smaller fixes" 4
+.IX Item "Smaller fixes"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.RS 4
+.ie n .IP "panic: sv_chop %s" 4
+.el .IP "panic: sv_chop \f(CW%s\fR" 4
+.IX Item "panic: sv_chop %s"
+.IP "Maximal count of pending signals (%s) exceeded" 4
+.IX Item "Maximal count of pending signals (%s) exceeded"
+.ie n .IP "panic: attempt to call %s in %s" 4
+.el .IP "panic: attempt to call \f(CW%s\fR in \f(CW%s\fR" 4
+.IX Item "panic: attempt to call %s in %s"
+.IP "FETCHSIZE returned a negative value" 4
+.IX Item "FETCHSIZE returned a negative value"
+.ie n .IP "Can't upgrade %s (%d) to %d" 4
+.el .IP "Can't upgrade \f(CW%s\fR (%d) to \f(CW%d\fR" 4
+.IX Item "Can't upgrade %s (%d) to %d"
+.ie n .IP "%s argument is not a HASH or ARRAY element or a subroutine" 4
+.el .IP "\f(CW%s\fR argument is not a HASH or ARRAY element or a subroutine" 4
+.IX Item "%s argument is not a HASH or ARRAY element or a subroutine"
+.ie n .IP "Cannot make the non-overridable builtin %s fatal" 4
+.el .IP "Cannot make the non-overridable builtin \f(CW%s\fR fatal" 4
+.IX Item "Cannot make the non-overridable builtin %s fatal"
+.ie n .IP "Unrecognized character '%s' in column %d" 4
+.el .IP "Unrecognized character '%s' in column \f(CW%d\fR" 4
+.IX Item "Unrecognized character '%s' in column %d"
+.IP "Offset outside string" 4
+.IX Item "Offset outside string"
+.IP "Invalid escape in the specified encoding in regexp; marked by <\-\- HERE in m/%s/" 4
+.IX Item "Invalid escape in the specified encoding in regexp; marked by <-- HERE in m/%s/"
+.IP "Your machine doesn't support dump/undump." 4
+.IX Item "Your machine doesn't support dump/undump."
+.RE
+.RS 4
+.RE
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.RS 4
+.IP "Macro cleanups" 4
+.IX Item "Macro cleanups"
+.RE
+.RS 4
+.RE
+.IP "New Tests" 4
+.IX Item "New Tests"
+.PD
+ext/DynaLoader/t/DynaLoader.t, t/comp/fold.t, t/io/pvbm.t,
+t/lib/proxy_constant_subs.t, t/op/attrhand.t, t/op/dbm.t,
+t/op/inccode\-tie.t, t/op/incfilter.t, t/op/kill0.t, t/op/qrstack.t,
+t/op/qr.t, t/op/regexp_qr_embed.t, t/op/regexp_qr.t, t/op/rxcode.t,
+t/op/studytied.t, t/op/substT.t, t/op/symbolcache.t, t/op/upgrade.t,
+t/mro/package_aliases.t, t/pod/twice.t, t/run/cloexec.t, t/uni/cache.t,
+t/uni/chr.t, t/uni/greek.t, t/uni/latin2.t, t/uni/overload.t, t/uni/tie.t
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.PD 0
+.IP "Platform Specific Notes" 4
+.IX Item "Platform Specific Notes"
+.RS 4
+.IP Win32 4
+.IX Item "Win32"
+.IP OS/2 4
+.IX Item "OS/2"
+.IP VMS 4
+.IX Item "VMS"
+.RE
+.RS 4
+.RE
+.IP Obituary 4
+.IX Item "Obituary"
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl588delta \- what is new for perl v5.8.8"
+.IX Subsection "perl588delta - what is new for perl v5.8.8"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.ie n .IP """h2xs"" enhancements" 4
+.el .IP "\f(CWh2xs\fR enhancements" 4
+.IX Item "h2xs enhancements"
+.ie n .IP """perlivp"" enhancements" 4
+.el .IP "\f(CWperlivp\fR enhancements" 4
+.IX Item "perlivp enhancements"
+.RE
+.RS 4
+.RE
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP "no warnings 'category' works correctly with \-w" 4
+.IX Item "no warnings 'category' works correctly with -w"
+.IP "Remove over-optimisation" 4
+.IX Item "Remove over-optimisation"
+.IP "\fBsprintf()\fR fixes" 4
+.IX Item "sprintf() fixes"
+.IP "Debugger and Unicode slowdown" 4
+.IX Item "Debugger and Unicode slowdown"
+.IP "Smaller fixes" 4
+.IX Item "Smaller fixes"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.RS 4
+.IP "Attempt to set length of freed array" 4
+.IX Item "Attempt to set length of freed array"
+.IP "Non-string passed as bitmask" 4
+.IX Item "Non-string passed as bitmask"
+.IP "Search pattern not terminated or ternary operator parsed as search pattern" 4
+.IX Item "Search pattern not terminated or ternary operator parsed as search pattern"
+.RE
+.RS 4
+.RE
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl587delta \- what is new for perl v5.8.7"
+.IX Subsection "perl587delta - what is new for perl v5.8.7"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Unicode Character Database 4.1.0" 4
+.IX Item "Unicode Character Database 4.1.0"
+.IP "suidperl less insecure" 4
+.IX Item "suidperl less insecure"
+.IP "Optional site customization script" 4
+.IX Item "Optional site customization script"
+.ie n .IP """Config.pm"" is now much smaller." 4
+.el .IP "\f(CWConfig.pm\fR is now much smaller." 4
+.IX Item "Config.pm is now much smaller."
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "find2perl enhancements" 4
+.IX Item "find2perl enhancements"
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl586delta \- what is new for perl v5.8.6"
+.IX Subsection "perl586delta - what is new for perl v5.8.6"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "New Tests" 4
+.IX Item "New Tests"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl585delta \- what is new for perl v5.8.5"
+.IX Subsection "perl585delta - what is new for perl v5.8.5"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP "Perl's debugger" 4
+.IX Item "Perl's debugger"
+.IP h2ph 4
+.IX Item "h2ph"
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl584delta \- what is new for perl v5.8.4"
+.IX Subsection "perl584delta - what is new for perl v5.8.4"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Malloc wrapping" 4
+.IX Item "Malloc wrapping"
+.IP "Unicode Character Database 4.0.1" 4
+.IX Item "Unicode Character Database 4.0.1"
+.IP "suidperl less insecure" 4
+.IX Item "suidperl less insecure"
+.IP format 4
+.IX Item "format"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated modules" 4
+.IX Item "Updated modules"
+.PD
+Attribute::Handlers, B, Benchmark, CGI, Carp, Cwd, Exporter, File::Find,
+IO, IPC::Open3, Local::Maketext, Math::BigFloat, Math::BigInt,
+Math::BigRat, MIME::Base64, ODBM_File, POSIX, Shell, Socket, Storable,
+Switch, Sys::Syslog, Term::ANSIColor, Time::HiRes, Unicode::UCD, Win32,
+base, open, threads, utf8
+.RE
+.RS 4
+.RE
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.PD 0
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Future Directions" 4
+.IX Item "Future Directions"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl583delta \- what is new for perl v5.8.3"
+.IX Subsection "perl583delta - what is new for perl v5.8.3"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.PD
+CGI, Cwd, Digest, Digest::MD5, Encode, File::Spec, FindBin, List::Util,
+Math::BigInt, PodParser, Pod::Perldoc, POSIX, Unicode::Collate,
+Unicode::Normalize, Test::Harness, threads::shared
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.PD 0
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Configuration and Building" 4
+.IX Item "Configuration and Building"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Future Directions" 4
+.IX Item "Future Directions"
+.IP Obituary 4
+.IX Item "Obituary"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl582delta \- what is new for perl v5.8.2"
+.IX Subsection "perl582delta - what is new for perl v5.8.2"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Hash Randomisation" 4
+.IX Item "Hash Randomisation"
+.IP Threading 4
+.IX Item "Threading"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules And Pragmata" 4
+.IX Item "Updated Modules And Pragmata"
+.PD
+Devel::PPPort, Digest::MD5, I18N::LangTags, libnet, MIME::Base64,
+Pod::Perldoc, strict, Tie::Hash, Time::HiRes, Unicode::Collate,
+Unicode::Normalize, UNIVERSAL
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.PD 0
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.IP "Future Directions" 4
+.IX Item "Future Directions"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl581delta \- what is new for perl v5.8.1"
+.IX Subsection "perl581delta - what is new for perl v5.8.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Hash Randomisation" 4
+.IX Item "Hash Randomisation"
+.IP "UTF\-8 On Filehandles No Longer Activated By Locale" 4
+.IX Item "UTF-8 On Filehandles No Longer Activated By Locale"
+.IP "Single-number v\-strings are no longer v\-strings before ""=>""" 4
+.IX Item "Single-number v-strings are no longer v-strings before ""=>"""
+.IP "(Win32) The \-C Switch Has Been Repurposed" 4
+.IX Item "(Win32) The -C Switch Has Been Repurposed"
+.IP "(Win32) The /d Switch Of cmd.exe" 4
+.IX Item "(Win32) The /d Switch Of cmd.exe"
+.RE
+.RS 4
+.RE
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "UTF\-8 no longer default under UTF\-8 locales" 4
+.IX Item "UTF-8 no longer default under UTF-8 locales"
+.IP "Unsafe signals again available" 4
+.IX Item "Unsafe signals again available"
+.IP "Tied Arrays with Negative Array Indices" 4
+.IX Item "Tied Arrays with Negative Array Indices"
+.IP "local ${$x}" 4
+.IX Item "local ${$x}"
+.IP "Unicode Character Database 4.0.0" 4
+.IX Item "Unicode Character Database 4.0.0"
+.IP "Deprecation Warnings" 4
+.IX Item "Deprecation Warnings"
+.IP "Miscellaneous Enhancements" 4
+.IX Item "Miscellaneous Enhancements"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "Updated Modules And Pragmata" 4
+.IX Item "Updated Modules And Pragmata"
+.PD
+base, B::Bytecode, B::Concise, B::Deparse, Benchmark, ByteLoader, bytes,
+CGI, charnames, CPAN, Data::Dumper, DB_File, Devel::PPPort, Digest::MD5,
+Encode, fields, libnet, Math::BigInt, MIME::Base64, NEXT, Net::Ping,
+PerlIO::scalar, podlators, Pod::LaTeX, PodParsers, Pod::Perldoc,
+Scalar::Util, Storable, strict, Term::ANSIcolor, Test::Harness, Test::More,
+Test::Simple, Text::Balanced, Time::HiRes, threads, threads::shared,
+Unicode::Collate, Unicode::Normalize, Win32::GetFolderPath,
+Win32::GetOSVersion
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.PD 0
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Platform-specific enhancements" 4
+.IX Item "Platform-specific enhancements"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP "Closures, eval and lexicals" 4
+.IX Item "Closures, eval and lexicals"
+.IP "Generic fixes" 4
+.IX Item "Generic fixes"
+.IP "Platform-specific fixes" 4
+.IX Item "Platform-specific fixes"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.RS 4
+.ie n .IP "Changed ""A thread exited while %d threads were running""" 4
+.el .IP "Changed ""A thread exited while \f(CW%d\fR threads were running""" 4
+.IX Item "Changed ""A thread exited while %d threads were running"""
+.IP "Removed ""Attempt to clear a restricted hash""" 4
+.IX Item "Removed ""Attempt to clear a restricted hash"""
+.IP "New ""Illegal declaration of anonymous subroutine""" 4
+.IX Item "New ""Illegal declaration of anonymous subroutine"""
+.IP "Changed ""Invalid range ""%s"" in transliteration operator""" 4
+.IX Item "Changed ""Invalid range ""%s"" in transliteration operator"""
+.IP "New ""Missing control char name in \ec""" 4
+.IX Item "New ""Missing control char name in c"""
+.ie n .IP "New ""Newline in left-justified string for %s""" 4
+.el .IP "New ""Newline in left-justified string for \f(CW%s\fR""" 4
+.IX Item "New ""Newline in left-justified string for %s"""
+.ie n .IP "New ""Possible precedence problem on bitwise %c operator""" 4
+.el .IP "New ""Possible precedence problem on bitwise \f(CW%c\fR operator""" 4
+.IX Item "New ""Possible precedence problem on bitwise %c operator"""
+.IP "New ""Pseudo-hashes are deprecated""" 4
+.IX Item "New ""Pseudo-hashes are deprecated"""
+.ie n .IP "New ""\fBread()\fR on %s filehandle %s""" 4
+.el .IP "New ""\fBread()\fR on \f(CW%s\fR filehandle \f(CW%s\fR""" 4
+.IX Item "New ""read() on %s filehandle %s"""
+.IP "New ""5.005 threads are deprecated""" 4
+.IX Item "New ""5.005 threads are deprecated"""
+.IP "New ""Tied variable freed while still in use""" 4
+.IX Item "New ""Tied variable freed while still in use"""
+.IP "New ""To%s: illegal mapping '%s'""" 4
+.IX Item "New ""To%s: illegal mapping '%s'"""
+.IP "New ""Use of freed value in iteration""" 4
+.IX Item "New ""Use of freed value in iteration"""
+.RE
+.RS 4
+.RE
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "New Tests" 4
+.IX Item "New Tests"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.RS 4
+.IP "Tied hashes in scalar context" 4
+.IX Item "Tied hashes in scalar context"
+.IP "Net::Ping 450_service and 510_ping_udp failures" 4
+.IX Item "Net::Ping 450_service and 510_ping_udp failures"
+.IP B::C 4
+.IX Item "B::C"
+.RE
+.RS 4
+.RE
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.RS 4
+.IP "EBCDIC Platforms" 4
+.IX Item "EBCDIC Platforms"
+.IP "Cygwin 1.5 problems" 4
+.IX Item "Cygwin 1.5 problems"
+.IP "HP-UX: HP cc warnings about sendfile and sendpath" 4
+.IX Item "HP-UX: HP cc warnings about sendfile and sendpath"
+.IP "IRIX: t/uni/tr_7jis.t falsely failing" 4
+.IX Item "IRIX: t/uni/tr_7jis.t falsely failing"
+.IP "Mac OS X: no usemymalloc" 4
+.IX Item "Mac OS X: no usemymalloc"
+.IP "Tru64: No threaded builds with GNU cc (gcc)" 4
+.IX Item "Tru64: No threaded builds with GNU cc (gcc)"
+.IP "Win32: sysopen, sysread, syswrite" 4
+.IX Item "Win32: sysopen, sysread, syswrite"
+.RE
+.RS 4
+.RE
+.IP "Future Directions" 4
+.IX Item "Future Directions"
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perl58delta \- what is new for perl v5.8.0"
+.IX Subsection "perl58delta - what is new for perl v5.8.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Highlights In 5.8.0" 4
+.IX Item "Highlights In 5.8.0"
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Binary Incompatibility" 4
+.IX Item "Binary Incompatibility"
+.IP "64\-bit platforms and malloc" 4
+.IX Item "64-bit platforms and malloc"
+.IP "AIX Dynaloading" 4
+.IX Item "AIX Dynaloading"
+.ie n .IP "Attributes for ""my"" variables now handled at run-time" 4
+.el .IP "Attributes for \f(CWmy\fR variables now handled at run-time" 4
+.IX Item "Attributes for my variables now handled at run-time"
+.IP "Socket Extension Dynamic in VMS" 4
+.IX Item "Socket Extension Dynamic in VMS"
+.IP "IEEE-format Floating Point Default on OpenVMS Alpha" 4
+.IX Item "IEEE-format Floating Point Default on OpenVMS Alpha"
+.ie n .IP "New Unicode Semantics (no more ""use utf8"", almost)" 4
+.el .IP "New Unicode Semantics (no more \f(CWuse utf8\fR, almost)" 4
+.IX Item "New Unicode Semantics (no more use utf8, almost)"
+.IP "New Unicode Properties" 4
+.IX Item "New Unicode Properties"
+.IP "REF(...) Instead Of SCALAR(...)" 4
+.IX Item "REF(...) Instead Of SCALAR(...)"
+.IP "pack/unpack D/F recycled" 4
+.IX Item "pack/unpack D/F recycled"
+.IP "\fBglob()\fR now returns filenames in alphabetical order" 4
+.IX Item "glob() now returns filenames in alphabetical order"
+.IP Deprecations 4
+.IX Item "Deprecations"
+.RE
+.RS 4
+.RE
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Unicode Overhaul" 4
+.IX Item "Unicode Overhaul"
+.IP "PerlIO is Now The Default" 4
+.IX Item "PerlIO is Now The Default"
+.IP ithreads 4
+.IX Item "ithreads"
+.IP "Restricted Hashes" 4
+.IX Item "Restricted Hashes"
+.IP "Safe Signals" 4
+.IX Item "Safe Signals"
+.IP "Understanding of Numbers" 4
+.IX Item "Understanding of Numbers"
+.IP "Arrays now always interpolate into double-quoted strings [561]" 4
+.IX Item "Arrays now always interpolate into double-quoted strings [561]"
+.IP "Miscellaneous Changes" 4
+.IX Item "Miscellaneous Changes"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules and Pragmata" 4
+.IX Item "New Modules and Pragmata"
+.IP "Updated And Improved Modules and Pragmata" 4
+.IX Item "Updated And Improved Modules and Pragmata"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.IP "New Documentation" 4
+.IX Item "New Documentation"
+.IP "Performance Enhancements" 4
+.IX Item "Performance Enhancements"
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "Generic Improvements" 4
+.IX Item "Generic Improvements"
+.IP "New Or Improved Platforms" 4
+.IX Item "New Or Improved Platforms"
+.RE
+.RS 4
+.RE
+.IP "Selected Bug Fixes" 4
+.IX Item "Selected Bug Fixes"
+.RS 4
+.IP "Platform Specific Changes and Fixes" 4
+.IX Item "Platform Specific Changes and Fixes"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.IP "Changed Internals" 4
+.IX Item "Changed Internals"
+.IP "Security Vulnerability Closed [561]" 4
+.IX Item "Security Vulnerability Closed [561]"
+.IP "New Tests" 4
+.IX Item "New Tests"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.RS 4
+.IP "The Compiler Suite Is Still Very Experimental" 4
+.IX Item "The Compiler Suite Is Still Very Experimental"
+.IP "Localising Tied Arrays and Hashes Is Broken" 4
+.IX Item "Localising Tied Arrays and Hashes Is Broken"
+.IP "Building Extensions Can Fail Because Of Largefiles" 4
+.IX Item "Building Extensions Can Fail Because Of Largefiles"
+.ie n .IP "Modifying $_ Inside for(..)" 4
+.el .IP "Modifying \f(CW$_\fR Inside for(..)" 4
+.IX Item "Modifying $_ Inside for(..)"
+.IP "mod_perl 1.26 Doesn't Build With Threaded Perl" 4
+.IX Item "mod_perl 1.26 Doesn't Build With Threaded Perl"
+.IP "lib/ftmp\-security tests warn 'system possibly insecure'" 4
+.IX Item "lib/ftmp-security tests warn 'system possibly insecure'"
+.IP "libwww-perl (LWP) fails base/date #51" 4
+.IX Item "libwww-perl (LWP) fails base/date #51"
+.IP "PDL failing some tests" 4
+.IX Item "PDL failing some tests"
+.IP Perl_get_sv 4
+.IX Item "Perl_get_sv"
+.IP "Self-tying Problems" 4
+.IX Item "Self-tying Problems"
+.IP ext/threads/t/libc 4
+.IX Item "ext/threads/t/libc"
+.IP "Failure of Thread (5.005\-style) tests" 4
+.IX Item "Failure of Thread (5.005-style) tests"
+.IP "Timing problems" 4
+.IX Item "Timing problems"
+.IP "Tied/Magical Array/Hash Elements Do Not Autovivify" 4
+.IX Item "Tied/Magical Array/Hash Elements Do Not Autovivify"
+.IP "Unicode in package/class and subroutine names does not work" 4
+.IX Item "Unicode in package/class and subroutine names does not work"
+.RE
+.RS 4
+.RE
+.IP "Platform Specific Problems" 4
+.IX Item "Platform Specific Problems"
+.RS 4
+.IP AIX 4
+.IX Item "AIX"
+.IP "Alpha systems with old gccs fail several tests" 4
+.IX Item "Alpha systems with old gccs fail several tests"
+.IP AmigaOS 4
+.IX Item "AmigaOS"
+.IP BeOS 4
+.IX Item "BeOS"
+.IP "Cygwin ""unable to remap""" 4
+.IX Item "Cygwin ""unable to remap"""
+.IP "Cygwin ndbm tests fail on FAT" 4
+.IX Item "Cygwin ndbm tests fail on FAT"
+.IP "DJGPP Failures" 4
+.IX Item "DJGPP Failures"
+.IP "FreeBSD built with ithreads coredumps reading large directories" 4
+.IX Item "FreeBSD built with ithreads coredumps reading large directories"
+.IP "FreeBSD Failing locale Test 117 For ISO 8859\-15 Locales" 4
+.IX Item "FreeBSD Failing locale Test 117 For ISO 8859-15 Locales"
+.IP "IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5" 4
+.IX Item "IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5"
+.IP "HP-UX lib/posix Subtest 9 Fails When LP64\-Configured" 4
+.IX Item "HP-UX lib/posix Subtest 9 Fails When LP64-Configured"
+.IP "Linux with glibc 2.2.5 fails t/op/int subtest #6 with \-Duse64bitint" 4
+.IX Item "Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint"
+.IP "Linux With Sfio Fails op/misc Test 48" 4
+.IX Item "Linux With Sfio Fails op/misc Test 48"
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+.IP "Mac OS X dyld undefined symbols" 4
+.IX Item "Mac OS X dyld undefined symbols"
+.IP "OS/2 Test Failures" 4
+.IX Item "OS/2 Test Failures"
+.IP "op/sprintf tests 91, 129, and 130" 4
+.IX Item "op/sprintf tests 91, 129, and 130"
+.IP SCO 4
+.IX Item "SCO"
+.IP "Solaris 2.5" 4
+.IX Item "Solaris 2.5"
+.IP "Solaris x86 Fails Tests With \-Duse64bitint" 4
+.IX Item "Solaris x86 Fails Tests With -Duse64bitint"
+.IP "SUPER-UX (NEC SX)" 4
+.IX Item "SUPER-UX (NEC SX)"
+.IP "Term::ReadKey not working on Win32" 4
+.IX Item "Term::ReadKey not working on Win32"
+.IP UNICOS/mk 4
+.IX Item "UNICOS/mk"
+.IP UTS 4
+.IX Item "UTS"
+.IP "VOS (Stratus)" 4
+.IX Item "VOS (Stratus)"
+.IP VMS 4
+.IX Item "VMS"
+.IP Win32 4
+.IX Item "Win32"
+.IP "XML::Parser not working" 4
+.IX Item "XML::Parser not working"
+.IP "z/OS (OS/390)" 4
+.IX Item "z/OS (OS/390)"
+.IP "Unicode Support on EBCDIC Still Spotty" 4
+.IX Item "Unicode Support on EBCDIC Still Spotty"
+.IP "Seen In Perl 5.7 But Gone Now" 4
+.IX Item "Seen In Perl 5.7 But Gone Now"
+.RE
+.RS 4
+.RE
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perl561delta \- what's new for perl v5.6.1"
+.IX Subsection "perl561delta - what's new for perl v5.6.1"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Summary of changes between 5.6.0 and 5.6.1" 4
+.IX Item "Summary of changes between 5.6.0 and 5.6.1"
+.RS 4
+.IP "Security Issues" 4
+.IX Item "Security Issues"
+.IP "Core bug fixes" 4
+.IX Item "Core bug fixes"
+.PD
+\&\f(CWUNIVERSAL::isa()\fR, Memory leaks, Numeric conversions, qw(a\e\eb), \fBcaller()\fR,
+Bugs in regular expressions, "slurp" mode, Autovivification of symbolic
+references to special variables, Lexical warnings, Spurious warnings and
+errors, \fBglob()\fR, Tainting, \fBsort()\fR, #line directives, Subroutine prototypes,
+\&\fBmap()\fR, Debugger, PERL5OPT, \fBchop()\fR, Unicode support, 64\-bit support,
+Compiler, Lvalue subroutines, IO::Socket, File::Find, xsubpp, \f(CW\*(C`no
+Module;\*(C'\fR, Tests
+.IP "Core features" 4
+.IX Item "Core features"
+.PD 0
+.IP "Configuration issues" 4
+.IX Item "Configuration issues"
+.IP Documentation 4
+.IX Item "Documentation"
+.IP "Bundled modules" 4
+.IX Item "Bundled modules"
+.PD
+B::Concise, File::Temp, Pod::LaTeX, Pod::Text::Overstrike, CGI, CPAN,
+Class::Struct, DB_File, Devel::Peek, File::Find, Getopt::Long, IO::Poll,
+IPC::Open3, Math::BigFloat, Math::Complex, Net::Ping, Opcode, Pod::Parser,
+Pod::Text, SDBM_File, Sys::Syslog, Tie::RefHash, Tie::SubstrHash
+.IP "Platform-specific improvements" 4
+.IX Item "Platform-specific improvements"
+NCR MP-RAS, NonStop-UX
+.RE
+.RS 4
+.RE
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.PD 0
+.IP "Interpreter cloning, threads, and concurrency" 4
+.IX Item "Interpreter cloning, threads, and concurrency"
+.IP "Lexically scoped warning categories" 4
+.IX Item "Lexically scoped warning categories"
+.IP "Unicode and UTF\-8 support" 4
+.IX Item "Unicode and UTF-8 support"
+.IP "Support for interpolating named characters" 4
+.IX Item "Support for interpolating named characters"
+.IP """our"" declarations" 4
+.IX Item """our"" declarations"
+.IP "Support for strings represented as a vector of ordinals" 4
+.IX Item "Support for strings represented as a vector of ordinals"
+.IP "Improved Perl version numbering system" 4
+.IX Item "Improved Perl version numbering system"
+.IP "New syntax for declaring subroutine attributes" 4
+.IX Item "New syntax for declaring subroutine attributes"
+.IP "File and directory handles can be autovivified" 4
+.IX Item "File and directory handles can be autovivified"
+.IP "\fBopen()\fR with more than two arguments" 4
+.IX Item "open() with more than two arguments"
+.IP "64\-bit support" 4
+.IX Item "64-bit support"
+.IP "Large file support" 4
+.IX Item "Large file support"
+.IP "Long doubles" 4
+.IX Item "Long doubles"
+.IP """more bits""" 4
+.IX Item """more bits"""
+.IP "Enhanced support for \fBsort()\fR subroutines" 4
+.IX Item "Enhanced support for sort() subroutines"
+.ie n .IP """sort $coderef @foo"" allowed" 4
+.el .IP "\f(CWsort $coderef @foo\fR allowed" 4
+.IX Item "sort $coderef @foo allowed"
+.IP "File globbing implemented internally" 4
+.IX Item "File globbing implemented internally"
+.IP "Support for CHECK blocks" 4
+.IX Item "Support for CHECK blocks"
+.IP "POSIX character class syntax [: :] supported" 4
+.IX Item "POSIX character class syntax [: :] supported"
+.IP "Better pseudo-random number generator" 4
+.IX Item "Better pseudo-random number generator"
+.ie n .IP "Improved ""qw//"" operator" 4
+.el .IP "Improved \f(CWqw//\fR operator" 4
+.IX Item "Improved qw// operator"
+.IP "Better worst-case behavior of hashes" 4
+.IX Item "Better worst-case behavior of hashes"
+.IP "\fBpack()\fR format 'Z' supported" 4
+.IX Item "pack() format 'Z' supported"
+.IP "\fBpack()\fR format modifier '!' supported" 4
+.IX Item "pack() format modifier '!' supported"
+.IP "\fBpack()\fR and \fBunpack()\fR support counted strings" 4
+.IX Item "pack() and unpack() support counted strings"
+.IP "Comments in \fBpack()\fR templates" 4
+.IX Item "Comments in pack() templates"
+.IP "Weak references" 4
+.IX Item "Weak references"
+.IP "Binary numbers supported" 4
+.IX Item "Binary numbers supported"
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+.IP "Some arrows may be omitted in calls through references" 4
+.IX Item "Some arrows may be omitted in calls through references"
+.IP "Boolean assignment operators are legal lvalues" 4
+.IX Item "Boolean assignment operators are legal lvalues"
+.IP "\fBexists()\fR is supported on subroutine names" 4
+.IX Item "exists() is supported on subroutine names"
+.IP "\fBexists()\fR and \fBdelete()\fR are supported on array elements" 4
+.IX Item "exists() and delete() are supported on array elements"
+.IP "Pseudo-hashes work better" 4
+.IX Item "Pseudo-hashes work better"
+.IP "Automatic flushing of output buffers" 4
+.IX Item "Automatic flushing of output buffers"
+.IP "Better diagnostics on meaningless filehandle operations" 4
+.IX Item "Better diagnostics on meaningless filehandle operations"
+.IP "Where possible, buffered data discarded from duped input filehandle" 4
+.IX Item "Where possible, buffered data discarded from duped input filehandle"
+.IP "\fBeof()\fR has the same old magic as <>" 4
+.IX Item "eof() has the same old magic as <>"
+.IP "\fBbinmode()\fR can be used to set :crlf and :raw modes" 4
+.IX Item "binmode() can be used to set :crlf and :raw modes"
+.ie n .IP """\-T"" filetest recognizes UTF\-8 encoded files as ""text""" 4
+.el .IP "\f(CW\-T\fR filetest recognizes UTF\-8 encoded files as ""text""" 4
+.IX Item "-T filetest recognizes UTF-8 encoded files as ""text"""
+.IP "\fBsystem()\fR, backticks and pipe open now reflect \fBexec()\fR failure" 4
+.IX Item "system(), backticks and pipe open now reflect exec() failure"
+.IP "Improved diagnostics" 4
+.IX Item "Improved diagnostics"
+.IP "Diagnostics follow STDERR" 4
+.IX Item "Diagnostics follow STDERR"
+.IP "More consistent close-on-exec behavior" 4
+.IX Item "More consistent close-on-exec behavior"
+.IP "\fBsyswrite()\fR ease-of-use" 4
+.IX Item "syswrite() ease-of-use"
+.IP "Better syntax checks on parenthesized unary operators" 4
+.IX Item "Better syntax checks on parenthesized unary operators"
+.IP "Bit operators support full native integer width" 4
+.IX Item "Bit operators support full native integer width"
+.IP "Improved security features" 4
+.IX Item "Improved security features"
+.IP "More functional bareword prototype (*)" 4
+.IX Item "More functional bareword prototype (*)"
+.ie n .IP """require"" and ""do"" may be overridden" 4
+.el .IP "\f(CWrequire\fR and \f(CWdo\fR may be overridden" 4
+.IX Item "require and do may be overridden"
+.IP "$^X variables may now have names longer than one character" 4
+.IX Item "$^X variables may now have names longer than one character"
+.ie n .IP "New variable $^C reflects ""\-c"" switch" 4
+.el .IP "New variable $^C reflects \f(CW\-c\fR switch" 4
+.IX Item "New variable $^C reflects -c switch"
+.IP "New variable $^V contains Perl version as a string" 4
+.IX Item "New variable $^V contains Perl version as a string"
+.IP "Optional Y2K warnings" 4
+.IX Item "Optional Y2K warnings"
+.IP "Arrays now always interpolate into double-quoted strings" 4
+.IX Item "Arrays now always interpolate into double-quoted strings"
+.IP "@\- and @+ provide starting/ending offsets of regex submatches" 4
+.IX Item "@- and @+ provide starting/ending offsets of regex submatches"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP Modules 4
+.IX Item "Modules"
+.PD
+attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
+DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
+Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
+File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
+Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
+podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
+pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
+Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
+.IP Pragmata 4
+.IX Item "Pragmata"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP dprofpp 4
+.IX Item "dprofpp"
+.IP find2perl 4
+.IX Item "find2perl"
+.IP h2xs 4
+.IX Item "h2xs"
+.IP perlcc 4
+.IX Item "perlcc"
+.IP perldoc 4
+.IX Item "perldoc"
+.IP "The Perl Debugger" 4
+.IX Item "The Perl Debugger"
+.RE
+.RS 4
+.RE
+.IP "Improved Documentation" 4
+.IX Item "Improved Documentation"
+.PD
+perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
+perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
+perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
+perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
+.IP "Performance enhancements" 4
+.IX Item "Performance enhancements"
+.RS 4
+.PD 0
+.ie n .IP "Simple \fBsort()\fR using { $a <=> $b } and the like are optimized" 4
+.el .IP "Simple \fBsort()\fR using { \f(CW$a\fR <=> \f(CW$b\fR } and the like are optimized" 4
+.IX Item "Simple sort() using { $a <=> $b } and the like are optimized"
+.IP "Optimized assignments to lexical variables" 4
+.IX Item "Optimized assignments to lexical variables"
+.IP "Faster subroutine calls" 4
+.IX Item "Faster subroutine calls"
+.IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hash iteration are faster" 4
+.IX Item "delete(), each(), values() and hash iteration are faster"
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "\-Dusethreads means something different" 4
+.IX Item "-Dusethreads means something different"
+.IP "New Configure flags" 4
+.IX Item "New Configure flags"
+.IP "Threadedness and 64\-bitness now more daring" 4
+.IX Item "Threadedness and 64-bitness now more daring"
+.IP "Long Doubles" 4
+.IX Item "Long Doubles"
+.IP \-Dusemorebits 4
+.IX Item "-Dusemorebits"
+.IP \-Duselargefiles 4
+.IX Item "-Duselargefiles"
+.IP installusrbinperl 4
+.IX Item "installusrbinperl"
+.IP "SOCKS support" 4
+.IX Item "SOCKS support"
+.ie n .IP """\-A"" flag" 4
+.el .IP "\f(CW\-A\fR flag" 4
+.IX Item "-A flag"
+.IP "Enhanced Installation Directories" 4
+.IX Item "Enhanced Installation Directories"
+.IP "gcc automatically tried if 'cc' does not seem to be working" 4
+.IX Item "gcc automatically tried if 'cc' does not seem to be working"
+.RE
+.RS 4
+.RE
+.IP "Platform specific changes" 4
+.IX Item "Platform specific changes"
+.RS 4
+.IP "Supported platforms" 4
+.IX Item "Supported platforms"
+.IP DOS 4
+.IX Item "DOS"
+.IP "OS390 (OpenEdition MVS)" 4
+.IX Item "OS390 (OpenEdition MVS)"
+.IP VMS 4
+.IX Item "VMS"
+.IP Win32 4
+.IX Item "Win32"
+.RE
+.RS 4
+.RE
+.IP "Significant bug fixes" 4
+.IX Item "Significant bug fixes"
+.RS 4
+.IP "<HANDLE> on empty files" 4
+.IX Item "<HANDLE> on empty files"
+.ie n .IP """eval \*(Aq...\*(Aq"" improvements" 4
+.el .IP "\f(CWeval \*(Aq...\*(Aq\fR improvements" 4
+.IX Item "eval ... improvements"
+.IP "All compilation errors are true errors" 4
+.IX Item "All compilation errors are true errors"
+.IP "Implicitly closed filehandles are safer" 4
+.IX Item "Implicitly closed filehandles are safer"
+.IP "Behavior of list slices is more consistent" 4
+.IX Item "Behavior of list slices is more consistent"
+.ie n .IP """(\e$)"" prototype and $foo{a}" 4
+.el .IP "\f(CW(\e$)\fR prototype and \f(CW$foo{a}\fR" 4
+.IX Item "($) prototype and $foo{a}"
+.ie n .IP """goto &sub"" and AUTOLOAD" 4
+.el .IP "\f(CWgoto &sub\fR and AUTOLOAD" 4
+.IX Item "goto &sub and AUTOLOAD"
+.ie n .IP """\-bareword"" allowed under ""use integer""" 4
+.el .IP "\f(CW\-bareword\fR allowed under \f(CWuse integer\fR" 4
+.IX Item "-bareword allowed under use integer"
+.IP "Failures in \fBDESTROY()\fR" 4
+.IX Item "Failures in DESTROY()"
+.IP "Locale bugs fixed" 4
+.IX Item "Locale bugs fixed"
+.IP "Memory leaks" 4
+.IX Item "Memory leaks"
+.IP "Spurious subroutine stubs after failed subroutine calls" 4
+.IX Item "Spurious subroutine stubs after failed subroutine calls"
+.ie n .IP "Taint failures under ""\-U""" 4
+.el .IP "Taint failures under \f(CW\-U\fR" 4
+.IX Item "Taint failures under -U"
+.ie n .IP "END blocks and the ""\-c"" switch" 4
+.el .IP "END blocks and the \f(CW\-c\fR switch" 4
+.IX Item "END blocks and the -c switch"
+.IP "Potential to leak DATA filehandles" 4
+.IX Item "Potential to leak DATA filehandles"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.PD
+"%s" variable \f(CW%s\fR masks earlier declaration in same \f(CW%s\fR, "my sub" not yet
+implemented, "our" variable \f(CW%s\fR redeclared, '!' allowed only after types \f(CW%s\fR,
+/ cannot take a count, / must be followed by a, A or Z, / must be followed
+by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
+\&\e\e%c passed through, /%s/: Unrecognized escape \e\e%c in character class
+passed through, /%s/ should probably be written as "%s", %s() called too
+early to check prototype, \f(CW%s\fR argument is not a HASH or ARRAY element, \f(CW%s\fR
+argument is not a HASH or ARRAY element or slice, \f(CW%s\fR argument is not a
+subroutine name, \f(CW%s\fR package attribute may clash with future reserved word:
+\&\f(CW%s\fR, (in cleanup) \f(CW%s\fR, <> should be quotes, Attempt to join self, Bad evalled
+substitution pattern, Bad \fBrealloc()\fR ignored, Bareword found in conditional,
+Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
+size > 32 non-portable, Buffer overflow in prime_env_iter: \f(CW%s\fR, Can't check
+filesystem of script "%s", Can't declare class for non-scalar \f(CW%s\fR in "%s",
+Can't declare \f(CW%s\fR in "%s", Can't ignore signal CHLD, forcing to default,
+Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
+remove \f(CW%s:\fR \f(CW%s\fR, skipping file, Can't return \f(CW%s\fR from lvalue subroutine, Can't
+weaken a nonreference, Character class [:%s:] unknown, Character class
+syntax [%s] belongs inside character classes, Constant is not \f(CW%s\fR reference,
+constant(%s): \f(CW%s\fR, CORE::%s is not a keyword, defined(@array) is deprecated,
+defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
+"local" instead of "our"?), Document contains no data, entering effective
+\&\f(CW%s\fR failed, false [] range "%s" in regexp, Filehandle \f(CW%s\fR opened only for
+output, \fBflock()\fR on closed filehandle \f(CW%s\fR, Global symbol "%s" requires
+explicit package name, Hexadecimal number > 0xffffffff non-portable,
+Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
+|%s|, Illegal binary digit \f(CW%s\fR, Illegal binary digit \f(CW%s\fR ignored, Illegal
+number of bits in vec, Integer overflow in \f(CW%s\fR number, Invalid \f(CW%s\fR attribute:
+\&\f(CW%s\fR, Invalid \f(CW%s\fR attributes: \f(CW%s\fR, invalid [] range "%s" in regexp, Invalid
+separator character \f(CW%s\fR in attribute list, Invalid separator character \f(CW%s\fR in
+subroutine attribute list, leaving effective \f(CW%s\fR failed, Lvalue subs
+returning \f(CW%s\fR not implemented yet, Method \f(CW%s\fR not permitted, Missing
+\&\f(CW%sbrace\fR%s on \eN{}, Missing command in piped open, Missing name in "my sub",
+No \f(CW%s\fR specified for \-%c, No package name allowed for variable \f(CW%s\fR in "our",
+No space allowed after \-%c, no UTC offset information; assuming local time
+is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
+panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
+around "%s" list, Possible unintended interpolation of \f(CW%s\fR in string,
+Possible Y2K bug: \f(CW%s\fR, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
+instead, Premature end of script headers, Repeat count in pack overflows,
+Repeat count in unpack overflows, \fBrealloc()\fR of freed memory ignored,
+Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
+zero-length expression, switching effective \f(CW%s\fR is not implemented, This
+Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
+environ elements (%s=%s), Too late to run \f(CW%s\fR block, Unknown \fBopen()\fR mode
+\&'%s', Unknown process \f(CW%x\fR sent message to prime_env_iter: \f(CW%s\fR, Unrecognized
+escape \e\e%c passed through, Unterminated attribute parameter in attribute
+list, Unterminated attribute list, Unterminated attribute parameter in
+subroutine attribute list, Unterminated subroutine attribute list, Value of
+CLI symbol "%s" too long, Version number must be a constant number
+.IP "New tests" 4
+.IX Item "New tests"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Perl Source Incompatibilities" 4
+.IX Item "Perl Source Incompatibilities"
+.PD
+CHECK is a new keyword, Treatment of list slices of undef has changed,
+Format of \f(CW$English::PERL_VERSION\fR is different, Literals of the form
+\&\f(CW1.2.3\fR parse differently, Possibly changed pseudo-random number
+generator, Hashing function for hash keys has changed, \f(CW\*(C`undef\*(C'\fR fails on
+read only values, Close-on-exec bit may be set on pipe and socket handles,
+Writing \f(CW"$$1"\fR to mean \f(CW"${$}1"\fR is unsupported, \fBdelete()\fR, \fBeach()\fR,
+\&\fBvalues()\fR and \f(CW\*(C`\e(%h)\*(C'\fR, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
+Text of some diagnostic output has changed, \f(CW\*(C`%@\*(C'\fR has been removed,
+Parenthesized \fBnot()\fR behaves like a list operator, Semantics of bareword
+prototype \f(CW\*(C`(*)\*(C'\fR have changed, Semantics of bit operators may have changed
+on 64\-bit platforms, More builtins taint their results
+.IP "C Source Incompatibilities" 4
+.IX Item "C Source Incompatibilities"
+\&\f(CW\*(C`PERL_POLLUTE\*(C'\fR, \f(CW\*(C`PERL_IMPLICIT_CONTEXT\*(C'\fR, \f(CW\*(C`PERL_POLLUTE_MALLOC\*(C'\fR
+.IP "Compatible C Source API Changes" 4
+.IX Item "Compatible C Source API Changes"
+\&\f(CW\*(C`PATCHLEVEL\*(C'\fR is now \f(CW\*(C`PERL_VERSION\*(C'\fR
+.IP "Binary Incompatibilities" 4
+.IX Item "Binary Incompatibilities"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.RS 4
+.IP "Localizing a tied hash element may leak memory" 4
+.IX Item "Localizing a tied hash element may leak memory"
+.IP "Known test failures" 4
+.IX Item "Known test failures"
+.IP "EBCDIC platforms not fully supported" 4
+.IX Item "EBCDIC platforms not fully supported"
+.IP "UNICOS/mk CC failures during Configure run" 4
+.IX Item "UNICOS/mk CC failures during Configure run"
+.IP "Arrow operator and arrays" 4
+.IX Item "Arrow operator and arrays"
+.IP "Experimental features" 4
+.IX Item "Experimental features"
+.PD
+Threads, Unicode, 64\-bit support, Lvalue subroutines, Weak references, The
+pseudo-hash data type, The Compiler suite, Internal implementation of file
+globbing, The DB module, The regular expression code constructs:
+.RE
+.RS 4
+.RE
+.IP "Obsolete Diagnostics" 4
+.IX Item "Obsolete Diagnostics"
+Character class syntax [: :] is reserved for future extensions, Ill-formed
+logical name |%s| in prime_env_iter, In string, @%s now must be written as
+\&\e@%s, Probable precedence problem on \f(CW%s\fR, regexp too big, Use of "$$<digit>"
+to mean "${$}<digit>" is deprecated
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perl56delta \- what's new for perl v5.6.0"
+.IX Subsection "perl56delta - what's new for perl v5.6.0"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Core Enhancements" 4
+.IX Item "Core Enhancements"
+.RS 4
+.IP "Interpreter cloning, threads, and concurrency" 4
+.IX Item "Interpreter cloning, threads, and concurrency"
+.IP "Lexically scoped warning categories" 4
+.IX Item "Lexically scoped warning categories"
+.IP "Unicode and UTF\-8 support" 4
+.IX Item "Unicode and UTF-8 support"
+.IP "Support for interpolating named characters" 4
+.IX Item "Support for interpolating named characters"
+.IP """our"" declarations" 4
+.IX Item """our"" declarations"
+.IP "Support for strings represented as a vector of ordinals" 4
+.IX Item "Support for strings represented as a vector of ordinals"
+.IP "Improved Perl version numbering system" 4
+.IX Item "Improved Perl version numbering system"
+.IP "New syntax for declaring subroutine attributes" 4
+.IX Item "New syntax for declaring subroutine attributes"
+.IP "File and directory handles can be autovivified" 4
+.IX Item "File and directory handles can be autovivified"
+.IP "\fBopen()\fR with more than two arguments" 4
+.IX Item "open() with more than two arguments"
+.IP "64\-bit support" 4
+.IX Item "64-bit support"
+.IP "Large file support" 4
+.IX Item "Large file support"
+.IP "Long doubles" 4
+.IX Item "Long doubles"
+.IP """more bits""" 4
+.IX Item """more bits"""
+.IP "Enhanced support for \fBsort()\fR subroutines" 4
+.IX Item "Enhanced support for sort() subroutines"
+.ie n .IP """sort $coderef @foo"" allowed" 4
+.el .IP "\f(CWsort $coderef @foo\fR allowed" 4
+.IX Item "sort $coderef @foo allowed"
+.IP "File globbing implemented internally" 4
+.IX Item "File globbing implemented internally"
+.IP "Support for CHECK blocks" 4
+.IX Item "Support for CHECK blocks"
+.IP "POSIX character class syntax [: :] supported" 4
+.IX Item "POSIX character class syntax [: :] supported"
+.IP "Better pseudo-random number generator" 4
+.IX Item "Better pseudo-random number generator"
+.ie n .IP "Improved ""qw//"" operator" 4
+.el .IP "Improved \f(CWqw//\fR operator" 4
+.IX Item "Improved qw// operator"
+.IP "Better worst-case behavior of hashes" 4
+.IX Item "Better worst-case behavior of hashes"
+.IP "\fBpack()\fR format 'Z' supported" 4
+.IX Item "pack() format 'Z' supported"
+.IP "\fBpack()\fR format modifier '!' supported" 4
+.IX Item "pack() format modifier '!' supported"
+.IP "\fBpack()\fR and \fBunpack()\fR support counted strings" 4
+.IX Item "pack() and unpack() support counted strings"
+.IP "Comments in \fBpack()\fR templates" 4
+.IX Item "Comments in pack() templates"
+.IP "Weak references" 4
+.IX Item "Weak references"
+.IP "Binary numbers supported" 4
+.IX Item "Binary numbers supported"
+.IP "Lvalue subroutines" 4
+.IX Item "Lvalue subroutines"
+.IP "Some arrows may be omitted in calls through references" 4
+.IX Item "Some arrows may be omitted in calls through references"
+.IP "Boolean assignment operators are legal lvalues" 4
+.IX Item "Boolean assignment operators are legal lvalues"
+.IP "\fBexists()\fR is supported on subroutine names" 4
+.IX Item "exists() is supported on subroutine names"
+.IP "\fBexists()\fR and \fBdelete()\fR are supported on array elements" 4
+.IX Item "exists() and delete() are supported on array elements"
+.IP "Pseudo-hashes work better" 4
+.IX Item "Pseudo-hashes work better"
+.IP "Automatic flushing of output buffers" 4
+.IX Item "Automatic flushing of output buffers"
+.IP "Better diagnostics on meaningless filehandle operations" 4
+.IX Item "Better diagnostics on meaningless filehandle operations"
+.IP "Where possible, buffered data discarded from duped input filehandle" 4
+.IX Item "Where possible, buffered data discarded from duped input filehandle"
+.IP "\fBeof()\fR has the same old magic as <>" 4
+.IX Item "eof() has the same old magic as <>"
+.IP "\fBbinmode()\fR can be used to set :crlf and :raw modes" 4
+.IX Item "binmode() can be used to set :crlf and :raw modes"
+.ie n .IP """\-T"" filetest recognizes UTF\-8 encoded files as ""text""" 4
+.el .IP "\f(CW\-T\fR filetest recognizes UTF\-8 encoded files as ""text""" 4
+.IX Item "-T filetest recognizes UTF-8 encoded files as ""text"""
+.IP "\fBsystem()\fR, backticks and pipe open now reflect \fBexec()\fR failure" 4
+.IX Item "system(), backticks and pipe open now reflect exec() failure"
+.IP "Improved diagnostics" 4
+.IX Item "Improved diagnostics"
+.IP "Diagnostics follow STDERR" 4
+.IX Item "Diagnostics follow STDERR"
+.IP "More consistent close-on-exec behavior" 4
+.IX Item "More consistent close-on-exec behavior"
+.IP "\fBsyswrite()\fR ease-of-use" 4
+.IX Item "syswrite() ease-of-use"
+.IP "Better syntax checks on parenthesized unary operators" 4
+.IX Item "Better syntax checks on parenthesized unary operators"
+.IP "Bit operators support full native integer width" 4
+.IX Item "Bit operators support full native integer width"
+.IP "Improved security features" 4
+.IX Item "Improved security features"
+.IP "More functional bareword prototype (*)" 4
+.IX Item "More functional bareword prototype (*)"
+.ie n .IP """require"" and ""do"" may be overridden" 4
+.el .IP "\f(CWrequire\fR and \f(CWdo\fR may be overridden" 4
+.IX Item "require and do may be overridden"
+.IP "$^X variables may now have names longer than one character" 4
+.IX Item "$^X variables may now have names longer than one character"
+.ie n .IP "New variable $^C reflects ""\-c"" switch" 4
+.el .IP "New variable $^C reflects \f(CW\-c\fR switch" 4
+.IX Item "New variable $^C reflects -c switch"
+.IP "New variable $^V contains Perl version as a string" 4
+.IX Item "New variable $^V contains Perl version as a string"
+.IP "Optional Y2K warnings" 4
+.IX Item "Optional Y2K warnings"
+.IP "Arrays now always interpolate into double-quoted strings" 4
+.IX Item "Arrays now always interpolate into double-quoted strings"
+.IP "@\- and @+ provide starting/ending offsets of regex matches" 4
+.IX Item "@- and @+ provide starting/ending offsets of regex matches"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP Modules 4
+.IX Item "Modules"
+.PD
+attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
+DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
+Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
+File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
+Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
+podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
+pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
+Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
+.IP Pragmata 4
+.IX Item "Pragmata"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP dprofpp 4
+.IX Item "dprofpp"
+.IP find2perl 4
+.IX Item "find2perl"
+.IP h2xs 4
+.IX Item "h2xs"
+.IP perlcc 4
+.IX Item "perlcc"
+.IP perldoc 4
+.IX Item "perldoc"
+.IP "The Perl Debugger" 4
+.IX Item "The Perl Debugger"
+.RE
+.RS 4
+.RE
+.IP "Improved Documentation" 4
+.IX Item "Improved Documentation"
+.PD
+perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
+perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
+perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
+perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
+.IP "Performance enhancements" 4
+.IX Item "Performance enhancements"
+.RS 4
+.PD 0
+.ie n .IP "Simple \fBsort()\fR using { $a <=> $b } and the like are optimized" 4
+.el .IP "Simple \fBsort()\fR using { \f(CW$a\fR <=> \f(CW$b\fR } and the like are optimized" 4
+.IX Item "Simple sort() using { $a <=> $b } and the like are optimized"
+.IP "Optimized assignments to lexical variables" 4
+.IX Item "Optimized assignments to lexical variables"
+.IP "Faster subroutine calls" 4
+.IX Item "Faster subroutine calls"
+.IP "\fBdelete()\fR, \fBeach()\fR, \fBvalues()\fR and hash iteration are faster" 4
+.IX Item "delete(), each(), values() and hash iteration are faster"
+.RE
+.RS 4
+.RE
+.IP "Installation and Configuration Improvements" 4
+.IX Item "Installation and Configuration Improvements"
+.RS 4
+.IP "\-Dusethreads means something different" 4
+.IX Item "-Dusethreads means something different"
+.IP "New Configure flags" 4
+.IX Item "New Configure flags"
+.IP "Threadedness and 64\-bitness now more daring" 4
+.IX Item "Threadedness and 64-bitness now more daring"
+.IP "Long Doubles" 4
+.IX Item "Long Doubles"
+.IP \-Dusemorebits 4
+.IX Item "-Dusemorebits"
+.IP \-Duselargefiles 4
+.IX Item "-Duselargefiles"
+.IP installusrbinperl 4
+.IX Item "installusrbinperl"
+.IP "SOCKS support" 4
+.IX Item "SOCKS support"
+.ie n .IP """\-A"" flag" 4
+.el .IP "\f(CW\-A\fR flag" 4
+.IX Item "-A flag"
+.IP "Enhanced Installation Directories" 4
+.IX Item "Enhanced Installation Directories"
+.RE
+.RS 4
+.RE
+.IP "Platform specific changes" 4
+.IX Item "Platform specific changes"
+.RS 4
+.IP "Supported platforms" 4
+.IX Item "Supported platforms"
+.IP DOS 4
+.IX Item "DOS"
+.IP "OS390 (OpenEdition MVS)" 4
+.IX Item "OS390 (OpenEdition MVS)"
+.IP VMS 4
+.IX Item "VMS"
+.IP Win32 4
+.IX Item "Win32"
+.RE
+.RS 4
+.RE
+.IP "Significant bug fixes" 4
+.IX Item "Significant bug fixes"
+.RS 4
+.IP "<HANDLE> on empty files" 4
+.IX Item "<HANDLE> on empty files"
+.ie n .IP """eval \*(Aq...\*(Aq"" improvements" 4
+.el .IP "\f(CWeval \*(Aq...\*(Aq\fR improvements" 4
+.IX Item "eval ... improvements"
+.IP "All compilation errors are true errors" 4
+.IX Item "All compilation errors are true errors"
+.IP "Implicitly closed filehandles are safer" 4
+.IX Item "Implicitly closed filehandles are safer"
+.IP "Behavior of list slices is more consistent" 4
+.IX Item "Behavior of list slices is more consistent"
+.ie n .IP """(\e$)"" prototype and $foo{a}" 4
+.el .IP "\f(CW(\e$)\fR prototype and \f(CW$foo{a}\fR" 4
+.IX Item "($) prototype and $foo{a}"
+.ie n .IP """goto &sub"" and AUTOLOAD" 4
+.el .IP "\f(CWgoto &sub\fR and AUTOLOAD" 4
+.IX Item "goto &sub and AUTOLOAD"
+.ie n .IP """\-bareword"" allowed under ""use integer""" 4
+.el .IP "\f(CW\-bareword\fR allowed under \f(CWuse integer\fR" 4
+.IX Item "-bareword allowed under use integer"
+.IP "Failures in \fBDESTROY()\fR" 4
+.IX Item "Failures in DESTROY()"
+.IP "Locale bugs fixed" 4
+.IX Item "Locale bugs fixed"
+.IP "Memory leaks" 4
+.IX Item "Memory leaks"
+.IP "Spurious subroutine stubs after failed subroutine calls" 4
+.IX Item "Spurious subroutine stubs after failed subroutine calls"
+.ie n .IP "Taint failures under ""\-U""" 4
+.el .IP "Taint failures under \f(CW\-U\fR" 4
+.IX Item "Taint failures under -U"
+.ie n .IP "END blocks and the ""\-c"" switch" 4
+.el .IP "END blocks and the \f(CW\-c\fR switch" 4
+.IX Item "END blocks and the -c switch"
+.IP "Potential to leak DATA filehandles" 4
+.IX Item "Potential to leak DATA filehandles"
+.RE
+.RS 4
+.RE
+.IP "New or Changed Diagnostics" 4
+.IX Item "New or Changed Diagnostics"
+.PD
+"%s" variable \f(CW%s\fR masks earlier declaration in same \f(CW%s\fR, "my sub" not yet
+implemented, "our" variable \f(CW%s\fR redeclared, '!' allowed only after types \f(CW%s\fR,
+/ cannot take a count, / must be followed by a, A or Z, / must be followed
+by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
+\&\e\e%c passed through, /%s/: Unrecognized escape \e\e%c in character class
+passed through, /%s/ should probably be written as "%s", %s() called too
+early to check prototype, \f(CW%s\fR argument is not a HASH or ARRAY element, \f(CW%s\fR
+argument is not a HASH or ARRAY element or slice, \f(CW%s\fR argument is not a
+subroutine name, \f(CW%s\fR package attribute may clash with future reserved word:
+\&\f(CW%s\fR, (in cleanup) \f(CW%s\fR, <> should be quotes, Attempt to join self, Bad evalled
+substitution pattern, Bad \fBrealloc()\fR ignored, Bareword found in conditional,
+Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
+size > 32 non-portable, Buffer overflow in prime_env_iter: \f(CW%s\fR, Can't check
+filesystem of script "%s", Can't declare class for non-scalar \f(CW%s\fR in "%s",
+Can't declare \f(CW%s\fR in "%s", Can't ignore signal CHLD, forcing to default,
+Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
+remove \f(CW%s:\fR \f(CW%s\fR, skipping file, Can't return \f(CW%s\fR from lvalue subroutine, Can't
+weaken a nonreference, Character class [:%s:] unknown, Character class
+syntax [%s] belongs inside character classes, Constant is not \f(CW%s\fR reference,
+constant(%s): \f(CW%s\fR, CORE::%s is not a keyword, defined(@array) is deprecated,
+defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
+"local" instead of "our"?), Document contains no data, entering effective
+\&\f(CW%s\fR failed, false [] range "%s" in regexp, Filehandle \f(CW%s\fR opened only for
+output, \fBflock()\fR on closed filehandle \f(CW%s\fR, Global symbol "%s" requires
+explicit package name, Hexadecimal number > 0xffffffff non-portable,
+Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
+|%s|, Illegal binary digit \f(CW%s\fR, Illegal binary digit \f(CW%s\fR ignored, Illegal
+number of bits in vec, Integer overflow in \f(CW%s\fR number, Invalid \f(CW%s\fR attribute:
+\&\f(CW%s\fR, Invalid \f(CW%s\fR attributes: \f(CW%s\fR, invalid [] range "%s" in regexp, Invalid
+separator character \f(CW%s\fR in attribute list, Invalid separator character \f(CW%s\fR in
+subroutine attribute list, leaving effective \f(CW%s\fR failed, Lvalue subs
+returning \f(CW%s\fR not implemented yet, Method \f(CW%s\fR not permitted, Missing
+\&\f(CW%sbrace\fR%s on \eN{}, Missing command in piped open, Missing name in "my sub",
+No \f(CW%s\fR specified for \-%c, No package name allowed for variable \f(CW%s\fR in "our",
+No space allowed after \-%c, no UTC offset information; assuming local time
+is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
+panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
+around "%s" list, Possible unintended interpolation of \f(CW%s\fR in string,
+Possible Y2K bug: \f(CW%s\fR, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
+instead, Premature end of script headers, Repeat count in pack overflows,
+Repeat count in unpack overflows, \fBrealloc()\fR of freed memory ignored,
+Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
+zero-length expression, switching effective \f(CW%s\fR is not implemented, This
+Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
+environ elements (%s=%s), Too late to run \f(CW%s\fR block, Unknown \fBopen()\fR mode
+\&'%s', Unknown process \f(CW%x\fR sent message to prime_env_iter: \f(CW%s\fR, Unrecognized
+escape \e\e%c passed through, Unterminated attribute parameter in attribute
+list, Unterminated attribute list, Unterminated attribute parameter in
+subroutine attribute list, Unterminated subroutine attribute list, Value of
+CLI symbol "%s" too long, Version number must be a constant number
+.IP "New tests" 4
+.IX Item "New tests"
+.PD 0
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "Perl Source Incompatibilities" 4
+.IX Item "Perl Source Incompatibilities"
+.PD
+CHECK is a new keyword, Treatment of list slices of undef has changed,
+Format of \f(CW$English::PERL_VERSION\fR is different, Literals of the form
+\&\f(CW1.2.3\fR parse differently, Possibly changed pseudo-random number
+generator, Hashing function for hash keys has changed, \f(CW\*(C`undef\*(C'\fR fails on
+read only values, Close-on-exec bit may be set on pipe and socket handles,
+Writing \f(CW"$$1"\fR to mean \f(CW"${$}1"\fR is unsupported, \fBdelete()\fR, \fBeach()\fR,
+\&\fBvalues()\fR and \f(CW\*(C`\e(%h)\*(C'\fR, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
+Text of some diagnostic output has changed, \f(CW\*(C`%@\*(C'\fR has been removed,
+Parenthesized \fBnot()\fR behaves like a list operator, Semantics of bareword
+prototype \f(CW\*(C`(*)\*(C'\fR have changed, Semantics of bit operators may have changed
+on 64\-bit platforms, More builtins taint their results
+.IP "C Source Incompatibilities" 4
+.IX Item "C Source Incompatibilities"
+\&\f(CW\*(C`PERL_POLLUTE\*(C'\fR, \f(CW\*(C`PERL_IMPLICIT_CONTEXT\*(C'\fR, \f(CW\*(C`PERL_POLLUTE_MALLOC\*(C'\fR
+.IP "Compatible C Source API Changes" 4
+.IX Item "Compatible C Source API Changes"
+\&\f(CW\*(C`PATCHLEVEL\*(C'\fR is now \f(CW\*(C`PERL_VERSION\*(C'\fR
+.IP "Binary Incompatibilities" 4
+.IX Item "Binary Incompatibilities"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.RS 4
+.IP "Thread test failures" 4
+.IX Item "Thread test failures"
+.IP "EBCDIC platforms not supported" 4
+.IX Item "EBCDIC platforms not supported"
+.IP "In 64\-bit HP-UX the lib/io_multihomed test may hang" 4
+.IX Item "In 64-bit HP-UX the lib/io_multihomed test may hang"
+.IP "NEXTSTEP 3.3 POSIX test failure" 4
+.IX Item "NEXTSTEP 3.3 POSIX test failure"
+.IP "Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc" 4
+.IX Item "Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc"
+.IP "UNICOS/mk CC failures during Configure run" 4
+.IX Item "UNICOS/mk CC failures during Configure run"
+.IP "Arrow operator and arrays" 4
+.IX Item "Arrow operator and arrays"
+.IP "Experimental features" 4
+.IX Item "Experimental features"
+.PD
+Threads, Unicode, 64\-bit support, Lvalue subroutines, Weak references, The
+pseudo-hash data type, The Compiler suite, Internal implementation of file
+globbing, The DB module, The regular expression code constructs:
+.RE
+.RS 4
+.RE
+.IP "Obsolete Diagnostics" 4
+.IX Item "Obsolete Diagnostics"
+Character class syntax [: :] is reserved for future extensions, Ill-formed
+logical name |%s| in prime_env_iter, In string, @%s now must be written as
+\&\e@%s, Probable precedence problem on \f(CW%s\fR, regexp too big, Use of "$$<digit>"
+to mean "${$}<digit>" is deprecated
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perl5005delta \- what's new for perl5.005"
+.IX Subsection "perl5005delta - what's new for perl5.005"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "About the new versioning system" 4
+.IX Item "About the new versioning system"
+.IP "Incompatible Changes" 4
+.IX Item "Incompatible Changes"
+.RS 4
+.IP "WARNING:	This version is not binary compatible with Perl 5.004." 4
+.IX Item "WARNING: This version is not binary compatible with Perl 5.004."
+.IP "Default installation structure has changed" 4
+.IX Item "Default installation structure has changed"
+.IP "Perl Source Compatibility" 4
+.IX Item "Perl Source Compatibility"
+.IP "C Source Compatibility" 4
+.IX Item "C Source Compatibility"
+.IP "Binary Compatibility" 4
+.IX Item "Binary Compatibility"
+.IP "Security fixes may affect compatibility" 4
+.IX Item "Security fixes may affect compatibility"
+.IP "Relaxed new mandatory warnings introduced in 5.004" 4
+.IX Item "Relaxed new mandatory warnings introduced in 5.004"
+.IP Licensing 4
+.IX Item "Licensing"
+.RE
+.RS 4
+.RE
+.IP "Core Changes" 4
+.IX Item "Core Changes"
+.RS 4
+.IP Threads 4
+.IX Item "Threads"
+.IP Compiler 4
+.IX Item "Compiler"
+.IP "Regular Expressions" 4
+.IX Item "Regular Expressions"
+.PD
+Many new and improved optimizations, Many bug fixes, New regular expression
+constructs, New operator for precompiled regular expressions, Other
+improvements, Incompatible changes
+.IP "Improved \fBmalloc()\fR" 4
+.IX Item "Improved malloc()"
+.PD 0
+.IP "Quicksort is internally implemented" 4
+.IX Item "Quicksort is internally implemented"
+.IP "Reliable signals" 4
+.IX Item "Reliable signals"
+.IP "Reliable stack pointers" 4
+.IX Item "Reliable stack pointers"
+.IP "More generous treatment of carriage returns" 4
+.IX Item "More generous treatment of carriage returns"
+.IP "Memory leaks" 4
+.IX Item "Memory leaks"
+.IP "Better support for multiple interpreters" 4
+.IX Item "Better support for multiple interpreters"
+.IP "Behavior of \fBlocal()\fR on array and hash elements is now well-defined" 4
+.IX Item "Behavior of local() on array and hash elements is now well-defined"
+.ie n .IP """%!"" is transparently tied to the Errno module" 4
+.el .IP "\f(CW%!\fR is transparently tied to the Errno module" 4
+.IX Item "%! is transparently tied to the Errno module"
+.IP "Pseudo-hashes are supported" 4
+.IX Item "Pseudo-hashes are supported"
+.ie n .IP """EXPR foreach EXPR"" is supported" 4
+.el .IP "\f(CWEXPR foreach EXPR\fR is supported" 4
+.IX Item "EXPR foreach EXPR is supported"
+.IP "Keywords can be globally overridden" 4
+.IX Item "Keywords can be globally overridden"
+.ie n .IP "$^E is meaningful on Win32" 4
+.el .IP "\f(CW$^E\fR is meaningful on Win32" 4
+.IX Item "$^E is meaningful on Win32"
+.ie n .IP """foreach (1..1000000)"" optimized" 4
+.el .IP "\f(CWforeach (1..1000000)\fR optimized" 4
+.IX Item "foreach (1..1000000) optimized"
+.ie n .IP """Foo::"" can be used as implicitly quoted package name" 4
+.el .IP "\f(CWFoo::\fR can be used as implicitly quoted package name" 4
+.IX Item "Foo:: can be used as implicitly quoted package name"
+.ie n .IP """exists $Foo::{Bar::}"" tests existence of a package" 4
+.el .IP "\f(CWexists $Foo::{Bar::}\fR tests existence of a package" 4
+.IX Item "exists $Foo::{Bar::} tests existence of a package"
+.IP "Better locale support" 4
+.IX Item "Better locale support"
+.IP "Experimental support for 64\-bit platforms" 4
+.IX Item "Experimental support for 64-bit platforms"
+.IP "\fBprototype()\fR returns useful results on builtins" 4
+.IX Item "prototype() returns useful results on builtins"
+.IP "Extended support for exception handling" 4
+.IX Item "Extended support for exception handling"
+.IP "Re-blessing in \fBDESTROY()\fR supported for chaining \fBDESTROY()\fR methods" 4
+.IX Item "Re-blessing in DESTROY() supported for chaining DESTROY() methods"
+.ie n .IP "All ""printf"" format conversions are handled internally" 4
+.el .IP "All \f(CWprintf\fR format conversions are handled internally" 4
+.IX Item "All printf format conversions are handled internally"
+.ie n .IP "New ""INIT"" keyword" 4
+.el .IP "New \f(CWINIT\fR keyword" 4
+.IX Item "New INIT keyword"
+.ie n .IP "New ""lock"" keyword" 4
+.el .IP "New \f(CWlock\fR keyword" 4
+.IX Item "New lock keyword"
+.ie n .IP "New ""qr//"" operator" 4
+.el .IP "New \f(CWqr//\fR operator" 4
+.IX Item "New qr// operator"
+.ie n .IP """our"" is now a reserved word" 4
+.el .IP "\f(CWour\fR is now a reserved word" 4
+.IX Item "our is now a reserved word"
+.IP "Tied arrays are now fully supported" 4
+.IX Item "Tied arrays are now fully supported"
+.IP "Tied handles support is better" 4
+.IX Item "Tied handles support is better"
+.IP "4th argument to substr" 4
+.IX Item "4th argument to substr"
+.IP "Negative LENGTH argument to splice" 4
+.IX Item "Negative LENGTH argument to splice"
+.IP "Magic lvalues are now more magical" 4
+.IX Item "Magic lvalues are now more magical"
+.IP "<> now reads in records" 4
+.IX Item "<> now reads in records"
+.RE
+.RS 4
+.RE
+.IP "Supported Platforms" 4
+.IX Item "Supported Platforms"
+.RS 4
+.IP "New Platforms" 4
+.IX Item "New Platforms"
+.IP "Changes in existing support" 4
+.IX Item "Changes in existing support"
+.RE
+.RS 4
+.RE
+.IP "Modules and Pragmata" 4
+.IX Item "Modules and Pragmata"
+.RS 4
+.IP "New Modules" 4
+.IX Item "New Modules"
+.PD
+B, Data::Dumper, Dumpvalue, Errno, File::Spec, ExtUtils::Installed,
+ExtUtils::Packlist, Fatal, IPC::SysV, Test, Tie::Array, Tie::Handle,
+Thread, attrs, fields, re
+.IP "Changes in existing modules" 4
+.IX Item "Changes in existing modules"
+Benchmark, Carp, CGI, Fcntl, Math::Complex, Math::Trig, POSIX, DB_File,
+MakeMaker, CPAN, Cwd
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.PD 0
+.IP "Documentation Changes" 4
+.IX Item "Documentation Changes"
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+.PD
+Ambiguous call resolved as CORE::%s(), qualify as such or use &, Bad index
+while coercing array into hash, Bareword "%s" refers to nonexistent
+package, Can't call method "%s" on an undefined value, Can't check
+filesystem of script "%s" for nosuid, Can't coerce array into hash, Can't
+goto subroutine from an eval-string, Can't localize pseudo-hash element,
+Can't use %%! because Errno.pm is not available, Cannot find an opnumber
+for "%s", Character class syntax [. .] is reserved for future extensions,
+Character class syntax [: :] is reserved for future extensions, Character
+class syntax [= =] is reserved for future extensions, \f(CW%s:\fR Eval-group in
+insecure regular expression, \f(CW%s:\fR Eval-group not allowed, use re 'eval', \f(CW%s:\fR
+Eval-group not allowed at run time, Explicit blessing to '' (assuming
+package main), Illegal hex digit ignored, No such array field, No such
+field "%s" in variable \f(CW%s\fR of type \f(CW%s\fR, Out of memory during ridiculously
+large request, Range iterator outside integer range, Recursive inheritance
+detected while looking for method '%s' \f(CW%s\fR, Reference found where even-sized
+list expected, Undefined value assigned to typeglob, Use of reserved word
+"%s" is deprecated, perl: warning: Setting locale failed
+.IP "Obsolete Diagnostics" 4
+.IX Item "Obsolete Diagnostics"
+Can't \fBmktemp()\fR, Can't write to temp file for \fB\-e\fR: \f(CW%s\fR, Cannot open
+temporary file, regexp too big
+.IP "Configuration Changes" 4
+.IX Item "Configuration Changes"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perl5004delta \- what's new for perl5.004"
+.IX Subsection "perl5004delta - what's new for perl5.004"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "Supported Environments" 4
+.IX Item "Supported Environments"
+.IP "Core Changes" 4
+.IX Item "Core Changes"
+.RS 4
+.ie n .IP "List assignment to %ENV works" 4
+.el .IP "List assignment to \f(CW%ENV\fR works" 4
+.IX Item "List assignment to %ENV works"
+.ie n .IP "Change to ""Can't locate Foo.pm in @INC"" error" 4
+.el .IP "Change to ""Can't locate Foo.pm in \f(CW@INC\fR"" error" 4
+.IX Item "Change to ""Can't locate Foo.pm in @INC"" error"
+.IP "Compilation option: Binary compatibility with 5.003" 4
+.IX Item "Compilation option: Binary compatibility with 5.003"
+.ie n .IP "$PERL5OPT environment variable" 4
+.el .IP "\f(CW$PERL5OPT\fR environment variable" 4
+.IX Item "$PERL5OPT environment variable"
+.IP "Limitations on \fB\-M\fR, \fB\-m\fR, and \fB\-T\fR options" 4
+.IX Item "Limitations on -M, -m, and -T options"
+.IP "More precise warnings" 4
+.IX Item "More precise warnings"
+.ie n .IP "Deprecated: Inherited ""AUTOLOAD"" for non-methods" 4
+.el .IP "Deprecated: Inherited \f(CWAUTOLOAD\fR for non-methods" 4
+.IX Item "Deprecated: Inherited AUTOLOAD for non-methods"
+.ie n .IP "Previously deprecated %OVERLOAD is no longer usable" 4
+.el .IP "Previously deprecated \f(CW%OVERLOAD\fR is no longer usable" 4
+.IX Item "Previously deprecated %OVERLOAD is no longer usable"
+.IP "Subroutine arguments created only when they're modified" 4
+.IX Item "Subroutine arguments created only when they're modified"
+.ie n .IP "Group vector changeable with $)" 4
+.el .IP "Group vector changeable with \f(CW$)\fR" 4
+.IX Item "Group vector changeable with $)"
+.IP "Fixed parsing of $$<digit>, &$<digit>, etc." 4
+.IX Item "Fixed parsing of $$<digit>, &$<digit>, etc."
+.IP "Fixed localization of $<digit>, $&, etc." 4
+.IX Item "Fixed localization of $<digit>, $&, etc."
+.IP "No resetting of $. on implicit close" 4
+.IX Item "No resetting of $. on implicit close"
+.ie n .IP """wantarray"" may return undef" 4
+.el .IP "\f(CWwantarray\fR may return undef" 4
+.IX Item "wantarray may return undef"
+.ie n .IP """eval EXPR"" determines value of EXPR in scalar context" 4
+.el .IP "\f(CWeval EXPR\fR determines value of EXPR in scalar context" 4
+.IX Item "eval EXPR determines value of EXPR in scalar context"
+.IP "Changes to tainting checks" 4
+.IX Item "Changes to tainting checks"
+.PD
+No \fBglob()\fR or <*>, No spawning if tainted \f(CW$CDPATH\fR, \f(CW$ENV\fR, \f(CW$BASH_ENV\fR, No
+spawning if tainted \f(CW$TERM\fR doesn't look like a terminal name
+.IP "New Opcode module and revised Safe module" 4
+.IX Item "New Opcode module and revised Safe module"
+.PD 0
+.IP "Embedding improvements" 4
+.IX Item "Embedding improvements"
+.IP "Internal change: FileHandle class based on IO::* classes" 4
+.IX Item "Internal change: FileHandle class based on IO::* classes"
+.IP "Internal change: PerlIO abstraction interface" 4
+.IX Item "Internal change: PerlIO abstraction interface"
+.IP "New and changed syntax" 4
+.IX Item "New and changed syntax"
+.PD
+\&\f(CW$coderef\fR\->(PARAMS)
+.IP "New and changed builtin constants" 4
+.IX Item "New and changed builtin constants"
+_\|_PACKAGE_\|_
+.IP "New and changed builtin variables" 4
+.IX Item "New and changed builtin variables"
+$^E, $^H, $^M
+.IP "New and changed builtin functions" 4
+.IX Item "New and changed builtin functions"
+delete on slices, flock, printf and sprintf, keys as an lvalue, \fBmy()\fR in
+Control Structures, \fBpack()\fR and \fBunpack()\fR, \fBsysseek()\fR, use VERSION, use Module
+VERSION LIST, prototype(FUNCTION), srand, \f(CW$_\fR as Default, \f(CW\*(C`m//gc\*(C'\fR does not
+reset search position on failure, \f(CW\*(C`m//x\*(C'\fR ignores whitespace before ?*+{},
+nested \f(CW\*(C`sub{}\*(C'\fR closures work now, formats work right on changing lexicals
+.IP "New builtin methods" 4
+.IX Item "New builtin methods"
+isa(CLASS), can(METHOD), VERSION( [NEED] )
+.IP "TIEHANDLE now supported" 4
+.IX Item "TIEHANDLE now supported"
+TIEHANDLE classname, LIST, PRINT this, LIST, PRINTF this, LIST, READ this
+LIST, READLINE this, GETC this, DESTROY this
+.IP "Malloc enhancements" 4
+.IX Item "Malloc enhancements"
+\&\-DPERL_EMERGENCY_SBRK, \-DPACK_MALLOC, \-DTWO_POT_OPTIMIZE
+.IP "Miscellaneous efficiency enhancements" 4
+.IX Item "Miscellaneous efficiency enhancements"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Support for More Operating Systems" 4
+.IX Item "Support for More Operating Systems"
+.RS 4
+.IP Win32 4
+.IX Item "Win32"
+.IP "Plan 9" 4
+.IX Item "Plan 9"
+.IP QNX 4
+.IX Item "QNX"
+.IP AmigaOS 4
+.IX Item "AmigaOS"
+.RE
+.RS 4
+.RE
+.IP Pragmata 4
+.IX Item "Pragmata"
+.PD
+use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use
+constant NAME => VALUE, use locale, use ops, use vmsish
+.IP Modules 4
+.IX Item "Modules"
+.RS 4
+.PD 0
+.IP "Required Updates" 4
+.IX Item "Required Updates"
+.IP "Installation directories" 4
+.IX Item "Installation directories"
+.IP "Module information summary" 4
+.IX Item "Module information summary"
+.IP Fcntl 4
+.IX Item "Fcntl"
+.IP IO 4
+.IX Item "IO"
+.IP Math::Complex 4
+.IX Item "Math::Complex"
+.IP Math::Trig 4
+.IX Item "Math::Trig"
+.IP DB_File 4
+.IX Item "DB_File"
+.IP Net::Ping 4
+.IX Item "Net::Ping"
+.IP "Object-oriented overrides for builtin operators" 4
+.IX Item "Object-oriented overrides for builtin operators"
+.RE
+.RS 4
+.RE
+.IP "Utility Changes" 4
+.IX Item "Utility Changes"
+.RS 4
+.IP pod2html 4
+.IX Item "pod2html"
+.PD
+Sends converted HTML to standard output
+.IP xsubpp 4
+.IX Item "xsubpp"
+\&\f(CW\*(C`void\*(C'\fR XSUBs now default to returning nothing
+.RE
+.RS 4
+.RE
+.IP "C Language API Changes" 4
+.IX Item "C Language API Changes"
+\&\f(CW\*(C`gv_fetchmethod\*(C'\fR and \f(CW\*(C`perl_call_sv\*(C'\fR, \f(CW\*(C`perl_eval_pv\*(C'\fR, Extended API for
+manipulating hashes
+.IP "Documentation Changes" 4
+.IX Item "Documentation Changes"
+perldelta, perlfaq, perllocale, perltoot, perlapio,
+perlmodlib, perldebug, perlsec
+.IP "New Diagnostics" 4
+.IX Item "New Diagnostics"
+"my" variable \f(CW%s\fR masks earlier declaration in same scope, \f(CW%s\fR argument is
+not a HASH element or slice, Allocation too large: \f(CW%lx\fR, Allocation too
+large, Applying \f(CW%s\fR to \f(CW%s\fR will act on scalar(%s), Attempt to free
+nonexistent shared string, Attempt to use reference as lvalue in substr,
+Bareword "%s" refers to nonexistent package, Can't redefine active sort
+subroutine \f(CW%s\fR, Can't use bareword ("%s") as \f(CW%s\fR ref while "strict refs" in
+use, Cannot resolve method `%s' overloading `%s' in package `%s', Constant
+subroutine \f(CW%s\fR redefined, Constant subroutine \f(CW%s\fR undefined, Copy method did
+not return a reference, Died, Exiting pseudo-block via \f(CW%s\fR, Identifier too
+long, Illegal character \f(CW%s\fR (carriage return), Illegal switch in PERL5OPT:
+\&\f(CW%s\fR, Integer overflow in hex number, Integer overflow in octal number,
+internal error: glob failed, Invalid conversion in \f(CW%s:\fR "%s", Invalid type
+in pack: '%s', Invalid type in unpack: '%s', Name "%s::%s" used only once:
+possible typo, Null picture in formline, Offset outside string, Out of
+memory!, Out of memory during request for \f(CW%s\fR, panic: frexp, Possible
+attempt to put comments in \fBqw()\fR list, Possible attempt to separate words
+with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found
+while resolving method `%s' overloading `%s' in \f(CW%s\fR, Too late for "\fB\-T\fR"
+option, untie attempted while \f(CW%d\fR inner references still exist, Unrecognized
+character \f(CW%s\fR, Unsupported function fork, Use of "$$<digit>" to mean
+"${$}<digit>" is deprecated, Value of \f(CW%s\fR can be "0"; test with \fBdefined()\fR,
+Variable "%s" may be unavailable, Variable "%s" will not stay shared,
+Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter,
+Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too
+long, Process terminated by SIG%s
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perlbook \- Books about and related to Perl"
+.IX Subsection "perlbook - Books about and related to Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The most popular books" 4
+.IX Item "The most popular books"
+.PD
+\&\fIProgramming Perl\fR (the "Camel Book"):, \fIThe Perl Cookbook\fR (the "Ram
+Book"):, \fILearning Perl\fR  (the "Llama Book"), \fIIntermediate Perl\fR (the
+"Alpaca Book")
+.IP References 4
+.IX Item "References"
+\&\fIPerl 5 Pocket Reference\fR, \fIPerl Debugger Pocket Reference\fR, \fIRegular
+Expression Pocket Reference\fR
+.IP Tutorials 4
+.IX Item "Tutorials"
+\&\fIBeginning Perl\fR, \fILearning Perl\fR (the "Llama Book"), \fIIntermediate
+Perl\fR (the "Alpaca Book"), \fIMastering Perl\fR, \fIEffective Perl Programming\fR
+.IP Task-Oriented 4
+.IX Item "Task-Oriented"
+\&\fIWriting Perl Modules for CPAN\fR, \fIThe Perl Cookbook\fR, \fIAutomating System
+Administration with Perl\fR, \fIReal World SQL Server Administration with
+Perl\fR
+.IP "Special Topics" 4
+.IX Item "Special Topics"
+\&\fIRegular Expressions Cookbook\fR, \fIProgramming the Perl DBI\fR, \fIPerl Best
+Practices\fR, \fIHigher-Order Perl\fR, \fIMastering Regular Expressions\fR,
+\&\fINetwork Programming with Perl\fR, \fIPerl Template Toolkit\fR, \fIObject
+Oriented Perl\fR, \fIData Munging with Perl\fR, \fIMastering Perl/Tk\fR,
+\&\fIExtending and Embedding Perl\fR, \fIPro Perl Debugging\fR
+.IP "Free (as in beer) books" 4
+.IX Item "Free (as in beer) books"
+.PD 0
+.IP "Other interesting, non-Perl books" 4
+.IX Item "Other interesting, non-Perl books"
+.PD
+\&\fIProgramming Pearls\fR, \fIMore Programming Pearls\fR
+.IP "A note on freshness" 4
+.IX Item "A note on freshness"
+.PD 0
+.IP "Get your book listed" 4
+.IX Item "Get your book listed"
+.RE
+.RS 4
+.RE
+.PD
+.SS "perlcommunity \- a brief overview of the Perl community"
+.IX Subsection "perlcommunity - a brief overview of the Perl community"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Where to Find the Community" 4
+.IX Item "Where to Find the Community"
+.IP "Mailing Lists and Newsgroups" 4
+.IX Item "Mailing Lists and Newsgroups"
+.IP IRC 4
+.IX Item "IRC"
+.IP Websites 4
+.IX Item "Websites"
+.PD
+<https://perl.com/>, <http://blogs.perl.org/>,
+<https://perl.theplanetarium.org/>, <https://perlweekly.com/>,
+<https://www.perlmonks.org/>, <https://stackoverflow.com/>
+.IP "User Groups" 4
+.IX Item "User Groups"
+.PD 0
+.IP Workshops 4
+.IX Item "Workshops"
+.IP Hackathons 4
+.IX Item "Hackathons"
+.IP Conventions 4
+.IX Item "Conventions"
+.PD
+The Perl Conference, OSCON
+.IP "Calendar of Perl Events" 4
+.IX Item "Calendar of Perl Events"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perldoc \- Look up Perl documentation in Pod format."
+.IX Subsection "perldoc - Look up Perl documentation in Pod format."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.PD
+\&\fB\-h\fR, \fB\-D\fR, \fB\-t\fR, \fB\-u\fR, \fB\-m\fR \fImodule\fR, \fB\-l\fR, \fB\-U\fR, \fB\-F\fR, \fB\-f\fR
+\&\fIperlfunc\fR, \fB\-q\fR \fIperlfaq-search-regexp\fR, \fB\-a\fR \fIperlapifunc\fR, \fB\-v\fR
+\&\fIperlvar\fR, \fB\-T\fR, \fB\-d\fR \fIdestination-filename\fR, \fB\-o\fR
+\&\fIoutput-formatname\fR, \fB\-M\fR \fImodule-name\fR, \fB\-w\fR \fIoption:value\fR or \fB\-w\fR
+\&\fIoption\fR, \fB\-X\fR, \fB\-L\fR \fIlanguage_code\fR,
+\&\fBPageName|ModuleName|ProgramName|URL\fR, \fB\-n\fR \fIsome-formatter\fR, \fB\-r\fR,
+\&\fB\-i\fR, \fB\-V\fR
+.IP SECURITY 4
+.IX Item "SECURITY"
+.PD 0
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.IP CHANGES 4
+.IX Item "CHANGES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlexperiment \- A listing of experimental features in Perl"
+.IX Subsection "perlexperiment - A listing of experimental features in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Current experiments" 4
+.IX Item "Current experiments"
+.PD
+Smart match (\f(CW\*(C`~~\*(C'\fR), Pluggable keywords, Aliasing via reference, The
+"const" attribute, use re 'strict';, Declaring a reference to a variable,
+There is an \f(CW\*(C`installhtml\*(C'\fR target in the Makefile, (Limited)
+Variable-length look-behind, Unicode private use character hooks, Unicode
+property wildcards, try/catch control structure, Use of \f(CW@_\fR within
+subroutine signatures, for loop with multiple iteration variables, The
+builtin namespace, The defer block modifier, Extra paired delimiters for
+quote-like operators
+.IP "Accepted features" 4
+.IX Item "Accepted features"
+64\-bit support, die accepts a reference, DB module, Weak references,
+Internal file glob, \fBfork()\fR emulation, \-Dusemultiplicity \-Duseithreads,
+Support for long doubles, The \f(CW\*(C`\eN\*(C'\fR regex character class, \f(CW\*(C`(?{code})\*(C'\fR and
+\&\f(CW\*(C`(??{ code })\*(C'\fR, Linux abstract Unix domain sockets, Lvalue subroutines,
+Backtracking control verbs, The \f(CW\*(C`:pop\*(C'\fR IO pseudolayer, \f(CW\*(C`\es\*(C'\fR in regexp
+matches vertical tab, Postfix dereference syntax, Lexical subroutines,
+String\- and number-specific bitwise operators, Alphabetic assertions,
+Script runs, The infix \f(CW\*(C`isa\*(C'\fR operator, Subroutine signatures, Regular
+Expression Set Operations
+.IP "Removed features" 4
+.IX Item "Removed features"
+5.005\-style threading, perlcc, The pseudo-hash data type, GetOpt::Long
+Options can now take multiple values at once (experimental), Assertions,
+Test::Harness::Straps, \f(CW\*(C`legacy\*(C'\fR, Lexical \f(CW$_\fR, Array and hash container
+functions accept references, \f(CW\*(C`our\*(C'\fR can have an experimental optional
+attribute \f(CW\*(C`unique\*(C'\fR, The \f(CW\*(C`:win32\*(C'\fR IO pseudolayer
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "perlartistic \- the Perl Artistic License"
+.IX Subsection "perlartistic - the Perl Artistic License"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "The ""Artistic License""" 4
+.IX Item "The ""Artistic License"""
+.RS 4
+.IP Preamble 4
+.IX Item "Preamble"
+.IP Definitions 4
+.IX Item "Definitions"
+.PD
+"Package", "Standard Version", "Copyright Holder", "You", "Reasonable
+copying fee", "Freely Available"
+.IP Conditions 4
+.IX Item "Conditions"
+a), b), c), d), a), b), c), d)
+.RE
+.RS 4
+.RE
+.SS "perlgpl \- the GNU General Public License, version 1"
+.IX Subsection "perlgpl - the GNU General Public License, version 1"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "GNU GENERAL PUBLIC LICENSE" 4
+.IX Item "GNU GENERAL PUBLIC LICENSE"
+.PD
+.SS "perlaix \- Perl version 5 on IBM AIX (UNIX) systems"
+.IX Subsection "perlaix - Perl version 5 on IBM AIX (UNIX) systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Compiling Perl 5 on AIX" 4
+.IX Item "Compiling Perl 5 on AIX"
+.IP "Supported Compilers" 4
+.IX Item "Supported Compilers"
+.IP "Incompatibility with AIX Toolbox lib gdbm" 4
+.IX Item "Incompatibility with AIX Toolbox lib gdbm"
+.IP "Perl 5 was successfully compiled and tested on:" 4
+.IX Item "Perl 5 was successfully compiled and tested on:"
+.IP "Building Dynamic Extensions on AIX" 4
+.IX Item "Building Dynamic Extensions on AIX"
+.IP "Using Large Files with Perl" 4
+.IX Item "Using Large Files with Perl"
+.IP "Threaded Perl" 4
+.IX Item "Threaded Perl"
+.IP "64\-bit Perl" 4
+.IX Item "64-bit Perl"
+.IP "Long doubles" 4
+.IX Item "Long doubles"
+.IP "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32\-bit)" 4
+.IX Item "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)"
+.IP "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32\-bit)" 4
+.IX Item "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)"
+.IP "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64\-bit)" 4
+.IX Item "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)"
+.IP "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64\-bit)" 4
+.IX Item "Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)"
+.IP "Compiling Perl 5 on AIX 7.1.0" 4
+.IX Item "Compiling Perl 5 on AIX 7.1.0"
+.IP "Compiling Perl 5 on older AIX versions up to 4.3.3" 4
+.IX Item "Compiling Perl 5 on older AIX versions up to 4.3.3"
+.IP "OS level" 4
+.IX Item "OS level"
+.IP "Building Dynamic Extensions on AIX < 5L" 4
+.IX Item "Building Dynamic Extensions on AIX < 5L"
+.IP "The IBM ANSI C Compiler" 4
+.IX Item "The IBM ANSI C Compiler"
+.IP "The usenm option" 4
+.IX Item "The usenm option"
+.IP "Using GNU's gcc for building Perl" 4
+.IX Item "Using GNU's gcc for building Perl"
+.IP "Using Large Files with Perl < 5L" 4
+.IX Item "Using Large Files with Perl < 5L"
+.IP "Threaded Perl < 5L" 4
+.IX Item "Threaded Perl < 5L"
+.IP "64\-bit Perl < 5L" 4
+.IX Item "64-bit Perl < 5L"
+.IP "AIX 4.2 and extensions using C++ with statics" 4
+.IX Item "AIX 4.2 and extensions using C++ with statics"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "perlamiga \- Perl under AmigaOS 4.1"
+.IX Subsection "perlamiga - Perl under AmigaOS 4.1"
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1" 4
+.IX Item "Prerequisites for running Perl 5.22.1 under AmigaOS 4.1"
+.PD
+\&\fBAmigaOS 4.1 update 6 with all updates applied as of 9th October 2013\fR,
+\&\fBnewlib.library version 53.28 or greater\fR, \fBAmigaOS SDK\fR, \fBabc-shell\fR
+.IP "Starting Perl programs under AmigaOS 4.1" 4
+.IX Item "Starting Perl programs under AmigaOS 4.1"
+.PD 0
+.IP "Limitations of Perl under AmigaOS 4.1" 4
+.IX Item "Limitations of Perl under AmigaOS 4.1"
+.PD
+\&\fBNested Piped programs can crash when run from older abc-shells\fR,
+\&\fBIncorrect or unexpected command line unescaping\fR, \fBStarting subprocesses
+via open has limitations\fR, If you find any other limitations or bugs then
+let me know
+.RE
+.RS 4
+.RE
+.IP INSTALLATION 4
+.IX Item "INSTALLATION"
+.PD 0
+.IP "Amiga Specific Modules" 4
+.IX Item "Amiga Specific Modules"
+.RS 4
+.IP Amiga::ARexx 4
+.IX Item "Amiga::ARexx"
+.IP Amiga::Exec 4
+.IX Item "Amiga::Exec"
+.RE
+.RS 4
+.RE
+.IP BUILDING 4
+.IX Item "BUILDING"
+.IP CHANGES 4
+.IX Item "CHANGES"
+.PD
+\&\fBAugust 2015\fR, Port to Perl 5.22, Add handling of NIL: to \fBafstat()\fR, Fix
+inheritance of environment variables by subprocesses, Fix exec, and exit in
+"forked" subprocesses, Fix issue with newlib's unlink, which could cause
+infinite loops, Add \fBflock()\fR emulation using IDOS\->LockRecord thanks to Tony
+Cook for the suggestion, Fix issue where kill was using the wrong kind of
+process ID, \fB27th November 2013\fR, Create new installation system based on
+installperl links and Amiga protection bits now set correctly, Pod now
+defaults to text, File::Spec should now recognise an Amiga style absolute
+path as well as an Unix style one. Relative paths must always be Unix
+style, \fB20th November 2013\fR, Configured to use SDK:Local/C/perl to start
+standard scripts, Added Amiga::Exec module with support for \fBWait()\fR and
+AmigaOS signal numbers, \fB10th October 13\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "perlandroid \- Perl under Android"
+.IX Subsection "perlandroid - Perl under Android"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Cross-compilation 4
+.IX Item "Cross-compilation"
+.RS 4
+.IP "Get the Android Native Development Kit (NDK)" 4
+.IX Item "Get the Android Native Development Kit (NDK)"
+.IP "Determine the architecture you'll be cross-compiling for" 4
+.IX Item "Determine the architecture you'll be cross-compiling for"
+.IP "Set up a standalone toolchain" 4
+.IX Item "Set up a standalone toolchain"
+.IP "adb or ssh?" 4
+.IX Item "adb or ssh?"
+.IP "Configure and beyond" 4
+.IX Item "Configure and beyond"
+.RE
+.RS 4
+.RE
+.IP "Native Builds" 4
+.IX Item "Native Builds"
+.RS 4
+.IP CCTools 4
+.IX Item "CCTools"
+.IP Termux 4
+.IX Item "Termux"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlbs2000 \- building and installing Perl for BS2000."
+.IX Subsection "perlbs2000 - building and installing Perl for BS2000."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "gzip on BS2000" 4
+.IX Item "gzip on BS2000"
+.IP "bison on BS2000" 4
+.IX Item "bison on BS2000"
+.IP "Unpacking Perl Distribution on BS2000" 4
+.IX Item "Unpacking Perl Distribution on BS2000"
+.IP "Compiling Perl on BS2000" 4
+.IX Item "Compiling Perl on BS2000"
+.IP "Testing Perl on BS2000" 4
+.IX Item "Testing Perl on BS2000"
+.IP "Installing Perl on BS2000" 4
+.IX Item "Installing Perl on BS2000"
+.IP "Using Perl in the Posix-Shell of BS2000" 4
+.IX Item "Using Perl in the Posix-Shell of BS2000"
+.IP "Using Perl in ""native"" BS2000" 4
+.IX Item "Using Perl in ""native"" BS2000"
+.IP "Floating point anomalies on BS2000" 4
+.IX Item "Floating point anomalies on BS2000"
+.IP "Using PerlIO and different encodings on ASCII and EBCDIC partitions" 4
+.IX Item "Using PerlIO and different encodings on ASCII and EBCDIC partitions"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP "Mailing list" 4
+.IX Item "Mailing list"
+.RE
+.RS 4
+.RE
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perlcygwin \- Perl for Cygwin"
+.IX Subsection "perlcygwin - Perl for Cygwin"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "PREREQUISITES FOR COMPILING PERL ON CYGWIN" 4
+.IX Item "PREREQUISITES FOR COMPILING PERL ON CYGWIN"
+.RS 4
+.IP "Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)" 4
+.IX Item "Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)"
+.IP "Cygwin Configuration" 4
+.IX Item "Cygwin Configuration"
+.PD
+\&\f(CW\*(C`PATH\*(C'\fR, \fInroff\fR
+.RE
+.RS 4
+.RE
+.IP "CONFIGURE PERL ON CYGWIN" 4
+.IX Item "CONFIGURE PERL ON CYGWIN"
+.RS 4
+.PD 0
+.IP "Stripping Perl Binaries on Cygwin" 4
+.IX Item "Stripping Perl Binaries on Cygwin"
+.IP "Optional Libraries for Perl on Cygwin" 4
+.IX Item "Optional Libraries for Perl on Cygwin"
+.PD
+\&\f(CW\*(C`\-lcrypt\*(C'\fR, \f(CW\*(C`\-lgdbm_compat\*(C'\fR (\f(CW\*(C`use GDBM_File\*(C'\fR), \f(CW\*(C`\-ldb\*(C'\fR (\f(CW\*(C`use DB_File\*(C'\fR),
+\&\f(CW\*(C`cygserver\*(C'\fR (\f(CW\*(C`use IPC::SysV\*(C'\fR), \f(CW\*(C`\-lutil\*(C'\fR
+.IP "Configure-time Options for Perl on Cygwin" 4
+.IX Item "Configure-time Options for Perl on Cygwin"
+\&\f(CW\*(C`\-Uusedl\*(C'\fR, \f(CW\*(C`\-Dusemymalloc\*(C'\fR, \f(CW\*(C`\-Uuseperlio\*(C'\fR, \f(CW\*(C`\-Dusemultiplicity\*(C'\fR,
+\&\f(CW\*(C`\-Uuse64bitint\*(C'\fR, \f(CW\*(C`\-Duselongdouble\*(C'\fR, \f(CW\*(C`\-Uuseithreads\*(C'\fR, \f(CW\*(C`\-Duselargefiles\*(C'\fR,
+\&\f(CW\*(C`\-Dmksymlinks\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "MAKE ON CYGWIN" 4
+.IX Item "MAKE ON CYGWIN"
+.PD 0
+.IP "TEST ON CYGWIN" 4
+.IX Item "TEST ON CYGWIN"
+.RS 4
+.IP "File Permissions on Cygwin" 4
+.IX Item "File Permissions on Cygwin"
+.IP "NDBM_File and ODBM_File do not work on FAT filesystems" 4
+.IX Item "NDBM_File and ODBM_File do not work on FAT filesystems"
+.ie n .IP "fork() failures in io_* tests" 4
+.el .IP "\f(CWfork()\fR failures in io_* tests" 4
+.IX Item "fork() failures in io_* tests"
+.RE
+.RS 4
+.RE
+.IP "Specific features of the Cygwin port" 4
+.IX Item "Specific features of the Cygwin port"
+.RS 4
+.IP "Script Portability on Cygwin" 4
+.IX Item "Script Portability on Cygwin"
+.PD
+Pathnames, Text/Binary, PerlIO, \fI.exe\fR, Cygwin vs. Windows process ids,
+Cygwin vs. Windows errors, rebase errors on fork or system, Miscellaneous
+.IP "Prebuilt methods:" 4
+.IX Item "Prebuilt methods:"
+\&\f(CW\*(C`Cwd::cwd\*(C'\fR, \f(CW\*(C`Cygwin::pid_to_winpid\*(C'\fR, \f(CW\*(C`Cygwin::winpid_to_pid\*(C'\fR,
+\&\f(CW\*(C`Cygwin::win_to_posix_path\*(C'\fR, \f(CW\*(C`Cygwin::posix_to_win_path\*(C'\fR,
+\&\f(CWCygwin::mount_table()\fR, \f(CW\*(C`Cygwin::mount_flags\*(C'\fR, \f(CW\*(C`Cygwin::is_binmount\*(C'\fR,
+\&\f(CW\*(C`Cygwin::sync_winenv\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "INSTALL PERL ON CYGWIN" 4
+.IX Item "INSTALL PERL ON CYGWIN"
+.PD 0
+.IP "MANIFEST ON CYGWIN" 4
+.IX Item "MANIFEST ON CYGWIN"
+.PD
+Documentation, Build, Configure, Make, Install, Tests, Compiled Perl
+Source, Compiled Module Source, Perl Modules/Scripts, Perl Module Tests
+.IP "BUGS ON CYGWIN" 4
+.IX Item "BUGS ON CYGWIN"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perlfreebsd \- Perl version 5 on FreeBSD systems"
+.IX Subsection "perlfreebsd - Perl version 5 on FreeBSD systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "FreeBSD core dumps from readdir_r with ithreads" 4
+.IX Item "FreeBSD core dumps from readdir_r with ithreads"
+.ie n .IP "$^X doesn't always contain a full path in FreeBSD" 4
+.el .IP "\f(CW$^X\fR doesn't always contain a full path in FreeBSD" 4
+.IX Item "$^X doesn't always contain a full path in FreeBSD"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlhaiku \- Perl version 5.10+ on Haiku"
+.IX Subsection "perlhaiku - Perl version 5.10+ on Haiku"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "BUILD AND INSTALL" 4
+.IX Item "BUILD AND INSTALL"
+.IP "KNOWN PROBLEMS" 4
+.IX Item "KNOWN PROBLEMS"
+.IP CONTACT 4
+.IX Item "CONTACT"
+.PD
+.SS "perlhpux \- Perl version 5 on Hewlett-Packard Unix (HP-UX) systems"
+.IX Subsection "perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Using perl as shipped with HP-UX" 4
+.IX Item "Using perl as shipped with HP-UX"
+.IP "Using perl from HP's porting centre" 4
+.IX Item "Using perl from HP's porting centre"
+.IP "Other prebuilt perl binaries" 4
+.IX Item "Other prebuilt perl binaries"
+.IP "Compiling Perl 5 on HP-UX" 4
+.IX Item "Compiling Perl 5 on HP-UX"
+.IP PA-RISC 4
+.IX Item "PA-RISC"
+.IP "PA-RISC 1.0" 4
+.IX Item "PA-RISC 1.0"
+.IP "PA-RISC 1.1" 4
+.IX Item "PA-RISC 1.1"
+.IP "PA-RISC 2.0" 4
+.IX Item "PA-RISC 2.0"
+.IP "Portability Between PA-RISC Versions" 4
+.IX Item "Portability Between PA-RISC Versions"
+.IP "Itanium Processor Family (IPF) and HP-UX" 4
+.IX Item "Itanium Processor Family (IPF) and HP-UX"
+.IP "Itanium, Itanium 2 & Madison 6" 4
+.IX Item "Itanium, Itanium 2 & Madison 6"
+.IP "HP-UX versions" 4
+.IX Item "HP-UX versions"
+.IP "Building Dynamic Extensions on HP-UX" 4
+.IX Item "Building Dynamic Extensions on HP-UX"
+.IP "The HP ANSI C Compiler" 4
+.IX Item "The HP ANSI C Compiler"
+.IP "The GNU C Compiler" 4
+.IX Item "The GNU C Compiler"
+.IP "Using Large Files with Perl on HP-UX" 4
+.IX Item "Using Large Files with Perl on HP-UX"
+.IP "Threaded Perl on HP-UX" 4
+.IX Item "Threaded Perl on HP-UX"
+.IP "64\-bit Perl on HP-UX" 4
+.IX Item "64-bit Perl on HP-UX"
+.IP "Oracle on HP-UX" 4
+.IX Item "Oracle on HP-UX"
+.IP "GDBM and Threads on HP-UX" 4
+.IX Item "GDBM and Threads on HP-UX"
+.IP "NFS filesystems and \fButime\fR\|(2) on HP-UX" 4
+.IX Item "NFS filesystems and utime on HP-UX"
+.IP "HP-UX Kernel Parameters (maxdsiz) for Compiling Perl" 4
+.IX Item "HP-UX Kernel Parameters (maxdsiz) for Compiling Perl"
+.RE
+.RS 4
+.RE
+.IP "nss_delete core dump from op/pwent or op/grent" 4
+.IX Item "nss_delete core dump from op/pwent or op/grent"
+.IP "error: pasting "")"" and ""l"" does not give a valid preprocessing token" 4
+.IX Item "error: pasting "")"" and ""l"" does not give a valid preprocessing token"
+.IP "Redeclaration of ""sendpath"" with a different storage class specifier" 4
+.IX Item "Redeclaration of ""sendpath"" with a different storage class specifier"
+.IP Miscellaneous 4
+.IX Item "Miscellaneous"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlhurd \- Perl version 5 on Hurd"
+.IX Subsection "perlhurd - Perl version 5 on Hurd"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Known Problems with Perl on Hurd" 4
+.IX Item "Known Problems with Perl on Hurd"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlirix \- Perl version 5 on Irix systems"
+.IX Subsection "perlirix - Perl version 5 on Irix systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Building 32\-bit Perl in Irix" 4
+.IX Item "Building 32-bit Perl in Irix"
+.IP "Building 64\-bit Perl in Irix" 4
+.IX Item "Building 64-bit Perl in Irix"
+.IP "About Compiler Versions of Irix" 4
+.IX Item "About Compiler Versions of Irix"
+.IP "Linker Problems in Irix" 4
+.IX Item "Linker Problems in Irix"
+.IP "Malloc in Irix" 4
+.IX Item "Malloc in Irix"
+.IP "Building with threads in Irix" 4
+.IX Item "Building with threads in Irix"
+.IP "Irix 5.3" 4
+.IX Item "Irix 5.3"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perllinux \- Perl version 5 on Linux systems"
+.IX Subsection "perllinux - Perl version 5 on Linux systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Deploying Perl on Linux" 4
+.IX Item "Deploying Perl on Linux"
+.IP "Experimental Support for Sun Studio Compilers for Linux OS" 4
+.IX Item "Experimental Support for Sun Studio Compilers for Linux OS"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlmacosx \- Perl under Mac OS X"
+.IX Subsection "perlmacosx - Perl under Mac OS X"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Installation Prefix" 4
+.IX Item "Installation Prefix"
+.IP "SDK support" 4
+.IX Item "SDK support"
+.IP "Universal Binary support" 4
+.IX Item "Universal Binary support"
+.IP "64\-bit PPC support" 4
+.IX Item "64-bit PPC support"
+.IP "libperl and Prebinding" 4
+.IX Item "libperl and Prebinding"
+.IP "Updating Apple's Perl" 4
+.IX Item "Updating Apple's Perl"
+.IP "Known problems" 4
+.IX Item "Known problems"
+.IP Cocoa 4
+.IX Item "Cocoa"
+.RE
+.RS 4
+.RE
+.IP "Starting From Scratch" 4
+.IX Item "Starting From Scratch"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP DATE 4
+.IX Item "DATE"
+.PD
+.SS "perlopenbsd \- Perl version 5 on OpenBSD systems"
+.IX Subsection "perlopenbsd - Perl version 5 on OpenBSD systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads" 4
+.IX Item "OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlos2 \- Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT."
+.IX Subsection "perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Target 4
+.IX Item "Target"
+.IP "Other OSes" 4
+.IX Item "Other OSes"
+.IP Prerequisites 4
+.IX Item "Prerequisites"
+.PD
+EMX, RSX, HPFS, pdksh
+.IP "Starting Perl programs under OS/2 (and DOS and...)" 4
+.IX Item "Starting Perl programs under OS/2 (and DOS and...)"
+.PD 0
+.IP "Starting OS/2 (and DOS) programs under Perl" 4
+.IX Item "Starting OS/2 (and DOS) programs under Perl"
+.RE
+.RS 4
+.RE
+.IP "Frequently asked questions" 4
+.IX Item "Frequently asked questions"
+.RS 4
+.IP """It does not work""" 4
+.IX Item """It does not work"""
+.IP "I cannot run external programs" 4
+.IX Item "I cannot run external programs"
+.IP "I cannot embed perl into my program, or use \fIperl.dll\fR from my program." 4
+.IX Item "I cannot embed perl into my program, or use perl.dll from my program."
+.PD
+Is your program EMX-compiled with \f(CW\*(C`\-Zmt \-Zcrtdll\*(C'\fR?, Did you use
+ExtUtils::Embed?
+.ie n .IP "\`\` and pipe\-""open"" do not work under DOS." 4
+.el .IP "\f(CW\`\`\fR and pipe\-\f(CWopen\fR do not work under DOS." 4
+.IX Item " and pipe-open do not work under DOS."
+.PD 0
+.ie n .IP "Cannot start ""find.exe ""pattern"" file""" 4
+.el .IP "Cannot start \f(CWfind.exe ""pattern"" file\fR" 4
+.IX Item "Cannot start find.exe ""pattern"" file"
+.RE
+.RS 4
+.RE
+.IP INSTALLATION 4
+.IX Item "INSTALLATION"
+.RS 4
+.IP "Automatic binary installation" 4
+.IX Item "Automatic binary installation"
+.PD
+\&\f(CW\*(C`PERL_BADLANG\*(C'\fR, \f(CW\*(C`PERL_BADFREE\*(C'\fR, \fIConfig.pm\fR
+.IP "Manual binary installation" 4
+.IX Item "Manual binary installation"
+Perl VIO and PM executables (dynamically linked), Perl_ VIO executable
+(statically linked), Executables for Perl utilities, Main Perl library,
+Additional Perl modules, Tools to compile Perl modules, Manpages for Perl
+and utilities, Manpages for Perl modules, Source for Perl documentation,
+Perl manual in \fI.INF\fR format, Pdksh
+.IP \fBWarning\fR 4
+.IX Item "Warning"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Accessing documentation" 4
+.IX Item "Accessing documentation"
+.RS 4
+.IP "OS/2 \fI.INF\fR file" 4
+.IX Item "OS/2 .INF file"
+.IP "Plain text" 4
+.IX Item "Plain text"
+.IP Manpages 4
+.IX Item "Manpages"
+.IP HTML 4
+.IX Item "HTML"
+.ie n .IP "GNU ""info"" files" 4
+.el .IP "GNU \f(CWinfo\fR files" 4
+.IX Item "GNU info files"
+.IP "\fIPDF\fR files" 4
+.IX Item "PDF files"
+.ie n .IP """LaTeX"" docs" 4
+.el .IP "\f(CWLaTeX\fR docs" 4
+.IX Item "LaTeX docs"
+.RE
+.RS 4
+.RE
+.IP BUILD 4
+.IX Item "BUILD"
+.RS 4
+.IP "The short story" 4
+.IX Item "The short story"
+.IP Prerequisites 4
+.IX Item "Prerequisites"
+.IP "Getting perl source" 4
+.IX Item "Getting perl source"
+.IP "Application of the patches" 4
+.IX Item "Application of the patches"
+.IP Hand-editing 4
+.IX Item "Hand-editing"
+.IP Making 4
+.IX Item "Making"
+.IP Testing 4
+.IX Item "Testing"
+.PD
+A lot of \f(CW\*(C`bad free\*(C'\fR, Process terminated by SIGTERM/SIGINT, \fIop/fs.t\fR,
+18, 25, \fIop/stat.t\fR
+.IP "Installing the built perl" 4
+.IX Item "Installing the built perl"
+.PD 0
+.ie n .IP """a.out""\-style build" 4
+.el .IP "\f(CWa.out\fR\-style build" 4
+.IX Item "a.out-style build"
+.RE
+.RS 4
+.RE
+.IP "Building a binary distribution" 4
+.IX Item "Building a binary distribution"
+.IP "Building custom \fI.EXE\fR files" 4
+.IX Item "Building custom .EXE files"
+.RS 4
+.IP "Making executables with a custom collection of statically loaded extensions" 4
+.IX Item "Making executables with a custom collection of statically loaded extensions"
+.IP "Making executables with a custom search-paths" 4
+.IX Item "Making executables with a custom search-paths"
+.RE
+.RS 4
+.RE
+.IP "Build FAQ" 4
+.IX Item "Build FAQ"
+.RS 4
+.ie n .IP "Some ""/"" became ""\e"" in pdksh." 4
+.el .IP "Some \f(CW/\fR became \f(CW\e\fR in pdksh." 4
+.IX Item "Some / became in pdksh."
+.ie n .IP "\*(Aqerrno\*(Aq \- unresolved external" 4
+.el .IP "\f(CW\*(Aqerrno\*(Aq\fR \- unresolved external" 4
+.IX Item "errno - unresolved external"
+.IP "Problems with tr or sed" 4
+.IX Item "Problems with tr or sed"
+.IP "Some problem (forget which ;\-)" 4
+.IX Item "Some problem (forget which ;-)"
+.IP "Library ... not found" 4
+.IX Item "Library ... not found"
+.IP "Segfault in make" 4
+.IX Item "Segfault in make"
+.IP "op/sprintf test failure" 4
+.IX Item "op/sprintf test failure"
+.RE
+.RS 4
+.RE
+.IP "Specific (mis)features of OS/2 port" 4
+.IX Item "Specific (mis)features of OS/2 port"
+.RS 4
+.ie n .IP """setpriority"", ""getpriority""" 4
+.el .IP "\f(CWsetpriority\fR, \f(CWgetpriority\fR" 4
+.IX Item "setpriority, getpriority"
+.ie n .IP system() 4
+.el .IP \f(CWsystem()\fR 4
+.IX Item "system()"
+.ie n .IP """extproc"" on the first line" 4
+.el .IP "\f(CWextproc\fR on the first line" 4
+.IX Item "extproc on the first line"
+.IP "Additional modules:" 4
+.IX Item "Additional modules:"
+.IP "Prebuilt methods:" 4
+.IX Item "Prebuilt methods:"
+.PD
+\&\f(CW\*(C`File::Copy::syscopy\*(C'\fR, \f(CW\*(C`DynaLoader::mod2fname\*(C'\fR,  \f(CWCwd::current_drive()\fR,
+ \f(CWCwd::sys_chdir(name)\fR,  \f(CWCwd::change_drive(name)\fR, 
+\&\f(CWCwd::sys_is_absolute(name)\fR,	\f(CWCwd::sys_is_rooted(name)\fR, 
+\&\f(CWCwd::sys_is_relative(name)\fR,	\f(CWCwd::sys_cwd(name)\fR, 
+\&\f(CW\*(C`Cwd::sys_abspath(name, dir)\*(C'\fR,  \f(CWCwd::extLibpath([type])\fR, 
+\&\f(CW\*(C`Cwd::extLibpath_set( path [, type ] )\*(C'\fR,
+\&\f(CW\*(C`OS2::Error(do_harderror,do_exception)\*(C'\fR, \f(CWOS2::Errors2Drive(drive)\fR,
+\&\fBOS2::SysInfo()\fR, \fBOS2::BootDrive()\fR, \f(CWOS2::MorphPM(serve)\fR,
+\&\f(CWOS2::UnMorphPM(serve)\fR, \f(CWOS2::Serve_Messages(force)\fR,
+\&\f(CW\*(C`OS2::Process_Messages(force [, cnt])\*(C'\fR, \f(CW\*(C`OS2::_control87(new,mask)\*(C'\fR,
+\&\fBOS2::get_control87()\fR, \f(CW\*(C`OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)\*(C'\fR,
+\&\f(CW\*(C`OS2::DLLname([how [, \e&xsub]])\*(C'\fR
+.IP "Prebuilt variables:" 4
+.IX Item "Prebuilt variables:"
+\&\f(CW$OS2::emx_rev\fR, \f(CW$OS2::emx_env\fR, \f(CW$OS2::os_ver\fR, \f(CW$OS2::is_aout\fR, \f(CW$OS2::can_fork\fR,
+\&\f(CW$OS2::nsyserror\fR
+.IP Misfeatures 4
+.IX Item "Misfeatures"
+.PD 0
+.IP Modifications 4
+.IX Item "Modifications"
+.PD
+\&\f(CW\*(C`popen\*(C'\fR, \f(CW\*(C`tmpnam\*(C'\fR, \f(CW\*(C`tmpfile\*(C'\fR, \f(CW\*(C`ctermid\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR,
+\&\f(CW\*(C`flock\*(C'\fR
+.IP "Identifying DLLs" 4
+.IX Item "Identifying DLLs"
+.PD 0
+.IP "Centralized management of resources" 4
+.IX Item "Centralized management of resources"
+.PD
+\&\f(CW\*(C`HAB\*(C'\fR, \f(CW\*(C`HMQ\*(C'\fR, Treating errors reported by OS/2 API,
+\&\f(CWCheckOSError(expr)\fR, \f(CWCheckWinError(expr)\fR, \f(CWSaveWinError(expr)\fR,
+\&\f(CW\*(C`SaveCroakWinError(expr,die,name1,name2)\*(C'\fR, \f(CW\*(C`WinError_2_Perl_rc\*(C'\fR,
+\&\f(CW\*(C`FillWinError\*(C'\fR, \f(CWFillOSError(rc)\fR, Loading DLLs and ordinals in DLLs
+.RE
+.RS 4
+.RE
+.IP "Perl flavors" 4
+.IX Item "Perl flavors"
+.RS 4
+.PD 0
+.IP \fIperl.exe\fR 4
+.IX Item "perl.exe"
+.IP \fIperl_.exe\fR 4
+.IX Item "perl_.exe"
+.IP \fIperl_\|_.exe\fR 4
+.IX Item "perl__.exe"
+.IP \fIperl_\|_\|_.exe\fR 4
+.IX Item "perl___.exe"
+.IP "Why strange names?" 4
+.IX Item "Why strange names?"
+.IP "Why dynamic linking?" 4
+.IX Item "Why dynamic linking?"
+.IP "Why chimera build?" 4
+.IX Item "Why chimera build?"
+.RE
+.RS 4
+.RE
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.RS 4
+.ie n .IP """PERLLIB_PREFIX""" 4
+.el .IP \f(CWPERLLIB_PREFIX\fR 4
+.IX Item "PERLLIB_PREFIX"
+.ie n .IP """PERL_BADLANG""" 4
+.el .IP \f(CWPERL_BADLANG\fR 4
+.IX Item "PERL_BADLANG"
+.ie n .IP """PERL_BADFREE""" 4
+.el .IP \f(CWPERL_BADFREE\fR 4
+.IX Item "PERL_BADFREE"
+.ie n .IP """PERL_SH_DIR""" 4
+.el .IP \f(CWPERL_SH_DIR\fR 4
+.IX Item "PERL_SH_DIR"
+.ie n .IP """USE_PERL_FLOCK""" 4
+.el .IP \f(CWUSE_PERL_FLOCK\fR 4
+.IX Item "USE_PERL_FLOCK"
+.ie n .IP """TMP"" or ""TEMP""" 4
+.el .IP "\f(CWTMP\fR or \f(CWTEMP\fR" 4
+.IX Item "TMP or TEMP"
+.RE
+.RS 4
+.RE
+.IP Evolution 4
+.IX Item "Evolution"
+.RS 4
+.IP "Text-mode filehandles" 4
+.IX Item "Text-mode filehandles"
+.IP Priorities 4
+.IX Item "Priorities"
+.IP "DLL name mangling: pre 5.6.2" 4
+.IX Item "DLL name mangling: pre 5.6.2"
+.IP "DLL name mangling: 5.6.2 and beyond" 4
+.IX Item "DLL name mangling: 5.6.2 and beyond"
+.PD
+Global DLLs, specific DLLs, \f(CW\*(C`BEGINLIBPATH\*(C'\fR and \f(CW\*(C`ENDLIBPATH\*(C'\fR, \fI.\fR from
+\&\f(CW\*(C`LIBPATH\*(C'\fR
+.IP "DLL forwarder generation" 4
+.IX Item "DLL forwarder generation"
+.PD 0
+.IP Threading 4
+.IX Item "Threading"
+.IP "Calls to external programs" 4
+.IX Item "Calls to external programs"
+.IP "Memory allocation" 4
+.IX Item "Memory allocation"
+.IP Threads 4
+.IX Item "Threads"
+.PD
+\&\f(CW\*(C`COND_WAIT\*(C'\fR, \fIos2.c\fR
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "perlos390 \- building and installing Perl for z/OS (previously called OS/390)"
+.IX Subsection "perlos390 - building and installing Perl for z/OS (previously called OS/390)"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Tools 4
+.IX Item "Tools"
+.IP "Building a 64\-bit Dynamic ASCII Perl" 4
+.IX Item "Building a 64-bit Dynamic ASCII Perl"
+.IP "Building a 64\-bit Dynamic EBCDIC Perl" 4
+.IX Item "Building a 64-bit Dynamic EBCDIC Perl"
+.IP "Setup and utilities for Perl on OS/390" 4
+.IX Item "Setup and utilities for Perl on OS/390"
+.IP "Useful files for trouble-shooting" 4
+.IX Item "Useful files for trouble-shooting"
+.IP "Build Anomalies with Perl on OS/390" 4
+.IX Item "Build Anomalies with Perl on OS/390"
+.IP "Testing Anomalies with Perl on OS/390" 4
+.IX Item "Testing Anomalies with Perl on OS/390"
+.IP "Usage Hints for Perl on z/OS" 4
+.IX Item "Usage Hints for Perl on z/OS"
+.IP "Modules and Extensions for Perl on z/OS (Static Only)" 4
+.IX Item "Modules and Extensions for Perl on z/OS (Static Only)"
+.IP "Running Perl on z/OS" 4
+.IX Item "Running Perl on z/OS"
+.PD
+For ASCII Only:, For ASCII or EBCDIC:
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD 0
+.IP "OTHER SITES" 4
+.IX Item "OTHER SITES"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perlos400 \- Perl version 5 on OS/400"
+.IX Subsection "perlos400 - Perl version 5 on OS/400"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Compiling Perl for OS/400 PASE" 4
+.IX Item "Compiling Perl for OS/400 PASE"
+.IP "Installing Perl in OS/400 PASE" 4
+.IX Item "Installing Perl in OS/400 PASE"
+.IP "Using Perl in OS/400 PASE" 4
+.IX Item "Using Perl in OS/400 PASE"
+.IP "Known Problems" 4
+.IX Item "Known Problems"
+.IP "Perl on ILE" 4
+.IX Item "Perl on ILE"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "perlplan9 \- Plan 9\-specific documentation for Perl"
+.IX Subsection "perlplan9 - Plan 9-specific documentation for Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Invoking Perl" 4
+.IX Item "Invoking Perl"
+.IP "What's in Plan 9 Perl" 4
+.IX Item "What's in Plan 9 Perl"
+.IP "What's not in Plan 9 Perl" 4
+.IX Item "What's not in Plan 9 Perl"
+.IP "Perl5 Functions not currently supported in Plan 9 Perl" 4
+.IX Item "Perl5 Functions not currently supported in Plan 9 Perl"
+.IP "Signals in Plan 9 Perl" 4
+.IX Item "Signals in Plan 9 Perl"
+.RE
+.RS 4
+.RE
+.IP "COMPILING AND INSTALLING PERL ON PLAN 9" 4
+.IX Item "COMPILING AND INSTALLING PERL ON PLAN 9"
+.RS 4
+.IP "Installing Perl Documentation on Plan 9" 4
+.IX Item "Installing Perl Documentation on Plan 9"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "Revision date" 4
+.IX Item "Revision date"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlqnx \- Perl version 5 on QNX"
+.IX Subsection "perlqnx - Perl version 5 on QNX"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Required Software for Compiling Perl on QNX4" 4
+.IX Item "Required Software for Compiling Perl on QNX4"
+.PD
+/bin/sh, ar, nm, cpp, make
+.IP "Outstanding Issues with Perl on QNX4" 4
+.IX Item "Outstanding Issues with Perl on QNX4"
+.PD 0
+.IP "QNX auxiliary files" 4
+.IX Item "QNX auxiliary files"
+.PD
+qnx/ar, qnx/cpp
+.IP "Outstanding issues with perl under QNX6" 4
+.IX Item "Outstanding issues with perl under QNX6"
+.PD 0
+.IP Cross-compilation 4
+.IX Item "Cross-compilation"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlriscos \- Perl version 5 for RISC OS"
+.IX Subsection "perlriscos - Perl version 5 for RISC OS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP BUILD 4
+.IX Item "BUILD"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlsolaris \- Perl version 5 on Solaris systems"
+.IX Subsection "perlsolaris - Perl version 5 on Solaris systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Solaris Version Numbers." 4
+.IX Item "Solaris Version Numbers."
+.RE
+.RS 4
+.RE
+.IP RESOURCES 4
+.IX Item "RESOURCES"
+.PD
+Solaris FAQ, Precompiled Binaries, Solaris Documentation
+.IP "SETTING UP" 4
+.IX Item "SETTING UP"
+.RS 4
+.PD 0
+.IP "File Extraction Problems on Solaris." 4
+.IX Item "File Extraction Problems on Solaris."
+.IP "Compiler and Related Tools on Solaris." 4
+.IX Item "Compiler and Related Tools on Solaris."
+.IP "Environment for Compiling perl on Solaris" 4
+.IX Item "Environment for Compiling perl on Solaris"
+.RE
+.RS 4
+.RE
+.IP "RUN CONFIGURE." 4
+.IX Item "RUN CONFIGURE."
+.RS 4
+.IP "64\-bit perl on Solaris." 4
+.IX Item "64-bit perl on Solaris."
+.IP "Threads in perl on Solaris." 4
+.IX Item "Threads in perl on Solaris."
+.IP "Malloc Issues with perl on Solaris." 4
+.IX Item "Malloc Issues with perl on Solaris."
+.RE
+.RS 4
+.RE
+.IP "MAKE PROBLEMS." 4
+.IX Item "MAKE PROBLEMS."
+.PD
+Dynamic Loading Problems With GNU as and GNU ld, ld.so.1: ./perl: fatal:
+relocation error:, dlopen: stub interception failed, #error "No
+DATAMODEL_NATIVE specified", sh: ar: not found
+.IP "MAKE TEST" 4
+.IX Item "MAKE TEST"
+.RS 4
+.PD 0
+.IP "op/stat.t test 4 in Solaris" 4
+.IX Item "op/stat.t test 4 in Solaris"
+.IP "nss_delete core dump from op/pwent or op/grent" 4
+.IX Item "nss_delete core dump from op/pwent or op/grent"
+.RE
+.RS 4
+.RE
+.IP CROSS-COMPILATION 4
+.IX Item "CROSS-COMPILATION"
+.IP "PREBUILT BINARIES OF PERL FOR SOLARIS." 4
+.IX Item "PREBUILT BINARIES OF PERL FOR SOLARIS."
+.IP "RUNTIME ISSUES FOR PERL ON SOLARIS." 4
+.IX Item "RUNTIME ISSUES FOR PERL ON SOLARIS."
+.RS 4
+.IP "Limits on Numbers of Open Files on Solaris." 4
+.IX Item "Limits on Numbers of Open Files on Solaris."
+.RE
+.RS 4
+.RE
+.IP "SOLARIS-SPECIFIC MODULES." 4
+.IX Item "SOLARIS-SPECIFIC MODULES."
+.IP "SOLARIS-SPECIFIC PROBLEMS WITH MODULES." 4
+.IX Item "SOLARIS-SPECIFIC PROBLEMS WITH MODULES."
+.RS 4
+.IP "Proc::ProcessTable on Solaris" 4
+.IX Item "Proc::ProcessTable on Solaris"
+.IP "BSD::Resource on Solaris" 4
+.IX Item "BSD::Resource on Solaris"
+.IP "Net::SSLeay on Solaris" 4
+.IX Item "Net::SSLeay on Solaris"
+.RE
+.RS 4
+.RE
+.IP "SunOS 4.x" 4
+.IX Item "SunOS 4.x"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlsynology \- Perl 5 on Synology DSM systems"
+.IX Subsection "perlsynology - Perl 5 on Synology DSM systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Setting up the build environment" 4
+.IX Item "Setting up the build environment"
+.IP "Compiling Perl 5" 4
+.IX Item "Compiling Perl 5"
+.IP "Known problems" 4
+.IX Item "Known problems"
+.PD
+Error message "No error definitions found",
+\&\fIext/DynaLoader/t/DynaLoader.t\fR
+.IP "Smoke testing Perl" 4
+.IX Item "Smoke testing Perl"
+.PD 0
+.IP "Adding libraries" 4
+.IX Item "Adding libraries"
+.RE
+.RS 4
+.RE
+.IP REVISION 4
+.IX Item "REVISION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perltru64 \- Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems"
+.IX Subsection "perltru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Compiling Perl 5 on Tru64" 4
+.IX Item "Compiling Perl 5 on Tru64"
+.IP "Using Large Files with Perl on Tru64" 4
+.IX Item "Using Large Files with Perl on Tru64"
+.IP "Threaded Perl on Tru64" 4
+.IX Item "Threaded Perl on Tru64"
+.IP "Long Doubles on Tru64" 4
+.IX Item "Long Doubles on Tru64"
+.IP "DB_File tests failing on Tru64" 4
+.IX Item "DB_File tests failing on Tru64"
+.IP "64\-bit Perl on Tru64" 4
+.IX Item "64-bit Perl on Tru64"
+.IP "Warnings about floating-point overflow when compiling Perl on Tru64" 4
+.IX Item "Warnings about floating-point overflow when compiling Perl on Tru64"
+.RE
+.RS 4
+.RE
+.IP "Testing Perl on Tru64" 4
+.IX Item "Testing Perl on Tru64"
+.IP "ext/ODBM_File/odbm Test Failing With Static Builds" 4
+.IX Item "ext/ODBM_File/odbm Test Failing With Static Builds"
+.IP "Perl Fails Because Of Unresolved Symbol sockatmark" 4
+.IX Item "Perl Fails Because Of Unresolved Symbol sockatmark"
+.IP "read_cur_obj_info: bad file magic number" 4
+.IX Item "read_cur_obj_info: bad file magic number"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlvms \- VMS-specific documentation for Perl"
+.IX Subsection "perlvms - VMS-specific documentation for Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP Installation 4
+.IX Item "Installation"
+.IP "Organization of Perl Images" 4
+.IX Item "Organization of Perl Images"
+.RS 4
+.IP "Core Images" 4
+.IX Item "Core Images"
+.IP "Perl Extensions" 4
+.IX Item "Perl Extensions"
+.IP "Installing static extensions" 4
+.IX Item "Installing static extensions"
+.IP "Installing dynamic extensions" 4
+.IX Item "Installing dynamic extensions"
+.RE
+.RS 4
+.RE
+.IP "File specifications" 4
+.IX Item "File specifications"
+.RS 4
+.IP Syntax 4
+.IX Item "Syntax"
+.IP "Filename Case" 4
+.IX Item "Filename Case"
+.IP "Symbolic Links" 4
+.IX Item "Symbolic Links"
+.IP "Wildcard expansion" 4
+.IX Item "Wildcard expansion"
+.IP Pipes 4
+.IX Item "Pipes"
+.RE
+.RS 4
+.RE
+.IP "PERL5LIB and PERLLIB" 4
+.IX Item "PERL5LIB and PERLLIB"
+.IP "The Perl Forked Debugger" 4
+.IX Item "The Perl Forked Debugger"
+.IP PERL_VMS_EXCEPTION_DEBUG 4
+.IX Item "PERL_VMS_EXCEPTION_DEBUG"
+.IP "Command line" 4
+.IX Item "Command line"
+.RS 4
+.IP "I/O redirection and backgrounding" 4
+.IX Item "I/O redirection and backgrounding"
+.IP "Command line switches" 4
+.IX Item "Command line switches"
+.PD
+\&\-i, \-S, \-u
+.RE
+.RS 4
+.RE
+.IP "Perl functions" 4
+.IX Item "Perl functions"
+File tests, backticks, binmode FILEHANDLE, crypt PLAINTEXT, USER, die,
+dump, exec LIST, fork, getpwent, getpwnam, getpwuid, gmtime, kill, qx//,
+select (system call), stat EXPR, system LIST, time, times, unlink LIST,
+utime LIST, waitpid PID,FLAGS
+.IP "Perl variables" 4
+.IX Item "Perl variables"
+\&\f(CW%ENV\fR, CRTL_ENV, CLISYM_[LOCAL], Any other string, $!, $^E, $?, $|
+.IP "Standard modules with VMS-specific differences" 4
+.IX Item "Standard modules with VMS-specific differences"
+.RS 4
+.PD 0
+.IP SDBM_File 4
+.IX Item "SDBM_File"
+.RE
+.RS 4
+.RE
+.IP "Revision date" 4
+.IX Item "Revision date"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "perlvos \- Perl for Stratus OpenVOS"
+.IX Subsection "perlvos - Perl for Stratus OpenVOS"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "BUILDING PERL FOR OPENVOS" 4
+.IX Item "BUILDING PERL FOR OPENVOS"
+.IP "INSTALLING PERL IN OPENVOS" 4
+.IX Item "INSTALLING PERL IN OPENVOS"
+.IP "USING PERL IN OPENVOS" 4
+.IX Item "USING PERL IN OPENVOS"
+.RS 4
+.IP "Restrictions of Perl on OpenVOS" 4
+.IX Item "Restrictions of Perl on OpenVOS"
+.RE
+.RS 4
+.RE
+.IP "TEST STATUS" 4
+.IX Item "TEST STATUS"
+.IP "SUPPORT STATUS" 4
+.IX Item "SUPPORT STATUS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "LAST UPDATE" 4
+.IX Item "LAST UPDATE"
+.PD
+.SS "perlwin32 \- Perl under Windows"
+.IX Subsection "perlwin32 - Perl under Windows"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+<https://osdn.net/projects/mingw/>, <https://mingw\-w64.org>
+.RS 4
+.IP "Setting Up Perl on Windows" 4
+.IX Item "Setting Up Perl on Windows"
+Make, Command Shell, Microsoft Visual C++, Microsoft Visual C++ 2013\-2022
+Community Edition, Microsoft C++ Build Tools, GCC, Intel C++ Compiler
+.IP Building 4
+.IX Item "Building"
+.PD 0
+.IP "Testing Perl on Windows" 4
+.IX Item "Testing Perl on Windows"
+.IP "Installation of Perl on Windows" 4
+.IX Item "Installation of Perl on Windows"
+.IP "Usage Hints for Perl on Windows" 4
+.IX Item "Usage Hints for Perl on Windows"
+.PD
+Environment Variables, File Globbing, Using perl from the command line,
+Building Extensions, Command-line Wildcard Expansion, Notes on 64\-bit
+Windows
+.IP "Running Perl Scripts" 4
+.IX Item "Running Perl Scripts"
+.PD 0
+.IP "Miscellaneous Things" 4
+.IX Item "Miscellaneous Things"
+.RE
+.RS 4
+.RE
+.IP "BUGS AND CAVEATS" 4
+.IX Item "BUGS AND CAVEATS"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+Gary Ng <71564.1743@CompuServe.COM>, Gurusamy Sarathy
+<gsar@activestate.com>, Nick Ing-Simmons
+<nick@ing\-simmons.net>, Jan Dubois <jand@activestate.com>,
+Steve Hay <steve.m.hay@googlemail.com>
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "perlboot \- Links to information on object-oriented programming in Perl"
+.IX Subsection "perlboot - Links to information on object-oriented programming in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "perlbot \- Links to information on object-oriented programming in Perl"
+.IX Subsection "perlbot - Links to information on object-oriented programming in Perl"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "perlrepository \- Links to current information on the Perl source repository"
+.IX Subsection "perlrepository - Links to current information on the Perl source repository"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "perltodo \- Link to the Perl to-do list"
+.IX Subsection "perltodo - Link to the Perl to-do list"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "perltooc \- Links to information on object-oriented programming in Perl"
+.IX Subsection "perltooc - Links to information on object-oriented programming in Perl"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "perltoot \- Links to information on object-oriented programming in Perl"
+.IX Subsection "perltoot - Links to information on object-oriented programming in Perl"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SH "PRAGMA DOCUMENTATION"
+.IX Header "PRAGMA DOCUMENTATION"
+.SS "attributes \- get/set subroutine or variable attributes"
+.IX Subsection "attributes - get/set subroutine or variable attributes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "What ""import"" does" 4
+.el .IP "What \f(CWimport\fR does" 4
+.IX Item "What import does"
+.IP "Built-in Attributes" 4
+.IX Item "Built-in Attributes"
+.PD
+lvalue, method, prototype(..), const, shared
+.IP "Available Subroutines" 4
+.IX Item "Available Subroutines"
+get, reftype
+.IP "Package-specific Attribute Handling" 4
+.IX Item "Package-specific Attribute Handling"
+FETCH_\fItype\fR_ATTRIBUTES, MODIFY_\fItype\fR_ATTRIBUTES
+.IP "Syntax of Attribute Lists" 4
+.IX Item "Syntax of Attribute Lists"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.RS 4
+.IP "Default exports" 4
+.IX Item "Default exports"
+.IP "Available exports" 4
+.IX Item "Available exports"
+.IP "Export tags defined" 4
+.IX Item "Export tags defined"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP "MORE EXAMPLES" 4
+.IX Item "MORE EXAMPLES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "autodie \- Replace functions with ones that succeed or die with lexical scope"
+.IX Subsection "autodie - Replace functions with ones that succeed or die with lexical scope"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXCEPTIONS 4
+.IX Item "EXCEPTIONS"
+.IP CATEGORIES 4
+.IX Item "CATEGORIES"
+.IP "FUNCTION SPECIFIC NOTES" 4
+.IX Item "FUNCTION SPECIFIC NOTES"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP flock 4
+.IX Item "flock"
+.IP system/exec 4
+.IX Item "system/exec"
+.RE
+.RS 4
+.RE
+.IP GOTCHAS 4
+.IX Item "GOTCHAS"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+:void cannot be used with lexical scope, No user hints defined for \f(CW%s\fR
+.IP "Tips and Tricks" 4
+.IX Item "Tips and Tricks"
+.RS 4
+.PD 0
+.IP "Importing autodie into another namespace than ""caller""" 4
+.IX Item "Importing autodie into another namespace than ""caller"""
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.RS 4
+.IP "autodie and string eval" 4
+.IX Item "autodie and string eval"
+.IP "REPORTING BUGS" 4
+.IX Item "REPORTING BUGS"
+.RE
+.RS 4
+.RE
+.IP FEEDBACK 4
+.IX Item "FEEDBACK"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.PD
+.SS "autodie::Scope::Guard \- Wrapper class for calling subs at end of scope"
+.IX Subsection "autodie::Scope::Guard - Wrapper class for calling subs at end of scope"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Methods 4
+.IX Item "Methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "autodie::Scope::GuardStack \-  Hook stack for managing scopes via %^H"
+.IX Subsection "autodie::Scope::GuardStack - Hook stack for managing scopes via %^H"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Methods 4
+.IX Item "Methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "autodie::Util \- Internal Utility subroutines for autodie and Fatal"
+.IX Subsection "autodie::Util - Internal Utility subroutines for autodie and Fatal"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Methods 4
+.IX Item "Methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "autodie::exception \- Exceptions from autodying functions."
+.IX Subsection "autodie::exception - Exceptions from autodying functions."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Common Methods" 4
+.IX Item "Common Methods"
+.RE
+.RS 4
+.RE
+.IP "Advanced methods" 4
+.IX Item "Advanced methods"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "autodie::exception::system \- Exceptions from autodying \fBsystem()\fP."
+.IX Subsection "autodie::exception::system - Exceptions from autodying system()."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP stringify 4
+.IX Item "stringify"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "autodie::hints \- Provide hints about user subroutines to autodie"
+.IX Subsection "autodie::hints - Provide hints about user subroutines to autodie"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Introduction 4
+.IX Item "Introduction"
+.IP "What are hints?" 4
+.IX Item "What are hints?"
+.IP "Example hints" 4
+.IX Item "Example hints"
+.RE
+.RS 4
+.RE
+.IP "Manually setting hints from within your program" 4
+.IX Item "Manually setting hints from within your program"
+.IP "Adding hints to your module" 4
+.IX Item "Adding hints to your module"
+.IP "Insisting on hints" 4
+.IX Item "Insisting on hints"
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+.PD
+Attempts to set_hints_for unidentifiable subroutine, fail hints cannot be
+provided with either scalar or list hints for \f(CW%s\fR, \f(CW%s\fR hint missing for \f(CW%s\fR
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "autodie::skip \- Skip a package when throwing autodie exceptions"
+.IX Subsection "autodie::skip - Skip a package when throwing autodie exceptions"
+.IP SYNPOSIS 4
+.IX Item "SYNPOSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "autouse \- postpone load of modules until a function is used"
+.IX Subsection "autouse - postpone load of modules until a function is used"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP WARNING 4
+.IX Item "WARNING"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "base \- Establish an ISA relationship with base classes at compile time"
+.IX Subsection "base - Establish an ISA relationship with base classes at compile time"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+Base class package "%s" is empty, Class 'Foo' tried to inherit from itself
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD 0
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "bigfloat \- transparent big floating point number support for Perl"
+.IX Subsection "bigfloat - transparent big floating point number support for Perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Options 4
+.IX Item "Options"
+.PD
+a or accuracy, p or precision, t or trace, l, lib, try, or only, hex, oct,
+v or version
+.IP "Math Library" 4
+.IX Item "Math Library"
+.PD 0
+.IP "Method calls" 4
+.IX Item "Method calls"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\fBinf()\fR, \fBNaN()\fR, e, PI, \fBbexp()\fR, \fBbpi()\fR, \fBaccuracy()\fR, \fBprecision()\fR, \fBround_mode()\fR,
+\&\fBdiv_scale()\fR, \fBupgrade()\fR, \fBdowngrade()\fR, \fBin_effect()\fR
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+Hexadecimal, octal, and binary floating point literals, Operator vs literal
+overloading, Ranges, \fBin_effect()\fR, \fBhex()\fR/\fBoct()\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "bigint \- transparent big integer support for Perl"
+.IX Subsection "bigint - transparent big integer support for Perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "use integer vs. use bigint" 4
+.IX Item "use integer vs. use bigint"
+.IP Options 4
+.IX Item "Options"
+.PD
+a or accuracy, p or precision, t or trace, l, lib, try, or only, hex, oct,
+v or version
+.IP "Math Library" 4
+.IX Item "Math Library"
+.PD 0
+.IP "Method calls" 4
+.IX Item "Method calls"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\fBinf()\fR, \fBNaN()\fR, e, PI, \fBbexp()\fR, \fBbpi()\fR, \fBaccuracy()\fR, \fBprecision()\fR, \fBround_mode()\fR,
+\&\fBdiv_scale()\fR, \fBin_effect()\fR
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+Hexadecimal, octal, and binary floating point literals, Operator vs literal
+overloading, Ranges, \fBin_effect()\fR, \fBhex()\fR/\fBoct()\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "bignum \- transparent big number support for Perl"
+.IX Subsection "bignum - transparent big number support for Perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Literal numeric constants" 4
+.IX Item "Literal numeric constants"
+.IP "Upgrading and downgrading" 4
+.IX Item "Upgrading and downgrading"
+.IP Overloading 4
+.IX Item "Overloading"
+.IP Options 4
+.IX Item "Options"
+.PD
+a or accuracy, p or precision, l, lib, try, or only, hex, oct, v or version
+.IP "Math Library" 4
+.IX Item "Math Library"
+.PD 0
+.IP "Method calls" 4
+.IX Item "Method calls"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\fBinf()\fR, \fBNaN()\fR, e, PI, \fBbexp()\fR, \fBbpi()\fR, \fBaccuracy()\fR, \fBprecision()\fR, \fBround_mode()\fR,
+\&\fBdiv_scale()\fR, \fBupgrade()\fR, \fBdowngrade()\fR, \fBin_effect()\fR
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+The \fBupgrade()\fR and \fBdowngrade()\fR methods, Hexadecimal, octal, and binary
+floating point literals, Operator vs literal overloading, Ranges,
+\&\fBin_effect()\fR, \fBhex()\fR/\fBoct()\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "bigrat \- transparent big rational number support for Perl"
+.IX Subsection "bigrat - transparent big rational number support for Perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Options 4
+.IX Item "Options"
+.PD
+a or accuracy, p or precision, t or trace, l, lib, try, or only, hex, oct,
+v or version
+.IP "Math Library" 4
+.IX Item "Math Library"
+.PD 0
+.IP "Method calls" 4
+.IX Item "Method calls"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\fBinf()\fR, \fBNaN()\fR, e, PI, \fBbexp()\fR, \fBbpi()\fR, \fBaccuracy()\fR, \fBprecision()\fR, \fBround_mode()\fR,
+\&\fBdiv_scale()\fR, \fBin_effect()\fR
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+Hexadecimal, octal, and binary floating point literals, Operator vs literal
+overloading, Ranges, \fBin_effect()\fR, \fBhex()\fR/\fBoct()\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "blib \- Use MakeMaker's uninstalled version of a package"
+.IX Subsection "blib - Use MakeMaker's uninstalled version of a package"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "builtin \- Perl pragma to import built-in utility functions"
+.IX Subsection "builtin - Perl pragma to import built-in utility functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Lexical Import" 4
+.IX Item "Lexical Import"
+.RE
+.RS 4
+.RE
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP true 4
+.IX Item "true"
+.IP false 4
+.IX Item "false"
+.IP is_bool 4
+.IX Item "is_bool"
+.IP weaken 4
+.IX Item "weaken"
+.IP unweaken 4
+.IX Item "unweaken"
+.IP is_weak 4
+.IX Item "is_weak"
+.IP blessed 4
+.IX Item "blessed"
+.IP refaddr 4
+.IX Item "refaddr"
+.IP reftype 4
+.IX Item "reftype"
+.IP created_as_string 4
+.IX Item "created_as_string"
+.IP created_as_number 4
+.IX Item "created_as_number"
+.IP ceil 4
+.IX Item "ceil"
+.IP floor 4
+.IX Item "floor"
+.IP indexed 4
+.IX Item "indexed"
+.IP trim 4
+.IX Item "trim"
+.IP is_tainted 4
+.IX Item "is_tainted"
+.IP export_lexically 4
+.IX Item "export_lexically"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "bytes \- Perl pragma to expose the individual bytes of characters"
+.IX Subsection "bytes - Perl pragma to expose the individual bytes of characters"
+.IP NOTICE 4
+.IX Item "NOTICE"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "charnames \- access to Unicode character names and named character sequences; also define character names"
+.IX Subsection "charnames - access to Unicode character names and named character sequences; also define character names"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "LOOSE MATCHES" 4
+.IX Item "LOOSE MATCHES"
+.IP ALIASES 4
+.IX Item "ALIASES"
+.IP "CUSTOM ALIASES" 4
+.IX Item "CUSTOM ALIASES"
+.IP charnames::string_vianame(\fIname\fR) 4
+.IX Item "charnames::string_vianame(name)"
+.IP charnames::vianame(\fIname\fR) 4
+.IX Item "charnames::vianame(name)"
+.IP charnames::viacode(\fIcode\fR) 4
+.IX Item "charnames::viacode(code)"
+.IP "CUSTOM TRANSLATORS" 4
+.IX Item "CUSTOM TRANSLATORS"
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+.SS "constant \- Perl pragma to declare constants"
+.IX Subsection "constant - Perl pragma to declare constants"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.RS 4
+.IP "List constants" 4
+.IX Item "List constants"
+.IP "Defining multiple constants at once" 4
+.IX Item "Defining multiple constants at once"
+.IP "Magic constants" 4
+.IX Item "Magic constants"
+.RE
+.RS 4
+.RE
+.IP "TECHNICAL NOTES" 4
+.IX Item "TECHNICAL NOTES"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "deprecate \- Perl pragma for deprecating the inclusion of a module in core"
+.IX Subsection "deprecate - Perl pragma for deprecating the inclusion of a module in core"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Important Caveat" 4
+.IX Item "Important Caveat"
+.RE
+.RS 4
+.RE
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "diagnostics, splain \- produce verbose warning diagnostics"
+.IX Subsection "diagnostics, splain - produce verbose warning diagnostics"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "The ""diagnostics"" Pragma" 4
+.el .IP "The \f(CWdiagnostics\fR Pragma" 4
+.IX Item "The diagnostics Pragma"
+.IP "The \fIsplain\fR Program" 4
+.IX Item "The splain Program"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP INTERNALS 4
+.IX Item "INTERNALS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "encoding \- allows you to write your script in non-ASCII and non\-UTF\-8"
+.IX Subsection "encoding - allows you to write your script in non-ASCII and non-UTF-8"
+.IP WARNING 4
+.IX Item "WARNING"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`use encoding [\*(Aq\fR\f(CIENCNAME\fR\f(CW\*(Aq] ;\*(C'\fR, \f(CW\*(C`use encoding \fR\f(CIENCNAME\fR\f(CW,
+Filter=>1;\*(C'\fR, \f(CW\*(C`no encoding;\*(C'\fR
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RS 4
+.PD 0
+.ie n .IP "Setting ""STDIN"" and/or ""STDOUT"" individually" 4
+.el .IP "Setting \f(CWSTDIN\fR and/or \f(CWSTDOUT\fR individually" 4
+.IX Item "Setting STDIN and/or STDOUT individually"
+.ie n .IP "The "":locale"" sub-pragma" 4
+.el .IP "The \f(CW:locale\fR sub-pragma" 4
+.IX Item "The :locale sub-pragma"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.RS 4
+.IP "SIDE EFFECTS" 4
+.IX Item "SIDE EFFECTS"
+.IP "DO NOT MIX MULTIPLE ENCODINGS" 4
+.IX Item "DO NOT MIX MULTIPLE ENCODINGS"
+.IP "Prior to Perl v5.22" 4
+.IX Item "Prior to Perl v5.22"
+.IP "Prior to Encode version 1.87" 4
+.IX Item "Prior to Encode version 1.87"
+.IP "Prior to Perl v5.8.1" 4
+.IX Item "Prior to Perl v5.8.1"
+.PD
+"NON-EUC" doublebyte encodings, \f(CW\*(C`tr///\*(C'\fR, Legend of characters above
+.RE
+.RS 4
+.RE
+.IP "EXAMPLE \- Greekperl" 4
+.IX Item "EXAMPLE - Greekperl"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+Thread safety, Can't be used by more than one module in a single program,
+Other modules using \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR get the encoded stream, literals
+in regex that are longer than 127 bytes, EBCDIC, \f(CW\*(C`format\*(C'\fR, See also
+"CAVEATS" in encoding
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "encoding::warnings \- Warn on implicit encoding conversions"
+.IX Subsection "encoding::warnings - Warn on implicit encoding conversions"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP NOTICE 4
+.IX Item "NOTICE"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overview of the problem" 4
+.IX Item "Overview of the problem"
+.IP "Detecting the problem" 4
+.IX Item "Detecting the problem"
+.IP "Solving the problem" 4
+.IX Item "Solving the problem"
+.PD
+Upgrade both sides to unicode-strings, Downgrade both sides to
+byte-strings, Specify the encoding for implicit byte-string upgrading,
+PerlIO layers for \fBSTDIN\fR and \fBSTDOUT\fR, Literal conversions, Implicit
+upgrading for byte-strings
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "experimental \- Experimental features made easy"
+.IX Subsection "experimental - Experimental features made easy"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`args_array_with_signatures\*(C'\fR \- allow \f(CW@_\fR to be used in signatured subs,
+\&\f(CW\*(C`array_base\*(C'\fR \- allow the use of \f(CW$[\fR to change the starting index of
+\&\f(CW@array\fR, \f(CW\*(C`autoderef\*(C'\fR \- allow push, each, keys, and other built-ins on
+references, \f(CW\*(C`bitwise\*(C'\fR \- allow the new stringwise bit operators, \f(CW\*(C`builtin\*(C'\fR
+\&\- allow the use of the functions in the builtin:: namespace, \f(CW\*(C`const_attr\*(C'\fR
+\&\- allow the :const attribute on subs, \f(CW\*(C`declared_refs\*(C'\fR \- enables aliasing
+via assignment to references, \f(CW\*(C`defer\*(C'\fR \- enables the use of defer blocks,
+\&\f(CW\*(C`extra_paired_delimiters\*(C'\fR \- enables the use of more paired string
+delimiters than the traditional four, \f(CW\*(C`<\ \ >\*(C'\fR, \f(CW\*(C`(\ )\*(C'\fR, \f(CW\*(C`{\ }\*(C'\fR,
+and \f(CW\*(C`[\ ]\*(C'\fR, \f(CW\*(C`for_list\*(C'\fR \- allows iterating over multiple values at a
+time with \f(CW\*(C`for\*(C'\fR, \f(CW\*(C`isa\*(C'\fR \- allow the use of the \f(CW\*(C`isa\*(C'\fR infix operator,
+\&\f(CW\*(C`lexical_topic\*(C'\fR \- allow the use of lexical \f(CW$_\fR via \f(CW\*(C`my $_\*(C'\fR,
+\&\f(CW\*(C`lexical_subs\*(C'\fR \- allow the use of lexical subroutines, \f(CW\*(C`postderef\*(C'\fR \-
+allow the use of postfix dereferencing expressions, \f(CW\*(C`postderef_qq\*(C'\fR \- allow
+the use of postfix dereferencing expressions inside interpolating strings,
+\&\f(CW\*(C`re_strict\*(C'\fR \- enables strict mode in regular expressions, \f(CW\*(C`refaliasing\*(C'\fR \-
+allow aliasing via \f(CW\*(C`\e$x = \e$y\*(C'\fR, \f(CW\*(C`regex_sets\*(C'\fR \- allow extended bracketed
+character classes in regexps, \f(CW\*(C`signatures\*(C'\fR \- allow subroutine signatures
+(for named arguments), \f(CW\*(C`smartmatch\*(C'\fR \- allow the use of \f(CW\*(C`~~\*(C'\fR, \f(CW\*(C`switch\*(C'\fR \-
+allow the use of \f(CW\*(C`~~\*(C'\fR, given, and when, \f(CW\*(C`try\*(C'\fR \- allow the use of \f(CW\*(C`try\*(C'\fR
+and \f(CW\*(C`catch\*(C'\fR, \f(CW\*(C`win32_perlio\*(C'\fR \- allows the use of the :win32 IO layer
+.RS 4
+.IP "Ordering matters" 4
+.IX Item "Ordering matters"
+.PD 0
+.IP Disclaimer 4
+.IX Item "Disclaimer"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "feature \- Perl pragma to enable new features"
+.IX Subsection "feature - Perl pragma to enable new features"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Lexical effect" 4
+.IX Item "Lexical effect"
+.ie n .IP """no feature""" 4
+.el .IP "\f(CWno feature\fR" 4
+.IX Item "no feature"
+.RE
+.RS 4
+.RE
+.IP "AVAILABLE FEATURES" 4
+.IX Item "AVAILABLE FEATURES"
+.RS 4
+.IP "The 'say' feature" 4
+.IX Item "The 'say' feature"
+.IP "The 'state' feature" 4
+.IX Item "The 'state' feature"
+.IP "The 'switch' feature" 4
+.IX Item "The 'switch' feature"
+.IP "The 'unicode_strings' feature" 4
+.IX Item "The 'unicode_strings' feature"
+.IP "The 'unicode_eval' and 'evalbytes' features" 4
+.IX Item "The 'unicode_eval' and 'evalbytes' features"
+.IP "The 'current_sub' feature" 4
+.IX Item "The 'current_sub' feature"
+.IP "The 'array_base' feature" 4
+.IX Item "The 'array_base' feature"
+.IP "The 'fc' feature" 4
+.IX Item "The 'fc' feature"
+.IP "The 'lexical_subs' feature" 4
+.IX Item "The 'lexical_subs' feature"
+.IP "The 'postderef' and 'postderef_qq' features" 4
+.IX Item "The 'postderef' and 'postderef_qq' features"
+.IP "The 'signatures' feature" 4
+.IX Item "The 'signatures' feature"
+.IP "The 'refaliasing' feature" 4
+.IX Item "The 'refaliasing' feature"
+.IP "The 'bitwise' feature" 4
+.IX Item "The 'bitwise' feature"
+.IP "The 'declared_refs' feature" 4
+.IX Item "The 'declared_refs' feature"
+.IP "The 'isa' feature" 4
+.IX Item "The 'isa' feature"
+.IP "The 'indirect' feature" 4
+.IX Item "The 'indirect' feature"
+.IP "The 'multidimensional' feature" 4
+.IX Item "The 'multidimensional' feature"
+.IP "The 'bareword_filehandles' feature" 4
+.IX Item "The 'bareword_filehandles' feature"
+.IP "The 'try' feature" 4
+.IX Item "The 'try' feature"
+.IP "The 'defer' feature" 4
+.IX Item "The 'defer' feature"
+.IP "The 'extra_paired_delimiters' feature" 4
+.IX Item "The 'extra_paired_delimiters' feature"
+.IP "The 'module_true' feature" 4
+.IX Item "The 'module_true' feature"
+.IP "The 'class' feature" 4
+.IX Item "The 'class' feature"
+.RE
+.RS 4
+.RE
+.IP "FEATURE BUNDLES" 4
+.IX Item "FEATURE BUNDLES"
+.IP "IMPLICIT LOADING" 4
+.IX Item "IMPLICIT LOADING"
+.IP "CHECKING FEATURES" 4
+.IX Item "CHECKING FEATURES"
+.PD
+feature_enabled($feature), feature_enabled($feature, \f(CW$depth\fR),
+\&\fBfeatures_enabled()\fR, features_enabled($depth), \fBfeature_bundle()\fR,
+feature_bundle($depth)
+.SS "fields \- compile-time class fields"
+.IX Subsection "fields - compile-time class fields"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+new, phash
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "filetest \- Perl pragma to control the filetest permission operators"
+.IX Subsection "filetest - Perl pragma to control the filetest permission operators"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Consider this carefully" 4
+.IX Item "Consider this carefully"
+.IP "The ""access"" sub-pragma" 4
+.IX Item "The ""access"" sub-pragma"
+.ie n .IP "Limitation with regard to ""_""" 4
+.el .IP "Limitation with regard to \f(CW_\fR" 4
+.IX Item "Limitation with regard to _"
+.RE
+.RS 4
+.RE
+.PD
+.ie n .SS "if \- ""use"" a Perl module if a condition holds"
+.el .SS "if \- \f(CWuse\fP a Perl module if a condition holds"
+.IX Subsection "if - use a Perl module if a condition holds"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP """use if""" 4
+.el .IP "\f(CWuse if\fR" 4
+.IX Item "use if"
+.ie n .IP """no if""" 4
+.el .IP "\f(CWno if\fR" 4
+.IX Item "no if"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENCE" 4
+.IX Item "COPYRIGHT AND LICENCE"
+.PD
+.SS "integer \- Perl pragma to use integer arithmetic instead of floating point"
+.IX Subsection "integer - Perl pragma to use integer arithmetic instead of floating point"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "less \- perl pragma to request less of something"
+.IX Subsection "less - perl pragma to request less of something"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FOR MODULE AUTHORS" 4
+.IX Item "FOR MODULE AUTHORS"
+.RS 4
+.ie n .IP """BOOLEAN = less\->of( FEATURE )""" 4
+.el .IP "\f(CWBOOLEAN = less\->of( FEATURE )\fR" 4
+.IX Item "BOOLEAN = less->of( FEATURE )"
+.ie n .IP """FEATURES = less\->of()""" 4
+.el .IP "\f(CWFEATURES = less\->of()\fR" 4
+.IX Item "FEATURES = less->of()"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+This probably does nothing, This works only on 5.10+
+.ie n .SS "lib \- manipulate @INC at compile time"
+.el .SS "lib \- manipulate \f(CW@INC\fP at compile time"
+.IX Subsection "lib - manipulate @INC at compile time"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "Adding directories to @INC" 4
+.el .IP "Adding directories to \f(CW@INC\fR" 4
+.IX Item "Adding directories to @INC"
+.ie n .IP "Deleting directories from @INC" 4
+.el .IP "Deleting directories from \f(CW@INC\fR" 4
+.IX Item "Deleting directories from @INC"
+.ie n .IP "Restoring original @INC" 4
+.el .IP "Restoring original \f(CW@INC\fR" 4
+.IX Item "Restoring original @INC"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "locale \- Perl pragma to use or avoid POSIX locales for built-in operations"
+.IX Subsection "locale - Perl pragma to use or avoid POSIX locales for built-in operations"
+.IP WARNING 4
+.IX Item "WARNING"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "mro \- Method Resolution Order"
+.IX Subsection "mro - Method Resolution Order"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OVERVIEW 4
+.IX Item "OVERVIEW"
+.IP "The C3 MRO" 4
+.IX Item "The C3 MRO"
+.RS 4
+.IP "What is C3?" 4
+.IX Item "What is C3?"
+.IP "How does C3 work" 4
+.IX Item "How does C3 work"
+.RE
+.RS 4
+.RE
+.IP Functions 4
+.IX Item "Functions"
+.RS 4
+.ie n .IP "mro::get_linear_isa($classname[, $type])" 4
+.el .IP "mro::get_linear_isa($classname[, \f(CW$type\fR])" 4
+.IX Item "mro::get_linear_isa($classname[, $type])"
+.ie n .IP "mro::set_mro ($classname, $type)" 4
+.el .IP "mro::set_mro ($classname, \f(CW$type\fR)" 4
+.IX Item "mro::set_mro ($classname, $type)"
+.IP mro::get_mro($classname) 4
+.IX Item "mro::get_mro($classname)"
+.IP mro::get_isarev($classname) 4
+.IX Item "mro::get_isarev($classname)"
+.IP mro::is_universal($classname) 4
+.IX Item "mro::is_universal($classname)"
+.IP \fBmro::invalidate_all_method_caches()\fR 4
+.IX Item "mro::invalidate_all_method_caches()"
+.IP mro::method_changed_in($classname) 4
+.IX Item "mro::method_changed_in($classname)"
+.IP mro::get_pkg_gen($classname) 4
+.IX Item "mro::get_pkg_gen($classname)"
+.IP next::method 4
+.IX Item "next::method"
+.IP next::can 4
+.IX Item "next::can"
+.IP maybe::next::method 4
+.IX Item "maybe::next::method"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP "The original Dylan paper" 4
+.IX Item "The original Dylan paper"
+.PD
+"/citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.19.3910&rep=rep1
+&type=pdf" in http:
+.IP "Python 2.3 MRO" 4
+.IX Item "Python 2.3 MRO"
+<https://www.python.org/download/releases/2.3/mro/>
+.IP Class::C3 4
+.IX Item "Class::C3"
+Class::C3
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "ok \- Alternative to Test::More::use_ok"
+.IX Subsection "ok - Alternative to Test::More::use_ok"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CC0 1.0 Universal" 4
+.IX Item "CC0 1.0 Universal"
+.PD
+.SS "open \- perl pragma to set default PerlIO layers for input and output"
+.IX Subsection "open - perl pragma to set default PerlIO layers for input and output"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "IMPLEMENTATION DETAILS" 4
+.IX Item "IMPLEMENTATION DETAILS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ops \- Perl pragma to restrict unsafe operations when compiling"
+.IX Subsection "ops - Perl pragma to restrict unsafe operations when compiling"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "overload \- Package for overloading Perl operations"
+.IX Subsection "overload - Package for overloading Perl operations"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Fundamentals 4
+.IX Item "Fundamentals"
+.IP "Overloadable Operations" 4
+.IX Item "Overloadable Operations"
+.PD
+\&\f(CW\*(C`not\*(C'\fR, \f(CW\*(C`neg\*(C'\fR, \f(CW\*(C`++\*(C'\fR, \f(CW\*(C`\-\-\*(C'\fR, \fIAssignments\fR, \fINon-mutators with a mutator
+variant\fR, \f(CW\*(C`int\*(C'\fR, \fIString, numeric, boolean, and regexp conversions\fR,
+\&\fIIteration\fR, \fIFile tests\fR, \fIMatching\fR, \fIDereferencing\fR, \fISpecial\fR
+.IP "Magic Autogeneration" 4
+.IX Item "Magic Autogeneration"
+.PD 0
+.ie n .IP "Special Keys for ""use overload""" 4
+.el .IP "Special Keys for \f(CWuse overload\fR" 4
+.IX Item "Special Keys for use overload"
+.PD
+defined, but FALSE, \f(CW\*(C`undef\*(C'\fR, TRUE
+.IP "How Perl Chooses an Operator Implementation" 4
+.IX Item "How Perl Chooses an Operator Implementation"
+.PD 0
+.IP "Losing Overloading" 4
+.IX Item "Losing Overloading"
+.IP "Inheritance and Overloading" 4
+.IX Item "Inheritance and Overloading"
+.PD
+Method names in the \f(CW\*(C`use overload\*(C'\fR directive, Overloading of an operation
+is inherited by derived classes
+.IP "Run-time Overloading" 4
+.IX Item "Run-time Overloading"
+.PD 0
+.IP "Public Functions" 4
+.IX Item "Public Functions"
+.PD
+overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op)
+.IP "Overloading Constants" 4
+.IX Item "Overloading Constants"
+integer, float, binary, q, qr
+.RE
+.RS 4
+.RE
+.IP IMPLEMENTATION 4
+.IX Item "IMPLEMENTATION"
+.PD 0
+.IP COOKBOOK 4
+.IX Item "COOKBOOK"
+.RS 4
+.IP "Two-face Scalars" 4
+.IX Item "Two-face Scalars"
+.IP "Two-face References" 4
+.IX Item "Two-face References"
+.IP "Symbolic Calculator" 4
+.IX Item "Symbolic Calculator"
+.IP "\fIReally\fR Symbolic Calculator" 4
+.IX Item "Really Symbolic Calculator"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+Odd number of arguments for overload::constant, '%s' is not an overloadable
+type, '%s' is not a code reference, overload arg '%s' is invalid
+.IP "BUGS AND PITFALLS" 4
+.IX Item "BUGS AND PITFALLS"
+.SS "overloading \- perl pragma to lexically control overloading"
+.IX Subsection "overloading - perl pragma to lexically control overloading"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`no overloading\*(C'\fR, \f(CW\*(C`no overloading @ops\*(C'\fR, \f(CW\*(C`use overloading\*(C'\fR, \f(CW\*(C`use
+overloading @ops\*(C'\fR
+.SS "parent \- Establish an ISA relationship with base classes at compile time"
+.IX Subsection "parent - Establish an ISA relationship with base classes at compile time"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+base, parent::versioned
+.IP "AUTHORS AND CONTRIBUTORS" 4
+.IX Item "AUTHORS AND CONTRIBUTORS"
+.PD 0
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "re \- Perl pragma to alter regular expression behaviour"
+.IX Subsection "re - Perl pragma to alter regular expression behaviour"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "'taint' mode" 4
+.IX Item "'taint' mode"
+.IP "'eval' mode" 4
+.IX Item "'eval' mode"
+.IP "'strict' mode" 4
+.IX Item "'strict' mode"
+.IP "'/flags' mode" 4
+.IX Item "'/flags' mode"
+.IP "'debug' mode" 4
+.IX Item "'debug' mode"
+.IP "'Debug' mode" 4
+.IX Item "'Debug' mode"
+.PD
+Compile related options, COMPILE, PARSE, OPTIMISE, TRIEC, DUMP, FLAGS,
+TEST, Execute related options, EXECUTE, MATCH, TRIEE, INTUIT, Extra
+debugging options, EXTRA, BUFFERS, TRIEM, STATE, STACK, GPOS, OPTIMISEM,
+DUMP_PRE_OPTIMIZE, WILDCARD, Other useful flags, ALL, All, MORE, More
+.IP "Exportable Functions" 4
+.IX Item "Exportable Functions"
+is_regexp($ref), regexp_pattern($ref), regname($name,$all), regnames($all),
+\&\fBregnames_count()\fR, regmust($ref), optimization($ref), minlen, minlenret,
+gofs, noscan, isall, anchor SBOL, anchor MBOL, anchor GPOS, skip, implicit,
+anchored/floating, anchored utf8/floating utf8, anchored min
+offset/floating min offset, anchored max offset/floating max offset,
+anchored end shift/floating end shift, checking, stclass
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "sigtrap \- Perl pragma to enable simple signal handling"
+.IX Subsection "sigtrap - Perl pragma to enable simple signal handling"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RS 4
+.IP "SIGNAL HANDLERS" 4
+.IX Item "SIGNAL HANDLERS"
+.PD
+\&\fBstack-trace\fR, \fBdie\fR, \fBhandler\fR \fIyour-handler\fR
+.IP "SIGNAL LISTS" 4
+.IX Item "SIGNAL LISTS"
+\&\fBnormal-signals\fR, \fBerror-signals\fR, \fBold-interface-signals\fR
+.IP OTHER 4
+.IX Item "OTHER"
+\&\fBuntrapped\fR, \fBany\fR, \fIsignal\fR, \fInumber\fR
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.SS "sort \- perl pragma to control \fBsort()\fP behaviour"
+.IX Subsection "sort - perl pragma to control sort() behaviour"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+.SS "stable \- Experimental features made easy, once we know they're stable"
+.IX Subsection "stable - Experimental features made easy, once we know they're stable"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`bitwise\*(C'\fR \- stable as of perl 5.22, available via stable 0.031, \f(CW\*(C`isa\*(C'\fR \-
+stable as of perl 5.32, available via stable 0.031, \f(CW\*(C`lexical_subs\*(C'\fR \-
+stable as of perl 5.22, available via stable 0.031, \f(CW\*(C`postderef\*(C'\fR \- stable
+as of perl 5.20, available via stable 0.031
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "strict \- Perl pragma to restrict unsafe constructs"
+.IX Subsection "strict - Perl pragma to restrict unsafe constructs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`strict refs\*(C'\fR, \f(CW\*(C`strict vars\*(C'\fR, \f(CW\*(C`strict subs\*(C'\fR
+.IP HISTORY 4
+.IX Item "HISTORY"
+.SS "subs \- Perl pragma to predeclare subroutine names"
+.IX Subsection "subs - Perl pragma to predeclare subroutine names"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "threads \- Perl interpreter-based threads"
+.IX Subsection "threads - Perl interpreter-based threads"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP WARNING 4
+.IX Item "WARNING"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$thr\fR = threads\->create(FUNCTION, ARGS), \f(CW$thr\fR\->\fBjoin()\fR, \f(CW$thr\fR\->\fBdetach()\fR,
+threads\->\fBdetach()\fR, threads\->\fBself()\fR, \f(CW$thr\fR\->\fBtid()\fR, threads\->\fBtid()\fR, "$thr",
+threads\->object($tid), threads\->\fByield()\fR, threads\->\fBlist()\fR,
+threads\->list(threads::all), threads\->list(threads::running),
+threads\->list(threads::joinable), \f(CW$thr1\fR\->equal($thr2), async BLOCK;,
+\&\f(CW$thr\fR\->\fBerror()\fR, \f(CW$thr\fR\->\fB_handle()\fR, threads\->\fB_handle()\fR
+.IP "EXITING A THREAD" 4
+.IX Item "EXITING A THREAD"
+threads\->\fBexit()\fR, threads\->exit(status), \fBdie()\fR, exit(status), use threads
+\&'exit' => 'threads_only', threads\->create({'exit' => 'thread_only'}, ...),
+\&\f(CW$thr\fR\->set_thread_exit_only(boolean), threads\->set_thread_exit_only(boolean)
+.IP "THREAD STATE" 4
+.IX Item "THREAD STATE"
+\&\f(CW$thr\fR\->\fBis_running()\fR, \f(CW$thr\fR\->\fBis_joinable()\fR, \f(CW$thr\fR\->\fBis_detached()\fR,
+threads\->\fBis_detached()\fR
+.IP "THREAD CONTEXT" 4
+.IX Item "THREAD CONTEXT"
+.RS 4
+.PD 0
+.IP "Explicit context" 4
+.IX Item "Explicit context"
+.IP "Implicit context" 4
+.IX Item "Implicit context"
+.ie n .IP $thr\->\fBwantarray()\fR 4
+.el .IP \f(CW$thr\fR\->\fBwantarray()\fR 4
+.IX Item "$thr->wantarray()"
+.IP threads\->\fBwantarray()\fR 4
+.IX Item "threads->wantarray()"
+.RE
+.RS 4
+.RE
+.IP "THREAD STACK SIZE" 4
+.IX Item "THREAD STACK SIZE"
+.PD
+threads\->\fBget_stack_size()\fR;, \f(CW$size\fR = \f(CW$thr\fR\->\fBget_stack_size()\fR;, \f(CW$old_size\fR =
+threads\->set_stack_size($new_size);, use threads ('stack_size' => VALUE);,
+\&\f(CW$ENV\fR{'PERL5_ITHREADS_STACK_SIZE'}, threads\->create({'stack_size' => VALUE},
+FUNCTION, ARGS), \f(CW$thr2\fR = \f(CW$thr1\fR\->create(FUNCTION, ARGS)
+.IP "THREAD SIGNALLING" 4
+.IX Item "THREAD SIGNALLING"
+\&\f(CW$thr\fR\->kill('SIG...');
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+Perl exited with active threads:, Thread creation failed: pthread_create
+returned #, Thread # terminated abnormally: .., Using minimum thread stack
+size of #, Thread creation failed: pthread_attr_setstacksize(\fISIZE\fR)
+returned 22
+.IP ERRORS 4
+.IX Item "ERRORS"
+This Perl not built to support threads, Cannot change stack size of an
+existing thread, Cannot signal threads without safe signals, Unrecognized
+signal name: ..
+.IP "BUGS AND LIMITATIONS" 4
+.IX Item "BUGS AND LIMITATIONS"
+Thread-safe modules, Using non-thread-safe modules, Memory consumption,
+Current working directory, Locales, Environment variables, Catching
+signals, Parent-child threads, Unsafe signals, Perl has been built with
+\&\f(CW\*(C`PERL_OLD_SIGNALS\*(C'\fR (see \f(CW\*(C`perl\ \-V\*(C'\fR), The environment variable
+\&\f(CW\*(C`PERL_SIGNALS\*(C'\fR is set to \f(CW\*(C`unsafe\*(C'\fR (see "PERL_SIGNALS" in perlrun), The
+module Perl::Unsafe::Signals is used, Identity of objects returned from
+threads, Returning blessed objects from threads, END blocks in threads,
+Open directory handles, Detached threads and global destruction, Perl Bugs
+and the CPAN Version of threads
+.IP REQUIREMENTS 4
+.IX Item "REQUIREMENTS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.PD
+.SS "threads::shared \- Perl extension for sharing data structures between threads"
+.IX Subsection "threads::shared - Perl extension for sharing data structures between threads"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+share VARIABLE, shared_clone REF, is_shared VARIABLE, lock VARIABLE,
+cond_wait VARIABLE, cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE,
+ABS_TIMEOUT, cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal
+VARIABLE, cond_broadcast VARIABLE
+.IP OBJECTS 4
+.IX Item "OBJECTS"
+.PD 0
+.IP NOTES 4
+.IX Item "NOTES"
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+.PD
+\&\fBcond_broadcast()\fR called on unlocked variable, \fBcond_signal()\fR called on
+unlocked variable
+.IP "BUGS AND LIMITATIONS" 4
+.IX Item "BUGS AND LIMITATIONS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "utf8 \- Perl pragma to enable/disable UTF\-8 (or UTF-EBCDIC) in source code"
+.IX Subsection "utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Utility functions" 4
+.IX Item "Utility functions"
+.PD
+\&\f(CW\*(C`$num_octets = utf8::upgrade($string)\*(C'\fR, \f(CW\*(C`$success =
+utf8::downgrade($string[, $fail_ok])\*(C'\fR, \f(CWutf8::encode($string)\fR, \f(CW\*(C`$success
+= utf8::decode($string)\*(C'\fR, \f(CW$unicode =
+utf8::native_to_unicode($code_point)\fR, \f(CW$native =
+utf8::unicode_to_native($code_point)\fR, \f(CW\*(C`$flag = utf8::is_utf8($string)\*(C'\fR,
+\&\f(CW\*(C`$flag = utf8::valid($string)\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "vars \- Perl pragma to predeclare global variable names"
+.IX Subsection "vars - Perl pragma to predeclare global variable names"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "version \- Perl extension for Version Objects"
+.IX Subsection "version - Perl extension for Version Objects"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "TYPES OF VERSION OBJECTS" 4
+.IX Item "TYPES OF VERSION OBJECTS"
+.PD
+Decimal Versions, Dotted Decimal Versions
+.IP "DECLARING VERSIONS" 4
+.IX Item "DECLARING VERSIONS"
+.RS 4
+.PD 0
+.IP "How to convert a module from decimal to dotted-decimal" 4
+.IX Item "How to convert a module from decimal to dotted-decimal"
+.ie n .IP "How to declare() a dotted-decimal version" 4
+.el .IP "How to \f(CWdeclare()\fR a dotted-decimal version" 4
+.IX Item "How to declare() a dotted-decimal version"
+.RE
+.RS 4
+.RE
+.IP "PARSING AND COMPARING VERSIONS" 4
+.IX Item "PARSING AND COMPARING VERSIONS"
+.RS 4
+.ie n .IP "How to parse() a version" 4
+.el .IP "How to \f(CWparse()\fR a version" 4
+.IX Item "How to parse() a version"
+.IP "How to check for a legal version string" 4
+.IX Item "How to check for a legal version string"
+.PD
+\&\f(CWis_lax()\fR, \f(CWis_strict()\fR
+.IP "How to compare version objects" 4
+.IX Item "How to compare version objects"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OBJECT METHODS" 4
+.IX Item "OBJECT METHODS"
+.RS 4
+.IP \fBis_alpha()\fR 4
+.IX Item "is_alpha()"
+.IP \fBis_qv()\fR 4
+.IX Item "is_qv()"
+.IP \fBnormal()\fR 4
+.IX Item "normal()"
+.IP \fBnumify()\fR 4
+.IX Item "numify()"
+.IP \fBstringify()\fR 4
+.IX Item "stringify()"
+.RE
+.RS 4
+.RE
+.IP "EXPORTED FUNCTIONS" 4
+.IX Item "EXPORTED FUNCTIONS"
+.RS 4
+.IP \fBqv()\fR 4
+.IX Item "qv()"
+.IP \fBis_lax()\fR 4
+.IX Item "is_lax()"
+.IP \fBis_strict()\fR 4
+.IX Item "is_strict()"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "version::Internals \- Perl extension for Version Objects"
+.IX Subsection "version::Internals - Perl extension for Version Objects"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP "WHAT IS A VERSION?" 4
+.IX Item "WHAT IS A VERSION?"
+.PD
+Decimal versions, Dotted-Decimal versions
+.RS 4
+.IP "Decimal Versions" 4
+.IX Item "Decimal Versions"
+.PD 0
+.IP "Dotted-Decimal Versions" 4
+.IX Item "Dotted-Decimal Versions"
+.IP "Alpha Versions" 4
+.IX Item "Alpha Versions"
+.IP "Regular Expressions for Version Parsing" 4
+.IX Item "Regular Expressions for Version Parsing"
+.PD
+\&\f(CW$version::LAX\fR, \f(CW$version::STRICT\fR, v1.234.5
+.RE
+.RS 4
+.RE
+.IP "IMPLEMENTATION DETAILS" 4
+.IX Item "IMPLEMENTATION DETAILS"
+.RS 4
+.PD 0
+.IP "Equivalence between Decimal and Dotted-Decimal Versions" 4
+.IX Item "Equivalence between Decimal and Dotted-Decimal Versions"
+.IP "Quoting Rules" 4
+.IX Item "Quoting Rules"
+.IP "What about v\-strings?" 4
+.IX Item "What about v-strings?"
+.IP "Version Object Internals" 4
+.IX Item "Version Object Internals"
+.PD
+original, qv, alpha, version
+.IP "Replacement UNIVERSAL::VERSION" 4
+.IX Item "Replacement UNIVERSAL::VERSION"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "USAGE DETAILS" 4
+.IX Item "USAGE DETAILS"
+.RS 4
+.IP "Using modules that use version.pm" 4
+.IX Item "Using modules that use version.pm"
+.PD
+Decimal versions always work, Dotted-Decimal version work sometimes
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\fBnew()\fR, \fBqv()\fR, Normal Form, Numification, Stringification, Comparison
+operators, Logical Operators
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "vmsish \- Perl pragma to control VMS-specific language features"
+.IX Subsection "vmsish - Perl pragma to control VMS-specific language features"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`vmsish status\*(C'\fR, \f(CW\*(C`vmsish exit\*(C'\fR, \f(CW\*(C`vmsish time\*(C'\fR, \f(CW\*(C`vmsish hushed\*(C'\fR
+.SS "warnings \- Perl pragma to control optional warnings"
+.IX Subsection "warnings - Perl pragma to control optional warnings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Default Warnings and Optional Warnings" 4
+.IX Item "Default Warnings and Optional Warnings"
+.IP """Negative warnings""" 4
+.IX Item """Negative warnings"""
+.ie n .IP "What's wrong with \fB\-w\fR and $^W" 4
+.el .IP "What's wrong with \fB\-w\fR and \f(CW$^W\fR" 4
+.IX Item "What's wrong with -w and $^W"
+.IP "Controlling Warnings from the Command Line" 4
+.IX Item "Controlling Warnings from the Command Line"
+.PD
+\&\fB\-w\fR , \fB\-W\fR , \fB\-X\fR
+.IX Xref "-w -W -X"
+.IP "Backward Compatibility" 4
+.IX Item "Backward Compatibility"
+.PD 0
+.IP "Category Hierarchy" 4
+.IX Xref "warning, categories"
+.IX Item "Category Hierarchy"
+.IP "Fatal Warnings" 4
+.IX Xref "warning, fatal"
+.IX Item "Fatal Warnings"
+.IP "Reporting Warnings from a Module" 4
+.IX Xref "warning, reporting warning, registering"
+.IX Item "Reporting Warnings from a Module"
+.RE
+.RS 4
+.RE
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+use warnings::register, \fBwarnings::enabled()\fR, warnings::enabled($category),
+warnings::enabled($object), warnings::enabled_at_level($category, \f(CW$level\fR),
+\&\fBwarnings::fatal_enabled()\fR, warnings::fatal_enabled($category),
+warnings::fatal_enabled($object),
+warnings::fatal_enabled_at_level($category, \f(CW$level\fR),
+warnings::warn($message), warnings::warn($category, \f(CW$message\fR),
+warnings::warn($object, \f(CW$message\fR), warnings::warn_at_level($category,
+\&\f(CW$level\fR, \f(CW$message\fR), warnings::warnif($message), warnings::warnif($category,
+\&\f(CW$message\fR), warnings::warnif($object, \f(CW$message\fR),
+warnings::warnif_at_level($category, \f(CW$level\fR, \f(CW$message\fR),
+warnings::register_categories(@names)
+.SS "warnings::register \- warnings import function"
+.IX Subsection "warnings::register - warnings import function"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SH "MODULE DOCUMENTATION"
+.IX Header "MODULE DOCUMENTATION"
+.SS "AnyDBM_File \- provide framework for multiple DBMs"
+.IX Subsection "AnyDBM_File - provide framework for multiple DBMs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "DBM Comparisons" 4
+.IX Item "DBM Comparisons"
+.PD
+[0], [1], [2], [3]
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "App::Cpan \- easily interact with CPAN from the command line"
+.IX Subsection "App::Cpan - easily interact with CPAN from the command line"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Options 4
+.IX Item "Options"
+.PD
+\&\-a, \-A module [ module ... ], \-c module, \-C module [ module ... ], \-D
+module [ module ... ], \-f, \-F, \-g module [ module ... ], \-G module [ module
+\&... ], \-h, \-i module [ module ... ], \-I, \-j Config.pm, \-J, \-l, \-L author [
+author ... ], \-m, \-M mirror1,mirror2,.., \-n, \-O, \-p, \-P, \-r, \-s, \-t module
+[ module ... ], \-T, \-u, \-v, \-V, \-w, \-x module [ module ... ], \-\fIX\fR
+.IP Examples 4
+.IX Item "Examples"
+.PD 0
+.IP "Environment variables" 4
+.IX Item "Environment variables"
+.PD
+NONINTERACTIVE_TESTING, PERL_MM_USE_DEFAULT, CPAN_OPTS,
+CPANSCRIPT_LOGLEVEL, GIT_COMMAND
+.IP Methods 4
+.IX Item "Methods"
+.RE
+.RS 4
+.RE
+.PP
+run( ARGS )
+.IP "EXIT VALUES" 4
+.IX Item "EXIT VALUES"
+.PD 0
+.IP "TO DO" 4
+.IX Item "TO DO"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "SOURCE AVAILABILITY" 4
+.IX Item "SOURCE AVAILABILITY"
+.IP CREDITS 4
+.IX Item "CREDITS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.ie n .SS "App::Prove \- Implements the ""prove"" command."
+.el .SS "App::Prove \- Implements the \f(CWprove\fP command."
+.IX Subsection "App::Prove - Implements the prove command."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP Attributes 4
+.IX Item "Attributes"
+.PD
+\&\f(CW\*(C`archive\*(C'\fR, \f(CW\*(C`argv\*(C'\fR, \f(CW\*(C`backwards\*(C'\fR, \f(CW\*(C`blib\*(C'\fR, \f(CW\*(C`color\*(C'\fR, \f(CW\*(C`directives\*(C'\fR,
+\&\f(CW\*(C`dry\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`extensions\*(C'\fR, \f(CW\*(C`failures\*(C'\fR, \f(CW\*(C`comments\*(C'\fR, \f(CW\*(C`formatter\*(C'\fR,
+\&\f(CW\*(C`harness\*(C'\fR, \f(CW\*(C`ignore_exit\*(C'\fR, \f(CW\*(C`includes\*(C'\fR, \f(CW\*(C`jobs\*(C'\fR, \f(CW\*(C`lib\*(C'\fR, \f(CW\*(C`merge\*(C'\fR,
+\&\f(CW\*(C`modules\*(C'\fR, \f(CW\*(C`parse\*(C'\fR, \f(CW\*(C`plugins\*(C'\fR, \f(CW\*(C`quiet\*(C'\fR, \f(CW\*(C`really_quiet\*(C'\fR, \f(CW\*(C`recurse\*(C'\fR,
+\&\f(CW\*(C`rules\*(C'\fR, \f(CW\*(C`show_count\*(C'\fR, \f(CW\*(C`show_help\*(C'\fR, \f(CW\*(C`show_man\*(C'\fR, \f(CW\*(C`show_version\*(C'\fR,
+\&\f(CW\*(C`shuffle\*(C'\fR, \f(CW\*(C`state\*(C'\fR, \f(CW\*(C`state_class\*(C'\fR, \f(CW\*(C`taint_fail\*(C'\fR, \f(CW\*(C`taint_warn\*(C'\fR,
+\&\f(CW\*(C`test_args\*(C'\fR, \f(CW\*(C`timer\*(C'\fR, \f(CW\*(C`verbose\*(C'\fR, \f(CW\*(C`warnings_fail\*(C'\fR, \f(CW\*(C`warnings_warn\*(C'\fR,
+\&\f(CW\*(C`tapversion\*(C'\fR, \f(CW\*(C`trap\*(C'\fR
+.IP PLUGINS 4
+.IX Item "PLUGINS"
+.RS 4
+.PD 0
+.IP "Sample Plugin" 4
+.IX Item "Sample Plugin"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.ie n .SS "App::Prove::State \- State storage for the ""prove"" command."
+.el .SS "App::Prove::State \- State storage for the \f(CWprove\fP command."
+.IX Subsection "App::Prove::State - State storage for the prove command."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`store\*(C'\fR, \f(CW\*(C`extensions\*(C'\fR (optional), \f(CW\*(C`result_class\*(C'\fR (optional)
+.RE
+.RS 4
+.RE
+.ie n .IP """result_class""" 4
+.el .IP \f(CWresult_class\fR 4
+.IX Item "result_class"
+.PD 0
+.ie n .IP """extensions""" 4
+.el .IP \f(CWextensions\fR 4
+.IX Item "extensions"
+.ie n .IP """results""" 4
+.el .IP \f(CWresults\fR 4
+.IX Item "results"
+.ie n .IP """commit""" 4
+.el .IP \f(CWcommit\fR 4
+.IX Item "commit"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PD
+\&\f(CW\*(C`last\*(C'\fR, \f(CW\*(C`failed\*(C'\fR, \f(CW\*(C`passed\*(C'\fR, \f(CW\*(C`all\*(C'\fR, \f(CW\*(C`hot\*(C'\fR, \f(CW\*(C`todo\*(C'\fR, \f(CW\*(C`slow\*(C'\fR, \f(CW\*(C`fast\*(C'\fR,
+\&\f(CW\*(C`new\*(C'\fR, \f(CW\*(C`old\*(C'\fR, \f(CW\*(C`save\*(C'\fR
+.SS "App::Prove::State::Result \- Individual test suite results."
+.IX Subsection "App::Prove::State::Result - Individual test suite results."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.ie n .IP """state_version""" 4
+.el .IP \f(CWstate_version\fR 4
+.IX Item "state_version"
+.ie n .IP """test_class""" 4
+.el .IP \f(CWtest_class\fR 4
+.IX Item "test_class"
+.PD
+.SS "App::Prove::State::Result::Test \- Individual test results."
+.IX Subsection "App::Prove::State::Result::Test - Individual test results."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PD
+.SS "Archive::Tar \- module for manipulations of tar archives"
+.IX Subsection "Archive::Tar - module for manipulations of tar archives"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+.RS 4
+.ie n .IP "Archive::Tar\->new( [$file, $compressed] )" 4
+.el .IP "Archive::Tar\->new( [$file, \f(CW$compressed\fR] )" 4
+.IX Item "Archive::Tar->new( [$file, $compressed] )"
+.RE
+.RS 4
+.RE
+.ie n .IP "$tar\->read ( $filename|$handle, [$compressed, {opt => 'val'}] )" 4
+.el .IP "\f(CW$tar\fR\->read ( \f(CW$filename\fR|$handle, [$compressed, {opt => 'val'}] )" 4
+.IX Item "$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )"
+.PD
+limit, filter, md5, extract
+.ie n .IP "$tar\->contains_file( $filename )" 4
+.el .IP "\f(CW$tar\fR\->contains_file( \f(CW$filename\fR )" 4
+.IX Item "$tar->contains_file( $filename )"
+.PD 0
+.ie n .IP "$tar\->extract( [@filenames] )" 4
+.el .IP "\f(CW$tar\fR\->extract( [@filenames] )" 4
+.IX Item "$tar->extract( [@filenames] )"
+.ie n .IP "$tar\->extract_file( $file, [$extract_path] )" 4
+.el .IP "\f(CW$tar\fR\->extract_file( \f(CW$file\fR, [$extract_path] )" 4
+.IX Item "$tar->extract_file( $file, [$extract_path] )"
+.ie n .IP "$tar\->list_files( [\e@properties] )" 4
+.el .IP "\f(CW$tar\fR\->list_files( [\e@properties] )" 4
+.IX Item "$tar->list_files( [@properties] )"
+.ie n .IP "$tar\->get_files( [@filenames] )" 4
+.el .IP "\f(CW$tar\fR\->get_files( [@filenames] )" 4
+.IX Item "$tar->get_files( [@filenames] )"
+.ie n .IP "$tar\->get_content( $file )" 4
+.el .IP "\f(CW$tar\fR\->get_content( \f(CW$file\fR )" 4
+.IX Item "$tar->get_content( $file )"
+.ie n .IP "$tar\->replace_content( $file, $content )" 4
+.el .IP "\f(CW$tar\fR\->replace_content( \f(CW$file\fR, \f(CW$content\fR )" 4
+.IX Item "$tar->replace_content( $file, $content )"
+.ie n .IP "$tar\->rename( $file, $new_name )" 4
+.el .IP "\f(CW$tar\fR\->rename( \f(CW$file\fR, \f(CW$new_name\fR )" 4
+.IX Item "$tar->rename( $file, $new_name )"
+.ie n .IP "$tar\->chmod( $file, $mode )" 4
+.el .IP "\f(CW$tar\fR\->chmod( \f(CW$file\fR, \f(CW$mode\fR )" 4
+.IX Item "$tar->chmod( $file, $mode )"
+.ie n .IP "$tar\->chown( $file, $uname [, $gname] )" 4
+.el .IP "\f(CW$tar\fR\->chown( \f(CW$file\fR, \f(CW$uname\fR [, \f(CW$gname\fR] )" 4
+.IX Item "$tar->chown( $file, $uname [, $gname] )"
+.ie n .IP "$tar\->remove (@filenamelist)" 4
+.el .IP "\f(CW$tar\fR\->remove (@filenamelist)" 4
+.IX Item "$tar->remove (@filenamelist)"
+.ie n .IP $tar\->clear 4
+.el .IP \f(CW$tar\fR\->clear 4
+.IX Item "$tar->clear"
+.ie n .IP "$tar\->write ( [$file, $compressed, $prefix] )" 4
+.el .IP "\f(CW$tar\fR\->write ( [$file, \f(CW$compressed\fR, \f(CW$prefix\fR] )" 4
+.IX Item "$tar->write ( [$file, $compressed, $prefix] )"
+.ie n .IP "$tar\->add_files( @filenamelist )" 4
+.el .IP "\f(CW$tar\fR\->add_files( \f(CW@filenamelist\fR )" 4
+.IX Item "$tar->add_files( @filenamelist )"
+.ie n .IP "$tar\->add_data ( $filename, $data, [$opthashref] )" 4
+.el .IP "\f(CW$tar\fR\->add_data ( \f(CW$filename\fR, \f(CW$data\fR, [$opthashref] )" 4
+.IX Item "$tar->add_data ( $filename, $data, [$opthashref] )"
+.PD
+FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET
+.ie n .IP "$tar\->error( [$BOOL] )" 4
+.el .IP "\f(CW$tar\fR\->error( [$BOOL] )" 4
+.IX Item "$tar->error( [$BOOL] )"
+.PD 0
+.ie n .IP "$tar\->setcwd( $cwd );" 4
+.el .IP "\f(CW$tar\fR\->setcwd( \f(CW$cwd\fR );" 4
+.IX Item "$tar->setcwd( $cwd );"
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RS 4
+.ie n .IP "Archive::Tar\->create_archive($file, $compressed, @filelist)" 4
+.el .IP "Archive::Tar\->create_archive($file, \f(CW$compressed\fR, \f(CW@filelist\fR)" 4
+.IX Item "Archive::Tar->create_archive($file, $compressed, @filelist)"
+.RE
+.RS 4
+.RE
+.ie n .IP "Archive::Tar\->iter( $filename, [ $compressed, {opt => $val} ] )" 4
+.el .IP "Archive::Tar\->iter( \f(CW$filename\fR, [ \f(CW$compressed\fR, {opt => \f(CW$val\fR} ] )" 4
+.IX Item "Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )"
+.ie n .IP "Archive::Tar\->list_archive($file, $compressed, [\e@properties])" 4
+.el .IP "Archive::Tar\->list_archive($file, \f(CW$compressed\fR, [\e@properties])" 4
+.IX Item "Archive::Tar->list_archive($file, $compressed, [@properties])"
+.ie n .IP "Archive::Tar\->extract_archive($file, $compressed)" 4
+.el .IP "Archive::Tar\->extract_archive($file, \f(CW$compressed\fR)" 4
+.IX Item "Archive::Tar->extract_archive($file, $compressed)"
+.ie n .IP "$bool = Archive::Tar\->has_io_string" 4
+.el .IP "\f(CW$bool\fR = Archive::Tar\->has_io_string" 4
+.IX Item "$bool = Archive::Tar->has_io_string"
+.ie n .IP "$bool = Archive::Tar\->has_perlio" 4
+.el .IP "\f(CW$bool\fR = Archive::Tar\->has_perlio" 4
+.IX Item "$bool = Archive::Tar->has_perlio"
+.ie n .IP "$bool = Archive::Tar\->has_zlib_support" 4
+.el .IP "\f(CW$bool\fR = Archive::Tar\->has_zlib_support" 4
+.IX Item "$bool = Archive::Tar->has_zlib_support"
+.ie n .IP "$bool = Archive::Tar\->has_bzip2_support" 4
+.el .IP "\f(CW$bool\fR = Archive::Tar\->has_bzip2_support" 4
+.IX Item "$bool = Archive::Tar->has_bzip2_support"
+.ie n .IP "$bool = Archive::Tar\->has_xz_support" 4
+.el .IP "\f(CW$bool\fR = Archive::Tar\->has_xz_support" 4
+.IX Item "$bool = Archive::Tar->has_xz_support"
+.IP Archive::Tar\->can_handle_compressed_files 4
+.IX Item "Archive::Tar->can_handle_compressed_files"
+.IP "GLOBAL VARIABLES" 4
+.IX Item "GLOBAL VARIABLES"
+.RS 4
+.ie n .IP $Archive::Tar::FOLLOW_SYMLINK 4
+.el .IP \f(CW$Archive::Tar::FOLLOW_SYMLINK\fR 4
+.IX Item "$Archive::Tar::FOLLOW_SYMLINK"
+.ie n .IP $Archive::Tar::CHOWN 4
+.el .IP \f(CW$Archive::Tar::CHOWN\fR 4
+.IX Item "$Archive::Tar::CHOWN"
+.ie n .IP $Archive::Tar::CHMOD 4
+.el .IP \f(CW$Archive::Tar::CHMOD\fR 4
+.IX Item "$Archive::Tar::CHMOD"
+.ie n .IP $Archive::Tar::SAME_PERMISSIONS 4
+.el .IP \f(CW$Archive::Tar::SAME_PERMISSIONS\fR 4
+.IX Item "$Archive::Tar::SAME_PERMISSIONS"
+.ie n .IP $Archive::Tar::DO_NOT_USE_PREFIX 4
+.el .IP \f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR 4
+.IX Item "$Archive::Tar::DO_NOT_USE_PREFIX"
+.ie n .IP $Archive::Tar::DEBUG 4
+.el .IP \f(CW$Archive::Tar::DEBUG\fR 4
+.IX Item "$Archive::Tar::DEBUG"
+.ie n .IP $Archive::Tar::WARN 4
+.el .IP \f(CW$Archive::Tar::WARN\fR 4
+.IX Item "$Archive::Tar::WARN"
+.ie n .IP $Archive::Tar::error 4
+.el .IP \f(CW$Archive::Tar::error\fR 4
+.IX Item "$Archive::Tar::error"
+.ie n .IP $Archive::Tar::INSECURE_EXTRACT_MODE 4
+.el .IP \f(CW$Archive::Tar::INSECURE_EXTRACT_MODE\fR 4
+.IX Item "$Archive::Tar::INSECURE_EXTRACT_MODE"
+.ie n .IP $Archive::Tar::HAS_PERLIO 4
+.el .IP \f(CW$Archive::Tar::HAS_PERLIO\fR 4
+.IX Item "$Archive::Tar::HAS_PERLIO"
+.ie n .IP $Archive::Tar::HAS_IO_STRING 4
+.el .IP \f(CW$Archive::Tar::HAS_IO_STRING\fR 4
+.IX Item "$Archive::Tar::HAS_IO_STRING"
+.ie n .IP $Archive::Tar::ZERO_PAD_NUMBERS 4
+.el .IP \f(CW$Archive::Tar::ZERO_PAD_NUMBERS\fR 4
+.IX Item "$Archive::Tar::ZERO_PAD_NUMBERS"
+.IP "Tuning the way RESOLVE_SYMLINK will works" 4
+.IX Item "Tuning the way RESOLVE_SYMLINK will works"
+.RE
+.RS 4
+.RE
+.IP FAQ 4
+.IX Item "FAQ"
+.PD
+What's the minimum perl version required to run Archive::Tar?, Isn't
+Archive::Tar slow?, Isn't Archive::Tar heavier on memory than /bin/tar?,
+Can you lazy-load data instead?, How much memory will an X kb tar file
+need?, What do you do with unsupported filetypes in an archive?, I'm using
+WinZip, or some other non-POSIX client, and files are not being extracted
+properly!, How do I extract only files that have property X from an
+archive?, How do I access .tar.Z files?, How do I handle Unicode strings?
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP TODO 4
+.IX Item "TODO"
+.PD
+Check if passed in handles are open for read/write, Allow archives to be
+passed in as string, Facilitate processing an opened filehandle of a
+compressed archive
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+The GNU tar specification, The PAX format specification, A comparison of
+GNU and POSIX tar standards;
+\&\f(CW\*(C`http://www.delorie.com/gnu/docs/tar/tar_114.html\*(C'\fR, GNU tar intends to
+switch to POSIX compatibility, A Comparison between various tar
+implementations
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Archive::Tar::File \- a subclass for in-memory extracted file from Archive::Tar"
+.IX Subsection "Archive::Tar::File - a subclass for in-memory extracted file from Archive::Tar"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Accessors 4
+.IX Item "Accessors"
+.PD
+name, mode, uid, gid, size, mtime, chksum, type, linkname, magic, version,
+uname, gname, devmajor, devminor, prefix, raw
+.RE
+.RS 4
+.RE
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.PD 0
+.ie n .IP "Archive::Tar::File\->new( file => $path )" 4
+.el .IP "Archive::Tar::File\->new( file => \f(CW$path\fR )" 4
+.IX Item "Archive::Tar::File->new( file => $path )"
+.ie n .IP "Archive::Tar::File\->new( data => $path, $data, $opt )" 4
+.el .IP "Archive::Tar::File\->new( data => \f(CW$path\fR, \f(CW$data\fR, \f(CW$opt\fR )" 4
+.IX Item "Archive::Tar::File->new( data => $path, $data, $opt )"
+.ie n .IP "Archive::Tar::File\->new( chunk => $chunk )" 4
+.el .IP "Archive::Tar::File\->new( chunk => \f(CW$chunk\fR )" 4
+.IX Item "Archive::Tar::File->new( chunk => $chunk )"
+.RE
+.RS 4
+.RE
+.ie n .IP "$bool = $file\->extract( [ $alternative_name ] )" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->extract( [ \f(CW$alternative_name\fR ] )" 4
+.IX Item "$bool = $file->extract( [ $alternative_name ] )"
+.ie n .IP "$path = $file\->full_path" 4
+.el .IP "\f(CW$path\fR = \f(CW$file\fR\->full_path" 4
+.IX Item "$path = $file->full_path"
+.ie n .IP "$bool = $file\->validate" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->validate" 4
+.IX Item "$bool = $file->validate"
+.ie n .IP "$bool = $file\->has_content" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->has_content" 4
+.IX Item "$bool = $file->has_content"
+.ie n .IP "$content = $file\->get_content" 4
+.el .IP "\f(CW$content\fR = \f(CW$file\fR\->get_content" 4
+.IX Item "$content = $file->get_content"
+.ie n .IP "$cref = $file\->get_content_by_ref" 4
+.el .IP "\f(CW$cref\fR = \f(CW$file\fR\->get_content_by_ref" 4
+.IX Item "$cref = $file->get_content_by_ref"
+.ie n .IP "$bool = $file\->replace_content( $content )" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->replace_content( \f(CW$content\fR )" 4
+.IX Item "$bool = $file->replace_content( $content )"
+.ie n .IP "$bool = $file\->rename( $new_name )" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->rename( \f(CW$new_name\fR )" 4
+.IX Item "$bool = $file->rename( $new_name )"
+.ie n .IP "$bool = $file\->chmod $mode)" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->chmod \f(CW$mode\fR)" 4
+.IX Item "$bool = $file->chmod $mode)"
+.ie n .IP "$bool = $file\->chown( $user [, $group])" 4
+.el .IP "\f(CW$bool\fR = \f(CW$file\fR\->chown( \f(CW$user\fR [, \f(CW$group\fR])" 4
+.IX Item "$bool = $file->chown( $user [, $group])"
+.IP "Convenience methods" 4
+.IX Item "Convenience methods"
+.PD
+\&\f(CW$file\fR\->is_file, \f(CW$file\fR\->is_dir, \f(CW$file\fR\->is_hardlink, \f(CW$file\fR\->is_symlink,
+\&\f(CW$file\fR\->is_chardev, \f(CW$file\fR\->is_blockdev, \f(CW$file\fR\->is_fifo, \f(CW$file\fR\->is_socket,
+\&\f(CW$file\fR\->is_longlink, \f(CW$file\fR\->is_label, \f(CW$file\fR\->is_unknown
+.SS "Attribute::Handlers \- Simpler definition of attribute handlers"
+.IX Subsection "Attribute::Handlers - Simpler definition of attribute handlers"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+[0], [1], [2], [3], [4], [5], [6], [7]
+.RS 4
+.IP "Typed lexicals" 4
+.IX Item "Typed lexicals"
+.PD 0
+.IP "Type-specific attribute handlers" 4
+.IX Item "Type-specific attribute handlers"
+.IP "Non-interpretive attribute handlers" 4
+.IX Item "Non-interpretive attribute handlers"
+.IP "Phase-specific attribute handlers" 4
+.IX Item "Phase-specific attribute handlers"
+.ie n .IP "Attributes as ""tie"" interfaces" 4
+.el .IP "Attributes as \f(CWtie\fR interfaces" 4
+.IX Item "Attributes as tie interfaces"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP "UTILITY FUNCTIONS" 4
+.IX Item "UTILITY FUNCTIONS"
+.PD
+findsym
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+\&\f(CW\*(C`Bad attribute type: ATTR(%s)\*(C'\fR, \f(CW\*(C`Attribute handler %s doesn\*(Aqt handle %s
+attributes\*(C'\fR, \f(CW\*(C`Declaration of %s attribute in package %s may clash with
+future reserved word\*(C'\fR, \f(CW\*(C`Can\*(Aqt have two ATTR specifiers on one subroutine\*(C'\fR,
+\&\f(CW\*(C`Can\*(Aqt autotie a %s\*(C'\fR, \f(CW\*(C`Internal error: %s symbol went missing\*(C'\fR, \f(CW\*(C`Won\*(Aqt
+be able to apply END handler\*(C'\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "AutoLoader \- load subroutines only on demand"
+.IX Subsection "AutoLoader - load subroutines only on demand"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Subroutine Stubs" 4
+.IX Item "Subroutine Stubs"
+.IP "Using \fBAutoLoader\fR's AUTOLOAD Subroutine" 4
+.IX Item "Using AutoLoader's AUTOLOAD Subroutine"
+.IP "Overriding \fBAutoLoader\fR's AUTOLOAD Subroutine" 4
+.IX Item "Overriding AutoLoader's AUTOLOAD Subroutine"
+.IP "Package Lexicals" 4
+.IX Item "Package Lexicals"
+.IP "Not Using AutoLoader" 4
+.IX Item "Not Using AutoLoader"
+.IP "\fBAutoLoader\fR vs. \fBSelfLoader\fR" 4
+.IX Item "AutoLoader vs. SelfLoader"
+.IP "Forcing AutoLoader to Load a Function" 4
+.IX Item "Forcing AutoLoader to Load a Function"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "AutoSplit \- split a package for autoloading"
+.IX Subsection "AutoSplit - split a package for autoloading"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$keep\fR, \f(CW$check\fR, \f(CW$modtime\fR
+.RS 4
+.IP "Multiple packages" 4
+.IX Item "Multiple packages"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "B \- The Perl Compiler Backend"
+.IX Subsection "B - The Perl Compiler Backend"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OVERVIEW 4
+.IX Item "OVERVIEW"
+.IP "Utility Functions" 4
+.IX Item "Utility Functions"
+.RS 4
+.ie n .IP "Functions Returning ""B::SV"", ""B::AV"", ""B::HV"", and ""B::CV"" objects" 4
+.el .IP "Functions Returning \f(CWB::SV\fR, \f(CWB::AV\fR, \f(CWB::HV\fR, and \f(CWB::CV\fR objects" 4
+.IX Item "Functions Returning B::SV, B::AV, B::HV, and B::CV objects"
+.PD
+sv_undef, sv_yes, sv_no, svref_2object(SVREF), amagic_generation, init_av,
+check_av, unitcheck_av, begin_av, end_av, comppadlist, regex_padav, main_cv
+.IP "Functions for Examining the Symbol Table" 4
+.IX Item "Functions for Examining the Symbol Table"
+walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
+.ie n .IP "Functions Returning ""B::OP"" objects or for walking op trees" 4
+.el .IP "Functions Returning \f(CWB::OP\fR objects or for walking op trees" 4
+.IX Item "Functions Returning B::OP objects or for walking op trees"
+main_root, main_start, walkoptree(OP, METHOD), walkoptree_debug(DEBUG)
+.IP "Miscellaneous Utility Functions" 4
+.IX Item "Miscellaneous Utility Functions"
+ppname(OPNUM), hash(STR), cast_I32(I), minus_c, cstring(STR),
+perlstring(STR), safename(STR), class(OBJ), threadsv_names
+.IP "Exported utility variables" 4
+.IX Item "Exported utility variables"
+\&\f(CW@optype\fR, \f(CW@specialsv_name\fR
+.RE
+.RS 4
+.RE
+.IP "OVERVIEW OF CLASSES" 4
+.IX Item "OVERVIEW OF CLASSES"
+.RS 4
+.PD 0
+.IP "SV-RELATED CLASSES" 4
+.IX Item "SV-RELATED CLASSES"
+.IP "B::SV Methods" 4
+.IX Item "B::SV Methods"
+.PD
+REFCNT, FLAGS, IsBOOL, object_2svref, TRUE, TRUE_nomg
+.IP "B::IV Methods" 4
+.IX Item "B::IV Methods"
+IV, IVX, UVX, int_value, needs64bits, packiv
+.IP "B::NV Methods" 4
+.IX Item "B::NV Methods"
+NV, NVX, COP_SEQ_RANGE_LOW, COP_SEQ_RANGE_HIGH
+.IP "B::RV Methods" 4
+.IX Item "B::RV Methods"
+RV
+.IP "B::PV Methods" 4
+.IX Item "B::PV Methods"
+PV, RV, PVX, CUR, LEN
+.IP "B::PVMG Methods" 4
+.IX Item "B::PVMG Methods"
+MAGIC, SvSTASH
+.IP "B::MAGIC Methods" 4
+.IX Item "B::MAGIC Methods"
+MOREMAGIC, precomp, PRIVATE, TYPE, FLAGS, OBJ, PTR, REGEX
+.IP "B::INVLIST Methods" 4
+.IX Item "B::INVLIST Methods"
+prev_index, is_offset, array_len, get_invlist_array
+.IP "B::PVLV Methods" 4
+.IX Item "B::PVLV Methods"
+TARGOFF, TARGLEN, TYPE, TARG
+.IP "B::BM Methods" 4
+.IX Item "B::BM Methods"
+USEFUL, PREVIOUS, RARE, TABLE
+.IP "B::REGEXP Methods" 4
+.IX Item "B::REGEXP Methods"
+REGEX, precomp, qr_anoncv, compflags
+.IP "B::GV Methods" 4
+.IX Item "B::GV Methods"
+is_empty, NAME, SAFENAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN,
+LINE, FILE, FILEGV, GvREFCNT, FLAGS, GPFLAGS
+.IP "B::IO Methods" 4
+.IX Item "B::IO Methods"
+LINES, PAGE, PAGE_LEN, LINES_LEFT, TOP_NAME, TOP_GV, FMT_NAME, FMT_GV,
+BOTTOM_NAME, BOTTOM_GV, SUBPROCESS, IoTYPE, IoFLAGS, IsSTD
+.IP "B::AV Methods" 4
+.IX Item "B::AV Methods"
+FILL, MAX, ARRAY, ARRAYelt
+.IP "B::CV Methods" 4
+.IX Item "B::CV Methods"
+STASH, START, ROOT, GV, FILE, DEPTH, PADLIST, OUTSIDE, OUTSIDE_SEQ, XSUB,
+XSUBANY, CvFLAGS, const_sv, NAME_HEK
+.IP "B::HV Methods" 4
+.IX Item "B::HV Methods"
+FILL, MAX, KEYS, RITER, NAME, ARRAY
+.IP "OP-RELATED CLASSES" 4
+.IX Item "OP-RELATED CLASSES"
+.PD 0
+.IP "B::OP Methods" 4
+.IX Item "B::OP Methods"
+.PD
+next, sibling, parent, name, ppaddr, desc, targ, type, opt, flags, private,
+spare
+.IP "B::UNOP Method" 4
+.IX Item "B::UNOP Method"
+first
+.IP "B::UNOP_AUX Methods (since 5.22)" 4
+.IX Item "B::UNOP_AUX Methods (since 5.22)"
+aux_list(cv), string(cv)
+.IP "B::BINOP Method" 4
+.IX Item "B::BINOP Method"
+last
+.IP "B::LOGOP Method" 4
+.IX Item "B::LOGOP Method"
+other
+.IP "B::LISTOP Method" 4
+.IX Item "B::LISTOP Method"
+children
+.IP "B::PMOP Methods" 4
+.IX Item "B::PMOP Methods"
+pmreplroot, pmreplstart, pmflags, precomp, pmoffset, code_list, pmregexp
+.IP "B::SVOP Methods" 4
+.IX Item "B::SVOP Methods"
+sv, gv
+.IP "B::PADOP Method" 4
+.IX Item "B::PADOP Method"
+padix
+.IP "B::PVOP Method" 4
+.IX Item "B::PVOP Method"
+pv
+.IP "B::LOOP Methods" 4
+.IX Item "B::LOOP Methods"
+redoop, nextop, lastop
+.IP "B::COP Methods" 4
+.IX Item "B::COP Methods"
+label, stash, stashpv, stashoff (threaded only), file, cop_seq, line,
+warnings, io, hints, hints_hash
+.IP "B::METHOP Methods (Since Perl 5.22)" 4
+.IX Item "B::METHOP Methods (Since Perl 5.22)"
+first, meth_sv
+.IP "PAD-RELATED CLASSES" 4
+.IX Item "PAD-RELATED CLASSES"
+.PD 0
+.IP "B::PADLIST Methods" 4
+.IX Item "B::PADLIST Methods"
+.PD
+MAX, ARRAY, ARRAYelt, NAMES, REFCNT, id, outid
+.IP "B::PADNAMELIST Methods" 4
+.IX Item "B::PADNAMELIST Methods"
+MAX, ARRAY, ARRAYelt, REFCNT
+.IP "B::PADNAME Methods" 4
+.IX Item "B::PADNAME Methods"
+PV, PVX, LEN, REFCNT, GEN, FLAGS, TYPE, SvSTASH, OURSTASH, PROTOCV,
+COP_SEQ_RANGE_LOW, COP_SEQ_RANGE_HIGH, PARENT_PAD_INDEX,
+PARENT_FAKELEX_FLAGS, IsUndef
+.ie n .IP $B::overlay 4
+.el .IP \f(CW$B::overlay\fR 4
+.IX Item "$B::overlay"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "B::Concise \- Walk Perl syntax tree, printing concise info about ops"
+.IX Subsection "B::Concise - Walk Perl syntax tree, printing concise info about ops"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RS 4
+.IP "Options for Opcode Ordering" 4
+.IX Item "Options for Opcode Ordering"
+.PD
+\&\fB\-basic\fR, \fB\-exec\fR, \fB\-tree\fR
+.IP "Options for Line-Style" 4
+.IX Item "Options for Line-Style"
+\&\fB\-concise\fR, \fB\-terse\fR, \fB\-linenoise\fR, \fB\-debug\fR, \fB\-env\fR
+.IP "Options for tree-specific formatting" 4
+.IX Item "Options for tree-specific formatting"
+\&\fB\-compact\fR, \fB\-loose\fR, \fB\-vt\fR, \fB\-ascii\fR
+.IP "Options controlling sequence numbering" 4
+.IX Item "Options controlling sequence numbering"
+\&\fB\-base\fR\fIn\fR, \fB\-bigendian\fR, \fB\-littleendian\fR
+.IP "Other options" 4
+.IX Item "Other options"
+\&\fB\-src\fR, \fB\-stash="somepackage"\fR, \fB\-main\fR, \fB\-nomain\fR, \fB\-nobanner\fR,
+\&\fB\-banner\fR, \fB\-banneris\fR => subref
+.IP "Option Stickiness" 4
+.IX Item "Option Stickiness"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP ABBREVIATIONS 4
+.IX Item "ABBREVIATIONS"
+.RS 4
+.IP "OP class abbreviations" 4
+.IX Item "OP class abbreviations"
+.IP "OP flags abbreviations" 4
+.IX Item "OP flags abbreviations"
+.RE
+.RS 4
+.RE
+.IP "FORMATTING SPECIFICATIONS" 4
+.IX Item "FORMATTING SPECIFICATIONS"
+.RS 4
+.IP "Special Patterns" 4
+.IX Item "Special Patterns"
+.PD
+\&\fB(x(\fR\fIexec_text\fR\fB;\fR\fIbasic_text\fR\fB)x)\fR, \fB(*(\fR\fItext\fR\fB)*)\fR,
+\&\fB(*(\fR\fItext1\fR\fB;\fR\fItext2\fR\fB)*)\fR, \fB(?(\fR\fItext1\fR\fB#\fR\fIvar\fR\fIText2\fR\fB)?)\fR,
+\&\fB~\fR
+.IP "# Variables" 4
+.IX Item "# Variables"
+\&\fB#\fR\fIvar\fR, \fB#\fR\fIvar\fR\fIN\fR, \fB#\fR\fIVar\fR, \fB#addr\fR, \fB#arg\fR, \fB#class\fR,
+\&\fB#classsym\fR, \fB#coplabel\fR, \fB#exname\fR, \fB#extarg\fR, \fB#firstaddr\fR,
+\&\fB#flags\fR, \fB#flagval\fR, \fB#hints\fR, \fB#hintsval\fR, \fB#hyphseq\fR, \fB#label\fR,
+\&\fB#lastaddr\fR, \fB#name\fR, \fB#NAME\fR, \fB#next\fR, \fB#nextaddr\fR, \fB#noise\fR,
+\&\fB#private\fR, \fB#privval\fR, \fB#seq\fR, \fB#opt\fR, \fB#sibaddr\fR, \fB#svaddr\fR,
+\&\fB#svclass\fR, \fB#svval\fR, \fB#targ\fR, \fB#targarg\fR, \fB#targarglife\fR, \fB#typenum\fR
+.RE
+.RS 4
+.RE
+.IP "One-Liner Command tips" 4
+.IX Item "One-Liner Command tips"
+perl \-MO=Concise,bar foo.pl, perl \-MDigest::MD5=md5 \-MO=Concise,md5 \-e1,
+perl \-MPOSIX \-MO=Concise,_POSIX_ARG_MAX \-e1, perl \-MPOSIX \-MO=Concise,a \-e
+\&'print _POSIX_SAVED_IDS', perl \-MPOSIX \-MO=Concise,a \-e 'sub
+a{_POSIX_SAVED_IDS}', perl \-MB::Concise \-e
+\&'B::Concise::compile("\-exec","\-src", \e%B::Concise::)\->()'
+.IP "Using B::Concise outside of the O framework" 4
+.IX Item "Using B::Concise outside of the O framework"
+.RS 4
+.PD 0
+.IP "Example: Altering Concise Renderings" 4
+.IX Item "Example: Altering Concise Renderings"
+.IP \fBset_style()\fR 4
+.IX Item "set_style()"
+.IP set_style_standard($name) 4
+.IX Item "set_style_standard($name)"
+.IP "add_style ()" 4
+.IX Item "add_style ()"
+.IP "add_callback ()" 4
+.IX Item "add_callback ()"
+.IP "Running \fBB::Concise::compile()\fR" 4
+.IX Item "Running B::Concise::compile()"
+.IP \fBB::Concise::reset_sequence()\fR 4
+.IX Item "B::Concise::reset_sequence()"
+.IP Errors 4
+.IX Item "Errors"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "B::Deparse \- Perl compiler backend to produce perl code"
+.IX Subsection "B::Deparse - Perl compiler backend to produce perl code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.PD
+\&\fB\-d\fR, \fB\-f\fR\fIFILE\fR, \fB\-l\fR, \fB\-p\fR, \fB\-P\fR, \fB\-q\fR, \fB\-s\fR\fILETTERS\fR, \fBC\fR,
+\&\fBi\fR\fINUMBER\fR, \fBT\fR, \fBv\fR\fISTRING\fR\fB.\fR, \fB\-x\fR\fILEVEL\fR
+.IP "USING B::Deparse AS A MODULE" 4
+.IX Item "USING B::Deparse AS A MODULE"
+.RS 4
+.PD 0
+.IP Synopsis 4
+.IX Item "Synopsis"
+.IP Description 4
+.IX Item "Description"
+.IP new 4
+.IX Item "new"
+.IP ambient_pragmas 4
+.IX Item "ambient_pragmas"
+.PD
+strict, $[, bytes, utf8, integer, re, warnings, hint_bits, warning_bits,
+%^H
+.IP coderef2text 4
+.IX Item "coderef2text"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "B::Op_private \- OP op_private flag definitions"
+.IX Subsection "B::Op_private - OP op_private flag definitions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP %bits 4
+.el .IP \f(CW%bits\fR 4
+.IX Item "%bits"
+.ie n .IP %defines 4
+.el .IP \f(CW%defines\fR 4
+.IX Item "%defines"
+.ie n .IP %labels 4
+.el .IP \f(CW%labels\fR 4
+.IX Item "%labels"
+.ie n .IP %ops_using 4
+.el .IP \f(CW%ops_using\fR 4
+.IX Item "%ops_using"
+.RE
+.RS 4
+.RE
+.PD
+.SS "B::Showlex \- Show lexical variables used in functions or files"
+.IX Subsection "B::Showlex - Show lexical variables used in functions or files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP TODO 4
+.IX Item "TODO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "B::Terse \- Walk Perl syntax tree, printing terse info about ops"
+.IX Subsection "B::Terse - Walk Perl syntax tree, printing terse info about ops"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "B::Xref \- Generates cross reference reports for Perl programs"
+.IX Subsection "B::Xref - Generates cross reference reports for Perl programs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+i, &, s, r
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+\&\f(CW\*(C`\-oFILENAME\*(C'\fR, \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR, \f(CW\*(C`\-D[tO]\*(C'\fR
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Benchmark \- benchmark running times of Perl code"
+.IX Subsection "Benchmark - benchmark running times of Perl code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Methods 4
+.IX Item "Methods"
+.PD
+new, debug, iters
+.IP "Standard Exports" 4
+.IX Item "Standard Exports"
+timeit(COUNT, CODE), timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] ),
+timethese ( COUNT, CODEHASHREF, [ STYLE ] ), timediff ( T1, T2 ), timestr (
+TIMEDIFF, [ STYLE, [ FORMAT ] ] )
+.IP "Optional Exports" 4
+.IX Item "Optional Exports"
+clearcache ( COUNT ), clearallcache ( ), cmpthese ( COUNT, CODEHASHREF, [
+STYLE ] ), cmpthese ( RESULTSHASHREF, [ STYLE ] ), countit(TIME, CODE),
+disablecache ( ), enablecache ( ), timesum ( T1, T2 )
+.IP :hireswallclock 4
+.IX Item ":hireswallclock"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Benchmark Object" 4
+.IX Item "Benchmark Object"
+.PD
+cpu_p, cpu_c, cpu_a, real, iters
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP INHERITANCE 4
+.IX Item "INHERITANCE"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.PD
+.SS "CORE \- Namespace for Perl's core routines"
+.IX Subsection "CORE - Namespace for Perl's core routines"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDING CORE FUNCTIONS" 4
+.IX Item "OVERRIDING CORE FUNCTIONS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "CPAN \- query, download and build perl modules from CPAN sites"
+.IX Subsection "CPAN - query, download and build perl modules from CPAN sites"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "CPAN::shell([$prompt, $command]) Starting Interactive Mode" 4
+.el .IP "CPAN::shell([$prompt, \f(CW$command\fR]) Starting Interactive Mode" 4
+.IX Item "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
+.PD
+Searching for authors, bundles, distribution files and modules, \f(CW\*(C`get\*(C'\fR,
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, \f(CW\*(C`install\*(C'\fR, \f(CW\*(C`clean\*(C'\fR modules or distributions, \f(CW\*(C`readme\*(C'\fR,
+\&\f(CW\*(C`perldoc\*(C'\fR, \f(CW\*(C`look\*(C'\fR module or distribution, \f(CW\*(C`ls\*(C'\fR author, \f(CW\*(C`ls\*(C'\fR
+globbing_expression, \f(CW\*(C`failed\*(C'\fR, Persistence between sessions, The \f(CW\*(C`force\*(C'\fR
+and the \f(CW\*(C`fforce\*(C'\fR pragma, Lockfile, Signals
+.IP CPAN::Shell 4
+.IX Item "CPAN::Shell"
+.PD 0
+.IP autobundle 4
+.IX Item "autobundle"
+.IP hosts 4
+.IX Item "hosts"
+.PD
+install_tested, is_tested
+.IP mkmyconfig 4
+.IX Item "mkmyconfig"
+.PD 0
+.IP "r [Module|/Regexp/]..." 4
+.IX Item "r [Module|/Regexp/]..."
+.IP "recent ***EXPERIMENTAL COMMAND***" 4
+.IX Item "recent ***EXPERIMENTAL COMMAND***"
+.IP recompile 4
+.IX Item "recompile"
+.IP "report Bundle|Distribution|Module" 4
+.IX Item "report Bundle|Distribution|Module"
+.IP "smoke ***EXPERIMENTAL COMMAND***" 4
+.IX Item "smoke ***EXPERIMENTAL COMMAND***"
+.IP "upgrade [Module|/Regexp/]..." 4
+.IX Item "upgrade [Module|/Regexp/]..."
+.ie n .IP "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution" 4
+.el .IP "The four \f(CWCPAN::*\fR Classes: Author, Bundle, Module, Distribution" 4
+.IX Item "The four CPAN::* Classes: Author, Bundle, Module, Distribution"
+.IP "Integrating local directories" 4
+.IX Item "Integrating local directories"
+.IP Redirection 4
+.IX Item "Redirection"
+.IP "Plugin support ***EXPERIMENTAL***" 4
+.IX Item "Plugin support ***EXPERIMENTAL***"
+.RE
+.RS 4
+.RE
+.IP CONFIGURATION 4
+.IX Item "CONFIGURATION"
+.PD
+completion support, displaying some help: o conf help, displaying current
+values: o conf [KEY], changing of scalar values: o conf KEY VALUE, changing
+of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST, reverting to
+saved: o conf defaults, saving the config: o conf commit
+.RS 4
+.IP "Config Variables" 4
+.IX Item "Config Variables"
+\&\f(CW\*(C`o conf <scalar option>\*(C'\fR, \f(CW\*(C`o conf <scalar option>
+<value>\*(C'\fR, \f(CW\*(C`o conf <list option>\*(C'\fR, \f(CW\*(C`o conf <list
+option> [shift|pop]\*(C'\fR, \f(CW\*(C`o conf <list option>
+[unshift|push|splice] <list>\*(C'\fR, interactive editing: o conf init
+[MATCH|LIST]
+.IP "CPAN::anycwd($path): Note on config variable getcwd" 4
+.IX Item "CPAN::anycwd($path): Note on config variable getcwd"
+cwd, getcwd, fastcwd, getdcwd, backtickcwd
+.IP "Note on the format of the urllist parameter" 4
+.IX Item "Note on the format of the urllist parameter"
+.PD 0
+.IP "The urllist parameter has CD-ROM support" 4
+.IX Item "The urllist parameter has CD-ROM support"
+.IP "Maintaining the urllist parameter" 4
+.IX Item "Maintaining the urllist parameter"
+.ie n .IP "The ""requires"" and ""build_requires"" dependency declarations" 4
+.el .IP "The \f(CWrequires\fR and \f(CWbuild_requires\fR dependency declarations" 4
+.IX Item "The requires and build_requires dependency declarations"
+.IP "Configuration of the allow_installing_* parameters" 4
+.IX Item "Configuration of the allow_installing_* parameters"
+.IP "Configuration for individual distributions (\fIDistroprefs\fR)" 4
+.IX Item "Configuration for individual distributions (Distroprefs)"
+.IP Filenames 4
+.IX Item "Filenames"
+.IP "Fallback Data::Dumper and Storable" 4
+.IX Item "Fallback Data::Dumper and Storable"
+.IP Blueprint 4
+.IX Item "Blueprint"
+.IP "Language Specs" 4
+.IX Item "Language Specs"
+.PD
+comment [scalar], cpanconfig [hash], depends [hash] *** EXPERIMENTAL
+FEATURE ***, disabled [boolean], features [array] *** EXPERIMENTAL FEATURE
+***, goto [string], install [hash], make [hash], match [hash], patches
+[array], pl [hash], test [hash]
+.IP "Processing Instructions" 4
+.IX Item "Processing Instructions"
+args [array], commandline, eexpect [hash], env [hash], expect [array]
+.ie n .IP "Schema verification with ""Kwalify""" 4
+.el .IP "Schema verification with \f(CWKwalify\fR" 4
+.IX Item "Schema verification with Kwalify"
+.PD 0
+.IP "Example Distroprefs Files" 4
+.IX Item "Example Distroprefs Files"
+.RE
+.RS 4
+.RE
+.IP "PROGRAMMER'S INTERFACE" 4
+.IX Item "PROGRAMMER'S INTERFACE"
+.PD
+expand($type,@things), expandany(@things), Programming Examples
+.RS 4
+.IP "Methods in the other Classes" 4
+.IX Item "Methods in the other Classes"
+\&\fBCPAN::Author::as_glimpse()\fR, \fBCPAN::Author::as_string()\fR,
+\&\fBCPAN::Author::email()\fR, \fBCPAN::Author::fullname()\fR, \fBCPAN::Author::name()\fR,
+\&\fBCPAN::Bundle::as_glimpse()\fR, \fBCPAN::Bundle::as_string()\fR,
+\&\fBCPAN::Bundle::clean()\fR, \fBCPAN::Bundle::contains()\fR,
+CPAN::Bundle::force($method,@args), \fBCPAN::Bundle::get()\fR,
+\&\fBCPAN::Bundle::inst_file()\fR, \fBCPAN::Bundle::inst_version()\fR,
+\&\fBCPAN::Bundle::uptodate()\fR, \fBCPAN::Bundle::install()\fR, \fBCPAN::Bundle::make()\fR,
+\&\fBCPAN::Bundle::readme()\fR, \fBCPAN::Bundle::test()\fR,
+\&\fBCPAN::Distribution::as_glimpse()\fR, \fBCPAN::Distribution::as_string()\fR,
+CPAN::Distribution::author, \fBCPAN::Distribution::pretty_id()\fR,
+\&\fBCPAN::Distribution::base_id()\fR, \fBCPAN::Distribution::clean()\fR,
+\&\fBCPAN::Distribution::containsmods()\fR, \fBCPAN::Distribution::cvs_import()\fR,
+\&\fBCPAN::Distribution::dir()\fR, CPAN::Distribution::force($method,@args),
+\&\fBCPAN::Distribution::get()\fR, \fBCPAN::Distribution::install()\fR,
+\&\fBCPAN::Distribution::isa_perl()\fR, \fBCPAN::Distribution::look()\fR,
+\&\fBCPAN::Distribution::make()\fR, \fBCPAN::Distribution::perldoc()\fR,
+\&\fBCPAN::Distribution::prefs()\fR, \fBCPAN::Distribution::prereq_pm()\fR,
+\&\fBCPAN::Distribution::readme()\fR, \fBCPAN::Distribution::reports()\fR,
+\&\fBCPAN::Distribution::read_yaml()\fR, \fBCPAN::Distribution::test()\fR,
+\&\fBCPAN::Distribution::uptodate()\fR, \fBCPAN::Index::force_reload()\fR,
+\&\fBCPAN::Index::reload()\fR, \fBCPAN::InfoObj::dump()\fR, \fBCPAN::Module::as_glimpse()\fR,
+\&\fBCPAN::Module::as_string()\fR, \fBCPAN::Module::clean()\fR,
+\&\fBCPAN::Module::cpan_file()\fR, \fBCPAN::Module::cpan_version()\fR,
+\&\fBCPAN::Module::cvs_import()\fR, \fBCPAN::Module::description()\fR,
+\&\fBCPAN::Module::distribution()\fR, \fBCPAN::Module::dslip_status()\fR,
+CPAN::Module::force($method,@args), \fBCPAN::Module::get()\fR,
+\&\fBCPAN::Module::inst_file()\fR, \fBCPAN::Module::available_file()\fR,
+\&\fBCPAN::Module::inst_version()\fR, \fBCPAN::Module::available_version()\fR,
+\&\fBCPAN::Module::install()\fR, \fBCPAN::Module::look()\fR, \fBCPAN::Module::make()\fR,
+\&\fBCPAN::Module::manpage_headline()\fR, \fBCPAN::Module::perldoc()\fR,
+\&\fBCPAN::Module::readme()\fR, \fBCPAN::Module::reports()\fR, \fBCPAN::Module::test()\fR,
+\&\fBCPAN::Module::uptodate()\fR, \fBCPAN::Module::userid()\fR
+.IP "Cache Manager" 4
+.IX Item "Cache Manager"
+.PD 0
+.IP Bundles 4
+.IX Item "Bundles"
+.RE
+.RS 4
+.RE
+.IP PREREQUISITES 4
+.IX Item "PREREQUISITES"
+.IP UTILITIES 4
+.IX Item "UTILITIES"
+.RS 4
+.IP "Finding packages and VERSION" 4
+.IX Item "Finding packages and VERSION"
+.IP Debugging 4
+.IX Item "Debugging"
+.PD
+o debug package.., o debug \-package.., o debug all, o debug number
+.IP "Floppy, Zip, Offline Mode" 4
+.IX Item "Floppy, Zip, Offline Mode"
+.PD 0
+.IP "Basic Utilities for Programmers" 4
+.IX Item "Basic Utilities for Programmers"
+.PD
+has_inst($module), use_inst($module), has_usable($module),
+instance($module), \fBfrontend()\fR, frontend($new_frontend)
+.RE
+.RS 4
+.RE
+.IP SECURITY 4
+.IX Item "SECURITY"
+.RS 4
+.PD 0
+.IP "Cryptographically signed modules" 4
+.IX Item "Cryptographically signed modules"
+.RE
+.RS 4
+.RE
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.IP "POPULATE AN INSTALLATION WITH LOTS OF MODULES" 4
+.IX Item "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
+.IP "WORKING WITH CPAN.pm BEHIND FIREWALLS" 4
+.IX Item "WORKING WITH CPAN.pm BEHIND FIREWALLS"
+.RS 4
+.IP "Three basic types of firewalls" 4
+.IX Item "Three basic types of firewalls"
+.PD
+http firewall, ftp firewall, One-way visibility, SOCKS, IP Masquerade
+.IP "Configuring lynx or ncftp for going through a firewall" 4
+.IX Item "Configuring lynx or ncftp for going through a firewall"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP FAQ 4
+.IX Item "FAQ"
+.PD
+1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11), 12), 13), 14), 15), 16), 17),
+18), 19)
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.RS 4
+.PD 0
+.IP "OLD PERL VERSIONS" 4
+.IX Item "OLD PERL VERSIONS"
+.IP CPANPLUS 4
+.IX Item "CPANPLUS"
+.IP CPANMINUS 4
+.IX Item "CPANMINUS"
+.RE
+.RS 4
+.RE
+.IP "SECURITY ADVICE" 4
+.IX Item "SECURITY ADVICE"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP TRANSLATIONS 4
+.IX Item "TRANSLATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "CPAN::API::HOWTO \- a recipe book for programming with CPAN.pm"
+.IX Subsection "CPAN::API::HOWTO - a recipe book for programming with CPAN.pm"
+.IP RECIPES 4
+.IX Item "RECIPES"
+.RS 4
+.PD 0
+.IP "What distribution contains a particular module?" 4
+.IX Item "What distribution contains a particular module?"
+.IP "What modules does a particular distribution contain?" 4
+.IX Item "What modules does a particular distribution contain?"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "CPAN::Debug \- internal debugging for CPAN.pm"
+.IX Subsection "CPAN::Debug - internal debugging for CPAN.pm"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.SS "CPAN::Distroprefs \-\- read and match distroprefs"
+.IX Subsection "CPAN::Distroprefs -- read and match distroprefs"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP INTERFACE 4
+.IX Item "INTERFACE"
+.PD
+a CPAN::Distroprefs::Result object, \f(CW\*(C`undef\*(C'\fR, indicating that no prefs
+files remain to be found
+.IP RESULTS 4
+.IX Item "RESULTS"
+.RS 4
+.PD 0
+.IP Common 4
+.IX Item "Common"
+.IP Errors 4
+.IX Item "Errors"
+.IP Successes 4
+.IX Item "Successes"
+.RE
+.RS 4
+.RE
+.IP PREFS 4
+.IX Item "PREFS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "CPAN::FirstTime \- Utility for CPAN::Config file Initialization"
+.IX Subsection "CPAN::FirstTime - Utility for CPAN::Config file Initialization"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+allow_installing_module_downgrades, allow_installing_outdated_dists,
+auto_commit, build_cache, build_dir, build_dir_reuse,
+build_requires_install_policy, cache_metadata, check_sigs,
+cleanup_after_install, colorize_output, colorize_print, colorize_warn,
+colorize_debug, commandnumber_in_prompt, connect_to_internet_ok,
+ftp_passive, ftpstats_period, ftpstats_size, getcwd, halt_on_failure,
+histfile, histsize, inactivity_timeout, index_expire,
+inhibit_startup_message, keep_source_where, load_module_verbosity,
+makepl_arg, make_arg, make_install_arg, make_install_make_command,
+mbuildpl_arg, mbuild_arg, mbuild_install_arg, mbuild_install_build_command,
+pager, prefer_installer, prefs_dir, prerequisites_policy, pushy_https,
+randomize_urllist, recommends_policy, scan_cache, shell,
+show_unparsable_versions, show_upload_date, show_zero_versions,
+suggests_policy, tar_verbosity, term_is_latin, term_ornaments, test_report,
+perl5lib_verbosity, prefer_external_tar, trust_test_report_history,
+urllist_ping_external, urllist_ping_verbose, use_prompt_default,
+use_sqlite, version_timeout, yaml_load_code, yaml_module
+.IP LICENSE 4
+.IX Item "LICENSE"
+.SS "CPAN::HandleConfig \- internal configuration handling for CPAN.pm"
+.IX Subsection "CPAN::HandleConfig - internal configuration handling for CPAN.pm"
+.PD 0
+.ie n .IP """CLASS\->safe_quote ITEM""" 4
+.el .IP "\f(CWCLASS\->safe_quote ITEM\fR" 4
+.IX Item "CLASS->safe_quote ITEM"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "CPAN::Kwalify \- Interface between CPAN.pm and Kwalify.pm"
+.IX Subsection "CPAN::Kwalify - Interface between CPAN.pm and Kwalify.pm"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+_validate($schema_name, \f(CW$data\fR, \f(CW$file\fR, \f(CW$doc\fR), yaml($schema_name)
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "CPAN::Meta \- the distribution metadata for a CPAN dist"
+.IX Subsection "CPAN::Meta - the distribution metadata for a CPAN dist"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP create 4
+.IX Item "create"
+.IP load_file 4
+.IX Item "load_file"
+.IP load_yaml_string 4
+.IX Item "load_yaml_string"
+.IP load_json_string 4
+.IX Item "load_json_string"
+.IP load_string 4
+.IX Item "load_string"
+.IP save 4
+.IX Item "save"
+.IP meta_spec_version 4
+.IX Item "meta_spec_version"
+.IP effective_prereqs 4
+.IX Item "effective_prereqs"
+.IP should_index_file 4
+.IX Item "should_index_file"
+.IP should_index_package 4
+.IX Item "should_index_package"
+.IP features 4
+.IX Item "features"
+.IP feature 4
+.IX Item "feature"
+.IP as_struct 4
+.IX Item "as_struct"
+.IP as_string 4
+.IX Item "as_string"
+.RE
+.RS 4
+.RE
+.IP "STRING DATA" 4
+.IX Item "STRING DATA"
+.IP "LIST DATA" 4
+.IX Item "LIST DATA"
+.IP "MAP DATA" 4
+.IX Item "MAP DATA"
+.IP "CUSTOM DATA" 4
+.IX Item "CUSTOM DATA"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.RS 4
+.IP "Bugs / Feature Requests" 4
+.IX Item "Bugs / Feature Requests"
+.IP "Source Code" 4
+.IX Item "Source Code"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Converter \- Convert CPAN distribution metadata structures"
+.IX Subsection "CPAN::Meta::Converter - Convert CPAN distribution metadata structures"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP convert 4
+.IX Item "convert"
+.IP upgrade_fragment 4
+.IX Item "upgrade_fragment"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Feature \- an optional feature provided by a CPAN distribution"
+.IX Subsection "CPAN::Meta::Feature - an optional feature provided by a CPAN distribution"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP identifier 4
+.IX Item "identifier"
+.IP description 4
+.IX Item "description"
+.IP prereqs 4
+.IX Item "prereqs"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::History \- history of CPAN Meta Spec changes"
+.IX Subsection "CPAN::Meta::History - history of CPAN Meta Spec changes"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.RS 4
+.IP "Version 2" 4
+.IX Item "Version 2"
+.IP "Version 1.4" 4
+.IX Item "Version 1.4"
+.IP "Version 1.3" 4
+.IX Item "Version 1.3"
+.IP "Version 1.2" 4
+.IX Item "Version 1.2"
+.IP "Version 1.1" 4
+.IX Item "Version 1.1"
+.IP "Version 1.0" 4
+.IX Item "Version 1.0"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::History::Meta_1_0 \- Version 1.0 metadata specification for META.yml"
+.IX Subsection "CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml"
+.IP PREFACE 4
+.IX Item "PREFACE"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Format 4
+.IX Item "Format"
+.IP Fields 4
+.IX Item "Fields"
+.PD
+name, version, license, perl, gpl, lgpl, artistic, bsd, open_source,
+unrestricted, restrictive, distribution_type, requires, recommends,
+build_requires, conflicts, dynamic_config, generated_by
+.IP "Related Projects" 4
+.IX Item "Related Projects"
+DOAP
+.IP History 4
+.IX Item "History"
+.SS "CPAN::Meta::History::Meta_1_1 \- Version 1.1 metadata specification for META.yml"
+.IX Subsection "CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml"
+.PD 0
+.IP PREFACE 4
+.IX Item "PREFACE"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Format 4
+.IX Item "Format"
+.IP Fields 4
+.IX Item "Fields"
+.PD
+name, version, license, perl, gpl, lgpl, artistic, bsd, open_source,
+unrestricted, restrictive, license_uri, distribution_type, private,
+requires, recommends, build_requires, conflicts, dynamic_config,
+generated_by
+.RS 4
+.IP "Ingy's suggestions" 4
+.IX Item "Ingy's suggestions"
+short_description, description, maturity, author_id, owner_id,
+categorization, keyword, chapter_id, URL for further information,
+namespaces
+.RE
+.RS 4
+.RE
+.IP History 4
+.IX Item "History"
+.SS "CPAN::Meta::History::Meta_1_2 \- Version 1.2 metadata specification for META.yml"
+.IX Subsection "CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for META.yml"
+.PD 0
+.IP PREFACE 4
+.IX Item "PREFACE"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FORMAT 4
+.IX Item "FORMAT"
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.PD
+distribution, module
+.IP "VERSION SPECIFICATIONS" 4
+.IX Item "VERSION SPECIFICATIONS"
+.PD 0
+.IP HEADER 4
+.IX Item "HEADER"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.RS 4
+.IP meta-spec 4
+.IX Item "meta-spec"
+.IP name 4
+.IX Item "name"
+.IP version 4
+.IX Item "version"
+.IP abstract 4
+.IX Item "abstract"
+.IP author 4
+.IX Item "author"
+.IP license 4
+.IX Item "license"
+.PD
+perl, gpl, lgpl, artistic, bsd, open_source, unrestricted, restrictive
+.IP distribution_type 4
+.IX Item "distribution_type"
+.PD 0
+.IP requires 4
+.IX Item "requires"
+.IP recommends 4
+.IX Item "recommends"
+.IP build_requires 4
+.IX Item "build_requires"
+.IP conflicts 4
+.IX Item "conflicts"
+.IP dynamic_config 4
+.IX Item "dynamic_config"
+.IP private 4
+.IX Item "private"
+.IP provides 4
+.IX Item "provides"
+.IP no_index 4
+.IX Item "no_index"
+.IP keywords 4
+.IX Item "keywords"
+.IP resources 4
+.IX Item "resources"
+.PD
+homepage, license, bugtracker
+.IP generated_by 4
+.IX Item "generated_by"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+March 14, 2003 (Pi day), May 8, 2003, November 13, 2003, November 16, 2003,
+December 9, 2003, December 15, 2003, July 26, 2005, August 23, 2005
+.SS "CPAN::Meta::History::Meta_1_3 \- Version 1.3 metadata specification for META.yml"
+.IX Subsection "CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for META.yml"
+.IP PREFACE 4
+.IX Item "PREFACE"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FORMAT 4
+.IX Item "FORMAT"
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.PD
+distribution, module
+.IP HEADER 4
+.IX Item "HEADER"
+.PD 0
+.IP FIELDS 4
+.IX Item "FIELDS"
+.RS 4
+.IP meta-spec 4
+.IX Item "meta-spec"
+.IP name 4
+.IX Item "name"
+.IP version 4
+.IX Item "version"
+.IP abstract 4
+.IX Item "abstract"
+.IP author 4
+.IX Item "author"
+.IP license 4
+.IX Item "license"
+.PD
+apache, artistic, bsd, gpl, lgpl, mit, mozilla, open_source, perl,
+restrictive, unrestricted
+.IP distribution_type 4
+.IX Item "distribution_type"
+.PD 0
+.IP requires 4
+.IX Item "requires"
+.IP recommends 4
+.IX Item "recommends"
+.IP build_requires 4
+.IX Item "build_requires"
+.IP conflicts 4
+.IX Item "conflicts"
+.IP dynamic_config 4
+.IX Item "dynamic_config"
+.IP private 4
+.IX Item "private"
+.IP provides 4
+.IX Item "provides"
+.IP no_index 4
+.IX Item "no_index"
+.IP keywords 4
+.IX Item "keywords"
+.IP resources 4
+.IX Item "resources"
+.PD
+homepage, license, bugtracker
+.IP generated_by 4
+.IX Item "generated_by"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "VERSION SPECIFICATIONS" 4
+.IX Item "VERSION SPECIFICATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+March 14, 2003 (Pi day), May 8, 2003, November 13, 2003, November 16, 2003,
+December 9, 2003, December 15, 2003, July 26, 2005, August 23, 2005
+.SS "CPAN::Meta::History::Meta_1_4 \- Version 1.4 metadata specification for META.yml"
+.IX Subsection "CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for META.yml"
+.IP PREFACE 4
+.IX Item "PREFACE"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FORMAT 4
+.IX Item "FORMAT"
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.PD
+distribution, module
+.IP HEADER 4
+.IX Item "HEADER"
+.PD 0
+.IP FIELDS 4
+.IX Item "FIELDS"
+.RS 4
+.IP meta-spec 4
+.IX Item "meta-spec"
+.IP name 4
+.IX Item "name"
+.IP version 4
+.IX Item "version"
+.IP abstract 4
+.IX Item "abstract"
+.IP author 4
+.IX Item "author"
+.IP license 4
+.IX Item "license"
+.PD
+apache, artistic, bsd, gpl, lgpl, mit, mozilla, open_source, perl,
+restrictive, unrestricted
+.IP distribution_type 4
+.IX Item "distribution_type"
+.PD 0
+.IP requires 4
+.IX Item "requires"
+.IP recommends 4
+.IX Item "recommends"
+.IP build_requires 4
+.IX Item "build_requires"
+.IP configure_requires 4
+.IX Item "configure_requires"
+.IP conflicts 4
+.IX Item "conflicts"
+.IP dynamic_config 4
+.IX Item "dynamic_config"
+.IP private 4
+.IX Item "private"
+.IP provides 4
+.IX Item "provides"
+.IP no_index 4
+.IX Item "no_index"
+.IP keywords 4
+.IX Item "keywords"
+.IP resources 4
+.IX Item "resources"
+.PD
+homepage, license, bugtracker
+.IP generated_by 4
+.IX Item "generated_by"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "VERSION SPECIFICATIONS" 4
+.IX Item "VERSION SPECIFICATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+March 14, 2003 (Pi day), May 8, 2003, November 13, 2003, November 16, 2003,
+December 9, 2003, December 15, 2003, July 26, 2005, August 23, 2005, June
+12, 2007
+.SS "CPAN::Meta::Merge \- Merging CPAN Meta fragments"
+.IX Subsection "CPAN::Meta::Merge - Merging CPAN Meta fragments"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP merge(@fragments) 4
+.IX Item "merge(@fragments)"
+.RE
+.RS 4
+.RE
+.IP "MERGE STRATEGIES" 4
+.IX Item "MERGE STRATEGIES"
+.PD
+identical, set_addition, uniq_map, improvise
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD 0
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Prereqs \- a set of distribution prerequisites by phase and type"
+.IX Subsection "CPAN::Meta::Prereqs - a set of distribution prerequisites by phase and type"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP requirements_for 4
+.IX Item "requirements_for"
+.IP phases 4
+.IX Item "phases"
+.IP types_in 4
+.IX Item "types_in"
+.IP with_merged_prereqs 4
+.IX Item "with_merged_prereqs"
+.IP merged_requirements 4
+.IX Item "merged_requirements"
+.IP as_string_hash 4
+.IX Item "as_string_hash"
+.IP is_finalized 4
+.IX Item "is_finalized"
+.IP finalize 4
+.IX Item "finalize"
+.IP clone 4
+.IX Item "clone"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Requirements \- a set of version requirements for a CPAN dist"
+.IX Subsection "CPAN::Meta::Requirements - a set of version requirements for a CPAN dist"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP add_minimum 4
+.IX Item "add_minimum"
+.IP add_maximum 4
+.IX Item "add_maximum"
+.IP add_exclusion 4
+.IX Item "add_exclusion"
+.IP exact_version 4
+.IX Item "exact_version"
+.IP add_requirements 4
+.IX Item "add_requirements"
+.IP accepts_module 4
+.IX Item "accepts_module"
+.IP clear_requirement 4
+.IX Item "clear_requirement"
+.IP requirements_for_module 4
+.IX Item "requirements_for_module"
+.IP structured_requirements_for_module 4
+.IX Item "structured_requirements_for_module"
+.IP required_modules 4
+.IX Item "required_modules"
+.IP clone 4
+.IX Item "clone"
+.IP is_simple 4
+.IX Item "is_simple"
+.IP is_finalized 4
+.IX Item "is_finalized"
+.IP finalize 4
+.IX Item "finalize"
+.IP as_string_hash 4
+.IX Item "as_string_hash"
+.IP add_string_requirement 4
+.IX Item "add_string_requirement"
+.PD
+>= 1.3, <= 1.3, != 1.3, > 1.3, < 1.3, >= 1.3, != 1.5, <= 2.0
+.IP from_string_hash 4
+.IX Item "from_string_hash"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.RS 4
+.IP "Bugs / Feature Requests" 4
+.IX Item "Bugs / Feature Requests"
+.IP "Source Code" 4
+.IX Item "Source Code"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Spec \- specification for CPAN distribution metadata"
+.IX Subsection "CPAN::Meta::Spec - specification for CPAN distribution metadata"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.PD
+distribution, module, package, consumer, producer, must, should, may, etc
+.IP "DATA TYPES" 4
+.IX Item "DATA TYPES"
+.RS 4
+.PD 0
+.IP Boolean 4
+.IX Item "Boolean"
+.IP String 4
+.IX Item "String"
+.IP List 4
+.IX Item "List"
+.IP Map 4
+.IX Item "Map"
+.IP "License String" 4
+.IX Item "License String"
+.IP URL 4
+.IX Item "URL"
+.IP Version 4
+.IX Item "Version"
+.IP "Version Range" 4
+.IX Item "Version Range"
+.RE
+.RS 4
+.RE
+.IP STRUCTURE 4
+.IX Item "STRUCTURE"
+.RS 4
+.IP "REQUIRED FIELDS" 4
+.IX Item "REQUIRED FIELDS"
+.PD
+version, url, stable, testing, unstable
+.IP "OPTIONAL FIELDS" 4
+.IX Item "OPTIONAL FIELDS"
+file, directory, package, namespace, description, prereqs, file, version,
+homepage, license, bugtracker, repository
+.IP "DEPRECATED FIELDS" 4
+.IX Item "DEPRECATED FIELDS"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "VERSION NUMBERS" 4
+.IX Item "VERSION NUMBERS"
+.RS 4
+.IP "Version Formats" 4
+.IX Item "Version Formats"
+.PD
+Decimal versions, Dotted-integer versions
+.IP "Version Ranges" 4
+.IX Item "Version Ranges"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP PREREQUISITES 4
+.IX Item "PREREQUISITES"
+.RS 4
+.IP "Prereq Spec" 4
+.IX Item "Prereq Spec"
+.PD
+configure, build, test, runtime, develop, requires, recommends, suggests,
+conflicts
+.IP "Merging and Resolving Prerequisites" 4
+.IX Item "Merging and Resolving Prerequisites"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP SERIALIZATION 4
+.IX Item "SERIALIZATION"
+.IP "NOTES FOR IMPLEMENTORS" 4
+.IX Item "NOTES FOR IMPLEMENTORS"
+.RS 4
+.IP "Extracting Version Numbers from Perl Modules" 4
+.IX Item "Extracting Version Numbers from Perl Modules"
+.IP "Comparing Version Numbers" 4
+.IX Item "Comparing Version Numbers"
+.IP "Prerequisites for dynamically configured distributions" 4
+.IX Item "Prerequisites for dynamically configured distributions"
+.IP "Indexing distributions a la PAUSE" 4
+.IX Item "Indexing distributions a la PAUSE"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::Validator \- validate CPAN distribution metadata structures"
+.IX Subsection "CPAN::Meta::Validator - validate CPAN distribution metadata structures"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP is_valid 4
+.IX Item "is_valid"
+.IP errors 4
+.IX Item "errors"
+.IP "Check Methods" 4
+.IX Item "Check Methods"
+.IP "Validator Methods" 4
+.IX Item "Validator Methods"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "CPAN::Meta::YAML \- Read and write a subset of YAML for CPAN Meta files"
+.IX Subsection "CPAN::Meta::YAML - Read and write a subset of YAML for CPAN Meta files"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+new( LOCAL_FILE_NAME )
+.PP
+\&\fBcontinents()\fR
+.PP
+countries( [CONTINENTS] )
+.PP
+mirrors( [COUNTRIES] )
+.PP
+get_mirrors_by_countries( [COUNTRIES] )
+.PP
+get_mirrors_by_continents( [CONTINENTS] )
+.PP
+get_countries_by_continents( [CONTINENTS] )
+.PP
+default_mirror
+.PP
+best_mirrors
+.PP
+get_n_random_mirrors_by_continents( N, [CONTINENTS] )
+.PP
+get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, \f(CW%ARGS\fR );
+.PP
+find_best_continents( HASH_REF );
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "CPAN::Nox \- Wrapper around CPAN.pm without using any XS module"
+.IX Subsection "CPAN::Nox - Wrapper around CPAN.pm without using any XS module"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "CPAN::Plugin \- Base class for CPAN shell extensions"
+.IX Subsection "CPAN::Plugin - Base class for CPAN shell extensions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Alpha Status" 4
+.IX Item "Alpha Status"
+.IP "How Plugins work?" 4
+.IX Item "How Plugins work?"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP plugin_requires 4
+.IX Item "plugin_requires"
+.IP distribution_object 4
+.IX Item "distribution_object"
+.IP distribution 4
+.IX Item "distribution"
+.IP distribution_info 4
+.IX Item "distribution_info"
+.IP build_dir 4
+.IX Item "build_dir"
+.IP is_xs 4
+.IX Item "is_xs"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "CPAN::Plugin::Specfile \- Proof of concept implementation of a trivial CPAN::Plugin"
+.IX Subsection "CPAN::Plugin::Specfile - Proof of concept implementation of a trivial CPAN::Plugin"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "CPAN::Queue \- internal queue support for CPAN.pm"
+.IX Subsection "CPAN::Queue - internal queue support for CPAN.pm"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.SS "CPAN::Tarzip \- internal handling of tar archives for CPAN.pm"
+.IX Subsection "CPAN::Tarzip - internal handling of tar archives for CPAN.pm"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "CPAN::Version \- utility functions to compare CPAN versions"
+.IX Subsection "CPAN::Version - utility functions to compare CPAN versions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Carp \- alternative warn and die for modules"
+.IX Subsection "Carp - alternative warn and die for modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Forcing a Stack Trace" 4
+.IX Item "Forcing a Stack Trace"
+.IP "Stack Trace formatting" 4
+.IX Item "Stack Trace formatting"
+.RE
+.RS 4
+.RE
+.IP "GLOBAL VARIABLES" 4
+.IX Item "GLOBAL VARIABLES"
+.RS 4
+.ie n .IP $Carp::MaxEvalLen 4
+.el .IP \f(CW$Carp::MaxEvalLen\fR 4
+.IX Item "$Carp::MaxEvalLen"
+.ie n .IP $Carp::MaxArgLen 4
+.el .IP \f(CW$Carp::MaxArgLen\fR 4
+.IX Item "$Carp::MaxArgLen"
+.ie n .IP $Carp::MaxArgNums 4
+.el .IP \f(CW$Carp::MaxArgNums\fR 4
+.IX Item "$Carp::MaxArgNums"
+.ie n .IP $Carp::Verbose 4
+.el .IP \f(CW$Carp::Verbose\fR 4
+.IX Item "$Carp::Verbose"
+.ie n .IP $Carp::RefArgFormatter 4
+.el .IP \f(CW$Carp::RefArgFormatter\fR 4
+.IX Item "$Carp::RefArgFormatter"
+.ie n .IP @CARP_NOT 4
+.el .IP \f(CW@CARP_NOT\fR 4
+.IX Item "@CARP_NOT"
+.ie n .IP %Carp::Internal 4
+.el .IP \f(CW%Carp::Internal\fR 4
+.IX Item "%Carp::Internal"
+.ie n .IP %Carp::CarpInternal 4
+.el .IP \f(CW%Carp::CarpInternal\fR 4
+.IX Item "%Carp::CarpInternal"
+.ie n .IP $Carp::CarpLevel 4
+.el .IP \f(CW$Carp::CarpLevel\fR 4
+.IX Item "$Carp::CarpLevel"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP CONTRIBUTING 4
+.IX Item "CONTRIBUTING"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Class::Struct \- declare struct-like datatypes as Perl classes"
+.IX Subsection "Class::Struct - declare struct-like datatypes as Perl classes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "The struct() function" 4
+.el .IP "The \f(CWstruct()\fR function" 4
+.IX Item "The struct() function"
+.IP "Class Creation at Compile Time" 4
+.IX Item "Class Creation at Compile Time"
+.IP "Element Types and Accessor Methods" 4
+.IX Item "Element Types and Accessor Methods"
+.PD
+Scalar (\f(CW\*(Aq$\*(Aq\fR or \f(CW\*(Aq*$\*(Aq\fR), Array (\f(CW\*(Aq@\*(Aq\fR or \f(CW\*(Aq*@\*(Aq\fR), Hash (\f(CW\*(Aq%\*(Aq\fR or
+\&\f(CW\*(Aq*%\*(Aq\fR), Class (\f(CW\*(AqClass_Name\*(Aq\fR or \f(CW\*(Aq*Class_Name\*(Aq\fR)
+.ie n .IP "Initializing with ""new""" 4
+.el .IP "Initializing with \f(CWnew\fR" 4
+.IX Item "Initializing with new"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD
+Example 1, Example 2, Example 3
+.IP "Author and Modification History" 4
+.IX Item "Author and Modification History"
+.SS "Compress::Raw::Bzip2 \- Low-Level Interface to bzip2 compression library"
+.IX Subsection "Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Compression 4
+.IX Item "Compression"
+.RS 4
+.ie n .IP "($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;" 4
+.el .IP "($z, \f(CW$status\fR) = new Compress::Raw::Bzip2 \f(CW$appendOutput\fR, \f(CW$blockSize100k\fR, \f(CW$workfactor\fR;" 4
+.IX Item "($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;"
+.PD
+\&\fR\f(CB$appendOutput\fR\fB\fR, \fB\fR\f(CB$blockSize100k\fR\fB\fR, \fB\fR\f(CB$workfactor\fR\fB\fR
+.ie n .IP "$status = $bz\->bzdeflate($input, $output);" 4
+.el .IP "\f(CW$status\fR = \f(CW$bz\fR\->bzdeflate($input, \f(CW$output\fR);" 4
+.IX Item "$status = $bz->bzdeflate($input, $output);"
+.PD 0
+.ie n .IP "$status = $bz\->bzflush($output);" 4
+.el .IP "\f(CW$status\fR = \f(CW$bz\fR\->bzflush($output);" 4
+.IX Item "$status = $bz->bzflush($output);"
+.ie n .IP "$status = $bz\->bzclose($output);" 4
+.el .IP "\f(CW$status\fR = \f(CW$bz\fR\->bzclose($output);" 4
+.IX Item "$status = $bz->bzclose($output);"
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP Uncompression 4
+.IX Item "Uncompression"
+.RS 4
+.ie n .IP "($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;" 4
+.el .IP "($z, \f(CW$status\fR) = new Compress::Raw::Bunzip2 \f(CW$appendOutput\fR, \f(CW$consumeInput\fR, \f(CW$small\fR, \f(CW$verbosity\fR, \f(CW$limitOutput\fR;" 4
+.IX Item "($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;"
+.PD
+\&\fR\f(CB$appendOutput\fR\fB\fR, \fB\fR\f(CB$consumeInput\fR\fB\fR, \fB\fR\f(CB$small\fR\fB\fR, \fB\fR\f(CB$limitOutput\fR\fB\fR,
+\&\fB\fR\f(CB$verbosity\fR\fB\fR
+.ie n .IP "$status = $z\->bzinflate($input, $output);" 4
+.el .IP "\f(CW$status\fR = \f(CW$z\fR\->bzinflate($input, \f(CW$output\fR);" 4
+.IX Item "$status = $z->bzinflate($input, $output);"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Misc 4
+.IX Item "Misc"
+.RS 4
+.ie n .IP "my $version = \fBCompress::Raw::Bzip2::bzlibversion()\fR;" 4
+.el .IP "my \f(CW$version\fR = \fBCompress::Raw::Bzip2::bzlibversion()\fR;" 4
+.IX Item "my $version = Compress::Raw::Bzip2::bzlibversion();"
+.RE
+.RS 4
+.RE
+.IP Constants 4
+.IX Item "Constants"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Compress::Raw::Zlib \- Low-Level Interface to zlib or zlib-ng compression library"
+.IX Subsection "Compress::Raw::Zlib - Low-Level Interface to zlib or zlib-ng compression library"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Compress::Raw::Zlib::Deflate 4
+.IX Item "Compress::Raw::Zlib::Deflate"
+.RS 4
+.ie n .IP "\fB($d, \fR\fB$status\fR\fB) = new Compress::Raw::Zlib::Deflate( [OPT] ) \fR" 4
+.el .IP "\fB($d, \fR\f(CB$status\fR\fB) = new Compress::Raw::Zlib::Deflate( [OPT] ) \fR" 4
+.IX Item "($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) "
+.PD
+\&\fB\-Level\fR, \fB\-Method\fR, \fB\-WindowBits\fR, \fB\-MemLevel\fR, \fB\-Strategy\fR,
+\&\fB\-Dictionary\fR, \fB\-Bufsize\fR, \fB\-AppendOutput\fR, \fB\-CRC32\fR, \fB\-ADLER32\fR
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->deflate($input, \fR\fB$output\fR\fB)\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->deflate($input, \fR\f(CB$output\fR\fB)\fR" 4
+.IX Item "$status = $d->deflate($input, $output)"
+.PD 0
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->flush($output [, \fR\fB$flush_type\fR\fB]) \fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->flush($output [, \fR\f(CB$flush_type\fR\fB]) \fR" 4
+.IX Item "$status = $d->flush($output [, $flush_type]) "
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->deflateReset() \fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->deflateReset() \fR" 4
+.IX Item "$status = $d->deflateReset() "
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->deflateParams([OPT])\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->deflateParams([OPT])\fR" 4
+.IX Item "$status = $d->deflateParams([OPT])"
+.PD
+\&\fB\-Level\fR, \fB\-Strategy\fR, \fB\-BufSize\fR
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->deflateTune($good_length, \fR\fB$max_lazy\fR\fB, \fR\fB$nice_length\fR\fB, \fR\fB$max_chain\fR\fB)\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->deflateTune($good_length, \fR\f(CB$max_lazy\fR\fB, \fR\f(CB$nice_length\fR\fB, \fR\f(CB$max_chain\fR\fB)\fR" 4
+.IX Item "$status = $d->deflateTune($good_length, $max_lazy, $nice_length, $max_chain)"
+.PD 0
+.ie n .IP \fR\fB$d\fR\fB\->dict_adler()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->dict_adler()\fR 4
+.IX Item "$d->dict_adler()"
+.ie n .IP \fR\fB$d\fR\fB\->crc32()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->crc32()\fR 4
+.IX Item "$d->crc32()"
+.ie n .IP \fR\fB$d\fR\fB\->adler32()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->adler32()\fR 4
+.IX Item "$d->adler32()"
+.ie n .IP \fR\fB$d\fR\fB\->msg()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->msg()\fR 4
+.IX Item "$d->msg()"
+.ie n .IP \fR\fB$d\fR\fB\->total_in()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->total_in()\fR 4
+.IX Item "$d->total_in()"
+.ie n .IP \fR\fB$d\fR\fB\->total_out()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->total_out()\fR 4
+.IX Item "$d->total_out()"
+.ie n .IP \fR\fB$d\fR\fB\->get_Strategy()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->get_Strategy()\fR 4
+.IX Item "$d->get_Strategy()"
+.ie n .IP \fR\fB$d\fR\fB\->get_Level()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->get_Level()\fR 4
+.IX Item "$d->get_Level()"
+.ie n .IP \fR\fB$d\fR\fB\->get_BufSize()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->get_BufSize()\fR 4
+.IX Item "$d->get_BufSize()"
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP Compress::Raw::Zlib::Inflate 4
+.IX Item "Compress::Raw::Zlib::Inflate"
+.RS 4
+.ie n .IP "\fB ($i, \fR\fB$status\fR\fB) = new Compress::Raw::Zlib::Inflate( [OPT] ) \fR" 4
+.el .IP "\fB ($i, \fR\f(CB$status\fR\fB) = new Compress::Raw::Zlib::Inflate( [OPT] ) \fR" 4
+.IX Item " ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) "
+.PD
+\&\fB\-WindowBits\fR, \fB\-Bufsize\fR, \fB\-Dictionary\fR, \fB\-AppendOutput\fR, \fB\-CRC32\fR,
+\&\fB\-ADLER32\fR, \fB\-ConsumeInput\fR, \fB\-LimitOutput\fR
+.ie n .IP "\fB \fR\fB$status\fR\fB = \fR\fB$i\fR\fB\->inflate($input, \fR\fB$output\fR\fB [,$eof]) \fR" 4
+.el .IP "\fB \fR\f(CB$status\fR\fB = \fR\f(CB$i\fR\fB\->inflate($input, \fR\f(CB$output\fR\fB [,$eof]) \fR" 4
+.IX Item " $status = $i->inflate($input, $output [,$eof]) "
+.PD 0
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$i\fR\fB\->inflateSync($input)\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$i\fR\fB\->inflateSync($input)\fR" 4
+.IX Item "$status = $i->inflateSync($input)"
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$i\fR\fB\->inflateReset() \fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$i\fR\fB\->inflateReset() \fR" 4
+.IX Item "$status = $i->inflateReset() "
+.ie n .IP \fR\fB$i\fR\fB\->dict_adler()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->dict_adler()\fR 4
+.IX Item "$i->dict_adler()"
+.ie n .IP \fR\fB$i\fR\fB\->crc32()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->crc32()\fR 4
+.IX Item "$i->crc32()"
+.ie n .IP \fR\fB$i\fR\fB\->adler32()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->adler32()\fR 4
+.IX Item "$i->adler32()"
+.ie n .IP \fR\fB$i\fR\fB\->msg()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->msg()\fR 4
+.IX Item "$i->msg()"
+.ie n .IP \fR\fB$i\fR\fB\->total_in()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->total_in()\fR 4
+.IX Item "$i->total_in()"
+.ie n .IP \fR\fB$i\fR\fB\->total_out()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->total_out()\fR 4
+.IX Item "$i->total_out()"
+.ie n .IP \fR\fB$d\fR\fB\->get_BufSize()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->get_BufSize()\fR 4
+.IX Item "$d->get_BufSize()"
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.IP "CHECKSUM FUNCTIONS" 4
+.IX Item "CHECKSUM FUNCTIONS"
+.IP Misc 4
+.IX Item "Misc"
+.RS 4
+.ie n .IP "my $version = \fBCompress::Raw::Zlib::zlib_version()\fR;" 4
+.el .IP "my \f(CW$version\fR = \fBCompress::Raw::Zlib::zlib_version()\fR;" 4
+.IX Item "my $version = Compress::Raw::Zlib::zlib_version();"
+.ie n .IP "my $version = \fBCompress::Raw::Zlib::zlibng_version()\fR;" 4
+.el .IP "my \f(CW$version\fR = \fBCompress::Raw::Zlib::zlibng_version()\fR;" 4
+.IX Item "my $version = Compress::Raw::Zlib::zlibng_version();"
+.ie n .IP "my $flags = \fBCompress::Raw::Zlib::zlibCompileFlags()\fR;" 4
+.el .IP "my \f(CW$flags\fR = \fBCompress::Raw::Zlib::zlibCompileFlags()\fR;" 4
+.IX Item "my $flags = Compress::Raw::Zlib::zlibCompileFlags();"
+.IP "\fBis_zlib_native()\fR; =head2 \fBis_zlibng_native()\fR; =head2 \fBis_zlibng_compat()\fR; =head2 \fBis_zlibng()\fR;" 4
+.IX Item "is_zlib_native(); =head2 is_zlibng_native(); =head2 is_zlibng_compat(); =head2 is_zlibng();"
+.RE
+.RS 4
+.RE
+.IP "The LimitOutput option." 4
+.IX Item "The LimitOutput option."
+.IP "ACCESSING ZIP FILES" 4
+.IX Item "ACCESSING ZIP FILES"
+.IP FAQ 4
+.IX Item "FAQ"
+.RS 4
+.IP "Compatibility with Unix compress/uncompress." 4
+.IX Item "Compatibility with Unix compress/uncompress."
+.IP "Accessing .tar.Z files" 4
+.IX Item "Accessing .tar.Z files"
+.IP "Zlib Library Version Support" 4
+.IX Item "Zlib Library Version Support"
+.RE
+.RS 4
+.RE
+.IP CONSTANTS 4
+.IX Item "CONSTANTS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Compress::Zlib \- Interface to zlib compression library"
+.IX Subsection "Compress::Zlib - Interface to zlib compression library"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Notes for users of Compress::Zlib version 1" 4
+.IX Item "Notes for users of Compress::Zlib version 1"
+.RE
+.RS 4
+.RE
+.IP "GZIP INTERFACE" 4
+.IX Item "GZIP INTERFACE"
+.PD
+\&\fR\f(CB$gz\fR\fB = gzopen($filename, \fR\f(CB$mode\fR\fB)\fR, \fB\fR\f(CB$gz\fR\fB = gzopen($filehandle, \fR\f(CB$mode\fR\fB)\fR,
+\&\fB\fR\f(CB$bytesread\fR\fB = \fR\f(CB$gz\fR\fB\->gzread($buffer [, \fR\f(CB$size\fR\fB]) ;\fR, \fB\fR\f(CB$bytesread\fR\fB =
+\&\fR\f(CB$gz\fR\fB\->gzreadline($line) ;\fR, \fB\fR\f(CB$byteswritten\fR\fB = \fR\f(CB$gz\fR\fB\->gzwrite($buffer)
+;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$gz\fR\fB\->gzflush($flush_type) ;\fR, \fB\fR\f(CB$offset\fR\fB =
+\&\fR\f(CB$gz\fR\fB\->gztell() ;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$gz\fR\fB\->gzseek($offset, \fR\f(CB$whence\fR\fB) ;\fR,
+\&\fB\fR\f(CB$gz\fR\fB\->gzclose\fR, \fB\fR\f(CB$gz\fR\fB\->gzsetparams($level, \fR\f(CB$strategy\fR\fB\fR, \fB\fR\f(CB$level\fR\fB\fR,
+\&\fB\fR\f(CB$strategy\fR\fB\fR, \fB\fR\f(CB$gz\fR\fB\->gzerror\fR, \fB\fR\f(CB$gzerrno\fR\fB\fR
+.RS 4
+.IP Examples 4
+.IX Item "Examples"
+.PD 0
+.IP Compress::Zlib::memGzip 4
+.IX Item "Compress::Zlib::memGzip"
+.IP Compress::Zlib::memGunzip 4
+.IX Item "Compress::Zlib::memGunzip"
+.RE
+.RS 4
+.RE
+.IP COMPRESS/UNCOMPRESS 4
+.IX Item "COMPRESS/UNCOMPRESS"
+.PD
+\&\fR\f(CB$dest\fR\fB = compress($source [, \fR\f(CB$level\fR\fB] ) ;\fR, \fB\fR\f(CB$dest\fR\fB = uncompress($source)
+;\fR
+.IP "Deflate Interface" 4
+.IX Item "Deflate Interface"
+.RS 4
+.PD 0
+.ie n .IP "\fB($d, \fR\fB$status\fR\fB) = deflateInit( [OPT] )\fR" 4
+.el .IP "\fB($d, \fR\f(CB$status\fR\fB) = deflateInit( [OPT] )\fR" 4
+.IX Item "($d, $status) = deflateInit( [OPT] )"
+.PD
+\&\fB\-Level\fR, \fB\-Method\fR, \fB\-WindowBits\fR, \fB\-MemLevel\fR, \fB\-Strategy\fR,
+\&\fB\-Dictionary\fR, \fB\-Bufsize\fR
+.ie n .IP "\fB($out, \fR\fB$status\fR\fB) = \fR\fB$d\fR\fB\->deflate($buffer)\fR" 4
+.el .IP "\fB($out, \fR\f(CB$status\fR\fB) = \fR\f(CB$d\fR\fB\->deflate($buffer)\fR" 4
+.IX Item "($out, $status) = $d->deflate($buffer)"
+.PD 0
+.ie n .IP "\fB($out, \fR\fB$status\fR\fB) = \fR\fB$d\fR\fB\->flush()\fR =head2 \fB($out, \fR\fB$status\fR\fB) = \fR\fB$d\fR\fB\->flush($flush_type)\fR" 4
+.el .IP "\fB($out, \fR\f(CB$status\fR\fB) = \fR\f(CB$d\fR\fB\->flush()\fR =head2 \fB($out, \fR\f(CB$status\fR\fB) = \fR\f(CB$d\fR\fB\->flush($flush_type)\fR" 4
+.IX Item "($out, $status) = $d->flush() =head2 ($out, $status) = $d->flush($flush_type)"
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$d\fR\fB\->deflateParams([OPT])\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$d\fR\fB\->deflateParams([OPT])\fR" 4
+.IX Item "$status = $d->deflateParams([OPT])"
+.PD
+\&\fB\-Level\fR, \fB\-Strategy\fR
+.ie n .IP \fR\fB$d\fR\fB\->dict_adler()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->dict_adler()\fR 4
+.IX Item "$d->dict_adler()"
+.PD 0
+.ie n .IP \fR\fB$d\fR\fB\->msg()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->msg()\fR 4
+.IX Item "$d->msg()"
+.ie n .IP \fR\fB$d\fR\fB\->total_in()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->total_in()\fR 4
+.IX Item "$d->total_in()"
+.ie n .IP \fR\fB$d\fR\fB\->total_out()\fR 4
+.el .IP \fR\f(CB$d\fR\fB\->total_out()\fR 4
+.IX Item "$d->total_out()"
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "Inflate Interface" 4
+.IX Item "Inflate Interface"
+.RS 4
+.ie n .IP "\fB($i, \fR\fB$status\fR\fB) = inflateInit()\fR" 4
+.el .IP "\fB($i, \fR\f(CB$status\fR\fB) = inflateInit()\fR" 4
+.IX Item "($i, $status) = inflateInit()"
+.PD
+\&\fB\-WindowBits\fR, \fB\-Bufsize\fR, \fB\-Dictionary\fR
+.ie n .IP "\fB($out, \fR\fB$status\fR\fB) = \fR\fB$i\fR\fB\->inflate($buffer)\fR" 4
+.el .IP "\fB($out, \fR\f(CB$status\fR\fB) = \fR\f(CB$i\fR\fB\->inflate($buffer)\fR" 4
+.IX Item "($out, $status) = $i->inflate($buffer)"
+.PD 0
+.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$i\fR\fB\->inflateSync($buffer)\fR" 4
+.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$i\fR\fB\->inflateSync($buffer)\fR" 4
+.IX Item "$status = $i->inflateSync($buffer)"
+.ie n .IP \fR\fB$i\fR\fB\->dict_adler()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->dict_adler()\fR 4
+.IX Item "$i->dict_adler()"
+.ie n .IP \fR\fB$i\fR\fB\->msg()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->msg()\fR 4
+.IX Item "$i->msg()"
+.ie n .IP \fR\fB$i\fR\fB\->total_in()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->total_in()\fR 4
+.IX Item "$i->total_in()"
+.ie n .IP \fR\fB$i\fR\fB\->total_out()\fR 4
+.el .IP \fR\f(CB$i\fR\fB\->total_out()\fR 4
+.IX Item "$i->total_out()"
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "CHECKSUM FUNCTIONS" 4
+.IX Item "CHECKSUM FUNCTIONS"
+.IP Misc 4
+.IX Item "Misc"
+.RS 4
+.ie n .IP "my $version = \fBCompress::Zlib::zlib_version()\fR;" 4
+.el .IP "my \f(CW$version\fR = \fBCompress::Zlib::zlib_version()\fR;" 4
+.IX Item "my $version = Compress::Zlib::zlib_version();"
+.RE
+.RS 4
+.RE
+.IP CONSTANTS 4
+.IX Item "CONSTANTS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Config, =for comment  Generated by configpm.  Any changes made here will be lost!"
+.IX Subsection "Config, =for comment Generated by configpm. Any changes made here will be lost!"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBmyconfig()\fR, \fBconfig_sh()\fR, config_re($regex), config_vars(@names),
+\&\fBbincompat_options()\fR, \fBnon_bincompat_options()\fR, \fBcompile_date()\fR,
+\&\fBlocal_patches()\fR, \fBheader_files()\fR
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP WARNING 4
+.IX Item "WARNING"
+.IP GLOSSARY 4
+.IX Item "GLOSSARY"
+.IP P 4
+.IX Item "P"
+.PD
+\&\f(CW\*(C`PERL_API_REVISION\*(C'\fR, \f(CW\*(C`PERL_API_SUBVERSION\*(C'\fR, \f(CW\*(C`PERL_API_VERSION\*(C'\fR,
+\&\f(CW\*(C`PERL_CONFIG_SH\*(C'\fR, \f(CW\*(C`PERL_PATCHLEVEL\*(C'\fR, \f(CW\*(C`PERL_REVISION\*(C'\fR,
+\&\f(CW\*(C`PERL_SUBVERSION\*(C'\fR, \f(CW\*(C`PERL_VERSION\*(C'\fR
+.IP _ 4
+.IX Item "_"
+\&\f(CW\*(C`_a\*(C'\fR, \f(CW\*(C`_exe\*(C'\fR, \f(CW\*(C`_o\*(C'\fR
+.IP a 4
+.IX Item "a"
+\&\f(CW\*(C`afs\*(C'\fR, \f(CW\*(C`afsroot\*(C'\fR, \f(CW\*(C`alignbytes\*(C'\fR, \f(CW\*(C`aphostname\*(C'\fR, \f(CW\*(C`api_revision\*(C'\fR,
+\&\f(CW\*(C`api_subversion\*(C'\fR, \f(CW\*(C`api_version\*(C'\fR, \f(CW\*(C`api_versionstring\*(C'\fR, \f(CW\*(C`ar\*(C'\fR, \f(CW\*(C`archlib\*(C'\fR,
+\&\f(CW\*(C`archlibexp\*(C'\fR, \f(CW\*(C`archname\*(C'\fR, \f(CW\*(C`archname64\*(C'\fR, \f(CW\*(C`archobjs\*(C'\fR, \f(CW\*(C`asctime_r_proto\*(C'\fR,
+\&\f(CW\*(C`awk\*(C'\fR
+.IP b 4
+.IX Item "b"
+\&\f(CW\*(C`baserev\*(C'\fR, \f(CW\*(C`bash\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, \f(CW\*(C`bin_ELF\*(C'\fR, \f(CW\*(C`binexp\*(C'\fR, \f(CW\*(C`bison\*(C'\fR, \f(CW\*(C`byacc\*(C'\fR,
+\&\f(CW\*(C`byteorder\*(C'\fR
+.IP c 4
+.IX Item "c"
+\&\f(CW\*(C`c\*(C'\fR, \f(CW\*(C`castflags\*(C'\fR, \f(CW\*(C`cat\*(C'\fR, \f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`cccdlflags\*(C'\fR, \f(CW\*(C`ccdlflags\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR,
+\&\f(CW\*(C`ccflags_uselargefiles\*(C'\fR, \f(CW\*(C`ccname\*(C'\fR, \f(CW\*(C`ccsymbols\*(C'\fR, \f(CW\*(C`ccversion\*(C'\fR, \f(CW\*(C`cf_by\*(C'\fR,
+\&\f(CW\*(C`cf_email\*(C'\fR, \f(CW\*(C`cf_time\*(C'\fR, \f(CW\*(C`charbits\*(C'\fR, \f(CW\*(C`charsize\*(C'\fR, \f(CW\*(C`chgrp\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR,
+\&\f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`clocktype\*(C'\fR, \f(CW\*(C`comm\*(C'\fR, \f(CW\*(C`compiler_warning\*(C'\fR, \f(CW\*(C`compress\*(C'\fR,
+\&\f(CW\*(C`config_arg0\*(C'\fR, \f(CW\*(C`config_argc\*(C'\fR, \f(CW\*(C`config_args\*(C'\fR, \f(CW\*(C`contains\*(C'\fR, \f(CW\*(C`cp\*(C'\fR,
+\&\f(CW\*(C`cpio\*(C'\fR, \f(CW\*(C`cpp\*(C'\fR, \f(CW\*(C`cpp_stuff\*(C'\fR, \f(CW\*(C`cppccsymbols\*(C'\fR, \f(CW\*(C`cppflags\*(C'\fR, \f(CW\*(C`cpplast\*(C'\fR,
+\&\f(CW\*(C`cppminus\*(C'\fR, \f(CW\*(C`cpprun\*(C'\fR, \f(CW\*(C`cppstdin\*(C'\fR, \f(CW\*(C`cppsymbols\*(C'\fR, \f(CW\*(C`crypt_r_proto\*(C'\fR,
+\&\f(CW\*(C`cryptlib\*(C'\fR, \f(CW\*(C`csh\*(C'\fR, \f(CW\*(C`ctermid_r_proto\*(C'\fR, \f(CW\*(C`ctime_r_proto\*(C'\fR
+.IP d 4
+.IX Item "d"
+\&\f(CW\*(C`d_Gconvert\*(C'\fR, \f(CW\*(C`d_PRIEUldbl\*(C'\fR, \f(CW\*(C`d_PRIFUldbl\*(C'\fR, \f(CW\*(C`d_PRIGUldbl\*(C'\fR,
+\&\f(CW\*(C`d_PRIXU64\*(C'\fR, \f(CW\*(C`d_PRId64\*(C'\fR, \f(CW\*(C`d_PRIeldbl\*(C'\fR, \f(CW\*(C`d_PRIfldbl\*(C'\fR, \f(CW\*(C`d_PRIgldbl\*(C'\fR,
+\&\f(CW\*(C`d_PRIi64\*(C'\fR, \f(CW\*(C`d_PRIo64\*(C'\fR, \f(CW\*(C`d_PRIu64\*(C'\fR, \f(CW\*(C`d_PRIx64\*(C'\fR, \f(CW\*(C`d_SCNfldbl\*(C'\fR,
+\&\f(CW\*(C`d_\|_fwalk\*(C'\fR, \f(CW\*(C`d_accept4\*(C'\fR, \f(CW\*(C`d_access\*(C'\fR, \f(CW\*(C`d_accessx\*(C'\fR, \f(CW\*(C`d_acosh\*(C'\fR,
+\&\f(CW\*(C`d_aintl\*(C'\fR, \f(CW\*(C`d_alarm\*(C'\fR, \f(CW\*(C`d_archlib\*(C'\fR, \f(CW\*(C`d_asctime64\*(C'\fR, \f(CW\*(C`d_asctime_r\*(C'\fR,
+\&\f(CW\*(C`d_asinh\*(C'\fR, \f(CW\*(C`d_atanh\*(C'\fR, \f(CW\*(C`d_atolf\*(C'\fR, \f(CW\*(C`d_atoll\*(C'\fR,
+\&\f(CW\*(C`d_attribute_always_inline\*(C'\fR, \f(CW\*(C`d_attribute_deprecated\*(C'\fR,
+\&\f(CW\*(C`d_attribute_format\*(C'\fR, \f(CW\*(C`d_attribute_malloc\*(C'\fR, \f(CW\*(C`d_attribute_nonnull\*(C'\fR,
+\&\f(CW\*(C`d_attribute_noreturn\*(C'\fR, \f(CW\*(C`d_attribute_pure\*(C'\fR, \f(CW\*(C`d_attribute_unused\*(C'\fR,
+\&\f(CW\*(C`d_attribute_visibility\*(C'\fR, \f(CW\*(C`d_attribute_warn_unused_result\*(C'\fR,
+\&\f(CW\*(C`d_backtrace\*(C'\fR, \f(CW\*(C`d_bsd\*(C'\fR, \f(CW\*(C`d_bsdgetpgrp\*(C'\fR, \f(CW\*(C`d_bsdsetpgrp\*(C'\fR,
+\&\f(CW\*(C`d_builtin_add_overflow\*(C'\fR, \f(CW\*(C`d_builtin_choose_expr\*(C'\fR, \f(CW\*(C`d_builtin_expect\*(C'\fR,
+\&\f(CW\*(C`d_builtin_mul_overflow\*(C'\fR, \f(CW\*(C`d_builtin_sub_overflow\*(C'\fR,
+\&\f(CW\*(C`d_c99_variadic_macros\*(C'\fR, \f(CW\*(C`d_casti32\*(C'\fR, \f(CW\*(C`d_castneg\*(C'\fR, \f(CW\*(C`d_cbrt\*(C'\fR,
+\&\f(CW\*(C`d_chown\*(C'\fR, \f(CW\*(C`d_chroot\*(C'\fR, \f(CW\*(C`d_chsize\*(C'\fR, \f(CW\*(C`d_class\*(C'\fR, \f(CW\*(C`d_clearenv\*(C'\fR,
+\&\f(CW\*(C`d_closedir\*(C'\fR, \f(CW\*(C`d_cmsghdr_s\*(C'\fR, \f(CW\*(C`d_copysign\*(C'\fR, \f(CW\*(C`d_copysignl\*(C'\fR,
+\&\f(CW\*(C`d_cplusplus\*(C'\fR, \f(CW\*(C`d_crypt\*(C'\fR, \f(CW\*(C`d_crypt_r\*(C'\fR, \f(CW\*(C`d_csh\*(C'\fR, \f(CW\*(C`d_ctermid\*(C'\fR,
+\&\f(CW\*(C`d_ctermid_r\*(C'\fR, \f(CW\*(C`d_ctime64\*(C'\fR, \f(CW\*(C`d_ctime_r\*(C'\fR, \f(CW\*(C`d_cuserid\*(C'\fR,
+\&\f(CW\*(C`d_dbminitproto\*(C'\fR, \f(CW\*(C`d_difftime\*(C'\fR, \f(CW\*(C`d_difftime64\*(C'\fR, \f(CW\*(C`d_dir_dd_fd\*(C'\fR,
+\&\f(CW\*(C`d_dirfd\*(C'\fR, \f(CW\*(C`d_dirnamlen\*(C'\fR, \f(CW\*(C`d_dladdr\*(C'\fR, \f(CW\*(C`d_dlerror\*(C'\fR, \f(CW\*(C`d_dlopen\*(C'\fR,
+\&\f(CW\*(C`d_dlsymun\*(C'\fR, \f(CW\*(C`d_dosuid\*(C'\fR, \f(CW\*(C`d_double_has_inf\*(C'\fR, \f(CW\*(C`d_double_has_nan\*(C'\fR,
+\&\f(CW\*(C`d_double_has_negative_zero\*(C'\fR, \f(CW\*(C`d_double_has_subnormals\*(C'\fR,
+\&\f(CW\*(C`d_double_style_cray\*(C'\fR, \f(CW\*(C`d_double_style_ibm\*(C'\fR, \f(CW\*(C`d_double_style_ieee\*(C'\fR,
+\&\f(CW\*(C`d_double_style_vax\*(C'\fR, \f(CW\*(C`d_drand48_r\*(C'\fR, \f(CW\*(C`d_drand48proto\*(C'\fR, \f(CW\*(C`d_dup2\*(C'\fR,
+\&\f(CW\*(C`d_dup3\*(C'\fR, \f(CW\*(C`d_duplocale\*(C'\fR, \f(CW\*(C`d_eaccess\*(C'\fR, \f(CW\*(C`d_endgrent\*(C'\fR, \f(CW\*(C`d_endgrent_r\*(C'\fR,
+\&\f(CW\*(C`d_endhent\*(C'\fR, \f(CW\*(C`d_endhostent_r\*(C'\fR, \f(CW\*(C`d_endnent\*(C'\fR, \f(CW\*(C`d_endnetent_r\*(C'\fR,
+\&\f(CW\*(C`d_endpent\*(C'\fR, \f(CW\*(C`d_endprotoent_r\*(C'\fR, \f(CW\*(C`d_endpwent\*(C'\fR, \f(CW\*(C`d_endpwent_r\*(C'\fR,
+\&\f(CW\*(C`d_endsent\*(C'\fR, \f(CW\*(C`d_endservent_r\*(C'\fR, \f(CW\*(C`d_eofnblk\*(C'\fR, \f(CW\*(C`d_erf\*(C'\fR, \f(CW\*(C`d_erfc\*(C'\fR,
+\&\f(CW\*(C`d_eunice\*(C'\fR, \f(CW\*(C`d_exp2\*(C'\fR, \f(CW\*(C`d_expm1\*(C'\fR, \f(CW\*(C`d_faststdio\*(C'\fR, \f(CW\*(C`d_fchdir\*(C'\fR,
+\&\f(CW\*(C`d_fchmod\*(C'\fR, \f(CW\*(C`d_fchmodat\*(C'\fR, \f(CW\*(C`d_fchown\*(C'\fR, \f(CW\*(C`d_fcntl\*(C'\fR, \f(CW\*(C`d_fcntl_can_lock\*(C'\fR,
+\&\f(CW\*(C`d_fd_macros\*(C'\fR, \f(CW\*(C`d_fd_set\*(C'\fR, \f(CW\*(C`d_fdclose\*(C'\fR, \f(CW\*(C`d_fdim\*(C'\fR, \f(CW\*(C`d_fds_bits\*(C'\fR,
+\&\f(CW\*(C`d_fegetround\*(C'\fR, \f(CW\*(C`d_ffs\*(C'\fR, \f(CW\*(C`d_ffsl\*(C'\fR, \f(CW\*(C`d_fgetpos\*(C'\fR, \f(CW\*(C`d_finite\*(C'\fR,
+\&\f(CW\*(C`d_finitel\*(C'\fR, \f(CW\*(C`d_flexfnam\*(C'\fR, \f(CW\*(C`d_flock\*(C'\fR, \f(CW\*(C`d_flockproto\*(C'\fR, \f(CW\*(C`d_fma\*(C'\fR,
+\&\f(CW\*(C`d_fmax\*(C'\fR, \f(CW\*(C`d_fmin\*(C'\fR, \f(CW\*(C`d_fork\*(C'\fR, \f(CW\*(C`d_fp_class\*(C'\fR, \f(CW\*(C`d_fp_classify\*(C'\fR,
+\&\f(CW\*(C`d_fp_classl\*(C'\fR, \f(CW\*(C`d_fpathconf\*(C'\fR, \f(CW\*(C`d_fpclass\*(C'\fR, \f(CW\*(C`d_fpclassify\*(C'\fR,
+\&\f(CW\*(C`d_fpclassl\*(C'\fR, \f(CW\*(C`d_fpgetround\*(C'\fR, \f(CW\*(C`d_fpos64_t\*(C'\fR, \f(CW\*(C`d_freelocale\*(C'\fR,
+\&\f(CW\*(C`d_frexpl\*(C'\fR, \f(CW\*(C`d_fs_data_s\*(C'\fR, \f(CW\*(C`d_fseeko\*(C'\fR, \f(CW\*(C`d_fsetpos\*(C'\fR, \f(CW\*(C`d_fstatfs\*(C'\fR,
+\&\f(CW\*(C`d_fstatvfs\*(C'\fR, \f(CW\*(C`d_fsync\*(C'\fR, \f(CW\*(C`d_ftello\*(C'\fR, \f(CW\*(C`d_ftime\*(C'\fR, \f(CW\*(C`d_futimes\*(C'\fR,
+\&\f(CW\*(C`d_gai_strerror\*(C'\fR, \f(CW\*(C`d_gdbm_ndbm_h_uses_prototypes\*(C'\fR,
+\&\f(CW\*(C`d_gdbmndbm_h_uses_prototypes\*(C'\fR, \f(CW\*(C`d_getaddrinfo\*(C'\fR, \f(CW\*(C`d_getcwd\*(C'\fR,
+\&\f(CW\*(C`d_getenv_preserves_other_thread\*(C'\fR, \f(CW\*(C`d_getespwnam\*(C'\fR, \f(CW\*(C`d_getfsstat\*(C'\fR,
+\&\f(CW\*(C`d_getgrent\*(C'\fR, \f(CW\*(C`d_getgrent_r\*(C'\fR, \f(CW\*(C`d_getgrgid_r\*(C'\fR, \f(CW\*(C`d_getgrnam_r\*(C'\fR,
+\&\f(CW\*(C`d_getgrps\*(C'\fR, \f(CW\*(C`d_gethbyaddr\*(C'\fR, \f(CW\*(C`d_gethbyname\*(C'\fR, \f(CW\*(C`d_gethent\*(C'\fR,
+\&\f(CW\*(C`d_gethname\*(C'\fR, \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR, \f(CW\*(C`d_gethostbyname_r\*(C'\fR,
+\&\f(CW\*(C`d_gethostent_r\*(C'\fR, \f(CW\*(C`d_gethostprotos\*(C'\fR, \f(CW\*(C`d_getitimer\*(C'\fR, \f(CW\*(C`d_getlogin\*(C'\fR,
+\&\f(CW\*(C`d_getlogin_r\*(C'\fR, \f(CW\*(C`d_getmnt\*(C'\fR, \f(CW\*(C`d_getmntent\*(C'\fR, \f(CW\*(C`d_getnameinfo\*(C'\fR,
+\&\f(CW\*(C`d_getnbyaddr\*(C'\fR, \f(CW\*(C`d_getnbyname\*(C'\fR, \f(CW\*(C`d_getnent\*(C'\fR, \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR,
+\&\f(CW\*(C`d_getnetbyname_r\*(C'\fR, \f(CW\*(C`d_getnetent_r\*(C'\fR, \f(CW\*(C`d_getnetprotos\*(C'\fR, \f(CW\*(C`d_getpagsz\*(C'\fR,
+\&\f(CW\*(C`d_getpbyname\*(C'\fR, \f(CW\*(C`d_getpbynumber\*(C'\fR, \f(CW\*(C`d_getpent\*(C'\fR, \f(CW\*(C`d_getpgid\*(C'\fR,
+\&\f(CW\*(C`d_getpgrp\*(C'\fR, \f(CW\*(C`d_getpgrp2\*(C'\fR, \f(CW\*(C`d_getppid\*(C'\fR, \f(CW\*(C`d_getprior\*(C'\fR,
+\&\f(CW\*(C`d_getprotobyname_r\*(C'\fR, \f(CW\*(C`d_getprotobynumber_r\*(C'\fR, \f(CW\*(C`d_getprotoent_r\*(C'\fR,
+\&\f(CW\*(C`d_getprotoprotos\*(C'\fR, \f(CW\*(C`d_getprpwnam\*(C'\fR, \f(CW\*(C`d_getpwent\*(C'\fR, \f(CW\*(C`d_getpwent_r\*(C'\fR,
+\&\f(CW\*(C`d_getpwnam_r\*(C'\fR, \f(CW\*(C`d_getpwuid_r\*(C'\fR, \f(CW\*(C`d_getsbyname\*(C'\fR, \f(CW\*(C`d_getsbyport\*(C'\fR,
+\&\f(CW\*(C`d_getsent\*(C'\fR, \f(CW\*(C`d_getservbyname_r\*(C'\fR, \f(CW\*(C`d_getservbyport_r\*(C'\fR,
+\&\f(CW\*(C`d_getservent_r\*(C'\fR, \f(CW\*(C`d_getservprotos\*(C'\fR, \f(CW\*(C`d_getspnam\*(C'\fR, \f(CW\*(C`d_getspnam_r\*(C'\fR,
+\&\f(CW\*(C`d_gettimeod\*(C'\fR, \f(CW\*(C`d_gmtime64\*(C'\fR, \f(CW\*(C`d_gmtime_r\*(C'\fR, \f(CW\*(C`d_gnulibc\*(C'\fR, \f(CW\*(C`d_grpasswd\*(C'\fR,
+\&\f(CW\*(C`d_has_C_UTF8\*(C'\fR, \f(CW\*(C`d_hasmntopt\*(C'\fR, \f(CW\*(C`d_htonl\*(C'\fR, \f(CW\*(C`d_hypot\*(C'\fR, \f(CW\*(C`d_ilogb\*(C'\fR,
+\&\f(CW\*(C`d_ilogbl\*(C'\fR, \f(CW\*(C`d_inc_version_list\*(C'\fR, \f(CW\*(C`d_inetaton\*(C'\fR, \f(CW\*(C`d_inetntop\*(C'\fR,
+\&\f(CW\*(C`d_inetpton\*(C'\fR, \f(CW\*(C`d_int64_t\*(C'\fR, \f(CW\*(C`d_ip_mreq\*(C'\fR, \f(CW\*(C`d_ip_mreq_source\*(C'\fR,
+\&\f(CW\*(C`d_ipv6_mreq\*(C'\fR, \f(CW\*(C`d_ipv6_mreq_source\*(C'\fR, \f(CW\*(C`d_isascii\*(C'\fR, \f(CW\*(C`d_isblank\*(C'\fR,
+\&\f(CW\*(C`d_isfinite\*(C'\fR, \f(CW\*(C`d_isfinitel\*(C'\fR, \f(CW\*(C`d_isinf\*(C'\fR, \f(CW\*(C`d_isinfl\*(C'\fR, \f(CW\*(C`d_isless\*(C'\fR,
+\&\f(CW\*(C`d_isnan\*(C'\fR, \f(CW\*(C`d_isnanl\*(C'\fR, \f(CW\*(C`d_isnormal\*(C'\fR, \f(CW\*(C`d_j0\*(C'\fR, \f(CW\*(C`d_j0l\*(C'\fR, \f(CW\*(C`d_killpg\*(C'\fR,
+\&\f(CW\*(C`d_lc_monetary_2008\*(C'\fR, \f(CW\*(C`d_lchown\*(C'\fR, \f(CW\*(C`d_ldbl_dig\*(C'\fR, \f(CW\*(C`d_ldexpl\*(C'\fR,
+\&\f(CW\*(C`d_lgamma\*(C'\fR, \f(CW\*(C`d_lgamma_r\*(C'\fR, \f(CW\*(C`d_libm_lib_version\*(C'\fR, \f(CW\*(C`d_libname_unique\*(C'\fR,
+\&\f(CW\*(C`d_link\*(C'\fR, \f(CW\*(C`d_linkat\*(C'\fR, \f(CW\*(C`d_llrint\*(C'\fR, \f(CW\*(C`d_llrintl\*(C'\fR, \f(CW\*(C`d_llround\*(C'\fR,
+\&\f(CW\*(C`d_llroundl\*(C'\fR, \f(CW\*(C`d_localeconv_l\*(C'\fR, \f(CW\*(C`d_localtime64\*(C'\fR, \f(CW\*(C`d_localtime_r\*(C'\fR,
+\&\f(CW\*(C`d_localtime_r_needs_tzset\*(C'\fR, \f(CW\*(C`d_locconv\*(C'\fR, \f(CW\*(C`d_lockf\*(C'\fR, \f(CW\*(C`d_log1p\*(C'\fR,
+\&\f(CW\*(C`d_log2\*(C'\fR, \f(CW\*(C`d_logb\*(C'\fR, \f(CW\*(C`d_long_double_style_ieee\*(C'\fR,
+\&\f(CW\*(C`d_long_double_style_ieee_doubledouble\*(C'\fR,
+\&\f(CW\*(C`d_long_double_style_ieee_extended\*(C'\fR, \f(CW\*(C`d_long_double_style_ieee_std\*(C'\fR,
+\&\f(CW\*(C`d_long_double_style_vax\*(C'\fR, \f(CW\*(C`d_longdbl\*(C'\fR, \f(CW\*(C`d_longlong\*(C'\fR, \f(CW\*(C`d_lrint\*(C'\fR,
+\&\f(CW\*(C`d_lrintl\*(C'\fR, \f(CW\*(C`d_lround\*(C'\fR, \f(CW\*(C`d_lroundl\*(C'\fR, \f(CW\*(C`d_lseekproto\*(C'\fR, \f(CW\*(C`d_lstat\*(C'\fR,
+\&\f(CW\*(C`d_madvise\*(C'\fR, \f(CW\*(C`d_malloc_good_size\*(C'\fR, \f(CW\*(C`d_malloc_size\*(C'\fR,
+\&\f(CW\*(C`d_malloc_usable_size\*(C'\fR, \f(CW\*(C`d_mblen\*(C'\fR, \f(CW\*(C`d_mbrlen\*(C'\fR, \f(CW\*(C`d_mbrtowc\*(C'\fR,
+\&\f(CW\*(C`d_mbstowcs\*(C'\fR, \f(CW\*(C`d_mbtowc\*(C'\fR, \f(CW\*(C`d_memmem\*(C'\fR, \f(CW\*(C`d_memrchr\*(C'\fR, \f(CW\*(C`d_mkdir\*(C'\fR,
+\&\f(CW\*(C`d_mkdtemp\*(C'\fR, \f(CW\*(C`d_mkfifo\*(C'\fR, \f(CW\*(C`d_mkostemp\*(C'\fR, \f(CW\*(C`d_mkstemp\*(C'\fR, \f(CW\*(C`d_mkstemps\*(C'\fR,
+\&\f(CW\*(C`d_mktime\*(C'\fR, \f(CW\*(C`d_mktime64\*(C'\fR, \f(CW\*(C`d_mmap\*(C'\fR, \f(CW\*(C`d_modfl\*(C'\fR, \f(CW\*(C`d_modflproto\*(C'\fR,
+\&\f(CW\*(C`d_mprotect\*(C'\fR, \f(CW\*(C`d_msg\*(C'\fR, \f(CW\*(C`d_msg_ctrunc\*(C'\fR, \f(CW\*(C`d_msg_dontroute\*(C'\fR, \f(CW\*(C`d_msg_oob\*(C'\fR,
+\&\f(CW\*(C`d_msg_peek\*(C'\fR, \f(CW\*(C`d_msg_proxy\*(C'\fR, \f(CW\*(C`d_msgctl\*(C'\fR, \f(CW\*(C`d_msgget\*(C'\fR, \f(CW\*(C`d_msghdr_s\*(C'\fR,
+\&\f(CW\*(C`d_msgrcv\*(C'\fR, \f(CW\*(C`d_msgsnd\*(C'\fR, \f(CW\*(C`d_msync\*(C'\fR, \f(CW\*(C`d_munmap\*(C'\fR, \f(CW\*(C`d_mymalloc\*(C'\fR, \f(CW\*(C`d_nan\*(C'\fR,
+\&\f(CW\*(C`d_nanosleep\*(C'\fR, \f(CW\*(C`d_ndbm\*(C'\fR, \f(CW\*(C`d_ndbm_h_uses_prototypes\*(C'\fR, \f(CW\*(C`d_nearbyint\*(C'\fR,
+\&\f(CW\*(C`d_newlocale\*(C'\fR, \f(CW\*(C`d_nextafter\*(C'\fR, \f(CW\*(C`d_nexttoward\*(C'\fR, \f(CW\*(C`d_nice\*(C'\fR,
+\&\f(CW\*(C`d_nl_langinfo\*(C'\fR, \f(CW\*(C`d_nl_langinfo_l\*(C'\fR, \f(CW\*(C`d_non_int_bitfields\*(C'\fR,
+\&\f(CW\*(C`d_nv_preserves_uv\*(C'\fR, \f(CW\*(C`d_nv_zero_is_allbits_zero\*(C'\fR, \f(CW\*(C`d_off64_t\*(C'\fR,
+\&\f(CW\*(C`d_old_pthread_create_joinable\*(C'\fR, \f(CW\*(C`d_oldpthreads\*(C'\fR, \f(CW\*(C`d_oldsock\*(C'\fR,
+\&\f(CW\*(C`d_open3\*(C'\fR, \f(CW\*(C`d_openat\*(C'\fR, \f(CW\*(C`d_pathconf\*(C'\fR, \f(CW\*(C`d_pause\*(C'\fR, \f(CW\*(C`d_perl_otherlibdirs\*(C'\fR,
+\&\f(CW\*(C`d_phostname\*(C'\fR, \f(CW\*(C`d_pipe\*(C'\fR, \f(CW\*(C`d_pipe2\*(C'\fR, \f(CW\*(C`d_poll\*(C'\fR, \f(CW\*(C`d_portable\*(C'\fR,
+\&\f(CW\*(C`d_prctl\*(C'\fR, \f(CW\*(C`d_prctl_set_name\*(C'\fR, \f(CW\*(C`d_printf_format_null\*(C'\fR, \f(CW\*(C`d_procselfexe\*(C'\fR,
+\&\f(CW\*(C`d_pseudofork\*(C'\fR, \f(CW\*(C`d_pthread_atfork\*(C'\fR, \f(CW\*(C`d_pthread_attr_setscope\*(C'\fR,
+\&\f(CW\*(C`d_pthread_yield\*(C'\fR, \f(CW\*(C`d_ptrdiff_t\*(C'\fR, \f(CW\*(C`d_pwage\*(C'\fR, \f(CW\*(C`d_pwchange\*(C'\fR,
+\&\f(CW\*(C`d_pwclass\*(C'\fR, \f(CW\*(C`d_pwcomment\*(C'\fR, \f(CW\*(C`d_pwexpire\*(C'\fR, \f(CW\*(C`d_pwgecos\*(C'\fR, \f(CW\*(C`d_pwpasswd\*(C'\fR,
+\&\f(CW\*(C`d_pwquota\*(C'\fR, \f(CW\*(C`d_qgcvt\*(C'\fR, \f(CW\*(C`d_quad\*(C'\fR, \f(CW\*(C`d_querylocale\*(C'\fR, \f(CW\*(C`d_random_r\*(C'\fR,
+\&\f(CW\*(C`d_re_comp\*(C'\fR, \f(CW\*(C`d_readdir\*(C'\fR, \f(CW\*(C`d_readdir64_r\*(C'\fR, \f(CW\*(C`d_readdir_r\*(C'\fR,
+\&\f(CW\*(C`d_readlink\*(C'\fR, \f(CW\*(C`d_readv\*(C'\fR, \f(CW\*(C`d_recvmsg\*(C'\fR, \f(CW\*(C`d_regcmp\*(C'\fR, \f(CW\*(C`d_regcomp\*(C'\fR,
+\&\f(CW\*(C`d_remainder\*(C'\fR, \f(CW\*(C`d_remquo\*(C'\fR, \f(CW\*(C`d_rename\*(C'\fR, \f(CW\*(C`d_renameat\*(C'\fR, \f(CW\*(C`d_rewinddir\*(C'\fR,
+\&\f(CW\*(C`d_rint\*(C'\fR, \f(CW\*(C`d_rmdir\*(C'\fR, \f(CW\*(C`d_round\*(C'\fR, \f(CW\*(C`d_sbrkproto\*(C'\fR, \f(CW\*(C`d_scalbn\*(C'\fR,
+\&\f(CW\*(C`d_scalbnl\*(C'\fR, \f(CW\*(C`d_sched_yield\*(C'\fR, \f(CW\*(C`d_scm_rights\*(C'\fR, \f(CW\*(C`d_seekdir\*(C'\fR, \f(CW\*(C`d_select\*(C'\fR,
+\&\f(CW\*(C`d_sem\*(C'\fR, \f(CW\*(C`d_semctl\*(C'\fR, \f(CW\*(C`d_semctl_semid_ds\*(C'\fR, \f(CW\*(C`d_semctl_semun\*(C'\fR,
+\&\f(CW\*(C`d_semget\*(C'\fR, \f(CW\*(C`d_semop\*(C'\fR, \f(CW\*(C`d_sendmsg\*(C'\fR, \f(CW\*(C`d_setegid\*(C'\fR, \f(CW\*(C`d_setenv\*(C'\fR,
+\&\f(CW\*(C`d_seteuid\*(C'\fR, \f(CW\*(C`d_setgrent\*(C'\fR, \f(CW\*(C`d_setgrent_r\*(C'\fR, \f(CW\*(C`d_setgrps\*(C'\fR, \f(CW\*(C`d_sethent\*(C'\fR,
+\&\f(CW\*(C`d_sethostent_r\*(C'\fR, \f(CW\*(C`d_setitimer\*(C'\fR, \f(CW\*(C`d_setlinebuf\*(C'\fR, \f(CW\*(C`d_setlocale\*(C'\fR,
+\&\f(CW\*(C`d_setlocale_accepts_any_locale_name\*(C'\fR, \f(CW\*(C`d_setlocale_r\*(C'\fR, \f(CW\*(C`d_setnent\*(C'\fR,
+\&\f(CW\*(C`d_setnetent_r\*(C'\fR, \f(CW\*(C`d_setpent\*(C'\fR, \f(CW\*(C`d_setpgid\*(C'\fR, \f(CW\*(C`d_setpgrp\*(C'\fR, \f(CW\*(C`d_setpgrp2\*(C'\fR,
+\&\f(CW\*(C`d_setprior\*(C'\fR, \f(CW\*(C`d_setproctitle\*(C'\fR, \f(CW\*(C`d_setprotoent_r\*(C'\fR, \f(CW\*(C`d_setpwent\*(C'\fR,
+\&\f(CW\*(C`d_setpwent_r\*(C'\fR, \f(CW\*(C`d_setregid\*(C'\fR, \f(CW\*(C`d_setresgid\*(C'\fR, \f(CW\*(C`d_setresuid\*(C'\fR,
+\&\f(CW\*(C`d_setreuid\*(C'\fR, \f(CW\*(C`d_setrgid\*(C'\fR, \f(CW\*(C`d_setruid\*(C'\fR, \f(CW\*(C`d_setsent\*(C'\fR, \f(CW\*(C`d_setservent_r\*(C'\fR,
+\&\f(CW\*(C`d_setsid\*(C'\fR, \f(CW\*(C`d_setvbuf\*(C'\fR, \f(CW\*(C`d_shm\*(C'\fR, \f(CW\*(C`d_shmat\*(C'\fR, \f(CW\*(C`d_shmatprototype\*(C'\fR,
+\&\f(CW\*(C`d_shmctl\*(C'\fR, \f(CW\*(C`d_shmdt\*(C'\fR, \f(CW\*(C`d_shmget\*(C'\fR, \f(CW\*(C`d_sigaction\*(C'\fR, \f(CW\*(C`d_siginfo_si_addr\*(C'\fR,
+\&\f(CW\*(C`d_siginfo_si_band\*(C'\fR, \f(CW\*(C`d_siginfo_si_errno\*(C'\fR, \f(CW\*(C`d_siginfo_si_fd\*(C'\fR,
+\&\f(CW\*(C`d_siginfo_si_pid\*(C'\fR, \f(CW\*(C`d_siginfo_si_status\*(C'\fR, \f(CW\*(C`d_siginfo_si_uid\*(C'\fR,
+\&\f(CW\*(C`d_siginfo_si_value\*(C'\fR, \f(CW\*(C`d_signbit\*(C'\fR, \f(CW\*(C`d_sigprocmask\*(C'\fR, \f(CW\*(C`d_sigsetjmp\*(C'\fR,
+\&\f(CW\*(C`d_sin6_scope_id\*(C'\fR, \f(CW\*(C`d_sitearch\*(C'\fR, \f(CW\*(C`d_snprintf\*(C'\fR, \f(CW\*(C`d_sockaddr_in6\*(C'\fR,
+\&\f(CW\*(C`d_sockaddr_sa_len\*(C'\fR, \f(CW\*(C`d_sockaddr_storage\*(C'\fR, \f(CW\*(C`d_sockatmark\*(C'\fR,
+\&\f(CW\*(C`d_sockatmarkproto\*(C'\fR, \f(CW\*(C`d_socket\*(C'\fR, \f(CW\*(C`d_socklen_t\*(C'\fR, \f(CW\*(C`d_sockpair\*(C'\fR,
+\&\f(CW\*(C`d_socks5_init\*(C'\fR, \f(CW\*(C`d_sqrtl\*(C'\fR, \f(CW\*(C`d_srand48_r\*(C'\fR, \f(CW\*(C`d_srandom_r\*(C'\fR,
+\&\f(CW\*(C`d_sresgproto\*(C'\fR, \f(CW\*(C`d_sresuproto\*(C'\fR, \f(CW\*(C`d_stat\*(C'\fR, \f(CW\*(C`d_statblks\*(C'\fR,
+\&\f(CW\*(C`d_statfs_f_flags\*(C'\fR, \f(CW\*(C`d_statfs_s\*(C'\fR, \f(CW\*(C`d_static_inline\*(C'\fR, \f(CW\*(C`d_statvfs\*(C'\fR,
+\&\f(CW\*(C`d_stdio_cnt_lval\*(C'\fR, \f(CW\*(C`d_stdio_ptr_lval\*(C'\fR, \f(CW\*(C`d_stdio_ptr_lval_nochange_cnt\*(C'\fR,
+\&\f(CW\*(C`d_stdio_ptr_lval_sets_cnt\*(C'\fR, \f(CW\*(C`d_stdio_stream_array\*(C'\fR, \f(CW\*(C`d_stdiobase\*(C'\fR,
+\&\f(CW\*(C`d_stdstdio\*(C'\fR, \f(CW\*(C`d_strcoll\*(C'\fR, \f(CW\*(C`d_strerror_l\*(C'\fR, \f(CW\*(C`d_strerror_r\*(C'\fR,
+\&\f(CW\*(C`d_strftime\*(C'\fR, \f(CW\*(C`d_strlcat\*(C'\fR, \f(CW\*(C`d_strlcpy\*(C'\fR, \f(CW\*(C`d_strnlen\*(C'\fR, \f(CW\*(C`d_strtod\*(C'\fR,
+\&\f(CW\*(C`d_strtod_l\*(C'\fR, \f(CW\*(C`d_strtol\*(C'\fR, \f(CW\*(C`d_strtold\*(C'\fR, \f(CW\*(C`d_strtold_l\*(C'\fR, \f(CW\*(C`d_strtoll\*(C'\fR,
+\&\f(CW\*(C`d_strtoq\*(C'\fR, \f(CW\*(C`d_strtoul\*(C'\fR, \f(CW\*(C`d_strtoull\*(C'\fR, \f(CW\*(C`d_strtouq\*(C'\fR, \f(CW\*(C`d_strxfrm\*(C'\fR,
+\&\f(CW\*(C`d_strxfrm_l\*(C'\fR, \f(CW\*(C`d_suidsafe\*(C'\fR, \f(CW\*(C`d_symlink\*(C'\fR, \f(CW\*(C`d_syscall\*(C'\fR,
+\&\f(CW\*(C`d_syscallproto\*(C'\fR, \f(CW\*(C`d_sysconf\*(C'\fR, \f(CW\*(C`d_sysernlst\*(C'\fR, \f(CW\*(C`d_syserrlst\*(C'\fR,
+\&\f(CW\*(C`d_system\*(C'\fR, \f(CW\*(C`d_tcgetpgrp\*(C'\fR, \f(CW\*(C`d_tcsetpgrp\*(C'\fR, \f(CW\*(C`d_telldir\*(C'\fR,
+\&\f(CW\*(C`d_telldirproto\*(C'\fR, \f(CW\*(C`d_tgamma\*(C'\fR, \f(CW\*(C`d_thread_local\*(C'\fR,
+\&\f(CW\*(C`d_thread_safe_nl_langinfo_l\*(C'\fR, \f(CW\*(C`d_time\*(C'\fR, \f(CW\*(C`d_timegm\*(C'\fR, \f(CW\*(C`d_times\*(C'\fR,
+\&\f(CW\*(C`d_tm_tm_gmtoff\*(C'\fR, \f(CW\*(C`d_tm_tm_zone\*(C'\fR, \f(CW\*(C`d_tmpnam_r\*(C'\fR, \f(CW\*(C`d_towlower\*(C'\fR,
+\&\f(CW\*(C`d_towupper\*(C'\fR, \f(CW\*(C`d_trunc\*(C'\fR, \f(CW\*(C`d_truncate\*(C'\fR, \f(CW\*(C`d_truncl\*(C'\fR, \f(CW\*(C`d_ttyname_r\*(C'\fR,
+\&\f(CW\*(C`d_tzname\*(C'\fR, \f(CW\*(C`d_u32align\*(C'\fR, \f(CW\*(C`d_ualarm\*(C'\fR, \f(CW\*(C`d_umask\*(C'\fR, \f(CW\*(C`d_uname\*(C'\fR,
+\&\f(CW\*(C`d_union_semun\*(C'\fR, \f(CW\*(C`d_unlinkat\*(C'\fR, \f(CW\*(C`d_unordered\*(C'\fR, \f(CW\*(C`d_unsetenv\*(C'\fR,
+\&\f(CW\*(C`d_uselocale\*(C'\fR, \f(CW\*(C`d_usleep\*(C'\fR, \f(CW\*(C`d_usleepproto\*(C'\fR, \f(CW\*(C`d_ustat\*(C'\fR, \f(CW\*(C`d_vendorarch\*(C'\fR,
+\&\f(CW\*(C`d_vendorbin\*(C'\fR, \f(CW\*(C`d_vendorlib\*(C'\fR, \f(CW\*(C`d_vendorscript\*(C'\fR, \f(CW\*(C`d_vfork\*(C'\fR,
+\&\f(CW\*(C`d_void_closedir\*(C'\fR, \f(CW\*(C`d_voidsig\*(C'\fR, \f(CW\*(C`d_voidtty\*(C'\fR, \f(CW\*(C`d_vsnprintf\*(C'\fR, \f(CW\*(C`d_wait4\*(C'\fR,
+\&\f(CW\*(C`d_waitpid\*(C'\fR, \f(CW\*(C`d_wcrtomb\*(C'\fR, \f(CW\*(C`d_wcscmp\*(C'\fR, \f(CW\*(C`d_wcstombs\*(C'\fR, \f(CW\*(C`d_wcsxfrm\*(C'\fR,
+\&\f(CW\*(C`d_wctomb\*(C'\fR, \f(CW\*(C`d_writev\*(C'\fR, \f(CW\*(C`d_xenix\*(C'\fR, \f(CW\*(C`date\*(C'\fR, \f(CW\*(C`db_hashtype\*(C'\fR,
+\&\f(CW\*(C`db_prefixtype\*(C'\fR, \f(CW\*(C`db_version_major\*(C'\fR, \f(CW\*(C`db_version_minor\*(C'\fR,
+\&\f(CW\*(C`db_version_patch\*(C'\fR, \f(CW\*(C`default_inc_excludes_dot\*(C'\fR, \f(CW\*(C`direntrytype\*(C'\fR,
+\&\f(CW\*(C`dlext\*(C'\fR, \f(CW\*(C`dlsrc\*(C'\fR, \f(CW\*(C`doubleinfbytes\*(C'\fR, \f(CW\*(C`doublekind\*(C'\fR, \f(CW\*(C`doublemantbits\*(C'\fR,
+\&\f(CW\*(C`doublenanbytes\*(C'\fR, \f(CW\*(C`doublesize\*(C'\fR, \f(CW\*(C`drand01\*(C'\fR, \f(CW\*(C`drand48_r_proto\*(C'\fR,
+\&\f(CW\*(C`dtrace\*(C'\fR, \f(CW\*(C`dtraceobject\*(C'\fR, \f(CW\*(C`dtracexnolibs\*(C'\fR, \f(CW\*(C`dynamic_ext\*(C'\fR
+.IP e 4
+.IX Item "e"
+\&\f(CW\*(C`eagain\*(C'\fR, \f(CW\*(C`ebcdic\*(C'\fR, \f(CW\*(C`echo\*(C'\fR, \f(CW\*(C`egrep\*(C'\fR, \f(CW\*(C`emacs\*(C'\fR, \f(CW\*(C`endgrent_r_proto\*(C'\fR,
+\&\f(CW\*(C`endhostent_r_proto\*(C'\fR, \f(CW\*(C`endnetent_r_proto\*(C'\fR, \f(CW\*(C`endprotoent_r_proto\*(C'\fR,
+\&\f(CW\*(C`endpwent_r_proto\*(C'\fR, \f(CW\*(C`endservent_r_proto\*(C'\fR, \f(CW\*(C`eunicefix\*(C'\fR, \f(CW\*(C`exe_ext\*(C'\fR,
+\&\f(CW\*(C`expr\*(C'\fR, \f(CW\*(C`extensions\*(C'\fR, \f(CW\*(C`extern_C\*(C'\fR, \f(CW\*(C`extras\*(C'\fR
+.IP f 4
+.IX Item "f"
+\&\f(CW\*(C`fflushNULL\*(C'\fR, \f(CW\*(C`fflushall\*(C'\fR, \f(CW\*(C`find\*(C'\fR, \f(CW\*(C`firstmakefile\*(C'\fR, \f(CW\*(C`flex\*(C'\fR,
+\&\f(CW\*(C`fpossize\*(C'\fR, \f(CW\*(C`fpostype\*(C'\fR, \f(CW\*(C`freetype\*(C'\fR, \f(CW\*(C`from\*(C'\fR, \f(CW\*(C`full_ar\*(C'\fR, \f(CW\*(C`full_csh\*(C'\fR,
+\&\f(CW\*(C`full_sed\*(C'\fR
+.IP g 4
+.IX Item "g"
+\&\f(CW\*(C`gccansipedantic\*(C'\fR, \f(CW\*(C`gccosandvers\*(C'\fR, \f(CW\*(C`gccversion\*(C'\fR, \f(CW\*(C`getgrent_r_proto\*(C'\fR,
+\&\f(CW\*(C`getgrgid_r_proto\*(C'\fR, \f(CW\*(C`getgrnam_r_proto\*(C'\fR, \f(CW\*(C`gethostbyaddr_r_proto\*(C'\fR,
+\&\f(CW\*(C`gethostbyname_r_proto\*(C'\fR, \f(CW\*(C`gethostent_r_proto\*(C'\fR, \f(CW\*(C`getlogin_r_proto\*(C'\fR,
+\&\f(CW\*(C`getnetbyaddr_r_proto\*(C'\fR, \f(CW\*(C`getnetbyname_r_proto\*(C'\fR, \f(CW\*(C`getnetent_r_proto\*(C'\fR,
+\&\f(CW\*(C`getprotobyname_r_proto\*(C'\fR, \f(CW\*(C`getprotobynumber_r_proto\*(C'\fR,
+\&\f(CW\*(C`getprotoent_r_proto\*(C'\fR, \f(CW\*(C`getpwent_r_proto\*(C'\fR, \f(CW\*(C`getpwnam_r_proto\*(C'\fR,
+\&\f(CW\*(C`getpwuid_r_proto\*(C'\fR, \f(CW\*(C`getservbyname_r_proto\*(C'\fR, \f(CW\*(C`getservbyport_r_proto\*(C'\fR,
+\&\f(CW\*(C`getservent_r_proto\*(C'\fR, \f(CW\*(C`getspnam_r_proto\*(C'\fR, \f(CW\*(C`gidformat\*(C'\fR, \f(CW\*(C`gidsign\*(C'\fR,
+\&\f(CW\*(C`gidsize\*(C'\fR, \f(CW\*(C`gidtype\*(C'\fR, \f(CW\*(C`glibpth\*(C'\fR, \f(CW\*(C`gmake\*(C'\fR, \f(CW\*(C`gmtime_r_proto\*(C'\fR,
+\&\f(CW\*(C`gnulibc_version\*(C'\fR, \f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`groupcat\*(C'\fR, \f(CW\*(C`groupstype\*(C'\fR, \f(CW\*(C`gzip\*(C'\fR
+.IP h 4
+.IX Item "h"
+\&\f(CW\*(C`h_fcntl\*(C'\fR, \f(CW\*(C`h_sysfile\*(C'\fR, \f(CW\*(C`hint\*(C'\fR, \f(CW\*(C`hostcat\*(C'\fR, \f(CW\*(C`hostgenerate\*(C'\fR,
+\&\f(CW\*(C`hostosname\*(C'\fR, \f(CW\*(C`hostperl\*(C'\fR, \f(CW\*(C`html1dir\*(C'\fR, \f(CW\*(C`html1direxp\*(C'\fR, \f(CW\*(C`html3dir\*(C'\fR,
+\&\f(CW\*(C`html3direxp\*(C'\fR
+.IP i 4
+.IX Item "i"
+\&\f(CW\*(C`i16size\*(C'\fR, \f(CW\*(C`i16type\*(C'\fR, \f(CW\*(C`i32dformat\*(C'\fR, \f(CW\*(C`i32size\*(C'\fR, \f(CW\*(C`i32type\*(C'\fR, \f(CW\*(C`i64size\*(C'\fR,
+\&\f(CW\*(C`i64type\*(C'\fR, \f(CW\*(C`i8size\*(C'\fR, \f(CW\*(C`i8type\*(C'\fR, \f(CW\*(C`i_arpainet\*(C'\fR, \f(CW\*(C`i_bfd\*(C'\fR, \f(CW\*(C`i_bsdioctl\*(C'\fR,
+\&\f(CW\*(C`i_crypt\*(C'\fR, \f(CW\*(C`i_db\*(C'\fR, \f(CW\*(C`i_dbm\*(C'\fR, \f(CW\*(C`i_dirent\*(C'\fR, \f(CW\*(C`i_dlfcn\*(C'\fR, \f(CW\*(C`i_execinfo\*(C'\fR,
+\&\f(CW\*(C`i_fcntl\*(C'\fR, \f(CW\*(C`i_fenv\*(C'\fR, \f(CW\*(C`i_fp\*(C'\fR, \f(CW\*(C`i_fp_class\*(C'\fR, \f(CW\*(C`i_gdbm\*(C'\fR, \f(CW\*(C`i_gdbm_ndbm\*(C'\fR,
+\&\f(CW\*(C`i_gdbmndbm\*(C'\fR, \f(CW\*(C`i_grp\*(C'\fR, \f(CW\*(C`i_ieeefp\*(C'\fR, \f(CW\*(C`i_inttypes\*(C'\fR, \f(CW\*(C`i_langinfo\*(C'\fR,
+\&\f(CW\*(C`i_libutil\*(C'\fR, \f(CW\*(C`i_locale\*(C'\fR, \f(CW\*(C`i_machcthr\*(C'\fR, \f(CW\*(C`i_malloc\*(C'\fR, \f(CW\*(C`i_mallocmalloc\*(C'\fR,
+\&\f(CW\*(C`i_mntent\*(C'\fR, \f(CW\*(C`i_ndbm\*(C'\fR, \f(CW\*(C`i_netdb\*(C'\fR, \f(CW\*(C`i_neterrno\*(C'\fR, \f(CW\*(C`i_netinettcp\*(C'\fR,
+\&\f(CW\*(C`i_niin\*(C'\fR, \f(CW\*(C`i_poll\*(C'\fR, \f(CW\*(C`i_prot\*(C'\fR, \f(CW\*(C`i_pthread\*(C'\fR, \f(CW\*(C`i_pwd\*(C'\fR, \f(CW\*(C`i_quadmath\*(C'\fR,
+\&\f(CW\*(C`i_rpcsvcdbm\*(C'\fR, \f(CW\*(C`i_sgtty\*(C'\fR, \f(CW\*(C`i_shadow\*(C'\fR, \f(CW\*(C`i_socks\*(C'\fR, \f(CW\*(C`i_stdbool\*(C'\fR,
+\&\f(CW\*(C`i_stdint\*(C'\fR, \f(CW\*(C`i_stdlib\*(C'\fR, \f(CW\*(C`i_sunmath\*(C'\fR, \f(CW\*(C`i_sysaccess\*(C'\fR, \f(CW\*(C`i_sysdir\*(C'\fR,
+\&\f(CW\*(C`i_sysfile\*(C'\fR, \f(CW\*(C`i_sysfilio\*(C'\fR, \f(CW\*(C`i_sysin\*(C'\fR, \f(CW\*(C`i_sysioctl\*(C'\fR, \f(CW\*(C`i_syslog\*(C'\fR,
+\&\f(CW\*(C`i_sysmman\*(C'\fR, \f(CW\*(C`i_sysmode\*(C'\fR, \f(CW\*(C`i_sysmount\*(C'\fR, \f(CW\*(C`i_sysndir\*(C'\fR, \f(CW\*(C`i_sysparam\*(C'\fR,
+\&\f(CW\*(C`i_syspoll\*(C'\fR, \f(CW\*(C`i_sysresrc\*(C'\fR, \f(CW\*(C`i_syssecrt\*(C'\fR, \f(CW\*(C`i_sysselct\*(C'\fR, \f(CW\*(C`i_syssockio\*(C'\fR,
+\&\f(CW\*(C`i_sysstat\*(C'\fR, \f(CW\*(C`i_sysstatfs\*(C'\fR, \f(CW\*(C`i_sysstatvfs\*(C'\fR, \f(CW\*(C`i_syssyscall\*(C'\fR,
+\&\f(CW\*(C`i_systime\*(C'\fR, \f(CW\*(C`i_systimek\*(C'\fR, \f(CW\*(C`i_systimes\*(C'\fR, \f(CW\*(C`i_systypes\*(C'\fR, \f(CW\*(C`i_sysuio\*(C'\fR,
+\&\f(CW\*(C`i_sysun\*(C'\fR, \f(CW\*(C`i_sysutsname\*(C'\fR, \f(CW\*(C`i_sysvfs\*(C'\fR, \f(CW\*(C`i_syswait\*(C'\fR, \f(CW\*(C`i_termio\*(C'\fR,
+\&\f(CW\*(C`i_termios\*(C'\fR, \f(CW\*(C`i_time\*(C'\fR, \f(CW\*(C`i_unistd\*(C'\fR, \f(CW\*(C`i_ustat\*(C'\fR, \f(CW\*(C`i_utime\*(C'\fR, \f(CW\*(C`i_vfork\*(C'\fR,
+\&\f(CW\*(C`i_wchar\*(C'\fR, \f(CW\*(C`i_wctype\*(C'\fR, \f(CW\*(C`i_xlocale\*(C'\fR, \f(CW\*(C`ignore_versioned_solibs\*(C'\fR,
+\&\f(CW\*(C`inc_version_list\*(C'\fR, \f(CW\*(C`inc_version_list_init\*(C'\fR, \f(CW\*(C`incpath\*(C'\fR, \f(CW\*(C`incpth\*(C'\fR,
+\&\f(CW\*(C`inews\*(C'\fR, \f(CW\*(C`initialinstalllocation\*(C'\fR, \f(CW\*(C`installarchlib\*(C'\fR, \f(CW\*(C`installbin\*(C'\fR,
+\&\f(CW\*(C`installhtml1dir\*(C'\fR, \f(CW\*(C`installhtml3dir\*(C'\fR, \f(CW\*(C`installman1dir\*(C'\fR,
+\&\f(CW\*(C`installman3dir\*(C'\fR, \f(CW\*(C`installprefix\*(C'\fR, \f(CW\*(C`installprefixexp\*(C'\fR,
+\&\f(CW\*(C`installprivlib\*(C'\fR, \f(CW\*(C`installscript\*(C'\fR, \f(CW\*(C`installsitearch\*(C'\fR, \f(CW\*(C`installsitebin\*(C'\fR,
+\&\f(CW\*(C`installsitehtml1dir\*(C'\fR, \f(CW\*(C`installsitehtml3dir\*(C'\fR, \f(CW\*(C`installsitelib\*(C'\fR,
+\&\f(CW\*(C`installsiteman1dir\*(C'\fR, \f(CW\*(C`installsiteman3dir\*(C'\fR, \f(CW\*(C`installsitescript\*(C'\fR,
+\&\f(CW\*(C`installstyle\*(C'\fR, \f(CW\*(C`installusrbinperl\*(C'\fR, \f(CW\*(C`installvendorarch\*(C'\fR,
+\&\f(CW\*(C`installvendorbin\*(C'\fR, \f(CW\*(C`installvendorhtml1dir\*(C'\fR, \f(CW\*(C`installvendorhtml3dir\*(C'\fR,
+\&\f(CW\*(C`installvendorlib\*(C'\fR, \f(CW\*(C`installvendorman1dir\*(C'\fR, \f(CW\*(C`installvendorman3dir\*(C'\fR,
+\&\f(CW\*(C`installvendorscript\*(C'\fR, \f(CW\*(C`intsize\*(C'\fR, \f(CW\*(C`issymlink\*(C'\fR, \f(CW\*(C`ivdformat\*(C'\fR, \f(CW\*(C`ivsize\*(C'\fR,
+\&\f(CW\*(C`ivtype\*(C'\fR
+.IP k 4
+.IX Item "k"
+\&\f(CW\*(C`known_extensions\*(C'\fR, \f(CW\*(C`ksh\*(C'\fR
+.IP l 4
+.IX Item "l"
+\&\f(CW\*(C`ld\*(C'\fR, \f(CW\*(C`ld_can_script\*(C'\fR, \f(CW\*(C`lddlflags\*(C'\fR, \f(CW\*(C`ldflags\*(C'\fR,
+\&\f(CW\*(C`ldflags_uselargefiles\*(C'\fR, \f(CW\*(C`ldlibpthname\*(C'\fR, \f(CW\*(C`less\*(C'\fR, \f(CW\*(C`lib_ext\*(C'\fR, \f(CW\*(C`libc\*(C'\fR,
+\&\f(CW\*(C`libperl\*(C'\fR, \f(CW\*(C`libpth\*(C'\fR, \f(CW\*(C`libs\*(C'\fR, \f(CW\*(C`libsdirs\*(C'\fR, \f(CW\*(C`libsfiles\*(C'\fR, \f(CW\*(C`libsfound\*(C'\fR,
+\&\f(CW\*(C`libspath\*(C'\fR, \f(CW\*(C`libswanted\*(C'\fR, \f(CW\*(C`libswanted_uselargefiles\*(C'\fR, \f(CW\*(C`line\*(C'\fR, \f(CW\*(C`lint\*(C'\fR,
+\&\f(CW\*(C`lkflags\*(C'\fR, \f(CW\*(C`ln\*(C'\fR, \f(CW\*(C`lns\*(C'\fR, \f(CW\*(C`localtime_r_proto\*(C'\fR, \f(CW\*(C`locincpth\*(C'\fR,
+\&\f(CW\*(C`loclibpth\*(C'\fR, \f(CW\*(C`longdblinfbytes\*(C'\fR, \f(CW\*(C`longdblkind\*(C'\fR, \f(CW\*(C`longdblmantbits\*(C'\fR,
+\&\f(CW\*(C`longdblnanbytes\*(C'\fR, \f(CW\*(C`longdblsize\*(C'\fR, \f(CW\*(C`longlongsize\*(C'\fR, \f(CW\*(C`longsize\*(C'\fR, \f(CW\*(C`lp\*(C'\fR,
+\&\f(CW\*(C`lpr\*(C'\fR, \f(CW\*(C`ls\*(C'\fR, \f(CW\*(C`lseeksize\*(C'\fR, \f(CW\*(C`lseektype\*(C'\fR
+.IP m 4
+.IX Item "m"
+\&\f(CW\*(C`mail\*(C'\fR, \f(CW\*(C`mailx\*(C'\fR, \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_set_make\*(C'\fR, \f(CW\*(C`mallocobj\*(C'\fR, \f(CW\*(C`mallocsrc\*(C'\fR,
+\&\f(CW\*(C`malloctype\*(C'\fR, \f(CW\*(C`man1dir\*(C'\fR, \f(CW\*(C`man1direxp\*(C'\fR, \f(CW\*(C`man1ext\*(C'\fR, \f(CW\*(C`man3dir\*(C'\fR,
+\&\f(CW\*(C`man3direxp\*(C'\fR, \f(CW\*(C`man3ext\*(C'\fR, \f(CW\*(C`mips_type\*(C'\fR, \f(CW\*(C`mistrustnm\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR,
+\&\f(CW\*(C`mmaptype\*(C'\fR, \f(CW\*(C`modetype\*(C'\fR, \f(CW\*(C`more\*(C'\fR, \f(CW\*(C`multiarch\*(C'\fR, \f(CW\*(C`mv\*(C'\fR, \f(CW\*(C`myarchname\*(C'\fR,
+\&\f(CW\*(C`mydomain\*(C'\fR, \f(CW\*(C`myhostname\*(C'\fR, \f(CW\*(C`myuname\*(C'\fR
+.IP n 4
+.IX Item "n"
+\&\f(CW\*(C`n\*(C'\fR, \f(CW\*(C`need_va_copy\*(C'\fR, \f(CW\*(C`netdb_hlen_type\*(C'\fR, \f(CW\*(C`netdb_host_type\*(C'\fR,
+\&\f(CW\*(C`netdb_name_type\*(C'\fR, \f(CW\*(C`netdb_net_type\*(C'\fR, \f(CW\*(C`nm\*(C'\fR, \f(CW\*(C`nm_opt\*(C'\fR, \f(CW\*(C`nm_so_opt\*(C'\fR,
+\&\f(CW\*(C`nonxs_ext\*(C'\fR, \f(CW\*(C`nroff\*(C'\fR, \f(CW\*(C`nvEUformat\*(C'\fR, \f(CW\*(C`nvFUformat\*(C'\fR, \f(CW\*(C`nvGUformat\*(C'\fR,
+\&\f(CW\*(C`nv_overflows_integers_at\*(C'\fR, \f(CW\*(C`nv_preserves_uv_bits\*(C'\fR, \f(CW\*(C`nveformat\*(C'\fR,
+\&\f(CW\*(C`nvfformat\*(C'\fR, \f(CW\*(C`nvgformat\*(C'\fR, \f(CW\*(C`nvmantbits\*(C'\fR, \f(CW\*(C`nvsize\*(C'\fR, \f(CW\*(C`nvtype\*(C'\fR
+.IP o 4
+.IX Item "o"
+\&\f(CW\*(C`o_nonblock\*(C'\fR, \f(CW\*(C`obj_ext\*(C'\fR, \f(CW\*(C`old_pthread_create_joinable\*(C'\fR, \f(CW\*(C`optimize\*(C'\fR,
+\&\f(CW\*(C`orderlib\*(C'\fR, \f(CW\*(C`osname\*(C'\fR, \f(CW\*(C`osvers\*(C'\fR, \f(CW\*(C`otherlibdirs\*(C'\fR
+.IP p 4
+.IX Item "p"
+\&\f(CW\*(C`package\*(C'\fR, \f(CW\*(C`pager\*(C'\fR, \f(CW\*(C`passcat\*(C'\fR, \f(CW\*(C`patchlevel\*(C'\fR, \f(CW\*(C`path_sep\*(C'\fR, \f(CW\*(C`perl\*(C'\fR,
+\&\f(CW\*(C`perl5\*(C'\fR, \f(CW\*(C`perl_patchlevel\*(C'\fR, \f(CW\*(C`perl_static_inline\*(C'\fR, \f(CW\*(C`perl_thread_local\*(C'\fR,
+\&\f(CW\*(C`perladmin\*(C'\fR, \f(CW\*(C`perllibs\*(C'\fR, \f(CW\*(C`perlpath\*(C'\fR, \f(CW\*(C`pg\*(C'\fR, \f(CW\*(C`phostname\*(C'\fR, \f(CW\*(C`pidtype\*(C'\fR,
+\&\f(CW\*(C`plibpth\*(C'\fR, \f(CW\*(C`pmake\*(C'\fR, \f(CW\*(C`pr\*(C'\fR, \f(CW\*(C`prefix\*(C'\fR, \f(CW\*(C`prefixexp\*(C'\fR, \f(CW\*(C`privlib\*(C'\fR,
+\&\f(CW\*(C`privlibexp\*(C'\fR, \f(CW\*(C`procselfexe\*(C'\fR, \f(CW\*(C`ptrsize\*(C'\fR
+.IP q 4
+.IX Item "q"
+\&\f(CW\*(C`quadkind\*(C'\fR, \f(CW\*(C`quadtype\*(C'\fR
+.IP r 4
+.IX Item "r"
+\&\f(CW\*(C`randbits\*(C'\fR, \f(CW\*(C`randfunc\*(C'\fR, \f(CW\*(C`random_r_proto\*(C'\fR, \f(CW\*(C`randseedtype\*(C'\fR, \f(CW\*(C`ranlib\*(C'\fR,
+\&\f(CW\*(C`rd_nodata\*(C'\fR, \f(CW\*(C`readdir64_r_proto\*(C'\fR, \f(CW\*(C`readdir_r_proto\*(C'\fR, \f(CW\*(C`revision\*(C'\fR, \f(CW\*(C`rm\*(C'\fR,
+\&\f(CW\*(C`rm_try\*(C'\fR, \f(CW\*(C`rmail\*(C'\fR, \f(CW\*(C`run\*(C'\fR, \f(CW\*(C`runnm\*(C'\fR
+.IP s 4
+.IX Item "s"
+\&\f(CW\*(C`sGMTIME_max\*(C'\fR, \f(CW\*(C`sGMTIME_min\*(C'\fR, \f(CW\*(C`sLOCALTIME_max\*(C'\fR, \f(CW\*(C`sLOCALTIME_min\*(C'\fR,
+\&\f(CW\*(C`sPRIEUldbl\*(C'\fR, \f(CW\*(C`sPRIFUldbl\*(C'\fR, \f(CW\*(C`sPRIGUldbl\*(C'\fR, \f(CW\*(C`sPRIXU64\*(C'\fR, \f(CW\*(C`sPRId64\*(C'\fR,
+\&\f(CW\*(C`sPRIeldbl\*(C'\fR, \f(CW\*(C`sPRIfldbl\*(C'\fR, \f(CW\*(C`sPRIgldbl\*(C'\fR, \f(CW\*(C`sPRIi64\*(C'\fR, \f(CW\*(C`sPRIo64\*(C'\fR,
+\&\f(CW\*(C`sPRIu64\*(C'\fR, \f(CW\*(C`sPRIx64\*(C'\fR, \f(CW\*(C`sSCNfldbl\*(C'\fR, \f(CW\*(C`sched_yield\*(C'\fR, \f(CW\*(C`scriptdir\*(C'\fR,
+\&\f(CW\*(C`scriptdirexp\*(C'\fR, \f(CW\*(C`sed\*(C'\fR, \f(CW\*(C`seedfunc\*(C'\fR, \f(CW\*(C`selectminbits\*(C'\fR, \f(CW\*(C`selecttype\*(C'\fR,
+\&\f(CW\*(C`sendmail\*(C'\fR, \f(CW\*(C`setgrent_r_proto\*(C'\fR, \f(CW\*(C`sethostent_r_proto\*(C'\fR,
+\&\f(CW\*(C`setlocale_r_proto\*(C'\fR, \f(CW\*(C`setnetent_r_proto\*(C'\fR, \f(CW\*(C`setprotoent_r_proto\*(C'\fR,
+\&\f(CW\*(C`setpwent_r_proto\*(C'\fR, \f(CW\*(C`setservent_r_proto\*(C'\fR, \f(CW\*(C`sh\*(C'\fR, \f(CW\*(C`shar\*(C'\fR, \f(CW\*(C`sharpbang\*(C'\fR,
+\&\f(CW\*(C`shmattype\*(C'\fR, \f(CW\*(C`shortsize\*(C'\fR, \f(CW\*(C`shrpenv\*(C'\fR, \f(CW\*(C`shsharp\*(C'\fR, \f(CW\*(C`sig_count\*(C'\fR,
+\&\f(CW\*(C`sig_name\*(C'\fR, \f(CW\*(C`sig_name_init\*(C'\fR, \f(CW\*(C`sig_num\*(C'\fR, \f(CW\*(C`sig_num_init\*(C'\fR, \f(CW\*(C`sig_size\*(C'\fR,
+\&\f(CW\*(C`signal_t\*(C'\fR, \f(CW\*(C`sitearch\*(C'\fR, \f(CW\*(C`sitearchexp\*(C'\fR, \f(CW\*(C`sitebin\*(C'\fR, \f(CW\*(C`sitebinexp\*(C'\fR,
+\&\f(CW\*(C`sitehtml1dir\*(C'\fR, \f(CW\*(C`sitehtml1direxp\*(C'\fR, \f(CW\*(C`sitehtml3dir\*(C'\fR, \f(CW\*(C`sitehtml3direxp\*(C'\fR,
+\&\f(CW\*(C`sitelib\*(C'\fR, \f(CW\*(C`sitelib_stem\*(C'\fR, \f(CW\*(C`sitelibexp\*(C'\fR, \f(CW\*(C`siteman1dir\*(C'\fR,
+\&\f(CW\*(C`siteman1direxp\*(C'\fR, \f(CW\*(C`siteman3dir\*(C'\fR, \f(CW\*(C`siteman3direxp\*(C'\fR, \f(CW\*(C`siteprefix\*(C'\fR,
+\&\f(CW\*(C`siteprefixexp\*(C'\fR, \f(CW\*(C`sitescript\*(C'\fR, \f(CW\*(C`sitescriptexp\*(C'\fR, \f(CW\*(C`sizesize\*(C'\fR,
+\&\f(CW\*(C`sizetype\*(C'\fR, \f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`smail\*(C'\fR, \f(CW\*(C`so\*(C'\fR, \f(CW\*(C`sockethdr\*(C'\fR, \f(CW\*(C`socketlib\*(C'\fR,
+\&\f(CW\*(C`socksizetype\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, \f(CW\*(C`spackage\*(C'\fR, \f(CW\*(C`spitshell\*(C'\fR, \f(CW\*(C`srand48_r_proto\*(C'\fR,
+\&\f(CW\*(C`srandom_r_proto\*(C'\fR, \f(CW\*(C`src\*(C'\fR, \f(CW\*(C`ssizetype\*(C'\fR, \f(CW\*(C`st_dev_sign\*(C'\fR, \f(CW\*(C`st_dev_size\*(C'\fR,
+\&\f(CW\*(C`st_ino_sign\*(C'\fR, \f(CW\*(C`st_ino_size\*(C'\fR, \f(CW\*(C`startperl\*(C'\fR, \f(CW\*(C`startsh\*(C'\fR, \f(CW\*(C`static_ext\*(C'\fR,
+\&\f(CW\*(C`stdchar\*(C'\fR, \f(CW\*(C`stdio_base\*(C'\fR, \f(CW\*(C`stdio_bufsiz\*(C'\fR, \f(CW\*(C`stdio_cnt\*(C'\fR, \f(CW\*(C`stdio_filbuf\*(C'\fR,
+\&\f(CW\*(C`stdio_ptr\*(C'\fR, \f(CW\*(C`stdio_stream_array\*(C'\fR, \f(CW\*(C`strerror_r_proto\*(C'\fR, \f(CW\*(C`submit\*(C'\fR,
+\&\f(CW\*(C`subversion\*(C'\fR, \f(CW\*(C`sysman\*(C'\fR, \f(CW\*(C`sysroot\*(C'\fR
+.IP t 4
+.IX Item "t"
+\&\f(CW\*(C`tail\*(C'\fR, \f(CW\*(C`taint_disabled\*(C'\fR, \f(CW\*(C`taint_support\*(C'\fR, \f(CW\*(C`tar\*(C'\fR, \f(CW\*(C`targetarch\*(C'\fR,
+\&\f(CW\*(C`targetdir\*(C'\fR, \f(CW\*(C`targetenv\*(C'\fR, \f(CW\*(C`targethost\*(C'\fR, \f(CW\*(C`targetmkdir\*(C'\fR, \f(CW\*(C`targetport\*(C'\fR,
+\&\f(CW\*(C`targetsh\*(C'\fR, \f(CW\*(C`tbl\*(C'\fR, \f(CW\*(C`tee\*(C'\fR, \f(CW\*(C`test\*(C'\fR, \f(CW\*(C`timeincl\*(C'\fR, \f(CW\*(C`timetype\*(C'\fR,
+\&\f(CW\*(C`tmpnam_r_proto\*(C'\fR, \f(CW\*(C`to\*(C'\fR, \f(CW\*(C`touch\*(C'\fR, \f(CW\*(C`tr\*(C'\fR, \f(CW\*(C`trnl\*(C'\fR, \f(CW\*(C`troff\*(C'\fR,
+\&\f(CW\*(C`ttyname_r_proto\*(C'\fR
+.IP u 4
+.IX Item "u"
+\&\f(CW\*(C`u16size\*(C'\fR, \f(CW\*(C`u16type\*(C'\fR, \f(CW\*(C`u32XUformat\*(C'\fR, \f(CW\*(C`u32oformat\*(C'\fR, \f(CW\*(C`u32size\*(C'\fR,
+\&\f(CW\*(C`u32type\*(C'\fR, \f(CW\*(C`u32uformat\*(C'\fR, \f(CW\*(C`u32xformat\*(C'\fR, \f(CW\*(C`u64size\*(C'\fR, \f(CW\*(C`u64type\*(C'\fR,
+\&\f(CW\*(C`u8size\*(C'\fR, \f(CW\*(C`u8type\*(C'\fR, \f(CW\*(C`uidformat\*(C'\fR, \f(CW\*(C`uidsign\*(C'\fR, \f(CW\*(C`uidsize\*(C'\fR, \f(CW\*(C`uidtype\*(C'\fR,
+\&\f(CW\*(C`uname\*(C'\fR, \f(CW\*(C`uniq\*(C'\fR, \f(CW\*(C`uquadtype\*(C'\fR, \f(CW\*(C`use64bitall\*(C'\fR, \f(CW\*(C`use64bitint\*(C'\fR,
+\&\f(CW\*(C`usecbacktrace\*(C'\fR, \f(CW\*(C`usecrosscompile\*(C'\fR, \f(CW\*(C`usedefaultstrict\*(C'\fR, \f(CW\*(C`usedevel\*(C'\fR,
+\&\f(CW\*(C`usedl\*(C'\fR, \f(CW\*(C`usedtrace\*(C'\fR, \f(CW\*(C`usefaststdio\*(C'\fR, \f(CW\*(C`useithreads\*(C'\fR,
+\&\f(CW\*(C`usekernprocpathname\*(C'\fR, \f(CW\*(C`uselanginfo\*(C'\fR, \f(CW\*(C`uselargefiles\*(C'\fR, \f(CW\*(C`uselongdouble\*(C'\fR,
+\&\f(CW\*(C`usemallocwrap\*(C'\fR, \f(CW\*(C`usemorebits\*(C'\fR, \f(CW\*(C`usemultiplicity\*(C'\fR, \f(CW\*(C`usemymalloc\*(C'\fR,
+\&\f(CW\*(C`usenm\*(C'\fR, \f(CW\*(C`usensgetexecutablepath\*(C'\fR, \f(CW\*(C`useopcode\*(C'\fR, \f(CW\*(C`useperlio\*(C'\fR,
+\&\f(CW\*(C`useposix\*(C'\fR, \f(CW\*(C`usequadmath\*(C'\fR, \f(CW\*(C`usereentrant\*(C'\fR, \f(CW\*(C`userelocatableinc\*(C'\fR,
+\&\f(CW\*(C`useshrplib\*(C'\fR, \f(CW\*(C`usesitecustomize\*(C'\fR, \f(CW\*(C`usesocks\*(C'\fR, \f(CW\*(C`usethreads\*(C'\fR,
+\&\f(CW\*(C`usevendorprefix\*(C'\fR, \f(CW\*(C`useversionedarchname\*(C'\fR, \f(CW\*(C`usevfork\*(C'\fR, \f(CW\*(C`usrinc\*(C'\fR,
+\&\f(CW\*(C`uuname\*(C'\fR, \f(CW\*(C`uvXUformat\*(C'\fR, \f(CW\*(C`uvoformat\*(C'\fR, \f(CW\*(C`uvsize\*(C'\fR, \f(CW\*(C`uvtype\*(C'\fR, \f(CW\*(C`uvuformat\*(C'\fR,
+\&\f(CW\*(C`uvxformat\*(C'\fR
+.IP v 4
+.IX Item "v"
+\&\f(CW\*(C`vendorarch\*(C'\fR, \f(CW\*(C`vendorarchexp\*(C'\fR, \f(CW\*(C`vendorbin\*(C'\fR, \f(CW\*(C`vendorbinexp\*(C'\fR,
+\&\f(CW\*(C`vendorhtml1dir\*(C'\fR, \f(CW\*(C`vendorhtml1direxp\*(C'\fR, \f(CW\*(C`vendorhtml3dir\*(C'\fR,
+\&\f(CW\*(C`vendorhtml3direxp\*(C'\fR, \f(CW\*(C`vendorlib\*(C'\fR, \f(CW\*(C`vendorlib_stem\*(C'\fR, \f(CW\*(C`vendorlibexp\*(C'\fR,
+\&\f(CW\*(C`vendorman1dir\*(C'\fR, \f(CW\*(C`vendorman1direxp\*(C'\fR, \f(CW\*(C`vendorman3dir\*(C'\fR,
+\&\f(CW\*(C`vendorman3direxp\*(C'\fR, \f(CW\*(C`vendorprefix\*(C'\fR, \f(CW\*(C`vendorprefixexp\*(C'\fR, \f(CW\*(C`vendorscript\*(C'\fR,
+\&\f(CW\*(C`vendorscriptexp\*(C'\fR, \f(CW\*(C`version\*(C'\fR, \f(CW\*(C`version_patchlevel_string\*(C'\fR,
+\&\f(CW\*(C`versiononly\*(C'\fR, \f(CW\*(C`vi\*(C'\fR
+.IP x 4
+.IX Item "x"
+\&\f(CW\*(C`xlibpth\*(C'\fR, \f(CW\*(C`xlocale_needed\*(C'\fR
+.IP y 4
+.IX Item "y"
+\&\f(CW\*(C`yacc\*(C'\fR, \f(CW\*(C`yaccflags\*(C'\fR
+.IP z 4
+.IX Item "z"
+\&\f(CW\*(C`zcat\*(C'\fR, \f(CW\*(C`zip\*(C'\fR
+.IP "GIT DATA" 4
+.IX Item "GIT DATA"
+.PD 0
+.IP NOTE 4
+.IX Item "NOTE"
+.PD
+.SS "Config::Extensions \- hash lookup of which core extensions were built."
+.IX Subsection "Config::Extensions - hash lookup of which core extensions were built."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+dynamic, nonxs, static
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "Config::Perl::V \- Structured data retrieval of perl \-V output"
+.IX Subsection "Config::Perl::V - Structured data retrieval of perl -V output"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "$conf = myconfig ()" 4
+.el .IP "\f(CW$conf\fR = myconfig ()" 4
+.IX Item "$conf = myconfig ()"
+.ie n .IP "$conf = plv2hash ($text [, ...])" 4
+.el .IP "\f(CW$conf\fR = plv2hash ($text [, ...])" 4
+.IX Item "$conf = plv2hash ($text [, ...])"
+.ie n .IP "$info = summary ([$conf])" 4
+.el .IP "\f(CW$info\fR = summary ([$conf])" 4
+.IX Item "$info = summary ([$conf])"
+.ie n .IP "$md5 = signature ([$conf])" 4
+.el .IP "\f(CW$md5\fR = signature ([$conf])" 4
+.IX Item "$md5 = signature ([$conf])"
+.IP "The hash structure" 4
+.IX Item "The hash structure"
+.PD
+build, osname, stamp, options, derived, patches, environment, config, inc
+.RE
+.RS 4
+.RE
+.IP REASONING 4
+.IX Item "REASONING"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP TODO 4
+.IX Item "TODO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Cwd \- get pathname of current working directory"
+.IX Subsection "Cwd - get pathname of current working directory"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "getcwd and friends" 4
+.IX Item "getcwd and friends"
+.PD
+getcwd, cwd, fastcwd, fastgetcwd, getdcwd
+.IP "abs_path and friends" 4
+.IX Item "abs_path and friends"
+abs_path, realpath, fast_abs_path
+.ie n .IP $ENV{PWD} 4
+.el .IP \f(CW$ENV\fR{PWD} 4
+.IX Item "$ENV{PWD}"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP NOTES 4
+.IX Item "NOTES"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "DB \- programmatic interface to the Perl debugging API"
+.IX Subsection "DB - programmatic interface to the Perl debugging API"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.PD
+.Vb 3
+\& $DB::sub,  %DB::sub,  $DB::single,  $DB::signal,  $DB::trace,  @DB::args, 
+\&@DB::dbline,  %DB::dbline,  $DB::package,  $DB::filename,  $DB::subname, 
+\&$DB::lineno
+.Ve
+.IP "API Methods" 4
+.IX Item "API Methods"
+CLIENT\->\fBregister()\fR, CLIENT\->evalcode(STRING), CLIENT\->skippkg('D::hide'),
+CLIENT\->\fBrun()\fR, CLIENT\->\fBstep()\fR, CLIENT\->\fBnext()\fR, CLIENT\->\fBdone()\fR
+.IP "Client Callback Methods" 4
+.IX Item "Client Callback Methods"
+CLIENT\->\fBinit()\fR, CLIENT\->prestop([STRING]), CLIENT\->\fBstop()\fR, CLIENT\->\fBidle()\fR,
+CLIENT\->poststop([STRING]), CLIENT\->evalcode(STRING), CLIENT\->\fBcleanup()\fR,
+CLIENT\->output(LIST)
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter \-\- Filter DBM keys/values"
+.IX Subsection "DBM_Filter -- Filter DBM keys/values"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "What is a DBM Filter?" 4
+.IX Item "What is a DBM Filter?"
+.RS 4
+.IP "So what's new?" 4
+.IX Item "So what's new?"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.ie n .IP "$db\->\fBFilter_Push()\fR / $db\->\fBFilter_Key_Push()\fR / $db\->\fBFilter_Value_Push()\fR" 4
+.el .IP "\f(CW$db\fR\->\fBFilter_Push()\fR / \f(CW$db\fR\->\fBFilter_Key_Push()\fR / \f(CW$db\fR\->\fBFilter_Value_Push()\fR" 4
+.IX Item "$db->Filter_Push() / $db->Filter_Key_Push() / $db->Filter_Value_Push()"
+.PD
+Filter_Push, Filter_Key_Push, Filter_Value_Push
+.ie n .IP $db\->\fBFilter_Pop()\fR 4
+.el .IP \f(CW$db\fR\->\fBFilter_Pop()\fR 4
+.IX Item "$db->Filter_Pop()"
+.PD 0
+.ie n .IP $db\->\fBFiltered()\fR 4
+.el .IP \f(CW$db\fR\->\fBFiltered()\fR 4
+.IX Item "$db->Filtered()"
+.RE
+.RS 4
+.RE
+.IP "Writing a Filter" 4
+.IX Item "Writing a Filter"
+.RS 4
+.IP "Immediate Filters" 4
+.IX Item "Immediate Filters"
+.IP "Canned Filters" 4
+.IX Item "Canned Filters"
+.PD
+"name", params
+.RE
+.RS 4
+.RE
+.IP "Filters Included" 4
+.IX Item "Filters Included"
+utf8, encode, compress, int32, null
+.IP NOTES 4
+.IX Item "NOTES"
+.RS 4
+.PD 0
+.IP "Maintain Round Trip Integrity" 4
+.IX Item "Maintain Round Trip Integrity"
+.IP "Don't mix filtered & non-filtered data in the same database file." 4
+.IX Item "Don't mix filtered & non-filtered data in the same database file."
+.RE
+.RS 4
+.RE
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter::compress \- filter for DBM_Filter"
+.IX Subsection "DBM_Filter::compress - filter for DBM_Filter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter::encode \- filter for DBM_Filter"
+.IX Subsection "DBM_Filter::encode - filter for DBM_Filter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter::int32 \- filter for DBM_Filter"
+.IX Subsection "DBM_Filter::int32 - filter for DBM_Filter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter::null \- filter for DBM_Filter"
+.IX Subsection "DBM_Filter::null - filter for DBM_Filter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DBM_Filter::utf8 \- filter for DBM_Filter"
+.IX Subsection "DBM_Filter::utf8 - filter for DBM_Filter"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "DB_File \- Perl5 access to Berkeley DB version 1.x"
+.IX Subsection "DB_File - Perl5 access to Berkeley DB version 1.x"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBDB_HASH\fR, \fBDB_BTREE\fR, \fBDB_RECNO\fR
+.RS 4
+.IP "Using DB_File with Berkeley DB version 2 or greater" 4
+.IX Item "Using DB_File with Berkeley DB version 2 or greater"
+.PD 0
+.IP "Interface to Berkeley DB" 4
+.IX Item "Interface to Berkeley DB"
+.IP "Opening a Berkeley DB Database File" 4
+.IX Item "Opening a Berkeley DB Database File"
+.IP "Default Parameters" 4
+.IX Item "Default Parameters"
+.IP "In Memory Databases" 4
+.IX Item "In Memory Databases"
+.RE
+.RS 4
+.RE
+.IP DB_HASH 4
+.IX Item "DB_HASH"
+.RS 4
+.IP "A Simple Example" 4
+.IX Item "A Simple Example"
+.RE
+.RS 4
+.RE
+.IP DB_BTREE 4
+.IX Item "DB_BTREE"
+.RS 4
+.IP "Changing the BTREE sort order" 4
+.IX Item "Changing the BTREE sort order"
+.IP "Handling Duplicate Keys" 4
+.IX Item "Handling Duplicate Keys"
+.IP "The \fBget_dup()\fR Method" 4
+.IX Item "The get_dup() Method"
+.IP "The \fBfind_dup()\fR Method" 4
+.IX Item "The find_dup() Method"
+.IP "The \fBdel_dup()\fR Method" 4
+.IX Item "The del_dup() Method"
+.IP "Matching Partial Keys" 4
+.IX Item "Matching Partial Keys"
+.RE
+.RS 4
+.RE
+.IP DB_RECNO 4
+.IX Item "DB_RECNO"
+.RS 4
+.IP "The 'bval' Option" 4
+.IX Item "The 'bval' Option"
+.IP "A Simple Example" 4
+.IX Item "A Simple Example"
+.IP "Extra RECNO Methods" 4
+.IX Item "Extra RECNO Methods"
+.PD
+\&\fR\f(CB$X\fR\fB\->push(list) ;\fR, \fB\fR\f(CB$value\fR\fB = \fR\f(CB$X\fR\fB\->pop ;\fR, \fB\fR\f(CB$X\fR\fB\->shift\fR,
+\&\fB\fR\f(CB$X\fR\fB\->unshift(list) ;\fR, \fB\fR\f(CB$X\fR\fB\->length\fR, \fB\fR\f(CB$X\fR\fB\->splice(offset,
+length, elements);\fR
+.IP "Another Example" 4
+.IX Item "Another Example"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "THE API INTERFACE" 4
+.IX Item "THE API INTERFACE"
+.PD
+\&\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->get($key, \fR\f(CB$value\fR\fB [, \fR\f(CB$flags\fR\fB]) ;\fR, \fB\fR\f(CB$status\fR\fB =
+\&\fR\f(CB$X\fR\fB\->put($key, \fR\f(CB$value\fR\fB [, \fR\f(CB$flags\fR\fB]) ;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->del($key [,
+\&\fR\f(CB$flags\fR\fB]) ;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->fd ;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->seq($key,
+\&\fR\f(CB$value\fR\fB, \fR\f(CB$flags\fR\fB) ;\fR, \fB\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->sync([$flags]) ;\fR
+.IP "DBM FILTERS" 4
+.IX Item "DBM FILTERS"
+.RS 4
+.PD 0
+.IP "DBM Filter Low-level API" 4
+.IX Item "DBM Filter Low-level API"
+.PD
+\&\fBfilter_store_key\fR, \fBfilter_store_value\fR, \fBfilter_fetch_key\fR,
+\&\fBfilter_fetch_value\fR
+.IP "The Filter" 4
+.IX Item "The Filter"
+.PD 0
+.IP "An Example \-\- the NULL termination problem." 4
+.IX Item "An Example -- the NULL termination problem."
+.IP "Another Example \-\- Key is a C int." 4
+.IX Item "Another Example -- Key is a C int."
+.RE
+.RS 4
+.RE
+.IP "HINTS AND TIPS" 4
+.IX Item "HINTS AND TIPS"
+.RS 4
+.IP "Locking: The Trouble with fd" 4
+.IX Item "Locking: The Trouble with fd"
+.IP "Safe ways to lock a database" 4
+.IX Item "Safe ways to lock a database"
+.PD
+\&\fBTie::DB_Lock\fR, \fBTie::DB_LockFile\fR, \fBDB_File::Lock\fR
+.IP "Sharing Databases With C Applications" 4
+.IX Item "Sharing Databases With C Applications"
+.PD 0
+.IP "The \fBuntie()\fR Gotcha" 4
+.IX Item "The untie() Gotcha"
+.RE
+.RS 4
+.RE
+.IP "COMMON QUESTIONS" 4
+.IX Item "COMMON QUESTIONS"
+.RS 4
+.IP "Why is there Perl source in my database?" 4
+.IX Item "Why is there Perl source in my database?"
+.IP "How do I store complex data structures with DB_File?" 4
+.IX Item "How do I store complex data structures with DB_File?"
+.IP "What does ""wide character in subroutine entry"" mean?" 4
+.IX Item "What does ""wide character in subroutine entry"" mean?"
+.IP "What does ""Invalid Argument"" mean?" 4
+.IX Item "What does ""Invalid Argument"" mean?"
+.IP "What does ""Bareword 'DB_File' not allowed"" mean?" 4
+.IX Item "What does ""Bareword 'DB_File' not allowed"" mean?"
+.RE
+.RS 4
+.RE
+.IP REFERENCES 4
+.IX Item "REFERENCES"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AVAILABILITY 4
+.IX Item "AVAILABILITY"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.ie n .SS "Data::Dumper \- stringified perl data structures, suitable for both printing and ""eval"""
+.el .SS "Data::Dumper \- stringified perl data structures, suitable for both printing and \f(CWeval\fP"
+.IX Subsection "Data::Dumper - stringified perl data structures, suitable for both printing and eval"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\fIPACKAGE\fR\->new(\fIARRAYREF [\fR, \fIARRAYREF]\fR), \fR\f(CI$OBJ\fR\fI\fR\->Dump  \fIor\fR 
+\&\fIPACKAGE\fR\->Dump(\fIARRAYREF [\fR, \fIARRAYREF]\fR), \fI\fR\f(CI$OBJ\fR\fI\fR\->Seen(\fI[HASHREF]\fR),
+\&\fI\fR\f(CI$OBJ\fR\fI\fR\->Values(\fI[ARRAYREF]\fR), \fI\fR\f(CI$OBJ\fR\fI\fR\->Names(\fI[ARRAYREF]\fR),
+\&\fI\fR\f(CI$OBJ\fR\fI\fR\->Reset
+.IP Functions 4
+.IX Item "Functions"
+Dumper(\fILIST\fR)
+.IP "Configuration Variables or Methods" 4
+.IX Item "Configuration Variables or Methods"
+.PD 0
+.IP Exports 4
+.IX Item "Exports"
+.PD
+Dumper
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.RS 4
+.IP NOTE 4
+.IX Item "NOTE"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Devel::PPPort \- Perl/Pollution/Portability"
+.IX Subsection "Devel::PPPort - Perl/Pollution/Portability"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "Start using Devel::PPPort for XS projects" 4
+.IX Item "Start using Devel::PPPort for XS projects"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Why use ppport.h?" 4
+.IX Item "Why use ppport.h?"
+.IP "How to use ppport.h" 4
+.IX Item "How to use ppport.h"
+.IP "Running ppport.h" 4
+.IX Item "Running ppport.h"
+.RE
+.RS 4
+.RE
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP WriteFile 4
+.IX Item "WriteFile"
+.IP GetFileContents 4
+.IX Item "GetFileContents"
+.RE
+.RS 4
+.RE
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.RS 4
+.IP "Provided Perl compatibility API" 4
+.IX Item "Provided Perl compatibility API"
+.IP "Supported Perl API, sorted by version" 4
+.IX Item "Supported Perl API, sorted by version"
+.PD
+perl 5.35.9, perl 5.35.8, perl 5.35.7, perl 5.35.6, perl 5.35.5, perl
+5.35.4, perl 5.35.1, perl 5.33.8, perl 5.33.7, perl 5.33.5, perl 5.33.2,
+perl 5.32.1, perl 5.31.9, perl 5.31.7, perl 5.31.5, perl 5.31.4, perl
+5.31.3, perl 5.29.10, perl 5.29.9, perl 5.27.11, perl 5.27.9, perl 5.27.8,
+perl 5.27.7, perl 5.27.6, perl 5.27.5, perl 5.27.4, perl 5.27.3, perl
+5.27.2, perl 5.27.1, perl 5.25.11, perl 5.25.10, perl 5.25.9, perl 5.25.8,
+perl 5.25.7, perl 5.25.6, perl 5.25.5, perl 5.25.4, perl 5.25.3, perl
+5.25.2, perl 5.25.1, perl 5.24.0, perl 5.23.9, perl 5.23.8, perl 5.23.6,
+perl 5.23.5, perl 5.23.2, perl 5.23.0, perl 5.21.10, perl 5.21.9, perl
+5.21.8, perl 5.21.7, perl 5.21.6, perl 5.21.5, perl 5.21.4, perl 5.21.3,
+perl 5.21.2, perl 5.21.1, perl 5.19.10, perl 5.19.9, perl 5.19.7, perl
+5.19.5, perl 5.19.4, perl 5.19.3, perl 5.19.2, perl 5.19.1, perl 5.18.0,
+perl 5.17.11, perl 5.17.8, perl 5.17.7, perl 5.17.6, perl 5.17.5, perl
+5.17.4, perl 5.17.2, perl 5.17.1, perl 5.16.0, perl 5.15.8, perl 5.15.7,
+perl 5.15.6, perl 5.15.4, perl 5.15.3, perl 5.15.2, perl 5.15.1, perl
+5.13.10, perl 5.13.9, perl 5.13.8, perl 5.13.7, perl 5.13.6, perl 5.13.5,
+perl 5.13.4, perl 5.13.3, perl 5.13.2, perl 5.13.1, perl 5.13.0, perl
+5.11.5, perl 5.11.4, perl 5.11.2, perl 5.11.0, perl 5.10.1, perl 5.10.0,
+perl 5.9.5, perl 5.9.4, perl 5.9.3, perl 5.9.2, perl 5.9.1, perl 5.9.0,
+perl 5.8.9, perl 5.8.8, perl 5.8.3, perl 5.8.1, perl 5.8.0, perl 5.7.3,
+perl 5.7.2, perl 5.7.1, perl 5.7.0, perl 5.6.1, perl 5.6.0, perl 5.005_03,
+perl 5.005, perl 5.004_05, perl 5.004, perl 5.003_07 (or maybe earlier),
+Backported version unknown
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Devel::Peek \- A data debugging tool for the XS programmer"
+.IX Subsection "Devel::Peek - A data debugging tool for the XS programmer"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Runtime debugging" 4
+.IX Item "Runtime debugging"
+.IP "Memory footprint debugging" 4
+.IX Item "Memory footprint debugging"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "A simple scalar string" 4
+.IX Item "A simple scalar string"
+.IP "A simple scalar number" 4
+.IX Item "A simple scalar number"
+.IP "A simple scalar with an extra reference" 4
+.IX Item "A simple scalar with an extra reference"
+.IP "A reference to a simple scalar" 4
+.IX Item "A reference to a simple scalar"
+.IP "A reference to an array" 4
+.IX Item "A reference to an array"
+.IP "A reference to a hash" 4
+.IX Item "A reference to a hash"
+.IP "Dumping a large array or hash" 4
+.IX Item "Dumping a large array or hash"
+.IP "A reference to an SV which holds a C pointer" 4
+.IX Item "A reference to an SV which holds a C pointer"
+.IP "A reference to a subroutine" 4
+.IX Item "A reference to a subroutine"
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Devel::SelfStubber \- generate stubs for a SelfLoading module"
+.IX Subsection "Devel::SelfStubber - generate stubs for a SelfLoading module"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Digest \- Modules that calculate message digests"
+.IX Subsection "Digest - Modules that calculate message digests"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fIbinary\fR, \fIhex\fR, \fIbase64\fR
+.IP "OO INTERFACE" 4
+.IX Item "OO INTERFACE"
+\&\f(CW$ctx\fR = Digest\->XXX($arg,...), \f(CW$ctx\fR = Digest\->new(XXX => \f(CW$arg\fR,...), \f(CW$ctx\fR =
+Digest::XXX\->new($arg,...), \f(CW$other_ctx\fR = \f(CW$ctx\fR\->clone, \f(CW$ctx\fR\->reset,
+\&\f(CW$ctx\fR\->add( \f(CW$data\fR ), \f(CW$ctx\fR\->add( \f(CW$chunk1\fR, \f(CW$chunk2\fR, ... ), \f(CW$ctx\fR\->addfile(
+\&\f(CW$io_handle\fR ), \f(CW$ctx\fR\->add_bits( \f(CW$data\fR, \f(CW$nbits\fR ), \f(CW$ctx\fR\->add_bits( \f(CW$bitstring\fR
+), \f(CW$ctx\fR\->digest, \f(CW$ctx\fR\->hexdigest, \f(CW$ctx\fR\->b64digest,
+\&\f(CW$ctx\fR\->base64_padded_digest
+.IP "Digest speed" 4
+.IX Item "Digest speed"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Digest::MD5 \- Perl interface to the MD5 Algorithm"
+.IX Subsection "Digest::MD5 - Perl interface to the MD5 Algorithm"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+md5($data,...), md5_hex($data,...), md5_base64($data,...)
+.IP METHODS 4
+.IX Item "METHODS"
+\&\f(CW$md5\fR = Digest::MD5\->new, \f(CW$md5\fR\->reset, \f(CW$md5\fR\->clone, \f(CW$md5\fR\->add($data,...),
+\&\f(CW$md5\fR\->addfile($io_handle), \f(CW$md5\fR\->add_bits($data, \f(CW$nbits\fR),
+\&\f(CW$md5\fR\->add_bits($bitstring), \f(CW$md5\fR\->digest, \f(CW$md5\fR\->hexdigest, \f(CW$md5\fR\->b64digest,
+\&\f(CW@ctx\fR = \f(CW$md5\fR\->context, \f(CW$md5\fR\->context(@ctx)
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "Digest::SHA \- Perl extension for SHA\-1/224/256/384/512"
+.IX Subsection "Digest::SHA - Perl extension for SHA-1/224/256/384/512"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "SYNOPSIS (HMAC-SHA)" 4
+.IX Item "SYNOPSIS (HMAC-SHA)"
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "UNICODE AND SIDE EFFECTS" 4
+.IX Item "UNICODE AND SIDE EFFECTS"
+.IP "NIST STATEMENT ON SHA\-1" 4
+.IX Item "NIST STATEMENT ON SHA-1"
+.IP "PADDING OF BASE64 DIGESTS" 4
+.IX Item "PADDING OF BASE64 DIGESTS"
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP "EXPORTABLE FUNCTIONS" 4
+.IX Item "EXPORTABLE FUNCTIONS"
+.PD
+\&\fBsha1($data, ...)\fR, \fBsha224($data, ...)\fR, \fBsha256($data, ...)\fR,
+\&\fBsha384($data, ...)\fR, \fBsha512($data, ...)\fR, \fBsha512224($data, ...)\fR,
+\&\fBsha512256($data, ...)\fR, \fBsha1_hex($data, ...)\fR, \fBsha224_hex($data,
+\&...)\fR, \fBsha256_hex($data, ...)\fR, \fBsha384_hex($data, ...)\fR,
+\&\fBsha512_hex($data, ...)\fR, \fBsha512224_hex($data, ...)\fR,
+\&\fBsha512256_hex($data, ...)\fR, \fBsha1_base64($data, ...)\fR,
+\&\fBsha224_base64($data, ...)\fR, \fBsha256_base64($data, ...)\fR,
+\&\fBsha384_base64($data, ...)\fR, \fBsha512_base64($data, ...)\fR,
+\&\fBsha512224_base64($data, ...)\fR, \fBsha512256_base64($data, ...)\fR,
+\&\fBnew($alg)\fR, \fBreset($alg)\fR, \fBhashsize\fR, \fBalgorithm\fR, \fBclone\fR,
+\&\fBadd($data, ...)\fR, \fBadd_bits($data, \fR\f(CB$nbits\fR\fB)\fR, \fBadd_bits($bits)\fR,
+\&\fBaddfile(*FILE)\fR, \fBaddfile($filename [, \fR\f(CB$mode\fR\fB])\fR, \fBgetstate\fR,
+\&\fBputstate($str)\fR, \fBdump($filename)\fR, \fBload($filename)\fR, \fBdigest\fR,
+\&\fBhexdigest\fR, \fBb64digest\fR, \fBhmac_sha1($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha224($data,
+\&\fR\f(CB$key\fR\fB)\fR, \fBhmac_sha256($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha384($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha512($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha512224($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha512256($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha1_hex($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha224_hex($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha256_hex($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha384_hex($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha512_hex($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha512224_hex($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha512256_hex($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha1_base64($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha224_base64($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha256_base64($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha384_base64($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha512_base64($data, \fR\f(CB$key\fR\fB)\fR, \fBhmac_sha512224_base64($data, \fR\f(CB$key\fR\fB)\fR,
+\&\fBhmac_sha512256_base64($data, \fR\f(CB$key\fR\fB)\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP ACKNOWLEDGMENTS 4
+.IX Item "ACKNOWLEDGMENTS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Digest::base \- Digest base class"
+.IX Subsection "Digest::base - Digest base class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Digest::file \- Calculate digests of files"
+.IX Subsection "Digest::file - Calculate digests of files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+digest_file( \f(CW$file\fR, \f(CW$algorithm\fR, [$arg,...] ), digest_file_hex( \f(CW$file\fR,
+\&\f(CW$algorithm\fR, [$arg,...] ), digest_file_base64( \f(CW$file\fR, \f(CW$algorithm\fR, [$arg,...]
+)
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "DirHandle \- (obsolete) supply object methods for directory handles"
+.IX Subsection "DirHandle - (obsolete) supply object methods for directory handles"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Dumpvalue \- provides screen dump of Perl data."
+.IX Subsection "Dumpvalue - provides screen dump of Perl data."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Creation 4
+.IX Item "Creation"
+.PD
+\&\f(CW\*(C`arrayDepth\*(C'\fR, \f(CW\*(C`hashDepth\*(C'\fR, \f(CW\*(C`compactDump\*(C'\fR, \f(CW\*(C`veryCompact\*(C'\fR, \f(CW\*(C`globPrint\*(C'\fR,
+\&\f(CW\*(C`dumpDBFiles\*(C'\fR, \f(CW\*(C`dumpPackages\*(C'\fR, \f(CW\*(C`dumpReused\*(C'\fR, \f(CW\*(C`tick\*(C'\fR, \f(CW\*(C`quoteHighBit\*(C'\fR,
+\&\f(CW\*(C`printUndef\*(C'\fR, \f(CW\*(C`usageOnly\*(C'\fR, unctrl, subdump, bareStringify, quoteHighBit,
+stopDbSignal
+.IP Methods 4
+.IX Item "Methods"
+dumpValue, dumpValues, stringify, dumpvars, set_quote, set_unctrl,
+compactDump, veryCompact, set, get
+.RE
+.RS 4
+.RE
+.SS "DynaLoader \- Dynamically load C libraries into Perl code"
+.IX Subsection "DynaLoader - Dynamically load C libraries into Perl code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW@dl_library_path\fR, \f(CW@dl_resolve_using\fR, \f(CW@dl_require_symbols\fR, \f(CW@dl_librefs\fR,
+\&\f(CW@dl_modules\fR, \f(CW@dl_shared_objects\fR, \fBdl_error()\fR, \f(CW$dl_debug\fR, \f(CW$dl_dlext\fR,
+\&\fBdl_findfile()\fR, \fBdl_expandspec()\fR, \fBdl_load_file()\fR, \fBdl_unload_file()\fR,
+\&\fBdl_load_flags()\fR, \fBdl_find_symbol()\fR, \fBdl_find_symbol_anywhere()\fR,
+\&\fBdl_undef_symbols()\fR, \fBdl_install_xsub()\fR, \fBbootstrap()\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "Encode \- character encodings in Perl"
+.IX Subsection "Encode - character encodings in Perl"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP "Table of Contents" 4
+.IX Item "Table of Contents"
+.PD
+Encode::Alias \- Alias definitions to encodings, Encode::Encoding \-
+Encode Implementation Base Class, Encode::Supported \- List of Supported
+Encodings, Encode::CN \- Simplified Chinese Encodings, Encode::JP \-
+Japanese Encodings, Encode::KR \- Korean Encodings, Encode::TW \-
+Traditional Chinese Encodings
+.RE
+.RS 4
+.RE
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP TERMINOLOGY 4
+.IX Item "TERMINOLOGY"
+.RE
+.RS 4
+.RE
+.IP "THE PERL ENCODING API" 4
+.IX Item "THE PERL ENCODING API"
+.RS 4
+.IP "Basic methods" 4
+.IX Item "Basic methods"
+.IP "Listing available encodings" 4
+.IX Item "Listing available encodings"
+.IP "Defining Aliases" 4
+.IX Item "Defining Aliases"
+.IP "Finding IANA Character Set Registry names" 4
+.IX Item "Finding IANA Character Set Registry names"
+.RE
+.RS 4
+.RE
+.IP "Encoding via PerlIO" 4
+.IX Item "Encoding via PerlIO"
+.IP "Handling Malformed Data" 4
+.IX Item "Handling Malformed Data"
+.RS 4
+.IP "List of \fICHECK\fR values" 4
+.IX Item "List of CHECK values"
+.PD
+perlqq mode (\fICHECK\fR = Encode::FB_PERLQQ), HTML charref mode (\fICHECK\fR =
+Encode::FB_HTMLCREF), XML charref mode (\fICHECK\fR = Encode::FB_XMLCREF)
+.IP "coderef for CHECK" 4
+.IX Item "coderef for CHECK"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Defining Encodings" 4
+.IX Item "Defining Encodings"
+.IP "The UTF8 flag" 4
+.IX Item "The UTF8 flag"
+.PD
+Goal #1:, Goal #2:, Goal #3:, Goal #4:
+.RS 4
+.IP "Messing with Perl's Internals" 4
+.IX Item "Messing with Perl's Internals"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "UTF\-8 vs. utf8 vs. UTF8" 4
+.IX Item "UTF-8 vs. utf8 vs. UTF8"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Encode::Alias \- alias definitions to encodings"
+.IX Subsection "Encode::Alias - alias definitions to encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+As a simple string, As a qr// compiled regular expression, e.g.:, As a code
+reference, e.g.:
+.RS 4
+.IP "Alias overloading" 4
+.IX Item "Alias overloading"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Byte \- Single Byte Encodings"
+.IX Subsection "Encode::Byte - Single Byte Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::CJKConstants \-\- Internally used by Encode::??::ISO_2022_*"
+.IX Subsection "Encode::CJKConstants -- Internally used by Encode::??::ISO_2022_*"
+.SS "Encode::CN \- China-based Chinese Encodings"
+.IX Subsection "Encode::CN - China-based Chinese Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::CN::HZ \-\- internally used by Encode::CN"
+.IX Subsection "Encode::CN::HZ -- internally used by Encode::CN"
+.SS "Encode::Config \-\- internally used by Encode"
+.IX Subsection "Encode::Config -- internally used by Encode"
+.SS "Encode::EBCDIC \- EBCDIC Encodings"
+.IX Subsection "Encode::EBCDIC - EBCDIC Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Encoder \-\- Object Oriented Encoder"
+.IX Subsection "Encode::Encoder -- Object Oriented Encoder"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP Description 4
+.IX Item "Description"
+.RS 4
+.IP "Predefined Methods" 4
+.IX Item "Predefined Methods"
+.PD
+\&\f(CW$e\fR = Encode::Encoder\->new([$data, \f(CW$encoding\fR]);, \fBencoder()\fR,
+\&\f(CW$e\fR\->data([$data]), \f(CW$e\fR\->encoding([$encoding]),
+\&\f(CW$e\fR\->bytes([$encoding])
+.IP "Example: base64 transcoder" 4
+.IX Item "Example: base64 transcoder"
+.PD 0
+.IP "Operator Overloading" 4
+.IX Item "Operator Overloading"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Encoding \- Encode Implementation Base Class"
+.IX Subsection "Encode::Encoding - Encode Implementation Base Class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Methods you should implement" 4
+.IX Item "Methods you should implement"
+.PD
+\&\->encode($string [,$check]), \->decode($octets [,$check]),
+\&\->cat_decode($destination, \f(CW$octets\fR, \f(CW$offset\fR, \f(CW$terminator\fR [,$check])
+.IP "Other methods defined in Encode::Encodings" 4
+.IX Item "Other methods defined in Encode::Encodings"
+\&\->name, \->mime_name, \->renew, \->renewed, \->\fBperlio_ok()\fR,
+\&\->\fBneeds_lines()\fR
+.IP "Example: Encode::ROT13" 4
+.IX Item "Example: Encode::ROT13"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "Why the heck Encode API is different?" 4
+.IX Item "Why the heck Encode API is different?"
+.RS 4
+.IP "Compiled Encodings" 4
+.IX Item "Compiled Encodings"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+Scheme 1, Scheme 2, Other Schemes
+.SS "Encode::GSM0338 \-\- ETSI GSM 03.38 Encoding"
+.IX Subsection "Encode::GSM0338 -- ETSI GSM 03.38 Encoding"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Septets 4
+.IX Item "Septets"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Guess \-\- Guesses encoding from data"
+.IX Subsection "Encode::Guess -- Guesses encoding from data"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Encode::Guess\->set_suspects, Encode::Guess\->add_suspects,
+Encode::decode("Guess" ...), Encode::Guess\->guess($data),
+guess_encoding($data, [, \fIlist of suspects\fR])
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP "TO DO" 4
+.IX Item "TO DO"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::JP \- Japanese Encodings"
+.IX Subsection "Encode::JP - Japanese Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Note on ISO\-2022\-JP(\-1)?" 4
+.IX Item "Note on ISO-2022-JP(-1)?"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::JP::H2Z \-\- internally used by Encode::JP::2022_JP*"
+.IX Subsection "Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*"
+.SS "Encode::JP::JIS7 \-\- internally used by Encode::JP"
+.IX Subsection "Encode::JP::JIS7 -- internally used by Encode::JP"
+.SS "Encode::KR \- Korean Encodings"
+.IX Subsection "Encode::KR - Korean Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::KR::2022_KR \-\- internally used by Encode::KR"
+.IX Subsection "Encode::KR::2022_KR -- internally used by Encode::KR"
+.SS "Encode::MIME::Header \-\- MIME encoding for an unstructured email header"
+.IX Subsection "Encode::MIME::Header -- MIME encoding for an unstructured email header"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::MIME::Name, Encode::MIME::NAME \-\- internally used by Encode"
+.IX Subsection "Encode::MIME::Name, Encode::MIME::NAME -- internally used by Encode"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "Encode::PerlIO \-\- a detailed document on Encode and PerlIO"
+.IX Subsection "Encode::PerlIO -- a detailed document on Encode and PerlIO"
+.PD 0
+.IP Overview 4
+.IX Item "Overview"
+.IP "How does it work?" 4
+.IX Item "How does it work?"
+.IP "Line Buffering" 4
+.IX Item "Line Buffering"
+.RS 4
+.IP "How can I tell whether my encoding fully supports PerlIO ?" 4
+.IX Item "How can I tell whether my encoding fully supports PerlIO ?"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Supported \-\- Encodings supported by Encode"
+.IX Subsection "Encode::Supported -- Encodings supported by Encode"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Encoding Names" 4
+.IX Item "Encoding Names"
+.RE
+.RS 4
+.RE
+.IP "Supported Encodings" 4
+.IX Item "Supported Encodings"
+.RS 4
+.IP "Built-in Encodings" 4
+.IX Item "Built-in Encodings"
+.IP "Encode::Unicode \-\- other Unicode encodings" 4
+.IX Item "Encode::Unicode -- other Unicode encodings"
+.IP "Encode::Byte \-\- Extended ASCII" 4
+.IX Item "Encode::Byte -- Extended ASCII"
+.PD
+ISO\-8859 and corresponding vendor mappings, KOI8 \- De Facto Standard for
+the Cyrillic world
+.IP "gsm0338 \- Hentai Latin 1" 4
+.IX Item "gsm0338 - Hentai Latin 1"
+gsm0338 support before 2.19
+.IP "CJK: Chinese, Japanese, Korean (Multibyte)" 4
+.IX Item "CJK: Chinese, Japanese, Korean (Multibyte)"
+Encode::CN \-\- Continental China, Encode::JP \-\- Japan, Encode::KR \-\- Korea,
+Encode::TW \-\- Taiwan, Encode::HanExtra \-\- More Chinese via CPAN,
+Encode::JIS2K \-\- JIS X 0213 encodings via CPAN
+.IP "Miscellaneous encodings" 4
+.IX Item "Miscellaneous encodings"
+Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess
+.RE
+.RS 4
+.RE
+.IP "Unsupported encodings" 4
+.IX Item "Unsupported encodings"
+.Vb 4
+\&  ISO\-2022\-JP\-2 [RFC1554], ISO\-2022\-CN [RFC1922], Various HP\-UX encodings,
+\&Cyrillic encoding ISO\-IR\-111, ISO\-8859\-8\-1 [Hebrew], ISIRI 3342, Iran
+\&System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
+\&Various Mac encodings, (Mac) Indic encodings
+.Ve
+.IP "Encoding vs. Charset \-\- terminology" 4
+.IX Item "Encoding vs. Charset -- terminology"
+.PD 0
+.IP "Encoding Classification (by Anton Tagunov and Dan Kogai)" 4
+.IX Item "Encoding Classification (by Anton Tagunov and Dan Kogai)"
+.RS 4
+.IP "Microsoft-related naming mess" 4
+.IX Item "Microsoft-related naming mess"
+.PD
+KS_C_5601\-1987, GB2312, Big5, Shift_JIS
+.RE
+.RS 4
+.RE
+.IP Glossary 4
+.IX Item "Glossary"
+character repertoire, coded character set (CCS), character encoding scheme
+(CES), charset (in MIME context), EUC, ISO\-2022, UCS, UCS\-2, Unicode, UTF,
+UTF\-16
+.IP "See Also" 4
+.IX Item "See Also"
+.PD 0
+.IP References 4
+.IX Item "References"
+.PD
+ECMA, ECMA\-035 (eq \f(CW\*(C`ISO\-2022\*(C'\fR), IANA, Assigned Charset Names by IANA, ISO,
+RFC, UC, Unicode Glossary
+.RS 4
+.IP "Other Notable Sites" 4
+.IX Item "Other Notable Sites"
+czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org:
+"Introduction to i18n"
+.IP "Offline sources" 4
+.IX Item "Offline sources"
+\&\f(CW\*(C`CJKV Information Processing\*(C'\fR by Ken Lunde
+.RE
+.RS 4
+.RE
+.SS "Encode::Symbol \- Symbol Encodings"
+.IX Subsection "Encode::Symbol - Symbol Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::TW \- Taiwan-based Chinese Encodings"
+.IX Subsection "Encode::TW - Taiwan-based Chinese Encodings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Unicode \-\- Various Unicode Transformation Formats"
+.IX Subsection "Encode::Unicode -- Various Unicode Transformation Formats"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.PD
+<http://www.unicode.org/glossary/> says:, Quick Reference
+.IP "Size, Endianness, and BOM" 4
+.IX Item "Size, Endianness, and BOM"
+.RS 4
+.PD 0
+.IP "by size" 4
+.IX Item "by size"
+.IP "by endianness" 4
+.IX Item "by endianness"
+.PD
+BOM as integer when fetched in network byte order
+.RE
+.RS 4
+.RE
+.IP "Surrogate Pairs" 4
+.IX Item "Surrogate Pairs"
+.PD 0
+.IP "Error Checking" 4
+.IX Item "Error Checking"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Encode::Unicode::UTF7 \-\- UTF\-7 encoding"
+.IX Subsection "Encode::Unicode::UTF7 -- UTF-7 encoding"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ABSTRACT 4
+.IX Item "ABSTRACT"
+.IP "In Practice" 4
+.IX Item "In Practice"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "English \- use nice English (or awk) names for ugly punctuation variables"
+.IX Subsection "English - use nice English (or awk) names for ugly punctuation variables"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP PERFORMANCE 4
+.IX Item "PERFORMANCE"
+.PD
+.SS "Env \- perl module that imports environment variables as scalars or arrays"
+.IX Subsection "Env - perl module that imports environment variables as scalars or arrays"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Errno \- System errno constants"
+.IX Subsection "Errno - System errno constants"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Exporter \- Implements default import method for modules"
+.IX Subsection "Exporter - Implements default import method for modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How to Export" 4
+.IX Item "How to Export"
+.IP "Selecting What to Export" 4
+.IX Item "Selecting What to Export"
+.IP "How to Import" 4
+.IX Item "How to Import"
+.PD
+\&\f(CW\*(C`use YourModule;\*(C'\fR, \f(CW\*(C`use YourModule ();\*(C'\fR, \f(CW\*(C`use YourModule qw(...);\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Advanced Features" 4
+.IX Item "Advanced Features"
+.RS 4
+.PD 0
+.IP "Specialised Import Lists" 4
+.IX Item "Specialised Import Lists"
+.IP "Exporting Without Using Exporter's import Method" 4
+.IX Item "Exporting Without Using Exporter's import Method"
+.IP "Exporting Without Inheriting from Exporter" 4
+.IX Item "Exporting Without Inheriting from Exporter"
+.IP "Module Version Checking" 4
+.IX Item "Module Version Checking"
+.IP "Managing Unknown Symbols" 4
+.IX Item "Managing Unknown Symbols"
+.IP "Tag Handling Utility Functions" 4
+.IX Item "Tag Handling Utility Functions"
+.IP "Generating Combined Tags" 4
+.IX Item "Generating Combined Tags"
+.ie n .IP """AUTOLOAD""ed Constants" 4
+.el .IP "\f(CWAUTOLOAD\fRed Constants" 4
+.IX Item "AUTOLOADed Constants"
+.RE
+.RS 4
+.RE
+.IP "Good Practices" 4
+.IX Item "Good Practices"
+.RS 4
+.ie n .IP "Declaring @EXPORT_OK and Friends" 4
+.el .IP "Declaring \f(CW@EXPORT_OK\fR and Friends" 4
+.IX Item "Declaring @EXPORT_OK and Friends"
+.IP "Playing Safe" 4
+.IX Item "Playing Safe"
+.IP "What Not to Export" 4
+.IX Item "What Not to Export"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Exporter::Heavy \- Exporter guts"
+.IX Subsection "Exporter::Heavy - Exporter guts"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::CBuilder \- Compile and link C code for Perl modules"
+.IX Subsection "ExtUtils::CBuilder - Compile and link C code for Perl modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+new, have_compiler, have_cplusplus, compile, \f(CW\*(C`object_file\*(C'\fR,
+\&\f(CW\*(C`include_dirs\*(C'\fR, \f(CW\*(C`extra_compiler_flags\*(C'\fR, \f(CW\*(C`C++\*(C'\fR, link, lib_file,
+module_name, extra_linker_flags, link_executable, exe_file, object_file,
+lib_file, exe_file, prelink, need_prelink, extra_link_args_after_prelink
+.IP "TO DO" 4
+.IX Item "TO DO"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::CBuilder::Platform::Windows \- Builder class for Windows platforms"
+.IX Subsection "ExtUtils::CBuilder::Platform::Windows - Builder class for Windows platforms"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::Command \- utilities to replace common UNIX commands in Makefiles etc."
+.IX Subsection "ExtUtils::Command - utilities to replace common UNIX commands in Makefiles etc."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RE
+.RS 4
+.RE
+.PD
+.PP
+cat
+.PP
+eqtime
+.PP
+rm_rf
+.PP
+rm_f
+.PP
+touch
+.PP
+mv
+.PP
+cp
+.PP
+chmod
+.PP
+mkpath
+.PP
+test_f
+.PP
+test_d
+.PP
+dos2unix
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::Command::MM \- Commands for the MM's to use in Makefiles"
+.IX Subsection "ExtUtils::Command::MM - Commands for the MM's to use in Makefiles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBtest_harness\fR
+.PP
+\&\fBpod2man\fR
+.PP
+\&\fBwarn_if_old_packlist\fR
+.PP
+\&\fBperllocal_install\fR
+.PP
+\&\fBuninstall\fR
+.PP
+\&\fBtest_s\fR
+.PP
+\&\fBcp_nonempty\fR
+.SS "ExtUtils::Constant \- generate XS code to import C header constants"
+.IX Subsection "ExtUtils::Constant - generate XS code to import C header constants"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.PD
+IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PP
+constant_types
+.PP
+XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME
+.PP
+autoload PACKAGE, VERSION, AUTOLOADER
+.PP
+WriteMakefileSnippet
+.PP
+WriteConstants ATTRIBUTE => VALUE [, ...], NAME, DEFAULT_TYPE,
+BREAKOUT_AT, NAMES, PROXYSUBS, C_FH, C_FILE, XS_FH, XS_FILE, XS_SUBNAME,
+C_SUBNAME
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "ExtUtils::Constant::Base \- base class for ExtUtils::Constant objects"
+.IX Subsection "ExtUtils::Constant::Base - base class for ExtUtils::Constant objects"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.PD
+.PP
+header
+.PP
+memEQ_clause args_hashref
+.PP
+dump_names arg_hashref, ITEM..
+.PP
+assign arg_hashref, VALUE..
+.PP
+return_clause arg_hashref, ITEM
+.PP
+switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..
+.PP
+params WHAT
+.PP
+dogfood arg_hashref, ITEM..
+.PP
+normalise_items args, default_type, seen_types, seen_items, ITEM..
+.PP
+C_constant arg_hashref, ITEM.., name, type, value, macro, default, pre,
+post, def_pre, def_post, utf8, weight
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::Constant::Utils \- helper functions for ExtUtils::Constant"
+.IX Subsection "ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.PD
+C_stringify NAME
+.PP
+perl_stringify NAME
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "ExtUtils::Constant::XS \- generate C code for XS modules' constants."
+.IX Subsection "ExtUtils::Constant::XS - generate C code for XS modules' constants."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::Embed \- Utilities for embedding Perl in C/C++ applications"
+.IX Subsection "ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.ie n .IP @EXPORT 4
+.el .IP \f(CW@EXPORT\fR 4
+.IX Item "@EXPORT"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\fBxsinit()\fR, Examples, \fBldopts()\fR, Examples, \fBperl_inc()\fR, \fBccflags()\fR, \fBccdlflags()\fR,
+\&\fBccopts()\fR, \fBxsi_header()\fR, xsi_protos(@modules), xsi_body(@modules)
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::Install \- install files from here to there"
+.IX Subsection "ExtUtils::Install - install files from here to there"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP _chmod($$;$) 4
+.IX Item "_chmod($$;$)"
+.IP _warnonce(@) 4
+.IX Item "_warnonce(@)"
+.IP _choke(@) 4
+.IX Item "_choke(@)"
+.RE
+.RS 4
+.RE
+.ie n .IP "_move_file_at_boot( $file, $target, $moan  )" 4
+.el .IP "_move_file_at_boot( \f(CW$file\fR, \f(CW$target\fR, \f(CW$moan\fR  )" 4
+.IX Item "_move_file_at_boot( $file, $target, $moan )"
+.ie n .IP "_unlink_or_rename( $file, $tryhard, $installing )" 4
+.el .IP "_unlink_or_rename( \f(CW$file\fR, \f(CW$tryhard\fR, \f(CW$installing\fR )" 4
+.IX Item "_unlink_or_rename( $file, $tryhard, $installing )"
+.IP Functions 4
+.IX Item "Functions"
+.RS 4
+.IP _get_install_skip 4
+.IX Item "_get_install_skip"
+.RE
+.RS 4
+.RE
+.IP _have_write_access 4
+.IX Item "_have_write_access"
+.ie n .IP _can_write_dir($dir) 4
+.el .IP _can_write_dir(\f(CW$dir\fR) 4
+.IX Item "_can_write_dir($dir)"
+.IP _mkpath($dir,$show,$mode,$verbose,$dry_run) 4
+.IX Item "_mkpath($dir,$show,$mode,$verbose,$dry_run)"
+.IP _copy($from,$to,$verbose,$dry_run) 4
+.IX Item "_copy($from,$to,$verbose,$dry_run)"
+.IP _chdir($from) 4
+.IX Item "_chdir($from)"
+.IP install 4
+.IX Item "install"
+.IP _do_cleanup 4
+.IX Item "_do_cleanup"
+.ie n .IP "install_rooted_file( $file )" 4
+.el .IP "install_rooted_file( \f(CW$file\fR )" 4
+.IX Item "install_rooted_file( $file )"
+.ie n .IP "install_rooted_dir( $dir )" 4
+.el .IP "install_rooted_dir( \f(CW$dir\fR )" 4
+.IX Item "install_rooted_dir( $dir )"
+.ie n .IP "forceunlink( $file, $tryhard )" 4
+.el .IP "forceunlink( \f(CW$file\fR, \f(CW$tryhard\fR )" 4
+.IX Item "forceunlink( $file, $tryhard )"
+.ie n .IP "directory_not_empty( $dir )" 4
+.el .IP "directory_not_empty( \f(CW$dir\fR )" 4
+.IX Item "directory_not_empty( $dir )"
+.IP install_default 4
+.IX Item "install_default"
+.IP uninstall 4
+.IX Item "uninstall"
+.IP inc_uninstall($filepath,$libdir,$verbose,$dry_run,$ignore,$results) 4
+.IX Item "inc_uninstall($filepath,$libdir,$verbose,$dry_run,$ignore,$results)"
+.IP run_filter($cmd,$src,$dest) 4
+.IX Item "run_filter($cmd,$src,$dest)"
+.IP pm_to_blib 4
+.IX Item "pm_to_blib"
+.IP _autosplit 4
+.IX Item "_autosplit"
+.IP _invokant 4
+.IX Item "_invokant"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.PD
+\&\fBPERL_INSTALL_ROOT\fR, \fBEU_INSTALL_IGNORE_SKIP\fR,
+\&\fBEU_INSTALL_SITE_SKIPFILE\fR, \fBEU_INSTALL_ALWAYS_COPY\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "ExtUtils::Installed \- Inventory management of installed modules"
+.IX Subsection "ExtUtils::Installed - Inventory management of installed modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\fBnew()\fR, \fBmodules()\fR, \fBfiles()\fR, \fBdirectories()\fR, \fBdirectory_tree()\fR, \fBvalidate()\fR,
+\&\fBpacklist()\fR, \fBversion()\fR
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::Liblist \- determine libraries to use and how to use them"
+.IX Subsection "ExtUtils::Liblist - determine libraries to use and how to use them"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+For static extensions, For dynamic extensions at build/link time, For
+dynamic extensions at load time
+.RS 4
+.IP EXTRALIBS 4
+.IX Item "EXTRALIBS"
+.PD 0
+.IP "LDLOADLIBS and LD_RUN_PATH" 4
+.IX Item "LDLOADLIBS and LD_RUN_PATH"
+.IP BSLOADLIBS 4
+.IX Item "BSLOADLIBS"
+.RE
+.RS 4
+.RE
+.IP PORTABILITY 4
+.IX Item "PORTABILITY"
+.RS 4
+.IP "VMS implementation" 4
+.IX Item "VMS implementation"
+.IP "Win32 implementation" 4
+.IX Item "Win32 implementation"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM \- OS adjusted ExtUtils::MakeMaker subclass"
+.IX Subsection "ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::MM::Utils \- ExtUtils::MM methods without dependency on ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM::Utils - ExtUtils::MM methods without dependency on ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+maybe_command
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_AIX \- AIX specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_Any \- Platform-agnostic MM methods"
+.IX Subsection "ExtUtils::MM_Any - Platform-agnostic MM methods"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Cross-platform helper methods" 4
+.IX Item "Cross-platform helper methods"
+.RE
+.RS 4
+.RE
+.IP Targets 4
+.IX Item "Targets"
+.IP "Init methods" 4
+.IX Item "Init methods"
+.IP Tools 4
+.IX Item "Tools"
+.IP "File::Spec wrappers" 4
+.IX Item "File::Spec wrappers"
+.IP Misc 4
+.IX Item "Misc"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::MM_BeOS \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_BeOS - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+os_flavor
+.PP
+init_linker
+.SS "ExtUtils::MM_Cygwin \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_Cygwin - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+os_flavor
+.PP
+cflags
+.PP
+replace_manpage_separator
+.PP
+init_linker
+.PP
+maybe_command
+.PP
+dynamic_lib
+.PP
+install
+.SS "ExtUtils::MM_DOS \- DOS specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.PD
+os_flavor
+.RE
+.RS 4
+.RE
+.PP
+\&\fBreplace_manpage_separator\fR
+.PP
+xs_static_lib_is_xs
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_Darwin \- special behaviors for OS X"
+.IX Subsection "ExtUtils::MM_Darwin - special behaviors for OS X"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden Methods" 4
+.IX Item "Overridden Methods"
+.RE
+.RS 4
+.RE
+.PD
+.SS "ExtUtils::MM_MacOS \- once produced Makefiles for MacOS Classic"
+.IX Subsection "ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::MM_NW5 \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_NW5 - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+os_flavor
+.PP
+init_platform, platform_constants
+.PP
+static_lib_pure_cmd
+.PP
+xs_static_lib_is_xs
+.PP
+dynamic_lib
+.SS "ExtUtils::MM_OS2 \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_OS2 - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+init_dist
+.PP
+init_linker
+.PP
+os_flavor
+.PP
+xs_static_lib_is_xs
+.SS "ExtUtils::MM_OS390 \- OS390 specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_OS390 - OS390 specific subclass of ExtUtils::MM_Unix"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overriden methods" 4
+.IX Item "Overriden methods"
+.PD
+xs_make_dynamic_lib
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_QNX \- QNX specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_UWIN \- U/WIN specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.PD
+os_flavor
+.RE
+.RS 4
+.RE
+.PP
+\&\fBreplace_manpage_separator\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_Unix \- methods used by ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+os_flavor
+.PP
+c_o (o)
+.PP
+xs_obj_opt
+.PP
+dbgoutflag
+.PP
+cflags (o)
+.PP
+const_cccmd (o)
+.PP
+const_config (o)
+.PP
+const_loadlibs (o)
+.PP
+constants (o)
+.PP
+depend (o)
+.PP
+init_DEST
+.PP
+init_dist
+.PP
+dist (o)
+.PP
+dist_basics (o)
+.PP
+dist_ci (o)
+.PP
+dist_core (o)
+.PP
+\&\fBdist_target\fR
+.PP
+\&\fBtardist_target\fR
+.PP
+\&\fBzipdist_target\fR
+.PP
+\&\fBtarfile_target\fR
+.PP
+zipfile_target
+.PP
+uutardist_target
+.PP
+shdist_target
+.PP
+dlsyms (o)
+.PP
+dynamic_bs (o)
+.PP
+dynamic_lib (o)
+.PP
+xs_dynamic_lib_macros
+.PP
+xs_make_dynamic_lib
+.PP
+exescan
+.PP
+extliblist
+.PP
+find_perl
+.PP
+fixin
+.PP
+force (o)
+.PP
+guess_name
+.PP
+has_link_code
+.PP
+init_dirscan
+.PP
+init_MANPODS
+.PP
+init_MAN1PODS
+.PP
+init_MAN3PODS
+.PP
+init_PM
+.PP
+init_DIRFILESEP
+.PP
+init_main
+.PP
+init_tools
+.PP
+init_linker
+.PP
+init_lib2arch
+.PP
+init_PERL
+.PP
+init_platform, platform_constants
+.PP
+init_PERM
+.PP
+init_xs
+.PP
+install (o)
+.PP
+installbin (o)
+.PP
+linkext (o)
+.PP
+lsdir
+.PP
+macro (o)
+.PP
+makeaperl (o)
+.PP
+xs_static_lib_is_xs (o)
+.PP
+makefile (o)
+.PP
+maybe_command
+.PP
+needs_linking (o)
+.PP
+parse_abstract
+.PP
+parse_version
+.PP
+pasthru (o)
+.PP
+perl_script
+.PP
+perldepend (o)
+.PP
+pm_to_blib
+.PP
+ppd
+.PP
+prefixify
+.PP
+processPL (o)
+.PP
+specify_shell
+.PP
+quote_paren
+.PP
+replace_manpage_separator
+.PP
+cd
+.PP
+oneliner
+.PP
+quote_literal
+.PP
+escape_newlines
+.PP
+max_exec_len
+.PP
+static (o)
+.PP
+xs_make_static_lib
+.PP
+static_lib_closures
+.PP
+static_lib_fixtures
+.PP
+static_lib_pure_cmd
+.PP
+staticmake (o)
+.PP
+subdir_x (o)
+.PP
+subdirs (o)
+.PP
+test (o)
+.PP
+test_via_harness (override)
+.PP
+test_via_script (override)
+.PP
+tool_xsubpp (o)
+.PP
+all_target
+.PP
+top_targets (o)
+.PP
+writedoc
+.PP
+xs_c (o)
+.PP
+xs_cpp (o)
+.PP
+xs_o (o)
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "ExtUtils::MM_VMS \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_VMS - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Methods always loaded" 4
+.IX Item "Methods always loaded"
+.PD
+wraplist
+.RE
+.RS 4
+.RE
+.IP Methods 4
+.IX Item "Methods"
+guess_name (override)
+.PP
+find_perl (override)
+.PP
+_fixin_replace_shebang (override)
+.PP
+maybe_command (override)
+.PP
+pasthru (override)
+.PP
+pm_to_blib (override)
+.PP
+perl_script (override)
+.PP
+replace_manpage_separator
+.PP
+init_DEST
+.PP
+init_DIRFILESEP
+.PP
+init_main (override)
+.PP
+init_tools (override)
+.PP
+init_platform (override)
+.PP
+platform_constants
+.PP
+init_VERSION (override)
+.PP
+constants (override)
+.PP
+special_targets
+.PP
+cflags (override)
+.PP
+const_cccmd (override)
+.PP
+tools_other (override)
+.PP
+init_dist (override)
+.PP
+c_o (override)
+.PP
+xs_c (override)
+.PP
+xs_o (override)
+.PP
+_xsbuild_replace_macro (override)
+.PP
+_xsbuild_value (override)
+.PP
+dlsyms (override)
+.PP
+xs_obj_opt
+.PP
+dynamic_lib (override)
+.PP
+xs_make_static_lib (override)
+.PP
+static_lib_pure_cmd (override)
+.PP
+xs_static_lib_is_xs
+.PP
+extra_clean_files
+.PP
+zipfile_target, tarfile_target, shdist_target
+.PP
+install (override)
+.PP
+perldepend (override)
+.PP
+makeaperl (override)
+.PP
+maketext_filter (override)
+.PP
+prefixify (override)
+.PP
+cd
+.PP
+oneliner
+.PP
+\&\fBecho\fR
+.PP
+quote_literal
+.PP
+escape_dollarsigns
+.PP
+escape_all_dollarsigns
+.PP
+escape_newlines
+.PP
+max_exec_len
+.PP
+init_linker
+.PP
+catdir (override), catfile (override)
+.PP
+eliminate_macros
+.PP
+fixpath
+.PP
+os_flavor
+.PP
+is_make_type (override)
+.PP
+make_type (override)
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "ExtUtils::MM_VOS \- VOS specific subclass of ExtUtils::MM_Unix"
+.IX Subsection "ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MM_Win32 \- methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IX Subsection "ExtUtils::MM_Win32 - methods to override UN*X behaviour in ExtUtils::MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.PD
+\&\fBdlsyms\fR
+.PP
+xs_dlsyms_ext
+.PP
+replace_manpage_separator
+.PP
+\&\fBmaybe_command\fR
+.PP
+\&\fBinit_DIRFILESEP\fR
+.PP
+init_tools
+.PP
+init_others
+.PP
+init_platform, platform_constants
+.PP
+specify_shell
+.PP
+constants
+.PP
+special_targets
+.PP
+static_lib_pure_cmd
+.PP
+dynamic_lib
+.PP
+extra_clean_files
+.PP
+init_linker
+.PP
+perl_script
+.PP
+quote_dep
+.PP
+xs_obj_opt
+.PP
+pasthru
+.PP
+arch_check (override)
+.PP
+oneliner
+.PP
+cd
+.PP
+max_exec_len
+.PP
+os_flavor
+.PP
+dbgoutflag
+.PP
+cflags
+.PP
+make_type
+.SS "ExtUtils::MM_Win95 \- method to customize MakeMaker for Win9X"
+.IX Subsection "ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.PD
+max_exec_len
+.RE
+.RS 4
+.RE
+.PP
+os_flavor
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "ExtUtils::MY \- ExtUtils::MakeMaker subclass for customization"
+.IX Subsection "ExtUtils::MY - ExtUtils::MakeMaker subclass for customization"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::MakeMaker \- Create a module Makefile"
+.IX Subsection "ExtUtils::MakeMaker - Create a module Makefile"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "How To Write A Makefile.PL" 4
+.IX Item "How To Write A Makefile.PL"
+.IP "Default Makefile Behaviour" 4
+.IX Item "Default Makefile Behaviour"
+.IP "make test" 4
+.IX Item "make test"
+.IP "make testdb" 4
+.IX Item "make testdb"
+.IP "make install" 4
+.IX Item "make install"
+.IP INSTALL_BASE 4
+.IX Item "INSTALL_BASE"
+.IP "PREFIX and LIB attribute" 4
+.IX Item "PREFIX and LIB attribute"
+.IP "AFS users" 4
+.IX Item "AFS users"
+.IP "Static Linking of a new Perl Binary" 4
+.IX Item "Static Linking of a new Perl Binary"
+.IP "Determination of Perl Library and Installation Locations" 4
+.IX Item "Determination of Perl Library and Installation Locations"
+.IP "Which architecture dependent directory?" 4
+.IX Item "Which architecture dependent directory?"
+.IP "Using Attributes and Parameters" 4
+.IX Item "Using Attributes and Parameters"
+.PD
+ABSTRACT, ABSTRACT_FROM, AUTHOR, BINARY_LOCATION, BUILD_REQUIRES, C,
+CCFLAGS, CONFIG, CONFIGURE, CONFIGURE_REQUIRES, DEFINE, DESTDIR, DIR,
+DISTNAME, DISTVNAME, DLEXT, DL_FUNCS, DL_VARS, EXCLUDE_EXT, EXE_FILES,
+FIRST_MAKEFILE, FULLPERL, FULLPERLRUN, FULLPERLRUNINST, FUNCLIST, H,
+IMPORTS, INC, INCLUDE_EXT, INSTALLARCHLIB, INSTALLBIN, INSTALLDIRS,
+INSTALLMAN1DIR, INSTALLMAN3DIR, INSTALLPRIVLIB, INSTALLSCRIPT,
+INSTALLSITEARCH, INSTALLSITEBIN, INSTALLSITELIB, INSTALLSITEMAN1DIR,
+INSTALLSITEMAN3DIR, INSTALLSITESCRIPT, INSTALLVENDORARCH, INSTALLVENDORBIN,
+INSTALLVENDORLIB, INSTALLVENDORMAN1DIR, INSTALLVENDORMAN3DIR,
+INSTALLVENDORSCRIPT, INST_ARCHLIB, INST_BIN, INST_LIB, INST_MAN1DIR,
+INST_MAN3DIR, INST_SCRIPT, LD, LDDLFLAGS, LDFROM, LIB, LIBPERL_A, LIBS,
+LICENSE, LINKTYPE, MAGICXS, MAKE, MAKEAPERL, MAKEFILE_OLD, MAN1PODS,
+MAN3PODS, MAP_TARGET, META_ADD, META_MERGE, MIN_PERL_VERSION, MYEXTLIB,
+NAME, NEEDS_LINKING, NOECHO, NORECURS, NO_META, NO_MYMETA, NO_PACKLIST,
+NO_PERLLOCAL, NO_VC, OBJECT, OPTIMIZE, PERL, PERL_CORE, PERLMAINCC,
+PERL_ARCHLIB, PERL_LIB, PERL_MALLOC_OK, PERLPREFIX, PERLRUN, PERLRUNINST,
+PERL_SRC, PERM_DIR, PERM_RW, PERM_RWX, PL_FILES, PM, PMLIBDIRS, PM_FILTER,
+POLLUTE, PPM_INSTALL_EXEC, PPM_INSTALL_SCRIPT, PPM_UNINSTALL_EXEC,
+PPM_UNINSTALL_SCRIPT, PREFIX, PREREQ_FATAL, PREREQ_PM, PREREQ_PRINT,
+PRINT_PREREQ, SITEPREFIX, SIGN, SKIP, TEST_REQUIRES, TYPEMAPS,
+USE_MM_LD_RUN_PATH, VENDORPREFIX, VERBINST, VERSION, VERSION_FROM,
+VERSION_SYM, XS, XSBUILD, XSMULTI, XSOPT, XSPROTOARG, XS_VERSION
+.IP "Additional lowercase attributes" 4
+.IX Item "Additional lowercase attributes"
+clean, depend, dist, dynamic_lib, linkext, macro, postamble, realclean,
+test, tool_autosplit
+.IP "Overriding MakeMaker Methods" 4
+.IX Item "Overriding MakeMaker Methods"
+.PD 0
+.IP "The End Of Cargo Cult Programming" 4
+.IX Item "The End Of Cargo Cult Programming"
+.PD
+\&\f(CW\*(C`MAN3PODS => \*(Aq \*(Aq\*(C'\fR
+.IP "Hintsfile support" 4
+.IX Item "Hintsfile support"
+.PD 0
+.IP "Distribution Support" 4
+.IX Item "Distribution Support"
+.PD
+.Vb 3
+\&   make distcheck,    make skipcheck,    make distclean,    make veryclean,
+\&   make manifest,    make distdir,   make disttest,    make tardist,   
+\&make dist,    make uutardist,    make shdist,    make zipdist,    make ci
+.Ve
+.IP "Module Meta-Data (META and MYMETA)" 4
+.IX Item "Module Meta-Data (META and MYMETA)"
+.PD 0
+.IP "Disabling an extension" 4
+.IX Item "Disabling an extension"
+.IP "Other Handy Functions" 4
+.IX Item "Other Handy Functions"
+.PD
+prompt, os_unsupported
+.IP "Supported versions of Perl" 4
+.IX Item "Supported versions of Perl"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.PD
+PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "ExtUtils::MakeMaker::Config \- Wrapper around Config.pm"
+.IX Subsection "ExtUtils::MakeMaker::Config - Wrapper around Config.pm"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::MakeMaker::FAQ \- Frequently Asked Questions About MakeMaker"
+.IX Subsection "ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Module Installation" 4
+.IX Item "Module Installation"
+.PD
+How do I install a module into my home directory?, How do I get MakeMaker
+and Module::Build to install to the same place?, How do I keep from
+installing man pages?, How do I use a module without installing it?, How
+can I organize tests into subdirectories and have them run?, PREFIX vs
+INSTALL_BASE from Module::Build::Cookbook, Generating *.pm files with
+substitutions eg of \f(CW$VERSION\fR
+.IP "Common errors and problems" 4
+.IX Item "Common errors and problems"
+"No rule to make target `/usr/lib/perl5/CORE/config.h', needed by
+`Makefile'"
+.IP "Philosophy and History" 4
+.IX Item "Philosophy and History"
+Why not just use <insert other build config tool here>?, What is
+Module::Build and how does it relate to MakeMaker?, pure perl.	no make, no
+shell commands, easier to customize, cleaner internals, less cruft
+.IP "Module Writing" 4
+.IX Item "Module Writing"
+How do I keep my \f(CW$VERSION\fR up to date without resetting it manually?, What's
+this \fIMETA.yml\fR thing and how did it get in my \fIMANIFEST\fR?!, How do I
+delete everything not in my \fIMANIFEST\fR?, Which tar should I use on
+Windows?, Which zip should I use on Windows for '[ndg]make zipdist'?
+.IP XS 4
+.IX Item "XS"
+How do I prevent "object version X.XX does not match bootstrap parameter
+Y.YY" errors?, How do I make two or more XS files coexist in the same
+directory?, XSMULTI, Separate directories, Bootstrapping
+.RE
+.RS 4
+.RE
+.IP DESIGN 4
+.IX Item "DESIGN"
+.RS 4
+.PD 0
+.IP "MakeMaker object hierarchy (simplified)" 4
+.IX Item "MakeMaker object hierarchy (simplified)"
+.IP "MakeMaker object hierarchy (real)" 4
+.IX Item "MakeMaker object hierarchy (real)"
+.IP "The MM_* hierarchy" 4
+.IX Item "The MM_* hierarchy"
+.RE
+.RS 4
+.RE
+.IP PATCHING 4
+.IX Item "PATCHING"
+.PD
+make a pull request on the MakeMaker github repository, raise a issue on
+the MakeMaker github repository, file an RT ticket, email
+makemaker@perl.org
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::MakeMaker::Locale \- bundled Encode::Locale"
+.IX Subsection "ExtUtils::MakeMaker::Locale - bundled Encode::Locale"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+decode_argv( ), decode_argv( Encode::FB_CROAK ), env( \f(CW$uni_key\fR ), env(
+\&\f(CW$uni_key\fR => \f(CW$uni_value\fR ), reinit( ), reinit( \f(CW$encoding\fR ), \f(CW$ENCODING_LOCALE\fR,
+\&\f(CW$ENCODING_LOCALE_FS\fR, \f(CW$ENCODING_CONSOLE_IN\fR, \f(CW$ENCODING_CONSOLE_OUT\fR
+.IP NOTES 4
+.IX Item "NOTES"
+.RS 4
+.PD 0
+.IP Windows 4
+.IX Item "Windows"
+.IP "Mac OS X" 4
+.IX Item "Mac OS X"
+.IP "POSIX (Linux and other Unixes)" 4
+.IX Item "POSIX (Linux and other Unixes)"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::MakeMaker::Tutorial \- Writing a module with MakeMaker"
+.IX Subsection "ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "The Mantra" 4
+.IX Item "The Mantra"
+.IP "The Layout" 4
+.IX Item "The Layout"
+.PD
+Makefile.PL, MANIFEST, lib/, t/, Changes, README, INSTALL, MANIFEST.SKIP,
+bin/
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "ExtUtils::Manifest \- Utilities to write and check a MANIFEST file"
+.IX Subsection "ExtUtils::Manifest - Utilities to write and check a MANIFEST file"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP mkmanifest 4
+.IX Item "mkmanifest"
+.RE
+.RS 4
+.RE
+.IP manifind 4
+.IX Item "manifind"
+.IP manicheck 4
+.IX Item "manicheck"
+.IP filecheck 4
+.IX Item "filecheck"
+.IP fullcheck 4
+.IX Item "fullcheck"
+.IP skipcheck 4
+.IX Item "skipcheck"
+.IP maniread 4
+.IX Item "maniread"
+.IP maniskip 4
+.IX Item "maniskip"
+.IP manicopy 4
+.IX Item "manicopy"
+.IP maniadd 4
+.IX Item "maniadd"
+.IP MANIFEST 4
+.IX Item "MANIFEST"
+.IP MANIFEST.SKIP 4
+.IX Item "MANIFEST.SKIP"
+.PD
+#!include_default, #!include /Path/to/another/manifest.skip
+.IP EXPORT_OK 4
+.IX Item "EXPORT_OK"
+.PD 0
+.IP "GLOBAL VARIABLES" 4
+.IX Item "GLOBAL VARIABLES"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+\&\f(CW\*(C`Not in MANIFEST:\*(C'\fR \fIfile\fR, \f(CW\*(C`Skipping\*(C'\fR \fIfile\fR, \f(CW\*(C`No such file:\*(C'\fR \fIfile\fR,
+\&\f(CW\*(C`MANIFEST:\*(C'\fR \fI$!\fR, \f(CW\*(C`Added to MANIFEST:\*(C'\fR \fIfile\fR
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+\&\fBPERL_MM_MANIFEST_DEBUG\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "ExtUtils::Miniperl \- write the C code for miniperlmain.c and perlmain.c"
+.IX Subsection "ExtUtils::Miniperl - write the C code for miniperlmain.c and perlmain.c"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::Mkbootstrap \- make a bootstrap file for use by DynaLoader"
+.IX Subsection "ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::Mksymlists \- write linker options files for dynamic extension"
+.IX Subsection "ExtUtils::Mksymlists - write linker options files for dynamic extension"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+DLBASE, DL_FUNCS, DL_VARS, FILE, FUNCLIST, IMPORTS, NAME
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP REVISION 4
+.IX Item "REVISION"
+.PD
+.SS "ExtUtils::PL2Bat \- Batch file creation to run perl scripts on Windows"
+.IX Subsection "ExtUtils::PL2Bat - Batch file creation to run perl scripts on Windows"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP OVERVIEW 4
+.IX Item "OVERVIEW"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP pl2bat(%opts) 4
+.IX Item "pl2bat(%opts)"
+.PD
+\&\f(CW\*(C`in\*(C'\fR, \f(CW\*(C`out\*(C'\fR, \f(CW\*(C`ntargs\*(C'\fR, \f(CW\*(C`otherargs\*(C'\fR, \f(CW\*(C`stripsuffix\*(C'\fR, \f(CW\*(C`usewarnings\*(C'\fR,
+\&\f(CW\*(C`update\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.PP
+\&\fBmkfh()\fR
+.PP
+_\|_find_relocations
+.SS "ExtUtils::Packlist \- manage .packlist files"
+.IX Subsection "ExtUtils::Packlist - manage .packlist files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\fBnew()\fR, \fBread()\fR, \fBwrite()\fR, \fBvalidate()\fR, \fBpacklist_file()\fR
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ExtUtils::ParseXS \- converts Perl XS code into C code"
+.IX Subsection "ExtUtils::ParseXS - converts Perl XS code into C code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$pxs\fR\->\fBnew()\fR, \f(CW$pxs\fR\->\fBprocess_file()\fR, \fBC++\fR, \fBhiertype\fR, \fBexcept\fR,
+\&\fBtypemap\fR, \fBprototypes\fR, \fBversioncheck\fR, \fBlinenumbers\fR, \fBoptimize\fR,
+\&\fBinout\fR, \fBargtypes\fR, \fBs\fR, \fBdie_on_error\fR, \f(CW$pxs\fR\->\fBreport_error_count()\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "ExtUtils::ParseXS::Constants \- Initialization values for some globals"
+.IX Subsection "ExtUtils::ParseXS::Constants - Initialization values for some globals"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "ExtUtils::ParseXS::Eval \- Clean package to evaluate code in"
+.IX Subsection "ExtUtils::ParseXS::Eval - Clean package to evaluate code in"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP SUBROUTINES 4
+.IX Item "SUBROUTINES"
+.RS 4
+.ie n .IP "$pxs\->eval_output_typemap_code($typemapcode, $other_hashref)" 4
+.el .IP "\f(CW$pxs\fR\->eval_output_typemap_code($typemapcode, \f(CW$other_hashref\fR)" 4
+.IX Item "$pxs->eval_output_typemap_code($typemapcode, $other_hashref)"
+.RE
+.RS 4
+.RE
+.ie n .IP "$pxs\->eval_input_typemap_code($typemapcode, $other_hashref)" 4
+.el .IP "\f(CW$pxs\fR\->eval_input_typemap_code($typemapcode, \f(CW$other_hashref\fR)" 4
+.IX Item "$pxs->eval_input_typemap_code($typemapcode, $other_hashref)"
+.IP TODO 4
+.IX Item "TODO"
+.PD
+.SS "ExtUtils::ParseXS::Utilities \- Subroutines used with ExtUtils::ParseXS"
+.IX Subsection "ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP SUBROUTINES 4
+.IX Item "SUBROUTINES"
+.RS 4
+.ie n .IP standard_typemap_locations() 4
+.el .IP \f(CWstandard_typemap_locations()\fR 4
+.IX Item "standard_typemap_locations()"
+.PD
+Purpose, Arguments, Return Value
+.RE
+.RS 4
+.RE
+.ie n .IP trim_whitespace() 4
+.el .IP \f(CWtrim_whitespace()\fR 4
+.IX Item "trim_whitespace()"
+Purpose, Argument, Return Value
+.ie n .IP C_string() 4
+.el .IP \f(CWC_string()\fR 4
+.IX Item "C_string()"
+Purpose, Arguments, Return Value
+.ie n .IP valid_proto_string() 4
+.el .IP \f(CWvalid_proto_string()\fR 4
+.IX Item "valid_proto_string()"
+Purpose, Arguments, Return Value
+.ie n .IP process_typemaps() 4
+.el .IP \f(CWprocess_typemaps()\fR 4
+.IX Item "process_typemaps()"
+Purpose, Arguments, Return Value
+.ie n .IP map_type() 4
+.el .IP \f(CWmap_type()\fR 4
+.IX Item "map_type()"
+Purpose, Arguments, Return Value
+.ie n .IP standard_XS_defs() 4
+.el .IP \f(CWstandard_XS_defs()\fR 4
+.IX Item "standard_XS_defs()"
+Purpose, Arguments, Return Value
+.ie n .IP assign_func_args() 4
+.el .IP \f(CWassign_func_args()\fR 4
+.IX Item "assign_func_args()"
+Purpose, Arguments, Return Value
+.ie n .IP analyze_preprocessor_statements() 4
+.el .IP \f(CWanalyze_preprocessor_statements()\fR 4
+.IX Item "analyze_preprocessor_statements()"
+Purpose, Arguments, Return Value
+.ie n .IP set_cond() 4
+.el .IP \f(CWset_cond()\fR 4
+.IX Item "set_cond()"
+Purpose, Arguments, Return Value
+.ie n .IP current_line_number() 4
+.el .IP \f(CWcurrent_line_number()\fR 4
+.IX Item "current_line_number()"
+Purpose, Arguments, Return Value
+.ie n .IP Warn() 4
+.el .IP \f(CWWarn()\fR 4
+.IX Item "Warn()"
+Purpose, Arguments, Return Value
+.ie n .IP WarnHint() 4
+.el .IP \f(CWWarnHint()\fR 4
+.IX Item "WarnHint()"
+Purpose, Arguments, Return Value
+.ie n .IP _MsgHint() 4
+.el .IP \f(CW_MsgHint()\fR 4
+.IX Item "_MsgHint()"
+Purpose, Arguments, Return Value
+.ie n .IP blurt() 4
+.el .IP \f(CWblurt()\fR 4
+.IX Item "blurt()"
+Purpose, Arguments, Return Value
+.ie n .IP death() 4
+.el .IP \f(CWdeath()\fR 4
+.IX Item "death()"
+Purpose, Arguments, Return Value
+.ie n .IP check_conditional_preprocessor_statements() 4
+.el .IP \f(CWcheck_conditional_preprocessor_statements()\fR 4
+.IX Item "check_conditional_preprocessor_statements()"
+Purpose, Arguments, Return Value
+.ie n .IP escape_file_for_line_directive() 4
+.el .IP \f(CWescape_file_for_line_directive()\fR 4
+.IX Item "escape_file_for_line_directive()"
+Purpose, Arguments, Return Value
+.ie n .IP """report_typemap_failure""" 4
+.el .IP \f(CWreport_typemap_failure\fR 4
+.IX Item "report_typemap_failure"
+Purpose, Arguments, Return Value
+.SS "ExtUtils::Typemaps \- Read/Write/Modify Perl/XS typemap files"
+.IX Subsection "ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP new 4
+.IX Item "new"
+.IP file 4
+.IX Item "file"
+.IP add_typemap 4
+.IX Item "add_typemap"
+.IP add_inputmap 4
+.IX Item "add_inputmap"
+.IP add_outputmap 4
+.IX Item "add_outputmap"
+.IP add_string 4
+.IX Item "add_string"
+.IP remove_typemap 4
+.IX Item "remove_typemap"
+.IP remove_inputmap 4
+.IX Item "remove_inputmap"
+.IP remove_outputmap 4
+.IX Item "remove_outputmap"
+.IP get_typemap 4
+.IX Item "get_typemap"
+.IP get_inputmap 4
+.IX Item "get_inputmap"
+.IP get_outputmap 4
+.IX Item "get_outputmap"
+.IP write 4
+.IX Item "write"
+.IP as_string 4
+.IX Item "as_string"
+.IP as_embedded_typemap 4
+.IX Item "as_embedded_typemap"
+.IP merge 4
+.IX Item "merge"
+.IP is_empty 4
+.IX Item "is_empty"
+.IP list_mapped_ctypes 4
+.IX Item "list_mapped_ctypes"
+.IP _get_typemap_hash 4
+.IX Item "_get_typemap_hash"
+.IP _get_inputmap_hash 4
+.IX Item "_get_inputmap_hash"
+.IP _get_outputmap_hash 4
+.IX Item "_get_outputmap_hash"
+.IP _get_prototype_hash 4
+.IX Item "_get_prototype_hash"
+.IP clone 4
+.IX Item "clone"
+.IP tidy_type 4
+.IX Item "tidy_type"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "ExtUtils::Typemaps::Cmd \- Quick commands for handling typemaps"
+.IX Subsection "ExtUtils::Typemaps::Cmd - Quick commands for handling typemaps"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "EXPORTED FUNCTIONS" 4
+.IX Item "EXPORTED FUNCTIONS"
+.RS 4
+.IP embeddable_typemap 4
+.IX Item "embeddable_typemap"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "ExtUtils::Typemaps::InputMap \- Entry in the INPUT section of a typemap"
+.IX Subsection "ExtUtils::Typemaps::InputMap - Entry in the INPUT section of a typemap"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP new 4
+.IX Item "new"
+.IP code 4
+.IX Item "code"
+.IP xstype 4
+.IX Item "xstype"
+.IP cleaned_code 4
+.IX Item "cleaned_code"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "ExtUtils::Typemaps::OutputMap \- Entry in the OUTPUT section of a typemap"
+.IX Subsection "ExtUtils::Typemaps::OutputMap - Entry in the OUTPUT section of a typemap"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP new 4
+.IX Item "new"
+.IP code 4
+.IX Item "code"
+.IP xstype 4
+.IX Item "xstype"
+.IP cleaned_code 4
+.IX Item "cleaned_code"
+.IP targetable 4
+.IX Item "targetable"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "ExtUtils::Typemaps::Type \- Entry in the TYPEMAP section of a typemap"
+.IX Subsection "ExtUtils::Typemaps::Type - Entry in the TYPEMAP section of a typemap"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP new 4
+.IX Item "new"
+.IP proto 4
+.IX Item "proto"
+.IP xstype 4
+.IX Item "xstype"
+.IP ctype 4
+.IX Item "ctype"
+.IP tidy_ctype 4
+.IX Item "tidy_ctype"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.ie n .SS "ExtUtils::testlib \- add blib/* directories to @INC"
+.el .SS "ExtUtils::testlib \- add blib/* directories to \f(CW@INC\fP"
+.IX Subsection "ExtUtils::testlib - add blib/* directories to @INC"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Fatal \- Replace functions with equivalents which succeed or die"
+.IX Subsection "Fatal - Replace functions with equivalents which succeed or die"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP "BEST PRACTICE" 4
+.IX Item "BEST PRACTICE"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+Bad subroutine name for Fatal: \f(CW%s\fR, \f(CW%s\fR is not a Perl subroutine, \f(CW%s\fR is
+neither a builtin, nor a Perl subroutine, Cannot make the non-overridable
+\&\f(CW%s\fR fatal, Internal error: \f(CW%s\fR
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Fcntl \- load the C Fcntl.h defines"
+.IX Subsection "Fcntl - load the C Fcntl.h defines"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP "EXPORTED SYMBOLS" 4
+.IX Item "EXPORTED SYMBOLS"
+.PD
+.SS "File::Basename \- Parse file paths into directory, filename and suffix."
+.IX Subsection "File::Basename - Parse file paths into directory, filename and suffix."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+\&\f(CW\*(C`fileparse\*(C'\fR
+.IX Xref "fileparse"
+.PP
+\&\f(CW\*(C`basename\*(C'\fR
+.IX Xref "basename filename"
+.PP
+\&\f(CW\*(C`dirname\*(C'\fR
+.IX Xref "dirname"
+.PP
+\&\f(CW\*(C`fileparse_set_fstype\*(C'\fR
+.IX Xref "filesystem"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "File::Compare \- Compare files or filehandles"
+.IX Subsection "File::Compare - Compare files or filehandles"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP RETURN 4
+.IX Item "RETURN"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "File::Copy \- Copy files or filehandles"
+.IX Subsection "File::Copy - Copy files or filehandles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+copy  , move   , syscopy ,
+rmscopy($from,$to[,$date_flag])
+.IX Xref "copy cp move mv rename syscopy rmscopy"
+.IP RETURN 4
+.IX Item "RETURN"
+.PD 0
+.IP NOTES 4
+.IX Item "NOTES"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "File::DosGlob \- DOS like globbing and then some"
+.IX Subsection "File::DosGlob - DOS like globbing and then some"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "EXPORTS (by request only)" 4
+.IX Item "EXPORTS (by request only)"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Fetch \- A generic file fetching mechanism"
+.IX Subsection "File::Fetch - A generic file fetching mechanism"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$ff\fR\->uri, \f(CW$ff\fR\->scheme, \f(CW$ff\fR\->host, \f(CW$ff\fR\->vol, \f(CW$ff\fR\->share, \f(CW$ff\fR\->path,
+\&\f(CW$ff\fR\->file, \f(CW$ff\fR\->file_default
+.PP
+\&\f(CW$ff\fR\->output_file
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.PD 0
+.ie n .IP "$ff = File::Fetch\->new( uri => 'http://some.where.com/dir/file.txt' );" 4
+.el .IP "\f(CW$ff\fR = File::Fetch\->new( uri => 'http://some.where.com/dir/file.txt' );" 4
+.IX Item "$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );"
+.RE
+.RS 4
+.RE
+.ie n .IP "$where = $ff\->fetch( [to => /my/output/dir/ | \e$scalar] )" 4
+.el .IP "\f(CW$where\fR = \f(CW$ff\fR\->fetch( [to => /my/output/dir/ | \e$scalar] )" 4
+.IX Item "$where = $ff->fetch( [to => /my/output/dir/ | $scalar] )"
+.ie n .IP $ff\->error([BOOL]) 4
+.el .IP \f(CW$ff\fR\->error([BOOL]) 4
+.IX Item "$ff->error([BOOL])"
+.IP "HOW IT WORKS" 4
+.IX Item "HOW IT WORKS"
+.IP "GLOBAL VARIABLES" 4
+.IX Item "GLOBAL VARIABLES"
+.RS 4
+.ie n .IP $File::Fetch::FROM_EMAIL 4
+.el .IP \f(CW$File::Fetch::FROM_EMAIL\fR 4
+.IX Item "$File::Fetch::FROM_EMAIL"
+.ie n .IP $File::Fetch::USER_AGENT 4
+.el .IP \f(CW$File::Fetch::USER_AGENT\fR 4
+.IX Item "$File::Fetch::USER_AGENT"
+.ie n .IP $File::Fetch::FTP_PASSIVE 4
+.el .IP \f(CW$File::Fetch::FTP_PASSIVE\fR 4
+.IX Item "$File::Fetch::FTP_PASSIVE"
+.ie n .IP $File::Fetch::TIMEOUT 4
+.el .IP \f(CW$File::Fetch::TIMEOUT\fR 4
+.IX Item "$File::Fetch::TIMEOUT"
+.ie n .IP $File::Fetch::WARN 4
+.el .IP \f(CW$File::Fetch::WARN\fR 4
+.IX Item "$File::Fetch::WARN"
+.ie n .IP $File::Fetch::DEBUG 4
+.el .IP \f(CW$File::Fetch::DEBUG\fR 4
+.IX Item "$File::Fetch::DEBUG"
+.ie n .IP $File::Fetch::BLACKLIST 4
+.el .IP \f(CW$File::Fetch::BLACKLIST\fR 4
+.IX Item "$File::Fetch::BLACKLIST"
+.ie n .IP $File::Fetch::METHOD_FAIL 4
+.el .IP \f(CW$File::Fetch::METHOD_FAIL\fR 4
+.IX Item "$File::Fetch::METHOD_FAIL"
+.RE
+.RS 4
+.RE
+.IP MAPPING 4
+.IX Item "MAPPING"
+.IP "FREQUENTLY ASKED QUESTIONS" 4
+.IX Item "FREQUENTLY ASKED QUESTIONS"
+.RS 4
+.IP "So how do I use a proxy with File::Fetch?" 4
+.IX Item "So how do I use a proxy with File::Fetch?"
+.IP "I used 'lynx' to fetch a file, but its contents is all wrong!" 4
+.IX Item "I used 'lynx' to fetch a file, but its contents is all wrong!"
+.IP "Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?" 4
+.IX Item "Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?"
+.RE
+.RS 4
+.RE
+.IP TODO 4
+.IX Item "TODO"
+.PD
+Implement \f(CW$PREFER_BIN\fR
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "File::Find \- Traverse a directory tree."
+.IX Subsection "File::Find - Traverse a directory tree."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBfind\fR, \fBfinddepth\fR
+.RS 4
+.ie n .IP %options 4
+.el .IP \f(CW%options\fR 4
+.IX Item "%options"
+\&\f(CW\*(C`wanted\*(C'\fR, \f(CW\*(C`bydepth\*(C'\fR, \f(CW\*(C`preprocess\*(C'\fR, \f(CW\*(C`postprocess\*(C'\fR, \f(CW\*(C`follow\*(C'\fR,
+\&\f(CW\*(C`follow_fast\*(C'\fR, \f(CW\*(C`follow_skip\*(C'\fR, \f(CW\*(C`dangling_symlinks\*(C'\fR, \f(CW\*(C`no_chdir\*(C'\fR,
+\&\f(CW\*(C`untaint\*(C'\fR, \f(CW\*(C`untaint_pattern\*(C'\fR, \f(CW\*(C`untaint_skip\*(C'\fR
+.IP "The wanted function" 4
+.IX Item "The wanted function"
+\&\f(CW$File::Find::dir\fR is the current directory name,, \f(CW$_\fR is the current
+filename within that directory, \f(CW$File::Find::name\fR is the complete
+pathname to the file
+.RE
+.RS 4
+.RE
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+.PD 0
+.IP "BUGS AND CAVEATS" 4
+.IX Item "BUGS AND CAVEATS"
+.PD
+\&\f(CW$dont_use_nlink\fR, symlinks
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Glob \- Perl extension for BSD glob routine"
+.IX Subsection "File::Glob - Perl extension for BSD glob routine"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "META CHARACTERS" 4
+.IX Item "META CHARACTERS"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP "POSIX FLAGS" 4
+.IX Item "POSIX FLAGS"
+.PD
+\&\f(CW\*(C`GLOB_ERR\*(C'\fR, \f(CW\*(C`GLOB_LIMIT\*(C'\fR, \f(CW\*(C`GLOB_MARK\*(C'\fR, \f(CW\*(C`GLOB_NOCASE\*(C'\fR, \f(CW\*(C`GLOB_NOCHECK\*(C'\fR,
+\&\f(CW\*(C`GLOB_NOSORT\*(C'\fR, \f(CW\*(C`GLOB_BRACE\*(C'\fR, \f(CW\*(C`GLOB_NOMAGIC\*(C'\fR, \f(CW\*(C`GLOB_QUOTE\*(C'\fR,
+\&\f(CW\*(C`GLOB_TILDE\*(C'\fR, \f(CW\*(C`GLOB_CSH\*(C'\fR, \f(CW\*(C`GLOB_ALPHASORT\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+\&\f(CW\*(C`GLOB_NOSPACE\*(C'\fR, \f(CW\*(C`GLOB_ABEND\*(C'\fR
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "File::GlobMapper \- Extend File Glob to Allow Input and Output Files"
+.IX Subsection "File::GlobMapper - Extend File Glob to Allow Input and Output Files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Behind The Scenes" 4
+.IX Item "Behind The Scenes"
+.IP Limitations 4
+.IX Item "Limitations"
+.IP "Input File Glob" 4
+.IX Item "Input File Glob"
+.PD
+\&\fB~\fR, \fB~user\fR, \fB.\fR, \fB*\fR, \fB?\fR, \fB\e\fR,  \fB[]\fR,  \fB{,}\fR,  \fB()\fR
+.IP "Output File Glob" 4
+.IX Item "Output File Glob"
+"*", #1
+.IP "Returned Data" 4
+.IX Item "Returned Data"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "A Rename script" 4
+.IX Item "A Rename script"
+.IP "A few example globmaps" 4
+.IX Item "A few example globmaps"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "File::Path \- Create or remove directory trees"
+.IX Subsection "File::Path - Create or remove directory trees"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+make_path( \f(CW$dir1\fR, \f(CW$dir2\fR, .... ), make_path( \f(CW$dir1\fR, \f(CW$dir2\fR, ...., \e%opts ),
+mode => \f(CW$num\fR, chmod => \f(CW$num\fR, verbose => \f(CW$bool\fR, error => \e$err, owner =>
+\&\f(CW$owner\fR, user => \f(CW$owner\fR, uid => \f(CW$owner\fR, group => \f(CW$group\fR, mkpath( \f(CW$dir\fR ),
+mkpath( \f(CW$dir\fR, \f(CW$verbose\fR, \f(CW$mode\fR ), mkpath( [$dir1, \f(CW$dir2\fR,...], \f(CW$verbose\fR,
+\&\f(CW$mode\fR ), mkpath( \f(CW$dir1\fR, \f(CW$dir2\fR,..., \e%opt ), remove_tree( \f(CW$dir1\fR, \f(CW$dir2\fR, ....
+), remove_tree( \f(CW$dir1\fR, \f(CW$dir2\fR, ...., \e%opts ), verbose => \f(CW$bool\fR, safe =>
+\&\f(CW$bool\fR, keep_root => \f(CW$bool\fR, result => \e$res, error => \e$err, rmtree( \f(CW$dir\fR ),
+rmtree( \f(CW$dir\fR, \f(CW$verbose\fR, \f(CW$safe\fR ), rmtree( [$dir1, \f(CW$dir2\fR,...], \f(CW$verbose\fR,
+\&\f(CW$safe\fR ), rmtree( \f(CW$dir1\fR, \f(CW$dir2\fR,..., \e%opt )
+.RS 4
+.IP "ERROR HANDLING" 4
+.IX Item "ERROR HANDLING"
+\&\fBNOTE:\fR
+.IP NOTES 4
+.IX Item "NOTES"
+<http://cve.circl.lu/cve/CVE\-2004\-0452>,
+<http://cve.circl.lu/cve/CVE\-2005\-0448>
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+mkdir [path]: [errmsg] (SEVERE), No root path(s) specified, No such file or
+directory, cannot fetch initial working directory: [errmsg], cannot stat
+initial working directory: [errmsg], cannot chdir to [dir]: [errmsg],
+directory [dir] changed before chdir, expected dev=[n] ino=[n], actual
+dev=[n] ino=[n], aborting. (FATAL), cannot make directory [dir]
+read+writeable: [errmsg], cannot read [dir]: [errmsg], cannot reset chmod
+[dir]: [errmsg], cannot remove [dir] when cwd is [dir], cannot chdir to
+[parent\-dir] from [child\-dir]: [errmsg], aborting. (FATAL), cannot stat
+prior working directory [dir]: [errmsg], aborting. (FATAL), previous
+directory [parent\-dir] changed before entering [child\-dir], expected
+dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL), cannot make
+directory [dir] writeable: [errmsg], cannot remove directory [dir]:
+[errmsg], cannot restore permissions of [dir] to [0nnn]: [errmsg], cannot
+make file [file] writeable: [errmsg], cannot unlink file [file]: [errmsg],
+cannot restore permissions of [file] to [0nnn]: [errmsg], unable to map
+[owner] to a uid, ownership not changed");, unable to map [group] to a gid,
+group ownership not changed
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP "BUGS AND LIMITATIONS" 4
+.IX Item "BUGS AND LIMITATIONS"
+.RS 4
+.IP "MULTITHREADED APPLICATIONS" 4
+.IX Item "MULTITHREADED APPLICATIONS"
+.IP "NFS Mount Points" 4
+.IX Item "NFS Mount Points"
+.IP "REPORTING BUGS" 4
+.IX Item "REPORTING BUGS"
+.RE
+.RS 4
+.RE
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.PD
+<\fIbulkdd@cpan.org\fR>, Charlie Gonzalez <\fIitcharlie@cpan.org\fR>, Craig A.
+Berry <\fIcraigberry@mac.com\fR>, James E Keenan <\fIjkeenan@cpan.org\fR>, John
+Lightsey <\fIjohn@perlsec.org\fR>, Nigel Horne <\fInjh@bandsman.co.uk\fR>,
+Richard Elberger <\fIriche@cpan.org\fR>, Ryan Yee <\fIryee@cpan.org\fR>, Skye
+Shaw <\fIshaw@cpan.org\fR>, Tom Lutz <\fItommylutz@gmail.com\fR>, Will Sheppard
+<\fIwillsheppard@github\fR>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "File::Spec \- portably perform operations on file names"
+.IX Subsection "File::Spec - portably perform operations on file names"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+canonpath , catdir , catfile , curdir
+, devnull , rootdir , tmpdir , updir
+, no_upwards, case_tolerant, file_name_is_absolute, path ,
+join , splitpath  , splitdir
+ , \fBcatpath()\fR, abs2rel  
+, \fBrel2abs()\fR
+.IX Xref "canonpath catdir catfile curdir devnull rootdir tmpdir updir path join, path splitpath split, path splitdir split, dir abs2rel absolute, path relative, path rel2abs absolute, path relative, path"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "File::Spec::AmigaOS \- File::Spec for AmigaOS"
+.IX Subsection "File::Spec::AmigaOS - File::Spec for AmigaOS"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+tmpdir
+.PP
+file_name_is_absolute
+.SS "File::Spec::Cygwin \- methods for Cygwin file specs"
+.IX Subsection "File::Spec::Cygwin - methods for Cygwin file specs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+canonpath
+.PP
+file_name_is_absolute
+.PP
+tmpdir (override)
+.PP
+case_tolerant
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "File::Spec::Epoc \- methods for Epoc file specs"
+.IX Subsection "File::Spec::Epoc - methods for Epoc file specs"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+\&\fBcanonpath()\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Spec::Functions \- portably perform operations on file names"
+.IX Subsection "File::Spec::Functions - portably perform operations on file names"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Exports 4
+.IX Item "Exports"
+.RE
+.RS 4
+.RE
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Spec::Mac \- File::Spec for Mac OS (Classic)"
+.IX Subsection "File::Spec::Mac - File::Spec for Mac OS (Classic)"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+canonpath
+.PP
+\&\fBcatdir()\fR
+.PP
+catfile
+.PP
+curdir
+.PP
+devnull
+.PP
+rootdir
+.PP
+tmpdir
+.PP
+updir
+.PP
+file_name_is_absolute
+.PP
+path
+.PP
+splitpath
+.PP
+splitdir
+.PP
+catpath
+.PP
+abs2rel
+.PP
+rel2abs
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD 0
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Spec::OS2 \- methods for OS/2 file specs"
+.IX Subsection "File::Spec::OS2 - methods for OS/2 file specs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+tmpdir, splitpath
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "File::Spec::Unix \- File::Spec for Unix, base for other File::Spec modules"
+.IX Subsection "File::Spec::Unix - File::Spec for Unix, base for other File::Spec modules"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\fBcanonpath()\fR
+.PP
+\&\fBcatdir()\fR
+.PP
+catfile
+.PP
+curdir
+.PP
+devnull
+.PP
+rootdir
+.PP
+tmpdir
+.PP
+updir
+.PP
+no_upwards
+.PP
+case_tolerant
+.PP
+file_name_is_absolute
+.PP
+path
+.PP
+join
+.PP
+splitpath
+.PP
+splitdir
+.PP
+\&\fBcatpath()\fR
+.PP
+abs2rel
+.PP
+\&\fBrel2abs()\fR
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Spec::VMS \- methods for VMS file specs"
+.IX Subsection "File::Spec::VMS - methods for VMS file specs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+canonpath (override)
+.PP
+catdir (override)
+.PP
+catfile (override)
+.PP
+curdir (override)
+.PP
+devnull (override)
+.PP
+rootdir (override)
+.PP
+tmpdir (override)
+.PP
+updir (override)
+.PP
+case_tolerant (override)
+.PP
+path (override)
+.PP
+file_name_is_absolute (override)
+.PP
+splitpath (override)
+.PP
+splitdir (override)
+.PP
+catpath (override)
+.PP
+abs2rel (override)
+.PP
+rel2abs (override)
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Spec::Win32 \- methods for Win32 file specs"
+.IX Subsection "File::Spec::Win32 - methods for Win32 file specs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+devnull
+.PP
+tmpdir
+.PP
+case_tolerant
+.PP
+file_name_is_absolute
+.PP
+catfile
+.PP
+canonpath
+.PP
+splitpath
+.PP
+splitdir
+.PP
+catpath
+.IP "Note For File::Spec::Win32 Maintainers" 4
+.IX Item "Note For File::Spec::Win32 Maintainers"
+.PD 0
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "File::Temp \- return name and handle of a temporary file safely"
+.IX Subsection "File::Temp - return name and handle of a temporary file safely"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP PORTABILITY 4
+.IX Item "PORTABILITY"
+.IP "OBJECT-ORIENTED INTERFACE" 4
+.IX Item "OBJECT-ORIENTED INTERFACE"
+.PD
+\&\fBnew\fR, \fBnewdir\fR, \fBfilename\fR, \fBdirname\fR, \fBunlink_on_destroy\fR,
+\&\fBDESTROY\fR
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+\&\fBtempfile\fR, \fBtempdir\fR
+.IP "MKTEMP FUNCTIONS" 4
+.IX Item "MKTEMP FUNCTIONS"
+\&\fBmkstemp\fR, \fBmkstemps\fR, \fBmkdtemp\fR, \fBmktemp\fR
+.IP "POSIX FUNCTIONS" 4
+.IX Item "POSIX FUNCTIONS"
+\&\fBtmpnam\fR, \fBtmpfile\fR
+.IP "ADDITIONAL FUNCTIONS" 4
+.IX Item "ADDITIONAL FUNCTIONS"
+\&\fBtempnam\fR
+.IP "UTILITY FUNCTIONS" 4
+.IX Item "UTILITY FUNCTIONS"
+\&\fBunlink0\fR, \fBcmpstat\fR, \fBunlink1\fR, \fBcleanup\fR
+.IP "PACKAGE VARIABLES" 4
+.IX Item "PACKAGE VARIABLES"
+\&\fBsafe_level\fR, STANDARD, MEDIUM, HIGH, TopSystemUID, \fR\f(CB$KEEP_ALL\fR\fB\fR,
+\&\fB\fR\f(CB$DEBUG\fR\fB\fR
+.IP WARNING 4
+.IX Item "WARNING"
+.RS 4
+.PD 0
+.IP "Temporary files and NFS" 4
+.IX Item "Temporary files and NFS"
+.IP Forking 4
+.IX Item "Forking"
+.IP "Directory removal" 4
+.IX Item "Directory removal"
+.IP "Taint mode" 4
+.IX Item "Taint mode"
+.IP BINMODE 4
+.IX Item "BINMODE"
+.RE
+.RS 4
+.RE
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "File::stat \- by-name interface to Perl's built-in \fBstat()\fP functions"
+.IX Subsection "File::stat - by-name interface to Perl's built-in stat() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP ERRORS 4
+.IX Item "ERRORS"
+.PD
+\&\-%s is not implemented on a File::stat object
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+File::stat ignores use filetest 'access', File::stat ignores VMS ACLs
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "FileCache \- keep more files open than the system permits"
+.IX Subsection "FileCache - keep more files open than the system permits"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+cacheout EXPR, cacheout MODE, EXPR
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+.SS "FileHandle \- supply object methods for filehandles"
+.IX Subsection "FileHandle - supply object methods for filehandles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$fh\fR\->print, \f(CW$fh\fR\->printf, \f(CW$fh\fR\->getline, \f(CW$fh\fR\->getlines
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "Filter::Simple \- Simplified source filtering"
+.IX Subsection "Filter::Simple - Simplified source filtering"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "The Problem" 4
+.IX Item "The Problem"
+.IP "A Solution" 4
+.IX Item "A Solution"
+.IP "Disabling or changing <no> behaviour" 4
+.IX Item "Disabling or changing <no> behaviour"
+.IP "All-in-one interface" 4
+.IX Item "All-in-one interface"
+.IP "Filtering only specific components of source code" 4
+.IX Item "Filtering only specific components of source code"
+.PD
+\&\f(CW"code"\fR, \f(CW"code_no_comments"\fR, \f(CW"executable"\fR,
+\&\f(CW"executable_no_comments"\fR, \f(CW"quotelike"\fR, \f(CW"string"\fR, \f(CW"regex"\fR,
+\&\f(CW"all"\fR
+.IP "Filtering only the code parts of source code" 4
+.IX Item "Filtering only the code parts of source code"
+.PD 0
+.ie n .IP "Using Filter::Simple with an explicit ""import"" subroutine" 4
+.el .IP "Using Filter::Simple with an explicit \f(CWimport\fR subroutine" 4
+.IX Item "Using Filter::Simple with an explicit import subroutine"
+.IP "Using Filter::Simple and Exporter together" 4
+.IX Item "Using Filter::Simple and Exporter together"
+.IP "How it works" 4
+.IX Item "How it works"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTACT 4
+.IX Item "CONTACT"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Filter::Util::Call \- Perl Source Filter Utility Module"
+.IX Subsection "Filter::Util::Call - Perl Source Filter Utility Module"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "\fBuse Filter::Util::Call\fR" 4
+.IX Item "use Filter::Util::Call"
+.IP \fBimport()\fR 4
+.IX Item "import()"
+.IP \fBfilter_add()\fR 4
+.IX Item "filter_add()"
+.IP "\fBfilter() and anonymous sub\fR" 4
+.IX Item "filter() and anonymous sub"
+.PD
+\&\fR\f(CB$_\fR\fB\fR, \fB\fR\f(CB$status\fR\fB\fR, \fBfilter_read\fR and \fBfilter_read_exact\fR, \fBfilter_del\fR,
+\&\fIreal_import\fR, \fI\fR\f(BIunimport()\fR\fI\fR
+.RE
+.RS 4
+.RE
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+_\|_DATA_\|_ is ignored, Max. codesize limited to 32\-bit
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Example 1: A simple filter." 4
+.IX Item "Example 1: A simple filter."
+.IP "Example 2: Using the context" 4
+.IX Item "Example 2: Using the context"
+.IP "Example 3: Using the context within the filter" 4
+.IX Item "Example 3: Using the context within the filter"
+.IP "Example 4: Using filter_del" 4
+.IX Item "Example 4: Using filter_del"
+.RE
+.RS 4
+.RE
+.IP Filter::Simple 4
+.IX Item "Filter::Simple"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP DATE 4
+.IX Item "DATE"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "FindBin \- Locate directory of original perl script"
+.IX Subsection "FindBin - Locate directory of original perl script"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "EXPORTABLE VARIABLES" 4
+.IX Item "EXPORTABLE VARIABLES"
+.IP "KNOWN ISSUES" 4
+.IX Item "KNOWN ISSUES"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "GDBM_File \- Perl5 access to the gdbm library."
+.IX Subsection "GDBM_File - Perl5 access to the gdbm library."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Tie 4
+.IX Item "Tie"
+.PD
+\&\fBGDBM_READER\fR, \fBGDBM_WRITER\fR, \fBGDBM_WRCREAT\fR, \fBGDBM_NEWDB\fR
+.RE
+.RS 4
+.RE
+.IP "STATIC METHODS" 4
+.IX Item "STATIC METHODS"
+.RS 4
+.PD 0
+.IP GDBM_version 4
+.IX Item "GDBM_version"
+.PD
+1  \- exact guess, 2  \- approximate, 3  \- rough guess
+.RE
+.RS 4
+.RE
+.IP "ERROR HANDLING" 4
+.IX Item "ERROR HANDLING"
+.RS 4
+.PD 0
+.ie n .IP $GDBM_File::gdbm_errno 4
+.el .IP \f(CW$GDBM_File::gdbm_errno\fR 4
+.IX Item "$GDBM_File::gdbm_errno"
+.IP gdbm_check_syserr 4
+.IX Item "gdbm_check_syserr"
+.RE
+.RS 4
+.RE
+.IP "DATABASE METHODS" 4
+.IX Item "DATABASE METHODS"
+.RS 4
+.IP close 4
+.IX Item "close"
+.IP errno 4
+.IX Item "errno"
+.IP syserrno 4
+.IX Item "syserrno"
+.IP strerror 4
+.IX Item "strerror"
+.IP clear_error 4
+.IX Item "clear_error"
+.IP needs_recovery 4
+.IX Item "needs_recovery"
+.IP reorganize 4
+.IX Item "reorganize"
+.IP sync 4
+.IX Item "sync"
+.IP count 4
+.IX Item "count"
+.IP flags 4
+.IX Item "flags"
+.IP dbname 4
+.IX Item "dbname"
+.IP cache_size 4
+.IX Item "cache_size"
+.IP block_size 4
+.IX Item "block_size"
+.IP sync_mode 4
+.IX Item "sync_mode"
+.IP centfree 4
+.IX Item "centfree"
+.IP coalesce 4
+.IX Item "coalesce"
+.IP mmap 4
+.IX Item "mmap"
+.IP mmapsize 4
+.IX Item "mmapsize"
+.IP recover 4
+.IX Item "recover"
+.PD
+err => sub { ... }, backup => \e$str, max_failed_keys => \f(CW$n\fR,
+max_failed_buckets => \f(CW$n\fR, max_failures => \f(CW$n\fR, stat => \e%hash,
+recovered_keys, recovered_buckets, failed_keys, failed_buckets
+.IP convert 4
+.IX Item "convert"
+.PD 0
+.IP dump 4
+.IX Item "dump"
+.PD
+\&\fBbinary\fR => 1, \fBmode\fR => \fIMODE\fR, \fBoverwrite\fR => 1
+.IP load 4
+.IX Item "load"
+\&\fBreplace\fR => 1, \fBrestore_mode\fR => 0 | 1, \fBrestore_owner\fR => 0 | 1,
+\&\fBstrict_errors\fR => 1
+.RE
+.RS 4
+.RE
+.IP "CRASH TOLERANCE" 4
+.IX Item "CRASH TOLERANCE"
+.RS 4
+.PD 0
+.IP crash_tolerance_status 4
+.IX Item "crash_tolerance_status"
+.IP failure_atomic 4
+.IX Item "failure_atomic"
+.IP latest_snapshot 4
+.IX Item "latest_snapshot"
+.PD
+GDBM_SNAPSHOT_BAD, GDBM_SNAPSHOT_ERR, GDBM_SNAPSHOT_SAME,
+GDBM_SNAPSHOT_SUSPICIOUS
+.RE
+.RS 4
+.RE
+.IP AVAILABILITY 4
+.IX Item "AVAILABILITY"
+.PD 0
+.IP "SECURITY AND PORTABILITY" 4
+.IX Item "SECURITY AND PORTABILITY"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Getopt::Long \- Extended processing of command line options"
+.IX Subsection "Getopt::Long - Extended processing of command line options"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Command Line Options, an Introduction" 4
+.IX Item "Command Line Options, an Introduction"
+.IP "Getting Started with Getopt::Long" 4
+.IX Item "Getting Started with Getopt::Long"
+.RS 4
+.IP "Simple options" 4
+.IX Item "Simple options"
+.IP "A little bit less simple options" 4
+.IX Item "A little bit less simple options"
+.IP "Mixing command line option with other arguments" 4
+.IX Item "Mixing command line option with other arguments"
+.IP "Options with values" 4
+.IX Item "Options with values"
+.IP "Options with multiple values" 4
+.IX Item "Options with multiple values"
+.IP "Options with hash values" 4
+.IX Item "Options with hash values"
+.IP "User-defined subroutines to handle options" 4
+.IX Item "User-defined subroutines to handle options"
+.IP "Options with multiple names" 4
+.IX Item "Options with multiple names"
+.IP "Case and abbreviations" 4
+.IX Item "Case and abbreviations"
+.IP "Summary of Option Specifications" 4
+.IX Item "Summary of Option Specifications"
+.PD
+!, +, s, i, o, f, : \fItype\fR [ \fIdesttype\fR ], : \fInumber\fR [ \fIdesttype\fR ], :
++ [ \fIdesttype\fR ]
+.RE
+.RS 4
+.RE
+.IP "Advanced Possibilities" 4
+.IX Item "Advanced Possibilities"
+.RS 4
+.PD 0
+.IP "Object oriented interface" 4
+.IX Item "Object oriented interface"
+.IP "Callback object" 4
+.IX Item "Callback object"
+.PD
+name, given
+.IP "Thread Safety" 4
+.IX Item "Thread Safety"
+.PD 0
+.IP "Documentation and help texts" 4
+.IX Item "Documentation and help texts"
+.IP "Parsing options from an arbitrary array" 4
+.IX Item "Parsing options from an arbitrary array"
+.IP "Parsing options from an arbitrary string" 4
+.IX Item "Parsing options from an arbitrary string"
+.IP "Storing options values in a hash" 4
+.IX Item "Storing options values in a hash"
+.IP Bundling 4
+.IX Item "Bundling"
+.IP "The lonesome dash" 4
+.IX Item "The lonesome dash"
+.IP "Argument callback" 4
+.IX Item "Argument callback"
+.RE
+.RS 4
+.RE
+.IP "Configuring Getopt::Long" 4
+.IX Item "Configuring Getopt::Long"
+.PD
+default, posix_default, auto_abbrev, getopt_compat, gnu_compat, gnu_getopt,
+require_order, permute, bundling (default: disabled), bundling_override
+(default: disabled), ignore_case  (default: enabled), ignore_case_always
+(default: disabled), auto_version (default:disabled), auto_help
+(default:disabled), pass_through (default: disabled), prefix,
+prefix_pattern, long_prefix_pattern, debug (default: disabled)
+.IP "Exportable Methods" 4
+.IX Item "Exportable Methods"
+VersionMessage, \f(CW\*(C`\-message\*(C'\fR, \f(CW\*(C`\-msg\*(C'\fR, \f(CW\*(C`\-exitval\*(C'\fR, \f(CW\*(C`\-output\*(C'\fR, HelpMessage
+.IP "Return values and Errors" 4
+.IX Item "Return values and Errors"
+.PD 0
+.IP Legacy 4
+.IX Item "Legacy"
+.RS 4
+.IP "Default destinations" 4
+.IX Item "Default destinations"
+.IP "Alternative option starters" 4
+.IX Item "Alternative option starters"
+.IP "Configuration variables" 4
+.IX Item "Configuration variables"
+.RE
+.RS 4
+.RE
+.IP "Tips and Techniques" 4
+.IX Item "Tips and Techniques"
+.RS 4
+.IP "Pushing multiple values in a hash option" 4
+.IX Item "Pushing multiple values in a hash option"
+.RE
+.RS 4
+.RE
+.IP Troubleshooting 4
+.IX Item "Troubleshooting"
+.RS 4
+.IP "GetOptions does not return a false result when an option is not supplied" 4
+.IX Item "GetOptions does not return a false result when an option is not supplied"
+.IP "GetOptions does not split the command line correctly" 4
+.IX Item "GetOptions does not split the command line correctly"
+.IP "Undefined subroutine &main::GetOptions called" 4
+.IX Item "Undefined subroutine &main::GetOptions called"
+.IP "How do I put a ""\-?"" option into a Getopt::Long?" 4
+.IX Item "How do I put a ""-?"" option into a Getopt::Long?"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND DISCLAIMER" 4
+.IX Item "COPYRIGHT AND DISCLAIMER"
+.PD
+.SS "Getopt::Std \- Process single-character switches with switch clustering"
+.IX Subsection "Getopt::Std - Process single-character switches with switch clustering"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.ie n .IP """\-\-help"" and ""\-\-version""" 4
+.el .IP "\f(CW\-\-help\fR and \f(CW\-\-version\fR" 4
+.IX Item "--help and --version"
+.PD
+.SS "HTTP::Tiny \- A small, simple, correct HTTP/1.1 client"
+.IX Subsection "HTTP::Tiny - A small, simple, correct HTTP/1.1 client"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP get|head|put|post|patch|delete 4
+.IX Item "get|head|put|post|patch|delete"
+.IP post_form 4
+.IX Item "post_form"
+.IP mirror 4
+.IX Item "mirror"
+.IP request 4
+.IX Item "request"
+.IP www_form_urlencode 4
+.IX Item "www_form_urlencode"
+.IP can_ssl 4
+.IX Item "can_ssl"
+.IP connected 4
+.IX Item "connected"
+.RE
+.RS 4
+.RE
+.IP "TLS/SSL SUPPORT" 4
+.IX Item "TLS/SSL SUPPORT"
+.IP "PROXY SUPPORT" 4
+.IX Item "PROXY SUPPORT"
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.RS 4
+.IP "Bugs / Feature Requests" 4
+.IX Item "Bugs / Feature Requests"
+.IP "Source Code" 4
+.IX Item "Source Code"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Hash::Util \- A selection of general-utility hash subroutines"
+.IX Subsection "Hash::Util - A selection of general-utility hash subroutines"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Restricted hashes" 4
+.IX Item "Restricted hashes"
+.PD
+\&\fBlock_keys\fR, \fBunlock_keys\fR
+.RE
+.RS 4
+.RE
+.PP
+\&\fBlock_keys_plus\fR
+.PP
+\&\fBlock_value\fR, \fBunlock_value\fR
+.PP
+\&\fBlock_hash\fR, \fBunlock_hash\fR
+.PP
+\&\fBlock_hash_recurse\fR, \fBunlock_hash_recurse\fR
+.PP
+\&\fBhashref_locked\fR, \fBhash_locked\fR
+.PP
+\&\fBhashref_unlocked\fR, \fBhash_unlocked\fR
+.PP
+\&\fBlegal_keys\fR, \fBhidden_keys\fR, \fBall_keys\fR, \fBhash_seed\fR, \fBhash_value\fR,
+\&\fBbucket_info\fR, \fBbucket_stats\fR, \fBbucket_array\fR
+.PP
+\&\fBbucket_stats_formatted\fR
+.PP
+\&\fBhv_store\fR, \fBhash_traversal_mask\fR, \fBbucket_ratio\fR, \fBused_buckets\fR,
+\&\fBnum_buckets\fR
+.IP "Operating on references to hashes." 4
+.IX Item "Operating on references to hashes."
+lock_ref_keys, unlock_ref_keys, lock_ref_keys_plus, lock_ref_value,
+unlock_ref_value, lock_hashref, unlock_hashref, lock_hashref_recurse,
+unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Hash::Util::FieldHash \- Support for Inside-Out Classes"
+.IX Subsection "Hash::Util::FieldHash - Support for Inside-Out Classes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+id, id_2obj, register, idhash, idhashes, fieldhash, fieldhashes
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "The Inside-out Technique" 4
+.IX Item "The Inside-out Technique"
+.IP "Problems of Inside-out" 4
+.IX Item "Problems of Inside-out"
+.IP Solutions 4
+.IX Item "Solutions"
+.IP "More Problems" 4
+.IX Item "More Problems"
+.IP "The Generic Object" 4
+.IX Item "The Generic Object"
+.IP "How to use Field Hashes" 4
+.IX Item "How to use Field Hashes"
+.IP "Garbage-Collected Hashes" 4
+.IX Item "Garbage-Collected Hashes"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD
+\&\f(CWinit()\fR, \f(CWfirst()\fR, \f(CWlast()\fR, \f(CWname()\fR, \f(CW\*(C`Name_hash\*(C'\fR, \f(CW\*(C`Name_id\*(C'\fR,
+\&\f(CW\*(C`Name_idhash\*(C'\fR, \f(CW\*(C`Name_id_reg\*(C'\fR, \f(CW\*(C`Name_idhash_reg\*(C'\fR, \f(CW\*(C`Name_fieldhash\*(C'\fR
+.RS 4
+.IP "Example 1" 4
+.IX Item "Example 1"
+.PD 0
+.IP "Example 2" 4
+.IX Item "Example 2"
+.RE
+.RS 4
+.RE
+.IP GUTS 4
+.IX Item "GUTS"
+.RS 4
+.ie n .IP "The ""PERL_MAGIC_uvar"" interface for hashes" 4
+.el .IP "The \f(CWPERL_MAGIC_uvar\fR interface for hashes" 4
+.IX Item "The PERL_MAGIC_uvar interface for hashes"
+.IP "Weakrefs call uvar magic" 4
+.IX Item "Weakrefs call uvar magic"
+.IP "How field hashes work" 4
+.IX Item "How field hashes work"
+.IP "Internal function Hash::Util::FieldHash::_fieldhash" 4
+.IX Item "Internal function Hash::Util::FieldHash::_fieldhash"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "I18N::Collate \- compare 8\-bit scalar data according to the current locale"
+.IX Subsection "I18N::Collate - compare 8-bit scalar data according to the current locale"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "I18N::LangTags \- functions for dealing with RFC3066\-style language tags"
+.IX Subsection "I18N::LangTags - functions for dealing with RFC3066-style language tags"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.PP
+the function is_language_tag($lang1)
+.PP
+the function extract_language_tags($whatever)
+.PP
+the function same_language_tag($lang1, \f(CW$lang2\fR)
+.PP
+the function similarity_language_tag($lang1, \f(CW$lang2\fR)
+.PP
+the function is_dialect_of($lang1, \f(CW$lang2\fR)
+.PP
+the function super_languages($lang1)
+.PP
+the function locale2language_tag($locale_identifier)
+.PP
+the function encode_language_tag($lang1)
+.PP
+the function alternate_language_tags($lang1)
+.PP
+the function \f(CW@langs\fR = panic_languages(@accept_languages)
+.PP
+the function implicate_supers( ...languages... ), the function
+implicate_supers_strictly( ...languages... )
+.IP "ABOUT LOWERCASING" 4
+.IX Item "ABOUT LOWERCASING"
+.PD 0
+.IP "ABOUT UNICODE PLAINTEXT LANGUAGE TAGS" 4
+.IX Item "ABOUT UNICODE PLAINTEXT LANGUAGE TAGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "I18N::LangTags::Detect \- detect the user's language preferences"
+.IX Subsection "I18N::LangTags::Detect - detect the user's language preferences"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "I18N::LangTags::List \-\- tags and names for human languages"
+.IX Subsection "I18N::LangTags::List -- tags and names for human languages"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "ABOUT LANGUAGE TAGS" 4
+.IX Item "ABOUT LANGUAGE TAGS"
+.IP "LIST OF LANGUAGES" 4
+.IX Item "LIST OF LANGUAGES"
+.PD
+{ab} : Abkhazian, {ace} : Achinese, {ach} : Acoli, {ada} : Adangme, {ady} :
+Adyghe, {aa} : Afar, {afh} : Afrihili, {af} : Afrikaans, [{afa} :
+Afro-Asiatic (Other)], {ak} : Akan, {akk} : Akkadian, {sq} : Albanian,
+{ale} : Aleut, [{alg} : Algonquian languages], [{tut} : Altaic (Other)],
+{am} : Amharic, {i\-ami} : Ami, [{apa} : Apache languages], {ar} : Arabic,
+{arc} : Aramaic, {arp} : Arapaho, {arn} : Araucanian, {arw} : Arawak, {hy}
+: Armenian, {an} : Aragonese, [{art} : Artificial (Other)], {ast} :
+Asturian, {as} : Assamese, [{ath} : Athapascan languages], [{aus} :
+Australian languages], [{map} : Austronesian (Other)], {av} : Avaric, {ae}
+: Avestan, {awa} : Awadhi, {ay} : Aymara, {az} : Azerbaijani, {ban} :
+Balinese, [{bat} : Baltic (Other)], {bal} : Baluchi, {bm} : Bambara, [{bai}
+: Bamileke languages], {bad} : Banda, [{bnt} : Bantu (Other)], {bas} :
+Basa, {ba} : Bashkir, {eu} : Basque, {btk} : Batak (Indonesia), {bej} :
+Beja, {be} : Belarusian, {bem} : Bemba, {bn} : Bengali, [{ber} : Berber
+(Other)], {bho} : Bhojpuri, {bh} : Bihari, {bik} : Bikol, {bin} : Bini,
+{bi} : Bislama, {bs} : Bosnian, {bra} : Braj, {br} : Breton, {bug} :
+Buginese, {bg} : Bulgarian, {i\-bnn} : Bunun, {bua} : Buriat, {my} :
+Burmese, {cad} : Caddo, {car} : Carib, {ca} : Catalan, [{cau} : Caucasian
+(Other)], {ceb} : Cebuano, [{cel} : Celtic (Other)], [{cai} : Central
+American Indian (Other)], {chg} : Chagatai, [{cmc} : Chamic languages],
+{ch} : Chamorro, {ce} : Chechen, {chr} : Cherokee, {chy} : Cheyenne, {chb}
+: Chibcha, {ny} : Chichewa, {zh} : Chinese, {chn} : Chinook Jargon, {chp} :
+Chipewyan, {cho} : Choctaw, {cu} : Church Slavic, {chk} : Chuukese, {cv} :
+Chuvash, {cop} : Coptic, {kw} : Cornish, {co} : Corsican, {cr} : Cree,
+{mus} : Creek, [{cpe} : English-based Creoles and pidgins (Other)], [{cpf}
+: French-based Creoles and pidgins (Other)], [{cpp} : Portuguese-based
+Creoles and pidgins (Other)], [{crp} : Creoles and pidgins (Other)], {hr} :
+Croatian, [{cus} : Cushitic (Other)], {cs} : Czech, {dak} : Dakota, {da} :
+Danish, {dar} : Dargwa, {day} : Dayak, {i\-default} : Default (Fallthru)
+Language, {del} : Delaware, {din} : Dinka, {dv} : Divehi, {doi} : Dogri,
+{dgr} : Dogrib, [{dra} : Dravidian (Other)], {dua} : Duala, {nl} : Dutch,
+{dum} : Middle Dutch (ca.1050\-1350), {dyu} : Dyula, {dz} : Dzongkha, {efi}
+: Efik, {egy} : Ancient Egyptian, {eka} : Ekajuk, {elx} : Elamite, {en} :
+English, {enm} : Old English (1100\-1500), {ang} : Old English
+(ca.450\-1100), {i\-enochian} : Enochian (Artificial), {myv} : Erzya, {eo} :
+Esperanto, {et} : Estonian, {ee} : Ewe, {ewo} : Ewondo, {fan} : Fang, {fat}
+: Fanti, {fo} : Faroese, {fj} : Fijian, {fi} : Finnish, [{fiu} :
+Finno-Ugrian (Other)], {fon} : Fon, {fr} : French, {frm} : Middle French
+(ca.1400\-1600), {fro} : Old French (842\-ca.1400), {fy} : Frisian, {fur} :
+Friulian, {ff} : Fulah, {gaa} : Ga, {gd} : Scots Gaelic, {gl} : Gallegan,
+{lg} : Ganda, {gay} : Gayo, {gba} : Gbaya, {gez} : Geez, {ka} : Georgian,
+{de} : German, {gmh} : Middle High German (ca.1050\-1500), {goh} : Old High
+German (ca.750\-1050), [{gem} : Germanic (Other)], {gil} : Gilbertese, {gon}
+: Gondi, {gor} : Gorontalo, {got} : Gothic, {grb} : Grebo, {grc} : Ancient
+Greek, {el} : Modern Greek, {gn} : Guarani, {gu} : Gujarati, {gwi} :
+Gwich'in, {hai} : Haida, {ht} : Haitian, {ha} : Hausa, {haw} : Hawaiian,
+{he} : Hebrew, {hz} : Herero, {hil} : Hiligaynon, {him} : Himachali, {hi} :
+Hindi, {ho} : Hiri Motu, {hit} : Hittite, {hmn} : Hmong, {hu} : Hungarian,
+{hup} : Hupa, {iba} : Iban, {is} : Icelandic, {io} : Ido, {ig} : Igbo,
+{ijo} : Ijo, {ilo} : Iloko, [{inc} : Indic (Other)], [{ine} : Indo-European
+(Other)], {id} : Indonesian, {inh} : Ingush, {ia} : Interlingua
+(International Auxiliary Language Association), {ie} : Interlingue, {iu} :
+Inuktitut, {ik} : Inupiaq, [{ira} : Iranian (Other)], {ga} : Irish, {mga} :
+Middle Irish (900\-1200), {sga} : Old Irish (to 900), [{iro} : Iroquoian
+languages], {it} : Italian, {ja} : Japanese, {jv} : Javanese, {jrb} :
+Judeo-Arabic, {jpr} : Judeo-Persian, {kbd} : Kabardian, {kab} : Kabyle,
+{kac} : Kachin, {kl} : Kalaallisut, {xal} : Kalmyk, {kam} : Kamba, {kn} :
+Kannada, {kr} : Kanuri, {krc} : Karachay-Balkar, {kaa} : Kara-Kalpak, {kar}
+: Karen, {ks} : Kashmiri, {csb} : Kashubian, {kaw} : Kawi, {kk} : Kazakh,
+{kha} : Khasi, {km} : Khmer, [{khi} : Khoisan (Other)], {kho} : Khotanese,
+{ki} : Kikuyu, {kmb} : Kimbundu, {rw} : Kinyarwanda, {ky} : Kirghiz,
+{i\-klingon} : Klingon, {kv} : Komi, {kg} : Kongo, {kok} : Konkani, {ko} :
+Korean, {kos} : Kosraean, {kpe} : Kpelle, {kro} : Kru, {kj} : Kuanyama,
+{kum} : Kumyk, {ku} : Kurdish, {kru} : Kurukh, {kut} : Kutenai, {lad} :
+Ladino, {lah} : Lahnda, {lam} : Lamba, {lo} : Lao, {la} : Latin, {lv} :
+Latvian, {lb} : Letzeburgesch, {lez} : Lezghian, {li} : Limburgish, {ln} :
+Lingala, {lt} : Lithuanian, {nds} : Low German, {art\-lojban} : Lojban
+(Artificial), {loz} : Lozi, {lu} : Luba-Katanga, {lua} : Luba-Lulua, {lui}
+: Luiseno, {lun} : Lunda, {luo} : Luo (Kenya and Tanzania), {lus} : Lushai,
+{mk} : Macedonian, {mad} : Madurese, {mag} : Magahi, {mai} : Maithili,
+{mak} : Makasar, {mg} : Malagasy, {ms} : Malay, {ml} : Malayalam, {mt} :
+Maltese, {mnc} : Manchu, {mdr} : Mandar, {man} : Mandingo, {mni} :
+Manipuri, [{mno} : Manobo languages], {gv} : Manx, {mi} : Maori, {mr} :
+Marathi, {chm} : Mari, {mh} : Marshall, {mwr} : Marwari, {mas} : Masai,
+[{myn} : Mayan languages], {men} : Mende, {mic} : Micmac, {min} :
+Minangkabau, {i\-mingo} : Mingo, [{mis} : Miscellaneous languages], {moh} :
+Mohawk, {mdf} : Moksha, {mo} : Moldavian, [{mkh} : Mon-Khmer (Other)],
+{lol} : Mongo, {mn} : Mongolian, {mos} : Mossi, [{mul} : Multiple
+languages], [{mun} : Munda languages], {nah} : Nahuatl, {nap} : Neapolitan,
+{na} : Nauru, {nv} : Navajo, {nd} : North Ndebele, {nr} : South Ndebele,
+{ng} : Ndonga, {ne} : Nepali, {new} : Newari, {nia} : Nias, [{nic} :
+Niger-Kordofanian (Other)], [{ssa} : Nilo-Saharan (Other)], {niu} : Niuean,
+{nog} : Nogai, {non} : Old Norse, [{nai} : North American Indian], {no} :
+Norwegian, {nb} : Norwegian Bokmal, {nn} : Norwegian Nynorsk, [{nub} :
+Nubian languages], {nym} : Nyamwezi, {nyn} : Nyankole, {nyo} : Nyoro, {nzi}
+: Nzima, {oc} : Occitan (post 1500), {oj} : Ojibwa, {or} : Oriya, {om} :
+Oromo, {osa} : Osage, {os} : Ossetian; Ossetic, [{oto} : Otomian
+languages], {pal} : Pahlavi, {i\-pwn} : Paiwan, {pau} : Palauan, {pi} :
+Pali, {pam} : Pampanga, {pag} : Pangasinan, {pa} : Panjabi, {pap} :
+Papiamento, [{paa} : Papuan (Other)], {fa} : Persian, {peo} : Old Persian
+(ca.600\-400 B.C.), [{phi} : Philippine (Other)], {phn} : Phoenician, {pon}
+: Pohnpeian, {pl} : Polish, {pt} : Portuguese, [{pra} : Prakrit languages],
+{pro} : Old Provencal (to 1500), {ps} : Pushto, {qu} : Quechua, {rm} :
+Raeto-Romance, {raj} : Rajasthani, {rap} : Rapanui, {rar} : Rarotongan,
+[{qaa \- qtz} : Reserved for local use.], [{roa} : Romance (Other)], {ro} :
+Romanian, {rom} : Romany, {rn} : Rundi, {ru} : Russian, [{sal} : Salishan
+languages], {sam} : Samaritan Aramaic, {se} : Northern Sami, {sma} :
+Southern Sami, {smn} : Inari Sami, {smj} : Lule Sami, {sms} : Skolt Sami,
+[{smi} : Sami languages (Other)], {sm} : Samoan, {sad} : Sandawe, {sg} :
+Sango, {sa} : Sanskrit, {sat} : Santali, {sc} : Sardinian, {sas} : Sasak,
+{sco} : Scots, {sel} : Selkup, [{sem} : Semitic (Other)], {sr} : Serbian,
+{srr} : Serer, {shn} : Shan, {sn} : Shona, {sid} : Sidamo, {sgn\-...} : Sign
+Languages, {bla} : Siksika, {sd} : Sindhi, {si} : Sinhalese, [{sit} :
+Sino-Tibetan (Other)], [{sio} : Siouan languages], {den} : Slave
+(Athapascan), [{sla} : Slavic (Other)], {sk} : Slovak, {sl} : Slovenian,
+{sog} : Sogdian, {so} : Somali, {son} : Songhai, {snk} : Soninke, {wen} :
+Sorbian languages, {nso} : Northern Sotho, {st} : Southern Sotho, [{sai} :
+South American Indian (Other)], {es} : Spanish, {suk} : Sukuma, {sux} :
+Sumerian, {su} : Sundanese, {sus} : Susu, {sw} : Swahili, {ss} : Swati,
+{sv} : Swedish, {syr} : Syriac, {tl} : Tagalog, {ty} : Tahitian, [{tai} :
+Tai (Other)], {tg} : Tajik, {tmh} : Tamashek, {ta} : Tamil, {i\-tao} : Tao,
+{tt} : Tatar, {i\-tay} : Tayal, {te} : Telugu, {ter} : Tereno, {tet} :
+Tetum, {th} : Thai, {bo} : Tibetan, {tig} : Tigre, {ti} : Tigrinya, {tem} :
+Timne, {tiv} : Tiv, {tli} : Tlingit, {tpi} : Tok Pisin, {tkl} : Tokelau,
+{tog} : Tonga (Nyasa), {to} : Tonga (Tonga Islands), {tsi} : Tsimshian,
+{ts} : Tsonga, {i\-tsu} : Tsou, {tn} : Tswana, {tum} : Tumbuka, [{tup} :
+Tupi languages], {tr} : Turkish, {ota} : Ottoman Turkish (1500\-1928), {crh}
+: Crimean Turkish, {tk} : Turkmen, {tvl} : Tuvalu, {tyv} : Tuvinian, {tw} :
+Twi, {udm} : Udmurt, {uga} : Ugaritic, {ug} : Uighur, {uk} : Ukrainian,
+{umb} : Umbundu, {und} : Undetermined, {ur} : Urdu, {uz} : Uzbek, {vai} :
+Vai, {ve} : Venda, {vi} : Vietnamese, {vo} : Volapuk, {vot} : Votic, [{wak}
+: Wakashan languages], {wa} : Walloon, {wal} : Walamo, {war} : Waray, {was}
+: Washo, {cy} : Welsh, {wo} : Wolof, {x\-...} : Unregistered (Semi-Private
+Use), {xh} : Xhosa, {sah} : Yakut, {yao} : Yao, {yap} : Yapese, {ii} :
+Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd}
+: Zande, [{zap} : Zapotec], {zen} : Zenaga, {za} : Zhuang, {zu} : Zulu,
+{zun} : Zuni
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP "COPYRIGHT AND DISCLAIMER" 4
+.IX Item "COPYRIGHT AND DISCLAIMER"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "I18N::Langinfo \- query locale information"
+.IX Subsection "I18N::Langinfo - query locale information"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "For systems without ""nl_langinfo""" 4
+.el .IP "For systems without \f(CWnl_langinfo\fR" 4
+.IX Item "For systems without nl_langinfo"
+.PD
+\&\f(CW\*(C`ERA\*(C'\fR, \f(CW\*(C`CODESET\*(C'\fR, \f(CW\*(C`YESEXPR\*(C'\fR, \f(CW\*(C`YESSTR\*(C'\fR, \f(CW\*(C`NOEXPR\*(C'\fR, \f(CW\*(C`NOSTR\*(C'\fR, \f(CW\*(C`D_FMT\*(C'\fR,
+\&\f(CW\*(C`T_FMT\*(C'\fR, \f(CW\*(C`D_T_FMT\*(C'\fR, \f(CW\*(C`CRNCYSTR\*(C'\fR, \f(CW\*(C`ALT_DIGITS\*(C'\fR, \f(CW\*(C`ERA_D_FMT\*(C'\fR,
+\&\f(CW\*(C`ERA_T_FMT\*(C'\fR, \f(CW\*(C`ERA_D_T_FMT\*(C'\fR, \f(CW\*(C`T_FMT_AMPM\*(C'\fR
+.IP EXPORT 4
+.IX Item "EXPORT"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO \- load various IO modules"
+.IX Subsection "IO - load various IO modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP DEPRECATED 4
+.IX Item "DEPRECATED"
+.PD
+.SS "IO::Compress::Base \- Base Class for IO::Compress modules"
+.IX Subsection "IO::Compress::Base - Base Class for IO::Compress modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::Bzip2 \- Write bzip2 files/buffers"
+.IX Subsection "IO::Compress::Bzip2 - Write bzip2 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "bzip2 \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeIn => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A Buffer, A Filename, A
+Filehandle, \f(CW\*(C`BlockSize100K => number\*(C'\fR, \f(CW\*(C`WorkFactor => number\*(C'\fR,
+\&\f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP printf 4
+.IX Item "printf"
+.IP syswrite 4
+.IX Item "syswrite"
+.IP write 4
+.IX Item "write"
+.IP flush 4
+.IX Item "flush"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP newStream([OPTS]) 4
+.IX Item "newStream([OPTS])"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::Deflate \- Write RFC 1950 files/buffers"
+.IX Subsection "IO::Compress::Deflate - Write RFC 1950 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "deflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "deflate \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "deflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeIn => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A Buffer, A Filename, A
+Filehandle, \f(CW\*(C`Merge => 0|1\*(C'\fR, \-Level, \-Strategy, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP printf 4
+.IX Item "printf"
+.IP syswrite 4
+.IX Item "syswrite"
+.IP write 4
+.IX Item "write"
+.IP flush 4
+.IX Item "flush"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP newStream([OPTS]) 4
+.IX Item "newStream([OPTS])"
+.IP deflateParams 4
+.IX Item "deflateParams"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all, :constants, :flush, :level, :strategy
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::FAQ \-\- Frequently Asked Questions about IO::Compress"
+.IX Subsection "IO::Compress::FAQ -- Frequently Asked Questions about IO::Compress"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP GENERAL 4
+.IX Item "GENERAL"
+.RS 4
+.IP "Compatibility with Unix compress/uncompress." 4
+.IX Item "Compatibility with Unix compress/uncompress."
+.IP "Accessing .tar.Z files" 4
+.IX Item "Accessing .tar.Z files"
+.IP "How do I recompress using a different compression?" 4
+.IX Item "How do I recompress using a different compression?"
+.RE
+.RS 4
+.RE
+.IP ZIP 4
+.IX Item "ZIP"
+.RS 4
+.IP "What Compression Types do IO::Compress::Zip & IO::Uncompress::Unzip support?" 4
+.IX Item "What Compression Types do IO::Compress::Zip & IO::Uncompress::Unzip support?"
+.PD
+Store (method 0), Deflate (method 8), Bzip2 (method 12), Lzma (method 14)
+.IP "Can I Read/Write Zip files larger the 4 Gig?" 4
+.IX Item "Can I Read/Write Zip files larger the 4 Gig?"
+.PD 0
+.IP "Can I write more that 64K entries is a Zip files?" 4
+.IX Item "Can I write more that 64K entries is a Zip files?"
+.IP "Zip Resources" 4
+.IX Item "Zip Resources"
+.RE
+.RS 4
+.RE
+.IP GZIP 4
+.IX Item "GZIP"
+.RS 4
+.IP "Gzip Resources" 4
+.IX Item "Gzip Resources"
+.IP "Dealing with concatenated gzip files" 4
+.IX Item "Dealing with concatenated gzip files"
+.IP "Reading bgzip files with IO::Uncompress::Gunzip" 4
+.IX Item "Reading bgzip files with IO::Uncompress::Gunzip"
+.RE
+.RS 4
+.RE
+.IP ZLIB 4
+.IX Item "ZLIB"
+.RS 4
+.IP "Zlib Resources" 4
+.IX Item "Zlib Resources"
+.RE
+.RS 4
+.RE
+.IP Bzip2 4
+.IX Item "Bzip2"
+.RS 4
+.IP "Bzip2 Resources" 4
+.IX Item "Bzip2 Resources"
+.IP "Dealing with Concatenated bzip2 files" 4
+.IX Item "Dealing with Concatenated bzip2 files"
+.IP "Interoperating with Pbzip2" 4
+.IX Item "Interoperating with Pbzip2"
+.RE
+.RS 4
+.RE
+.IP "HTTP & NETWORK" 4
+.IX Item "HTTP & NETWORK"
+.RS 4
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Compressed files and Net::FTP" 4
+.IX Item "Compressed files and Net::FTP"
+.RE
+.RS 4
+.RE
+.IP MISC 4
+.IX Item "MISC"
+.RS 4
+.ie n .IP "Using ""InputLength"" to uncompress data embedded in a larger file/buffer." 4
+.el .IP "Using \f(CWInputLength\fR to uncompress data embedded in a larger file/buffer." 4
+.IX Item "Using InputLength to uncompress data embedded in a larger file/buffer."
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::Gzip \- Write RFC 1952 files/buffers"
+.IX Subsection "IO::Compress::Gzip - Write RFC 1952 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "gzip \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeIn => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A Buffer, A Filename, A
+Filehandle, \f(CW\*(C`Merge => 0|1\*(C'\fR, \-Level, \-Strategy, \f(CW\*(C`Minimal => 0|1\*(C'\fR,
+\&\f(CW\*(C`Comment => $comment\*(C'\fR, \f(CW\*(C`Name => $string\*(C'\fR, \f(CW\*(C`Time => $number\*(C'\fR,
+\&\f(CW\*(C`TextFlag => 0|1\*(C'\fR, \f(CW\*(C`HeaderCRC => 0|1\*(C'\fR, \f(CW\*(C`OS_Code => $value\*(C'\fR,
+\&\f(CW\*(C`ExtraField => $data\*(C'\fR, \f(CW\*(C`ExtraFlags => $value\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP printf 4
+.IX Item "printf"
+.IP syswrite 4
+.IX Item "syswrite"
+.IP write 4
+.IX Item "write"
+.IP flush 4
+.IX Item "flush"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP newStream([OPTS]) 4
+.IX Item "newStream([OPTS])"
+.IP deflateParams 4
+.IX Item "deflateParams"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all, :constants, :flush, :level, :strategy
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::RawDeflate \- Write RFC 1951 files/buffers"
+.IX Subsection "IO::Compress::RawDeflate - Write RFC 1951 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "rawdeflate \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeIn => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A Buffer, A Filename, A
+Filehandle, \f(CW\*(C`Merge => 0|1\*(C'\fR, \-Level, \-Strategy, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP printf 4
+.IX Item "printf"
+.IP syswrite 4
+.IX Item "syswrite"
+.IP write 4
+.IX Item "write"
+.IP flush 4
+.IX Item "flush"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP newStream([OPTS]) 4
+.IX Item "newStream([OPTS])"
+.IP deflateParams 4
+.IX Item "deflateParams"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all, :constants, :flush, :level, :strategy
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Compress::Zip \- Write zip files/buffers"
+.IX Subsection "IO::Compress::Zip - Write zip files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Store (0), Deflate (8), Bzip2 (12), Lzma (14), Zstandard (93), Xz (95)
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.PD 0
+.ie n .IP "zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "zip \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, the full filename contained in
+\&\f(CW$input_filename_or_reference\fR, the file protection attributes, the
+UID/GID for the file, the file timestamps, A filename, A filehandle, A
+scalar reference, An Array Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeIn => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A Buffer, A Filename, A
+Filehandle, \f(CW\*(C`Name => $string\*(C'\fR, If the \f(CW$input\fR parameter is not a
+filename, the \fIarchive member name\fR will be an empty string, \f(CW\*(C`CanonicalName => 0|1\*(C'\fR, \f(CW\*(C`FilterName => sub { ... }\*(C'\fR, \f(CW\*(C`Efs => 0|1\*(C'\fR, \f(CW\*(C`Minimal => 1|0\*(C'\fR, \f(CW\*(C`Stream => 0|1\*(C'\fR, \f(CW\*(C`Zip64 => 0|1\*(C'\fR,
+\&\-Level, \-Strategy, \f(CW\*(C`BlockSize100K => number\*(C'\fR, \f(CW\*(C`WorkFactor => number\*(C'\fR, \f(CW\*(C`Preset => number\*(C'\fR, \f(CW\*(C`Extreme => 0|1\*(C'\fR, \f(CW\*(C`Time => $number\*(C'\fR,
+\&\f(CW\*(C`ExtAttr => $attr\*(C'\fR, \f(CW\*(C`exTime => [$atime, $mtime, $ctime]\*(C'\fR, \f(CW\*(C`exUnix2 => [$uid, $gid]\*(C'\fR, \f(CW\*(C`exUnixN => [$uid, $gid]\*(C'\fR, \f(CWComment =>
+$comment\fR, \f(CW\*(C`ZipComment => $comment\*(C'\fR, \f(CW\*(C`Method => $method\*(C'\fR, \f(CW\*(C`TextFlag => 0|1\*(C'\fR, \f(CW\*(C`ExtraFieldLocal => $data\*(C'\fR, \f(CW\*(C`ExtraFieldCentral
+=> $data\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP print 4
+.IX Item "print"
+.IP printf 4
+.IX Item "printf"
+.IP syswrite 4
+.IX Item "syswrite"
+.IP write 4
+.IX Item "write"
+.IP flush 4
+.IX Item "flush"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP newStream([OPTS]) 4
+.IX Item "newStream([OPTS])"
+.IP deflateParams 4
+.IX Item "deflateParams"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all, :constants, :flush, :level, :strategy, :zip_method
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Apache::GZip Revisited" 4
+.IX Item "Apache::GZip Revisited"
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Dir \- supply object methods for directory handles"
+.IX Subsection "IO::Dir - supply object methods for directory handles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (),
+rewind (), close (), tie \f(CW%hash\fR, 'IO::Dir', DIRNAME [, OPTIONS ]
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::File \- supply object methods for filehandles"
+.IX Subsection "IO::File - supply object methods for filehandles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile
+.IP METHODS 4
+.IX Item "METHODS"
+open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode(
+[LAYER] )
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "IO::Handle \- supply object methods for I/O handles"
+.IX Subsection "IO::Handle - supply object methods for I/O handles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new (), new_from_fd ( FD, MODE )
+.IP METHODS 4
+.IX Item "METHODS"
+\&\f(CW$io\fR\->fdopen ( FD, MODE ), \f(CW$io\fR\->opened, \f(CW$io\fR\->getline, \f(CW$io\fR\->getlines,
+\&\f(CW$io\fR\->ungetc ( ORD ), \f(CW$io\fR\->write ( BUF, LEN [, OFFSET ] ), \f(CW$io\fR\->error,
+\&\f(CW$io\fR\->clearerr, \f(CW$io\fR\->sync, \f(CW$io\fR\->flush, \f(CW$io\fR\->printflush ( ARGS ),
+\&\f(CW$io\fR\->blocking ( [ BOOL ] ), \f(CW$io\fR\->untaint
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "IO::Pipe \- supply object methods for pipes"
+.IX Subsection "IO::Pipe - supply object methods for pipes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( [READER, WRITER] )
+.IP METHODS 4
+.IX Item "METHODS"
+reader ([ARGS]), writer ([ARGS]), handles ()
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::Poll \- Object interface to system poll call"
+.IX Subsection "IO::Poll - Object interface to system poll call"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove (
+IO ), handles( [ EVENT_MASK ] )
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::Seekable \- supply seek based methods for I/O objects"
+.IX Subsection "IO::Seekable - supply seek based methods for I/O objects"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$io\fR\->getpos, \f(CW$io\fR\->setpos, \f(CW$io\fR\->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
+WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), \f(CW$io\fR\->sysseek( POS, WHENCE ),
+\&\f(CW$io\fR\->tell
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "IO::Select \- OO interface to the select system call"
+.IX Subsection "IO::Select - OO interface to the select system call"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( [ HANDLES ] )
+.IP METHODS 4
+.IX Item "METHODS"
+add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read (
+[ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ),
+count (), \fBbits()\fR, select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::Socket \- Object interface to socket communications"
+.IX Subsection "IO::Socket - Object interface to socket communications"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CONSTRUCTOR ARGUMENTS" 4
+.IX Item "CONSTRUCTOR ARGUMENTS"
+.RS 4
+.IP Blocking 4
+.IX Item "Blocking"
+.IP Domain 4
+.IX Item "Domain"
+.IP Listen 4
+.IX Item "Listen"
+.IP Timeout 4
+.IX Item "Timeout"
+.IP Type 4
+.IX Item "Type"
+.RE
+.RS 4
+.RE
+.IP CONSTRUCTORS 4
+.IX Item "CONSTRUCTORS"
+.RS 4
+.IP new 4
+.IX Item "new"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP accept 4
+.IX Item "accept"
+.IP atmark 4
+.IX Item "atmark"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP bind 4
+.IX Item "bind"
+.IP connected 4
+.IX Item "connected"
+.IP getsockopt 4
+.IX Item "getsockopt"
+.IP listen 4
+.IX Item "listen"
+.IP peername 4
+.IX Item "peername"
+.IP protocol 4
+.IX Item "protocol"
+.IP recv 4
+.IX Item "recv"
+.IP send 4
+.IX Item "send"
+.IP setsockopt 4
+.IX Item "setsockopt"
+.IP shutdown 4
+.IX Item "shutdown"
+.IP sockdomain 4
+.IX Item "sockdomain"
+.IP socket 4
+.IX Item "socket"
+.IP socketpair 4
+.IX Item "socketpair"
+.IP sockname 4
+.IX Item "sockname"
+.IP sockopt 4
+.IX Item "sockopt"
+.IP socktype 4
+.IX Item "socktype"
+.IP timeout 4
+.IX Item "timeout"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::Socket::INET \- Object interface for AF_INET domain sockets"
+.IX Subsection "IO::Socket::INET - Object interface for AF_INET domain sockets"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( [ARGS] )
+.RS 4
+.IP METHODS 4
+.IX Item "METHODS"
+sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost
+()
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.ie n .SS "IO::Socket::IP, ""IO::Socket::IP"" \- Family-neutral IP socket supporting both IPv4 and IPv6"
+.el .SS "IO::Socket::IP, \f(CWIO::Socket::IP\fP \- Family-neutral IP socket supporting both IPv4 and IPv6"
+.IX Subsection "IO::Socket::IP, IO::Socket::IP - Family-neutral IP socket supporting both IPv4 and IPv6"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.ie n .IP "REPLACING ""IO::Socket"" DEFAULT BEHAVIOUR" 4
+.el .IP "REPLACING \f(CWIO::Socket\fR DEFAULT BEHAVIOUR" 4
+.IX Item "REPLACING IO::Socket DEFAULT BEHAVIOUR"
+.IP CONSTRUCTORS 4
+.IX Item "CONSTRUCTORS"
+.IP new 4
+.IX Item "new"
+.PD
+PeerHost => STRING, PeerService => STRING, PeerAddr => STRING, PeerPort =>
+STRING, PeerAddrInfo => ARRAY, LocalHost => STRING, LocalService => STRING,
+LocalAddr => STRING, LocalPort => STRING, LocalAddrInfo => ARRAY, Family =>
+INT, Type => INT, Proto => STRING or INT, GetAddrInfoFlags => INT, Listen
+=> INT, ReuseAddr => BOOL, ReusePort => BOOL, Broadcast => BOOL, Sockopts
+=> ARRAY, V6Only => BOOL, MultiHomed, Blocking => BOOL, Timeout => NUM
+.IP "new (one arg)" 4
+.IX Item "new (one arg)"
+.PD 0
+.IP METHODS 4
+.IX Item "METHODS"
+.IP sockhost_service 4
+.IX Item "sockhost_service"
+.IP sockhost 4
+.IX Item "sockhost"
+.IP sockport 4
+.IX Item "sockport"
+.IP sockhostname 4
+.IX Item "sockhostname"
+.IP sockservice 4
+.IX Item "sockservice"
+.IP sockaddr 4
+.IX Item "sockaddr"
+.IP peerhost_service 4
+.IX Item "peerhost_service"
+.IP peerhost 4
+.IX Item "peerhost"
+.IP peerport 4
+.IX Item "peerport"
+.IP peerhostname 4
+.IX Item "peerhostname"
+.IP peerservice 4
+.IX Item "peerservice"
+.IP peeraddr 4
+.IX Item "peeraddr"
+.IP as_inet 4
+.IX Item "as_inet"
+.IP NON-BLOCKING 4
+.IX Item "NON-BLOCKING"
+.ie n .IP """PeerHost"" AND ""LocalHost"" PARSING" 4
+.el .IP "\f(CWPeerHost\fR AND \f(CWLocalHost\fR PARSING" 4
+.IX Item "PeerHost AND LocalHost PARSING"
+.RS 4
+.IP split_addr 4
+.IX Item "split_addr"
+.RE
+.RS 4
+.RE
+.IP join_addr 4
+.IX Item "join_addr"
+.ie n .IP """IO::Socket::INET"" INCOMPATIBILITES" 4
+.el .IP "\f(CWIO::Socket::INET\fR INCOMPATIBILITES" 4
+.IX Item "IO::Socket::INET INCOMPATIBILITES"
+.IP TODO 4
+.IX Item "TODO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "IO::Socket::UNIX \- Object interface for AF_UNIX domain sockets"
+.IX Subsection "IO::Socket::UNIX - Object interface for AF_UNIX domain sockets"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( [ARGS] )
+.IP METHODS 4
+.IX Item "METHODS"
+\&\fBhostpath()\fR, \fBpeerpath()\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IO::Uncompress::AnyInflate \- Uncompress zlib-based (zip, gzip) file/buffer"
+.IX Subsection "IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip) file/buffer"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.PD 0
+.ie n .IP "anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "anyinflate \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR, \f(CW\*(C`RawInflate => 0|1\*(C'\fR, \f(CW\*(C`ParseExtra => 0|1\*(C'\fR If the gzip FEXTRA header field is present and
+this option is set, it will force the module to check that it conforms to
+the sub-field structure as defined in RFC 1952
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP inflateSync 4
+.IX Item "inflateSync"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::AnyUncompress \- Uncompress gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or lzop file/buffer"
+.IX Subsection "IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or lzop file/buffer"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip, zstd (Zstandard),
+bzip2, lzop, lzf, lzma, lzip, xz
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.PD 0
+.ie n .IP "anyuncompress $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "anyuncompress \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "anyuncompress $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR, \f(CW\*(C`RawInflate => 0|1\*(C'\fR, \f(CW\*(C`UnLzma => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::Base \- Base Class for IO::Uncompress modules"
+.IX Subsection "IO::Uncompress::Base - Base Class for IO::Uncompress modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::Bunzip2 \- Read bzip2 files/buffers"
+.IX Subsection "IO::Uncompress::Bunzip2 - Read bzip2 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "bunzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "bunzip2 \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "bunzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR, \f(CW\*(C`Small => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::Gunzip \- Read RFC 1952 files/buffers"
+.IX Subsection "IO::Uncompress::Gunzip - Read RFC 1952 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "gunzip \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR, \f(CW\*(C`ParseExtra => 0|1\*(C'\fR If the gzip FEXTRA header field is present and this option is set, it
+will force the module to check that it conforms to the sub-field structure
+as defined in RFC 1952
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP inflateSync 4
+.IX Item "inflateSync"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.PD
+Name, Comment
+.IP tell 4
+.IX Item "tell"
+.PD 0
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::Inflate \- Read RFC 1950 files/buffers"
+.IX Subsection "IO::Uncompress::Inflate - Read RFC 1950 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "inflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "inflate \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "inflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP inflateSync 4
+.IX Item "inflateSync"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::RawInflate \- Read RFC 1951 files/buffers"
+.IX Subsection "IO::Uncompress::RawInflate - Read RFC 1951 files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.ie n .IP "rawinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "rawinflate \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "rawinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CWInputLength =>
+$size\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP inflateSync 4
+.IX Item "inflateSync"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Uncompress::Unzip \- Read zip files/buffers"
+.IX Subsection "IO::Uncompress::Unzip - Read zip files/buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Store (0), Deflate (8), Bzip2 (12), Lzma (14), Xz (95), Zstandard (93)
+.IP "Functional Interface" 4
+.IX Item "Functional Interface"
+.RS 4
+.PD 0
+.ie n .IP "unzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]" 4
+.el .IP "unzip \f(CW$input_filename_or_reference\fR => \f(CW$output_filename_or_reference\fR [, OPTS]" 4
+.IX Item "unzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.PD
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+.IP Notes 4
+.IX Item "Notes"
+.PD 0
+.IP "Optional Parameters" 4
+.IX Item "Optional Parameters"
+.PD
+\&\f(CW\*(C`AutoClose => 0|1\*(C'\fR, \f(CW\*(C`BinModeOut => 0|1\*(C'\fR, \f(CW\*(C`Append => 0|1\*(C'\fR, A
+Buffer, A Filename, A Filehandle, \f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`TrailingData => $scalar\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "OO Interface" 4
+.IX Item "OO Interface"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.PD
+A filename, A filehandle, A scalar reference
+.IP "Constructor Options" 4
+.IX Item "Constructor Options"
+\&\f(CW\*(C`Name => "membername"\*(C'\fR, \f(CW\*(C`Efs => 0| 1\*(C'\fR, \f(CW\*(C`AutoClose => 0|1\*(C'\fR,
+\&\f(CW\*(C`MultiStream => 0|1\*(C'\fR, \f(CW\*(C`Prime => $string\*(C'\fR, \f(CW\*(C`Transparent => 0|1\*(C'\fR, \f(CW\*(C`BlockSize => $num\*(C'\fR, \f(CW\*(C`InputLength => $size\*(C'\fR, \f(CW\*(C`Append =>
+0|1\*(C'\fR, \f(CW\*(C`Strict => 0|1\*(C'\fR
+.IP Examples 4
+.IX Item "Examples"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.IP read 4
+.IX Item "read"
+.IP read 4
+.IX Item "read"
+.IP getline 4
+.IX Item "getline"
+.IP getc 4
+.IX Item "getc"
+.IP ungetc 4
+.IX Item "ungetc"
+.IP inflateSync 4
+.IX Item "inflateSync"
+.IP getHeaderInfo 4
+.IX Item "getHeaderInfo"
+.IP tell 4
+.IX Item "tell"
+.IP eof 4
+.IX Item "eof"
+.IP seek 4
+.IX Item "seek"
+.IP binmode 4
+.IX Item "binmode"
+.IP opened 4
+.IX Item "opened"
+.IP autoflush 4
+.IX Item "autoflush"
+.IP input_line_number 4
+.IX Item "input_line_number"
+.IP fileno 4
+.IX Item "fileno"
+.IP close 4
+.IX Item "close"
+.IP nextStream 4
+.IX Item "nextStream"
+.IP trailingData 4
+.IX Item "trailingData"
+.RE
+.RS 4
+.RE
+.IP Importing 4
+.IX Item "Importing"
+.PD
+:all
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Working with Net::FTP" 4
+.IX Item "Working with Net::FTP"
+.IP "Walking through a zip file" 4
+.IX Item "Walking through a zip file"
+.IP "Unzipping a complete zip file to disk" 4
+.IX Item "Unzipping a complete zip file to disk"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "MODIFICATION HISTORY" 4
+.IX Item "MODIFICATION HISTORY"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "IO::Zlib \- IO:: style interface to Compress::Zlib"
+.IX Subsection "IO::Zlib - IO:: style interface to Compress::Zlib"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.PD
+new ( [ARGS] )
+.IP "OBJECT METHODS" 4
+.IX Item "OBJECT METHODS"
+open ( FILENAME, MODE ), opened, close, getc, getline, getlines, print (
+ARGS... ), read ( BUF, NBYTES, [OFFSET] ), eof, seek ( OFFSET, WHENCE ),
+tell, setpos ( POS ), getpos ( POS )
+.IP "USING THE EXTERNAL GZIP" 4
+.IX Item "USING THE EXTERNAL GZIP"
+.PD 0
+.IP "CLASS METHODS" 4
+.IX Item "CLASS METHODS"
+.PD
+has_Compress_Zlib, gzip_external, gzip_used, gzip_read_open,
+gzip_write_open
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+IO::Zlib::getlines: must be called in list context,
+IO::Zlib::gzopen_external: mode '...' is illegal, IO::Zlib::import: '...'
+is illegal, IO::Zlib::import: ':gzip_external' requires an argument,
+IO::Zlib::import: 'gzip_read_open' requires an argument, IO::Zlib::import:
+\&'gzip_read' '...' is illegal, IO::Zlib::import: 'gzip_write_open' requires
+an argument, IO::Zlib::import: 'gzip_write_open' '...' is illegal,
+IO::Zlib::import: no Compress::Zlib and no external gzip, IO::Zlib::open:
+needs a filename, IO::Zlib::READ: NBYTES must be specified,
+IO::Zlib::WRITE: too long LENGTH
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IPC::Cmd \- finding and running system commands made easy"
+.IX Subsection "IPC::Cmd - finding and running system commands made easy"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CLASS METHODS" 4
+.IX Item "CLASS METHODS"
+.RS 4
+.ie n .IP "$ipc_run_version = IPC::Cmd\->can_use_ipc_run( [VERBOSE] )" 4
+.el .IP "\f(CW$ipc_run_version\fR = IPC::Cmd\->can_use_ipc_run( [VERBOSE] )" 4
+.IX Item "$ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] )"
+.RE
+.RS 4
+.RE
+.ie n .IP "$ipc_open3_version = IPC::Cmd\->can_use_ipc_open3( [VERBOSE] )" 4
+.el .IP "\f(CW$ipc_open3_version\fR = IPC::Cmd\->can_use_ipc_open3( [VERBOSE] )" 4
+.IX Item "$ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )"
+.ie n .IP "$bool = IPC::Cmd\->can_capture_buffer" 4
+.el .IP "\f(CW$bool\fR = IPC::Cmd\->can_capture_buffer" 4
+.IX Item "$bool = IPC::Cmd->can_capture_buffer"
+.ie n .IP "$bool = IPC::Cmd\->can_use_run_forked" 4
+.el .IP "\f(CW$bool\fR = IPC::Cmd\->can_use_run_forked" 4
+.IX Item "$bool = IPC::Cmd->can_use_run_forked"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.ie n .IP "$path = can_run( PROGRAM );" 4
+.el .IP "\f(CW$path\fR = can_run( PROGRAM );" 4
+.IX Item "$path = can_run( PROGRAM );"
+.RE
+.RS 4
+.RE
+.ie n .IP "$ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => \e$SCALAR, timeout => DIGIT] );" 4
+.el .IP "\f(CW$ok\fR | ($ok, \f(CW$err\fR, \f(CW$full_buf\fR, \f(CW$stdout_buff\fR, \f(CW$stderr_buff\fR) = run( command => COMMAND, [verbose => BOOL, buffer => \e$SCALAR, timeout => DIGIT] );" 4
+.IX Item "$ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => $SCALAR, timeout => DIGIT] );"
+.PD
+command, verbose, buffer, timeout, success, error message, full_buffer,
+out_buffer, error_buffer
+.ie n .IP "$hashref = run_forked( COMMAND, { child_stdin => SCALAR, timeout => DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} );" 4
+.el .IP "\f(CW$hashref\fR = run_forked( COMMAND, { child_stdin => SCALAR, timeout => DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} );" 4
+.IX Item "$hashref = run_forked( COMMAND, { child_stdin => SCALAR, timeout => DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} );"
+\&\f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`child_stdin\*(C'\fR, \f(CW\*(C`stdout_handler\*(C'\fR, \f(CW\*(C`stderr_handler\*(C'\fR,
+\&\f(CW\*(C`wait_loop_callback\*(C'\fR, \f(CW\*(C`discard_output\*(C'\fR,
+\&\f(CW\*(C`terminate_on_parent_sudden_death\*(C'\fR, \f(CW\*(C`exit_code\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR,
+\&\f(CW\*(C`stderr\*(C'\fR, \f(CW\*(C`merged\*(C'\fR, \f(CW\*(C`err_msg\*(C'\fR
+.ie n .IP "$q = QUOTE" 4
+.el .IP "\f(CW$q\fR = QUOTE" 4
+.IX Item "$q = QUOTE"
+.PD 0
+.IP "HOW IT WORKS" 4
+.IX Item "HOW IT WORKS"
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.RS 4
+.ie n .IP $IPC::Cmd::VERBOSE 4
+.el .IP \f(CW$IPC::Cmd::VERBOSE\fR 4
+.IX Item "$IPC::Cmd::VERBOSE"
+.ie n .IP $IPC::Cmd::USE_IPC_RUN 4
+.el .IP \f(CW$IPC::Cmd::USE_IPC_RUN\fR 4
+.IX Item "$IPC::Cmd::USE_IPC_RUN"
+.ie n .IP $IPC::Cmd::USE_IPC_OPEN3 4
+.el .IP \f(CW$IPC::Cmd::USE_IPC_OPEN3\fR 4
+.IX Item "$IPC::Cmd::USE_IPC_OPEN3"
+.ie n .IP $IPC::Cmd::WARN 4
+.el .IP \f(CW$IPC::Cmd::WARN\fR 4
+.IX Item "$IPC::Cmd::WARN"
+.ie n .IP $IPC::Cmd::INSTANCES 4
+.el .IP \f(CW$IPC::Cmd::INSTANCES\fR 4
+.IX Item "$IPC::Cmd::INSTANCES"
+.ie n .IP $IPC::Cmd::ALLOW_NULL_ARGS 4
+.el .IP \f(CW$IPC::Cmd::ALLOW_NULL_ARGS\fR 4
+.IX Item "$IPC::Cmd::ALLOW_NULL_ARGS"
+.RE
+.RS 4
+.RE
+.IP Caveats 4
+.IX Item "Caveats"
+.PD
+Whitespace and IPC::Open3 / \fBsystem()\fR, Whitespace and IPC::Run, IO Redirect,
+Interleaving STDOUT/STDERR
+.IP "See Also" 4
+.IX Item "See Also"
+.PD 0
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IPC::Msg \- SysV Msg IPC object class"
+.IX Subsection "IPC::Msg - SysV Msg IPC object class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+new ( KEY , FLAGS ), id, rcv ( BUF, LEN [, TYPE [, FLAGS ]] ), remove, set
+( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), snd ( TYPE, MSG [,
+FLAGS ] ), stat
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IPC::Open2 \- open a process for both reading and writing using \fBopen2()\fP"
+.IX Subsection "IPC::Open2 - open a process for both reading and writing using open2()"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP WARNING 4
+.IX Item "WARNING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "IPC::Open3 \- open a process for reading, writing, and error handling using \fBopen3()\fP"
+.IX Subsection "IPC::Open3 - open a process for reading, writing, and error handling using open3()"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "See Also" 4
+.IX Item "See Also"
+.PD
+IPC::Open2, IPC::Run
+.IP WARNING 4
+.IX Item "WARNING"
+.SS "IPC::Semaphore \- SysV Semaphore IPC object class"
+.IX Subsection "IPC::Semaphore - SysV Semaphore IPC object class"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+new ( KEY , NSEMS , FLAGS ), getall, getncnt ( SEM ), getpid ( SEM ),
+getval ( SEM ), getzcnt ( SEM ), id, op ( OPLIST ), remove, set ( STAT ),
+set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N
+, VALUE ), stat
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IPC::SharedMem \- SysV Shared Memory IPC object class"
+.IX Subsection "IPC::SharedMem - SysV Shared Memory IPC object class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+new ( KEY , SIZE , FLAGS ), id, read ( POS, SIZE ), write ( STRING, POS,
+SIZE ), remove, is_removed, stat, attach ( [FLAG] ), detach, addr
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "IPC::SysV \- System V IPC constants and system calls"
+.IX Subsection "IPC::SysV - System V IPC constants and system calls"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+ftok( PATH ), ftok( PATH, ID ), shmat( ID, ADDR, FLAG ), shmdt( ADDR ),
+memread( ADDR, VAR, POS, SIZE ), memwrite( ADDR, STRING, POS, SIZE )
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Internals \- Reserved special namespace for internals related functions"
+.IX Subsection "Internals - Reserved special namespace for internals related functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+SvREFCNT(THING [, \f(CW$value\fR]), SvREADONLY(THING, [, \f(CW$value\fR]),
+hv_clear_placeholders(%hash)
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "JSON::PP \- JSON::XS compatible pure-Perl module."
+.IX Subsection "JSON::PP - JSON::XS compatible pure-Perl module."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FUNCTIONAL INTERFACE" 4
+.IX Item "FUNCTIONAL INTERFACE"
+.RS 4
+.IP encode_json 4
+.IX Item "encode_json"
+.IP decode_json 4
+.IX Item "decode_json"
+.IP JSON::PP::is_bool 4
+.IX Item "JSON::PP::is_bool"
+.RE
+.RS 4
+.RE
+.IP "OBJECT-ORIENTED INTERFACE" 4
+.IX Item "OBJECT-ORIENTED INTERFACE"
+.RS 4
+.IP new 4
+.IX Item "new"
+.IP ascii 4
+.IX Item "ascii"
+.IP latin1 4
+.IX Item "latin1"
+.IP utf8 4
+.IX Item "utf8"
+.IP pretty 4
+.IX Item "pretty"
+.IP indent 4
+.IX Item "indent"
+.IP space_before 4
+.IX Item "space_before"
+.IP space_after 4
+.IX Item "space_after"
+.IP relaxed 4
+.IX Item "relaxed"
+.PD
+list items can have an end-comma, shell-style '#'\-comments, C\-style
+multiple-line '/* */'\-comments (JSON::PP only), C++\-style one-line
+\&'//'\-comments (JSON::PP only), literal ASCII TAB characters in strings
+.IP canonical 4
+.IX Item "canonical"
+.PD 0
+.IP allow_nonref 4
+.IX Item "allow_nonref"
+.IP allow_unknown 4
+.IX Item "allow_unknown"
+.IP allow_blessed 4
+.IX Item "allow_blessed"
+.IP convert_blessed 4
+.IX Item "convert_blessed"
+.IP allow_tags 4
+.IX Item "allow_tags"
+.IP boolean_values 4
+.IX Item "boolean_values"
+.IP core_bools 4
+.IX Item "core_bools"
+.IP filter_json_object 4
+.IX Item "filter_json_object"
+.IP filter_json_single_key_object 4
+.IX Item "filter_json_single_key_object"
+.IP shrink 4
+.IX Item "shrink"
+.IP max_depth 4
+.IX Item "max_depth"
+.IP max_size 4
+.IX Item "max_size"
+.IP encode 4
+.IX Item "encode"
+.IP decode 4
+.IX Item "decode"
+.IP decode_prefix 4
+.IX Item "decode_prefix"
+.RE
+.RS 4
+.RE
+.IP "FLAGS FOR JSON::PP ONLY" 4
+.IX Item "FLAGS FOR JSON::PP ONLY"
+.RS 4
+.IP allow_singlequote 4
+.IX Item "allow_singlequote"
+.IP allow_barekey 4
+.IX Item "allow_barekey"
+.IP allow_bignum 4
+.IX Item "allow_bignum"
+.IP loose 4
+.IX Item "loose"
+.IP escape_slash 4
+.IX Item "escape_slash"
+.IP indent_length 4
+.IX Item "indent_length"
+.IP sort_by 4
+.IX Item "sort_by"
+.RE
+.RS 4
+.RE
+.IP "INCREMENTAL PARSING" 4
+.IX Item "INCREMENTAL PARSING"
+.RS 4
+.IP incr_parse 4
+.IX Item "incr_parse"
+.IP incr_text 4
+.IX Item "incr_text"
+.IP incr_skip 4
+.IX Item "incr_skip"
+.IP incr_reset 4
+.IX Item "incr_reset"
+.RE
+.RS 4
+.RE
+.IP MAPPING 4
+.IX Item "MAPPING"
+.RS 4
+.IP "JSON \-> PERL" 4
+.IX Item "JSON -> PERL"
+.PD
+object, array, string, number, true, false, null, shell-style comments (\f(CW\*(C`# \fR\f(CItext\fR\f(CW\*(C'\fR), tagged values (\f(CW\*(C`(\fR\f(CItag\fR\f(CW)\fR\f(CIvalue\fR\f(CW\*(C'\fR)
+.IP "PERL \-> JSON" 4
+.IX Item "PERL -> JSON"
+hash references, array references, other references, JSON::PP::true,
+JSON::PP::false, JSON::PP::null, blessed objects, simple scalars
+.IP "OBJECT SERIALISATION" 4
+.IX Item "OBJECT SERIALISATION"
+1. \f(CW\*(C`allow_tags\*(C'\fR is enabled and the object has a \f(CW\*(C`FREEZE\*(C'\fR method, 2.
+\&\f(CW\*(C`convert_blessed\*(C'\fR is enabled and the object has a \f(CW\*(C`TO_JSON\*(C'\fR method, 3.
+\&\f(CW\*(C`allow_bignum\*(C'\fR is enabled and the object is a \f(CW\*(C`Math::BigInt\*(C'\fR or
+\&\f(CW\*(C`Math::BigFloat\*(C'\fR, 4. \f(CW\*(C`allow_blessed\*(C'\fR is enabled, 5. none of the above
+.RE
+.RS 4
+.RE
+.IP "ENCODING/CODESET FLAG NOTES" 4
+.IX Item "ENCODING/CODESET FLAG NOTES"
+\&\f(CW\*(C`utf8\*(C'\fR flag disabled, \f(CW\*(C`utf8\*(C'\fR flag enabled, \f(CW\*(C`latin1\*(C'\fR or \f(CW\*(C`ascii\*(C'\fR flags
+enabled
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "CURRENT MAINTAINER" 4
+.IX Item "CURRENT MAINTAINER"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "JSON::PP::Boolean \- dummy module providing JSON::PP::Boolean"
+.IX Subsection "JSON::PP::Boolean - dummy module providing JSON::PP::Boolean"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "List::Util \- A selection of general-utility list subroutines"
+.IX Subsection "List::Util - A selection of general-utility list subroutines"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "LIST-REDUCTION FUNCTIONS" 4
+.IX Item "LIST-REDUCTION FUNCTIONS"
+.IP reduce 4
+.IX Item "reduce"
+.IP reductions 4
+.IX Item "reductions"
+.IP any 4
+.IX Item "any"
+.IP all 4
+.IX Item "all"
+.IP none 4
+.IX Item "none"
+.IP notall 4
+.IX Item "notall"
+.IP first 4
+.IX Item "first"
+.IP max 4
+.IX Item "max"
+.IP maxstr 4
+.IX Item "maxstr"
+.IP min 4
+.IX Item "min"
+.IP minstr 4
+.IX Item "minstr"
+.IP product 4
+.IX Item "product"
+.IP sum 4
+.IX Item "sum"
+.IP sum0 4
+.IX Item "sum0"
+.IP "KEY/VALUE PAIR LIST FUNCTIONS" 4
+.IX Item "KEY/VALUE PAIR LIST FUNCTIONS"
+.IP pairs 4
+.IX Item "pairs"
+.IP unpairs 4
+.IX Item "unpairs"
+.IP pairkeys 4
+.IX Item "pairkeys"
+.IP pairvalues 4
+.IX Item "pairvalues"
+.IP pairgrep 4
+.IX Item "pairgrep"
+.IP pairfirst 4
+.IX Item "pairfirst"
+.IP pairmap 4
+.IX Item "pairmap"
+.IP "OTHER FUNCTIONS" 4
+.IX Item "OTHER FUNCTIONS"
+.IP shuffle 4
+.IX Item "shuffle"
+.IP sample 4
+.IX Item "sample"
+.IP uniq 4
+.IX Item "uniq"
+.IP uniqint 4
+.IX Item "uniqint"
+.IP uniqnum 4
+.IX Item "uniqnum"
+.IP uniqstr 4
+.IX Item "uniqstr"
+.IP head 4
+.IX Item "head"
+.IP tail 4
+.IX Item "tail"
+.IP zip 4
+.IX Item "zip"
+.IP mesh 4
+.IX Item "mesh"
+.IP "CONFIGURATION VARIABLES" 4
+.IX Item "CONFIGURATION VARIABLES"
+.RS 4
+.ie n .IP $RAND 4
+.el .IP \f(CW$RAND\fR 4
+.IX Item "$RAND"
+.RE
+.RS 4
+.RE
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.RS 4
+.IP "RT #95409" 4
+.IX Item "RT #95409"
+.IP "\fBuniqnum()\fR on oversized bignums" 4
+.IX Item "uniqnum() on oversized bignums"
+.RE
+.RS 4
+.RE
+.IP "SUGGESTED ADDITIONS" 4
+.IX Item "SUGGESTED ADDITIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "List::Util::XS \- Indicate if List::Util was compiled with a C compiler"
+.IX Subsection "List::Util::XS - Indicate if List::Util was compiled with a C compiler"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Locale::Maketext \- framework for localization"
+.IX Subsection "Locale::Maketext - framework for localization"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "QUICK OVERVIEW" 4
+.IX Item "QUICK OVERVIEW"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Construction Methods" 4
+.IX Item "Construction Methods"
+.IP "The ""maketext"" Method" 4
+.IX Item "The ""maketext"" Method"
+.PD
+\&\f(CW$lh\fR\->fail_with \fIor\fR \f(CW$lh\fR\->fail_with(\fIPARAM\fR), \f(CW$lh\fR\->failure_handler_auto,
+\&\f(CW$lh\fR\->denylist(@list) <or> \f(CW$lh\fR\->blacklist(@list), \f(CW$lh\fR\->allowlist(@list) <or>
+\&\f(CW$lh\fR\->whitelist(@list)
+.IP "Utility Methods" 4
+.IX Item "Utility Methods"
+\&\f(CW$language\fR\->quant($number, \f(CW$singular\fR), \f(CW$language\fR\->quant($number, \f(CW$singular\fR,
+\&\f(CW$plural\fR), \f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR),
+\&\f(CW$language\fR\->numf($number), \f(CW$language\fR\->numerate($number, \f(CW$singular\fR, \f(CW$plural\fR,
+\&\f(CW$negative\fR), \f(CW$language\fR\->sprintf($format, \f(CW@items\fR), \f(CW$language\fR\->\fBlanguage_tag()\fR,
+\&\f(CW$language\fR\->\fBencoding()\fR
+.IP "Language Handle Attributes and Internals" 4
+.IX Item "Language Handle Attributes and Internals"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "LANGUAGE CLASS HIERARCHIES" 4
+.IX Item "LANGUAGE CLASS HIERARCHIES"
+.IP "ENTRIES IN EACH LEXICON" 4
+.IX Item "ENTRIES IN EACH LEXICON"
+.IP "BRACKET NOTATION" 4
+.IX Item "BRACKET NOTATION"
+.IP "BRACKET NOTATION SECURITY" 4
+.IX Item "BRACKET NOTATION SECURITY"
+.IP "AUTO LEXICONS" 4
+.IX Item "AUTO LEXICONS"
+.IP "READONLY LEXICONS" 4
+.IX Item "READONLY LEXICONS"
+.IP "CONTROLLING LOOKUP FAILURE" 4
+.IX Item "CONTROLLING LOOKUP FAILURE"
+.IP "HOW TO USE MAKETEXT" 4
+.IX Item "HOW TO USE MAKETEXT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMER" 4
+.IX Item "COPYRIGHT AND DISCLAIMER"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Locale::Maketext::Cookbook \- recipes for using Locale::Maketext"
+.IX Subsection "Locale::Maketext::Cookbook - recipes for using Locale::Maketext"
+.IP INTRODUCTION 4
+.IX Item "INTRODUCTION"
+.PD 0
+.IP "ONESIDED LEXICONS" 4
+.IX Item "ONESIDED LEXICONS"
+.IP "DECIMAL PLACES IN NUMBER FORMATTING" 4
+.IX Item "DECIMAL PLACES IN NUMBER FORMATTING"
+.PD
+.SS "Locale::Maketext::Guts \- Deprecated module to load Locale::Maketext utf8 code"
+.IX Subsection "Locale::Maketext::Guts - Deprecated module to load Locale::Maketext utf8 code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Locale::Maketext::GutsLoader \- Deprecated module to load Locale::Maketext utf8 code"
+.IX Subsection "Locale::Maketext::GutsLoader - Deprecated module to load Locale::Maketext utf8 code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Locale::Maketext::Simple \- Simple interface to Locale::Maketext::Lexicon"
+.IX Subsection "Locale::Maketext::Simple - Simple interface to Locale::Maketext::Lexicon"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RS 4
+.IP Class 4
+.IX Item "Class"
+.IP Path 4
+.IX Item "Path"
+.IP Style 4
+.IX Item "Style"
+.IP Export 4
+.IX Item "Export"
+.IP Subclass 4
+.IX Item "Subclass"
+.IP Decode 4
+.IX Item "Decode"
+.IP Encoding 4
+.IX Item "Encoding"
+.RE
+.RS 4
+.RE
+.IP ACKNOWLEDGMENTS 4
+.IX Item "ACKNOWLEDGMENTS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.RS 4
+.IP "The ""MIT"" License" 4
+.IX Item "The ""MIT"" License"
+.RE
+.RS 4
+.RE
+.PD
+.SS "Locale::Maketext::TPJ13 \-\- article about software localization"
+.IX Subsection "Locale::Maketext::TPJ13 -- article about software localization"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Localization and Perl: gettext breaks, Maketext fixes" 4
+.IX Item "Localization and Perl: gettext breaks, Maketext fixes"
+.RS 4
+.IP "A Localization Horror Story: It Could Happen To You" 4
+.IX Item "A Localization Horror Story: It Could Happen To You"
+.IP "The Linguistic View" 4
+.IX Item "The Linguistic View"
+.IP "Breaking gettext" 4
+.IX Item "Breaking gettext"
+.IP "Replacing gettext" 4
+.IX Item "Replacing gettext"
+.IP "Buzzwords: Abstraction and Encapsulation" 4
+.IX Item "Buzzwords: Abstraction and Encapsulation"
+.IP "Buzzword: Isomorphism" 4
+.IX Item "Buzzword: Isomorphism"
+.IP "Buzzword: Inheritance" 4
+.IX Item "Buzzword: Inheritance"
+.IP "Buzzword: Concision" 4
+.IX Item "Buzzword: Concision"
+.IP "The Devil in the Details" 4
+.IX Item "The Devil in the Details"
+.IP "The Proof in the Pudding: Localizing Web Sites" 4
+.IX Item "The Proof in the Pudding: Localizing Web Sites"
+.IP References 4
+.IX Item "References"
+.RE
+.RS 4
+.RE
+.PD
+.SS "MIME::Base64 \- Encoding and decoding of base64 strings"
+.IX Subsection "MIME::Base64 - Encoding and decoding of base64 strings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+encode_base64( \f(CW$bytes\fR ), encode_base64( \f(CW$bytes\fR, \f(CW$eol\fR );, decode_base64(
+\&\f(CW$str\fR ), encode_base64url( \f(CW$bytes\fR ), decode_base64url( \f(CW$str\fR ),
+encoded_base64_length( \f(CW$bytes\fR ), encoded_base64_length( \f(CW$bytes\fR, \f(CW$eol\fR ),
+decoded_base64_length( \f(CW$str\fR )
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "MIME::QuotedPrint \- Encoding and decoding of quoted-printable strings"
+.IX Subsection "MIME::QuotedPrint - Encoding and decoding of quoted-printable strings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+encode_qp( \f(CW$str\fR), encode_qp( \f(CW$str\fR, \f(CW$eol\fR), encode_qp( \f(CW$str\fR, \f(CW$eol\fR, \f(CW$binmode\fR
+), decode_qp( \f(CW$str\fR )
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Math::BigFloat \- arbitrary size floating point math package"
+.IX Subsection "Math::BigFloat - arbitrary size floating point math package"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Input 4
+.IX Item "Input"
+.IP Output 4
+.IX Item "Output"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Configuration methods" 4
+.IX Item "Configuration methods"
+.PD
+\&\fBaccuracy()\fR, \fBprecision()\fR
+.IP "Constructor methods" 4
+.IX Item "Constructor methods"
+\&\fBfrom_hex()\fR, \fBfrom_oct()\fR, \fBfrom_bin()\fR, \fBfrom_ieee754()\fR, \fBbpi()\fR
+.IP "Arithmetic methods" 4
+.IX Item "Arithmetic methods"
+\&\fBbmuladd()\fR, \fBbdiv()\fR, \fBbmod()\fR, \fBbexp()\fR, \fBbnok()\fR, \fBbsin()\fR, \fBbcos()\fR, \fBbatan()\fR,
+\&\fBbatan2()\fR, \fBas_float()\fR, \fBto_ieee754()\fR
+.IP "ACCURACY AND PRECISION" 4
+.IX Item "ACCURACY AND PRECISION"
+.PD 0
+.IP Rounding 4
+.IX Item "Rounding"
+.PD
+bfround ( +$scale ), bfround ( \-$scale ), bfround ( 0 ), bround  ( +$scale
+), bround  ( \-$scale ) and bround ( 0 )
+.RE
+.RS 4
+.RE
+.IP "NUMERIC LITERALS" 4
+.IX Item "NUMERIC LITERALS"
+.RS 4
+.PD 0
+.IP "Hexadecimal, octal, and binary floating point literals" 4
+.IX Item "Hexadecimal, octal, and binary floating point literals"
+.IP "Math library" 4
+.IX Item "Math library"
+.IP "Using Math::BigInt::Lite" 4
+.IX Item "Using Math::BigInt::Lite"
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+stringify, \fBbstr()\fR, \fBbrsft()\fR, Modifying and =, \fBprecision()\fR vs. \fBaccuracy()\fR
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings, The Bignum mailing list, Post to mailing list, View mailing list,
+Subscribe/Unsubscribe
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "Math::BigInt \- arbitrary size integer math package"
+.IX Subsection "Math::BigInt - arbitrary size integer math package"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Input 4
+.IX Item "Input"
+.IP Output 4
+.IX Item "Output"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Configuration methods" 4
+.IX Item "Configuration methods"
+.PD
+\&\fBaccuracy()\fR, \fBprecision()\fR, \fBdiv_scale()\fR, \fBround_mode()\fR, \fBupgrade()\fR, \fBdowngrade()\fR,
+\&\fBmodify()\fR, \fBconfig()\fR
+.IP "Constructor methods" 4
+.IX Item "Constructor methods"
+\&\fBnew()\fR, \fBfrom_dec()\fR, \fBfrom_hex()\fR, \fBfrom_oct()\fR, \fBfrom_bin()\fR, \fBfrom_bytes()\fR,
+\&\fBfrom_base()\fR, \fBfrom_base_num()\fR, \fBbzero()\fR, \fBbone()\fR, \fBbinf()\fR, \fBbnan()\fR, \fBbpi()\fR,
+\&\fBcopy()\fR, \fBas_int()\fR, \fBas_number()\fR, \fBas_float()\fR, \fBas_rat()\fR
+.IP "Boolean methods" 4
+.IX Item "Boolean methods"
+\&\fBis_zero()\fR, is_one( [ SIGN ]), \fBis_finite()\fR, is_inf( [ SIGN ] ), \fBis_nan()\fR,
+\&\fBis_positive()\fR, \fBis_pos()\fR, \fBis_negative()\fR, \fBis_neg()\fR, \fBis_non_positive()\fR,
+\&\fBis_non_negative()\fR, \fBis_odd()\fR, \fBis_even()\fR, \fBis_int()\fR
+.IP "Comparison methods" 4
+.IX Item "Comparison methods"
+\&\fBbcmp()\fR, \fBbacmp()\fR, \fBbeq()\fR, \fBbne()\fR, \fBblt()\fR, \fBble()\fR, \fBbgt()\fR, \fBbge()\fR
+.IP "Arithmetic methods" 4
+.IX Item "Arithmetic methods"
+\&\fBbneg()\fR, \fBbabs()\fR, \fBbsgn()\fR, \fBbnorm()\fR, \fBbinc()\fR, \fBbdec()\fR, \fBbadd()\fR, \fBbsub()\fR, \fBbmul()\fR,
+\&\fBbmuladd()\fR, \fBbdiv()\fR, \fBbtdiv()\fR, \fBbmod()\fR, \fBbtmod()\fR, \fBbmodinv()\fR, \fBbmodpow()\fR, \fBbpow()\fR,
+\&\fBblog()\fR, \fBbexp()\fR, \fBbnok()\fR, \fBbuparrow()\fR, \fBuparrow()\fR, \fBbackermann()\fR, \fBackermann()\fR,
+\&\fBbsin()\fR, \fBbcos()\fR, \fBbatan()\fR, \fBbatan2()\fR, \fBbsqrt()\fR, \fBbroot()\fR, \fBbfac()\fR, \fBbdfac()\fR,
+\&\fBbtfac()\fR, \fBbmfac()\fR, \fBbfib()\fR, \fBblucas()\fR, \fBbrsft()\fR, \fBblsft()\fR
+.IP "Bitwise methods" 4
+.IX Item "Bitwise methods"
+\&\fBband()\fR, \fBbior()\fR, \fBbxor()\fR, \fBbnot()\fR
+.IP "Rounding methods" 4
+.IX Item "Rounding methods"
+\&\fBround()\fR, \fBbround()\fR, \fBbfround()\fR, \fBbfloor()\fR, \fBbceil()\fR, \fBbint()\fR
+.IP "Other mathematical methods" 4
+.IX Item "Other mathematical methods"
+\&\fBbgcd()\fR, \fBblcm()\fR
+.IP "Object property methods" 4
+.IX Item "Object property methods"
+\&\fBsign()\fR, \fBdigit()\fR, \fBdigitsum()\fR, \fBbdigitsum()\fR, \fBlength()\fR, \fBmantissa()\fR, \fBexponent()\fR,
+\&\fBparts()\fR, \fBsparts()\fR, \fBnparts()\fR, \fBeparts()\fR, \fBdparts()\fR, \fBfparts()\fR, \fBnumerator()\fR,
+\&\fBdenominator()\fR
+.IP "String conversion methods" 4
+.IX Item "String conversion methods"
+\&\fBbstr()\fR, \fBbsstr()\fR, \fBbnstr()\fR, \fBbestr()\fR, \fBbdstr()\fR, \fBbfstr()\fR, \fBto_hex()\fR, \fBto_bin()\fR,
+\&\fBto_oct()\fR, \fBto_bytes()\fR, \fBto_base()\fR, \fBto_base_num()\fR, \fBas_hex()\fR, \fBas_bin()\fR,
+\&\fBas_oct()\fR, \fBas_bytes()\fR
+.IP "Other conversion methods" 4
+.IX Item "Other conversion methods"
+\&\fBnumify()\fR
+.IP "Utility methods" 4
+.IX Item "Utility methods"
+\&\fBdec_str_to_dec_flt_str()\fR, \fBhex_str_to_dec_flt_str()\fR,
+\&\fBoct_str_to_dec_flt_str()\fR, \fBbin_str_to_dec_flt_str()\fR, \fBdec_str_to_dec_str()\fR,
+\&\fBhex_str_to_dec_str()\fR, \fBoct_str_to_dec_str()\fR, \fBbin_str_to_dec_str()\fR
+.RE
+.RS 4
+.RE
+.IP "ACCURACY and PRECISION" 4
+.IX Item "ACCURACY and PRECISION"
+.RS 4
+.PD 0
+.IP "Precision P" 4
+.IX Item "Precision P"
+.IP "Accuracy A" 4
+.IX Item "Accuracy A"
+.IP "Fallback F" 4
+.IX Item "Fallback F"
+.IP "Rounding mode R" 4
+.IX Item "Rounding mode R"
+.PD
+\&'trunc', 'even', 'odd', '+inf', '\-inf', 'zero', 'common', Precision,
+Accuracy (significant digits), Setting/Accessing, Creating numbers, Usage,
+Precedence, Overriding globals, Local settings, Rounding, Default values,
+Remarks
+.RE
+.RS 4
+.RE
+.IP "Infinity and Not a Number" 4
+.IX Item "Infinity and Not a Number"
+\&\fBoct()\fR/\fBhex()\fR
+.IP INTERNALS 4
+.IX Item "INTERNALS"
+.RS 4
+.PD 0
+.IP "MATH LIBRARY" 4
+.IX Item "MATH LIBRARY"
+.IP SIGN 4
+.IX Item "SIGN"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP "NUMERIC LITERALS" 4
+.IX Item "NUMERIC LITERALS"
+.RS 4
+.IP "Hexadecimal, octal, and binary floating point literals" 4
+.IX Item "Hexadecimal, octal, and binary floating point literals"
+.RE
+.RS 4
+.RE
+.IP PERFORMANCE 4
+.IX Item "PERFORMANCE"
+.RS 4
+.IP "Alternative math libraries" 4
+.IX Item "Alternative math libraries"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP "Subclassing Math::BigInt" 4
+.IX Item "Subclassing Math::BigInt"
+.RE
+.RS 4
+.RE
+.IP UPGRADING 4
+.IX Item "UPGRADING"
+.RS 4
+.IP Auto-upgrade 4
+.IX Item "Auto-upgrade"
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+Comparing numbers as strings, \fBint()\fR, Modifying and =, Overloading \-$x,
+Mixing different object types
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings, The Bignum mailing list, Post to mailing list, View mailing list,
+Subscribe/Unsubscribe
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "Math::BigInt::Calc \- pure Perl module to support Math::BigInt"
+.IX Subsection "Math::BigInt::Calc - pure Perl module to support Math::BigInt"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.PD
+base_len, use_int
+.IP METHODS 4
+.IX Item "METHODS"
+\&\fB_base_len()\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "Math::BigInt::FastCalc \- Math::BigInt::Calc with some XS for more speed"
+.IX Subsection "Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more speed"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP STORAGE 4
+.IX Item "STORAGE"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Math::BigInt::Lib \- virtual parent class for Math::BigInt libraries"
+.IX Subsection "Math::BigInt::Lib - virtual parent class for Math::BigInt libraries"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "General Notes" 4
+.IX Item "General Notes"
+.PD
+CLASS\->\fBapi_version()\fR, CLASS\->_new(STR), CLASS\->\fB_zero()\fR,
+CLASS\->\fB_one()\fR, CLASS\->\fB_two()\fR, CLASS\->\fB_ten()\fR,
+CLASS\->_from_bin(STR), CLASS\->_from_oct(STR),
+CLASS\->_from_hex(STR), CLASS\->_from_bytes(STR),
+CLASS\->_from_base(STR, BASE, COLLSEQ), CLASS\->_from_base_num(ARRAY,
+BASE), CLASS\->_add(OBJ1, OBJ2), CLASS\->_mul(OBJ1, OBJ2),
+CLASS\->_div(OBJ1, OBJ2), CLASS\->_sub(OBJ1, OBJ2, FLAG),
+CLASS\->_sub(OBJ1, OBJ2), CLASS\->_sadd(OBJ1, SIGN1, OBJ2, SIGN2),
+CLASS\->_ssub(OBJ1, SIGN1, OBJ2, SIGN2), CLASS\->_dec(OBJ),
+CLASS\->_inc(OBJ), CLASS\->_mod(OBJ1, OBJ2), CLASS\->_sqrt(OBJ),
+CLASS\->_root(OBJ, N), CLASS\->_fac(OBJ), CLASS\->_dfac(OBJ),
+CLASS\->_pow(OBJ1, OBJ2), CLASS\->_modinv(OBJ1, OBJ2),
+CLASS\->_modpow(OBJ1, OBJ2, OBJ3), CLASS\->_rsft(OBJ, N, B),
+CLASS\->_lsft(OBJ, N, B), CLASS\->_log_int(OBJ, B),
+CLASS\->_gcd(OBJ1, OBJ2), CLASS\->_lcm(OBJ1, OBJ2),
+CLASS\->_fib(OBJ), CLASS\->_lucas(OBJ), CLASS\->_and(OBJ1, OBJ2),
+CLASS\->_or(OBJ1, OBJ2), CLASS\->_xor(OBJ1, OBJ2),
+CLASS\->_sand(OBJ1, OBJ2, SIGN1, SIGN2), CLASS\->_sor(OBJ1, OBJ2,
+SIGN1, SIGN2), CLASS\->_sxor(OBJ1, OBJ2, SIGN1, SIGN2),
+CLASS\->_is_zero(OBJ), CLASS\->_is_one(OBJ), CLASS\->_is_two(OBJ),
+CLASS\->_is_ten(OBJ), CLASS\->_is_even(OBJ), CLASS\->_is_odd(OBJ),
+CLASS\->_acmp(OBJ1, OBJ2), CLASS\->_str(OBJ),
+CLASS\->_to_bin(OBJ), CLASS\->_to_oct(OBJ), CLASS\->_to_hex(OBJ),
+CLASS\->_to_bytes(OBJ), CLASS\->_to_base(OBJ, BASE, COLLSEQ),
+CLASS\->_to_base_num(OBJ, BASE), CLASS\->_as_bin(OBJ),
+CLASS\->_as_oct(OBJ), CLASS\->_as_hex(OBJ),
+CLASS\->_as_bytes(OBJ), CLASS\->_num(OBJ), CLASS\->_copy(OBJ),
+CLASS\->_len(OBJ), CLASS\->_zeros(OBJ), CLASS\->_digit(OBJ, N),
+CLASS\->_digitsum(OBJ), CLASS\->_check(OBJ), CLASS\->_set(OBJ)
+.IP "API version 2" 4
+.IX Item "API version 2"
+CLASS\->_1ex(N), CLASS\->_nok(OBJ1, OBJ2), CLASS\->_alen(OBJ)
+.RE
+.RS 4
+.RE
+.IP "WRAP YOUR OWN" 4
+.IX Item "WRAP YOUR OWN"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+RT: CPAN's request tracker, AnnoCPAN: Annotated CPAN documentation, CPAN
+Ratings, MetaCPAN, CPAN Testers Matrix, The Bignum mailing list, Post to
+mailing list, View mailing list, Subscribe/Unsubscribe
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Math::BigRat \- arbitrary size rational number math package"
+.IX Subsection "Math::BigRat - arbitrary size rational number math package"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "MATH LIBRARY" 4
+.IX Item "MATH LIBRARY"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\fBnew()\fR, \fBnumerator()\fR, \fBdenominator()\fR, \fBparts()\fR, \fBdparts()\fR, \fBfparts()\fR, \fBnumify()\fR,
+\&\fBas_int()\fR, \fBas_number()\fR, \fBas_float()\fR, \fBas_hex()\fR, \fBas_bin()\fR, \fBas_oct()\fR,
+\&\fBfrom_hex()\fR, \fBfrom_oct()\fR, \fBfrom_bin()\fR, \fBbnan()\fR, \fBbzero()\fR, \fBbinf()\fR, \fBbone()\fR,
+\&\fBlength()\fR, \fBdigit()\fR, \fBbnorm()\fR, \fBbfac()\fR, \fBbround()\fR/\fBround()\fR/\fBbfround()\fR, \fBbmod()\fR,
+\&\fBbmodinv()\fR, \fBbmodpow()\fR, \fBbneg()\fR, \fBis_one()\fR, \fBis_zero()\fR, \fBis_pos()\fR/\fBis_positive()\fR,
+\&\fBis_neg()\fR/\fBis_negative()\fR, \fBis_int()\fR, \fBis_odd()\fR, \fBis_even()\fR, \fBbceil()\fR, \fBbfloor()\fR,
+\&\fBbint()\fR, \fBbsqrt()\fR, \fBbroot()\fR, \fBbadd()\fR, \fBbmul()\fR, \fBbsub()\fR, \fBbdiv()\fR, \fBbinv()\fR, \fBbdec()\fR,
+\&\fBbinc()\fR, \fBcopy()\fR, \fBbstr()\fR/\fBbsstr()\fR, \fBbcmp()\fR, \fBbacmp()\fR, \fBbeq()\fR, \fBbne()\fR, \fBblt()\fR,
+\&\fBble()\fR, \fBbgt()\fR, \fBbge()\fR, \fBblsft()\fR/\fBbrsft()\fR, \fBband()\fR, \fBbior()\fR, \fBbxor()\fR, \fBbnot()\fR,
+\&\fBbpow()\fR, \fBblog()\fR, \fBbexp()\fR, \fBbnok()\fR, \fBconfig()\fR
+.IP "NUMERIC LITERALS" 4
+.IX Item "NUMERIC LITERALS"
+.RS 4
+.PD 0
+.IP "Hexadecimal, octal, and binary floating point literals" 4
+.IX Item "Hexadecimal, octal, and binary floating point literals"
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+GitHub, RT: CPAN's request tracker, MetaCPAN, CPAN Testers Matrix, CPAN
+Ratings
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "Math::Complex \- complex numbers and associated mathematical functions"
+.IX Subsection "Math::Complex - complex numbers and associated mathematical functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OPERATIONS 4
+.IX Item "OPERATIONS"
+.IP CREATION 4
+.IX Item "CREATION"
+.IP DISPLAYING 4
+.IX Item "DISPLAYING"
+.RS 4
+.IP "CHANGED IN PERL 5.6" 4
+.IX Item "CHANGED IN PERL 5.6"
+.RE
+.RS 4
+.RE
+.IP USAGE 4
+.IX Item "USAGE"
+.IP CONSTANTS 4
+.IX Item "CONSTANTS"
+.RS 4
+.IP PI 4
+.IX Item "PI"
+.IP Inf 4
+.IX Item "Inf"
+.RE
+.RS 4
+.RE
+.IP "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO" 4
+.IX Item "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO"
+.IP "ERRORS DUE TO INDIGESTIBLE ARGUMENTS" 4
+.IX Item "ERRORS DUE TO INDIGESTIBLE ARGUMENTS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Math::Trig \- trigonometric functions"
+.IX Subsection "Math::Trig - trigonometric functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "TRIGONOMETRIC FUNCTIONS" 4
+.IX Item "TRIGONOMETRIC FUNCTIONS"
+.PD
+\&\fBtan\fR
+.RS 4
+.IP "ERRORS DUE TO DIVISION BY ZERO" 4
+.IX Item "ERRORS DUE TO DIVISION BY ZERO"
+.PD 0
+.IP "SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS" 4
+.IX Item "SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS"
+.RE
+.RS 4
+.RE
+.IP "PLANE ANGLE CONVERSIONS" 4
+.IX Item "PLANE ANGLE CONVERSIONS"
+.PD
+deg2rad, grad2rad, rad2deg, grad2deg, deg2grad, rad2grad, rad2rad, deg2deg,
+grad2grad
+.IP "RADIAL COORDINATE CONVERSIONS" 4
+.IX Item "RADIAL COORDINATE CONVERSIONS"
+.RS 4
+.PD 0
+.IP "COORDINATE SYSTEMS" 4
+.IX Item "COORDINATE SYSTEMS"
+.IP "3\-D ANGLE CONVERSIONS" 4
+.IX Item "3-D ANGLE CONVERSIONS"
+.PD
+cartesian_to_cylindrical, cartesian_to_spherical, cylindrical_to_cartesian,
+cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical
+.RE
+.RS 4
+.RE
+.IP "GREAT CIRCLE DISTANCES AND DIRECTIONS" 4
+.IX Item "GREAT CIRCLE DISTANCES AND DIRECTIONS"
+.RS 4
+.PD 0
+.IP great_circle_distance 4
+.IX Item "great_circle_distance"
+.IP great_circle_direction 4
+.IX Item "great_circle_direction"
+.IP great_circle_bearing 4
+.IX Item "great_circle_bearing"
+.IP great_circle_destination 4
+.IX Item "great_circle_destination"
+.IP great_circle_midpoint 4
+.IX Item "great_circle_midpoint"
+.IP great_circle_waypoint 4
+.IX Item "great_circle_waypoint"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "CAVEAT FOR GREAT CIRCLE FORMULAS" 4
+.IX Item "CAVEAT FOR GREAT CIRCLE FORMULAS"
+.IP "Real-valued asin and acos" 4
+.IX Item "Real-valued asin and acos"
+.PD
+asin_real, acos_real
+.RE
+.RS 4
+.RE
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Memoize \- Make functions faster by trading space for time"
+.IX Subsection "Memoize - Make functions faster by trading space for time"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.IP DETAILS 4
+.IX Item "DETAILS"
+.IP OPTIONS 4
+.IX Item "OPTIONS"
+.RS 4
+.IP INSTALL 4
+.IX Item "INSTALL"
+.IP NORMALIZER 4
+.IX Item "NORMALIZER"
+.ie n .IP """SCALAR_CACHE"", ""LIST_CACHE""" 4
+.el .IP "\f(CWSCALAR_CACHE\fR, \f(CWLIST_CACHE\fR" 4
+.IX Item "SCALAR_CACHE, LIST_CACHE"
+.PD
+\&\f(CW\*(C`MEMORY\*(C'\fR, \f(CW\*(C`HASH\*(C'\fR, \f(CW\*(C`TIE\*(C'\fR, \f(CW\*(C`FAULT\*(C'\fR, \f(CW\*(C`MERGE\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "OTHER FACILITIES" 4
+.IX Item "OTHER FACILITIES"
+.RS 4
+.PD 0
+.ie n .IP """unmemoize""" 4
+.el .IP \f(CWunmemoize\fR 4
+.IX Item "unmemoize"
+.ie n .IP """flush_cache""" 4
+.el .IP \f(CWflush_cache\fR 4
+.IX Item "flush_cache"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "PERSISTENT CACHE SUPPORT" 4
+.IX Item "PERSISTENT CACHE SUPPORT"
+.IP "EXPIRATION SUPPORT" 4
+.IX Item "EXPIRATION SUPPORT"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "THANK YOU" 4
+.IX Item "THANK YOU"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Memoize::AnyDBM_File \- glue to provide EXISTS for AnyDBM_File for Storable use"
+.IX Subsection "Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for Storable use"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "Memoize::Expire \- Plug-in module for automatic expiration of memoized values"
+.IX Subsection "Memoize::Expire - Plug-in module for automatic expiration of memoized values"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP INTERFACE 4
+.IX Item "INTERFACE"
+.PD
+.Vb 1
+\& TIEHASH,  EXISTS,  STORE
+.Ve
+.IP ALTERNATIVES 4
+.IX Item "ALTERNATIVES"
+.PD 0
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Memoize::NDBM_File \- glue to provide EXISTS for NDBM_File for Storable use"
+.IX Subsection "Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for Storable use"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "Memoize::SDBM_File \- DEPRECATED compability shim"
+.IX Subsection "Memoize::SDBM_File - DEPRECATED compability shim"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Memoize::Storable \- store Memoized data in Storable database"
+.IX Subsection "Memoize::Storable - store Memoized data in Storable database"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.SS "Module::CoreList \- what modules shipped with versions of perl"
+.IX Subsection "Module::CoreList - what modules shipped with versions of perl"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FUNCTIONS API" 4
+.IX Item "FUNCTIONS API"
+.PD
+\&\f(CWfirst_release( MODULE )\fR, \f(CWfirst_release_by_date( MODULE )\fR,
+\&\f(CW\*(C`find_modules( REGEX, [ LIST OF PERLS ] )\*(C'\fR, \f(CWfind_version( PERL_VERSION
+)\fR, \f(CW\*(C`is_core( MODULE, [ MODULE_VERSION, [ PERL_VERSION ] ] )\*(C'\fR,
+\&\f(CW\*(C`is_deprecated( MODULE, PERL_VERSION )\*(C'\fR, \f(CWdeprecated_in( MODULE )\fR,
+\&\f(CWremoved_from( MODULE )\fR, \f(CWremoved_from_by_date( MODULE )\fR,
+\&\f(CW\*(C`changes_between( PERL_VERSION, PERL_VERSION )\*(C'\fR
+.IP "DATA STRUCTURES" 4
+.IX Item "DATA STRUCTURES"
+\&\f(CW%Module::CoreList::version\fR, \f(CW%Module::CoreList::delta\fR,
+\&\f(CW%Module::CoreList::released\fR, \f(CW%Module::CoreList::families\fR,
+\&\f(CW%Module::CoreList::deprecated\fR, \f(CW%Module::CoreList::upstream\fR,
+\&\f(CW%Module::CoreList::bug_tracker\fR
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Module::CoreList::Utils \- what utilities shipped with versions of perl"
+.IX Subsection "Module::CoreList::Utils - what utilities shipped with versions of perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FUNCTIONS API" 4
+.IX Item "FUNCTIONS API"
+.PD
+\&\f(CW\*(C`utilities\*(C'\fR, \f(CWfirst_release( UTILITY )\fR, \f(CWfirst_release_by_date( UTILITY
+)\fR, \f(CWremoved_from( UTILITY )\fR, \f(CWremoved_from_by_date( UTILITY )\fR
+.IP "DATA STRUCTURES" 4
+.IX Item "DATA STRUCTURES"
+\&\f(CW%Module::CoreList::Utils::utilities\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Module::Load \- runtime require of both modules and files"
+.IX Subsection "Module::Load - runtime require of both modules and files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "Difference between ""load"" and ""autoload""" 4
+.el .IP "Difference between \f(CWload\fR and \f(CWautoload\fR" 4
+.IX Item "Difference between load and autoload"
+.RE
+.RS 4
+.RE
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+load, autoload, load_remote, autoload_remote
+.IP Rules 4
+.IX Item "Rules"
+.PD 0
+.IP "IMPORTS THE FUNCTIONS" 4
+.IX Item "IMPORTS THE FUNCTIONS"
+.PD
+"load","autoload","load_remote","autoload_remote", 'all', '','none',undef
+.IP Caveats 4
+.IX Item "Caveats"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Module::Load::Conditional \- Looking up module information / loading at runtime"
+.IX Subsection "Module::Load::Conditional - Looking up module information / loading at runtime"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Methods 4
+.IX Item "Methods"
+.RS 4
+.ie n .IP "$href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );" 4
+.el .IP "\f(CW$href\fR = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );" 4
+.IX Item "$href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );"
+.PD
+module, version, verbose, file, dir, version, uptodate
+.RE
+.RS 4
+.RE
+.ie n .IP "$bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )" 4
+.el .IP "\f(CW$bool\fR = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )" 4
+.IX Item "$bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )"
+modules, verbose, nocache, autoload
+.ie n .IP "@list = requires( MODULE );" 4
+.el .IP "\f(CW@list\fR = requires( MODULE );" 4
+.IX Item "@list = requires( MODULE );"
+.PD 0
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.RS 4
+.ie n .IP $Module::Load::Conditional::VERBOSE 4
+.el .IP \f(CW$Module::Load::Conditional::VERBOSE\fR 4
+.IX Item "$Module::Load::Conditional::VERBOSE"
+.ie n .IP $Module::Load::Conditional::FIND_VERSION 4
+.el .IP \f(CW$Module::Load::Conditional::FIND_VERSION\fR 4
+.IX Item "$Module::Load::Conditional::FIND_VERSION"
+.ie n .IP $Module::Load::Conditional::CHECK_INC_HASH 4
+.el .IP \f(CW$Module::Load::Conditional::CHECK_INC_HASH\fR 4
+.IX Item "$Module::Load::Conditional::CHECK_INC_HASH"
+.ie n .IP $Module::Load::Conditional::FORCE_SAFE_INC 4
+.el .IP \f(CW$Module::Load::Conditional::FORCE_SAFE_INC\fR 4
+.IX Item "$Module::Load::Conditional::FORCE_SAFE_INC"
+.ie n .IP $Module::Load::Conditional::CACHE 4
+.el .IP \f(CW$Module::Load::Conditional::CACHE\fR 4
+.IX Item "$Module::Load::Conditional::CACHE"
+.ie n .IP $Module::Load::Conditional::ERROR 4
+.el .IP \f(CW$Module::Load::Conditional::ERROR\fR 4
+.IX Item "$Module::Load::Conditional::ERROR"
+.ie n .IP $Module::Load::Conditional::DEPRECATED 4
+.el .IP \f(CW$Module::Load::Conditional::DEPRECATED\fR 4
+.IX Item "$Module::Load::Conditional::DEPRECATED"
+.RE
+.RS 4
+.RE
+.IP "See Also" 4
+.IX Item "See Also"
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Module::Loaded \- mark modules as loaded or unloaded"
+.IX Subsection "Module::Loaded - mark modules as loaded or unloaded"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.ie n .IP "$bool = mark_as_loaded( PACKAGE );" 4
+.el .IP "\f(CW$bool\fR = mark_as_loaded( PACKAGE );" 4
+.IX Item "$bool = mark_as_loaded( PACKAGE );"
+.RE
+.RS 4
+.RE
+.ie n .IP "$bool = mark_as_unloaded( PACKAGE );" 4
+.el .IP "\f(CW$bool\fR = mark_as_unloaded( PACKAGE );" 4
+.IX Item "$bool = mark_as_unloaded( PACKAGE );"
+.ie n .IP "$loc = is_loaded( PACKAGE );" 4
+.el .IP "\f(CW$loc\fR = is_loaded( PACKAGE );" 4
+.IX Item "$loc = is_loaded( PACKAGE );"
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Module::Metadata \- Gather package and POD information from perl module files"
+.IX Subsection "Module::Metadata - Gather package and POD information from perl module files"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CLASS METHODS" 4
+.IX Item "CLASS METHODS"
+.RS 4
+.ie n .IP """new_from_file($filename, collect_pod => 1, decode_pod => 1)""" 4
+.el .IP "\f(CWnew_from_file($filename, collect_pod => 1, decode_pod => 1)\fR" 4
+.IX Item "new_from_file($filename, collect_pod => 1, decode_pod => 1)"
+.ie n .IP """new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)""" 4
+.el .IP "\f(CWnew_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)\fR" 4
+.IX Item "new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)"
+.ie n .IP """new_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)""" 4
+.el .IP "\f(CWnew_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)\fR" 4
+.IX Item "new_from_module($module, collect_pod => 1, inc => @dirs, decode_pod => 1)"
+.ie n .IP """find_module_by_name($module, \e@dirs)""" 4
+.el .IP "\f(CWfind_module_by_name($module, \e@dirs)\fR" 4
+.IX Item "find_module_by_name($module, @dirs)"
+.ie n .IP """find_module_dir_by_name($module, \e@dirs)""" 4
+.el .IP "\f(CWfind_module_dir_by_name($module, \e@dirs)\fR" 4
+.IX Item "find_module_dir_by_name($module, @dirs)"
+.ie n .IP "provides( %options )" 4
+.el .IP "\f(CWprovides( %options )\fR" 4
+.IX Item "provides( %options )"
+.PD
+version \fB(required)\fR, dir, files, prefix
+.ie n .IP """package_versions_from_directory($dir, \e@files?)""" 4
+.el .IP "\f(CWpackage_versions_from_directory($dir, \e@files?)\fR" 4
+.IX Item "package_versions_from_directory($dir, @files?)"
+.PD 0
+.ie n .IP """log_info (internal)""" 4
+.el .IP "\f(CWlog_info (internal)\fR" 4
+.IX Item "log_info (internal)"
+.RE
+.RS 4
+.RE
+.IP "OBJECT METHODS" 4
+.IX Item "OBJECT METHODS"
+.RS 4
+.ie n .IP name() 4
+.el .IP \f(CWname()\fR 4
+.IX Item "name()"
+.ie n .IP version($package) 4
+.el .IP \f(CWversion($package)\fR 4
+.IX Item "version($package)"
+.ie n .IP filename() 4
+.el .IP \f(CWfilename()\fR 4
+.IX Item "filename()"
+.ie n .IP packages_inside() 4
+.el .IP \f(CWpackages_inside()\fR 4
+.IX Item "packages_inside()"
+.ie n .IP pod_inside() 4
+.el .IP \f(CWpod_inside()\fR 4
+.IX Item "pod_inside()"
+.ie n .IP contains_pod() 4
+.el .IP \f(CWcontains_pod()\fR 4
+.IX Item "contains_pod()"
+.ie n .IP pod($section) 4
+.el .IP \f(CWpod($section)\fR 4
+.IX Item "pod($section)"
+.ie n .IP "is_indexable($package) or is_indexable()" 4
+.el .IP "\f(CWis_indexable($package)\fR or \f(CWis_indexable()\fR" 4
+.IX Item "is_indexable($package) or is_indexable()"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "NDBM_File \- Tied access to ndbm files"
+.IX Subsection "NDBM_File - Tied access to ndbm files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`O_RDONLY\*(C'\fR, \f(CW\*(C`O_WRONLY\*(C'\fR, \f(CW\*(C`O_RDWR\*(C'\fR
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.RS 4
+.PD 0
+.ie n .IP """ndbm store returned \-1, errno 22, key ""..."" at ...""" 4
+.el .IP "\f(CWndbm store returned \-1, errno 22, key ""..."" at ...\fR" 4
+.IX Item "ndbm store returned -1, errno 22, key ""..."" at ..."
+.RE
+.RS 4
+.RE
+.IP "SECURITY AND PORTABILITY" 4
+.IX Item "SECURITY AND PORTABILITY"
+.IP "BUGS AND WARNINGS" 4
+.IX Item "BUGS AND WARNINGS"
+.PD
+.SS "NEXT \- Provide a pseudo-class NEXT (et al) that allows method redispatch"
+.IX Subsection "NEXT - Provide a pseudo-class NEXT (et al) that allows method redispatch"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Enforcing redispatch" 4
+.IX Item "Enforcing redispatch"
+.IP "Avoiding repetitions" 4
+.IX Item "Avoiding repetitions"
+.IP "Invoking all versions of a method with a single call" 4
+.IX Item "Invoking all versions of a method with a single call"
+.ie n .IP "Using ""EVERY"" methods" 4
+.el .IP "Using \f(CWEVERY\fR methods" 4
+.IX Item "Using EVERY methods"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "BUGS AND IRRITATIONS" 4
+.IX Item "BUGS AND IRRITATIONS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Net::Cmd \- Network Command class (as used by FTP, SMTP etc)"
+.IX Subsection "Net::Cmd - Network Command class (as used by FTP, SMTP etc)"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Public Methods" 4
+.IX Item "Public Methods"
+.PD
+\&\f(CWdebug($level)\fR, \f(CWmessage()\fR, \f(CWcode()\fR, \f(CWok()\fR, \f(CWstatus()\fR,
+\&\f(CWdatasend($data)\fR, \f(CWdataend()\fR
+.IP "Protected Methods" 4
+.IX Item "Protected Methods"
+\&\f(CW\*(C`debug_print($dir, $text)\*(C'\fR, \f(CW\*(C`debug_text($dir, $text)\*(C'\fR, \f(CW\*(C`command($cmd[,
+$args, ... ])\*(C'\fR, \f(CWunsupported()\fR, \f(CWresponse()\fR, \f(CWparse_response($text)\fR,
+\&\f(CWgetline()\fR, \f(CWungetline($text)\fR, \f(CWrawdatasend($data)\fR,
+\&\f(CWread_until_dot()\fR, \f(CWtied_fh()\fR
+.IP "Pseudo Responses" 4
+.IX Item "Pseudo Responses"
+Initial value, Connection closed, Timeout
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+Default Exports, Optional Exports, Export Tags
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::Config \- Local configuration data for libnet"
+.IX Subsection "Net::Config - Local configuration data for libnet"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CWrequires_firewall($host)\fR
+.IP "NetConfig Values" 4
+.IX Item "NetConfig Values"
+nntp_hosts, snpp_hosts, pop3_hosts, smtp_hosts, ph_hosts, daytime_hosts,
+time_hosts, inet_domain, ftp_firewall, ftp_firewall_type, 0, 1, 2,
+3, 4, 5, 6, 7, ftp_ext_passive, ftp_int_passive,
+local_netmask, test_hosts, test_exists
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+Default Exports, Optional Exports, Export Tags
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::Domain \- Attempt to evaluate the current host's internet name and domain"
+.IX Subsection "Net::Domain - Attempt to evaluate the current host's internet name and domain"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Functions 4
+.IX Item "Functions"
+.PD
+\&\f(CWhostfqdn()\fR, \f(CWdomainname()\fR, \f(CWhostname()\fR, \f(CWhostdomain()\fR
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+Default Exports, Optional Exports, Export Tags
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::FTP \- FTP Client class"
+.IX Subsection "Net::FTP - FTP Client class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Overview 4
+.IX Item "Overview"
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`new([$host][, %options])\*(C'\fR
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\f(CW\*(C`login([$login[, $password[, $account]]])\*(C'\fR, \f(CWstarttls()\fR, \f(CWstoptls()\fR,
+\&\f(CWprot($level)\fR, \f(CWhost()\fR, \f(CWaccount($acct)\fR, \f(CW\*(C`authorize([$auth[,
+$resp]])\*(C'\fR, \f(CWsite($args)\fR, \f(CWascii()\fR, \f(CWbinary()\fR, \f(CWtype([$type])\fR,
+\&\f(CW\*(C`rename($oldname, $newname)\*(C'\fR, \f(CWdelete($filename)\fR, \f(CWcwd([$dir])\fR,
+\&\f(CWcdup()\fR, \f(CWpassive([$passive])\fR, \f(CWpwd()\fR, \f(CWrestart($where)\fR,
+\&\f(CW\*(C`rmdir($dir[, $recurse])\*(C'\fR, \f(CW\*(C`mkdir($dir[, $recurse])\*(C'\fR, \f(CW\*(C`alloc($size[,
+$record_size])\*(C'\fR, \f(CWls([$dir])\fR, \f(CWdir([$dir])\fR, \f(CW\*(C`get($remote_file[,
+$local_file[, $where]])\*(C'\fR, \f(CW\*(C`put($local_file[, $remote_file])\*(C'\fR,
+\&\f(CW\*(C`put_unique($local_file[, $remote_file])\*(C'\fR, \f(CW\*(C`append($local_file[,
+$remote_file])\*(C'\fR, \f(CWunique_name()\fR, \f(CWmdtm($file)\fR, \f(CWsize($file)\fR,
+\&\f(CWsupported($cmd)\fR, \f(CW\*(C`hash([$filehandle_glob_ref[,
+$bytes_per_hash_mark]])\*(C'\fR, \f(CWfeature($name)\fR, \f(CWnlst([$dir])\fR,
+\&\f(CWlist([$dir])\fR, \f(CWretr($file)\fR, \f(CWstor($file)\fR, \f(CWstou($file)\fR,
+\&\f(CWappe($file)\fR, \f(CWport([$port])\fR, \f(CWeprt([$port])\fR, \f(CWpasv()\fR, \f(CWepsv()\fR,
+\&\f(CW\*(C`pasv_xfer($src_file, $dest_server[, $dest_file ])\*(C'\fR,
+\&\f(CW\*(C`pasv_xfer_unique($src_file, $dest_server[, $dest_file ])\*(C'\fR,
+\&\f(CWpasv_wait($non_pasv_server)\fR, \f(CWabort()\fR, \f(CWquit()\fR
+.IP "Methods for the Adventurous" 4
+.IX Item "Methods for the Adventurous"
+\&\f(CW\*(C`quot($cmd[, $args])\*(C'\fR, \f(CWcan_inet6()\fR, \f(CWcan_ssl()\fR
+.IP "The dataconn Class" 4
+.IX Item "The dataconn Class"
+.PD 0
+.IP Unimplemented 4
+.IX Item "Unimplemented"
+.PD
+\&\f(CW\*(C`SMNT\*(C'\fR, \f(CW\*(C`HELP\*(C'\fR, \f(CW\*(C`MODE\*(C'\fR, \f(CW\*(C`SYST\*(C'\fR, \f(CW\*(C`STAT\*(C'\fR, \f(CW\*(C`STRU\*(C'\fR, \f(CW\*(C`REIN\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD 0
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.RS 4
+.IP "Reporting Bugs" 4
+.IX Item "Reporting Bugs"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::NNTP \- NNTP Client class"
+.IX Subsection "Net::NNTP - NNTP Client class"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`new([$host][, %options])\*(C'\fR
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\f(CWhost()\fR, \f(CWstarttls()\fR, \f(CW\*(C`article([{$msgid|$msgnum}[, $fh]])\*(C'\fR,
+\&\f(CW\*(C`body([{$msgid|$msgnum}[, [$fh]])\*(C'\fR, \f(CW\*(C`head([{$msgid|$msgnum}[, [$fh]])\*(C'\fR,
+\&\f(CWarticlefh([{$msgid|$msgnum}])\fR, \f(CWbodyfh([{$msgid|$msgnum}])\fR,
+\&\f(CWheadfh([{$msgid|$msgnum}])\fR, \f(CWnntpstat([{$msgid|$msgnum}])\fR,
+\&\f(CWgroup([$group])\fR, \f(CWhelp()\fR, \f(CW\*(C`ihave($msgid[, $message])\*(C'\fR, \f(CWlast()\fR,
+\&\f(CWdate()\fR, \f(CWpostok()\fR, \f(CW\*(C`authinfo($user, $pass)\*(C'\fR, \f(CW\*(C`authinfo_simple($user,
+$pass)\*(C'\fR, \f(CWlist()\fR, \f(CW\*(C`newgroups($since[, $distributions])\*(C'\fR,
+\&\f(CW\*(C`newnews($since[, $groups[, $distributions]])\*(C'\fR, \f(CWnext()\fR,
+\&\f(CWpost([$message])\fR, \f(CWpostfh()\fR, \f(CWslave()\fR, \f(CWquit()\fR, \f(CWcan_inet6()\fR,
+\&\f(CWcan_ssl()\fR
+.IP "Extension Methods" 4
+.IX Item "Extension Methods"
+\&\f(CWnewsgroups([$pattern])\fR, \f(CWdistributions()\fR, \f(CWdistribution_patterns()\fR,
+\&\f(CWsubscriptions()\fR, \f(CWoverview_fmt()\fR, \f(CWactive_times()\fR,
+\&\f(CWactive([$pattern])\fR, \f(CWxgtitle($pattern)\fR, \f(CW\*(C`xhdr($header,
+$message_spec)\*(C'\fR, \f(CWxover($message_spec)\fR, \f(CWxpath($message_id)\fR,
+\&\f(CW\*(C`xpat($header, $pattern, $message_spec)\*(C'\fR, \f(CWxrover($message_spec)\fR,
+\&\f(CWlistgroup([$group])\fR, \f(CWreader()\fR
+.IP Unsupported 4
+.IX Item "Unsupported"
+.PD 0
+.IP Definitions 4
+.IX Item "Definitions"
+.PD
+\&\f(CW$message_spec\fR, \f(CW$pattern\fR, Examples, \f(CW\*(C`[^]\-]\*(C'\fR, \f(CW*bdc\fR, \f(CW\*(C`[0\-9a\-zA\-Z]\*(C'\fR,
+\&\f(CW\*(C`a??d\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD 0
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::Netrc \- OO interface to users netrc file"
+.IX Subsection "Net::Netrc - OO interface to users netrc file"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "The \fI.netrc\fR File" 4
+.IX Item "The .netrc File"
+.PD
+machine name, default, login name, password string, account string, macdef
+name
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+\&\f(CW\*(C`lookup($machine[, $login])\*(C'\fR
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\f(CWlogin()\fR, \f(CWpassword()\fR, \f(CWaccount()\fR, \f(CWlpa()\fR
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD 0
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::POP3 \- Post Office Protocol 3 Client class (RFC1939)"
+.IX Subsection "Net::POP3 - Post Office Protocol 3 Client class (RFC1939)"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`new([$host][, %options])\*(C'\fR
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\f(CWhost()\fR, \f(CW\*(C`auth($username, $password)\*(C'\fR, \f(CWuser($user)\fR, \f(CWpass($pass)\fR,
+\&\f(CW\*(C`login([$user[, $pass]])\*(C'\fR, \f(CWstarttls(%sslargs)\fR, \f(CW\*(C`apop([$user[,
+$pass]])\*(C'\fR, \f(CWbanner()\fR, \f(CWcapa()\fR, \f(CWcapabilities()\fR, \f(CW\*(C`top($msgnum[,
+$numlines])\*(C'\fR, \f(CWlist([$msgnum])\fR, \f(CW\*(C`get($msgnum[, $fh])\*(C'\fR,
+\&\f(CWgetfh($msgnum)\fR, \f(CWlast()\fR, \f(CWpopstat()\fR, \f(CWping($user)\fR,
+\&\f(CWuidl([$msgnum])\fR, \f(CWdelete($msgnum)\fR, \f(CWreset()\fR, \f(CWquit()\fR,
+\&\f(CWcan_inet6()\fR, \f(CWcan_ssl()\fR
+.IP Notes 4
+.IX Item "Notes"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::Ping \- check a remote host for reachability"
+.IX Subsection "Net::Ping - check a remote host for reachability"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Functions 4
+.IX Item "Functions"
+.PD
+Net::Ping\->new([proto, timeout, bytes, device, tos, ttl, family,	   
+	   host, port, bind, gateway, retrans, pingstring,		   
+     source_verify econnrefused dontfrag		      
+IPV6_USE_MIN_MTU IPV6_RECVPATHMTU]) , \f(CW$p\fR\->ping($host [, \f(CW$timeout\fR [,
+\&\f(CW$family\fR]]); , \f(CW$p\fR\->source_verify( { 0 | 1 } ); ,
+\&\f(CW$p\fR\->service_check( { 0 | 1 } ); , \f(CW$p\fR\->tcp_service_check( {
+0 | 1 } ); , \f(CW$p\fR\->hires( { 0 | 1 } ); , \f(CW$p\fR\->time
+, \f(CW$p\fR\->socket_blocking_mode( \f(CW$fh\fR, \f(CW$mode\fR ); ,
+\&\f(CW$p\fR\->IPV6_USE_MIN_MTU , \f(CW$p\fR\->IPV6_RECVPATHMTU
+, \f(CW$p\fR\->IPV6_HOPLIMIT , \f(CW$p\fR\->IPV6_REACHCONF
+\&\fINYI\fR , \f(CW$p\fR\->bind($local_addr); ,
+\&\f(CW$p\fR\->message_type([$ping_type]); , \f(CW$p\fR\->open($host); ,
+\&\f(CW$p\fR\->ack( [ \f(CW$host\fR ] ); , \f(CW$p\fR\->nack( \f(CW$failed_ack_host\fR ); ,
+\&\f(CW$p\fR\->ack_unfork($host) , \f(CW$p\fR\->ping_icmp([$host, \f(CW$timeout\fR,
+\&\f(CW$family\fR]) , \f(CW$p\fR\->ping_icmpv6([$host, \f(CW$timeout\fR, \f(CW$family\fR])
+, \f(CW$p\fR\->ping_stream([$host, \f(CW$timeout\fR, \f(CW$family\fR]) ,
+\&\f(CW$p\fR\->ping_syn([$host, \f(CW$ip\fR, \f(CW$start_time\fR, \f(CW$stop_time\fR]) ,
+\&\f(CW$p\fR\->ping_syn_fork([$host, \f(CW$timeout\fR, \f(CW$family\fR]) ,
+\&\f(CW$p\fR\->ping_tcp([$host, \f(CW$timeout\fR, \f(CW$family\fR]) , \f(CW$p\fR\->ping_udp([$host,
+\&\f(CW$timeout\fR, \f(CW$family\fR]) , \f(CW$p\fR\->ping_external([$host, \f(CW$timeout\fR,
+\&\f(CW$family\fR]) , \f(CW$p\fR\->tcp_connect([$ip, \f(CW$timeout\fR])
+, \f(CW$p\fR\->tcp_echo([$ip, \f(CW$timeout\fR, \f(CW$pingstring\fR]) ,
+\&\f(CW$p\fR\->\fBclose()\fR; , \f(CW$p\fR\->port_number([$port_number]) ,
+\&\f(CW$p\fR\->mselect , \f(CW$p\fR\->ntop , \f(CW$p\fR\->checksum($msg) ,
+\&\f(CW$p\fR\->icmp_result , pingecho($host [, \f(CW$timeout\fR]); ,
+wakeonlan($mac, [$host, [$port]])
+.IX Xref "new ping source_verify service_check tcp_service_check hires time socket_blocking_mode IPV6_USE_MIN_MTU IPV6_RECVPATHMTU IPV6_HOPLIMIT IPV6_REACHCONF bind message_type open ack nack ack_unfork ping_icmp ping_icmpv6 ping_stream ping_syn ping_syn_fork ping_tcp ping_udp ping_external tcp_connect tcp_echo close port_number mselect ntop checksum icmp_result pingecho wakeonlan"
+.RE
+.RS 4
+.RE
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP INSTALL 4
+.IX Item "INSTALL"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Net::SMTP \- Simple Mail Transfer Protocol Client"
+.IX Subsection "Net::SMTP - Simple Mail Transfer Protocol Client"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`new([$host][, %options])\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Object Methods" 4
+.IX Item "Object Methods"
+\&\f(CWbanner()\fR, \f(CWdomain()\fR, \f(CWhello($domain)\fR, \f(CWhost()\fR, \f(CWetrn($domain)\fR,
+\&\f(CWstarttls(%sslargs)\fR, \f(CW\*(C`auth($username, $password)\*(C'\fR, \f(CWauth($sasl)\fR,
+\&\f(CW\*(C`mail($address[, %options])\*(C'\fR, \f(CWsend($address)\fR,
+\&\f(CWsend_or_mail($address)\fR, \f(CWsend_and_mail($address)\fR, \f(CWreset()\fR,
+\&\f(CW\*(C`recipient($address[, $address[, ...]][, %options])\*(C'\fR, \f(CW\*(C`to($address[,
+$address[, ...]])\*(C'\fR, \f(CW\*(C`cc($address[, $address[, ...]])\*(C'\fR, \f(CW\*(C`bcc($address[,
+$address[, ...]])\*(C'\fR, \f(CWdata([$data])\fR, \f(CWbdat($data)\fR, \f(CWbdatlast($data)\fR,
+\&\f(CWexpand($address)\fR, \f(CWverify($address)\fR, \f(CWhelp([$subject])\fR, \f(CWquit()\fR,
+\&\f(CWcan_inet6()\fR, \f(CWcan_ssl()\fR
+.RS 4
+.IP Addresses 4
+.IX Item "Addresses"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::Time \- time and daytime network client interface"
+.IX Subsection "Net::Time - time and daytime network client interface"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Functions 4
+.IX Item "Functions"
+.PD
+\&\f(CW\*(C`inet_time([$host[, $protocol[, $timeout]]])\*(C'\fR, \f(CW\*(C`inet_daytime([$host[,
+$protocol[, $timeout]]])\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+Default Exports, Optional Exports, Export Tags
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Net::hostent \- by-name interface to Perl's built-in gethost*() functions"
+.IX Subsection "Net::hostent - by-name interface to Perl's built-in gethost*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Net::libnetFAQ, libnetFAQ \- libnet Frequently Asked Questions"
+.IX Subsection "Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Where to get this document" 4
+.IX Item "Where to get this document"
+.IP "How to contribute to this document" 4
+.IX Item "How to contribute to this document"
+.RE
+.RS 4
+.RE
+.IP "Author and Copyright Information" 4
+.IX Item "Author and Copyright Information"
+.RS 4
+.IP Disclaimer 4
+.IX Item "Disclaimer"
+.RE
+.RS 4
+.RE
+.IP "Obtaining and installing libnet" 4
+.IX Item "Obtaining and installing libnet"
+.RS 4
+.IP "What is libnet ?" 4
+.IX Item "What is libnet ?"
+.IP "Which version of perl do I need ?" 4
+.IX Item "Which version of perl do I need ?"
+.IP "What other modules do I need ?" 4
+.IX Item "What other modules do I need ?"
+.IP "What machines support libnet ?" 4
+.IX Item "What machines support libnet ?"
+.IP "Where can I get the latest libnet release" 4
+.IX Item "Where can I get the latest libnet release"
+.RE
+.RS 4
+.RE
+.IP "Using Net::FTP" 4
+.IX Item "Using Net::FTP"
+.RS 4
+.IP "How do I download files from an FTP server ?" 4
+.IX Item "How do I download files from an FTP server ?"
+.IP "How do I transfer files in binary mode ?" 4
+.IX Item "How do I transfer files in binary mode ?"
+.IP "How can I get the size of a file on a remote FTP server ?" 4
+.IX Item "How can I get the size of a file on a remote FTP server ?"
+.IP "How can I get the modification time of a file on a remote FTP server ?" 4
+.IX Item "How can I get the modification time of a file on a remote FTP server ?"
+.IP "How can I change the permissions of a file on a remote server ?" 4
+.IX Item "How can I change the permissions of a file on a remote server ?"
+.IP "Can I do a reget operation like the ftp command ?" 4
+.IX Item "Can I do a reget operation like the ftp command ?"
+.IP "How do I get a directory listing from an FTP server ?" 4
+.IX Item "How do I get a directory listing from an FTP server ?"
+.IP "Changing directory to """" does not fail ?" 4
+.IX Item "Changing directory to """" does not fail ?"
+.IP "I am behind a SOCKS firewall, but the Firewall option does not work ?" 4
+.IX Item "I am behind a SOCKS firewall, but the Firewall option does not work ?"
+.IP "I am behind an FTP proxy firewall, but cannot access machines outside ?" 4
+.IX Item "I am behind an FTP proxy firewall, but cannot access machines outside ?"
+.IP "My ftp proxy firewall does not listen on port 21" 4
+.IX Item "My ftp proxy firewall does not listen on port 21"
+.IP "Is it possible to change the file permissions of a file on an FTP server ?" 4
+.IX Item "Is it possible to change the file permissions of a file on an FTP server ?"
+.IP "I have seen scripts call a method message, but cannot find it documented ?" 4
+.IX Item "I have seen scripts call a method message, but cannot find it documented ?"
+.IP "Why does Net::FTP not implement mput and mget methods" 4
+.IX Item "Why does Net::FTP not implement mput and mget methods"
+.RE
+.RS 4
+.RE
+.IP "Using Net::SMTP" 4
+.IX Item "Using Net::SMTP"
+.RS 4
+.IP "Why can't the part of an Email address after the @ be used as the hostname ?" 4
+.IX Item "Why can't the part of an Email address after the @ be used as the hostname ?"
+.IP "Why does Net::SMTP not do DNS MX lookups ?" 4
+.IX Item "Why does Net::SMTP not do DNS MX lookups ?"
+.IP "The verify method always returns true ?" 4
+.IX Item "The verify method always returns true ?"
+.RE
+.RS 4
+.RE
+.IP "Debugging scripts" 4
+.IX Item "Debugging scripts"
+.RS 4
+.IP "How can I debug my scripts that use Net::* modules ?" 4
+.IX Item "How can I debug my scripts that use Net::* modules ?"
+.RE
+.RS 4
+.RE
+.IP "AUTHOR AND COPYRIGHT" 4
+.IX Item "AUTHOR AND COPYRIGHT"
+.PD
+.SS "Net::netent \- by-name interface to Perl's built-in getnet*() functions"
+.IX Subsection "Net::netent - by-name interface to Perl's built-in getnet*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Net::protoent \- by-name interface to Perl's built-in getproto*() functions"
+.IX Subsection "Net::protoent - by-name interface to Perl's built-in getproto*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Net::servent \- by-name interface to Perl's built-in getserv*() functions"
+.IX Subsection "Net::servent - by-name interface to Perl's built-in getserv*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "O \- Generic interface to Perl Compiler backends"
+.IX Subsection "O - Generic interface to Perl Compiler backends"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONVENTIONS 4
+.IX Item "CONVENTIONS"
+.IP IMPLEMENTATION 4
+.IX Item "IMPLEMENTATION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "ODBM_File \- Tied access to odbm files"
+.IX Subsection "ODBM_File - Tied access to odbm files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`O_RDONLY\*(C'\fR, \f(CW\*(C`O_WRONLY\*(C'\fR, \f(CW\*(C`O_RDWR\*(C'\fR
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.RS 4
+.PD 0
+.ie n .IP """odbm store returned \-1, errno 22, key ""..."" at ...""" 4
+.el .IP "\f(CWodbm store returned \-1, errno 22, key ""..."" at ...\fR" 4
+.IX Item "odbm store returned -1, errno 22, key ""..."" at ..."
+.RE
+.RS 4
+.RE
+.IP "SECURITY AND PORTABILITY" 4
+.IX Item "SECURITY AND PORTABILITY"
+.IP "BUGS AND WARNINGS" 4
+.IX Item "BUGS AND WARNINGS"
+.PD
+.SS "Opcode \- Disable named opcodes when compiling perl code"
+.IX Subsection "Opcode - Disable named opcodes when compiling perl code"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP WARNING 4
+.IX Item "WARNING"
+.IP "Operator Names and Operator Lists" 4
+.IX Item "Operator Names and Operator Lists"
+.PD
+an operator name (opname), an operator tag name (optag), a negated opname
+or optag, an operator set (opset)
+.IP "Opcode Functions" 4
+.IX Item "Opcode Functions"
+opcodes, opset (OP, ...), opset_to_ops (OPSET), opset_to_hex (OPSET),
+full_opset, empty_opset, invert_opset (OPSET), verify_opset (OPSET, ...),
+define_optag (OPTAG, OPSET), opmask_add (OPSET), opmask, opdesc (OP, ...),
+opdump (PAT)
+.IP "Manipulating Opsets" 4
+.IX Item "Manipulating Opsets"
+.PD 0
+.IP "TO DO (maybe)" 4
+.IX Item "TO DO (maybe)"
+.IP "Predefined Opcode Tags" 4
+.IX Item "Predefined Opcode Tags"
+.PD
+:base_core, :base_mem, :base_loop, :base_io, :base_orig, :base_math,
+:base_thread, :default, :filesys_read, :sys_db, :browse, :filesys_open,
+:filesys_write, :subprocess, :ownprocess, :others, :load,
+:still_to_be_decided, :dangerous
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD
+.SS "POSIX \- Perl interface to IEEE Std 1003.1"
+.IX Subsection "POSIX - Perl interface to IEEE Std 1003.1"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\f(CW\*(C`_exit\*(C'\fR, \f(CW\*(C`abort\*(C'\fR, \f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`access\*(C'\fR, \f(CW\*(C`acos\*(C'\fR, \f(CW\*(C`acosh\*(C'\fR, \f(CW\*(C`alarm\*(C'\fR,
+\&\f(CW\*(C`asctime\*(C'\fR, \f(CW\*(C`asin\*(C'\fR, \f(CW\*(C`asinh\*(C'\fR, \f(CW\*(C`assert\*(C'\fR, \f(CW\*(C`atan\*(C'\fR, \f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR,
+\&\f(CW\*(C`atexit\*(C'\fR, \f(CW\*(C`atof\*(C'\fR, \f(CW\*(C`atoi\*(C'\fR, \f(CW\*(C`atol\*(C'\fR, \f(CW\*(C`bsearch\*(C'\fR, \f(CW\*(C`calloc\*(C'\fR, \f(CW\*(C`cbrt\*(C'\fR,
+\&\f(CW\*(C`ceil\*(C'\fR, \f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`clearerr\*(C'\fR, \f(CW\*(C`clock\*(C'\fR, \f(CW\*(C`close\*(C'\fR,
+\&\f(CW\*(C`closedir\*(C'\fR, \f(CW\*(C`cos\*(C'\fR, \f(CW\*(C`cosh\*(C'\fR, \f(CW\*(C`copysign\*(C'\fR, \f(CW\*(C`creat\*(C'\fR, \f(CW\*(C`ctermid\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR,
+\&\f(CW\*(C`cuserid\*(C'\fR [POSIX.1\-1988], \f(CW\*(C`difftime\*(C'\fR, \f(CW\*(C`div\*(C'\fR, \f(CW\*(C`dup\*(C'\fR, \f(CW\*(C`dup2\*(C'\fR, \f(CW\*(C`erf\*(C'\fR,
+\&\f(CW\*(C`erfc\*(C'\fR, \f(CW\*(C`errno\*(C'\fR, \f(CW\*(C`execl\*(C'\fR, \f(CW\*(C`execle\*(C'\fR, \f(CW\*(C`execlp\*(C'\fR, \f(CW\*(C`execv\*(C'\fR, \f(CW\*(C`execve\*(C'\fR,
+\&\f(CW\*(C`execvp\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, \f(CW\*(C`exp\*(C'\fR, \f(CW\*(C`expm1\*(C'\fR, \f(CW\*(C`fabs\*(C'\fR, \f(CW\*(C`fclose\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR,
+\&\f(CW\*(C`fdopen\*(C'\fR, \f(CW\*(C`feof\*(C'\fR, \f(CW\*(C`ferror\*(C'\fR, \f(CW\*(C`fflush\*(C'\fR, \f(CW\*(C`fgetc\*(C'\fR, \f(CW\*(C`fgetpos\*(C'\fR, \f(CW\*(C`fgets\*(C'\fR,
+\&\f(CW\*(C`fileno\*(C'\fR, \f(CW\*(C`floor\*(C'\fR, \f(CW\*(C`fdim\*(C'\fR, \f(CW\*(C`fegetround\*(C'\fR, \f(CW\*(C`fesetround\*(C'\fR, \f(CW\*(C`fma\*(C'\fR,
+\&\f(CW\*(C`fmax\*(C'\fR, \f(CW\*(C`fmin\*(C'\fR, \f(CW\*(C`fmod\*(C'\fR, \f(CW\*(C`fopen\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`fpathconf\*(C'\fR, \f(CW\*(C`fpclassify\*(C'\fR,
+\&\f(CW\*(C`fprintf\*(C'\fR, \f(CW\*(C`fputc\*(C'\fR, \f(CW\*(C`fputs\*(C'\fR, \f(CW\*(C`fread\*(C'\fR, \f(CW\*(C`free\*(C'\fR, \f(CW\*(C`freopen\*(C'\fR, \f(CW\*(C`frexp\*(C'\fR,
+\&\f(CW\*(C`fscanf\*(C'\fR, \f(CW\*(C`fseek\*(C'\fR, \f(CW\*(C`fsetpos\*(C'\fR, \f(CW\*(C`fstat\*(C'\fR, \f(CW\*(C`fsync\*(C'\fR, \f(CW\*(C`ftell\*(C'\fR, \f(CW\*(C`fwrite\*(C'\fR,
+\&\f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`getchar\*(C'\fR, \f(CW\*(C`getcwd\*(C'\fR, \f(CW\*(C`getegid\*(C'\fR, \f(CW\*(C`getenv\*(C'\fR, \f(CW\*(C`geteuid\*(C'\fR,
+\&\f(CW\*(C`getgid\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`getgrnam\*(C'\fR, \f(CW\*(C`getgroups\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR,
+\&\f(CW\*(C`getpayload\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getpid\*(C'\fR, \f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, \f(CW\*(C`getpwuid\*(C'\fR,
+\&\f(CW\*(C`gets\*(C'\fR, \f(CW\*(C`getuid\*(C'\fR, \f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`hypot\*(C'\fR, \f(CW\*(C`ilogb\*(C'\fR, \f(CW\*(C`Inf\*(C'\fR, \f(CW\*(C`isalnum\*(C'\fR,
+\&\f(CW\*(C`isalpha\*(C'\fR, \f(CW\*(C`isatty\*(C'\fR, \f(CW\*(C`iscntrl\*(C'\fR, \f(CW\*(C`isdigit\*(C'\fR, \f(CW\*(C`isfinite\*(C'\fR, \f(CW\*(C`isgraph\*(C'\fR,
+\&\f(CW\*(C`isgreater\*(C'\fR, \f(CW\*(C`isinf\*(C'\fR, \f(CW\*(C`islower\*(C'\fR, \f(CW\*(C`isnan\*(C'\fR, \f(CW\*(C`isnormal\*(C'\fR, \f(CW\*(C`isprint\*(C'\fR,
+\&\f(CW\*(C`ispunct\*(C'\fR, \f(CW\*(C`issignaling\*(C'\fR, \f(CW\*(C`isspace\*(C'\fR, \f(CW\*(C`isupper\*(C'\fR, \f(CW\*(C`isxdigit\*(C'\fR, \f(CW\*(C`j0\*(C'\fR,
+\&\f(CW\*(C`j1\*(C'\fR, \f(CW\*(C`jn\*(C'\fR, \f(CW\*(C`y0\*(C'\fR, \f(CW\*(C`y1\*(C'\fR, \f(CW\*(C`yn\*(C'\fR, \f(CW\*(C`kill\*(C'\fR, \f(CW\*(C`labs\*(C'\fR, \f(CW\*(C`lchown\*(C'\fR, \f(CW\*(C`ldexp\*(C'\fR,
+\&\f(CW\*(C`ldiv\*(C'\fR, \f(CW\*(C`lgamma\*(C'\fR, \f(CW\*(C`log1p\*(C'\fR, \f(CW\*(C`log2\*(C'\fR, \f(CW\*(C`logb\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`localeconv\*(C'\fR,
+\&\f(CW\*(C`localtime\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`log10\*(C'\fR, \f(CW\*(C`longjmp\*(C'\fR, \f(CW\*(C`lseek\*(C'\fR, \f(CW\*(C`lrint\*(C'\fR, \f(CW\*(C`lround\*(C'\fR,
+\&\f(CW\*(C`malloc\*(C'\fR, \f(CW\*(C`mblen\*(C'\fR, \f(CW\*(C`mbtowc\*(C'\fR, \f(CW\*(C`memchr\*(C'\fR, \f(CW\*(C`memcmp\*(C'\fR, \f(CW\*(C`memcpy\*(C'\fR,
+\&\f(CW\*(C`memmove\*(C'\fR, \f(CW\*(C`memset\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`mkfifo\*(C'\fR, \f(CW\*(C`mktime\*(C'\fR, \f(CW\*(C`modf\*(C'\fR, \f(CW\*(C`NaN\*(C'\fR,
+\&\f(CW\*(C`nan\*(C'\fR, \f(CW\*(C`nearbyint\*(C'\fR, \f(CW\*(C`nextafter\*(C'\fR, \f(CW\*(C`nexttoward\*(C'\fR, \f(CW\*(C`nice\*(C'\fR, \f(CW\*(C`offsetof\*(C'\fR,
+\&\f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, \f(CW\*(C`pathconf\*(C'\fR, \f(CW\*(C`pause\*(C'\fR, \f(CW\*(C`perror\*(C'\fR, \f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`pow\*(C'\fR,
+\&\f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`putc\*(C'\fR, \f(CW\*(C`putchar\*(C'\fR, \f(CW\*(C`puts\*(C'\fR, \f(CW\*(C`qsort\*(C'\fR, \f(CW\*(C`raise\*(C'\fR, \f(CW\*(C`rand\*(C'\fR,
+\&\f(CW\*(C`read\*(C'\fR, \f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`realloc\*(C'\fR, \f(CW\*(C`remainder\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, \f(CW\*(C`remquo\*(C'\fR,
+\&\f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rewind\*(C'\fR, \f(CW\*(C`rewinddir\*(C'\fR, \f(CW\*(C`rint\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`round\*(C'\fR, \f(CW\*(C`scalbn\*(C'\fR,
+\&\f(CW\*(C`scanf\*(C'\fR, \f(CW\*(C`setgid\*(C'\fR, \f(CW\*(C`setjmp\*(C'\fR, \f(CW\*(C`setlocale\*(C'\fR, \f(CW\*(C`setpayload\*(C'\fR,
+\&\f(CW\*(C`setpayloadsig\*(C'\fR, \f(CW\*(C`setpgid\*(C'\fR, \f(CW\*(C`setsid\*(C'\fR, \f(CW\*(C`setuid\*(C'\fR, \f(CW\*(C`sigaction\*(C'\fR,
+\&\f(CW\*(C`siglongjmp\*(C'\fR, \f(CW\*(C`signbit\*(C'\fR, \f(CW\*(C`sigpending\*(C'\fR, \f(CW\*(C`sigprocmask\*(C'\fR, \f(CW\*(C`sigsetjmp\*(C'\fR,
+\&\f(CW\*(C`sigsuspend\*(C'\fR, \f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`sinh\*(C'\fR, \f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`sprintf\*(C'\fR, \f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`srand\*(C'\fR,
+\&\f(CW\*(C`sscanf\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`strcat\*(C'\fR, \f(CW\*(C`strchr\*(C'\fR, \f(CW\*(C`strcmp\*(C'\fR, \f(CW\*(C`strcoll\*(C'\fR, \f(CW\*(C`strcpy\*(C'\fR,
+\&\f(CW\*(C`strcspn\*(C'\fR, \f(CW\*(C`strerror\*(C'\fR, \f(CW\*(C`strftime\*(C'\fR, \f(CW\*(C`strlen\*(C'\fR, \f(CW\*(C`strncat\*(C'\fR, \f(CW\*(C`strncmp\*(C'\fR,
+\&\f(CW\*(C`strncpy\*(C'\fR, \f(CW\*(C`strpbrk\*(C'\fR, \f(CW\*(C`strrchr\*(C'\fR, \f(CW\*(C`strspn\*(C'\fR, \f(CW\*(C`strstr\*(C'\fR, \f(CW\*(C`strtod\*(C'\fR,
+\&\f(CW\*(C`strtok\*(C'\fR, \f(CW\*(C`strtol\*(C'\fR, \f(CW\*(C`strtold\*(C'\fR, \f(CW\*(C`strtoul\*(C'\fR, \f(CW\*(C`strxfrm\*(C'\fR, \f(CW\*(C`sysconf\*(C'\fR,
+\&\f(CW\*(C`system\*(C'\fR, \f(CW\*(C`tan\*(C'\fR, \f(CW\*(C`tanh\*(C'\fR, \f(CW\*(C`tcdrain\*(C'\fR, \f(CW\*(C`tcflow\*(C'\fR, \f(CW\*(C`tcflush\*(C'\fR,
+\&\f(CW\*(C`tcgetpgrp\*(C'\fR, \f(CW\*(C`tcsendbreak\*(C'\fR, \f(CW\*(C`tcsetpgrp\*(C'\fR, \f(CW\*(C`tgamma\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`times\*(C'\fR,
+\&\f(CW\*(C`tmpfile\*(C'\fR, \f(CW\*(C`tmpnam\*(C'\fR, \f(CW\*(C`tolower\*(C'\fR, \f(CW\*(C`toupper\*(C'\fR, \f(CW\*(C`trunc\*(C'\fR, \f(CW\*(C`ttyname\*(C'\fR,
+\&\f(CW\*(C`tzname\*(C'\fR, \f(CW\*(C`tzset\*(C'\fR, \f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`uname\*(C'\fR, \f(CW\*(C`ungetc\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR,
+\&\f(CW\*(C`vfprintf\*(C'\fR, \f(CW\*(C`vprintf\*(C'\fR, \f(CW\*(C`vsprintf\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR, \f(CW\*(C`wctomb\*(C'\fR,
+\&\f(CW\*(C`write\*(C'\fR
+.IP CLASSES 4
+.IX Item "CLASSES"
+.RS 4
+.PD 0
+.ie n .IP """POSIX::SigAction""" 4
+.el .IP \f(CWPOSIX::SigAction\fR 4
+.IX Item "POSIX::SigAction"
+.PD
+\&\f(CW\*(C`new\*(C'\fR, \f(CW\*(C`handler\*(C'\fR, \f(CW\*(C`mask\*(C'\fR, \f(CW\*(C`flags\*(C'\fR, \f(CW\*(C`safe\*(C'\fR
+.ie n .IP """POSIX::SigRt""" 4
+.el .IP \f(CWPOSIX::SigRt\fR 4
+.IX Item "POSIX::SigRt"
+\&\f(CW%SIGRT\fR, \f(CW\*(C`SIGRTMIN\*(C'\fR, \f(CW\*(C`SIGRTMAX\*(C'\fR
+.ie n .IP """POSIX::SigSet""" 4
+.el .IP \f(CWPOSIX::SigSet\fR 4
+.IX Item "POSIX::SigSet"
+\&\f(CW\*(C`new\*(C'\fR, \f(CW\*(C`addset\*(C'\fR, \f(CW\*(C`delset\*(C'\fR, \f(CW\*(C`emptyset\*(C'\fR, \f(CW\*(C`fillset\*(C'\fR, \f(CW\*(C`ismember\*(C'\fR
+.ie n .IP """POSIX::Termios""" 4
+.el .IP \f(CWPOSIX::Termios\fR 4
+.IX Item "POSIX::Termios"
+\&\f(CW\*(C`new\*(C'\fR, \f(CW\*(C`getattr\*(C'\fR, \f(CW\*(C`getcc\*(C'\fR, \f(CW\*(C`getcflag\*(C'\fR, \f(CW\*(C`getiflag\*(C'\fR, \f(CW\*(C`getispeed\*(C'\fR,
+\&\f(CW\*(C`getlflag\*(C'\fR, \f(CW\*(C`getoflag\*(C'\fR, \f(CW\*(C`getospeed\*(C'\fR, \f(CW\*(C`setattr\*(C'\fR, \f(CW\*(C`setcc\*(C'\fR, \f(CW\*(C`setcflag\*(C'\fR,
+\&\f(CW\*(C`setiflag\*(C'\fR, \f(CW\*(C`setispeed\*(C'\fR, \f(CW\*(C`setlflag\*(C'\fR, \f(CW\*(C`setoflag\*(C'\fR, \f(CW\*(C`setospeed\*(C'\fR, Baud
+rate values, Terminal interface values, \f(CW\*(C`c_cc\*(C'\fR field values, \f(CW\*(C`c_cflag\*(C'\fR
+field values, \f(CW\*(C`c_iflag\*(C'\fR field values, \f(CW\*(C`c_lflag\*(C'\fR field values, \f(CW\*(C`c_oflag\*(C'\fR
+field values
+.RE
+.RS 4
+.RE
+.IP "PATHNAME CONSTANTS" 4
+.IX Item "PATHNAME CONSTANTS"
+Constants
+.IP "POSIX CONSTANTS" 4
+.IX Item "POSIX CONSTANTS"
+Constants
+.IP "RESOURCE CONSTANTS" 4
+.IX Item "RESOURCE CONSTANTS"
+Constants
+.IP "SYSTEM CONFIGURATION" 4
+.IX Item "SYSTEM CONFIGURATION"
+Constants
+.IP ERRNO 4
+.IX Item "ERRNO"
+Constants
+.IP FCNTL 4
+.IX Item "FCNTL"
+Constants
+.IP FLOAT 4
+.IX Item "FLOAT"
+Constants
+.IP "FLOATING-POINT ENVIRONMENT" 4
+.IX Item "FLOATING-POINT ENVIRONMENT"
+Constants
+.IP LIMITS 4
+.IX Item "LIMITS"
+Constants
+.IP LOCALE 4
+.IX Item "LOCALE"
+Constants
+.IP MATH 4
+.IX Item "MATH"
+Constants
+.IP SIGNAL 4
+.IX Item "SIGNAL"
+Constants
+.IP STAT 4
+.IX Item "STAT"
+Constants, Macros
+.IP STDLIB 4
+.IX Item "STDLIB"
+Constants
+.IP STDIO 4
+.IX Item "STDIO"
+Constants
+.IP TIME 4
+.IX Item "TIME"
+Constants
+.IP UNISTD 4
+.IX Item "UNISTD"
+Constants
+.IP WAIT 4
+.IX Item "WAIT"
+Constants, \f(CW\*(C`WNOHANG\*(C'\fR, \f(CW\*(C`WUNTRACED\*(C'\fR, Macros, \f(CW\*(C`WIFEXITED\*(C'\fR, \f(CW\*(C`WEXITSTATUS\*(C'\fR,
+\&\f(CW\*(C`WIFSIGNALED\*(C'\fR, \f(CW\*(C`WTERMSIG\*(C'\fR, \f(CW\*(C`WIFSTOPPED\*(C'\fR, \f(CW\*(C`WSTOPSIG\*(C'\fR
+.IP WINSOCK 4
+.IX Item "WINSOCK"
+Constants
+.SS "Params::Check \- A generic input parsing/checking mechanism."
+.IX Subsection "Params::Check - A generic input parsing/checking mechanism."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Template 4
+.IX Item "Template"
+.PD
+default, required, strict_type, defined, no_override, store, allow
+.IP Functions 4
+.IX Item "Functions"
+.RS 4
+.PD 0
+.IP "check( \e%tmpl, \e%args, [$verbose] );" 4
+.IX Item "check( %tmpl, %args, [$verbose] );"
+.PD
+Template, Arguments, Verbose
+.RE
+.RS 4
+.RE
+.ie n .IP "allow( $test_me, \e@criteria );" 4
+.el .IP "allow( \f(CW$test_me\fR, \e@criteria );" 4
+.IX Item "allow( $test_me, @criteria );"
+string, regexp, subroutine, array ref
+.IP \fBlast_error()\fR 4
+.IX Item "last_error()"
+.PD 0
+.IP "Global Variables" 4
+.IX Item "Global Variables"
+.RS 4
+.ie n .IP $Params::Check::VERBOSE 4
+.el .IP \f(CW$Params::Check::VERBOSE\fR 4
+.IX Item "$Params::Check::VERBOSE"
+.ie n .IP $Params::Check::STRICT_TYPE 4
+.el .IP \f(CW$Params::Check::STRICT_TYPE\fR 4
+.IX Item "$Params::Check::STRICT_TYPE"
+.ie n .IP $Params::Check::ALLOW_UNKNOWN 4
+.el .IP \f(CW$Params::Check::ALLOW_UNKNOWN\fR 4
+.IX Item "$Params::Check::ALLOW_UNKNOWN"
+.ie n .IP $Params::Check::STRIP_LEADING_DASHES 4
+.el .IP \f(CW$Params::Check::STRIP_LEADING_DASHES\fR 4
+.IX Item "$Params::Check::STRIP_LEADING_DASHES"
+.ie n .IP $Params::Check::NO_DUPLICATES 4
+.el .IP \f(CW$Params::Check::NO_DUPLICATES\fR 4
+.IX Item "$Params::Check::NO_DUPLICATES"
+.ie n .IP $Params::Check::PRESERVE_CASE 4
+.el .IP \f(CW$Params::Check::PRESERVE_CASE\fR 4
+.IX Item "$Params::Check::PRESERVE_CASE"
+.ie n .IP $Params::Check::ONLY_ALLOW_DEFINED 4
+.el .IP \f(CW$Params::Check::ONLY_ALLOW_DEFINED\fR 4
+.IX Item "$Params::Check::ONLY_ALLOW_DEFINED"
+.ie n .IP $Params::Check::SANITY_CHECK_TEMPLATE 4
+.el .IP \f(CW$Params::Check::SANITY_CHECK_TEMPLATE\fR 4
+.IX Item "$Params::Check::SANITY_CHECK_TEMPLATE"
+.ie n .IP $Params::Check::WARNINGS_FATAL 4
+.el .IP \f(CW$Params::Check::WARNINGS_FATAL\fR 4
+.IX Item "$Params::Check::WARNINGS_FATAL"
+.ie n .IP $Params::Check::CALLER_DEPTH 4
+.el .IP \f(CW$Params::Check::CALLER_DEPTH\fR 4
+.IX Item "$Params::Check::CALLER_DEPTH"
+.RE
+.RS 4
+.RE
+.IP Acknowledgements 4
+.IX Item "Acknowledgements"
+.IP "BUG REPORTS" 4
+.IX Item "BUG REPORTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Parse::CPAN::Meta \- Parse META.yml and META.json CPAN metadata files"
+.IX Subsection "Parse::CPAN::Meta - Parse META.yml and META.json CPAN metadata files"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP load_file 4
+.IX Item "load_file"
+.IP load_yaml_string 4
+.IX Item "load_yaml_string"
+.IP load_json_string 4
+.IX Item "load_json_string"
+.IP load_string 4
+.IX Item "load_string"
+.IP yaml_backend 4
+.IX Item "yaml_backend"
+.IP json_backend 4
+.IX Item "json_backend"
+.IP json_decoder 4
+.IX Item "json_decoder"
+.RE
+.RS 4
+.RE
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP Load 4
+.IX Item "Load"
+.IP LoadFile 4
+.IX Item "LoadFile"
+.RE
+.RS 4
+.RE
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.RS 4
+.IP CPAN_META_JSON_DECODER 4
+.IX Item "CPAN_META_JSON_DECODER"
+.IP CPAN_META_JSON_BACKEND 4
+.IX Item "CPAN_META_JSON_BACKEND"
+.IP PERL_JSON_BACKEND 4
+.IX Item "PERL_JSON_BACKEND"
+.IP PERL_YAML_BACKEND 4
+.IX Item "PERL_YAML_BACKEND"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Perl::OSType \- Map Perl operating system names to generic types"
+.IX Subsection "Perl::OSType - Map Perl operating system names to generic types"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.RS 4
+.IP \fBos_type()\fR 4
+.IX Item "os_type()"
+.IP \fBis_os_type()\fR 4
+.IX Item "is_os_type()"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.RS 4
+.IP "Bugs / Feature Requests" 4
+.IX Item "Bugs / Feature Requests"
+.IP "Source Code" 4
+.IX Item "Source Code"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "PerlIO \- On demand loader for PerlIO layers and root of PerlIO::* name space"
+.IX Subsection "PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Layers 4
+.IX Item "Layers"
+.PD
+:unix, :stdio, :perlio, :crlf, :utf8, :bytes, :raw, :pop
+.IP "Custom Layers" 4
+.IX Item "Custom Layers"
+:encoding, :mmap, :via, :scalar
+.IP "Alternatives to raw" 4
+.IX Item "Alternatives to raw"
+.PD 0
+.IP "Defaults and how to override them" 4
+.IX Item "Defaults and how to override them"
+.IP "Querying the layers of filehandles" 4
+.IX Item "Querying the layers of filehandles"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "PerlIO::encoding \- encoding layer"
+.IX Subsection "PerlIO::encoding - encoding layer"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "PerlIO::mmap \- Memory mapped IO"
+.IX Subsection "PerlIO::mmap - Memory mapped IO"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "IMPLEMENTATION NOTE" 4
+.IX Item "IMPLEMENTATION NOTE"
+.PD
+.SS "PerlIO::scalar \- in-memory IO, scalar IO"
+.IX Subsection "PerlIO::scalar - in-memory IO, scalar IO"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "IMPLEMENTATION NOTE" 4
+.IX Item "IMPLEMENTATION NOTE"
+.PD
+.SS "PerlIO::via \- Helper class for PerlIO layers implemented in perl"
+.IX Subsection "PerlIO::via - Helper class for PerlIO layers implemented in perl"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "EXPECTED METHODS" 4
+.IX Item "EXPECTED METHODS"
+.PD
+\&\f(CW$class\fR\->PUSHED([$mode,[$fh]]), \f(CW$obj\fR\->POPPED([$fh]),
+\&\f(CW$obj\fR\->UTF8($belowFlag,[$fh]), \f(CW$obj\fR\->OPEN($path,$mode,[$fh]),
+\&\f(CW$obj\fR\->BINMODE([$fh]), \f(CW$obj\fR\->FDOPEN($fd,[$fh]),
+\&\f(CW$obj\fR\->SYSOPEN($path,$imode,$perm,[$fh]), \f(CW$obj\fR\->FILENO($fh),
+\&\f(CW$obj\fR\->READ($buffer,$len,$fh), \f(CW$obj\fR\->WRITE($buffer,$fh), \f(CW$obj\fR\->FILL($fh),
+\&\f(CW$obj\fR\->CLOSE($fh), \f(CW$obj\fR\->SEEK($posn,$whence,$fh), \f(CW$obj\fR\->TELL($fh),
+\&\f(CW$obj\fR\->UNREAD($buffer,$fh), \f(CW$obj\fR\->FLUSH($fh), \f(CW$obj\fR\->SETLINEBUF($fh),
+\&\f(CW$obj\fR\->CLEARERR($fh), \f(CW$obj\fR\->ERROR($fh), \f(CW$obj\fR\->EOF($fh)
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Example \- a Hexadecimal Handle" 4
+.IX Item "Example - a Hexadecimal Handle"
+.RE
+.RS 4
+.RE
+.PD
+.SS "PerlIO::via::QuotedPrint \- PerlIO layer for quoted-printable strings"
+.IX Subsection "PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP FEEDBACK 4
+.IX Item "FEEDBACK"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AVAILABILITY 4
+.IX Item "AVAILABILITY"
+.IP INSTALLATION 4
+.IX Item "INSTALLATION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Pod::Checker \- check pod documents for syntax errors"
+.IX Subsection "Pod::Checker - check pod documents for syntax errors"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP OPTIONS/ARGUMENTS 4
+.IX Item "OPTIONS/ARGUMENTS"
+.RS 4
+.IP \fBpodchecker()\fR 4
+.IX Item "podchecker()"
+.PD
+\&\fB\-warnings\fR => \fIval\fR, \fB\-quiet\fR => \fIval\fR
+.RE
+.RS 4
+.RE
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.RS 4
+.IP Errors 4
+.IX Item "Errors"
+.PD
+empty =headn, =over on line \fIN\fR without closing =back, You forgot a
+\&'=back' before '=head\fIN\fR', =over is the last thing in the document?!,
+\&'=item' outside of any '=over', =back without =over, Can't have a 0 in
+=over \fIN\fR, =over should be: '=over' or '=over positive_number', =begin
+\&\fITARGET\fR without matching =end \fITARGET\fR, =begin without a target?, =end
+\&\fITARGET\fR without matching =begin, '=end' without a target?, '=end
+\&\fITARGET\fR' is invalid, =end \fICONTENT\fR doesn't match =begin \fITARGET\fR, =for
+without a target?, unresolved internal link \fINAME\fR, Unknown directive:
+\&\fICMD\fR, Deleting unknown formatting code \fISEQ\fR, Unterminated
+\&\fISEQ\fR<> sequence, An E<...> surrounding strange content,
+An empty E<>, An empty \f(CW\*(C`L<>\*(C'\fR, An empty X<>,
+Spurious text after =pod / =cut, =back doesn't take any parameters, but you
+said =back \fIARGUMENT\fR, =pod directives shouldn't be over one line long! 
+Ignoring all \fIN\fR lines of content, =cut found outside a pod block, Invalid
+=encoding syntax: \fICONTENT\fR
+.IP Warnings 4
+.IX Item "Warnings"
+nested commands \fICMD\fR<...\fICMD\fR<...>...>, multiple
+occurrences (\fIN\fR) of link target \fIname\fR, line containing nothing but
+whitespace in paragraph, =item has no contents, You can't have =items (as
+at line \fIN\fR) unless the first thing after the =over is an =item, Expected
+\&'=item \fIEXPECTED VALUE\fR', Expected '=item *', Possible =item type
+mismatch: '\fIx\fR' found leading a supposed definition =item, You have '=item
+x' instead of the expected '=item \fIN\fR', Unknown E content in
+E<\fICONTENT\fR>, empty =over/=back block, empty section in previous
+paragraph, Verbatim paragraph in NAME section, =head\fIn\fR without preceding
+higher level, A non-empty Z<>
+.IP Hyperlinks 4
+.IX Item "Hyperlinks"
+ignoring leading/trailing whitespace in link, alternative text/node '%s'
+contains non-escaped | or /
+.RE
+.RS 4
+.RE
+.IP "RETURN VALUE" 4
+.IX Item "RETURN VALUE"
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP SCRIPTS 4
+.IX Item "SCRIPTS"
+.IP INTERFACE 4
+.IX Item "INTERFACE"
+.PD
+end_B, end_C, end_Document, end_F, end_I, end_L, end_Para, end_S, end_X,
+end_fcode, end_for, end_head, end_head1, end_head2, end_head3, end_head4,
+end_item, end_item_bullet, end_item_number, end_item_text,
+handle_pod_and_cut, handle_text, handle_whiteline, hyperlink, scream,
+start_B, start_C, start_Data, start_F, start_I, start_L, start_Para,
+start_S, start_Verbatim, start_X, start_fcode, start_for, start_head,
+start_head1, start_head2, start_head3, start_head4, start_item_bullet,
+start_item_number, start_item_text, start_over, start_over_block,
+start_over_bullet, start_over_empty, start_over_number, start_over_text,
+whine
+.PP
+\&\f(CW\*(C`Pod::Checker\->new( %options )\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->poderror( @args )\*(C'\fR, \f(CW\*(C`$checker\->poderror( {%opts},
+@args )\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->num_errors()\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->num_warnings()\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->name()\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->node()\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->idx()\*(C'\fR
+.PP
+\&\f(CW\*(C`$checker\->hyperlinks()\*(C'\fR
+.PP
+\&\fBline()\fR
+.PP
+\&\fBtype()\fR
+.PP
+\&\fBpage()\fR
+.PP
+\&\fBnode()\fR
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "Pod::Escapes \- for resolving Pod E<...> sequences"
+.IX Subsection "Pod::Escapes - for resolving Pod E<...> sequences"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP GOODIES 4
+.IX Item "GOODIES"
+.PD
+e2char($e_content), e2charnum($e_content), \f(CW$Name2character\fR{\fIname\fR},
+\&\f(CW$Name2character_number\fR{\fIname\fR}, \f(CW$Latin1Code_to_fallback\fR{\fIinteger\fR},
+\&\f(CW$Latin1Char_to_fallback\fR{\fIcharacter\fR}, \f(CW$Code2USASCII\fR{\fIinteger\fR}
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP REPOSITORY 4
+.IX Item "REPOSITORY"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Html \- module to convert pod files to HTML"
+.IX Subsection "Pod::Html - module to convert pod files to HTML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.IP pod2html 4
+.IX Item "pod2html"
+.PD
+backlink, cachedir, css, flush, header, help, htmldir, htmlroot, index,
+infile, outfile, poderrors, podpath, podroot, quiet, recurse, title,
+verbose
+.IP "Formerly Exported Auxiliary Functions" 4
+.IX Item "Formerly Exported Auxiliary Functions"
+\&\f(CWhtmlify()\fR (by default), \f(CWanchorify()\fR (upon request),
+\&\f(CWrelativize_url()\fR (upon request)
+.RE
+.RS 4
+.RE
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Pod::Html::Util \- helper functions for Pod-Html"
+.IX Subsection "Pod::Html::Util - helper functions for Pod-Html"
+.IP SUBROUTINES 4
+.IX Item "SUBROUTINES"
+.PD 0
+.ie n .IP process_command_line() 4
+.el .IP \f(CWprocess_command_line()\fR 4
+.IX Item "process_command_line()"
+.ie n .IP usage() 4
+.el .IP \f(CWusage()\fR 4
+.IX Item "usage()"
+.ie n .IP unixify() 4
+.el .IP \f(CWunixify()\fR 4
+.IX Item "unixify()"
+.ie n .IP relativize_url() 4
+.el .IP \f(CWrelativize_url()\fR 4
+.IX Item "relativize_url()"
+.ie n .IP html_escape() 4
+.el .IP \f(CWhtml_escape()\fR 4
+.IX Item "html_escape()"
+.ie n .IP htmlify() 4
+.el .IP \f(CWhtmlify()\fR 4
+.IX Item "htmlify()"
+.ie n .IP anchorify() 4
+.el .IP \f(CWanchorify()\fR 4
+.IX Item "anchorify()"
+.ie n .IP trim_leading_whitespace() 4
+.el .IP \f(CWtrim_leading_whitespace()\fR 4
+.IX Item "trim_leading_whitespace()"
+.PD
+.SS "Pod::Man \- Convert POD data to formatted *roff input"
+.IX Subsection "Pod::Man - Convert POD data to formatted *roff input"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CLASS METHODS" 4
+.IX Item "CLASS METHODS"
+.PD
+new(ARGS), center, date, encoding, errors, fixed, fixedbold, fixeditalic,
+fixedbolditalic, guesswork, functions, manref, quoting, variables,
+language, lquote, rquote, name, nourls, quotes, release, section, stderr,
+utf8
+.IP "INSTANCE METHODS" 4
+.IX Item "INSTANCE METHODS"
+output_fh(FH), output_string(REF), parse_file(PATH), parse_from_file(INPUT,
+OUTPUT), parse_from_filehandle(FH, OUTPUT), parse_lines(LINES[, ...[,
+undef]]), parse_string_document(INPUT)
+.IP ENCODING 4
+.IX Item "ENCODING"
+.RS 4
+.PD 0
+.IP History 4
+.IX Item "History"
+.IP "Testing results" 4
+.IX Item "Testing results"
+.PD
+[1], [2], [3]
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+roff font should be 1 or 2 chars, not "%s", Invalid errors setting "%s",
+Invalid quote specification "%s", POD document had syntax errors
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+PERL_CORE, POD_MAN_DATE, SOURCE_DATE_EPOCH
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.RS 4
+.IP "Sentence spacing" 4
+.IX Item "Sentence spacing"
+.IP Hyphens 4
+.IX Item "Hyphens"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::ParseLink \- Parse an L<> formatting code in POD text"
+.IX Subsection "Pod::ParseLink - Parse an L<> formatting code in POD text"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::Perldoc \- Look up Perl documentation in Pod format."
+.IX Subsection "Pod::Perldoc - Look up Perl documentation in Pod format."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::BaseTo \- Base for Pod::Perldoc formatters"
+.IX Subsection "Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::GetOptsOO \- Customized option parser for Pod::Perldoc"
+.IX Subsection "Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Call Pod::Perldoc::GetOptsOO::getopts($object, \e@ARGV, \f(CW$truth\fR), Given \-n,
+if there's a opt_n_with, it'll call \f(CW$object\fR\->opt_n_with( ARGUMENT )   
+(e.g., "\-n foo" => \f(CW$object\fR\->opt_n_with('foo').	Ditto "\-nfoo"), Otherwise
+(given \-n) if there's an opt_n, we'll call it \f(CW$object\fR\->opt_n($truth)   
+(Truth defaults to 1), Otherwise we try calling
+\&\f(CW$object\fR\->handle_unknown_option('n')    (and we increment the error count by
+the return value of it), If there's no handle_unknown_option, then we just
+warn, and then increment    the error counter
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToANSI \- render Pod with ANSI color escapes"
+.IX Subsection "Pod::Perldoc::ToANSI - render Pod with ANSI color escapes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToChecker \- let Perldoc check Pod for errors"
+.IX Subsection "Pod::Perldoc::ToChecker - let Perldoc check Pod for errors"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToMan \- let Perldoc render Pod as man pages"
+.IX Subsection "Pod::Perldoc::ToMan - let Perldoc render Pod as man pages"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToNroff \- let Perldoc convert Pod to nroff"
+.IX Subsection "Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToPod \- let Perldoc render Pod as ... Pod!"
+.IX Subsection "Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToRtf \- let Perldoc render Pod as RTF"
+.IX Subsection "Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToTerm \- render Pod with terminal escapes"
+.IX Subsection "Pod::Perldoc::ToTerm - render Pod with terminal escapes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "PAGER FORMATTING" 4
+.IX Item "PAGER FORMATTING"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToText \- let Perldoc render Pod as plaintext"
+.IX Subsection "Pod::Perldoc::ToText - let Perldoc render Pod as plaintext"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToTk \- let Perldoc use Tk::Pod to render Pod"
+.IX Subsection "Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Perldoc::ToXml \- let Perldoc render Pod as XML"
+.IX Subsection "Pod::Perldoc::ToXml - let Perldoc render Pod as XML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Pod::Simple \- framework for parsing Pod"
+.IX Subsection "Pod::Simple - framework for parsing Pod"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "MAIN METHODS" 4
+.IX Item "MAIN METHODS"
+.PD
+\&\f(CW\*(C`$parser = \fR\f(CISomeClass\fR\f(CW\->new();\*(C'\fR, \f(CW\*(C`$parser\->output_fh( *OUT );\*(C'\fR,
+\&\f(CW\*(C`$parser\->output_string( \e$somestring );\*(C'\fR, \f(CW\*(C`$parser\->parse_file(
+\&\fR\f(CI$some_filename\fR\f(CW );\*(C'\fR, \f(CW\*(C`$parser\->parse_file( *INPUT_FH );\*(C'\fR, \f(CW\*(C`$parser\->parse_string_document( \fR\f(CI$all_content\fR\f(CW );\*(C'\fR, \f(CW\*(C`$parser\->parse_lines( \fR\f(CI...@lines...\fR\f(CW, undef );\*(C'\fR, \f(CW\*(C`$parser\->content_seen\*(C'\fR, \f(CW\*(C`\fR\f(CISomeClass\fR\f(CW\->filter( \fR\f(CI$filename\fR\f(CW );\*(C'\fR, \f(CW\*(C`\fR\f(CISomeClass\fR\f(CW\->filter( \fR\f(CI*INPUT_FH\fR\f(CW );\*(C'\fR, \f(CW\*(C`\fR\f(CISomeClass\fR\f(CW\->filter(
+\&\fR\f(CI\e$document_content\fR\f(CW );\*(C'\fR
+.IP "SECONDARY METHODS" 4
+.IX Item "SECONDARY METHODS"
+\&\f(CW\*(C`$parser\->parse_characters( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->no_whining(
+\&\fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->source_filename\*(C'\fR, \f(CW\*(C`$parser\->doc_has_started\*(C'\fR, \f(CW\*(C`$parser\->source_dead\*(C'\fR, \f(CW\*(C`$parser\->strip_verbatim_indent( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->expand_verbatim_tabs( \fR\f(CIn\fR\f(CW )\*(C'\fR
+.IP "TERTIARY METHODS" 4
+.IX Item "TERTIARY METHODS"
+\&\f(CW\*(C`$parser\->abandon_output_fh()\*(C'\fR, \f(CW\*(C`$parser\->abandon_output_string()\*(C'\fR, \f(CW\*(C`$parser\->accept_code( @codes )\*(C'\fR, \f(CW\*(C`$parser\->accept_codes(
+@codes )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_data(
+@directives )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_processed( @directives )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_verbatim( @directives )\*(C'\fR, \f(CW\*(C`$parser\->accept_target( @targets )\*(C'\fR, \f(CW\*(C`$parser\->accept_target_as_text( @targets )\*(C'\fR, \f(CW\*(C`$parser\->accept_targets( @targets )\*(C'\fR, \f(CW\*(C`$parser\->accept_targets_as_text( @targets )\*(C'\fR, \f(CW\*(C`$parser\->any_errata_seen()\*(C'\fR, \f(CW\*(C`$parser\->errata_seen()\*(C'\fR, \f(CW\*(C`$parser\->detected_encoding()\*(C'\fR, \f(CW\*(C`$parser\->encoding()\*(C'\fR, \f(CW\*(C`$parser\->parse_from_file( $source,
+$to )\*(C'\fR, \f(CW\*(C`$parser\->scream( @error_messages )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_code( @codes )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_codes( @codes )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_directive( @directives )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_directives( @directives )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_target( @targets )\*(C'\fR, \f(CW\*(C`$parser\->unaccept_targets( @targets )\*(C'\fR, \f(CW\*(C`$parser\->version_report()\*(C'\fR, \f(CW\*(C`$parser\->whine(
+@error_messages )\*(C'\fR
+.IX Xref "abandon_output_fh abandon_output_string accept_code accept_codes accept_directive_as_data accept_directive_as_processed accept_directive_as_verbatim accept_target accept_target_as_text accept_targets accept_targets_as_text any_errata_seen errata_seen detected_encoding encoding parse_from_file scream unaccept_code unaccept_codes unaccept_directive unaccept_directives unaccept_target unaccept_targets version_report whine"
+.IP ENCODING 4
+.IX Item "ENCODING"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR, Karl Williamson \f(CW\*(C`khw@cpan.org\*(C'\fR,
+Gabor Szabo \f(CW\*(C`szabgab@gmail.com\*(C'\fR, Shawn H Corey  \f(CW\*(C`SHCOREY at cpan.org\*(C'\fR
+.SS "Pod::Simple::Checker \-\- check the Pod syntax of a document"
+.IX Subsection "Pod::Simple::Checker -- check the Pod syntax of a document"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::Debug \-\- put Pod::Simple into trace/debug mode"
+.IX Subsection "Pod::Simple::Debug -- put Pod::Simple into trace/debug mode"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP GUTS 4
+.IX Item "GUTS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::DumpAsText \-\- dump Pod-parsing events as text"
+.IX Subsection "Pod::Simple::DumpAsText -- dump Pod-parsing events as text"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::DumpAsXML \-\- turn Pod into XML"
+.IX Subsection "Pod::Simple::DumpAsXML -- turn Pod into XML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::HTML \- convert Pod to HTML"
+.IX Subsection "Pod::Simple::HTML - convert Pod to HTML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CALLING FROM THE COMMAND LINE" 4
+.IX Item "CALLING FROM THE COMMAND LINE"
+.IP "CALLING FROM PERL" 4
+.IX Item "CALLING FROM PERL"
+.RS 4
+.IP "Minimal code" 4
+.IX Item "Minimal code"
+.IP "More detailed example" 4
+.IX Item "More detailed example"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP html_css 4
+.IX Item "html_css"
+.IP html_javascript 4
+.IX Item "html_javascript"
+.IP title_prefix 4
+.IX Item "title_prefix"
+.IP title_postfix 4
+.IX Item "title_postfix"
+.IP html_header_before_title 4
+.IX Item "html_header_before_title"
+.IP top_anchor 4
+.IX Item "top_anchor"
+.IP html_h_level 4
+.IX Item "html_h_level"
+.IP index 4
+.IX Item "index"
+.IP html_header_after_title 4
+.IX Item "html_header_after_title"
+.IP html_footer 4
+.IX Item "html_footer"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::HTMLBatch \- convert several Pod files to several HTML files"
+.IX Subsection "Pod::Simple::HTMLBatch - convert several Pod files to several HTML files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "FROM THE COMMAND LINE" 4
+.IX Item "FROM THE COMMAND LINE"
+.RE
+.RS 4
+.RE
+.IP "MAIN METHODS" 4
+.IX Item "MAIN METHODS"
+.PD
+\&\f(CW$batchconv\fR = Pod::Simple::HTMLBatch\->new;, \f(CW$batchconv\fR\->batch_convert(
+\&\fIindirs\fR, \fIoutdir\fR );, \f(CW$batchconv\fR\->batch_convert( undef    , ...);,
+\&\f(CW$batchconv\fR\->batch_convert( q{@INC}, ...);, \f(CW$batchconv\fR\->batch_convert(
+\&\e@dirs , ...);, \f(CW$batchconv\fR\->batch_convert( "somedir" , ...);,
+\&\f(CW$batchconv\fR\->batch_convert( 'somedir:someother:also' , ...);,
+\&\f(CW$batchconv\fR\->batch_convert( ... , undef );, \f(CW$batchconv\fR\->batch_convert( ... ,
+\&'somedir' );
+.RS 4
+.IP "ACCESSOR METHODS" 4
+.IX Item "ACCESSOR METHODS"
+\&\f(CW$batchconv\fR\->verbose( \fInonnegative_integer\fR );, \f(CW$batchconv\fR\->index(
+\&\fItrue-or-false\fR );, \f(CW$batchconv\fR\->contents_file( \fIfilename\fR );,
+\&\f(CW$batchconv\fR\->contents_page_start( \fIHTML_string\fR );,
+\&\f(CW$batchconv\fR\->contents_page_end( \fIHTML_string\fR );, \f(CW$batchconv\fR\->add_css( \f(CW$url\fR
+);, \f(CW$batchconv\fR\->add_javascript( \f(CW$url\fR );, \f(CW$batchconv\fR\->css_flurry(
+\&\fItrue-or-false\fR );, \f(CW$batchconv\fR\->javascript_flurry( \fItrue-or-false\fR );,
+\&\f(CW$batchconv\fR\->no_contents_links( \fItrue-or-false\fR );,
+\&\f(CW$batchconv\fR\->html_render_class( \fIclassname\fR );, \f(CW$batchconv\fR\->search_class(
+\&\fIclassname\fR );
+.RE
+.RS 4
+.RE
+.IP "NOTES ON CUSTOMIZATION" 4
+.IX Item "NOTES ON CUSTOMIZATION"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::JustPod \-\- just the Pod, the whole Pod, and nothing but the Pod"
+.IX Subsection "Pod::Simple::JustPod -- just the Pod, the whole Pod, and nothing but the Pod"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::LinkSection \-\- represent ""section"" attributes of L codes"
+.IX Subsection "Pod::Simple::LinkSection -- represent ""section"" attributes of L codes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::Methody \-\- turn Pod::Simple events into method calls"
+.IX Subsection "Pod::Simple::Methody -- turn Pod::Simple events into method calls"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "METHOD CALLING" 4
+.IX Item "METHOD CALLING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::PullParser \-\- a pull-parser interface to parsing Pod"
+.IX Subsection "Pod::Simple::PullParser -- a pull-parser interface to parsing Pod"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+my \f(CW$token\fR = \f(CW$parser\fR\->get_token, \f(CW$parser\fR\->unget_token( \f(CW$token\fR ),
+\&\f(CW$parser\fR\->unget_token( \f(CW$token1\fR, \f(CW$token2\fR, ... ), \f(CW$parser\fR\->set_source(
+\&\f(CW$filename\fR ), \f(CW$parser\fR\->set_source( \f(CW$filehandle_object\fR ),
+\&\f(CW$parser\fR\->set_source( \e$document_source ), \f(CW$parser\fR\->set_source(
+\&\e@document_lines ), \f(CW$parser\fR\->parse_file(...),
+\&\f(CW$parser\fR\->parse_string_document(...), \f(CW$parser\fR\->filter(...),
+\&\f(CW$parser\fR\->parse_from_file(...), my \f(CW$title_string\fR = \f(CW$parser\fR\->get_title, my
+\&\f(CW$title_string\fR = \f(CW$parser\fR\->get_short_title, \f(CW$author_name\fR	 =
+\&\f(CW$parser\fR\->get_author, \f(CW$description_name\fR = \f(CW$parser\fR\->get_description,
+\&\f(CW$version_block\fR = \f(CW$parser\fR\->get_version
+.IP NOTE 4
+.IX Item "NOTE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::PullParserEndToken \-\- end-tokens from Pod::Simple::PullParser"
+.IX Subsection "Pod::Simple::PullParserEndToken -- end-tokens from Pod::Simple::PullParser"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$token\fR\->tagname, \f(CW$token\fR\->tagname(\fIsomestring\fR), \f(CW$token\fR\->tag(...),
+\&\f(CW$token\fR\->is_tag(\fIsomestring\fR) or \f(CW$token\fR\->is_tagname(\fIsomestring\fR)
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::PullParserStartToken \-\- start-tokens from Pod::Simple::PullParser"
+.IX Subsection "Pod::Simple::PullParserStartToken -- start-tokens from Pod::Simple::PullParser"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$token\fR\->tagname, \f(CW$token\fR\->tagname(\fIsomestring\fR), \f(CW$token\fR\->tag(...),
+\&\f(CW$token\fR\->is_tag(\fIsomestring\fR) or \f(CW$token\fR\->is_tagname(\fIsomestring\fR),
+\&\f(CW$token\fR\->attr(\fIattrname\fR), \f(CW$token\fR\->attr(\fIattrname\fR, \fInewvalue\fR),
+\&\f(CW$token\fR\->attr_hash
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::PullParserTextToken \-\- text-tokens from Pod::Simple::PullParser"
+.IX Subsection "Pod::Simple::PullParserTextToken -- text-tokens from Pod::Simple::PullParser"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$token\fR\->text, \f(CW$token\fR\->text(\fIsomestring\fR), \f(CW$token\fR\->\fBtext_r()\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::PullParserToken \-\- tokens from Pod::Simple::PullParser"
+.IX Subsection "Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW$token\fR\->type, \f(CW$token\fR\->is_start, \f(CW$token\fR\->is_text, \f(CW$token\fR\->is_end,
+\&\f(CW$token\fR\->dump
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::RTF \-\- format Pod as RTF"
+.IX Subsection "Pod::Simple::RTF -- format Pod as RTF"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FORMAT CONTROL ATTRIBUTES" 4
+.IX Item "FORMAT CONTROL ATTRIBUTES"
+.PD
+\&\f(CW$parser\fR\->head1_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->head2_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->head3_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->head4_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->codeblock_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->header_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->normal_halfpoint_size( \fIhalfpoint_integer\fR );,
+\&\f(CW$parser\fR\->no_proofing_exemptions( \fItrue_or_false\fR );, \f(CW$parser\fR\->doc_lang(
+\&\fImicrosoft_decimal_language_code\fR )
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::Search \- find POD documents in directory trees"
+.IX Subsection "Pod::Simple::Search - find POD documents in directory trees"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTRUCTOR 4
+.IX Item "CONSTRUCTOR"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$search\fR\->inc( \fItrue-or-false\fR );, \f(CW$search\fR\->verbose( \fInonnegative-number\fR
+);, \f(CW$search\fR\->limit_glob( \fIsome-glob-string\fR );, \f(CW$search\fR\->callback(
+\&\fI\e&some_routine\fR );, \f(CW$search\fR\->laborious( \fItrue-or-false\fR );,
+\&\f(CW$search\fR\->recurse( \fItrue-or-false\fR );, \f(CW$search\fR\->shadows( \fItrue-or-false\fR
+);, \f(CW$search\fR\->is_case_insensitive( \fItrue-or-false\fR );, \f(CW$search\fR\->limit_re(
+\&\fIsome-regxp\fR );, \f(CW$search\fR\->dir_prefix( \fIsome-string-value\fR );,
+\&\f(CW$search\fR\->progress( \fIsome-progress-object\fR );, \f(CW$name2path\fR =
+\&\f(CW$self\fR\->name2path;, \f(CW$path2name\fR = \f(CW$self\fR\->path2name;
+.IP "MAIN SEARCH METHODS" 4
+.IX Item "MAIN SEARCH METHODS"
+.RS 4
+.PD 0
+.ie n .IP """$search\->survey( @directories )""" 4
+.el .IP "\f(CW$search\->survey( @directories )\fR" 4
+.IX Item "$search->survey( @directories )"
+.PD
+\&\f(CW\*(C`name2path\*(C'\fR, \f(CW\*(C`path2name\*(C'\fR
+.ie n .IP """$search\->simplify_name( $str )""" 4
+.el .IP "\f(CW$search\->simplify_name( $str )\fR" 4
+.IX Item "$search->simplify_name( $str )"
+.PD 0
+.ie n .IP """$search\->find( $pod )""" 4
+.el .IP "\f(CW$search\->find( $pod )\fR" 4
+.IX Item "$search->find( $pod )"
+.ie n .IP """$search\->find( $pod, @search_dirs )""" 4
+.el .IP "\f(CW$search\->find( $pod, @search_dirs )\fR" 4
+.IX Item "$search->find( $pod, @search_dirs )"
+.ie n .IP """$self\->contains_pod( $file )""" 4
+.el .IP "\f(CW$self\->contains_pod( $file )\fR" 4
+.IX Item "$self->contains_pod( $file )"
+.RE
+.RS 4
+.RE
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::SimpleTree \-\- parse Pod into a simple parse tree"
+.IX Subsection "Pod::Simple::SimpleTree -- parse Pod into a simple parse tree"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP "Tree Contents" 4
+.IX Item "Tree Contents"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::Subclassing \-\- write a formatter as a Pod::Simple subclass"
+.IX Subsection "Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Pod::Simple, Pod::Simple::Methody, Pod::Simple::PullParser,
+Pod::Simple::SimpleTree
+.IP Events 4
+.IX Item "Events"
+\&\f(CW\*(C`$parser\->_handle_element_start( \fR\f(CIelement_name\fR\f(CW, \fR\f(CIattr_hashref\fR\f(CW )\*(C'\fR,
+\&\f(CW\*(C`$parser\->_handle_element_end( \fR\f(CIelement_name\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->_handle_text(	\fR\f(CItext_string\fR\f(CW	)\*(C'\fR, events with an element_name
+of Document, events with an element_name of Para, events with an
+element_name of B, C, F, or I, events with an element_name of S, events
+with an element_name of X, events with an element_name of L, events with an
+element_name of E or Z, events with an element_name of Verbatim, events
+with an element_name of head1 .. head4, events with an element_name of
+encoding, events with an element_name of over-bullet, events with an
+element_name of over-number, events with an element_name of over-text,
+events with an element_name of over-block, events with an element_name of
+over-empty, events with an element_name of item-bullet, events with an
+element_name of item-number, events with an element_name of item-text,
+events with an element_name of for, events with an element_name of Data
+.IP "More Pod::Simple Methods" 4
+.IX Item "More Pod::Simple Methods"
+\&\f(CW\*(C`$parser\->accept_targets( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->accept_targets_as_text(  \fR\f(CISOMEVALUE\fR\f(CW	)\*(C'\fR, \f(CW\*(C`$parser\->accept_codes( \fR\f(CICodename\fR\f(CW, \fR\f(CICodename\fR\f(CW...  )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_data( \fR\f(CIdirective_name\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_verbatim( \fR\f(CIdirective_name\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->accept_directive_as_processed( \fR\f(CIdirective_name\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->nbsp_for_S( \fR\f(CIBOOLEAN\fR\f(CW );\*(C'\fR, \f(CW\*(C`$parser\->version_report()\*(C'\fR,
+\&\f(CW\*(C`$parser\->pod_para_count()\*(C'\fR, \f(CW\*(C`$parser\->line_count()\*(C'\fR, \f(CW\*(C`$parser\->nix_X_codes(  \fR\f(CISOMEVALUE\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->keep_encoding_directive(  \fR\f(CISOMEVALUE\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->merge_text(  \fR\f(CISOMEVALUE\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->code_handler( 
+\&\fR\f(CICODE_REF\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->cut_handler(  \fR\f(CICODE_REF\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->pod_handler(  \fR\f(CICODE_REF\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->whiteline_handler( 
+\&\fR\f(CICODE_REF\fR\f(CW  )\*(C'\fR, \f(CW\*(C`$parser\->whine( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->scream( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->source_dead(1)\*(C'\fR, \f(CW\*(C`$parser\->hide_line_numbers( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->no_whining( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->bare_output(
+\&\fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->preserve_whitespace( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR, \f(CW\*(C`$parser\->parse_empty_lists( \fR\f(CISOMEVALUE\fR\f(CW )\*(C'\fR
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::Text \-\- format Pod as plaintext"
+.IX Subsection "Pod::Simple::Text -- format Pod as plaintext"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::TextContent \-\- get the text content of Pod"
+.IX Subsection "Pod::Simple::TextContent -- get the text content of Pod"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::XHTML \-\- format Pod as validating XHTML"
+.IX Subsection "Pod::Simple::XHTML -- format Pod as validating XHTML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Minimal code" 4
+.IX Item "Minimal code"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP perldoc_url_prefix 4
+.IX Item "perldoc_url_prefix"
+.IP perldoc_url_postfix 4
+.IX Item "perldoc_url_postfix"
+.IP man_url_prefix 4
+.IX Item "man_url_prefix"
+.IP man_url_postfix 4
+.IX Item "man_url_postfix"
+.IP "title_prefix, title_postfix" 4
+.IX Item "title_prefix, title_postfix"
+.IP html_css 4
+.IX Item "html_css"
+.IP html_javascript 4
+.IX Item "html_javascript"
+.IP html_doctype 4
+.IX Item "html_doctype"
+.IP html_charset 4
+.IX Item "html_charset"
+.IP html_header_tags 4
+.IX Item "html_header_tags"
+.IP html_h_level 4
+.IX Item "html_h_level"
+.IP default_title 4
+.IX Item "default_title"
+.IP force_title 4
+.IX Item "force_title"
+.IP "html_header, html_footer" 4
+.IX Item "html_header, html_footer"
+.IP index 4
+.IX Item "index"
+.IP anchor_items 4
+.IX Item "anchor_items"
+.IP backlink 4
+.IX Item "backlink"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP handle_text 4
+.IX Item "handle_text"
+.IP handle_code 4
+.IX Item "handle_code"
+.IP accept_targets_as_html 4
+.IX Item "accept_targets_as_html"
+.IP resolve_pod_page_link 4
+.IX Item "resolve_pod_page_link"
+.IP resolve_man_page_link 4
+.IX Item "resolve_man_page_link"
+.IP idify 4
+.IX Item "idify"
+.IP batch_mode_page_object_init 4
+.IX Item "batch_mode_page_object_init"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP ACKNOWLEDGEMENTS 4
+.IX Item "ACKNOWLEDGEMENTS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Simple::XMLOutStream \-\- turn Pod into XML"
+.IX Subsection "Pod::Simple::XMLOutStream -- turn Pod into XML"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "ABOUT EXTENDING POD" 4
+.IX Item "ABOUT EXTENDING POD"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP "COPYRIGHT AND DISCLAIMERS" 4
+.IX Item "COPYRIGHT AND DISCLAIMERS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR, Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR,
+David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR
+.SS "Pod::Text \- Convert POD data to formatted text"
+.IX Subsection "Pod::Text - Convert POD data to formatted text"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Encoding 4
+.IX Item "Encoding"
+.RE
+.RS 4
+.RE
+.IP "CLASS METHODS" 4
+.IX Item "CLASS METHODS"
+.PD
+new(ARGS), alt, code, encoding, errors, guesswork, quoting, indent, loose,
+margin, nourls, quotes, sentence, stderr, utf8, width
+.IP "INSTANCE METHODS" 4
+.IX Item "INSTANCE METHODS"
+output_fh(FH), output_string(REF), parse_file(PATH), parse_from_file(INPUT,
+OUTPUT), parse_from_filehandle(FH, OUTPUT), parse_lines(LINES[, ...[,
+undef]]), parse_string_document(INPUT)
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+pod2text([[\-a,] [\-NNN,]] INPUT[, OUTPUT])
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+Bizarre space in item, Item called without tag, Can't open \f(CW%s\fR for reading:
+\&\f(CW%s\fR, Invalid errors setting "%s", Invalid quote specification "%s", POD
+document had syntax errors
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::Text::Color \- Convert POD data to formatted color ASCII text"
+.IX Subsection "Pod::Text::Color - Convert POD data to formatted color ASCII text"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::Text::Overstrike \- Convert POD data to formatted overstrike text"
+.IX Subsection "Pod::Text::Overstrike - Convert POD data to formatted overstrike text"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::Text::Termcap \- Convert POD data to ASCII text with format escapes"
+.IX Subsection "Pod::Text::Termcap - Convert POD data to ASCII text with format escapes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Pod::Usage \- extracts POD documentation and shows usage information"
+.IX Subsection "Pod::Usage - extracts POD documentation and shows usage information"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP ARGUMENTS 4
+.IX Item "ARGUMENTS"
+.PD
+\&\f(CW\*(C`\-message\*(C'\fR \fIstring\fR, \f(CW\*(C`\-msg\*(C'\fR \fIstring\fR, \f(CW\*(C`\-exitval\*(C'\fR \fIvalue\fR, \f(CW\*(C`\-verbose\*(C'\fR
+\&\fIvalue\fR, \f(CW\*(C`\-sections\*(C'\fR \fIspec\fR, \f(CW\*(C`\-output\*(C'\fR \fIhandle\fR, \f(CW\*(C`\-input\*(C'\fR \fIhandle\fR,
+\&\f(CW\*(C`\-pathlist\*(C'\fR \fIstring\fR, \f(CW\*(C`\-noperldoc\*(C'\fR, \f(CW\*(C`\-perlcmd\*(C'\fR, \f(CW\*(C`\-perldoc\*(C'\fR
+\&\fIpath-to-perldoc\fR, \f(CW\*(C`\-perldocopt\*(C'\fR \fIstring\fR
+.RS 4
+.IP "Formatting base class" 4
+.IX Item "Formatting base class"
+.PD 0
+.IP "Pass-through options" 4
+.IX Item "Pass-through options"
+.RE
+.RS 4
+.RE
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Scripts 4
+.IX Item "Scripts"
+.RE
+.RS 4
+.RE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.IP "Recommended Use" 4
+.IX Item "Recommended Use"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP ACKNOWLEDGMENTS 4
+.IX Item "ACKNOWLEDGMENTS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "SDBM_File \- Tied access to sdbm files"
+.IX Subsection "SDBM_File - Tied access to sdbm files"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Tie 4
+.IX Item "Tie"
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.RS 4
+.ie n .IP """sdbm store returned \-1, errno 22, key ""..."" at ...""" 4
+.el .IP "\f(CWsdbm store returned \-1, errno 22, key ""..."" at ...\fR" 4
+.IX Item "sdbm store returned -1, errno 22, key ""..."" at ..."
+.RE
+.RS 4
+.RE
+.IP "SECURITY WARNING" 4
+.IX Item "SECURITY WARNING"
+.IP "BUGS AND WARNINGS" 4
+.IX Item "BUGS AND WARNINGS"
+.PD
+.SS "Safe \- Compile and execute code in restricted compartments"
+.IX Subsection "Safe - Compile and execute code in restricted compartments"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+a new namespace, an operator mask
+.IP WARNING 4
+.IX Item "WARNING"
+.PD 0
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "permit (OP, ...)" 4
+.IX Item "permit (OP, ...)"
+.IP "permit_only (OP, ...)" 4
+.IX Item "permit_only (OP, ...)"
+.IP "deny (OP, ...)" 4
+.IX Item "deny (OP, ...)"
+.IP "deny_only (OP, ...)" 4
+.IX Item "deny_only (OP, ...)"
+.IP "trap (OP, ...), untrap (OP, ...)" 4
+.IX Item "trap (OP, ...), untrap (OP, ...)"
+.IP "share (NAME, ...)" 4
+.IX Item "share (NAME, ...)"
+.IP "share_from (PACKAGE, ARRAYREF)" 4
+.IX Item "share_from (PACKAGE, ARRAYREF)"
+.IP "varglob (VARNAME)" 4
+.IX Item "varglob (VARNAME)"
+.IP "reval (STRING, STRICT)" 4
+.IX Item "reval (STRING, STRICT)"
+.IP "rdo (FILENAME)" 4
+.IX Item "rdo (FILENAME)"
+.IP "root (NAMESPACE)" 4
+.IX Item "root (NAMESPACE)"
+.IP "mask (MASK)" 4
+.IX Item "mask (MASK)"
+.IP "wrap_code_ref (CODEREF)" 4
+.IX Item "wrap_code_ref (CODEREF)"
+.IP "wrap_code_refs_within (...)" 4
+.IX Item "wrap_code_refs_within (...)"
+.RE
+.RS 4
+.RE
+.IP RISKS 4
+.IX Item "RISKS"
+.PD
+Memory, CPU, Snooping, Signals, State Changes
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.SS "Scalar::Util \- A selection of general-utility scalar subroutines"
+.IX Subsection "Scalar::Util - A selection of general-utility scalar subroutines"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "Core Perl ""builtin"" Functions" 4
+.el .IP "Core Perl \f(CWbuiltin\fR Functions" 4
+.IX Item "Core Perl builtin Functions"
+.RE
+.RS 4
+.RE
+.IP "FUNCTIONS FOR REFERENCES" 4
+.IX Item "FUNCTIONS FOR REFERENCES"
+.RS 4
+.IP blessed 4
+.IX Item "blessed"
+.IP refaddr 4
+.IX Item "refaddr"
+.IP reftype 4
+.IX Item "reftype"
+.IP weaken 4
+.IX Item "weaken"
+.IP unweaken 4
+.IX Item "unweaken"
+.IP isweak 4
+.IX Item "isweak"
+.RE
+.RS 4
+.RE
+.IP "OTHER FUNCTIONS" 4
+.IX Item "OTHER FUNCTIONS"
+.RS 4
+.IP dualvar 4
+.IX Item "dualvar"
+.IP isdual 4
+.IX Item "isdual"
+.IP isvstring 4
+.IX Item "isvstring"
+.IP looks_like_number 4
+.IX Item "looks_like_number"
+.IP openhandle 4
+.IX Item "openhandle"
+.IP readonly 4
+.IX Item "readonly"
+.IP set_prototype 4
+.IX Item "set_prototype"
+.IP tainted 4
+.IX Item "tainted"
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+Vstrings are not implemented in this version of perl
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Search::Dict \- look \- search for key in dictionary file"
+.IX Subsection "Search::Dict - look - search for key in dictionary file"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "SelectSaver \- save and restore selected file handle"
+.IX Subsection "SelectSaver - save and restore selected file handle"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "SelfLoader \- load functions only on demand"
+.IX Subsection "SelfLoader - load functions only on demand"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "The _\|_DATA_\|_ token" 4
+.IX Item "The __DATA__ token"
+.IP "SelfLoader autoloading" 4
+.IX Item "SelfLoader autoloading"
+.IP "Autoloading and package lexicals" 4
+.IX Item "Autoloading and package lexicals"
+.IP "SelfLoader and AutoLoader" 4
+.IX Item "SelfLoader and AutoLoader"
+.IP "_\|_DATA_\|_, _\|_END_\|_, and the FOOBAR::DATA filehandle." 4
+.IX Item "__DATA__, __END__, and the FOOBAR::DATA filehandle."
+.IP "Classes and inherited methods." 4
+.IX Item "Classes and inherited methods."
+.RE
+.RS 4
+.RE
+.IP "Multiple packages and fully qualified subroutine names" 4
+.IX Item "Multiple packages and fully qualified subroutine names"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+a), b)
+.ie n .SS "Socket, ""Socket"" \- networking constants and support functions"
+.el .SS "Socket, \f(CWSocket\fP \- networking constants and support functions"
+.IX Subsection "Socket, Socket - networking constants and support functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CONSTANTS 4
+.IX Item "CONSTANTS"
+.IP "PF_INET, PF_INET6, PF_UNIX, ..." 4
+.IX Item "PF_INET, PF_INET6, PF_UNIX, ..."
+.IP "AF_INET, AF_INET6, AF_UNIX, ..." 4
+.IX Item "AF_INET, AF_INET6, AF_UNIX, ..."
+.IP "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..." 4
+.IX Item "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..."
+.IP "SOCK_NONBLOCK. SOCK_CLOEXEC" 4
+.IX Item "SOCK_NONBLOCK. SOCK_CLOEXEC"
+.IP SOL_SOCKET 4
+.IX Item "SOL_SOCKET"
+.IP "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..." 4
+.IX Item "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..."
+.IP "IP_OPTIONS, IP_TOS, IP_TTL, ..." 4
+.IX Item "IP_OPTIONS, IP_TOS, IP_TTL, ..."
+.IP "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..." 4
+.IX Item "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..."
+.IP "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..." 4
+.IX Item "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..."
+.IP "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..." 4
+.IX Item "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..."
+.IP "SHUT_RD, SHUT_RDWR, SHUT_WR" 4
+.IX Item "SHUT_RD, SHUT_RDWR, SHUT_WR"
+.IP "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE" 4
+.IX Item "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE"
+.IP "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..." 4
+.IX Item "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..."
+.IP "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..." 4
+.IX Item "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..."
+.IP "IN6ADDR_ANY, IN6ADDR_LOOPBACK" 4
+.IX Item "IN6ADDR_ANY, IN6ADDR_LOOPBACK"
+.IP "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..." 4
+.IX Item "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..."
+.IP "STRUCTURE MANIPULATORS" 4
+.IX Item "STRUCTURE MANIPULATORS"
+.ie n .IP "$family = sockaddr_family $sockaddr" 4
+.el .IP "\f(CW$family\fR = sockaddr_family \f(CW$sockaddr\fR" 4
+.IX Item "$family = sockaddr_family $sockaddr"
+.ie n .IP "$sockaddr = pack_sockaddr_in $port, $ip_address" 4
+.el .IP "\f(CW$sockaddr\fR = pack_sockaddr_in \f(CW$port\fR, \f(CW$ip_address\fR" 4
+.IX Item "$sockaddr = pack_sockaddr_in $port, $ip_address"
+.ie n .IP "($port, $ip_address) = unpack_sockaddr_in $sockaddr" 4
+.el .IP "($port, \f(CW$ip_address\fR) = unpack_sockaddr_in \f(CW$sockaddr\fR" 4
+.IX Item "($port, $ip_address) = unpack_sockaddr_in $sockaddr"
+.ie n .IP "$sockaddr = sockaddr_in $port, $ip_address" 4
+.el .IP "\f(CW$sockaddr\fR = sockaddr_in \f(CW$port\fR, \f(CW$ip_address\fR" 4
+.IX Item "$sockaddr = sockaddr_in $port, $ip_address"
+.ie n .IP "($port, $ip_address) = sockaddr_in $sockaddr" 4
+.el .IP "($port, \f(CW$ip_address\fR) = sockaddr_in \f(CW$sockaddr\fR" 4
+.IX Item "($port, $ip_address) = sockaddr_in $sockaddr"
+.ie n .IP "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" 4
+.el .IP "\f(CW$sockaddr\fR = pack_sockaddr_in6 \f(CW$port\fR, \f(CW$ip6_address\fR, [$scope_id, [$flowinfo]]" 4
+.IX Item "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]"
+.ie n .IP "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr" 4
+.el .IP "($port, \f(CW$ip6_address\fR, \f(CW$scope_id\fR, \f(CW$flowinfo\fR) = unpack_sockaddr_in6 \f(CW$sockaddr\fR" 4
+.IX Item "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr"
+.ie n .IP "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" 4
+.el .IP "\f(CW$sockaddr\fR = sockaddr_in6 \f(CW$port\fR, \f(CW$ip6_address\fR, [$scope_id, [$flowinfo]]" 4
+.IX Item "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]"
+.ie n .IP "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr" 4
+.el .IP "($port, \f(CW$ip6_address\fR, \f(CW$scope_id\fR, \f(CW$flowinfo\fR) = sockaddr_in6 \f(CW$sockaddr\fR" 4
+.IX Item "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr"
+.ie n .IP "$sockaddr = pack_sockaddr_un $path" 4
+.el .IP "\f(CW$sockaddr\fR = pack_sockaddr_un \f(CW$path\fR" 4
+.IX Item "$sockaddr = pack_sockaddr_un $path"
+.ie n .IP "($path) = unpack_sockaddr_un $sockaddr" 4
+.el .IP "($path) = unpack_sockaddr_un \f(CW$sockaddr\fR" 4
+.IX Item "($path) = unpack_sockaddr_un $sockaddr"
+.ie n .IP "$sockaddr = sockaddr_un $path" 4
+.el .IP "\f(CW$sockaddr\fR = sockaddr_un \f(CW$path\fR" 4
+.IX Item "$sockaddr = sockaddr_un $path"
+.ie n .IP "($path) = sockaddr_un $sockaddr" 4
+.el .IP "($path) = sockaddr_un \f(CW$sockaddr\fR" 4
+.IX Item "($path) = sockaddr_un $sockaddr"
+.ie n .IP "$ip_mreq = pack_ip_mreq $multiaddr, $interface" 4
+.el .IP "\f(CW$ip_mreq\fR = pack_ip_mreq \f(CW$multiaddr\fR, \f(CW$interface\fR" 4
+.IX Item "$ip_mreq = pack_ip_mreq $multiaddr, $interface"
+.ie n .IP "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq" 4
+.el .IP "($multiaddr, \f(CW$interface\fR) = unpack_ip_mreq \f(CW$ip_mreq\fR" 4
+.IX Item "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq"
+.ie n .IP "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface" 4
+.el .IP "\f(CW$ip_mreq_source\fR = pack_ip_mreq_source \f(CW$multiaddr\fR, \f(CW$source\fR, \f(CW$interface\fR" 4
+.IX Item "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface"
+.ie n .IP "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq" 4
+.el .IP "($multiaddr, \f(CW$source\fR, \f(CW$interface\fR) = unpack_ip_mreq_source \f(CW$ip_mreq\fR" 4
+.IX Item "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq"
+.ie n .IP "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex" 4
+.el .IP "\f(CW$ipv6_mreq\fR = pack_ipv6_mreq \f(CW$multiaddr6\fR, \f(CW$ifindex\fR" 4
+.IX Item "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex"
+.ie n .IP "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq" 4
+.el .IP "($multiaddr6, \f(CW$ifindex\fR) = unpack_ipv6_mreq \f(CW$ipv6_mreq\fR" 4
+.IX Item "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.ie n .IP "$ip_address = inet_aton $string" 4
+.el .IP "\f(CW$ip_address\fR = inet_aton \f(CW$string\fR" 4
+.IX Item "$ip_address = inet_aton $string"
+.ie n .IP "$string = inet_ntoa $ip_address" 4
+.el .IP "\f(CW$string\fR = inet_ntoa \f(CW$ip_address\fR" 4
+.IX Item "$string = inet_ntoa $ip_address"
+.ie n .IP "$address = inet_pton $family, $string" 4
+.el .IP "\f(CW$address\fR = inet_pton \f(CW$family\fR, \f(CW$string\fR" 4
+.IX Item "$address = inet_pton $family, $string"
+.ie n .IP "$string = inet_ntop $family, $address" 4
+.el .IP "\f(CW$string\fR = inet_ntop \f(CW$family\fR, \f(CW$address\fR" 4
+.IX Item "$string = inet_ntop $family, $address"
+.ie n .IP "($err, @result) = getaddrinfo $host, $service, [$hints]" 4
+.el .IP "($err, \f(CW@result\fR) = getaddrinfo \f(CW$host\fR, \f(CW$service\fR, [$hints]" 4
+.IX Item "($err, @result) = getaddrinfo $host, $service, [$hints]"
+.PD
+flags => INT, family => INT, socktype => INT, protocol => INT, family =>
+INT, socktype => INT, protocol => INT, addr => STRING, canonname => STRING,
+AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST
+.ie n .IP "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]" 4
+.el .IP "($err, \f(CW$hostname\fR, \f(CW$servicename\fR) = getnameinfo \f(CW$sockaddr\fR, [$flags, [$xflags]]" 4
+.IX Item "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]"
+NI_NUMERICHOST, NI_NUMERICSERV, NI_NAMEREQD, NI_DGRAM, NIx_NOHOST,
+NIx_NOSERV
+.IP "\fBgetaddrinfo()\fR / \fBgetnameinfo()\fR ERROR CONSTANTS" 4
+.IX Item "getaddrinfo() / getnameinfo() ERROR CONSTANTS"
+EAI_AGAIN, EAI_BADFLAGS, EAI_FAMILY, EAI_NODATA, EAI_NONAME, EAI_SERVICE
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.RS 4
+.PD 0
+.IP "Lookup for \fBconnect()\fR" 4
+.IX Item "Lookup for connect()"
+.IP "Making a human-readable string out of an address" 4
+.IX Item "Making a human-readable string out of an address"
+.IP "Resolving hostnames into IP addresses" 4
+.IX Item "Resolving hostnames into IP addresses"
+.IP "Accessing socket options" 4
+.IX Item "Accessing socket options"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Storable \- persistence for Perl data structures"
+.IX Subsection "Storable - persistence for Perl data structures"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "MEMORY STORE" 4
+.IX Item "MEMORY STORE"
+.IP "ADVISORY LOCKING" 4
+.IX Item "ADVISORY LOCKING"
+.IP SPEED 4
+.IX Item "SPEED"
+.IP "CANONICAL REPRESENTATION" 4
+.IX Item "CANONICAL REPRESENTATION"
+.IP "CODE REFERENCES" 4
+.IX Item "CODE REFERENCES"
+.IP "FORWARD COMPATIBILITY" 4
+.IX Item "FORWARD COMPATIBILITY"
+.PD
+utf8 data, restricted hashes, huge objects, files from future versions of
+Storable
+.IP "ERROR REPORTING" 4
+.IX Item "ERROR REPORTING"
+.PD 0
+.IP "WIZARDS ONLY" 4
+.IX Item "WIZARDS ONLY"
+.RS 4
+.IP Hooks 4
+.IX Item "Hooks"
+.PD
+\&\f(CW\*(C`STORABLE_freeze\*(C'\fR \fIobj\fR, \fIcloning\fR, \f(CW\*(C`STORABLE_thaw\*(C'\fR \fIobj\fR, \fIcloning\fR,
+\&\fIserialized\fR, .., \f(CW\*(C`STORABLE_attach\*(C'\fR \fIclass\fR, \fIcloning\fR, \fIserialized\fR
+.IP Predicates 4
+.IX Item "Predicates"
+\&\f(CW\*(C`Storable::last_op_in_netorder\*(C'\fR, \f(CW\*(C`Storable::is_storing\*(C'\fR,
+\&\f(CW\*(C`Storable::is_retrieving\*(C'\fR
+.IP Recursion 4
+.IX Item "Recursion"
+.PD 0
+.IP "Deep Cloning" 4
+.IX Item "Deep Cloning"
+.RE
+.RS 4
+.RE
+.IP "Storable magic" 4
+.IX Item "Storable magic"
+.PD
+\&\f(CW$info\fR = Storable::file_magic( \f(CW$filename\fR ), \f(CW\*(C`version\*(C'\fR, \f(CW\*(C`version_nv\*(C'\fR,
+\&\f(CW\*(C`major\*(C'\fR, \f(CW\*(C`minor\*(C'\fR, \f(CW\*(C`hdrsize\*(C'\fR, \f(CW\*(C`netorder\*(C'\fR, \f(CW\*(C`byteorder\*(C'\fR, \f(CW\*(C`intsize\*(C'\fR,
+\&\f(CW\*(C`longsize\*(C'\fR, \f(CW\*(C`ptrsize\*(C'\fR, \f(CW\*(C`nvsize\*(C'\fR, \f(CW\*(C`file\*(C'\fR, \f(CW$info\fR = Storable::read_magic(
+\&\f(CW$buffer\fR ), \f(CW$info\fR = Storable::read_magic( \f(CW$buffer\fR, \f(CW$must_be_file\fR )
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP "SECURITY WARNING" 4
+.IX Item "SECURITY WARNING"
+.IP WARNING 4
+.IX Item "WARNING"
+.IP "REGULAR EXPRESSIONS" 4
+.IX Item "REGULAR EXPRESSIONS"
+.IP BUGS 4
+.IX Item "BUGS"
+.RS 4
+.IP "64 bit data in perl 5.6.0 and 5.6.1" 4
+.IX Item "64 bit data in perl 5.6.0 and 5.6.1"
+.RE
+.RS 4
+.RE
+.IP CREDITS 4
+.IX Item "CREDITS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Sub::Util \- A selection of utility subroutines for subs and CODE references"
+.IX Subsection "Sub::Util - A selection of utility subroutines for subs and CODE references"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.IP prototype 4
+.IX Item "prototype"
+.IP set_prototype 4
+.IX Item "set_prototype"
+.IP subname 4
+.IX Item "subname"
+.IP set_subname 4
+.IX Item "set_subname"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Symbol \- manipulate Perl symbols and their names"
+.IX Subsection "Symbol - manipulate Perl symbols and their names"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+.SS "Sys::Hostname \- Try every conceivable way to get hostname"
+.IX Subsection "Sys::Hostname - Try every conceivable way to get hostname"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Sys::Syslog \- Perl interface to the UNIX \fBsyslog\fP\|(3) calls"
+.IX Subsection "Sys::Syslog - Perl interface to the UNIX syslog calls"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\fBopenlog($ident, \fR\f(CB$logopt\fR\fB, \fR\f(CB$facility\fR\fB)\fR, \fBsyslog($priority, \fR\f(CB$message\fR\fB)\fR,
+\&\fBsyslog($priority, \fR\f(CB$format\fR\fB, \fR\f(CB@args\fR\fB)\fR, \fBNote\fR,
+\&\fBsetlogmask($mask_priority)\fR, \fBsetlogsock()\fR, \fBNote\fR, \fBcloselog()\fR
+.IP "THE RULES OF SYS::SYSLOG" 4
+.IX Item "THE RULES OF SYS::SYSLOG"
+.PD 0
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP CONSTANTS 4
+.IX Item "CONSTANTS"
+.RS 4
+.IP Facilities 4
+.IX Item "Facilities"
+.IP Levels 4
+.IX Item "Levels"
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+\&\f(CW\*(C`Invalid argument passed to setlogsock\*(C'\fR, \f(CW\*(C`eventlog passed to setlogsock,
+but no Win32 API available\*(C'\fR, \f(CW\*(C`no connection to syslog available\*(C'\fR, \f(CW\*(C`stream
+passed to setlogsock, but %s is not writable\*(C'\fR, \f(CW\*(C`stream passed to
+setlogsock, but could not find any device\*(C'\fR, \f(CW\*(C`tcp passed to setlogsock, but
+tcp service unavailable\*(C'\fR, \f(CW\*(C`syslog: expecting argument %s\*(C'\fR, \f(CW\*(C`syslog:
+invalid level/facility: %s\*(C'\fR, \f(CW\*(C`syslog: too many levels given: %s\*(C'\fR,
+\&\f(CW\*(C`syslog: too many facilities given: %s\*(C'\fR, \f(CW\*(C`syslog: level must be given\*(C'\fR,
+\&\f(CW\*(C`udp passed to setlogsock, but udp service unavailable\*(C'\fR, \f(CW\*(C`unix passed to
+setlogsock, but path not available\*(C'\fR
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP "Other modules" 4
+.IX Item "Other modules"
+.IP "Manual Pages" 4
+.IX Item "Manual Pages"
+.IP RFCs 4
+.IX Item "RFCs"
+.IP Articles 4
+.IX Item "Articles"
+.IP "Event Log" 4
+.IX Item "Event Log"
+.RE
+.RS 4
+.RE
+.IP "AUTHORS & ACKNOWLEDGEMENTS" 4
+.IX Item "AUTHORS & ACKNOWLEDGEMENTS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.PD
+Perl Documentation, MetaCPAN, Search CPAN, AnnoCPAN: Annotated CPAN
+documentation, CPAN Ratings, RT: CPAN's request tracker
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "TAP::Base \- Base class that provides common functionality to TAP::Parser and TAP::Harness"
+.IX Subsection "TAP::Base - Base class that provides common functionality to TAP::Parser and TAP::Harness"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Formatter::Base \- Base class for harness output delegates"
+.IX Subsection "TAP::Formatter::Base - Base class for harness output delegates"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`verbosity\*(C'\fR, \f(CW\*(C`verbose\*(C'\fR, \f(CW\*(C`timer\*(C'\fR, \f(CW\*(C`failures\*(C'\fR, \f(CW\*(C`comments\*(C'\fR, \f(CW\*(C`quiet\*(C'\fR,
+\&\f(CW\*(C`really_quiet\*(C'\fR, \f(CW\*(C`silent\*(C'\fR, \f(CW\*(C`errors\*(C'\fR, \f(CW\*(C`directives\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`color\*(C'\fR,
+\&\f(CW\*(C`jobs\*(C'\fR, \f(CW\*(C`show_count\*(C'\fR
+.RE
+.RS 4
+.RE
+.SS "TAP::Formatter::Color \- Run Perl test scripts with color"
+.IX Subsection "TAP::Formatter::Color - Run Perl test scripts with color"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Formatter::Console \- Harness output delegate for default console output"
+.IX Subsection "TAP::Formatter::Console - Harness output delegate for default console output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.ie n .IP """open_test""" 4
+.el .IP \f(CWopen_test\fR 4
+.IX Item "open_test"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Formatter::Console::ParallelSession \- Harness output delegate for parallel console output"
+.IX Subsection "TAP::Formatter::Console::ParallelSession - Harness output delegate for parallel console output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Formatter::Console::Session \- Harness output delegate for default console output"
+.IX Subsection "TAP::Formatter::Console::Session - Harness output delegate for default console output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.ie n .IP """clear_for_close""" 4
+.el .IP \f(CWclear_for_close\fR 4
+.IX Item "clear_for_close"
+.ie n .IP """close_test""" 4
+.el .IP \f(CWclose_test\fR 4
+.IX Item "close_test"
+.ie n .IP """header""" 4
+.el .IP \f(CWheader\fR 4
+.IX Item "header"
+.ie n .IP """result""" 4
+.el .IP \f(CWresult\fR 4
+.IX Item "result"
+.PD
+.SS "TAP::Formatter::File \- Harness output delegate for file output"
+.IX Subsection "TAP::Formatter::File - Harness output delegate for file output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.ie n .IP """open_test""" 4
+.el .IP \f(CWopen_test\fR 4
+.IX Item "open_test"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Formatter::File::Session \- Harness output delegate for file output"
+.IX Subsection "TAP::Formatter::File::Session - Harness output delegate for file output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP result 4
+.IX Item "result"
+.RE
+.RS 4
+.RE
+.IP close_test 4
+.IX Item "close_test"
+.PD
+.SS "TAP::Formatter::Session \- Abstract base class for harness output delegate"
+.IX Subsection "TAP::Formatter::Session - Abstract base class for harness output delegate"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`formatter\*(C'\fR, \f(CW\*(C`parser\*(C'\fR, \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`show_count\*(C'\fR
+.RE
+.RS 4
+.RE
+.SS "TAP::Harness \- Run test scripts with statistics"
+.IX Subsection "TAP::Harness - Run test scripts with statistics"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`verbosity\*(C'\fR, \f(CW\*(C`timer\*(C'\fR, \f(CW\*(C`failures\*(C'\fR, \f(CW\*(C`comments\*(C'\fR, \f(CW\*(C`show_count\*(C'\fR,
+\&\f(CW\*(C`normalize\*(C'\fR, \f(CW\*(C`lib\*(C'\fR, \f(CW\*(C`switches\*(C'\fR, \f(CW\*(C`test_args\*(C'\fR, \f(CW\*(C`color\*(C'\fR, \f(CW\*(C`exec\*(C'\fR,
+\&\f(CW\*(C`merge\*(C'\fR, \f(CW\*(C`sources\*(C'\fR, \f(CW\*(C`aggregator_class\*(C'\fR, \f(CW\*(C`version\*(C'\fR, \f(CW\*(C`formatter_class\*(C'\fR,
+\&\f(CW\*(C`multiplexer_class\*(C'\fR, \f(CW\*(C`parser_class\*(C'\fR, \f(CW\*(C`scheduler_class\*(C'\fR, \f(CW\*(C`formatter\*(C'\fR,
+\&\f(CW\*(C`errors\*(C'\fR, \f(CW\*(C`directives\*(C'\fR, \f(CW\*(C`ignore_exit\*(C'\fR, \f(CW\*(C`jobs\*(C'\fR, \f(CW\*(C`rules\*(C'\fR, \f(CW\*(C`rulesfiles\*(C'\fR,
+\&\f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`trap\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PP
+the source name of a test to run, a reference to a [ source name, display
+name ] array
+.IP CONFIGURING 4
+.IX Item "CONFIGURING"
+.RS 4
+.PD 0
+.IP Plugins 4
+.IX Item "Plugins"
+.ie n .IP """Module::Build""" 4
+.el .IP \f(CWModule::Build\fR 4
+.IX Item "Module::Build"
+.ie n .IP """ExtUtils::MakeMaker""" 4
+.el .IP \f(CWExtUtils::MakeMaker\fR 4
+.IX Item "ExtUtils::MakeMaker"
+.ie n .IP """prove""" 4
+.el .IP \f(CWprove\fR 4
+.IX Item "prove"
+.RE
+.RS 4
+.RE
+.IP "WRITING PLUGINS" 4
+.IX Item "WRITING PLUGINS"
+.PD
+Customize how TAP gets into the parser, Customize how TAP results are
+output from the parser
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.PD 0
+.IP Methods 4
+.IX Item "Methods"
+.PD
+"new" in TAP::Harness, "runtests" in TAP::Harness, "summary" in TAP::Harness
+.RE
+.RS 4
+.RE
+.IP REPLACING 4
+.IX Item "REPLACING"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Harness::Beyond, Test::Harness::Beyond \- Beyond make test"
+.IX Subsection "TAP::Harness::Beyond, Test::Harness::Beyond - Beyond make test"
+.IP "Beyond make test" 4
+.IX Item "Beyond make test"
+.RS 4
+.PD 0
+.IP "Saved State" 4
+.IX Item "Saved State"
+.IP "Parallel Testing" 4
+.IX Item "Parallel Testing"
+.IP "Non-Perl Tests" 4
+.IX Item "Non-Perl Tests"
+.IP "Mixing it up" 4
+.IX Item "Mixing it up"
+.IP "Rolling My Own" 4
+.IX Item "Rolling My Own"
+.IP "Deeper Customisation" 4
+.IX Item "Deeper Customisation"
+.IP Callbacks 4
+.IX Item "Callbacks"
+.IP "Parsing TAP" 4
+.IX Item "Parsing TAP"
+.IP "Getting Support" 4
+.IX Item "Getting Support"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Harness::Env \- Parsing harness related environmental variables where appropriate"
+.IX Subsection "TAP::Harness::Env - Parsing harness related environmental variables where appropriate"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+create( \e%args )
+.IP "ENVIRONMENTAL VARIABLES" 4
+.IX Item "ENVIRONMENTAL VARIABLES"
+\&\f(CW\*(C`HARNESS_PERL_SWITCHES\*(C'\fR, \f(CW\*(C`HARNESS_VERBOSE\*(C'\fR, \f(CW\*(C`HARNESS_SUBCLASS\*(C'\fR,
+\&\f(CW\*(C`HARNESS_OPTIONS\*(C'\fR, \f(CW\*(C`j<n>\*(C'\fR, \f(CW\*(C`c\*(C'\fR, \f(CW\*(C`a<file.tgz>\*(C'\fR, \f(CW\*(C`fPackage\-With\-Dashes\*(C'\fR, \f(CW\*(C`HARNESS_TIMER\*(C'\fR, \f(CW\*(C`HARNESS_COLOR\*(C'\fR,
+\&\f(CW\*(C`HARNESS_IGNORE_EXIT\*(C'\fR
+.ie n .SS "TAP::Object \- Base class that provides common functionality to all ""TAP::*"" modules"
+.el .SS "TAP::Object \- Base class that provides common functionality to all \f(CWTAP::*\fP modules"
+.IX Subsection "TAP::Object - Base class that provides common functionality to all TAP::* modules"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PD
+.SS "TAP::Parser \- Parse TAP output"
+.IX Subsection "TAP::Parser - Parse TAP output"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.PD
+\&\f(CW\*(C`source\*(C'\fR, \f(CW\*(C`tap\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`sources\*(C'\fR, \f(CW\*(C`callback\*(C'\fR, \f(CW\*(C`switches\*(C'\fR,
+\&\f(CW\*(C`test_args\*(C'\fR, \f(CW\*(C`spool\*(C'\fR, \f(CW\*(C`merge\*(C'\fR, \f(CW\*(C`grammar_class\*(C'\fR,
+\&\f(CW\*(C`result_factory_class\*(C'\fR, \f(CW\*(C`iterator_factory_class\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PD 0
+.IP "INDIVIDUAL RESULTS" 4
+.IX Item "INDIVIDUAL RESULTS"
+.RS 4
+.IP "Result types" 4
+.IX Item "Result types"
+.PD
+Version, Plan, Pragma, Test, Comment, Bailout, Unknown
+.IP "Common type methods" 4
+.IX Item "Common type methods"
+.PD 0
+.ie n .IP """plan"" methods" 4
+.el .IP "\f(CWplan\fR methods" 4
+.IX Item "plan methods"
+.ie n .IP """pragma"" methods" 4
+.el .IP "\f(CWpragma\fR methods" 4
+.IX Item "pragma methods"
+.ie n .IP """comment"" methods" 4
+.el .IP "\f(CWcomment\fR methods" 4
+.IX Item "comment methods"
+.ie n .IP """bailout"" methods" 4
+.el .IP "\f(CWbailout\fR methods" 4
+.IX Item "bailout methods"
+.ie n .IP """unknown"" methods" 4
+.el .IP "\f(CWunknown\fR methods" 4
+.IX Item "unknown methods"
+.ie n .IP """test"" methods" 4
+.el .IP "\f(CWtest\fR methods" 4
+.IX Item "test methods"
+.RE
+.RS 4
+.RE
+.IP "TOTAL RESULTS" 4
+.IX Item "TOTAL RESULTS"
+.RS 4
+.IP "Individual Results" 4
+.IX Item "Individual Results"
+.RE
+.RS 4
+.RE
+.IP Pragmas 4
+.IX Item "Pragmas"
+.IP "Summary Results" 4
+.IX Item "Summary Results"
+.ie n .IP """ignore_exit""" 4
+.el .IP \f(CWignore_exit\fR 4
+.IX Item "ignore_exit"
+.PD
+.PP
+Misplaced plan, No plan, More than one plan, Test numbers out of sequence
+.IP CALLBACKS 4
+.IX Item "CALLBACKS"
+\&\f(CW\*(C`test\*(C'\fR, \f(CW\*(C`version\*(C'\fR, \f(CW\*(C`plan\*(C'\fR, \f(CW\*(C`comment\*(C'\fR, \f(CW\*(C`bailout\*(C'\fR, \f(CW\*(C`yaml\*(C'\fR, \f(CW\*(C`unknown\*(C'\fR,
+\&\f(CW\*(C`ELSE\*(C'\fR, \f(CW\*(C`ALL\*(C'\fR, \f(CW\*(C`EOF\*(C'\fR
+.IP "TAP GRAMMAR" 4
+.IX Item "TAP GRAMMAR"
+.PD 0
+.IP "BACKWARDS COMPATIBILITY" 4
+.IX Item "BACKWARDS COMPATIBILITY"
+.RS 4
+.IP Differences 4
+.IX Item "Differences"
+.PD
+TODO plans, 'Missing' tests
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.PD 0
+.IP "Parser Components" 4
+.IX Item "Parser Components"
+.PD
+option 1, option 2
+.RE
+.RS 4
+.RE
+.IP ACKNOWLEDGMENTS 4
+.IX Item "ACKNOWLEDGMENTS"
+Michael Schwern, Andy Lester, chromatic, GEOFFR, Shlomi Fish, Torsten
+Schoenfeld, Jerry Gay, Aristotle, Adam Kennedy, Yves Orton, Adrian Howard,
+Sean & Lil, Andreas J. Koenig, Florian Ragwitz, Corion, Mark Stosberg, Matt
+Kraai, David Wheeler, Alex Vandiver, Cosimo Streppone, Ville Skyttä
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SS "TAP::Parser::Aggregator \- Aggregate TAP::Parser results"
+.IX Subsection "TAP::Parser::Aggregator - Aggregate TAP::Parser results"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP "Summary methods" 4
+.IX Item "Summary methods"
+.PD
+failed, parse_errors, passed, planned, skipped, todo, todo_passed, wait,
+exit
+.PP
+Failed tests, Parse errors, Bad exit or wait status
+.IP "See Also" 4
+.IX Item "See Also"
+.SS "TAP::Parser::Grammar \- A grammar for the Test Anything Protocol."
+.IX Subsection "TAP::Parser::Grammar - A grammar for the Test Anything Protocol."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP "TAP GRAMMAR" 4
+.IX Item "TAP GRAMMAR"
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Iterator \- Base class for TAP source iterators"
+.IX Subsection "TAP::Parser::Iterator - Base class for TAP source iterators"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Iterator::Array \- Iterator for array-based TAP sources"
+.IX Subsection "TAP::Parser::Iterator::Array - Iterator for array-based TAP sources"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.RE
+.RS 4
+.RE
+.IP ATTRIBUTION 4
+.IX Item "ATTRIBUTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Iterator::Process \- Iterator for process-based TAP sources"
+.IX Subsection "TAP::Parser::Iterator::Process - Iterator for process-based TAP sources"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.RE
+.RS 4
+.RE
+.IP ATTRIBUTION 4
+.IX Item "ATTRIBUTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Iterator::Stream \- Iterator for filehandle-based TAP sources"
+.IX Subsection "TAP::Parser::Iterator::Stream - Iterator for filehandle-based TAP sources"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP ATTRIBUTION 4
+.IX Item "ATTRIBUTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::IteratorFactory \- Figures out which SourceHandler objects to use for a given Source"
+.IX Subsection "TAP::Parser::IteratorFactory - Figures out which SourceHandler objects to use for a given Source"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP ATTRIBUTION 4
+.IX Item "ATTRIBUTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Multiplexer \- Multiplex multiple TAP::Parsers"
+.IX Subsection "TAP::Parser::Multiplexer - Multiplex multiple TAP::Parsers"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP "See Also" 4
+.IX Item "See Also"
+.PD
+.SS "TAP::Parser::Result \- Base class for TAP::Parser output objects"
+.IX Subsection "TAP::Parser::Result - Base class for TAP::Parser output objects"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RE
+.RS 4
+.RE
+.IP "Boolean methods" 4
+.IX Item "Boolean methods"
+.PD
+\&\f(CW\*(C`is_plan\*(C'\fR, \f(CW\*(C`is_pragma\*(C'\fR, \f(CW\*(C`is_test\*(C'\fR, \f(CW\*(C`is_comment\*(C'\fR, \f(CW\*(C`is_bailout\*(C'\fR,
+\&\f(CW\*(C`is_version\*(C'\fR, \f(CW\*(C`is_unknown\*(C'\fR, \f(CW\*(C`is_yaml\*(C'\fR
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.PD 0
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Result::Bailout \- Bailout result token."
+.IX Subsection "TAP::Parser::Result::Bailout - Bailout result token."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Result::Comment \- Comment result token."
+.IX Subsection "TAP::Parser::Result::Comment - Comment result token."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Result::Plan \- Plan result token."
+.IX Subsection "TAP::Parser::Result::Plan - Plan result token."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`raw\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Result::Pragma \- TAP pragma token."
+.IX Subsection "TAP::Parser::Result::Pragma - TAP pragma token."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`raw\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Result::Test \- Test result token."
+.IX Subsection "TAP::Parser::Result::Test - Test result token."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.RS 4
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.RE
+.RS 4
+.RE
+.PD
+.SS "TAP::Parser::Result::Unknown \- Unknown result token."
+.IX Subsection "TAP::Parser::Result::Unknown - Unknown result token."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`raw\*(C'\fR
+.SS "TAP::Parser::Result::Version \- TAP syntax version token."
+.IX Subsection "TAP::Parser::Result::Version - TAP syntax version token."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`raw\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Result::YAML \- YAML result token."
+.IX Subsection "TAP::Parser::Result::YAML - YAML result token."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "OVERRIDDEN METHODS" 4
+.IX Item "OVERRIDDEN METHODS"
+.PD
+\&\f(CW\*(C`as_string\*(C'\fR, \f(CW\*(C`raw\*(C'\fR
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::ResultFactory \- Factory for creating TAP::Parser output objects"
+.IX Subsection "TAP::Parser::ResultFactory - Factory for creating TAP::Parser output objects"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Scheduler \- Schedule tests during parallel testing"
+.IX Subsection "TAP::Parser::Scheduler - Schedule tests during parallel testing"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Rules data structure" 4
+.IX Item "Rules data structure"
+.PD
+By default, all tests are eligible to be run in parallel. Specifying any of
+your own rules removes this one, "First match wins". The first rule that
+matches a test will be the one that applies, Any test which does not match
+a rule will be run in sequence at the end of the run, The existence of a
+rule does not imply selecting a test. You must still specify the tests to
+run, Specifying a rule to allow tests to run in parallel does not make the
+run in parallel. You still need specify the number of parallel \f(CW\*(C`jobs\*(C'\fR in
+your Harness object
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.SS "TAP::Parser::Scheduler::Job \- A single testing job."
+.IX Subsection "TAP::Parser::Scheduler::Job - A single testing job."
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP Attributes 4
+.IX Item "Attributes"
+.PD
+.SS "TAP::Parser::Scheduler::Spinner \- A no-op job."
+.IX Subsection "TAP::Parser::Scheduler::Spinner - A no-op job."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::Source \- a TAP source & meta data about it"
+.IX Subsection "TAP::Parser::Source - a TAP source & meta data about it"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler \- Base class for different TAP source handlers"
+.IX Subsection "TAP::Parser::SourceHandler - Base class for different TAP source handlers"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler::Executable \- Stream output from an executable TAP source"
+.IX Subsection "TAP::Parser::SourceHandler::Executable - Stream output from an executable TAP source"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler::File \- Stream TAP from a text file."
+.IX Subsection "TAP::Parser::SourceHandler::File - Stream TAP from a text file."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP CONFIGURATION 4
+.IX Item "CONFIGURATION"
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler::Handle \- Stream TAP from an IO::Handle or a GLOB."
+.IX Subsection "TAP::Parser::SourceHandler::Handle - Stream TAP from an IO::Handle or a GLOB."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler::Perl \- Stream TAP from a Perl executable"
+.IX Subsection "TAP::Parser::SourceHandler::Perl - Stream TAP from a Perl executable"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.RS 4
+.IP Example 4
+.IX Item "Example"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::SourceHandler::RawTAP \- Stream output from raw TAP in a scalar/array ref."
+.IX Subsection "TAP::Parser::SourceHandler::RawTAP - Stream output from raw TAP in a scalar/array ref."
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "TAP::Parser::YAMLish::Reader \- Read YAMLish data from iterator"
+.IX Subsection "TAP::Parser::YAMLish::Reader - Read YAMLish data from iterator"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "TAP::Parser::YAMLish::Writer \- Write YAMLish data"
+.IX Subsection "TAP::Parser::YAMLish::Writer - Write YAMLish data"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "Class Methods" 4
+.IX Item "Class Methods"
+.IP "Instance Methods" 4
+.IX Item "Instance Methods"
+.PD
+a reference to a scalar to append YAML to, the handle of an open file, a
+reference to an array into which YAML will be pushed, a code reference
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Term::ANSIColor \- Color screen output using ANSI escape sequences"
+.IX Subsection "Term::ANSIColor - Color screen output using ANSI escape sequences"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Supported Colors" 4
+.IX Item "Supported Colors"
+.IP "Function Interface" 4
+.IX Item "Function Interface"
+.PD
+color(ATTR[, ATTR ...]), colored(STRING, ATTR[, ATTR ...]),
+colored(ATTR\-REF, STRING[, STRING...]), uncolor(ESCAPE),
+colorstrip(STRING[, STRING ...]), colorvalid(ATTR[, ATTR ...]),
+coloralias(ALIAS[, ATTR ...])
+.IP "Constant Interface" 4
+.IX Item "Constant Interface"
+.PD 0
+.IP "The Color Stack" 4
+.IX Item "The Color Stack"
+.IP "Supporting CLICOLOR" 4
+.IX Item "Supporting CLICOLOR"
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+Bad color mapping \f(CW%s\fR, Bad escape sequence \f(CW%s\fR, Bareword "%s" not allowed
+while "strict subs" in use, Cannot alias standard color \f(CW%s\fR, Cannot alias
+standard color \f(CW%s\fR in \f(CW%s\fR, Invalid alias name \f(CW%s\fR, Invalid alias name \f(CW%s\fR in
+\&\f(CW%s\fR, Invalid attribute name \f(CW%s\fR, Invalid attribute name \f(CW%s\fR in \f(CW%s\fR, Name "%s"
+used only once: possible typo, No comma allowed after filehandle, No name
+for escape sequence \f(CW%s\fR
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+ANSI_COLORS_ALIASES, ANSI_COLORS_DISABLED, NO_COLOR
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.PD 0
+.IP RESTRICTIONS 4
+.IX Item "RESTRICTIONS"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Term::Cap \- Perl termcap interface"
+.IX Subsection "Term::Cap - Perl termcap interface"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP METHODS 4
+.IX Item "METHODS"
+.RE
+.RS 4
+.RE
+.PD
+.PP
+\&\fBTgetent\fR, OSPEED, TERM
+.PP
+\&\fBTpad\fR, \fR\f(CB$string\fR\fB\fR, \fB\fR\f(CB$cnt\fR\fB\fR, \fB\fR\f(CB$FH\fR\fB\fR
+.PP
+\&\fBTputs\fR, \fR\f(CB$cap\fR\fB\fR, \fB\fR\f(CB$cnt\fR\fB\fR, \fB\fR\f(CB$FH\fR\fB\fR
+.PP
+\&\fBTgoto\fR, \fR\f(CB$cap\fR\fB\fR, \fB\fR\f(CB$col\fR\fB\fR, \fB\fR\f(CB$row\fR\fB\fR, \fB\fR\f(CB$FH\fR\fB\fR
+.PP
+\&\fBTrequire\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Term::Complete \- Perl word completion module"
+.IX Subsection "Term::Complete - Perl word completion module"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+<tab>, ^D, ^U, <del>, <bs>
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.ie n .SS "Term::ReadLine \- Perl interface to various ""readline"" packages. If no real package is found, substitutes stubs instead of basic functions."
+.el .SS "Term::ReadLine \- Perl interface to various \f(CWreadline\fP packages. If no real package is found, substitutes stubs instead of basic functions."
+.IX Subsection "Term::ReadLine - Perl interface to various readline packages. If no real package is found, substitutes stubs instead of basic functions."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Minimal set of supported functions" 4
+.IX Item "Minimal set of supported functions"
+.PD
+\&\f(CW\*(C`ReadLine\*(C'\fR, \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`addhistory\*(C'\fR, \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT\*(C'\fR, \f(CW\*(C`MinLine\*(C'\fR,
+\&\f(CW\*(C`findConsole\*(C'\fR, Attribs, \f(CW\*(C`Features\*(C'\fR
+.IP "Additional supported functions" 4
+.IX Item "Additional supported functions"
+\&\f(CW\*(C`tkRunning\*(C'\fR, \f(CW\*(C`event_loop\*(C'\fR, \f(CW\*(C`ornaments\*(C'\fR, \f(CW\*(C`newTTY\*(C'\fR
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD 0
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.PD
+.SS "Test \- provides a simple framework for writing test scripts"
+.IX Subsection "Test - provides a simple framework for writing test scripts"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "QUICK START GUIDE" 4
+.IX Item "QUICK START GUIDE"
+.RS 4
+.IP Functions 4
+.IX Item "Functions"
+.PD
+\&\f(CWplan(...)\fR, \f(CW\*(C`tests => \fR\f(CInumber\fR\f(CW\*(C'\fR, \f(CW\*(C`todo => [\fR\f(CI1,5,14\fR\f(CW]\*(C'\fR,
+\&\f(CW\*(C`onfail => sub { ... }\*(C'\fR, \f(CW\*(C`onfail => \e&some_sub\*(C'\fR
+.RE
+.RS 4
+.RE
+.PP
+\&\fB_to_value\fR
+.PP
+\&\f(CWok(...)\fR
+.PP
+\&\f(CW\*(C`skip(\fR\f(CIskip_if_true\fR\f(CW, \fR\f(CIargs...\fR\f(CW)\*(C'\fR
+.IP "TEST TYPES" 4
+.IX Item "TEST TYPES"
+NORMAL TESTS, SKIPPED TESTS, TODO TESTS
+.IP ONFAIL 4
+.IX Item "ONFAIL"
+.PD 0
+.IP "BUGS and CAVEATS" 4
+.IX Item "BUGS and CAVEATS"
+.IP ENVIRONMENT 4
+.IX Item "ENVIRONMENT"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Test2 \- Framework for writing test tools that all work together."
+.IX Subsection "Test2 - Framework for writing test tools that all work together."
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "WHAT IS NEW?" 4
+.IX Item "WHAT IS NEW?"
+.PD
+Easier to test new testing tools, Better diagnostics capabilities, Event
+driven, More complete API, Support for output other than TAP, Subtest
+implementation is more sane, Support for threading/forking
+.RE
+.RS 4
+.RE
+.IP "GETTING STARTED" 4
+.IX Item "GETTING STARTED"
+.SS "Test2, This describes the namespace layout for the Test2 ecosystem. Not all the namespaces listed here are part of the Test2 distribution, some are implemented in Test2::Suite."
+.IX Subsection "Test2, This describes the namespace layout for the Test2 ecosystem. Not all the namespaces listed here are part of the Test2 distribution, some are implemented in Test2::Suite."
+.PD 0
+.IP Test2::Tools:: 4
+.IX Item "Test2::Tools::"
+.IP Test2::Plugin:: 4
+.IX Item "Test2::Plugin::"
+.IP Test2::Bundle:: 4
+.IX Item "Test2::Bundle::"
+.IP Test2::Require:: 4
+.IX Item "Test2::Require::"
+.IP Test2::Formatter:: 4
+.IX Item "Test2::Formatter::"
+.IP Test2::Event:: 4
+.IX Item "Test2::Event::"
+.IP Test2::Hub:: 4
+.IX Item "Test2::Hub::"
+.IP Test2::IPC:: 4
+.IX Item "Test2::IPC::"
+.IP Test2::Util:: 4
+.IX Item "Test2::Util::"
+.IP Test2::API:: 4
+.IX Item "Test2::API::"
+.IP Test2:: 4
+.IX Item "Test2::"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP "CONTACTING US" 4
+.IX Item "CONTACTING US"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API \- Primary interface for writing Test2 based testing tools."
+.IX Subsection "Test2::API - Primary interface for writing Test2 based testing tools."
+.PD 0
+.IP "***INTERNALS NOTE***" 4
+.IX Item "***INTERNALS NOTE***"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP "WRITING A TOOL" 4
+.IX Item "WRITING A TOOL"
+.IP "TESTING YOUR TOOLS" 4
+.IX Item "TESTING YOUR TOOLS"
+.IP "OTHER API FUNCTIONS" 4
+.IX Item "OTHER API FUNCTIONS"
+.RE
+.RS 4
+.RE
+.IP "MAIN API EXPORTS" 4
+.IX Item "MAIN API EXPORTS"
+.RS 4
+.IP context(...) 4
+.IX Item "context(...)"
+.PD
+\&\f(CW$ctx\fR = \fBcontext()\fR, \f(CW$ctx\fR = context(%params), level => \f(CW$int\fR, wrapped => \f(CW$int\fR,
+stack => \f(CW$stack\fR, hub => \f(CW$hub\fR, on_init => sub { ... }, on_release => sub {
+\&... }
+.IP release($;$) 4
+.IX Item "release($;$)"
+release \f(CW$ctx\fR;, release \f(CW$ctx\fR, ...;
+.IP context_do(&;@) 4
+.IX Item "context_do(&;@)"
+.PD 0
+.IP no_context(&;$) 4
+.IX Item "no_context(&;$)"
+.PD
+no_context { ... };, no_context { ... } \f(CW$hid\fR;
+.IP intercept(&) 4
+.IX Item "intercept(&)"
+.PD 0
+.IP run_subtest(...) 4
+.IX Item "run_subtest(...)"
+.PD
+\&\f(CW$NAME\fR, \e&CODE, \f(CW$BUFFERED\fR or \e%PARAMS, 'buffered' => \f(CW$bool\fR, 'inherit_trace'
+=> \f(CW$bool\fR, 'no_fork' => \f(CW$bool\fR, \f(CW@ARGS\fR, Things not effected by this flag,
+Things that are effected by this flag, Things that are formatter dependant
+.RE
+.RS 4
+.RE
+.IP "OTHER API EXPORTS" 4
+.IX Item "OTHER API EXPORTS"
+.RS 4
+.PD 0
+.IP "STATUS AND INITIALIZATION STATE" 4
+.IX Item "STATUS AND INITIALIZATION STATE"
+.PD
+\&\f(CW$bool\fR = \fBtest2_init_done()\fR, \f(CW$bool\fR = \fBtest2_load_done()\fR, \fBtest2_set_is_end()\fR,
+test2_set_is_end($bool), \f(CW$bool\fR = \fBtest2_get_is_end()\fR, \f(CW$stack\fR =
+\&\fBtest2_stack()\fR, \f(CW$bool\fR = \fBtest2_is_testing_done()\fR, test2_ipc_disable, \f(CW$bool\fR =
+test2_ipc_diabled, \fBtest2_ipc_wait_enable()\fR, \fBtest2_ipc_wait_disable()\fR, \f(CW$bool\fR
+= \fBtest2_ipc_wait_enabled()\fR, \f(CW$bool\fR = \fBtest2_no_wait()\fR, test2_no_wait($bool),
+\&\f(CW$fh\fR = \fBtest2_stdout()\fR, \f(CW$fh\fR = \fBtest2_stderr()\fR, \fBtest2_reset_io()\fR
+.IP "BEHAVIOR HOOKS" 4
+.IX Item "BEHAVIOR HOOKS"
+test2_add_callback_exit(sub { ... }), test2_add_callback_post_load(sub {
+\&... }), test2_add_callback_testing_done(sub { ... }),
+test2_add_callback_context_acquire(sub { ... }),
+test2_add_callback_context_init(sub { ... }),
+test2_add_callback_context_release(sub { ... }),
+test2_add_callback_pre_subtest(sub { ... }), \f(CW@list\fR =
+\&\fBtest2_list_context_acquire_callbacks()\fR, \f(CW@list\fR =
+\&\fBtest2_list_context_init_callbacks()\fR, \f(CW@list\fR =
+\&\fBtest2_list_context_release_callbacks()\fR, \f(CW@list\fR =
+\&\fBtest2_list_exit_callbacks()\fR, \f(CW@list\fR = \fBtest2_list_post_load_callbacks()\fR,
+\&\f(CW@list\fR = \fBtest2_list_pre_subtest_callbacks()\fR, test2_add_uuid_via(sub { ...
+}), \f(CW$sub\fR = \fBtest2_add_uuid_via()\fR
+.IP "IPC AND CONCURRENCY" 4
+.IX Item "IPC AND CONCURRENCY"
+\&\f(CW$bool\fR = \fBtest2_has_ipc()\fR, \f(CW$ipc\fR = \fBtest2_ipc()\fR, test2_ipc_add_driver($DRIVER),
+\&\f(CW@drivers\fR = \fBtest2_ipc_drivers()\fR, \f(CW$bool\fR = \fBtest2_ipc_polling()\fR,
+\&\fBtest2_ipc_enable_polling()\fR, \fBtest2_ipc_disable_polling()\fR,
+\&\fBtest2_ipc_enable_shm()\fR, test2_ipc_set_pending($uniq_val), \f(CW$pending\fR =
+\&\fBtest2_ipc_get_pending()\fR, \f(CW$timeout\fR = \fBtest2_ipc_get_timeout()\fR,
+test2_ipc_set_timeout($timeout)
+.IP "MANAGING FORMATTERS" 4
+.IX Item "MANAGING FORMATTERS"
+\&\f(CW$formatter\fR = test2_formatter, test2_formatter_set($class_or_instance),
+\&\f(CW@formatters\fR = \fBtest2_formatters()\fR, test2_formatter_add($class_or_instance)
+.RE
+.RS 4
+.RE
+.IP "OTHER EXAMPLES" 4
+.IX Item "OTHER EXAMPLES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP MAGIC 4
+.IX Item "MAGIC"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::Breakage \- What breaks at what version"
+.IX Subsection "Test2::API::Breakage - What breaks at what version"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\f(CW%mod_ver\fR = \fBupgrade_suggested()\fR, \f(CW%mod_ver\fR =
+Test2::API::Breakage\->\fBupgrade_suggested()\fR, \f(CW%mod_ver\fR = \fBupgrade_required()\fR,
+\&\f(CW%mod_ver\fR = Test2::API::Breakage\->\fBupgrade_required()\fR, \f(CW%mod_ver\fR =
+\&\fBknown_broken()\fR, \f(CW%mod_ver\fR = Test2::API::Breakage\->\fBknown_broken()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::Context \- Object to represent a testing context."
+.IX Subsection "Test2::API::Context - Object to represent a testing context."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP "CRITICAL DETAILS" 4
+.IX Item "CRITICAL DETAILS"
+.PD
+you MUST always use the \fBcontext()\fR sub from Test2::API, You MUST always
+release the context when done with it, You MUST NOT pass context objects
+around, You MUST NOT store or cache a context for later, You SHOULD obtain
+your context as soon as possible in a given tool
+.IP METHODS 4
+.IX Item "METHODS"
+\&\f(CW$ctx\fR\->done_testing;, \f(CW$clone\fR = \f(CW$ctx\fR\->\fBsnapshot()\fR, \f(CW$ctx\fR\->\fBrelease()\fR,
+\&\f(CW$ctx\fR\->throw($message), \f(CW$ctx\fR\->alert($message), \f(CW$stack\fR = \f(CW$ctx\fR\->\fBstack()\fR, \f(CW$hub\fR
+= \f(CW$ctx\fR\->\fBhub()\fR, \f(CW$dbg\fR = \f(CW$ctx\fR\->\fBtrace()\fR, \f(CW$ctx\fR\->do_in_context(\e&code, \f(CW@args\fR);,
+\&\f(CW$ctx\fR\->\fBrestore_error_vars()\fR, $! = \f(CW$ctx\fR\->\fBerrno()\fR, $? = \f(CW$ctx\fR\->\fBchild_error()\fR,
+$@ = \f(CW$ctx\fR\->\fBeval_error()\fR
+.RS 4
+.IP "EVENT PRODUCTION METHODS" 4
+.IX Item "EVENT PRODUCTION METHODS"
+\&\f(CW$event\fR = \f(CW$ctx\fR\->\fBpass()\fR, \f(CW$event\fR = \f(CW$ctx\fR\->pass($name), \f(CW$true\fR =
+\&\f(CW$ctx\fR\->\fBpass_and_release()\fR, \f(CW$true\fR = \f(CW$ctx\fR\->pass_and_release($name), my \f(CW$event\fR
+= \f(CW$ctx\fR\->\fBfail()\fR, my \f(CW$event\fR = \f(CW$ctx\fR\->fail($name), my \f(CW$event\fR =
+\&\f(CW$ctx\fR\->fail($name, \f(CW@diagnostics\fR), my \f(CW$false\fR = \f(CW$ctx\fR\->\fBfail_and_release()\fR, my
+\&\f(CW$false\fR = \f(CW$ctx\fR\->fail_and_release($name), my \f(CW$false\fR =
+\&\f(CW$ctx\fR\->fail_and_release($name, \f(CW@diagnostics\fR), \f(CW$event\fR = \f(CW$ctx\fR\->ok($bool,
+\&\f(CW$name\fR), \f(CW$event\fR = \f(CW$ctx\fR\->ok($bool, \f(CW$name\fR, \e@on_fail), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->note($message), \f(CW$event\fR = \f(CW$ctx\fR\->diag($message), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->plan($max), \f(CW$event\fR = \f(CW$ctx\fR\->plan(0, 'SKIP', \f(CW$reason\fR), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->skip($name, \f(CW$reason\fR);, \f(CW$event\fR = \f(CW$ctx\fR\->bail($reason), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->send_ev2(%facets), \f(CW$event\fR = \f(CW$ctx\fR\->build_e2(%facets), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->send_ev2_and_release($Type, \f(CW%parameters\fR), \f(CW$event\fR =
+\&\f(CW$ctx\fR\->send_event($Type, \f(CW%parameters\fR), \f(CW$event\fR = \f(CW$ctx\fR\->build_event($Type,
+\&\f(CW%parameters\fR), \f(CW$event\fR = \f(CW$ctx\fR\->send_event_and_release($Type, \f(CW%parameters\fR)
+.RE
+.RS 4
+.RE
+.IP HOOKS 4
+.IX Item "HOOKS"
+.RS 4
+.PD 0
+.IP "INIT HOOKS" 4
+.IX Item "INIT HOOKS"
+.IP "RELEASE HOOKS" 4
+.IX Item "RELEASE HOOKS"
+.RE
+.RS 4
+.RE
+.IP "THIRD PARTY META-DATA" 4
+.IX Item "THIRD PARTY META-DATA"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>, Kent Fredric
+<kentnl@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::Instance \- Object used by Test2::API under the hood"
+.IX Subsection "Test2::API::Instance - Object used by Test2::API under the hood"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD
+\&\f(CW$pid\fR = \f(CW$obj\fR\->pid, \f(CW$obj\fR\->tid, \f(CW$obj\fR\->\fBreset()\fR, \f(CW$obj\fR\->\fBload()\fR, \f(CW$bool\fR =
+\&\f(CW$obj\fR\->loaded, \f(CW$arrayref\fR = \f(CW$obj\fR\->post_load_callbacks,
+\&\f(CW$obj\fR\->add_post_load_callback(sub { ... }), \f(CW$hashref\fR = \f(CW$obj\fR\->\fBcontexts()\fR,
+\&\f(CW$arrayref\fR = \f(CW$obj\fR\->context_acquire_callbacks, \f(CW$arrayref\fR =
+\&\f(CW$obj\fR\->context_init_callbacks, \f(CW$arrayref\fR = \f(CW$obj\fR\->context_release_callbacks,
+\&\f(CW$arrayref\fR = \f(CW$obj\fR\->pre_subtest_callbacks,
+\&\f(CW$obj\fR\->add_context_init_callback(sub { ... }),
+\&\f(CW$obj\fR\->add_context_release_callback(sub { ... }),
+\&\f(CW$obj\fR\->add_pre_subtest_callback(sub { ... }), \f(CW$obj\fR\->\fBset_exit()\fR,
+\&\f(CW$obj\fR\->set_ipc_pending($val), \f(CW$pending\fR = \f(CW$obj\fR\->\fBget_ipc_pending()\fR, \f(CW$timeout\fR =
+\&\f(CW$obj\fR\->ipc_timeout;, \f(CW$obj\fR\->set_ipc_timeout($timeout);, \f(CW$drivers\fR =
+\&\f(CW$obj\fR\->ipc_drivers, \f(CW$obj\fR\->add_ipc_driver($DRIVER_CLASS), \f(CW$bool\fR =
+\&\f(CW$obj\fR\->ipc_polling, \f(CW$obj\fR\->enable_ipc_polling, \f(CW$obj\fR\->disable_ipc_polling,
+\&\f(CW$bool\fR = \f(CW$obj\fR\->no_wait, \f(CW$bool\fR = \f(CW$obj\fR\->set_no_wait($bool), \f(CW$arrayref\fR =
+\&\f(CW$obj\fR\->exit_callbacks, \f(CW$obj\fR\->add_exit_callback(sub { ... }), \f(CW$bool\fR =
+\&\f(CW$obj\fR\->finalized, \f(CW$ipc\fR = \f(CW$obj\fR\->ipc, \f(CW$obj\fR\->ipc_disable, \f(CW$bool\fR =
+\&\f(CW$obj\fR\->ipc_disabled, \f(CW$stack\fR = \f(CW$obj\fR\->stack, \f(CW$formatter\fR = \f(CW$obj\fR\->formatter,
+\&\f(CW$bool\fR = \f(CW$obj\fR\->\fBformatter_set()\fR, \f(CW$obj\fR\->add_formatter($class),
+\&\f(CW$obj\fR\->add_formatter($obj), \f(CW$obj\fR\->set_add_uuid_via(sub { ... }), \f(CW$sub\fR =
+\&\f(CW$obj\fR\->\fBadd_uuid_via()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::InterceptResult \- Representation of a list of events."
+.IX Subsection "Test2::API::InterceptResult - Representation of a list of events."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP CONSTRUCTION 4
+.IX Item "CONSTRUCTION"
+.PD
+\&\f(CW$events\fR = Test2::API::InterceptResult\->new(@EVENTS), \f(CW$events\fR =
+Test2::API::InterceptResult\->new_from_ref(\e@EVENTS), \f(CW$clone\fR =
+\&\f(CW$events\fR\->\fBclone()\fR
+.IP NORMALIZATION 4
+.IX Item "NORMALIZATION"
+\&\f(CW@events\fR = \f(CW$events\fR\->event_list, \f(CW$hub\fR = \f(CW$events\fR\->hub, \f(CW$state\fR =
+\&\f(CW$events\fR\->state, \f(CW$new\fR = \f(CW$events\fR\->upgrade, \f(CW$events\fR\->upgrade(in_place =>
+\&\f(CW$BOOL\fR), \f(CW$new\fR = \f(CW$events\fR\->squash_info, \f(CW$events\fR\->squash_info(in_place =>
+\&\f(CW$BOOL\fR)
+.IP FILTERING 4
+.IX Item "FILTERING"
+in_place => \f(CW$BOOL\fR, args => \e@ARGS, \f(CW$events\fR\->grep($CALL, \f(CW%PARAMS\fR),
+\&\f(CW$events\fR\->asserts(%PARAMS), \f(CW$events\fR\->subtests(%PARAMS),
+\&\f(CW$events\fR\->diags(%PARAMS), \f(CW$events\fR\->notes(%PARAMS), \f(CW$events\fR\->errors(%PARAMS),
+\&\f(CW$events\fR\->plans(%PARAMS), \f(CW$events\fR\->causes_fail(%PARAMS),
+\&\f(CW$events\fR\->causes_failure(%PARAMS)
+.IP MAPPING 4
+.IX Item "MAPPING"
+\&\f(CW$arrayref\fR = \f(CW$events\fR\->map($CALL, \f(CW%PARAMS\fR), \f(CW$arrayref\fR =
+\&\f(CW$events\fR\->flatten(%PARAMS), \f(CW$arrayref\fR = \f(CW$events\fR\->briefs(%PARAMS), \f(CW$arrayref\fR
+= \f(CW$events\fR\->summaries(%PARAMS), \f(CW$arrayref\fR =
+\&\f(CW$events\fR\->subtest_results(%PARAMS), \f(CW$arrayref\fR =
+\&\f(CW$events\fR\->diag_messages(%PARAMS), \f(CW$arrayref\fR =
+\&\f(CW$events\fR\->note_messages(%PARAMS), \f(CW$arrayref\fR =
+\&\f(CW$events\fR\->error_messages(%PARAMS)
+.RE
+.RS 4
+.RE
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::InterceptResult::Event \- Representation of an event for use in testing other test tools."
+.IX Subsection "Test2::API::InterceptResult::Event - Representation of an event for use in testing other test tools."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "!!! IMPORTANT NOTES ON DESIGN !!!" 4
+.IX Item "!!! IMPORTANT NOTES ON DESIGN !!!"
+.IP ATTRIBUTES 4
+.IX Item "ATTRIBUTES"
+.PD
+\&\f(CW$hashref\fR = \f(CW$event\fR\->facet_data, \f(CW$class\fR = \f(CW$event\fR\->result_class
+.IP DUPLICATION 4
+.IX Item "DUPLICATION"
+\&\f(CW$copy\fR = \f(CW$event\fR\->clone
+.IP "CONDENSED MULTI-FACET DATA" 4
+.IX Item "CONDENSED MULTI-FACET DATA"
+\&\f(CW$bool\fR = \f(CW$event\fR\->causes_failure, \f(CW$bool\fR = \f(CW$event\fR\->causes_fail,
+STRING_OR_EMPTY_LIST = \f(CW$event\fR\->brief, \f(CW$hashref\fR = \f(CW$event\fR\->flatten, \f(CW$hashref\fR
+= \f(CW$event\fR\->flatten(include_subevents => 1), always present, Present if the
+event has a trace facet, If an assertion is present, If a plan is present:,
+If amnesty facets are present, If Info (note/diag) facets are present, If
+error facets are present, Present if the event is a subtest, If a bail-out
+is being requested, \f(CW$hashref\fR = \f(CW$event\fR\->\fBsummary()\fR
+.IP "DIRECT ARBITRARY FACET ACCESS" 4
+.IX Item "DIRECT ARBITRARY FACET ACCESS"
+\&\f(CW@list_of_facets\fR = \f(CW$event\fR\->facet($name), \f(CW$undef_or_facet\fR =
+\&\f(CW$event\fR\->the_facet($name)
+.IP "TRACE FACET" 4
+.IX Item "TRACE FACET"
+\&\f(CW@list_of_facets\fR = \f(CW$event\fR\->trace, \f(CW$undef_or_hashref\fR = \f(CW$event\fR\->the_trace,
+\&\f(CW$undef_or_arrayref\fR = \f(CW$event\fR\->frame, \f(CW$undef_or_string\fR =
+\&\f(CW$event\fR\->trace_details, \f(CW$undef_or_string\fR = \f(CW$event\fR\->trace_package,
+\&\f(CW$undef_or_string\fR = \f(CW$event\fR\->trace_file, \f(CW$undef_or_integer\fR =
+\&\f(CW$event\fR\->trace_line, \f(CW$undef_or_string\fR = \f(CW$event\fR\->trace_subname,
+\&\f(CW$undef_or_string\fR = \f(CW$event\fR\->trace_tool, \f(CW$undef_or_string\fR =
+\&\f(CW$event\fR\->trace_signature
+.IP "ASSERT FACET" 4
+.IX Item "ASSERT FACET"
+\&\f(CW$bool\fR = \f(CW$event\fR\->has_assert, \f(CW$undef_or_hashref\fR = \f(CW$event\fR\->the_assert,
+\&\f(CW@list_of_facets\fR = \f(CW$event\fR\->assert, EMPTY_LIST_OR_STRING =
+\&\f(CW$event\fR\->assert_brief
+.IP "SUBTESTS (PARENT FACET)" 4
+.IX Item "SUBTESTS (PARENT FACET)"
+\&\f(CW$bool\fR = \f(CW$event\fR\->has_subtest, \f(CW$undef_or_hashref\fR = \f(CW$event\fR\->the_subtest,
+\&\f(CW@list_of_facets\fR = \f(CW$event\fR\->subtest, EMPTY_LIST_OR_OBJECT =
+\&\f(CW$event\fR\->subtest_result
+.IP "CONTROL FACET (BAILOUT, ENCODING)" 4
+.IX Item "CONTROL FACET (BAILOUT, ENCODING)"
+\&\f(CW$bool\fR = \f(CW$event\fR\->has_bailout, \f(CW$undef_hashref\fR = \f(CW$event\fR\->the_bailout,
+EMPTY_LIST_OR_HASHREF = \f(CW$event\fR\->bailout, EMPTY_LIST_OR_STRING =
+\&\f(CW$event\fR\->bailout_brief, EMPTY_LIST_OR_STRING = \f(CW$event\fR\->bailout_reason
+.IP "PLAN FACET" 4
+.IX Item "PLAN FACET"
+\&\f(CW$bool\fR = \f(CW$event\fR\->has_plan, \f(CW$undef_or_hashref\fR = \f(CW$event\fR\->the_plan,
+\&\f(CW@list_if_hashrefs\fR = \f(CW$event\fR\->plan, EMPTY_LIST_OR_STRING \f(CW$event\fR\->plan_brief
+.IP "AMNESTY FACET (TODO AND SKIP)" 4
+.IX Item "AMNESTY FACET (TODO AND SKIP)"
+\&\f(CW$event\fR\->has_amnesty, \f(CW$event\fR\->the_amnesty, \f(CW$event\fR\->amnesty,
+\&\f(CW$event\fR\->amnesty_reasons, \f(CW$event\fR\->has_todos, \f(CW$event\fR\->todos,
+\&\f(CW$event\fR\->todo_reasons, \f(CW$event\fR\->has_skips, \f(CW$event\fR\->skips,
+\&\f(CW$event\fR\->skip_reasons, \f(CW$event\fR\->has_other_amnesty, \f(CW$event\fR\->other_amnesty,
+\&\f(CW$event\fR\->other_amnesty_reasons
+.IP "ERROR FACET (CAPTURED EXCEPTIONS)" 4
+.IX Item "ERROR FACET (CAPTURED EXCEPTIONS)"
+\&\f(CW$event\fR\->has_errors, \f(CW$event\fR\->the_errors, \f(CW$event\fR\->errors,
+\&\f(CW$event\fR\->error_messages, \f(CW$event\fR\->error_brief
+.IP "INFO FACET (DIAG, NOTE)" 4
+.IX Item "INFO FACET (DIAG, NOTE)"
+\&\f(CW$event\fR\->has_info, \f(CW$event\fR\->the_info, \f(CW$event\fR\->info, \f(CW$event\fR\->info_messages,
+\&\f(CW$event\fR\->has_diags, \f(CW$event\fR\->diags, \f(CW$event\fR\->diag_messages, \f(CW$event\fR\->has_notes,
+\&\f(CW$event\fR\->notes, \f(CW$event\fR\->note_messages, \f(CW$event\fR\->has_other_info,
+\&\f(CW$event\fR\->other_info, \f(CW$event\fR\->other_info_messages
+.RE
+.RS 4
+.RE
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::InterceptResult::Hub \- Hub used by InterceptResult."
+.IX Subsection "Test2::API::InterceptResult::Hub - Hub used by InterceptResult."
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::InterceptResult::Squasher \- Encapsulation of the algorithm that squashes diags into assertions."
+.IX Subsection "Test2::API::InterceptResult::Squasher - Encapsulation of the algorithm that squashes diags into assertions."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::API::Stack \- Object to manage a stack of Test2::Hub instances."
+.IX Subsection "Test2::API::Stack - Object to manage a stack of Test2::Hub instances."
+.PD 0
+.IP "***INTERNALS NOTE***" 4
+.IX Item "***INTERNALS NOTE***"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$stack\fR = Test2::API::Stack\->\fBnew()\fR, \f(CW$hub\fR = \f(CW$stack\fR\->\fBnew_hub()\fR, \f(CW$hub\fR =
+\&\f(CW$stack\fR\->new_hub(%params), \f(CW$hub\fR = \f(CW$stack\fR\->new_hub(%params, class => \f(CW$class\fR),
+\&\f(CW$hub\fR = \f(CW$stack\fR\->\fBtop()\fR, \f(CW$hub\fR = \f(CW$stack\fR\->\fBpeek()\fR, \f(CW$stack\fR\->cull, \f(CW@hubs\fR =
+\&\f(CW$stack\fR\->all, \f(CW$stack\fR\->clear, \f(CW$stack\fR\->push($hub), \f(CW$stack\fR\->pop($hub)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event \- Base class for events"
+.IX Subsection "Test2::Event - Base class for events"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP GENERAL 4
+.IX Item "GENERAL"
+.PD
+\&\f(CW$trace\fR = \f(CW$e\fR\->trace, \f(CW$bool_or_undef\fR = \f(CW$e\fR\->related($e2), \f(CW$e\fR\->add_amnesty({tag
+=> \f(CW$TAG\fR, details => \f(CW$DETAILS\fR});, \f(CW$uuid\fR = \f(CW$e\fR\->uuid, \f(CW$class\fR =
+\&\f(CW$e\fR\->load_facet($name), \f(CW@classes\fR = \f(CW$e\fR\->\fBFACET_TYPES()\fR, \f(CW@classes\fR =
+Test2::Event\->\fBFACET_TYPES()\fR
+.IP "NEW API" 4
+.IX Item "NEW API"
+\&\f(CW$hashref\fR = \f(CW$e\fR\->\fBcommon_facet_data()\fR;, \f(CW$hashref\fR = \f(CW$e\fR\->\fBfacet_data()\fR, \f(CW$hashref\fR
+= \f(CW$e\fR\->\fBfacets()\fR, \f(CW@errors\fR = \f(CW$e\fR\->\fBvalidate_facet_data()\fR;, \f(CW@errors\fR =
+\&\f(CW$e\fR\->validate_facet_data(%params);, \f(CW@errors\fR =
+\&\f(CW$e\fR\->validate_facet_data(\e%facets, \f(CW%params\fR);, \f(CW@errors\fR =
+Test2::Event\->validate_facet_data(%params);, \f(CW@errors\fR =
+Test2::Event\->validate_facet_data(\e%facets, \f(CW%params\fR);, require_facet_class
+=> \f(CW$BOOL\fR, about => {...}, assert => {...}, control => {...}, meta => {...},
+parent => {...}, plan => {...}, trace => {...}, amnesty => [{...}, ...],
+errors => [{...}, ...], info => [{...}, ...]
+.IP "LEGACY API" 4
+.IX Item "LEGACY API"
+\&\f(CW$bool\fR = \f(CW$e\fR\->causes_fail, \f(CW$bool\fR = \f(CW$e\fR\->increments_count, \f(CW$e\fR\->callback($hub),
+\&\f(CW$num\fR = \f(CW$e\fR\->nested, \f(CW$bool\fR = \f(CW$e\fR\->global, \f(CW$code\fR = \f(CW$e\fR\->terminate, \f(CW$msg\fR =
+\&\f(CW$e\fR\->summary, ($count, \f(CW$directive\fR, \f(CW$reason\fR) = \f(CW$e\fR\->\fBsets_plan()\fR, \f(CW$bool\fR =
+\&\f(CW$e\fR\->diagnostics, \f(CW$bool\fR = \f(CW$e\fR\->no_display, \f(CW$id\fR = \f(CW$e\fR\->in_subtest, \f(CW$id\fR =
+\&\f(CW$e\fR\->subtest_id
+.RE
+.RS 4
+.RE
+.IP "THIRD PARTY META-DATA" 4
+.IX Item "THIRD PARTY META-DATA"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Bail \- Bailout!"
+.IX Subsection "Test2::Event::Bail - Bailout!"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$reason\fR = \f(CW$e\fR\->reason
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Diag \- Diag event type"
+.IX Subsection "Test2::Event::Diag - Diag event type"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$diag\fR\->message
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Encoding \- Set the encoding for the output stream"
+.IX Subsection "Test2::Event::Encoding - Set the encoding for the output stream"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$encoding\fR = \f(CW$e\fR\->encoding
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Exception \- Exception event"
+.IX Subsection "Test2::Event::Exception - Exception event"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$reason\fR = \f(CW$e\fR\->error
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Fail \- Event for a simple failed assertion"
+.IX Subsection "Test2::Event::Fail - Event for a simple failed assertion"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Generic \- Generic event type."
+.IX Subsection "Test2::Event::Generic - Generic event type."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$e\fR\->facet_data($data), \f(CW$data\fR = \f(CW$e\fR\->facet_data, \f(CW$e\fR\->callback($hub),
+\&\f(CW$e\fR\->set_callback(sub { ... }), \f(CW$bool\fR = \f(CW$e\fR\->causes_fail,
+\&\f(CW$e\fR\->set_causes_fail($bool), \f(CW$bool\fR = \f(CW$e\fR\->diagnostics,
+\&\f(CW$e\fR\->set_diagnostics($bool), \f(CW$bool_or_undef\fR = \f(CW$e\fR\->global, \f(CW@bool_or_empty\fR =
+\&\f(CW$e\fR\->global, \f(CW$e\fR\->set_global($bool_or_undef), \f(CW$bool\fR = \f(CW$e\fR\->increments_count,
+\&\f(CW$e\fR\->set_increments_count($bool), \f(CW$bool\fR = \f(CW$e\fR\->no_display,
+\&\f(CW$e\fR\->set_no_display($bool), \f(CW@plan\fR = \f(CW$e\fR\->sets_plan,
+\&\f(CW$e\fR\->set_sets_plan(\e@plan), \f(CW$summary\fR = \f(CW$e\fR\->summary,
+\&\f(CW$e\fR\->set_summary($summary_or_undef), \f(CW$int_or_undef\fR = \f(CW$e\fR\->terminate,
+\&\f(CW@int_or_empty\fR = \f(CW$e\fR\->terminate, \f(CW$e\fR\->set_terminate($int_or_undef)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Note \- Note event type"
+.IX Subsection "Test2::Event::Note - Note event type"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$note\fR\->message
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Ok \- Ok event type"
+.IX Subsection "Test2::Event::Ok - Ok event type"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$rb\fR = \f(CW$e\fR\->pass, \f(CW$name\fR = \f(CW$e\fR\->name, \f(CW$b\fR = \f(CW$e\fR\->effective_pass
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Pass \- Event for a simple passing assertion"
+.IX Subsection "Test2::Event::Pass - Event for a simple passing assertion"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Plan \- The event of a plan"
+.IX Subsection "Test2::Event::Plan - The event of a plan"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$num\fR = \f(CW$plan\fR\->max, \f(CW$dir\fR = \f(CW$plan\fR\->directive, \f(CW$reason\fR = \f(CW$plan\fR\->reason
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Skip \- Skip event type"
+.IX Subsection "Test2::Event::Skip - Skip event type"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$reason\fR = \f(CW$e\fR\->reason
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Subtest \- Event for subtest types"
+.IX Subsection "Test2::Event::Subtest - Event for subtest types"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.PD
+\&\f(CW$arrayref\fR = \f(CW$e\fR\->subevents, \f(CW$bool\fR = \f(CW$e\fR\->buffered
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::TAP::Version \- Event for TAP version."
+.IX Subsection "Test2::Event::TAP::Version - Event for TAP version."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$version\fR = \f(CW$e\fR\->version
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::V2 \- Second generation event."
+.IX Subsection "Test2::Event::V2 - Second generation event."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP "USING A CONTEXT" 4
+.IX Item "USING A CONTEXT"
+.IP "USING THE CONSTRUCTOR" 4
+.IX Item "USING THE CONSTRUCTOR"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$fd\fR = \f(CW$e\fR\->\fBfacet_data()\fR, \f(CW$about\fR = \f(CW$e\fR\->\fBabout()\fR, \f(CW$trace\fR = \f(CW$e\fR\->\fBtrace()\fR
+.RS 4
+.IP MUTATION 4
+.IX Item "MUTATION"
+\&\f(CW$e\fR\->add_amnesty({...}), \f(CW$e\fR\->add_hub({...}), \f(CW$e\fR\->set_uuid($UUID),
+\&\f(CW$e\fR\->set_trace($trace)
+.IP "LEGACY SUPPORT METHODS" 4
+.IX Item "LEGACY SUPPORT METHODS"
+causes_fail, diagnostics, global, increments_count, no_display, sets_plan,
+subtest_id, summary, terminate
+.RE
+.RS 4
+.RE
+.IP "THIRD PARTY META-DATA" 4
+.IX Item "THIRD PARTY META-DATA"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Event::Waiting \- Tell all procs/threads it is time to be done"
+.IX Subsection "Test2::Event::Waiting - Tell all procs/threads it is time to be done"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet \- Base class for all event facets."
+.IX Subsection "Test2::EventFacet - Base class for all event facets."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$key\fR = \f(CW$facet_class\fR\->\fBfacet_key()\fR, \f(CW$bool\fR = \f(CW$facet_class\fR\->\fBis_list()\fR, \f(CW$clone\fR =
+\&\f(CW$facet\fR\->\fBclone()\fR, \f(CW$clone\fR = \f(CW$facet\fR\->clone(%replace)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::About \- Facet with event details."
+.IX Subsection "Test2::EventFacet::About - Facet with event details."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$about\fR\->{details}, \f(CW$string\fR = \f(CW$about\fR\->\fBdetails()\fR, \f(CW$package\fR =
+\&\f(CW$about\fR\->{package}, \f(CW$package\fR = \f(CW$about\fR\->\fBpackage()\fR, \f(CW$bool\fR =
+\&\f(CW$about\fR\->{no_display}, \f(CW$bool\fR = \f(CW$about\fR\->\fBno_display()\fR, \f(CW$uuid\fR = \f(CW$about\fR\->{uuid},
+\&\f(CW$uuid\fR = \f(CW$about\fR\->\fBuuid()\fR, \f(CW$uuid\fR = \f(CW$about\fR\->{eid}, \f(CW$uuid\fR = \f(CW$about\fR\->\fBeid()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Amnesty \- Facet for assertion amnesty."
+.IX Subsection "Test2::EventFacet::Amnesty - Facet for assertion amnesty."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$amnesty\fR\->{details}, \f(CW$string\fR = \f(CW$amnesty\fR\->\fBdetails()\fR, \f(CW$short_string\fR
+= \f(CW$amnesty\fR\->{tag}, \f(CW$short_string\fR = \f(CW$amnesty\fR\->\fBtag()\fR, \f(CW$bool\fR =
+\&\f(CW$amnesty\fR\->{inherited}, \f(CW$bool\fR = \f(CW$amnesty\fR\->\fBinherited()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Assert \- Facet representing an assertion."
+.IX Subsection "Test2::EventFacet::Assert - Facet representing an assertion."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$assert\fR\->{details}, \f(CW$string\fR = \f(CW$assert\fR\->\fBdetails()\fR, \f(CW$bool\fR =
+\&\f(CW$assert\fR\->{pass}, \f(CW$bool\fR = \f(CW$assert\fR\->\fBpass()\fR, \f(CW$bool\fR = \f(CW$assert\fR\->{no_debug},
+\&\f(CW$bool\fR = \f(CW$assert\fR\->\fBno_debug()\fR, \f(CW$int\fR = \f(CW$assert\fR\->{number}, \f(CW$int\fR =
+\&\f(CW$assert\fR\->\fBnumber()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Control \- Facet for hub actions and behaviors."
+.IX Subsection "Test2::EventFacet::Control - Facet for hub actions and behaviors."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$control\fR\->{details}, \f(CW$string\fR = \f(CW$control\fR\->\fBdetails()\fR, \f(CW$bool\fR =
+\&\f(CW$control\fR\->{global}, \f(CW$bool\fR = \f(CW$control\fR\->\fBglobal()\fR, \f(CW$exit\fR =
+\&\f(CW$control\fR\->{terminate}, \f(CW$exit\fR = \f(CW$control\fR\->\fBterminate()\fR, \f(CW$bool\fR =
+\&\f(CW$control\fR\->{halt}, \f(CW$bool\fR = \f(CW$control\fR\->\fBhalt()\fR, \f(CW$bool\fR =
+\&\f(CW$control\fR\->{has_callback}, \f(CW$bool\fR = \f(CW$control\fR\->\fBhas_callback()\fR, \f(CW$encoding\fR =
+\&\f(CW$control\fR\->{encoding}, \f(CW$encoding\fR = \f(CW$control\fR\->\fBencoding()\fR, \f(CW$phase\fR =
+\&\f(CW$control\fR\->{phase}, \f(CW$phase\fR = \f(CW$control\fR\->\fBphase()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Error \- Facet for errors that need to be shown."
+.IX Subsection "Test2::EventFacet::Error - Facet for errors that need to be shown."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$error\fR\->{details}, \f(CW$string\fR = \f(CW$error\fR\->\fBdetails()\fR, \f(CW$short_string\fR =
+\&\f(CW$error\fR\->{tag}, \f(CW$short_string\fR = \f(CW$error\fR\->\fBtag()\fR, \f(CW$bool\fR = \f(CW$error\fR\->{fail}, \f(CW$bool\fR
+= \f(CW$error\fR\->\fBfail()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Hub \- Facet for the hubs an event passes through."
+.IX Subsection "Test2::EventFacet::Hub - Facet for the hubs an event passes through."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "FACET FIELDS" 4
+.IX Item "FACET FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$trace\fR\->{details}, \f(CW$string\fR = \f(CW$trace\fR\->\fBdetails()\fR, \f(CW$int\fR =
+\&\f(CW$trace\fR\->{pid}, \f(CW$int\fR = \f(CW$trace\fR\->\fBpid()\fR, \f(CW$int\fR = \f(CW$trace\fR\->{tid}, \f(CW$int\fR =
+\&\f(CW$trace\fR\->\fBtid()\fR, \f(CW$hid\fR = \f(CW$trace\fR\->{hid}, \f(CW$hid\fR = \f(CW$trace\fR\->\fBhid()\fR, \f(CW$huuid\fR =
+\&\f(CW$trace\fR\->{huuid}, \f(CW$huuid\fR = \f(CW$trace\fR\->\fBhuuid()\fR, \f(CW$int\fR = \f(CW$trace\fR\->{nested}, \f(CW$int\fR =
+\&\f(CW$trace\fR\->\fBnested()\fR, \f(CW$bool\fR = \f(CW$trace\fR\->{buffered}, \f(CW$bool\fR = \f(CW$trace\fR\->\fBbuffered()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Info \- Facet for information a developer might care about."
+.IX Subsection "Test2::EventFacet::Info - Facet for information a developer might care about."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string_or_structure\fR = \f(CW$info\fR\->{details}, \f(CW$string_or_structure\fR =
+\&\f(CW$info\fR\->\fBdetails()\fR, \f(CW$structure\fR = \f(CW$info\fR\->{table}, \f(CW$structure\fR = \f(CW$info\fR\->\fBtable()\fR,
+\&\f(CW$short_string\fR = \f(CW$info\fR\->{tag}, \f(CW$short_string\fR = \f(CW$info\fR\->\fBtag()\fR, \f(CW$bool\fR =
+\&\f(CW$info\fR\->{debug}, \f(CW$bool\fR = \f(CW$info\fR\->\fBdebug()\fR, \f(CW$bool\fR = \f(CW$info\fR\->{important}, \f(CW$bool\fR =
+\&\f(CW$info\fR\->important
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Info::Table \- Intermediary representation of a table."
+.IX Subsection "Test2::EventFacet::Info::Table - Intermediary representation of a table."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP ATTRIBUTES 4
+.IX Item "ATTRIBUTES"
+.PD
+\&\f(CW$header_aref\fR = \f(CW$t\fR\->\fBheader()\fR, \f(CW$rows_aref\fR = \f(CW$t\fR\->\fBrows()\fR, \f(CW$bool\fR =
+\&\f(CW$t\fR\->\fBcollapse()\fR, \f(CW$aref\fR = \f(CW$t\fR\->\fBno_collapse()\fR, \f(CW$str\fR = \f(CW$t\fR\->\fBas_string()\fR, \f(CW$href\fR =
+\&\f(CW$t\fR\->\fBas_hash()\fR, \f(CW%args\fR = \f(CW$t\fR\->\fBinfo_args()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Meta \- Facet for meta-data"
+.IX Subsection "Test2::EventFacet::Meta - Facet for meta-data"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "METHODS AND FIELDS" 4
+.IX Item "METHODS AND FIELDS"
+.PD
+\&\f(CW$anything\fR = \f(CW$meta\fR\->{anything}, \f(CW$anything\fR = \f(CW$meta\fR\->\fBanything()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Parent \- Facet for events contains other events"
+.IX Subsection "Test2::EventFacet::Parent - Facet for events contains other events"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$parent\fR\->{details}, \f(CW$string\fR = \f(CW$parent\fR\->\fBdetails()\fR, \f(CW$hid\fR =
+\&\f(CW$parent\fR\->{hid}, \f(CW$hid\fR = \f(CW$parent\fR\->\fBhid()\fR, \f(CW$arrayref\fR = \f(CW$parent\fR\->{children},
+\&\f(CW$arrayref\fR = \f(CW$parent\fR\->\fBchildren()\fR, \f(CW$bool\fR = \f(CW$parent\fR\->{buffered}, \f(CW$bool\fR =
+\&\f(CW$parent\fR\->\fBbuffered()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Plan \- Facet for setting the plan"
+.IX Subsection "Test2::EventFacet::Plan - Facet for setting the plan"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$plan\fR\->{details}, \f(CW$string\fR = \f(CW$plan\fR\->\fBdetails()\fR, \f(CW$positive_int\fR =
+\&\f(CW$plan\fR\->{count}, \f(CW$positive_int\fR = \f(CW$plan\fR\->\fBcount()\fR, \f(CW$bool\fR = \f(CW$plan\fR\->{skip},
+\&\f(CW$bool\fR = \f(CW$plan\fR\->\fBskip()\fR, \f(CW$bool\fR = \f(CW$plan\fR\->{none}, \f(CW$bool\fR = \f(CW$plan\fR\->\fBnone()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Render \- Facet that dictates how to render an event."
+.IX Subsection "Test2::EventFacet::Render - Facet that dictates how to render an event."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FIELDS 4
+.IX Item "FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$render\fR\->[#]\->{details}, \f(CW$string\fR = \f(CW$render\fR\->[#]\->\fBdetails()\fR,
+\&\f(CW$string\fR = \f(CW$render\fR\->[#]\->{tag}, \f(CW$string\fR = \f(CW$render\fR\->[#]\->\fBtag()\fR, \f(CW$string\fR =
+\&\f(CW$render\fR\->[#]\->{facet}, \f(CW$string\fR = \f(CW$render\fR\->[#]\->\fBfacet()\fR, \f(CW$mode\fR =
+\&\f(CW$render\fR\->[#]\->{mode}, \f(CW$mode\fR = \f(CW$render\fR\->[#]\->\fBmode()\fR, calculated, replace
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::EventFacet::Trace \- Debug information for events"
+.IX Subsection "Test2::EventFacet::Trace - Debug information for events"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP "FACET FIELDS" 4
+.IX Item "FACET FIELDS"
+.PD
+\&\f(CW$string\fR = \f(CW$trace\fR\->{details}, \f(CW$string\fR = \f(CW$trace\fR\->\fBdetails()\fR, \f(CW$frame\fR =
+\&\f(CW$trace\fR\->{frame}, \f(CW$frame\fR = \f(CW$trace\fR\->\fBframe()\fR, \f(CW$int\fR = \f(CW$trace\fR\->{pid}, \f(CW$int\fR =
+\&\f(CW$trace\fR\->\fBpid()\fR, \f(CW$int\fR = \f(CW$trace\fR\->{tid}, \f(CW$int\fR = \f(CW$trace\fR\->\fBtid()\fR, \f(CW$id\fR =
+\&\f(CW$trace\fR\->{cid}, \f(CW$id\fR = \f(CW$trace\fR\->\fBcid()\fR, \f(CW$uuid\fR = \f(CW$trace\fR\->{uuid}, \f(CW$uuid\fR =
+\&\f(CW$trace\fR\->\fBuuid()\fR, ($pkg, \f(CW$file\fR, \f(CW$line\fR, \f(CW$subname\fR) = \f(CW$trace\fR\->call, \f(CW@caller\fR =
+\&\f(CW$trace\fR\->full_call, \f(CW$warning_bits\fR = \f(CW$trace\fR\->warning_bits
+.RS 4
+.IP "DISCOURAGED HUB RELATED FIELDS" 4
+.IX Item "DISCOURAGED HUB RELATED FIELDS"
+\&\f(CW$hid\fR = \f(CW$trace\fR\->{hid}, \f(CW$hid\fR = \f(CW$trace\fR\->\fBhid()\fR, \f(CW$huuid\fR = \f(CW$trace\fR\->{huuid},
+\&\f(CW$huuid\fR = \f(CW$trace\fR\->\fBhuuid()\fR, \f(CW$int\fR = \f(CW$trace\fR\->{nested}, \f(CW$int\fR = \f(CW$trace\fR\->\fBnested()\fR,
+\&\f(CW$bool\fR = \f(CW$trace\fR\->{buffered}, \f(CW$bool\fR = \f(CW$trace\fR\->\fBbuffered()\fR
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+\&\f(CW$trace\fR\->set_detail($msg), \f(CW$msg\fR = \f(CW$trace\fR\->detail, \f(CW$str\fR = \f(CW$trace\fR\->debug,
+\&\f(CW$trace\fR\->alert($MESSAGE), \f(CW$trace\fR\->throw($MESSAGE), ($package, \f(CW$file\fR, \f(CW$line\fR,
+\&\f(CW$subname\fR) = \f(CW$trace\fR\->\fBcall()\fR, \f(CW$pkg\fR = \f(CW$trace\fR\->package, \f(CW$file\fR = \f(CW$trace\fR\->file,
+\&\f(CW$line\fR = \f(CW$trace\fR\->line, \f(CW$subname\fR = \f(CW$trace\fR\->subname, \f(CW$sig\fR = trace\->signature
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Formatter \- Namespace for formatters."
+.IX Subsection "Test2::Formatter - Namespace for formatters."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "CREATING FORMATTERS" 4
+.IX Item "CREATING FORMATTERS"
+.PD
+The number of tests that were planned, The number of tests actually seen,
+The number of tests which failed, A boolean indicating whether or not the
+test suite passed, A boolean indicating whether or not this call is for a
+subtest
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Formatter::TAP \- Standard TAP formatter"
+.IX Subsection "Test2::Formatter::TAP - Standard TAP formatter"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$bool\fR = \f(CW$tap\fR\->no_numbers, \f(CW$tap\fR\->set_no_numbers($bool), \f(CW$arrayref\fR =
+\&\f(CW$tap\fR\->handles, \f(CW$tap\fR\->set_handles(\e@handles);, \f(CW$encoding\fR = \f(CW$tap\fR\->encoding,
+\&\f(CW$tap\fR\->encoding($encoding), \f(CW$tap\fR\->write($e, \f(CW$num\fR)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>, Kent Fredric
+<kentnl@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Hub \- The conduit through which all events flow."
+.IX Subsection "Test2::Hub - The conduit through which all events flow."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "COMMON TASKS" 4
+.IX Item "COMMON TASKS"
+.RS 4
+.IP "SENDING EVENTS" 4
+.IX Item "SENDING EVENTS"
+.IP "ALTERING OR REMOVING EVENTS" 4
+.IX Item "ALTERING OR REMOVING EVENTS"
+.IP "LISTENING FOR EVENTS" 4
+.IX Item "LISTENING FOR EVENTS"
+.IP "POST-TEST BEHAVIORS" 4
+.IX Item "POST-TEST BEHAVIORS"
+.IP "SETTING THE FORMATTER" 4
+.IX Item "SETTING THE FORMATTER"
+.RE
+.RS 4
+.RE
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$hub\fR\->send($event), \f(CW$hub\fR\->process($event), \f(CW$old\fR = \f(CW$hub\fR\->format($formatter),
+\&\f(CW$sub\fR = \f(CW$hub\fR\->listen(sub { ... }, \f(CW%optional_params\fR), \f(CW$hub\fR\->unlisten($sub),
+\&\f(CW$sub\fR = \f(CW$hub\fR\->filter(sub { ... }, \f(CW%optional_params\fR), \f(CW$sub\fR =
+\&\f(CW$hub\fR\->pre_filter(sub { ... }, \f(CW%optional_params\fR), \f(CW$hub\fR\->unfilter($sub),
+\&\f(CW$hub\fR\->pre_unfilter($sub), \f(CW$hub\fR\->follow_op(sub { ... }), \f(CW$sub\fR =
+\&\f(CW$hub\fR\->add_context_acquire(sub { ... });,
+\&\f(CW$hub\fR\->remove_context_acquire($sub);, \f(CW$sub\fR = \f(CW$hub\fR\->add_context_init(sub {
+\&... });, \f(CW$hub\fR\->remove_context_init($sub);, \f(CW$sub\fR =
+\&\f(CW$hub\fR\->add_context_release(sub { ... });,
+\&\f(CW$hub\fR\->remove_context_release($sub);, \f(CW$hub\fR\->\fBcull()\fR, \f(CW$pid\fR = \f(CW$hub\fR\->\fBpid()\fR, \f(CW$tid\fR
+= \f(CW$hub\fR\->\fBtid()\fR, \f(CW$hud\fR = \f(CW$hub\fR\->\fBhid()\fR, \f(CW$uuid\fR = \f(CW$hub\fR\->\fBuuid()\fR, \f(CW$ipc\fR =
+\&\f(CW$hub\fR\->\fBipc()\fR, \f(CW$hub\fR\->set_no_ending($bool), \f(CW$bool\fR = \f(CW$hub\fR\->no_ending, \f(CW$bool\fR =
+\&\f(CW$hub\fR\->active, \f(CW$hub\fR\->set_active($bool)
+.RS 4
+.IP "STATE METHODS" 4
+.IX Item "STATE METHODS"
+\&\f(CW$hub\fR\->\fBreset_state()\fR, \f(CW$num\fR = \f(CW$hub\fR\->count, \f(CW$num\fR = \f(CW$hub\fR\->failed, \f(CW$bool\fR =
+\&\f(CW$hub\fR\->ended, \f(CW$bool\fR = \f(CW$hub\fR\->is_passing, \f(CW$hub\fR\->is_passing($bool),
+\&\f(CW$hub\fR\->plan($plan), \f(CW$plan\fR = \f(CW$hub\fR\->plan, \f(CW$bool\fR = \f(CW$hub\fR\->check_plan
+.RE
+.RS 4
+.RE
+.IP "THIRD PARTY META-DATA" 4
+.IX Item "THIRD PARTY META-DATA"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Hub::Interceptor \- Hub used by interceptor to grab results."
+.IX Subsection "Test2::Hub::Interceptor - Hub used by interceptor to grab results."
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Hub::Interceptor::Terminator \- Exception class used by Test2::Hub::Interceptor"
+.IX Subsection "Test2::Hub::Interceptor::Terminator - Exception class used by Test2::Hub::Interceptor"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Hub::Subtest \- Hub used by subtests"
+.IX Subsection "Test2::Hub::Subtest - Hub used by subtests"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP TOGGLES 4
+.IX Item "TOGGLES"
+.PD
+\&\f(CW$bool\fR = \f(CW$hub\fR\->manual_skip_all, \f(CW$hub\fR\->set_manual_skip_all($bool)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::IPC \- Turn on IPC for threading or forking support."
+.IX Subsection "Test2::IPC - Turn on IPC for threading or forking support."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP "DISABLING IT" 4
+.IX Item "DISABLING IT"
+.RE
+.RS 4
+.RE
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+\&\fBcull()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::IPC::Driver \- Base class for Test2 IPC drivers."
+.IX Subsection "Test2::IPC::Driver - Base class for Test2 IPC drivers."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\f(CW$self\fR\->abort($msg), \f(CW$self\fR\->abort_trace($msg)
+.IP "LOADING DRIVERS" 4
+.IX Item "LOADING DRIVERS"
+.PD 0
+.IP "WRITING DRIVERS" 4
+.IX Item "WRITING DRIVERS"
+.RS 4
+.IP "METHODS SUBCLASSES MUST IMPLEMENT" 4
+.IX Item "METHODS SUBCLASSES MUST IMPLEMENT"
+.PD
+\&\f(CW$ipc\fR\->is_viable, \f(CW$ipc\fR\->add_hub($hid), \f(CW$ipc\fR\->drop_hub($hid),
+\&\f(CW$ipc\fR\->send($hid, \f(CW$event\fR);, \f(CW$ipc\fR\->send($hid, \f(CW$event\fR, \f(CW$global\fR);, \f(CW@events\fR =
+\&\f(CW$ipc\fR\->cull($hid), \f(CW$ipc\fR\->\fBwaiting()\fR
+.IP "METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE" 4
+.IX Item "METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE"
+\&\f(CW$ipc\fR\->driver_abort($msg)
+.RE
+.RS 4
+.RE
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::IPC::Driver::Files \- Temp dir + Files concurrency model."
+.IX Subsection "Test2::IPC::Driver::Files - Temp dir + Files concurrency model."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP "ENVIRONMENT VARIABLES" 4
+.IX Item "ENVIRONMENT VARIABLES"
+.PD
+T2_KEEP_TEMPDIR=0, T2_TEMPDIR_TEMPLATE='test2\-XXXXXX'
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Tools::Tiny \- Tiny set of tools for unfortunate souls who cannot use Test2::Suite."
+.IX Subsection "Test2::Tools::Tiny - Tiny set of tools for unfortunate souls who cannot use Test2::Suite."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "USE Test2::Suite INSTEAD" 4
+.IX Item "USE Test2::Suite INSTEAD"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+ok($bool, \f(CW$name\fR), ok($bool, \f(CW$name\fR, \f(CW@diag\fR), is($got, \f(CW$want\fR, \f(CW$name\fR), is($got,
+\&\f(CW$want\fR, \f(CW$name\fR, \f(CW@diag\fR), isnt($got, \f(CW$do_not_want\fR, \f(CW$name\fR), isnt($got,
+\&\f(CW$do_not_want\fR, \f(CW$name\fR, \f(CW@diag\fR), like($got, \f(CW$regex\fR, \f(CW$name\fR), like($got, \f(CW$regex\fR,
+\&\f(CW$name\fR, \f(CW@diag\fR), unlike($got, \f(CW$regex\fR, \f(CW$name\fR), unlike($got, \f(CW$regex\fR, \f(CW$name\fR,
+\&\f(CW@diag\fR), is_deeply($got, \f(CW$want\fR, \f(CW$name\fR), is_deeply($got, \f(CW$want\fR, \f(CW$name\fR,
+\&\f(CW@diag\fR), diag($msg), note($msg), skip_all($reason), todo \f(CW$reason\fR => sub {
+\&... }, plan($count), \fBdone_testing()\fR, \f(CW$warnings\fR = warnings { ... },
+\&\f(CW$exception\fR = exception { ... }, tests \f(CW$name\fR => sub { ... }, \f(CW$output\fR =
+capture { ... }
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Transition \- Transition notes when upgrading to Test2"
+.IX Subsection "Test2::Transition - Transition notes when upgrading to Test2"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "THINGS THAT BREAK" 4
+.IX Item "THINGS THAT BREAK"
+.RS 4
+.IP "Test::Builder1.5/2 conditionals" 4
+.IX Item "Test::Builder1.5/2 conditionals"
+.IP "Replacing the Test::Builder singleton" 4
+.IX Item "Replacing the Test::Builder singleton"
+.IP "Directly Accessing Hash Elements" 4
+.IX Item "Directly Accessing Hash Elements"
+.IP "Subtest indentation" 4
+.IX Item "Subtest indentation"
+.RE
+.RS 4
+.RE
+.IP "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED" 4
+.IX Item "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED"
+.RS 4
+.IP "WORKS BUT TESTS WILL FAIL" 4
+.IX Item "WORKS BUT TESTS WILL FAIL"
+.PD
+Test::DBIx::Class::Schema, Device::Chip
+.IP "UPGRADE SUGGESTED" 4
+.IX Item "UPGRADE SUGGESTED"
+Test::Exception, Data::Peek, circular::require, Test::Module::Used,
+Test::Moose::More, Test::FITesque, Test::Kit, autouse
+.IP "NEED TO UPGRADE" 4
+.IX Item "NEED TO UPGRADE"
+Test::SharedFork, Test::Builder::Clutch, Test::Dist::VersionSync,
+Test::Modern, Test::UseAllModules, Test::More::Prefix
+.IP "STILL BROKEN" 4
+.IX Item "STILL BROKEN"
+Test::Aggregate, Test::Wrapper, Test::ParallelSubtest, Test::Pretty,
+Net::BitTorrent, Test::Group, Test::Flatten,
+Log::Dispatch::Config::TestLog, Test::Able
+.RE
+.RS 4
+.RE
+.IP "MAKE ASSERTIONS \-> SEND EVENTS" 4
+.IX Item "MAKE ASSERTIONS -> SEND EVENTS"
+.RS 4
+.PD 0
+.IP LEGACY 4
+.IX Item "LEGACY"
+.IP TEST2 4
+.IX Item "TEST2"
+.PD
+ok($bool, \f(CW$name\fR), diag(@messages), note(@messages), subtest($name, \f(CW$code\fR)
+.RE
+.RS 4
+.RE
+.IP "WRAP EXISTING TOOLS" 4
+.IX Item "WRAP EXISTING TOOLS"
+.RS 4
+.PD 0
+.IP LEGACY 4
+.IX Item "LEGACY"
+.IP TEST2 4
+.IX Item "TEST2"
+.RE
+.RS 4
+.RE
+.IP "USING UTF8" 4
+.IX Item "USING UTF8"
+.RS 4
+.IP LEGACY 4
+.IX Item "LEGACY"
+.IP TEST2 4
+.IX Item "TEST2"
+.RE
+.RS 4
+.RE
+.IP "AUTHORS, CONTRIBUTORS AND REVIEWERS" 4
+.IX Item "AUTHORS, CONTRIBUTORS AND REVIEWERS"
+.PD
+Chad Granum (EXODIST) <exodist@cpan.org>
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Util \- Tools used by Test2 and friends."
+.IX Subsection "Test2::Util - Tools used by Test2 and friends."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+($success, \f(CW$error\fR) = try { ... }, protect { ... }, CAN_FORK,
+CAN_REALLY_FORK, CAN_THREAD, USE_THREADS, get_tid, my \f(CW$file\fR =
+pkg_to_file($package), \f(CW$string\fR = \fBipc_separator()\fR, \f(CW$string\fR = \fBgen_uid()\fR,
+($ok, \f(CW$err\fR) = do_rename($old_name, \f(CW$new_name\fR), ($ok, \f(CW$err\fR) =
+do_unlink($filename), ($ok, \f(CW$err\fR) = try_sig_mask { ... }, SIGINT, SIGALRM,
+SIGHUP, SIGTERM, SIGUSR1, SIGUSR2
+.IP "NOTES && CAVEATS" 4
+.IX Item "NOTES && CAVEATS"
+Devel::Cover
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>, Kent Fredric
+<kentnl@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Util::ExternalMeta \- Allow third party tools to safely attach meta-data to your instances."
+.IX Subsection "Test2::Util::ExternalMeta - Allow third party tools to safely attach meta-data to your instances."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP "WHERE IS THE DATA STORED?" 4
+.IX Item "WHERE IS THE DATA STORED?"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+\&\f(CW$val\fR = \f(CW$obj\fR\->meta($key), \f(CW$val\fR = \f(CW$obj\fR\->meta($key, \f(CW$default\fR), \f(CW$val\fR =
+\&\f(CW$obj\fR\->get_meta($key), \f(CW$val\fR = \f(CW$obj\fR\->delete_meta($key), \f(CW$obj\fR\->set_meta($key,
+\&\f(CW$val\fR)
+.IP "META-KEY RESTRICTIONS" 4
+.IX Item "META-KEY RESTRICTIONS"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Util::Facets2Legacy \- Convert facet data to the legacy event API."
+.IX Subsection "Test2::Util::Facets2Legacy - Convert facet data to the legacy event API."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.RS 4
+.IP "AS METHODS" 4
+.IX Item "AS METHODS"
+.IP "AS FUNCTIONS" 4
+.IX Item "AS FUNCTIONS"
+.RE
+.RS 4
+.RE
+.IP "NOTE ON CYCLES" 4
+.IX Item "NOTE ON CYCLES"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+\&\f(CW$bool\fR = \f(CW$e\fR\->\fBcauses_fail()\fR, \f(CW$bool\fR = causes_fail($f), \f(CW$bool\fR =
+\&\f(CW$e\fR\->\fBdiagnostics()\fR, \f(CW$bool\fR = diagnostics($f), \f(CW$bool\fR = \f(CW$e\fR\->\fBglobal()\fR, \f(CW$bool\fR =
+global($f), \f(CW$bool\fR = \f(CW$e\fR\->\fBincrements_count()\fR, \f(CW$bool\fR = increments_count($f),
+\&\f(CW$bool\fR = \f(CW$e\fR\->\fBno_display()\fR, \f(CW$bool\fR = no_display($f), ($max, \f(CW$directive\fR,
+\&\f(CW$reason\fR) = \f(CW$e\fR\->\fBsets_plan()\fR, ($max, \f(CW$directive\fR, \f(CW$reason\fR) = sets_plan($f),
+\&\f(CW$id\fR = \f(CW$e\fR\->\fBsubtest_id()\fR, \f(CW$id\fR = subtest_id($f), \f(CW$string\fR = \f(CW$e\fR\->\fBsummary()\fR,
+\&\f(CW$string\fR = summary($f), \f(CW$undef_or_int\fR = \f(CW$e\fR\->\fBterminate()\fR, \f(CW$undef_or_int\fR =
+terminate($f), \f(CW$uuid\fR = \f(CW$e\fR\->\fBuuid()\fR, \f(CW$uuid\fR = uuid($f)
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Util::HashBase \- Build hash based classes."
+.IX Subsection "Test2::Util::HashBase - Build hash based classes."
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "THIS IS A BUNDLED COPY OF HASHBASE" 4
+.IX Item "THIS IS A BUNDLED COPY OF HASHBASE"
+.IP METHODS 4
+.IX Item "METHODS"
+.RS 4
+.IP "PROVIDED BY HASH BASE" 4
+.IX Item "PROVIDED BY HASH BASE"
+.PD
+\&\f(CW$it\fR = \f(CW$class\fR\->new(%PAIRS), \f(CW$it\fR = \f(CW$class\fR\->new(\e%PAIRS), \f(CW$it\fR =
+\&\f(CW$class\fR\->new(\e@ORDERED_VALUES)
+.IP HOOKS 4
+.IX Item "HOOKS"
+\&\f(CW$self\fR\->\fBinit()\fR
+.RE
+.RS 4
+.RE
+.IP ACCESSORS 4
+.IX Item "ACCESSORS"
+.RS 4
+.PD 0
+.IP READ/WRITE 4
+.IX Item "READ/WRITE"
+.PD
+\&\fBfoo()\fR, \fBset_foo()\fR, \fBFOO()\fR
+.IP "READ ONLY" 4
+.IX Item "READ ONLY"
+\&\fBset_foo()\fR
+.IP "DEPRECATED SETTER" 4
+.IX Item "DEPRECATED SETTER"
+\&\fBset_foo()\fR
+.IP "NO SETTER" 4
+.IX Item "NO SETTER"
+.PD 0
+.IP "NO READER" 4
+.IX Item "NO READER"
+.IP "CONSTANT ONLY" 4
+.IX Item "CONSTANT ONLY"
+.RE
+.RS 4
+.RE
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.IP "GETTING A LIST OF ATTRIBUTES FOR A CLASS" 4
+.IX Item "GETTING A LIST OF ATTRIBUTES FOR A CLASS"
+.PD
+\&\f(CW@list\fR = Test2::Util::HashBase::attr_list($class), \f(CW@list\fR =
+\&\f(CW$class\fR\->\fBTest2::Util::HashBase::attr_list()\fR
+.IP SOURCE 4
+.IX Item "SOURCE"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test2::Util::Trace \- Legacy wrapper fro Test2::EventFacet::Trace."
+.IX Subsection "Test2::Util::Trace - Legacy wrapper fro Test2::EventFacet::Trace."
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::Builder \- Backend for building test libraries"
+.IX Subsection "Test::Builder - Backend for building test libraries"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Construction 4
+.IX Item "Construction"
+.PD
+\&\fBnew\fR, \fBcreate\fR, \fBsubtest\fR, \fBname\fR, \fBreset\fR
+.IP "Setting up tests" 4
+.IX Item "Setting up tests"
+\&\fBplan\fR, \fBexpected_tests\fR, \fBno_plan\fR, \fBdone_testing\fR, \fBhas_plan\fR,
+\&\fBskip_all\fR, \fBexported_to\fR
+.IP "Running tests" 4
+.IX Item "Running tests"
+\&\fBok\fR, \fBis_eq\fR, \fBis_num\fR, \fBisnt_eq\fR, \fBisnt_num\fR, \fBlike\fR, \fBunlike\fR,
+\&\fBcmp_ok\fR
+.IP "Other Testing Methods" 4
+.IX Item "Other Testing Methods"
+\&\fBBAIL_OUT\fR, \fBskip\fR, \fBtodo_skip\fR, \fBskip_rest\fR
+.IP "Test building utility methods" 4
+.IX Item "Test building utility methods"
+\&\fBmaybe_regex\fR, \fBis_fh\fR
+.RE
+.RS 4
+.RE
+.IP "Test style" 4
+.IX Item "Test style"
+\&\fBlevel\fR, \fBuse_numbers\fR, \fBno_diag\fR, \fBno_ending\fR, \fBno_header\fR
+.IP Output 4
+.IX Item "Output"
+\&\fBdiag\fR, \fBnote\fR, \fBexplain\fR, \fBoutput\fR, \fBfailure_output\fR, \fBtodo_output\fR,
+reset_outputs, carp, croak
+.IP "Test Status and Info" 4
+.IX Item "Test Status and Info"
+\&\fBno_log_results\fR, \fBcurrent_test\fR, \fBis_passing\fR, \fBsummary\fR, \fBdetails\fR,
+\&\fBtodo\fR, \fBfind_TODO\fR, \fBin_todo\fR, \fBtodo_start\fR, \f(CW\*(C`todo_end\*(C'\fR, \fBcaller\fR
+.IP "EXIT CODES" 4
+.IX Item "EXIT CODES"
+.PD 0
+.IP THREADS 4
+.IX Item "THREADS"
+.IP MEMORY 4
+.IX Item "MEMORY"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP INTERNALS 4
+.IX Item "INTERNALS"
+.IP LEGACY 4
+.IX Item "LEGACY"
+.IP EXTERNAL 4
+.IX Item "EXTERNAL"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::Builder::Formatter \- Test::Builder subclass of Test2::Formatter::TAP"
+.IX Subsection "Test::Builder::Formatter - Test::Builder subclass of Test2::Formatter::TAP"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::Builder::IO::Scalar \- A copy of IO::Scalar for Test::Builder"
+.IX Subsection "Test::Builder::IO::Scalar - A copy of IO::Scalar for Test::Builder"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "COPYRIGHT and LICENSE" 4
+.IX Item "COPYRIGHT and LICENSE"
+.IP Construction 4
+.IX Item "Construction"
+.PD
+.PP
+new [ARGS...]
+.PP
+open [SCALARREF]
+.PP
+opened
+.PP
+close
+.IP "Input and output" 4
+.IX Item "Input and output"
+.PP
+flush
+.PP
+getc
+.PP
+getline
+.PP
+getlines
+.PP
+print ARGS..
+.PP
+read BUF, NBYTES, [OFFSET]
+.PP
+write BUF, NBYTES, [OFFSET]
+.PP
+sysread BUF, LEN, [OFFSET]
+.PP
+syswrite BUF, NBYTES, [OFFSET]
+.IP "Seeking/telling and other attributes" 4
+.IX Item "Seeking/telling and other attributes"
+.PP
+autoflush
+.PP
+binmode
+.PP
+clearerr
+.PP
+eof
+.PP
+seek OFFSET, WHENCE
+.PP
+sysseek OFFSET, WHENCE
+.PP
+tell
+.PP
+.Vb 1
+\& use_RS [YESNO]
+.Ve
+.PP
+setpos POS
+.PP
+getpos
+.PP
+sref
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.RS 4
+.IP "Primary Maintainer" 4
+.IX Item "Primary Maintainer"
+.IP "Principal author" 4
+.IX Item "Principal author"
+.IP "Other contributors" 4
+.IX Item "Other contributors"
+.RE
+.RS 4
+.RE
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Test::Builder::Module \- Base class for test modules"
+.IX Subsection "Test::Builder::Module - Base class for test modules"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Importing 4
+.IX Item "Importing"
+.RE
+.RS 4
+.RE
+.IP Builder 4
+.IX Item "Builder"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Test::Builder::Tester \- test testsuites that have been built with Test::Builder"
+.IX Subsection "Test::Builder::Tester - test testsuites that have been built with Test::Builder"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP Functions 4
+.IX Item "Functions"
+.PD
+test_out, test_err
+.PP
+test_fail
+.PP
+test_diag
+.PP
+test_test, title (synonym 'name', 'label'), skip_out, skip_err
+.PP
+line_num
+.PP
+color
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Test::Builder::Tester::Color \- turn on colour in Test::Builder::Tester"
+.IX Subsection "Test::Builder::Tester::Color - turn on colour in Test::Builder::Tester"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Test::Builder::TodoDiag \- Test::Builder subclass of Test2::Event::Diag"
+.IX Subsection "Test::Builder::TodoDiag - Test::Builder subclass of Test2::Event::Diag"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::Harness \- Run Perl standard test scripts with statistics"
+.IX Subsection "Test::Harness - Run Perl standard test scripts with statistics"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.ie n .IP "runtests( @test_files )" 4
+.el .IP "runtests( \f(CW@test_files\fR )" 4
+.IX Item "runtests( @test_files )"
+.RE
+.RS 4
+.RE
+.IP "execute_tests( tests => \e@test_files, out => \e*FH )" 4
+.IX Item "execute_tests( tests => @test_files, out => *FH )"
+.IP EXPORT 4
+.IX Item "EXPORT"
+.IP "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS" 4
+.IX Item "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS"
+.PD
+\&\f(CW\*(C`HARNESS_ACTIVE\*(C'\fR, \f(CW\*(C`HARNESS_VERSION\*(C'\fR
+.IP "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS" 4
+.IX Item "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS"
+\&\f(CW\*(C`HARNESS_PERL_SWITCHES\*(C'\fR, \f(CW\*(C`HARNESS_TIMER\*(C'\fR, \f(CW\*(C`HARNESS_VERBOSE\*(C'\fR,
+\&\f(CW\*(C`HARNESS_OPTIONS\*(C'\fR, \f(CW\*(C`j<n>\*(C'\fR, \f(CW\*(C`c\*(C'\fR, \f(CW\*(C`a<file.tgz>\*(C'\fR, \f(CW\*(C`fPackage\-With\-Dashes\*(C'\fR, \f(CW\*(C`HARNESS_SUBCLASS\*(C'\fR,
+\&\f(CW\*(C`HARNESS_SUMMARY_COLOR_SUCCESS\*(C'\fR, \f(CW\*(C`HARNESS_SUMMARY_COLOR_FAIL\*(C'\fR
+.IP "Taint Mode" 4
+.IX Item "Taint Mode"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "LICENCE AND COPYRIGHT" 4
+.IX Item "LICENCE AND COPYRIGHT"
+.PD
+.SS "Test::More \- yet another framework for writing test scripts"
+.IX Subsection "Test::More - yet another framework for writing test scripts"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "I love it when a plan comes together" 4
+.IX Item "I love it when a plan comes together"
+.RE
+.RS 4
+.RE
+.PD
+.PP
+\&\fBdone_testing\fR
+.IP "Test names" 4
+.IX Item "Test names"
+.PD 0
+.IP "I'm ok, you're not ok." 4
+.IX Item "I'm ok, you're not ok."
+.PD
+\&\fBok\fR
+.PP
+\&\fBis\fR, \fBisnt\fR
+.PP
+\&\fBlike\fR
+.PP
+\&\fBunlike\fR
+.PP
+\&\fBcmp_ok\fR
+.PP
+\&\fBcan_ok\fR
+.PP
+\&\fBisa_ok\fR
+.PP
+\&\fBnew_ok\fR
+.PP
+\&\fBsubtest\fR
+.PP
+\&\fBpass\fR, \fBfail\fR
+.IP "Module tests" 4
+.IX Item "Module tests"
+\&\fBrequire_ok\fR
+.PP
+\&\fBuse_ok\fR
+.IP "Complex data structures" 4
+.IX Item "Complex data structures"
+\&\fBis_deeply\fR
+.IP Diagnostics 4
+.IX Item "Diagnostics"
+\&\fBdiag\fR, \fBnote\fR
+.PP
+\&\fBexplain\fR
+.IP "Conditional tests" 4
+.IX Item "Conditional tests"
+\&\fBSKIP: BLOCK\fR
+.PP
+\&\fBTODO: BLOCK\fR, \fBtodo_skip\fR
+.PP
+When do I use SKIP vs. TODO?
+.IP "Test control" 4
+.IX Item "Test control"
+\&\fBBAIL_OUT\fR
+.IP "Discouraged comparison functions" 4
+.IX Item "Discouraged comparison functions"
+\&\fBeq_array\fR
+.PP
+\&\fBeq_hash\fR
+.PP
+\&\fBeq_set\fR
+.IP "Extending and Embedding Test::More" 4
+.IX Item "Extending and Embedding Test::More"
+\&\fBbuilder\fR
+.IP "EXIT CODES" 4
+.IX Item "EXIT CODES"
+.PD 0
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.PD
+subtests, \f(CWdone_testing()\fR, \f(CWcmp_ok()\fR, \f(CWnew_ok()\fR \f(CWnote()\fR and
+\&\f(CWexplain()\fR
+.IP "CAVEATS and NOTES" 4
+.IX Item "CAVEATS and NOTES"
+utf8 / "Wide character in print", Overloaded objects, Threads
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.RS 4
+.IP ALTERNATIVES 4
+.IX Item "ALTERNATIVES"
+.IP "ADDITIONAL LIBRARIES" 4
+.IX Item "ADDITIONAL LIBRARIES"
+.IP "OTHER COMPONENTS" 4
+.IX Item "OTHER COMPONENTS"
+.IP BUNDLES 4
+.IX Item "BUNDLES"
+.RE
+.RS 4
+.RE
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP BUGS 4
+.IX Item "BUGS"
+.PD 0
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.PD
+.SS "Test::Simple \- Basic utilities for writing tests."
+.IX Subsection "Test::Simple - Basic utilities for writing tests."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\fBok\fR
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP NOTES 4
+.IX Item "NOTES"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+Test::More
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.PD 0
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::Tester \- Ease testing test modules built with Test::Builder"
+.IX Subsection "Test::Tester - Ease testing test modules built with Test::Builder"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "HOW TO USE (THE EASY WAY)" 4
+.IX Item "HOW TO USE (THE EASY WAY)"
+.IP "HOW TO USE (THE HARD WAY)" 4
+.IX Item "HOW TO USE (THE HARD WAY)"
+.IP "TEST RESULTS" 4
+.IX Item "TEST RESULTS"
+.PD
+ok, actual_ok, name, type, reason, diag, depth
+.IP "SPACES AND TABS" 4
+.IX Item "SPACES AND TABS"
+.PD 0
+.IP COLOUR 4
+.IX Item "COLOUR"
+.IP "EXPORTED FUNCTIONS" 4
+.IX Item "EXPORTED FUNCTIONS"
+.IP "HOW IT WORKS" 4
+.IX Item "HOW IT WORKS"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Test::Tester::Capture \- Help testing test modules built with Test::Builder"
+.IX Subsection "Test::Tester::Capture - Help testing test modules built with Test::Builder"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Test::Tester::CaptureRunner \- Help testing test modules built with Test::Builder"
+.IX Subsection "Test::Tester::CaptureRunner - Help testing test modules built with Test::Builder"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Test::Tutorial \- A tutorial about writing really basic tests"
+.IX Subsection "Test::Tutorial - A tutorial about writing really basic tests"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.PD 0
+.IP "Nuts and bolts of testing." 4
+.IX Item "Nuts and bolts of testing."
+.IP "Where to start?" 4
+.IX Item "Where to start?"
+.IP Names 4
+.IX Item "Names"
+.IP "Test the manual" 4
+.IX Item "Test the manual"
+.IP "Sometimes the tests are wrong" 4
+.IX Item "Sometimes the tests are wrong"
+.IP "Testing lots of values" 4
+.IX Item "Testing lots of values"
+.IP "Informative names" 4
+.IX Item "Informative names"
+.IP "Skipping tests" 4
+.IX Item "Skipping tests"
+.IP "Todo tests" 4
+.IX Item "Todo tests"
+.IP "Testing with taint mode." 4
+.IX Item "Testing with taint mode."
+.RE
+.RS 4
+.RE
+.IP FOOTNOTES 4
+.IX Item "FOOTNOTES"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP MAINTAINERS 4
+.IX Item "MAINTAINERS"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.SS "Test::use::ok \- Alternative to Test::More::use_ok"
+.IX Subsection "Test::use::ok - Alternative to Test::More::use_ok"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.PD
+Chad Granum <exodist@cpan.org>
+.IP "CC0 1.0 Universal" 4
+.IX Item "CC0 1.0 Universal"
+.SS "Text::Abbrev \- abbrev \- create an abbreviation table from a list"
+.IX Subsection "Text::Abbrev - abbrev - create an abbreviation table from a list"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD
+.SS "Text::Balanced \- Extract delimited text sequences from strings."
+.IX Subsection "Text::Balanced - Extract delimited text sequences from strings."
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "General Behaviour in List Contexts" 4
+.IX Item "General Behaviour in List Contexts"
+.PD
+[0], [1], [2]
+.IP "General Behaviour in Scalar and Void Contexts" 4
+.IX Item "General Behaviour in Scalar and Void Contexts"
+.PD 0
+.IP "A Note About Prefixes" 4
+.IX Item "A Note About Prefixes"
+.IP Functions 4
+.IX Item "Functions"
+.PD
+\&\f(CW\*(C`extract_delimited\*(C'\fR, \f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_variable\*(C'\fR, [0], [1],
+[2], \f(CW\*(C`extract_tagged\*(C'\fR, \f(CW\*(C`reject => $listref\*(C'\fR, \f(CWignore =>
+$listref\fR, \f(CW\*(C`fail => $str\*(C'\fR, [0], [1], [2], [3], [4], [5],
+\&\f(CW\*(C`gen_extract_tagged\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR, [0], [1], [2], [3], [4], [5],
+[6], [7], [8], [9], [10], \f(CW\*(C`extract_quotelike\*(C'\fR, [0], [1], [2], [3], [4],
+[5], [6], [7..10], \f(CW\*(C`extract_codeblock\*(C'\fR, \f(CW\*(C`extract_multiple\*(C'\fR,
+\&\f(CW\*(C`gen_delimited_pat\*(C'\fR, \f(CW\*(C`delimited_pat\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.Vb 10
+\& C<Did not find a suitable bracket: "%s">,  C<Did not find prefix: /%s/>, 
+\&C<Did not find opening bracket after prefix: "%s">,  C<No quotelike
+\&operator found after prefix: "%s">,  C<Unmatched closing bracket: "%c">, 
+\&C<Unmatched opening bracket(s): "%s">, C<Unmatched embedded quote (%s)>,
+\&C<Did not find closing delimiter to match \*(Aq%s\*(Aq>,  C<Mismatched closing
+\&bracket: expected "%c" but found "%s">,  C<No block delimiter found after
+\&quotelike "%s">, C<Did not find leading dereferencer>, C<Bad identifier
+\&after dereferencer>, C<Did not find expected opening bracket at %s>,
+\&C<Improperly nested codeblock at %s>,  C<Missing second block for quotelike
+\&"%s">, C<No match found for opening bracket>, C<Did not find opening tag:
+\&/%s/>, C<Unable to construct closing tag to match: /%s/>, C<Found invalid
+\&nested tag: %s>, C<Found unbalanced nested tag: %s>, C<Did not find closing
+\&tag>
+.Ve
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+Default Exports, Optional Exports, Export Tags, \f(CW\*(C`:ALL\*(C'\fR
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.PD 0
+.IP FEEDBACK 4
+.IX Item "FEEDBACK"
+.IP AVAILABILITY 4
+.IX Item "AVAILABILITY"
+.IP INSTALLATION 4
+.IX Item "INSTALLATION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP COPYRIGHT 4
+.IX Item "COPYRIGHT"
+.IP LICENCE 4
+.IX Item "LICENCE"
+.IP VERSION 4
+.IX Item "VERSION"
+.IP DATE 4
+.IX Item "DATE"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+.SS "Text::ParseWords \- parse text into an array of tokens or array of arrays"
+.IX Subsection "Text::ParseWords - parse text into an array of tokens or array of arrays"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+true, false, \f(CW"delimiters"\fR
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+0, 1, 2, 3, 4, 5
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD 0
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Text::Tabs \- expand and unexpand tabs like unix \fBexpand\fP\|(1) and \fBunexpand\fP\|(1)"
+.IX Subsection "Text::Tabs - expand and unexpand tabs like unix expand and unexpand"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+expand, unexpand, \f(CW$tabstop\fR
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.PD 0
+.IP BUGS 4
+.IX Item "BUGS"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Text::Wrap \- line wrapping to form simple paragraphs"
+.IX Subsection "Text::Wrap - line wrapping to form simple paragraphs"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP OVERRIDES 4
+.IX Item "OVERRIDES"
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Thread \- Manipulate threads in Perl (for old code only)"
+.IX Subsection "Thread - Manipulate threads in Perl (for old code only)"
+.IP DEPRECATED 4
+.IX Item "DEPRECATED"
+.PD 0
+.IP HISTORY 4
+.IX Item "HISTORY"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.PD
+\&\f(CW$thread\fR = Thread\->new(\e&start_sub), \f(CW$thread\fR = Thread\->new(\e&start_sub,
+LIST), lock VARIABLE, async BLOCK;, Thread\->self, Thread\->list, cond_wait
+VARIABLE, cond_signal VARIABLE, cond_broadcast VARIABLE, yield
+.IP METHODS 4
+.IX Item "METHODS"
+join, detach, equal, tid, done
+.IP DEFUNCT 4
+.IX Item "DEFUNCT"
+lock(\e&sub), eval, flags
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.SS "Thread::Queue \- Thread-safe queues"
+.IX Subsection "Thread::Queue - Thread-safe queues"
+.PD 0
+.IP VERSION 4
+.IX Item "VERSION"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+Ordinary scalars, Array refs, Hash refs, Scalar refs, Objects based on the
+above
+.IP "QUEUE CREATION" 4
+.IX Item "QUEUE CREATION"
+\&\->\fBnew()\fR, \->new(LIST)
+.IP "BASIC METHODS" 4
+.IX Item "BASIC METHODS"
+\&\->enqueue(LIST), \->\fBdequeue()\fR, \->dequeue(COUNT), \->\fBdequeue_nb()\fR,
+\&\->dequeue_nb(COUNT), \->dequeue_timed(TIMEOUT), \->dequeue_timed(TIMEOUT,
+COUNT), \->\fBpending()\fR, \->limit, \->\fBend()\fR
+.IP "ADVANCED METHODS" 4
+.IX Item "ADVANCED METHODS"
+\&\->\fBpeek()\fR, \->peek(INDEX), \->insert(INDEX, LIST), \->\fBextract()\fR,
+\&\->extract(INDEX), \->extract(INDEX, COUNT)
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Thread::Semaphore \- Thread-safe semaphores"
+.IX Subsection "Thread::Semaphore - Thread-safe semaphores"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.PD
+\&\->\fBnew()\fR, \->new(NUMBER), \->\fBdown()\fR, \->down(NUMBER), \->\fBdown_nb()\fR,
+\&\->down_nb(NUMBER), \->\fBdown_force()\fR, \->down_force(NUMBER),
+\&\->down_timed(TIMEOUT), \->down_timed(TIMEOUT, NUMBER), \->\fBup()\fR, \->up(NUMBER)
+.IP NOTES 4
+.IX Item "NOTES"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP MAINTAINER 4
+.IX Item "MAINTAINER"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.PD
+.SS "Tie::Array \- base class for tied arrays"
+.IX Subsection "Tie::Array - base class for tied arrays"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+TIEARRAY classname, LIST, STORE this, index, value, FETCH this, index,
+FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this,
+key, DELETE this, key, CLEAR this, DESTROY this, PUSH this, LIST, POP this,
+SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Tie::File \- Access the lines of a disk file via a Perl array"
+.IX Subsection "Tie::File - Access the lines of a disk file via a Perl array"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP """recsep""" 4
+.el .IP \f(CWrecsep\fR 4
+.IX Item "recsep"
+.ie n .IP """autochomp""" 4
+.el .IP \f(CWautochomp\fR 4
+.IX Item "autochomp"
+.ie n .IP """mode""" 4
+.el .IP \f(CWmode\fR 4
+.IX Item "mode"
+.ie n .IP """memory""" 4
+.el .IP \f(CWmemory\fR 4
+.IX Item "memory"
+.ie n .IP """dw_size""" 4
+.el .IP \f(CWdw_size\fR 4
+.IX Item "dw_size"
+.IP "Option Format" 4
+.IX Item "Option Format"
+.RE
+.RS 4
+.RE
+.IP "Public Methods" 4
+.IX Item "Public Methods"
+.RS 4
+.ie n .IP """flock""" 4
+.el .IP \f(CWflock\fR 4
+.IX Item "flock"
+.ie n .IP """autochomp""" 4
+.el .IP \f(CWautochomp\fR 4
+.IX Item "autochomp"
+.ie n .IP """defer"", ""flush"", ""discard"", and ""autodefer""" 4
+.el .IP "\f(CWdefer\fR, \f(CWflush\fR, \f(CWdiscard\fR, and \f(CWautodefer\fR" 4
+.IX Item "defer, flush, discard, and autodefer"
+.ie n .IP """offset""" 4
+.el .IP \f(CWoffset\fR 4
+.IX Item "offset"
+.RE
+.RS 4
+.RE
+.IP "Tying to an already-opened filehandle" 4
+.IX Item "Tying to an already-opened filehandle"
+.IP "Deferred Writing" 4
+.IX Item "Deferred Writing"
+.RS 4
+.IP Autodeferring 4
+.IX Item "Autodeferring"
+.RE
+.RS 4
+.RE
+.IP "CONCURRENT ACCESS TO FILES" 4
+.IX Item "CONCURRENT ACCESS TO FILES"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP SUBCLASSING 4
+.IX Item "SUBCLASSING"
+.ie n .IP "WHAT ABOUT ""DB_File""?" 4
+.el .IP "WHAT ABOUT \f(CWDB_File\fR?" 4
+.IX Item "WHAT ABOUT DB_File?"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP WARRANTY 4
+.IX Item "WARRANTY"
+.IP THANKS 4
+.IX Item "THANKS"
+.IP TODO 4
+.IX Item "TODO"
+.PD
+.SS "Tie::Handle \- base class definitions for tied handles"
+.IX Subsection "Tie::Handle - base class definitions for tied handles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+TIEHANDLE classname, LIST, WRITE this, scalar, length, offset, PRINT this,
+LIST, PRINTF this, format, LIST, READ this, scalar, length, offset,
+READLINE this, GETC this, CLOSE this, OPEN this, filename, BINMODE this,
+EOF this, TELL this, SEEK this, offset, whence, DESTROY this
+.IP "MORE INFORMATION" 4
+.IX Item "MORE INFORMATION"
+.PD 0
+.IP COMPATIBILITY 4
+.IX Item "COMPATIBILITY"
+.PD
+.SS "Tie::Hash, Tie::StdHash, Tie::ExtraHash \- base class definitions for tied hashes"
+.IX Subsection "Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for tied hashes"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+TIEHASH classname, LIST, STORE this, key, value, FETCH this, key, FIRSTKEY
+this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR
+this, SCALAR this
+.IP "Inheriting from \fBTie::StdHash\fR" 4
+.IX Item "Inheriting from Tie::StdHash"
+.PD 0
+.IP "Inheriting from \fBTie::ExtraHash\fR" 4
+.IX Item "Inheriting from Tie::ExtraHash"
+.ie n .IP """SCALAR"", ""UNTIE"" and ""DESTROY""" 4
+.el .IP "\f(CWSCALAR\fR, \f(CWUNTIE\fR and \f(CWDESTROY\fR" 4
+.IX Item "SCALAR, UNTIE and DESTROY"
+.IP "MORE INFORMATION" 4
+.IX Item "MORE INFORMATION"
+.PD
+.SS "Tie::Hash::NamedCapture \- Named regexp capture buffers"
+.IX Subsection "Tie::Hash::NamedCapture - Named regexp capture buffers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+.SS "Tie::Memoize \- add data to hash when needed"
+.IX Subsection "Tie::Memoize - add data to hash when needed"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "Inheriting from \fBTie::Memoize\fR" 4
+.IX Item "Inheriting from Tie::Memoize"
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Tie::RefHash \- Use references as hash keys"
+.IX Subsection "Tie::RefHash - Use references as hash keys"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP EXAMPLE 4
+.IX Item "EXAMPLE"
+.IP "THREAD SUPPORT" 4
+.IX Item "THREAD SUPPORT"
+.IP "STORABLE SUPPORT" 4
+.IX Item "STORABLE SUPPORT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP SUPPORT 4
+.IX Item "SUPPORT"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENCE" 4
+.IX Item "COPYRIGHT AND LICENCE"
+.PD
+.SS "Tie::Scalar, Tie::StdScalar \- base class definitions for tied scalars"
+.IX Subsection "Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this
+.RS 4
+.IP "Tie::Scalar vs Tie::StdScalar" 4
+.IX Item "Tie::Scalar vs Tie::StdScalar"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP "MORE INFORMATION" 4
+.IX Item "MORE INFORMATION"
+.PD
+.SS "Tie::StdHandle \- base class definitions for tied handles"
+.IX Subsection "Tie::StdHandle - base class definitions for tied handles"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+.SS "Tie::SubstrHash \- Fixed-table-size, fixed-key-length hashing"
+.IX Subsection "Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+.SS "Time::HiRes \- High resolution alarm, sleep, gettimeofday, interval timers"
+.IX Subsection "Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+gettimeofday (), usleep ( \f(CW$useconds\fR ), nanosleep ( \f(CW$nanoseconds\fR ), ualarm (
+\&\f(CW$useconds\fR [, \f(CW$interval_useconds\fR ] ), tv_interval, time (), sleep (
+\&\f(CW$floating_seconds\fR ), alarm ( \f(CW$floating_seconds\fR [,
+\&\f(CW$interval_floating_seconds\fR ] ), setitimer ( \f(CW$which\fR, \f(CW$floating_seconds\fR [,
+\&\f(CW$interval_floating_seconds\fR ] ), getitimer ( \f(CW$which\fR ), clock_gettime (
+\&\f(CW$which\fR ), clock_getres ( \f(CW$which\fR ), clock_nanosleep ( \f(CW$which\fR, \f(CW$nanoseconds\fR,
+\&\f(CW$flags\fR = 0), \fBclock()\fR, stat, stat FH, stat EXPR, lstat, lstat FH, lstat
+EXPR, utime LIST
+.IP EXAMPLES 4
+.IX Item "EXAMPLES"
+.PD 0
+.IP "C API" 4
+.IX Item "C API"
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.RS 4
+.IP "useconds or interval more than ..." 4
+.IX Item "useconds or interval more than ..."
+.IP "negative time not invented yet" 4
+.IX Item "negative time not invented yet"
+.IP "internal error: useconds < 0 (unsigned ... signed ...)" 4
+.IX Item "internal error: useconds < 0 (unsigned ... signed ...)"
+.IP "useconds or uinterval equal to or more than 1000000" 4
+.IX Item "useconds or uinterval equal to or more than 1000000"
+.IP "unimplemented in this platform" 4
+.IX Item "unimplemented in this platform"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Time::Local \- Efficiently compute time from local and GMT time"
+.IX Subsection "Time::Local - Efficiently compute time from local and GMT time"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP FUNCTIONS 4
+.IX Item "FUNCTIONS"
+.RS 4
+.ie n .IP "timelocal_posix() and timegm_posix()" 4
+.el .IP "\f(CWtimelocal_posix()\fR and \f(CWtimegm_posix()\fR" 4
+.IX Item "timelocal_posix() and timegm_posix()"
+.ie n .IP "timelocal_modern() and timegm_modern()" 4
+.el .IP "\f(CWtimelocal_modern()\fR and \f(CWtimegm_modern()\fR" 4
+.IX Item "timelocal_modern() and timegm_modern()"
+.ie n .IP "timelocal() and timegm()" 4
+.el .IP "\f(CWtimelocal()\fR and \f(CWtimegm()\fR" 4
+.IX Item "timelocal() and timegm()"
+.ie n .IP "timelocal_nocheck() and timegm_nocheck()" 4
+.el .IP "\f(CWtimelocal_nocheck()\fR and \f(CWtimegm_nocheck()\fR" 4
+.IX Item "timelocal_nocheck() and timegm_nocheck()"
+.IP "Year Value Interpretation" 4
+.IX Item "Year Value Interpretation"
+.IP "Limits of time_t" 4
+.IX Item "Limits of time_t"
+.IP "Ambiguous Local Times (DST)" 4
+.IX Item "Ambiguous Local Times (DST)"
+.IP "Non-Existent Local Times (DST)" 4
+.IX Item "Non-Existent Local Times (DST)"
+.IP "Negative Epoch Values" 4
+.IX Item "Negative Epoch Values"
+.RE
+.RS 4
+.RE
+.IP IMPLEMENTATION 4
+.IX Item "IMPLEMENTATION"
+.IP "AUTHORS EMERITUS" 4
+.IX Item "AUTHORS EMERITUS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP SOURCE 4
+.IX Item "SOURCE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP CONTRIBUTORS 4
+.IX Item "CONTRIBUTORS"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.PD
+.SS "Time::Piece \- Object Oriented time objects"
+.IX Subsection "Time::Piece - Object Oriented time objects"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP USAGE 4
+.IX Item "USAGE"
+.RS 4
+.IP "Local Locales" 4
+.IX Item "Local Locales"
+.IP "Date Calculations" 4
+.IX Item "Date Calculations"
+.IP Truncation 4
+.IX Item "Truncation"
+.IP "Date Comparisons" 4
+.IX Item "Date Comparisons"
+.IP "Date Parsing" 4
+.IX Item "Date Parsing"
+.IP YYYY\-MM\-DDThh:mm:ss 4
+.IX Item "YYYY-MM-DDThh:mm:ss"
+.IP "Week Number" 4
+.IX Item "Week Number"
+.IP "Global Overriding" 4
+.IX Item "Global Overriding"
+.RE
+.RS 4
+.RE
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.RS 4
+.ie n .IP "Setting $ENV{TZ} in Threads on Win32" 4
+.el .IP "Setting \f(CW$ENV\fR{TZ} in Threads on Win32" 4
+.IX Item "Setting $ENV{TZ} in Threads on Win32"
+.IP "Use of epoch seconds" 4
+.IX Item "Use of epoch seconds"
+.RE
+.RS 4
+.RE
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP BUGS 4
+.IX Item "BUGS"
+.PD
+.SS "Time::Seconds \- a simple API to convert seconds to other date values"
+.IX Subsection "Time::Seconds - a simple API to convert seconds to other date values"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP METHODS 4
+.IX Item "METHODS"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "COPYRIGHT AND LICENSE" 4
+.IX Item "COPYRIGHT AND LICENSE"
+.IP Bugs 4
+.IX Item "Bugs"
+.PD
+.SS "Time::gmtime \- by-name interface to Perl's built-in \fBgmtime()\fP function"
+.IX Subsection "Time::gmtime - by-name interface to Perl's built-in gmtime() function"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Time::localtime \- by-name interface to Perl's built-in \fBlocaltime()\fP function"
+.IX Subsection "Time::localtime - by-name interface to Perl's built-in localtime() function"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "Time::tm \- internal object used by Time::gmtime and Time::localtime"
+.IX Subsection "Time::tm - internal object used by Time::gmtime and Time::localtime"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "UNIVERSAL \- base class for ALL classes (blessed references)"
+.IX Subsection "UNIVERSAL - base class for ALL classes (blessed references)"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.PD
+\&\f(CW\*(C`$obj\->isa( TYPE )\*(C'\fR, \f(CW\*(C`CLASS\->isa( TYPE )\*(C'\fR, \f(CW\*(C`eval { VAL\->isa(
+TYPE ) }\*(C'\fR, \f(CW\*(C`TYPE\*(C'\fR, \f(CW$obj\fR, \f(CW\*(C`CLASS\*(C'\fR, \f(CW\*(C`VAL\*(C'\fR, \f(CW\*(C`$obj\->DOES( ROLE )\*(C'\fR,
+\&\f(CW\*(C`CLASS\->DOES( ROLE )\*(C'\fR, \f(CW\*(C`$obj\->can( METHOD )\*(C'\fR, \f(CW\*(C`CLASS\->can(
+METHOD )\*(C'\fR, \f(CW\*(C`eval { VAL\->can( METHOD ) }\*(C'\fR, \f(CW\*(C`VERSION ( [ REQUIRE ] )\*(C'\fR
+.IP WARNINGS 4
+.IX Item "WARNINGS"
+.PD 0
+.IP EXPORTS 4
+.IX Item "EXPORTS"
+.PD
+.SS "Unicode::Collate \- Unicode Collation Algorithm"
+.IX Subsection "Unicode::Collate - Unicode Collation Algorithm"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Constructor and Tailoring" 4
+.IX Item "Constructor and Tailoring"
+.PD
+UCA_Version, alternate, backwards, entry, hangul_terminator, highestFFFF,
+identical, ignoreChar, ignoreName, ignore_level2, katakana_before_hiragana,
+level, long_contraction, minimalFFFE, normalization, overrideCJK,
+overrideHangul, overrideOut, preprocess, rearrange, rewrite, suppress,
+table, undefChar, undefName, upper_before_lower, variable
+.IP "Methods for Collation" 4
+.IX Item "Methods for Collation"
+\&\f(CW\*(C`@sorted = $Collator\->sort(@not_sorted)\*(C'\fR, \f(CW\*(C`$result =
+$Collator\->cmp($a, $b)\*(C'\fR, \f(CW\*(C`$result = $Collator\->eq($a, $b)\*(C'\fR,
+\&\f(CW\*(C`$result = $Collator\->ne($a, $b)\*(C'\fR, \f(CW\*(C`$result = $Collator\->lt($a,
+$b)\*(C'\fR, \f(CW\*(C`$result = $Collator\->le($a, $b)\*(C'\fR, \f(CW\*(C`$result =
+$Collator\->gt($a, $b)\*(C'\fR, \f(CW\*(C`$result = $Collator\->ge($a, $b)\*(C'\fR,
+\&\f(CW\*(C`$sortKey = $Collator\->getSortKey($string)\*(C'\fR, \f(CW\*(C`$sortKeyForm =
+$Collator\->viewSortKey($string)\*(C'\fR
+.IP "Methods for Searching" 4
+.IX Item "Methods for Searching"
+\&\f(CW\*(C`$position = $Collator\->index($string, $substring[, $position])\*(C'\fR,
+\&\f(CW\*(C`($position, $length) = $Collator\->index($string, $substring[,
+$position])\*(C'\fR, \f(CW\*(C`$match_ref = $Collator\->match($string, $substring)\*(C'\fR,
+\&\f(CW\*(C`($match)   = $Collator\->match($string, $substring)\*(C'\fR, \f(CW\*(C`@match =
+$Collator\->gmatch($string, $substring)\*(C'\fR, \f(CW\*(C`$count =
+$Collator\->subst($string, $substring, $replacement)\*(C'\fR, \f(CW\*(C`$count =
+$Collator\->gsubst($string, $substring, $replacement)\*(C'\fR
+.IP "Other Methods" 4
+.IX Item "Other Methods"
+\&\f(CW\*(C`%old_tailoring = $Collator\->change(%new_tailoring)\*(C'\fR,
+\&\f(CW\*(C`$modified_collator = $Collator\->change(%new_tailoring)\*(C'\fR, \f(CW\*(C`$version =
+$Collator\->version()\*(C'\fR, \f(CWUCA_Version()\fR, \f(CWBase_Unicode_Version()\fR
+.RE
+.RS 4
+.RE
+.IP EXPORT 4
+.IX Item "EXPORT"
+.PD 0
+.IP INSTALL 4
+.IX Item "INSTALL"
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+Normalization, Conformance Test
+.IP "AUTHOR, COPYRIGHT AND LICENSE" 4
+.IX Item "AUTHOR, COPYRIGHT AND LICENSE"
+.PD 0
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+Unicode Collation Algorithm \- UTS #10, The Default Unicode Collation
+Element Table (DUCET), The conformance test for the UCA, Hangul Syllable
+Type, Unicode Normalization Forms \- UAX #15, Unicode Locale Data Markup
+Language (LDML) \- UTS #35
+.SS "Unicode::Collate::CJK::Big5 \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::Big5 - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::GB2312 \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::GB2312 - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::JISX0208 \- weighting JIS KANJI for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::JISX0208 - weighting JIS KANJI for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::Korean \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::Korean - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::Pinyin \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::Pinyin - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::Stroke \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::Stroke - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::CJK::Zhuyin \- weighting CJK Unified Ideographs for Unicode::Collate"
+.IX Subsection "Unicode::Collate::CJK::Zhuyin - weighting CJK Unified Ideographs for Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+CLDR \- Unicode Common Locale Data Repository, Unicode Locale Data Markup
+Language (LDML) \- UTS #35, Unicode::Collate, Unicode::Collate::Locale
+.SS "Unicode::Collate::Locale \- Linguistic tailoring for DUCET via Unicode::Collate"
+.IX Subsection "Unicode::Collate::Locale - Linguistic tailoring for DUCET via Unicode::Collate"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP Constructor 4
+.IX Item "Constructor"
+.IP Methods 4
+.IX Item "Methods"
+.PD
+\&\f(CW\*(C`$Collator\->getlocale\*(C'\fR, \f(CW\*(C`$Collator\->locale_version\*(C'\fR
+.IP "A list of tailorable locales" 4
+.IX Item "A list of tailorable locales"
+.PD 0
+.IP "A list of variant codes and their aliases" 4
+.IX Item "A list of variant codes and their aliases"
+.RE
+.RS 4
+.RE
+.IP INSTALL 4
+.IX Item "INSTALL"
+.IP CAVEAT 4
+.IX Item "CAVEAT"
+.PD
+Tailoring is not maximum, Collation reordering is not supported
+.RS 4
+.IP Reference 4
+.IX Item "Reference"
+.RE
+.RS 4
+.RE
+.PD 0
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+Unicode Collation Algorithm \- UTS #10, The Default Unicode Collation
+Element Table (DUCET), Unicode Locale Data Markup Language (LDML) \- UTS
+#35, CLDR \- Unicode Common Locale Data Repository, Unicode::Collate,
+Unicode::Normalize
+.SS "Unicode::Normalize \- Unicode Normalization Forms"
+.IX Subsection "Unicode::Normalize - Unicode Normalization Forms"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "Normalization Forms" 4
+.IX Item "Normalization Forms"
+.PD
+\&\f(CW\*(C`$NFD_string = NFD($string)\*(C'\fR, \f(CW\*(C`$NFC_string = NFC($string)\*(C'\fR,
+\&\f(CW\*(C`$NFKD_string = NFKD($string)\*(C'\fR, \f(CW\*(C`$NFKC_string = NFKC($string)\*(C'\fR,
+\&\f(CW\*(C`$FCD_string = FCD($string)\*(C'\fR, \f(CW\*(C`$FCC_string = FCC($string)\*(C'\fR,
+\&\f(CW\*(C`$normalized_string = normalize($form_name, $string)\*(C'\fR
+.IP "Decomposition and Composition" 4
+.IX Item "Decomposition and Composition"
+\&\f(CW\*(C`$decomposed_string = decompose($string [, $useCompatMapping])\*(C'\fR,
+\&\f(CW\*(C`$reordered_string = reorder($string)\*(C'\fR, \f(CW$composed_string =
+compose($string)\fR, \f(CW($processed, $unprocessed) =
+splitOnLastStarter($normalized)\fR, \f(CW\*(C`$processed = normalize_partial($form,
+$unprocessed)\*(C'\fR, \f(CW\*(C`$processed = NFD_partial($unprocessed)\*(C'\fR, \f(CW$processed =
+NFC_partial($unprocessed)\fR, \f(CW\*(C`$processed = NFKD_partial($unprocessed)\*(C'\fR,
+\&\f(CW\*(C`$processed = NFKC_partial($unprocessed)\*(C'\fR
+.IP "Quick Check" 4
+.IX Item "Quick Check"
+\&\f(CW\*(C`$result = checkNFD($string)\*(C'\fR, \f(CW\*(C`$result = checkNFC($string)\*(C'\fR, \f(CW$result =
+checkNFKD($string)\fR, \f(CW\*(C`$result = checkNFKC($string)\*(C'\fR, \f(CW$result =
+checkFCD($string)\fR, \f(CW\*(C`$result = checkFCC($string)\*(C'\fR, \f(CW\*(C`$result =
+check($form_name, $string)\*(C'\fR
+.IP "Character Data" 4
+.IX Item "Character Data"
+\&\f(CW\*(C`$canonical_decomposition = getCanon($code_point)\*(C'\fR,
+\&\f(CW\*(C`$compatibility_decomposition = getCompat($code_point)\*(C'\fR,
+\&\f(CW\*(C`$code_point_composite = getComposite($code_point_here,
+$code_point_next)\*(C'\fR, \f(CW\*(C`$combining_class = getCombinClass($code_point)\*(C'\fR,
+\&\f(CW\*(C`$may_be_composed_with_prev_char = isComp2nd($code_point)\*(C'\fR,
+\&\f(CW\*(C`$is_exclusion = isExclusion($code_point)\*(C'\fR, \f(CW$is_singleton =
+isSingleton($code_point)\fR, \f(CW$is_non_starter_decomposition =
+isNonStDecomp($code_point)\fR, \f(CW$is_Full_Composition_Exclusion =
+isComp_Ex($code_point)\fR, \f(CW\*(C`$NFD_is_NO = isNFD_NO($code_point)\*(C'\fR,
+\&\f(CW\*(C`$NFC_is_NO = isNFC_NO($code_point)\*(C'\fR, \f(CW$NFC_is_MAYBE =
+isNFC_MAYBE($code_point)\fR, \f(CW\*(C`$NFKD_is_NO = isNFKD_NO($code_point)\*(C'\fR,
+\&\f(CW\*(C`$NFKC_is_NO = isNFKC_NO($code_point)\*(C'\fR, \f(CW$NFKC_is_MAYBE =
+isNFKC_MAYBE($code_point)\fR
+.RE
+.RS 4
+.RE
+.IP EXPORT 4
+.IX Item "EXPORT"
+.PD 0
+.IP CAVEATS 4
+.IX Item "CAVEATS"
+.PD
+Perl's version vs. Unicode version, Correction of decomposition mapping,
+Revised definition of canonical composition
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD 0
+.IP LICENSE 4
+.IX Item "LICENSE"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.PD
+<http://www.unicode.org/reports/tr15/>,
+<http://www.unicode.org/Public/UNIDATA/CompositionExclusions.txt>,
+<http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt>,
+<http://www.unicode.org/Public/UNIDATA/NormalizationCorrections.txt>,
+<http://www.unicode.org/review/pr\-29.html>,
+<http://www.unicode.org/notes/tn5/>
+.SS "Unicode::UCD \- Unicode character database"
+.IX Subsection "Unicode::UCD - Unicode character database"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "code point argument" 4
+.IX Item "code point argument"
+.RE
+.RS 4
+.RE
+.IP \fBcharinfo()\fR 4
+.IX Item "charinfo()"
+.PD
+\&\fBcode\fR, \fBname\fR, \fBcategory\fR, \fBcombining\fR, \fBbidi\fR, \fBdecomposition\fR,
+\&\fBdecimal\fR, \fBdigit\fR, \fBnumeric\fR, \fBmirrored\fR, \fBunicode10\fR, \fBcomment\fR,
+\&\fBupper\fR, \fBlower\fR, \fBtitle\fR, \fBblock\fR, \fBscript\fR
+.IP \fBcharprop()\fR 4
+.IX Item "charprop()"
+Block, Decomposition_Mapping, Name_Alias, Numeric_Value, Script_Extensions
+.IP \fBcharprops_all()\fR 4
+.IX Item "charprops_all()"
+.PD 0
+.IP \fBcharblock()\fR 4
+.IX Item "charblock()"
+.IP \fBcharscript()\fR 4
+.IX Item "charscript()"
+.IP \fBcharblocks()\fR 4
+.IX Item "charblocks()"
+.IP \fBcharscripts()\fR 4
+.IX Item "charscripts()"
+.IP \fBcharinrange()\fR 4
+.IX Item "charinrange()"
+.IP \fBgeneral_categories()\fR 4
+.IX Item "general_categories()"
+.IP \fBbidi_types()\fR 4
+.IX Item "bidi_types()"
+.IP \fBcompexcl()\fR 4
+.IX Item "compexcl()"
+.IP \fBcasefold()\fR 4
+.IX Item "casefold()"
+.PD
+\&\fBcode\fR, \fBfull\fR, \fBsimple\fR, \fBmapping\fR, \fBstatus\fR, \fB*\fR If you use this
+\&\f(CW\*(C`I\*(C'\fR mapping, \fB*\fR If you exclude this \f(CW\*(C`I\*(C'\fR mapping, \fBturkic\fR
+.IP \fBall_casefolds()\fR 4
+.IX Item "all_casefolds()"
+.PD 0
+.IP \fBcasespec()\fR 4
+.IX Item "casespec()"
+.PD
+\&\fBcode\fR, \fBlower\fR, \fBtitle\fR, \fBupper\fR, \fBcondition\fR
+.IP \fBnamedseq()\fR 4
+.IX Item "namedseq()"
+.PD 0
+.IP \fBnum()\fR 4
+.IX Item "num()"
+.IP \fBprop_aliases()\fR 4
+.IX Item "prop_aliases()"
+.IP \fBprop_values()\fR 4
+.IX Item "prop_values()"
+.IP \fBprop_value_aliases()\fR 4
+.IX Item "prop_value_aliases()"
+.IP \fBprop_invlist()\fR 4
+.IX Item "prop_invlist()"
+.IP \fBprop_invmap()\fR 4
+.IX Item "prop_invmap()"
+.PD
+\&\fR\f(CB\*(C`s\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`sl\*(C'\fR\fB\fR, \f(CW\*(C`correction\*(C'\fR, \f(CW\*(C`control\*(C'\fR, \f(CW\*(C`alternate\*(C'\fR, \f(CW\*(C`figment\*(C'\fR,
+\&\f(CW\*(C`abbreviation\*(C'\fR, \fB\fR\f(CB\*(C`a\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`al\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`ae\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`ale\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`ar\*(C'\fR\fB\fR, \fB\fR\f(CB\*(C`n\*(C'\fR\fB\fR,
+\&\fB\fR\f(CB\*(C`ad\*(C'\fR\fB\fR
+.IP \fBsearch_invlist()\fR 4
+.IX Item "search_invlist()"
+.PD 0
+.IP Unicode::UCD::UnicodeVersion 4
+.IX Item "Unicode::UCD::UnicodeVersion"
+.IP "\fBBlocks versus Scripts\fR" 4
+.IX Item "Blocks versus Scripts"
+.IP "\fBMatching Scripts and Blocks\fR" 4
+.IX Item "Matching Scripts and Blocks"
+.IP "Old-style versus new-style block names" 4
+.IX Item "Old-style versus new-style block names"
+.IP "Use with older Unicode versions" 4
+.IX Item "Use with older Unicode versions"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "User::grent \- by-name interface to Perl's built-in getgr*() functions"
+.IX Subsection "User::grent - by-name interface to Perl's built-in getgr*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.PD
+.SS "User::pwent \- by-name interface to Perl's built-in getpw*() functions"
+.IX Subsection "User::pwent - by-name interface to Perl's built-in getpw*() functions"
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.PD 0
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.IP "System Specifics" 4
+.IX Item "System Specifics"
+.RE
+.RS 4
+.RE
+.IP NOTE 4
+.IX Item "NOTE"
+.IP AUTHOR 4
+.IX Item "AUTHOR"
+.IP HISTORY 4
+.IX Item "HISTORY"
+.PD
+March 18th, 2000
+.SS "XSLoader \- Dynamically load C libraries into Perl code"
+.IX Subsection "XSLoader - Dynamically load C libraries into Perl code"
+.IP VERSION 4
+.IX Item "VERSION"
+.PD 0
+.IP SYNOPSIS 4
+.IX Item "SYNOPSIS"
+.IP DESCRIPTION 4
+.IX Item "DESCRIPTION"
+.RS 4
+.ie n .IP "Migration from ""DynaLoader""" 4
+.el .IP "Migration from \f(CWDynaLoader\fR" 4
+.IX Item "Migration from DynaLoader"
+.IP "Backward compatible boilerplate" 4
+.IX Item "Backward compatible boilerplate"
+.RE
+.RS 4
+.RE
+.IP "Order of initialization: early \fBload()\fR" 4
+.IX Item "Order of initialization: early load()"
+.RS 4
+.IP "The most hairy case" 4
+.IX Item "The most hairy case"
+.RE
+.RS 4
+.RE
+.IP DIAGNOSTICS 4
+.IX Item "DIAGNOSTICS"
+.PD
+\&\f(CW\*(C`Can\*(Aqt find \*(Aq%s\*(Aq symbol in %s\*(C'\fR, \f(CW\*(C`Can\*(Aqt load \*(Aq%s\*(Aq for module %s: %s\*(C'\fR,
+\&\f(CW\*(C`Undefined symbols present after loading %s: %s\*(C'\fR
+.IP LIMITATIONS 4
+.IX Item "LIMITATIONS"
+.PD 0
+.IP "KNOWN BUGS" 4
+.IX Item "KNOWN BUGS"
+.IP BUGS 4
+.IX Item "BUGS"
+.IP "SEE ALSO" 4
+.IX Item "SEE ALSO"
+.IP AUTHORS 4
+.IX Item "AUTHORS"
+.IP "COPYRIGHT & LICENSE" 4
+.IX Item "COPYRIGHT & LICENSE"
+.PD
+.SH "AUXILIARY DOCUMENTATION"
+.IX Header "AUXILIARY DOCUMENTATION"
+Here should be listed all the extra programs' documentation, but they
+don't all have manual pages yet:
+.IP h2ph 4
+.IX Item "h2ph"
+.PD 0
+.IP h2xs 4
+.IX Item "h2xs"
+.IP perlbug 4
+.IX Item "perlbug"
+.IP pl2pm 4
+.IX Item "pl2pm"
+.IP pod2html 4
+.IX Item "pod2html"
+.IP pod2man 4
+.IX Item "pod2man"
+.IP splain 4
+.IX Item "splain"
+.IP xsubpp 4
+.IX Item "xsubpp"
+.PD
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall <\fIlarry@wall.org\fR>, with the help of oodles
+of other folks.
diff --git a/upstream/mageia-cauldron/man1/perltodo.1 b/upstream/mageia-cauldron/man1/perltodo.1
new file mode 100644
index 00000000..8c5e63bd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltodo.1
@@ -0,0 +1,71 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTODO 1"
+.TH PERLTODO 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltodo \- Link to the Perl to\-do list
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The Perl 5 to-do list is maintained in the git repository, and can
+be viewed at <https://github.com/Perl/perl5/blob/blead/Porting/todo.pod>.
+.PP
+(The to-do list used to be here in perltodo. That has stopped, as installing a
+snapshot that becomes increasingly out of date isn't that useful to anyone.)
diff --git a/upstream/mageia-cauldron/man1/perltooc.1 b/upstream/mageia-cauldron/man1/perltooc.1
new file mode 100644
index 00000000..a0adb598
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltooc.1
@@ -0,0 +1,71 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTOOC 1"
+.TH PERLTOOC 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltooc \- Links to information on object\-oriented programming in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+For information on OO programming with Perl, please see perlootut
+and perlobj.
+.PP
+(The above documents supersede the tutorial that was formerly here in
+perltooc.)
diff --git a/upstream/mageia-cauldron/man1/perltoot.1 b/upstream/mageia-cauldron/man1/perltoot.1
new file mode 100644
index 00000000..ec99bf77
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltoot.1
@@ -0,0 +1,71 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTOOT 1"
+.TH PERLTOOT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltoot \- Links to information on object\-oriented programming in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+For information on OO programming with Perl, please see perlootut
+and perlobj.
+.PP
+(The above documents supersede the tutorial that was formerly here in
+perltoot.)
diff --git a/upstream/mageia-cauldron/man1/perltrap.1 b/upstream/mageia-cauldron/man1/perltrap.1
new file mode 100644
index 00000000..6ffd0099
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltrap.1
@@ -0,0 +1,363 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTRAP 1"
+.TH PERLTRAP 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltrap \- Perl traps for the unwary
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The biggest trap of all is forgetting to \f(CW\*(C`use warnings\*(C'\fR or use the \fB\-w\fR
+switch; see warnings and "\-w" in perlrun. The second biggest trap is not
+making your entire program runnable under \f(CW\*(C`use strict\*(C'\fR.  The third biggest
+trap is not reading the list of changes in this version of Perl; see
+perldelta.
+.SS "Awk Traps"
+.IX Subsection "Awk Traps"
+Accustomed \fBawk\fR users should take special note of the following:
+.IP \(bu 4
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
+.IP \(bu 4
+The English module, loaded via
+.Sp
+.Vb 1
+\&    use English;
+.Ve
+.Sp
+allows you to refer to special variables (like \f(CW$/\fR) with names (like
+\&\f(CW$RS\fR), as though they were in \fBawk\fR; see perlvar for details.
+.IP \(bu 4
+Semicolons are required after all simple statements in Perl (except
+at the end of a block).  Newline is not a statement delimiter.
+.IP \(bu 4
+Curly brackets are required on \f(CW\*(C`if\*(C'\fRs and \f(CW\*(C`while\*(C'\fRs.
+.IP \(bu 4
+Variables begin with "$", "@" or "%" in Perl.
+.IP \(bu 4
+Arrays index from 0.  Likewise string positions in \fBsubstr()\fR and
+\&\fBindex()\fR.
+.IP \(bu 4
+You have to decide whether your array has numeric or string indices.
+.IP \(bu 4
+Hash values do not spring into existence upon mere reference.
+.IP \(bu 4
+You have to decide whether you want to use string or numeric
+comparisons.
+.IP \(bu 4
+Reading an input line does not split it for you.  You get to split it
+to an array yourself.  And the \fBsplit()\fR operator has different
+arguments than \fBawk\fR's.
+.IP \(bu 4
+The current input line is normally in \f(CW$_\fR, not \f(CW$0\fR.  It generally does
+not have the newline stripped.  ($0 is the name of the program
+executed.)  See perlvar.
+.IP \(bu 4
+$<\fIdigit\fR> does not refer to fields\-\-it refers to substrings matched
+by the last match pattern.
+.IP \(bu 4
+The \fBprint()\fR statement does not add field and record separators unless
+you set \f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR.  You can set \f(CW$OFS\fR and \f(CW$ORS\fR if you're using
+the English module.
+.IP \(bu 4
+You must open your files before you print to them.
+.IP \(bu 4
+The range operator is "..", not comma.  The comma operator works as in
+C.
+.IP \(bu 4
+The match operator is "=~", not "~".  ("~" is the one's complement
+operator, as in C.)
+.IP \(bu 4
+The exponentiation operator is "**", not "^".  "^" is the XOR
+operator, as in C.  (You know, one could get the feeling that \fBawk\fR is
+basically incompatible with C.)
+.IP \(bu 4
+The concatenation operator is ".", not the null string.  (Using the
+null string would render \f(CW\*(C`/pat/ /pat/\*(C'\fR unparsable, because the third slash
+would be interpreted as a division operator\-\-the tokenizer is in fact
+slightly context sensitive for operators like "/", "?", and ">".
+And in fact, "." itself can be the beginning of a number.)
+.IP \(bu 4
+The \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, and \f(CW\*(C`continue\*(C'\fR keywords work differently.
+.IP \(bu 4
+The following variables work differently:
+.Sp
+.Vb 10
+\&      Awk       Perl
+\&      ARGC      scalar @ARGV (compare with $#ARGV)
+\&      ARGV[0]   $0
+\&      FILENAME  $ARGV
+\&      FNR       $. \- something
+\&      FS        (whatever you like)
+\&      NF        $#Fld, or some such
+\&      NR        $.
+\&      OFMT      $#
+\&      OFS       $,
+\&      ORS       $\e
+\&      RLENGTH   length($&)
+\&      RS        $/
+\&      RSTART    length($\`)
+\&      SUBSEP    $;
+.Ve
+.IP \(bu 4
+You cannot set \f(CW$RS\fR to a pattern, only a string.
+.IP \(bu 4
+When in doubt, run the \fBawk\fR construct through \fBa2p\fR and see what it
+gives you.
+.SS "C/C++ Traps"
+.IX Subsection "C/C++ Traps"
+Cerebral C and C++ programmers should take note of the following:
+.IP \(bu 4
+Curly brackets are required on \f(CW\*(C`if\*(C'\fR's and \f(CW\*(C`while\*(C'\fR's.
+.IP \(bu 4
+You must use \f(CW\*(C`elsif\*(C'\fR rather than \f(CW\*(C`else if\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`break\*(C'\fR and \f(CW\*(C`continue\*(C'\fR keywords from C become in Perl \f(CW\*(C`last\*(C'\fR
+and \f(CW\*(C`next\*(C'\fR, respectively.  Unlike in C, these do \fInot\fR work within a
+\&\f(CW\*(C`do { } while\*(C'\fR construct.  See "Loop Control" in perlsyn.
+.IP \(bu 4
+The switch statement is called \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR and only available in
+perl 5.10 or newer.  See "Switch Statements" in perlsyn.
+.IP \(bu 4
+Variables begin with "$", "@" or "%" in Perl.
+.IP \(bu 4
+Comments begin with "#", not "/*" or "//".  Perl may interpret C/C++
+comments as division operators, unterminated regular expressions or
+the defined-or operator.
+.IP \(bu 4
+You can't take the address of anything, although a similar operator
+in Perl is the backslash, which creates a reference.
+.IP \(bu 4
+\&\f(CW\*(C`ARGV\*(C'\fR must be capitalized.  \f(CW$ARGV[0]\fR is C's \f(CW\*(C`argv[1]\*(C'\fR, and \f(CW\*(C`argv[0]\*(C'\fR
+ends up in \f(CW$0\fR.
+.IP \(bu 4
+System calls such as \fBlink()\fR, \fBunlink()\fR, \fBrename()\fR, etc. return nonzero for
+success, not 0. (\fBsystem()\fR, however, returns zero for success.)
+.IP \(bu 4
+Signal handlers deal with signal names, not numbers.  Use \f(CW\*(C`kill \-l\*(C'\fR
+to find their names on your system.
+.SS "JavaScript Traps"
+.IX Subsection "JavaScript Traps"
+Judicious JavaScript programmers should take note of the following:
+.IP \(bu 4
+In Perl, binary \f(CW\*(C`+\*(C'\fR is always addition.  \f(CW\*(C`$string1 + $string2\*(C'\fR converts
+both strings to numbers and then adds them.  To concatenate two strings,
+use the \f(CW\*(C`.\*(C'\fR operator.
+.IP \(bu 4
+The \f(CW\*(C`+\*(C'\fR unary operator doesn't do anything in Perl.  It exists to avoid
+syntactic ambiguities.
+.IP \(bu 4
+Unlike \f(CW\*(C`for...in\*(C'\fR, Perl's \f(CW\*(C`for\*(C'\fR (also spelled \f(CW\*(C`foreach\*(C'\fR) does not allow
+the left-hand side to be an arbitrary expression.  It must be a variable:
+.Sp
+.Vb 3
+\&   for my $variable (keys %hash) {
+\&        ...
+\&   }
+.Ve
+.Sp
+Furthermore, don't forget the \f(CW\*(C`keys\*(C'\fR in there, as
+\&\f(CW\*(C`foreach my $kv (%hash) {}\*(C'\fR iterates over the keys and values, and is
+generally not useful ($kv would be a key, then a value, and so on).
+.IP \(bu 4
+To iterate over the indices of an array, use \f(CW\*(C`foreach my $i (0 .. $#array)
+{}\*(C'\fR.  \f(CW\*(C`foreach my $v (@array) {}\*(C'\fR iterates over the values.
+.IP \(bu 4
+Perl requires braces following \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`while\*(C'\fR, \f(CW\*(C`foreach\*(C'\fR, etc.
+.IP \(bu 4
+In Perl, \f(CW\*(C`else if\*(C'\fR is spelled \f(CW\*(C`elsif\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`? :\*(C'\fR has higher precedence than assignment.  In JavaScript, one can
+write:
+.Sp
+.Vb 1
+\&    condition ? do_something() : variable = 3
+.Ve
+.Sp
+and the variable is only assigned if the condition is false.  In Perl, you
+need parentheses:
+.Sp
+.Vb 1
+\&    $condition ? do_something() : ($variable = 3);
+.Ve
+.Sp
+Or just use \f(CW\*(C`if\*(C'\fR.
+.IP \(bu 4
+Perl requires semicolons to separate statements.
+.IP \(bu 4
+Variables declared with \f(CW\*(C`my\*(C'\fR only affect code \fIafter\fR the declaration.
+You cannot write \f(CW\*(C`$x = 1; my $x;\*(C'\fR and expect the first assignment to
+affect the same variable.  It will instead assign to an \f(CW$x\fR declared
+previously in an outer scope, or to a global variable.
+.Sp
+Note also that the variable is not visible until the following
+\&\fIstatement\fR.  This means that in \f(CW\*(C`my $x = 1 + $x\*(C'\fR the second \f(CW$x\fR refers
+to one declared previously.
+.IP \(bu 4
+\&\f(CW\*(C`my\*(C'\fR variables are scoped to the current block, not to the current
+function.  If you write \f(CW\*(C`{my $x;} $x;\*(C'\fR, the second \f(CW$x\fR does not refer to
+the one declared inside the block.
+.IP \(bu 4
+An object's members cannot be made accessible as variables.  The closest
+Perl equivalent to \f(CW\*(C`with(object) { method() }\*(C'\fR is \f(CW\*(C`for\*(C'\fR, which can alias
+\&\f(CW$_\fR to the object:
+.Sp
+.Vb 3
+\&    for ($object) {
+\&        $_\->method;
+\&    }
+.Ve
+.IP \(bu 4
+The object or class on which a method is called is passed as one of the
+method's arguments, not as a separate \f(CW\*(C`this\*(C'\fR value.
+.SS "Sed Traps"
+.IX Subsection "Sed Traps"
+Seasoned \fBsed\fR programmers should take note of the following:
+.IP \(bu 4
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
+.IP \(bu 4
+Backreferences in substitutions use "$" rather than "\e".
+.IP \(bu 4
+The pattern matching metacharacters "(", ")", and "|" do not have backslashes
+in front.
+.IP \(bu 4
+The range operator is \f(CW\*(C`...\*(C'\fR, rather than comma.
+.SS "Shell Traps"
+.IX Subsection "Shell Traps"
+Sharp shell programmers should take note of the following:
+.IP \(bu 4
+The backtick operator does variable interpolation without regard to
+the presence of single quotes in the command.
+.IP \(bu 4
+The backtick operator does no translation of the return value, unlike \fBcsh\fR.
+.IP \(bu 4
+Shells (especially \fBcsh\fR) do several levels of substitution on each
+command line.  Perl does substitution in only certain constructs
+such as double quotes, backticks, angle brackets, and search patterns.
+.IP \(bu 4
+Shells interpret scripts a little bit at a time.  Perl compiles the
+entire program before executing it (except for \f(CW\*(C`BEGIN\*(C'\fR blocks, which
+execute at compile time).
+.IP \(bu 4
+The arguments are available via \f(CW@ARGV\fR, not \f(CW$1\fR, \f(CW$2\fR, etc.
+.IP \(bu 4
+The environment is not automatically made available as separate scalar
+variables.
+.IP \(bu 4
+The shell's \f(CW\*(C`test\*(C'\fR uses "=", "!=", "<" etc for string comparisons and "\-eq",
+"\-ne", "\-lt" etc for numeric comparisons. This is the reverse of Perl, which
+uses \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR, \f(CW\*(C`lt\*(C'\fR for string comparisons, and \f(CW\*(C`==\*(C'\fR, \f(CW\*(C`!=\*(C'\fR \f(CW\*(C`<\*(C'\fR etc
+for numeric comparisons.
+.SS "Perl Traps"
+.IX Subsection "Perl Traps"
+Practicing Perl Programmers should take note of the following:
+.IP \(bu 4
+Remember that many operations behave differently in a list
+context than they do in a scalar one.  See perldata for details.
+.IP \(bu 4
+Avoid barewords if you can, especially all lowercase ones.
+You can't tell by just looking at it whether a bareword is
+a function or a string.  By using quotes on strings and
+parentheses on function calls, you won't ever get them confused.
+.IP \(bu 4
+You cannot discern from mere inspection which builtins
+are unary operators (like \fBchop()\fR and \fBchdir()\fR)
+and which are list operators (like \fBprint()\fR and \fBunlink()\fR).
+(Unless prototyped, user-defined subroutines can \fBonly\fR be list
+operators, never unary ones.)  See perlop and perlsub.
+.IP \(bu 4
+People have a hard time remembering that some functions
+default to \f(CW$_\fR, or \f(CW@ARGV\fR, or whatever, but that others which
+you might expect to do not.
+.IP \(bu 4
+The <FH> construct is not the name of the filehandle, it is a readline
+operation on that handle.  The data read is assigned to \f(CW$_\fR only if the
+file read is the sole condition in a while loop:
+.Sp
+.Vb 3
+\&    while (<FH>)      { }
+\&    while (defined($_ = <FH>)) { }..
+\&    <FH>;  # data discarded!
+.Ve
+.IP \(bu 4
+Remember not to use \f(CW\*(C`=\*(C'\fR when you need \f(CW\*(C`=~\*(C'\fR;
+these two constructs are quite different:
+.Sp
+.Vb 2
+\&    $x =  /foo/;
+\&    $x =~ /foo/;
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`do {}\*(C'\fR construct isn't a real loop that you can use
+loop control on.
+.IP \(bu 4
+Use \f(CWmy()\fR for local variables whenever you can get away with
+it (but see perlform for where you can't).
+Using \f(CWlocal()\fR actually gives a local value to a global
+variable, which leaves you open to unforeseen side-effects
+of dynamic scoping.
+.IP \(bu 4
+If you localize an exported variable in a module, its exported value will
+not change.  The local name becomes an alias to a new value but the
+external name is still an alias for the original.
+.PP
+As always, if any of these are ever officially declared as bugs,
+they'll be fixed and removed.
diff --git a/upstream/mageia-cauldron/man1/perltru64.1 b/upstream/mageia-cauldron/man1/perltru64.1
new file mode 100644
index 00000000..51d729f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltru64.1
@@ -0,0 +1,240 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTRU64 1"
+.TH PERLTRU64 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltru64 \- Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes various features of HP's (formerly Compaq's,
+formerly Digital's) Unix operating system (Tru64) that will affect
+how Perl version 5 (hereafter just Perl) is configured, compiled
+and/or runs.
+.SS "Compiling Perl 5 on Tru64"
+.IX Subsection "Compiling Perl 5 on Tru64"
+The recommended compiler to use in Tru64 is the native C compiler.
+The native compiler produces much faster code (the speed difference is
+noticeable: several dozen percentages) and also more correct code: if
+you are considering using the GNU C compiler you should use at the
+very least the release of 2.95.3 since all older gcc releases are
+known to produce broken code when compiling Perl.  One manifestation
+of this brokenness is the lib/sdbm test dumping core; another is many
+of the op/regexp and op/pat, or ext/Storable tests dumping core
+(the exact pattern of failures depending on the GCC release and
+optimization flags).
+.PP
+Both the native cc and gcc seem to consume lots of memory when
+building Perl.  toke.c is a known trouble spot when optimizing:
+256 megabytes of data section seems to be enough.  Another known
+trouble spot is the mktables script which builds the Unicode support
+tables.  The default setting of the process data section in Tru64
+should be one gigabyte, but some sites/setups might have lowered that.
+The configuration process of Perl checks for too low process limits,
+and lowers the optimization for the toke.c if necessary, and also
+gives advice on how to raise the process limits
+(for example: \f(CW\*(C`ulimit \-d 262144\*(C'\fR)
+.PP
+Also, Configure might abort with
+.PP
+.Vb 2
+\& Build a threading Perl? [n]
+\& Configure[2437]: Syntax error at line 1 : \*(Aqconfig.sh\*(Aq is not expected.
+.Ve
+.PP
+This indicates that Configure is being run with a broken Korn shell
+(even though you think you are using a Bourne shell by using
+"sh Configure" or "./Configure").  The Korn shell bug has been reported
+to Compaq as of February 1999 but in the meanwhile, the reason ksh is
+being used is that you have the environment variable BIN_SH set to
+\&'xpg4'.  This causes /bin/sh to delegate its duties to /bin/posix/sh
+(a ksh).  Unset the environment variable and rerun Configure.
+.SS "Using Large Files with Perl on Tru64"
+.IX Subsection "Using Large Files with Perl on Tru64"
+In Tru64 Perl is automatically able to use large files, that is,
+files larger than 2 gigabytes, there is no need to use the Configure
+\&\-Duselargefiles option as described in INSTALL (though using the option
+is harmless).
+.SS "Threaded Perl on Tru64"
+.IX Subsection "Threaded Perl on Tru64"
+If you want to use threads, you should primarily use the Perl
+5.8.0 threads model by running Configure with \-Duseithreads.
+.PP
+Perl threading is going to work only in Tru64 4.0 and newer releases,
+older operating releases like 3.2 aren't probably going to work
+properly with threads.
+.PP
+In Tru64 V5 (at least V5.1A, V5.1B) you cannot build threaded Perl with gcc
+because the system header <pthread.h> explicitly checks for supported
+C compilers, gcc (at least 3.2.2) not being one of them.  But the
+system C compiler should work just fine.
+.SS "Long Doubles on Tru64"
+.IX Subsection "Long Doubles on Tru64"
+You cannot Configure Perl to use long doubles unless you have at least
+Tru64 V5.0, the long double support simply wasn't functional enough
+before that.  Perl's Configure will override attempts to use the long
+doubles (you can notice this by Configure finding out that the \fBmodfl()\fR
+function does not work as it should).
+.PP
+At the time of this writing (June 2002), there is a known bug in the
+Tru64 libc printing of long doubles when not using "e" notation.
+The values are correct and usable, but you only get a limited number
+of digits displayed unless you force the issue by using \f(CW\*(C`printf
+"%.33e",$num\*(C'\fR or the like.  For Tru64 versions V5.0A through V5.1A, a
+patch is expected sometime after perl 5.8.0 is released.  If your libc
+has not yet been patched, you'll get a warning from Configure when
+selecting long doubles.
+.SS "DB_File tests failing on Tru64"
+.IX Subsection "DB_File tests failing on Tru64"
+The DB_File tests (db\-btree.t, db\-hash.t, db\-recno.t) may fail you
+have installed a newer version of Berkeley DB into the system and the
+\&\-I and \-L compiler and linker flags introduce version conflicts with
+the DB 1.85 headers and libraries that came with the Tru64.  For example, 
+mixing a DB v2 library with the DB v1 headers is a bad idea.  Watch
+out for Configure options \-Dlocincpth and \-Dloclibpth, and check your
+/usr/local/include and /usr/local/lib since they are included by default.
+.PP
+The second option is to explicitly instruct Configure to detect the
+newer Berkeley DB installation, by supplying the right directories with
+\&\f(CW\*(C`\-Dlocincpth=/some/include\*(C'\fR and \f(CW\*(C`\-Dloclibpth=/some/lib\*(C'\fR \fBand\fR before
+running "make test" setting your LD_LIBRARY_PATH to \fI/some/lib\fR.
+.PP
+The third option is to work around the problem by disabling the
+DB_File completely when build Perl by specifying \-Ui_db to Configure,
+and then using the BerkeleyDB module from CPAN instead of DB_File.
+The BerkeleyDB works with Berkeley DB versions 2.* or greater.
+.PP
+The Berkeley DB 4.1.25 has been tested with Tru64 V5.1A and found
+to work.  The latest Berkeley DB can be found from <http://www.sleepycat.com>.
+.SS "64\-bit Perl on Tru64"
+.IX Subsection "64-bit Perl on Tru64"
+In Tru64 Perl's integers are automatically 64\-bit wide, there is
+no need to use the Configure \-Duse64bitint option as described
+in INSTALL.  Similarly, there is no need for \-Duse64bitall
+since pointers are automatically 64\-bit wide.
+.SS "Warnings about floating-point overflow when compiling Perl on Tru64"
+.IX Subsection "Warnings about floating-point overflow when compiling Perl on Tru64"
+When compiling Perl in Tru64 you may (depending on the compiler
+release) see two warnings like this
+.PP
+.Vb 4
+\& cc: Warning: numeric.c, line 104: In this statement, floating\-point
+\& overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
+\&     return HUGE_VAL;
+\& \-\-\-\-\-\-\-\-\-\-\-^
+.Ve
+.PP
+and when compiling the POSIX extension
+.PP
+.Vb 4
+\& cc: Warning: const\-c.inc, line 2007: In this statement, floating\-point
+\& overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
+\&             return HUGE_VAL;
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-^
+.Ve
+.PP
+The exact line numbers may vary between Perl releases.  The warnings
+are benign and can be ignored: in later C compiler releases the warnings
+should be gone.
+.PP
+When the file \fIpp_sys.c\fR is being compiled you may (depending on the
+operating system release) see an additional compiler flag being used:
+\&\f(CW\*(C`\-DNO_EFF_ONLY_OK\*(C'\fR.  This is normal and refers to a feature that is
+relevant only if you use the \f(CW\*(C`filetest\*(C'\fR pragma.  In older releases of
+the operating system the feature was broken and the NO_EFF_ONLY_OK
+instructs Perl not to use the feature.
+.SH "Testing Perl on Tru64"
+.IX Header "Testing Perl on Tru64"
+During "make test" the \f(CW\*(C`comp\*(C'\fR/\f(CW\*(C`cpp\*(C'\fR will be skipped because on Tru64 it
+cannot be tested before Perl has been installed.  The test refers to
+the use of the \f(CW\*(C`\-P\*(C'\fR option of Perl.
+.SH "ext/ODBM_File/odbm Test Failing With Static Builds"
+.IX Header "ext/ODBM_File/odbm Test Failing With Static Builds"
+The ext/ODBM_File/odbm is known to fail with static builds
+(Configure \-Uusedl) due to a known bug in Tru64's static libdbm
+library.  The good news is that you very probably don't need to ever
+use the ODBM_File extension since more advanced NDBM_File works fine,
+not to mention the even more advanced DB_File.
+.SH "Perl Fails Because Of Unresolved Symbol sockatmark"
+.IX Header "Perl Fails Because Of Unresolved Symbol sockatmark"
+If you get an error like
+.PP
+.Vb 1
+\&    Can\*(Aqt load \*(Aq.../OSF1/lib/perl5/5.8.0/alpha\-dec_osf/auto/IO/IO.so\*(Aq for module IO: Unresolved symbol in .../lib/perl5/5.8.0/alpha\-dec_osf/auto/IO/IO.so: sockatmark at .../lib/perl5/5.8.0/alpha\-dec_osf/XSLoader.pm line 75.
+.Ve
+.PP
+you need to either recompile your Perl in Tru64 4.0D or upgrade your
+Tru64 4.0D to at least 4.0F: the \fBsockatmark()\fR system call was
+added in Tru64 4.0F, and the IO extension refers that symbol.
+.SH "read_cur_obj_info: bad file magic number"
+.IX Header "read_cur_obj_info: bad file magic number"
+You may be mixing the Tru64 cc/ar/ld with the GNU gcc/ar/ld.
+That may work, but sometimes it doesn't (your gcc or GNU utils
+may have been compiled for an incompatible OS release).
+.PP
+Try 'which ld' and 'which ld' (or try 'ar \-\-version' and 'ld \-\-version',
+which work only for the GNU tools, and will announce themselves to be such),
+and adjust your PATH so that you are consistently using either
+the native tools or the GNU tools.  After fixing your PATH, you should
+do 'make distclean' and start all the way from running the Configure
+since you may have quite a confused situation.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Jarkko Hietaniemi <jhi@iki.fi>
diff --git a/upstream/mageia-cauldron/man1/perltw.1 b/upstream/mageia-cauldron/man1/perltw.1
new file mode 100644
index 00000000..195c8d6a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perltw.1
@@ -0,0 +1,189 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLTW 1"
+.TH PERLTW 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perltw \- 正體中文 Perl 指�
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+歡迎來到 Perl 的天地!
+.PP
+從 5.8.0 版開始, Perl 具備了完善的 Unicode (�國碼) 支�,
+也連帶支�了許多拉�語系以外的編碼方�; CJK (中日韓) 便是其中的一部份.
+Unicode 是國際性的標準, 試圖涵蓋世界上所有的字符: 西方世界, �方世界,
+以�兩者間的一切 (希臘文, 敘利亞文, 阿拉伯文, 希伯來文, �度文,
+�地安文, 等等). 它也容�了多種作業系統與平臺 (如 PC �麥金塔).
+.PP
+Perl 本身以 Unicode 進行�作. 這表示 Perl 內部的字串資料�用 Unicode
+表示; Perl 的函�與算符 (例如正�表示�比�) 也能� Unicode 進行�作.
+在輸入�輸出時, 為了處�以 Unicode 之�的編碼方�儲存的資料, Perl
+�供了 Encode 這個模組, �以讓你輕易地讀��寫入舊有的編碼資料.
+.PP
+Encode 延伸模組支�下列正體中文的編碼方� ('big5' 表示 'big5\-eten'):
+.PP
+.Vb 3
+\&    big5\-eten   Big5 編碼 (�倚天延伸字形)
+\&    big5\-hkscs  Big5 + 香港外字集, 2001 年版
+\&    cp950       字碼� 950 (Big5 + 微軟添加的字符)
+.Ve
+.PP
+舉例來說, 將 Big5 編碼的檔案轉� Unicode, 祗需�入下列指令:
+.PP
+.Vb 2
+\&    perl \-MEncode \-pe \*(Aq$_= encode( utf8 => decode( big5 => $_ ) )\*(Aq \e
+\&      < file.big5 > file.utf8
+.Ve
+.PP
+Perl 也內附了 "piconv", 一支完全以 Perl 寫�的字符轉�工具程�, 用法如下:
+.PP
+.Vb 2
+\&    piconv \-f big5 \-t utf8 < file.big5 > file.utf8
+\&    piconv \-f utf8 \-t big5 < file.utf8 > file.big5
+.Ve
+.PP
+�外，若程�碼本身以 utf8 編碼儲存，��使用 utf8 模組，�讓程�碼中字串以�其�
+算皆以字符為單�，而�以�元為單�，如下所示：
+.PP
+.Vb 4
+\&    #!/usr/bin/env perl
+\&    use utf8;
+\&    print length("駱�");      #  2 (�是 6)
+\&    print index("諄諄教誨", "教誨"); #  2 (從 0 起算第 2 個字符)
+.Ve
+.SS �外的中文編碼
+.IX Subsection "�外的中文編碼"
+如果需�更多的中文編碼, �以從 CPAN (<https://www.cpan.org/>) 下載
+Encode::HanExtra 模組. 它目��供下列編碼方�:
+.PP
+.Vb 4
+\&    cccii       1980 年文建會的中文資訊交�碼
+\&    euc\-tw      Unix 延伸字符集, 包� CNS11643 平� 1\-7
+\&    big5plus    中文數�化技術推廣基金會的 Big5+
+\&    big5ext     中文數�化技術推廣基金會的 Big5e
+.Ve
+.PP
+�外, Encode::HanConvert 模組則�供了簡�轉�用的兩種編碼:
+.PP
+.Vb 2
+\&    big5\-simp   Big5 正體中文與 Unicode 簡體中文互轉
+\&    gbk\-trad    GBK 簡體中文與 Unicode 正體中文互轉
+.Ve
+.PP
+若想在 GBK 與 Big5 之間互轉, 請�考該模組內附的 b2g.pl 與 g2b.pl 兩支程�,
+或在程�內使用下列寫法:
+.PP
+.Vb 3
+\&    use Encode::HanConvert;
+\&    $euc_cn = big5_to_gb($big5); # 從 Big5 轉為 GBK
+\&    $big5 = gb_to_big5($euc_cn); # 從 GBK 轉為 Big5
+.Ve
+.SS 進一步的資訊
+.IX Subsection "進一步的資訊"
+請�考 Perl 內附的大�說明文件 (�幸全是用英文寫的), 來學習更多關於
+Perl 的知識, 以� Unicode 的使用方�. ��, 外部的資�相當�富:
+.SS "�供 Perl 資�的網�"
+.IX Subsection "�供 Perl 資�的網�"
+.IP <https://www.perl.org/> 4
+.IX Item "<https://www.perl.org/>"
+Perl 的首�
+.IP <https://www.perl.com/> 4
+.IX Item "<https://www.perl.com/>"
+由 Perl 基金會所營�的文章輯錄
+.IP <https://www.cpan.org/> 4
+.IX Item "<https://www.cpan.org/>"
+Perl 綜�典�網 (Comprehensive Perl Archive Network)
+.IP <https://lists.perl.org/> 4
+.IX Item "<https://lists.perl.org/>"
+Perl 郵�論壇一覽
+.SS "學習 Perl 的網�"
+.IX Subsection "學習 Perl 的網�"
+.IP <http://www.oreilly.com.cn/index.php?func=booklist&cat=68> 4
+.IX Item "<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>"
+正體中文版的��禮 Perl 書藉
+.SS "Perl 使用者集會"
+.IX Subsection "Perl 使用者集會"
+.IP <https://www.pm.org/groups/taiwan.html> 4
+.IX Item "<https://www.pm.org/groups/taiwan.html>"
+臺� Perl 推廣組一覽
+.IP <irc://chat.freenode.org/#perl.tw> 4
+.IX Item "<irc://chat.freenode.org/#perl.tw>"
+Perl.tw 線上�天室
+.SS "Unicode 相關網�"
+.IX Subsection "Unicode 相關網�"
+.IP <https://www.unicode.org/> 4
+.IX Item "<https://www.unicode.org/>"
+Unicode 學術學會 (Unicode 標準的制定者)
+.IP <http://www.cl.cam.ac.uk/%7Emgk25/unicode.html> 4
+.IX Item "<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>"
+Unix/Linux 上的 UTF\-8 � Unicode 答客�
+.SS 中文化資訊
+.IX Subsection "中文化資訊"
+.IP 中文化軟體�盟 4
+.IX Item "中文化軟體�盟"
+<http://www.cpatch.org/>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode, Encode::TW, perluniintro, perlunicode
+.SH AUTHORS
+.IX Header "AUTHORS"
+Jarkko Hietaniemi <jhi@iki.fi>
+.PP
+Audrey Tang (�鳳) <audreyt@audreyt.org>
diff --git a/upstream/mageia-cauldron/man1/perlunicode.1 b/upstream/mageia-cauldron/man1/perlunicode.1
new file mode 100644
index 00000000..ead666c0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlunicode.1
@@ -0,0 +1,2232 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNICODE 1"
+.TH PERLUNICODE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlunicode \- Unicode support in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+If you haven't already, before reading this document, you should become
+familiar with both perlunitut and perluniintro.
+.PP
+Unicode aims to \fBUNI\fR\-fy the en\-\fBCODE\fR\-ings of all the world's
+character sets into a single Standard.   For quite a few of the various
+coding standards that existed when Unicode was first created, converting
+from each to Unicode essentially meant adding a constant to each code
+point in the original standard, and converting back meant just
+subtracting that same constant.  For ASCII and ISO\-8859\-1, the constant
+is 0.  For ISO\-8859\-5, (Cyrillic) the constant is 864; for Hebrew
+(ISO\-8859\-8), it's 1488; Thai (ISO\-8859\-11), 3424; and so forth.  This
+made it easy to do the conversions, and facilitated the adoption of
+Unicode.
+.PP
+And it worked; nowadays, those legacy standards are rarely used.  Most
+everyone uses Unicode.
+.PP
+Unicode is a comprehensive standard.  It specifies many things outside
+the scope of Perl, such as how to display sequences of characters.  For
+a full discussion of all aspects of Unicode, see
+<https://www.unicode.org>.
+.SS "Important Caveats"
+.IX Subsection "Important Caveats"
+Even though some of this section may not be understandable to you on
+first reading, we think it's important enough to highlight some of the
+gotchas before delving further, so here goes:
+.PP
+Unicode support is an extensive requirement. While Perl does not
+implement the Unicode standard or the accompanying technical reports
+from cover to cover, Perl does support many Unicode features.
+.PP
+Also, the use of Unicode may present security issues that aren't
+obvious, see "Security Implications of Unicode" below.
+.ie n .IP "Safest if you ""use feature \*(Aqunicode_strings\*(Aq""" 4
+.el .IP "Safest if you \f(CWuse feature \*(Aqunicode_strings\*(Aq\fR" 4
+.IX Item "Safest if you use feature unicode_strings"
+In order to preserve backward compatibility, Perl does not turn
+on full internal Unicode support unless the pragma
+\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
+is specified.  (This is automatically
+selected if you \f(CW\*(C`use\ v5.12\*(C'\fR or higher.)  Failure to do this can
+trigger unexpected surprises.  See "The "Unicode Bug"" below.
+.Sp
+This pragma doesn't affect I/O.  Nor does it change the internal
+representation of strings, only their interpretation.  There are still
+several places where Unicode isn't fully supported, such as in
+filenames.
+.IP "Input and Output Layers" 4
+.IX Item "Input and Output Layers"
+Use the \f(CW:encoding(...)\fR layer  to read from and write to
+filehandles using the specified encoding.  (See open.)
+.IP "You must convert your non-ASCII, non\-UTF\-8 Perl scripts to be UTF\-8." 4
+.IX Item "You must convert your non-ASCII, non-UTF-8 Perl scripts to be UTF-8."
+The encoding module has been deprecated since perl 5.18 and the
+perl internals it requires have been removed with perl 5.26.
+.ie n .IP """use utf8"" still needed to enable UTF\-8 in scripts" 4
+.el .IP "\f(CWuse utf8\fR still needed to enable UTF\-8 in scripts" 4
+.IX Item "use utf8 still needed to enable UTF-8 in scripts"
+If your Perl script is itself encoded in UTF\-8,
+the \f(CW\*(C`use\ utf8\*(C'\fR pragma must be explicitly included to enable
+recognition of that (in string or regular expression literals, or in
+identifier names).  \fBThis is the only time when an explicit \fR\f(CB\*(C`use\ utf8\*(C'\fR\fB is needed.\fR  (See utf8).
+.Sp
+If a Perl script begins with the bytes that form the UTF\-8 encoding of
+the Unicode BYTE ORDER MARK (\f(CW\*(C`BOM\*(C'\fR, see "Unicode Encodings"), those
+bytes are completely ignored.
+.IP "UTF\-16 scripts autodetected" 4
+.IX Item "UTF-16 scripts autodetected"
+If a Perl script begins with the Unicode \f(CW\*(C`BOM\*(C'\fR (UTF\-16LE,
+UTF16\-BE), or if the script looks like non\-\f(CW\*(C`BOM\*(C'\fR\-marked
+UTF\-16 of either endianness, Perl will correctly read in the script as
+the appropriate Unicode encoding.
+.SS "Byte and Character Semantics"
+.IX Subsection "Byte and Character Semantics"
+Before Unicode, most encodings used 8 bits (a single byte) to encode
+each character.  Thus a character was a byte, and a byte was a
+character, and there could be only 256 or fewer possible characters.
+"Byte Semantics" in the title of this section refers to
+this behavior.  There was no need to distinguish between "Byte" and
+"Character".
+.PP
+Then along comes Unicode which has room for over a million characters
+(and Perl allows for even more).  This means that a character may
+require more than a single byte to represent it, and so the two terms
+are no longer equivalent.  What matter are the characters as whole
+entities, and not usually the bytes that comprise them.  That's what the
+term "Character Semantics" in the title of this section refers to.
+.PP
+Perl had to change internally to decouple "bytes" from "characters".
+It is important that you too change your ideas, if you haven't already,
+so that "byte" and "character" no longer mean the same thing in your
+mind.
+.PP
+The basic building block of Perl strings has always been a "character".
+The changes basically come down to that the implementation no longer
+thinks that a character is always just a single byte.
+.PP
+There are various things to note:
+.IP \(bu 4
+String handling functions, for the most part, continue to operate in
+terms of characters.  \f(CWlength()\fR, for example, returns the number of
+characters in a string, just as before.  But that number no longer is
+necessarily the same as the number of bytes in the string (there may be
+more bytes than characters).  The other such functions include
+\&\f(CWchop()\fR, \f(CWchomp()\fR, \f(CWsubstr()\fR, \f(CWpos()\fR, \f(CWindex()\fR, \f(CWrindex()\fR,
+\&\f(CWsort()\fR, \f(CWsprintf()\fR, and \f(CWwrite()\fR.
+.Sp
+The exceptions are:
+.RS 4
+.IP \(bu 4
+the bit-oriented \f(CW\*(C`vec\*(C'\fR
+.Sp
+\ 
+.IP \(bu 4
+the byte-oriented \f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR \f(CW"C"\fR format
+.Sp
+However, the \f(CW\*(C`W\*(C'\fR specifier does operate on whole characters, as does the
+\&\f(CW\*(C`U\*(C'\fR specifier.
+.IP \(bu 4
+some operators that interact with the platform's operating system
+.Sp
+Operators dealing with filenames are examples.
+.IP \(bu 4
+when the functions are called from within the scope of the
+\&\f(CW\*(C`use\ bytes\*(C'\fR pragma
+.Sp
+Likely, you should use this only for debugging anyway.
+.RE
+.RS 4
+.RE
+.IP \(bu 4
+Strings\-\-including hash keys\-\-and regular expression patterns may
+contain characters that have ordinal values larger than 255.
+.Sp
+If you use a Unicode editor to edit your program, Unicode characters may
+occur directly within the literal strings in UTF\-8 encoding, or UTF\-16.
+(The former requires a \f(CW\*(C`use utf8\*(C'\fR, the latter may require a \f(CW\*(C`BOM\*(C'\fR.)
+.Sp
+"Creating Unicode" in perluniintro gives other ways to place non-ASCII
+characters in your strings.
+.IP \(bu 4
+The \f(CWchr()\fR and \f(CWord()\fR functions work on whole characters.
+.IP \(bu 4
+Regular expressions match whole characters.  For example, \f(CW"."\fR matches
+a whole character instead of only a single byte.
+.IP \(bu 4
+The \f(CW\*(C`tr///\*(C'\fR operator translates whole characters.  (Note that the
+\&\f(CW\*(C`tr///CU\*(C'\fR functionality has been removed.  For similar functionality to
+that, see \f(CW\*(C`pack(\*(AqU0\*(Aq,\ ...)\*(C'\fR and \f(CW\*(C`pack(\*(AqC0\*(Aq,\ ...)\*(C'\fR).
+.IP \(bu 4
+\&\f(CW\*(C`scalar reverse()\*(C'\fR reverses by character rather than by byte.
+.IP \(bu 4
+The bit string operators, \f(CW\*(C`& | ^ ~\*(C'\fR and (starting in v5.22)
+\&\f(CW\*(C`&. |. ^.  ~.\*(C'\fR can operate on bit strings encoded in UTF\-8, but this
+can give unexpected results if any of the strings contain code points
+above 0xFF.  Starting in v5.28, it is a fatal error to have such an
+operand.  Otherwise, the operation is performed on a non\-UTF\-8 copy of
+the operand.  If you're not sure about the encoding of a string,
+downgrade it before using any of these operators; you can use
+\&\f(CWutf8::utf8_downgrade()\fR.
+.PP
+The bottom line is that Perl has always practiced "Character Semantics",
+but with the advent of Unicode, that is now different than "Byte
+Semantics".
+.SS "ASCII Rules versus Unicode Rules"
+.IX Subsection "ASCII Rules versus Unicode Rules"
+Before Unicode, when a character was a byte was a character,
+Perl knew only about the 128 characters defined by ASCII, code points 0
+through 127 (except for under \f(CW\*(C`use\ locale\*(C'\fR).  That
+left the code
+points 128 to 255 as unassigned, and available for whatever use a
+program might want.  The only semantics they have is their ordinal
+numbers, and that they are members of none of the non-negative character
+classes.  None are considered to match \f(CW\*(C`\ew\*(C'\fR for example, but all match
+\&\f(CW\*(C`\eW\*(C'\fR.
+.PP
+Unicode, of course, assigns each of those code points a particular
+meaning (along with ones above 255).  To preserve backward
+compatibility, Perl only uses the Unicode meanings when there is some
+indication that Unicode is what is intended; otherwise the non-ASCII
+code points remain treated as if they are unassigned.
+.PP
+Here are the ways that Perl knows that a string should be treated as
+Unicode:
+.IP \(bu 4
+Within the scope of \f(CW\*(C`use\ utf8\*(C'\fR
+.Sp
+If the whole program is Unicode (signified by using 8\-bit \fBU\fRnicode
+\&\fBT\fRransformation \fBF\fRormat), then all literal strings within it must be
+Unicode.
+.IP \(bu 4
+Within the scope of
+\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
+.Sp
+This pragma was created so you can explicitly tell Perl that operations
+executed within its scope are to use Unicode rules.  More operations are
+affected with newer perls.  See "The "Unicode Bug"".
+.IP \(bu 4
+Within the scope of \f(CW\*(C`use\ v5.12\*(C'\fR or higher
+.Sp
+This implicitly turns on \f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR.
+.IP \(bu 4
+Within the scope of
+\&\f(CW\*(C`use\ locale\ \*(Aqnot_characters\*(Aq\*(C'\fR,
+or \f(CW\*(C`use\ locale\*(C'\fR and the current
+locale is a UTF\-8 locale.
+.Sp
+The former is defined to imply Unicode handling; and the latter
+indicates a Unicode locale, hence a Unicode interpretation of all
+strings within it.
+.IP \(bu 4
+When the string contains a Unicode-only code point
+.Sp
+Perl has never accepted code points above 255 without them being
+Unicode, so their use implies Unicode for the whole string.
+.IP \(bu 4
+When the string contains a Unicode named code point \f(CW\*(C`\eN{...}\*(C'\fR
+.Sp
+The \f(CW\*(C`\eN{...}\*(C'\fR construct explicitly refers to a Unicode code point,
+even if it is one that is also in ASCII.  Therefore the string
+containing it must be Unicode.
+.IP \(bu 4
+When the string has come from an external source marked as
+Unicode
+.Sp
+The \f(CW\*(C`\-C\*(C'\fR command line option can
+specify that certain inputs to the program are Unicode, and the values
+of this can be read by your Perl code, see "${^UNICODE}" in perlvar.
+.IP \(bu 4
+When the string has been upgraded to UTF\-8
+.Sp
+The function \f(CWutf8::utf8_upgrade()\fR
+can be explicitly used to permanently (unless a subsequent
+\&\f(CWutf8::utf8_downgrade()\fR is called) cause a string to be treated as
+Unicode.
+.IP \(bu 4
+There are additional methods for regular expression patterns
+.Sp
+A pattern that is compiled with the \f(CW\*(C`/u\*(C'\fR or \f(CW\*(C`/a\*(C'\fR modifiers is
+treated as Unicode (though there are some restrictions with \f(CW\*(C`/a\*(C'\fR).
+Under the \f(CW\*(C`/d\*(C'\fR and \f(CW\*(C`/l\*(C'\fR modifiers, there are several other
+indications for Unicode; see "Character set modifiers" in perlre.
+.PP
+Note that all of the above are overridden within the scope of
+\&\f(CW\*(C`use bytes\*(C'\fR; but you should be using this pragma only for
+debugging.
+.PP
+Note also that some interactions with the platform's operating system
+never use Unicode rules.
+.PP
+When Unicode rules are in effect:
+.IP \(bu 4
+Case translation operators use the Unicode case translation tables.
+.Sp
+Note that \f(CWuc()\fR, or \f(CW\*(C`\eU\*(C'\fR in interpolated strings, translates to
+uppercase, while \f(CW\*(C`ucfirst\*(C'\fR, or \f(CW\*(C`\eu\*(C'\fR in interpolated strings,
+translates to titlecase in languages that make the distinction (which is
+equivalent to uppercase in languages without the distinction).
+.Sp
+There is a CPAN module, \f(CW\*(C`Unicode::Casing\*(C'\fR, which allows you to
+define your own mappings to be used in \f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR,
+\&\f(CWucfirst()\fR, and \f(CW\*(C`fc\*(C'\fR (or their double-quoted string inlined versions
+such as \f(CW\*(C`\eU\*(C'\fR).  (Prior to Perl 5.16, this functionality was partially
+provided in the Perl core, but suffered from a number of insurmountable
+drawbacks, so the CPAN module was written instead.)
+.IP \(bu 4
+Character classes in regular expressions match based on the character
+properties specified in the Unicode properties database.
+.Sp
+\&\f(CW\*(C`\ew\*(C'\fR can be used to match a Japanese ideograph, for instance; and
+\&\f(CW\*(C`[[:digit:]]\*(C'\fR a Bengali number.
+.IP \(bu 4
+Named Unicode properties, scripts, and block ranges may be used (like
+bracketed character classes) by using the \f(CW\*(C`\ep{}\*(C'\fR "matches property"
+construct and the \f(CW\*(C`\eP{}\*(C'\fR negation, "doesn't match property".
+.Sp
+See "Unicode Character Properties" for more details.
+.Sp
+You can define your own character properties and use them
+in the regular expression with the \f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR construct.
+See "User-Defined Character Properties" for more details.
+.SS "Extended Grapheme Clusters (Logical characters)"
+.IX Subsection "Extended Grapheme Clusters (Logical characters)"
+Consider a character, say \f(CW\*(C`H\*(C'\fR.  It could appear with various marks around it,
+such as an acute accent, or a circumflex, or various hooks, circles, arrows,
+\&\fIetc.\fR, above, below, to one side or the other, \fIetc\fR.  There are many
+possibilities among the world's languages.  The number of combinations is
+astronomical, and if there were a character for each combination, it would
+soon exhaust Unicode's more than a million possible characters.  So Unicode
+took a different approach: there is a character for the base \f(CW\*(C`H\*(C'\fR, and a
+character for each of the possible marks, and these can be variously combined
+to get a final logical character.  So a logical character\-\-what appears to be a
+single character\-\-can be a sequence of more than one individual characters.
+The Unicode standard calls these "extended grapheme clusters" (which
+is an improved version of the no-longer much used "grapheme cluster");
+Perl furnishes the \f(CW\*(C`\eX\*(C'\fR regular expression construct to match such
+sequences in their entirety.
+.PP
+But Unicode's intent is to unify the existing character set standards and
+practices, and several pre-existing standards have single characters that
+mean the same thing as some of these combinations, like ISO\-8859\-1,
+which has quite a few of them. For example, \f(CW"LATIN CAPITAL LETTER E
+WITH ACUTE"\fR was already in this standard when Unicode came along.
+Unicode therefore added it to its repertoire as that single character.
+But this character is considered by Unicode to be equivalent to the
+sequence consisting of the character \f(CW"LATIN CAPITAL LETTER E"\fR
+followed by the character \f(CW"COMBINING ACUTE ACCENT"\fR.
+.PP
+\&\f(CW"LATIN CAPITAL LETTER E WITH ACUTE"\fR is called a "pre-composed"
+character, and its equivalence with the "E" and the "COMBINING ACCENT"
+sequence is called canonical equivalence.  All pre-composed characters
+are said to have a decomposition (into the equivalent sequence), and the
+decomposition type is also called canonical.  A string may be comprised
+as much as possible of precomposed characters, or it may be comprised of
+entirely decomposed characters.  Unicode calls these respectively,
+"Normalization Form Composed" (NFC) and "Normalization Form Decomposed".
+The \f(CW\*(C`Unicode::Normalize\*(C'\fR module contains functions that convert
+between the two.  A string may also have both composed characters and
+decomposed characters; this module can be used to make it all one or the
+other.
+.PP
+You may be presented with strings in any of these equivalent forms.
+There is currently nothing in Perl 5 that ignores the differences.  So
+you'll have to specially handle it.  The usual advice is to convert your
+inputs to \f(CW\*(C`NFD\*(C'\fR before processing further.
+.PP
+For more detailed information, see <http://unicode.org/reports/tr15/>.
+.SS "Unicode Character Properties"
+.IX Subsection "Unicode Character Properties"
+(The only time that Perl considers a sequence of individual code
+points as a single logical character is in the \f(CW\*(C`\eX\*(C'\fR construct, already
+mentioned above.   Therefore "character" in this discussion means a single
+Unicode code point.)
+.PP
+Very nearly all Unicode character properties are accessible through
+regular expressions by using the \f(CW\*(C`\ep{}\*(C'\fR "matches property" construct
+and the \f(CW\*(C`\eP{}\*(C'\fR "doesn't match property" for its negation.
+.PP
+For instance, \f(CW\*(C`\ep{Uppercase}\*(C'\fR matches any single character with the Unicode
+\&\f(CW"Uppercase"\fR property, while \f(CW\*(C`\ep{L}\*(C'\fR matches any character with a
+\&\f(CW\*(C`General_Category\*(C'\fR of \f(CW"L"\fR (letter) property (see
+"General_Category" below).  Brackets are not
+required for single letter property names, so \f(CW\*(C`\ep{L}\*(C'\fR is equivalent to \f(CW\*(C`\epL\*(C'\fR.
+.PP
+More formally, \f(CW\*(C`\ep{Uppercase}\*(C'\fR matches any single character whose Unicode
+\&\f(CW\*(C`Uppercase\*(C'\fR property value is \f(CW\*(C`True\*(C'\fR, and \f(CW\*(C`\eP{Uppercase}\*(C'\fR matches any character
+whose \f(CW\*(C`Uppercase\*(C'\fR property value is \f(CW\*(C`False\*(C'\fR, and they could have been written as
+\&\f(CW\*(C`\ep{Uppercase=True}\*(C'\fR and \f(CW\*(C`\ep{Uppercase=False}\*(C'\fR, respectively.
+.PP
+This formality is needed when properties are not binary; that is, if they can
+take on more values than just \f(CW\*(C`True\*(C'\fR and \f(CW\*(C`False\*(C'\fR.  For example, the
+\&\f(CW\*(C`Bidi_Class\*(C'\fR property (see "Bidirectional Character Types" below),
+can take on several different
+values, such as \f(CW\*(C`Left\*(C'\fR, \f(CW\*(C`Right\*(C'\fR, \f(CW\*(C`Whitespace\*(C'\fR, and others.  To match these, one needs
+to specify both the property name (\f(CW\*(C`Bidi_Class\*(C'\fR), AND the value being
+matched against
+(\f(CW\*(C`Left\*(C'\fR, \f(CW\*(C`Right\*(C'\fR, \fIetc.\fR).  This is done, as in the examples above, by having the
+two components separated by an equal sign (or interchangeably, a colon), like
+\&\f(CW\*(C`\ep{Bidi_Class: Left}\*(C'\fR.
+.PP
+All Unicode-defined character properties may be written in these compound forms
+of \f(CW\*(C`\ep{\fR\f(CIproperty\fR\f(CW=\fR\f(CIvalue\fR\f(CW}\*(C'\fR or \f(CW\*(C`\ep{\fR\f(CIproperty\fR\f(CW:\fR\f(CIvalue\fR\f(CW}\*(C'\fR, but Perl provides some
+additional properties that are written only in the single form, as well as
+single-form short-cuts for all binary properties and certain others described
+below, in which you may omit the property name and the equals or colon
+separator.
+.PP
+Most Unicode character properties have at least two synonyms (or aliases if you
+prefer): a short one that is easier to type and a longer one that is more
+descriptive and hence easier to understand.  Thus the \f(CW"L"\fR and
+\&\f(CW"Letter"\fR properties above are equivalent and can be used
+interchangeably.  Likewise, \f(CW"Upper"\fR is a synonym for \f(CW"Uppercase"\fR,
+and we could have written \f(CW\*(C`\ep{Uppercase}\*(C'\fR equivalently as \f(CW\*(C`\ep{Upper}\*(C'\fR.
+Also, there are typically various synonyms for the values the property
+can be.   For binary properties, \f(CW"True"\fR has 3 synonyms: \f(CW"T"\fR,
+\&\f(CW"Yes"\fR, and \f(CW"Y"\fR; and \f(CW"False"\fR has correspondingly \f(CW"F"\fR,
+\&\f(CW"No"\fR, and \f(CW"N"\fR.  But be careful.  A short form of a value for one
+property may not mean the same thing as the short form spelled the same
+for another.
+Thus, for the \f(CW"General_Category"\fR property, \f(CW"L"\fR means
+\&\f(CW"Letter"\fR, but for the \f(CW\*(C`Bidi_Class\*(C'\fR
+property, \f(CW"L"\fR means \f(CW"Left"\fR.  A complete list of properties and
+synonyms is in perluniprops.
+.PP
+Upper/lower case differences in property names and values are irrelevant;
+thus \f(CW\*(C`\ep{Upper}\*(C'\fR means the same thing as \f(CW\*(C`\ep{upper}\*(C'\fR or even \f(CW\*(C`\ep{UpPeR}\*(C'\fR.
+Similarly, you can add or subtract underscores anywhere in the middle of a
+word, so that these are also equivalent to \f(CW\*(C`\ep{U_p_p_e_r}\*(C'\fR.  And white space
+is generally irrelevant adjacent to non-word characters, such as the
+braces and the equals or colon separators, so \f(CW\*(C`\ep{   Upper  }\*(C'\fR and
+\&\f(CW\*(C`\ep{ Upper_case : Y }\*(C'\fR are equivalent to these as well.  In fact, white
+space and even hyphens can usually be added or deleted anywhere.  So
+even \f(CW\*(C`\ep{ Up\-per case = Yes}\*(C'\fR is equivalent.  All this is called
+"loose-matching" by Unicode.  The "name" property has some restrictions
+on this due to a few outlier names.  Full details are given in
+<https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>.
+.PP
+The few places where stricter matching is
+used is in the middle of numbers, the "name" property, and in the Perl
+extension properties that begin or end with an underscore.  Stricter
+matching cares about white space (except adjacent to non-word
+characters), hyphens, and non-interior underscores.
+.PP
+You can also use negation in both \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR by introducing a caret
+(\f(CW\*(C`^\*(C'\fR) between the first brace and the property name: \f(CW\*(C`\ep{^Tamil}\*(C'\fR is
+equal to \f(CW\*(C`\eP{Tamil}\*(C'\fR.
+.PP
+Almost all properties are immune to case-insensitive matching.  That is,
+adding a \f(CW\*(C`/i\*(C'\fR regular expression modifier does not change what they
+match.  There are two sets that are affected.
+The first set is
+\&\f(CW\*(C`Uppercase_Letter\*(C'\fR,
+\&\f(CW\*(C`Lowercase_Letter\*(C'\fR,
+and \f(CW\*(C`Titlecase_Letter\*(C'\fR,
+all of which match \f(CW\*(C`Cased_Letter\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
+And the second set is
+\&\f(CW\*(C`Uppercase\*(C'\fR,
+\&\f(CW\*(C`Lowercase\*(C'\fR,
+and \f(CW\*(C`Titlecase\*(C'\fR,
+all of which match \f(CW\*(C`Cased\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
+This set also includes its subsets \f(CW\*(C`PosixUpper\*(C'\fR and \f(CW\*(C`PosixLower\*(C'\fR both
+of which under \f(CW\*(C`/i\*(C'\fR match \f(CW\*(C`PosixAlpha\*(C'\fR.
+(The difference between these sets is that some things, such as Roman
+numerals, come in both upper and lower case so they are \f(CW\*(C`Cased\*(C'\fR, but
+aren't considered letters, so they aren't \f(CW\*(C`Cased_Letter\*(C'\fR's.)
+.PP
+See "Beyond Unicode code points" for special considerations when
+matching Unicode properties against non-Unicode code points.
+.PP
+\fR\f(BIGeneral_Category\fR\fI\fR
+.IX Subsection "General_Category"
+.PP
+Every Unicode character is assigned a general category, which is the "most
+usual categorization of a character" (from
+<https://www.unicode.org/reports/tr44>).
+.PP
+The compound way of writing these is like \f(CW\*(C`\ep{General_Category=Number}\*(C'\fR
+(short: \f(CW\*(C`\ep{gc:n}\*(C'\fR).  But Perl furnishes shortcuts in which everything up
+through the equal or colon separator is omitted.  So you can instead just write
+\&\f(CW\*(C`\epN\*(C'\fR.
+.PP
+Here are the short and long forms of the values the \f(CW\*(C`General Category\*(C'\fR property
+can have:
+.PP
+.Vb 1
+\&    Short       Long
+\&
+\&    L           Letter
+\&    LC, L&      Cased_Letter (that is: [\ep{Ll}\ep{Lu}\ep{Lt}])
+\&    Lu          Uppercase_Letter
+\&    Ll          Lowercase_Letter
+\&    Lt          Titlecase_Letter
+\&    Lm          Modifier_Letter
+\&    Lo          Other_Letter
+\&
+\&    M           Mark
+\&    Mn          Nonspacing_Mark
+\&    Mc          Spacing_Mark
+\&    Me          Enclosing_Mark
+\&
+\&    N           Number
+\&    Nd          Decimal_Number (also Digit)
+\&    Nl          Letter_Number
+\&    No          Other_Number
+\&
+\&    P           Punctuation (also Punct)
+\&    Pc          Connector_Punctuation
+\&    Pd          Dash_Punctuation
+\&    Ps          Open_Punctuation
+\&    Pe          Close_Punctuation
+\&    Pi          Initial_Punctuation
+\&                (may behave like Ps or Pe depending on usage)
+\&    Pf          Final_Punctuation
+\&                (may behave like Ps or Pe depending on usage)
+\&    Po          Other_Punctuation
+\&
+\&    S           Symbol
+\&    Sm          Math_Symbol
+\&    Sc          Currency_Symbol
+\&    Sk          Modifier_Symbol
+\&    So          Other_Symbol
+\&
+\&    Z           Separator
+\&    Zs          Space_Separator
+\&    Zl          Line_Separator
+\&    Zp          Paragraph_Separator
+\&
+\&    C           Other
+\&    Cc          Control (also Cntrl)
+\&    Cf          Format
+\&    Cs          Surrogate
+\&    Co          Private_Use
+\&    Cn          Unassigned
+.Ve
+.PP
+Single-letter properties match all characters in any of the
+two-letter sub-properties starting with the same letter.
+\&\f(CW\*(C`LC\*(C'\fR and \f(CW\*(C`L&\*(C'\fR are special: both are aliases for the set consisting of everything matched by \f(CW\*(C`Ll\*(C'\fR, \f(CW\*(C`Lu\*(C'\fR, and \f(CW\*(C`Lt\*(C'\fR.
+.PP
+\fR\f(BIBidirectional Character Types\fR\fI\fR
+.IX Subsection "Bidirectional Character Types"
+.PP
+Because scripts differ in their directionality (Hebrew and Arabic are
+written right to left, for example) Unicode supplies a \f(CW\*(C`Bidi_Class\*(C'\fR property.
+Some of the values this property can have are:
+.PP
+.Vb 1
+\&    Value       Meaning
+\&
+\&    L           Left\-to\-Right
+\&    LRE         Left\-to\-Right Embedding
+\&    LRO         Left\-to\-Right Override
+\&    R           Right\-to\-Left
+\&    AL          Arabic Letter
+\&    RLE         Right\-to\-Left Embedding
+\&    RLO         Right\-to\-Left Override
+\&    PDF         Pop Directional Format
+\&    EN          European Number
+\&    ES          European Separator
+\&    ET          European Terminator
+\&    AN          Arabic Number
+\&    CS          Common Separator
+\&    NSM         Non\-Spacing Mark
+\&    BN          Boundary Neutral
+\&    B           Paragraph Separator
+\&    S           Segment Separator
+\&    WS          Whitespace
+\&    ON          Other Neutrals
+.Ve
+.PP
+This property is always written in the compound form.
+For example, \f(CW\*(C`\ep{Bidi_Class:R}\*(C'\fR matches characters that are normally
+written right to left.  Unlike the
+\&\f(CW"General_Category"\fR property, this
+property can have more values added in a future Unicode release.  Those
+listed above comprised the complete set for many Unicode releases, but
+others were added in Unicode 6.3; you can always find what the
+current ones are in perluniprops.  And
+<https://www.unicode.org/reports/tr9/> describes how to use them.
+.PP
+\fR\f(BIScripts\fR\fI\fR
+.IX Subsection "Scripts"
+.PP
+The world's languages are written in many different scripts.  This sentence
+(unless you're reading it in translation) is written in Latin, while Russian is
+written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
+Hiragana or Katakana.  There are many more.
+.PP
+The Unicode \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR properties give what
+script a given character is in.  The \f(CW\*(C`Script_Extensions\*(C'\fR property is an
+improved version of \f(CW\*(C`Script\*(C'\fR, as demonstrated below.  Either property
+can be specified with the compound form like
+\&\f(CW\*(C`\ep{Script=Hebrew}\*(C'\fR (short: \f(CW\*(C`\ep{sc=hebr}\*(C'\fR), or
+\&\f(CW\*(C`\ep{Script_Extensions=Javanese}\*(C'\fR (short: \f(CW\*(C`\ep{scx=java}\*(C'\fR).
+In addition, Perl furnishes shortcuts for all
+\&\f(CW\*(C`Script_Extensions\*(C'\fR property names.  You can omit everything up through
+the equals (or colon), and simply write \f(CW\*(C`\ep{Latin}\*(C'\fR or \f(CW\*(C`\eP{Cyrillic}\*(C'\fR.
+(This is not true for \f(CW\*(C`Script\*(C'\fR, which is required to be
+written in the compound form.  Prior to Perl v5.26, the single form
+returned the plain old \f(CW\*(C`Script\*(C'\fR version, but was changed because
+\&\f(CW\*(C`Script_Extensions\*(C'\fR gives better results.)
+.PP
+The difference between these two properties involves characters that are
+used in multiple scripts.  For example the digits '0' through '9' are
+used in many parts of the world.  These are placed in a script named
+\&\f(CW\*(C`Common\*(C'\fR.  Other characters are used in just a few scripts.  For
+example, the \f(CW"KATAKANA\-HIRAGANA DOUBLE HYPHEN"\fR is used in both Japanese
+scripts, Katakana and Hiragana, but nowhere else.  The \f(CW\*(C`Script\*(C'\fR
+property places all characters that are used in multiple scripts in the
+\&\f(CW\*(C`Common\*(C'\fR script, while the \f(CW\*(C`Script_Extensions\*(C'\fR property places those
+that are used in only a few scripts into each of those scripts; while
+still using \f(CW\*(C`Common\*(C'\fR for those used in many scripts.  Thus both these
+match:
+.PP
+.Vb 2
+\& "0" =~ /\ep{sc=Common}/     # Matches
+\& "0" =~ /\ep{scx=Common}/    # Matches
+.Ve
+.PP
+and only the first of these match:
+.PP
+.Vb 2
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Common}  # Matches
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Common} # No match
+.Ve
+.PP
+And only the last two of these match:
+.PP
+.Vb 4
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Hiragana}  # No match
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Katakana}  # No match
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Hiragana} # Matches
+\& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Katakana} # Matches
+.Ve
+.PP
+\&\f(CW\*(C`Script_Extensions\*(C'\fR is thus an improved \f(CW\*(C`Script\*(C'\fR, in which there are
+fewer characters in the \f(CW\*(C`Common\*(C'\fR script, and correspondingly more in
+other scripts.  It is new in Unicode version 6.0, and its data are likely
+to change significantly in later releases, as things get sorted out.
+New code should probably be using \f(CW\*(C`Script_Extensions\*(C'\fR and not plain
+\&\f(CW\*(C`Script\*(C'\fR.  If you compile perl with a Unicode release that doesn't have
+\&\f(CW\*(C`Script_Extensions\*(C'\fR, the single form Perl extensions will instead refer
+to the plain \f(CW\*(C`Script\*(C'\fR property.  If you compile with a version of
+Unicode that doesn't have the \f(CW\*(C`Script\*(C'\fR property, these extensions will
+not be defined at all.
+.PP
+(Actually, besides \f(CW\*(C`Common\*(C'\fR, the \f(CW\*(C`Inherited\*(C'\fR script, contains
+characters that are used in multiple scripts.  These are modifier
+characters which inherit the script value
+of the controlling character.  Some of these are used in many scripts,
+and so go into \f(CW\*(C`Inherited\*(C'\fR in both \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR.
+Others are used in just a few scripts, so are in \f(CW\*(C`Inherited\*(C'\fR in
+\&\f(CW\*(C`Script\*(C'\fR, but not in \f(CW\*(C`Script_Extensions\*(C'\fR.)
+.PP
+It is worth stressing that there are several different sets of digits in
+Unicode that are equivalent to 0\-9 and are matchable by \f(CW\*(C`\ed\*(C'\fR in a
+regular expression.  If they are used in a single language only, they
+are in that language's \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR.  If they are
+used in more than one script, they will be in \f(CW\*(C`sc=Common\*(C'\fR, but only
+if they are used in many scripts should they be in \f(CW\*(C`scx=Common\*(C'\fR.
+.PP
+The explanation above has omitted some detail; refer to UAX#24 "Unicode
+Script Property": <https://www.unicode.org/reports/tr24>.
+.PP
+A complete list of scripts and their shortcuts is in perluniprops.
+.PP
+\fR\f(BIUse of the \fR\f(CB"Is"\fR\f(BI Prefix\fR\fI\fR
+.IX Subsection "Use of the ""Is"" Prefix"
+.PP
+For backward compatibility (with ancient Perl 5.6), all properties writable
+without using the compound form mentioned
+so far may have \f(CW\*(C`Is\*(C'\fR or \f(CW\*(C`Is_\*(C'\fR prepended to their name, so \f(CW\*(C`\eP{Is_Lu}\*(C'\fR, for
+example, is equal to \f(CW\*(C`\eP{Lu}\*(C'\fR, and \f(CW\*(C`\ep{IsScript:Arabic}\*(C'\fR is equal to
+\&\f(CW\*(C`\ep{Arabic}\*(C'\fR.
+.PP
+\fR\f(BIBlocks\fR\fI\fR
+.IX Subsection "Blocks"
+.PP
+In addition to \fBscripts\fR, Unicode also defines \fBblocks\fR of
+characters.  The difference between scripts and blocks is that the
+concept of scripts is closer to natural languages, while the concept
+of blocks is more of an artificial grouping based on groups of Unicode
+characters with consecutive ordinal values. For example, the \f(CW"Basic Latin"\fR
+block is all the characters whose ordinals are between 0 and 127, inclusive; in
+other words, the ASCII characters.  The \f(CW"Latin"\fR script contains some letters
+from this as well as several other blocks, like \f(CW"Latin\-1 Supplement"\fR,
+\&\f(CW"Latin Extended\-A"\fR, \fIetc.\fR, but it does not contain all the characters from
+those blocks. It does not, for example, contain the digits 0\-9, because
+those digits are shared across many scripts, and hence are in the
+\&\f(CW\*(C`Common\*(C'\fR script.
+.PP
+For more about scripts versus blocks, see UAX#24 "Unicode Script Property":
+<https://www.unicode.org/reports/tr24>
+.PP
+The \f(CW\*(C`Script_Extensions\*(C'\fR or \f(CW\*(C`Script\*(C'\fR properties are likely to be the
+ones you want to use when processing
+natural language; the \f(CW\*(C`Block\*(C'\fR property may occasionally be useful in working
+with the nuts and bolts of Unicode.
+.PP
+Block names are matched in the compound form, like \f(CW\*(C`\ep{Block: Arrows}\*(C'\fR or
+\&\f(CW\*(C`\ep{Blk=Hebrew}\*(C'\fR.  Unlike most other properties, only a few block names have a
+Unicode-defined short name.
+.PP
+Perl also defines single form synonyms for the block property in cases
+where these do not conflict with something else.  But don't use any of
+these, because they are unstable.  Since these are Perl extensions, they
+are subordinate to official Unicode property names; Unicode doesn't know
+nor care about Perl's extensions.  It may happen that a name that
+currently means the Perl extension will later be changed without warning
+to mean a different Unicode property in a future version of the perl
+interpreter that uses a later Unicode release, and your code would no
+longer work.  The extensions are mentioned here for completeness:  Take
+the block name and prefix it with one of: \f(CW\*(C`In\*(C'\fR (for example
+\&\f(CW\*(C`\ep{Blk=Arrows}\*(C'\fR can currently be written as \f(CW\*(C`\ep{In_Arrows}\*(C'\fR); or
+sometimes \f(CW\*(C`Is\*(C'\fR (like \f(CW\*(C`\ep{Is_Arrows}\*(C'\fR); or sometimes no prefix at all
+(\f(CW\*(C`\ep{Arrows}\*(C'\fR).  As of this writing (Unicode 9.0) there are no
+conflicts with using the \f(CW\*(C`In_\*(C'\fR prefix, but there are plenty with the
+other two forms.  For example, \f(CW\*(C`\ep{Is_Hebrew}\*(C'\fR and \f(CW\*(C`\ep{Hebrew}\*(C'\fR mean
+\&\f(CW\*(C`\ep{Script_Extensions=Hebrew}\*(C'\fR which is NOT the same thing as
+\&\f(CW\*(C`\ep{Blk=Hebrew}\*(C'\fR.  Our
+advice used to be to use the \f(CW\*(C`In_\*(C'\fR prefix as a single form way of
+specifying a block.  But Unicode 8.0 added properties whose names begin
+with \f(CW\*(C`In\*(C'\fR, and it's now clear that it's only luck that's so far
+prevented a conflict.  Using \f(CW\*(C`In\*(C'\fR is only marginally less typing than
+\&\f(CW\*(C`Blk:\*(C'\fR, and the latter's meaning is clearer anyway, and guaranteed to
+never conflict.  So don't take chances.  Use \f(CW\*(C`\ep{Blk=foo}\*(C'\fR for new
+code.  And be sure that block is what you really really want to do.  In
+most cases scripts are what you want instead.
+.PP
+A complete list of blocks is in perluniprops.
+.PP
+\fR\f(BIOther Properties\fR\fI\fR
+.IX Subsection "Other Properties"
+.PP
+There are many more properties than the very basic ones described here.
+A complete list is in perluniprops.
+.PP
+Unicode defines all its properties in the compound form, so all single-form
+properties are Perl extensions.  Most of these are just synonyms for the
+Unicode ones, but some are genuine extensions, including several that are in
+the compound form.  And quite a few of these are actually recommended by Unicode
+(in <https://www.unicode.org/reports/tr18>).
+.PP
+This section gives some details on all extensions that aren't just
+synonyms for compound-form Unicode properties
+(for those properties, you'll have to refer to the
+Unicode Standard <https://www.unicode.org/reports/tr44>.
+.ie n .IP "\fR\fB""\ep{All}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{All}\fR\fB\fR 4
+.IX Item "p{All}"
+This matches every possible code point.  It is equivalent to \f(CW\*(C`qr/./s\*(C'\fR.
+Unlike all the other non-user-defined \f(CW\*(C`\ep{}\*(C'\fR property matches, no
+warning is ever generated if this is property is matched against a
+non-Unicode code point (see "Beyond Unicode code points" below).
+.ie n .IP "\fR\fB""\ep{Alnum}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Alnum}\fR\fB\fR 4
+.IX Item "p{Alnum}"
+This matches any \f(CW\*(C`\ep{Alphabetic}\*(C'\fR or \f(CW\*(C`\ep{Decimal_Number}\*(C'\fR character.
+.ie n .IP "\fR\fB""\ep{Any}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Any}\fR\fB\fR 4
+.IX Item "p{Any}"
+This matches any of the 1_114_112 Unicode code points.  It is a synonym
+for \f(CW\*(C`\ep{Unicode}\*(C'\fR.
+.ie n .IP "\fR\fB""\ep{ASCII}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{ASCII}\fR\fB\fR 4
+.IX Item "p{ASCII}"
+This matches any of the 128 characters in the US-ASCII character set,
+which is a subset of Unicode.
+.ie n .IP "\fR\fB""\ep{Assigned}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Assigned}\fR\fB\fR 4
+.IX Item "p{Assigned}"
+This matches any assigned code point; that is, any code point whose general
+category is not \f(CW\*(C`Unassigned\*(C'\fR (or equivalently, not \f(CW\*(C`Cn\*(C'\fR).
+.ie n .IP "\fR\fB""\ep{Blank}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Blank}\fR\fB\fR 4
+.IX Item "p{Blank}"
+This is the same as \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ep{HorizSpace}\*(C'\fR:  A character that changes the
+spacing horizontally.
+.ie n .IP "\fR\fB""\ep{Decomposition_Type: Non_Canonical}""\fR\fB\fR    (Short: ""\ep{Dt=NonCanon}"")" 4
+.el .IP "\fR\f(CB\ep{Decomposition_Type: Non_Canonical}\fR\fB\fR    (Short: \f(CW\ep{Dt=NonCanon}\fR)" 4
+.IX Item "p{Decomposition_Type: Non_Canonical} (Short: p{Dt=NonCanon})"
+Matches a character that has any of the non-canonical decomposition
+types.  Canonical decompositions are introduced in the
+"Extended Grapheme Clusters (Logical characters)" section above.
+However, many more characters have a different type of decomposition,
+generically called "compatible" decompositions, or "non-canonical".  The
+sequences that form these decompositions are not considered canonically
+equivalent to the pre-composed character.  An example is the
+\&\f(CW"SUPERSCRIPT ONE"\fR.  It is somewhat like a regular digit 1, but not
+exactly; its decomposition into the digit 1 is called a "compatible"
+decomposition, specifically a "super" (for "superscript") decomposition.
+There are several such compatibility decompositions (see
+<https://www.unicode.org/reports/tr44>).  \f(CW\*(C`\ep{Dt:\ Non_Canon}\*(C'\fR is a
+Perl extension that uses just one name to refer to the union of all of
+them.
+.Sp
+Most Unicode characters don't have a decomposition, so their
+decomposition type is \f(CW"None"\fR.  Hence, \f(CW\*(C`Non_Canonical\*(C'\fR is equivalent
+to
+.Sp
+.Vb 1
+\& qr/(?[ \eP{DT=Canonical} \- \ep{DT=None} ])/
+.Ve
+.Sp
+(Note that one of the non-canonical decompositions is named "compat",
+which could perhaps have been better named "miscellaneous".  It includes
+just the things that Unicode couldn't figure out a better generic name
+for.)
+.ie n .IP "\fR\fB""\ep{Graph}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Graph}\fR\fB\fR 4
+.IX Item "p{Graph}"
+Matches any character that is graphic.  Theoretically, this means a character
+that on a printer would cause ink to be used.
+.ie n .IP "\fR\fB""\ep{HorizSpace}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{HorizSpace}\fR\fB\fR 4
+.IX Item "p{HorizSpace}"
+This is the same as \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ep{Blank}\*(C'\fR:  a character that changes the
+spacing horizontally.
+.ie n .IP "\fR\fB""\ep{In=*}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{In=*}\fR\fB\fR 4
+.IX Item "p{In=*}"
+This is a synonym for \f(CW\*(C`\ep{Present_In=*}\*(C'\fR
+.ie n .IP "\fR\fB""\ep{PerlSpace}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{PerlSpace}\fR\fB\fR 4
+.IX Item "p{PerlSpace}"
+This is the same as \f(CW\*(C`\es\*(C'\fR, restricted to ASCII, namely \f(CW\*(C`[\ \ef\en\er\et]\*(C'\fR
+and starting in Perl v5.18, a vertical tab.
+.Sp
+Mnemonic: Perl's (original) space
+.ie n .IP "\fR\fB""\ep{PerlWord}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{PerlWord}\fR\fB\fR 4
+.IX Item "p{PerlWord}"
+This is the same as \f(CW\*(C`\ew\*(C'\fR, restricted to ASCII, namely \f(CW\*(C`[A\-Za\-z0\-9_]\*(C'\fR
+.Sp
+Mnemonic: Perl's (original) word.
+.ie n .IP "\fR\fB""\ep{Posix...}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Posix...}\fR\fB\fR 4
+.IX Item "p{Posix...}"
+There are several of these, which are equivalents, using the \f(CW\*(C`\ep{}\*(C'\fR
+notation, for Posix classes and are described in
+"POSIX Character Classes" in perlrecharclass.
+.ie n .IP "\fR\fB""\ep{Present_In: *}""\fR\fB\fR    (Short: ""\ep{In=*}"")" 4
+.el .IP "\fR\f(CB\ep{Present_In: *}\fR\fB\fR    (Short: \f(CW\ep{In=*}\fR)" 4
+.IX Item "p{Present_In: *} (Short: p{In=*})"
+This property is used when you need to know in what Unicode version(s) a
+character is.
+.Sp
+The "*" above stands for some Unicode version number, such as
+\&\f(CW1.1\fR or \f(CW12.0\fR; or the "*" can also be \f(CW\*(C`Unassigned\*(C'\fR.  This property will
+match the code points whose final disposition has been settled as of the
+Unicode release given by the version number; \f(CW\*(C`\ep{Present_In: Unassigned}\*(C'\fR
+will match those code points whose meaning has yet to be assigned.
+.Sp
+For example, \f(CW\*(C`U+0041\*(C'\fR \f(CW"LATIN CAPITAL LETTER A"\fR was present in the very first
+Unicode release available, which is \f(CW1.1\fR, so this property is true for all
+valid "*" versions.  On the other hand, \f(CW\*(C`U+1EFF\*(C'\fR was not assigned until version
+5.1 when it became \f(CW"LATIN SMALL LETTER Y WITH LOOP"\fR, so the only "*" that
+would match it are 5.1, 5.2, and later.
+.Sp
+Unicode furnishes the \f(CW\*(C`Age\*(C'\fR property from which this is derived.  The problem
+with Age is that a strict interpretation of it (which Perl takes) has it
+matching the precise release a code point's meaning is introduced in.  Thus
+\&\f(CW\*(C`U+0041\*(C'\fR would match only 1.1; and \f(CW\*(C`U+1EFF\*(C'\fR only 5.1.  This is not usually what
+you want.
+.Sp
+Some non-Perl implementations of the Age property may change its meaning to be
+the same as the Perl \f(CW\*(C`Present_In\*(C'\fR property; just be aware of that.
+.Sp
+Another confusion with both these properties is that the definition is not
+that the code point has been \fIassigned\fR, but that the meaning of the code point
+has been \fIdetermined\fR.  This is because 66 code points will always be
+unassigned, and so the \f(CW\*(C`Age\*(C'\fR for them is the Unicode version in which the decision
+to make them so was made.  For example, \f(CW\*(C`U+FDD0\*(C'\fR is to be permanently
+unassigned to a character, and the decision to do that was made in version 3.1,
+so \f(CW\*(C`\ep{Age=3.1}\*(C'\fR matches this character, as also does \f(CW\*(C`\ep{Present_In: 3.1}\*(C'\fR and up.
+.ie n .IP "\fR\fB""\ep{Print}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Print}\fR\fB\fR 4
+.IX Item "p{Print}"
+This matches any character that is graphical or blank, except controls.
+.ie n .IP "\fR\fB""\ep{SpacePerl}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{SpacePerl}\fR\fB\fR 4
+.IX Item "p{SpacePerl}"
+This is the same as \f(CW\*(C`\es\*(C'\fR, including beyond ASCII.
+.Sp
+Mnemonic: Space, as modified by Perl.  (It doesn't include the vertical tab
+until v5.18, which both the Posix standard and Unicode consider white space.)
+.ie n .IP "\fR\fB""\ep{Title}""\fR\fB\fR and  \fB\fR\fB""\ep{Titlecase}""\fR\fB\fR" 4
+.el .IP "\fR\f(CB\ep{Title}\fR\fB\fR and  \fB\fR\f(CB\ep{Titlecase}\fR\fB\fR" 4
+.IX Item "p{Title} and p{Titlecase}"
+Under case-sensitive matching, these both match the same code points as
+\&\f(CW\*(C`\ep{General Category=Titlecase_Letter}\*(C'\fR (\f(CW\*(C`\ep{gc=lt}\*(C'\fR).  The difference
+is that under \f(CW\*(C`/i\*(C'\fR caseless matching, these match the same as
+\&\f(CW\*(C`\ep{Cased}\*(C'\fR, whereas \f(CW\*(C`\ep{gc=lt}\*(C'\fR matches \f(CW\*(C`\ep{Cased_Letter\*(C'\fR).
+.ie n .IP "\fR\fB""\ep{Unicode}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Unicode}\fR\fB\fR 4
+.IX Item "p{Unicode}"
+This matches any of the 1_114_112 Unicode code points.
+\&\f(CW\*(C`\ep{Any}\*(C'\fR.
+.ie n .IP "\fR\fB""\ep{VertSpace}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{VertSpace}\fR\fB\fR 4
+.IX Item "p{VertSpace}"
+This is the same as \f(CW\*(C`\ev\*(C'\fR:  A character that changes the spacing vertically.
+.ie n .IP "\fR\fB""\ep{Word}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{Word}\fR\fB\fR 4
+.IX Item "p{Word}"
+This is the same as \f(CW\*(C`\ew\*(C'\fR, including over 100_000 characters beyond ASCII.
+.ie n .IP "\fR\fB""\ep{XPosix...}""\fR\fB\fR" 4
+.el .IP \fR\f(CB\ep{XPosix...}\fR\fB\fR 4
+.IX Item "p{XPosix...}"
+There are several of these, which are the standard Posix classes
+extended to the full Unicode range.  They are described in
+"POSIX Character Classes" in perlrecharclass.
+.ie n .SS "Comparison of ""\eN{...}"" and ""\ep{name=...}"""
+.el .SS "Comparison of \f(CW\eN{...}\fP and \f(CW\ep{name=...}\fP"
+.IX Subsection "Comparison of N{...} and p{name=...}"
+Starting in Perl 5.32, you can specify a character by its name in
+regular expression patterns using \f(CW\*(C`\ep{name=...}\*(C'\fR.  This is in addition
+to the longstanding method of using \f(CW\*(C`\eN{...}\*(C'\fR.  The following
+summarizes the differences between these two:
+.PP
+.Vb 6
+\&                       \eN{...}       \ep{Name=...}
+\& can interpolate    only with eval       yes            [1]
+\& custom names            yes             no             [2]
+\& name aliases            yes             yes            [3]
+\& named sequences         yes             yes            [4]
+\& name value parsing     exact       Unicode loose       [5]
+.Ve
+.IP [1] 4
+.IX Item "[1]"
+The ability to interpolate means you can do something like
+.Sp
+.Vb 1
+\& qr/\ep{na=latin capital letter $which}/
+.Ve
+.Sp
+and specify \f(CW$which\fR elsewhere.
+.IP [2] 4
+.IX Item "[2]"
+You can create your own names for characters, and override official
+ones when using \f(CW\*(C`\eN{...}\*(C'\fR.  See "CUSTOM ALIASES" in charnames.
+.IP [3] 4
+.IX Item "[3]"
+Some characters have multiple names (synonyms).
+.IP [4] 4
+.IX Item "[4]"
+Some particular sequences of characters are given a single name, in
+addition to their individual ones.
+.IP [5] 4
+.IX Item "[5]"
+Exact name value matching means you have to specify case, hyphens,
+underscores, and spaces precisely in the name you want.  Loose matching
+follows the Unicode rules
+<https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>,
+where these are mostly irrelevant.  Except for a few outlier character
+names, these are the same rules as are already used for any other
+\&\f(CW\*(C`\ep{...}\*(C'\fR property.
+.SS "Wildcards in Property Values"
+.IX Subsection "Wildcards in Property Values"
+Starting in Perl 5.30, it is possible to do something like this:
+.PP
+.Vb 1
+\& qr!\ep{numeric_value=/\eA[0\-5]\ez/}!
+.Ve
+.PP
+or, by abbreviating and adding \f(CW\*(C`/x\*(C'\fR,
+.PP
+.Vb 1
+\& qr! \ep{nv= /(?x) \eA [0\-5] \ez / }!
+.Ve
+.PP
+This matches all code points whose numeric value is one of 0, 1, 2, 3,
+4, or 5.  This particular example could instead have been written as
+.PP
+.Vb 1
+\& qr! \eA [ \ep{nv=0}\ep{nv=1}\ep{nv=2}\ep{nv=3}\ep{nv=4}\ep{nv=5} ] \ez !xx
+.Ve
+.PP
+in earlier perls, so in this case this feature just makes things easier
+and shorter to write.  If we hadn't included the \f(CW\*(C`\eA\*(C'\fR and \f(CW\*(C`\ez\*(C'\fR, these
+would have matched things like \f(CW\*(C`1/2\*(C'\fR because that contains a 1 (as
+well as a 2).  As written, it matches things like subscripts that have
+these numeric values.  If we only wanted the decimal digits with those
+numeric values, we could say,
+.PP
+.Vb 1
+\& qr! (?[ \ed & \ep{nv=/[0\-5]/ ]) }!x
+.Ve
+.PP
+The \f(CW\*(C`\ed\*(C'\fR gets rid of needing to anchor the pattern, since it forces the
+result to only match \f(CW\*(C`[0\-9]\*(C'\fR, and the \f(CW\*(C`[0\-5]\*(C'\fR further restricts it.
+.PP
+The text in the above examples enclosed between the \f(CW"/"\fR
+characters can be just about any regular expression.  It is independent
+of the main pattern, so doesn't share any capturing groups, \fIetc\fR.  The
+delimiters for it must be ASCII punctuation, but it may NOT be
+delimited by \f(CW"{"\fR, nor \f(CW"}"\fR nor contain a literal \f(CW"}"\fR, as that
+delimits the end of the enclosing \f(CW\*(C`\ep{}\*(C'\fR.  Like any pattern, certain
+other delimiters are terminated by their mirror images.  These are
+\&\f(CW"("\fR, \f(CW\*(C`"[\*(C'\fR", and \f(CW"<"\fR.  If the delimiter is any of \f(CW"\-"\fR,
+\&\f(CW"_"\fR, \f(CW"+"\fR, or \f(CW"\e"\fR, or is the same delimiter as is used for the
+enclosing pattern, it must be preceded by a backslash escape, both
+fore and aft.
+.PP
+Beware of using \f(CW"$"\fR to indicate to match the end of the string.  It
+can too easily be interpreted as being a punctuation variable, like
+\&\f(CW$/\fR.
+.PP
+No modifiers may follow the final delimiter.  Instead, use
+"(?adlupimnsx\-imnsx)" in perlre and/or
+"(?adluimnsx\-imnsx:pattern)" in perlre to specify modifiers.
+However, certain modifiers are illegal in your wildcard subpattern.
+The only character set modifier specifiable is \f(CW\*(C`/aa\*(C'\fR;
+any other character set, and \f(CW\*(C`\-m\*(C'\fR, and \f(CW\*(C`p\*(C'\fR, and \f(CW\*(C`s\*(C'\fR are all illegal.
+Specifying modifiers like \f(CW\*(C`qr/.../gc\*(C'\fR that aren't legal in the
+\&\f(CW\*(C`(?...)\*(C'\fR notation normally raise a warning, but with wildcard
+subpatterns, their use is an error.  The \f(CW\*(C`m\*(C'\fR modifier is ineffective;
+everything that matches will be a single line.
+.PP
+By default, your pattern is matched case-insensitively, as if \f(CW\*(C`/i\*(C'\fR had
+been specified.  You can change this by saying \f(CW\*(C`(?\-i)\*(C'\fR in your pattern.
+.PP
+There are also certain operations that are illegal.  You can't nest
+\&\f(CW\*(C`\ep{...}\*(C'\fR and \f(CW\*(C`\eP{...}\*(C'\fR calls within a wildcard subpattern, and \f(CW\*(C`\eG\*(C'\fR
+doesn't make sense, so is also prohibited.
+.PP
+And the \f(CW\*(C`*\*(C'\fR quantifier (or its equivalent \f(CW\*(C`(0,}\*(C'\fR) is illegal.
+.PP
+This feature is not available when the left-hand side is prefixed by
+\&\f(CW\*(C`Is_\*(C'\fR, nor for any form that is marked as "Discouraged" in
+"Discouraged" in perluniprops.
+.PP
+This experimental feature has been added to begin to implement
+<https://www.unicode.org/reports/tr18/#Wildcard_Properties>.  Using it
+will raise a (default-on) warning in the
+\&\f(CW\*(C`experimental::uniprop_wildcards\*(C'\fR category.  We reserve the right to
+change its operation as we gain experience.
+.PP
+Your subpattern can be just about anything, but for it to have some
+utility, it should match when called with either or both of
+a) the full name of the property value with underscores (and/or spaces
+in the Block property) and some things uppercase; or b) the property
+value in all lowercase with spaces and underscores squeezed out.  For
+example,
+.PP
+.Vb 2
+\& qr!\ep{Blk=/Old I.*/}!
+\& qr!\ep{Blk=/oldi.*/}!
+.Ve
+.PP
+would match the same things.
+.PP
+Another example that shows that within \f(CW\*(C`\ep{...}\*(C'\fR, \f(CW\*(C`/x\*(C'\fR isn't needed to
+have spaces:
+.PP
+.Vb 1
+\& qr!\ep{scx= /Hebrew|Greek/ }!
+.Ve
+.PP
+To be safe, we should have anchored the above example, to prevent
+matches for something like \f(CW\*(C`Hebrew_Braille\*(C'\fR, but there aren't
+any script names like that, so far.
+A warning is issued if none of the legal values for a property are
+matched by your pattern.  It's likely that a future release will raise a
+warning if your pattern ends up causing every possible code point to
+match.
+.PP
+Starting in 5.32, the Name, Name Aliases, and Named Sequences properties
+are allowed to be matched.  They are considered to be a single
+combination property, just as has long been the case for \f(CW\*(C`\eN{}\*(C'\fR.  Loose
+matching doesn't work in exactly the same way for these as it does for
+the values of other properties.  The rules are given in
+<https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>.  As a
+result, Perl doesn't try loose matching for you, like it does in other
+properties.  All letters in names are uppercase, but you can add \f(CW\*(C`(?i)\*(C'\fR
+to your subpattern to ignore case.  If you're uncertain where a blank
+is, you can use \f(CW\*(C` ?\*(C'\fR in your subpattern.  No character name contains an
+underscore, so don't bother trying to match one.  The use of hyphens is
+particularly problematic; refer to the above link.  But note that, as of
+Unicode 13.0, the only script in modern usage which has weirdnesses with
+these is Tibetan; also the two Korean characters U+116C HANGUL JUNGSEONG
+OE and U+1180 HANGUL JUNGSEONG O\-E.  Unicode makes no promises to not
+add hyphen-problematic names in the future.
+.PP
+Using wildcards on these is resource intensive, given the hundreds of
+thousands of legal names that must be checked against.
+.PP
+An example of using Name property wildcards is
+.PP
+.Vb 1
+\& qr!\ep{name=/(SMILING|GRINNING) FACE/}!
+.Ve
+.PP
+Another is
+.PP
+.Vb 1
+\& qr/(?[ \ep{name=\e/CJK\e/} \- \ep{ideographic} ])/
+.Ve
+.PP
+which is the 200\-ish (as of Unicode 13.0) CJK characters that aren't
+ideographs.
+.PP
+There are certain properties that wildcard subpatterns don't currently
+work with.  These are:
+.PP
+.Vb 9
+\& Bidi Mirroring Glyph
+\& Bidi Paired Bracket
+\& Case Folding
+\& Decomposition Mapping
+\& Equivalent Unified Ideograph
+\& Lowercase Mapping
+\& NFKC Case Fold
+\& Titlecase Mapping
+\& Uppercase Mapping
+.Ve
+.PP
+Nor is the \f(CW\*(C`@\fR\f(CIunicode_property\fR\f(CW@\*(C'\fR form implemented.
+.PP
+Here's a complete example of matching IPV4 internet protocol addresses
+in any (single) script
+.PP
+.Vb 1
+\& no warnings \*(Aqexperimental::uniprop_wildcards\*(Aq;
+\&
+\& # Can match a substring, so this intermediate regex needs to have
+\& # context or anchoring in its final use.  Using nt=de yields decimal
+\& # digits.  When specifying a subset of these, we must include \ed to
+\& # prevent things like U+00B2 SUPERSCRIPT TWO from matching
+\& my $zero_through_255 =
+\&  qr/ \eb (*sr:                                  # All from same sript
+\&            (?[ \ep{nv=0} & \ed ])*               # Optional leading zeros
+\&        (                                       # Then one of:
+\&                                  \ed{1,2}       #   0 \- 99
+\&            | (?[ \ep{nv=1} & \ed ])  \ed{2}       #   100 \- 199
+\&            | (?[ \ep{nv=2} & \ed ])
+\&               (  (?[ \ep{nv=:[0\-4]:} & \ed ]) \ed #   200 \- 249
+\&                | (?[ \ep{nv=5}     & \ed ])
+\&                  (?[ \ep{nv=:[0\-5]:} & \ed ])    #   250 \- 255
+\&               )
+\&        )
+\&      )
+\&    \eb
+\&  /x;
+\&
+\& my $ipv4 = qr/ \eA (*sr:         $zero_through_255
+\&                         (?: [.] $zero_through_255 ) {3}
+\&                   )
+\&                \ez
+\&            /x;
+.Ve
+.SS "User-Defined Character Properties"
+.IX Subsection "User-Defined Character Properties"
+You can define your own binary character properties by defining subroutines
+whose names begin with \f(CW"In"\fR or \f(CW"Is"\fR.  (The regex sets feature
+"(?[ ])" in perlre provides an alternative which allows more complex
+definitions.)  The subroutines can be defined in any
+package.  They override any Unicode properties expressed as the same
+names.  The user-defined properties can be used in the regular
+expression
+\&\f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR constructs; if you are using a user-defined property from a
+package other than the one you are in, you must specify its package in the
+\&\f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR construct.
+.PP
+.Vb 3
+\&    # assuming property IsForeign defined in Lang::
+\&    package main;  # property package name required
+\&    if ($txt =~ /\ep{Lang::IsForeign}+/) { ... }
+\&
+\&    package Lang;  # property package name not required
+\&    if ($txt =~ /\ep{IsForeign}+/) { ... }
+.Ve
+.PP
+The subroutines are passed a single parameter, which is 0 if
+case-sensitive matching is in effect and non-zero if caseless matching
+is in effect.  The subroutine may return different values depending on
+the value of the flag.  But the subroutine is never called more than
+once for each flag value (zero vs non-zero).  The return value is saved
+and used instead of calling the sub ever again.  If the sub is defined
+at the time the pattern is compiled, it will be called then; if not, it
+will be called the first time its value (for that flag) is needed during
+execution.
+.PP
+Note that if the regular expression is tainted, then Perl will die rather
+than calling the subroutine when the name of the subroutine is
+determined by the tainted data.
+.PP
+The subroutines must return a specially-formatted string, with one
+or more newline-separated lines.  Each line must be one of the following:
+.IP \(bu 4
+A single hexadecimal number denoting a code point to include.
+.IP \(bu 4
+Two hexadecimal numbers separated by horizontal whitespace (space or
+tabular characters) denoting a range of code points to include.  The
+second number must not be smaller than the first.
+.IP \(bu 4
+Something to include, prefixed by \f(CW"+"\fR: a built-in character
+property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
+name) user-defined character property,
+to represent all the characters in that property; two hexadecimal code
+points for a range; or a single hexadecimal code point.
+.IP \(bu 4
+Something to exclude, prefixed by \f(CW"\-"\fR: an existing character
+property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
+name) user-defined character property,
+to represent all the characters in that property; two hexadecimal code
+points for a range; or a single hexadecimal code point.
+.IP \(bu 4
+Something to negate, prefixed \f(CW"!"\fR: an existing character
+property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
+name) user-defined character property,
+to represent all the characters in that property; two hexadecimal code
+points for a range; or a single hexadecimal code point.
+.IP \(bu 4
+Something to intersect with, prefixed by \f(CW"&"\fR: an existing character
+property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
+name) user-defined character property,
+for all the characters except the characters in the property; two
+hexadecimal code points for a range; or a single hexadecimal code point.
+.PP
+For example, to define a property that covers both the Japanese
+syllabaries (hiragana and katakana), you can define
+.PP
+.Vb 6
+\&    sub InKana {
+\&        return <<END;
+\&    3040\et309F
+\&    30A0\et30FF
+\&    END
+\&    }
+.Ve
+.PP
+Imagine that the here-doc end marker is at the beginning of the line.
+Now you can use \f(CW\*(C`\ep{InKana}\*(C'\fR and \f(CW\*(C`\eP{InKana}\*(C'\fR.
+.PP
+You could also have used the existing block property names:
+.PP
+.Vb 6
+\&    sub InKana {
+\&        return <<\*(AqEND\*(Aq;
+\&    +utf8::InHiragana
+\&    +utf8::InKatakana
+\&    END
+\&    }
+.Ve
+.PP
+Suppose you wanted to match only the allocated characters,
+not the raw block ranges: in other words, you want to remove
+the unassigned characters:
+.PP
+.Vb 7
+\&    sub InKana {
+\&        return <<\*(AqEND\*(Aq;
+\&    +utf8::InHiragana
+\&    +utf8::InKatakana
+\&    \-utf8::IsCn
+\&    END
+\&    }
+.Ve
+.PP
+The negation is useful for defining (surprise!) negated classes.
+.PP
+.Vb 7
+\&    sub InNotKana {
+\&        return <<\*(AqEND\*(Aq;
+\&    !utf8::InHiragana
+\&    \-utf8::InKatakana
+\&    +utf8::IsCn
+\&    END
+\&    }
+.Ve
+.PP
+This will match all non-Unicode code points, since every one of them is
+not in Kana.  You can use intersection to exclude these, if desired, as
+this modified example shows:
+.PP
+.Vb 8
+\&    sub InNotKana {
+\&        return <<\*(AqEND\*(Aq;
+\&    !utf8::InHiragana
+\&    \-utf8::InKatakana
+\&    +utf8::IsCn
+\&    &utf8::Any
+\&    END
+\&    }
+.Ve
+.PP
+\&\f(CW&utf8::Any\fR must be the last line in the definition.
+.PP
+Intersection is used generally for getting the common characters matched
+by two (or more) classes.  It's important to remember not to use \f(CW"&"\fR for
+the first set; that would be intersecting with nothing, resulting in an
+empty set.  (Similarly using \f(CW"\-"\fR for the first set does nothing).
+.PP
+Unlike non-user-defined \f(CW\*(C`\ep{}\*(C'\fR property matches, no warning is ever
+generated if these properties are matched against a non-Unicode code
+point (see "Beyond Unicode code points" below).
+.SS "User-Defined Case Mappings (for serious hackers only)"
+.IX Subsection "User-Defined Case Mappings (for serious hackers only)"
+\&\fBThis feature has been removed as of Perl 5.16.\fR
+The CPAN module \f(CW\*(C`Unicode::Casing\*(C'\fR provides better functionality without
+the drawbacks that this feature had.  If you are using a Perl earlier
+than 5.16, this feature was most fully documented in the 5.14 version of
+this pod:
+<http://perldoc.perl.org/5.14.0/perlunicode.html#User\-Defined\-Case\-Mappings\-%28for\-serious\-hackers\-only%29>
+.SS "Character Encodings for Input and Output"
+.IX Subsection "Character Encodings for Input and Output"
+See Encode.
+.SS "Unicode Regular Expression Support Level"
+.IX Subsection "Unicode Regular Expression Support Level"
+The following list of Unicode supported features for regular expressions describes
+all features currently directly supported by core Perl.  The references
+to "Level \fIN\fR" and the section numbers refer to
+UTS#18 "Unicode Regular Expressions" <https://www.unicode.org/reports/tr18>,
+version 18, October 2016.
+.PP
+\fILevel 1 \- Basic Unicode Support\fR
+.IX Subsection "Level 1 - Basic Unicode Support"
+.PP
+.Vb 8
+\& RL1.1   Hex Notation                     \- Done          [1]
+\& RL1.2   Properties                       \- Done          [2]
+\& RL1.2a  Compatibility Properties         \- Done          [3]
+\& RL1.3   Subtraction and Intersection     \- Done          [4]
+\& RL1.4   Simple Word Boundaries           \- Done          [5]
+\& RL1.5   Simple Loose Matches             \- Done          [6]
+\& RL1.6   Line Boundaries                  \- Partial       [7]
+\& RL1.7   Supplementary Code Points        \- Done          [8]
+.Ve
+.ie n .IP "[1] ""\eN{U+...}"" and ""\ex{...}""" 4
+.el .IP "[1] \f(CW\eN{U+...}\fR and \f(CW\ex{...}\fR" 4
+.IX Item "[1] N{U+...} and x{...}"
+.PD 0
+.ie n .IP "[2] ""\ep{...}"" ""\eP{...}"".  This requirement is for a minimal list of properties.  Perl supports these.  See R2.7 for other properties." 4
+.el .IP "[2] \f(CW\ep{...}\fR \f(CW\eP{...}\fR.  This requirement is for a minimal list of properties.  Perl supports these.  See R2.7 for other properties." 4
+.IX Item "[2] p{...} P{...}. This requirement is for a minimal list of properties. Perl supports these. See R2.7 for other properties."
+.IP [3] 4
+.IX Item "[3]"
+.PD
+Perl has \f(CW\*(C`\ed\*(C'\fR \f(CW\*(C`\eD\*(C'\fR \f(CW\*(C`\es\*(C'\fR \f(CW\*(C`\eS\*(C'\fR \f(CW\*(C`\ew\*(C'\fR \f(CW\*(C`\eW\*(C'\fR \f(CW\*(C`\eX\*(C'\fR \f(CW\*(C`[:\fR\f(CIprop\fR\f(CW:]\*(C'\fR
+\&\f(CW\*(C`[:^\fR\f(CIprop\fR\f(CW:]\*(C'\fR, plus all the properties specified by
+<https://www.unicode.org/reports/tr18/#Compatibility_Properties>.  These
+are described above in "Other Properties"
+.IP [4] 4
+.IX Item "[4]"
+The regex sets feature \f(CW"(?[...])"\fR starting in v5.18 accomplishes
+this.  See "(?[ ])" in perlre.
+.ie n .IP "[5] ""\eb"" ""\eB"" meet most, but not all, the details of this requirement, but ""\eb{wb}"" and ""\eB{wb}"" do, as well as the stricter R2.3." 4
+.el .IP "[5] \f(CW\eb\fR \f(CW\eB\fR meet most, but not all, the details of this requirement, but \f(CW\eb{wb}\fR and \f(CW\eB{wb}\fR do, as well as the stricter R2.3." 4
+.IX Item "[5] b B meet most, but not all, the details of this requirement, but b{wb} and B{wb} do, as well as the stricter R2.3."
+.PD 0
+.IP [6] 4
+.IX Item "[6]"
+.PD
+Note that Perl does Full case-folding in matching, not Simple:
+.Sp
+For example \f(CW\*(C`U+1F88\*(C'\fR is equivalent to \f(CW\*(C`U+1F00 U+03B9\*(C'\fR, instead of just
+\&\f(CW\*(C`U+1F80\*(C'\fR.  This difference matters mainly for certain Greek capital
+letters with certain modifiers: the Full case-folding decomposes the
+letter, while the Simple case-folding would map it to a single
+character.
+.IP [7] 4
+.IX Item "[7]"
+The reason this is considered to be only partially implemented is that
+Perl has \f(CW\*(C`qr/\eb{lb}/\*(C'\fR and
+\&\f(CW\*(C`Unicode::LineBreak\*(C'\fR that are conformant with
+UAX#14 "Unicode Line Breaking Algorithm" <https://www.unicode.org/reports/tr14>.
+The regular expression construct provides default behavior, while the
+heavier-weight module provides customizable line breaking.
+.Sp
+But Perl treats \f(CW\*(C`\en\*(C'\fR as the start\- and end-line
+delimiter, whereas Unicode specifies more characters that should be
+so-interpreted.
+.Sp
+These are:
+.Sp
+.Vb 6
+\& VT   U+000B  (\ev in C)
+\& FF   U+000C  (\ef)
+\& CR   U+000D  (\er)
+\& NEL  U+0085
+\& LS   U+2028
+\& PS   U+2029
+.Ve
+.Sp
+\&\f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR in regular expression patterns are supposed to match all
+these, but don't.
+These characters also don't, but should, affect \f(CW\*(C`<>\*(C'\fR \f(CW$.\fR, and
+script line numbers.
+.Sp
+Also, lines should not be split within \f(CW\*(C`CRLF\*(C'\fR (i.e. there is no
+empty line between \f(CW\*(C`\er\*(C'\fR and \f(CW\*(C`\en\*(C'\fR).  For \f(CW\*(C`CRLF\*(C'\fR, try the \f(CW\*(C`:crlf\*(C'\fR
+layer (see PerlIO).
+.ie n .IP "[8] UTF\-8/UTF\-EBDDIC used in Perl allows not only ""U+10000"" to ""U+10FFFF"" but also beyond ""U+10FFFF""" 4
+.el .IP "[8] UTF\-8/UTF\-EBDDIC used in Perl allows not only \f(CWU+10000\fR to \f(CWU+10FFFF\fR but also beyond \f(CWU+10FFFF\fR" 4
+.IX Item "[8] UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to U+10FFFF but also beyond U+10FFFF"
+.PP
+\fILevel 2 \- Extended Unicode Support\fR
+.IX Subsection "Level 2 - Extended Unicode Support"
+.PP
+.Vb 10
+\& RL2.1   Canonical Equivalents           \- Retracted     [9]
+\&                                           by Unicode
+\& RL2.2   Extended Grapheme Clusters and  \- Partial       [10]
+\&         Character Classes with Strings
+\& RL2.3   Default Word Boundaries         \- Done          [11]
+\& RL2.4   Default Case Conversion         \- Done
+\& RL2.5   Name Properties                 \- Done
+\& RL2.6   Wildcards in Property Values    \- Partial       [12]
+\& RL2.7   Full Properties                 \- Partial       [13]
+\& RL2.8   Optional Properties             \- Partial       [14]
+.Ve
+.IP "[9] Unicode has rewritten this portion of UTS#18 to say that getting canonical equivalence (see UAX#15 ""Unicode Normalization Forms"" <https://www.unicode.org/reports/tr15>) is basically to be done at the programmer level.  Use NFD to write both your regular expressions and text to match them against (you can use Unicode::Normalize)." 4
+.IX Item "[9] Unicode has rewritten this portion of UTS#18 to say that getting canonical equivalence (see UAX#15 ""Unicode Normalization Forms"" <https://www.unicode.org/reports/tr15>) is basically to be done at the programmer level. Use NFD to write both your regular expressions and text to match them against (you can use Unicode::Normalize)."
+.PD 0
+.ie n .IP "[10] Perl has ""\eX"" and ""\eb{gcb}"".  Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support." 4
+.el .IP "[10] Perl has \f(CW\eX\fR and \f(CW\eb{gcb}\fR.  Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support." 4
+.IX Item "[10] Perl has X and b{gcb}. Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support."
+.IP "[11] see UAX#29 ""Unicode Text Segmentation"" <https://www.unicode.org/reports/tr29>," 4
+.IX Item "[11] see UAX#29 ""Unicode Text Segmentation"" <https://www.unicode.org/reports/tr29>,"
+.IP "[12] see ""Wildcards in Property Values"" above." 4
+.IX Item "[12] see ""Wildcards in Property Values"" above."
+.IP "[13] Perl supports all the properties in the Unicode Character Database (UCD).  It does not yet support the listed properties that come from other Unicode sources." 4
+.IX Item "[13] Perl supports all the properties in the Unicode Character Database (UCD). It does not yet support the listed properties that come from other Unicode sources."
+.IP "[14] The only optional property that Perl supports is Named Sequence.  None of these properties are in the UCD." 4
+.IX Item "[14] The only optional property that Perl supports is Named Sequence. None of these properties are in the UCD."
+.PD
+.PP
+\fILevel 3 \- Tailored Support\fR
+.IX Subsection "Level 3 - Tailored Support"
+.PP
+This has been retracted by Unicode.
+.SS "Unicode Encodings"
+.IX Subsection "Unicode Encodings"
+Unicode characters are assigned to \fIcode points\fR, which are abstract
+numbers.  To use these numbers, various encodings are needed.
+.IP \(bu 4
+UTF\-8
+.Sp
+UTF\-8 is a variable-length (1 to 4 bytes), byte-order independent
+encoding.  In most of Perl's documentation, including elsewhere in this
+document, the term "UTF\-8" means also "UTF-EBCDIC".  But in this section,
+"UTF\-8" refers only to the encoding used on ASCII platforms.  It is a
+superset of 7\-bit US-ASCII, so anything encoded in ASCII has the
+identical representation when encoded in UTF\-8.
+.Sp
+The following table is from Unicode 3.2.
+.Sp
+.Vb 1
+\& Code Points            1st Byte  2nd Byte  3rd Byte 4th Byte
+\&
+\&   U+0000..U+007F       00..7F
+\&   U+0080..U+07FF     * C2..DF    80..BF
+\&   U+0800..U+0FFF       E0      * A0..BF    80..BF
+\&   U+1000..U+CFFF       E1..EC    80..BF    80..BF
+\&   U+D000..U+D7FF       ED        80..9F    80..BF
+\&   U+D800..U+DFFF       +++++ utf16 surrogates, not legal utf8 +++++
+\&   U+E000..U+FFFF       EE..EF    80..BF    80..BF
+\&  U+10000..U+3FFFF      F0      * 90..BF    80..BF    80..BF
+\&  U+40000..U+FFFFF      F1..F3    80..BF    80..BF    80..BF
+\& U+100000..U+10FFFF     F4        80..8F    80..BF    80..BF
+.Ve
+.Sp
+Note the gaps marked by "*" before several of the byte entries above.  These are
+caused by legal UTF\-8 avoiding non-shortest encodings: it is technically
+possible to UTF\-8\-encode a single code point in different ways, but that is
+explicitly forbidden, and the shortest possible encoding should always be used
+(and that is what Perl does).
+.Sp
+Another way to look at it is via bits:
+.Sp
+.Vb 1
+\&                Code Points  1st Byte  2nd Byte  3rd Byte  4th Byte
+\&
+\&                   0aaaaaaa  0aaaaaaa
+\&           00000bbbbbaaaaaa  110bbbbb  10aaaaaa
+\&           ccccbbbbbbaaaaaa  1110cccc  10bbbbbb  10aaaaaa
+\& 00000dddccccccbbbbbbaaaaaa  11110ddd  10cccccc  10bbbbbb  10aaaaaa
+.Ve
+.Sp
+As you can see, the continuation bytes all begin with \f(CW"10"\fR, and the
+leading bits of the start byte tell how many bytes there are in the
+encoded character.
+.Sp
+The original UTF\-8 specification allowed up to 6 bytes, to allow
+encoding of numbers up to \f(CW\*(C`0x7FFF_FFFF\*(C'\fR.  Perl continues to allow those,
+and has extended that up to 13 bytes to encode code points up to what
+can fit in a 64\-bit word.  However, Perl will warn if you output any of
+these as being non-portable; and under strict UTF\-8 input protocols,
+they are forbidden.  In addition, it is now illegal to use a code point
+larger than what a signed integer variable on your system can hold.  On
+32\-bit ASCII systems, this means \f(CW\*(C`0x7FFF_FFFF\*(C'\fR is the legal maximum
+(much higher on 64\-bit systems).
+.IP \(bu 4
+UTF-EBCDIC
+.Sp
+Like UTF\-8, but EBCDIC-safe, in the way that UTF\-8 is ASCII-safe.
+This means that all the basic characters (which includes all
+those that have ASCII equivalents (like \f(CW"A"\fR, \f(CW"0"\fR, \f(CW"%"\fR, \fIetc.\fR)
+are the same in both EBCDIC and UTF-EBCDIC.)
+.Sp
+UTF-EBCDIC is used on EBCDIC platforms.  It generally requires more
+bytes to represent a given code point than UTF\-8 does; the largest
+Unicode code points take 5 bytes to represent (instead of 4 in UTF\-8),
+and, extended for 64\-bit words, it uses 14 bytes instead of 13 bytes in
+UTF\-8.
+.IP \(bu 4
+UTF\-16, UTF\-16BE, UTF\-16LE, Surrogates, and \f(CW\*(C`BOM\*(C'\fR's (Byte Order Marks)
+.Sp
+The followings items are mostly for reference and general Unicode
+knowledge, Perl doesn't use these constructs internally.
+.Sp
+Like UTF\-8, UTF\-16 is a variable-width encoding, but where
+UTF\-8 uses 8\-bit code units, UTF\-16 uses 16\-bit code units.
+All code points occupy either 2 or 4 bytes in UTF\-16: code points
+\&\f(CW\*(C`U+0000..U+FFFF\*(C'\fR are stored in a single 16\-bit unit, and code
+points \f(CW\*(C`U+10000..U+10FFFF\*(C'\fR in two 16\-bit units.  The latter case is
+using \fIsurrogates\fR, the first 16\-bit unit being the \fIhigh
+surrogate\fR, and the second being the \fIlow surrogate\fR.
+.Sp
+Surrogates are code points set aside to encode the \f(CW\*(C`U+10000..U+10FFFF\*(C'\fR
+range of Unicode code points in pairs of 16\-bit units.  The \fIhigh
+surrogates\fR are the range \f(CW\*(C`U+D800..U+DBFF\*(C'\fR and the \fIlow surrogates\fR
+are the range \f(CW\*(C`U+DC00..U+DFFF\*(C'\fR.  The surrogate encoding is
+.Sp
+.Vb 2
+\&    $hi = ($uni \- 0x10000) / 0x400 + 0xD800;
+\&    $lo = ($uni \- 0x10000) % 0x400 + 0xDC00;
+.Ve
+.Sp
+and the decoding is
+.Sp
+.Vb 1
+\&    $uni = 0x10000 + ($hi \- 0xD800) * 0x400 + ($lo \- 0xDC00);
+.Ve
+.Sp
+Because of the 16\-bitness, UTF\-16 is byte-order dependent.  UTF\-16
+itself can be used for in-memory computations, but if storage or
+transfer is required either UTF\-16BE (big-endian) or UTF\-16LE
+(little-endian) encodings must be chosen.
+.Sp
+This introduces another problem: what if you just know that your data
+is UTF\-16, but you don't know which endianness?  Byte Order Marks, or
+\&\f(CW\*(C`BOM\*(C'\fR's, are a solution to this.  A special character has been reserved
+in Unicode to function as a byte order marker: the character with the
+code point \f(CW\*(C`U+FEFF\*(C'\fR is the \f(CW\*(C`BOM\*(C'\fR.
+.Sp
+The trick is that if you read a \f(CW\*(C`BOM\*(C'\fR, you will know the byte order,
+since if it was written on a big-endian platform, you will read the
+bytes \f(CW\*(C`0xFE 0xFF\*(C'\fR, but if it was written on a little-endian platform,
+you will read the bytes \f(CW\*(C`0xFF 0xFE\*(C'\fR.  (And if the originating platform
+was writing in ASCII platform UTF\-8, you will read the bytes
+\&\f(CW\*(C`0xEF 0xBB 0xBF\*(C'\fR.)
+.Sp
+The way this trick works is that the character with the code point
+\&\f(CW\*(C`U+FFFE\*(C'\fR is not supposed to be in input streams, so the
+sequence of bytes \f(CW\*(C`0xFF 0xFE\*(C'\fR is unambiguously "\f(CW\*(C`BOM\*(C'\fR, represented in
+little-endian format" and cannot be \f(CW\*(C`U+FFFE\*(C'\fR, represented in big-endian
+format".
+.Sp
+Surrogates have no meaning in Unicode outside their use in pairs to
+represent other code points.  However, Perl allows them to be
+represented individually internally, for example by saying
+\&\f(CWchr(0xD801)\fR, so that all code points, not just those valid for open
+interchange, are
+representable.  Unicode does define semantics for them, such as their
+\&\f(CW"General_Category"\fR is \f(CW"Cs"\fR.  But because their use is somewhat dangerous,
+Perl will warn (using the warning category \f(CW"surrogate"\fR, which is a
+sub-category of \f(CW"utf8"\fR) if an attempt is made
+to do things like take the lower case of one, or match
+case-insensitively, or to output them.  (But don't try this on Perls
+before 5.14.)
+.IP \(bu 4
+UTF\-32, UTF\-32BE, UTF\-32LE
+.Sp
+The UTF\-32 family is pretty much like the UTF\-16 family, except that
+the units are 32\-bit, and therefore the surrogate scheme is not
+needed.  UTF\-32 is a fixed-width encoding.  The \f(CW\*(C`BOM\*(C'\fR signatures are
+\&\f(CW\*(C`0x00 0x00 0xFE 0xFF\*(C'\fR for BE and \f(CW\*(C`0xFF 0xFE 0x00 0x00\*(C'\fR for LE.
+.IP \(bu 4
+UCS\-2, UCS\-4
+.Sp
+Legacy, fixed-width encodings defined by the ISO 10646 standard.  UCS\-2 is a 16\-bit
+encoding.  Unlike UTF\-16, UCS\-2 is not extensible beyond \f(CW\*(C`U+FFFF\*(C'\fR,
+because it does not use surrogates.  UCS\-4 is a 32\-bit encoding,
+functionally identical to UTF\-32 (the difference being that
+UCS\-4 forbids neither surrogates nor code points larger than \f(CW\*(C`0x10_FFFF\*(C'\fR).
+.IP \(bu 4
+UTF\-7
+.Sp
+A seven-bit safe (non-eight-bit) encoding, which is useful if the
+transport or storage is not eight-bit safe.  Defined by RFC 2152.
+.SS "Noncharacter code points"
+.IX Subsection "Noncharacter code points"
+66 code points are set aside in Unicode as "noncharacter code points".
+These all have the \f(CW\*(C`Unassigned\*(C'\fR (\f(CW\*(C`Cn\*(C'\fR) \f(CW"General_Category"\fR, and
+no character will ever be assigned to any of them.  They are the 32 code
+points between \f(CW\*(C`U+FDD0\*(C'\fR and \f(CW\*(C`U+FDEF\*(C'\fR inclusive, and the 34 code
+points:
+.PP
+.Vb 7
+\& U+FFFE   U+FFFF
+\& U+1FFFE  U+1FFFF
+\& U+2FFFE  U+2FFFF
+\& ...
+\& U+EFFFE  U+EFFFF
+\& U+FFFFE  U+FFFFF
+\& U+10FFFE U+10FFFF
+.Ve
+.PP
+Until Unicode 7.0, the noncharacters were "\fBforbidden\fR for use in open
+interchange of Unicode text data", so that code that processed those
+streams could use these code points as sentinels that could be mixed in
+with character data, and would always be distinguishable from that data.
+(Emphasis above and in the next paragraph are added in this document.)
+.PP
+Unicode 7.0 changed the wording so that they are "\fBnot recommended\fR for
+use in open interchange of Unicode text data".  The 7.0 Standard goes on
+to say:
+.Sp
+.RS 4
+"If a noncharacter is received in open interchange, an application is
+not required to interpret it in any way.  It is good practice, however,
+to recognize it as a noncharacter and to take appropriate action, such
+as replacing it with \f(CW\*(C`U+FFFD\*(C'\fR replacement character, to indicate the
+problem in the text.  It is not recommended to simply delete
+noncharacter code points from such text, because of the potential
+security issues caused by deleting uninterpreted characters.  (See
+conformance clause C7 in Section 3.2, Conformance Requirements, and
+Unicode Technical Report #36, "Unicode Security
+Considerations" <https://www.unicode.org/reports/tr36/#Substituting_for_Ill_Formed_Subsequences>)."
+.RE
+.PP
+This change was made because it was found that various commercial tools
+like editors, or for things like source code control, had been written
+so that they would not handle program files that used these code points,
+effectively precluding their use almost entirely!  And that was never
+the intent.  They've always been meant to be usable within an
+application, or cooperating set of applications, at will.
+.PP
+If you're writing code, such as an editor, that is supposed to be able
+to handle any Unicode text data, then you shouldn't be using these code
+points yourself, and instead allow them in the input.  If you need
+sentinels, they should instead be something that isn't legal Unicode.
+For UTF\-8 data, you can use the bytes 0xC0 and 0xC1 as sentinels, as
+they never appear in well-formed UTF\-8.  (There are equivalents for
+UTF-EBCDIC).  You can also store your Unicode code points in integer
+variables and use negative values as sentinels.
+.PP
+If you're not writing such a tool, then whether you accept noncharacters
+as input is up to you (though the Standard recommends that you not).  If
+you do strict input stream checking with Perl, these code points
+continue to be forbidden.  This is to maintain backward compatibility
+(otherwise potential security holes could open up, as an unsuspecting
+application that was written assuming the noncharacters would be
+filtered out before getting to it, could now, without warning, start
+getting them).  To do strict checking, you can use the layer
+\&\f(CW:encoding(\*(AqUTF\-8\*(Aq)\fR.
+.PP
+Perl continues to warn (using the warning category \f(CW"nonchar"\fR, which
+is a sub-category of \f(CW"utf8"\fR) if an attempt is made to output
+noncharacters.
+.SS "Beyond Unicode code points"
+.IX Subsection "Beyond Unicode code points"
+The maximum Unicode code point is \f(CW\*(C`U+10FFFF\*(C'\fR, and Unicode only defines
+operations on code points up through that.  But Perl works on code
+points up to the maximum permissible signed number available on the
+platform.  However, Perl will not accept these from input streams unless
+lax rules are being used, and will warn (using the warning category
+\&\f(CW"non_unicode"\fR, which is a sub-category of \f(CW"utf8"\fR) if any are output.
+.PP
+Since Unicode rules are not defined on these code points, if a
+Unicode-defined operation is done on them, Perl uses what we believe are
+sensible rules, while generally warning, using the \f(CW"non_unicode"\fR
+category.  For example, \f(CWuc("\ex{11_0000}")\fR will generate such a
+warning, returning the input parameter as its result, since Perl defines
+the uppercase of every non-Unicode code point to be the code point
+itself.  (All the case changing operations, not just uppercasing, work
+this way.)
+.PP
+The situation with matching Unicode properties in regular expressions,
+the \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR constructs, against these code points is not as
+clear cut, and how these are handled has changed as we've gained
+experience.
+.PP
+One possibility is to treat any match against these code points as
+undefined.  But since Perl doesn't have the concept of a match being
+undefined, it converts this to failing or \f(CW\*(C`FALSE\*(C'\fR.  This is almost, but
+not quite, what Perl did from v5.14 (when use of these code points
+became generally reliable) through v5.18.  The difference is that Perl
+treated all \f(CW\*(C`\ep{}\*(C'\fR matches as failing, but all \f(CW\*(C`\eP{}\*(C'\fR matches as
+succeeding.
+.PP
+One problem with this is that it leads to unexpected, and confusing
+results in some cases:
+.PP
+.Vb 2
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=True}      # Failed on <= v5.18
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=False}     # Failed! on <= v5.18
+.Ve
+.PP
+That is, it treated both matches as undefined, and converted that to
+false (raising a warning on each).  The first case is the expected
+result, but the second is likely counterintuitive: "How could both be
+false when they are complements?"  Another problem was that the
+implementation optimized many Unicode property matches down to already
+existing simpler, faster operations, which don't raise the warning.  We
+chose to not forgo those optimizations, which help the vast majority of
+matches, just to generate a warning for the unlikely event that an
+above-Unicode code point is being matched against.
+.PP
+As a result of these problems, starting in v5.20, what Perl does is
+to treat non-Unicode code points as just typical unassigned Unicode
+characters, and matches accordingly.  (Note: Unicode has atypical
+unassigned code points.  For example, it has noncharacter code points,
+and ones that, when they do get assigned, are destined to be written
+Right-to-left, as Arabic and Hebrew are.  Perl assumes that no
+non-Unicode code point has any atypical properties.)
+.PP
+Perl, in most cases, will raise a warning when matching an above-Unicode
+code point against a Unicode property when the result is \f(CW\*(C`TRUE\*(C'\fR for
+\&\f(CW\*(C`\ep{}\*(C'\fR, and \f(CW\*(C`FALSE\*(C'\fR for \f(CW\*(C`\eP{}\*(C'\fR.  For example:
+.PP
+.Vb 2
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=True}      # Fails, no warning
+\& chr(0x110000) =~ \ep{ASCII_Hex_Digit=False}     # Succeeds, with warning
+.Ve
+.PP
+In both these examples, the character being matched is non-Unicode, so
+Unicode doesn't define how it should match.  It clearly isn't an ASCII
+hex digit, so the first example clearly should fail, and so it does,
+with no warning.  But it is arguable that the second example should have
+an undefined, hence \f(CW\*(C`FALSE\*(C'\fR, result.  So a warning is raised for it.
+.PP
+Thus the warning is raised for many fewer cases than in earlier Perls,
+and only when what the result is could be arguable.  It turns out that
+none of the optimizations made by Perl (or are ever likely to be made)
+cause the warning to be skipped, so it solves both problems of Perl's
+earlier approach.  The most commonly used property that is affected by
+this change is \f(CW\*(C`\ep{Unassigned}\*(C'\fR which is a short form for
+\&\f(CW\*(C`\ep{General_Category=Unassigned}\*(C'\fR.  Starting in v5.20, all non-Unicode
+code points are considered \f(CW\*(C`Unassigned\*(C'\fR.  In earlier releases the
+matches failed because the result was considered undefined.
+.PP
+The only place where the warning is not raised when it might ought to
+have been is if optimizations cause the whole pattern match to not even
+be attempted.  For example, Perl may figure out that for a string to
+match a certain regular expression pattern, the string has to contain
+the substring \f(CW"foobar"\fR.  Before attempting the match, Perl may look
+for that substring, and if not found, immediately fail the match without
+actually trying it; so no warning gets generated even if the string
+contains an above-Unicode code point.
+.PP
+This behavior is more "Do what I mean" than in earlier Perls for most
+applications.  But it catches fewer issues for code that needs to be
+strictly Unicode compliant.  Therefore there is an additional mode of
+operation available to accommodate such code.  This mode is enabled if a
+regular expression pattern is compiled within the lexical scope where
+the \f(CW"non_unicode"\fR warning class has been made fatal, say by:
+.PP
+.Vb 1
+\& use warnings FATAL => "non_unicode"
+.Ve
+.PP
+(see warnings).  In this mode of operation, Perl will raise the
+warning for all matches against a non-Unicode code point (not just the
+arguable ones), and it skips the optimizations that might cause the
+warning to not be output.  (It currently still won't warn if the match
+isn't even attempted, like in the \f(CW"foobar"\fR example above.)
+.PP
+In summary, Perl now normally treats non-Unicode code points as typical
+Unicode unassigned code points for regular expression matches, raising a
+warning only when it is arguable what the result should be.  However, if
+this warning has been made fatal, it isn't skipped.
+.PP
+There is one exception to all this.  \f(CW\*(C`\ep{All}\*(C'\fR looks like a Unicode
+property, but it is a Perl extension that is defined to be true for all
+possible code points, Unicode or not, so no warning is ever generated
+when matching this against a non-Unicode code point.  (Prior to v5.20,
+it was an exact synonym for \f(CW\*(C`\ep{Any}\*(C'\fR, matching code points \f(CW0\fR
+through \f(CW0x10FFFF\fR.)
+.SS "Security Implications of Unicode"
+.IX Subsection "Security Implications of Unicode"
+First, read
+Unicode Security Considerations <https://www.unicode.org/reports/tr36>.
+.PP
+Also, note the following:
+.IP \(bu 4
+Malformed UTF\-8
+.Sp
+UTF\-8 is very structured, so many combinations of bytes are invalid.  In
+the past, Perl tried to soldier on and make some sense of invalid
+combinations, but this can lead to security holes, so now, if the Perl
+core needs to process an invalid combination, it will either raise a
+fatal error, or will replace those bytes by the sequence that forms the
+Unicode REPLACEMENT CHARACTER, for which purpose Unicode created it.
+.Sp
+Every code point can be represented by more than one possible
+syntactically valid UTF\-8 sequence.  Early on, both Unicode and Perl
+considered any of these to be valid, but now, all sequences longer
+than the shortest possible one are considered to be malformed.
+.Sp
+Unicode considers many code points to be illegal, or to be avoided.
+Perl generally accepts them, once they have passed through any input
+filters that may try to exclude them.  These have been discussed above
+(see "Surrogates" under UTF\-16 in "Unicode Encodings",
+"Noncharacter code points", and "Beyond Unicode code points").
+.IP \(bu 4
+Regular expression pattern matching may surprise you if you're not
+accustomed to Unicode.  Starting in Perl 5.14, several pattern
+modifiers are available to control this, called the character set
+modifiers.  Details are given in "Character set modifiers" in perlre.
+.PP
+As discussed elsewhere, Perl has one foot (two hooves?) planted in
+each of two worlds: the old world of ASCII and single-byte locales, and
+the new world of Unicode, upgrading when necessary.
+If your legacy code does not explicitly use Unicode, no automatic
+switch-over to Unicode should happen.
+.SS "Unicode in Perl on EBCDIC"
+.IX Subsection "Unicode in Perl on EBCDIC"
+Unicode is supported on EBCDIC platforms.  See perlebcdic.
+.PP
+Unless ASCII vs. EBCDIC issues are specifically being discussed,
+references to UTF\-8 encoding in this document and elsewhere should be
+read as meaning UTF-EBCDIC on EBCDIC platforms.
+See "Unicode and UTF" in perlebcdic.
+.PP
+Because UTF-EBCDIC is so similar to UTF\-8, the differences are mostly
+hidden from you; \f(CW\*(C`use\ utf8\*(C'\fR (and NOT something like
+\&\f(CW\*(C`use\ utfebcdic\*(C'\fR) declares the script is in the platform's
+"native" 8\-bit encoding of Unicode.  (Similarly for the \f(CW":utf8"\fR
+layer.)
+.SS Locales
+.IX Subsection "Locales"
+See "Unicode and UTF\-8" in perllocale
+.SS "When Unicode Does Not Happen"
+.IX Subsection "When Unicode Does Not Happen"
+There are still many places where Unicode (in some encoding or
+another) could be given as arguments or received as results, or both in
+Perl, but it is not, in spite of Perl having extensive ways to input and
+output in Unicode, and a few other "entry points" like the \f(CW@ARGV\fR
+array (which can sometimes be interpreted as UTF\-8).
+.PP
+The following are such interfaces.  Also, see "The "Unicode Bug"".
+For all of these interfaces Perl
+currently (as of v5.16.0) simply assumes byte strings both as arguments
+and results, or UTF\-8 strings if the (deprecated) \f(CW\*(C`encoding\*(C'\fR pragma has been used.
+.PP
+One reason that Perl does not attempt to resolve the role of Unicode in
+these situations is that the answers are highly dependent on the operating
+system and the file system(s).  For example, whether filenames can be
+in Unicode and in exactly what kind of encoding, is not exactly a
+portable concept.  Similarly for \f(CW\*(C`qx\*(C'\fR and \f(CW\*(C`system\*(C'\fR: how well will the
+"command-line interface" (and which of them?) handle Unicode?
+.IP \(bu 4
+\&\f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR,
+\&\f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`\-X\*(C'\fR
+.IP \(bu 4
+\&\f(CW%ENV\fR
+.IP \(bu 4
+\&\f(CW\*(C`glob\*(C'\fR (aka the \f(CW\*(C`<*>\*(C'\fR)
+.IP \(bu 4
+\&\f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`qx\*(C'\fR (aka the backtick operator), \f(CW\*(C`system\*(C'\fR
+.IP \(bu 4
+\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR
+.SS "The ""Unicode Bug"""
+.IX Subsection "The ""Unicode Bug"""
+The term, "Unicode bug" has been applied to an inconsistency with the
+code points in the \f(CW\*(C`Latin\-1 Supplement\*(C'\fR block, that is, between
+128 and 255.  Without a locale specified, unlike all other characters or
+code points, these characters can have very different semantics
+depending on the rules in effect.  (Characters whose code points are
+above 255 force Unicode rules; whereas the rules for ASCII characters
+are the same under both ASCII and Unicode rules.)
+.PP
+Under Unicode rules, these upper\-Latin1 characters are interpreted as
+Unicode code points, which means they have the same semantics as Latin\-1
+(ISO\-8859\-1) and C1 controls.
+.PP
+As explained in "ASCII Rules versus Unicode Rules", under ASCII rules,
+they are considered to be unassigned characters.
+.PP
+This can lead to unexpected results.  For example, a string's
+semantics can suddenly change if a code point above 255 is appended to
+it, which changes the rules from ASCII to Unicode.  As an
+example, consider the following program and its output:
+.PP
+.Vb 11
+\& $ perl \-le\*(Aq
+\&     no feature "unicode_strings";
+\&     $s1 = "\exC2";
+\&     $s2 = "\ex{2660}";
+\&     for ($s1, $s2, $s1.$s2) {
+\&         print /\ew/ || 0;
+\&     }
+\& \*(Aq
+\& 0
+\& 0
+\& 1
+.Ve
+.PP
+If there's no \f(CW\*(C`\ew\*(C'\fR in \f(CW\*(C`s1\*(C'\fR nor in \f(CW\*(C`s2\*(C'\fR, why does their concatenation
+have one?
+.PP
+This anomaly stems from Perl's attempt to not disturb older programs that
+didn't use Unicode, along with Perl's desire to add Unicode support
+seamlessly.  But the result turned out to not be seamless.  (By the way,
+you can choose to be warned when things like this happen.  See
+\&\f(CW\*(C`encoding::warnings\*(C'\fR.)
+.PP
+\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
+was added, starting in Perl v5.12, to address this problem.  It affects
+these things:
+.IP \(bu 4
+Changing the case of a scalar, that is, using \f(CWuc()\fR, \f(CWucfirst()\fR, \f(CWlc()\fR,
+and \f(CWlcfirst()\fR, or \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR and \f(CW\*(C`\el\*(C'\fR in double-quotish
+contexts, such as regular expression substitutions.
+.Sp
+Under \f(CW\*(C`unicode_strings\*(C'\fR starting in Perl 5.12.0, Unicode rules are
+generally used.  See "lc" in perlfunc for details on how this works
+in combination with various other pragmas.
+.IP \(bu 4
+Using caseless (\f(CW\*(C`/i\*(C'\fR) regular expression matching.
+.Sp
+Starting in Perl 5.14.0, regular expressions compiled within
+the scope of \f(CW\*(C`unicode_strings\*(C'\fR use Unicode rules
+even when executed or compiled into larger
+regular expressions outside the scope.
+.IP \(bu 4
+Matching any of several properties in regular expressions.
+.Sp
+These properties are \f(CW\*(C`\eb\*(C'\fR (without braces), \f(CW\*(C`\eB\*(C'\fR (without braces),
+\&\f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\eS\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\eW\*(C'\fR, and all the Posix character classes
+\&\fIexcept\fR \f(CW\*(C`[[:ascii:]]\*(C'\fR.
+.Sp
+Starting in Perl 5.14.0, regular expressions compiled within
+the scope of \f(CW\*(C`unicode_strings\*(C'\fR use Unicode rules
+even when executed or compiled into larger
+regular expressions outside the scope.
+.IP \(bu 4
+In \f(CW\*(C`quotemeta\*(C'\fR or its inline equivalent \f(CW\*(C`\eQ\*(C'\fR.
+.Sp
+Starting in Perl 5.16.0, consistent quoting rules are used within the
+scope of \f(CW\*(C`unicode_strings\*(C'\fR, as described in "quotemeta" in perlfunc.
+Prior to that, or outside its scope, no code points above 127 are quoted
+in UTF\-8 encoded strings, but in byte encoded strings, code points
+between 128\-255 are always quoted.
+.IP \(bu 4
+In the \f(CW\*(C`..\*(C'\fR or range operator.
+.Sp
+Starting in Perl 5.26.0, the range operator on strings treats their lengths
+consistently within the scope of \f(CW\*(C`unicode_strings\*(C'\fR. Prior to that, or
+outside its scope, it could produce strings whose length in characters
+exceeded that of the right-hand side, where the right-hand side took up more
+bytes than the correct range endpoint.
+.IP \(bu 4
+In \f(CW\*(C`split\*(C'\fR's special-case whitespace splitting.
+.Sp
+Starting in Perl 5.28.0, the \f(CW\*(C`split\*(C'\fR function with a pattern specified as
+a string containing a single space handles whitespace characters consistently
+within the scope of \f(CW\*(C`unicode_strings\*(C'\fR. Prior to that, or outside its scope,
+characters that are whitespace according to Unicode rules but not according to
+ASCII rules were treated as field contents rather than field separators when
+they appear in byte-encoded strings.
+.PP
+You can see from the above that the effect of \f(CW\*(C`unicode_strings\*(C'\fR
+increased over several Perl releases.  (And Perl's support for Unicode
+continues to improve; it's best to use the latest available release in
+order to get the most complete and accurate results possible.)  Note that
+\&\f(CW\*(C`unicode_strings\*(C'\fR is automatically chosen if you \f(CW\*(C`use\ v5.12\*(C'\fR or
+higher.
+.PP
+For Perls earlier than those described above, or when a string is passed
+to a function outside the scope of \f(CW\*(C`unicode_strings\*(C'\fR, see the next section.
+.SS "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)"
+.IX Subsection "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)"
+Sometimes (see "When Unicode Does Not Happen" or "The "Unicode Bug"")
+there are situations where you simply need to force a byte
+string into UTF\-8, or vice versa.  The standard module Encode can be
+used for this, or the low-level calls
+\&\f(CWutf8::upgrade($bytestring)\fR and
+\&\f(CW\*(C`utf8::downgrade($utf8string[, FAIL_OK])\*(C'\fR.
+.PP
+Note that \f(CWutf8::downgrade()\fR can fail if the string contains characters
+that don't fit into a byte.
+.PP
+Calling either function on a string that already is in the desired state is a
+no-op.
+.PP
+"ASCII Rules versus Unicode Rules" gives all the ways that a string is
+made to use Unicode rules.
+.SS "Using Unicode in XS"
+.IX Subsection "Using Unicode in XS"
+See "Unicode Support" in perlguts for an introduction to Unicode at
+the XS level, and "Unicode Support" in perlapi for the API details.
+.SS "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)"
+.IX Subsection "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)"
+Perl by default comes with the latest supported Unicode version built-in, but
+the goal is to allow you to change to use any earlier one.  In Perls
+v5.20 and v5.22, however, the earliest usable version is Unicode 5.1.
+Perl v5.18 and v5.24 are able to handle all earlier versions.
+.PP
+Download the files in the desired version of Unicode from the Unicode web
+site <https://www.unicode.org>).  These should replace the existing files in
+\&\fIlib/unicore\fR in the Perl source tree.  Follow the instructions in
+\&\fIREADME.perl\fR in that directory to change some of their names, and then build
+perl (see INSTALL).
+.SS "Porting code from perl\-5.6.X"
+.IX Subsection "Porting code from perl-5.6.X"
+Perls starting in 5.8 have a different Unicode model from 5.6. In 5.6 the
+programmer was required to use the \f(CW\*(C`utf8\*(C'\fR pragma to declare that a
+given scope expected to deal with Unicode data and had to make sure that
+only Unicode data were reaching that scope. If you have code that is
+working with 5.6, you will need some of the following adjustments to
+your code. The examples are written such that the code will continue to
+work under 5.6, so you should be safe to try them out.
+.IP \(bu 3
+A filehandle that should read or write UTF\-8
+.Sp
+.Vb 3
+\&  if ($] > 5.008) {
+\&    binmode $fh, ":encoding(UTF\-8)";
+\&  }
+.Ve
+.IP \(bu 3
+A scalar that is going to be passed to some extension
+.Sp
+Be it \f(CW\*(C`Compress::Zlib\*(C'\fR, \f(CW\*(C`Apache::Request\*(C'\fR or any extension that has no
+mention of Unicode in the manpage, you need to make sure that the
+UTF8 flag is stripped off. Note that at the time of this writing
+(January 2012) the mentioned modules are not UTF\-8\-aware. Please
+check the documentation to verify if this is still true.
+.Sp
+.Vb 4
+\&  if ($] > 5.008) {
+\&    require Encode;
+\&    $val = Encode::encode("UTF\-8", $val); # make octets
+\&  }
+.Ve
+.IP \(bu 3
+A scalar we got back from an extension
+.Sp
+If you believe the scalar comes back as UTF\-8, you will most likely
+want the UTF8 flag restored:
+.Sp
+.Vb 4
+\&  if ($] > 5.008) {
+\&    require Encode;
+\&    $val = Encode::decode("UTF\-8", $val);
+\&  }
+.Ve
+.IP \(bu 3
+Same thing, if you are really sure it is UTF\-8
+.Sp
+.Vb 4
+\&  if ($] > 5.008) {
+\&    require Encode;
+\&    Encode::_utf8_on($val);
+\&  }
+.Ve
+.IP \(bu 3
+A wrapper for DBI \f(CW\*(C`fetchrow_array\*(C'\fR and \f(CW\*(C`fetchrow_hashref\*(C'\fR
+.Sp
+When the database contains only UTF\-8, a wrapper function or method is
+a convenient way to replace all your \f(CW\*(C`fetchrow_array\*(C'\fR and
+\&\f(CW\*(C`fetchrow_hashref\*(C'\fR calls. A wrapper function will also make it easier to
+adapt to future enhancements in your database driver. Note that at the
+time of this writing (January 2012), the DBI has no standardized way
+to deal with UTF\-8 data. Please check the DBI documentation to verify if
+that is still true.
+.Sp
+.Vb 10
+\&  sub fetchrow {
+\&    # $what is one of fetchrow_{array,hashref}
+\&    my($self, $sth, $what) = @_;
+\&    if ($] < 5.008) {
+\&      return $sth\->$what;
+\&    } else {
+\&      require Encode;
+\&      if (wantarray) {
+\&        my @arr = $sth\->$what;
+\&        for (@arr) {
+\&          defined && /[^\e000\-\e177]/ && Encode::_utf8_on($_);
+\&        }
+\&        return @arr;
+\&      } else {
+\&        my $ret = $sth\->$what;
+\&        if (ref $ret) {
+\&          for my $k (keys %$ret) {
+\&            defined
+\&            && /[^\e000\-\e177]/
+\&            && Encode::_utf8_on($_) for $ret\->{$k};
+\&          }
+\&          return $ret;
+\&        } else {
+\&          defined && /[^\e000\-\e177]/ && Encode::_utf8_on($_) for $ret;
+\&          return $ret;
+\&        }
+\&      }
+\&    }
+\&  }
+.Ve
+.IP \(bu 3
+A large scalar that you know can only contain ASCII
+.Sp
+Scalars that contain only ASCII and are marked as UTF\-8 are sometimes
+a drag to your program. If you recognize such a situation, just remove
+the UTF8 flag:
+.Sp
+.Vb 1
+\&  utf8::downgrade($val) if $] > 5.008;
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+See also "The "Unicode Bug"" above.
+.SS "Interaction with Extensions"
+.IX Subsection "Interaction with Extensions"
+When Perl exchanges data with an extension, the extension should be
+able to understand the UTF8 flag and act accordingly. If the
+extension doesn't recognize that flag, it's likely that the extension
+will return incorrectly-flagged data.
+.PP
+So if you're working with Unicode data, consult the documentation of
+every module you're using if there are any issues with Unicode data
+exchange. If the documentation does not talk about Unicode at all,
+suspect the worst and probably look at the source to learn how the
+module is implemented. Modules written completely in Perl shouldn't
+cause problems. Modules that directly or indirectly access code written
+in other programming languages are at risk.
+.PP
+For affected functions, the simple strategy to avoid data corruption is
+to always make the encoding of the exchanged data explicit. Choose an
+encoding that you know the extension can handle. Convert arguments passed
+to the extensions to that encoding and convert results back from that
+encoding. Write wrapper functions that do the conversions for you, so
+you can later change the functions when the extension catches up.
+.PP
+To provide an example, let's say the popular \f(CW\*(C`Foo::Bar::escape_html\*(C'\fR
+function doesn't deal with Unicode data yet. The wrapper function
+would convert the argument to raw UTF\-8 and convert the result back to
+Perl's internal representation like so:
+.PP
+.Vb 6
+\&    sub my_escape_html ($) {
+\&        my($what) = shift;
+\&        return unless defined $what;
+\&        Encode::decode("UTF\-8", Foo::Bar::escape_html(
+\&                                     Encode::encode("UTF\-8", $what)));
+\&    }
+.Ve
+.PP
+Sometimes, when the extension does not convert data but just stores
+and retrieves it, you will be able to use the otherwise
+dangerous \f(CWEncode::_utf8_on()\fR function. Let's say
+the popular \f(CW\*(C`Foo::Bar\*(C'\fR extension, written in C, provides a \f(CW\*(C`param\*(C'\fR
+method that lets you store and retrieve data according to these prototypes:
+.PP
+.Vb 2
+\&    $self\->param($name, $value);            # set a scalar
+\&    $value = $self\->param($name);           # retrieve a scalar
+.Ve
+.PP
+If it does not yet provide support for any encoding, one could write a
+derived class with such a \f(CW\*(C`param\*(C'\fR method:
+.PP
+.Vb 12
+\&    sub param {
+\&      my($self,$name,$value) = @_;
+\&      utf8::upgrade($name);     # make sure it is UTF\-8 encoded
+\&      if (defined $value) {
+\&        utf8::upgrade($value);  # make sure it is UTF\-8 encoded
+\&        return $self\->SUPER::param($name,$value);
+\&      } else {
+\&        my $ret = $self\->SUPER::param($name);
+\&        Encode::_utf8_on($ret); # we know, it is UTF\-8 encoded
+\&        return $ret;
+\&      }
+\&    }
+.Ve
+.PP
+Some extensions provide filters on data entry/exit points, such as
+\&\f(CW\*(C`DB_File::filter_store_key\*(C'\fR and family. Look out for such filters in
+the documentation of your extensions; they can make the transition to
+Unicode data much easier.
+.SS Speed
+.IX Subsection "Speed"
+Some functions are slower when working on UTF\-8 encoded strings than
+on byte encoded strings.  All functions that need to hop over
+characters such as \f(CWlength()\fR, \f(CWsubstr()\fR or \f(CWindex()\fR, or matching
+regular expressions can work \fBmuch\fR faster when the underlying data are
+byte-encoded.
+.PP
+In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
+a caching scheme was introduced which improved the situation.  In general,
+operations with UTF\-8 encoded strings are still slower. As an example,
+the Unicode properties (character classes) like \f(CW\*(C`\ep{Nd}\*(C'\fR are known to
+be quite a bit slower (5\-20 times) than their simpler counterparts
+like \f(CW\*(C`[0\-9]\*(C'\fR (then again, there are hundreds of Unicode characters matching
+\&\f(CW\*(C`Nd\*(C'\fR compared with the 10 ASCII characters matching \f(CW\*(C`[0\-9]\*(C'\fR).
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlunitut, perluniintro, perluniprops, Encode, open, utf8, bytes,
+perlretut, "${^UNICODE}" in perlvar,
+<https://www.unicode.org/reports/tr44>).
diff --git a/upstream/mageia-cauldron/man1/perlunicook.1 b/upstream/mageia-cauldron/man1/perlunicook.1
new file mode 100644
index 00000000..72b46938
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlunicook.1
@@ -0,0 +1,968 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNICOOK 1"
+.TH PERLUNICOOK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlunicook \- cookbookish examples of handling Unicode in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This manpage contains short recipes demonstrating how to handle common Unicode
+operations in Perl, plus one complete program at the end. Any undeclared
+variables in individual recipes are assumed to have a previous appropriate
+value in them.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.SS "â„ž 0: Standard preamble"
+.IX Subsection "â„ž 0: Standard preamble"
+Unless otherwise notes, all examples below require this standard preamble
+to work correctly, with the \f(CW\*(C`#!\*(C'\fR adjusted to work on your system:
+.PP
+.Vb 1
+\& #!/usr/bin/env perl
+\&
+\& use v5.36;     # or later to get "unicode_strings" feature,
+\&                #   plus strict, warnings
+\& use utf8;      # so literals and identifiers can be in UTF\-8
+\& use warnings  qw(FATAL utf8);    # fatalize encoding glitches
+\& use open      qw(:std :encoding(UTF\-8)); # undeclared streams in UTF\-8
+\& use charnames qw(:full :short);  # unneeded in v5.16
+.Ve
+.PP
+This \fIdoes\fR make even Unix programmers \f(CW\*(C`binmode\*(C'\fR your binary streams,
+or open them with \f(CW\*(C`:raw\*(C'\fR, but that's the only way to get at them
+portably anyway.
+.PP
+\&\fBWARNING\fR: \f(CW\*(C`use autodie\*(C'\fR (pre 2.26) and \f(CW\*(C`use open\*(C'\fR do not get along with each
+other.
+.SS "â„ž 1: Generic Unicode-savvy filter"
+.IX Subsection "â„ž 1: Generic Unicode-savvy filter"
+Always decompose on the way in, then recompose on the way out.
+.PP
+.Vb 1
+\& use Unicode::Normalize;
+\&
+\& while (<>) {
+\&     $_ = NFD($_);   # decompose + reorder canonically
+\&     ...
+\& } continue {
+\&     print NFC($_);  # recompose (where possible) + reorder canonically
+\& }
+.Ve
+.SS "â„ž 2: Fine-tuning Unicode warnings"
+.IX Subsection "â„ž 2: Fine-tuning Unicode warnings"
+As of v5.14, Perl distinguishes three subclasses of UTF‑8 warnings.
+.PP
+.Vb 4
+\& use v5.14;                  # subwarnings unavailable any earlier
+\& no warnings "nonchar";      # the 66 forbidden non\-characters
+\& no warnings "surrogate";    # UTF\-16/CESU\-8 nonsense
+\& no warnings "non_unicode";  # for codepoints over 0x10_FFFF
+.Ve
+.SS "â„ž 3: Declare source in utf8 for identifiers and literals"
+.IX Subsection "â„ž 3: Declare source in utf8 for identifiers and literals"
+Without the all-critical \f(CW\*(C`use utf8\*(C'\fR declaration, putting UTF‑8 in your
+literals and identifiers won’t work right.  If you used the standard
+preamble just given above, this already happened.  If you did, you can
+do things like this:
+.PP
+.Vb 1
+\& use utf8;
+\&
+\& my $measure   = "Ångström";
+\& my @μsoft     = qw( cp852 cp1251 cp1252 );
+\& my @ὑπέ�μεγας = qw( ὑπέ�  μεγας );
+\& my @鯉        = qw( koi8\-f koi8\-u koi8\-r );
+\& my $motto     = "👪 💗 �"; # FAMILY, GROWING HEART, DROMEDARY CAMEL
+.Ve
+.PP
+If you forget \f(CW\*(C`use utf8\*(C'\fR, high bytes will be misunderstood as
+separate characters, and nothing will work right.
+.SS "â„ž 4: Characters and their numbers"
+.IX Subsection "â„ž 4: Characters and their numbers"
+The \f(CW\*(C`ord\*(C'\fR and \f(CW\*(C`chr\*(C'\fR functions work transparently on all codepoints,
+not just on ASCII alone — nor in fact, not even just on Unicode alone.
+.PP
+.Vb 3
+\& # ASCII characters
+\& ord("A")
+\& chr(65)
+\&
+\& # characters from the Basic Multilingual Plane
+\& ord("Σ")
+\& chr(0x3A3)
+\&
+\& # beyond the BMP
+\& ord("�")               # MATHEMATICAL ITALIC SMALL N
+\& chr(0x1D45B)
+\&
+\& # beyond Unicode! (up to MAXINT)
+\& ord("\ex{20_0000}")
+\& chr(0x20_0000)
+.Ve
+.SS "â„ž 5: Unicode literals by character number"
+.IX Subsection "â„ž 5: Unicode literals by character number"
+In an interpolated literal, whether a double-quoted string or a
+regex, you may specify a character by its number using the
+\&\f(CW\*(C`\ex{\fR\f(CIHHHHHH\fR\f(CW}\*(C'\fR escape.
+.PP
+.Vb 2
+\& String: "\ex{3a3}"
+\& Regex:  /\ex{3a3}/
+\&
+\& String: "\ex{1d45b}"
+\& Regex:  /\ex{1d45b}/
+\&
+\& # even non\-BMP ranges in regex work fine
+\& /[\ex{1D434}\-\ex{1D467}]/
+.Ve
+.SS "â„ž 6: Get character name by number"
+.IX Subsection "â„ž 6: Get character name by number"
+.Vb 2
+\& use charnames ();
+\& my $name = charnames::viacode(0x03A3);
+.Ve
+.SS "â„ž 7: Get character number by name"
+.IX Subsection "â„ž 7: Get character number by name"
+.Vb 2
+\& use charnames ();
+\& my $number = charnames::vianame("GREEK CAPITAL LETTER SIGMA");
+.Ve
+.SS "â„ž 8: Unicode named characters"
+.IX Subsection "â„ž 8: Unicode named characters"
+Use the \f(CW\*(C`\eN{\fR\f(CIcharname\fR\f(CW}\*(C'\fR notation to get the character
+by that name for use in interpolated literals (double-quoted
+strings and regexes).  In v5.16, there is an implicit
+.PP
+.Vb 1
+\& use charnames qw(:full :short);
+.Ve
+.PP
+But prior to v5.16, you must be explicit about which set of charnames you
+want.  The \f(CW\*(C`:full\*(C'\fR names are the official Unicode character name, alias, or
+sequence, which all share a namespace.
+.PP
+.Vb 1
+\& use charnames qw(:full :short latin greek);
+\&
+\& "\eN{MATHEMATICAL ITALIC SMALL N}"      # :full
+\& "\eN{GREEK CAPITAL LETTER SIGMA}"       # :full
+.Ve
+.PP
+Anything else is a Perl-specific convenience abbreviation.  Specify one or
+more scripts by names if you want short names that are script-specific.
+.PP
+.Vb 3
+\& "\eN{Greek:Sigma}"                      # :short
+\& "\eN{ae}"                               #  latin
+\& "\eN{epsilon}"                          #  greek
+.Ve
+.PP
+The v5.16 release also supports a \f(CW\*(C`:loose\*(C'\fR import for loose matching of
+character names, which works just like loose matching of property names:
+that is, it disregards case, whitespace, and underscores:
+.PP
+.Vb 1
+\& "\eN{euro sign}"                        # :loose (from v5.16)
+.Ve
+.PP
+Starting in v5.32, you can also use
+.PP
+.Vb 1
+\& qr/\ep{name=euro sign}/
+.Ve
+.PP
+to get official Unicode named characters in regular expressions.  Loose
+matching is always done for these.
+.SS "â„ž 9: Unicode named sequences"
+.IX Subsection "â„ž 9: Unicode named sequences"
+These look just like character names but return multiple codepoints.
+Notice the \f(CW%vx\fR vector-print functionality in \f(CW\*(C`printf\*(C'\fR.
+.PP
+.Vb 4
+\& use charnames qw(:full);
+\& my $seq = "\eN{LATIN CAPITAL LETTER A WITH MACRON AND GRAVE}";
+\& printf "U+%v04X\en", $seq;
+\& U+0100.0300
+.Ve
+.SS "â„ž 10: Custom named characters"
+.IX Subsection "â„ž 10: Custom named characters"
+Use \f(CW\*(C`:alias\*(C'\fR to give your own lexically scoped nicknames to existing
+characters, or even to give unnamed private-use characters useful names.
+.PP
+.Vb 4
+\& use charnames ":full", ":alias" => {
+\&     ecute => "LATIN SMALL LETTER E WITH ACUTE",
+\&     "APPLE LOGO" => 0xF8FF, # private use character
+\& };
+\&
+\& "\eN{ecute}"
+\& "\eN{APPLE LOGO}"
+.Ve
+.SS "â„ž 11: Names of CJK codepoints"
+.IX Subsection "â„ž 11: Names of CJK codepoints"
+Sinograms like “�京� come back with character names of
+\&\f(CW\*(C`CJK UNIFIED IDEOGRAPH\-6771\*(C'\fR and \f(CW\*(C`CJK UNIFIED IDEOGRAPH\-4EAC\*(C'\fR,
+because their “names� vary.  The CPAN \f(CW\*(C`Unicode::Unihan\*(C'\fR module
+has a large database for decoding these (and a whole lot more), provided you
+know how to understand its output.
+.PP
+.Vb 8
+\& # cpan \-i Unicode::Unihan
+\& use Unicode::Unihan;
+\& my $str = "�京";
+\& my $unhan = Unicode::Unihan\->new;
+\& for my $lang (qw(Mandarin Cantonese Korean JapaneseOn JapaneseKun)) {
+\&     printf "CJK $str in %\-12s is ", $lang;
+\&     say $unhan\->$lang($str);
+\& }
+.Ve
+.PP
+prints:
+.PP
+.Vb 5
+\& CJK �京 in Mandarin     is DONG1JING1
+\& CJK �京 in Cantonese    is dung1ging1
+\& CJK �京 in Korean       is TONGKYENG
+\& CJK �京 in JapaneseOn   is TOUKYOU KEI KIN
+\& CJK �京 in JapaneseKun  is HIGASHI AZUMAMIYAKO
+.Ve
+.PP
+If you have a specific romanization scheme in mind,
+use the specific module:
+.PP
+.Vb 5
+\& # cpan \-i Lingua::JA::Romanize::Japanese
+\& use Lingua::JA::Romanize::Japanese;
+\& my $k2r = Lingua::JA::Romanize::Japanese\->new;
+\& my $str = "�京";
+\& say "Japanese for $str is ", $k2r\->chars($str);
+.Ve
+.PP
+prints
+.PP
+.Vb 1
+\& Japanese for �京 is toukyou
+.Ve
+.SS "â„ž 12: Explicit encode/decode"
+.IX Subsection "â„ž 12: Explicit encode/decode"
+On rare occasion, such as a database read, you may be
+given encoded text you need to decode.
+.PP
+.Vb 1
+\&  use Encode qw(encode decode);
+\&
+\&  my $chars = decode("shiftjis", $bytes, 1);
+\& # OR
+\&  my $bytes = encode("MIME\-Header\-ISO_2022_JP", $chars, 1);
+.Ve
+.PP
+For streams all in the same encoding, don't use encode/decode; instead
+set the file encoding when you open the file or immediately after with
+\&\f(CW\*(C`binmode\*(C'\fR as described later below.
+.SS "â„ž 13: Decode program arguments as utf8"
+.IX Subsection "â„ž 13: Decode program arguments as utf8"
+.Vb 6
+\&     $ perl \-CA ...
+\& or
+\&     $ export PERL_UNICODE=A
+\& or
+\&    use Encode qw(decode);
+\&    @ARGV = map { decode(\*(AqUTF\-8\*(Aq, $_, 1) } @ARGV;
+.Ve
+.SS "â„ž 14: Decode program arguments as locale encoding"
+.IX Subsection "â„ž 14: Decode program arguments as locale encoding"
+.Vb 3
+\&    # cpan \-i Encode::Locale
+\&    use Encode qw(locale);
+\&    use Encode::Locale;
+\&
+\&    # use "locale" as an arg to encode/decode
+\&    @ARGV = map { decode(locale => $_, 1) } @ARGV;
+.Ve
+.SS "â„ž 15: Declare STD{IN,OUT,ERR} to be utf8"
+.IX Subsection "â„ž 15: Declare STD{IN,OUT,ERR} to be utf8"
+Use a command-line option, an environment variable, or else
+call \f(CW\*(C`binmode\*(C'\fR explicitly:
+.PP
+.Vb 9
+\&     $ perl \-CS ...
+\& or
+\&     $ export PERL_UNICODE=S
+\& or
+\&     use open qw(:std :encoding(UTF\-8));
+\& or
+\&     binmode(STDIN,  ":encoding(UTF\-8)");
+\&     binmode(STDOUT, ":utf8");
+\&     binmode(STDERR, ":utf8");
+.Ve
+.SS "â„ž 16: Declare STD{IN,OUT,ERR} to be in locale encoding"
+.IX Subsection "â„ž 16: Declare STD{IN,OUT,ERR} to be in locale encoding"
+.Vb 3
+\&    # cpan \-i Encode::Locale
+\&    use Encode;
+\&    use Encode::Locale;
+\&
+\&    # or as a stream for binmode or open
+\&    binmode STDIN,  ":encoding(console_in)"  if \-t STDIN;
+\&    binmode STDOUT, ":encoding(console_out)" if \-t STDOUT;
+\&    binmode STDERR, ":encoding(console_out)" if \-t STDERR;
+.Ve
+.SS "â„ž 17: Make file I/O default to utf8"
+.IX Subsection "â„ž 17: Make file I/O default to utf8"
+Files opened without an encoding argument will be in UTF\-8:
+.PP
+.Vb 5
+\&     $ perl \-CD ...
+\& or
+\&     $ export PERL_UNICODE=D
+\& or
+\&     use open qw(:encoding(UTF\-8));
+.Ve
+.SS "â„ž 18: Make all I/O and args default to utf8"
+.IX Subsection "â„ž 18: Make all I/O and args default to utf8"
+.Vb 7
+\&     $ perl \-CSDA ...
+\& or
+\&     $ export PERL_UNICODE=SDA
+\& or
+\&     use open qw(:std :encoding(UTF\-8));
+\&     use Encode qw(decode);
+\&     @ARGV = map { decode(\*(AqUTF\-8\*(Aq, $_, 1) } @ARGV;
+.Ve
+.SS "â„ž 19: Open file with specific encoding"
+.IX Subsection "â„ž 19: Open file with specific encoding"
+Specify stream encoding.  This is the normal way
+to deal with encoded text, not by calling low-level
+functions.
+.PP
+.Vb 7
+\& # input file
+\&     open(my $in_file, "< :encoding(UTF\-16)", "wintext");
+\& OR
+\&     open(my $in_file, "<", "wintext");
+\&     binmode($in_file, ":encoding(UTF\-16)");
+\& THEN
+\&     my $line = <$in_file>;
+\&
+\& # output file
+\&     open($out_file, "> :encoding(cp1252)", "wintext");
+\& OR
+\&     open(my $out_file, ">", "wintext");
+\&     binmode($out_file, ":encoding(cp1252)");
+\& THEN
+\&     print $out_file "some text\en";
+.Ve
+.PP
+More layers than just the encoding can be specified here. For example,
+the incantation \f(CW":raw :encoding(UTF\-16LE) :crlf"\fR includes implicit
+CRLF handling.
+.SS "â„ž 20: Unicode casing"
+.IX Subsection "â„ž 20: Unicode casing"
+Unicode casing is very different from ASCII casing.
+.PP
+.Vb 2
+\& uc("henry â…·")  # "HENRY â…§"
+\& uc("tschüß")   # "TSCHÜSS"  notice ß => SS
+\&
+\& # both are true:
+\& "tschüß"  =~ /TSCHÜSS/i   # notice ß => SS
+\& "Σίσυφος" =~ /ΣΊΣΥΦΟΣ/i   # notice Σ,σ,ς sameness
+.Ve
+.SS "â„ž 21: Unicode case-insensitive comparisons"
+.IX Subsection "â„ž 21: Unicode case-insensitive comparisons"
+Also available in the CPAN Unicode::CaseFold module,
+the new \f(CW\*(C`fc\*(C'\fR “foldcase� function from v5.16 grants
+access to the same Unicode casefolding as the \f(CW\*(C`/i\*(C'\fR
+pattern modifier has always used:
+.PP
+.Vb 1
+\& use feature "fc"; # fc() function is from v5.16
+\&
+\& # sort case\-insensitively
+\& my @sorted = sort { fc($a) cmp fc($b) } @list;
+\&
+\& # both are true:
+\& fc("tschüß")  eq fc("TSCHÜSS")
+\& fc("Σίσυφος") eq fc("ΣΊΣΥΦΟΣ")
+.Ve
+.SS "â„ž 22: Match Unicode linebreak sequence in regex"
+.IX Subsection "â„ž 22: Match Unicode linebreak sequence in regex"
+A Unicode linebreak matches the two-character CRLF
+grapheme or any of seven vertical whitespace characters.
+Good for dealing with textfiles coming from different
+operating systems.
+.PP
+.Vb 1
+\& \eR
+\&
+\& s/\eR/\en/g;  # normalize all linebreaks to \en
+.Ve
+.SS "â„ž 23: Get character category"
+.IX Subsection "â„ž 23: Get character category"
+Find the general category of a numeric codepoint.
+.PP
+.Vb 2
+\& use Unicode::UCD qw(charinfo);
+\& my $cat = charinfo(0x3A3)\->{category};  # "Lu"
+.Ve
+.SS "â„ž 24: Disabling Unicode-awareness in builtin charclasses"
+.IX Subsection "â„ž 24: Disabling Unicode-awareness in builtin charclasses"
+Disable \f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\eb\*(C'\fR, \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\ed\*(C'\fR, and the POSIX
+classes from working correctly on Unicode either in this
+scope, or in just one regex.
+.PP
+.Vb 2
+\& use v5.14;
+\& use re "/a";
+\&
+\& # OR
+\&
+\& my($num) = $str =~ /(\ed+)/a;
+.Ve
+.PP
+Or use specific un-Unicode properties, like \f(CW\*(C`\ep{ahex}\*(C'\fR
+and \f(CW\*(C`\ep{POSIX_Digit\*(C'\fR}.  Properties still work normally
+no matter what charset modifiers (\f(CW\*(C`/d /u /l /a /aa\*(C'\fR)
+should be effect.
+.SS "â„ž 25: Match Unicode properties in regex with \ep, \eP"
+.IX Subsection "â„ž 25: Match Unicode properties in regex with p, P"
+These all match a single codepoint with the given
+property.  Use \f(CW\*(C`\eP\*(C'\fR in place of \f(CW\*(C`\ep\*(C'\fR to match
+one codepoint lacking that property.
+.PP
+.Vb 8
+\& \epL, \epN, \epS, \epP, \epM, \epZ, \epC
+\& \ep{Sk}, \ep{Ps}, \ep{Lt}
+\& \ep{alpha}, \ep{upper}, \ep{lower}
+\& \ep{Latin}, \ep{Greek}
+\& \ep{script_extensions=Latin}, \ep{scx=Greek}
+\& \ep{East_Asian_Width=Wide}, \ep{EA=W}
+\& \ep{Line_Break=Hyphen}, \ep{LB=HY}
+\& \ep{Numeric_Value=4}, \ep{NV=4}
+.Ve
+.SS "â„ž 26: Custom character properties"
+.IX Subsection "â„ž 26: Custom character properties"
+Define at compile-time your own custom character
+properties for use in regexes.
+.PP
+.Vb 2
+\& # using private\-use characters
+\& sub In_Tengwar { "E000\etE07F\en" }
+\&
+\& if (/\ep{In_Tengwar}/) { ... }
+\&
+\& # blending existing properties
+\& sub Is_GraecoRoman_Title {<<\*(AqEND_OF_SET\*(Aq}
+\& +utf8::IsLatin
+\& +utf8::IsGreek
+\& &utf8::IsTitle
+\& END_OF_SET
+\&
+\& if (/\ep{Is_GraecoRoman_Title}/ { ... }
+.Ve
+.SS "â„ž 27: Unicode normalization"
+.IX Subsection "â„ž 27: Unicode normalization"
+Typically render into NFD on input and NFC on output. Using NFKC or NFKD
+functions improves recall on searches, assuming you've already done to the
+same text to be searched. Note that this is about much more than just pre\-
+combined compatibility glyphs; it also reorders marks according to their
+canonical combining classes and weeds out singletons.
+.PP
+.Vb 5
+\& use Unicode::Normalize;
+\& my $nfd  = NFD($orig);
+\& my $nfc  = NFC($orig);
+\& my $nfkd = NFKD($orig);
+\& my $nfkc = NFKC($orig);
+.Ve
+.SS "â„ž 28: Convert non-ASCII Unicode numerics"
+.IX Subsection "â„ž 28: Convert non-ASCII Unicode numerics"
+Unless you’ve used \f(CW\*(C`/a\*(C'\fR or \f(CW\*(C`/aa\*(C'\fR, \f(CW\*(C`\ed\*(C'\fR matches more than
+ASCII digits only, but Perl’s implicit string-to-number
+conversion does not current recognize these.  Here’s how to
+convert such strings manually.
+.PP
+.Vb 8
+\& use v5.14;  # needed for num() function
+\& use Unicode::UCD qw(num);
+\& my $str = "got Ⅻ and ४५६७ and ⅞ and here";
+\& my @nums = ();
+\& while ($str =~ /(\ed+|\eN)/g) {  # not just ASCII!
+\&    push @nums, num($1);
+\& }
+\& say "@nums";   #     12      4567      0.875
+\&
+\& use charnames qw(:full);
+\& my $nv = num("\eN{RUMI DIGIT ONE}\eN{RUMI DIGIT TWO}");
+.Ve
+.SS "â„ž 29: Match Unicode grapheme cluster in regex"
+.IX Subsection "â„ž 29: Match Unicode grapheme cluster in regex"
+Programmer-visible “characters� are codepoints matched by \f(CW\*(C`/./s\*(C'\fR,
+but user-visible “characters� are graphemes matched by \f(CW\*(C`/\eX/\*(C'\fR.
+.PP
+.Vb 3
+\& # Find vowel *plus* any combining diacritics,underlining,etc.
+\& my $nfd = NFD($orig);
+\& $nfd =~ / (?=[aeiou]) \eX /xi
+.Ve
+.SS "â„ž 30: Extract by grapheme instead of by codepoint (regex)"
+.IX Subsection "â„ž 30: Extract by grapheme instead of by codepoint (regex)"
+.Vb 2
+\& # match and grab five first graphemes
+\& my($first_five) = $str =~ /^ ( \eX{5} ) /x;
+.Ve
+.SS "â„ž 31: Extract by grapheme instead of by codepoint (substr)"
+.IX Subsection "â„ž 31: Extract by grapheme instead of by codepoint (substr)"
+.Vb 4
+\& # cpan \-i Unicode::GCString
+\& use Unicode::GCString;
+\& my $gcs = Unicode::GCString\->new($str);
+\& my $first_five = $gcs\->substr(0, 5);
+.Ve
+.SS "â„ž 32: Reverse string by grapheme"
+.IX Subsection "â„ž 32: Reverse string by grapheme"
+Reversing by codepoint messes up diacritics, mistakenly converting
+\&\f(CW\*(C`crème brûlée\*(C'\fR into \f(CW\*(C`éel̂urb em̀erc\*(C'\fR instead of into \f(CW\*(C`eélûrb emèrc\*(C'\fR;
+so reverse by grapheme instead.  Both these approaches work
+right no matter what normalization the string is in:
+.PP
+.Vb 1
+\& $str = join("", reverse $str =~ /\eX/g);
+\&
+\& # OR: cpan \-i Unicode::GCString
+\& use Unicode::GCString;
+\& $str = reverse Unicode::GCString\->new($str);
+.Ve
+.SS "â„ž 33: String length in graphemes"
+.IX Subsection "â„ž 33: String length in graphemes"
+The string \f(CW\*(C`brûlée\*(C'\fR has six graphemes but up to eight codepoints.
+This counts by grapheme, not by codepoint:
+.PP
+.Vb 3
+\& my $str = "brûlée";
+\& my $count = 0;
+\& while ($str =~ /\eX/g) { $count++ }
+\&
+\&  # OR: cpan \-i Unicode::GCString
+\& use Unicode::GCString;
+\& my $gcs = Unicode::GCString\->new($str);
+\& my $count = $gcs\->length;
+.Ve
+.SS "â„ž 34: Unicode column-width for printing"
+.IX Subsection "â„ž 34: Unicode column-width for printing"
+Perl’s \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`sprintf\*(C'\fR, and \f(CW\*(C`format\*(C'\fR think all
+codepoints take up 1 print column, but many take 0 or 2.
+Here to show that normalization makes no difference,
+we print out both forms:
+.PP
+.Vb 2
+\& use Unicode::GCString;
+\& use Unicode::Normalize;
+\&
+\& my @words = qw/crème brûlée/;
+\& @words = map { NFC($_), NFD($_) } @words;
+\&
+\& for my $str (@words) {
+\&     my $gcs = Unicode::GCString\->new($str);
+\&     my $cols = $gcs\->columns;
+\&     my $pad = " " x (10 \- $cols);
+\&     say str, $pad, " |";
+\& }
+.Ve
+.PP
+generates this to show that it pads correctly no matter
+the normalization:
+.PP
+.Vb 4
+\& crème      |
+\& crème      |
+\& brûlée     |
+\& brûle�e     |
+.Ve
+.SS "â„ž 35: Unicode collation"
+.IX Subsection "â„ž 35: Unicode collation"
+Text sorted by numeric codepoint follows no reasonable alphabetic order;
+use the UCA for sorting text.
+.PP
+.Vb 3
+\& use Unicode::Collate;
+\& my $col = Unicode::Collate\->new();
+\& my @list = $col\->sort(@old_list);
+.Ve
+.PP
+See the \fIucsort\fR program from the Unicode::Tussle CPAN module
+for a convenient command-line interface to this module.
+.SS "â„ž 36: Case\- \fIand\fP accent-insensitive Unicode sort"
+.IX Subsection "â„ž 36: Case- and accent-insensitive Unicode sort"
+Specify a collation strength of level 1 to ignore case and
+diacritics, only looking at the basic character.
+.PP
+.Vb 3
+\& use Unicode::Collate;
+\& my $col = Unicode::Collate\->new(level => 1);
+\& my @list = $col\->sort(@old_list);
+.Ve
+.SS "â„ž 37: Unicode locale collation"
+.IX Subsection "â„ž 37: Unicode locale collation"
+Some locales have special sorting rules.
+.PP
+.Vb 4
+\& # either use v5.12, OR: cpan \-i Unicode::Collate::Locale
+\& use Unicode::Collate::Locale;
+\& my $col = Unicode::Collate::Locale\->new(locale => "de_\|_phonebook");
+\& my @list = $col\->sort(@old_list);
+.Ve
+.PP
+The \fIucsort\fR program mentioned above accepts a \f(CW\*(C`\-\-locale\*(C'\fR parameter.
+.ie n .SS "â„ž 38: Making ""cmp"" work on text instead of codepoints"
+.el .SS "â„ž 38: Making \f(CWcmp\fP work on text instead of codepoints"
+.IX Subsection "â„ž 38: Making cmp work on text instead of codepoints"
+Instead of this:
+.PP
+.Vb 5
+\& @srecs = sort {
+\&     $b\->{AGE}   <=>  $a\->{AGE}
+\&                 ||
+\&     $a\->{NAME}  cmp  $b\->{NAME}
+\& } @recs;
+.Ve
+.PP
+Use this:
+.PP
+.Vb 9
+\& my $coll = Unicode::Collate\->new();
+\& for my $rec (@recs) {
+\&     $rec\->{NAME_key} = $coll\->getSortKey( $rec\->{NAME} );
+\& }
+\& @srecs = sort {
+\&     $b\->{AGE}       <=>  $a\->{AGE}
+\&                     ||
+\&     $a\->{NAME_key}  cmp  $b\->{NAME_key}
+\& } @recs;
+.Ve
+.SS "â„ž 39: Case\- \fIand\fP accent-insensitive comparisons"
+.IX Subsection "â„ž 39: Case- and accent-insensitive comparisons"
+Use a collator object to compare Unicode text by character
+instead of by codepoint.
+.PP
+.Vb 5
+\& use Unicode::Collate;
+\& my $es = Unicode::Collate\->new(
+\&     level => 1,
+\&     normalization => undef
+\& );
+\&
+\&  # now both are true:
+\& $es\->eq("García",  "GARCIA" );
+\& $es\->eq("Márquez", "MARQUEZ");
+.Ve
+.SS "â„ž 40: Case\- \fIand\fP accent-insensitive locale comparisons"
+.IX Subsection "â„ž 40: Case- and accent-insensitive locale comparisons"
+Same, but in a specific locale.
+.PP
+.Vb 3
+\& my $de = Unicode::Collate::Locale\->new(
+\&            locale => "de_\|_phonebook",
+\&          );
+\&
+\& # now this is true:
+\& $de\->eq("tschüß", "TSCHUESS");  # notice ü => UE, ß => SS
+.Ve
+.SS "â„ž 41: Unicode linebreaking"
+.IX Subsection "â„ž 41: Unicode linebreaking"
+Break up text into lines according to Unicode rules.
+.PP
+.Vb 3
+\& # cpan \-i Unicode::LineBreak
+\& use Unicode::LineBreak;
+\& use charnames qw(:full);
+\&
+\& my $para = "This is a super\eN{HYPHEN}long string. " x 20;
+\& my $fmt = Unicode::LineBreak\->new;
+\& print $fmt\->break($para), "\en";
+.Ve
+.SS "â„ž 42: Unicode text in DBM hashes, the tedious way"
+.IX Subsection "â„ž 42: Unicode text in DBM hashes, the tedious way"
+Using a regular Perl string as a key or value for a DBM
+hash will trigger a wide character exception if any codepoints
+won’t fit into a byte.  Here’s how to manually manage the translation:
+.PP
+.Vb 3
+\&    use DB_File;
+\&    use Encode qw(encode decode);
+\&    tie %dbhash, "DB_File", "pathname";
+\&
+\& # STORE
+\&
+\&    # assume $uni_key and $uni_value are abstract Unicode strings
+\&    my $enc_key   = encode("UTF\-8", $uni_key, 1);
+\&    my $enc_value = encode("UTF\-8", $uni_value, 1);
+\&    $dbhash{$enc_key} = $enc_value;
+\&
+\& # FETCH
+\&
+\&    # assume $uni_key holds a normal Perl string (abstract Unicode)
+\&    my $enc_key   = encode("UTF\-8", $uni_key, 1);
+\&    my $enc_value = $dbhash{$enc_key};
+\&    my $uni_value = decode("UTF\-8", $enc_value, 1);
+.Ve
+.SS "â„ž 43: Unicode text in DBM hashes, the easy way"
+.IX Subsection "â„ž 43: Unicode text in DBM hashes, the easy way"
+Here’s how to implicitly manage the translation; all encoding
+and decoding is done automatically, just as with streams that
+have a particular encoding attached to them:
+.PP
+.Vb 2
+\&    use DB_File;
+\&    use DBM_Filter;
+\&
+\&    my $dbobj = tie %dbhash, "DB_File", "pathname";
+\&    $dbobj\->Filter_Value("utf8");  # this is the magic bit
+\&
+\& # STORE
+\&
+\&    # assume $uni_key and $uni_value are abstract Unicode strings
+\&    $dbhash{$uni_key} = $uni_value;
+\&
+\&  # FETCH
+\&
+\&    # $uni_key holds a normal Perl string (abstract Unicode)
+\&    my $uni_value = $dbhash{$uni_key};
+.Ve
+.SS "â„ž 44: PROGRAM: Demo of Unicode collation and printing"
+.IX Subsection "â„ž 44: PROGRAM: Demo of Unicode collation and printing"
+Here’s a full program showing how to make use of locale-sensitive
+sorting, Unicode casing, and managing print widths when some of the
+characters take up zero or two columns, not just one column each time.
+When run, the following program produces this nicely aligned output:
+.PP
+.Vb 10
+\&    Crème Brûlée....... €2.00
+\&    Éclair............. €1.60
+\&    Fideuà............. €4.20
+\&    Hamburger.......... €6.00
+\&    Jamón Serrano...... €4.45
+\&    Linguiça........... €7.00
+\&    Pâté............... €4.15
+\&    Pears.............. €2.00
+\&    Pêches............. €2.25
+\&    Smørbrød........... €5.75
+\&    Spätzle............ €5.50
+\&    Xoriço............. €3.00
+\&    Γ��ος.............. €6.50
+\&    막걸리............. €4.00
+\&    �も�............. €2.65
+\&    �好�焼�......... €8.00
+\&    シュークリーム..... €1.85
+\&    寿�............... €9.99
+\&    包�............... €7.50
+.Ve
+.PP
+Here's that program.
+.PP
+.Vb 10
+\& #!/usr/bin/env perl
+\& # umenu \- demo sorting and printing of Unicode food
+\& #
+\& # (obligatory and increasingly long preamble)
+\& #
+\& use v5.36;
+\& use utf8;
+\& use warnings  qw(FATAL utf8);    # fatalize encoding faults
+\& use open      qw(:std :encoding(UTF\-8)); # undeclared streams in UTF\-8
+\& use charnames qw(:full :short);  # unneeded in v5.16
+\&
+\& # std modules
+\& use Unicode::Normalize;          # std perl distro as of v5.8
+\& use List::Util qw(max);          # std perl distro as of v5.10
+\& use Unicode::Collate::Locale;    # std perl distro as of v5.14
+\&
+\& # cpan modules
+\& use Unicode::GCString;           # from CPAN
+\&
+\& my %price = (
+\&     "γ��ος"             => 6.50, # gyros
+\&     "pears"             => 2.00, # like um, pears
+\&     "linguiça"          => 7.00, # spicy sausage, Portuguese
+\&     "xoriço"            => 3.00, # chorizo sausage, Catalan
+\&     "hamburger"         => 6.00, # burgermeister meisterburger
+\&     "éclair"            => 1.60, # dessert, French
+\&     "smørbrød"          => 5.75, # sandwiches, Norwegian
+\&     "spätzle"           => 5.50, # Bayerisch noodles, little sparrows
+\&     "包�"              => 7.50, # bao1 zi5, steamed pork buns, Mandarin
+\&     "jamón serrano"     => 4.45, # country ham, Spanish
+\&     "pêches"            => 2.25, # peaches, French
+\&     "シュークリーム"    => 1.85, # cream\-filled pastry like eclair
+\&     "막걸리"            => 4.00, # makgeolli, Korean rice wine
+\&     "寿�"              => 9.99, # sushi, Japanese
+\&     "�も�"            => 2.65, # omochi, rice cakes, Japanese
+\&     "crème brûlée"      => 2.00, # crema catalana
+\&     "fideuà"            => 4.20, # more noodles, Valencian
+\&                                  # (Catalan=fideuada)
+\&     "pâté"              => 4.15, # gooseliver paste, French
+\&     "�好�焼�"        => 8.00, # okonomiyaki, Japanese
+\& );
+\&
+\& my $width = 5 + max map { colwidth($_) } keys %price;
+\&
+\& # So the Asian stuff comes out in an order that someone
+\& # who reads those scripts won\*(Aqt freak out over; the
+\& # CJK stuff will be in JIS X 0208 order that way.
+\& my $coll  = Unicode::Collate::Locale\->new(locale => "ja");
+\&
+\& for my $item ($coll\->sort(keys %price)) {
+\&     print pad(entitle($item), $width, ".");
+\&     printf " €%.2f\en", $price{$item};
+\& }
+\&
+\& sub pad ($str, $width, $padchar) {
+\&     return $str . ($padchar x ($width \- colwidth($str)));
+\& }
+\&
+\& sub colwidth ($str) {
+\&     return Unicode::GCString\->new($str)\->columns;
+\& }
+\&
+\& sub entitle ($str) {
+\&     $str =~ s{ (?=\epL)(\eS)     (\eS*) }
+\&              { ucfirst($1) . lc($2)  }xge;
+\&     return $str;
+\& }
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See these manpages, some of which are CPAN modules:
+perlunicode, perluniprops,
+perlre, perlrecharclass,
+perluniintro, perlunitut, perlunifaq,
+PerlIO, DB_File, DBM_Filter, DBM_Filter::utf8,
+Encode, Encode::Locale,
+Unicode::UCD,
+Unicode::Normalize,
+Unicode::GCString, Unicode::LineBreak,
+Unicode::Collate, Unicode::Collate::Locale,
+Unicode::Unihan,
+Unicode::CaseFold,
+Unicode::Tussle,
+Lingua::JA::Romanize::Japanese,
+Lingua::ZH::Romanize::Pinyin,
+Lingua::KO::Romanize::Hangul.
+.PP
+The Unicode::Tussle CPAN module includes many programs
+to help with working with Unicode, including
+these programs to fully or partly replace standard utilities:
+\&\fItcgrep\fR instead of \fIegrep\fR,
+\&\fIuniquote\fR instead of \fIcat \-v\fR or \fIhexdump\fR,
+\&\fIuniwc\fR instead of \fIwc\fR,
+\&\fIunilook\fR instead of \fIlook\fR,
+\&\fIunifmt\fR instead of \fIfmt\fR,
+and
+\&\fIucsort\fR instead of \fIsort\fR.
+For exploring Unicode character names and character properties,
+see its \fIuniprops\fR, \fIunichars\fR, and \fIuninames\fR programs.
+It also supplies these programs, all of which are general filters that do Unicode-y things:
+\&\fIunititle\fR and \fIunicaps\fR;
+\&\fIuniwide\fR and \fIuninarrow\fR;
+\&\fIunisupers\fR and \fIunisubs\fR;
+\&\fInfd\fR, \fInfc\fR, \fInfkd\fR, and \fInfkc\fR;
+and \fIuc\fR, \fIlc\fR, and \fItc\fR.
+.PP
+Finally, see the published Unicode Standard (page numbers are from version
+6.0.0), including these specific annexes and technical reports:
+.IP "§3.13 Default Case Algorithms, page 113; §4.2  Case, pages 120–122; Case Mappings, page 166–172, especially Caseless Matching starting on page 170." 4
+.IX Item "§3.13 Default Case Algorithms, page 113; §4.2 Case, pages 120–122; Case Mappings, page 166–172, especially Caseless Matching starting on page 170."
+.PD 0
+.IP "UAX #44: Unicode Character Database" 4
+.IX Item "UAX #44: Unicode Character Database"
+.IP "UTS #18: Unicode Regular Expressions" 4
+.IX Item "UTS #18: Unicode Regular Expressions"
+.IP "UAX #15: Unicode Normalization Forms" 4
+.IX Item "UAX #15: Unicode Normalization Forms"
+.IP "UTS #10: Unicode Collation Algorithm" 4
+.IX Item "UTS #10: Unicode Collation Algorithm"
+.IP "UAX #29: Unicode Text Segmentation" 4
+.IX Item "UAX #29: Unicode Text Segmentation"
+.IP "UAX #14: Unicode Line Breaking Algorithm" 4
+.IX Item "UAX #14: Unicode Line Breaking Algorithm"
+.IP "UAX #11: East Asian Width" 4
+.IX Item "UAX #11: East Asian Width"
+.PD
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen <tchrist@perl.com> wrote this, with occasional
+kibbitzing from Larry Wall and Jeffrey Friedl in the background.
+.SH "COPYRIGHT AND LICENCE"
+.IX Header "COPYRIGHT AND LICENCE"
+Copyright © 2012 Tom Christiansen.
+.PP
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Most of these examples taken from the current edition of the “Camel Book�;
+that is, from the 4ᵗʰ Edition of \fIProgramming Perl\fR, Copyright © 2012 Tom
+Christiansen <et al.>, 2012\-02\-13 by O’Reilly Media.  The code itself is
+freely redistributable, and you are encouraged to transplant, fold,
+spindle, and mutilate any of the examples in this manpage however you please
+for inclusion into your own programs without any encumbrance whatsoever.
+Acknowledgement via code comment is polite but not required.
+.SH "REVISION HISTORY"
+.IX Header "REVISION HISTORY"
+v1.0.0 – first public release, 2012\-02\-27
diff --git a/upstream/mageia-cauldron/man1/perlunifaq.1 b/upstream/mageia-cauldron/man1/perlunifaq.1
new file mode 100644
index 00000000..35be7580
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlunifaq.1
@@ -0,0 +1,389 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNIFAQ 1"
+.TH PERLUNIFAQ 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlunifaq \- Perl Unicode FAQ
+.SH "Q and A"
+.IX Header "Q and A"
+This is a list of questions and answers about Unicode in Perl, intended to be
+read after perlunitut.
+.SS "perlunitut isn't really a Unicode tutorial, is it?"
+.IX Subsection "perlunitut isn't really a Unicode tutorial, is it?"
+No, and this isn't really a Unicode FAQ.
+.PP
+Perl has an abstracted interface for all supported character encodings, so this
+is actually a generic \f(CW\*(C`Encode\*(C'\fR tutorial and \f(CW\*(C`Encode\*(C'\fR FAQ. But many people
+think that Unicode is special and magical, and I didn't want to disappoint
+them, so I decided to call the document a Unicode tutorial.
+.SS "What character encodings does Perl support?"
+.IX Subsection "What character encodings does Perl support?"
+To find out which character encodings your Perl supports, run:
+.PP
+.Vb 1
+\&    perl \-MEncode \-le "print for Encode\->encodings(\*(Aq:all\*(Aq)"
+.Ve
+.SS "Which version of perl should I use?"
+.IX Subsection "Which version of perl should I use?"
+Well, if you can, upgrade to the most recent, but certainly \f(CW5.8.1\fR or newer.
+The tutorial and FAQ assume the latest release.
+.PP
+You should also check your modules, and upgrade them if necessary. For example,
+HTML::Entities requires version >= 1.32 to function correctly, even though the
+changelog is silent about this.
+.SS "What about binary data, like images?"
+.IX Subsection "What about binary data, like images?"
+Well, apart from a bare \f(CW\*(C`binmode $fh\*(C'\fR, you shouldn't treat them specially.
+(The binmode is needed because otherwise Perl may convert line endings on Win32
+systems.)
+.PP
+Be careful, though, to never combine text strings with binary strings. If you
+need text in a binary stream, encode your text strings first using the
+appropriate encoding, then join them with binary strings. See also: "What if I
+don't encode?".
+.SS "When should I decode or encode?"
+.IX Subsection "When should I decode or encode?"
+Whenever you're communicating text with anything that is external to your perl
+process, like a database, a text file, a socket, or another program. Even if
+the thing you're communicating with is also written in Perl.
+.SS "What if I don't decode?"
+.IX Subsection "What if I don't decode?"
+Whenever your encoded, binary string is used together with a text string, Perl
+will assume that your binary string was encoded with ISO\-8859\-1, also known as
+latin\-1. If it wasn't latin\-1, then your data is unpleasantly converted. For
+example, if it was UTF\-8, the individual bytes of multibyte characters are seen
+as separate characters, and then again converted to UTF\-8. Such double encoding
+can be compared to double HTML encoding (\f(CW\*(C`&amp;gt;\*(C'\fR), or double URI encoding
+(\f(CW%253E\fR).
+.PP
+This silent implicit decoding is known as "upgrading". That may sound
+positive, but it's best to avoid it.
+.SS "What if I don't encode?"
+.IX Subsection "What if I don't encode?"
+It depends on what you output and how you output it.
+.PP
+\fIOutput via a filehandle\fR
+.IX Subsection "Output via a filehandle"
+.IP \(bu 4
+If the string's characters are all code point 255 or lower, Perl
+outputs bytes that match those code points. This is what happens with encoded
+strings. It can also, though, happen with unencoded strings that happen to be
+all code point 255 or lower.
+.IP \(bu 4
+Otherwise, Perl outputs the string encoded as UTF\-8. This only happens
+with strings you neglected to encode. Since that should not happen, Perl also
+throws a "wide character" warning in this case.
+.PP
+\fIOther output mechanisms (e.g., \fR\f(CI\*(C`exec\*(C'\fR\fI, \fR\f(CI\*(C`chdir\*(C'\fR\fI, ..)\fR
+.IX Subsection "Other output mechanisms (e.g., exec, chdir, ..)"
+.PP
+Your text string will be sent using the bytes in Perl's internal format.
+.PP
+Because the internal format is often UTF\-8, these bugs are hard to spot,
+because UTF\-8 is usually the encoding you wanted! But don't be lazy, and don't
+use the fact that Perl's internal format is UTF\-8 to your advantage. Encode
+explicitly to avoid weird bugs, and to show to maintenance programmers that you
+thought this through.
+.SS "Is there a way to automatically decode or encode?"
+.IX Subsection "Is there a way to automatically decode or encode?"
+If all data that comes from a certain handle is encoded in exactly the same
+way, you can tell the PerlIO system to automatically decode everything, with
+the \f(CW\*(C`encoding\*(C'\fR layer. If you do this, you can't accidentally forget to decode
+or encode anymore, on things that use the layered handle.
+.PP
+You can provide this layer when \f(CW\*(C`open\*(C'\fRing the file:
+.PP
+.Vb 2
+\&  open my $fh, \*(Aq>:encoding(UTF\-8)\*(Aq, $filename;  # auto encoding on write
+\&  open my $fh, \*(Aq<:encoding(UTF\-8)\*(Aq, $filename;  # auto decoding on read
+.Ve
+.PP
+Or if you already have an open filehandle:
+.PP
+.Vb 1
+\&  binmode $fh, \*(Aq:encoding(UTF\-8)\*(Aq;
+.Ve
+.PP
+Some database drivers for DBI can also automatically encode and decode, but
+that is sometimes limited to the UTF\-8 encoding.
+.SS "What if I don't know which encoding was used?"
+.IX Subsection "What if I don't know which encoding was used?"
+Do whatever you can to find out, and if you have to: guess. (Don't forget to
+document your guess with a comment.)
+.PP
+You could open the document in a web browser, and change the character set or
+character encoding until you can visually confirm that all characters look the
+way they should.
+.PP
+There is no way to reliably detect the encoding automatically, so if people
+keep sending you data without charset indication, you may have to educate them.
+.SS "Can I use Unicode in my Perl sources?"
+.IX Subsection "Can I use Unicode in my Perl sources?"
+Yes, you can! If your sources are UTF\-8 encoded, you can indicate that with the
+\&\f(CW\*(C`use utf8\*(C'\fR pragma.
+.PP
+.Vb 1
+\&    use utf8;
+.Ve
+.PP
+This doesn't do anything to your input, or to your output. It only influences
+the way your sources are read. You can use Unicode in string literals, in
+identifiers (but they still have to be "word characters" according to \f(CW\*(C`\ew\*(C'\fR),
+and even in custom delimiters.
+.SS "Data::Dumper doesn't restore the UTF8 flag; is it broken?"
+.IX Subsection "Data::Dumper doesn't restore the UTF8 flag; is it broken?"
+No, Data::Dumper's Unicode abilities are as they should be. There have been
+some complaints that it should restore the UTF8 flag when the data is read
+again with \f(CW\*(C`eval\*(C'\fR. However, you should really not look at the flag, and
+nothing indicates that Data::Dumper should break this rule.
+.PP
+Here's what happens: when Perl reads in a string literal, it sticks to 8 bit
+encoding as long as it can. (But perhaps originally it was internally encoded
+as UTF\-8, when you dumped it.) When it has to give that up because other
+characters are added to the text string, it silently upgrades the string to
+UTF\-8.
+.PP
+If you properly encode your strings for output, none of this is of your
+concern, and you can just \f(CW\*(C`eval\*(C'\fR dumped data as always.
+.SS "Why do regex character classes sometimes match only in the ASCII range?"
+.IX Subsection "Why do regex character classes sometimes match only in the ASCII range?"
+Starting in Perl 5.14 (and partially in Perl 5.12), just put a
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR near the beginning of your program.
+Within its lexical scope you shouldn't have this problem.  It also is
+automatically enabled under \f(CW\*(C`use feature \*(Aq:5.12\*(Aq\*(C'\fR or \f(CW\*(C`use v5.12\*(C'\fR or
+using \f(CW\*(C`\-E\*(C'\fR on the command line for Perl 5.12 or higher.
+.PP
+The rationale for requiring this is to not break older programs that
+rely on the way things worked before Unicode came along.  Those older
+programs knew only about the ASCII character set, and so may not work
+properly for additional characters.  When a string is encoded in UTF\-8,
+Perl assumes that the program is prepared to deal with Unicode, but when
+the string isn't, Perl assumes that only ASCII
+is wanted, and so those characters that are not ASCII
+characters aren't recognized as to what they would be in Unicode.
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR tells Perl to treat all characters as
+Unicode, whether the string is encoded in UTF\-8 or not, thus avoiding
+the problem.
+.PP
+However, on earlier Perls, or if you pass strings to subroutines outside
+the feature's scope, you can force Unicode rules by changing the
+encoding to UTF\-8 by doing \f(CWutf8::upgrade($string)\fR. This can be used
+safely on any string, as it checks and does not change strings that have
+already been upgraded.
+.PP
+For a more detailed discussion, see Unicode::Semantics on CPAN.
+.SS "Why do some characters not uppercase or lowercase correctly?"
+.IX Subsection "Why do some characters not uppercase or lowercase correctly?"
+See the answer to the previous question.
+.SS "How can I determine if a string is a text string or a binary string?"
+.IX Subsection "How can I determine if a string is a text string or a binary string?"
+You can't. Some use the UTF8 flag for this, but that's misuse, and makes well
+behaved modules like Data::Dumper look bad. The flag is useless for this
+purpose, because it's off when an 8 bit encoding (by default ISO\-8859\-1) is
+used to store the string.
+.PP
+This is something you, the programmer, has to keep track of; sorry. You could
+consider adopting a kind of "Hungarian notation" to help with this.
+.SS "How do I convert from encoding FOO to encoding BAR?"
+.IX Subsection "How do I convert from encoding FOO to encoding BAR?"
+By first converting the FOO-encoded byte string to a text string, and then the
+text string to a BAR-encoded byte string:
+.PP
+.Vb 2
+\&    my $text_string = decode(\*(AqFOO\*(Aq, $foo_string);
+\&    my $bar_string  = encode(\*(AqBAR\*(Aq, $text_string);
+.Ve
+.PP
+or by skipping the text string part, and going directly from one binary
+encoding to the other:
+.PP
+.Vb 2
+\&    use Encode qw(from_to);
+\&    from_to($string, \*(AqFOO\*(Aq, \*(AqBAR\*(Aq);  # changes contents of $string
+.Ve
+.PP
+or by letting automatic decoding and encoding do all the work:
+.PP
+.Vb 3
+\&    open my $foofh, \*(Aq<:encoding(FOO)\*(Aq, \*(Aqexample.foo.txt\*(Aq;
+\&    open my $barfh, \*(Aq>:encoding(BAR)\*(Aq, \*(Aqexample.bar.txt\*(Aq;
+\&    print { $barfh } $_ while <$foofh>;
+.Ve
+.ie n .SS "What are ""decode_utf8"" and ""encode_utf8""?"
+.el .SS "What are \f(CWdecode_utf8\fP and \f(CWencode_utf8\fP?"
+.IX Subsection "What are decode_utf8 and encode_utf8?"
+These are alternate syntaxes for \f(CW\*(C`decode(\*(Aqutf8\*(Aq, ...)\*(C'\fR and \f(CW\*(C`encode(\*(Aqutf8\*(Aq,
+\&...)\*(C'\fR. Do not use these functions for data exchange. Instead use
+\&\f(CW\*(C`decode(\*(AqUTF\-8\*(Aq, ...)\*(C'\fR and \f(CW\*(C`encode(\*(AqUTF\-8\*(Aq, ...)\*(C'\fR; see
+"What's the difference between UTF\-8 and utf8?" below.
+.SS "What is a ""wide character""?"
+.IX Subsection "What is a ""wide character""?"
+This is a term used for characters occupying more than one byte.
+.PP
+The Perl warning "Wide character in ..." is caused by such a character.
+With no specified encoding layer, Perl tries to
+fit things into a single byte.  When it can't, it
+emits this warning (if warnings are enabled), and uses UTF\-8 encoded data
+instead.
+.PP
+To avoid this warning and to avoid having different output encodings in a single
+stream, always specify an encoding explicitly, for example with a PerlIO layer:
+.PP
+.Vb 1
+\&    binmode STDOUT, ":encoding(UTF\-8)";
+.Ve
+.SH INTERNALS
+.IX Header "INTERNALS"
+.SS "What is ""the UTF8 flag""?"
+.IX Subsection "What is ""the UTF8 flag""?"
+Please, unless you're hacking the internals, or debugging weirdness, don't
+think about the UTF8 flag at all. That means that you very probably shouldn't
+use \f(CW\*(C`is_utf8\*(C'\fR, \f(CW\*(C`_utf8_on\*(C'\fR or \f(CW\*(C`_utf8_off\*(C'\fR at all.
+.PP
+The UTF8 flag, also called SvUTF8, is an internal flag that indicates that the
+current internal representation is UTF\-8. Without the flag, it is assumed to be
+ISO\-8859\-1. Perl converts between these automatically.  (Actually Perl usually
+assumes the representation is ASCII; see "Why do regex character classes
+sometimes match only in the ASCII range?" above.)
+.PP
+One of Perl's internal formats happens to be UTF\-8. Unfortunately, Perl can't
+keep a secret, so everyone knows about this. That is the source of much
+confusion. It's better to pretend that the internal format is some unknown
+encoding, and that you always have to encode and decode explicitly.
+.ie n .SS "What about the ""use bytes"" pragma?"
+.el .SS "What about the \f(CWuse bytes\fP pragma?"
+.IX Subsection "What about the use bytes pragma?"
+Don't use it. It makes no sense to deal with bytes in a text string, and it
+makes no sense to deal with characters in a byte string. Do the proper
+conversions (by decoding/encoding), and things will work out well: you get
+character counts for decoded data, and byte counts for encoded data.
+.PP
+\&\f(CW\*(C`use bytes\*(C'\fR is usually a failed attempt to do something useful. Just forget
+about it.
+.ie n .SS "What about the ""use encoding"" pragma?"
+.el .SS "What about the \f(CWuse encoding\fP pragma?"
+.IX Subsection "What about the use encoding pragma?"
+Don't use it. Unfortunately, it assumes that the programmer's environment and
+that of the user will use the same encoding. It will use the same encoding for
+the source code and for STDIN and STDOUT. When a program is copied to another
+machine, the source code does not change, but the STDIO environment might.
+.PP
+If you need non-ASCII characters in your source code, make it a UTF\-8 encoded
+file and \f(CW\*(C`use utf8\*(C'\fR.
+.PP
+If you need to set the encoding for STDIN, STDOUT, and STDERR, for example
+based on the user's locale, \f(CW\*(C`use open\*(C'\fR.
+.ie n .SS "What is the difference between "":encoding"" and "":utf8""?"
+.el .SS "What is the difference between \f(CW:encoding\fP and \f(CW:utf8\fP?"
+.IX Subsection "What is the difference between :encoding and :utf8?"
+Because UTF\-8 is one of Perl's internal formats, you can often just skip the
+encoding or decoding step, and manipulate the UTF8 flag directly.
+.PP
+Instead of \f(CW:encoding(UTF\-8)\fR, you can simply use \f(CW\*(C`:utf8\*(C'\fR, which skips the
+encoding step if the data was already represented as UTF8 internally. This is
+widely accepted as good behavior when you're writing, but it can be dangerous
+when reading, because it causes internal inconsistency when you have invalid
+byte sequences. Using \f(CW\*(C`:utf8\*(C'\fR for input can sometimes result in security
+breaches, so please use \f(CW:encoding(UTF\-8)\fR instead.
+.PP
+Instead of \f(CW\*(C`decode\*(C'\fR and \f(CW\*(C`encode\*(C'\fR, you could use \f(CW\*(C`_utf8_on\*(C'\fR and \f(CW\*(C`_utf8_off\*(C'\fR,
+but this is considered bad style. Especially \f(CW\*(C`_utf8_on\*(C'\fR can be dangerous, for
+the same reason that \f(CW\*(C`:utf8\*(C'\fR can.
+.PP
+There are some shortcuts for oneliners;
+see \-C in perlrun.
+.ie n .SS "What's the difference between ""UTF\-8"" and ""utf8""?"
+.el .SS "What's the difference between \f(CWUTF\-8\fP and \f(CWutf8\fP?"
+.IX Subsection "What's the difference between UTF-8 and utf8?"
+\&\f(CW\*(C`UTF\-8\*(C'\fR is the official standard. \f(CW\*(C`utf8\*(C'\fR is Perl's way of being liberal in
+what it accepts. If you have to communicate with things that aren't so liberal,
+you may want to consider using \f(CW\*(C`UTF\-8\*(C'\fR. If you have to communicate with things
+that are too liberal, you may have to use \f(CW\*(C`utf8\*(C'\fR. The full explanation is in
+"UTF\-8 vs. utf8 vs. UTF8" in Encode.
+.PP
+\&\f(CW\*(C`UTF\-8\*(C'\fR is internally known as \f(CW\*(C`utf\-8\-strict\*(C'\fR. The tutorial uses UTF\-8
+consistently, even where utf8 is actually used internally, because the
+distinction can be hard to make, and is mostly irrelevant.
+.PP
+For example, utf8 can be used for code points that don't exist in Unicode, like
+9999999, but if you encode that to UTF\-8, you get a substitution character (by
+default; see "Handling Malformed Data" in Encode for more ways of dealing with
+this.)
+.PP
+Okay, if you insist: the "internal format" is utf8, not UTF\-8. (When it's not
+some other encoding.)
+.SS "I lost track; what encoding is the internal format really?"
+.IX Subsection "I lost track; what encoding is the internal format really?"
+It's good that you lost track, because you shouldn't depend on the internal
+format being any specific encoding. But since you asked: by default, the
+internal format is either ISO\-8859\-1 (latin\-1), or utf8, depending on the
+history of the string. On EBCDIC platforms, this may be different even.
+.PP
+Perl knows how it stored the string internally, and will use that knowledge
+when you \f(CW\*(C`encode\*(C'\fR. In other words: don't try to find out what the internal
+encoding for a certain string is, but instead just encode it into the encoding
+that you want.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Juerd Waalboer <#####@juerd.nl>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlunicode, perluniintro, Encode
diff --git a/upstream/mageia-cauldron/man1/perluniintro.1 b/upstream/mageia-cauldron/man1/perluniintro.1
new file mode 100644
index 00000000..54046fe6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perluniintro.1
@@ -0,0 +1,1073 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNIINTRO 1"
+.TH PERLUNIINTRO 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perluniintro \- Perl Unicode introduction
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document gives a general idea of Unicode and how to use Unicode
+in Perl.  See "Further Resources" for references to more in-depth
+treatments of Unicode.
+.SS Unicode
+.IX Subsection "Unicode"
+Unicode is a character set standard which plans to codify all of the
+writing systems of the world, plus many other symbols.
+.PP
+Unicode and ISO/IEC 10646 are coordinated standards that unify
+almost all other modern character set standards,
+covering more than 80 writing systems and hundreds of languages,
+including all commercially-important modern languages.  All characters
+in the largest Chinese, Japanese, and Korean dictionaries are also
+encoded. The standards will eventually cover almost all characters in
+more than 250 writing systems and thousands of languages.
+Unicode 1.0 was released in October 1991, and 6.0 in October 2010.
+.PP
+A Unicode \fIcharacter\fR is an abstract entity.  It is not bound to any
+particular integer width, especially not to the C language \f(CW\*(C`char\*(C'\fR.
+Unicode is language-neutral and display-neutral: it does not encode the
+language of the text, and it does not generally define fonts or other graphical
+layout details.  Unicode operates on characters and on text built from
+those characters.
+.PP
+Unicode defines characters like \f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR or \f(CW\*(C`GREEK
+SMALL LETTER ALPHA\*(C'\fR and unique numbers for the characters, in this
+case 0x0041 and 0x03B1, respectively.  These unique numbers are called
+\&\fIcode points\fR.  A code point is essentially the position of the
+character within the set of all possible Unicode characters, and thus in
+Perl, the term \fIordinal\fR is often used interchangeably with it.
+.PP
+The Unicode standard prefers using hexadecimal notation for the code
+points.  If numbers like \f(CW0x0041\fR are unfamiliar to you, take a peek
+at a later section, "Hexadecimal Notation".  The Unicode standard
+uses the notation \f(CW\*(C`U+0041 LATIN CAPITAL LETTER A\*(C'\fR, to give the
+hexadecimal code point and the normative name of the character.
+.PP
+Unicode also defines various \fIproperties\fR for the characters, like
+"uppercase" or "lowercase", "decimal digit", or "punctuation";
+these properties are independent of the names of the characters.
+Furthermore, various operations on the characters like uppercasing,
+lowercasing, and collating (sorting) are defined.
+.PP
+A Unicode \fIlogical\fR "character" can actually consist of more than one internal
+\&\fIactual\fR "character" or code point.  For Western languages, this is adequately
+modelled by a \fIbase character\fR (like \f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR) followed
+by one or more \fImodifiers\fR (like \f(CW\*(C`COMBINING ACUTE ACCENT\*(C'\fR).  This sequence of
+base character and modifiers is called a \fIcombining character
+sequence\fR.  Some non-western languages require more complicated
+models, so Unicode created the \fIgrapheme cluster\fR concept, which was
+later further refined into the \fIextended grapheme cluster\fR.  For
+example, a Korean Hangul syllable is considered a single logical
+character, but most often consists of three actual
+Unicode characters: a leading consonant followed by an interior vowel followed
+by a trailing consonant.
+.PP
+Whether to call these extended grapheme clusters "characters" depends on your
+point of view. If you are a programmer, you probably would tend towards seeing
+each element in the sequences as one unit, or "character".  However from
+the user's point of view, the whole sequence could be seen as one
+"character" since that's probably what it looks like in the context of the
+user's language.  In this document, we take the programmer's point of
+view: one "character" is one Unicode code point.
+.PP
+For some combinations of base character and modifiers, there are
+\&\fIprecomposed\fR characters.  There is a single character equivalent, for
+example, for the sequence \f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR followed by
+\&\f(CW\*(C`COMBINING ACUTE ACCENT\*(C'\fR.  It is called  \f(CW\*(C`LATIN CAPITAL LETTER A WITH
+ACUTE\*(C'\fR.  These precomposed characters are, however, only available for
+some combinations, and are mainly meant to support round-trip
+conversions between Unicode and legacy standards (like ISO 8859).  Using
+sequences, as Unicode does, allows for needing fewer basic building blocks
+(code points) to express many more potential grapheme clusters.  To
+support conversion between equivalent forms, various \fInormalization
+forms\fR are also defined.  Thus, \f(CW\*(C`LATIN CAPITAL LETTER A WITH ACUTE\*(C'\fR is
+in \fINormalization Form Composed\fR, (abbreviated NFC), and the sequence
+\&\f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR followed by \f(CW\*(C`COMBINING ACUTE ACCENT\*(C'\fR
+represents the same character in \fINormalization Form Decomposed\fR (NFD).
+.PP
+Because of backward compatibility with legacy encodings, the "a unique
+number for every character" idea breaks down a bit: instead, there is
+"at least one number for every character".  The same character could
+be represented differently in several legacy encodings.  The
+converse is not true: some code points do not have an assigned
+character.  Firstly, there are unallocated code points within
+otherwise used blocks.  Secondly, there are special Unicode control
+characters that do not represent true characters.
+.PP
+When Unicode was first conceived, it was thought that all the world's
+characters could be represented using a 16\-bit word; that is a maximum of
+\&\f(CW0x10000\fR (or 65,536) characters would be needed, from \f(CW0x0000\fR to
+\&\f(CW0xFFFF\fR.  This soon proved to be wrong, and since Unicode 2.0 (July
+1996), Unicode has been defined all the way up to 21 bits (\f(CW0x10FFFF\fR),
+and Unicode 3.1 (March 2001) defined the first characters above \f(CW0xFFFF\fR.
+The first \f(CW0x10000\fR characters are called the \fIPlane 0\fR, or the
+\&\fIBasic Multilingual Plane\fR (BMP).  With Unicode 3.1, 17 (yes,
+seventeen) planes in all were defined\-\-but they are nowhere near full of
+defined characters, yet.
+.PP
+When a new language is being encoded, Unicode generally will choose a
+\&\f(CW\*(C`block\*(C'\fR of consecutive unallocated code points for its characters.  So
+far, the number of code points in these blocks has always been evenly
+divisible by 16.  Extras in a block, not currently needed, are left
+unallocated, for future growth.  But there have been occasions when
+a later release needed more code points than the available extras, and a
+new block had to allocated somewhere else, not contiguous to the initial
+one, to handle the overflow.  Thus, it became apparent early on that
+"block" wasn't an adequate organizing principle, and so the \f(CW\*(C`Script\*(C'\fR
+property was created.  (Later an improved script property was added as
+well, the \f(CW\*(C`Script_Extensions\*(C'\fR property.)  Those code points that are in
+overflow blocks can still
+have the same script as the original ones.  The script concept fits more
+closely with natural language: there is \f(CW\*(C`Latin\*(C'\fR script, \f(CW\*(C`Greek\*(C'\fR
+script, and so on; and there are several artificial scripts, like
+\&\f(CW\*(C`Common\*(C'\fR for characters that are used in multiple scripts, such as
+mathematical symbols.  Scripts usually span varied parts of several
+blocks.  For more information about scripts, see "Scripts" in perlunicode.
+The division into blocks exists, but it is almost completely
+accidental\-\-an artifact of how the characters have been and still are
+allocated.  (Note that this paragraph has oversimplified things for the
+sake of this being an introduction.  Unicode doesn't really encode
+languages, but the writing systems for them\-\-their scripts; and one
+script can be used by many languages.  Unicode also encodes things that
+aren't really about languages, such as symbols like \f(CW\*(C`BAGGAGE CLAIM\*(C'\fR.)
+.PP
+The Unicode code points are just abstract numbers.  To input and
+output these abstract numbers, the numbers must be \fIencoded\fR or
+\&\fIserialised\fR somehow.  Unicode defines several \fIcharacter encoding
+forms\fR, of which \fIUTF\-8\fR is the most popular.  UTF\-8 is a
+variable length encoding that encodes Unicode characters as 1 to 4
+bytes.  Other encodings
+include UTF\-16 and UTF\-32 and their big\- and little-endian variants
+(UTF\-8 is byte-order independent).  The ISO/IEC 10646 defines the UCS\-2
+and UCS\-4 encoding forms.
+.PP
+For more information about encodings\-\-for instance, to learn what
+\&\fIsurrogates\fR and \fIbyte order marks\fR (BOMs) are\-\-see perlunicode.
+.SS "Perl's Unicode Support"
+.IX Subsection "Perl's Unicode Support"
+Starting from Perl v5.6.0, Perl has had the capacity to handle Unicode
+natively.  Perl v5.8.0, however, is the first recommended release for
+serious Unicode work.  The maintenance release 5.6.1 fixed many of the
+problems of the initial Unicode implementation, but for example
+regular expressions still do not work with Unicode in 5.6.1.
+Perl v5.14.0 is the first release where Unicode support is
+(almost) seamlessly integratable without some gotchas. (There are a few
+exceptions. Firstly, some differences in quotemeta
+were fixed starting in Perl 5.16.0. Secondly, some differences in
+the range operator were fixed starting in
+Perl 5.26.0. Thirdly, some differences in split were fixed
+started in Perl 5.28.0.)
+.PP
+To enable this
+seamless support, you should \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR (which is
+automatically selected if you \f(CW\*(C`use v5.12\*(C'\fR or higher).  See feature.
+(5.14 also fixes a number of bugs and departures from the Unicode
+standard.)
+.PP
+Before Perl v5.8.0, the use of \f(CW\*(C`use utf8\*(C'\fR was used to declare
+that operations in the current block or file would be Unicode-aware.
+This model was found to be wrong, or at least clumsy: the "Unicodeness"
+is now carried with the data, instead of being attached to the
+operations.
+Starting with Perl v5.8.0, only one case remains where an explicit \f(CW\*(C`use
+utf8\*(C'\fR is needed: if your Perl script itself is encoded in UTF\-8, you can
+use UTF\-8 in your identifier names, and in string and regular expression
+literals, by saying \f(CW\*(C`use utf8\*(C'\fR.  This is not the default because
+scripts with legacy 8\-bit data in them would break.  See utf8.
+.SS "Perl's Unicode Model"
+.IX Subsection "Perl's Unicode Model"
+Perl supports both pre\-5.6 strings of eight-bit native bytes, and
+strings of Unicode characters.  The general principle is that Perl tries
+to keep its data as eight-bit bytes for as long as possible, but as soon
+as Unicodeness cannot be avoided, the data is transparently upgraded
+to Unicode.  Prior to Perl v5.14.0, the upgrade was not completely
+transparent (see "The "Unicode Bug"" in perlunicode), and for backwards
+compatibility, full transparency is not gained unless \f(CWuse feature
+\&\*(Aqunicode_strings\*(Aq\fR (see feature) or \f(CW\*(C`use v5.12\*(C'\fR (or higher) is
+selected.
+.PP
+Internally, Perl currently uses either whatever the native eight-bit
+character set of the platform (for example Latin\-1) is, defaulting to
+UTF\-8, to encode Unicode strings. Specifically, if all code points in
+the string are \f(CW0xFF\fR or less, Perl uses the native eight-bit
+character set.  Otherwise, it uses UTF\-8.
+.PP
+A user of Perl does not normally need to know nor care how Perl
+happens to encode its internal strings, but it becomes relevant when
+outputting Unicode strings to a stream without a PerlIO layer (one with
+the "default" encoding).  In such a case, the raw bytes used internally
+(the native character set or UTF\-8, as appropriate for each string)
+will be used, and a "Wide character" warning will be issued if those
+strings contain a character beyond 0x00FF.
+.PP
+For example,
+.PP
+.Vb 1
+\&      perl \-e \*(Aqprint "\ex{DF}\en", "\ex{0100}\ex{DF}\en"\*(Aq
+.Ve
+.PP
+produces a fairly useless mixture of native bytes and UTF\-8, as well
+as a warning:
+.PP
+.Vb 1
+\&     Wide character in print at ...
+.Ve
+.PP
+To output UTF\-8, use the \f(CW\*(C`:encoding\*(C'\fR or \f(CW\*(C`:utf8\*(C'\fR output layer.  Prepending
+.PP
+.Vb 1
+\&      binmode(STDOUT, ":utf8");
+.Ve
+.PP
+to this sample program ensures that the output is completely UTF\-8,
+and removes the program's warning.
+.PP
+You can enable automatic UTF\-8\-ification of your standard file
+handles, default \f(CWopen()\fR layer, and \f(CW@ARGV\fR by using either
+the \f(CW\*(C`\-C\*(C'\fR command line switch or the \f(CW\*(C`PERL_UNICODE\*(C'\fR environment
+variable, see perlrun for the
+documentation of the \f(CW\*(C`\-C\*(C'\fR switch.
+.PP
+Note that this means that Perl expects other software to work the same
+way:
+if Perl has been led to believe that STDIN should be UTF\-8, but then
+STDIN coming in from another command is not UTF\-8, Perl will likely
+complain about the malformed UTF\-8.
+.PP
+All features that combine Unicode and I/O also require using the new
+PerlIO feature.  Almost all Perl 5.8 platforms do use PerlIO, though:
+you can see whether yours is by running "perl \-V" and looking for
+\&\f(CW\*(C`useperlio=define\*(C'\fR.
+.SS "Unicode and EBCDIC"
+.IX Subsection "Unicode and EBCDIC"
+Perl 5.8.0 added support for Unicode on EBCDIC platforms.  This support
+was allowed to lapse in later releases, but was revived in 5.22.
+Unicode support is somewhat more complex to implement since additional
+conversions are needed.  See perlebcdic for more information.
+.PP
+On EBCDIC platforms, the internal Unicode encoding form is UTF-EBCDIC
+instead of UTF\-8.  The difference is that as UTF\-8 is "ASCII-safe" in
+that ASCII characters encode to UTF\-8 as-is, while UTF-EBCDIC is
+"EBCDIC-safe", in that all the basic characters (which includes all
+those that have ASCII equivalents (like \f(CW"A"\fR, \f(CW"0"\fR, \f(CW"%"\fR, \fIetc.\fR)
+are the same in both EBCDIC and UTF-EBCDIC.  Often, documentation
+will use the term "UTF\-8" to mean UTF-EBCDIC as well.  This is the case
+in this document.
+.SS "Creating Unicode"
+.IX Subsection "Creating Unicode"
+This section applies fully to Perls starting with v5.22.  Various
+caveats for earlier releases are in the "Earlier releases caveats"
+subsection below.
+.PP
+To create Unicode characters in literals,
+use the \f(CW\*(C`\eN{...}\*(C'\fR notation in double-quoted strings:
+.PP
+.Vb 2
+\& my $smiley_from_name = "\eN{WHITE SMILING FACE}";
+\& my $smiley_from_code_point = "\eN{U+263a}";
+.Ve
+.PP
+Similarly, they can be used in regular expression literals
+.PP
+.Vb 2
+\& $smiley =~ /\eN{WHITE SMILING FACE}/;
+\& $smiley =~ /\eN{U+263a}/;
+.Ve
+.PP
+or, starting in v5.32:
+.PP
+.Vb 2
+\& $smiley =~ /\ep{Name=WHITE SMILING FACE}/;
+\& $smiley =~ /\ep{Name=whitesmilingface}/;
+.Ve
+.PP
+At run-time you can use:
+.PP
+.Vb 4
+\& use charnames ();
+\& my $hebrew_alef_from_name
+\&                      = charnames::string_vianame("HEBREW LETTER ALEF");
+\& my $hebrew_alef_from_code_point = charnames::string_vianame("U+05D0");
+.Ve
+.PP
+Naturally, \f(CWord()\fR will do the reverse: it turns a character into
+a code point.
+.PP
+There are other runtime options as well.  You can use \f(CWpack()\fR:
+.PP
+.Vb 1
+\& my $hebrew_alef_from_code_point = pack("U", 0x05d0);
+.Ve
+.PP
+Or you can use \f(CWchr()\fR, though it is less convenient in the general
+case:
+.PP
+.Vb 2
+\& $hebrew_alef_from_code_point = chr(utf8::unicode_to_native(0x05d0));
+\& utf8::upgrade($hebrew_alef_from_code_point);
+.Ve
+.PP
+The \f(CWutf8::unicode_to_native()\fR and \f(CWutf8::upgrade()\fR aren't needed if
+the argument is above 0xFF, so the above could have been written as
+.PP
+.Vb 1
+\& $hebrew_alef_from_code_point = chr(0x05d0);
+.Ve
+.PP
+since 0x5d0 is above 255.
+.PP
+\&\f(CW\*(C`\ex{}\*(C'\fR and \f(CW\*(C`\eo{}\*(C'\fR can also be used to specify code points at compile
+time in double-quotish strings, but, for backward compatibility with
+older Perls, the same rules apply as with \f(CWchr()\fR for code points less
+than 256.
+.PP
+\&\f(CWutf8::unicode_to_native()\fR is used so that the Perl code is portable
+to EBCDIC platforms.  You can omit it if you're \fIreally\fR sure no one
+will ever want to use your code on a non-ASCII platform.  Starting in
+Perl v5.22, calls to it on ASCII platforms are optimized out, so there's
+no performance penalty at all in adding it.  Or you can simply use the
+other constructs that don't require it.
+.PP
+See "Further Resources" for how to find all these names and numeric
+codes.
+.PP
+\fIEarlier releases caveats\fR
+.IX Subsection "Earlier releases caveats"
+.PP
+On EBCDIC platforms, prior to v5.22, using \f(CW\*(C`\eN{U+...}\*(C'\fR doesn't work
+properly.
+.PP
+Prior to v5.16, using \f(CW\*(C`\eN{...}\*(C'\fR with a character name (as opposed to a
+\&\f(CW\*(C`U+...\*(C'\fR code point) required a \f(CW\*(C`use\ charnames\ :full\*(C'\fR.
+.PP
+Prior to v5.14, there were some bugs in \f(CW\*(C`\eN{...}\*(C'\fR with a character name
+(as opposed to a \f(CW\*(C`U+...\*(C'\fR code point).
+.PP
+\&\f(CWcharnames::string_vianame()\fR was introduced in v5.14.  Prior to that,
+\&\f(CWcharnames::vianame()\fR should work, but only if the argument is of the
+form \f(CW"U+..."\fR.  Your best bet there for runtime Unicode by character
+name is probably:
+.PP
+.Vb 3
+\& use charnames ();
+\& my $hebrew_alef_from_name
+\&                  = pack("U", charnames::vianame("HEBREW LETTER ALEF"));
+.Ve
+.SS "Handling Unicode"
+.IX Subsection "Handling Unicode"
+Handling Unicode is for the most part transparent: just use the
+strings as usual.  Functions like \f(CWindex()\fR, \f(CWlength()\fR, and
+\&\f(CWsubstr()\fR will work on the Unicode characters; regular expressions
+will work on the Unicode characters (see perlunicode and perlretut).
+.PP
+Note that Perl considers grapheme clusters to be separate characters, so for
+example
+.PP
+.Vb 2
+\& print length("\eN{LATIN CAPITAL LETTER A}\eN{COMBINING ACUTE ACCENT}"),
+\&       "\en";
+.Ve
+.PP
+will print 2, not 1.  The only exception is that regular expressions
+have \f(CW\*(C`\eX\*(C'\fR for matching an extended grapheme cluster.  (Thus \f(CW\*(C`\eX\*(C'\fR in a
+regular expression would match the entire sequence of both the example
+characters.)
+.PP
+Life is not quite so transparent, however, when working with legacy
+encodings, I/O, and certain special cases:
+.SS "Legacy Encodings"
+.IX Subsection "Legacy Encodings"
+When you combine legacy data and Unicode, the legacy data needs
+to be upgraded to Unicode.  Normally the legacy data is assumed to be
+ISO 8859\-1 (or EBCDIC, if applicable).
+.PP
+The \f(CW\*(C`Encode\*(C'\fR module knows about many encodings and has interfaces
+for doing conversions between those encodings:
+.PP
+.Vb 2
+\&    use Encode \*(Aqdecode\*(Aq;
+\&    $data = decode("iso\-8859\-3", $data); # convert from legacy
+.Ve
+.SS "Unicode I/O"
+.IX Subsection "Unicode I/O"
+Normally, writing out Unicode data
+.PP
+.Vb 1
+\&    print FH $some_string_with_unicode, "\en";
+.Ve
+.PP
+produces raw bytes that Perl happens to use to internally encode the
+Unicode string.  Perl's internal encoding depends on the system as
+well as what characters happen to be in the string at the time. If
+any of the characters are at code points \f(CW0x100\fR or above, you will get
+a warning.  To ensure that the output is explicitly rendered in the
+encoding you desire\-\-and to avoid the warning\-\-open the stream with
+the desired encoding. Some examples:
+.PP
+.Vb 1
+\&    open FH, ">:utf8", "file";
+\&
+\&    open FH, ">:encoding(ucs2)",      "file";
+\&    open FH, ">:encoding(UTF\-8)",     "file";
+\&    open FH, ">:encoding(shift_jis)", "file";
+.Ve
+.PP
+and on already open streams, use \f(CWbinmode()\fR:
+.PP
+.Vb 1
+\&    binmode(STDOUT, ":utf8");
+\&
+\&    binmode(STDOUT, ":encoding(ucs2)");
+\&    binmode(STDOUT, ":encoding(UTF\-8)");
+\&    binmode(STDOUT, ":encoding(shift_jis)");
+.Ve
+.PP
+The matching of encoding names is loose: case does not matter, and
+many encodings have several aliases.  Note that the \f(CW\*(C`:utf8\*(C'\fR layer
+must always be specified exactly like that; it is \fInot\fR subject to
+the loose matching of encoding names. Also note that currently \f(CW\*(C`:utf8\*(C'\fR is unsafe for
+input, because it accepts the data without validating that it is indeed valid
+UTF\-8; you should instead use \f(CW:encoding(UTF\-8)\fR (with or without a
+hyphen).
+.PP
+See PerlIO for the \f(CW\*(C`:utf8\*(C'\fR layer, PerlIO::encoding and
+Encode::PerlIO for the \f(CW:encoding()\fR layer, and
+Encode::Supported for many encodings supported by the \f(CW\*(C`Encode\*(C'\fR
+module.
+.PP
+Reading in a file that you know happens to be encoded in one of the
+Unicode or legacy encodings does not magically turn the data into
+Unicode in Perl's eyes.  To do that, specify the appropriate
+layer when opening files
+.PP
+.Vb 2
+\&    open(my $fh,\*(Aq<:encoding(UTF\-8)\*(Aq, \*(Aqanything\*(Aq);
+\&    my $line_of_unicode = <$fh>;
+\&
+\&    open(my $fh,\*(Aq<:encoding(Big5)\*(Aq, \*(Aqanything\*(Aq);
+\&    my $line_of_unicode = <$fh>;
+.Ve
+.PP
+The I/O layers can also be specified more flexibly with
+the \f(CW\*(C`open\*(C'\fR pragma.  See open, or look at the following example.
+.PP
+.Vb 8
+\&    use open \*(Aq:encoding(UTF\-8)\*(Aq; # input/output default encoding will be
+\&                                 # UTF\-8
+\&    open X, ">file";
+\&    print X chr(0x100), "\en";
+\&    close X;
+\&    open Y, "<file";
+\&    printf "%#x\en", ord(<Y>); # this should print 0x100
+\&    close Y;
+.Ve
+.PP
+With the \f(CW\*(C`open\*(C'\fR pragma you can use the \f(CW\*(C`:locale\*(C'\fR layer
+.PP
+.Vb 10
+\&    BEGIN { $ENV{LC_ALL} = $ENV{LANG} = \*(Aqru_RU.KOI8\-R\*(Aq }
+\&    # the :locale will probe the locale environment variables like
+\&    # LC_ALL
+\&    use open OUT => \*(Aq:locale\*(Aq; # russki parusski
+\&    open(O, ">koi8");
+\&    print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8\-R 0xc1
+\&    close O;
+\&    open(I, "<koi8");
+\&    printf "%#x\en", ord(<I>), "\en"; # this should print 0xc1
+\&    close I;
+.Ve
+.PP
+These methods install a transparent filter on the I/O stream that
+converts data from the specified encoding when it is read in from the
+stream.  The result is always Unicode.
+.PP
+The open pragma affects all the \f(CWopen()\fR calls after the pragma by
+setting default layers.  If you want to affect only certain
+streams, use explicit layers directly in the \f(CWopen()\fR call.
+.PP
+You can switch encodings on an already opened stream by using
+\&\f(CWbinmode()\fR; see "binmode" in perlfunc.
+.PP
+The \f(CW\*(C`:locale\*(C'\fR does not currently work with
+\&\f(CWopen()\fR and \f(CWbinmode()\fR, only with the \f(CW\*(C`open\*(C'\fR pragma.  The
+\&\f(CW\*(C`:utf8\*(C'\fR and \f(CW:encoding(...)\fR methods do work with all of \f(CWopen()\fR,
+\&\f(CWbinmode()\fR, and the \f(CW\*(C`open\*(C'\fR pragma.
+.PP
+Similarly, you may use these I/O layers on output streams to
+automatically convert Unicode to the specified encoding when it is
+written to the stream. For example, the following snippet copies the
+contents of the file "text.jis" (encoded as ISO\-2022\-JP, aka JIS) to
+the file "text.utf8", encoded as UTF\-8:
+.PP
+.Vb 3
+\&    open(my $nihongo, \*(Aq<:encoding(iso\-2022\-jp)\*(Aq, \*(Aqtext.jis\*(Aq);
+\&    open(my $unicode, \*(Aq>:utf8\*(Aq,                  \*(Aqtext.utf8\*(Aq);
+\&    while (<$nihongo>) { print $unicode $_ }
+.Ve
+.PP
+The naming of encodings, both by the \f(CWopen()\fR and by the \f(CW\*(C`open\*(C'\fR
+pragma allows for flexible names: \f(CW\*(C`koi8\-r\*(C'\fR and \f(CW\*(C`KOI8R\*(C'\fR will both be
+understood.
+.PP
+Common encodings recognized by ISO, MIME, IANA, and various other
+standardisation organisations are recognised; for a more detailed
+list see Encode::Supported.
+.PP
+\&\f(CWread()\fR reads characters and returns the number of characters.
+\&\f(CWseek()\fR and \f(CWtell()\fR operate on byte counts, as does \f(CWsysseek()\fR.
+.PP
+\&\f(CWsysread()\fR and \f(CWsyswrite()\fR should not be used on file handles with
+character encoding layers, they behave badly, and that behaviour has
+been deprecated since perl 5.24.
+.PP
+Notice that because of the default behaviour of not doing any
+conversion upon input if there is no default layer,
+it is easy to mistakenly write code that keeps on expanding a file
+by repeatedly encoding the data:
+.PP
+.Vb 8
+\&    # BAD CODE WARNING
+\&    open F, "file";
+\&    local $/; ## read in the whole file of 8\-bit characters
+\&    $t = <F>;
+\&    close F;
+\&    open F, ">:encoding(UTF\-8)", "file";
+\&    print F $t; ## convert to UTF\-8 on output
+\&    close F;
+.Ve
+.PP
+If you run this code twice, the contents of the \fIfile\fR will be twice
+UTF\-8 encoded.  A \f(CW\*(C`use open \*(Aq:encoding(UTF\-8)\*(Aq\*(C'\fR would have avoided the
+bug, or explicitly opening also the \fIfile\fR for input as UTF\-8.
+.PP
+\&\fBNOTE\fR: the \f(CW\*(C`:utf8\*(C'\fR and \f(CW\*(C`:encoding\*(C'\fR features work only if your
+Perl has been built with PerlIO, which is the default
+on most systems.
+.SS "Displaying Unicode As Text"
+.IX Subsection "Displaying Unicode As Text"
+Sometimes you might want to display Perl scalars containing Unicode as
+simple ASCII (or EBCDIC) text.  The following subroutine converts
+its argument so that Unicode characters with code points greater than
+255 are displayed as \f(CW\*(C`\ex{...}\*(C'\fR, control characters (like \f(CW\*(C`\en\*(C'\fR) are
+displayed as \f(CW\*(C`\ex..\*(C'\fR, and the rest of the characters as themselves:
+.PP
+.Vb 9
+\& sub nice_string {
+\&        join("",
+\&        map { $_ > 255                    # if wide character...
+\&              ? sprintf("\e\ex{%04X}", $_)  # \ex{...}
+\&              : chr($_) =~ /[[:cntrl:]]/  # else if control character...
+\&                ? sprintf("\e\ex%02X", $_)  # \ex..
+\&                : quotemeta(chr($_))      # else quoted or as themselves
+\&        } unpack("W*", $_[0]));           # unpack Unicode characters
+\&   }
+.Ve
+.PP
+For example,
+.PP
+.Vb 1
+\&   nice_string("foo\ex{100}bar\en")
+.Ve
+.PP
+returns the string
+.PP
+.Vb 1
+\&   \*(Aqfoo\ex{0100}bar\ex0A\*(Aq
+.Ve
+.PP
+which is ready to be printed.
+.PP
+(\f(CW\*(C`\e\ex{}\*(C'\fR is used here instead of \f(CW\*(C`\e\eN{}\*(C'\fR, since it's most likely that
+you want to see what the native values are.)
+.SS "Special Cases"
+.IX Subsection "Special Cases"
+.IP \(bu 4
+Starting in Perl 5.28, it is illegal for bit operators, like \f(CW\*(C`~\*(C'\fR, to
+operate on strings containing code points above 255.
+.IP \(bu 4
+The \fBvec()\fR function may produce surprising results if
+used on strings containing characters with ordinal values above
+255. In such a case, the results are consistent with the internal
+encoding of the characters, but not with much else. So don't do
+that, and starting in Perl 5.28, a deprecation message is issued if you
+do so, becoming illegal in Perl 5.32.
+.IP \(bu 4
+Peeking At Perl's Internal Encoding
+.Sp
+Normal users of Perl should never care how Perl encodes any particular
+Unicode string (because the normal ways to get at the contents of a
+string with Unicode\-\-via input and output\-\-should always be via
+explicitly-defined I/O layers). But if you must, there are two
+ways of looking behind the scenes.
+.Sp
+One way of peeking inside the internal encoding of Unicode characters
+is to use \f(CW\*(C`unpack("C*", ...\*(C'\fR to get the bytes of whatever the string
+encoding happens to be, or \f(CW\*(C`unpack("U0..", ...)\*(C'\fR to get the bytes of the
+UTF\-8 encoding:
+.Sp
+.Vb 2
+\&    # this prints  c4 80  for the UTF\-8 bytes 0xc4 0x80
+\&    print join(" ", unpack("U0(H2)*", pack("U", 0x100))), "\en";
+.Ve
+.Sp
+Yet another way would be to use the Devel::Peek module:
+.Sp
+.Vb 1
+\&    perl \-MDevel::Peek \-e \*(AqDump(chr(0x100))\*(Aq
+.Ve
+.Sp
+That shows the \f(CW\*(C`UTF8\*(C'\fR flag in FLAGS and both the UTF\-8 bytes
+and Unicode characters in \f(CW\*(C`PV\*(C'\fR.  See also later in this document
+the discussion about the \f(CWutf8::is_utf8()\fR function.
+.SS "Advanced Topics"
+.IX Subsection "Advanced Topics"
+.IP \(bu 4
+String Equivalence
+.Sp
+The question of string equivalence turns somewhat complicated
+in Unicode: what do you mean by "equal"?
+.Sp
+(Is \f(CW\*(C`LATIN CAPITAL LETTER A WITH ACUTE\*(C'\fR equal to
+\&\f(CW\*(C`LATIN CAPITAL LETTER A\*(C'\fR?)
+.Sp
+The short answer is that by default Perl compares equivalence (\f(CW\*(C`eq\*(C'\fR,
+\&\f(CW\*(C`ne\*(C'\fR) based only on code points of the characters.  In the above
+case, the answer is no (because 0x00C1 != 0x0041).  But sometimes, any
+CAPITAL LETTER A's should be considered equal, or even A's of any case.
+.Sp
+The long answer is that you need to consider character normalization
+and casing issues: see Unicode::Normalize, Unicode Technical Report #15,
+Unicode Normalization Forms <https://www.unicode.org/reports/tr15> and
+sections on case mapping in the Unicode Standard <https://www.unicode.org>.
+.Sp
+As of Perl 5.8.0, the "Full" case-folding of \fICase
+Mappings/SpecialCasing\fR is implemented, but bugs remain in \f(CW\*(C`qr//i\*(C'\fR with them,
+mostly fixed by 5.14, and essentially entirely by 5.18.
+.IP \(bu 4
+String Collation
+.Sp
+People like to see their strings nicely sorted\-\-or as Unicode
+parlance goes, collated.  But again, what do you mean by collate?
+.Sp
+(Does \f(CW\*(C`LATIN CAPITAL LETTER A WITH ACUTE\*(C'\fR come before or after
+\&\f(CW\*(C`LATIN CAPITAL LETTER A WITH GRAVE\*(C'\fR?)
+.Sp
+The short answer is that by default, Perl compares strings (\f(CW\*(C`lt\*(C'\fR,
+\&\f(CW\*(C`le\*(C'\fR, \f(CW\*(C`cmp\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, \f(CW\*(C`gt\*(C'\fR) based only on the code points of the
+characters.  In the above case, the answer is "after", since
+\&\f(CW0x00C1\fR > \f(CW0x00C0\fR.
+.Sp
+The long answer is that "it depends", and a good answer cannot be
+given without knowing (at the very least) the language context.
+See Unicode::Collate, and \fIUnicode Collation Algorithm\fR
+<https://www.unicode.org/reports/tr10/>
+.SS Miscellaneous
+.IX Subsection "Miscellaneous"
+.IP \(bu 4
+Character Ranges and Classes
+.Sp
+Character ranges in regular expression bracketed character classes ( e.g.,
+\&\f(CW\*(C`/[a\-z]/\*(C'\fR) and in the \f(CW\*(C`tr///\*(C'\fR (also known as \f(CW\*(C`y///\*(C'\fR) operator are not
+magically Unicode-aware.  What this means is that \f(CW\*(C`[A\-Za\-z]\*(C'\fR will not
+magically start to mean "all alphabetic letters" (not that it does mean that
+even for 8\-bit characters; for those, if you are using locales (perllocale),
+use \f(CW\*(C`/[[:alpha:]]/\*(C'\fR; and if not, use the 8\-bit\-aware property \f(CW\*(C`\ep{alpha}\*(C'\fR).
+.Sp
+All the properties that begin with \f(CW\*(C`\ep\*(C'\fR (and its inverse \f(CW\*(C`\eP\*(C'\fR) are actually
+character classes that are Unicode-aware.  There are dozens of them, see
+perluniprops.
+.Sp
+Starting in v5.22, you can use Unicode code points as the end points of
+regular expression pattern character ranges, and the range will include
+all Unicode code points that lie between those end points, inclusive.
+.Sp
+.Vb 1
+\& qr/ [ \eN{U+03} \- \eN{U+20} ] /xx
+.Ve
+.Sp
+includes the code points
+\&\f(CW\*(C`\eN{U+03}\*(C'\fR, \f(CW\*(C`\eN{U+04}\*(C'\fR, ..., \f(CW\*(C`\eN{U+20}\*(C'\fR.
+.Sp
+This also works for ranges in \f(CW\*(C`tr///\*(C'\fR starting in Perl v5.24.
+.IP \(bu 4
+String-To-Number Conversions
+.Sp
+Unicode does define several other decimal\-\-and numeric\-\-characters
+besides the familiar 0 to 9, such as the Arabic and Indic digits.
+Perl does not support string-to-number conversion for digits other
+than ASCII \f(CW0\fR to \f(CW9\fR (and ASCII \f(CW\*(C`a\*(C'\fR to \f(CW\*(C`f\*(C'\fR for hexadecimal).
+To get safe conversions from any Unicode string, use
+"\fBnum()\fR" in Unicode::UCD.
+.SS "Questions With Answers"
+.IX Subsection "Questions With Answers"
+.IP \(bu 4
+Will My Old Scripts Break?
+.Sp
+Very probably not.  Unless you are generating Unicode characters
+somehow, old behaviour should be preserved.  About the only behaviour
+that has changed and which could start generating Unicode is the old
+behaviour of \f(CWchr()\fR where supplying an argument more than 255
+produced a character modulo 255.  \f(CWchr(300)\fR, for example, was equal
+to \f(CWchr(45)\fR or "\-" (in ASCII), now it is LATIN CAPITAL LETTER I WITH
+BREVE.
+.IP \(bu 4
+How Do I Make My Scripts Work With Unicode?
+.Sp
+Very little work should be needed since nothing changes until you
+generate Unicode data.  The most important thing is getting input as
+Unicode; for that, see the earlier I/O discussion.
+To get full seamless Unicode support, add
+\&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR (or \f(CW\*(C`use v5.12\*(C'\fR or higher) to your
+script.
+.IP \(bu 4
+How Do I Know Whether My String Is In Unicode?
+.Sp
+You shouldn't have to care.  But you may if your Perl is before 5.14.0
+or you haven't specified \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR or \f(CWuse
+5.012\fR (or higher) because otherwise the rules for the code points
+in the range 128 to 255 are different depending on
+whether the string they are contained within is in Unicode or not.
+(See "When Unicode Does Not Happen" in perlunicode.)
+.Sp
+To determine if a string is in Unicode, use:
+.Sp
+.Vb 1
+\&    print utf8::is_utf8($string) ? 1 : 0, "\en";
+.Ve
+.Sp
+But note that this doesn't mean that any of the characters in the
+string are necessary UTF\-8 encoded, or that any of the characters have
+code points greater than 0xFF (255) or even 0x80 (128), or that the
+string has any characters at all.  All the \f(CWis_utf8()\fR does is to
+return the value of the internal "utf8ness" flag attached to the
+\&\f(CW$string\fR.  If the flag is off, the bytes in the scalar are interpreted
+as a single byte encoding.  If the flag is on, the bytes in the scalar
+are interpreted as the (variable-length, potentially multi-byte) UTF\-8 encoded
+code points of the characters.  Bytes added to a UTF\-8 encoded string are
+automatically upgraded to UTF\-8.  If mixed non\-UTF\-8 and UTF\-8 scalars
+are merged (double-quoted interpolation, explicit concatenation, or
+printf/sprintf parameter substitution), the result will be UTF\-8 encoded
+as if copies of the byte strings were upgraded to UTF\-8: for example,
+.Sp
+.Vb 3
+\&    $a = "ab\ex80c";
+\&    $b = "\ex{100}";
+\&    print "$a = $b\en";
+.Ve
+.Sp
+the output string will be UTF\-8\-encoded \f(CW\*(C`ab\ex80c = \ex{100}\en\*(C'\fR, but
+\&\f(CW$a\fR will stay byte-encoded.
+.Sp
+Sometimes you might really need to know the byte length of a string
+instead of the character length. For that use the \f(CW\*(C`bytes\*(C'\fR pragma
+and the \f(CWlength()\fR function:
+.Sp
+.Vb 6
+\&    my $unicode = chr(0x100);
+\&    print length($unicode), "\en"; # will print 1
+\&    use bytes;
+\&    print length($unicode), "\en"; # will print 2
+\&                                  # (the 0xC4 0x80 of the UTF\-8)
+\&    no bytes;
+.Ve
+.IP \(bu 4
+How Do I Find Out What Encoding a File Has?
+.Sp
+You might try Encode::Guess, but it has a number of limitations.
+.IP \(bu 4
+How Do I Detect Data That's Not Valid In a Particular Encoding?
+.Sp
+Use the \f(CW\*(C`Encode\*(C'\fR package to try converting it.
+For example,
+.Sp
+.Vb 1
+\&    use Encode \*(Aqdecode\*(Aq;
+\&
+\&    if (eval { decode(\*(AqUTF\-8\*(Aq, $string, Encode::FB_CROAK); 1 }) {
+\&        # $string is valid UTF\-8
+\&    } else {
+\&        # $string is not valid UTF\-8
+\&    }
+.Ve
+.Sp
+Or use \f(CW\*(C`unpack\*(C'\fR to try decoding it:
+.Sp
+.Vb 2
+\&    use warnings;
+\&    @chars = unpack("C0U*", $string_of_bytes_that_I_think_is_utf8);
+.Ve
+.Sp
+If invalid, a \f(CW\*(C`Malformed UTF\-8 character\*(C'\fR warning is produced. The "C0" means
+"process the string character per character".  Without that, the
+\&\f(CW\*(C`unpack("U*", ...)\*(C'\fR would work in \f(CW\*(C`U0\*(C'\fR mode (the default if the format
+string starts with \f(CW\*(C`U\*(C'\fR) and it would return the bytes making up the UTF\-8
+encoding of the target string, something that will always work.
+.IP \(bu 4
+How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?
+.Sp
+This probably isn't as useful as you might think.
+Normally, you shouldn't need to.
+.Sp
+In one sense, what you are asking doesn't make much sense: encodings
+are for characters, and binary data are not "characters", so converting
+"data" into some encoding isn't meaningful unless you know in what
+character set and encoding the binary data is in, in which case it's
+not just binary data, now is it?
+.Sp
+If you have a raw sequence of bytes that you know should be
+interpreted via a particular encoding, you can use \f(CW\*(C`Encode\*(C'\fR:
+.Sp
+.Vb 2
+\&    use Encode \*(Aqfrom_to\*(Aq;
+\&    from_to($data, "iso\-8859\-1", "UTF\-8"); # from latin\-1 to UTF\-8
+.Ve
+.Sp
+The call to \f(CWfrom_to()\fR changes the bytes in \f(CW$data\fR, but nothing
+material about the nature of the string has changed as far as Perl is
+concerned.  Both before and after the call, the string \f(CW$data\fR
+contains just a bunch of 8\-bit bytes. As far as Perl is concerned,
+the encoding of the string remains as "system-native 8\-bit bytes".
+.Sp
+You might relate this to a fictional 'Translate' module:
+.Sp
+.Vb 4
+\&   use Translate;
+\&   my $phrase = "Yes";
+\&   Translate::from_to($phrase, \*(Aqenglish\*(Aq, \*(Aqdeutsch\*(Aq);
+\&   ## phrase now contains "Ja"
+.Ve
+.Sp
+The contents of the string changes, but not the nature of the string.
+Perl doesn't know any more after the call than before that the
+contents of the string indicates the affirmative.
+.Sp
+Back to converting data.  If you have (or want) data in your system's
+native 8\-bit encoding (e.g. Latin\-1, EBCDIC, etc.), you can use
+pack/unpack to convert to/from Unicode.
+.Sp
+.Vb 2
+\&    $native_string  = pack("W*", unpack("U*", $Unicode_string));
+\&    $Unicode_string = pack("U*", unpack("W*", $native_string));
+.Ve
+.Sp
+If you have a sequence of bytes you \fBknow\fR is valid UTF\-8,
+but Perl doesn't know it yet, you can make Perl a believer, too:
+.Sp
+.Vb 2
+\&    $Unicode = $bytes;
+\&    utf8::decode($Unicode);
+.Ve
+.Sp
+or:
+.Sp
+.Vb 1
+\&    $Unicode = pack("U0a*", $bytes);
+.Ve
+.Sp
+You can find the bytes that make up a UTF\-8 sequence with
+.Sp
+.Vb 1
+\&    @bytes = unpack("C*", $Unicode_string)
+.Ve
+.Sp
+and you can create well-formed Unicode with
+.Sp
+.Vb 1
+\&    $Unicode_string = pack("U*", 0xff, ...)
+.Ve
+.IP \(bu 4
+How Do I Display Unicode?  How Do I Input Unicode?
+.Sp
+See <http://www.alanwood.net/unicode/> and
+<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
+.IP \(bu 4
+How Does Unicode Work With Traditional Locales?
+.Sp
+If your locale is a UTF\-8 locale, starting in Perl v5.26, Perl works
+well for all categories; before this, starting with Perl v5.20, it works
+for all categories but \f(CW\*(C`LC_COLLATE\*(C'\fR, which deals with
+sorting and the \f(CW\*(C`cmp\*(C'\fR operator.  But note that the standard
+\&\f(CW\*(C`Unicode::Collate\*(C'\fR and \f(CW\*(C`Unicode::Collate::Locale\*(C'\fR modules offer
+much more powerful solutions to collation issues, and work on earlier
+releases.
+.Sp
+For other locales, starting in Perl 5.16, you can specify
+.Sp
+.Vb 1
+\&    use locale \*(Aq:not_characters\*(Aq;
+.Ve
+.Sp
+to get Perl to work well with them.  The catch is that you
+have to translate from the locale character set to/from Unicode
+yourself.  See "Unicode I/O" above for how to
+.Sp
+.Vb 1
+\&    use open \*(Aq:locale\*(Aq;
+.Ve
+.Sp
+to accomplish this, but full details are in "Unicode and
+UTF\-8" in perllocale, including gotchas that happen if you don't specify
+\&\f(CW\*(C`:not_characters\*(C'\fR.
+.SS "Hexadecimal Notation"
+.IX Subsection "Hexadecimal Notation"
+The Unicode standard prefers using hexadecimal notation because
+that more clearly shows the division of Unicode into blocks of 256 characters.
+Hexadecimal is also simply shorter than decimal.  You can use decimal
+notation, too, but learning to use hexadecimal just makes life easier
+with the Unicode standard.  The \f(CW\*(C`U+HHHH\*(C'\fR notation uses hexadecimal,
+for example.
+.PP
+The \f(CW\*(C`0x\*(C'\fR prefix means a hexadecimal number, the digits are 0\-9 \fIand\fR
+a\-f (or A\-F, case doesn't matter).  Each hexadecimal digit represents
+four bits, or half a byte.  \f(CW\*(C`print 0x..., "\en"\*(C'\fR will show a
+hexadecimal number in decimal, and \f(CW\*(C`printf "%x\en", $decimal\*(C'\fR will
+show a decimal number in hexadecimal.  If you have just the
+"hex digits" of a hexadecimal number, you can use the \f(CWhex()\fR function.
+.PP
+.Vb 6
+\&    print 0x0009, "\en";    # 9
+\&    print 0x000a, "\en";    # 10
+\&    print 0x000f, "\en";    # 15
+\&    print 0x0010, "\en";    # 16
+\&    print 0x0011, "\en";    # 17
+\&    print 0x0100, "\en";    # 256
+\&
+\&    print 0x0041, "\en";    # 65
+\&
+\&    printf "%x\en",  65;    # 41
+\&    printf "%#x\en", 65;    # 0x41
+\&
+\&    print hex("41"), "\en"; # 65
+.Ve
+.SS "Further Resources"
+.IX Subsection "Further Resources"
+.IP \(bu 4
+Unicode Consortium
+.Sp
+<https://www.unicode.org/>
+.IP \(bu 4
+Unicode FAQ
+.Sp
+<https://www.unicode.org/faq/>
+.IP \(bu 4
+Unicode Glossary
+.Sp
+<https://www.unicode.org/glossary/>
+.IP \(bu 4
+Unicode Recommended Reading List
+.Sp
+The Unicode Consortium has a list of articles and books, some of which
+give a much more in depth treatment of Unicode:
+<http://unicode.org/resources/readinglist.html>
+.IP \(bu 4
+Unicode Useful Resources
+.Sp
+<https://www.unicode.org/unicode/onlinedat/resources.html>
+.IP \(bu 4
+Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications
+.Sp
+<http://www.alanwood.net/unicode/>
+.IP \(bu 4
+UTF\-8 and Unicode FAQ for Unix/Linux
+.Sp
+<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
+.IP \(bu 4
+Legacy Character Sets
+.Sp
+<http://www.czyborra.com/>
+<http://www.eki.ee/letter/>
+.IP \(bu 4
+You can explore various information from the Unicode data files using
+the \f(CW\*(C`Unicode::UCD\*(C'\fR module.
+.SH "UNICODE IN OLDER PERLS"
+.IX Header "UNICODE IN OLDER PERLS"
+If you cannot upgrade your Perl to 5.8.0 or later, you can still
+do some Unicode processing by using the modules \f(CW\*(C`Unicode::String\*(C'\fR,
+\&\f(CW\*(C`Unicode::Map8\*(C'\fR, and \f(CW\*(C`Unicode::Map\*(C'\fR, available from CPAN.
+If you have the GNU recode installed, you can also use the
+Perl front-end \f(CW\*(C`Convert::Recode\*(C'\fR for character conversions.
+.PP
+The following are fast conversions from ISO 8859\-1 (Latin\-1) bytes
+to UTF\-8 bytes and back, the code works even with older Perl 5 versions.
+.PP
+.Vb 2
+\&    # ISO 8859\-1 to UTF\-8
+\&    s/([\ex80\-\exFF])/chr(0xC0|ord($1)>>6).chr(0x80|ord($1)&0x3F)/eg;
+\&
+\&    # UTF\-8 to ISO 8859\-1
+\&    s/([\exC2\exC3])([\ex80\-\exBF])/chr(ord($1)<<6&0xC0|ord($2)&0x3F)/eg;
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlunitut, perlunicode, Encode, open, utf8, bytes,
+perlretut, perlrun, Unicode::Collate, Unicode::Normalize,
+Unicode::UCD
+.SH ACKNOWLEDGMENTS
+.IX Header "ACKNOWLEDGMENTS"
+Thanks to the kind readers of the perl5\-porters@perl.org,
+perl\-unicode@perl.org, linux\-utf8@nl.linux.org, and unicore@unicode.org
+mailing lists for their valuable feedback.
+.SH "AUTHOR, COPYRIGHT, AND LICENSE"
+.IX Header "AUTHOR, COPYRIGHT, AND LICENSE"
+Copyright 2001\-2011 Jarkko Hietaniemi <jhi@iki.fi>.
+Now maintained by Perl 5 Porters.
+.PP
+This document may be distributed under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/perluniprops.1 b/upstream/mageia-cauldron/man1/perluniprops.1
new file mode 100644
index 00000000..5fa553c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perluniprops.1
@@ -0,0 +1,7880 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNIPROPS 1"
+.TH PERLUNIPROPS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perluniprops \- Index of Unicode Version 15.0.0 character properties in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides information about the portion of the Unicode database
+that deals with character properties, that is the portion that is defined on
+single code points.  ("Other information in the Unicode data base"
+below briefly mentions other data that Unicode provides.)
+.PP
+Perl can provide access to all non-provisional Unicode character properties,
+though not all are enabled by default.  The omitted ones are the Unihan
+properties and certain
+deprecated or Unicode-internal properties.  (An installation may choose to
+recompile Perl's tables to change this.  See "Unicode character
+properties that are NOT accepted by Perl".)
+.PP
+For most purposes, access to Unicode properties from the Perl core is through
+regular expression matches, as described in the next section.
+For some special purposes, and to access the properties that are not suitable
+for regular expression matching, all the Unicode character properties that
+Perl handles are accessible via the standard Unicode::UCD module, as
+described in the section "Properties accessible through Unicode::UCD".
+.PP
+Perl also provides some additional extensions and short-cut synonyms
+for Unicode properties.
+.PP
+This document merely lists all available properties and does not attempt to
+explain what each property really means.  There is a brief description of each
+Perl extension; see "Other Properties" in perlunicode for more information on
+these.  There is some detail about Blocks, Scripts, General_Category,
+and Bidi_Class in perlunicode, but to find out about the intricacies of the
+official Unicode properties, refer to the Unicode standard.  A good starting
+place is <http://www.unicode.org/reports/tr44/>.
+.PP
+Note that you can define your own properties; see
+"User-Defined Character Properties" in perlunicode.
+.ie n .SH "Properties accessible through ""\ep{}"" and ""\eP{}"""
+.el .SH "Properties accessible through \f(CW\ep{}\fP and \f(CW\eP{}\fP"
+.IX Header "Properties accessible through p{} and P{}"
+The Perl regular expression \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR constructs give access to
+most of the Unicode character properties.  The table below shows all these
+constructs, both single and compound forms.
+.PP
+\&\fBCompound forms\fR consist of two components, separated by an equals sign or a
+colon.  The first component is the property name, and the second component is
+the particular value of the property to match against, for example,
+\&\f(CW\*(C`\ep{Script_Extensions: Greek}\*(C'\fR and \f(CW\*(C`\ep{Script_Extensions=Greek}\*(C'\fR both mean
+to match characters whose Script_Extensions property value is Greek.
+(\f(CW\*(C`Script_Extensions\*(C'\fR is an improved version of the \f(CW\*(C`Script\*(C'\fR property.)
+.PP
+\&\fBSingle forms\fR, like \f(CW\*(C`\ep{Greek}\*(C'\fR, are mostly Perl-defined shortcuts for
+their equivalent compound forms.  The table shows these equivalences.  (In our
+example, \f(CW\*(C`\ep{Greek}\*(C'\fR is a just a shortcut for
+\&\f(CW\*(C`\ep{Script_Extensions=Greek}\*(C'\fR).  There are also a few Perl-defined single
+forms that are not shortcuts for a compound form.  One such is \f(CW\*(C`\ep{Word}\*(C'\fR.
+These are also listed in the table.
+.PP
+In parsing these constructs, Perl always ignores Upper/lower case differences
+everywhere within the {braces}.  Thus \f(CW\*(C`\ep{Greek}\*(C'\fR means the same thing as
+\&\f(CW\*(C`\ep{greek}\*(C'\fR.  But note that changing the case of the \f(CW"p"\fR or \f(CW"P"\fR before
+the left brace completely changes the meaning of the construct, from "match"
+(for \f(CW\*(C`\ep{}\*(C'\fR) to "doesn't match" (for \f(CW\*(C`\eP{}\*(C'\fR).  Casing in this document is
+for improved legibility.
+.PP
+Also, white space, hyphens, and underscores are normally ignored
+everywhere between the {braces}, and hence can be freely added or removed
+even if the \f(CW\*(C`/x\*(C'\fR modifier hasn't been specified on the regular expression.
+But in the table below a '\fBT\fR' at the beginning of an entry
+means that tighter (stricter) rules are used for that entry:
+.RS 4
+.ie n .IP "Single form (""\ep{name}"") tighter rules:" 4
+.el .IP "Single form (\f(CW\ep{name}\fR) tighter rules:" 4
+.IX Item "Single form (p{name}) tighter rules:"
+White space, hyphens, and underscores ARE significant
+except for:
+.RS 4
+.IP \(bu 4
+white space adjacent to a non-word character
+.IP \(bu 4
+underscores separating digits in numbers
+.RE
+.RS 4
+.Sp
+That means, for example, that you can freely add or remove white space
+adjacent to (but within) the braces without affecting the meaning.
+.RE
+.ie n .IP "Compound form (""\ep{name=value}"" or ""\ep{name:value}"") tighter rules:" 4
+.el .IP "Compound form (\f(CW\ep{name=value}\fR or \f(CW\ep{name:value}\fR) tighter rules:" 4
+.IX Item "Compound form (p{name=value} or p{name:value}) tighter rules:"
+The tighter rules given above for the single form apply to everything to the
+right of the colon or equals; the looser rules still apply to everything to
+the left.
+.Sp
+That means, for example, that you can freely add or remove white space
+adjacent to (but within) the braces and the colon or equal sign.
+.RE
+.RS 4
+.RE
+.PP
+Some properties are considered obsolete by Unicode, but still available.
+There are several varieties of obsolescence:
+.RS 4
+.IP Stabilized 4
+.IX Item "Stabilized"
+A property may be stabilized.  Such a determination does not indicate
+that the property should or should not be used; instead it is a declaration
+that the property will not be maintained nor extended for newly encoded
+characters.  Such properties are marked with an '\fBS\fR' in the
+table.
+.IP Deprecated 4
+.IX Item "Deprecated"
+A property may be deprecated, perhaps because its original intent
+has been replaced by another property, or because its specification was
+somehow defective.  This means that its use is strongly
+discouraged, so much so that a warning will be issued if used, unless the
+regular expression is in the scope of a \f(CW\*(C`no\ warnings\ \*(Aqdeprecated\*(Aq\*(C'\fR
+statement.  A '\fBD\fR' flags each such entry in the table, and
+the entry there for the longest, most descriptive version of the property will
+give the reason it is deprecated, and perhaps advice.  Perl may issue such a
+warning, even for properties that aren't officially deprecated by Unicode,
+when there used to be characters or code points that were matched by them, but
+no longer.  This is to warn you that your program may not work like it did on
+earlier Unicode releases.
+.Sp
+A deprecated property may be made unavailable in a future Perl version, so it
+is best to move away from them.
+.Sp
+A deprecated property may also be stabilized, but this fact is not shown.
+.IP Obsolete 4
+.IX Item "Obsolete"
+Properties marked with an '\fBO\fR' in the table are considered (plain)
+obsolete.  Generally this designation is given to properties that Unicode once
+used for internal purposes (but not any longer).
+.IP Discouraged 4
+.IX Item "Discouraged"
+This is not actually a Unicode-specified obsolescence, but applies to certain
+Perl extensions that are present for backwards compatibility, but are
+discouraged from being used.  These are not obsolete, but their meanings are
+not stable.  Future Unicode versions could force any of these extensions to be
+removed without warning, replaced by another property with the same name that
+means something different.  An '\fBX\fR' flags each such entry in the
+table.  Use the equivalent shown instead.
+.Sp
+In particular, matches in the Block property have single forms
+defined by Perl that begin with \f(CW"In_"\fR, \f(CW\*(C`"Is_\*(C'\fR, or even with no prefix at
+all,  Like all \fBDISCOURAGED\fR forms, these are not stable.  For example,
+\&\f(CW\*(C`\ep{Block=Deseret}\*(C'\fR can currently be written as \f(CW\*(C`\ep{In_Deseret}\*(C'\fR,
+\&\f(CW\*(C`\ep{Is_Deseret}\*(C'\fR, or \f(CW\*(C`\ep{Deseret}\*(C'\fR.  But, a new Unicode version may
+come along that would force Perl to change the meaning of one or more of
+these, and your program would no longer be correct.  Currently there are no
+such conflicts with the form that begins \f(CW"In_"\fR, but there are many with the
+other two shortcuts, and Unicode continues to define new properties that begin
+with \f(CW"In"\fR, so it's quite possible that a conflict will occur in the future.
+The compound form is guaranteed to not become obsolete, and its meaning is
+clearer anyway.  See "Blocks" in perlunicode for more information about this.
+.Sp
+User-defined properties must begin with "In" or "Is".  These override any
+Unicode property of the same name.
+.RE
+.RS 4
+.RE
+.PP
+The table below has two columns.  The left column contains the \f(CW\*(C`\ep{}\*(C'\fR
+constructs to look up, possibly preceded by the flags mentioned above; and
+the right column contains information about them, like a description, or
+synonyms.  The table shows both the single and compound forms for each
+property that has them.  If the left column is a short name for a property,
+the right column will give its longer, more descriptive name; and if the left
+column is the longest name, the right column will show any equivalent shortest
+name, in both single and compound forms if applicable.
+.PP
+If braces are not needed to specify a property (e.g., \f(CW\*(C`\epL\*(C'\fR), the left
+column contains both forms, with and without braces.
+.PP
+The right column will also caution you if a property means something different
+than what might normally be expected.
+.PP
+All single forms are Perl extensions; a few compound forms are as well, and
+are noted as such.
+.PP
+Numbers in (parentheses) indicate the total number of Unicode code points
+matched by the property.  For the entries that give the longest, most
+descriptive version of the property, the count is followed by a list of some
+of the code points matched by it.  The list includes all the matched
+characters in the 0\-255 range, enclosed in the familiar [brackets] the same as
+a regular expression bracketed character class.  Following that, the next few
+higher matching ranges are also given.  To avoid visual ambiguity, the SPACE
+character is represented as \f(CW\*(C`\ex20\*(C'\fR.
+.PP
+For emphasis, those properties that match no code points at all are listed as
+well in a separate section following the table.
+.PP
+Most properties match the same code points regardless of whether \f(CW"/i"\fR
+case-insensitive matching is specified or not.  But a few properties are
+affected.  These are shown with the notation \f(CW\*(C`(/i=\ \fR\f(CIother_property\fR\f(CW)\*(C'\fR
+in the second column.  Under case-insensitive matching they match the
+same code pode points as the property \fIother_property\fR.
+.PP
+There is no description given for most non-Perl defined properties (See
+<http://www.unicode.org/reports/tr44/> for that).
+.PP
+For compactness, '\fB*\fR' is used as a wildcard instead of showing all possible
+combinations.  For example, entries like:
+.PP
+.Vb 1
+\& \ep{Gc: *}                                  \ep{General_Category: *}
+.Ve
+.PP
+mean that 'Gc' is a synonym for 'General_Category', and anything that is valid
+for the latter is also valid for the former.  Similarly,
+.PP
+.Vb 1
+\& \ep{Is_*}                                   \ep{*}
+.Ve
+.PP
+means that if and only if, for example, \f(CW\*(C`\ep{Foo}\*(C'\fR exists, then
+\&\f(CW\*(C`\ep{Is_Foo}\*(C'\fR and \f(CW\*(C`\ep{IsFoo}\*(C'\fR are also valid and all mean the same thing.
+And similarly, \f(CW\*(C`\ep{Foo=Bar}\*(C'\fR means the same as \f(CW\*(C`\ep{Is_Foo=Bar}\*(C'\fR and
+\&\f(CW\*(C`\ep{IsFoo=Bar}\*(C'\fR.  "*" here is restricted to something not beginning with an
+underscore.
+.PP
+Also, in binary properties, 'Yes', 'T', and 'True' are all synonyms for 'Y'.
+And 'No', 'F', and 'False' are all synonyms for 'N'.  The table shows 'Y*' and
+\&'N*' to indicate this, and doesn't have separate entries for the other
+possibilities.  Note that not all properties which have values 'Yes' and 'No'
+are binary, and they have all their values spelled out without using this wild
+card, and a \f(CW\*(C`NOT\*(C'\fR clause in their description that highlights their not being
+binary.  These also require the compound form to match them, whereas true
+binary properties have both single and compound forms available.
+.PP
+Note that all non-essential underscores are removed in the display of the
+short names below.
+.PP
+\&\fBLegend summary:\fR
+.IP "\fB*\fR is a wild-card" 4
+.IX Item "* is a wild-card"
+.PD 0
+.IP "\fB(\ed+)\fR in the info column gives the number of Unicode code points matched by this property." 4
+.IX Item "(d+) in the info column gives the number of Unicode code points matched by this property."
+.IP "\fBD\fR means this is deprecated." 4
+.IX Item "D means this is deprecated."
+.IP "\fBO\fR means this is obsolete." 4
+.IX Item "O means this is obsolete."
+.IP "\fBS\fR means this is stabilized." 4
+.IX Item "S means this is stabilized."
+.IP "\fBT\fR means tighter (stricter) name matching applies." 4
+.IX Item "T means tighter (stricter) name matching applies."
+.IP "\fBX\fR means use of this form is discouraged, and may not be stable." 4
+.IX Item "X means use of this form is discouraged, and may not be stable."
+.PD
+.PP
+.Vb 1
+\&       NAME                           INFO
+\&
+\&   \ep{Adlam}               \ep{Script_Extensions=Adlam} (Short:
+\&                             \ep{Adlm}; NOT \ep{Block=Adlam}) (90)
+\&   \ep{Adlm}                \ep{Adlam} (= \ep{Script_Extensions=Adlam})
+\&                             (NOT \ep{Block=Adlam}) (90)
+\& X \ep{Aegean_Numbers}      \ep{Block=Aegean_Numbers} (64)
+\& T \ep{Age: 1.1}            \ep{Age=V1_1} (33_979)
+\&   \ep{Age: V1_1}           Code point\*(Aqs usage introduced in version
+\&                             1.1 (33_979: U+0000..01F5, U+01FA..0217,
+\&                             U+0250..02A8, U+02B0..02DE,
+\&                             U+02E0..02E9, U+0300..0345 ...)
+\& T \ep{Age: 2.0}            \ep{Age=V2_0} (144_521)
+\&   \ep{Age: V2_0}           Code point\*(Aqs usage was introduced in
+\&                             version 2.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (144_521: U+0591..05A1,
+\&                             U+05A3..05AF, U+05C4, U+0F00..0F47,
+\&                             U+0F49..0F69, U+0F71..0F8B ...)
+\& T \ep{Age: 2.1}            \ep{Age=V2_1} (2)
+\&   \ep{Age: V2_1}           Code point\*(Aqs usage was introduced in
+\&                             version 2.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (2: U+20AC, U+FFFC)
+\& T \ep{Age: 3.0}            \ep{Age=V3_0} (10_307)
+\&   \ep{Age: V3_0}           Code point\*(Aqs usage was introduced in
+\&                             version 3.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (10_307: U+01F6..01F9,
+\&                             U+0218..021F, U+0222..0233,
+\&                             U+02A9..02AD, U+02DF, U+02EA..02EE ...)
+\& T \ep{Age: 3.1}            \ep{Age=V3_1} (44_978)
+\&   \ep{Age: V3_1}           Code point\*(Aqs usage was introduced in
+\&                             version 3.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (44_978: U+03F4..03F5,
+\&                             U+FDD0..FDEF, U+10300..1031E,
+\&                             U+10320..10323, U+10330..1034A,
+\&                             U+10400..10425 ...)
+\& T \ep{Age: 3.2}            \ep{Age=V3_2} (1016)
+\&   \ep{Age: V3_2}           Code point\*(Aqs usage was introduced in
+\&                             version 3.2; See also Property
+\&                             \*(AqPresent_In\*(Aq (1016: U+0220, U+034F,
+\&                             U+0363..036F, U+03D8..03D9, U+03F6,
+\&                             U+048A..048B ...)
+\& T \ep{Age: 4.0}            \ep{Age=V4_0} (1226)
+\&   \ep{Age: V4_0}           Code point\*(Aqs usage was introduced in
+\&                             version 4.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (1226: U+0221,
+\&                             U+0234..0236, U+02AE..02AF,
+\&                             U+02EF..02FF, U+0350..0357, U+035D..035F
+\&                             ...)
+\& T \ep{Age: 4.1}            \ep{Age=V4_1} (1273)
+\&   \ep{Age: V4_1}           Code point\*(Aqs usage was introduced in
+\&                             version 4.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (1273: U+0237..0241,
+\&                             U+0358..035C, U+03FC..03FF,
+\&                             U+04F6..04F7, U+05A2, U+05C5..05C7 ...)
+\& T \ep{Age: 5.0}            \ep{Age=V5_0} (1369)
+\&   \ep{Age: V5_0}           Code point\*(Aqs usage was introduced in
+\&                             version 5.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (1369: U+0242..024F,
+\&                             U+037B..037D, U+04CF, U+04FA..04FF,
+\&                             U+0510..0513, U+05BA ...)
+\& T \ep{Age: 5.1}            \ep{Age=V5_1} (1624)
+\&   \ep{Age: V5_1}           Code point\*(Aqs usage was introduced in
+\&                             version 5.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (1624: U+0370..0373,
+\&                             U+0376..0377, U+03CF, U+0487,
+\&                             U+0514..0523, U+0606..060A ...)
+\& T \ep{Age: 5.2}            \ep{Age=V5_2} (6648)
+\&   \ep{Age: V5_2}           Code point\*(Aqs usage was introduced in
+\&                             version 5.2; See also Property
+\&                             \*(AqPresent_In\*(Aq (6648: U+0524..0525,
+\&                             U+0800..082D, U+0830..083E, U+0900,
+\&                             U+094E, U+0955 ...)
+\& T \ep{Age: 6.0}            \ep{Age=V6_0} (2088)
+\&   \ep{Age: V6_0}           Code point\*(Aqs usage was introduced in
+\&                             version 6.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (2088: U+0526..0527,
+\&                             U+0620, U+065F, U+0840..085B, U+085E,
+\&                             U+093A..093B ...)
+\& T \ep{Age: 6.1}            \ep{Age=V6_1} (732)
+\&   \ep{Age: V6_1}           Code point\*(Aqs usage was introduced in
+\&                             version 6.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (732: U+058F, U+0604,
+\&                             U+08A0, U+08A2..08AC, U+08E4..08FE,
+\&                             U+0AF0 ...)
+\& T \ep{Age: 6.2}            \ep{Age=V6_2} (1)
+\&   \ep{Age: V6_2}           Code point\*(Aqs usage was introduced in
+\&                             version 6.2; See also Property
+\&                             \*(AqPresent_In\*(Aq (1: U+20BA)
+\& T \ep{Age: 6.3}            \ep{Age=V6_3} (5)
+\&   \ep{Age: V6_3}           Code point\*(Aqs usage was introduced in
+\&                             version 6.3; See also Property
+\&                             \*(AqPresent_In\*(Aq (5: U+061C, U+2066..2069)
+\& T \ep{Age: 7.0}            \ep{Age=V7_0} (2834)
+\&   \ep{Age: V7_0}           Code point\*(Aqs usage was introduced in
+\&                             version 7.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (2834: U+037F,
+\&                             U+0528..052F, U+058D..058E, U+0605,
+\&                             U+08A1, U+08AD..08B2 ...)
+\& T \ep{Age: 8.0}            \ep{Age=V8_0} (7716)
+\&   \ep{Age: V8_0}           Code point\*(Aqs usage was introduced in
+\&                             version 8.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (7716: U+08B3..08B4,
+\&                             U+08E3, U+0AF9, U+0C5A, U+0D5F, U+13F5
+\&                             ...)
+\& T \ep{Age: 9.0}            \ep{Age=V9_0} (7500)
+\&   \ep{Age: V9_0}           Code point\*(Aqs usage was introduced in
+\&                             version 9.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (7500: U+08B6..08BD,
+\&                             U+08D4..08E2, U+0C80, U+0D4F,
+\&                             U+0D54..0D56, U+0D58..0D5E ...)
+\& T \ep{Age: 10.0}           \ep{Age=V10_0} (8518)
+\&   \ep{Age: V10_0}          Code point\*(Aqs usage was introduced in
+\&                             version 10.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (8518: U+0860..086A,
+\&                             U+09FC..09FD, U+0AFA..0AFF, U+0D00,
+\&                             U+0D3B..0D3C, U+1CF7 ...)
+\& T \ep{Age: 11.0}           \ep{Age=V11_0} (684)
+\&   \ep{Age: V11_0}          Code point\*(Aqs usage was introduced in
+\&                             version 11.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (684: U+0560, U+0588,
+\&                             U+05EF, U+07FD..07FF, U+08D3, U+09FE ...)
+\& T \ep{Age: 12.0}           \ep{Age=V12_0} (554)
+\&   \ep{Age: V12_0}          Code point\*(Aqs usage was introduced in
+\&                             version 12.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (554: U+0C77, U+0E86,
+\&                             U+0E89, U+0E8C, U+0E8E..0E93, U+0E98 ...)
+\& T \ep{Age: 12.1}           \ep{Age=V12_1} (1)
+\&   \ep{Age: V12_1}          Code point\*(Aqs usage was introduced in
+\&                             version 12.1; See also Property
+\&                             \*(AqPresent_In\*(Aq (1: U+32FF)
+\& T \ep{Age: 13.0}           \ep{Age=V13_0} (5930)
+\&   \ep{Age: V13_0}          Code point\*(Aqs usage was introduced in
+\&                             version 13.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (5930: U+08BE..08C7,
+\&                             U+0B55, U+0D04, U+0D81, U+1ABF..1AC0,
+\&                             U+2B97 ...)
+\& T \ep{Age: 14.0}           \ep{Age=V14_0} (838)
+\&   \ep{Age: V14_0}          Code point\*(Aqs usage was introduced in
+\&                             version 14.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (838: U+061D, U+0870..088E,
+\&                             U+0890..0891, U+0898..089F, U+08B5,
+\&                             U+08C8..08D2 ...)
+\& T \ep{Age: 15.0}           \ep{Age=V15_0} (4489)
+\&   \ep{Age: V15_0}          Code point\*(Aqs usage was introduced in
+\&                             version 15.0; See also Property
+\&                             \*(AqPresent_In\*(Aq (4489: U+0CF3, U+0ECE,
+\&                             U+10EFD..10EFF, U+1123F..11241,
+\&                             U+11B00..11B09, U+11F00..11F10 ...)
+\&   \ep{Age: NA}             \ep{Age=Unassigned} (825_279 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Age: Unassigned}     Code point\*(Aqs usage has not been assigned
+\&                             in any Unicode release thus far.
+\& (Short: \ep{Age=NA}) (825_279 plus all above\-Unicode code points:
+\&                             U+0378..0379, U+0380..0383, U+038B,
+\&                             U+038D, U+03A2, U+0530 ...)
+\&   \ep{Aghb}                \ep{Caucasian_Albanian} (=
+\&                             \ep{Script_Extensions=
+\&                             Caucasian_Albanian}) (NOT \ep{Block=
+\&                             Caucasian_Albanian}) (53)
+\&   \ep{AHex}                \ep{PosixXDigit} (= \ep{ASCII_Hex_Digit=Y})
+\&                             (22)
+\&   \ep{AHex: *}             \ep{ASCII_Hex_Digit: *}
+\&   \ep{Ahom}                \ep{Script_Extensions=Ahom} (NOT \ep{Block=
+\&                             Ahom}) (65)
+\& X \ep{Alchemical}          \ep{Alchemical_Symbols} (= \ep{Block=
+\&                             Alchemical_Symbols}) (128)
+\& X \ep{Alchemical_Symbols}  \ep{Block=Alchemical_Symbols} (Short:
+\&                             \ep{InAlchemical}) (128)
+\&   \ep{All}                 All code points, including those above
+\&                             Unicode.  Same as qr/./s (1_114_112 plus
+\&                             all above\-Unicode code points:
+\&                             U+0000..infinity)
+\&   \ep{Alnum}               \ep{XPosixAlnum} (138_445)
+\&   \ep{Alpha}               \ep{XPosixAlpha} (= \ep{Alphabetic=Y})
+\&                             (137_765)
+\&   \ep{Alpha: *}            \ep{Alphabetic: *}
+\&   \ep{Alphabetic}          \ep{XPosixAlpha} (= \ep{Alphabetic=Y})
+\&                             (137_765)
+\&   \ep{Alphabetic: N*}      (Short: \ep{Alpha=N}, \eP{Alpha}) (976_347
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=
+\&                             >?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4
+\&                             \exb6\-\exb9\exbb\-\exbf\exd7\exf7],
+\&                             U+02C2..02C5, U+02D2..02DF,
+\&                             U+02E5..02EB, U+02ED, U+02EF..0344 ...)
+\&   \ep{Alphabetic: Y*}      (Short: \ep{Alpha=Y}, \ep{Alpha}) (137_765:
+\&                             [A\-Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6
+\&                             \exf8\-\exff], U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\& X \ep{Alphabetic_PF}       \ep{Alphabetic_Presentation_Forms} (=
+\&                             \ep{Block=Alphabetic_Presentation_Forms})
+\&                             (80)
+\& X \ep{Alphabetic_Presentation_Forms} \ep{Block=
+\&                             Alphabetic_Presentation_Forms} (Short:
+\&                             \ep{InAlphabeticPF}) (80)
+\&   \ep{Anatolian_Hieroglyphs} \ep{Script_Extensions=
+\&                             Anatolian_Hieroglyphs} (Short: \ep{Hluw};
+\&                             NOT \ep{Block=Anatolian_Hieroglyphs})
+\&                             (583)
+\& X \ep{Ancient_Greek_Music} \ep{Ancient_Greek_Musical_Notation} (=
+\&                             \ep{Block=
+\&                             Ancient_Greek_Musical_Notation}) (80)
+\& X \ep{Ancient_Greek_Musical_Notation} \ep{Block=
+\&                             Ancient_Greek_Musical_Notation} (Short:
+\&                             \ep{InAncientGreekMusic}) (80)
+\& X \ep{Ancient_Greek_Numbers} \ep{Block=Ancient_Greek_Numbers} (80)
+\& X \ep{Ancient_Symbols}     \ep{Block=Ancient_Symbols} (64)
+\&   \ep{Any}                 All Unicode code points (1_114_112:
+\&                             U+0000..10FFFF)
+\&   \ep{Arab}                \ep{Arabic} (= \ep{Script_Extensions=
+\&                             Arabic}) (NOT \ep{Block=Arabic}) (1414)
+\&   \ep{Arabic}              \ep{Script_Extensions=Arabic} (Short:
+\&                             \ep{Arab}; NOT \ep{Block=Arabic}) (1414)
+\& X \ep{Arabic_Ext_A}        \ep{Arabic_Extended_A} (= \ep{Block=
+\&                             Arabic_Extended_A}) (96)
+\& X \ep{Arabic_Ext_B}        \ep{Arabic_Extended_B} (= \ep{Block=
+\&                             Arabic_Extended_B}) (48)
+\& X \ep{Arabic_Ext_C}        \ep{Arabic_Extended_C} (= \ep{Block=
+\&                             Arabic_Extended_C}) (64)
+\& X \ep{Arabic_Extended_A}   \ep{Block=Arabic_Extended_A} (Short:
+\&                             \ep{InArabicExtA}) (96)
+\& X \ep{Arabic_Extended_B}   \ep{Block=Arabic_Extended_B} (Short:
+\&                             \ep{InArabicExtB}) (48)
+\& X \ep{Arabic_Extended_C}   \ep{Block=Arabic_Extended_C} (Short:
+\&                             \ep{InArabicExtC}) (64)
+\& X \ep{Arabic_Math}         \ep{Arabic_Mathematical_Alphabetic_Symbols}
+\&                             (= \ep{Block=
+\&                             Arabic_Mathematical_Alphabetic_Symbols})
+\&                             (256)
+\& X \ep{Arabic_Mathematical_Alphabetic_Symbols} \ep{Block=
+\&                             Arabic_Mathematical_Alphabetic_Symbols}
+\&                             (Short: \ep{InArabicMath}) (256)
+\& X \ep{Arabic_PF_A}         \ep{Arabic_Presentation_Forms_A} (=
+\&                             \ep{Block=Arabic_Presentation_Forms_A})
+\&                             (688)
+\& X \ep{Arabic_PF_B}         \ep{Arabic_Presentation_Forms_B} (=
+\&                             \ep{Block=Arabic_Presentation_Forms_B})
+\&                             (144)
+\& X \ep{Arabic_Presentation_Forms_A} \ep{Block=
+\&                             Arabic_Presentation_Forms_A} (Short:
+\&                             \ep{InArabicPFA}) (688)
+\& X \ep{Arabic_Presentation_Forms_B} \ep{Block=
+\&                             Arabic_Presentation_Forms_B} (Short:
+\&                             \ep{InArabicPFB}) (144)
+\& X \ep{Arabic_Sup}          \ep{Arabic_Supplement} (= \ep{Block=
+\&                             Arabic_Supplement}) (48)
+\& X \ep{Arabic_Supplement}   \ep{Block=Arabic_Supplement} (Short:
+\&                             \ep{InArabicSup}) (48)
+\&   \ep{Armenian}            \ep{Script_Extensions=Armenian} (Short:
+\&                             \ep{Armn}; NOT \ep{Block=Armenian}) (96)
+\&   \ep{Armi}                \ep{Imperial_Aramaic} (=
+\&                             \ep{Script_Extensions=Imperial_Aramaic})
+\&                             (NOT \ep{Block=Imperial_Aramaic}) (31)
+\&   \ep{Armn}                \ep{Armenian} (= \ep{Script_Extensions=
+\&                             Armenian}) (NOT \ep{Block=Armenian}) (96)
+\& X \ep{Arrows}              \ep{Block=Arrows} (112)
+\&   \ep{ASCII}               \ep{Block=Basic_Latin} (128)
+\&   \ep{ASCII_Hex_Digit}     \ep{PosixXDigit} (= \ep{ASCII_Hex_Digit=Y})
+\&                             (22)
+\&   \ep{ASCII_Hex_Digit: N*} (Short: \ep{AHex=N}, \eP{AHex}) (1_114_090
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?
+\&                             \e@G\-Z\e[\e\e\e]\e^_\`g\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..infinity)
+\&   \ep{ASCII_Hex_Digit: Y*} (Short: \ep{AHex=Y}, \ep{AHex}) (22: [0\-9A\-
+\&                             Fa\-f])
+\&   \ep{Assigned}            All assigned code points (288_767:
+\&                             U+0000..0377, U+037A..037F,
+\&                             U+0384..038A, U+038C, U+038E..03A1,
+\&                             U+03A3..052F ...)
+\&   \ep{Avestan}             \ep{Script_Extensions=Avestan} (Short:
+\&                             \ep{Avst}; NOT \ep{Block=Avestan}) (61)
+\&   \ep{Avst}                \ep{Avestan} (= \ep{Script_Extensions=
+\&                             Avestan}) (NOT \ep{Block=Avestan}) (61)
+\&   \ep{Bali}                \ep{Balinese} (= \ep{Script_Extensions=
+\&                             Balinese}) (NOT \ep{Block=Balinese}) (124)
+\&   \ep{Balinese}            \ep{Script_Extensions=Balinese} (Short:
+\&                             \ep{Bali}; NOT \ep{Block=Balinese}) (124)
+\&   \ep{Bamu}                \ep{Bamum} (= \ep{Script_Extensions=Bamum})
+\&                             (NOT \ep{Block=Bamum}) (657)
+\&   \ep{Bamum}               \ep{Script_Extensions=Bamum} (Short:
+\&                             \ep{Bamu}; NOT \ep{Block=Bamum}) (657)
+\& X \ep{Bamum_Sup}           \ep{Bamum_Supplement} (= \ep{Block=
+\&                             Bamum_Supplement}) (576)
+\& X \ep{Bamum_Supplement}    \ep{Block=Bamum_Supplement} (Short:
+\&                             \ep{InBamumSup}) (576)
+\& X \ep{Basic_Latin}         \ep{ASCII} (= \ep{Block=Basic_Latin}) (128)
+\&   \ep{Bass}                \ep{Bassa_Vah} (= \ep{Script_Extensions=
+\&                             Bassa_Vah}) (NOT \ep{Block=Bassa_Vah})
+\&                             (36)
+\&   \ep{Bassa_Vah}           \ep{Script_Extensions=Bassa_Vah} (Short:
+\&                             \ep{Bass}; NOT \ep{Block=Bassa_Vah}) (36)
+\&   \ep{Batak}               \ep{Script_Extensions=Batak} (Short:
+\&                             \ep{Batk}; NOT \ep{Block=Batak}) (56)
+\&   \ep{Batk}                \ep{Batak} (= \ep{Script_Extensions=Batak})
+\&                             (NOT \ep{Block=Batak}) (56)
+\&   \ep{Bc: *}               \ep{Bidi_Class: *}
+\&   \ep{Beng}                \ep{Bengali} (= \ep{Script_Extensions=
+\&                             Bengali}) (NOT \ep{Block=Bengali}) (113)
+\&   \ep{Bengali}             \ep{Script_Extensions=Bengali} (Short:
+\&                             \ep{Beng}; NOT \ep{Block=Bengali}) (113)
+\&   \ep{Bhaiksuki}           \ep{Script_Extensions=Bhaiksuki} (Short:
+\&                             \ep{Bhks}; NOT \ep{Block=Bhaiksuki}) (97)
+\&   \ep{Bhks}                \ep{Bhaiksuki} (= \ep{Script_Extensions=
+\&                             Bhaiksuki}) (NOT \ep{Block=Bhaiksuki})
+\&                             (97)
+\&   \ep{Bidi_C}              \ep{Bidi_Control} (= \ep{Bidi_Control=Y})
+\&                             (12)
+\&   \ep{Bidi_C: *}           \ep{Bidi_Control: *}
+\&   \ep{Bidi_Class: AL}      \ep{Bidi_Class=Arabic_Letter} (1769)
+\&   \ep{Bidi_Class: AN}      \ep{Bidi_Class=Arabic_Number} (63)
+\&   \ep{Bidi_Class: Arabic_Letter} (Short: \ep{Bc=AL}) (1769: U+0608,
+\&                             U+060B, U+060D, U+061B..064A,
+\&                             U+066D..066F, U+0671..06D5 ...)
+\&   \ep{Bidi_Class: Arabic_Number} (Short: \ep{Bc=AN}) (63:
+\&                             U+0600..0605, U+0660..0669,
+\&                             U+066B..066C, U+06DD, U+0890..0891,
+\&                             U+08E2 ...)
+\&   \ep{Bidi_Class: B}       \ep{Bidi_Class=Paragraph_Separator} (7)
+\&   \ep{Bidi_Class: BN}      \ep{Bidi_Class=Boundary_Neutral} (4016)
+\&   \ep{Bidi_Class: Boundary_Neutral} (Short: \ep{Bc=BN}) (4016: [^\et\en
+\&                             \ecK\ef\er\ex1c\-\ex7e\ex85\exa0\-\exac\exae\-\exff],
+\&                             U+180E, U+200B..200D, U+2060..2065,
+\&                             U+206A..206F, U+FDD0..FDEF ...)
+\&   \ep{Bidi_Class: Common_Separator} (Short: \ep{Bc=CS}) (15: [,.\e/:
+\&                             \exa0], U+060C, U+202F, U+2044, U+FE50,
+\&                             U+FE52 ...)
+\&   \ep{Bidi_Class: CS}      \ep{Bidi_Class=Common_Separator} (15)
+\&   \ep{Bidi_Class: EN}      \ep{Bidi_Class=European_Number} (168)
+\&   \ep{Bidi_Class: ES}      \ep{Bidi_Class=European_Separator} (12)
+\&   \ep{Bidi_Class: ET}      \ep{Bidi_Class=European_Terminator} (92)
+\&   \ep{Bidi_Class: European_Number} (Short: \ep{Bc=EN}) (168: [0\-9\exb2\-
+\&                             \exb3\exb9], U+06F0..06F9, U+2070,
+\&                             U+2074..2079, U+2080..2089, U+2488..249B
+\&                             ...)
+\&   \ep{Bidi_Class: European_Separator} (Short: \ep{Bc=ES}) (12: [+\e\-],
+\&                             U+207A..207B, U+208A..208B, U+2212,
+\&                             U+FB29, U+FE62..FE63 ...)
+\&   \ep{Bidi_Class: European_Terminator} (Short: \ep{Bc=ET}) (92: [#\e$
+\&                             \e%\exa2\-\exa5\exb0\-\exb1], U+058F,
+\&                             U+0609..060A, U+066A, U+09F2..09F3,
+\&                             U+09FB ...)
+\&   \ep{Bidi_Class: First_Strong_Isolate} (Short: \ep{Bc=FSI}) (1:
+\&                             U+2068)
+\&   \ep{Bidi_Class: FSI}     \ep{Bidi_Class=First_Strong_Isolate} (1)
+\&   \ep{Bidi_Class: L}       \ep{Bidi_Class=Left_To_Right} (1_096_272
+\&                             plus all above\-Unicode code points)
+\&   \ep{Bidi_Class: Left_To_Right} (Short: \ep{Bc=L}) (1_096_272 plus
+\&                             all above\-Unicode code points: [A\-Za\-z
+\&                             \exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-
+\&                             \exff], U+0100..02B8, U+02BB..02C1,
+\&                             U+02D0..02D1, U+02E0..02E4, U+02EE ...)
+\&   \ep{Bidi_Class: Left_To_Right_Embedding} (Short: \ep{Bc=LRE}) (1:
+\&                             U+202A)
+\&   \ep{Bidi_Class: Left_To_Right_Isolate} (Short: \ep{Bc=LRI}) (1:
+\&                             U+2066)
+\&   \ep{Bidi_Class: Left_To_Right_Override} (Short: \ep{Bc=LRO}) (1:
+\&                             U+202D)
+\&   \ep{Bidi_Class: LRE}     \ep{Bidi_Class=Left_To_Right_Embedding} (1)
+\&   \ep{Bidi_Class: LRI}     \ep{Bidi_Class=Left_To_Right_Isolate} (1)
+\&   \ep{Bidi_Class: LRO}     \ep{Bidi_Class=Left_To_Right_Override} (1)
+\&   \ep{Bidi_Class: Nonspacing_Mark} (Short: \ep{Bc=NSM}) (1993:
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{Bidi_Class: NSM}     \ep{Bidi_Class=Nonspacing_Mark} (1993)
+\&   \ep{Bidi_Class: ON}      \ep{Bidi_Class=Other_Neutral} (6029)
+\&   \ep{Bidi_Class: Other_Neutral} (Short: \ep{Bc=ON}) (6029: [!\e"&\e\*(Aq
+\&                             \e(\e)*;<=>?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\exa1\exa6\-
+\&                             \exa9\exab\-\exac\exae\-\exaf\exb4\exb6\-\exb8\exbb\-
+\&                             \exbf\exd7\exf7], U+02B9..02BA,
+\&                             U+02C2..02CF, U+02D2..02DF,
+\&                             U+02E5..02ED, U+02EF..02FF ...)
+\&   \ep{Bidi_Class: Paragraph_Separator} (Short: \ep{Bc=B}) (7: [\en\er
+\&                             \ex1c\-\ex1e\ex85], U+2029)
+\&   \ep{Bidi_Class: PDF}     \ep{Bidi_Class=Pop_Directional_Format} (1)
+\&   \ep{Bidi_Class: PDI}     \ep{Bidi_Class=Pop_Directional_Isolate} (1)
+\&   \ep{Bidi_Class: Pop_Directional_Format} (Short: \ep{Bc=PDF}) (1:
+\&                             U+202C)
+\&   \ep{Bidi_Class: Pop_Directional_Isolate} (Short: \ep{Bc=PDI}) (1:
+\&                             U+2069)
+\&   \ep{Bidi_Class: R}       \ep{Bidi_Class=Right_To_Left} (3647)
+\&   \ep{Bidi_Class: Right_To_Left} (Short: \ep{Bc=R}) (3647: U+0590,
+\&                             U+05BE, U+05C0, U+05C3, U+05C6,
+\&                             U+05C8..05FF ...)
+\&   \ep{Bidi_Class: Right_To_Left_Embedding} (Short: \ep{Bc=RLE}) (1:
+\&                             U+202B)
+\&   \ep{Bidi_Class: Right_To_Left_Isolate} (Short: \ep{Bc=RLI}) (1:
+\&                             U+2067)
+\&   \ep{Bidi_Class: Right_To_Left_Override} (Short: \ep{Bc=RLO}) (1:
+\&                             U+202E)
+\&   \ep{Bidi_Class: RLE}     \ep{Bidi_Class=Right_To_Left_Embedding} (1)
+\&   \ep{Bidi_Class: RLI}     \ep{Bidi_Class=Right_To_Left_Isolate} (1)
+\&   \ep{Bidi_Class: RLO}     \ep{Bidi_Class=Right_To_Left_Override} (1)
+\&   \ep{Bidi_Class: S}       \ep{Bidi_Class=Segment_Separator} (3)
+\&   \ep{Bidi_Class: Segment_Separator} (Short: \ep{Bc=S}) (3: [\et\ecK
+\&                             \ex1f])
+\&   \ep{Bidi_Class: White_Space} (Short: \ep{Bc=WS}) (17: [\ef\ex20],
+\&                             U+1680, U+2000..200A, U+2028, U+205F,
+\&                             U+3000)
+\&   \ep{Bidi_Class: WS}      \ep{Bidi_Class=White_Space} (17)
+\&   \ep{Bidi_Control}        \ep{Bidi_Control=Y} (Short: \ep{BidiC}) (12)
+\&   \ep{Bidi_Control: N*}    (Short: \ep{BidiC=N}, \eP{BidiC}) (1_114_100
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..061B, U+061D..200D,
+\&                             U+2010..2029, U+202F..2065,
+\&                             U+206A..infinity)
+\&   \ep{Bidi_Control: Y*}    (Short: \ep{BidiC=Y}, \ep{BidiC}) (12:
+\&                             U+061C, U+200E..200F, U+202A..202E,
+\&                             U+2066..2069)
+\&   \ep{Bidi_M}              \ep{Bidi_Mirrored} (= \ep{Bidi_Mirrored=Y})
+\&                             (553)
+\&   \ep{Bidi_M: *}           \ep{Bidi_Mirrored: *}
+\&   \ep{Bidi_Mirrored}       \ep{Bidi_Mirrored=Y} (Short: \ep{BidiM})
+\&                             (553)
+\&   \ep{Bidi_Mirrored: N*}   (Short: \ep{BidiM=N}, \eP{BidiM}) (1_113_559
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq*+,\e\-.\e/0\-9:;=?\e@A\-
+\&                             Z\e\e\e^_\`a\-z\e|~\ex7f\-\exaa\exac\-\exba\exbc\-
+\&                             \exff], U+0100..0F39, U+0F3E..169A,
+\&                             U+169D..2038, U+203B..2044, U+2047..207C
+\&                             ...)
+\&   \ep{Bidi_Mirrored: Y*}   (Short: \ep{BidiM=Y}, \ep{BidiM}) (553:
+\&                             [\e(\e)<>\e[\e]\e{\e}\exab\exbb], U+0F3A..0F3D,
+\&                             U+169B..169C, U+2039..203A,
+\&                             U+2045..2046, U+207D..207E ...)
+\&   \ep{Bidi_Paired_Bracket_Type: C} \ep{Bidi_Paired_Bracket_Type=Close}
+\&                             (64)
+\&   \ep{Bidi_Paired_Bracket_Type: Close} (Short: \ep{Bpt=C}) (64: [\e)\e]
+\&                             \e}], U+0F3B, U+0F3D, U+169C, U+2046,
+\&                             U+207E ...)
+\&   \ep{Bidi_Paired_Bracket_Type: N} \ep{Bidi_Paired_Bracket_Type=None}
+\&                             (1_113_984 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Bidi_Paired_Bracket_Type: None} (Short: \ep{Bpt=N}) (1_113_984
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq*+,\e\-.\e/0\-9:;<=>?
+\&                             \e@A\-Z\e\e\e^_\`a\-z\e|~\ex7f\-\exff],
+\&                             U+0100..0F39, U+0F3E..169A,
+\&                             U+169D..2044, U+2047..207C, U+207F..208C
+\&                             ...)
+\&   \ep{Bidi_Paired_Bracket_Type: O} \ep{Bidi_Paired_Bracket_Type=Open}
+\&                             (64)
+\&   \ep{Bidi_Paired_Bracket_Type: Open} (Short: \ep{Bpt=O}) (64:
+\&                             [\e(\e[\e{], U+0F3A, U+0F3C, U+169B,
+\&                             U+2045, U+207D ...)
+\&   \ep{Blank}               \ep{XPosixBlank} (18)
+\&   \ep{Blk: *}              \ep{Block: *}
+\&   \ep{Block: Adlam}        (NOT \ep{Adlam} NOR \ep{Is_Adlam}) (96:
+\&                             U+1E900..1E95F)
+\&   \ep{Block: Aegean_Numbers} (64: U+10100..1013F)
+\&   \ep{Block: Ahom}         (NOT \ep{Ahom} NOR \ep{Is_Ahom}) (80:
+\&                             U+11700..1174F)
+\&   \ep{Block: Alchemical}   \ep{Block=Alchemical_Symbols} (128)
+\&   \ep{Block: Alchemical_Symbols} (Short: \ep{Blk=Alchemical}) (128:
+\&                             U+1F700..1F77F)
+\&   \ep{Block: Alphabetic_PF} \ep{Block=Alphabetic_Presentation_Forms}
+\&                             (80)
+\&   \ep{Block: Alphabetic_Presentation_Forms} (Short: \ep{Blk=
+\&                             AlphabeticPF}) (80: U+FB00..FB4F)
+\&   \ep{Block: Anatolian_Hieroglyphs} (NOT \ep{Anatolian_Hieroglyphs}
+\&                             NOR \ep{Is_Anatolian_Hieroglyphs}) (640:
+\&                             U+14400..1467F)
+\&   \ep{Block: Ancient_Greek_Music} \ep{Block=
+\&                             Ancient_Greek_Musical_Notation} (80)
+\&   \ep{Block: Ancient_Greek_Musical_Notation} (Short: \ep{Blk=
+\&                             AncientGreekMusic}) (80: U+1D200..1D24F)
+\&   \ep{Block: Ancient_Greek_Numbers} (80: U+10140..1018F)
+\&   \ep{Block: Ancient_Symbols} (64: U+10190..101CF)
+\&   \ep{Block: Arabic}       (NOT \ep{Arabic} NOR \ep{Is_Arabic}) (256:
+\&                             U+0600..06FF)
+\&   \ep{Block: Arabic_Ext_A} \ep{Block=Arabic_Extended_A} (96)
+\&   \ep{Block: Arabic_Ext_B} \ep{Block=Arabic_Extended_B} (48)
+\&   \ep{Block: Arabic_Ext_C} \ep{Block=Arabic_Extended_C} (64)
+\&   \ep{Block: Arabic_Extended_A} (Short: \ep{Blk=ArabicExtA}) (96:
+\&                             U+08A0..08FF)
+\&   \ep{Block: Arabic_Extended_B} (Short: \ep{Blk=ArabicExtB}) (48:
+\&                             U+0870..089F)
+\&   \ep{Block: Arabic_Extended_C} (Short: \ep{Blk=ArabicExtC}) (64:
+\&                             U+10EC0..10EFF)
+\&   \ep{Block: Arabic_Math}  \ep{Block=
+\&                             Arabic_Mathematical_Alphabetic_Symbols}
+\&                             (256)
+\&   \ep{Block: Arabic_Mathematical_Alphabetic_Symbols} (Short: \ep{Blk=
+\&                             ArabicMath}) (256: U+1EE00..1EEFF)
+\&   \ep{Block: Arabic_PF_A}  \ep{Block=Arabic_Presentation_Forms_A} (688)
+\&   \ep{Block: Arabic_PF_B}  \ep{Block=Arabic_Presentation_Forms_B} (144)
+\&   \ep{Block: Arabic_Presentation_Forms_A} (Short: \ep{Blk=ArabicPFA})
+\&                             (688: U+FB50..FDFF)
+\&   \ep{Block: Arabic_Presentation_Forms_B} (Short: \ep{Blk=ArabicPFB})
+\&                             (144: U+FE70..FEFF)
+\&   \ep{Block: Arabic_Sup}   \ep{Block=Arabic_Supplement} (48)
+\&   \ep{Block: Arabic_Supplement} (Short: \ep{Blk=ArabicSup}) (48:
+\&                             U+0750..077F)
+\&   \ep{Block: Armenian}     (NOT \ep{Armenian} NOR \ep{Is_Armenian})
+\&                             (96: U+0530..058F)
+\&   \ep{Block: Arrows}       (112: U+2190..21FF)
+\&   \ep{Block: ASCII}        \ep{Block=Basic_Latin} (128)
+\&   \ep{Block: Avestan}      (NOT \ep{Avestan} NOR \ep{Is_Avestan}) (64:
+\&                             U+10B00..10B3F)
+\&   \ep{Block: Balinese}     (NOT \ep{Balinese} NOR \ep{Is_Balinese})
+\&                             (128: U+1B00..1B7F)
+\&   \ep{Block: Bamum}        (NOT \ep{Bamum} NOR \ep{Is_Bamum}) (96:
+\&                             U+A6A0..A6FF)
+\&   \ep{Block: Bamum_Sup}    \ep{Block=Bamum_Supplement} (576)
+\&   \ep{Block: Bamum_Supplement} (Short: \ep{Blk=BamumSup}) (576:
+\&                             U+16800..16A3F)
+\&   \ep{Block: Basic_Latin}  (Short: \ep{Blk=ASCII}) (128: [\ex00\-\ex7f])
+\&   \ep{Block: Bassa_Vah}    (NOT \ep{Bassa_Vah} NOR \ep{Is_Bassa_Vah})
+\&                             (48: U+16AD0..16AFF)
+\&   \ep{Block: Batak}        (NOT \ep{Batak} NOR \ep{Is_Batak}) (64:
+\&                             U+1BC0..1BFF)
+\&   \ep{Block: Bengali}      (NOT \ep{Bengali} NOR \ep{Is_Bengali}) (128:
+\&                             U+0980..09FF)
+\&   \ep{Block: Bhaiksuki}    (NOT \ep{Bhaiksuki} NOR \ep{Is_Bhaiksuki})
+\&                             (112: U+11C00..11C6F)
+\&   \ep{Block: Block_Elements} (32: U+2580..259F)
+\&   \ep{Block: Bopomofo}     (NOT \ep{Bopomofo} NOR \ep{Is_Bopomofo})
+\&                             (48: U+3100..312F)
+\&   \ep{Block: Bopomofo_Ext} \ep{Block=Bopomofo_Extended} (32)
+\&   \ep{Block: Bopomofo_Extended} (Short: \ep{Blk=BopomofoExt}) (32:
+\&                             U+31A0..31BF)
+\&   \ep{Block: Box_Drawing}  (128: U+2500..257F)
+\&   \ep{Block: Brahmi}       (NOT \ep{Brahmi} NOR \ep{Is_Brahmi}) (128:
+\&                             U+11000..1107F)
+\&   \ep{Block: Braille}      \ep{Block=Braille_Patterns} (256)
+\&   \ep{Block: Braille_Patterns} (Short: \ep{Blk=Braille}) (256:
+\&                             U+2800..28FF)
+\&   \ep{Block: Buginese}     (NOT \ep{Buginese} NOR \ep{Is_Buginese})
+\&                             (32: U+1A00..1A1F)
+\&   \ep{Block: Buhid}        (NOT \ep{Buhid} NOR \ep{Is_Buhid}) (32:
+\&                             U+1740..175F)
+\&   \ep{Block: Byzantine_Music} \ep{Block=Byzantine_Musical_Symbols}
+\&                             (256)
+\&   \ep{Block: Byzantine_Musical_Symbols} (Short: \ep{Blk=
+\&                             ByzantineMusic}) (256: U+1D000..1D0FF)
+\&   \ep{Block: Canadian_Syllabics} \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics}
+\&                             (640)
+\&   \ep{Block: Carian}       (NOT \ep{Carian} NOR \ep{Is_Carian}) (64:
+\&                             U+102A0..102DF)
+\&   \ep{Block: Caucasian_Albanian} (NOT \ep{Caucasian_Albanian} NOR
+\&                             \ep{Is_Caucasian_Albanian}) (64:
+\&                             U+10530..1056F)
+\&   \ep{Block: Chakma}       (NOT \ep{Chakma} NOR \ep{Is_Chakma}) (80:
+\&                             U+11100..1114F)
+\&   \ep{Block: Cham}         (NOT \ep{Cham} NOR \ep{Is_Cham}) (96:
+\&                             U+AA00..AA5F)
+\&   \ep{Block: Cherokee}     (NOT \ep{Cherokee} NOR \ep{Is_Cherokee})
+\&                             (96: U+13A0..13FF)
+\&   \ep{Block: Cherokee_Sup} \ep{Block=Cherokee_Supplement} (80)
+\&   \ep{Block: Cherokee_Supplement} (Short: \ep{Blk=CherokeeSup}) (80:
+\&                             U+AB70..ABBF)
+\&   \ep{Block: Chess_Symbols} (112: U+1FA00..1FA6F)
+\&   \ep{Block: Chorasmian}   (NOT \ep{Chorasmian} NOR \ep{Is_Chorasmian})
+\&                             (48: U+10FB0..10FDF)
+\&   \ep{Block: CJK}          \ep{Block=CJK_Unified_Ideographs} (20_992)
+\&   \ep{Block: CJK_Compat}   \ep{Block=CJK_Compatibility} (256)
+\&   \ep{Block: CJK_Compat_Forms} \ep{Block=CJK_Compatibility_Forms} (32)
+\&   \ep{Block: CJK_Compat_Ideographs} \ep{Block=
+\&                             CJK_Compatibility_Ideographs} (512)
+\&   \ep{Block: CJK_Compat_Ideographs_Sup} \ep{Block=
+\&                             CJK_Compatibility_Ideographs_Supplement}
+\&                             (544)
+\&   \ep{Block: CJK_Compatibility} (Short: \ep{Blk=CJKCompat}) (256:
+\&                             U+3300..33FF)
+\&   \ep{Block: CJK_Compatibility_Forms} (Short: \ep{Blk=CJKCompatForms})
+\&                             (32: U+FE30..FE4F)
+\&   \ep{Block: CJK_Compatibility_Ideographs} (Short: \ep{Blk=
+\&                             CJKCompatIdeographs}) (512: U+F900..FAFF)
+\&   \ep{Block: CJK_Compatibility_Ideographs_Supplement} (Short: \ep{Blk=
+\&                             CJKCompatIdeographsSup}) (544:
+\&                             U+2F800..2FA1F)
+\&   \ep{Block: CJK_Ext_A}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_A}
+\&                             (6592)
+\&   \ep{Block: CJK_Ext_B}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_B}
+\&                             (42_720)
+\&   \ep{Block: CJK_Ext_C}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_C}
+\&                             (4160)
+\&   \ep{Block: CJK_Ext_D}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_D} (224)
+\&   \ep{Block: CJK_Ext_E}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_E}
+\&                             (5776)
+\&   \ep{Block: CJK_Ext_F}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_F}
+\&                             (7488)
+\&   \ep{Block: CJK_Ext_G}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_G}
+\&                             (4944)
+\&   \ep{Block: CJK_Ext_H}    \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_H}
+\&                             (4192)
+\&   \ep{Block: CJK_Radicals_Sup} \ep{Block=CJK_Radicals_Supplement} (128)
+\&   \ep{Block: CJK_Radicals_Supplement} (Short: \ep{Blk=CJKRadicalsSup})
+\&                             (128: U+2E80..2EFF)
+\&   \ep{Block: CJK_Strokes}  (48: U+31C0..31EF)
+\&   \ep{Block: CJK_Symbols}  \ep{Block=CJK_Symbols_And_Punctuation} (64)
+\&   \ep{Block: CJK_Symbols_And_Punctuation} (Short: \ep{Blk=CJKSymbols})
+\&                             (64: U+3000..303F)
+\&   \ep{Block: CJK_Unified_Ideographs} (Short: \ep{Blk=CJK}) (20_992:
+\&                             U+4E00..9FFF)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_A} (Short: \ep{Blk=
+\&                             CJKExtA}) (6592: U+3400..4DBF)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_B} (Short: \ep{Blk=
+\&                             CJKExtB}) (42_720: U+20000..2A6DF)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_C} (Short: \ep{Blk=
+\&                             CJKExtC}) (4160: U+2A700..2B73F)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_D} (Short: \ep{Blk=
+\&                             CJKExtD}) (224: U+2B740..2B81F)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_E} (Short: \ep{Blk=
+\&                             CJKExtE}) (5776: U+2B820..2CEAF)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_F} (Short: \ep{Blk=
+\&                             CJKExtF}) (7488: U+2CEB0..2EBEF)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_G} (Short: \ep{Blk=
+\&                             CJKExtG}) (4944: U+30000..3134F)
+\&   \ep{Block: CJK_Unified_Ideographs_Extension_H} (Short: \ep{Blk=
+\&                             CJKExtH}) (4192: U+31350..323AF)
+\&   \ep{Block: Combining_Diacritical_Marks} (Short: \ep{Blk=
+\&                             Diacriticals}) (112: U+0300..036F)
+\&   \ep{Block: Combining_Diacritical_Marks_Extended} (Short: \ep{Blk=
+\&                             DiacriticalsExt}) (80: U+1AB0..1AFF)
+\&   \ep{Block: Combining_Diacritical_Marks_For_Symbols} (Short: \ep{Blk=
+\&                             DiacriticalsForSymbols}) (48:
+\&                             U+20D0..20FF)
+\&   \ep{Block: Combining_Diacritical_Marks_Supplement} (Short: \ep{Blk=
+\&                             DiacriticalsSup}) (64: U+1DC0..1DFF)
+\&   \ep{Block: Combining_Half_Marks} (Short: \ep{Blk=HalfMarks}) (16:
+\&                             U+FE20..FE2F)
+\&   \ep{Block: Combining_Marks_For_Symbols} \ep{Block=
+\&                             Combining_Diacritical_Marks_For_Symbols}
+\&                             (48)
+\&   \ep{Block: Common_Indic_Number_Forms} (Short: \ep{Blk=
+\&                             IndicNumberForms}) (16: U+A830..A83F)
+\&   \ep{Block: Compat_Jamo}  \ep{Block=Hangul_Compatibility_Jamo} (96)
+\&   \ep{Block: Control_Pictures} (64: U+2400..243F)
+\&   \ep{Block: Coptic}       (NOT \ep{Coptic} NOR \ep{Is_Coptic}) (128:
+\&                             U+2C80..2CFF)
+\&   \ep{Block: Coptic_Epact_Numbers} (32: U+102E0..102FF)
+\&   \ep{Block: Counting_Rod} \ep{Block=Counting_Rod_Numerals} (32)
+\&   \ep{Block: Counting_Rod_Numerals} (Short: \ep{Blk=CountingRod}) (32:
+\&                             U+1D360..1D37F)
+\&   \ep{Block: Cuneiform}    (NOT \ep{Cuneiform} NOR \ep{Is_Cuneiform})
+\&                             (1024: U+12000..123FF)
+\&   \ep{Block: Cuneiform_Numbers} \ep{Block=
+\&                             Cuneiform_Numbers_And_Punctuation} (128)
+\&   \ep{Block: Cuneiform_Numbers_And_Punctuation} (Short: \ep{Blk=
+\&                             CuneiformNumbers}) (128: U+12400..1247F)
+\&   \ep{Block: Currency_Symbols} (48: U+20A0..20CF)
+\&   \ep{Block: Cypriot_Syllabary} (64: U+10800..1083F)
+\&   \ep{Block: Cypro_Minoan} (NOT \ep{Cypro_Minoan} NOR
+\&                             \ep{Is_Cypro_Minoan}) (112:
+\&                             U+12F90..12FFF)
+\&   \ep{Block: Cyrillic}     (NOT \ep{Cyrillic} NOR \ep{Is_Cyrillic})
+\&                             (256: U+0400..04FF)
+\&   \ep{Block: Cyrillic_Ext_A} \ep{Block=Cyrillic_Extended_A} (32)
+\&   \ep{Block: Cyrillic_Ext_B} \ep{Block=Cyrillic_Extended_B} (96)
+\&   \ep{Block: Cyrillic_Ext_C} \ep{Block=Cyrillic_Extended_C} (16)
+\&   \ep{Block: Cyrillic_Ext_D} \ep{Block=Cyrillic_Extended_D} (96)
+\&   \ep{Block: Cyrillic_Extended_A} (Short: \ep{Blk=CyrillicExtA}) (32:
+\&                             U+2DE0..2DFF)
+\&   \ep{Block: Cyrillic_Extended_B} (Short: \ep{Blk=CyrillicExtB}) (96:
+\&                             U+A640..A69F)
+\&   \ep{Block: Cyrillic_Extended_C} (Short: \ep{Blk=CyrillicExtC}) (16:
+\&                             U+1C80..1C8F)
+\&   \ep{Block: Cyrillic_Extended_D} (Short: \ep{Blk=CyrillicExtD}) (96:
+\&                             U+1E030..1E08F)
+\&   \ep{Block: Cyrillic_Sup} \ep{Block=Cyrillic_Supplement} (48)
+\&   \ep{Block: Cyrillic_Supplement} (Short: \ep{Blk=CyrillicSup}) (48:
+\&                             U+0500..052F)
+\&   \ep{Block: Cyrillic_Supplementary} \ep{Block=Cyrillic_Supplement}
+\&                             (48)
+\&   \ep{Block: Deseret}      (80: U+10400..1044F)
+\&   \ep{Block: Devanagari}   (NOT \ep{Devanagari} NOR \ep{Is_Devanagari})
+\&                             (128: U+0900..097F)
+\&   \ep{Block: Devanagari_Ext} \ep{Block=Devanagari_Extended} (32)
+\&   \ep{Block: Devanagari_Ext_A} \ep{Block=Devanagari_Extended_A} (96)
+\&   \ep{Block: Devanagari_Extended} (Short: \ep{Blk=DevanagariExt}) (32:
+\&                             U+A8E0..A8FF)
+\&   \ep{Block: Devanagari_Extended_A} (Short: \ep{Blk=DevanagariExtA})
+\&                             (96: U+11B00..11B5F)
+\&   \ep{Block: Diacriticals} \ep{Block=Combining_Diacritical_Marks} (112)
+\&   \ep{Block: Diacriticals_Ext} \ep{Block=
+\&                             Combining_Diacritical_Marks_Extended}
+\&                             (80)
+\&   \ep{Block: Diacriticals_For_Symbols} \ep{Block=
+\&                             Combining_Diacritical_Marks_For_Symbols}
+\&                             (48)
+\&   \ep{Block: Diacriticals_Sup} \ep{Block=
+\&                             Combining_Diacritical_Marks_Supplement}
+\&                             (64)
+\&   \ep{Block: Dingbats}     (192: U+2700..27BF)
+\&   \ep{Block: Dives_Akuru}  (NOT \ep{Dives_Akuru} NOR
+\&                             \ep{Is_Dives_Akuru}) (96: U+11900..1195F)
+\&   \ep{Block: Dogra}        (NOT \ep{Dogra} NOR \ep{Is_Dogra}) (80:
+\&                             U+11800..1184F)
+\&   \ep{Block: Domino}       \ep{Block=Domino_Tiles} (112)
+\&   \ep{Block: Domino_Tiles} (Short: \ep{Blk=Domino}) (112:
+\&                             U+1F030..1F09F)
+\&   \ep{Block: Duployan}     (NOT \ep{Duployan} NOR \ep{Is_Duployan})
+\&                             (160: U+1BC00..1BC9F)
+\&   \ep{Block: Early_Dynastic_Cuneiform} (208: U+12480..1254F)
+\&   \ep{Block: Egyptian_Hieroglyph_Format_Controls} (48: U+13430..1345F)
+\&   \ep{Block: Egyptian_Hieroglyphs} (NOT \ep{Egyptian_Hieroglyphs} NOR
+\&                             \ep{Is_Egyptian_Hieroglyphs}) (1072:
+\&                             U+13000..1342F)
+\&   \ep{Block: Elbasan}      (NOT \ep{Elbasan} NOR \ep{Is_Elbasan}) (48:
+\&                             U+10500..1052F)
+\&   \ep{Block: Elymaic}      (NOT \ep{Elymaic} NOR \ep{Is_Elymaic}) (32:
+\&                             U+10FE0..10FFF)
+\&   \ep{Block: Emoticons}    (80: U+1F600..1F64F)
+\&   \ep{Block: Enclosed_Alphanum} \ep{Block=Enclosed_Alphanumerics} (160)
+\&   \ep{Block: Enclosed_Alphanum_Sup} \ep{Block=
+\&                             Enclosed_Alphanumeric_Supplement} (256)
+\&   \ep{Block: Enclosed_Alphanumeric_Supplement} (Short: \ep{Blk=
+\&                             EnclosedAlphanumSup}) (256:
+\&                             U+1F100..1F1FF)
+\&   \ep{Block: Enclosed_Alphanumerics} (Short: \ep{Blk=
+\&                             EnclosedAlphanum}) (160: U+2460..24FF)
+\&   \ep{Block: Enclosed_CJK} \ep{Block=Enclosed_CJK_Letters_And_Months}
+\&                             (256)
+\&   \ep{Block: Enclosed_CJK_Letters_And_Months} (Short: \ep{Blk=
+\&                             EnclosedCJK}) (256: U+3200..32FF)
+\&   \ep{Block: Enclosed_Ideographic_Sup} \ep{Block=
+\&                             Enclosed_Ideographic_Supplement} (256)
+\&   \ep{Block: Enclosed_Ideographic_Supplement} (Short: \ep{Blk=
+\&                             EnclosedIdeographicSup}) (256:
+\&                             U+1F200..1F2FF)
+\&   \ep{Block: Ethiopic}     (NOT \ep{Ethiopic} NOR \ep{Is_Ethiopic})
+\&                             (384: U+1200..137F)
+\&   \ep{Block: Ethiopic_Ext} \ep{Block=Ethiopic_Extended} (96)
+\&   \ep{Block: Ethiopic_Ext_A} \ep{Block=Ethiopic_Extended_A} (48)
+\&   \ep{Block: Ethiopic_Ext_B} \ep{Block=Ethiopic_Extended_B} (32)
+\&   \ep{Block: Ethiopic_Extended} (Short: \ep{Blk=EthiopicExt}) (96:
+\&                             U+2D80..2DDF)
+\&   \ep{Block: Ethiopic_Extended_A} (Short: \ep{Blk=EthiopicExtA}) (48:
+\&                             U+AB00..AB2F)
+\&   \ep{Block: Ethiopic_Extended_B} (Short: \ep{Blk=EthiopicExtB}) (32:
+\&                             U+1E7E0..1E7FF)
+\&   \ep{Block: Ethiopic_Sup} \ep{Block=Ethiopic_Supplement} (32)
+\&   \ep{Block: Ethiopic_Supplement} (Short: \ep{Blk=EthiopicSup}) (32:
+\&                             U+1380..139F)
+\&   \ep{Block: General_Punctuation} (Short: \ep{Blk=Punctuation}; NOT
+\&                             \ep{Punct} NOR \ep{Is_Punctuation}) (112:
+\&                             U+2000..206F)
+\&   \ep{Block: Geometric_Shapes} (96: U+25A0..25FF)
+\&   \ep{Block: Geometric_Shapes_Ext} \ep{Block=
+\&                             Geometric_Shapes_Extended} (128)
+\&   \ep{Block: Geometric_Shapes_Extended} (Short: \ep{Blk=
+\&                             GeometricShapesExt}) (128:
+\&                             U+1F780..1F7FF)
+\&   \ep{Block: Georgian}     (NOT \ep{Georgian} NOR \ep{Is_Georgian})
+\&                             (96: U+10A0..10FF)
+\&   \ep{Block: Georgian_Ext} \ep{Block=Georgian_Extended} (48)
+\&   \ep{Block: Georgian_Extended} (Short: \ep{Blk=GeorgianExt}) (48:
+\&                             U+1C90..1CBF)
+\&   \ep{Block: Georgian_Sup} \ep{Block=Georgian_Supplement} (48)
+\&   \ep{Block: Georgian_Supplement} (Short: \ep{Blk=GeorgianSup}) (48:
+\&                             U+2D00..2D2F)
+\&   \ep{Block: Glagolitic}   (NOT \ep{Glagolitic} NOR \ep{Is_Glagolitic})
+\&                             (96: U+2C00..2C5F)
+\&   \ep{Block: Glagolitic_Sup} \ep{Block=Glagolitic_Supplement} (48)
+\&   \ep{Block: Glagolitic_Supplement} (Short: \ep{Blk=GlagoliticSup})
+\&                             (48: U+1E000..1E02F)
+\&   \ep{Block: Gothic}       (NOT \ep{Gothic} NOR \ep{Is_Gothic}) (32:
+\&                             U+10330..1034F)
+\&   \ep{Block: Grantha}      (NOT \ep{Grantha} NOR \ep{Is_Grantha}) (128:
+\&                             U+11300..1137F)
+\&   \ep{Block: Greek}        \ep{Block=Greek_And_Coptic} (NOT \ep{Greek}
+\&                             NOR \ep{Is_Greek}) (144)
+\&   \ep{Block: Greek_And_Coptic} (Short: \ep{Blk=Greek}; NOT \ep{Greek}
+\&                             NOR \ep{Is_Greek}) (144: U+0370..03FF)
+\&   \ep{Block: Greek_Ext}    \ep{Block=Greek_Extended} (256)
+\&   \ep{Block: Greek_Extended} (Short: \ep{Blk=GreekExt}) (256:
+\&                             U+1F00..1FFF)
+\&   \ep{Block: Gujarati}     (NOT \ep{Gujarati} NOR \ep{Is_Gujarati})
+\&                             (128: U+0A80..0AFF)
+\&   \ep{Block: Gunjala_Gondi} (NOT \ep{Gunjala_Gondi} NOR
+\&                             \ep{Is_Gunjala_Gondi}) (80:
+\&                             U+11D60..11DAF)
+\&   \ep{Block: Gurmukhi}     (NOT \ep{Gurmukhi} NOR \ep{Is_Gurmukhi})
+\&                             (128: U+0A00..0A7F)
+\&   \ep{Block: Half_And_Full_Forms} \ep{Block=
+\&                             Halfwidth_And_Fullwidth_Forms} (240)
+\&   \ep{Block: Half_Marks}   \ep{Block=Combining_Half_Marks} (16)
+\&   \ep{Block: Halfwidth_And_Fullwidth_Forms} (Short: \ep{Blk=
+\&                             HalfAndFullForms}) (240: U+FF00..FFEF)
+\&   \ep{Block: Hangul}       \ep{Block=Hangul_Syllables} (NOT \ep{Hangul}
+\&                             NOR \ep{Is_Hangul}) (11_184)
+\&   \ep{Block: Hangul_Compatibility_Jamo} (Short: \ep{Blk=CompatJamo})
+\&                             (96: U+3130..318F)
+\&   \ep{Block: Hangul_Jamo}  (Short: \ep{Blk=Jamo}) (256: U+1100..11FF)
+\&   \ep{Block: Hangul_Jamo_Extended_A} (Short: \ep{Blk=JamoExtA}) (32:
+\&                             U+A960..A97F)
+\&   \ep{Block: Hangul_Jamo_Extended_B} (Short: \ep{Blk=JamoExtB}) (80:
+\&                             U+D7B0..D7FF)
+\&   \ep{Block: Hangul_Syllables} (Short: \ep{Blk=Hangul}; NOT \ep{Hangul}
+\&                             NOR \ep{Is_Hangul}) (11_184: U+AC00..D7AF)
+\&   \ep{Block: Hanifi_Rohingya} (NOT \ep{Hanifi_Rohingya} NOR
+\&                             \ep{Is_Hanifi_Rohingya}) (64:
+\&                             U+10D00..10D3F)
+\&   \ep{Block: Hanunoo}      (NOT \ep{Hanunoo} NOR \ep{Is_Hanunoo}) (32:
+\&                             U+1720..173F)
+\&   \ep{Block: Hatran}       (NOT \ep{Hatran} NOR \ep{Is_Hatran}) (32:
+\&                             U+108E0..108FF)
+\&   \ep{Block: Hebrew}       (NOT \ep{Hebrew} NOR \ep{Is_Hebrew}) (112:
+\&                             U+0590..05FF)
+\&   \ep{Block: High_Private_Use_Surrogates} (Short: \ep{Blk=
+\&                             HighPUSurrogates}) (128: U+DB80..DBFF)
+\&   \ep{Block: High_PU_Surrogates} \ep{Block=
+\&                             High_Private_Use_Surrogates} (128)
+\&   \ep{Block: High_Surrogates} (896: U+D800..DB7F)
+\&   \ep{Block: Hiragana}     (NOT \ep{Hiragana} NOR \ep{Is_Hiragana})
+\&                             (96: U+3040..309F)
+\&   \ep{Block: IDC}          \ep{Block=
+\&                             Ideographic_Description_Characters} (NOT
+\&                             \ep{ID_Continue} NOR \ep{Is_IDC}) (16)
+\&   \ep{Block: Ideographic_Description_Characters} (Short: \ep{Blk=IDC};
+\&                             NOT \ep{ID_Continue} NOR \ep{Is_IDC}) (16:
+\&                             U+2FF0..2FFF)
+\&   \ep{Block: Ideographic_Symbols} \ep{Block=
+\&                             Ideographic_Symbols_And_Punctuation} (32)
+\&   \ep{Block: Ideographic_Symbols_And_Punctuation} (Short: \ep{Blk=
+\&                             IdeographicSymbols}) (32: U+16FE0..16FFF)
+\&   \ep{Block: Imperial_Aramaic} (NOT \ep{Imperial_Aramaic} NOR
+\&                             \ep{Is_Imperial_Aramaic}) (32:
+\&                             U+10840..1085F)
+\&   \ep{Block: Indic_Number_Forms} \ep{Block=Common_Indic_Number_Forms}
+\&                             (16)
+\&   \ep{Block: Indic_Siyaq_Numbers} (80: U+1EC70..1ECBF)
+\&   \ep{Block: Inscriptional_Pahlavi} (NOT \ep{Inscriptional_Pahlavi}
+\&                             NOR \ep{Is_Inscriptional_Pahlavi}) (32:
+\&                             U+10B60..10B7F)
+\&   \ep{Block: Inscriptional_Parthian} (NOT \ep{Inscriptional_Parthian}
+\&                             NOR \ep{Is_Inscriptional_Parthian}) (32:
+\&                             U+10B40..10B5F)
+\&   \ep{Block: IPA_Ext}      \ep{Block=IPA_Extensions} (96)
+\&   \ep{Block: IPA_Extensions} (Short: \ep{Blk=IPAExt}) (96:
+\&                             U+0250..02AF)
+\&   \ep{Block: Jamo}         \ep{Block=Hangul_Jamo} (256)
+\&   \ep{Block: Jamo_Ext_A}   \ep{Block=Hangul_Jamo_Extended_A} (32)
+\&   \ep{Block: Jamo_Ext_B}   \ep{Block=Hangul_Jamo_Extended_B} (80)
+\&   \ep{Block: Javanese}     (NOT \ep{Javanese} NOR \ep{Is_Javanese})
+\&                             (96: U+A980..A9DF)
+\&   \ep{Block: Kaithi}       (NOT \ep{Kaithi} NOR \ep{Is_Kaithi}) (80:
+\&                             U+11080..110CF)
+\&   \ep{Block: Kaktovik_Numerals} (32: U+1D2C0..1D2DF)
+\&   \ep{Block: Kana_Ext_A}   \ep{Block=Kana_Extended_A} (48)
+\&   \ep{Block: Kana_Ext_B}   \ep{Block=Kana_Extended_B} (16)
+\&   \ep{Block: Kana_Extended_A} (Short: \ep{Blk=KanaExtA}) (48:
+\&                             U+1B100..1B12F)
+\&   \ep{Block: Kana_Extended_B} (Short: \ep{Blk=KanaExtB}) (16:
+\&                             U+1AFF0..1AFFF)
+\&   \ep{Block: Kana_Sup}     \ep{Block=Kana_Supplement} (256)
+\&   \ep{Block: Kana_Supplement} (Short: \ep{Blk=KanaSup}) (256:
+\&                             U+1B000..1B0FF)
+\&   \ep{Block: Kanbun}       (16: U+3190..319F)
+\&   \ep{Block: Kangxi}       \ep{Block=Kangxi_Radicals} (224)
+\&   \ep{Block: Kangxi_Radicals} (Short: \ep{Blk=Kangxi}) (224:
+\&                             U+2F00..2FDF)
+\&   \ep{Block: Kannada}      (NOT \ep{Kannada} NOR \ep{Is_Kannada}) (128:
+\&                             U+0C80..0CFF)
+\&   \ep{Block: Katakana}     (NOT \ep{Katakana} NOR \ep{Is_Katakana})
+\&                             (96: U+30A0..30FF)
+\&   \ep{Block: Katakana_Ext} \ep{Block=Katakana_Phonetic_Extensions} (16)
+\&   \ep{Block: Katakana_Phonetic_Extensions} (Short: \ep{Blk=
+\&                             KatakanaExt}) (16: U+31F0..31FF)
+\&   \ep{Block: Kawi}         (NOT \ep{Kawi} NOR \ep{Is_Kawi}) (96:
+\&                             U+11F00..11F5F)
+\&   \ep{Block: Kayah_Li}     (48: U+A900..A92F)
+\&   \ep{Block: Kharoshthi}   (NOT \ep{Kharoshthi} NOR \ep{Is_Kharoshthi})
+\&                             (96: U+10A00..10A5F)
+\&   \ep{Block: Khitan_Small_Script} (NOT \ep{Khitan_Small_Script} NOR
+\&                             \ep{Is_Khitan_Small_Script}) (512:
+\&                             U+18B00..18CFF)
+\&   \ep{Block: Khmer}        (NOT \ep{Khmer} NOR \ep{Is_Khmer}) (128:
+\&                             U+1780..17FF)
+\&   \ep{Block: Khmer_Symbols} (32: U+19E0..19FF)
+\&   \ep{Block: Khojki}       (NOT \ep{Khojki} NOR \ep{Is_Khojki}) (80:
+\&                             U+11200..1124F)
+\&   \ep{Block: Khudawadi}    (NOT \ep{Khudawadi} NOR \ep{Is_Khudawadi})
+\&                             (80: U+112B0..112FF)
+\&   \ep{Block: Lao}          (NOT \ep{Lao} NOR \ep{Is_Lao}) (128:
+\&                             U+0E80..0EFF)
+\&   \ep{Block: Latin_1}      \ep{Block=Latin_1_Supplement} (128)
+\&   \ep{Block: Latin_1_Sup}  \ep{Block=Latin_1_Supplement} (128)
+\&   \ep{Block: Latin_1_Supplement} (Short: \ep{Blk=Latin1}) (128: [\ex80\-
+\&                             \exff])
+\&   \ep{Block: Latin_Ext_A}  \ep{Block=Latin_Extended_A} (128)
+\&   \ep{Block: Latin_Ext_Additional} \ep{Block=
+\&                             Latin_Extended_Additional} (256)
+\&   \ep{Block: Latin_Ext_B}  \ep{Block=Latin_Extended_B} (208)
+\&   \ep{Block: Latin_Ext_C}  \ep{Block=Latin_Extended_C} (32)
+\&   \ep{Block: Latin_Ext_D}  \ep{Block=Latin_Extended_D} (224)
+\&   \ep{Block: Latin_Ext_E}  \ep{Block=Latin_Extended_E} (64)
+\&   \ep{Block: Latin_Ext_F}  \ep{Block=Latin_Extended_F} (64)
+\&   \ep{Block: Latin_Ext_G}  \ep{Block=Latin_Extended_G} (256)
+\&   \ep{Block: Latin_Extended_A} (Short: \ep{Blk=LatinExtA}) (128:
+\&                             U+0100..017F)
+\&   \ep{Block: Latin_Extended_Additional} (Short: \ep{Blk=
+\&                             LatinExtAdditional}) (256: U+1E00..1EFF)
+\&   \ep{Block: Latin_Extended_B} (Short: \ep{Blk=LatinExtB}) (208:
+\&                             U+0180..024F)
+\&   \ep{Block: Latin_Extended_C} (Short: \ep{Blk=LatinExtC}) (32:
+\&                             U+2C60..2C7F)
+\&   \ep{Block: Latin_Extended_D} (Short: \ep{Blk=LatinExtD}) (224:
+\&                             U+A720..A7FF)
+\&   \ep{Block: Latin_Extended_E} (Short: \ep{Blk=LatinExtE}) (64:
+\&                             U+AB30..AB6F)
+\&   \ep{Block: Latin_Extended_F} (Short: \ep{Blk=LatinExtF}) (64:
+\&                             U+10780..107BF)
+\&   \ep{Block: Latin_Extended_G} (Short: \ep{Blk=LatinExtG}) (256:
+\&                             U+1DF00..1DFFF)
+\&   \ep{Block: Lepcha}       (NOT \ep{Lepcha} NOR \ep{Is_Lepcha}) (80:
+\&                             U+1C00..1C4F)
+\&   \ep{Block: Letterlike_Symbols} (80: U+2100..214F)
+\&   \ep{Block: Limbu}        (NOT \ep{Limbu} NOR \ep{Is_Limbu}) (80:
+\&                             U+1900..194F)
+\&   \ep{Block: Linear_A}     (NOT \ep{Linear_A} NOR \ep{Is_Linear_A})
+\&                             (384: U+10600..1077F)
+\&   \ep{Block: Linear_B_Ideograms} (128: U+10080..100FF)
+\&   \ep{Block: Linear_B_Syllabary} (128: U+10000..1007F)
+\&   \ep{Block: Lisu}         (NOT \ep{Lisu} NOR \ep{Is_Lisu}) (48:
+\&                             U+A4D0..A4FF)
+\&   \ep{Block: Lisu_Sup}     \ep{Block=Lisu_Supplement} (16)
+\&   \ep{Block: Lisu_Supplement} (Short: \ep{Blk=LisuSup}) (16:
+\&                             U+11FB0..11FBF)
+\&   \ep{Block: Low_Surrogates} (1024: U+DC00..DFFF)
+\&   \ep{Block: Lycian}       (NOT \ep{Lycian} NOR \ep{Is_Lycian}) (32:
+\&                             U+10280..1029F)
+\&   \ep{Block: Lydian}       (NOT \ep{Lydian} NOR \ep{Is_Lydian}) (32:
+\&                             U+10920..1093F)
+\&   \ep{Block: Mahajani}     (NOT \ep{Mahajani} NOR \ep{Is_Mahajani})
+\&                             (48: U+11150..1117F)
+\&   \ep{Block: Mahjong}      \ep{Block=Mahjong_Tiles} (48)
+\&   \ep{Block: Mahjong_Tiles} (Short: \ep{Blk=Mahjong}) (48:
+\&                             U+1F000..1F02F)
+\&   \ep{Block: Makasar}      (NOT \ep{Makasar} NOR \ep{Is_Makasar}) (32:
+\&                             U+11EE0..11EFF)
+\&   \ep{Block: Malayalam}    (NOT \ep{Malayalam} NOR \ep{Is_Malayalam})
+\&                             (128: U+0D00..0D7F)
+\&   \ep{Block: Mandaic}      (NOT \ep{Mandaic} NOR \ep{Is_Mandaic}) (32:
+\&                             U+0840..085F)
+\&   \ep{Block: Manichaean}   (NOT \ep{Manichaean} NOR \ep{Is_Manichaean})
+\&                             (64: U+10AC0..10AFF)
+\&   \ep{Block: Marchen}      (NOT \ep{Marchen} NOR \ep{Is_Marchen}) (80:
+\&                             U+11C70..11CBF)
+\&   \ep{Block: Masaram_Gondi} (NOT \ep{Masaram_Gondi} NOR
+\&                             \ep{Is_Masaram_Gondi}) (96:
+\&                             U+11D00..11D5F)
+\&   \ep{Block: Math_Alphanum} \ep{Block=
+\&                             Mathematical_Alphanumeric_Symbols} (1024)
+\&   \ep{Block: Math_Operators} \ep{Block=Mathematical_Operators} (256)
+\&   \ep{Block: Mathematical_Alphanumeric_Symbols} (Short: \ep{Blk=
+\&                             MathAlphanum}) (1024: U+1D400..1D7FF)
+\&   \ep{Block: Mathematical_Operators} (Short: \ep{Blk=MathOperators})
+\&                             (256: U+2200..22FF)
+\&   \ep{Block: Mayan_Numerals} (32: U+1D2E0..1D2FF)
+\&   \ep{Block: Medefaidrin}  (NOT \ep{Medefaidrin} NOR
+\&                             \ep{Is_Medefaidrin}) (96: U+16E40..16E9F)
+\&   \ep{Block: Meetei_Mayek} (NOT \ep{Meetei_Mayek} NOR
+\&                             \ep{Is_Meetei_Mayek}) (64: U+ABC0..ABFF)
+\&   \ep{Block: Meetei_Mayek_Ext} \ep{Block=Meetei_Mayek_Extensions} (32)
+\&   \ep{Block: Meetei_Mayek_Extensions} (Short: \ep{Blk=MeeteiMayekExt})
+\&                             (32: U+AAE0..AAFF)
+\&   \ep{Block: Mende_Kikakui} (NOT \ep{Mende_Kikakui} NOR
+\&                             \ep{Is_Mende_Kikakui}) (224:
+\&                             U+1E800..1E8DF)
+\&   \ep{Block: Meroitic_Cursive} (NOT \ep{Meroitic_Cursive} NOR
+\&                             \ep{Is_Meroitic_Cursive}) (96:
+\&                             U+109A0..109FF)
+\&   \ep{Block: Meroitic_Hieroglyphs} (32: U+10980..1099F)
+\&   \ep{Block: Miao}         (NOT \ep{Miao} NOR \ep{Is_Miao}) (160:
+\&                             U+16F00..16F9F)
+\&   \ep{Block: Misc_Arrows}  \ep{Block=Miscellaneous_Symbols_And_Arrows}
+\&                             (256)
+\&   \ep{Block: Misc_Math_Symbols_A} \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_A}
+\&                             (48)
+\&   \ep{Block: Misc_Math_Symbols_B} \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_B}
+\&                             (128)
+\&   \ep{Block: Misc_Pictographs} \ep{Block=
+\&                             Miscellaneous_Symbols_And_Pictographs}
+\&                             (768)
+\&   \ep{Block: Misc_Symbols} \ep{Block=Miscellaneous_Symbols} (256)
+\&   \ep{Block: Misc_Technical} \ep{Block=Miscellaneous_Technical} (256)
+\&   \ep{Block: Miscellaneous_Mathematical_Symbols_A} (Short: \ep{Blk=
+\&                             MiscMathSymbolsA}) (48: U+27C0..27EF)
+\&   \ep{Block: Miscellaneous_Mathematical_Symbols_B} (Short: \ep{Blk=
+\&                             MiscMathSymbolsB}) (128: U+2980..29FF)
+\&   \ep{Block: Miscellaneous_Symbols} (Short: \ep{Blk=MiscSymbols})
+\&                             (256: U+2600..26FF)
+\&   \ep{Block: Miscellaneous_Symbols_And_Arrows} (Short: \ep{Blk=
+\&                             MiscArrows}) (256: U+2B00..2BFF)
+\&   \ep{Block: Miscellaneous_Symbols_And_Pictographs} (Short: \ep{Blk=
+\&                             MiscPictographs}) (768: U+1F300..1F5FF)
+\&   \ep{Block: Miscellaneous_Technical} (Short: \ep{Blk=MiscTechnical})
+\&                             (256: U+2300..23FF)
+\&   \ep{Block: Modi}         (NOT \ep{Modi} NOR \ep{Is_Modi}) (96:
+\&                             U+11600..1165F)
+\&   \ep{Block: Modifier_Letters} \ep{Block=Spacing_Modifier_Letters} (80)
+\&   \ep{Block: Modifier_Tone_Letters} (32: U+A700..A71F)
+\&   \ep{Block: Mongolian}    (NOT \ep{Mongolian} NOR \ep{Is_Mongolian})
+\&                             (176: U+1800..18AF)
+\&   \ep{Block: Mongolian_Sup} \ep{Block=Mongolian_Supplement} (32)
+\&   \ep{Block: Mongolian_Supplement} (Short: \ep{Blk=MongolianSup}) (32:
+\&                             U+11660..1167F)
+\&   \ep{Block: Mro}          (NOT \ep{Mro} NOR \ep{Is_Mro}) (48:
+\&                             U+16A40..16A6F)
+\&   \ep{Block: Multani}      (NOT \ep{Multani} NOR \ep{Is_Multani}) (48:
+\&                             U+11280..112AF)
+\&   \ep{Block: Music}        \ep{Block=Musical_Symbols} (256)
+\&   \ep{Block: Musical_Symbols} (Short: \ep{Blk=Music}) (256:
+\&                             U+1D100..1D1FF)
+\&   \ep{Block: Myanmar}      (NOT \ep{Myanmar} NOR \ep{Is_Myanmar}) (160:
+\&                             U+1000..109F)
+\&   \ep{Block: Myanmar_Ext_A} \ep{Block=Myanmar_Extended_A} (32)
+\&   \ep{Block: Myanmar_Ext_B} \ep{Block=Myanmar_Extended_B} (32)
+\&   \ep{Block: Myanmar_Extended_A} (Short: \ep{Blk=MyanmarExtA}) (32:
+\&                             U+AA60..AA7F)
+\&   \ep{Block: Myanmar_Extended_B} (Short: \ep{Blk=MyanmarExtB}) (32:
+\&                             U+A9E0..A9FF)
+\&   \ep{Block: Nabataean}    (NOT \ep{Nabataean} NOR \ep{Is_Nabataean})
+\&                             (48: U+10880..108AF)
+\&   \ep{Block: Nag_Mundari}  (NOT \ep{Nag_Mundari} NOR
+\&                             \ep{Is_Nag_Mundari}) (48: U+1E4D0..1E4FF)
+\&   \ep{Block: Nandinagari}  (NOT \ep{Nandinagari} NOR
+\&                             \ep{Is_Nandinagari}) (96: U+119A0..119FF)
+\&   \ep{Block: NB}           \ep{Block=No_Block} (820_944 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Block: New_Tai_Lue}  (NOT \ep{New_Tai_Lue} NOR
+\&                             \ep{Is_New_Tai_Lue}) (96: U+1980..19DF)
+\&   \ep{Block: Newa}         (NOT \ep{Newa} NOR \ep{Is_Newa}) (128:
+\&                             U+11400..1147F)
+\&   \ep{Block: NKo}          (NOT \ep{Nko} NOR \ep{Is_NKo}) (64:
+\&                             U+07C0..07FF)
+\&   \ep{Block: No_Block}     (Short: \ep{Blk=NB}) (820_944 plus all
+\&                             above\-Unicode code points: U+2FE0..2FEF,
+\&                             U+10200..1027F, U+103E0..103FF,
+\&                             U+105C0..105FF, U+107C0..107FF,
+\&                             U+108B0..108DF ...)
+\&   \ep{Block: Number_Forms} (64: U+2150..218F)
+\&   \ep{Block: Nushu}        (NOT \ep{Nushu} NOR \ep{Is_Nushu}) (400:
+\&                             U+1B170..1B2FF)
+\&   \ep{Block: Nyiakeng_Puachue_Hmong} (NOT \ep{Nyiakeng_Puachue_Hmong}
+\&                             NOR \ep{Is_Nyiakeng_Puachue_Hmong}) (80:
+\&                             U+1E100..1E14F)
+\&   \ep{Block: OCR}          \ep{Block=Optical_Character_Recognition}
+\&                             (32)
+\&   \ep{Block: Ogham}        (NOT \ep{Ogham} NOR \ep{Is_Ogham}) (32:
+\&                             U+1680..169F)
+\&   \ep{Block: Ol_Chiki}     (48: U+1C50..1C7F)
+\&   \ep{Block: Old_Hungarian} (NOT \ep{Old_Hungarian} NOR
+\&                             \ep{Is_Old_Hungarian}) (128:
+\&                             U+10C80..10CFF)
+\&   \ep{Block: Old_Italic}   (NOT \ep{Old_Italic} NOR \ep{Is_Old_Italic})
+\&                             (48: U+10300..1032F)
+\&   \ep{Block: Old_North_Arabian} (32: U+10A80..10A9F)
+\&   \ep{Block: Old_Permic}   (NOT \ep{Old_Permic} NOR \ep{Is_Old_Permic})
+\&                             (48: U+10350..1037F)
+\&   \ep{Block: Old_Persian}  (NOT \ep{Old_Persian} NOR
+\&                             \ep{Is_Old_Persian}) (64: U+103A0..103DF)
+\&   \ep{Block: Old_Sogdian}  (NOT \ep{Old_Sogdian} NOR
+\&                             \ep{Is_Old_Sogdian}) (48: U+10F00..10F2F)
+\&   \ep{Block: Old_South_Arabian} (32: U+10A60..10A7F)
+\&   \ep{Block: Old_Turkic}   (NOT \ep{Old_Turkic} NOR \ep{Is_Old_Turkic})
+\&                             (80: U+10C00..10C4F)
+\&   \ep{Block: Old_Uyghur}   (NOT \ep{Old_Uyghur} NOR \ep{Is_Old_Uyghur})
+\&                             (64: U+10F70..10FAF)
+\&   \ep{Block: Optical_Character_Recognition} (Short: \ep{Blk=OCR}) (32:
+\&                             U+2440..245F)
+\&   \ep{Block: Oriya}        (NOT \ep{Oriya} NOR \ep{Is_Oriya}) (128:
+\&                             U+0B00..0B7F)
+\&   \ep{Block: Ornamental_Dingbats} (48: U+1F650..1F67F)
+\&   \ep{Block: Osage}        (NOT \ep{Osage} NOR \ep{Is_Osage}) (80:
+\&                             U+104B0..104FF)
+\&   \ep{Block: Osmanya}      (NOT \ep{Osmanya} NOR \ep{Is_Osmanya}) (48:
+\&                             U+10480..104AF)
+\&   \ep{Block: Ottoman_Siyaq_Numbers} (80: U+1ED00..1ED4F)
+\&   \ep{Block: Pahawh_Hmong} (NOT \ep{Pahawh_Hmong} NOR
+\&                             \ep{Is_Pahawh_Hmong}) (144:
+\&                             U+16B00..16B8F)
+\&   \ep{Block: Palmyrene}    (32: U+10860..1087F)
+\&   \ep{Block: Pau_Cin_Hau}  (NOT \ep{Pau_Cin_Hau} NOR
+\&                             \ep{Is_Pau_Cin_Hau}) (64: U+11AC0..11AFF)
+\&   \ep{Block: Phags_Pa}     (NOT \ep{Phags_Pa} NOR \ep{Is_Phags_Pa})
+\&                             (64: U+A840..A87F)
+\&   \ep{Block: Phaistos}     \ep{Block=Phaistos_Disc} (48)
+\&   \ep{Block: Phaistos_Disc} (Short: \ep{Blk=Phaistos}) (48:
+\&                             U+101D0..101FF)
+\&   \ep{Block: Phoenician}   (NOT \ep{Phoenician} NOR \ep{Is_Phoenician})
+\&                             (32: U+10900..1091F)
+\&   \ep{Block: Phonetic_Ext} \ep{Block=Phonetic_Extensions} (128)
+\&   \ep{Block: Phonetic_Ext_Sup} \ep{Block=
+\&                             Phonetic_Extensions_Supplement} (64)
+\&   \ep{Block: Phonetic_Extensions} (Short: \ep{Blk=PhoneticExt}) (128:
+\&                             U+1D00..1D7F)
+\&   \ep{Block: Phonetic_Extensions_Supplement} (Short: \ep{Blk=
+\&                             PhoneticExtSup}) (64: U+1D80..1DBF)
+\&   \ep{Block: Playing_Cards} (96: U+1F0A0..1F0FF)
+\&   \ep{Block: Private_Use}  \ep{Block=Private_Use_Area} (NOT
+\&                             \ep{Private_Use} NOR \ep{Is_Private_Use})
+\&                             (6400)
+\&   \ep{Block: Private_Use_Area} (Short: \ep{Blk=PUA}; NOT
+\&                             \ep{Private_Use} NOR \ep{Is_Private_Use})
+\&                             (6400: U+E000..F8FF)
+\&   \ep{Block: Psalter_Pahlavi} (NOT \ep{Psalter_Pahlavi} NOR
+\&                             \ep{Is_Psalter_Pahlavi}) (48:
+\&                             U+10B80..10BAF)
+\&   \ep{Block: PUA}          \ep{Block=Private_Use_Area} (NOT
+\&                             \ep{Private_Use} NOR \ep{Is_Private_Use})
+\&                             (6400)
+\&   \ep{Block: Punctuation}  \ep{Block=General_Punctuation} (NOT
+\&                             \ep{Punct} NOR \ep{Is_Punctuation}) (112)
+\&   \ep{Block: Rejang}       (NOT \ep{Rejang} NOR \ep{Is_Rejang}) (48:
+\&                             U+A930..A95F)
+\&   \ep{Block: Rumi}         \ep{Block=Rumi_Numeral_Symbols} (32)
+\&   \ep{Block: Rumi_Numeral_Symbols} (Short: \ep{Blk=Rumi}) (32:
+\&                             U+10E60..10E7F)
+\&   \ep{Block: Runic}        (NOT \ep{Runic} NOR \ep{Is_Runic}) (96:
+\&                             U+16A0..16FF)
+\&   \ep{Block: Samaritan}    (NOT \ep{Samaritan} NOR \ep{Is_Samaritan})
+\&                             (64: U+0800..083F)
+\&   \ep{Block: Saurashtra}   (NOT \ep{Saurashtra} NOR \ep{Is_Saurashtra})
+\&                             (96: U+A880..A8DF)
+\&   \ep{Block: Sharada}      (NOT \ep{Sharada} NOR \ep{Is_Sharada}) (96:
+\&                             U+11180..111DF)
+\&   \ep{Block: Shavian}      (48: U+10450..1047F)
+\&   \ep{Block: Shorthand_Format_Controls} (16: U+1BCA0..1BCAF)
+\&   \ep{Block: Siddham}      (NOT \ep{Siddham} NOR \ep{Is_Siddham}) (128:
+\&                             U+11580..115FF)
+\&   \ep{Block: Sinhala}      (NOT \ep{Sinhala} NOR \ep{Is_Sinhala}) (128:
+\&                             U+0D80..0DFF)
+\&   \ep{Block: Sinhala_Archaic_Numbers} (32: U+111E0..111FF)
+\&   \ep{Block: Small_Form_Variants} (Short: \ep{Blk=SmallForms}) (32:
+\&                             U+FE50..FE6F)
+\&   \ep{Block: Small_Forms}  \ep{Block=Small_Form_Variants} (32)
+\&   \ep{Block: Small_Kana_Ext} \ep{Block=Small_Kana_Extension} (64)
+\&   \ep{Block: Small_Kana_Extension} (Short: \ep{Blk=SmallKanaExt}) (64:
+\&                             U+1B130..1B16F)
+\&   \ep{Block: Sogdian}      (NOT \ep{Sogdian} NOR \ep{Is_Sogdian}) (64:
+\&                             U+10F30..10F6F)
+\&   \ep{Block: Sora_Sompeng} (NOT \ep{Sora_Sompeng} NOR
+\&                             \ep{Is_Sora_Sompeng}) (48: U+110D0..110FF)
+\&   \ep{Block: Soyombo}      (NOT \ep{Soyombo} NOR \ep{Is_Soyombo}) (96:
+\&                             U+11A50..11AAF)
+\&   \ep{Block: Spacing_Modifier_Letters} (Short: \ep{Blk=
+\&                             ModifierLetters}) (80: U+02B0..02FF)
+\&   \ep{Block: Specials}     (16: U+FFF0..FFFF)
+\&   \ep{Block: Sundanese}    (NOT \ep{Sundanese} NOR \ep{Is_Sundanese})
+\&                             (64: U+1B80..1BBF)
+\&   \ep{Block: Sundanese_Sup} \ep{Block=Sundanese_Supplement} (16)
+\&   \ep{Block: Sundanese_Supplement} (Short: \ep{Blk=SundaneseSup}) (16:
+\&                             U+1CC0..1CCF)
+\&   \ep{Block: Sup_Arrows_A} \ep{Block=Supplemental_Arrows_A} (16)
+\&   \ep{Block: Sup_Arrows_B} \ep{Block=Supplemental_Arrows_B} (128)
+\&   \ep{Block: Sup_Arrows_C} \ep{Block=Supplemental_Arrows_C} (256)
+\&   \ep{Block: Sup_Math_Operators} \ep{Block=
+\&                             Supplemental_Mathematical_Operators}
+\&                             (256)
+\&   \ep{Block: Sup_PUA_A}    \ep{Block=Supplementary_Private_Use_Area_A}
+\&                             (65_536)
+\&   \ep{Block: Sup_PUA_B}    \ep{Block=Supplementary_Private_Use_Area_B}
+\&                             (65_536)
+\&   \ep{Block: Sup_Punctuation} \ep{Block=Supplemental_Punctuation} (128)
+\&   \ep{Block: Sup_Symbols_And_Pictographs} \ep{Block=
+\&                             Supplemental_Symbols_And_Pictographs}
+\&                             (256)
+\&   \ep{Block: Super_And_Sub} \ep{Block=Superscripts_And_Subscripts} (48)
+\&   \ep{Block: Superscripts_And_Subscripts} (Short: \ep{Blk=
+\&                             SuperAndSub}) (48: U+2070..209F)
+\&   \ep{Block: Supplemental_Arrows_A} (Short: \ep{Blk=SupArrowsA}) (16:
+\&                             U+27F0..27FF)
+\&   \ep{Block: Supplemental_Arrows_B} (Short: \ep{Blk=SupArrowsB}) (128:
+\&                             U+2900..297F)
+\&   \ep{Block: Supplemental_Arrows_C} (Short: \ep{Blk=SupArrowsC}) (256:
+\&                             U+1F800..1F8FF)
+\&   \ep{Block: Supplemental_Mathematical_Operators} (Short: \ep{Blk=
+\&                             SupMathOperators}) (256: U+2A00..2AFF)
+\&   \ep{Block: Supplemental_Punctuation} (Short: \ep{Blk=
+\&                             SupPunctuation}) (128: U+2E00..2E7F)
+\&   \ep{Block: Supplemental_Symbols_And_Pictographs} (Short: \ep{Blk=
+\&                             SupSymbolsAndPictographs}) (256:
+\&                             U+1F900..1F9FF)
+\&   \ep{Block: Supplementary_Private_Use_Area_A} (Short: \ep{Blk=
+\&                             SupPUAA}) (65_536: U+F0000..FFFFF)
+\&   \ep{Block: Supplementary_Private_Use_Area_B} (Short: \ep{Blk=
+\&                             SupPUAB}) (65_536: U+100000..10FFFF)
+\&   \ep{Block: Sutton_SignWriting} (688: U+1D800..1DAAF)
+\&   \ep{Block: Syloti_Nagri} (NOT \ep{Syloti_Nagri} NOR
+\&                             \ep{Is_Syloti_Nagri}) (48: U+A800..A82F)
+\&   \ep{Block: Symbols_And_Pictographs_Ext_A} \ep{Block=
+\&                             Symbols_And_Pictographs_Extended_A} (144)
+\&   \ep{Block: Symbols_And_Pictographs_Extended_A} (Short: \ep{Blk=
+\&                             SymbolsAndPictographsExtA}) (144:
+\&                             U+1FA70..1FAFF)
+\&   \ep{Block: Symbols_For_Legacy_Computing} (256: U+1FB00..1FBFF)
+\&   \ep{Block: Syriac}       (NOT \ep{Syriac} NOR \ep{Is_Syriac}) (80:
+\&                             U+0700..074F)
+\&   \ep{Block: Syriac_Sup}   \ep{Block=Syriac_Supplement} (16)
+\&   \ep{Block: Syriac_Supplement} (Short: \ep{Blk=SyriacSup}) (16:
+\&                             U+0860..086F)
+\&   \ep{Block: Tagalog}      (NOT \ep{Tagalog} NOR \ep{Is_Tagalog}) (32:
+\&                             U+1700..171F)
+\&   \ep{Block: Tagbanwa}     (NOT \ep{Tagbanwa} NOR \ep{Is_Tagbanwa})
+\&                             (32: U+1760..177F)
+\&   \ep{Block: Tags}         (128: U+E0000..E007F)
+\&   \ep{Block: Tai_Le}       (NOT \ep{Tai_Le} NOR \ep{Is_Tai_Le}) (48:
+\&                             U+1950..197F)
+\&   \ep{Block: Tai_Tham}     (NOT \ep{Tai_Tham} NOR \ep{Is_Tai_Tham})
+\&                             (144: U+1A20..1AAF)
+\&   \ep{Block: Tai_Viet}     (NOT \ep{Tai_Viet} NOR \ep{Is_Tai_Viet})
+\&                             (96: U+AA80..AADF)
+\&   \ep{Block: Tai_Xuan_Jing} \ep{Block=Tai_Xuan_Jing_Symbols} (96)
+\&   \ep{Block: Tai_Xuan_Jing_Symbols} (Short: \ep{Blk=TaiXuanJing}) (96:
+\&                             U+1D300..1D35F)
+\&   \ep{Block: Takri}        (NOT \ep{Takri} NOR \ep{Is_Takri}) (80:
+\&                             U+11680..116CF)
+\&   \ep{Block: Tamil}        (NOT \ep{Tamil} NOR \ep{Is_Tamil}) (128:
+\&                             U+0B80..0BFF)
+\&   \ep{Block: Tamil_Sup}    \ep{Block=Tamil_Supplement} (64)
+\&   \ep{Block: Tamil_Supplement} (Short: \ep{Blk=TamilSup}) (64:
+\&                             U+11FC0..11FFF)
+\&   \ep{Block: Tangsa}       (NOT \ep{Tangsa} NOR \ep{Is_Tangsa}) (96:
+\&                             U+16A70..16ACF)
+\&   \ep{Block: Tangut}       (NOT \ep{Tangut} NOR \ep{Is_Tangut}) (6144:
+\&                             U+17000..187FF)
+\&   \ep{Block: Tangut_Components} (768: U+18800..18AFF)
+\&   \ep{Block: Tangut_Sup}   \ep{Block=Tangut_Supplement} (128)
+\&   \ep{Block: Tangut_Supplement} (Short: \ep{Blk=TangutSup}) (128:
+\&                             U+18D00..18D7F)
+\&   \ep{Block: Telugu}       (NOT \ep{Telugu} NOR \ep{Is_Telugu}) (128:
+\&                             U+0C00..0C7F)
+\&   \ep{Block: Thaana}       (NOT \ep{Thaana} NOR \ep{Is_Thaana}) (64:
+\&                             U+0780..07BF)
+\&   \ep{Block: Thai}         (NOT \ep{Thai} NOR \ep{Is_Thai}) (128:
+\&                             U+0E00..0E7F)
+\&   \ep{Block: Tibetan}      (NOT \ep{Tibetan} NOR \ep{Is_Tibetan}) (256:
+\&                             U+0F00..0FFF)
+\&   \ep{Block: Tifinagh}     (NOT \ep{Tifinagh} NOR \ep{Is_Tifinagh})
+\&                             (80: U+2D30..2D7F)
+\&   \ep{Block: Tirhuta}      (NOT \ep{Tirhuta} NOR \ep{Is_Tirhuta}) (96:
+\&                             U+11480..114DF)
+\&   \ep{Block: Toto}         (NOT \ep{Toto} NOR \ep{Is_Toto}) (48:
+\&                             U+1E290..1E2BF)
+\&   \ep{Block: Transport_And_Map} \ep{Block=Transport_And_Map_Symbols}
+\&                             (128)
+\&   \ep{Block: Transport_And_Map_Symbols} (Short: \ep{Blk=
+\&                             TransportAndMap}) (128: U+1F680..1F6FF)
+\&   \ep{Block: UCAS}         \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics}
+\&                             (640)
+\&   \ep{Block: UCAS_Ext}     \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended} (80)
+\&   \ep{Block: UCAS_Ext_A}   \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended_A} (16)
+\&   \ep{Block: Ugaritic}     (NOT \ep{Ugaritic} NOR \ep{Is_Ugaritic})
+\&                             (32: U+10380..1039F)
+\&   \ep{Block: Unified_Canadian_Aboriginal_Syllabics} (Short: \ep{Blk=
+\&                             UCAS}) (640: U+1400..167F)
+\&   \ep{Block: Unified_Canadian_Aboriginal_Syllabics_Extended} (Short:
+\&                             \ep{Blk=UCASExt}) (80: U+18B0..18FF)
+\&   \ep{Block: Unified_Canadian_Aboriginal_Syllabics_Extended_A}
+\&                             (Short: \ep{Blk=UCASExtA}) (16:
+\&                             U+11AB0..11ABF)
+\&   \ep{Block: Vai}          (NOT \ep{Vai} NOR \ep{Is_Vai}) (320:
+\&                             U+A500..A63F)
+\&   \ep{Block: Variation_Selectors} (Short: \ep{Blk=VS}; NOT
+\&                             \ep{Variation_Selector} NOR \ep{Is_VS})
+\&                             (16: U+FE00..FE0F)
+\&   \ep{Block: Variation_Selectors_Supplement} (Short: \ep{Blk=VSSup})
+\&                             (240: U+E0100..E01EF)
+\&   \ep{Block: Vedic_Ext}    \ep{Block=Vedic_Extensions} (48)
+\&   \ep{Block: Vedic_Extensions} (Short: \ep{Blk=VedicExt}) (48:
+\&                             U+1CD0..1CFF)
+\&   \ep{Block: Vertical_Forms} (16: U+FE10..FE1F)
+\&   \ep{Block: Vithkuqi}     (NOT \ep{Vithkuqi} NOR \ep{Is_Vithkuqi})
+\&                             (80: U+10570..105BF)
+\&   \ep{Block: VS}           \ep{Block=Variation_Selectors} (NOT
+\&                             \ep{Variation_Selector} NOR \ep{Is_VS})
+\&                             (16)
+\&   \ep{Block: VS_Sup}       \ep{Block=Variation_Selectors_Supplement}
+\&                             (240)
+\&   \ep{Block: Wancho}       (NOT \ep{Wancho} NOR \ep{Is_Wancho}) (64:
+\&                             U+1E2C0..1E2FF)
+\&   \ep{Block: Warang_Citi}  (NOT \ep{Warang_Citi} NOR
+\&                             \ep{Is_Warang_Citi}) (96: U+118A0..118FF)
+\&   \ep{Block: Yezidi}       (NOT \ep{Yezidi} NOR \ep{Is_Yezidi}) (64:
+\&                             U+10E80..10EBF)
+\&   \ep{Block: Yi_Radicals}  (64: U+A490..A4CF)
+\&   \ep{Block: Yi_Syllables} (1168: U+A000..A48F)
+\&   \ep{Block: Yijing}       \ep{Block=Yijing_Hexagram_Symbols} (64)
+\&   \ep{Block: Yijing_Hexagram_Symbols} (Short: \ep{Blk=Yijing}) (64:
+\&                             U+4DC0..4DFF)
+\&   \ep{Block: Zanabazar_Square} (NOT \ep{Zanabazar_Square} NOR
+\&                             \ep{Is_Zanabazar_Square}) (80:
+\&                             U+11A00..11A4F)
+\&   \ep{Block: Znamenny_Music} \ep{Block=Znamenny_Musical_Notation} (208)
+\&   \ep{Block: Znamenny_Musical_Notation} (Short: \ep{Blk=
+\&                             ZnamennyMusic}) (208: U+1CF00..1CFCF)
+\& X \ep{Block_Elements}      \ep{Block=Block_Elements} (32)
+\&   \ep{Bopo}                \ep{Bopomofo} (= \ep{Script_Extensions=
+\&                             Bopomofo}) (NOT \ep{Block=Bopomofo}) (117)
+\&   \ep{Bopomofo}            \ep{Script_Extensions=Bopomofo} (Short:
+\&                             \ep{Bopo}; NOT \ep{Block=Bopomofo}) (117)
+\& X \ep{Bopomofo_Ext}        \ep{Bopomofo_Extended} (= \ep{Block=
+\&                             Bopomofo_Extended}) (32)
+\& X \ep{Bopomofo_Extended}   \ep{Block=Bopomofo_Extended} (Short:
+\&                             \ep{InBopomofoExt}) (32)
+\& X \ep{Box_Drawing}         \ep{Block=Box_Drawing} (128)
+\&   \ep{Bpt: *}              \ep{Bidi_Paired_Bracket_Type: *}
+\&   \ep{Brah}                \ep{Brahmi} (= \ep{Script_Extensions=
+\&                             Brahmi}) (NOT \ep{Block=Brahmi}) (115)
+\&   \ep{Brahmi}              \ep{Script_Extensions=Brahmi} (Short:
+\&                             \ep{Brah}; NOT \ep{Block=Brahmi}) (115)
+\&   \ep{Brai}                \ep{Braille} (= \ep{Script_Extensions=
+\&                             Braille}) (256)
+\&   \ep{Braille}             \ep{Script_Extensions=Braille} (Short:
+\&                             \ep{Brai}) (256)
+\& X \ep{Braille_Patterns}    \ep{Block=Braille_Patterns} (Short:
+\&                             \ep{InBraille}) (256)
+\&   \ep{Bugi}                \ep{Buginese} (= \ep{Script_Extensions=
+\&                             Buginese}) (NOT \ep{Block=Buginese}) (31)
+\&   \ep{Buginese}            \ep{Script_Extensions=Buginese} (Short:
+\&                             \ep{Bugi}; NOT \ep{Block=Buginese}) (31)
+\&   \ep{Buhd}                \ep{Buhid} (= \ep{Script_Extensions=Buhid})
+\&                             (NOT \ep{Block=Buhid}) (22)
+\&   \ep{Buhid}               \ep{Script_Extensions=Buhid} (Short:
+\&                             \ep{Buhd}; NOT \ep{Block=Buhid}) (22)
+\& X \ep{Byzantine_Music}     \ep{Byzantine_Musical_Symbols} (= \ep{Block=
+\&                             Byzantine_Musical_Symbols}) (256)
+\& X \ep{Byzantine_Musical_Symbols} \ep{Block=Byzantine_Musical_Symbols}
+\&                             (Short: \ep{InByzantineMusic}) (256)
+\&   \ep{C} \epC               \ep{Other} (= \ep{General_Category=Other})
+\&                             (965_096 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Cakm}                \ep{Chakma} (= \ep{Script_Extensions=
+\&                             Chakma}) (NOT \ep{Block=Chakma}) (91)
+\&   \ep{Canadian_Aboriginal} \ep{Script_Extensions=Canadian_Aboriginal}
+\&                             (Short: \ep{Cans}) (726)
+\& X \ep{Canadian_Syllabics}  \ep{Unified_Canadian_Aboriginal_Syllabics}
+\&                             (= \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics})
+\&                             (640)
+\& T \ep{Canonical_Combining_Class: 0} \ep{Canonical_Combining_Class=
+\&                             Not_Reordered} (1_113_190 plus all
+\&                             above\-Unicode code points)
+\& T \ep{Canonical_Combining_Class: 1} \ep{Canonical_Combining_Class=
+\&                             Overlay} (32)
+\& T \ep{Canonical_Combining_Class: 6} \ep{Canonical_Combining_Class=
+\&                             Han_Reading} (2)
+\& T \ep{Canonical_Combining_Class: 7} \ep{Canonical_Combining_Class=
+\&                             Nukta} (27)
+\& T \ep{Canonical_Combining_Class: 8} \ep{Canonical_Combining_Class=
+\&                             Kana_Voicing} (2)
+\& T \ep{Canonical_Combining_Class: 9} \ep{Canonical_Combining_Class=
+\&                             Virama} (65)
+\& T \ep{Canonical_Combining_Class: 10} \ep{Canonical_Combining_Class=
+\&                             CCC10} (1)
+\&   \ep{Canonical_Combining_Class: CCC10} (Short: \ep{Ccc=CCC10}) (1:
+\&                             U+05B0)
+\& T \ep{Canonical_Combining_Class: 11} \ep{Canonical_Combining_Class=
+\&                             CCC11} (1)
+\&   \ep{Canonical_Combining_Class: CCC11} (Short: \ep{Ccc=CCC11}) (1:
+\&                             U+05B1)
+\& T \ep{Canonical_Combining_Class: 12} \ep{Canonical_Combining_Class=
+\&                             CCC12} (1)
+\&   \ep{Canonical_Combining_Class: CCC12} (Short: \ep{Ccc=CCC12}) (1:
+\&                             U+05B2)
+\& T \ep{Canonical_Combining_Class: 13} \ep{Canonical_Combining_Class=
+\&                             CCC13} (1)
+\&   \ep{Canonical_Combining_Class: CCC13} (Short: \ep{Ccc=CCC13}) (1:
+\&                             U+05B3)
+\& T \ep{Canonical_Combining_Class: 14} \ep{Canonical_Combining_Class=
+\&                             CCC14} (1)
+\&   \ep{Canonical_Combining_Class: CCC14} (Short: \ep{Ccc=CCC14}) (1:
+\&                             U+05B4)
+\& T \ep{Canonical_Combining_Class: 15} \ep{Canonical_Combining_Class=
+\&                             CCC15} (1)
+\&   \ep{Canonical_Combining_Class: CCC15} (Short: \ep{Ccc=CCC15}) (1:
+\&                             U+05B5)
+\& T \ep{Canonical_Combining_Class: 16} \ep{Canonical_Combining_Class=
+\&                             CCC16} (1)
+\&   \ep{Canonical_Combining_Class: CCC16} (Short: \ep{Ccc=CCC16}) (1:
+\&                             U+05B6)
+\& T \ep{Canonical_Combining_Class: 17} \ep{Canonical_Combining_Class=
+\&                             CCC17} (1)
+\&   \ep{Canonical_Combining_Class: CCC17} (Short: \ep{Ccc=CCC17}) (1:
+\&                             U+05B7)
+\& T \ep{Canonical_Combining_Class: 18} \ep{Canonical_Combining_Class=
+\&                             CCC18} (2)
+\&   \ep{Canonical_Combining_Class: CCC18} (Short: \ep{Ccc=CCC18}) (2:
+\&                             U+05B8, U+05C7)
+\& T \ep{Canonical_Combining_Class: 19} \ep{Canonical_Combining_Class=
+\&                             CCC19} (2)
+\&   \ep{Canonical_Combining_Class: CCC19} (Short: \ep{Ccc=CCC19}) (2:
+\&                             U+05B9..05BA)
+\& T \ep{Canonical_Combining_Class: 20} \ep{Canonical_Combining_Class=
+\&                             CCC20} (1)
+\&   \ep{Canonical_Combining_Class: CCC20} (Short: \ep{Ccc=CCC20}) (1:
+\&                             U+05BB)
+\& T \ep{Canonical_Combining_Class: 21} \ep{Canonical_Combining_Class=
+\&                             CCC21} (1)
+\&   \ep{Canonical_Combining_Class: CCC21} (Short: \ep{Ccc=CCC21}) (1:
+\&                             U+05BC)
+\& T \ep{Canonical_Combining_Class: 22} \ep{Canonical_Combining_Class=
+\&                             CCC22} (1)
+\&   \ep{Canonical_Combining_Class: CCC22} (Short: \ep{Ccc=CCC22}) (1:
+\&                             U+05BD)
+\& T \ep{Canonical_Combining_Class: 23} \ep{Canonical_Combining_Class=
+\&                             CCC23} (1)
+\&   \ep{Canonical_Combining_Class: CCC23} (Short: \ep{Ccc=CCC23}) (1:
+\&                             U+05BF)
+\& T \ep{Canonical_Combining_Class: 24} \ep{Canonical_Combining_Class=
+\&                             CCC24} (1)
+\&   \ep{Canonical_Combining_Class: CCC24} (Short: \ep{Ccc=CCC24}) (1:
+\&                             U+05C1)
+\& T \ep{Canonical_Combining_Class: 25} \ep{Canonical_Combining_Class=
+\&                             CCC25} (1)
+\&   \ep{Canonical_Combining_Class: CCC25} (Short: \ep{Ccc=CCC25}) (1:
+\&                             U+05C2)
+\& T \ep{Canonical_Combining_Class: 26} \ep{Canonical_Combining_Class=
+\&                             CCC26} (1)
+\&   \ep{Canonical_Combining_Class: CCC26} (Short: \ep{Ccc=CCC26}) (1:
+\&                             U+FB1E)
+\& T \ep{Canonical_Combining_Class: 27} \ep{Canonical_Combining_Class=
+\&                             CCC27} (2)
+\&   \ep{Canonical_Combining_Class: CCC27} (Short: \ep{Ccc=CCC27}) (2:
+\&                             U+064B, U+08F0)
+\& T \ep{Canonical_Combining_Class: 28} \ep{Canonical_Combining_Class=
+\&                             CCC28} (2)
+\&   \ep{Canonical_Combining_Class: CCC28} (Short: \ep{Ccc=CCC28}) (2:
+\&                             U+064C, U+08F1)
+\& T \ep{Canonical_Combining_Class: 29} \ep{Canonical_Combining_Class=
+\&                             CCC29} (2)
+\&   \ep{Canonical_Combining_Class: CCC29} (Short: \ep{Ccc=CCC29}) (2:
+\&                             U+064D, U+08F2)
+\& T \ep{Canonical_Combining_Class: 30} \ep{Canonical_Combining_Class=
+\&                             CCC30} (2)
+\&   \ep{Canonical_Combining_Class: CCC30} (Short: \ep{Ccc=CCC30}) (2:
+\&                             U+0618, U+064E)
+\& T \ep{Canonical_Combining_Class: 31} \ep{Canonical_Combining_Class=
+\&                             CCC31} (2)
+\&   \ep{Canonical_Combining_Class: CCC31} (Short: \ep{Ccc=CCC31}) (2:
+\&                             U+0619, U+064F)
+\& T \ep{Canonical_Combining_Class: 32} \ep{Canonical_Combining_Class=
+\&                             CCC32} (2)
+\&   \ep{Canonical_Combining_Class: CCC32} (Short: \ep{Ccc=CCC32}) (2:
+\&                             U+061A, U+0650)
+\& T \ep{Canonical_Combining_Class: 33} \ep{Canonical_Combining_Class=
+\&                             CCC33} (1)
+\&   \ep{Canonical_Combining_Class: CCC33} (Short: \ep{Ccc=CCC33}) (1:
+\&                             U+0651)
+\& T \ep{Canonical_Combining_Class: 34} \ep{Canonical_Combining_Class=
+\&                             CCC34} (1)
+\&   \ep{Canonical_Combining_Class: CCC34} (Short: \ep{Ccc=CCC34}) (1:
+\&                             U+0652)
+\& T \ep{Canonical_Combining_Class: 35} \ep{Canonical_Combining_Class=
+\&                             CCC35} (1)
+\&   \ep{Canonical_Combining_Class: CCC35} (Short: \ep{Ccc=CCC35}) (1:
+\&                             U+0670)
+\& T \ep{Canonical_Combining_Class: 36} \ep{Canonical_Combining_Class=
+\&                             CCC36} (1)
+\&   \ep{Canonical_Combining_Class: CCC36} (Short: \ep{Ccc=CCC36}) (1:
+\&                             U+0711)
+\& T \ep{Canonical_Combining_Class: 84} \ep{Canonical_Combining_Class=
+\&                             CCC84} (1)
+\&   \ep{Canonical_Combining_Class: CCC84} (Short: \ep{Ccc=CCC84}) (1:
+\&                             U+0C55)
+\& T \ep{Canonical_Combining_Class: 91} \ep{Canonical_Combining_Class=
+\&                             CCC91} (1)
+\&   \ep{Canonical_Combining_Class: CCC91} (Short: \ep{Ccc=CCC91}) (1:
+\&                             U+0C56)
+\& T \ep{Canonical_Combining_Class: 103} \ep{Canonical_Combining_Class=
+\&                             CCC103} (2)
+\&   \ep{Canonical_Combining_Class: CCC103} (Short: \ep{Ccc=CCC103}) (2:
+\&                             U+0E38..0E39)
+\& T \ep{Canonical_Combining_Class: 107} \ep{Canonical_Combining_Class=
+\&                             CCC107} (4)
+\&   \ep{Canonical_Combining_Class: CCC107} (Short: \ep{Ccc=CCC107}) (4:
+\&                             U+0E48..0E4B)
+\& T \ep{Canonical_Combining_Class: 118} \ep{Canonical_Combining_Class=
+\&                             CCC118} (2)
+\&   \ep{Canonical_Combining_Class: CCC118} (Short: \ep{Ccc=CCC118}) (2:
+\&                             U+0EB8..0EB9)
+\& T \ep{Canonical_Combining_Class: 122} \ep{Canonical_Combining_Class=
+\&                             CCC122} (4)
+\&   \ep{Canonical_Combining_Class: CCC122} (Short: \ep{Ccc=CCC122}) (4:
+\&                             U+0EC8..0ECB)
+\& T \ep{Canonical_Combining_Class: 129} \ep{Canonical_Combining_Class=
+\&                             CCC129} (1)
+\&   \ep{Canonical_Combining_Class: CCC129} (Short: \ep{Ccc=CCC129}) (1:
+\&                             U+0F71)
+\& T \ep{Canonical_Combining_Class: 130} \ep{Canonical_Combining_Class=
+\&                             CCC130} (6)
+\&   \ep{Canonical_Combining_Class: CCC130} (Short: \ep{Ccc=CCC130}) (6:
+\&                             U+0F72, U+0F7A..0F7D, U+0F80)
+\& T \ep{Canonical_Combining_Class: 132} \ep{Canonical_Combining_Class=
+\&                             CCC132} (1)
+\&   \ep{Canonical_Combining_Class: CCC132} (Short: \ep{Ccc=CCC132}) (1:
+\&                             U+0F74)
+\& T \ep{Canonical_Combining_Class: 133} \ep{Canonical_Combining_Class=
+\&                             CCC133} (0)
+\&   \ep{Canonical_Combining_Class: CCC133} (Short: \ep{Ccc=CCC133}) (0)
+\& T \ep{Canonical_Combining_Class: 200} \ep{Canonical_Combining_Class=
+\&                             Attached_Below_Left} (0)
+\& T \ep{Canonical_Combining_Class: 202} \ep{Canonical_Combining_Class=
+\&                             Attached_Below} (5)
+\& T \ep{Canonical_Combining_Class: 214} \ep{Canonical_Combining_Class=
+\&                             Attached_Above} (1)
+\& T \ep{Canonical_Combining_Class: 216} \ep{Canonical_Combining_Class=
+\&                             Attached_Above_Right} (9)
+\& T \ep{Canonical_Combining_Class: 218} \ep{Canonical_Combining_Class=
+\&                             Below_Left} (2)
+\& T \ep{Canonical_Combining_Class: 220} \ep{Canonical_Combining_Class=
+\&                             Below} (181)
+\& T \ep{Canonical_Combining_Class: 222} \ep{Canonical_Combining_Class=
+\&                             Below_Right} (4)
+\& T \ep{Canonical_Combining_Class: 224} \ep{Canonical_Combining_Class=
+\&                             Left} (2)
+\& T \ep{Canonical_Combining_Class: 226} \ep{Canonical_Combining_Class=
+\&                             Right} (1)
+\& T \ep{Canonical_Combining_Class: 228} \ep{Canonical_Combining_Class=
+\&                             Above_Left} (5)
+\& T \ep{Canonical_Combining_Class: 230} \ep{Canonical_Combining_Class=
+\&                             Above} (510)
+\& T \ep{Canonical_Combining_Class: 232} \ep{Canonical_Combining_Class=
+\&                             Above_Right} (7)
+\& T \ep{Canonical_Combining_Class: 233} \ep{Canonical_Combining_Class=
+\&                             Double_Below} (4)
+\& T \ep{Canonical_Combining_Class: 234} \ep{Canonical_Combining_Class=
+\&                             Double_Above} (5)
+\& T \ep{Canonical_Combining_Class: 240} \ep{Canonical_Combining_Class=
+\&                             Iota_Subscript} (1)
+\&   \ep{Canonical_Combining_Class: A} \ep{Canonical_Combining_Class=
+\&                             Above} (510)
+\&   \ep{Canonical_Combining_Class: Above} (Short: \ep{Ccc=A}) (510:
+\&                             U+0300..0314, U+033D..0344, U+0346,
+\&                             U+034A..034C, U+0350..0352, U+0357 ...)
+\&   \ep{Canonical_Combining_Class: Above_Left} (Short: \ep{Ccc=AL}) (5:
+\&                             U+05AE, U+18A9, U+1DF7..1DF8, U+302B)
+\&   \ep{Canonical_Combining_Class: Above_Right} (Short: \ep{Ccc=AR}) (7:
+\&                             U+0315, U+031A, U+0358, U+1DF6, U+302C,
+\&                             U+1E4EC..1E4ED)
+\&   \ep{Canonical_Combining_Class: AL} \ep{Canonical_Combining_Class=
+\&                             Above_Left} (5)
+\&   \ep{Canonical_Combining_Class: AR} \ep{Canonical_Combining_Class=
+\&                             Above_Right} (7)
+\&   \ep{Canonical_Combining_Class: ATA} \ep{Canonical_Combining_Class=
+\&                             Attached_Above} (1)
+\&   \ep{Canonical_Combining_Class: ATAR} \ep{Canonical_Combining_Class=
+\&                             Attached_Above_Right} (9)
+\&   \ep{Canonical_Combining_Class: ATB} \ep{Canonical_Combining_Class=
+\&                             Attached_Below} (5)
+\&   \ep{Canonical_Combining_Class: ATBL} \ep{Canonical_Combining_Class=
+\&                             Attached_Below_Left} (0)
+\&   \ep{Canonical_Combining_Class: Attached_Above} (Short: \ep{Ccc=ATA})
+\&                             (1: U+1DCE)
+\&   \ep{Canonical_Combining_Class: Attached_Above_Right} (Short:
+\&                             \ep{Ccc=ATAR}) (9: U+031B, U+0F39,
+\&                             U+1D165..1D166, U+1D16E..1D172)
+\&   \ep{Canonical_Combining_Class: Attached_Below} (Short: \ep{Ccc=ATB})
+\&                             (5: U+0321..0322, U+0327..0328, U+1DD0)
+\&   \ep{Canonical_Combining_Class: Attached_Below_Left} (Short: \ep{Ccc=
+\&                             ATBL}) (0)
+\&   \ep{Canonical_Combining_Class: B} \ep{Canonical_Combining_Class=
+\&                             Below} (181)
+\&   \ep{Canonical_Combining_Class: Below} (Short: \ep{Ccc=B}) (181:
+\&                             U+0316..0319, U+031C..0320,
+\&                             U+0323..0326, U+0329..0333,
+\&                             U+0339..033C, U+0347..0349 ...)
+\&   \ep{Canonical_Combining_Class: Below_Left} (Short: \ep{Ccc=BL}) (2:
+\&                             U+1DFA, U+302A)
+\&   \ep{Canonical_Combining_Class: Below_Right} (Short: \ep{Ccc=BR}) (4:
+\&                             U+059A, U+05AD, U+1939, U+302D)
+\&   \ep{Canonical_Combining_Class: BL} \ep{Canonical_Combining_Class=
+\&                             Below_Left} (2)
+\&   \ep{Canonical_Combining_Class: BR} \ep{Canonical_Combining_Class=
+\&                             Below_Right} (4)
+\&   \ep{Canonical_Combining_Class: DA} \ep{Canonical_Combining_Class=
+\&                             Double_Above} (5)
+\&   \ep{Canonical_Combining_Class: DB} \ep{Canonical_Combining_Class=
+\&                             Double_Below} (4)
+\&   \ep{Canonical_Combining_Class: Double_Above} (Short: \ep{Ccc=DA})
+\&                             (5: U+035D..035E, U+0360..0361, U+1DCD)
+\&   \ep{Canonical_Combining_Class: Double_Below} (Short: \ep{Ccc=DB})
+\&                             (4: U+035C, U+035F, U+0362, U+1DFC)
+\&   \ep{Canonical_Combining_Class: Han_Reading} (Short: \ep{Ccc=HANR})
+\&                             (2: U+16FF0..16FF1)
+\&   \ep{Canonical_Combining_Class: HANR} \ep{Canonical_Combining_Class=
+\&                             Han_Reading} (2)
+\&   \ep{Canonical_Combining_Class: Iota_Subscript} (Short: \ep{Ccc=IS})
+\&                             (1: U+0345)
+\&   \ep{Canonical_Combining_Class: IS} \ep{Canonical_Combining_Class=
+\&                             Iota_Subscript} (1)
+\&   \ep{Canonical_Combining_Class: Kana_Voicing} (Short: \ep{Ccc=KV})
+\&                             (2: U+3099..309A)
+\&   \ep{Canonical_Combining_Class: KV} \ep{Canonical_Combining_Class=
+\&                             Kana_Voicing} (2)
+\&   \ep{Canonical_Combining_Class: L} \ep{Canonical_Combining_Class=
+\&                             Left} (2)
+\&   \ep{Canonical_Combining_Class: Left} (Short: \ep{Ccc=L}) (2:
+\&                             U+302E..302F)
+\&   \ep{Canonical_Combining_Class: NK} \ep{Canonical_Combining_Class=
+\&                             Nukta} (27)
+\&   \ep{Canonical_Combining_Class: Not_Reordered} (Short: \ep{Ccc=NR})
+\&                             (1_113_190 plus all above\-Unicode code
+\&                             points: U+0000..02FF, U+034F,
+\&                             U+0370..0482, U+0488..0590, U+05BE,
+\&                             U+05C0 ...)
+\&   \ep{Canonical_Combining_Class: NR} \ep{Canonical_Combining_Class=
+\&                             Not_Reordered} (1_113_190 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Canonical_Combining_Class: Nukta} (Short: \ep{Ccc=NK}) (27:
+\&                             U+093C, U+09BC, U+0A3C, U+0ABC, U+0B3C,
+\&                             U+0C3C ...)
+\&   \ep{Canonical_Combining_Class: OV} \ep{Canonical_Combining_Class=
+\&                             Overlay} (32)
+\&   \ep{Canonical_Combining_Class: Overlay} (Short: \ep{Ccc=OV}) (32:
+\&                             U+0334..0338, U+1CD4, U+1CE2..1CE8,
+\&                             U+20D2..20D3, U+20D8..20DA, U+20E5..20E6
+\&                             ...)
+\&   \ep{Canonical_Combining_Class: R} \ep{Canonical_Combining_Class=
+\&                             Right} (1)
+\&   \ep{Canonical_Combining_Class: Right} (Short: \ep{Ccc=R}) (1:
+\&                             U+1D16D)
+\&   \ep{Canonical_Combining_Class: Virama} (Short: \ep{Ccc=VR}) (65:
+\&                             U+094D, U+09CD, U+0A4D, U+0ACD, U+0B4D,
+\&                             U+0BCD ...)
+\&   \ep{Canonical_Combining_Class: VR} \ep{Canonical_Combining_Class=
+\&                             Virama} (65)
+\&   \ep{Cans}                \ep{Canadian_Aboriginal} (=
+\&                             \ep{Script_Extensions=
+\&                             Canadian_Aboriginal}) (726)
+\&   \ep{Cari}                \ep{Carian} (= \ep{Script_Extensions=
+\&                             Carian}) (NOT \ep{Block=Carian}) (49)
+\&   \ep{Carian}              \ep{Script_Extensions=Carian} (Short:
+\&                             \ep{Cari}; NOT \ep{Block=Carian}) (49)
+\&   \ep{Case_Ignorable}      \ep{Case_Ignorable=Y} (Short: \ep{CI}) (2707)
+\&   \ep{Case_Ignorable: N*}  (Short: \ep{CI=N}, \eP{CI}) (1_111_405 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex20!\e"#\e$\e%&\e(\e)*+,\e\-\e/0\-9;<=>?\e@A\-Z
+\&                             \e[\e\e\e]_a\-z\e{\e|\e}~\ex7f\-\exa7\exa9\-\exac\exae
+\&                             \exb0\-\exb3\exb5\-\exb6\exb9\-\exff],
+\&                             U+0100..02AF, U+0370..0373,
+\&                             U+0376..0379, U+037B..0383, U+0386 ...)
+\&   \ep{Case_Ignorable: Y*}  (Short: \ep{CI=Y}, \ep{CI}) (2707: [\e\*(Aq.:\e^\`
+\&                             \exa8\exad\exaf\exb4\exb7\-\exb8],
+\&                             U+02B0..036F, U+0374..0375, U+037A,
+\&                             U+0384..0385, U+0387 ...)
+\&   \ep{Cased}               \ep{Cased=Y} (4526)
+\&   \ep{Cased: N*}           (Single: \eP{Cased}) (1_109_586 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@\e[\e\e\e]
+\&                             \e^_\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4\exb6\-\exb9
+\&                             \exbb\-\exbf\exd7\exf7], U+01BB,
+\&                             U+01C0..01C3, U+0294, U+02B9..02BF,
+\&                             U+02C2..02DF ...)
+\&   \ep{Cased: Y*}           (Single: \ep{Cased}) (4526: [A\-Za\-z\exaa
+\&                             \exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..01BA, U+01BC..01BF,
+\&                             U+01C4..0293, U+0295..02B8, U+02C0..02C1
+\&                             ...)
+\&   \ep{Cased_Letter}        \ep{General_Category=Cased_Letter} (Short:
+\&                             \ep{LC}) (4095)
+\&   \ep{Category: *}         \ep{General_Category: *}
+\&   \ep{Caucasian_Albanian}  \ep{Script_Extensions=Caucasian_Albanian}
+\&                             (Short: \ep{Aghb}; NOT \ep{Block=
+\&                             Caucasian_Albanian}) (53)
+\&   \ep{Cc}                  \ep{XPosixCntrl} (= \ep{General_Category=
+\&                             Control}) (65)
+\&   \ep{Ccc: *}              \ep{Canonical_Combining_Class: *}
+\&   \ep{CE}                  \ep{Composition_Exclusion} (=
+\&                             \ep{Composition_Exclusion=Y}) (81)
+\&   \ep{CE: *}               \ep{Composition_Exclusion: *}
+\&   \ep{Cf}                  \ep{Format} (= \ep{General_Category=Format})
+\&                             (170)
+\&   \ep{Chakma}              \ep{Script_Extensions=Chakma} (Short:
+\&                             \ep{Cakm}; NOT \ep{Block=Chakma}) (91)
+\&   \ep{Cham}                \ep{Script_Extensions=Cham} (NOT \ep{Block=
+\&                             Cham}) (83)
+\&   \ep{Changes_When_Casefolded} \ep{Changes_When_Casefolded=Y} (Short:
+\&                             \ep{CWCF}) (1506)
+\&   \ep{Changes_When_Casefolded: N*} (Short: \ep{CWCF=N}, \eP{CWCF})
+\&                             (1_112_606 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-
+\&                             \exb4\exb6\-\exbf\exd7\exe0\-\exff], U+0101,
+\&                             U+0103, U+0105, U+0107, U+0109 ...)
+\&   \ep{Changes_When_Casefolded: Y*} (Short: \ep{CWCF=Y}, \ep{CWCF})
+\&                             (1506: [A\-Z\exb5\exc0\-\exd6\exd8\-\exdf],
+\&                             U+0100, U+0102, U+0104, U+0106, U+0108
+\&                             ...)
+\&   \ep{Changes_When_Casemapped} \ep{Changes_When_Casemapped=Y} (Short:
+\&                             \ep{CWCM}) (2927)
+\&   \ep{Changes_When_Casemapped: N*} (Short: \ep{CWCM=N}, \eP{CWCM})
+\&                             (1_111_185 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-\exb4
+\&                             \exb6\-\exbf\exd7\exf7], U+0138, U+018D,
+\&                             U+019B, U+01AA..01AB, U+01BA..01BB ...)
+\&   \ep{Changes_When_Casemapped: Y*} (Short: \ep{CWCM=Y}, \ep{CWCM})
+\&                             (2927: [A\-Za\-z\exb5\exc0\-\exd6\exd8\-\exf6
+\&                             \exf8\-\exff], U+0100..0137, U+0139..018C,
+\&                             U+018E..019A, U+019C..01A9, U+01AC..01B9
+\&                             ...)
+\&   \ep{Changes_When_Lowercased} \ep{Changes_When_Lowercased=Y} (Short:
+\&                             \ep{CWL}) (1433)
+\&   \ep{Changes_When_Lowercased: N*} (Short: \ep{CWL=N}, \eP{CWL})
+\&                             (1_112_679 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-
+\&                             \exbf\exd7\exdf\-\exff], U+0101, U+0103,
+\&                             U+0105, U+0107, U+0109 ...)
+\&   \ep{Changes_When_Lowercased: Y*} (Short: \ep{CWL=Y}, \ep{CWL}) (1433:
+\&                             [A\-Z\exc0\-\exd6\exd8\-\exde], U+0100, U+0102,
+\&                             U+0104, U+0106, U+0108 ...)
+\&   \ep{Changes_When_NFKC_Casefolded} \ep{Changes_When_NFKC_Casefolded=
+\&                             Y} (Short: \ep{CWKCF}) (10_491)
+\&   \ep{Changes_When_NFKC_Casefolded: N*} (Short: \ep{CWKCF=N},
+\&                             \eP{CWKCF}) (1_103_621 plus all above\-
+\&                             Unicode code points: [\ex00\-\ex20!\e"#\e$
+\&                             \e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`a\-
+\&                             z\e{\e|\e}~\ex7f\-\ex9f\exa1\-\exa7\exa9\exab\-\exac
+\&                             \exae\exb0\-\exb1\exb6\-\exb7\exbb\exbf\exd7\exe0\-
+\&                             \exff], U+0101, U+0103, U+0105, U+0107,
+\&                             U+0109 ...)
+\&   \ep{Changes_When_NFKC_Casefolded: Y*} (Short: \ep{CWKCF=Y},
+\&                             \ep{CWKCF}) (10_491: [A\-Z\exa0\exa8\exaa
+\&                             \exad\exaf\exb2\-\exb5\exb8\-\exba\exbc\-\exbe\exc0\-
+\&                             \exd6\exd8\-\exdf], U+0100, U+0102, U+0104,
+\&                             U+0106, U+0108 ...)
+\&   \ep{Changes_When_Titlecased} \ep{Changes_When_Titlecased=Y} (Short:
+\&                             \ep{CWT}) (1452)
+\&   \ep{Changes_When_Titlecased: N*} (Short: \ep{CWT=N}, \eP{CWT})
+\&                             (1_112_660 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-
+\&                             \exb4\exb6\-\exde\exf7], U+0100, U+0102,
+\&                             U+0104, U+0106, U+0108 ...)
+\&   \ep{Changes_When_Titlecased: Y*} (Short: \ep{CWT=Y}, \ep{CWT}) (1452:
+\&                             [a\-z\exb5\exdf\-\exf6\exf8\-\exff], U+0101,
+\&                             U+0103, U+0105, U+0107, U+0109 ...)
+\&   \ep{Changes_When_Uppercased} \ep{Changes_When_Uppercased=Y} (Short:
+\&                             \ep{CWU}) (1525)
+\&   \ep{Changes_When_Uppercased: N*} (Short: \ep{CWU=N}, \eP{CWU})
+\&                             (1_112_587 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-
+\&                             \exb4\exb6\-\exde\exf7], U+0100, U+0102,
+\&                             U+0104, U+0106, U+0108 ...)
+\&   \ep{Changes_When_Uppercased: Y*} (Short: \ep{CWU=Y}, \ep{CWU}) (1525:
+\&                             [a\-z\exb5\exdf\-\exf6\exf8\-\exff], U+0101,
+\&                             U+0103, U+0105, U+0107, U+0109 ...)
+\&   \ep{Cher}                \ep{Cherokee} (= \ep{Script_Extensions=
+\&                             Cherokee}) (NOT \ep{Block=Cherokee}) (172)
+\&   \ep{Cherokee}            \ep{Script_Extensions=Cherokee} (Short:
+\&                             \ep{Cher}; NOT \ep{Block=Cherokee}) (172)
+\& X \ep{Cherokee_Sup}        \ep{Cherokee_Supplement} (= \ep{Block=
+\&                             Cherokee_Supplement}) (80)
+\& X \ep{Cherokee_Supplement} \ep{Block=Cherokee_Supplement} (Short:
+\&                             \ep{InCherokeeSup}) (80)
+\& X \ep{Chess_Symbols}       \ep{Block=Chess_Symbols} (112)
+\&   \ep{Chorasmian}          \ep{Script_Extensions=Chorasmian} (Short:
+\&                             \ep{Chrs}; NOT \ep{Block=Chorasmian}) (28)
+\&   \ep{Chrs}                \ep{Chorasmian} (= \ep{Script_Extensions=
+\&                             Chorasmian}) (NOT \ep{Block=Chorasmian})
+\&                             (28)
+\&   \ep{CI}                  \ep{Case_Ignorable} (= \ep{Case_Ignorable=
+\&                             Y}) (2707)
+\&   \ep{CI: *}               \ep{Case_Ignorable: *}
+\& X \ep{CJK}                 \ep{CJK_Unified_Ideographs} (= \ep{Block=
+\&                             CJK_Unified_Ideographs}) (20_992)
+\& X \ep{CJK_Compat}          \ep{CJK_Compatibility} (= \ep{Block=
+\&                             CJK_Compatibility}) (256)
+\& X \ep{CJK_Compat_Forms}    \ep{CJK_Compatibility_Forms} (= \ep{Block=
+\&                             CJK_Compatibility_Forms}) (32)
+\& X \ep{CJK_Compat_Ideographs} \ep{CJK_Compatibility_Ideographs} (=
+\&                             \ep{Block=CJK_Compatibility_Ideographs})
+\&                             (512)
+\& X \ep{CJK_Compat_Ideographs_Sup}
+\&                             \ep{CJK_Compatibility_Ideographs_\-
+\&                             Supplement} (= \ep{Block=
+\&                             CJK_Compatibility_Ideographs_\-
+\&                             Supplement}) (544)
+\& X \ep{CJK_Compatibility}   \ep{Block=CJK_Compatibility} (Short:
+\&                             \ep{InCJKCompat}) (256)
+\& X \ep{CJK_Compatibility_Forms} \ep{Block=CJK_Compatibility_Forms}
+\&                             (Short: \ep{InCJKCompatForms}) (32)
+\& X \ep{CJK_Compatibility_Ideographs} \ep{Block=
+\&                             CJK_Compatibility_Ideographs} (Short:
+\&                             \ep{InCJKCompatIdeographs}) (512)
+\& X \ep{CJK_Compatibility_Ideographs_Supplement} \ep{Block=
+\&                             CJK_Compatibility_Ideographs_Supplement}
+\&                             (Short: \ep{InCJKCompatIdeographsSup})
+\&                             (544)
+\& X \ep{CJK_Ext_A}           \ep{CJK_Unified_Ideographs_Extension_A} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_A})
+\&                             (6592)
+\& X \ep{CJK_Ext_B}           \ep{CJK_Unified_Ideographs_Extension_B} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_B})
+\&                             (42_720)
+\& X \ep{CJK_Ext_C}           \ep{CJK_Unified_Ideographs_Extension_C} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_C})
+\&                             (4160)
+\& X \ep{CJK_Ext_D}           \ep{CJK_Unified_Ideographs_Extension_D} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_D})
+\&                             (224)
+\& X \ep{CJK_Ext_E}           \ep{CJK_Unified_Ideographs_Extension_E} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_E})
+\&                             (5776)
+\& X \ep{CJK_Ext_F}           \ep{CJK_Unified_Ideographs_Extension_F} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_F})
+\&                             (7488)
+\& X \ep{CJK_Ext_G}           \ep{CJK_Unified_Ideographs_Extension_G} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_G})
+\&                             (4944)
+\& X \ep{CJK_Ext_H}           \ep{CJK_Unified_Ideographs_Extension_H} (=
+\&                             \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_H})
+\&                             (4192)
+\& X \ep{CJK_Radicals_Sup}    \ep{CJK_Radicals_Supplement} (= \ep{Block=
+\&                             CJK_Radicals_Supplement}) (128)
+\& X \ep{CJK_Radicals_Supplement} \ep{Block=CJK_Radicals_Supplement}
+\&                             (Short: \ep{InCJKRadicalsSup}) (128)
+\& X \ep{CJK_Strokes}         \ep{Block=CJK_Strokes} (48)
+\& X \ep{CJK_Symbols}         \ep{CJK_Symbols_And_Punctuation} (=
+\&                             \ep{Block=CJK_Symbols_And_Punctuation})
+\&                             (64)
+\& X \ep{CJK_Symbols_And_Punctuation} \ep{Block=
+\&                             CJK_Symbols_And_Punctuation} (Short:
+\&                             \ep{InCJKSymbols}) (64)
+\& X \ep{CJK_Unified_Ideographs} \ep{Block=CJK_Unified_Ideographs}
+\&                             (Short: \ep{InCJK}) (20_992)
+\& X \ep{CJK_Unified_Ideographs_Extension_A} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_A}
+\&                             (Short: \ep{InCJKExtA}) (6592)
+\& X \ep{CJK_Unified_Ideographs_Extension_B} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_B}
+\&                             (Short: \ep{InCJKExtB}) (42_720)
+\& X \ep{CJK_Unified_Ideographs_Extension_C} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_C}
+\&                             (Short: \ep{InCJKExtC}) (4160)
+\& X \ep{CJK_Unified_Ideographs_Extension_D} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_D}
+\&                             (Short: \ep{InCJKExtD}) (224)
+\& X \ep{CJK_Unified_Ideographs_Extension_E} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_E}
+\&                             (Short: \ep{InCJKExtE}) (5776)
+\& X \ep{CJK_Unified_Ideographs_Extension_F} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_F}
+\&                             (Short: \ep{InCJKExtF}) (7488)
+\& X \ep{CJK_Unified_Ideographs_Extension_G} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_G}
+\&                             (Short: \ep{InCJKExtG}) (4944)
+\& X \ep{CJK_Unified_Ideographs_Extension_H} \ep{Block=
+\&                             CJK_Unified_Ideographs_Extension_H}
+\&                             (Short: \ep{InCJKExtH}) (4192)
+\&   \ep{Close_Punctuation}   \ep{General_Category=Close_Punctuation}
+\&                             (Short: \ep{Pe}) (77)
+\&   \ep{Cn}                  \ep{Unassigned} (= \ep{General_Category=
+\&                             Unassigned}) (825_345 plus all above\-
+\&                             Unicode code points)
+\&   \ep{Cntrl}               \ep{XPosixCntrl} (= \ep{General_Category=
+\&                             Control}) (65)
+\&   \ep{Co}                  \ep{Private_Use} (= \ep{General_Category=
+\&                             Private_Use}) (NOT \ep{Private_Use_Area})
+\&                             (137_468)
+\& X \ep{Combining_Diacritical_Marks} \ep{Block=
+\&                             Combining_Diacritical_Marks} (Short:
+\&                             \ep{InDiacriticals}) (112)
+\& X \ep{Combining_Diacritical_Marks_Extended} \ep{Block=
+\&                             Combining_Diacritical_Marks_Extended}
+\&                             (Short: \ep{InDiacriticalsExt}) (80)
+\& X \ep{Combining_Diacritical_Marks_For_Symbols} \ep{Block=
+\&                             Combining_Diacritical_Marks_For_Symbols}
+\&                             (Short: \ep{InDiacriticalsForSymbols})
+\&                             (48)
+\& X \ep{Combining_Diacritical_Marks_Supplement} \ep{Block=
+\&                             Combining_Diacritical_Marks_Supplement}
+\&                             (Short: \ep{InDiacriticalsSup}) (64)
+\& X \ep{Combining_Half_Marks} \ep{Block=Combining_Half_Marks} (Short:
+\&                             \ep{InHalfMarks}) (16)
+\&   \ep{Combining_Mark}      \ep{Mark} (= \ep{General_Category=Mark})
+\&                             (2450)
+\& X \ep{Combining_Marks_For_Symbols}
+\&                             \ep{Combining_Diacritical_Marks_For_\-
+\&                             Symbols} (= \ep{Block=
+\&                             Combining_Diacritical_Marks_For_\-
+\&                             Symbols}) (48)
+\&   \ep{Common}              \ep{Script_Extensions=Common} (Short:
+\&                             \ep{Zyyy}) (7873)
+\& X \ep{Common_Indic_Number_Forms} \ep{Block=Common_Indic_Number_Forms}
+\&                             (Short: \ep{InIndicNumberForms}) (16)
+\&   \ep{Comp_Ex}             \ep{Full_Composition_Exclusion} (=
+\&                             \ep{Full_Composition_Exclusion=Y}) (1120)
+\&   \ep{Comp_Ex: *}          \ep{Full_Composition_Exclusion: *}
+\& X \ep{Compat_Jamo}         \ep{Hangul_Compatibility_Jamo} (= \ep{Block=
+\&                             Hangul_Compatibility_Jamo}) (96)
+\&   \ep{Composition_Exclusion} \ep{Composition_Exclusion=Y} (Short:
+\&                             \ep{CE}) (81)
+\&   \ep{Composition_Exclusion: N*} (Short: \ep{CE=N}, \eP{CE}) (1_114_031
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..0957, U+0960..09DB, U+09DE,
+\&                             U+09E0..0A32, U+0A34..0A35, U+0A37..0A58
+\&                             ...)
+\&   \ep{Composition_Exclusion: Y*} (Short: \ep{CE=Y}, \ep{CE}) (81:
+\&                             U+0958..095F, U+09DC..09DD, U+09DF,
+\&                             U+0A33, U+0A36, U+0A59..0A5B ...)
+\&   \ep{Connector_Punctuation} \ep{General_Category=
+\&                             Connector_Punctuation} (Short: \ep{Pc})
+\&                             (10)
+\&   \ep{Control}             \ep{XPosixCntrl} (= \ep{General_Category=
+\&                             Control}) (65)
+\& X \ep{Control_Pictures}    \ep{Block=Control_Pictures} (64)
+\&   \ep{Copt}                \ep{Coptic} (= \ep{Script_Extensions=
+\&                             Coptic}) (NOT \ep{Block=Coptic}) (165)
+\&   \ep{Coptic}              \ep{Script_Extensions=Coptic} (Short:
+\&                             \ep{Copt}; NOT \ep{Block=Coptic}) (165)
+\& X \ep{Coptic_Epact_Numbers} \ep{Block=Coptic_Epact_Numbers} (32)
+\& X \ep{Counting_Rod}        \ep{Counting_Rod_Numerals} (= \ep{Block=
+\&                             Counting_Rod_Numerals}) (32)
+\& X \ep{Counting_Rod_Numerals} \ep{Block=Counting_Rod_Numerals} (Short:
+\&                             \ep{InCountingRod}) (32)
+\&   \ep{Cpmn}                \ep{Cypro_Minoan} (= \ep{Script_Extensions=
+\&                             Cypro_Minoan}) (NOT \ep{Block=
+\&                             Cypro_Minoan}) (101)
+\&   \ep{Cprt}                \ep{Cypriot} (= \ep{Script_Extensions=
+\&                             Cypriot}) (112)
+\&   \ep{Cs}                  \ep{Surrogate} (= \ep{General_Category=
+\&                             Surrogate}) (2048)
+\&   \ep{Cuneiform}           \ep{Script_Extensions=Cuneiform} (Short:
+\&                             \ep{Xsux}; NOT \ep{Block=Cuneiform}) (1234)
+\& X \ep{Cuneiform_Numbers}   \ep{Cuneiform_Numbers_And_Punctuation} (=
+\&                             \ep{Block=
+\&                             Cuneiform_Numbers_And_Punctuation}) (128)
+\& X \ep{Cuneiform_Numbers_And_Punctuation} \ep{Block=
+\&                             Cuneiform_Numbers_And_Punctuation}
+\&                             (Short: \ep{InCuneiformNumbers}) (128)
+\&   \ep{Currency_Symbol}     \ep{General_Category=Currency_Symbol}
+\&                             (Short: \ep{Sc}) (63)
+\& X \ep{Currency_Symbols}    \ep{Block=Currency_Symbols} (48)
+\&   \ep{CWCF}                \ep{Changes_When_Casefolded} (=
+\&                             \ep{Changes_When_Casefolded=Y}) (1506)
+\&   \ep{CWCF: *}             \ep{Changes_When_Casefolded: *}
+\&   \ep{CWCM}                \ep{Changes_When_Casemapped} (=
+\&                             \ep{Changes_When_Casemapped=Y}) (2927)
+\&   \ep{CWCM: *}             \ep{Changes_When_Casemapped: *}
+\&   \ep{CWKCF}               \ep{Changes_When_NFKC_Casefolded} (=
+\&                             \ep{Changes_When_NFKC_Casefolded=Y})
+\&                             (10_491)
+\&   \ep{CWKCF: *}            \ep{Changes_When_NFKC_Casefolded: *}
+\&   \ep{CWL}                 \ep{Changes_When_Lowercased} (=
+\&                             \ep{Changes_When_Lowercased=Y}) (1433)
+\&   \ep{CWL: *}              \ep{Changes_When_Lowercased: *}
+\&   \ep{CWT}                 \ep{Changes_When_Titlecased} (=
+\&                             \ep{Changes_When_Titlecased=Y}) (1452)
+\&   \ep{CWT: *}              \ep{Changes_When_Titlecased: *}
+\&   \ep{CWU}                 \ep{Changes_When_Uppercased} (=
+\&                             \ep{Changes_When_Uppercased=Y}) (1525)
+\&   \ep{CWU: *}              \ep{Changes_When_Uppercased: *}
+\&   \ep{Cypriot}             \ep{Script_Extensions=Cypriot} (Short:
+\&                             \ep{Cprt}) (112)
+\& X \ep{Cypriot_Syllabary}   \ep{Block=Cypriot_Syllabary} (64)
+\&   \ep{Cypro_Minoan}        \ep{Script_Extensions=Cypro_Minoan} (Short:
+\&                             \ep{Cpmn}; NOT \ep{Block=Cypro_Minoan})
+\&                             (101)
+\&   \ep{Cyrillic}            \ep{Script_Extensions=Cyrillic} (Short:
+\&                             \ep{Cyrl}; NOT \ep{Block=Cyrillic}) (510)
+\& X \ep{Cyrillic_Ext_A}      \ep{Cyrillic_Extended_A} (= \ep{Block=
+\&                             Cyrillic_Extended_A}) (32)
+\& X \ep{Cyrillic_Ext_B}      \ep{Cyrillic_Extended_B} (= \ep{Block=
+\&                             Cyrillic_Extended_B}) (96)
+\& X \ep{Cyrillic_Ext_C}      \ep{Cyrillic_Extended_C} (= \ep{Block=
+\&                             Cyrillic_Extended_C}) (16)
+\& X \ep{Cyrillic_Ext_D}      \ep{Cyrillic_Extended_D} (= \ep{Block=
+\&                             Cyrillic_Extended_D}) (96)
+\& X \ep{Cyrillic_Extended_A} \ep{Block=Cyrillic_Extended_A} (Short:
+\&                             \ep{InCyrillicExtA}) (32)
+\& X \ep{Cyrillic_Extended_B} \ep{Block=Cyrillic_Extended_B} (Short:
+\&                             \ep{InCyrillicExtB}) (96)
+\& X \ep{Cyrillic_Extended_C} \ep{Block=Cyrillic_Extended_C} (Short:
+\&                             \ep{InCyrillicExtC}) (16)
+\& X \ep{Cyrillic_Extended_D} \ep{Block=Cyrillic_Extended_D} (Short:
+\&                             \ep{InCyrillicExtD}) (96)
+\& X \ep{Cyrillic_Sup}        \ep{Cyrillic_Supplement} (= \ep{Block=
+\&                             Cyrillic_Supplement}) (48)
+\& X \ep{Cyrillic_Supplement} \ep{Block=Cyrillic_Supplement} (Short:
+\&                             \ep{InCyrillicSup}) (48)
+\& X \ep{Cyrillic_Supplementary} \ep{Cyrillic_Supplement} (= \ep{Block=
+\&                             Cyrillic_Supplement}) (48)
+\&   \ep{Cyrl}                \ep{Cyrillic} (= \ep{Script_Extensions=
+\&                             Cyrillic}) (NOT \ep{Block=Cyrillic}) (510)
+\&   \ep{Dash}                \ep{Dash=Y} (30)
+\&   \ep{Dash: N*}            (Single: \eP{Dash}) (1_114_082 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,.\e/0\-9:;<=>?\e@A\-Z
+\&                             \e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..0589, U+058B..05BD,
+\&                             U+05BF..13FF, U+1401..1805, U+1807..200F
+\&                             ...)
+\&   \ep{Dash: Y*}            (Single: \ep{Dash}) (30: [\e\-], U+058A,
+\&                             U+05BE, U+1400, U+1806, U+2010..2015 ...)
+\&   \ep{Dash_Punctuation}    \ep{General_Category=Dash_Punctuation}
+\&                             (Short: \ep{Pd}) (26)
+\&   \ep{Decimal_Number}      \ep{XPosixDigit} (= \ep{General_Category=
+\&                             Decimal_Number}) (680)
+\&   \ep{Decomposition_Type: Can} \ep{Decomposition_Type=Canonical}
+\&                             (13_233)
+\&   \ep{Decomposition_Type: Canonical} (Short: \ep{Dt=Can}) (13_233:
+\&                             [\exc0\-\exc5\exc7\-\excf\exd1\-\exd6\exd9\-\exdd
+\&                             \exe0\-\exe5\exe7\-\exef\exf1\-\exf6\exf9\-\exfd
+\&                             \exff], U+0100..010F, U+0112..0125,
+\&                             U+0128..0130, U+0134..0137, U+0139..013E
+\&                             ...)
+\&   \ep{Decomposition_Type: Circle} (Short: \ep{Dt=Enc}) (240:
+\&                             U+2460..2473, U+24B6..24EA,
+\&                             U+3244..3247, U+3251..327E,
+\&                             U+3280..32BF, U+32D0..32FE ...)
+\&   \ep{Decomposition_Type: Com} \ep{Decomposition_Type=Compat} (720)
+\&   \ep{Decomposition_Type: Compat} (Short: \ep{Dt=Com}) (720: [\exa8
+\&                             \exaf\exb4\-\exb5\exb8], U+0132..0133,
+\&                             U+013F..0140, U+0149, U+017F,
+\&                             U+01C4..01CC ...)
+\&   \ep{Decomposition_Type: Enc} \ep{Decomposition_Type=Circle} (240)
+\&   \ep{Decomposition_Type: Fin} \ep{Decomposition_Type=Final} (240)
+\&   \ep{Decomposition_Type: Final} (Short: \ep{Dt=Fin}) (240: U+FB51,
+\&                             U+FB53, U+FB57, U+FB5B, U+FB5F, U+FB63
+\&                             ...)
+\&   \ep{Decomposition_Type: Font} (Short: \ep{Dt=Font}) (1194: U+2102,
+\&                             U+210A..2113, U+2115, U+2119..211D,
+\&                             U+2124, U+2128 ...)
+\&   \ep{Decomposition_Type: Fra} \ep{Decomposition_Type=Fraction} (20)
+\&   \ep{Decomposition_Type: Fraction} (Short: \ep{Dt=Fra}) (20: [\exbc\-
+\&                             \exbe], U+2150..215F, U+2189)
+\&   \ep{Decomposition_Type: Init} \ep{Decomposition_Type=Initial} (171)
+\&   \ep{Decomposition_Type: Initial} (Short: \ep{Dt=Init}) (171: U+FB54,
+\&                             U+FB58, U+FB5C, U+FB60, U+FB64, U+FB68
+\&                             ...)
+\&   \ep{Decomposition_Type: Iso} \ep{Decomposition_Type=Isolated} (238)
+\&   \ep{Decomposition_Type: Isolated} (Short: \ep{Dt=Iso}) (238: U+FB50,
+\&                             U+FB52, U+FB56, U+FB5A, U+FB5E, U+FB62
+\&                             ...)
+\&   \ep{Decomposition_Type: Med} \ep{Decomposition_Type=Medial} (82)
+\&   \ep{Decomposition_Type: Medial} (Short: \ep{Dt=Med}) (82: U+FB55,
+\&                             U+FB59, U+FB5D, U+FB61, U+FB65, U+FB69
+\&                             ...)
+\&   \ep{Decomposition_Type: Nar} \ep{Decomposition_Type=Narrow} (122)
+\&   \ep{Decomposition_Type: Narrow} (Short: \ep{Dt=Nar}) (122:
+\&                             U+FF61..FFBE, U+FFC2..FFC7,
+\&                             U+FFCA..FFCF, U+FFD2..FFD7,
+\&                             U+FFDA..FFDC, U+FFE8..FFEE)
+\&   \ep{Decomposition_Type: Nb} \ep{Decomposition_Type=Nobreak} (5)
+\&   \ep{Decomposition_Type: Nobreak} (Short: \ep{Dt=Nb}) (5: [\exa0],
+\&                             U+0F0C, U+2007, U+2011, U+202F)
+\&   \ep{Decomposition_Type: Non_Canon} \ep{Decomposition_Type=
+\&                             Non_Canonical} (Perl extension) (3796)
+\&   \ep{Decomposition_Type: Non_Canonical} Union of all non\-canonical
+\&                             decompositions (Short: \ep{Dt=NonCanon})
+\&                             (Perl extension) (3796: [\exa0\exa8\exaa
+\&                             \exaf\exb2\-\exb5\exb8\-\exba\exbc\-\exbe],
+\&                             U+0132..0133, U+013F..0140, U+0149,
+\&                             U+017F, U+01C4..01CC ...)
+\&   \ep{Decomposition_Type: None} (Short: \ep{Dt=None}) (1_097_083 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex9f\exa1\-\exa7\exa9\exab\-\exae\exb0\-\exb1\exb6\-
+\&                             \exb7\exbb\exbf\exc6\exd0\exd7\-\exd8\exde\-\exdf
+\&                             \exe6\exf0\exf7\-\exf8\exfe], U+0110..0111,
+\&                             U+0126..0127, U+0131, U+0138,
+\&                             U+0141..0142 ...)
+\&   \ep{Decomposition_Type: Small} (Short: \ep{Dt=Sml}) (26:
+\&                             U+FE50..FE52, U+FE54..FE66, U+FE68..FE6B)
+\&   \ep{Decomposition_Type: Sml} \ep{Decomposition_Type=Small} (26)
+\&   \ep{Decomposition_Type: Sqr} \ep{Decomposition_Type=Square} (286)
+\&   \ep{Decomposition_Type: Square} (Short: \ep{Dt=Sqr}) (286: U+3250,
+\&                             U+32CC..32CF, U+32FF..3357,
+\&                             U+3371..33DF, U+33FF, U+1F130..1F14F ...)
+\&   \ep{Decomposition_Type: Sub} (Short: \ep{Dt=Sub}) (64: U+1D62..1D6A,
+\&                             U+2080..208E, U+2090..209C, U+2C7C,
+\&                             U+1E051..1E06A)
+\&   \ep{Decomposition_Type: Sup} \ep{Decomposition_Type=Super} (249)
+\&   \ep{Decomposition_Type: Super} (Short: \ep{Dt=Sup}) (249: [\exaa\exb2\-
+\&                             \exb3\exb9\-\exba], U+02B0..02B8,
+\&                             U+02E0..02E4, U+10FC, U+1D2C..1D2E,
+\&                             U+1D30..1D3A ...)
+\&   \ep{Decomposition_Type: Vert} \ep{Decomposition_Type=Vertical} (35)
+\&   \ep{Decomposition_Type: Vertical} (Short: \ep{Dt=Vert}) (35: U+309F,
+\&                             U+30FF, U+FE10..FE19, U+FE30..FE44,
+\&                             U+FE47..FE48)
+\&   \ep{Decomposition_Type: Wide} (Short: \ep{Dt=Wide}) (104: U+3000,
+\&                             U+FF01..FF60, U+FFE0..FFE6)
+\&   \ep{Default_Ignorable_Code_Point} \ep{Default_Ignorable_Code_Point=
+\&                             Y} (Short: \ep{DI}) (4174)
+\&   \ep{Default_Ignorable_Code_Point: N*} (Short: \ep{DI=N}, \eP{DI})
+\&                             (1_109_938 plus all above\-Unicode code
+\&                             points: [\ex00\-\exac\exae\-\exff],
+\&                             U+0100..034E, U+0350..061B,
+\&                             U+061D..115E, U+1161..17B3, U+17B6..180A
+\&                             ...)
+\&   \ep{Default_Ignorable_Code_Point: Y*} (Short: \ep{DI=Y}, \ep{DI})
+\&                             (4174: [\exad], U+034F, U+061C,
+\&                             U+115F..1160, U+17B4..17B5, U+180B..180F
+\&                             ...)
+\&   \ep{Dep}                 \ep{Deprecated} (= \ep{Deprecated=Y}) (15)
+\&   \ep{Dep: *}              \ep{Deprecated: *}
+\&   \ep{Deprecated}          \ep{Deprecated=Y} (Short: \ep{Dep}) (15)
+\&   \ep{Deprecated: N*}      (Short: \ep{Dep=N}, \eP{Dep}) (1_114_097
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..0148, U+014A..0672,
+\&                             U+0674..0F76, U+0F78, U+0F7A..17A2,
+\&                             U+17A5..2069 ...)
+\&   \ep{Deprecated: Y*}      (Short: \ep{Dep=Y}, \ep{Dep}) (15: U+0149,
+\&                             U+0673, U+0F77, U+0F79, U+17A3..17A4,
+\&                             U+206A..206F ...)
+\&   \ep{Deseret}             \ep{Script_Extensions=Deseret} (Short:
+\&                             \ep{Dsrt}) (80)
+\&   \ep{Deva}                \ep{Devanagari} (= \ep{Script_Extensions=
+\&                             Devanagari}) (NOT \ep{Block=Devanagari})
+\&                             (220)
+\&   \ep{Devanagari}          \ep{Script_Extensions=Devanagari} (Short:
+\&                             \ep{Deva}; NOT \ep{Block=Devanagari}) (220)
+\& X \ep{Devanagari_Ext}      \ep{Devanagari_Extended} (= \ep{Block=
+\&                             Devanagari_Extended}) (32)
+\& X \ep{Devanagari_Ext_A}    \ep{Devanagari_Extended_A} (= \ep{Block=
+\&                             Devanagari_Extended_A}) (96)
+\& X \ep{Devanagari_Extended} \ep{Block=Devanagari_Extended} (Short:
+\&                             \ep{InDevanagariExt}) (32)
+\& X \ep{Devanagari_Extended_A} \ep{Block=Devanagari_Extended_A} (Short:
+\&                             \ep{InDevanagariExtA}) (96)
+\&   \ep{DI}                  \ep{Default_Ignorable_Code_Point} (=
+\&                             \ep{Default_Ignorable_Code_Point=Y})
+\&                             (4174)
+\&   \ep{DI: *}               \ep{Default_Ignorable_Code_Point: *}
+\&   \ep{Dia}                 \ep{Diacritic} (= \ep{Diacritic=Y}) (1144)
+\&   \ep{Dia: *}              \ep{Diacritic: *}
+\&   \ep{Diacritic}           \ep{Diacritic=Y} (Short: \ep{Dia}) (1144)
+\&   \ep{Diacritic: N*}       (Short: \ep{Dia=N}, \eP{Dia}) (1_112_968
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=
+\&                             >?\e@A\-Z\e[\e\e\e]_a\-z\e{\e|\e}~\ex7f\-\exa7\exa9\-
+\&                             \exae\exb0\-\exb3\exb5\-\exb6\exb9\-\exff],
+\&                             U+0100..02AF, U+034F, U+0358..035C,
+\&                             U+0363..0373, U+0376..0379 ...)
+\&   \ep{Diacritic: Y*}       (Short: \ep{Dia=Y}, \ep{Dia}) (1144: [\e^\`
+\&                             \exa8\exaf\exb4\exb7\-\exb8], U+02B0..034E,
+\&                             U+0350..0357, U+035D..0362,
+\&                             U+0374..0375, U+037A ...)
+\& X \ep{Diacriticals}        \ep{Combining_Diacritical_Marks} (=
+\&                             \ep{Block=Combining_Diacritical_Marks})
+\&                             (112)
+\& X \ep{Diacriticals_Ext}    \ep{Combining_Diacritical_Marks_Extended}
+\&                             (= \ep{Block=
+\&                             Combining_Diacritical_Marks_Extended})
+\&                             (80)
+\& X \ep{Diacriticals_For_Symbols}
+\&                             \ep{Combining_Diacritical_Marks_For_\-
+\&                             Symbols} (= \ep{Block=
+\&                             Combining_Diacritical_Marks_For_\-
+\&                             Symbols}) (48)
+\& X \ep{Diacriticals_Sup}    \ep{Combining_Diacritical_Marks_Supplement}
+\&                             (= \ep{Block=
+\&                             Combining_Diacritical_Marks_Supplement})
+\&                             (64)
+\&   \ep{Diak}                \ep{Dives_Akuru} (= \ep{Script_Extensions=
+\&                             Dives_Akuru}) (NOT \ep{Block=
+\&                             Dives_Akuru}) (72)
+\&   \ep{Digit}               \ep{XPosixDigit} (= \ep{General_Category=
+\&                             Decimal_Number}) (680)
+\& X \ep{Dingbats}            \ep{Block=Dingbats} (192)
+\&   \ep{Dives_Akuru}         \ep{Script_Extensions=Dives_Akuru} (Short:
+\&                             \ep{Diak}; NOT \ep{Block=Dives_Akuru}) (72)
+\&   \ep{Dogr}                \ep{Dogra} (= \ep{Script_Extensions=Dogra})
+\&                             (NOT \ep{Block=Dogra}) (82)
+\&   \ep{Dogra}               \ep{Script_Extensions=Dogra} (Short:
+\&                             \ep{Dogr}; NOT \ep{Block=Dogra}) (82)
+\& X \ep{Domino}              \ep{Domino_Tiles} (= \ep{Block=
+\&                             Domino_Tiles}) (112)
+\& X \ep{Domino_Tiles}        \ep{Block=Domino_Tiles} (Short:
+\&                             \ep{InDomino}) (112)
+\&   \ep{Dsrt}                \ep{Deseret} (= \ep{Script_Extensions=
+\&                             Deseret}) (80)
+\&   \ep{Dt: *}               \ep{Decomposition_Type: *}
+\&   \ep{Dupl}                \ep{Duployan} (= \ep{Script_Extensions=
+\&                             Duployan}) (NOT \ep{Block=Duployan}) (147)
+\&   \ep{Duployan}            \ep{Script_Extensions=Duployan} (Short:
+\&                             \ep{Dupl}; NOT \ep{Block=Duployan}) (147)
+\&   \ep{Ea: *}               \ep{East_Asian_Width: *}
+\& X \ep{Early_Dynastic_Cuneiform} \ep{Block=Early_Dynastic_Cuneiform}
+\&                             (208)
+\&   \ep{East_Asian_Width: A} \ep{East_Asian_Width=Ambiguous} (138_739)
+\&   \ep{East_Asian_Width: Ambiguous} (Short: \ep{Ea=A}) (138_739: [\exa1
+\&                             \exa4\exa7\-\exa8\exaa\exad\-\exae\exb0\-\exb4\exb6\-
+\&                             \exba\exbc\-\exbf\exc6\exd0\exd7\-\exd8\exde\-\exe1
+\&                             \exe6\exe8\-\exea\exec\-\exed\exf0\exf2\-\exf3\exf7\-
+\&                             \exfa\exfc\exfe], U+0101, U+0111, U+0113,
+\&                             U+011B, U+0126..0127 ...)
+\&   \ep{East_Asian_Width: F} \ep{East_Asian_Width=Fullwidth} (104)
+\&   \ep{East_Asian_Width: Fullwidth} (Short: \ep{Ea=F}) (104: U+3000,
+\&                             U+FF01..FF60, U+FFE0..FFE6)
+\&   \ep{East_Asian_Width: H} \ep{East_Asian_Width=Halfwidth} (123)
+\&   \ep{East_Asian_Width: Halfwidth} (Short: \ep{Ea=H}) (123: U+20A9,
+\&                             U+FF61..FFBE, U+FFC2..FFC7,
+\&                             U+FFCA..FFCF, U+FFD2..FFD7, U+FFDA..FFDC
+\&                             ...)
+\&   \ep{East_Asian_Width: N} \ep{East_Asian_Width=Neutral} (792_623 plus
+\&                             all above\-Unicode code points)
+\&   \ep{East_Asian_Width: Na} \ep{East_Asian_Width=Narrow} (111)
+\&   \ep{East_Asian_Width: Narrow} (Short: \ep{Ea=Na}) (111: [\ex20\-\ex7e
+\&                             \exa2\-\exa3\exa5\-\exa6\exac\exaf],
+\&                             U+27E6..27ED, U+2985..2986)
+\&   \ep{East_Asian_Width: Neutral} (Short: \ep{Ea=N}) (792_623 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex1f
+\&                             \ex7f\-\exa0\exa9\exab\exb5\exbb\exc0\-\exc5\exc7\-
+\&                             \excf\exd1\-\exd6\exd9\-\exdd\exe2\-\exe5\exe7\exeb
+\&                             \exee\-\exef\exf1\exf4\-\exf6\exfb\exfd\exff],
+\&                             U+00FF..0100, U+0102..0110, U+0112,
+\&                             U+0114..011A, U+011C..0125 ...)
+\&   \ep{East_Asian_Width: W} \ep{East_Asian_Width=Wide} (182_412)
+\&   \ep{East_Asian_Width: Wide} (Short: \ep{Ea=W}) (182_412:
+\&                             U+1100..115F, U+231A..231B,
+\&                             U+2329..232A, U+23E9..23EC, U+23F0,
+\&                             U+23F3 ...)
+\&   \ep{EBase}               \ep{Emoji_Modifier_Base} (=
+\&                             \ep{Emoji_Modifier_Base=Y}) (134)
+\&   \ep{EBase: *}            \ep{Emoji_Modifier_Base: *}
+\&   \ep{EComp}               \ep{Emoji_Component} (= \ep{Emoji_Component=
+\&                             Y}) (146)
+\&   \ep{EComp: *}            \ep{Emoji_Component: *}
+\&   \ep{Egyp}                \ep{Egyptian_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Egyptian_Hieroglyphs}) (NOT \ep{Block=
+\&                             Egyptian_Hieroglyphs}) (1110)
+\& X \ep{Egyptian_Hieroglyph_Format_Controls} \ep{Block=
+\&                             Egyptian_Hieroglyph_Format_Controls} (48)
+\&   \ep{Egyptian_Hieroglyphs} \ep{Script_Extensions=
+\&                             Egyptian_Hieroglyphs} (Short: \ep{Egyp};
+\&                             NOT \ep{Block=Egyptian_Hieroglyphs})
+\&                             (1110)
+\&   \ep{Elba}                \ep{Elbasan} (= \ep{Script_Extensions=
+\&                             Elbasan}) (NOT \ep{Block=Elbasan}) (40)
+\&   \ep{Elbasan}             \ep{Script_Extensions=Elbasan} (Short:
+\&                             \ep{Elba}; NOT \ep{Block=Elbasan}) (40)
+\&   \ep{Elym}                \ep{Elymaic} (= \ep{Script_Extensions=
+\&                             Elymaic}) (NOT \ep{Block=Elymaic}) (23)
+\&   \ep{Elymaic}             \ep{Script_Extensions=Elymaic} (Short:
+\&                             \ep{Elym}; NOT \ep{Block=Elymaic}) (23)
+\&   \ep{EMod}                \ep{Emoji_Modifier} (= \ep{Emoji_Modifier=
+\&                             Y}) (5)
+\&   \ep{EMod: *}             \ep{Emoji_Modifier: *}
+\&   \ep{Emoji}               \ep{Emoji=Y} (1424)
+\&   \ep{Emoji: N*}           (Single: \eP{Emoji}) (1_112_688 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"\e$\e%&\e\*(Aq\e(\e)+,\e\-.\e/:;<=>?\e@A\-Z\e[\e\e\e]
+\&                             \e^_\`a\-z\e{\e|\e}~\ex7f\-\exa8\exaa\-\exad\exaf\-
+\&                             \exff], U+0100..203B, U+203D..2048,
+\&                             U+204A..2121, U+2123..2138, U+213A..2193
+\&                             ...)
+\&   \ep{Emoji: Y*}           (Single: \ep{Emoji}) (1424: [#*0\-9\exa9
+\&                             \exae], U+203C, U+2049, U+2122, U+2139,
+\&                             U+2194..2199 ...)
+\&   \ep{Emoji_Component}     \ep{Emoji_Component=Y} (Short: \ep{EComp})
+\&                             (146)
+\&   \ep{Emoji_Component: N*} (Short: \ep{EComp=N}, \eP{EComp}) (1_113_966
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"\e$\e%&\e\*(Aq\e(\e)+,\e\-.\e/:;<=>?
+\&                             \e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..200C, U+200E..20E2,
+\&                             U+20E4..FE0E, U+FE10..1F1E5,
+\&                             U+1F200..1F3FA ...)
+\&   \ep{Emoji_Component: Y*} (Short: \ep{EComp=Y}, \ep{EComp}) (146:
+\&                             [#*0\-9], U+200D, U+20E3, U+FE0F,
+\&                             U+1F1E6..1F1FF, U+1F3FB..1F3FF ...)
+\&   \ep{Emoji_Modifier}      \ep{Emoji_Modifier=Y} (Short: \ep{EMod}) (5)
+\&   \ep{Emoji_Modifier: N*}  (Short: \ep{EMod=N}, \eP{EMod}) (1_114_107
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..1F3FA, U+1F400..infinity)
+\&   \ep{Emoji_Modifier: Y*}  (Short: \ep{EMod=Y}, \ep{EMod}) (5:
+\&                             U+1F3FB..1F3FF)
+\&   \ep{Emoji_Modifier_Base} \ep{Emoji_Modifier_Base=Y} (Short:
+\&                             \ep{EBase}) (134)
+\&   \ep{Emoji_Modifier_Base: N*} (Short: \ep{EBase=N}, \eP{EBase})
+\&                             (1_113_978 plus all above\-Unicode code
+\&                             points: U+0000..261C, U+261E..26F8,
+\&                             U+26FA..2709, U+270E..1F384,
+\&                             U+1F386..1F3C1, U+1F3C5..1F3C6 ...)
+\&   \ep{Emoji_Modifier_Base: Y*} (Short: \ep{EBase=Y}, \ep{EBase}) (134:
+\&                             U+261D, U+26F9, U+270A..270D, U+1F385,
+\&                             U+1F3C2..1F3C4, U+1F3C7 ...)
+\&   \ep{Emoji_Presentation}  \ep{Emoji_Presentation=Y} (Short:
+\&                             \ep{EPres}) (1205)
+\&   \ep{Emoji_Presentation: N*} (Short: \ep{EPres=N}, \eP{EPres})
+\&                             (1_112_907 plus all above\-Unicode code
+\&                             points: U+0000..2319, U+231C..23E8,
+\&                             U+23ED..23EF, U+23F1..23F2,
+\&                             U+23F4..25FC, U+25FF..2613 ...)
+\&   \ep{Emoji_Presentation: Y*} (Short: \ep{EPres=Y}, \ep{EPres}) (1205:
+\&                             U+231A..231B, U+23E9..23EC, U+23F0,
+\&                             U+23F3, U+25FD..25FE, U+2614..2615 ...)
+\& X \ep{Emoticons}           \ep{Block=Emoticons} (80)
+\& X \ep{Enclosed_Alphanum}   \ep{Enclosed_Alphanumerics} (= \ep{Block=
+\&                             Enclosed_Alphanumerics}) (160)
+\& X \ep{Enclosed_Alphanum_Sup} \ep{Enclosed_Alphanumeric_Supplement} (=
+\&                             \ep{Block=
+\&                             Enclosed_Alphanumeric_Supplement}) (256)
+\& X \ep{Enclosed_Alphanumeric_Supplement} \ep{Block=
+\&                             Enclosed_Alphanumeric_Supplement}
+\&                             (Short: \ep{InEnclosedAlphanumSup}) (256)
+\& X \ep{Enclosed_Alphanumerics} \ep{Block=Enclosed_Alphanumerics}
+\&                             (Short: \ep{InEnclosedAlphanum}) (160)
+\& X \ep{Enclosed_CJK}        \ep{Enclosed_CJK_Letters_And_Months} (=
+\&                             \ep{Block=
+\&                             Enclosed_CJK_Letters_And_Months}) (256)
+\& X \ep{Enclosed_CJK_Letters_And_Months} \ep{Block=
+\&                             Enclosed_CJK_Letters_And_Months} (Short:
+\&                             \ep{InEnclosedCJK}) (256)
+\& X \ep{Enclosed_Ideographic_Sup} \ep{Enclosed_Ideographic_Supplement}
+\&                             (= \ep{Block=
+\&                             Enclosed_Ideographic_Supplement}) (256)
+\& X \ep{Enclosed_Ideographic_Supplement} \ep{Block=
+\&                             Enclosed_Ideographic_Supplement} (Short:
+\&                             \ep{InEnclosedIdeographicSup}) (256)
+\&   \ep{Enclosing_Mark}      \ep{General_Category=Enclosing_Mark}
+\&                             (Short: \ep{Me}) (13)
+\&   \ep{EPres}               \ep{Emoji_Presentation} (=
+\&                             \ep{Emoji_Presentation=Y}) (1205)
+\&   \ep{EPres: *}            \ep{Emoji_Presentation: *}
+\&   \ep{Ethi}                \ep{Ethiopic} (= \ep{Script_Extensions=
+\&                             Ethiopic}) (NOT \ep{Block=Ethiopic}) (523)
+\&   \ep{Ethiopic}            \ep{Script_Extensions=Ethiopic} (Short:
+\&                             \ep{Ethi}; NOT \ep{Block=Ethiopic}) (523)
+\& X \ep{Ethiopic_Ext}        \ep{Ethiopic_Extended} (= \ep{Block=
+\&                             Ethiopic_Extended}) (96)
+\& X \ep{Ethiopic_Ext_A}      \ep{Ethiopic_Extended_A} (= \ep{Block=
+\&                             Ethiopic_Extended_A}) (48)
+\& X \ep{Ethiopic_Ext_B}      \ep{Ethiopic_Extended_B} (= \ep{Block=
+\&                             Ethiopic_Extended_B}) (32)
+\& X \ep{Ethiopic_Extended}   \ep{Block=Ethiopic_Extended} (Short:
+\&                             \ep{InEthiopicExt}) (96)
+\& X \ep{Ethiopic_Extended_A} \ep{Block=Ethiopic_Extended_A} (Short:
+\&                             \ep{InEthiopicExtA}) (48)
+\& X \ep{Ethiopic_Extended_B} \ep{Block=Ethiopic_Extended_B} (Short:
+\&                             \ep{InEthiopicExtB}) (32)
+\& X \ep{Ethiopic_Sup}        \ep{Ethiopic_Supplement} (= \ep{Block=
+\&                             Ethiopic_Supplement}) (32)
+\& X \ep{Ethiopic_Supplement} \ep{Block=Ethiopic_Supplement} (Short:
+\&                             \ep{InEthiopicSup}) (32)
+\&   \ep{Ext}                 \ep{Extender} (= \ep{Extender=Y}) (50)
+\&   \ep{Ext: *}              \ep{Extender: *}
+\&   \ep{Extended_Pictographic} \ep{Extended_Pictographic=Y} (Short:
+\&                             \ep{ExtPict}) (3537)
+\&   \ep{Extended_Pictographic: N*} (Short: \ep{ExtPict=N}, \eP{ExtPict})
+\&                             (1_110_575 plus all above\-Unicode code
+\&                             points: [\ex00\-\exa8\exaa\-\exad\exaf\-\exff],
+\&                             U+0100..203B, U+203D..2048,
+\&                             U+204A..2121, U+2123..2138, U+213A..2193
+\&                             ...)
+\&   \ep{Extended_Pictographic: Y*} (Short: \ep{ExtPict=Y}, \ep{ExtPict})
+\&                             (3537: [\exa9\exae], U+203C, U+2049,
+\&                             U+2122, U+2139, U+2194..2199 ...)
+\&   \ep{Extender}            \ep{Extender=Y} (Short: \ep{Ext}) (50)
+\&   \ep{Extender: N*}        (Short: \ep{Ext=N}, \eP{Ext}) (1_114_062
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\exb6\exb8\-\exff], U+0100..02CF,
+\&                             U+02D2..063F, U+0641..07F9,
+\&                             U+07FB..0B54, U+0B56..0E45 ...)
+\&   \ep{Extender: Y*}        (Short: \ep{Ext=Y}, \ep{Ext}) (50: [\exb7],
+\&                             U+02D0..02D1, U+0640, U+07FA, U+0B55,
+\&                             U+0E46 ...)
+\&   \ep{ExtPict}             \ep{Extended_Pictographic} (=
+\&                             \ep{Extended_Pictographic=Y}) (3537)
+\&   \ep{ExtPict: *}          \ep{Extended_Pictographic: *}
+\&   \ep{Final_Punctuation}   \ep{General_Category=Final_Punctuation}
+\&                             (Short: \ep{Pf}) (10)
+\&   \ep{Format}              \ep{General_Category=Format} (Short:
+\&                             \ep{Cf}) (170)
+\&   \ep{Full_Composition_Exclusion} \ep{Full_Composition_Exclusion=Y}
+\&                             (Short: \ep{CompEx}) (1120)
+\&   \ep{Full_Composition_Exclusion: N*} (Short: \ep{CompEx=N},
+\&                             \eP{CompEx}) (1_112_992 plus all above\-
+\&                             Unicode code points: U+0000..033F,
+\&                             U+0342, U+0345..0373, U+0375..037D,
+\&                             U+037F..0386, U+0388..0957 ...)
+\&   \ep{Full_Composition_Exclusion: Y*} (Short: \ep{CompEx=Y},
+\&                             \ep{CompEx}) (1120: U+0340..0341,
+\&                             U+0343..0344, U+0374, U+037E, U+0387,
+\&                             U+0958..095F ...)
+\&   \ep{Gc: *}               \ep{General_Category: *}
+\&   \ep{GCB: *}              \ep{Grapheme_Cluster_Break: *}
+\&   \ep{General_Category: C} \ep{General_Category=Other} (965_096 plus
+\&                             all above\-Unicode code points)
+\&   \ep{General_Category: Cased_Letter} [\ep{Ll}\ep{Lu}\ep{Lt}] (Short:
+\&                             \ep{Gc=LC}, \ep{LC}) (4095: [A\-Za\-z\exb5
+\&                             \exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..01BA, U+01BC..01BF,
+\&                             U+01C4..0293, U+0295..02AF, U+0370..0373
+\&                             ...)
+\&   \ep{General_Category: Cc} \ep{General_Category=Control} (65)
+\&   \ep{General_Category: Cf} \ep{General_Category=Format} (170)
+\&   \ep{General_Category: Close_Punctuation} (Short: \ep{Gc=Pe}, \ep{Pe})
+\&                             (77: [\e)\e]\e}], U+0F3B, U+0F3D, U+169C,
+\&                             U+2046, U+207E ...)
+\&   \ep{General_Category: Cn} \ep{General_Category=Unassigned} (825_345
+\&                             plus all above\-Unicode code points)
+\&   \ep{General_Category: Cntrl} \ep{General_Category=Control} (65)
+\&   \ep{General_Category: Co} \ep{General_Category=Private_Use} (137_468)
+\&   \ep{General_Category: Combining_Mark} \ep{General_Category=Mark}
+\&                             (2450)
+\&   \ep{General_Category: Connector_Punctuation} (Short: \ep{Gc=Pc},
+\&                             \ep{Pc}) (10: [_], U+203F..2040, U+2054,
+\&                             U+FE33..FE34, U+FE4D..FE4F, U+FF3F)
+\&   \ep{General_Category: Control} (Short: \ep{Gc=Cc}, \ep{Cc}) (65:
+\&                             [\ex00\-\ex1f\ex7f\-\ex9f])
+\&   \ep{General_Category: Cs} \ep{General_Category=Surrogate} (2048)
+\&   \ep{General_Category: Currency_Symbol} (Short: \ep{Gc=Sc}, \ep{Sc})
+\&                             (63: [\e$\exa2\-\exa5], U+058F, U+060B,
+\&                             U+07FE..07FF, U+09F2..09F3, U+09FB ...)
+\&   \ep{General_Category: Dash_Punctuation} (Short: \ep{Gc=Pd}, \ep{Pd})
+\&                             (26: [\e\-], U+058A, U+05BE, U+1400,
+\&                             U+1806, U+2010..2015 ...)
+\&   \ep{General_Category: Decimal_Number} (Short: \ep{Gc=Nd}, \ep{Nd})
+\&                             (680: [0\-9], U+0660..0669, U+06F0..06F9,
+\&                             U+07C0..07C9, U+0966..096F, U+09E6..09EF
+\&                             ...)
+\&   \ep{General_Category: Digit} \ep{General_Category=Decimal_Number}
+\&                             (680)
+\&   \ep{General_Category: Enclosing_Mark} (Short: \ep{Gc=Me}, \ep{Me})
+\&                             (13: U+0488..0489, U+1ABE, U+20DD..20E0,
+\&                             U+20E2..20E4, U+A670..A672)
+\&   \ep{General_Category: Final_Punctuation} (Short: \ep{Gc=Pf}, \ep{Pf})
+\&                             (10: [\exbb], U+2019, U+201D, U+203A,
+\&                             U+2E03, U+2E05 ...)
+\&   \ep{General_Category: Format} (Short: \ep{Gc=Cf}, \ep{Cf}) (170:
+\&                             [\exad], U+0600..0605, U+061C, U+06DD,
+\&                             U+070F, U+0890..0891 ...)
+\&   \ep{General_Category: Initial_Punctuation} (Short: \ep{Gc=Pi},
+\&                             \ep{Pi}) (12: [\exab], U+2018,
+\&                             U+201B..201C, U+201F, U+2039, U+2E02 ...)
+\&   \ep{General_Category: L} \ep{General_Category=Letter} (136_104)
+\& X \ep{General_Category: L&} \ep{General_Category=Cased_Letter} (4095)
+\& X \ep{General_Category: L_} \ep{General_Category=Cased_Letter} Note
+\&                             the trailing \*(Aq_\*(Aq matters in spite of
+\&                             loose matching rules. (4095)
+\&   \ep{General_Category: LC} \ep{General_Category=Cased_Letter} (4095)
+\&   \ep{General_Category: Letter} (Short: \ep{Gc=L}, \ep{L}) (136_104:
+\&                             [A\-Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6
+\&                             \exf8\-\exff], U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\&   \ep{General_Category: Letter_Number} (Short: \ep{Gc=Nl}, \ep{Nl})
+\&                             (236: U+16EE..16F0, U+2160..2182,
+\&                             U+2185..2188, U+3007, U+3021..3029,
+\&                             U+3038..303A ...)
+\&   \ep{General_Category: Line_Separator} (Short: \ep{Gc=Zl}, \ep{Zl})
+\&                             (1: U+2028)
+\&   \ep{General_Category: Ll} \ep{General_Category=Lowercase_Letter}
+\&                             (/i= General_Category=Cased_Letter)
+\&                             (2233)
+\&   \ep{General_Category: Lm} \ep{General_Category=Modifier_Letter} (397)
+\&   \ep{General_Category: Lo} \ep{General_Category=Other_Letter}
+\&                             (131_612)
+\&   \ep{General_Category: Lowercase_Letter} (Short: \ep{Gc=Ll}, \ep{Ll};
+\&                             /i= General_Category=Cased_Letter)
+\&                             (2233: [a\-z\exb5\exdf\-\exf6\exf8\-\exff],
+\&                             U+0101, U+0103, U+0105, U+0107, U+0109
+\&                             ...)
+\&   \ep{General_Category: Lt} \ep{General_Category=Titlecase_Letter}
+\&                             (/i= General_Category=Cased_Letter) (31)
+\&   \ep{General_Category: Lu} \ep{General_Category=Uppercase_Letter}
+\&                             (/i= General_Category=Cased_Letter)
+\&                             (1831)
+\&   \ep{General_Category: M} \ep{General_Category=Mark} (2450)
+\&   \ep{General_Category: Mark} (Short: \ep{Gc=M}, \ep{M}) (2450:
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{General_Category: Math_Symbol} (Short: \ep{Gc=Sm}, \ep{Sm}) (948:
+\&                             [+<=>\e|~\exac\exb1\exd7\exf7], U+03F6,
+\&                             U+0606..0608, U+2044, U+2052,
+\&                             U+207A..207C ...)
+\&   \ep{General_Category: Mc} \ep{General_Category=Spacing_Mark} (452)
+\&   \ep{General_Category: Me} \ep{General_Category=Enclosing_Mark} (13)
+\&   \ep{General_Category: Mn} \ep{General_Category=Nonspacing_Mark}
+\&                             (1985)
+\&   \ep{General_Category: Modifier_Letter} (Short: \ep{Gc=Lm}, \ep{Lm})
+\&                             (397: U+02B0..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE, U+0374 ...)
+\&   \ep{General_Category: Modifier_Symbol} (Short: \ep{Gc=Sk}, \ep{Sk})
+\&                             (125: [\e^\`\exa8\exaf\exb4\exb8],
+\&                             U+02C2..02C5, U+02D2..02DF,
+\&                             U+02E5..02EB, U+02ED, U+02EF..02FF ...)
+\&   \ep{General_Category: N} \ep{General_Category=Number} (1831)
+\&   \ep{General_Category: Nd} \ep{General_Category=Decimal_Number} (680)
+\&   \ep{General_Category: Nl} \ep{General_Category=Letter_Number} (236)
+\&   \ep{General_Category: No} \ep{General_Category=Other_Number} (915)
+\&   \ep{General_Category: Nonspacing_Mark} (Short: \ep{Gc=Mn}, \ep{Mn})
+\&                             (1985: U+0300..036F, U+0483..0487,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{General_Category: Number} (Short: \ep{Gc=N}, \ep{N}) (1831: [0\-9
+\&                             \exb2\-\exb3\exb9\exbc\-\exbe], U+0660..0669,
+\&                             U+06F0..06F9, U+07C0..07C9,
+\&                             U+0966..096F, U+09E6..09EF ...)
+\&   \ep{General_Category: Open_Punctuation} (Short: \ep{Gc=Ps}, \ep{Ps})
+\&                             (79: [\e(\e[\e{], U+0F3A, U+0F3C, U+169B,
+\&                             U+201A, U+201E ...)
+\&   \ep{General_Category: Other} (Short: \ep{Gc=C}, \ep{C}) (965_096 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex1f\ex7f\-\ex9f\exad], U+0378..0379,
+\&                             U+0380..0383, U+038B, U+038D, U+03A2 ...)
+\&   \ep{General_Category: Other_Letter} (Short: \ep{Gc=Lo}, \ep{Lo})
+\&                             (131_612: [\exaa\exba], U+01BB,
+\&                             U+01C0..01C3, U+0294, U+05D0..05EA,
+\&                             U+05EF..05F2 ...)
+\&   \ep{General_Category: Other_Number} (Short: \ep{Gc=No}, \ep{No})
+\&                             (915: [\exb2\-\exb3\exb9\exbc\-\exbe],
+\&                             U+09F4..09F9, U+0B72..0B77,
+\&                             U+0BF0..0BF2, U+0C78..0C7E, U+0D58..0D5E
+\&                             ...)
+\&   \ep{General_Category: Other_Punctuation} (Short: \ep{Gc=Po}, \ep{Po})
+\&                             (628: [!\e"#\e%&\e\*(Aq*,.\e/:;?\e@\e\e\exa1\exa7
+\&                             \exb6\-\exb7\exbf], U+037E, U+0387,
+\&                             U+055A..055F, U+0589, U+05C0 ...)
+\&   \ep{General_Category: Other_Symbol} (Short: \ep{Gc=So}, \ep{So})
+\&                             (6634: [\exa6\exa9\exae\exb0], U+0482,
+\&                             U+058D..058E, U+060E..060F, U+06DE,
+\&                             U+06E9 ...)
+\&   \ep{General_Category: P} \ep{General_Category=Punctuation} (842)
+\&   \ep{General_Category: Paragraph_Separator} (Short: \ep{Gc=Zp},
+\&                             \ep{Zp}) (1: U+2029)
+\&   \ep{General_Category: Pc} \ep{General_Category=
+\&                             Connector_Punctuation} (10)
+\&   \ep{General_Category: Pd} \ep{General_Category=Dash_Punctuation} (26)
+\&   \ep{General_Category: Pe} \ep{General_Category=Close_Punctuation}
+\&                             (77)
+\&   \ep{General_Category: Pf} \ep{General_Category=Final_Punctuation}
+\&                             (10)
+\&   \ep{General_Category: Pi} \ep{General_Category=Initial_Punctuation}
+\&                             (12)
+\&   \ep{General_Category: Po} \ep{General_Category=Other_Punctuation}
+\&                             (628)
+\&   \ep{General_Category: Private_Use} (Short: \ep{Gc=Co}, \ep{Co})
+\&                             (137_468: U+E000..F8FF, U+F0000..FFFFD,
+\&                             U+100000..10FFFD)
+\&   \ep{General_Category: Ps} \ep{General_Category=Open_Punctuation} (79)
+\&   \ep{General_Category: Punct} \ep{General_Category=Punctuation} (842)
+\&   \ep{General_Category: Punctuation} (Short: \ep{Gc=P}, \ep{P}) (842:
+\&                             [!\e"#\e%&\e\*(Aq\e(\e)*,\e\-.\e/:;?\e@\e[\e\e\e]_\e{\e}
+\&                             \exa1\exa7\exab\exb6\-\exb7\exbb\exbf], U+037E,
+\&                             U+0387, U+055A..055F, U+0589..058A,
+\&                             U+05BE ...)
+\&   \ep{General_Category: S} \ep{General_Category=Symbol} (7770)
+\&   \ep{General_Category: Sc} \ep{General_Category=Currency_Symbol} (63)
+\&   \ep{General_Category: Separator} (Short: \ep{Gc=Z}, \ep{Z}) (19:
+\&                             [\ex20\exa0], U+1680, U+2000..200A,
+\&                             U+2028..2029, U+202F, U+205F ...)
+\&   \ep{General_Category: Sk} \ep{General_Category=Modifier_Symbol} (125)
+\&   \ep{General_Category: Sm} \ep{General_Category=Math_Symbol} (948)
+\&   \ep{General_Category: So} \ep{General_Category=Other_Symbol} (6634)
+\&   \ep{General_Category: Space_Separator} (Short: \ep{Gc=Zs}, \ep{Zs})
+\&                             (17: [\ex20\exa0], U+1680, U+2000..200A,
+\&                             U+202F, U+205F, U+3000)
+\&   \ep{General_Category: Spacing_Mark} (Short: \ep{Gc=Mc}, \ep{Mc})
+\&                             (452: U+0903, U+093B, U+093E..0940,
+\&                             U+0949..094C, U+094E..094F, U+0982..0983
+\&                             ...)
+\&   \ep{General_Category: Surrogate} (Short: \ep{Gc=Cs}, \ep{Cs}) (2048:
+\&                             U+D800..DFFF)
+\&   \ep{General_Category: Symbol} (Short: \ep{Gc=S}, \ep{S}) (7770:
+\&                             [\e$+<=>\e^\`\e|~\exa2\-\exa6\exa8\-\exa9\exac\exae\-
+\&                             \exb1\exb4\exb8\exd7\exf7], U+02C2..02C5,
+\&                             U+02D2..02DF, U+02E5..02EB, U+02ED,
+\&                             U+02EF..02FF ...)
+\&   \ep{General_Category: Titlecase_Letter} (Short: \ep{Gc=Lt}, \ep{Lt};
+\&                             /i= General_Category=Cased_Letter) (31:
+\&                             U+01C5, U+01C8, U+01CB, U+01F2,
+\&                             U+1F88..1F8F, U+1F98..1F9F ...)
+\&   \ep{General_Category: Unassigned} (Short: \ep{Gc=Cn}, \ep{Cn})
+\&                             (825_345 plus all above\-Unicode code
+\&                             points: U+0378..0379, U+0380..0383,
+\&                             U+038B, U+038D, U+03A2, U+0530 ...)
+\&   \ep{General_Category: Uppercase_Letter} (Short: \ep{Gc=Lu}, \ep{Lu};
+\&                             /i= General_Category=Cased_Letter)
+\&                             (1831: [A\-Z\exc0\-\exd6\exd8\-\exde], U+0100,
+\&                             U+0102, U+0104, U+0106, U+0108 ...)
+\&   \ep{General_Category: Z} \ep{General_Category=Separator} (19)
+\&   \ep{General_Category: Zl} \ep{General_Category=Line_Separator} (1)
+\&   \ep{General_Category: Zp} \ep{General_Category=Paragraph_Separator}
+\&                             (1)
+\&   \ep{General_Category: Zs} \ep{General_Category=Space_Separator} (17)
+\& X \ep{General_Punctuation} \ep{Block=General_Punctuation} (Short:
+\&                             \ep{InPunctuation}) (112)
+\& X \ep{Geometric_Shapes}    \ep{Block=Geometric_Shapes} (96)
+\& X \ep{Geometric_Shapes_Ext} \ep{Geometric_Shapes_Extended} (=
+\&                             \ep{Block=Geometric_Shapes_Extended})
+\&                             (128)
+\& X \ep{Geometric_Shapes_Extended} \ep{Block=Geometric_Shapes_Extended}
+\&                             (Short: \ep{InGeometricShapesExt}) (128)
+\&   \ep{Geor}                \ep{Georgian} (= \ep{Script_Extensions=
+\&                             Georgian}) (NOT \ep{Block=Georgian}) (174)
+\&   \ep{Georgian}            \ep{Script_Extensions=Georgian} (Short:
+\&                             \ep{Geor}; NOT \ep{Block=Georgian}) (174)
+\& X \ep{Georgian_Ext}        \ep{Georgian_Extended} (= \ep{Block=
+\&                             Georgian_Extended}) (48)
+\& X \ep{Georgian_Extended}   \ep{Block=Georgian_Extended} (Short:
+\&                             \ep{InGeorgianExt}) (48)
+\& X \ep{Georgian_Sup}        \ep{Georgian_Supplement} (= \ep{Block=
+\&                             Georgian_Supplement}) (48)
+\& X \ep{Georgian_Supplement} \ep{Block=Georgian_Supplement} (Short:
+\&                             \ep{InGeorgianSup}) (48)
+\&   \ep{Glag}                \ep{Glagolitic} (= \ep{Script_Extensions=
+\&                             Glagolitic}) (NOT \ep{Block=Glagolitic})
+\&                             (138)
+\&   \ep{Glagolitic}          \ep{Script_Extensions=Glagolitic} (Short:
+\&                             \ep{Glag}; NOT \ep{Block=Glagolitic}) (138)
+\& X \ep{Glagolitic_Sup}      \ep{Glagolitic_Supplement} (= \ep{Block=
+\&                             Glagolitic_Supplement}) (48)
+\& X \ep{Glagolitic_Supplement} \ep{Block=Glagolitic_Supplement} (Short:
+\&                             \ep{InGlagoliticSup}) (48)
+\&   \ep{Gong}                \ep{Gunjala_Gondi} (= \ep{Script_Extensions=
+\&                             Gunjala_Gondi}) (NOT \ep{Block=
+\&                             Gunjala_Gondi}) (65)
+\&   \ep{Gonm}                \ep{Masaram_Gondi} (= \ep{Script_Extensions=
+\&                             Masaram_Gondi}) (NOT \ep{Block=
+\&                             Masaram_Gondi}) (77)
+\&   \ep{Goth}                \ep{Gothic} (= \ep{Script_Extensions=
+\&                             Gothic}) (NOT \ep{Block=Gothic}) (27)
+\&   \ep{Gothic}              \ep{Script_Extensions=Gothic} (Short:
+\&                             \ep{Goth}; NOT \ep{Block=Gothic}) (27)
+\&   \ep{Gr_Base}             \ep{Grapheme_Base} (= \ep{Grapheme_Base=Y})
+\&                             (146_986)
+\&   \ep{Gr_Base: *}          \ep{Grapheme_Base: *}
+\&   \ep{Gr_Ext}              \ep{Grapheme_Extend} (= \ep{Grapheme_Extend=
+\&                             Y}) (2125)
+\&   \ep{Gr_Ext: *}           \ep{Grapheme_Extend: *}
+\&   \ep{Gran}                \ep{Grantha} (= \ep{Script_Extensions=
+\&                             Grantha}) (NOT \ep{Block=Grantha}) (116)
+\&   \ep{Grantha}             \ep{Script_Extensions=Grantha} (Short:
+\&                             \ep{Gran}; NOT \ep{Block=Grantha}) (116)
+\&   \ep{Graph}               \ep{XPosixGraph} (286_635)
+\&   \ep{Grapheme_Base}       \ep{Grapheme_Base=Y} (Short: \ep{GrBase})
+\&                             (146_986)
+\&   \ep{Grapheme_Base: N*}   (Short: \ep{GrBase=N}, \eP{GrBase}) (967_126
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex1f\ex7f\-\ex9f\exad], U+0300..036F,
+\&                             U+0378..0379, U+0380..0383, U+038B,
+\&                             U+038D ...)
+\&   \ep{Grapheme_Base: Y*}   (Short: \ep{GrBase=Y}, \ep{GrBase})
+\&                             (146_986: [\ex20\-\ex7e\exa0\-\exac\exae\-\exff],
+\&                             U+0100..02FF, U+0370..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C ...)
+\&   \ep{Grapheme_Cluster_Break: CN} \ep{Grapheme_Cluster_Break=Control}
+\&                             (3893)
+\&   \ep{Grapheme_Cluster_Break: Control} (Short: \ep{GCB=CN}) (3893: [^
+\&                             \en\er\ex20\-\ex7e\exa0\-\exac\exae\-\exff],
+\&                             U+061C, U+180E, U+200B, U+200E..200F,
+\&                             U+2028..202E ...)
+\&   \ep{Grapheme_Cluster_Break: CR} (Short: \ep{GCB=CR}) (1: [\er])
+\&   \ep{Grapheme_Cluster_Break: E_Base} (Short: \ep{GCB=EB}) (0)
+\&   \ep{Grapheme_Cluster_Break: E_Base_GAZ} (Short: \ep{GCB=EBG}) (0)
+\&   \ep{Grapheme_Cluster_Break: E_Modifier} (Short: \ep{GCB=EM}) (0)
+\&   \ep{Grapheme_Cluster_Break: EB} \ep{Grapheme_Cluster_Break=E_Base}
+\&                             (0)
+\&   \ep{Grapheme_Cluster_Break: EBG} \ep{Grapheme_Cluster_Break=
+\&                             E_Base_GAZ} (0)
+\&   \ep{Grapheme_Cluster_Break: EM} \ep{Grapheme_Cluster_Break=
+\&                             E_Modifier} (0)
+\&   \ep{Grapheme_Cluster_Break: EX} \ep{Grapheme_Cluster_Break=Extend}
+\&                             (2130)
+\&   \ep{Grapheme_Cluster_Break: Extend} (Short: \ep{GCB=EX}) (2130:
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{Grapheme_Cluster_Break: GAZ} \ep{Grapheme_Cluster_Break=
+\&                             Glue_After_Zwj} (0)
+\&   \ep{Grapheme_Cluster_Break: Glue_After_Zwj} (Short: \ep{GCB=GAZ}) (0)
+\&   \ep{Grapheme_Cluster_Break: L} (Short: \ep{GCB=L}) (125:
+\&                             U+1100..115F, U+A960..A97C)
+\&   \ep{Grapheme_Cluster_Break: LF} (Short: \ep{GCB=LF}) (1: [\en])
+\&   \ep{Grapheme_Cluster_Break: LV} (Short: \ep{GCB=LV}) (399: U+AC00,
+\&                             U+AC1C, U+AC38, U+AC54, U+AC70, U+AC8C
+\&                             ...)
+\&   \ep{Grapheme_Cluster_Break: LVT} (Short: \ep{GCB=LVT}) (10_773:
+\&                             U+AC01..AC1B, U+AC1D..AC37,
+\&                             U+AC39..AC53, U+AC55..AC6F,
+\&                             U+AC71..AC8B, U+AC8D..ACA7 ...)
+\&   \ep{Grapheme_Cluster_Break: Other} (Short: \ep{GCB=XX}) (1_096_109
+\&                             plus all above\-Unicode code points:
+\&                             [\ex20\-\ex7e\exa0\-\exac\exae\-\exff],
+\&                             U+0100..02FF, U+0370..0482,
+\&                             U+048A..0590, U+05BE, U+05C0 ...)
+\&   \ep{Grapheme_Cluster_Break: PP} \ep{Grapheme_Cluster_Break=Prepend}
+\&                             (27)
+\&   \ep{Grapheme_Cluster_Break: Prepend} (Short: \ep{GCB=PP}) (27:
+\&                             U+0600..0605, U+06DD, U+070F,
+\&                             U+0890..0891, U+08E2, U+0D4E ...)
+\&   \ep{Grapheme_Cluster_Break: Regional_Indicator} (Short: \ep{GCB=RI})
+\&                             (26: U+1F1E6..1F1FF)
+\&   \ep{Grapheme_Cluster_Break: RI} \ep{Grapheme_Cluster_Break=
+\&                             Regional_Indicator} (26)
+\&   \ep{Grapheme_Cluster_Break: SM} \ep{Grapheme_Cluster_Break=
+\&                             SpacingMark} (395)
+\&   \ep{Grapheme_Cluster_Break: SpacingMark} (Short: \ep{GCB=SM}) (395:
+\&                             U+0903, U+093B, U+093E..0940,
+\&                             U+0949..094C, U+094E..094F, U+0982..0983
+\&                             ...)
+\&   \ep{Grapheme_Cluster_Break: T} (Short: \ep{GCB=T}) (137:
+\&                             U+11A8..11FF, U+D7CB..D7FB)
+\&   \ep{Grapheme_Cluster_Break: V} (Short: \ep{GCB=V}) (95:
+\&                             U+1160..11A7, U+D7B0..D7C6)
+\&   \ep{Grapheme_Cluster_Break: XX} \ep{Grapheme_Cluster_Break=Other}
+\&                             (1_096_109 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Grapheme_Cluster_Break: ZWJ} (Short: \ep{GCB=ZWJ}) (1: U+200D)
+\&   \ep{Grapheme_Extend}     \ep{Grapheme_Extend=Y} (Short: \ep{GrExt})
+\&                             (2125)
+\&   \ep{Grapheme_Extend: N*} (Short: \ep{GrExt=N}, \eP{GrExt}) (1_111_987
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..02FF, U+0370..0482,
+\&                             U+048A..0590, U+05BE, U+05C0, U+05C3 ...)
+\&   \ep{Grapheme_Extend: Y*} (Short: \ep{GrExt=Y}, \ep{GrExt}) (2125:
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{Greek}               \ep{Script_Extensions=Greek} (Short:
+\&                             \ep{Grek}; NOT \ep{Greek_And_Coptic}) (522)
+\& X \ep{Greek_And_Coptic}    \ep{Block=Greek_And_Coptic} (Short:
+\&                             \ep{InGreek}) (144)
+\& X \ep{Greek_Ext}           \ep{Greek_Extended} (= \ep{Block=
+\&                             Greek_Extended}) (256)
+\& X \ep{Greek_Extended}      \ep{Block=Greek_Extended} (Short:
+\&                             \ep{InGreekExt}) (256)
+\&   \ep{Grek}                \ep{Greek} (= \ep{Script_Extensions=Greek})
+\&                             (NOT \ep{Greek_And_Coptic}) (522)
+\&   \ep{Gujarati}            \ep{Script_Extensions=Gujarati} (Short:
+\&                             \ep{Gujr}; NOT \ep{Block=Gujarati}) (105)
+\&   \ep{Gujr}                \ep{Gujarati} (= \ep{Script_Extensions=
+\&                             Gujarati}) (NOT \ep{Block=Gujarati}) (105)
+\&   \ep{Gunjala_Gondi}       \ep{Script_Extensions=Gunjala_Gondi}
+\&                             (Short: \ep{Gong}; NOT \ep{Block=
+\&                             Gunjala_Gondi}) (65)
+\&   \ep{Gurmukhi}            \ep{Script_Extensions=Gurmukhi} (Short:
+\&                             \ep{Guru}; NOT \ep{Block=Gurmukhi}) (94)
+\&   \ep{Guru}                \ep{Gurmukhi} (= \ep{Script_Extensions=
+\&                             Gurmukhi}) (NOT \ep{Block=Gurmukhi}) (94)
+\& X \ep{Half_And_Full_Forms} \ep{Halfwidth_And_Fullwidth_Forms} (=
+\&                             \ep{Block=Halfwidth_And_Fullwidth_Forms})
+\&                             (240)
+\& X \ep{Half_Marks}          \ep{Combining_Half_Marks} (= \ep{Block=
+\&                             Combining_Half_Marks}) (16)
+\& X \ep{Halfwidth_And_Fullwidth_Forms} \ep{Block=
+\&                             Halfwidth_And_Fullwidth_Forms} (Short:
+\&                             \ep{InHalfAndFullForms}) (240)
+\&   \ep{Han}                 \ep{Script_Extensions=Han} (98_696)
+\&   \ep{Hang}                \ep{Hangul} (= \ep{Script_Extensions=
+\&                             Hangul}) (NOT \ep{Hangul_Syllables})
+\&                             (11_775)
+\&   \ep{Hangul}              \ep{Script_Extensions=Hangul} (Short:
+\&                             \ep{Hang}; NOT \ep{Hangul_Syllables})
+\&                             (11_775)
+\& X \ep{Hangul_Compatibility_Jamo} \ep{Block=Hangul_Compatibility_Jamo}
+\&                             (Short: \ep{InCompatJamo}) (96)
+\& X \ep{Hangul_Jamo}         \ep{Block=Hangul_Jamo} (Short: \ep{InJamo})
+\&                             (256)
+\& X \ep{Hangul_Jamo_Extended_A} \ep{Block=Hangul_Jamo_Extended_A}
+\&                             (Short: \ep{InJamoExtA}) (32)
+\& X \ep{Hangul_Jamo_Extended_B} \ep{Block=Hangul_Jamo_Extended_B}
+\&                             (Short: \ep{InJamoExtB}) (80)
+\&   \ep{Hangul_Syllable_Type: L} \ep{Hangul_Syllable_Type=Leading_Jamo}
+\&                             (125)
+\&   \ep{Hangul_Syllable_Type: Leading_Jamo} (Short: \ep{Hst=L}) (125:
+\&                             U+1100..115F, U+A960..A97C)
+\&   \ep{Hangul_Syllable_Type: LV} \ep{Hangul_Syllable_Type=LV_Syllable}
+\&                             (399)
+\&   \ep{Hangul_Syllable_Type: LV_Syllable} (Short: \ep{Hst=LV}) (399:
+\&                             U+AC00, U+AC1C, U+AC38, U+AC54, U+AC70,
+\&                             U+AC8C ...)
+\&   \ep{Hangul_Syllable_Type: LVT} \ep{Hangul_Syllable_Type=
+\&                             LVT_Syllable} (10_773)
+\&   \ep{Hangul_Syllable_Type: LVT_Syllable} (Short: \ep{Hst=LVT})
+\&                             (10_773: U+AC01..AC1B, U+AC1D..AC37,
+\&                             U+AC39..AC53, U+AC55..AC6F,
+\&                             U+AC71..AC8B, U+AC8D..ACA7 ...)
+\&   \ep{Hangul_Syllable_Type: NA} \ep{Hangul_Syllable_Type=
+\&                             Not_Applicable} (1_102_583 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Hangul_Syllable_Type: Not_Applicable} (Short: \ep{Hst=NA})
+\&                             (1_102_583 plus all above\-Unicode code
+\&                             points: U+0000..10FF, U+1200..A95F,
+\&                             U+A97D..ABFF, U+D7A4..D7AF,
+\&                             U+D7C7..D7CA, U+D7FC..infinity)
+\&   \ep{Hangul_Syllable_Type: T} \ep{Hangul_Syllable_Type=Trailing_Jamo}
+\&                             (137)
+\&   \ep{Hangul_Syllable_Type: Trailing_Jamo} (Short: \ep{Hst=T}) (137:
+\&                             U+11A8..11FF, U+D7CB..D7FB)
+\&   \ep{Hangul_Syllable_Type: V} \ep{Hangul_Syllable_Type=Vowel_Jamo}
+\&                             (95)
+\&   \ep{Hangul_Syllable_Type: Vowel_Jamo} (Short: \ep{Hst=V}) (95:
+\&                             U+1160..11A7, U+D7B0..D7C6)
+\& X \ep{Hangul_Syllables}    \ep{Block=Hangul_Syllables} (Short:
+\&                             \ep{InHangul}) (11_184)
+\&   \ep{Hani}                \ep{Han} (= \ep{Script_Extensions=Han})
+\&                             (98_696)
+\&   \ep{Hanifi_Rohingya}     \ep{Script_Extensions=Hanifi_Rohingya}
+\&                             (Short: \ep{Rohg}; NOT \ep{Block=
+\&                             Hanifi_Rohingya}) (55)
+\&   \ep{Hano}                \ep{Hanunoo} (= \ep{Script_Extensions=
+\&                             Hanunoo}) (NOT \ep{Block=Hanunoo}) (23)
+\&   \ep{Hanunoo}             \ep{Script_Extensions=Hanunoo} (Short:
+\&                             \ep{Hano}; NOT \ep{Block=Hanunoo}) (23)
+\&   \ep{Hatr}                \ep{Hatran} (= \ep{Script_Extensions=
+\&                             Hatran}) (NOT \ep{Block=Hatran}) (26)
+\&   \ep{Hatran}              \ep{Script_Extensions=Hatran} (Short:
+\&                             \ep{Hatr}; NOT \ep{Block=Hatran}) (26)
+\&   \ep{Hebr}                \ep{Hebrew} (= \ep{Script_Extensions=
+\&                             Hebrew}) (NOT \ep{Block=Hebrew}) (134)
+\&   \ep{Hebrew}              \ep{Script_Extensions=Hebrew} (Short:
+\&                             \ep{Hebr}; NOT \ep{Block=Hebrew}) (134)
+\&   \ep{Hex}                 \ep{XPosixXDigit} (= \ep{Hex_Digit=Y}) (44)
+\&   \ep{Hex: *}              \ep{Hex_Digit: *}
+\&   \ep{Hex_Digit}           \ep{XPosixXDigit} (= \ep{Hex_Digit=Y}) (44)
+\&   \ep{Hex_Digit: N*}       (Short: \ep{Hex=N}, \eP{Hex}) (1_114_068
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?
+\&                             \e@G\-Z\e[\e\e\e]\e^_\`g\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..FF0F, U+FF1A..FF20,
+\&                             U+FF27..FF40, U+FF47..infinity)
+\&   \ep{Hex_Digit: Y*}       (Short: \ep{Hex=Y}, \ep{Hex}) (44: [0\-9A\-Fa\-
+\&                             f], U+FF10..FF19, U+FF21..FF26,
+\&                             U+FF41..FF46)
+\& X \ep{High_Private_Use_Surrogates} \ep{Block=
+\&                             High_Private_Use_Surrogates} (Short:
+\&                             \ep{InHighPUSurrogates}) (128)
+\& X \ep{High_PU_Surrogates}  \ep{High_Private_Use_Surrogates} (=
+\&                             \ep{Block=High_Private_Use_Surrogates})
+\&                             (128)
+\& X \ep{High_Surrogates}     \ep{Block=High_Surrogates} (896)
+\&   \ep{Hira}                \ep{Hiragana} (= \ep{Script_Extensions=
+\&                             Hiragana}) (NOT \ep{Block=Hiragana}) (433)
+\&   \ep{Hiragana}            \ep{Script_Extensions=Hiragana} (Short:
+\&                             \ep{Hira}; NOT \ep{Block=Hiragana}) (433)
+\&   \ep{Hluw}                \ep{Anatolian_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Anatolian_Hieroglyphs}) (NOT \ep{Block=
+\&                             Anatolian_Hieroglyphs}) (583)
+\&   \ep{Hmng}                \ep{Pahawh_Hmong} (= \ep{Script_Extensions=
+\&                             Pahawh_Hmong}) (NOT \ep{Block=
+\&                             Pahawh_Hmong}) (127)
+\&   \ep{Hmnp}                \ep{Nyiakeng_Puachue_Hmong} (=
+\&                             \ep{Script_Extensions=
+\&                             Nyiakeng_Puachue_Hmong}) (NOT \ep{Block=
+\&                             Nyiakeng_Puachue_Hmong}) (71)
+\&   \ep{HorizSpace}          \ep{XPosixBlank} (18)
+\&   \ep{Hst: *}              \ep{Hangul_Syllable_Type: *}
+\&   \ep{Hung}                \ep{Old_Hungarian} (= \ep{Script_Extensions=
+\&                             Old_Hungarian}) (NOT \ep{Block=
+\&                             Old_Hungarian}) (108)
+\& D \ep{Hyphen}              \ep{Hyphen=Y} (11)
+\& D \ep{Hyphen: N*}          Supplanted by Line_Break property values;
+\&                             see www.unicode.org/reports/tr14
+\&                             (Single: \eP{Hyphen}) (1_114_101 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,.\e/0\-9:;<=>?\e@A\-Z
+\&                             \e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-\exac\exae\-\exff],
+\&                             U+0100..0589, U+058B..1805,
+\&                             U+1807..200F, U+2012..2E16, U+2E18..30FA
+\&                             ...)
+\& D \ep{Hyphen: Y*}          Supplanted by Line_Break property values;
+\&                             see www.unicode.org/reports/tr14
+\&                             (Single: \ep{Hyphen}) (11: [\e\-\exad],
+\&                             U+058A, U+1806, U+2010..2011, U+2E17,
+\&                             U+30FB ...)
+\&   \ep{ID_Continue}         \ep{ID_Continue=Y} (Short: \ep{IDC}; NOT
+\&                             \ep{Ideographic_Description_Characters})
+\&                             (139_482)
+\&   \ep{ID_Continue: N*}     (Short: \ep{IDC=N}, \eP{IDC}) (974_630 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@
+\&                             \e[\e\e\e]\e^\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4\exb6
+\&                             \exb8\-\exb9\exbb\-\exbf\exd7\exf7],
+\&                             U+02C2..02C5, U+02D2..02DF,
+\&                             U+02E5..02EB, U+02ED, U+02EF..02FF ...)
+\&   \ep{ID_Continue: Y*}     (Short: \ep{IDC=Y}, \ep{IDC}) (139_482:
+\&                             [0\-9A\-Z_a\-z\exaa\exb5\exb7\exba\exc0\-\exd6
+\&                             \exd8\-\exf6\exf8\-\exff], U+0100..02C1,
+\&                             U+02C6..02D1, U+02E0..02E4, U+02EC,
+\&                             U+02EE ...)
+\&   \ep{ID_Start}            \ep{ID_Start=Y} (Short: \ep{IDS}) (136_345)
+\&   \ep{ID_Start: N*}        (Short: \ep{IDS=N}, \eP{IDS}) (977_767 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@
+\&                             \e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4\exb6\-
+\&                             \exb9\exbb\-\exbf\exd7\exf7], U+02C2..02C5,
+\&                             U+02D2..02DF, U+02E5..02EB, U+02ED,
+\&                             U+02EF..036F ...)
+\&   \ep{ID_Start: Y*}        (Short: \ep{IDS=Y}, \ep{IDS}) (136_345: [A\-
+\&                             Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-
+\&                             \exff], U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\&   \ep{IDC}                 \ep{ID_Continue} (= \ep{ID_Continue=Y}) (NOT
+\&                             \ep{Ideographic_Description_Characters})
+\&                             (139_482)
+\&   \ep{IDC: *}              \ep{ID_Continue: *}
+\&   \ep{Identifier_Status: Allowed} (112_159: [\e\*(Aq\e\-.0\-9:A\-Z_a\-z\exb7
+\&                             \exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..0131, U+0134..013E,
+\&                             U+0141..0148, U+014A..017E, U+018F ...)
+\&   \ep{Identifier_Status: Restricted} (1_001_953 plus all above\-
+\&                             Unicode code points: [\ex00\-\ex20!\e"#\e$
+\&                             \e%&\e(\e)*+,\e/;<=>?\e@\e[\e\e\e]\e^\`\e{\e|\e}~\ex7f\-
+\&                             \exb6\exb8\-\exbf\exd7\exf7], U+0132..0133,
+\&                             U+013F..0140, U+0149, U+017F..018E,
+\&                             U+0190..019F ...)
+\&   \ep{Identifier_Type: Default_Ignorable} (398: [\exad], U+034F,
+\&                             U+061C, U+115F..1160, U+17B4..17B5,
+\&                             U+180B..180F ...)
+\&   \ep{Identifier_Type: Deprecated} (15: U+0149, U+0673, U+0F77,
+\&                             U+0F79, U+17A3..17A4, U+206A..206F ...)
+\&   \ep{Identifier_Type: Exclusion} (17_241: U+03E2..03EF,
+\&                             U+0800..082D, U+0830..083E,
+\&                             U+1680..169C, U+16A0..16EA, U+16EE..16F8
+\&                             ...)
+\&   \ep{Identifier_Type: Inclusion} (17: [\e\*(Aq\e\-.:\exb7], U+0375, U+058A,
+\&                             U+05F3..05F4, U+06FD..06FE, U+0F0B ...)
+\&   \ep{Identifier_Type: Limited_Use} (5268: U+0700..070D,
+\&                             U+070F..074A, U+074D..074F,
+\&                             U+07C0..07FA, U+07FD..07FF, U+0840..085B
+\&                             ...)
+\&   \ep{Identifier_Type: Not_Character} (964_920 plus all above\-Unicode
+\&                             code points: [^\et\en\ecK\ef\er\ex20\-\ex7e\ex85
+\&                             \exa0\-\exff], U+0378..0379, U+0380..0383,
+\&                             U+038B, U+038D, U+03A2 ...)
+\&   \ep{Identifier_Type: Not_NFKC} (4921: [\exa0\exa8\exaa\exaf\exb2\-\exb5
+\&                             \exb8\-\exba\exbc\-\exbe], U+0132..0133,
+\&                             U+013F..0140, U+017F, U+01C4..01CC,
+\&                             U+01F1..01F3 ...)
+\&   \ep{Identifier_Type: Not_XID} (8277: [\et\en\ecK\ef\er\ex20!\e"#\e$\e%&
+\&                             \e(\e)*+,\e/;<=>?\e@\e[\e\e\e]\e^\`\e{\e|\e}~\ex85
+\&                             \exa1\-\exa7\exa9\exab\-\exac\exae\exb0\-\exb1\exb6
+\&                             \exbb\exbf\exd7\exf7], U+02C2..02C5,
+\&                             U+02D2..02D7, U+02DE..02DF,
+\&                             U+02E5..02EB, U+02ED ...)
+\&   \ep{Identifier_Type: Obsolete} (1627: U+018D, U+01AA..01AB,
+\&                             U+01B9..01BB, U+01BE..01BF,
+\&                             U+01F6..01F7, U+021C..021D ...)
+\&   \ep{Identifier_Type: Recommended} (112_142: [0\-9A\-Z_a\-z\exc0\-\exd6
+\&                             \exd8\-\exf6\exf8\-\exff], U+0100..0131,
+\&                             U+0134..013E, U+0141..0148,
+\&                             U+014A..017E, U+018F ...)
+\&   \ep{Identifier_Type: Technical} (1660: U+0180, U+018D,
+\&                             U+01AA..01AB, U+01BA..01BB, U+01BE,
+\&                             U+01C0..01C3 ...)
+\&   \ep{Identifier_Type: Uncommon_Use} (396: U+0181..018C, U+018E,
+\&                             U+0190..019F, U+01A2..01A9,
+\&                             U+01AC..01AE, U+01B1..01B8 ...)
+\&   \ep{Ideo}                \ep{Ideographic} (= \ep{Ideographic=Y})
+\&                             (105_854)
+\&   \ep{Ideo: *}             \ep{Ideographic: *}
+\&   \ep{Ideographic}         \ep{Ideographic=Y} (Short: \ep{Ideo})
+\&                             (105_854)
+\&   \ep{Ideographic: N*}     (Short: \ep{Ideo=N}, \eP{Ideo}) (1_008_258
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..3005, U+3008..3020,
+\&                             U+302A..3037, U+303B..33FF,
+\&                             U+4DC0..4DFF, U+A000..F8FF ...)
+\&   \ep{Ideographic: Y*}     (Short: \ep{Ideo=Y}, \ep{Ideo}) (105_854:
+\&                             U+3006..3007, U+3021..3029,
+\&                             U+3038..303A, U+3400..4DBF,
+\&                             U+4E00..9FFF, U+F900..FA6D ...)
+\& X \ep{Ideographic_Description_Characters} \ep{Block=
+\&                             Ideographic_Description_Characters}
+\&                             (Short: \ep{InIDC}) (16)
+\& X \ep{Ideographic_Symbols} \ep{Ideographic_Symbols_And_Punctuation} (=
+\&                             \ep{Block=
+\&                             Ideographic_Symbols_And_Punctuation})
+\&                             (32)
+\& X \ep{Ideographic_Symbols_And_Punctuation} \ep{Block=
+\&                             Ideographic_Symbols_And_Punctuation}
+\&                             (Short: \ep{InIdeographicSymbols}) (32)
+\&   \ep{IDS}                 \ep{ID_Start} (= \ep{ID_Start=Y}) (136_345)
+\&   \ep{IDS: *}              \ep{ID_Start: *}
+\&   \ep{IDS_Binary_Operator} \ep{IDS_Binary_Operator=Y} (Short:
+\&                             \ep{IDSB}) (10)
+\&   \ep{IDS_Binary_Operator: N*} (Short: \ep{IDSB=N}, \eP{IDSB})
+\&                             (1_114_102 plus all above\-Unicode code
+\&                             points: U+0000..2FEF, U+2FF2..2FF3,
+\&                             U+2FFC..infinity)
+\&   \ep{IDS_Binary_Operator: Y*} (Short: \ep{IDSB=Y}, \ep{IDSB}) (10:
+\&                             U+2FF0..2FF1, U+2FF4..2FFB)
+\&   \ep{IDS_Trinary_Operator} \ep{IDS_Trinary_Operator=Y} (Short:
+\&                             \ep{IDST}) (2)
+\&   \ep{IDS_Trinary_Operator: N*} (Short: \ep{IDST=N}, \eP{IDST})
+\&                             (1_114_110 plus all above\-Unicode code
+\&                             points: U+0000..2FF1, U+2FF4..infinity)
+\&   \ep{IDS_Trinary_Operator: Y*} (Short: \ep{IDST=Y}, \ep{IDST}) (2:
+\&                             U+2FF2..2FF3)
+\&   \ep{IDSB}                \ep{IDS_Binary_Operator} (=
+\&                             \ep{IDS_Binary_Operator=Y}) (10)
+\&   \ep{IDSB: *}             \ep{IDS_Binary_Operator: *}
+\&   \ep{IDST}                \ep{IDS_Trinary_Operator} (=
+\&                             \ep{IDS_Trinary_Operator=Y}) (2)
+\&   \ep{IDST: *}             \ep{IDS_Trinary_Operator: *}
+\&   \ep{Imperial_Aramaic}    \ep{Script_Extensions=Imperial_Aramaic}
+\&                             (Short: \ep{Armi}; NOT \ep{Block=
+\&                             Imperial_Aramaic}) (31)
+\&   \ep{In: *}               \ep{Present_In: *} (Perl extension)
+\& X \ep{In_*}                \ep{Block: *}
+\& X \ep{Indic_Number_Forms}  \ep{Common_Indic_Number_Forms} (= \ep{Block=
+\&                             Common_Indic_Number_Forms}) (16)
+\&   \ep{Indic_Positional_Category: Bottom} (Short: \ep{InPC=Bottom})
+\&                             (356: U+093C, U+0941..0944, U+094D,
+\&                             U+0952, U+0956..0957, U+0962..0963 ...)
+\&   \ep{Indic_Positional_Category: Bottom_And_Left} (Short: \ep{InPC=
+\&                             BottomAndLeft}) (1: U+A9BF)
+\&   \ep{Indic_Positional_Category: Bottom_And_Right} (Short: \ep{InPC=
+\&                             BottomAndRight}) (4: U+1B3B, U+A9BE,
+\&                             U+A9C0, U+11942)
+\&   \ep{Indic_Positional_Category: Left} (Short: \ep{InPC=Left}) (66:
+\&                             U+093F, U+094E, U+09BF, U+09C7..09C8,
+\&                             U+0A3F, U+0ABF ...)
+\&   \ep{Indic_Positional_Category: Left_And_Right} (Short: \ep{InPC=
+\&                             LeftAndRight}) (22: U+09CB..09CC,
+\&                             U+0B4B, U+0BCA..0BCC, U+0D4A..0D4C,
+\&                             U+0DDC, U+0DDE ...)
+\&   \ep{Indic_Positional_Category: NA} (Short: \ep{InPC=NA}) (1_112_875
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..08FF, U+0904..0939, U+093D,
+\&                             U+0950, U+0953..0954, U+0958..0961 ...)
+\&   \ep{Indic_Positional_Category: Overstruck} (Short: \ep{InPC=
+\&                             Overstruck}) (10: U+1CD4, U+1CE2..1CE8,
+\&                             U+10A01, U+10A06)
+\&   \ep{Indic_Positional_Category: Right} (Short: \ep{InPC=Right}) (295:
+\&                             U+0903, U+093B, U+093E, U+0940,
+\&                             U+0949..094C, U+094F ...)
+\&   \ep{Indic_Positional_Category: Top} (Short: \ep{InPC=Top}) (428:
+\&                             U+0900..0902, U+093A, U+0945..0948,
+\&                             U+0951, U+0955, U+0981 ...)
+\&   \ep{Indic_Positional_Category: Top_And_Bottom} (Short: \ep{InPC=
+\&                             TopAndBottom}) (10: U+0C48, U+0F73,
+\&                             U+0F76..0F79, U+0F81, U+1B3C,
+\&                             U+1112E..1112F)
+\&   \ep{Indic_Positional_Category: Top_And_Bottom_And_Left} (Short:
+\&                             \ep{InPC=TopAndBottomAndLeft}) (2:
+\&                             U+103C, U+1171E)
+\&   \ep{Indic_Positional_Category: Top_And_Bottom_And_Right} (Short:
+\&                             \ep{InPC=TopAndBottomAndRight}) (1:
+\&                             U+1B3D)
+\&   \ep{Indic_Positional_Category: Top_And_Left} (Short: \ep{InPC=
+\&                             TopAndLeft}) (6: U+0B48, U+0DDA, U+17BE,
+\&                             U+1C29, U+114BB, U+115B9)
+\&   \ep{Indic_Positional_Category: Top_And_Left_And_Right} (Short:
+\&                             \ep{InPC=TopAndLeftAndRight}) (4: U+0B4C,
+\&                             U+0DDD, U+17BF, U+115BB)
+\&   \ep{Indic_Positional_Category: Top_And_Right} (Short: \ep{InPC=
+\&                             TopAndRight}) (13: U+0AC9, U+0B57,
+\&                             U+0CC0, U+0CC7..0CC8, U+0CCA..0CCB,
+\&                             U+1925..1926 ...)
+\&   \ep{Indic_Positional_Category: Visual_Order_Left} (Short: \ep{InPC=
+\&                             VisualOrderLeft}) (19: U+0E40..0E44,
+\&                             U+0EC0..0EC4, U+19B5..19B7, U+19BA,
+\&                             U+AAB5..AAB6, U+AAB9 ...)
+\& X \ep{Indic_Siyaq_Numbers} \ep{Block=Indic_Siyaq_Numbers} (80)
+\&   \ep{Indic_Syllabic_Category: Avagraha} (Short: \ep{InSC=Avagraha})
+\&                             (17: U+093D, U+09BD, U+0ABD, U+0B3D,
+\&                             U+0C3D, U+0CBD ...)
+\&   \ep{Indic_Syllabic_Category: Bindu} (Short: \ep{InSC=Bindu}) (94:
+\&                             U+0900..0902, U+0981..0982, U+09FC,
+\&                             U+0A01..0A02, U+0A70, U+0A81..0A82 ...)
+\&   \ep{Indic_Syllabic_Category: Brahmi_Joining_Number} (Short:
+\&                             \ep{InSC=BrahmiJoiningNumber}) (20:
+\&                             U+11052..11065)
+\&   \ep{Indic_Syllabic_Category: Cantillation_Mark} (Short: \ep{InSC=
+\&                             CantillationMark}) (58: U+0951..0952,
+\&                             U+0A51, U+0AFA, U+0AFC, U+1CD0..1CD2,
+\&                             U+1CD4..1CE1 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant} (Short: \ep{InSC=Consonant})
+\&                             (2241: U+0915..0939, U+0958..095F,
+\&                             U+0978..097F, U+0995..09A8,
+\&                             U+09AA..09B0, U+09B2 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant_Dead} (Short: \ep{InSC=
+\&                             ConsonantDead}) (14: U+09CE, U+0C5D,
+\&                             U+0CDD, U+0D54..0D56, U+0D7A..0D7F,
+\&                             U+1CF2..1CF3)
+\&   \ep{Indic_Syllabic_Category: Consonant_Final} (Short: \ep{InSC=
+\&                             ConsonantFinal}) (70: U+1930..1931,
+\&                             U+1933..1939, U+19C1..19C7,
+\&                             U+1A58..1A59, U+1B03, U+1B81 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant_Head_Letter} (Short:
+\&                             \ep{InSC=ConsonantHeadLetter}) (5:
+\&                             U+0F88..0F8C)
+\&   \ep{Indic_Syllabic_Category: Consonant_Initial_Postfixed} (Short:
+\&                             \ep{InSC=ConsonantInitialPostfixed}) (1:
+\&                             U+1A5A)
+\&   \ep{Indic_Syllabic_Category: Consonant_Killer} (Short: \ep{InSC=
+\&                             ConsonantKiller}) (2: U+0E4C, U+17CD)
+\&   \ep{Indic_Syllabic_Category: Consonant_Medial} (Short: \ep{InSC=
+\&                             ConsonantMedial}) (31: U+0A75,
+\&                             U+0EBC..0EBD, U+103B..103E,
+\&                             U+105E..1060, U+1082, U+1A55..1A56 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant_Placeholder} (Short:
+\&                             \ep{InSC=ConsonantPlaceholder}) (22: [\e\-
+\&                             \exa0\exd7], U+0980, U+0A72..0A73, U+104B,
+\&                             U+104E, U+1900 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant_Preceding_Repha} (Short:
+\&                             \ep{InSC=ConsonantPrecedingRepha}) (4:
+\&                             U+0D4E, U+11941, U+11D46, U+11F02)
+\&   \ep{Indic_Syllabic_Category: Consonant_Prefixed} (Short: \ep{InSC=
+\&                             ConsonantPrefixed}) (10: U+111C2..111C3,
+\&                             U+1193F, U+11A3A, U+11A84..11A89)
+\&   \ep{Indic_Syllabic_Category: Consonant_Subjoined} (Short: \ep{InSC=
+\&                             ConsonantSubjoined}) (94: U+0F8D..0F97,
+\&                             U+0F99..0FBC, U+1929..192B, U+1A57,
+\&                             U+1A5B..1A5E, U+1BA1..1BA3 ...)
+\&   \ep{Indic_Syllabic_Category: Consonant_Succeeding_Repha} (Short:
+\&                             \ep{InSC=ConsonantSucceedingRepha}) (1:
+\&                             U+17CC)
+\&   \ep{Indic_Syllabic_Category: Consonant_With_Stacker} (Short:
+\&                             \ep{InSC=ConsonantWithStacker}) (8:
+\&                             U+0CF1..0CF2, U+1CF5..1CF6,
+\&                             U+11003..11004, U+11460..11461)
+\&   \ep{Indic_Syllabic_Category: Gemination_Mark} (Short: \ep{InSC=
+\&                             GeminationMark}) (4: U+0A71, U+0AFB,
+\&                             U+11237, U+11A98)
+\&   \ep{Indic_Syllabic_Category: Invisible_Stacker} (Short: \ep{InSC=
+\&                             InvisibleStacker}) (13: U+1039, U+17D2,
+\&                             U+1A60, U+1BAB, U+AAF6, U+10A3F ...)
+\&   \ep{Indic_Syllabic_Category: Joiner} (Short: \ep{InSC=Joiner}) (1:
+\&                             U+200D)
+\&   \ep{Indic_Syllabic_Category: Modifying_Letter} (Short: \ep{InSC=
+\&                             ModifyingLetter}) (1: U+0B83)
+\&   \ep{Indic_Syllabic_Category: Non_Joiner} (Short: \ep{InSC=
+\&                             NonJoiner}) (1: U+200C)
+\&   \ep{Indic_Syllabic_Category: Nukta} (Short: \ep{InSC=Nukta}) (32:
+\&                             U+093C, U+09BC, U+0A3C, U+0ABC,
+\&                             U+0AFD..0AFF, U+0B3C ...)
+\&   \ep{Indic_Syllabic_Category: Number} (Short: \ep{InSC=Number}) (501:
+\&                             [0\-9], U+0966..096F, U+09E6..09EF,
+\&                             U+0A66..0A6F, U+0AE6..0AEF, U+0B66..0B6F
+\&                             ...)
+\&   \ep{Indic_Syllabic_Category: Number_Joiner} (Short: \ep{InSC=
+\&                             NumberJoiner}) (1: U+1107F)
+\&   \ep{Indic_Syllabic_Category: Other} (Short: \ep{InSC=Other})
+\&                             (1_109_473 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,.
+\&                             \e/:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-
+\&                             \ex9f\exa1\-\exb1\exb4\-\exd6\exd8\-\exff],
+\&                             U+0100..08FF, U+0950, U+0953..0954,
+\&                             U+0964..0965, U+0970..0971 ...)
+\&   \ep{Indic_Syllabic_Category: Pure_Killer} (Short: \ep{InSC=
+\&                             PureKiller}) (26: U+0D3B..0D3C, U+0E3A,
+\&                             U+0E4E, U+0EBA, U+0F84, U+103A ...)
+\&   \ep{Indic_Syllabic_Category: Register_Shifter} (Short: \ep{InSC=
+\&                             RegisterShifter}) (2: U+17C9..17CA)
+\&   \ep{Indic_Syllabic_Category: Syllable_Modifier} (Short: \ep{InSC=
+\&                             SyllableModifier}) (26: [\exb2\-\exb3],
+\&                             U+09FE, U+0ECE, U+0F35, U+0F37, U+0FC6
+\&                             ...)
+\&   \ep{Indic_Syllabic_Category: Tone_Letter} (Short: \ep{InSC=
+\&                             ToneLetter}) (7: U+1970..1974, U+AAC0,
+\&                             U+AAC2)
+\&   \ep{Indic_Syllabic_Category: Tone_Mark} (Short: \ep{InSC=ToneMark})
+\&                             (42: U+0E48..0E4B, U+0EC8..0ECB, U+1037,
+\&                             U+1063..1064, U+1069..106D, U+1087..108D
+\&                             ...)
+\&   \ep{Indic_Syllabic_Category: Virama} (Short: \ep{InSC=Virama}) (27:
+\&                             U+094D, U+09CD, U+0A4D, U+0ACD, U+0B4D,
+\&                             U+0BCD ...)
+\&   \ep{Indic_Syllabic_Category: Visarga} (Short: \ep{InSC=Visarga})
+\&                             (36: U+0903, U+0983, U+0A03, U+0A83,
+\&                             U+0B03, U+0C03 ...)
+\&   \ep{Indic_Syllabic_Category: Vowel} (Short: \ep{InSC=Vowel}) (30:
+\&                             U+1963..196D, U+A85E..A861, U+A866,
+\&                             U+A922..A92A, U+11150..11154)
+\&   \ep{Indic_Syllabic_Category: Vowel_Dependent} (Short: \ep{InSC=
+\&                             VowelDependent}) (697: U+093A..093B,
+\&                             U+093E..094C, U+094E..094F,
+\&                             U+0955..0957, U+0962..0963, U+09BE..09C4
+\&                             ...)
+\&   \ep{Indic_Syllabic_Category: Vowel_Independent} (Short: \ep{InSC=
+\&                             VowelIndependent}) (500: U+0904..0914,
+\&                             U+0960..0961, U+0972..0977,
+\&                             U+0985..098C, U+098F..0990, U+0993..0994
+\&                             ...)
+\&   \ep{Inherited}           \ep{Script_Extensions=Inherited} (Short:
+\&                             \ep{Zinh}) (586)
+\&   \ep{Initial_Punctuation} \ep{General_Category=Initial_Punctuation}
+\&                             (Short: \ep{Pi}) (12)
+\&   \ep{InPC: *}             \ep{Indic_Positional_Category: *}
+\&   \ep{InSC: *}             \ep{Indic_Syllabic_Category: *}
+\&   \ep{Inscriptional_Pahlavi} \ep{Script_Extensions=
+\&                             Inscriptional_Pahlavi} (Short: \ep{Phli};
+\&                             NOT \ep{Block=Inscriptional_Pahlavi}) (27)
+\&   \ep{Inscriptional_Parthian} \ep{Script_Extensions=
+\&                             Inscriptional_Parthian} (Short:
+\&                             \ep{Prti}; NOT \ep{Block=
+\&                             Inscriptional_Parthian}) (30)
+\& X \ep{IPA_Ext}             \ep{IPA_Extensions} (= \ep{Block=
+\&                             IPA_Extensions}) (96)
+\& X \ep{IPA_Extensions}      \ep{Block=IPA_Extensions} (Short:
+\&                             \ep{InIPAExt}) (96)
+\&   \ep{Is_*}                \ep{*} (Any exceptions are individually
+\&                             noted beginning with the word NOT.) If
+\&                             an entry has flag(s) at its beginning,
+\&                             like "D", the "Is_" form has the same
+\&                             flag(s)
+\&   \ep{Ital}                \ep{Old_Italic} (= \ep{Script_Extensions=
+\&                             Old_Italic}) (NOT \ep{Block=Old_Italic})
+\&                             (39)
+\& X \ep{Jamo}                \ep{Hangul_Jamo} (= \ep{Block=Hangul_Jamo})
+\&                             (256)
+\& X \ep{Jamo_Ext_A}          \ep{Hangul_Jamo_Extended_A} (= \ep{Block=
+\&                             Hangul_Jamo_Extended_A}) (32)
+\& X \ep{Jamo_Ext_B}          \ep{Hangul_Jamo_Extended_B} (= \ep{Block=
+\&                             Hangul_Jamo_Extended_B}) (80)
+\&   \ep{Java}                \ep{Javanese} (= \ep{Script_Extensions=
+\&                             Javanese}) (NOT \ep{Block=Javanese}) (91)
+\&   \ep{Javanese}            \ep{Script_Extensions=Javanese} (Short:
+\&                             \ep{Java}; NOT \ep{Block=Javanese}) (91)
+\&   \ep{Jg: *}               \ep{Joining_Group: *}
+\&   \ep{Join_C}              \ep{Join_Control} (= \ep{Join_Control=Y}) (2)
+\&   \ep{Join_C: *}           \ep{Join_Control: *}
+\&   \ep{Join_Control}        \ep{Join_Control=Y} (Short: \ep{JoinC}) (2)
+\&   \ep{Join_Control: N*}    (Short: \ep{JoinC=N}, \eP{JoinC}) (1_114_110
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..200B, U+200E..infinity)
+\&   \ep{Join_Control: Y*}    (Short: \ep{JoinC=Y}, \ep{JoinC}) (2:
+\&                             U+200C..200D)
+\&   \ep{Joining_Group: African_Feh} (Short: \ep{Jg=AfricanFeh}) (1:
+\&                             U+08BB)
+\&   \ep{Joining_Group: African_Noon} (Short: \ep{Jg=AfricanNoon}) (1:
+\&                             U+08BD)
+\&   \ep{Joining_Group: African_Qaf} (Short: \ep{Jg=AfricanQaf}) (2:
+\&                             U+08BC, U+08C4)
+\&   \ep{Joining_Group: Ain}  (Short: \ep{Jg=Ain}) (9: U+0639..063A,
+\&                             U+06A0, U+06FC, U+075D..075F, U+08B3,
+\&                             U+08C3)
+\&   \ep{Joining_Group: Alaph} (Short: \ep{Jg=Alaph}) (1: U+0710)
+\&   \ep{Joining_Group: Alef} (Short: \ep{Jg=Alef}) (29: U+0622..0623,
+\&                             U+0625, U+0627, U+0671..0673, U+0675,
+\&                             U+0773..0774 ...)
+\&   \ep{Joining_Group: Beh}  (Short: \ep{Jg=Beh}) (27: U+0628,
+\&                             U+062A..062B, U+066E, U+0679..0680,
+\&                             U+0750..0756, U+08A0..08A1 ...)
+\&   \ep{Joining_Group: Beth} (Short: \ep{Jg=Beth}) (2: U+0712, U+072D)
+\&   \ep{Joining_Group: Burushaski_Yeh_Barree} (Short: \ep{Jg=
+\&                             BurushaskiYehBarree}) (2: U+077A..077B)
+\&   \ep{Joining_Group: Dal}  (Short: \ep{Jg=Dal}) (15: U+062F..0630,
+\&                             U+0688..0690, U+06EE, U+0759..075A,
+\&                             U+08AE)
+\&   \ep{Joining_Group: Dalath_Rish} (Short: \ep{Jg=DalathRish}) (4:
+\&                             U+0715..0716, U+072A, U+072F)
+\&   \ep{Joining_Group: E}    (Short: \ep{Jg=E}) (1: U+0725)
+\&   \ep{Joining_Group: Farsi_Yeh} (Short: \ep{Jg=FarsiYeh}) (7:
+\&                             U+063D..063F, U+06CC, U+06CE,
+\&                             U+0775..0776)
+\&   \ep{Joining_Group: Fe}   (Short: \ep{Jg=Fe}) (1: U+074F)
+\&   \ep{Joining_Group: Feh}  (Short: \ep{Jg=Feh}) (10: U+0641,
+\&                             U+06A1..06A6, U+0760..0761, U+08A4)
+\&   \ep{Joining_Group: Final_Semkath} (Short: \ep{Jg=FinalSemkath}) (1:
+\&                             U+0724)
+\&   \ep{Joining_Group: Gaf}  (Short: \ep{Jg=Gaf}) (17: U+063B..063C,
+\&                             U+06A9, U+06AB, U+06AF..06B4,
+\&                             U+0762..0764, U+088D ...)
+\&   \ep{Joining_Group: Gamal} (Short: \ep{Jg=Gamal}) (3: U+0713..0714,
+\&                             U+072E)
+\&   \ep{Joining_Group: Hah}  (Short: \ep{Jg=Hah}) (22: U+062C..062E,
+\&                             U+0681..0687, U+06BF, U+0757..0758,
+\&                             U+076E..076F, U+0772 ...)
+\&   \ep{Joining_Group: Hamza_On_Heh_Goal} (Short: \ep{Jg=
+\&                             HamzaOnHehGoal}) (1: U+06C3)
+\&   \ep{Joining_Group: Hanifi_Rohingya_Kinna_Ya} (Short: \ep{Jg=
+\&                             HanifiRohingyaKinnaYa}) (4: U+10D19,
+\&                             U+10D1E, U+10D20, U+10D23)
+\&   \ep{Joining_Group: Hanifi_Rohingya_Pa} (Short: \ep{Jg=
+\&                             HanifiRohingyaPa}) (3: U+10D02, U+10D09,
+\&                             U+10D1C)
+\&   \ep{Joining_Group: He}   (Short: \ep{Jg=He}) (1: U+0717)
+\&   \ep{Joining_Group: Heh}  (Short: \ep{Jg=Heh}) (1: U+0647)
+\&   \ep{Joining_Group: Heh_Goal} (Short: \ep{Jg=HehGoal}) (2:
+\&                             U+06C1..06C2)
+\&   \ep{Joining_Group: Heth} (Short: \ep{Jg=Heth}) (1: U+071A)
+\&   \ep{Joining_Group: Kaf}  (Short: \ep{Jg=Kaf}) (6: U+0643,
+\&                             U+06AC..06AE, U+077F, U+08B4)
+\&   \ep{Joining_Group: Kaph} (Short: \ep{Jg=Kaph}) (1: U+071F)
+\&   \ep{Joining_Group: Khaph} (Short: \ep{Jg=Khaph}) (1: U+074E)
+\&   \ep{Joining_Group: Knotted_Heh} (Short: \ep{Jg=KnottedHeh}) (2:
+\&                             U+06BE, U+06FF)
+\&   \ep{Joining_Group: Lam}  (Short: \ep{Jg=Lam}) (8: U+0644,
+\&                             U+06B5..06B8, U+076A, U+08A6, U+08C7)
+\&   \ep{Joining_Group: Lamadh} (Short: \ep{Jg=Lamadh}) (1: U+0720)
+\&   \ep{Joining_Group: Malayalam_Bha} (Short: \ep{Jg=MalayalamBha}) (1:
+\&                             U+0866)
+\&   \ep{Joining_Group: Malayalam_Ja} (Short: \ep{Jg=MalayalamJa}) (1:
+\&                             U+0861)
+\&   \ep{Joining_Group: Malayalam_Lla} (Short: \ep{Jg=MalayalamLla}) (1:
+\&                             U+0868)
+\&   \ep{Joining_Group: Malayalam_Llla} (Short: \ep{Jg=MalayalamLlla})
+\&                             (1: U+0869)
+\&   \ep{Joining_Group: Malayalam_Nga} (Short: \ep{Jg=MalayalamNga}) (1:
+\&                             U+0860)
+\&   \ep{Joining_Group: Malayalam_Nna} (Short: \ep{Jg=MalayalamNna}) (1:
+\&                             U+0864)
+\&   \ep{Joining_Group: Malayalam_Nnna} (Short: \ep{Jg=MalayalamNnna})
+\&                             (1: U+0865)
+\&   \ep{Joining_Group: Malayalam_Nya} (Short: \ep{Jg=MalayalamNya}) (1:
+\&                             U+0862)
+\&   \ep{Joining_Group: Malayalam_Ra} (Short: \ep{Jg=MalayalamRa}) (1:
+\&                             U+0867)
+\&   \ep{Joining_Group: Malayalam_Ssa} (Short: \ep{Jg=MalayalamSsa}) (1:
+\&                             U+086A)
+\&   \ep{Joining_Group: Malayalam_Tta} (Short: \ep{Jg=MalayalamTta}) (1:
+\&                             U+0863)
+\&   \ep{Joining_Group: Manichaean_Aleph} (Short: \ep{Jg=
+\&                             ManichaeanAleph}) (1: U+10AC0)
+\&   \ep{Joining_Group: Manichaean_Ayin} (Short: \ep{Jg=ManichaeanAyin})
+\&                             (2: U+10AD9..10ADA)
+\&   \ep{Joining_Group: Manichaean_Beth} (Short: \ep{Jg=ManichaeanBeth})
+\&                             (2: U+10AC1..10AC2)
+\&   \ep{Joining_Group: Manichaean_Daleth} (Short: \ep{Jg=
+\&                             ManichaeanDaleth}) (1: U+10AC5)
+\&   \ep{Joining_Group: Manichaean_Dhamedh} (Short: \ep{Jg=
+\&                             ManichaeanDhamedh}) (1: U+10AD4)
+\&   \ep{Joining_Group: Manichaean_Five} (Short: \ep{Jg=ManichaeanFive})
+\&                             (1: U+10AEC)
+\&   \ep{Joining_Group: Manichaean_Gimel} (Short: \ep{Jg=
+\&                             ManichaeanGimel}) (2: U+10AC3..10AC4)
+\&   \ep{Joining_Group: Manichaean_Heth} (Short: \ep{Jg=ManichaeanHeth})
+\&                             (1: U+10ACD)
+\&   \ep{Joining_Group: Manichaean_Hundred} (Short: \ep{Jg=
+\&                             ManichaeanHundred}) (1: U+10AEF)
+\&   \ep{Joining_Group: Manichaean_Kaph} (Short: \ep{Jg=ManichaeanKaph})
+\&                             (3: U+10AD0..10AD2)
+\&   \ep{Joining_Group: Manichaean_Lamedh} (Short: \ep{Jg=
+\&                             ManichaeanLamedh}) (1: U+10AD3)
+\&   \ep{Joining_Group: Manichaean_Mem} (Short: \ep{Jg=ManichaeanMem})
+\&                             (1: U+10AD6)
+\&   \ep{Joining_Group: Manichaean_Nun} (Short: \ep{Jg=ManichaeanNun})
+\&                             (1: U+10AD7)
+\&   \ep{Joining_Group: Manichaean_One} (Short: \ep{Jg=ManichaeanOne})
+\&                             (1: U+10AEB)
+\&   \ep{Joining_Group: Manichaean_Pe} (Short: \ep{Jg=ManichaeanPe}) (2:
+\&                             U+10ADB..10ADC)
+\&   \ep{Joining_Group: Manichaean_Qoph} (Short: \ep{Jg=ManichaeanQoph})
+\&                             (3: U+10ADE..10AE0)
+\&   \ep{Joining_Group: Manichaean_Resh} (Short: \ep{Jg=ManichaeanResh})
+\&                             (1: U+10AE1)
+\&   \ep{Joining_Group: Manichaean_Sadhe} (Short: \ep{Jg=
+\&                             ManichaeanSadhe}) (1: U+10ADD)
+\&   \ep{Joining_Group: Manichaean_Samekh} (Short: \ep{Jg=
+\&                             ManichaeanSamekh}) (1: U+10AD8)
+\&   \ep{Joining_Group: Manichaean_Taw} (Short: \ep{Jg=ManichaeanTaw})
+\&                             (1: U+10AE4)
+\&   \ep{Joining_Group: Manichaean_Ten} (Short: \ep{Jg=ManichaeanTen})
+\&                             (1: U+10AED)
+\&   \ep{Joining_Group: Manichaean_Teth} (Short: \ep{Jg=ManichaeanTeth})
+\&                             (1: U+10ACE)
+\&   \ep{Joining_Group: Manichaean_Thamedh} (Short: \ep{Jg=
+\&                             ManichaeanThamedh}) (1: U+10AD5)
+\&   \ep{Joining_Group: Manichaean_Twenty} (Short: \ep{Jg=
+\&                             ManichaeanTwenty}) (1: U+10AEE)
+\&   \ep{Joining_Group: Manichaean_Waw} (Short: \ep{Jg=ManichaeanWaw})
+\&                             (1: U+10AC7)
+\&   \ep{Joining_Group: Manichaean_Yodh} (Short: \ep{Jg=ManichaeanYodh})
+\&                             (1: U+10ACF)
+\&   \ep{Joining_Group: Manichaean_Zayin} (Short: \ep{Jg=
+\&                             ManichaeanZayin}) (2: U+10AC9..10ACA)
+\&   \ep{Joining_Group: Meem} (Short: \ep{Jg=Meem}) (4: U+0645,
+\&                             U+0765..0766, U+08A7)
+\&   \ep{Joining_Group: Mim}  (Short: \ep{Jg=Mim}) (1: U+0721)
+\&   \ep{Joining_Group: No_Joining_Group} (Short: \ep{Jg=NoJoiningGroup})
+\&                             (1_113_762 plus all above\-Unicode code
+\&                             points: U+0000..061F, U+0621, U+0640,
+\&                             U+064B..066D, U+0670, U+0674 ...)
+\&   \ep{Joining_Group: Noon} (Short: \ep{Jg=Noon}) (9: U+0646,
+\&                             U+06B9..06BC, U+0767..0769, U+0889)
+\&   \ep{Joining_Group: Nun}  (Short: \ep{Jg=Nun}) (1: U+0722)
+\&   \ep{Joining_Group: Nya}  (Short: \ep{Jg=Nya}) (1: U+06BD)
+\&   \ep{Joining_Group: Pe}   (Short: \ep{Jg=Pe}) (1: U+0726)
+\&   \ep{Joining_Group: Qaf}  (Short: \ep{Jg=Qaf}) (6: U+0642, U+066F,
+\&                             U+06A7..06A8, U+08A5, U+08B5)
+\&   \ep{Joining_Group: Qaph} (Short: \ep{Jg=Qaph}) (1: U+0729)
+\&   \ep{Joining_Group: Reh}  (Short: \ep{Jg=Reh}) (19: U+0631..0632,
+\&                             U+0691..0699, U+06EF, U+075B,
+\&                             U+076B..076C, U+0771 ...)
+\&   \ep{Joining_Group: Reversed_Pe} (Short: \ep{Jg=ReversedPe}) (1:
+\&                             U+0727)
+\&   \ep{Joining_Group: Rohingya_Yeh} (Short: \ep{Jg=RohingyaYeh}) (1:
+\&                             U+08AC)
+\&   \ep{Joining_Group: Sad}  (Short: \ep{Jg=Sad}) (6: U+0635..0636,
+\&                             U+069D..069E, U+06FB, U+08AF)
+\&   \ep{Joining_Group: Sadhe} (Short: \ep{Jg=Sadhe}) (1: U+0728)
+\&   \ep{Joining_Group: Seen} (Short: \ep{Jg=Seen}) (11: U+0633..0634,
+\&                             U+069A..069C, U+06FA, U+075C, U+076D,
+\&                             U+0770 ...)
+\&   \ep{Joining_Group: Semkath} (Short: \ep{Jg=Semkath}) (1: U+0723)
+\&   \ep{Joining_Group: Shin} (Short: \ep{Jg=Shin}) (1: U+072B)
+\&   \ep{Joining_Group: Straight_Waw} (Short: \ep{Jg=StraightWaw}) (1:
+\&                             U+08B1)
+\&   \ep{Joining_Group: Swash_Kaf} (Short: \ep{Jg=SwashKaf}) (1: U+06AA)
+\&   \ep{Joining_Group: Syriac_Waw} (Short: \ep{Jg=SyriacWaw}) (1: U+0718)
+\&   \ep{Joining_Group: Tah}  (Short: \ep{Jg=Tah}) (6: U+0637..0638,
+\&                             U+069F, U+088B..088C, U+08A3)
+\&   \ep{Joining_Group: Taw}  (Short: \ep{Jg=Taw}) (1: U+072C)
+\&   \ep{Joining_Group: Teh_Marbuta} (Short: \ep{Jg=TehMarbuta}) (3:
+\&                             U+0629, U+06C0, U+06D5)
+\&   \ep{Joining_Group: Teh_Marbuta_Goal} \ep{Joining_Group=
+\&                             Hamza_On_Heh_Goal} (1)
+\&   \ep{Joining_Group: Teth} (Short: \ep{Jg=Teth}) (2: U+071B..071C)
+\&   \ep{Joining_Group: Thin_Yeh} (Short: \ep{Jg=ThinYeh}) (1: U+0886)
+\&   \ep{Joining_Group: Vertical_Tail} (Short: \ep{Jg=VerticalTail}) (1:
+\&                             U+088E)
+\&   \ep{Joining_Group: Waw}  (Short: \ep{Jg=Waw}) (16: U+0624, U+0648,
+\&                             U+0676..0677, U+06C4..06CB, U+06CF,
+\&                             U+0778..0779 ...)
+\&   \ep{Joining_Group: Yeh}  (Short: \ep{Jg=Yeh}) (11: U+0620, U+0626,
+\&                             U+0649..064A, U+0678, U+06D0..06D1,
+\&                             U+0777 ...)
+\&   \ep{Joining_Group: Yeh_Barree} (Short: \ep{Jg=YehBarree}) (2:
+\&                             U+06D2..06D3)
+\&   \ep{Joining_Group: Yeh_With_Tail} (Short: \ep{Jg=YehWithTail}) (1:
+\&                             U+06CD)
+\&   \ep{Joining_Group: Yudh} (Short: \ep{Jg=Yudh}) (1: U+071D)
+\&   \ep{Joining_Group: Yudh_He} (Short: \ep{Jg=YudhHe}) (1: U+071E)
+\&   \ep{Joining_Group: Zain} (Short: \ep{Jg=Zain}) (1: U+0719)
+\&   \ep{Joining_Group: Zhain} (Short: \ep{Jg=Zhain}) (1: U+074D)
+\&   \ep{Joining_Type: C}     \ep{Joining_Type=Join_Causing} (7)
+\&   \ep{Joining_Type: D}     \ep{Joining_Type=Dual_Joining} (610)
+\&   \ep{Joining_Type: Dual_Joining} (Short: \ep{Jt=D}) (610: U+0620,
+\&                             U+0626, U+0628, U+062A..062E,
+\&                             U+0633..063F, U+0641..0647 ...)
+\&   \ep{Joining_Type: Join_Causing} (Short: \ep{Jt=C}) (7: U+0640,
+\&                             U+07FA, U+0883..0885, U+180A, U+200D)
+\&   \ep{Joining_Type: L}     \ep{Joining_Type=Left_Joining} (5)
+\&   \ep{Joining_Type: Left_Joining} (Short: \ep{Jt=L}) (5: U+A872,
+\&                             U+10ACD, U+10AD7, U+10D00, U+10FCB)
+\&   \ep{Joining_Type: Non_Joining} (Short: \ep{Jt=U}) (1_111_188 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \exac\exae\-\exff], U+0100..02FF,
+\&                             U+0370..0482, U+048A..0590, U+05BE,
+\&                             U+05C0 ...)
+\&   \ep{Joining_Type: R}     \ep{Joining_Type=Right_Joining} (152)
+\&   \ep{Joining_Type: Right_Joining} (Short: \ep{Jt=R}) (152:
+\&                             U+0622..0625, U+0627, U+0629,
+\&                             U+062F..0632, U+0648, U+0671..0673 ...)
+\&   \ep{Joining_Type: T}     \ep{Joining_Type=Transparent} (2150)
+\&   \ep{Joining_Type: Transparent} (Short: \ep{Jt=T}) (2150: [\exad],
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2 ...)
+\&   \ep{Joining_Type: U}     \ep{Joining_Type=Non_Joining} (1_111_188
+\&                             plus all above\-Unicode code points)
+\&   \ep{Jt: *}               \ep{Joining_Type: *}
+\&   \ep{Kaithi}              \ep{Script_Extensions=Kaithi} (Short:
+\&                             \ep{Kthi}; NOT \ep{Block=Kaithi}) (88)
+\& X \ep{Kaktovik_Numerals}   \ep{Block=Kaktovik_Numerals} (32)
+\&   \ep{Kali}                \ep{Kayah_Li} (= \ep{Script_Extensions=
+\&                             Kayah_Li}) (48)
+\&   \ep{Kana}                \ep{Katakana} (= \ep{Script_Extensions=
+\&                             Katakana}) (NOT \ep{Block=Katakana}) (373)
+\& X \ep{Kana_Ext_A}          \ep{Kana_Extended_A} (= \ep{Block=
+\&                             Kana_Extended_A}) (48)
+\& X \ep{Kana_Ext_B}          \ep{Kana_Extended_B} (= \ep{Block=
+\&                             Kana_Extended_B}) (16)
+\& X \ep{Kana_Extended_A}     \ep{Block=Kana_Extended_A} (Short:
+\&                             \ep{InKanaExtA}) (48)
+\& X \ep{Kana_Extended_B}     \ep{Block=Kana_Extended_B} (Short:
+\&                             \ep{InKanaExtB}) (16)
+\& X \ep{Kana_Sup}            \ep{Kana_Supplement} (= \ep{Block=
+\&                             Kana_Supplement}) (256)
+\& X \ep{Kana_Supplement}     \ep{Block=Kana_Supplement} (Short:
+\&                             \ep{InKanaSup}) (256)
+\& X \ep{Kanbun}              \ep{Block=Kanbun} (16)
+\& X \ep{Kangxi}              \ep{Kangxi_Radicals} (= \ep{Block=
+\&                             Kangxi_Radicals}) (224)
+\& X \ep{Kangxi_Radicals}     \ep{Block=Kangxi_Radicals} (Short:
+\&                             \ep{InKangxi}) (224)
+\&   \ep{Kannada}             \ep{Script_Extensions=Kannada} (Short:
+\&                             \ep{Knda}; NOT \ep{Block=Kannada}) (106)
+\&   \ep{Katakana}            \ep{Script_Extensions=Katakana} (Short:
+\&                             \ep{Kana}; NOT \ep{Block=Katakana}) (373)
+\& X \ep{Katakana_Ext}        \ep{Katakana_Phonetic_Extensions} (=
+\&                             \ep{Block=Katakana_Phonetic_Extensions})
+\&                             (16)
+\& X \ep{Katakana_Phonetic_Extensions} \ep{Block=
+\&                             Katakana_Phonetic_Extensions} (Short:
+\&                             \ep{InKatakanaExt}) (16)
+\&   \ep{Kawi}                \ep{Script_Extensions=Kawi} (NOT \ep{Block=
+\&                             Kawi}) (86)
+\&   \ep{Kayah_Li}            \ep{Script_Extensions=Kayah_Li} (Short:
+\&                             \ep{Kali}) (48)
+\&   \ep{Khar}                \ep{Kharoshthi} (= \ep{Script_Extensions=
+\&                             Kharoshthi}) (NOT \ep{Block=Kharoshthi})
+\&                             (68)
+\&   \ep{Kharoshthi}          \ep{Script_Extensions=Kharoshthi} (Short:
+\&                             \ep{Khar}; NOT \ep{Block=Kharoshthi}) (68)
+\&   \ep{Khitan_Small_Script} \ep{Script_Extensions=Khitan_Small_Script}
+\&                             (Short: \ep{Kits}; NOT \ep{Block=
+\&                             Khitan_Small_Script}) (471)
+\&   \ep{Khmer}               \ep{Script_Extensions=Khmer} (Short:
+\&                             \ep{Khmr}; NOT \ep{Block=Khmer}) (146)
+\& X \ep{Khmer_Symbols}       \ep{Block=Khmer_Symbols} (32)
+\&   \ep{Khmr}                \ep{Khmer} (= \ep{Script_Extensions=Khmer})
+\&                             (NOT \ep{Block=Khmer}) (146)
+\&   \ep{Khoj}                \ep{Khojki} (= \ep{Script_Extensions=
+\&                             Khojki}) (NOT \ep{Block=Khojki}) (85)
+\&   \ep{Khojki}              \ep{Script_Extensions=Khojki} (Short:
+\&                             \ep{Khoj}; NOT \ep{Block=Khojki}) (85)
+\&   \ep{Khudawadi}           \ep{Script_Extensions=Khudawadi} (Short:
+\&                             \ep{Sind}; NOT \ep{Block=Khudawadi}) (81)
+\&   \ep{Kits}                \ep{Khitan_Small_Script} (=
+\&                             \ep{Script_Extensions=
+\&                             Khitan_Small_Script}) (NOT \ep{Block=
+\&                             Khitan_Small_Script}) (471)
+\&   \ep{Knda}                \ep{Kannada} (= \ep{Script_Extensions=
+\&                             Kannada}) (NOT \ep{Block=Kannada}) (106)
+\&   \ep{Kthi}                \ep{Kaithi} (= \ep{Script_Extensions=
+\&                             Kaithi}) (NOT \ep{Block=Kaithi}) (88)
+\&   \ep{L} \epL               \ep{Letter} (= \ep{General_Category=Letter})
+\&                             (136_104)
+\& X \ep{L&}                  \ep{Cased_Letter} (= \ep{General_Category=
+\&                             Cased_Letter}) (4095)
+\& X \ep{L_}                  \ep{Cased_Letter} (= \ep{General_Category=
+\&                             Cased_Letter}) Note the trailing \*(Aq_\*(Aq
+\&                             matters in spite of loose matching
+\&                             rules. (4095)
+\&   \ep{Lana}                \ep{Tai_Tham} (= \ep{Script_Extensions=
+\&                             Tai_Tham}) (NOT \ep{Block=Tai_Tham}) (127)
+\&   \ep{Lao}                 \ep{Script_Extensions=Lao} (NOT \ep{Block=
+\&                             Lao}) (83)
+\&   \ep{Laoo}                \ep{Lao} (= \ep{Script_Extensions=Lao}) (NOT
+\&                             \ep{Block=Lao}) (83)
+\&   \ep{Latin}               \ep{Script_Extensions=Latin} (Short:
+\&                             \ep{Latn}) (1510)
+\& X \ep{Latin_1}             \ep{Latin_1_Supplement} (= \ep{Block=
+\&                             Latin_1_Supplement}) (128)
+\& X \ep{Latin_1_Sup}         \ep{Latin_1_Supplement} (= \ep{Block=
+\&                             Latin_1_Supplement}) (128)
+\& X \ep{Latin_1_Supplement}  \ep{Block=Latin_1_Supplement} (Short:
+\&                             \ep{InLatin1}) (128)
+\& X \ep{Latin_Ext_A}         \ep{Latin_Extended_A} (= \ep{Block=
+\&                             Latin_Extended_A}) (128)
+\& X \ep{Latin_Ext_Additional} \ep{Latin_Extended_Additional} (=
+\&                             \ep{Block=Latin_Extended_Additional})
+\&                             (256)
+\& X \ep{Latin_Ext_B}         \ep{Latin_Extended_B} (= \ep{Block=
+\&                             Latin_Extended_B}) (208)
+\& X \ep{Latin_Ext_C}         \ep{Latin_Extended_C} (= \ep{Block=
+\&                             Latin_Extended_C}) (32)
+\& X \ep{Latin_Ext_D}         \ep{Latin_Extended_D} (= \ep{Block=
+\&                             Latin_Extended_D}) (224)
+\& X \ep{Latin_Ext_E}         \ep{Latin_Extended_E} (= \ep{Block=
+\&                             Latin_Extended_E}) (64)
+\& X \ep{Latin_Ext_F}         \ep{Latin_Extended_F} (= \ep{Block=
+\&                             Latin_Extended_F}) (64)
+\& X \ep{Latin_Ext_G}         \ep{Latin_Extended_G} (= \ep{Block=
+\&                             Latin_Extended_G}) (256)
+\& X \ep{Latin_Extended_A}    \ep{Block=Latin_Extended_A} (Short:
+\&                             \ep{InLatinExtA}) (128)
+\& X \ep{Latin_Extended_Additional} \ep{Block=Latin_Extended_Additional}
+\&                             (Short: \ep{InLatinExtAdditional}) (256)
+\& X \ep{Latin_Extended_B}    \ep{Block=Latin_Extended_B} (Short:
+\&                             \ep{InLatinExtB}) (208)
+\& X \ep{Latin_Extended_C}    \ep{Block=Latin_Extended_C} (Short:
+\&                             \ep{InLatinExtC}) (32)
+\& X \ep{Latin_Extended_D}    \ep{Block=Latin_Extended_D} (Short:
+\&                             \ep{InLatinExtD}) (224)
+\& X \ep{Latin_Extended_E}    \ep{Block=Latin_Extended_E} (Short:
+\&                             \ep{InLatinExtE}) (64)
+\& X \ep{Latin_Extended_F}    \ep{Block=Latin_Extended_F} (Short:
+\&                             \ep{InLatinExtF}) (64)
+\& X \ep{Latin_Extended_G}    \ep{Block=Latin_Extended_G} (Short:
+\&                             \ep{InLatinExtG}) (256)
+\&   \ep{Latn}                \ep{Latin} (= \ep{Script_Extensions=Latin})
+\&                             (1510)
+\&   \ep{Lb: *}               \ep{Line_Break: *}
+\&   \ep{LC}                  \ep{Cased_Letter} (= \ep{General_Category=
+\&                             Cased_Letter}) (4095)
+\&   \ep{Lepc}                \ep{Lepcha} (= \ep{Script_Extensions=
+\&                             Lepcha}) (NOT \ep{Block=Lepcha}) (74)
+\&   \ep{Lepcha}              \ep{Script_Extensions=Lepcha} (Short:
+\&                             \ep{Lepc}; NOT \ep{Block=Lepcha}) (74)
+\&   \ep{Letter}              \ep{General_Category=Letter} (Short: \ep{L})
+\&                             (136_104)
+\&   \ep{Letter_Number}       \ep{General_Category=Letter_Number} (Short:
+\&                             \ep{Nl}) (236)
+\& X \ep{Letterlike_Symbols}  \ep{Block=Letterlike_Symbols} (80)
+\&   \ep{Limb}                \ep{Limbu} (= \ep{Script_Extensions=Limbu})
+\&                             (NOT \ep{Block=Limbu}) (69)
+\&   \ep{Limbu}               \ep{Script_Extensions=Limbu} (Short:
+\&                             \ep{Limb}; NOT \ep{Block=Limbu}) (69)
+\&   \ep{Lina}                \ep{Linear_A} (= \ep{Script_Extensions=
+\&                             Linear_A}) (NOT \ep{Block=Linear_A}) (386)
+\&   \ep{Linb}                \ep{Linear_B} (= \ep{Script_Extensions=
+\&                             Linear_B}) (268)
+\&   \ep{Line_Break: AI}      \ep{Line_Break=Ambiguous} (707)
+\&   \ep{Line_Break: AL}      \ep{Line_Break=Alphabetic} (22_215)
+\&   \ep{Line_Break: Alphabetic} (Short: \ep{Lb=AL}) (22_215: [#&*<=>\e@A\-
+\&                             Z\e^_\`a\-z~\exa6\exa9\exac\exae\-\exaf\exb5\exc0\-
+\&                             \exd6\exd8\-\exf6\exf8\-\exff], U+0100..02C6,
+\&                             U+02CE..02CF, U+02D1..02D7, U+02DC,
+\&                             U+02DE ...)
+\&   \ep{Line_Break: Ambiguous} (Short: \ep{Lb=AI}) (707: [\exa7\-\exa8\exaa
+\&                             \exb2\-\exb3\exb6\-\exba\exbc\-\exbe\exd7\exf7],
+\&                             U+02C7, U+02C9..02CB, U+02CD, U+02D0,
+\&                             U+02D8..02DB ...)
+\&   \ep{Line_Break: B2}      \ep{Line_Break=Break_Both} (3)
+\&   \ep{Line_Break: BA}      \ep{Line_Break=Break_After} (249)
+\&   \ep{Line_Break: BB}      \ep{Line_Break=Break_Before} (55)
+\&   \ep{Line_Break: BK}      \ep{Line_Break=Mandatory_Break} (4)
+\&   \ep{Line_Break: Break_After} (Short: \ep{Lb=BA}) (249: [\et\e|\exad],
+\&                             U+058A, U+05BE, U+0964..0965,
+\&                             U+0E5A..0E5B, U+0F0B ...)
+\&   \ep{Line_Break: Break_Before} (Short: \ep{Lb=BB}) (55: [\exb4],
+\&                             U+02C8, U+02CC, U+02DF, U+0C77, U+0C84
+\&                             ...)
+\&   \ep{Line_Break: Break_Both} (Short: \ep{Lb=B2}) (3: U+2014,
+\&                             U+2E3A..2E3B)
+\&   \ep{Line_Break: Break_Symbols} (Short: \ep{Lb=SY}) (1: [\e/])
+\&   \ep{Line_Break: Carriage_Return} (Short: \ep{Lb=CR}) (1: [\er])
+\&   \ep{Line_Break: CB}      \ep{Line_Break=Contingent_Break} (1)
+\&   \ep{Line_Break: CJ}      \ep{Line_Break=
+\&                             Conditional_Japanese_Starter} (60)
+\&   \ep{Line_Break: CL}      \ep{Line_Break=Close_Punctuation} (97)
+\&   \ep{Line_Break: Close_Parenthesis} (Short: \ep{Lb=CP}) (2: [\e)\e]])
+\&   \ep{Line_Break: Close_Punctuation} (Short: \ep{Lb=CL}) (97: [\e}],
+\&                             U+0F3B, U+0F3D, U+169C, U+2046, U+207E
+\&                             ...)
+\&   \ep{Line_Break: CM}      \ep{Line_Break=Combining_Mark} (2438)
+\&   \ep{Line_Break: Combining_Mark} (Short: \ep{Lb=CM}) (2438: [^\et\en
+\&                             \ecK\ef\er\ex20\-\ex7e\ex85\exa0\-\exff],
+\&                             U+0300..034E, U+0350..035B,
+\&                             U+0363..036F, U+0483..0489, U+0591..05BD
+\&                             ...)
+\&   \ep{Line_Break: Complex_Context} (Short: \ep{Lb=SA}) (758:
+\&                             U+0E01..0E3A, U+0E40..0E4E,
+\&                             U+0E81..0E82, U+0E84, U+0E86..0E8A,
+\&                             U+0E8C..0EA3 ...)
+\&   \ep{Line_Break: Conditional_Japanese_Starter} (Short: \ep{Lb=CJ})
+\&                             (60: U+3041, U+3043, U+3045, U+3047,
+\&                             U+3049, U+3063 ...)
+\&   \ep{Line_Break: Contingent_Break} (Short: \ep{Lb=CB}) (1: U+FFFC)
+\&   \ep{Line_Break: CP}      \ep{Line_Break=Close_Parenthesis} (2)
+\&   \ep{Line_Break: CR}      \ep{Line_Break=Carriage_Return} (1)
+\&   \ep{Line_Break: E_Base}  (Short: \ep{Lb=EB}) (134: U+261D, U+26F9,
+\&                             U+270A..270D, U+1F385, U+1F3C2..1F3C4,
+\&                             U+1F3C7 ...)
+\&   \ep{Line_Break: E_Modifier} (Short: \ep{Lb=EM}) (5: U+1F3FB..1F3FF)
+\&   \ep{Line_Break: EB}      \ep{Line_Break=E_Base} (134)
+\&   \ep{Line_Break: EM}      \ep{Line_Break=E_Modifier} (5)
+\&   \ep{Line_Break: EX}      \ep{Line_Break=Exclamation} (40)
+\&   \ep{Line_Break: Exclamation} (Short: \ep{Lb=EX}) (40: [!?], U+05C6,
+\&                             U+061B, U+061D..061F, U+06D4, U+07F9 ...)
+\&   \ep{Line_Break: GL}      \ep{Line_Break=Glue} (31)
+\&   \ep{Line_Break: Glue}    (Short: \ep{Lb=GL}) (31: [\exa0], U+034F,
+\&                             U+035C..0362, U+0F08, U+0F0C, U+0F12 ...)
+\&   \ep{Line_Break: H2}      (Short: \ep{Lb=H2}) (399: U+AC00, U+AC1C,
+\&                             U+AC38, U+AC54, U+AC70, U+AC8C ...)
+\&   \ep{Line_Break: H3}      (Short: \ep{Lb=H3}) (10_773: U+AC01..AC1B,
+\&                             U+AC1D..AC37, U+AC39..AC53,
+\&                             U+AC55..AC6F, U+AC71..AC8B, U+AC8D..ACA7
+\&                             ...)
+\&   \ep{Line_Break: Hebrew_Letter} (Short: \ep{Lb=HL}) (75:
+\&                             U+05D0..05EA, U+05EF..05F2, U+FB1D,
+\&                             U+FB1F..FB28, U+FB2A..FB36, U+FB38..FB3C
+\&                             ...)
+\&   \ep{Line_Break: HL}      \ep{Line_Break=Hebrew_Letter} (75)
+\&   \ep{Line_Break: HY}      \ep{Line_Break=Hyphen} (1)
+\&   \ep{Line_Break: Hyphen}  (Short: \ep{Lb=HY}) (1: [\e\-])
+\&   \ep{Line_Break: ID}      \ep{Line_Break=Ideographic} (172_465)
+\&   \ep{Line_Break: Ideographic} (Short: \ep{Lb=ID}) (172_465:
+\&                             U+231A..231B, U+23F0..23F3,
+\&                             U+2600..2603, U+2614..2615, U+2618,
+\&                             U+261A..261C ...)
+\&   \ep{Line_Break: IN}      \ep{Line_Break=Inseparable} (6)
+\&   \ep{Line_Break: Infix_Numeric} (Short: \ep{Lb=IS}) (13: [,.:;],
+\&                             U+037E, U+0589, U+060C..060D, U+07F8,
+\&                             U+2044 ...)
+\&   \ep{Line_Break: Inseparable} (Short: \ep{Lb=IN}) (6: U+2024..2026,
+\&                             U+22EF, U+FE19, U+10AF6)
+\&   \ep{Line_Break: Inseperable} \ep{Line_Break=Inseparable} (6)
+\&   \ep{Line_Break: IS}      \ep{Line_Break=Infix_Numeric} (13)
+\&   \ep{Line_Break: JL}      (Short: \ep{Lb=JL}) (125: U+1100..115F,
+\&                             U+A960..A97C)
+\&   \ep{Line_Break: JT}      (Short: \ep{Lb=JT}) (137: U+11A8..11FF,
+\&                             U+D7CB..D7FB)
+\&   \ep{Line_Break: JV}      (Short: \ep{Lb=JV}) (95: U+1160..11A7,
+\&                             U+D7B0..D7C6)
+\&   \ep{Line_Break: LF}      \ep{Line_Break=Line_Feed} (1)
+\&   \ep{Line_Break: Line_Feed} (Short: \ep{Lb=LF}) (1: [\en])
+\&   \ep{Line_Break: Mandatory_Break} (Short: \ep{Lb=BK}) (4: [\ecK\ef],
+\&                             U+2028..2029)
+\&   \ep{Line_Break: Next_Line} (Short: \ep{Lb=NL}) (1: [\ex85])
+\&   \ep{Line_Break: NL}      \ep{Line_Break=Next_Line} (1)
+\&   \ep{Line_Break: Nonstarter} (Short: \ep{Lb=NS}) (33: U+17D6,
+\&                             U+203C..203D, U+2047..2049, U+3005,
+\&                             U+301C, U+303B..303C ...)
+\&   \ep{Line_Break: NS}      \ep{Line_Break=Nonstarter} (33)
+\&   \ep{Line_Break: NU}      \ep{Line_Break=Numeric} (672)
+\&   \ep{Line_Break: Numeric} (Short: \ep{Lb=NU}) (672: [0\-9],
+\&                             U+0660..0669, U+066B..066C,
+\&                             U+06F0..06F9, U+07C0..07C9, U+0966..096F
+\&                             ...)
+\&   \ep{Line_Break: OP}      \ep{Line_Break=Open_Punctuation} (94)
+\&   \ep{Line_Break: Open_Punctuation} (Short: \ep{Lb=OP}) (94: [\e(\e[\e{
+\&                             \exa1\exbf], U+0F3A, U+0F3C, U+169B,
+\&                             U+201A, U+201E ...)
+\&   \ep{Line_Break: PO}      \ep{Line_Break=Postfix_Numeric} (38)
+\&   \ep{Line_Break: Postfix_Numeric} (Short: \ep{Lb=PO}) (38: [\e%\exa2
+\&                             \exb0], U+0609..060B, U+066A,
+\&                             U+09F2..09F3, U+09F9, U+0D79 ...)
+\&   \ep{Line_Break: PR}      \ep{Line_Break=Prefix_Numeric} (67)
+\&   \ep{Line_Break: Prefix_Numeric} (Short: \ep{Lb=PR}) (67: [\e$+\e\e\exa3\-
+\&                             \exa5\exb1], U+058F, U+07FE..07FF, U+09FB,
+\&                             U+0AF1, U+0BF9 ...)
+\&   \ep{Line_Break: QU}      \ep{Line_Break=Quotation} (39)
+\&   \ep{Line_Break: Quotation} (Short: \ep{Lb=QU}) (39: [\e"\e\*(Aq\exab\exbb],
+\&                             U+2018..2019, U+201B..201D, U+201F,
+\&                             U+2039..203A, U+275B..2760 ...)
+\&   \ep{Line_Break: Regional_Indicator} (Short: \ep{Lb=RI}) (26:
+\&                             U+1F1E6..1F1FF)
+\&   \ep{Line_Break: RI}      \ep{Line_Break=Regional_Indicator} (26)
+\&   \ep{Line_Break: SA}      \ep{Line_Break=Complex_Context} (758)
+\& D \ep{Line_Break: SG}      \ep{Line_Break=Surrogate} (2048)
+\&   \ep{Line_Break: SP}      \ep{Line_Break=Space} (1)
+\&   \ep{Line_Break: Space}   (Short: \ep{Lb=SP}) (1: [\ex20])
+\& D \ep{Line_Break: Surrogate} Surrogates should never appear in well\-
+\&                             formed text, and therefore shouldn\*(Aqt be
+\&                             the basis for line breaking (Short:
+\&                             \ep{Lb=SG}) (2048: U+D800..DFFF)
+\&   \ep{Line_Break: SY}      \ep{Line_Break=Break_Symbols} (1)
+\&   \ep{Line_Break: Unknown} (Short: \ep{Lb=XX}) (900_198 plus all
+\&                             above\-Unicode code points: U+0378..0379,
+\&                             U+0380..0383, U+038B, U+038D, U+03A2,
+\&                             U+0530 ...)
+\&   \ep{Line_Break: WJ}      \ep{Line_Break=Word_Joiner} (2)
+\&   \ep{Line_Break: Word_Joiner} (Short: \ep{Lb=WJ}) (2: U+2060, U+FEFF)
+\&   \ep{Line_Break: XX}      \ep{Line_Break=Unknown} (900_198 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Line_Break: ZW}      \ep{Line_Break=ZWSpace} (1)
+\&   \ep{Line_Break: ZWJ}     (Short: \ep{Lb=ZWJ}) (1: U+200D)
+\&   \ep{Line_Break: ZWSpace} (Short: \ep{Lb=ZW}) (1: U+200B)
+\&   \ep{Line_Separator}      \ep{General_Category=Line_Separator}
+\&                             (Short: \ep{Zl}) (1)
+\&   \ep{Linear_A}            \ep{Script_Extensions=Linear_A} (Short:
+\&                             \ep{Lina}; NOT \ep{Block=Linear_A}) (386)
+\&   \ep{Linear_B}            \ep{Script_Extensions=Linear_B} (Short:
+\&                             \ep{Linb}) (268)
+\& X \ep{Linear_B_Ideograms}  \ep{Block=Linear_B_Ideograms} (128)
+\& X \ep{Linear_B_Syllabary}  \ep{Block=Linear_B_Syllabary} (128)
+\&   \ep{Lisu}                \ep{Script_Extensions=Lisu} (NOT \ep{Block=
+\&                             Lisu}) (49)
+\& X \ep{Lisu_Sup}            \ep{Lisu_Supplement} (= \ep{Block=
+\&                             Lisu_Supplement}) (16)
+\& X \ep{Lisu_Supplement}     \ep{Block=Lisu_Supplement} (Short:
+\&                             \ep{InLisuSup}) (16)
+\&   \ep{Ll}                  \ep{Lowercase_Letter} (=
+\&                             \ep{General_Category=Lowercase_Letter})
+\&                             (/i= General_Category=Cased_Letter)
+\&                             (2233)
+\&   \ep{Lm}                  \ep{Modifier_Letter} (=
+\&                             \ep{General_Category=Modifier_Letter})
+\&                             (397)
+\&   \ep{Lo}                  \ep{Other_Letter} (= \ep{General_Category=
+\&                             Other_Letter}) (131_612)
+\&   \ep{LOE}                 \ep{Logical_Order_Exception} (=
+\&                             \ep{Logical_Order_Exception=Y}) (19)
+\&   \ep{LOE: *}              \ep{Logical_Order_Exception: *}
+\&   \ep{Logical_Order_Exception} \ep{Logical_Order_Exception=Y} (Short:
+\&                             \ep{LOE}) (19)
+\&   \ep{Logical_Order_Exception: N*} (Short: \ep{LOE=N}, \eP{LOE})
+\&                             (1_114_093 plus all above\-Unicode code
+\&                             points: U+0000..0E3F, U+0E45..0EBF,
+\&                             U+0EC5..19B4, U+19B8..19B9,
+\&                             U+19BB..AAB4, U+AAB7..AAB8 ...)
+\&   \ep{Logical_Order_Exception: Y*} (Short: \ep{LOE=Y}, \ep{LOE}) (19:
+\&                             U+0E40..0E44, U+0EC0..0EC4,
+\&                             U+19B5..19B7, U+19BA, U+AAB5..AAB6,
+\&                             U+AAB9 ...)
+\& X \ep{Low_Surrogates}      \ep{Block=Low_Surrogates} (1024)
+\&   \ep{Lower}               \ep{XPosixLower} (= \ep{Lowercase=Y}) (/i=
+\&                             Cased=Yes) (2544)
+\&   \ep{Lower: *}            \ep{Lowercase: *}
+\&   \ep{Lowercase}           \ep{XPosixLower} (= \ep{Lowercase=Y}) (/i=
+\&                             Cased=Yes) (2544)
+\&   \ep{Lowercase: N*}       (Short: \ep{Lower=N}, \eP{Lower}; /i= Cased=
+\&                             No) (1_111_568 plus all above\-Unicode
+\&                             code points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq
+\&                             \e(\e)*+,\e\-.\e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`\e{
+\&                             \e|\e}~\ex7f\-\exa9\exab\-\exb4\exb6\-\exb9\exbb\-
+\&                             \exde\exf7], U+0100, U+0102, U+0104,
+\&                             U+0106, U+0108 ...)
+\&   \ep{Lowercase: Y*}       (Short: \ep{Lower=Y}, \ep{Lower}; /i= Cased=
+\&                             Yes) (2544: [a\-z\exaa\exb5\exba\exdf\-\exf6
+\&                             \exf8\-\exff], U+0101, U+0103, U+0105,
+\&                             U+0107, U+0109 ...)
+\&   \ep{Lowercase_Letter}    \ep{General_Category=Lowercase_Letter}
+\&                             (Short: \ep{Ll}; /i= General_Category=
+\&                             Cased_Letter) (2233)
+\&   \ep{Lt}                  \ep{Titlecase_Letter} (=
+\&                             \ep{General_Category=Titlecase_Letter})
+\&                             (/i= General_Category=Cased_Letter) (31)
+\&   \ep{Lu}                  \ep{Uppercase_Letter} (=
+\&                             \ep{General_Category=Uppercase_Letter})
+\&                             (/i= General_Category=Cased_Letter)
+\&                             (1831)
+\&   \ep{Lyci}                \ep{Lycian} (= \ep{Script_Extensions=
+\&                             Lycian}) (NOT \ep{Block=Lycian}) (29)
+\&   \ep{Lycian}              \ep{Script_Extensions=Lycian} (Short:
+\&                             \ep{Lyci}; NOT \ep{Block=Lycian}) (29)
+\&   \ep{Lydi}                \ep{Lydian} (= \ep{Script_Extensions=
+\&                             Lydian}) (NOT \ep{Block=Lydian}) (27)
+\&   \ep{Lydian}              \ep{Script_Extensions=Lydian} (Short:
+\&                             \ep{Lydi}; NOT \ep{Block=Lydian}) (27)
+\&   \ep{M} \epM               \ep{Mark} (= \ep{General_Category=Mark})
+\&                             (2450)
+\&   \ep{Mahajani}            \ep{Script_Extensions=Mahajani} (Short:
+\&                             \ep{Mahj}; NOT \ep{Block=Mahajani}) (61)
+\&   \ep{Mahj}                \ep{Mahajani} (= \ep{Script_Extensions=
+\&                             Mahajani}) (NOT \ep{Block=Mahajani}) (61)
+\& X \ep{Mahjong}             \ep{Mahjong_Tiles} (= \ep{Block=
+\&                             Mahjong_Tiles}) (48)
+\& X \ep{Mahjong_Tiles}       \ep{Block=Mahjong_Tiles} (Short:
+\&                             \ep{InMahjong}) (48)
+\&   \ep{Maka}                \ep{Makasar} (= \ep{Script_Extensions=
+\&                             Makasar}) (NOT \ep{Block=Makasar}) (25)
+\&   \ep{Makasar}             \ep{Script_Extensions=Makasar} (Short:
+\&                             \ep{Maka}; NOT \ep{Block=Makasar}) (25)
+\&   \ep{Malayalam}           \ep{Script_Extensions=Malayalam} (Short:
+\&                             \ep{Mlym}; NOT \ep{Block=Malayalam}) (126)
+\&   \ep{Mand}                \ep{Mandaic} (= \ep{Script_Extensions=
+\&                             Mandaic}) (NOT \ep{Block=Mandaic}) (30)
+\&   \ep{Mandaic}             \ep{Script_Extensions=Mandaic} (Short:
+\&                             \ep{Mand}; NOT \ep{Block=Mandaic}) (30)
+\&   \ep{Mani}                \ep{Manichaean} (= \ep{Script_Extensions=
+\&                             Manichaean}) (NOT \ep{Block=Manichaean})
+\&                             (52)
+\&   \ep{Manichaean}          \ep{Script_Extensions=Manichaean} (Short:
+\&                             \ep{Mani}; NOT \ep{Block=Manichaean}) (52)
+\&   \ep{Marc}                \ep{Marchen} (= \ep{Script_Extensions=
+\&                             Marchen}) (NOT \ep{Block=Marchen}) (68)
+\&   \ep{Marchen}             \ep{Script_Extensions=Marchen} (Short:
+\&                             \ep{Marc}; NOT \ep{Block=Marchen}) (68)
+\&   \ep{Mark}                \ep{General_Category=Mark} (Short: \ep{M})
+\&                             (2450)
+\&   \ep{Masaram_Gondi}       \ep{Script_Extensions=Masaram_Gondi}
+\&                             (Short: \ep{Gonm}; NOT \ep{Block=
+\&                             Masaram_Gondi}) (77)
+\&   \ep{Math}                \ep{Math=Y} (2310)
+\&   \ep{Math: N*}            (Single: \eP{Math}) (1_111_802 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*,\e\-.\e/0\-9:;?\e@A\-Z
+\&                             \e[\e\e\e]_\`a\-z\e{\e}\ex7f\-\exab\exad\-\exb0\exb2\-
+\&                             \exd6\exd8\-\exf6\exf8\-\exff], U+0100..03CF,
+\&                             U+03D3..03D4, U+03D6..03EF,
+\&                             U+03F2..03F3, U+03F7..0605 ...)
+\&   \ep{Math: Y*}            (Single: \ep{Math}) (2310: [+<=>\e^\e|~\exac
+\&                             \exb1\exd7\exf7], U+03D0..03D2, U+03D5,
+\&                             U+03F0..03F1, U+03F4..03F6, U+0606..0608
+\&                             ...)
+\& X \ep{Math_Alphanum}       \ep{Mathematical_Alphanumeric_Symbols} (=
+\&                             \ep{Block=
+\&                             Mathematical_Alphanumeric_Symbols})
+\&                             (1024)
+\& X \ep{Math_Operators}      \ep{Mathematical_Operators} (= \ep{Block=
+\&                             Mathematical_Operators}) (256)
+\&   \ep{Math_Symbol}         \ep{General_Category=Math_Symbol} (Short:
+\&                             \ep{Sm}) (948)
+\& X \ep{Mathematical_Alphanumeric_Symbols} \ep{Block=
+\&                             Mathematical_Alphanumeric_Symbols}
+\&                             (Short: \ep{InMathAlphanum}) (1024)
+\& X \ep{Mathematical_Operators} \ep{Block=Mathematical_Operators}
+\&                             (Short: \ep{InMathOperators}) (256)
+\& X \ep{Mayan_Numerals}      \ep{Block=Mayan_Numerals} (32)
+\&   \ep{Mc}                  \ep{Spacing_Mark} (= \ep{General_Category=
+\&                             Spacing_Mark}) (452)
+\&   \ep{Me}                  \ep{Enclosing_Mark} (= \ep{General_Category=
+\&                             Enclosing_Mark}) (13)
+\&   \ep{Medefaidrin}         \ep{Script_Extensions=Medefaidrin} (Short:
+\&                             \ep{Medf}; NOT \ep{Block=Medefaidrin}) (91)
+\&   \ep{Medf}                \ep{Medefaidrin} (= \ep{Script_Extensions=
+\&                             Medefaidrin}) (NOT \ep{Block=
+\&                             Medefaidrin}) (91)
+\&   \ep{Meetei_Mayek}        \ep{Script_Extensions=Meetei_Mayek} (Short:
+\&                             \ep{Mtei}; NOT \ep{Block=Meetei_Mayek})
+\&                             (79)
+\& X \ep{Meetei_Mayek_Ext}    \ep{Meetei_Mayek_Extensions} (= \ep{Block=
+\&                             Meetei_Mayek_Extensions}) (32)
+\& X \ep{Meetei_Mayek_Extensions} \ep{Block=Meetei_Mayek_Extensions}
+\&                             (Short: \ep{InMeeteiMayekExt}) (32)
+\&   \ep{Mend}                \ep{Mende_Kikakui} (= \ep{Script_Extensions=
+\&                             Mende_Kikakui}) (NOT \ep{Block=
+\&                             Mende_Kikakui}) (213)
+\&   \ep{Mende_Kikakui}       \ep{Script_Extensions=Mende_Kikakui}
+\&                             (Short: \ep{Mend}; NOT \ep{Block=
+\&                             Mende_Kikakui}) (213)
+\&   \ep{Merc}                \ep{Meroitic_Cursive} (=
+\&                             \ep{Script_Extensions=Meroitic_Cursive})
+\&                             (NOT \ep{Block=Meroitic_Cursive}) (90)
+\&   \ep{Mero}                \ep{Meroitic_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Meroitic_Hieroglyphs}) (32)
+\&   \ep{Meroitic_Cursive}    \ep{Script_Extensions=Meroitic_Cursive}
+\&                             (Short: \ep{Merc}; NOT \ep{Block=
+\&                             Meroitic_Cursive}) (90)
+\&   \ep{Meroitic_Hieroglyphs} \ep{Script_Extensions=
+\&                             Meroitic_Hieroglyphs} (Short: \ep{Mero})
+\&                             (32)
+\&   \ep{Miao}                \ep{Script_Extensions=Miao} (NOT \ep{Block=
+\&                             Miao}) (149)
+\& X \ep{Misc_Arrows}         \ep{Miscellaneous_Symbols_And_Arrows} (=
+\&                             \ep{Block=
+\&                             Miscellaneous_Symbols_And_Arrows}) (256)
+\& X \ep{Misc_Math_Symbols_A} \ep{Miscellaneous_Mathematical_Symbols_A}
+\&                             (= \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_A})
+\&                             (48)
+\& X \ep{Misc_Math_Symbols_B} \ep{Miscellaneous_Mathematical_Symbols_B}
+\&                             (= \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_B})
+\&                             (128)
+\& X \ep{Misc_Pictographs}    \ep{Miscellaneous_Symbols_And_Pictographs}
+\&                             (= \ep{Block=
+\&                             Miscellaneous_Symbols_And_Pictographs})
+\&                             (768)
+\& X \ep{Misc_Symbols}        \ep{Miscellaneous_Symbols} (= \ep{Block=
+\&                             Miscellaneous_Symbols}) (256)
+\& X \ep{Misc_Technical}      \ep{Miscellaneous_Technical} (= \ep{Block=
+\&                             Miscellaneous_Technical}) (256)
+\& X \ep{Miscellaneous_Mathematical_Symbols_A} \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_A}
+\&                             (Short: \ep{InMiscMathSymbolsA}) (48)
+\& X \ep{Miscellaneous_Mathematical_Symbols_B} \ep{Block=
+\&                             Miscellaneous_Mathematical_Symbols_B}
+\&                             (Short: \ep{InMiscMathSymbolsB}) (128)
+\& X \ep{Miscellaneous_Symbols} \ep{Block=Miscellaneous_Symbols} (Short:
+\&                             \ep{InMiscSymbols}) (256)
+\& X \ep{Miscellaneous_Symbols_And_Arrows} \ep{Block=
+\&                             Miscellaneous_Symbols_And_Arrows}
+\&                             (Short: \ep{InMiscArrows}) (256)
+\& X \ep{Miscellaneous_Symbols_And_Pictographs} \ep{Block=
+\&                             Miscellaneous_Symbols_And_Pictographs}
+\&                             (Short: \ep{InMiscPictographs}) (768)
+\& X \ep{Miscellaneous_Technical} \ep{Block=Miscellaneous_Technical}
+\&                             (Short: \ep{InMiscTechnical}) (256)
+\&   \ep{Mlym}                \ep{Malayalam} (= \ep{Script_Extensions=
+\&                             Malayalam}) (NOT \ep{Block=Malayalam})
+\&                             (126)
+\&   \ep{Mn}                  \ep{Nonspacing_Mark} (=
+\&                             \ep{General_Category=Nonspacing_Mark})
+\&                             (1985)
+\&   \ep{Modi}                \ep{Script_Extensions=Modi} (NOT \ep{Block=
+\&                             Modi}) (89)
+\&   \ep{Modifier_Letter}     \ep{General_Category=Modifier_Letter}
+\&                             (Short: \ep{Lm}) (397)
+\& X \ep{Modifier_Letters}    \ep{Spacing_Modifier_Letters} (= \ep{Block=
+\&                             Spacing_Modifier_Letters}) (80)
+\&   \ep{Modifier_Symbol}     \ep{General_Category=Modifier_Symbol}
+\&                             (Short: \ep{Sk}) (125)
+\& X \ep{Modifier_Tone_Letters} \ep{Block=Modifier_Tone_Letters} (32)
+\&   \ep{Mong}                \ep{Mongolian} (= \ep{Script_Extensions=
+\&                             Mongolian}) (NOT \ep{Block=Mongolian})
+\&                             (172)
+\&   \ep{Mongolian}           \ep{Script_Extensions=Mongolian} (Short:
+\&                             \ep{Mong}; NOT \ep{Block=Mongolian}) (172)
+\& X \ep{Mongolian_Sup}       \ep{Mongolian_Supplement} (= \ep{Block=
+\&                             Mongolian_Supplement}) (32)
+\& X \ep{Mongolian_Supplement} \ep{Block=Mongolian_Supplement} (Short:
+\&                             \ep{InMongolianSup}) (32)
+\&   \ep{Mro}                 \ep{Script_Extensions=Mro} (NOT \ep{Block=
+\&                             Mro}) (43)
+\&   \ep{Mroo}                \ep{Mro} (= \ep{Script_Extensions=Mro}) (NOT
+\&                             \ep{Block=Mro}) (43)
+\&   \ep{Mtei}                \ep{Meetei_Mayek} (= \ep{Script_Extensions=
+\&                             Meetei_Mayek}) (NOT \ep{Block=
+\&                             Meetei_Mayek}) (79)
+\&   \ep{Mult}                \ep{Multani} (= \ep{Script_Extensions=
+\&                             Multani}) (NOT \ep{Block=Multani}) (48)
+\&   \ep{Multani}             \ep{Script_Extensions=Multani} (Short:
+\&                             \ep{Mult}; NOT \ep{Block=Multani}) (48)
+\& X \ep{Music}               \ep{Musical_Symbols} (= \ep{Block=
+\&                             Musical_Symbols}) (256)
+\& X \ep{Musical_Symbols}     \ep{Block=Musical_Symbols} (Short:
+\&                             \ep{InMusic}) (256)
+\&   \ep{Myanmar}             \ep{Script_Extensions=Myanmar} (Short:
+\&                             \ep{Mymr}; NOT \ep{Block=Myanmar}) (224)
+\& X \ep{Myanmar_Ext_A}       \ep{Myanmar_Extended_A} (= \ep{Block=
+\&                             Myanmar_Extended_A}) (32)
+\& X \ep{Myanmar_Ext_B}       \ep{Myanmar_Extended_B} (= \ep{Block=
+\&                             Myanmar_Extended_B}) (32)
+\& X \ep{Myanmar_Extended_A}  \ep{Block=Myanmar_Extended_A} (Short:
+\&                             \ep{InMyanmarExtA}) (32)
+\& X \ep{Myanmar_Extended_B}  \ep{Block=Myanmar_Extended_B} (Short:
+\&                             \ep{InMyanmarExtB}) (32)
+\&   \ep{Mymr}                \ep{Myanmar} (= \ep{Script_Extensions=
+\&                             Myanmar}) (NOT \ep{Block=Myanmar}) (224)
+\&   \ep{N} \epN               \ep{Number} (= \ep{General_Category=Number})
+\&                             (1831)
+\&   \ep{Na=*}                \ep{Name=*}
+\&   \ep{Nabataean}           \ep{Script_Extensions=Nabataean} (Short:
+\&                             \ep{Nbat}; NOT \ep{Block=Nabataean}) (40)
+\&   \ep{Nag_Mundari}         \ep{Script_Extensions=Nag_Mundari} (Short:
+\&                             \ep{Nagm}; NOT \ep{Block=Nag_Mundari}) (42)
+\&   \ep{Nagm}                \ep{Nag_Mundari} (= \ep{Script_Extensions=
+\&                             Nag_Mundari}) (NOT \ep{Block=
+\&                             Nag_Mundari}) (42)
+\&   \ep{Name=*}              Combination of Name and Name_Alias
+\&                             properties; has special loose matching
+\&                             rules, for which see Unicode UAX #44
+\&   \ep{Nand}                \ep{Nandinagari} (= \ep{Script_Extensions=
+\&                             Nandinagari}) (NOT \ep{Block=
+\&                             Nandinagari}) (86)
+\&   \ep{Nandinagari}         \ep{Script_Extensions=Nandinagari} (Short:
+\&                             \ep{Nand}; NOT \ep{Block=Nandinagari}) (86)
+\&   \ep{Narb}                \ep{Old_North_Arabian} (=
+\&                             \ep{Script_Extensions=Old_North_Arabian})
+\&                             (32)
+\& X \ep{NB}                  \ep{No_Block} (= \ep{Block=No_Block})
+\&                             (820_944 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Nbat}                \ep{Nabataean} (= \ep{Script_Extensions=
+\&                             Nabataean}) (NOT \ep{Block=Nabataean})
+\&                             (40)
+\&   \ep{NChar}               \ep{Noncharacter_Code_Point} (=
+\&                             \ep{Noncharacter_Code_Point=Y}) (66)
+\&   \ep{NChar: *}            \ep{Noncharacter_Code_Point: *}
+\&   \ep{Nd}                  \ep{XPosixDigit} (= \ep{General_Category=
+\&                             Decimal_Number}) (680)
+\&   \ep{New_Tai_Lue}         \ep{Script_Extensions=New_Tai_Lue} (Short:
+\&                             \ep{Talu}; NOT \ep{Block=New_Tai_Lue}) (83)
+\&   \ep{Newa}                \ep{Script_Extensions=Newa} (NOT \ep{Block=
+\&                             Newa}) (97)
+\&   \ep{NFC_QC: *}           \ep{NFC_Quick_Check: *}
+\&   \ep{NFC_Quick_Check: M}  \ep{NFC_Quick_Check=Maybe} (111)
+\&   \ep{NFC_Quick_Check: Maybe} (Short: \ep{NFCQC=M}) (111:
+\&                             U+0300..0304, U+0306..030C, U+030F,
+\&                             U+0311, U+0313..0314, U+031B ...)
+\&   \ep{NFC_Quick_Check: N}  \ep{NFC_Quick_Check=No} (NOT
+\&                             \eP{NFC_Quick_Check} NOR \eP{NFC_QC})
+\&                             (1120)
+\&   \ep{NFC_Quick_Check: No} (Short: \ep{NFCQC=N}; NOT
+\&                             \eP{NFC_Quick_Check} NOR \eP{NFC_QC})
+\&                             (1120: U+0340..0341, U+0343..0344,
+\&                             U+0374, U+037E, U+0387, U+0958..095F ...)
+\&   \ep{NFC_Quick_Check: Y}  \ep{NFC_Quick_Check=Yes} (NOT
+\&                             \ep{NFC_Quick_Check} NOR \ep{NFC_QC})
+\&                             (1_112_881 plus all above\-Unicode code
+\&                             points)
+\&   \ep{NFC_Quick_Check: Yes} (Short: \ep{NFCQC=Y}; NOT
+\&                             \ep{NFC_Quick_Check} NOR \ep{NFC_QC})
+\&                             (1_112_881 plus all above\-Unicode code
+\&                             points: U+0000..02FF, U+0305,
+\&                             U+030D..030E, U+0310, U+0312,
+\&                             U+0315..031A ...)
+\&   \ep{NFD_QC: *}           \ep{NFD_Quick_Check: *}
+\&   \ep{NFD_Quick_Check: N}  \ep{NFD_Quick_Check=No} (NOT
+\&                             \eP{NFD_Quick_Check} NOR \eP{NFD_QC})
+\&                             (13_233)
+\&   \ep{NFD_Quick_Check: No} (Short: \ep{NFDQC=N}; NOT
+\&                             \eP{NFD_Quick_Check} NOR \eP{NFD_QC})
+\&                             (13_233: [\exc0\-\exc5\exc7\-\excf\exd1\-\exd6
+\&                             \exd9\-\exdd\exe0\-\exe5\exe7\-\exef\exf1\-\exf6
+\&                             \exf9\-\exfd\exff], U+0100..010F,
+\&                             U+0112..0125, U+0128..0130,
+\&                             U+0134..0137, U+0139..013E ...)
+\&   \ep{NFD_Quick_Check: Y}  \ep{NFD_Quick_Check=Yes} (NOT
+\&                             \ep{NFD_Quick_Check} NOR \ep{NFD_QC})
+\&                             (1_100_879 plus all above\-Unicode code
+\&                             points)
+\&   \ep{NFD_Quick_Check: Yes} (Short: \ep{NFDQC=Y}; NOT
+\&                             \ep{NFD_Quick_Check} NOR \ep{NFD_QC})
+\&                             (1_100_879 plus all above\-Unicode code
+\&                             points: [\ex00\-\exbf\exc6\exd0\exd7\-\exd8\exde\-
+\&                             \exdf\exe6\exf0\exf7\-\exf8\exfe],
+\&                             U+0110..0111, U+0126..0127,
+\&                             U+0131..0133, U+0138, U+013F..0142 ...)
+\&   \ep{NFKC_QC: *}          \ep{NFKC_Quick_Check: *}
+\&   \ep{NFKC_Quick_Check: M} \ep{NFKC_Quick_Check=Maybe} (111)
+\&   \ep{NFKC_Quick_Check: Maybe} (Short: \ep{NFKCQC=M}) (111:
+\&                             U+0300..0304, U+0306..030C, U+030F,
+\&                             U+0311, U+0313..0314, U+031B ...)
+\&   \ep{NFKC_Quick_Check: N} \ep{NFKC_Quick_Check=No} (NOT
+\&                             \eP{NFKC_Quick_Check} NOR \eP{NFKC_QC})
+\&                             (4928)
+\&   \ep{NFKC_Quick_Check: No} (Short: \ep{NFKCQC=N}; NOT
+\&                             \eP{NFKC_Quick_Check} NOR \eP{NFKC_QC})
+\&                             (4928: [\exa0\exa8\exaa\exaf\exb2\-\exb5\exb8\-
+\&                             \exba\exbc\-\exbe], U+0132..0133,
+\&                             U+013F..0140, U+0149, U+017F,
+\&                             U+01C4..01CC ...)
+\&   \ep{NFKC_Quick_Check: Y} \ep{NFKC_Quick_Check=Yes} (NOT
+\&                             \ep{NFKC_Quick_Check} NOR \ep{NFKC_QC})
+\&                             (1_109_073 plus all above\-Unicode code
+\&                             points)
+\&   \ep{NFKC_Quick_Check: Yes} (Short: \ep{NFKCQC=Y}; NOT
+\&                             \ep{NFKC_Quick_Check} NOR \ep{NFKC_QC})
+\&                             (1_109_073 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex9f\exa1\-\exa7\exa9\exab\-
+\&                             \exae\exb0\-\exb1\exb6\-\exb7\exbb\exbf\-\exff],
+\&                             U+0100..0131, U+0134..013E,
+\&                             U+0141..0148, U+014A..017E, U+0180..01C3
+\&                             ...)
+\&   \ep{NFKD_QC: *}          \ep{NFKD_Quick_Check: *}
+\&   \ep{NFKD_Quick_Check: N} \ep{NFKD_Quick_Check=No} (NOT
+\&                             \eP{NFKD_Quick_Check} NOR \eP{NFKD_QC})
+\&                             (17_029)
+\&   \ep{NFKD_Quick_Check: No} (Short: \ep{NFKDQC=N}; NOT
+\&                             \eP{NFKD_Quick_Check} NOR \eP{NFKD_QC})
+\&                             (17_029: [\exa0\exa8\exaa\exaf\exb2\-\exb5\exb8\-
+\&                             \exba\exbc\-\exbe\exc0\-\exc5\exc7\-\excf\exd1\-
+\&                             \exd6\exd9\-\exdd\exe0\-\exe5\exe7\-\exef\exf1\-
+\&                             \exf6\exf9\-\exfd\exff], U+0100..010F,
+\&                             U+0112..0125, U+0128..0130,
+\&                             U+0132..0137, U+0139..0140 ...)
+\&   \ep{NFKD_Quick_Check: Y} \ep{NFKD_Quick_Check=Yes} (NOT
+\&                             \ep{NFKD_Quick_Check} NOR \ep{NFKD_QC})
+\&                             (1_097_083 plus all above\-Unicode code
+\&                             points)
+\&   \ep{NFKD_Quick_Check: Yes} (Short: \ep{NFKDQC=Y}; NOT
+\&                             \ep{NFKD_Quick_Check} NOR \ep{NFKD_QC})
+\&                             (1_097_083 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex9f\exa1\-\exa7\exa9\exab\-
+\&                             \exae\exb0\-\exb1\exb6\-\exb7\exbb\exbf\exc6\exd0
+\&                             \exd7\-\exd8\exde\-\exdf\exe6\exf0\exf7\-\exf8
+\&                             \exfe], U+0110..0111, U+0126..0127,
+\&                             U+0131, U+0138, U+0141..0142 ...)
+\&   \ep{Nko}                 \ep{Script_Extensions=Nko} (NOT \ep{Block=
+\&                             NKo}) (67)
+\&   \ep{Nkoo}                \ep{Nko} (= \ep{Script_Extensions=Nko}) (NOT
+\&                             \ep{Block=NKo}) (67)
+\&   \ep{Nl}                  \ep{Letter_Number} (= \ep{General_Category=
+\&                             Letter_Number}) (236)
+\&   \ep{No}                  \ep{Other_Number} (= \ep{General_Category=
+\&                             Other_Number}) (915)
+\& X \ep{No_Block}            \ep{Block=No_Block} (Short: \ep{InNB})
+\&                             (820_944 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Noncharacter_Code_Point} \ep{Noncharacter_Code_Point=Y} (Short:
+\&                             \ep{NChar}) (66)
+\&   \ep{Noncharacter_Code_Point: N*} (Short: \ep{NChar=N}, \eP{NChar})
+\&                             (1_114_046 plus all above\-Unicode code
+\&                             points: U+0000..FDCF, U+FDF0..FFFD,
+\&                             U+10000..1FFFD, U+20000..2FFFD,
+\&                             U+30000..3FFFD, U+40000..4FFFD ...)
+\&   \ep{Noncharacter_Code_Point: Y*} (Short: \ep{NChar=Y}, \ep{NChar})
+\&                             (66: U+FDD0..FDEF, U+FFFE..FFFF,
+\&                             U+1FFFE..1FFFF, U+2FFFE..2FFFF,
+\&                             U+3FFFE..3FFFF, U+4FFFE..4FFFF ...)
+\&   \ep{Nonspacing_Mark}     \ep{General_Category=Nonspacing_Mark}
+\&                             (Short: \ep{Mn}) (1985)
+\&   \ep{Nshu}                \ep{Nushu} (= \ep{Script_Extensions=Nushu})
+\&                             (NOT \ep{Block=Nushu}) (397)
+\&   \ep{Nt: *}               \ep{Numeric_Type: *}
+\&   \ep{Number}              \ep{General_Category=Number} (Short: \ep{N})
+\&                             (1831)
+\& X \ep{Number_Forms}        \ep{Block=Number_Forms} (64)
+\&   \ep{Numeric_Type: De}    \ep{Numeric_Type=Decimal} (680)
+\&   \ep{Numeric_Type: Decimal} (Short: \ep{Nt=De}) (680: [0\-9],
+\&                             U+0660..0669, U+06F0..06F9,
+\&                             U+07C0..07C9, U+0966..096F, U+09E6..09EF
+\&                             ...)
+\&   \ep{Numeric_Type: Di}    \ep{Numeric_Type=Digit} (128)
+\&   \ep{Numeric_Type: Digit} (Short: \ep{Nt=Di}) (128: [\exb2\-\exb3\exb9],
+\&                             U+1369..1371, U+19DA, U+2070,
+\&                             U+2074..2079, U+2080..2089 ...)
+\&   \ep{Numeric_Type: None}  (Short: \ep{Nt=None}) (1_112_200 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@A\-Z\e[\e\e\e]
+\&                             \e^_\`a\-z\e{\e|\e}~\ex7f\-\exb1\exb4\-\exb8\exba\-
+\&                             \exbb\exbf\-\exff], U+0100..065F,
+\&                             U+066A..06EF, U+06FA..07BF,
+\&                             U+07CA..0965, U+0970..09E5 ...)
+\&   \ep{Numeric_Type: Nu}    \ep{Numeric_Type=Numeric} (1104)
+\&   \ep{Numeric_Type: Numeric} (Short: \ep{Nt=Nu}) (1104: [\exbc\-\exbe],
+\&                             U+09F4..09F9, U+0B72..0B77,
+\&                             U+0BF0..0BF2, U+0C78..0C7E, U+0D58..0D5E
+\&                             ...)
+\& T \ep{Numeric_Value: \-1/2} (Short: \ep{Nv=\-1/2}) (1: U+0F33)
+\& T \ep{Numeric_Value: 0}    (Short: \ep{Nv=0}) (87: [0], U+0660,
+\&                             U+06F0, U+07C0, U+0966, U+09E6 ...)
+\& T \ep{Numeric_Value: 1/320} (Short: \ep{Nv=1/320}) (2: U+11FC0,
+\&                             U+11FD4)
+\& T \ep{Numeric_Value: 1/160} (Short: \ep{Nv=1/160}) (2: U+0D58, U+11FC1)
+\& T \ep{Numeric_Value: 1/80} (Short: \ep{Nv=1/80}) (1: U+11FC2)
+\& T \ep{Numeric_Value: 1/64} (Short: \ep{Nv=1/64}) (1: U+11FC3)
+\& T \ep{Numeric_Value: 1/40} (Short: \ep{Nv=1/40}) (2: U+0D59, U+11FC4)
+\& T \ep{Numeric_Value: 1/32} (Short: \ep{Nv=1/32}) (1: U+11FC5)
+\& T \ep{Numeric_Value: 3/80} (Short: \ep{Nv=3/80}) (2: U+0D5A, U+11FC6)
+\& T \ep{Numeric_Value: 3/64} (Short: \ep{Nv=3/64}) (1: U+11FC7)
+\& T \ep{Numeric_Value: 1/20} (Short: \ep{Nv=1/20}) (2: U+0D5B, U+11FC8)
+\& T \ep{Numeric_Value: 1/16} (Short: \ep{Nv=1/16}) (6: U+09F4, U+0B75,
+\&                             U+0D76, U+A833, U+11FC9..11FCA)
+\& T \ep{Numeric_Value: 1/12} (Short: \ep{Nv=1/12}) (1: U+109F6)
+\& T \ep{Numeric_Value: 1/10} (Short: \ep{Nv=1/10}) (3: U+0D5C, U+2152,
+\&                             U+11FCB)
+\& T \ep{Numeric_Value: 1/9}  (Short: \ep{Nv=1/9}) (1: U+2151)
+\& T \ep{Numeric_Value: 1/8}  (Short: \ep{Nv=1/8}) (7: U+09F5, U+0B76,
+\&                             U+0D77, U+215B, U+A834, U+11FCC ...)
+\& T \ep{Numeric_Value: 1/7}  (Short: \ep{Nv=1/7}) (1: U+2150)
+\& T \ep{Numeric_Value: 3/20} (Short: \ep{Nv=3/20}) (2: U+0D5D, U+11FCD)
+\& T \ep{Numeric_Value: 1/6}  (Short: \ep{Nv=1/6}) (4: U+2159, U+109F7,
+\&                             U+12461, U+1ED3D)
+\& T \ep{Numeric_Value: 3/16} (Short: \ep{Nv=3/16}) (5: U+09F6, U+0B77,
+\&                             U+0D78, U+A835, U+11FCE)
+\& T \ep{Numeric_Value: 1/5}  (Short: \ep{Nv=1/5}) (3: U+0D5E, U+2155,
+\&                             U+11FCF)
+\& T \ep{Numeric_Value: 1/4}  (Short: \ep{Nv=1/4}) (14: [\exbc], U+09F7,
+\&                             U+0B72, U+0D73, U+A830, U+10140 ...)
+\& T \ep{Numeric_Value: 1/3}  (Short: \ep{Nv=1/3}) (6: U+2153, U+109F9,
+\&                             U+10E7D, U+1245A, U+1245D, U+12465)
+\& T \ep{Numeric_Value: 3/8}  (Short: \ep{Nv=3/8}) (1: U+215C)
+\& T \ep{Numeric_Value: 2/5}  (Short: \ep{Nv=2/5}) (1: U+2156)
+\& T \ep{Numeric_Value: 5/12} (Short: \ep{Nv=5/12}) (1: U+109FA)
+\& T \ep{Numeric_Value: 1/2}  (Short: \ep{Nv=1/2}) (19: [\exbd], U+0B73,
+\&                             U+0D74, U+0F2A, U+2CFD, U+A831 ...)
+\& T \ep{Numeric_Value: 7/12} (Short: \ep{Nv=7/12}) (1: U+109FC)
+\& T \ep{Numeric_Value: 3/5}  (Short: \ep{Nv=3/5}) (1: U+2157)
+\& T \ep{Numeric_Value: 5/8}  (Short: \ep{Nv=5/8}) (1: U+215D)
+\& T \ep{Numeric_Value: 2/3}  (Short: \ep{Nv=2/3}) (7: U+2154, U+10177,
+\&                             U+109FD, U+10E7E, U+1245B, U+1245E ...)
+\& T \ep{Numeric_Value: 3/4}  (Short: \ep{Nv=3/4}) (9: [\exbe], U+09F8,
+\&                             U+0B74, U+0D75, U+A832, U+10178 ...)
+\& T \ep{Numeric_Value: 4/5}  (Short: \ep{Nv=4/5}) (1: U+2158)
+\& T \ep{Numeric_Value: 5/6}  (Short: \ep{Nv=5/6}) (3: U+215A, U+109FF,
+\&                             U+1245C)
+\& T \ep{Numeric_Value: 7/8}  (Short: \ep{Nv=7/8}) (1: U+215E)
+\& T \ep{Numeric_Value: 11/12} (Short: \ep{Nv=11/12}) (1: U+109BC)
+\& T \ep{Numeric_Value: 1}    (Short: \ep{Nv=1}) (144: [1\exb9], U+0661,
+\&                             U+06F1, U+07C1, U+0967, U+09E7 ...)
+\& T \ep{Numeric_Value: 3/2}  (Short: \ep{Nv=3/2}) (1: U+0F2B)
+\& T \ep{Numeric_Value: 2}    (Short: \ep{Nv=2}) (143: [2\exb2], U+0662,
+\&                             U+06F2, U+07C2, U+0968, U+09E8 ...)
+\& T \ep{Numeric_Value: 5/2}  (Short: \ep{Nv=5/2}) (1: U+0F2C)
+\& T \ep{Numeric_Value: 3}    (Short: \ep{Nv=3}) (144: [3\exb3], U+0663,
+\&                             U+06F3, U+07C3, U+0969, U+09E9 ...)
+\& T \ep{Numeric_Value: 7/2}  (Short: \ep{Nv=7/2}) (1: U+0F2D)
+\& T \ep{Numeric_Value: 4}    (Short: \ep{Nv=4}) (135: [4], U+0664,
+\&                             U+06F4, U+07C4, U+096A, U+09EA ...)
+\& T \ep{Numeric_Value: 9/2}  (Short: \ep{Nv=9/2}) (1: U+0F2E)
+\& T \ep{Numeric_Value: 5}    (Short: \ep{Nv=5}) (133: [5], U+0665,
+\&                             U+06F5, U+07C5, U+096B, U+09EB ...)
+\& T \ep{Numeric_Value: 11/2} (Short: \ep{Nv=11/2}) (1: U+0F2F)
+\& T \ep{Numeric_Value: 6}    (Short: \ep{Nv=6}) (117: [6], U+0666,
+\&                             U+06F6, U+07C6, U+096C, U+09EC ...)
+\& T \ep{Numeric_Value: 13/2} (Short: \ep{Nv=13/2}) (1: U+0F30)
+\& T \ep{Numeric_Value: 7}    (Short: \ep{Nv=7}) (116: [7], U+0667,
+\&                             U+06F7, U+07C7, U+096D, U+09ED ...)
+\& T \ep{Numeric_Value: 15/2} (Short: \ep{Nv=15/2}) (1: U+0F31)
+\& T \ep{Numeric_Value: 8}    (Short: \ep{Nv=8}) (112: [8], U+0668,
+\&                             U+06F8, U+07C8, U+096E, U+09EE ...)
+\& T \ep{Numeric_Value: 17/2} (Short: \ep{Nv=17/2}) (1: U+0F32)
+\& T \ep{Numeric_Value: 9}    (Short: \ep{Nv=9}) (116: [9], U+0669,
+\&                             U+06F9, U+07C9, U+096F, U+09EF ...)
+\& T \ep{Numeric_Value: 10}   (Short: \ep{Nv=10}) (63: U+0BF0, U+0D70,
+\&                             U+1372, U+2169, U+2179, U+2469 ...)
+\& T \ep{Numeric_Value: 11}   (Short: \ep{Nv=11}) (9: U+216A, U+217A,
+\&                             U+246A, U+247E, U+2492, U+24EB ...)
+\& T \ep{Numeric_Value: 12}   (Short: \ep{Nv=12}) (9: U+216B, U+217B,
+\&                             U+246B, U+247F, U+2493, U+24EC ...)
+\& T \ep{Numeric_Value: 13}   (Short: \ep{Nv=13}) (7: U+246C, U+2480,
+\&                             U+2494, U+24ED, U+16E8D, U+1D2CD ...)
+\& T \ep{Numeric_Value: 14}   (Short: \ep{Nv=14}) (7: U+246D, U+2481,
+\&                             U+2495, U+24EE, U+16E8E, U+1D2CE ...)
+\& T \ep{Numeric_Value: 15}   (Short: \ep{Nv=15}) (7: U+246E, U+2482,
+\&                             U+2496, U+24EF, U+16E8F, U+1D2CF ...)
+\& T \ep{Numeric_Value: 16}   (Short: \ep{Nv=16}) (8: U+09F9, U+246F,
+\&                             U+2483, U+2497, U+24F0, U+16E90 ...)
+\& T \ep{Numeric_Value: 17}   (Short: \ep{Nv=17}) (8: U+16EE, U+2470,
+\&                             U+2484, U+2498, U+24F1, U+16E91 ...)
+\& T \ep{Numeric_Value: 18}   (Short: \ep{Nv=18}) (8: U+16EF, U+2471,
+\&                             U+2485, U+2499, U+24F2, U+16E92 ...)
+\& T \ep{Numeric_Value: 19}   (Short: \ep{Nv=19}) (8: U+16F0, U+2472,
+\&                             U+2486, U+249A, U+24F3, U+16E93 ...)
+\& T \ep{Numeric_Value: 20}   (Short: \ep{Nv=20}) (36: U+1373, U+2473,
+\&                             U+2487, U+249B, U+24F4, U+3039 ...)
+\& T \ep{Numeric_Value: 21}   (Short: \ep{Nv=21}) (1: U+3251)
+\& T \ep{Numeric_Value: 22}   (Short: \ep{Nv=22}) (1: U+3252)
+\& T \ep{Numeric_Value: 23}   (Short: \ep{Nv=23}) (1: U+3253)
+\& T \ep{Numeric_Value: 24}   (Short: \ep{Nv=24}) (1: U+3254)
+\& T \ep{Numeric_Value: 25}   (Short: \ep{Nv=25}) (1: U+3255)
+\& T \ep{Numeric_Value: 26}   (Short: \ep{Nv=26}) (1: U+3256)
+\& T \ep{Numeric_Value: 27}   (Short: \ep{Nv=27}) (1: U+3257)
+\& T \ep{Numeric_Value: 28}   (Short: \ep{Nv=28}) (1: U+3258)
+\& T \ep{Numeric_Value: 29}   (Short: \ep{Nv=29}) (1: U+3259)
+\& T \ep{Numeric_Value: 30}   (Short: \ep{Nv=30}) (19: U+1374, U+303A,
+\&                             U+324A, U+325A, U+5345, U+10112 ...)
+\& T \ep{Numeric_Value: 31}   (Short: \ep{Nv=31}) (1: U+325B)
+\& T \ep{Numeric_Value: 32}   (Short: \ep{Nv=32}) (1: U+325C)
+\& T \ep{Numeric_Value: 33}   (Short: \ep{Nv=33}) (1: U+325D)
+\& T \ep{Numeric_Value: 34}   (Short: \ep{Nv=34}) (1: U+325E)
+\& T \ep{Numeric_Value: 35}   (Short: \ep{Nv=35}) (1: U+325F)
+\& T \ep{Numeric_Value: 36}   (Short: \ep{Nv=36}) (1: U+32B1)
+\& T \ep{Numeric_Value: 37}   (Short: \ep{Nv=37}) (1: U+32B2)
+\& T \ep{Numeric_Value: 38}   (Short: \ep{Nv=38}) (1: U+32B3)
+\& T \ep{Numeric_Value: 39}   (Short: \ep{Nv=39}) (1: U+32B4)
+\& T \ep{Numeric_Value: 40}   (Short: \ep{Nv=40}) (18: U+1375, U+324B,
+\&                             U+32B5, U+534C, U+10113, U+102ED ...)
+\& T \ep{Numeric_Value: 41}   (Short: \ep{Nv=41}) (1: U+32B6)
+\& T \ep{Numeric_Value: 42}   (Short: \ep{Nv=42}) (1: U+32B7)
+\& T \ep{Numeric_Value: 43}   (Short: \ep{Nv=43}) (1: U+32B8)
+\& T \ep{Numeric_Value: 44}   (Short: \ep{Nv=44}) (1: U+32B9)
+\& T \ep{Numeric_Value: 45}   (Short: \ep{Nv=45}) (1: U+32BA)
+\& T \ep{Numeric_Value: 46}   (Short: \ep{Nv=46}) (1: U+32BB)
+\& T \ep{Numeric_Value: 47}   (Short: \ep{Nv=47}) (1: U+32BC)
+\& T \ep{Numeric_Value: 48}   (Short: \ep{Nv=48}) (1: U+32BD)
+\& T \ep{Numeric_Value: 49}   (Short: \ep{Nv=49}) (1: U+32BE)
+\& T \ep{Numeric_Value: 50}   (Short: \ep{Nv=50}) (29: U+1376, U+216C,
+\&                             U+217C, U+2186, U+324C, U+32BF ...)
+\& T \ep{Numeric_Value: 60}   (Short: \ep{Nv=60}) (13: U+1377, U+324D,
+\&                             U+10115, U+102EF, U+109CE, U+10E6E ...)
+\& T \ep{Numeric_Value: 70}   (Short: \ep{Nv=70}) (13: U+1378, U+324E,
+\&                             U+10116, U+102F0, U+109CF, U+10E6F ...)
+\& T \ep{Numeric_Value: 80}   (Short: \ep{Nv=80}) (12: U+1379, U+324F,
+\&                             U+10117, U+102F1, U+10E70, U+11062 ...)
+\& T \ep{Numeric_Value: 90}   (Short: \ep{Nv=90}) (12: U+137A, U+10118,
+\&                             U+102F2, U+10341, U+10E71, U+11063 ...)
+\& T \ep{Numeric_Value: 100}  (Short: \ep{Nv=100}) (35: U+0BF1, U+0D71,
+\&                             U+137B, U+216D, U+217D, U+4F70 ...)
+\& T \ep{Numeric_Value: 200}  (Short: \ep{Nv=200}) (6: U+1011A, U+102F4,
+\&                             U+109D3, U+10E73, U+1EC84, U+1ED14)
+\& T \ep{Numeric_Value: 300}  (Short: \ep{Nv=300}) (7: U+1011B, U+1016B,
+\&                             U+102F5, U+109D4, U+10E74, U+1EC85 ...)
+\& T \ep{Numeric_Value: 400}  (Short: \ep{Nv=400}) (7: U+1011C, U+102F6,
+\&                             U+109D5, U+10E75, U+1EC86, U+1ED16 ...)
+\& T \ep{Numeric_Value: 500}  (Short: \ep{Nv=500}) (16: U+216E, U+217E,
+\&                             U+1011D, U+10145, U+1014C, U+10153 ...)
+\& T \ep{Numeric_Value: 600}  (Short: \ep{Nv=600}) (7: U+1011E, U+102F8,
+\&                             U+109D7, U+10E77, U+1EC88, U+1ED18 ...)
+\& T \ep{Numeric_Value: 700}  (Short: \ep{Nv=700}) (6: U+1011F, U+102F9,
+\&                             U+109D8, U+10E78, U+1EC89, U+1ED19)
+\& T \ep{Numeric_Value: 800}  (Short: \ep{Nv=800}) (6: U+10120, U+102FA,
+\&                             U+109D9, U+10E79, U+1EC8A, U+1ED1A)
+\& T \ep{Numeric_Value: 900}  (Short: \ep{Nv=900}) (7: U+10121, U+102FB,
+\&                             U+1034A, U+109DA, U+10E7A, U+1EC8B ...)
+\& T \ep{Numeric_Value: 1000} (Short: \ep{Nv=1000}) (22: U+0BF2, U+0D72,
+\&                             U+216F, U+217F..2180, U+4EDF, U+5343 ...)
+\& T \ep{Numeric_Value: 2000} (Short: \ep{Nv=2000}) (5: U+10123, U+109DC,
+\&                             U+1EC8D, U+1ED1D, U+1ED3A)
+\& T \ep{Numeric_Value: 3000} (Short: \ep{Nv=3000}) (4: U+10124, U+109DD,
+\&                             U+1EC8E, U+1ED1E)
+\& T \ep{Numeric_Value: 4000} (Short: \ep{Nv=4000}) (4: U+10125, U+109DE,
+\&                             U+1EC8F, U+1ED1F)
+\& T \ep{Numeric_Value: 5000} (Short: \ep{Nv=5000}) (8: U+2181, U+10126,
+\&                             U+10146, U+1014E, U+10172, U+109DF ...)
+\& T \ep{Numeric_Value: 6000} (Short: \ep{Nv=6000}) (4: U+10127, U+109E0,
+\&                             U+1EC91, U+1ED21)
+\& T \ep{Numeric_Value: 7000} (Short: \ep{Nv=7000}) (4: U+10128, U+109E1,
+\&                             U+1EC92, U+1ED22)
+\& T \ep{Numeric_Value: 8000} (Short: \ep{Nv=8000}) (4: U+10129, U+109E2,
+\&                             U+1EC93, U+1ED23)
+\& T \ep{Numeric_Value: 9000} (Short: \ep{Nv=9000}) (4: U+1012A, U+109E3,
+\&                             U+1EC94, U+1ED24)
+\& T \ep{Numeric_Value: 10000} (= 1.0e+04) (Short: \ep{Nv=10000}) (13:
+\&                             U+137C, U+2182, U+4E07, U+842C, U+1012B,
+\&                             U+10155 ...)
+\& T \ep{Numeric_Value: 20000} (= 2.0e+04) (Short: \ep{Nv=20000}) (4:
+\&                             U+1012C, U+109E5, U+1EC96, U+1ED26)
+\& T \ep{Numeric_Value: 30000} (= 3.0e+04) (Short: \ep{Nv=30000}) (4:
+\&                             U+1012D, U+109E6, U+1EC97, U+1ED27)
+\& T \ep{Numeric_Value: 40000} (= 4.0e+04) (Short: \ep{Nv=40000}) (4:
+\&                             U+1012E, U+109E7, U+1EC98, U+1ED28)
+\& T \ep{Numeric_Value: 50000} (= 5.0e+04) (Short: \ep{Nv=50000}) (7:
+\&                             U+2187, U+1012F, U+10147, U+10156,
+\&                             U+109E8, U+1EC99 ...)
+\& T \ep{Numeric_Value: 60000} (= 6.0e+04) (Short: \ep{Nv=60000}) (4:
+\&                             U+10130, U+109E9, U+1EC9A, U+1ED2A)
+\& T \ep{Numeric_Value: 70000} (= 7.0e+04) (Short: \ep{Nv=70000}) (4:
+\&                             U+10131, U+109EA, U+1EC9B, U+1ED2B)
+\& T \ep{Numeric_Value: 80000} (= 8.0e+04) (Short: \ep{Nv=80000}) (4:
+\&                             U+10132, U+109EB, U+1EC9C, U+1ED2C)
+\& T \ep{Numeric_Value: 90000} (= 9.0e+04) (Short: \ep{Nv=90000}) (4:
+\&                             U+10133, U+109EC, U+1EC9D, U+1ED2D)
+\& T \ep{Numeric_Value: 100000} (= 1.0e+05) (Short: \ep{Nv=100000}) (5:
+\&                             U+2188, U+109ED, U+1EC9E, U+1ECA0,
+\&                             U+1ECB4)
+\& T \ep{Numeric_Value: 200000} (= 2.0e+05) (Short: \ep{Nv=200000}) (2:
+\&                             U+109EE, U+1EC9F)
+\& T \ep{Numeric_Value: 216000} (= 2.2e+05) (Short: \ep{Nv=216000}) (1:
+\&                             U+12432)
+\& T \ep{Numeric_Value: 300000} (= 3.0e+05) (Short: \ep{Nv=300000}) (1:
+\&                             U+109EF)
+\& T \ep{Numeric_Value: 400000} (= 4.0e+05) (Short: \ep{Nv=400000}) (1:
+\&                             U+109F0)
+\& T \ep{Numeric_Value: 432000} (= 4.3e+05) (Short: \ep{Nv=432000}) (1:
+\&                             U+12433)
+\& T \ep{Numeric_Value: 500000} (= 5.0e+05) (Short: \ep{Nv=500000}) (1:
+\&                             U+109F1)
+\& T \ep{Numeric_Value: 600000} (= 6.0e+05) (Short: \ep{Nv=600000}) (1:
+\&                             U+109F2)
+\& T \ep{Numeric_Value: 700000} (= 7.0e+05) (Short: \ep{Nv=700000}) (1:
+\&                             U+109F3)
+\& T \ep{Numeric_Value: 800000} (= 8.0e+05) (Short: \ep{Nv=800000}) (1:
+\&                             U+109F4)
+\& T \ep{Numeric_Value: 900000} (= 9.0e+05) (Short: \ep{Nv=900000}) (1:
+\&                             U+109F5)
+\& T \ep{Numeric_Value: 1000000} (= 1.0e+06) (Short: \ep{Nv=1000000}) (1:
+\&                             U+16B5E)
+\& T \ep{Numeric_Value: 10000000} (= 1.0e+07) (Short: \ep{Nv=10000000})
+\&                             (1: U+1ECA1)
+\& T \ep{Numeric_Value: 20000000} (= 2.0e+07) (Short: \ep{Nv=20000000})
+\&                             (1: U+1ECA2)
+\& T \ep{Numeric_Value: 100000000} (= 1.0e+08) (Short: \ep{Nv=100000000})
+\&                             (3: U+4EBF, U+5104, U+16B5F)
+\& T \ep{Numeric_Value: 10000000000} (= 1.0e+10) (Short: \ep{Nv=
+\&                             10000000000}) (1: U+16B60)
+\& T \ep{Numeric_Value: 1000000000000} (= 1.0e+12) (Short: \ep{Nv=
+\&                             1000000000000}) (2: U+5146, U+16B61)
+\&   \ep{Numeric_Value: NaN}  (Short: \ep{Nv=NaN}) (1_112_200 plus all
+\&                             above\-Unicode code points: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@A\-Z\e[\e\e\e]
+\&                             \e^_\`a\-z\e{\e|\e}~\ex7f\-\exb1\exb4\-\exb8\exba\-
+\&                             \exbb\exbf\-\exff], U+0100..065F,
+\&                             U+066A..06EF, U+06FA..07BF,
+\&                             U+07CA..0965, U+0970..09E5 ...)
+\&   \ep{Nushu}               \ep{Script_Extensions=Nushu} (Short:
+\&                             \ep{Nshu}; NOT \ep{Block=Nushu}) (397)
+\&   \ep{Nv: *}               \ep{Numeric_Value: *}
+\&   \ep{Nyiakeng_Puachue_Hmong} \ep{Script_Extensions=
+\&                             Nyiakeng_Puachue_Hmong} (Short:
+\&                             \ep{Hmnp}; NOT \ep{Block=
+\&                             Nyiakeng_Puachue_Hmong}) (71)
+\& X \ep{OCR}                 \ep{Optical_Character_Recognition} (=
+\&                             \ep{Block=Optical_Character_Recognition})
+\&                             (32)
+\&   \ep{Ogam}                \ep{Ogham} (= \ep{Script_Extensions=Ogham})
+\&                             (NOT \ep{Block=Ogham}) (29)
+\&   \ep{Ogham}               \ep{Script_Extensions=Ogham} (Short:
+\&                             \ep{Ogam}; NOT \ep{Block=Ogham}) (29)
+\&   \ep{Ol_Chiki}            \ep{Script_Extensions=Ol_Chiki} (Short:
+\&                             \ep{Olck}) (48)
+\&   \ep{Olck}                \ep{Ol_Chiki} (= \ep{Script_Extensions=
+\&                             Ol_Chiki}) (48)
+\&   \ep{Old_Hungarian}       \ep{Script_Extensions=Old_Hungarian}
+\&                             (Short: \ep{Hung}; NOT \ep{Block=
+\&                             Old_Hungarian}) (108)
+\&   \ep{Old_Italic}          \ep{Script_Extensions=Old_Italic} (Short:
+\&                             \ep{Ital}; NOT \ep{Block=Old_Italic}) (39)
+\&   \ep{Old_North_Arabian}   \ep{Script_Extensions=Old_North_Arabian}
+\&                             (Short: \ep{Narb}) (32)
+\&   \ep{Old_Permic}          \ep{Script_Extensions=Old_Permic} (Short:
+\&                             \ep{Perm}; NOT \ep{Block=Old_Permic}) (44)
+\&   \ep{Old_Persian}         \ep{Script_Extensions=Old_Persian} (Short:
+\&                             \ep{Xpeo}; NOT \ep{Block=Old_Persian}) (50)
+\&   \ep{Old_Sogdian}         \ep{Script_Extensions=Old_Sogdian} (Short:
+\&                             \ep{Sogo}; NOT \ep{Block=Old_Sogdian}) (40)
+\&   \ep{Old_South_Arabian}   \ep{Script_Extensions=Old_South_Arabian}
+\&                             (Short: \ep{Sarb}) (32)
+\&   \ep{Old_Turkic}          \ep{Script_Extensions=Old_Turkic} (Short:
+\&                             \ep{Orkh}; NOT \ep{Block=Old_Turkic}) (73)
+\&   \ep{Old_Uyghur}          \ep{Script_Extensions=Old_Uyghur} (Short:
+\&                             \ep{Ougr}; NOT \ep{Block=Old_Uyghur}) (28)
+\&   \ep{Open_Punctuation}    \ep{General_Category=Open_Punctuation}
+\&                             (Short: \ep{Ps}) (79)
+\& X \ep{Optical_Character_Recognition} \ep{Block=
+\&                             Optical_Character_Recognition} (Short:
+\&                             \ep{InOCR}) (32)
+\&   \ep{Oriya}               \ep{Script_Extensions=Oriya} (Short:
+\&                             \ep{Orya}; NOT \ep{Block=Oriya}) (97)
+\&   \ep{Orkh}                \ep{Old_Turkic} (= \ep{Script_Extensions=
+\&                             Old_Turkic}) (NOT \ep{Block=Old_Turkic})
+\&                             (73)
+\& X \ep{Ornamental_Dingbats} \ep{Block=Ornamental_Dingbats} (48)
+\&   \ep{Orya}                \ep{Oriya} (= \ep{Script_Extensions=Oriya})
+\&                             (NOT \ep{Block=Oriya}) (97)
+\&   \ep{Osage}               \ep{Script_Extensions=Osage} (Short:
+\&                             \ep{Osge}; NOT \ep{Block=Osage}) (72)
+\&   \ep{Osge}                \ep{Osage} (= \ep{Script_Extensions=Osage})
+\&                             (NOT \ep{Block=Osage}) (72)
+\&   \ep{Osma}                \ep{Osmanya} (= \ep{Script_Extensions=
+\&                             Osmanya}) (NOT \ep{Block=Osmanya}) (40)
+\&   \ep{Osmanya}             \ep{Script_Extensions=Osmanya} (Short:
+\&                             \ep{Osma}; NOT \ep{Block=Osmanya}) (40)
+\&   \ep{Other}               \ep{General_Category=Other} (Short: \ep{C})
+\&                             (965_096 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Other_Letter}        \ep{General_Category=Other_Letter} (Short:
+\&                             \ep{Lo}) (131_612)
+\&   \ep{Other_Number}        \ep{General_Category=Other_Number} (Short:
+\&                             \ep{No}) (915)
+\&   \ep{Other_Punctuation}   \ep{General_Category=Other_Punctuation}
+\&                             (Short: \ep{Po}) (628)
+\&   \ep{Other_Symbol}        \ep{General_Category=Other_Symbol} (Short:
+\&                             \ep{So}) (6634)
+\& X \ep{Ottoman_Siyaq_Numbers} \ep{Block=Ottoman_Siyaq_Numbers} (80)
+\&   \ep{Ougr}                \ep{Old_Uyghur} (= \ep{Script_Extensions=
+\&                             Old_Uyghur}) (NOT \ep{Block=Old_Uyghur})
+\&                             (28)
+\&   \ep{P} \epP               \ep{Punct} (= \ep{General_Category=
+\&                             Punctuation}) (NOT
+\&                             \ep{General_Punctuation}) (842)
+\&   \ep{Pahawh_Hmong}        \ep{Script_Extensions=Pahawh_Hmong} (Short:
+\&                             \ep{Hmng}; NOT \ep{Block=Pahawh_Hmong})
+\&                             (127)
+\&   \ep{Palm}                \ep{Palmyrene} (= \ep{Script_Extensions=
+\&                             Palmyrene}) (32)
+\&   \ep{Palmyrene}           \ep{Script_Extensions=Palmyrene} (Short:
+\&                             \ep{Palm}) (32)
+\&   \ep{Paragraph_Separator} \ep{General_Category=Paragraph_Separator}
+\&                             (Short: \ep{Zp}) (1)
+\&   \ep{Pat_Syn}             \ep{Pattern_Syntax} (= \ep{Pattern_Syntax=
+\&                             Y}) (2760)
+\&   \ep{Pat_Syn: *}          \ep{Pattern_Syntax: *}
+\&   \ep{Pat_WS}              \ep{Pattern_White_Space} (=
+\&                             \ep{Pattern_White_Space=Y}) (11)
+\&   \ep{Pat_WS: *}           \ep{Pattern_White_Space: *}
+\&   \ep{Pattern_Syntax}      \ep{Pattern_Syntax=Y} (Short: \ep{PatSyn})
+\&                             (2760)
+\&   \ep{Pattern_Syntax: N*}  (Short: \ep{PatSyn=N}, \eP{PatSyn})
+\&                             (1_111_352 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex200\-9A\-Z_a\-z\ex7f\-\exa0
+\&                             \exa8\exaa\exad\exaf\exb2\-\exb5\exb7\-\exba\exbc\-
+\&                             \exbe\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..200F, U+2028..202F,
+\&                             U+203F..2040, U+2054, U+205F..218F ...)
+\&   \ep{Pattern_Syntax: Y*}  (Short: \ep{PatSyn=Y}, \ep{PatSyn}) (2760:
+\&                             [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@\e[\e\e\e]
+\&                             \e^\`\e{\e|\e}~\exa1\-\exa7\exa9\exab\-\exac\exae
+\&                             \exb0\-\exb1\exb6\exbb\exbf\exd7\exf7],
+\&                             U+2010..2027, U+2030..203E,
+\&                             U+2041..2053, U+2055..205E, U+2190..245F
+\&                             ...)
+\&   \ep{Pattern_White_Space} \ep{Pattern_White_Space=Y} (Short:
+\&                             \ep{PatWS}) (11)
+\&   \ep{Pattern_White_Space: N*} (Short: \ep{PatWS=N}, \eP{PatWS})
+\&                             (1_114_101 plus all above\-Unicode code
+\&                             points: [^\et\en\ecK\ef\er\ex20\ex85],
+\&                             U+0100..200D, U+2010..2027,
+\&                             U+202A..infinity)
+\&   \ep{Pattern_White_Space: Y*} (Short: \ep{PatWS=Y}, \ep{PatWS}) (11:
+\&                             [\et\en\ecK\ef\er\ex20\ex85], U+200E..200F,
+\&                             U+2028..2029)
+\&   \ep{Pau_Cin_Hau}         \ep{Script_Extensions=Pau_Cin_Hau} (Short:
+\&                             \ep{Pauc}; NOT \ep{Block=Pau_Cin_Hau}) (57)
+\&   \ep{Pauc}                \ep{Pau_Cin_Hau} (= \ep{Script_Extensions=
+\&                             Pau_Cin_Hau}) (NOT \ep{Block=
+\&                             Pau_Cin_Hau}) (57)
+\&   \ep{Pc}                  \ep{Connector_Punctuation} (=
+\&                             \ep{General_Category=
+\&                             Connector_Punctuation}) (10)
+\&   \ep{PCM}                 \ep{Prepended_Concatenation_Mark} (=
+\&                             \ep{Prepended_Concatenation_Mark=Y}) (13)
+\&   \ep{PCM: *}              \ep{Prepended_Concatenation_Mark: *}
+\&   \ep{Pd}                  \ep{Dash_Punctuation} (=
+\&                             \ep{General_Category=Dash_Punctuation})
+\&                             (26)
+\&   \ep{Pe}                  \ep{Close_Punctuation} (=
+\&                             \ep{General_Category=Close_Punctuation})
+\&                             (77)
+\&   \ep{PerlSpace}           \ep{PosixSpace} (6)
+\&   \ep{PerlWord}            \ep{PosixWord} (63)
+\&   \ep{Perm}                \ep{Old_Permic} (= \ep{Script_Extensions=
+\&                             Old_Permic}) (NOT \ep{Block=Old_Permic})
+\&                             (44)
+\&   \ep{Pf}                  \ep{Final_Punctuation} (=
+\&                             \ep{General_Category=Final_Punctuation})
+\&                             (10)
+\&   \ep{Phag}                \ep{Phags_Pa} (= \ep{Script_Extensions=
+\&                             Phags_Pa}) (NOT \ep{Block=Phags_Pa}) (59)
+\&   \ep{Phags_Pa}            \ep{Script_Extensions=Phags_Pa} (Short:
+\&                             \ep{Phag}; NOT \ep{Block=Phags_Pa}) (59)
+\& X \ep{Phaistos}            \ep{Phaistos_Disc} (= \ep{Block=
+\&                             Phaistos_Disc}) (48)
+\& X \ep{Phaistos_Disc}       \ep{Block=Phaistos_Disc} (Short:
+\&                             \ep{InPhaistos}) (48)
+\&   \ep{Phli}                \ep{Inscriptional_Pahlavi} (=
+\&                             \ep{Script_Extensions=
+\&                             Inscriptional_Pahlavi}) (NOT \ep{Block=
+\&                             Inscriptional_Pahlavi}) (27)
+\&   \ep{Phlp}                \ep{Psalter_Pahlavi} (=
+\&                             \ep{Script_Extensions=Psalter_Pahlavi})
+\&                             (NOT \ep{Block=Psalter_Pahlavi}) (30)
+\&   \ep{Phnx}                \ep{Phoenician} (= \ep{Script_Extensions=
+\&                             Phoenician}) (NOT \ep{Block=Phoenician})
+\&                             (29)
+\&   \ep{Phoenician}          \ep{Script_Extensions=Phoenician} (Short:
+\&                             \ep{Phnx}; NOT \ep{Block=Phoenician}) (29)
+\& X \ep{Phonetic_Ext}        \ep{Phonetic_Extensions} (= \ep{Block=
+\&                             Phonetic_Extensions}) (128)
+\& X \ep{Phonetic_Ext_Sup}    \ep{Phonetic_Extensions_Supplement} (=
+\&                             \ep{Block=
+\&                             Phonetic_Extensions_Supplement}) (64)
+\& X \ep{Phonetic_Extensions} \ep{Block=Phonetic_Extensions} (Short:
+\&                             \ep{InPhoneticExt}) (128)
+\& X \ep{Phonetic_Extensions_Supplement} \ep{Block=
+\&                             Phonetic_Extensions_Supplement} (Short:
+\&                             \ep{InPhoneticExtSup}) (64)
+\&   \ep{Pi}                  \ep{Initial_Punctuation} (=
+\&                             \ep{General_Category=
+\&                             Initial_Punctuation}) (12)
+\& X \ep{Playing_Cards}       \ep{Block=Playing_Cards} (96)
+\&   \ep{Plrd}                \ep{Miao} (= \ep{Script_Extensions=Miao})
+\&                             (NOT \ep{Block=Miao}) (149)
+\&   \ep{Po}                  \ep{Other_Punctuation} (=
+\&                             \ep{General_Category=Other_Punctuation})
+\&                             (628)
+\&   \ep{PosixAlnum}          (62: [0\-9A\-Za\-z])
+\&   \ep{PosixAlpha}          (52: [A\-Za\-z])
+\&   \ep{PosixBlank}          (2: [\et\ex20])
+\&   \ep{PosixCntrl}          ASCII control characters (33: ACK, BEL,
+\&                             BS, CAN, CR, DC1, DC2, DC3, DC4, DEL,
+\&                             DLE, ENQ, EOM, EOT, ESC, ETB, ETX, FF,
+\&                             FS, GS, HT, LF, NAK, NUL, RS, SI, SO,
+\&                             SOH, STX, SUB, SYN, US, VT)
+\&   \ep{PosixDigit}          (10: [0\-9])
+\&   \ep{PosixGraph}          (94: [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@A\-
+\&                             Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~])
+\&   \ep{PosixLower}          (/i= PosixAlpha) (26: [a\-z])
+\&   \ep{PosixPrint}          (95: [\ex20\-\ex7e])
+\&   \ep{PosixPunct}          (32: [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@
+\&                             \e[\e\e\e]\e^_\`\e{\e|\e}~])
+\&   \ep{PosixSpace}          (Short: \ep{PerlSpace}) (6: [\et\en\ecK\ef\er
+\&                             \ex20])
+\&   \ep{PosixUpper}          (/i= PosixAlpha) (26: [A\-Z])
+\&   \ep{PosixWord}           \ew, restricted to ASCII (Short:
+\&                             \ep{PerlWord}) (63: [0\-9A\-Z_a\-z])
+\&   \ep{PosixXDigit}         \ep{ASCII_Hex_Digit=Y} (Short: \ep{AHex})
+\&                             (22)
+\&   \ep{Prepended_Concatenation_Mark} \ep{Prepended_Concatenation_Mark=
+\&                             Y} (Short: \ep{PCM}) (13)
+\&   \ep{Prepended_Concatenation_Mark: N*} (Short: \ep{PCM=N}, \eP{PCM})
+\&                             (1_114_099 plus all above\-Unicode code
+\&                             points: U+0000..05FF, U+0606..06DC,
+\&                             U+06DE..070E, U+0710..088F,
+\&                             U+0892..08E1, U+08E3..110BC ...)
+\&   \ep{Prepended_Concatenation_Mark: Y*} (Short: \ep{PCM=Y}, \ep{PCM})
+\&                             (13: U+0600..0605, U+06DD, U+070F,
+\&                             U+0890..0891, U+08E2, U+110BD ...)
+\& T \ep{Present_In: 1.1}     \ep{Age=V1_1} (Short: \ep{In=1.1}) (Perl
+\&                             extension) (33_979)
+\&   \ep{Present_In: V1_1}    \ep{Present_In=1.1} (= \ep{Age=V1_1}) (Perl
+\&                             extension) (33_979)
+\& T \ep{Present_In: 2.0}     Code point\*(Aqs usage introduced in version
+\&                             2.0 or earlier (Short: \ep{In=2.0}) (Perl
+\&                             extension) (178_500: U+0000..01F5,
+\&                             U+01FA..0217, U+0250..02A8,
+\&                             U+02B0..02DE, U+02E0..02E9, U+0300..0345
+\&                             ...)
+\&   \ep{Present_In: V2_0}    \ep{Present_In=2.0} (Perl extension)
+\&                             (178_500)
+\& T \ep{Present_In: 2.1}     Code point\*(Aqs usage introduced in version
+\&                             2.1 or earlier (Short: \ep{In=2.1}) (Perl
+\&                             extension) (178_502: U+0000..01F5,
+\&                             U+01FA..0217, U+0250..02A8,
+\&                             U+02B0..02DE, U+02E0..02E9, U+0300..0345
+\&                             ...)
+\&   \ep{Present_In: V2_1}    \ep{Present_In=2.1} (Perl extension)
+\&                             (178_502)
+\& T \ep{Present_In: 3.0}     Code point\*(Aqs usage introduced in version
+\&                             3.0 or earlier (Short: \ep{In=3.0}) (Perl
+\&                             extension) (188_809: U+0000..021F,
+\&                             U+0222..0233, U+0250..02AD,
+\&                             U+02B0..02EE, U+0300..034E, U+0360..0362
+\&                             ...)
+\&   \ep{Present_In: V3_0}    \ep{Present_In=3.0} (Perl extension)
+\&                             (188_809)
+\& T \ep{Present_In: 3.1}     Code point\*(Aqs usage introduced in version
+\&                             3.1 or earlier (Short: \ep{In=3.1}) (Perl
+\&                             extension) (233_787: U+0000..021F,
+\&                             U+0222..0233, U+0250..02AD,
+\&                             U+02B0..02EE, U+0300..034E, U+0360..0362
+\&                             ...)
+\&   \ep{Present_In: V3_1}    \ep{Present_In=3.1} (Perl extension)
+\&                             (233_787)
+\& T \ep{Present_In: 3.2}     Code point\*(Aqs usage introduced in version
+\&                             3.2 or earlier (Short: \ep{In=3.2}) (Perl
+\&                             extension) (234_803: U+0000..0220,
+\&                             U+0222..0233, U+0250..02AD,
+\&                             U+02B0..02EE, U+0300..034F, U+0360..036F
+\&                             ...)
+\&   \ep{Present_In: V3_2}    \ep{Present_In=3.2} (Perl extension)
+\&                             (234_803)
+\& T \ep{Present_In: 4.0}     Code point\*(Aqs usage introduced in version
+\&                             4.0 or earlier (Short: \ep{In=4.0}) (Perl
+\&                             extension) (236_029: U+0000..0236,
+\&                             U+0250..0357, U+035D..036F,
+\&                             U+0374..0375, U+037A, U+037E ...)
+\&   \ep{Present_In: V4_0}    \ep{Present_In=4.0} (Perl extension)
+\&                             (236_029)
+\& T \ep{Present_In: 4.1}     Code point\*(Aqs usage introduced in version
+\&                             4.1 or earlier (Short: \ep{In=4.1}) (Perl
+\&                             extension) (237_302: U+0000..0241,
+\&                             U+0250..036F, U+0374..0375, U+037A,
+\&                             U+037E, U+0384..038A ...)
+\&   \ep{Present_In: V4_1}    \ep{Present_In=4.1} (Perl extension)
+\&                             (237_302)
+\& T \ep{Present_In: 5.0}     Code point\*(Aqs usage introduced in version
+\&                             5.0 or earlier (Short: \ep{In=5.0}) (Perl
+\&                             extension) (238_671: U+0000..036F,
+\&                             U+0374..0375, U+037A..037E,
+\&                             U+0384..038A, U+038C, U+038E..03A1 ...)
+\&   \ep{Present_In: V5_0}    \ep{Present_In=5.0} (Perl extension)
+\&                             (238_671)
+\& T \ep{Present_In: 5.1}     Code point\*(Aqs usage introduced in version
+\&                             5.1 or earlier (Short: \ep{In=5.1}) (Perl
+\&                             extension) (240_295: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0523 ...)
+\&   \ep{Present_In: V5_1}    \ep{Present_In=5.1} (Perl extension)
+\&                             (240_295)
+\& T \ep{Present_In: 5.2}     Code point\*(Aqs usage introduced in version
+\&                             5.2 or earlier (Short: \ep{In=5.2}) (Perl
+\&                             extension) (246_943: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0525 ...)
+\&   \ep{Present_In: V5_2}    \ep{Present_In=5.2} (Perl extension)
+\&                             (246_943)
+\& T \ep{Present_In: 6.0}     Code point\*(Aqs usage introduced in version
+\&                             6.0 or earlier (Short: \ep{In=6.0}) (Perl
+\&                             extension) (249_031: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0527 ...)
+\&   \ep{Present_In: V6_0}    \ep{Present_In=6.0} (Perl extension)
+\&                             (249_031)
+\& T \ep{Present_In: 6.1}     Code point\*(Aqs usage introduced in version
+\&                             6.1 or earlier (Short: \ep{In=6.1}) (Perl
+\&                             extension) (249_763: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0527 ...)
+\&   \ep{Present_In: V6_1}    \ep{Present_In=6.1} (Perl extension)
+\&                             (249_763)
+\& T \ep{Present_In: 6.2}     Code point\*(Aqs usage introduced in version
+\&                             6.2 or earlier (Short: \ep{In=6.2}) (Perl
+\&                             extension) (249_764: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0527 ...)
+\&   \ep{Present_In: V6_2}    \ep{Present_In=6.2} (Perl extension)
+\&                             (249_764)
+\& T \ep{Present_In: 6.3}     Code point\*(Aqs usage introduced in version
+\&                             6.3 or earlier (Short: \ep{In=6.3}) (Perl
+\&                             extension) (249_769: U+0000..0377,
+\&                             U+037A..037E, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..0527 ...)
+\&   \ep{Present_In: V6_3}    \ep{Present_In=6.3} (Perl extension)
+\&                             (249_769)
+\& T \ep{Present_In: 7.0}     Code point\*(Aqs usage introduced in version
+\&                             7.0 or earlier (Short: \ep{In=7.0}) (Perl
+\&                             extension) (252_603: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V7_0}    \ep{Present_In=7.0} (Perl extension)
+\&                             (252_603)
+\& T \ep{Present_In: 8.0}     Code point\*(Aqs usage introduced in version
+\&                             8.0 or earlier (Short: \ep{In=8.0}) (Perl
+\&                             extension) (260_319: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V8_0}    \ep{Present_In=8.0} (Perl extension)
+\&                             (260_319)
+\& T \ep{Present_In: 9.0}     Code point\*(Aqs usage introduced in version
+\&                             9.0 or earlier (Short: \ep{In=9.0}) (Perl
+\&                             extension) (267_819: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V9_0}    \ep{Present_In=9.0} (Perl extension)
+\&                             (267_819)
+\& T \ep{Present_In: 10.0}    Code point\*(Aqs usage introduced in version
+\&                             10.0 or earlier (Short: \ep{In=10.0})
+\&                             (Perl extension) (276_337: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V10_0}   \ep{Present_In=10.0} (Perl extension)
+\&                             (276_337)
+\& T \ep{Present_In: 11.0}    Code point\*(Aqs usage introduced in version
+\&                             11.0 or earlier (Short: \ep{In=11.0})
+\&                             (Perl extension) (277_021: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V11_0}   \ep{Present_In=11.0} (Perl extension)
+\&                             (277_021)
+\& T \ep{Present_In: 12.0}    Code point\*(Aqs usage introduced in version
+\&                             12.0 or earlier (Short: \ep{In=12.0})
+\&                             (Perl extension) (277_575: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V12_0}   \ep{Present_In=12.0} (Perl extension)
+\&                             (277_575)
+\& T \ep{Present_In: 12.1}    Code point\*(Aqs usage introduced in version
+\&                             12.1 or earlier (Short: \ep{In=12.1})
+\&                             (Perl extension) (277_576: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V12_1}   \ep{Present_In=12.1} (Perl extension)
+\&                             (277_576)
+\& T \ep{Present_In: 13.0}    Code point\*(Aqs usage introduced in version
+\&                             13.0 or earlier (Short: \ep{In=13.0})
+\&                             (Perl extension) (283_506: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V13_0}   \ep{Present_In=13.0} (Perl extension)
+\&                             (283_506)
+\& T \ep{Present_In: 14.0}    Code point\*(Aqs usage introduced in version
+\&                             14.0 or earlier (Short: \ep{In=14.0})
+\&                             (Perl extension) (284_344: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V14_0}   \ep{Present_In=14.0} (Perl extension)
+\&                             (284_344)
+\& T \ep{Present_In: 15.0}    Code point\*(Aqs usage introduced in version
+\&                             15.0 or earlier (Short: \ep{In=15.0})
+\&                             (Perl extension) (288_833: U+0000..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1, U+03A3..052F ...)
+\&   \ep{Present_In: V15_0}   \ep{Present_In=15.0} (Perl extension)
+\&                             (288_833)
+\&   \ep{Present_In: NA}      \ep{Present_In=Unassigned} (= \ep{Age=
+\&                             Unassigned}) (Perl extension) (825_279
+\&                             plus all above\-Unicode code points)
+\&   \ep{Present_In: Unassigned} \ep{Age=Unassigned} (Short: \ep{In=NA})
+\&                             (Perl extension) (825_279 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Print}               \ep{XPosixPrint} (286_652)
+\&   \ep{Private_Use}         \ep{General_Category=Private_Use} (Short:
+\&                             \ep{Co}; NOT \ep{Private_Use_Area})
+\&                             (137_468)
+\& X \ep{Private_Use_Area}    \ep{Block=Private_Use_Area} (Short:
+\&                             \ep{InPUA}) (6400)
+\&   \ep{Prti}                \ep{Inscriptional_Parthian} (=
+\&                             \ep{Script_Extensions=
+\&                             Inscriptional_Parthian}) (NOT \ep{Block=
+\&                             Inscriptional_Parthian}) (30)
+\&   \ep{Ps}                  \ep{Open_Punctuation} (=
+\&                             \ep{General_Category=Open_Punctuation})
+\&                             (79)
+\&   \ep{Psalter_Pahlavi}     \ep{Script_Extensions=Psalter_Pahlavi}
+\&                             (Short: \ep{Phlp}; NOT \ep{Block=
+\&                             Psalter_Pahlavi}) (30)
+\& X \ep{PUA}                 \ep{Private_Use_Area} (= \ep{Block=
+\&                             Private_Use_Area}) (6400)
+\&   \ep{Punct}               \ep{General_Category=Punctuation} (Short:
+\&                             \ep{P}; NOT \ep{General_Punctuation}) (842)
+\&   \ep{Punctuation}         \ep{Punct} (= \ep{General_Category=
+\&                             Punctuation}) (NOT
+\&                             \ep{General_Punctuation}) (842)
+\&   \ep{Qaac}                \ep{Coptic} (= \ep{Script_Extensions=
+\&                             Coptic}) (NOT \ep{Block=Coptic}) (165)
+\&   \ep{Qaai}                \ep{Inherited} (= \ep{Script_Extensions=
+\&                             Inherited}) (586)
+\&   \ep{QMark}               \ep{Quotation_Mark} (= \ep{Quotation_Mark=
+\&                             Y}) (30)
+\&   \ep{QMark: *}            \ep{Quotation_Mark: *}
+\&   \ep{Quotation_Mark}      \ep{Quotation_Mark=Y} (Short: \ep{QMark})
+\&                             (30)
+\&   \ep{Quotation_Mark: N*}  (Short: \ep{QMark=N}, \eP{QMark}) (1_114_082
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!#\e$\e%&\e(\e)*+,\e\-.\e/0\-9:;<=>?
+\&                             \e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-\exaa\exac\-
+\&                             \exba\exbc\-\exff], U+0100..2017,
+\&                             U+2020..2038, U+203B..2E41,
+\&                             U+2E43..300B, U+3010..301C ...)
+\&   \ep{Quotation_Mark: Y*}  (Short: \ep{QMark=Y}, \ep{QMark}) (30: [\e"
+\&                             \e\*(Aq\exab\exbb], U+2018..201F, U+2039..203A,
+\&                             U+2E42, U+300C..300F, U+301D..301F ...)
+\&   \ep{Radical}             \ep{Radical=Y} (329)
+\&   \ep{Radical: N*}         (Single: \eP{Radical}) (1_113_783 plus all
+\&                             above\-Unicode code points: U+0000..2E7F,
+\&                             U+2E9A, U+2EF4..2EFF, U+2FD6..infinity)
+\&   \ep{Radical: Y*}         (Single: \ep{Radical}) (329: U+2E80..2E99,
+\&                             U+2E9B..2EF3, U+2F00..2FD5)
+\&   \ep{Regional_Indicator}  \ep{Regional_Indicator=Y} (Short: \ep{RI})
+\&                             (26)
+\&   \ep{Regional_Indicator: N*} (Short: \ep{RI=N}, \eP{RI}) (1_114_086
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..1F1E5, U+1F200..infinity)
+\&   \ep{Regional_Indicator: Y*} (Short: \ep{RI=Y}, \ep{RI}) (26:
+\&                             U+1F1E6..1F1FF)
+\&   \ep{Rejang}              \ep{Script_Extensions=Rejang} (Short:
+\&                             \ep{Rjng}; NOT \ep{Block=Rejang}) (37)
+\&   \ep{RI}                  \ep{Regional_Indicator} (=
+\&                             \ep{Regional_Indicator=Y}) (26)
+\&   \ep{RI: *}               \ep{Regional_Indicator: *}
+\&   \ep{Rjng}                \ep{Rejang} (= \ep{Script_Extensions=
+\&                             Rejang}) (NOT \ep{Block=Rejang}) (37)
+\&   \ep{Rohg}                \ep{Hanifi_Rohingya} (=
+\&                             \ep{Script_Extensions=Hanifi_Rohingya})
+\&                             (NOT \ep{Block=Hanifi_Rohingya}) (55)
+\& X \ep{Rumi}                \ep{Rumi_Numeral_Symbols} (= \ep{Block=
+\&                             Rumi_Numeral_Symbols}) (32)
+\& X \ep{Rumi_Numeral_Symbols} \ep{Block=Rumi_Numeral_Symbols} (Short:
+\&                             \ep{InRumi}) (32)
+\&   \ep{Runic}               \ep{Script_Extensions=Runic} (Short:
+\&                             \ep{Runr}; NOT \ep{Block=Runic}) (86)
+\&   \ep{Runr}                \ep{Runic} (= \ep{Script_Extensions=Runic})
+\&                             (NOT \ep{Block=Runic}) (86)
+\&   \ep{S} \epS               \ep{Symbol} (= \ep{General_Category=Symbol})
+\&                             (7770)
+\&   \ep{Samaritan}           \ep{Script_Extensions=Samaritan} (Short:
+\&                             \ep{Samr}; NOT \ep{Block=Samaritan}) (61)
+\&   \ep{Samr}                \ep{Samaritan} (= \ep{Script_Extensions=
+\&                             Samaritan}) (NOT \ep{Block=Samaritan})
+\&                             (61)
+\&   \ep{Sarb}                \ep{Old_South_Arabian} (=
+\&                             \ep{Script_Extensions=Old_South_Arabian})
+\&                             (32)
+\&   \ep{Saur}                \ep{Saurashtra} (= \ep{Script_Extensions=
+\&                             Saurashtra}) (NOT \ep{Block=Saurashtra})
+\&                             (82)
+\&   \ep{Saurashtra}          \ep{Script_Extensions=Saurashtra} (Short:
+\&                             \ep{Saur}; NOT \ep{Block=Saurashtra}) (82)
+\&   \ep{SB: *}               \ep{Sentence_Break: *}
+\&   \ep{Sc}                  \ep{Currency_Symbol} (=
+\&                             \ep{General_Category=Currency_Symbol})
+\&                             (63)
+\&   \ep{Sc: *}               \ep{Script: *}
+\&   \ep{Script: Adlam}       (Short: \ep{Sc=Adlm}) (88: U+1E900..1E94B,
+\&                             U+1E950..1E959, U+1E95E..1E95F)
+\&   \ep{Script: Adlm}        \ep{Script=Adlam} (88)
+\&   \ep{Script: Aghb}        \ep{Script=Caucasian_Albanian} (=
+\&                             \ep{Script_Extensions=
+\&                             Caucasian_Albanian}) (53)
+\&   \ep{Script: Ahom}        \ep{Script_Extensions=Ahom} (Short: \ep{Sc=
+\&                             Ahom}, \ep{Ahom}) (65)
+\&   \ep{Script: Anatolian_Hieroglyphs} \ep{Script_Extensions=
+\&                             Anatolian_Hieroglyphs} (Short: \ep{Sc=
+\&                             Hluw}, \ep{Hluw}) (583)
+\&   \ep{Script: Arab}        \ep{Script=Arabic} (1368)
+\&   \ep{Script: Arabic}      (Short: \ep{Sc=Arab}) (1368: U+0600..0604,
+\&                             U+0606..060B, U+060D..061A,
+\&                             U+061C..061E, U+0620..063F, U+0641..064A
+\&                             ...)
+\&   \ep{Script: Armenian}    \ep{Script_Extensions=Armenian} (Short:
+\&                             \ep{Sc=Armn}, \ep{Armn}) (96)
+\&   \ep{Script: Armi}        \ep{Script=Imperial_Aramaic} (=
+\&                             \ep{Script_Extensions=Imperial_Aramaic})
+\&                             (31)
+\&   \ep{Script: Armn}        \ep{Script=Armenian} (=
+\&                             \ep{Script_Extensions=Armenian}) (96)
+\&   \ep{Script: Avestan}     \ep{Script_Extensions=Avestan} (Short:
+\&                             \ep{Sc=Avst}, \ep{Avst}) (61)
+\&   \ep{Script: Avst}        \ep{Script=Avestan} (=
+\&                             \ep{Script_Extensions=Avestan}) (61)
+\&   \ep{Script: Bali}        \ep{Script=Balinese} (=
+\&                             \ep{Script_Extensions=Balinese}) (124)
+\&   \ep{Script: Balinese}    \ep{Script_Extensions=Balinese} (Short:
+\&                             \ep{Sc=Bali}, \ep{Bali}) (124)
+\&   \ep{Script: Bamu}        \ep{Script=Bamum} (= \ep{Script_Extensions=
+\&                             Bamum}) (657)
+\&   \ep{Script: Bamum}       \ep{Script_Extensions=Bamum} (Short: \ep{Sc=
+\&                             Bamu}, \ep{Bamu}) (657)
+\&   \ep{Script: Bass}        \ep{Script=Bassa_Vah} (=
+\&                             \ep{Script_Extensions=Bassa_Vah}) (36)
+\&   \ep{Script: Bassa_Vah}   \ep{Script_Extensions=Bassa_Vah} (Short:
+\&                             \ep{Sc=Bass}, \ep{Bass}) (36)
+\&   \ep{Script: Batak}       \ep{Script_Extensions=Batak} (Short: \ep{Sc=
+\&                             Batk}, \ep{Batk}) (56)
+\&   \ep{Script: Batk}        \ep{Script=Batak} (= \ep{Script_Extensions=
+\&                             Batak}) (56)
+\&   \ep{Script: Beng}        \ep{Script=Bengali} (96)
+\&   \ep{Script: Bengali}     (Short: \ep{Sc=Beng}) (96: U+0980..0983,
+\&                             U+0985..098C, U+098F..0990,
+\&                             U+0993..09A8, U+09AA..09B0, U+09B2 ...)
+\&   \ep{Script: Bhaiksuki}   \ep{Script_Extensions=Bhaiksuki} (Short:
+\&                             \ep{Sc=Bhks}, \ep{Bhks}) (97)
+\&   \ep{Script: Bhks}        \ep{Script=Bhaiksuki} (=
+\&                             \ep{Script_Extensions=Bhaiksuki}) (97)
+\&   \ep{Script: Bopo}        \ep{Script=Bopomofo} (77)
+\&   \ep{Script: Bopomofo}    (Short: \ep{Sc=Bopo}) (77: U+02EA..02EB,
+\&                             U+3105..312F, U+31A0..31BF)
+\&   \ep{Script: Brah}        \ep{Script=Brahmi} (= \ep{Script_Extensions=
+\&                             Brahmi}) (115)
+\&   \ep{Script: Brahmi}      \ep{Script_Extensions=Brahmi} (Short:
+\&                             \ep{Sc=Brah}, \ep{Brah}) (115)
+\&   \ep{Script: Brai}        \ep{Script=Braille} (=
+\&                             \ep{Script_Extensions=Braille}) (256)
+\&   \ep{Script: Braille}     \ep{Script_Extensions=Braille} (Short:
+\&                             \ep{Sc=Brai}, \ep{Brai}) (256)
+\&   \ep{Script: Bugi}        \ep{Script=Buginese} (30)
+\&   \ep{Script: Buginese}    (Short: \ep{Sc=Bugi}) (30: U+1A00..1A1B,
+\&                             U+1A1E..1A1F)
+\&   \ep{Script: Buhd}        \ep{Script=Buhid} (20)
+\&   \ep{Script: Buhid}       (Short: \ep{Sc=Buhd}) (20: U+1740..1753)
+\&   \ep{Script: Cakm}        \ep{Script=Chakma} (71)
+\&   \ep{Script: Canadian_Aboriginal} \ep{Script_Extensions=
+\&                             Canadian_Aboriginal} (Short: \ep{Sc=
+\&                             Cans}, \ep{Cans}) (726)
+\&   \ep{Script: Cans}        \ep{Script=Canadian_Aboriginal} (=
+\&                             \ep{Script_Extensions=
+\&                             Canadian_Aboriginal}) (726)
+\&   \ep{Script: Cari}        \ep{Script=Carian} (= \ep{Script_Extensions=
+\&                             Carian}) (49)
+\&   \ep{Script: Carian}      \ep{Script_Extensions=Carian} (Short:
+\&                             \ep{Sc=Cari}, \ep{Cari}) (49)
+\&   \ep{Script: Caucasian_Albanian} \ep{Script_Extensions=
+\&                             Caucasian_Albanian} (Short: \ep{Sc=Aghb},
+\&                             \ep{Aghb}) (53)
+\&   \ep{Script: Chakma}      (Short: \ep{Sc=Cakm}) (71: U+11100..11134,
+\&                             U+11136..11147)
+\&   \ep{Script: Cham}        \ep{Script_Extensions=Cham} (Short: \ep{Sc=
+\&                             Cham}, \ep{Cham}) (83)
+\&   \ep{Script: Cher}        \ep{Script=Cherokee} (=
+\&                             \ep{Script_Extensions=Cherokee}) (172)
+\&   \ep{Script: Cherokee}    \ep{Script_Extensions=Cherokee} (Short:
+\&                             \ep{Sc=Cher}, \ep{Cher}) (172)
+\&   \ep{Script: Chorasmian}  \ep{Script_Extensions=Chorasmian} (Short:
+\&                             \ep{Sc=Chrs}, \ep{Chrs}) (28)
+\&   \ep{Script: Chrs}        \ep{Script=Chorasmian} (=
+\&                             \ep{Script_Extensions=Chorasmian}) (28)
+\&   \ep{Script: Common}      (Short: \ep{Sc=Zyyy}) (8301: [\ex00\-\ex20!
+\&                             \e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@\e[\e\e\e]
+\&                             \e^_\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb9\exbb\-\exbf
+\&                             \exd7\exf7], U+02B9..02DF, U+02E5..02E9,
+\&                             U+02EC..02FF, U+0374, U+037E ...)
+\&   \ep{Script: Copt}        \ep{Script=Coptic} (137)
+\&   \ep{Script: Coptic}      (Short: \ep{Sc=Copt}) (137: U+03E2..03EF,
+\&                             U+2C80..2CF3, U+2CF9..2CFF)
+\&   \ep{Script: Cpmn}        \ep{Script=Cypro_Minoan} (99)
+\&   \ep{Script: Cprt}        \ep{Script=Cypriot} (55)
+\&   \ep{Script: Cuneiform}   \ep{Script_Extensions=Cuneiform} (Short:
+\&                             \ep{Sc=Xsux}, \ep{Xsux}) (1234)
+\&   \ep{Script: Cypriot}     (Short: \ep{Sc=Cprt}) (55: U+10800..10805,
+\&                             U+10808, U+1080A..10835, U+10837..10838,
+\&                             U+1083C, U+1083F)
+\&   \ep{Script: Cypro_Minoan} (Short: \ep{Sc=Cpmn}) (99: U+12F90..12FF2)
+\&   \ep{Script: Cyrillic}    (Short: \ep{Sc=Cyrl}) (506: U+0400..0484,
+\&                             U+0487..052F, U+1C80..1C88, U+1D2B,
+\&                             U+1D78, U+2DE0..2DFF ...)
+\&   \ep{Script: Cyrl}        \ep{Script=Cyrillic} (506)
+\&   \ep{Script: Deseret}     \ep{Script_Extensions=Deseret} (Short:
+\&                             \ep{Sc=Dsrt}, \ep{Dsrt}) (80)
+\&   \ep{Script: Deva}        \ep{Script=Devanagari} (164)
+\&   \ep{Script: Devanagari}  (Short: \ep{Sc=Deva}) (164: U+0900..0950,
+\&                             U+0955..0963, U+0966..097F,
+\&                             U+A8E0..A8FF, U+11B00..11B09)
+\&   \ep{Script: Diak}        \ep{Script=Dives_Akuru} (=
+\&                             \ep{Script_Extensions=Dives_Akuru}) (72)
+\&   \ep{Script: Dives_Akuru} \ep{Script_Extensions=Dives_Akuru} (Short:
+\&                             \ep{Sc=Diak}, \ep{Diak}) (72)
+\&   \ep{Script: Dogr}        \ep{Script=Dogra} (60)
+\&   \ep{Script: Dogra}       (Short: \ep{Sc=Dogr}) (60: U+11800..1183B)
+\&   \ep{Script: Dsrt}        \ep{Script=Deseret} (=
+\&                             \ep{Script_Extensions=Deseret}) (80)
+\&   \ep{Script: Dupl}        \ep{Script=Duployan} (143)
+\&   \ep{Script: Duployan}    (Short: \ep{Sc=Dupl}) (143: U+1BC00..1BC6A,
+\&                             U+1BC70..1BC7C, U+1BC80..1BC88,
+\&                             U+1BC90..1BC99, U+1BC9C..1BC9F)
+\&   \ep{Script: Egyp}        \ep{Script=Egyptian_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Egyptian_Hieroglyphs}) (1110)
+\&   \ep{Script: Egyptian_Hieroglyphs} \ep{Script_Extensions=
+\&                             Egyptian_Hieroglyphs} (Short: \ep{Sc=
+\&                             Egyp}, \ep{Egyp}) (1110)
+\&   \ep{Script: Elba}        \ep{Script=Elbasan} (=
+\&                             \ep{Script_Extensions=Elbasan}) (40)
+\&   \ep{Script: Elbasan}     \ep{Script_Extensions=Elbasan} (Short:
+\&                             \ep{Sc=Elba}, \ep{Elba}) (40)
+\&   \ep{Script: Elym}        \ep{Script=Elymaic} (=
+\&                             \ep{Script_Extensions=Elymaic}) (23)
+\&   \ep{Script: Elymaic}     \ep{Script_Extensions=Elymaic} (Short:
+\&                             \ep{Sc=Elym}, \ep{Elym}) (23)
+\&   \ep{Script: Ethi}        \ep{Script=Ethiopic} (=
+\&                             \ep{Script_Extensions=Ethiopic}) (523)
+\&   \ep{Script: Ethiopic}    \ep{Script_Extensions=Ethiopic} (Short:
+\&                             \ep{Sc=Ethi}, \ep{Ethi}) (523)
+\&   \ep{Script: Geor}        \ep{Script=Georgian} (173)
+\&   \ep{Script: Georgian}    (Short: \ep{Sc=Geor}) (173: U+10A0..10C5,
+\&                             U+10C7, U+10CD, U+10D0..10FA,
+\&                             U+10FC..10FF, U+1C90..1CBA ...)
+\&   \ep{Script: Glag}        \ep{Script=Glagolitic} (134)
+\&   \ep{Script: Glagolitic}  (Short: \ep{Sc=Glag}) (134: U+2C00..2C5F,
+\&                             U+1E000..1E006, U+1E008..1E018,
+\&                             U+1E01B..1E021, U+1E023..1E024,
+\&                             U+1E026..1E02A)
+\&   \ep{Script: Gong}        \ep{Script=Gunjala_Gondi} (63)
+\&   \ep{Script: Gonm}        \ep{Script=Masaram_Gondi} (75)
+\&   \ep{Script: Goth}        \ep{Script=Gothic} (= \ep{Script_Extensions=
+\&                             Gothic}) (27)
+\&   \ep{Script: Gothic}      \ep{Script_Extensions=Gothic} (Short:
+\&                             \ep{Sc=Goth}, \ep{Goth}) (27)
+\&   \ep{Script: Gran}        \ep{Script=Grantha} (85)
+\&   \ep{Script: Grantha}     (Short: \ep{Sc=Gran}) (85: U+11300..11303,
+\&                             U+11305..1130C, U+1130F..11310,
+\&                             U+11313..11328, U+1132A..11330,
+\&                             U+11332..11333 ...)
+\&   \ep{Script: Greek}       (Short: \ep{Sc=Grek}) (518: U+0370..0373,
+\&                             U+0375..0377, U+037A..037D, U+037F,
+\&                             U+0384, U+0386 ...)
+\&   \ep{Script: Grek}        \ep{Script=Greek} (518)
+\&   \ep{Script: Gujarati}    (Short: \ep{Sc=Gujr}) (91: U+0A81..0A83,
+\&                             U+0A85..0A8D, U+0A8F..0A91,
+\&                             U+0A93..0AA8, U+0AAA..0AB0, U+0AB2..0AB3
+\&                             ...)
+\&   \ep{Script: Gujr}        \ep{Script=Gujarati} (91)
+\&   \ep{Script: Gunjala_Gondi} (Short: \ep{Sc=Gong}) (63:
+\&                             U+11D60..11D65, U+11D67..11D68,
+\&                             U+11D6A..11D8E, U+11D90..11D91,
+\&                             U+11D93..11D98, U+11DA0..11DA9)
+\&   \ep{Script: Gurmukhi}    (Short: \ep{Sc=Guru}) (80: U+0A01..0A03,
+\&                             U+0A05..0A0A, U+0A0F..0A10,
+\&                             U+0A13..0A28, U+0A2A..0A30, U+0A32..0A33
+\&                             ...)
+\&   \ep{Script: Guru}        \ep{Script=Gurmukhi} (80)
+\&   \ep{Script: Han}         (Short: \ep{Sc=Han}) (98_408: U+2E80..2E99,
+\&                             U+2E9B..2EF3, U+2F00..2FD5, U+3005,
+\&                             U+3007, U+3021..3029 ...)
+\&   \ep{Script: Hang}        \ep{Script=Hangul} (11_739)
+\&   \ep{Script: Hangul}      (Short: \ep{Sc=Hang}) (11_739:
+\&                             U+1100..11FF, U+302E..302F,
+\&                             U+3131..318E, U+3200..321E,
+\&                             U+3260..327E, U+A960..A97C ...)
+\&   \ep{Script: Hani}        \ep{Script=Han} (98_408)
+\&   \ep{Script: Hanifi_Rohingya} (Short: \ep{Sc=Rohg}) (50:
+\&                             U+10D00..10D27, U+10D30..10D39)
+\&   \ep{Script: Hano}        \ep{Script=Hanunoo} (21)
+\&   \ep{Script: Hanunoo}     (Short: \ep{Sc=Hano}) (21: U+1720..1734)
+\&   \ep{Script: Hatr}        \ep{Script=Hatran} (= \ep{Script_Extensions=
+\&                             Hatran}) (26)
+\&   \ep{Script: Hatran}      \ep{Script_Extensions=Hatran} (Short:
+\&                             \ep{Sc=Hatr}, \ep{Hatr}) (26)
+\&   \ep{Script: Hebr}        \ep{Script=Hebrew} (= \ep{Script_Extensions=
+\&                             Hebrew}) (134)
+\&   \ep{Script: Hebrew}      \ep{Script_Extensions=Hebrew} (Short:
+\&                             \ep{Sc=Hebr}, \ep{Hebr}) (134)
+\&   \ep{Script: Hira}        \ep{Script=Hiragana} (381)
+\&   \ep{Script: Hiragana}    (Short: \ep{Sc=Hira}) (381: U+3041..3096,
+\&                             U+309D..309F, U+1B001..1B11F, U+1B132,
+\&                             U+1B150..1B152, U+1F200)
+\&   \ep{Script: Hluw}        \ep{Script=Anatolian_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Anatolian_Hieroglyphs}) (583)
+\&   \ep{Script: Hmng}        \ep{Script=Pahawh_Hmong} (=
+\&                             \ep{Script_Extensions=Pahawh_Hmong}) (127)
+\&   \ep{Script: Hmnp}        \ep{Script=Nyiakeng_Puachue_Hmong} (=
+\&                             \ep{Script_Extensions=
+\&                             Nyiakeng_Puachue_Hmong}) (71)
+\&   \ep{Script: Hung}        \ep{Script=Old_Hungarian} (=
+\&                             \ep{Script_Extensions=Old_Hungarian})
+\&                             (108)
+\&   \ep{Script: Imperial_Aramaic} \ep{Script_Extensions=
+\&                             Imperial_Aramaic} (Short: \ep{Sc=Armi},
+\&                             \ep{Armi}) (31)
+\&   \ep{Script: Inherited}   (Short: \ep{Sc=Zinh}) (657: U+0300..036F,
+\&                             U+0485..0486, U+064B..0655, U+0670,
+\&                             U+0951..0954, U+1AB0..1ACE ...)
+\&   \ep{Script: Inscriptional_Pahlavi} \ep{Script_Extensions=
+\&                             Inscriptional_Pahlavi} (Short: \ep{Sc=
+\&                             Phli}, \ep{Phli}) (27)
+\&   \ep{Script: Inscriptional_Parthian} \ep{Script_Extensions=
+\&                             Inscriptional_Parthian} (Short: \ep{Sc=
+\&                             Prti}, \ep{Prti}) (30)
+\&   \ep{Script: Ital}        \ep{Script=Old_Italic} (=
+\&                             \ep{Script_Extensions=Old_Italic}) (39)
+\&   \ep{Script: Java}        \ep{Script=Javanese} (90)
+\&   \ep{Script: Javanese}    (Short: \ep{Sc=Java}) (90: U+A980..A9CD,
+\&                             U+A9D0..A9D9, U+A9DE..A9DF)
+\&   \ep{Script: Kaithi}      (Short: \ep{Sc=Kthi}) (68: U+11080..110C2,
+\&                             U+110CD)
+\&   \ep{Script: Kali}        \ep{Script=Kayah_Li} (47)
+\&   \ep{Script: Kana}        \ep{Script=Katakana} (321)
+\&   \ep{Script: Kannada}     (Short: \ep{Sc=Knda}) (91: U+0C80..0C8C,
+\&                             U+0C8E..0C90, U+0C92..0CA8,
+\&                             U+0CAA..0CB3, U+0CB5..0CB9, U+0CBC..0CC4
+\&                             ...)
+\&   \ep{Script: Katakana}    (Short: \ep{Sc=Kana}) (321: U+30A1..30FA,
+\&                             U+30FD..30FF, U+31F0..31FF,
+\&                             U+32D0..32FE, U+3300..3357, U+FF66..FF6F
+\&                             ...)
+\&   \ep{Script: Kawi}        \ep{Script_Extensions=Kawi} (Short: \ep{Sc=
+\&                             Kawi}, \ep{Kawi}) (86)
+\&   \ep{Script: Kayah_Li}    (Short: \ep{Sc=Kali}) (47: U+A900..A92D,
+\&                             U+A92F)
+\&   \ep{Script: Khar}        \ep{Script=Kharoshthi} (=
+\&                             \ep{Script_Extensions=Kharoshthi}) (68)
+\&   \ep{Script: Kharoshthi}  \ep{Script_Extensions=Kharoshthi} (Short:
+\&                             \ep{Sc=Khar}, \ep{Khar}) (68)
+\&   \ep{Script: Khitan_Small_Script} \ep{Script_Extensions=
+\&                             Khitan_Small_Script} (Short: \ep{Sc=
+\&                             Kits}, \ep{Kits}) (471)
+\&   \ep{Script: Khmer}       \ep{Script_Extensions=Khmer} (Short: \ep{Sc=
+\&                             Khmr}, \ep{Khmr}) (146)
+\&   \ep{Script: Khmr}        \ep{Script=Khmer} (= \ep{Script_Extensions=
+\&                             Khmer}) (146)
+\&   \ep{Script: Khoj}        \ep{Script=Khojki} (65)
+\&   \ep{Script: Khojki}      (Short: \ep{Sc=Khoj}) (65: U+11200..11211,
+\&                             U+11213..11241)
+\&   \ep{Script: Khudawadi}   (Short: \ep{Sc=Sind}) (69: U+112B0..112EA,
+\&                             U+112F0..112F9)
+\&   \ep{Script: Kits}        \ep{Script=Khitan_Small_Script} (=
+\&                             \ep{Script_Extensions=
+\&                             Khitan_Small_Script}) (471)
+\&   \ep{Script: Knda}        \ep{Script=Kannada} (91)
+\&   \ep{Script: Kthi}        \ep{Script=Kaithi} (68)
+\&   \ep{Script: Lana}        \ep{Script=Tai_Tham} (=
+\&                             \ep{Script_Extensions=Tai_Tham}) (127)
+\&   \ep{Script: Lao}         \ep{Script_Extensions=Lao} (Short: \ep{Sc=
+\&                             Lao}, \ep{Lao}) (83)
+\&   \ep{Script: Laoo}        \ep{Script=Lao} (= \ep{Script_Extensions=
+\&                             Lao}) (83)
+\&   \ep{Script: Latin}       (Short: \ep{Sc=Latn}) (1481: [A\-Za\-z\exaa
+\&                             \exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..02B8, U+02E0..02E4,
+\&                             U+1D00..1D25, U+1D2C..1D5C, U+1D62..1D65
+\&                             ...)
+\&   \ep{Script: Latn}        \ep{Script=Latin} (1481)
+\&   \ep{Script: Lepc}        \ep{Script=Lepcha} (= \ep{Script_Extensions=
+\&                             Lepcha}) (74)
+\&   \ep{Script: Lepcha}      \ep{Script_Extensions=Lepcha} (Short:
+\&                             \ep{Sc=Lepc}, \ep{Lepc}) (74)
+\&   \ep{Script: Limb}        \ep{Script=Limbu} (68)
+\&   \ep{Script: Limbu}       (Short: \ep{Sc=Limb}) (68: U+1900..191E,
+\&                             U+1920..192B, U+1930..193B, U+1940,
+\&                             U+1944..194F)
+\&   \ep{Script: Lina}        \ep{Script=Linear_A} (341)
+\&   \ep{Script: Linb}        \ep{Script=Linear_B} (211)
+\&   \ep{Script: Linear_A}    (Short: \ep{Sc=Lina}) (341: U+10600..10736,
+\&                             U+10740..10755, U+10760..10767)
+\&   \ep{Script: Linear_B}    (Short: \ep{Sc=Linb}) (211: U+10000..1000B,
+\&                             U+1000D..10026, U+10028..1003A,
+\&                             U+1003C..1003D, U+1003F..1004D,
+\&                             U+10050..1005D ...)
+\&   \ep{Script: Lisu}        \ep{Script_Extensions=Lisu} (Short: \ep{Sc=
+\&                             Lisu}, \ep{Lisu}) (49)
+\&   \ep{Script: Lyci}        \ep{Script=Lycian} (= \ep{Script_Extensions=
+\&                             Lycian}) (29)
+\&   \ep{Script: Lycian}      \ep{Script_Extensions=Lycian} (Short:
+\&                             \ep{Sc=Lyci}, \ep{Lyci}) (29)
+\&   \ep{Script: Lydi}        \ep{Script=Lydian} (= \ep{Script_Extensions=
+\&                             Lydian}) (27)
+\&   \ep{Script: Lydian}      \ep{Script_Extensions=Lydian} (Short:
+\&                             \ep{Sc=Lydi}, \ep{Lydi}) (27)
+\&   \ep{Script: Mahajani}    (Short: \ep{Sc=Mahj}) (39: U+11150..11176)
+\&   \ep{Script: Mahj}        \ep{Script=Mahajani} (39)
+\&   \ep{Script: Maka}        \ep{Script=Makasar} (=
+\&                             \ep{Script_Extensions=Makasar}) (25)
+\&   \ep{Script: Makasar}     \ep{Script_Extensions=Makasar} (Short:
+\&                             \ep{Sc=Maka}, \ep{Maka}) (25)
+\&   \ep{Script: Malayalam}   (Short: \ep{Sc=Mlym}) (118: U+0D00..0D0C,
+\&                             U+0D0E..0D10, U+0D12..0D44,
+\&                             U+0D46..0D48, U+0D4A..0D4F, U+0D54..0D63
+\&                             ...)
+\&   \ep{Script: Mand}        \ep{Script=Mandaic} (29)
+\&   \ep{Script: Mandaic}     (Short: \ep{Sc=Mand}) (29: U+0840..085B,
+\&                             U+085E)
+\&   \ep{Script: Mani}        \ep{Script=Manichaean} (51)
+\&   \ep{Script: Manichaean}  (Short: \ep{Sc=Mani}) (51: U+10AC0..10AE6,
+\&                             U+10AEB..10AF6)
+\&   \ep{Script: Marc}        \ep{Script=Marchen} (=
+\&                             \ep{Script_Extensions=Marchen}) (68)
+\&   \ep{Script: Marchen}     \ep{Script_Extensions=Marchen} (Short:
+\&                             \ep{Sc=Marc}, \ep{Marc}) (68)
+\&   \ep{Script: Masaram_Gondi} (Short: \ep{Sc=Gonm}) (75:
+\&                             U+11D00..11D06, U+11D08..11D09,
+\&                             U+11D0B..11D36, U+11D3A, U+11D3C..11D3D,
+\&                             U+11D3F..11D47 ...)
+\&   \ep{Script: Medefaidrin} \ep{Script_Extensions=Medefaidrin} (Short:
+\&                             \ep{Sc=Medf}, \ep{Medf}) (91)
+\&   \ep{Script: Medf}        \ep{Script=Medefaidrin} (=
+\&                             \ep{Script_Extensions=Medefaidrin}) (91)
+\&   \ep{Script: Meetei_Mayek} \ep{Script_Extensions=Meetei_Mayek}
+\&                             (Short: \ep{Sc=Mtei}, \ep{Mtei}) (79)
+\&   \ep{Script: Mend}        \ep{Script=Mende_Kikakui} (=
+\&                             \ep{Script_Extensions=Mende_Kikakui})
+\&                             (213)
+\&   \ep{Script: Mende_Kikakui} \ep{Script_Extensions=Mende_Kikakui}
+\&                             (Short: \ep{Sc=Mend}, \ep{Mend}) (213)
+\&   \ep{Script: Merc}        \ep{Script=Meroitic_Cursive} (=
+\&                             \ep{Script_Extensions=Meroitic_Cursive})
+\&                             (90)
+\&   \ep{Script: Mero}        \ep{Script=Meroitic_Hieroglyphs} (=
+\&                             \ep{Script_Extensions=
+\&                             Meroitic_Hieroglyphs}) (32)
+\&   \ep{Script: Meroitic_Cursive} \ep{Script_Extensions=
+\&                             Meroitic_Cursive} (Short: \ep{Sc=Merc},
+\&                             \ep{Merc}) (90)
+\&   \ep{Script: Meroitic_Hieroglyphs} \ep{Script_Extensions=
+\&                             Meroitic_Hieroglyphs} (Short: \ep{Sc=
+\&                             Mero}, \ep{Mero}) (32)
+\&   \ep{Script: Miao}        \ep{Script_Extensions=Miao} (Short: \ep{Sc=
+\&                             Miao}, \ep{Miao}) (149)
+\&   \ep{Script: Mlym}        \ep{Script=Malayalam} (118)
+\&   \ep{Script: Modi}        (Short: \ep{Sc=Modi}) (79: U+11600..11644,
+\&                             U+11650..11659)
+\&   \ep{Script: Mong}        \ep{Script=Mongolian} (168)
+\&   \ep{Script: Mongolian}   (Short: \ep{Sc=Mong}) (168: U+1800..1801,
+\&                             U+1804, U+1806..1819, U+1820..1878,
+\&                             U+1880..18AA, U+11660..1166C)
+\&   \ep{Script: Mro}         \ep{Script_Extensions=Mro} (Short: \ep{Sc=
+\&                             Mro}, \ep{Mro}) (43)
+\&   \ep{Script: Mroo}        \ep{Script=Mro} (= \ep{Script_Extensions=
+\&                             Mro}) (43)
+\&   \ep{Script: Mtei}        \ep{Script=Meetei_Mayek} (=
+\&                             \ep{Script_Extensions=Meetei_Mayek}) (79)
+\&   \ep{Script: Mult}        \ep{Script=Multani} (38)
+\&   \ep{Script: Multani}     (Short: \ep{Sc=Mult}) (38: U+11280..11286,
+\&                             U+11288, U+1128A..1128D, U+1128F..1129D,
+\&                             U+1129F..112A9)
+\&   \ep{Script: Myanmar}     (Short: \ep{Sc=Mymr}) (223: U+1000..109F,
+\&                             U+A9E0..A9FE, U+AA60..AA7F)
+\&   \ep{Script: Mymr}        \ep{Script=Myanmar} (223)
+\&   \ep{Script: Nabataean}   \ep{Script_Extensions=Nabataean} (Short:
+\&                             \ep{Sc=Nbat}, \ep{Nbat}) (40)
+\&   \ep{Script: Nag_Mundari} \ep{Script_Extensions=Nag_Mundari} (Short:
+\&                             \ep{Sc=Nagm}, \ep{Nagm}) (42)
+\&   \ep{Script: Nagm}        \ep{Script=Nag_Mundari} (=
+\&                             \ep{Script_Extensions=Nag_Mundari}) (42)
+\&   \ep{Script: Nand}        \ep{Script=Nandinagari} (65)
+\&   \ep{Script: Nandinagari} (Short: \ep{Sc=Nand}) (65: U+119A0..119A7,
+\&                             U+119AA..119D7, U+119DA..119E4)
+\&   \ep{Script: Narb}        \ep{Script=Old_North_Arabian} (=
+\&                             \ep{Script_Extensions=Old_North_Arabian})
+\&                             (32)
+\&   \ep{Script: Nbat}        \ep{Script=Nabataean} (=
+\&                             \ep{Script_Extensions=Nabataean}) (40)
+\&   \ep{Script: New_Tai_Lue} \ep{Script_Extensions=New_Tai_Lue} (Short:
+\&                             \ep{Sc=Talu}, \ep{Talu}) (83)
+\&   \ep{Script: Newa}        \ep{Script_Extensions=Newa} (Short: \ep{Sc=
+\&                             Newa}, \ep{Newa}) (97)
+\&   \ep{Script: Nko}         (Short: \ep{Sc=Nko}) (62: U+07C0..07FA,
+\&                             U+07FD..07FF)
+\&   \ep{Script: Nkoo}        \ep{Script=Nko} (62)
+\&   \ep{Script: Nshu}        \ep{Script=Nushu} (= \ep{Script_Extensions=
+\&                             Nushu}) (397)
+\&   \ep{Script: Nushu}       \ep{Script_Extensions=Nushu} (Short: \ep{Sc=
+\&                             Nshu}, \ep{Nshu}) (397)
+\&   \ep{Script: Nyiakeng_Puachue_Hmong} \ep{Script_Extensions=
+\&                             Nyiakeng_Puachue_Hmong} (Short: \ep{Sc=
+\&                             Hmnp}, \ep{Hmnp}) (71)
+\&   \ep{Script: Ogam}        \ep{Script=Ogham} (= \ep{Script_Extensions=
+\&                             Ogham}) (29)
+\&   \ep{Script: Ogham}       \ep{Script_Extensions=Ogham} (Short: \ep{Sc=
+\&                             Ogam}, \ep{Ogam}) (29)
+\&   \ep{Script: Ol_Chiki}    \ep{Script_Extensions=Ol_Chiki} (Short:
+\&                             \ep{Sc=Olck}, \ep{Olck}) (48)
+\&   \ep{Script: Olck}        \ep{Script=Ol_Chiki} (=
+\&                             \ep{Script_Extensions=Ol_Chiki}) (48)
+\&   \ep{Script: Old_Hungarian} \ep{Script_Extensions=Old_Hungarian}
+\&                             (Short: \ep{Sc=Hung}, \ep{Hung}) (108)
+\&   \ep{Script: Old_Italic}  \ep{Script_Extensions=Old_Italic} (Short:
+\&                             \ep{Sc=Ital}, \ep{Ital}) (39)
+\&   \ep{Script: Old_North_Arabian} \ep{Script_Extensions=
+\&                             Old_North_Arabian} (Short: \ep{Sc=Narb},
+\&                             \ep{Narb}) (32)
+\&   \ep{Script: Old_Permic}  (Short: \ep{Sc=Perm}) (43: U+10350..1037A)
+\&   \ep{Script: Old_Persian} \ep{Script_Extensions=Old_Persian} (Short:
+\&                             \ep{Sc=Xpeo}, \ep{Xpeo}) (50)
+\&   \ep{Script: Old_Sogdian} \ep{Script_Extensions=Old_Sogdian} (Short:
+\&                             \ep{Sc=Sogo}, \ep{Sogo}) (40)
+\&   \ep{Script: Old_South_Arabian} \ep{Script_Extensions=
+\&                             Old_South_Arabian} (Short: \ep{Sc=Sarb},
+\&                             \ep{Sarb}) (32)
+\&   \ep{Script: Old_Turkic}  \ep{Script_Extensions=Old_Turkic} (Short:
+\&                             \ep{Sc=Orkh}, \ep{Orkh}) (73)
+\&   \ep{Script: Old_Uyghur}  (Short: \ep{Sc=Ougr}) (26: U+10F70..10F89)
+\&   \ep{Script: Oriya}       (Short: \ep{Sc=Orya}) (91: U+0B01..0B03,
+\&                             U+0B05..0B0C, U+0B0F..0B10,
+\&                             U+0B13..0B28, U+0B2A..0B30, U+0B32..0B33
+\&                             ...)
+\&   \ep{Script: Orkh}        \ep{Script=Old_Turkic} (=
+\&                             \ep{Script_Extensions=Old_Turkic}) (73)
+\&   \ep{Script: Orya}        \ep{Script=Oriya} (91)
+\&   \ep{Script: Osage}       \ep{Script_Extensions=Osage} (Short: \ep{Sc=
+\&                             Osge}, \ep{Osge}) (72)
+\&   \ep{Script: Osge}        \ep{Script=Osage} (= \ep{Script_Extensions=
+\&                             Osage}) (72)
+\&   \ep{Script: Osma}        \ep{Script=Osmanya} (=
+\&                             \ep{Script_Extensions=Osmanya}) (40)
+\&   \ep{Script: Osmanya}     \ep{Script_Extensions=Osmanya} (Short:
+\&                             \ep{Sc=Osma}, \ep{Osma}) (40)
+\&   \ep{Script: Ougr}        \ep{Script=Old_Uyghur} (26)
+\&   \ep{Script: Pahawh_Hmong} \ep{Script_Extensions=Pahawh_Hmong}
+\&                             (Short: \ep{Sc=Hmng}, \ep{Hmng}) (127)
+\&   \ep{Script: Palm}        \ep{Script=Palmyrene} (=
+\&                             \ep{Script_Extensions=Palmyrene}) (32)
+\&   \ep{Script: Palmyrene}   \ep{Script_Extensions=Palmyrene} (Short:
+\&                             \ep{Sc=Palm}, \ep{Palm}) (32)
+\&   \ep{Script: Pau_Cin_Hau} \ep{Script_Extensions=Pau_Cin_Hau} (Short:
+\&                             \ep{Sc=Pauc}, \ep{Pauc}) (57)
+\&   \ep{Script: Pauc}        \ep{Script=Pau_Cin_Hau} (=
+\&                             \ep{Script_Extensions=Pau_Cin_Hau}) (57)
+\&   \ep{Script: Perm}        \ep{Script=Old_Permic} (43)
+\&   \ep{Script: Phag}        \ep{Script=Phags_Pa} (56)
+\&   \ep{Script: Phags_Pa}    (Short: \ep{Sc=Phag}) (56: U+A840..A877)
+\&   \ep{Script: Phli}        \ep{Script=Inscriptional_Pahlavi} (=
+\&                             \ep{Script_Extensions=
+\&                             Inscriptional_Pahlavi}) (27)
+\&   \ep{Script: Phlp}        \ep{Script=Psalter_Pahlavi} (29)
+\&   \ep{Script: Phnx}        \ep{Script=Phoenician} (=
+\&                             \ep{Script_Extensions=Phoenician}) (29)
+\&   \ep{Script: Phoenician}  \ep{Script_Extensions=Phoenician} (Short:
+\&                             \ep{Sc=Phnx}, \ep{Phnx}) (29)
+\&   \ep{Script: Plrd}        \ep{Script=Miao} (= \ep{Script_Extensions=
+\&                             Miao}) (149)
+\&   \ep{Script: Prti}        \ep{Script=Inscriptional_Parthian} (=
+\&                             \ep{Script_Extensions=
+\&                             Inscriptional_Parthian}) (30)
+\&   \ep{Script: Psalter_Pahlavi} (Short: \ep{Sc=Phlp}) (29:
+\&                             U+10B80..10B91, U+10B99..10B9C,
+\&                             U+10BA9..10BAF)
+\&   \ep{Script: Qaac}        \ep{Script=Coptic} (137)
+\&   \ep{Script: Qaai}        \ep{Script=Inherited} (657)
+\&   \ep{Script: Rejang}      \ep{Script_Extensions=Rejang} (Short:
+\&                             \ep{Sc=Rjng}, \ep{Rjng}) (37)
+\&   \ep{Script: Rjng}        \ep{Script=Rejang} (= \ep{Script_Extensions=
+\&                             Rejang}) (37)
+\&   \ep{Script: Rohg}        \ep{Script=Hanifi_Rohingya} (50)
+\&   \ep{Script: Runic}       \ep{Script_Extensions=Runic} (Short: \ep{Sc=
+\&                             Runr}, \ep{Runr}) (86)
+\&   \ep{Script: Runr}        \ep{Script=Runic} (= \ep{Script_Extensions=
+\&                             Runic}) (86)
+\&   \ep{Script: Samaritan}   \ep{Script_Extensions=Samaritan} (Short:
+\&                             \ep{Sc=Samr}, \ep{Samr}) (61)
+\&   \ep{Script: Samr}        \ep{Script=Samaritan} (=
+\&                             \ep{Script_Extensions=Samaritan}) (61)
+\&   \ep{Script: Sarb}        \ep{Script=Old_South_Arabian} (=
+\&                             \ep{Script_Extensions=Old_South_Arabian})
+\&                             (32)
+\&   \ep{Script: Saur}        \ep{Script=Saurashtra} (=
+\&                             \ep{Script_Extensions=Saurashtra}) (82)
+\&   \ep{Script: Saurashtra}  \ep{Script_Extensions=Saurashtra} (Short:
+\&                             \ep{Sc=Saur}, \ep{Saur}) (82)
+\&   \ep{Script: Sgnw}        \ep{Script=SignWriting} (=
+\&                             \ep{Script_Extensions=SignWriting}) (672)
+\&   \ep{Script: Sharada}     (Short: \ep{Sc=Shrd}) (96: U+11180..111DF)
+\&   \ep{Script: Shavian}     \ep{Script_Extensions=Shavian} (Short:
+\&                             \ep{Sc=Shaw}, \ep{Shaw}) (48)
+\&   \ep{Script: Shaw}        \ep{Script=Shavian} (=
+\&                             \ep{Script_Extensions=Shavian}) (48)
+\&   \ep{Script: Shrd}        \ep{Script=Sharada} (96)
+\&   \ep{Script: Sidd}        \ep{Script=Siddham} (=
+\&                             \ep{Script_Extensions=Siddham}) (92)
+\&   \ep{Script: Siddham}     \ep{Script_Extensions=Siddham} (Short:
+\&                             \ep{Sc=Sidd}, \ep{Sidd}) (92)
+\&   \ep{Script: SignWriting} \ep{Script_Extensions=SignWriting} (Short:
+\&                             \ep{Sc=Sgnw}, \ep{Sgnw}) (672)
+\&   \ep{Script: Sind}        \ep{Script=Khudawadi} (69)
+\&   \ep{Script: Sinh}        \ep{Script=Sinhala} (111)
+\&   \ep{Script: Sinhala}     (Short: \ep{Sc=Sinh}) (111: U+0D81..0D83,
+\&                             U+0D85..0D96, U+0D9A..0DB1,
+\&                             U+0DB3..0DBB, U+0DBD, U+0DC0..0DC6 ...)
+\&   \ep{Script: Sogd}        \ep{Script=Sogdian} (42)
+\&   \ep{Script: Sogdian}     (Short: \ep{Sc=Sogd}) (42: U+10F30..10F59)
+\&   \ep{Script: Sogo}        \ep{Script=Old_Sogdian} (=
+\&                             \ep{Script_Extensions=Old_Sogdian}) (40)
+\&   \ep{Script: Sora}        \ep{Script=Sora_Sompeng} (=
+\&                             \ep{Script_Extensions=Sora_Sompeng}) (35)
+\&   \ep{Script: Sora_Sompeng} \ep{Script_Extensions=Sora_Sompeng}
+\&                             (Short: \ep{Sc=Sora}, \ep{Sora}) (35)
+\&   \ep{Script: Soyo}        \ep{Script=Soyombo} (=
+\&                             \ep{Script_Extensions=Soyombo}) (83)
+\&   \ep{Script: Soyombo}     \ep{Script_Extensions=Soyombo} (Short:
+\&                             \ep{Sc=Soyo}, \ep{Soyo}) (83)
+\&   \ep{Script: Sund}        \ep{Script=Sundanese} (=
+\&                             \ep{Script_Extensions=Sundanese}) (72)
+\&   \ep{Script: Sundanese}   \ep{Script_Extensions=Sundanese} (Short:
+\&                             \ep{Sc=Sund}, \ep{Sund}) (72)
+\&   \ep{Script: Sylo}        \ep{Script=Syloti_Nagri} (45)
+\&   \ep{Script: Syloti_Nagri} (Short: \ep{Sc=Sylo}) (45: U+A800..A82C)
+\&   \ep{Script: Syrc}        \ep{Script=Syriac} (88)
+\&   \ep{Script: Syriac}      (Short: \ep{Sc=Syrc}) (88: U+0700..070D,
+\&                             U+070F..074A, U+074D..074F, U+0860..086A)
+\&   \ep{Script: Tagalog}     (Short: \ep{Sc=Tglg}) (23: U+1700..1715,
+\&                             U+171F)
+\&   \ep{Script: Tagb}        \ep{Script=Tagbanwa} (18)
+\&   \ep{Script: Tagbanwa}    (Short: \ep{Sc=Tagb}) (18: U+1760..176C,
+\&                             U+176E..1770, U+1772..1773)
+\&   \ep{Script: Tai_Le}      (Short: \ep{Sc=Tale}) (35: U+1950..196D,
+\&                             U+1970..1974)
+\&   \ep{Script: Tai_Tham}    \ep{Script_Extensions=Tai_Tham} (Short:
+\&                             \ep{Sc=Lana}, \ep{Lana}) (127)
+\&   \ep{Script: Tai_Viet}    \ep{Script_Extensions=Tai_Viet} (Short:
+\&                             \ep{Sc=Tavt}, \ep{Tavt}) (72)
+\&   \ep{Script: Takr}        \ep{Script=Takri} (68)
+\&   \ep{Script: Takri}       (Short: \ep{Sc=Takr}) (68: U+11680..116B9,
+\&                             U+116C0..116C9)
+\&   \ep{Script: Tale}        \ep{Script=Tai_Le} (35)
+\&   \ep{Script: Talu}        \ep{Script=New_Tai_Lue} (=
+\&                             \ep{Script_Extensions=New_Tai_Lue}) (83)
+\&   \ep{Script: Tamil}       (Short: \ep{Sc=Taml}) (123: U+0B82..0B83,
+\&                             U+0B85..0B8A, U+0B8E..0B90,
+\&                             U+0B92..0B95, U+0B99..0B9A, U+0B9C ...)
+\&   \ep{Script: Taml}        \ep{Script=Tamil} (123)
+\&   \ep{Script: Tang}        \ep{Script=Tangut} (= \ep{Script_Extensions=
+\&                             Tangut}) (6914)
+\&   \ep{Script: Tangsa}      \ep{Script_Extensions=Tangsa} (Short:
+\&                             \ep{Sc=Tnsa}, \ep{Tnsa}) (89)
+\&   \ep{Script: Tangut}      \ep{Script_Extensions=Tangut} (Short:
+\&                             \ep{Sc=Tang}, \ep{Tang}) (6914)
+\&   \ep{Script: Tavt}        \ep{Script=Tai_Viet} (=
+\&                             \ep{Script_Extensions=Tai_Viet}) (72)
+\&   \ep{Script: Telu}        \ep{Script=Telugu} (100)
+\&   \ep{Script: Telugu}      (Short: \ep{Sc=Telu}) (100: U+0C00..0C0C,
+\&                             U+0C0E..0C10, U+0C12..0C28,
+\&                             U+0C2A..0C39, U+0C3C..0C44, U+0C46..0C48
+\&                             ...)
+\&   \ep{Script: Tfng}        \ep{Script=Tifinagh} (=
+\&                             \ep{Script_Extensions=Tifinagh}) (59)
+\&   \ep{Script: Tglg}        \ep{Script=Tagalog} (23)
+\&   \ep{Script: Thaa}        \ep{Script=Thaana} (50)
+\&   \ep{Script: Thaana}      (Short: \ep{Sc=Thaa}) (50: U+0780..07B1)
+\&   \ep{Script: Thai}        \ep{Script_Extensions=Thai} (Short: \ep{Sc=
+\&                             Thai}, \ep{Thai}) (86)
+\&   \ep{Script: Tibetan}     \ep{Script_Extensions=Tibetan} (Short:
+\&                             \ep{Sc=Tibt}, \ep{Tibt}) (207)
+\&   \ep{Script: Tibt}        \ep{Script=Tibetan} (=
+\&                             \ep{Script_Extensions=Tibetan}) (207)
+\&   \ep{Script: Tifinagh}    \ep{Script_Extensions=Tifinagh} (Short:
+\&                             \ep{Sc=Tfng}, \ep{Tfng}) (59)
+\&   \ep{Script: Tirh}        \ep{Script=Tirhuta} (82)
+\&   \ep{Script: Tirhuta}     (Short: \ep{Sc=Tirh}) (82: U+11480..114C7,
+\&                             U+114D0..114D9)
+\&   \ep{Script: Tnsa}        \ep{Script=Tangsa} (= \ep{Script_Extensions=
+\&                             Tangsa}) (89)
+\&   \ep{Script: Toto}        \ep{Script_Extensions=Toto} (Short: \ep{Sc=
+\&                             Toto}, \ep{Toto}) (31)
+\&   \ep{Script: Ugar}        \ep{Script=Ugaritic} (=
+\&                             \ep{Script_Extensions=Ugaritic}) (31)
+\&   \ep{Script: Ugaritic}    \ep{Script_Extensions=Ugaritic} (Short:
+\&                             \ep{Sc=Ugar}, \ep{Ugar}) (31)
+\&   \ep{Script: Unknown}     \ep{Script_Extensions=Unknown} (Short:
+\&                             \ep{Sc=Zzzz}, \ep{Zzzz}) (964_861 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Script: Vai}         \ep{Script_Extensions=Vai} (Short: \ep{Sc=
+\&                             Vai}, \ep{Vai}) (300)
+\&   \ep{Script: Vaii}        \ep{Script=Vai} (= \ep{Script_Extensions=
+\&                             Vai}) (300)
+\&   \ep{Script: Vith}        \ep{Script=Vithkuqi} (=
+\&                             \ep{Script_Extensions=Vithkuqi}) (70)
+\&   \ep{Script: Vithkuqi}    \ep{Script_Extensions=Vithkuqi} (Short:
+\&                             \ep{Sc=Vith}, \ep{Vith}) (70)
+\&   \ep{Script: Wancho}      \ep{Script_Extensions=Wancho} (Short:
+\&                             \ep{Sc=Wcho}, \ep{Wcho}) (59)
+\&   \ep{Script: Wara}        \ep{Script=Warang_Citi} (=
+\&                             \ep{Script_Extensions=Warang_Citi}) (84)
+\&   \ep{Script: Warang_Citi} \ep{Script_Extensions=Warang_Citi} (Short:
+\&                             \ep{Sc=Wara}, \ep{Wara}) (84)
+\&   \ep{Script: Wcho}        \ep{Script=Wancho} (= \ep{Script_Extensions=
+\&                             Wancho}) (59)
+\&   \ep{Script: Xpeo}        \ep{Script=Old_Persian} (=
+\&                             \ep{Script_Extensions=Old_Persian}) (50)
+\&   \ep{Script: Xsux}        \ep{Script=Cuneiform} (=
+\&                             \ep{Script_Extensions=Cuneiform}) (1234)
+\&   \ep{Script: Yezi}        \ep{Script=Yezidi} (47)
+\&   \ep{Script: Yezidi}      (Short: \ep{Sc=Yezi}) (47: U+10E80..10EA9,
+\&                             U+10EAB..10EAD, U+10EB0..10EB1)
+\&   \ep{Script: Yi}          (Short: \ep{Sc=Yi}) (1220: U+A000..A48C,
+\&                             U+A490..A4C6)
+\&   \ep{Script: Yiii}        \ep{Script=Yi} (1220)
+\&   \ep{Script: Zanabazar_Square} \ep{Script_Extensions=
+\&                             Zanabazar_Square} (Short: \ep{Sc=Zanb},
+\&                             \ep{Zanb}) (72)
+\&   \ep{Script: Zanb}        \ep{Script=Zanabazar_Square} (=
+\&                             \ep{Script_Extensions=Zanabazar_Square})
+\&                             (72)
+\&   \ep{Script: Zinh}        \ep{Script=Inherited} (657)
+\&   \ep{Script: Zyyy}        \ep{Script=Common} (8301)
+\&   \ep{Script: Zzzz}        \ep{Script=Unknown} (=
+\&                             \ep{Script_Extensions=Unknown}) (964_861
+\&                             plus all above\-Unicode code points)
+\&   \ep{Script_Extensions: Adlam} (Short: \ep{Scx=Adlm}, \ep{Adlm}) (90:
+\&                             U+061F, U+0640, U+1E900..1E94B,
+\&                             U+1E950..1E959, U+1E95E..1E95F)
+\&   \ep{Script_Extensions: Adlm} \ep{Script_Extensions=Adlam} (90)
+\&   \ep{Script_Extensions: Aghb} \ep{Script_Extensions=
+\&                             Caucasian_Albanian} (53)
+\&   \ep{Script_Extensions: Ahom} (Short: \ep{Scx=Ahom}, \ep{Ahom}) (65:
+\&                             U+11700..1171A, U+1171D..1172B,
+\&                             U+11730..11746)
+\&   \ep{Script_Extensions: Anatolian_Hieroglyphs} (Short: \ep{Scx=Hluw},
+\&                             \ep{Hluw}) (583: U+14400..14646)
+\&   \ep{Script_Extensions: Arab} \ep{Script_Extensions=Arabic} (1414)
+\&   \ep{Script_Extensions: Arabic} (Short: \ep{Scx=Arab}, \ep{Arab})
+\&                             (1414: U+0600..0604, U+0606..06DC,
+\&                             U+06DE..06FF, U+0750..077F,
+\&                             U+0870..088E, U+0890..0891 ...)
+\&   \ep{Script_Extensions: Armenian} (Short: \ep{Scx=Armn}, \ep{Armn})
+\&                             (96: U+0531..0556, U+0559..058A,
+\&                             U+058D..058F, U+FB13..FB17)
+\&   \ep{Script_Extensions: Armi} \ep{Script_Extensions=Imperial_Aramaic}
+\&                             (31)
+\&   \ep{Script_Extensions: Armn} \ep{Script_Extensions=Armenian} (96)
+\&   \ep{Script_Extensions: Avestan} (Short: \ep{Scx=Avst}, \ep{Avst})
+\&                             (61: U+10B00..10B35, U+10B39..10B3F)
+\&   \ep{Script_Extensions: Avst} \ep{Script_Extensions=Avestan} (61)
+\&   \ep{Script_Extensions: Bali} \ep{Script_Extensions=Balinese} (124)
+\&   \ep{Script_Extensions: Balinese} (Short: \ep{Scx=Bali}, \ep{Bali})
+\&                             (124: U+1B00..1B4C, U+1B50..1B7E)
+\&   \ep{Script_Extensions: Bamu} \ep{Script_Extensions=Bamum} (657)
+\&   \ep{Script_Extensions: Bamum} (Short: \ep{Scx=Bamu}, \ep{Bamu}) (657:
+\&                             U+A6A0..A6F7, U+16800..16A38)
+\&   \ep{Script_Extensions: Bass} \ep{Script_Extensions=Bassa_Vah} (36)
+\&   \ep{Script_Extensions: Bassa_Vah} (Short: \ep{Scx=Bass}, \ep{Bass})
+\&                             (36: U+16AD0..16AED, U+16AF0..16AF5)
+\&   \ep{Script_Extensions: Batak} (Short: \ep{Scx=Batk}, \ep{Batk}) (56:
+\&                             U+1BC0..1BF3, U+1BFC..1BFF)
+\&   \ep{Script_Extensions: Batk} \ep{Script_Extensions=Batak} (56)
+\&   \ep{Script_Extensions: Beng} \ep{Script_Extensions=Bengali} (113)
+\&   \ep{Script_Extensions: Bengali} (Short: \ep{Scx=Beng}, \ep{Beng})
+\&                             (113: U+0951..0952, U+0964..0965,
+\&                             U+0980..0983, U+0985..098C,
+\&                             U+098F..0990, U+0993..09A8 ...)
+\&   \ep{Script_Extensions: Bhaiksuki} (Short: \ep{Scx=Bhks}, \ep{Bhks})
+\&                             (97: U+11C00..11C08, U+11C0A..11C36,
+\&                             U+11C38..11C45, U+11C50..11C6C)
+\&   \ep{Script_Extensions: Bhks} \ep{Script_Extensions=Bhaiksuki} (97)
+\&   \ep{Script_Extensions: Bopo} \ep{Script_Extensions=Bopomofo} (117)
+\&   \ep{Script_Extensions: Bopomofo} (Short: \ep{Scx=Bopo}, \ep{Bopo})
+\&                             (117: U+02EA..02EB, U+3001..3003,
+\&                             U+3008..3011, U+3013..301F,
+\&                             U+302A..302D, U+3030 ...)
+\&   \ep{Script_Extensions: Brah} \ep{Script_Extensions=Brahmi} (115)
+\&   \ep{Script_Extensions: Brahmi} (Short: \ep{Scx=Brah}, \ep{Brah})
+\&                             (115: U+11000..1104D, U+11052..11075,
+\&                             U+1107F)
+\&   \ep{Script_Extensions: Brai} \ep{Script_Extensions=Braille} (256)
+\&   \ep{Script_Extensions: Braille} (Short: \ep{Scx=Brai}, \ep{Brai})
+\&                             (256: U+2800..28FF)
+\&   \ep{Script_Extensions: Bugi} \ep{Script_Extensions=Buginese} (31)
+\&   \ep{Script_Extensions: Buginese} (Short: \ep{Scx=Bugi}, \ep{Bugi})
+\&                             (31: U+1A00..1A1B, U+1A1E..1A1F, U+A9CF)
+\&   \ep{Script_Extensions: Buhd} \ep{Script_Extensions=Buhid} (22)
+\&   \ep{Script_Extensions: Buhid} (Short: \ep{Scx=Buhd}, \ep{Buhd}) (22:
+\&                             U+1735..1736, U+1740..1753)
+\&   \ep{Script_Extensions: Cakm} \ep{Script_Extensions=Chakma} (91)
+\&   \ep{Script_Extensions: Canadian_Aboriginal} (Short: \ep{Scx=Cans},
+\&                             \ep{Cans}) (726: U+1400..167F,
+\&                             U+18B0..18F5, U+11AB0..11ABF)
+\&   \ep{Script_Extensions: Cans} \ep{Script_Extensions=
+\&                             Canadian_Aboriginal} (726)
+\&   \ep{Script_Extensions: Cari} \ep{Script_Extensions=Carian} (49)
+\&   \ep{Script_Extensions: Carian} (Short: \ep{Scx=Cari}, \ep{Cari}) (49:
+\&                             U+102A0..102D0)
+\&   \ep{Script_Extensions: Caucasian_Albanian} (Short: \ep{Scx=Aghb},
+\&                             \ep{Aghb}) (53: U+10530..10563, U+1056F)
+\&   \ep{Script_Extensions: Chakma} (Short: \ep{Scx=Cakm}, \ep{Cakm}) (91:
+\&                             U+09E6..09EF, U+1040..1049,
+\&                             U+11100..11134, U+11136..11147)
+\&   \ep{Script_Extensions: Cham} (Short: \ep{Scx=Cham}, \ep{Cham}) (83:
+\&                             U+AA00..AA36, U+AA40..AA4D,
+\&                             U+AA50..AA59, U+AA5C..AA5F)
+\&   \ep{Script_Extensions: Cher} \ep{Script_Extensions=Cherokee} (172)
+\&   \ep{Script_Extensions: Cherokee} (Short: \ep{Scx=Cher}, \ep{Cher})
+\&                             (172: U+13A0..13F5, U+13F8..13FD,
+\&                             U+AB70..ABBF)
+\&   \ep{Script_Extensions: Chorasmian} (Short: \ep{Scx=Chrs}, \ep{Chrs})
+\&                             (28: U+10FB0..10FCB)
+\&   \ep{Script_Extensions: Chrs} \ep{Script_Extensions=Chorasmian} (28)
+\&   \ep{Script_Extensions: Common} (Short: \ep{Scx=Zyyy}, \ep{Zyyy})
+\&                             (7873: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                             \e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-\exa9
+\&                             \exab\-\exb9\exbb\-\exbf\exd7\exf7],
+\&                             U+02B9..02DF, U+02E5..02E9,
+\&                             U+02EC..02FF, U+0374, U+037E ...)
+\&   \ep{Script_Extensions: Copt} \ep{Script_Extensions=Coptic} (165)
+\&   \ep{Script_Extensions: Coptic} (Short: \ep{Scx=Copt}, \ep{Copt})
+\&                             (165: U+03E2..03EF, U+2C80..2CF3,
+\&                             U+2CF9..2CFF, U+102E0..102FB)
+\&   \ep{Script_Extensions: Cpmn} \ep{Script_Extensions=Cypro_Minoan}
+\&                             (101)
+\&   \ep{Script_Extensions: Cprt} \ep{Script_Extensions=Cypriot} (112)
+\&   \ep{Script_Extensions: Cuneiform} (Short: \ep{Scx=Xsux}, \ep{Xsux})
+\&                             (1234: U+12000..12399, U+12400..1246E,
+\&                             U+12470..12474, U+12480..12543)
+\&   \ep{Script_Extensions: Cypriot} (Short: \ep{Scx=Cprt}, \ep{Cprt})
+\&                             (112: U+10100..10102, U+10107..10133,
+\&                             U+10137..1013F, U+10800..10805, U+10808,
+\&                             U+1080A..10835 ...)
+\&   \ep{Script_Extensions: Cypro_Minoan} (Short: \ep{Scx=Cpmn},
+\&                             \ep{Cpmn}) (101: U+10100..10101,
+\&                             U+12F90..12FF2)
+\&   \ep{Script_Extensions: Cyrillic} (Short: \ep{Scx=Cyrl}, \ep{Cyrl})
+\&                             (510: U+0400..052F, U+1C80..1C88,
+\&                             U+1D2B, U+1D78, U+1DF8, U+2DE0..2DFF ...)
+\&   \ep{Script_Extensions: Cyrl} \ep{Script_Extensions=Cyrillic} (510)
+\&   \ep{Script_Extensions: Deseret} (Short: \ep{Scx=Dsrt}, \ep{Dsrt})
+\&                             (80: U+10400..1044F)
+\&   \ep{Script_Extensions: Deva} \ep{Script_Extensions=Devanagari} (220)
+\&   \ep{Script_Extensions: Devanagari} (Short: \ep{Scx=Deva}, \ep{Deva})
+\&                             (220: U+0900..0952, U+0955..097F,
+\&                             U+1CD0..1CF6, U+1CF8..1CF9, U+20F0,
+\&                             U+A830..A839 ...)
+\&   \ep{Script_Extensions: Diak} \ep{Script_Extensions=Dives_Akuru} (72)
+\&   \ep{Script_Extensions: Dives_Akuru} (Short: \ep{Scx=Diak}, \ep{Diak})
+\&                             (72: U+11900..11906, U+11909,
+\&                             U+1190C..11913, U+11915..11916,
+\&                             U+11918..11935, U+11937..11938 ...)
+\&   \ep{Script_Extensions: Dogr} \ep{Script_Extensions=Dogra} (82)
+\&   \ep{Script_Extensions: Dogra} (Short: \ep{Scx=Dogr}, \ep{Dogr}) (82:
+\&                             U+0964..096F, U+A830..A839,
+\&                             U+11800..1183B)
+\&   \ep{Script_Extensions: Dsrt} \ep{Script_Extensions=Deseret} (80)
+\&   \ep{Script_Extensions: Dupl} \ep{Script_Extensions=Duployan} (147)
+\&   \ep{Script_Extensions: Duployan} (Short: \ep{Scx=Dupl}, \ep{Dupl})
+\&                             (147: U+1BC00..1BC6A, U+1BC70..1BC7C,
+\&                             U+1BC80..1BC88, U+1BC90..1BC99,
+\&                             U+1BC9C..1BCA3)
+\&   \ep{Script_Extensions: Egyp} \ep{Script_Extensions=
+\&                             Egyptian_Hieroglyphs} (1110)
+\&   \ep{Script_Extensions: Egyptian_Hieroglyphs} (Short: \ep{Scx=Egyp},
+\&                             \ep{Egyp}) (1110: U+13000..13455)
+\&   \ep{Script_Extensions: Elba} \ep{Script_Extensions=Elbasan} (40)
+\&   \ep{Script_Extensions: Elbasan} (Short: \ep{Scx=Elba}, \ep{Elba})
+\&                             (40: U+10500..10527)
+\&   \ep{Script_Extensions: Elym} \ep{Script_Extensions=Elymaic} (23)
+\&   \ep{Script_Extensions: Elymaic} (Short: \ep{Scx=Elym}, \ep{Elym})
+\&                             (23: U+10FE0..10FF6)
+\&   \ep{Script_Extensions: Ethi} \ep{Script_Extensions=Ethiopic} (523)
+\&   \ep{Script_Extensions: Ethiopic} (Short: \ep{Scx=Ethi}, \ep{Ethi})
+\&                             (523: U+1200..1248, U+124A..124D,
+\&                             U+1250..1256, U+1258, U+125A..125D,
+\&                             U+1260..1288 ...)
+\&   \ep{Script_Extensions: Geor} \ep{Script_Extensions=Georgian} (174)
+\&   \ep{Script_Extensions: Georgian} (Short: \ep{Scx=Geor}, \ep{Geor})
+\&                             (174: U+10A0..10C5, U+10C7, U+10CD,
+\&                             U+10D0..10FF, U+1C90..1CBA, U+1CBD..1CBF
+\&                             ...)
+\&   \ep{Script_Extensions: Glag} \ep{Script_Extensions=Glagolitic} (138)
+\&   \ep{Script_Extensions: Glagolitic} (Short: \ep{Scx=Glag}, \ep{Glag})
+\&                             (138: U+0484, U+0487, U+2C00..2C5F,
+\&                             U+2E43, U+A66F, U+1E000..1E006 ...)
+\&   \ep{Script_Extensions: Gong} \ep{Script_Extensions=Gunjala_Gondi}
+\&                             (65)
+\&   \ep{Script_Extensions: Gonm} \ep{Script_Extensions=Masaram_Gondi}
+\&                             (77)
+\&   \ep{Script_Extensions: Goth} \ep{Script_Extensions=Gothic} (27)
+\&   \ep{Script_Extensions: Gothic} (Short: \ep{Scx=Goth}, \ep{Goth}) (27:
+\&                             U+10330..1034A)
+\&   \ep{Script_Extensions: Gran} \ep{Script_Extensions=Grantha} (116)
+\&   \ep{Script_Extensions: Grantha} (Short: \ep{Scx=Gran}, \ep{Gran})
+\&                             (116: U+0951..0952, U+0964..0965,
+\&                             U+0BE6..0BF3, U+1CD0, U+1CD2..1CD3,
+\&                             U+1CF2..1CF4 ...)
+\&   \ep{Script_Extensions: Greek} (Short: \ep{Scx=Grek}, \ep{Grek}) (522:
+\&                             U+0342, U+0345, U+0370..0373,
+\&                             U+0375..0377, U+037A..037D, U+037F ...)
+\&   \ep{Script_Extensions: Grek} \ep{Script_Extensions=Greek} (522)
+\&   \ep{Script_Extensions: Gujarati} (Short: \ep{Scx=Gujr}, \ep{Gujr})
+\&                             (105: U+0951..0952, U+0964..0965,
+\&                             U+0A81..0A83, U+0A85..0A8D,
+\&                             U+0A8F..0A91, U+0A93..0AA8 ...)
+\&   \ep{Script_Extensions: Gujr} \ep{Script_Extensions=Gujarati} (105)
+\&   \ep{Script_Extensions: Gunjala_Gondi} (Short: \ep{Scx=Gong},
+\&                             \ep{Gong}) (65: U+0964..0965,
+\&                             U+11D60..11D65, U+11D67..11D68,
+\&                             U+11D6A..11D8E, U+11D90..11D91,
+\&                             U+11D93..11D98 ...)
+\&   \ep{Script_Extensions: Gurmukhi} (Short: \ep{Scx=Guru}, \ep{Guru})
+\&                             (94: U+0951..0952, U+0964..0965,
+\&                             U+0A01..0A03, U+0A05..0A0A,
+\&                             U+0A0F..0A10, U+0A13..0A28 ...)
+\&   \ep{Script_Extensions: Guru} \ep{Script_Extensions=Gurmukhi} (94)
+\&   \ep{Script_Extensions: Han} (Short: \ep{Scx=Han}, \ep{Han}) (98_696:
+\&                             U+2E80..2E99, U+2E9B..2EF3,
+\&                             U+2F00..2FD5, U+3001..3003,
+\&                             U+3005..3011, U+3013..301F ...)
+\&   \ep{Script_Extensions: Hang} \ep{Script_Extensions=Hangul} (11_775)
+\&   \ep{Script_Extensions: Hangul} (Short: \ep{Scx=Hang}, \ep{Hang})
+\&                             (11_775: U+1100..11FF, U+3001..3003,
+\&                             U+3008..3011, U+3013..301F,
+\&                             U+302E..3030, U+3037 ...)
+\&   \ep{Script_Extensions: Hani} \ep{Script_Extensions=Han} (98_696)
+\&   \ep{Script_Extensions: Hanifi_Rohingya} (Short: \ep{Scx=Rohg},
+\&                             \ep{Rohg}) (55: U+060C, U+061B, U+061F,
+\&                             U+0640, U+06D4, U+10D00..10D27 ...)
+\&   \ep{Script_Extensions: Hano} \ep{Script_Extensions=Hanunoo} (23)
+\&   \ep{Script_Extensions: Hanunoo} (Short: \ep{Scx=Hano}, \ep{Hano})
+\&                             (23: U+1720..1736)
+\&   \ep{Script_Extensions: Hatr} \ep{Script_Extensions=Hatran} (26)
+\&   \ep{Script_Extensions: Hatran} (Short: \ep{Scx=Hatr}, \ep{Hatr}) (26:
+\&                             U+108E0..108F2, U+108F4..108F5,
+\&                             U+108FB..108FF)
+\&   \ep{Script_Extensions: Hebr} \ep{Script_Extensions=Hebrew} (134)
+\&   \ep{Script_Extensions: Hebrew} (Short: \ep{Scx=Hebr}, \ep{Hebr})
+\&                             (134: U+0591..05C7, U+05D0..05EA,
+\&                             U+05EF..05F4, U+FB1D..FB36,
+\&                             U+FB38..FB3C, U+FB3E ...)
+\&   \ep{Script_Extensions: Hira} \ep{Script_Extensions=Hiragana} (433)
+\&   \ep{Script_Extensions: Hiragana} (Short: \ep{Scx=Hira}, \ep{Hira})
+\&                             (433: U+3001..3003, U+3008..3011,
+\&                             U+3013..301F, U+3030..3035, U+3037,
+\&                             U+303C..303D ...)
+\&   \ep{Script_Extensions: Hluw} \ep{Script_Extensions=
+\&                             Anatolian_Hieroglyphs} (583)
+\&   \ep{Script_Extensions: Hmng} \ep{Script_Extensions=Pahawh_Hmong}
+\&                             (127)
+\&   \ep{Script_Extensions: Hmnp} \ep{Script_Extensions=
+\&                             Nyiakeng_Puachue_Hmong} (71)
+\&   \ep{Script_Extensions: Hung} \ep{Script_Extensions=Old_Hungarian}
+\&                             (108)
+\&   \ep{Script_Extensions: Imperial_Aramaic} (Short: \ep{Scx=Armi},
+\&                             \ep{Armi}) (31: U+10840..10855,
+\&                             U+10857..1085F)
+\&   \ep{Script_Extensions: Inherited} (Short: \ep{Scx=Zinh}, \ep{Zinh})
+\&                             (586: U+0300..0341, U+0343..0344,
+\&                             U+0346..0362, U+0953..0954,
+\&                             U+1AB0..1ACE, U+1DC2..1DF7 ...)
+\&   \ep{Script_Extensions: Inscriptional_Pahlavi} (Short: \ep{Scx=Phli},
+\&                             \ep{Phli}) (27: U+10B60..10B72,
+\&                             U+10B78..10B7F)
+\&   \ep{Script_Extensions: Inscriptional_Parthian} (Short: \ep{Scx=
+\&                             Prti}, \ep{Prti}) (30: U+10B40..10B55,
+\&                             U+10B58..10B5F)
+\&   \ep{Script_Extensions: Ital} \ep{Script_Extensions=Old_Italic} (39)
+\&   \ep{Script_Extensions: Java} \ep{Script_Extensions=Javanese} (91)
+\&   \ep{Script_Extensions: Javanese} (Short: \ep{Scx=Java}, \ep{Java})
+\&                             (91: U+A980..A9CD, U+A9CF..A9D9,
+\&                             U+A9DE..A9DF)
+\&   \ep{Script_Extensions: Kaithi} (Short: \ep{Scx=Kthi}, \ep{Kthi}) (88:
+\&                             U+0966..096F, U+A830..A839,
+\&                             U+11080..110C2, U+110CD)
+\&   \ep{Script_Extensions: Kali} \ep{Script_Extensions=Kayah_Li} (48)
+\&   \ep{Script_Extensions: Kana} \ep{Script_Extensions=Katakana} (373)
+\&   \ep{Script_Extensions: Kannada} (Short: \ep{Scx=Knda}, \ep{Knda})
+\&                             (106: U+0951..0952, U+0964..0965,
+\&                             U+0C80..0C8C, U+0C8E..0C90,
+\&                             U+0C92..0CA8, U+0CAA..0CB3 ...)
+\&   \ep{Script_Extensions: Katakana} (Short: \ep{Scx=Kana}, \ep{Kana})
+\&                             (373: U+3001..3003, U+3008..3011,
+\&                             U+3013..301F, U+3030..3035, U+3037,
+\&                             U+303C..303D ...)
+\&   \ep{Script_Extensions: Kawi} (Short: \ep{Scx=Kawi}, \ep{Kawi}) (86:
+\&                             U+11F00..11F10, U+11F12..11F3A,
+\&                             U+11F3E..11F59)
+\&   \ep{Script_Extensions: Kayah_Li} (Short: \ep{Scx=Kali}, \ep{Kali})
+\&                             (48: U+A900..A92F)
+\&   \ep{Script_Extensions: Khar} \ep{Script_Extensions=Kharoshthi} (68)
+\&   \ep{Script_Extensions: Kharoshthi} (Short: \ep{Scx=Khar}, \ep{Khar})
+\&                             (68: U+10A00..10A03, U+10A05..10A06,
+\&                             U+10A0C..10A13, U+10A15..10A17,
+\&                             U+10A19..10A35, U+10A38..10A3A ...)
+\&   \ep{Script_Extensions: Khitan_Small_Script} (Short: \ep{Scx=Kits},
+\&                             \ep{Kits}) (471: U+16FE4, U+18B00..18CD5)
+\&   \ep{Script_Extensions: Khmer} (Short: \ep{Scx=Khmr}, \ep{Khmr}) (146:
+\&                             U+1780..17DD, U+17E0..17E9,
+\&                             U+17F0..17F9, U+19E0..19FF)
+\&   \ep{Script_Extensions: Khmr} \ep{Script_Extensions=Khmer} (146)
+\&   \ep{Script_Extensions: Khoj} \ep{Script_Extensions=Khojki} (85)
+\&   \ep{Script_Extensions: Khojki} (Short: \ep{Scx=Khoj}, \ep{Khoj}) (85:
+\&                             U+0AE6..0AEF, U+A830..A839,
+\&                             U+11200..11211, U+11213..11241)
+\&   \ep{Script_Extensions: Khudawadi} (Short: \ep{Scx=Sind}, \ep{Sind})
+\&                             (81: U+0964..0965, U+A830..A839,
+\&                             U+112B0..112EA, U+112F0..112F9)
+\&   \ep{Script_Extensions: Kits} \ep{Script_Extensions=
+\&                             Khitan_Small_Script} (471)
+\&   \ep{Script_Extensions: Knda} \ep{Script_Extensions=Kannada} (106)
+\&   \ep{Script_Extensions: Kthi} \ep{Script_Extensions=Kaithi} (88)
+\&   \ep{Script_Extensions: Lana} \ep{Script_Extensions=Tai_Tham} (127)
+\&   \ep{Script_Extensions: Lao} (Short: \ep{Scx=Lao}, \ep{Lao}) (83:
+\&                             U+0E81..0E82, U+0E84, U+0E86..0E8A,
+\&                             U+0E8C..0EA3, U+0EA5, U+0EA7..0EBD ...)
+\&   \ep{Script_Extensions: Laoo} \ep{Script_Extensions=Lao} (83)
+\&   \ep{Script_Extensions: Latin} (Short: \ep{Scx=Latn}, \ep{Latn})
+\&                             (1510: [A\-Za\-z\exaa\exba\exc0\-\exd6\exd8\-
+\&                             \exf6\exf8\-\exff], U+0100..02B8,
+\&                             U+02E0..02E4, U+0363..036F,
+\&                             U+0485..0486, U+0951..0952 ...)
+\&   \ep{Script_Extensions: Latn} \ep{Script_Extensions=Latin} (1510)
+\&   \ep{Script_Extensions: Lepc} \ep{Script_Extensions=Lepcha} (74)
+\&   \ep{Script_Extensions: Lepcha} (Short: \ep{Scx=Lepc}, \ep{Lepc}) (74:
+\&                             U+1C00..1C37, U+1C3B..1C49, U+1C4D..1C4F)
+\&   \ep{Script_Extensions: Limb} \ep{Script_Extensions=Limbu} (69)
+\&   \ep{Script_Extensions: Limbu} (Short: \ep{Scx=Limb}, \ep{Limb}) (69:
+\&                             U+0965, U+1900..191E, U+1920..192B,
+\&                             U+1930..193B, U+1940, U+1944..194F)
+\&   \ep{Script_Extensions: Lina} \ep{Script_Extensions=Linear_A} (386)
+\&   \ep{Script_Extensions: Linb} \ep{Script_Extensions=Linear_B} (268)
+\&   \ep{Script_Extensions: Linear_A} (Short: \ep{Scx=Lina}, \ep{Lina})
+\&                             (386: U+10107..10133, U+10600..10736,
+\&                             U+10740..10755, U+10760..10767)
+\&   \ep{Script_Extensions: Linear_B} (Short: \ep{Scx=Linb}, \ep{Linb})
+\&                             (268: U+10000..1000B, U+1000D..10026,
+\&                             U+10028..1003A, U+1003C..1003D,
+\&                             U+1003F..1004D, U+10050..1005D ...)
+\&   \ep{Script_Extensions: Lisu} (Short: \ep{Scx=Lisu}, \ep{Lisu}) (49:
+\&                             U+A4D0..A4FF, U+11FB0)
+\&   \ep{Script_Extensions: Lyci} \ep{Script_Extensions=Lycian} (29)
+\&   \ep{Script_Extensions: Lycian} (Short: \ep{Scx=Lyci}, \ep{Lyci}) (29:
+\&                             U+10280..1029C)
+\&   \ep{Script_Extensions: Lydi} \ep{Script_Extensions=Lydian} (27)
+\&   \ep{Script_Extensions: Lydian} (Short: \ep{Scx=Lydi}, \ep{Lydi}) (27:
+\&                             U+10920..10939, U+1093F)
+\&   \ep{Script_Extensions: Mahajani} (Short: \ep{Scx=Mahj}, \ep{Mahj})
+\&                             (61: U+0964..096F, U+A830..A839,
+\&                             U+11150..11176)
+\&   \ep{Script_Extensions: Mahj} \ep{Script_Extensions=Mahajani} (61)
+\&   \ep{Script_Extensions: Maka} \ep{Script_Extensions=Makasar} (25)
+\&   \ep{Script_Extensions: Makasar} (Short: \ep{Scx=Maka}, \ep{Maka})
+\&                             (25: U+11EE0..11EF8)
+\&   \ep{Script_Extensions: Malayalam} (Short: \ep{Scx=Mlym}, \ep{Mlym})
+\&                             (126: U+0951..0952, U+0964..0965,
+\&                             U+0D00..0D0C, U+0D0E..0D10,
+\&                             U+0D12..0D44, U+0D46..0D48 ...)
+\&   \ep{Script_Extensions: Mand} \ep{Script_Extensions=Mandaic} (30)
+\&   \ep{Script_Extensions: Mandaic} (Short: \ep{Scx=Mand}, \ep{Mand})
+\&                             (30: U+0640, U+0840..085B, U+085E)
+\&   \ep{Script_Extensions: Mani} \ep{Script_Extensions=Manichaean} (52)
+\&   \ep{Script_Extensions: Manichaean} (Short: \ep{Scx=Mani}, \ep{Mani})
+\&                             (52: U+0640, U+10AC0..10AE6,
+\&                             U+10AEB..10AF6)
+\&   \ep{Script_Extensions: Marc} \ep{Script_Extensions=Marchen} (68)
+\&   \ep{Script_Extensions: Marchen} (Short: \ep{Scx=Marc}, \ep{Marc})
+\&                             (68: U+11C70..11C8F, U+11C92..11CA7,
+\&                             U+11CA9..11CB6)
+\&   \ep{Script_Extensions: Masaram_Gondi} (Short: \ep{Scx=Gonm},
+\&                             \ep{Gonm}) (77: U+0964..0965,
+\&                             U+11D00..11D06, U+11D08..11D09,
+\&                             U+11D0B..11D36, U+11D3A, U+11D3C..11D3D
+\&                             ...)
+\&   \ep{Script_Extensions: Medefaidrin} (Short: \ep{Scx=Medf}, \ep{Medf})
+\&                             (91: U+16E40..16E9A)
+\&   \ep{Script_Extensions: Medf} \ep{Script_Extensions=Medefaidrin} (91)
+\&   \ep{Script_Extensions: Meetei_Mayek} (Short: \ep{Scx=Mtei},
+\&                             \ep{Mtei}) (79: U+AAE0..AAF6,
+\&                             U+ABC0..ABED, U+ABF0..ABF9)
+\&   \ep{Script_Extensions: Mend} \ep{Script_Extensions=Mende_Kikakui}
+\&                             (213)
+\&   \ep{Script_Extensions: Mende_Kikakui} (Short: \ep{Scx=Mend},
+\&                             \ep{Mend}) (213: U+1E800..1E8C4,
+\&                             U+1E8C7..1E8D6)
+\&   \ep{Script_Extensions: Merc} \ep{Script_Extensions=Meroitic_Cursive}
+\&                             (90)
+\&   \ep{Script_Extensions: Mero} \ep{Script_Extensions=
+\&                             Meroitic_Hieroglyphs} (32)
+\&   \ep{Script_Extensions: Meroitic_Cursive} (Short: \ep{Scx=Merc},
+\&                             \ep{Merc}) (90: U+109A0..109B7,
+\&                             U+109BC..109CF, U+109D2..109FF)
+\&   \ep{Script_Extensions: Meroitic_Hieroglyphs} (Short: \ep{Scx=Mero},
+\&                             \ep{Mero}) (32: U+10980..1099F)
+\&   \ep{Script_Extensions: Miao} (Short: \ep{Scx=Miao}, \ep{Miao}) (149:
+\&                             U+16F00..16F4A, U+16F4F..16F87,
+\&                             U+16F8F..16F9F)
+\&   \ep{Script_Extensions: Mlym} \ep{Script_Extensions=Malayalam} (126)
+\&   \ep{Script_Extensions: Modi} (Short: \ep{Scx=Modi}, \ep{Modi}) (89:
+\&                             U+A830..A839, U+11600..11644,
+\&                             U+11650..11659)
+\&   \ep{Script_Extensions: Mong} \ep{Script_Extensions=Mongolian} (172)
+\&   \ep{Script_Extensions: Mongolian} (Short: \ep{Scx=Mong}, \ep{Mong})
+\&                             (172: U+1800..1819, U+1820..1878,
+\&                             U+1880..18AA, U+202F, U+11660..1166C)
+\&   \ep{Script_Extensions: Mro} (Short: \ep{Scx=Mro}, \ep{Mro}) (43:
+\&                             U+16A40..16A5E, U+16A60..16A69,
+\&                             U+16A6E..16A6F)
+\&   \ep{Script_Extensions: Mroo} \ep{Script_Extensions=Mro} (43)
+\&   \ep{Script_Extensions: Mtei} \ep{Script_Extensions=Meetei_Mayek} (79)
+\&   \ep{Script_Extensions: Mult} \ep{Script_Extensions=Multani} (48)
+\&   \ep{Script_Extensions: Multani} (Short: \ep{Scx=Mult}, \ep{Mult})
+\&                             (48: U+0A66..0A6F, U+11280..11286,
+\&                             U+11288, U+1128A..1128D, U+1128F..1129D,
+\&                             U+1129F..112A9)
+\&   \ep{Script_Extensions: Myanmar} (Short: \ep{Scx=Mymr}, \ep{Mymr})
+\&                             (224: U+1000..109F, U+A92E,
+\&                             U+A9E0..A9FE, U+AA60..AA7F)
+\&   \ep{Script_Extensions: Mymr} \ep{Script_Extensions=Myanmar} (224)
+\&   \ep{Script_Extensions: Nabataean} (Short: \ep{Scx=Nbat}, \ep{Nbat})
+\&                             (40: U+10880..1089E, U+108A7..108AF)
+\&   \ep{Script_Extensions: Nag_Mundari} (Short: \ep{Scx=Nagm}, \ep{Nagm})
+\&                             (42: U+1E4D0..1E4F9)
+\&   \ep{Script_Extensions: Nagm} \ep{Script_Extensions=Nag_Mundari} (42)
+\&   \ep{Script_Extensions: Nand} \ep{Script_Extensions=Nandinagari} (86)
+\&   \ep{Script_Extensions: Nandinagari} (Short: \ep{Scx=Nand}, \ep{Nand})
+\&                             (86: U+0964..0965, U+0CE6..0CEF, U+1CE9,
+\&                             U+1CF2, U+1CFA, U+A830..A835 ...)
+\&   \ep{Script_Extensions: Narb} \ep{Script_Extensions=
+\&                             Old_North_Arabian} (32)
+\&   \ep{Script_Extensions: Nbat} \ep{Script_Extensions=Nabataean} (40)
+\&   \ep{Script_Extensions: New_Tai_Lue} (Short: \ep{Scx=Talu}, \ep{Talu})
+\&                             (83: U+1980..19AB, U+19B0..19C9,
+\&                             U+19D0..19DA, U+19DE..19DF)
+\&   \ep{Script_Extensions: Newa} (Short: \ep{Scx=Newa}, \ep{Newa}) (97:
+\&                             U+11400..1145B, U+1145D..11461)
+\&   \ep{Script_Extensions: Nko} (Short: \ep{Scx=Nko}, \ep{Nko}) (67:
+\&                             U+060C, U+061B, U+061F, U+07C0..07FA,
+\&                             U+07FD..07FF, U+FD3E..FD3F)
+\&   \ep{Script_Extensions: Nkoo} \ep{Script_Extensions=Nko} (67)
+\&   \ep{Script_Extensions: Nshu} \ep{Script_Extensions=Nushu} (397)
+\&   \ep{Script_Extensions: Nushu} (Short: \ep{Scx=Nshu}, \ep{Nshu}) (397:
+\&                             U+16FE1, U+1B170..1B2FB)
+\&   \ep{Script_Extensions: Nyiakeng_Puachue_Hmong} (Short: \ep{Scx=
+\&                             Hmnp}, \ep{Hmnp}) (71: U+1E100..1E12C,
+\&                             U+1E130..1E13D, U+1E140..1E149,
+\&                             U+1E14E..1E14F)
+\&   \ep{Script_Extensions: Ogam} \ep{Script_Extensions=Ogham} (29)
+\&   \ep{Script_Extensions: Ogham} (Short: \ep{Scx=Ogam}, \ep{Ogam}) (29:
+\&                             U+1680..169C)
+\&   \ep{Script_Extensions: Ol_Chiki} (Short: \ep{Scx=Olck}, \ep{Olck})
+\&                             (48: U+1C50..1C7F)
+\&   \ep{Script_Extensions: Olck} \ep{Script_Extensions=Ol_Chiki} (48)
+\&   \ep{Script_Extensions: Old_Hungarian} (Short: \ep{Scx=Hung},
+\&                             \ep{Hung}) (108: U+10C80..10CB2,
+\&                             U+10CC0..10CF2, U+10CFA..10CFF)
+\&   \ep{Script_Extensions: Old_Italic} (Short: \ep{Scx=Ital}, \ep{Ital})
+\&                             (39: U+10300..10323, U+1032D..1032F)
+\&   \ep{Script_Extensions: Old_North_Arabian} (Short: \ep{Scx=Narb},
+\&                             \ep{Narb}) (32: U+10A80..10A9F)
+\&   \ep{Script_Extensions: Old_Permic} (Short: \ep{Scx=Perm}, \ep{Perm})
+\&                             (44: U+0483, U+10350..1037A)
+\&   \ep{Script_Extensions: Old_Persian} (Short: \ep{Scx=Xpeo}, \ep{Xpeo})
+\&                             (50: U+103A0..103C3, U+103C8..103D5)
+\&   \ep{Script_Extensions: Old_Sogdian} (Short: \ep{Scx=Sogo}, \ep{Sogo})
+\&                             (40: U+10F00..10F27)
+\&   \ep{Script_Extensions: Old_South_Arabian} (Short: \ep{Scx=Sarb},
+\&                             \ep{Sarb}) (32: U+10A60..10A7F)
+\&   \ep{Script_Extensions: Old_Turkic} (Short: \ep{Scx=Orkh}, \ep{Orkh})
+\&                             (73: U+10C00..10C48)
+\&   \ep{Script_Extensions: Old_Uyghur} (Short: \ep{Scx=Ougr}, \ep{Ougr})
+\&                             (28: U+0640, U+10AF2, U+10F70..10F89)
+\&   \ep{Script_Extensions: Oriya} (Short: \ep{Scx=Orya}, \ep{Orya}) (97:
+\&                             U+0951..0952, U+0964..0965,
+\&                             U+0B01..0B03, U+0B05..0B0C,
+\&                             U+0B0F..0B10, U+0B13..0B28 ...)
+\&   \ep{Script_Extensions: Orkh} \ep{Script_Extensions=Old_Turkic} (73)
+\&   \ep{Script_Extensions: Orya} \ep{Script_Extensions=Oriya} (97)
+\&   \ep{Script_Extensions: Osage} (Short: \ep{Scx=Osge}, \ep{Osge}) (72:
+\&                             U+104B0..104D3, U+104D8..104FB)
+\&   \ep{Script_Extensions: Osge} \ep{Script_Extensions=Osage} (72)
+\&   \ep{Script_Extensions: Osma} \ep{Script_Extensions=Osmanya} (40)
+\&   \ep{Script_Extensions: Osmanya} (Short: \ep{Scx=Osma}, \ep{Osma})
+\&                             (40: U+10480..1049D, U+104A0..104A9)
+\&   \ep{Script_Extensions: Ougr} \ep{Script_Extensions=Old_Uyghur} (28)
+\&   \ep{Script_Extensions: Pahawh_Hmong} (Short: \ep{Scx=Hmng},
+\&                             \ep{Hmng}) (127: U+16B00..16B45,
+\&                             U+16B50..16B59, U+16B5B..16B61,
+\&                             U+16B63..16B77, U+16B7D..16B8F)
+\&   \ep{Script_Extensions: Palm} \ep{Script_Extensions=Palmyrene} (32)
+\&   \ep{Script_Extensions: Palmyrene} (Short: \ep{Scx=Palm}, \ep{Palm})
+\&                             (32: U+10860..1087F)
+\&   \ep{Script_Extensions: Pau_Cin_Hau} (Short: \ep{Scx=Pauc}, \ep{Pauc})
+\&                             (57: U+11AC0..11AF8)
+\&   \ep{Script_Extensions: Pauc} \ep{Script_Extensions=Pau_Cin_Hau} (57)
+\&   \ep{Script_Extensions: Perm} \ep{Script_Extensions=Old_Permic} (44)
+\&   \ep{Script_Extensions: Phag} \ep{Script_Extensions=Phags_Pa} (59)
+\&   \ep{Script_Extensions: Phags_Pa} (Short: \ep{Scx=Phag}, \ep{Phag})
+\&                             (59: U+1802..1803, U+1805, U+A840..A877)
+\&   \ep{Script_Extensions: Phli} \ep{Script_Extensions=
+\&                             Inscriptional_Pahlavi} (27)
+\&   \ep{Script_Extensions: Phlp} \ep{Script_Extensions=Psalter_Pahlavi}
+\&                             (30)
+\&   \ep{Script_Extensions: Phnx} \ep{Script_Extensions=Phoenician} (29)
+\&   \ep{Script_Extensions: Phoenician} (Short: \ep{Scx=Phnx}, \ep{Phnx})
+\&                             (29: U+10900..1091B, U+1091F)
+\&   \ep{Script_Extensions: Plrd} \ep{Script_Extensions=Miao} (149)
+\&   \ep{Script_Extensions: Prti} \ep{Script_Extensions=
+\&                             Inscriptional_Parthian} (30)
+\&   \ep{Script_Extensions: Psalter_Pahlavi} (Short: \ep{Scx=Phlp},
+\&                             \ep{Phlp}) (30: U+0640, U+10B80..10B91,
+\&                             U+10B99..10B9C, U+10BA9..10BAF)
+\&   \ep{Script_Extensions: Qaac} \ep{Script_Extensions=Coptic} (165)
+\&   \ep{Script_Extensions: Qaai} \ep{Script_Extensions=Inherited} (586)
+\&   \ep{Script_Extensions: Rejang} (Short: \ep{Scx=Rjng}, \ep{Rjng}) (37:
+\&                             U+A930..A953, U+A95F)
+\&   \ep{Script_Extensions: Rjng} \ep{Script_Extensions=Rejang} (37)
+\&   \ep{Script_Extensions: Rohg} \ep{Script_Extensions=Hanifi_Rohingya}
+\&                             (55)
+\&   \ep{Script_Extensions: Runic} (Short: \ep{Scx=Runr}, \ep{Runr}) (86:
+\&                             U+16A0..16EA, U+16EE..16F8)
+\&   \ep{Script_Extensions: Runr} \ep{Script_Extensions=Runic} (86)
+\&   \ep{Script_Extensions: Samaritan} (Short: \ep{Scx=Samr}, \ep{Samr})
+\&                             (61: U+0800..082D, U+0830..083E)
+\&   \ep{Script_Extensions: Samr} \ep{Script_Extensions=Samaritan} (61)
+\&   \ep{Script_Extensions: Sarb} \ep{Script_Extensions=
+\&                             Old_South_Arabian} (32)
+\&   \ep{Script_Extensions: Saur} \ep{Script_Extensions=Saurashtra} (82)
+\&   \ep{Script_Extensions: Saurashtra} (Short: \ep{Scx=Saur}, \ep{Saur})
+\&                             (82: U+A880..A8C5, U+A8CE..A8D9)
+\&   \ep{Script_Extensions: Sgnw} \ep{Script_Extensions=SignWriting} (672)
+\&   \ep{Script_Extensions: Sharada} (Short: \ep{Scx=Shrd}, \ep{Shrd})
+\&                             (102: U+0951, U+1CD7, U+1CD9,
+\&                             U+1CDC..1CDD, U+1CE0, U+11180..111DF)
+\&   \ep{Script_Extensions: Shavian} (Short: \ep{Scx=Shaw}, \ep{Shaw})
+\&                             (48: U+10450..1047F)
+\&   \ep{Script_Extensions: Shaw} \ep{Script_Extensions=Shavian} (48)
+\&   \ep{Script_Extensions: Shrd} \ep{Script_Extensions=Sharada} (102)
+\&   \ep{Script_Extensions: Sidd} \ep{Script_Extensions=Siddham} (92)
+\&   \ep{Script_Extensions: Siddham} (Short: \ep{Scx=Sidd}, \ep{Sidd})
+\&                             (92: U+11580..115B5, U+115B8..115DD)
+\&   \ep{Script_Extensions: SignWriting} (Short: \ep{Scx=Sgnw}, \ep{Sgnw})
+\&                             (672: U+1D800..1DA8B, U+1DA9B..1DA9F,
+\&                             U+1DAA1..1DAAF)
+\&   \ep{Script_Extensions: Sind} \ep{Script_Extensions=Khudawadi} (81)
+\&   \ep{Script_Extensions: Sinh} \ep{Script_Extensions=Sinhala} (113)
+\&   \ep{Script_Extensions: Sinhala} (Short: \ep{Scx=Sinh}, \ep{Sinh})
+\&                             (113: U+0964..0965, U+0D81..0D83,
+\&                             U+0D85..0D96, U+0D9A..0DB1,
+\&                             U+0DB3..0DBB, U+0DBD ...)
+\&   \ep{Script_Extensions: Sogd} \ep{Script_Extensions=Sogdian} (43)
+\&   \ep{Script_Extensions: Sogdian} (Short: \ep{Scx=Sogd}, \ep{Sogd})
+\&                             (43: U+0640, U+10F30..10F59)
+\&   \ep{Script_Extensions: Sogo} \ep{Script_Extensions=Old_Sogdian} (40)
+\&   \ep{Script_Extensions: Sora} \ep{Script_Extensions=Sora_Sompeng} (35)
+\&   \ep{Script_Extensions: Sora_Sompeng} (Short: \ep{Scx=Sora},
+\&                             \ep{Sora}) (35: U+110D0..110E8,
+\&                             U+110F0..110F9)
+\&   \ep{Script_Extensions: Soyo} \ep{Script_Extensions=Soyombo} (83)
+\&   \ep{Script_Extensions: Soyombo} (Short: \ep{Scx=Soyo}, \ep{Soyo})
+\&                             (83: U+11A50..11AA2)
+\&   \ep{Script_Extensions: Sund} \ep{Script_Extensions=Sundanese} (72)
+\&   \ep{Script_Extensions: Sundanese} (Short: \ep{Scx=Sund}, \ep{Sund})
+\&                             (72: U+1B80..1BBF, U+1CC0..1CC7)
+\&   \ep{Script_Extensions: Sylo} \ep{Script_Extensions=Syloti_Nagri} (57)
+\&   \ep{Script_Extensions: Syloti_Nagri} (Short: \ep{Scx=Sylo},
+\&                             \ep{Sylo}) (57: U+0964..0965,
+\&                             U+09E6..09EF, U+A800..A82C)
+\&   \ep{Script_Extensions: Syrc} \ep{Script_Extensions=Syriac} (107)
+\&   \ep{Script_Extensions: Syriac} (Short: \ep{Scx=Syrc}, \ep{Syrc})
+\&                             (107: U+060C, U+061B..061C, U+061F,
+\&                             U+0640, U+064B..0655, U+0670 ...)
+\&   \ep{Script_Extensions: Tagalog} (Short: \ep{Scx=Tglg}, \ep{Tglg})
+\&                             (25: U+1700..1715, U+171F, U+1735..1736)
+\&   \ep{Script_Extensions: Tagb} \ep{Script_Extensions=Tagbanwa} (20)
+\&   \ep{Script_Extensions: Tagbanwa} (Short: \ep{Scx=Tagb}, \ep{Tagb})
+\&                             (20: U+1735..1736, U+1760..176C,
+\&                             U+176E..1770, U+1772..1773)
+\&   \ep{Script_Extensions: Tai_Le} (Short: \ep{Scx=Tale}, \ep{Tale}) (45:
+\&                             U+1040..1049, U+1950..196D, U+1970..1974)
+\&   \ep{Script_Extensions: Tai_Tham} (Short: \ep{Scx=Lana}, \ep{Lana})
+\&                             (127: U+1A20..1A5E, U+1A60..1A7C,
+\&                             U+1A7F..1A89, U+1A90..1A99, U+1AA0..1AAD)
+\&   \ep{Script_Extensions: Tai_Viet} (Short: \ep{Scx=Tavt}, \ep{Tavt})
+\&                             (72: U+AA80..AAC2, U+AADB..AADF)
+\&   \ep{Script_Extensions: Takr} \ep{Script_Extensions=Takri} (80)
+\&   \ep{Script_Extensions: Takri} (Short: \ep{Scx=Takr}, \ep{Takr}) (80:
+\&                             U+0964..0965, U+A830..A839,
+\&                             U+11680..116B9, U+116C0..116C9)
+\&   \ep{Script_Extensions: Tale} \ep{Script_Extensions=Tai_Le} (45)
+\&   \ep{Script_Extensions: Talu} \ep{Script_Extensions=New_Tai_Lue} (83)
+\&   \ep{Script_Extensions: Tamil} (Short: \ep{Scx=Taml}, \ep{Taml}) (133:
+\&                             U+0951..0952, U+0964..0965,
+\&                             U+0B82..0B83, U+0B85..0B8A,
+\&                             U+0B8E..0B90, U+0B92..0B95 ...)
+\&   \ep{Script_Extensions: Taml} \ep{Script_Extensions=Tamil} (133)
+\&   \ep{Script_Extensions: Tang} \ep{Script_Extensions=Tangut} (6914)
+\&   \ep{Script_Extensions: Tangsa} (Short: \ep{Scx=Tnsa}, \ep{Tnsa}) (89:
+\&                             U+16A70..16ABE, U+16AC0..16AC9)
+\&   \ep{Script_Extensions: Tangut} (Short: \ep{Scx=Tang}, \ep{Tang})
+\&                             (6914: U+16FE0, U+17000..187F7,
+\&                             U+18800..18AFF, U+18D00..18D08)
+\&   \ep{Script_Extensions: Tavt} \ep{Script_Extensions=Tai_Viet} (72)
+\&   \ep{Script_Extensions: Telu} \ep{Script_Extensions=Telugu} (106)
+\&   \ep{Script_Extensions: Telugu} (Short: \ep{Scx=Telu}, \ep{Telu})
+\&                             (106: U+0951..0952, U+0964..0965,
+\&                             U+0C00..0C0C, U+0C0E..0C10,
+\&                             U+0C12..0C28, U+0C2A..0C39 ...)
+\&   \ep{Script_Extensions: Tfng} \ep{Script_Extensions=Tifinagh} (59)
+\&   \ep{Script_Extensions: Tglg} \ep{Script_Extensions=Tagalog} (25)
+\&   \ep{Script_Extensions: Thaa} \ep{Script_Extensions=Thaana} (66)
+\&   \ep{Script_Extensions: Thaana} (Short: \ep{Scx=Thaa}, \ep{Thaa}) (66:
+\&                             U+060C, U+061B..061C, U+061F,
+\&                             U+0660..0669, U+0780..07B1, U+FDF2 ...)
+\&   \ep{Script_Extensions: Thai} (Short: \ep{Scx=Thai}, \ep{Thai}) (86:
+\&                             U+0E01..0E3A, U+0E40..0E5B)
+\&   \ep{Script_Extensions: Tibetan} (Short: \ep{Scx=Tibt}, \ep{Tibt})
+\&                             (207: U+0F00..0F47, U+0F49..0F6C,
+\&                             U+0F71..0F97, U+0F99..0FBC,
+\&                             U+0FBE..0FCC, U+0FCE..0FD4 ...)
+\&   \ep{Script_Extensions: Tibt} \ep{Script_Extensions=Tibetan} (207)
+\&   \ep{Script_Extensions: Tifinagh} (Short: \ep{Scx=Tfng}, \ep{Tfng})
+\&                             (59: U+2D30..2D67, U+2D6F..2D70, U+2D7F)
+\&   \ep{Script_Extensions: Tirh} \ep{Script_Extensions=Tirhuta} (97)
+\&   \ep{Script_Extensions: Tirhuta} (Short: \ep{Scx=Tirh}, \ep{Tirh})
+\&                             (97: U+0951..0952, U+0964..0965, U+1CF2,
+\&                             U+A830..A839, U+11480..114C7,
+\&                             U+114D0..114D9)
+\&   \ep{Script_Extensions: Tnsa} \ep{Script_Extensions=Tangsa} (89)
+\&   \ep{Script_Extensions: Toto} (Short: \ep{Scx=Toto}, \ep{Toto}) (31:
+\&                             U+1E290..1E2AE)
+\&   \ep{Script_Extensions: Ugar} \ep{Script_Extensions=Ugaritic} (31)
+\&   \ep{Script_Extensions: Ugaritic} (Short: \ep{Scx=Ugar}, \ep{Ugar})
+\&                             (31: U+10380..1039D, U+1039F)
+\&   \ep{Script_Extensions: Unknown} (Short: \ep{Scx=Zzzz}, \ep{Zzzz})
+\&                             (964_861 plus all above\-Unicode code
+\&                             points: U+0378..0379, U+0380..0383,
+\&                             U+038B, U+038D, U+03A2, U+0530 ...)
+\&   \ep{Script_Extensions: Vai} (Short: \ep{Scx=Vai}, \ep{Vai}) (300:
+\&                             U+A500..A62B)
+\&   \ep{Script_Extensions: Vaii} \ep{Script_Extensions=Vai} (300)
+\&   \ep{Script_Extensions: Vith} \ep{Script_Extensions=Vithkuqi} (70)
+\&   \ep{Script_Extensions: Vithkuqi} (Short: \ep{Scx=Vith}, \ep{Vith})
+\&                             (70: U+10570..1057A, U+1057C..1058A,
+\&                             U+1058C..10592, U+10594..10595,
+\&                             U+10597..105A1, U+105A3..105B1 ...)
+\&   \ep{Script_Extensions: Wancho} (Short: \ep{Scx=Wcho}, \ep{Wcho}) (59:
+\&                             U+1E2C0..1E2F9, U+1E2FF)
+\&   \ep{Script_Extensions: Wara} \ep{Script_Extensions=Warang_Citi} (84)
+\&   \ep{Script_Extensions: Warang_Citi} (Short: \ep{Scx=Wara}, \ep{Wara})
+\&                             (84: U+118A0..118F2, U+118FF)
+\&   \ep{Script_Extensions: Wcho} \ep{Script_Extensions=Wancho} (59)
+\&   \ep{Script_Extensions: Xpeo} \ep{Script_Extensions=Old_Persian} (50)
+\&   \ep{Script_Extensions: Xsux} \ep{Script_Extensions=Cuneiform} (1234)
+\&   \ep{Script_Extensions: Yezi} \ep{Script_Extensions=Yezidi} (60)
+\&   \ep{Script_Extensions: Yezidi} (Short: \ep{Scx=Yezi}, \ep{Yezi}) (60:
+\&                             U+060C, U+061B, U+061F, U+0660..0669,
+\&                             U+10E80..10EA9, U+10EAB..10EAD ...)
+\&   \ep{Script_Extensions: Yi} (Short: \ep{Scx=Yi}, \ep{Yi}) (1246:
+\&                             U+3001..3002, U+3008..3011,
+\&                             U+3014..301B, U+30FB, U+A000..A48C,
+\&                             U+A490..A4C6 ...)
+\&   \ep{Script_Extensions: Yiii} \ep{Script_Extensions=Yi} (1246)
+\&   \ep{Script_Extensions: Zanabazar_Square} (Short: \ep{Scx=Zanb},
+\&                             \ep{Zanb}) (72: U+11A00..11A47)
+\&   \ep{Script_Extensions: Zanb} \ep{Script_Extensions=Zanabazar_Square}
+\&                             (72)
+\&   \ep{Script_Extensions: Zinh} \ep{Script_Extensions=Inherited} (586)
+\&   \ep{Script_Extensions: Zyyy} \ep{Script_Extensions=Common} (7873)
+\&   \ep{Script_Extensions: Zzzz} \ep{Script_Extensions=Unknown} (964_861
+\&                             plus all above\-Unicode code points)
+\&   \ep{Scx: *}              \ep{Script_Extensions: *}
+\&   \ep{SD}                  \ep{Soft_Dotted} (= \ep{Soft_Dotted=Y}) (50)
+\&   \ep{SD: *}               \ep{Soft_Dotted: *}
+\&   \ep{Sentence_Break: AT}  \ep{Sentence_Break=ATerm} (4)
+\&   \ep{Sentence_Break: ATerm} (Short: \ep{SB=AT}) (4: [.], U+2024,
+\&                             U+FE52, U+FF0E)
+\&   \ep{Sentence_Break: CL}  \ep{Sentence_Break=Close} (195)
+\&   \ep{Sentence_Break: Close} (Short: \ep{SB=CL}) (195: [\e"\e\*(Aq\e(\e)\e[\e]
+\&                             \e{\e}\exab\exbb], U+0F3A..0F3D,
+\&                             U+169B..169C, U+2018..201F,
+\&                             U+2039..203A, U+2045..2046 ...)
+\&   \ep{Sentence_Break: CR}  (Short: \ep{SB=CR}) (1: [\er])
+\&   \ep{Sentence_Break: EX}  \ep{Sentence_Break=Extend} (2550)
+\&   \ep{Sentence_Break: Extend} (Short: \ep{SB=EX}) (2550: U+0300..036F,
+\&                             U+0483..0489, U+0591..05BD, U+05BF,
+\&                             U+05C1..05C2, U+05C4..05C5 ...)
+\&   \ep{Sentence_Break: FO}  \ep{Sentence_Break=Format} (72)
+\&   \ep{Sentence_Break: Format} (Short: \ep{SB=FO}) (72: [\exad],
+\&                             U+0600..0605, U+061C, U+06DD, U+070F,
+\&                             U+0890..0891 ...)
+\&   \ep{Sentence_Break: LE}  \ep{Sentence_Break=OLetter} (132_036)
+\&   \ep{Sentence_Break: LF}  (Short: \ep{SB=LF}) (1: [\en])
+\&   \ep{Sentence_Break: LO}  \ep{Sentence_Break=Lower} (2497)
+\&   \ep{Sentence_Break: Lower} (Short: \ep{SB=LO}) (2497: [a\-z\exaa\exb5
+\&                             \exba\exdf\-\exf6\exf8\-\exff], U+0101, U+0103,
+\&                             U+0105, U+0107, U+0109 ...)
+\&   \ep{Sentence_Break: NU}  \ep{Sentence_Break=Numeric} (682)
+\&   \ep{Sentence_Break: Numeric} (Short: \ep{SB=NU}) (682: [0\-9],
+\&                             U+0660..0669, U+066B..066C,
+\&                             U+06F0..06F9, U+07C0..07C9, U+0966..096F
+\&                             ...)
+\&   \ep{Sentence_Break: OLetter} (Short: \ep{SB=LE}) (132_036: U+01BB,
+\&                             U+01C0..01C3, U+0294, U+02B9..02BF,
+\&                             U+02C6..02D1, U+02EC ...)
+\&   \ep{Sentence_Break: Other} (Short: \ep{SB=XX}) (973_938 plus all
+\&                             above\-Unicode code points: [^\et\en\ecK\ef
+\&                             \er\ex20!\e"\e\*(Aq\e(\e),\e\-.0\-9:?A\-Z\e[\e]a\-z\e{\e}
+\&                             \ex85\exa0\exaa\-\exab\exad\exb5\exba\-\exbb\exc0\-
+\&                             \exd6\exd8\-\exf6\exf8\-\exff], U+02C2..02C5,
+\&                             U+02D2..02DF, U+02E5..02EB, U+02ED,
+\&                             U+02EF..02FF ...)
+\&   \ep{Sentence_Break: SC}  \ep{Sentence_Break=SContinue} (26)
+\&   \ep{Sentence_Break: SContinue} (Short: \ep{SB=SC}) (26: [,\e\-:],
+\&                             U+055D, U+060C..060D, U+07F8, U+1802,
+\&                             U+1808 ...)
+\&   \ep{Sentence_Break: SE}  \ep{Sentence_Break=Sep} (3)
+\&   \ep{Sentence_Break: Sep} (Short: \ep{SB=SE}) (3: [\ex85],
+\&                             U+2028..2029)
+\&   \ep{Sentence_Break: Sp}  (Short: \ep{SB=Sp}) (20: [\et\ecK\ef\ex20\exa0],
+\&                             U+1680, U+2000..200A, U+202F, U+205F,
+\&                             U+3000)
+\&   \ep{Sentence_Break: ST}  \ep{Sentence_Break=STerm} (151)
+\&   \ep{Sentence_Break: STerm} (Short: \ep{SB=ST}) (151: [!?], U+0589,
+\&                             U+061D..061F, U+06D4, U+0700..0702,
+\&                             U+07F9 ...)
+\&   \ep{Sentence_Break: UP}  \ep{Sentence_Break=Upper} (1936)
+\&   \ep{Sentence_Break: Upper} (Short: \ep{SB=UP}) (1936: [A\-Z\exc0\-\exd6
+\&                             \exd8\-\exde], U+0100, U+0102, U+0104,
+\&                             U+0106, U+0108 ...)
+\&   \ep{Sentence_Break: XX}  \ep{Sentence_Break=Other} (973_938 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Sentence_Terminal}   \ep{Sentence_Terminal=Y} (Short: \ep{STerm})
+\&                             (154)
+\&   \ep{Sentence_Terminal: N*} (Short: \ep{STerm=N}, \eP{STerm})
+\&                             (1_113_958 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-
+\&                             \e/0\-9:;<=>\e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-
+\&                             \exff], U+0100..0588, U+058A..061C,
+\&                             U+0620..06D3, U+06D5..06FF, U+0703..07F8
+\&                             ...)
+\&   \ep{Sentence_Terminal: Y*} (Short: \ep{STerm=Y}, \ep{STerm}) (154:
+\&                             [!.?], U+0589, U+061D..061F, U+06D4,
+\&                             U+0700..0702, U+07F9 ...)
+\&   \ep{Separator}           \ep{General_Category=Separator} (Short:
+\&                             \ep{Z}) (19)
+\&   \ep{Sgnw}                \ep{SignWriting} (= \ep{Script_Extensions=
+\&                             SignWriting}) (672)
+\&   \ep{Sharada}             \ep{Script_Extensions=Sharada} (Short:
+\&                             \ep{Shrd}; NOT \ep{Block=Sharada}) (102)
+\&   \ep{Shavian}             \ep{Script_Extensions=Shavian} (Short:
+\&                             \ep{Shaw}) (48)
+\&   \ep{Shaw}                \ep{Shavian} (= \ep{Script_Extensions=
+\&                             Shavian}) (48)
+\& X \ep{Shorthand_Format_Controls} \ep{Block=Shorthand_Format_Controls}
+\&                             (16)
+\&   \ep{Shrd}                \ep{Sharada} (= \ep{Script_Extensions=
+\&                             Sharada}) (NOT \ep{Block=Sharada}) (102)
+\&   \ep{Sidd}                \ep{Siddham} (= \ep{Script_Extensions=
+\&                             Siddham}) (NOT \ep{Block=Siddham}) (92)
+\&   \ep{Siddham}             \ep{Script_Extensions=Siddham} (Short:
+\&                             \ep{Sidd}; NOT \ep{Block=Siddham}) (92)
+\&   \ep{SignWriting}         \ep{Script_Extensions=SignWriting} (Short:
+\&                             \ep{Sgnw}) (672)
+\&   \ep{Sind}                \ep{Khudawadi} (= \ep{Script_Extensions=
+\&                             Khudawadi}) (NOT \ep{Block=Khudawadi})
+\&                             (81)
+\&   \ep{Sinh}                \ep{Sinhala} (= \ep{Script_Extensions=
+\&                             Sinhala}) (NOT \ep{Block=Sinhala}) (113)
+\&   \ep{Sinhala}             \ep{Script_Extensions=Sinhala} (Short:
+\&                             \ep{Sinh}; NOT \ep{Block=Sinhala}) (113)
+\& X \ep{Sinhala_Archaic_Numbers} \ep{Block=Sinhala_Archaic_Numbers} (32)
+\&   \ep{Sk}                  \ep{Modifier_Symbol} (=
+\&                             \ep{General_Category=Modifier_Symbol})
+\&                             (125)
+\&   \ep{Sm}                  \ep{Math_Symbol} (= \ep{General_Category=
+\&                             Math_Symbol}) (948)
+\& X \ep{Small_Form_Variants} \ep{Block=Small_Form_Variants} (Short:
+\&                             \ep{InSmallForms}) (32)
+\& X \ep{Small_Forms}         \ep{Small_Form_Variants} (= \ep{Block=
+\&                             Small_Form_Variants}) (32)
+\& X \ep{Small_Kana_Ext}      \ep{Small_Kana_Extension} (= \ep{Block=
+\&                             Small_Kana_Extension}) (64)
+\& X \ep{Small_Kana_Extension} \ep{Block=Small_Kana_Extension} (Short:
+\&                             \ep{InSmallKanaExt}) (64)
+\&   \ep{So}                  \ep{Other_Symbol} (= \ep{General_Category=
+\&                             Other_Symbol}) (6634)
+\&   \ep{Soft_Dotted}         \ep{Soft_Dotted=Y} (Short: \ep{SD}) (50)
+\&   \ep{Soft_Dotted: N*}     (Short: \ep{SD=N}, \eP{SD}) (1_114_062 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@A\-
+\&                             Z\e[\e\e\e]\e^_\`a\-hk\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..012E, U+0130..0248,
+\&                             U+024A..0267, U+0269..029C, U+029E..02B1
+\&                             ...)
+\&   \ep{Soft_Dotted: Y*}     (Short: \ep{SD=Y}, \ep{SD}) (50: [i\-j],
+\&                             U+012F, U+0249, U+0268, U+029D, U+02B2
+\&                             ...)
+\&   \ep{Sogd}                \ep{Sogdian} (= \ep{Script_Extensions=
+\&                             Sogdian}) (NOT \ep{Block=Sogdian}) (43)
+\&   \ep{Sogdian}             \ep{Script_Extensions=Sogdian} (Short:
+\&                             \ep{Sogd}; NOT \ep{Block=Sogdian}) (43)
+\&   \ep{Sogo}                \ep{Old_Sogdian} (= \ep{Script_Extensions=
+\&                             Old_Sogdian}) (NOT \ep{Block=
+\&                             Old_Sogdian}) (40)
+\&   \ep{Sora}                \ep{Sora_Sompeng} (= \ep{Script_Extensions=
+\&                             Sora_Sompeng}) (NOT \ep{Block=
+\&                             Sora_Sompeng}) (35)
+\&   \ep{Sora_Sompeng}        \ep{Script_Extensions=Sora_Sompeng} (Short:
+\&                             \ep{Sora}; NOT \ep{Block=Sora_Sompeng})
+\&                             (35)
+\&   \ep{Soyo}                \ep{Soyombo} (= \ep{Script_Extensions=
+\&                             Soyombo}) (NOT \ep{Block=Soyombo}) (83)
+\&   \ep{Soyombo}             \ep{Script_Extensions=Soyombo} (Short:
+\&                             \ep{Soyo}; NOT \ep{Block=Soyombo}) (83)
+\&   \ep{Space}               \ep{White_Space} (= \ep{White_Space=Y}) (25)
+\&   \ep{Space: *}            \ep{White_Space: *}
+\&   \ep{Space_Separator}     \ep{General_Category=Space_Separator}
+\&                             (Short: \ep{Zs}) (17)
+\&   \ep{SpacePerl}           \ep{XPosixSpace} (25)
+\&   \ep{Spacing_Mark}        \ep{General_Category=Spacing_Mark} (Short:
+\&                             \ep{Mc}) (452)
+\& X \ep{Spacing_Modifier_Letters} \ep{Block=Spacing_Modifier_Letters}
+\&                             (Short: \ep{InModifierLetters}) (80)
+\& X \ep{Specials}            \ep{Block=Specials} (16)
+\&   \ep{STerm}               \ep{Sentence_Terminal} (=
+\&                             \ep{Sentence_Terminal=Y}) (154)
+\&   \ep{STerm: *}            \ep{Sentence_Terminal: *}
+\&   \ep{Sund}                \ep{Sundanese} (= \ep{Script_Extensions=
+\&                             Sundanese}) (NOT \ep{Block=Sundanese})
+\&                             (72)
+\&   \ep{Sundanese}           \ep{Script_Extensions=Sundanese} (Short:
+\&                             \ep{Sund}; NOT \ep{Block=Sundanese}) (72)
+\& X \ep{Sundanese_Sup}       \ep{Sundanese_Supplement} (= \ep{Block=
+\&                             Sundanese_Supplement}) (16)
+\& X \ep{Sundanese_Supplement} \ep{Block=Sundanese_Supplement} (Short:
+\&                             \ep{InSundaneseSup}) (16)
+\& X \ep{Sup_Arrows_A}        \ep{Supplemental_Arrows_A} (= \ep{Block=
+\&                             Supplemental_Arrows_A}) (16)
+\& X \ep{Sup_Arrows_B}        \ep{Supplemental_Arrows_B} (= \ep{Block=
+\&                             Supplemental_Arrows_B}) (128)
+\& X \ep{Sup_Arrows_C}        \ep{Supplemental_Arrows_C} (= \ep{Block=
+\&                             Supplemental_Arrows_C}) (256)
+\& X \ep{Sup_Math_Operators}  \ep{Supplemental_Mathematical_Operators} (=
+\&                             \ep{Block=
+\&                             Supplemental_Mathematical_Operators})
+\&                             (256)
+\& X \ep{Sup_PUA_A}           \ep{Supplementary_Private_Use_Area_A} (=
+\&                             \ep{Block=
+\&                             Supplementary_Private_Use_Area_A})
+\&                             (65_536)
+\& X \ep{Sup_PUA_B}           \ep{Supplementary_Private_Use_Area_B} (=
+\&                             \ep{Block=
+\&                             Supplementary_Private_Use_Area_B})
+\&                             (65_536)
+\& X \ep{Sup_Punctuation}     \ep{Supplemental_Punctuation} (= \ep{Block=
+\&                             Supplemental_Punctuation}) (128)
+\& X \ep{Sup_Symbols_And_Pictographs}
+\&                             \ep{Supplemental_Symbols_And_Pictographs}
+\&                             (= \ep{Block=
+\&                             Supplemental_Symbols_And_Pictographs})
+\&                             (256)
+\& X \ep{Super_And_Sub}       \ep{Superscripts_And_Subscripts} (=
+\&                             \ep{Block=Superscripts_And_Subscripts})
+\&                             (48)
+\& X \ep{Superscripts_And_Subscripts} \ep{Block=
+\&                             Superscripts_And_Subscripts} (Short:
+\&                             \ep{InSuperAndSub}) (48)
+\& X \ep{Supplemental_Arrows_A} \ep{Block=Supplemental_Arrows_A} (Short:
+\&                             \ep{InSupArrowsA}) (16)
+\& X \ep{Supplemental_Arrows_B} \ep{Block=Supplemental_Arrows_B} (Short:
+\&                             \ep{InSupArrowsB}) (128)
+\& X \ep{Supplemental_Arrows_C} \ep{Block=Supplemental_Arrows_C} (Short:
+\&                             \ep{InSupArrowsC}) (256)
+\& X \ep{Supplemental_Mathematical_Operators} \ep{Block=
+\&                             Supplemental_Mathematical_Operators}
+\&                             (Short: \ep{InSupMathOperators}) (256)
+\& X \ep{Supplemental_Punctuation} \ep{Block=Supplemental_Punctuation}
+\&                             (Short: \ep{InSupPunctuation}) (128)
+\& X \ep{Supplemental_Symbols_And_Pictographs} \ep{Block=
+\&                             Supplemental_Symbols_And_Pictographs}
+\&                             (Short: \ep{InSupSymbolsAndPictographs})
+\&                             (256)
+\& X \ep{Supplementary_Private_Use_Area_A} \ep{Block=
+\&                             Supplementary_Private_Use_Area_A}
+\&                             (Short: \ep{InSupPUAA}) (65_536)
+\& X \ep{Supplementary_Private_Use_Area_B} \ep{Block=
+\&                             Supplementary_Private_Use_Area_B}
+\&                             (Short: \ep{InSupPUAB}) (65_536)
+\&   \ep{Surrogate}           \ep{General_Category=Surrogate} (Short:
+\&                             \ep{Cs}) (2048)
+\& X \ep{Sutton_SignWriting}  \ep{Block=Sutton_SignWriting} (688)
+\&   \ep{Sylo}                \ep{Syloti_Nagri} (= \ep{Script_Extensions=
+\&                             Syloti_Nagri}) (NOT \ep{Block=
+\&                             Syloti_Nagri}) (57)
+\&   \ep{Syloti_Nagri}        \ep{Script_Extensions=Syloti_Nagri} (Short:
+\&                             \ep{Sylo}; NOT \ep{Block=Syloti_Nagri})
+\&                             (57)
+\&   \ep{Symbol}              \ep{General_Category=Symbol} (Short: \ep{S})
+\&                             (7770)
+\& X \ep{Symbols_And_Pictographs_Ext_A}
+\&                             \ep{Symbols_And_Pictographs_Extended_A}
+\&                             (= \ep{Block=
+\&                             Symbols_And_Pictographs_Extended_A})
+\&                             (144)
+\& X \ep{Symbols_And_Pictographs_Extended_A} \ep{Block=
+\&                             Symbols_And_Pictographs_Extended_A} (144)
+\& X \ep{Symbols_For_Legacy_Computing} \ep{Block=
+\&                             Symbols_For_Legacy_Computing} (256)
+\&   \ep{Syrc}                \ep{Syriac} (= \ep{Script_Extensions=
+\&                             Syriac}) (NOT \ep{Block=Syriac}) (107)
+\&   \ep{Syriac}              \ep{Script_Extensions=Syriac} (Short:
+\&                             \ep{Syrc}; NOT \ep{Block=Syriac}) (107)
+\& X \ep{Syriac_Sup}          \ep{Syriac_Supplement} (= \ep{Block=
+\&                             Syriac_Supplement}) (16)
+\& X \ep{Syriac_Supplement}   \ep{Block=Syriac_Supplement} (Short:
+\&                             \ep{InSyriacSup}) (16)
+\&   \ep{Tagalog}             \ep{Script_Extensions=Tagalog} (Short:
+\&                             \ep{Tglg}; NOT \ep{Block=Tagalog}) (25)
+\&   \ep{Tagb}                \ep{Tagbanwa} (= \ep{Script_Extensions=
+\&                             Tagbanwa}) (NOT \ep{Block=Tagbanwa}) (20)
+\&   \ep{Tagbanwa}            \ep{Script_Extensions=Tagbanwa} (Short:
+\&                             \ep{Tagb}; NOT \ep{Block=Tagbanwa}) (20)
+\& X \ep{Tags}                \ep{Block=Tags} (128)
+\&   \ep{Tai_Le}              \ep{Script_Extensions=Tai_Le} (Short:
+\&                             \ep{Tale}; NOT \ep{Block=Tai_Le}) (45)
+\&   \ep{Tai_Tham}            \ep{Script_Extensions=Tai_Tham} (Short:
+\&                             \ep{Lana}; NOT \ep{Block=Tai_Tham}) (127)
+\&   \ep{Tai_Viet}            \ep{Script_Extensions=Tai_Viet} (Short:
+\&                             \ep{Tavt}; NOT \ep{Block=Tai_Viet}) (72)
+\& X \ep{Tai_Xuan_Jing}       \ep{Tai_Xuan_Jing_Symbols} (= \ep{Block=
+\&                             Tai_Xuan_Jing_Symbols}) (96)
+\& X \ep{Tai_Xuan_Jing_Symbols} \ep{Block=Tai_Xuan_Jing_Symbols} (Short:
+\&                             \ep{InTaiXuanJing}) (96)
+\&   \ep{Takr}                \ep{Takri} (= \ep{Script_Extensions=Takri})
+\&                             (NOT \ep{Block=Takri}) (80)
+\&   \ep{Takri}               \ep{Script_Extensions=Takri} (Short:
+\&                             \ep{Takr}; NOT \ep{Block=Takri}) (80)
+\&   \ep{Tale}                \ep{Tai_Le} (= \ep{Script_Extensions=
+\&                             Tai_Le}) (NOT \ep{Block=Tai_Le}) (45)
+\&   \ep{Talu}                \ep{New_Tai_Lue} (= \ep{Script_Extensions=
+\&                             New_Tai_Lue}) (NOT \ep{Block=
+\&                             New_Tai_Lue}) (83)
+\&   \ep{Tamil}               \ep{Script_Extensions=Tamil} (Short:
+\&                             \ep{Taml}; NOT \ep{Block=Tamil}) (133)
+\& X \ep{Tamil_Sup}           \ep{Tamil_Supplement} (= \ep{Block=
+\&                             Tamil_Supplement}) (64)
+\& X \ep{Tamil_Supplement}    \ep{Block=Tamil_Supplement} (Short:
+\&                             \ep{InTamilSup}) (64)
+\&   \ep{Taml}                \ep{Tamil} (= \ep{Script_Extensions=Tamil})
+\&                             (NOT \ep{Block=Tamil}) (133)
+\&   \ep{Tang}                \ep{Tangut} (= \ep{Script_Extensions=
+\&                             Tangut}) (NOT \ep{Block=Tangut}) (6914)
+\&   \ep{Tangsa}              \ep{Script_Extensions=Tangsa} (Short:
+\&                             \ep{Tnsa}; NOT \ep{Block=Tangsa}) (89)
+\&   \ep{Tangut}              \ep{Script_Extensions=Tangut} (Short:
+\&                             \ep{Tang}; NOT \ep{Block=Tangut}) (6914)
+\& X \ep{Tangut_Components}   \ep{Block=Tangut_Components} (768)
+\& X \ep{Tangut_Sup}          \ep{Tangut_Supplement} (= \ep{Block=
+\&                             Tangut_Supplement}) (128)
+\& X \ep{Tangut_Supplement}   \ep{Block=Tangut_Supplement} (Short:
+\&                             \ep{InTangutSup}) (128)
+\&   \ep{Tavt}                \ep{Tai_Viet} (= \ep{Script_Extensions=
+\&                             Tai_Viet}) (NOT \ep{Block=Tai_Viet}) (72)
+\&   \ep{Telu}                \ep{Telugu} (= \ep{Script_Extensions=
+\&                             Telugu}) (NOT \ep{Block=Telugu}) (106)
+\&   \ep{Telugu}              \ep{Script_Extensions=Telugu} (Short:
+\&                             \ep{Telu}; NOT \ep{Block=Telugu}) (106)
+\&   \ep{Term}                \ep{Terminal_Punctuation} (=
+\&                             \ep{Terminal_Punctuation=Y}) (278)
+\&   \ep{Term: *}             \ep{Terminal_Punctuation: *}
+\&   \ep{Terminal_Punctuation} \ep{Terminal_Punctuation=Y} (Short:
+\&                             \ep{Term}) (278)
+\&   \ep{Terminal_Punctuation: N*} (Short: \ep{Term=N}, \eP{Term})
+\&                             (1_113_834 plus all above\-Unicode code
+\&                             points: [\ex00\-\ex20\e"#\e$\e%&\e\*(Aq\e(\e)*+\e\-\e/0\-
+\&                             9<=>\e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~\ex7f\-\exff],
+\&                             U+0100..037D, U+037F..0386,
+\&                             U+0388..0588, U+058A..05C2, U+05C4..060B
+\&                             ...)
+\&   \ep{Terminal_Punctuation: Y*} (Short: \ep{Term=Y}, \ep{Term}) (278:
+\&                             [!,.:;?], U+037E, U+0387, U+0589,
+\&                             U+05C3, U+060C ...)
+\&   \ep{Tfng}                \ep{Tifinagh} (= \ep{Script_Extensions=
+\&                             Tifinagh}) (NOT \ep{Block=Tifinagh}) (59)
+\&   \ep{Tglg}                \ep{Tagalog} (= \ep{Script_Extensions=
+\&                             Tagalog}) (NOT \ep{Block=Tagalog}) (25)
+\&   \ep{Thaa}                \ep{Thaana} (= \ep{Script_Extensions=
+\&                             Thaana}) (NOT \ep{Block=Thaana}) (66)
+\&   \ep{Thaana}              \ep{Script_Extensions=Thaana} (Short:
+\&                             \ep{Thaa}; NOT \ep{Block=Thaana}) (66)
+\&   \ep{Thai}                \ep{Script_Extensions=Thai} (NOT \ep{Block=
+\&                             Thai}) (86)
+\&   \ep{Tibetan}             \ep{Script_Extensions=Tibetan} (Short:
+\&                             \ep{Tibt}; NOT \ep{Block=Tibetan}) (207)
+\&   \ep{Tibt}                \ep{Tibetan} (= \ep{Script_Extensions=
+\&                             Tibetan}) (NOT \ep{Block=Tibetan}) (207)
+\&   \ep{Tifinagh}            \ep{Script_Extensions=Tifinagh} (Short:
+\&                             \ep{Tfng}; NOT \ep{Block=Tifinagh}) (59)
+\&   \ep{Tirh}                \ep{Tirhuta} (= \ep{Script_Extensions=
+\&                             Tirhuta}) (NOT \ep{Block=Tirhuta}) (97)
+\&   \ep{Tirhuta}             \ep{Script_Extensions=Tirhuta} (Short:
+\&                             \ep{Tirh}; NOT \ep{Block=Tirhuta}) (97)
+\&   \ep{Title}               \ep{Titlecase} (/i= Cased=Yes) (31)
+\&   \ep{Titlecase}           (= \ep{Gc=Lt}) (Short: \ep{Title}; /i=
+\&                             Cased=Yes) (31: U+01C5, U+01C8, U+01CB,
+\&                             U+01F2, U+1F88..1F8F, U+1F98..1F9F ...)
+\&   \ep{Titlecase_Letter}    \ep{General_Category=Titlecase_Letter}
+\&                             (Short: \ep{Lt}; /i= General_Category=
+\&                             Cased_Letter) (31)
+\&   \ep{Tnsa}                \ep{Tangsa} (= \ep{Script_Extensions=
+\&                             Tangsa}) (NOT \ep{Block=Tangsa}) (89)
+\&   \ep{Toto}                \ep{Script_Extensions=Toto} (NOT \ep{Block=
+\&                             Toto}) (31)
+\& X \ep{Transport_And_Map}   \ep{Transport_And_Map_Symbols} (= \ep{Block=
+\&                             Transport_And_Map_Symbols}) (128)
+\& X \ep{Transport_And_Map_Symbols} \ep{Block=Transport_And_Map_Symbols}
+\&                             (Short: \ep{InTransportAndMap}) (128)
+\& X \ep{UCAS}                \ep{Unified_Canadian_Aboriginal_Syllabics}
+\&                             (= \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics})
+\&                             (640)
+\& X \ep{UCAS_Ext}            \ep{Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended} (= \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended}) (80)
+\& X \ep{UCAS_Ext_A}          \ep{Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended_A} (= \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended_A}) (16)
+\&   \ep{Ugar}                \ep{Ugaritic} (= \ep{Script_Extensions=
+\&                             Ugaritic}) (NOT \ep{Block=Ugaritic}) (31)
+\&   \ep{Ugaritic}            \ep{Script_Extensions=Ugaritic} (Short:
+\&                             \ep{Ugar}; NOT \ep{Block=Ugaritic}) (31)
+\&   \ep{UIdeo}               \ep{Unified_Ideograph} (=
+\&                             \ep{Unified_Ideograph=Y}) (97_058)
+\&   \ep{UIdeo: *}            \ep{Unified_Ideograph: *}
+\&   \ep{Unassigned}          \ep{General_Category=Unassigned} (Short:
+\&                             \ep{Cn}) (825_345 plus all above\-Unicode
+\&                             code points)
+\&   \ep{Unicode}             \ep{Any} (1_114_112)
+\& X \ep{Unified_Canadian_Aboriginal_Syllabics} \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics}
+\&                             (Short: \ep{InUCAS}) (640)
+\& X \ep{Unified_Canadian_Aboriginal_Syllabics_Extended} \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended} (Short: \ep{InUCASExt}) (80)
+\& X \ep{Unified_Canadian_Aboriginal_Syllabics_Extended_A} \ep{Block=
+\&                             Unified_Canadian_Aboriginal_Syllabics_\-
+\&                             Extended_A} (Short: \ep{InUCASExtA}) (16)
+\&   \ep{Unified_Ideograph}   \ep{Unified_Ideograph=Y} (Short: \ep{UIdeo})
+\&                             (97_058)
+\&   \ep{Unified_Ideograph: N*} (Short: \ep{UIdeo=N}, \eP{UIdeo})
+\&                             (1_017_054 plus all above\-Unicode code
+\&                             points: U+0000..33FF, U+4DC0..4DFF,
+\&                             U+A000..FA0D, U+FA10, U+FA12,
+\&                             U+FA15..FA1E ...)
+\&   \ep{Unified_Ideograph: Y*} (Short: \ep{UIdeo=Y}, \ep{UIdeo}) (97_058:
+\&                             U+3400..4DBF, U+4E00..9FFF,
+\&                             U+FA0E..FA0F, U+FA11, U+FA13..FA14,
+\&                             U+FA1F ...)
+\&   \ep{Unknown}             \ep{Script_Extensions=Unknown} (Short:
+\&                             \ep{Zzzz}) (964_861 plus all above\-
+\&                             Unicode code points)
+\&   \ep{Upper}               \ep{XPosixUpper} (= \ep{Uppercase=Y}) (/i=
+\&                             Cased=Yes) (1951)
+\&   \ep{Upper: *}            \ep{Uppercase: *}
+\&   \ep{Uppercase}           \ep{XPosixUpper} (= \ep{Uppercase=Y}) (/i=
+\&                             Cased=Yes) (1951)
+\&   \ep{Uppercase: N*}       (Short: \ep{Upper=N}, \eP{Upper}; /i= Cased=
+\&                             No) (1_112_161 plus all above\-Unicode
+\&                             code points: [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq
+\&                             \e(\e)*+,\e\-.\e/0\-9:;<=>?\e@\e[\e\e\e]\e^_\`a\-z\e{
+\&                             \e|\e}~\ex7f\-\exbf\exd7\exdf\-\exff], U+0101,
+\&                             U+0103, U+0105, U+0107, U+0109 ...)
+\&   \ep{Uppercase: Y*}       (Short: \ep{Upper=Y}, \ep{Upper}; /i= Cased=
+\&                             Yes) (1951: [A\-Z\exc0\-\exd6\exd8\-\exde],
+\&                             U+0100, U+0102, U+0104, U+0106, U+0108
+\&                             ...)
+\&   \ep{Uppercase_Letter}    \ep{General_Category=Uppercase_Letter}
+\&                             (Short: \ep{Lu}; /i= General_Category=
+\&                             Cased_Letter) (1831)
+\&   \ep{Vai}                 \ep{Script_Extensions=Vai} (NOT \ep{Block=
+\&                             Vai}) (300)
+\&   \ep{Vaii}                \ep{Vai} (= \ep{Script_Extensions=Vai}) (NOT
+\&                             \ep{Block=Vai}) (300)
+\&   \ep{Variation_Selector}  \ep{Variation_Selector=Y} (Short: \ep{VS};
+\&                             NOT \ep{Variation_Selectors}) (260)
+\&   \ep{Variation_Selector: N*} (Short: \ep{VS=N}, \eP{VS}) (1_113_852
+\&                             plus all above\-Unicode code points:
+\&                             U+0000..180A, U+180E, U+1810..FDFF,
+\&                             U+FE10..E00FF, U+E01F0..infinity)
+\&   \ep{Variation_Selector: Y*} (Short: \ep{VS=Y}, \ep{VS}) (260:
+\&                             U+180B..180D, U+180F, U+FE00..FE0F,
+\&                             U+E0100..E01EF)
+\& X \ep{Variation_Selectors} \ep{Block=Variation_Selectors} (Short:
+\&                             \ep{InVS}) (16)
+\& X \ep{Variation_Selectors_Supplement} \ep{Block=
+\&                             Variation_Selectors_Supplement} (Short:
+\&                             \ep{InVSSup}) (240)
+\& X \ep{Vedic_Ext}           \ep{Vedic_Extensions} (= \ep{Block=
+\&                             Vedic_Extensions}) (48)
+\& X \ep{Vedic_Extensions}    \ep{Block=Vedic_Extensions} (Short:
+\&                             \ep{InVedicExt}) (48)
+\& X \ep{Vertical_Forms}      \ep{Block=Vertical_Forms} (16)
+\&   \ep{Vertical_Orientation: R} \ep{Vertical_Orientation=Rotated}
+\&                             (786_609 plus all above\-Unicode code
+\&                             points)
+\&   \ep{Vertical_Orientation: Rotated} (Short: \ep{Vo=R}) (786_609 plus
+\&                             all above\-Unicode code points: [\ex00\-
+\&                             \exa6\exa8\exaa\-\exad\exaf\-\exb0\exb2\-\exbb\exbf\-
+\&                             \exd6\exd8\-\exf6\exf8\-\exff], U+0100..02E9,
+\&                             U+02EC..10FF, U+1200..1400,
+\&                             U+1680..18AF, U+1900..2015 ...)
+\&   \ep{Vertical_Orientation: Tr} \ep{Vertical_Orientation=
+\&                             Transformed_Rotated} (47)
+\&   \ep{Vertical_Orientation: Transformed_Rotated} (Short: \ep{Vo=Tr})
+\&                             (47: U+2329..232A, U+3008..3011,
+\&                             U+3014..301F, U+3030, U+30A0, U+30FC ...)
+\&   \ep{Vertical_Orientation: Transformed_Upright} (Short: \ep{Vo=Tu})
+\&                             (148: U+3001..3002, U+3041, U+3043,
+\&                             U+3045, U+3047, U+3049 ...)
+\&   \ep{Vertical_Orientation: Tu} \ep{Vertical_Orientation=
+\&                             Transformed_Upright} (148)
+\&   \ep{Vertical_Orientation: U} \ep{Vertical_Orientation=Upright}
+\&                             (327_308)
+\&   \ep{Vertical_Orientation: Upright} (Short: \ep{Vo=U}) (327_308:
+\&                             [\exa7\exa9\exae\exb1\exbc\-\exbe\exd7\exf7],
+\&                             U+02EA..02EB, U+1100..11FF,
+\&                             U+1401..167F, U+18B0..18FF, U+2016 ...)
+\&   \ep{VertSpace}           \ev (7: [\en\ecK\ef\er\ex85], U+2028..2029)
+\&   \ep{Vith}                \ep{Vithkuqi} (= \ep{Script_Extensions=
+\&                             Vithkuqi}) (NOT \ep{Block=Vithkuqi}) (70)
+\&   \ep{Vithkuqi}            \ep{Script_Extensions=Vithkuqi} (Short:
+\&                             \ep{Vith}; NOT \ep{Block=Vithkuqi}) (70)
+\&   \ep{Vo: *}               \ep{Vertical_Orientation: *}
+\&   \ep{VS}                  \ep{Variation_Selector} (=
+\&                             \ep{Variation_Selector=Y}) (NOT
+\&                             \ep{Variation_Selectors}) (260)
+\&   \ep{VS: *}               \ep{Variation_Selector: *}
+\& X \ep{VS_Sup}              \ep{Variation_Selectors_Supplement} (=
+\&                             \ep{Block=
+\&                             Variation_Selectors_Supplement}) (240)
+\&   \ep{Wancho}              \ep{Script_Extensions=Wancho} (Short:
+\&                             \ep{Wcho}; NOT \ep{Block=Wancho}) (59)
+\&   \ep{Wara}                \ep{Warang_Citi} (= \ep{Script_Extensions=
+\&                             Warang_Citi}) (NOT \ep{Block=
+\&                             Warang_Citi}) (84)
+\&   \ep{Warang_Citi}         \ep{Script_Extensions=Warang_Citi} (Short:
+\&                             \ep{Wara}; NOT \ep{Block=Warang_Citi}) (84)
+\&   \ep{WB: *}               \ep{Word_Break: *}
+\&   \ep{Wcho}                \ep{Wancho} (= \ep{Script_Extensions=
+\&                             Wancho}) (NOT \ep{Block=Wancho}) (59)
+\&   \ep{White_Space}         \ep{White_Space=Y} (Short: \ep{Space}) (25)
+\&   \ep{White_Space: N*}     (Short: \ep{Space=N}, \eP{Space}) (1_114_087
+\&                             plus all above\-Unicode code points: [^
+\&                             \et\en\ecK\ef\er\ex20\ex85\exa0], U+0100..167F,
+\&                             U+1681..1FFF, U+200B..2027,
+\&                             U+202A..202E, U+2030..205E ...)
+\&   \ep{White_Space: Y*}     (Short: \ep{Space=Y}, \ep{Space}) (25: [\et
+\&                             \en\ecK\ef\er\ex20\ex85\exa0], U+1680,
+\&                             U+2000..200A, U+2028..2029, U+202F,
+\&                             U+205F ...)
+\&   \ep{Word}                \ep{XPosixWord} (139_612)
+\&   \ep{Word_Break: ALetter} (Short: \ep{WB=LE}) (29_489: [A\-Za\-z\exaa
+\&                             \exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..02D7, U+02DE..02FF,
+\&                             U+0370..0374, U+0376..0377, U+037A..037D
+\&                             ...)
+\&   \ep{Word_Break: CR}      (Short: \ep{WB=CR}) (1: [\er])
+\&   \ep{Word_Break: Double_Quote} (Short: \ep{WB=DQ}) (1: [\e"])
+\&   \ep{Word_Break: DQ}      \ep{Word_Break=Double_Quote} (1)
+\&   \ep{Word_Break: E_Base}  (Short: \ep{WB=EB}) (0)
+\&   \ep{Word_Break: E_Base_GAZ} (Short: \ep{WB=EBG}) (0)
+\&   \ep{Word_Break: E_Modifier} (Short: \ep{WB=EM}) (0)
+\&   \ep{Word_Break: EB}      \ep{Word_Break=E_Base} (0)
+\&   \ep{Word_Break: EBG}     \ep{Word_Break=E_Base_GAZ} (0)
+\&   \ep{Word_Break: EM}      \ep{Word_Break=E_Modifier} (0)
+\&   \ep{Word_Break: EX}      \ep{Word_Break=ExtendNumLet} (11)
+\&   \ep{Word_Break: Extend}  (Short: \ep{WB=Extend}) (2554:
+\&                             U+0300..036F, U+0483..0489,
+\&                             U+0591..05BD, U+05BF, U+05C1..05C2,
+\&                             U+05C4..05C5 ...)
+\&   \ep{Word_Break: ExtendNumLet} (Short: \ep{WB=EX}) (11: [_], U+202F,
+\&                             U+203F..2040, U+2054, U+FE33..FE34,
+\&                             U+FE4D..FE4F ...)
+\&   \ep{Word_Break: FO}      \ep{Word_Break=Format} (71)
+\&   \ep{Word_Break: Format}  (Short: \ep{WB=FO}) (71: [\exad],
+\&                             U+0600..0605, U+061C, U+06DD, U+070F,
+\&                             U+0890..0891 ...)
+\&   \ep{Word_Break: GAZ}     \ep{Word_Break=Glue_After_Zwj} (0)
+\&   \ep{Word_Break: Glue_After_Zwj} (Short: \ep{WB=GAZ}) (0)
+\&   \ep{Word_Break: Hebrew_Letter} (Short: \ep{WB=HL}) (75:
+\&                             U+05D0..05EA, U+05EF..05F2, U+FB1D,
+\&                             U+FB1F..FB28, U+FB2A..FB36, U+FB38..FB3C
+\&                             ...)
+\&   \ep{Word_Break: HL}      \ep{Word_Break=Hebrew_Letter} (75)
+\&   \ep{Word_Break: KA}      \ep{Word_Break=Katakana} (331)
+\&   \ep{Word_Break: Katakana} (Short: \ep{WB=KA}) (331: U+3031..3035,
+\&                             U+309B..309C, U+30A0..30FA,
+\&                             U+30FC..30FF, U+31F0..31FF, U+32D0..32FE
+\&                             ...)
+\&   \ep{Word_Break: LE}      \ep{Word_Break=ALetter} (29_489)
+\&   \ep{Word_Break: LF}      (Short: \ep{WB=LF}) (1: [\en])
+\&   \ep{Word_Break: MB}      \ep{Word_Break=MidNumLet} (7)
+\&   \ep{Word_Break: MidLetter} (Short: \ep{WB=ML}) (9: [:\exb7], U+0387,
+\&                             U+055F, U+05F4, U+2027, U+FE13 ...)
+\&   \ep{Word_Break: MidNum}  (Short: \ep{WB=MN}) (15: [,;], U+037E,
+\&                             U+0589, U+060C..060D, U+066C, U+07F8 ...)
+\&   \ep{Word_Break: MidNumLet} (Short: \ep{WB=MB}) (7: [.],
+\&                             U+2018..2019, U+2024, U+FE52, U+FF07,
+\&                             U+FF0E)
+\&   \ep{Word_Break: ML}      \ep{Word_Break=MidLetter} (9)
+\&   \ep{Word_Break: MN}      \ep{Word_Break=MidNum} (15)
+\&   \ep{Word_Break: Newline} (Short: \ep{WB=NL}) (5: [\ecK\ef\ex85],
+\&                             U+2028..2029)
+\&   \ep{Word_Break: NL}      \ep{Word_Break=Newline} (5)
+\&   \ep{Word_Break: NU}      \ep{Word_Break=Numeric} (681)
+\&   \ep{Word_Break: Numeric} (Short: \ep{WB=NU}) (681: [0\-9],
+\&                             U+0660..0669, U+066B, U+06F0..06F9,
+\&                             U+07C0..07C9, U+0966..096F ...)
+\&   \ep{Word_Break: Other}   (Short: \ep{WB=XX}) (1_080_819 plus all
+\&                             above\-Unicode code points: [^\en\ecK\ef\er
+\&                             \ex20\e"\e\*(Aq,.0\-9:;A\-Z_a\-z\ex85\exaa\exad\exb5
+\&                             \exb7\exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+02D8..02DD, U+0375, U+0378..0379,
+\&                             U+0380..0385, U+038B ...)
+\&   \ep{Word_Break: Regional_Indicator} (Short: \ep{WB=RI}) (26:
+\&                             U+1F1E6..1F1FF)
+\&   \ep{Word_Break: RI}      \ep{Word_Break=Regional_Indicator} (26)
+\&   \ep{Word_Break: Single_Quote} (Short: \ep{WB=SQ}) (1: [\e\*(Aq])
+\&   \ep{Word_Break: SQ}      \ep{Word_Break=Single_Quote} (1)
+\&   \ep{Word_Break: WSegSpace} (Short: \ep{WB=WSegSpace}) (14: [\ex20],
+\&                             U+1680, U+2000..2006, U+2008..200A,
+\&                             U+205F, U+3000)
+\&   \ep{Word_Break: XX}      \ep{Word_Break=Other} (1_080_819 plus all
+\&                             above\-Unicode code points)
+\&   \ep{Word_Break: ZWJ}     (Short: \ep{WB=ZWJ}) (1: U+200D)
+\&   \ep{WSpace}              \ep{White_Space} (= \ep{White_Space=Y}) (25)
+\&   \ep{WSpace: *}           \ep{White_Space: *}
+\&   \ep{XDigit}              \ep{XPosixXDigit} (= \ep{Hex_Digit=Y}) (44)
+\&   \ep{XID_Continue}        \ep{XID_Continue=Y} (Short: \ep{XIDC})
+\&                             (139_463)
+\&   \ep{XID_Continue: N*}    (Short: \ep{XIDC=N}, \eP{XIDC}) (974_649
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?
+\&                             \e@\e[\e\e\e]\e^\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4
+\&                             \exb6\exb8\-\exb9\exbb\-\exbf\exd7\exf7],
+\&                             U+02C2..02C5, U+02D2..02DF,
+\&                             U+02E5..02EB, U+02ED, U+02EF..02FF ...)
+\&   \ep{XID_Continue: Y*}    (Short: \ep{XIDC=Y}, \ep{XIDC}) (139_463:
+\&                             [0\-9A\-Z_a\-z\exaa\exb5\exb7\exba\exc0\-\exd6
+\&                             \exd8\-\exf6\exf8\-\exff], U+0100..02C1,
+\&                             U+02C6..02D1, U+02E0..02E4, U+02EC,
+\&                             U+02EE ...)
+\&   \ep{XID_Start}           \ep{XID_Start=Y} (Short: \ep{XIDS}) (136_322)
+\&   \ep{XID_Start: N*}       (Short: \ep{XIDS=N}, \eP{XIDS}) (977_790
+\&                             plus all above\-Unicode code points:
+\&                             [\ex00\-\ex20!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=
+\&                             >?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\ex7f\-\exa9\exab\-\exb4
+\&                             \exb6\-\exb9\exbb\-\exbf\exd7\exf7],
+\&                             U+02C2..02C5, U+02D2..02DF,
+\&                             U+02E5..02EB, U+02ED, U+02EF..036F ...)
+\&   \ep{XID_Start: Y*}       (Short: \ep{XIDS=Y}, \ep{XIDS}) (136_322:
+\&                             [A\-Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6
+\&                             \exf8\-\exff], U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\&   \ep{XIDC}                \ep{XID_Continue} (= \ep{XID_Continue=Y})
+\&                             (139_463)
+\&   \ep{XIDC: *}             \ep{XID_Continue: *}
+\&   \ep{XIDS}                \ep{XID_Start} (= \ep{XID_Start=Y}) (136_322)
+\&   \ep{XIDS: *}             \ep{XID_Start: *}
+\&   \ep{Xpeo}                \ep{Old_Persian} (= \ep{Script_Extensions=
+\&                             Old_Persian}) (NOT \ep{Block=
+\&                             Old_Persian}) (50)
+\&   \ep{XPerlSpace}          \ep{XPosixSpace} (25)
+\&   \ep{XPosixAlnum}         Alphabetic and (decimal) Numeric (Short:
+\&                             \ep{Alnum}) (138_445: [0\-9A\-Za\-z\exaa\exb5
+\&                             \exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\&   \ep{XPosixAlpha}         \ep{Alphabetic=Y} (Short: \ep{Alpha})
+\&                             (137_765)
+\&   \ep{XPosixBlank}         \eh, Horizontal white space (Short:
+\&                             \ep{Blank}) (18: [\et\ex20\exa0], U+1680,
+\&                             U+2000..200A, U+202F, U+205F, U+3000)
+\&   \ep{XPosixCntrl}         \ep{General_Category=Control} Control
+\&                             characters (Short: \ep{Cc}) (65)
+\&   \ep{XPosixDigit}         \ep{General_Category=Decimal_Number} [0\-9]
+\&                             + all other decimal digits (Short:
+\&                             \ep{Nd}) (680)
+\&   \ep{XPosixGraph}         Characters that are graphical (Short:
+\&                             \ep{Graph}) (286_635: [!\e"#\e$\e%&\e\*(Aq
+\&                             \e(\e)*+,\e\-.\e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`a\-z
+\&                             \e{\e|\e}~\exa1\-\exff], U+0100..0377,
+\&                             U+037A..037F, U+0384..038A, U+038C,
+\&                             U+038E..03A1 ...)
+\&   \ep{XPosixLower}         \ep{Lowercase=Y} (Short: \ep{Lower}; /i=
+\&                             Cased=Yes) (2544)
+\&   \ep{XPosixPrint}         Characters that are graphical plus space
+\&                             characters (but no controls) (Short:
+\&                             \ep{Print}) (286_652: [\ex20\-\ex7e\exa0\-
+\&                             \exff], U+0100..0377, U+037A..037F,
+\&                             U+0384..038A, U+038C, U+038E..03A1 ...)
+\&   \ep{XPosixPunct}         \ep{Punct} + ASCII\-range \ep{Symbol} (851:
+\&                             [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=>?\e@\e[\e\e\e]
+\&                             \e^_\`\e{\e|\e}~\exa1\exa7\exab\exb6\-\exb7\exbb
+\&                             \exbf], U+037E, U+0387, U+055A..055F,
+\&                             U+0589..058A, U+05BE ...)
+\&   \ep{XPosixSpace}         \es including beyond ASCII and vertical tab
+\&                             (Short: \ep{SpacePerl}) (25: [\et\en\ecK\ef
+\&                             \er\ex20\ex85\exa0], U+1680, U+2000..200A,
+\&                             U+2028..2029, U+202F, U+205F ...)
+\&   \ep{XPosixUpper}         \ep{Uppercase=Y} (Short: \ep{Upper}; /i=
+\&                             Cased=Yes) (1951)
+\&   \ep{XPosixWord}          \ew, including beyond ASCII; = \ep{Alnum} +
+\&                             \epM + \ep{Pc} + \ep{Join_Control} (Short:
+\&                             \ep{Word}) (139_612: [0\-9A\-Z_a\-z\exaa\exb5
+\&                             \exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                             U+0100..02C1, U+02C6..02D1,
+\&                             U+02E0..02E4, U+02EC, U+02EE ...)
+\&   \ep{XPosixXDigit}        \ep{Hex_Digit=Y} (Short: \ep{Hex}) (44)
+\&   \ep{Xsux}                \ep{Cuneiform} (= \ep{Script_Extensions=
+\&                             Cuneiform}) (NOT \ep{Block=Cuneiform})
+\&                             (1234)
+\&   \ep{Yezi}                \ep{Yezidi} (= \ep{Script_Extensions=
+\&                             Yezidi}) (NOT \ep{Block=Yezidi}) (60)
+\&   \ep{Yezidi}              \ep{Script_Extensions=Yezidi} (Short:
+\&                             \ep{Yezi}; NOT \ep{Block=Yezidi}) (60)
+\&   \ep{Yi}                  \ep{Script_Extensions=Yi} (1246)
+\& X \ep{Yi_Radicals}         \ep{Block=Yi_Radicals} (64)
+\& X \ep{Yi_Syllables}        \ep{Block=Yi_Syllables} (1168)
+\&   \ep{Yiii}                \ep{Yi} (= \ep{Script_Extensions=Yi}) (1246)
+\& X \ep{Yijing}              \ep{Yijing_Hexagram_Symbols} (= \ep{Block=
+\&                             Yijing_Hexagram_Symbols}) (64)
+\& X \ep{Yijing_Hexagram_Symbols} \ep{Block=Yijing_Hexagram_Symbols}
+\&                             (Short: \ep{InYijing}) (64)
+\&   \ep{Z} \epZ               \ep{Separator} (= \ep{General_Category=
+\&                             Separator}) (19)
+\&   \ep{Zanabazar_Square}    \ep{Script_Extensions=Zanabazar_Square}
+\&                             (Short: \ep{Zanb}; NOT \ep{Block=
+\&                             Zanabazar_Square}) (72)
+\&   \ep{Zanb}                \ep{Zanabazar_Square} (=
+\&                             \ep{Script_Extensions=Zanabazar_Square})
+\&                             (NOT \ep{Block=Zanabazar_Square}) (72)
+\&   \ep{Zinh}                \ep{Inherited} (= \ep{Script_Extensions=
+\&                             Inherited}) (586)
+\&   \ep{Zl}                  \ep{Line_Separator} (= \ep{General_Category=
+\&                             Line_Separator}) (1)
+\& X \ep{Znamenny_Music}      \ep{Znamenny_Musical_Notation} (= \ep{Block=
+\&                             Znamenny_Musical_Notation}) (208)
+\& X \ep{Znamenny_Musical_Notation} \ep{Block=Znamenny_Musical_Notation}
+\&                             (Short: \ep{InZnamennyMusic}) (208)
+\&   \ep{Zp}                  \ep{Paragraph_Separator} (=
+\&                             \ep{General_Category=
+\&                             Paragraph_Separator}) (1)
+\&   \ep{Zs}                  \ep{Space_Separator} (=
+\&                             \ep{General_Category=Space_Separator})
+\&                             (17)
+\&   \ep{Zyyy}                \ep{Common} (= \ep{Script_Extensions=
+\&                             Common}) (7873)
+\&   \ep{Zzzz}                \ep{Unknown} (= \ep{Script_Extensions=
+\&                             Unknown}) (964_861 plus all above\-
+\&                             Unicode code points)
+.Ve
+.ie n .SS "Legal ""\ep{}"" and ""\eP{}"" constructs that match no characters"
+.el .SS "Legal \f(CW\ep{}\fP and \f(CW\eP{}\fP constructs that match no characters"
+.IX Subsection "Legal p{} and P{} constructs that match no characters"
+Unicode has some property-value pairs that currently don't match anything.
+This happens generally either because they are obsolete, or they exist for
+symmetry with other forms, but no language has yet been encoded that uses
+them.  In this version of Unicode, the following match zero code points:
+.IP \ep{Canonical_Combining_Class=Attached_Below_Left} 4
+.IX Item "p{Canonical_Combining_Class=Attached_Below_Left}"
+.PD 0
+.IP \ep{Canonical_Combining_Class=CCC133} 4
+.IX Item "p{Canonical_Combining_Class=CCC133}"
+.IP \ep{Grapheme_Cluster_Break=E_Base} 4
+.IX Item "p{Grapheme_Cluster_Break=E_Base}"
+.IP \ep{Grapheme_Cluster_Break=E_Base_GAZ} 4
+.IX Item "p{Grapheme_Cluster_Break=E_Base_GAZ}"
+.IP \ep{Grapheme_Cluster_Break=E_Modifier} 4
+.IX Item "p{Grapheme_Cluster_Break=E_Modifier}"
+.IP \ep{Grapheme_Cluster_Break=Glue_After_Zwj} 4
+.IX Item "p{Grapheme_Cluster_Break=Glue_After_Zwj}"
+.IP \ep{Word_Break=E_Base} 4
+.IX Item "p{Word_Break=E_Base}"
+.IP \ep{Word_Break=E_Base_GAZ} 4
+.IX Item "p{Word_Break=E_Base_GAZ}"
+.IP \ep{Word_Break=E_Modifier} 4
+.IX Item "p{Word_Break=E_Modifier}"
+.IP \ep{Word_Break=Glue_After_Zwj} 4
+.IX Item "p{Word_Break=Glue_After_Zwj}"
+.PD
+.SH "Properties accessible through Unicode::UCD"
+.IX Header "Properties accessible through Unicode::UCD"
+The value of any Unicode (not including Perl extensions) character
+property mentioned above for any single code point is available through
+"\fBcharprop()\fR" in Unicode::UCD.  "\fBcharprops_all()\fR" in Unicode::UCD returns the
+values of all the Unicode properties for a given code point.
+.PP
+Besides these, all the Unicode character properties mentioned above
+(except for those marked as for internal use by Perl) are also
+accessible by "\fBprop_invlist()\fR" in Unicode::UCD.
+.PP
+Due to their nature, not all Unicode character properties are suitable for
+regular expression matches, nor \f(CWprop_invlist()\fR.  The remaining
+non-provisional, non-internal ones are accessible via
+"\fBprop_invmap()\fR" in Unicode::UCD (except for those that this Perl installation
+hasn't included; see below for which those are).
+.PP
+For compatibility with other parts of Perl, all the single forms given in the
+table in the section above
+are recognized.  BUT, there are some ambiguities between some Perl extensions
+and the Unicode properties, all of which are silently resolved in favor of the
+official Unicode property.  To avoid surprises, you should only use
+\&\f(CWprop_invmap()\fR for forms listed in the table below, which omits the
+non-recommended ones.  The affected forms are the Perl single form equivalents
+of Unicode properties, such as \f(CW\*(C`\ep{sc}\*(C'\fR being a single-form equivalent of
+\&\f(CW\*(C`\ep{gc=sc}\*(C'\fR, which is treated by \f(CWprop_invmap()\fR as the \f(CW\*(C`Script\*(C'\fR property,
+whose short name is \f(CW\*(C`sc\*(C'\fR.  The table indicates the current ambiguities in the
+INFO column, beginning with the word \f(CW"NOT"\fR.
+.PP
+The standard Unicode properties listed below are documented in
+<http://www.unicode.org/reports/tr44/>; Perl_Decimal_Digit is documented in
+"\fBprop_invmap()\fR" in Unicode::UCD.  The other Perl extensions are in
+"Other Properties" in perlunicode;
+.PP
+The first column in the table is a name for the property; the second column is
+an alternative name, if any, plus possibly some annotations.  The alternative
+name is the property's full name, unless that would simply repeat the first
+column, in which case the second column indicates the property's short name
+(if different).  The annotations are given only in the entry for the full
+name.  The annotations for binary properties include a list of the first few
+ranges that the property matches.  To avoid any ambiguity, the SPACE character
+is represented as \f(CW\*(C`\ex20\*(C'\fR.
+.PP
+If a property is obsolete, etc, the entry will be flagged with the same
+characters used in the table in the section above, like \fBD\fR or \fBS\fR.
+.PP
+.Vb 1
+\&   NAME                      INFO
+\&
+\&   Age
+\&   AHex                    ASCII_Hex_Digit
+\&   All                     (Perl extension).  All code points,
+\&                           including those above Unicode.  Same as
+\&                           qr/./s.  U+0000..infinity
+\&   Alnum                   XPosixAlnum.  (Perl extension)
+\&   Alpha                   Alphabetic
+\&   Alphabetic              (Short: Alpha).  [A\-Za\-z\exaa\exb5\exba\exc0\-
+\&                           \exd6\exd8\-\exf6\exf8\-\exff], U+0100..02C1,
+\&                           U+02C6..02D1, U+02E0..02E4, U+02EC, U+02EE
+\&                           ...
+\&   Any                     (Perl extension).  All Unicode code
+\&                           points.  U+0000..10FFFF
+\&   ASCII                   Block=Basic_Latin.  (Perl extension).
+\&                           [\ex00\-\ex7f]
+\&   ASCII_Hex_Digit         (Short: AHex).  [0\-9A\-Fa\-f]
+\&   Assigned                (Perl extension).  All assigned code
+\&                           points.  U+0000..0377, U+037A..037F,
+\&                           U+0384..038A, U+038C, U+038E..03A1,
+\&                           U+03A3..052F ...
+\&   Bc                      Bidi_Class
+\&   Bidi_C                  Bidi_Control
+\&   Bidi_Class              (Short: bc)
+\&   Bidi_Control            (Short: Bidi_C).  U+061C, U+200E..200F,
+\&                           U+202A..202E, U+2066..2069
+\&   Bidi_M                  Bidi_Mirrored
+\&   Bidi_Mirrored           (Short: Bidi_M).  [\e(\e)<>\e[\e]\e{\e}\exab
+\&                           \exbb], U+0F3A..0F3D, U+169B..169C,
+\&                           U+2039..203A, U+2045..2046, U+207D..207E
+\&                           ...
+\&   Bidi_Mirroring_Glyph    (Short: bmg)
+\&   Bidi_Paired_Bracket     (Short: bpb)
+\&   Bidi_Paired_Bracket_Type (Short: bpt)
+\&   Blank                   XPosixBlank.  (Perl extension)
+\&   Blk                     Block
+\&   Block                   (Short: blk)
+\&   Bmg                     Bidi_Mirroring_Glyph
+\&   Bpb                     Bidi_Paired_Bracket
+\&   Bpt                     Bidi_Paired_Bracket_Type
+\&   Canonical_Combining_Class (Short: ccc)
+\&   Case_Folding            (Short: cf)
+\&   Case_Ignorable          (Short: CI).  [\e\*(Aq.:\e^\`\exa8\exad\exaf\exb4
+\&                           \exb7\-\exb8], U+02B0..036F, U+0374..0375,
+\&                           U+037A, U+0384..0385, U+0387 ...
+\&   Cased                   [A\-Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-
+\&                           \exff], U+0100..01BA, U+01BC..01BF,
+\&                           U+01C4..0293, U+0295..02B8, U+02C0..02C1
+\&                           ...
+\&   Category                General_Category
+\&   Ccc                     Canonical_Combining_Class
+\&   CE                      Composition_Exclusion
+\&   Cf                      Case_Folding; NOT \*(Aqcf\*(Aq meaning
+\&                           \*(AqGeneral_Category=Format\*(Aq
+\&   Changes_When_Casefolded (Short: CWCF).  [A\-Z\exb5\exc0\-\exd6\exd8\-
+\&                           \exdf], U+0100, U+0102, U+0104, U+0106,
+\&                           U+0108 ...
+\&   Changes_When_Casemapped (Short: CWCM).  [A\-Za\-z\exb5\exc0\-\exd6\exd8\-
+\&                           \exf6\exf8\-\exff], U+0100..0137,
+\&                           U+0139..018C, U+018E..019A, U+019C..01A9,
+\&                           U+01AC..01B9 ...
+\&   Changes_When_Lowercased (Short: CWL).  [A\-Z\exc0\-\exd6\exd8\-\exde],
+\&                           U+0100, U+0102, U+0104, U+0106, U+0108 ...
+\&   Changes_When_NFKC_Casefolded (Short: CWKCF).  [A\-Z\exa0\exa8\exaa
+\&                           \exad\exaf\exb2\-\exb5\exb8\-\exba\exbc\-\exbe\exc0\-
+\&                           \exd6\exd8\-\exdf], U+0100, U+0102, U+0104,
+\&                           U+0106, U+0108 ...
+\&   Changes_When_Titlecased (Short: CWT).  [a\-z\exb5\exdf\-\exf6\exf8\-
+\&                           \exff], U+0101, U+0103, U+0105, U+0107,
+\&                           U+0109 ...
+\&   Changes_When_Uppercased (Short: CWU).  [a\-z\exb5\exdf\-\exf6\exf8\-
+\&                           \exff], U+0101, U+0103, U+0105, U+0107,
+\&                           U+0109 ...
+\&   CI                      Case_Ignorable
+\&   Cntrl                   XPosixCntrl (=General_Category=Control).
+\&                           (Perl extension)
+\&   Comp_Ex                 Full_Composition_Exclusion
+\&   Composition_Exclusion   (Short: CE).  U+0958..095F, U+09DC..09DD,
+\&                           U+09DF, U+0A33, U+0A36, U+0A59..0A5B ...
+\&   CWCF                    Changes_When_Casefolded
+\&   CWCM                    Changes_When_Casemapped
+\&   CWKCF                   Changes_When_NFKC_Casefolded
+\&   CWL                     Changes_When_Lowercased
+\&   CWT                     Changes_When_Titlecased
+\&   CWU                     Changes_When_Uppercased
+\&   Dash                    [\e\-], U+058A, U+05BE, U+1400, U+1806,
+\&                           U+2010..2015 ...
+\&   Decomposition_Mapping   (Short: dm)
+\&   Decomposition_Type      (Short: dt)
+\&   Default_Ignorable_Code_Point (Short: DI).  [\exad], U+034F, U+061C,
+\&                           U+115F..1160, U+17B4..17B5, U+180B..180F
+\&                           ...
+\&   Dep                     Deprecated
+\&   Deprecated              (Short: Dep).  U+0149, U+0673, U+0F77,
+\&                           U+0F79, U+17A3..17A4, U+206A..206F ...
+\&   DI                      Default_Ignorable_Code_Point
+\&   Dia                     Diacritic
+\&   Diacritic               (Short: Dia).  [\e^\`\exa8\exaf\exb4\exb7\-\exb8],
+\&                           U+02B0..034E, U+0350..0357, U+035D..0362,
+\&                           U+0374..0375, U+037A ...
+\&   Digit                   XPosixDigit (=General_Category=
+\&                           Decimal_Number).  (Perl extension)
+\&   Dm                      Decomposition_Mapping
+\&   Dt                      Decomposition_Type
+\&   Ea                      East_Asian_Width
+\&   East_Asian_Width        (Short: ea)
+\&   EBase                   Emoji_Modifier_Base
+\&   EComp                   Emoji_Component
+\&   EMod                    Emoji_Modifier
+\&   Emoji                   [#*0\-9\exa9\exae], U+203C, U+2049, U+2122,
+\&                           U+2139, U+2194..2199 ...
+\&   Emoji_Component         (Short: EComp).  [#*0\-9], U+200D, U+20E3,
+\&                           U+FE0F, U+1F1E6..1F1FF, U+1F3FB..1F3FF ...
+\&   Emoji_Modifier          (Short: EMod).  U+1F3FB..1F3FF
+\&   Emoji_Modifier_Base     (Short: EBase).  U+261D, U+26F9,
+\&                           U+270A..270D, U+1F385, U+1F3C2..1F3C4,
+\&                           U+1F3C7 ...
+\&   Emoji_Presentation      (Short: EPres).  U+231A..231B,
+\&                           U+23E9..23EC, U+23F0, U+23F3,
+\&                           U+25FD..25FE, U+2614..2615 ...
+\&   EPres                   Emoji_Presentation
+\&   EqUIdeo                 Equivalent_Unified_Ideograph
+\&   Equivalent_Unified_Ideograph (Short: EqUIdeo)
+\&   Ext                     Extender
+\&   Extended_Pictographic   (Short: ExtPict).  [\exa9\exae], U+203C,
+\&                           U+2049, U+2122, U+2139, U+2194..2199 ...
+\&   Extender                (Short: Ext).  [\exb7], U+02D0..02D1,
+\&                           U+0640, U+07FA, U+0B55, U+0E46 ...
+\&   ExtPict                 Extended_Pictographic
+\&   Full_Composition_Exclusion (Short: Comp_Ex).  U+0340..0341,
+\&                           U+0343..0344, U+0374, U+037E, U+0387,
+\&                           U+0958..095F ...
+\&   Gc                      General_Category
+\&   GCB                     Grapheme_Cluster_Break
+\&   General_Category        (Short: gc)
+\&   Gr_Base                 Grapheme_Base
+\&   Gr_Ext                  Grapheme_Extend
+\&   Graph                   XPosixGraph.  (Perl extension)
+\&   Grapheme_Base           (Short: Gr_Base).  [\ex20\-\ex7e\exa0\-\exac
+\&                           \exae\-\exff], U+0100..02FF, U+0370..0377,
+\&                           U+037A..037F, U+0384..038A, U+038C ...
+\&   Grapheme_Cluster_Break  (Short: GCB)
+\&   Grapheme_Extend         (Short: Gr_Ext).  U+0300..036F,
+\&                           U+0483..0489, U+0591..05BD, U+05BF,
+\&                           U+05C1..05C2, U+05C4..05C5 ...
+\&   Hangul_Syllable_Type    (Short: hst)
+\&   Hex                     Hex_Digit
+\&   Hex_Digit               (Short: Hex).  [0\-9A\-Fa\-f], U+FF10..FF19,
+\&                           U+FF21..FF26, U+FF41..FF46
+\&   HorizSpace              XPosixBlank.  (Perl extension)
+\&   Hst                     Hangul_Syllable_Type
+\& D Hyphen                  [\e\-\exad], U+058A, U+1806, U+2010..2011,
+\&                           U+2E17, U+30FB ...  Supplanted by
+\&                           Line_Break property values; see
+\&                           www.unicode.org/reports/tr14
+\&   ID_Continue             (Short: IDC).  [0\-9A\-Z_a\-z\exaa\exb5\exb7
+\&                           \exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                           U+0100..02C1, U+02C6..02D1, U+02E0..02E4,
+\&                           U+02EC, U+02EE ...
+\&   ID_Start                (Short: IDS).  [A\-Za\-z\exaa\exb5\exba\exc0\-
+\&                           \exd6\exd8\-\exf6\exf8\-\exff], U+0100..02C1,
+\&                           U+02C6..02D1, U+02E0..02E4, U+02EC, U+02EE
+\&                           ...
+\&   IDC                     ID_Continue
+\&   Identifier_Status
+\&   Identifier_Type
+\&   Ideo                    Ideographic
+\&   Ideographic             (Short: Ideo).  U+3006..3007,
+\&                           U+3021..3029, U+3038..303A, U+3400..4DBF,
+\&                           U+4E00..9FFF, U+F900..FA6D ...
+\&   IDS                     ID_Start
+\&   IDS_Binary_Operator     (Short: IDSB).  U+2FF0..2FF1, U+2FF4..2FFB
+\&   IDS_Trinary_Operator    (Short: IDST).  U+2FF2..2FF3
+\&   IDSB                    IDS_Binary_Operator
+\&   IDST                    IDS_Trinary_Operator
+\&   In                      Present_In.  (Perl extension)
+\&   Indic_Positional_Category (Short: InPC)
+\&   Indic_Syllabic_Category (Short: InSC)
+\&   InPC                    Indic_Positional_Category
+\&   InSC                    Indic_Syllabic_Category
+\&   Isc                     ISO_Comment; NOT \*(Aqisc\*(Aq meaning
+\&                           \*(AqGeneral_Category=Other\*(Aq
+\&   ISO_Comment             (Short: isc)
+\&   Jg                      Joining_Group
+\&   Join_C                  Join_Control
+\&   Join_Control            (Short: Join_C).  U+200C..200D
+\&   Joining_Group           (Short: jg)
+\&   Joining_Type            (Short: jt)
+\&   Jt                      Joining_Type
+\&   Lb                      Line_Break
+\&   Lc                      Lowercase_Mapping; NOT \*(Aqlc\*(Aq meaning
+\&                           \*(AqGeneral_Category=Cased_Letter\*(Aq
+\&   Line_Break              (Short: lb)
+\&   LOE                     Logical_Order_Exception
+\&   Logical_Order_Exception (Short: LOE).  U+0E40..0E44, U+0EC0..0EC4,
+\&                           U+19B5..19B7, U+19BA, U+AAB5..AAB6, U+AAB9
+\&                           ...
+\&   Lower                   Lowercase
+\&   Lowercase               (Short: Lower).  [a\-z\exaa\exb5\exba\exdf\-
+\&                           \exf6\exf8\-\exff], U+0101, U+0103, U+0105,
+\&                           U+0107, U+0109 ...
+\&   Lowercase_Mapping       (Short: lc)
+\&   Math                    [+<=>\e^\e|~\exac\exb1\exd7\exf7], U+03D0..03D2,
+\&                           U+03D5, U+03F0..03F1, U+03F4..03F6,
+\&                           U+0606..0608 ...
+\&   Na                      Name
+\&   Na1                     Unicode_1_Name
+\&   Name                    (Short: na)
+\&   Name_Alias
+\&   NChar                   Noncharacter_Code_Point
+\&   NFC_QC                  NFC_Quick_Check
+\&   NFC_Quick_Check         (Short: NFC_QC)
+\&   NFD_QC                  NFD_Quick_Check
+\&   NFD_Quick_Check         (Short: NFD_QC)
+\&   NFKC_Casefold           (Short: NFKC_CF)
+\&   NFKC_CF                 NFKC_Casefold
+\&   NFKC_QC                 NFKC_Quick_Check
+\&   NFKC_Quick_Check        (Short: NFKC_QC)
+\&   NFKD_QC                 NFKD_Quick_Check
+\&   NFKD_Quick_Check        (Short: NFKD_QC)
+\&   Noncharacter_Code_Point (Short: NChar).  U+FDD0..FDEF,
+\&                           U+FFFE..FFFF, U+1FFFE..1FFFF,
+\&                           U+2FFFE..2FFFF, U+3FFFE..3FFFF,
+\&                           U+4FFFE..4FFFF ...
+\&   Nt                      Numeric_Type
+\&   Numeric_Type            (Short: nt)
+\&   Numeric_Value           (Short: nv)
+\&   Nv                      Numeric_Value
+\&   Pat_Syn                 Pattern_Syntax
+\&   Pat_WS                  Pattern_White_Space
+\&   Pattern_Syntax          (Short: Pat_Syn).  [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                           \e/:;<=>?\e@\e[\e\e\e]\e^\`\e{\e|\e}~\exa1\-\exa7\exa9
+\&                           \exab\-\exac\exae\exb0\-\exb1\exb6\exbb\exbf\exd7
+\&                           \exf7], U+2010..2027, U+2030..203E,
+\&                           U+2041..2053, U+2055..205E, U+2190..245F
+\&                           ...
+\&   Pattern_White_Space     (Short: Pat_WS).  [\et\en\ecK\ef\er\ex20\ex85],
+\&                           U+200E..200F, U+2028..2029
+\&   PCM                     Prepended_Concatenation_Mark
+\&   Perl_Decimal_Digit      (Perl extension)
+\&   PerlSpace               PosixSpace.  (Perl extension)
+\&   PerlWord                PosixWord.  (Perl extension)
+\&   PosixAlnum              (Perl extension).  [0\-9A\-Za\-z]
+\&   PosixAlpha              (Perl extension).  [A\-Za\-z]
+\&   PosixBlank              (Perl extension).  [\et\ex20]
+\&   PosixCntrl              (Perl extension).  ASCII control
+\&                           characters.  ACK, BEL, BS, CAN, CR, DC1,
+\&                           DC2, DC3, DC4, DEL, DLE, ENQ, EOM, EOT,
+\&                           ESC, ETB, ETX, FF, FS, GS, HT, LF, NAK,
+\&                           NUL, RS, SI, SO, SOH, STX, SUB, SYN, US, VT
+\&   PosixDigit              (Perl extension).  [0\-9]
+\&   PosixGraph              (Perl extension).  [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                           \e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]\e^_\`a\-z\e{\e|\e}~]
+\&   PosixLower              (Perl extension).  [a\-z]
+\&   PosixPrint              (Perl extension).  [\ex20\-\ex7e]
+\&   PosixPunct              (Perl extension).  [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.
+\&                           \e/:;<=>?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~]
+\&   PosixSpace              (Perl extension).  [\et\en\ecK\ef\er\ex20]
+\&   PosixUpper              (Perl extension).  [A\-Z]
+\&   PosixWord               (Perl extension).  \ew, restricted to
+\&                           ASCII.  [0\-9A\-Z_a\-z]
+\&   PosixXDigit             ASCII_Hex_Digit.  (Perl extension).
+\&                           [0\-9A\-Fa\-f]
+\&   Prepended_Concatenation_Mark (Short: PCM).  U+0600..0605, U+06DD,
+\&                           U+070F, U+0890..0891, U+08E2, U+110BD ...
+\&   Present_In              (Short: In).  (Perl extension)
+\&   Print                   XPosixPrint.  (Perl extension)
+\&   Punct                   General_Category=Punctuation.  (Perl
+\&                           extension).  [!\e"#\e%&\e\*(Aq\e(\e)*,\e\-.\e/:;?\e@
+\&                           \e[\e\e\e]_\e{\e}\exa1\exa7\exab\exb6\-\exb7\exbb\exbf],
+\&                           U+037E, U+0387, U+055A..055F,
+\&                           U+0589..058A, U+05BE ...
+\&   QMark                   Quotation_Mark
+\&   Quotation_Mark          (Short: QMark).  [\e"\e\*(Aq\exab\exbb],
+\&                           U+2018..201F, U+2039..203A, U+2E42,
+\&                           U+300C..300F, U+301D..301F ...
+\&   Radical                 U+2E80..2E99, U+2E9B..2EF3, U+2F00..2FD5
+\&   Regional_Indicator      (Short: RI).  U+1F1E6..1F1FF
+\&   RI                      Regional_Indicator
+\&   SB                      Sentence_Break
+\&   Sc                      Script; NOT \*(Aqsc\*(Aq meaning
+\&                           \*(AqGeneral_Category=Currency_Symbol\*(Aq
+\&   Scf                     Simple_Case_Folding
+\&   Script                  (Short: sc)
+\&   Script_Extensions       (Short: scx)
+\&   Scx                     Script_Extensions
+\&   SD                      Soft_Dotted
+\&   Sentence_Break          (Short: SB)
+\&   Sentence_Terminal       (Short: STerm).  [!.?], U+0589,
+\&                           U+061D..061F, U+06D4, U+0700..0702, U+07F9
+\&                           ...
+\&   Sfc                     Simple_Case_Folding
+\&   Simple_Case_Folding     (Short: scf)
+\&   Simple_Lowercase_Mapping (Short: slc)
+\&   Simple_Titlecase_Mapping (Short: stc)
+\&   Simple_Uppercase_Mapping (Short: suc)
+\&   Slc                     Simple_Lowercase_Mapping
+\&   Soft_Dotted             (Short: SD).  [i\-j], U+012F, U+0249,
+\&                           U+0268, U+029D, U+02B2 ...
+\&   Space                   White_Space
+\&   SpacePerl               XPosixSpace.  (Perl extension)
+\&   Stc                     Simple_Titlecase_Mapping
+\&   STerm                   Sentence_Terminal
+\&   Suc                     Simple_Uppercase_Mapping
+\&   Tc                      Titlecase_Mapping
+\&   Term                    Terminal_Punctuation
+\&   Terminal_Punctuation    (Short: Term).  [!,.:;?], U+037E, U+0387,
+\&                           U+0589, U+05C3, U+060C ...
+\&   Title                   Titlecase.  (Perl extension)
+\&   Titlecase               (Short: Title).  (Perl extension).  (=
+\&                           \ep{Gc=Lt}).  U+01C5, U+01C8, U+01CB,
+\&                           U+01F2, U+1F88..1F8F, U+1F98..1F9F ...
+\&   Titlecase_Mapping       (Short: tc)
+\&   Uc                      Uppercase_Mapping
+\&   UIdeo                   Unified_Ideograph
+\&   Unicode                 Any.  (Perl extension)
+\&   Unicode_1_Name          (Short: na1)
+\&   Unified_Ideograph       (Short: UIdeo).  U+3400..4DBF,
+\&                           U+4E00..9FFF, U+FA0E..FA0F, U+FA11,
+\&                           U+FA13..FA14, U+FA1F ...
+\&   Upper                   Uppercase
+\&   Uppercase               (Short: Upper).  [A\-Z\exc0\-\exd6\exd8\-\exde],
+\&                           U+0100, U+0102, U+0104, U+0106, U+0108 ...
+\&   Uppercase_Mapping       (Short: uc)
+\&   Variation_Selector      (Short: VS).  U+180B..180D, U+180F,
+\&                           U+FE00..FE0F, U+E0100..E01EF
+\&   Vertical_Orientation    (Short: vo)
+\&   VertSpace               (Perl extension).  \ev.  [\en\ecK\ef\er\ex85],
+\&                           U+2028..2029
+\&   Vo                      Vertical_Orientation
+\&   VS                      Variation_Selector
+\&   WB                      Word_Break
+\&   White_Space             (Short: WSpace).  [\et\en\ecK\ef\er\ex20\ex85
+\&                           \exa0], U+1680, U+2000..200A, U+2028..2029,
+\&                           U+202F, U+205F ...
+\&   Word                    XPosixWord.  (Perl extension)
+\&   Word_Break              (Short: WB)
+\&   WSpace                  White_Space
+\&   XDigit                  XPosixXDigit (=Hex_Digit).  (Perl
+\&                           extension)
+\&   XID_Continue            (Short: XIDC).  [0\-9A\-Z_a\-z\exaa\exb5\exb7
+\&                           \exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                           U+0100..02C1, U+02C6..02D1, U+02E0..02E4,
+\&                           U+02EC, U+02EE ...
+\&   XID_Start               (Short: XIDS).  [A\-Za\-z\exaa\exb5\exba\exc0\-
+\&                           \exd6\exd8\-\exf6\exf8\-\exff], U+0100..02C1,
+\&                           U+02C6..02D1, U+02E0..02E4, U+02EC, U+02EE
+\&                           ...
+\&   XIDC                    XID_Continue
+\&   XIDS                    XID_Start
+\&   XPerlSpace              XPosixSpace.  (Perl extension)
+\&   XPosixAlnum             (Short: Alnum).  (Perl extension).
+\&                           Alphabetic and (decimal) Numeric.  [0\-9A\-
+\&                           Za\-z\exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-
+\&                           \exff], U+0100..02C1, U+02C6..02D1,
+\&                           U+02E0..02E4, U+02EC, U+02EE ...
+\&   XPosixAlpha             Alphabetic.  (Perl extension).  [A\-Za\-z
+\&                           \exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                           U+0100..02C1, U+02C6..02D1, U+02E0..02E4,
+\&                           U+02EC, U+02EE ...
+\&   XPosixBlank             (Short: Blank).  (Perl extension).  \eh,
+\&                           Horizontal white space.  [\et\ex20\exa0],
+\&                           U+1680, U+2000..200A, U+202F, U+205F,
+\&                           U+3000
+\&   XPosixCntrl             General_Category=Control  (Short: Cntrl).
+\&                           (Perl extension).  Control characters.
+\&                           [\ex00\-\ex1f\ex7f\-\ex9f]
+\&   XPosixDigit             General_Category=Decimal_Number  (Short:
+\&                           Digit).  (Perl extension).  [0\-9] + all
+\&                           other decimal digits.  [0\-9],
+\&                           U+0660..0669, U+06F0..06F9, U+07C0..07C9,
+\&                           U+0966..096F, U+09E6..09EF ...
+\&   XPosixGraph             (Short: Graph).  (Perl extension).
+\&                           Characters that are graphical.  [!\e"#\e$
+\&                           \e%&\e\*(Aq\e(\e)*+,\e\-.\e/0\-9:;<=>?\e@A\-Z\e[\e\e\e]
+\&                           \e^_\`a\-z\e{\e|\e}~\exa1\-\exff], U+0100..0377,
+\&                           U+037A..037F, U+0384..038A, U+038C,
+\&                           U+038E..03A1 ...
+\&   XPosixLower             Lowercase.  (Perl extension).  [a\-z\exaa
+\&                           \exb5\exba\exdf\-\exf6\exf8\-\exff], U+0101,
+\&                           U+0103, U+0105, U+0107, U+0109 ...
+\&   XPosixPrint             (Short: Print).  (Perl extension).
+\&                           Characters that are graphical plus space
+\&                           characters (but no controls).  [\ex20\-\ex7e
+\&                           \exa0\-\exff], U+0100..0377, U+037A..037F,
+\&                           U+0384..038A, U+038C, U+038E..03A1 ...
+\&   XPosixPunct             (Perl extension).  \ep{Punct} + ASCII\-range
+\&                           \ep{Symbol}.  [!\e"#\e$\e%&\e\*(Aq\e(\e)*+,\e\-.\e/:;<=
+\&                           >?\e@\e[\e\e\e]\e^_\`\e{\e|\e}~\exa1\exa7\exab\exb6\-
+\&                           \exb7\exbb\exbf], U+037E, U+0387,
+\&                           U+055A..055F, U+0589..058A, U+05BE ...
+\&   XPosixSpace             (Perl extension).  \es including beyond
+\&                           ASCII and vertical tab.  [\et\en\ecK\ef\er\ex20
+\&                           \ex85\exa0], U+1680, U+2000..200A,
+\&                           U+2028..2029, U+202F, U+205F ...
+\&   XPosixUpper             Uppercase.  (Perl extension).  [A\-Z\exc0\-
+\&                           \exd6\exd8\-\exde], U+0100, U+0102, U+0104,
+\&                           U+0106, U+0108 ...
+\&   XPosixWord              (Short: Word).  (Perl extension).  \ew,
+\&                           including beyond ASCII; = \ep{Alnum} + \epM
+\&                           + \ep{Pc} + \ep{Join_Control}.  [0\-9A\-Z_a\-z
+\&                           \exaa\exb5\exba\exc0\-\exd6\exd8\-\exf6\exf8\-\exff],
+\&                           U+0100..02C1, U+02C6..02D1, U+02E0..02E4,
+\&                           U+02EC, U+02EE ...
+\&   XPosixXDigit            Hex_Digit  (Short: XDigit).  (Perl
+\&                           extension).  [0\-9A\-Fa\-f], U+FF10..FF19,
+\&                           U+FF21..FF26, U+FF41..FF46
+.Ve
+.SH "Properties accessible through other means"
+.IX Header "Properties accessible through other means"
+Certain properties are accessible also via core function calls.  These are:
+.PP
+.Vb 3
+\& Lowercase_Mapping          lc() and lcfirst()
+\& Titlecase_Mapping          ucfirst()
+\& Uppercase_Mapping          uc()
+.Ve
+.PP
+Also, Case_Folding is accessible through the \f(CW\*(C`/i\*(C'\fR modifier in regular
+expressions, the \f(CW\*(C`\eF\*(C'\fR transliteration escape, and the \f(CW\*(C`fc\*(C'\fR
+operator.
+.PP
+Besides being able to say \f(CW\*(C`\ep{Name=...}\*(C'\fR, the Name and Name_Aliases
+properties are accessible through the \f(CW\*(C`\eN{}\*(C'\fR interpolation in double-quoted
+strings and regular expressions; and functions \f(CWcharnames::viacode()\fR,
+\&\f(CWcharnames::vianame()\fR, and \f(CWcharnames::string_vianame()\fR (which require a
+\&\f(CW\*(C`use charnames ();\*(C'\fR to be specified.
+.PP
+Finally, most properties related to decomposition are accessible via
+Unicode::Normalize.
+.SH "Unicode character properties that are NOT accepted by Perl"
+.IX Header "Unicode character properties that are NOT accepted by Perl"
+Perl will generate an error for a few character properties in Unicode when
+used in a regular expression.  The non-Unihan ones are listed below, with the
+reasons they are not accepted, perhaps with work-arounds.  The short names for
+the properties are listed enclosed in (parentheses).
+As described after the list, an installation can change the defaults and choose
+to accept any of these.  The list is machine generated based on the
+choices made for the installation that generated this document.
+.IP "\fIExpands_On_NFC\fR (XO_NFC)" 4
+.IX Item "Expands_On_NFC (XO_NFC)"
+.PD 0
+.IP "\fIExpands_On_NFD\fR (XO_NFD)" 4
+.IX Item "Expands_On_NFD (XO_NFD)"
+.IP "\fIExpands_On_NFKC\fR (XO_NFKC)" 4
+.IX Item "Expands_On_NFKC (XO_NFKC)"
+.IP "\fIExpands_On_NFKD\fR (XO_NFKD)" 4
+.IX Item "Expands_On_NFKD (XO_NFKD)"
+.PD
+Deprecated by Unicode.  These are characters that expand to more than one character in the specified normalization form, but whether they actually take up more bytes or not depends on the encoding being used.  For example, a UTF\-8 encoded character may expand to a different number of bytes than a UTF\-32 encoded character.
+.IP "\fIGrapheme_Link\fR (Gr_Link)" 4
+.IX Item "Grapheme_Link (Gr_Link)"
+Duplicates ccc=vr (Canonical_Combining_Class=Virama)
+.IP "\fIJamo_Short_Name\fR (JSN)" 4
+.IX Item "Jamo_Short_Name (JSN)"
+.PD 0
+.IP "\fIOther_Alphabetic\fR (OAlpha)" 4
+.IX Item "Other_Alphabetic (OAlpha)"
+.IP "\fIOther_Default_Ignorable_Code_Point\fR (ODI)" 4
+.IX Item "Other_Default_Ignorable_Code_Point (ODI)"
+.IP "\fIOther_Grapheme_Extend\fR (OGr_Ext)" 4
+.IX Item "Other_Grapheme_Extend (OGr_Ext)"
+.IP "\fIOther_ID_Continue\fR (OIDC)" 4
+.IX Item "Other_ID_Continue (OIDC)"
+.IP "\fIOther_ID_Start\fR (OIDS)" 4
+.IX Item "Other_ID_Start (OIDS)"
+.IP "\fIOther_Lowercase\fR (OLower)" 4
+.IX Item "Other_Lowercase (OLower)"
+.IP "\fIOther_Math\fR (OMath)" 4
+.IX Item "Other_Math (OMath)"
+.IP "\fIOther_Uppercase\fR (OUpper)" 4
+.IX Item "Other_Uppercase (OUpper)"
+.PD
+Used by Unicode internally for generating other properties and not intended to be used stand-alone
+.IP "\fIScript=Katakana_Or_Hiragana\fR (sc=Hrkt)" 4
+.IX Item "Script=Katakana_Or_Hiragana (sc=Hrkt)"
+Obsolete.  All code points previously matched by this have been moved to "Script=Common".  Consider instead using "Script_Extensions=Katakana" or "Script_Extensions=Hiragana" (or both)
+.IP "\fIScript_Extensions=Katakana_Or_Hiragana\fR (scx=Hrkt)" 4
+.IX Item "Script_Extensions=Katakana_Or_Hiragana (scx=Hrkt)"
+All code points that would be matched by this are matched by either "Script_Extensions=Katakana" or "Script_Extensions=Hiragana"
+.PP
+An installation can choose to allow any of these to be matched by downloading
+the Unicode database from <http://www.unicode.org/Public/> to
+\&\f(CW$Config{privlib}\fR/\fIunicore/\fR in the Perl source tree, changing the
+controlling lists contained in the program
+\&\f(CW$Config{privlib}\fR/\fIunicore/mktables\fR and then re-compiling and installing.
+(\f(CW%Config\fR is available from the Config module).
+.PP
+Also, perl can be recompiled to operate on an earlier version of the Unicode
+standard.  Further information is at
+\&\f(CW$Config{privlib}\fR/\fIunicore/README.perl\fR.
+.SH "Other information in the Unicode data base"
+.IX Header "Other information in the Unicode data base"
+The Unicode data base is delivered in two different formats.  The XML version
+is valid for more modern Unicode releases.  The other version is a collection
+of files.  The two are intended to give equivalent information.  Perl uses the
+older form; this allows you to recompile Perl to use early Unicode releases.
+.PP
+The only non-character property that Perl currently supports is Named
+Sequences, in which a sequence of code points
+is given a name and generally treated as a single entity.  (Perl supports
+these via the \f(CW\*(C`\eN{...}\*(C'\fR double-quotish construct,
+"charnames::string_vianame(name)" in charnames, and "\fBnamedseq()\fR" in Unicode::UCD.
+.PP
+Below is a list of the files in the Unicode data base that Perl doesn't
+currently use, along with very brief descriptions of their purposes.
+Some of the names of the files have been shortened from those that Unicode
+uses, in order to allow them to be distinguishable from similarly named files
+on file systems for which only the first 8 characters of a name are
+significant.
+.IP \fIauxiliary/GraphemeBreakTest.html\fR 4
+.IX Item "auxiliary/GraphemeBreakTest.html"
+.PD 0
+.IP \fIauxiliary/LineBreakTest.html\fR 4
+.IX Item "auxiliary/LineBreakTest.html"
+.IP \fIauxiliary/SentenceBreakTest.html\fR 4
+.IX Item "auxiliary/SentenceBreakTest.html"
+.IP \fIauxiliary/WordBreakTest.html\fR 4
+.IX Item "auxiliary/WordBreakTest.html"
+.PD
+Documentation of validation Tests
+.IP \fIBidiCharacterTest.txt\fR 4
+.IX Item "BidiCharacterTest.txt"
+.PD 0
+.IP \fIBidiTest.txt\fR 4
+.IX Item "BidiTest.txt"
+.PD
+Validation Tests
+.IP \fICJKRadicals.txt\fR 4
+.IX Item "CJKRadicals.txt"
+Maps the kRSUnicode property values to corresponding code points
+.IP \fIconfusables.txt\fR 4
+.IX Item "confusables.txt"
+.PD 0
+.IP \fIconfusablesSummary.txt\fR 4
+.IX Item "confusablesSummary.txt"
+.IP \fIintentional.txt\fR 4
+.IX Item "intentional.txt"
+.PD
+Currently unused by Perl
+.IP \fIemoji/ReadMe.txt\fR 4
+.IX Item "emoji/ReadMe.txt"
+.PD 0
+.IP \fIReadMe.txt\fR 4
+.IX Item "ReadMe.txt"
+.PD
+Documentation
+.IP \fIEmojiSources.txt\fR 4
+.IX Item "EmojiSources.txt"
+Maps certain Unicode code points to their legacy Japanese cell-phone values
+.IP \fIextracted/DName.txt\fR 4
+.IX Item "extracted/DName.txt"
+This file adds no new information not already present in other files
+.IP \fIIndex.txt\fR 4
+.IX Item "Index.txt"
+Alphabetical index of Unicode characters
+.IP \fINamedSqProv.txt\fR 4
+.IX Item "NamedSqProv.txt"
+Named sequences proposed for inclusion in a later version of the Unicode Standard; if you need them now, you can append this file to \fINamedSequences.txt\fR and recompile perl
+.IP \fINamesList.html\fR 4
+.IX Item "NamesList.html"
+Describes the format and contents of \fINamesList.txt\fR
+.IP \fINamesList.txt\fR 4
+.IX Item "NamesList.txt"
+Annotated list of characters
+.IP \fINormalizationCorrections.txt\fR 4
+.IX Item "NormalizationCorrections.txt"
+Documentation of corrections already incorporated into the Unicode data base
+.IP \fINushuSources.txt\fR 4
+.IX Item "NushuSources.txt"
+Specifies source material for Nushu characters
+.IP \fIStandardizedVariants.html\fR 4
+.IX Item "StandardizedVariants.html"
+Obsoleted as of Unicode 9.0, but previously provided a visual display of the standard variant sequences derived from \fIStandardizedVariants.txt\fR.
+.IP \fIStandardizedVariants.txt\fR 4
+.IX Item "StandardizedVariants.txt"
+Certain glyph variations for character display are standardized.  This lists the non-Unihan ones; the Unihan ones are also not used by Perl, and are in a separate Unicode data base <http://www.unicode.org/ivd>
+.IP \fITangutSources.txt\fR 4
+.IX Item "TangutSources.txt"
+Specifies source mappings for Tangut ideographs and components. This data file also includes informative radical-stroke values that are used internally by Unicode
+.IP \fIUSourceData.txt\fR 4
+.IX Item "USourceData.txt"
+Documentation of status and cross reference of proposals for encoding by Unicode of Unihan characters
+.IP \fIUSourceGlyphs.pdf\fR 4
+.IX Item "USourceGlyphs.pdf"
+Pictures of the characters in \fIUSourceData.txt\fR
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+<http://www.unicode.org/reports/tr44/>
+.PP
+perlrecharclass
+.PP
+perlunicode
diff --git a/upstream/mageia-cauldron/man1/perlunitut.1 b/upstream/mageia-cauldron/man1/perlunitut.1
new file mode 100644
index 00000000..bb943ee2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlunitut.1
@@ -0,0 +1,285 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUNITUT 1"
+.TH PERLUNITUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlunitut \- Perl Unicode Tutorial
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The days of just flinging strings around are over. It's well established that
+modern programs need to be capable of communicating funny accented letters, and
+things like euro symbols. This means that programmers need new habits. It's
+easy to program Unicode capable software, but it does require discipline to do
+it right.
+.PP
+There's a lot to know about character sets, and text encodings. It's probably
+best to spend a full day learning all this, but the basics can be learned in
+minutes.
+.PP
+These are not the very basics, though. It is assumed that you already
+know the difference between bytes and characters, and realise (and accept!)
+that there are many different character sets and encodings, and that your
+program has to be explicit about them. Recommended reading is "The Absolute
+Minimum Every Software Developer Absolutely, Positively Must Know About Unicode
+and Character Sets (No Excuses!)" by Joel Spolsky, at
+<http://joelonsoftware.com/articles/Unicode.html>.
+.PP
+This tutorial speaks in rather absolute terms, and provides only a limited view
+of the wealth of character string related features that Perl has to offer. For
+most projects, this information will probably suffice.
+.SS Definitions
+.IX Subsection "Definitions"
+It's important to set a few things straight first. This is the most important
+part of this tutorial. This view may conflict with other information that you
+may have found on the web, but that's mostly because many sources are wrong.
+.PP
+You may have to re-read this entire section a few times...
+.PP
+\fIUnicode\fR
+.IX Subsection "Unicode"
+.PP
+\&\fBUnicode\fR is a character set with room for lots of characters. The ordinal
+value of a character is called a \fBcode point\fR.   (But in practice, the
+distinction between code point and character is blurred, so the terms often
+are used interchangeably.)
+.PP
+There are many, many code points, but computers work with bytes, and a byte has
+room for only 256 values.  Unicode has many more characters than that,
+so you need a method to make these accessible.
+.PP
+Unicode is encoded using several competing encodings, of which UTF\-8 is the
+most used. In a Unicode encoding, multiple subsequent bytes can be used to
+store a single code point, or simply: character.
+.PP
+\fIUTF\-8\fR
+.IX Subsection "UTF-8"
+.PP
+\&\fBUTF\-8\fR is a Unicode encoding. Many people think that Unicode and UTF\-8 are
+the same thing, but they're not. There are more Unicode encodings, but much of
+the world has standardized on UTF\-8.
+.PP
+UTF\-8 treats the first 128 codepoints, 0..127, the same as ASCII. They take
+only one byte per character. All other characters are encoded as two to
+four bytes using a complex scheme. Fortunately, Perl handles this for
+us, so we don't have to worry about this.
+.PP
+\fIText strings (character strings)\fR
+.IX Subsection "Text strings (character strings)"
+.PP
+\&\fBText strings\fR, or \fBcharacter strings\fR are made of characters. Bytes are
+irrelevant here, and so are encodings. Each character is just that: the
+character.
+.PP
+On a text string, you would do things like:
+.PP
+.Vb 4
+\&    $text =~ s/foo/bar/;
+\&    if ($string =~ /^\ed+$/) { ... }
+\&    $text = ucfirst $text;
+\&    my $character_count = length $text;
+.Ve
+.PP
+The value of a character (\f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`chr\*(C'\fR) is the corresponding Unicode code
+point.
+.PP
+\fIBinary strings (byte strings)\fR
+.IX Subsection "Binary strings (byte strings)"
+.PP
+\&\fBBinary strings\fR, or \fBbyte strings\fR are made of bytes. Here, you don't have
+characters, just bytes. All communication with the outside world (anything
+outside of your current Perl process) is done in binary.
+.PP
+On a binary string, you would do things like:
+.PP
+.Vb 4
+\&    my (@length_content) = unpack "(V/a)*", $binary;
+\&    $binary =~ s/\ex00\ex0F/\exFF\exF0/;  # for the brave :)
+\&    print {$fh} $binary;
+\&    my $byte_count = length $binary;
+.Ve
+.PP
+\fIEncoding\fR
+.IX Subsection "Encoding"
+.PP
+\&\fBEncoding\fR (as a verb) is the conversion from \fItext\fR to \fIbinary\fR. To encode,
+you have to supply the target encoding, for example \f(CW\*(C`iso\-8859\-1\*(C'\fR or \f(CW\*(C`UTF\-8\*(C'\fR.
+Some encodings, like the \f(CW\*(C`iso\-8859\*(C'\fR ("latin") range, do not support the full
+Unicode standard; characters that can't be represented are lost in the
+conversion.
+.PP
+\fIDecoding\fR
+.IX Subsection "Decoding"
+.PP
+\&\fBDecoding\fR is the conversion from \fIbinary\fR to \fItext\fR. To decode, you have to
+know what encoding was used during the encoding phase. And most of all, it must
+be something decodable. It doesn't make much sense to decode a PNG image into a
+text string.
+.PP
+\fIInternal format\fR
+.IX Subsection "Internal format"
+.PP
+Perl has an \fBinternal format\fR, an encoding that it uses to encode text strings
+so it can store them in memory. All text strings are in this internal format.
+In fact, text strings are never in any other format!
+.PP
+You shouldn't worry about what this format is, because conversion is
+automatically done when you decode or encode.
+.SS "Your new toolkit"
+.IX Subsection "Your new toolkit"
+Add to your standard heading the following line:
+.PP
+.Vb 1
+\&    use Encode qw(encode decode);
+.Ve
+.PP
+Or, if you're lazy, just:
+.PP
+.Vb 1
+\&    use Encode;
+.Ve
+.SS "I/O flow (the actual 5 minute tutorial)"
+.IX Subsection "I/O flow (the actual 5 minute tutorial)"
+The typical input/output flow of a program is:
+.PP
+.Vb 3
+\&    1. Receive and decode
+\&    2. Process
+\&    3. Encode and output
+.Ve
+.PP
+If your input is binary, and is supposed to remain binary, you shouldn't decode
+it to a text string, of course. But in all other cases, you should decode it.
+.PP
+Decoding can't happen reliably if you don't know how the data was encoded. If
+you get to choose, it's a good idea to standardize on UTF\-8.
+.PP
+.Vb 3
+\&    my $foo   = decode(\*(AqUTF\-8\*(Aq, get \*(Aqhttp://example.com/\*(Aq);
+\&    my $bar   = decode(\*(AqISO\-8859\-1\*(Aq, readline STDIN);
+\&    my $xyzzy = decode(\*(AqWindows\-1251\*(Aq, $cgi\->param(\*(Aqfoo\*(Aq));
+.Ve
+.PP
+Processing happens as you knew before. The only difference is that you're now
+using characters instead of bytes. That's very useful if you use things like
+\&\f(CW\*(C`substr\*(C'\fR, or \f(CW\*(C`length\*(C'\fR.
+.PP
+It's important to realize that there are no bytes in a text string. Of course,
+Perl has its internal encoding to store the string in memory, but ignore that.
+If you have to do anything with the number of bytes, it's probably best to move
+that part to step 3, just after you've encoded the string. Then you know
+exactly how many bytes it will be in the destination string.
+.PP
+The syntax for encoding text strings to binary strings is as simple as decoding:
+.PP
+.Vb 1
+\&    $body = encode(\*(AqUTF\-8\*(Aq, $body);
+.Ve
+.PP
+If you needed to know the length of the string in bytes, now's the perfect time
+for that. Because \f(CW$body\fR is now a byte string, \f(CW\*(C`length\*(C'\fR will report the
+number of bytes, instead of the number of characters. The number of
+characters is no longer known, because characters only exist in text strings.
+.PP
+.Vb 1
+\&    my $byte_count = length $body;
+.Ve
+.PP
+And if the protocol you're using supports a way of letting the recipient know
+which character encoding you used, please help the receiving end by using that
+feature! For example, E\-mail and HTTP support MIME headers, so you can use the
+\&\f(CW\*(C`Content\-Type\*(C'\fR header. They can also have \f(CW\*(C`Content\-Length\*(C'\fR to indicate the
+number of \fIbytes\fR, which is always a good idea to supply if the number is
+known.
+.PP
+.Vb 2
+\&    "Content\-Type: text/plain; charset=UTF\-8",
+\&    "Content\-Length: $byte_count"
+.Ve
+.SH SUMMARY
+.IX Header "SUMMARY"
+Decode everything you receive, encode everything you send out. (If it's text
+data.)
+.SH "Q and A (or FAQ)"
+.IX Header "Q and A (or FAQ)"
+After reading this document, you ought to read perlunifaq too, then
+perluniintro.
+.SH ACKNOWLEDGEMENTS
+.IX Header "ACKNOWLEDGEMENTS"
+Thanks to Johan Vromans from Squirrel Consultancy. His UTF\-8 rants during the
+Amsterdam Perl Mongers meetings got me interested and determined to find out
+how to use character encodings in Perl in ways that don't break easily.
+.PP
+Thanks to Gerard Goossen from TTY. His presentation "UTF\-8 in the wild" (Dutch
+Perl Workshop 2006) inspired me to publish my thoughts and write this tutorial.
+.PP
+Thanks to the people who asked about this kind of stuff in several Perl IRC
+channels, and have constantly reminded me that a simpler explanation was
+needed.
+.PP
+Thanks to the people who reviewed this document for me, before it went public.
+They are: Benjamin Smith, Jan-Pieter Cornet, Johan Vromans, Lukas Mai, Nathan
+Gray.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Juerd Waalboer <#####@juerd.nl>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlunifaq, perlunicode, perluniintro, Encode
diff --git a/upstream/mageia-cauldron/man1/perlutil.1 b/upstream/mageia-cauldron/man1/perlutil.1
new file mode 100644
index 00000000..ce505cf1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlutil.1
@@ -0,0 +1,254 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLUTIL 1"
+.TH PERLUTIL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlutil \- utilities packaged with the Perl distribution
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Along with the Perl interpreter itself, the Perl distribution installs a
+range of utilities on your system. There are also several utilities
+which are used by the Perl distribution itself as part of the install
+process. This document exists to list all of these utilities, explain
+what they are for and provide pointers to each module's documentation,
+if appropriate.
+.SH "LIST OF UTILITIES"
+.IX Header "LIST OF UTILITIES"
+.SS Documentation
+.IX Subsection "Documentation"
+.IP perldoc 3
+.IX Item "perldoc"
+The main interface to Perl's documentation is \fIperldoc\fR, although
+if you're reading this, it's more than likely that you've already found
+it. \fIperldoc\fR will extract and format the documentation from any file
+in the current directory, any Perl module installed on the system, or
+any of the standard documentation pages, such as this one. Use 
+\&\f(CW\*(C`perldoc <name>\*(C'\fR to get information on any of the utilities
+described in this document.
+.IP pod2man 3
+.IX Item "pod2man"
+.PD 0
+.IP pod2text 3
+.IX Item "pod2text"
+.PD
+If it's run from a terminal, \fIperldoc\fR will usually call \fIpod2man\fR to
+translate POD (Plain Old Documentation \- see perlpod for an
+explanation) into a manpage, and then run \fIman\fR to display it; if
+\&\fIman\fR isn't available, \fIpod2text\fR will be used instead and the output
+piped through your favourite pager.
+.IP pod2html 3
+.IX Item "pod2html"
+As well as these two, there is another converter: \fIpod2html\fR will
+produce HTML pages from POD.
+.IP pod2usage 3
+.IX Item "pod2usage"
+If you just want to know how to use the utilities described here,
+\&\fIpod2usage\fR will just extract the "USAGE" section; some of
+the utilities will automatically call \fIpod2usage\fR on themselves when
+you call them with \f(CW\*(C`\-help\*(C'\fR.
+.IP podchecker 3
+.IX Item "podchecker"
+If you're writing your own documentation in POD, the \fIpodchecker\fR
+utility will look for errors in your markup.
+.IP splain 3
+.IX Item "splain"
+\&\fIsplain\fR is an interface to perldiag \- paste in your error message
+to it, and it'll explain it for you.
+.IP \fIroffitall\fR 3
+.IX Item "roffitall"
+The \fIroffitall\fR utility is not installed on your system but lives in
+the \fIpod/\fR directory of your Perl source kit; it converts all the
+documentation from the distribution to \fI*roff\fR format, and produces a
+typeset PostScript or text file of the whole lot.
+.SS Converters
+.IX Subsection "Converters"
+.IP pl2pm 3
+.IX Item "pl2pm"
+To help you convert legacy programs to more modern Perl, the
+\&\fIpl2pm\fR utility will help you convert old-style Perl 4 libraries
+to new-style Perl5 modules.
+.SS Administration
+.IX Subsection "Administration"
+.IP libnetcfg 3
+.IX Item "libnetcfg"
+To display and change the libnet configuration run the libnetcfg command.
+.IP perlivp 3
+.IX Item "perlivp"
+The \fIperlivp\fR program is set up at Perl source code build time to test
+the Perl version it was built under.  It can be used after running \f(CW\*(C`make
+install\*(C'\fR (or your platform's equivalent procedure) to verify that perl
+and its libraries have been installed correctly.
+.SS Development
+.IX Subsection "Development"
+There are a set of utilities which help you in developing Perl programs, 
+and in particular, extending Perl with C.
+.IP perlbug 3
+.IX Item "perlbug"
+\&\fIperlbug\fR used to be the recommended way to report bugs in the perl
+interpreter itself or any of the standard library modules back to the
+developers; bug reports and patches should now be submitted to
+<https://github.com/Perl/perl5/issues>.
+.IP perlthanks 3
+.IX Item "perlthanks"
+This program provides an easy way to send a thank-you message back to the
+authors and maintainers of perl. It's just \fIperlbug\fR installed under
+another name.
+.IP h2ph 3
+.IX Item "h2ph"
+Back before Perl had the XS system for connecting with C libraries,
+programmers used to get library constants by reading through the C
+header files. You may still see \f(CW\*(C`require\ \*(Aqsyscall.ph\*(Aq\*(C'\fR or similar
+around \- the \fI.ph\fR file should be created by running \fIh2ph\fR on the
+corresponding \fI.h\fR file. See the h2ph documentation for more on how
+to convert a whole bunch of header files at once.
+.IP h2xs 3
+.IX Item "h2xs"
+\&\fIh2xs\fR converts C header files into XS modules, and will try and write
+as much glue between C libraries and Perl modules as it can. It's also
+very useful for creating skeletons of pure Perl modules.
+.IP enc2xs 3
+.IX Item "enc2xs"
+\&\fIenc2xs\fR builds a Perl extension for use by Encode from either
+Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
+Besides being used internally during the build process of the Encode
+module, you can use \fIenc2xs\fR to add your own encoding to perl.
+No knowledge of XS is necessary.
+.IP xsubpp 3
+.IX Item "xsubpp"
+\&\fIxsubpp\fR is a compiler to convert Perl XS code into C code.
+It is typically run by the makefiles created by ExtUtils::MakeMaker.
+.Sp
+\&\fIxsubpp\fR will compile XS code into C code by embedding the constructs
+necessary to let C functions manipulate Perl values and creates the glue
+necessary to let Perl access those functions.
+.IP prove 3
+.IX Item "prove"
+\&\fIprove\fR is a command-line interface to the test-running functionality
+of Test::Harness.  It's an alternative to \f(CW\*(C`make test\*(C'\fR.
+.IP corelist 3
+.IX Item "corelist"
+A command-line front-end to Module::CoreList, to query what modules
+were shipped with given versions of perl.
+.SS "General tools"
+.IX Subsection "General tools"
+A few general-purpose tools are shipped with perl, mostly because they
+came along modules included in the perl distribution.
+.IP encguess 3
+.IX Item "encguess"
+\&\fIencguess\fR will attempt to guess the character encoding of files.
+.IP json_pp 3
+.IX Item "json_pp"
+\&\fIjson_pp\fR is a pure Perl JSON converter and formatter.
+.IP piconv 3
+.IX Item "piconv"
+\&\fIpiconv\fR is a Perl version of \fBiconv\fR\|(1), a character encoding converter
+widely available for various Unixen today.  This script was primarily a
+technology demonstrator for Perl v5.8.0, but you can use piconv in the
+place of iconv for virtually any case.
+.IP ptar 3
+.IX Item "ptar"
+\&\fIptar\fR is a tar-like program, written in pure Perl.
+.IP ptardiff 3
+.IX Item "ptardiff"
+\&\fIptardiff\fR is a small utility that produces a diff between an extracted
+archive and an unextracted one. (Note that this utility requires the
+Text::Diff module to function properly; this module isn't distributed
+with perl, but is available from the CPAN.)
+.IP ptargrep 3
+.IX Item "ptargrep"
+\&\fIptargrep\fR is a utility to apply pattern matching to the contents of files 
+in a tar archive.
+.IP shasum 3
+.IX Item "shasum"
+This utility, that comes with the Digest::SHA module, is used to print
+or verify SHA checksums.
+.IP streamzip 3
+.IX Item "streamzip"
+\&\fIstreamzip\fR compresses data streamed to STDIN into a streamed zip container.
+.IP zipdetails 3
+.IX Item "zipdetails"
+\&\fIzipdetails\fR displays information about the internal record structure of the zip file.
+It is not concerned with displaying any details of the compressed data stored in the zip file.
+.SS Installation
+.IX Subsection "Installation"
+These utilities help manage extra Perl modules that don't come with the perl
+distribution.
+.IP cpan 3
+.IX Item "cpan"
+\&\fIcpan\fR is a command-line interface to CPAN.pm.  It allows you to install
+modules or distributions from CPAN, or just get information about them, and
+a lot more.  It is similar to the command line mode of the CPAN module,
+.Sp
+.Vb 1
+\&    perl \-MCPAN \-e shell
+.Ve
+.IP instmodsh 3
+.IX Item "instmodsh"
+A little interface to ExtUtils::Installed to examine installed modules,
+validate your packlists and even create a tarball from an installed module.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perldoc, pod2man, pod2text, pod2html, pod2usage,
+podchecker, splain, pl2pm,
+perlbug, h2ph, h2xs, enc2xs,
+xsubpp, cpan, encguess, instmodsh, json_pp,
+piconv, prove, corelist, ptar,
+ptardiff, shasum, streamzip, zipdetails
diff --git a/upstream/mageia-cauldron/man1/perlvar.1 b/upstream/mageia-cauldron/man1/perlvar.1
new file mode 100644
index 00000000..9b06d42d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlvar.1
@@ -0,0 +1,2893 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLVAR 1"
+.TH PERLVAR 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlvar \- Perl predefined variables
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "The Syntax of Variable Names"
+.IX Subsection "The Syntax of Variable Names"
+Variable names in Perl can have several formats.  Usually, they
+must begin with a letter or underscore, in which case they can be
+arbitrarily long (up to an internal limit of 251 characters) and
+may contain letters, digits, underscores, or the special sequence
+\&\f(CW\*(C`::\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR.  In this case, the part before the last \f(CW\*(C`::\*(C'\fR or
+\&\f(CW\*(C`\*(Aq\*(C'\fR is taken to be a \fIpackage qualifier\fR; see perlmod.
+A Unicode letter that is not ASCII is not considered to be a letter
+unless \f(CW"use\ utf8"\fR is in effect, and somewhat more complicated
+rules apply; see "Identifier parsing" in perldata for details.
+.PP
+Perl variable names may also be a sequence of digits, a single
+punctuation character, or the two-character sequence: \f(CW\*(C`^\*(C'\fR (caret or
+CIRCUMFLEX ACCENT) followed by any one of the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR.
+These names are all reserved for
+special uses by Perl; for example, the all-digits names are used
+to hold data captured by backreferences after a regular expression
+match.
+.PP
+Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
+preceded by a caret.  These must all be written using the demarcated
+variable form using curly braces such as \f(CW\*(C`${^Foo}\*(C'\fR;
+the braces are \fBnot\fR optional.  \f(CW\*(C`${^Foo}\*(C'\fR denotes the scalar variable
+whose name is considered to be a control\-\f(CW\*(C`F\*(C'\fR followed by two \f(CW\*(C`o\*(C'\fR's.
+(See "Demarcated variable names using braces" in perldata for more
+information on this form of spelling a variable name or specifying
+access to an element of an array or a hash).
+These variables are
+reserved for future special uses by Perl, except for the ones that
+begin with \f(CW\*(C`^_\*(C'\fR (caret-underscore).  No
+name that begins with \f(CW\*(C`^_\*(C'\fR will acquire a special
+meaning in any future version of Perl; such names may therefore be
+used safely in programs.  \f(CW$^_\fR itself, however, \fIis\fR reserved.
+.PP
+Note that you also \fBmust\fR use the demarcated form to access subscripts
+of variables of this type when interpolating, for instance to access the
+first element of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR variable inside of a double quoted
+string you would write \f(CW"${^CAPTURE[0]}"\fR and NOT \f(CW"${^CAPTURE}[0]"\fR
+which would mean to reference a scalar variable named \f(CW\*(C`${^CAPTURE}\*(C'\fR and
+not index 0 of the magic \f(CW\*(C`@{^CAPTURE}\*(C'\fR array which is populated by the
+regex engine.
+.PP
+Perl identifiers that begin with digits or
+punctuation characters are exempt from the effects of the \f(CW\*(C`package\*(C'\fR
+declaration and are always forced to be in package \f(CW\*(C`main\*(C'\fR; they are
+also exempt from \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR errors.  A few other names are also
+exempt in these ways:
+.PP
+.Vb 5
+\&    ENV      STDIN
+\&    INC      STDOUT
+\&    ARGV     STDERR
+\&    ARGVOUT
+\&    SIG
+.Ve
+.PP
+In particular, the special \f(CW\*(C`${^_XYZ}\*(C'\fR variables are always taken
+to be in package \f(CW\*(C`main\*(C'\fR, regardless of any \f(CW\*(C`package\*(C'\fR declarations
+presently in scope.
+.SH "SPECIAL VARIABLES"
+.IX Header "SPECIAL VARIABLES"
+The following names have special meaning to Perl.  Most punctuation
+names have reasonable mnemonics, or analogs in the shells.
+Nevertheless, if you wish to use long variable names, you need only say:
+.PP
+.Vb 1
+\&    use English;
+.Ve
+.PP
+at the top of your program.  This aliases all the short names to the long
+names in the current package.  Some even have medium names, generally
+borrowed from \fBawk\fR.  For more info, please see English.
+.PP
+Before you continue, note the sort order for variables.  In general, we
+first list the variables in case-insensitive, almost-lexigraphical
+order (ignoring the \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`^\*(C'\fR preceding words, as in \f(CW\*(C`${^UNICODE}\*(C'\fR
+or \f(CW$^T\fR), although \f(CW$_\fR and \f(CW@_\fR move up to the top of the pile.
+For variables with the same identifier, we list it in order of scalar,
+array, hash, and bareword.
+.SS "General Variables"
+.IX Subsection "General Variables"
+.ie n .IP $ARG 8
+.el .IP \f(CW$ARG\fR 8
+.IX Item "$ARG"
+.PD 0
+.ie n .IP $_ 8
+.el .IP \f(CW$_\fR 8
+.IX Xref "$_ $ARG"
+.IX Item "$_"
+.PD
+The default input and pattern-searching space.  The following pairs are
+equivalent:
+.Sp
+.Vb 2
+\&    while (<>) {...}    # equivalent only in while!
+\&    while (defined($_ = <>)) {...}
+\&
+\&    /^Subject:/
+\&    $_ =~ /^Subject:/
+\&
+\&    tr/a\-z/A\-Z/
+\&    $_ =~ tr/a\-z/A\-Z/
+\&
+\&    chomp
+\&    chomp($_)
+.Ve
+.Sp
+Here are the places where Perl will assume \f(CW$_\fR even if you don't use it:
+.RS 8
+.IP \(bu 3
+The following functions use \f(CW$_\fR as a default argument:
+.Sp
+abs, alarm, chomp, chop, chr, chroot,
+cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
+lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
+quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
+rmdir, say, sin, split (for its second
+argument), sqrt, stat, study, uc, ucfirst,
+unlink, unpack.
+.IP \(bu 3
+All file tests (\f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR) except for \f(CW\*(C`\-t\*(C'\fR, which defaults to STDIN.
+See "\-X" in perlfunc
+.IP \(bu 3
+The pattern matching operations \f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR and \f(CW\*(C`tr///\*(C'\fR (aka \f(CW\*(C`y///\*(C'\fR)
+when used without an \f(CW\*(C`=~\*(C'\fR operator.
+.IP \(bu 3
+The default iterator variable in a \f(CW\*(C`foreach\*(C'\fR loop if no other
+variable is supplied.
+.IP \(bu 3
+The implicit iterator variable in the \f(CWgrep()\fR and \f(CWmap()\fR functions.
+.IP \(bu 3
+The implicit variable of \f(CWgiven()\fR.
+.IP \(bu 3
+The default place to put the next value or input record
+when a \f(CW\*(C`<FH>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readdir\*(C'\fR or \f(CW\*(C`each\*(C'\fR
+operation's result is tested by itself as the sole criterion of a \f(CW\*(C`while\*(C'\fR
+test.  Outside a \f(CW\*(C`while\*(C'\fR test, this will not happen.
+.RE
+.RS 8
+.Sp
+\&\f(CW$_\fR is a global variable.
+.Sp
+However, between perl v5.10.0 and v5.24.0, it could be used lexically by
+writing \f(CW\*(C`my $_\*(C'\fR.  Making \f(CW$_\fR refer to the global \f(CW$_\fR in the same scope
+was then possible with \f(CW\*(C`our $_\*(C'\fR.  This experimental feature was removed and is
+now a fatal error, but you may encounter it in older code.
+.Sp
+Mnemonic: underline is understood in certain operations.
+.RE
+.ie n .IP @ARG 8
+.el .IP \f(CW@ARG\fR 8
+.IX Item "@ARG"
+.PD 0
+.ie n .IP @_ 8
+.el .IP \f(CW@_\fR 8
+.IX Xref "@_ @ARG"
+.IX Item "@_"
+.PD
+Within a subroutine the array \f(CW@_\fR contains the parameters passed to
+that subroutine.  Inside a subroutine, \f(CW@_\fR is the default array for
+the array operators \f(CW\*(C`pop\*(C'\fR and \f(CW\*(C`shift\*(C'\fR.
+.Sp
+See perlsub.
+.ie n .IP $LIST_SEPARATOR 8
+.el .IP \f(CW$LIST_SEPARATOR\fR 8
+.IX Item "$LIST_SEPARATOR"
+.PD 0
+.IP "$""" 8
+.IX Xref "$"" $LIST_SEPARATOR"
+.PD
+When an array or an array slice is interpolated into a double-quoted
+string or a similar context such as \f(CW\*(C`/.../\*(C'\fR, its elements are
+separated by this value.  Default is a space.  For example, this:
+.Sp
+.Vb 1
+\&    print "The array is: @array\en";
+.Ve
+.Sp
+is equivalent to this:
+.Sp
+.Vb 1
+\&    print "The array is: " . join($", @array) . "\en";
+.Ve
+.Sp
+Mnemonic: works in double-quoted context.
+.ie n .IP $PROCESS_ID 8
+.el .IP \f(CW$PROCESS_ID\fR 8
+.IX Item "$PROCESS_ID"
+.PD 0
+.ie n .IP $PID 8
+.el .IP \f(CW$PID\fR 8
+.IX Item "$PID"
+.IP $$ 8
+.IX Xref "$$ $PID $PROCESS_ID"
+.PD
+The process number of the Perl running this script.  Though you \fIcan\fR set
+this variable, doing so is generally discouraged, although it can be
+invaluable for some testing purposes.  It will be reset automatically
+across \f(CWfork()\fR calls.
+.Sp
+Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
+would emulate POSIX semantics on Linux systems using LinuxThreads, a
+partial implementation of POSIX Threads that has since been superseded
+by the Native POSIX Thread Library (NPTL).
+.Sp
+LinuxThreads is now obsolete on Linux, and caching \f(CWgetpid()\fR
+like this made embedding perl unnecessarily complex (since you'd have
+to manually update the value of $$), so now \f(CW$$\fR and \f(CWgetppid()\fR
+will always return the same values as the underlying C library.
+.Sp
+Debian GNU/kFreeBSD systems also used LinuxThreads up until and
+including the 6.0 release, but after that moved to FreeBSD thread
+semantics, which are POSIX-like.
+.Sp
+To see if your system is affected by this discrepancy check if
+\&\f(CW\*(C`getconf GNU_LIBPTHREAD_VERSION | grep \-q NPTL\*(C'\fR returns a false
+value.  NTPL threads preserve the POSIX semantics.
+.Sp
+Mnemonic: same as shells.
+.ie n .IP $PROGRAM_NAME 8
+.el .IP \f(CW$PROGRAM_NAME\fR 8
+.IX Item "$PROGRAM_NAME"
+.PD 0
+.ie n .IP $0 8
+.el .IP \f(CW$0\fR 8
+.IX Xref "$0 $PROGRAM_NAME"
+.IX Item "$0"
+.PD
+Contains the name of the program being executed.
+.Sp
+On some (but not all) operating systems assigning to \f(CW$0\fR modifies
+the argument area that the \f(CW\*(C`ps\*(C'\fR program sees.  On some platforms you
+may have to use special \f(CW\*(C`ps\*(C'\fR options or a different \f(CW\*(C`ps\*(C'\fR to see the
+changes.  Modifying the \f(CW$0\fR is more useful as a way of indicating the
+current program state than it is for hiding the program you're
+running.
+.Sp
+Note that there are platform-specific limitations on the maximum
+length of \f(CW$0\fR.  In the most extreme case it may be limited to the
+space occupied by the original \f(CW$0\fR.
+.Sp
+In some platforms there may be arbitrary amount of padding, for
+example space characters, after the modified name as shown by \f(CW\*(C`ps\*(C'\fR.
+In some platforms this padding may extend all the way to the original
+length of the argument area, no matter what you do (this is the case
+for example with Linux 2.2).
+.Sp
+Note for BSD users: setting \f(CW$0\fR does not completely remove "perl"
+from the \fBps\fR\|(1) output.  For example, setting \f(CW$0\fR to \f(CW"foobar"\fR may
+result in \f(CW"perl: foobar (perl)"\fR (whether both the \f(CW"perl: "\fR prefix
+and the " (perl)" suffix are shown depends on your exact BSD variant
+and version).  This is an operating system feature, Perl cannot help it.
+.Sp
+In multithreaded scripts Perl coordinates the threads so that any
+thread may modify its copy of the \f(CW$0\fR and the change becomes visible
+to \fBps\fR\|(1) (assuming the operating system plays along).  Note that
+the view of \f(CW$0\fR the other threads have will not change since they
+have their own copies of it.
+.Sp
+If the program has been given to perl via the switches \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR,
+\&\f(CW$0\fR will contain the string \f(CW"\-e"\fR.
+.Sp
+On Linux as of perl v5.14.0 the legacy process name will be set with
+\&\f(CWprctl(2)\fR, in addition to altering the POSIX name via \f(CW\*(C`argv[0]\*(C'\fR as
+perl has done since version 4.000.  Now system utilities that read the
+legacy process name such as ps, top and killall will recognize the
+name you set when assigning to \f(CW$0\fR.  The string you supply will be
+cut off at 16 bytes, this is a limitation imposed by Linux.
+.Sp
+Wide characters are invalid in \f(CW$0\fR values. For historical reasons,
+though, Perl accepts them and encodes them to UTF\-8. When this
+happens a wide-character warning is triggered.
+.Sp
+Mnemonic: same as \fBsh\fR and \fBksh\fR.
+.ie n .IP $REAL_GROUP_ID 8
+.el .IP \f(CW$REAL_GROUP_ID\fR 8
+.IX Item "$REAL_GROUP_ID"
+.PD 0
+.ie n .IP $GID 8
+.el .IP \f(CW$GID\fR 8
+.IX Item "$GID"
+.IP $( 8
+.IX Xref "$( $GID $REAL_GROUP_ID"
+.PD
+The real gid of this process.  If you are on a machine that supports
+membership in multiple groups simultaneously, gives a space separated
+list of groups you are in.  The first number is the one returned by
+\&\f(CWgetgid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, one of which may be
+the same as the first number.
+.Sp
+However, a value assigned to \f(CW$(\fR must be a single number used to
+set the real gid.  So the value given by \f(CW$(\fR should \fInot\fR be assigned
+back to \f(CW$(\fR without being forced numeric, such as by adding zero.  Note
+that this is different to the effective gid (\f(CW$)\fR) which does take a
+list.
+.Sp
+You can change both the real gid and the effective gid at the same
+time by using \f(CWPOSIX::setgid()\fR.  Changes
+to \f(CW$(\fR require a check to \f(CW$!\fR
+to detect any possible errors after an attempted change.
+.Sp
+Mnemonic: parentheses are used to \fIgroup\fR things.  The real gid is the
+group you \fIleft\fR, if you're running setgid.
+.ie n .IP $EFFECTIVE_GROUP_ID 8
+.el .IP \f(CW$EFFECTIVE_GROUP_ID\fR 8
+.IX Item "$EFFECTIVE_GROUP_ID"
+.PD 0
+.ie n .IP $EGID 8
+.el .IP \f(CW$EGID\fR 8
+.IX Item "$EGID"
+.IP $) 8
+.IX Xref "$) $EGID $EFFECTIVE_GROUP_ID"
+.PD
+The effective gid of this process.  If you are on a machine that
+supports membership in multiple groups simultaneously, gives a space
+separated list of groups you are in.  The first number is the one
+returned by \f(CWgetegid()\fR, and the subsequent ones by \f(CWgetgroups()\fR,
+one of which may be the same as the first number.
+.Sp
+Similarly, a value assigned to \f(CW$)\fR must also be a space-separated
+list of numbers.  The first number sets the effective gid, and
+the rest (if any) are passed to \f(CWsetgroups()\fR.  To get the effect of an
+empty list for \f(CWsetgroups()\fR, just repeat the new effective gid; that is,
+to force an effective gid of 5 and an effectively empty \f(CWsetgroups()\fR
+list, say \f(CW\*(C` $) = "5 5" \*(C'\fR.
+.Sp
+You can change both the effective gid and the real gid at the same
+time by using \f(CWPOSIX::setgid()\fR (use only a single numeric argument).
+Changes to \f(CW$)\fR require a check to \f(CW$!\fR to detect any possible errors
+after an attempted change.
+.Sp
+\&\f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR can be set only on
+machines that support the corresponding \fIset[re][ug]\fR\f(BIid()\fR routine.  \f(CW$(\fR
+and \f(CW$)\fR can be swapped only on machines supporting \f(CWsetregid()\fR.
+.Sp
+Mnemonic: parentheses are used to \fIgroup\fR things.  The effective gid
+is the group that's \fIright\fR for you, if you're running setgid.
+.ie n .IP $REAL_USER_ID 8
+.el .IP \f(CW$REAL_USER_ID\fR 8
+.IX Item "$REAL_USER_ID"
+.PD 0
+.ie n .IP $UID 8
+.el .IP \f(CW$UID\fR 8
+.IX Item "$UID"
+.IP $< 8
+.IX Xref "$< $UID $REAL_USER_ID"
+.PD
+The real uid of this process.  You can change both the real uid and the
+effective uid at the same time by using \f(CWPOSIX::setuid()\fR.  Since
+changes to \f(CW$<\fR require a system call, check \f(CW$!\fR after a change
+attempt to detect any possible errors.
+.Sp
+Mnemonic: it's the uid you came \fIfrom\fR, if you're running setuid.
+.ie n .IP $EFFECTIVE_USER_ID 8
+.el .IP \f(CW$EFFECTIVE_USER_ID\fR 8
+.IX Item "$EFFECTIVE_USER_ID"
+.PD 0
+.ie n .IP $EUID 8
+.el .IP \f(CW$EUID\fR 8
+.IX Item "$EUID"
+.IP $> 8
+.IX Xref "$> $EUID $EFFECTIVE_USER_ID"
+.PD
+The effective uid of this process.  For example:
+.Sp
+.Vb 2
+\&    $< = $>;            # set real to effective uid
+\&    ($<,$>) = ($>,$<);  # swap real and effective uids
+.Ve
+.Sp
+You can change both the effective uid and the real uid at the same
+time by using \f(CWPOSIX::setuid()\fR.  Changes to \f(CW$>\fR require a check
+to \f(CW$!\fR to detect any possible errors after an attempted change.
+.Sp
+\&\f(CW$<\fR and \f(CW$>\fR can be swapped only on machines
+supporting \f(CWsetreuid()\fR.
+.Sp
+Mnemonic: it's the uid you went \fIto\fR, if you're running setuid.
+.ie n .IP $SUBSCRIPT_SEPARATOR 8
+.el .IP \f(CW$SUBSCRIPT_SEPARATOR\fR 8
+.IX Item "$SUBSCRIPT_SEPARATOR"
+.PD 0
+.ie n .IP $SUBSEP 8
+.el .IP \f(CW$SUBSEP\fR 8
+.IX Item "$SUBSEP"
+.IP $; 8
+.IX Xref "$; $SUBSEP SUBSCRIPT_SEPARATOR"
+.PD
+The subscript separator for multidimensional array emulation.  If you
+refer to a hash element as
+.Sp
+.Vb 1
+\&    $foo{$x,$y,$z}
+.Ve
+.Sp
+it really means
+.Sp
+.Vb 1
+\&    $foo{join($;, $x, $y, $z)}
+.Ve
+.Sp
+But don't put
+.Sp
+.Vb 1
+\&    @foo{$x,$y,$z}     # a slice\-\-note the @
+.Ve
+.Sp
+which means
+.Sp
+.Vb 1
+\&    ($foo{$x},$foo{$y},$foo{$z})
+.Ve
+.Sp
+Default is "\e034", the same as SUBSEP in \fBawk\fR.  If your keys contain
+binary data there might not be any safe value for \f(CW$;\fR.
+.Sp
+Consider using "real" multidimensional arrays as described
+in perllol.
+.Sp
+Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
+.ie n .IP $a 8
+.el .IP \f(CW$a\fR 8
+.IX Item "$a"
+.PD 0
+.ie n .IP $b 8
+.el .IP \f(CW$b\fR 8
+.IX Xref "$a $b"
+.IX Item "$b"
+.PD
+Special package variables when using \f(CWsort()\fR, see "sort" in perlfunc.
+Because of this specialness \f(CW$a\fR and \f(CW$b\fR don't need to be declared
+(using \f(CW\*(C`use vars\*(C'\fR, or \f(CWour()\fR) even when using the \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR
+pragma.  Don't lexicalize them with \f(CW\*(C`my $a\*(C'\fR or \f(CW\*(C`my $b\*(C'\fR if you want to
+be able to use them in the \f(CWsort()\fR comparison block or function.
+.ie n .IP %ENV 8
+.el .IP \f(CW%ENV\fR 8
+.IX Xref "%ENV"
+.IX Item "%ENV"
+The hash \f(CW%ENV\fR contains your current environment.  Setting a
+value in \f(CW\*(C`ENV\*(C'\fR changes the environment for any child processes
+you subsequently \f(CWfork()\fR off.
+.Sp
+As of v5.18.0, both keys and values stored in \f(CW%ENV\fR are stringified.
+.Sp
+.Vb 7
+\&    my $foo = 1;
+\&    $ENV{\*(Aqbar\*(Aq} = \e$foo;
+\&    if( ref $ENV{\*(Aqbar\*(Aq} ) {
+\&        say "Pre 5.18.0 Behaviour";
+\&    } else {
+\&        say "Post 5.18.0 Behaviour";
+\&    }
+.Ve
+.Sp
+Previously, only child processes received stringified values:
+.Sp
+.Vb 2
+\&    my $foo = 1;
+\&    $ENV{\*(Aqbar\*(Aq} = \e$foo;
+\&
+\&    # Always printed \*(Aqnon ref\*(Aq
+\&    system($^X, \*(Aq\-e\*(Aq,
+\&           q/print ( ref $ENV{\*(Aqbar\*(Aq}  ? \*(Aqref\*(Aq : \*(Aqnon ref\*(Aq ) /);
+.Ve
+.Sp
+This happens because you can't really share arbitrary data structures with
+foreign processes.
+.ie n .IP $OLD_PERL_VERSION 8
+.el .IP \f(CW$OLD_PERL_VERSION\fR 8
+.IX Item "$OLD_PERL_VERSION"
+.PD 0
+.IP $] 8
+.IX Xref "$] $OLD_PERL_VERSION"
+.PD
+The revision, version, and subversion of the Perl interpreter, represented
+as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
+is the subversion / 1e6.  For example, Perl v5.10.1 would be "5.010001".
+.Sp
+This variable can be used to determine whether the Perl interpreter
+executing a script is in the right range of versions:
+.Sp
+.Vb 1
+\&    warn "No PerlIO!\en" if "$]" < 5.008;
+.Ve
+.Sp
+When comparing \f(CW$]\fR, numeric comparison operators should be used, but the
+variable should be stringified first to avoid issues where its original
+numeric value is inaccurate.
+.Sp
+See also the documentation of \f(CW\*(C`use VERSION\*(C'\fR and
+\&\f(CW\*(C`require VERSION\*(C'\fR for a convenient way to fail if the running Perl
+interpreter is too old.
+.Sp
+See "$^V" for a representation of the Perl version as a version
+object, which allows more flexible string comparisons.
+.Sp
+The main advantage of \f(CW$]\fR over \f(CW$^V\fR is that it works the same on any
+version of Perl.  The disadvantages are that it can't easily be compared
+to versions in other formats (e.g. literal v\-strings, "v1.2.3" or
+version objects) and numeric comparisons are subject to the binary
+floating point representation; it's good for numeric literal version
+checks and bad for comparing to a variable that hasn't been
+sanity-checked.
+.Sp
+The \f(CW$OLD_PERL_VERSION\fR form was added in Perl v5.20.0 for historical
+reasons but its use is discouraged. (If your reason to use \f(CW$]\fR is to
+run code on old perls then referring to it as \f(CW$OLD_PERL_VERSION\fR would
+be self-defeating.)
+.Sp
+Mnemonic: Is this version of perl in the right bracket?
+.ie n .IP $SYSTEM_FD_MAX 8
+.el .IP \f(CW$SYSTEM_FD_MAX\fR 8
+.IX Item "$SYSTEM_FD_MAX"
+.PD 0
+.IP $^F 8
+.IX Xref "$^F $SYSTEM_FD_MAX"
+.IX Item "$^F"
+.PD
+The maximum system file descriptor, ordinarily 2.  System file
+descriptors are passed to \f(CWexec()\fRed processes, while higher file
+descriptors are not.  Also, during an
+\&\f(CWopen()\fR, system file descriptors are
+preserved even if the \f(CWopen()\fR fails (ordinary file descriptors are
+closed before the \f(CWopen()\fR is attempted).  The close-on-exec
+status of a file descriptor will be decided according to the value of
+\&\f(CW$^F\fR when the corresponding file, pipe, or socket was opened, not the
+time of the \f(CWexec()\fR.
+.ie n .IP @F 8
+.el .IP \f(CW@F\fR 8
+.IX Xref "@F"
+.IX Item "@F"
+The array \f(CW@F\fR contains the fields of each line read in when autosplit
+mode is turned on.  See perlrun for the \fB\-a\fR switch.  This
+array is package-specific, and must be declared or given a full package
+name if not in package main when running under \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR.
+.ie n .IP @INC 8
+.el .IP \f(CW@INC\fR 8
+.IX Xref "@INC"
+.IX Item "@INC"
+The array \f(CW@INC\fR contains the list of places that the \f(CW\*(C`do EXPR\*(C'\fR,
+\&\f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR constructs look for their library files.  It
+initially consists of the arguments to any \fB\-I\fR command-line
+switches, followed by the default Perl library, probably
+\&\fI/usr/local/lib/perl\fR.
+Prior to Perl 5.26, \f(CW\*(C`.\*(C'\fR \-which represents the current directory, was included
+in \f(CW@INC\fR; it has been removed. This change in behavior is documented
+in \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR and it is
+not recommended that \f(CW\*(C`.\*(C'\fR be re-added to \f(CW@INC\fR.
+If you need to modify \f(CW@INC\fR at runtime, you should use the \f(CW\*(C`use lib\*(C'\fR pragma
+to get the machine-dependent library properly loaded as well:
+.Sp
+.Vb 2
+\&    use lib \*(Aq/mypath/libdir/\*(Aq;
+\&    use SomeMod;
+.Ve
+.Sp
+You can also insert hooks into the file inclusion system by putting Perl
+code directly into \f(CW@INC\fR.  Those hooks may be subroutine references,
+array references or blessed objects.  See "require" in perlfunc for details.
+.ie n .IP %INC 8
+.el .IP \f(CW%INC\fR 8
+.IX Xref "%INC"
+.IX Item "%INC"
+The hash \f(CW%INC\fR contains entries for each filename included via the
+\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators.  The key is the filename
+you specified (with module names converted to pathnames), and the
+value is the location of the file found.  The \f(CW\*(C`require\*(C'\fR
+operator uses this hash to determine whether a particular file has
+already been included.
+.Sp
+If the file was loaded via a hook (e.g. a subroutine reference, see
+"require" in perlfunc for a description of these hooks), this hook is
+by default inserted into \f(CW%INC\fR in place of a filename.  Note, however,
+that the hook may have set the \f(CW%INC\fR entry by itself to provide some more
+specific info.
+.ie n .IP $INC 8
+.el .IP \f(CW$INC\fR 8
+.IX Xref "$INC"
+.IX Item "$INC"
+As of 5.37.7 when an \f(CW@INC\fR hook is executed the index of the \f(CW@INC\fR
+array that holds the hook will be localized into the \f(CW$INC\fR variable.
+When the hook returns the integer successor of its value will be used to
+determine the next index in \f(CW@INC\fR that will be checked, thus if it is
+set to \-1 (or \f(CW\*(C`undef\*(C'\fR) the traversal over the \f(CW@INC\fR array will be
+restarted from its beginning.
+.Sp
+Normally traversal through the \f(CW@INC\fR array is from beginning to end
+(\f(CW\*(C`0 .. $#INC\*(C'\fR), and if the \f(CW@INC\fR array is modified by the hook the
+iterator may be left in a state where newly added entries are skipped.
+Changing this value allows an \f(CW@INC\fR hook to rewrite the \f(CW@INC\fR array
+and tell Perl where to continue afterwards. See "require" in perlfunc for
+details on \f(CW@INC\fR hooks.
+.ie n .IP $INPLACE_EDIT 8
+.el .IP \f(CW$INPLACE_EDIT\fR 8
+.IX Item "$INPLACE_EDIT"
+.PD 0
+.IP $^I 8
+.IX Xref "$^I $INPLACE_EDIT"
+.IX Item "$^I"
+.PD
+The current value of the inplace-edit extension.  Use \f(CW\*(C`undef\*(C'\fR to disable
+inplace editing.
+.Sp
+Mnemonic: value of \fB\-i\fR switch.
+.ie n .IP @ISA 8
+.el .IP \f(CW@ISA\fR 8
+.IX Xref "@ISA"
+.IX Item "@ISA"
+Each package contains a special array called \f(CW@ISA\fR which contains a list
+of that class's parent classes, if any. This array is simply a list of
+scalars, each of which is a string that corresponds to a package name. The
+array is examined when Perl does method resolution, which is covered in
+perlobj.
+.Sp
+To load packages while adding them to \f(CW@ISA\fR, see the parent pragma. The
+discouraged base pragma does this as well, but should not be used except
+when compatibility with the discouraged fields pragma is required.
+.IP $^M 8
+.IX Xref "$^M"
+.IX Item "$^M"
+By default, running out of memory is an untrappable, fatal error.
+However, if suitably built, Perl can use the contents of \f(CW$^M\fR
+as an emergency memory pool after \f(CWdie()\fRing.  Suppose that your Perl
+were compiled with \f(CW\*(C`\-DPERL_EMERGENCY_SBRK\*(C'\fR and used Perl's malloc.
+Then
+.Sp
+.Vb 1
+\&    $^M = \*(Aqa\*(Aq x (1 << 16);
+.Ve
+.Sp
+would allocate a 64K buffer for use in an emergency.  See the
+INSTALL file in the Perl distribution for information on how to
+add custom C compilation flags when compiling perl.  To discourage casual
+use of this advanced feature, there is no English long name for
+this variable.
+.Sp
+This variable was added in Perl 5.004.
+.IP ${^MAX_NESTED_EVAL_BEGIN_BLOCKS} 8
+.IX Item "${^MAX_NESTED_EVAL_BEGIN_BLOCKS}"
+This variable determines the maximum number \f(CW\*(C`eval EXPR\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR or
+\&\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR block nesting that is allowed. This means it also
+controls the maximum nesting of \f(CW\*(C`use\*(C'\fR statements as well.
+.Sp
+The default of 1000 should be sufficiently large for normal working
+purposes, and if you must raise it then you should be conservative
+with your choice or you may encounter segfaults from exhaustion of
+the C stack. It seems unlikely that real code has a use depth above
+1000, but we have left this configurable just in case.
+.Sp
+When set to \f(CW0\fR then \f(CW\*(C`BEGIN\*(C'\fR blocks inside of \f(CW\*(C`eval EXPR\*(C'\fR or
+\&\f(CW\*(C`require EXPR\*(C'\fR are forbidden entirely and will trigger an exception
+which will terminate the compilation and in the case of \f(CW\*(C`require\*(C'\fR
+will throw an exception, or in the case of \f(CW\*(C`eval\*(C'\fR return the error in
+\&\f(CW$@\fR as usual.
+.Sp
+Consider the code
+.Sp
+.Vb 1
+\& perl \-le\*(Aqsub f { eval "BEGIN { f() }"; } f()\*(Aq
+.Ve
+.Sp
+each invocation of \f(CWf()\fR will consume considerable C stack, and this
+variable is used to cause code like this to die instead of exhausting
+the C stack and triggering a segfault. Needless to say code like this is
+unusual, it is unlikely you will actually need to raise the setting.
+However it may be useful to set it to 0 for a limited time period to
+prevent BEGIN{} blocks from being executed during an \f(CW\*(C`eval EXPR\*(C'\fR.
+.Sp
+Note that setting this to 1 would NOT affect code like this:
+.Sp
+.Vb 1
+\&    BEGIN { $n += 1; BEGIN { $n += 2; BEGIN { $n += 4 } } }
+.Ve
+.Sp
+The reason is that BEGIN blocks are executed immediately after they are
+completed, thus the innermost will execute before the ones which contain
+it have even finished compiling, and the depth will not go above 1. In
+fact the above code is equivalent to
+.Sp
+.Vb 3
+\&    BEGIN { $n+=4 }
+\&    BEGIN { $n+=2 }
+\&    BEGIN { $n+=1 }
+.Ve
+.Sp
+which makes it obvious why a ${^MAX_EVAL_BEGIN_DEPTH} of 1 would not
+block this code.
+.Sp
+Only \f(CW\*(C`BEGIN\*(C'\fR's executed inside of an \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR (possibly via
+\&\f(CW\*(C`use\*(C'\fR) are affected.
+.ie n .IP $OSNAME 8
+.el .IP \f(CW$OSNAME\fR 8
+.IX Item "$OSNAME"
+.PD 0
+.IP $^O 8
+.IX Xref "$^O $OSNAME"
+.IX Item "$^O"
+.PD
+The name of the operating system under which this copy of Perl was
+built, as determined during the configuration process.  For examples
+see "PLATFORMS" in perlport.
+.Sp
+The value is identical to \f(CW$Config{\*(Aqosname\*(Aq}\fR.  See also Config
+and the \fB\-V\fR command-line switch documented in perlrun.
+.Sp
+In Windows platforms, \f(CW$^O\fR is not very helpful: since it is always
+\&\f(CW\*(C`MSWin32\*(C'\fR, it doesn't tell the difference between
+95/98/ME/NT/2000/XP/CE/.NET.  Use \f(CWWin32::GetOSName()\fR or
+\&\fBWin32::GetOSVersion()\fR (see Win32 and perlport) to distinguish
+between the variants.
+.Sp
+This variable was added in Perl 5.003.
+.ie n .IP %SIG 8
+.el .IP \f(CW%SIG\fR 8
+.IX Xref "%SIG"
+.IX Item "%SIG"
+The hash \f(CW%SIG\fR contains signal handlers for signals.  For example:
+.Sp
+.Vb 6
+\&    sub handler {   # 1st argument is signal name
+\&        my($sig) = @_;
+\&        print "Caught a SIG$sig\-\-shutting down\en";
+\&        close(LOG);
+\&        exit(0);
+\&    }
+\&
+\&    $SIG{\*(AqINT\*(Aq}  = \e&handler;
+\&    $SIG{\*(AqQUIT\*(Aq} = \e&handler;
+\&    ...
+\&    $SIG{\*(AqINT\*(Aq}  = \*(AqDEFAULT\*(Aq;   # restore default action
+\&    $SIG{\*(AqQUIT\*(Aq} = \*(AqIGNORE\*(Aq;    # ignore SIGQUIT
+.Ve
+.Sp
+Using a value of \f(CW\*(AqIGNORE\*(Aq\fR usually has the effect of ignoring the
+signal, except for the \f(CW\*(C`CHLD\*(C'\fR signal.  See perlipc for more about
+this special case.  Using an empty string or \f(CW\*(C`undef\*(C'\fR as the value has
+the same effect as \f(CW\*(AqDEFAULT\*(Aq\fR.
+.Sp
+Here are some other examples:
+.Sp
+.Vb 7
+\&    $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not
+\&                                # recommended)
+\&    $SIG{"PIPE"} = \e&Plumber;   # just fine; assume current
+\&                                # Plumber
+\&    $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
+\&    $SIG{"PIPE"} = Plumber();   # oops, what did Plumber()
+\&                                # return??
+.Ve
+.Sp
+Be sure not to use a bareword as the name of a signal handler,
+lest you inadvertently call it.
+.Sp
+Using a string that doesn't correspond to any existing function or a
+glob that doesn't contain a code slot is equivalent to \f(CW\*(AqIGNORE\*(Aq\fR,
+but a warning is emitted when the handler is being called (the warning
+is not emitted for the internal hooks described below).
+.Sp
+If your system has the \f(CWsigaction()\fR function then signal handlers
+are installed using it.  This means you get reliable signal handling.
+.Sp
+The default delivery policy of signals changed in Perl v5.8.0 from
+immediate (also known as "unsafe") to deferred, also known as "safe
+signals".  See perlipc for more information.
+.Sp
+Certain internal hooks can be also set using the \f(CW%SIG\fR hash.  The
+routine indicated by \f(CW$SIG{_\|_WARN_\|_}\fR is called when a warning
+message is about to be printed.  The warning message is passed as the
+first argument.  The presence of a \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hook causes the
+ordinary printing of warnings to \f(CW\*(C`STDERR\*(C'\fR to be suppressed.  You can
+use this to save warnings in a variable, or turn warnings into fatal
+errors, like this:
+.Sp
+.Vb 2
+\&    local $SIG{_\|_WARN_\|_} = sub { die $_[0] };
+\&    eval $proggie;
+.Ve
+.Sp
+As the \f(CW\*(AqIGNORE\*(Aq\fR hook is not supported by \f(CW\*(C`_\|_WARN_\|_\*(C'\fR, its effect is
+the same as using \f(CW\*(AqDEFAULT\*(Aq\fR.  You can disable warnings using the
+empty subroutine:
+.Sp
+.Vb 1
+\&    local $SIG{_\|_WARN_\|_} = sub {};
+.Ve
+.Sp
+The routine indicated by \f(CW$SIG{_\|_DIE_\|_}\fR is called when a fatal
+exception is about to be thrown.  The error message is passed as the
+first argument.  When a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hook routine returns, the exception
+processing continues as it would have in the absence of the hook,
+unless the hook routine itself exits via a \f(CW\*(C`goto &sub\*(C'\fR, a loop exit,
+or a \f(CWdie()\fR.  The \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler is explicitly disabled during
+the call, so that you can die from a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler.  Similarly
+for \f(CW\*(C`_\|_WARN_\|_\*(C'\fR.
+.Sp
+The \f(CW$SIG{_\|_DIE_\|_}\fR hook is called even inside an \f(CWeval()\fR. It was
+never intended to happen this way, but an implementation glitch made
+this possible. This used to be deprecated, as it allowed strange action
+at a distance like rewriting a pending exception in \f(CW$@\fR. Plans to
+rectify this have been scrapped, as users found that rewriting a
+pending exception is actually a useful feature, and not a bug.
+.Sp
+The \f(CW$SIG{_\|_DIE_\|_}\fR doesn't support \f(CW\*(AqIGNORE\*(Aq\fR; it has the same
+effect as \f(CW\*(AqDEFAULT\*(Aq\fR.
+.Sp
+\&\f(CW\*(C`_\|_DIE_\|_\*(C'\fR/\f(CW\*(C`_\|_WARN_\|_\*(C'\fR handlers are very special in one respect: they
+may be called to report (probable) errors found by the parser.  In such
+a case the parser may be in inconsistent state, so any attempt to
+evaluate Perl code from such a handler will probably result in a
+segfault.  This means that warnings or errors that result from parsing
+Perl should be used with extreme caution, like this:
+.Sp
+.Vb 5
+\&    require Carp if defined $^S;
+\&    Carp::confess("Something wrong") if defined &Carp::confess;
+\&    die "Something wrong, but could not load Carp to give "
+\&      . "backtrace...\en\et"
+\&      . "To see backtrace try starting Perl with \-MCarp switch";
+.Ve
+.Sp
+Here the first line will load \f(CW\*(C`Carp\*(C'\fR \fIunless\fR it is the parser who
+called the handler.  The second line will print backtrace and die if
+\&\f(CW\*(C`Carp\*(C'\fR was available.  The third line will be executed only if \f(CW\*(C`Carp\*(C'\fR was
+not available.
+.Sp
+Having to even think about the \f(CW$^S\fR variable in your exception
+handlers is simply wrong.  \f(CW$SIG{_\|_DIE_\|_}\fR as currently implemented
+invites grievous and difficult to track down errors.  Avoid it
+and use an \f(CW\*(C`END{}\*(C'\fR or CORE::GLOBAL::die override instead.
+.Sp
+See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and
+warnings for additional information.
+.IP %{^HOOK} 8
+.IX Xref "%{^HOOK}"
+.IX Item "%{^HOOK}"
+This hash contains coderefs which are called when various perl keywords
+which are hard or impossible to wrap are called. The keys of this hash
+are named after the keyword that is being hooked, followed by two
+underbars and then a phase term; either "before" or "after".
+.Sp
+Perl will throw an error if you attempt modify a key which is not
+documented to exist, or if you attempt to store anything other than a
+code reference or undef in the hash.  If you wish to use an object to
+implement a hook you can use currying to embed the object into an
+anonymous code reference.
+.Sp
+Currently there is only one keyword which can be hooked, \f(CW\*(C`require\*(C'\fR, but
+it is expected that in future releases there will be additional keywords
+with hook support.
+.RS 8
+.IP require_\|_before 4
+.IX Item "require__before"
+The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR is called by
+\&\f(CW\*(C`require\*(C'\fR \fBbefore\fR it checks \f(CW%INC\fR, looks up \f(CW@INC\fR, calls INC
+hooks, or compiles any code.  It is called with a single argument, the
+filename for the item being required (package names are converted to
+paths).  It may alter this filename to change what file is loaded.  If
+the hook dies during execution then it will block the require from executing.
+.Sp
+In order to make it easy to perform an action with shared state both
+before and after the require keyword was executed the \f(CW\*(C`require_\|_before\*(C'\fR
+hook may return a "post-action" coderef which will in turn be executed when
+the \f(CW\*(C`require\*(C'\fR completes.  This coderef will be executed regardless as to
+whether the require completed succesfully or threw an exception.  It will
+be called with the filename that was required.  You can check \f(CW%INC\fR to
+determine if the require was successful.  Any other return from the
+\&\f(CW\*(C`require_\|_before\*(C'\fR hook will be silently ignored.
+.Sp
+\&\f(CW\*(C`require_\|_before\*(C'\fR hooks are called in FIFO order, and if the hook
+returns a code reference those code references will be called in FILO
+order.  In other words if A requires B requires C, then
+\&\f(CW\*(C`require_\|_before\*(C'\fR will be called first for A, then B and then C, and
+the post-action code reference will executed first for C, then B and
+then finally A.
+.Sp
+Well behaved code should ensure that when setting up a
+\&\f(CW\*(C`require_\|_before\*(C'\fR hook that any prior installed hook will be called,
+and that their return value, if a code reference, will be called as
+well.  See "require" in perlfunc for an example implementation.
+.IP require_\|_after 4
+.IX Item "require__after"
+The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR is called by
+\&\f(CW\*(C`require\*(C'\fR \fBafter\fR the require completes.  It is called with a single
+argument, the filename for the item being required (package names are
+converted to paths).  It is executed when the \f(CW\*(C`require\*(C'\fR completes,
+either via exception or via completion of the require statement, and you
+can check \f(CW%INC\fR to determine if the require was successful.
+.Sp
+The \f(CW\*(C`require_\|_after\*(C'\fR hook is called for each required file in FILO
+order. In other words if A requires B requires C, then \f(CW\*(C`require_\|_after\*(C'\fR
+will be called first for C, then B and then A.
+.RE
+.RS 8
+.RE
+.ie n .IP $BASETIME 8
+.el .IP \f(CW$BASETIME\fR 8
+.IX Item "$BASETIME"
+.PD 0
+.IP $^T 8
+.IX Xref "$^T $BASETIME"
+.IX Item "$^T"
+.PD
+The time at which the program began running, in seconds since the
+epoch (beginning of 1970).  The values returned by the \fB\-M\fR, \fB\-A\fR,
+and \fB\-C\fR filetests are based on this value.
+.ie n .IP $PERL_VERSION 8
+.el .IP \f(CW$PERL_VERSION\fR 8
+.IX Item "$PERL_VERSION"
+.PD 0
+.IP $^V 8
+.IX Xref "$^V $PERL_VERSION"
+.IX Item "$^V"
+.PD
+The revision, version, and subversion of the Perl interpreter,
+represented as a version object.
+.Sp
+This variable first appeared in perl v5.6.0; earlier versions of perl
+will see an undefined value.  Before perl v5.10.0 \f(CW$^V\fR was represented
+as a v\-string rather than a version object.
+.Sp
+\&\f(CW$^V\fR can be used to determine whether the Perl interpreter executing
+a script is in the right range of versions.  For example:
+.Sp
+.Vb 1
+\&    warn "Hashes not randomized!\en" if !$^V or $^V lt v5.8.1
+.Ve
+.Sp
+While version objects overload stringification, to portably convert
+\&\f(CW$^V\fR into its string representation, use \f(CWsprintf()\fR's \f(CW"%vd"\fR
+conversion, which works for both v\-strings or version objects:
+.Sp
+.Vb 1
+\&    printf "version is v%vd\en", $^V;  # Perl\*(Aqs version
+.Ve
+.Sp
+See the documentation of \f(CW\*(C`use VERSION\*(C'\fR and \f(CW\*(C`require VERSION\*(C'\fR
+for a convenient way to fail if the running Perl interpreter is too old.
+.Sp
+See also \f(CW"$]"\fR for a decimal representation of the Perl version.
+.Sp
+The main advantage of \f(CW$^V\fR over \f(CW$]\fR is that, for Perl v5.10.0 or
+later, it overloads operators, allowing easy comparison against other
+version representations (e.g. decimal, literal v\-string, "v1.2.3", or
+objects).  The disadvantage is that prior to v5.10.0, it was only a
+literal v\-string, which can't be easily printed or compared, whereas
+the behavior of \f(CW$]\fR is unchanged on all versions of Perl.
+.Sp
+Mnemonic: use ^V for a version object.
+.ie n .IP $EXECUTABLE_NAME 8
+.el .IP \f(CW$EXECUTABLE_NAME\fR 8
+.IX Item "$EXECUTABLE_NAME"
+.PD 0
+.IP $^X 8
+.IX Xref "$^X $EXECUTABLE_NAME"
+.IX Item "$^X"
+.PD
+The name used to execute the current copy of Perl, from C's
+\&\f(CW\*(C`argv[0]\*(C'\fR or (where supported) \fI/proc/self/exe\fR.
+.Sp
+Depending on the host operating system, the value of \f(CW$^X\fR may be
+a relative or absolute pathname of the perl program file, or may
+be the string used to invoke perl but not the pathname of the
+perl program file.  Also, most operating systems permit invoking
+programs that are not in the PATH environment variable, so there
+is no guarantee that the value of \f(CW$^X\fR is in PATH.  For VMS, the
+value may or may not include a version number.
+.Sp
+You usually can use the value of \f(CW$^X\fR to re-invoke an independent
+copy of the same perl that is currently running, e.g.,
+.Sp
+.Vb 1
+\&    @first_run = \`$^X \-le "print int rand 100 for 1..100"\`;
+.Ve
+.Sp
+But recall that not all operating systems support forking or
+capturing of the output of commands, so this complex statement
+may not be portable.
+.Sp
+It is not safe to use the value of \f(CW$^X\fR as a path name of a file,
+as some operating systems that have a mandatory suffix on
+executable files do not require use of the suffix when invoking
+a command.  To convert the value of \f(CW$^X\fR to a path name, use the
+following statements:
+.Sp
+.Vb 7
+\&    # Build up a set of file names (not command names).
+\&    use Config;
+\&    my $this_perl = $^X;
+\&    if ($^O ne \*(AqVMS\*(Aq) {
+\&        $this_perl .= $Config{_exe}
+\&        unless $this_perl =~ m/$Config{_exe}$/i;
+\&    }
+.Ve
+.Sp
+Because many operating systems permit anyone with read access to
+the Perl program file to make a copy of it, patch the copy, and
+then execute the copy, the security-conscious Perl programmer
+should take care to invoke the installed copy of perl, not the
+copy referenced by \f(CW$^X\fR.  The following statements accomplish
+this goal, and produce a pathname that can be invoked as a
+command or referenced as a file.
+.Sp
+.Vb 6
+\&    use Config;
+\&    my $secure_perl_path = $Config{perlpath};
+\&    if ($^O ne \*(AqVMS\*(Aq) {
+\&        $secure_perl_path .= $Config{_exe}
+\&        unless $secure_perl_path =~ m/$Config{_exe}$/i;
+\&    }
+.Ve
+.SS "Variables related to regular expressions"
+.IX Subsection "Variables related to regular expressions"
+Most of the special variables related to regular expressions are side
+effects. Perl sets these variables when it has completed a match
+successfully, so you should check the match result before using them.
+For instance:
+.PP
+.Vb 3
+\&    if( /P(A)TT(ER)N/ ) {
+\&        print "I found $1 and $2\en";
+\&    }
+.Ve
+.PP
+These variables are read-only and behave similarly to a dynamically
+scoped variable, with only a few exceptions which are explicitly
+documented as behaving otherwise.  See the following section for more
+details.
+.PP
+\fIScoping Rules of Regex Variables\fR
+.IX Subsection "Scoping Rules of Regex Variables"
+.PP
+Regular expression variables allow the programmer to access the state of
+the most recent \fIsuccessful\fR regex match in the current dynamic scope.
+.PP
+The variables themselves are global and unscoped, but the data they
+access is scoped similarly to dynamically scoped variables, in that
+every successful match behaves as though it localizes a global state
+object to the current block or file scope.
+(See "Compound Statements" in perlsyn for more details on dynamic
+scoping and the \f(CW\*(C`local\*(C'\fR keyword.)
+.PP
+A \fIsuccessful match\fR includes any successful match performed by the
+search and replace operator \f(CW\*(C`s///\*(C'\fR as well as those performed by the
+\&\f(CW\*(C`m//\*(C'\fR operator.
+.PP
+Consider the following code:
+.PP
+.Vb 7
+\&    my @state;
+\&    sub matchit {
+\&        push @state, $1;            # pushes "baz"
+\&        my $str = shift;
+\&        $str =~ /(zat)/;            # matches "zat"
+\&        push @state, $1;            # pushes "zat"
+\&    }
+\&
+\&    {
+\&        $str = "foo bar baz blorp zat";
+\&        $str =~ /(foo)/;            # matches "foo"
+\&        push @state, $1;            # pushes "foo"
+\&        {
+\&            $str =~ /(pizza)/;      # does NOT match
+\&            push @state, $1;        # pushes "foo"
+\&            $str =~ /(bar)/;        # matches "bar"
+\&            push @state, $1;        # pushes "bar"
+\&            $str =~ /(baz)/;        # matches "baz"
+\&            matchit($str);          # see above
+\&            push @state, $1;        # pushes "baz"
+\&        }
+\&        $str =~ s/noodles/rice/;    # does NOT match
+\&        push @state, $1;            # pushes "foo"
+\&        $str =~ s/(blorp)/zwoop/;   # matches "blorp"
+\&        push @state, $1;            # pushes "blorp"
+\&    }
+\&    # the following prints "foo, foo, bar, baz, zat, baz, foo, blorp"
+\&    print join ",", @state;
+.Ve
+.PP
+Notice that each successful match in the exact same scope overrides the
+match context of the previous successful match, but that unsuccessful
+matches do not. Also note that in an inner nested scope the previous
+state from an outer dynamic scope persists until it has been overriden
+by another successful match, but that when the inner nested scope exits
+whatever match context was in effect before the inner successful match
+is restored when the scope concludes.
+.PP
+It is a known issue that \f(CW\*(C`goto LABEL\*(C'\fR may interact poorly with the
+dynamically scoped match context. This may not be fixable, and is
+considered to be one of many good reasons to avoid \f(CW\*(C`goto LABEL\*(C'\fR.
+.PP
+\fIPerformance issues\fR
+.IX Subsection "Performance issues"
+.PP
+Traditionally in Perl, any use of any of the three variables  \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR
+or \f(CW\*(C`$\*(Aq\*(C'\fR (or their \f(CW\*(C`use English\*(C'\fR equivalents) anywhere in the code, caused
+all subsequent successful pattern matches to make a copy of the matched
+string, in case the code might subsequently access one of those variables.
+This imposed a considerable performance penalty across the whole program,
+so generally the use of these variables has been discouraged.
+.PP
+In Perl 5.6.0 the \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR dynamic arrays were introduced that
+supply the indices of successful matches. So you could for example do
+this:
+.PP
+.Vb 1
+\&    $str =~ /pattern/;
+\&
+\&    print $\`, $&, $\*(Aq; # bad: performance hit
+\&
+\&    print             # good: no performance hit
+\&    substr($str, 0,     $\-[0]),
+\&    substr($str, $\-[0], $+[0]\-$\-[0]),
+\&    substr($str, $+[0]);
+.Ve
+.PP
+In Perl 5.10.0 the \f(CW\*(C`/p\*(C'\fR match operator flag and the \f(CW\*(C`${^PREMATCH}\*(C'\fR,
+\&\f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR variables were introduced, that allowed
+you to suffer the penalties only on patterns marked with \f(CW\*(C`/p\*(C'\fR.
+.PP
+In Perl 5.18.0 onwards, perl started noting the presence of each of the
+three variables separately, and only copied that part of the string
+required; so in
+.PP
+.Vb 1
+\&    $\`; $&; "abcdefgh" =~ /d/
+.Ve
+.PP
+perl would only copy the "abcd" part of the string. That could make a big
+difference in something like
+.PP
+.Vb 3
+\&    $str = \*(Aqx\*(Aq x 1_000_000;
+\&    $&; # whoops
+\&    $str =~ /x/g # one char copied a million times, not a million chars
+.Ve
+.PP
+In Perl 5.20.0 a new copy-on-write system was enabled by default, which
+finally fixes most of the performance issues with these three variables, and
+makes them safe to use anywhere.
+.PP
+The \f(CW\*(C`Devel::NYTProf\*(C'\fR and \f(CW\*(C`Devel::FindAmpersand\*(C'\fR modules can help you
+find uses of these problematic match variables in your code.
+.ie n .IP "$<\fIdigits\fR> ($1, $2, ...)" 8
+.el .IP "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)" 8
+.IX Xref "$1 $2 $3 $\\f(ISdigits\\f(IE"
+.IX Item "$<digits> ($1, $2, ...)"
+Contains the subpattern from the corresponding set of capturing
+parentheses from the last successful pattern match in the current
+dynamic scope. (See "Scoping Rules of Regex Variables".)
+.Sp
+Note there is a distinction between a capture buffer which matches
+the empty string a capture buffer which is optional. Eg, \f(CW\*(C`(x?)\*(C'\fR and
+\&\f(CW\*(C`(x)?\*(C'\fR The latter may be undef, the former not.
+.Sp
+These variables are read-only.
+.Sp
+Mnemonic: like \edigits.
+.IP @{^CAPTURE} 8
+.IX Xref "@{^CAPTURE} @^CAPTURE"
+.IX Item "@{^CAPTURE}"
+An array which exposes the contents of the capture buffers, if any, of
+the last successful pattern match, not counting patterns matched
+in nested blocks that have been exited already.
+.Sp
+Note that the 0 index of @{^CAPTURE} is equivalent to \f(CW$1\fR, the 1 index
+is equivalent to \f(CW$2\fR, etc.
+.Sp
+.Vb 3
+\&    if ("foal"=~/(.)(.)(.)(.)/) {
+\&        print join "\-", @{^CAPTURE};
+\&    }
+.Ve
+.Sp
+should output "f\-o-a-l".
+.Sp
+See also "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)", "%{^CAPTURE}" and
+"%{^CAPTURE_ALL}".
+.Sp
+Note that unlike most other regex magic variables there is no single
+letter equivalent to \f(CW\*(C`@{^CAPTURE}\*(C'\fR. Also be aware that when
+interpolating subscripts of this array you \fBmust\fR use the demarcated
+variable form, for instance
+.Sp
+.Vb 1
+\&    print "${^CAPTURE[0]}"
+.Ve
+.Sp
+see "Demarcated variable names using braces" in perldata for more
+information on this form and its uses.
+.Sp
+This variable was added in 5.25.7
+.ie n .IP $MATCH 8
+.el .IP \f(CW$MATCH\fR 8
+.IX Item "$MATCH"
+.PD 0
+.IP $& 8
+.IX Xref "$& $MATCH"
+.PD
+The string matched by the last successful pattern match.
+(See "Scoping Rules of Regex Variables".)
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: like \f(CW\*(C`&\*(C'\fR in some editors.
+.IP ${^MATCH} 8
+.IX Xref "${^MATCH}"
+.IX Item "${^MATCH}"
+It is only guaranteed to return a defined value when the pattern was
+compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW$&\fR (\f(CW$MATCH\fR) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $PREMATCH 8
+.el .IP \f(CW$PREMATCH\fR 8
+.IX Item "$PREMATCH"
+.PD 0
+.IP $` 8
+.IX Xref "$` $PREMATCH"
+.PD
+The string preceding whatever was matched by the last successful
+pattern match. (See "Scoping Rules of Regex Variables").
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: \f(CW\*(C`\`\*(C'\fR often precedes a quoted string.
+.IP ${^PREMATCH} 8
+.IX Xref "${^PREMATCH}"
+.IX Item "${^PREMATCH}"
+It is only guaranteed to return a defined value when the pattern was
+executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW\*(C`$\`\*(C'\fR ($PREMATCH) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $POSTMATCH 8
+.el .IP \f(CW$POSTMATCH\fR 8
+.IX Item "$POSTMATCH"
+.PD 0
+.IP $' 8
+.IX Xref "$' $POSTMATCH @-"
+.PD
+The string following whatever was matched by the last successful
+pattern match. (See "Scoping Rules of Regex Variables"). Example:
+.Sp
+.Vb 3
+\&    local $_ = \*(Aqabcdefghi\*(Aq;
+\&    /def/;
+\&    print "$\`:$&:$\*(Aq\en";       # prints abc:def:ghi
+.Ve
+.Sp
+See "Performance issues" above for the serious performance implications
+of using this variable (even once) in your code.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: \f(CW\*(C`\*(Aq\*(C'\fR often follows a quoted string.
+.IP ${^POSTMATCH} 8
+.IX Xref "${^POSTMATCH}"
+.IX Item "${^POSTMATCH}"
+It is only guaranteed to return a defined value when the pattern was
+compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier.
+.Sp
+This is similar to \f(CW\*(C`$\*(Aq\*(C'\fR (\f(CW$POSTMATCH\fR) except that to use it you must
+use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur
+and performance penalty associated with that variable.
+.Sp
+See "Performance issues" above.
+.Sp
+This variable was added in Perl v5.10.0.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP $LAST_PAREN_MATCH 8
+.el .IP \f(CW$LAST_PAREN_MATCH\fR 8
+.IX Item "$LAST_PAREN_MATCH"
+.PD 0
+.IP $+ 8
+.IX Xref "$+ $LAST_PAREN_MATCH"
+.PD
+The text matched by the highest used capture group of the last
+successful search pattern. (See "Scoping Rules of Regex Variables").
+It is logically equivalent to the highest
+numbered capture variable (\f(CW$1\fR, \f(CW$2\fR, ...) which has a defined value.
+.Sp
+This is useful if you don't know which one of a set of alternative patterns
+matched.  For example:
+.Sp
+.Vb 1
+\&    /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+.Ve
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+Mnemonic: be positive and forward looking.
+.ie n .IP $LAST_SUBMATCH_RESULT 8
+.el .IP \f(CW$LAST_SUBMATCH_RESULT\fR 8
+.IX Item "$LAST_SUBMATCH_RESULT"
+.PD 0
+.IP $^N 8
+.IX Xref "$^N $LAST_SUBMATCH_RESULT"
+.IX Item "$^N"
+.PD
+The text matched by the used group most-recently closed (i.e. the group
+with the rightmost closing parenthesis) of the last successful match.
+(See "Scoping Rules of Regex Variables").
+.Sp
+This is subtly different from \f(CW$+\fR. For example in
+.Sp
+.Vb 1
+\&    "ab" =~ /^((.)(.))$/
+.Ve
+.Sp
+we have
+.Sp
+.Vb 3
+\&    $1,$^N   have the value "ab"
+\&    $2       has  the value "a"
+\&    $3,$+    have the value "b"
+.Ve
+.Sp
+This is primarily used inside \f(CW\*(C`(?{...})\*(C'\fR blocks for examining text
+recently matched.  For example, to effectively capture text to a variable
+(in addition to \f(CW$1\fR, \f(CW$2\fR, etc.), replace \f(CW\*(C`(...)\*(C'\fR with
+.Sp
+.Vb 1
+\&    (?:(...)(?{ $var = $^N }))
+.Ve
+.Sp
+By setting and then using \f(CW$var\fR in this way relieves you from having to
+worry about exactly which numbered set of parentheses they are.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.8.0.
+.Sp
+Mnemonic: the (possibly) Nested parenthesis that most recently closed.
+.ie n .IP @LAST_MATCH_END 8
+.el .IP \f(CW@LAST_MATCH_END\fR 8
+.IX Item "@LAST_MATCH_END"
+.PD 0
+.IP @+ 8
+.IX Xref "@+ @LAST_MATCH_END"
+.PD
+This array holds the offsets of the ends of the last successful
+match and any matching capture buffers that the pattern contains.
+(See "Scoping Rules of Regex Variables")
+.Sp
+The number of elements it contains will be one more than the number
+of capture buffers in the pattern, regardless of which capture buffers
+actually matched. You can use this to determine how many capture
+buffers there are in the pattern. (As opposed to \f(CW\*(C`@\-\*(C'\fR which may
+have fewer elements.)
+.Sp
+\&\f(CW$+[0]\fR is the offset into the string of the end of the entire match.
+This is the same value as what the \f(CW\*(C`pos\*(C'\fR function returns when called
+on the variable that was matched against. The \fIn\fRth element of this
+array holds the offset of the \fIn\fRth submatch, so \f(CW$+[1]\fR is the offset
+past where \f(CW$1\fR ends, \f(CW$+[2]\fR the offset past where \f(CW$2\fR ends, and so
+on. You can use \f(CW$#+\fR to determine how many subgroups were in the last
+successful match. See the examples given for the \f(CW\*(C`@\-\*(C'\fR variable.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.6.0.
+.IP %{^CAPTURE} 8
+.IX Item "%{^CAPTURE}"
+.PD 0
+.ie n .IP %LAST_PAREN_MATCH 8
+.el .IP \f(CW%LAST_PAREN_MATCH\fR 8
+.IX Item "%LAST_PAREN_MATCH"
+.IP %+ 8
+.IX Xref "%+ %LAST_PAREN_MATCH %{^CAPTURE}"
+.PD
+Similar to \f(CW\*(C`@+\*(C'\fR, the \f(CW\*(C`%+\*(C'\fR hash allows access to the named capture
+buffers, should they exist, in the last successful match in the
+currently active dynamic scope. (See "Scoping Rules of Regex Variables").
+.Sp
+For example, \f(CW$+{foo}\fR is equivalent to \f(CW$1\fR after the following match:
+.Sp
+.Vb 1
+\&    \*(Aqfoo\*(Aq =~ /(?<foo>foo)/;
+.Ve
+.Sp
+The keys of the \f(CW\*(C`%+\*(C'\fR hash list only the names of buffers that have
+captured (and that are thus associated to defined values).
+.Sp
+If multiple distinct capture groups have the same name, then
+\&\f(CW$+{NAME}\fR will refer to the leftmost defined group in the match.
+.Sp
+The underlying behaviour of \f(CW\*(C`%+\*(C'\fR is provided by the
+Tie::Hash::NamedCapture module.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash
+associated with the last successful regular expression.  Therefore mixing
+iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising.
+.Sp
+This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE}\*(C'\fR alias was
+added in 5.25.7.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.ie n .IP @LAST_MATCH_START 8
+.el .IP \f(CW@LAST_MATCH_START\fR 8
+.IX Item "@LAST_MATCH_START"
+.PD 0
+.IP @\- 8
+.IX Xref "@- @LAST_MATCH_START"
+.PD
+This array holds the offsets of the beginnings of the last successful
+match and any capture buffers it contains.
+(See "Scoping Rules of Regex Variables").
+.Sp
+The number of elements it contains will be one more than the number of
+the highest capture buffers (also called a subgroup) that actually
+matched something. (As opposed to \f(CW\*(C`@+\*(C'\fR which may have fewer elements.)
+.Sp
+\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset of the start of the last successful match.
+\&\f(CW\*(C`$\-[\fR\f(CIn\fR\f(CW]\*(C'\fR is the offset of the start of the substring matched by
+\&\fIn\fR\-th subpattern, or undef if the subpattern did not match.
+.Sp
+Thus, after a match against \f(CW$_\fR, \f(CW$&\fR coincides with
+\&\f(CW\*(C`substr $_, $\-[0], $+[0] \- $\-[0]\*(C'\fR.  Similarly, \f(CW\*(C`$\fR\f(CIn\fR\f(CW\*(C'\fR coincides
+with \f(CW\*(C`substr $_, $\-[n], $+[n] \- $\-[n]\*(C'\fR if \f(CW\*(C`$\-[n]\*(C'\fR is defined, and
+\&\f(CW$+\fR coincides with \f(CW\*(C`substr $_, $\-[$#\-], $+[$#\-] \- $\-[$#\-]\*(C'\fR.
+One can use \f(CW\*(C`$#\-\*(C'\fR to find the last matched subgroup in the last
+successful match.  Contrast with \f(CW$#+\fR, the number of subgroups
+in the regular expression.
+.Sp
+\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset into the string of the beginning of the
+entire match.  The \fIn\fRth element of this array holds the offset
+of the \fIn\fRth submatch, so \f(CW\*(C`$\-[1]\*(C'\fR is the offset where \f(CW$1\fR
+begins, \f(CW\*(C`$\-[2]\*(C'\fR the offset where \f(CW$2\fR begins, and so on.
+.Sp
+After a match against some variable \f(CW$var\fR:
+.RS 8
+.ie n .IP """$\`"" is the same as ""substr($var, 0, $\-[0])""" 5
+.el .IP "\f(CW$\`\fR is the same as \f(CWsubstr($var, 0, $\-[0])\fR" 5
+.IX Item "$ is the same as substr($var, 0, $-[0])"
+.PD 0
+.ie n .IP "$& is the same as ""substr($var, $\-[0], $+[0] \- $\-[0])""" 5
+.el .IP "\f(CW$&\fR is the same as \f(CWsubstr($var, $\-[0], $+[0] \- $\-[0])\fR" 5
+.IX Item "$& is the same as substr($var, $-[0], $+[0] - $-[0])"
+.ie n .IP """$\*(Aq"" is the same as ""substr($var, $+[0])""" 5
+.el .IP "\f(CW$\*(Aq\fR is the same as \f(CWsubstr($var, $+[0])\fR" 5
+.IX Item "$ is the same as substr($var, $+[0])"
+.ie n .IP "$1 is the same as ""substr($var, $\-[1], $+[1] \- $\-[1])""" 5
+.el .IP "\f(CW$1\fR is the same as \f(CWsubstr($var, $\-[1], $+[1] \- $\-[1])\fR" 5
+.IX Item "$1 is the same as substr($var, $-[1], $+[1] - $-[1])"
+.ie n .IP "$2 is the same as ""substr($var, $\-[2], $+[2] \- $\-[2])""" 5
+.el .IP "\f(CW$2\fR is the same as \f(CWsubstr($var, $\-[2], $+[2] \- $\-[2])\fR" 5
+.IX Item "$2 is the same as substr($var, $-[2], $+[2] - $-[2])"
+.ie n .IP "$3 is the same as ""substr($var, $\-[3], $+[3] \- $\-[3])""" 5
+.el .IP "\f(CW$3\fR is the same as \f(CWsubstr($var, $\-[3], $+[3] \- $\-[3])\fR" 5
+.IX Item "$3 is the same as substr($var, $-[3], $+[3] - $-[3])"
+.RE
+.RS 8
+.PD
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.Sp
+This variable was added in Perl v5.6.0.
+.RE
+.IP %{^CAPTURE_ALL} 8
+.IX Xref "%{^CAPTURE_ALL}"
+.IX Item "%{^CAPTURE_ALL}"
+.PD 0
+.IP %\- 8
+.IX Xref "%-"
+.PD
+Similar to \f(CW\*(C`%+\*(C'\fR, this variable allows access to the named capture
+groups in the last successful match in the currently active dynamic
+scope. (See "Scoping Rules of Regex Variables"). To each capture group
+name found in the regular expression, it associates a reference to an
+array containing the list of values captured by all buffers with that
+name (should there be several of them), in the order where they appear.
+.Sp
+Here's an example:
+.Sp
+.Vb 12
+\&    if (\*(Aq1234\*(Aq =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
+\&        foreach my $bufname (sort keys %\-) {
+\&            my $ary = $\-{$bufname};
+\&            foreach my $idx (0..$#$ary) {
+\&                print "\e$\-{$bufname}[$idx] : ",
+\&                      (defined($ary\->[$idx])
+\&                          ? "\*(Aq$ary\->[$idx]\*(Aq"
+\&                          : "undef"),
+\&                      "\en";
+\&            }
+\&        }
+\&    }
+.Ve
+.Sp
+would print out:
+.Sp
+.Vb 4
+\&    $\-{A}[0] : \*(Aq1\*(Aq
+\&    $\-{A}[1] : \*(Aq3\*(Aq
+\&    $\-{B}[0] : \*(Aq2\*(Aq
+\&    $\-{B}[1] : \*(Aq4\*(Aq
+.Ve
+.Sp
+The keys of the \f(CW\*(C`%\-\*(C'\fR hash correspond to all buffer names found in
+the regular expression.
+.Sp
+The behaviour of \f(CW\*(C`%\-\*(C'\fR is implemented via the
+Tie::Hash::NamedCapture module.
+.Sp
+\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash
+associated with the last successful regular expression.  Therefore mixing
+iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results.
+Likewise, if the last successful match changes, then the results may be
+surprising. See "Scoping Rules of Regex Variables".
+.Sp
+This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR alias was
+added in 5.25.7.
+.Sp
+This variable is read-only, and its value is dynamically scoped.
+.IP ${^LAST_SUCCESSFUL_PATTERN} 8
+.IX Item "${^LAST_SUCCESSFUL_PATTERN}"
+The last successful pattern that matched in the current scope.  The empty
+pattern defaults to matching to this. For instance:
+.Sp
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s//BLAH/;
+\&    }
+.Ve
+.Sp
+and
+.Sp
+.Vb 3
+\&    if (m/foo/ || m/bar/) {
+\&        s/${^LAST_SUCCESSFUL_PATTERN}/BLAH/;
+\&    }
+.Ve
+.Sp
+are equivalent.
+.Sp
+You can use this to debug which pattern matched last, or to match with it again.
+.Sp
+Added in Perl 5.37.10.
+.ie n .IP $LAST_REGEXP_CODE_RESULT 8
+.el .IP \f(CW$LAST_REGEXP_CODE_RESULT\fR 8
+.IX Item "$LAST_REGEXP_CODE_RESULT"
+.PD 0
+.IP $^R 8
+.IX Xref "$^R $LAST_REGEXP_CODE_RESULT"
+.IX Item "$^R"
+.PD
+The result of evaluation of the last successful \f(CW\*(C`(?{ code })\*(C'\fR
+regular expression assertion (see perlre).
+.Sp
+This variable may be written to, and its value is scoped normally,
+unlike most other regex variables.
+.Sp
+This variable was added in Perl 5.005.
+.IP ${^RE_COMPILE_RECURSION_LIMIT} 8
+.IX Xref "${^RE_COMPILE_RECURSION_LIMIT}"
+.IX Item "${^RE_COMPILE_RECURSION_LIMIT}"
+The current value giving the maximum number of open but unclosed
+parenthetical groups there may be at any point during a regular
+expression compilation.  The default is currently 1000 nested groups.
+You may adjust it depending on your needs and the amount of memory
+available.
+.Sp
+This variable was added in Perl v5.30.0.
+.IP ${^RE_DEBUG_FLAGS} 8
+.IX Xref "${^RE_DEBUG_FLAGS}"
+.IX Item "${^RE_DEBUG_FLAGS}"
+The current value of the regex debugging flags.  Set to 0 for no debug output
+even when the \f(CW\*(C`re \*(Aqdebug\*(Aq\*(C'\fR module is loaded.  See re for details.
+.Sp
+This variable was added in Perl v5.10.0.
+.IP ${^RE_TRIE_MAXBUF} 8
+.IX Xref "${^RE_TRIE_MAXBUF}"
+.IX Item "${^RE_TRIE_MAXBUF}"
+Controls how certain regex optimisations are applied and how much memory they
+utilize.  This value by default is 65536 which corresponds to a 512kB
+temporary cache.  Set this to a higher value to trade
+memory for speed when matching large alternations.  Set
+it to a lower value if you want the optimisations to
+be as conservative of memory as possible but still occur, and set it to a
+negative value to prevent the optimisation and conserve the most memory.
+Under normal situations this variable should be of no interest to you.
+.Sp
+This variable was added in Perl v5.10.0.
+.SS "Variables related to filehandles"
+.IX Subsection "Variables related to filehandles"
+Variables that depend on the currently selected filehandle may be set
+by calling an appropriate object method on the \f(CW\*(C`IO::Handle\*(C'\fR object,
+although this is less efficient than using the regular built-in
+variables.  (Summary lines below for this contain the word HANDLE.)
+First you must say
+.PP
+.Vb 1
+\&    use IO::Handle;
+.Ve
+.PP
+after which you may use either
+.PP
+.Vb 1
+\&    method HANDLE EXPR
+.Ve
+.PP
+or more safely,
+.PP
+.Vb 1
+\&    HANDLE\->method(EXPR)
+.Ve
+.PP
+Each method returns the old value of the \f(CW\*(C`IO::Handle\*(C'\fR attribute.  The
+methods each take an optional EXPR, which, if supplied, specifies the
+new value for the \f(CW\*(C`IO::Handle\*(C'\fR attribute in question.  If not
+supplied, most methods do nothing to the current value\-\-except for
+\&\f(CWautoflush()\fR, which will assume a 1 for you, just to be different.
+.PP
+Because loading in the \f(CW\*(C`IO::Handle\*(C'\fR class is an expensive operation,
+you should learn how to use the regular built-in variables.
+.PP
+A few of these variables are considered "read-only".  This means that
+if you try to assign to this variable, either directly or indirectly
+through a reference, you'll raise a run-time exception.
+.PP
+You should be very careful when modifying the default values of most
+special variables described in this document.  In most cases you want
+to localize these variables before changing them, since if you don't,
+the change may affect other modules which rely on the default values
+of the special variables that you have changed.  This is one of the
+correct ways to read the whole file at once:
+.PP
+.Vb 4
+\&    open my $fh, "<", "foo" or die $!;
+\&    local $/; # enable localized slurp mode
+\&    my $content = <$fh>;
+\&    close $fh;
+.Ve
+.PP
+But the following code is quite bad:
+.PP
+.Vb 4
+\&    open my $fh, "<", "foo" or die $!;
+\&    undef $/; # enable slurp mode
+\&    my $content = <$fh>;
+\&    close $fh;
+.Ve
+.PP
+since some other module, may want to read data from some file in the
+default "line mode", so if the code we have just presented has been
+executed, the global value of \f(CW$/\fR is now changed for any other code
+running inside the same Perl interpreter.
+.PP
+Usually when a variable is localized you want to make sure that this
+change affects the shortest scope possible.  So unless you are already
+inside some short \f(CW\*(C`{}\*(C'\fR block, you should create one yourself.  For
+example:
+.PP
+.Vb 7
+\&    my $content = \*(Aq\*(Aq;
+\&    open my $fh, "<", "foo" or die $!;
+\&    {
+\&        local $/;
+\&        $content = <$fh>;
+\&    }
+\&    close $fh;
+.Ve
+.PP
+Here is an example of how your own code can go broken:
+.PP
+.Vb 5
+\&    for ( 1..3 ){
+\&        $\e = "\er\en";
+\&        nasty_break();
+\&        print "$_";
+\&    }
+\&
+\&    sub nasty_break {
+\&        $\e = "\ef";
+\&        # do something with $_
+\&    }
+.Ve
+.PP
+You probably expect this code to print the equivalent of
+.PP
+.Vb 1
+\&    "1\er\en2\er\en3\er\en"
+.Ve
+.PP
+but instead you get:
+.PP
+.Vb 1
+\&    "1\ef2\ef3\ef"
+.Ve
+.PP
+Why? Because \f(CWnasty_break()\fR modifies \f(CW\*(C`$\e\*(C'\fR without localizing it
+first.  The value you set in  \f(CWnasty_break()\fR is still there when you
+return.  The fix is to add \f(CWlocal()\fR so the value doesn't leak out of
+\&\f(CWnasty_break()\fR:
+.PP
+.Vb 1
+\&    local $\e = "\ef";
+.Ve
+.PP
+It's easy to notice the problem in such a short example, but in more
+complicated code you are looking for trouble if you don't localize
+changes to the special variables.
+.ie n .IP $ARGV 8
+.el .IP \f(CW$ARGV\fR 8
+.IX Xref "$ARGV"
+.IX Item "$ARGV"
+Contains the name of the current file when reading from \f(CW\*(C`<>\*(C'\fR.
+.ie n .IP @ARGV 8
+.el .IP \f(CW@ARGV\fR 8
+.IX Xref "@ARGV"
+.IX Item "@ARGV"
+The array \f(CW@ARGV\fR contains the command-line arguments intended for
+the script.  \f(CW$#ARGV\fR is generally the number of arguments minus
+one, because \f(CW$ARGV[0]\fR is the first argument, \fInot\fR the program's
+command name itself.  See "$0" for the command name.
+.IP ARGV 8
+.IX Xref "ARGV"
+.IX Item "ARGV"
+The special filehandle that iterates over command-line filenames in
+\&\f(CW@ARGV\fR.  Usually written as the null filehandle in the angle operator
+\&\f(CW\*(C`<>\*(C'\fR.  Note that currently \f(CW\*(C`ARGV\*(C'\fR only has its magical effect
+within the \f(CW\*(C`<>\*(C'\fR operator; elsewhere it is just a plain filehandle
+corresponding to the last file opened by \f(CW\*(C`<>\*(C'\fR.  In particular,
+passing \f(CW\*(C`\e*ARGV\*(C'\fR as a parameter to a function that expects a filehandle
+may not cause your function to automatically read the contents of all the
+files in \f(CW@ARGV\fR.
+.IP ARGVOUT 8
+.IX Xref "ARGVOUT"
+.IX Item "ARGVOUT"
+The special filehandle that points to the currently open output file
+when doing edit-in-place processing with \fB\-i\fR.  Useful when you have
+to do a lot of inserting and don't want to keep modifying \f(CW$_\fR.  See
+perlrun for the \fB\-i\fR switch.
+.IP "IO::Handle\->output_field_separator( EXPR )" 8
+.IX Item "IO::Handle->output_field_separator( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_FIELD_SEPARATOR 8
+.el .IP \f(CW$OUTPUT_FIELD_SEPARATOR\fR 8
+.IX Item "$OUTPUT_FIELD_SEPARATOR"
+.ie n .IP $OFS 8
+.el .IP \f(CW$OFS\fR 8
+.IX Item "$OFS"
+.IP $, 8
+.IX Xref "$, $OFS $OUTPUT_FIELD_SEPARATOR"
+.PD
+The output field separator for the print operator.  If defined, this
+value is printed between each of print's arguments.  Default is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+You cannot call \f(CWoutput_field_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+Mnemonic: what is printed when there is a "," in your print statement.
+.IP "HANDLE\->input_line_number( EXPR )" 8
+.IX Item "HANDLE->input_line_number( EXPR )"
+.PD 0
+.ie n .IP $INPUT_LINE_NUMBER 8
+.el .IP \f(CW$INPUT_LINE_NUMBER\fR 8
+.IX Item "$INPUT_LINE_NUMBER"
+.ie n .IP $NR 8
+.el .IP \f(CW$NR\fR 8
+.IX Item "$NR"
+.IP $. 8
+.IX Xref "$. $NR $INPUT_LINE_NUMBER line number"
+.PD
+Current line number for the last filehandle accessed.
+.Sp
+Each filehandle in Perl counts the number of lines that have been read
+from it.  (Depending on the value of \f(CW$/\fR, Perl's idea of what
+constitutes a line may not match yours.)  When a line is read from a
+filehandle (via \f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR), or when \f(CWtell()\fR or
+\&\f(CWseek()\fR is called on it, \f(CW$.\fR becomes an alias to the line counter
+for that filehandle.
+.Sp
+You can adjust the counter by assigning to \f(CW$.\fR, but this will not
+actually move the seek pointer.  \fILocalizing \fR\f(CI$.\fR\fI will not localize
+the filehandle's line count\fR.  Instead, it will localize perl's notion
+of which filehandle \f(CW$.\fR is currently aliased to.
+.Sp
+\&\f(CW$.\fR is reset when the filehandle is closed, but \fBnot\fR when an open
+filehandle is reopened without an intervening \f(CWclose()\fR.  For more
+details, see "I/O Operators" in perlop.  Because \f(CW\*(C`<>\*(C'\fR never does
+an explicit close, line numbers increase across \f(CW\*(C`ARGV\*(C'\fR files (but see
+examples in "eof" in perlfunc).
+.Sp
+You can also use \f(CW\*(C`HANDLE\->input_line_number(EXPR)\*(C'\fR to access the
+line counter for a given filehandle without having to worry about
+which handle you last accessed.
+.Sp
+Mnemonic: many programs use "." to mean the current line number.
+.IP "IO::Handle\->input_record_separator( EXPR )" 8
+.IX Item "IO::Handle->input_record_separator( EXPR )"
+.PD 0
+.ie n .IP $INPUT_RECORD_SEPARATOR 8
+.el .IP \f(CW$INPUT_RECORD_SEPARATOR\fR 8
+.IX Item "$INPUT_RECORD_SEPARATOR"
+.ie n .IP $RS 8
+.el .IP \f(CW$RS\fR 8
+.IX Item "$RS"
+.IP $/ 8
+.IX Xref "$ $RS $INPUT_RECORD_SEPARATOR"
+.PD
+The input record separator, newline by default.  This influences Perl's
+idea of what a "line" is.  Works like \fBawk\fR's RS variable, including
+treating empty lines as a terminator if set to the null string (an
+empty line cannot contain any spaces or tabs).  You may set it to a
+multi-character string to match a multi-character terminator, or to
+\&\f(CW\*(C`undef\*(C'\fR to read through the end of file.  Setting it to \f(CW"\en\en"\fR
+means something slightly different than setting to \f(CW""\fR, if the file
+contains consecutive empty lines.  Setting to \f(CW""\fR will treat two or
+more consecutive empty lines as a single empty line.  Setting to
+\&\f(CW"\en\en"\fR will blindly assume that the next input character belongs to
+the next paragraph, even if it's a newline.
+.Sp
+.Vb 3
+\&    local $/;           # enable "slurp" mode
+\&    local $_ = <FH>;    # whole file now here
+\&    s/\en[ \et]+/ /g;
+.Ve
+.Sp
+Remember: the value of \f(CW$/\fR is a string, not a regex.  \fBawk\fR has to
+be better for something. :\-)
+.Sp
+Setting \f(CW$/\fR to an empty string \-\- the so-called \fIparagraph mode\fR \-\- merits
+special attention.  When \f(CW$/\fR is set to \f(CW""\fR and the entire file is read in
+with that setting, any sequence of one or more consecutive newlines at the
+beginning of the file is discarded.  With the exception of the final record in
+the file, each sequence of characters ending in two or more newlines is
+treated as one record and is read in to end in exactly two newlines.  If the
+last record in the file ends in zero or one consecutive newlines, that record
+is read in with that number of newlines.  If the last record ends in two or
+more consecutive newlines, it is read in with two newlines like all preceding
+records.
+.Sp
+Suppose we wrote the following string to a file:
+.Sp
+.Vb 4
+\&    my $string = "\en\en\en";
+\&    $string .= "alpha beta\engamma delta\en\en\en";
+\&    $string .= "epsilon zeta eta\en\en";
+\&    $string .= "theta\en";
+\&
+\&    my $file = \*(Aqsimple_file.txt\*(Aq;
+\&    open my $OUT, \*(Aq>\*(Aq, $file or die;
+\&    print $OUT $string;
+\&    close $OUT or die;
+.Ve
+.Sp
+Now we read that file in paragraph mode:
+.Sp
+.Vb 4
+\&    local $/ = ""; # paragraph mode
+\&    open my $IN, \*(Aq<\*(Aq, $file or die;
+\&    my @records = <$IN>;
+\&    close $IN or die;
+.Ve
+.Sp
+\&\f(CW@records\fR will consist of these 3 strings:
+.Sp
+.Vb 5
+\&    (
+\&      "alpha beta\engamma delta\en\en",
+\&      "epsilon zeta eta\en\en",
+\&      "theta\en",
+\&    )
+.Ve
+.Sp
+Setting \f(CW$/\fR to a reference to an integer, scalar containing an
+integer, or scalar that's convertible to an integer will attempt to
+read records instead of lines, with the maximum record size being the
+referenced integer number of characters.  So this:
+.Sp
+.Vb 3
+\&    local $/ = \e32768; # or \e"32768", or \e$var_containing_32768
+\&    open my $fh, "<", $myfile or die $!;
+\&    local $_ = <$fh>;
+.Ve
+.Sp
+will read a record of no more than 32768 characters from \f(CW$fh\fR.  If you're
+not reading from a record-oriented file (or your OS doesn't have
+record-oriented files), then you'll likely get a full chunk of data
+with every read.  If a record is larger than the record size you've
+set, you'll get the record back in pieces.  Trying to set the record
+size to zero or less is deprecated and will cause $/ to have the value
+of "undef", which will cause reading in the (rest of the) whole file.
+.Sp
+As of 5.19.9 setting \f(CW$/\fR to any other form of reference will throw a
+fatal exception. This is in preparation for supporting new ways to set
+\&\f(CW$/\fR in the future.
+.Sp
+On VMS only, record reads bypass PerlIO layers and any associated
+buffering, so you must not mix record and non-record reads on the
+same filehandle.  Record mode mixes with line mode only when the
+same buffering layer is in use for both modes.
+.Sp
+You cannot call \f(CWinput_record_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+See also "Newlines" in perlport.  Also see "$.".
+.Sp
+Mnemonic: / delimits line boundaries when quoting poetry.
+.IP "IO::Handle\->output_record_separator( EXPR )" 8
+.IX Item "IO::Handle->output_record_separator( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_RECORD_SEPARATOR 8
+.el .IP \f(CW$OUTPUT_RECORD_SEPARATOR\fR 8
+.IX Item "$OUTPUT_RECORD_SEPARATOR"
+.ie n .IP $ORS 8
+.el .IP \f(CW$ORS\fR 8
+.IX Item "$ORS"
+.IP $\e 8
+.IX Xref "$\\ $ORS $OUTPUT_RECORD_SEPARATOR"
+.IX Item "$"
+.PD
+The output record separator for the print operator.  If defined, this
+value is printed after the last of print's arguments.  Default is \f(CW\*(C`undef\*(C'\fR.
+.Sp
+You cannot call \f(CWoutput_record_separator()\fR on a handle, only as a
+static method.  See IO::Handle.
+.Sp
+Mnemonic: you set \f(CW\*(C`$\e\*(C'\fR instead of adding "\en" at the end of the print.
+Also, it's just like \f(CW$/\fR, but it's what you get "back" from Perl.
+.IP "HANDLE\->autoflush( EXPR )" 8
+.IX Item "HANDLE->autoflush( EXPR )"
+.PD 0
+.ie n .IP $OUTPUT_AUTOFLUSH 8
+.el .IP \f(CW$OUTPUT_AUTOFLUSH\fR 8
+.IX Item "$OUTPUT_AUTOFLUSH"
+.IP $| 8
+.IX Xref "$| autoflush flush $OUTPUT_AUTOFLUSH"
+.PD
+If set to nonzero, forces a flush right away and after every write or
+print on the currently selected output channel.  Default is 0
+(regardless of whether the channel is really buffered by the system or
+not; \f(CW$|\fR tells you only whether you've asked Perl explicitly to
+flush after each write).  STDOUT will typically be line buffered if
+output is to the terminal and block buffered otherwise.  Setting this
+variable is useful primarily when you are outputting to a pipe or
+socket, such as when you are running a Perl program under \fBrsh\fR and
+want to see the output as it's happening.  This has no effect on input
+buffering.  See "getc" in perlfunc for that.  See "select" in perlfunc on
+how to select the output channel.  See also IO::Handle.
+.Sp
+Mnemonic: when you want your pipes to be piping hot.
+.IP ${^LAST_FH} 8
+.IX Xref "${^LAST_FH}"
+.IX Item "${^LAST_FH}"
+This read-only variable contains a reference to the last-read filehandle.
+This is set by \f(CW\*(C`<HANDLE>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`eof\*(C'\fR and \f(CW\*(C`seek\*(C'\fR.
+This is the same handle that \f(CW$.\fR and \f(CW\*(C`tell\*(C'\fR and \f(CW\*(C`eof\*(C'\fR without arguments
+use.  It is also the handle used when Perl appends ", <STDIN> line 1" to
+an error or warning message.
+.Sp
+This variable was added in Perl v5.18.0.
+.PP
+\fIVariables related to formats\fR
+.IX Subsection "Variables related to formats"
+.PP
+The special variables for formats are a subset of those for
+filehandles.  See perlform for more information about Perl's
+formats.
+.ie n .IP $ACCUMULATOR 8
+.el .IP \f(CW$ACCUMULATOR\fR 8
+.IX Item "$ACCUMULATOR"
+.PD 0
+.IP $^A 8
+.IX Xref "$^A $ACCUMULATOR"
+.IX Item "$^A"
+.PD
+The current value of the \f(CWwrite()\fR accumulator for \f(CWformat()\fR lines.
+A format contains \f(CWformline()\fR calls that put their result into
+\&\f(CW$^A\fR.  After calling its format, \f(CWwrite()\fR prints out the contents
+of \f(CW$^A\fR and empties.  So you never really see the contents of \f(CW$^A\fR
+unless you call \f(CWformline()\fR yourself and then look at it.  See
+perlform and "formline PICTURE,LIST" in perlfunc.
+.IP IO::Handle\->format_formfeed(EXPR) 8
+.IX Item "IO::Handle->format_formfeed(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_FORMFEED 8
+.el .IP \f(CW$FORMAT_FORMFEED\fR 8
+.IX Item "$FORMAT_FORMFEED"
+.IP $^L 8
+.IX Xref "$^L $FORMAT_FORMFEED"
+.IX Item "$^L"
+.PD
+What formats output as a form feed.  The default is \f(CW\*(C`\ef\*(C'\fR.
+.Sp
+You cannot call \f(CWformat_formfeed()\fR on a handle, only as a static
+method.  See IO::Handle.
+.IP HANDLE\->format_page_number(EXPR) 8
+.IX Item "HANDLE->format_page_number(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_PAGE_NUMBER 8
+.el .IP \f(CW$FORMAT_PAGE_NUMBER\fR 8
+.IX Item "$FORMAT_PAGE_NUMBER"
+.IP $% 8
+.IX Xref "$% $FORMAT_PAGE_NUMBER"
+.PD
+The current page number of the currently selected output channel.
+.Sp
+Mnemonic: \f(CW\*(C`%\*(C'\fR is page number in \fBnroff\fR.
+.IP HANDLE\->format_lines_left(EXPR) 8
+.IX Item "HANDLE->format_lines_left(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_LINES_LEFT 8
+.el .IP \f(CW$FORMAT_LINES_LEFT\fR 8
+.IX Item "$FORMAT_LINES_LEFT"
+.IP $\- 8
+.IX Xref "$- $FORMAT_LINES_LEFT"
+.PD
+The number of lines left on the page of the currently selected output
+channel.
+.Sp
+Mnemonic: lines_on_page \- lines_printed.
+.IP "IO::Handle\->format_line_break_characters EXPR" 8
+.IX Item "IO::Handle->format_line_break_characters EXPR"
+.PD 0
+.ie n .IP $FORMAT_LINE_BREAK_CHARACTERS 8
+.el .IP \f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR 8
+.IX Item "$FORMAT_LINE_BREAK_CHARACTERS"
+.ie n .IP $: 8
+.el .IP \f(CW$:\fR 8
+.IX Xref "$: FORMAT_LINE_BREAK_CHARACTERS"
+.IX Item "$:"
+.PD
+The current set of characters after which a string may be broken to
+fill continuation fields (starting with \f(CW\*(C`^\*(C'\fR) in a format.  The default is
+"\ \en\-", to break on a space, newline, or a hyphen.
+.Sp
+You cannot call \f(CWformat_line_break_characters()\fR on a handle, only as
+a static method.  See IO::Handle.
+.Sp
+Mnemonic: a "colon" in poetry is a part of a line.
+.IP HANDLE\->format_lines_per_page(EXPR) 8
+.IX Item "HANDLE->format_lines_per_page(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_LINES_PER_PAGE 8
+.el .IP \f(CW$FORMAT_LINES_PER_PAGE\fR 8
+.IX Item "$FORMAT_LINES_PER_PAGE"
+.IP $= 8
+.IX Xref "$= $FORMAT_LINES_PER_PAGE"
+.PD
+The current page length (printable lines) of the currently selected
+output channel.  The default is 60.
+.Sp
+Mnemonic: = has horizontal lines.
+.IP HANDLE\->format_top_name(EXPR) 8
+.IX Item "HANDLE->format_top_name(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_TOP_NAME 8
+.el .IP \f(CW$FORMAT_TOP_NAME\fR 8
+.IX Item "$FORMAT_TOP_NAME"
+.IP $^ 8
+.IX Xref "$^ $FORMAT_TOP_NAME"
+.PD
+The name of the current top-of-page format for the currently selected
+output channel.  The default is the name of the filehandle with \f(CW\*(C`_TOP\*(C'\fR
+appended.  For example, the default format top name for the \f(CW\*(C`STDOUT\*(C'\fR
+filehandle is \f(CW\*(C`STDOUT_TOP\*(C'\fR.
+.Sp
+Mnemonic: points to top of page.
+.IP HANDLE\->format_name(EXPR) 8
+.IX Item "HANDLE->format_name(EXPR)"
+.PD 0
+.ie n .IP $FORMAT_NAME 8
+.el .IP \f(CW$FORMAT_NAME\fR 8
+.IX Item "$FORMAT_NAME"
+.IP $~ 8
+.IX Xref "$~ $FORMAT_NAME"
+.PD
+The name of the current report format for the currently selected
+output channel.  The default format name is the same as the filehandle
+name.  For example, the default format name for the \f(CW\*(C`STDOUT\*(C'\fR
+filehandle is just \f(CW\*(C`STDOUT\*(C'\fR.
+.Sp
+Mnemonic: brother to \f(CW$^\fR.
+.SS "Error Variables"
+.IX Xref "error exception"
+.IX Subsection "Error Variables"
+The variables \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, and \f(CW$?\fR contain information
+about different types of error conditions that may appear during
+execution of a Perl program.  The variables are shown ordered by
+the "distance" between the subsystem which reported the error and
+the Perl process.  They correspond to errors detected by the Perl
+interpreter, C library, operating system, or an external program,
+respectively.
+.PP
+To illustrate the differences between these variables, consider the
+following Perl expression, which uses a single-quoted string.  After
+execution of this statement, perl may have set all four special error
+variables:
+.PP
+.Vb 5
+\&    eval q{
+\&        open my $pipe, "/cdrom/install |" or die $!;
+\&        my @res = <$pipe>;
+\&        close $pipe or die "bad pipe: $?, $!";
+\&    };
+.Ve
+.PP
+When perl executes the \f(CWeval()\fR expression, it translates the
+\&\f(CWopen()\fR, \f(CW\*(C`<PIPE>\*(C'\fR, and \f(CW\*(C`close\*(C'\fR calls in the C run-time library
+and thence to the operating system kernel.  perl sets \f(CW$!\fR to
+the C library's \f(CW\*(C`errno\*(C'\fR if one of these calls fails.
+.PP
+\&\f(CW$@\fR is set if the string to be \f(CW\*(C`eval\*(C'\fR\-ed did not compile (this may
+happen if \f(CW\*(C`open\*(C'\fR or \f(CW\*(C`close\*(C'\fR were imported with bad prototypes), or
+if Perl code executed during evaluation \f(CWdie()\fRd.  In these cases the
+value of \f(CW$@\fR is the compile error, or the argument to \f(CW\*(C`die\*(C'\fR (which
+will interpolate \f(CW$!\fR and \f(CW$?\fR).  (See also Fatal, though.)
+.PP
+Under a few operating systems, \f(CW$^E\fR may contain a more verbose error
+indicator, such as in this case, "CDROM tray not closed."  Systems that
+do not support extended error messages leave \f(CW$^E\fR the same as \f(CW$!\fR.
+.PP
+Finally, \f(CW$?\fR may be set to a non\-0 value if the external program
+\&\fI/cdrom/install\fR fails.  The upper eight bits reflect specific error
+conditions encountered by the program (the program's \f(CWexit()\fR value).
+The lower eight bits reflect mode of failure, like signal death and
+core dump information.  See \fBwait\fR\|(2) for details.  In contrast to
+\&\f(CW$!\fR and \f(CW$^E\fR, which are set only if an error condition is detected,
+the variable \f(CW$?\fR is set on each \f(CW\*(C`wait\*(C'\fR or pipe \f(CW\*(C`close\*(C'\fR,
+overwriting the old value.  This is more like \f(CW$@\fR, which on every
+\&\f(CWeval()\fR is always set on failure and cleared on success.
+.PP
+For more details, see the individual descriptions at \f(CW$@\fR, \f(CW$!\fR,
+\&\f(CW$^E\fR, and \f(CW$?\fR.
+.IP ${^CHILD_ERROR_NATIVE} 8
+.IX Xref "$^CHILD_ERROR_NATIVE"
+.IX Item "${^CHILD_ERROR_NATIVE}"
+The native status returned by the last pipe close, backtick (\f(CW\`\`\fR)
+command, successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the
+\&\f(CWsystem()\fR operator.  On POSIX-like systems this value can be decoded
+with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and
+WSTOPSIG functions provided by the POSIX module.
+.Sp
+Under VMS this reflects the actual VMS exit status; i.e. it is the
+same as \f(CW$?\fR when the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in effect.
+.Sp
+This variable was added in Perl v5.10.0.
+.ie n .IP $EXTENDED_OS_ERROR 8
+.el .IP \f(CW$EXTENDED_OS_ERROR\fR 8
+.IX Item "$EXTENDED_OS_ERROR"
+.PD 0
+.IP $^E 8
+.IX Xref "$^E $EXTENDED_OS_ERROR"
+.IX Item "$^E"
+.PD
+Error information specific to the current operating system.  At the
+moment, this differs from \f(CW"$!"\fR under only VMS, OS/2, and Win32 (and
+for MacPerl).  On all other platforms, \f(CW$^E\fR is always just the same
+as \f(CW$!\fR.
+.Sp
+Under VMS, \f(CW$^E\fR provides the VMS status value from the last system
+error.  This is more specific information about the last system error
+than that provided by \f(CW$!\fR.  This is particularly important when \f(CW$!\fR
+is set to \fBEVMSERR\fR.
+.Sp
+Under OS/2, \f(CW$^E\fR is set to the error code of the last call to OS/2
+API either via CRT, or directly from perl.
+.Sp
+Under Win32, \f(CW$^E\fR always returns the last error information reported
+by the Win32 call \f(CWGetLastError()\fR which describes the last error
+from within the Win32 API.  Most Win32\-specific code will report errors
+via \f(CW$^E\fR.  ANSI C and Unix-like calls set \f(CW\*(C`errno\*(C'\fR and so most
+portable Perl code will report errors via \f(CW$!\fR.
+.Sp
+Caveats mentioned in the description of \f(CW"$!"\fR generally apply to
+\&\f(CW$^E\fR, also.
+.Sp
+This variable was added in Perl 5.003.
+.Sp
+Mnemonic: Extra error explanation.
+.ie n .IP $EXCEPTIONS_BEING_CAUGHT 8
+.el .IP \f(CW$EXCEPTIONS_BEING_CAUGHT\fR 8
+.IX Item "$EXCEPTIONS_BEING_CAUGHT"
+.PD 0
+.IP $^S 8
+.IX Xref "$^S $EXCEPTIONS_BEING_CAUGHT"
+.IX Item "$^S"
+.PD
+Current state of the interpreter.
+.Sp
+.Vb 5
+\&    $^S         State
+\&    \-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    undef       Parsing module, eval, or main program
+\&    true (1)    Executing an eval or try block
+\&    false (0)   Otherwise
+.Ve
+.Sp
+The first state may happen in \f(CW$SIG{_\|_DIE_\|_}\fR and \f(CW$SIG{_\|_WARN_\|_}\fR
+handlers.
+.Sp
+The English name \f(CW$EXCEPTIONS_BEING_CAUGHT\fR is slightly misleading, because
+the \f(CW\*(C`undef\*(C'\fR value does not indicate whether exceptions are being caught,
+since compilation of the main program does not catch exceptions.
+.Sp
+This variable was added in Perl 5.004.
+.ie n .IP $WARNING 8
+.el .IP \f(CW$WARNING\fR 8
+.IX Item "$WARNING"
+.PD 0
+.IP $^W 8
+.IX Xref "$^W $WARNING"
+.IX Item "$^W"
+.PD
+The current value of the warning switch, initially true if \fB\-w\fR was
+used, false otherwise, but directly modifiable.
+.Sp
+See also warnings.
+.Sp
+Mnemonic: related to the \fB\-w\fR switch.
+.IP ${^WARNING_BITS} 8
+.IX Xref "${^WARNING_BITS}"
+.IX Item "${^WARNING_BITS}"
+The current set of warning checks enabled by the \f(CW\*(C`use warnings\*(C'\fR pragma.
+It has the same scoping as the \f(CW$^H\fR and \f(CW\*(C`%^H\*(C'\fR variables.  The exact
+values are considered internal to the warnings pragma and may change
+between versions of Perl.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW\*(C`${^WARNING_BITS}\*(C'\fR is stored with that statement, and can later be
+retrieved via \f(CW\*(C`(caller($level))[9]\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.ie n .IP $OS_ERROR 8
+.el .IP \f(CW$OS_ERROR\fR 8
+.IX Item "$OS_ERROR"
+.PD 0
+.ie n .IP $ERRNO 8
+.el .IP \f(CW$ERRNO\fR 8
+.IX Item "$ERRNO"
+.IP $! 8
+.IX Xref "$! $ERRNO $OS_ERROR"
+.PD
+When referenced, \f(CW$!\fR retrieves the current value
+of the C \f(CW\*(C`errno\*(C'\fR integer variable.
+If \f(CW$!\fR is assigned a numerical value, that value is stored in \f(CW\*(C`errno\*(C'\fR.
+When referenced as a string, \f(CW$!\fR yields the system error string
+corresponding to \f(CW\*(C`errno\*(C'\fR.
+.Sp
+Many system or library calls set \f(CW\*(C`errno\*(C'\fR if they fail,
+to indicate the cause of failure.  They usually do \fBnot\fR
+set \f(CW\*(C`errno\*(C'\fR to zero if they succeed and may set \f(CW\*(C`errno\*(C'\fR to a
+non-zero value on success.  This means \f(CW\*(C`errno\*(C'\fR, hence \f(CW$!\fR, is
+meaningful only \fIimmediately\fR after a \fBfailure\fR:
+.Sp
+.Vb 11
+\&    if (open my $fh, "<", $filename) {
+\&        # Here $! is meaningless.
+\&        ...
+\&    }
+\&    else {
+\&        # ONLY here is $! meaningful.
+\&        ...
+\&        # Already here $! might be meaningless.
+\&    }
+\&    # Since here we might have either success or failure,
+\&    # $! is meaningless.
+.Ve
+.Sp
+Here, \fImeaningless\fR means that \f(CW$!\fR may be unrelated to the outcome
+of the \f(CWopen()\fR operator.  Assignment to \f(CW$!\fR is similarly ephemeral.
+It can be used immediately before invoking the \f(CWdie()\fR operator,
+to set the exit value, or to inspect the system error string
+corresponding to error \fIn\fR, or to restore \f(CW$!\fR to a meaningful state.
+.Sp
+Perl itself may set \f(CW\*(C`errno\*(C'\fR to a non-zero on failure even if no
+system call is performed.
+.Sp
+Mnemonic: What just went bang?
+.ie n .IP %OS_ERROR 8
+.el .IP \f(CW%OS_ERROR\fR 8
+.IX Item "%OS_ERROR"
+.PD 0
+.ie n .IP %ERRNO 8
+.el .IP \f(CW%ERRNO\fR 8
+.IX Item "%ERRNO"
+.IP %! 8
+.IX Xref "%! %OS_ERROR %ERRNO"
+.PD
+Each element of \f(CW\*(C`%!\*(C'\fR has a true value only if \f(CW$!\fR is set to that
+value.  For example, \f(CW$!{ENOENT}\fR is true if and only if the current
+value of \f(CW$!\fR is \f(CW\*(C`ENOENT\*(C'\fR; that is, if the most recent error was "No
+such file or directory" (or its moral equivalent: not all operating
+systems give that exact error, and certainly not all languages).  The
+specific true value is not guaranteed, but in the past has generally
+been the numeric value of \f(CW$!\fR.  To check if a particular key is
+meaningful on your system, use \f(CW\*(C`exists $!{the_key}\*(C'\fR; for a list of legal
+keys, use \f(CW\*(C`keys %!\*(C'\fR.  See Errno for more information, and also see
+"$!".
+.Sp
+This variable was added in Perl 5.005.
+.ie n .IP $CHILD_ERROR 8
+.el .IP \f(CW$CHILD_ERROR\fR 8
+.IX Item "$CHILD_ERROR"
+.PD 0
+.IP $? 8
+.IX Xref "$? $CHILD_ERROR"
+.PD
+The status returned by the last pipe close, backtick (\f(CW\`\`\fR) command,
+successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the \f(CWsystem()\fR
+operator.  This is just the 16\-bit status word returned by the
+traditional Unix \f(CWwait()\fR system call (or else is made up to look
+like it).  Thus, the exit value of the subprocess is really (\f(CW$? >>
+8\fR), and \f(CW\*(C`$? & 127\*(C'\fR gives which signal, if any, the process died
+from, and \f(CW\*(C`$? & 128\*(C'\fR reports whether there was a core dump.
+.Sp
+Additionally, if the \f(CW\*(C`h_errno\*(C'\fR variable is supported in C, its value
+is returned via \f(CW$?\fR if any \f(CW\*(C`gethost*()\*(C'\fR function fails.
+.Sp
+If you have installed a signal handler for \f(CW\*(C`SIGCHLD\*(C'\fR, the
+value of \f(CW$?\fR will usually be wrong outside that handler.
+.Sp
+Inside an \f(CW\*(C`END\*(C'\fR subroutine \f(CW$?\fR contains the value that is going to be
+given to \f(CWexit()\fR.  You can modify \f(CW$?\fR in an \f(CW\*(C`END\*(C'\fR subroutine to
+change the exit status of your program.  For example:
+.Sp
+.Vb 3
+\&    END {
+\&        $? = 1 if $? == 255;  # die would make it 255
+\&    }
+.Ve
+.Sp
+Under VMS, the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the
+actual VMS exit status, instead of the default emulation of POSIX
+status; see "$?" in perlvms for details.
+.Sp
+Mnemonic: similar to \fBsh\fR and \fBksh\fR.
+.ie n .IP $EVAL_ERROR 8
+.el .IP \f(CW$EVAL_ERROR\fR 8
+.IX Item "$EVAL_ERROR"
+.PD 0
+.IP $@ 8
+.IX Xref "$@ $EVAL_ERROR"
+.PD
+The Perl error from the last \f(CW\*(C`eval\*(C'\fR operator, i.e. the last exception that
+was caught.  For \f(CW\*(C`eval BLOCK\*(C'\fR, this is either a runtime error message or the
+string or reference \f(CW\*(C`die\*(C'\fR was called with.  The \f(CW\*(C`eval STRING\*(C'\fR form also
+catches syntax errors and other compile time exceptions.
+.Sp
+If no error occurs, \f(CW\*(C`eval\*(C'\fR sets \f(CW$@\fR to the empty string.
+.Sp
+Warning messages are not collected in this variable.  You can, however,
+set up a routine to process warnings by setting \f(CW$SIG{_\|_WARN_\|_}\fR as
+described in "%SIG".
+.Sp
+Mnemonic: Where was the error "at"?
+.SS "Variables related to the interpreter state"
+.IX Subsection "Variables related to the interpreter state"
+These variables provide information about the current interpreter state.
+.ie n .IP $COMPILING 8
+.el .IP \f(CW$COMPILING\fR 8
+.IX Item "$COMPILING"
+.PD 0
+.IP $^C 8
+.IX Xref "$^C $COMPILING"
+.IX Item "$^C"
+.PD
+The current value of the flag associated with the \fB\-c\fR switch.
+Mainly of use with \fB\-MO=...\fR to allow code to alter its behavior
+when being compiled, such as for example to \f(CW\*(C`AUTOLOAD\*(C'\fR at compile
+time rather than normal, deferred loading.  Setting
+\&\f(CW\*(C`$^C = 1\*(C'\fR is similar to calling \f(CW\*(C`B::minus_c\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.ie n .IP $DEBUGGING 8
+.el .IP \f(CW$DEBUGGING\fR 8
+.IX Item "$DEBUGGING"
+.PD 0
+.IP $^D 8
+.IX Xref "$^D $DEBUGGING"
+.IX Item "$^D"
+.PD
+The current value of the debugging flags.  May be read or set.  Like its
+command-line equivalent, you can use numeric
+or symbolic values, e.g. \f(CW\*(C`$^D = 10\*(C'\fR or \f(CW\*(C`$^D = "st"\*(C'\fR.  See
+"\fB\-D\fR\fInumber\fR" in perlrun.  The contents of this variable also affects the
+debugger operation.  See "Debugger Internals" in perldebguts.
+.Sp
+Mnemonic: value of \fB\-D\fR switch.
+.IP ${^GLOBAL_PHASE} 8
+.IX Xref "${^GLOBAL_PHASE}"
+.IX Item "${^GLOBAL_PHASE}"
+The current phase of the perl interpreter.
+.Sp
+Possible values are:
+.RS 8
+.IP CONSTRUCT 8
+.IX Item "CONSTRUCT"
+The \f(CW\*(C`PerlInterpreter*\*(C'\fR is being constructed via \f(CW\*(C`perl_construct\*(C'\fR.  This
+value is mostly there for completeness and for use via the
+underlying C variable \f(CW\*(C`PL_phase\*(C'\fR.  It's not really possible for Perl
+code to be executed unless construction of the interpreter is
+finished.
+.IP START 8
+.IX Item "START"
+This is the global compile-time.  That includes, basically, every
+\&\f(CW\*(C`BEGIN\*(C'\fR block executed directly or indirectly from during the
+compile-time of the top-level program.
+.Sp
+This phase is not called "BEGIN" to avoid confusion with
+\&\f(CW\*(C`BEGIN\*(C'\fR\-blocks, as those are executed during compile-time of any
+compilation unit, not just the top-level program.  A new, localised
+compile-time entered at run-time, for example by constructs as
+\&\f(CW\*(C`eval "use SomeModule"\*(C'\fR are not global interpreter phases, and
+therefore aren't reflected by \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR.
+.IP CHECK 8
+.IX Item "CHECK"
+Execution of any \f(CW\*(C`CHECK\*(C'\fR blocks.
+.IP INIT 8
+.IX Item "INIT"
+Similar to "CHECK", but for \f(CW\*(C`INIT\*(C'\fR\-blocks, not \f(CW\*(C`CHECK\*(C'\fR blocks.
+.IP RUN 8
+.IX Item "RUN"
+The main run-time, i.e. the execution of \f(CW\*(C`PL_main_root\*(C'\fR.
+.IP END 8
+.IX Item "END"
+Execution of any \f(CW\*(C`END\*(C'\fR blocks.
+.IP DESTRUCT 8
+.IX Item "DESTRUCT"
+Global destruction.
+.RE
+.RS 8
+.Sp
+Also note that there's no value for UNITCHECK-blocks.  That's because
+those are run for each compilation unit individually, and therefore is
+not a global interpreter phase.
+.Sp
+Not every program has to go through each of the possible phases, but
+transition from one phase to another can only happen in the order
+described in the above list.
+.Sp
+An example of all of the phases Perl code can see:
+.Sp
+.Vb 1
+\&    BEGIN { print "compile\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    INIT  { print "init\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    CHECK { print "check\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    {
+\&        package Print::Phase;
+\&
+\&        sub new {
+\&            my ($class, $time) = @_;
+\&            return bless \e$time, $class;
+\&        }
+\&
+\&        sub DESTROY {
+\&            my $self = shift;
+\&            print "$$self: ${^GLOBAL_PHASE}\en";
+\&        }
+\&    }
+\&
+\&    print "run\-time: ${^GLOBAL_PHASE}\en";
+\&
+\&    my $runtime = Print::Phase\->new(
+\&        "lexical variables are garbage collected before END"
+\&    );
+\&
+\&    END   { print "end\-time: ${^GLOBAL_PHASE}\en" }
+\&
+\&    our $destruct = Print::Phase\->new(
+\&        "package variables are garbage collected after END"
+\&    );
+.Ve
+.Sp
+This will print out
+.Sp
+.Vb 7
+\&    compile\-time: START
+\&    check\-time: CHECK
+\&    init\-time: INIT
+\&    run\-time: RUN
+\&    lexical variables are garbage collected before END: RUN
+\&    end\-time: END
+\&    package variables are garbage collected after END: DESTRUCT
+.Ve
+.Sp
+This variable was added in Perl 5.14.0.
+.RE
+.IP $^H 8
+.IX Xref "$^H"
+.IX Item "$^H"
+WARNING: This variable is strictly for
+internal use only.  Its availability,
+behavior, and contents are subject to change without notice.
+.Sp
+This variable contains compile-time hints for the Perl interpreter.  At the
+end of compilation of a BLOCK the value of this variable is restored to the
+value when the interpreter started to compile the BLOCK.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW$^H\fR is stored with that statement, and can later be retrieved via
+\&\f(CW\*(C`(caller($level))[8]\*(C'\fR.  See "caller EXPR" in perlfunc.
+.Sp
+When perl begins to parse any block construct that provides a lexical scope
+(e.g., eval body, required file, subroutine body, loop body, or conditional
+block), the existing value of \f(CW$^H\fR is saved, but its value is left unchanged.
+When the compilation of the block is completed, it regains the saved value.
+Between the points where its value is saved and restored, code that
+executes within BEGIN blocks is free to change the value of \f(CW$^H\fR.
+.Sp
+This behavior provides the semantic of lexical scoping, and is used in,
+for instance, the \f(CW\*(C`use strict\*(C'\fR pragma.
+.Sp
+The contents should be an integer; different bits of it are used for
+different pragmatic flags.  Here's an example:
+.Sp
+.Vb 1
+\&    sub add_100 { $^H |= 0x100 }
+\&
+\&    sub foo {
+\&        BEGIN { add_100() }
+\&        bar\->baz($boon);
+\&    }
+.Ve
+.Sp
+Consider what happens during execution of the BEGIN block.  At this point
+the BEGIN block has already been compiled, but the body of \f(CWfoo()\fR is still
+being compiled.  The new value of \f(CW$^H\fR
+will therefore be visible only while
+the body of \f(CWfoo()\fR is being compiled.
+.Sp
+Substitution of \f(CW\*(C`BEGIN { add_100() }\*(C'\fR block with:
+.Sp
+.Vb 1
+\&    BEGIN { require strict; strict\->import(\*(Aqvars\*(Aq) }
+.Ve
+.Sp
+demonstrates how \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR is implemented.  Here's a conditional
+version of the same lexical pragma:
+.Sp
+.Vb 3
+\&    BEGIN {
+\&        require strict; strict\->import(\*(Aqvars\*(Aq) if $condition
+\&    }
+.Ve
+.Sp
+This variable was added in Perl 5.003.
+.IP %^H 8
+.IX Xref "%^H"
+.IX Item "%^H"
+The \f(CW\*(C`%^H\*(C'\fR hash provides the same scoping semantics as \f(CW$^H\fR.  This
+makes it useful for implementing lexically scoped pragmas.  See perlpragma.
+All the entries are stringified when accessed at runtime, so only simple values
+can be accommodated.  This means no references to objects, for example.
+.Sp
+Each time a statement completes being compiled, the current value of
+\&\f(CW\*(C`%^H\*(C'\fR is stored with that statement, and can later be retrieved via
+\&\f(CW\*(C`(caller($level))[10]\*(C'\fR.  See "caller EXPR" in perlfunc.
+.Sp
+When putting items into \f(CW\*(C`%^H\*(C'\fR, in order to avoid conflicting with other
+users of the hash there is a convention regarding which keys to use.
+A module should use only keys that begin with the module's name (the
+name of its main package) and a "/" character.  For example, a module
+\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR.
+.Sp
+This variable was added in Perl v5.6.0.
+.IP ${^OPEN} 8
+.IX Xref "${^OPEN}"
+.IX Item "${^OPEN}"
+An internal variable used by PerlIO.  A string in two parts, separated
+by a \f(CW\*(C`\e0\*(C'\fR byte, the first part describes the input layers, the second
+part describes the output layers.
+.Sp
+This is the mechanism that applies the lexical effects of the open
+pragma, and the main program scope effects of the \f(CW\*(C`io\*(C'\fR or \f(CW\*(C`D\*(C'\fR options
+for the \-C command-line switch and
+PERL_UNICODE environment variable.
+.Sp
+The functions \f(CWaccept()\fR, \f(CWopen()\fR, \f(CWpipe()\fR, \f(CWreadpipe()\fR (as well
+as the related \f(CW\*(C`qx\*(C'\fR and \f(CW\`STRING\`\fR operators), \f(CWsocket()\fR,
+\&\f(CWsocketpair()\fR, and \f(CWsysopen()\fR are affected by the lexical value of
+this variable.  The implicit "ARGV" handle opened by \f(CWreadline()\fR (or
+the related \f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`<<>>\*(C'\fR operators) on passed filenames is
+also affected (but not if it opens \f(CW\*(C`STDIN\*(C'\fR).  If this variable is not
+set, these functions will set the default layers as described in
+"Defaults and how to override them" in PerlIO.
+.Sp
+\&\f(CWopen()\fR ignores this variable (and the default layers) when called with
+3 arguments and explicit layers are specified.  Indirect calls to these
+functions via modules like IO::Handle are not affected as they occur
+in a different lexical scope.  Directory handles such as opened by
+\&\f(CWopendir()\fR are not currently affected.
+.Sp
+This variable was added in Perl v5.8.0.
+.ie n .IP $PERLDB 8
+.el .IP \f(CW$PERLDB\fR 8
+.IX Item "$PERLDB"
+.PD 0
+.IP $^P 8
+.IX Xref "$^P $PERLDB"
+.IX Item "$^P"
+.PD
+The internal variable for debugging support.  The meanings of the
+various bits are subject to change, but currently indicate:
+.RS 8
+.IP 0x01 6
+.IX Item "0x01"
+Debug subroutine enter/exit.
+.IP 0x02 6
+.IX Item "0x02"
+Line-by-line debugging.  Causes \f(CWDB::DB()\fR subroutine to be called for
+each statement executed.  Also causes saving source code lines (like
+0x400).
+.IP 0x04 6
+.IX Item "0x04"
+Switch off optimizations.
+.IP 0x08 6
+.IX Item "0x08"
+Preserve more data for future interactive inspections.
+.IP 0x10 6
+.IX Item "0x10"
+Keep info about source lines on which a subroutine is defined.
+.IP 0x20 6
+.IX Item "0x20"
+Start with single-step on.
+.IP 0x40 6
+.IX Item "0x40"
+Use subroutine address instead of name when reporting.
+.IP 0x80 6
+.IX Item "0x80"
+Report \f(CW\*(C`goto &subroutine\*(C'\fR as well.
+.IP 0x100 6
+.IX Item "0x100"
+Provide informative "file" names for evals based on the place they were compiled.
+.IP 0x200 6
+.IX Item "0x200"
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
+.IP 0x400 6
+.IX Item "0x400"
+Save source code lines into \f(CW\*(C`@{"_<$filename"}\*(C'\fR.
+.IP 0x800 6
+.IX Item "0x800"
+When saving source, include evals that generate no subroutines.
+.IP 0x1000 6
+.IX Item "0x1000"
+When saving source, include source that did not compile.
+.RE
+.RS 8
+.Sp
+Some bits may be relevant at compile-time only, some at
+run-time only.  This is a new mechanism and the details may change.
+See also perldebguts.
+.RE
+.IP ${^TAINT} 8
+.IX Xref "${^TAINT}"
+.IX Item "${^TAINT}"
+Reflects if taint mode is on or off.  1 for on (the program was run with
+\&\fB\-T\fR), 0 for off, \-1 when only taint warnings are enabled (i.e. with
+\&\fB\-t\fR or \fB\-TU\fR).
+.Sp
+Note: if your perl was built without taint support (see perlsec),
+then \f(CW\*(C`${^TAINT}\*(C'\fR will always be 0, even if the program was run with \fB\-T\fR).
+.Sp
+This variable is read-only.
+.Sp
+This variable was added in Perl v5.8.0.
+.IP ${^SAFE_LOCALES} 8
+.IX Xref "${^SAFE_LOCALES}"
+.IX Item "${^SAFE_LOCALES}"
+Reflects if safe locale operations are available to this perl (when the
+value is 1) or not (the value is 0).  This variable is always 1 if the
+perl has been compiled without threads.  It is also 1 if this perl is
+using thread-safe locale operations.  Note that an individual thread may
+choose to use the global locale (generally unsafe) by calling
+"switch_to_global_locale" in perlapi.  This variable currently is still
+set to 1 in such threads.
+.Sp
+This variable is read-only.
+.Sp
+This variable was added in Perl v5.28.0.
+.IP ${^UNICODE} 8
+.IX Xref "${^UNICODE}"
+.IX Item "${^UNICODE}"
+Reflects certain Unicode settings of Perl.  See
+perlrun documentation for the \f(CW\*(C`\-C\*(C'\fR
+switch for more information about the possible values.
+.Sp
+This variable is set during Perl startup and is thereafter read-only.
+.Sp
+This variable was added in Perl v5.8.2.
+.IP ${^UTF8CACHE} 8
+.IX Xref "${^UTF8CACHE}"
+.IX Item "${^UTF8CACHE}"
+This variable controls the state of the internal UTF\-8 offset caching code.
+1 for on (the default), 0 for off, \-1 to debug the caching code by checking
+all its results against linear scans, and panicking on any discrepancy.
+.Sp
+This variable was added in Perl v5.8.9.  It is subject to change or
+removal without notice, but is currently used to avoid recalculating the
+boundaries of multi-byte UTF\-8\-encoded characters.
+.IP ${^UTF8LOCALE} 8
+.IX Xref "${^UTF8LOCALE}"
+.IX Item "${^UTF8LOCALE}"
+This variable indicates whether a UTF\-8 locale was detected by perl at
+startup.  This information is used by perl when it's in
+adjust\-utf8ness\-to\-locale mode (as when run with the \f(CW\*(C`\-CL\*(C'\fR command-line
+switch); see perlrun for more info on
+this.
+.Sp
+This variable was added in Perl v5.8.8.
+.SS "Deprecated and removed variables"
+.IX Subsection "Deprecated and removed variables"
+Deprecating a variable announces the intent of the perl maintainers to
+eventually remove the variable from the language.  It may still be
+available despite its status.  Using a deprecated variable triggers
+a warning.
+.PP
+Once a variable is removed, its use triggers an error telling you
+the variable is unsupported.
+.PP
+See perldiag for details about error messages.
+.IP $# 8
+.IX Xref "$#"
+\&\f(CW$#\fR was a variable that could be used to format printed numbers.
+After a deprecation cycle, its magic was removed in Perl v5.10.0 and
+using it now triggers a warning: \f(CW\*(C`$# is no longer supported\*(C'\fR.
+.Sp
+This is not the sigil you use in front of an array name to get the
+last index, like \f(CW$#array\fR.  That's still how you get the last index
+of an array in Perl.  The two have nothing to do with each other.
+.Sp
+Deprecated in Perl 5.
+.Sp
+Removed in Perl v5.10.0.
+.IP $* 8
+.IX Xref "$*"
+\&\f(CW$*\fR was a variable that you could use to enable multiline matching.
+After a deprecation cycle, its magic was removed in Perl v5.10.0.
+Using it now triggers a warning: \f(CW\*(C`$* is no longer supported\*(C'\fR.
+You should use the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR regexp modifiers instead.
+.Sp
+Deprecated in Perl 5.
+.Sp
+Removed in Perl v5.10.0.
+.IP $[ 8
+.IX Xref "$["
+This variable stores the index of the first element in an array, and
+of the first character in a substring.  The default is 0, but you could
+theoretically set it to 1 to make Perl behave more like \fBawk\fR (or Fortran)
+when subscripting and when evaluating the \fBindex()\fR and \fBsubstr()\fR functions.
+.Sp
+As of release 5 of Perl, assignment to \f(CW$[\fR is treated as a compiler
+directive, and cannot influence the behavior of any other file.
+(That's why you can only assign compile-time constants to it.)
+Its use is highly discouraged.
+.Sp
+Prior to Perl v5.10.0, assignment to \f(CW$[\fR could be seen from outer lexical
+scopes in the same file, unlike other compile-time directives (such as
+strict).  Using \fBlocal()\fR on it would bind its value strictly to a lexical
+block.  Now it is always lexically scoped.
+.Sp
+As of Perl v5.16.0, it is implemented by the arybase module.
+.Sp
+As of Perl v5.30.0, or under \f(CW\*(C`use v5.16\*(C'\fR, or \f(CW\*(C`no feature "array_base"\*(C'\fR,
+\&\f(CW$[\fR no longer has any effect, and always contains 0.
+Assigning 0 to it is permitted, but any other value will produce an error.
+.Sp
+Mnemonic: [ begins subscripts.
+.Sp
+Deprecated in Perl v5.12.0.
+.IP ${^ENCODING} 8
+.IX Xref "${^ENCODING}"
+.IX Item "${^ENCODING}"
+This variable is no longer supported.
+.Sp
+It used to hold the \fIobject reference\fR to the \f(CW\*(C`Encode\*(C'\fR object that was
+used to convert the source code to Unicode.
+.Sp
+Its purpose was to allow your non-ASCII Perl
+scripts not to have to be written in UTF\-8; this was
+useful before editors that worked on UTF\-8 encoded text were common, but
+that was long ago.  It caused problems, such as affecting the operation
+of other modules that weren't expecting it, causing general mayhem.
+.Sp
+If you need something like this functionality, it is recommended that use
+you a simple source filter, such as Filter::Encoding.
+.Sp
+If you are coming here because code of yours is being adversely affected
+by someone's use of this variable, you can usually work around it by
+doing this:
+.Sp
+.Vb 1
+\& local ${^ENCODING};
+.Ve
+.Sp
+near the beginning of the functions that are getting broken.  This
+undefines the variable during the scope of execution of the including
+function.
+.Sp
+This variable was added in Perl 5.8.2 and removed in 5.26.0.
+Setting it to anything other than \f(CW\*(C`undef\*(C'\fR was made fatal in Perl 5.28.0.
+.IP ${^WIN32_SLOPPY_STAT} 8
+.IX Xref "${^WIN32_SLOPPY_STAT} sitecustomize sitecustomize.pl"
+.IX Item "${^WIN32_SLOPPY_STAT}"
+This variable no longer has any function.
+.Sp
+This variable was added in Perl v5.10.0 and removed in Perl v5.34.0.
diff --git a/upstream/mageia-cauldron/man1/perlvms.1 b/upstream/mageia-cauldron/man1/perlvms.1
new file mode 100644
index 00000000..dba02b0f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlvms.1
@@ -0,0 +1,1197 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLVMS 1"
+.TH PERLVMS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlvms \- VMS\-specific documentation for Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Gathered below are notes describing details of Perl 5's 
+behavior on VMS.  They are a supplement to the regular Perl 5 
+documentation, so we have focussed on the ways in which Perl 
+5 functions differently under VMS than it does under Unix, 
+and on the interactions between Perl and the rest of the 
+operating system.  We haven't tried to duplicate complete 
+descriptions of Perl features from the main Perl 
+documentation, which can be found in the \fI[.pod]\fR 
+subdirectory of the Perl distribution.
+.PP
+We hope these notes will save you from confusion and lost 
+sleep when writing Perl scripts on VMS.  If you find we've 
+missed something you think should appear here, please don't 
+hesitate to drop a line to vmsperl@perl.org.
+.SH Installation
+.IX Header "Installation"
+Directions for building and installing Perl 5 can be found in 
+the file \fIREADME.vms\fR in the main source directory of the 
+Perl distribution.
+.SH "Organization of Perl Images"
+.IX Header "Organization of Perl Images"
+.SS "Core Images"
+.IX Subsection "Core Images"
+During the build process, three Perl images are produced.
+\&\fIMiniperl.Exe\fR is an executable image which contains all of
+the basic functionality of Perl, but cannot take advantage of
+Perl XS extensions and has a hard-wired list of library locations
+for loading pure-Perl modules.  It is used extensively to build and
+test Perl and various extensions, but is not installed.
+.PP
+Most of the complete Perl resides in the shareable image \fIPerlShr.Exe\fR,
+which provides a core to which the Perl executable image and all Perl
+extensions are linked. It is generally located via the logical name
+\&\fIPERLSHR\fR.  While it's possible to put the image in \fISYS$SHARE\fR to
+make it loadable, that's not recommended. And while you may wish to
+INSTALL the image for performance reasons, you should not install it
+with privileges; if you do, the result will not be what you expect as
+image privileges are disabled during Perl start-up.
+.PP
+Finally, \fIPerl.Exe\fR is an executable image containing the main
+entry point for Perl, as well as some initialization code.  It
+should be placed in a public directory, and made world executable.
+In order to run Perl with command line arguments, you should
+define a foreign command to invoke this image.
+.SS "Perl Extensions"
+.IX Subsection "Perl Extensions"
+Perl extensions are packages which provide both XS and Perl code
+to add new functionality to perl.  (XS is a meta-language which
+simplifies writing C code which interacts with Perl, see
+perlxs for more details.)  The Perl code for an
+extension is treated like any other library module \- it's
+made available in your script through the appropriate
+\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statement, and usually defines a Perl
+package containing the extension.
+.PP
+The portion of the extension provided by the XS code may be
+connected to the rest of Perl in either of two ways.  In the
+\&\fBstatic\fR configuration, the object code for the extension is
+linked directly into \fIPerlShr.Exe\fR, and is initialized whenever
+Perl is invoked.  In the \fBdynamic\fR configuration, the extension's
+machine code is placed into a separate shareable image, which is
+mapped by Perl's DynaLoader when the extension is \f(CW\*(C`use\*(C'\fRd or
+\&\f(CW\*(C`require\*(C'\fRd in your script.  This allows you to maintain the
+extension as a separate entity, at the cost of keeping track of the
+additional shareable image.  Most extensions can be set up as either
+static or dynamic.
+.PP
+The source code for an extension usually resides in its own
+directory.  At least three files are generally provided:
+\&\fIExtshortname\fR\fI.xs\fR (where \fIExtshortname\fR is the portion of
+the extension's name following the last \f(CW\*(C`::\*(C'\fR), containing
+the XS code, \fIExtshortname\fR\fI.pm\fR, the Perl library module
+for the extension, and \fIMakefile.PL\fR, a Perl script which uses
+the \f(CW\*(C`MakeMaker\*(C'\fR library modules supplied with Perl to generate
+a \fIDescrip.MMS\fR file for the extension.
+.SS "Installing static extensions"
+.IX Subsection "Installing static extensions"
+Since static extensions are incorporated directly into
+\&\fIPerlShr.Exe\fR, you'll have to rebuild Perl to incorporate a
+new extension.  You should edit the main \fIDescrip.MMS\fR or \fIMakefile\fR
+you use to build Perl, adding the extension's name to the \f(CW\*(C`ext\*(C'\fR
+macro, and the extension's object file to the \f(CW\*(C`extobj\*(C'\fR macro.
+You'll also need to build the extension's object file, either
+by adding dependencies to the main \fIDescrip.MMS\fR, or using a
+separate \fIDescrip.MMS\fR for the extension.  Then, rebuild
+\&\fIPerlShr.Exe\fR to incorporate the new code.
+.PP
+Finally, you'll need to copy the extension's Perl library
+module to the \fI[.\fR\fIExtname\fR\fI]\fR subdirectory under one
+of the directories in \f(CW@INC\fR, where \fIExtname\fR is the name
+of the extension, with all \f(CW\*(C`::\*(C'\fR replaced by \f(CW\*(C`.\*(C'\fR (e.g.
+the library module for extension Foo::Bar would be copied
+to a \fI[.Foo.Bar]\fR subdirectory).
+.SS "Installing dynamic extensions"
+.IX Subsection "Installing dynamic extensions"
+In general, the distributed kit for a Perl extension includes
+a file named Makefile.PL, which is a Perl program which is used
+to create a \fIDescrip.MMS\fR file which can be used to build and
+install the files required by the extension.  The kit should be
+unpacked into a directory tree \fBnot\fR under the main Perl source
+directory, and the procedure for building the extension is simply
+.PP
+.Vb 4
+\&    $ perl Makefile.PL  ! Create Descrip.MMS
+\&    $ mmk               ! Build necessary files
+\&    $ mmk test          ! Run test code, if supplied
+\&    $ mmk install       ! Install into public Perl tree
+.Ve
+.PP
+VMS support for this process in the current release of Perl
+is sufficient to handle most extensions.  (See the MakeMaker
+documentation for more details on installation options for
+extensions.)
+.IP \(bu 4
+the \fI[.Lib.Auto.\fR\fIArch\fR\f(CI$PVers\fR\fI\fR\fIExtname\fR\fI]\fR subdirectory
+of one of the directories in \f(CW@INC\fR (where \fIPVers\fR
+is the version of Perl you're using, as supplied in \f(CW$]\fR,
+with '.' converted to '_'), or
+.IP \(bu 4
+one of the directories in \f(CW@INC\fR, or
+.IP \(bu 4
+a directory which the extensions Perl library module
+passes to the DynaLoader when asking it to map
+the shareable image, or
+.IP \(bu 4
+\&\fISys$Share\fR or \fISys$Library\fR.
+.PP
+If the shareable image isn't in any of these places, you'll need
+to define a logical name \fIExtshortname\fR, where \fIExtshortname\fR
+is the portion of the extension's name after the last \f(CW\*(C`::\*(C'\fR, which
+translates to the full file specification of the shareable image.
+.SH "File specifications"
+.IX Header "File specifications"
+.SS Syntax
+.IX Subsection "Syntax"
+We have tried to make Perl aware of both VMS-style and Unix-style file
+specifications wherever possible.  You may use either style, or both,
+on the command line and in scripts, but you may not combine the two
+styles within a single file specification.  VMS Perl interprets Unix
+pathnames in much the same way as the CRTL (\fIe.g.\fR the first component
+of an absolute path is read as the device name for the VMS file
+specification).  There are a set of functions provided in the
+\&\f(CW\*(C`VMS::Filespec\*(C'\fR package for explicit interconversion between VMS and
+Unix syntax; its documentation provides more details.
+.PP
+We've tried to minimize the dependence of Perl library
+modules on Unix syntax, but you may find that some of these,
+as well as some scripts written for Unix systems, will
+require that you use Unix syntax, since they will assume that
+\&'/' is the directory separator, \fIetc.\fR  If you find instances
+of this in the Perl distribution itself, please let us know,
+so we can try to work around them.
+.PP
+Also when working on Perl programs on VMS, if you need a syntax
+in a specific operating system format, then you need either to
+check the appropriate DECC$ feature logical, or call a conversion
+routine to force it to that format.
+.PP
+The feature logical name DECC$FILENAME_UNIX_REPORT modifies traditional
+Perl behavior in the conversion of file specifications from Unix to VMS
+format in order to follow the extended character handling rules now
+expected by the CRTL.  Specifically, when this feature is in effect, the
+\&\f(CW\*(C`./.../\*(C'\fR in a Unix path is now translated to \f(CW\*(C`[.^.^.^.]\*(C'\fR instead of
+the traditional VMS \f(CW\*(C`[...]\*(C'\fR.  To be compatible with what MakeMaker
+expects, if a VMS path cannot be translated to a Unix path, it is
+passed through unchanged, so \f(CWunixify("[...]")\fR will return \f(CW\*(C`[...]\*(C'\fR.
+.PP
+There are several ambiguous cases where a conversion routine cannot
+determine whether an input filename is in Unix format or in VMS format,
+since now both VMS and Unix file specifications may have characters in
+them that could be mistaken for syntax delimiters of the other type. So
+some pathnames simply cannot be used in a mode that allows either type
+of pathname to be present.  Perl will tend to assume that an ambiguous
+filename is in Unix format.
+.PP
+Allowing "." as a version delimiter is simply incompatible with
+determining whether a pathname is in VMS format or in Unix format with
+extended file syntax.  There is no way to know whether "perl\-5.8.6" is a
+Unix "perl\-5.8.6" or a VMS "perl\-5.8;6" when passing it to \fBunixify()\fR or
+\&\fBvmsify()\fR.
+.PP
+The DECC$FILENAME_UNIX_REPORT logical name controls how Perl interprets
+filenames to the extent that Perl uses the CRTL internally for many
+purposes, and attempts to follow CRTL conventions for reporting
+filenames.  The DECC$FILENAME_UNIX_ONLY feature differs in that it
+expects all filenames passed to the C run-time to be already in Unix
+format.  This feature is not yet supported in Perl since Perl uses
+traditional OpenVMS file specifications internally and in the test
+harness, and it is not yet clear whether this mode will be useful or
+useable.  The feature logical name DECC$POSIX_COMPLIANT_PATHNAMES is new
+with the RMS Symbolic Link SDK and included with OpenVMS v8.3, but is
+not yet supported in Perl.
+.SS "Filename Case"
+.IX Subsection "Filename Case"
+Perl enables DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE by
+default.  Note that the latter only takes effect when extended parse
+is set in the process in which Perl is running.  When these features
+are explicitly disabled in the environment or the CRTL does not support
+them, Perl follows the traditional CRTL behavior of downcasing command-line
+arguments and returning file specifications in lower case only.
+.PP
+\&\fIN. B.\fR  It is very easy to get tripped up using a mixture of other
+programs, external utilities, and Perl scripts that are in varying
+states of being able to handle case preservation.  For example, a file
+created by an older version of an archive utility or a build utility
+such as MMK or MMS may generate a filename in all upper case even on an
+ODS\-5 volume.  If this filename is later retrieved by a Perl script or
+module in a case preserving environment, that upper case name may not
+match the mixed-case or lower-case expectations of the Perl code.  Your
+best bet is to follow an all-or-nothing approach to case preservation:
+either don't use it at all, or make sure your entire toolchain and
+application environment support and use it.
+.PP
+OpenVMS Alpha v7.3\-1 and later and all version of OpenVMS I64 support
+case sensitivity as a process setting (see \f(CW\*(C`SET\ PROCESS\ /CASE_LOOKUP=SENSITIVE\*(C'\fR). Perl does not currently support case
+sensitivity on VMS, but it may in the future, so Perl programs should
+use the \f(CW\*(C`File::Spec\->case_tolerant\*(C'\fR method to determine the state, and
+not the \f(CW$^O\fR variable.
+.SS "Symbolic Links"
+.IX Subsection "Symbolic Links"
+When built on an ODS\-5 volume with symbolic links enabled, Perl by
+default supports symbolic links when the requisite support is available
+in the filesystem and CRTL (generally 64\-bit OpenVMS v8.3 and later). 
+There are a number of limitations and caveats to be aware of when
+working with symbolic links on VMS.  Most notably, the target of a valid
+symbolic link must be expressed as a Unix-style path and it must exist
+on a volume visible from your POSIX root (see the \f(CW\*(C`SHOW\ ROOT\*(C'\fR command
+in DCL help).  For further details on symbolic link capabilities and
+requirements, see chapter 12 of the CRTL manual that ships with OpenVMS
+v8.3 or later.
+.SS "Wildcard expansion"
+.IX Subsection "Wildcard expansion"
+File specifications containing wildcards are allowed both on 
+the command line and within Perl globs (e.g. \f(CW\*(C`<*.c>\*(C'\fR).  If
+the wildcard filespec uses VMS syntax, the resultant 
+filespecs will follow VMS syntax; if a Unix-style filespec is 
+passed in, Unix-style filespecs will be returned.
+Similar to the behavior of wildcard globbing for a Unix shell,
+one can escape command line wildcards with double quotation
+marks \f(CW\*(C`"\*(C'\fR around a perl program command line argument.  However,
+owing to the stripping of \f(CW\*(C`"\*(C'\fR characters carried out by the C
+handling of argv you will need to escape a construct such as
+this one (in a directory containing the files \fIPERL.C\fR, \fIPERL.EXE\fR,
+\&\fIPERL.H\fR, and \fIPERL.OBJ\fR):
+.PP
+.Vb 2
+\&    $ perl \-e "print join(\*(Aq \*(Aq,@ARGV)" perl.*
+\&    perl.c perl.exe perl.h perl.obj
+.Ve
+.PP
+in the following triple quoted manner:
+.PP
+.Vb 2
+\&    $ perl \-e "print join(\*(Aq \*(Aq,@ARGV)" """perl.*"""
+\&    perl.*
+.Ve
+.PP
+In both the case of unquoted command line arguments or in calls
+to \f(CWglob()\fR VMS wildcard expansion is performed. (csh-style
+wildcard expansion is available if you use \f(CW\*(C`File::Glob::glob\*(C'\fR.)
+If the wildcard filespec contains a device or directory 
+specification, then the resultant filespecs will also contain 
+a device and directory; otherwise, device and directory 
+information are removed.  VMS-style resultant filespecs will 
+contain a full device and directory, while Unix-style 
+resultant filespecs will contain only as much of a directory 
+path as was present in the input filespec.  For example, if 
+your default directory is Perl_Root:[000000], the expansion 
+of \f(CW\*(C`[.t]*.*\*(C'\fR will yield filespecs  like 
+"perl_root:[t]base.dir", while the expansion of \f(CW\*(C`t/*/*\*(C'\fR will 
+yield filespecs like "t/base.dir".  (This is done to match 
+the behavior of glob expansion performed by Unix shells.)
+.PP
+Similarly, the resultant filespec will contain the file version
+only if one was present in the input filespec.
+.SS Pipes
+.IX Subsection "Pipes"
+Input and output pipes to Perl filehandles are supported; the 
+"file name" is passed to lib$\fBspawn()\fR for asynchronous 
+execution.  You should be careful to close any pipes you have 
+opened in a Perl script, lest you leave any "orphaned" 
+subprocesses around when Perl exits.
+.PP
+You may also use backticks to invoke a DCL subprocess, whose 
+output is used as the return value of the expression.  The 
+string between the backticks is handled as if it were the
+argument to the \f(CW\*(C`system\*(C'\fR operator (see below).  In this case,
+Perl will wait for the subprocess to complete before continuing.
+.PP
+The mailbox (MBX) that perl can create to communicate with a pipe
+defaults to a buffer size of 8192 on 64\-bit systems, 512 on VAX.  The
+default buffer size is adjustable via the logical name PERL_MBX_SIZE
+provided that the value falls between 128 and the SYSGEN parameter
+MAXBUF inclusive.  For example, to set the mailbox size to 32767 use
+\&\f(CW\*(C`$ENV{\*(AqPERL_MBX_SIZE\*(Aq} = 32767;\*(C'\fR and then open and use pipe constructs. 
+An alternative would be to issue the command:
+.PP
+.Vb 1
+\&    $ Define PERL_MBX_SIZE 32767
+.Ve
+.PP
+before running your wide record pipe program.  A larger value may
+improve performance at the expense of the BYTLM UAF quota.
+.SH "PERL5LIB and PERLLIB"
+.IX Header "PERL5LIB and PERLLIB"
+The PERL5LIB and PERLLIB environment elements work as documented in perl,
+except that the element separator is, by default, '|' instead of ':'.
+However, when running under a Unix shell as determined by the logical
+name \f(CW\*(C`GNV$UNIX_SHELL\*(C'\fR, the separator will be ':' as on Unix systems. The
+directory specifications may use either VMS or Unix syntax.
+.SH "The Perl Forked Debugger"
+.IX Header "The Perl Forked Debugger"
+The Perl forked debugger places the debugger commands and output in a
+separate X\-11 terminal window so that commands and output from multiple
+processes are not mixed together.
+.PP
+Perl on VMS supports an emulation of the forked debugger when Perl is
+run on a VMS system that has X11 support installed.
+.PP
+To use the forked debugger, you need to have the default display set to an
+X\-11 Server and some environment variables set that Unix expects.
+.PP
+The forked debugger requires the environment variable \f(CW\*(C`TERM\*(C'\fR to be \f(CW\*(C`xterm\*(C'\fR,
+and the environment variable \f(CW\*(C`DISPLAY\*(C'\fR to exist.  \f(CW\*(C`xterm\*(C'\fR must be in
+lower case.
+.PP
+.Vb 1
+\&  $define TERM "xterm"
+\&
+\&  $define DISPLAY "hostname:0.0"
+.Ve
+.PP
+Currently the value of \f(CW\*(C`DISPLAY\*(C'\fR is ignored.  It is recommended that it be set
+to be the hostname of the display, the server and screen in Unix notation.  In
+the future the value of DISPLAY may be honored by Perl instead of using the
+default display.
+.PP
+It may be helpful to always use the forked debugger so that script I/O is
+separated from debugger I/O.  You can force the debugger to be forked by
+assigning a value to the logical name <PERLDB_PIDS> that is not a process
+identification number.
+.PP
+.Vb 1
+\&  $define PERLDB_PIDS XXXX
+.Ve
+.SH PERL_VMS_EXCEPTION_DEBUG
+.IX Header "PERL_VMS_EXCEPTION_DEBUG"
+The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS
+debugger to be invoked if a fatal exception that is not otherwise
+handled is raised.  The purpose of this is to allow debugging of
+internal Perl problems that would cause such a condition.
+.PP
+This allows the programmer to look at the execution stack and variables to
+find out the cause of the exception.  As the debugger is being invoked as
+the Perl interpreter is about to do a fatal exit, continuing the execution
+in debug mode is usually not practical.
+.PP
+Starting Perl in the VMS debugger may change the program execution
+profile in a way that such problems are not reproduced.
+.PP
+The \f(CW\*(C`kill\*(C'\fR function can be used to test this functionality from within
+a program.
+.PP
+In typical VMS style, only the first letter of the value of this logical
+name is actually checked in a case insensitive mode, and it is considered
+enabled if it is the value "T","1" or "E".
+.PP
+This logical name must be defined before Perl is started.
+.SH "Command line"
+.IX Header "Command line"
+.SS "I/O redirection and backgrounding"
+.IX Subsection "I/O redirection and backgrounding"
+Perl for VMS supports redirection of input and output on the 
+command line, using a subset of Bourne shell syntax:
+.IP \(bu 4
+\&\f(CW\*(C`<file\*(C'\fR reads stdin from \f(CW\*(C`file\*(C'\fR,
+.IP \(bu 4
+\&\f(CW\*(C`>file\*(C'\fR writes stdout to \f(CW\*(C`file\*(C'\fR,
+.IP \(bu 4
+\&\f(CW\*(C`>>file\*(C'\fR appends stdout to \f(CW\*(C`file\*(C'\fR,
+.IP \(bu 4
+\&\f(CW\*(C`2>file\*(C'\fR writes stderr to \f(CW\*(C`file\*(C'\fR,
+.IP \(bu 4
+\&\f(CW\*(C`2>>file\*(C'\fR appends stderr to \f(CW\*(C`file\*(C'\fR, and
+.IP \(bu 4
+\&\f(CW\*(C`2>&1\*(C'\fR redirects stderr to stdout.
+.PP
+In addition, output may be piped to a subprocess, using the  
+character '|'.  Anything after this character on the command 
+line is passed to a subprocess for execution; the subprocess 
+takes the output of Perl as its input.
+.PP
+Finally, if the command line ends with '&', the entire 
+command is run in the background as an asynchronous 
+subprocess.
+.SS "Command line switches"
+.IX Subsection "Command line switches"
+The following command line switches behave differently under
+VMS than described in perlrun.  Note also that in order
+to pass uppercase switches to Perl, you need to enclose
+them in double-quotes on the command line, since the CRTL
+downcases all unquoted strings.
+.PP
+On newer 64 bit versions of OpenVMS, a process setting now
+controls if the quoting is needed to preserve the case of
+command line arguments.
+.IP \-i 4
+.IX Item "-i"
+If the \f(CW\*(C`\-i\*(C'\fR switch is present but no extension for a backup
+copy is given, then inplace editing creates a new version of
+a file; the existing copy is not deleted.  (Note that if
+an extension is given, an existing file is renamed to the backup
+file, as is the case under other operating systems, so it does
+not remain as a previous version under the original filename.)
+.IP \-S 4
+.IX Item "-S"
+If the \f(CW"\-S"\fR or \f(CW\*(C`\-"S"\*(C'\fR switch is present \fIand\fR the script
+name does not contain a directory, then Perl translates the
+logical name DCL$PATH as a searchlist, using each translation
+as a directory in which to look for the script.  In addition,
+if no file type is specified, Perl looks in each directory
+for a file matching the name specified, with a blank type,
+a type of \fI.pl\fR, and a type of \fI.com\fR, in that order.
+.IP \-u 4
+.IX Item "-u"
+The \f(CW\*(C`\-u\*(C'\fR switch causes the VMS debugger to be invoked
+after the Perl program is compiled, but before it has
+run.  It does not create a core dump file.
+.SH "Perl functions"
+.IX Header "Perl functions"
+As of the time this document was last revised, the following 
+Perl functions were implemented in the VMS port of Perl 
+(functions marked with * are discussed in more detail below):
+.PP
+.Vb 10
+\&    file tests*, abs, alarm, atan, backticks*, binmode*, bless,
+\&    caller, chdir, chmod, chown, chomp, chop, chr,
+\&    close, closedir, cos, crypt*, defined, delete, die, do, dump*, 
+\&    each, endgrent, endpwent, eof, eval, exec*, exists, exit, exp, 
+\&    fileno, flock  getc, getgrent*, getgrgid*, getgrnam, getlogin,
+\&    getppid, getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
+\&    grep, hex, ioctl, import, index, int, join, keys, kill*,
+\&    last, lc, lcfirst, lchown*, length, link*, local, localtime, log,
+\&    lstat, m//, map, mkdir, my, next, no, oct, open, opendir, ord,
+\&    pack, pipe, pop, pos, print, printf, push, q//, qq//, qw//,
+\&    qx//*, quotemeta, rand, read, readdir, readlink*, redo, ref,
+\&    rename, require, reset, return, reverse, rewinddir, rindex,
+\&    rmdir, s///, scalar, seek, seekdir, select(internal),
+\&    select (system call)*, setgrent, setpwent, shift, sin, sleep,
+\&    socketpair, sort, splice, split, sprintf, sqrt, srand, stat,
+\&    study, substr, symlink*, sysread, system*, syswrite, tell,
+\&    telldir, tie, time, times*, tr///, uc, ucfirst, umask,
+\&    undef, unlink*, unpack, untie, unshift, use, utime*,
+\&    values, vec, wait, waitpid*, wantarray, warn, write, y///
+.Ve
+.PP
+The following functions were not implemented in the VMS port, 
+and calling them produces a fatal error (usually) or 
+undefined behavior (rarely, we hope):
+.PP
+.Vb 4
+\&    chroot, dbmclose, dbmopen, fork*, getpgrp, getpriority,  
+\&    msgctl, msgget, msgsend, msgrcv, semctl,
+\&    semget, semop, setpgrp, setpriority, shmctl, shmget,
+\&    shmread, shmwrite, syscall
+.Ve
+.PP
+The following functions are available on Perls compiled with Dec C
+5.2 or greater and running VMS 7.0 or greater:
+.PP
+.Vb 1
+\&    truncate
+.Ve
+.PP
+The following functions are available on Perls built on VMS 7.2 or
+greater:
+.PP
+.Vb 1
+\&    fcntl (without locking)
+.Ve
+.PP
+The following functions may or may not be implemented, 
+depending on what type of socket support you've built into 
+your copy of Perl:
+.PP
+.Vb 9
+\&    accept, bind, connect, getpeername,
+\&    gethostbyname, getnetbyname, getprotobyname,
+\&    getservbyname, gethostbyaddr, getnetbyaddr,
+\&    getprotobynumber, getservbyport, gethostent,
+\&    getnetent, getprotoent, getservent, sethostent,
+\&    setnetent, setprotoent, setservent, endhostent,
+\&    endnetent, endprotoent, endservent, getsockname,
+\&    getsockopt, listen, recv, select(system call)*,
+\&    send, setsockopt, shutdown, socket
+.Ve
+.PP
+The following function is available on Perls built on 64 bit OpenVMS v8.2
+with hard links enabled on an ODS\-5 formatted build disk.  CRTL support
+is in principle available as of OpenVMS v7.3\-1, and better configuration
+support could detect this.
+.PP
+.Vb 1
+\&    link
+.Ve
+.PP
+The following functions are available on Perls built on 64 bit OpenVMS
+v8.2 and later.  CRTL support is in principle available as of OpenVMS
+v7.3\-2, and better configuration support could detect this.
+.PP
+.Vb 2
+\&   getgrgid, getgrnam, getpwnam, getpwuid,
+\&   setgrent, ttyname
+.Ve
+.PP
+The following functions are available on Perls built on 64 bit OpenVMS v8.2
+and later.
+.PP
+.Vb 1
+\&   statvfs, socketpair
+.Ve
+.IP "File tests" 4
+.IX Item "File tests"
+The tests \f(CW\*(C`\-b\*(C'\fR, \f(CW\*(C`\-B\*(C'\fR, \f(CW\*(C`\-c\*(C'\fR, \f(CW\*(C`\-C\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR, \f(CW\*(C`\-e\*(C'\fR, \f(CW\*(C`\-f\*(C'\fR,
+\&\f(CW\*(C`\-o\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, \f(CW\*(C`\-s\*(C'\fR, \f(CW\*(C`\-S\*(C'\fR, \f(CW\*(C`\-t\*(C'\fR, \f(CW\*(C`\-T\*(C'\fR, and \f(CW\*(C`\-z\*(C'\fR work as
+advertised.  The return values for \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR
+tell you whether you can actually access the file; this may
+not reflect the UIC-based file protections.  Since real and
+effective UIC don't differ under VMS, \f(CW\*(C`\-O\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR,
+and \f(CW\*(C`\-X\*(C'\fR are equivalent to \f(CW\*(C`\-o\*(C'\fR, \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR.
+Similarly, several other tests, including \f(CW\*(C`\-A\*(C'\fR, \f(CW\*(C`\-g\*(C'\fR, \f(CW\*(C`\-k\*(C'\fR,
+\&\f(CW\*(C`\-l\*(C'\fR, \f(CW\*(C`\-p\*(C'\fR, and \f(CW\*(C`\-u\*(C'\fR, aren't particularly meaningful under
+VMS, and the values returned by these tests reflect whatever
+your CRTL \f(CWstat()\fR routine does to the equivalent bits in the
+st_mode field.  Finally, \f(CW\*(C`\-d\*(C'\fR returns true if passed a device
+specification without an explicit directory (e.g. \f(CW\*(C`DUA1:\*(C'\fR), as
+well as if passed a directory.
+.Sp
+There are DECC feature logical names AND ODS\-5 volume attributes that
+also control what values are returned for the date fields.
+.Sp
+Note: Some sites have reported problems when using the file-access
+tests (\f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR) on files accessed via DEC's DFS.
+Specifically, since DFS does not currently provide access to the
+extended file header of files on remote volumes, attempts to
+examine the ACL fail, and the file tests will return false,
+with \f(CW$!\fR indicating that the file does not exist.  You can
+use \f(CW\*(C`stat\*(C'\fR on these files, since that checks UIC-based protection
+only, and then manually check the appropriate bits, as defined by
+your C compiler's \fIstat.h\fR, in the mode value it returns, if you
+need an approximation of the file's protections.
+.IP backticks 4
+.IX Item "backticks"
+Backticks create a subprocess, and pass the enclosed string
+to it for execution as a DCL command.  Since the subprocess is
+created directly via \f(CW\*(C`lib$spawn()\*(C'\fR, any valid DCL command string
+may be specified.
+.IP "binmode FILEHANDLE" 4
+.IX Item "binmode FILEHANDLE"
+The \f(CW\*(C`binmode\*(C'\fR operator will attempt to insure that no translation
+of carriage control occurs on input from or output to this filehandle.
+Since this involves reopening the file and then restoring its
+file position indicator, if this function returns FALSE, the
+underlying filehandle may no longer point to an open file, or may
+point to a different position in the file than before \f(CW\*(C`binmode\*(C'\fR
+was called.
+.Sp
+Note that \f(CW\*(C`binmode\*(C'\fR is generally not necessary when using normal
+filehandles; it is provided so that you can control I/O to existing
+record-structured files when necessary.  You can also use the
+\&\f(CW\*(C`vmsfopen\*(C'\fR function in the VMS::Stdio extension to gain finer
+control of I/O to files and devices with different record structures.
+.IP "crypt PLAINTEXT, USER" 4
+.IX Item "crypt PLAINTEXT, USER"
+The \f(CW\*(C`crypt\*(C'\fR operator uses the \f(CW\*(C`sys$hash_password\*(C'\fR system
+service to generate the hashed representation of PLAINTEXT.
+If USER is a valid username, the algorithm and salt values
+are taken from that user's UAF record.  If it is not, then
+the preferred algorithm and a salt of 0 are used.  The
+quadword encrypted value is returned as an 8\-character string.
+.Sp
+The value returned by \f(CW\*(C`crypt\*(C'\fR may be compared against
+the encrypted password from the UAF returned by the \f(CW\*(C`getpw*\*(C'\fR
+functions, in order to authenticate users.  If you're
+going to do this, remember that the encrypted password in
+the UAF was generated using uppercase username and
+password strings; you'll have to upcase the arguments to
+\&\f(CW\*(C`crypt\*(C'\fR to insure that you'll get the proper value:
+.Sp
+.Vb 9
+\&    sub validate_passwd {
+\&        my($user,$passwd) = @_;
+\&        my($pwdhash);
+\&        if ( !($pwdhash = (getpwnam($user))[1]) ||
+\&               $pwdhash ne crypt("\eU$passwd","\eU$name") ) {
+\&            intruder_alert($name);
+\&        }
+\&        return 1;
+\&    }
+.Ve
+.IP die 4
+.IX Item "die"
+\&\f(CW\*(C`die\*(C'\fR will force the native VMS exit status to be an SS$_ABORT code
+if neither of the $! or $? status values are ones that would cause
+the native status to be interpreted as being what VMS classifies as
+SEVERE_ERROR severity for DCL error handling.
+.Sp
+When \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR is active (see "$?" below), the native VMS exit
+status value will have either one of the \f(CW$!\fR or \f(CW$?\fR or \f(CW$^E\fR or
+the Unix value 255 encoded into it in a way that the effective original
+value can be decoded by other programs written in C, including Perl
+and the GNV package.  As per the normal non-VMS behavior of \f(CW\*(C`die\*(C'\fR if
+either \f(CW$!\fR or \f(CW$?\fR are non-zero, one of those values will be
+encoded into a native VMS status value.  If both of the Unix status
+values are 0, and the \f(CW$^E\fR value is set one of ERROR or SEVERE_ERROR
+severity, then the \f(CW$^E\fR value will be used as the exit code as is.
+If none of the above apply, the Unix value of 255 will be encoded into
+a native VMS exit status value.
+.Sp
+Please note a significant difference in the behavior of \f(CW\*(C`die\*(C'\fR in
+the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR mode is that it does not force a VMS
+SEVERE_ERROR status on exit.  The Unix exit values of 2 through
+255 will be encoded in VMS status values with severity levels of
+SUCCESS.  The Unix exit value of 1 will be encoded in a VMS status
+value with a severity level of ERROR.  This is to be compatible with
+how the VMS C library encodes these values.
+.Sp
+The minimum severity level set by \f(CW\*(C`die\*(C'\fR in \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR mode
+may be changed to be ERROR or higher in the future depending on the 
+results of testing and further review.
+.Sp
+See "$?" for a description of the encoding of the Unix value to
+produce a native VMS status containing it.
+.IP dump 4
+.IX Item "dump"
+Rather than causing Perl to abort and dump core, the \f(CW\*(C`dump\*(C'\fR
+operator invokes the VMS debugger.  If you continue to
+execute the Perl program under the debugger, control will
+be transferred to the label specified as the argument to
+\&\f(CW\*(C`dump\*(C'\fR, or, if no label was specified, back to the
+beginning of the program.  All other state of the program
+(\fIe.g.\fR values of variables, open file handles) are not
+affected by calling \f(CW\*(C`dump\*(C'\fR.
+.IP "exec LIST" 4
+.IX Item "exec LIST"
+A call to \f(CW\*(C`exec\*(C'\fR will cause Perl to exit, and to invoke the command
+given as an argument to \f(CW\*(C`exec\*(C'\fR via \f(CW\*(C`lib$do_command\*(C'\fR.  If the
+argument begins with '@' or '$' (other than as part of a filespec),
+then it is executed as a DCL command.  Otherwise, the first token on
+the command line is treated as the filespec of an image to run, and
+an attempt is made to invoke it (using \fI.Exe\fR and the process
+defaults to expand the filespec) and pass the rest of \f(CW\*(C`exec\*(C'\fR's
+argument to it as parameters.  If the token has no file type, and
+matches a file with null type, then an attempt is made to determine
+whether the file is an executable image which should be invoked
+using \f(CW\*(C`MCR\*(C'\fR or a text file which should be passed to DCL as a
+command procedure.
+.IP fork 4
+.IX Item "fork"
+While in principle the \f(CW\*(C`fork\*(C'\fR operator could be implemented via
+(and with the same rather severe limitations as) the CRTL \f(CWvfork()\fR
+routine, and while some internal support to do just that is in
+place, the implementation has never been completed, making \f(CW\*(C`fork\*(C'\fR
+currently unavailable.  A true kernel \f(CWfork()\fR is expected in a
+future version of VMS, and the pseudo-fork based on interpreter
+threads may be available in a future version of Perl on VMS (see
+perlfork).  In the meantime, use \f(CW\*(C`system\*(C'\fR, backticks, or piped
+filehandles to create subprocesses.
+.IP getpwent 4
+.IX Item "getpwent"
+.PD 0
+.IP getpwnam 4
+.IX Item "getpwnam"
+.IP getpwuid 4
+.IX Item "getpwuid"
+.PD
+These operators obtain the information described in perlfunc,
+if you have the privileges necessary to retrieve the named user's
+UAF information via \f(CW\*(C`sys$getuai\*(C'\fR.  If not, then only the \f(CW$name\fR,
+\&\f(CW$uid\fR, and \f(CW$gid\fR items are returned.  The \f(CW$dir\fR item contains
+the login directory in VMS syntax, while the \f(CW$comment\fR item
+contains the login directory in Unix syntax. The \f(CW$gcos\fR item
+contains the owner field from the UAF record.  The \f(CW$quota\fR
+item is not used.
+.IP gmtime 4
+.IX Item "gmtime"
+The \f(CW\*(C`gmtime\*(C'\fR operator will function properly if you have a
+working CRTL \f(CWgmtime()\fR routine, or if the logical name
+SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds
+which must be added to UTC to yield local time.  (This logical
+name is defined automatically if you are running a version of
+VMS with built-in UTC support.)  If neither of these cases is
+true, a warning message is printed, and \f(CW\*(C`undef\*(C'\fR is returned.
+.IP kill 4
+.IX Item "kill"
+In most cases, \f(CW\*(C`kill\*(C'\fR is implemented via the undocumented system
+service \f(CW$SIGPRC\fR, which has the same calling sequence as \f(CW$FORCEX\fR, but
+throws an exception in the target process rather than forcing it to call
+\&\f(CW$EXIT\fR.  Generally speaking, \f(CW\*(C`kill\*(C'\fR follows the behavior of the
+CRTL's \f(CWkill()\fR function, but unlike that function can be called from
+within a signal handler.  Also, unlike the \f(CW\*(C`kill\*(C'\fR in some versions of
+the CRTL, Perl's \f(CW\*(C`kill\*(C'\fR checks the validity of the signal passed in and
+returns an error rather than attempting to send an unrecognized signal.
+.Sp
+Also, negative signal values don't do anything special under
+VMS; they're just converted to the corresponding positive value.
+.IP qx// 4
+.IX Item "qx//"
+See the entry on \f(CW\*(C`backticks\*(C'\fR above.
+.IP "select (system call)" 4
+.IX Item "select (system call)"
+If Perl was not built with socket support, the system call
+version of \f(CW\*(C`select\*(C'\fR is not available at all.  If socket
+support is present, then the system call version of
+\&\f(CW\*(C`select\*(C'\fR functions only for file descriptors attached
+to sockets.  It will not provide information about regular
+files or pipes, since the CRTL \f(CWselect()\fR routine does not
+provide this functionality.
+.IP "stat EXPR" 4
+.IX Item "stat EXPR"
+Since VMS keeps track of files according to a different scheme
+than Unix, it's not really possible to represent the file's ID
+in the \f(CW\*(C`st_dev\*(C'\fR and \f(CW\*(C`st_ino\*(C'\fR fields of a \f(CW\*(C`struct stat\*(C'\fR.  Perl
+tries its best, though, and the values it uses are pretty unlikely
+to be the same for two different files.  We can't guarantee this,
+though, so caveat scriptor.
+.IP "system LIST" 4
+.IX Item "system LIST"
+The \f(CW\*(C`system\*(C'\fR operator creates a subprocess, and passes its 
+arguments to the subprocess for execution as a DCL command.  
+Since the subprocess is created directly via \f(CW\*(C`lib$spawn()\*(C'\fR, any 
+valid DCL command string may be specified.  If the string begins with
+\&'@', it is treated as a DCL command unconditionally.  Otherwise, if
+the first token contains a character used as a delimiter in file
+specification (e.g. \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`]\*(C'\fR), an attempt is made to expand it
+using  a default type of \fI.Exe\fR and the process defaults, and if
+successful, the resulting file is invoked via \f(CW\*(C`MCR\*(C'\fR. This allows you
+to invoke an image directly simply by passing the file specification
+to \f(CW\*(C`system\*(C'\fR, a common Unixish idiom.  If the token has no file type,
+and matches a file with null type, then an attempt is made to
+determine whether the file is an executable image which should be
+invoked using \f(CW\*(C`MCR\*(C'\fR or a text file which should be passed to DCL
+as a command procedure.
+.Sp
+If LIST consists of the empty string, \f(CW\*(C`system\*(C'\fR spawns an
+interactive DCL subprocess, in the same fashion as typing
+\&\fBSPAWN\fR at the DCL prompt.
+.Sp
+Perl waits for the subprocess to complete before continuing
+execution in the current process.  As described in perlfunc,
+the return value of \f(CW\*(C`system\*(C'\fR is a fake "status" which follows
+POSIX semantics unless the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in
+effect; see the description of \f(CW$?\fR in this document for more 
+detail.
+.IP time 4
+.IX Item "time"
+The value returned by \f(CW\*(C`time\*(C'\fR is the offset in seconds from
+01\-JAN\-1970 00:00:00 (just like the CRTL's \fBtimes()\fR routine), in order
+to make life easier for code coming in from the POSIX/Unix world.
+.IP times 4
+.IX Item "times"
+The array returned by the \f(CW\*(C`times\*(C'\fR operator is divided up 
+according to the same rules the CRTL \f(CWtimes()\fR routine.  
+Therefore, the "system time" elements will always be 0, since 
+there is no difference between "user time" and "system" time 
+under VMS, and the time accumulated by a subprocess may or may 
+not appear separately in the "child time" field, depending on 
+whether \f(CWtimes()\fR keeps track of subprocesses separately.  Note
+especially that the VAXCRTL (at least) keeps track only of
+subprocesses spawned using \f(CWfork()\fR and \f(CWexec()\fR; it will not
+accumulate the times of subprocesses spawned via pipes, \f(CWsystem()\fR,
+or backticks.
+.IP "unlink LIST" 4
+.IX Item "unlink LIST"
+\&\f(CW\*(C`unlink\*(C'\fR will delete the highest version of a file only; in
+order to delete all versions, you need to say
+.Sp
+.Vb 1
+\&    1 while unlink LIST;
+.Ve
+.Sp
+You may need to make this change to scripts written for a
+Unix system which expect that after a call to \f(CW\*(C`unlink\*(C'\fR,
+no files with the names passed to \f(CW\*(C`unlink\*(C'\fR will exist.
+(Note: This can be changed at compile time; if you
+\&\f(CW\*(C`use Config\*(C'\fR and \f(CW$Config{\*(Aqd_unlink_all_versions\*(Aq}\fR is
+\&\f(CW\*(C`define\*(C'\fR, then \f(CW\*(C`unlink\*(C'\fR will delete all versions of a
+file on the first call.)
+.Sp
+\&\f(CW\*(C`unlink\*(C'\fR will delete a file if at all possible, even if it
+requires changing file protection (though it won't try to
+change the protection of the parent directory).  You can tell
+whether you've got explicit delete access to a file by using the
+\&\f(CW\*(C`VMS::Filespec::candelete\*(C'\fR operator.  For instance, in order
+to delete only files to which you have delete access, you could
+say something like
+.Sp
+.Vb 8
+\&    sub safe_unlink {
+\&        my($file,$num);
+\&        foreach $file (@_) {
+\&            next unless VMS::Filespec::candelete($file);
+\&            $num += unlink $file;
+\&        }
+\&        $num;
+\&    }
+.Ve
+.Sp
+(or you could just use \f(CW\*(C`VMS::Stdio::remove\*(C'\fR, if you've installed
+the VMS::Stdio extension distributed with Perl). If \f(CW\*(C`unlink\*(C'\fR has to
+change the file protection to delete the file, and you interrupt it
+in midstream, the file may be left intact, but with a changed ACL
+allowing you delete access.
+.Sp
+This behavior of \f(CW\*(C`unlink\*(C'\fR is to be compatible with POSIX behavior
+and not traditional VMS behavior.
+.IP "utime LIST" 4
+.IX Item "utime LIST"
+This operator changes only the modification time of the file (VMS 
+revision date) on ODS\-2 volumes and ODS\-5 volumes without access 
+dates enabled. On ODS\-5 volumes with access dates enabled, the 
+true access time is modified.
+.IP "waitpid PID,FLAGS" 4
+.IX Item "waitpid PID,FLAGS"
+If PID is a subprocess started by a piped \f(CWopen()\fR (see open), 
+\&\f(CW\*(C`waitpid\*(C'\fR will wait for that subprocess, and return its final status
+value in \f(CW$?\fR.  If PID is a subprocess created in some other way (e.g.
+SPAWNed before Perl was invoked), \f(CW\*(C`waitpid\*(C'\fR will simply check once per
+second whether the process has completed, and return when it has.  (If
+PID specifies a process that isn't a subprocess of the current process,
+and you invoked Perl with the \f(CW\*(C`\-w\*(C'\fR switch, a warning will be issued.)
+.Sp
+Returns PID on success, \-1 on error.  The FLAGS argument is ignored
+in all cases.
+.SH "Perl variables"
+.IX Header "Perl variables"
+The following VMS-specific information applies to the indicated
+"special" Perl variables, in addition to the general information
+in perlvar.  Where there is a conflict, this information
+takes precedence.
+.ie n .IP %ENV 4
+.el .IP \f(CW%ENV\fR 4
+.IX Item "%ENV"
+The operation of the \f(CW%ENV\fR array depends on the translation
+of the logical name \fIPERL_ENV_TABLES\fR.  If defined, it should
+be a search list, each element of which specifies a location
+for \f(CW%ENV\fR elements.  If you tell Perl to read or set the
+element \f(CW\*(C`$ENV{\*(C'\fR\fIname\fR\f(CW\*(C`}\*(C'\fR, then Perl uses the translations of
+\&\fIPERL_ENV_TABLES\fR as follows:
+.RS 4
+.IP CRTL_ENV 4
+.IX Item "CRTL_ENV"
+This string tells Perl to consult the CRTL's internal \f(CW\*(C`environ\*(C'\fR array
+of key-value pairs, using \fIname\fR as the key.  In most cases, this
+contains only a few keys, but if Perl was invoked via the C
+\&\f(CW\*(C`exec[lv]e()\*(C'\fR function, as is the case for some embedded Perl
+applications or when running under a shell such as GNV bash, the
+\&\f(CW\*(C`environ\*(C'\fR array may have been populated by the calling program.
+.IP CLISYM_[LOCAL] 4
+.IX Item "CLISYM_[LOCAL]"
+A string beginning with \f(CW\*(C`CLISYM_\*(C'\fRtells Perl to consult the CLI's
+symbol tables, using \fIname\fR as the name of the symbol.  When reading
+an element of \f(CW%ENV\fR, the local symbol table is scanned first, followed
+by the global symbol table..  The characters following \f(CW\*(C`CLISYM_\*(C'\fR are
+significant when an element of \f(CW%ENV\fR is set or deleted: if the
+complete string is \f(CW\*(C`CLISYM_LOCAL\*(C'\fR, the change is made in the local
+symbol table; otherwise the global symbol table is changed.
+.IP "Any other string" 4
+.IX Item "Any other string"
+If an element of \fIPERL_ENV_TABLES\fR translates to any other string,
+that string is used as the name of a logical name table, which is
+consulted using \fIname\fR as the logical name.  The normal search
+order of access modes is used.
+.RE
+.RS 4
+.Sp
+\&\fIPERL_ENV_TABLES\fR is translated once when Perl starts up; any changes
+you make while Perl is running do not affect the behavior of \f(CW%ENV\fR.
+If \fIPERL_ENV_TABLES\fR is not defined, then Perl defaults to consulting
+first the logical name tables specified by \fILNM$FILE_DEV\fR, and then
+the CRTL \f(CW\*(C`environ\*(C'\fR array.  This default order is reversed when the
+logical name \fIGNV$UNIX_SHELL\fR is defined, such as when running under
+GNV bash.
+.Sp
+For operations on \f(CW%ENV\fR entries based on logical names or DCL symbols, the
+key string is treated as if it were entirely uppercase, regardless of the
+case actually specified in the Perl expression. Entries in \f(CW%ENV\fR based on the
+CRTL's environ array preserve the case of the key string when stored, and
+lookups are case sensitive.
+.Sp
+When an element of \f(CW%ENV\fR is read, the locations to which
+\&\fIPERL_ENV_TABLES\fR points are checked in order, and the value
+obtained from the first successful lookup is returned.  If the
+name of the \f(CW%ENV\fR element contains a semi-colon, it and
+any characters after it are removed.  These are ignored when
+the CRTL \f(CW\*(C`environ\*(C'\fR array or a CLI symbol table is consulted.
+However, the name is looked up in a logical name table, the
+suffix after the semi-colon is treated as the translation index
+to be used for the lookup.   This lets you look up successive values
+for search list logical names.  For instance, if you say
+.Sp
+.Vb 3
+\&   $  Define STORY  once,upon,a,time,there,was
+\&   $  perl \-e "for ($i = 0; $i <= 6; $i++) " \-
+\&   _$ \-e "{ print $ENV{\*(Aqstory;\*(Aq.$i},\*(Aq \*(Aq}"
+.Ve
+.Sp
+Perl will print \f(CW\*(C`ONCE UPON A TIME THERE WAS\*(C'\fR, assuming, of course,
+that \fIPERL_ENV_TABLES\fR is set up so that the logical name \f(CW\*(C`story\*(C'\fR
+is found, rather than a CLI symbol or CRTL \f(CW\*(C`environ\*(C'\fR element with
+the same name.
+.Sp
+When an element of \f(CW%ENV\fR is set to a defined string, the
+corresponding definition is made in the location to which the
+first translation of \fIPERL_ENV_TABLES\fR points.  If this causes a
+logical name to be created, it is defined in supervisor mode.
+(The same is done if an existing logical name was defined in
+executive or kernel mode; an existing user or supervisor mode
+logical name is reset to the new value.)  If the value is an empty
+string, the logical name's translation is defined as a single \f(CW\*(C`NUL\*(C'\fR
+(ASCII \f(CW\*(C`\e0\*(C'\fR) character, since a logical name cannot translate to a
+zero-length string.  (This restriction does not apply to CLI symbols
+or CRTL \f(CW\*(C`environ\*(C'\fR values; they are set to the empty string.)
+.Sp
+When an element of \f(CW%ENV\fR is set to \f(CW\*(C`undef\*(C'\fR, the element is looked
+up as if it were being read, and if it is found, it is deleted.  (An
+item "deleted" from the CRTL \f(CW\*(C`environ\*(C'\fR array is set to the empty
+string.)  Using \f(CW\*(C`delete\*(C'\fR to remove an element from \f(CW%ENV\fR has a
+similar effect, but after the element is deleted, another attempt is
+made to look up the element, so an inner-mode logical name or a name
+in another location will replace the logical name just deleted. In
+either case, only the first value found searching PERL_ENV_TABLES is
+altered.  It is not possible at present to define a search list
+logical name via \f(CW%ENV\fR.
+.Sp
+The element \f(CW$ENV{DEFAULT}\fR is special: when read, it returns
+Perl's current default device and directory, and when set, it
+resets them, regardless of the definition of \fIPERL_ENV_TABLES\fR.
+It cannot be cleared or deleted; attempts to do so are silently
+ignored.
+.Sp
+Note that if you want to pass on any elements of the
+C\-local environ array to a subprocess which isn't
+started by fork/exec, or isn't running a C program, you
+can "promote" them to logical names in the current
+process, which will then be inherited by all subprocesses,
+by saying
+.Sp
+.Vb 4
+\&    foreach my $key (qw[C\-local keys you want promoted]) {
+\&        my $temp = $ENV{$key}; # read from C\-local array
+\&        $ENV{$key} = $temp;    # and define as logical name
+\&    }
+.Ve
+.Sp
+(You can't just say \f(CW\*(C`$ENV{$key} = $ENV{$key}\*(C'\fR, since the
+Perl optimizer is smart enough to elide the expression.)
+.Sp
+Don't try to clear \f(CW%ENV\fR by saying \f(CW\*(C`%ENV = ();\*(C'\fR, it will throw
+a fatal error.  This is equivalent to doing the following from DCL:
+.Sp
+.Vb 1
+\&    DELETE/LOGICAL *
+.Ve
+.Sp
+You can imagine how bad things would be if, for example, the SYS$MANAGER
+or SYS$SYSTEM logical names were deleted.
+.Sp
+At present, the first time you iterate over \f(CW%ENV\fR using
+\&\f(CW\*(C`keys\*(C'\fR, or \f(CW\*(C`values\*(C'\fR,  you will incur a time penalty as all
+logical names are read, in order to fully populate \f(CW%ENV\fR.
+Subsequent iterations will not reread logical names, so they
+won't be as slow, but they also won't reflect any changes
+to logical name tables caused by other programs.
+.Sp
+You do need to be careful with the logical names representing
+process-permanent files, such as \f(CW\*(C`SYS$INPUT\*(C'\fR and \f(CW\*(C`SYS$OUTPUT\*(C'\fR.
+The translations for these logical names are prepended with a
+two-byte binary value (0x1B 0x00) that needs to be stripped off
+if you want to use it. (In previous versions of Perl it wasn't
+possible to get the values of these logical names, as the null
+byte acted as an end-of-string marker)
+.RE
+.IP $! 4
+The string value of \f(CW$!\fR is that returned by the CRTL's
+\&\fBstrerror()\fR function, so it will include the VMS message for
+VMS-specific errors.  The numeric value of \f(CW$!\fR is the
+value of \f(CW\*(C`errno\*(C'\fR, except if errno is EVMSERR, in which
+case \f(CW$!\fR contains the value of vaxc$errno.  Setting \f(CW$!\fR
+always sets errno to the value specified.  If this value is
+EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so
+that the string value of \f(CW$!\fR won't reflect the VMS error
+message from before \f(CW$!\fR was set.
+.IP $^E 4
+.IX Item "$^E"
+This variable provides direct access to VMS status values
+in vaxc$errno, which are often more specific than the
+generic Unix-style error messages in \f(CW$!\fR.  Its numeric value
+is the value of vaxc$errno, and its string value is the
+corresponding VMS message string, as retrieved by sys$\fBgetmsg()\fR.
+Setting \f(CW$^E\fR sets vaxc$errno to the value specified.
+.Sp
+While Perl attempts to keep the vaxc$errno value to be current, if
+errno is not EVMSERR, it may not be from the current operation.
+.IP $? 4
+The "status value" returned in \f(CW$?\fR is synthesized from the
+actual exit status of the subprocess in a way that approximates
+POSIX \fBwait\fR\|(5) semantics, in order to allow Perl programs to
+portably test for successful completion of subprocesses.  The
+low order 8 bits of \f(CW$?\fR are always 0 under VMS, since the
+termination status of a process may or may not have been
+generated by an exception.
+.Sp
+The next 8 bits contain the termination status of the program.
+.Sp
+If the child process follows the convention of C programs
+compiled with the _POSIX_EXIT macro set, the status value will
+contain the actual value of 0 to 255 returned by that program
+on a normal exit.
+.Sp
+With the _POSIX_EXIT macro set, the Unix exit value of zero is
+represented as a VMS native status of 1, and the Unix values
+from 2 to 255 are encoded by the equation:
+.Sp
+.Vb 1
+\&   VMS_status = 0x35a000 + (unix_value * 8) + 1.
+.Ve
+.Sp
+And in the special case of Unix value 1 the encoding is:
+.Sp
+.Vb 1
+\&   VMS_status = 0x35a000 + 8 + 2 + 0x10000000.
+.Ve
+.Sp
+For other termination statuses, the severity portion of the
+subprocess's exit status is used: if the severity was success or
+informational, these bits are all 0; if the severity was
+warning, they contain a value of 1; if the severity was
+error or fatal error, they contain the actual severity bits,
+which turns out to be a value of 2 for error and 4 for severe_error.
+Fatal is another term for the severe_error status.
+.Sp
+As a result, \f(CW$?\fR will always be zero if the subprocess's exit
+status indicated successful completion, and non-zero if a
+warning or error occurred or a program compliant with encoding
+_POSIX_EXIT values was run and set a status.
+.Sp
+How can you tell the difference between a non-zero status that is
+the result of a VMS native error status or an encoded Unix status?
+You can not unless you look at the ${^CHILD_ERROR_NATIVE} value.
+The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value
+and check the severity bits. If the severity bits are equal to 1,
+then if the numeric value for \f(CW$?\fR is between 2 and 255 or 0, then
+\&\f(CW$?\fR accurately reflects a value passed back from a Unix application.
+If \f(CW$?\fR is 1, and the severity bits indicate a VMS error (2), then
+\&\f(CW$?\fR is from a Unix application exit value.
+.Sp
+In practice, Perl scripts that call programs that return _POSIX_EXIT
+type status values will be expecting those values, and programs that
+call traditional VMS programs will either be expecting the previous
+behavior or just checking for a non-zero status.
+.Sp
+And success is always the value 0 in all behaviors.
+.Sp
+When the actual VMS termination status of the child is an error,
+internally the \f(CW$!\fR value will be set to the closest Unix errno
+value to that error so that Perl scripts that test for error
+messages will see the expected Unix style error message instead
+of a VMS message.
+.Sp
+Conversely, when setting \f(CW$?\fR in an END block, an attempt is made
+to convert the POSIX value into a native status intelligible to
+the operating system upon exiting Perl.  What this boils down to
+is that setting \f(CW$?\fR to zero results in the generic success value
+SS$_NORMAL, and setting \f(CW$?\fR to a non-zero value results in the
+generic failure status SS$_ABORT.  See also "exit" in perlport.
+.Sp
+With the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR logical name defined as "ENABLE",
+setting \f(CW$?\fR will cause the new value to be encoded into \f(CW$^E\fR
+so that either the original parent or child exit status values 
+ 0 to 255 can be automatically recovered by C programs expecting
+_POSIX_EXIT behavior.  If both a parent and a child exit value are
+non-zero, then it will be assumed that this is actually a VMS native
+status value to be passed through.  The special value of 0xFFFF is
+almost a NOOP as it will cause the current native VMS status in the
+C library to become the current native Perl VMS status, and is handled
+this way as it is known to not be a valid native VMS status value.
+It is recommend that only values in the range of normal Unix parent or
+child status numbers, 0 to 255 are used.
+.Sp
+The pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the actual 
+VMS exit status instead of the default emulation of POSIX status 
+described above.  This pragma also disables the conversion of
+non-zero values to SS$_ABORT when setting \f(CW$?\fR in an END
+block (but zero will still be converted to SS$_NORMAL).
+.Sp
+Do not use the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR with \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR
+enabled, as they are at times requesting conflicting actions and the
+consequence of ignoring this advice will be undefined to allow future
+improvements in the POSIX exit handling.
+.Sp
+In general, with \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR enabled, more detailed information
+will be available in the exit status for DCL scripts or other native VMS tools,
+and will give the expected information for Posix programs.  It has not been
+made the default in order to preserve backward compatibility.
+.Sp
+N.B. Setting \f(CW\*(C`DECC$FILENAME_UNIX_REPORT\*(C'\fR implicitly enables 
+\&\f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR.
+.IP $| 4
+Setting \f(CW$|\fR for an I/O stream causes data to be flushed
+all the way to disk on each write (\fIi.e.\fR not just to
+the underlying RMS buffers for a file).  In other words,
+it's equivalent to calling \fBfflush()\fR and \fBfsync()\fR from C.
+.SH "Standard modules with VMS-specific differences"
+.IX Header "Standard modules with VMS-specific differences"
+.SS SDBM_File
+.IX Subsection "SDBM_File"
+SDBM_File works properly on VMS. It has, however, one minor
+difference. The database directory file created has a \fI.sdbm_dir\fR
+extension rather than a \fI.dir\fR extension. \fI.dir\fR files are VMS filesystem
+directory files, and using them for other purposes could cause unacceptable
+problems.
+.SH "Revision date"
+.IX Header "Revision date"
+Please see the git repository for revision history.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Charles Bailey  bailey@cor.newman.upenn.edu
+Craig Berry  craigberry@mac.com
+Dan Sugalski  dan@sidhe.org
+John Malmberg wb8tyw@qsl.net
diff --git a/upstream/mageia-cauldron/man1/perlvos.1 b/upstream/mageia-cauldron/man1/perlvos.1
new file mode 100644
index 00000000..92d82665
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlvos.1
@@ -0,0 +1,165 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLVOS 1"
+.TH PERLVOS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlvos \- Perl for Stratus OpenVOS
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+This file contains notes for building perl on the Stratus OpenVOS
+operating system.  Perl is a scripting or macro language that is
+popular on many systems.  See perlbook for a number of good books
+on Perl.
+.PP
+These are instructions for building Perl from source.  This version of
+Perl requires the dynamic linking support that is found in OpenVOS
+Release 17.1 and thus is not supported on OpenVOS Release 17.0 or
+earlier releases.
+.PP
+If you are running VOS Release 14.4.1 or later, you can obtain a
+pre-compiled, supported copy of perl by purchasing the GNU Tools
+product from Stratus Technologies.
+.SH "BUILDING PERL FOR OPENVOS"
+.IX Header "BUILDING PERL FOR OPENVOS"
+To build perl from its source code on the Stratus V Series platform
+you must have OpenVOS Release 17.1.0 or later, GNU Tools Release
+3.5 or later, and the C/POSIX Runtime Libraries.
+.PP
+Follow the normal instructions for building perl; e.g, enter bash, run
+the Configure script, then use "gmake" to build perl.
+.SH "INSTALLING PERL IN OPENVOS"
+.IX Header "INSTALLING PERL IN OPENVOS"
+.IP 1. 4
+After you have built perl using the Configure script, ensure that you
+have modify and default write permission to \f(CW\*(C`>system>ported\*(C'\fR and
+all subdirectories.  Then type
+.Sp
+.Vb 1
+\&     gmake install
+.Ve
+.IP 2. 4
+While there are currently no architecture-specific extensions or
+modules distributed with perl, the following directories can be
+used to hold such files (replace the string VERSION by the
+appropriate version number):
+.Sp
+.Vb 1
+\&     >system>ported>lib>perl5>VERSION>i786
+.Ve
+.IP 3. 4
+Site-specific perl extensions and modules can be installed in one of
+two places.  Put architecture-independent files into:
+.Sp
+.Vb 1
+\&     >system>ported>lib>perl5>site_perl>VERSION
+.Ve
+.Sp
+Put site-specific architecture-dependent files into one of the
+following directories:
+.Sp
+.Vb 1
+\&     >system>ported>lib>perl5>site_perl>VERSION>i786
+.Ve
+.IP 4. 4
+You can examine the \f(CW@INC\fR variable from within a perl program
+to see the order in which Perl searches these directories.
+.SH "USING PERL IN OPENVOS"
+.IX Header "USING PERL IN OPENVOS"
+.SS "Restrictions of Perl on OpenVOS"
+.IX Subsection "Restrictions of Perl on OpenVOS"
+This port of Perl version 5 prefers Unix-style, slash-separated
+pathnames over OpenVOS-style greater-than-separated pathnames.
+OpenVOS-style pathnames should work in most contexts, but if you have
+trouble, replace all greater-than characters by slash characters.
+Because the slash character is used as a pathname delimiter, Perl
+cannot process OpenVOS pathnames containing a slash character in a
+directory or file name; these must be renamed.
+.PP
+This port of Perl also uses Unix-epoch date values internally.
+As long as you are dealing with ASCII character string
+representations of dates, this should not be an issue.  The
+supported epoch is January 1, 1980 to January 17, 2038.
+.PP
+See the file pod/perlport.pod for more information about the OpenVOS
+port of Perl.
+.SH "TEST STATUS"
+.IX Header "TEST STATUS"
+A number of the perl self-tests fails for various reasons; generally
+these are minor and due to subtle differences between common
+POSIX-based environments and the OpenVOS POSIX environment.  Ensure
+that you conduct sufficient testing of your code to guarantee that it
+works properly in the OpenVOS environment.
+.SH "SUPPORT STATUS"
+.IX Header "SUPPORT STATUS"
+I'm offering this port "as is".  You can ask me questions, but I
+can't guarantee I'll be able to answer them.  There are some
+excellent books available on the Perl language; consult a book
+seller.
+.PP
+If you want a supported version of perl for OpenVOS, purchase the
+OpenVOS GNU Tools product from Stratus Technologies, along with a
+support contract (or from anyone else who will sell you support).
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Green (Paul.Green@stratus.com)
+.SH "LAST UPDATE"
+.IX Header "LAST UPDATE"
+February 28, 2013
diff --git a/upstream/mageia-cauldron/man1/perlwin32.1 b/upstream/mageia-cauldron/man1/perlwin32.1
new file mode 100644
index 00000000..1448c904
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlwin32.1
@@ -0,0 +1,821 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLWIN32 1"
+.TH PERLWIN32 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlwin32 \- Perl under Windows
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+These are instructions for building Perl under Windows 7 and later.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Before you start, you should glance through the README file
+found in the top-level directory to which the Perl distribution
+was extracted.  Make sure you read and understand the terms under
+which this software is being distributed.
+.PP
+Also make sure you read "BUGS AND CAVEATS" below for the
+known limitations of this port.
+.PP
+The INSTALL file in the perl top-level has much information that is
+only relevant to people building Perl on Unix-like systems.  In
+particular, you can safely ignore any information that talks about
+"Configure".
+.PP
+You may also want to look at one other option for building a perl that
+will work on Windows: the README.cygwin file, which give a different
+set of rules to build a perl for Windows.  This method will probably
+enable you to build a more Unix-compatible perl, but you will also
+need to download and use various other build-time and run-time support
+software described in that file.
+.PP
+This set of instructions is meant to describe a so-called "native"
+port of Perl to the Windows platform.  This includes both 32\-bit and
+64\-bit Windows operating systems.  The resulting Perl requires no
+additional software to run (other than what came with your operating
+system).  Currently, this port is capable of using one of the
+following compilers on the Intel x86 and x86_64 architectures:
+.PP
+.Vb 4
+\&      Microsoft Visual C++    version 12.0 or later
+\&      Intel C++ Compiler      (experimental)
+\&      Gcc by mingw.org        gcc version 3.4.5\-5.3.0
+\&      Gcc by mingw\-w64.org    gcc version 4.4.3 or later
+.Ve
+.PP
+Note that the last two of these are actually competing projects both
+delivering complete gcc toolchain for MS Windows:
+.IP <https://osdn.net/projects/mingw/> 4
+.IX Item "<https://osdn.net/projects/mingw/>"
+Delivers gcc toolchain building 32\-bit executables (which can be used both 32 and 64 bit Windows platforms)
+.IP <https://mingw\-w64.org> 4
+.IX Item "<https://mingw-w64.org>"
+Delivers gcc toolchain targeting both 64\-bit Windows and 32\-bit Windows
+platforms (despite the project name "mingw\-w64" they are not only 64\-bit
+oriented). They deliver the native gcc compilers and cross-compilers
+that are also supported by perl's makefile.
+.PP
+The Microsoft Visual C++ compilers are also now being given away free. They
+are available as "Visual C++ 2013\-2022 Community Edition" and are the same
+compilers that ship with "Visual C++ 2013\-2022 Professional".
+.PP
+Visual C++ 2013 is capable of \fBtargeting\fR XP and Windows Server 2003 but the
+build host requirement is Windows 7/Windows Server 2012. For more details see
+https://docs.microsoft.com/en\-us/visualstudio/productinfo/vs2013\-compatibility\-vs
+and
+https://docs.microsoft.com/en\-us/visualstudio/productinfo/vs2013\-sysrequirements\-vs
+.PP
+The MinGW64 compiler is available at <https://mingw\-w64.org>.
+The latter is actually a cross-compiler targeting Win64. There's also a trimmed
+down compiler (no java, or gfortran) suitable for building perl available at:
+<https://strawberryperl.com/package/kmx/64_gcctoolchain/>
+.PP
+NOTE: If you're using a 32\-bit compiler to build perl on a 64\-bit Windows
+operating system, then you should set the WIN64 environment variable to "undef".
+Also, the trimmed down compiler only passes tests when USE_ITHREADS *= define
+(as opposed to undef) and when the CFG *= Debug line is commented out.
+.PP
+This port fully supports MakeMaker (the set of modules that
+is used to build extensions to perl).  Therefore, you should be
+able to build and install most extensions found in the CPAN sites.
+See "Usage Hints for Perl on Windows" below for general hints about this.
+.SS "Setting Up Perl on Windows"
+.IX Subsection "Setting Up Perl on Windows"
+.IP Make 4
+.IX Item "Make"
+You need a "make" program to build the sources.  If you are using
+Visual C++, you can use nmake supplied with Visual C++.
+You may also use gmake instead of nmake.  Builds using gcc need
+gmake. nmake is not supported for gcc builds.  Parallel building is only
+supported with gmake, not nmake.
+.IP "Command Shell" 4
+.IX Item "Command Shell"
+Use the default "cmd" shell that comes with Windows.  Some versions of the
+popular 4DOS/NT shell have incompatibilities that may cause you trouble.
+If the build fails under that shell, try building again with the cmd
+shell.
+.Sp
+Make sure the path to the build directory does not contain spaces.  The
+build usually works in this circumstance, but some tests will fail.
+.IP "Microsoft Visual C++" 4
+.IX Item "Microsoft Visual C++"
+The nmake that comes with Visual C++ will suffice for building. Visual C++
+requires that certain things be set up in the console before Visual C++ will
+successfully run. To make a console box be able to run the C compiler, you will
+need to beforehand, run \f(CW\*(C`vcvarsall.bat x86\*(C'\fR to compile for x86\-32 and for
+x86\-64 \f(CW\*(C`vcvarsall.bat amd64\*(C'\fR. On a typical install of a Microsoft C++
+compiler product, these batch files will already be in your \f(CW\*(C`PATH\*(C'\fR
+environment variable so you may just type them without an absolute path into
+your console. If you need to find the absolute path to the batch file, it is
+usually found somewhere like
+C:\eProgram Files (x86)\eMicrosoft Visual Studio 14.0\eVC.
+With some newer Microsoft C products (released after ~2004), the installer will
+put a shortcut in the start menu to launch a new console window with the
+console already set up for your target architecture (x86\-32 or x86\-64 or IA64).
+With the newer compilers, you may also use the older batch files if you choose
+so.
+.IP "Microsoft Visual C++ 2013\-2022 Community Edition" 4
+.IX Item "Microsoft Visual C++ 2013-2022 Community Edition"
+These free versions of Visual C++ 2013\-2022 Professional contain the same
+compilers and linkers that ship with the full versions, and also contain
+everything necessary to build Perl.
+.Sp
+These packages can be downloaded from <https://visualstudio.microsoft.com/>.
+.Sp
+Install Visual C++ 2013\-2022 Community, then setup your environment
+using, e.g.
+.Sp
+\&\fIC:\eProgram Files\eMicrosoft Visual Studio 12.0\eCommon7\eTools\evsvars32.bat\fR
+.Sp
+(assuming the default installation location was chosen).
+.Sp
+Perl should now build using the \fIwin32/Makefile\fR.  You will need to edit that
+file to set \f(CW\*(C`CCTYPE\*(C'\fR to one of \f(CW\*(C`MSVC120\*(C'\fR\-\f(CW\*(C`MSVC143\*(C'\fR first.
+.IP "Microsoft C++ Build Tools" 4
+.IX Item "Microsoft C++ Build Tools"
+There's also a standalone (IDE-less) version of the build tools mentioned
+above containing the MSVC compiler available for download from
+<https://visualstudio.microsoft.com/visual\-cpp\-build\-tools/>.
+.Sp
+This is also referred to as \fIBuild Tools for Visual Studio\fR.
+.IP GCC 4
+.IX Item "GCC"
+Perl can be compiled with gcc from MinGW (version 3.4.5 or later) or from
+MinGW64 (version 4.4.3 or later).  It can be downloaded here:
+.Sp
+<https://osdn.net/projects/mingw/>
+<https://www.mingw\-w64.org/>
+.Sp
+You also need gmake. Usually it comes with MinGW but its executable may have
+a different name, such as mingw32\-make.exe.
+.Sp
+Note that the MinGW build currently fails with version 6.3.0 or later.
+.Sp
+Note also that the C++ mode build currently fails with MinGW 3.4.5 and 4.7.2
+or later, and with MinGW64 64\-bit 6.3.0 or later.
+.IP "Intel C++ Compiler" 4
+.IX Item "Intel C++ Compiler"
+Experimental support for using Intel C++ Compiler has been added. Edit
+\&\fIwin32/Makefile\fR and pick the correct \f(CW\*(C`CCTYPE\*(C'\fR for the Visual C that Intel C
+was installed into. Also uncomment \f(CW\*(C`_\|_ICC\*(C'\fR to enable Intel C on Visual C support.
+To set up the build environment, from the Start Menu run
+IA\-32 Visual Studio 20_\|_ mode or Intel 64 Visual Studio 20_\|_ mode as
+appropriate. Then run \f(CW\*(C`nmake\*(C'\fR as usual in that prompt box.
+.Sp
+Only Intel C++ Compiler v12.1 has been tested. Other versions probably will
+work. Using Intel C++ Compiler instead of Visual C has the benefit of C99
+compatibility which is needed by some CPAN XS modules, while maintaining
+compatibility with Visual C object code and Visual C debugging infrastructure
+unlike GCC.
+.SS Building
+.IX Subsection "Building"
+.IP \(bu 4
+Make sure you are in the \fIwin32\fR subdirectory under the perl toplevel.
+This directory contains a \fIMakefile\fR that will work with
+versions of \f(CW\*(C`nmake\*(C'\fR that come with Visual C++, and
+a GNU make \fIGNUmakefile\fR that will work for all supported compilers.
+The defaults in the \f(CW\*(C`gmake\*(C'\fR makefile are set up to build with MinGW/gcc.
+.IP \(bu 4
+Edit the \fIGNUmakefile\fR (or \fIMakefile\fR, if you're using \fInmake\fR) and change
+the values of \fIINST_DRV\fR and \f(CW\*(C`INST_TOP\*(C'\fR. You can also enable various build
+flags. These are explained in the makefiles.
+.Sp
+Note that it is generally not a good idea to try to build a \f(CW\*(C`perl\*(C'\fR with
+\&\f(CW\*(C`INST_DRV\*(C'\fR and \f(CW\*(C`INST_TOP\*(C'\fR set to a path that already exists from a previous
+build.  In particular, this may cause problems with the
+\&\fIlib/ExtUtils/t/Embed.t\fR test, which attempts to build a test program and
+may end up building against the installed \f(CW\*(C`perl\*(C'\fR's \fIlib/CORE\fR directory
+rather than the one being tested.
+.Sp
+You will have to make sure that \f(CW\*(C`CCTYPE\*(C'\fR is set correctly and that
+\&\f(CW\*(C`CCHOME\*(C'\fR points to wherever you installed your compiler.  For GCC this
+should be the directory that contains the \fIbin\fR, \fIinclude\fR and
+\&\fIlib\fR directories.
+.Sp
+If building with the cross-compiler provided by
+mingw\-w64.org you'll need to uncomment the line that sets
+\&\f(CW\*(C`GCCCROSS\*(C'\fR in the \fIGNUmakefile\fR. Do this only if it's the cross-compiler,
+ie. only if the \fIbin\fR folder doesn't contain a \fIgcc.exe\fR. (The cross-compiler
+does not provide a \fIgcc.exe\fR, \fIg++.exe\fR, \fIar.exe\fR, etc. Instead, all of these
+executables are prefixed with \f(CW\*(C`x86_64\-w64\-mingw32\-\*(C'\fR.)
+.Sp
+The default value for \f(CW\*(C`CCHOME\*(C'\fR in the makefiles for Visual C++
+may not be correct for some versions.  Make sure the default exists
+and is valid.
+.Sp
+If you want build some core extensions statically into \f(CW\*(C`perl\*(C'\fR's DLL,
+specify them in the \f(CW\*(C`STATIC_EXT\*(C'\fR macro.
+.Sp
+Be sure to read the instructions near the top of the makefiles carefully.
+.IP \(bu 4
+Type \f(CW\*(C`gmake\*(C'\fR (or \f(CW\*(C`nmake\*(C'\fR if you are using that version of \f(CW\*(C`make\*(C'\fR).
+.Sp
+This should build everything.  Specifically, it will create \fIperl.exe\fR,
+\&\fIperl538.dll\fR at the perl toplevel, and various other extension DLL's
+under the \fIlib\eauto\fR directory.  If the build fails for any reason, make
+sure you have done the previous steps correctly.
+.Sp
+To try \f(CW\*(C`gmake\*(C'\fR's parallel mode, type \f(CW\*(C`gmake \-j2\*(C'\fR where \f(CW2\fR is the maximum number
+of parallel jobs you want to run. A number of things in the build process will
+run in parallel, but there are serialization points where you will see just 1
+CPU maxed out. This is normal.
+.Sp
+If you are advanced enough with building C code, here is a suggestion to speed
+up building \f(CW\*(C`perl\*(C'\fR, and the later \f(CW\*(C`make test\*(C'\fR. Try to keep your \f(CW\*(C`PATH\*(C'\fR environment
+variable with the least number of folders possible (remember to keep your C
+compiler's folders there). \fIC:\eWINDOWS\esystem32\fR or \fIC:\eWINNT\esystem32\fR
+depending on your OS version should be first folder in \f(CW\*(C`PATH\*(C'\fR, since \f(CW\*(C`cmd.exe\*(C'\fR
+is the most commonly launched program during the build and later testing.
+.SS "Testing Perl on Windows"
+.IX Subsection "Testing Perl on Windows"
+Type "gmake test" (or "nmake test").  This will run most
+of the tests from the testsuite (many tests will be skipped).
+.PP
+There should be no test failures.
+.PP
+If you build with Visual C++ 2013 then three tests currently may fail with
+Daylight Saving Time related problems: \fIt/io/fs.t\fR,
+\&\fIcpan/HTTP\-Tiny/t/110_mirror.t\fR and \fIlib/File/Copy.t\fR. The failures are
+caused by bugs in the CRT in VC++ 2013 which are fixed in VC++2015 and
+later, as explained by Microsoft here:
+<https://connect.microsoft.com/VisualStudio/feedback/details/811534/utime\-sometimes\-fails\-to\-set\-the\-correct\-file\-times\-in\-visual\-c\-2013>. In the meantime,
+if you need fixed \f(CW\*(C`stat\*(C'\fR and \f(CW\*(C`utime\*(C'\fR functions then have a look at the
+CPAN distribution Win32::UTCFileTime.
+.PP
+If you build with Visual C++ 2015 or later then \fIext/XS\-APItest/t/locale.t\fR
+may crash (after all its tests have passed). This is due to a regression in the
+Universal CRT introduced in the Windows 10 April 2018 Update, and will be fixed
+in the May 2019 Update, as explained here: <https://developercommunity.visualstudio.com/content/problem/519486/setlocalelc\-numeric\-iso\-latin\-16\-fails\-then\-succee.html>.
+.PP
+If you build with certain versions (e.g. 4.8.1) of gcc from mingw then
+\&\fIext/POSIX/t/time.t\fR may fail test 17 due to a known bug in those gcc builds:
+see <https://sourceforge.net/p/mingw/bugs/2152/>.
+.PP
+Some test failures may occur if you use a command shell other than the
+native "cmd.exe", or if you are building from a path that contains
+spaces.  So don't do that.
+.PP
+If you are running the tests from a emacs shell window, you may see
+failures in op/stat.t.  Run "gmake test-notty" in that case.
+.PP
+Furthermore, you should make sure that during \f(CW\*(C`make test\*(C'\fR you do not
+have any GNU tool packages in your path: some toolkits like Unixutils
+include some tools (\f(CW\*(C`type\*(C'\fR for instance) which override the Windows
+ones and makes tests fail. Remove them from your path while testing to
+avoid these errors.
+.PP
+To see the output of specific failing tests run the harness from the t
+directory:
+.PP
+.Vb 3
+\&  # assuming you\*(Aqre starting from the win32 directory
+\&  cd ..\ewin32
+\&  .\eperl harness <list of tests>
+.Ve
+.PP
+Please report any other failures as described under "BUGS AND CAVEATS".
+.SS "Installation of Perl on Windows"
+.IX Subsection "Installation of Perl on Windows"
+Type "gmake install" ("nmake install").  This will
+put the newly built perl and the libraries under whatever \f(CW\*(C`INST_TOP\*(C'\fR
+points to in the Makefile.  It will also install the pod documentation
+under \f(CW\*(C`$INST_TOP\e$INST_VER\elib\epod\*(C'\fR and HTML versions of the same
+under \f(CW\*(C`$INST_TOP\e$INST_VER\elib\epod\ehtml\*(C'\fR.
+.PP
+To use the Perl you just installed you will need to add a new entry to
+your PATH environment variable: \f(CW\*(C`$INST_TOP\ebin\*(C'\fR, e.g.
+.PP
+.Vb 1
+\&    set PATH=c:\eperl\ebin;%PATH%
+.Ve
+.PP
+If you opted to uncomment \f(CW\*(C`INST_VER\*(C'\fR and \f(CW\*(C`INST_ARCH\*(C'\fR in the makefile
+then the installation structure is a little more complicated and you will
+need to add two new PATH components instead: \f(CW\*(C`$INST_TOP\e$INST_VER\ebin\*(C'\fR and
+\&\f(CW\*(C`$INST_TOP\e$INST_VER\ebin\e$ARCHNAME\*(C'\fR, e.g.
+.PP
+.Vb 1
+\&    set PATH=c:\eperl\e5.6.0\ebin;c:\eperl\e5.6.0\ebin\eMSWin32\-x86;%PATH%
+.Ve
+.SS "Usage Hints for Perl on Windows"
+.IX Subsection "Usage Hints for Perl on Windows"
+.IP "Environment Variables" 4
+.IX Item "Environment Variables"
+The installation paths that you set during the build get compiled
+into perl, so you don't have to do anything additional to start
+using that perl (except add its location to your PATH variable).
+.Sp
+If you put extensions in unusual places, you can set PERL5LIB
+to a list of paths separated by semicolons where you want perl
+to look for libraries.  Look for descriptions of other environment
+variables you can set in perlrun.
+.Sp
+You can also control the shell that perl uses to run \fBsystem()\fR and
+backtick commands via PERL5SHELL.  See perlrun.
+.Sp
+Perl does not depend on the registry, but it can look up certain default
+values if you choose to put them there unless disabled at build time with
+USE_NO_REGISTRY.  On Perl process start Perl checks if
+\&\f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR and \f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR
+exist.  If the keys exists, they will be checked for remainder of the Perl
+process's run life for certain entries.  Entries in
+\&\f(CW\*(C`HKEY_CURRENT_USER\eSoftware\ePerl\*(C'\fR override entries in
+\&\f(CW\*(C`HKEY_LOCAL_MACHINE\eSoftware\ePerl\*(C'\fR.  One or more of the following entries
+(of type REG_SZ or REG_EXPAND_SZ) may be set in the keys:
+.Sp
+.Vb 7
+\& lib\-$]        version\-specific standard library path to add to @INC
+\& lib           standard library path to add to @INC
+\& sitelib\-$]    version\-specific site library path to add to @INC
+\& sitelib       site library path to add to @INC
+\& vendorlib\-$]  version\-specific vendor library path to add to @INC
+\& vendorlib     vendor library path to add to @INC
+\& PERL*         fallback for all %ENV lookups that begin with "PERL"
+.Ve
+.Sp
+Note the \f(CW$]\fR in the above is not literal.  Substitute whatever version
+of perl you want to honor that entry, e.g. \f(CW5.6.0\fR.  Paths must be
+separated with semicolons, as usual on Windows.
+.IP "File Globbing" 4
+.IX Item "File Globbing"
+By default, perl handles file globbing using the File::Glob extension,
+which provides portable globbing.
+.Sp
+If you want perl to use globbing that emulates the quirks of DOS
+filename conventions, you might want to consider using File::DosGlob
+to override the internal \fBglob()\fR implementation.  See File::DosGlob for
+details.
+.IP "Using perl from the command line" 4
+.IX Item "Using perl from the command line"
+If you are accustomed to using perl from various command-line
+shells found in UNIX environments, you will be less than pleased
+with what Windows offers by way of a command shell.
+.Sp
+The crucial thing to understand about the Windows environment is that
+the command line you type in is processed twice before Perl sees it.
+First, your command shell (usually CMD.EXE) preprocesses the command
+line, to handle redirection, environment variable expansion, and
+location of the executable to run. Then, the perl executable splits
+the remaining command line into individual arguments, using the
+C runtime library upon which Perl was built.
+.Sp
+It is particularly important to note that neither the shell nor the C
+runtime do any wildcard expansions of command-line arguments (so
+wildcards need not be quoted).  Also, the quoting behaviours of the
+shell and the C runtime are rudimentary at best (and may, if you are
+using a non-standard shell, be inconsistent).  The only (useful) quote
+character is the double quote (").  It can be used to protect spaces
+and other special characters in arguments.
+.Sp
+The Windows documentation describes the shell parsing rules here:
+<https://docs.microsoft.com/en\-us/windows\-server/administration/windows\-commands/cmd>
+and the C runtime parsing rules here:
+<https://msdn.microsoft.com/en\-us/library/17w5ykft%28v=VS.100%29.aspx>.
+.Sp
+Here are some further observations based on experiments: The C runtime
+breaks arguments at spaces and passes them to programs in argc/argv.
+Double quotes can be used to prevent arguments with spaces in them from
+being split up.  You can put a double quote in an argument by escaping
+it with a backslash and enclosing the whole argument within double quotes.
+The backslash and the pair of double quotes surrounding the argument will
+be stripped by the C runtime.
+.Sp
+The file redirection characters "<", ">", and "|" can be quoted by
+double quotes (although there are suggestions that this may not always
+be true).  Single quotes are not treated as quotes by the shell or
+the C runtime, they don't get stripped by the shell (just to make
+this type of quoting completely useless).  The caret "^" has also
+been observed to behave as a quoting character, but this appears
+to be a shell feature, and the caret is not stripped from the command
+line, so Perl still sees it (and the C runtime phase does not treat
+the caret as a quote character).
+.Sp
+Here are some examples of usage of the "cmd" shell:
+.Sp
+This prints two doublequotes:
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aq\e"\e"\*(Aq "
+.Ve
+.Sp
+This does the same:
+.Sp
+.Vb 1
+\&    perl \-e "print \e"\e\e\e"\e\e\e"\e" "
+.Ve
+.Sp
+This prints "bar" and writes "foo" to the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" > blurch
+.Ve
+.Sp
+This prints "foo" ("bar" disappears into nowhereland):
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2> nul
+.Ve
+.Sp
+This prints "bar" and writes "foo" into the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 1> blurch
+.Ve
+.Sp
+This pipes "foo" to the "less" pager and prints "bar" on the console:
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" | less
+.Ve
+.Sp
+This pipes "foo\enbar\en" to the less pager:
+.Sp
+.Vb 1
+\&    perl \-le "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2>&1 | less
+.Ve
+.Sp
+This pipes "foo" to the pager and writes "bar" in the file "blurch":
+.Sp
+.Vb 1
+\&    perl \-e "print \*(Aqfoo\*(Aq; print STDERR \*(Aqbar\*(Aq" 2> blurch | less
+.Ve
+.Sp
+Discovering the usefulness of the "command.com" shell on Windows 9x
+is left as an exercise to the reader :)
+.Sp
+One particularly pernicious problem with the 4NT command shell for
+Windows is that it (nearly) always treats a % character as indicating
+that environment variable expansion is needed.  Under this shell, it is
+therefore important to always double any % characters which you want
+Perl to see (for example, for hash variables), even when they are
+quoted.
+.IP "Building Extensions" 4
+.IX Item "Building Extensions"
+The Comprehensive Perl Archive Network (CPAN) offers a wealth
+of extensions, some of which require a C compiler to build.
+Look in <https://www.cpan.org/> for more information on CPAN.
+.Sp
+Note that not all of the extensions available from CPAN may work
+in the Windows environment; you should check the information at
+<https://www.cpantesters.org/> before investing too much effort into
+porting modules that don't readily build.
+.Sp
+Most extensions (whether they require a C compiler or not) can
+be built, tested and installed with the standard mantra:
+.Sp
+.Vb 4
+\&    perl Makefile.PL
+\&    $MAKE
+\&    $MAKE test
+\&    $MAKE install
+.Ve
+.Sp
+where \f(CW$MAKE\fR is whatever 'make' program you have configured perl to
+use.  Use "perl \-V:make" to find out what this is.  Some extensions
+may not provide a testsuite (so "$MAKE test" may not do anything or
+fail), but most serious ones do.
+.Sp
+It is important that you use a supported 'make' program, and
+ensure Config.pm knows about it.
+.Sp
+Note that MakeMaker actually emits makefiles with different syntax
+depending on what 'make' it thinks you are using.  Therefore, it is
+important that one of the following values appears in Config.pm:
+.Sp
+.Vb 3
+\&    make=\*(Aqnmake\*(Aq        # MakeMaker emits nmake syntax
+\&    any other value     # MakeMaker emits generic make syntax
+\&                            (e.g GNU make, or Perl make)
+.Ve
+.Sp
+If the value doesn't match the 'make' program you want to use,
+edit Config.pm to fix it.
+.Sp
+If a module implements XSUBs, you will need one of the supported
+C compilers.  You must make sure you have set up the environment for
+the compiler for command-line compilation before running \f(CW\*(C`perl Makefile.PL\*(C'\fR
+or any invocation of make.
+.Sp
+If a module does not build for some reason, look carefully for
+why it failed, and report problems to the module author.  If
+it looks like the extension building support is at fault, report
+that with full details of how the build failed using the GitHub
+issue tracker at <https://github.com/Perl/perl5/issues>.
+.IP "Command-line Wildcard Expansion" 4
+.IX Item "Command-line Wildcard Expansion"
+The default command shells on DOS descendant operating systems (such
+as they are) usually do not expand wildcard arguments supplied to
+programs.  They consider it the application's job to handle that.
+This is commonly achieved by linking the application (in our case,
+perl) with startup code that the C runtime libraries usually provide.
+However, doing that results in incompatible perl versions (since the
+behavior of the argv expansion code differs depending on the
+compiler, and it is even buggy on some compilers).  Besides, it may
+be a source of frustration if you use such a perl binary with an
+alternate shell that *does* expand wildcards.
+.Sp
+Instead, the following solution works rather well. The nice things
+about it are 1) you can start using it right away; 2) it is more
+powerful, because it will do the right thing with a pattern like
+*/*/*.c; 3) you can decide whether you do/don't want to use it; and
+4) you can extend the method to add any customizations (or even
+entirely different kinds of wildcard expansion).
+.Sp
+.Vb 10
+\& C:\e> copy con c:\eperl\elib\eWild.pm
+\& # Wild.pm \- emulate shell @ARGV expansion on shells that don\*(Aqt
+\& use File::DosGlob;
+\& @ARGV = map {
+\&              my @g = File::DosGlob::glob($_) if /[*?]/;
+\&              @g ? @g : $_;
+\&            } @ARGV;
+\& 1;
+\& ^Z
+\& C:\e> set PERL5OPT=\-MWild
+\& C:\e> perl \-le "for (@ARGV) { print }" */*/perl*.c
+\& p4view/perl/perl.c
+\& p4view/perl/perlio.c
+\& p4view/perl/perly.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+\& perl5.005/win32/perlglob.c
+\& perl5.005/win32/perllib.c
+.Ve
+.Sp
+Note there are two distinct steps there: 1) You'll have to create
+Wild.pm and put it in your perl lib directory. 2) You'll need to
+set the PERL5OPT environment variable.  If you want argv expansion
+to be the default, just set PERL5OPT in your default startup
+environment.
+.Sp
+If you are using the Visual C compiler, you can get the C runtime's
+command line wildcard expansion built into perl binary.  The resulting
+binary will always expand unquoted command lines, which may not be
+what you want if you use a shell that does that for you.  The expansion
+done is also somewhat less powerful than the approach suggested above.
+.IP "Notes on 64\-bit Windows" 4
+.IX Item "Notes on 64-bit Windows"
+Windows .NET Server supports the LLP64 data model on the Intel Itanium
+architecture.
+.Sp
+The LLP64 data model is different from the LP64 data model that is the
+norm on 64\-bit Unix platforms.  In the former, \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`long\*(C'\fR are
+both 32\-bit data types, while pointers are 64 bits wide.  In addition,
+there is a separate 64\-bit wide integral type, \f(CW\*(C`_\|_int64\*(C'\fR.  In contrast,
+the LP64 data model that is pervasive on Unix platforms provides \f(CW\*(C`int\*(C'\fR
+as the 32\-bit type, while both the \f(CW\*(C`long\*(C'\fR type and pointers are of
+64\-bit precision.  Note that both models provide for 64\-bits of
+addressability.
+.Sp
+64\-bit Windows running on Itanium is capable of running 32\-bit x86
+binaries transparently.  This means that you could use a 32\-bit build
+of Perl on a 64\-bit system.  Given this, why would one want to build
+a 64\-bit build of Perl?  Here are some reasons why you would bother:
+.RS 4
+.IP \(bu 4
+A 64\-bit native application will run much more efficiently on
+Itanium hardware.
+.IP \(bu 4
+There is no 2GB limit on process size.
+.IP \(bu 4
+Perl automatically provides large file support when built under
+64\-bit Windows.
+.IP \(bu 4
+Embedding Perl inside a 64\-bit application.
+.RE
+.RS 4
+.RE
+.SS "Running Perl Scripts"
+.IX Subsection "Running Perl Scripts"
+Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
+indicate to the OS that it should execute the file using perl.
+Windows has no comparable means to indicate arbitrary files are
+executables.
+.PP
+Instead, all available methods to execute plain text files on
+Windows rely on the file "extension".  There are three methods
+to use this to execute perl scripts:
+.IP 1. 8
+There is a facility called "file extension associations".  This can be
+manipulated via the two commands "assoc" and "ftype" that come
+standard with Windows.  Type "ftype /?" for a complete example of how
+to set this up for perl scripts (Say what?  You thought Windows
+wasn't perl-ready? :).
+.IP 2. 8
+Since file associations don't work everywhere, and there are
+reportedly bugs with file associations where it does work, the
+old method of wrapping the perl script to make it look like a
+regular batch file to the OS, may be used.  The install process
+makes available the "pl2bat.bat" script which can be used to wrap
+perl scripts into batch files.  For example:
+.Sp
+.Vb 1
+\&        pl2bat foo.pl
+.Ve
+.Sp
+will create the file "FOO.BAT".  Note "pl2bat" strips any
+\&.pl suffix and adds a .bat suffix to the generated file.
+.Sp
+If you use the 4DOS/NT or similar command shell, note that
+"pl2bat" uses the "%*" variable in the generated batch file to
+refer to all the command line arguments, so you may need to make
+sure that construct works in batch files.  As of this writing,
+4DOS/NT users will need a "ParameterChar = *" statement in their
+4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
+startup file to enable this to work.
+.IP 3. 8
+Using "pl2bat" has a few problems:  the file name gets changed,
+so scripts that rely on \f(CW$0\fR to find what they must do may not
+run properly; running "pl2bat" replicates the contents of the
+original script, and so this process can be maintenance intensive
+if the originals get updated often.  A different approach that
+avoids both problems is possible.
+.Sp
+A script called "runperl.bat" is available that can be copied
+to any filename (along with the .bat suffix).  For example,
+if you call it "foo.bat", it will run the file "foo" when it is
+executed.  Since you can run batch files on Windows platforms simply
+by typing the name (without the extension), this effectively
+runs the file "foo", when you type either "foo" or "foo.bat".
+With this method, "foo.bat" can even be in a different location
+than the file "foo", as long as "foo" is available somewhere on
+the PATH.  If your scripts are on a filesystem that allows symbolic
+links, you can even avoid copying "runperl.bat".
+.Sp
+Here's a diversion:  copy "runperl.bat" to "runperl", and type
+"runperl".  Explain the observed behavior, or lack thereof. :)
+Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
+.SS "Miscellaneous Things"
+.IX Subsection "Miscellaneous Things"
+A full set of HTML documentation is installed, so you should be
+able to use it if you have a web browser installed on your
+system.
+.PP
+\&\f(CW\*(C`perldoc\*(C'\fR is also a useful tool for browsing information contained
+in the documentation, especially in conjunction with a pager
+like \f(CW\*(C`less\*(C'\fR (recent versions of which have Windows support).  You may
+have to set the PAGER environment variable to use a specific pager.
+"perldoc \-f foo" will print information about the perl operator
+"foo".
+.PP
+One common mistake when using this port with a GUI library like \f(CW\*(C`Tk\*(C'\fR
+is assuming that Perl's normal behavior of opening a command-line
+window will go away.  This isn't the case.  If you want to start a copy
+of \f(CW\*(C`perl\*(C'\fR without opening a command-line window, use the \f(CW\*(C`wperl\*(C'\fR
+executable built during the installation process.  Usage is exactly
+the same as normal \f(CW\*(C`perl\*(C'\fR on Windows, except that options like \f(CW\*(C`\-h\*(C'\fR
+don't work (since they need a command-line window to print to).
+.PP
+If you find bugs in perl, you can report them to
+<https://github.com/Perl/perl5/issues>.
+.SH "BUGS AND CAVEATS"
+.IX Header "BUGS AND CAVEATS"
+Norton AntiVirus interferes with the build process, particularly if
+set to "AutoProtect, All Files, when Opened". Unlike large applications
+the perl build process opens and modifies a lot of files. Having the
+AntiVirus scan each and every one slows build the process significantly.
+Worse, with PERLIO=stdio the build process fails with peculiar messages
+as the virus checker interacts badly with miniperl.exe writing configure
+files (it seems to either catch file part written and treat it as suspicious,
+or virus checker may have it "locked" in a way which inhibits miniperl
+updating it). The build does complete with
+.PP
+.Vb 1
+\&   set PERLIO=perlio
+.Ve
+.PP
+but that may be just luck. Other AntiVirus software may have similar issues.
+.PP
+A git GUI shell extension for Windows such as TortoiseGit will cause the build
+and later \f(CW\*(C`make test\*(C'\fR to run much slower since every file is checked for its
+git status as soon as it is created and/or modified. TortoiseGit doesn't cause
+any test failures or build problems unlike the antivirus software described
+above, but it does cause similar slowness. It is suggested to use Task Manager
+to look for background processes which use high CPU amounts during the building
+process.
+.PP
+Some of the built-in functions do not act exactly as documented in
+perlfunc, and a few are not implemented at all.  To avoid
+surprises, particularly if you have had prior exposure to Perl
+in other operating environments or if you intend to write code
+that will be portable to other environments, see perlport
+for a reasonably definitive list of these differences.
+.PP
+Not all extensions available from CPAN may build or work properly
+in the Windows environment.  See "Building Extensions".
+.PP
+Most \f(CWsocket()\fR related calls are supported, but they may not
+behave as on Unix platforms.  See perlport for the full list.
+.PP
+Signal handling may not behave as on Unix platforms (where it
+doesn't exactly "behave", either :).  For instance, calling \f(CWdie()\fR
+or \f(CWexit()\fR from signal handlers will cause an exception, since most
+implementations of \f(CWsignal()\fR on Windows are severely crippled.
+Thus, signals may work only for simple things like setting a flag
+variable in the handler.  Using signals under this port should
+currently be considered unsupported.
+.PP
+Please report detailed descriptions of any problems and solutions that
+you may find at <<https://github.com/Perl/perl5/issues>>,
+along with the output produced by \f(CW\*(C`perl \-V\*(C'\fR.
+.SH ACKNOWLEDGEMENTS
+.IX Header "ACKNOWLEDGEMENTS"
+The use of a camel with the topic of Perl is a trademark
+of O'Reilly and Associates, Inc. Used with permission.
+.SH AUTHORS
+.IX Header "AUTHORS"
+.IP "Gary Ng <71564.1743@CompuServe.COM>" 4
+.IX Item "Gary Ng <71564.1743@CompuServe.COM>"
+.PD 0
+.IP "Gurusamy Sarathy <gsar@activestate.com>" 4
+.IX Item "Gurusamy Sarathy <gsar@activestate.com>"
+.IP "Nick Ing-Simmons <nick@ing\-simmons.net>" 4
+.IX Item "Nick Ing-Simmons <nick@ing-simmons.net>"
+.IP "Jan Dubois <jand@activestate.com>" 4
+.IX Item "Jan Dubois <jand@activestate.com>"
+.IP "Steve Hay <steve.m.hay@googlemail.com>" 4
+.IX Item "Steve Hay <steve.m.hay@googlemail.com>"
+.PD
+.PP
+This document is maintained by Jan Dubois.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perl
+.SH HISTORY
+.IX Header "HISTORY"
+This port was originally contributed by Gary Ng around 5.003_24,
+and borrowed from the Hip Communications port that was available
+at the time.  Various people have made numerous and sundry hacks
+since then.
+.PP
+GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
+.PP
+Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
+.PP
+Support for \fBfork()\fR emulation was added in 5.6 (ActiveState Tool Corp).
+.PP
+Win9x support was added in 5.6 (Benjamin Stuhl).
+.PP
+Support for 64\-bit Windows added in 5.8 (ActiveState Corp).
+.PP
+Last updated: 06 October 2021
diff --git a/upstream/mageia-cauldron/man1/perlxs.1 b/upstream/mageia-cauldron/man1/perlxs.1
new file mode 100644
index 00000000..4445c22a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlxs.1
@@ -0,0 +1,2656 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLXS 1"
+.TH PERLXS 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlxs \- XS language reference manual
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS Introduction
+.IX Subsection "Introduction"
+XS is an interface description file format used to create an extension
+interface between Perl and C code (or a C library) which one wishes
+to use with Perl.  The XS interface is combined with the library to
+create a new library which can then be either dynamically loaded
+or statically linked into perl.  The XS interface description is
+written in the XS language and is the core component of the Perl
+extension interface.
+.PP
+Before writing XS, read the "CAVEATS" section below.
+.PP
+An \fBXSUB\fR forms the basic unit of the XS interface.  After compilation
+by the \fBxsubpp\fR compiler, each XSUB amounts to a C function definition
+which will provide the glue between Perl calling conventions and C
+calling conventions.
+.PP
+The glue code pulls the arguments from the Perl stack, converts these
+Perl values to the formats expected by a C function, calls this C function,
+and then transfers the return values of the C function back to Perl.
+Return values here may be a conventional C return value or any C
+function arguments that may serve as output parameters.  These return
+values may be passed back to Perl either by putting them on the
+Perl stack, or by modifying the arguments supplied from the Perl side.
+.PP
+The above is a somewhat simplified view of what really happens.  Since
+Perl allows more flexible calling conventions than C, XSUBs may do much
+more in practice, such as checking input parameters for validity,
+throwing exceptions (or returning undef/empty list) if the return value
+from the C function indicates failure, calling different C functions
+based on numbers and types of the arguments, providing an object-oriented
+interface, etc.
+.PP
+Of course, one could write such glue code directly in C.  However, this
+would be a tedious task, especially if one needs to write glue for
+multiple C functions, and/or one is not familiar enough with the Perl
+stack discipline and other such arcana.  XS comes to the rescue here:
+instead of writing this glue C code in long-hand, one can write
+a more concise short-hand \fIdescription\fR of what should be done by
+the glue, and let the XS compiler \fBxsubpp\fR handle the rest.
+.PP
+The XS language allows one to describe the mapping between how the C
+routine is used, and how the corresponding Perl routine is used.  It
+also allows creation of Perl routines which are directly translated to
+C code and which are not related to a pre-existing C function.  In cases
+when the C interface coincides with the Perl interface, the XSUB
+declaration is almost identical to a declaration of a C function (in K&R
+style).  In such circumstances, there is another tool called \f(CW\*(C`h2xs\*(C'\fR
+that is able to translate an entire C header file into a corresponding
+XS file that will provide glue to the functions/macros described in
+the header file.
+.PP
+The XS compiler is called \fBxsubpp\fR.  This compiler creates
+the constructs necessary to let an XSUB manipulate Perl values, and
+creates the glue necessary to let Perl call the XSUB.  The compiler
+uses \fBtypemaps\fR to determine how to map C function parameters
+and output values to Perl values and back.  The default typemap
+(which comes with Perl) handles many common C types.  A supplementary
+typemap may also be needed to handle any special structures and types
+for the library being linked. For more information on typemaps,
+see perlxstypemap.
+.PP
+A file in XS format starts with a C language section which goes until the
+first \f(CW\*(C`MODULE =\*(C'\fR directive.  Other XS directives and XSUB definitions
+may follow this line.  The "language" used in this part of the file
+is usually referred to as the XS language.  \fBxsubpp\fR recognizes and
+skips POD (see perlpod) in both the C and XS language sections, which
+allows the XS file to contain embedded documentation.
+.PP
+See perlxstut for a tutorial on the whole extension creation process.
+.PP
+Note: For some extensions, Dave Beazley's SWIG system may provide a
+significantly more convenient mechanism for creating the extension
+glue code.  See <http://www.swig.org/> for more information.
+.PP
+For simple bindings to C libraries as well as other machine code libraries,
+consider instead using the much simpler
+libffi <http://sourceware.org/libffi/> interface via CPAN modules like
+FFI::Platypus or FFI::Raw.
+.SS "On The Road"
+.IX Subsection "On The Road"
+Many of the examples which follow will concentrate on creating an interface
+between Perl and the ONC+ RPC bind library functions.  The \fBrpcb_gettime()\fR
+function is used to demonstrate many features of the XS language.  This
+function has two parameters; the first is an input parameter and the second
+is an output parameter.  The function also returns a status value.
+.PP
+.Vb 1
+\&        bool_t rpcb_gettime(const char *host, time_t *timep);
+.Ve
+.PP
+From C this function will be called with the following
+statements.
+.PP
+.Vb 4
+\&     #include <rpc/rpc.h>
+\&     bool_t status;
+\&     time_t timep;
+\&     status = rpcb_gettime( "localhost", &timep );
+.Ve
+.PP
+If an XSUB is created to offer a direct translation between this function
+and Perl, then this XSUB will be used from Perl with the following code.
+The \f(CW$status\fR and \f(CW$timep\fR variables will contain the output of the function.
+.PP
+.Vb 2
+\&     use RPC;
+\&     $status = rpcb_gettime( "localhost", $timep );
+.Ve
+.PP
+The following XS file shows an XS subroutine, or XSUB, which
+demonstrates one possible interface to the \fBrpcb_gettime()\fR
+function.  This XSUB represents a direct translation between
+C and Perl and so preserves the interface even from Perl.
+This XSUB will be invoked from Perl with the usage shown
+above.  Note that the first three #include statements, for
+\&\f(CW\*(C`EXTERN.h\*(C'\fR, \f(CW\*(C`perl.h\*(C'\fR, and \f(CW\*(C`XSUB.h\*(C'\fR, will always be present at the
+beginning of an XS file.  This approach and others will be
+expanded later in this document.  A #define for \f(CW\*(C`PERL_NO_GET_CONTEXT\*(C'\fR
+should be present to fetch the interpreter context more efficiently,
+see perlguts for details.
+.PP
+.Vb 5
+\&     #define PERL_NO_GET_CONTEXT
+\&     #include "EXTERN.h"
+\&     #include "perl.h"
+\&     #include "XSUB.h"
+\&     #include <rpc/rpc.h>
+\&
+\&     MODULE = RPC  PACKAGE = RPC
+\&
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+Any extension to Perl, including those containing XSUBs,
+should have a Perl module to serve as the bootstrap which
+pulls the extension into Perl.  This module will export the
+extension's functions and variables to the Perl program and
+will cause the extension's XSUBs to be linked into Perl.
+The following module will be used for most of the examples
+in this document and should be used from Perl with the \f(CW\*(C`use\*(C'\fR
+command as shown earlier.  Perl modules are explained in
+more detail later in this document.
+.PP
+.Vb 1
+\&     package RPC;
+\&
+\&     require Exporter;
+\&     require DynaLoader;
+\&     @ISA = qw(Exporter DynaLoader);
+\&     @EXPORT = qw( rpcb_gettime );
+\&
+\&     bootstrap RPC;
+\&     1;
+.Ve
+.PP
+Throughout this document a variety of interfaces to the \fBrpcb_gettime()\fR
+XSUB will be explored.  The XSUBs will take their parameters in different
+orders or will take different numbers of parameters.  In each case the
+XSUB is an abstraction between Perl and the real C \fBrpcb_gettime()\fR
+function, and the XSUB must always ensure that the real \fBrpcb_gettime()\fR
+function is called with the correct parameters.  This abstraction will
+allow the programmer to create a more Perl-like interface to the C
+function.
+.SS "The Anatomy of an XSUB"
+.IX Subsection "The Anatomy of an XSUB"
+The simplest XSUBs consist of 3 parts: a description of the return
+value, the name of the XSUB routine and the names of its arguments,
+and a description of types or formats of the arguments.
+.PP
+The following XSUB allows a Perl program to access a C library function
+called \fBsin()\fR.  The XSUB will imitate the C function which takes a single
+argument and returns a single value.
+.PP
+.Vb 3
+\&     double
+\&     sin(x)
+\&       double x
+.Ve
+.PP
+Optionally, one can merge the description of types and the list of
+argument names, rewriting this as
+.PP
+.Vb 2
+\&     double
+\&     sin(double x)
+.Ve
+.PP
+This makes this XSUB look similar to an ANSI C declaration.  An optional
+semicolon is allowed after the argument list, as in
+.PP
+.Vb 2
+\&     double
+\&     sin(double x);
+.Ve
+.PP
+Parameters with C pointer types can have different semantic: C functions
+with similar declarations
+.PP
+.Vb 2
+\&     bool string_looks_as_a_number(char *s);
+\&     bool make_char_uppercase(char *c);
+.Ve
+.PP
+are used in absolutely incompatible manner.  Parameters to these functions
+could be described to \fBxsubpp\fR like this:
+.PP
+.Vb 2
+\&     char *  s
+\&     char    &c
+.Ve
+.PP
+Both these XS declarations correspond to the \f(CW\*(C`char*\*(C'\fR C type, but they have
+different semantics, see "The & Unary Operator".
+.PP
+It is convenient to think that the indirection operator
+\&\f(CW\*(C`*\*(C'\fR should be considered as a part of the type and the address operator \f(CW\*(C`&\*(C'\fR
+should be considered part of the variable.  See perlxstypemap
+for more info about handling qualifiers and unary operators in C types.
+.PP
+The function name and the return type must be placed on
+separate lines and should be flush left-adjusted.
+.PP
+.Vb 1
+\&  INCORRECT                        CORRECT
+\&
+\&  double sin(x)                    double
+\&    double x                       sin(x)
+\&                                     double x
+.Ve
+.PP
+The rest of the function description may be indented or left-adjusted. The
+following example shows a function with its body left-adjusted.  Most
+examples in this document will indent the body for better readability.
+.PP
+.Vb 1
+\&  CORRECT
+\&
+\&  double
+\&  sin(x)
+\&  double x
+.Ve
+.PP
+More complicated XSUBs may contain many other sections.  Each section of
+an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
+However, the first two lines of an XSUB always contain the same data:
+descriptions of the return type and the names of the function and its
+parameters.  Whatever immediately follows these is considered to be
+an INPUT: section unless explicitly marked with another keyword.
+(See "The INPUT: Keyword".)
+.PP
+An XSUB section continues until another section-start keyword is found.
+.SS "The Argument Stack"
+.IX Subsection "The Argument Stack"
+The Perl argument stack is used to store the values which are
+sent as parameters to the XSUB and to store the XSUB's
+return value(s).  In reality all Perl functions (including non-XSUB
+ones) keep their values on this stack all the same time, each limited
+to its own range of positions on the stack.  In this document the
+first position on that stack which belongs to the active
+function will be referred to as position 0 for that function.
+.PP
+XSUBs refer to their stack arguments with the macro \fBST(x)\fR, where \fIx\fR
+refers to a position in this XSUB's part of the stack.  Position 0 for that
+function would be known to the XSUB as \fBST\fR\|(0).  The XSUB's incoming
+parameters and outgoing return values always begin at \fBST\fR\|(0).  For many
+simple cases the \fBxsubpp\fR compiler will generate the code necessary to
+handle the argument stack by embedding code fragments found in the
+typemaps.  In more complex cases the programmer must supply the code.
+.SS "The RETVAL Variable"
+.IX Subsection "The RETVAL Variable"
+The RETVAL variable is a special C variable that is declared automatically
+for you.  The C type of RETVAL matches the return type of the C library
+function.  The \fBxsubpp\fR compiler will declare this variable in each XSUB
+with non\-\f(CW\*(C`void\*(C'\fR return type.  By default the generated C function
+will use RETVAL to hold the return value of the C library function being
+called.  In simple cases the value of RETVAL will be placed in \fBST\fR\|(0) of
+the argument stack where it can be received by Perl as the return value
+of the XSUB.
+.PP
+If the XSUB has a return type of \f(CW\*(C`void\*(C'\fR then the compiler will
+not declare a RETVAL variable for that function.  When using
+a PPCODE: section no manipulation of the RETVAL variable is required, the
+section may use direct stack manipulation to place output values on the stack.
+.PP
+If PPCODE: directive is not used, \f(CW\*(C`void\*(C'\fR return value should be used
+only for subroutines which do not return a value, \fIeven if\fR CODE:
+directive is used which sets \fBST\fR\|(0) explicitly.
+.PP
+Older versions of this document recommended to use \f(CW\*(C`void\*(C'\fR return
+value in such cases. It was discovered that this could lead to
+segfaults in cases when XSUB was \fItruly\fR \f(CW\*(C`void\*(C'\fR. This practice is
+now deprecated, and may be not supported at some future version. Use
+the return value \f(CW\*(C`SV *\*(C'\fR in such cases. (Currently \f(CW\*(C`xsubpp\*(C'\fR contains
+some heuristic code which tries to disambiguate between "truly-void"
+and "old-practice-declared-as-void" functions. Hence your code is at
+mercy of this heuristics unless you use \f(CW\*(C`SV *\*(C'\fR as return value.)
+.SS "Returning SVs, AVs and HVs through RETVAL"
+.IX Subsection "Returning SVs, AVs and HVs through RETVAL"
+When you're using RETVAL to return an \f(CW\*(C`SV *\*(C'\fR, there's some magic
+going on behind the scenes that should be mentioned. When you're
+manipulating the argument stack using the ST(x) macro, for example,
+you usually have to pay special attention to reference counts. (For
+more about reference counts, see perlguts.) To make your life
+easier, the typemap file automatically makes \f(CW\*(C`RETVAL\*(C'\fR mortal when
+you're returning an \f(CW\*(C`SV *\*(C'\fR. Thus, the following two XSUBs are more
+or less equivalent:
+.PP
+.Vb 6
+\&  void
+\&  alpha()
+\&      PPCODE:
+\&          ST(0) = newSVpv("Hello World",0);
+\&          sv_2mortal(ST(0));
+\&          XSRETURN(1);
+\&
+\&  SV *
+\&  beta()
+\&      CODE:
+\&          RETVAL = newSVpv("Hello World",0);
+\&      OUTPUT:
+\&          RETVAL
+.Ve
+.PP
+This is quite useful as it usually improves readability. While
+this works fine for an \f(CW\*(C`SV *\*(C'\fR, it's unfortunately not as easy
+to have \f(CW\*(C`AV *\*(C'\fR or \f(CW\*(C`HV *\*(C'\fR as a return value. You \fIshould\fR be
+able to write:
+.PP
+.Vb 7
+\&  AV *
+\&  array()
+\&      CODE:
+\&          RETVAL = newAV();
+\&          /* do something with RETVAL */
+\&      OUTPUT:
+\&          RETVAL
+.Ve
+.PP
+But due to an unfixable bug (fixing it would break lots of existing
+CPAN modules) in the typemap file, the reference count of the \f(CW\*(C`AV *\*(C'\fR
+is not properly decremented. Thus, the above XSUB would leak memory
+whenever it is being called. The same problem exists for \f(CW\*(C`HV *\*(C'\fR,
+\&\f(CW\*(C`CV *\*(C'\fR, and \f(CW\*(C`SVREF\*(C'\fR (which indicates a scalar reference, not
+a general \f(CW\*(C`SV *\*(C'\fR).
+In XS code on perls starting with perl 5.16, you can override the
+typemaps for any of these types with a version that has proper
+handling of refcounts. In your \f(CW\*(C`TYPEMAP\*(C'\fR section, do
+.PP
+.Vb 1
+\&  AV*   T_AVREF_REFCOUNT_FIXED
+.Ve
+.PP
+to get the repaired variant. For backward compatibility with older
+versions of perl, you can instead decrement the reference count
+manually when you're returning one of the aforementioned
+types using \f(CW\*(C`sv_2mortal\*(C'\fR:
+.PP
+.Vb 8
+\&  AV *
+\&  array()
+\&      CODE:
+\&          RETVAL = newAV();
+\&          sv_2mortal((SV*)RETVAL);
+\&          /* do something with RETVAL */
+\&      OUTPUT:
+\&          RETVAL
+.Ve
+.PP
+Remember that you don't have to do this for an \f(CW\*(C`SV *\*(C'\fR. The reference
+documentation for all core typemaps can be found in perlxstypemap.
+.SS "The MODULE Keyword"
+.IX Subsection "The MODULE Keyword"
+The MODULE keyword is used to start the XS code and to specify the package
+of the functions which are being defined.  All text preceding the first
+MODULE keyword is considered C code and is passed through to the output with
+POD stripped, but otherwise untouched.  Every XS module will have a
+bootstrap function which is used to hook the XSUBs into Perl.  The package
+name of this bootstrap function will match the value of the last MODULE
+statement in the XS source files.  The value of MODULE should always remain
+constant within the same XS file, though this is not required.
+.PP
+The following example will start the XS code and will place
+all functions in a package named RPC.
+.PP
+.Vb 1
+\&     MODULE = RPC
+.Ve
+.SS "The PACKAGE Keyword"
+.IX Subsection "The PACKAGE Keyword"
+When functions within an XS source file must be separated into packages
+the PACKAGE keyword should be used.  This keyword is used with the MODULE
+keyword and must follow immediately after it when used.
+.PP
+.Vb 1
+\&     MODULE = RPC  PACKAGE = RPC
+\&
+\&     [ XS code in package RPC ]
+\&
+\&     MODULE = RPC  PACKAGE = RPCB
+\&
+\&     [ XS code in package RPCB ]
+\&
+\&     MODULE = RPC  PACKAGE = RPC
+\&
+\&     [ XS code in package RPC ]
+.Ve
+.PP
+The same package name can be used more than once, allowing for
+non-contiguous code. This is useful if you have a stronger ordering
+principle than package names.
+.PP
+Although this keyword is optional and in some cases provides redundant
+information it should always be used.  This keyword will ensure that the
+XSUBs appear in the desired package.
+.SS "The PREFIX Keyword"
+.IX Subsection "The PREFIX Keyword"
+The PREFIX keyword designates prefixes which should be
+removed from the Perl function names.  If the C function is
+\&\f(CWrpcb_gettime()\fR and the PREFIX value is \f(CW\*(C`rpcb_\*(C'\fR then Perl will
+see this function as \f(CWgettime()\fR.
+.PP
+This keyword should follow the PACKAGE keyword when used.
+If PACKAGE is not used then PREFIX should follow the MODULE
+keyword.
+.PP
+.Vb 1
+\&     MODULE = RPC  PREFIX = rpc_
+\&
+\&     MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
+.Ve
+.SS "The OUTPUT: Keyword"
+.IX Subsection "The OUTPUT: Keyword"
+The OUTPUT: keyword indicates that certain function parameters should be
+updated (new values made visible to Perl) when the XSUB terminates or that
+certain values should be returned to the calling Perl function.  For
+simple functions which have no CODE: or PPCODE: section,
+such as the \fBsin()\fR function above, the RETVAL variable is
+automatically designated as an output value.  For more complex functions
+the \fBxsubpp\fR compiler will need help to determine which variables are output
+variables.
+.PP
+This keyword will normally be used to complement the CODE: keyword.
+The RETVAL variable is not recognized as an output variable when the
+CODE: keyword is present.  The OUTPUT: keyword is used in this
+situation to tell the compiler that RETVAL really is an output
+variable.
+.PP
+The OUTPUT: keyword can also be used to indicate that function parameters
+are output variables.  This may be necessary when a parameter has been
+modified within the function and the programmer would like the update to
+be seen by Perl.
+.PP
+.Vb 6
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+The OUTPUT: keyword will also allow an output parameter to
+be mapped to a matching piece of code rather than to a
+typemap.
+.PP
+.Vb 6
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        OUTPUT:
+\&          timep sv_setnv(ST(1), (double)timep);
+.Ve
+.PP
+\&\fBxsubpp\fR emits an automatic \f(CWSvSETMAGIC()\fR for all parameters in the
+OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
+behavior, as it takes care of properly invoking 'set' magic on output
+parameters (needed for hash or array element parameters that must be
+created if they didn't exist).  If for some reason, this behavior is
+not desired, the OUTPUT section may contain a \f(CW\*(C`SETMAGIC: DISABLE\*(C'\fR line
+to disable it for the remainder of the parameters in the OUTPUT section.
+Likewise, \f(CW\*(C`SETMAGIC: ENABLE\*(C'\fR can be used to reenable it for the
+remainder of the OUTPUT section.  See perlguts for more details
+about 'set' magic.
+.SS "The NO_OUTPUT Keyword"
+.IX Subsection "The NO_OUTPUT Keyword"
+The NO_OUTPUT can be placed as the first token of the XSUB.  This keyword
+indicates that while the C subroutine we provide an interface to has
+a non\-\f(CW\*(C`void\*(C'\fR return type, the return value of this C subroutine should not
+be returned from the generated Perl subroutine.
+.PP
+With this keyword present "The RETVAL Variable" is created, and in the
+generated call to the subroutine this variable is assigned to, but the value
+of this variable is not going to be used in the auto-generated code.
+.PP
+This keyword makes sense only if \f(CW\*(C`RETVAL\*(C'\fR is going to be accessed by the
+user-supplied code.  It is especially useful to make a function interface
+more Perl-like, especially when the C return value is just an error condition
+indicator.  For example,
+.PP
+.Vb 5
+\&  NO_OUTPUT int
+\&  delete_file(char *name)
+\&    POSTCALL:
+\&      if (RETVAL != 0)
+\&          croak("Error %d while deleting file \*(Aq%s\*(Aq", RETVAL, name);
+.Ve
+.PP
+Here the generated XS function returns nothing on success, and will \fBdie()\fR
+with a meaningful error message on error.
+.SS "The CODE: Keyword"
+.IX Subsection "The CODE: Keyword"
+This keyword is used in more complicated XSUBs which require
+special handling for the C function.  The RETVAL variable is
+still declared, but it will not be returned unless it is specified
+in the OUTPUT: section.
+.PP
+The following XSUB is for a C function which requires special handling of
+its parameters.  The Perl usage is given first.
+.PP
+.Vb 1
+\&     $status = rpcb_gettime( "localhost", $timep );
+.Ve
+.PP
+The XSUB follows.
+.PP
+.Vb 9
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t timep
+\&        CODE:
+\&               RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.SS "The INIT: Keyword"
+.IX Subsection "The INIT: Keyword"
+The INIT: keyword allows initialization to be inserted into the XSUB before
+the compiler generates the call to the C function.  Unlike the CODE: keyword
+above, this keyword does not affect the way the compiler handles RETVAL.
+.PP
+.Vb 8
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        INIT:
+\&          printf("# Host is %s\en", host );
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+Another use for the INIT: section is to check for preconditions before
+making a call to the C function:
+.PP
+.Vb 9
+\&    long long
+\&    lldiv(a,b)
+\&        long long a
+\&        long long b
+\&      INIT:
+\&        if (a == 0 && b == 0)
+\&            XSRETURN_UNDEF;
+\&        if (b == 0)
+\&            croak("lldiv: cannot divide by 0");
+.Ve
+.SS "The NO_INIT Keyword"
+.IX Subsection "The NO_INIT Keyword"
+The NO_INIT keyword is used to indicate that a function
+parameter is being used only as an output value.  The \fBxsubpp\fR
+compiler will normally generate code to read the values of
+all function parameters from the argument stack and assign
+them to C variables upon entry to the function.  NO_INIT
+will tell the compiler that some parameters will be used for
+output rather than for input and that they will be handled
+before the function terminates.
+.PP
+The following example shows a variation of the \fBrpcb_gettime()\fR function.
+This function uses the timep variable only as an output variable and does
+not care about its initial contents.
+.PP
+.Vb 6
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep = NO_INIT
+\&        OUTPUT:
+\&          timep
+.Ve
+.SS "The TYPEMAP: Keyword"
+.IX Subsection "The TYPEMAP: Keyword"
+Starting with Perl 5.16, you can embed typemaps into your XS code
+instead of or in addition to typemaps in a separate file.  Multiple
+such embedded typemaps will be processed in order of appearance in
+the XS code and like local typemap files take precedence over the
+default typemap, the embedded typemaps may overwrite previous
+definitions of TYPEMAP, INPUT, and OUTPUT stanzas.  The syntax for
+embedded typemaps is
+.PP
+.Vb 3
+\&      TYPEMAP: <<HERE
+\&      ... your typemap code here ...
+\&      HERE
+.Ve
+.PP
+where the \f(CW\*(C`TYPEMAP\*(C'\fR keyword must appear in the first column of a
+new line.
+.PP
+Refer to perlxstypemap for details on writing typemaps.
+.SS "Initializing Function Parameters"
+.IX Subsection "Initializing Function Parameters"
+C function parameters are normally initialized with their values from
+the argument stack (which in turn contains the parameters that were
+passed to the XSUB from Perl).  The typemaps contain the
+code segments which are used to translate the Perl values to
+the C parameters.  The programmer, however, is allowed to
+override the typemaps and supply alternate (or additional)
+initialization code.  Initialization code starts with the first
+\&\f(CW\*(C`=\*(C'\fR, \f(CW\*(C`;\*(C'\fR or \f(CW\*(C`+\*(C'\fR on a line in the INPUT: section.  The only
+exception happens if this \f(CW\*(C`;\*(C'\fR terminates the line, then this \f(CW\*(C`;\*(C'\fR
+is quietly ignored.
+.PP
+The following code demonstrates how to supply initialization code for
+function parameters.  The initialization code is eval'ed within double
+quotes by the compiler before it is added to the output so anything
+which should be interpreted literally [mainly \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, or \f(CW\*(C`\e\e\*(C'\fR]
+must be protected with backslashes.  The variables \f(CW$var\fR, \f(CW$arg\fR,
+and \f(CW$type\fR can be used as in typemaps.
+.PP
+.Vb 6
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          char *host = (char *)SvPVbyte_nolen($arg);
+\&          time_t &timep = 0;
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+This should not be used to supply default values for parameters.  One
+would normally use this when a function parameter must be processed by
+another library function before it can be used.  Default parameters are
+covered in the next section.
+.PP
+If the initialization begins with \f(CW\*(C`=\*(C'\fR, then it is output in
+the declaration for the input variable, replacing the initialization
+supplied by the typemap.  If the initialization
+begins with \f(CW\*(C`;\*(C'\fR or \f(CW\*(C`+\*(C'\fR, then it is performed after
+all of the input variables have been declared.  In the \f(CW\*(C`;\*(C'\fR
+case the initialization normally supplied by the typemap is not performed.
+For the \f(CW\*(C`+\*(C'\fR case, the declaration for the variable will include the
+initialization from the typemap.  A global
+variable, \f(CW%v\fR, is available for the truly rare case where
+information from one initialization is needed in another
+initialization.
+.PP
+Here's a truly obscure example:
+.PP
+.Vb 6
+\&     bool_t
+\&     rpcb_gettime(host,timep)
+\&          time_t &timep; /* \e$v{timep}=@{[$v{timep}=$arg]} */
+\&          char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL;
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+The construct \f(CW\*(C`\e$v{timep}=@{[$v{timep}=$arg]}\*(C'\fR used in the above
+example has a two-fold purpose: first, when this line is processed by
+\&\fBxsubpp\fR, the Perl snippet \f(CW\*(C`$v{timep}=$arg\*(C'\fR is evaluated.  Second,
+the text of the evaluated snippet is output into the generated C file
+(inside a C comment)!  During the processing of \f(CW\*(C`char *host\*(C'\fR line,
+\&\f(CW$arg\fR will evaluate to \f(CWST(0)\fR, and \f(CW$v{timep}\fR will evaluate to
+\&\f(CWST(1)\fR.
+.SS "Default Parameter Values"
+.IX Subsection "Default Parameter Values"
+Default values for XSUB arguments can be specified by placing an
+assignment statement in the parameter list.  The default value may
+be a number, a string or the special string \f(CW\*(C`NO_INIT\*(C'\fR.  Defaults should
+always be used on the right-most parameters only.
+.PP
+To allow the XSUB for \fBrpcb_gettime()\fR to have a default host
+value the parameters to the XSUB could be rearranged.  The
+XSUB will then call the real \fBrpcb_gettime()\fR function with
+the parameters in the correct order.  This XSUB can be called
+from Perl with either of the following statements:
+.PP
+.Vb 1
+\&     $status = rpcb_gettime( $timep, $host );
+\&
+\&     $status = rpcb_gettime( $timep );
+.Ve
+.PP
+The XSUB will look like the code which follows.  A CODE:
+block is used to call the real \fBrpcb_gettime()\fR function with
+the parameters in the correct order for that function.
+.PP
+.Vb 9
+\&     bool_t
+\&     rpcb_gettime(timep,host="localhost")
+\&          char *host
+\&          time_t timep = NO_INIT
+\&        CODE:
+\&               RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.SS "The PREINIT: Keyword"
+.IX Subsection "The PREINIT: Keyword"
+The PREINIT: keyword allows extra variables to be declared immediately
+before or after the declarations of the parameters from the INPUT: section
+are emitted.
+.PP
+If a variable is declared inside a CODE: section it will follow any typemap
+code that is emitted for the input parameters.  This may result in the
+declaration ending up after C code, which is C syntax error.  Similar
+errors may happen with an explicit \f(CW\*(C`;\*(C'\fR\-type or \f(CW\*(C`+\*(C'\fR\-type initialization of
+parameters is used (see "Initializing Function Parameters").  Declaring
+these variables in an INIT: section will not help.
+.PP
+In such cases, to force an additional variable to be declared together
+with declarations of other variables, place the declaration into a
+PREINIT: section.  The PREINIT: keyword may be used one or more times
+within an XSUB.
+.PP
+The following examples are equivalent, but if the code is using complex
+typemaps then the first example is safer.
+.PP
+.Vb 10
+\&     bool_t
+\&     rpcb_gettime(timep)
+\&          time_t timep = NO_INIT
+\&        PREINIT:
+\&          char *host = "localhost";
+\&        CODE:
+\&          RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+For this particular case an INIT: keyword would generate the
+same C code as the PREINIT: keyword.  Another correct, but error-prone example:
+.PP
+.Vb 9
+\&     bool_t
+\&     rpcb_gettime(timep)
+\&          time_t timep = NO_INIT
+\&        CODE:
+\&          char *host = "localhost";
+\&          RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+Another way to declare \f(CW\*(C`host\*(C'\fR is to use a C block in the CODE: section:
+.PP
+.Vb 11
+\&     bool_t
+\&     rpcb_gettime(timep)
+\&          time_t timep = NO_INIT
+\&        CODE:
+\&          {
+\&            char *host = "localhost";
+\&            RETVAL = rpcb_gettime( host, &timep );
+\&          }
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+The ability to put additional declarations before the typemap entries are
+processed is very handy in the cases when typemap conversions manipulate
+some global state:
+.PP
+.Vb 8
+\&    MyObject
+\&    mutate(o)
+\&        PREINIT:
+\&            MyState st = global_state;
+\&        INPUT:
+\&            MyObject o;
+\&        CLEANUP:
+\&            reset_to(global_state, st);
+.Ve
+.PP
+Here we suppose that conversion to \f(CW\*(C`MyObject\*(C'\fR in the INPUT: section and from
+MyObject when processing RETVAL will modify a global variable \f(CW\*(C`global_state\*(C'\fR.
+After these conversions are performed, we restore the old value of
+\&\f(CW\*(C`global_state\*(C'\fR (to avoid memory leaks, for example).
+.PP
+There is another way to trade clarity for compactness: INPUT sections allow
+declaration of C variables which do not appear in the parameter list of
+a subroutine.  Thus the above code for \fBmutate()\fR can be rewritten as
+.PP
+.Vb 6
+\&    MyObject
+\&    mutate(o)
+\&          MyState st = global_state;
+\&          MyObject o;
+\&        CLEANUP:
+\&          reset_to(global_state, st);
+.Ve
+.PP
+and the code for \fBrpcb_gettime()\fR can be rewritten as
+.PP
+.Vb 9
+\&     bool_t
+\&     rpcb_gettime(timep)
+\&          time_t timep = NO_INIT
+\&          char *host = "localhost";
+\&        C_ARGS:
+\&          host, &timep
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.SS "The SCOPE: Keyword"
+.IX Subsection "The SCOPE: Keyword"
+The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
+enabled, the XSUB will invoke ENTER and LEAVE automatically.
+.PP
+To support potentially complex type mappings, if a typemap entry used
+by an XSUB contains a comment like \f(CW\*(C`/*scope*/\*(C'\fR then scoping will
+be automatically enabled for that XSUB.
+.PP
+To enable scoping:
+.PP
+.Vb 1
+\&    SCOPE: ENABLE
+.Ve
+.PP
+To disable scoping:
+.PP
+.Vb 1
+\&    SCOPE: DISABLE
+.Ve
+.SS "The INPUT: Keyword"
+.IX Subsection "The INPUT: Keyword"
+The XSUB's parameters are usually evaluated immediately after entering the
+XSUB.  The INPUT: keyword can be used to force those parameters to be
+evaluated a little later.  The INPUT: keyword can be used multiple times
+within an XSUB and can be used to list one or more input variables.  This
+keyword is used with the PREINIT: keyword.
+.PP
+The following example shows how the input parameter \f(CW\*(C`timep\*(C'\fR can be
+evaluated late, after a PREINIT.
+.PP
+.Vb 10
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&        PREINIT:
+\&          time_t tt;
+\&        INPUT:
+\&          time_t timep
+\&        CODE:
+\&               RETVAL = rpcb_gettime( host, &tt );
+\&               timep = tt;
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+The next example shows each input parameter evaluated late.
+.PP
+.Vb 10
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&        PREINIT:
+\&          time_t tt;
+\&        INPUT:
+\&          char *host
+\&        PREINIT:
+\&          char *h;
+\&        INPUT:
+\&          time_t timep
+\&        CODE:
+\&               h = host;
+\&               RETVAL = rpcb_gettime( h, &tt );
+\&               timep = tt;
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+Since INPUT sections allow declaration of C variables which do not appear
+in the parameter list of a subroutine, this may be shortened to:
+.PP
+.Vb 12
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          time_t tt;
+\&          char *host;
+\&          char *h = host;
+\&          time_t timep;
+\&        CODE:
+\&          RETVAL = rpcb_gettime( h, &tt );
+\&          timep = tt;
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+(We used our knowledge that input conversion for \f(CW\*(C`char *\*(C'\fR is a "simple" one,
+thus \f(CW\*(C`host\*(C'\fR is initialized on the declaration line, and our assignment
+\&\f(CW\*(C`h = host\*(C'\fR is not performed too early.  Otherwise one would need to have the
+assignment \f(CW\*(C`h = host\*(C'\fR in a CODE: or INIT: section.)
+.SS "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords"
+.IX Subsection "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords"
+In the list of parameters for an XSUB, one can precede parameter names
+by the \f(CW\*(C`IN\*(C'\fR/\f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR keywords.
+\&\f(CW\*(C`IN\*(C'\fR keyword is the default, the other keywords indicate how the Perl
+interface should differ from the C interface.
+.PP
+Parameters preceded by \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR
+keywords are considered to be used by the C subroutine \fIvia
+pointers\fR.  \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR keywords indicate that the C subroutine
+does not inspect the memory pointed by this parameter, but will write
+through this pointer to provide additional return values.
+.PP
+Parameters preceded by \f(CW\*(C`OUTLIST\*(C'\fR keyword do not appear in the usage
+signature of the generated Perl function.
+.PP
+Parameters preceded by \f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR \fIdo\fR appear as
+parameters to the Perl function.  With the exception of
+\&\f(CW\*(C`OUT\*(C'\fR\-parameters, these parameters are converted to the corresponding
+C type, then pointers to these data are given as arguments to the C
+function.  It is expected that the C function will write through these
+pointers.
+.PP
+The return list of the generated Perl function consists of the C return value
+from the function (unless the XSUB is of \f(CW\*(C`void\*(C'\fR return type or
+\&\f(CW\*(C`The NO_OUTPUT Keyword\*(C'\fR was used) followed by all the \f(CW\*(C`OUTLIST\*(C'\fR
+and \f(CW\*(C`IN_OUTLIST\*(C'\fR parameters (in the order of appearance).  On the
+return from the XSUB the \f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR Perl parameter will be
+modified to have the values written by the C function.
+.PP
+For example, an XSUB
+.PP
+.Vb 5
+\&  void
+\&  day_month(OUTLIST day, IN unix_time, OUTLIST month)
+\&    int day
+\&    int unix_time
+\&    int month
+.Ve
+.PP
+should be used from Perl as
+.PP
+.Vb 1
+\&  my ($day, $month) = day_month(time);
+.Ve
+.PP
+The C signature of the corresponding function should be
+.PP
+.Vb 1
+\&  void day_month(int *day, int unix_time, int *month);
+.Ve
+.PP
+The \f(CW\*(C`IN\*(C'\fR/\f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR keywords can be
+mixed with ANSI-style declarations, as in
+.PP
+.Vb 2
+\&  void
+\&  day_month(OUTLIST int day, int unix_time, OUTLIST int month)
+.Ve
+.PP
+(here the optional \f(CW\*(C`IN\*(C'\fR keyword is omitted).
+.PP
+The \f(CW\*(C`IN_OUT\*(C'\fR parameters are identical with parameters introduced with
+"The & Unary Operator" and put into the \f(CW\*(C`OUTPUT:\*(C'\fR section (see
+"The OUTPUT: Keyword").  The \f(CW\*(C`IN_OUTLIST\*(C'\fR parameters are very similar,
+the only difference being that the value C function writes through the
+pointer would not modify the Perl parameter, but is put in the output
+list.
+.PP
+The \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR parameter differ from \f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR
+parameters only by the initial value of the Perl parameter not
+being read (and not being given to the C function \- which gets some
+garbage instead).  For example, the same C function as above can be
+interfaced with as
+.PP
+.Vb 1
+\&  void day_month(OUT int day, int unix_time, OUT int month);
+.Ve
+.PP
+or
+.PP
+.Vb 8
+\&  void
+\&  day_month(day, unix_time, month)
+\&      int &day = NO_INIT
+\&      int  unix_time
+\&      int &month = NO_INIT
+\&    OUTPUT:
+\&      day
+\&      month
+.Ve
+.PP
+However, the generated Perl function is called in very C\-ish style:
+.PP
+.Vb 2
+\&  my ($day, $month);
+\&  day_month($day, time, $month);
+.Ve
+.ie n .SS "The length(NAME) Keyword"
+.el .SS "The \f(CWlength(NAME)\fP Keyword"
+.IX Subsection "The length(NAME) Keyword"
+If one of the input arguments to the C function is the length of a string
+argument \f(CW\*(C`NAME\*(C'\fR, one can substitute the name of the length-argument by
+\&\f(CWlength(NAME)\fR in the XSUB declaration.  This argument must be omitted when
+the generated Perl function is called.  E.g.,
+.PP
+.Vb 9
+\&  void
+\&  dump_chars(char *s, short l)
+\&  {
+\&    short n = 0;
+\&    while (n < l) {
+\&        printf("s[%d] = \e"\e\e%#03o\e"\en", n, (int)s[n]);
+\&        n++;
+\&    }
+\&  }
+\&
+\&  MODULE = x            PACKAGE = x
+\&
+\&  void dump_chars(char *s, short length(s))
+.Ve
+.PP
+should be called as \f(CWdump_chars($string)\fR.
+.PP
+This directive is supported with ANSI-type function declarations only.
+.SS "Variable-length Parameter Lists"
+.IX Subsection "Variable-length Parameter Lists"
+XSUBs can have variable-length parameter lists by specifying an ellipsis
+\&\f(CW\*(C`(...)\*(C'\fR in the parameter list.  This use of the ellipsis is similar to that
+found in ANSI C.  The programmer is able to determine the number of
+arguments passed to the XSUB by examining the \f(CW\*(C`items\*(C'\fR variable which the
+\&\fBxsubpp\fR compiler supplies for all XSUBs.  By using this mechanism one can
+create an XSUB which accepts a list of parameters of unknown length.
+.PP
+The \fIhost\fR parameter for the \fBrpcb_gettime()\fR XSUB can be
+optional so the ellipsis can be used to indicate that the
+XSUB will take a variable number of parameters.  Perl should
+be able to call this XSUB with either of the following statements.
+.PP
+.Vb 1
+\&     $status = rpcb_gettime( $timep, $host );
+\&
+\&     $status = rpcb_gettime( $timep );
+.Ve
+.PP
+The XS code, with ellipsis, follows.
+.PP
+.Vb 12
+\&     bool_t
+\&     rpcb_gettime(timep, ...)
+\&          time_t timep = NO_INIT
+\&        PREINIT:
+\&          char *host = "localhost";
+\&        CODE:
+\&          if( items > 1 )
+\&               host = (char *)SvPVbyte_nolen(ST(1));
+\&          RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.SS "The C_ARGS: Keyword"
+.IX Subsection "The C_ARGS: Keyword"
+The C_ARGS: keyword allows creating of XSUBS which have different
+calling sequence from Perl than from C, without a need to write
+CODE: or PPCODE: section.  The contents of the C_ARGS: paragraph is
+put as the argument to the called C function without any change.
+.PP
+For example, suppose that a C function is declared as
+.PP
+.Vb 1
+\&    symbolic nth_derivative(int n, symbolic function, int flags);
+.Ve
+.PP
+and that the default flags are kept in a global C variable
+\&\f(CW\*(C`default_flags\*(C'\fR.  Suppose that you want to create an interface which
+is called as
+.PP
+.Vb 1
+\&    $second_deriv = $function\->nth_derivative(2);
+.Ve
+.PP
+To do this, declare the XSUB as
+.PP
+.Vb 6
+\&    symbolic
+\&    nth_derivative(function, n)
+\&        symbolic        function
+\&        int             n
+\&      C_ARGS:
+\&        n, function, default_flags
+.Ve
+.SS "The PPCODE: Keyword"
+.IX Subsection "The PPCODE: Keyword"
+The PPCODE: keyword is an alternate form of the CODE: keyword and is used
+to tell the \fBxsubpp\fR compiler that the programmer is supplying the code to
+control the argument stack for the XSUBs return values.  Occasionally one
+will want an XSUB to return a list of values rather than a single value.
+In these cases one must use PPCODE: and then explicitly push the list of
+values on the stack.  The PPCODE: and CODE: keywords should not be used
+together within the same XSUB.
+.PP
+The actual difference between PPCODE: and CODE: sections is in the
+initialization of \f(CW\*(C`SP\*(C'\fR macro (which stands for the \fIcurrent\fR Perl
+stack pointer), and in the handling of data on the stack when returning
+from an XSUB.  In CODE: sections SP preserves the value which was on
+entry to the XSUB: SP is on the function pointer (which follows the
+last parameter).  In PPCODE: sections SP is moved backward to the
+beginning of the parameter list, which allows \f(CW\*(C`PUSH*()\*(C'\fR macros
+to place output values in the place Perl expects them to be when
+the XSUB returns back to Perl.
+.PP
+The generated trailer for a CODE: section ensures that the number of return
+values Perl will see is either 0 or 1 (depending on the \f(CW\*(C`void\*(C'\fRness of the
+return value of the C function, and heuristics mentioned in
+"The RETVAL Variable").  The trailer generated for a PPCODE: section
+is based on the number of return values and on the number of times
+\&\f(CW\*(C`SP\*(C'\fR was updated by \f(CW\*(C`[X]PUSH*()\*(C'\fR macros.
+.PP
+Note that macros \f(CWST(i)\fR, \f(CW\*(C`XST_m*()\*(C'\fR and \f(CW\*(C`XSRETURN*()\*(C'\fR work equally
+well in CODE: sections and PPCODE: sections.
+.PP
+The following XSUB will call the C \fBrpcb_gettime()\fR function
+and will return its two output values, timep and status, to
+Perl as a single list.
+.PP
+.Vb 11
+\&     void
+\&     rpcb_gettime(host)
+\&          char *host
+\&        PREINIT:
+\&          time_t  timep;
+\&          bool_t  status;
+\&        PPCODE:
+\&          status = rpcb_gettime( host, &timep );
+\&          EXTEND(SP, 2);
+\&          PUSHs(sv_2mortal(newSViv(status)));
+\&          PUSHs(sv_2mortal(newSViv(timep)));
+.Ve
+.PP
+Notice that the programmer must supply the C code necessary
+to have the real \fBrpcb_gettime()\fR function called and to have
+the return values properly placed on the argument stack.
+.PP
+The \f(CW\*(C`void\*(C'\fR return type for this function tells the \fBxsubpp\fR compiler that
+the RETVAL variable is not needed or used and that it should not be created.
+In most scenarios the void return type should be used with the PPCODE:
+directive.
+.PP
+The \fBEXTEND()\fR macro is used to make room on the argument
+stack for 2 return values.  The PPCODE: directive causes the
+\&\fBxsubpp\fR compiler to create a stack pointer available as \f(CW\*(C`SP\*(C'\fR, and it
+is this pointer which is being used in the \fBEXTEND()\fR macro.
+The values are then pushed onto the stack with the \fBPUSHs()\fR
+macro.
+.PP
+Now the \fBrpcb_gettime()\fR function can be used from Perl with
+the following statement.
+.PP
+.Vb 1
+\&     ($status, $timep) = rpcb_gettime("localhost");
+.Ve
+.PP
+When handling output parameters with a PPCODE section, be sure to handle
+\&'set' magic properly.  See perlguts for details about 'set' magic.
+.SS "Returning Undef And Empty Lists"
+.IX Subsection "Returning Undef And Empty Lists"
+Occasionally the programmer will want to return simply
+\&\f(CW\*(C`undef\*(C'\fR or an empty list if a function fails rather than a
+separate status value.  The \fBrpcb_gettime()\fR function offers
+just this situation.  If the function succeeds we would like
+to have it return the time and if it fails we would like to
+have undef returned.  In the following Perl code the value
+of \f(CW$timep\fR will either be undef or it will be a valid time.
+.PP
+.Vb 1
+\&     $timep = rpcb_gettime( "localhost" );
+.Ve
+.PP
+The following XSUB uses the \f(CW\*(C`SV *\*(C'\fR return type as a mnemonic only,
+and uses a CODE: block to indicate to the compiler
+that the programmer has supplied all the necessary code.  The
+\&\fBsv_newmortal()\fR call will initialize the return value to undef, making that
+the default return value.
+.PP
+.Vb 10
+\&     SV *
+\&     rpcb_gettime(host)
+\&          char *  host
+\&        PREINIT:
+\&          time_t  timep;
+\&          bool_t x;
+\&        CODE:
+\&          ST(0) = sv_newmortal();
+\&          if( rpcb_gettime( host, &timep ) )
+\&               sv_setnv( ST(0), (double)timep);
+.Ve
+.PP
+The next example demonstrates how one would place an explicit undef in the
+return value, should the need arise.
+.PP
+.Vb 10
+\&     SV *
+\&     rpcb_gettime(host)
+\&          char *  host
+\&        PREINIT:
+\&          time_t  timep;
+\&          bool_t x;
+\&        CODE:
+\&          if( rpcb_gettime( host, &timep ) ){
+\&               ST(0) = sv_newmortal();
+\&               sv_setnv( ST(0), (double)timep);
+\&          }
+\&          else{
+\&               ST(0) = &PL_sv_undef;
+\&          }
+.Ve
+.PP
+To return an empty list one must use a PPCODE: block and
+then not push return values on the stack.
+.PP
+.Vb 12
+\&     void
+\&     rpcb_gettime(host)
+\&          char *host
+\&        PREINIT:
+\&          time_t  timep;
+\&        PPCODE:
+\&          if( rpcb_gettime( host, &timep ) )
+\&               PUSHs(sv_2mortal(newSViv(timep)));
+\&          else{
+\&              /* Nothing pushed on stack, so an empty
+\&               * list is implicitly returned. */
+\&          }
+.Ve
+.PP
+Some people may be inclined to include an explicit \f(CW\*(C`return\*(C'\fR in the above
+XSUB, rather than letting control fall through to the end.  In those
+situations \f(CW\*(C`XSRETURN_EMPTY\*(C'\fR should be used, instead.  This will ensure that
+the XSUB stack is properly adjusted.  Consult perlapi for other
+\&\f(CW\*(C`XSRETURN\*(C'\fR macros.
+.PP
+Since \f(CW\*(C`XSRETURN_*\*(C'\fR macros can be used with CODE blocks as well, one can
+rewrite this example as:
+.PP
+.Vb 11
+\&     int
+\&     rpcb_gettime(host)
+\&          char *host
+\&        PREINIT:
+\&          time_t  timep;
+\&        CODE:
+\&          RETVAL = rpcb_gettime( host, &timep );
+\&          if (RETVAL == 0)
+\&                XSRETURN_UNDEF;
+\&        OUTPUT:
+\&          RETVAL
+.Ve
+.PP
+In fact, one can put this check into a POSTCALL: section as well.  Together
+with PREINIT: simplifications, this leads to:
+.PP
+.Vb 7
+\&     int
+\&     rpcb_gettime(host)
+\&          char *host
+\&          time_t  timep;
+\&        POSTCALL:
+\&          if (RETVAL == 0)
+\&                XSRETURN_UNDEF;
+.Ve
+.SS "The REQUIRE: Keyword"
+.IX Subsection "The REQUIRE: Keyword"
+The REQUIRE: keyword is used to indicate the minimum version of the
+\&\fBxsubpp\fR compiler needed to compile the XS module.  An XS module which
+contains the following statement will compile with only \fBxsubpp\fR version
+1.922 or greater:
+.PP
+.Vb 1
+\&        REQUIRE: 1.922
+.Ve
+.SS "The CLEANUP: Keyword"
+.IX Subsection "The CLEANUP: Keyword"
+This keyword can be used when an XSUB requires special cleanup procedures
+before it terminates.  When the CLEANUP: keyword is used it must follow
+any CODE:, or OUTPUT: blocks which are present in the XSUB.  The code
+specified for the cleanup block will be added as the last statements in
+the XSUB.
+.SS "The POSTCALL: Keyword"
+.IX Subsection "The POSTCALL: Keyword"
+This keyword can be used when an XSUB requires special procedures
+executed after the C subroutine call is performed.  When the POSTCALL:
+keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
+present in the XSUB.
+.PP
+See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty Lists".
+.PP
+The POSTCALL: block does not make a lot of sense when the C subroutine
+call is supplied by user by providing either CODE: or PPCODE: section.
+.SS "The BOOT: Keyword"
+.IX Subsection "The BOOT: Keyword"
+The BOOT: keyword is used to add code to the extension's bootstrap
+function.  The bootstrap function is generated by the \fBxsubpp\fR compiler and
+normally holds the statements necessary to register any XSUBs with Perl.
+With the BOOT: keyword the programmer can tell the compiler to add extra
+statements to the bootstrap function.
+.PP
+This keyword may be used any time after the first MODULE keyword and should
+appear on a line by itself.  The first blank line after the keyword will
+terminate the code block.
+.PP
+.Vb 4
+\&     BOOT:
+\&     # The following message will be printed when the
+\&     # bootstrap function executes.
+\&     printf("Hello from the bootstrap!\en");
+.Ve
+.SS "The VERSIONCHECK: Keyword"
+.IX Subsection "The VERSIONCHECK: Keyword"
+The VERSIONCHECK: keyword corresponds to \fBxsubpp\fR's \f(CW\*(C`\-versioncheck\*(C'\fR and
+\&\f(CW\*(C`\-noversioncheck\*(C'\fR options.  This keyword overrides the command line
+options.  Version checking is enabled by default.  When version checking is
+enabled the XS module will attempt to verify that its version matches the
+version of the PM module.
+.PP
+To enable version checking:
+.PP
+.Vb 1
+\&    VERSIONCHECK: ENABLE
+.Ve
+.PP
+To disable version checking:
+.PP
+.Vb 1
+\&    VERSIONCHECK: DISABLE
+.Ve
+.PP
+Note that if the version of the PM module is an NV (a floating point
+number), it will be stringified with a possible loss of precision
+(currently chopping to nine decimal places) so that it may not match
+the version of the XS module anymore. Quoting the \f(CW$VERSION\fR declaration
+to make it a string is recommended if long version numbers are used.
+.SS "The PROTOTYPES: Keyword"
+.IX Subsection "The PROTOTYPES: Keyword"
+The PROTOTYPES: keyword corresponds to \fBxsubpp\fR's \f(CW\*(C`\-prototypes\*(C'\fR and
+\&\f(CW\*(C`\-noprototypes\*(C'\fR options.  This keyword overrides the command line options.
+Prototypes are disabled by default.  When prototypes are enabled, XSUBs will
+be given Perl prototypes.  This keyword may be used multiple times in an XS
+module to enable and disable prototypes for different parts of the module.
+Note that \fBxsubpp\fR will nag you if you don't explicitly enable or disable
+prototypes, with:
+.PP
+.Vb 1
+\&    Please specify prototyping behavior for Foo.xs (see perlxs manual)
+.Ve
+.PP
+To enable prototypes:
+.PP
+.Vb 1
+\&    PROTOTYPES: ENABLE
+.Ve
+.PP
+To disable prototypes:
+.PP
+.Vb 1
+\&    PROTOTYPES: DISABLE
+.Ve
+.SS "The PROTOTYPE: Keyword"
+.IX Subsection "The PROTOTYPE: Keyword"
+This keyword is similar to the PROTOTYPES: keyword above but can be used to
+force \fBxsubpp\fR to use a specific prototype for the XSUB.  This keyword
+overrides all other prototype options and keywords but affects only the
+current XSUB.  Consult "Prototypes" in perlsub for information about Perl
+prototypes.
+.PP
+.Vb 10
+\&    bool_t
+\&    rpcb_gettime(timep, ...)
+\&          time_t timep = NO_INIT
+\&        PROTOTYPE: $;$
+\&        PREINIT:
+\&          char *host = "localhost";
+\&        CODE:
+\&                  if( items > 1 )
+\&                       host = (char *)SvPVbyte_nolen(ST(1));
+\&                  RETVAL = rpcb_gettime( host, &timep );
+\&        OUTPUT:
+\&          timep
+\&          RETVAL
+.Ve
+.PP
+If the prototypes are enabled, you can disable it locally for a given
+XSUB as in the following example:
+.PP
+.Vb 4
+\&    void
+\&    rpcb_gettime_noproto()
+\&        PROTOTYPE: DISABLE
+\&    ...
+.Ve
+.SS "The ALIAS: Keyword"
+.IX Subsection "The ALIAS: Keyword"
+The ALIAS: keyword allows an XSUB to have two or more unique Perl names
+and to know which of those names was used when it was invoked.  The Perl
+names may be fully-qualified with package names.  Each alias is given an
+index.  The compiler will setup a variable called \f(CW\*(C`ix\*(C'\fR which contain the
+index of the alias which was used.  When the XSUB is called with its
+declared name \f(CW\*(C`ix\*(C'\fR will be 0.
+.PP
+The following example will create aliases \f(CWFOO::gettime()\fR and
+\&\f(CWBAR::getit()\fR for this function.
+.PP
+.Vb 11
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        ALIAS:
+\&            FOO::gettime = 1
+\&            BAR::getit = 2
+\&        INIT:
+\&          printf("# ix = %d\en", ix );
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+A warning will be produced when you create more than one alias to the same
+value. This may be worked around in a backwards compatible way by creating
+multiple defines which resolve to the same value, or with a modern version
+of ExtUtils::ParseXS you can use a symbolic alias, which are denoted with
+a \f(CW\*(C`=>\*(C'\fR instead of a \f(CW\*(C`=\*(C'\fR. For instance you could change the above
+so that the alias section looked like this:
+.PP
+.Vb 4
+\&        ALIAS:
+\&            FOO::gettime = 1
+\&            BAR::getit = 2
+\&            BAZ::gettime => FOO::gettime
+.Ve
+.PP
+this would have the same effect as this:
+.PP
+.Vb 4
+\&        ALIAS:
+\&            FOO::gettime = 1
+\&            BAR::getit = 2
+\&            BAZ::gettime = 1
+.Ve
+.PP
+except that the latter will produce warnings during the build process. A
+mechanism that would work in a backwards compatible way with older
+versions of our tool chain would be to do this:
+.PP
+.Vb 3
+\&    #define FOO_GETTIME 1
+\&    #define BAR_GETIT 2
+\&    #define BAZ_GETTIME 1
+\&
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        ALIAS:
+\&            FOO::gettime = FOO_GETTIME
+\&            BAR::getit = BAR_GETIT
+\&            BAZ::gettime = BAZ_GETTIME
+\&        INIT:
+\&          printf("# ix = %d\en", ix );
+\&        OUTPUT:
+\&          timep
+.Ve
+.SS "The OVERLOAD: Keyword"
+.IX Subsection "The OVERLOAD: Keyword"
+Instead of writing an overloaded interface using pure Perl, you
+can also use the OVERLOAD keyword to define additional Perl names
+for your functions (like the ALIAS: keyword above).  However, the
+overloaded functions must be defined in such a way as to accept the number
+of parameters supplied by perl's overload system.  For most overload
+methods, it will be three parameters; for the \f(CW\*(C`nomethod\*(C'\fR function it will
+be four.  However, the bitwise operators \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR may be
+called with three \fIor\fR five arguments (see overload).
+.PP
+If any
+function has the OVERLOAD: keyword, several additional lines
+will be defined in the c file generated by xsubpp in order to
+register with the overload magic.
+.PP
+Since blessed objects are actually stored as RV's, it is useful
+to use the typemap features to preprocess parameters and extract
+the actual SV stored within the blessed RV.  See the sample for
+T_PTROBJ_SPECIAL below.
+.PP
+To use the OVERLOAD: keyword, create an XS function which takes
+three input parameters (or use the C\-style '...' definition) like
+this:
+.PP
+.Vb 7
+\&    SV *
+\&    cmp (lobj, robj, swap)
+\&    My_Module_obj    lobj
+\&    My_Module_obj    robj
+\&    IV               swap
+\&    OVERLOAD: cmp <=>
+\&    { /* function defined here */}
+.Ve
+.PP
+In this case, the function will overload both of the three way
+comparison operators.  For all overload operations using non-alpha
+characters, you must type the parameter without quoting, separating
+multiple overloads with whitespace.  Note that "" (the stringify
+overload) should be entered as \e"\e" (i.e. escaped).
+.PP
+Since, as mentioned above, bitwise operators may take extra arguments, you
+may want to use something like \f(CW\*(C`(lobj, robj, swap, ...)\*(C'\fR (with
+literal \f(CW\*(C`...\*(C'\fR) as your parameter list.
+.SS "The FALLBACK: Keyword"
+.IX Subsection "The FALLBACK: Keyword"
+In addition to the OVERLOAD keyword, if you need to control how
+Perl autogenerates missing overloaded operators, you can set the
+FALLBACK keyword in the module header section, like this:
+.PP
+.Vb 1
+\&    MODULE = RPC  PACKAGE = RPC
+\&
+\&    FALLBACK: TRUE
+\&    ...
+.Ve
+.PP
+where FALLBACK can take any of the three values TRUE, FALSE, or
+UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
+it defaults to UNDEF.  FALLBACK is not used except when one or
+more functions using OVERLOAD have been defined.  Please see
+"fallback" in overload for more details.
+.SS "The INTERFACE: Keyword"
+.IX Subsection "The INTERFACE: Keyword"
+This keyword declares the current XSUB as a keeper of the given
+calling signature.  If some text follows this keyword, it is
+considered as a list of functions which have this signature, and
+should be attached to the current XSUB.
+.PP
+For example, if you have 4 C functions \fBmultiply()\fR, \fBdivide()\fR, \fBadd()\fR,
+\&\fBsubtract()\fR all having the signature:
+.PP
+.Vb 1
+\&    symbolic f(symbolic, symbolic);
+.Ve
+.PP
+you can make them all to use the same XSUB using this:
+.PP
+.Vb 7
+\&    symbolic
+\&    interface_s_ss(arg1, arg2)
+\&        symbolic        arg1
+\&        symbolic        arg2
+\&    INTERFACE:
+\&        multiply divide
+\&        add subtract
+.Ve
+.PP
+(This is the complete XSUB code for 4 Perl functions!)  Four generated
+Perl function share names with corresponding C functions.
+.PP
+The advantage of this approach comparing to ALIAS: keyword is that there
+is no need to code a switch statement, each Perl function (which shares
+the same XSUB) knows which C function it should call.  Additionally, one
+can attach an extra function \fBremainder()\fR at runtime by using
+.PP
+.Vb 3
+\&    CV *mycv = newXSproto("Symbolic::remainder",
+\&                          XS_Symbolic_interface_s_ss, _\|_FILE_\|_, "$$");
+\&    XSINTERFACE_FUNC_SET(mycv, remainder);
+.Ve
+.PP
+say, from another XSUB.  (This example supposes that there was no
+INTERFACE_MACRO: section, otherwise one needs to use something else instead of
+\&\f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR, see the next section.)
+.SS "The INTERFACE_MACRO: Keyword"
+.IX Subsection "The INTERFACE_MACRO: Keyword"
+This keyword allows one to define an INTERFACE using a different way
+to extract a function pointer from an XSUB.  The text which follows
+this keyword should give the name of macros which would extract/set a
+function pointer.  The extractor macro is given return type, \f(CW\*(C`CV*\*(C'\fR,
+and \f(CW\*(C`XSANY.any_dptr\*(C'\fR for this \f(CW\*(C`CV*\*(C'\fR.  The setter macro is given cv,
+and the function pointer.
+.PP
+The default value is \f(CW\*(C`XSINTERFACE_FUNC\*(C'\fR and \f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR.
+An INTERFACE keyword with an empty list of functions can be omitted if
+INTERFACE_MACRO keyword is used.
+.PP
+Suppose that in the previous example functions pointers for
+\&\fBmultiply()\fR, \fBdivide()\fR, \fBadd()\fR, \fBsubtract()\fR are kept in a global C array
+\&\f(CW\*(C`fp[]\*(C'\fR with offsets being \f(CW\*(C`multiply_off\*(C'\fR, \f(CW\*(C`divide_off\*(C'\fR, \f(CW\*(C`add_off\*(C'\fR,
+\&\f(CW\*(C`subtract_off\*(C'\fR.  Then one can use
+.PP
+.Vb 4
+\&    #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \e
+\&        ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
+\&    #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \e
+\&        CvXSUBANY(cv).any_i32 = CAT2( f, _off )
+.Ve
+.PP
+in C section,
+.PP
+.Vb 10
+\&    symbolic
+\&    interface_s_ss(arg1, arg2)
+\&        symbolic        arg1
+\&        symbolic        arg2
+\&      INTERFACE_MACRO:
+\&        XSINTERFACE_FUNC_BYOFFSET
+\&        XSINTERFACE_FUNC_BYOFFSET_set
+\&      INTERFACE:
+\&        multiply divide
+\&        add subtract
+.Ve
+.PP
+in XSUB section.
+.SS "The INCLUDE: Keyword"
+.IX Subsection "The INCLUDE: Keyword"
+This keyword can be used to pull other files into the XS module.  The other
+files may have XS code.  INCLUDE: can also be used to run a command to
+generate the XS code to be pulled into the module.
+.PP
+The file \fIRpcb1.xsh\fR contains our \f(CWrpcb_gettime()\fR function:
+.PP
+.Vb 6
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+The XS module can use INCLUDE: to pull that file into it.
+.PP
+.Vb 1
+\&    INCLUDE: Rpcb1.xsh
+.Ve
+.PP
+If the parameters to the INCLUDE: keyword are followed by a pipe (\f(CW\*(C`|\*(C'\fR) then
+the compiler will interpret the parameters as a command. This feature is
+mildly deprecated in favour of the \f(CW\*(C`INCLUDE_COMMAND:\*(C'\fR directive, as documented
+below.
+.PP
+.Vb 1
+\&    INCLUDE: cat Rpcb1.xsh |
+.Ve
+.PP
+Do not use this to run perl: \f(CW\*(C`INCLUDE: perl |\*(C'\fR will run the perl that
+happens to be the first in your path and not necessarily the same perl that is
+used to run \f(CW\*(C`xsubpp\*(C'\fR. See "The INCLUDE_COMMAND: Keyword".
+.SS "The INCLUDE_COMMAND: Keyword"
+.IX Subsection "The INCLUDE_COMMAND: Keyword"
+Runs the supplied command and includes its output into the current XS
+document. \f(CW\*(C`INCLUDE_COMMAND\*(C'\fR assigns special meaning to the \f(CW$^X\fR token
+in that it runs the same perl interpreter that is running \f(CW\*(C`xsubpp\*(C'\fR:
+.PP
+.Vb 1
+\&    INCLUDE_COMMAND: cat Rpcb1.xsh
+\&
+\&    INCLUDE_COMMAND: $^X \-e ...
+.Ve
+.SS "The CASE: Keyword"
+.IX Subsection "The CASE: Keyword"
+The CASE: keyword allows an XSUB to have multiple distinct parts with each
+part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
+other XS keywords must be contained within a CASE:.  This means nothing may
+precede the first CASE: in the XSUB and anything following the last CASE: is
+included in that case.
+.PP
+A CASE: might switch via a parameter of the XSUB, via the \f(CW\*(C`ix\*(C'\fR ALIAS:
+variable (see "The ALIAS: Keyword"), or maybe via the \f(CW\*(C`items\*(C'\fR variable
+(see "Variable-length Parameter Lists").  The last CASE: becomes the
+\&\fBdefault\fR case if it is not associated with a conditional.  The following
+example shows CASE switched via \f(CW\*(C`ix\*(C'\fR with a function \f(CWrpcb_gettime()\fR
+having an alias \f(CWx_gettime()\fR.  When the function is called as
+\&\f(CWrpcb_gettime()\fR its parameters are the usual \f(CW\*(C`(char *host, time_t *timep)\*(C'\fR,
+but when the function is called as \f(CWx_gettime()\fR its parameters are
+reversed, \f(CW\*(C`(time_t *timep, char *host)\*(C'\fR.
+.PP
+.Vb 10
+\&    long
+\&    rpcb_gettime(a,b)
+\&      CASE: ix == 1
+\&        ALIAS:
+\&          x_gettime = 1
+\&        INPUT:
+\&          # \*(Aqa\*(Aq is timep, \*(Aqb\*(Aq is host
+\&          char *b
+\&          time_t a = NO_INIT
+\&        CODE:
+\&               RETVAL = rpcb_gettime( b, &a );
+\&        OUTPUT:
+\&          a
+\&          RETVAL
+\&      CASE:
+\&          # \*(Aqa\*(Aq is host, \*(Aqb\*(Aq is timep
+\&          char *a
+\&          time_t &b = NO_INIT
+\&        OUTPUT:
+\&          b
+\&          RETVAL
+.Ve
+.PP
+That function can be called with either of the following statements.  Note
+the different argument lists.
+.PP
+.Vb 1
+\&        $status = rpcb_gettime( $host, $timep );
+\&
+\&        $status = x_gettime( $timep, $host );
+.Ve
+.SS "The EXPORT_XSUB_SYMBOLS: Keyword"
+.IX Subsection "The EXPORT_XSUB_SYMBOLS: Keyword"
+The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need.
+In perl versions earlier than 5.16.0, this keyword does nothing. Starting
+with 5.16, XSUB symbols are no longer exported by default. That is, they
+are \f(CW\*(C`static\*(C'\fR functions. If you include
+.PP
+.Vb 1
+\&  EXPORT_XSUB_SYMBOLS: ENABLE
+.Ve
+.PP
+in your XS code, the XSUBs following this line will not be declared \f(CW\*(C`static\*(C'\fR.
+You can later disable this with
+.PP
+.Vb 1
+\&  EXPORT_XSUB_SYMBOLS: DISABLE
+.Ve
+.PP
+which, again, is the default that you should probably never change.
+You cannot use this keyword on versions of perl before 5.16 to make
+XSUBs \f(CW\*(C`static\*(C'\fR.
+.SS "The & Unary Operator"
+.IX Subsection "The & Unary Operator"
+The \f(CW\*(C`&\*(C'\fR unary operator in the INPUT: section is used to tell \fBxsubpp\fR
+that it should convert a Perl value to/from C using the C type to the left
+of \f(CW\*(C`&\*(C'\fR, but provide a pointer to this value when the C function is called.
+.PP
+This is useful to avoid a CODE: block for a C function which takes a parameter
+by reference.  Typically, the parameter should be not a pointer type (an
+\&\f(CW\*(C`int\*(C'\fR or \f(CW\*(C`long\*(C'\fR but not an \f(CW\*(C`int*\*(C'\fR or \f(CW\*(C`long*\*(C'\fR).
+.PP
+The following XSUB will generate incorrect C code.  The \fBxsubpp\fR compiler will
+turn this into code which calls \f(CWrpcb_gettime()\fR with parameters \f(CW\*(C`(char
+*host, time_t timep)\*(C'\fR, but the real \f(CWrpcb_gettime()\fR wants the \f(CW\*(C`timep\*(C'\fR
+parameter to be of type \f(CW\*(C`time_t*\*(C'\fR rather than \f(CW\*(C`time_t\*(C'\fR.
+.PP
+.Vb 6
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t timep
+\&        OUTPUT:
+\&          timep
+.Ve
+.PP
+That problem is corrected by using the \f(CW\*(C`&\*(C'\fR operator.  The \fBxsubpp\fR compiler
+will now turn this into code which calls \f(CWrpcb_gettime()\fR correctly with
+parameters \f(CW\*(C`(char *host, time_t *timep)\*(C'\fR.  It does this by carrying the
+\&\f(CW\*(C`&\*(C'\fR through, so the function call looks like \f(CW\*(C`rpcb_gettime(host, &timep)\*(C'\fR.
+.PP
+.Vb 6
+\&    bool_t
+\&    rpcb_gettime(host,timep)
+\&          char *host
+\&          time_t &timep
+\&        OUTPUT:
+\&          timep
+.Ve
+.SS "Inserting POD, Comments and C Preprocessor Directives"
+.IX Subsection "Inserting POD, Comments and C Preprocessor Directives"
+C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
+PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
+Comments are allowed anywhere after the MODULE keyword.  The compiler will
+pass the preprocessor directives through untouched and will remove the
+commented lines. POD documentation is allowed at any point, both in the
+C and XS language sections. POD must be terminated with a \f(CW\*(C`=cut\*(C'\fR command;
+\&\f(CW\*(C`xsubpp\*(C'\fR will exit with an error if it does not. It is very unlikely that
+human generated C code will be mistaken for POD, as most indenting styles
+result in whitespace in front of any line starting with \f(CW\*(C`=\*(C'\fR. Machine
+generated XS files may fall into this trap unless care is taken to
+ensure that a space breaks the sequence "\en=".
+.PP
+Comments can be added to XSUBs by placing a \f(CW\*(C`#\*(C'\fR as the first
+non-whitespace of a line.  Care should be taken to avoid making the
+comment look like a C preprocessor directive, lest it be interpreted as
+such.  The simplest way to prevent this is to put whitespace in front of
+the \f(CW\*(C`#\*(C'\fR.
+.PP
+If you use preprocessor directives to choose one of two
+versions of a function, use
+.PP
+.Vb 3
+\&    #if ... version1
+\&    #else /* ... version2  */
+\&    #endif
+.Ve
+.PP
+and not
+.PP
+.Vb 4
+\&    #if ... version1
+\&    #endif
+\&    #if ... version2
+\&    #endif
+.Ve
+.PP
+because otherwise \fBxsubpp\fR will believe that you made a duplicate
+definition of the function.  Also, put a blank line before the
+#else/#endif so it will not be seen as part of the function body.
+.SS "Using XS With C++"
+.IX Subsection "Using XS With C++"
+If an XSUB name contains \f(CW\*(C`::\*(C'\fR, it is considered to be a C++ method.
+The generated Perl function will assume that
+its first argument is an object pointer.  The object pointer
+will be stored in a variable called THIS.  The object should
+have been created by C++ with the \fBnew()\fR function and should
+be blessed by Perl with the \fBsv_setref_pv()\fR macro.  The
+blessing of the object by Perl can be handled by a typemap.  An example
+typemap is shown at the end of this section.
+.PP
+If the return type of the XSUB includes \f(CW\*(C`static\*(C'\fR, the method is considered
+to be a static method.  It will call the C++
+function using the \fBclass::method()\fR syntax.  If the method is not static
+the function will be called using the THIS\->\fBmethod()\fR syntax.
+.PP
+The next examples will use the following C++ class.
+.PP
+.Vb 6
+\&     class color {
+\&          public:
+\&          color();
+\&          ~color();
+\&          int blue();
+\&          void set_blue( int );
+\&
+\&          private:
+\&          int c_blue;
+\&     };
+.Ve
+.PP
+The XSUBs for the \fBblue()\fR and \fBset_blue()\fR methods are defined with the class
+name but the parameter for the object (THIS, or "self") is implicit and is
+not listed.
+.PP
+.Vb 2
+\&     int
+\&     color::blue()
+\&
+\&     void
+\&     color::set_blue( val )
+\&          int val
+.Ve
+.PP
+Both Perl functions will expect an object as the first parameter.  In the
+generated C++ code the object is called \f(CW\*(C`THIS\*(C'\fR, and the method call will
+be performed on this object.  So in the C++ code the \fBblue()\fR and \fBset_blue()\fR
+methods will be called as this:
+.PP
+.Vb 1
+\&     RETVAL = THIS\->blue();
+\&
+\&     THIS\->set_blue( val );
+.Ve
+.PP
+You could also write a single get/set method using an optional argument:
+.PP
+.Vb 10
+\&     int
+\&     color::blue( val = NO_INIT )
+\&         int val
+\&         PROTOTYPE $;$
+\&         CODE:
+\&             if (items > 1)
+\&                 THIS\->set_blue( val );
+\&             RETVAL = THIS\->blue();
+\&         OUTPUT:
+\&             RETVAL
+.Ve
+.PP
+If the function's name is \fBDESTROY\fR then the C++ \f(CW\*(C`delete\*(C'\fR function will be
+called and \f(CW\*(C`THIS\*(C'\fR will be given as its parameter.  The generated C++ code for
+.PP
+.Vb 2
+\&     void
+\&     color::DESTROY()
+.Ve
+.PP
+will look like this:
+.PP
+.Vb 1
+\&     color *THIS = ...;  // Initialized as in typemap
+\&
+\&     delete THIS;
+.Ve
+.PP
+If the function's name is \fBnew\fR then the C++ \f(CW\*(C`new\*(C'\fR function will be called
+to create a dynamic C++ object.  The XSUB will expect the class name, which
+will be kept in a variable called \f(CW\*(C`CLASS\*(C'\fR, to be given as the first
+argument.
+.PP
+.Vb 2
+\&     color *
+\&     color::new()
+.Ve
+.PP
+The generated C++ code will call \f(CW\*(C`new\*(C'\fR.
+.PP
+.Vb 1
+\&     RETVAL = new color();
+.Ve
+.PP
+The following is an example of a typemap that could be used for this C++
+example.
+.PP
+.Vb 2
+\&    TYPEMAP
+\&    color *  O_OBJECT
+\&
+\&    OUTPUT
+\&    # The Perl object is blessed into \*(AqCLASS\*(Aq, which should be a
+\&    # char* having the name of the package for the blessing.
+\&    O_OBJECT
+\&        sv_setref_pv( $arg, CLASS, (void*)$var );
+\&
+\&    INPUT
+\&    O_OBJECT
+\&        if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
+\&            $var = ($type)SvIV((SV*)SvRV( $arg ));
+\&        else{
+\&            warn(\e"${Package}::$func_name() \-\- \e"
+\&                \e"$var is not a blessed SV reference\e");
+\&            XSRETURN_UNDEF;
+\&        }
+.Ve
+.SS "Interface Strategy"
+.IX Subsection "Interface Strategy"
+When designing an interface between Perl and a C library a straight
+translation from C to XS (such as created by \f(CW\*(C`h2xs \-x\*(C'\fR) is often sufficient.
+However, sometimes the interface will look
+very C\-like and occasionally nonintuitive, especially when the C function
+modifies one of its parameters, or returns failure inband (as in "negative
+return values mean failure").  In cases where the programmer wishes to
+create a more Perl-like interface the following strategy may help to
+identify the more critical parts of the interface.
+.PP
+Identify the C functions with input/output or output parameters.  The XSUBs for
+these functions may be able to return lists to Perl.
+.PP
+Identify the C functions which use some inband info as an indication
+of failure.  They may be
+candidates to return undef or an empty list in case of failure.  If the
+failure may be detected without a call to the C function, you may want to use
+an INIT: section to report the failure.  For failures detectable after the C
+function returns one may want to use a POSTCALL: section to process the
+failure.  In more complicated cases use CODE: or PPCODE: sections.
+.PP
+If many functions use the same failure indication based on the return value,
+you may want to create a special typedef to handle this situation.  Put
+.PP
+.Vb 1
+\&  typedef int negative_is_failure;
+.Ve
+.PP
+near the beginning of XS file, and create an OUTPUT typemap entry
+for \f(CW\*(C`negative_is_failure\*(C'\fR which converts negative values to \f(CW\*(C`undef\*(C'\fR, or
+maybe \fBcroak()\fRs.  After this the return value of type \f(CW\*(C`negative_is_failure\*(C'\fR
+will create more Perl-like interface.
+.PP
+Identify which values are used by only the C and XSUB functions
+themselves, say, when a parameter to a function should be a contents of a
+global variable.  If Perl does not need to access the contents of the value
+then it may not be necessary to provide a translation for that value
+from C to Perl.
+.PP
+Identify the pointers in the C function parameter lists and return
+values.  Some pointers may be used to implement input/output or
+output parameters, they can be handled in XS with the \f(CW\*(C`&\*(C'\fR unary operator,
+and, possibly, using the NO_INIT keyword.
+Some others will require handling of types like \f(CW\*(C`int *\*(C'\fR, and one needs
+to decide what a useful Perl translation will do in such a case.  When
+the semantic is clear, it is advisable to put the translation into a typemap
+file.
+.PP
+Identify the structures used by the C functions.  In many
+cases it may be helpful to use the T_PTROBJ typemap for
+these structures so they can be manipulated by Perl as
+blessed objects.  (This is handled automatically by \f(CW\*(C`h2xs \-x\*(C'\fR.)
+.PP
+If the same C type is used in several different contexts which require
+different translations, \f(CW\*(C`typedef\*(C'\fR several new types mapped to this C type,
+and create separate \fItypemap\fR entries for these new types.  Use these
+types in declarations of return type and parameters to XSUBs.
+.SS "Perl Objects And C Structures"
+.IX Subsection "Perl Objects And C Structures"
+When dealing with C structures one should select either
+\&\fBT_PTROBJ\fR or \fBT_PTRREF\fR for the XS type.  Both types are
+designed to handle pointers to complex objects.  The
+T_PTRREF type will allow the Perl object to be unblessed
+while the T_PTROBJ type requires that the object be blessed.
+By using T_PTROBJ one can achieve a form of type-checking
+because the XSUB will attempt to verify that the Perl object
+is of the expected type.
+.PP
+The following XS code shows the \fBgetnetconfigent()\fR function which is used
+with ONC+ TIRPC.  The \fBgetnetconfigent()\fR function will return a pointer to a
+C structure and has the C prototype shown below.  The example will
+demonstrate how the C pointer will become a Perl reference.  Perl will
+consider this reference to be a pointer to a blessed object and will
+attempt to call a destructor for the object.  A destructor will be
+provided in the XS source to free the memory used by \fBgetnetconfigent()\fR.
+Destructors in XS can be created by specifying an XSUB function whose name
+ends with the word \fBDESTROY\fR.  XS destructors can be used to free memory
+which may have been malloc'd by another XSUB.
+.PP
+.Vb 1
+\&     struct netconfig *getnetconfigent(const char *netid);
+.Ve
+.PP
+A \f(CW\*(C`typedef\*(C'\fR will be created for \f(CW\*(C`struct netconfig\*(C'\fR.  The Perl
+object will be blessed in a class matching the name of the C
+type, with the tag \f(CW\*(C`Ptr\*(C'\fR appended, and the name should not
+have embedded spaces if it will be a Perl package name.  The
+destructor will be placed in a class corresponding to the
+class of the object and the PREFIX keyword will be used to
+trim the name to the word DESTROY as Perl will expect.
+.PP
+.Vb 1
+\&     typedef struct netconfig Netconfig;
+\&
+\&     MODULE = RPC  PACKAGE = RPC
+\&
+\&     Netconfig *
+\&     getnetconfigent(netid)
+\&          char *netid
+\&
+\&     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
+\&
+\&     void
+\&     rpcb_DESTROY(netconf)
+\&          Netconfig *netconf
+\&        CODE:
+\&          printf("Now in NetconfigPtr::DESTROY\en");
+\&          free( netconf );
+.Ve
+.PP
+This example requires the following typemap entry.  Consult
+perlxstypemap for more information about adding new typemaps
+for an extension.
+.PP
+.Vb 2
+\&     TYPEMAP
+\&     Netconfig *  T_PTROBJ
+.Ve
+.PP
+This example will be used with the following Perl statements.
+.PP
+.Vb 2
+\&     use RPC;
+\&     $netconf = getnetconfigent("udp");
+.Ve
+.PP
+When Perl destroys the object referenced by \f(CW$netconf\fR it will send the
+object to the supplied XSUB DESTROY function.  Perl cannot determine, and
+does not care, that this object is a C struct and not a Perl object.  In
+this sense, there is no difference between the object created by the
+\&\fBgetnetconfigent()\fR XSUB and an object created by a normal Perl subroutine.
+.SS "Safely Storing Static Data in XS"
+.IX Subsection "Safely Storing Static Data in XS"
+Starting with Perl 5.8, a macro framework has been defined to allow
+static data to be safely stored in XS modules that will be accessed from
+a multi-threaded Perl.
+.PP
+Although primarily designed for use with multi-threaded Perl, the macros
+have been designed so that they will work with non-threaded Perl as well.
+.PP
+It is therefore strongly recommended that these macros be used by all
+XS modules that make use of static data.
+.PP
+The easiest way to get a template set of macros to use is by specifying
+the \f(CW\*(C`\-g\*(C'\fR (\f(CW\*(C`\-\-global\*(C'\fR) option with h2xs (see h2xs).
+.PP
+Below is an example module that makes use of the macros.
+.PP
+.Vb 4
+\&    #define PERL_NO_GET_CONTEXT
+\&    #include "EXTERN.h"
+\&    #include "perl.h"
+\&    #include "XSUB.h"
+\&
+\&    /* Global Data */
+\&
+\&    #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
+\&
+\&    typedef struct {
+\&        int count;
+\&        char name[3][100];
+\&    } my_cxt_t;
+\&
+\&    START_MY_CXT
+\&
+\&    MODULE = BlindMice           PACKAGE = BlindMice
+\&
+\&    BOOT:
+\&    {
+\&        MY_CXT_INIT;
+\&        MY_CXT.count = 0;
+\&        strcpy(MY_CXT.name[0], "None");
+\&        strcpy(MY_CXT.name[1], "None");
+\&        strcpy(MY_CXT.name[2], "None");
+\&    }
+\&
+\&    int
+\&    newMouse(char * name)
+\&        PREINIT:
+\&          dMY_CXT;
+\&        CODE:
+\&          if (MY_CXT.count >= 3) {
+\&              warn("Already have 3 blind mice");
+\&              RETVAL = 0;
+\&          }
+\&          else {
+\&              RETVAL = ++ MY_CXT.count;
+\&              strcpy(MY_CXT.name[MY_CXT.count \- 1], name);
+\&          }
+\&        OUTPUT:
+\&          RETVAL
+\&
+\&    char *
+\&    get_mouse_name(index)
+\&          int index
+\&        PREINIT:
+\&          dMY_CXT;
+\&        CODE:
+\&          if (index > MY_CXT.count)
+\&            croak("There are only 3 blind mice.");
+\&          else
+\&            RETVAL = MY_CXT.name[index \- 1];
+\&        OUTPUT:
+\&          RETVAL
+\&
+\&    void
+\&    CLONE(...)
+\&        CODE:
+\&          MY_CXT_CLONE;
+.Ve
+.PP
+\fIMY_CXT REFERENCE\fR
+.IX Subsection "MY_CXT REFERENCE"
+.IP MY_CXT_KEY 5
+.IX Item "MY_CXT_KEY"
+This macro is used to define a unique key to refer to the static data
+for an XS module. The suggested naming scheme, as used by h2xs, is to
+use a string that consists of the module name, the string "::_guts"
+and the module version number.
+.Sp
+.Vb 1
+\&    #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
+.Ve
+.IP "typedef my_cxt_t" 5
+.IX Item "typedef my_cxt_t"
+This struct typedef \fImust\fR always be called \f(CW\*(C`my_cxt_t\*(C'\fR. The other
+\&\f(CW\*(C`CXT*\*(C'\fR macros assume the existence of the \f(CW\*(C`my_cxt_t\*(C'\fR typedef name.
+.Sp
+Declare a typedef named \f(CW\*(C`my_cxt_t\*(C'\fR that is a structure that contains
+all the data that needs to be interpreter-local.
+.Sp
+.Vb 3
+\&    typedef struct {
+\&        int some_value;
+\&    } my_cxt_t;
+.Ve
+.IP START_MY_CXT 5
+.IX Item "START_MY_CXT"
+Always place the START_MY_CXT macro directly after the declaration
+of \f(CW\*(C`my_cxt_t\*(C'\fR.
+.IP MY_CXT_INIT 5
+.IX Item "MY_CXT_INIT"
+The MY_CXT_INIT macro initializes storage for the \f(CW\*(C`my_cxt_t\*(C'\fR struct.
+.Sp
+It \fImust\fR be called exactly once, typically in a BOOT: section. If you
+are maintaining multiple interpreters, it should be called once in each
+interpreter instance, except for interpreters cloned from existing ones.
+(But see "MY_CXT_CLONE" below.)
+.IP dMY_CXT 5
+.IX Item "dMY_CXT"
+Use the dMY_CXT macro (a declaration) in all the functions that access
+MY_CXT.
+.IP MY_CXT 5
+.IX Item "MY_CXT"
+Use the MY_CXT macro to access members of the \f(CW\*(C`my_cxt_t\*(C'\fR struct. For
+example, if \f(CW\*(C`my_cxt_t\*(C'\fR is
+.Sp
+.Vb 3
+\&    typedef struct {
+\&        int index;
+\&    } my_cxt_t;
+.Ve
+.Sp
+then use this to access the \f(CW\*(C`index\*(C'\fR member
+.Sp
+.Vb 2
+\&    dMY_CXT;
+\&    MY_CXT.index = 2;
+.Ve
+.IP aMY_CXT/pMY_CXT 5
+.IX Item "aMY_CXT/pMY_CXT"
+\&\f(CW\*(C`dMY_CXT\*(C'\fR may be quite expensive to calculate, and to avoid the overhead
+of invoking it in each function it is possible to pass the declaration
+onto other functions using the \f(CW\*(C`aMY_CXT\*(C'\fR/\f(CW\*(C`pMY_CXT\*(C'\fR macros, eg
+.Sp
+.Vb 5
+\&    void sub1() {
+\&        dMY_CXT;
+\&        MY_CXT.index = 1;
+\&        sub2(aMY_CXT);
+\&    }
+\&
+\&    void sub2(pMY_CXT) {
+\&        MY_CXT.index = 2;
+\&    }
+.Ve
+.Sp
+Analogously to \f(CW\*(C`pTHX\*(C'\fR, there are equivalent forms for when the macro is the
+first or last in multiple arguments, where an underscore represents a
+comma, i.e.  \f(CW\*(C`_aMY_CXT\*(C'\fR, \f(CW\*(C`aMY_CXT_\*(C'\fR, \f(CW\*(C`_pMY_CXT\*(C'\fR and \f(CW\*(C`pMY_CXT_\*(C'\fR.
+.IP MY_CXT_CLONE 5
+.IX Item "MY_CXT_CLONE"
+By default, when a new interpreter is created as a copy of an existing one
+(eg via \f(CW\*(C`threads\->create()\*(C'\fR), both interpreters share the same physical
+my_cxt_t structure. Calling \f(CW\*(C`MY_CXT_CLONE\*(C'\fR (typically via the package's
+\&\f(CWCLONE()\fR function), causes a byte-for-byte copy of the structure to be
+taken, and any future dMY_CXT will cause the copy to be accessed instead.
+.IP MY_CXT_INIT_INTERP(my_perl) 5
+.IX Item "MY_CXT_INIT_INTERP(my_perl)"
+.PD 0
+.IP dMY_CXT_INTERP(my_perl) 5
+.IX Item "dMY_CXT_INTERP(my_perl)"
+.PD
+These are versions of the macros which take an explicit interpreter as an
+argument.
+.PP
+Note that these macros will only work together within the \fIsame\fR source
+file; that is, a dMY_CTX in one source file will access a different structure
+than a dMY_CTX in another source file.
+.SS "Thread-aware system interfaces"
+.IX Subsection "Thread-aware system interfaces"
+Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
+system/library interfaces that have thread-aware versions
+(e.g. \fBgetpwent_r()\fR) into frontend macros (e.g. \fBgetpwent()\fR) that
+correctly handle the multithreaded interaction with the Perl
+interpreter.  This will happen transparently, the only thing
+you need to do is to instantiate a Perl interpreter.
+.PP
+This wrapping happens always when compiling Perl core source
+(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
+defined).  When compiling XS code outside of the Perl core, the wrapping
+does not take place before Perl 5.28.  Starting in that release you can
+.PP
+.Vb 1
+\& #define PERL_REENTRANT
+.Ve
+.PP
+in your code to enable the wrapping.  It is advisable to do so if you
+are using such functions, as intermixing the \f(CW\*(C`_r\*(C'\fR\-forms (as Perl compiled
+for multithreaded operation will do) and the \f(CW\*(C`_r\*(C'\fR\-less forms is neither
+well-defined (inconsistent results, data corruption, or even crashes
+become more likely), nor is it very portable.  Unfortunately, not all
+systems have all the \f(CW\*(C`_r\*(C'\fR forms, but using this \f(CW\*(C`#define\*(C'\fR gives you
+whatever protection that Perl is aware is available on each system.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+File \f(CW\*(C`RPC.xs\*(C'\fR: Interface to some ONC+ RPC bind library functions.
+.PP
+.Vb 4
+\&     #define PERL_NO_GET_CONTEXT
+\&     #include "EXTERN.h"
+\&     #include "perl.h"
+\&     #include "XSUB.h"
+\&
+\&     /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
+\&     #include <tirpc/rpc.h>
+\&
+\&     typedef struct netconfig Netconfig;
+\&
+\&     MODULE = RPC  PACKAGE = RPC
+\&
+\&     SV *
+\&     rpcb_gettime(host="localhost")
+\&          char *host
+\&        PREINIT:
+\&          time_t  timep;
+\&        CODE:
+\&          ST(0) = sv_newmortal();
+\&          if( rpcb_gettime( host, &timep ) )
+\&               sv_setnv( ST(0), (double)timep );
+\&
+\&     Netconfig *
+\&     getnetconfigent(netid="udp")
+\&          char *netid
+\&
+\&     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
+\&
+\&     void
+\&     rpcb_DESTROY(netconf)
+\&          Netconfig *netconf
+\&        CODE:
+\&          printf("NetconfigPtr::DESTROY\en");
+\&          free( netconf );
+.Ve
+.PP
+File \f(CW\*(C`typemap\*(C'\fR: Custom typemap for RPC.xs. (cf. perlxstypemap)
+.PP
+.Vb 2
+\&     TYPEMAP
+\&     Netconfig *  T_PTROBJ
+.Ve
+.PP
+File \f(CW\*(C`RPC.pm\*(C'\fR: Perl module for the RPC extension.
+.PP
+.Vb 1
+\&     package RPC;
+\&
+\&     require Exporter;
+\&     require DynaLoader;
+\&     @ISA = qw(Exporter DynaLoader);
+\&     @EXPORT = qw(rpcb_gettime getnetconfigent);
+\&
+\&     bootstrap RPC;
+\&     1;
+.Ve
+.PP
+File \f(CW\*(C`rpctest.pl\*(C'\fR: Perl test program for the RPC extension.
+.PP
+.Vb 1
+\&     use RPC;
+\&
+\&     $netconf = getnetconfigent();
+\&     $a = rpcb_gettime();
+\&     print "time = $a\en";
+\&     print "netconf = $netconf\en";
+\&
+\&     $netconf = getnetconfigent("tcp");
+\&     $a = rpcb_gettime("poplar");
+\&     print "time = $a\en";
+\&     print "netconf = $netconf\en";
+.Ve
+.PP
+In Makefile.PL add \-ltirpc and \-I/usr/include/tirpc.
+.SH CAVEATS
+.IX Header "CAVEATS"
+XS code has full access to system calls including C library functions.
+It thus has the capability of interfering with things that the Perl core
+or other modules have set up, such as signal handlers or file handles.
+It could mess with the memory, or any number of harmful things.  Don't.
+.PP
+Some modules have an event loop, waiting for user-input.  It is highly
+unlikely that two such modules would work adequately together in a
+single Perl application.
+.PP
+In general, the perl interpreter views itself as the center of the
+universe as far as the Perl program goes.  XS code is viewed as a
+help-mate, to accomplish things that perl doesn't do, or doesn't do fast
+enough, but always subservient to perl.  The closer XS code adheres to
+this model, the less likely conflicts will occur.
+.PP
+One area where there has been conflict is in regards to C locales.  (See
+perllocale.)  perl, with one exception and unless told otherwise,
+sets up the underlying locale the program is running in to the locale
+passed
+into it from the environment.  This is an important difference from a
+generic C language program, where the underlying locale is the "C"
+locale unless the program changes it.  As of v5.20, this underlying
+locale is completely hidden from pure Perl code outside the lexical
+scope of \f(CW\*(C`use\ locale\*(C'\fR except for a couple of function calls in the
+POSIX module which of necessity use it.  But the underlying locale, with
+that
+one exception is exposed to XS code, affecting all C library routines
+whose behavior is locale-dependent.  Your XS code better not assume that
+the underlying locale is "C".  The exception is the
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR
+locale category, and the reason it is an exception is that experience
+has shown that it can be problematic for XS code, whereas we have not
+had reports of problems with the
+other locale categories.  And the reason
+for this one category being problematic is that the character used as a
+decimal point can vary.  Many European languages use a comma, whereas
+English, and hence Perl are expecting a dot (U+002E: FULL STOP).  Many
+modules can handle only the radix character being a dot, and so perl
+attempts to make it so.  Up through Perl v5.20, the attempt was merely
+to set \f(CW\*(C`LC_NUMERIC\*(C'\fR upon startup to the \f(CW"C"\fR locale.  Any
+\&\fBsetlocale()\fR otherwise would change
+it; this caused some failures.  Therefore, starting in v5.22, perl tries
+to keep \f(CW\*(C`LC_NUMERIC\*(C'\fR always set to \f(CW"C"\fR for XS code.
+.PP
+To summarize, here's what to expect and how to handle locales in XS code:
+.IP "Non-locale-aware XS code" 4
+.IX Item "Non-locale-aware XS code"
+Keep in mind that even if you think your code is not locale-aware, it
+may call a library function that is.  Hopefully the man page for such
+a function will indicate that dependency, but the documentation is
+imperfect.
+.Sp
+The current locale is exposed to XS code except possibly \f(CW\*(C`LC_NUMERIC\*(C'\fR
+(explained in the next paragraph).
+There have not been reports of problems with the other categories.
+Perl initializes things on start-up so that the current locale is the
+one which is indicated by the user's environment in effect at that time.
+See "ENVIRONMENT" in perllocale.
+.Sp
+However, up through v5.20, Perl initialized things on start-up so that
+\&\f(CW\*(C`LC_NUMERIC\*(C'\fR was set to the "C" locale.  But if any code anywhere
+changed it, it would stay changed.  This means that your module can't
+count on \f(CW\*(C`LC_NUMERIC\*(C'\fR being something in particular, and you can't
+expect floating point numbers (including version strings) to have dots
+in them.  If you don't allow for a non-dot, your code could break if
+anyone anywhere changed the locale.  For this reason, v5.22 changed
+the behavior so that Perl tries to keep \f(CW\*(C`LC_NUMERIC\*(C'\fR in the "C" locale
+except around the operations internally where it should be something
+else.  Misbehaving XS code will always be able to change the locale
+anyway, but the most common instance of this is checked for and
+handled.
+.IP "Locale-aware XS code" 4
+.IX Item "Locale-aware XS code"
+If the locale from the user's environment is desired, there should be no
+need for XS code to set the locale except for \f(CW\*(C`LC_NUMERIC\*(C'\fR, as perl has
+already set the others up.  XS code should avoid changing the locale, as
+it can adversely affect other, unrelated, code and may not be
+thread-safe.  To minimize problems, the macros
+"STORE_LC_NUMERIC_SET_TO_NEEDED" in perlapi,
+"STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" in perlapi, and
+"RESTORE_LC_NUMERIC" in perlapi should be used to affect any needed
+change.
+.Sp
+But, starting with Perl v5.28, locales are thread-safe on platforms that
+support this functionality.  Windows has this starting with Visual
+Studio 2005.  Many other modern platforms support the thread-safe POSIX
+2008 functions.  The C \f(CW\*(C`#define\*(C'\fR \f(CW\*(C`USE_THREAD_SAFE_LOCALE\*(C'\fR will be
+defined iff this build is using these.  From Perl-space, the read-only
+variable \f(CW\*(C`${SAFE_LOCALES}\*(C'\fR is 1 if either the build is not threaded, or
+if \f(CW\*(C`USE_THREAD_SAFE_LOCALE\*(C'\fR is defined; otherwise it is 0.
+.Sp
+The way this works under-the-hood is that every thread has a choice of
+using a locale specific to it (this is the Windows and POSIX 2008
+functionality), or the global locale that is accessible to all threads
+(this is the functionality that has always been there).  The
+implementations for Windows and POSIX are completely different.  On
+Windows, the runtime can be set up so that the standard
+\&\f(CWsetlocale(3)\fR function either only knows about the global locale or
+the locale for this thread.  On POSIX, \f(CW\*(C`setlocale\*(C'\fR always deals with
+the global locale, and other functions have been created to handle
+per-thread locales.  Perl makes this transparent to perl-space code.  It
+continues to use \f(CWPOSIX::setlocale()\fR, and the interpreter translates
+that into the per-thread functions.
+.Sp
+All other locale-sensitive functions automatically use the per-thread
+locale, if that is turned on, and failing that, the global locale.  Thus
+calls to \f(CW\*(C`setlocale\*(C'\fR are ineffective on POSIX systems for the current
+thread if that thread is using a per-thread locale.  If perl is compiled
+for single-thread operation, it does not use the per-thread functions,
+so \f(CW\*(C`setlocale\*(C'\fR does work as expected.
+.Sp
+If you have loaded the \f(CW\*(C`POSIX\*(C'\fR module you can use the methods given
+in perlcall to call \f(CW\*(C`POSIX::setlocale\*(C'\fR to safely
+change or query the locale (on systems where it is safe to do so), or
+you can use the new 5.28 function "Perl_setlocale" in perlapi instead,
+which is a drop-in replacement for the system \f(CWsetlocale(3)\fR, and
+handles single-threaded and multi-threaded applications transparently.
+.Sp
+There are some locale-related library calls that still aren't
+thread-safe because they return data in a buffer global to all threads.
+In the past, these didn't matter as locales weren't thread-safe at all.
+But now you have to be aware of them in case your module is called in a
+multi-threaded application.  The known ones are
+.Sp
+.Vb 8
+\& asctime()
+\& ctime()
+\& gcvt() [POSIX.1\-2001 only (function removed in POSIX.1\-2008)]
+\& getdate()
+\& wcrtomb() if its final argument is NULL
+\& wcsrtombs() if its final argument is NULL
+\& wcstombs()
+\& wctomb()
+.Ve
+.Sp
+Some of these shouldn't really be called in a Perl application, and for
+others there are thread-safe versions of these already implemented:
+.Sp
+.Vb 3
+\& asctime_r()
+\& ctime_r()
+\& Perl_langinfo()
+.Ve
+.Sp
+The \f(CW\*(C`_r\*(C'\fR forms are automatically used, starting in Perl 5.28, if you
+compile your code, with
+.Sp
+.Vb 1
+\& #define PERL_REENTRANT
+.Ve
+.Sp
+See also "Perl_langinfo" in perlapi.
+You can use the methods given in perlcall, to get the best available
+locale-safe versions of these
+.Sp
+.Vb 3
+\& POSIX::localeconv()
+\& POSIX::wcstombs()
+\& POSIX::wctomb()
+.Ve
+.Sp
+And note, that some items returned by \f(CW\*(C`Localeconv\*(C'\fR are available
+through "Perl_langinfo" in perlapi.
+.Sp
+The others shouldn't be used in a threaded application.
+.Sp
+Some modules may call a non-perl library that is locale-aware.  This is
+fine as long as it doesn't try to query or change the locale using the
+system \f(CW\*(C`setlocale\*(C'\fR.  But if these do call the system \f(CW\*(C`setlocale\*(C'\fR,
+those calls may be ineffective.  Instead,
+\&\f(CW\*(C`Perl_setlocale\*(C'\fR works in all circumstances.
+Plain setlocale is ineffective on multi-threaded POSIX 2008 systems.  It
+operates only on the global locale, whereas each thread has its own
+locale, paying no attention to the global one.  Since converting
+these non-Perl libraries to \f(CW\*(C`Perl_setlocale\*(C'\fR is out of the question,
+there is a new function in v5.28
+\&\f(CW\*(C`switch_to_global_locale\*(C'\fR that will
+switch the thread it is called from so that any system \f(CW\*(C`setlocale\*(C'\fR
+calls will have their desired effect.  The function
+\&\f(CW\*(C`sync_locale\*(C'\fR must be called before returning to
+perl.
+.Sp
+This thread can change the locale all it wants and it won't affect any
+other thread, except any that also have been switched to the global
+locale.  This means that a multi-threaded application can have a single
+thread using an alien library without a problem; but no more than a
+single thread can be so-occupied.  Bad results likely will happen.
+.Sp
+In perls without multi-thread locale support, some alien libraries,
+such as \f(CW\*(C`Gtk\*(C'\fR change locales.  This can cause problems for the Perl
+core and other modules.  For these, before control is returned to
+perl, starting in v5.20.1, calling the function
+\&\fBsync_locale()\fR from XS should be sufficient to
+avoid most of these problems.  Prior to this, you need a pure Perl
+statement that does this:
+.Sp
+.Vb 1
+\& POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
+.Ve
+.Sp
+or use the methods given in perlcall.
+.SH "XS VERSION"
+.IX Header "XS VERSION"
+This document covers features supported by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR
+(also known as \f(CW\*(C`xsubpp\*(C'\fR) 3.51
+.SH "AUTHOR DIAGNOSTICS"
+.IX Header "AUTHOR DIAGNOSTICS"
+As of version 3.49 certain warnings are disabled by default. While developing
+you can set \f(CW$ENV{AUTHOR_WARNINGS}\fR to true in your environment or in your
+Makefile.PL, or set \f(CW$ExtUtils::ParseXS::AUTHOR_WARNINGS\fR to true via code, or
+pass \f(CW\*(C`author_warnings=>1\*(C'\fR into \fBprocess_file()\fR explicitly.  Currently this will
+enable stricter alias checking but more warnings might be added in the future.
+The kind of warnings this will enable are only helpful to the author of the XS
+file, and the diagnostics produced will not include installation specific
+details so they are only useful to the maintainer of the XS code itself.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Originally written by Dean Roehrich <\fIroehrich@cray.com\fR>.
+.PP
+Maintained since 1996 by The Perl Porters <\fIperl5\-porters@perl.org\fR>.
diff --git a/upstream/mageia-cauldron/man1/perlxstut.1 b/upstream/mageia-cauldron/man1/perlxstut.1
new file mode 100644
index 00000000..8d7d53d4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlxstut.1
@@ -0,0 +1,1499 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLXSTUT 1"
+.TH PERLXSTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlxstut \- Tutorial for writing XSUBs
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This tutorial will educate the reader on the steps involved in creating
+a Perl extension.  The reader is assumed to have access to perlguts,
+perlapi and perlxs.
+.PP
+This tutorial starts with very simple examples and becomes more complex,
+with each new example adding new features.  Certain concepts may not be
+completely explained until later in the tutorial in order to slowly ease
+the reader into building extensions.
+.PP
+This tutorial was written from a Unix point of view.  Where I know them
+to be otherwise different for other platforms (e.g. Win32), I will list
+them.  If you find something that was missed, please let me know.
+.SH "SPECIAL NOTES"
+.IX Header "SPECIAL NOTES"
+.SS make
+.IX Subsection "make"
+This tutorial assumes that the make program that Perl is configured to
+use is called \f(CW\*(C`make\*(C'\fR.  Instead of running "make" in the examples that
+follow, you may have to substitute whatever make program Perl has been
+configured to use.  Running \fBperl \-V:make\fR should tell you what it is.
+.SS "Version caveat"
+.IX Subsection "Version caveat"
+When writing a Perl extension for general consumption, one should expect that
+the extension will be used with versions of Perl different from the
+version available on your machine.  Since you are reading this document,
+the version of Perl on your machine is probably 5.005 or later, but the users
+of your extension may have more ancient versions.
+.PP
+To understand what kinds of incompatibilities one may expect, and in the rare
+case that the version of Perl on your machine is older than this document,
+see the section on "Troubleshooting these Examples" for more information.
+.PP
+If your extension uses some features of Perl which are not available on older
+releases of Perl, your users would appreciate an early meaningful warning.
+You would probably put this information into the \fIREADME\fR file, but nowadays
+installation of extensions may be performed automatically, guided by \fICPAN.pm\fR
+module or other tools.
+.PP
+In MakeMaker-based installations, \fIMakefile.PL\fR provides the earliest
+opportunity to perform version checks.  One can put something like this
+in \fIMakefile.PL\fR for this purpose:
+.PP
+.Vb 8
+\&    eval { require 5.007 }
+\&        or die <<EOD;
+\&    ############
+\&    ### This module uses frobnication framework which is not available
+\&    ### before version 5.007 of Perl.  Upgrade your Perl before
+\&    ### installing Kara::Mba.
+\&    ############
+\&    EOD
+.Ve
+.SS "Dynamic Loading versus Static Loading"
+.IX Subsection "Dynamic Loading versus Static Loading"
+It is commonly thought that if a system does not have the capability to
+dynamically load a library, you cannot build XSUBs.  This is incorrect.
+You \fIcan\fR build them, but you must link the XSUBs subroutines with the
+rest of Perl, creating a new executable.  This situation is similar to
+Perl 4.
+.PP
+This tutorial can still be used on such a system.  The XSUB build mechanism
+will check the system and build a dynamically-loadable library if possible,
+or else a static library and then, optionally, a new statically-linked
+executable with that static library linked in.
+.PP
+Should you wish to build a statically-linked executable on a system which
+can dynamically load libraries, you may, in all the following examples,
+where the command "\f(CW\*(C`make\*(C'\fR" with no arguments is executed, run the command
+"\f(CW\*(C`make perl\*(C'\fR" instead.
+.PP
+If you have generated such a statically-linked executable by choice, then
+instead of saying "\f(CW\*(C`make test\*(C'\fR", you should say "\f(CW\*(C`make test_static\*(C'\fR".
+On systems that cannot build dynamically-loadable libraries at all, simply
+saying "\f(CW\*(C`make test\*(C'\fR" is sufficient.
+.SS "Threads and PERL_NO_GET_CONTEXT"
+.IX Subsection "Threads and PERL_NO_GET_CONTEXT"
+For threaded builds, perl requires the context pointer for the current
+thread, without \f(CW\*(C`PERL_NO_GET_CONTEXT\*(C'\fR, perl will call a function to
+retrieve the context.
+.PP
+For improved performance, include:
+.PP
+.Vb 1
+\&  #define PERL_NO_GET_CONTEXT
+.Ve
+.PP
+as shown below.
+.PP
+For more details, see perlguts.
+.SH TUTORIAL
+.IX Header "TUTORIAL"
+Now let's go on with the show!
+.SS "EXAMPLE 1"
+.IX Subsection "EXAMPLE 1"
+Our first extension will be very simple.  When we call the routine in the
+extension, it will print out a well-known message and return.
+.PP
+Run "\f(CW\*(C`h2xs \-A \-n Mytest\*(C'\fR".  This creates a directory named Mytest,
+possibly under ext/ if that directory exists in the current working
+directory.  Several files will be created under the Mytest dir, including
+MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, and Changes.
+.PP
+The MANIFEST file contains the names of all the files just created in the
+Mytest directory.
+.PP
+The file Makefile.PL should look something like this:
+.PP
+.Vb 1
+\&    use ExtUtils::MakeMaker;
+\&
+\&    # See lib/ExtUtils/MakeMaker.pm for details of how to influence
+\&    # the contents of the Makefile that is written.
+\&    WriteMakefile(
+\&        NAME         => \*(AqMytest\*(Aq,
+\&        VERSION_FROM => \*(AqMytest.pm\*(Aq, # finds $VERSION
+\&        LIBS         => [\*(Aq\*(Aq],        # e.g., \*(Aq\-lm\*(Aq
+\&        DEFINE       => \*(Aq\*(Aq,          # e.g., \*(Aq\-DHAVE_SOMETHING\*(Aq
+\&        INC          => \*(Aq\-I\*(Aq,        # e.g., \*(Aq\-I. \-I/usr/include/other\*(Aq
+\&    );
+.Ve
+.PP
+The file Mytest.pm should start with something like this:
+.PP
+.Vb 1
+\&    package Mytest;
+\&
+\&    use 5.008008;
+\&    use strict;
+\&    use warnings;
+\&
+\&    require Exporter;
+\&
+\&    our @ISA = qw(Exporter);
+\&    our %EXPORT_TAGS = ( \*(Aqall\*(Aq => [ qw(
+\&
+\&    ) ] );
+\&
+\&    our @EXPORT_OK = ( @{ $EXPORT_TAGS{\*(Aqall\*(Aq} } );
+\&
+\&    our @EXPORT = qw(
+\&
+\&    );
+\&
+\&    our $VERSION = \*(Aq0.01\*(Aq;
+\&
+\&    require XSLoader;
+\&    XSLoader::load(\*(AqMytest\*(Aq, $VERSION);
+\&
+\&    # Preloaded methods go here.
+\&
+\&    1;
+\&    _\|_END_\|_
+\&    # Below is the stub of documentation for your module. You better
+\&    # edit it!
+.Ve
+.PP
+The rest of the .pm file contains sample code for providing documentation for
+the extension.
+.PP
+Finally, the Mytest.xs file should look something like this:
+.PP
+.Vb 4
+\&    #define PERL_NO_GET_CONTEXT
+\&    #include "EXTERN.h"
+\&    #include "perl.h"
+\&    #include "XSUB.h"
+\&
+\&    #include "ppport.h"
+\&
+\&    MODULE = Mytest             PACKAGE = Mytest
+.Ve
+.PP
+Let's edit the .xs file by adding this to the end of the file:
+.PP
+.Vb 4
+\&    void
+\&    hello()
+\&        CODE:
+\&            printf("Hello, world!\en");
+.Ve
+.PP
+It is okay for the lines starting at the "CODE:" line to not be indented.
+However, for readability purposes, it is suggested that you indent CODE:
+one level and the lines following one more level.
+.PP
+Now we'll run "\f(CW\*(C`perl Makefile.PL\*(C'\fR".  This will create a real Makefile,
+which make needs.  Its output looks something like:
+.PP
+.Vb 5
+\&    % perl Makefile.PL
+\&    Checking if your kit is complete...
+\&    Looks good
+\&    Writing Makefile for Mytest
+\&    %
+.Ve
+.PP
+Now, running make will produce output that looks something like this (some
+long lines have been shortened for clarity and some extraneous lines have
+been deleted):
+.PP
+.Vb 10
+\& % make
+\& cp lib/Mytest.pm blib/lib/Mytest.pm
+\& perl xsubpp  \-typemap typemap  Mytest.xs > Mytest.xsc && \e
+\& mv Mytest.xsc Mytest.c
+\& Please specify prototyping behavior for Mytest.xs (see perlxs manual)
+\& cc \-c     Mytest.c
+\& Running Mkbootstrap for Mytest ()
+\& chmod 644 Mytest.bs
+\& rm \-f blib/arch/auto/Mytest/Mytest.so
+\& cc \-shared \-L/usr/local/lib Mytest.o \-o blib/arch/auto/Mytest/Mytest.so
+\&
+\& chmod 755 blib/arch/auto/Mytest/Mytest.so
+\& cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
+\& chmod 644 blib/arch/auto/Mytest/Mytest.bs
+\& Manifying blib/man3/Mytest.3pm
+\& %
+.Ve
+.PP
+You can safely ignore the line about "prototyping behavior" \- it is
+explained in "The PROTOTYPES: Keyword" in perlxs.
+.PP
+Perl has its own special way of easily writing test scripts, but for this
+example only, we'll create our own test script.  Create a file called hello
+that looks like this:
+.PP
+.Vb 1
+\&    #! /opt/perl5/bin/perl
+\&
+\&    use ExtUtils::testlib;
+\&
+\&    use Mytest;
+\&
+\&    Mytest::hello();
+.Ve
+.PP
+Now we make the script executable (\f(CW\*(C`chmod +x hello\*(C'\fR), run the script
+and we should see the following output:
+.PP
+.Vb 3
+\&    % ./hello
+\&    Hello, world!
+\&    %
+.Ve
+.SS "EXAMPLE 2"
+.IX Subsection "EXAMPLE 2"
+Now let's add to our extension a subroutine that will take a single numeric
+argument as input and return 1 if the number is even or 0 if the number
+is odd.
+.PP
+Add the following to the end of Mytest.xs:
+.PP
+.Vb 7
+\&    int
+\&    is_even(input)
+\&            int input
+\&        CODE:
+\&            RETVAL = (input % 2 == 0);
+\&        OUTPUT:
+\&            RETVAL
+.Ve
+.PP
+There does not need to be whitespace at the start of the "\f(CW\*(C`int input\*(C'\fR"
+line, but it is useful for improving readability.  Placing a semi-colon at
+the end of that line is also optional.  Any amount and kind of whitespace
+may be placed between the "\f(CW\*(C`int\*(C'\fR" and "\f(CW\*(C`input\*(C'\fR".
+.PP
+Now re-run make to rebuild our new shared library.
+.PP
+Now perform the same steps as before, generating a Makefile from the
+Makefile.PL file, and running make.
+.PP
+In order to test that our extension works, we now need to look at the
+file Mytest.t.  This file is set up to imitate the same kind of testing
+structure that Perl itself has.  Within the test script, you perform a
+number of tests to confirm the behavior of the extension, printing "ok"
+when the test is correct, "not ok" when it is not.
+.PP
+.Vb 2
+\&    use Test::More tests => 4;
+\&    BEGIN { use_ok(\*(AqMytest\*(Aq) };
+\&
+\&    #########################
+\&
+\&    # Insert your test code below, the Test::More module is use()ed here
+\&    # so read its man page ( perldoc Test::More ) for help writing this
+\&    # test script.
+\&
+\&    is( Mytest::is_even(0), 1 );
+\&    is( Mytest::is_even(1), 0 );
+\&    is( Mytest::is_even(2), 1 );
+.Ve
+.PP
+We will be calling the test script through the command "\f(CW\*(C`make test\*(C'\fR".  You
+should see output that looks something like this:
+.PP
+.Vb 7
+\& %make test
+\& PERL_DL_NONLAZY=1 /usr/bin/perl "\-MExtUtils::Command::MM" "\-e"
+\& "test_harness(0, \*(Aqblib/lib\*(Aq, \*(Aqblib/arch\*(Aq)" t/*.t
+\& t/Mytest....ok
+\& All tests successful.
+\& Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU)
+\& %
+.Ve
+.SS "What has gone on?"
+.IX Subsection "What has gone on?"
+The program h2xs is the starting point for creating extensions.  In later
+examples we'll see how we can use h2xs to read header files and generate
+templates to connect to C routines.
+.PP
+h2xs creates a number of files in the extension directory.  The file
+Makefile.PL is a perl script which will generate a true Makefile to build
+the extension.  We'll take a closer look at it later.
+.PP
+The .pm and .xs files contain the meat of the extension.  The .xs file holds
+the C routines that make up the extension.  The .pm file contains routines
+that tell Perl how to load your extension.
+.PP
+Generating the Makefile and running \f(CW\*(C`make\*(C'\fR created a directory called blib
+(which stands for "build library") in the current working directory.  This
+directory will contain the shared library that we will build.  Once we have
+tested it, we can install it into its final location.
+.PP
+Invoking the test script via "\f(CW\*(C`make test\*(C'\fR" did something very important.
+It invoked perl with all those \f(CW\*(C`\-I\*(C'\fR arguments so that it could find the
+various files that are part of the extension.  It is \fIvery\fR important that
+while you are still testing extensions that you use "\f(CW\*(C`make test\*(C'\fR".  If you
+try to run the test script all by itself, you will get a fatal error.
+Another reason it is important to use "\f(CW\*(C`make test\*(C'\fR" to run your test
+script is that if you are testing an upgrade to an already-existing version,
+using "\f(CW\*(C`make test\*(C'\fR" ensures that you will test your new extension, not the
+already-existing version.
+.PP
+When Perl sees a \f(CW\*(C`use extension;\*(C'\fR, it searches for a file with the same name
+as the \f(CW\*(C`use\*(C'\fR'd extension that has a .pm suffix.  If that file cannot be found,
+Perl dies with a fatal error.  The default search path is contained in the
+\&\f(CW@INC\fR array.
+.PP
+In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic
+Loader extensions.  It then sets the \f(CW@ISA\fR and \f(CW@EXPORT\fR arrays and the
+\&\f(CW$VERSION\fR scalar; finally it tells perl to bootstrap the module.  Perl
+will call its dynamic loader routine (if there is one) and load the shared
+library.
+.PP
+The two arrays \f(CW@ISA\fR and \f(CW@EXPORT\fR are very important.  The \f(CW@ISA\fR
+array contains a list of other packages in which to search for methods (or
+subroutines) that do not exist in the current package.  This is usually
+only important for object-oriented extensions (which we will talk about
+much later), and so usually doesn't need to be modified.
+.PP
+The \f(CW@EXPORT\fR array tells Perl which of the extension's variables and
+subroutines should be placed into the calling package's namespace.  Because
+you don't know if the user has already used your variable and subroutine
+names, it's vitally important to carefully select what to export.  Do \fInot\fR
+export method or variable names \fIby default\fR without a good reason.
+.PP
+As a general rule, if the module is trying to be object-oriented then don't
+export anything.  If it's just a collection of functions and variables, then
+you can export them via another array, called \f(CW@EXPORT_OK\fR.  This array
+does not automatically place its subroutine and variable names into the
+namespace unless the user specifically requests that this be done.
+.PP
+See perlmod for more information.
+.PP
+The \f(CW$VERSION\fR variable is used to ensure that the .pm file and the shared
+library are "in sync" with each other.  Any time you make changes to
+the .pm or .xs files, you should increment the value of this variable.
+.SS "Writing good test scripts"
+.IX Subsection "Writing good test scripts"
+The importance of writing good test scripts cannot be over-emphasized.  You
+should closely follow the "ok/not ok" style that Perl itself uses, so that
+it is very easy and unambiguous to determine the outcome of each test case.
+When you find and fix a bug, make sure you add a test case for it.
+.PP
+By running "\f(CW\*(C`make test\*(C'\fR", you ensure that your Mytest.t script runs and uses
+the correct version of your extension.  If you have many test cases,
+save your test files in the "t" directory and use the suffix ".t".
+When you run "\f(CW\*(C`make test\*(C'\fR", all of these test files will be executed.
+.SS "EXAMPLE 3"
+.IX Subsection "EXAMPLE 3"
+Our third extension will take one argument as its input, round off that
+value, and set the \fIargument\fR to the rounded value.
+.PP
+Add the following to the end of Mytest.xs:
+.PP
+.Vb 10
+\&        void
+\&        round(arg)
+\&                double  arg
+\&            CODE:
+\&                if (arg > 0.0) {
+\&                        arg = floor(arg + 0.5);
+\&                } else if (arg < 0.0) {
+\&                        arg = ceil(arg \- 0.5);
+\&                } else {
+\&                        arg = 0.0;
+\&                }
+\&            OUTPUT:
+\&                arg
+.Ve
+.PP
+Edit the Makefile.PL file so that the corresponding line looks like this:
+.PP
+.Vb 1
+\&        LIBS      => [\*(Aq\-lm\*(Aq],   # e.g., \*(Aq\-lm\*(Aq
+.Ve
+.PP
+Generate the Makefile and run make.  Change the test number in Mytest.t to
+"9" and add the following tests:
+.PP
+.Vb 1
+\&        my $i;
+\&
+\&        $i = \-1.5;
+\&        Mytest::round($i);
+\&        is( $i, \-2.0, \*(AqRounding \-1.5 to \-2.0\*(Aq );
+\&
+\&        $i = \-1.1;
+\&        Mytest::round($i);
+\&        is( $i, \-1.0, \*(AqRounding \-1.1 to \-1.0\*(Aq );
+\&
+\&        $i = 0.0;
+\&        Mytest::round($i);
+\&        is( $i, 0.0, \*(AqRounding 0.0 to 0.0\*(Aq );
+\&
+\&        $i = 0.5;
+\&        Mytest::round($i);
+\&        is( $i, 1.0, \*(AqRounding 0.5 to 1.0\*(Aq );
+\&
+\&        $i = 1.2;
+\&        Mytest::round($i);
+\&        is( $i, 1.0, \*(AqRounding 1.2 to 1.0\*(Aq );
+.Ve
+.PP
+Running "\f(CW\*(C`make test\*(C'\fR" should now print out that all nine tests are okay.
+.PP
+Notice that in these new test cases, the argument passed to round was a
+scalar variable.  You might be wondering if you can round a constant or
+literal.  To see what happens, temporarily add the following line to Mytest.t:
+.PP
+.Vb 1
+\&        Mytest::round(3);
+.Ve
+.PP
+Run "\f(CW\*(C`make test\*(C'\fR" and notice that Perl dies with a fatal error.  Perl won't
+let you change the value of constants!
+.SS "What's new here?"
+.IX Subsection "What's new here?"
+.IP \(bu 4
+We've made some changes to Makefile.PL.  In this case, we've specified an
+extra library to be linked into the extension's shared library, the math
+library libm in this case.  We'll talk later about how to write XSUBs that
+can call every routine in a library.
+.IP \(bu 4
+The value of the function is not being passed back as the function's return
+value, but by changing the value of the variable that was passed into the
+function.  You might have guessed that when you saw that the return value
+of round is of type "void".
+.SS "Input and Output Parameters"
+.IX Subsection "Input and Output Parameters"
+You specify the parameters that will be passed into the XSUB on the line(s)
+after you declare the function's return value and name.  Each input parameter
+line starts with optional whitespace, and may have an optional terminating
+semicolon.
+.PP
+The list of output parameters occurs at the very end of the function, just
+after the OUTPUT: directive.  The use of RETVAL tells Perl that you
+wish to send this value back as the return value of the XSUB function.  In
+Example 3, we wanted the "return value" placed in the original variable
+which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section.
+.SS "The XSUBPP Program"
+.IX Subsection "The XSUBPP Program"
+The \fBxsubpp\fR program takes the XS code in the .xs file and translates it into
+C code, placing it in a file whose suffix is .c.  The C code created makes
+heavy use of the C functions within Perl.
+.SS "The TYPEMAP file"
+.IX Subsection "The TYPEMAP file"
+The \fBxsubpp\fR program uses rules to convert from Perl's data types (scalar,
+array, etc.) to C's data types (int, char, etc.).  These rules are stored
+in the typemap file ($PERLLIB/ExtUtils/typemap).  There's a brief discussion
+below, but all the nitty-gritty details can be found in perlxstypemap.
+If you have a new-enough version of perl (5.16 and up) or an upgraded
+XS compiler (\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR 3.13_01 or better), then you can inline
+typemaps in your XS instead of writing separate files.
+Either way, this typemap thing is split into three parts:
+.PP
+The first section maps various C data types to a name, which corresponds
+somewhat with the various Perl types.  The second section contains C code
+which \fBxsubpp\fR uses to handle input parameters.  The third section contains
+C code which \fBxsubpp\fR uses to handle output parameters.
+.PP
+Let's take a look at a portion of the .c file created for our extension.
+The file name is Mytest.c:
+.PP
+.Vb 10
+\&        XS(XS_Mytest_round)
+\&        {
+\&            dXSARGS;
+\&            if (items != 1)
+\&                Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
+\&            PERL_UNUSED_VAR(cv); /* \-W */
+\&            {
+\&                double  arg = (double)SvNV(ST(0));      /* XXXXX */
+\&                if (arg > 0.0) {
+\&                        arg = floor(arg + 0.5);
+\&                } else if (arg < 0.0) {
+\&                        arg = ceil(arg \- 0.5);
+\&                } else {
+\&                        arg = 0.0;
+\&                }
+\&                sv_setnv(ST(0), (double)arg);   /* XXXXX */
+\&                SvSETMAGIC(ST(0));
+\&            }
+\&            XSRETURN_EMPTY;
+\&        }
+.Ve
+.PP
+Notice the two lines commented with "XXXXX".  If you check the first part
+of the typemap file (or section), you'll see that doubles are of type
+T_DOUBLE.  In the INPUT part of the typemap, an argument that is T_DOUBLE
+is assigned to the variable arg by calling the routine SvNV on something,
+then casting it to double, then assigned to the variable arg.  Similarly,
+in the OUTPUT section, once arg has its final value, it is passed to the
+sv_setnv function to be passed back to the calling subroutine.  These two
+functions are explained in perlguts; we'll talk more later about what
+that "\fBST\fR\|(0)" means in the section on the argument stack.
+.SS "Warning about Output Arguments"
+.IX Subsection "Warning about Output Arguments"
+In general, it's not a good idea to write extensions that modify their input
+parameters, as in Example 3.  Instead, you should probably return multiple
+values in an array and let the caller handle them (we'll do this in a later
+example).  However, in order to better accommodate calling pre-existing C
+routines, which often do modify their input parameters, this behavior is
+tolerated.
+.SS "EXAMPLE 4"
+.IX Subsection "EXAMPLE 4"
+In this example, we'll now begin to write XSUBs that will interact with
+pre-defined C libraries.  To begin with, we will build a small library of
+our own, then let h2xs write our .pm and .xs files for us.
+.PP
+Create a new directory called Mytest2 at the same level as the directory
+Mytest.  In the Mytest2 directory, create another directory called mylib,
+and cd into that directory.
+.PP
+Here we'll create some files that will generate a test library.  These will
+include a C source file and a header file.  We'll also create a Makefile.PL
+in this directory.  Then we'll make sure that running make at the Mytest2
+level will automatically run this Makefile.PL file and the resulting Makefile.
+.PP
+In the mylib directory, create a file mylib.h that looks like this:
+.PP
+.Vb 1
+\&        #define TESTVAL 4
+\&
+\&        extern double   foo(int, long, const char*);
+.Ve
+.PP
+Also create a file mylib.c that looks like this:
+.PP
+.Vb 2
+\&        #include <stdlib.h>
+\&        #include "mylib.h"
+\&
+\&        double
+\&        foo(int a, long b, const char *c)
+\&        {
+\&                return (a + b + atof(c) + TESTVAL);
+\&        }
+.Ve
+.PP
+And finally create a file Makefile.PL that looks like this:
+.PP
+.Vb 7
+\&        use ExtUtils::MakeMaker;
+\&        $Verbose = 1;
+\&        WriteMakefile(
+\&            NAME  => \*(AqMytest2::mylib\*(Aq,
+\&            SKIP  => [qw(all static static_lib dynamic dynamic_lib)],
+\&            clean => {\*(AqFILES\*(Aq => \*(Aqlibmylib$(LIB_EXT)\*(Aq},
+\&        );
+\&
+\&
+\&        sub MY::top_targets {
+\&                \*(Aq
+\&        all :: static
+\&
+\&        pure_all :: static
+\&
+\&        static ::       libmylib$(LIB_EXT)
+\&
+\&        libmylib$(LIB_EXT): $(O_FILES)
+\&                $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
+\&                $(RANLIB) libmylib$(LIB_EXT)
+\&
+\&        \*(Aq;
+\&        }
+.Ve
+.PP
+Make sure you use a tab and not spaces on the lines beginning with "$(AR)"
+and "$(RANLIB)".  Make will not function properly if you use spaces.
+It has also been reported that the "cr" argument to $(AR) is unnecessary
+on Win32 systems.
+.PP
+We will now create the main top-level Mytest2 files.  Change to the directory
+above Mytest2 and run the following command:
+.PP
+.Vb 1
+\&        % h2xs \-O \-n Mytest2 Mytest2/mylib/mylib.h
+.Ve
+.PP
+This will print out a warning about overwriting Mytest2, but that's okay.
+Our files are stored in Mytest2/mylib, and will be untouched.
+.PP
+The normal Makefile.PL that h2xs generates doesn't know about the mylib
+directory.  We need to tell it that there is a subdirectory and that we
+will be generating a library in it.  Let's add the argument MYEXTLIB to
+the WriteMakefile call so that it looks like this:
+.PP
+.Vb 8
+\&        WriteMakefile(
+\&            NAME         => \*(AqMytest2\*(Aq,
+\&            VERSION_FROM => \*(AqMytest2.pm\*(Aq, # finds $VERSION
+\&            LIBS         => [\*(Aq\*(Aq],   # e.g., \*(Aq\-lm\*(Aq
+\&            DEFINE       => \*(Aq\*(Aq,     # e.g., \*(Aq\-DHAVE_SOMETHING\*(Aq
+\&            INC          => \*(Aq\*(Aq,     # e.g., \*(Aq\-I/usr/include/other\*(Aq
+\&            MYEXTLIB     => \*(Aqmylib/libmylib$(LIB_EXT)\*(Aq,
+\&        );
+.Ve
+.PP
+and then at the end add a subroutine (which will override the pre-existing
+subroutine).  Remember to use a tab character to indent the line beginning
+with "cd"!
+.PP
+.Vb 6
+\&        sub MY::postamble {
+\&        \*(Aq
+\&        $(MYEXTLIB): mylib/Makefile
+\&                cd mylib && $(MAKE) $(PASSTHRU)
+\&        \*(Aq;
+\&        }
+.Ve
+.PP
+Let's also fix the MANIFEST file by appending the following three lines:
+.PP
+.Vb 3
+\&        mylib/Makefile.PL
+\&        mylib/mylib.c
+\&        mylib/mylib.h
+.Ve
+.PP
+To keep our namespace nice and unpolluted, edit the .pm file and change
+the variable \f(CW@EXPORT\fR to \f(CW@EXPORT_OK\fR.  Finally, in the
+\&.xs file, edit the #include line to read:
+.PP
+.Vb 1
+\&        #include "mylib/mylib.h"
+.Ve
+.PP
+And also add the following function definition to the end of the .xs file:
+.PP
+.Vb 7
+\&        double
+\&        foo(a,b,c)
+\&                int             a
+\&                long            b
+\&                const char *    c
+\&            OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+Now we also need to create a typemap because the default Perl doesn't
+currently support the \f(CW\*(C`const char *\*(C'\fR type.  Include a new TYPEMAP
+section in your XS code before the above function:
+.PP
+.Vb 3
+\&        TYPEMAP: <<END
+\&        const char *    T_PV
+\&        END
+.Ve
+.PP
+Now run perl on the top-level Makefile.PL.  Notice that it also created a
+Makefile in the mylib directory.  Run make and watch that it does cd into
+the mylib directory and run make in there as well.
+.PP
+Now edit the Mytest2.t script and change the number of tests to "5",
+and add the following lines to the end of the script:
+.PP
+.Vb 3
+\&        is( Mytest2::foo( 1, 2, "Hello, world!" ), 7 );
+\&        is( Mytest2::foo( 1, 2, "0.0" ),           7 );
+\&        ok( abs( Mytest2::foo( 0, 0, "\-3.4" ) \- 0.6 ) <= 0.01 );
+.Ve
+.PP
+(When dealing with floating-point comparisons, it is best to not check for
+equality, but rather that the difference between the expected and actual
+result is below a certain amount (called epsilon) which is 0.01 in this case)
+.PP
+Run "\f(CW\*(C`make test\*(C'\fR" and all should be well. There are some warnings on missing
+tests for the Mytest2::mylib extension, but you can ignore them.
+.SS "What has happened here?"
+.IX Subsection "What has happened here?"
+Unlike previous examples, we've now run h2xs on a real include file.  This
+has caused some extra goodies to appear in both the .pm and .xs files.
+.IP \(bu 4
+In the .xs file, there's now a #include directive with the absolute path to
+the mylib.h header file.  We changed this to a relative path so that we
+could move the extension directory if we wanted to.
+.IP \(bu 4
+There's now some new C code that's been added to the .xs file.  The purpose
+of the \f(CW\*(C`constant\*(C'\fR routine is to make the values that are #define'd in the
+header file accessible by the Perl script (by calling either \f(CW\*(C`TESTVAL\*(C'\fR or
+\&\f(CW&Mytest2::TESTVAL\fR).  There's also some XS code to allow calls to the
+\&\f(CW\*(C`constant\*(C'\fR routine.
+.IP \(bu 4
+The .pm file originally exported the name \f(CW\*(C`TESTVAL\*(C'\fR in the \f(CW@EXPORT\fR array.
+This could lead to name clashes.  A good rule of thumb is that if the #define
+is only going to be used by the C routines themselves, and not by the user,
+they should be removed from the \f(CW@EXPORT\fR array.  Alternately, if you don't
+mind using the "fully qualified name" of a variable, you could move most
+or all of the items from the \f(CW@EXPORT\fR array into the \f(CW@EXPORT_OK\fR array.
+.IP \(bu 4
+If our include file had contained #include directives, these would not have
+been processed by h2xs.  There is no good solution to this right now.
+.IP \(bu 4
+We've also told Perl about the library that we built in the mylib
+subdirectory.  That required only the addition of the \f(CW\*(C`MYEXTLIB\*(C'\fR variable
+to the WriteMakefile call and the replacement of the postamble subroutine
+to cd into the subdirectory and run make.  The Makefile.PL for the
+library is a bit more complicated, but not excessively so.  Again we
+replaced the postamble subroutine to insert our own code.  This code
+simply specified that the library to be created here was a static archive
+library (as opposed to a dynamically loadable library) and provided the
+commands to build it.
+.SS "Anatomy of .xs file"
+.IX Subsection "Anatomy of .xs file"
+The .xs file of "EXAMPLE 4" contained some new elements.  To understand
+the meaning of these elements, pay attention to the line which reads
+.PP
+.Vb 1
+\&        MODULE = Mytest2                PACKAGE = Mytest2
+.Ve
+.PP
+Anything before this line is plain C code which describes which headers
+to include, and defines some convenience functions.  No translations are
+performed on this part, apart from having embedded POD documentation
+skipped over (see perlpod) it goes into the generated output C file as is.
+.PP
+Anything after this line is the description of XSUB functions.
+These descriptions are translated by \fBxsubpp\fR into C code which
+implements these functions using Perl calling conventions, and which
+makes these functions visible from Perl interpreter.
+.PP
+Pay a special attention to the function \f(CW\*(C`constant\*(C'\fR.  This name appears
+twice in the generated .xs file: once in the first part, as a static C
+function, then another time in the second part, when an XSUB interface to
+this static C function is defined.
+.PP
+This is quite typical for .xs files: usually the .xs file provides
+an interface to an existing C function.  Then this C function is defined
+somewhere (either in an external library, or in the first part of .xs file),
+and a Perl interface to this function (i.e. "Perl glue") is described in the
+second part of .xs file.  The situation in "EXAMPLE 1", "EXAMPLE 2",
+and "EXAMPLE 3", when all the work is done inside the "Perl glue", is
+somewhat of an exception rather than the rule.
+.SS "Getting the fat out of XSUBs"
+.IX Subsection "Getting the fat out of XSUBs"
+In "EXAMPLE 4" the second part of .xs file contained the following
+description of an XSUB:
+.PP
+.Vb 7
+\&        double
+\&        foo(a,b,c)
+\&                int             a
+\&                long            b
+\&                const char *    c
+\&            OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+Note that in contrast with "EXAMPLE 1", "EXAMPLE 2" and "EXAMPLE 3",
+this description does not contain the actual \fIcode\fR for what is done
+during a call to Perl function \fBfoo()\fR.  To understand what is going
+on here, one can add a CODE section to this XSUB:
+.PP
+.Vb 9
+\&        double
+\&        foo(a,b,c)
+\&                int             a
+\&                long            b
+\&                const char *    c
+\&            CODE:
+\&                RETVAL = foo(a,b,c);
+\&            OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+However, these two XSUBs provide almost identical generated C code: \fBxsubpp\fR
+compiler is smart enough to figure out the \f(CW\*(C`CODE:\*(C'\fR section from the first
+two lines of the description of XSUB.  What about \f(CW\*(C`OUTPUT:\*(C'\fR section?  In
+fact, that is absolutely the same!  The \f(CW\*(C`OUTPUT:\*(C'\fR section can be removed
+as well, \fIas far as \fR\f(CI\*(C`CODE:\*(C'\fR\fI section or \fR\f(CI\*(C`PPCODE:\*(C'\fR\fI section\fR is not
+specified: \fBxsubpp\fR can see that it needs to generate a function call
+section, and will autogenerate the OUTPUT section too.  Thus one can
+shortcut the XSUB to become:
+.PP
+.Vb 5
+\&        double
+\&        foo(a,b,c)
+\&                int             a
+\&                long            b
+\&                const char *    c
+.Ve
+.PP
+Can we do the same with an XSUB
+.PP
+.Vb 7
+\&        int
+\&        is_even(input)
+\&                int     input
+\&            CODE:
+\&                RETVAL = (input % 2 == 0);
+\&            OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+of "EXAMPLE 2"?  To do this, one needs to define a C function \f(CW\*(C`int
+is_even(int input)\*(C'\fR.  As we saw in "Anatomy of .xs file", a proper place
+for this definition is in the first part of .xs file.  In fact a C function
+.PP
+.Vb 5
+\&        int
+\&        is_even(int arg)
+\&        {
+\&                return (arg % 2 == 0);
+\&        }
+.Ve
+.PP
+is probably overkill for this.  Something as simple as a \f(CW\*(C`#define\*(C'\fR will
+do too:
+.PP
+.Vb 1
+\&        #define is_even(arg)    ((arg) % 2 == 0)
+.Ve
+.PP
+After having this in the first part of .xs file, the "Perl glue" part becomes
+as simple as
+.PP
+.Vb 3
+\&        int
+\&        is_even(input)
+\&                int     input
+.Ve
+.PP
+This technique of separation of the glue part from the workhorse part has
+obvious tradeoffs: if you want to change a Perl interface, you need to
+change two places in your code.  However, it removes a lot of clutter,
+and makes the workhorse part independent from idiosyncrasies of Perl calling
+convention.  (In fact, there is nothing Perl-specific in the above description,
+a different version of \fBxsubpp\fR might have translated this to TCL glue or
+Python glue as well.)
+.SS "More about XSUB arguments"
+.IX Subsection "More about XSUB arguments"
+With the completion of Example 4, we now have an easy way to simulate some
+real-life libraries whose interfaces may not be the cleanest in the world.
+We shall now continue with a discussion of the arguments passed to the
+\&\fBxsubpp\fR compiler.
+.PP
+When you specify arguments to routines in the .xs file, you are really
+passing three pieces of information for each argument listed.  The first
+piece is the order of that argument relative to the others (first, second,
+etc).  The second is the type of argument, and consists of the type
+declaration of the argument (e.g., int, char*, etc).  The third piece is
+the calling convention for the argument in the call to the library function.
+.PP
+While Perl passes arguments to functions by reference,
+C passes arguments by value; to implement a C function which modifies data
+of one of the "arguments", the actual argument of this C function would be
+a pointer to the data.  Thus two C functions with declarations
+.PP
+.Vb 2
+\&        int string_length(char *s);
+\&        int upper_case_char(char *cp);
+.Ve
+.PP
+may have completely different semantics: the first one may inspect an array
+of chars pointed by s, and the second one may immediately dereference \f(CW\*(C`cp\*(C'\fR
+and manipulate \f(CW*cp\fR only (using the return value as, say, a success
+indicator).  From Perl one would use these functions in
+a completely different manner.
+.PP
+One conveys this info to \fBxsubpp\fR by replacing \f(CW\*(C`*\*(C'\fR before the
+argument by \f(CW\*(C`&\*(C'\fR.  \f(CW\*(C`&\*(C'\fR means that the argument should be passed to a library
+function by its address.  The above two function may be XSUB-ified as
+.PP
+.Vb 3
+\&        int
+\&        string_length(s)
+\&                char *  s
+\&
+\&        int
+\&        upper_case_char(cp)
+\&                char    &cp
+.Ve
+.PP
+For example, consider:
+.PP
+.Vb 4
+\&        int
+\&        foo(a,b)
+\&                char    &a
+\&                char *  b
+.Ve
+.PP
+The first Perl argument to this function would be treated as a char and
+assigned to the variable a, and its address would be passed into the function
+foo. The second Perl argument would be treated as a string pointer and assigned
+to the variable b. The \fIvalue\fR of b would be passed into the function foo.
+The actual call to the function foo that \fBxsubpp\fR generates would look like
+this:
+.PP
+.Vb 1
+\&        foo(&a, b);
+.Ve
+.PP
+\&\fBxsubpp\fR will parse the following function argument lists identically:
+.PP
+.Vb 3
+\&        char    &a
+\&        char&a
+\&        char    & a
+.Ve
+.PP
+However, to help ease understanding, it is suggested that you place a "&"
+next to the variable name and away from the variable type), and place a
+"*" near the variable type, but away from the variable name (as in the
+call to foo above).  By doing so, it is easy to understand exactly what
+will be passed to the C function; it will be whatever is in the "last
+column".
+.PP
+You should take great pains to try to pass the function the type of variable
+it wants, when possible.  It will save you a lot of trouble in the long run.
+.SS "The Argument Stack"
+.IX Subsection "The Argument Stack"
+If we look at any of the C code generated by any of the examples except
+example 1, you will notice a number of references to ST(n), where n is
+usually 0.  "ST" is actually a macro that points to the n'th argument
+on the argument stack.  \fBST\fR\|(0) is thus the first argument on the stack and
+therefore the first argument passed to the XSUB, \fBST\fR\|(1) is the second
+argument, and so on.
+.PP
+When you list the arguments to the XSUB in the .xs file, that tells \fBxsubpp\fR
+which argument corresponds to which of the argument stack (i.e., the first
+one listed is the first argument, and so on).  You invite disaster if you
+do not list them in the same order as the function expects them.
+.PP
+The actual values on the argument stack are pointers to the values passed
+in.  When an argument is listed as being an OUTPUT value, its corresponding
+value on the stack (i.e., \fBST\fR\|(0) if it was the first argument) is changed.
+You can verify this by looking at the C code generated for Example 3.
+The code for the \fBround()\fR XSUB routine contains lines that look like this:
+.PP
+.Vb 3
+\&        double  arg = (double)SvNV(ST(0));
+\&        /* Round the contents of the variable arg */
+\&        sv_setnv(ST(0), (double)arg);
+.Ve
+.PP
+The arg variable is initially set by taking the value from \fBST\fR\|(0), then is
+stored back into \fBST\fR\|(0) at the end of the routine.
+.PP
+XSUBs are also allowed to return lists, not just scalars.  This must be
+done by manipulating stack values \fBST\fR\|(0), \fBST\fR\|(1), etc, in a subtly
+different way.  See perlxs for details.
+.PP
+XSUBs are also allowed to avoid automatic conversion of Perl function arguments
+to C function arguments.  See perlxs for details.  Some people prefer
+manual conversion by inspecting \f(CWST(i)\fR even in the cases when automatic
+conversion will do, arguing that this makes the logic of an XSUB call clearer.
+Compare with "Getting the fat out of XSUBs" for a similar tradeoff of
+a complete separation of "Perl glue" and "workhorse" parts of an XSUB.
+.PP
+While experts may argue about these idioms, a novice to Perl guts may
+prefer a way which is as little Perl-guts-specific as possible, meaning
+automatic conversion and automatic call generation, as in
+"Getting the fat out of XSUBs".  This approach has the additional
+benefit of protecting the XSUB writer from future changes to the Perl API.
+.SS "Extending your Extension"
+.IX Subsection "Extending your Extension"
+Sometimes you might want to provide some extra methods or subroutines
+to assist in making the interface between Perl and your extension simpler
+or easier to understand.  These routines should live in the .pm file.
+Whether they are automatically loaded when the extension itself is loaded
+or only loaded when called depends on where in the .pm file the subroutine
+definition is placed.  You can also consult AutoLoader for an alternate
+way to store and load your extra subroutines.
+.SS "Documenting your Extension"
+.IX Subsection "Documenting your Extension"
+There is absolutely no excuse for not documenting your extension.
+Documentation belongs in the .pm file.  This file will be fed to pod2man,
+and the embedded documentation will be converted to the manpage format,
+then placed in the blib directory.  It will be copied to Perl's
+manpage directory when the extension is installed.
+.PP
+You may intersperse documentation and Perl code within the .pm file.
+In fact, if you want to use method autoloading, you must do this,
+as the comment inside the .pm file explains.
+.PP
+See perlpod for more information about the pod format.
+.SS "Installing your Extension"
+.IX Subsection "Installing your Extension"
+Once your extension is complete and passes all its tests, installing it
+is quite simple: you simply run "make install".  You will either need
+to have write permission into the directories where Perl is installed,
+or ask your system administrator to run the make for you.
+.PP
+Alternately, you can specify the exact directory to place the extension's
+files by placing a "PREFIX=/destination/directory" after the make install
+(or in between the make and install if you have a brain-dead version of make).
+This can be very useful if you are building an extension that will eventually
+be distributed to multiple systems.  You can then just archive the files in
+the destination directory and distribute them to your destination systems.
+.SS "EXAMPLE 5"
+.IX Subsection "EXAMPLE 5"
+In this example, we'll do some more work with the argument stack.  The
+previous examples have all returned only a single value.  We'll now
+create an extension that returns an array.
+.PP
+This extension is very Unix-oriented (struct statfs and the statfs system
+call).  If you are not running on a Unix system, you can substitute for
+statfs any other function that returns multiple values, you can hard-code
+values to be returned to the caller (although this will be a bit harder
+to test the error case), or you can simply not do this example.  If you
+change the XSUB, be sure to fix the test cases to match the changes.
+.PP
+Return to the Mytest directory and add the following code to the end of
+Mytest.xs:
+.PP
+.Vb 6
+\&        void
+\&        statfs(path)
+\&                char *  path
+\&            INIT:
+\&                int i;
+\&                struct statfs buf;
+\&
+\&            PPCODE:
+\&                i = statfs(path, &buf);
+\&                if (i == 0) {
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
+\&                        XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
+\&                } else {
+\&                        XPUSHs(sv_2mortal(newSVnv(errno)));
+\&                }
+.Ve
+.PP
+You'll also need to add the following code to the top of the .xs file, just
+after the include of "XSUB.h":
+.PP
+.Vb 1
+\&        #include <sys/vfs.h>
+.Ve
+.PP
+Also add the following code segment to Mytest.t while incrementing the "9"
+tests to "11":
+.PP
+.Vb 1
+\&    my @a;
+\&
+\&        @a = Mytest::statfs("/blech");
+\&        ok( scalar(@a) == 1 && $a[0] == 2 );
+\&
+\&        @a = Mytest::statfs("/");
+\&        is( scalar(@a), 7 );
+.Ve
+.SS "New Things in this Example"
+.IX Subsection "New Things in this Example"
+This example added quite a few new concepts.  We'll take them one at a time.
+.IP \(bu 4
+The INIT: directive contains code that will be placed immediately after
+the argument stack is decoded.  C does not allow variable declarations at
+arbitrary locations inside a function,
+so this is usually the best way to declare local variables needed by the XSUB.
+(Alternatively, one could put the whole \f(CW\*(C`PPCODE:\*(C'\fR section into braces, and
+put these declarations on top.)
+.IP \(bu 4
+This routine also returns a different number of arguments depending on the
+success or failure of the call to statfs.  If there is an error, the error
+number is returned as a single-element array.  If the call is successful,
+then a 7\-element array is returned.  Since only one argument is passed into
+this function, we need room on the stack to hold the 7 values which may be
+returned.
+.Sp
+We do this by using the PPCODE: directive, rather than the CODE: directive.
+This tells \fBxsubpp\fR that we will be managing the return values that will be
+put on the argument stack by ourselves.
+.IP \(bu 4
+When we want to place values to be returned to the caller onto the stack,
+we use the series of macros that begin with "XPUSH".  There are five
+different versions, for placing integers, unsigned integers, doubles,
+strings, and Perl scalars on the stack.  In our example, we placed a
+Perl scalar onto the stack.  (In fact this is the only macro which
+can be used to return multiple values.)
+.Sp
+The XPUSH* macros will automatically extend the return stack to prevent
+it from being overrun.  You push values onto the stack in the order you
+want them seen by the calling program.
+.IP \(bu 4
+The values pushed onto the return stack of the XSUB are actually mortal SV's.
+They are made mortal so that once the values are copied by the calling
+program, the SV's that held the returned values can be deallocated.
+If they were not mortal, then they would continue to exist after the XSUB
+routine returned, but would not be accessible.  This is a memory leak.
+.IP \(bu 4
+If we were interested in performance, not in code compactness, in the success
+branch we would not use \f(CW\*(C`XPUSHs\*(C'\fR macros, but \f(CW\*(C`PUSHs\*(C'\fR macros, and would
+pre-extend the stack before pushing the return values:
+.Sp
+.Vb 1
+\&        EXTEND(SP, 7);
+.Ve
+.Sp
+The tradeoff is that one needs to calculate the number of return values
+in advance (though overextending the stack will not typically hurt
+anything but memory consumption).
+.Sp
+Similarly, in the failure branch we could use \f(CW\*(C`PUSHs\*(C'\fR \fIwithout\fR extending
+the stack: the Perl function reference comes to an XSUB on the stack, thus
+the stack is \fIalways\fR large enough to take one return value.
+.SS "EXAMPLE 6"
+.IX Subsection "EXAMPLE 6"
+In this example, we will accept a reference to an array as an input
+parameter, and return a reference to an array of hashes.  This will
+demonstrate manipulation of complex Perl data types from an XSUB.
+.PP
+This extension is somewhat contrived.  It is based on the code in
+the previous example.  It calls the statfs function multiple times,
+accepting a reference to an array of filenames as input, and returning
+a reference to an array of hashes containing the data for each of the
+filesystems.
+.PP
+Return to the Mytest directory and add the following code to the end of
+Mytest.xs:
+.PP
+.Vb 8
+\&    SV *
+\&    multi_statfs(paths)
+\&            SV * paths
+\&        INIT:
+\&            AV * results;
+\&            SSize_t numpaths = 0, n;
+\&            int i;
+\&            struct statfs buf;
+\&
+\&            SvGETMAGIC(paths);
+\&            if ((!SvROK(paths))
+\&                || (SvTYPE(SvRV(paths)) != SVt_PVAV)
+\&                || ((numpaths = av_top_index((AV *)SvRV(paths))) < 0))
+\&            {
+\&                XSRETURN_UNDEF;
+\&            }
+\&            results = (AV *)sv_2mortal((SV *)newAV());
+\&        CODE:
+\&            for (n = 0; n <= numpaths; n++) {
+\&                HV * rh;
+\&                STRLEN l;
+\&                SV * path = *av_fetch((AV *)SvRV(paths), n, 0);
+\&                char * fn = SvPVbyte(path, l);
+\&
+\&                i = statfs(fn, &buf);
+\&                if (i != 0) {
+\&                    av_push(results, newSVnv(errno));
+\&                    continue;
+\&                }
+\&
+\&                rh = (HV *)sv_2mortal((SV *)newHV());
+\&
+\&                hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
+\&                hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
+\&                hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
+\&                hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
+\&                hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
+\&                hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
+\&                hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);
+\&
+\&                av_push(results, newRV_inc((SV *)rh));
+\&            }
+\&            RETVAL = newRV_inc((SV *)results);
+\&        OUTPUT:
+\&            RETVAL
+.Ve
+.PP
+And add the following code to Mytest.t, while incrementing the "11"
+tests to "13":
+.PP
+.Vb 3
+\&        my $results = Mytest::multi_statfs([ \*(Aq/\*(Aq, \*(Aq/blech\*(Aq ]);
+\&        ok( ref $results\->[0] );
+\&        ok( ! ref $results\->[1] );
+.Ve
+.SS "New Things in this Example"
+.IX Subsection "New Things in this Example"
+There are a number of new concepts introduced here, described below:
+.IP \(bu 4
+This function does not use a typemap.  Instead, we declare it as accepting
+one SV* (scalar) parameter, and returning an SV* value, and we take care of
+populating these scalars within the code.  Because we are only returning
+one value, we don't need a \f(CW\*(C`PPCODE:\*(C'\fR directive \- instead, we use \f(CW\*(C`CODE:\*(C'\fR
+and \f(CW\*(C`OUTPUT:\*(C'\fR directives.
+.IP \(bu 4
+When dealing with references, it is important to handle them with caution.
+The \f(CW\*(C`INIT:\*(C'\fR block first calls SvGETMAGIC(paths), in case
+paths is a tied variable.  Then it checks that \f(CW\*(C`SvROK\*(C'\fR returns
+true, which indicates that paths is a valid reference.  (Simply
+checking \f(CW\*(C`SvROK\*(C'\fR won't trigger FETCH on a tied variable.)  It
+then verifies that the object referenced by paths is an array, using \f(CW\*(C`SvRV\*(C'\fR
+to dereference paths, and \f(CW\*(C`SvTYPE\*(C'\fR to discover its type.  As an added test,
+it checks that the array referenced by paths is non-empty, using the
+\&\f(CW\*(C`av_top_index\*(C'\fR function (which returns \-1 if the array is empty). The
+XSRETURN_UNDEF macro is used to abort the XSUB and return the undefined value
+whenever all three of these conditions are not met.
+.IP \(bu 4
+We manipulate several arrays in this XSUB.  Note that an array is represented
+internally by an AV* pointer.  The functions and macros for manipulating
+arrays are similar to the functions in Perl: \f(CW\*(C`av_top_index\*(C'\fR returns the
+highest index in an AV*, much like $#array; \f(CW\*(C`av_fetch\*(C'\fR fetches a single scalar
+value from an array, given its index; \f(CW\*(C`av_push\*(C'\fR pushes a scalar value onto the
+end of the array, automatically extending the array as necessary.
+.Sp
+Specifically, we read pathnames one at a time from the input array, and
+store the results in an output array (results) in the same order.  If
+statfs fails, the element pushed onto the return array is the value of
+errno after the failure.  If statfs succeeds, though, the value pushed
+onto the return array is a reference to a hash containing some of the
+information in the statfs structure.
+.Sp
+As with the return stack, it would be possible (and a small performance win)
+to pre-extend the return array before pushing data into it, since we know
+how many elements we will return:
+.Sp
+.Vb 1
+\&        av_extend(results, numpaths);
+.Ve
+.IP \(bu 4
+We are performing only one hash operation in this function, which is storing
+a new scalar under a key using \f(CW\*(C`hv_store\*(C'\fR.  A hash is represented by an HV*
+pointer.  Like arrays, the functions for manipulating hashes from an XSUB
+mirror the functionality available from Perl.  See perlguts and perlapi
+for details.
+.IP \(bu 4
+To create a reference, we use the \f(CW\*(C`newRV_inc\*(C'\fR function.  Note that you can
+cast an AV* or an HV* to type SV* in this case (and many others).  This
+allows you to take references to arrays, hashes and scalars with the same
+function.  Conversely, the \f(CW\*(C`SvRV\*(C'\fR function always returns an SV*, which may
+need to be cast to the appropriate type if it is something other than a
+scalar (check with \f(CW\*(C`SvTYPE\*(C'\fR).
+.IP \(bu 4
+At this point, xsubpp is doing very little work \- the differences between
+Mytest.xs and Mytest.c are minimal.
+.SS "EXAMPLE 7 (Coming Soon)"
+.IX Subsection "EXAMPLE 7 (Coming Soon)"
+XPUSH args AND set RETVAL AND assign return value to array
+.SS "EXAMPLE 8 (Coming Soon)"
+.IX Subsection "EXAMPLE 8 (Coming Soon)"
+Setting $!
+.SS "EXAMPLE 9 Passing open files to XSes"
+.IX Subsection "EXAMPLE 9 Passing open files to XSes"
+You would think passing files to an XS is difficult, with all the
+typeglobs and stuff. Well, it isn't.
+.PP
+Suppose that for some strange reason we need a wrapper around the
+standard C library function \f(CWfputs()\fR. This is all we need:
+.PP
+.Vb 5
+\&  #define PERLIO_NOT_STDIO 0  /* For co\-existence with stdio only */
+\&  #define PERL_NO_GET_CONTEXT /* This is more efficient */
+\&  #include "EXTERN.h"
+\&  #include "perl.h"
+\&  #include "XSUB.h"
+\&
+\&  #include <stdio.h>
+\&
+\&  int
+\&  fputs(s, stream)
+\&    char *          s
+\&    FILE *          stream
+.Ve
+.PP
+The real work is done in the standard typemap.
+.PP
+For more details, see
+"Co-existence with stdio" in perlapio.
+.PP
+\&\fBBut\fR you lose all the fine stuff done by the perlio layers. This
+calls the stdio function \f(CWfputs()\fR, which knows nothing about them.
+.PP
+The standard typemap offers three variants of PerlIO *:
+\&\f(CW\*(C`InputStream\*(C'\fR (T_IN), \f(CW\*(C`InOutStream\*(C'\fR (T_INOUT) and \f(CW\*(C`OutputStream\*(C'\fR
+(T_OUT). A bare \f(CW\*(C`PerlIO *\*(C'\fR is considered a T_INOUT. If it matters
+in your code (see below for why it might) #define or typedef
+one of the specific names and use that as the argument or result
+type in your XS file.
+.PP
+The standard typemap does not contain PerlIO * before perl 5.7,
+but it has the three stream variants. Using a PerlIO * directly
+is not backwards compatible unless you provide your own typemap.
+.PP
+For streams coming \fIfrom\fR perl the main difference is that
+\&\f(CW\*(C`OutputStream\*(C'\fR will get the output PerlIO * \- which may make
+a difference on a socket. Like in our example...
+.PP
+For streams being handed \fIto\fR perl a new file handle is created
+(i.e. a reference to a new glob) and associated with the PerlIO *
+provided. If the read/write state of the PerlIO * is not correct then you
+may get errors or warnings from when the file handle is used.
+So if you opened the PerlIO * as "w" it should really be an
+\&\f(CW\*(C`OutputStream\*(C'\fR if open as "r" it should be an \f(CW\*(C`InputStream\*(C'\fR.
+.PP
+Now, suppose you want to use perlio layers in your XS. We'll use the
+perlio \f(CWPerlIO_puts()\fR function as an example.
+.PP
+In the C part of the XS file (above the first MODULE line) you
+have
+.PP
+.Vb 3
+\&        #define OutputStream    PerlIO *
+\&    or
+\&        typedef PerlIO *        OutputStream;
+.Ve
+.PP
+And this is the XS code:
+.PP
+.Vb 8
+\&        int
+\&        perlioputs(s, stream)
+\&                char *          s
+\&                OutputStream    stream
+\&        CODE:
+\&                RETVAL = PerlIO_puts(stream, s);
+\&        OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+We have to use a \f(CW\*(C`CODE\*(C'\fR section because \f(CWPerlIO_puts()\fR has the arguments
+reversed compared to \f(CWfputs()\fR, and we want to keep the arguments the same.
+.PP
+Wanting to explore this thoroughly, we want to use the stdio \f(CWfputs()\fR
+on a PerlIO *. This means we have to ask the perlio system for a stdio
+\&\f(CW\*(C`FILE *\*(C'\fR:
+.PP
+.Vb 10
+\&        int
+\&        perliofputs(s, stream)
+\&                char *          s
+\&                OutputStream    stream
+\&        PREINIT:
+\&                FILE *fp = PerlIO_findFILE(stream);
+\&        CODE:
+\&                if (fp != (FILE*) 0) {
+\&                        RETVAL = fputs(s, fp);
+\&                } else {
+\&                        RETVAL = \-1;
+\&                }
+\&        OUTPUT:
+\&                RETVAL
+.Ve
+.PP
+Note: \f(CWPerlIO_findFILE()\fR will search the layers for a stdio
+layer. If it can't find one, it will call \f(CWPerlIO_exportFILE()\fR to
+generate a new stdio \f(CW\*(C`FILE\*(C'\fR. Please only call \f(CWPerlIO_exportFILE()\fR if
+you want a \fInew\fR \f(CW\*(C`FILE\*(C'\fR. It will generate one on each call and push a
+new stdio layer. So don't call it repeatedly on the same
+file. \f(CWPerlIO_findFILE()\fR will retrieve the stdio layer once it has been
+generated by \f(CWPerlIO_exportFILE()\fR.
+.PP
+This applies to the perlio system only. For versions before 5.7,
+\&\f(CWPerlIO_exportFILE()\fR is equivalent to \f(CWPerlIO_findFILE()\fR.
+.SS "Troubleshooting these Examples"
+.IX Subsection "Troubleshooting these Examples"
+As mentioned at the top of this document, if you are having problems with
+these example extensions, you might see if any of these help you.
+.IP \(bu 4
+In versions of 5.002 prior to the gamma version, the test script in Example
+1 will not function properly.  You need to change the "use lib" line to
+read:
+.Sp
+.Vb 1
+\&        use lib \*(Aq./blib\*(Aq;
+.Ve
+.IP \(bu 4
+In versions of 5.002 prior to version 5.002b1h, the test.pl file was not
+automatically created by h2xs.  This means that you cannot say "make test"
+to run the test script.  You will need to add the following line before the
+"use extension" statement:
+.Sp
+.Vb 1
+\&        use lib \*(Aq./blib\*(Aq;
+.Ve
+.IP \(bu 4
+In versions 5.000 and 5.001, instead of using the above line, you will need
+to use the following line:
+.Sp
+.Vb 1
+\&        BEGIN { unshift(@INC, "./blib") }
+.Ve
+.IP \(bu 4
+This document assumes that the executable named "perl" is Perl version 5.
+Some systems may have installed Perl version 5 as "perl5".
+.SH "See also"
+.IX Header "See also"
+For more information, consult perlguts, perlapi, perlxs, perlmod,
+perlapio, and perlpod
+.SH Author
+.IX Header "Author"
+Jeff Okamoto <\fIokamoto@corp.hp.com\fR>
+.PP
+Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
+and Tim Bunce.
+.PP
+PerlIO material contributed by Lupe Christoph, with some clarification
+by Nick Ing-Simmons.
+.PP
+Changes for h2xs as of Perl 5.8.x by Renee Baecker
+.PP
+This document is now maintained as part of Perl itself.
+.SS "Last Changed"
+.IX Subsection "Last Changed"
+2020\-10\-05
diff --git a/upstream/mageia-cauldron/man1/perlxstypemap.1 b/upstream/mageia-cauldron/man1/perlxstypemap.1
new file mode 100644
index 00000000..fffb189d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlxstypemap.1
@@ -0,0 +1,713 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLXSTYPEMAP 1"
+.TH PERLXSTYPEMAP 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+perlxstypemap \- Perl XS C/Perl type mapping
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The more you think about interfacing between two languages, the more
+you'll realize that the majority of programmer effort has to go into
+converting between the data structures that are native to either of
+the languages involved.  This trumps other matter such as differing
+calling conventions because the problem space is so much greater.
+There are simply more ways to shove data into memory than there are
+ways to implement a function call.
+.PP
+Perl XS' attempt at a solution to this is the concept of typemaps.
+At an abstract level, a Perl XS typemap is nothing but a recipe for
+converting from a certain Perl data structure to a certain C
+data structure and vice versa.  Since there can be C types that
+are sufficiently similar to one another to warrant converting with
+the same logic, XS typemaps are represented by a unique identifier,
+henceforth called an \fBXS type\fR in this document.  You can then tell
+the XS compiler that multiple C types are to be mapped with the same
+XS typemap.
+.PP
+In your XS code, when you define an argument with a C type or when
+you are using a \f(CW\*(C`CODE:\*(C'\fR and an \f(CW\*(C`OUTPUT:\*(C'\fR section together with a
+C return type of your XSUB, it'll be the typemapping mechanism that
+makes this easy.
+.SS "Anatomy of a typemap"
+.IX Subsection "Anatomy of a typemap"
+In more practical terms, the typemap is a collection of code
+fragments which are used by the \fBxsubpp\fR compiler to map C function
+parameters and values to Perl values.  The typemap file may consist
+of three sections labelled \f(CW\*(C`TYPEMAP\*(C'\fR, \f(CW\*(C`INPUT\*(C'\fR, and \f(CW\*(C`OUTPUT\*(C'\fR.
+An unlabelled initial section is assumed to be a \f(CW\*(C`TYPEMAP\*(C'\fR section.
+The INPUT section tells the compiler how to translate Perl values
+into variables of certain C types.  The OUTPUT section tells the
+compiler how to translate the values from certain C types into values
+Perl can understand.  The TYPEMAP section tells the compiler which
+of the INPUT and OUTPUT code fragments should be used to map a given
+C type to a Perl value.  The section labels \f(CW\*(C`TYPEMAP\*(C'\fR, \f(CW\*(C`INPUT\*(C'\fR, or
+\&\f(CW\*(C`OUTPUT\*(C'\fR must begin in the first column on a line by themselves,
+and must be in uppercase.
+.PP
+Each type of section can appear an arbitrary number of times
+and does not have to appear at all.  For example, a typemap may
+commonly lack \f(CW\*(C`INPUT\*(C'\fR and \f(CW\*(C`OUTPUT\*(C'\fR sections if all it needs to
+do is associate additional C types with core XS types like T_PTROBJ.
+Lines that start with a hash \f(CW\*(C`#\*(C'\fR are considered comments and ignored
+in the \f(CW\*(C`TYPEMAP\*(C'\fR section, but are considered significant in \f(CW\*(C`INPUT\*(C'\fR
+and \f(CW\*(C`OUTPUT\*(C'\fR. Blank lines are generally ignored.
+.PP
+Traditionally, typemaps needed to be written to a separate file,
+conventionally called \f(CW\*(C`typemap\*(C'\fR in a CPAN distribution.  With
+ExtUtils::ParseXS (the XS compiler) version 3.12 or better which
+comes with perl 5.16, typemaps can also be embedded directly into
+XS code using a HERE-doc like syntax:
+.PP
+.Vb 3
+\&  TYPEMAP: <<HERE
+\&  ...
+\&  HERE
+.Ve
+.PP
+where \f(CW\*(C`HERE\*(C'\fR can be replaced by other identifiers like with normal
+Perl HERE-docs.  All details below about the typemap textual format
+remain valid.
+.PP
+The \f(CW\*(C`TYPEMAP\*(C'\fR section should contain one pair of C type and
+XS type per line as follows.  An example from the core typemap file:
+.PP
+.Vb 6
+\&  TYPEMAP
+\&  # all variants of char* is handled by the T_PV typemap
+\&  char *          T_PV
+\&  const char *    T_PV
+\&  unsigned char * T_PV
+\&  ...
+.Ve
+.PP
+The \f(CW\*(C`INPUT\*(C'\fR and \f(CW\*(C`OUTPUT\*(C'\fR sections have identical formats, that is,
+each unindented line starts a new in\- or output map respectively.
+A new in\- or output map must start with the name of the XS type to
+map on a line by itself, followed by the code that implements it
+indented on the following lines. Example:
+.PP
+.Vb 5
+\&  INPUT
+\&  T_PV
+\&    $var = ($type)SvPV_nolen($arg)
+\&  T_PTR
+\&    $var = INT2PTR($type,SvIV($arg))
+.Ve
+.PP
+We'll get to the meaning of those Perlish-looking variables in a
+little bit.
+.PP
+Finally, here's an example of the full typemap file for mapping C
+strings of the \f(CW\*(C`char *\*(C'\fR type to Perl scalars/strings:
+.PP
+.Vb 2
+\&  TYPEMAP
+\&  char *  T_PV
+\&
+\&  INPUT
+\&  T_PV
+\&    $var = ($type)SvPV_nolen($arg)
+\&
+\&  OUTPUT
+\&  T_PV
+\&    sv_setpv((SV*)$arg, $var);
+.Ve
+.PP
+Here's a more complicated example: suppose that you wanted
+\&\f(CW\*(C`struct netconfig\*(C'\fR to be blessed into the class \f(CW\*(C`Net::Config\*(C'\fR.
+One way to do this is to use underscores (_) to separate package
+names, as follows:
+.PP
+.Vb 1
+\&  typedef struct netconfig * Net_Config;
+.Ve
+.PP
+And then provide a typemap entry \f(CW\*(C`T_PTROBJ_SPECIAL\*(C'\fR that maps
+underscores to double-colons (::), and declare \f(CW\*(C`Net_Config\*(C'\fR to be of
+that type:
+.PP
+.Vb 2
+\&  TYPEMAP
+\&  Net_Config      T_PTROBJ_SPECIAL
+\&
+\&  INPUT
+\&  T_PTROBJ_SPECIAL
+\&    if (sv_derived_from($arg, \e"${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e")){
+\&      IV tmp = SvIV((SV*)SvRV($arg));
+\&      $var = INT2PTR($type, tmp);
+\&    }
+\&    else
+\&      croak(\e"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e")
+\&
+\&  OUTPUT
+\&  T_PTROBJ_SPECIAL
+\&    sv_setref_pv($arg, \e"${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e",
+\&                 (void*)$var);
+.Ve
+.PP
+The INPUT and OUTPUT sections substitute underscores for double-colons
+on the fly, giving the desired effect.  This example demonstrates some
+of the power and versatility of the typemap facility.
+.PP
+The \f(CW\*(C`INT2PTR\*(C'\fR macro (defined in perl.h) casts an integer to a pointer
+of a given type, taking care of the possible different size of integers
+and pointers.  There are also \f(CW\*(C`PTR2IV\*(C'\fR, \f(CW\*(C`PTR2UV\*(C'\fR, \f(CW\*(C`PTR2NV\*(C'\fR macros,
+to map the other way, which may be useful in OUTPUT sections.
+.SS "The Role of the typemap File in Your Distribution"
+.IX Subsection "The Role of the typemap File in Your Distribution"
+The default typemap in the \fIlib/ExtUtils\fR directory of the Perl source
+contains many useful types which can be used by Perl extensions.  Some
+extensions define additional typemaps which they keep in their own directory.
+These additional typemaps may reference INPUT and OUTPUT maps in the main
+typemap.  The \fBxsubpp\fR compiler will allow the extension's own typemap to
+override any mappings which are in the default typemap.  Instead of using
+an additional \fItypemap\fR file, typemaps may be embedded verbatim in XS
+with a heredoc-like syntax.  See the documentation on the \f(CW\*(C`TYPEMAP:\*(C'\fR XS
+keyword.
+.PP
+For CPAN distributions, you can assume that the XS types defined by
+the perl core are already available. Additionally, the core typemap
+has default XS types for a large number of C types.  For example, if
+you simply return a \f(CW\*(C`char *\*(C'\fR from your XSUB, the core typemap will
+have this C type associated with the T_PV XS type.  That means your
+C string will be copied into the PV (pointer value) slot of a new scalar
+that will be returned from your XSUB to Perl.
+.PP
+If you're developing a CPAN distribution using XS, you may add your own
+file called \fItypemap\fR to the distribution.  That file may contain
+typemaps that either map types that are specific to your code or that
+override the core typemap file's mappings for common C types.
+.SS "Sharing typemaps Between CPAN Distributions"
+.IX Subsection "Sharing typemaps Between CPAN Distributions"
+Starting with ExtUtils::ParseXS version 3.13_01 (comes with perl 5.16
+and better), it is rather easy to share typemap code between multiple
+CPAN distributions. The general idea is to share it as a module that
+offers a certain API and have the dependent modules declare that as a
+built-time requirement and import the typemap into the XS. An example
+of such a typemap-sharing module on CPAN is
+\&\f(CW\*(C`ExtUtils::Typemaps::Basic\*(C'\fR. Two steps to getting that module's
+typemaps available in your code:
+.IP \(bu 4
+Declare \f(CW\*(C`ExtUtils::Typemaps::Basic\*(C'\fR as a build-time dependency
+in \f(CW\*(C`Makefile.PL\*(C'\fR (use \f(CW\*(C`BUILD_REQUIRES\*(C'\fR), or in your \f(CW\*(C`Build.PL\*(C'\fR
+(use \f(CW\*(C`build_requires\*(C'\fR).
+.IP \(bu 4
+Include the following line in the XS section of your XS file:
+(don't break the line)
+.Sp
+.Vb 2
+\&  INCLUDE_COMMAND: $^X \-MExtUtils::Typemaps::Cmd
+\&                   \-e "print embeddable_typemap(q{Basic})"
+.Ve
+.SS "Writing typemap Entries"
+.IX Subsection "Writing typemap Entries"
+Each INPUT or OUTPUT typemap entry is a double-quoted Perl string that
+will be evaluated in the presence of certain variables to get the
+final C code for mapping a certain C type.
+.PP
+This means that you can embed Perl code in your typemap (C) code using
+constructs such as
+\&\f(CW\*(C`${ perl code that evaluates to scalar reference here }\*(C'\fR. A common
+use case is to generate error messages that refer to the true function
+name even when using the ALIAS XS feature:
+.PP
+.Vb 1
+\&  ${ $ALIAS ? \eq[GvNAME(CvGV(cv))] : \eqq[\e"$pname\e"] }
+.Ve
+.PP
+For many typemap examples, refer to the core typemap file that can be
+found in the perl source tree at \fIlib/ExtUtils/typemap\fR.
+.PP
+The Perl variables that are available for interpolation into typemaps
+are the following:
+.IP \(bu 4
+\&\fR\f(CI$var\fR\fI\fR \- the name of the input or output variable, eg. RETVAL for
+return values.
+.IP \(bu 4
+\&\fR\f(CI$type\fR\fI\fR \- the raw C type of the parameter, any \f(CW\*(C`:\*(C'\fR replaced with
+\&\f(CW\*(C`_\*(C'\fR.
+e.g. for a type of \f(CW\*(C`Foo::Bar\*(C'\fR, \fI\fR\f(CI$type\fR\fI\fR is \f(CW\*(C`Foo_\|_Bar\*(C'\fR
+.IP \(bu 4
+\&\fR\f(CI$ntype\fR\fI\fR \- the supplied type with \f(CW\*(C`*\*(C'\fR replaced with \f(CW\*(C`Ptr\*(C'\fR.
+e.g. for a type of \f(CW\*(C`Foo*\*(C'\fR, \fI\fR\f(CI$ntype\fR\fI\fR is \f(CW\*(C`FooPtr\*(C'\fR
+.IP \(bu 4
+\&\fR\f(CI$arg\fR\fI\fR \- the stack entry, that the parameter is input from or output
+to, e.g. \f(CWST(0)\fR
+.IP \(bu 4
+\&\fR\f(CI$argoff\fR\fI\fR \- the argument stack offset of the argument.  ie. 0 for the
+first argument, etc.
+.IP \(bu 4
+\&\fR\f(CI$pname\fR\fI\fR \- the full name of the XSUB, with including the \f(CW\*(C`PACKAGE\*(C'\fR
+name, with any \f(CW\*(C`PREFIX\*(C'\fR stripped.  This is the non-ALIAS name.
+.IP \(bu 4
+\&\fR\f(CI$Package\fR\fI\fR \- the package specified by the most recent \f(CW\*(C`PACKAGE\*(C'\fR
+keyword.
+.IP \(bu 4
+\&\fR\f(CI$ALIAS\fR\fI\fR \- non-zero if the current XSUB has any aliases declared with
+\&\f(CW\*(C`ALIAS\*(C'\fR.
+.SS "Full Listing of Core Typemaps"
+.IX Subsection "Full Listing of Core Typemaps"
+Each C type is represented by an entry in the typemap file that
+is responsible for converting perl variables (SV, AV, HV, CV, etc.)
+to and from that type. The following sections list all XS types
+that come with perl by default.
+.IP T_SV 4
+.IX Item "T_SV"
+This simply passes the C representation of the Perl variable (an SV*)
+in and out of the XS layer. This can be used if the C code wants
+to deal directly with the Perl variable.
+.IP T_SVREF 4
+.IX Item "T_SVREF"
+Used to pass in and return a reference to an SV.
+.Sp
+Note that this typemap does not decrement the reference count
+when returning the reference to an SV*.
+See also: T_SVREF_REFCOUNT_FIXED
+.IP T_SVREF_FIXED 4
+.IX Item "T_SVREF_FIXED"
+Used to pass in and return a reference to an SV.
+This is a fixed
+variant of T_SVREF that decrements the refcount appropriately
+when returning a reference to an SV*. Introduced in perl 5.15.4.
+.IP T_AVREF 4
+.IX Item "T_AVREF"
+From the perl level this is a reference to a perl array.
+From the C level this is a pointer to an AV.
+.Sp
+Note that this typemap does not decrement the reference count
+when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
+.IP T_AVREF_REFCOUNT_FIXED 4
+.IX Item "T_AVREF_REFCOUNT_FIXED"
+From the perl level this is a reference to a perl array.
+From the C level this is a pointer to an AV. This is a fixed
+variant of T_AVREF that decrements the refcount appropriately
+when returning an AV*. Introduced in perl 5.15.4.
+.IP T_HVREF 4
+.IX Item "T_HVREF"
+From the perl level this is a reference to a perl hash.
+From the C level this is a pointer to an HV.
+.Sp
+Note that this typemap does not decrement the reference count
+when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
+.IP T_HVREF_REFCOUNT_FIXED 4
+.IX Item "T_HVREF_REFCOUNT_FIXED"
+From the perl level this is a reference to a perl hash.
+From the C level this is a pointer to an HV. This is a fixed
+variant of T_HVREF that decrements the refcount appropriately
+when returning an HV*. Introduced in perl 5.15.4.
+.IP T_CVREF 4
+.IX Item "T_CVREF"
+From the perl level this is a reference to a perl subroutine
+(e.g. \f(CW$sub\fR = sub { 1 };). From the C level this is a pointer
+to a CV.
+.Sp
+Note that this typemap does not decrement the reference count
+when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
+.IP T_CVREF_REFCOUNT_FIXED 4
+.IX Item "T_CVREF_REFCOUNT_FIXED"
+From the perl level this is a reference to a perl subroutine
+(e.g. \f(CW$sub\fR = sub { 1 };). From the C level this is a pointer
+to a CV.
+.Sp
+This is a fixed
+variant of T_HVREF that decrements the refcount appropriately
+when returning an HV*. Introduced in perl 5.15.4.
+.IP T_SYSRET 4
+.IX Item "T_SYSRET"
+The T_SYSRET typemap is used to process return values from system calls.
+It is only meaningful when passing values from C to perl (there is
+no concept of passing a system return value from Perl to C).
+.Sp
+System calls return \-1 on error (setting ERRNO with the reason)
+and (usually) 0 on success. If the return value is \-1 this typemap
+returns \f(CW\*(C`undef\*(C'\fR. If the return value is not \-1, this typemap
+translates a 0 (perl false) to "0 but true" (which
+is perl true) or returns the value itself, to indicate that the
+command succeeded.
+.Sp
+The POSIX module makes extensive use of this type.
+.IP T_UV 4
+.IX Item "T_UV"
+An unsigned integer.
+.IP T_IV 4
+.IX Item "T_IV"
+A signed integer. This is cast to the required integer type when
+passed to C and converted to an IV when passed back to Perl.
+.IP T_INT 4
+.IX Item "T_INT"
+A signed integer. This typemap converts the Perl value to a native
+integer type (the \f(CW\*(C`int\*(C'\fR type on the current platform). When returning
+the value to perl it is processed in the same way as for T_IV.
+.Sp
+Its behaviour is identical to using an \f(CW\*(C`int\*(C'\fR type in XS with T_IV.
+.IP T_ENUM 4
+.IX Item "T_ENUM"
+An enum value. Used to transfer an enum component
+from C. There is no reason to pass an enum value to C since
+it is stored as an IV inside perl.
+.IP T_BOOL 4
+.IX Item "T_BOOL"
+A boolean type. This can be used to pass true and false values to and
+from C.
+.IP T_U_INT 4
+.IX Item "T_U_INT"
+This is for unsigned integers. It is equivalent to using T_UV
+but explicitly casts the variable to type \f(CW\*(C`unsigned int\*(C'\fR.
+The default type for \f(CW\*(C`unsigned int\*(C'\fR is T_UV.
+.IP T_SHORT 4
+.IX Item "T_SHORT"
+Short integers. This is equivalent to T_IV but explicitly casts
+the return to type \f(CW\*(C`short\*(C'\fR. The default typemap for \f(CW\*(C`short\*(C'\fR
+is T_IV.
+.IP T_U_SHORT 4
+.IX Item "T_U_SHORT"
+Unsigned short integers. This is equivalent to T_UV but explicitly
+casts the return to type \f(CW\*(C`unsigned short\*(C'\fR. The default typemap for
+\&\f(CW\*(C`unsigned short\*(C'\fR is T_UV.
+.Sp
+T_U_SHORT is used for type \f(CW\*(C`U16\*(C'\fR in the standard typemap.
+.IP T_LONG 4
+.IX Item "T_LONG"
+Long integers. This is equivalent to T_IV but explicitly casts
+the return to type \f(CW\*(C`long\*(C'\fR. The default typemap for \f(CW\*(C`long\*(C'\fR
+is T_IV.
+.IP T_U_LONG 4
+.IX Item "T_U_LONG"
+Unsigned long integers. This is equivalent to T_UV but explicitly
+casts the return to type \f(CW\*(C`unsigned long\*(C'\fR. The default typemap for
+\&\f(CW\*(C`unsigned long\*(C'\fR is T_UV.
+.Sp
+T_U_LONG is used for type \f(CW\*(C`U32\*(C'\fR in the standard typemap.
+.IP T_CHAR 4
+.IX Item "T_CHAR"
+Single 8\-bit characters.
+.IP T_U_CHAR 4
+.IX Item "T_U_CHAR"
+An unsigned byte.
+.IP T_FLOAT 4
+.IX Item "T_FLOAT"
+A floating point number. This typemap guarantees to return a variable
+cast to a \f(CW\*(C`float\*(C'\fR.
+.IP T_NV 4
+.IX Item "T_NV"
+A Perl floating point number. Similar to T_IV and T_UV in that the
+return type is cast to the requested numeric type rather than
+to a specific type.
+.IP T_DOUBLE 4
+.IX Item "T_DOUBLE"
+A double precision floating point number. This typemap guarantees to
+return a variable cast to a \f(CW\*(C`double\*(C'\fR.
+.IP T_PV 4
+.IX Item "T_PV"
+A string (char *).
+.IP T_PTR 4
+.IX Item "T_PTR"
+A memory address (pointer). Typically associated with a \f(CW\*(C`void *\*(C'\fR
+type.
+.IP T_PTRREF 4
+.IX Item "T_PTRREF"
+Similar to T_PTR except that the pointer is stored in a scalar and the
+reference to that scalar is returned to the caller. This can be used
+to hide the actual pointer value from the programmer since it is usually
+not required directly from within perl.
+.Sp
+The typemap checks that a scalar reference is passed from perl to XS.
+.IP T_PTROBJ 4
+.IX Item "T_PTROBJ"
+Similar to T_PTRREF except that the reference is blessed into a class.
+This allows the pointer to be used as an object. Most commonly used to
+deal with C structs. The typemap checks that the perl object passed
+into the XS routine is of the correct class (or part of a subclass).
+.Sp
+The pointer is blessed into a class that is derived from the name
+of type of the pointer but with all '*' in the name replaced with
+\&'Ptr'.
+.Sp
+For \f(CW\*(C`DESTROY\*(C'\fR XSUBs only, a T_PTROBJ is optimized to a T_PTRREF. This means
+the class check is skipped.
+.IP T_REF_IV_REF 4
+.IX Item "T_REF_IV_REF"
+NOT YET
+.IP T_REF_IV_PTR 4
+.IX Item "T_REF_IV_PTR"
+Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
+The difference is that when the object is passed back into XS it must be
+of the correct type (inheritance is not supported) while T_PTROBJ supports
+inheritance.
+.Sp
+The pointer is blessed into a class that is derived from the name
+of type of the pointer but with all '*' in the name replaced with
+\&'Ptr'.
+.Sp
+For \f(CW\*(C`DESTROY\*(C'\fR XSUBs only, a T_REF_IV_PTR is optimized to a T_PTRREF. This
+means the class check is skipped.
+.IP T_PTRDESC 4
+.IX Item "T_PTRDESC"
+NOT YET
+.IP T_REFREF 4
+.IX Item "T_REFREF"
+Similar to T_PTRREF, except the pointer stored in the referenced scalar
+is dereferenced and copied to the output variable. This means that
+T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
+.Sp
+Only the INPUT part of this is implemented (Perl to XSUB) and there
+are no known users in core or on CPAN.
+.IP T_REFOBJ 4
+.IX Item "T_REFOBJ"
+Like T_REFREF, except it does strict type checking (inheritance is not
+supported).
+.Sp
+For \f(CW\*(C`DESTROY\*(C'\fR XSUBs only, a T_REFOBJ is optimized to a T_REFREF. This means
+the class check is skipped.
+.IP T_OPAQUEPTR 4
+.IX Item "T_OPAQUEPTR"
+This can be used to store bytes in the string component of the
+SV. Here the representation of the data is irrelevant to perl and the
+bytes themselves are just stored in the SV. It is assumed that the C
+variable is a pointer (the bytes are copied from that memory
+location).  If the pointer is pointing to something that is
+represented by 8 bytes then those 8 bytes are stored in the SV (and
+\&\fBlength()\fR will report a value of 8). This entry is similar to T_OPAQUE.
+.Sp
+In principle the \fBunpack()\fR command can be used to convert the bytes
+back to a number (if the underlying type is known to be a number).
+.Sp
+This entry can be used to store a C structure (the number
+of bytes to be copied is calculated using the C \f(CW\*(C`sizeof\*(C'\fR function)
+and can be used as an alternative to T_PTRREF without having to worry
+about a memory leak (since Perl will clean up the SV).
+.IP T_OPAQUE 4
+.IX Item "T_OPAQUE"
+This can be used to store data from non-pointer types in the string
+part of an SV. It is similar to T_OPAQUEPTR except that the
+typemap retrieves the pointer directly rather than assuming it
+is being supplied. For example, if an integer is imported into
+Perl using T_OPAQUE rather than T_IV the underlying bytes representing
+the integer will be stored in the SV but the actual integer value will
+not be available. i.e. The data is opaque to perl.
+.Sp
+The data may be retrieved using the \f(CW\*(C`unpack\*(C'\fR function if the
+underlying type of the byte stream is known.
+.Sp
+T_OPAQUE supports input and output of simple types.
+T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
+is acceptable.
+.IP "Implicit array" 4
+.IX Item "Implicit array"
+xsubpp supports a special syntax for returning
+packed C arrays to perl. If the XS return type is given as
+.Sp
+.Vb 1
+\&  array(type, nelem)
+.Ve
+.Sp
+xsubpp will copy the contents of \f(CW\*(C`nelem * sizeof(type)\*(C'\fR bytes from
+RETVAL to an SV and push it onto the stack. This is only really useful
+if the number of items to be returned is known at compile time and you
+don't mind having a string of bytes in your SV.  Use T_ARRAY to push a
+variable number of arguments onto the return stack (they won't be
+packed as a single string though).
+.Sp
+This is similar to using T_OPAQUEPTR but can be used to process more
+than one element.
+.IP T_PACKED 4
+.IX Item "T_PACKED"
+Calls user-supplied functions for conversion. For \f(CW\*(C`OUTPUT\*(C'\fR
+(XSUB to Perl), a function named \f(CW\*(C`XS_pack_$ntype\*(C'\fR is called
+with the output Perl scalar and the C variable to convert from.
+\&\f(CW$ntype\fR is the normalized C type that is to be mapped to
+Perl. Normalized means that all \f(CW\*(C`*\*(C'\fR are replaced by the
+string \f(CW\*(C`Ptr\*(C'\fR. The return value of the function is ignored.
+.Sp
+Conversely for \f(CW\*(C`INPUT\*(C'\fR (Perl to XSUB) mapping, the
+function named \f(CW\*(C`XS_unpack_$ntype\*(C'\fR is called with the input Perl
+scalar as argument and the return value is cast to the mapped
+C type and assigned to the output C variable.
+.Sp
+An example conversion function for a typemapped struct
+\&\f(CW\*(C`foo_t *\*(C'\fR might be:
+.Sp
+.Vb 8
+\&  static void
+\&  XS_pack_foo_tPtr(SV *out, foo_t *in)
+\&  {
+\&    dTHX; /* alas, signature does not include pTHX_ */
+\&    HV* hash = newHV();
+\&    hv_stores(hash, "int_member", newSViv(in\->int_member));
+\&    hv_stores(hash, "float_member", newSVnv(in\->float_member));
+\&    /* ... */
+\&
+\&    /* mortalize as thy stack is not refcounted */
+\&    sv_setsv(out, sv_2mortal(newRV_noinc((SV*)hash)));
+\&  }
+.Ve
+.Sp
+The conversion from Perl to C is left as an exercise to the reader,
+but the prototype would be:
+.Sp
+.Vb 2
+\&  static foo_t *
+\&  XS_unpack_foo_tPtr(SV *in);
+.Ve
+.Sp
+Instead of an actual C function that has to fetch the thread context
+using \f(CW\*(C`dTHX\*(C'\fR, you can define macros of the same name and avoid the
+overhead. Also, keep in mind to possibly free the memory allocated by
+\&\f(CW\*(C`XS_unpack_foo_tPtr\*(C'\fR.
+.IP T_PACKEDARRAY 4
+.IX Item "T_PACKEDARRAY"
+T_PACKEDARRAY is similar to T_PACKED. In fact, the \f(CW\*(C`INPUT\*(C'\fR (Perl
+to XSUB) typemap is identical, but the \f(CW\*(C`OUTPUT\*(C'\fR typemap passes
+an additional argument to the \f(CW\*(C`XS_pack_$ntype\*(C'\fR function. This
+third parameter indicates the number of elements in the output
+so that the function can handle C arrays sanely. The variable
+needs to be declared by the user and must have the name
+\&\f(CW\*(C`count_$ntype\*(C'\fR where \f(CW$ntype\fR is the normalized C type name
+as explained above. The signature of the function would be for
+the example above and \f(CW\*(C`foo_t **\*(C'\fR:
+.Sp
+.Vb 2
+\&  static void
+\&  XS_pack_foo_tPtrPtr(SV *out, foo_t *in, UV count_foo_tPtrPtr);
+.Ve
+.Sp
+The type of the third parameter is arbitrary as far as the typemap
+is concerned. It just has to be in line with the declared variable.
+.Sp
+Of course, unless you know the number of elements in the
+\&\f(CW\*(C`sometype **\*(C'\fR C array, within your XSUB, the return value from
+\&\f(CW\*(C`foo_t ** XS_unpack_foo_tPtrPtr(...)\*(C'\fR will be hard to decipher.
+Since the details are all up to the XS author (the typemap user),
+there are several solutions, none of which particularly elegant.
+The most commonly seen solution has been to allocate memory for
+N+1 pointers and assign \f(CW\*(C`NULL\*(C'\fR to the (N+1)th to facilitate
+iteration.
+.Sp
+Alternatively, using a customized typemap for your purposes in
+the first place is probably preferable.
+.IP T_DATAUNIT 4
+.IX Item "T_DATAUNIT"
+NOT YET
+.IP T_CALLBACK 4
+.IX Item "T_CALLBACK"
+NOT YET
+.IP T_ARRAY 4
+.IX Item "T_ARRAY"
+This is used to convert the perl argument list to a C array
+and for pushing the contents of a C array onto the perl
+argument stack.
+.Sp
+The usual calling signature is
+.Sp
+.Vb 1
+\&  @out = array_func( @in );
+.Ve
+.Sp
+Any number of arguments can occur in the list before the array but
+the input and output arrays must be the last elements in the list.
+.Sp
+When used to pass a perl list to C the XS writer must provide a
+function (named after the array type but with 'Ptr' substituted for
+\&'*') to allocate the memory required to hold the list. A pointer
+should be returned. It is up to the XS writer to free the memory on
+exit from the function. The variable \f(CW\*(C`ix_$var\*(C'\fR is set to the number
+of elements in the new array.
+.Sp
+When returning a C array to Perl the XS writer must provide an integer
+variable called \f(CW\*(C`size_$var\*(C'\fR containing the number of elements in the
+array. This is used to determine how many elements should be pushed
+onto the return argument stack. This is not required on input since
+Perl knows how many arguments are on the stack when the routine is
+called. Ordinarily this variable would be called \f(CW\*(C`size_RETVAL\*(C'\fR.
+.Sp
+Additionally, the type of each element is determined from the type of
+the array. If the array uses type \f(CW\*(C`intArray *\*(C'\fR xsubpp will
+automatically work out that it contains variables of type \f(CW\*(C`int\*(C'\fR and
+use that typemap entry to perform the copy of each element. All
+pointer '*' and 'Array' tags are removed from the name to determine
+the subtype.
+.IP T_STDIO 4
+.IX Item "T_STDIO"
+This is used for passing perl filehandles to and from C using
+\&\f(CW\*(C`FILE *\*(C'\fR structures.
+.IP T_INOUT 4
+.IX Item "T_INOUT"
+This is used for passing perl filehandles to and from C using
+\&\f(CW\*(C`PerlIO *\*(C'\fR structures. The file handle can used for reading and
+writing. This corresponds to the \f(CW\*(C`+<\*(C'\fR mode, see also T_IN
+and T_OUT.
+.Sp
+See perliol for more information on the Perl IO abstraction
+layer. Perl must have been built with \f(CW\*(C`\-Duseperlio\*(C'\fR.
+.Sp
+There is no check to assert that the filehandle passed from Perl
+to C was created with the right \f(CWopen()\fR mode.
+.Sp
+Hint: The perlxstut tutorial covers the T_INOUT, T_IN, and T_OUT
+XS types nicely.
+.IP T_IN 4
+.IX Item "T_IN"
+Same as T_INOUT, but the filehandle that is returned from C to Perl
+can only be used for reading (mode \f(CW\*(C`<\*(C'\fR).
+.IP T_OUT 4
+.IX Item "T_OUT"
+Same as T_INOUT, but the filehandle that is returned from C to Perl
+is set to use the open mode \f(CW\*(C`+>\*(C'\fR.
diff --git a/upstream/mageia-cauldron/man1/pf2afm.1 b/upstream/mageia-cauldron/man1/pf2afm.1
new file mode 100644
index 00000000..d0b07708
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pf2afm.1
@@ -0,0 +1,22 @@
+.TH PF2AFM 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+pf2afm \- Make an AFM file from Postscript (PFB/PFA/PFM) font files using ghostscript
+.SH SYNOPSIS
+\fBpf2afm\fR  \fIfontfilename\fR
+.SH DESCRIPTION
+This script invokes
+.BR gs (1)
+to make an AFM file from PFB / PFA and (optionally) PFM files.
+Output goes to
+.IR fontfilename.afm ,
+which must not already exist.
+.SH SEE ALSO
+gs(1)
+.br
+pf2afm.ps in the Ghostscript lib directory.
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/pfbtopfa.1 b/upstream/mageia-cauldron/man1/pfbtopfa.1
new file mode 100644
index 00000000..9b01b0d2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pfbtopfa.1
@@ -0,0 +1,17 @@
+.TH PFBTOPFA 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+pfbtopfa \- Convert Postscript .pfb fonts to .pfa format using ghostscript
+.SH SYNOPSIS
+\fBpfbtopfa\fR \fIinput.pfb\fR \fI[output.pfa]\fR
+.SH DESCRIPTION
+This script invokes
+.BR gs (1)
+to convert a .pfb file into a .pfa file.
+.SH SEE ALSO
+gs(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/pfbtops.1 b/upstream/mageia-cauldron/man1/pfbtops.1
new file mode 100644
index 00000000..0b96cca5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pfbtops.1
@@ -0,0 +1,98 @@
+.TH PFBTOPS 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+pfbtops \- translate Printer Font Binary files to PostScript ASCII
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY pfbtops
+.RI [ pfb-file ]
+.YS
+.
+.SY pfbtops
+.B \-\-help
+.YS
+.
+.SY pfbtops
+.B \-v
+.SY pfbtops
+.B \-\-version
+.YS
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.I pfbtops
+translates a PostScript font in Printer Font Binary (PFB) format to
+ASCII, splitting overlong lines in text packets into smaller chunks.
+.
+If
+.I pfb-file
+is omitted, the PFB file will be read from the standard input.
+.
+The ASCII format PostScript font will be written on the standard output.
+.
+PostScript fonts for MS-DOS are normally supplied in PFB format.
+.
+.
+.LP
+The resulting ASCII format PostScript font can be used with groff,
+if it is first listed in
+.I /usr/\:share/\:groff/\:1.22.4/\:font/\:devps/\:download
+and
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/\:devpdf/\:download .
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.TP
+.B \-\-help
+Display a usage message and exit.
+.
+.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.IR grops (1),
+.IR gropdf (1)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/pfmtopam.1 b/upstream/mageia-cauldron/man1/pfmtopam.1
new file mode 100644
index 00000000..e95cf13f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pfmtopam.1
@@ -0,0 +1,91 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pfmtopam User Manual" 0 "10 April 2004" "netpbm documentation"
+
+.SH NAME
+pfmtopam - Convert PFM (Portable Float Map) image to Netpbm format
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpfmtopam\fP
+[\fB-maxval=\fP\fIn\fP]
+[\fB-verbose\fP]
+[\fIimagefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpfmtopam\fP reads a PFM (Portable Float Map) image and converts
+it to PAM.
+.PP
+See
+.BR "\fBpamtopfm\fP" (1)\c
+\& for a description of
+PFM.
+.PP
+If you want one of the older, more portable Netpbm formats, run the
+output through \fBpamtopnm\fP.
+
+\fBpamtopfm\fP creates a PAM with tuple type "RGB" or
+"GRAYSCALE" depending on whether or not the PFM is in the color
+subformat.
+.PP
+Use
+.BR "\fBpamtopfm\fP" (1)\c
+\& to convert a PFM
+image to Netpbm format.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpfmtopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-maxval=\fP\fIn\fP
+.sp
+This specifies the maxval for the PAM.  Default is 255.
+
+.TP
+\fB-verbose\fP
+.sp
+This causes \fBpfmtopam\fP to display messages describing 
+     the PFM input file.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopfm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpfmtopam\fP was added to Netpbm in Release 10.22 (April 2004).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pfmtopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmabel.1 b/upstream/mageia-cauldron/man1/pgmabel.1
new file mode 100644
index 00000000..945599e5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmabel.1
@@ -0,0 +1,132 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmabel User Manual" 0 "June 2002" "netpbm documentation"
+
+.SH NAME
+pgmabel - create cross section using Abel Integration for Deconvolution
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmabel\fP
+[\fB-help\fP]
+[\fB-axis\fP \fIaxis\fP]
+[\fB-factor\fP \fIfactor\fP]
+[\fB-pixsize\fP \fIpixsize\fP]
+[\fB-left\fP | \fB-right\fP]
+[\fB-verbose\fP]
+[\fIfilespec\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmabel\fP reads as input a PGM image, which it assumes to be an
+image of a rotational symmetric transparent object.  The image must have
+a vertical symmetry axis.  \fBpgmabel\fP produces as output an image of
+a cross-section of the image.
+
+\fBpgmabel\fP does the calculation by performing the Abel Integration
+for Deconvolution of an axial-symmetrical image by solving the system
+of linear equations.
+
+After integration, \fBpgmabel\fP weights all gray-values of one side
+by the surface area of the calculated ring in square pixels divided by
+4*\fIfactor\fP multiplied by the size of one pixel (\fIpixsize\fP).
+With the \fB-verbose\fP option, \fBpgmabel\fP prints the weighting
+factors.
+.PP
+Where the calculation generates a negative result, the output is black.
+.PP
+The computation is unstable against periodic structures with size 2 in
+the vertical direction.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmabel\fP recognizes the following
+command line options:
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+
+.TP
+\fB-help\fP
+Prints a help message.
+
+.TP
+\fB-axis\fP \fIaxis\fP
+Position of the axis of symmetry in the image in pixels from the left
+edge of the image.  Default is the center of the image.
+
+.TP
+\fB-factor\fP \fIfactor\fP
+User defined factor for enhancement of the output.  Use a \fIfactor\fP
+less than 1 for decreasing gary values.  Default is 1.0.
+
+.TP
+\fB-pixsize\fP \fIpixsize\fP
+The size of a pixel for getting scale invariant.  Default is 0.1.
+
+.TP
+\fB-left\fP
+Calculate only the left side of the image.  You cannot specify both
+\fBleft\fP and \fBright\fP.
+
+.TP
+\fB-right\fP
+Analogous to \fB-left\fP.
+
+.TP
+\fB-verbose\fP
+print information about the calculation.
+
+
+
+.UN example
+.SH EXAMPLE
+.PP
+Rotate a PGM image to get an image with a vertical axis of symmetry,
+then calculate the cross section:
+
+.nf
+    pnmrotate 90 file.pgm | pgmabel -axis 140 >cross_section.pgm
+
+.fi
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmrotate" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.3 (June 2002).
+
+.UN author
+.SH AUTHOR
+.PP
+Volker Schmidt (lefti@voyager.boerde.de)
+.PP
+Copyright (C) 1997-2002 German Aerospace research establishment
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmabel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmbentley.1 b/upstream/mageia-cauldron/man1/pgmbentley.1
new file mode 100644
index 00000000..dcc040f3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmbentley.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmbentley User Manual" 0 "11 January 1991" "netpbm documentation"
+
+.SH NAME
+pgmbentley - Bentleyize a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmbentley\fP
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmbentley\fP reads a PGM image as input and performs the
+Bentley Effect, and writes a PGM image as output.
+.PP
+The Bentley Effect is described in "Beyond Photography"
+by Holzmann, chapter 4, photo 4.  It's a vertical smearing based on
+brightness.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmbentley\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmoil" (1)\c
+\&,
+.BR "ppmrelief" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Wilson Bent (\fIwhb@hoh-2.att.com\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmbentley.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmcrater.1 b/upstream/mageia-cauldron/man1/pgmcrater.1
new file mode 100644
index 00000000..25414778
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmcrater.1
@@ -0,0 +1,100 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmcrater User Manual" 0 "26 July 2014" "netpbm documentation"
+
+.SH NAME
+
+pgmcrater - create cratered terrain by fractal forgery
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmcrater\fP
+
+[\fB-number\fP \fIn\fP]
+
+[\fB-height\fP|\fB-ysize\fP \fIs\fP]
+
+[\fB-width\fP|\fB-xsize\fP \fIs\fP]
+
+[\fB-gamma\fP \fIg\fP]
+
+[\fB-randomseed=\fP\fIinteger\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmcrater\fP is obsolete.  All it does now is invoke
+\fBpamcrater\fP, \fBpamshadedrelief\fP, and \fBpamtopnm\fP.  You should use
+those programs in any new application, or if you are modifying an old program
+or process that does not have to work with a version of Netpbm before 10.68
+(September 2014).  \fBpgmcrater\fP exists only for backward compatibility.
+.PP
+The combination of the three programs mentioned above performs the same
+function as traditional \fBpgmcrater\fP.
+.PP
+\fBpgmcrater\fP's \fB-number\fP, \fB-height\fP, \fB-width\fP,
+and \fB-randomseed\fP options are equivalent to the options of the same name
+on \fBpamcrater\fP.
+.PP
+\fBpgmcrater\fP's \fB-gamma\fP option is equivalent to
+the option of the same name on \fBpamshadedrelief\fP.
+.PP
+\fBpgmcrater\fP's \fB-ysize\fP option is identical to \fB-height\fP;
+\fB-xsize\fP is identical to \fB-width\fP.
+.PP
+Note: The former \fBpgmcrater\fP code was split into \fBpamcrater\fP
+and \fBpamshadedrelief\fP.  The reason for the split is that having separate
+programs is more consistent with Netpbm's building block philosophy.  It is
+possible the separate components can be used in other applications.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcrater" (1)\c
+\&,
+.BR "pamshadedrelief" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmcrater.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmdeshadow.1 b/upstream/mageia-cauldron/man1/pgmdeshadow.1
new file mode 100644
index 00000000..1d4087ea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmdeshadow.1
@@ -0,0 +1,81 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmdeshadow User Manual" 0 "06 July 2006" "netpbm documentation"
+
+.SH NAME
+
+pgmdeshadow - Deshadow a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmdeshadow\fP
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmdeshadow\fP removes gray shadows from an image.  This is
+useful for an image containing text, such as a scanned book pages,
+where a shadow typically appears near the book crease or near one side
+of the image.  \fBpgmdeshadow\fP recognizes a gray shadow as an area
+of smoothly changing color, starting from the outer edges of the
+image.  The program uses a simple image reconstruction algorithm to
+determine the local shadow gray level, then divides each pixel's gray
+level by the local shadow gray level.
+.PP
+The algorithm is the "fast hybrid grayscale reruction"
+algorithm from Luc Vincent, "Morphological Grayscale Reruction in
+Image Analysis: Applications and Efficient Algorithms.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmdeshadow\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN references
+.SH REFERENCES
+
+
+
+.IP \(bu
+Luc Vincent, "Morphological Grayscale Reconstruction in Image
+Analysis: Applications and Efficient Algorithms," IEEE
+Transactions on Image Processing, vol. 2, no. 2, April 1993,
+pp. 176-201.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmshadow" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpgmdeshadow\fP was added to Netpbm in Version 10.35 (August 2006).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmdeshadow.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmedge.1 b/upstream/mageia-cauldron/man1/pgmedge.1
new file mode 100644
index 00000000..988ac1c6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmedge.1
@@ -0,0 +1,30 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmedge User Manual" 0 "March 2002" "netpbm documentation"
+
+
+.SH NAME
+
+pgmedge - replaced by pamedge
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmedge\fP was replaced in Netpbm 10.14 (March 2002) by
+.BR "pamedge" (1)\c
+\&.
+.PP
+\fBpamedge\fP is backward compatible with \fBpgmedge\fP, but works on
+color images too.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmedge.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmenhance.1 b/upstream/mageia-cauldron/man1/pgmenhance.1
new file mode 100644
index 00000000..0ed0e646
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmenhance.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmenhance User Manual" 0 "13 January 1989" "netpbm documentation"
+
+.SH NAME
+
+pgmenhance - edge-enhance a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmenhance\fP
+
+[-\fIN\fP]
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmenhance\fP reads a PGM image as input, enhances the edges,
+and writes a PGM image as output.
+.PP
+The edge enhancing technique is taken from Philip R. Thompson's
+"xim" program, which in turn took it from section 6 of
+"Digital Halftones by Dot Diffusion", D. E. Knuth, ACM
+Transaction on Graphics Vol. 6, No. 4, October 1987, which in turn got
+it from two 1976 papers by J. F. Jarvis et. al.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmenhance\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-\fP\fIN\fP
+.sp
+The optional \fB-\fP\fIN\fP option should be a digit from 1 to 9.
+1 is the lowest level of enhancement; 9 is the highest.  The default
+is 9.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamedge" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmenhance.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmhist.1 b/upstream/mageia-cauldron/man1/pgmhist.1
new file mode 100644
index 00000000..7db6b3b1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmhist.1
@@ -0,0 +1,148 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmhist User Manual" 0 "18 December 2021" "netpbm documentation"
+
+.SH NAME
+
+pgmhist - print a histogram of the values in a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmhist\fP
+
+[\fB-median\fP, \fB-quartile\fP, \fB-decile\fP]
+
+[\fB-forensic\fP]
+
+[\fB-machine\fP]
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmhist\fP reads a PGM image as input and prints a histogram of the
+gray values or other gray value distribution metrics.
+.PP
+If you specify none of \fB-median\fP, \fB-quartile\fP, or \fB-decile\fP,
+\fBpgmhist\fP prints a complete histogram showing how many pixels of each
+possible gray value exist in the image.  Along with each gray value, it tells
+you how many pixels are at lest as black as it and how many are at least as
+white.
+.PP
+\fB-median\fP, \fB-quartile\fP, and \fB-decile\fP options cause
+\fBpgmhist\fP instead to print the indicated quantiles.  Each quantile is a
+gray value that actually appears in the image (as opposed to fractional values
+that are sometimes used for quantiles).  The 3rd quartile is the least gray
+value for which at least 75% of the pixels are as dark or darker than it.
+The 4th quartile is the brightest gray value that appears in the image.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmhist\fP recognizes the following
+command line options:
+.PP
+You may specify at most one of \fB-median\fP, \fB-quartile\fP, and
+\fB-decile\fP.  If none of these is specified \fBpgmhist\fP prints
+a histogram of gray values.
+
+
+.TP
+\fB-median\fP
+.sp
+This option causes \fBpgmhist\fP to print the median gray value.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+.TP
+\fB-quartile\fP
+.sp
+This option causes \fBpgmhist\fP to print the four quartile gray values.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+.TP
+\fB-decile\fP
+.sp
+This option causes \fBpgmhist\fP to print the ten decile gray values.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+.TP
+\fB-forensic\fP
+.sp
+With this option, \fBpgmhist\fP works on images that contain invalid gray
+values.  Normally, like most Netpbm programs, \fBpgmhist\fP fails if it
+encounters a gray value greater than the maxval that the image declares.  The
+presence of such a value means the image is invalid, so the pixels have no
+meaning.  But with \fB-forensic\fP, \fBpgmhist\fP produces a histogram
+of the actual gray values without regard to maxval.  It issues messages
+summarizing the invalid pixels if there are any.
+.sp
+One use for this is to diagnose the problem that caused the invalid Netpbm
+image to exist.
+.sp
+There is a small exception to the ability of \fBpgmhist\fP to process
+invalid pixels even with \fB-forensic\fP: it can never process a gray value
+greater than 65535.  Note that in the rarely used Plain PGM format, it is
+possible for a number greater than that to appear where a gray value belongs.
+.sp
+This option was new in Netpbm 10.66 (March 2014).  But Netpbm older than
+10.66 does not properly reject invalid sample values, so the effect is very
+similar to \fB-forensic\fP.
+
+.TP
+\fB-machine\fP
+.sp
+This option causes \fBpgmhist\fP to print the information in a way
+easily digestible by a machine as opposed to a human.
+.sp
+For the quantiles, there is one line per quantile, in quantile order, and
+it consists of the gray value of the quantile in decimal with no leading
+zeroes.
+.sp
+For the full histogram output, it consists of one line per possible
+gray value (whether that value appears in the image or not), in order of
+the gray values.  The line consists of two tokens separated by a space.  The
+first is the gray value; the second is the number of pixels in the image that
+have that gray value.  Both are decimal numbers without leading zeroes.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmnorm" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmhist.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmkernel.1 b/upstream/mageia-cauldron/man1/pgmkernel.1
new file mode 100644
index 00000000..269fc4ad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmkernel.1
@@ -0,0 +1,127 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmkernel User Manual" 0 "19 December 2013" "netpbm documentation"
+
+.SH NAME
+pgmkernel - generate a convolution kernel
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpgmkernel\fP
+[\fB-weight=\fP\fInumber\fP]
+[\fB-maxval=\fP] {\fIsize\fP | \fIwidth\fP \fIheight\fP}
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmkernel\fP generates a convolution kernel that you can use
+with \fBpnmconvol\fP.  The kernel is one where the weight of each location
+is inversely proportional to its distance from the center of the kernel.
+.PP
+\fBpgmkernel\fP generates a PGM image of width and height \fIsize\fP
+if you specify one argument, or width \fIwidth\fP and height \fIheight\fP
+if you specify two arguments.
+.PP
+\fBpgmkernel\fP computes the convolution function K as follows.
+
+.RS
+K(i,j) = 1 / ( 1 + w * sqrt(i^2 + j^2)) 
+.RE
+
+where \fIw\fP is a coefficient specified via the \fB-weight\fP
+option.  \fIi\fP and \fIj\fP are measured in pixels.  K is zero
+everywhere beyond the specified kernel width and height.
+.PP
+The sample values in the PGM output have this value scaled and biased using
+the protocol \fBpnmconvol\fP specifies for representing the real numbers K
+in PGM.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmkernel\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-weight=\fP\fInumber\fP
+The distance from the center is weighted by this; a higher number means
+the value falls off more quickly as you go away from the center.
+.sp
+This must be a positive real number.
+.sp
+The default is 6.0.
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+The maxval for the PGM kernel.
+.sp
+Default is 255.
+.sp
+This option was new in Netpbm 10.65 (December 2013).  Before that, the
+maxval is always 255.
+    
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The computation time is proportional to \fIwidth\fP*\fIheight\fP.
+This increases rapidly with the increase of the kernel size.  A better
+approach could be using a FFT in these cases.
+
+.UN history
+.SH HISTORY
+.PP
+Before Netpbm 10.65 (December 2013), the output was always in
+Plain (text) PGM format.  (Now, like standard Netpbm programs, the default
+is raw PGM and you can get Plain PGM with a \fB-plain\fP option).
+.PP
+Before Netpbm 10.65 (December 2013), this manual said negative values
+for \fB-weight\fP were valid (as long as they were greater than -1.0).  But
+the program never worked with negative numbers and it isn't clear that the
+result would be useful, so \fB-weight\fP is now required to be nonnegative
+and the program fails gracefully if you specify a negative value.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&
+.BR "pamgauss" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmkernel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmmake.1 b/upstream/mageia-cauldron/man1/pgmmake.1
new file mode 100644
index 00000000..3490ae79
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmmake.1
@@ -0,0 +1,90 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmmake User Manual" 0 "19 February 2006" "netpbm documentation"
+
+.SH NAME
+pgmmake - create a PGM image of a specified gray level and dimensions
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmmake\fP
+[\fB-maxval=\fP\fImaxval\fP]
+\fIgraylevel\fP
+\fIwidth\fP
+\fIheight\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmmake\fP produces a PGM image of the specified gray level, width,
+height, and maxval.
+.PP
+Specify the gray level (\fIgraylevel\fP) as a decimal floating point
+number in the range [0, 1].  E.g. 1 is white, 0 is black, and 0.5 is
+half luminosity gray.
+
+.UN example
+.SH EXAMPLES
+
+.nf
+    pgmmake 1 50 50
+
+.fi
+.nf
+    pgmmake .2 50 100 -maxval=5
+
+.fi
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmmake\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+     The maxval for the generated image.  Default is 255.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmmake" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+This program was new in Netpbm 10.32 (February 2006).
+.PP
+With older Netpbm, use \fBppmmake\fP and \fBppmtopgm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmmake.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmmedian.1 b/upstream/mageia-cauldron/man1/pgmmedian.1
new file mode 100644
index 00000000..a585420f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmmedian.1
@@ -0,0 +1,161 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmmedian User Manual" 0 "20 January 2022" "netpbm documentation"
+
+.SH NAME
+pgmmedian - apply a median filter to a PGM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmmedian\fP
+
+[\fB-width=\fP\fIn\fP]
+
+[\fB-height=\fP\fIn\fP]
+
+[\fB-type=\fP\fImedian_type\fP]
+
+[\fB-cutoff=\fP\fIint\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmmedian\fP applies a median filter to a PGM image, using either
+the histogram sort or select kth value method to determine the median.
+.PP
+A median filter is a convolution filter in which the value of a pixel in
+the output is the median of a certain set of pixels in the neighborhood of the
+corresponding input pixel.  The effect is to eliminate locally extreme values.
+Such pixels typically show up as speckles.
+.PP
+Pixels at the edges of the image, pixels where the convolution kernel would
+go off the edge of the image, are just copied.  For example, if \fB-height\fP
+is 9, the first 4 and last 4 rows of the input image are just copied to the
+output.
+  
+.PP
+See the \fB-type\fP and \fB-cutoff\fP options for information on
+how \fBpgmmedian\fP chooses between the two methods.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmmedian\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-cutoff\fP \fIint\fP
+This option provides the cutoff value that \fBpgmmedian\fP uses
+to decide between using the histogram sort or select kth value method
+to find the median.
+
+If (\fImaxval\fP / ((\fIwidth\fP * \fIheight\fP) - 1)), where
+\fImaxval\fP is the maxval of the image and \fIwidth\fP and
+\fIheight\fP are the dimensions of the mask, is less than the cutoff
+value, \fBpgmmedian\fP uses histogram sort.  Otherwise, it uses kth
+value.
+.sp
+This option has no effect if you specify \fB-type\fP.
+.sp
+The default is 250
+
+.TP
+\fB-width=\fP\fIn\fP
+Width of the median mask to apply.
+.sp
+Maximum allowed is the width of the input image.
+.sp
+Default is 3.
+
+.TP
+\fB-height=\fP\fIn\fP
+Height of the median mask to apply.
+.sp
+Maximum allowed is the height of the input image.
+.sp
+Default is 3.
+
+.TP
+\fB-type\fP \fImedian_type\fP
+This option selects which method to use to find median regardless
+of cutoff value.  Choices are \fBhistogram_sort\fP and \fBselect\fP.
+.sp
+By default, \fBpgmmedian\fP decides which method to use as described
+under the \fB-cutoff\fP option.
+
+
+
+.UN references
+.SH REFERENCES
+
+
+
+.IP \(bu
+"Collected Algorithms from ACM" Volume II, Algorithm 489
+by Robert W. Floyd
+
+.IP \(bu
+"A Fast Two-Dimensional Median Filtering Algorithm" in
+"IEEE Transactions on Acoustics, Speech, and Signal
+Processing" Vol. ASSP-27, No. 1, February 1979
+
+.IP \(bu
+"Digital Image Processing Algorithms" by Ioannis
+Pitas, Prentice Hall, 1993 ISBN 0-13-145814-0
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmnoise" (1)\c
+\&,
+.BR "pamaddnoise" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pgmmorphconv" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpgmmedian\fP was added to Netpbm in Version 10.29 (August 2005).
+It had been distributed by Mike Burns via his own web site before that
+(and continued to be so).
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1996 by Mike Burns <\fIburns@cac.psu.edu\fP>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmmedian.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmminkowski.1 b/upstream/mageia-cauldron/man1/pgmminkowski.1
new file mode 100644
index 00000000..4e866727
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmminkowski.1
@@ -0,0 +1,113 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmminkowski User Manual" 0 "29 October 2002" "netpbm documentation"
+
+.SH NAME
+
+pgmminkowski - compute Minkowski integral
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmminkowski\fP \fIpgmfile\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpgmminkowski\fP computes the 3 Minkowski integrals of a PGM image. 
+.PP
+The Minkowski integrals mathematically characterize the shapes in the
+image and hence are the basis of "morphological image analysis."
+.PP
+Hadwiger's theorem has it that these integrals are the only
+motion-invariant, additive and conditionally continuous functions of a
+two-dimensional image, which means that they are preserved under
+certain kinds of deformations of the image.  On top of that, they are
+very easy and quickly calculated.  This makes them of interest for
+certain kinds of pattern recognition.
+.PP
+Basically, the Minkowski integrals are the area, total perimeter
+length, and the Euler characteristic of the image, where these metrics
+apply to the foreground image, not the rectangular PGM image itself.  The
+foreground image consists of all the pixels in the image that are
+white.  For a grayscale image, there is some threshold of intensity
+applied to categorize pixels into black and white, and the Minkowski
+integrals are calculated as a function of this threshold value. The
+total surface area refers to the number of white pixels in the PGM and
+the perimeter is the sum of perimeters of each closed white region in
+the PGM.
+.PP
+For a grayscale image, these numbers are a function of the threshold
+of what you want to call black or white.  \fBpgmminkowski\fP reports these
+numbers as a function of the threshold for all possible threshold
+values.  Since the total surface area can increase only as a function
+of the threshold, it is a reparameterization of the threshold.  It
+turns out that if you consider the other two functions, the boundary
+length and the Euler characteristic, as a function of the first one,
+the surface, you get two functions that are a fingerprint of the
+picture.  This fingerprint is e.g. sufficient to recognize the
+difference between pictures of different crystal lattices under a
+scanning tunnelling electron microscope.
+.PP
+For more information about Minkowski integrals, see e.g. 
+
+.IP \(bu
+
+.UR http://rugth30.phys.rug.nl/pdf/prechaos.pdf
+ J.S. Kole, K. Michielsen, and H. De Raedt, "Morphological Image Analysis of Quantum Motion in Billiards", Phys. Rev. E 63, 016201-1 - 016201-7 (2001) 
+.UE
+\&
+
+.IP \(bu
+K. Michielsen and
+H. De Raedt, "Integral-Geometry Morphological Image Analysis",
+Phys. Rep. 347, 461-538 (2001).
+
+
+.PP
+The output is suitable for direct use as a datafile in \fBgnuplot\fP.
+.PP
+In addition to the three Minkowski integrals, \fBpgmminkowski\fP also
+lists the horizontal and vertical edge counts.
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmminkowski\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmmorphconv" (1)\c
+\&
+.BR "pbmminkowski" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Luuk van Dijk, 2001.
+.PP
+Based on work which is Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmminkowski.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmmorphconv.1 b/upstream/mageia-cauldron/man1/pgmmorphconv.1
new file mode 100644
index 00000000..8e9b926b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmmorphconv.1
@@ -0,0 +1,141 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmmorphconv User Manual" 0 "29 March 2015" "netpbm documentation"
+
+.SH NAME
+
+pgmmorphconv - perform morphological convolutions: dilation, erosion
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmmorphconv\fP
+[
+ \fB-erode\fP |
+ \fB-dilate\fP |
+ \fB-open\fP |
+ \fB-close\fP |
+ \fB-gradient\fP
+]
+\fItemplatefile\fP
+[\fIpgmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmmorphconv\fP performs morphological convolutions on a
+PGM image: dilation and erosion.
+.PP
+\fBpgmmorphconv\fP performs a "topological" convolution.  For each
+pixel of the input, \fBpgmmorphconv\fP generates an output pixel in
+the same position.  To determine the intensity of the output pixel,
+\fBpgmmorphconv\fP lays the template image over the input image such
+that the middle pixel of the template is over the input pixel in
+question.  \fBpgmmorphconv\fP looks at the input pixels underneath each
+white pixel in the template.  For a dilation, the maximum intensity of
+all those pixels is the intensity of the output pixel.  For an erosion,
+it is the minimum.
+.PP
+Thus, the dilation effect is that bright areas of the input get bigger
+and dark areas smaller.  The erosion effect is the opposite.  The simplest
+template image would be one with a white pixel in the middle and the rest
+black.  This would produce an output image identical to the input.  Another
+simple template image is a fully white square.  This causes bright or dark
+areas to expand in all directions.  A template image that is white on the
+left side and black on the right would smear the image to the right.
+.PP
+The template file named by \fItemplatefile\fP contains the
+template image as a PBM image.  It must have an odd number of rows and
+an odd number of columns, so there is a definite middle pixel.  It
+must contain at least one white pixel.
+.PP
+This is similar to the continuous convolution done by
+\fBpnmconvol\fP, except that with \fBpnmconvol\fP the output intensity is
+a weighted average of nearby input pixels instead of a minimum or maximum.
+.PP
+This convolution changes the three Minkowski integrals in a predefined
+way, and can be used to filter an image to enhance certain features, to
+ease their automatic recognition.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmmorphconv\fP recognizes the following
+command line options:
+.PP
+The options \fB-erode\fP and \fB-dilate\fP obviously produce an
+erosion or dilation, respectively.  
+.PP
+The \fB-open\fP option causes
+\fBpgmmorphconv\fP to perform first an erode and then a dilate
+operation.  The \fB-close\fP option causes a dilate first and then an
+erode.  If you specify none of these options, it is the same as
+\fB-dilate\fP.
+.PP
+With \fB-gradient\fP, \fBpgmmorphconv\fP produces an image which is the
+difference between the eroded image and the dilated image.  \fB-gradient\fP
+was new in Netpbm 10.70 (March 2015).
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pgmminkowski" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmconvol" (1)\c
+\&
+.IP \(bu
+
+.BR "pgm" (1)\c
+\&
+
+.PP
+For more information about morphological convolutions, see e.g.
+
+.IP \(bu
+
+.UR http://rugth30.phys.rug.nl/pdf/prechaos.pdf
+ J.S. Kole, K. Michielsen, and H. De Raedt, "Morphological Image Analysis of Quantum Motion in Billiards", Phys. Rev. E 63, 016201-1 - 016201-7 (2001) 
+.UE
+\&
+.IP \(bu
+K. Michielsen and
+H. De Raedt, "Integral-Geometry Morphological Image Analysis",
+Phys. Rep. 347, 461-538 (2001).
+
+
+
+
+.UN authors
+.SH AUTHORS
+
+Luuk van Dijk, 2001.
+.PP
+Based on work which is Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmmorphconv.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmnoise.1 b/upstream/mageia-cauldron/man1/pgmnoise.1
new file mode 100644
index 00000000..9bbe8de5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmnoise.1
@@ -0,0 +1,101 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmnoise User Manual" 0 "27 June 2013" "netpbm documentation"
+
+.SH NAME
+pgmnoise - create a PGM image made up of white noise
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmnoise\fP \fIwidth\fP \fIheight\fP
+
+[\fB-maxval=\fP\fIn\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+.PP
+Minimum unique abbreviations of option are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmnoise\fP creates a PGM image that is made up of pixels
+of random brightness.
+.PP
+You specify the dimensions of the image with the \fIwidth\fP
+and \fIheight\fP arguments.
+.PP
+The randomness in the image is limited before Netpbm 10.37 (December
+2006) -- if you run the program twice in the same second, you may get
+identical output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmnoise\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-maxval=\fP\fIn\fP
+The maxval of the generated image.
+.sp
+Default is 255.
+.sp
+This option was new in Netpbm 10.63 (June 2013).
+
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBpgmnoise\fP uses a seed derived from the time of day
+and process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+.sp
+This option was new in Netpbm 10.45 (December 2008).
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pbmnoise" (1)\c
+\&
+.IP \(bu
+
+.BR "pgm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmnoise.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmnorm.1 b/upstream/mageia-cauldron/man1/pgmnorm.1
new file mode 100644
index 00000000..1d2e7157
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmnorm.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmnorm User Manual" 0 "March 2002" "netpbm documentation"
+
+.SH NAME
+
+pgmnorm - replaced by pnmnorm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmnorm\fP was replaced in Netpbm 9.25 (March 2002) by
+.BR "pnmnorm" (1)\c
+\&.
+.PP
+\fBpnmnorm\fP is backward compatible with \fBpgmnorm\fP, but it also
+handles PPM images.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmnorm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmoil.1 b/upstream/mageia-cauldron/man1/pgmoil.1
new file mode 100644
index 00000000..0031c102
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmoil.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmoil User Manual" 0 "July 2001" "netpbm documentation"
+
+.SH NAME
+
+pgmoil - replaced by pamoil
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmoil\fP was replaced in Netpbm 9.16 (July 2001) by
+.BR "pamoil" (1)\c
+\&.
+.PP
+\fBpamoil\fP is backward compatible with \fBpgmoil\fP, but works on
+color images too.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmoil.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmramp.1 b/upstream/mageia-cauldron/man1/pgmramp.1
new file mode 100644
index 00000000..9fd1b8bc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmramp.1
@@ -0,0 +1,139 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmramp User Manual" 0 "15 February 2014" "netpbm documentation"
+
+.SH NAME
+
+pgmramp - generate a grayscale ramp
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmramp\fP
+{\fB-lr\fP|\fB-tb\fP|\fB-rectangle\fP|\fB-ellipse\fP|\fB-diagonal\fP}
+[\fB-maxval=\fP\fImaxval\fP]
+\fIwidth\fP \fIheight\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Generates a graymap of the specified size containing a
+black-to-white ramp.  These ramps are useful for multiplying with
+other images, using \fBpamarith\fP.
+.PP
+The ramp is linear in brightness, not intensity.  I.e. the
+gamma-corrected sample values in the PGM rise linearly with distance
+from the corner of the image.  If you want a ramp that is linear in
+light intensity, use \fBpnmgamma\fP with \fBpgmramp\fP.
+.PP
+Options let you choose the shape of the ramp (left to right, inside
+out, etc.).  You can use \fBpamflip\fP to get more shapes.  For
+example, the \fB-lr\fP option gives you a left to right ramp and
+
+.nf
+\f(CW
+    $ pgmramp -lr 100 100 | pamflip -lr
+\fP
+
+.fi
+
+gives you a right to left ramp.
+.PP
+To generate a simple ramp of all the values from 0 to maxval, and not
+necessarily a graphic image, use
+.BR "pamseq" (1)\c
+\&.
+.PP
+\fBppmrainbow\fP does something similar to what \fBpgmramp\fP does,
+but for color.  The image fades between two colors of your choice.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmramp\fP recognizes the following
+command line options:
+.PP
+You must specify exactly one of the ramp type options.
+
+
+.TP
+\fB-lr\fP
+A left to right ramp.  Black on the left; white on the right.
+
+.TP
+\fB-tb\fP
+A top to bottom ramp.  Black on top; white on the bottom.
+
+.TP
+\fB-rectangle\fP
+An outside-in rectangular ramp.  It is black around the edges and white
+in the center.
+
+.TP
+\fB-ellipse\fP
+An outside-in elliptical ramp.  It is black around the edge and white
+in the center.
+
+.TP
+\fB-diagonal\fP
+A ramp from top left corner diagonally down to bottom right.  Black at
+the top left; white at the bottom right.
+.sp
+This option was new in Netpbm 10.66 (March 2014).
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+     The maxval for the generated image.  Default is 255.
+.sp
+     This option was new in Netpbm 10.1 (June 2002).  Before that, the maxval
+     is always 255.
+     
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpamflip\fP" (1)\c
+\&,
+.BR "\fBpamarith\fP" (1)\c
+\&,
+.BR "\fBpnmgamma\fP" (1)\c
+\&,
+.BR "\fBpamseq\fP" (1)\c
+\&,
+.BR "\fBppmrainbow\fP" (1)\c
+\&,
+.BR "\fBpamgradient\fP" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmramp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmslice.1 b/upstream/mageia-cauldron/man1/pgmslice.1
new file mode 100644
index 00000000..8b48e229
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmslice.1
@@ -0,0 +1,27 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmslice User Manual" 0 "22 June 2002" "netpbm documentation"
+
+.SH NAME
+
+pgmslice - extract one line of pixel values out of a PGM
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Starting with Netpbm 10.3, \fBpgmslice\fP is obsolete.  Use
+.BR "\fBpamslice\fP" (1)\c
+\& instead.  It is backward
+compatible.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmslice.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtexture.1 b/upstream/mageia-cauldron/man1/pgmtexture.1
new file mode 100644
index 00000000..e3817198
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtexture.1
@@ -0,0 +1,117 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtexture User Manual" 0 "22 August 1991" "netpbm documentation"
+
+.SH NAME
+
+pgmtexture - calculate textural features on a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtexture\fP
+
+[\fB-d\fP \fId\fP]
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtexture\fP reads a PGM image as input and calculates
+textural features based on spatial dependence matrices at 0, 45, 90,
+and 135 degrees for a distance \fId\fP (default = 1).
+.PP
+Textural features include:
+
+
+.IP \(bu
+Angular Second Moment
+.IP \(bu
+Contrast
+.IP \(bu
+Correlation
+.IP \(bu
+Variance
+.IP \(bu
+Inverse Difference Moment
+.IP \(bu
+Sum Average
+.IP \(bu
+Sum Variance
+.IP \(bu
+Sum Entropy
+.IP \(bu
+Entropy
+.IP \(bu
+Difference Variance
+.IP \(bu
+Difference Entropy
+.IP \(bu
+Information Measures of Correlation
+.IP \(bu
+Maximal Correlation Coefficient
+
+     
+.PP
+Algorithm taken from: \fIHaralick, R.M., K. Shanmugam, and
+I. Dinstein. 1973. Textural features for image classification.
+\fIIEEE Transactions on Systems, Man, and Cybertinetics,\fP
+SMC-3(6):610-621.\fP
+     
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmtexture\fP recognizes the following
+command line option:
+
+
+
+.TP
+-d \fIdistance\fP
+The distance.  Default is 1.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The method for finding the Maximal Correlation Coefficient, which requires
+finding the second largest eigenvalue of a matrix Q, does not always converge.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgm" (1)\c
+\&,
+.BR "pamsharpness" (1)\c
+\&,
+.BR "pamsharpmap" (1)\c
+\&,
+.BR "pgmedge" (1)\c
+\&,
+.BR "pgmminkowski" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Texas Agricultural Experiment Station, employer for
+hire of James Darrell McCauley. 
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtexture.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtofs.1 b/upstream/mageia-cauldron/man1/pgmtofs.1
new file mode 100644
index 00000000..1921387d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtofs.1
@@ -0,0 +1,59 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtofs User Manual" 0 "18 May 1990" "netpbm documentation"
+
+.SH NAME
+
+pgmtofs - convert PGM image to Usenix FaceSaver(tm) format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtofs\fP
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtofs\fP reads a PGM image as input and produces Usenix
+FaceSaver(tm) format as output.
+.PP
+FaceSaver is a registered trademark of Metron Computerware Ltd. of
+Oakland, CA.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmtofs\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "fstopgm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtofs.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtolispm.1 b/upstream/mageia-cauldron/man1/pgmtolispm.1
new file mode 100644
index 00000000..6d7bda9d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtolispm.1
@@ -0,0 +1,77 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtolispm User Manual" 0 "06 March 1990" "netpbm documentation"
+
+.SH NAME
+
+pgmtolispm - convert a PGM image to Lisp Machine format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtolispm\fP
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtolispm\fP reads a PGM image as input and produces a Lisp
+Machine bitmap as output.
+.PP
+This is the file format read by the tv:read-bit-array-file function
+on TI Explorer and Symbolics lisp machines.
+.PP
+Given a PGM (instead of a PBM), \fBpgmtolispm\fP outputs a
+multi-plane image.  This is probably not useful unless you have a
+color lisp machine.
+.PP
+Multi-plane bitmaps on lisp machines are color; but the lispm image
+file format does not include a color map, so we must treat it as a
+graymap instead.  This is unfortunate.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmtolispm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "lispmtopgm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+Output width is always rounded up to the nearest multiple of 32;
+this might not always be what you want, but it probably is (arrays
+which are not modulo 32 cannot be passed to the Lispm BITBLT function,
+and thus cannot easily be displayed on the screen).
+.PP
+No color.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtolispm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtopbm.1 b/upstream/mageia-cauldron/man1/pgmtopbm.1
new file mode 100644
index 00000000..81d5345b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtopbm.1
@@ -0,0 +1,104 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtopbm User Manual" 0 "17 July 2020" "netpbm documentation"
+
+.SH NAME
+
+pgmtopbm - convert a PGM image to PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtopbm\fP
+
+[\fB-floyd\fP | \fB-fs\fP | \fB-threshold\fP
+| \fB-hilbert\fP
+| \fB-dither8\fP | \fB-d8\fP | \fB-cluster3\fP
+| \fB-c3\fP | \fB-cluster4\fP | \fB-c4\fP
+| \fB-cluster8\fP | \fB-c8\fP]
+
+[\fB-value\fP \fIval\fP]
+
+[\fB-clump\fP \fIsize\fP]
+
+[\fB-randomseed\fP \fIinteger\fP]
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program is almost entirely obsolete since Netpbm 10.23 (July
+2004).  Use
+.BR "\fBpamditherbw\fP" (1)\c
+\& to do
+what this program used to do.
+.PP
+\fBpgmtopbm\fP never was the simple converter it appeared to be.
+It was a dithering program.  Unfortunately, it didn't do the dithering
+properly because it treated the PGM input samples as if they were
+directly proportional to light intensity, but they are actually
+gamma-adjusted.
+.PP
+\fBpamditherbw\fP is backward compatible with \fBpgmtopbm\fP
+except that it 
+
+.IP \(bu
+does the correct gamma adjustments.
+.IP \(bu
+produces PAM output instead of PBM.  (Modern Netpbm programs that
+accept PBM input also accept PAM input, but if you need actual PBM,
+you can use \fBpamtopnm\fP with \fBpamditherbw\fP).
+
+So use the manual for \fBpamditherbw\fP for \fBpgmtopbm\fP, except
+ignore anything that says it was added after Netpbm Release 10.23
+and ignore any options that are not shown in the synopsis above.
+.PP
+Although \fBpgmtopbm\fP is mostly obsolete, the simple threshold
+method (specified by \fB-threshold\fP) is an exception.  Unlike the
+other conversion methods, gamma-adjustment is not an issue with
+simple thresholding and \fBpgmtopbm\fP can produce PBM output
+directly.  Note that even in this basic mode of operation
+\fBpgmtopbm\fP may produce output which is slightly different from
+what \fBpamditherbw\fP does because of differences in internal
+calculation.
+.PP
+If you just want to convert a PGM image with maxval 1 to PBM,
+use
+.BR "\fBpamtopnm\fP" (1)\c
+\&.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pbmtopgm" (1)\c
+\&,
+.BR "pamthreshold" (1)\c
+\&,
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtopgm.1 b/upstream/mageia-cauldron/man1/pgmtopgm.1
new file mode 100644
index 00000000..34711083
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtopgm.1
@@ -0,0 +1,73 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtopgm User Manual" 0 "September 2002" "netpbm documentation"
+
+.SH NAME
+pgmtopgm - copy PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtopgm\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtopgm\fP simply copies a PGM image from Standard Input to
+Standard Output.  This may seem an unnecessary duplication of
+\fBcat\fP, but remember that a PGM program can read a PBM image as
+if it were PGM.  So \fBpgmtopgm\fP can read either a PBM or PGM
+image and produce a PGM image as output.
+.PP
+Even that is of limited usefulness because of the fact that almost
+any program to which you would feed the resulting PGM image could also
+just take the original image directly.  However, sometimes you really
+need a true PGM image.
+.PP
+When you know you have a PBM image and want a PGM image,
+\fBpbmtopgm\fP is a more general way to do that conversion.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoppm" (1)\c
+\&,
+.BR "pamtopam" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pbmtopgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.9 (September 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtoppm.1 b/upstream/mageia-cauldron/man1/pgmtoppm.1
new file mode 100644
index 00000000..b71ebe56
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtoppm.1
@@ -0,0 +1,180 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtoppm User Manual" 0 "02 October 2021" "netpbm documentation"
+
+.SH NAME
+
+pgmtoppm - colorize a PGM (grayscale) image into a PPM (color) image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtoppm\fP
+[\fB-black=\fP\fIcolorspec1\fP]
+[\fB-white=\fP\fIcolorspec2\fP]
+ [\fIpgmfile\fP]
+\fBpgmtoppm\fP \fB-map=\fP\fIfilename\fP [\fIpgmfile\fP]
+\fBpgmtoppm\fP \fIcolorspec\fP [\fIpgmfile\fP]
+\fBpgmtoppm\fP \fIcolorspec1\fP\fB-\fP\fIcolorspec2\fP [\fIpgmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+If all you want to do is convert PGM to PPM, keeping the same gray pixels,
+  you may not need to.  All Netpbm programs that expect PPM input also
+  recognize PGM.  And if you must have a PPM file, use \fBppmtoppm\fP
+  instead.  It is more efficient and easier to use.
+.PP
+\fBpgmtoppm\fP reads a PGM as input and produces a PPM file as
+output with a specific color assigned to each gray value in the input.
+.PP
+You can specify the color in the output to which black in the input maps,
+  and the color to which white maps.  All the gray values in between map
+  linearly (across a three dimensional space) to colors between the black and
+  white colors you specify.
+.PP
+Use the \fB-black\fP and \fB-white\fP options for this.  For historical
+  reasons, you can alternatively use a non-option argument to specify the
+  colors.  If you do that, \fBpgmtoppm\fP interprets the color argument
+  like this: if the argument takes the form \fIblack\fP-\fIwhite\fP,
+  it has the effect of \fB-black=\fP\fIblack\fP \fB-white=\fP\fIwhite\fP
+  If instead there is no hyphen in the color argument, it has the effect of
+  \fB-white=\fP\fIcolor_argument\fP.
+.PP
+Because of the historical syntax, it is not possible to let both
+  \fB-black\fP and \fB-white\fP default (but you shouldn't want to --
+  see below for advice on making such a null conversion).
+  
+.PP
+You can alternatively specify an entire colormap with the \fB-map\fP
+option.
+  
+.PP
+A more direct way to specify a particular color to replace each
+particular gray level is to use \fBpamlookup\fP.  You make an index
+file that explicitly associates a color with each possible gray level.
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpgmtoppm\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-black=\fP\fIcolorspec\fP
+The program maps black pixels in the input to this color in the output.
+The default is black.
+.sp
+Specify the color (\fIcolor\fP) as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+You cannot specify this together with \fB-map\fP.
+.sp
+This option was new in Netpbm 10.97 (December 2021).  Before that,
+  use the color argument.
+  
+.TP
+\fB-white=\fP\fIcolorspec\fP
+The program maps white pixels in the input to this color in the output.
+The default is white.
+.sp
+Specify the color (\fIcolor\fP) as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+You cannot specify this together with \fB-map\fP.
+.sp
+This option was new in Netpbm 10.97 (December 2021).  Before that,
+  use the color argument.
+
+.TP
+\fB-map=\fP\fIfilename\fP
+This option specifies a complete mapping of gray values in the input to
+    color values in the output.  The map file (named \fIfilename\fP) is just
+    a \fBppm\fP file; it can be any shape, all that matters is the colors in
+    it and their order.  In this case, black gets mapped into the first color
+    in the map file, and white gets mapped to the last and gray values in
+    between are mapped linearly onto the sequence of colors in between.  The
+    maxval of the output image is the maxval of the map image.
+
+
+
+  
+.UN maxval
+.SH NOTE - MAXVAL
+.PP
+When you don't use \fB-map\fP, the "maxval," or depth,
+of the output image is the same as that of the input image.  The
+maxval affects the color resolution, which may cause quantization
+errors you don't anticipate in your output.  For example, you have a
+simple black and white image as a PGM with maxval 1.  Run this image
+through \fBpgmtoppm 0f/00/00\fP to try to make the image black and
+faint red.  Because the output image will also have maxval 1, there is
+no such thing as faint red.  It has to be either full-on red or black.
+\fBpgmtoppm\fP rounds the color 0f/00/00 down to black, and you get
+an output image that is nothing but black.
+.PP
+The fix is easy: Pass the input through \fBpamdepth\fP on the way
+into \fBpgmtoppm\fP to increase its depth to something that would
+give you the resolution you need to get your desired color.  In this
+case, \fBpamdepth 16\fP would do it.  Or spare yourself the
+unnecessary thinking and just say \fBpamdepth 255\fP.
+.PP
+PBM input is a special case.  While you might think this would be
+equivalent to a PGM with maxval 1 since only two gray levels are
+necessary to represent a PBM image, \fBpgmtoppm\fP, like all Netpbm
+programs, in fact treats it as a maxval of 255.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoppm" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "rgb3toppm" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "ppmtorgb3" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtosbig.1 b/upstream/mageia-cauldron/man1/pgmtosbig.1
new file mode 100644
index 00000000..ca48cead
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtosbig.1
@@ -0,0 +1,79 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtosbig User Manual" 0 "18 January 2015" "netpbm documentation"
+
+.SH NAME
+
+pgmtosbig - convert PGM image to SBIG format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtosbig\fP
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtosbig\fP reads a PGM image as input and produces a
+Santa Barbara Instrument Group SBIG Type 3 image as output.
+.PP
+Note that this format is distinct from the SBIG ST-4 format.
+
+
+.IP \(bu
+The image is uncompressed
+.IP \(bu
+The image says it is from a "ST-6" camera
+.IP \(bu
+The image header has these lines:
+
+.IP \(bu
+camera type
+.IP \(bu
+height
+.IP \(bu
+width
+.IP \(bu
+saturation level  
+
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmtosbig\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "sbigtopgm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpgmtosbig\fP was new in Netpbm 10.70, and was intended primarily as a
+test tool for \fBsbigtopgm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtosbig.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgmtost4.1 b/upstream/mageia-cauldron/man1/pgmtost4.1
new file mode 100644
index 00000000..4fb1ce88
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgmtost4.1
@@ -0,0 +1,81 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pgmtost4 User Manual" 0 "20 January 2015" "netpbm documentation"
+
+.SH NAME
+
+pgmtost4 - convert PGM image to SBIG ST-4 format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpgmtost4\fP
+
+[\fIpgmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpgmtost4\fP reads a PGM image as input and produces a
+Santa Barbara Instrument Group SBIG ST-4 camera CCD image as output.
+.PP
+Note that this format is distinct from the SBIG format used with mos
+SBIG cameras.  For that, see \fBpgmtosbig\fP
+
+
+.IP \(bu
+The image is uncompressed
+.IP \(bu
+The image says it is from a "ST-6" camera
+.IP \(bu
+The image header has these lines:
+
+.IP \(bu
+camera type
+.IP \(bu
+height
+.IP \(bu
+width
+.IP \(bu
+saturation level  
+
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpgmtost4\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "st4topgm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpgmtosbig\fP was new in Netpbm 10.70, and was intended primarily as a
+test tool for \fBsbigtopgm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pgmtost4.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pgpewrap.1 b/upstream/mageia-cauldron/man1/pgpewrap.1
new file mode 100644
index 00000000..20327349
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pgpewrap.1
@@ -0,0 +1,46 @@
+.\" -*-nroff-*-
+.\"
+.\"     pgpewrap, a command line munging tool
+.\"     Manpage Copyright (c) 2013 Honza Horak
+.\"
+.\"     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 2 of the License, or
+.\"     (at your option) any later version.
+.\"
+.\"     This program is distributed in the hope that it will be useful,
+.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"     GNU General Public License for more details.
+.\"
+.\"     You should have received a copy of the GNU General Public License
+.\"     along with this program; if not, write to the Free Software
+.\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+.\"
+.TH pgpewrap 1 "May 2013" Unix "User Manuals"
+.SH NAME
+pgpewrap \- Mutt command line munging tool
+
+.SH SYNTAX
+.PP
+\fBpgpewrap\fP [ \fBflags\fP ] \-\- \fBprefix\fP [ \fBrecipients\fP ]
+
+.SH DESCRIPTION
+.PP
+This is a little C program which does some command line munging: The
+first argument is a command to be executed.  When \fBpgpewrap\fP
+encounters a "\-\-" (dash\-dash) argument, it will interpret the next
+argument as a prefix which is put in front of all following
+arguments.
+
+.SH EXAMPLE
+
+        pgpewrap pgpe file \-\- \-r a b c
+
+will execute:
+
+        pgpe file -r a -r b -r c
+
+This script is needed with PGP 5 and with GPG, since their command
+line interfaces can't be properly served by mutt's format mechanism.
+
diff --git a/upstream/mageia-cauldron/man1/pi1toppm.1 b/upstream/mageia-cauldron/man1/pi1toppm.1
new file mode 100644
index 00000000..be04e1d7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pi1toppm.1
@@ -0,0 +1,62 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pi1toppm User Manual" 0 "19 July 1990" "netpbm documentation"
+
+.SH NAME
+
+pi1toppm - convert an Atari Degas .pi1 into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpi1toppm\fP
+
+[\fIpi1file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpi1toppm\fP reads an Atari Degas .pi1 file as input and
+produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpi1toppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtopi1" (1)\c
+\&,
+.BR "pc1toppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pi3topbm" (1)\c
+\&,
+.BR "pbmtopi3" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pi1toppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pi3topbm.1 b/upstream/mageia-cauldron/man1/pi3topbm.1
new file mode 100644
index 00000000..0c81b250
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pi3topbm.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pi3topbm User Manual" 0 "11 March 1990" "netpbm documentation"
+
+.SH NAME
+
+pi3topbm - convert an Atari Degas .pi3 file into a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpi3topbm\fP
+
+[\fIpi3file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpi3topbm\fP reads an Atari Degas .pi3 file as input and
+produces a PBM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpi3topbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtopi3" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pi1toppm" (1)\c
+\&,
+.BR "ppmtopi1" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1988 by David Beckemeyer (bdt!david) and Diomidis D. Spinellis.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pi3topbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pic.1 b/upstream/mageia-cauldron/man1/pic.1
new file mode 100644
index 00000000..9a97b4c0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pic.1
@@ -0,0 +1,1336 @@
+.TH PIC 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+pic \- compile pictures for troff or TeX
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr pic_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.ie t \{\
+.  ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.  ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(tx
+.\}
+.el \{\
+.  ds tx TeX
+.  ds lx LaTeX
+.\}
+.
+.ie \n(.g .ds ic \/
+.el       .ds ic \^
+.
+.\" The BSD man macros can't handle " in arguments to font change macros,
+.\" so use \(ts instead of ".
+.tr \(ts"\""
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY pic
+.OP \-nvCSU
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY pic
+.B \-t
+.OP \-cvzCSU
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This manual page describes the GNU version of
+.BR pic ,
+which is part of the groff document formatting system.
+.
+.B pic
+compiles descriptions of pictures embedded within
+.B troff
+or \*(tx input files into commands that are understood by \*(tx or
+.BR troff .
+.
+Each picture starts with a line beginning with
+.B .PS
+and ends with a line beginning with
+.BR .PE .
+.
+Anything outside of
+.B .PS
+and
+.B .PE
+is passed through without change.
+.
+.
+.LP
+It is the user's responsibility to provide appropriate definitions
+of the
+.B PS
+and
+.B PE
+macros.
+.
+When the macro package being used does not supply such definitions
+(for example, old versions of \-ms), appropriate definitions can be
+obtained with
+.BR \-mpic :
+.
+These will center each picture.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Options that do not take arguments may be grouped behind a single
+.BR \- .
+.
+The special option
+.B \-\^\-
+can be used to mark the end of the options.
+.
+A filename of
+.B \-
+refers to the standard input.
+.
+.TP
+.B \-C
+Recognize
+.B .PS
+and
+.B .PE
+even when followed by a character other than space or newline.
+.
+.TP
+.B \-S
+Safer mode; do not execute
+.B sh
+commands.
+.
+This can be useful when operating on untrustworthy input (enabled by
+default).
+.
+.TP
+.B \-U
+Unsafe mode; revert the default option
+.BR \-S .
+.
+.TP
+.B \-n
+Don't use the groff extensions to the troff drawing commands.
+.
+You should use this if you are using a postprocessor that doesn't
+support these extensions.
+.
+The extensions are described in
+.BR groff_out (5).
+.
+The
+.B \-n
+option also causes
+.B pic
+not to use zero-length lines to draw dots in troff mode.
+.
+.TP
+.B \-t
+\*(tx mode.
+.
+.TP
+.B \-c
+Be more compatible with
+.BR tpic .
+.
+Implies
+.BR \-t .
+Lines beginning with
+.B \e
+are not passed through transparently.
+.
+Lines beginning with
+.B .
+are passed through with the initial
+.B .
+changed to
+.BR \e .
+.
+A line beginning with
+.B .ps
+is given special treatment:
+it takes an optional integer argument specifying
+the line thickness (pen size) in milliinches;
+a missing argument restores the previous line thickness;
+the default line thickness is 8 milliinches.
+.
+The line thickness thus specified takes effect only when a
+non-negative line thickness has not been specified by use of the
+.B thickness
+attribute or by setting the
+.B linethick
+variable.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.B \-z
+In \*(tx mode draw dots using zero-length lines.
+.
+.
+.LP
+The following options supported by other versions of
+.B pic
+are ignored:
+.
+.TP
+.B \-D
+Draw all lines using the \eD escape sequence.
+.B pic
+always does this.
+.
+.TP
+.BI \-T \ dev
+Generate output for the
+.B troff
+device
+.IR dev .
+.
+This is unnecessary because the
+.B troff
+output generated by
+.B pic
+is device-independent.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+This section describes only the differences between GNU
+.B pic
+and the original version of
+.BR pic .
+.
+Many of these differences also apply to newer versions of Unix
+.BR pic .
+.
+A complete documentation is available in the file
+.
+.
+.LP
+.RS
+.I /usr/\:share/\:doc/\:groff\-1.22.4/pic.ms
+.RE
+.
+.
+.\" ====================================================================
+.SS \*(tx mode
+.\" ====================================================================
+.
+\*(tx mode is enabled by the
+.B \-t
+option.
+.
+In \*(tx mode,
+.B pic
+will define a vbox called
+.B \egraph
+for each picture.
+.
+Use the
+.B figname
+command to change the name of the vbox.
+.
+You must yourself print that vbox using, for example, the command
+.
+.
+.RS
+.LP
+.B
+\ecenterline{\ebox\egraph}
+.RE
+.
+.
+.LP
+Actually, since the vbox has a height of zero (it is defined with
+\evtop) this will produce slightly more vertical space above the
+picture than below it;
+.RS
+.LP
+.B
+\ecenterline{\eraise 1em\ebox\egraph}
+.RE
+.LP
+would avoid this.
+.
+.
+.LP
+To make the vbox having a positive height and a depth of zero
+(as used e.g.\& by \*[lx]'s
+.BR \%graphics.sty ),
+define the following macro in your document:
+.RS
+.LP
+.B \edef\egpicbox#1{%
+.br
+.B "   \evbox{\eunvbox\ecsname #1\eendcsname\ekern 0pt}}"
+.RE
+.LP
+Now you can simply say
+.B \egpicbox{graph}
+instead of \ebox\egraph.
+.
+.
+.LP
+You must use a \*(tx driver that supports the
+.B tpic
+specials, version 2.
+.
+.
+.LP
+Lines beginning with
+.B \e
+are passed through transparently; a
+.B %
+is added to the end of the line to avoid unwanted spaces.
+.
+You can safely use this feature to change fonts or to
+change the value of
+.BR \ebaselineskip .
+.
+Anything else may well produce undesirable results; use at your own risk.
+.
+Lines beginning with a period are not given any special treatment.
+.
+.
+.\" ====================================================================
+.SS Commands
+.\" ====================================================================
+.
+.TP
+\fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \
+[\fBby\fR [\fB*\fR]\,\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
+Set
+.I variable
+to
+.IR expr1 .
+.
+While the value of
+.I variable
+is less than or equal to
+.IR expr2 ,
+do
+.I body
+and increment
+.I variable
+by
+.IR expr3 ;
+if
+.B by
+is not given, increment
+.I variable
+by 1.
+.
+If
+.I expr3
+is prefixed by
+.B *
+then
+.I variable
+will instead be multiplied by
+.IR expr3 .
+.
+The value of
+.I expr3
+can be negative for the additive case;
+.I variable
+is then tested whether it is greater than or equal to
+.IR expr2 .
+.
+For the multiplicative case,
+.I expr3
+must be greater than zero.
+.
+If the constraints aren't met, the loop isn't executed.
+.
+.I X
+can be any character not occurring in
+.IR body .
+.
+.TP
+\fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
+[\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR]
+Evaluate
+.IR expr ;
+if it is non-zero then do
+.IR if-true ,
+otherwise do
+.IR if-false .
+.
+.I X
+can be any character not occurring in
+.IR if-true .
+.
+.I Y
+can be any character not occurring in
+.IR if-false .
+.
+.TP
+\fBprint\fR \fIarg\fR\|.\|.\|.
+Concatenate the arguments and print as a line on stderr.
+.
+Each
+.I arg
+must be an expression, a position, or text.
+.
+This is useful for debugging.
+.
+.TP
+\fBcommand\fR \fIarg\fR\|.\|.\|.
+Concatenate the arguments
+and pass them through as a line to troff or \*(tx.
+.
+Each
+.I arg
+must be an expression, a position, or text.
+.
+This has a similar effect to a line beginning with
+.B .\&
+or
+.BR \e ,
+but allows the values of variables to be passed through.
+.
+For example,
+.RS
+.IP
+.ft B
+.nf
+\&.PS
+x = 14
+command ".ds string x is " x "."
+\&.PE
+\e*[string]
+.ft
+.fi
+.RE
+.IP
+prints
+.RS
+.IP
+.B x is 14.
+.RE
+.
+.TP
+\fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
+Pass
+.I command
+to a shell.
+.
+.I X
+can be any character not occurring in
+.IR command .
+.
+.TP
+\fBcopy\fR \fB"\,\fIfilename\/\fB"\fR
+Include
+.I filename
+at this point in the file.
+.
+.TP
+\fBcopy\fR [\fB"\,\fIfilename\/\fB"\fR] \fBthru\fR \fIX\fR \fIbody\fR \fIX\fR \
+[\fBuntil\fR \fB"\,\fIword\*(ic\fB"\fR]
+.ns
+.TP
+\fBcopy\fR [\fB"\,\fIfilename\/\fB"\fR] \fBthru\fR \fImacro\fR \
+[\fBuntil\fR \fB"\,\fIword\*(ic\fB"\fR]
+This construct does
+.I body
+once for each line of
+.IR filename ;
+the line is split into blank-delimited words,
+and occurrences of
+.BI $ i
+in
+.IR body ,
+for
+.I i
+between 1 and 9,
+are replaced by the
+.IR i -th
+word of the line.
+.
+If
+.I filename
+is not given, lines are taken from the current input up to
+.BR .PE .
+.
+If an
+.B until
+clause is specified,
+lines will be read only until a line the first word of which is
+.IR word ;
+that line will then be discarded.
+.
+.I X
+can be any character not occurring in
+.IR body .
+.
+For example,
+.RS
+.IP
+.ft B
+.nf
+\&.PS
+copy thru % circle at ($1,$2) % until "END"
+1 2
+3 4
+5 6
+END
+box
+\&.PE
+.ft
+.fi
+.RE
+.IP
+is equivalent to
+.RS
+.IP
+.ft B
+.nf
+\&.PS
+circle at (1,2)
+circle at (3,4)
+circle at (5,6)
+box
+\&.PE
+.ft
+.fi
+.RE
+.
+.IP
+The commands to be performed for each line can also be taken
+from a macro defined earlier by giving the name of the macro
+as the argument to
+.BR thru .
+.
+.
+.LP
+.B reset
+.br
+.ns
+.TP
+\fBreset\fI variable1\/\fR[\fB,\fR]\fI variable2 .\^.\^.
+Reset pre-defined variables
+.IR variable1 ,
+.I variable2
+\&.\^.\^.\& to their default values.
+.
+If no arguments are given, reset all pre-defined variables to their
+default values.
+.
+Note that assigning a value to
+.B scale
+also causes all pre-defined variables that control dimensions to be
+reset to their default values times the new value of scale.
+.
+.TP
+\fBplot\fR \fIexpr\fR [\fB"\,\fItext\*(ic\fB"\fR]
+This is a text object which is constructed by using
+.I text
+as a format string for sprintf
+with an argument of
+.IR expr .
+.
+If
+.I text
+is omitted a format string of
+.B "\(ts%g\(ts"
+is used.
+.
+Attributes can be specified in the same way as for a normal text
+object.
+Be very careful that you specify an appropriate format string;
+.B pic
+does only very limited checking of the string.
+This is deprecated in favour of
+.BR sprintf .
+.
+.TP
+.IB variable\  := \ expr
+This is similar to
+.B =
+except
+.I variable
+must already be defined,
+and
+.I expr
+will be assigned to
+.I variable
+without creating a variable local to the current block.
+.
+(By contrast,
+.B =
+defines the variable in the current block if it is not already defined
+there, and then changes the value in the current block only.)
+.
+For example, the following:
+.RS
+.IP
+.ft B
+.nf
+\&.PS
+x = 3
+y = 3
+[
+  x := 5
+  y = 5
+]
+print x " " y
+\&.PE
+.ft
+.fi
+.RE
+.IP
+prints
+.RS
+.IP
+.B 5 3
+.RE
+.
+.
+.LP
+Arguments of the form
+.IP
+.I X anything X
+.LP
+are also allowed to be of the form
+.IP
+.BI {\  anything\  }
+.
+.
+.LP
+In this case
+.I anything
+can contain balanced occurrences of
+.B {
+and
+.BR } .
+Strings may contain
+.I X
+or imbalanced occurrences of
+.B {
+and
+.BR } .
+.
+.
+.\" ====================================================================
+.SS Expressions
+.\" ====================================================================
+.
+The syntax for expressions has been significantly extended:
+.
+.
+.LP
+.IB  x\  ^\  y
+(exponentiation)
+.br
+.BI sin( x )
+.br
+.BI cos( x )
+.br
+.BI atan2( y , \ x )
+.br
+.BI log( x )
+(base 10)
+.br
+.BI exp( x )
+(base 10, i.e.\&
+.ie t 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
+.el   10^\fIx\fR)
+.br
+.BI sqrt( x )
+.br
+.BI int( x )
+.br
+.B rand()
+(return a random number between 0 and 1)
+.br
+.BI rand( x )
+(return a random number between 1 and
+.IR x ;
+deprecated)
+.br
+.BI srand( x )
+(set the random number seed)
+.br
+.BI max( e1 , \ e2 )
+.br
+.BI min( e1 , \ e2 )
+.br
+.BI ! e
+.br
+\fIe1\fB && \fIe2\fR
+.br
+\fIe1\fB || \fIe2\fR
+.br
+\fIe1\fB == \fIe2\fR
+.br
+\fIe1\fB != \fIe2\fR
+.br
+\fIe1\fB >= \fIe2\fR
+.br
+\fIe1\fB > \fIe2\fR
+.br
+\fIe1\fB <= \fIe2\fR
+.br
+\fIe1\fB < \fIe2\fR
+.br
+\fB"\,\fIstr1\*(ic\fB" == "\,\fIstr2\*(ic\fB"\fR
+.br
+\fB"\,\fIstr1\*(ic\fB" != "\,\fIstr2\*(ic\fB"\fR
+.br
+.
+.
+.LP
+String comparison expressions must be parenthesised in some contexts
+to avoid ambiguity.
+.
+.
+.\" ====================================================================
+.SS Other Changes
+.\" ====================================================================
+.
+A bare expression,
+.IR expr ,
+is acceptable as an attribute;
+it is equivalent to
+.IR dir\ expr ,
+where
+.I dir
+is the current direction.
+.
+For example
+.LP
+.RS
+.B line 2i
+.RE
+.LP
+means draw a line 2\ inches long in the current direction.
+.
+The \[oq]i\[cq] (or \[oq]I\[cq]) character is ignored; to use another
+measurement unit, set the
+.I scale
+variable to an appropriate value.
+.
+.
+.LP
+The maximum width and height of the picture are taken from the variables
+.B maxpswid
+and
+.BR maxpsht .
+.
+Initially these have values 8.5 and 11.
+.
+.
+.LP
+Scientific notation is allowed for numbers.
+For example
+.RS
+.LP
+.B
+x = 5e\-2
+.RE
+.
+.
+.LP
+Text attributes can be compounded.
+.
+For example,
+.RS
+.LP
+.B
+"foo" above ljust
+.RE
+.LP
+is valid.
+.
+.
+.LP
+There is no limit to the depth to which blocks can be examined.
+.
+For example,
+.RS
+.LP
+.B
+[A: [B: [C: box ]]] with .A.B.C.sw at 1,2
+.br
+.B
+circle at last [\^].A.B.C
+.RE
+.LP
+is acceptable.
+.
+.
+.LP
+Arcs now have compass points determined by the circle of which the arc
+is a part.
+.
+.
+.LP
+Circles, ellipses, and arcs can be dotted or dashed.
+.
+In \*(tx mode splines can be dotted or dashed also.
+.
+.
+.LP
+Boxes can have rounded corners.
+.
+The
+.B rad
+attribute specifies the radius of the quarter-circles at each corner.
+If no
+.B rad
+or
+.B diam
+attribute is given, a radius of
+.B boxrad
+is used.
+.
+Initially,
+.B boxrad
+has a value of\ 0.
+.
+A box with rounded corners can be dotted or dashed.
+.
+.
+.LP
+Boxes can have slanted sides.
+.
+This effectively changes the shape of a box from a rectangle to an
+arbitrary parallelogram.
+.
+The
+.B xslanted
+and
+.B yslanted
+attributes specify the x and y\~offset of the box's upper right
+corner from its default position.
+.
+.
+.LP
+The
+.B .PS
+line can have a second argument specifying a maximum height for
+the picture.
+.
+If the width of zero is specified the width will be ignored in computing
+the scaling factor for the picture.
+.
+Note that GNU
+.B pic
+will always scale a picture by the same amount vertically as well as
+horizontally.
+.
+This is different from the DWB
+2.0
+.B pic
+which may scale a picture by a different amount vertically than
+horizontally if a height is specified.
+.
+.
+.LP
+Each text object has an invisible box associated with it.
+.
+The compass points of a text object are determined by this box.
+.
+The implicit motion associated with the object is also determined
+by this box.
+.
+The dimensions of this box are taken from the width and height attributes;
+if the width attribute is not supplied then the width will be taken to be
+.BR textwid ;
+if the height attribute is not supplied then the height will be taken to be
+the number of text strings associated with the object
+times
+.BR textht .
+.
+Initially
+.B textwid
+and
+.B textht
+have a value of 0.
+.
+.
+.LP
+In (almost all) places where a quoted text string can be used,
+an expression of the form
+.IP
+.BI sprintf(\(ts format \(ts,\  arg ,\fR.\|.\|.\fB)
+.LP
+can also be used;
+this will produce the arguments formatted according to
+.IR format ,
+which should be a string as described in
+.BR printf (3)
+appropriate for the number of arguments supplied.
+.
+.
+.LP
+The thickness of the lines used to draw objects is controlled by the
+.B linethick
+variable.
+.
+This gives the thickness of lines in points.
+.
+A negative value means use the default thickness:
+in \*(tx output mode, this means use a thickness of 8 milliinches;
+in \*(tx output mode with the
+.B \-c
+option, this means use the line thickness specified by
+.B .ps
+lines;
+in troff output mode, this means use a thickness proportional
+to the pointsize.
+.
+A zero value means draw the thinnest possible line supported by
+the output device.
+.
+Initially it has a value of \-1.
+.
+There is also a
+.BR thick [ ness ]
+attribute.
+.
+For example,
+.RS
+.LP
+.B circle thickness 1.5
+.RE
+.LP
+would draw a circle using a line with a thickness of 1.5 points.
+.
+The thickness of lines is not affected by the
+value of the
+.B scale
+variable, nor by the width or height given in the
+.B .PS
+line.
+.
+.
+.LP
+Boxes (including boxes with rounded corners or slanted sides),
+circles and ellipses can be filled by giving them an attribute of
+.BR fill [ ed ].
+.
+This takes an optional argument of an expression with a value between
+0 and 1; 0 will fill it with white, 1 with black, values in between
+with a proportionally gray shade.
+.
+A value greater than 1 can also be used:
+this means fill with the
+shade of gray that is currently being used for text and lines.
+.
+Normally this will be black, but output devices may provide
+a mechanism for changing this.
+.
+Without an argument, then the value of the variable
+.B fillval
+will be used.
+.
+Initially this has a value of 0.5.
+.
+The invisible attribute does not affect the filling of objects.
+.
+Any text associated with a filled object will be added after the
+object has been filled, so that the text will not be obscured
+by the filling.
+.
+.
+.LP
+Three additional modifiers are available to specify colored objects:
+.BR outline [ d ]
+sets the color of the outline,
+.B shaded
+the fill color, and
+.B colo\fR[\fPu\fR]\fPr\fR[\fPed\fR]
+sets both.
+.
+All three keywords expect a suffix specifying the color, for example
+.RS
+.LP
+.B circle shaded """green""" outline """black"""
+.RE
+.
+.
+.LP
+Currently, color support isn't available in \*(tx mode.
+.
+Predefined color names for
+.B groff
+are in the device macro files, for example
+.BR ps.tmac ;
+additional colors can be defined with the
+.B .defcolor
+request (see the manual page of
+.BR troff (1)
+for more details).
+.
+.
+.LP
+To change the name of the vbox in \*(tx mode, set the pseudo-variable
+.B figname
+(which is actually a specially parsed command) within a picture.
+.
+Example:
+.RS
+.LP
+.B .PS
+.br
+.B figname = foobar;
+.br
+.B ...
+.br
+.B .PE
+.RE
+.
+.
+.LP
+The picture is then available in the box
+.BR \efoobar .
+.
+.
+.LP
+.B pic
+assumes that at the beginning of a picture both glyph and fill color are
+set to the default value.
+.
+.
+.LP
+Arrow heads will be drawn as solid triangles if the variable
+.B arrowhead
+is non-zero and either \*(tx mode is enabled or the
+.B \-n
+option has not been given.
+.
+Initially
+.B arrowhead
+has a value of\ 1.
+.
+Note that solid arrow heads are always filled with the current outline
+color.
+.
+.
+.LP
+The troff output of
+.B pic
+is device-independent.
+.
+The
+.B \-T
+option is therefore redundant.
+.
+All numbers are taken to be in inches; numbers are never interpreted
+to be in troff machine units.
+.
+.
+.LP
+Objects can have an
+.B aligned
+attribute.
+.
+This will only work if the postprocessor is
+.BR grops ,
+or
+.BR gropdf .
+.
+Any text associated with an object having the
+.B aligned
+attribute will be rotated about the center of the object
+so that it is aligned in the direction from the start point
+to the end point of the object.
+.
+Note that this attribute will have no effect for objects whose start
+and end points are coincident.
+.
+.
+.LP
+In places where
+.IB n th
+is allowed
+.BI \[oq] expr \[cq]th
+is also allowed.
+.
+Note that
+.B \[cq]th
+is a single token: no space is allowed between the
+.B \[cq]
+and the
+.BR th .
+.
+For example,
+.IP
+.ft B
+.nf
+for i = 1 to 4 do {
+   line from \[oq]i\[cq]th box.nw to \[oq]i+1\[cq]th box.se
+}
+.ft
+.fi
+.
+.
+.\" ====================================================================
+.SH CONVERSION
+.\" ====================================================================
+.
+To obtain a stand-alone picture from a
+.B pic
+file, enclose your
+.B pic
+code with
+.B .PS
+and
+.B .PE
+requests;
+.B roff
+configuration commands may be added at the beginning of the file, but no
+.B roff
+text.
+.
+.
+.LP
+It is necessary to feed this file into
+.B groff
+without adding any page information, so you must check which
+.B .PS
+and
+.B .PE
+requests are actually called.
+.
+For example, the mm macro package adds a page number, which is very
+annoying.
+.
+At the moment, calling standard
+.B groff
+without any macro package works.
+.
+Alternatively, you can define your own requests, e.g.\& to do nothing:
+.LP
+.RS
+.nf
+.ft B
+\&.de PS
+\&..
+\&.de PE
+\&..
+.ft
+.fi
+.RE
+.
+.
+.LP
+.B groff
+itself does not provide direct conversion into other graphics file
+formats.
+.
+But there are lots of possibilities if you first transform your
+picture into PostScript\*R format using the
+.B groff
+option
+.BR \-Tps .
+.
+Since this
+.IR ps -file
+lacks BoundingBox information it is not very useful by itself, but it
+may be fed into other conversion programs, usually named
+.BI ps2 other
+or
+.BI psto other
+or the like.
+.
+Moreover, the PostScript interpreter
+.B ghostscript
+.RB ( gs )
+has built-in graphics conversion devices that are called with the option
+.LP
+.RS
+.BI "gs \-sDEVICE=" <devname>
+.RE
+.LP
+Call
+.LP
+.RS
+.B gs \-\-help
+.RE
+.LP
+for a list of the available devices.
+.
+.
+.LP
+An alternative may be to use the
+.B \-Tpdf
+option to convert your picture directly into
+.B PDF
+format.
+.
+The MediaBox of the file produced can be controlled by passing a
+.B \-P\-p
+papersize to groff.
+.
+.
+.LP
+As the Encapsulated PostScript File Format
+.B EPS
+is getting more and more important, and the conversion wasn't
+regarded trivial in the past you might be interested to know that
+there is a conversion tool named
+.B ps2eps
+which does the right job.
+.
+It is much better than the tool
+.B ps2epsi
+packaged with
+.BR gs .
+.
+.
+.LP
+For bitmapped graphic formats, you should use
+.BR pstopnm ;
+the resulting (intermediate)
+.B PNM
+file can be then converted to virtually any graphics format using the
+tools of the
+.B netpbm
+package.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/pic.tmac
+Example definitions of the
+.B PS
+and
+.B PE
+macros.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR troff (1),
+.BR groff_out (5),
+.BR tex (1),
+.BR gs (1),
+.BR ps2eps (1),
+.BR pstopnm (1),
+.BR ps2epsi (1),
+.BR pnm (5)
+.
+.
+.LP
+Eric S.\& Raymond,
+.I Making Pictures With GNU PIC.
+.br
+.I /usr/\:share/\:doc/\:groff\-1.22.4/pic.ps
+(this file, together with its source file, pic.ms, is part
+of the groff documentation)
+.
+.
+.LP
+Tpic: Pic for \*(tx
+.LP
+Brian W.\& Kernighan,
+.UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
+.I PIC \(em A Graphics Language for Typesetting (User Manual)
+.UE .
+AT&T Bell Laboratories, Computing Science Technical Report No.\ 116
+(revised May, 1991).
+.
+.
+.LP
+.B ps2eps
+is available from CTAN mirrors, e.g.\&
+.UR ftp://\:ftp.dante.de/\:tex\-archive/\:support/\:ps2eps/
+.UE
+.
+.
+.LP
+W.\& Richard Stevens,
+.UR http://\:www.kohala.com/\:start/\:troff/\:pic2html.html
+.I Turning PIC into HTML
+.UE
+.
+.
+.LP
+W.\& Richard Stevens,
+.UR http://\:www.kohala.com/\:start/\:troff/\:pic.examples.ps
+.IR "Examples of " pic " Macros"
+.UE
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+Input characters that are invalid for
+.B groff
+(i.e., those with ASCII code 0,
+or 013 octal, or between 015 and 037 octal, or between 0200 and 0237
+octal) are rejected even in \*(tx mode.
+.
+.
+.LP
+The interpretation of
+.B fillval
+is incompatible with the pic in 10th edition Unix,
+which interprets 0 as black and 1 as white.
+.
+.
+.LP
+PostScript\*R is a registered trademark of Adobe Systems Incorporation.
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[pic_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/pico.1 b/upstream/mageia-cauldron/man1/pico.1
new file mode 100644
index 00000000..e87a68ec
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pico.1
@@ -0,0 +1,258 @@
+.TH pico 1 "Version 5.09"
+.SH Name
+pico \- simple text editor in the style of the Alpine Composer
+.SH Syntax
+.B pico
+[
+.I options
+] [
+.I file
+]
+.SH Description
+\fIPico\fR is a simple, display-oriented text editor based on
+the Alpine message system composer.  As with Alpine, commands are 
+displayed at the bottom of the screen, and context-sensitive
+help is provided.  As characters are typed they are immediately 
+inserted into the text.
+.PP
+Editing commands are entered using control-key
+combinations.  As a work-around for communications programs that
+swallow certain control characters, you can emulate a control key
+by pressing ESCAPE twice, followed by the desired control character,
+e.g. "ESC ESC c" would be equivalent to entering a ctrl-c.
+The editor has five basic features: paragraph justification,
+searching, block cut/paste, a spelling checker, and a file browser.
+.PP
+Paragraph justification (or filling) takes place in the paragraph that
+contains the cursor, or, if the cursor is between lines, in the paragraph
+immediately below.  Paragraphs are delimited by blank lines, or by lines
+beginning with a space or tab.  Unjustification can be done immediately
+after justification using the control-U key combination. 
+.PP
+String searches are not sensitive to case.  A search begins at the current
+cursor position and wraps around the end of the text.  The most recent   
+search string is offered as the default in subsequent searches.
+.PP
+Blocks of text can be moved, copied or deleted with creative use of the
+command for mark (ctrl-^), delete (ctrl-k) and undelete (ctrl-u).
+The delete command will remove text between the "mark" and the current 
+cursor position, and place it in the "cut" buffer.  The undelete command
+effects a "paste" at the current cursor position.
+.PP
+The spell checker examines all words in the text.  It then offers, in 
+turn, each misspelled word for correction while 
+highlighting it in the text.  Spell checking can be cancelled at any time.  
+Alternatively, \fIpico\fR will substitute for the default spell checking 
+routine a routine defined by the SPELL environment variable.  The replacement 
+routine should read standard input and write standard output.
+.PP
+The file browser is offered as an option in the "Read File" and "Write Out"
+command prompts.  It is intended to help in searching for specific files 
+and navigating directory hierarchies.  Filenames with sizes and names of 
+directories in the current working directory are presented for selection.
+The current working directory is displayed on the top line of the display 
+while the list of available commands takes up the bottom two.  Several 
+basic file manipulation functions are supported:  file renaming, copying, 
+and deletion.
+.PP
+More specific help is available in \fIpico\fR's online help.
+.SH Options
+.IP \fB+\fIn\fB\fR
+Causes \fIpico\fR to be started with the cursor located \fIn\fR lines 
+into the file. (Note: no space between "+" sign and number)
+.IP \fB-a\fR
+Display all files including those beginning with a period (.).
+.IP \fB-b\fR
+Enable the option to Replace text matches found using the
+"Where is" command. This now does nothing. Instead, the option is
+always turned on (as if the -b flag had been specified).
+.IP \fB-d\fR
+Rebind the "delete" key so the character the cursor is on is rubbed out
+rather than the character to its left.
+.IP \fB-e\fR
+Enable file name completion.
+.IP \fB-f\fR
+Use function keys for commands.  This option supported only in 
+conjunction with UW Enhanced NCSA telnet.
+.IP \fB-h\fR
+List valid command line options.
+.IP \fB-j\fR
+Enable "Goto" command in the file browser.  This enables the command to
+permit explicitly telling \fIpilot\fR which directory to visit.
+.IP \fB-g\fR
+Enable "Show Cursor" mode in file browser.  Cause cursor to be positioned
+before the current selection rather than placed at the lower left of the
+display.
+.IP \fB-k\fR
+Causes "Cut Text" command to remove characters from the cursor position
+to the end of the line rather than remove the entire line.
+.IP \fB-m\fR
+Enable mouse functionality.  This only works when \fIpico\fR is run from
+within an X Window System "xterm" window.
+.IP \fB-n\fIn\fB\fR
+The \-n\fIn\fR option enables new mail notification.  The \fIn\fR 
+argument is optional, and specifies how often, in seconds, your 
+mailbox is checked for new mail.  For example, \-n60 causes \fIpico\fR 
+to check for new mail once every minute.  The default interval is 180 
+seconds, while the minimum allowed is 30. (Note: no space between "n" and 
+the number) 
+.IP \fB-o\ \fIdir\fB\fR
+Sets operating directory.  Only files within this directory are accessible.
+Likewise, the file browser is limited to the specified directory subtree.
+.IP \fB-r\fIn\fB\fR
+Sets column used to limit the "Justify" command's right margin
+.IP \fB-s\ \fIspeller\fR
+Specify an alternate program
+.I spell
+to use when spell checking.
+.IP \fB-t\fR
+Enable "tool" mode.  Intended for when \fIpico\fR is used as the
+editor within other tools (e.g., Elm, Pnews).  \fIPico\fR will not prompt
+for save on exit, and will not rename the buffer during the "Write Out"
+command.
+.IP \fB-v\fR
+View the file only, disallowing any editing.
+.IP \fB-version\fR
+Print Pico version and exit.
+.IP \fB-w\fR
+Disable word wrap (thus allow editing of long lines).
+.IP \fB-x\fR
+Disable keymenu at the bottom of the screen.
+.IP \fB-z\fR
+Enable ^Z suspension of \fIpico\fR.
+.IP \fB-p\fR
+Preserve the "start" and "stop" characters, typically Ctrl-Q and Ctrl-S,
+which are sometimes used in communications paths to control data flow
+between devices that operate at different speeds.
+.IP \fB-Q\ \fIquotestr\fB\fR
+Set the quote string.  Especially useful when composing email, setting this 
+allows the quote string to be checked for when Justifying paragraphs.
+A common quote string is "> ".
+.IP \fB-W\ \fIword_separators\fB\fR
+If characters listed here appear in the middle of a word surrounded by
+alphanumeric characters that word is split into two words. This is used by
+the Forward and Backward word commands and by the spell checker.
+.IP \fB-q\fR
+Termcap or terminfo definition for input escape sequences are used in
+preference to sequences defined by default.  This option is only available
+if \fIpico\fR was compiled with the TERMCAP_WINS define turned on.
+.IP \fB-setlocale_ctype\fR
+Do setlocale(LC_CTYPE) if available. Default is to not do this setlocale.
+.IP \fB-no_setlocale_collate\fR
+Do not do setlocale(LC_COLLATE). Default is to do this setlocale.
+.PP
+Lastly, when a running \fIpico\fR is disconnected (i.e., receives a 
+SIGHUP), \fIpico\fR will save the current work if needed before exiting.
+Work is saved under the current filename with ".save" appended.
+If the current work is unnamed, it is saved under the filename "pico.save".
+.PP
+.SH Color Support
+If your terminal supports colors, Pico can be configured to color
+text. Users can configure the color of the text, the text in the key menu,
+the titlebar, messages and prompt in the status line. As an added feature
+Pico can also be used to configure the color of up to three different
+levels of quoted text, and the signature of an email message. This is 
+useful when Pico is used as a tool (with the -t command line switch.)
+.PP
+Pico can tell you the number of colors that your terminal supports, when
+started with the switch -color_codes. In addition Pico will print a table
+showing the numerical code of every color supported in that terminal. In order
+to configure colors, one must use these numerical codes. For example, 0 is
+for black, so in order to configure a black color, one must use its code, the
+number 0.
+.PP
+In order to activate colors, one must use the option -ncolors with a numerical
+value indicating the number of colors that your terminal supports, for example,
+\fI-ncolors 256\fR indicates that the user wishes to use a table of 256 colors.
+.PP
+All options that control color, are four letter options. Their last two 
+letters are either "fc" or "bc", indicating \fIforeground color\fR and 
+\fIbacground color\fR, respectively. The first two letters indicate the 
+type of text that is being configured, for example "nt" stands for 
+\fInormal text\fR, so that -ntfc represents the color of the normal text,
+while -ntbc represents the color of the background of normal text. Here
+is a complete list of the color options supported by Pico.
+.IP \fB-color_code\fR
+displays the number of colors supported by the terminal, and a 
+table showing the association of colors and numerical codes
+.IP \fB-ncolors\fB\ \fInumber\fR
+activates color support in Pico, and tells Pico how many colors to use.
+Depending on your terminal \fInumber\fR could be 8, 16, or 256.
+.IP \fB-ntfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color to be used to color normal text.
+.IP \fB-ntbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background for normal text.
+.IP \fB-rtfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of reverse text. Default: same
+as background color of normal text (if specified.)
+.IP \fB-rtbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of
+reverse text. Default: same as color of normal text (if specified.)
+.IP \fB-tbfc\fB\ \fInum\fR
+specifies the number \fInum\fR of then color of text of the title bar.
+Default: same as foreground color of reverse text.
+.IP \fB-tbbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color in the background of the title bar.
+.IP \fB-klfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the text of the key label.
+.IP \fB-klbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color in the background of the key label.
+.IP \fB-knfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the text of the key name.
+.IP \fB-knbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of the key name.
+.IP \fB-stfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the text of the status line.
+.IP \fB-stbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of the status line.
+.IP \fB-prfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the text of a prompt.
+.IP \fB-prbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of a prompt.
+.IP \fB-q1fc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the text of level one of quoted text.
+.IP \fB-q1bc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of level one of quoted text. If the option
+-q1bc is used, the default value of this option is the background color
+or normal text.
+.IP \fB-q2fc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of text of level two of quoted text.
+.IP \fB-q2bc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of level two of quoted text. If the option
+-q1bc is used, the default value of this option is the background color
+or normal text.
+.IP \fB-q3fc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of text of level three of quoted text.
+.IP \fB-sbfc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of text of signature block text.
+.IP \fB-sbbc\fB\ \fInum\fR
+specifies the number \fInum\fR of the color of the background of signature
+block text.
+.PP
+.SH Bugs
+The manner in which lines longer than the display width are dealt
+is not immediately obvious.  Lines that continue beyond the edge
+of the display are indicated by a '$' character at the end
+of the line.  Long lines are scrolled horizontally as the cursor 
+moves through them.
+.SH Files
+.ta 1.75i
+.nf
+pico.save	Unnamed interrupted work saved here.
+*.save	Interrupted work on a named file is saved here.
+.fi
+.SH Authors
+Michael Seibel <mikes@cac.washington.edu>
+.br
+Laurence Lundblade <lgl@cac.washington.edu>
+.br
+Pico was originally derived from MicroEmacs 3.6, by Dave G. Conroy.
+.br
+Copyright 1989-2008 by the University of Washington.
+.SH "See Also"
+alpine(1)
+.br
+Source distribution (part of the Alpine Message System):
+
+.nf
+$Date: 2009-02-02 13:54:23 -0600 (Mon, 02 Feb 2009) $
diff --git a/upstream/mageia-cauldron/man1/piconv.1 b/upstream/mageia-cauldron/man1/piconv.1
new file mode 100644
index 00000000..e0160cc7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/piconv.1
@@ -0,0 +1,167 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PICONV 1"
+.TH PICONV 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+piconv \-\- iconv(1), reinvented in perl
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 6
+\&  piconv [\-f from_encoding] [\-t to_encoding]
+\&         [\-p|\-\-perlqq|\-\-htmlcref|\-\-xmlcref] [\-C N|\-c] [\-D] [\-S scheme]
+\&         [\-s string|file...]
+\&  piconv \-l
+\&  piconv \-r encoding_alias
+\&  piconv \-h
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpiconv\fR is perl version of \fBiconv\fR, a character encoding converter
+widely available for various Unixen today.  This script was primarily
+a technology demonstrator for Perl 5.8.0, but you can use piconv in the
+place of iconv for virtually any case.
+.PP
+piconv converts the character encoding of either STDIN or files
+specified in the argument and prints out to STDOUT.
+.PP
+Here is the list of options.  Some options can be in short format (\-f)
+or long (\-\-from) one.
+.IP "\-f,\-\-from \fIfrom_encoding\fR" 4
+.IX Item "-f,--from from_encoding"
+Specifies the encoding you are converting from.  Unlike \fBiconv\fR,
+this option can be omitted.  In such cases, the current locale is used.
+.IP "\-t,\-\-to \fIto_encoding\fR" 4
+.IX Item "-t,--to to_encoding"
+Specifies the encoding you are converting to.  Unlike \fBiconv\fR,
+this option can be omitted.  In such cases, the current locale is used.
+.Sp
+Therefore, when both \-f and \-t are omitted, \fBpiconv\fR just acts
+like \fBcat\fR.
+.IP "\-s,\-\-string \fIstring\fR" 4
+.IX Item "-s,--string string"
+uses \fIstring\fR instead of file for the source of text.
+.IP \-l,\-\-list 4
+.IX Item "-l,--list"
+Lists all available encodings, one per line, in case-insensitive
+order.  Note that only the canonical names are listed; many aliases
+exist.  For example, the names are case-insensitive, and many standard
+and common aliases work, such as "latin1" for "ISO\-8859\-1", or "ibm850"
+instead of "cp850", or "winlatin1" for "cp1252".  See Encode::Supported
+for a full discussion.
+.IP "\-r,\-\-resolve \fIencoding_alias\fR" 4
+.IX Item "-r,--resolve encoding_alias"
+Resolve \fIencoding_alias\fR to Encode canonical encoding name.
+.IP "\-C,\-\-check \fIN\fR" 4
+.IX Item "-C,--check N"
+Check the validity of the stream if \fIN\fR = 1.  When \fIN\fR = \-1, something
+interesting happens when it encounters an invalid character.
+.IP \-c 4
+.IX Item "-c"
+Same as \f(CW\*(C`\-C 1\*(C'\fR.
+.IP \-p,\-\-perlqq 4
+.IX Item "-p,--perlqq"
+Transliterate characters missing in encoding to \ex{HHHH} where HHHH is the
+hexadecimal Unicode code point.
+.IP \-\-htmlcref 4
+.IX Item "--htmlcref"
+Transliterate characters missing in encoding to &#NNN; where NNN is the
+decimal Unicode code point.
+.IP \-\-xmlcref 4
+.IX Item "--xmlcref"
+Transliterate characters missing in encoding to &#xHHHH; where HHHH is the
+hexadecimal Unicode code point.
+.IP \-h,\-\-help 4
+.IX Item "-h,--help"
+Show usage.
+.IP \-D,\-\-debug 4
+.IX Item "-D,--debug"
+Invokes debugging mode.  Primarily for Encode hackers.
+.IP "\-S,\-\-scheme \fIscheme\fR" 4
+.IX Item "-S,--scheme scheme"
+Selects which scheme is to be used for conversion.  Available schemes
+are as follows:
+.RS 4
+.IP from_to 4
+.IX Item "from_to"
+Uses Encode::from_to for conversion.  This is the default.
+.IP decode_encode 4
+.IX Item "decode_encode"
+Input strings are \fBdecode()\fRd then \fBencode()\fRd.  A straight two-step
+implementation.
+.IP perlio 4
+.IX Item "perlio"
+The new perlIO layer is used.  NI\-S' favorite.
+.Sp
+You should use this option if you are using UTF\-16 and others which
+linefeed is not $/.
+.RE
+.RS 4
+.Sp
+Like the \fI\-D\fR option, this is also for Encode hackers.
+.RE
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBiconv\fR\|(1)
+\&\fBlocale\fR\|(3)
+Encode
+Encode::Supported
+Encode::Alias
+PerlIO
diff --git a/upstream/mageia-cauldron/man1/pidstat.1 b/upstream/mageia-cauldron/man1/pidstat.1
new file mode 100644
index 00000000..7bcd6247
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pidstat.1
@@ -0,0 +1,450 @@
+.\" pidstat manual page - (C) 2007-2020 Sebastien Godard (sysstat <at> orange.fr)
+.TH PIDSTAT 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+pidstat \- Report statistics for Linux tasks.
+
+.SH SYNOPSIS
+.B pidstat [ -d ] [ -H ] [ -h ] [ -I ] [ -l ] [ -R ] [ -r ] [ -s ] [ -t ] [ -U [
+.IB "username " "] ] [ -u ] [ -V ] [ -v ] [ -w ] [ -C " "comm " "] [ -G " "process_name"
+.BI "] [ --dec={ 0 | 1 | 2 } ] [ --human ] [ -p { " "pid" "[,...]"
+.B | SELF | ALL } ] [ -T { TASK | CHILD | ALL } ] [
+.IB "interval " "[ " "count " "] ] [ -e " "program"
+.IB "args " "]"
+
+.SH DESCRIPTION
+.RB "The " "pidstat"
+command is used for monitoring individual tasks currently being managed
+by the Linux kernel.
+It writes to standard output activities for every task selected with option
+.B -p
+or for every task managed by the Linux kernel if option
+.B -p ALL
+has been used. Not selecting any tasks is equivalent to specifying
+.B -p ALL
+but only active tasks (tasks with non-zero statistics values)
+will appear in the report.
+.PP
+.RB "The " "pidstat"
+command can also be used for monitoring the child processes of selected tasks.
+Read about option
+.BR "-T " "below."
+.PP
+.RI "The " "interval"
+parameter specifies the amount of time in seconds between each report.
+A value of 0 (or no parameters at all) indicates that tasks statistics are
+to be reported for the time since system startup (boot). The
+.IR "count " "parameter can be specified in conjunction with the"
+.IR "interval " "parameter if this one is not set to zero. The value of"
+.IR "count " "determines the number of reports generated at"
+.IR "interval " "seconds apart. If the " "interval " "parameter is specified without the " "count"
+parameter, the
+.B pidstat
+command generates reports continuously.
+.PP
+You can select information about specific task activities using flags.
+Not specifying any flags selects only CPU activity.
+
+.SH OPTIONS
+.TP
+.BI "-C " "comm"
+Display only tasks whose command name includes the string
+.IR "comm" ". This string can be a regular expression."
+.TP
+.B -d
+Report I/O statistics (kernels 2.6.20 and later only).
+The following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP kB_rd/s
+Number of kilobytes the task has caused to be read from disk per second.
+.IP kB_wr/s
+Number of kilobytes the task has caused, or shall cause to be
+written to disk per second.
+.IP kB_ccwr/s
+Number of kilobytes whose writing to disk has been cancelled by
+the task. This may occur when the task truncates some
+dirty pagecache. In this case, some IO which another task has
+been accounted for will not be happening.
+.IP iodelay
+Block I/O delay of the task being monitored,
+measured in clock ticks. This metric includes the delays spent
+waiting for sync block I/O completion and for swapin block I/O
+completion.
+.IP Command
+The command name of the task.
+.RE
+.TP
+.B --dec={ 0 | 1 | 2 }
+Specify the number of decimal places to use (0 to 2, default value is 2).
+.TP
+.BI "-e " "program args"
+Execute
+.I program
+with given arguments
+.I args
+and monitor it with
+.BR "pidstat" "."
+.BR "pidstat " "stops when"
+.IR "program " "terminates."
+.TP
+.BI "-G " "process_name"
+Display only processes whose command name includes the string
+.IR "process_name" "."
+This string can be a regular expression. If option
+.BR "-t " "is used together with option " "-G"
+then the threads belonging to that process are also displayed
+(even if their command name doesn't include the string
+.IR "process_name" ")."
+.TP
+.B -H
+Display timestamp in seconds since the epoch.
+.TP
+.B -h
+Display all activities horizontally on a single line, with no
+average statistics at the end of the report. This is
+intended to make it easier to be parsed by other programs.
+.TP
+.B --human
+Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
+The units displayed with this option supersede any other default units (e.g.
+kilobytes, sectors...) associated with the metrics.
+.TP
+.B -I
+In an SMP environment, indicate that tasks CPU usage
+.RB "(as displayed by option " "-u" ")"
+should be divided by the total number of processors.
+.TP
+.B -l
+Display the process command name and all its arguments.
+.TP
+.BI "-p { " "pid" "[,...] | SELF | ALL }"
+Select tasks (processes) for which statistics are to be reported.
+.I pid
+is the process identification number. The
+.B SELF
+keyword indicates that statistics are to be reported for the
+.BR "pidstat " "process itself, whereas the " "ALL"
+keyword indicates that statistics are to be reported for all the
+tasks managed by the system.
+.TP
+.B -R
+Report realtime priority and scheduling policy information.
+The following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP prio
+The realtime priority of the task being monitored.
+.IP policy
+The scheduling policy of the task being monitored.
+.IP Command
+The command name of the task.
+.RE
+.TP
+.B -r
+Report page faults and memory utilization.
+
+When reporting statistics for individual tasks,
+the following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP minflt/s
+Total number of minor faults the task has made per second, those
+which have not required loading a memory page from disk.
+.IP majflt/s
+Total number of major faults the task has made per second, those
+which have required loading a memory page from disk.
+.IP VSZ
+Virtual Size: The virtual memory usage of entire task in kilobytes.
+.IP RSS
+Resident Set Size: The non-swapped physical memory
+used by the task in kilobytes.
+.IP %MEM
+The tasks's currently used share of available physical memory.
+.IP Command
+The command name of the task.
+.RE
+.IP
+When reporting global statistics for tasks and all their children,
+the following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task which is being monitored
+together with its children.
+.IP USER
+The name of the real user owning the task which is being monitored
+together with its children.
+.IP PID
+The identification number of the task which is being monitored
+together with its children.
+.IP minflt-nr
+Total number of minor faults made by the task and all its children,
+and collected during the interval of time.
+.IP majflt-nr
+Total number of major faults made by the task and all its children,
+and collected during the interval of time.
+.IP Command
+The command name of the task which is being monitored
+together with its children.
+.RE
+.TP
+.B -s
+Report stack utilization.
+The following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP StkSize
+The amount of memory in kilobytes reserved for the task as stack,
+but not necessarily used.
+.IP StkRef
+The amount of memory in kilobytes used as stack, referenced by the task.
+.IP Command
+The command name of the task.
+.RE
+.TP
+.B -T { TASK | CHILD | ALL }
+This option specifies what has to be monitored by the
+.BR "pidstat " "command. The " "TASK"
+keyword indicates that statistics are to be reported for individual tasks
+(this is the default option) whereas the
+.B CHILD
+keyword indicates that statistics are to be globally reported for the
+selected tasks and all their children. The
+.B ALL
+keyword indicates that statistics are to be reported for
+individual tasks and globally for the selected
+tasks and their children.
+
+Note: Global statistics for tasks and all their children are not available
+for all options of
+.B pidstat.
+Also these statistics are not necessarily relevant to current time interval:
+The statistics of a child process are collected only when it finishes or
+it is killed.
+.TP
+.B -t
+Also display statistics for threads associated with selected tasks.
+
+This option adds the following values to the reports:
+.RS
+.IP TGID
+The identification number of the thread group leader.
+.IP TID
+The identification number of the thread being monitored.
+.RE
+.TP
+.BI "-U [ " "username " "]"
+Display the real user name of the tasks being monitored instead of the UID.
+.RI "If " "username"
+is specified, then only tasks belonging to the specified user are displayed.
+.TP
+.B -u
+Report CPU utilization.
+
+When reporting statistics for individual tasks,
+the following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP %usr
+Percentage of CPU used by the task while executing at the user level
+(application), with or without nice priority. Note that this field
+does NOT include time spent running a virtual processor.
+.IP %system
+Percentage of CPU used by the task while executing at the system level (kernel).
+.IP %guest
+Percentage of CPU spent by the task in virtual machine (running a virtual processor).
+.IP %wait
+Percentage of CPU spent by the task while waiting to run.
+.IP %CPU
+Total percentage of CPU time used by the task. In an SMP environment,
+the task's CPU usage will be divided by the total number of CPU's if option
+.B -I
+has been entered on the command line.
+.IP CPU
+Processor number to which the task is attached.
+.IP Command
+The command name of the task.
+.RE
+.IP
+When reporting global statistics for tasks and all their children,
+the following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task which is being monitored
+together with its children.
+.IP USER
+The name of the real user owning the task which is being monitored
+together with its children.
+.IP PID
+The identification number of the task which is being monitored
+together with its children.
+.IP usr-ms
+Total number of milliseconds spent
+by the task and all its children while executing at the
+user level (application), with or without nice priority, and
+collected during the interval of time. Note that this field does
+NOT include time spent running a virtual processor.
+.IP system-ms
+Total number of milliseconds spent
+by the task and all its children while executing at the
+system level (kernel), and collected during the interval of time.
+.IP guest-ms
+Total number of milliseconds spent
+by the task and all its children in virtual machine (running a virtual processor).
+.IP Command
+The command name of the task which is being monitored
+together with its children.
+.RE
+.TP
+.B -V
+Print version number then exit.
+.TP
+.B -v
+Report values of some kernel tables. The following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP threads
+Number of threads associated with current task.
+.IP fd-nr
+Number of file descriptors associated with current task.
+.IP Command
+The command name of the task.
+.RE
+.TP
+.B -w
+Report task switching activity (kernels 2.6.23 and later only).
+The following values may be displayed:
+.RS
+.IP UID
+The real user identification number of the task being monitored.
+.IP USER
+The name of the real user owning the task being monitored.
+.IP PID
+The identification number of the task being monitored.
+.IP cswch/s
+Total number of voluntary context switches the task made per second.
+A voluntary context switch occurs when a task blocks because it
+requires a resource that is unavailable.
+.IP nvcswch/s
+Total number of non voluntary context switches the task made per second.
+An involuntary context switch takes place when a task executes
+for the duration of its time slice and then is forced to relinquish the
+processor.
+.IP Command
+The command name of the task.
+.RE
+
+.SH ENVIRONMENT
+The
+.B pidstat
+command takes into account the following environment variables:
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.IR "never" ", " "always " "or " "auto"
+(the latter is equivalent to the default settings).
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B I=
+SGR (Select Graphic Rendition) substring for item values like PID, UID or CPU number.
+.TP
+.B N=
+SGR substring for non-zero statistics values and for tasks names.
+.TP
+.BR "W=" " (or " "M=" ")"
+SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
+metric's meaning).
+.TP
+.BR "X=" " (or " "H=" ")"
+SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
+metric's meaning).
+.TP
+.B Z=
+SGR substring for zero values and for threads names.
+.RE
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.BR ISO
+then the current locale will be ignored when printing the date in the report header. The
+.B pidstat
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+The timestamp will also be compliant with ISO 8601 format.
+
+.SH EXAMPLES
+.TP
+.B pidstat 2 5
+Display five reports of CPU statistics for every active task in the system
+at two second intervals.
+.TP
+.B pidstat -r -p 1643 2 5
+Display five reports of page faults and memory statistics for
+PID 1643 at two second intervals.
+.TP
+.B pidstat -C """fox|bird"" -r -p ALL
+Display global page faults and memory statistics for all the
+processes whose command name includes the string "fox" or "bird".
+.TP
+.B pidstat -T CHILD -r 2 5
+Display five reports of page faults statistics at two second intervals
+for the child processes of all tasks in the system. Only child processes
+with non-zero statistics values are displayed.
+
+.SH BUGS
+.IR "/proc " "filesystem must be mounted for the"
+.BR "pidstat " "command to work."
+.PP
+.RB "Although " "pidstat"
+speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
+A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
+
+.SH FILES
+.IR "/proc " "contains various files with system statistics."
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "top" "(1), " "ps" "(1), " "mpstat" "(1), " "iostat" "(1), " "vmstat" "(8)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/pilot.1 b/upstream/mageia-cauldron/man1/pilot.1
new file mode 100644
index 00000000..4ddcd16d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pilot.1
@@ -0,0 +1,84 @@
+.TH pilot 1 "Version 1.1"
+.SH Name
+pilot \- simple file system browser in the style of the Alpine Composer
+.SH Syntax
+.B pilot
+[
+.I options
+] [
+.I directory
+]
+.SH Description
+\fIPilot\fR is a simple, display-oriented file system browser based on
+the Alpine message system composer.  As with Alpine, commands are 
+displayed at the bottom of the screen, and context-sensitive
+help is provided.
+.PP
+\fIPilot\fR displays the current working directory at the top of the
+screen.  The directory's contents are displayed in columns of file name,
+file size pairs.  Names that are directories are indicated by the name
+"(dir)" in place of the file size.  The parent of the current working
+directory is indicated by the file name ".." and size of "(parent dir)".
+File names that are symbolic links to other files are displayed with a
+file size of "--".
+.PP
+Several basic file manipulation commands are provided: Delete, Rename,
+Copy, View, Launch, and Edit.  The "View" and "Edit" commands operate on
+text files only.  By default, the "View" command displays files
+using "alpine -F", but will respect the environment variable PAGER if set.
+The "Edit" command simply invokes "pico".  The "Launch" command provides
+a convenient way to either execute the selected file or to run an 
+application on it.
+.PP
+More specific help is available in \fIpilot\fR's online help.
+.SH Options
+.IP \fB-a\fR
+Display all files including those beginning with a period (.).
+.IP \fB-f\fR
+Use function keys for commands.  This option supported only in 
+conjunction with UW Enhanced NCSA telnet.
+.IP \fB-g\fR
+Enable "Show Cursor" mode.  Cause cursor to be positioned
+before the current selection rather than placed at the lower left of the
+display.
+.IP \fB-j\fR
+Enable "Goto" command.  This enables the command to permit explicitly
+telling \fIpilot\fR which directory to visit.
+.IP \fB-m\fR
+Enable mouse functionality.  This only works when \fIpilot\fR is run from
+within an X Window System "xterm" window.
+.IP \fB-n\fIn\fB\fR
+The \-n\fIn\fR option enables new mail notification.  The \fIn\fR 
+argument is optional, and specifies how often, in seconds, your 
+mailbox is checked for new mail.  For example, \-n60 causes \fIpilot\fR 
+to check for new mail once every minute.  The default interval is 180 
+seconds, while the minimum allowed is 30. (Note: no space between "n" and 
+the number) 
+.IP \fB-o\ \fIdir\fB\fR
+Sets operating directory.  Only files within the specified directory are
+accessible and browsing is limited to the specified directory subtree.
+.IP \fB-v\fR
+Enable single vertical column display.
+.IP \fB-x\fR
+Disable keymenu at the bottom of the screen.
+.IP \fB-z\fR
+Enable ^Z suspension of \fIpilot\fR.
+.IP \fB-q\fR
+Termcap or terminfo definition for input escape sequences are used in
+preference to sequences defined by default.  This option is only available
+if \fIpilot\fR was compiled with the TERMCAP_WINS define turned on.
+.IP \fB-setlocale_ctype\fR
+Do setlocale(LC_CTYPE) if available. Default is to not do this setlocale.
+.IP \fB-no_setlocale_collate\fR
+Do not do setlocale(LC_COLLATE). Default is to do this setlocale.
+.fi
+.SH Authors
+Michael Seibel <mikes@cac.washington.edu>
+.br
+Copyright 1994-2007 by the University of Washington.
+.SH "See Also"
+alpine(1)
+.br
+Source distribution (part of the Alpine Message System):
+
+$Date: 2005/01/14 20:40:14 $
diff --git a/upstream/mageia-cauldron/man1/pinky.1 b/upstream/mageia-cauldron/man1/pinky.1
new file mode 100644
index 00000000..23250838
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pinky.1
@@ -0,0 +1,62 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PINKY "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+pinky \- lightweight finger
+.SH SYNOPSIS
+.B pinky
+[\fI\,OPTION\/\fR]... [\fI\,USER\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.TP
+\fB\-l\fR
+produce long format output for the specified USERs
+.TP
+\fB\-b\fR
+omit the user's home directory and shell in long format
+.TP
+\fB\-h\fR
+omit the user's project file in long format
+.TP
+\fB\-p\fR
+omit the user's plan file in long format
+.TP
+\fB\-s\fR
+do short format output, this is the default
+.TP
+\fB\-f\fR
+omit the line of column headings in short format
+.TP
+\fB\-w\fR
+omit the user's full name in short format
+.TP
+\fB\-i\fR
+omit the user's full name and remote host in short format
+.TP
+\fB\-q\fR
+omit the user's full name, remote host and idle time
+in short format
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+A lightweight 'finger' program;  print user information.
+The utmp file will be \fI\,/run/utmp\/\fP.
+.SH AUTHOR
+Written by Joseph Arceneaux, David MacKenzie, and Kaveh Ghazi.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/pinky>
+.br
+or available locally via: info \(aq(coreutils) pinky invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/pjtoppm.1 b/upstream/mageia-cauldron/man1/pjtoppm.1
new file mode 100644
index 00000000..dce3276c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pjtoppm.1
@@ -0,0 +1,62 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pjtoppm User Manual" 0 "14 July 1991" "netpbm documentation"
+
+.SH NAME
+
+pjtoppm - convert an HP PaintJet file to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpjtoppm\fP
+
+[\fIpaintjet\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpjtoppm\fP reads an HP PaintJet file as input and converts it
+into a PPM image.  This was a quick hack to save some trees, and it
+only handles a small subset of the paintjet commands.  In particular,
+it will only handle enough commands to convert most raster image
+files.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpjtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN references
+.SH REFERENCES
+
+HP PaintJet XL Color Graphics Printer User's Guide
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtopj" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Christos Zoulas.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pjtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pktopbm.1 b/upstream/mageia-cauldron/man1/pktopbm.1
new file mode 100644
index 00000000..3291d453
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pktopbm.1
@@ -0,0 +1,77 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pktopbm User Manual" 0 "06 August 1990" "netpbm documentation"
+
+.SH NAME
+
+pktopbm - convert packed (PK) format font into PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+pktopbm pkfile[.pk] [ -x width ] [ -y height ] [-c num] pbmfile ...
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpktopbm\fP reads a packed (PK) font file as input, and produces
+PBM images as output. If the filename "-" is used for any of
+the filenames, the standard input stream (or standard output where
+appropriate) will be used. If either the width or height is specified,
+this value will be used for all bitmaps produced. Also if one or both
+values are specified, the bitmap will be relocated with the hoffset
+and voffset given in the pkfile. The basepoint will be placed in the
+lower left corner of the bitmap if the bitmap is bigger than the
+specified size it will be truncated at the top or right.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpktopbm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-c\fP \fInum\fP
+Sets the character number of the next bitmap written to \fInum\fP.
+
+.TP
+\fB-x\fP \fIwidth\fP
+Sets the width of the image in columns.
+
+.TP
+\fB-y\fP \fIwidth\fP
+Sets the height of the image in rows.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtopk" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Adapted from Tom Rokicki's pxtopk by Angus Duggan <\fIajcd@dcs.ed.ac.uk\fP>.  <\fIbartel@informatik.tu-muenchen.de\fP>
+in March 1995.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pktopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pl2pm.1 b/upstream/mageia-cauldron/man1/pl2pm.1
new file mode 100644
index 00000000..4793bc97
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pl2pm.1
@@ -0,0 +1,80 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PL2PM 1"
+.TH PL2PM 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+pl2pm \- Rough tool to translate Perl4 .pl files to Perl5 .pm modules.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBpl2pm\fR \fIfiles\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpl2pm\fR is a tool to aid in the conversion of Perl4\-style .pl
+library files to Perl5\-style library modules.  Usually, your old .pl
+file will still work fine and you should only use this tool if you
+plan to update your library to use some of the newer Perl 5 features,
+such as AutoLoading.
+.SH LIMITATIONS
+.IX Header "LIMITATIONS"
+It's just a first step, but it's usually a good first step.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Larry Wall <larry@wall.org>
diff --git a/upstream/mageia-cauldron/man1/pldd.1 b/upstream/mageia-cauldron/man1/pldd.1
new file mode 100644
index 00000000..955ffa82
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pldd.1
@@ -0,0 +1,105 @@
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pldd 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+pldd \- display dynamic shared objects linked into a process
+.SH SYNOPSIS
+.nf
+.BI "pldd " "pid"
+.BI pldd " option"
+.fi
+.SH DESCRIPTION
+The
+.B pldd
+command displays a list of the dynamic shared objects (DSOs) that are
+linked into the process with the specified process ID (PID).
+The list includes the libraries that have been dynamically loaded using
+.BR dlopen (3).
+.SH OPTIONS
+.TP
+.B \-\-help
+.TQ
+.B \-?
+Display a help message and exit.
+.TP
+.B \-\-usage
+Display a short usage message and exit.
+.TP
+.B \-\-version
+.TQ
+.B \-V
+Display program version information and exit.
+.SH EXIT STATUS
+On success,
+.B pldd
+exits with the status 0.
+If the specified process does not exist,
+the user does not have permission to access
+its dynamic shared object list,
+or no command-line arguments are supplied,
+.B pldd
+exists with a status of 1.
+If given an invalid option, it exits with the status 64.
+.SH VERSIONS
+Some other systems
+.\" There are man pages on Solaris and HP-UX.
+have a similar command.
+.SH STANDARDS
+None.
+.SH HISTORY
+glibc 2.15.
+.SH NOTES
+The command
+.P
+.in +4n
+.EX
+lsof \-p PID
+.EE
+.in
+.P
+also shows output that includes the dynamic shared objects
+that are linked into a process.
+.P
+The
+.BR gdb (1)
+.I "info shared"
+command also shows the shared libraries being used by a process,
+so that one can obtain similar output to
+.B pldd
+using a command such as the following
+(to monitor the process with the specified
+.IR pid ):
+.P
+.in +4n
+.EX
+$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
+        \fB\-ex "quit" \-p $pid | grep \[aq]\[ha]0x.*0x\[aq]\fP
+.EE
+.in
+.SH BUGS
+From glibc 2.19 to glibc 2.29,
+.B pldd
+was broken: it just hung when executed.
+.\" glibc commit 1a4c27355e146b6d8cc6487b998462c7fdd1048f
+This problem was fixed in glibc 2.30, and the fix has been backported
+to earlier glibc versions in some distributions.
+.SH EXAMPLES
+.EX
+$ \fBecho $$\fP               # Display PID of shell
+1143
+$ \fBpldd $$\fP               # Display DSOs linked into the shell
+1143:   /usr/bin/bash
+linux\-vdso.so.1
+/lib64/libtinfo.so.5
+/lib64/libdl.so.2
+/lib64/libc.so.6
+/lib64/ld\-linux\-x86\-64.so.2
+/lib64/libnss_files.so.2
+.EE
+.SH SEE ALSO
+.BR ldd (1),
+.BR lsof (1),
+.BR dlopen (3),
+.BR ld.so (8)
diff --git a/upstream/mageia-cauldron/man1/pm-gawk.1 b/upstream/mageia-cauldron/man1/pm-gawk.1
new file mode 100644
index 00000000..9f87d89b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pm-gawk.1
@@ -0,0 +1,208 @@
+.ds EP \fIGAWK: Effective AWK Programming\fP
+.ds PM \fIPersistent Memory gawk User Manual\fP
+.TH PM-GAWK 1 "Nov 17 2022" "Free Software Foundation" "Utility Commands"
+.SH NAME
+persistent memory gawk \- persistent data and functions
+.SH SYNOPSIS
+.ft CW
+.nf
+truncate -s \f(CIsize\fP heap.pma
+export GAWK_PERSIST_FILE=heap.pma
+gawk .\^.\^.
+.sp
+truncate -s \f(CIsize\fP heap.pma
+GAWK_PERSIST_FILE=heap.pma gawk .\^.\^.
+.sp
+truncate -s \f(CIsize\fP heap.pma
+alias pm='GAWK_PERSIST_FILE=heap.pma'
+pm gawk .\^.\^.                       # succinct
+.sp
+unset GAWK_PERSIST_FILE   # disable persistence
+.sp
+export GAWK_PERSIST_FILE=other_heap.pma  # change heap
+.sp
+rm heap.pma               # delete heap
+.fi
+.ft R
+.SH DESCRIPTION
+.PP
+.I Gawk
+5.2 and later supports a persistent memory feature that
+can store script-defined variables and functions in a
+file for later use.  The feature, called
+.IR pm-gawk ,
+is described in \*(EP and in \*(PM.
+.PP
+.I pm-gawk
+is activated by passing to
+.I gawk
+the name of an initially empty
+(all-zero-bytes)
+.IR "heap file" ,
+via the environment variable
+\f(CWGAWK_PERSIST_FILE\fP.
+.I pm-gawk
+retains script-defined variables and functions in the heap file for
+use in subsequent
+.I gawk
+invocations.
+.PP
+.I pm-gawk
+offers at least two advantages compared with the existing \f(CWrwarray\fP
+extension: it offers constant-time (``O(1) time'') access to individual
+elements of persistent associative arrays, and it can store script-defined
+functions in addition to variables.
+.SH EXAMPLES
+.PP
+Demonstrate persistent variables:
+.sp .5
+.RS
+.nf
+.ft CW
+$ \f(CBtruncate -s 1G heap.pma\fP            # create heap file
+$ \f(CBexport GAWK_PERSIST_FILE=heap.pma\fP  # "ambient" env var
+$ \f(CBgawk 'BEGIN { print ++i }'\fP
+1
+$ \f(CBgawk 'BEGIN { print ++i }'\fP
+2
+$ \f(CBgawk 'BEGIN { print ++i }'\fP
+3
+.ft R
+.fi
+.RE
+.PP
+To pass the environment variable on per-command basis:
+.sp .5
+.RS
+.nf
+.ft CW
+$ \f(CBunset GAWK_PERSIST_FILE\fP
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
+4
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
+5
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
+6
+.ft R
+.fi
+.RE
+.PP
+To reduce visual clutter of per-command environment variable passing:
+.sp .5
+.RS
+.nf
+.ft CW
+$ \f(CBalias pm='GAWK_PERSIST_FILE=heap.pma'\fP
+$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
+7
+$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
+8
+.ft R
+.fi
+.RE
+.PP
+To refrain from activating persistence:
+.sp .5
+.RS
+.nf
+.ft CW
+$ \f(CBunset GAWK_PERSIST_FILE\fP
+$ \f(CBgawk 'BEGIN { print ++i }'\fP
+1
+$ \f(CBgawk 'BEGIN { print ++i }'\fP
+1
+.ft R
+.fi
+.RE
+.PP
+To permanently ``forget'' the contents of the heap file:
+.sp .5
+.RS
+.nf
+.ft CW
+$ \f(CBrm heap.pma\fP
+.ft R
+.fi
+.RE
+.PP
+.SH ENVIRONMENT VARIABLES
+.PP
+\f(CWGAWK_PERSIST_FILE\fP contains the name of a heap file where
+script-defined variables and functions are stored.  If this environment
+variable is not visible to
+.IR gawk ,
+the
+persistence feature is not activated and
+.I gawk
+behaves in
+its traditional manner.
+.SH VERSION INFORMATION
+.PP
+Persistent memory
+.I gawk
+was first released in
+.I gawk
+5.2.
+.SH AUTHORS
+Arnold Robbins, the maintainer of
+.IR gawk ,
+implemented 
+.I pm-gawk
+using a persistent memory allocator (pma) provided by
+Terence Kelly.  An earlier proof-of-concept prototype
+of persistent
+.I gawk
+was developed by Haris Volos, Zi Fan
+Tan, and Jianan Li using a fork of the official
+.I gawk
+sources.
+.SH CAVEATS
+The GNU/Linux CIFS filesystem is known to cause problems
+for the persistent memory allocator. Do not use a backing file
+on such a filesystem with
+.IR pm-gawk .
+.SH BUG REPORTS
+Follow the procedures in \*(EP and in \*(PM.
+For suspected
+bugs related to persistence (as opposed to other
+non-persistence-related
+.I gawk
+bugs) please also send
+e-mail to Terence Kelly at one or more of these addresses:
+\f(CWtpkelly@acm.org\fP,
+\f(CWtpkelly@eecs.umich.edu\fP,
+or
+\f(CWtpkelly@cs.princeton.edu\fP.
+.SH SEE ALSO
+.IR gawk (1),
+\*(EP,
+and
+\*(PM.
+The two manuals should be available in the Info subsystem
+if Info installed on your system.
+.PP
+See \f(CWhttps://web.eecs.umich.edu/~tpkelly/pma/\fP for
+the latest source code and manual.
+.SH COPYING PERMISSIONS
+Copyright \(co 2022
+Terence Kelly.
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual page provided the copyright notice and this permission
+notice are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual page).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual page under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual page into another language, under the above conditions for
+modified versions, except that this permission notice may be stated in
+a translation approved by the Foundation.
diff --git a/upstream/mageia-cauldron/man1/pngtopam.1 b/upstream/mageia-cauldron/man1/pngtopam.1
new file mode 100644
index 00000000..99352895
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pngtopam.1
@@ -0,0 +1,327 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pngtopam User Manual" 0 "22 July 2008" "netpbm documentation"
+
+.SH NAME
+pngtopam - convert a PNG image into a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpngtopam\fP
+[\fB-verbose\fP]
+[\fB-alphapam\fP | \fB-alpha\fP | \fB-mix\fP]
+[\fB-background\fP=\fIcolor\fP]
+[\fB-gamma\fP=\fIvalue\fP]
+[\fB-text\fP=\fIfilename\fP]
+[\fB-time\fP]
+[\fB-byrow\fP]
+[\fIpngfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpngtopam\fP reads a PNG image (Portable Network Graphics) as
+input and produces a Netpbm image as output.  The type of the output file
+depends on the input file - if it's black & white, \fBpngtopam\fP
+creates a PBM file.  If it's grayscale, \fBpngtopam\fP creates a PGM
+file.  Otherwise, it creates a PPM file.  Except that with the
+\fB-alphapam\fP option, it always creates a PAM file.  That file has
+tuple type GRAYSCALE_ALPHA or RGB_ALPHA depending on whether the input
+has color or not.
+.PP
+To convert in the other direction, use \fBpamtopng\fP or
+\fBpnmtopng\fP.  The former is the more modern of the two and can recognize
+transparency information in a PAM file, as you might generate with \fBpngtopam
+-alphapam\fP.  It has existed only since June 2015.  The latter has more
+features, but probably not ones that matter in the modern world.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpngtopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display various information about the input PNG image and the
+conversion process.
+.sp
+If you want even more information about the PNG image, use
+\fBpngcheck\fP (not part of Netpbm).
+     
+.TP
+\fB-alphapam\fP
+Produce a single output image containing the main image (foreground)
+and the transparency channel or transparency mask.  This image is in the PAM
+format with tuple type of either GRAYSCALE_ALPHA (which has a depth of
+2 channels) or RGB_ALPHA (which has a depth of 4 channels).
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+.sp
+This option was new in Netpbm 10.44 (September 2008).
+
+.TP
+\fB-alpha\fP
+Output the transparency channel or transparency mask of the image. The
+result is either a PBM file or a PGM file, depending on whether
+different levels of transparency appear.
+.sp
+\fBpngtopam\fP discards the main image (the foreground).
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+
+.TP
+\fB-mix\fP
+Compose the image with the transparency or transparency mask against a
+background.  The background color is determined by the bKGD chunk in
+the PNG, except that you can override it with \fB-background\fP.
+If the PNG has no bKGD chunk and you don't specify \fB-background\fP,
+the background color is white.
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+
+.TP
+\fB-background=\fP\fIcolor\fP
+This option specifies the background color with which to mix the image
+when you specify \fB-mix\fP.
+.sp
+\fIcolor\fP is as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Examples:
+
+
+.IP \(bu
+\f(CW-background=rgb:01/ff/80\fP
+.IP \(bu
+\f(CW-background=rgbi:1/255/128\fP
+
+.sp
+If you don't specify \fB-background\fP, the background color is what
+is specified in the PNG image, and if the PNG doesn't specify anything,
+white.
+.sp
+You cannot specify \fB-background\fP unless you also specify
+\fB-mix\fP.  Before Netpbm 10.27 (March 2005), you could specify
+\fB-background\fP without \fB-mix\fP and it was just ignored.  (This
+caused a usability problem).
+
+
+.TP
+\fB-gamma=\fP\fIvalue\fP
+This option causes \fBpngtopam\fP to respect the image gamma information
+in the PNG file (from the gAMA chunk).  Probably by historical accident,
+\fBpngtopam\fP ignores that information by default, assuming the image uses
+the same gamma transformation as a Netpbm image, so the output image has
+different colors than the PNG file actually represents if the PNG doesn't
+actually do that.  (However, it is rare for a PNG file to use a gamma
+transformation different from what the Netpbm formats specify, or if it does,
+to specify with a gAMA chuck what that is).
+.sp
+But when you \fIdo\fP specify \fB-gamma\fP, you get a rather strange
+additional function, probably a historical mistake:
+\fBpngtopam\fP incorporates the specified screen gamma value into the output
+pixels, so that the samples in the Netpbm output deviate from the Netpbm
+format specifications and are appropriate raw intensity values to send to the
+display.  This function essentially just exercises the ability of the PNG
+library to make gamma corrections to the pixels as it reads them from the PNG
+file to produce values appropriate for sending to a certain display in certain
+viewing conditions.  It's a strange function because it has nothing to do with
+PNG and because in Netpbm, the normal way to make gamma corrections
+appropriate for sending to a ceratin display in certain viewing conditions is
+with the program \fBpngtopam\fP, applied to the normal output of
+\fBpngtopam\fP.
+.sp
+If you specify \fB-gamma\fP, but the PNG image does not specify what gamma
+transformation it uses (there is no gAMA chunk), \fBpngtopam\fP assumes a
+simple power transformation with an image gamma of 1.0.  That is probably not
+not the actual image gamma; it is much more likely to be .45.
+.sp
+Because the gammas of uncompensated monitors are around 2.6, which results 
+in an image-gamma of 0.45, some typical situations are: 
+when the image-gamma is 0.45 (use -verbose to check) and the picture is too 
+light, your system is gamma-corrected, so convert with "-gamma 1.0". 
+When no gAMA chunk is present or the image-gamma is 1.0, use 2.2 to make the 
+picture lighter and 0.45 to make the picture darker.
+.sp
+One oddity to be aware of when using \fB-gamma\fP on an image with
+transparency: The PNG image specifies that a certain color is
+transparent, i.e. every pixel in the image of that color is
+transparent.  But \fBpngtopam\fP interprets this as applying to the
+gamma-corrected space, and there may be less precision in that space
+than in the original, which means multiple uncorrected colors map to
+the same corrected color.  So imagine that the image contains 3 shades
+of white (gray) and specifies that one of them is transparent.  After gamma
+correction, those three shades are indistinguishable, so
+\fBpngtopam\fP considers pixels of all three shades to be transparent.
+
+
+.TP
+\fB-text=\fP\fIfile\fP
+Writes the tEXt and zTXt chunks to a file, in a format as
+described in the \fBpnmtopng\fP user manual.  These chunks contain
+text comments or annotations.
+
+.TP
+\fB-time\fP
+Prints the tIME chunk to stderr.
+
+.TP
+\fB-byrow\fP
+This option can make \fBpngtopam\fP run faster or in environments
+where it would otherwise fail.
+.sp
+\fBpngtopam\fP has two ways to do the conversion from PNG to PAM, using
+respectively two facilities of the PNG library:
+
+
+
+.TP
+Whole Image
+Decode the entire image into memory at once, using
+\fBpng_read_image()\fP, then convert to PAM and output row by row.
+   
+.TP
+Row By Row
+Read, convert, and output one row at a time using \fBpng_read_row()\fP.
+
+
+.sp
+Whole Image is generally preferable because the PNG library does more of
+the work, which means it understands more of the PNG format possibilities now
+and in the future.  Also, if the PNG is interlaced, \fBpngtopam\fP does
+not know how to assemble the rows in the right order.
+.sp
+Row By Row uses far less memory, which means with large images, it
+can run in environments where Whole Image cannot and may also run
+faster.  And because Netpbm code does more of the work, it's possible
+that it can be more flexible or at least give better diagnostic
+information if there's something wrong with the PNG.
+.sp
+The Netpbm native code may do something correctly that the PNG library does
+incorrectly, or vice versa.
+.sp
+In Netpbm, we stress function over performance, so by default
+\fBpngtopam\fP uses Whole Image.  You can select Row By Row with
+\fB-byrow\fP if you want the speed or resource requirement improvement.
+.sp
+\fB-byrow\fP was new in Netpbm 10.54 (March 2011).
+
+
+.TP
+\fB-orientraw\fP
+A TIFF stream contains raster data which can be arranged in the
+stream various ways.  Most commonly, it is arranged by rows, with the
+top row first, and the pixels left to right within each row, but many
+other orientations are possible.
+.sp
+The common orientation is the same on the Netpbm formats use, so
+\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
+is oriented that way.
+.sp
+But if the TIFF raster is oriented any other way, it can take a
+considerable amount of processing for \fBtifftopnm\fP to convert it to
+Netpbm format.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopng" (1)\c
+\&,
+.BR "pnmtopng" (1)\c
+\&,
+.BR "pngtopnm" (1)\c
+\&,
+\fBptot\fP,
+.BR "pnmgamma" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+.PP
+For information on the PNG format, see 
+.UR http://schaik.com/png
+http://schaik.com/png
+.UE
+\&.
+
+.UN note
+.SH NOTE
+.PP
+A PNG image contains a lot of information that can't be represented in 
+Netpbm formats.  Therefore, you lose information when you convert to 
+another format with "pngtopam | pnmtoxxx".  If there is a specialized 
+converter that converts directly to the other format, e.g. \fBptot\fP
+to convert from PNG to TIFF, you'll get better results using that.
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+There could be an option to include PNG comment chunks in the output
+image as PNM comments instead of putting them in a separate file.
+.PP
+The program could be much faster, with a bit of code optimizing.
+As with any Netpbm program, speed always takes a back seat to quick
+present and future development.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpngtopam\fP was new in Netpbm 10.44, as a replacement for
+\fBpngtopnm\fP.  The main improvement over \fBpngtopnm\fP was that
+it could generate a PAM image with a transparency channel, whereas
+with \fBpngtopnm\fP, you would have to extract the transparency
+channel as a separate file, in a separate run.
+.PP
+\fBpngtopnm\fP was new in Netpbm 8.1 (March 2000), the first big
+change to the package in Netpbm's renaissance.  It and \fBpnmtopng\fP
+were simply copied from the
+.BR "
+\fBpnmtopng\fP package" (1)\c
+\& by Greg Roelofs.  Those were based on
+simpler reference applications by Alexander Lehmann
+<alex@hal.rhein-main.de> and Willem van Schaik
+<willem@schaik.com> and distributed with their PNG library.
+.PP
+Nearly all of the code has changed since it was copied from the
+\fBpnmtopng\fP package, most of it just to improve maintainability.
+
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pngtopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pngtopnm.1 b/upstream/mageia-cauldron/man1/pngtopnm.1
new file mode 100644
index 00000000..c4045ac6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pngtopnm.1
@@ -0,0 +1,70 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pngtopnm User Manual" 0 "22 July 2008" "netpbm documentation"
+
+.SH NAME
+
+pngtopnm - Convert a PNG image to PNM: replaced by pngtopam
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpngtopnm\fP
+[\fB-verbose\fP]
+[\fB-alpha\fP | \fB-mix\fP]
+[\fB-background\fP=\fIcolor\fP]
+[\fB-gamma\fP=\fIvalue\fP]
+[\fB-text\fP=\fIfilename\fP]
+[\fB-time\fP]
+[\fIpngfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpngtopnm\fP was obsoleted by
+.BR "\fBpngtopam\fP" (1)\c
+\&, introduced with Netpbm 10.44
+(September 2008).  \fBpngtopam\fP is backward compatible with
+\fBpngtopnm\fP, plus adds many additional functions, including the
+ability to produce a PAM image that includes a transparency (alpha)
+channel.
+
+Starting in Release 10.48, \fBpngtopnm\fP is just an alias for
+\fBpngtopam\fP.
+.PP
+\fBpngtopnm\fP remained in the Netpbm package through Release 10.47
+because it may have fewer bugs than \fBpngtopam\fP in those releases, and may
+be faster in some environments.  But \fBpngtopnm\fP's incompatibility with
+the most current PNG libraries makes it impractical to maintain along with
+\fBpngtopam\fP now.
+.PP
+In releases before 10.48, you can use the \fBpngtopam\fP documentation for
+\fBpngtopnm\fP, considering the following differences:
+
+
+
+.IP \(bu
+\fBpngtopnm\fP options are a subset of \fBpngtopam\fP's, as
+documented above.
+
+.IP \(bu
+Any change that the \fBpngtopam\fP manual says happened in or
+after Netpbm 10.44 doesn't apply to \fBpngtopnm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pngtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmalias.1 b/upstream/mageia-cauldron/man1/pnmalias.1
new file mode 100644
index 00000000..4756d0dc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmalias.1
@@ -0,0 +1,114 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmalias User Manual" 0 "15 March 2004" "netpbm documentation"
+
+.SH NAME
+
+pnmalias - antialias a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmalias\fP
+
+[\fB-bgcolor\fP \fIcolor\fP]
+
+[\fB-fgcolor\fP \fIcolor\fP]
+
+[\fB-bonly\fP]
+
+[\fB-fonly\fP]
+
+[\fB-balias\fP]
+
+[\fB-falias\fP]
+
+[\fB-weight\fP \fIw\fP]
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmalias\fP reads a PNM image as input, and applies
+anti-aliasing to background and foreground pixels.  If the input file
+is a PBM, \fBpnmalias\fP promotes the output anti-aliased image to a
+PGM, and prints a message informing the user of the change in format.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmalias\fP recognizes the following
+command line options:
+.PP
+\fB-bgcolor\fP \fIcolorb\fP sets the background color the
+\fIcolorb\fP.
+.PP
+\fB-fgcolor\fP \fIcolorf\fP sets the foreground color to
+\fIcolorf\fP.
+.PP
+Pixels with these values will be anti-aliased.  By default,
+\fBpnmalias\fP takes the background color to be black, and foreground
+color to be white.
+.PP
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.PP
+Note that even when dealing with PGMs, background and foreground
+colors need to be specified in the fashion described above.  In this
+case, \fBpnmalias\fP takes the background and foreground pixel values
+to be the value of the red component for the specified color.
+.PP
+\fB-bonly\fP says to apply anti-aliasing only to the background pixels.
+.PP
+\fB-fonly\fP says to apply anti-aliasing only to the foreground pixels.
+.PP
+\fB-balias\fP says to apply anti-aliasing to all pixels surrounding
+background pixels.
+.PP
+\fB-falias\fP says to apply anti-aliasing to all pixels surrounding
+foreground pixels.
+.PP
+If you specify neither \fB-balias\fP nor \fB-falias\fP,
+\fBpnmalias\fP applies anti-aliasing only among neighboring
+background and foreground pixels.
+.PP
+\fB-weight\fP \fIw\fP says to use \fIw\fP as the central weight
+for the aliasing filter.  \fIw\fP must be a real number in the range
+0 < \fIw\fP < 1.  The lower the value of \fIw\fP is, the
+"blurrier" the output image is.  The default is w = 1/3.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtext" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992 by Alberto Accomazzi, Smithsonian Astrophysical Observatory.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmalias.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmarith.1 b/upstream/mageia-cauldron/man1/pnmarith.1
new file mode 100644
index 00000000..bef2369a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmarith.1
@@ -0,0 +1,32 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmarith User Manual" 0 "22 June 2002" "netpbm documentation"
+
+.SH NAME
+
+pnmarith - replaced by pamarith
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Starting with Netpbm 10.3, \fBpnmarith\fP is obsolete.  Use
+.BR "\fBpamarith\fP" (1)\c
+\& instead.
+
+\fBpamarith\fP is backward compatible with \fBpnmarith\fP except where
+your input images have different depths.  \fBpnmarith\fP would convert
+the one with the lesser depth to have the higher depth before doing the
+arithmetic.  With \fBpamarith\fP, you must do that step separately, using
+\fBpgmtoppm\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmarith.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmcat.1 b/upstream/mageia-cauldron/man1/pnmcat.1
new file mode 100644
index 00000000..0c6ddd7c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmcat.1
@@ -0,0 +1,33 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmcat User Manual" 0 "13 August 2022" "netpbm documentation"
+
+.SH NAME
+
+pnmcat - replaced by pamcat
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmcat\fP was obsoleted by
+.BR "\fBpamcat\fP" (1)\c
+\&, introduced with Netpbm 11.00
+(September 2022).  \fBpamcat\fP is backward compatible with \fBpnmcat\fP,
+plus adds many additional functions, including the ability to process PAM
+images.
+.PP
+In Netpbm before 11.00, use the manual for \fBpamcat\fP with
+\fBpnmcat\fP.  Features that are in \fBpamcat\fP but not \fBpnmcat\fP
+are indicated by statements that they didn't exist before 11.00.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmcat.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmcolormap.1 b/upstream/mageia-cauldron/man1/pnmcolormap.1
new file mode 100644
index 00000000..a6b8b6a3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmcolormap.1
@@ -0,0 +1,307 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmcolormap User Manual" 0 "21 February 2023" "netpbm documentation"
+
+.SH NAME
+
+pnmcolormap - create quantization color map for a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmcolormap\fP
+
+[\fB-center\fP|\fB-meancolor\fP|\fB-meanpixel\fP]
+
+[\fB-spreadbrightness\fP|\fB-spreadluminosity\fP]
+
+[\fB-splitpixelct\fP|\fB-splitcolorct\fP|\fB-splitspread\fP]
+
+[\fB-sort\fP]
+
+[\fB-square\fP] 
+
+[\fB-verbose\fP] 
+
+[\fB-debug\fP] 
+
+\fIncolors\fP|\fBall\fP
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmcolormap\fP reads a PNM or PAM image as input, chooses
+\fIncolors\fP colors to best represent the image and writes a PNM
+color map defining them as output.  A PAM image may actually contain
+tuples of any kind, but \fBpnmcolormap\fP's concept of the tuple values
+that best represent the ones present in the image may not make sense if
+the tuple type isn't RGB or GRAYSCALE.  The design of the program, and
+the rest of this manual, assumes the tuples represent colors.
+.PP
+You can use this map as input to \fBpnmremap\fP on the same input
+image to quantize the colors in that image, I.e. produce a similar
+image with fewer colors.  \fBpnmquant\fP does both the \fBpnmcolormap\fP
+and \fBpnmremap\fP steps for you.
+.PP
+A PNM colormap is a PNM image of any dimensions that contains at
+least one pixel of each color in the set of colors it represents.  The
+ones \fBpnmcolormap\fP generates have exactly one pixel of each color,
+except where padding is necessary with the \fB-square\fP option.
+.PP
+The quantization method is Heckbert's "median cut".
+See 
+.UR #quant
+QUANTIZATION METHOD
+.UE
+\&.
+.PP
+The output image is of the same format (PBM, PGM, PPM, PAM) as the
+input image.  Note that a colormap of a PBM image is not very
+interesting.
+.PP
+The colormap generally has the same maxval as the input image, but
+\fBpnmcolormap\fP may reduce it if there are too many colors in the
+input, as part of its quantization algorithm.
+.PP
+\fBpnmcolormap\fP works on a multi-image input stream.  In that
+case, it produces one colormap that applies to all of the colors in
+all of the input images.  All the images must have the same format,
+depth, and maxval (but may have different height and width).  This is
+useful if you need to quantize a bunch of images that will form a
+movie or otherwise be used together -- you generally want them all to
+draw from the same palette, whereas computing a colormap separately
+from each image would make the same color in two images map to
+different colors.  Before Netpbm 10.31 (December 2005), \fBpnmcolormap\fP
+ignored any image after the first.
+.PP
+If you want to create a colormap without basing it on the colors in
+an input image, \fBpamseq\fP, \fBppmmake\fP, and \fBpnmcat\fP can
+be useful.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+The single parameter, which is required, is the number of colors you want
+in the output colormap.  \fBpnmcolormap\fP may produce a color map with
+slightly fewer colors than that.  You may specify \fBall\fP to get a colormap
+of every color in the input image (no quantization).  When you specify
+\fBall\fP, the function is essentially the same as that of \fBppmhist
+-map\fP.  \fBppmhist\fP is much older.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmcolormap\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and
+its value.
+
+
+.TP
+\fB-sort\fP
+This option causes the output colormap to be sorted by the red
+component intensity, then the green, then the blue in ascending order.
+This is an insertion sort, so it is not very fast on large colormaps.
+Sorting is useful because it allows you to compare two sets of colors.
+
+.TP
+\fB-square\fP
+By default, \fBpnmcolormap\fP produces as the color map a PPM
+image with one row and with one column for each color in the colormap.
+This option causes \fBpnmcolormap\fP instead to produce a PPM image
+that is within one row or column of being square, with the last pixel
+duplicated as necessary to create a number of pixels which is such an
+almost-perfect square.
+
+.TP
+\fB-verbose\fP
+This option causes \fBpnmcolormap\fP to display messages to
+Standard Error about the quantization..TP
+\fB-center\fP
+
+.TP
+\fB-debug\fP
+This option causes \fBpnmcolormap\fP to display messages to
+Standard Error about internal workings.
+
+.TP
+\fB-center\fP
+
+.TP
+\fB-meancolor\fP
+
+.TP
+\fB-meanpixel\fP
+
+.TP
+\fB-spreadbrightness\fP
+
+.TP
+\fB-spreadluminosity\fP
+
+.TP
+\fB-splitpixelct\fP
+
+.TP
+\fB-splitcolorct\fP
+
+.TP
+\fB-splitspread\fP
+These options control the quantization algorithm.  See 
+.UR #quant
+QUANTIZATION METHOD
+.UE
+\&.
+
+
+
+
+.UN quant
+.SH QUANTIZATION METHOD
+.PP
+A quantization method is a way to choose which colors, being fewer
+in number than in the input, you want in the output.
+\fBpnmcolormap\fP uses Heckbert's "median cut" quantization
+method.
+.PP
+This method involves separating all the colors into
+"boxes," each holding colors that represent about the same
+number of pixels.  You start with one box and split boxes in two until
+the number of boxes is the same as the number of colors you want in
+the output, and choose one color to represent each box.
+.PP
+There are three ways \fBpnmcolormap\fP can choose the box to split in
+  each step:
+  
+.IP \(bu
+Split the box containing the most pixels.  This is the default,
+      and you can select it explicitly with option \fB-splitpixelct\fP.
+.IP \(bu
+Split the box containing the most colors.  This appears to be useful
+      for academic purposes only.  Select this with option
+      \fB-splitcolorct\fP.
+.IP \(bu
+Split the box containing the largest color spread.  Select this
+      with option \fB-splitspread\fP.  This can produce a better result for
+      small details with colors not found elsewhere in the image.
+  
+.PP
+\fB-splitpixelct\fP, \fBsplitcolorct\fP, and \fBsplitspread\fP were new
+  in Netpbm 10.88 (September 2019).  Before that, \fBpnmcolormap\fP always
+  splits the box containing the most pixels.
+  
+.PP
+When you split a box, you do it so each sub-box has the same number of
+pixels (except one sub-box has more if the full box has an odd number), with
+the 'greatest' pixels in one sub-box and the 'least'
+pixels in the other.  "Greater," for a particular box, means it is brighter in
+the color component (red, green, blue) which has the largest spread in that
+box.  \fBpnmcolormap\fP gives you two ways to define "largest spread.": 1)
+largest spread of brightness; 2) largest spread of contribution to the
+luminosity of the color.  E.g. red is weighted much more than blue.  Select
+among these with the \fB-spreadbrightness\fP and \fB-spreadluminosity\fP
+options.  The default is \fB-spreadbrightness\fP.  Where there are multiple
+colors of the median magnitude, they are distributed arbitrarily among between
+the subboxes.  This arbitrary distribution depends upon what the system's
+\fBqsort\fP function does with multiple equal values, so \fBpnmcolormap\fP
+may produce slightly different results on different systems.
+.PP
+\fBpnmcolormap\fP provides three ways of choosing a color to represent a
+box: 1) the center color - the color halfway between the greatest and least
+colors in the box, using the above definition of "greater"; 2) the mean of the
+colors (each component averaged separately by brightness) in the box; 3) the
+mean weighted by the number of pixels of a color in the image.
+.PP
+Select among these with the \fB-center\fP, \fB-meancolor\fP, and
+\fB-meanpixel\fP options.  The default is \fB-center\fP.
+.PP
+Note that in all three methods, there may be colors in the output
+which do not appear in the input at all.
+.PP
+Also note that the color chosen to represent the colors in Box A the best
+may also represent a color in Box B better than the color chosen to represent
+the colors in Box B the best.  This is true for various measures of goodness
+of representation of one color by another.  In particular, if you
+use \fBpnmremap\fP to map the colors in the very image that you used to
+create the color map to the colors in that colormap, the colors in Box B will
+often map to the color \fBpnmcolormap\fP chose to represent some other box
+and in fact the color \fBpnmcolormap\fP chose to represent Box B may not
+appear in the \fBpnmremap\fP output at all.
+  
+
+.UN references
+.SH REFERENCES
+
+"Color Image Quantization for Frame Buffer Display" by Paul Heckbert,
+SIGGRAPH '82 Proceedings, page 297.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppmquantall" (1)\c
+\&,
+.BR "pamgetcolor" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Before Netpbm 10.15 (April 2003), \fBpnmcolormap\fP used a lot
+more memory for large images because it kept the entire input image in
+memory.  Now, it processes it a row at a time, but because it
+sometimes must make multiple passes through the image, it first copies
+the input into a temporary seekable file if it is not already in a seekable
+file.
+.PP
+\fBpnmcolormap\fP first appeared in Netpbm 9.23 (January 2002).
+Before that, its function was available only as part of the function
+of \fBpnmquant\fP (which was derived from the much older
+\fBppmquant\fP).  Color quantization really has two main subfunctions, so
+Netpbm 9.23 split it out into two separate programs:
+\fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced
+\fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and
+\fBpnmremap\fP.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmcolormap.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmcomp.1 b/upstream/mageia-cauldron/man1/pnmcomp.1
new file mode 100644
index 00000000..8194b5c9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmcomp.1
@@ -0,0 +1,39 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmcomp User Manual" 0 "02 August 2014" "netpbm documentation"
+
+.SH NAME
+
+\fBpnmcomp\fP - replaced by pamcomp
+
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmcomp\fP was obsoleted by
+.BR "\fBpamcomp\fP" (1)\c
+\&,
+introduced with Netpbm 10.21 (March 2004).  \fBpamcomp\fP is backward
+compatible with \fBpnmcomp\fP, plus adds many additional functions.  Among
+this is the ability to process PAM images, including those with transparency
+channels.
+.PP
+\fBpnmcomp\fP remained in the Netpbm package until Netpbm 10.68 (September
+2014) because of hopes that it had fewer bugs than \fBpamcomp\fP because of
+its age.  But now it would just be clutter.
+.PP
+In Netpbm before 10.21, use the manual for \fBpamcomp\fP with
+\fBpnmcomp\fP.  Features that are in \fBpamcomp\fP but not \fBpnmcomp\fP
+are indicated by statements that they didn't exist before 10.21.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmcomp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmconvol.1 b/upstream/mageia-cauldron/man1/pnmconvol.1
new file mode 100644
index 00000000..cb5e2a29
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmconvol.1
@@ -0,0 +1,486 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmconvol User Manual" 0 "30 November 2018" "netpbm documentation"
+
+.SH NAME
+pnmconvol - general MxN convolution on a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmconvol\fP
+{
+\fB-matrix=\fP\fIconvolution_matrix\fP
+|
+\fB-matrixfile=\fP\fIfilename\fP[\fB,\fP\fIfilename\fP[\fB,\fP ...]]
+}
+[\fB-normalize\fP]
+[\fB-bias=\fIn\fP\fP]
+
+[\fInetpbmfile\fP]
+.PP
+\fBpnmconvol\fP
+\fIconvolution_matrix_file\fP
+[\fB-normalize\fP]
+[\fB-nooffset\fP]
+[\fInetpbmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmconvol\fP reads a Netpbm image as input, convolves it with
+a specified convolution matrix, and writes a Netpbm image as output.
+.PP
+A command use for convolution is blurring.  See examples in the
+.BR "\fBpamgauss\fP" (1)\c
+\& manual.
+  
+.PP
+Convolution means replacing each pixel with a weighted average of
+the nearby pixels.  The weights and the area to average are determined
+by the convolution matrix (sometimes called a convolution kernel),
+which you supply in one of several ways.  See 
+.UR #convolmatrix
+ Convolution Matrix
+.UE
+\&.
+.PP
+At the edges of the convolved image, where the convolution matrix would
+extend over the edge of the image, \fBpnmconvol\fP just copies the input
+pixels directly to the output.  It's often better to deal with the pixels near
+an edge by assuming some blank or background color beyond the edge.  To do
+that, use \fBpnmpad\fP to add a margin all around whose size is half that of
+your convolution matrix size, not counting its center, in the same dimension.
+(E.g. if your convolution matrix is 5 wide by 3 high, use
+\f(CWpnmpad -left=2 -right=2 -top=1 -bottom=1\fP).  Feed that enlarged
+image to \fBpnmconvol\fP, then use \fBpamcut\fP to chop the edges off the
+convolved output, getting back to your original image dimensions.  (E.g.
+\f(CWpamcut -left=2 -right=-2 -top=1 -bottom=-1\fP).
+.PP
+The convolution computation can result in a value which is outside the
+range representable in the output.  When that happens, \fBpnmconvol\fP just
+clips the output, which means brightness is not conserved.
+.PP
+To avoid clipping, you may want to scale your input values.  For example,
+if your convolution matrix might produce an output value as much as double the
+maximum value in the input, then make sure the maxval of the input (which is
+also the maxval of the output) is at least twice the actual maximum value in
+the input.
+.PP
+Clipping negative numbers deserves special consideration.  If your
+convolution matrix includes negative numbers, it is possible for
+\fBpnmconvol\fP to calculate an output pixel as a negative value,
+which \fBpnmconvol\fP would of course clip to zero, since Netpbm formats
+cannot represent negative numbers.
+
+
+.UN convolmatrix
+.SS Convolution Matrix
+.PP
+There are three ways to specify the convolution matrix:
+
+
+.IP \(bu
+directly with a \fB-matrix\fP option.
+
+.IP \(bu
+In a file (or set of them) named by a \fB-matrixfile\fP option, whose
+contents are similar to a \fB-matrix\fP option value.
+
+.IP \(bu
+With a special PNM file.
+
+.PP
+The PNM file option is the hardest, and exists only because
+until Netpbm 10.49 (December 2009), it was the only way.
+.PP
+The regular convolution matrix file is slightly easier to read
+than the \fB-matrix\fP option value, and makes your command line
+less messy, but requires you to manage a separate file.  With the file,
+you can have separate convolution matrices for the individual color
+components, which you can't do with \fB-matrix\fP.
+.PP
+In any case, the convolution matrix \fBpnmconvol\fP uses is a
+matrix of real numbers.  They can be whole or fractional, positive,
+negative, or zero.
+.PP
+The convolution matrix always has an odd width and height, so that
+there is a center element.  \fBpnmconvol\fP figuratively places that
+center element over a pixel of the input image and weights that pixel
+and its neighbors as indicated by the convolution matrix to produce the
+pixel in the same location of the output image.
+.PP
+For a normal convolution, where you're neither adding nor subtracting total
+value from the image, but merely moving it around, you'll want to make sure
+that all the numbers in the matrix add up to 1.  If they don't,
+\fBpnmconvol\fP warns you.
+.PP
+The elements of the matrix are actually tuples, one for each sample in the
+input.  (I.e. if the input is an RGB image, each element of the convolution
+matrix has one weight for red, one for green, and one for blue.
+
+
+.UN matrixopt
+.B Directly On the Command Line
+.PP
+Here are examples of a \fB-matrix\fP option:
+
+.nf
+\f(CW
+    -matrix=0,.2,0;.2,.2,.2;0,.2,0
+\fP
+
+.fi
+
+.nf
+\f(CW
+    -matrix=-1,3,-1
+\fP
+
+.fi
+.PP
+The value consists of each row of the matrix from top to bottom, separated
+by semicolons.  Each row consists of the elements of the row from left to
+right, separated by commas.  You must of course have the same number of
+elements in each row.  Each element is a decimal floating point number
+and is the weight to give to each component of a pixel that corresponds to
+that matrix location.
+.PP
+Note that when you supply this option via a shell, semicolon
+(";") probably means something to the shell, so use quotation
+marks.
+.PP
+There is no way with this method to have different weights for different
+components of a pixel.
+.PP
+The \fB-normalize\fP option is often quite handy with \fB-matrix\fP
+because it lets you quickly throw together the command without working out the
+math to make sure the matrix isn't biased.  Note that if you use the
+\fB-normalize\fP option, the weights in the matrix aren't actually the
+numbers you specify in the \fB-matrix\fP option.
+
+
+.UN matrixfile
+.B Regular Matrix File
+.PP
+Specify the name of the matrix file with a \fB-matrixfile\fP
+option.  Or specify a list of them, one for each plane of the image.
+.PP
+Examples:
+
+.nf
+\f(CW
+    -matrixfile=mymatrix
+\fP
+
+\f(CW
+    -matrixfile=myred,mygreen,myblue
+\fP
+
+.fi
+.PP
+Each file applies to one plane of the image (e.g. red, green, or blue), in
+order.  The matrix in each file must have the same dimensions.  If the
+input image has more planes than the number of files you specify, the first
+file applies to the extra planes as well.
+.PP
+\fBpnmconvol\fP interprets the file as text, with lines delimited by Unix
+newline characters (line feeds).
+.PP
+Each line of the file is one row of the matrix, in order from top to
+bottom.
+.PP
+For each row, the file contains a floating point decimal number for each
+element in the row, from left to right, separated by spaces.  This is not just
+any old white space -- it is exactly one space.  Two spaces in a row mean
+you've specified a null string for an element (which is invalid).  If you
+want to line up your matrix visually, use leading and trailing zeroes
+in the floating point numbers to do it.
+.PP
+There is no way to put comments in the file.  There is no signature
+or any other metadata in the file.
+.PP
+Note that if you use the \fB-normalize\fP option, the weights in the
+matrix aren't actually what is in the file.
+
+
+.UN matrixpnm
+.B PNM File
+.PP
+Before Netpbm 10.49 (December 2009), this was the only way to 
+specify a convolution matrix.  \fBpnmconvol\fP used this method in
+an attempt to exploit the generic matrix processing capabilities of
+Netpbm, but as the Netpbm formats don't directly allow matrices with
+the kinds of numbers you need in a convolution matrix, it is quite
+cumbersome.  In fact, there simply is no way to specify some convolution
+matrices with a legal Netpbm image, so to make it work, \fBpnmconvol\fP has
+to relax the Netpbm file requirement that sample values be no greater
+than the image's maxval.  I.e. it isn't even a real PNM file.
+.PP
+The way you select this method of supplying the convolution matrix is to
+\fInot\fP specify \fB-matrix\fP or \fB-matrixfile\fP.  When you do that,
+you must specify a second non-option argument -- that is the name of the PNM
+file (or PNM equivalent PAM file).
+.PP
+There are two ways \fBpnmconvol\fP interprets the PNM convolution matrix
+image pixels as weights: with offsets, and without offsets.
+.PP
+The simpler of the two is without offsets.  That is what happens
+when you specify the \fB-nooffset\fP option.  In that case,
+\fBpnmconvol\fP simply normalizes the sample values in the PNM image
+by dividing by the maxval.
+.PP
+For example, here is a sample convolution file that causes an output pixel
+to be a simple average of its corresponding input pixel and its 8 neighbors,
+resulting in a smoothed image:
+
+.nf
+    P2
+    3 3
+    18
+    2 2 2
+    2 2 2
+    2 2 2
+
+.fi
+.PP
+(Note that the above text is an actual PGM file -- you can cut and paste
+it.  If you're not familiar with the plain PGM format, see
+.BR "the PGM format specification" (1)\c
+\&).
+.PP
+\fBpnmconvol\fP divides each of the sample values (2) by the maxval
+(18) so the weight of each of the 9 input pixels gets is 1/9, which is
+exactly what you want to keep the overall brightness of the image the
+same.  \fBpnmconvol\fP creates an output pixel by multiplying the
+values of each of 9 pixels by 1/9 and adding.
+.PP
+Note that with maxval 18, the range of possible values is 0 to 18.
+After scaling, the range is 0 to 1.
+.PP
+For a normal convolution, where you're neither adding nor
+subtracting total value from the image, but merely moving it around,
+you'll want to make sure that all the scaled values in (each plane of)
+your convolution PNM add up to 1, which means all the actual sample
+values add up to the maxval.  Alternatively, you can use the
+\fB-normalize\fP option to scale the scaled values further to make them all
+add up to 1 automatically.
+.PP
+When you \fIdon't\fP specify \fB-nooffset\fP, \fBpnmconvol\fP
+applies an offset, the purpose of which is to allow you to indicate
+negative weights even though PNM sample values are never negative.  In
+this case, \fBpnmconvol\fP subtracts half the maxval from each sample
+and then normalizes by dividing by half the maxval.  So to get the
+same result as we did above with \fB-nooffset\fP, the convolution
+matrix PNM image would have to look like this:
+
+.nf
+    P2
+    3 3
+    18
+    10 10 10
+    10 10 10
+    10 10 10
+
+.fi
+.PP
+To see how this works, do the above-mentioned offset: 10 - 18/2
+gives 1.  The normalization step divides by 18/2 = 9, which makes it
+1/9 - exactly what you want.  The equivalent matrix for 5x5 smoothing
+would have maxval 50 and be filled with 26.
+.PP
+Note that with maxval 18, the range of possible values is 0 to 18.
+After offset, that's -9 to 9, and after normalizing, the range is -1 to 1.
+.PP
+The convolution file will usually be a PGM, so that the same
+convolution gets applied to each color component.  However, if you
+want to use a PPM and do a different convolution to different
+colors, you can certainly do that.
+
+
+.UN otherconvol
+.SS Other Forms of Convolution
+.PP
+\fBpnmconvol\fP does only arithmetic, linear combination convolution.
+There are other forms of convolution that are especially useful in image
+processing.
+.PP
+\fBpgmmedian\fP does median filtering, which is a form of convolution
+where the output pixel value, rather than being a linear combination of the
+pixels in the window, is the median of a certain subset of them.
+.PP
+\fBpgmmorphconv\fP does dilation and erosion, which is like the median
+filter but the output value is the minimum or maximum of the values in the
+window.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmconvol\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-matrix=\fP\fIconvolution_matrix\fP
+The value of the convolution matrix.  See
+.UR #matrixopt
+Convolution Matrix
+.UE
+\&.
+.sp
+You may not specify both this and \fB-matrixfile\fP.
+.sp
+This option was new in Netpbm 10.49 (December 2009).  Before
+that, use a PNM file for the convolution matrix.
+
+.TP
+\fB-matrixfile=\fP\fIfilename\fP
+This specifies that you are supplying the convolution matrix in
+a file and names that file.  See
+.UR #matrixfile
+Convolution Matrix
+.UE
+\&.
+.sp
+You may not specify both this and \fB-matrix\fP.
+.sp
+This option was new in Netpbm 10.49 (December 2009).  Before
+that, use a PNM file for the convolution matrix.
+
+.TP
+\fB-normalize\fP
+This option says to adjust the weights in your convolution matrix so they
+all add up to one.  You usually want them to add up to one so that the
+convolved result tends to have the same overall brightness as the input.  With
+\fB-normalize\fP, \fBpnmconvol\fP scales all the weights by the same factor
+to make the sum one.  It does this for each plane.
+.sp
+This can be quite convenient because you can just throw numbers into
+the matrix that have roughly the right relationship to each other and let
+\fBpnmconvol\fP do the work of normalizing them.  And you can adjust a matrix
+by raising or lowering certain weights without having to modify all the other
+weights to maintain normalcy.  And you can use friendly integers.
+.sp
+Example:
+
+.nf
+\f(CW
+    $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
+\fP
+
+.fi
+.sp
+This is of course a basic 3x3 average, but without you having to
+specify 1/9 (.1111111) for each weight.
+.sp
+This option was new in Netpbm 10.50 (March 2010).  But before Netpbm 10.79
+(June 2017), it has no effect when you specify the convolution matrix via
+pseudo-PNM file.
+
+.TP
+\fB-bias=\fP\fIn\fP
+.sp
+This specifies an amount to add to the convolved value for each sample.
+.sp
+The purpose of this addition is normally to handle negative convolution
+results.  Because the convolution matrix can contain negative numbers, the
+convolved value for a pixel could be negative.  But Netpbm formats cannot
+contain negative sample values, so without any bias, such samples would get
+clipped to zero.  The bias allows the output image to retain the information,
+and a program that pocesses that output, knowing the bias value, could
+reconstruct the real convolved values.
+.sp
+For example, with \fBbias=100\fP, a sample whose convolved value is -5
+appears as 95 in the output, whereas a sample whose convolved value is 5
+appears as 105 in the output.
+.sp
+A typical value for the bias is half the maxval, allowing the same range on
+either side of zero.
+.sp
+If the sample value, after adding the bias, is still less than
+zero, \fBpnmconvol\fP clips it to zero.  If it exceeds the maxval of the
+output image, it clips it to the maxval.
+.sp
+The default is zero.
+.sp
+This option was new in Netpbm 10.68 (September 2014).
+
+.TP
+\fB-nooffset=\fP
+This is part of the obsolete PNM image method of specifying the
+convolution matrix.  See
+.UR #matrixpnm
+Convolution Matrix
+.UE
+\&.
+
+
+
+.UN history
+.SH HISTORY
+.PP
+The \fB-nooffset\fP option was new in Netpbm 10.23 (July 2004),
+making it substantially easier to specify a convolution matrix, but
+still hard.  In Netpbm 10.49 (December 2009), the PNM convolution
+matrix tyranny was finally ended with the \fB-matrix\fP and
+\fB-matrixfile\fP options.  In between, \fBpnmconvol\fP was broken
+for a while because the Netpbm library started enforcing the
+requirement that a sample value not exceed the maxval of the
+image.  \fBpnmconvol\fP used the Netpbm library to read the PNM
+convolution matrix file, but in the pseudo-PNM format
+that \fBpnmconvol\fP uses, a sample value sometimes has to exceed the
+maxval.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "pgmmorphconv" (1)\c
+\&,
+.BR "pgmmedian" (1)\c
+\&,
+.BR "pnmnlfilt" (1)\c
+\&,
+.BR "pgmkernel" (1)\c
+\&,
+.BR "pamgauss" (1)\c
+\&,
+.BR "pammasksharpen" (1)\c
+\&,
+.BR "pnmpad" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+Modified 26 November 1994 by Mike Burns, \fIburns@chem.psu.edu\fP
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmconvol.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmcrop.1 b/upstream/mageia-cauldron/man1/pnmcrop.1
new file mode 100644
index 00000000..6bc83a94
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmcrop.1
@@ -0,0 +1,427 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmcrop User Manual" 0 "16 August 2020" "netpbm documentation"
+
+.SH NAME
+pnmcrop - crop a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmcrop\fP
+
+[\fB-white\fP
+|\fB-black\fP
+|\fB-sides\fP
+|\fB-bg-color=\fP\fIcolor\fP
+|\fB-bg-corner=\fP{
+\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP}
+]
+
+[\fB-left\fP]
+
+[\fB-right\fP]
+
+[\fB-top\fP]
+
+[\fB-bottom\fP]
+
+[\fB-margin=\fP\fIpixels\fP]
+
+[\fB-closeness=\fP\fIcloseness_percent\fP]
+
+[\fB-borderfile=\fP\fIfilename\fP]
+
+[\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP}]
+
+{[\fB-reportfull\fP]|[\fB-reportsize\fP]}
+
+[\fB-verbose\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmcrop\fP reads a PBM, PGM, or PPM image as input, removes
+borders that are the background color, and produces the same type of
+image as output.
+.PP
+If you don't specify otherwise, \fBpnmcrop\fP assumes the
+background color is whatever color the top left and right corners of
+the image are and if they are different colors, something midway
+between them.  You can specify that the background is white or black
+with the \fB-white\fP and \fB-black\fP options or make
+\fBpnmcrop\fP base its guess on all four corners instead of just two
+with \fB-sides\fP.
+.PP
+By default, \fBpnmcrop\fP chops off any stripe of background color
+it finds, on all four sides.  You can tell \fBpnmcrop\fP to remove
+only specific borders with the \fB-left\fP, \fB-right\fP,
+  \fB-top\fP, and \fB-bottom\fP options.
+.PP
+But note that \fBpnmcrop\fP's determination of the background color is
+independent of which edges you crop, which may not be intuitive.  For example,
+imagine an image with a blue border at the top and a black border at the
+bottom and you say to crop the bottom (\fB-bottom\fP).  You may have expected
+to crop the black border, but you actually won't crop anything,
+because \fBpnmcrop\fP considers the background color to be whatever color the
+top two corners are, which is blue, and there is no blue at the bottom of the
+image.  If you do want \fBpnmcrop\fP to take the background color from the
+edges being cropped, use \fB-bg-corner\fP.
+  
+.PP
+If you want to leave some border, use the \fB-margin\fP option.  It
+will not only spare some of the border from cropping, but will fill in
+(with what \fBpnmcrop\fP considers the background color) if necessary
+to get up to that size.
+.PP
+If the input is a multi-image stream, \fBpnmcrop\fP processes each
+one independently and produces a multi-image stream as output.  It chooses
+where to crop independently for each image.  So if you start with a stream
+of images of the same dimensions, you may end up with images of differing
+dimensions.  Before Netpbm 10.37 (December 2006), \fBpnmcrop\fP ignored
+all input images but the first.
+.PP
+If you want to chop a specific amount off the side of an image, use
+\fBpamcut\fP.
+.PP
+If you want to add different borders after removing the existing
+ones, use \fBpnmcat\fP or \fBpamcomp\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmcrop\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-white\fP
+Take white to be the background color.  \fBpnmcrop\fP removes
+borders which are white.
+.sp
+You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP,
+\fB-bg-color\fP, and \fB-bg-corner\fP.
+
+.TP
+\fB-black\fP
+Take black to be the background color.  \fBpnmcrop \fP removes
+borders which are black.
+.sp
+You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP,
+\fB-bg-color\fP, and \fB-bg-corner\fP.
+
+.TP
+\fB-bg-color=\fP\fIcolor\fP
+This tells \fBpnmcrop\fP what color is the background - it will crop
+areas of this color.  \fIcolor\fP is a value that would be used as the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP,
+\fB-bg-color\fP, and \fB-bg-corner\fP.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-sides\fP
+Determine the background color from the colors of the four corners
+of the input image.  \fBpnmcrop\fP removes borders which are of the
+background color.
+.sp
+If at least three of the four corners are the same color,
+\fBpnmcrop \fP takes that as the background color.  If not,
+\fBpnmcrop\fP looks for two corners of the same color in the
+following order, taking the first found as the background color: top,
+left, right, bottom.  If all four corners are different colors,
+\fBpnmcrop\fP assumes an average of the four colors as the background
+color.
+.sp
+The \fB-sides\fP option slows \fBpnmcrop\fP down, as it reads the
+entire image to determine the background color in addition to the up
+to three times that it would read it without \fB-sides\fP.
+.sp
+You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP,
+\fB-bg-color\fP, and \fB-bg-corner\fP.
+
+.TP
+\fB-bg-corner=\fP{\fBtopleft\fP|\fBtopright\fP|\fBbottomleft\fP|\fBbottomright\fP
+This option indicates a corner which is background.  \fBpnmcrop\fP will
+use the color of this corner as the background color and crop edges of that
+color.
+.sp
+You may specify at most one of \fB-black\fP, \fB-white\fP, \fB-sides\fP,
+\fB-bg-color\fP, and \fB-bg-corner\fP.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-left\fP
+Remove any left border.
+
+.TP
+\fB-right\fP
+Remove any right border.
+
+.TP
+\fB-top\fP
+Remove any top border.
+
+.TP
+\fB-bottom\fP
+Remove any bottom border.
+
+.TP
+\fB-margin=\fP\fIpixels\fP
+Leave \fIpixels\fP pixels of border.  Expand the border to this size
+if necessary.
+.sp
+This option was new in Netpbm 10.29 (August 2005).
+
+.TP
+\fB-closeness=\fP\fIcloseness_percent\fP
+Any color in the image that is at least this close to the operative
+background color is considered to be background.
+.sp
+You can use this if the image has borders that vary slightly in color, such
+as would be the case in a photograph.  Consider a photograph against a white
+screen.  The color of the screen varies slightly with shading and dirt and
+such, but is still quite distinct in color from the subject of the
+photograph.  \fBpnmcrop\fP will choose some particular shade as the
+background color and if you specify an appropriate \fB-closeness\fP value, it
+will correctly identify all of the screen as background and crop it off.
+.sp
+To implement more complex rules for identifying background, use
+\fB-borderfile\fP.
+.sp
+The default is zero, which means a pixel's color must exactly match the
+background color for the pixel to be considered part of a background border.
+.sp
+This option was new in Netpbm 10.78 (March 2017).  With older Netpbm,
+colors must match exactly.
+
+.TP
+\fB-borderfile=\fP\fIfilename\fP
+Use the image in the file named \fIfilename\fP instead of the input
+image to determine where the borders of the input image are and the
+background color.
+.sp
+Without this option, \fBpnmcrop\fP examines the input image and figures
+out what part of the image is border and what part is foreground (not border),
+as well as the background color.  With this option, \fBpnmcrop\fP finds the
+borders in one image, then uses the those four border sizes (left, right, top,
+bottom) in cropping a different image.  Furthermore, if you use
+\fB-margin\fP to add borders, the color of those borders is the background
+color \fBpnmcrop\fP detects in the border file.
+.sp
+The point of this is that you may want to help \fBpnmcrop\fP to come to a
+different conclusion as to where the borders are and what the background color
+is by preprocessing the input image.  For example, consider an image that has
+speckles of noise in its borders.  \fBpnmcrop\fP isn't smart enough to
+recognize these as noise; it sees them as foreground image.  So \fBpnmcrop\fP
+considers most of your borders to be foreground and does not crop them off as
+you want.  To fix this, run the image through a despeckler such as
+\fBpbmclean\fP and tell \fBpnmcrop\fP to use the despeckled version of the
+image as the \fB-borderfile\fP image, but the original speckled version as
+the input image.  That way, you crop the borders, but retain the true
+foreground image, speckles and all.
+.sp
+The border file must have the same number of images in it as the input
+file; the background color determination for image N of the input is based on
+the image N of the border file.
+.sp
+This option was new in Netpbm 10.29 (August 2005).
+.sp
+Before Netpbm 10.46 (March 2009), the original image and not the
+border file determines the background color.  \fBpnmcrop\fP
+fails if there is no apparent background color in the original image
+(i.e. the corners of the image don't have a common color).
+
+.TP
+\fB-blank-image=\fP{\fBabort\fP|\fBpass\fP|\fBminimize\fP|\fBmaxcrop\fP}
+This determines how \fBpnmcrop\fP handles an image which is entirely
+  background (blank), a case where cropping doesn't make much sense.
+
+
+.TP
+abort
+  
+program fails, with explanatory message (default)
+
+.TP
+pass
+    
+Output image is the same as the input image.
+      \fB-margin\fP has no effect.
+
+.TP
+minimize
+    
+output is a single row, column, or pixel (of the background color).
+      If you crop both vertically and horizontally (the default), it is a
+      single pixel.  If you crop only vertically, a single row, of the
+      original width.  If you crop only horizontally, it is a single column,
+      of the original height.
+.sp
+This is a somewhat incongruous result; the mathematically consistent
+        result of cropping the background from an image that is entirely
+        background would be an image with no pixels at all.  But such a thing
+        does not exist in the Netpbm formats (and you probably wouldn't want
+        it anyway, because whoever processes this output may not tolerate
+        that).
+.sp
+The background can be more than one color when you specify
+      \fB-closeness\fP, so it matters which row, column, or pixel remains.
+      If you crop on the top and not bottom, it is the last row that remains.
+      If you crop on both the top and bottom, it is the middle row that
+      remains.  The other cases follow similarly.
+.sp
+If you specify a margin (\fB-margin\fP), the output image consists
+        entirely of the margins; there is no single row, column, or pixel
+        between the margins.  So with \fB-margin\fP, the incongruity
+        mentioned above does not exist.  But before Netpbm 10.92 (September
+        2020), \fB-margin\fP was ignored with \fB-blank-image=minimize\fP.
+
+.TP
+maxcrop
+    
+This odd function selects a hypothetical cropping which is not even
+      possible, and therefore is valid only with \fB-reportfull\fP or
+      \fB-reportsize\fP.  The cropping that this selects is a crop of the
+      entire image on every side on which you request cropping.  So if you
+      request cropping only on the left, of a 600 pixel wide image, this
+      selects a cropping of 600 pixels from the left and none from the other
+      three sides.  Note that were this cropping actually applied, this would
+      produce an image with no pixels, which is not a valid Netpbm image.  But
+      it gets stranger still if you request cropping on both the right and the
+      left.  In that case, the cropping selected is a cropping of 600 pixels
+      from both the right and left sides, which would leave a negative-width
+      image.
+.sp
+      This is actually useful if you are trying to find a single set of
+      cropping parameters to crop a stream of images.  To do this, you could
+      do a pass with \fB-reportsize\fP and \fB-blank-image=maxcrop\fP to
+      compute the maximum crop for each edge, and then use those numbers in
+      \fB-crop\fIxxx\fP\fP options on a \fBpamcut\fP pass to do the crop.
+      In this scenario, any all-background (blank) images would have no effect
+      on the cropping parameters you compute.  If you do this, you must give
+      special consideration to a stream with nothing but blank images.
+
+
+.sp
+\fB-margin\fP is always ignored when the image is all background.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-reportfull\fP
+With this option, \fBpnmcrop\fP does not actually crop anything.  Instead, it
+just prints to Standard Output parameters of the cropping it would have done.
+The output is a single line per image, like in this example:
+
+.nf
+  
+     0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0
+  
+
+.fi
+.sp
+The line is composed of the following blank-delimited tokens:
+
+
+.IP \(bu
+how many pixels would be cropped or padded on the left.  This is
+    a signed decimal number, where + means pad and - means crop.  If there
+    would be no change, this is unsigned zero.
+
+.IP \(bu
+same, but for the right side.
+
+.IP \(bu
+same, but for the top.
+
+.IP \(bu
+same, but for the bottom.
+
+.IP \(bu
+the resulting image width in pixels, in decimal.
+
+.IP \(bu
+the resulting image height in pixels, in decimal.
+
+.IP \(bu
+The color \fBpnmcrop\fP took to be the background color, like
+   'rgb-255:10/0/255' (This is a format recognized by
+   the 
+.UR libnetpbm_image.html#colorname
+\fBpnm_parsecolor()\fP
+.UE
+\&
+   library routine).  The maxval in the color specification is the maxval of
+   the image.
+
+.IP \(bu
+The closeness value (see \fB-closeness\fP option) \fBpnmcrop\fP
+   used, in floating point decimal.
+
+.sp
+You cannot use \fB-borderfile\fP together with this option.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-reportsize\fP
+This is like \fB-reportfull\fP, but reports only the left, right, top,
+bottom, width, and height.
+.sp
+You cannot use \fB-borderfile\fP together with this option.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-verbose\fP
+Print on Standard Error information about the processing,
+including exactly how much is being cropped off of which sides.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcut" (1)\c
+\&,
+.BR "pamfile" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmcrop.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmcut.1 b/upstream/mageia-cauldron/man1/pnmcut.1
new file mode 100644
index 00000000..6f3631bf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmcut.1
@@ -0,0 +1,37 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmcut User Manual" 0 "02 February 2009" "netpbm documentation"
+
+.SH NAME
+
+pnmcut - replaced by pamcut
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmcut\fP was obsoleted by
+.BR "\fBpamcut\fP" (1)\c
+\&, introduced with Netpbm 9.20 (May
+2001).  \fBpamcut\fP is backward compatible with \fBpnmcut\fP, plus
+adds many additional functions, including the ability to process PAM
+images.
+.PP
+\fBpnmcut\fP remained in the Netpbm package until Netpbm 10.46 (March
+2009) because of hopes that it had fewer bugs than \fBpamcut\fP because of its
+age.  But now it would just be clutter.
+.PP
+In Netpbm before 9.20, use the manual for \fBpamcut\fP with
+\fBpnmcut\fP.  Features that are in \fBpamcut\fP but not \fBpnmcut\fP
+are indicated by statements that they didn't exist before 9.20.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmcut.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmdepth.1 b/upstream/mageia-cauldron/man1/pnmdepth.1
new file mode 100644
index 00000000..1397fc3f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmdepth.1
@@ -0,0 +1,35 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmdepth User Manual" 0 "06 March 2006" "netpbm documentation"
+
+.SH NAME
+
+pnmdepth - replaced by pamdepth
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Starting with Netpbm 10.32 (February 2006), \fBpnmdepth\fP is
+obsolete.  Use
+.BR "\fBpamdepth\fP" (1)\c
+\& instead.
+
+\fBpamdepth\fP is backward compatible with \fBpnmdepth\fP.  You can
+use the \fBpamdepth\fP manual for \fBpnmdepth\fP as long as you ignore
+features that were added after Netpbm 10.31.
+.PP
+For backward compatibility, the name 'pnmdepth' continues to exist
+as an alias for 'pamdepth'.  But because of a bug, that name doesn't work
+in Netpbm 10.32.  You have to fix the symbolic link.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmdepth.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmenlarge.1 b/upstream/mageia-cauldron/man1/pnmenlarge.1
new file mode 100644
index 00000000..022b3d29
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmenlarge.1
@@ -0,0 +1,28 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmenlarge User Manual" 0 "September 2004" "netpbm documentation"
+
+.SH NAME
+pnmenlarge - replaced by pamenlarge
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmenlarge\fP was replaced in Netpbm 10.25 (October 2004) by
+.BR "pamenlarge" (1)\c
+\&.
+.PP
+\fBpamenlarge\fP is backward compatible with \fBpnmenlarge\fP,
+but works on PAM images too.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmenlarge.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmfile.1 b/upstream/mageia-cauldron/man1/pnmfile.1
new file mode 100644
index 00000000..c6b5ea78
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmfile.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmfile User Manual" 0 "September 2002" "netpbm documentation"
+
+.SH NAME
+
+pnmfile - replaced by pamfile
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmfile\fP was replaced in Netpbm 10.9 (September 2002) by
+.BR "pamfile" (1)\c
+\&.
+.PP
+\fBpamfile\fP is backward compatible with \fBpnmfile\fP, but works on
+PAM images too.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmfile.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmflip.1 b/upstream/mageia-cauldron/man1/pnmflip.1
new file mode 100644
index 00000000..c0b89dda
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmflip.1
@@ -0,0 +1,42 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmflip User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+
+pnmflip - replaced by pamflip
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmflip\fP was replaced in Netpbm 10.13 (December 2002) by
+.BR "pamflip" (1)\c
+\&.
+.PP
+\fBpamflip\fP is mostly backward compatible with \fBpnmflip\fP,
+but works on PAM images too.
+.PP
+One way \fBpamflip\fP is not backward compatible with \fBpnmflip\fP
+is that \fBpnmflip\fP lets you specify any number of basic flip options,
+whereas \fBpamflip\fP requires exactly one.  (\fBpamflip\fP provides
+the \fB-xform\fP option for requesting multiple transformations, though).
+Because of this incompatibility, \fBpnmflip\fP still exists as a
+separate program, and all it does is translate its options to \fBpamflip\fP
+style and run \fBpamflip\fP.
+.PP
+You should not make any new use of \fBpnmflip\fP and if you modify an
+existing use, you should upgrade to \fBpamflip\fP.  But note that if you
+write a program that might have to be used with very old
+Netpbm, \fBpnmflip\fP is the only way to do that.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmflip.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmgamma.1 b/upstream/mageia-cauldron/man1/pnmgamma.1
new file mode 100644
index 00000000..152dc7ad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmgamma.1
@@ -0,0 +1,339 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmgamma User Manual" 0 "30 June 2007" "netpbm documentation"
+
+.SH NAME
+pnmgamma - perform gamma adjustment on a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBpnmgamma\fP
+{
+ \fB-bt709tolinear\fP | 
+ \fB-lineartobt709\fP |
+ \fB-bt709tosrgb\fP | 
+ \fB-srgbtobt709\fP
+}
+[\fB-gamma=\fP\fIfloat\fP]
+[\fB-rgamma=\fP\fIfloat\fP]
+[\fB-ggamma=\fP\fIfloat\fP]
+[\fB-bgamma=\fP\fIfloat\fP]
+
+[\fIpnmfile\fP]
+.PP
+\fBpnmgamma \fP
+[
+ \fB-bt709ramp\fP |
+ \fB-srgbramp\fP 
+]
+[\fB-ungamma\fP]
+[{\fIgamma\fP | \fIredgamma\fP \fIgreengamma\fP \fIbluegamma\fP}
+[\fIpnmfile\fP]]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBPnmgamma\fP performs gamma adjustment on pseudo-PNM images.
+.PP
+The PPM format specification specifies that certain sample values
+in a file represent certain light intensities in an image.  In
+particular, they specify that the sample values are directly
+proportional to luminance as defined by ITU-R Recommendation BT.709.
+BT.709 luminance as a function of radiance is a power function
+modified with a linear ramp near black.
+.PP
+However, people sometimes work with approximations of PPM and PGM
+where the sample values represent intensity in different ways:
+.PP
+In one common variation, the sample value is directly proportional
+to radiance (often called "linear intensity").
+.PP
+Another popular variation is to make the samples proportional to
+luminance as defined by the International Electrotechnical Commission
+(IEC) SRGB standard.  The SRGB gamma transfer function is like the
+BT.709 one except with different constants in it.
+.PP
+Note that SRGB is often spelled "sRGB".  In this
+document, we use standard English typography, though, which doesn't
+allow for that kind of capitalization.
+.PP
+\fBpnmgamma\fP allows you to manipulate the gamma transfer
+function, thus working with and/or creating pseudo-PPM files that are
+useful for various things.
+.PP
+For example, if you feed a true PPM to \f(CWpnmgamma -bt709tolinear
+\fP, you get as output a file which is PPM in every respect except
+that the sample values are radiances.  If you feed such a file to
+\f(CWpnmgamma -linearto709\fP, you get back a true PPM.
+.PP
+The situation for PGM images is analogous.  And \fBpnmgamma\fP
+treats PBM images as PGM images.
+.PP
+When you feed a radiance-proportional pseudo-PPM image to a display
+program that expects a true PPM, the display appears darker than it
+should, so \fBpnmgamma\fP has the effect of lightening the image.
+When you feed a true PPM to a display program that expects
+radiance-proportional sample values, and therefore does a gamma
+adjustment of its own on them, the display appears lighter than it
+should, so \fBpnmgamma\fP with a gamma value less than one (the
+multiplicative inverse of whatever gamma value the display program
+uses) has the effect of darkening the image.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+The form of the parameters depends on whether you're using the old
+syntax or the new syntax.  With the old syntax, the parameters are
+a mixture of gamma values and the input file name.  With the new
+syntax, the only parameter is the input file name and you specify gamma
+values with option.
+.PP
+You use the old syntax if you specify \fB-bt709ramp\fP (or
+its synonym \fB-cieramp\fP) or \fB-srgramp\fP or if you don't specify
+any transfer function at all (and thus default to a simple exponential).
+Otherwise, you use the new syntax.
+.PP
+With the old syntax, you may specify a single gamma value or 3
+separate gamma values (red, green, and blue) or no gamma values.  In
+any case, the meanings of those parameters is the same as the more
+modern \fB-gamma\fP, \fB-rgamma\fP, \fB-ggamma\fP, and
+\fB-bgamma\fP options described below.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmgamma\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-bt709tolinear\fP
+Convert the image from BT.709 luminance to radiance.  I.e. convert
+from true PPM or PGM to a radiance-linear variation that can be used
+with certain tools that need it.
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-lineartobt709\fP
+Convert the image from radiance to BT.709 luminance.  I.e. convert
+to true PPM or PGM from a radiance-linear variation.
+.sp
+You get true BT.709 (ergo true PPM or PGM) only if you use the
+default gamma value (i.e. don't specify \fB-gamma\fP, etc.).
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-bt709tosrgb\fP
+Convert the image from BT.709 luminance to SRGB luminance.
+I.e. convert from true PPM or PGM to an SRGB-based variation that is
+required by certain tools and display devices.
+.sp
+You get true SRGB only if you use the default gamma value
+(i.e. don't specify \fB-gamma\fP, etc.).
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-srgbtobt709\fP
+Convert the image from SRGB luminance to BT.709 luminance.
+I.e. convert to true PPM or PGM from an SRGB-based variation.
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-bt709ramp\fP
+Same as \fB-lineartobt709\fP, but using the old syntax.
+.sp
+This option was renamed in Netpbm 10.32 (February 2006).  Before that,
+its name is \fB-cieramp\fP.
+
+.TP
+\fB-cieramp\fP
+This is an obsolete synonym for \fB-bt709ramp\fP.
+.sp
+The name of this option comes from a former belief that this was a
+standard of CIE (International Commission On Illumination), but it now
+(August 2005) looks like it never was.
+
+.TP
+\fB-srgbramp \fP
+Convert the image from radiance to SRGB luminance.  Note that it is
+true SRGB only if you use the default gamma value (i.e. don't specify
+any gamma parameters).
+.sp
+This is an old syntax option.  There is no equivalent in the new
+syntax because it really shouldn't be a function of \fBpnmgamma\fP at
+all.  It exists solely for backward compatibility.  The reason it
+shouldn't exist is that the way to do this conversion consistent with
+the Netpbm philosophy is do a \fB-lineartobt709\fP followed by a
+\fB-bt709tosrgb\fP.  It's exactly analogous to the way you have to
+convert from PNG to TIFF by doing a \fBpngtopam\fP followed by a
+\fBpnmtotiff\fP.  The \fB-srgbramp\fP option actually dates to
+before there was a standard definition of what the sample values of a
+Netpbm image measure, and \fBpnmgamma\fP considered radiance-linear
+to be the proper intermediate format.
+
+.TP
+\fB-ungamma\fP
+Apply the inverse of the specified transfer function (i.e. go from
+gamma-adjusted luminance to radiance).
+.sp
+This is valid only with \fB-bt709ramp\fP (aka \fB-cieramp\fP),
+\fB-srgbramp\fP, and the default exponential transfer function.
+
+.TP
+\fB-gamma=\fP\fIfloat\fP
+This specifies the gamma value to use in the transfer function.  All
+of the transfer functions involve an exponent, and the gamma value is that
+exponent.
+.sp
+The standards specify a particular gamma value.  If you use anything
+else, you are varying from the standard.
+.sp
+The default is the standard value.  For the simple exponential transfer
+function (which is not a standard), the default is 2.2.
+.sp
+In the \fB-bt709tosrgb\fP and \fB-srgbtobt709\fP conversions
+there are \fItwo\fP exponents.  \fB-gamma\fP affects the
+"to" function; the "from" function always uses the
+standard gamma value.
+.sp
+If you specify one of the component-specific options (\fB-rgamma\fP,
+etc.), that overrides the \fB-gamma\fP value.
+.sp
+With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP,
+or the default exponential transfer function, you can't actually use
+this option, but you specify the same thing with 
+.UR #parameters
+parameters.
+.UE
+\&
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-rgamma=\fP\fIfloat\fP
+.TP
+\fB-ggamma=\fP\fIfloat\fP
+.TP
+\fB-bgamma=\fP\fIfloat\fP
+These options are just like \fB-gamma\fP, except they specify the
+value for a particular one of the color components.
+.sp
+If you don't specify this option for a particular color component,
+the default is the \fB-gamma\fP value (or \fB-gamma\fP's default if
+you didn't specify that either).
+.sp
+With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP,
+or the default exponential transfer function, you can't actually use
+this option, but you specify the same thing with 
+.UR #parameters
+parameters.
+.UE
+\&
+.sp
+This option was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+This is the maxval of the output image.  By default, the maxval of
+the output is the same as that of the input.
+.sp
+Because the transformation is not linear, you need a greater maxval
+in the output in order not to lose any information from the input.
+For example, if you convert to radiance-linear sample values with 
+\f(CW-ungamma -bt709ramp\fP and default gamma value, and your maxval is
+255 on both input and output, 3 different input sample values all
+generate output sample value 254.  In order to have a different output
+sample value for each input sample value, you would need an output
+maxval at least 3 times the input maxval.
+.sp
+This option was new in Netpbm 10.32 (February 2006).  Before that,
+you can achieve the same result by increasing the maxval of the input
+or decreasing the maxval of the output using \fBpamdepth\fP.
+
+
+
+.UN gamma
+.SH WHAT IS GAMMA?
+.PP
+A good explanation of gamma is in Charles Poynton's Gamma FAQ at
+.BR "
+http://www.poynton.com/GammaFAQ.html" (1)\c
+\& and Color FAQ at
+.BR "
+http://www.poynton.com/ColorFAQ.html" (1)\c
+\&.
+.PP
+In brief: The simplest way to code an image is by using sample
+values that are directly proportional to the radiance of the color
+components.  Radiance is a physical quantification based on the amount
+of power in the light; it is easily measurable in a laboratory, but
+does not take into account what the light looks like to a person.  It
+wastes the sample space because the human eye can't discern
+differences between low-radiance colors as well as it can between
+high-radiance colors.  So instead, we pass the radiance values
+through a transfer function that makes it so that changing a sample
+value by 1 causes the same level of perceived color change anywhere in
+the sample range.  We store those resulting values in the image file.
+That transfer function is called the gamma transfer function and the
+transformation is called gamma adjusting.
+.PP
+The gamma-adjusted value, proportional to subjective brightness,
+are known as the luminance of the pixel.
+.PP
+There is no precise objective way to measure luminance, since it's
+psychological.  Also, perception of brightness varies according to a
+variety of factors, including the surrounding in which an image is
+viewed.  Therefore, there is not just one gamma transfer function.
+.PP
+Virtually all image formats, either specified or de facto, use
+gamma-adjusted values for their sample values.
+.PP
+What's really nice about gamma is that by coincidence, the inverse
+function that you have to do to convert the gamma-adjusted values
+back to radiance is done automatically by CRTs.  You just apply a
+voltage to the CRT's electron gun that is proportional to the
+gamma-adjusted sample value, and the radiance of the light that comes
+out of the screen is close to the radiance value you had before you
+applied the gamma transfer function!
+.PP
+And when you consider that computer video devices usually want you
+to store in video memory a value proportional to the signal voltage
+you want to go to the monitor, which the monitor turns into a
+proportional drive voltage on the electron gun, it is really
+convenient to work with gamma-adjusted sample values.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Bill Davidson and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmgamma.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmhisteq.1 b/upstream/mageia-cauldron/man1/pnmhisteq.1
new file mode 100644
index 00000000..4e841c2f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmhisteq.1
@@ -0,0 +1,222 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmhisteq User Manual" 0 "22 March 2015" "netpbm documentation"
+
+.SH NAME
+
+pnmhisteq - histogram equalize a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmhisteq\fP
+
+[\fB-gray\fP]
+
+[\fB-noblack\fP]
+[\fB-nowhite\fP]
+
+[\fB-rmap\fP \fIpgmfile\fP]
+
+[\fB-wmap\fP \fIpgmfile\fP]
+
+[\fB-verbose\fP]
+
+[\fIpnmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmhisteq\fP increases the contrast of a PGM or PPM image
+through the technique of "histogram equalization."[1]
+.PP
+\fBpnmhisteq\fP computes a histogram of the luminosity of the
+pixels in the image.  It then calculates a mapping between each
+luminosity and a new luminosity such that it spreads out intensity
+levels around histogram peaks and compresses them at troughs.  I.e.
+it moves pixels around in the histogram so as to make it flat.  It
+applies that mapping to the input image to produce the output image.
+The effect of this is that the image has equal numbers of pixels at each
+possible intensity level, which means it uses the available levels of
+intensity more efficiently and thereby has more visible detail.
+.PP
+Mathematically, the luminosity mapping is this: Assume the pixels
+are sorted by luminosity into \fIB\fP buckets numbered from 0 (lowest
+luminosity) to \fIB\fP-1.  \fIN[i]\fP is the number of pixels in
+bucket \fIi\fP.  \fIT\fP is the total number of pixels (sum of
+\fIN[i]\fP over all \fIi\fP).  \fIW\fP is the luminosity of white.
+.PP
+\fBpnmhisteq\fP replaces an input pixel whose luminosity falls into
+bucket \fIj\fP with one whose luminosity is:
+
+.nf
+
+      j
+     ---
+     \e
+      > (N[i] / T) * W
+     /
+     ---
+     i=0
+
+.fi
+.PP
+Considering a grayscale image for simplicity, this means that
+pixels in the most luminous bucket become white.  Pixels in the 10th
+per centile of luminosity become 10% of white.
+.PP
+\fBpnmhisteq\fP maps a single luminosity in the input to a single
+luminosity in the output.  That means if pixels A and B both have luminosity
+\&.2 in the input, and pixel A has luminosity .4 in the output, pixel B also has
+luminosity .4 in the output.  And since the luminosities in the input are not
+continuous, the luminosities in the output aren't either and \fBpnmhisteq\fP
+doesn't meet the ideal of having exactly the same number of pixels of each
+luminosity in the output.
+.PP
+If you're processing a related set of images, for example frames of
+an animation, it's generally best to apply the same luminosity mapping
+to every frame, since otherwise you'll get distracting frame-to-frame
+changes in the brightness of objects.  \fBpnmhisteq\fP's \fB-wmap\fP
+option allows you to save, as a PGM image, the luminosity map it
+computes from an image.  The \fB-rmap\fP option causes \fBpnmisteq\fP
+to use such an image as its luminosity map.
+.PP
+So you can run \fBpnmhisteq\fP with \fB-wmap\fP on a composite
+you created with \fBpnmcat\fP of the images you intend to process.
+Then, you can run \fBpnmisteq\fP with \fB-rmap\fP on each of the
+individual images, using the luminosity map you generated from the
+composite.
+.PP
+Use \fBpnmhistmap\fP to see the result.  Run a color image through
+\fBppmtopgm\fP first so that you see a histogram of the luminosity instead of
+histograms of the three color components.  It should generally show a flat
+histogram.  But because of the quantization effects described above, you might
+see high bars interleaved with low bars, with the local average being flat.
+To see local averages, use the \fB-width\fP option of \fBpnmhistmap\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmhisteq\fP recognizes the following
+command line options:
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB-gray\fP
+When processing a color image, only gray pixels (those with identical
+red, green, and blue values) are included in the histogram and
+modified in the output image.  This is a special purpose option
+intended for images where the actual data are gray scale, with color
+annotations you don't want modified.  Weather satellite images that
+show continent outlines in color are best processed using this option.
+The option has no effect when the input is a graymap.
+
+.TP
+\fB-noblack\fP
+Do not include black pixels in the equalization.  The black pixels in the
+output are exactly the black pixels in the input and the number of black
+pixels does not affect the color of any other pixels.
+.sp
+Sometimes, black isn't as much a color as a background or annotation for
+the real colors, so you want to treat it specially this way.  Think of a
+picture of stars, which is nearly all black, but with lots of stars of
+different brightness.  You want to change the brightnesses of the stars to
+maximize contrast between them, but if you considered the blackness to be
+significant, all the stars would end up close to full white.
+.sp
+This option was new in Netpbm 10.70 (March 2015).
+
+.TP
+\fB-nowhite\fP
+.sp
+Same as \fB-noblack\fP, but for the white pixels.
+.sp
+This option was new in Netpbm 10.70 (March 2015).
+
+.TP
+\fB-rmap\fP \fImapfile\fP
+Process the image using the luminosity map specified by the PGM
+file \fImapfile\fP.
+
+The PGM image, usually created by an earlier run of \fBpnmhisteq\fP
+with the \fB-wmap\fP option, contains a single row with number of
+columns equal to the maxval (greatest intensity value) of the image
+plus one.  Each pixel in the image is transformed by looking up its
+luminosity in the corresponding column in the map file (column number
+= luminosity) and changing it to the value given by that column.
+
+.TP
+\fB-wmap\fP \fImapfile\fP
+Creates a PGM file \fImapfile\fP, containing the luminosity map
+computed from the histogram of the input image.  This map file can be
+read on subsequent runs of \fBpnmhisteq\fP with the \fB-rmap\fP
+option, allowing a group of images to be processed with an identical
+map.
+
+.TP
+\fB-verbose\fP
+Prints the histogram and luminosity map on Standard Error.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+Histogram equalization is effective for increasing the visible
+detail in scientific imagery and in some continuous-tone pictures.  It
+is often too drastic, however, for scanned halftone images, where it
+does an excellent job of making halftone artifacts apparent.  You
+might want to experiment with \fBpnmnorm\fP and \fBpnmgamma\fP for
+more subtle contrast enhancement.
+.PP
+The luminosity map file supplied by the \fB-rmap\fP option must
+have the same maxval as the input image.  This is always the case when
+the map file was created by the \fB-wmap\fP option of
+\fBpnmhisteq\fP.  If this restriction causes a problem, simply adjust
+the maxval of the map with \fBpamdepth\fP to agree with the input
+image.
+.PP
+If the input is a PBM file (on which histogram equalization is an
+identity operation), the only effect of passing the file through
+\fBpnmhisteq\fP will be the passage of time.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmnorm" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+
+.TP
+[1]
+Russ, John C.  The Image Processing Handbook.  Boca Raton: CRC
+Press, 1992.  Pages 105-110.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmhisteq.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmhistmap.1 b/upstream/mageia-cauldron/man1/pnmhistmap.1
new file mode 100644
index 00000000..193e2ea4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmhistmap.1
@@ -0,0 +1,192 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmhistmap User Manual" 0 "13 July 2009" "netpbm documentation"
+
+.SH NAME
+pnmhistmap - draw a histogram for a PGM or PPM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmhistmap\fP
+
+[\fB-red\fP] [\fB-green\fP] [\fB-blue\fP]
+
+[\fB-black\fP] [\fB-white\fP]
+
+[\fB-max\fP \fIN\fP]
+
+[\fB-lval\fP] [\fB-rval\fP]
+
+[\fB-height\fP] [\fB-width\fP]
+
+[\fB-dots\fP]
+
+[\fB-verbose\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmhistmap\fP reads a PNM image as input and produces an image
+showing a histogram of the color (or gray) values in the input.  A PGM
+input results in a PBM output.  A PPM input results in a PPM output
+with three overlaid histograms: a red one for the red input, a green
+one for the green input, and a blue one for the blue input.
+.PP
+For example, from the following image produces the following histogram:
+.PP
+.B image
+.IMG -C testimg.png
+.B histogram from image
+.IMG -C testimg_histbar.png
+.PP
+If the input is PBM, \fBpnmhistmap\fP produces an error message
+and no output image.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmhistmap\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-red\fP
+.TP
+\fB-green\fP
+.TP
+\fB-blue\fP
+Include the indicated color component in the output.  If you
+specify none of these, \fBpnmhistmap\fP include all three.
+.sp
+These options are meaningless if the input is PGM.
+.sp
+These options were new in Netpbm 10.26 (January 2005).  Before
+that, \fBpnmhistmap\fP always included all three color components.
+
+.TP
+\fB-dots\fP
+Plot the histogram as dots.  By default, \fBpnmhistmap\fP plots
+bars.
+.sp
+Example of dots:.B -dots example
+.IMG -C testimg_histdot.png
+.sp
+This option was new in Netpbm 10.26 (January 2005).  Before that,
+\fBpnmhistmap\fP always plotted bars.
+
+.TP
+\fB-lval\fP \fIminpixval\fP
+.TP
+\fB-rval\fP \fImaxpixval\fP
+These options specify the range of intensity values to include.
+\fBpnmhistmap\fP ignores intensities less than \fIminpixval\fP and
+greater than \fImaxpixval\fP.  So the left side of the histogram
+corresponds to \fIminpixval\fP and the right side corresponds to
+\fImaxpixval\fP.
+.sp
+By default, \fBpnmhistmap\fP plots the entire possible range: zero
+to the maxval.
+.sp
+These options were new in Netpbm 10.26 (January 2005).  Before that,
+\fBpnmhistmap\fP always plotted from zero to the maxval.
+
+.TP
+-height
+.TP
+-width
+These options specify the dimensions, in pixels of the histogram image.
+.sp
+The default height is 200 pixels.
+.sp
+The default width is one pixel for each plotted intensity value (so it's 
+controlled by the maxval of the image and the \fB-lval\fP and \fB-rval\fP
+options).  The "count buckets" in the histogram are always
+one pixel wide.  If you specify a width less than the number of plotted
+intensity values, a bucket represents more than one intensity value.
+If you specify a width greater that the number of plotted intensity values,
+some buckets represent no color (the count is zero).
+.sp
+This option was new in Netpbm 10.26 (January 2005).  Before that,
+the dimensions were always what the default is today.
+
+.TP
+\fB-black \fP
+Ignore the count of black pixels when scaling the histogram.
+
+.TP
+\fB-white\fP
+Ignore the count of white pixels when scaling the histogram.
+.sp
+The -black and -white options, which can be used separately or
+together, are useful for images with a large percentage of pixels
+whose value is zero or 255, which can cause the remaining histogram
+data to become unreadably small.  Note that, for color inputs, these
+options apply to all colors; if, for example, the input has a large
+number of bright-red areas, you will probably want to use the -white
+option.
+
+.TP
+\fB-max N\fP
+Force the scaling of the histogram to use N as the largest-count value.
+This is useful for inputs with a large percentage of single-color pixels
+which are not black or white.
+
+.TP
+\fB-verbose\fP
+Report the progress of making the histogram, including the largest-count
+value used to scale the output.
+
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBpnmhistmap\fP assumes maxval is always 255.  Images with a
+smaller maxval will only use the lower-value side of the histogram.
+You can overcome this either by piping the input through
+\fBpamdepth\fP or by cutting and scaling the lower-value side of the
+histogram.  Neither is a particularly elegant solution to the problem.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmhist" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Wilson H. Bent. Jr. (\fIwhb@usc.edu\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmhistmap.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmindex.1 b/upstream/mageia-cauldron/man1/pnmindex.1
new file mode 100644
index 00000000..a676133a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmindex.1
@@ -0,0 +1,148 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmindex User Manual" 0 "14 November 2015" "netpbm documentation"
+
+.SH NAME
+pnmindex - build a visual index of a bunch of PNM images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmindex\fP
+
+[\fB-size=\fP\fIN\fP]
+
+[\fB-across=\fP\fIN\fP]
+
+[\fB-colors=\fP\fIN\fP]
+
+[\fB-black\fP]
+
+[\fB-title=\fP\fItitle\fP]
+
+[\fB-quant\fP|\fB-noquant\fP]
+
+\fIpnmfile\fP ...
+.PP
+You can use the minimum unique abbreviation of the options.  You can use
+two hyphens instead of one.  You can separate an option name from its value
+with white space instead of an equals sign.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpnmindex\fP creates an index image containing thumbnail (small)
+versions of a bunch of PNM files you supply.  (Akin to a photographic
+"contact sheet").
+.PP
+\fBpnmindex\fP labels each thumbnail and, optionally, contains a
+title.
+.PP
+If you just want to concatenate some images together in a grid, use
+\fBpamundice\fP for that.
+.PP
+If you want to take apart the image you generated with \fBpnmindex\fP,
+use \fBpamdice\fP or \fBpamcut\fP.
+.PP
+The program can generate large temporary files.  By default, these go in
+directory \fB/tmp\fP, but you can usse the \fBTMPDIR\fP environment variable
+to have them somewhere else.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmindex\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-size=\fP\fIN\fP
+The size of each thumbnail.  The image is scaled to fit maximally
+inside a \fIN\fP x \fIN\fP pixel box without changing its aspect
+ratio.  Default is 100.
+
+.TP
+\fB-across=\fP\fIN\fP
+The number of thumbnails in each row.  Default is 6.
+
+.TP
+\fB-colors=\fP\fIN\fP
+The maximum number of colors allowed in the overall image.  If it
+would otherwise have more colors than these, \fBpnmindex\fP quantizes
+the result.  The default is 256.
+.sp
+However, this value is meaningless if you specify the
+\fB-noquant\fP option.
+
+.TP
+\fB-black\fP
+This controls the color of the padding between the images;
+normally it's white and the labels are black lettering on white
+background, but the \fB-black\fP option reverses this.
+
+.TP
+\fB-title=\fP\fItitle\fP
+Specifies a title top place at the top of the image.
+Default is no title.
+
+.TP
+\fB-quant\fP
+Enables quantization (to the number of colors specified by
+\fB-colors\fP).  Quantization is on by default but you can disable
+it with \fB-noquant.\fP
+
+.TP
+\fB-noquant\fP
+See \fB-quant\fP.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamscale" (1)\c
+\&,
+.BR "pamcat" (1)\c
+\&,
+.BR "pbmtext" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamdice" (1)\c
+\&,
+.BR "pamundice" (1)\c
+\&,
+.BR "pnmtile" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1991 by Jef Poskanzer.
+.PP
+\fB-title\fP and \fB-noquant\fP added 2000 by John Heidemann.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmindex.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnminterp.1 b/upstream/mageia-cauldron/man1/pnminterp.1
new file mode 100644
index 00000000..d5377623
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnminterp.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnminterp User Manual" 0 "December 2001" "netpbm documentation"
+
+.SH NAME
+
+pnminterp - replaced by pamstretch
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnminterp\fP was replaced in Netpbm 9.21 (December 2001) by
+.BR "pamstretch" (1)\c
+\&.
+.PP
+\fBpamstretch\fP is backward compatible with \fBpnminterp\fP, but
+also recognizes PAM input, including that with a transparency channel.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnminterp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnminvert.1 b/upstream/mageia-cauldron/man1/pnminvert.1
new file mode 100644
index 00000000..21392241
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnminvert.1
@@ -0,0 +1,61 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnminvert User Manual" 0 "08 August 1989" "netpbm documentation"
+
+.SH NAME
+
+pnminvert - invert a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnminvert\fP
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnminvert\fP reads a PNM image as input, inverts it black for
+white, and produces a PNM image as output.
+.PP
+If the image is grayscale, \fBpnminvert\fP replaces a pixel with
+one of complementary brightness, i.e. if the original pixel has gamma-adjusted
+gray value G, the output pixel has gray value maxval - G.
+.PP
+If the image is color, \fBpnminvert\fP inverts each individual RGB
+component the same as for a grayscale image.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpnminvert\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnminvert.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmmargin.1 b/upstream/mageia-cauldron/man1/pnmmargin.1
new file mode 100644
index 00000000..aae3634c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmmargin.1
@@ -0,0 +1,114 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmmargin User Manual" 0 "12 November 2014" "netpbm documentation"
+
+.SH NAME
+
+pnmmargin - add borders to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmmargin\fP
+[\fB-white\fP|\fB-black\fP|\fB-color\fP \fIcolorspec\fP] \fIsize\fP
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmmargin\fP adds a border around a PNM image.
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+\fIpnmfile\fP is the name of the input file.  If you don't specify this
+argument, \fBpnmmargin\fP reads the input image from its Standard Input.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-plain\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmmargin\fP recognizes the following
+command line options:
+.PP
+You can specify the border color with the \fB-white\fP,
+\fB-black\fP, and \fB-color\fP options.  If you don't specify a color, the
+program makes a guess.
+.PP
+The value of \fB-color\fP is like the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.PP
+The \fB-plain\fP common option was implemented beginning with Netpbm
+version 10.40 (September 2007).
+.PP
+The \fB-quiet\fP common option is not implemented.
+
+.UN notes
+.SH NOTES
+.PP
+To remove a border of a specified size from an image, use
+\fBpamcut\fP.  \fBpnmcrop\fP also removes borders, but determines by itself
+what is border and what is subject.
+.PP
+For lower level control, including to add different size borders to
+different sides of the image, look at \fBpnmcat\fP.
+.PP
+If all you're trying to do is get the image up to a certain required
+size, \fBpamcut\fP may be what you want.
+.PP
+\fBpnmpad\fP does essentially the same thing, but gives you more control
+over the individual margins and does only black and white margins.
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pamcut" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmcrop" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmcat" (1)\c
+\&
+.IP \(bu
+
+.BR "pnmpad" (1)\c
+\&
+.IP \(bu
+
+.BR "pnm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmmargin.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmmercator.1 b/upstream/mageia-cauldron/man1/pnmmercator.1
new file mode 100644
index 00000000..3ef7c7d2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmmercator.1
@@ -0,0 +1,154 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "PnmMercator User Manual" 0 "October 2009" "netpbm documentation"
+
+.SH NAME
+pnmmercator - transform a worldmap from rectangular projection to Mercator
+projection and vice-versa
+
+.UN synopsis
+.SH SYNOPSIS
+\fBpnmmercator\fP
+[\fB-inverse\fP]
+[\fB-nomix\fP]
+[\fB-[v]verbose\fP]
+[\fB\fIfilename\fP\fP]
+.PP
+Minimum unique abbreviation of option is acceptable. 
+You may use double hyphens instead of single hyphen to denote options.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+The \fBpnmmercator\fP utility, converts a rectangular projection worldmap
+to a Mercator projection format, as used for maps.google.com and many other
+online maps.  The map used as input for \fBpnmmercator\fP must have rows for
+-90 to 90 degrees latitude and columns for -180 to +180 degrees longitude. The
+file will typically be twice as wide as high, but this is not a
+requirement. The output file will be using the 
+.UR http://en.wikipedia.org/wiki/Mercator_projection
+Mercator projection
+.UE
+\& and will get double the height of the input file.
+.PP
+Maps using the Mercator projection are stretched more the closer a row is
+to the North or South Pole. The last few degrees (> 85 or < -85 degrees)
+are not part of a Mercator map at all because they would be stretched too much
+and the rows close to the edge will show banding, because they originate from
+the same row in the original map.
+.PP
+To overcome this, the program will by default do interpolation of pixel
+colors, which will eliminate the banding effect, but will cause some blurring
+of the output. With the -nomix option, this interpolation of colors isn't
+applied. You can obtain the highest quality output by starting with an input
+map of high resolution, so that you can follow the \fBpnmmercator\fP
+transformation with a \fBpamscale\fP reduction in size.
+.PP
+This program can also convert a Mercator projection map back to a
+rectangular projection based.  As said, the Mercator map doesn't have
+information about the latitudes close to the poles.  Therefore the top rows in
+the output image will be identical and copied from the row corresponding with
+latitude of 85 degrees. The same at the bottom of the map.
+.PP
+Pnmmercator doesn't have any provision for scaling the image. You can scale
+by piping the output of the program through Netpbm programs such as
+\fBpamscale\fP.
+.PP
+You can find maps to be used as input at
+.BR "flatplanet.sourceforge.net" (1)\c
+\&
+or 
+.UR http://www.evl.uic.edu/pape/data/Earth/
+uic.edu/pape
+.UE
+\&.
+.PP
+The point of a Mercator projection map is that compass directions work on
+it.  If you draw a straight line northeast from some point on the Mercator
+map, the line traces the course you would sail if you sailed a compass bearing
+of northeast from that spot.  Naturally, primitive navigators appreciated
+that.  The biggest drawback of Mercator is that areas to the north and south
+appear much larger than they are in real life.  For example, Greenland appears
+to be larger than South America even though it only a ninth as large.  Note
+that areas away from the equator are stretched north-south as well as
+east-west.
+.PP
+A rectangular projection is one where vertical distance is proportional to
+angular latitude distance of the represented area and horizontal distance is
+proportional to angular longitude.
+
+
+.UN parameters
+.SH PARAMETERS
+.PP
+\fB\fIfilename\fP\fP is the name of the input file.  If you don't specify
+this, \fBpnmmercator\fP reads the image from standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmmercator\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-inverse\fP
+.sp
+With this option a conversion from Mercator to degrees is applied.The
+output image will have half the height of the input map.
+
+.TP
+\fB-nomix\fP
+.sp
+Default behaviour is that color blending is applied in between two adjacent
+rows. If you specify the -nomix parameter there is no blending. The
+consequence is a banding at the top and bottom of the map.  With this option,
+the output map will also consist of exactly the same colors as the input.
+
+.TP
+\fB-verbose\fP and \fB-vverbose\fP
+.sp
+This parameter outputs some additional information. If you double the 'v',
+it will output debug data about the lat/long degree and Mercator
+conversions.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\& and
+.BR "pamscale" (1)\c
+\&
+.BR "ppmglobe" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmmercator\fP was new in Netpbm 10.49 (December 2009).
+
+.UN authors
+.SH AUTHORS
+.PP
+\fIWillem van Schaik\fP (of
+\fBpnmtopng\fP/\fBpngtopnm\fP fame) wrote this program in October 2009 and
+suggested it for inclusion in Netpbm.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmmercator.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmmontage.1 b/upstream/mageia-cauldron/man1/pnmmontage.1
new file mode 100644
index 00000000..afeb6825
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmmontage.1
@@ -0,0 +1,192 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmmontage User Manual" 0 "22 November 2012" "netpbm documentation"
+
+.SH NAME
+pnmmontage - create a montage of PNM images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmmontage\fP
+
+[\fB-header=\fP\fIheaderfile\fP]
+
+[\fB-quality=\fP\fIn\fP]
+
+[\fB-prefix=\fP\fIprefix\fP]
+
+[\fB-0\fP|\fB-1\fP|\fB-2\fP|\fB...\fP|\fB-9\fP]
+
+[\fB-data=\fP\fIfilename\fP]
+
+\fIpnmfile\fP...
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmmontage\fP packs images of differing sizes into a minimum-area
+composite image.
+.PP
+Areas of the output that cannot be occupied by an image are black.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmmontage\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-data=\fP\fIfilename\fP
+This option causes \fBpnmmontage\fP to write a file that describes
+in machine-readable form the positions of the original images within
+the packed image.  Here is an example:
+
+.nf
+
+            :0:0:227:298
+            ../image1.ppm:0:0:227:149
+            ../image2.ppm:0:149:227:149
+
+
+.fi
+.sp
+There is a line for each component image and one for the composite.
+.sp
+The 5 fields on each line are:
+
+
+.IP \(bu
+source image name (or null string indicating the line for the composite
+image)
+.IP \(bu
+Column number of upper left corner of the image
+.IP \(bu
+Row number of upper left corner of the image
+.IP \(bu
+width of the image (columns)
+.IP \(bu
+height of the image (rows)
+
+.sp
+This option was new in Netpbm 10.6 (July 2002).
+
+.TP
+\fB-header=\fP\fIfilename\fP
+Tells \fBpnmmontage\fP to write a C header file of the locations
+of the original images within the packed image.  Each original image
+generates four #defines within the packed file: xxxX, xxxY, xxxSZX,
+and xxxSZY, where xxx is the name of the file, converted to all
+uppercase.  The output also includes #defines OVERALLX and OVERALLY, which
+specifies the total size of the montage image.
+.sp
+Here is an example:
+
+.nf
+\f(CW
+            #define OVERALLX 227
+            #define OVERALLY 298
+            
+            #define X 0
+            #define Y 0
+            #define SZX 227
+            #define SZY 149
+            
+            #define X 0
+            #define Y 149
+            #define SZX 227
+            #define SZY 149
+\fP
+
+.fi
+
+.TP
+\fB-prefix\fP
+Tells \fBpnmmontage\fP to use the specified prefix on all of the
+#defines it generates.
+
+.TP
+\fB-quality\fP
+Before attempting to place the subimages, \fBpnmmontage\fP will
+calculate a minimum possible area for the montage; this is either the
+total of the areas of all the subimages, or the width of the widest
+subimage times the height of the tallest subimage, whichever is
+greater.  \fBpnmmontage\fP then initiates a problem-space search to
+find the best packing; if it finds a solution that is (at least) as
+good as the minimum area times the quality as a percent, it will break
+out of the search.  Thus, \fB-quality=100\fP will find the best possible
+solution; however, it may take a very long time to do so.  The default
+is \fB-quality=200.\fP
+
+.TP
+\fB-0\fP, \fB-1\fP, ... \fB-9\fP
+These options control the quality at a higher level than
+\fB-quality\fP; \fB-0\fP is the worst quality (pick the first
+solution found), while \fB-9\fP is the best quality (perform an
+exhaustive search of problem space for the absolute best packing).
+The higher the number, the slower the computation.  The default is
+\fB-5\fP.
+
+
+
+
+.UN notes
+.SH NOTES
+.PP
+Using \fB-9\fP is very slow on all but the smallest image sets.
+.PP
+The minimum area arrangement is often not a convenient shape.  For
+example, it might be a tall, thin column of images, when you'd rather
+have something more square.  To force a minimum width or height, you
+can include a strut image - a black image that wide and one pixel high.
+Similarly, you can use a vertical strut to force a minimum height.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcat" (1)\c
+\&,
+.BR "pnmindex" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmmontage\fP was new in Netpbm 9.10 (January 2001).
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2000 by Ben Olmstead.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmmontage.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmnlfilt.1 b/upstream/mageia-cauldron/man1/pnmnlfilt.1
new file mode 100644
index 00000000..42e4b0bd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmnlfilt.1
@@ -0,0 +1,190 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmnlfilt User Manual" 0 "24 October 2006" "netpbm documentation"
+
+.SH NAME
+
+pnmnlfilt - non-linear filters: smooth, alpha trim mean, optimal
+estimation smoothing, edge enhancement.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmnlfilt\fP
+\fIalpha\fP
+\fIradius\fP
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmnlfilt\fP produces an output image where the pixels are a
+summary of multiple pixels near the corresponding location in an input
+image.
+.PP
+This program works on multi-image streams.
+.PP
+This is something of a swiss army knife filter.  It has 3 distinct
+operating modes.  In all of the modes \fBpnmnlfilt\fP examines each
+pixel in the image and processes it according to the values of it and
+its surrounding pixels.  Rather than using a square block of
+surrounding pixels (e.g. the subject pixel and its 8 immediate
+neighbors, in a 3x3 square), \fBpnmnlfilt\fP uses 7 hexagonal areas.
+You choose the size of the hexagons with the radius parameter.  A
+radius value of 1/3 means that the 7 hexagons essentially fit into the
+subject pixel (ie.  there will be no filtering effect).  A radius
+value of 1.0 means that the 7 hexagons essentially cover the 3x3
+immediate neighbor square.
+.PP
+Your choice of "alpha" parameter selects among the three
+modes.
+
+.UN alphatrimmedmean
+.SS 
+Alpha trimmed mean filter (0.0 <= alpha <= 0.5)
+.PP
+The value of the center pixel will be replaced by the mean of
+the 7 hexagon values, but the 7 values are sorted by size and the top
+and bottom alpha portion of the 7 are excluded from the mean.  This
+implies that an alpha value of 0.0 gives the same sort of output as a
+normal convolution (ie. averaging or smoothing filter), where radius
+will determine the "strength" of the filter. A good value to
+start from for subtle filtering is alpha = 0.0, radius = 0.55 For a
+more blatant effect, try alpha 0.0 and radius 1.0
+.PP
+An alpha value of 0.5 will cause the median value of the 7 hexagons
+to be used to replace the center pixel value. This sort of filter is
+good for eliminating "pop" or single pixel noise from an
+image without spreading the noise out or smudging features on the
+image. Judicious use of the radius parameter will fine tune the
+filtering. Intermediate values of alpha give effects somewhere between
+smoothing and "pop" noise reduction. For subtle filtering
+try starting with values of alpha = 0.4, radius = 0.6 For a more
+blatant effect try alpha = 0.5, radius = 1.0
+
+.UN optimalestsmooth
+.SS 
+Optimal estimation smoothing. (1.0 <= alpha <= 2.0)
+.PP
+This type of filter applies a smoothing filter adaptively over the
+image.  For each pixel the variance of the surrounding hexagon values
+is calculated, and the amount of smoothing is made inversely
+proportional to it. The idea is that if the variance is small then it
+is due to noise in the image, while if the variance is large, it is
+because of "wanted" image features. As usual the radius
+parameter controls the effective radius, but it probably advisable to
+leave the radius between 0.8 and 1.0 for the variance calculation to
+be meaningful.  The alpha parameter sets the noise threshold, over
+which less smoothing will be done.  This means that small values of
+alpha will give the most subtle filtering effect, while large values
+will tend to smooth all parts of the image. You could start with
+values like alpha = 1.2, radius = 1.0 and try increasing or decreasing
+the alpha parameter to get the desired effect. This type of filter is
+best for filtering out dithering noise in both bitmap and color
+images.
+
+.UN edgeenhance
+.SS Edge enhancement. (-0.1 >= alpha >= -0.9)
+.PP
+This is the opposite type of filter to the smoothing filter. It
+enhances edges. The alpha parameter controls the amount of edge
+enhancement, from subtle (-0.1) to blatant (-0.9). The radius
+parameter controls the effective radius as usual, but useful values
+are between 0.5 and 0.9. Try starting with values of alpha = 0.3,
+radius = 0.8
+
+.UN combination
+.SS Combination use.
+.PP
+The various modes of \fBpnmnlfilt\fP can be used one after the
+other to get the desired result. For instance to turn a monochrome
+dithered image into a grayscale image you could try one or two passes
+of the smoothing filter, followed by a pass of the optimal estimation
+filter, then some subtle edge enhancement. Note that using edge
+enhancement is only likely to be useful after one of the non-linear
+filters (alpha trimmed mean or optimal estimation filter), as edge
+enhancement is the direct opposite of smoothing.
+.PP
+For reducing color quantization noise in images (ie. turning .gif
+files back into 24 bit files) you could try a pass of the optimal
+estimation filter (alpha 1.2, radius 1.0), a pass of the median filter
+(alpha 0.5, radius 0.55), and possibly a pass of the edge enhancement
+filter.  Several passes of the optimal estimation filter with
+declining alpha values are more effective than a single pass with a
+large alpha value.  As usual, there is a tradeoff between filtering
+effectiveness and losing detail. Experimentation is encouraged.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpnmnlfilt\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN references
+.SH REFERENCES
+.PP
+The alpha-trimmed mean filter is based on the description in IEEE
+CG&A May 1990 Page 23 by Mark E. Lee and Richard A. Redner, and
+has been enhanced to allow continuous alpha adjustment.
+.PP
+The optimal estimation filter is taken from an article
+"Converting Dithered Images Back to Gray Scale" by Allen
+Stenger, Dr Dobb's Journal, November 1992, and this article references
+"Digital Image Enhancement and Noise Filtering by Use of Local
+Statistics", Jong-Sen Lee, IEEE Transactions on Pattern Analysis
+and Machine Intelligence, March 1980.
+.PP
+The edge enhancement details are from
+.BR "pgmenhance" (1)\c
+\&, which is taken from Philip
+R. Thompson's "xim" program, which in turn took it from
+section 6 of "Digital Halftones by Dot Diffusion",
+D. E. Knuth, ACM Transaction on Graphics Vol. 6, No. 4, October 1987,
+which in turn got it from two 1976 papers by J. F. Jarvis et. al.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+The parameters are:
+
+
+.TP
+\fIalpha\fP
+The alpha value (described above), in decimal.  May be fractional.
+
+.TP
+\fIradius\fP
+The radius (described above), in decimal.  May be fractional.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmenhance" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Graeme W. Gill \fIgraeme@labtam.oz.au\fP
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmnlfilt.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmnoraw.1 b/upstream/mageia-cauldron/man1/pnmnoraw.1
new file mode 100644
index 00000000..aa08f59a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmnoraw.1
@@ -0,0 +1,34 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmnoraw User Manual" 0 "March 2000" "netpbm documentation"
+
+.SH NAME
+
+pnmnoraw - replaced by pnmtoplainpnm and pamtopnm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmnoraw\fP was replaced in Netpbm 8.2 (March 2000) by
+.BR "pnmtoplainpnm" (1)\c
+\&, which was obsoleted by
+\fBpnmtopnm\fP in Netpbm 10.23 (July 2004), which in turn was
+obsoleted by \fBpamtopnm\fP.
+.PP
+\fBpnmtoplainpnm\fP was actually the same program; it was just renamed
+to make it clear that is just a format converter.
+.PP
+\fBpamtopnm\fP is more general, in that it can go both directions.
+\fBpamtopnm -plain\fP is the same as \fBpnmnoraw\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmnoraw.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmnorm.1 b/upstream/mageia-cauldron/man1/pnmnorm.1
new file mode 100644
index 00000000..dfd73266
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmnorm.1
@@ -0,0 +1,356 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmnorm User Manual" 0 "19 December 2014" "netpbm documentation"
+
+.SH NAME
+
+pnmnorm - normalize the contrast in a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmnorm\fP
+
+[\fB-bpercent=\fP\fIpercent\fP | \fB-bvalue=\fP\fIN\fP | \fB-bsingle\fP]
+
+[\fB-wpercent=\fP\fIpercent\fP | \fB-wvalue=\fP\fIN\fP | \fB-wsingle\fP]
+
+[\fB-midvalue=\fP\fIN\fP]
+
+[\fB-middle=N\fP]
+
+[\fB-maxexpand=\fP\fIpercent\fP]
+
+[\fB-keephues\fP]
+
+[\fB-luminosity\fP | \fB-colorvalue\fP | \fB-saturation\fP]
+
+[\fIppmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmnorm\fP reads a PNM image (PBM, PGM, or PPM).  It normalizes the
+contrast by forcing the brightest pixels to white, the darkest pixels to
+black, and spreading out the ones in between.  It produces the same kind of
+file as output.  This is pretty useless for a PBM image.
+.PP
+The program offers two ways of spreading out the pixels in between the
+darkest and brightest: linear and quadratic.  In the quadratic case, you
+specify some in between brightness and specify what brightness that should
+become in the output.  With those three constraints: the brightness that
+becomes black, the brightness that becomes white, and the brightness that
+becomes that middle value, \fBpnmnorm\fP computes a quadratic equation that
+maps all the other brightnesses from input values to output values.
+.PP
+The program first determines a mapping of old brightness to new
+brightness.  For each possible brightness of a pixel, the program
+determines a corresponding brightness for the output image.
+.PP
+Then for each pixel in the image, the program computes a color which has
+the desired output brightness and puts that in the output.  With a color
+image, it is not always possible to compute such a color and retain any
+semblance of the original hue, so the brightest and dimmest pixels may only
+approximate the desired brightness.
+.PP
+For a PPM image, you have a choice of three ways to define brightness:
+
+.IP \(bu
+luminosity
+.IP \(bu
+color value
+.IP \(bu
+saturation
+
+
+In the case of saturation, "brightness" is pretty much a
+misnomer, but you can use the brightness analogy to see what it does.
+In the analogy, bright means saturated and dark means unsaturated.
+.PP
+Note that all of these are different from separately normalizing
+the individual color components.
+.PP
+An alternative way to spread out the brightnesses in an image is
+\fBpnmhisteq\fP.  \fBpnmhisteq\fP stretches the brightest pixels to
+white and the darkest pixels to black, but rather than linearly
+adjusting the ones in between, it adjusts them so that there are an
+equal number of pixels of each brightness throughout the range.  This
+gives you more contrast than \fBpnmnorm\fP does, but can considerably
+change the picture in exchange.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmnorm\fP recognizes the following
+command line options:
+.PP
+By default, the darkest 2 percent of all pixels are mapped to
+black, and the brightest 1 percent are mapped to white.  You can
+override this behavior and specify either a different percentage, or
+specific brightness values to map to black and to white, or just have
+the single greatest brightness map to white and the least brightness map
+to black.
+
+
+.TP
+\fB-bpercent\fP
+.TP
+\fB-wpercent\fP
+.TP
+\fB-bvalue\fP
+.TP
+\fB-wvalue\fP
+.sp
+To specify a percentage, use the \fB-bpercent\fP and
+\fB-wpercent\fP options, or you can specify the exact pixel values to
+be mapped by using the \fB-bvalue\fP and \fB-wvalue\fP options.
+You can get appropriate numbers for the options from
+\fBppmhist\fP.  If you just want to enhance the contrast, then
+choose values at elbows in the histogram; e.g. if value 29 represents
+3% of the image but value 30 represents 20%, choose 30 for
+\fIbvalue\fP.  If you want to brighten the image, then set
+\fIbvalue\fP to 0 and just fiddle with \fIwvalue\fP; similarly, to
+darken the image, set \fIwvalue\fP to maxval and play with
+\fIbvalue\fP.
+.sp
+If you specify both \fB-bvalue\fP and \fB-bpercent\fP, \fBpnmnorm\fP
+uses the one that produces the least change.  The same goes for
+\fB-wvalue\fP and \fB-wpercent\fP.  (In Netpbm 10.26 (January 2005),
+the \fB-bvalue\fP/\fB-wvalue\fP takes precedence, and before that,
+it's a syntax error to specify both).
+.sp
+If you want to maximize the change instead of minimizing it, just
+cascade two runs of \fBpnmnorm\fP, specifying values for the first
+and percentages for the second.
+.sp
+\fB-bpercent\fP and \fB-wpercent\fP values are floating point
+decimal.  Zero is valid and is the same as \fB-bvalue=0\fP or
+\fB-wvalue=\fP\fImaxval\fP, respectively.
+.sp
+Because there are whole numbers of pixels at each brightness,
+\fBpnmnorm\fP obviously can't guarantee the exact percentage, so it
+arranges that \fIat least\fP the percentage of pixels you specify
+get remapped as promised.
+.sp
+It is possible for your \fB-bpercent\fP or \fB-wpercent\fP
+to overlap your \fB-wvalue\fP or \fB-bvalue\fP, respectively.  For
+example, you say \fB-bpercent=20\fP and \fB-wvalue=100\fP for an
+image in which only 10 percent of the pixels are darker than 100.
+In that case, \fBpnmnorm\fP adjusts the percentile value as
+required.  In the example, it uses 99 as the black value (like
+\fB-bvalue=99\fP).
+.sp
+It is also possible for your \fB-bpercent\fP and \fB-wpercent\fP
+options to select the same brightness value for the stretch-to-white
+and stretch-to-black value because of the fact that \fBpnmnorm\fP
+can't subdivide a histogram cell.  E.g. if an image is all brightness
+100, then no matter what \fB-bpercent\fP and \fB-wpercent\fP
+values you choose, it's the same as saying \fB-bvalue=100 -wvalue=100\fP.
+In that case, \fBpnmnorm\fP changes one of the values by 1 to make it
+legal.  In the example, \fBpnmnorm\fP would either make the black
+value 99 or the white value 101.
+.sp
+Before Netpbm 10.43 (June 2008), \fBpnmnorm\fP fails if the
+\fB-wpercent\fP and/or \fB-bpercent\fP values specify an overlap.
+.sp
+The stretch points are further constrained by the \fB-maxexpand\fP
+option.  Sometimes, too much contrast is a bad thing.  If your
+intensities are all concentrated in the middle, \fB-bpercent=2\fP and
+\fB-wpercent=1\fP might mean that an intensity of 60 gets stretched
+up to 100 and intensity of 20 gets stretched down to zero, for a
+range expansion of 150% (from a range of 40 to a range of 100).  That
+much stretching means two adjacent pixels that used to differ in
+intensity by 4 units now differ by 10, and that might be unsightly.
+
+.TP
+\fB-bsingle\fP
+.sp
+To specify that the single least brightness in the image should stretch to
+black in the output, specify \fB-bsingle\fP.  To specify that the single
+greatest brightness in the image should stretch to white in the output,
+specify \fB-wsingle\fP.  \fB-bsingle\fP and \fB-wsingle\fP were new in
+Netpbm 10.69 (December 2014).
+
+.TP
+\fB-maxexpand\fP
+.sp
+So that you can put a limit on the amount of expansion without
+having to examine the image first, there is the \fB-maxexpand\fP
+option.  It specifies the maximum expansion you will tolerate, as an
+additional percentage.  In the example above, you could say
+\fB-maxexpand=50\fP to say you want the range to expand by at most
+50%, regardless of your other options.  \fBpnmnorm\fP figures out
+what intensity to stretch to full intensity and what intensity to
+stretch to zero intensity as described above, and then raises the
+former and lowers the latter as needed to limit the expansion to the
+amount you specified.
+.sp
+When \fBpnmnorm\fP limits the expansion because of \fB-maxexpand\fP,
+it tells you about it with a message like this:
+.nf
+
+    limiting expansion of 150% to 50%
+
+
+.fi
+.sp
+In any case, \fBpnmnorm\fP tells you exactly what expansion it's
+doing, like this:
+
+.nf
+
+    remapping 25..75 to 0..100
+
+
+.fi
+.sp
+Before Netpbm 10.26 (December 2004), it was not valid to specify both
+\fB-bvalue\fP and \fB-bpercent\fP or \fB-wvalue\fP and \fB-wpercent\fP.
+.sp
+\fB-maxexpand\fP was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-keephues\fP
+.sp
+This option says to keep each pixel the same hue as
+it is in the input; just adjust its brightness.  You normally want this;
+the only reason it is not the default behavior is backward compatibility
+with a design mistake.
+.sp
+By default, \fBpnmnorm\fP normalizes contrast in each component
+independently (except that the meaning of the \fB-wpercent\fP and
+\fB-bpercent\fP options are based on the overall brightnesses of the
+colors, not each component taken separately).  So if you have a color
+which is intensely red but dimly green, \fBpnmnorm\fP would make the
+red more intense and the green less intense, so you end up with a
+different hue than you started with.
+
+.TP
+\fB-midvalue=\fP\fIN\fP
+.TP
+\fB-middle=\fP\fIN\fP
+.sp
+When you specify \fB-midvalue=\fP\fIN\fP, \fBpnmnorm\fP uses a quadratic
+function to map old brightnesses to new ones, making sure that an old
+brightness of \fIN\fP becomes 50% bright in the output.  You can override
+that 50% default with \fB-middle\fP.  The value of \fB-middle\fP is a
+floating point number in the range 0 through 1 with 0 being full darkness and
+1 full brightness.  If your \fB-midvalue\fP and \fB-middle\fP indicate an
+ambiguous or impossible quadratic function (e.g. \fB-midvalue\fP is the same
+as \fB-bvalue\fP, so an infinite number of quadratic functions
+fit), \fBpnmnorm\fP just ignores your \fB-midvalue\fP and maps linearly.
+
+\fB-midvalue\fP and \fB-middle\fP were new in Netpbm 10.57 (December 2011).
+.sp
+If you specify \fB-keephues\fP, \fBpnmnorm\fP would likely leave
+this pixel alone, since its overall brightness is medium.
+.sp
+\fB-keephues\fP can cause clipping, because a certain color may be
+below a target intensity while one of its components is saturated.
+Where that's the case, \fBpnmnorm\fP uses the maximum representable
+intensity for the saturated component and the pixel ends up with less
+overall intensity, and a different hue, than it is supposed to have.
+.sp
+This option is meaningless on grayscale images.
+.sp
+When you \fIdon't\fP specify \fB-keephues\fP, the
+\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP options
+affect the transfer function (which is the same for all three RGB
+components), but are meaningless when it comes to applying the
+transfer function (since it is applied to each individual RGB
+component).
+.sp
+Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fP option.
+
+.TP
+\fB-luminosity\fP
+.TP
+\fB-colorvalue\fP
+.TP
+\fB-saturation\fP
+.sp
+\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP determine
+what property of the pixels \fBpnmnorm\fP normalizes.  I.e., what kind of
+brightness.  You cannot specify more than one of these.
+.sp
+The \fB-luminosity\fP option says to use the luminosity (i.e. the
+"Y" in the YUV or YCbCr color space) as the pixel's brightness.  The
+luminosity is a measure of how bright a human eye would find the color,
+taking into account the fact that the human eye is more sensitive to some
+RGB components than others.
+.sp
+This option is default.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fP option,
+but its meaning was still the default.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+.sp
+The \fB-colorvalue\fP option says to use the color value (i.e. the
+"V" in the HSV color space) as the pixel's brightness.  The
+color value is the gamma-adjusted intensity of the most intense RGB
+component.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+.sp
+The \fB-saturation\fP option says to use the saturation (i.e. the
+"S" in the HSV color space) as the pixel's brightness.  The
+saturation is the ratio of the intensity of the most intense RGB
+component to the difference between the intensities of the most and least
+intense RGB component (all intensities gamma-adjusted).
+.sp
+In this case, "brightness" is more of a metaphor than anything.
+"bright" means saturated and "dark" means unsaturated.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmhisteq" (1)\c
+\&,
+.BR "pamlevels" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "pgmhist" (1)\c
+\&,
+.BR "pambrighten" (1)\c
+\&,
+.BR "ppmdim" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmnorm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmpad.1 b/upstream/mageia-cauldron/man1/pnmpad.1
new file mode 100644
index 00000000..bfa58cb4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmpad.1
@@ -0,0 +1,283 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmpad User Manual" 0 "25 December 2021" "netpbm documentation"
+
+.SH NAME
+
+pnmpad - add borders to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmpad \fP
+[\fB-white\fP|\fB-black\fP]
+[\fB-width=\fP\fIpixels\fP]
+[\fB-halign=\fP\fIratio\fP]
+[\fB-mwidth=\fP\fIpixels\fP]
+[\fB-left=\fP\fIpixels\fP]
+[\fB-right=\fP\fIpixels\fP]
+[\fB-height=\fP\fIpixels\fP]
+[\fB-valign=\fP\fIratio\fP]
+[\fB-mheight=\fP\fIpixels\fP]
+[\fB-top=\fP\fIpixels\fP]
+[\fB-bottom=\fP\fIpixels\fP]
+[\fB-reportonly\fP]
+[\fB-verbose\fP]
+[\fIpnmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmpad\fP reads a PNM image as input and outputs a PNM image
+that is the input image plus black or white borders of the sizes
+specified.
+.PP
+If you just need to convert an image to a certain size regardless
+of the original dimensions, \fBpamcut\fP with the \fB-pad\fP option
+may be a better choice.
+.PP
+\fBpnmmargin\fP does essentially the same thing, but allows you to
+add borders of any color and requires all four borders to be the same
+size.
+.PP
+You can use \fBpamcomp\fP to add borders of any content - solid color,
+  pattern, or whatever.  For example, if you wanted to add 10 pixels of red
+  borders to the top and bottom of a 100x100 image, you could create a
+  100x120 red image (e.g. with \fBppmmake\fP) and then use \fBpamcomp\fP
+  to insert your 100x100 image into the center of it.
+  
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmpad\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or an equals sign between an option name and
+its value.
+
+
+.TP
+\fB-white\fP
+.TP
+\fB-black\fP
+Set pad color.  Default is \fB-black\fP.
+
+.TP
+\fB-left=\fP\fIpixels\fP
+.TP
+\fB-right=\fP\fIpixels\fP
+.TP
+\fB-width=\fP\fIwidth\fP
+.TP
+\fB-halign=\fP\fIratio\fP
+.TP
+\fB-mwidth=\fP\fIpixels\fP
+Specify amount of left and right padding in pixels.
+.sp
+\fB-left\fP and \fB-right\fP directly specify the amount of
+padding added to the left and right sides, respectively, of the image.
+.sp
+Alternatively, you can specify \fB-width\fP and just one of
+\fB-left\fP and \fB-right\fP and \fBpnmpad\fP calculates the required
+padding on the other side to make the output \fIwidth\fP pixels wide.  If
+the \fB-width\fP value is less than the width of the input image plus the
+specified padding, \fBpnmpad\fP ignores \fB-width\fP.
+.sp
+If you specify all three of \fB-width\fP, \fB-left\fP, and
+\fB-right\fP, you must ensure that the \fB-left\fP and \fB-right\fP
+padding are sufficient to make the image at least as wide as
+\fB-width\fP specifies.  Otherwise, \fBpnmpad\fP fails.
+.sp
+When you specify \fB-width\fP without \fB-left\fP or
+\fB-right\fP, and \fB-width\fP is larger than the input image,
+\fBpnmpad\fP chooses left and right padding amounts in a certain
+ratio.  That ratio defaults to half, but you can set it to anything
+(from 0 to 1) with the \fB-halign\fP option.  If the input image is
+already at least as wide as \fB-width\fP specifies, \fBpnmpad\fP
+adds no padding.
+.sp
+Common values for \fB-halign\fP are:
+
+.TP
+\fB0.0\fP 
+left aligned
+
+.TP
+\fB0.5\fP 
+center aligned (default)
+
+.TP
+\fB1.0\fP 
+right aligned
+
+.sp
+\fB-mwidth=\fP\fIpixels\fP says to pad to a multiple of
+\fIpixels\fP pixels.  E.g. if \fIpixels\fP is 10, the output image width
+will be a multiple of 10 pixels.  \fBpnmpad\fP adds to whatever padding the
+other options say to do to get to this multiple.  It divides that padding
+between the left and right sides of the image to maintain the ratio the other
+options produce.  E.g. if you say \fB-left=10 -right=10 -mwidth=50\fP with a
+100-pixel image, you end up with a 150-pixel image with the extra padding
+split evenly between left and right for a total of 25 pixels of padding
+on the left and 25 on the right.  If the other options indicate no
+padding, \fBpnmpad\fP adds padding in the ratio specified by \fB-halign\fP
+and if \fB-halign\fP is not specified, equally on both sides.
+.sp
+Before Netpbm 10.97 (December 2021), \fBpnmpad\fP does not allow
+\fB-halign\fP with \fB-mwidth\fP and adds padding only on the right
+when \fB-mwidth\fP is specified and the other options indicate no padding.
+.sp
+Before Netpbm 10.72 (September 2015), there is no \fB-mwidth\fP.
+.sp
+Before Netpbm 10.23 (July 2004), \fBpnmpad\fP did not allow the
+\fB-left\fP or \fB-right\fP option together with \fB-width\fP.
+
+.TP
+\fB-top=\fP\fIpixels\fP
+.TP
+\fB-bottom=\fP\fIpixels\fP
+.TP
+\fB-height=\fP\fIheight\fP
+.TP
+\fB-valign=\fP\fIratio\fP
+.TP
+\fB-mheight=\fP\fIpixels\fP
+These options determine the vertical padding.  They are analogous to the
+horizontal padding options above.
+
+.TP
+\fB-reportonly\fP
+  This causes \fBpnmpad\fP to write to Standard Output a description of the
+  padding it would have done instead of producing an output image.  See
+  
+.UR #reportonly
+below
+.UE
+\& for a description of this output and ways
+  to use it.
+.sp
+This option was new in Netpbm 10.89 (December 2019).
+
+.TP
+\fB-verbose\fP
+This causes verbose messages.
+
+
+
+.UN reportonly
+.SH REPORT ONLY
+.PP
+When you specify \fB-reportonly\fP, \fBpnmpad\fP does not produce an
+  output image.  Instead, it writes to Standard Output a description of the
+  padding it would have done without \fB-reportonly\fP.
+.PP
+That description is one line of text, containing 6 decimal numbers of
+  pixels, separated by spaces:
+
+
+.IP \(bu
+left padding
+.IP \(bu
+right padding
+.IP \(bu
+top padding
+.IP \(bu
+bottom padding
+.IP \(bu
+output width
+.IP \(bu
+output height
+
+.PP
+Example:
+.nf
+    
+      4 3 0 2 100 100
+    
+
+.fi
+.PP
+One use for this is to make padding which is fancier than the black and
+  white that \fBpnmpad\fP can do.
+.PP
+In the following example, we pad an image with 10 pixels of gray all
+  around, without knowing the original image dimensions beforehand.  We do
+  this by generating a gray image with \fBpbmmake\fP and then pasting the
+  subject image into the middle of it.
+.PP
+The example uses shell arrays, such as exist in Bash, but not Dash.
+  
+.nf
+    \f(CW
+    pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
+    pbmmake -gray ${pad[4]} ${pad[5]} | \e
+      pnmpaste input.ppm ${pad[0]} ${pad[2]} -
+    \fP
+
+.fi
+    
+
+.UN history
+.SH HISTORY
+.PP
+Before February 2002, \fBpnmpad\fP had a different option syntax
+which was less expressive and not like conventional Netpbm programs.
+That syntax is still understood by \fBpnmpad\fP for backward
+compatibility, but not documented or supported for future use.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmmake" (1)\c
+\&,
+.BR "pnmpaste" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmcrop" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pnmmargin" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2002 by Martin van Beilen
+.PP
+Copyright (C) 1990 by Angus Duggan
+.PP
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.  This software is provided "as is"
+without express or implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmpad.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmpaste.1 b/upstream/mageia-cauldron/man1/pnmpaste.1
new file mode 100644
index 00000000..ba997fb2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmpaste.1
@@ -0,0 +1,129 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmpaste User Manual" 0 "16 December 2018" "netpbm documentation"
+
+.SH NAME
+
+pnmpaste - paste a rectangle into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmpaste\fP
+
+[\fB-replace\fP | \fB-or\fP | \fB-and\fP | \fB-xor\fP |
+\fB-nor\fP | \fB-nand\fP | \fB-nxor\fP]
+
+\fIfrompnmfile\fP \fIx\fP \fIy\fP
+[\fIintopnmfile\fP]
+.PP
+You can abbreviate all options to their shortest unique prefix.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmpaste\fP reads two PNM images as input and inserts the first
+image (the "pasted image") into the second (the "base image") at the
+specified location, and produces a PNM image the same size and type as
+the base image as output.
+.PP
+Either file name argument (but not both) may be '-' to indicate
+Standard Input.  If you don't specify the second file argument at all, that's
+the same as '-'.
+.PP
+\fIx\fP and \fIy\fP specify the location in the base image at
+which to put the top left corner of the pasted image, \fIx\fP giving
+the horizontal position and \fIx\fP giving the vertical position.  A
+nonnegative value indicates the number of pixels right of the right
+edge or below the top edge of the base image, while a negative value
+indicates the number of pixels right of the right edge or below the
+bottom edge (so x = -5 means 5 pixels left of the right edge).
+.PP
+If any part of the pasted image does not fit within the base image,
+\fBpnmpaste\fP fails.
+.PP
+This tool is most useful in combination with \fIpamcut\fP.  For
+instance, if you want to edit a small segment of a large image, and
+your image editor cannot edit the large image, you can cut out the
+segment you are interested in, edit it, and then paste it back in.
+.PP
+Another useful companion tool is \fBpbmmask\fP.
+.PP
+\fBpamcomp\fP is a more general tool, except that it lacks the
+"or," "and," and "xor" functions.
+\fBpamcomp\fP allows you to specify a transparency mask in order to have
+only part of the inserted image get inserted.  So the inserted pixels
+need not be a rectangle.  You can also have the inserted image be
+translucent, so the resulting image is a mixture of the inserted image
+and the base image.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmpaste\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-replace\fP, \fB-or\fP, \fB-and\fP, \fB-xor\fP,
+\fB-nor\fP, \fB-nand\fP, \fB-nxor\fP
+.sp
+These option specify the operation to use when doing the paste.
+The default is \fB-replace\fP, which means to do the obvious paste:
+replace pixels of the "into" image with those of the
+"from" image.
+.sp
+\fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, \fB-xor\fP,
+and \fBnxor\fP are allowed only if both input images are PBM images.  They
+say to combine the "from" and "into" images by performing boolean operations:
+Each pixel of the output image is the result of the boolean operation on the
+corresponding pixels of the two input images, where white is TRUE and black
+is FALSE.
+.sp
+Note that this is different from what you would get by doing a bit
+arithmetic on the bits in the PBM images, because in PBM, white is
+represented by a 0 bit, and 0 in bit arithmetic corresponds to FALSE
+in boolean arithmetic.
+.sp
+\fB-nand\fP, \fB-nor\fP, and \fB-nxor\fP were new in Netpbm 10.85
+(December 2018).
+
+
+  
+.UN seealso
+.SH SEE ALSO
+.BR "pamcomp" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnminvert" (1)\c
+\&,
+.BR "pnmarith" (1)\c
+\&,
+.BR "pbmmask" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmpaste.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmpsnr.1 b/upstream/mageia-cauldron/man1/pnmpsnr.1
new file mode 100644
index 00000000..5e84032e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmpsnr.1
@@ -0,0 +1,212 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmpsnr User Manual" 0 "06 January 2018" "netpbm documentation"
+
+.SH NAME
+pnmpsnr - compute the difference between two images (the PSNR)
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmpsnr\fP
+
+[\fIpnmfile1\fP]
+
+[\fIpnmfile2\fP]
+
+[\fB-rgb\fP]
+[\fB-machine\fP]
+[\fB-max=\fP\fIn\fP]
+[\fB-target=\fP\fIn\fP]
+[\fB-target1=\fP\fIn\fP]
+[\fB-target2=\fP\fIn\fP]
+[\fB-target3=\fP\fIn\fP]
+.PP
+Minimum unique abbreviations of options are acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmpsnr\fP reads two PBM, PGM, or PPM files, or PAM equivalents, as
+input and computes the magnitude of difference between the two images as a peak
+signal-to-noise ratio (PSNR) This metric is typically used in image
+compression papers to rate the distortion between original and decoded image.
+.PP
+\fBpnmpsnr\fP either prints these values or compares them to thresholds
+you specify.
+  
+.PP
+The PSNR of a given component is the ratio of the maximum mean square
+difference of component values that could exist between the two images (a
+measure of the information content in an image) to the actual mean square
+difference for the two subject images.  It is expressed as a decibel value.
+.PP
+The mean square difference of a component for two images is the
+mean square difference of the component value, comparing each pixel
+with the pixel in the same position of the other image.  For the
+purposes of this computation, components are normalized to the scale
+[0..1].
+.PP
+The maximum mean square difference is identically 1.
+.PP
+So the higher the PSNR, the closer the images are.  A luminance
+PSNR of 20 means the mean square difference of the luminances of the
+pixels is 100 times less than the maximum possible difference,
+i.e. 0.01.
+.PP
+Note that the word "peak" is a misnomer; there is no maximum involved; the
+metric is a mean.  But "peak signal to noise ratio" is for some reason the
+common term for this measurement.
+.PP
+If the inputs are PBM or PGM, \fBpnmpsnr\fP computes the PSNR of the
+luminance only.  Otherwise, it computes three separate PSNRs: either the
+luminance, and chrominance (Cb and Cr) components of the colors or the
+red, green, and blue components.
+.PP
+By default, the program prints the PSNRs to Standard Output in
+human-friendly form.
+.PP
+With the \fB-machine\fP option, the program prints the PSNRs, but
+in machine-friendly form.
+.PP
+With a \fB-target\fP[\fIx\fP] option, the program just prints
+\&'match' or 'nomatch', depending on whether the PSNRs
+exceed targets you specify.
+  
+.PP
+\fBpnmpsnr\fP reports the PSNR either in human-friendly form or in
+machine-friendly form (see \fB-machine\fP).
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmpsnr\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-rgb\fP
+This option causes \fBpnmpsnr\fP to compare the red, green, and blue
+components of the color rather than the luminance and chrominance components.
+It has no effect on a monotone image.
+.sp
+This option was new in Netpbm 10.71 (June 2015).
+
+.TP
+\fB-machine\fP
+This option causes \fBpnmpsnr\fP to report the PSNRs in machine-friendly
+form, so another program can easily use the information.
+.sp
+The output is a single line.  It contains one floating point decimal number
+for each color component, with a single space between every two.  (This means
+there are either 1 or 3 numbers).  For the YCbCr color space (no \fB-rgb\fP),
+they are in the order Y, Cb, Cr.  For the RGB color space (\fB-rgb\fP), they
+are in R, G, B order.  For a monotone image, there is one number.
+.sp
+Where the component does not differ between the images, so the PSNR is
+infinite, the number is \fBinf\fP
+.sp
+But note that the number displayed is also modified by the effect of
+\fB-max\fP.  In particular, with \fB-max\fP, you will never see \fBinf\fP.
+.sp
+This option has no effect when you also specify \fB-target\fP[\fIn\fP].
+.sp
+This option was new in Netpbm 10.74 (March 2016).
+
+.TP
+\fB-max=\fP\fIn\fP
+This is meaningful only with \fB-machine\fP.
+.sp
+It specifies the maximum number \fBpnmpsnr\fP will print as a PSNR.
+If the PSNR is greater than \fIn\fP, \fBpnmpsnr\fP just prints \fIn\fP.
+\fIn\fP is a decimal floating point number.  An infinite PSNR is considered
+greater than any number.
+.sp
+This is mainly useful to deal with infinite PSNRs.  It is often much more
+convenient to have a program process only numbers than to make it deal with
+infinity, and often a very large number has the same effect on a program as
+infinity.
+.sp
+Note that the output is logarithmic, which means you will not see really
+large but finite numbers.  If you specify \fB-max=1000\fP, the only way you
+will see 1000 in the output is if the PSNR is really infinite.  Two images
+with as many pixels as there are electrons in the universe, differing in only
+one pixel, and only in the smallest amount representable in the Netpbm format,
+have a PSNR less than 1000.
+.sp
+This option was new in Netpbm 10.74 (March 2016).
+
+.TP
+\fB-target\fP=\fIn\fP
+                        
+This option causes \fBpnmpsnr\fP to run in comparison mode - rather than
+print the PSNRs, it just tells you whether the PSNRs exceed 
+\fIn\fP (a floating point number), i.e. whether the compared images are the
+same within a given margin of error.  If all the computed PSNRs (luminance for
+a PBM or PGM; luminance and chrominance or red, green, and blue for PPM)
+exceed \fIn\fP, the program prints 'match' to Standard Output.
+Otherwise, it prints 'nomatch'.
+.sp
+If you also specify any of \fB-target1\fP, \fB-target2\fP, or
+\fB-target3\fP, and the images are color, \fBpnmpsnr\fP ignores
+\fB-target\fP.
+.sp
+This is mainly useful for use in a program.  If you're
+running \fBpnmpsnr\fP manually, you could just run \fBpnmpsnr\fP
+without \fB-target\fP and compare the PSNRs to your targets yourself.
+.sp
+This option was new in Netpbm 10.82 (March 2018).
+
+.TP
+\fB-target\fP{\fB1\fP,\fB2\fP,\fB3\fP}=\fIn\fP
+Like \fB-target\fP, these options cause \fBpnmpsnr\fP to run in comparison
+mode.  But they provide separate targets for the individual color component
+PSNRs.  \fB-target1\fP, \fBtarget-2\fP, and \fB-target3\fP are for either
+the Y, Cb, and Cr components, respectively, or the red, green, and blue
+components, respectively, depending upon whether you specified \fB-rgb\fP.
+.sp
+If you don't specify the corresponding \fB-target\fP\fIn\fP option for a
+component, \fBpnmpsnr\fP ignores the PSNR of that component in deciding
+whether the images match.
+.sp
+If the image is a PBM or PGM, these options have no effect, except that it
+stilll selects comparison mode, so if you don't \fIalso\fP
+specify \fB-target\fP, and the image is PBM or PGM, the program fails.
+.sp
+Note that the options are defined so that you could code a
+\fBpnmpsnr\fP command in a program that works on both color and monotone
+images, specifying individual PSNR targets for use on the color images and the
+single target for use on the monotone images.
+.sp
+These options were new in Netpbm 10.82 (March 2018).
+    
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmpsnr.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmquant.1 b/upstream/mageia-cauldron/man1/pnmquant.1
new file mode 100644
index 00000000..165b1a7e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmquant.1
@@ -0,0 +1,186 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmquant User Manual" 0 "09 February 2019" "netpbm documentation"
+
+.SH NAME
+pnmquant - quantize the colors in a Netpbm image to a smaller set
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmquant\fP
+[\fB-center\fP|\fB-meancolor\fP|\fB-meanpixel\fP]
+[\fB-floyd\fP|\fB-fs\fP]
+[\fB-nofloyd\fP|\fB-nofs\fP]
+[\fB-spreadbrightness\fP|\fB-spreadluminosity\fP]
+{[\fB-norandom\fP]|[\fB-randomseed=\fP\fIn\fP]}
+\fIncolors\fP [\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmquant\fP reads a PNM image as input.  It chooses \fIncolors\fP
+colors to best represent the image, maps the existing colors
+to the new ones, and writes a PNM image as output.
+.PP
+This program is simply a combination of \fBpnmcolormap\fP and
+\fBpnmremap\fP, where the colors of the input are remapped using a
+color map which is generated from the colors in that same input.  The
+options have the same meaning as in those programs.  See their
+documentation to understand \fBpnmquant\fP.
+.PP
+You may actually get fewer than \fBncolors\fP colors in the output because
+  the method \fBpnmcolormap\fP uses to choose the best set of colors for the
+  image is not the same as the method \fBpnmremap\fP uses to determine the
+  best color from the set to represent an individual color.  For example,
+  \fBpnmcolormap\fP may include salmon in the color map as the best
+  representative of a pink pixel in the input and include coral in the color
+  map as the best representative of an actual coral pixel in the input.  But
+  \fBpnmremap\fP is free to use any color in the color map to represent that
+  pink pixel and would find coral is a closer match for pink than salmon and
+  therefore use coral for pink.  \fBpnmremap\fP might not use salmon
+  for \fIany\fP pixel.
+.PP
+This waste of a slot in the color map is a consequence of the approximate
+  method \fBpnmcolormap\fP uses in order to compute the color map with a
+  practical amount of computation.
+
+
+.UN separate
+.SS Running \fBpnmcolormap\fP and \fBpnmremap\fP Separately
+
+.PP
+It is much faster to call \fBpnmcolormap\fP and \fBpnmremap\fP
+directly than to run \fBpnmquant\fP.  You save the overhead of the
+Perl interpreter and creating two extra processes.  \fBpnmquant\fP is
+just a convenience.
+.PP
+Here is an example of the relationship between the programs:
+.PP
+This:
+
+.nf
+\f(CW
+    $ pnmquant 256 myimage.pnm >/tmp/colormap.pnm >myimage256.pnm
+\fP
+
+.fi
+.PP
+does essentially this:
+
+.nf
+\f(CW
+    $ pnmcolormap 256 myimage.pnm >/tmp/colormap.pnm
+    $ pnmremap -mapfile=/tmp/colormap.pnm myimage.pnm >myimage256.pnm
+\fP
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmquant\fP recognizes the following
+command line options:
+
+.UN pnmcolormapopt
+.SS Options Passed to \fBpnmcolormap\fP
+
+  
+.PP
+These options control the selection of the palette.  They are options to
+.BR "\fBpnmcolormap\fP" (1)\c
+\&.
+
+
+.TP
+\fB-center\fP
+.TP
+\fB-meancolor\fP
+.TP
+\fB-meanpixel\fP
+.TP
+\fB-spreadbrightness\fP
+.TP
+\fB-spreadluminosity\fP
+
+
+.UN pnmremapopt
+.SS Options Passed to \fBpnmremap\fP
+
+  
+.PP
+These options control which color from the palette the program uses to
+  replace a pixel of a certain color from the input.  They are options to
+.BR "\fBpnmremap\fP" (1)\c
+\&.
+
+
+.TP
+\fB-floyd\fP
+.TP
+\fB-fs\fP
+.TP
+\fB-nofloyd\fP
+.TP
+\fB-nofs\fP
+.TP
+\fB-norandom\fP
+.TP
+\fB-randomseed\fP
+.TP
+\fB-norandom\fP
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmquant\fP did not exist before Netpbm 9.21 (January 2001).
+Before that, \fBppmquant\fP did the same thing, but only on PPM
+images.  \fBppmquant\fP continues to exist, but is only a front end
+(for name compatibility) to \fBpnmquant\fP.
+.PP
+\fB-version\fP did not exist before Netpbm 10.75 (June 2016).
+  
+.PP
+\fB-norandom\fP did not exist before Netpbm 10.82 (March 2018).
+  
+.UN seealso
+.SH SEE ALSO
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnmquantall" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "ppmquant" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmquant.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmquantall.1 b/upstream/mageia-cauldron/man1/pnmquantall.1
new file mode 100644
index 00000000..398e79e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmquantall.1
@@ -0,0 +1,93 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmquantall User Manual" 0 "05 March 2012" "netpbm documentation"
+
+.SH NAME
+
+pnmquantall - run Pnmquant on a bunch of files all at once, so they
+share a common colormap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmquantall\fP
+
+[\fB-ext\fP \fIextension\fP] \fIncolors\fP \fInetpbm_file\fP...
+.PP
+Note that the usual syntax rules for Netpbm programs \fIdon't apply\fP
+to this program.  For example, you can't abbreviate -ext and you can't put
+it anywhere on the line you want.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmquantall\fP takes a bunch of Netpbm image files as input, chooses
+\fIncolors\fP colors to best represent all of the images, maps the
+existing colors to the new ones, and \fBoverwrites the input
+files\fP with the new quantized versions.
+.PP
+If you don't want to overwrite your input files, use the
+\fB-ext\fP option.  The output files are then named the same as the
+input files, plus a period and the extension text you specify.
+.PP
+The purpose is this: Let's say you've got a dozen PPMs that you want to
+display on the screen all at the same time.  Your screen can only display 256
+different colors, but the PPMs have a total of a thousand or so different
+colors.  For a single image you solve this problem
+with \fBpnmquant\fP; \fBpnmquantall\fP solves it for multiple images.
+.PP
+Note that another approach to this problem is to pre-select a set
+of colors and then use \fBpnmremap\fP to separately quantize each PPM
+to that set.)
+.PP
+This is a rather simple program that runs \fBpnmcolormap\fP and
+\fBpnmremap\fP.  If you are considering using it in a program of any
+sophistication, you should probably just run those programs directly.
+Even if you are typing it, you may want to do the steps manually because
+it gives you access to the various options of \fBpnmcolormap\fP and
+\fBpnmremap\fP for doing the quantization differently.
+
+
+.UN options
+.SH OPTIONS
+.PP
+\fBpnmquantall\fP recognizes the following command line option:
+
+
+.TP
+\fB-ext\fP \fIextension\fP
+Specify an extension for the output files.  By default the input files
+are overwritten.
+
+.PP
+\fBpnmquantall\fP does not recognize the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)  However, the \fB-version\fP option works.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmquantall.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmremap.1 b/upstream/mageia-cauldron/man1/pnmremap.1
new file mode 100644
index 00000000..515ef488
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmremap.1
@@ -0,0 +1,370 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmremap User Manual" 0 "13 November 2014" "netpbm documentation"
+
+.SH NAME
+pnmremap - replace colors in a PNM image with colors from another set
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmremap\fP
+
+\fB-mapfile=\fP\fIpalettefile\fP
+
+[\fB-floyd\fP|\fB-fs\fP|\fB-nfloyd\fP|\fB-nofs\fP]
+
+{[\fB-norandom\fP]|\fBrandomseed=\fP\fIn\fP}
+
+[\fB-firstisdefault\fP]
+
+[\fB-verbose\fP]
+
+[\fB-missingcolor=\fP\fIcolorspec\fP]
+
+[\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmremap\fP replaces the colors in an input image with those
+from a palette you specify.  Where colors in the input are present in
+the palette, they just stay the same in the output.  But where the
+input contains a color that is not in the palette, \fBpnmremap\fP
+gives you these choices:
+
+
+.IP \(bu
+Choose the closest color from the palette.
+
+.IP \(bu
+Choose the first color from the palette.
+
+.IP \(bu
+Use a color specified by a command option (\fB-missing\fP).
+
+.IP \(bu
+Dither.  This means rather than mapping pixel by pixel,
+\fBpnmremap\fP uses colors from the palette to try to make
+multi-pixel regions of the output have the same average color as the
+input (for another kind of dithering, see \fBppmdither\fP).
+
+
+.PP
+Two reasons to use this program are: 1) you want to reduce the
+number of colors in the input image; and 2) you need to feed the image
+to something that can handle only certain colors.
+.PP
+To reduce colors, you can generate the palette with
+\fBpnmcolormap\fP.
+.PP
+By default, \fBpnmremap\fP maps an input color that is not in the
+palette to the closest color that \fIis\fP in the palette.  Closest
+means with the smallest Cartesian distance in the red, green, blue
+brightness space (smallest sum of the squares of the differences in
+red, green, and blue ITU-R Recommendation BT.709 gamma-adjusted
+intensities).
+.PP
+You can instead specify a single default color for \fBpnmremap\fP
+to use for any color in the input image that is not in the palette.
+Use the \fB-missing\fP option for this.
+.PP
+You can also specify that the first color in the palette image
+is the default.  Use the \fB-firstisdefault\fP option for this.
+.PP
+The palette is simply a PNM image.  The colors of the pixels in the
+image are the colors in the palette.  Where the pixels appear in the
+image, and the dimensions of the image, are irrelevant.  Multiple
+pixels of the same color are fine.  However, a palette image is
+typically a single row with one pixel per color.
+.PP
+If you specify \fB-missing\fP, the color you so specify is in
+the palette in addition to whatever is in the palette image.
+.PP
+For historical reasons, Netpbm sometimes calls the palette a
+"colormap." But it doesn't really map anything.
+\fBpnmremap\fP creates its own map, based on the palette, to map
+colors from the input image to output colors.
+
+.UN mismatch
+.SS Palette/Image Type Mismatch
+.PP
+In the simple case, the palette image is of the same depth (number
+of planes, i.e. number of components in each tuple (pixel)) as the
+input image and \fBpnmremap\fP just does a straightforward search of
+the palette for each input tuple (pixel).  In fact, \fBpnmremap\fP
+doesn't even care if the image is a visual image.
+.PP
+But what about when the depths differ?  In that case,
+\fBpnmremap\fP converts the input image (in its own memory) to match
+the palette and then proceeds as above.
+.PP
+There are only two such cases in which \fBpnmremap\fP knows how to
+do the conversion:  when one of them is tuple type RGB, depth 3, and the
+other is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice
+versa.
+.PP
+In any other case, \fBpnmremap\fP issues and error message and fails.
+.PP
+Note that as long as your input and palette images are PNM, they'll
+always fall into one of the cases \fBpnmremap\fP can handle.  There's an
+issue only if you're using some exotic PAM image.
+.PP
+Before Netpbm 10.27 (March 2005), \fBpnmremap\fP could not handle
+the case of a palette of greater depth than the input image.  (It would
+issue an error message and fail in that case).  You can use \fBppmtoppm\fP
+to increase the depth of the input image to work around this limitation.
+.PP
+In any case, the output image has the same tuple type and depth as
+the palette image.
+
+.UN multiple
+.SS Multiple Image Stream
+.PP
+\fBpnmremap\fP handles a multiple image input stream, producing a
+multiple image output stream.  The input images need not be similar in
+any way.
+.PP
+Before Netpbm 10.30 (October 2005), \fBpnmremap\fP ignored any image
+after the first.
+
+
+.UN example
+.SS Examples
+
+.nf
+pnmcolormap testimg.ppm 256 >palette.ppm
+
+pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
+
+.fi
+.PP
+To limit colors to a certain set, a typical example is to create an
+image for posting on the World Wide Web, where different browsers know
+different colors.  But all browsers are supposed to know the 216
+"web safe" colors which are essentially all the colors you
+can represent in a PPM image with a maxval of 5.  So you can do this:
+
+.nf
+pamseq 3 5 >websafe.pam
+
+pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
+
+.fi
+.PP
+Another useful palette is one for the 8 color IBM TTL color set, which
+you can create with
+.nf
+pamseq 3 1 >ibmttl.pam
+
+.fi
+.PP
+If you want to quantize one image to use the colors in another one,
+just use the second one as the palette.  You don't have to reduce it
+down to only one pixel of each color, just use it as is.
+.PP
+The output image has the same type and maxval as the palette image.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+There is one parameter, which is required: The file specification of
+the input PNM file.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmremap\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-mapfile=\fP\fIpalettefilename\fP
+This names the file that contains the palette image.
+.sp
+This option is mandatory.
+
+.TP
+\fB-floyd\fP
+.TP
+\fB-fs\fP
+.TP
+\fB-nofloyd\fP
+.TP
+\fB-nofs\fP
+These options determine whether \fBpnmremap\fP does Floyd-Steinberg
+dithering.  Without Floyd-Steinberg, \fBpnmremap\fP selects the output color
+of a pixel based on the color of only the corresponding input pixel.  With
+Floyd-Steinberg, \fBpnmremap\fP considers regions of pixels such that the
+average color of a region is the same in the output as in the input.  The
+dithering effect appears as a dot pattern up close, but from a distance, the
+dots blend so that you see more colors than are present in the color map.
+.sp
+As an example, if your color map contains only black and white, and
+the input image has 4 adjacent pixels of gray, \fBpnmremap\fP with
+Floyd-Steinberg would generate output pixels black, white, black, white,
+which from a distance looks gray.  But without Floyd-Steinberg,
+\fBpnmremap\fP would generate 4 white pixels, white being the single-pixel
+approximation of gray.
+.sp
+Floyd-Steinberg gives vastly better results on images where
+unmodified quantization has banding or other artifacts, especially
+when going to a small number of colors such as the above IBM set.
+However, it does take substantially more CPU time.
+.sp
+\fB-fs\fP is a synonym for \fB-floyd\fP.  \fB-nofs\fP is a
+synonym for \fB-nofloyd\fP.
+.sp
+The default is \fB-nofloyd\fP.
+.sp
+Before Netpbm 10.46 (March 2009), dithering doesn't work quite as you
+expect if the color map has a lower maxval than the input.  \fBpnmremap\fP
+reduces the color resolution to the color map's maxval before doing any
+dithering, so the dithering does not have the effect of making the image,
+at a distance, appear to have the original maxval.  In current Netpbm, it
+does.
+
+.TP
+\fB-norandom\fP
+This option affects a detail of the Floyd-Steinberg dithering process.
+It has no effect if you aren't doing Floyd-Steinberg dithering.
+.sp
+By default, \fBpnmremap\fP initializes the error propagation
+accumulator to random values to avoid the appearance of unwanted
+patterns.  This is an extension of the original Floyd-Steinberg
+algorithm.
+.sp
+A drawback of this is that the same \fBpnmremap\fP on the same
+input produces slightly different output every time, which makes
+comparison difficult.
+.sp
+With \fB-norandom\fP, \fBpnmremap\fP initializes the error
+accumulators to zero and the output is completely predictable.
+.sp
+Alternatively, you can use \fB-randomseed\fP to get randomization
+across the image, but still have repeatable results.
+.sp
+You cannot specify this along with \fB-randomseed\fP.
+.sp
+\fB-norandom\fP was new in Netpbm 10.39 (June 2007).
+
+
+.TP
+\fB-randomseed=\fP\fIn\fP
+This option affects a detail of the Floyd-Steinberg dithering process.
+It has no effect if you aren't doing Floyd-Steinberg dithering.
+.sp
+This option supplies the seed for the random number generator used in the
+randomization process described in the explanation of the \fB-norandom\fP
+option.  If you run \fBpnmremap\fP twice with the same \fB-randomseed\fP
+value, you will get identical results.
+.sp
+If you do not specify \fB-randomseed\fP, \fBpnmremap\fP chooses a seed
+at random, adding another level of randomness to the dithering.
+.sp
+You cannot specify this along with \fB-norandom\fP.
+.sp
+This option was new in Netpbm 10.82 (March 2018).
+  
+
+.TP
+\fB-firstisdefault\fP
+This tells \fBpnmremap\fP to map any input color that is not in
+the palette to the first color in the palette (the color of the pixel
+in the top left corner of the palette image)
+.sp
+See 
+.UR #description
+DESCRIPTION
+.UE
+\&.
+.sp
+If you specify \fB-firstisdefault\fP, the maxval of your input
+must match the maxval of your palette image.
+
+.TP
+\fB-missingcolor=\fP\fIcolorspec\fP
+This specifies the default color for \fBpnmremap\fP to map to a
+color in the input image that isn't in the palette.  \fIcolor\fP may
+or may not be in the palette image; it is part of the palette
+regardless.
+.sp
+\fIcolorspec\fP is as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+If you specify \fB-missingcolor\fP, the maxval of your input must
+match the maxval of your palette image.
+
+.TP
+\fB-verbose\fP
+Display helpful messages about the mapping process.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pamlookup" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppmquantall" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "ppmquant" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmremap\fP first appeared in Netpbm 9.23 (January 2002).
+Before that, its function was available only as part of the function
+of \fBpnmquant\fP (which was derived from the much older
+\fBppmquant\fP).  Color quantization really has two main subfunctions, so
+Netpbm 9.23 split it out into two separate programs:
+\fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced
+\fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and
+\fBpnmremap\fP.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmremap.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmrotate.1 b/upstream/mageia-cauldron/man1/pnmrotate.1
new file mode 100644
index 00000000..f830f76b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmrotate.1
@@ -0,0 +1,148 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmrotate User Manual" 0 "30 August 2002" "netpbm documentation"
+
+.SH NAME
+pnmrotate - rotate a PNM image by some angle
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmrotate\fP
+[\fB-noantialias\fP] [\fB-background=\fP\fIcolor\fP] \fIangle\fP
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpnmrotate\fP reads a PNM image as input.  It rotates it by the
+specified angle and produces the same kind of PNM image as output.
+.PP
+The input is the file named by \fIpnmfile\fP or Standard Input if you
+don't specify \fIpnmfile\fP.  The output goes to Standard Output.
+.PP
+The resulting image is a rectangle that contains the (rectangular)
+input image within it, rotated with respect to its bottom edge.  The
+containing rectangle is as small as possible to contain the rotated
+image.  The background of the containing image is a single color that
+\fBpnmrotate\fP determines to be the background color of the original
+image, or that you specify explicitly.
+.PP
+\fIangle\fP is in decimal degrees (floating point), measured
+counter-clockwise.  It can be negative, but it should be between -90
+and 90.
+.PP
+You should use \fBpamflip\fP instead for rotations that are a
+multiple of a quarter turn.  It is faster and more accurate.
+.PP
+For rotations greater than 45 degrees you may get better results if
+you first use \fIpamflip\fP to do a 90 degree rotation and then
+\fIpnmrotate\fP less than 45 degrees back the other direction.
+.PP
+The rotation algorithm is Alan Paeth's three-shear method.  Each
+shear is implemented by looping over the source pixels and
+distributing fractions to each of the destination pixels.  This has an
+"anti-aliasing" effect - it avoids jagged edges and similar
+artifacts.  However, it also means that the original colors or gray
+levels in the image are modified.  If you need to keep precisely the
+same set of colors, you can use the \fB-noantialias\fP option.
+.PP
+The program runs faster and uses less real memory with the
+\fB-noantialias\fP option.  It uses a large amount of virtual memory
+either way, as it keeps a copy of the input image and a copy of the
+output image in memory, using 12 bytes per pixel for each.  But with
+\fB-noantialias\fP, it accesses this memory sequentially in half a
+dozen passes, with only a few pages of memory at a time required in
+real memory.
+.PP
+In contrast, without \fB-noantialias\fP, the program's real memory
+working set size is one page per input image row plus one page per output
+image row.  Before Netpbm 10.16 (June 2003), \fB-noantialias\fP had the
+same memory requirement.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmrotate\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+
+.TP
+\fB-background=\fP\fIcolor\fP
+This determines the color of the background on which the rotated image
+sits.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+By default, if you don't specify this option, \fBpnmrotate\fP selects
+what appears to it to be the background color of the original image.  It 
+determines this color rather simplistically, by taking an average of the colors
+of the two top corners of the image.
+.sp
+This option was new in Netpbm 10.15.  Before that, \fBpnmrotate\fP
+always behaved as is the default now.
+
+.TP
+\fB-noantialias\fP
+This option forces \fBpnmrotate\fP to simply move pixels around instead 
+of synthesizing output pixels from multiple input pixels.  The latter could
+cause the output to contain colors that are not in the input, which may not
+be desirable.  It also probably makes the output contain a large number of
+colors.  If you need a small number of colors, but it doesn't matter if they
+are the exact ones from the input, consider using \fBpnmquant\fP on the 
+output instead of using \fB-noantialias\fP.
+.sp
+Note that to ensure the output does not contain colors that are not
+in the input, you also must consider the background color.  See the
+\fB-background\fP option.
+
+
+
+.UN references
+.SH REFERENCES
+
+"A Fast Algorithm for General Raster Rotation" by Alan Paeth,
+Graphics Interface '86, pp. 77-81.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmshear" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmrotate.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmscale.1 b/upstream/mageia-cauldron/man1/pnmscale.1
new file mode 100644
index 00000000..fa02e761
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmscale.1
@@ -0,0 +1,37 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmscale User Manual" 0 "02 February 2009" "netpbm documentation"
+
+.SH NAME
+
+pnmscale - replaced by pamscale
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmscale\fP was obsoleted by
+.BR "\fBpamscale\fP" (1)\c
+\&, introduced with Netpbm 10.20
+(January 2004).  \fBpamscale\fP is backward compatible with \fBpnmscale\fP,
+plus adds many additional functions, including the ability to process PAM
+images.
+.PP
+\fBpnmscale\fP remained in the Netpbm package until Netpbm 10.46 (March
+2009) because of hopes that it had fewer bugs than \fBpamscale\fP because of
+its age.  But now it would just be clutter.
+.PP
+In Netpbm before 10.20, use the manual for \fBpamscale\fP with
+\fBpnmscale\fP.  Features that are in \fBpamscale\fP but not \fBpnmscale\fP
+are indicated by statements that they didn't exist before 10.20.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmscale.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmscalefixed.1 b/upstream/mageia-cauldron/man1/pnmscalefixed.1
new file mode 100644
index 00000000..f312efec
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmscalefixed.1
@@ -0,0 +1,138 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmscalefixed User Manual" 0 "01 July 2020" "netpbm documentation"
+
+.SH NAME
+
+pnmscalefixed - scale a PNM file quickly
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpnmscalefixed\fP is like \fBpamscale\fP except that
+it uses fixed point arithmetic internally instead of floating point,
+which may make it run faster.  In turn, it is less accurate and may
+distort the image.  It also lacks many of the features of \fBpamscale\fP.
+.PP
+Use the \fBpamscale\fP user manual with \fBpnmscalefixed\fP.  This
+document only describes the difference.  Avoid any feature mentioned in
+the \fBpamscale\fP manual as not existing before Netpbm 9.9.
+.PP
+\fBpnmscalefixed\fP uses fixed point 12 bit arithmetic.  By
+contrast, \fBpamscale\fP uses floating point arithmetic which on most
+machines is probably 24 bit precision.  This makes
+\fBpnmscalefixed\fP run faster (30% faster in one experiment), but
+the imprecision can cause distortions at the right and bottom edges.
+.PP
+The distortion takes the following form: One pixel from the edge of
+the input is rendered larger in the output than the scaling factor
+requires.  Consequently, the rest of the image is smaller than the
+scaling factor requires, because the overall dimensions of the image
+are always as requested.  This distortion will usually be very hard to
+see.
+.PP
+\fBpnmscalefixed\fP with the \fB-verbose\fP option tells you how
+much distortion there is.
+.PP
+The amount of distortion depends on the size of the input image and how
+close the scaling factor is to an integral 1/4096th.
+.PP
+If the scaling factor is an exact multiple of 1/4096, there is no
+distortion.  So, for example doubling or halving an image causes no
+distortion.  But reducing it or enlarging it by a third would cause
+some distortion.  To consider an extreme case, scaling a 100,000 row
+image down to 50,022 rows would create an output image with all of the
+input squeezed into the top 50,000 rows, and the last row of the input
+copied into the bottom 22 rows of output.
+.PP
+\fBpnmscalefixed\fP could probably be modified to use 16 bit or
+better arithmetic without losing anything.  The modification would
+consist of a single constant in the source code.  Until there is a
+demonstrated need for that, though, the Netpbm maintainer wants to
+keep the safety cushion afforded by the original 12 bit precision.
+.PP
+\fBpnmscalefixed\fP does not have \fBpamscale\fP's \fB-nomix\fP
+option.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmscalefixed\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-xsize\fP
+.TP
+\fB-width\fP
+.TP
+\fB-ysize\fP
+.TP
+\fB-height\fP
+.TP
+\fB-xscale\fP
+.TP
+\fB-yscale\fP
+.TP
+\fB-pixels\fP
+.TP
+\fB-xysize\fP
+.TP
+\fB-reduce\fP
+.sp
+These options determine the scale factors.  See the
+.BR "\fBpamscale\fP" (1)\c
+\& user manual for details.
+
+.TP
+\fB-verbose\fP
+.sp
+Report details of the transformation.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmscalefixed\fP was originally \fBpnmscale\fP. In Netpbm 9.9
+(November 2000) \fBpnmscale\fP was rewritten to use floating point
+arithmetic; the former fixed point arithmetic version was renamed
+\fBpnmscalefixed\fP.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamscale" (1)\c
+\&,
+.BR "pamstretch" (1)\c
+\&,
+.BR "pamstretch-gen" (1)\c
+\&,
+.BR "pbmreduce" (1)\c
+\&,
+.BR "pbmpscale" (1)\c
+\&,
+.BR "pamenlarge" (1)\c
+\&,
+.BR "pnmscale" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmscalefixed.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmshear.1 b/upstream/mageia-cauldron/man1/pnmshear.1
new file mode 100644
index 00000000..60f40a2f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmshear.1
@@ -0,0 +1,141 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmshear User Manual" 0 "22 March 2020" "netpbm documentation"
+
+.SH NAME
+pnmshear - shear a PNM image by a specified angle
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmshear\fP
+
+[\fB-noantialias\fP] [\fB-background=\fP\fIcolor\fP]
+\fIangle\fP [\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or equals signs between an option name and
+its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmshear\fP reads a PNM image as input and shears it by the
+specified angle and produce a PNM image as output.  If the input file
+is in color, the output will be too, otherwise it will be grayscale.
+The angle is in degrees (floating point), and measures this:
+
+.nf
+    +-------+  +-------+
+    |       |  |\e       \e
+    |  OLD  |  | \e  NEW  \e
+    |       |  |an\e       \e
+    +-------+  |gle+-------+
+
+.fi
+
+If the angle is negative, it shears the other way:
+.nf
+    +-------+  |-an+-------+
+    |       |  |gl/       /
+    |  OLD  |  |e/  NEW  /
+    |       |  |/       /
+    +-------+  +-------+
+
+.fi
+
+The angle should not get too close to 90 or -90, or the resulting image will
+be unreasonably wide.  In fact, if it gets too close, the width will be so
+large that \fBpnmshear\fP cannot do computations in the word sizes it uses,
+and the program detects this and fails.
+.PP
+\fBpnmshear\fP does the shearing by looping over the source pixels
+and distributing fractions to each of the destination pixels.  This
+has an "anti-aliasing" effect - it avoids jagged edges and
+similar artifacts.  However, it also means that the original colors in
+the image are modified and there are typically more of them than you
+started with.  If you need to keep precisely the same set of colors,
+see the \fB-noantialias\fP option.  If the expanded palette is a
+problem, you can run the result through \fBpnmquant\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmshear\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-background=\fP\fIcolor\fP
+This determines the color of the background on which the sheared image
+sits.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+By default, if you don't specify this option, \fBpnmshear\fP selects
+what appears to it to be the background color of the original image.  It 
+determines this color rather simplistically, by taking an average of the colors
+of the two top corners of the image.
+.sp
+This option was new in Netpbm 10.37 (December 2006).  Before that,
+\fBpnmshear\fP always behaved as is the default now.
+
+.TP
+\fB-noantialias\fP
+This option forces \fBpnmshear\fP to simply move pixels around instead 
+of synthesizing output pixels from multiple input pixels.  The latter could
+cause the output to contain colors that are not in the input, which may not
+be desirable.  It also probably makes the output contain a large number of
+colors.  If you need a small number of colors, but it doesn't matter if they
+are the exact ones from the input, consider using \fBpnmquant\fP on the 
+output instead of using \fB-noantialias\fP.
+.sp
+Note that to ensure the output does not contain colors that are not
+in the input, you also must consider the background color.  See the
+\fB-background\fP option.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmrotate" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "pamhomography" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pamrestack" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmshear.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmsmooth.1 b/upstream/mageia-cauldron/man1/pnmsmooth.1
new file mode 100644
index 00000000..7912d9f1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmsmooth.1
@@ -0,0 +1,143 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmsmooth User Manual" 0 "19 December 2009" "netpbm documentation"
+
+.SH NAME
+pnmsmooth - smooth out an image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmsmooth\fP
+[\fB-width=\fP\fIcols\fP] [\fB-height=\fP\fIrows\fP]
+[\fIpnmfile\fP] [\fB-size\fP]
+.PP
+Minimum unique abbreviations of options is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmsmooth\fP smoothes out an image by replacing each pixel with the
+average of its width X height neighbors.  It is implemented as a progam that
+invokes \fBpnmconvol\fP with an appropriate convolution matrix.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmsmooth\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-width=\fP\fIcols\fP
+.TP
+\fB-height=\fP\fIrows\fP
+These options specify the dimensions of the convolution matrix.
+Default dimensions are 3 wide and 3 high.
+.sp
+Before Netpbm 10.49 (December 2009), the maximum size of the convolution
+matrix is limited by the maxval of the image such that width * height * 2 must
+not exceed the maxval.  (use \fBpamdepth\fP to increase the maxval if
+necessary).
+.sp
+These options were new in Netpbm 10.32 (February 2006).  Before that,
+use \fB-size\fP.
+
+.TP
+\fB-size\fP
+This deprecated option exists in current Netpbm for backward
+compatibility.  It was obsoleted by \fB-width\fP and \fB-height\fP
+in Netpbm 10.32 (February 2006).
+.sp
+When you use this option, the first two program arguments are the width
+and height, respectively, of the convolution matrix and do the same thing
+as the \fB-width\fP and \fB-height\fP option values.  The third
+(optional) program argument is the input file name.
+.sp
+In reality, in old \fBpnmsmooth\fP, the width and height are two
+values of the \fB-size\fP option, but the modern Netpbm command syntax
+paradigm doesn't allow an option with multiple values, so instead
+\fB-size\fP is an option with no value and width and height are program
+arguments.  That has the fortunate effect of making the following command
+mean the same in current \fBpnmsmooth\fP as in old \fBpnmsmooth\fP:
+.nf
+\f(CW
+     pnmsmooth -size 5 5 infile.ppm >outfile.ppm
+\fP
+
+.fi
+
+.TP
+\fB-dump=\fP\fIdumpfile\fP
+This options makes \fBpnmsmooth\fP only show you the
+convolution matrix.  It writes to Standard Output a \fBpnmconvol\fP
+\fB-matrix\fP option value that represents the matrix.  It does not
+invoke \fBpnmconvol\fP and does not produce an output image.
+.sp
+Before Netpbm 10.49 (December 2009), this option is rather different.
+It takes a file name as a value, and it writes to that file the
+convolution matrix as a PGM file (as used to be the normal input for
+\fBpnmconvol\fP).
+
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Before Netpbm 10.32 (February 2006), \fBpnmsmooth\fP did not use
+the modern Netpbm command line parser, so had an unconventional command line
+syntax.  Most importantly, you could not use an equal sign or double
+hyphens in the options.
+.PP
+Before Netpbm 10.49 (December 2009), there was a \fB-dump\fP option.
+This strange option caused \fBpnmsmooth\fP not to do any smoothing or
+produce any output image but instead write the convolution matrix it
+would have used, as PGM file such as \fBpnmconvol\fP used to use, to
+a file you specify.  The idea was you could then use that file with a
+separate invocation of \fBpnmconvol\fP.
+.PP
+Then, in Netpbm 10.49, there was a rather different \fB-dump\fP
+option with a similar purpose: It caused \fBpnmsmooth\fP to write to
+Standard Error a string suitable as a value for the \fBpnmconvol\fP
+\fB-matrix\fP option (an option that was new in Netpbm 10.49).
+.PP
+But in Netpbm 10.51 (June 2010), \fBpnmconvol\fP started using the even
+newer \fBpnmconvol\fP \fB-normalize\fP option (new in 10.50), which made
+specifying the convolution matrix for the kind of smoothing that
+\fBpnmsmooth\fP does trivial, so \fB-dump\fP disappeared from
+\fBpnmsmooth\fP.
+.PP
+(There were also ease of implementation issues that kept us from simply
+keeping the original \fB-dump\fP around for backward compatibility: As we
+modified \fBpnmsmooth\fP to take advantage of the new features of
+\fBpnmconvol\fP, which \fBpnmsmooth\fP uses internally, the information
+needed to implement \fB-dump\fP was no longer available in the program).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmsmooth.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmsplit.1 b/upstream/mageia-cauldron/man1/pnmsplit.1
new file mode 100644
index 00000000..b2aa6b1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmsplit.1
@@ -0,0 +1,31 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmsplit User Manual" 0 "23 October 2005" "netpbm documentation"
+
+.SH NAME
+
+pnmsplit - replaced by pamsplit
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Starting with Netpbm 10.31 (December 2005), \fBpnmsplit\fP is
+obsolete.  Use
+.BR "\fBpamsplit\fP" (1)\c
+\& instead.
+
+\fBpamsplit\fP is backward compatible with \fBpnmsplit\fP.  You can
+use the \fBpamsplit\fP manual for \fBpnmsplit\fP as long as you ignore
+features that were added after Netpbm 10.30.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmsplit.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmstitch.1 b/upstream/mageia-cauldron/man1/pnmstitch.1
new file mode 100644
index 00000000..b141dbb4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmstitch.1
@@ -0,0 +1,138 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmstitch User Manual" 0 "July 2002" "netpbm documentation"
+
+.SH NAME
+pnmstitch - stitch together two panoramic (side-by-side) photographs
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmstitch\fP
+[
+[\fIleft_filespec\fP] \fIright_filespec\fP |
+\fIleft_filespec\fP \fIright_filespec\fP \fIoutput_filespec\fP
+]
+[\fB-width=\fP\fIwidth\fP]
+[\fB-height=\fP\fIheight\fP]
+[\fB-xrightpos=\fP\fIcolumn\fP]
+[\fB-yrightpos=\fP\fIrow\fP]
+[\fB-stitcher=\fP{\fBRotateSliver\fP,
+\fBBiLinearSliver\fP,\fBLinearSliver\fP}]
+[\fB-filter=\fP{\fBLineAtATime\fP,\fBHorizontalCrop\fP}]
+[\fB-output=\fP\fIoutput_filespec\fP]
+[\fB-verbose\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmstitch\fP stitches together two panoramic photographs.  This
+means if you have photographs of the left and right side of something
+that is too big for a single camera frame, \fBpnmstitch\fP can join them
+into one wide picture.
+.PP
+\fBpnmstitch\fP works only on side-by-side images, not top and bottom
+(though you could certainly use \fBpamflip\fP in combination with
+\fBpnmstitch\fP to achieve this).  It stitches together two images, but
+you can use it repeatedly to stitch together as many as you need to.
+.PP
+Your photographs must overlap in order for \fBpnmstitch\fP to
+work, and the overlap should be substantial.  \fBpnmstitch\fP shifts
+and stretches the right hand image to match it up the left hand image.
+You probably want to crop the result with \fBpamcut\fP to make a nice
+rectangular image.
+.PP
+If you're just trying to join (concatenate) two images at their edges, use
+\fBpnmcat\fP.
+.PP
+The \fIleft_filespec\fP and \fIright_filespec\fP arguments are the
+specifications (names) of the PNM files containing the left hand and
+right hand images.  If you specify only \fIright_filespec\fP, the
+left hand image comes from Standard Input.  If you specify neither, both
+images come from Standard Input as a multi-image file containing first the
+left and then the right image.
+.PP
+\fIoutput_filespec\fP is the specification (name) of the output PNM file.
+The \fB-output\fP option also specifies the output file.  You cannot specify
+both the argument and the option.  If you specify neither, the output goes to
+Standard Output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmstitch\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-width=\fIwidth\fP\fP
+.TP
+\fB-height=\fIheight\fP\fP
+.TP
+\fB-xrightpos=\fIcolumn\fP\fP
+.TP
+\fB-yrightpos=\fIrow\fP\fP
+These are constraints on where \fBpnmstitch\fP stitches the images together.
+For the \fBLinearSliver\fP method, \fIcolumn\fP and \fIrow\fP tell what
+location in the right hand image matches up to the top right corner of the
+left hand image.
+     
+.TP
+\fB-stitcher=\fP{\fBRotateSliver\fP,\fBBiLinearSliver\fP,
+\fBLinearSliver\fP}
+The default is \fBRotateSliver\fP.
+
+.TP
+\fB-filter=\fP{\fBLineAtATime\fP,\fBHorizontalCrop\fP}
+No details available.
+     
+.TP
+\fB-output=\fP\fIoutput_filespec\fP
+Name of output file.  If you don't specify this option, the output image
+goes to Standard Output.
+
+.TP
+\fB-verbose\fP
+This option causes \fBpnmstitch\fP to issue messages to Standard Error
+about the stitching process.
+     
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcut" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.7 (August 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmstitch.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtile.1 b/upstream/mageia-cauldron/man1/pnmtile.1
new file mode 100644
index 00000000..12679e4d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtile.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtile User Manual" 0 "01 April 2007" "netpbm documentation"
+
+.SH NAME
+pnmtile - replicate an image to fill a specified region
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtile\fP
+\fIwidth\fP
+\fIheight\fP
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtile\fP reads a PNM image as input.  It replicates it to fill
+an area of the specified dimensions and produces an image in the same
+format as output.
+.PP
+You can do pretty much the reverse with \fBpamdice\fP.
+.PP
+You can explicitly concatenate an image to itself (or anything else)
+with \fBpnmcat\fP.
+.PP
+If you're trying to tile multiple images into a superimage,
+see \fBpamundice\fP or (for a thumbnail sheet) \fBpnmindex\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpnmtile\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamundice" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&,
+.BR "pamdice" (1)\c
+\&,
+.BR "pnmindex" (1)\c
+\&,
+.BR "pampop9" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtile.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtoddif.1 b/upstream/mageia-cauldron/man1/pnmtoddif.1
new file mode 100644
index 00000000..d75ab548
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtoddif.1
@@ -0,0 +1,93 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtoddif User Manual" 0 "2003" "netpbm documentation"
+
+.SH NAME
+
+pnmtoddif - Convert a PNM image to DDIF format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtoddif\fP
+[\fB-resolution\fP \fIx\fP \fIy\fP]
+[\fIpnmfile\fP [\fIddiffile\fP]]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtoddif\fP takes a PNM image and converts it into a DDIF image
+file.
+.PP
+\fBpnmtoddif\fP writes PBM format (bitmap) data as a 1 bit DDIF,
+PGM format data (grayscale) as an 8 bit grayscale DDIF, and PPM format
+(color) data as an 8,8,8 bit color DDIF.  \fBpnmtoddif\fP writes any
+DDIF image file uncompressed.  The data plane organization is
+interleaved by pixel.
+.PP
+In addition to the number of pixels in the width and height
+dimension, DDIF images also carry information about the size that the
+image should have, that is, the physical space that a pixel occupies.
+Netpbm images do not carry this information, hence you have to supply
+it externally.  The default of 78 dpi has the beneficial property of
+not causing a resize on most Digital Equipment Corporation color
+monitors.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtoddif\fP recognizes the following
+command line option:
+
+
+.TP
+\fBresolution\fP \fIx\fP \fIy\fP
+The horizontal and vertical resolution of the output image in dots
+per inch.  Default is 78 dpi.
+
+
+
+.UN arguments
+.SH ARGUMENTS
+
+
+.TP
+\fIpnmfile\fP
+The filename for the image file in pnm format.  Default is to
+read from Standard Input.
+
+.TP
+\fIddiffile\fP
+The filename for the image file to be created in DDIF format.  By
+default, \fBpnmtoddif\fP writes to Standard Output.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Burkhard Neidecker-Lutz, Digital Equipment Corporation, CEC Karlsruhe
+\fIneideck@nestvx.enet.dec.com\fP
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtoddif.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtofiasco.1 b/upstream/mageia-cauldron/man1/pnmtofiasco.1
new file mode 100644
index 00000000..50677e7e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtofiasco.1
@@ -0,0 +1,403 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtofiasco User Manual" 0 "12 July 2000" "netpbm documentation"
+
+.SH NAME
+
+pnmtofiasco - Convert PNM file to FIASCO compressed file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtofiasco\fP
+[\fIoption\fP]...
+[\fIfilename\fP]...
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpnmtofiasco\fP compresses the named pbm, pgm, or ppm image files,
+or Standard Input if no file is named, and produces a FIASCO file on
+Standard Output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtofiasco\fP recognizes the following
+command line options:
+.PP
+All option names may be abbreviated; for example, --optimize may be
+written --optim or --opt. For most options a one letter short option
+is provided.  Mandatory or optional arguments to long options are
+mandatory or optional for short options, too.  Both short and long
+options are case sensitive.
+
+.UN basicopts
+.SS Basic Options
+
+
+.TP
+\fB-i\fP \fIname\fP, \fB--input-name=\fP\fIname\fP
+Compress the named images, not Standard Input.  If \fIname\fP is
+\fB-\fP, read Standard Input.  \fIname\fP has to be either an image
+filename or a template of the form:
+
+.nf
+prefix[start-end{+,-}step]suffix
+
+.fi
+.sp
+Templates are useful when compressing video streams: e.g., if you
+specify the template \fBimg0[12-01-2].pgm\fP, then \fBpnmtofiasco\fP
+compresses the images img012.pgm, img010.pgm, ..., img002.pgm.
+.sp
+If \fIname\fP is a relative path, \fBpnmtofiasco \fP searches for
+the image files in the current directory and in the (colon-separated)
+list of directories given by the environment variable
+\fBFIASCO_IMAGES\fP.
+
+.TP
+\fB-o\fP \fIoutput-file\fP, \fB--output-name=\fP\fIname\fP
+Write FIASCO output to the named file, not to Standard Output.
+.sp
+If \fIname\fP is a relative path and the environment variable
+\fBFIASCO_DATA\fP is a (colon-separated) list of directories, then
+\fBpnmtofiasco\fP writes the output file to the first (writable)
+directory of this list. Otherwise, \fBpnmtofiasco\fP write it to the
+current directory.
+
+.TP
+\fB-q\fP \fIN\fP, \fB--quality=\fP\fIN\fP
+Set quality of compression to \fIN\fP.  Quality is 1 (worst) to
+100 (best); default is 20.
+
+.TP
+\fB-v\fP, \fB--version\fP
+Print \fBpnmtofiasco\fP version number, then exit.
+
+.TP
+\fB-V\fP \fIN\fP, \fB--verbose \fP\fIN\fP
+Set level of verbosity to \fIN\fP.  Level is 0 (no output at
+all), 1 (show progress meter), or 2 (show detailed compression
+statistics); default is 1.
+
+.TP
+\fB-B\fP \fIN\fP, \fB--progress-meter \fP\fIN\fP
+Set type of progress-meter to \fIN\fP.  The following types are
+available; default is 1:
+
+
+.TP
+\fB0\fP
+no progress meter
+
+.TP
+\fB1\fP
+RPM style progress bar using 50 hash marks
+
+.TP
+\fB2\fP
+percentage meter
+
+
+
+.TP
+\fB-f\fP \fIname\fP, \fB--config=\fP\fIname\fP
+Load parameter file \fIname \fP to initialize the options of
+\fBpnmtofiasco\fP.  See file \fBsystem.fiascorc\fP for an example of
+the syntax. Options of \fBpnmtofiasco\fP are set by any of the
+following methods (in the specified order):
+
+
+.IP \(bu
+Global resource file \fB/etc/system.fiascorc\fP
+.IP \(bu
+$HOME/.fiascorc
+.IP \(bu
+command line
+.IP \(bu
+--config=\fIname\fP
+
+
+.TP
+\fB-h\fP, \fB--info\fP
+Print brief help, then exit.
+
+.TP
+\fB-H\fP, \fB--help\fP
+Print detailed help, then exit.
+
+
+
+.UN advancedopts
+.SS Options for Advanced Users
+
+
+.TP
+\fB-b\fP \fIname\fP, \fB--basis-name=\fP\fIname\fP
+Preload compression basis \fIname\fP into FIASCO.  The basis
+\fIname\fP provides the initial compression dictionary.  Either use
+one of the files "small.fco", "medium.fco", or
+"large.fco" that come with \fBpnmtofiasco \fP or create a
+new ASCII basis file.
+
+.TP
+\fB-z\fP \fIN\fP, \fB--optimize=\fP\fIN\fP 
+Set optimization level to \fIN\fP.  Level is 0 (fastest) to 3
+(slowest); default is 1.  Be warned, the encoding time dramatically
+increased when \fIN\fP=\fB2\fP or \fIN\fP=\fB3\fP while the
+compression performance only slightly improves.
+
+.TP
+\fB-P\fP, \fB--prediction\fP
+Use additional predictive coding.  If this optimization is enabled
+then the image is compressed in two steps.  In the first step, a coarse
+approximation of the image is computed using large unichrome
+blocks.  Finally, the delta image is computed and the prediction error
+is approximated using the standard FIASCO algorithm.
+
+.TP
+\fB-D\fP \fIN\fP, \fB--dictionary-size=\fP\fIN\fP
+Set size of dictionary that is used when coding the luminance band
+to \fIN\fP; default is 10000, i.e., the dictionary is not restricted.
+
+.TP
+\fB-C\fP \fIN\fP, \fB--chroma-dictionary=\fP\fIN\fP
+Set size of dictionary that is used when coding chroma bands to
+\fIN\fP; default is 40.
+
+.TP
+\fB-Q\fP \fIN\fP, \fB--chroma-qfactor=\fP\fIN\fP
+Reduce the quality of chroma band compression \fIN\fP-times with
+respect to the user defined quality \fIq\fP of the luminance band
+compression (\fB--quality\fP=\fIq\fP); default is 2.
+
+.TP
+\fB-t\fP \fIN\fP, \fB--tiling-exponent=\fP\fIN\fP
+Subdivide the image into 2^\fIN\fP tiles prior coding; default is
+4, i.e. the image is subdivided into 16 tiles. The processing order of
+the individual tiles is defined by the option
+\fB--tiling-method=\fP\fIname\fP.
+
+.TP
+\fB-T\fP \fIname\fP, \fB--tiling-method=\fP\fIname\fP
+Order the individual image tiles (the image is subdivided into;
+see option \fB--tiling-exponent=\fP\fIN\fP) by method \fIname\fP;
+default is \fBdesc-variance\fP.
+
+
+.TP
+\fBdesc-variance\fP
+Tiles with small variances are processed first.
+
+.TP
+\fBasc-variance\fP
+Tiles with large variances are processed first.
+
+.TP
+\fBdesc-spiral\fP
+Tiles are process in spiral order starting in the middle. 
+
+.TP
+\fBasc-spiral\fP
+Tiles are process in spiral order starting at the border.
+
+
+
+.TP
+\fB--rpf-mantissa=\fP\fIN\fP
+Use \fIN\fP mantissa bits for quantized coefficients.
+
+.TP
+\fB--dc-rpf-mantissa=\fP\fIN\fP
+Use \fIN\fP mantissa bits for quantized DC coefficients.
+
+.TP
+\fB--rpf-range=\fP\fIN\fP
+Coefficients outside the quantization interval
+[-\fIN\fP,+\fIN\fP] are set to zero.
+
+.TP
+\fB--dc-rpf-range=\fP\fIN\fP
+DC coefficients outside the quantization interval
+[-\fIN\fP,+\fIN\fP] are set to zero.
+
+
+
+.UN videoopts
+.SS Additional Options for Video Compression
+
+
+.TP
+\fB-s\fP \fIN\fP, \fB--smooth=\fP\fIN\fP
+Smooth decompressed reference frames along the partitioning
+borders by the given amount \fIN\fP.  \fIN\fP is 0 (no smoothing) to
+100; default is 70.  This factor is stored in the FIASCO file.
+
+.TP
+\fB-m\fP \fIN\fP, \fB--min-level=\fP\fIN\fP
+Start prediction (motion compensated prediction or additional
+prediction) on block level \fIN\fP; default is level 6.  I.e., motion
+compensation is applied to all image blocks of at least 8x8 pixels
+(binary tree level \fIN\fP=6), 16x8 (\fIN\fP=7), 16x16 (\fIN\fP=8),
+etc.
+
+.TP
+\fB-M\fP \fIN\fP, \fB--max-level=\fP\fIN\fP
+Stop prediction (motion compensated prediction or additional
+prediction) on block level \fIN\fP; default is level 10.  I.e.,
+motion compensation is applied to all image blocks of at most 16x16
+pixels (\fIN\fP=8), 32x16 (\fIN\fP=9), 32x32 (\fIN\fP=10), etc.
+
+.TP
+\fB-2\fP, \fB--half-pixel\fP
+Use half pixel precise motion compensation.
+
+.TP
+\fB-F\fP \fIN\fP, \fB--fps=\fP\fIN\fP
+Set number of frames per second to \fIN\fP.  This value is stored
+in the FIASCO output file and is used in the decoder
+.BR "fiascotopnm" (1)\c
+\& to control the framerate.
+
+.TP
+\fB-p\fP \fItype\fP, \fB--pattern=\fP\fItype\fP
+Defines the type of inter frame compression which should be
+applied to individual frames of a video stream.  \fItype\fP is a
+sequence of characters; default is "IPPPPPPPPP".  Element
+\fBN\fP defines the type of predicting which should be used for frame
+\fBN\fP; the frame type pattern is periodically extended.  Valid
+characters are:
+
+
+.TP
+\fBI\fP
+intra frame, i.e., no motion compensated prediction is used at
+all.
+
+.TP
+\fBP\fP
+predicted frame, i.e., a previously encoded frame is used for
+prediction (forward prediction).
+
+.TP
+\fBB\fP
+bidirectional predicted frame, i.e., not only a previously shown
+frame but also a frame of the future is used for prediction (forward,
+backward or interpolated prediction).
+
+
+
+.TP
+\fB--cross-B-search\fP
+Instead of using exhaustive search the "Cross-B-Search"
+algorithm is used to find the best interpolated prediction of
+B-frames.
+
+.TP
+\fB--B-as-past-ref\fP
+Also use previously encoded B-frames when prediction the current
+frame. If this option is not set, only I- and P-frames are used to
+predict the current frame.
+
+
+
+
+.UN examples
+.SH EXAMPLES
+.PP
+Compress the still image "foo.ppm" to the FIASCO file
+"foo.wfa" using the default options:
+
+.nf
+        pnmtofiasco < foo.ppm >foo.wfa
+
+.fi
+.PP
+Compress the video frames "foo0*.ppm" to the FIASCO file
+"video.wfa" using half pixel precise motion compensation at
+a frame rate of 15 frames per second.  Intra frame 1 is used to
+predict P-frame 4, frames 1 and 4 are used to predict B-frames 2 and
+3, and so on.  Frame 10 is again an intra-frame.
+
+.nf
+        pnmtofiasco -2 -p "IBBPBBPBB" -fps 15 -o video.wfa foo0*.ppm
+
+.fi
+
+.UN files
+.SH FILES
+
+
+.TP
+\fB/etc/system.fiascorc\fP
+The systemwide initialization file.
+
+.TP
+$HOME\fB/.fiascorc\fP
+The personal initialization file.
+
+
+
+.UN environment
+.SH ENVIRONMENT
+
+
+
+
+.TP
+\fBFIASCO_IMAGES\fP
+Search path for image files.  Default is "./".
+
+.TP
+\fBFIASCO_DATA\fP
+Search and save path for FIASCO files.  Default is "./".
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "fiascotopnm" (1)\c
+\&,
+.BR "pnmtojpeg" (1)\c
+\&,
+.BR "pnmtojbig" (1)\c
+\&,
+.BR "pamtogif" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+.PP
+Ullrich Hafner, Juergen Albert, Stefan Frank, and Michael Unger.
+\fBWeighted Finite Automata for Video Compression\fP, IEEE Journal on
+Selected Areas In Communications, January 1998
+.PP
+Ullrich Hafner. \fBLow Bit-Rate Image and Video Coding with
+Weighted Finite Automata\fP, Ph.D. thesis, Mensch & Buch Verlag,
+ISBN 3-89820-002-7, October 1999.
+.PP
+FIASCO: An Open-Source Fractal Image and Sequence Codec, Linux Journal,
+January 2001.
+
+.UN author
+.SH AUTHOR
+
+Ullrich Hafner <\fIhafner@bigfoot.de\fP>
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtofiasco.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtofits.1 b/upstream/mageia-cauldron/man1/pnmtofits.1
new file mode 100644
index 00000000..894c5c40
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtofits.1
@@ -0,0 +1,28 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "pnmtofits" 1 "September 2005" "netpbm documentation"
+
+.SH NAME
+
+pnmtofits - replaced by pamtofits
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+In Netpbm 10.30 (October 2005), \fBpnmtofits\fP was extended and renamed to
+.BR "pamtofits" (1)\c
+\&.
+.PP
+\fBpamtofits\fP is backward compatible with \fBpnmtofits\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtofits.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtojpeg.1 b/upstream/mageia-cauldron/man1/pnmtojpeg.1
new file mode 100644
index 00000000..b302b44b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtojpeg.1
@@ -0,0 +1,560 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtojpeg User Manual" 0 "23 April 2007" "netpbm documentation"
+
+.SH NAME
+pnmtojpeg - convert PNM image to a JFIF ("JPEG") image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtojpeg\fP
+[\fB-exif=\fP\fIfilespec\fP]
+[\fB-quality=\fP\fIn\fP]
+[{\fB-grayscale\fP|\fB-greyscale\fP}]
+[\fB-density=\fP\fIn\fP\fBx\fP\fIn\fP[\fBdpi\fP,\fBdpcm\fP]]
+[\fB-optimize\fP|\fB-optimise\fP]
+[\fB-rgb\fP]
+[\fB-progressive\fP]
+[\fB-comment=\fP\fItext\fP]
+[\fB-dct=\fP{\fBint\fP|\fBfast\fP|\fBfloat\fP}]
+[\fB-arithmetic\fP]
+[\fB-restart=\fP\fIn\fP]
+[\fB-smooth=\fP\fIn\fP]
+[\fB-maxmemory=\fP\fIn\fP]
+[\fB-verbose\fP]
+[\fB-baseline\fP]
+[\fB-qtables=\fP\fIfilespec\fP]
+[\fB-qslots=n[,...]\fP]
+[\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]]
+[\fB-scans=\fP\fIfilespec\fP]
+[\fB-tracelevel=\fP\fIN\fP]
+
+\fIfilename\fP
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtojpeg\fP converts the named PBM, PGM, or PPM image file, or
+the standard input if no file is named, to a JFIF file on the standard
+output.
+.PP
+\fBpnmtojpeg\fP uses the Independent JPEG Group's JPEG library to
+create the output file.  See \fB
+.UR http://www.ijg.org
+http://www.ijg.org
+.UE
+\& \fP for information
+on the library.
+.PP
+"JFIF" is the correct name for the image format commonly
+known as "JPEG." Strictly speaking, JPEG is a method of
+compression.  The image format using JPEG compression that is by far
+the most common is JFIF.  There is also a subformat of TIFF that uses
+JPEG compression.
+.PP
+EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
+file that contains an EXIF header as an APP1 marker).
+\fBpnmtojpeg\fP creates an EXIF image when you specify the
+\fB-exif\fP option.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtojpeg\fP recognizes the following
+command line options:
+
+.UN basicopts
+.SS Basic Options
+
+
+.TP
+\fB-exif=\fP\fIfilespec\fP
+This option specifies that the output image is to be EXIF (a subformat
+of JFIF), i.e. it will have an EXIF header as a JFIF APP1 marker.
+The contents of that marker are the contents of the specified file.
+The special value \fB-\fP 
+means to read the EXIF header contents from standard input.  It is
+invalid to specify standard input for both the EXIF header and the
+input image.
+.sp
+The EXIF file starts with a two byte field which is the length of
+the file, including the length field, in pure binary, most significant
+byte first.  The special value of zero for the length field means there
+is to be no EXIF header, i.e. the same as no \fB-exif\fP
+option.  This is useful for when you convert a file from JFIF to PNM
+using \fBjpegtopnm\fP,
+then transform it, then convert it back to JFIF with
+\fBpnmtojpeg\fP, and you don't know whether or not it includes an EXIF header.
+\fBjpegtopnm\fP
+creates an EXIF file containing nothing but two bytes of zero when
+the input JFIF file has no EXIF header.  Thus, you can transfer
+any EXIF header from the input JFIF to the output JFIF without
+worrying about whether an EXIF header actually exists.
+.sp
+The contents of the EXIF file after the length field are the exact
+byte for byte contents of the APP1 marker, not counting the length
+field, that constitutes the EXIF header.
+
+.TP
+\fB-quality=\fP\fIn\fP
+Scale quantization tables to adjust image quality.  \fIn\fP is 0
+(worst) to 100 (best); default is 75.  Below about 25 can produce images
+some interpreters won't be able to interpret.  See below for more info.
+
+.TP
+\fB-grayscale\fP
+.TP
+\fB-greyscale\fP
+.TP
+\fB-rgb\fP
+These options determine the color space used in the JFIF output.
+\fB-grayscale\fP (or \fB-greyscale\fP) means to create a gray scale
+JFIF, converting from color PPM input if necessary.  \fB-rgb\fP means to
+create an RGB JFIF, and the program fails if the input is not PPM.
+.sp
+If you specify neither, The output file is in YCbCr format if the
+input is PPM, and grayscale format if the input is PBM or PGM.
+.sp
+YCbCr format (a color is represented by an intensity value and two
+chrominance values) usually compresses much better than RGB (a color
+is represented by one red, one green, and one blue value).  RGB is
+rare.  But you may be able to convert between JFIF and PPM faster with
+RGB, since it's the same color space PPM uses.
+.sp
+The \fBtestimg.ppm\fP file that comes with Netpbm is 2.3 times
+larger with the \fB-rgb\fP option than with the YCbCr default, and in
+one experiment \fBpnmtojpeg\fP took 16% more CPU time to convert it.
+The extra CPU time probably indicates that processing of all the extra
+compressed data consumed all the CPU time saved by not having to
+convert the RGB inputs to YCbCr.
+.sp
+Grayscale format takes up a lot less space and takes less time to create
+and process than the color formats, even if the image contains nothing
+but black, white, and gray.
+.sp
+The \fB-rgb\fP option was added in Netpbm 10.11 in October 2002.
+
+.TP
+\fB-density=\fP\fIdensity\fP
+This option determines the density (aka resolution) information
+recorded in the JFIF output image.  It does not affect the raster in
+any way; it just tells whoever reads the JFIF how to interpret the
+raster.
+.sp
+The density value takes the form \fIx\fP\fBx\fP\fIy\fP followed
+by an optional unit specifier of \fBdpi\fP or \fBdpcm\fP.  Examples:
+\fB1x1\fP, \fB3x2\fP, \fB300x300dpi\fP, \fB100x200dpcm\fP.  The
+first number is the horizontal density; the 2nd number is the vertical
+density.  Each may be any integer from 1 to 65535.  The unit specifier
+is \fBdpi\fP for dots per inch or \fBdpcm\fP for dots per
+centimeter.  If you don't specify the units, the density information
+goes into the JFIF explicitly stating "density unspecified" (also
+interpreted as "unknown").  This may seem pointless, but note that
+even without specifying the units, the density numbers tell the aspect
+ratio of the pixels.  E.g. \fB1x1\fP tells you the pixels are square.
+\fB3x2\fP tells you the pixels are vertical rectangles.
+.sp
+Note that if you specify different horizontal and vertical
+densities, the resulting JFIF image is \fInot\fP a true
+representation of the input PNM image, because \fBpnmtojpeg\fP
+converts the raster pixel-for-pixel and the pixels of a PNM image are
+defined to be square.  Thus, if you start with a square PNM image and
+specify \fB-density=3x2\fP, the resulting JFIF image is a horizontally
+squashed version of the original.  However, it is common to use an
+input image which is a slight variation on PNM rather than true PNM
+such that the pixels are not square.  In that case, the appropriate
+-density option yields a faithful reproduction of the input pseudo-PNM
+image.
+.sp
+The default is 1x1 in unspecified units.
+.sp
+Before Netpbm 10.15 (April 2003), this option did not exist and the
+\fBpnmtojpeg\fP always created a JFIF with a density of 1x1 in
+unspecified units.
+
+.TP
+\fB-optimize\fP
+ Perform optimization of entropy encoding parameters.  Without
+this, \fBpnmtojpeg\fP uses default encoding parameters.
+\fB-optimize\fP usually makes the JFIF file a little smaller, but
+\fBpnmtojpeg\fP runs somewhat slower and needs much more memory.
+Image quality and speed of decompression are unaffected by
+\fB-optimize\fP.
+
+.TP
+\fB-progressive\fP
+Create a progressive JPEG file (see below).
+.TP
+\fB-comment=\fP\fItext\fP
+Include a comment marker in the JFIF output, with comment text 
+\fItext\fP.
+
+Without this option, there are no comment markers in the output.
+
+
+.PP
+The \fB-quality\fP option lets you trade off compressed file size
+against quality of the reconstructed image: the higher the quality
+setting, the larger the JFIF file, and the closer the output image
+will be to the original input.  Normally you want to use the lowest
+quality setting (smallest file) that decompresses into something
+visually indistinguishable from the original image.  For this purpose
+the quality setting should be between 50 and 95 for reasonable
+results; the default of 75 is often about right.  If you see defects
+at \fB-quality=75\fP, then go up 5 or 10 counts at a time until you
+are happy with the output image.  (The optimal setting will vary from
+one image to another.)
+.PP
+\fB-quality=100\fP generates a quantization table of all 1's,
+minimizing loss in the quantization step (but there is still
+information loss in subsampling, as well as roundoff error).  This
+setting is of interest mainly for experimental purposes.  Quality
+values above about 95 are \fInot\fP recommended for normal use; the
+compressed file size goes up dramatically for hardly any gain in
+output image quality.
+.PP
+In the other direction, quality values below 50 will produce very
+small files of low image quality.  Settings around 5 to 10 might be
+useful in preparing an index of a large image library, for example.
+Try \fB-quality=2\fP (or so) for some amusing Cubist effects.  (Note:
+quality values below about 25 generate 2-byte quantization tables,
+which are considered optional in the JFIF standard.  \fBpnmtojpeg\fP
+emits a warning message when you give such a quality value, because
+some other JFIF programs may be unable to decode the resulting file.
+Use \fB-baseline\fP if you need to ensure compatibility at low
+quality values.)
+.PP
+The \fB-progressive\fP option creates a "progressive
+JPEG" file.  In this type of JFIF file, the data is stored in
+multiple scans of increasing quality.  If the file is being
+transmitted over a slow communications link, the decoder can use the
+first scan to display a low-quality image very quickly, and can then
+improve the display with each subsequent scan.  The final image is
+exactly equivalent to a standard JFIF file of the same quality
+setting, and the total file size is about the same -- often a little
+smaller.
+.PP
+\fBCaution:\fP progressive JPEG is not yet widely
+implemented, so many decoders will be unable to view a progressive
+JPEG file at all.
+.PP
+If you're trying to control the quality/file size tradeoff, you
+might consider the JPEG2000 format instead.  See
+.BR "pamtojpeg2k" (1)\c
+\&.
+
+.UN advancedopts
+.SS Advanced options
+
+
+
+.TP
+\fB-dct=int\fP
+Use integer DCT method (default).
+
+.TP
+\fB-dct=fast\fP
+Use fast integer DCT (less accurate).
+
+.TP
+\fB-dct=float\fP
+Use floating-point DCT method.  The float method is very slightly
+more accurate than the int method, but is much slower unless your
+machine has very fast floating-point hardware.  Also note that results
+of the floating-point method may vary slightly across machines, while
+the integer methods should give the same results everywhere.  The fast
+integer method is much less accurate than the other two.
+
+.TP
+\fB-arithmetic\fP
+Use arithmetic coding.  Default is Huffman encoding.  Arithmetic coding
+tends to get you a smaller result.
+.sp
+You may need patent licenses to use this option.  According to 
+.UR http://www.faqs.org/faqs/jpeg-faq
+the JPEG FAQ
+.UE
+\&,
+This method is covered by patents owned by IBM, AT&T, and Mitsubishi.
+.sp
+The author of the FAQ recommends against using arithmetic coding (and
+therefore this option) because the space savings is not great enough to
+justify the legal hassles.
+.sp
+Most JPEG libraries, including any distributed by the Independent
+JPEG Group since about 1998 are not capable of arithmetic encoding.
+\fBpnmtojpeg\fP uses a JPEG library (either bound to it when the
+\fBpnmtojpeg\fP executable was built or accessed on your system at
+run time) to do the JPEG encoding.  If \fBpnmtojpeg\fP terminates
+with the message, "Sorry, there are legal restrictions on
+arithmetic coding" or "Sorry, arithmetic coding not
+supported," this is the problem.
+     
+.TP
+\fB-restart=\fP\fIn\fP
+Emit a JPEG restart marker every \fIn\fP MCU rows, or every \fIn\fP
+MCU blocks if you append \fBB\fP to the number.  \fB-restart 0\fP
+(the default) means no restart markers.
+
+.TP
+\fB-smooth=\fP\fIn\fP
+Smooth the input image to eliminate dithering noise.  \fIn\fP,
+ranging from 1 to 100, indicates the strength of smoothing.  0 (the
+default) means no smoothing.
+
+.TP
+\fB-maxmemory=\fP\fIn\fP
+Set a limit for amount of memory to use in processing large images.  Value is
+in thousands of bytes, or millions of bytes if you append
+\fBM\fP to the number.  For example, \fB-max=4m\fP
+selects 4,000,000 bytes.  If \fBpnmtojpeg\fP
+needs more space, it will use temporary files.
+
+.TP
+\fB-verbose\fP
+Print to the Standard Error file messages about the conversion process.
+This can be helpful in debugging problems.
+
+.PP
+The \fB-restart\fP option tells \fBpnmtojpeg \fP to insert extra
+markers that allow a JPEG decoder to resynchronize after a
+transmission error.  Without restart markers, any damage to a
+compressed file will usually ruin the image from the point of the
+error to the end of the image; with restart markers, the damage is
+usually confined to the portion of the image up to the next restart
+marker.  Of course, the restart markers occupy extra space.  We
+recommend \fB-restart=1\fP for images that will be transmitted
+across unreliable networks such as Usenet.
+.PP
+The \fB-smooth\fP option filters the input to eliminate
+fine-scale noise.  This is often useful when converting dithered
+images to JFIF: a moderate smoothing factor of 10 to 50 gets rid of
+dithering patterns in the input file, resulting in a smaller JFIF file
+and a better-looking image.  Too large a smoothing factor will visibly
+blur the image, however.
+
+.UN wizardopts
+.SS Wizard Options
+
+
+.TP
+\fB-baseline\fP
+Force baseline-compatible quantization tables to be generated.
+This clamps quantization values to 8 bits even at low quality
+settings.  (This switch is poorly named, since it does not ensure that
+the output is actually baseline JPEG.  For example, you can use
+\fB-baseline\fP and \fB-progressive\fP together.)
+
+.TP
+\fB-qtables=\fP\fIfilespec\fP
+Use the quantization tables given in the specified text file.
+
+.TP
+\fB-qslots=n[,...]\fP
+Select which quantization table to use for each color component.
+
+.TP
+\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]
+Set JPEG sampling factors for each color component.
+
+.TP
+\fB-scans=\fP\fIfilespec\fP
+Use the scan script given in the specified text file.  See below
+for information on scan scripts.
+
+.TP
+\fB-tracelevel=\fP\fIN\fP
+This sets the level of debug tracing the program outputs as it runs.
+0 means none, and is the default.  This level primarily controls tracing
+of the JPEG library, and you can get some pretty interesting information
+about the compression process.
+
+
+.PP
+The "wizard" options are intended for experimentation
+with JPEG.  If you don't know what you are doing, \fBdon't use
+them\fP.  These switches are documented further in the file
+wizard.doc that comes with the Independent JPEG Group's JPEG library.
+
+.UN examples
+.SH EXAMPLES
+.PP
+This example compresses the PPM file foo.ppm with a quality factor
+of 60 and saves the output as foo.jpg:
+
+.nf
+    \fBpnmtojpeg -quality=60 foo.ppm > foo.jpg\fP
+
+.fi
+.PP
+Here's a more typical example.  It converts from BMP to JFIF:
+
+.nf
+    \fBcat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg\fP
+
+.fi
+
+.UN loss
+.SH JPEG LOSS
+.PP
+When you compress with JPEG, you lose information -- i.e. the resulting
+image has somewhat lower quality than the original.  This is a characteristic
+of JPEG itself, not any particular program.  So if you do the usual 
+Netpbm thing and convert from JFIF to PNM, manipulate, then convert back
+to JFIF, you will lose quality.  The more you do it, the more you lose.
+Drawings (charts, cartoons, line drawings, and such with few colors
+and sharp edges) suffer the most.
+.PP
+To avoid this, you can use a compressed image format other than
+JPEG.  PNG and JPEG2000 are good choices, and Netpbm contains converters
+for those.
+.PP
+If you need to use JFIF on a drawing, you should experiment with
+\fBpnmtojpeg\fP's \fB-quality\fP and \fB-smooth\fP options to get a
+satisfactory conversion.  \fB-smooth 10\fP or so is often helpful.
+.PP
+Because of the loss, you should do all the manipulation you have to
+do on the image in some other format and convert to JFIF as the last
+step.  And if you can keep a copy in the original format, so much the
+better.
+
+The \fB-optimize\fP option to \fBpnmtojpeg\fP is worth using when
+you are making a "final" version for posting or archiving.
+It's also a win when you are using low quality settings to make very
+small JFIF files; the percentage improvement is often a lot more than
+it is on larger files.  (At present, \fB-optimize\fP mode is
+automatically in effect when you generate a progressive JPEG file).
+.PP
+You can do flipping and rotating transformations losslessly with
+the program \fBjpegtran\fP, which is packaged with the Independent
+Jpeg Group's JPEG library.  \fBjpegtran\fP exercises its intimate
+knowledge of the way JPEG works to do the transformation without ever
+actually decompressing the image.
+
+.UN otherprog
+.SH OTHER PROGRAMS
+.PP
+Another program, \fBcjpeg\fP, is similar.  \fBcjpeg\fP is
+maintained by the Independent JPEG Group and packaged with the JPEG
+library which \fBpnmtojpeg\fP uses for all its JPEG work.  Because of
+that, you may expect it to exploit more current JPEG features.  Also,
+since you have to have the library to run \fBpnmtojpeg\fP, but not
+vice versa, \fBcjpeg\fP may be more commonly available.
+.PP
+On the other hand, \fBcjpeg\fP does not use the NetPBM libraries
+to process its input, as all the NetPBM tools such as \fBpnmtojpeg\fP
+do.  This means it is less likely to be consistent with all the other
+programs that deal with the NetPBM formats.  Also, the command syntax
+of \fBpnmtojpeg\fP is consistent with that of the other Netpbm tools,
+unlike \fBcjpeg\fP.
+
+.UN scanscripts
+.SH SCAN SCRIPTS
+.PP
+Use the \fB-scan\fP option to specify a scan script.  Or use the
+\fB-progressive\fP option to specify a particular built-in scan
+script.
+.PP
+Just what a scan script is, and the basic format of the scan script
+file, is covered in the \fBwizard.doc\fP file that comes with the
+Independent JPEG Group's JPEG library.  Scan scripts are same for
+\fBpnmtojpeg\fP as the are for \fBcjpeg\fP.
+.PP
+This section contains additional information that isn't, but
+probably should be, in that document.
+.PP
+First, there are many restrictions on what is a valid scan script.
+The JPEG library, and thus \fBpnmtojpeg\fP, checks thoroughly for any
+lack of compliance with these restrictions, but does little to tell
+you how the script fails to comply.  The messages are very general and
+sometimes untrue.
+.PP
+To start with, the entries for the DC coefficient must come before any
+entries for the AC coefficients.  The DC coefficient is Coefficient 0;
+all the other coefficients are AC coefficients.  So in an entry for
+the DC coefficient, the two numbers after the colon must be 0 and 0.
+In an entry for AC coefficients, the first number after the colon must
+not be 0.
+.PP
+In a DC entry, the color components must be in increasing order.
+E.g. "0,2,1" before the colon is wrong.  So is "0,0,0".
+.PP
+In an entry for an AC coefficient, you must specify only one color
+component.  I.e. there can be only one number before the colon.
+.PP
+In the first entry for a particular coefficient for a particular color
+component, the "Ah" value must be zero, but the Al value can be any
+valid bit number.  In subsequent entries, Ah must be the Al value from
+the previous entry (for that coefficient for that color component),
+and the Al value must be one less than the Ah value.
+.PP
+The script must ultimately specify at least some of the DC coefficient
+for every color component.  Otherwise, you get the error message
+"Script does not transmit all the data."  You need not specify all of
+the bits of the DC coefficient, or any of the AC coefficients.
+.PP
+There is a standard option in building the JPEG library to omit scan
+script capability.  If for some reason your library was built with
+this option, you get the message "Requested feature was omitted at
+compile time."
+
+.UN environment
+.SH ENVIRONMENT
+
+
+.TP
+\fBJPEGMEM\fP
+If this environment variable is set, its value is the default
+memory limit.  The value is specified as described for the
+\fB-maxmemory\fP option.  An explicit \fB-maxmemory \fP option
+overrides any \fBJPEGMEM\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "jpegtopnm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBcjpeg\fP man page,
+\fBdjpeg\fP man page,
+\fBjpegtran\fP man page,
+\fBrdjpgcom\fP man page,
+\fBwrjpgcom\fP man page
+.PP
+Wallace, Gregory K.  "The JPEG Still Picture Compression
+Standard", Communications of the ACM, April 1991 (vol. 34,
+no. 4), pp. 30-44.
+
+
+.UN author
+.SH AUTHOR
+
+\fBpnmtojpeg\fP and this manual were derived in large part from
+\fBcjpeg\fP, by the Independent JPEG Group.  The program is otherwise
+by Bryan Henderson on March 07, 2000.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtojpeg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtopalm.1 b/upstream/mageia-cauldron/man1/pnmtopalm.1
new file mode 100644
index 00000000..5d974a3e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtopalm.1
@@ -0,0 +1,316 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtopalm User Manual" 0 "25 August 2017" "netpbm documentation"
+
+.SH NAME
+pnmtopalm - convert a PNM image to a Palm Bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtopalm\fP
+
+[\fB-verbose\fP]
+
+[\fB-depth=\fP\fIN\fP]
+
+[\fB-maxdepth=\fP\fIN\fP]
+
+[\fB-colormap\fP]
+
+[\fB-transparent=\fP\fIcolorspec\fP]
+
+[\fB-density=\fP\fIN\fP]
+
+[\fB-offset\fP]
+
+[\fB-withdummy\fP]
+[\fB-scanline_compression\fP | \fB-rle_compression\fP |
+\fB-packbits_compression\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtopalm\fP reads a PNM image as input, from Standard Input or
+\fIpnmfile\fP and produces a Palm Bitmap as output.
+.PP
+Palm Bitmap files are either grayscale files with 1, 2, or 4 bits per
+pixel, or mapped color files with 8 bit per pixel, or a direct color file with
+16 bits per pixel, and \fBpnmtopalm\fP chooses this color depth based on the
+maxval and number of colors in the input, unless you specify a depth (bits per
+pixel) with \fB-depth\fP.  You can also specify a maximum depth
+with \fB-maxdepth\fP to partially constrain \fBpnmtopalm\fP's choice.  Input
+files must have an appropriate number and set of colors for the selected
+output constraints.
+.PP
+This often means that you should run the PNM image through
+\fBpnmquant\fP or \fBpnmremap\fP before you pass it to
+\fBpnmtopalm\fP.  Netpbm comes with several colormap files you can
+use with \fBpnmremap\fP for this purpose.  They are
+\fIpalmgray2.map\fP (4 shades of gray for a depth of 2),
+\fIpalmgray4.map\fP (16 shades of gray for a depth of 4), and
+\fIpalmcolor8.map\fP (232 colors in default Palm colormap).  In a
+standard Netpbm installation, these are in the Netpbm data directory,
+and you can find the Netpbm data directory with a \fBnetpbm-config
+--datadir\fP shell command.
+.PP
+Example:
+
+.nf
+  pnmremap myimage.ppm \e
+           -mapfile=$(netpbm-config --datadir)/palmgray2.map \e
+  | pnmtopalm -depth=2 >myimage.palm
+
+
+.fi
+.PP
+Compressed Palm Bitmap files, at least the ones \fBpnmtopalm\fP knows how
+to create, cannot have more than 8 bits per pixel.  \fBpnmtopalm\fP defaults
+to 8 bits per pixel if you specify a compressed output.  You can specify the
+number of bits per pixel explicitly with \fB-depth\fP.  \fB-maxdepth\fP
+has the same effect as \fB-depth\fP.  If you specify more than 8 bits per
+pixel with either of these, \fBpnmtopalm\fP fails.
+
+.UN version
+.SS Palm Bitmap Version
+.PP
+\fBpnmtopalm\fP generates a Version 0, 1, 2, or 3 Palm Bitmap.
+It generates the oldest (lowest) version it can for the given image and
+the options you specify.
+
+
+.IP \(bu
+If you specify a density (\fB-density\fP option) higher than
+"low," the version is at least 3.
+
+.IP \(bu
+If you specify transparency (\fB-transparent\fP option) or 
+any compression, the version is at least 2.
+
+.IP \(bu
+If you specify a custom colormap (\fB-colormap\fP option), the
+version is at least 1.
+
+.IP \(bu
+If the image has more than one bit per pixel, the version is at least
+1.  The image has more than one bit per pixel if you specify it with
+\fB-depth\fP or if you let it default and the image has more than
+two colors (or shades of gray).
+
+
+.PP
+All releases of Palm OS can read a Version 0 bitmap.  Palm OS 3.0 and
+later can read a Version 1 bitmap.  Palm OS 3.5 and later can read a
+Version 2 bitmap.  To read a Version 3 bitmap, you need Palm OS Garnet
+or a handheld running the High Density Display Feature Set.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtopalm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display the format of the output file.
+
+.TP
+\fB-depth=\fP\fIN\fP
+Produce a file of depth \fIN\fP, where \fIN\fP must be either 1, 2,
+4, 8, or 16.  Because the default Palm 8-bit colormap is not
+grayscale, if the input is a grayscale or monochrome image, the
+output will never be more than 4 bits deep, regardless of the
+specified depth.  Note that 8-bit color works only in PalmOS 3.5 (and
+higher), and 16-bit direct color works only in PalmOS 4.0 (and
+higher).  However, the 16-bit direct color format is also compatible
+with the various PalmOS 3.x versions used in the Handspring Visor, so
+these images may also work in that device.
+
+.TP
+\fB-maxdepth=\fP\fIN\fP
+Produce a file of minimal depth, but in any case less than \fIN\fP
+bits wide.  If you specify 16-bit, the output will always be 16-bit
+direct color.
+
+.TP
+\fB-offset\fP
+Set the \fBnextDepthOffset\fP field in the palm file header to indicate
+the end of the file (and pad the end of the file to 4 bytes, since
+\fBnextDepthOffset\fP can point only to 4 byte boundaries).
+.sp
+A palm image file can contain multiple renditions of the same image,
+with different color depths, so a viewer can choose one appropriate for
+the display.  The \fBnextDepthOffset\fP field tells where in the stream
+the next rendition begins.
+.sp
+\fBpnmtopalm\fP creates a file that contains only one image, but
+you can separately concatenate multiple one-image files to create a
+multi-image file.  If you do that, you'll need to use \fB-offset\fP
+so that the resulting concatenation is a correct stream.
+.sp
+By default (if you don't specify \fB-offset\fP), \fBpnmtopalm\fP
+generates a \fBnextDepthOffset\fP field that says there is no following
+image (and does not add any padding after the image).
+.sp
+Version 3 Palm Bitmaps actually have a \fBnextBitmapOffset\fP
+field instead of the \fBnextDepthOffset\fP.  The foregoing applies to
+whichever is relevant.
+.sp
+The \fB-offset\fP option was new in Netpbm 10.26 (January 2005).
+Before that, \fBpnmtopalm\fP always set the \fBnextDepthOffset\fP
+field to "none."
+.sp
+Before Netpbm 10.27 (March 2005), you cannot use \fB-offset\fP if
+you create a compressed raster (because \fBpnmtopalm\fP isn't smart
+enough to be able to know the size of the image at the time it writes
+the header).  You also cannot use it with 16 bit color depth or with
+the \fB-colormap\fP option, for much the same reason.
+
+.TP
+\fB-withdummy\fP
+This option tells \fBpnmtopalm\fP to put in the stream, after
+the image, a dummy image header to introduce subsequent high density
+images.
+.sp
+This dummy image header is a special sequence specified in Palm Bitmap
+specifications.  It looks to an older Palm Bitmap interpreter like an invalid
+image header, so such an interpreter will stop reading the stream
+there.  But a new Palm Bitmap interpreter recognizes it for what it is (just
+something to choke an old interpreter) and skips over it.  Presumably,
+you will add to the stream after this high density images which would
+confuse an older interpreter.
+.sp
+If you specify \fB-withdummy\fP, you must also specify \fB-offset\fP,
+since it doesn't make any sense otherwise.
+.sp
+\fB-withdummy\fP was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-colormap\fP
+Build a custom colormap and include it in the output file.  This is
+not recommended by Palm, for efficiency reasons.  Otherwise, \fBpnmtopalm\fP
+uses the default Palm colormap for color output.
+
+.TP
+\fB-transparent=\fP\fIcolorspec\fP
+Marks \fIone\fP particular color as fully transparent.
+.sp
+\fIcolorspec\fP is as described for the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Transparency works only on Palm OS 3.5 and higher.
+
+.TP
+\fB-scanline_compression\fP
+Specifies that the output Palm bitmap will use the Palm scanline
+compression scheme.  Scanline compression works only in Palm OS 2.0
+and higher.
+
+.TP
+\fB-rle_compression\fP
+Specifies that the output Palm bitmap will use the Palm RLE
+compression scheme.  RLE compression works only with Palm OS 3.5 and
+higher.
+
+.TP
+\fB-packbits_compression\fP
+Specifies that the output Palm bitmap will use the Palm packbits
+compression scheme.  Packbits compression works only with Palm OS 4.0 and
+higher.
+.sp
+This option was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-density\fP=\fIN\fP
+This specifies the Palm Bitmap density.  The density is a number that
+is proportional to the resolution the image should have when displayed.
+The proportionality factor is up to whatever is doing the displaying,
+but it's helpful to think of these numbers as being pixels per inch.
+The allowable values are:
+
+
+.IP \(bu
+72
+.IP \(bu
+108
+.IP \(bu
+144
+.IP \(bu
+216
+.IP \(bu
+288
+
+.sp
+This option was new in Netpbm 10.27 (March 2005).  Earlier Netpbm
+could not generate Version 3 Palm Bitmaps, so there was no such thing
+as density.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "palmtopnm" (1)\c
+\&,
+.BR "pdbimgtopam" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN notes
+.SH NOTES
+.PP
+Palm Bitmaps may contains multiple renditions of the same bitmap,
+in different depths.  To construct an N-multiple-rendition Palm Bitmap
+with \fBpnmtopalm\fP, first construct renditions 1 through N-1 using
+the \fB-offset\fP option, then construct the Nth image without the
+\fB-offset\fP option.  Then concatenate the individual renditions
+together in a single file using \fBcat\fP.
+.PP
+If you will include both high density and low density renditions,
+put the high density images last and when you create the last of the
+low density images, use the \fB-withdummy\fP option.
+.PP
+If you specify the Palm packbits compression scheme for a 16-bit direct
+color bitmap, this program generates an invalid bitmap.
+
+
+.UN authors
+.SH AUTHORS
+
+This program was originally written as ppmtoTbmp.c, by Ian Goldberg
+and George Caswell.  It was completely re-written by Bill Janssen to
+add color, compression, and transparency function.
+Copyright 1995-2001 by Ian Goldberg, George Caswell, and Bill Janssen.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtopalm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtopclxl.1 b/upstream/mageia-cauldron/man1/pnmtopclxl.1
new file mode 100644
index 00000000..dea6dbd4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtopclxl.1
@@ -0,0 +1,258 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtopclxl User Manual" 0 "22 March 2011" "netpbm documentation"
+
+.SH NAME
+pnmtopclxl - convert a PNM image to an HP LaserJet PCL XL printer stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtopclxl\fP
+
+{
+[\fB-dpi=\fP\fIN\fP]
+[\fB-xoffs=\fP\fIN\fP]
+[\fB-yoffs=\fP\fIN\fP]
+[\fB-center\fP]
+[\fB-duplex=\fP{\fBvertical\fP|\fBhorizontal\fP}]
+[\fB-format=\fP\fIpaperformat\fP]
+[\fB-feeder=\fP\fIN\fP]
+[\fB-copies=\fP\fIN\fP]
+[\fB-rendergray\fP]
+[\fB-jobsetup=\fP\fIfilename\fP]
+
+|
+\fB-embedded\fP
+
+}
+[\fB-colorok\fP]
+\fIpnmfile1\fP \fIpnmfile2\fP ...
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtopclxl\fP reads one or more PNM input streams, each containing one
+or more PNM images, and generates a sequence of output pages in the
+HP PCL-XL (formerly named PCL 6) printer control language.  You can send
+this stream to a PCL-XL printer to print the images.
+.PP
+Alternatively, you can make \fBpnmtopclxl\fP generate just the PCL-XL
+instructions to print an image, which you can embed in your own PCL-XL
+stream to place an image on one of your pages.  (\fB-embedded\fP option).
+.PP
+If the input is PPM, the output is a color printer stream (the PCL
+color space is RGB).  Otherwise, the output is grayscale (the PCL color space
+is grayscale).  If you want a grayscale output from a color input, run your
+input through
+.BR "ppmtopgm" (1)\c
+\&.  See the 
+\fB-colorok\fP option for more information about choosing between color
+and grayscale.
+.PP
+The output goes to Standard Output.  All of the pages go to one
+file, concatenated in the same order as the input images.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtopclxl\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-dpi=\fP\fIN\fP
+This option selects the resolution of the image (not the printer!).
+\fIN\fP is the resolution in dots per inch, from 1 to 65535.  The default
+is 300.
+
+.TP
+\fB-xoffs=\fP\fIN\fP
+This option and \fB-yoffs\fP determine the location on the page of the
+upper left corner of each image.  Note that the image may have built in
+borders too, which would make the main image within more left and down 
+that what you specify here.
+.sp
+\fB-xoffs\fP and \fB-yoffs\fP specify the distance from the left of the
+page and from the top of the page, respectively, in inches, of the upper left
+corner of the image.  The default for each is zero.
+.sp
+These options are meaningless if you specify \fB-center\fP.
+
+.TP
+\fB-yoffs\fP \fIN\fP
+See \fB-xoffs\fP.
+
+.TP
+\fB-center\fP
+This option tells \fBpnmtopclxl\fP to center each image on the page.
+If you don't specify this option, the position of an image on the page is
+determined by \fB-xoffs\fP and \fB-yoffs\fP (or their defaults).
+
+.TP
+\fB-duplex=\fP{\fBvertical\fP|\fBhorizontal\fP} 
+This option
+causes \fBpnmtopclxl\fP to create a printer stream that prints pages
+on both sides of the sheet of paper.  \fBvertical\fP means to print
+them so that the left edge of both pages is on the same edge of the
+sheet, while \fBhorizontal\fP means the more usual duplexing where the
+top of both pages is on the same edge of the sheet.
+
+.TP
+\fB-format=\fP\fIpaperformat\fP
+This option selects the media (e.g. paper size) that the printer
+control stream specifies.  \fIpaperformat\fP is one of the following
+self-explanatory keywords:
+
+
+.IP \(bu
+letter
+.IP \(bu
+legal
+.IP \(bu
+a3
+.IP \(bu
+a4
+.IP \(bu
+a5
+.IP \(bu
+a6
+.IP \(bu
+jb4
+.IP \(bu
+jb5
+.IP \(bu
+jb6
+.IP \(bu
+exec
+.IP \(bu
+ledger
+.IP \(bu
+b5envelope
+.IP \(bu
+c5envelope
+.IP \(bu
+com10envelope
+.IP \(bu
+monarchenvelope
+.IP \(bu
+dlenvelope
+.IP \(bu
+jpostcard
+.IP \(bu
+jdoublepostcard
+
+.sp
+The default is \fBletter\fP.
+
+.TP
+\fB-feeder=\fP\fIN\fP
+This options selects the media source (e.g. paper tray) that the
+printer control stream specifies.
+
+.TP
+\fB-copies=\fP\fIN\fP
+This option specifies the number of copies that the printer control
+stream tells the printer to print.
+
+.TP
+\fB-rendergray\fP
+This option causes \fBpnmtopclxl\fP to include in the output
+stream a command to set the RENDERMODE environment variable to
+GRAYSCALE, which typically causes the printer to print in grayscale
+regardless of the colors in the input, and may cause it to run much
+faster even if the image is grayscale anyway.
+.sp
+This option was new in Netpbm 10.29 (August 2005).
+
+.TP
+\fB-jobsetup=\fP\fIfilename\fP
+This option causes \fBpnmtopclxl\fP to include arbitrary job setup
+PJL commands at the beginning of the output stream.  It reads them from
+the named file.
+.sp
+\fBpnmtopclxl\fP does not inspect these commands in any way, but it
+does expect them to be job setup commands.  If you have garbage in your
+file, you will hear from the printer.
+.sp
+This option was new in Netpbm 10.29 (August 2005).
+
+.TP
+\fB-colorok\fP
+This option simply tells \fBpnmtopclxl\fP not to warn you if you supply
+a color input and therefore get color output.  By default, \fBpnmtopclxl\fP
+issues a warning any time it produces a color printer stream because it is
+usually a mistake.  It's a mistake because PCL XL is mainly used for laser
+printers, and laser printers are mainly black and white.  If you send a color
+print stream to a black and white printer, it typically refuses to print
+anything, and even if it manages to convert it to black and white and print
+it, it takes 3 times as long to transmit a color stream to the printer than
+to transmit the grayscale image that gives the same result.
+
+.TP
+\fB-embedded\fP
+Without this option, \fBpnmtopclxl\fP generates an entire printer control
+stream that sets up the printer, ejects pages, and places a lone image on
+each page.  With the option, \fBpnmtopclxl\fP generates only the instructions
+to generate the image itself.  This is not useful all by itself, but you
+can embed it in a suitable PCL-XL stream in order to add an image to it.
+.sp
+This makes sense only for a single image, so you cannot specify multiple
+input files and if an input file has multiple images in it, \fBpnmtopclxl\fP
+ignores any after the first (it won't even read them).
+.sp
+All the options that control the printer control stream outside the image
+itself, such as \fB-xoffs\fP and \fB-feeder\fP are invalid
+with \fB-embedded\fP.
+.sp
+This option was new in Netpbm 10.54 (March 2011).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBppmtolj\fP" (1)\c
+\&,
+.BR "\fBpbmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtopj\fP" (1)\c
+\&,
+.BR "\fBppmtopjxl\fP" (1)\c
+\&,
+.BR "\fBthinkjettopbm\fP" (1)\c
+\&,
+.BR "\fBppm\fP" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmtopclxl\fP was added to Netpbm in Release 10.6 (July 2002).
+It was contributed by
+\fIJochen Karrer\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtopclxl.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtoplainpnm.1 b/upstream/mageia-cauldron/man1/pnmtoplainpnm.1
new file mode 100644
index 00000000..bd32259b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtoplainpnm.1
@@ -0,0 +1,33 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtoplainpnm User Manual" 0 "July 2004" "netpbm documentation"
+
+.SH NAME
+
+pnmtoplainpnm - replaced by pamtopnm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtoplainpnm\fP was obsoleted in Netpbm 10.23 (July 2004) by
+.BR "pamtopnm" (1)\c
+\&.  Just use the Netpbm common option
+\fB-plain\fP.
+.PP
+\fBpnmtoplainpnm\fP exists today for backward compatibility; all it
+does is call \fBpamtopnm -plain\fP.
+.PP
+\fBpnmtoplainpnm\fP was new in Netpbm 8.2 (March 2000) as a renaming
+of \fBpnmnoraw\fP, which was new in Pbmplus in November 1989.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtoplainpnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtopng.1 b/upstream/mageia-cauldron/man1/pnmtopng.1
new file mode 100644
index 00000000..96cf9df4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtopng.1
@@ -0,0 +1,566 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtopng User Manual" 0 "13 March 2019" "netpbm documentation"
+
+.SH NAME
+pnmtopng - convert a PNM image to PNG
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtopng\fP
+[\fB-verbose\fP]
+[\fB-downscale\fP]
+[\fB-interlace\fP]
+[\fB-alpha=\fP\fIfile\fP]
+[\fB-transparent=\fP[\fB=\fP]\fIcolor\fP]
+[\fB-background=\fP\fIcolor\fP]
+[\fB-palette=\fP\fIpalettefile\fP]
+[\fB-gamma=\fP\fIvalue\fP]
+[\fB-hist\fP]
+[\fB-text=\fP\fIfile\fP]
+[\fB-ztxt=\fP\fIfile\fP]
+[\fB-rgb='\fP\fIwx\fP \fIwy\fP
+  \fIrx\fP \fIry\fP \fIgx\fP \fIgy\fP \fIbx\fP \fIby\fP\fB'\fP]
+[\fB-size='\fP\fIx\fP \fIy\fP \fIunit\fP\fB'\fP]
+[\fB-srgbintent=\fP\fIintent\fP]
+[\fB-modtime='\fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP
+  \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP\fB'\fP]
+[\fB-nofilter\fP]
+[\fB-sub\fP]
+[\fB-up\fP]
+[\fB-avg\fP]
+[\fB-paeth\fP]
+[\fB-compression=\fP\fIn\fP]
+[\fB-comp_mem_level=\fP\fIn\fP]
+[\fB-comp_strategy=\fP{\fBhuffman_only\fP|\fBfiltered\fP}]
+[\fB-comp_method=\fP\fBdeflated\fP]
+[\fB-comp_window_bits=\fP\fIn\fP]
+[\fB-comp_buffer_size=\fP\fIn\fP]
+[\fB-force\fP]
+[\fB-libversion\fP]
+[\fIpnmfile\fP]
+
+
+.SH OPTION USAGE
+.PP
+Obsolete options:
+.PP
+[\fB-filter \fP\fIn\fP]
+.PP
+Options available only in older versions:
+.PP
+[\fB-chroma\fP \fIwx wy rx ry gx gy bx by\fP]
+[\fB-phys\fP \fIx\fP \fIy\fP \fIunit\fP]
+[\fB-time \fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP
+  \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtopng\fP reads a PNM image as input and produces a PNG image as
+output.
+.PP
+Color component values in PNG files are either eight or sixteen
+bits wide, so \fBpnmtopng\fP will automatically scale colors to have
+a maxval of 255 or 65535.
+.PP
+For a grayscale image, \fBpnmtopng\fP produces a PNG bit depth 1,
+2, 4, 8 or 16.  When the input image has a small maxval, the output
+PNG image has a correspondingly small bit depth.  But in mapping the
+PNM maxval to the PNG maxval (which is by definition the maximum value
+that can be represented in the number of bits), a fair amount of
+distortion happens with these low maxvals.  For example, with a PNM
+maxval of 5 and a PNG maxval of 7, the input sample 2 becomes the
+output sample 3.  The input brightness is 2/5 = .40, while the output
+brightness is 3/7 = .43.  Note that this is not a problem if you view
+the maxval as a precision, because in .4 and .43 are identical within
+the precision implied by maxval 5.  Indeed, if you convert this PNG
+back to a maxval 5 PGM, the pixel's value will again be 2, exactly as
+it was originally.  But if you need precisely the same colors in the
+output PNG as in the input PNM, make sure your input PNM has a maxval
+which is a power of two minus one.  If you can't do that, then convert
+it with \fBpamdepth\fP to something with a large maxval that is a
+power of two minus one (255 and 65535 are good choices) to minimize
+the error.
+
+
+.UN options
+.SH OPTIONS
+
+.UN notesyntax
+.SS Note: Option Syntax of Older Versions
+.PP
+\fBpnmtopng\fP changed in Netpbm 10.30 (October 2005) to use the
+standard Netpbm command line syntax.  Before that, you could not
+use double hyphens to denote an option and could not use an equal
+sign to separate an option name from its value.  And the options had
+to come before the non-option program arguments.
+.PP
+Furthermore, the options \fB-chroma\fP, \fB-phys\fP, and
+\fB-time\fP were replaced by \fB-rgb\fP, \fB-size\fP, and
+\fB-modtime\fP, respectively.  The only difference, taking
+\fB-phys\fP/\fB-size\fP as an example, is that \fB-phys\fP takes
+multiple program arguments as the option argument, whereas \fB-size\fP
+takes a single program argument which is composed of multiple words.
+E.g.  The old shell command
+
+.nf
+\f(CW
+   pnmtopng -phys 800 800 0 input.pnm > output.png
+\fP
+
+.fi
+.PP
+is equivalent to the new shell command
+
+.nf
+\f(CW
+   pnmtopng -size "800 800 0" input.pnm > output.png
+\fP
+
+.fi
+.PP
+If you're writing a program that needs to work with both new and old
+, have it first try with the new syntax, and if it fails
+with "unrecognized option," fall back to the old syntax.
+
+.UN curroptions
+.SS Current Options
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtopng\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+This causes \fBpnmtopng\fP to display information about the format of the
+output file.
+.sp
+\ 
+
+.TP
+\fB-downscale\fP
+This enables \fBpnmtopng\fP to scale maxvalues of more then 65535 to 16
+bits. Since this means loss of image data, \fBpnmtopng\fP does not do it by
+default.
+.sp
+\ 
+
+.TP
+\fB-interlace\fP
+This causes the PNG file to be interlaced, in Adam7 format.  The interlaced
+format is one in which the raster data starts with a low-resolution
+representation of the entire image, then continues with additional information
+for the entire image, then even more information, etc.  In Adam7 in
+particular, there are seven such passes of the whole image.  This is useful
+when you are receiving the image over a slow communication line as someone is
+waiting to see it.  The simplest thing to do in that case is wait for the
+entire image to arrive and then display it instantly, but then the user is
+wasting time staring at a blank space until the whole image arrives.  With the
+standard non-interlaced format, the data arrives row-by-row starting at the
+top, so the displayer could display each row of the image as it arrives and
+gradually paint down to the bottom.  But with an interlaced image, the
+displayer can start by showing a low-resolution version of the image, then
+gradually improve the display as more data arrives.
+.sp
+\ 
+     
+.TP
+\fB-alpha=\fP\fIfilename\fP
+This specifies the transparency (alpha) channel of the image.  You supply
+the transparency channel as a standard PGM transparency mask (see
+the
+.BR "PGM" (1)\c
+\& specification.  \fBpnmtopng\fP does not
+necessarily represents the transparency information as a transparency channel
+in the PNG format.  If it can represent the transparency information through a
+palette, it will do so in order to make a smaller PNG file.
+\fBpnmtopng\fP even sorts the palette so it can omit the opaque colors
+from the transparency part of the palette and save space for the palette.
+.sp
+\ 
+
+.TP
+\fB-transparent=\fP\fIcolor\fP
+\fBpnmtopng\fP marks the specified color as transparent in the PNG image.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+E.g. \fBred\fP or
+\fBrgb:ff/00/0d\fP.  If the color you specify is not present in the
+image, \fBpnmtopng\fP selects instead the color in the image that is
+closest to the one you specify.  Closeness is measured as a Cartesian
+distance between colors in RGB space.  If multiple colors are
+equidistant, \fBpnmtopng\fP chooses one of them arbitrarily.
+.sp
+However, if you prefix your color specification with
+"=", e.g.
+
+.nf
+\f(CW
+                    -transparent =red
+\fP
+
+.fi
+.sp
+ only the exact color you specify will be transparent.  If that
+color does not appear in the image, there will be no transparency.
+\fBpnmtopng\fP issues an information message when this is the case.
+
+.TP
+\fB-background=\fP\fIcolor\fP
+Causes \fBpnmtopng\fP to create a background color chunk in the PNG output
+which can be used for subsequent transparency channel or transparent color
+conversions.  Specify \fIcolor\fP the same as for \fB-transparent\fP.
+.sp
+\ 
+
+.TP
+\fB-palette=\fP\fIpalettefile\fP
+This option specifies a palette to use in the PNG.  It forces
+\fBpnmtopng\fP to create the paletted (colormapped) variety of PNG --
+if that isn't possible, \fBpnmtopng\fP fails.  If the palette you
+specify doesn't contain exactly the colors in the image,
+\fBpnmtopng\fP fails.  Since \fBpnmtopng\fP will automatically
+generate a paletted PNG, with a correct palette, when appropriate, the
+only reason you would specify the \fB-palette\fP option is if you care
+in what order the colors appear in the palette.  The PNG palette has colors
+in the same order as the palette you specify.
+.sp
+You specify the palette by naming a PPM file that has one pixel for
+each color in the palette.
+.sp
+Alternatively, consider the case that have a palette and you want
+to make sure your PNG contains only colors from the palette,
+approximating if necessary.  You don't care what indexes the PNG uses
+internally for the colors (i.e. the order of the PNG palette).  In
+this case, you don't need \fB-palette\fP.  Pass the Netpbm input
+image and your palette PPM through \fBpnmremap\fP.  Though you might
+think it would, using \fB-palette\fP in this case wouldn't even save
+\fBpnmtopng\fP any work.
+
+.TP
+\fB-gamma=\fP\fIvalue\fP
+Causes \fBpnmtopng\fP to create a gAMA chunk.  This information helps
+describe how the color values in the PNG must be interpreted.  Without
+the gAMA chunk, whatever interprets the PNG must get this information
+separately (or just assume something standard).  If your input is a true
+PPM or PGM image, you should specify \fB-gamma=.52\fP.  But sometimes 
+people generate images which are ostensibly PPM except the image uses a 
+different gamma transfer function than the one specified for PPM.  A common
+case of this is when the image is created by simple hardware that doesn't
+have digital computational ability.  Also, some simple programs that generate
+images from scratch do it with a gamma transfer in which the gamma value is
+1.0.
+.sp
+\ 
+
+.TP
+\fB-hist\fP
+Use this parameter to create a chunk that specifies the frequency
+(or histogram) of the colors in the image.
+.sp
+\ 
+
+.TP
+\fB-text=\fP\fIfilename\fP
+This option lets you include arbitrary text strings in the PNG output, as tEXt
+chunks.
+.sp
+\fIfilename\fP is the name of a file that contains your text strings.
+.sp
+The output contains a distinct tEXt chunk for each entry in the file.
+.sp
+Here is an example of a text string file:
+
+.nf
+	Title           PNG file
+	Author          John Doe
+	Description     how to include a text chunk
+                        PNG file
+	"Creation Date" 2015-may-11
+	Software        pamtopng
+
+.fi
+.sp
+The file is divided into entries, each entry comprising consecutive lines
+of text.  The first line of an entry starts in the first column (i.e. the
+first column is not white space) and every other line has white space in the
+first column.  The first entry starts in the first line, so it is not valid
+for the first line of the file to have white space in its first column.
+.sp
+The first word in an entry is the key of the text string
+(e.g. 'Title').  It begins in column one of the line and continues
+up to, but not including, the first delimiter character or the end of the
+line, whichever is first.  You can enclose the key in double quotes in
+which case the key can consists of multiple words.  The quotes are not
+part of the key.  The text string per se begins after the key and any
+delimiter characters after it, plus the text in subsequent continuation lines.
+.sp
+There is no limit on the length of a file line or entry or key or text
+string.  There is no limit on the number of entries.
+
+.TP
+\fB-ztxt=\fP\fIfilename\fP
+The same as \fB-text\fP, except the text string is compressed in the PNG
+output.  \fBpnmtopng\fP uses zTXt chunks instead of a tEXt chunks, unless the
+key for the text string starts with 'A' or 'T'.  This
+odd exception exists for backward compatibility; we don't know why the program
+was originally designed this way, except that the distinction was meant to
+roughly identify the keys 'Author' and 'Title'.
+.sp
+\ 
+
+.TP
+\fB-rgb=\fP\fIchroma_list\fP
+This option specifies how red, green, and blue component values
+of a pixel specify a particular color, by telling the chromaticities
+of those 3 primary illuminants and of white (i.e. full strength of
+all three).
+.sp
+The \fIchroma_list\fP value is a blank-separated list of 8 floating
+point decimal numbers.  The CIE-1931 X and Y chromaticities (in that
+order) of each of white, red, green, and blue, in that order.
+.sp
+This information goes into the PNG's cHRM chunk.
+.sp
+In a shell command, make sure you use quotation marks so that the
+blanks in \fIchroma_list\fP don't make the shell see multiple command
+arguments.
+.sp
+This option was new in Netpbm 10.30 (October 2005).  Before that,
+the option \fB-chroma\fP does the same thing, but with slightly
+different syntax.
+
+.TP
+\fB-size="\fP\fIx\fP \fIy\fP \fIunit\fP\fB"\fP
+This option determines the aspect ratio of the individual pixels
+of your image as well as the physical resolution of it.
+.sp
+\fIunit\fP is either \fB0\fP or \fI1\fP.  When it is \fI1\fP,
+the option specifies the physical resolution of the image in pixels
+per meter.  For example, \fB-size="10000 15000 1"\fP means
+that when someone displays the image, he should make it so that 10,000
+pixels horizontally occupy 1 meter and 15,000 pixels vertically occupy
+one meter.  And even if he doesn't take this advice on the overall
+size of the displayed image, he should at least make it so that each
+pixel displays as 1.5 times as high as wide.
+.sp
+When \fIunit\fP is \fB0\fP, that means there is no advice on
+the absolute physical resolution; just on the ratio of horizontal to 
+vertical physical resolution.
+.sp
+This information goes into the PNG's pHYS chunk.
+.sp
+When you don't specify \fB-size\fP, \fBpnmtopng\fP creates the image
+with no pHYS chunk, which means square pixels of no absolute resolution.
+.sp
+This option was new in Netpbm 10.30 (October 2005).  Before that,
+the option \fB-phys\fP does the same thing, but with slightly
+different syntax.
+
+.TP
+\fB-srgbintent=\fP\fIintent\fP
+This asserts that the input is a pseudo-Netpbm image that uses an
+sRGB color space (unlike true Netpbm) and indicates how you intend for the
+colors to be rendered.  It causes \fBpnmtopng\fP to include an sRGB chunk
+in the PNG image that specifies that intent, so see the PNG documentation for
+more information on what this really means.
+.sp
+\fIintent\fP is one of:
+
+
+.IP \(bu
+\fBperceptual\fP  
+.IP \(bu
+\fBrelativecolorimetric\fP  
+.IP \(bu
+\fBsaturation\fP  
+.IP \(bu
+\fBabsolutecolorimetric\fP  
+
+.sp
+This option was new in Netpbm 10.71 (June 2015).  Before that,
+\fBpnmtopng\fP never generates an sRGB chunk.
+
+.TP
+\fB-modtime="\fP[\fIyy\fP]\fIyy-mm-dd hh:mm:ss\fP\fB"\fP 
+This option allows you to specify the modification time value to
+be placed in the PNG output.  You can specify the year parameter
+either as a two digit or four digit value.
+.sp
+This option was new in Netpbm 10.30 (October 2005).  Before that,
+the option \fB-time\fP does the same thing, but with slightly
+different syntax.
+
+.TP
+\fB-filter=\fP\fIn\fP
+This option is obsolete.  Before Netpbm 10.22 (April 2004), this was
+the only way to specify a row filter.  It specifies a single type of
+row filter, by number, that \fBpnmtopng\fP must use on each row.
+.sp
+Use \fB-nofilter\fP, \fB-sub\fP, \fB-up\fP, \fB-avg\fP, and
+\fB-paeth\fP in current Netpbm.
+
+.TP
+\fB-nofilter\fP
+.TP
+\fB-sub\fP
+.TP
+\fB-up\fP
+.TP
+\fB-avg\fP
+.TP
+\fB-paeth\fP
+Each of these options permits \fBpnmtopng\fP to use one type of
+row filter.  \fBpnmtopng\fP chooses whichever of the permitted
+filters it finds to be optimal.  If you specify none of these options,
+it is the same as specifying all of them -- \fBpnmtopng\fP uses any
+row filter type it finds optimal.
+.sp
+These options were new with Netpbm 10.22 (April 2004).  Before that,
+you could use the \fB-filter\fP option to specify one permitted row
+filter type.  The default, when you specify no filter options, was the
+same.
+
+.TP
+\fB-compression=\fP\fIn\fP
+This option sets set the compression level of the zlib
+compression.  Select a level from 0 for no compression (maximum speed)
+to 9 for maximum compression (minimum speed).
+.sp
+The default is the default of the zlib library.
+
+.TP
+\fB-comp_mem_level=\fP\fIn\fP
+This option sets the memory usage level of the zlib compression.
+Select a level from 1 for minimum memory usage (and minimum speed) to
+9 for maximum memory usage (and speed).
+.sp
+The default is the default of the zlib library.
+.sp
+This option was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-comp_strategy=\fP{\fBhuffman_only\fP|\fBfiltered\fP}
+This options sets the compression strategy of the zlib compression.
+See Zlib documentation for information on what these strategies are.
+.sp
+The default is the default of the zlib library.
+.sp
+This option was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-comp_method=\fP\fBdeflated\fP
+This option does nothing.  It is here for mathematical
+completeness and for possible forward compatibility.  It theoretically
+selects the compression method of the zlib compression, but the Z
+library knows only one method today, so there's nothing to choose.
+.sp
+The default is the default of the zlib library.
+.sp
+This option was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-comp_window_bits=\fP\fIN\fP
+This option tells how big a window the zlib compression algorithm
+uses.  The value is the base 2 logarithm of the window size in bytes,
+so 8 means 256 bytes.  The value must be from 8 to 15 (i.e. 256 bytes
+to 32K).
+.sp
+See Zlib documentation for details on what this window size is.
+.sp
+The default is the default of the zlib library.
+.sp
+This option was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-comp_buffer_size\fP=\fIN\fP
+This option determines in what size pieces \fBpnmtopng\fP does the
+zlib compression.  One compressed piece goes in each IDAT chunk in the
+PNG.  So the bigger this value, the fewer IDAT chunks your PNG will have.
+Theoretically, this makes the PNG smaller because 1) you have less
+per-IDAT-chunk overhead, and 2) the compression algorithm has more data
+to work with.  But in reality, the difference will probably not be
+noticeable above about 8K, which is the default.
+.sp
+The value \fIn\fP is the size of the compressed piece (i.e. the
+compression buffer) in bytes.
+.sp
+This option was new in Netpbm 10.30 (October 2005).
+
+
+.TP
+\fB-force\fP
+When you specify this, \fBpnmtopng\fP limits its optimizations.  The
+resulting PNG output is as similar to the Netpbm input as possible.  For
+example, the PNG output will not be paletted and the transparency channel will
+be represented as a full transparency channel even if the information could be
+represented more succinctly with a transparency chunk.
+.sp
+\ 
+
+.TP
+\fB-libversion\fP
+This option causes \fBpnmtopng\fP to display version information
+about itself and the libraries it uses, \fBin addition to all its
+normal function\fP.  Do not confuse this with the Netpbm common
+option \fB-version\fP, which causes the program to display version
+information about the Netpbm library and do nothing else.
+.sp
+You can't really use this option in a program that invokes
+\fBpnmtopng\fP and needs to know which version it is.  Its function
+has changed too much over the history of \fBpnmtopng\fP.  The option
+is good only for human eyes.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pngtopam" (1)\c
+\&, 
+.BR "pamtopng" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+.PP
+For information on the PNG format, see 
+.UR http://schaik.com/png
+http://schaik.com/png
+.UE
+\&.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtopng.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtopnm.1 b/upstream/mageia-cauldron/man1/pnmtopnm.1
new file mode 100644
index 00000000..506429f4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtopnm.1
@@ -0,0 +1,89 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtopnm User Manual" 0 "24 March 2005" "netpbm documentation"
+
+.SH NAME
+
+pnmtopnm - copy a PNM image
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtopnm\fP
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtopnm\fP simply copies a PNM image to Standard Output.  The
+output has the same major PNM format (PBM, PGM, or PPM) and maxval as
+the input.  This may seem an unnecessary duplication of \fBcat\fP,
+but it lets you convert between the plain (ASCII) and raw (binary)
+subformats of PNM.  Use the \fB-plain\fP Netpbm common option to
+ensure the output is plain PNM, and don't use \fB-plain\fP to ensure
+the output is raw PNM.  See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.
+.PP
+You don't normally need to convert between the PNM subformats, because
+any program that uses the Netpbm library to read a PNM image will read
+all of them directly.  But there are a lot of programs that don't use
+the Netpbm library and understand only the raw format.  Plain format
+is nice because it is human readable; people often use it to debug
+programs that process PNM images.
+.PP
+\fBpnmtopnm\fP is really just another name for the program
+\fBpamtopnm\fP.  The latter does the job because like any Netpbm
+program that takes PAM input via the Netpbm programming library
+facilities, it also takes PNM input.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpnmtopnm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmtopnm\fP was new in Netpbm 10.23 (July 2004).  It obsoleted
+\fBpnmtoplainpnm\fP, which specifically did the conversion to plain
+PNM.  There was no program to explicitly convert to raw PNM, but many
+Netpbm programs can be made, with the right options, to be idempotent
+(i.e. to do the same thing as \fBpnmtopnm\fP).
+.PP
+Then David Jones realized that the existing \fBpamtopnm\fP already
+did everything that \fBpnmtopnm\fP did and more, so 
+in Netpbm 10.27 (March 2005), \fBpnmtopnm\fP became simply an alternate
+name for \fBpamtopnm\fP.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoppm" (1)\c
+\&
+.BR "pgmtopgm" (1)\c
+\&
+.BR "pamtopnm" (1)\c
+\&
+.BR "pnm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtops.1 b/upstream/mageia-cauldron/man1/pnmtops.1
new file mode 100644
index 00000000..18346682
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtops.1
@@ -0,0 +1,532 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtops User Manual" 0 "20 April 2018" "netpbm documentation"
+
+.SH NAME
+pnmtops - convert PNM image to Postscript
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtops\fP
+[\fB-scale=\fP\fIs\fP]
+[\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]]
+[\fB-imagewidth=\fP\fIn\fP]
+[\fB-imageheight=\fP\fIn\fP]
+[\fB-width=\fP\fIN\fP]
+[\fB-height=\fP\fIN\fP]
+[\fB-equalpixels\fP]
+[\fB-bitspersample=\fP\fIN\fP]
+[\fB-turn\fP|\fB-noturn\fP]
+[\fB-rle\fP|\fB-runlength\fP]
+[\fB-flate\fP]
+[\fB-ascii85\fP]
+[\fB-nocenter\fP|\fB-center\fP]
+[\fB-nosetpage\fP|\fB-setpage\fP]
+[\fB-level=\fP\fIN\fP]
+[\fB-dict\fP]
+[\fB-vmreclaim\fP]
+[\fB-psfilter\fP]
+[\fB-noshowpage\fP]
+[\fB-verbose\fP]
+[\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtops\fP reads a Netpbm image stream as input and produces
+Encapsulated Postscript (EPSF) as output.
+.PP
+(Note: people usually render the name as "PostScript," but we use
+standard typography in the Netpbm manual, so capitalize only the first
+letter).
+.PP
+If the input file is in color (PPM), \fBpnmtops\fP generates a
+color Postscript file.  Some Postscript interpreters can't handle
+color Postscript.  If you have one of these you will need to run your
+image through \fBppmtopgm\fP first.
+.PP
+If you specify no output dimensioning options, the output image is
+dimensioned as if you had specified \fB-scale=1.0\fP, which means
+approximately 72 pixels of the input image generate one inch of output
+(if that fits the page).
+.PP
+Use \fB-imagewidth\fP, \fB-imageheight\fP, \fB-equalpixels\fP,
+\fB-width\fP, \fB-height\fP, and \fB-scale\fP to adjust that.
+.PP
+Each image in the input stream becomes one complete one-page Postscript 
+program in the output.  (This may not be the best way to create a multi-page
+Postscript stream; someone who knows Postscript should work on this).
+.PP
+The line at the top of the file produced by \fBpnmtops\fP is
+either "%!PS-Adobe-3.0 EPSF-3.0" or just
+"%!PS-Adobe-3.0".  The numbers do not reflect the Postscript
+language level, but the version of the DSC comment specification and
+EPS specification implemented.  The Postscript language level is in the
+"%%LanguageLevel:" comment.  \fBpnmtops\fP omits "EPSF-3.0" if you
+specify \fB-setpage\fP, because it is incorrect to claim EPS
+compliance if the file uses \fBsetpagedevice\fP.
+
+
+.SS What is Encapsulated Postscript?
+.PP
+Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the
+set of streams that conform to EPSF is a subset of those that conform
+to Postscript).  It is designed so that an EPSF stream can be embedded
+in another Postscript stream.  A typical reason to do that is to have an
+EPSF stream that describes a picture you can put in a larger document.
+.PP
+But EPSF is not an image format -- converting from Netpbm format to EPSF
+really means generating a program to print that Netpbm image on paper.  Note
+that there are myriad ways to print an image on paper; \fBpnmtops\fP
+command line options let you control some of them.
+.PP
+An Encapsulated Postscript document conforms to the DSC (Document
+Structuring Convention).  The DSC defines some Postscript comments
+(they're comments from a Postscript point of view, but have semantic
+value from a DSC point of view).
+.PP
+More information about Encapsulated Postscript is at 
+.BR "
+http://www.tailrecursive.org/postscript/eps.html" (1)\c
+\&.
+.PP
+Many of the ideas in \fBpnmtops\fP come from Dirk Krause's \fBbmeps\fP.
+See 
+.UR #seealso
+SEE ALSO
+.UE
+\&.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtops\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-imagewidth\fP, \fB-imageheight\fP
+Tells how wide and high you want the image on the page, in inches.
+The aspect ratio of the image is preserved, so if you specify both of these,
+the image on the page will be the largest image that will fit within the
+box of those dimensions.
+.sp
+If these dimensions are greater than the page size, you get Postscript
+output that runs off the page.
+.sp
+You cannot use \fBimagewidth\fP or \fBimageheight\fP with
+\fB-scale\fP or \fB-equalpixels\fP.
+
+.TP
+\fB-equalpixels\fP
+This option causes the output image to have the same number of pixels
+as the input image.  So if the output device is 600 dpi and your image
+is 3000 pixels wide, the output image would be 5 inches wide.
+.sp
+You cannot use \fB-equalpixels\fP with \fB-imagewidth\fP,
+\fB-imageheight\fP, or \fB-scale\fP.
+
+.TP
+\fB-bitspersample=\fP\fIN\fP
+This option selects the number of bits for each component of each pixel in
+the Postscript output.  By default, \fBpnmtops\fP chooses the value that
+corresponds to the maxval of the PNM input, subject to constraints of the
+Postscript language.  In particular, if you don't select Postscript level
+2 (\fB-level\fP) with built-in Postscript (\fB-psfilter\fP), the most
+bits per pixel you can have is 8.
+.sp
+The value must be 1, 2, 4, 8, or 12, with 12 being restricted to the
+case described above.
+.sp
+This option was new in Netpbm 10.51 (June 2010).
+
+.TP
+\fB-scale\fP
+tells how big you want the image on the page.  The value is the number of
+inches of output image that you want 72 pixels of the input to generate.
+.sp
+But \fBpnmtops \fP rounds the number to something that is an
+integral number of output device pixels.  E.g. if the output device is
+300 dpi and you specify \fB-scale=1.0\fP, then 75 (not 72) pixels of
+input becomes one inch of output (4 output pixels for each input
+pixel).  Note that the \fB-dpi\fP option tells \fBpnmtops\fP how
+many pixels per inch the output device generates.
+.sp
+If the size so specified does not fit on the page (as measured
+either by the \fB-width\fP and \fB-height\fP options or the default
+page size of 8.5 inches by 11 inches), \fBpnmtops\fP ignores the
+\fB-scale\fP option, issues a warning, and scales the image to fit on
+the page.
+
+.TP
+\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]
+.sp
+This option specifies the dots per inch resolution of your output
+device.  The default is 300 dpi.  In theory PostScript is
+device-independent and you don't have to worry about this, but in
+practice its raster rendering can have unsightly bands if the device
+pixels and the image pixels aren't in sync.
+.sp
+Also this option is crucial to the working of the
+\fBequalpixels\fP option.
+.sp
+If you specify \fIN\fP\fBx\fP\fIN\fP, the first number is the
+horizontal resolution and the second number is the vertical
+resolution.  If you specify just a single number \fIN\fP, that is the
+resolution in both directions.
+     
+.TP
+\fB-width\fP, \fB-height\fP
+ These options specify the dimensions, in inches, of the page on
+which the output is to be printed.  This can affect the size of the
+output image.
+.sp
+The page size has no effect, however, when you specify the 
+\fB-imagewidth\fP, \fB-imageheight\fP, or \fB-equalpixels\fP options.
+.sp
+These options may also affect positioning of the image on the page and
+even the paper selected (or cut) by the printer/plotter when the
+output is printed.  See the \fB-nosetpage\fP option.
+.sp
+The default is 8.5 inches by 11 inches.
+
+.TP
+\fB-turn\fP
+
+.TP
+\fB-noturn\fP 
+These options control whether the image gets turned 90 degrees.
+Normally, if an image fits the page better when turned (e.g. the image
+is wider than it is tall, but the page is taller than it is wide), it
+gets turned automatically to better fit the page.  If you specify the
+\fB-turn\fP option, \fBpnmtops \fP turns the image no matter what
+its shape; If you specify \fB-noturn\fP, \fBpnmtops\fP does
+\fInot\fP turn it no matter what its shape.
+
+.TP
+\fB-rle\fP
+
+.TP
+\fB-runlength\fP
+These identical options tell \fBpnmtops\fP to use run length
+compression in encoding the image in the Postscript program.  This may
+save time if the host-to-printer link is slow; but normally the
+printer's processing time dominates, so \fB-rle\fP has no effect (and
+in the absence of buffering, may make things slower).
+.sp
+This may, however, make the Postscript program considerable smaller.
+.sp
+This usually doesn't help at all with a color image and
+\fB-psfilter\fP, because in that case, the Postscript program
+\fBpnmtops\fP creates has the red, green, and blue values for each
+pixel together, which means you would see long runs of identical bytes
+only in the unlikely event that the red, green, and blue values for a
+bunch of adjacent pixels are all the same.  But without
+\fB-psfilter\fP, the Postscript program has all the red values, then
+all the green values, then all the blue values, so long runs appear
+wherever there are long stretches of the same color.
+.sp
+Here is an explanation by Jef Poskanzer of why he invented the
+\fB-rle\fP option:
+
+.RS
+I just spent a few hours modifying my pbmtops filter to produce run length
+encoded PostScript output.  The results are not spectacular for me - yes, the
+files are smaller, but the printing times are about the same.  But I'm
+printing over the network.  If you were stuck with the serial line, this would
+be a big win.  I've appended a sample program generated by my filter.  If
+anyone sees ways to improve the code, please let me know, I'm not much of a
+PostScript hacker.  This version of pbmtops will be distributed to
+comp.sources.misc and expo.lcs.mit.edu sometime in October. - Jef
+.RE
+.sp
+This is
+from 
+.UR http://www.lngpstscrpt.tk/re-postscript-run-length-encoding-again
+a forum about Postscript
+.UE
+\&, extracted in October 2010.  Jef added -rle in
+August 1988.  In those days, RS-232 lines (referred to as "serial" in
+the quotation) were typically 9600bps.  2400 bps lines were still around.
+What the quotation calls "the network" is probably a 10 Mbps
+Ethernet connection.
+
+.TP
+\fB-flate\fP
+This option tells \fBpnmtops\fP to use "flate"
+compression (i.e. compression via the "Z" library -- the
+same as PNG).
+.sp
+See the \fB-rle\fP option for information about compression in general.
+.sp
+You must specify \fB-psfilter\fP if you specify \fB-flate\fP.
+.sp
+There exist modern versions of \fBpnmtops\fP that cannot do flate
+compression; these versions were built without the Z library and built not to
+require the Z library.  If you have such a version, it fails with an
+explanatory error message when you specify \fB-flate\fP.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+.sp
+Before Netpbm 10.32 (February 2006), you could not specify \fB-rle\fP
+and \fB-flate\fP together.
+
+
+.TP
+\fB-ascii85\fP
+By default, \fBpnmtops\fP uses "asciihex" encoding of
+the image raster.  The image raster is a stream of bits, while a Postscript
+program is text, so there has to be an encoding from bits to text.  Asciihex
+encoding is just the common hexadecimal representation of bits.  E.g. 8
+1 bits would be encoded as the two characters "FF".
+.sp
+With the \fB-ascii85\fP option, \fBpnmtops\fP uses
+"ascii85" encoding instead.  This is an encoding in which 32
+bits are encoded into five characters of text.  Thus, it produces less
+text for the same raster than asciihex.  But ascii85 is not available
+in Postscript Level 1, whereas asciihex is.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-psfilter\fP
+\fBpnmtops\fP can generate two different kinds of Encapsulated
+Postscript programs to represent an image.  By default, it generates a
+program that redefines \fBreadstring\fP in a custom manner and
+doesn't rely on any built-in Postscript filters.  But with the
+\fB-psfilter\fP option, \fBpnmtops\fP leaves \fBreadstring\fP alone
+and uses the built-in Postscript filters \fB/ASCII85Decode\fP,
+\fB/ASCIIHexDecode\fP, \fB/RunLengthDecode\fP, and \fB/FlateDecode\fP.
+.sp
+This option was new in Netbpm 10.27 (March 2005).  Before that, 
+\fBpnmtops\fP always used the custom \fBreadstring\fP.
+.sp
+The custom code can't do flate or ascii85 encoding, so you must use
+\fB-psfilter\fP if you want those (see \fB-flate\fP, \fB-ascii85\fP).
+
+.TP
+\fB-level\fP
+This option determines the level (version number) of Postscript that
+\fBpnmtops\fP uses.  By default, \fBpnmtops\fP uses Level 2.  Some
+features of \fBpnmtops\fP are available only in higher Postscript levels,
+so if you specify too low a level for your image and your options,
+\fBpnmtops\fP fails.  For example, \fBpnmtops\fP cannot do a color image
+in Level 1.
+.sp
+This option was new in Netpbm 10.27 (March 2005).  Before that,
+\fBpnmtops\fP always used Level 2.
+
+.TP
+\fB-dict\fP
+This causes the Postscript program create a separated dictionary
+for its local variables and remove it from the stack as it exits.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-vmreclaim\fP
+This option causes the Postscript program to force a memory garbage
+collection as it exits.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-nocenter\fP
+     By default, \fBpnmtops\fP centers the image on the output page.
+     You can cause \fBpnmtops\fP to instead put the image against the
+     lower left corner of the page with the \fB-nocenter \fP
+     option.  This is useful for programs which can include
+     PostScript files, but can't cope with pictures which are not
+     positioned in the lower left corner.
+.sp
+     If you want to position an image on the page arbitrarily, use
+     \fBpamcomp\fP to create an image of the full page with the image in
+     question at the proper place and the rest of the page white, and use
+     \fBpnmtops\fP to convert the composed result to Encapsulated Postscript.
+.sp
+     For backward compatibility, \fBpnmtops\fP accepts the option
+     \fB-center\fP, but it has no effect.
+
+.TP
+\fB-setpage\fP
+     This causes \fBpnmtops\fP to include a "setpagedevice"
+     directive in the output.  This causes the output to violate specifications
+     of EPSF encapsulated Postscript, but if you're not using it in an
+     encapsulated way, may be what you need.  The directive tells the
+     printer/plotter what size paper to use (or cut).  The dimensions it
+     specifies on this directive are those selected by the
+     \fB-width\fP and \fB-height\fP options or defaulted.
+.sp
+From January through May 2002, the default was to include
+     "setpagedevice" and this option did not exist.  Before
+     January 2002, there was no way to include "setpagedevice"
+     and neither the \fB-setpage\fP nor \fB-nosetpage\fP option existed.
+     
+.TP
+\fB-nosetpage\fP
+     This tells \fBpnmtops\fP not to include a "setpagedevice"
+     directive in the output.  This is the default, so the option has no
+     effect.
+.sp
+See the \fB-setpage\fP option for the history of this option.
+
+.TP
+\fB-noshowpage\fP
+     This tells \fBpnmtops\fP not to include a "showpage"
+     directive in the output.  By default, \fBpnmtops\fP includes a
+     "showpage" at the end of the EPSF program.  According to
+     EPSF specs, this is OK, and the program that includes the EPSF is
+     supposed to redefine showpage so this doesn't cause undesirable
+     behavior.  But it's often easier just not to have the showpage.
+.sp
+This options was new in Netpbm 10.27 (March 2005).  Earlier
+     versions of \fBpnmtops\fP always include the showpage.
+
+.TP
+\fB-showpage\fP
+    This tells \fBpnmtops\fP to include a "showpage" directive
+    at the end of the EPSF output.  This is the default, so the option has
+    no effect.
+.sp
+This option was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-verbose\fP
+    This causes informational messages about the conversion process and
+    result.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+If the PNM image has a maxval greater than 255, \fBpnmtops\fP will
+produce output with 8 bits per sample resolution unless you specify
+-psfilter, even though Postscript Level 2 has a 12 bits per sample
+format.  \fBpnmtops\fP's custom raster-generating code just doesn't
+know the 12 bit format.
+
+.UN applications
+.SH APPLICATIONS
+.PP
+You can use the Postscript output a number of ways.  Many printers take
+Postscript input (but you still need some kind of printer driver to transport
+the Postscript to the printer).
+.PP
+There is also the Ghostscript program (not part of Netpbm), which takes
+Postscript as input and generates an output stream to control any of myriad
+models of printer (but you still need some kind of printer driver to transport
+that stream to the printer).
+.PP
+Ghostscript also can convert the Postscript file to PDF, which is a very
+popular document and image format.  Use Ghostscript's \fBpdfwrite\fP output
+device type.  The program \fBps2pdf\fP (distributed with Ghostscript) is a
+convenient way to run Ghostscript with \fBpdfwrite\fP.
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "\fBbmpp\fP" (1)\c
+\& converts
+from Netpbm and other formats to Encapsulated Postscript.
+
+\fBbmpp\fP has a few functions \fBpnmtops\fP does not, such as the ability
+to use LZW compression.
+.PP
+.BR "pnm" (1)\c
+\&,
+\fBgs\fP,
+.BR "psidtopgm" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbmtolps" (1)\c
+\&,
+.BR "pbmtoepsi" (1)\c
+\&,
+.BR "pbmtopsg3" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+
+
+.UN history
+.SH HISTORY
+.PP
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.PP
+Modified November 1993 by Wolfgang Stuerzlinger, \fIwrzl@gup.uni-linz.ac.at\fP
+.PP
+The program was originally \fBpbmtops\fP.  It became \fBpgmtops\fP in
+October 1988 and was merged with \fBppmtops\fP to form \fBpnmtops\fP in
+January 1991.  \fBppmtops\fP came into being some time before September 1989.
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #limitations
+LIMITATIONS
+.UE
+\&
+.IP \(bu
+
+.UR #applications
+APPLICATIONS
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtops.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtorast.1 b/upstream/mageia-cauldron/man1/pnmtorast.1
new file mode 100644
index 00000000..a0005549
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtorast.1
@@ -0,0 +1,78 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtorast User Manual" 0 "12 January 1991" "netpbm documentation"
+
+.SH NAME
+pnmtorast - convert a PPM into a Sun rasterfile
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtorast\fP
+[\fB-standard\fP|\fB-rle\fP]
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtorast\fPreads a PPM image as input and produces a Sun
+rasterfile as output.
+.PP
+Color values in Sun rasterfiles are eight bits wide, so
+\fBpnmtorast\fP will automatically scale colors to have a maxval of
+255.  An extra \fBpamdepth\fP step is not necessary.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtorast\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+
+.TP
+\fB-standard\fP
+.sp
+Forces the result to be in RT_STANDARD form.
+
+.TP
+\fB-rle\fP
+.sp
+Forces the result to be in RT_BYTE_ENCODED, which is smaller but,
+well, less standard.
+.sp
+The default is \fB-rle\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "rasttopnm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtorast.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtorle.1 b/upstream/mageia-cauldron/man1/pnmtorle.1
new file mode 100644
index 00000000..8fba283e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtorle.1
@@ -0,0 +1,133 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtorle User Manual" 0 "07 March 2022" "netpbm documentation"
+
+.SH NAME
+
+pnmtorle - convert a Netpbm image file into an RLE image file.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtorle\fP
+
+[\fB-header\fP]
+[\fB-verbose\fP]
+[\fB-alpha\fP]
+[\fB-outfile=\fP\fIoutfile\fP]
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program converts Netpbm image files into Utah RLE image files.
+You can include a transparency mask.  If the input is a multiple image file,
+the output consists of several concatenated RLE images.
+.PP
+\fIpnmfile\fP is the name of the Netpbm image input file.  If you don't
+specify this argument, input is from Standard Input.
+.PP
+The RLE file will contain either a three channel color image (24 bits) or a
+single channel grayscale image (8 bits) depending upon the type of Netpbm
+input.  If the Netpbm input is color, the RLE output is 3 channel 24 bit
+color.  If the Netpbm input is grayscale or black and white, the RLE output is
+single channel grayscale.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm (most
+notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtorle\fP recognizes the following command line options:
+
+
+.TP
+\fB-verbose\fP
+  This option will cause \fBpnmtorle\fP to operate in verbose mode.  The
+  program writes header information to Standard Error.  Actually, there is not
+  much header information stored in a Netpbm file, so this information is
+  minimal.
+.sp
+Before Netpbm 10.98 (March 2022), this option is just \fB-v\fP.
+
+.TP
+\fB-header\fP
+This option causes the program to dump the header of the Netpbm image to be
+Standard Error without converting the file.  It is equivalent to using
+the \fB-verbose\fP option except that no file conversion takes place.
+.sp
+Before Netpbm 10.98 (March 2022), this option is just \fB-h\fP.
+
+.TP
+\fB-alpha\fP
+This option causes \fBpnmtorle\fP to include a transparency channel in the
+output image.  The transparency channel is based on the image: Wherever a
+pixel is black, the corresponding trasparency value is transparent.
+Everywhere else, the transparency value is fully opaque.
+
+.TP
+\fB-outfile\fP \fIoutfile\fP
+If you specify this option, \fBpnmtorle\fP writes the output to
+this file.  If \fIoutfile\fP is \fB-\fP or you don't specify
+\fB-outfile\fP, \fBpnmtorle\fP writes the output to Standard Output.
+.sp
+Before Netpbm 10.98 (March 2022), this option is just \fB-o\fP.and
+    must be separated from its value by a space, not an equal sign.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+   pnmtorle -verbose file.ppm -outfile=file.rle
+
+.fi
+.PP
+While running in verbose mode, convert file.ppm to RLE format and store
+resulting data in file.rle.
+
+.nf
+   pnmtorle -header file.pgm
+
+.fi
+.PP
+Dump the header information of the Netpbm file called file.pgm.
+
+.UN seealso
+.SH SEE ALSO
+.BR "rletopnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+.nf
+Wes Barris,
+Army High Performance Computing Research Center (AHPCRC)
+Minnesota Supercomputer Center, Inc.
+
+.fi
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtorle.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtosgi.1 b/upstream/mageia-cauldron/man1/pnmtosgi.1
new file mode 100644
index 00000000..36b64404
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtosgi.1
@@ -0,0 +1,81 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtosgi User Manual" 0 "29 January 1994" "netpbm documentation"
+
+.SH NAME
+
+pnmtosgi - convert a PNM image to a SGI image file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtosgi\fP
+
+[\fB-verbatim\fP|\fB-rle\fP]
+
+[\fB-imagename\fP \fIName\fP]
+
+[\fBpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtosgi\fP reads a PNM image as input and produces an SGI
+image file as output.  The SGI image will be 2-dimensional (1 channel)
+for PBM and PGM input, and 3-dimensional (3 channels) for PPM.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtosgi\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbatim\fP
+Write an uncompressed file.
+.TP
+\fB-rle\fP (default)
+Write a compressed (run length encoded) file.
+.TP
+\fB-imagename\fP \fIname\fP
+Write the string "name" into the imagename field of the header.
+The name string is limited to 79 characters.
+If no name is given, pnmtosgi writes "no name" into this field.
+
+
+.UN references
+.SH REFERENCES
+
+SGI Image File Format documentation (draft v0.95) by Paul Haeberli (\fIpaul@sgi.com\fP).  Available via ftp at
+sgi.com:graphics/SGIIMAGESPEC.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&,
+.BR "sgitopnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1994 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtosgi.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtosir.1 b/upstream/mageia-cauldron/man1/pnmtosir.1
new file mode 100644
index 00000000..4c5b9856
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtosir.1
@@ -0,0 +1,59 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtosir User Manual" 0 "20 March 1991" "netpbm documentation"
+
+.SH NAME
+
+pnmtosir - convert a PNM image into a Solitaire format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtosir\fP
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtosir\fP reads a PNM image as input and produces a Solitaire
+Image Recorder format image.
+.PP
+\fBpnmtosir\fP produces an MGI TYPE 17 file for PBM and PGM files.  For
+PPM, it writes a MGI TYPE 11 file.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpnmtosir\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "sirtopnm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Marvin Landis.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtosir.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtotiff.1 b/upstream/mageia-cauldron/man1/pnmtotiff.1
new file mode 100644
index 00000000..fcb0e454
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtotiff.1
@@ -0,0 +1,28 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "pnmtotiff" 1 "September 2005" "netpbm documentation"
+
+.SH NAME
+
+pnmtotiff - replaced by pamtotiff
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+In Netpbm 10.30 (October 2005), \fBpnmtotiff\fP was extended and renamed to
+.BR "pamtotiff" (1)\c
+\&.
+.PP
+\fBpamtotiff\fP is backward compatible with \fBpnmtotiff\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtotiff.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtotiffcmyk.1 b/upstream/mageia-cauldron/man1/pnmtotiffcmyk.1
new file mode 100644
index 00000000..a8d1c9de
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtotiffcmyk.1
@@ -0,0 +1,211 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtotiffcmyk User Manual" 0 "21 March 2017" "netpbm documentation"
+
+.SH NAME
+
+pnmtotiffcmyk - convert a Netpbm image into a CMYK encoded TIFF file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtotiffcmyk \fP
+	[\fB-none\fP|\fB-packbits\fP|\fB-lzw\fP]
+	[\fB-predictor\fP \fIn\fP]
+	[\fB-msb2lsb\fP|\fB-lsb2msb\fP]
+	[\fB-rowsperstrip\fP \fIn\fP]
+	[\fB-lowdotrange\fP \fIn\fP]
+	[\fB-highdotrange\fP \fIn\fP]
+	[\fB-knormal\fP|\fB-konly\fP|\fB-kremove\fP]
+	[[\fB-default\fP]
+        [\fB-theta\fP \fIdeg\fP]
+        [\fB-gamma\fP \fIn\fP]
+        [\fB-gammap\fP \fIn\fP]
+        [\fB-negative\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtotiffcmyk\fPreads a PNM image as input and produces a CMYK
+encoded TIFF file as output.  It optionally modifies the color
+balance and black level, and modifies removal of CMY from under K.
+.PP
+Output is to Standard Output, but unlike with most Netpbm programs,
+Standard Output must be a seekable file.  An ordinary file is fine, but you
+cannot pipe the output to another program.  Furthermore, the program replaces
+any content currently in the file even if it was opened for appending.
+.PP
+\fBpamtotiff\fP generates many other kinds of TIFF files.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtotiffcmyk\fP recognizes the following
+command line options:
+.PP
+The order of most options is not important, but options for particular
+conversion algorithms must appear after the algorithm is selected
+(\fB-default\fP,\fB-negative\fP).  If you don't select an algorithm,
+\fBpnmtotiffcmyk\fP assumes \fB-default\fP and the appropriate
+options (\fB-theta\fP,\fB-gamma\fP,\fB-gammap\fP) can appear
+anywhere.
+
+.SS \fB-none\fP,\fB-packbits\fP,\fB-lzw\fP,\fB-predictor\fP
+.PP
+Tiff files can be compressed.  By default, \fBpnmtotiffcmyk\fP
+uses LZW decompression, but (apparently) some readers cannot read
+this, so you may want to select a different algorithm
+(\fB-none\fP,\fB-packbits\fP).  For LZW compression, a
+\fB-predictor\fP value of 2 forces horizontal differencing of
+scanlines before encoding; a value of 1 forces no differencing.
+
+.SS \fB-msb2lsb\fP,\fB-lsb2msb\fP
+.PP
+These options control fill order (default is \fB-msb2lsb\fP).
+
+.SS \fB-rowsperstrip\fP
+.PP
+This sets the number of rows in an image strip (data in the Tiff
+files generated by this program is stored in strips - each strip is
+compressed individually).  The default gives a strip size of no more
+than 8 kb.
+
+.SS \fB-lowdotrange\fP,\fB-highdotrange\fP
+.PP
+These options set tag values that may be useful for printers.
+
+.SS \fB-knormal\fP,\fB-kremove\fP,\fB-konly\fP
+.PP
+These options control the calculation of the CMYK ink levels.
+They are useful only for testing and debugging the code.
+.PP
+\fB-kremove\fP sets the black (K) levels to zero while leaving the
+other ink levels as they would be if the black level were normal.
+.PP
+\fB-konly\fP sets all inks to the normal black value.
+
+.SS \fB-default\fP,\fB-negative\fP
+.PP
+These options control what ink levels \fBpnmtotiffcmyk\fP uses to
+represent each input color.
+.PP
+\fB-negative\fP selects a simple algorithm that generates a color
+negative.  None of the following options apply to this algorithm.  The
+algorithm is included as an example in the source code to help
+implementors of other conversions.
+.PP
+\fB-default\fP is not necessary, unless you have to countermand a
+\fB-negative\fP on the same command line.  
+.PP
+The default conversion from RGB to CMYK is as follows: The basic
+values of the 3 pigments are C = 1-R, M = 1-G, Y = 1-B.  From this,
+\fBpnmtotiffcmyk\fP chooses a black (K) level which is the minimum of
+those three.  It then replaces that much of the 3 pigments with the
+black.  I.e. it subtracts K from each of the basic C, M, and Y
+values.
+.PP
+The options below modify this conversion.
+
+.SS \fB-theta\fP \fIdeg\fP
+.PP
+\fB-theta\fP provides a simple correction for any color bias that
+may occur in the printed image because, in practice, inks do not
+exactly complement the primary colors.  It rotates the colors (before
+black replacement) by \fIdeg\fP degrees in the color wheel.  Unless
+you are trying to produce unusual effects you will need to use small
+values.  Try generating three images at -10, 0 (the default) and 10
+degrees and see which has the best color balance.
+
+.SS \fB-gamma\fP \fIn\fP
+.PP
+\fB-gamma\fP applies a gamma correction to the black (K) value
+described above.  Specifically, instead of calculating the K value as
+min(C,M,Y), \fBpnmtotiffcmyk\fP raises that value (normalised to the
+range 0 to 1) to the \fIn\fPth power.  In practice, this means that a
+value greater than 1 makes the image lighter and a value less than 1
+makes the image darker.  The range of allowed values is 0.1 to 10.
+
+.SS \fB-gammap\fP \fIn\fP
+.PP
+This option controls the black replacement.
+.PP
+If you specify \fB-gammap\fP, \fBpnmtotiffcmyk\fP uses the specified
+gamma value in computing how much ink to remove from the 3 pigments, but
+still uses the regular gamma value (\fB-gamma\fP option) to generate the
+actual amount of black ink with which to replace it.
+.PP
+Values of \fIn\fP from 0.01 to 10 are valid.
+.PP
+For example, it may be best to only subtract black from the
+colored inks in the very darkest regions.  In that case, \fIn\fP
+should be a large value, such as 5.
+.PP
+As a special case, if \fIn\fP is -1, \fBpnmtotiffcmyk\fP does not
+remove any pigment (but still adds the black ink).  This means dark
+areas are even darker.  Furthermore, when printed, dark areas contain
+a lot of ink which can make high contrast areas, like lettering,
+appear fuzzy.  It's hard to see what the utility of this is.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtotiff" (1)\c
+\&, 
+.BR "tifftopnm" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (c) 1999 Andrew Cooke (Jara Software).  Released under the
+GPL with no warranty.  See source or COPYRIGHT and LICENCE files in
+distribution for full details.
+
+Much of the code uses ideas from other Netpbm programs, written by Jef
+Poskanzer (thanks go to him and libtiff maintainer Sam Leffler).  A
+small section of the code - some of the tiff tag settings - is derived
+directly from pnmtotiff, by Jef Poskanzer, which, in turn,
+acknowledges Patrick Naughton with the following text:
+
+.RS
+.PP
+Derived by Jef Poskanzer from ras2tif.c, which is:
+.PP
+Copyright (c) 1990 by Sun Microsystems, Inc.
+.PP
+Author: Patrick J. Naughton
+\fInaughton@wind.sun.com\fP
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.
+.PP
+This file is provided AS IS with no warranties of any kind.  The
+author shall have no liability with respect to the infringement of
+copyrights, trade secrets or any patents by this file or any part
+thereof.  In no event will the author be liable for any lost revenue
+or profits or other special, indirect and consequential damages.
+
+.RE
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtotiffcmyk.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pnmtoxwd.1 b/upstream/mageia-cauldron/man1/pnmtoxwd.1
new file mode 100644
index 00000000..14291682
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmtoxwd.1
@@ -0,0 +1,83 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtoxwd User Manual" 0 "24 September 1991" "netpbm documentation"
+
+.SH NAME
+
+pnmtoxwd - convert a PNM into an X11 window dump
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtoxwd\fP
+
+[\fB-pseudodepth\fP \fIn\fP]
+
+[\fB-directcolor\fP]
+
+[\fIpnmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtoxwd\fP reads a PNM image as input and produces an X11
+window dump as output.  You can display this output with \fBxwud\fP.
+.PP
+Normally, pnmtoxwd produces a StaticGray dump file for PBM and PGM
+files.  For PPM, it writes a PseudoColor dump file if there are up to
+256 colors in the input, and a DirectColor dump file otherwise.
+.PP
+In an X11 window dump file, various integers can be represented in
+either big endian (most significant byte first) or little endian code.
+Those generated by \fBpnmtoxwd\fP are always big endian.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtoxwd\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-directcolor\fP
+.sp
+Output in DirectColor format.
+
+.TP
+\fB-pseudodepth\fP \fI1-16\fP
+.sp
+Set the depth of PseudoColor dump in bits.  Values between 1 to 16 are
+accepted.  Default is 8 (for a maximum of 256 colors.)
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "xwdtopnm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBxwud\fP
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pnmtoxwd.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pod2html.1 b/upstream/mageia-cauldron/man1/pod2html.1
new file mode 100644
index 00000000..7c420f4f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pod2html.1
@@ -0,0 +1,261 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "POD2HTML 1"
+.TH POD2HTML 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+pod2html \- convert .pod files to .html files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 8
+\&    pod2html \-\-help \-\-htmldir=<name> \-\-htmlroot=<URL>
+\&             \-\-infile=<name> \-\-outfile=<name>
+\&             \-\-podpath=<name>:...:<name> \-\-podroot=<name>
+\&             \-\-cachedir=<name> \-\-flush \-\-recurse \-\-norecurse
+\&             \-\-quiet \-\-noquiet \-\-verbose \-\-noverbose
+\&             \-\-index \-\-noindex \-\-backlink \-\-nobacklink
+\&             \-\-header \-\-noheader \-\-poderrors \-\-nopoderrors
+\&             \-\-css=<URL> \-\-title=<name>
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Converts files from pod format (see perlpod) to HTML format.
+.SH ARGUMENTS
+.IX Header "ARGUMENTS"
+pod2html takes the following arguments:
+.IP backlink 4
+.IX Item "backlink"
+.Vb 2
+\&  \-\-backlink
+\&  \-\-nobacklink
+.Ve
+.Sp
+Turn =head1 directives into links pointing to the top of the HTML file.
+\&\-\-nobacklink (which is the default behavior) does not create these backlinks.
+.IP cachedir 4
+.IX Item "cachedir"
+.Vb 1
+\&  \-\-cachedir=name
+.Ve
+.Sp
+Specify which directory is used for storing cache. Default directory is the
+current working directory.
+.IP css 4
+.IX Item "css"
+.Vb 1
+\&  \-\-css=URL
+.Ve
+.Sp
+Specify the URL of cascading style sheet to link from resulting HTML file.
+Default is none style sheet.
+.IP flush 4
+.IX Item "flush"
+.Vb 1
+\&  \-\-flush
+.Ve
+.Sp
+Flush the cache.
+.IP header 4
+.IX Item "header"
+.Vb 2
+\&  \-\-header
+\&  \-\-noheader
+.Ve
+.Sp
+Create header and footer blocks containing the text of the "NAME" section.
+\&\-\-noheader \-\- which is the default behavior \-\- does not create header or footer
+blocks.
+.IP help 4
+.IX Item "help"
+.Vb 1
+\&  \-\-help
+.Ve
+.Sp
+Displays the usage message.
+.IP htmldir 4
+.IX Item "htmldir"
+.Vb 1
+\&  \-\-htmldir=name
+.Ve
+.Sp
+Sets the directory to which all cross references in the resulting HTML file
+will be relative. Not passing this causes all links to be absolute since this
+is the value that tells Pod::Html the root of the documentation tree.
+.Sp
+Do not use this and \-\-htmlroot in the same call to pod2html; they are mutually
+exclusive.
+.IP htmlroot 4
+.IX Item "htmlroot"
+.Vb 1
+\&  \-\-htmlroot=URL
+.Ve
+.Sp
+Sets the base URL for the HTML files.  When cross-references are made, the
+HTML root is prepended to the URL.
+.Sp
+Do not use this if relative links are desired: use \-\-htmldir instead.
+.Sp
+Do not pass both this and \-\-htmldir to pod2html; they are mutually exclusive.
+.IP index 4
+.IX Item "index"
+.Vb 1
+\&  \-\-index
+.Ve
+.Sp
+Generate an index at the top of the HTML file (default behaviour).
+.RS 4
+.IP noindex 4
+.IX Item "noindex"
+.Vb 1
+\&  \-\-noindex
+.Ve
+.Sp
+Do not generate an index at the top of the HTML file.
+.RE
+.RS 4
+.RE
+.IP infile 4
+.IX Item "infile"
+.Vb 1
+\&  \-\-infile=name
+.Ve
+.Sp
+Specify the pod file to convert.  Input is taken from STDIN if no
+infile is specified.
+.IP outfile 4
+.IX Item "outfile"
+.Vb 1
+\&  \-\-outfile=name
+.Ve
+.Sp
+Specify the HTML file to create.  Output goes to STDOUT if no outfile
+is specified.
+.IP poderrors 4
+.IX Item "poderrors"
+.Vb 2
+\&  \-\-poderrors
+\&  \-\-nopoderrors
+.Ve
+.Sp
+Include a "POD ERRORS" section in the outfile if there were any POD errors in
+the infile (default behaviour).  \-\-nopoderrors does not create this "POD
+ERRORS" section.
+.IP podpath 4
+.IX Item "podpath"
+.Vb 1
+\&  \-\-podpath=name:...:name
+.Ve
+.Sp
+Specify which subdirectories of the podroot contain pod files whose
+HTML converted forms can be linked-to in cross-references.
+.IP podroot 4
+.IX Item "podroot"
+.Vb 1
+\&  \-\-podroot=name
+.Ve
+.Sp
+Specify the base directory for finding library pods.
+.IP quiet 4
+.IX Item "quiet"
+.Vb 2
+\&  \-\-quiet
+\&  \-\-noquiet
+.Ve
+.Sp
+Don't display mostly harmless warning messages.  \-\-noquiet \-\- which is the
+default behavior \-\- \fIdoes\fR display these mostly harmless warning messages (but
+this is not the same as "verbose" mode).
+.IP recurse 4
+.IX Item "recurse"
+.Vb 2
+\&  \-\-recurse
+\&  \-\-norecurse
+.Ve
+.Sp
+Recurse into subdirectories specified in podpath (default behaviour).
+\&\-\-norecurse does not recurse into these subdirectories.
+.IP title 4
+.IX Item "title"
+.Vb 1
+\&  \-\-title=title
+.Ve
+.Sp
+Specify the title of the resulting HTML file.
+.IP verbose 4
+.IX Item "verbose"
+.Vb 2
+\&  \-\-verbose
+\&  \-\-noverbose
+.Ve
+.Sp
+Display progress messages. \-\-noverbose \-\- which is the default behavior \-\-
+does not display these progress messages.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen, <tchrist@perl.com>.
+.SH BUGS
+.IX Header "BUGS"
+See Pod::Html for a list of known bugs in the translator.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlpod, Pod::Html
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+This program is distributed under the Artistic License.
diff --git a/upstream/mageia-cauldron/man1/pod2man.1 b/upstream/mageia-cauldron/man1/pod2man.1
new file mode 100644
index 00000000..85da7a6b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pod2man.1
@@ -0,0 +1,419 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "POD2MAN 1"
+.TH POD2MAN 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+pod2man \- Convert POD data to formatted *roff input
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+pod2man [\fB\-\-center\fR=\fIstring\fR] [\fB\-\-date\fR=\fIstring\fR]
+    [\fB\-\-encoding\fR=\fIencoding\fR] [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-fixed\fR=\fIfont\fR]
+    [\fB\-\-fixedbold\fR=\fIfont\fR] [\fB\-\-fixeditalic\fR=\fIfont\fR]
+    [\fB\-\-fixedbolditalic\fR=\fIfont\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]]
+    [\fB\-\-name\fR=\fIname\fR] [\fB\-\-nourls\fR] [\fB\-\-official\fR]
+    [\fB\-\-release\fR=\fIversion\fR] [\fB\-\-section\fR=\fImanext\fR]
+    [\fB\-\-quotes\fR=\fIquotes\fR] [\fB\-\-lquote\fR=\fIquote\fR] [\fB\-\-rquote\fR=\fIquote\fR]
+    [\fB\-\-stderr\fR] [\fB\-\-utf8\fR] [\fB\-\-verbose\fR] [\fIinput\fR [\fIoutput\fR] ...]
+.PP
+pod2man \fB\-\-help\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpod2man\fR is a wrapper script around the Pod::Man module, using it to
+generate *roff input from POD source.  The resulting *roff code is suitable
+for display on a terminal using \fBnroff\fR\|(1), normally via \fBman\fR\|(1), or
+printing using \fBtroff\fR\|(1).
+.PP
+By default (on non-EBCDIC systems), \fBpod2man\fR outputs UTF\-8 manual pages.
+Its output should work with the \fBman\fR program on systems that use \fBgroff\fR
+(most Linux distributions) or \fBmandoc\fR (most BSD variants), but may result in
+mangled output on older UNIX systems.  To choose a different, possibly more
+backward-compatible output mangling on such systems, use \f(CW\*(C`\-\-encoding=roff\*(C'\fR
+(the default in earlier Pod::Man versions).  See the \fB\-\-encoding\fR option and
+"ENCODING" in Pod::Man for more details.
+.PP
+\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code).
+If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR.  \fIoutput\fR, if given, is the
+file to which to write the formatted output.  If \fIoutput\fR isn't given, the
+formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR.  Several POD files can be processed
+in the same \fBpod2man\fR invocation (saving module load and compile times) by
+providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line.
+.PP
+\&\fB\-\-section\fR, \fB\-\-release\fR, \fB\-\-center\fR, \fB\-\-date\fR, and \fB\-\-official\fR can be
+used to set the headers and footers to use.  If not given, Pod::Man will
+assume various defaults.  See below for details.
+.SH OPTIONS
+.IX Header "OPTIONS"
+Each option is annotated with the version of podlators in which that option
+was added with its current meaning.
+.IP "\fB\-c\fR \fIstring\fR, \fB\-\-center\fR=\fIstring\fR" 4
+.IX Item "-c string, --center=string"
+[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR.  The
+default is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR, but also see \fB\-\-official\fR
+below.
+.IP "\fB\-d\fR \fIstring\fR, \fB\-\-date\fR=\fIstring\fR" 4
+.IX Item "-d string, --date=string"
+[4.00] Set the left-hand footer string for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR.  By
+default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date
+of the input file, or the current date (if input comes from \f(CW\*(C`STDIN\*(C'\fR) will be
+used, and the date will be in UTC.  See "CLASS METHODS" in Pod::Man for more
+details.
+.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4
+.IX Item "-e encoding, --encoding=encoding"
+[5.00] Specifies the encoding of the output.  \fIencoding\fR must be an encoding
+recognized by the Encode module (see Encode::Supported).  The default on
+non-EBCDIC systems is UTF\-8.
+.Sp
+If the output contains characters that cannot be represented in this encoding,
+that is an error that will be reported as configured by the \fB\-\-errors\fR
+option.  If error handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character
+will be replaced with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR).
+.Sp
+If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`groff\*(C'\fR (the default on
+EBCDIC systems), or if the Encode module is not available and the encoding is
+set to anything other than \f(CW\*(C`roff\*(C'\fR (see below), Pod::Man will translate all
+non-ASCII characters to \f(CW\*(C`\e[uNNNN]\*(C'\fR Unicode escapes.  These are not
+traditionally part of the *roff language, but are supported by \fBgroff\fR and
+\&\fBmandoc\fR and thus by the majority of manual page processors in use today.
+.Sp
+If \fIencoding\fR is set to the special value \f(CW\*(C`roff\*(C'\fR, \fBpod2man\fR will do its
+historic transformation of (some) ISO 8859\-1 characters into *roff escapes
+that may be adequate in troff and may be readable (if ugly) in nroff.  This
+was the default behavior of versions of \fBpod2man\fR before 5.00.  With this
+encoding, all other non-ASCII characters will be replaced with \f(CW\*(C`X\*(C'\fR.  It may
+be required for very old troff and nroff implementations that do not support
+UTF\-8, but its representation of any non-ASCII character is very poor and
+often specific to European languages.  Its use is discouraged.
+.Sp
+WARNING: The input encoding of the POD source is independent from the output
+encoding, and setting this option does not affect the interpretation of the
+POD input.  Unless your POD source is US-ASCII, its encoding should be
+declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source.  If this is not done,
+Pod::Simple will will attempt to guess the encoding and may be successful if
+it's Latin\-1 or UTF\-8, but it will produce warnings.  See \fBperlpod\fR\|(1) for
+more information.
+.IP \fB\-\-errors\fR=\fIstyle\fR 4
+.IX Item "--errors=style"
+[2.5.0] Set the error handling style.  \f(CW\*(C`die\*(C'\fR says to throw an exception on
+any POD formatting error.  \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error,
+but not to throw an exception.  \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in
+the resulting documentation summarizing the errors.  \f(CW\*(C`none\*(C'\fR ignores POD
+errors entirely, as much as possible.
+.Sp
+The default is \f(CW\*(C`die\*(C'\fR.
+.IP \fB\-\-fixed\fR=\fIfont\fR 4
+.IX Item "--fixed=font"
+[1.0] The fixed-width font to use for verbatim text and code.  Defaults to
+\&\f(CW\*(C`CW\*(C'\fR.  Some systems may want \f(CW\*(C`CR\*(C'\fR instead.  Only matters for \fBtroff\fR
+output.
+.IP \fB\-\-fixedbold\fR=\fIfont\fR 4
+.IX Item "--fixedbold=font"
+[1.0] Bold version of the fixed-width font.  Defaults to \f(CW\*(C`CB\*(C'\fR.  Only matters
+for \fBtroff\fR output.
+.IP \fB\-\-fixeditalic\fR=\fIfont\fR 4
+.IX Item "--fixeditalic=font"
+[1.0] Italic version of the fixed-width font (something of a misnomer, since
+most fixed-width fonts only have an oblique version, not an italic version).
+Defaults to \f(CW\*(C`CI\*(C'\fR.  Only matters for \fBtroff\fR output.
+.IP \fB\-\-fixedbolditalic\fR=\fIfont\fR 4
+.IX Item "--fixedbolditalic=font"
+[1.0] Bold italic (in theory, probably oblique in practice) version of the
+fixed-width font.  Pod::Man doesn't assume you have this, and defaults to
+\&\f(CW\*(C`CB\*(C'\fR.  Some systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR.
+Only matters for \fBtroff\fR output.
+.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4
+.IX Item "--guesswork=rule[,rule...]"
+[5.00] By default, \fBpod2man\fR applies some default formatting rules based on
+guesswork and regular expressions that are intended to make writing Perl
+documentation easier and require less explicit markup.  These rules may not
+always be appropriate, particularly for documentation that isn't about Perl.
+This option allows turning all or some of it off.
+.Sp
+The special rule \f(CW\*(C`all\*(C'\fR enables all guesswork.  This is also the default for
+backward compatibility reasons.  The special rule \f(CW\*(C`none\*(C'\fR disables all
+guesswork.  Otherwise, the value of this option should be a comma-separated
+list of one or more of the following keywords:
+.RS 4
+.IP functions 4
+.IX Item "functions"
+Convert function references like \f(CWfoo()\fR to bold even if they have no markup.
+The function name accepts valid Perl characters for function names (including
+\&\f(CW\*(C`:\*(C'\fR), and the trailing parentheses must be present and empty.
+.IP manref 4
+.IX Item "manref"
+Make the first part (before the parentheses) of man page references like
+\&\f(CWfoo(1)\fR bold even if they have no markup.  The section must be a single
+number optionally followed by lowercase letters.
+.IP quoting 4
+.IX Item "quoting"
+If no guesswork is enabled, any text enclosed in C<> is surrounded by
+double quotes in nroff (terminal) output unless the contents are already
+quoted.  When this guesswork is enabled, quote marks will also be suppressed
+for Perl variables, function names, function calls, numbers, and hex
+constants.
+.IP variables 4
+.IX Item "variables"
+Convert Perl variable names to a fixed-width font even if they have no markup.
+This transformation will only be apparent in troff output, or some other
+output format (unlike nroff terminal output) that supports fixed-width fonts.
+.RE
+.RS 4
+.Sp
+Any unknown guesswork name is silently ignored (for potential future
+compatibility), so be careful about spelling.
+.RE
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+[1.00] Print out usage information.
+.IP "\fB\-l\fR, \fB\-\-lax\fR" 4
+.IX Item "-l, --lax"
+[1.00] No longer used.  \fBpod2man\fR used to check its input for validity as a
+manual page, but this should now be done by \fBpodchecker\fR\|(1) instead.
+Accepted for backward compatibility; this option no longer does anything.
+.IP \fB\-\-language\fR=\fIlanguage\fR 4
+.IX Item "--language=language"
+[5.00] Add commands telling \fBgroff\fR that the input file is in the given
+language.  The value of this setting must be a language abbreviation for which
+\&\fBgroff\fR provides supplemental configuration, such as \f(CW\*(C`ja\*(C'\fR (for Japanese) or
+\&\f(CW\*(C`zh\*(C'\fR (for Chinese).
+.Sp
+This adds:
+.Sp
+.Vb 2
+\&    .mso <language>.tmac
+\&    .hla <language>
+.Ve
+.Sp
+to the start of the file, which configure correct line breaking for the
+specified language.  Without these commands, groff may not know how to add
+proper line breaks for Chinese and Japanese text if the man page is installed
+into the normal man page directory, such as \fI/usr/share/man\fR.
+.Sp
+On many systems, this will be done automatically if the man page is installed
+into a language-specific man page directory, such as \fI/usr/share/man/zh_CN\fR.
+In that case, this option is not required.
+.Sp
+Unfortunately, the commands added with this option are specific to \fBgroff\fR
+and will not work with other \fBtroff\fR and \fBnroff\fR implementations.
+.IP \fB\-\-lquote\fR=\fIquote\fR 4
+.IX Item "--lquote=quote"
+.PD 0
+.IP \fB\-\-rquote\fR=\fIquote\fR 4
+.IX Item "--rquote=quote"
+.PD
+[4.08] Sets the quote marks used to surround C<> text.  \fB\-\-lquote\fR sets
+the left quote mark and \fB\-\-rquote\fR sets the right quote mark.  Either may
+also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote mark is added
+on that side of C<> text (but the font is still changed for troff output).
+.Sp
+Also see the \fB\-\-quotes\fR option, which can be used to set both quotes at once.
+If both \fB\-\-quotes\fR and one of the other options is set, \fB\-\-lquote\fR or
+\&\fB\-\-rquote\fR overrides \fB\-\-quotes\fR.
+.IP "\fB\-n\fR \fIname\fR, \fB\-\-name\fR=\fIname\fR" 4
+.IX Item "-n name, --name=name"
+[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro to \fIname\fR.
+Without this option, the manual name is set to the uppercased base name of the
+file being converted unless the manual section is 3, in which case the path is
+parsed to see if it is a Perl module path.  If it is, a path like
+\&\f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR is converted into a name like \f(CW\*(C`Pod::Man\*(C'\fR.  This option,
+if given, overrides any automatic determination of the name.
+.Sp
+Although one does not have to follow this convention, be aware that the
+convention for UNIX manual pages is for the title to be in all-uppercase, even
+if the command isn't.  (Perl modules traditionally use mixed case for the
+manual page title, however.)
+.Sp
+This option is probably not useful when converting multiple POD files at once.
+.Sp
+When converting POD source from standard input, the name will be set to
+\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided.  Providing this option is strongly
+recommended to set a meaningful manual page name.
+.IP \fB\-\-nourls\fR 4
+.IX Item "--nourls"
+[2.5.0] Normally, L<> formatting codes with a URL but anchor text are
+formatted to show both the anchor text and the URL.  In other words:
+.Sp
+.Vb 1
+\&    L<foo|http://example.com/>
+.Ve
+.Sp
+is formatted as:
+.Sp
+.Vb 1
+\&    foo <http://example.com/>
+.Ve
+.Sp
+This flag, if given, suppresses the URL when anchor text is given, so this
+example would be formatted as just \f(CW\*(C`foo\*(C'\fR.  This can produce less
+cluttered output in cases where the URLs are not particularly important.
+.IP "\fB\-o\fR, \fB\-\-official\fR" 4
+.IX Item "-o, --official"
+[1.00] Set the default header to indicate that this page is part of the
+standard Perl release, if \fB\-\-center\fR is not also given.
+.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4
+.IX Item "-q quotes, --quotes=quotes"
+[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR.  If
+\&\fIquotes\fR is a single character, it is used as both the left and right quote.
+Otherwise, it is split in half, and the first half of the string is used as
+the left quote and the second is used as the right quote.
+.Sp
+\&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
+marks are added around C<> text (but the font is still changed for troff
+output).
+.Sp
+Also see the \fB\-\-lquote\fR and \fB\-\-rquote\fR options, which can be used to set the
+left and right quotes independently.  If both \fB\-\-quotes\fR and one of the other
+options is set, \fB\-\-lquote\fR or \fB\-\-rquote\fR overrides \fB\-\-quotes\fR.
+.IP "\fB\-r\fR \fIversion\fR, \fB\-\-release\fR=\fIversion\fR" 4
+.IX Item "-r version, --release=version"
+[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro to \fIversion\fR.  By
+default, this is set to the version of Perl you run \fBpod2man\fR under.  Setting
+this to the empty string will cause some *roff implementations to use the
+system default value.
+.Sp
+Note that some system \f(CW\*(C`an\*(C'\fR macro sets assume that the centered footer will be
+a modification date and will prepend something like \f(CW\*(C`Last modified: \*(C'\fR.  If
+this is the case for your target system, you may want to set \fB\-\-release\fR to
+the last modified date and \fB\-\-date\fR to the version number.
+.IP "\fB\-s\fR \fIstring\fR, \fB\-\-section\fR=\fIstring\fR" 4
+.IX Item "-s string, --section=string"
+[1.00] Set the section for the \f(CW\*(C`.TH\*(C'\fR macro.  The standard section numbering
+convention is to use 1 for user commands, 2 for system calls, 3 for functions,
+4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous
+information, and 8 for administrator commands.  There is a lot of variation
+here, however; some systems (like Solaris) use 4 for file formats, 5 for
+miscellaneous information, and 7 for devices.  Still others use 1m instead of
+8, or some mix of both.  About the only section numbers that are reliably
+consistent are 1, 2, and 3.
+.Sp
+By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR, in which
+case section 3 will be selected.
+.IP \fB\-\-stderr\fR 4
+.IX Item "--stderr"
+[2.1.3] By default, \fBpod2man\fR dies if any errors are detected in the POD
+input.  If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are
+sent to standard error, but \fBpod2man\fR does not abort.  This is equivalent to
+\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility.
+.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4
+.IX Item "-u, --utf8"
+[2.1.0] This option used to tell \fBpod2man\fR to produce UTF\-8 output.  Since
+this is now the default as of version 5.00, it is ignored and does nothing.
+.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
+.IX Item "-v, --verbose"
+[1.11] Print out the name of each output file as it is being generated.
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+As long as all documents processed result in some output, even if that output
+includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR),
+\&\fBpod2man\fR will exit with status 0.  If any of the documents being processed
+do not result in an output document, \fBpod2man\fR will exit with status 1.  If
+there are syntax errors in a POD document being processed and the error
+handling style is set to the default of \f(CW\*(C`die\*(C'\fR, \fBpod2man\fR will abort
+immediately with exit status 255.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+If \fBpod2man\fR fails with errors, see Pod::Man and Pod::Simple for
+information about what those errors might mean.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 3
+\&    pod2man program > program.1
+\&    pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
+\&    pod2man \-\-section=7 note.pod > note.7
+.Ve
+.PP
+If you would like to print out a lot of man page continuously, you probably
+want to set the C and D registers to set contiguous page numbering and
+even/odd paging, at least on some versions of \fBman\fR\|(7).
+.PP
+.Vb 1
+\&    troff \-man \-rC1 \-rD1 perl.1 perldata.1 perlsyn.1 ...
+.Ve
+.PP
+To get index entries on \f(CW\*(C`STDERR\*(C'\fR, turn on the F register, as in:
+.PP
+.Vb 1
+\&    troff \-man \-rF1 perl.1
+.Ve
+.PP
+The indexing merely outputs messages via \f(CW\*(C`.tm\*(C'\fR for each major page, section,
+subsection, item, and any \f(CW\*(C`X<>\*(C'\fR directives.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Russ Allbery <rra@cpan.org>, based on the original \fBpod2man\fR by Larry Wall
+and Tom Christiansen.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-2019, 2022 Russ Allbery
+<rra@cpan.org>
+.PP
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Pod::Man, Pod::Simple, \fBman\fR\|(1), \fBnroff\fR\|(1), \fBperlpod\fR\|(1),
+\&\fBpodchecker\fR\|(1), \fBperlpodstyle\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(7)
+.PP
+The man page documenting the an macro set may be \fBman\fR\|(5) instead of
+\&\fBman\fR\|(7) on your system.
+.PP
+The current version of this script is always available from its web site at
+<https://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
+Perl core distribution as of 5.6.0.
diff --git a/upstream/mageia-cauldron/man1/pod2texi.1 b/upstream/mageia-cauldron/man1/pod2texi.1
new file mode 100644
index 00000000..e76c8165
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pod2texi.1
@@ -0,0 +1,249 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "2023-08-15" "perl v5.34.0" "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"
+pod2texi \- convert Pod to Texinfo
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  pod2texi [OPTION]... POD...
+.Ve
+.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
+Texinfo manual.
+.PP
+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"
+.IX Header "OPTIONS"
+.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
+.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
+\&\f(CW@chapter\fR/\f(CW@unnumbered\fR level, 2 to the \f(CW@section\fR level, and so on.
+The default is 0, meaning that \f(CW\*(C`head1\*(C'\fR commands are still output as
+chapters, but the output is arranged as a standalone manual.
+.Sp
+If the level is not 0, the Pod file is rendered as a fragment of a
+Texinfo manual suitable for \f(CW@include\fR.  In this case, each Pod file
+has an additional sectioning command covering the entire file, one level
+above the \f(CW\*(C`\-\-base\-level\*(C'\fR value.  Therefore, to make each Pod file a
+chapter in a large manual, you should use \f(CW\*(C`section\*(C'\fR as the base level.
+.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
+.IX Item "--debug=NUM"
+Set debugging level to \fI\s-1NUM\s0\fR.
+.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
+.IX Item "--help"
+Display help and exit.
+.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
+.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
+.IX Item "--no-section-nodes"
+Use anchors for sections instead of nodes.
+.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
+.IX Item "--preamble=STR"
+Insert \fI\s-1STR\s0\fR as top boilerplate before menu and includes.  If \fI\s-1STR\s0\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
+.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
+.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
+.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
+.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
+.IX Item "--version"
+Display version information and exit.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Pod::Simple::Texinfo.  perlpod.  The Texinfo manual.
+Texinfo home page: <http://www.gnu.org/software/texinfo/>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2012\-2023 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
+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"
+.IX Header "AUTHOR"
+Patrice Dumas <bug\-texinfo@gnu.org>.
diff --git a/upstream/mageia-cauldron/man1/pod2text.1 b/upstream/mageia-cauldron/man1/pod2text.1
new file mode 100644
index 00000000..e286ccf8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pod2text.1
@@ -0,0 +1,294 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "POD2TEXT 1"
+.TH POD2TEXT 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+pod2text \- Convert POD data to formatted ASCII text
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+pod2text [\fB\-aclostu\fR] [\fB\-\-code\fR] [\fB\-e\fR\ \fIencoding\fR]
+    [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]]
+    [\fB\-i\fR\ \fIindent\fR] [\fB\-q\fR\ \fIquotes\fR]
+    [\fB\-\-nourls\fR] [\fB\-\-stderr\fR] [\fB\-w\fR\ \fIwidth\fR] [\fIinput\fR [\fIoutput\fR ...]]
+.PP
+pod2text \fB\-h\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpod2text\fR is a wrapper script around the Pod::Text and its subclasses.
+It uses them to generate formatted text from POD source.  It can optionally
+use either termcap sequences or ANSI color escape sequences to format the
+text.
+.PP
+\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code).
+If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR.  \fIoutput\fR, if given, is the
+file to which to write the formatted output.  If \fIoutput\fR isn't given, the
+formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR.  Several POD files can be processed
+in the same \fBpod2text\fR invocation (saving module load and compile times) by
+providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line.
+.PP
+By default, the output encoding is the same as the encoding of the input file,
+or UTF\-8 if that encoding is not set (except on EBCDIC systems).  See the
+\&\fB\-e\fR option to explicitly set the output encoding and "Encoding" in Pod::Text
+for more discussion.
+.SH OPTIONS
+.IX Header "OPTIONS"
+Each option is annotated with the version of podlators in which that option
+was added with its current meaning.
+.IP "\fB\-a\fR, \fB\-\-alt\fR" 4
+.IX Item "-a, --alt"
+[1.00] Use an alternate output format that, among other things, uses a
+different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a colon in the left
+margin.
+.IP \fB\-\-code\fR 4
+.IX Item "--code"
+[1.11] Include any non-POD text from the input file in the output as well.
+Useful for viewing code documented with POD blocks with the POD rendered and
+the code left intact.
+.IP "\fB\-c\fR, \fB\-\-color\fR" 4
+.IX Item "-c, --color"
+[1.00] Format the output with ANSI color escape sequences.  Using this option
+requires that Term::ANSIColor be installed on your system.
+.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4
+.IX Item "-e encoding, --encoding=encoding"
+[5.00] Specifies the encoding of the output.  \fIencoding\fR must be an encoding
+recognized by the Encode module (see Encode::Supported).  If the output
+contains characters that cannot be represented in this encoding, that is an
+error that will be reported as configured by the \f(CW\*(C`errors\*(C'\fR option.  If error
+handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be replaced
+with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR).
+.Sp
+WARNING: The input encoding of the POD source is independent from the output
+encoding, and setting this option does not affect the interpretation of the
+POD input.  Unless your POD source is US-ASCII, its encoding should be
+declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source, as near to the top of
+the file as possible.  If this is not done, Pod::Simple will will attempt to
+guess the encoding and may be successful if it's Latin\-1 or UTF\-8, but it will
+produce warnings.  See \fBperlpod\fR\|(1) for more information.
+.IP \fB\-\-errors\fR=\fIstyle\fR 4
+.IX Item "--errors=style"
+[2.5.0] Set the error handling style.  \f(CW\*(C`die\*(C'\fR says to throw an exception on
+any POD formatting error.  \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error,
+but not to throw an exception.  \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in
+the resulting documentation summarizing the errors.  \f(CW\*(C`none\*(C'\fR ignores POD
+errors entirely, as much as possible.
+.Sp
+The default is \f(CW\*(C`die\*(C'\fR.
+.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4
+.IX Item "--guesswork=rule[,rule...]"
+[5.01] By default, \fBpod2text\fR applies some default formatting rules based on
+guesswork and regular expressions that are intended to make writing Perl
+documentation easier and require less explicit markup.  These rules may not
+always be appropriate, particularly for documentation that isn't about Perl.
+This option allows turning all or some of it off.
+.Sp
+The special rule \f(CW\*(C`all\*(C'\fR enables all guesswork.  This is also the default for
+backward compatibility reasons.  The special rule \f(CW\*(C`none\*(C'\fR disables all
+guesswork.  Otherwise, the value of this option should be a comma-separated
+list of one or more of the following keywords:
+.RS 4
+.IP quoting 4
+.IX Item "quoting"
+If no guesswork is enabled, any text enclosed in C<> is surrounded by
+double quotes in nroff (terminal) output unless the contents are already
+quoted.  When this guesswork is enabled, quote marks will also be suppressed
+for Perl variables, function names, function calls, numbers, and hex
+constants.
+.RE
+.RS 4
+.Sp
+Any unknown guesswork name is silently ignored (for potential future
+compatibility), so be careful about spelling.
+.RE
+.IP "\fB\-i\fR \fIindent\fR, \fB\-\-indent=\fR\fIindent\fR" 4
+.IX Item "-i indent, --indent=indent"
+[1.00] Set the number of spaces to indent regular text, and the default
+indentation for \f(CW\*(C`=over\*(C'\fR blocks.  Defaults to 4 spaces if this option isn't
+given.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+[1.00] Print out usage information and exit.
+.IP "\fB\-l\fR, \fB\-\-loose\fR" 4
+.IX Item "-l, --loose"
+[1.00] Print a blank line after a \f(CW\*(C`=head1\*(C'\fR heading.  Normally, no blank line
+is printed after \f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR,
+because this is the expected formatting for manual pages; if you're formatting
+arbitrary text documents, using this option is recommended.
+.IP "\fB\-m\fR \fIwidth\fR, \fB\-\-left\-margin\fR=\fIwidth\fR, \fB\-\-margin\fR=\fIwidth\fR" 4
+.IX Item "-m width, --left-margin=width, --margin=width"
+[1.24] The width of the left margin in spaces.  Defaults to 0.  This is the
+margin for all text, including headings, not the amount by which regular text
+is indented; for the latter, see \fB\-i\fR option.
+.IP \fB\-\-nourls\fR 4
+.IX Item "--nourls"
+[2.5.0] Normally, L<> formatting codes with a URL but anchor text are
+formatted to show both the anchor text and the URL.  In other words:
+.Sp
+.Vb 1
+\&    L<foo|http://example.com/>
+.Ve
+.Sp
+is formatted as:
+.Sp
+.Vb 1
+\&    foo <http://example.com/>
+.Ve
+.Sp
+This flag, if given, suppresses the URL when anchor text is given, so this
+example would be formatted as just \f(CW\*(C`foo\*(C'\fR.  This can produce less cluttered
+output in cases where the URLs are not particularly important.
+.IP "\fB\-o\fR, \fB\-\-overstrike\fR" 4
+.IX Item "-o, --overstrike"
+[1.06] Format the output with overstrike printing.  Bold text is rendered as
+character, backspace, character.  Italics and file names are rendered as
+underscore, backspace, character.  Many pagers, such as \fBless\fR, know how to
+convert this to bold or underlined text.
+.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4
+.IX Item "-q quotes, --quotes=quotes"
+[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR.  If
+\&\fIquotes\fR is a single character, it is used as both the left and right quote.
+Otherwise, it is split in half, and the first half of the string is used as
+the left quote and the second is used as the right quote.
+.Sp
+\&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
+marks are added around C<> text.
+.IP "\fB\-s\fR, \fB\-\-sentence\fR" 4
+.IX Item "-s, --sentence"
+[1.00] Assume each sentence ends with two spaces and try to preserve that
+spacing.  Without this option, all consecutive whitespace in non-verbatim
+paragraphs is compressed into a single space.
+.IP \fB\-\-stderr\fR 4
+.IX Item "--stderr"
+[2.1.3] By default, \fBpod2text\fR dies if any errors are detected in the POD
+input.  If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are
+sent to standard error, but \fBpod2text\fR does not abort.  This is equivalent to
+\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility.
+.IP "\fB\-t\fR, \fB\-\-termcap\fR" 4
+.IX Item "-t, --termcap"
+[1.00] Try to determine the width of the screen and the bold and underline
+sequences for the terminal from termcap, and use that information in
+formatting the output.  Output will be wrapped at two columns less than the
+width of your terminal device.  Using this option requires that your system
+have a termcap file somewhere where Term::Cap can find it and requires that
+your system support termios.  With this option, the output of \fBpod2text\fR will
+contain terminal control sequences for your current terminal type.
+.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4
+.IX Item "-u, --utf8"
+[2.2.0] Set the output encoding to UTF\-8.  This is equivalent to
+\&\f(CW\*(C`\-\-encoding=UTF\-8\*(C'\fR and is supported for backward compatibility.
+.IP "\fB\-w\fR, \fB\-\-width=\fR\fIwidth\fR, \fB\-\fR\fIwidth\fR" 4
+.IX Item "-w, --width=width, -width"
+[1.00] The column at which to wrap text on the right-hand side.  Defaults to
+76, unless \fB\-t\fR is given, in which case it's two columns less than the width
+of your terminal device.
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+As long as all documents processed result in some output, even if that output
+includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR),
+\&\fBpod2text\fR will exit with status 0.  If any of the documents being processed
+do not result in an output document, \fBpod2text\fR will exit with status 1.  If
+there are syntax errors in a POD document being processed and the error
+handling style is set to the default of \f(CW\*(C`die\*(C'\fR, \fBpod2text\fR will abort
+immediately with exit status 255.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+If \fBpod2text\fR fails with errors, see Pod::Text and Pod::Simple for
+information about what those errors might mean.  Internally, it can also
+produce the following diagnostics:
+.IP "\-c (\-\-color) requires Term::ANSIColor be installed" 4
+.IX Item "-c (--color) requires Term::ANSIColor be installed"
+(F) \fB\-c\fR or \fB\-\-color\fR were given, but Term::ANSIColor could not be loaded.
+.ie n .IP "Unknown option: %s" 4
+.el .IP "Unknown option: \f(CW%s\fR" 4
+.IX Item "Unknown option: %s"
+(F) An unknown command line option was given.
+.PP
+In addition, other Getopt::Long error messages may result from invalid
+command-line options.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+.IP COLUMNS 4
+.IX Item "COLUMNS"
+If \fB\-t\fR is given, \fBpod2text\fR will take the current width of your screen from
+this environment variable, if available.  It overrides terminal width
+information in TERMCAP.
+.IP TERMCAP 4
+.IX Item "TERMCAP"
+If \fB\-t\fR is given, \fBpod2text\fR will use the contents of this environment
+variable if available to determine the correct formatting sequences for your
+current terminal device.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Russ Allbery <rra@cpan.org>.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-2019, 2022 Russ Allbery
+<rra@cpan.org>
+.PP
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode::Supported, Pod::Text, Pod::Text::Color,
+Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Simple, \fBperlpod\fR\|(1)
+.PP
+The current version of this script is always available from its web site at
+<https://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
+Perl core distribution as of 5.6.0.
diff --git a/upstream/mageia-cauldron/man1/pod2usage.1 b/upstream/mageia-cauldron/man1/pod2usage.1
new file mode 100644
index 00000000..6c095656
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pod2usage.1
@@ -0,0 +1,142 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "POD2USAGE 1"
+.TH POD2USAGE 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+pod2usage \- print usage messages from embedded pod docs in files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.IP \fBpod2usage\fR 12
+.IX Item "pod2usage"
+[\fB\-help\fR]
+[\fB\-man\fR]
+[\fB\-exit\fR\ \fIexitval\fR]
+[\fB\-output\fR\ \fIoutfile\fR]
+[\fB\-verbose\fR \fIlevel\fR]
+[\fB\-pathlist\fR \fIdirlist\fR]
+[\fB\-formatter\fR \fImodule\fR]
+[\fB\-utf8\fR]
+\&\fIfile\fR
+.SH "OPTIONS AND ARGUMENTS"
+.IX Header "OPTIONS AND ARGUMENTS"
+.IP \fB\-help\fR 8
+.IX Item "-help"
+Print a brief help message and exit.
+.IP \fB\-man\fR 8
+.IX Item "-man"
+Print this command's manual page and exit.
+.IP "\fB\-exit\fR \fIexitval\fR" 8
+.IX Item "-exit exitval"
+The exit status value to return.
+.IP "\fB\-output\fR \fIoutfile\fR" 8
+.IX Item "-output outfile"
+The output file to print to. If the special names "\-" or ">&1" or ">&STDOUT"
+are used then standard output is used. If ">&2" or ">&STDERR" is used then
+standard error is used.
+.IP "\fB\-verbose\fR \fIlevel\fR" 8
+.IX Item "-verbose level"
+The desired level of verbosity to use:
+.Sp
+.Vb 3
+\&    1 : print SYNOPSIS only
+\&    2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
+\&    3 : print the entire manpage (similar to running pod2text)
+.Ve
+.IP "\fB\-pathlist\fR \fIdirlist\fR" 8
+.IX Item "-pathlist dirlist"
+Specifies one or more directories to search for the input file if it
+was not supplied with an absolute path. Each directory path in the given
+list should be separated by a ':' on Unix (';' on MSWin32 and DOS).
+.IP "\fB\-formatter\fR \fImodule\fR" 8
+.IX Item "-formatter module"
+Which text formatter to use. Default is Pod::Text, or for very old
+Perl versions Pod::PlainText. An alternative would be e.g. 
+Pod::Text::Termcap.
+.IP \fB\-utf8\fR 8
+.IX Item "-utf8"
+This option assumes that the formatter (see above) understands the option
+"utf8". It turns on generation of utf8 output.
+.IP \fIfile\fR 8
+.IX Item "file"
+The pathname of a file containing pod documentation to be output in
+usage message format. If omitted, standard input is read \- but the
+output is then formatted with Pod::Text only \- unless a specific
+formatter has been specified with \fB\-formatter\fR.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpod2usage\fR will read the given input file looking for pod
+documentation and will print the corresponding usage message.
+If no input file is specified then standard input is read.
+.PP
+\&\fBpod2usage\fR invokes the \fBpod2usage()\fR function in the \fBPod::Usage\fR
+module. Please see "\fBpod2usage()\fR" in Pod::Usage.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Pod::Usage, pod2text, Pod::Text, Pod::Text::Termcap,
+perldoc
+.SH AUTHOR
+.IX Header "AUTHOR"
+Please report bugs using <http://rt.cpan.org>.
+.PP
+Brad Appleton <bradapp@enteract.com>
+.PP
+Based on code for \fBpod2text\|(1)\fR written by
+Tom Christiansen <tchrist@mox.perl.com>
diff --git a/upstream/mageia-cauldron/man1/podchecker.1 b/upstream/mageia-cauldron/man1/podchecker.1
new file mode 100644
index 00000000..0a2c5d08
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/podchecker.1
@@ -0,0 +1,120 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PODCHECKER 1"
+.TH PODCHECKER 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+podchecker \- check the syntax of POD format documentation files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBpodchecker\fR [\fB\-help\fR] [\fB\-man\fR] [\fB\-(no)warnings\fR] [\fIfile\fR\ ...]
+.SH "OPTIONS AND ARGUMENTS"
+.IX Header "OPTIONS AND ARGUMENTS"
+.IP \fB\-help\fR 8
+.IX Item "-help"
+Print a brief help message and exit.
+.IP \fB\-man\fR 8
+.IX Item "-man"
+Print the manual page and exit.
+.IP "\fB\-warnings\fR \fB\-nowarnings\fR" 8
+.IX Item "-warnings -nowarnings"
+Turn on/off printing of warnings. Repeating \fB\-warnings\fR increases the
+warning level, i.e. more warnings are printed. Currently increasing to
+level two causes flagging of unescaped "<,>" characters.
+.IP \fIfile\fR 8
+.IX Item "file"
+The pathname of a POD file to syntax-check (defaults to standard input).
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpodchecker\fR will read the given input files looking for POD
+syntax errors in the POD documentation and will print any errors
+it find to STDERR. At the end, it will print a status message
+indicating the number of errors found.
+.PP
+Directories are ignored, an appropriate warning message is printed.
+.PP
+\&\fBpodchecker\fR invokes the \fBpodchecker()\fR function exported by \fBPod::Checker\fR
+Please see "\fBpodchecker()\fR" in Pod::Checker for more details.
+.SH "RETURN VALUE"
+.IX Header "RETURN VALUE"
+\&\fBpodchecker\fR returns a 0 (zero) exit status if all specified
+POD files are ok.
+.SH ERRORS
+.IX Header "ERRORS"
+\&\fBpodchecker\fR returns the exit status 1 if at least one of
+the given POD files has syntax errors.
+.PP
+The status 2 indicates that at least one of the specified 
+files does not contain \fIany\fR POD commands.
+.PP
+Status 1 overrides status 2. If you want unambiguous
+results, call \fBpodchecker\fR with one single argument only.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Pod::Simple and Pod::Checker
+.SH AUTHORS
+.IX Header "AUTHORS"
+Please report bugs using <http://rt.cpan.org>.
+.PP
+Brad Appleton <bradapp@enteract.com>,
+Marek Rouchal <marekr@cpan.org>
+.PP
+Based on code for \fBPod::Text::pod2text\|(1)\fR written by
+Tom Christiansen <tchrist@mox.perl.com>
diff --git a/upstream/mageia-cauldron/man1/portablectl.1 b/upstream/mageia-cauldron/man1/portablectl.1
new file mode 100644
index 00000000..4dba78bb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/portablectl.1
@@ -0,0 +1,799 @@
+'\" t
+.TH "PORTABLECTL" "1" "" "systemd 255" "portablectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+portablectl \- Attach, detach or inspect portable service images
+.SH "SYNOPSIS"
+.HP \w'\fBportablectl\fR\ 'u
+\fBportablectl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBportablectl\fR
+may be used to attach, detach or inspect portable service images\&. It\*(Aqs primarily a command interfacing with
+\fBsystemd-portabled.service\fR(8)\&.
+.PP
+Portable service images contain an OS file system tree along with
+\fBsystemd\fR(1)
+unit file information\&. A service image may be "attached" to the local system\&. If attached, a set of unit files are copied from the image to the host, and extended with
+\fIRootDirectory=\fR
+or
+\fIRootImage=\fR
+assignments (in case of service units) pointing to the image file or directory, ensuring the services will run within the file system context of the image\&.
+.PP
+Portable service images are an efficient way to bundle multiple related services and other units together, and transfer them as a whole between systems\&. When these images are attached the local system the contained units may run in most ways like regular system\-provided units, either with full privileges or inside strict sandboxing, depending on the selected configuration\&. For more details, see
+\m[blue]\fBPortable Services Documentation\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.PP
+Specifically portable service images may be of the following kind:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Directory trees containing an OS, including the top\-level directories
+/usr/,
+/etc/, and so on\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+btrfs subvolumes containing OS trees, similar to normal directory trees\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Binary "raw" disk images containing MBR or GPT partition tables and Linux file system partitions\&. (These must be regular files, with the
+\&.raw
+suffix\&.)
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR
+.RS 4
+List available portable service images\&. This will list all portable service images discovered in the portable image search paths (see below), along with brief metadata and state information\&. Note that many of the commands below may both operate on images inside and outside of the search paths\&. This command is hence mostly a convenience option, the commands are generally not restricted to what this list shows\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBattach\fR \fIIMAGE\fR [\fIPREFIX\&...\fR]
+.RS 4
+Attach a portable service image to the host system\&. Expects a file system path to a portable service image file or directory as first argument\&. If the specified path contains no slash character ("/") it is understood as image filename that is searched for in the portable service image search paths (see below)\&. To reference a file in the current working directory prefix the filename with
+"\&./"
+to avoid this search path logic\&.
+.sp
+When a portable service is attached four operations are executed:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+All unit files of types
+\&.service,
+\&.socket,
+\&.target,
+\&.timer
+and
+\&.path
+which match the indicated unit file name prefix are copied from the image to the host\*(Aqs
+/etc/systemd/system\&.attached/
+directory (or
+/run/systemd/system\&.attached/
+\(em depending whether
+\fB\-\-runtime\fR
+is specified, see below), which is included in the built\-in unit search path of the system service manager\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+For unit files of type
+\&.service
+a drop\-in is added to these copies that adds
+\fIRootDirectory=\fR
+or
+\fIRootImage=\fR
+settings (see
+\fBsystemd.unit\fR(5)
+for details), that ensures these services are run within the file system of the originating portable service image\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+A second drop\-in is created: the "profile" drop\-in, that may contain additional security settings (and other settings)\&. A number of profiles are available by default but administrators may define their own ones\&. See below\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+If the portable service image file is not already in the search path (see below), a symbolic link to it is created in
+/etc/portables/
+or
+/run/portables/, to make sure it is included in it\&.
+.RE
+.sp
+By default all unit files whose names start with a prefix generated from the image\*(Aqs file name are copied out\&. Specifically, the prefix is determined from the image file name with any suffix such as
+\&.raw
+removed, truncated at the first occurrence of an underscore character ("_"), if there is one\&. The underscore logic is supposed to be used to versioning so that the an image file
+foobar_47\&.11\&.raw
+will result in a unit file matching prefix of
+foobar\&. This prefix is then compared with all unit files names contained in the image in the usual directories, but only unit file names where the prefix is followed by
+"\-",
+"\&."
+or
+"@"
+are considered\&. Example: if a portable service image file is named
+foobar_47\&.11\&.raw
+then by default all its unit files with names such as
+foobar\-quux\-waldi\&.service,
+foobar\&.service
+or
+foobar@\&.service
+will be considered\&. It\*(Aqs possible to override the matching prefix: all strings listed on the command line after the image file name are considered prefixes, overriding the implicit logic where the prefix is derived from the image file name\&.
+.sp
+By default, after the unit files are attached the service manager\*(Aqs configuration is reloaded, except when
+\fB\-\-no\-reload\fR
+is specified (see below)\&. This ensures that the new units made available to the service manager are seen by it\&.
+.sp
+If
+\fB\-\-now\fR
+and/or
+\fB\-\-enable\fR
+are passed, the portable services are immediately started (blocking operation unless
+\fB\-\-no\-block\fR
+is passed) and/or enabled after attaching the image\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBdetach\fR \fIIMAGE\fR [\fIPREFIX\&...\fR]
+.RS 4
+Detaches a portable service image from the host\&. This undoes the operations executed by the
+\fBattach\fR
+command above, and removes the unit file copies, drop\-ins and image symlink again\&. This command expects an image name or path as parameter\&. Note that if a path is specified only the last component of it (i\&.e\&. the file or directory name itself, not the path to it) is used for finding matching unit files\&. This is a convenience feature to allow all arguments passed as
+\fBattach\fR
+also to
+\fBdetach\fR\&.
+.sp
+Added in version 239\&.
+.PP
+If
+\fB\-\-now\fR
+and/or
+\fB\-\-enable\fR
+are passed, the portable services are immediately stopped (blocking operation) and/or disabled before detaching the image\&. Prefix(es) are also accepted, to be used in case the unit names do not match the image name as described in the
+\fBattach\fR\&.
+.RE
+.PP
+\fBreattach\fR \fIIMAGE\fR [\fIPREFIX\&...\fR]
+.RS 4
+Detaches an existing portable service image from the host, and immediately attaches it again\&. This is useful in case the image was replaced\&. Running units are not stopped during the process\&. Partial matching, to allow for different versions in the image name, is allowed: only the part before the first
+"_"
+character has to match\&. If the new image doesn\*(Aqt exist, the existing one will not be detached\&. The parameters follow the same syntax as the
+\fBattach\fR
+command\&.
+.sp
+Added in version 248\&.
+.PP
+If
+\fB\-\-now\fR
+and/or
+\fB\-\-enable\fR
+are passed, the portable services are immediately stopped if removed, started and/or enabled if added, or restarted if updated\&. Prefixes are also accepted, in the same way as described in the
+\fBattach\fR
+case\&.
+.RE
+.PP
+\fBinspect\fR \fIIMAGE\fR [\fIPREFIX\&...\fR]
+.RS 4
+Extracts various metadata from a portable service image and presents it to the caller\&. Specifically, the
+\fBos-release\fR(5)
+file of the image is retrieved as well as all matching unit files\&. By default a short summary showing the most relevant metadata in combination with a list of matching unit files is shown (that is the unit files
+\fBattach\fR
+would install to the host system)\&. If combined with
+\fB\-\-cat\fR
+(see above), the
+os\-release
+data and the units files\*(Aq contents is displayed unprocessed\&. This command is useful to determine whether an image qualifies as portable service image, and which unit files are included\&. This command expects the path to the image as parameter, optionally followed by a list of unit file prefixes to consider, similar to the
+\fBattach\fR
+command described above\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBis\-attached\fR \fIIMAGE\fR
+.RS 4
+Determines whether the specified image is currently attached or not\&. Unless combined with the
+\fB\-\-quiet\fR
+switch this will show a short state identifier for the image\&. Specifically:
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \&Image attachment states
+.TS
+allbox tab(:);
+lB lB.
+T{
+State
+T}:T{
+Description
+T}
+.T&
+l l
+l l
+l l
+l l
+l l
+l l
+l l.
+T{
+\fBdetached\fR
+T}:T{
+The image is currently not attached\&.
+T}
+T{
+\fBattached\fR
+T}:T{
+The image is currently attached, i\&.e\&. its unit files have been made available to the host system\&.
+T}
+T{
+\fBattached\-runtime\fR
+T}:T{
+Like \fBattached\fR, but the unit files have been made available transiently only, i\&.e\&. the \fBattach\fR command has been invoked with the \fB\-\-runtime\fR option\&.
+T}
+T{
+\fBenabled\fR
+T}:T{
+The image is currently attached, and at least one unit file associated with it has been enabled\&.
+T}
+T{
+\fBenabled\-runtime\fR
+T}:T{
+Like \fBenabled\fR, but the unit files have been made available transiently only, i\&.e\&. the \fBattach\fR command has been invoked with the \fB\-\-runtime\fR option\&.
+T}
+T{
+\fBrunning\fR
+T}:T{
+The image is currently attached, and at least one unit file associated with it is running\&.
+T}
+T{
+\fBrunning\-runtime\fR
+T}:T{
+The image is currently attached transiently, and at least one unit file associated with it is running\&.
+T}
+.TE
+.sp 1
+Added in version 239\&.
+.RE
+.PP
+\fBread\-only\fR \fIIMAGE\fR [\fIBOOL\fR]
+.RS 4
+Marks or (unmarks) a portable service image read\-only\&. Takes an image name, followed by a boolean as arguments\&. If the boolean is omitted, positive is implied, i\&.e\&. the image is marked read\-only\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBremove\fR \fIIMAGE\fR\&...
+.RS 4
+Removes one or more portable service images\&. Note that this command will only remove the specified image path itself \(em it refers to a symbolic link then the symbolic link is removed and not the image it points to\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBset\-limit\fR [\fIIMAGE\fR] \fIBYTES\fR
+.RS 4
+Sets the maximum size in bytes that a specific portable service image, or all images, may grow up to on disk (disk quota)\&. Takes either one or two parameters\&. The first, optional parameter refers to a portable service image name\&. If specified, the size limit of the specified image is changed\&. If omitted, the overall size limit of the sum of all images stored locally is changed\&. The final argument specifies the size limit in bytes, possibly suffixed by the usual K, M, G, T units\&. If the size limit shall be disabled, specify
+"\-"
+as size\&.
+.sp
+Note that per\-image size limits are only supported on btrfs file systems\&. Also, depending on
+\fIBindPaths=\fR
+settings in the portable service\*(Aqs unit files directories from the host might be visible in the image environment during runtime which are not affected by this setting, as only the image itself is counted against this limit\&.
+.sp
+Added in version 239\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppresses additional informational output while running\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-p\fR \fIPROFILE\fR, \fB\-\-profile=\fR\fIPROFILE\fR
+.RS 4
+When attaching an image, select the profile to use\&. By default the
+"default"
+profile is used\&. For details about profiles, see below\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-copy=\fR
+.RS 4
+When attaching an image, select whether to prefer copying or symlinking of files installed into the host system\&. Takes one of
+"copy"
+(to prefer copying of files),
+"symlink"
+(to prefer creation of symbolic links) or
+"auto"
+for an intermediary mode where security profile drop\-ins are symlinked while unit files are copied\&. Note that this option expresses a preference only, in cases where symbolic links cannot be created \(em for example when the image operated on is a raw disk image, and hence not directly referentiable from the host file system \(em copying of files is used unconditionally\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-runtime\fR
+.RS 4
+When specified the unit and drop\-in files are placed in
+/run/systemd/system\&.attached/
+instead of
+/etc/systemd/system\&.attached/\&. Images attached with this option set hence remain attached only until the next reboot, while they are normally attached persistently\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-no\-reload\fR
+.RS 4
+Don\*(Aqt reload the service manager after attaching or detaching a portable service image\&. Normally the service manager is reloaded to ensure it is aware of added or removed unit files\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-cat\fR
+.RS 4
+When inspecting portable service images, show the (unprocessed) contents of the metadata files pulled from the image, instead of brief summaries\&. Specifically, this will show the
+\fBos-release\fR(5)
+and unit file contents of the image\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-enable\fR
+.RS 4
+Immediately enable/disable the portable service after attaching/detaching\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-now\fR
+.RS 4
+Immediately start/stop/restart the portable service after attaching/before detaching/after upgrading\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-no\-block\fR
+.RS 4
+Don\*(Aqt block waiting for attach \-\-now to complete\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-extension=\fR\fIPATH\fR
+.RS 4
+Add an additional image
+\fIPATH\fR
+as an overlay on top of
+\fIIMAGE\fR
+when attaching/detaching\&. This argument can be specified multiple times, in which case the order in which images are laid down follows the rules specified in
+\fBsystemd.exec\fR(5)
+for the
+\fIExtensionImages=\fR
+directive and for the
+\fBsystemd-sysext\fR(8)
+and\&.
+\fBsystemd-confext\fR(8)
+tools\&. The images must contain an
+extension\-release
+file with metadata that matches what is defined in the
+os\-release
+of
+\fIIMAGE\fR\&. See:
+\fBos-release\fR(5)\&. Images can be block images, btrfs subvolumes or directories\&. For more information on portable services with extensions, see the
+"Extension Images"
+paragraph on
+\m[blue]\fBPortable Services Documentation\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.sp
+Note that the same extensions have to be specified, in the same order, when attaching and detaching\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-force\fR
+.RS 4
+Skip safety checks and attach or detach images (with extensions) without first ensuring that the units are not running, and do not insist that the
+extension\-release\&.\fINAME\fR
+file in the extension image has to match the image filename\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "FILES AND DIRECTORIES"
+.PP
+Portable service images are preferably stored in
+/var/lib/portables/, but are also searched for in
+/etc/portables/,
+/run/systemd/portables/,
+/usr/local/lib/portables/
+and
+/usr/lib/portables/\&. It\*(Aqs recommended not to place image files directly in
+/etc/portables/
+or
+/run/systemd/portables/
+(as these are generally not suitable for storing large or non\-textual data), but use these directories only for linking images located elsewhere into the image search path\&.
+.PP
+When a portable service image is attached, matching unit files are copied onto the host into the
+/etc/systemd/system\&.attached/
+and
+/run/systemd/system\&.attached/
+directories\&. When an image is detached, the unit files are removed again from these directories\&.
+.SH "PROFILES"
+.PP
+When portable service images are attached a "profile" drop\-in is linked in, which may be used to enforce additional security (and other) restrictions locally\&. Four profile drop\-ins are defined by default, and shipped in
+/usr/lib/systemd/portable/profile/\&. Additional, local profiles may be defined by placing them in
+/etc/systemd/portable/profile/\&. The default profiles are:
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&2.\ \&Profiles
+.TS
+allbox tab(:);
+lB lB.
+T{
+Name
+T}:T{
+Description
+T}
+.T&
+l l
+l l
+l l
+l l.
+T{
+default
+T}:T{
+This is the default profile if no other profile name is set via the \fB\-\-profile=\fR (see above)\&. It\*(Aqs fairly restrictive, but should be useful for common, unprivileged system workloads\&. This includes write access to the logging framework, as well as IPC access to the D\-Bus system\&.
+T}
+T{
+nonetwork
+T}:T{
+Very similar to default, but networking is turned off for any services of the portable service image\&.
+T}
+T{
+strict
+T}:T{
+A profile with very strict settings\&. This profile excludes IPC (D\-Bus) and network access\&.
+T}
+T{
+trusted
+T}:T{
+A profile with very relaxed settings\&. In this profile the services run with full privileges\&.
+T}
+.TE
+.sp 1
+.PP
+For details on these profiles and their effects see their precise definitions, e\&.g\&.
+/usr/lib/systemd/portable/profile/default/service\&.conf
+and similar\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-sysext\fR(8),
+\fBorg.freedesktop.portable1\fR(5),
+\fBsystemd-portabled.service\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Portable Services Documentation
+.RS 4
+\%https://systemd.io/PORTABLE_SERVICES
+.RE
diff --git a/upstream/mageia-cauldron/man1/ppm3d.1 b/upstream/mageia-cauldron/man1/ppm3d.1
new file mode 100644
index 00000000..9d1c72fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppm3d.1
@@ -0,0 +1,135 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppm3d User Manual" 0 "20 February 2007" "netpbm documentation"
+
+.SH NAME
+ppm3d - convert two PPM images into an anaglyph (red/blue 3d glasses) PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppm3d\fP
+[\fB-color\fP]
+[\fB-offset=\fP\fIhorizontal_offset\fP]
+\fIleftppmfile\fP
+\fIrightppmfile\fP
+.PP
+Deprecated optional 3rd argument: \fIhorizontal_offset\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppm3d\fP reads two PPM images as input and produces a PPM as
+output, with the images overlapping by the specified number of pixels
+in blue-green/red format.  The idea is that if you look at the image with
+3-D glasses (glasses that admit only red through one eye and only
+green or blue through the other), you see an image with depth.  This
+is called an anaglyph stereogram.
+.PP
+\fBppm3d\fP can produce either of two kinds of anaglyph stereogram:
+monochrome or color.  Use the \fB-color\fP option to choose.
+.PP
+In the monochrome version, \fBppm3d\fP ignores any color
+(actually, chrominance) in the input images and produces a result
+which is monochrome.  Viewed through red-green glasses it is yellow,
+but without any other color in the field, your brain tends to see it
+as grayscale.
+.PP
+In the color version, \fBppm3d\fP generates a result which is close to the
+color of the original.  It's not great, though, because each eye necessarily
+cannot see the entire spectrum.  Red and cyan don't work well, but most other
+colors -- especially when heavily saturated -- come out quite well.
+.PP
+To view a color anaglyph stereogram, you need glasses with a left
+lens that admits only red light and a right lens that admits only blue
+and green light.  (The right lens may be called a cyan lens because
+that is its pigment in white light; don't be misled into thinking that
+cyan is the only color that gets through it).  Your brain is wired so
+that even though the components of light are coming in through
+different eyes, they mix in your brain to form the same sensation as
+if you were looking at the combined light with both eyes.
+.PP
+The input PPMs must be the same dimensions.
+.PP
+To make a different kind of stereogram, use \fBpamstereogram\fP.
+That makes a stereogram that you view without special glasses, just by
+letting your eyes unfocus so that each eye sees different parts of the
+image.
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+The mandatory arguments are file names of the left and right input
+images.
+.PP
+An optional third argument specifies the same thing as the value of
+the \fB-offset\fP argument, but is deprecated because -offset is easier
+to use and read.  Before Netpbm 10.38 (March 2007), this third argument
+is the only way to specify the offset.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppm3d\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-offset=\fP\fIhorizontal_offset\fP
+This option indicates the amount, in pixels, by which the left and
+image is offset to the right of the right image in the output.
+.sp
+The effect of this option is to move the entire image forward
+(positive numbers) or backward (negative numbers).  With a zero
+offset, the main subject of the picture appears in the plane of the
+picture (i.e. if the image is projected on a screen, the location of
+the screen).  The main subject is the subject at the location where
+the line of sight of the left camera intersects the line of sight of
+the right camera -- the main subject appears at the same location in
+both the left and right images.
+.sp
+Default is zero.
+.sp
+This option was new in Netpbm 10.38 (March 2007).  Before that, use
+the third argument instead.  Also, before Netpbm 10.38 the default is
++30 pixels.
+
+.TP
+\fB-color\fP
+This option causes \fBppm3d\fP to generate a color anaglyph
+stereogram.  By default, it generates monochrome.
+.sp
+This option was new in Netpbm 10.38 (March 2007).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamstereogram" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by David K. Drum.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppm3d.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmbrighten.1 b/upstream/mageia-cauldron/man1/ppmbrighten.1
new file mode 100644
index 00000000..6f1c474a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmbrighten.1
@@ -0,0 +1,45 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmbrighten User Manual" 0 "09 August 2020" "netpbm documentation"
+
+.SH NAME
+
+ppmbrighten - replaced by pambrighten
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+Starting with Netpbm 10.86 (March 2019), \fBppmbrighten\fP is
+obsolete.  Use
+.BR "\fBpambrighten\fP" (1)\c
+\& instead.
+
+\fBpambrighten\fP is mostly backward compatible with \fBppmbrighten\fP.  You
+can use the \fBpambrighten\fP manual for \fBppmbrighten\fP as long as you
+ignore features that were added after Netpbm 10.86.
+.PP
+One way in which \fBpambrighten\fP is not backward compatible is that
+  \fBpambrighten\fP does not have a \fB-normalize\fP option.  If you want
+  that function, use \fBpnmnorm\fP on the image before passing it to
+  \fBpambrighten\fP.
+.PP
+Another backward incompatibility is that \fBpambrighten\fP produces the
+  same kind of output as the input, whereas \fBppmbrighten\fP always
+  produces PPM.  If you need PPM output, pass the results through
+  \fBppmtoppm\fP.
+.PP
+\fBppmbrighten\fP is currently implemented as a triviel program that
+  invokes \fBpambrighten\fP, \fBpnmnorm\fP, and \fBppmtoppm\fP.
+  
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmbrighten.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmchange.1 b/upstream/mageia-cauldron/man1/ppmchange.1
new file mode 100644
index 00000000..5700dc9f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmchange.1
@@ -0,0 +1,178 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmchange User Manual" 0 "December 2016" "netpbm documentation"
+
+.SH NAME
+ppmchange - change all pixels of one color to another in a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmchange\fP
+
+[\fB-closeness=\fP\fIcloseness_percent\fP]
+[\fB-remainder=\fP\fIremainder_color\fP]
+[\fB-closeok\fP]
+[\fIoldcolor newcolor\fP] ...
+[\fIppmfile\fP]
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+\fBppmchange red blue redimage.ppm >blueimage.ppm\fP
+
+\fBppmchange red red -remainder=black myimage.ppm >redblack.ppm\fP
+
+\fBppmchange -closeness=10 white white black black\fP
+
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmchange\fP reads a PPM image as input and changes all pixels of
+color \fIoldcolor\fP to color \fInewcolor\fP.
+
+You may specify up to 256 oldcolor/newcolor pairs on the command line.
+\fBppmchange\fP leaves all colors not mentioned unchanged, unless you
+specify the \fB-remainder\fP option, in which case they are all
+changed to the single specified color.
+.PP
+You can specify that colors similar, but not identical, to the ones
+you specify get replaced by specifying a "closeness" factor.
+.PP
+Specify the colors as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.PP
+If a pixel matches two different \fIoldcolor\fPs, \fBppmchange\fP
+replaces it with the \fInewcolor\fP of the leftmost specified one.
+.PP
+The maxval of the output image is the same as that of the input
+image.  If a \fInewcolor\fP you specify cannot be exactly represented
+in that maxval, \fBppmchange\fP assumes a color that is as close as
+possible to what you specified but can be represented with your
+maxval.  Unless you specify the \fB-closeok\fP option,
+\fBppmchange\fP issues a warning that it is using an approximation.
+.PP
+A common way that you can have this maxval problem, where the color
+you specify cannot be represented with your maxval, is that your input
+is a PBM (black and white) image that you are colorizing.  The maxval
+in this case is 1, which severely limits the colors to which you can
+change.  To avoid this problem, use \fBpamdepth\fP to make the maxval
+of your input something consistent with your colors.  255 is usually a
+good choice.
+.PP
+Before Netpbm 10.22 (April 2004), \fBppmchange\fP always behaved as
+if the user specified \fB-closeok\fP, and there was no \fB-closeok\fP
+option.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmchange\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-closeness \fP\fIcloseness_percent\fP
+\fIcloseness\fP is a percentage indicating how close to the color you
+specified a pixel must be to get replaced.  By default, it is 0, which means
+the pixel must be the exact color you specified.
+.sp
+A pixel gets replaced if the distance in color between it and the
+color you specified is less than or equal to \fIcloseness\fP per cent
+of the maxval.
+.sp
+The "distance" in color is defined as the Cartesian sum of the
+individual differences in red, green, and blue intensities between the
+two pixels, normalized so that the difference between black and white
+is 100%.
+.sp
+This is probably simpler than what you want most the time.  You
+probably would like to change colors that have similar chrominance,
+regardless of their intensity.  So if there's a red barn that is
+variously shadowed, you want the entire barn changed.  But because the
+shadowing significantly changes the color according to
+\fBppmchange\fP's distance formula, parts of the barn are probably
+about as distant in color from other parts of the barn as they are
+from green grass next to the barn.
+.sp
+Maybe \fBppmchange\fP will be enhanced some day to do chrominance
+analysis.
+.sp
+This option was new in Netpbm 9.8 (September 2000).
+
+.TP
+\fB-closeok\fP
+This option affects how \fBppmchange\fP interprets a color you
+specify in the arguments.  When you specify this option, \fBppmchange\fP
+may use a color close to, but not the same as what you specify.  See
+.UR #description
+the description section
+.UE
+\& for details.
+.sp
+This option was new in Netpbm 10.22 (April 2004).  Before that,
+\fBppmchange\fP always behaved as if you specified this option.
+     
+.TP
+\fB-remainder \fP\fIcolor\fP
+\fBppmchange\fP changes all pixels which are not of a color for
+which you specify an explicit replacement color on the command line to
+color \fIcolor\fP.
+.sp
+An example application of this is
+
+.nf
+\fBppmchange -remainder=black red red\fP
+
+.fi
+
+to lift only the red portions from an image, or
+.nf
+\fBppmchange -remainder=black red white | ppmtopgm\fP
+
+.fi
+
+to create a mask file for the red portions of the image.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtoppm" (1)\c
+\&,
+.BR "ppmcolormask" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Wilson H. Bent. Jr. (\fIwhb@usc.edu\fP)
+with modifications by Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmchange.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmcie.1 b/upstream/mageia-cauldron/man1/ppmcie.1
new file mode 100644
index 00000000..ab15f05c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmcie.1
@@ -0,0 +1,372 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmcie User Manual" 0 "31 July 2005" "netpbm documentation"
+
+.SH NAME
+
+ppmcie - draw a CIE color chart as a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmcie\fP
+
+[
+\fB-rec709\fP|\fB-cie\fP|\fB-ebu\fP|\fB-hdtv\fP|\fB-ntsc\fP|\fB-smpte\fP
+]
+[\fB-xy\fP|\fB-upvp\fP]
+
+[\fB-red\fP \fIrx\fP \fIry\fP]
+
+[\fB-green\fP \fIgx\fP \fIgy\fP]
+
+[\fB-blue\fP \fIbx\fP \fIby\fP]
+
+[\fB-white\fP \fIwx\fP \fIwy\fP]
+
+[\fB-size\fP \fIedge\fP]
+
+[{\fB-xsize\fP|\fB-width\fP} \fIwidth\fP]
+
+[{\fB-ysize\fP|\fB-height\fP} \fIheight\fP]
+
+[\fB-noblack\fP]
+[\fB-nowpoint\fP]
+[\fB-nolabel\fP]
+[\fB-noaxes\fP]
+[\fB-full\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBppmcie\fP creates a PPM file containing a plot of the CIE
+"tongue" color chart -- to the extent possible in a PPM
+image.  Alternatively, creates a pseudo-PPM image of the color tongue
+using RGB values from a color system of your choice.
+.PP
+The CIE color tongue is an image of all the hues that can be described
+by CIE X-Y chromaticity coordinates.  They are arranged on a two
+dimensional coordinate plane with the X chromaticity on the horizontal
+axis and the Y chromaticity on the vertical scale.  (You can choose
+alternatively to use CIE u'-v' chromaticity coordinates, but the
+general idea of the color tongue is the same).
+.PP
+Note that the PPM format specifies that the RGB values in the file are
+from the ITU-R Recommendation BT.709 color system, gamma-corrected.
+And positive.  See
+.BR "ppm" (1)\c
+\& for details.  If
+you use one of the color system options on \fBppmcie\fP, what you get
+is not a true PPM image, but is very similar.  If you display such
+\fBppmcie\fP output using a device that expects PPM input (which
+includes just about any computer graphics display program), it will
+display the wrong colors.
+.PP
+However, you may have a device that expects one of these variations on 
+PPM.
+.PP
+In every RGB color system you can specify, including the default
+(which produces a true PPM image) there are hues in the color tongue
+that can't be represented.  For example, monochromatic blue-green with 
+a wavelength of 500nm cannot be represented in a PPM image.  
+.PP
+For these hues, \fBppmcie\fP substitutes a similar hue as follows:
+They are desaturated and rendered as the shade where the edge of the
+Maxwell triangle intersects a line drawn from the requested shade to
+the white point defined by the color system's white point.
+Furthermore, unless you specify the \fB-full\fP option, \fBppmcie\fP
+reduces their intensity by 25% compared to the true hues in the image.
+.PP
+\fBppmcie\fP draws and labels the CIE X-Y coordinate axes unless you
+choose otherwise with options.
+.PP
+\fBppmcie\fP draws the Maxwell triangle for the color system in use
+on the color tongue.  The Maxwell triangle is the triangle whose
+vertices are the primary illuminant hues for the color system.  The
+hues inside the triangle show the color gamut for the color system.
+They are also the only ones that are correct for the CIE X-Y
+chromaticity coordinates shown.  (See explanation above).  \fBppmcie\fP
+denotes the Maxwell triangle by rendering it at full brightness, while
+rendering the rest of the color tongue as 3/4 brightness.  You can turn
+this off with options.
+.PP
+\fBppmcie\fP also places a black cross at the color system's white
+point (with the center of the cross open so you can actually see the
+white color) and displays in text the CIE X-Y chromaticities of the
+primary illuminants and white point for the color system.  You can
+turn this off with options, though.
+.PP
+\fBppmcie\fP annotates the periphery of the color tongue with the
+wavelength, in nanometers of the monochromatic hues which appear
+there.
+.PP
+\fBppmcie\fP displays the black body chromaticity curve for Planckian
+radiators from 1000 to 30000 kelvins on the image.  This curve traces the
+colors of black bodies as various temperatures.
+.PP
+You can choose from several standard color systems, or specify one of
+your own numerically.
+.PP
+CIE charts, by their very nature, contain a very large number of
+colors.  If you're encoding the chart for a color mapped device or
+file format, you'll need to use \fBpnmquant\fP or \fBppmdither\fP to
+reduce the number of colors in the image.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmcie\fP recognizes the following
+command line options:
+.PP
+You may abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB-rec709\fP
+.TP
+\fB-cie\fP
+.TP
+\fB-ebu\fP
+.TP
+\fB-hdtv\fP
+.TP
+\fB-ntsc\fP
+.TP
+\fB-smpte\fP
+Select a standard color system whose gamut to plot.  The default is
+\fB-rec709\fP, which chooses ITU-R Recommendation BT.709,
+gamma-corrected.  This is the only color system for which
+\fBppmcie\fP's output is a true PPM image.  See explanation above.
+\fB-ebu\fP chooses the primaries used in the PAL and SECAM
+broadcasting standards.  \fB-ntsc\fP chooses the primaries specified
+by the NTSC broadcasting system (few modern monitors actually cover
+this range).  \fB-smpte\fP selects the primaries recommended by the
+Society of Motion Picture and Television Engineers (SMPTE) in
+standards RP-37 and RP-145, and \fB-hdtv\fP uses the much broader
+\fIHDTV ideal\fP primaries.  \fB-cie\fP chooses a color system that
+has the largest possible gamut within the spectrum of the chart.  This
+is the same color system as you get with the \fB-cie\fP option to
+John Walker's \fBcietoppm\fP program.
+
+.TP
+\fB-xy\fP
+plot CIE 1931 x y chromaticities.  This is the default.
+
+.TP
+\fB-upvp\fP
+plot u' v' 1976 chromaticities rather than CIE 1931 x y
+chromaticities.  The advantage of u' v' coordinates is that equal
+intervals of distance on the u' v' plane correspond roughly to the
+eye's ability to discriminate colors.
+
+.TP
+\fB-red\fP\fI rx ry\fP
+specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the red
+illuminant of a custom color system and selects the custom system.
+
+.TP
+\fB-green\fP\fI gx gy\fP
+specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the green
+illuminant of the color system and selects the custom system.
+
+.TP
+\fB-blue\fP\fI bx by\fP
+specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the blue
+illuminant of the color system and selects the custom system.
+
+.TP
+\fB-white\fP\fI wx wy\fP
+specifies the CIE \fIx\fP and \fIy\fP co-ordinates of the white
+point of the color system and selects the custom system.
+
+.TP
+\fB-size\fP\fI edge\fP
+Create an image of \fIedge\fP by \fIedge\fP pixels.  The default is
+512x512.
+
+.TP
+\fB-xsize|-width\fP\fI width\fP
+Sets the width of the generated image to \fIwidth\fP pixels.  The
+default width is 512 pixels.  If the height and width of the image are
+not the same, the CIE diagram will be stretched in the longer
+dimension.
+
+.TP
+\fB-ysize|-height\fP\fI height\fP
+Sets the height of the generated image to \fIheight\fP pixels.  The
+default height is 512 pixels.  If the height and width of the image
+are not the same, the CIE diagram will be stretched in the longer
+dimension.
+
+.TP
+\fB-noblack\fP
+Don't plot the black body chromaticity curve.
+
+.TP
+\fB-nowpoint\fP
+Don't plot the color system's white point.
+
+.TP
+\fB-nolabel\fP
+Omit the label.
+
+.TP
+\fB-noaxes\fP
+Don't plot axes.
+
+.TP
+\fB-full\fP
+Plot the entire CIE tongue in full brightness; don't dim the part
+which is outside the gamut of the specified color system (i.e. outside
+the Maxwell triangle).
+
+
+
+.UN interpretation
+.SH INTERPRETATION OF COLOR CHART
+.PP
+A color spectrum is a linear combination of one or more monochromatic
+colors.
+.PP
+A color is a set of color spectra that all look the same to the
+human eye (and brain).  Actually, for the purposes of the definition,
+we assume the eye has infinite precision, so we can call two color
+spectra different colors even though they're so close a person
+couldn't possibly tell them apart.
+.PP
+The eye contains 3 kinds of color receptors (cones).  Each has a
+different response to the various monochromatic colors.  One kind
+responds most strongly to blue, another red, another green.  Because
+there are only three, many different color spectra will excite the
+cones at exactly the same level, so the eye cannot tell them apart.
+All such spectra that excite the cones in the same way are a single
+color.
+.PP
+Each point in the color tongue represents a unique color.  But
+there are an infinite number of color spectra in the set that is that
+color; i.e. an infinite number of color spectra that would look to you
+like this point.  A machine could tell them apart, but you could not.
+.PP
+Remember that the colors outside the highlighted triangle are
+approximations of the real colors because the PPM format cannot
+represent them (and your display device probably cannot display them).
+That is, unless you're using a variation of PPM and a special display
+device, as discussed earlier in this manual.
+.PP
+A color is always relative to some given maximum brightness.  A
+particular beam of light looks lime green if in a dim field, but
+pea green if in a bright field.  An image on a movie screen may
+look pitch black because the projector is not shining any light on
+it, but when you turn off the projector and look at the same spot in
+room light, the screen looks quite white.  The same light from that spot
+hit your eye with the project on as with it off.
+.PP
+The chart shows two dimensions of color.  The third is intensity.
+All the colors in the chart have the same intensity.  To get all
+possible colors in the gamut, Make copies of the whole chart at every
+intensity between zero and the maximum.
+.PP
+The edge of the tongue consists of all the monochromatic colors.
+A monochromatic color is one with a single wavelength.  I.e. a color
+that is in a rainbow.  The numbers you see are the wavelengths in
+nanometers.
+.PP
+Any straight line segment within the tongue contains colors which
+are linear combinations of two colors -- the colors at either end of
+the line segment.
+.PP
+Any color in the chart can be created from two other colors (actually,
+from any of an infinite number of pairs of other colors).
+.PP
+All the colors within a triangle inside the tongue can be created
+from a linear combination of the colors at the vertices of that triangle.
+.PP
+Any color in the tongue can be created from at most 3 monochromatic
+colors.
+.PP
+The highlighted triangle shows the colors that can be expressed
+in the tristimulus color system you chose.  (ITU-R BT.709 by default).
+The corners of the triangle are the 3 primary illuminants in that
+system (a certain red, green, and blue for BT.709).  The edges of
+the triangle, then, represent the colors you can represent with two
+of the primary illuminants (saturated colors), and the interior colors
+require all three primary illuminants (are not saturated).
+.PP
+In the ITU-R BT.709 color system (the default), the white point is
+defined as D65, which is (and is named after) the color of a black
+body at 6502 kelvins.  Therefore, you should see the temperature curve
+on the image pass through the white part of the image, and the cross
+that marks the white point, at 6502 kelvins.
+.PP
+D65 white is supposed to be the color of the sun.  If you have a
+perfect BT.709 display device, you should see the color of the sun
+at the white point cross.  That's an important color, because when you
+look at an object in sunlight, the color that reflects of the object
+is based on the color of sunlight.  Note that the sun produces a
+particular color spectrum, but many other color spectra are the same
+color, and display devices never use the actual color spectrum of the
+sun.
+.PP
+The colors at the corners of the triangle have the chromaticities
+phosphors in a monitor that uses the selected color system.  Note
+that in BT.709 they are very close to monochromatic red, green,
+and blue, but not quite.  That's why you can't display even one true
+color of the rainbow on a video monitor.
+.PP
+Remember that the chart shows colors of constant intensity,
+therefore the corners of the triangles are not the full colors of the
+primary illuminants, but only their chromaticities.  In fact, the
+illuminants typically have different intensities.  In BT.709, the
+blue primary illuminant is far more intense than the green, which is
+more intense than the red.  Designers did this in order to make an
+equal combination of red, green, and blue generate gray.  I.e.  a
+combination of full strength red, full strength green, and full
+strength blue BT.709 primary illuminants is D65 white.
+.PP
+The tongue has a sharp straight edge at the bottom because that's
+the limit of human vision.  There are colors below that line, but they
+involve infrared and ultraviolet light, so you can't see them.  This
+line is called the "line of purples."
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdither" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1995 by John Walker (\fIkelvin@fourmilab.ch\fP)
+.PP
+WWW home page: 
+.UR http://www.fourmilab.ch/
+http://www.fourmilab.ch/
+.UE
+\&
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided as
+is without express or implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmcie.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmcolormask.1 b/upstream/mageia-cauldron/man1/ppmcolormask.1
new file mode 100644
index 00000000..0a29174a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmcolormask.1
@@ -0,0 +1,149 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmcolormask User Manual" 0 "01 May 2006" "netpbm documentation"
+
+.SH NAME
+ppmcolormask - produce mask of areas of a certain color in a PPM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmcolormask\fP \fB-color=\fP\fIcolor_list\fP [\fIppmfile\fP]
+.PP
+\fBppmcolormask\fP \fIcolor\fP [\fIppmfile\fP]
+
+.UN examples
+.SH EXAMPLES
+
+.nf
+\f(CW
+    ppmcolormask -color red testimg.ppm >redmask.pbm
+    pamcomp background.ppm testimg.ppm -alpha=redmask.pbm >test.ppm
+
+    ppmcolormask -color=red,pink,salmon testimg.ppm >reddishmask.pbm
+
+    ppmcolormask -color=bk:red,bk:orange,bk:yellow testimg.ppm >firemask.pbm
+
+\fP
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmcolormask\fP reads a PPM file as input and produces a PBM
+(bitmap) file as output.  The output file is the same dimensions as
+the input file and is black in all places where the input file is a
+color indicated by the \fB-color\fP option, and white everywhere
+else.
+.PP
+The output of \fBppmcolormask\fP is useful as a transparency mask input
+to \fBpamcomp\fP.  Note that you don't need \fBppmcolormask\fP and
+\fBpamcomp\fP if you are ultimately converting to PNG with
+\fBpnmtopng\fP because the \fB-transparent\fP option on \fBpnmtopng\fP does
+the same thing.
+.PP
+\fIppmfile\fP is the input file.  If you don't specify
+\fIppmfile\fP, the input is from Standard Input.
+.PP
+The output goes to Standard Output.
+.PP
+In the obsolete alternative syntax, specifying the \fIcolor\fP
+names a single exact color to be masked.
+.PP
+\fBppmchange\fP does a similar thing: it modifies an image by
+changing colors you specify to other colors you specify.  The two
+programs give you somewhat different means of specifying colors in the
+input image.
+.PP
+To make a mask of an image's background, without having to tell it
+what color it is, use \fBpambackground\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmcolormask\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-color=\fP\fIcolor_list\fP
+This mandatory option specifies the colors that are to be masked
+(where the image is one of these colors, the output mask will be black).
+.sp
+Examples:
+
+
+.IP \(bu
+\fB-color=red\fP
+.IP \(bu
+\fB-color=red,pink,salmon\fP
+.IP \(bu
+\fB-color=rgb:80/80/ff\fP
+.IP \(bu
+\fB-color=bk:red,bk:orange,bk:yellow\fP
+
+.sp
+\fIcolor_list\fP is a list of colors separated by commas.  Each
+color is either an exact color name as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\& or one of the 
+.UR libppm.html#berlinkay
+Berlin-Kay color names
+.UE
+\&.  In the
+latter case, all colors that are better described by that Berlin-Kay
+color name than any other are in the mask set.
+.sp
+The algorithm \fBppmcolormask\fP uses to determine to which colors
+a Berlin-Kay color name applies is based on a Sugeno-type fuzzy
+inference system developed by \fIKenan Kalajdzic\fP in 2006.  The
+fuzzy model consists of partially linear membership functions defined
+in the HSV color space.  Although more complex algorithms for fuzzy
+color matching exist, this algorithm is intentionally simplified to
+achieve a satisfactory speed using relatively compact code.
+.sp
+This option was new in Netpbm 10.34 (June 2006).  Before that,
+you must use the \fIcolor\fP argument and cannot specify a Berlin-Kay
+color.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfind" (1)\c
+\&,
+.BR "pambackground" (1)\c
+\&,
+.BR "ppmchange" (1)\c
+\&,
+.BR "pgmtoppm" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pbmmask" (1)\c
+\&,
+.BR "pnmtopng" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmcolormask.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmcolors.1 b/upstream/mageia-cauldron/man1/ppmcolors.1
new file mode 100644
index 00000000..db1eedcc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmcolors.1
@@ -0,0 +1,33 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmcolors User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+ppmcolors - obsolete
+
+.UN description
+.SH DESCRIPTION
+.PP
+\fBppmcolors\fP is obsolete.  The more general program
+.BR "pamseq" (1)\c
+\& took its place in June 2002.
+
+\fBppmcolors\fP remains for backward compatibility, but all it does
+is run \fBpamseq\fP.  It is slower and less flexible than running
+\fBpamseq\fP directly.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamseq" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmcolors.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdcfont.1 b/upstream/mageia-cauldron/man1/ppmdcfont.1
new file mode 100644
index 00000000..22264850
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdcfont.1
@@ -0,0 +1,59 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdcfont User Manual" 0 "September 2005" "netpbm documentation"
+
+.SH NAME
+
+ppmdcfont - Turn a Ppmdfont file into C source for a builtin font
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmdcfont\fP
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+(There are no arguments or options)
+.PP
+\fBppmdcfont\fP creates a C source file that you can compile into
+a built-in font for use with the Netpbm PPM drawing facilities.  It
+reads a Ppmdfont file on Standard Input and writes the C source code to
+Standard Output.
+.PP
+The output C source code has the font object's name hardcoded as
+\fBppmd_standardfont\fP, which you will definitely want to edit,
+because that is the name of the font built in to \fBlibnetpbm\fP.  If
+you don't change it, it will conflict both cognitively and in program
+linking.  There should obviously be an option on \fBppmdcfont\fP to
+choose this, but the development effort has not been justified so far.
+.PP
+See
+.BR "Libnetpbm PPM Drawing Function
+Manual" (1)\c
+\& for details on Ppmdfont files.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdraw" (1)\c
+\&,
+.BR "ppmddumpfont" (1)\c
+\&,
+.BR "ppmdcfont" (1)\c
+\&,
+.BR "Libnetpbm PPM Drawing Function Manual" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdcfont.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmddumpfont.1 b/upstream/mageia-cauldron/man1/ppmddumpfont.1
new file mode 100644
index 00000000..e0729b59
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmddumpfont.1
@@ -0,0 +1,50 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmddumpfont User Manual" 0 "September 2005" "netpbm documentation"
+
+.SH NAME
+
+ppmddumpfont - dump a Ppmdfont file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmddumpfont\fP
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmddumpfont\fP reads a Ppmdfont file on Standard Input and
+writes to Standard Error a human readable description of the font.
+.PP
+(There are no arguments or options)
+.PP
+See
+.BR "Libnetpbm PPM Drawing Function
+Manual" (1)\c
+\& for details on Ppmdfont files.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdraw" (1)\c
+\&,
+.BR "ppmdmkfont" (1)\c
+\&,
+.BR "ppmdcfont" (1)\c
+\&,
+.BR "Libnetpbm PPM Drawing Function Manual" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmddumpfont.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdim.1 b/upstream/mageia-cauldron/man1/ppmdim.1
new file mode 100644
index 00000000..edf37545
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdim.1
@@ -0,0 +1,63 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdim User Manual" 0 "June 2002" "netpbm documentation"
+
+.SH NAME
+ppmdim - dim a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+ppmdim
+\fIdimfactor\fP
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program is largely obsoleted by the more general
+.BR "\fBpamfunc\fP" (1)\c
+\& (use the \fB-multiplier\fP
+option).  \fBppmdim\fP remains for backward compatibility and also
+because its use of integer arithmetic may make it faster.
+
+\fBppmdim\fP reads a PPM image input and diminishes its brightness by
+the specified dimfactor.  The dimfactor may be in the range from 0.0
+(total blackness, deep night, nada, null, nothing) to 1.0 (original
+picture's brightness).
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmdim\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&,
+.BR "pamfunc" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdim.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdist.1 b/upstream/mageia-cauldron/man1/ppmdist.1
new file mode 100644
index 00000000..7f002662
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdist.1
@@ -0,0 +1,89 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdist User Manual" 0 "22 July 1992" "netpbm documentation"
+
+.SH NAME
+
+ppmdist - simplistic grayscale assignment for machine generated, color images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmdist\fP
+
+[\fB-intensity\fP|\fB-frequency\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmdist\fP reads a PPM image as input and performs a simplistic
+grayscale assignment intended for use with grayscale or bitmap
+printers.
+.PP
+Often conversion from ppm to pgm will yield an image with contrast
+too low for good printer output.  The program maximizes contrast
+between the gray levels output.
+.PP
+A ppm input of n colors is read, and a pgm of n gray levels is
+written.  The gray levels take on the values 0..n-1, while maxval
+takes on n-1.
+.PP
+The mapping from color to stepped grayscale can be performed in
+order of input pixel intensity, or input pixel frequency (number of
+repetitions).
+.PP
+This program is helpful only for images with a very small number of
+colors.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmdist\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-frequency\fP
+Sort input colors by the number of times a color appears in the
+input, before mapping to evenly distributed graylevels of output.
+
+.TP
+\fB-intensity\fP
+Sort input colors by their grayscale intensity, before mapping to
+evenly distributed graylevels of output.  This is the default.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Dan Stromberg.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdist.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdither.1 b/upstream/mageia-cauldron/man1/ppmdither.1
new file mode 100644
index 00000000..73c8db2f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdither.1
@@ -0,0 +1,109 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdither User Manual" 0 "16 December 2009" "netpbm documentation"
+
+.SH NAME
+ppmdither - ordered dither for color images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmdither\fP
+
+[\fB-dim\fP=\fIpower\fP]
+
+[\fB-red\fP=\fIn\fP]
+
+[\fB-green\fP=\fIn\fP]
+
+[\fB-blue\fP=\fIn\fP]
+
+[\fInetpbmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmdither\fP reads a Netpbm image as input, and applies dithering
+to it to reduce the number of colors used down to the specified number
+of shades for each primary.  It produces a PPM image as output.
+.PP
+The default number of shades is 5 red, 9 green, and 5 blue, for a total of
+225 colors.  To convert the image to a binary rgb format suitable for
+primitive color printers, use \fB-red=2 -green=2 -blue=2\fP.
+.PP
+You can do another kind of dither -- Floyd-Steinberg -- with 
+\fBpnmquant\fP or \fBpnmremap\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmdither\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-dim\fP \fIpower\fP
+ The size of the dithering matrix.  The dithering matrix is a
+square whose dimension is a power of 2.  \fIpower\fP is that power of
+2.  The default is 4, for a 16 by 16 matrix.
+
+.TP
+\fB-red\fP=\fIn\fP
+The number of red shades to be used, including black; minimum of 2.
+.sp
+Default is 5.
+
+.TP
+\fB-green\fP \fIn\fP
+The number of green shades to be used, including black; minimum of 2.
+.sp
+Default is 9.
+
+.TP
+\fB-blue\fP \fIn\fP
+The number of blue shades to be used, including black; minimum of 2.
+.sp
+Default is 5.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamditherbw" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Christos Zoulas.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdither.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdmkfont.1 b/upstream/mageia-cauldron/man1/ppmdmkfont.1
new file mode 100644
index 00000000..665cf262
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdmkfont.1
@@ -0,0 +1,52 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdmkfont User Manual" 0 "September 2005" "netpbm documentation"
+
+.SH NAME
+
+ppmdmkfont - Create Ppmdfont "standard".
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmdmkfont\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmdmkfont\fP creates the "standard" Ppmdfont font as
+a Ppmdfont file.  It has no input; it always generates identical files.
+.PP
+(There are no arguments or options)
+.PP
+This program is useful mainly as an example for creating other fonts.
+\fBlibnetpbm\fP has the "standard" font built in.
+.PP
+See
+.BR "Libnetpbm PPM Drawing Function
+Manual" (1)\c
+\& for details on Ppmdfont files.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdraw" (1)\c
+\&,
+.BR "ppmddumpfont" (1)\c
+\&,
+.BR "ppmdcfont" (1)\c
+\&,
+.BR "Libnetpbm PPM Drawing Function Manual" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdmkfont.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmdraw.1 b/upstream/mageia-cauldron/man1/ppmdraw.1
new file mode 100644
index 00000000..d75d5b60
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmdraw.1
@@ -0,0 +1,294 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmdraw User Manual" 0 "22 June 2005" "netpbm documentation"
+
+.SH NAME
+ppmdraw - draw lines, text, etc on a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmdraw\fP
+
+{
+\fB-script=\fP\fIscript\fP
+|
+\fB-scriptfile=\fP\fIfilename\fP
+}
+[\fB-verbose\fP]
+
+[\fIppmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmdraw\fP draws lines, shapes, text, etc. on a PPM image.  It is
+essentially an easy-to-program front end to \fBlibnetpbm\fP's
+"ppmd" subroutines.  It lets you create a human-friendly
+script to describe the drawing rather than write a C program.
+.PP
+You supply drawing instructions with a script, which you supply either
+in a file named by a \fB-scriptfile\fP option or as the value of a
+\fB-script\fP option.  Here is an example script:
+
+.nf
+\f(CW
+setpos 50 50;
+text_here 10 30 "hello";
+setcolor black;
+text_here 10 0 "there";
+line_here 5 20;
+\fP
+
+.fi
+.PP
+This example starts at Column 50, Row 50 of the input image and
+writes the word "hello" there in 10 pixel high white letters
+at a 30 degree angle up from horizontal.  Then, from where that leaves
+off, the script writes "there" in 10 pixel high black
+letters horizontally.  Finally, it draws a black line to a point 5
+pixels over and 20 pixels down from the end of "there."
+.PP
+If you don't specify \fIppmfile\fP, \fBppmdraw\fP reads its input
+PPM image from Standard Input.
+.PP
+The output image goes to Standard Output.
+.PP
+\fBppmdraw\fP works on multi-image streams.  It executes the same
+script on each input image and produces an output stream with one image
+for each input image.  But before Netpbm 10.32 (February 2006),
+\fBppmdraw\fP ignored every image after the first.
+.PP
+If you just want to add a single line of text to an image,
+\fBppmlabel\fP may be more what you want.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmdraw\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-script=\fP\fIscript\fP
+This option gives the script.  See 
+.UR #script
+Script
+.UE
+\&.
+.sp
+You may not specify both \fB-script\fP and \fB-scriptfile\fP.
+
+.TP
+\fB-scriptfile=\fP\fIfilename\fP
+This option names a file that contains the script.  \fB-\fP
+means Standard Input.
+.sp
+You may not specify both \fB-script\fP and \fB-scriptfile\fP.
+.sp
+You may not specify \fB-\fP (Standard Input) for both
+\fB-scriptfile\fP and the input image file.
+
+
+
+
+.UN script
+.SH SCRIPT
+.PP
+The heart of \fBppmdraw\fP function is its script.  The script is
+a character stream.  The stream consists of commands.  Commands are
+separated by semicolons.  White space is regarded just like in C: Any
+contiguous stretch of unquoted white space is equivalent to a single
+space character.  Note that this means newlines have no particular
+significance.
+.PP
+A command is composed of tokens, separated from each other by
+white space.  To write a token that contains white space, enclose
+it in double quotes.  Everything between two matched quotation marks
+is one token.
+.PP
+The first token of a command is the verb, which determines the
+basic function of the command.  The rest of the tokens of the command
+are arguments, the meaning of which depends upon the verb.  The
+following list gives all the valid verbs, and for each its meaning and
+its arguments.
+.PP
+Many command have arguments that specify a position on the canvas,
+which you specify by row and column.  Row 0 is the top row.  Column 0
+is the leftmost column.  You may specify negative numbers (but such
+a position would necessarily be off the canvas).
+.PP
+Your drawing instructions may involve positions not on the canvas.
+But any pixels you draw there just get discarded.
+
+
+.TP
+setpos
+Set the "current position" in the image.  This affects
+where subsequent commands draw things.  The 2 arguments are the column
+and row number.
+.sp
+At the start of the script, the current position is (0,0).
+
+.TP
+setlinetype
+The 1 argument is "normal" or "nodiag.".  This
+effects a \fBppmd_setlinetype()\fP call.  Further details are not yet
+documented.
+
+.TP
+setlineclip
+This effects a \fBppmd_setlineclip()\fP call.  Not yet documented.
+
+.TP
+setcolor
+This sets the "current color", which determines the color
+in which subsequent drawing commands draw.  Before the first
+\fBsetcolor\fP, the current color is white.
+.sp
+There is one argument.  It specifies the color as described for the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+.TP
+setfont
+This sets the "current font", which determines the font
+in which subsequent text drawing commands draw.  Before the first
+\fBsetfont\fP, the current font is a built in font called
+"standard."
+.sp
+The argument of this command is a file name.  It is the name of a
+Netpbm PPMD font file.
+.sp
+A Netpbm PPMD font file typically has a name that ends in
+".ppmdfont" and its first 8 bytes are the ASCII encoding of
+"ppmdfont".
+.sp
+There is only one of these fonts as far as we know.  It is distributed with
+Netpbm as the file \fBstandard.ppmdfont\fP, but you don't need to use that
+file because the same font is built into the Netpbm library and is the
+default.  If you want to make a new font, you can find the format of a
+ppmdfont file in the Netpbm interface header file \fBppmdfont.h\fP, but
+you'll have to make your own tools to build it.  The program \fBppmdmkfont\fP
+generates \fBstandard.ppmdfont\fP, so you can use that as an example.
+
+.TP
+line
+This draws a one pixel wide line in the current color.  The 4 arguments
+are: starting column, starting row, ending column, ending row.
+.sp
+This command does not affect the current position.
+
+.TP
+line_here
+This is like \fBline\fP, except it works in a more relative way.
+.sp
+The line starts at the current point.  The two arguments are the
+rightward and downward displacement from there to the terminal point.
+The command moves the current position to the terminal point after drawing.
+
+.TP
+spline3
+This draws a spline in the current color between 2 points, using a third
+as a control point.  It approximates a cubic spline segment.
+.sp
+The shape of the curve is such that it passes through the specified
+endpoints, and lines tangent to the curve at those endpoints intersect at the
+control point.  Controlling the tangents allows you to connect this curve to
+other curves generated the same way without having corners at the connection
+points.
+.sp
+The 6 arguments are the starting point column, starting point row, control
+point column, control point row, ending point column, and ending point row.
+.sp
+This command does not affect the current position.
+
+.TP
+circle
+This command draws a circle in the current color.  The three
+arguments are the column number and row number of the center of the
+circle and the radius of the circle in pixels.
+
+.TP
+filledrectangle
+This command draws a rectangle filled with the current color.
+
+The 4 arguments are the column and row numbers of the upper left corner
+of the rectangle, the width of the rectangle, and the height of the
+rectangle.
+
+.TP
+text
+This command draws text in the current color in the built-in font.
+The 5 arguments are:
+
+
+.IP \(bu
+column number of starting point of baseline
+.IP \(bu
+row number of starting point of baseline
+.IP \(bu
+height of characters, in pixels
+.IP \(bu
+angle of baseline in degrees elevated from the horizontal
+.IP \(bu
+text
+
+.sp
+Note that if your text contains white space, you'll have to use double
+quotes to cause it to be a single token.
+
+.TP
+text_here
+This is like \fBtext\fP, except that the baseline starts at
+the current position and the command updates the current position to the
+other end of the baseline after it draws.
+.sp
+Bear in mind that a script starts with the current position in the
+top line, so if you leave it there, only the bottom line of your text
+will be within the image!
+
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmdraw\fP was new in Netpbm 10.29 (August 2005).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmlabel" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+.BR "libnetpbm_draw" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmdraw.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmfade.1 b/upstream/mageia-cauldron/man1/ppmfade.1
new file mode 100644
index 00000000..70f73f73
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmfade.1
@@ -0,0 +1,158 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmfade User Manual" 0 "01 April 2000" "netpbm documentation"
+
+.SH NAME
+ppmfade - generate a transition between two image files using special effects
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmfade\fP
+[\fB-f\fP \fIfirst.ppm\fP]
+[\fB-l\fP \fIlast.ppm\fP]
+[\fB-mix\fP|\fB-spread\fP|\fB-shift\fP|
+\fB-relief\fP|\fB-oil\fP|\fB-edge\fP|\fB-bentley\fP|\fB-block\fP]
+[\fB-base\fP \fIname\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmfade\fPgenerates a transition between either two input
+images or between one input image and black.  You can use the 30
+intermediate images generated to show a smooth transition between
+segments of a movie.  The input and output images are in the PPM
+format.  If you specify both input images, they should both be the
+same size.  If you want to fade from black to an image, specify only
+the last image.  If you want to fade from an image to black, specify
+only the first image.  \fBppmfade\fP names the resulting image files
+\fIbase\fP\fB.\fP\fInnnn\fP\fB.ppm\fP, where \fInnnn\fP is a
+number varying between 0001 and 0030 and \fIbase\fP is what you
+specify with via the \fB-base\fP option (default \fBfade\fP).
+.PP
+Another way to convert by steps from one image to another is
+morphing.  You can use \fBxmorph\fP to do that.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmfade\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-f\fP \fIfirst.ppm\fP
+This is the image file (PPM format) to be used at the beginning of the
+transition.  If you don't specify this, the fade will start from black.
+
+.TP
+\fB-l\fP \fIlast.ppm\fP
+This is the image file (PPM format) to be used at the ending of the
+transition.  If you don't specify this, the fade will end with black.
+
+.TP
+\fB-mix\fP
+The two images are superimposed with the brightness of the first image
+decreasing from full to none and the brightness of the final image
+increasing from none to full.  The transition is quadratic in brightness
+with faster transition in the beginning and slower at the end.
+
+.TP
+\fB-spread\fP
+The pixels in the first image will be moved (spread) further and further
+from their original location and then moved into the proper location in
+the final image.  This is the default transition.
+
+.TP
+\fB-shift\fP
+The pixels in the first image will be shifted further and further horizontally
+from their original location and then moved into the proper location in
+the final image.
+
+.TP
+\fB-relief\fP
+The first image is faded to a Laplacian relief filtered version of the
+first image.  This is then faded to a Laplacian relief filtered version
+of the second image and finally faded to the final image.
+
+.TP
+\fB-oil\fP
+The first image is faded to an "oil transfer" version
+of the first image.  This is then faded to an "oil transfer"
+version of the second image and finally faded to the final image.
+
+.TP
+\fB-edge\fP
+The first image is faded to an edge detected version of the first image.
+This is then faded to an edge detected version of the second image and
+finally faded to the final image.
+
+.TP
+\fB-bentley\fP
+ The first image is faded to a "Bentley Effect" version
+of the first image.  This is then faded to a "Bentley
+Effect" version of the second image and finally faded to the
+final image.
+
+.TP
+\fB-block\fP
+The first image is defocused to small blocks.  The small blocks are converted
+to match a defocused version of the last image.  The block version of the last
+image is then focused to the final image.
+
+.TP
+\fB-base\fP \fIname\fP
+This forms part of the output filenames, as described above.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+\fBppmfade -f teapot.ppm -l pyr.ppm\fP
+.PP
+Fade from teapot.ppm to pyr.ppm generating fade.0001.ppm to fade.0030.ppm using
+the "spread" transition.
+.PP
+\fBppmfade -l teapot.ppm\fP
+.PP
+Fade from black to teapot.ppm generating fade.0001.ppm to fade.0030.ppm.
+.PP
+\fBppmfade -f teapot.ppm -base end\fP
+.PP
+Fade from teapot.ppm to black generating end.0001.ppm to end.0030.ppm.
+
+.UN seealso
+.SH SEE ALSO
+
+\fBtontsc\fP manual,
+\fBsgifade\fP manual,
+\fBsmart_vfr\fP manual,
+\fBxmorph\fP manual,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+Bryan Henderson, Olympia WA; April 2000
+.PP
+Inspired by and intended as a replacement for \fBpbmfade\fP (not a
+Netpbm program) by Wesley C. Barris.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmfade.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmflash.1 b/upstream/mageia-cauldron/man1/ppmflash.1
new file mode 100644
index 00000000..cb57d9ac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmflash.1
@@ -0,0 +1,79 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmflash User Manual" 0 "26 January 2003" "netpbm documentation"
+
+.SH NAME
+ppmflash - brighten a picture to approach white
+
+.UN synopsis
+.SH SYNOPSIS
+
+ppmflash 
+\fIflashfactor\fP
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmflash\fP reads a PPM image as input.  It changes the color of
+each pixel to bring it a specified amount closer to white.  It
+generates a PPM image of the result.
+.PP
+\fIflashfactor\fP is a real number between 0 and 1, inclusive.
+\fBppmflash\fP increases the intensity of each RGB component by the
+fraction \fIflashfactor\fP of the difference between the current
+value and full intensity.  So if a pixel contains 60% full red, 10%
+full green, and no blue and you specify 0.5 (half), \fBppmflash\fP
+increases the red to 80% (because it was 40% from full intensity, so
+it adds half of 40% to the original 60%), the green to 55%, and the
+blue to 50%.
+.PP
+If \fIflashfactor\fP is zero, the output is identical to the input.
+If \fIflashfactor\fP is one, the output is all white.
+.PP
+\fBpambrighten\fP does a more normal kind of brightening.
+\fBpamfunc\fP does a very simple brightening.  Both
+\fBpambrighten\fP and \fBpamfunc\fP can reduce brightness as well.
+.PP
+\fBpnmgamma\fP is another way people do a similar brightening, though
+it isn't really intended for that.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmflash\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pambrighten" (1)\c
+\&
+.BR "pamfunc" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmflash.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmforge.1 b/upstream/mageia-cauldron/man1/ppmforge.1
new file mode 100644
index 00000000..d9656c67
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmforge.1
@@ -0,0 +1,392 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmforge User Manual" 0 "27 March 2021" "netpbm documentation"
+
+.SH NAME
+
+ppmforge - fractal forgeries of clouds, planets, and starry skies
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmforge\fP
+
+[\fB-clouds\fP]
+[\fB-night\fP]
+[\fB-dimension\fP \fIdimen\fP]
+[\fB-hour\fP \fIhour\fP]
+[\fB-inclination|-tilt\fP \fIangle\fP]
+[\fB-mesh\fP \fIsize\fP]
+[\fB-power\fP \fIfactor\fP]
+[\fB-glaciers\fP \fIlevel\fP]
+[\fB-ice\fP \fIlevel\fP]
+[\fB-saturation\fP \fIsat\fP]
+[\fB-seed\fP \fIseed\fP]
+[\fB-stars\fP \fIfraction\fP]
+[{\fB-xsize\fP|\fB-width\fP} \fIwidth\fP]
+[{\fB-ysize\fP|\fB-height\fP} \fIheight\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmforge\fP generates three kinds of ``random fractal forgeries,''
+the term coined by Richard F. Voss of the IBM Thomas J. Watson
+Research Center for seemingly realistic pictures of natural objects
+generated by simple algorithms embodying randomness and fractal
+self-similarity.  The techniques used by \fBppmforge\fP are
+essentially those given by Voss[1], particularly the technique of
+spectral synthesis explained in more detail by Dietmar Saupe[2].
+.PP
+The program generates two varieties of pictures: planets and
+clouds, which are just different renderings of data generated in an
+identical manner, illustrating the unity of the fractal structure of
+these very different objects.  A third type of picture, a starry sky,
+is synthesised directly from pseudorandom numbers.
+.PP
+The generation of planets or clouds begins with the preparation of
+an array of random data in the frequency domain.  The size of this
+array, the ``mesh size,'' can be set with the \fB-mesh\fP option; the
+larger the mesh the more realistic the pictures but the calculation
+time and memory requirement increases as the square of the mesh size.
+The fractal dimension, which you can specify with the
+\fB-dimension\fP option, determines the roughness of the terrain on
+the planet or the scale of detail in the clouds.  As the fractal
+dimension is increased, more high frequency components are added into
+the random mesh.
+.PP
+Once the mesh is generated, an inverse two dimensional Fourier
+transform is performed upon it.  This converts the original random
+frequency domain data into spatial amplitudes.  We scale the real
+components that result from the Fourier transform into numbers from 0
+to 1 associated with each point on the mesh.  You can further modify
+this number by applying a ``power law scale'' to it with the
+\fB-power\fP option.  Unity scale leaves the numbers unmodified; a
+power scale of 0.5 takes the square root of the numbers in the mesh,
+while a power scale of 3 replaces the numbers in the mesh with their
+cubes.  Power law scaling is best envisioned by thinking of the data
+as representing the elevation of terrain; powers less than 1 yield
+landscapes with vertical scarps that look like glacially-carved
+valleys; powers greater than one make fairy-castle spires (which
+require large mesh sizes and high resolution for best results).
+.PP
+After these calculations, we have a array of the specified size
+containing numbers that range from 0 to 1.  \fBppmforge\fP generates
+as follows:
+.PP
+The randomness in the image is limited before Netpbm 10.37 (December
+2006) -- if you run the program twice in the same second, you may get
+identical output.
+
+
+.TP
+\fBClouds\fP
+A color map is created that ranges from pure blue to white by
+increasing admixture (desaturation) of blue with white.  Numbers less
+than 0.5 are colored blue, numbers between 0.5 and 1.0 are colored
+with corresponding levels of white, with 1.0 being pure white.
+
+.TP
+\fBPlanet\fP
+The mesh is projected onto a sphere.  Values less than 0.5 are treated
+as water and values between 0.5 and 1.0 as land.  The water areas are
+colored based upon the water depth, and land based on its elevation.
+The random depth data are used to create clouds over the oceans.  An
+atmosphere approximately like the Earth's is simulated; its light
+absorption is calculated to create a blue cast around the limb of the
+planet.  A function that rises from 0 to 1 based on latitude is
+modulated by the local elevation to generate polar ice caps--high
+altitude terrain carries glaciers farther from the pole.  Based on the
+position of the star with respect to the observer, the apparent color
+of each pixel of the planet is calculated by ray-tracing from the star
+to the planet to the observer and applying a lighting model that sums
+ambient light and diffuse reflection (for most planets ambient light
+is zero, as their primary star is the only source of illumination).
+Additional random data are used to generate stars around the planet.
+
+.TP
+\fBNight\fP
+A sequence of pseudorandom numbers is used to generate stars with a
+user specified density.
+
+.PP
+Cloud pictures always contain 256 or fewer colors and may be
+displayed on most color mapped devices without further processing.
+Planet pictures often contain tens of thousands of colors which must
+be compressed with \fBpnmquant\fP or \fBppmdither\fP before encoding
+in a color mapped format.  If the display resolution is high enough,
+\fBppmdither\fP generally produces better looking planets.
+\fBpnmquant\fP tends to create discrete color bands, particularly in
+the oceans, which are unrealistic and distracting.  The number of
+colors in starry sky pictures generated with the \fB-night\fP option
+depends on the value specified for \fB-saturation\fP.  Small values
+limit the color temperature distribution of the stars and reduce the
+number of colors in the image.  If the \fB-saturation\fP is set to
+0, none of the stars will be colored and the resulting image will
+never contain more than 256 colors.  Night sky pictures with many
+different star colors often look best when color compressed by
+\fBpamdepth\fP rather than \fBpnmquant\fP or \fBppmdither\fP.  Try
+\fInewmaxval\fP settings of 63, 31, or 15 with \fBpamdepth\fP to
+reduce the number of colors in the picture to 256 or fewer.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmforge\fP recognizes the following
+command line options:
+.PP
+You can abbreviate any options to its shortest unique prefix.
+
+
+.TP
+\fB-clouds\fP
+Generate clouds.  An image of fractal clouds is generated.  Selecting clouds
+sets the default for fractal dimension to 2.15 and power scale factor
+to 0.75.
+
+.TP
+\fB-dimension\fP \fIdimen\fP
+ Sets the fractal dimension to the specified \fIdimen\fP, which may be
+any real number between 0 and 5 inclusive.  Higher fractal dimensions create
+more ``chaotic'' images, which require higher resolution output and a larger
+FFT mesh size to look good.  If no dimension is specified, the program uses
+2.4 when generating planets and 2.15 for clouds.
+
+.TP
+\fB-glaciers\fP \fIlevel\fP
+The floating point \fIlevel\fP setting controls the extent to
+which terrain elevation causes ice to appear at lower latitudes.  The
+default value of 0.75 makes the polar caps extend toward the equator
+across high terrain and forms glaciers in the highest mountains, as on
+Earth.  Higher values make ice sheets that cover more and more of the
+land surface, simulating planets in the midst of an ice age.  Lower
+values tend to be boring, resulting in unrealistic
+geometrically-precise ice cap boundaries.
+
+.TP
+\fB-hour\fP \fIhour\fP
+When generating a planet, \fBppmforge\fP uses \fIhour\fP as the
+"hour angle at the central meridian."  If you specify \fB-hour
+12\fP, for example, the planet will be fully illuminated,
+corresponding to high noon at the longitude at the center of the
+screen.  You can specify any floating point value between 0 and 24 for
+\fIhour\fP, but values which place most of the planet in darkness (0
+to 4 and 20 to 24) result in crescents which, while pretty, don't give
+you many illuminated pixels for the amount of computing that's
+required.  If no \fB-hour\fP option is specified, a random hour angle
+is chosen, biased so that only 25% of the images generated will be
+crescents.
+
+.TP
+\fB-ice\fP \fIlevel\fP
+Sets the extent of the polar ice caps to the given floating point
+\fIlevel\fP.  The default level of 0.4 produces ice caps similar to
+those of the Earth.  Smaller values reduce the amount of ice, while
+larger \fB-ice\fP settings create more prominent ice caps.
+Sufficiently large values, such as 100 or more, in conjunction with
+small settings for \fB-glaciers\fP (try 0.1) create "ice
+balls" like Europa.
+
+.TP
+\fB-inclination|-tilt\fP \fIangle\fP
+The inclination angle of the planet with regard to its primary
+star is set to \fIangle\fP, which can be any floating point value
+from -90 to 90.  The inclination angle can be thought of as
+specifying, in degrees, the ``season'' the planet is currently
+experiencing or, more precisely, the latitude at which the star
+transits the zenith at local noon.  If 0, the planet is at equinox;
+the star is directly overhead at the equator.  Positive values
+represent summer in the northern hemisphere, negative values summer in
+the southern hemisphere.  The Earth's inclination angle, for example,
+is about 23.5 at the June solstice, 0 at the equinoxes in March and
+September, and -23.5 at the December solstice.  If no inclination
+angle is specified, a random value between -21.6 and 21.6 degrees is
+chosen.
+
+.TP
+\fB-mesh\fP \fIsize\fP
+A mesh of \fIsize\fP by \fIsize\fP will be used for the fast
+Fourier transform (FFT).  Note that memory requirements and
+computation speed increase as the square of \fIsize\fP; if you double
+the mesh size, the program will use four times the memory and run four
+times as long.  The default mesh is 256x256, which produces reasonably
+good looking pictures while using half a megabyte for the 256x256
+array of single precision complex numbers required by the FFT.  On
+machines with limited memory capacity, you may have to reduce the mesh
+size to avoid running out of RAM.  Increasing the mesh size produces
+better looking pictures; the difference becomes particularly
+noticeable when generating high resolution images with relatively high
+fractal dimensions (between 2.2 and 3).
+
+.TP
+\fB-night\fP
+A starry sky is generated.  The stars are created by the same
+algorithm used for the stars that surround planet pictures, but the
+output consists exclusively of stars.
+
+.TP
+\fB-power\fP \fIfactor\fP
+Sets the "power factor" used to scale elevations
+synthesised from the FFT to \fIfactor\fP, which can be any floating
+point number greater than zero.  If no factor is specified a default
+of 1.2 is used if a planet is being generated, or 0.75 if clouds are
+selected by the \fB-clouds\fP option.  The result of the FFT image
+synthesis is an array of elevation values between 0 and 1.  A
+non-unity power factor exponentiates each of these elevations to the
+specified power.  For example, a power factor of 2 squares each value,
+while a power factor of 0.5 replaces each with its square root.  (Note
+that exponentiating values between 0 and 1 yields values that remain
+within that range.)  Power factors less than 1 emphasise large-scale
+elevation changes at the expense of small variations.  Power factors
+greater than 1 increase the roughness of the terrain and, like high
+fractal dimensions, may require a larger FFT mesh size and/or higher
+screen resolution to look good.
+
+.TP
+\fB-saturation\fP \fIsat\fP
+Controls the degree of color saturation of the stars that surround
+planet pictures and fill starry skies created with the \fB-night\fP
+option.  The default value of 125 creates stars which resemble the sky
+as seen by the human eye from Earth's surface.  Stars are dim; only
+the brightest activate the cones in the human retina, causing color to
+be perceived.  Higher values of \fIsat\fP approximate the appearance
+of stars from Earth orbit, where better dark adaptation, absence of
+skyglow, and the concentration of light from a given star onto a
+smaller area of the retina thanks to the lack of atmospheric
+turbulence enhances the perception of color.  Values greater than 250
+create ``science fiction'' skies that, while pretty, don't occur in
+this universe.
+.sp
+Thanks to the inverse square law combined with Nature's love of
+mediocrity, there are many, many dim stars for every bright one.  This
+population relationship is accurately reflected in the skies created
+by \fBppmforge\fP.  Dim, low mass stars live much longer than bright
+massive stars, consequently there are many reddish stars for every
+blue giant.  This relationship is preserved by \fBppmforge\fP.  You
+can reverse the proportion, simulating the sky as seen in a starburst
+galaxy, by specifying a negative \fIsat\fP value.
+
+.TP
+\fB-seed\fP \fInum\fP
+Sets the seed for the random number generator to the integer
+\fInum\fP.  The seed used to create each picture is displayed on
+standard output (unless suppressed with the \fB-quiet\fP option).
+Pictures generated with the same seed will be identical.  If no
+\fB-seed\fP is specified, a random seed derived from the date and
+time will be chosen.  Specifying an explicit seed allows you to
+re-render a picture you particularly like at a higher resolution or
+with different viewing parameters.
+
+.TP
+\fB-stars\fP \fIfraction\fP
+Specifies the percentage of pixels, in tenths of a percent, which
+will appear as stars, either surrounding a planet or filling the
+entire frame if \fB-night\fP is specified.  The default
+\fIfraction\fP is 100.
+
+.TP
+\fB-xsize|-width\fP\fI width\fP
+Sets the width of the generated image to \fIwidth\fP pixels.  The
+default width is 256 pixels.  Images must be at least as wide as they
+are high; if a width less than the height is specified, it will be
+increased to equal the height.  If you must have a long skinny image,
+make a square one with \fBppmforge\fP, then use \fBpamcut\fP to
+extract a portion of the shape and size you require.
+
+.TP
+\fB-ysize|-height\fP \fIheight\fP
+Sets the height of the generated image to \fIheight\fP pixels.
+The default height is 256 pixels.  If the height specified exceeds the
+width, the width will be increased to equal the height.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The algorithms require the output image to be at least as wide as
+it is high, and the width to be an even number of pixels.  These
+constraints are enforced by increasing the size of the requested
+image if necessary.
+.PP
+You may have to reduce the FFT mesh size on machines with 16 bit
+integers and segmented pointer architectures.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcut" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+
+.TP
+[1] 
+Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw
+et. al., Fundamental Algorithms for Computer Graphics, Berlin:
+Springer-Verlag, 1985.
+
+.TP
+[2]
+Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images,
+New York: Springer Verlag, 1988.
+
+
+
+.UN author
+.SH AUTHOR
+
+.nf
+John Walker
+Autodesk SA
+Avenue des Champs-Montants 14b
+CH-2074 MARIN
+Suisse/Schweiz/Svizzera/Svizra/Switzerland
+    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
+    \fBFax:\fP038/33 88 15
+    \fBVoice:\fP038/33 76 33
+
+.fi
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided ``as
+is'' without express or implied warranty.
+
+.SS PLUGWARE!
+
+If you like this kind of stuff, you may also enjoy ``James Gleick's
+Chaos--The Software'' for MS-DOS, available for $59.95 from your
+local software store or directly from Autodesk, Inc., Attn: Science
+Series, 2320 Marinship Way, Sausalito, CA 94965, USA.  Telephone:
+(800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext
+4886.  Fax: (415) 289-4718.  ``Chaos--The Software'' includes a more
+comprehensive fractal forgery generator which creates
+three-dimensional landscapes as well as clouds and planets, plus five
+more modules which explore other aspects of Chaos.  The user guide of
+more than 200 pages includes an introduction by James Gleick and
+detailed explanations by Rudy Rucker of the mathematics and algorithms
+used by each program.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmforge.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmglobe.1 b/upstream/mageia-cauldron/man1/ppmglobe.1
new file mode 100644
index 00000000..5d396323
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmglobe.1
@@ -0,0 +1,161 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmglobe User Manual" 0 "23 February 2006" "netpbm documentation"
+
+.SH NAME
+ppmglobe - generate strips to glue onto a sphere
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmglobe\fP
+[\fB-background=\fP\fIcolorname\fP]
+[\fB-closeok\fP]
+\fIstripcount\fP
+[\fIfilename\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmglobe\fP does the inverse of a cylindrical projection of a
+sphere.  Starting with a cylindrical projection, it produces an image
+you can cut up and glue onto a sphere to obtain the spherical image of
+which it is the cylindrical projection.
+.PP
+What is a cylindrical projection?  Imagine a map of the Earth on flat
+paper.  There are lots of different ways cartographers show the three
+dimensional information in such a two dimensional map.  The cylindrical
+projection is one.  You could make a cylindrical projection by tracing as
+folows: wrap a rectangular sheet of paper around the globe, touching the globe
+at the Equator.  For each point of color on the globe, run a horizontal line
+from the axis of the globe through that point and out to the paper.  Mark the
+same color on the paper there.  Lay the paper out flat and you have a
+cylindrical projection.
+.PP
+Here's where \fBppmglobe\fP comes in:  Pass the image on that paper
+through \fBppmglobe\fP and what comes out the other side looks something
+like this:
+.PP
+.B Example of map of the earth run through ppmglobe
+.IMG -C globe.jpg
+.PP
+You could cut out the strips and glue it onto a sphere and you'd
+have a copy of the original globe.
+.PP
+Note that cylindrical projections are not what you normally see as
+maps of the Earth.  You're more likely to see a Mercator projection.
+In the Mercator projection, the Earth gets stretched North-South as
+well as East-West as you move away from the Equator.  It was invented
+for use in navigation, because you can draw straight compass courses
+on it, but is used today because it is pretty.
+.PP
+You can find maps of planets at 
+.UR http://maps.jpl.nasa.gov
+maps.jpl.nasa.gov
+.UE
+\&.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+\fIstripcount\fP is the number of strips \fBppmglobe\fP is to
+generate in the output.  More strips makes it easier to fit onto a
+sphere (less stretching, tearing, and crumpling of paper), but makes
+you do more cutting out of the strips.
+.PP
+The strips are all the same width.  If the number of columns of
+pixels in the image doesn't evenly divide by the number of strips,
+\fBppmglobe\fP truncates the image on the right to create nothing but
+whole strips.  In the pathological case that there are fewer columns
+of pixels than the number of strips you asked for, \fBppmglobe\fP
+fails.
+.PP
+Before Netpbm 10.32 (February 2006), instead of truncating the image
+on the right, \fBppmglobe\fP produces a fractional strip on the right.
+.PP
+\fIfilename\fP is the name of the input file.  If you don't
+specify this, \fBppmglobe\fP reads the image from Standard Input.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmglobe\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-background=\fP\fIcolorname\fP
+This specifies the color that goes between the strips.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+The default is black.
+.sp
+This option was new in Netpbm 10.31 (December 2005).  Before that,
+the background is always black.
+
+.TP
+\fB-closeok\fP
+This means it is OK if the background isn't exactly the color you specify.
+Sometimes, it is impossible to represent a named color exactly because of the
+precision (i.e. maxval) of the image's color space.  If you specify
+\fB-closeok\fP and \fBppmglobe\fP can't represent the color you name
+exactly, it will use instead the closest color to it that is possible.
+If you don't specify \fBcloseok\fP, \fBppmglobe\fP fails in that
+situation.
+.sp
+This option was new in Netpbm 10.31 (December 2005).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+.BR "pnmmercator" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmglobe\fP was new in Netpbm 10.16 (June 2003).
+.PP
+It is derived from Max Gensthaler's \fBppmglobemap\fP.
+
+.UN authors
+.SH AUTHORS
+.PP
+\fIMax Gensthaler\fP
+wrote a program he called
+\fBppmglobemap\fP in June 2003 and suggested it for inclusion in
+Netpbm.  Bryan Henderson modified the code slightly and included it in
+Netpbm as \fBppmglobe\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmglobe.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmhist.1 b/upstream/mageia-cauldron/man1/ppmhist.1
new file mode 100644
index 00000000..798db970
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmhist.1
@@ -0,0 +1,217 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmhist User Manual" 0 "24 August 2019" "netpbm documentation"
+
+.SH NAME
+ppmhist - print a histogram of the colors in a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmhist\fP
+[\fB-hexcolor\fP | \fB-float\fP | \fB-colorname\fP | \fB-map\fP]
+[\fB-nomap\fP]
+[\fB-noheader\fP]
+[\fB-sort=\fP{\fBfrequency\fP,\fBrgb\fP}]
+[\fB-forensic\fP]
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmhist\fP reads a PPM image as input and generates a histogram
+of the colors in the image, i.e. a list of all the colors and how many
+pixels of each color are in the image.
+
+.UN output
+.SS Output Format
+.PP
+The output is in one of two basic formats:  a report for humans
+and a PPM image for use by programs.  The PPM image is actually quite
+readable by humans too.
+
+.B Human Report
+.PP
+You get this format by specifying (or defaulting to) the
+\fB-nomap\fP option.
+.PP
+The format is one line for each color in the input image.
+.PP
+By default, there are two lines of column header and a summary at the top.
+Use the \fB-noheader\fP option to suppress those lines.
+.PP
+The summary tells you whether black or white are present and how many
+shades of gray and color are present.  The summary was new in Netpbm 10.82
+(March 2018).
+  
+.PP
+In each line, \fBppmhist\fP identifies the color by red, green,
+and blue components.  By default, it lists each of these in decimal,
+using the exact values that are in the PPM input.  So if the image has
+a maxval of 255, the numbers in the listing range from 0 to 255.  With
+the \fB-hexcolor\fP option, you can change these numbers to
+hexadecimal.  With the \fB-float\fP option, the numbers are
+fractional, adjusted to a maxval of 1.
+.PP
+Each line lists the luminosity of the color.  It is in decimal
+on the same scale as the rgb values (see above).
+.PP
+Each line lists the number of pixels in the image that have the color.
+This is in decimal.
+
+
+.B PPM Output
+.PP
+You get this format with the \fB-map\fP option.
+.PP
+The output file is a genuine PPM image, but it is PPM Plain format
+and contains comments so that it is not a lot different from the
+human report described above.
+.PP
+As a PPM image, it can be useful as input to other programs that
+need some kind of palette.  The image is a single row with one
+column for each distinct color in the image.
+.PP
+The function of PPM output is essentially the same as the output of
+\fBpnmcolormap all\fP.  \fBppmhist\fP is much older than \fBpnmcolormap\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmhist\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-sort=\fP{\fBfrequency\fP,\fBrgb\fP}
+The \fB-sort\fP option determines the order in which the colors are
+listed in the output.  \fBrgb\fP means to sort them first by the intensity of
+the red component of the color, then of the green, then of the blue, with the
+least intense first.  \fBfrequency\fP means to list them in order of how many
+pixels in the input image have the color, with the most represented colors
+first.  Among colors with the same frequency, the order is the same as with
+\fBrgb\fP.
+.sp
+The default is \fBfrequency\fP.
+.sp
+Before Netpbm 10.88 (September 2019), with \fB-sort=frequency\fP, the
+order of colors that have the same frequency is arbitrary.
+  
+.TP
+\fB-hexcolor\fP
+Print the color components in hexadecimal.  See 
+.UR #output
+output format
+.UE
+\&.
+.sp
+You may not specify this option along with \fB-float\fP or \fBmap\fP.
+
+.TP
+\fB-float\fP
+Print the color components and the luminosity as floating point
+numbers in the range [0,1].  See 
+.UR #output
+output format
+.UE
+\&.
+.sp
+You may not specify this option along with \fB-hexcolor\fP or \fBmap\fP.
+.sp
+This option was added in Netpbm 10.19 (November 2003).
+
+.TP
+\fB-map\fP
+Generates a PPM file of the colormap for the image, with the
+color histogram as comments.  See 
+.UR #output
+output format
+.UE
+\&.
+.sp
+You may not specify this option along with \fB-float\fP or \fBhexcolor\fP.
+
+.TP
+\fB-nomap\fP
+Generates the histogram for human reading.  This is the default.
+
+.TP
+\fB-colorname\fP
+Add the color name to the output.  This is the name from the 
+.UR libppm.html#dictionary
+system color dictionary
+.UE
+\&.  If the exact
+color is not in the color dictionary, it is the closest color that is
+in the dictionary and is preceded by a '*'.  If you don't have a 
+system color dictionary, the program fails.
+.sp
+This option was added in Netpbm 10.10 (October 2002).
+
+.TP
+\fB-noheader\fP
+Do not print the column headings.
+
+.TP
+\fB-forensic\fP
+.sp
+With this option, \fBppmhist\fP works on images that contain invalid sample
+values.  Normally, like most Netpbm programs, \fBppmhist\fP fails if it
+encounters a sample value greater than the maxval that the image declares.  The
+presence of such a value means the image is invalid, so the pixels have no
+meaning.  But with \fB-forensic\fP, \fBppmhist\fP produces a histogram
+of the actual sample values without regard to maxval.  It issues messages
+summarizing the invalid pixels if there are any.
+.sp
+One use for this is to diagnose the problem that caused the invalid Netpbm
+image to exist.
+.sp
+There is a small exception to the ability of \fBppmhist\fP to process
+invalid pixels even with \fB-forensic\fP: it can never process a sample value
+greater than 65535.  Note that in the rarely used Plain PPM format, it is
+possible for a number greater than that to appear where a sample value
+belongs.
+.sp
+This option was new in Netpbm 10.66 (March 2014).  But Netpbm older than
+10.66 does not properly reject invalid sample values, so the effect is very
+similar to \fB-forensic\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&,
+.BR "pgmhist" (1)\c
+\&,
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pnmhistmap" (1)\c
+\&,
+.BR "ppmchange" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmhist.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmlabel.1 b/upstream/mageia-cauldron/man1/ppmlabel.1
new file mode 100644
index 00000000..51e54d69
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmlabel.1
@@ -0,0 +1,214 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmlabel User Manual" 0 "15 April 2006" "netpbm documentation"
+
+.SH NAME
+ppmlabel - add text to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmlabel\fP
+
+[\fB-angle\fP \fIangle\fP]
+
+[\fB-background\fP { \fBtransparent\fP | \fIcolor\fP } ]
+
+[\fB-color\fP \fIcolor\fP]
+
+[\fB-file\fP \fIfilename\fP]
+
+[\fB-size\fP
+
+\fItextsize\fP]
+
+[\fB-text\fP \fItext_string\fP]
+
+[\fB-x\fP \fIcolumn\fP]
+
+[\fB-y\fP \fIrow\fP]
+
+\&...
+
+[\fIppmfile\fP]
+
+
+.UN example
+.SH EXAMPLE
+
+.nf
+\f(CW
+    ppmlabel -x 50 -y 50 -text hello \e
+             -angle -30 -text there \e
+             testimg.ppm 
+\fP
+
+.fi
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmlabel\fP uses the text drawing facilities of \fBlibnetpbm\fP's
+"ppmd" component to add text to a PBM image.  You control
+the location, size, baseline angle, color of the text, and background
+color (if any) with command line arguments.  You can specify the text
+on the command line or supply it in files.
+.PP
+You can add any number of separate labels in a single invocation of
+\fBppmlabel\fP, limited only by any restrictions your environment has
+on the number and size of program arguments (e.g. a shell's command 
+size limit).
+.PP
+If you don't specify \fIppmfile\fP, \fBppmlabel\fP reads its input
+PPM image from Standard Input.
+.PP
+The output image goes to Standard Output.
+.PP
+A more sophisticated way to add a label to an image is to use
+\fBpbmtext\fP or \fBpbmtextps\fP to create an image of the text, then
+\fBpamcomp\fP to overlay it onto the base image.
+.PP
+Another more general program is \fBppmdraw\fP.  It is slightly harder
+to use for simple labelling.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmlabel\fP recognizes the following
+command line options:
+.PP
+The arguments on the \fBppmlabel\fP command line are not options in
+the strict sense; they are commands which control the placement and
+appearance of the text being added to the input image.  They are
+executed left to right, and any number of arguments may appear.
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB-angle\fP\fI angle\fP
+This option sets the angle of the baseline of subsequent text.
+\fIangle\fP is an integral number of degrees, measured
+counterclockwise from the row axis of the image.
+
+.TP
+\fB-background\fP { \fBtransparent\fP | \fIcolor\fP }
+If the argument is \fBtransparent\fP, \fBppmlabel\fP draws the
+text over the existing pixels in the image.  If you specify a
+\fIcolor\fP (see the \fB-color\fP option below for information on
+how to specify colors), \fBppmlabel\fP generates background rectangles
+enclosing subsequent text, and those rectangles are filled with that
+color.
+
+.TP
+\fB-color\fP \fIcolor\fP
+This option sets the color for subsequent text.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+\fB-colour\fP is an acceptable alternate spelling.
+
+.TP
+\fB-file\fP \fIfilename\fP
+This option causes \fBppmlabel\fP to read lines of text from the file
+named \fIfilename\fP and draw it on successive lines.
+
+.TP
+\fB-size\fP \fItextsize\fP
+This option sets the height of the tallest characters above the
+baseline to \fItextsize\fP pixels.
+
+.TP
+\fB-text\fP \fItext_string\fP
+This option causes \fBppmlabel\fP to draw the specified text
+string.  It advances the location for subsequent text down 1.75 times
+the current \fItextsize\fP.  That lets you draw multiple lines of
+text in a reasonable manner without specifying the position of each
+line.
+.sp
+Note that if you invoke \fBppmlabel\fP via a shell command and your
+text string contains spaces, you'll have to quote it so the shell treats
+the whole string as a single token.  E.g.
+.nf
+  $ ppmlabel -text "this is my text" baseimage.ppm >annotatedimage.ppm
+
+.fi
+
+
+.TP
+\fB-x\fP \fIcolumn\fP
+This option sets the pixel column at which subsequent text will
+be left justified.  Depending on the shape of the first character, the
+actual text may begin a few pixels to the right of this point.
+
+.TP
+\fB-y\fP \fIrow\fP
+This option sets the pixel row which will form the baseline of
+subsequent text.  Characters with descenders, such as "y," will extend
+below this line.  
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+Text strings are restricted to 7 bit ASCII.  The text font used by
+\fBppmlabel\fP doesn't include definitions for 8 bit ISO 8859/1 characters.
+.PP
+When drawing multiple lines of text with a non-transparent
+background, it should probably fill the space between the lines with
+the background color.  This is tricky to get right when the text is
+rotated to a non-orthogonal angle.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmmake" (1)\c
+\&,
+.BR "ppmdraw" (1)\c
+\&,
+.BR "pbmtext" (1)\c
+\&,
+.BR "pbmtextps" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995 by John Walker (\fIkelvin@fourmilab.ch\fP)
+WWW home page: 
+.UR http://www.fourmilab.ch/
+http://www.fourmilab.ch/
+.UE
+\&
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided
+``as is'' without express or implied warranty.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmlabel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmmake.1 b/upstream/mageia-cauldron/man1/ppmmake.1
new file mode 100644
index 00000000..5521ea0d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmmake.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmmake User Manual" 0 "02 September 2002" "netpbm documentation"
+
+.SH NAME
+ppmmake - create a PPM image of a specified color and dimensions
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmmake\fP
+[\fB-maxval=\fP\fImaxval\fP]
+\fIcolor\fP
+\fIwidth\fP
+\fIheight\fP
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmmake\fP produces a PPM image of the specified color, width,
+height, and maxval.
+.PP
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+
+.UN example
+.SH EXAMPLES
+
+.nf
+    ppmmake red 50 50
+
+.fi
+.nf
+    ppmmake rgb:ff/80/80 50 100 -maxval=5
+
+.fi
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmmake\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-maxval=\fP\fImaxval\fP
+     The maxval for the generated image.  Default is 255.
+.sp
+     This option did not exist before June 2002.  Before, the maxval was
+     always 255.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmmake" (1)\c
+\&,
+.BR "pgmmake" (1)\c
+\&,
+.BR "ppmpat" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmmake.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmmix.1 b/upstream/mageia-cauldron/man1/ppmmix.1
new file mode 100644
index 00000000..23fc26f7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmmix.1
@@ -0,0 +1,79 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmmix User Manual" 0 "23 March 2010" "netpbm documentation"
+
+.SH NAME
+
+ppmmix - blend together two PPM images
+
+.UN synopsis
+.SH SYNOPSIS
+
+ppmmix \fIfadefactor\fP \fIppmfile1\fP \fIppmfile2\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmmix\fP reads two PPM images as input and mixes them together
+using the specified fade factor.  The fade factor may be in the range
+from 0.0 (only ppmfile1's image data) to 1.0 (only ppmfile2's image
+data).  Anything in between specifies a smooth blend between the two
+images.
+.PP
+The two images must have the same dimensions and the same maxval.  Before
+Netpbm 10.54 (March 2011), they must also have the same type (PBM/PGM/PPM).
+.PP
+The fade factor is applied to brightness, not light intensity.  That means
+for example that if you have a series of images you generated
+using \fBppmmix\fP of a black and a white image with a linearly increasing
+fade factor, you will see an image getting linearly brighter, but the light
+intensity will increase faster at the end.  That is because it requires more
+intensity change at the bright end of the scale than at the dark end for the
+human eye to perceive the same brightness change.  This also means that
+if the original images aren't all one color, the mixed image is distorted,
+since the intensity relationship between pixels is different from the
+original image.
+.PP
+\fBpamcomp\fP is a more general alternative.  It allows you to mix
+images of different size and to have the fade factor vary throughout
+the image (through the use of a transparency mask).  It does not have the
+same-maxval and same-type restrictions.  It mixes light intensity, not
+brightness.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmmix\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcomp" (1)\c
+\&,
+.BR "pammixmulti" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmmix.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmnorm.1 b/upstream/mageia-cauldron/man1/ppmnorm.1
new file mode 100644
index 00000000..8dc49c2a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmnorm.1
@@ -0,0 +1,29 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmnorm User Manual" 0 "March 2002" "netpbm documentation"
+
+.SH NAME
+
+ppmnorm - replaced by pnmnorm
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmnorm\fP was replaced in Netpbm 9.25 (March 2002) by
+.BR "pnmnorm" (1)\c
+\&.
+.PP
+\fBpnmnorm\fP is backward compatible with \fBppmnorm\fP except that
+for PBM and PGM input, it produced PBM and PGM output.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmnorm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmntsc.1 b/upstream/mageia-cauldron/man1/ppmntsc.1
new file mode 100644
index 00000000..04ce9fc1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmntsc.1
@@ -0,0 +1,122 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmntsc User Manual" 0 "19 April 2000" "netpbm documentation"
+
+.SH NAME
+
+ppmntsc - Make RGB colors legal for NTSC or PAL color systems.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmntsc\fP
+
+[\fB--pal\fP]
+[\fB--legalonly\fP]
+[\fB--illegalonly\fP]
+[\fB--correctedonly\fP]
+[\fB--verbose\fP]
+[\fB--debug\fP]
+[\fIinfile\fP]
+.PP
+Minimum unique abbreviations of options are acceptable.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program makes colors legal in the NTSC (or PAL) color systems.
+Often, images generated on the computer are made for use in movies
+which ultimately end up on a television screen.  However, the range of colors
+(as specified by their RGB values) on a computer does not match the
+range of colors that can be represented using the NTSC (or PAL)
+systems.  If an image with "illegal" colors is sent directly
+to an NTSC (or PAL) video system for recording, the
+"illegal" colors will be clipped.  This may result in an
+undesirable looking picture.
+.PP
+This utility tests each pixel in an image to see if it falls
+within the legal NTSC (or PAL) range.  If not, it raises or lowers the
+pixel's saturation in the output so that it does fall within legal
+limits.  Pixels that are already OK just go unmodified into the
+output.
+.PP
+Input is from the file named \fIinput\fP.  If \fIinput\fP is
+\fB-\fP, input is from Standard Input.  If you don't specify
+\fIinput\fP, input is from Standard Input.
+.PP
+Output is always to Standard Output.
+.PP
+This program handles multi-image PPM input, producing multi-image
+PPM output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmntsc\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB--pal\fP
+Use the PAL transform instead of the default NTSC.
+
+.TP
+\fB--verbose\fP
+Print a grand total of the number of illegal pixels.
+
+.TP
+\fB--debug\fP
+Produce a humongous listing of illegal colors and their legal counterparts.
+NOTE:  This option may produce a great deal of output.
+
+.TP
+\fB--legalonly\fP
+Output only pixels that are already legal.  Output black in place of pixels
+that are not.
+
+.TP
+\fB--illegalonly\fP
+Output only pixels that are illegal (and output them uncorrected).
+Output black in place of pixels that are already legal.
+
+.TP
+\fB--correctedonly\fP
+Output only pixels that are corrected versions of illegal pixels.  Output
+black in place of pixels that are already legal.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdim" (1)\c
+\&,
+.BR "pambrighten" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Wes Barris, Minnesota Supercomputer Center, Inc., Bryan Henderson
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmntsc.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmpat.1 b/upstream/mageia-cauldron/man1/ppmpat.1
new file mode 100644
index 00000000..ed7f0d99
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmpat.1
@@ -0,0 +1,235 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmpat User Manual" 0 "02 March 2016" "netpbm documentation"
+
+.SH NAME
+
+ppmpat - make a pretty PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmpat\fP
+[{\fB-gingham2\fP|\fB-g2\fP} |
+{\fB-gingham3\fP|\fB-g3\fP} |
+\fB-madras\fP |
+\fB-tartan\fP |
+\fB-poles\fP |
+\fB-squig\fP |
+\fB-camo\fP |
+\fB-anticamo\fP |
+\fB-argyle1\fP |
+\fB-argyle2\fP]
+[\fB-color\fP \fIcolorlist\fP]
+[\fB-mesh\fP]
+[\fB-randomseed\fP \fIinteger\fP]
+
+\fIwidth\fP \fIheight\fP
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmpat\fP produces a PPM of the specified width and height,
+with a pattern in it.
+.PP
+You could, for example, use it to create wallpaper for a computer screen.
+.PP
+One use of this program is as an example of the Netpbm library
+.BR "drawing" (1)\c
+\& functions, which it uses.
+.PP
+Some of the patterns have large numbers of colors, so if you want
+a simpler pattern, use \fBpnmquant\fP on the output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmpat\fP recognizes the following
+command line options:
+
+.UN patspec
+.SS Pattern Specification
+.PP
+Specify the pattern type with these options.  One pattern type must
+be specified.
+
+
+.TP
+\fB-gingham2\fP \fB-g2\fP
+A gingham check pattern.  Can be tiled.
+.sp
+If you specify -color, give two colors: background and foreground, in that
+order.
+
+.TP
+\fB-gingham3\fP \fB-g3\fP
+A slightly more complicated gingham.  Can be tiled.
+.sp
+If you specify -color, give three colors: background and two foregrounds,
+in that order.
+
+.TP
+\fB-madras\fP
+A madras plaid.  Can be tiled.
+.sp
+If you specify -color, give three colors: background and two foregrounds,
+in that order.
+
+.TP
+\fB-tartan\fP
+A tartan plaid.  Can be tiled.
+.sp
+If you specify -color, give three colors: background and two foregrounds,
+in that order.
+
+.TP
+\fB-poles\fP
+Color gradients centered on randomly-placed poles.
+.sp
+If you specify -color, give two or more colors.
+
+.TP
+\fB-squig\fP
+Squiggley tubular pattern.  Can be tiled.
+.sp
+If you specify -color, give three or more colors.  The first is the
+background color.
+
+.TP
+\fB-camo\fP
+Camouflage pattern.
+.sp
+If you specify \fB-color\fP, give three or more colors.  The first is the
+background color; the others are colors for the leafy foreground shapes.
+The foreground shapes will probably occupy nearly the entire image, so that the
+background color is barely visible.
+
+.TP
+\fB-anticamo\fP
+Anti-camouflage pattern - like -camo, but ultra-bright colors.
+.sp
+If you specify \fB-color\fP, this is the same as \fB-camo\fP.
+
+.TP
+\fB-argyle1\fP
+A diamond argyle pattern, without a cross through the diamond, with one
+diamond.  Can be tiled.
+.sp
+If you specify -color, give two colors: background and foreground, in that
+order.
+.sp
+This option was new in Netpbm 10.78 (March 2017).
+
+.TP
+\fB-argyle2\fP
+A diamond argyle pattern, with a cross through the diamond, with one
+diamond.  Can be tiled.
+.sp
+If you specify -color, give three colors: background, foreground, and
+stripe, in that order.
+.sp
+This option was new in Netpbm 10.78 (March 2017).
+
+
+
+.UN otheropts
+.SS Other Options
+
+
+
+.TP
+\fB-color\fP \fIcolorlist\fP
+This specifies the colors to appear in the pattern.
+.sp
+If you do not specify this option, \fBppmpat\fP chooses colors at random.
+.sp
+Different patterns take different numbers of colors.  Some can involve
+variable numbers of colors.  If you specify a number of colors incompatible
+with the pattern you specify, \fBppmpat\fP fails, telling you how many colors
+to specify.
+.sp
+\fIcolorlist\fP is a comma-separated list of colors.
+.sp
+Specify each color as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Example: \fB-color red, green, rgbi:1.0/0.5/.25\fP .
+.sp
+This option was new in Netpbm 10.78 (March 2017).
+
+.TP
+\fB-mesh\fP
+This option affects the patterns generated by the
+\fB-gingham2\fP, \fB-gingham3\fP, \fB-madras\fP, and \fB-tartan\fP.  When
+this option is \fInot\fP specified, when two colors intersect, the program
+mixes them and puts the average in the rectangular intersection region.
+with \fB-mesh\fP, the program fills that region with a checkerboard pattern
+consisting of the two colors.  The resulting image looks like a true woven
+fabric, with separate threads for the separate colors.
+.sp
+This option was new in Netpbm 10.97 (December 2021).
+
+  
+.TP
+\fB-randomseed\fP \fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+By default, \fBppmpat\fP uses a seed derived from the time of day
+and process ID, which gives you fairly uncorrelated results in multiple
+invocations.
+.sp
+This option was new in Netpbm 10.61 (December 2012).
+
+
+
+.UN references
+.SH REFERENCES
+
+Some of the patterns are from "Designer's Guide to Color 3"
+by Jeanne Allen.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtile" (1)\c
+\&, 
+.BR "pnmquant" (1)\c
+\&, 
+.BR "ppmmake" (1)\c
+\&, 
+.BR "ppmrainbow" (1)\c
+\&, 
+.BR "pamgradient" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmpat.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmquant.1 b/upstream/mageia-cauldron/man1/ppmquant.1
new file mode 100644
index 00000000..1694ac83
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmquant.1
@@ -0,0 +1,89 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmquant User Manual" 0 "22 October 2003" "netpbm documentation"
+
+.SH NAME
+
+ppmquant - quantize the colors in a PPM image down to a specified number
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmquant\fP
+[\fB-floyd\fP|\fB-fs\fP]
+\fIncolors\fP
+[\fIppmfile\fP]
+\fBppmquant\fP
+[\fB-floyd\fP|\fB-fs\fP]
+[\fB-nofloyd\fP|\fB-nofs\fP]
+\fB-mapfile\fP
+\fImapfile\fP
+[\fIppmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.  You
+may use two hyphens instead of one to designate an option.  You may
+use either white space or equals signs between an option name and its
+value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmquant\fP is obsolete.  All it does now is invoke
+\fBpnmquant\fP or \fBpnmremap\fP.  You should use one of those
+programs in any new program, or if you are modifying an old program,
+and your program does not have to work with a version of Netpbm before
+9.21 (January 2001).  \fBppmquant\fP exists only for name
+compatibility.
+.PP
+\fBpnmquant\fP is fully backward compatible with \fBppmquant\fP
+\fIwithout\fP the \fB-mapfile\fP option; \fBpnmremap\fP is fully
+backward compatible with \fBppmquant\fP \fIwith\fP the
+\fB-mapfile\fP option.
+.PP
+Except with differences suggested by the syntax synopsis above,
+\fBppmquant\fP's function is the same as \fBpnmquant\fP and
+\fBpnmremap\fP.
+.PP
+Before Netpbm 10.19 (November 2003), \fBppmquant\fP was a completely
+separate program from \fBpnmquant\fP, and was a bona fide PPM program.
+That means if you gave it a PGM or PBM image as input, it would process it
+as if it were PPM and generate a PPM output.  Now, since it is really a
+PNM program, it processes PBM and PGM inputs as what they are and produces
+the same kind of output.
+.PP
+Note: The reason \fBppmquant\fP was changed in Netpbm 10.19 is
+that for some time before that, \fBppmquant\fP had a serious bug that
+would have been difficult to fix -- it chose the wrong color set.
+Maintaining two versions of the same code did not make sense.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmquant.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmquantall.1 b/upstream/mageia-cauldron/man1/ppmquantall.1
new file mode 100644
index 00000000..484790c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmquantall.1
@@ -0,0 +1,33 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmquantall User Manual" 0 "05 March 2012" "netpbm documentation"
+
+.SH NAME
+
+ppmquantall - replaced by pnmquantall
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmquantall\fP was obsoleted by
+.BR "\fBpnmquantall\fP" (1)\c
+\&, introduced with Netpbm 10.58
+(March 2012).  \fBpnmquantall\fP is just a renaming to reflect the fact
+that the program handles all kinds of Netpbm input files, not just
+PPM.  Though this was not always the case, it had been for many years
+before the renaming.
+.PP
+For Netpbm before 10.58, where the program is still named
+\fBppmquantall\fP, just use the \fBpnmquantall\fP manual.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmquantall.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmrainbow.1 b/upstream/mageia-cauldron/man1/ppmrainbow.1
new file mode 100644
index 00000000..b6f9e063
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmrainbow.1
@@ -0,0 +1,135 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmrainbow User Manual" 0 "12 November 2014" "netpbm documentation"
+
+.SH NAME
+
+ppmrainbow - Generate a rainbow
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmrainbow\fP
+
+[\fB-width=\fP\fInumber\fP] [\fB-height=\fP\fInumber\fP]
+[\fB-tmpdir=\fP\fIdirectory\fP] [\fB-norepeat\fP] [\fB-verbose\fP] \fIcolor\fP ...
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBppmrainbow\fP generates a PPM image that fades from one color to
+another to another from left to right, like a rainbow.
+.PP
+If you want a vertical or other non-horizontal rainbow, run the output
+through \fBpnmrotate\fP or \fBpamflip\fP.
+.PP
+One use for such a rainbow is to compose it with another image
+under a transparency mask in order to add a rainbow area to another image.
+In fact, you can make rainbow-colored text by using \fBpbmtext\fP,
+\fBpamcomp\fP, and \fBppmrainbow\fP.
+.PP
+\fBpgmramp\fP does a similar thing for grayscale images.
+.PP
+If you just want an image containing all the possible colors (for some
+kind of processing; not to look at), see \fBpamseq\fP.
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+\fIcolor\fP ... is the list of colors, in order from left to right,
+to go into the rainbow.
+.PP
+The first color is added again on the right end of the image unless you
+specify the \fB-norepeat\fP option.  This means you can concatenate multiple
+copies (tile, as with \fBpnmtile\fP) to make a continuous larger image.
+.PP
+\fIcolor\fP is as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or equals signs between an option name and
+its value.
+
+
+.TP
+\fB-width \fP\fInumber\fP
+The width in pixels of the output image.
+.sp
+Default is 600.
+
+.TP
+\fB-height \fP\fInumber\fP
+The height in pixels of the output image.
+.sp
+Default is 8.
+
+.TP
+\fB-norepeat\fP
+     
+This option makes \fBppmrainbow\fP end the rainbow with the last
+color you specify.  Without this option, \fBppmrainbow\fP adds the
+first color you specify to the right end of the rainbow as if you had
+repeated it.
+
+.TP
+\fB-tmpdir\fP
+The directory specification of the directory \fBppmrainbow\fP is
+to use for temporary files.
+.sp
+Default is the value of the \fBTMPDIR\fP environment variable, or
+\fB/tmp\fP if \fBTMPDIR\fP is not set.
+.sp
+\fBppmrainbow\fP always creates a directory within this directory
+and creates all its files within that directory.
+
+.TP
+\fB-verbose\fP
+Print the "commands" (invocations of other Netpbm
+programs) that \fBppmrainbow\fP uses to create the image.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmramp" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "pamgradient" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "ppmfade" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&.
+
+.UN author
+.SH AUTHOR
+.PP
+Arjen Bax wrote \fBppmrainbow\fP in June 2001 and contributed it
+to the Netpbm package.  Bryan Henderson wrote this manual in July
+2001.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmrainbow.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmrelief.1 b/upstream/mageia-cauldron/man1/ppmrelief.1
new file mode 100644
index 00000000..54295244
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmrelief.1
@@ -0,0 +1,73 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmrelief User Manual" 0 "02 August 2014" "netpbm documentation"
+
+.SH NAME
+
+ppmrelief - compute a relief of a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmrelief\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmrelief\fP reads a PPM image as input, and writes a relief of
+that image as a PPM image as output.
+.PP
+The relief process is described in "Beyond Photography" by
+Holzmann, equation 3.19.  It's a sort of edge-detection and is essentially
+a convolution with this matrix:
+
+.nf
+
+    |  1  0  0 |
+    |  0  0  0 |
+    |  0  0 -1 |
+
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmrelief\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamshadedrelief" (1)\c
+\&, 
+.BR "pgmbentley" (1)\c
+\&, 
+.BR "pgmoil" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Wilson Bent (\fIwhb@hoh-2.att.com\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmrelief.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmrough.1 b/upstream/mageia-cauldron/man1/ppmrough.1
new file mode 100644
index 00000000..55ebb7fd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmrough.1
@@ -0,0 +1,190 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmrough User Manual" 0 "28 January 2022" "netpbm documentation"
+
+.SH NAME
+ppmrough - create PPM image of two colors with a ragged border between them
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmrough\fP
+
+[\fB-left \fP\fIpixels\fP]
+
+[\fB-right \fP\fIpixels\fP]
+
+[\fB-top \fP\fIpixels\fP]
+
+[\fB-bottom \fP\fIpixels\fP]
+
+[\fB-width \fP\fIpixels\fP]
+
+[\fB-height \fP\fIpixels\fP]
+
+[\fB-bg \fP\fIcolorspec\fP]
+
+[\fB-fg \fP\fIcolorspec\fP]
+
+[\fB-var \fP\fIpixels\fP]
+
+[\fB-randomseed \fP\fIseed\fP]
+
+[\fB-verbose\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmrough\fP generates a PPM image of the specified width, height, and
+colors.  \fBppmrough\fP tiles the image into semi-rectangular regions with a
+ragged borders between them.  It calculates the fluctuations with
+pseudo-random numbers.
+.PP
+\fBppmrough\fP writes the PPM image to Standard Output.
+.PP
+The maxval of the output image is 255 (You can change this with
+\fBpamdepth\fP).
+.PP
+Use the options \fB-left\fP or \fB-right\fP, respectively, to
+make vertical borders, and \fB-top\fP or \fB-bottom\fP,
+respectively, to generate horizontal borders inside the image.  Each of
+these options needs an integer value \fIpixels\fP that determines the
+average distance of the interior border to the related edge of the
+image.  You may combine the \fB-left\fP, \fB-right\fP, \fB-top\fP,
+and \fB-bottom\fP options to generate an image with more than one
+border.  The algorithm ensures that you can concatenate two images
+produced with the same (i.e. \fB-left\fP) value without dislocations.
+.PP
+You specify the dimensions of the generated image with the
+\fB-width\fP and \fB-height\fP options.
+.PP
+Use the \fB-bg\fP and \fB-fg\fP options to set the background
+(margin) color and the foreground (interior) color, respectively.  If
+you don't specify any of the \fB-left\fP, \fB-right\fP, \fB-top\fP,
+and \fB-bottom\fP options, all pixels are set to foreground color.
+The defaults are white foreground and black background.
+.PP
+Use the \fB-var\fP option to control the "raggedness" of
+the border.  The less its value is the smoother the border is.  You
+can initialize the pseudo-random generator with the \fB-init\fP
+option.
+.PP
+You could use \fBppmrough\fP with \fBppmtopgm\fP to create a PGM
+transparency mask and use it to roughen up the edges of another image.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmrough\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-left=\fP\fIpixels\fP
+ Specifies the mean distance of the border from the left margin
+(default: no border).
+
+.TP
+\fB-right=\fP\fIpixels\fP
+Specifies the mean distance of the border from the right margin
+(default: no border).
+
+.TP
+\fB-top=\fP\fIpixels\fP
+Specifies the mean distance of the border from the top margin
+(default: no border).
+
+.TP
+\fB-bottom=\fP\fIpixels\fP
+Specifies the mean distance of the border from the bottom margin
+(default: no border).
+
+.TP
+\fB-width=\fP\fIpixels\fP
+Specifies the width of the image (default: 100).
+
+.TP
+\fB-height=\fP\fIpixels\fP
+Specifies the height of the image (default: 100).
+
+.TP
+\fB-bg=\fP\fIcolorspec\fP
+Background color.  \fIcolorspec\fP is as described for the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.  Default is black.
+
+.TP
+\fB-fg=\fP\fIcolor\fP
+Foreground color.  \fIcolorspec\fP is as described for the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.  Default is white.
+
+.TP
+\fB-var=\fP\fIpixels\fP
+ Specifies the variance of the ragged border (default: 10). Must
+be a positive integer.  Set \fIpixels\fP to 1 to get a straight
+border.
+
+.TP
+\fB-randomseed=\fP\fIseed\fP
+Use this option to initialize the pseudo-random number generator
+with \fIseed\fP.
+.sp
+You can use this to cause the program to produce repeatable output.
+.sp
+Before Netpbm 10.61 (December 2012), this is called \fB-init\fP,
+and that still works.
+
+.TP
+\fB-verbose\fP
+Run \fBppmrough\fP in verbose mode.  It reports all parameters on
+Standard Error.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmmake" (1)\c
+\&,
+.BR "pamcat" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.9 (September 2002).
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2002 by Eckard Specht.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmrough.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmshadow.1 b/upstream/mageia-cauldron/man1/ppmshadow.1
new file mode 100644
index 00000000..3e0dd457
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmshadow.1
@@ -0,0 +1,294 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmshadow User Manual" 0 "24 June 2017" "netpbm documentation"
+
+.SH NAME
+ppmshadow - add simulated shadows to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmshadow\fP
+[\fB-b\fP \fIblur_size\fP]
+[\fB-k\fP]
+[\fB-t\fP]
+[\fB-x\fP \fIxoffset\fP]
+[\fB-y\fP \fIyoffset\fP]
+[\fIppmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmshadow\fP adds a simulated shadow to an image, giving the
+appearance that the contents of the image float above the page,
+casting a diffuse shadow on the background.  Shadows can either be
+black, as cast by opaque objects, or translucent, where the shadow
+takes on the color of the object which casts it.  You can specify the
+crispness of the shadow and its displacement from the image with command
+line options.
+.PP
+\fBppmshadow\fP sees your image as a foreground on a background.
+The background color is whatever color the top left pixel of your image is.
+The background is all the pixels that are that color and the foreground
+is everything else.  The shadow that \fBppmshadow\fP generates is a
+shadow of the foreground, cast on the background.
+.PP
+The shadow is the same size as the foreground, plus some fringes
+as determined by the \fB-b\fP option.  It is truncated to fit in your
+image.  The output image is the same dimensions as the input image.
+.PP
+You can use \fBpamcomp\fP to place a foreground image over a background
+before running \fBppmshadow\fP on it.  You can use \fBppmmake\fP to make
+the background image (just an image of a solid color).
+.PP
+The output has the same dimensions and maxval as the input.
+.PP
+The blurring to make the fringes of the shadow will not have a desirable
+effect if the color depth (maxval) of the image is too low -- you need a high
+maxval to get all the shades needed to create a smooth gradient.  So if your
+input has low maxval (including most notably if the input is PBM, which means
+its maxval is 1), run it through \fBpamdepth\fP to raise its maxval.  255 is
+usually a good choice.
+.PP
+Input is a PPM file named by the \fIppmfile\fP command line argument; if
+you don't specify \fIppmfile\fP, the input is Standard Input.
+.PP
+The output is a PPM file, written to Standard Output.
+
+
+.UN options
+.SH OPTIONS
+
+\fBppmshadow\fP recognizes the following command line options:
+
+
+.TP
+\fB-b\fP \fIblur_size\fP
+Sets the distance of the light source from the image.  Larger values
+move the light source closer, casting a more diffuse shadow, while
+smaller settings move the light further away, yielding a sharper
+shadow.  \fIblur_size\fP is the number of pixels of fringe there is
+on the shadow, beyond where the shadow would be if there were no
+blurring.
+.sp
+The default is 11 pixels.
+.sp
+Note that this option controls only the fringing effect of moving
+the light source closer to the object.  It does not make the shadow
+grow or shrink as would happpen in the real world if you moved a point
+light source closer to and further from an object.
+
+.TP
+\fB-k\fP
+Keep the intermediate temporary image files.  When debugging, these
+intermediate files provide many clues as to the source of an error.
+See 
+.UR #tempfiles
+below
+.UE
+\& for a list of the contents of each file.
+
+.TP
+\fB-t\fP
+Consider the non-background material in the image translucent -- it
+casts shadows of its own color rather than a black shadow, which is
+default.  This often results in fuzzy, difficult-to-read images but in
+some circumstances may look better.
+
+.TP
+\fB-x\fP\fI xoffset\fP
+Specifies the displacement of the light source to the left of the
+image.  Larger settings of \fBxoffset\fP displace the shadow to the
+right, as would be cast by a light further to the left.  If not
+specified, the horizontal offset is half of \fIblur_size \fP (above),
+to the left.
+
+.TP
+\fB-y\fP\fI yoffset\fP
+ Specifies the displacement of the light source above the top of
+the image.  Larger settings displace the shadow downward,
+corresponding to moving the light further above the top of the image.
+If you don't specify \fB-y\fP, the vertical offset defaults to the
+same as the horizontal offset (above), upward.
+
+
+.PP
+\fBppmshadow\fP does not recognize the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)  However, the \fB-version\fP option works.
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The source image must contain sufficient space on the edges in the
+direction in which the shadow is cast to contain the shadow -- if it
+doesn't some of the internal steps may fail.  You can usually expand
+the border of a too-tightly-cropped image with \fBpnmmargin\fP before
+processing it with \fBppmshadow\fP.
+.PP
+Black pixels and pixels with the same color as the image
+background don't cast a shadow.  If this causes unintentional
+"holes" in the shadow, fill the offending areas with a color
+which differs from black or the background by RGB values of 1, which
+will be imperceptible to the viewer.  Since the comparison is exact,
+the modified areas will now cast shadows.  
+.PP
+The background color of the source image (which is preserved in
+the output) is deemed to be the color of the pixel at the top left of
+the input image.  If that pixel isn't part of the background, simply
+add a one-pixel border at the top of the image, generate the shadow
+image, then delete the border from it.
+.PP
+If something goes wrong along the way, the error messages from the
+various Netpbm programs \fBppmshadow\fP calls will, in general,
+provide little or no clue as to where \fBppmshadow\fP went astray.
+In this case, Specify the \fB-k\fP option and examine the
+intermediate results in the temporary files (which this option causes
+to be preserved).  If you manually run the commands that
+\fBppmshadow\fP runs on these files, you can figure out where the
+problem is.  In problem cases where you want to manually tweak the
+image generation process along the way, you can keep the intermediate
+files with the \fB-k \fP option, modify them appropriately with an
+image editor, then recombine them with the steps used by the code in
+\fBppmshadow\fP.
+.PP
+Shadows are by default black, as cast by opaque material in the
+image occluding white light.  Use the \fB-t\fP option to simulate
+translucent material, where the shadow takes on the color of the
+object that casts it.  If the contrast between the image and
+background is insufficient, the \fB-t\fP option may yield
+unattractive results which resemble simple blurring of the original
+image.
+.PP
+Because Netpbm used to have a maximum maxval of 255, which meant
+that the largest convolution kernel \fBpnmconvol\fP could use was 11
+by 11, \fBppmshadow\fP includes a horrid, CPU-time-burning kludge
+which, if a blur of greater than 11 is requested, performs an initial
+convolution with an 11 x 11 kernel, then calls \fBpnmsmooth\fP
+(which is itself a program that calls \fBpnmconvol\fP with a 3 x 3
+kernel) as many times as the requested blur exceeds 11.  It's ugly,
+but it gets the job done on those rare occasions where you need a blur
+greater than 11.
+.PP
+If you wish to generate an image at high resolution, then scale it
+to publication size with \fBpamscale\fP in order to eliminate jagged
+edges by resampling, it's best to generate the shadow in the original
+high resolution image, prior to scaling it down in size.  If you scale
+first and then add the shadow, you'll get an unsightly jagged stripe
+between the edge of material and its shadow, due to resampled pixels
+intermediate between the image and background obscuring the shadow.
+
+.UN exitstatus
+.SH EXIT STATUS
+
+\fBppmshadow\fP returns status 0 if processing was completed without
+errors, and a nonzero Unix error code if an error prevented generation
+of output.  Some errors may result in the script aborting, usually
+displaying error messages from various Netpbm components it uses,
+without returning a nonzero error code.  When this happens, the output
+file will be empty, so be sure to test this if you need to know if the
+program succeeded.
+
+.UN tempfiles
+.SH TEMPORARY FILES
+.PP
+\fBppmshadow\fP creates a number of temporary files as it executes.  It
+creates a new directory for them in the directory named by the
+\fBTMPDIR\fP environment variable, defaulting to \fB/tmp\fP if it is not
+set.
+.PP
+In normal operation, \fBppmshadow\fP finds a unique name for the
+temporary directory and deletes each temporary file as
+soon as it is done with it and leaves no debris around after it
+completes.  To preserve the intermediate files for debugging, use the
+\fB-k\fP command line option.  In that case, the directory name is
+\fBppmshadow\fP\fIpid\fP, where \fIpid\fP is the process ID of
+the \fBppmshadow\fP process, and the program fails if \fBppmshadow\fP cannot
+create that directory because the name is already in use.
+.PP
+The temporary files are: 
+
+
+.TP
+\fBinfile.ppm\fP
+A copy of the input.
+
+.TP
+\fBbackground.ppm\fP
+Blank image with background of source image
+
+.TP
+\fBbgmask.ppm\fP
+Positive binary mask
+
+.TP
+\fBconvkernel.ppm\fP
+Convolution kernel for blurring shadow
+
+.TP
+\fBblurredlackshad.ppm\fP
+Blurred shadow image before coloring
+
+.TP
+\fBblurred.ppm\fP
+Blurred, colored shadow image
+
+.TP
+\fBshadow.ppm\fP
+Clipped shadow image, offset as requested
+
+.TP
+\fBshadback.ppm\fP
+Generated shadow times positive mask
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&,
+.BR "pnmmargin" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+John Walker 
+.UR http://www.fourmilab.ch
+http://www.fourmilab.ch
+.UE
+\& August
+8, 1997
+
+.UN copyright
+.SH COPYRIGHT
+This software is in the public domain.  Permission to use, copy,
+modify, and distribute this software and its documentation for any
+purpose and without fee is hereby granted, without any conditions or
+restrictions.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmshadow.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmshift.1 b/upstream/mageia-cauldron/man1/ppmshift.1
new file mode 100644
index 00000000..77edd6fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmshift.1
@@ -0,0 +1,100 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmshift User Manual" 0 "20 November 2008" "netpbm documentation"
+
+.SH NAME
+
+ppmshift - shift lines of a PPM image left or right by a random amount
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmshift\fP
+\fIshift\fP
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmshift\fP reads a PPM image as input.  It shifts every row of image
+data to the left or right by a random amount, within a range of \fIshift\fP
+pixels.  The random distribution is uniform, centered at zero movement.
+.PP
+The randomness in the image is limited before Netpbm 10.37 (December
+2006) -- if you run the program twice in the same second, you may get
+identical output.
+.PP
+This is an effect the author intended to use for MPEG tests.
+Unfortunately, this program is not useful for that - it creates too random
+patterns to be used for animations.  Still, it might give interesting results
+on still images.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmshift\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN example
+.SH EXAMPLE
+.PP
+Check this out: Save your favorite model's picture from something like
+alt.binaries.pictures.supermodels (ok, or from any other picture source),
+convert it to ppm, and process it e.g. like this, assuming the picture is 
+800x600 pixels:
+
+.nf
+     #take the upper half, and leave it like it is
+     pamcut -top=0 -width=800 -height=300 cs.ppm >upper.ppm
+     
+     #take the lower half, flip it upside down, dim it and distort it a little
+     pamcut -top=300 -width=800 -height=300 cs.ppm | \e
+         pamflip -topbottom | \e
+         ppmdim 0.7 | \e
+         ppmshift 10 >lower.ppm
+     
+     #and concatenate the two pieces
+     pnmcat -topbottom upper.ppm lower.ppm >newpic.ppm
+
+
+.fi
+.PP
+The resulting picture looks like the image being reflected on a water 
+surface with slight ripples.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&,
+.BR "ppmdim" (1)\c
+\&,
+.BR "pnmcat" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmshift.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmspread.1 b/upstream/mageia-cauldron/man1/ppmspread.1
new file mode 100644
index 00000000..168a2ec5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmspread.1
@@ -0,0 +1,80 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmspread User Manual" 0 "06 March 2021" "netpbm documentation"
+
+.SH NAME
+
+ppmspread - displace a PPM image's pixels by a random amount
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmspread\fP \fIamount\fP [\fIppmfile\fP]
+[\fB-randomseed=\fP\fIinteger\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmspread\fP reads a PPM image as input and moves every pixel
+around a random bit relative to its original position. \fIamount\fP
+determines by how many pixels a pixel is to be moved around at most.
+.PP
+Pictures processed with this filter will seem to be somewhat
+dissolved or unfocussed (although they appear more coarse than images
+processed by something like \fIpnmconvol\fP).
+.PP
+The randomness in the image is limited before Netpbm 10.37 (December
+2006) -- if you run the program twice in the same second, you may get
+identical output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmspread\fP recognizes the following
+command line options:
+
+
+  
+.TP
+\fB-randomseed=\fP\fIinteger\fP
+This is the seed for the random number generator that generates the
+pixels.
+.sp
+Use this to ensure you get the same image on separate invocations.
+.sp
+This option was new in Netpbm 10.94 (March 2021).
+
+
+
+  
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&, 
+.BR "pnmconvol" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmspread.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoacad.1 b/upstream/mageia-cauldron/man1/ppmtoacad.1
new file mode 100644
index 00000000..7b2c6202
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoacad.1
@@ -0,0 +1,173 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoacad User Manual" 0 "10 October 1991" "netpbm documentation"
+
+.SH NAME
+
+ppmtoacad - convert PPM to Autocad database or slide
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoacad\fP
+
+[\fB-dxb\fP]
+
+[\fB-poly\fP]
+
+[\fB-background\fP \fIcolor\fP]
+
+[\fB-white\fP]
+
+[\fB-aspect\fP \fIratio\fP]
+
+[\fB-8\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoacad\fP reads a PPM image as input and produces an
+Autocad\*R slide file or binary database import (.dxb) file as
+output.  If you don't specify \fIppmfile\fP,
+\fBppmtoacad\fP takes the input from Standard Input.
+.PP
+(Typographical note: the name of Autocad is often rendered as
+AutoCAD.  Netpbm documentation uses standard American typography, wherein
+that is not a valid form of capitalization).
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoacad\fP recognizes the following
+command line options:
+.PP
+You may abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB-dxb\fP
+\fBppmtoacad\fP writes an Autocad binary database import (.dxb)
+file.  You read this file with the DXBIN command and, once loaded, it
+becomes part of the Autocad geometrical database, so you can view and
+edit it like any other object.  Each sequence of identical pixels
+becomes a separate object in the database; this can result in very
+large Autocad drawing files.  However, if you want to trace over a
+bitmap, it lets you zoom and pan around the bitmap as you wish.
+
+.TP
+\fB-poly\fP
+If you don't specify the \fB-dxb\fP option, \fBppmtoacad\fP
+generates an Autocad slide file.  Normally each row of pixels is
+represented by an Autocad line entity.  If you specify \fB-poly\fP,
+\fBppmtoacad\fP renders the pixels as filled polygons.  If you view
+the slide on a display with higher resolution than the source image,
+this will cause the pixels to expand instead of appearing as discrete
+lines against the screen background color.  Regrettably, this
+representation yields slide files which occupy more storage space and
+take longer to display.
+
+.TP
+\fB-background\fP \fIcolor\fP
+Most Autocad display drivers can be configured to use any
+available color as the screen background.  Some users prefer a black
+screen background, others white, while splinter groups advocate burnt
+ocher, tawny puce, and shocking gray.  Discarding pixels whose closest
+Autocad color representation is equal to the background color can
+substantially reduce the size of the Autocad database or slide file
+needed to represent a bitmap.  If you don't specify
+\fB-background\fP, \fBppmtoacad\fP assumes the screen background
+color to be black.  You may specify any Autocad color number as the
+screen background; \fBppmtoacad\fP assumes color numbers to specify
+the hues defined in the standard Autocad 256 color palette.
+
+.TP
+\fB-white\fP
+Since many Autocad users choose a white screen background, this
+option is provided as a short-cut.  Specifying \fB-white\fP is
+identical in effect to \fB-background 7\fP.
+
+.TP
+\fB-aspect\fP \fIratio\fP
+If the source image had non-square pixels (which means it is not
+standard PPM), specify the ratio of the pixel width to pixel height as
+\fIratio\fP.  \fBppmtoacad\fP will correct the resulting slide or
+\&.dxb file so that pixels on the Autocad screen will be square.  For
+example, to correct an image made for a 320x200 VGA/MCGA screen,
+specify \fB-aspect 0.8333\fP.
+
+.TP
+\fB-8\fP
+Restricts the colors in the output file to the 8 RGB shades.
+
+
+.UN restrictions
+.SH RESTRICTIONS
+.PP
+Autocad has a fixed palette of 256 colors, distributed along the
+hue, lightness, and saturation axes.  So it may poorly render images
+which contain many nearly-identical colors, or colors not closely
+approximated by Autocad's palette.
+.PP
+\fBppmtoacad\fP works best if the system displaying its output can
+display the full 256 color Autocad palette.  Monochrome, 8 color, and
+16 color configurations will produce less than optimal results.
+.PP
+When creating a .dxb file or a slide file with the \fB-poly\fP
+option, \fBppmtoacad\fP finds both vertical and horizontal runs of
+identical pixels and consolidates them into rectangular regions to
+reduce the size of the output file.  This is effective for images with
+large areas of constant color but it's no substitute for true raster
+to vector conversion.  In particular, this process does not optimize
+thin diagonal lines at all.
+.PP
+Output files can be huge.
+
+.UN seealso
+.SH SEE ALSO
+.PP
+Autocad Reference Manual: \fISlide File Format\fP and \fIBinary
+Drawing Interchange (DXB) Files\fP,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+.nf
+John Walker
+Autodesk SA
+Avenue des Champs-Montants 14b
+CH-2074 MARIN
+Suisse/Schweiz/Svizzera/Svizra/Switzerland
+    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
+    \fBFax:\fP038/33 88 15
+    \fBVoice:\fP038/33 76 33
+
+.fi
+.PP
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided
+"as is" without express or implied warranty.
+.PP
+Autocad and Autodesk are registered trademarks of Autodesk, Inc.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoacad.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoapplevol.1 b/upstream/mageia-cauldron/man1/ppmtoapplevol.1
new file mode 100644
index 00000000..f04fe22e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoapplevol.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoapplevol User Manual" 0 "27 January 2022" "netpbm documentation"
+
+.SH NAME
+
+ppmtoapplevol - convert a PPM into an Apple volume label image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoapplevol\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoapplevol\fP reads a PPM image as input and produces an Apple
+volume label image as output.
+.PP
+EFI-based Apple systems use a simple image format to provide textual labels
+for devices.  This program generates that format.
+.PP
+The input image must be exactly 12 rows tall and up to 255 columns wide.
+  The program fails if it is not.  Use \fBpamfile\fP to see the dimensions of
+  your image and \fBpamscale\fP or \fBpamcut\fP to make it 12 rows and less
+  than 256 columns if it isn't.
+.PP
+Netpbm does not have a converter for the other direction.
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+The optional \fIppmfile\fP argument is the name of the input file.
+  The default is to read the input image from Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoapplevol\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamfile" (1)\c
+\&
+.BR "pamcut" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmtoapplevol\fP was new in Netpbm 10.54 (March 2011).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoapplevol.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoarbtxt.1 b/upstream/mageia-cauldron/man1/ppmtoarbtxt.1
new file mode 100644
index 00000000..46c1adb5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoarbtxt.1
@@ -0,0 +1,278 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoarbtxt User Manual" 0 "26 November 2014" "netpbm documentation"
+
+.SH NAME
+ppmtoarbtxt - generate image in arbitrary text format from PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoarbtxt\fP
+\fIbodytmpl\fP
+[\fB-hd\fP \fIheadtmpl\fP]
+[\fB-tl\fP \fItailtmpl\fP]
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoarbtxt\fP generates simple text-based graphics formats based on
+format descriptions given as input.  A text-based graphics format is one in
+which an image is represented by text (like PNM plain format, but unlike
+PNM raw format).
+
+\fBppmtoarbtxt\fP reads a PPM image as input.  For each pixel in the
+image, \fBppmtoarbtxt\fP writes the contents of the template file
+\fIbodytmpl\fP, with certain substitutions based on the value of the
+pixel, to Standard Output.
+.PP
+You may also supply a head template file, in which case \fBppmtoarbtxt\fP
+generates text from the template file, based on the image dimensions, and
+includes it in the output before anything else.
+.PP
+Likewise, you may supply a tail template file to cause text to be placed
+at the end of the output.
+
+
+.UN templatefiles
+.SS Template Files
+.PP
+The text that \fBppmtoarbtxt\fP generates from a template file is the
+literal text of the template file, except with substitution specifier replaced
+with something else.  The program recognizes a substitution specifier as
+text of the form \fB#(\fP...\fB)\fP.
+.PP
+\fBppmtoarbtxt\fP treats white space in the template files the same as any
+other characters, placing it in the output, with one exception: If the
+template file ends with a newline character, \fBppmtoarbtxt\fP ignores it --
+it does not include it in the output.
+.PP
+Many substitution specifiers use format strings (another form of template)
+to specify the substitution.  You should make these format strings as minimal
+as possible, placing literal text outside the substitution specifier instead
+of inside the format string.  For example,
+.PP
+Wrong: \f(CW#(flum %%%2.2f 0 1) \fP
+.PP
+Right: \f(CW%#(flum %2.2f 0 1) \fP
+.PP
+The valid substitution specifiers are as follows.  Text that has the
+form of a substitution specifier but is not actually valid (e.g.
+\fB#(random junk)\fP usually just specifies its literal value, but if it is
+close enough to something valid, \fBppmtoarbtxt\fP assumes you made a mistake
+and fails.
+.PP
+Useful in a body template, to do substitutions based on a particular pixel:
+
+
+.TP
+\fB#(ired\fP\fI format blackref whiteref\fP\fB)\fP
+generates an integer in the range \fIblackref\fP to
+\fIwhiteref\fP in a format specified by \fIformat\fP representing the red
+intensity of the pixel.  A red intensity of 0 becomes \fIblackref\fP; a red
+intensity of maxval becomes \fIwhiteref\fP, with the rest linearly
+interpolated in between.
+.sp
+\fIformat\fP is a printf-like format specifier like "%d".
+\fBppmtoarbtxt\fP uses as the entire format string to a \fBfprintf\fP POSIX
+library call whose only other argument is the red itensity as an integer data
+type.  \fBppmtoarbtxt\fP does not necessarily verify that your format string
+makes sense; there are values you could specify that could even crash the
+program.  To avoid unexpected behavior, keep format strings simple and
+hardcoded, and never include a per cent sign or newline.
+.sp
+\fB#(ired)\fP is equivalent to \fB#(ired %d 0 255)\fP.
+
+.TP
+\fB#(igreen\fP\fI format blackref whiteref\fP\fB)\fP
+Same as \fB#(ired...\fP, but for green.
+
+.TP
+\fB#(iblue\fP\fI format blackref whiteref\fP\fB)\fP
+Same as \fB#(ired...\fP, but for blue.
+
+.TP
+\fB#(ilum\fP\fI format blackref whiteref\fP\fB)\fP
+Same as \fB#(ired...\fP, but representing the luminance value
+(0.299*red + 0.587*green + 0.114*blue) of the pixel.
+
+.TP
+\fB#(fred\fP\fI format blackref whiteref\fP\fB)\fP
+Same as \fB#(ired...\fP, but generates a floating point number instead
+of an integer.
+.sp
+In this case, the second argument to the \fBfprintf\fP that uses 
+\fIformat\fP has a double precision floating point data type.
+.sp
+\fB#(fred)\fP is equivalent to \fB#(fred %f 0.0 1.0)\fP.
+
+.TP
+\fB#(fgreen \fP\fIformat blackref whiteref\fP\fB)\fP
+Same as \fB#(fred...\fP, but for green.
+
+.TP
+\fB#(fblue \fP\fIformat blackref whiteref\fP\fB)\fP
+Same as \fB#(fred...\fP, but for blue.
+
+.TP
+\fB#(flum \fP\fIformat blackref whiteref\fP\fB)\fP
+Same as \fB#(fred...\fP, but representing the luminance value
+(0.299*red + 0.587*green + 0.114*blue) of the pixel.
+
+.TP
+\fB#(posx \fP\fIformat\fP\fB)\fP
+Generates the horizontal position of the pixel, in pixels from the left
+edge of the image.
+.sp
+The second argument to the \fBfprintf\fP that uses \fIformat\fP has an
+unsigned integer data type.
+.sp
+\fIformat\fP defaults to \fB%u\fP
+
+.TP
+\fB#(posy \fP\fIformat\fP\fB)\fP
+Same as \fB#(width...\fP, but for the vertical position.
+
+
+.PP
+If you use any of the above substitution specifiers in a head or tail
+template, the result is undefined.
+.PP
+Useful in a head or tail template, to do substitutions based on whole-image
+attributes:
+
+
+.TP
+\fB#(width \fP\fIformat\fP\fB)\fP
+Generates the width in pixels of the image.
+.sp
+The second argument to the \fBfprintf\fP that uses \fIformat\fP
+has an unsigned integer data type.
+.sp
+\fIformat\fP defaults to \fB%u\fP
+
+.TP
+\fB#(height \fP\fIformat\fP\fB)\fP
+Same as \fB#(width...\fP, but for the height of the image.
+
+
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoarbtxt\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-hd\fP \fIheadtmpl\fP
+This option specifies a head template (\fIheadtmpl\fP is the name of the
+head template file); it causes \fBppmtoarbtxt\fP to place the contents of the
+file named \fIheadtmpl\fP at the beginning of the output
+
+.TP
+\fB-tl\fP \fItailtmpl\fP
+This option specifies a tail template; it is analogous to \fB-hd\fP.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.SS gray inversion
+.PP
+Here we generate a PGM plain-format image with gray inversion
+(like \fBppmtopgm | pnminvert\fP).
+.PP
+Contents of our head template file:
+
+.nf
+P2
+#(width) #(height)
+255
+
+.fi
+.PP
+Contents of our body skeleton file:
+
+.nf
+#(ilum %d 255 0)
+
+.fi
+
+.SS povray file
+.PP
+Here we generate a povray file where each pixel is represented by a
+sphere at location (x,y,z) = (posx,height-posy,luminance).  The color
+of the sphere is the color of the pixel.
+.PP
+Contents of our head skeleton:
+
+.nf
+#include "colors.inc"
+#include "textures.inc"
+camera {
+   location  <#(width) * 0.6, #(height) * 0.7, 80>
+   look_at   <#(width) * 0.5, #(height) * 0.5, 0>
+}
+
+light_source { <#(width) * 0.5, #(height) * 0.5, 25> color White
+}
+
+.fi
+.PP
+Contents of our body skeleton:
+
+.nf
+sphere { <#(posx),#(height)-#(posy),#(ilum %d 0 10)>, 0.5
+  texture {
+    pigment {
+      color rgb <#(fred),#(fgreen),#(fblue)>
+    }
+    finish {
+      phong 1
+    }
+  }
+}
+
+.fi
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtoplainpnm" (1)\c
+\&
+.BR "pamtable" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmtoarbtxt\fP was added to Netpbm in Release 10.14 (March 2003).
+It existed under the name \fBppmtotxt\fP since 1995.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995 by Peter Kirchgessner
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoarbtxt.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoascii.1 b/upstream/mageia-cauldron/man1/ppmtoascii.1
new file mode 100644
index 00000000..b3a3269b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoascii.1
@@ -0,0 +1,92 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoascii User Manual" 0 "09 April 2010" "netpbm documentation"
+
+.SH NAME
+ppmtoascii - convert a PPM image to ASCII graphics with ANSI terminal color
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoascii\fP
+
+[\fB-1x2\fP|\fB-2x4\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoascii\fP reads a PPM image as input and produces a somewhat
+crude ASCII graphic image as output, with ANSI terminal control characters
+so it has crude color when sent to a color text terminal.
+.PP
+There is no converter for the other direction.
+.PP
+\fBppmtoterm\fP does a similar thing, but displays each character of the
+image as a single pixel (using the same dense character for every pixel),
+whereas \fBppmtoascii\fP combines 2 or 8 pixels into one character, where
+the character roughly represents those particular pixels.
+.PP
+Note that ANSI provides for only eight colors (including black and white).
+.PP
+Note that an ANSI terminal can't display a single character in multiple
+colors, so where a character represents 8 pixels of differing colors, the
+color of the character is one that is the average of the colors of those
+pixels.
+.PP
+\fBpbmtoascii\fP does the same thing for PBM images, with no terminal
+control characters (because none are needed for a strictly black and white
+image).
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoascii\fP recognizes the following
+command line options:
+.PP
+The \fB-1x2\fP and \fB-2x4\fP options give you two alternate ways for the
+pixels to get mapped to characters.  With \fB1x2\fP, the default, each
+character represents a group of 1 pixel across by 2 pixels down.  With
+\fB-2x4\fP, each character represents 2 pixels across by 4 pixels down.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoascii" (1)\c
+\&
+.BR "ppmtoterm" (1)\c
+\&
+.BR "ppm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmtoascii\fP was new in Netpbm 10.51 (June 2010).  Frank Ch. Eigler
+derived it from \fBpbmtoascii\fP.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2010 by Frank Ch. Eigler.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoascii.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtobmp.1 b/upstream/mageia-cauldron/man1/ppmtobmp.1
new file mode 100644
index 00000000..ecd5c9aa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtobmp.1
@@ -0,0 +1,167 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtobmp User Manual" 0 "20 December 2018" "netpbm documentation"
+
+.SH NAME
+ppmtobmp - convert a PPM image into a BMP file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtobmp\fP
+
+[\fB-windows\fP]
+
+[\fB-os2\fP]
+
+[\fB-bpp=\fP\fIbits_per_pixel\fP]
+
+[\fB-mapfile=\fP\fIfilename\fP]
+
+[\fIppmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtobmp\fP reads a PPM image as input and produces a Microsoft
+Windows or OS/2 BMP file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtobmp\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-windows\fP
+Tells the program to produce a Microsoft Windows BMP file.  (This
+is the default.)
+
+.TP
+\fB-os2\fP
+Tells the program to produce an OS/2 BMP file.  (Before August
+2000, this was the default).
+
+.TP
+\fB-bpp\fP
+This tells how many bits per pixel you want the BMP file to
+contain.  Only 1, 4, 8, and 24 are possible.  By default,
+\fBppmtobmp\fP chooses the smallest number with which it can
+represent all the colors in the input image.  If you specify a number
+too small to represent all the colors in the input image,
+\fBppmtobmp\fP tells you and terminates.  You can use \fBpnmquant\fP
+or \fBppmdither\fP to reduce the number of colors in the image.
+.sp
+Before Netpbm 10.85 (December 2018), \fBppmtobmp\fP ignores this option if
+the input is PBM and produces a BMP with 1 bit per pixel.  With these
+versions, if you want more than that, use \fBpbmtopgm\fP to convert the PBM
+to PGM first.
+
+.TP
+\fB-mapfile=\fP\fIfilename\fP
+This identifies a file to use as the BMP palette (aka
+"colormap").  In one BMP subformat, the BMP stream contains
+a palette of up to 256 colors, and represents the image raster as
+indices into that palette.  Normally, \fBppmtobmp\fP takes care of
+computing a suitable palette, but if you are going to dissect the BMP
+output in some way, you may want certain values for the palette
+indices.  E.g. you might want red to be 13, where \fBppmtobmp\fP
+would (arbitrarily) choose 39.  In that case, you can construct the
+palette yourself and use this option to tell \fBppmtobmp\fP to use
+your palette.
+.sp
+This option does \fInot\fP control what colors are in the
+output.  The colors in the output are exactly those in the input, and
+the palette you supply must contain at least all the colors that are
+in the input.  You can use \fBpnmremap\fP to adjust your input image
+so that it contains only colors from your palette.
+.sp
+The palette file is a Netpbm format file with one pixel per
+palette entry.  Each pixel must have a distinct color (no repeats).
+The order of the BMP palette \fBppmtobmp\fP generates is the order
+of the pixels in the palette file, going from top to bottom, left
+to right.
+.sp
+A BMP palette may have at most 256 colors, so the palette file
+must have at most 256 pixels.
+.sp
+You may find \fBpnmcolormap\fP useful in generating the palette
+file.  \fBpamseq\fP too.
+.sp
+In the case of grayscale image, if you are processing the BMP image, it
+  may be convenient for you to have the actual gray values in the raster
+  part of the image rather than arbitrary indices into a palette.  There is
+  no BMP format specifically for that, but you can achieve it by using a
+  palette in which each index is equal to the indexed gray value, and then
+  ignoring the palette when you process the BMP image.
+.sp
+Here is an example of doing that:
+
+.nf
+    \f(CW
+    $ pamseq 1 255 > mapfile.pgm
+
+    $ ppmtobmp -mapfile=mapfile.pgm input.pgm > output.bmp
+    \fP
+
+.fi
+.sp
+This option was new in Netpbm 10.45 (December 2008).
+
+
+
+
+.UN notes
+.SH NOTES
+.PP
+To get a faithful reproduction of the input image, the maxval of the
+input image must be 255.  If it is something else, 
+the colors in the BMP file may be slightly different from the colors
+in the input.
+.PP
+Windows icons are not BMP files.  Use \fBppmtowinicon\fP to
+create those.
+
+.UN seealso
+.SH SEE ALSO
+.BR "bmptoppm" (1)\c
+\&,
+.BR "ppmtowinicon" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992 by David W. Sanderson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtobmp.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoeyuv.1 b/upstream/mageia-cauldron/man1/ppmtoeyuv.1
new file mode 100644
index 00000000..9e330f1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoeyuv.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoeyuv User Manual" 0 "03 April 2000" "netpbm documentation"
+
+.SH NAME
+
+ppmtoeyuv - convert a PPM image into a Berkeley YUV file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoeyuv\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoeyuv\fP reads a PPM image as input and produces a Berkeley
+Encoder YUV (not the same as Abekas YUV) file on the Standard Output
+file.
+.PP
+With no argument, \fBppmtoeyuv\fPtakes input from Standard Input.
+Otherwise, \fIppmfile\fP is the file specification of the input file.
+.PP
+\fBppmtoeyuv\fP handles multi-image PPM input streams, outputting
+consecutive eyuv images.  There must be at least one image, though.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoeyuv\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "eyuvtoppm" (1)\c
+\&,
+.BR "ppmtoyuv" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoeyuv.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtogif.1 b/upstream/mageia-cauldron/man1/ppmtogif.1
new file mode 100644
index 00000000..9a8a0d9e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtogif.1
@@ -0,0 +1,95 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtogif User Manual" 0 "" "netpbm documentation"
+
+.SH NAME
+.PP
+ppmtogif - replaced by pamtogif
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+.SH SYNOPSIS
+.PP
+\fBppmtogif\fP was replaced in Netpbm 10.37 (December 2006) by
+.BR "pamtogif" (1)\c
+\&.
+.PP
+\fBpamtogif\fP is mostly backward compatible with \fBppmtogif\fP.
+
+.SH DESCRIPTION
+.PP
+One way \fBpamtogif\fP is not backward compatible with \fBppmtogif\fP
+is that to specify a transparency (alpha) mask with \fBppmtogif\fP, you
+supply the transparency as a separate pseudo-PGM image and use the
+\fB-alpha\fP option, whereas with \fBpamtogif\fP, you supply an input
+image that has the transparency integrated into it, and there is no
+\fB-alpha\fP option.
+.PP
+\fBppmtogif\fP still exists as a separate program for backward 
+compatibility, but it runs \fBpamtogif\fP to do the essential work.
+The compatibility \fBppmtogif\fP interprets an \fB-alpha\fP option
+by reading the transparency image and combining it with the input
+image, then feeding \fBpamtogif\fP the combined image it expects.
+Other than that, the compatibility \fBppmtogif\fP just passes input and
+options directly to \fBpamtogif\fP.
+.PP
+You should not make any new use of \fBppmtogif\fP and if you modify an
+existing use, you should upgrade to \fBpamtogif\fP.  But note that if you
+write a program that might have to be used with old Netpbm, \fBppmtogif\fP is
+the only way to do that.
+.PP
+Unless you use the \fB-alpha\fP option, you can simply change the name
+of the program.  If you use \fB-alpha\fP, here is how to upgrade:
+
+.nf
+\f(CW
+  $ ppmtogif -alpha=myalpha.pgm myinput.ppm >myoutput.gif
+\fP
+
+.fi
+
+becomes
+
+.nf
+\f(CW
+  $ pamstack -tupletype=RGB_ALPHA myinput.ppm myalpha.pgm |  \e
+      pamtogif >myoutput.gif
+\fP
+
+.fi
+
+
+.SH Original Ppmtogif
+.PP
+If you are using Netpbm before 10.37, \fBpamtogif\fP doesn't exist,
+so you use \fBppmtogif\fP.  You can use the \fBpamtogif\fP manual
+for \fBppmtogif\fP, with the following exceptions.
+.PP
+The current documentation of \fBpamtogif\fP documents all versions
+of that program.  Use the information for Version 10.37 only.
+.PP
+\fBppmtogif\fP before Netpbm 10.31 does not accept PAM input at all.
+.PP
+\fBppmtogif\fP does not accept PAM input with transparency information
+in it.  Instead, \fBppmtogif\fP has an \fB-alpha\fP option.
+.PP
+The syntax of the option is \fB-alpha=\fP\fIpgmfile\fP.
+\fBppmtogif\fP treats the contents of the named PGM file the same as
+\fBpamtogif\fP treats the alpha plane of a PAM.  The PGM image must
+have the same dimensions as the input file.  But unlike the PAM case,
+the alpha image need not have the same maxval as the input.
+\fBppmtogif\fP interprets the alpha file using the alpha file's
+maxval.
+.PP
+You cannot specify both \fB-transparent\fP and \fB-alpha\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtogif.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoicr.1 b/upstream/mageia-cauldron/man1/ppmtoicr.1
new file mode 100644
index 00000000..a13741d5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoicr.1
@@ -0,0 +1,159 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoicr User Manual" 0 "17 July 2022" "netpbm documentation"
+
+.SH NAME
+
+ppmtoicr - convert a PPM image into NCSA ICR format 
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoicr\fP
+
+[\fB-windowname\fP \fIname\fP]
+
+[\fB-expand\fP \fIexpand\fP]
+
+[\fB-display\fP \fIdisplay\fP]
+
+[\fIppmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoicr\fP reads a PPM file as input.  Produces an NCSA Telnet
+Interactive Color Raster graphic file as output.
+
+If \fIppmfile\fP is not supplied, \fBppmtoicr\fP reads from Standard
+Input.
+.PP
+Interactive Color Raster (ICR) is a protocol for displaying raster
+graphics on workstation screens. The protocol is implemented in NCSA
+Telnet for the Macintosh version 2.3.  The ICR protocol shares
+characteristics of the Tektronix graphics terminal emulation protocol.
+For example, escape sequences are used to control the display.
+.PP
+\fBppmtoicr\fP will output the appropriate sequences to create a
+window of the dimensions of the input image, create a colormap of up
+to 256 colors on the display, then load the picture data into the
+window.
+.PP
+Note that there is no icrtoppm tool - this transformation is one
+way.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoicr\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-windowname\fP \fIname\fP
+Output will be displayed in \fIname\fP.
+.sp
+\fIname\fP must be printable characters, and not '^'.
+.sp
+Default is to use the input file name if specified on the command line or
+  "untitled" if the input is from Standard Input.  In the former case, any
+  unprintable character or '^' in the file name becomes a
+  '.' in the window name.
+    
+.TP
+\fB-expand\fP \fIexpand\fP
+Output will be expanded on display by factor \fIexpand\fP (For
+example, a value of 2 will cause four pixels to be displayed for every
+input pixel.)
+
+.TP
+\fB-display\fP \fIdisplay\fP
+Output will be displayed on screen numbered \fIdisplay\fP
+
+
+
+.UN examples
+.SH EXAMPLES
+
+To display a PPM file named \fBppmfile\fP using the protocol:
+
+.nf
+    ppmtoicr ppmfile
+
+.fi
+
+This will create a window named \fIppmfile\fP on the display with the
+correct dimensions for \fIppmfile\fP, create and download a colormap
+of up to 256 colors, and download the picture into the window.  You
+may achieve the same effect with the following sequence:
+
+.nf
+    ppmtoicr ppmfile > filename
+    cat filename
+
+.fi
+.PP
+To display a GIF file using the protocol in a window titled after the
+input file, zoom the displayed image by a factor of 2:
+
+.nf
+    giftopnm giffile | ppmtoicr -windowname=giffile -expand=2
+
+.fi
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The protocol uses frequent fflush() calls to speed up display.  If
+you save the output to a file for later display via \fBcat\fP,
+\fBppmtoicr\fP will draw much more slowly.  In either case,
+increasing the blocksize limit on the display will speed up
+transmission substantially.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+.PP
+NCSA Telnet for the Macintosh, University of Illinois at
+Urbana-Champaign (1989)
+
+.UN history
+.SH HISTORY
+.PP
+Until Netpbm 10.71 (June 2015), there was a \fB-rle\fP option documented,
+which was said to cause the output to use run length encoding compression.
+But because of a simple bug in option processing code, the option never had
+any effect.  And the compression code did not look like it worked anyway and
+would take a fair amount of work to fix.  Because it was unlikely anyone would
+ever use this program again, much less want to use run length encoding, we
+removed it from the documentation rather than fix the code.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Kanthan Pillay (\fIsvpillay@Princeton.EDU\fP),
+Princeton University Computing and Information Technology.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoicr.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoilbm.1 b/upstream/mageia-cauldron/man1/ppmtoilbm.1
new file mode 100644
index 00000000..7642e1df
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoilbm.1
@@ -0,0 +1,249 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoilbm User Manual" 0 "15 January 2022" "netpbm documentation"
+
+.SH NAME
+
+ppmtoilbm - convert a PPM image into an ILBM file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoilbm\fP
+
+[\fB-maxplanes\fP|\fB-mp\fP \fIN\fP]
+
+[\fB-fixplanes\fP|\fB-fp\fP \fIN\fP]
+
+[\fB-ham6\fP|\fB-ham8\fP]
+
+[{\fB-dcbits\fP|\fB-dcplanes\fP} \fIr\fP \fIg\fP \fIb\fP]
+
+[
+\fB-normal\fP|\fB-hamif\fP|\fB-hamforce\fP|\fB-24if\fP|\fB-24force\fP|
+\fB-dcif\fP|\fB-dcforce\fP|\fB-cmaponly\fP
+]
+
+[\fB-ecs\fP|\fB-aga\fP]
+
+[\fB-compress\fP|\fB-nocompress\fP]
+
+[\fB-cmethod\fP \fItype\fP]
+
+[\fB-map\fP \fIppmfile\fP]
+
+[\fBppmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoilbm\fP reads a PPM image as input.  Produces an ILBM file
+as output.  \fBppmtoilbm\fP understands the following ILBM types:
+
+
+
+.IP \(bu
+Normal ILBMs with 1-16 planes
+
+.IP \(bu
+Amiga HAM with 3-16 planes
+
+.IP \(bu
+24 bit
+
+.IP \(bu
+Color map (BMHD + CMAP chunk only, nPlanes = 0)
+
+.IP \(bu
+Unofficial direct color.  1-16 planes for each color component.
+
+
+.PP
+Chunks written: BMHD, CMAP, CAMG (only for HAM), BODY (not for
+colormap files) unofficial DCOL chunk for direct color ILBM.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoilbm\fP recognizes the following
+command line options:
+.PP
+Options marked with (*) can be prefixed with a "no",
+e.g. "-nohamif".  All options can be abbreviated to their
+shortest unique prefix.
+
+
+.TP
+\fB-maxplanes\fP | \fB-mp\fP \fIn\fP
+(default 5, minimum 1, maximum 16) Maximum planes to write in a
+normal ILBM.  If the image does not fit into <n> planes,
+ppmtoilbm writes a HAM file (if -hamif is used), a 24bit file (if
+-24if is used) or a direct color file (if -dcif is used) or aborts
+with an error.
+
+.TP
+\fB-fixplanes\fP | \fB-fp\fP \fIb\fP
+(min 1, max 16) If a normal ILBM is written, it will have exactly
+<n> planes.
+
+.TP
+\fB-hambits\fP | \fB-hamplanes\fP \fIn\fP
+(default 6, min 3, max 16) Select number of planes for HAM
+picture.  The current Amiga hardware understands 6 and 8 planes, so for
+now you should only use this values.
+
+.TP
+\fB-normal\fP
+Turns off -hamif/-24if/-dcif, -hamforce/-24force/-dcforce and
+-cmaponly.  Also sets compression type to byterun1.
+.sp
+This is the default.
+
+.TP
+\fB-hamif\fP (*)
+.TP
+\fB-24if\fP (*)
+.TP
+\fB-dcif\fP (*)
+Write a HAM/24bit/direct color file if the image does not fit into
+<maxplanes> planes.
+
+.TP
+\fB-hamforce\fP (*)
+.TP
+\fB-24force\fP (*)
+.TP
+\fB-dcforce\fP (*)
+Write a HAM/24bit/direct color file.
+
+.TP
+\fB-dcbits\fP \fIr\fP \fIg\fP \fIb\fP
+.TP
+\fB-dcplanes\fP \fIr\fP \fIg\fP \fIb\fP
+(default 5, min 1, max 16).  Select number of bits for red, green
+and blue in a direct color ILBM.
+
+.TP
+\fB-ecs\fP
+Shortcut for: -hamplanes 6 -maxplanes 5
+.sp
+This is the default.
+
+.TP
+\fB-aga\fP
+Shortcut for: \fB-hamplanes 8 -maxplanes 8\fP
+
+.TP
+\fB-ham6\fP
+Shortcut for: \fB-hamplanes 6 -hamforce\fP
+
+.TP
+\fB-ham8\fP
+Shortcut for: \fB-hamplanes 8 -hamforce\fP
+
+.TP
+\fB-compress\fP (*)
+This is the default.
+Compress the BODY chunk.  The default compression method is
+byterun1.  Compression requires building the ILBM image in memory;
+turning compression off allows stream-writing of the image, but the
+resulting file will usually be 30% to 50% larger.  Another alternative
+is the -savemem option, this will keep memory requirements for
+compression at a minimum, but is very slow.
+
+.TP
+\fB-cmethod\fP \fBnone\fP|\fBbyterun1\fP
+This option does the same thing as \fB-compress\fP.
+
+.TP
+\fB-map\fP \fIppmfile\fP
+Write a normal ILBM using the colors in <ppmfile> as the
+colormap.  The colormap file also determines the number of planes;
+\fB-maxplanes\fP and \fB-fixplanes\fP are ignored.
+
+.TP
+\fB-cmaponly\fP
+Write a colormap file: only BMHD and CMAP chunks, no BODY chunk,
+nPlanes = 0.
+
+.TP
+\fB-savemem\fP
+See the \fB-compress\fP option.
+
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+HAM pictures will always get a grayscale colormap; a real color
+selection algorithm might give better results.  On the other hand,
+this allows row-by-row operation on HAM images, and all HAM images of
+the same depth (no. of planes) share a common colormap, which is
+useful for building HAM animations.
+
+.UN references
+.SH REFERENCES
+
+Amiga ROM Kernel Reference Manual - Devices (3rd Ed.)
+Addison Wesley, ISBN 0-201-56775-X
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&, 
+.BR "ilbmtoppm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+For about a year in 1993-1994, there was a \fB-savemem\fP option.
+.PP
+There used to be a \fB-floyd\fP (aka \fB-fs\fP) option that was supposed
+  to cause images to be dithered so that a larger number of colors in the PPM
+  input could be represented in a smaller number of colors in the ILBM output.
+  But it was never documented.  Furthermore, developers discovered in January
+  2022 that the code for this was nonfunctional because of defects, and had
+  been for a very long time and maybe always.  Finally,, this functions is not
+  appropriate in the Netpbm philosophy, because dithering should be done by a
+  separate dithering program, not a format conversion program.  Indeed,
+  the programs \fBppmdither\fP, \fBpnmquant\fP, and \fBpnmremap\fP can do
+  this.
+.PP
+Therefore, since Netpbm 10.98 (March 2022), the dithering code has not been
+  in the program and any attempt to use the options fails with a simple
+  invalid option message.  But the \fB-nofloyd\fP and \fB-nofs\fP options
+  remain, doing nothing as they were designed to do, and still not documented.
+  This is just in case something uses those options, since the cost of
+  maintaining them is so small.
+
+  
+.UN authors
+.SH AUTHORS
+.PP
+Copyright (C) 1989 by Jef Poskanzer.
+.PP
+Modified October 1993 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoilbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtojpeg.1 b/upstream/mageia-cauldron/man1/ppmtojpeg.1
new file mode 100644
index 00000000..e4ae7bf1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtojpeg.1
@@ -0,0 +1,30 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtojpeg User Manual" 0 "September 2001" "netpbm documentation"
+
+.SH NAME
+
+ppmtojpeg - replaced by pnmtojpeg
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtojpeg\fP was replaced in Netpbm 9.19 (September 2001) by
+.BR "pnmtojpeg" (1)\c
+\&.
+.PP
+\fBpnmtojpeg\fP is backward compatible with \fBppmtojpeg\fP
+except that with PGM or PBM input, it generates JPEG output in the special
+grayscale format.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtojpeg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoleaf.1 b/upstream/mageia-cauldron/man1/ppmtoleaf.1
new file mode 100644
index 00000000..84b1974b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoleaf.1
@@ -0,0 +1,59 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoleaf User Manual" 0 "01 June 2000" "netpbm documentation"
+
+.SH NAME
+
+ppmtoleaf - convert PPM image to Interleaf image format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoleaf\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoleaf\fP reads an Interleaf image file as input and
+generates a PPM image as output.
+.PP
+Interleaf is a now-defunct (actually purchased ca. 2000 by
+BroadVision) technical publishing software company.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoleaf\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+The program is copyright (C) 1994 by Bill O'Donnell.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoleaf.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtolj.1 b/upstream/mageia-cauldron/man1/ppmtolj.1
new file mode 100644
index 00000000..45b9d725
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtolj.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtolj User Manual" 0 "04 September 2000" "netpbm documentation"
+
+.SH NAME
+ppmtolj - convert a PPM image to an HP LaserJet PCL 5 Color file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtolj\fP
+
+[\fB-gamma\fP \fIval\fP]
+
+[\fB-resolution\fP {\fB75\fP|\fB100\fP|\fB150\fP|\fB300\fP|\fB600\fP}]
+
+[\fB-delta\fP]
+
+[\fB-float\fP]
+
+[\fB-noreset\fP] 
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtolj\fP reads a PPM image as input and converts it into a
+color file suitable to be printed by an HP color PCL 5 printer.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtolj\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-delta\fP
+Apply delta row compression to reduce the size of the pcl file. 
+.TP
+\fB-gamma\fP \fIint\fP
+Gamma correct the image using the integer parameter as a gamma (default 0).
+
+.TP
+\fB-float\fP
+Suppress positioning information.  The default is to write the sequence 
+ESC&l0E to the output.
+
+.TP
+\fB-noreset\fP
+Don't write the reset sequence to the beginning and end of the output.
+
+.TP
+\fB-resolution\fP
+Set the required output resolution 75|100|150|300|600
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+HP PCL 5 & Color Reference Guide,
+.BR "\fBpnmtopclxl\fP" (1)\c
+\&,
+.BR "\fBpbmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtopj\fP" (1)\c
+\&,
+.BR "\fBthinkjettopbm\fP" (1)\c
+\&,
+.BR "\fBppm\fP" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2000 by Jonathan Melvin.(\fIjonathan.melvin@heywood.co.uk\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtolj.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtomap.1 b/upstream/mageia-cauldron/man1/ppmtomap.1
new file mode 100644
index 00000000..dd2f9439
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtomap.1
@@ -0,0 +1,50 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtomap User Manual" 0 "06 January 2002" "netpbm documentation"
+
+.SH NAME
+
+ppmtomap - replaced by pnmcolormap
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program exists only for backward compatibility.
+.PP
+Use \fBpnmcolormap\fP, which replaced it in January 2002.
+.PP
+One trivial difference between \fBppmtomap\fP and \fBpnmcolormap
+all\fP is that if the input is PBM or PGM, \fBppmtomap\fP would
+produce PPM output, whereas \fBpnmcolormap all\fP produces the same
+kind of output as the input.  This should not be very noticeable,
+though, as PBM and PGM images are usually usable anywhere a PPM image
+is.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtomap\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmcolormap" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtomap.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtomitsu.1 b/upstream/mageia-cauldron/man1/ppmtomitsu.1
new file mode 100644
index 00000000..ece0e900
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtomitsu.1
@@ -0,0 +1,138 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtomitsu User Manual" 0 "24 March 2009" "netpbm documentation"
+
+.SH NAME
+
+ppmtomitsu - convert a PPM image to a Mitsubishi S340-10 file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtomitsu\fP
+
+[-sharpness \fIval\fP]
+
+[\fB-enlarge\fP \fIval\fP]
+
+[\fB-media\fP \fIstring\fP]
+
+[\fB-copy\fP \fIval\fP]
+
+[\fB-dpi300\fP]
+
+[\fB-tiny\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtomitsu\fP reads a PPM image as input and converts it into a
+format suitable to be printed by a Mitsubishi S340-10 printer, or any
+other Mitsubishi color sublimation printer.
+.PP
+The Mitsubishi S340-10 Color Sublimation printer can print in 24 bit
+color.  Images of the available sizes take so long to transfer that
+there is a fast method, employing a lookuptable, that ppmtomitsu will
+use if there is a maximum of 256 colors in the image.  ppmtomitsu
+will try to position your image to the center of the paper, and will
+rotate your image for you if xsize is larger than ysize.  If your
+image is larger than the media allows, ppmtomitsu will quit with an
+error message. (We decided that the media were too expensive to have
+careless users produce misprints.)  Once data transmission has
+started, the job can't be stopped in a sane way without resetting the
+printer.  The printer understands putting together images in the
+printers memory; ppmtomitsu doesn't utilize this as pnmcat etc provide
+the same functionality and let you view the result on-screen, too.
+The S340-10 is the lowest common denominator printer; for higher
+resolution printers there's the dpi300 option. The other printers are also
+capable of higher values for enlarge eg, but I don't think that's
+essential enough to warrant a change in the program.
+.PP
+For proper results, the input maxval must be 255.  Use \fBpamdepth\fP
+to ensure that it is.
+.PP
+Before Netpbm 10.40 (September 2007), all Netpbm PPM programs, including
+\fBppmtomitsu\fP, see a PBM image as having maxval 1, so \fBppmtomitsu\fP
+does not function properly with PBM input.  You can use \fBppmtoppm\fP
+together with \fBpamdepth\fP to turn your PBM input into maxval 255
+PPM input that \fBppmtomitsu\fP will use properly.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtomitsu\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-sharpness\fP \fI1-4\fP
+"sharpness" designation.  Default is  to use the current sharpness.
+
+.TP
+\fB-enlarge\fP \fI1-3\fP
+Enlarge by a factor; Default is 1 (no enlarge)
+
+.TP
+\fB-media\fP {\fBA\fP|\fBA4\fP|\fBAS\fP|\fBA4S\fP}
+Designate the media you're using.  Default is 1184 x 1350, which will
+fit on any media.  A is 1216 x 1350, A4 is 1184 x 1452, AS is 1216 x
+1650 and A4S is 1184 x 1754.  A warning: If you specify a different
+media than the printer currently has, the printer will wait until you
+put in the correct media or switch it off.
+
+.TP
+\fB-copy\fP \fI1-9\fP
+The number of copies to produce.  Default is 1.
+
+.TP
+\fB-dpi300\fP
+Double the number of allowed pixels for a S3600-30 Printer in S340-10
+compatibility mode.  (The S3600-30 has 300 dpi).
+
+.TP
+\fB-tiny\fP
+Memory-saving, but always slow. The printer will get the data
+line-by-line in 24bit. It's probably a good idea to use this if your
+machine starts paging a lot without this option.
+
+
+
+.UN references
+.SH REFERENCES
+
+Mitsubishi Sublimation Full Color Printer S340-10 Specifications of
+Parallel Interface LSP-F0232F
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmquant" (1)\c
+\&, 
+.BR "pamscale" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992, 93 by S.Petra Zeidler, MPIfR Bonn, Germany.  (\fIspz@specklec.mpifr-bonn.mpg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtomitsu.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtompeg.1 b/upstream/mageia-cauldron/man1/ppmtompeg.1
new file mode 100644
index 00000000..6f4bfc57
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtompeg.1
@@ -0,0 +1,1213 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtompeg User Manual" 0 "23 July 2006" "netpbm documentation"
+
+.SH NAME
+ppmtompeg - encode an MPEG-1 bitstream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtompeg\fP
+[\fIoptions\fP]
+\fIparameter-file\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtompeg\fP produces an MPEG-1 video stream.  MPEG-1 is the
+first great video compression method, and is what is used in Video CDs
+(VCD).  \fBppmtompeg\fP originated in the year 1995.  DVD uses a more
+advanced method, MPEG-2.  There is an even newer method called MPEG-4
+which is also called Divx.  I don't know where one finds that used.
+.PP
+There's technically a difference between a compression method for
+video and an actual file (stream) format for a movie, and I don't know
+if it can be validly said that the format of the stream
+\fBppmtompeg\fP produces is MPEG-1.
+.PP
+Mencoder from the 
+.UR http://www.mplayerhq.hu
+Mplayer package
+.UE
+\& is probably superior for most video format generation
+needs, if for no other reason than that it is more popular.
+.PP
+The programming library 
+.UR http://pm2v.free.fr
+\fBPM2V\fP
+.UE
+\&
+generates MPEG-2 streams.
+.PP
+Use 
+.UR http://www.mplayerhq.hu
+Mplayer
+.UE
+\& (not part of Netpbm)
+to do the reverse conversion: to create a series of PNM files from an MPEG
+stream.
+.PP
+\fIparam_file\fP is a parameter file which includes a list of
+input files and other parameters.  The file is described in detail
+below.
+.PP
+To understand this program, you need to understand something about
+the complex MPEG-1 format.  One source of information about this
+standard format is the section Introduction to MPEG in the 
+.UR http://www.faqs.org/faqs/compression-faq/
+Compression FAQ
+.UE
+\&.
+
+.UN options
+.SH OPTIONS
+.PP
+The \fB-gop\fP, \fB-combine_gops\fP, \fB-frames\fP, and
+\fB-combine_frames\fP options are all mutually exclusive.
+
+
+.TP
+\fB-stat stat_file\fP
+This option causes \fBppmtompeg\fP to append the statistics that
+it write to Standard Output to the file \fIstat_file\fP as well.  The
+statistics use the following abbreviations: bits per block (bpb), bits
+per frame (bpf), seconds per frame (spf), and bits per second (bps).
+.sp
+These statistics include how many I, P, and B frames there were,
+and information about compression and quality.
+
+
+.TP
+\fB-quiet\fP \fInum_seconds\fP
+ causes \fBppmtompeg\fP not to report remaining time more often
+than every \fInum_seconds\fP seconds (unless the time estimate rises,
+which will happen near the beginning of the run).  A negative value
+tells \fBppmtompeg\fP not to report at all.  0 is the default
+(reports once after each frame).  Note that the time remaining is an
+estimate and does not take into account time to read in frames.
+
+.TP
+\fB-realquiet\fP 
+ causes \fBppmtompeg\fP to run silently,
+with the only screen output being errors.  Particularly useful when
+reading input from stdin.  The equivalent of the \fB-quiet\fP
+common option of most other Netpbm programs.
+
+.TP
+
+\fB-no_frame_summary\fP
+ This option prevents \fBppmtompeg\fP from printing a summary
+line for each frame
+
+.TP
+\fB-float_dct\fP
+ forces \fBppmtompeg\fP to use a more accurate, yet more
+computationally expensive version of the DCT.
+
+.TP
+\fB-gop\fP \fIgop_num\fP
+causes \fBppmtompeg\fP to encode only the numbered GOP (first GOP is 0).  The
+parameter file is the same as for normal usage.  The output file will be
+the normal output file with the suffix \fB.gop.\fP\fIgop_num\fP.
+\fBppmtompeg\fP does not output any sequence information.
+
+.TP
+\fB-combine_gops\fP
+ causes \fBppmtompeg\fP simply to combine some GOP files into a
+single MPEG output stream.  \fBppmtompeg\fP inserts a sequence header
+and trailer.  In this case, the parameter file needs only to contain 
+the SIZE value, an output file, and perhaps a list of input GOP
+files (see below).
+
+If you don't supply a list of input GOP files is used, then
+\fBppmtompeg\fP assumes you're using the same parameter file you used
+when you created the input (with the \fB-gop\fP option) and
+calculates the corresponding gop filenames itself.  If this is not the
+case, you can specify input GOP files in the same manner as normal
+input files -- except instead of using INPUT_DIR, INPUT, and
+END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT.  If no
+input GOP files are specified, then the default is to use the output
+file name with suffix \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP
+starting from 0, as the input files.
+.sp
+Thus, unless you're mixing and matching GOP files from different
+sources, you can simply use the same parameter file for creating the
+GOP files (\fB-gop\fP) and for later turning them into an MPEG stream
+(\fB-combine_gops\fP).
+     
+
+.TP
+\fB-frames \fIfirst_frame\fP \fIlast_frame\fP\fP
+This option causes \fBppmtompeg\fP to encode only the frames numbered
+\fIfirst_frame\fP to \fIlast_frame\fP, inclusive.  The parameter
+file is the same as for normal usage.  The output will be placed in
+separate files, one per frame, with the file names being the normal
+output file name with the suffix \fB.frame.\fP\fIframe_num\fP.  No
+GOP header information is output.  (Thus, the parameter file need not
+include the GOP_SIZE value)
+.sp
+Use \fBppmtompeg -combine_frames\fP to combine these frames later into
+an MPEG stream.
+
+
+.TP
+\fB-combine_frames\fP
+ This option causes \fBppmtompeg\fP simply to combine some
+individual MPEG frames (such as you might have created with an earlier
+run of \fBppmtompeg -frames\fP) into a single MPEG stream.  Sequence
+and GOP headers are inserted appropriately.  In this case, the
+parameter file needs to contain only the SIZE value, the GOP_SIZE
+value, an output file, and perhaps a list of frame files (see below).
+.sp
+The parameter file may specify input frame files in the same manner
+as normal input files -- except instead of using INPUT_DIR, INPUT, and
+END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT. If
+no input frame files are specified, then the default is to use the
+output file name with suffix \fB.frame.\fP\fIframe_num\fP, with
+\fIframe_num\fP starting from 0, as the input files.
+     
+
+
+.TP
+\fB-nice\fP
+This option causes \fBppmtompeg\fP to run any remote processes
+"nicely," i.e.  at low priority.  (This is relevant only if you are
+running \fBppmtompeg\fP in parallel mode.  Otherwise, there are no
+remote processes).  See 'man nice.'
+
+.TP
+\fB-max_machines \fInum_machines\fP\fP
+This option causes \fBppmtompeg\fP to use no more than
+\fInum_machines\fP machines as slaves for use in parallel encoding.
+
+.TP
+\fB-snr\fP 
+This option causes \fBppmtompeg\fP to include the signal-to-noise
+ratio in the reported statistics.  Prints SNR (Y U V) and peak SNR (Y
+U V) for each frame.  In summary, prints averages of luminance only
+(Y).  SNR is defined as 10*log(variance of original/variance of
+error).  Peak SNR is defined as 20*log(255/RMSE).  Note that
+\fBppmtompeg\fP runs a little slower when you use this option.
+
+.TP
+\fB-mse\fP
+This option causes \fBppmtompeg\fP to report the mean squared
+error per block.  It also automatically reports the quality of the
+images, so there is no need to specify \fB-snr\fP then.
+
+.TP
+\fB-bit_rate_info\fP \fIrate_file\fP
+ This option makes \fBppmtompeg\fP write bit rate information
+into the file \fIrate_file\fP.  Bit rate information is bits per frame, and
+also bits per I-frame-to-I-frame.
+
+.TP
+\fB-mv_histogram\fP 
+ This option causes \fBppmtompeg\fP to print a histogram of the
+motion vectors as part of statistics.  There are three histograms --
+one for P frame, one for forward B frame, and one for backward B frame
+motion vectors.
+.sp
+The output is in the form of a matrix, each entry corresponding to one
+motion vector in the search window. The center of the matrix
+represents (0,0) motion vectors.
+
+.TP
+\fB-debug_sockets\fP
+This option causes \fBppmtompeg\fP to print to Standard Output
+messages that narrate the communication between the machines when you run
+\fBppmtompeg\fP in 
+.UR #parallel
+parallel mode
+.UE
+\&.
+
+.TP
+\fB-debug_machines\fP
+This option causes \fBppmtompeg\fP to print to Standard Output
+messages that narrate the progress of the conversion on the various
+machines when you run \fBppmtompeg\fP in 
+.UR #parallel
+parallel mode
+.UE
+\&.
+     
+
+
+.UN parmfile
+.SH PARAMETER FILE
+.PP
+The parameter file \fBmust\fP contain the following
+lines (except when using the \fB-combine_gops\fP or \fB-combine_frames\fP
+options):
+
+
+
+.TP
+\fBPATTERN\fP \fIpattern\fP
+This statement specifies the pattern (sequence) of I frames, P frames,
+and B frames.  \fIpattern\fP is just a sequence of the letters I, P, and
+B with nothing between.  Example:
+
+.nf
+    PATTERN IBBPBBPBBPBBPBB
+</pre>
+.sp
+See 
+.UR #ipb
+I Frames, P Frames, B Frames
+.UE
+\&.
+
+.TP
+\fBOUTPUT\fP \fIoutput file\fP
+This names the file where the output MPEG stream goes.
+     
+.TP
+\fBINPUT_DIR\fP \fIdirectory\fP
+This statement tells where the input images (frames) come from.
+If each frame is in a separate file, \fIdirectory\fP is the directory
+where they all are.  You may use \fB.\fP to refer to the current 
+directory.  A null \fIdirectory\fP refers to the root directory of the
+system file tree.
+.sp
+To have \fBppmtompeg\fP read all the frames serially from Standard 
+Input, specify
+.nf
+    INPUT_DIR stdin
+
+.fi
+
+.TP
+\fBINPUT\fP
+This line must be followed by a list of the input files (in display order)
+and then the line \fBEND_INPUT\fP.
+.sp
+There are three types of lines between INPUT and END_INPUT.  First,
+a line may simply be the name of an input file.  Second, the line
+may be of the form \fIsingle_star_expr\fP
+\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB]\fP.
+\fIsingle_star_expr\fP can have a single \fB*\fP in it.  It is
+replaced by all the numbers between x and y inclusive.  So, for
+example, the line \fBtennis*.ppm [12-15]\fP refers to the files
+tennis12.ppm, tennis13.ppm, tennis14.ppm, tennis15.ppm.
+.sp
+Uniform zero-padding occurs, as well.  For example, the line
+\fBfootball.*.ppm [001-130]\fP refers to the files football.001.ppm,
+football.002.ppm, ..., football.009.ppm, football.010.ppm, ...,
+football.130.ppm.
+.sp
+The third type of line is: \fIsingle_star_expr\fP
+\fB[\fP\fIx\fP\fB-\fP\fIy\fP\fB+\fP\fIs\fP\fB]\fP, where the
+line is treated exactly as above, except that we skip by \fIs\fP.  Thus, the
+line \fBfootball.*.ppm [001-130+4]\fP refers to the files
+football.001.ppm, football.005.ppm, football.009.ppm,
+football.013.ppm, etc.
+.sp
+Furthermore, a line may specify a shell command to execute to
+generate lines to be interpreted as described above, as if those lines
+were in the parameter file instead.  Use back ticks, like in the
+Bourne Shell, like this:
+
+.nf
+    `cat myfilelist`
+
+.fi
+.sp
+If input is from Standard Input (per the \fBINPUT_DIR\fP statement), 
+\fBppmtompeg\fP ignores the \fBINPUT\fP/\fBEND_INPUT\fP block, but
+it still must be present.
+     
+.TP
+\fBBASE_FILE_FORMAT\fP {\fBPPM\fP | \fBPNM\fP | \fBYUV\fP | 
+     \fBJPEG\fP | \fBJMOVIE\fP}
+\fBppmtompeg\fP must convert all input files to one of the
+following formats as a first step of processing: PNM, YUV, JPEG(v4),
+or JMOVIE.  (The conversion may be trivial if your input files are
+already in one of these formats).  This line specifies which of the
+four formats.  PPM is actually a subset of PNM.  The separate
+specification is allowed for backward compatibility.  Use PNM instead
+of PPM in new applications.
+
+.TP
+\fBINPUT_CONVERT\fP \fIconversion_command\fP
+You must specify how to convert a file to the base file format.
+If no conversion is necessary, then you would just say:
+
+.nf
+     INPUT_CONVERT *
+
+.fi
+.sp
+Otherwise, \fIconversion_command\fP is a shell command that causes
+an image in the format your specified with \fBBASE_FILE_FORMAT\fP to
+be written to Standard Output.  \fBppmtompeg\fP executes the command
+once for each line between \fBINPUT\fP and \fBEND_INPUT\fP (which is
+normally, but not necessarily, a file name).  In the conversion
+command, \fBppmtompeg\fP replaces each '*' with the contents of that
+line.
+     
+     If you had a bunch of gif files, you might say:
+.nf
+     INPUT_CONVERT giftopnm *
+
+.fi
+
+     If you have a bunch of separate a.Y, a.U, and a.V files (where
+     the U and V have already been subsampled), then you might say:
+
+.nf
+     INPUT_CONVERT cat *.Y *.U *.V
+
+.fi
+.sp
+Input conversion is not allowed with input from stdin, so use
+
+.nf
+     INPUT_CONVERT *
+
+.fi
+
+as described above.
+     
+.TP
+\fBSIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP
+.sp
+\fIwidth\fP and \fIheight\fP are the width and height of each
+frame in pixels.
+.sp
+When \fBppmtompeg\fP can get this information from the input image
+files, it ignores the \fBSIZE\fP parameter and you may omit it.
+.sp
+When the image files are in YUV format, the files don't contain
+dimension information, so \fBSIZE\fP is required.
+.sp
+When \fBppmtompeg\fP is running in parallel mode, not all of the
+processes in the network have access to the image files, so
+\fBSIZE\fP is required and must give the same dimensions as the
+input image files.
+
+.TP
+\fBYUV_SIZE\fP \fIwidth\fP\fBx\fP\fIheight\fP
+This is an obsolete synonym of \fBSIZE\fP.
+
+.TP
+\fBYUV_FORMAT\fP {\fBABEKAS\fP | \fBPHILLIPS\fP | \fBUCB\fP |
+                      \fBEYUV\fP | \fIpattern\fP}
+This is meaningful only when \fBBASE_FILE_FORMAT\fP specifies
+YUV format, and then it is required.  It specifies the sub-format of
+the YUV class.
+
+
+.TP
+\fBGOP_SIZE\fP \fIn\fP
+\fIn\fP is the number of frames in a Group of Pictures.  Except that
+because a GOP must start with an I frame, \fBppmtompeg\fP makes a GOP as
+much longer than \fIn\fP as it has to to make the next GOP start with an
+I frame.
+.sp
+Normally, it makes sense to make your GOP size a multiple of your
+pattern length (the latter is determined by the PATTERN parameter file
+statement).
+.sp
+See 
+.UR #gop
+Group Of Pictures
+.UE
+\&.
+
+.TP
+\fBSLICES_PER_FRAME\fP \fIn\fP
+\fIn\fP is roughly the number of slices per frame.  Note, at
+least one MPEG player may complain if slices do not start at the left
+side of an image.  To ensure this does not happen, make sure the
+number of rows is divisible by SLICES_PER_FRAME.
+
+.TP
+\fBPIXEL\fP {\fBFULL\fP | \fBHALF\fP} 
+use half-pixel motion vectors, or just full-pixel ones It is
+usually important that you use half-pixel motion vectors, because it
+results in both better quality and better compression.
+     
+
+.TP
+\fBRANGE\fP \fIn\fP
+Use a search range of \fIn\fP pixels in each of the four directions
+from a subject pixel.  (So the search window is a square \fIn\fP*2 pixels
+on a side).
+
+.TP
+\fBPSEARCH_ALG\fP {\fBEXHAUSTIVE\fP | \fBTWOLEVEL\fP |
+     \fBSUBSAMPLE\fP | \fBLOGARITHMIC\fP}
+This statement tells \fBppmtompeg\fP what kind of search
+    technique (algorithm) to use for P frames.  You select the desired
+    combination of speed and compression.  \fBEXHAUSTIVE\fP gives the
+    best compression, but \fBLOGARITHMIC\fP is the fastest.
+    \fBTWOLEVEL\fP is an exhaustive full-pixel search, followed by a
+    local half- pixel search around the best full-pixel vector (the
+    PIXEL option is ignored for this search technique).
+
+.TP
+\fBBSEARCH_ALG\fP {\fBSIMPLE\fP | \fBCROSS2\fP | \fBEXHAUSTIVE\fP}
+This statement tells \fBppmtompeg\fP what kind of search
+    technique (algorithm) to use for B frames.  \fBSIMPLE\fP means
+    find best forward and backward vectors, then interpolate.
+    \fBCROSS2\fP means find those two vectors, then see what backward
+    vector best matches the best forward vector, and vice versa.
+    \fBEXHAUSTIVE\fP does an n-squared search and is
+    \fIextremely\fP slow in relation to the others (\fBCROSS2\fP
+    is about half as fast as \fBSIMPLE\fP).
+
+.TP
+\fBIQSCALE\fP \fIn\fP
+Use \fIn\fP as the qscale for I frames.
+     See 
+.UR #qscale
+Qscale
+.UE
+\&.
+
+.TP
+\fBPQSCALE\fP \fIn\fP
+Use \fIn\fP as the qscale for P frames.
+     See 
+.UR #qscale
+Qscale
+.UE
+\&.
+
+.TP
+\fBBQSCALE\fP \fIn\fP
+Use \fIn\fP as the qscale for B frames.
+     See 
+.UR #qscale
+Qscale
+.UE
+\&.
+
+.TP
+\fBREFERENCE_FRAME\fP {\fBORIGINAL\fP | \fBDECODED\fP} 
+This
+statement determines whether \fBppmtompeg\fP uses the original images
+or the decoded images when computing motion vectors.  Using decoded
+images is more accurate and should increase the playback quality of
+the output, but it makes the encoding take longer and seems to give
+worse compression.  It also causes some complications with parallel
+encoding. (see the section on parallel encoding).  One thing you can
+do as a trade-off is select \fBORIGINAL\fP here, and lower the
+qscale (see \fBQSCALE\fP if the quality is not good enough.
+
+.B Original or Decoded? (Normalized)
+.TS
+r c c c c c.
+_
+Reference	Compression	Speed	Quality I	Quality P	Quality B
+Decoded	1000	1000	1000	969	919
+Original	885	1373	1000	912	884
+.TE
+
+
+
+
+     
+.PP
+The following lines are optional:
+
+
+
+.TP
+\fBFORCE_ENCODE_LAST_FRAME\fP
+This statement is obsolete.  It does nothing.
+.sp
+Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP would drop
+trailing B frames from your movie, since a movie can't end with a B
+frame.  (See 
+.UR #ipb
+I Frames, P Frames, B Frames
+.UE
+\&.)
+You would have to specify \fBFORCE_ENCODE_LAST_FRAME\fP to stop
+that from happening and get the same function that \fBppmtompeg\fP
+has today.
+
+
+.TP
+\fBNIQTABLE\fP
+This statement specifies a custom non-intra quantization table.
+If you don't specify this statement, \fBppmtompeg\fP uses a default
+non-intra quantization table.
+.sp
+The 8 lines immediately following \fBNIQTABLE\fP specify the quantization
+table.  Each line defines a table row and consists of 8 integers,
+whitespace-delimited, which define the table columns.
+
+.TP
+\fBIQTABLE\fP
+This is analogous to NIQTABLE, but for the intra quantization table.
+
+.TP
+\fBASPECT_RATIO\fP \fIratio\fP
+This statement specifies the aspect ratio for \fBppmtompeg\fP to
+specify in the MPEG output.  I'm not sure what this is used for.
+.sp
+\fIratio\fP must be 1.0, 0.6735, 0.7031, 0.7615, 0.8055, 0.8437,
+0.8935, 0.9157, 0.9815, 1.0255, 1.0695, 1.0950, 1.1575, or 1.2015.
+
+.TP
+\fBFRAME_RATE\fP \fIrate\fP
+This specifies the frame rate for \fBppmtompeg\fP to specify in the
+MPEG output.  Some players use this value to determine the playback rate.
+.sp
+\fIrate\fP must be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60.
+
+.TP
+\fBBIT_RATE\fP \fIrate\fP
+This specifies the bit rate for Constant Bit Rate (CBR) encoding.
+.sp
+\fIrate\fP must be an integer.
+
+.TP
+\fBBUFFER_SIZE\fP \fIsize\fP 
+This specifies the value
+\fBppmtompeg\fP is to specify in the MPEG output for the Video
+Buffering Verifier (VBV) buffer size needed to decode the sequence.
+.sp
+A Video Verifying Buffer is a buffer in which a decoder keeps the
+decoded bits in order to match the uneven speed of the decoding with
+the required constant playback speed.
+.sp
+As \fBppmtompeg\fP encodes the image, it simulates the decoding
+process in terms of how many bits would be in the VBV as each frame gets
+decoded, assuming a VBV of the size you indicate.
+.sp
+If you specify the \fBWARN_VBV_UNDERFLOW\fP statement,
+\fBppmtompeg\fP issues a warning each time the simulation underflows
+the buffer, which suggests that an underflow would occur on playback,
+which suggests the buffer is too small.
+.sp
+If you specify the \fBWARN_VBV_OVERFLOW\fP statement,
+\fBppmtompeg\fP issues a warning each time the simulation overflows
+the buffer, which suggests that an overflow would occur on playback,
+which suggests the buffer is too small.
+
+.TP
+\fBWARN_VBV_UNDERFLOW\fP
+.TP
+\fBWARN_VBV_OVERFLOW\fP
+See \fBBUFFER_SIZE\fP.
+.sp
+These options were new in Netpbm 10.26 (January 2005).  Before that,
+\fBppmtompeg\fP issued the warnings always.
+
+
+
+
+The following statements apply only to parallel operation:
+
+ 
+
+.TP
+\fBPARALLEL\fP
+This statement, paired with \fBEND PARALLEL\fP, is what causes
+\fBppmtompeg\fP to operate in parallel mode.  See 
+.UR #parallel
+Parallel Operation
+.UE
+\&.
+
+.TP
+\fBEND PARALLEL\fP
+This goes with \fBPARALLEL\fP.
+
+.TP
+\fBPARALLEL_TEST_FRAMES\fP \fIn\fP 
+The master starts off by measuring each slave's speed.  It does
+this by giving each slave \fIn\fP frames to encode and noting how
+long the slave takes to finish.  These are not just test frames,
+though -- they're real frames and the results become part of the
+output.
+\fBppmtompeg\fP is old and measures time in undivided seconds, so
+to get useful timings, specify enough frames that it will take at
+least 5 seconds to process them.  The default is 10.
+.sp
+If you specify \fBFORCE_I_ALIGN\fP, \fBppmtompeg\fP will increase
+the test frames value enough to maintain the alignment.
+.sp
+If there aren't enough frames for every slave to have the indicated
+number of test frames, \fBppmtompeg\fP will give some slaves fewer.
+
+
+.TP
+\fBPARALLEL_TIME_CHUNKS\fP \fIt\fP
+When you specify this statement, the master attempts to feed work
+to the slaves in chunks that take \fIt\fP seconds to process.  It uses
+the speed measurement it made when it started up (see PARALLEL_TEST_FRAMES)
+to decide how many frames to put in the chunk.  This statement obviously
+doesn't affect the first batch of work sent to each slave, which is the
+one used to measure the slave's speed.
+.sp
+Smaller values of \fIt\fP increase communication, but improve load
+balancing.  The default is 30 seconds.
+.sp
+You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,
+and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
+
+.TP
+\fBPARALLEL_CHUNK_TAPER\fP
+When you specify this statement, the master distributes work like
+with PARALLEL_TIME_CHUNKS, except that the master chooses the number
+of seconds for the chunks.  It starts with a large number and, as it
+gets closer to finishing the job, reduces it.  That way, it reduces
+scheduling overhead when precise scheduling isn't helpful, but still
+prevents a slave from finishing early after all the work has already
+been handed out to the other slaves, and then sitting idle while
+there's still work to do.
+.sp
+You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,
+and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
+
+
+.TP
+\fBPARALLEL_PERFECT\fP
+If this statement is present, \fBppmtompeg\fP schedules on the
+assumption that each machine is about the same speed.  The master will
+simply divide up the frames evenly between the slaves -- each
+slave gets the same number of frames.  If some slaves are faster than
+others, they will finish first and remain idle while the slower slaves
+continue.
+.sp
+This has the advantage of minimal scheduling overhead.  Where slaves
+have different speeds, though, it makes inefficient use of the fast
+ones.  Where slaves are the same speed, it also has the disadvantage
+that they all finish at the same time and feed their output to the
+single Combine Server in a burst, which makes less efficient use of
+the Combine Server and thus can increase the total elapsed time.
+.sp
+You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,
+and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
+
+.TP
+\fBRSH\fP \fIremote_shell_command\fP
+\fBppmtompeg\fP executes the shell command
+\fIremote_shell_command\fP to start a process on another machine.
+The default command is \fBrsh\fP, and whatever command you specify
+must have compatible semantics.  \fBssh\fP is usually compatible.
+The command \fBppmtompeg\fP uses is one like this:
+\fBssh remote.host.com -l username shellcommand\fP.
+.sp
+Be sure to set up \fB.rhosts\fP files or SSH key authorizations
+where needed.  Otherwise, you'll have to type in passwords.
+.sp
+On some HP machines, \fBrsh\fP is the restricted shell, and you want
+to specify \fBremsh\fP.
+
+.TP
+\fBFORCE_I_ALIGN\fP
+This statement forces each slave to encode a chunk of frames which
+is a multiple of the pattern length (see \fBPATTERN\fP).  Since the
+first frame in any pattern is an I frame, this forces each chunk
+encoded by a slave to begin with an I frame.
+.sp
+This document used to say there was an argument to
+\fBFORCE_I_ALIGN\fP which was the number of frames \fBppmtompeg\fP
+would use (and was required to be a multiple of the pattern length).
+But \fBppmtompeg\fP has apparently always ignored that argument, and
+it does now.
+
+.TP
+\fBKEEP_TEMP_FILES\fP
+This statement causes \fBppmtompeg\fP not to delete the temporary
+files it uses to transmit encoded frames to the combine server.  This
+means you will be left with a file for each frame, the same as you
+would get with the \fB-frames\fP option.
+.sp
+This is mostly useful for debugging.
+.sp
+This works only if you're using a shared filesystem to communicate
+between the servers.
+.sp
+This option was new in Netpbm 10.26 (January 2005).
+
+
+
+
+.UN parameterfile
+.SS Parameter File Notes
+.PP
+ If you use the \fB-combine_gops\fP option, then you need to specify
+only the SIZE and OUTPUT values in the parameter file.  In
+addition, the parameter file may specify input GOP files in the same
+manner as normal input files -- except instead of using INPUT_DIR,
+INPUT, and END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT.
+If you specify no input GOP files, then \fBppmtompeg\fP uses by default the
+output file name with suffix \fB.gop.\fP\fIgop_num\fP, with \fIgop_num\fP
+starting from 0, as the input files. 
+.PP
+If you use the \fB-combine_frames\fP option, then you need to
+specify only the SIZE, GOP_SIZE, and OUTPUT values in the
+parameter file.  In addition, the parameter file may specify input
+frame files in the same manner as normal input files -- except instead
+of using INPUT_DIR, INPUT, and END_INPUT, use FRAME_INPUT_DIR,
+FRAME_INPUT, and FRAME_END_INPUT.  If no input frame files are
+specified, then the default is to use the output file name with suffix
+\fB.frame.\fP\fIframe_num\fP, with \fIframe_num\fP starting from 0,
+as the input files.
+.PP
+Any number of spaces and tabs may come between each option and value.  Lines
+beginning with \fB#\fP are ignored.  Any other lines are ignored except for
+those between INPUT and END_INPUT.  This allows you to use the same
+parameter file for normal usage and for \fB-combine_gops\fP and
+\fB-combine_frames\fP.
+.PP
+The file format is case-sensitive so all keywords should be in
+upper case.
+.PP
+The statements may appear in any order, except that the order within
+a block statement (such as INPUT ... END INPUT) is significant.
+.PP
+\fBppmtompeg\fP is prepared to handle up to 16 B frames between
+reference frames when encoding with input from stdin.  (To build a
+modified \fBppmtompeg\fP with a higher limit, change the constant
+B_FRAME_RUN in frame.c and recompile).
+
+.UN general
+.SH GENERAL USAGE INFORMATION
+
+.UN qscale
+.SS Qscale
+.PP
+The quantization scale values (qscale) give a trade-off between
+quality and compression.  Using different Qscale values has very little
+effect on speed.  The qscale values can be set separately for I, P, and
+B frames.
+.PP
+You select the qscale values with the \fBIQSCALE\fP,
+\fBPQSCALE\fP, and \fBBSCALE\fP parameter file statements.
+.PP
+A qscale value is an integer from 1 to 31.  Larger numbers give
+better compression, but worse quality.  In the following, the quality
+numbers are peak signal-to-noise ratio, defined as:
+.B signal-to-noise formula
+.IMG -C ppmtompeg-snr.gif
+where MSE is the mean squared error.
+     
+.PP
+Flower garden tests:
+
+.B Qscale vs Quality
+.TS
+r r r r.
+_
+Qscale	I Frames	P Frames	B Frames
+1	43.2	46.3	46.5
+6	32.6	34.6	34.3
+11	28.6	29.5	30.0
+16	26.3	26.8	28.6
+21	24.7	25.0	27.9
+26	23.5	23.9	27.5
+31	22.6	23.0	27.3
+.TE
+
+.B Qscale vs Compression
+.TS
+r r r r.
+_
+Qscale	I Frames	P Frames	B Frames
+1	2	2	2
+6	7	10	15
+11	11	18	43
+16	15	29	97
+21	19	41	173
+26	24	56	256
+31	28	73	330
+.TE
+
+
+.UN searchtech
+.SS Search Techniques
+     
+.PP
+There are several different motion vector search techniques
+available.  There are different techniques available for P frame
+search and B frame search. Using different search techniques present
+little difference in quality, but a large difference in compression
+and speed.
+     
+.PP
+There are 4 types of P frame search: Exhaustive, TwoLevel,
+SubSample, and Logarithmic.
+     
+.PP
+There are 3 types of B frame search: Exhaustive, Cross2, and
+Simple.
+     
+The recommended search techniques are TwoLevel and Logarithmic for
+P frame search, and Cross2 and Simple for B frame search. Here are
+some numbers comparing the different search methods:
+     
+.B P frame Motion Vector Search (Normalized)
+.TS
+r c c c.
+_
+Technique	T{
+Compression
+.UR #smallbetter
+\u1\d
+.UE
+T}	T{
+Speed      
+.UR #largefaster
+\u2\d
+.UE
+T}	T{
+Quality    
+.UR #largebetter
+\u3\d
+.UE
+T}
+Exhaustive	1000	1000	1000
+SubSample	1008	2456	1000
+TwoLevel	1009	3237	1000
+Logarithmic	1085	8229	998
+.TE
+
+.B B frame Motion Vector Search (Normalized)
+.TS
+r c c c.
+_
+Technique	T{
+Compression
+.UR #smallbetter
+\u1\d
+.UE
+T}	T{
+Speed
+.UR #largefaster
+\u2\d
+.UE
+T}	T{
+Quality
+.UR #largebetter
+\u3\d
+.UE
+T}
+Exhaustive	1000	1000	1000
+Cross2	975	1000	996
+Simple	938	1765	991
+.TE
+
+.UN smallbetter
+\u1\dSmaller numbers are better
+compression.
+
+.UN largefaster
+\u2\dLarger numbers mean faster
+execution.
+
+.UN largebetter
+\u3\dLarger numbers mean better quality.
+.PP
+For some reason, Simple seems to give better compression, but it
+depends on the image sequence.
+.PP
+Select the search techniques with the \fBPSEARCH_ALG\fP and
+\fBBSEARCH_ALG\fP parameter file statements.
+
+
+.UN gop
+.SS Group Of Pictures (GOP)
+.PP
+A Group of Pictures (GOP) is a roughly independently decodable
+sequence of frames.  An MPEG video stream is made of one or more
+GOP's.  You may specify how many frames should be in each GOP with the
+\fBGOP_SIZE\fP parameter file statement.  A GOP always starts with an
+I frame.
+.PP
+Instead of encoding an entire sequence, you can encode a single
+GOP.  To do this, use the \fB-gop\fP command option.  You can later
+join the resulting GOP files at any time by running \fBppmtompeg\fP
+with the \fB-combine_gops\fP command option.
+     
+     
+.UN slices
+.SS Slices
+.PP
+A slice is an independently decodable unit in a frame.  It can be
+as small as one macroblock, or it can be as big as the entire frame.
+Barring transmission error, adding slices does not change quality or
+speed; the only effect is slightly worse compression.  More slices are
+used for noisy transmission so that errors are more recoverable. Since
+usually errors are not such a problem, we usually just use one slice
+per frame.
+     
+.PP
+Control the slice size with the \fBSLICES_PER_FRAME\fP parameter
+file statement.
+.PP
+Some MPEG playback systems require that each slice consist of whole
+rows of macroblocks.  If you are encoding for this kind of player, if
+the height of the image is H pixels, then you should set the
+SLICES_PER_FRAME to some number which divides H/16.  For example, if
+the image is 240 pixels (15 macroblocks) high, then you should use
+only 15, 5, 3, or 1 slices per frame.
+     
+.PP
+Note: these MPEG playback systems are really wrong, since the MPEG
+standard says this doesn't have to be so.
+
+
+
+.UN searchwindow
+.SS Search Window
+     
+.PP
+The search window is the window in which \fBppmtompeg\fP searches
+for motion vectors.  The window is a square.  You can specify the size
+of the square, and whether to allow half-pixel motion vectors or not,
+with the \fBRANGE\fP and \fBPIXEL\fP parameter file statements.
+
+.UN ipb
+.SS I Frames, P Frames, B Frames
+.PP
+In MPEG-1, a movie is represented as a sequence of MPEG frames,
+each of which is an I Frame, a P Frame, or a B Frame.  Each represents
+an actual frame of the movie (don't get confused by the dual use of
+the word "frame."  A movie frame is a graphical image.  An MPEG frame
+is a set of data that describes a movie frame).
+.PP
+An I frame ("intra" frame) describes a movie frame in isolation --
+without respect to any other frame in the movie.  A P frame
+("predictive" frame) describes a movie frame by describing how it
+differs from the movie frame described by the latest preceding I  or
+P frame.  A B frame ("bidirectional" frame) describes a movie frame by
+describing how it differs from the movie frames described by the
+nearest I or P frame before \fIand\fP after it.
+.PP
+Note that the first frame of a movie must be described by an I
+frame (because there is no previous movie frame) and the last movie
+frame must be described by an I or P frame (because there is no
+subsequent movie frame).
+.PP
+Beyond that, you can choose which frames are represented by which
+types.  You specify a pattern, such as IBPBP and \fBppmtompeg\fP
+simply repeats it over and over throughout the movie.  The pattern
+affects speed, quality, and stream size.  Here is a chart which shows
+some of the trade-offs:
+
+.B Comparison of I/P/B Frames (Normalized)
+.TS
+r c c c.
+_
+Frame Type	Size	Speed	Quality
+I frames	1000	1000	1000
+P frames	409	609	969
+B frames	72	260	919
+.TE
+
+(this is with constant qscale)
+     
+.PP
+A standard sequence is IBBPBBPBBPBBPBB.
+     
+.PP
+Select the sequence with the \fBPATTERN\fP parameter file statement.
+.PP
+Since the last MPEG frame cannot be a B frame (see above), if the
+pattern you specify indicates a B frame for the last movie frame of
+the movie, \fBppmtompeg\fP makes it an I frame instead.
+.PP
+Before Netpbm 10.26 (January 2005), \fBppmtompeg\fP instead drops
+the trailing B frames by default, and you need the
+\fBFORCE_ENCODE_LAST_FRAME\fP parameter file statement to make it do
+this.
+.PP
+The MPEG frames don't appear in the MPEG-1 stream in the same order that
+the corresponding movie frames appear in the movie -- the B frames come after
+the I and P frames on which they are based.  For example, if the movie is
+4 frames that you will represent with the pattern IBBP, the MPEG-1 stream
+will start with an I frame describing movie frame 0.  The next frame in
+the MPEG-1 stream is a P frame describing movie frame 3.  The last two
+frames in the MPEG-1 stream are B frames describing movie frames 1 and 2,
+respectively.
+
+
+.UN iofiles
+.SS Specifying Input and Output Files 
+.PP
+Specify the input frame images with the \fBINPUT_DIR\fP,
+\fBINPUT\fP, \fBEND_INPUT\fP, \fBBASE_FILE_FORMAT\fP,
+\fBSIZE\fP, \fBYUV_FORMAT\fP and \fBINPUT_CONVERT\fP parameter
+file statements.
+.PP
+Specify the output file with the \fBOUTPUT\fP parameter file statement.
+
+
+.UN statistics
+.SS Statistics
+.PP
+\fBppmtompeg\fP can generate a variety of statistics about the 
+encoding.  See the \fB-stat\fP, \fB-snr\fP, \fB-mv_histogram\fP,
+\fB-quiet\fP, \fB-no_frame_summary\fP, and \fB-bit_rate_info\fP
+options.
+     
+
+.UN parallel
+.SH PARALLEL OPERATION
+.PP
+You can run \fBppmtompeg\fP on multiple machines at once, encoding
+the same MPEG stream.  When you do, the machines are used as shown in
+the following diagram.  We call this "parallel mode."
+.PP
+.B ppmtompeg-par.gif
+.IMG -C ppmtompeg-par.gif
+.PP
+To do parallel processing, put the statement
+
+.nf
+    PARALLEL
+
+.fi
+
+in the parameter file, followed by a listing of the machines, one
+machine per line, then
+
+.nf
+    END_PARALLEL
+
+.fi
+
+Each of the machine lines must be in one of two forms.  If the machine
+has filesystem access to the input files, then the line is:
+.PP
+\fImachine\fP \fIuser\fP \fIexecutable\fP
+.PP
+The executable is normally \fBppmtompeg\fP (you may need to give
+the complete path if you've built for different architectures).  If
+the machine does not have filesystem access to the input files, the line
+is:
+.PP
+\fBREMOTE\fP \fImachine\fP \fIuser\fP \fIexecutable\fP
+\fIparameter file\fP
+.PP
+The \fB-max_machines\fP command option limits the number of
+machines \fBppmtompeg\fP will use.  If you specify more machines in
+the parameter file than \fB-max_machines\fP allows, \fBppmtompeg\fP
+uses only the machines listed first.  This is handy if you want to
+experiment with different amounts of parallelism.
+.PP
+In general, you should use full path file names when describing
+executables and parameter files.  This \fIincludes\fP the parameter
+file argument on the original invocation of \fBppmtompeg\fP.
+.PP
+All file names must be the same on all systems (so if e.g. you're
+using an NFS filesystem, you must make sure it is mounted at the same
+mountpoint on all systems).
+.PP
+Because not all of the processes involved in parallel operation
+have easy access to the input files, you must specify the \fBSIZE\fP
+parameter file statement when you do parallel operation.
+.PP
+The machine on which you originally invoke \fBppmtompeg\fP is the
+master machine.  It hosts a "combine server,", a
+"decode server," and a number of "i/o servers,"
+all as separate processes.  The other machines in the network (listed
+in the parameter file) are slave machines.  Each hosts a single
+process that continuously requests work from the master and does it.
+The slave process does the computation to encode MPEG frames.  It
+processes frames in batches identified by the master.
+.PP
+The master uses a remote shell command to start a process on a
+slave machine.  By default, it uses an \fBrsh\fP shell command to do
+this.  But use the \fBRSH\fP parameter file statement to control
+this.  The shell command the master executes remotely is
+\fBppmtompeg\fP, but with options to indicate that it is to perform
+slave functions.
+.PP
+The various machines talk to each other over TCP connections.  Each
+machine finds and binds to a free TCP port number and tells its
+partners the port number.  These port numbers are at least 2048.
+.PP
+Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS, and
+PARALLEL_PERFECT parameter file statements to control the way the
+master divides up work among the slaves.
+.PP
+Use the \fB-nice\fP command option to cause all slave processes to run
+"nicely," i.e. as low priority processes.  That way, this substantial and
+long-running CPU load will have minimal impact on other, possibly
+interactive, users of the systems.
+
+.UN speed
+.SH SPEED
+.PP
+Here is a look at \fBppmtompeg\fP speed, in single-node (not parallel)
+operation:
+
+.B Compression Speed
+.TS
+r c.
+_
+Machine Type	Macroblocks per second\u1\d
+HP 9000/755	280
+DEC 3000/400	247
+HP 9000/750	191
+Sparc 10	104
+DEC 5000	68
+.TE
+\u1\dA macroblock is a 16x16 pixel square
+.PP
+The measurements in the table are with inputs and outputs via a
+conventional locally attached filesystem.  If you are using a network
+filesystem over a single 10 MB/s Ethernet, that constrains your speed more
+than your CPU speed.  In that case, don't expect to get better than 4
+or 5 frames per second no matter how fast your CPUs are.
+.PP
+Network speed is even more of a bottleneck when the slaves do not
+have filesystem access to the input files -- i.e. you declare them
+REMOTE.
+.PP
+Where I/O is the bottleneck, size of the input frames can make a big
+difference.  So YUV input is better than PPM, and JPEG is better than
+both.
+.PP
+When you're first trying to get parallel mode working, be sure to
+use the \fB-debug_machines\fP option so you can see what's going on.
+Also, \fB-debug_sockets\fP can help you diagnose communication
+problems.
+
+
+.UN authors
+.SH AUTHORS
+
+
+
+.IP \(bu
+Kevin Gong - University of California, Berkeley, \fIkeving@cs.berkeley.edu\fP
+
+.IP \(bu
+Ketan Patel - University of California, Berkeley, \fIkpatel@cs.berkeley.edu\fP
+
+.IP \(bu
+Dan Wallach - University of California, Berkeley, \fIdwallach@cs.berkeley.edu\fP
+
+.IP \(bu
+Darryl Brown - University of California, Berkeley, \fIdarryl@cs.berkeley.edu\fP
+
+.IP \(bu
+Eugene Hung - University of California, Berkeley, \fIeyhung@cs.berkeley.edu\fP
+
+.IP \(bu
+Steve Smoot - University of California, Berkeley, \fIsmoot@cs.berkeley.edu\fP
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtompeg.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoneo.1 b/upstream/mageia-cauldron/man1/ppmtoneo.1
new file mode 100644
index 00000000..44050bf2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoneo.1
@@ -0,0 +1,57 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoneo User Manual" 0 "24 April 2001" "netpbm documentation"
+
+.SH NAME
+
+ppmtoneo - convert a PPM into an Atari Neochrome .neo file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoneo\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoneo\fP reads a PPM image as input and produces an Atari
+Neochrome .neo file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoneo\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "neotoppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2001 by Teemu Hukkanen <\fItjhukkan@iki.fi\fP>, based on
+ppmtopi1 by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoneo.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopcx.1 b/upstream/mageia-cauldron/man1/ppmtopcx.1
new file mode 100644
index 00000000..7c76d61f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopcx.1
@@ -0,0 +1,204 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopcx User Manual" 0 "26 September 2020" "netpbm documentation"
+
+.SH NAME
+
+ppmtopcx - convert a PPM image to a PCX file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopcx\fP
+
+[\fB-24bit\fP]
+
+[\fB-8bit\fP]
+
+[\fB-packed\fP]
+
+[\fB-stdpalette\fP]
+
+[\fB-palette=\fP\fIpalettefile\fP]
+
+[\fB-planes=\fP\fIplanes\fP]
+
+[\fB-xpos=\fP\fIcols\fP]
+
+[\fB-ypos=\fP\fIrows\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopcx\fP reads a PPM image as input and produces a PCX file
+as output.  The type of the PCX file depends on the number of colors
+in the input image:
+
+
+.TP
+16 colors or fewer:
+1 bit/pixel, 1-4 planes, colormap in header
+
+.TP
+more than 16 colors, but no more than 256:
+8 bits/pixel, 1 plane, colormap at the end of the file.
+
+.TP
+More than 256 colors:
+24bit truecolor file (8 bits/pixel, 3 planes).
+
+
+.PP
+You can override some of that and explicitly choose the format with
+the options below.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtopcx\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-24bit\fP
+Produce a 24bit truecolor PCX file, even if the image has 256
+colors or fewer.
+
+.TP
+\fB-8bit\fP
+Produce an 8bit (256 colors) PCX file, even if the image has 16
+colors or fewer.
+.sp
+This option was added in Netpbm 10.18 (August 2003).
+
+.TP
+\fB-packed\fP
+Use "packed pixel" format for files with 16 colors or
+fewer: 1, 2, or 4 bits/pixel, 1 plane.
+
+.TP
+\fB-stdpalette\fP
+Instead of computing a palette from the colors in the image, use
+a standard, built-in 16 color palette.  If the image contains a color
+that is not in the standard palette, \fBppmtopcx\fP fails.
+.sp
+The standard palette is not only a set of colors, but a specific
+mapping of palette indexes to colors.  E.g. red is 4.
+.sp
+You can use \fBpnmremap\fP with a suitable PPM image of the standard
+palette to adapt your image to use exactly those colors in the palette
+so that \fBppmtopcx -stdpalette\fP will work on it.
+.sp
+The file \fBpcxstd.ppm\fP, part of Netpbm, contains the standard
+palette.
+.sp
+Although the PCX header tells exactly what palette is used in the
+file, some older PCX interpreters do not use that information.  They
+instead assume the standard palette.  If you don't use the
+\fB-stdpalette\fP option, \fBppmtopcx\fP, \fBppmtopcx\fP may create
+an image that uses a different palette (a rearrangement of the same
+colors) and then one of these older interpreters would interpret the
+colors in the image wrong.
+.sp
+You cannot specify this option along with \fB-palette\fP.
+.sp
+This option was new in Netpbm 10.22 (April 2004).
+
+.TP
+\fB-palette=\fP\fIpalettefile\fP
+Instead of computing the palette from the colors in the image, use
+the palette from the file \fIpalettefile\fP.  If the palette contains
+a color that is not in that palette, \fBppmtopcx\fP fails.
+.sp
+The palette file must be a PPM image that contains one pixel for
+each color in the palette.  It doesn't matter what the aspect ratio
+of the palette image is.  The order of the colors in the PCX palette
+is the order of the pixels in the PPM image in standard western
+reading order (left to right, top to bottom).  If there is a duplicate
+color in the palette, \fBppmtopcx\fP chooses between them arbitrarily
+in building the PCX raster.
+.sp
+You would need this only if you have a PCX reader that can't read
+the palette that is in the PCX file and instead assumes some particular
+palette.  See also the \fB-stdpalette\fP option.
+.sp
+If your input image might contain colors other than those in your
+palette, you can convert the input image to one that contains only
+those colors in your palette with \fBpnmremap\fP.
+.sp
+You cannot specify this along with \fB-stdpalette\fP.
+.sp
+This option was new in Netpbhm 10.25 (October 2004).
+
+.TP
+\fB-planes=\fP\fIplanes\fP
+Generate a PCX file with \fIplanes\fP planes, even though the number
+of colors in the image could be represented in fewer.  This makes the file
+larger, but some PCX interpreters are capable of processing only certain
+numbers of planes.
+.sp
+This is meaningful only when \fBppmtopcx\fP generates an image in
+the 16 color palette format without packed pixels.  Consequently, you
+cannot specify this option together with \fB-24bit\fP or
+\fB-8bit\fP or \fB-packed\fP.
+.sp
+The valid values for \fIplanes\fP are 1, 2, 3, and 4.  By default,
+\fBppmtopcx\fP chooses the smallest number of planes that can represent
+the colors in the image.  E.g. if there are 5 colors, \fBppmtopcx\fP 
+chooses 3 planes.
+.sp
+This option was new in Netpbm 10.21 (March 2004).
+     
+.TP
+\fB-xpos=\fP\fIcols\fP
+
+.TP
+\fB-ypos=\fP\fIrows\fP
+ These options set the position of the image in some field
+(e.g. on a screen) in columns to the right of the left edge and rows
+below the top edge.  The PCX format contains image position
+information.  Don't confuse this with the position of an area of
+interest within the image.  For example, using \fBpnmpad\fP to add a
+10 pixel left border to an image and then converting that image to PCX
+with xpos = 0 is not the same as converting the original image to PCX
+and setting xpos = 10.
+.sp
+The values may be from -32767 to 32768.
+.sp
+The default for each is zero.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pcxtoppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1994 by Ingo Wilken (\fIIngo.Wilken@informatik.uni-oldenburg.de\fP)
+.PP
+Based on previous work by Michael Davidson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopcx.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopgm.1 b/upstream/mageia-cauldron/man1/ppmtopgm.1
new file mode 100644
index 00000000..d49dd0a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopgm.1
@@ -0,0 +1,96 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopgm User Manual" 0 "25 June 2017" "netpbm documentation"
+
+.SH NAME
+
+ppmtopgm - convert a PPM image to a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopgm\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopgm\fP reads a PPM as input and produces a PGM as output.
+The output is a "black and white" rendering of the original
+image, as in a black and white photograph.  The quantization formula
+\fBppmtopgm\fP uses is y = .299 r + .587 g + .114 b.
+.PP
+The dimensions and maxval of the output are the same as the input.
+Note that with only one color plane, there are far fewer brightnesses
+that can be represented with the same maxval than with three color
+planes, so you may want to increase the maxval of the input with
+\fBpamdepth\fP before giving it to \fBppmtopgm\fP to avoid loss of
+information.  For example, with a maxval of 1, there are 8 brightnesses that
+are possible in a PPM (though some of them are barely distinguishable), but
+only 2 brightness levels possible in a PGM.
+.PP
+Note that although there is a \fBpgmtoppm\fP program, it is not
+necessary for simple conversions from pgm to ppm , because any ppm
+program can read pgm (and pbm ) files automatically.  \fBpgmtoppm\fP
+is for colorizing a pgm file.  Also, see \fBppmtorgb3\fP for a
+different way of converting color to gray.  And \fBppmdist\fP
+generates a grayscale image from a color image, but in a way that
+makes it easy to differentiate the original colors, not necessarily a
+way that looks like a black and white photograph.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN quote
+.SH QUOTE
+
+.nf
+Cold-hearted orb that rules the night
+Removes the colors from our sight
+Red is gray, and yellow white
+But we decide which is right
+And which is a quantization error.
+
+.fi
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtoppm" (1)\c
+\&,
+.BR "ppmtorgb3" (1)\c
+\&,
+.BR "rgb3toppm" (1)\c
+\&,
+.BR "ppmdist" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopi1.1 b/upstream/mageia-cauldron/man1/ppmtopi1.1
new file mode 100644
index 00000000..e520b730
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopi1.1
@@ -0,0 +1,60 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopi1 User Manual" 0 "19 July 1990" "netpbm documentation"
+
+.SH NAME
+
+ppmtopi1 - convert a PPM image into an Atari Degas .pi1 file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopi1\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopi1\fP reads a PPM image as input and produces an Atari
+Degas .pi1 file as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtopi1\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pi1toppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+.BR "pbmtopi3" (1)\c
+\&, 
+.BR "pi3topbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopi1.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopict.1 b/upstream/mageia-cauldron/man1/ppmtopict.1
new file mode 100644
index 00000000..49b66752
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopict.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopict User Manual" 0 "15 April 1990" "netpbm documentation"
+
+.SH NAME
+
+ppmtopict - convert a PPM image to a Macintosh PICT file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopict\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopict\fP reads a PPM image as input and produces a
+Macintosh PICT file as output.
+.PP
+The generated file is only the data fork of a picture.  You will
+need a program such as \fImcvert\fP to generate a Macbinary or a
+BinHex file that contains the necessary information to identify the
+file as a PICT file to MacOS.
+.PP
+Even though PICT can have 2 and 4 bits per pixel, \fBppmtopict\fP
+always generates an 8 bits per pixel file.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtopict\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The picture size field is correct only if the output is to a file
+since writing into this field requires seeking backwards on a file.
+However the PICT documentation seems to suggest that this field is not
+critical anyway since it is only the lower 16 bits of the picture
+size.
+
+.UN seealso
+.SH SEE ALSO
+.BR "picttoppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+\fBmcvert\fP
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Ken Yap <\fIken@cs.rocester.edu\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopict.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopj.1 b/upstream/mageia-cauldron/man1/ppmtopj.1
new file mode 100644
index 00000000..3a506ff0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopj.1
@@ -0,0 +1,150 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopj User Manual" 0 "13 July 1991" "netpbm documentation"
+
+.SH NAME
+ppmtopj - convert a PPM image to an HP PaintJet file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopj\fP
+
+[\fB-gamma\fP \fIval\fP]
+
+[\fB-xpos\fP \fIval\fP]
+
+[\fB-ypos\fP \fIval\fP]
+
+[\fB-back\fP {\fBdark\fP|\fBlite\fP}]
+
+[\fB-rle\fP]
+
+[\fB-center\fP]
+
+[\fB-render\fP {
+\fBnone\fP |
+\fBsnap\fP |
+\fBbw\fP |
+\fBdither\fP |
+\fBdiffuse\fP |
+\fBmonodither\fP |
+\fBmonodiffuse\fP |
+\fBclusterdither\fP |
+\fBmonoclusterdither\fP
+}]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopj\fP reads a PPM image as input and converts it into a
+format suitable to be printed by an HP PaintJet printer.
+.PP
+For best results, the input file should be in 8-color RGB form;
+i.e. it should have only
+the 8 binary combinations of full-on and full-off primaries.
+You could convert your input to this format like this:
+
+.nf
+    pamseq 3 1 testimg.ppm >8color.pam
+    pnmremap -map 8color.pam testimg.pam | ppmtopj
+
+.fi
+
+Or you could use 
+.nf
+    ppmdither -red 2 -green 2 -blue 2
+
+.fi
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtopj\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-rle\fP
+Run length encode the image.
+(This can result in larger images)
+
+.TP
+\fB-back\fP
+Enhance the foreground by indicating if the background is light or
+dark compared to the foreground.
+
+.TP
+\fB-render\fP \fIalg\fP
+Use an internal rendering algorithm (default dither).
+
+.TP
+\fB-gamma\fP \fIint\fP
+Gamma correct the image using the integer \fIint\fP as a gamma (default 0).
+
+.TP
+\fB-center\fP
+Center the image to an 8.5 by 11 page
+
+.TP
+\fB-xpos\fP \fIpos\fP
+Move by \fIpos\fP pixels in the x direction.
+
+.TP
+\fB-ypos\fP \fIpos\fP
+Move by \fIpos\fP pixels in the y direction.
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+HP PaintJet XL Color Graphics Printer User's Guide,
+.BR "\fBpnmtopclxl\fP" (1)\c
+\&,
+.BR "\fBpjtoppm\fP" (1)\c
+\&,
+.BR "\fBpamdepth\fP" (1)\c
+\&,
+.BR "\fBpnmremap\fP" (1)\c
+\&,
+.BR "\fBpamseq\fP" (1)\c
+\&,
+.BR "\fBppmdither\fP" (1)\c
+\&,
+.BR "\fBpbmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtopjxl\fP" (1)\c
+\&,
+.BR "\fBthinkjettopbm\fP" (1)\c
+\&,
+.BR "\fBppm\fP" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Christos Zoulas.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopj.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopjxl.1 b/upstream/mageia-cauldron/man1/ppmtopjxl.1
new file mode 100644
index 00000000..0e1e06a7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopjxl.1
@@ -0,0 +1,144 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopjxl User Manual" 0 "14 March 1991" "netpbm documentation"
+
+.SH NAME
+
+ppmtopjxl - convert a PPM image to an HP PaintJet XL PCL file
+
+.UN synopsis
+.SH SYNOPSIS
+
+ppmtopjxl 
+[\fB-nopack\fP] 
+[\fB-gamma\fP \fIn\fP] 
+[\fB-presentation\fP] 
+[\fB-dark\fP] 
+[\fB-diffuse\fP] 
+[\fB-cluster\fP] 
+[\fB-dither\fP] 
+[\fB-xshift\fP \fIs\fP] 
+[\fB-yshift\fP \fIs\fP] 
+[\fB-xshift\fP \fIs\fP] 
+[\fB-yshift\fP \fIs\fP] 
+[{\fB-xsize\fP|\fB-width\fP|\fB-xscale\fP} \fIs\fP] 
+[{\fB-ysize\fP|\fB-height\fP|\fB-yscale\fP} \fIs\fP] 
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopjxl\fP reads a PPM image as input and produces a PCL file
+suitable for printing on an HP PaintJet XL printer as output.
+.PP
+The generated file is not suitable for printing on a normal
+PrintJet printer.  The \fB-nopack\fP option generates a file which
+does not use the normal TIFF 4.0 compression method and thus might
+be printable on a normal PaintJet printer (not an XL).
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtopjxl\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-nopack\fP
+.sp
+Generate a file which does not use the normal TIFF 4.0 compression
+method. This file might be printable on a normal PaintJet printer
+(not an XL).
+
+.TP
+\fB-gamma\fP
+.sp
+Set the gamma correction for the image. The useful range for the
+PaintJet XL is approximately 0.6 to 1.5.
+
+.TP
+\fB-dither\fP, \fB-cluster\fP, \fB-diffuse\fP
+.sp
+Alter the rendering algorithm used for images.  These options
+select ordered dithering, clustered ordered dithering, or error
+diffusion respectively.
+
+.TP
+\fB-dark\fP
+.sp
+Enhance images with a dark background when they are reduced in size.
+
+.TP
+\fB-presentation\fP
+.sp
+Turn on presentation mode, in which two passes are made over the
+paper to increase ink density.  You should use this only for images where
+quality is critical.
+
+.TP
+\fB-xsize\fP, \fB-ysize\fP
+.sp
+Resize the image.  The parameter to either of these options is
+interpreted as the number of dots to set the width or height to, but
+you may append an optional dimension of `\fBpt\fP' (points),
+`\fBdp\fP' (decipoints), `\fBin\fP' (inches), or `\fBcm\fP'
+(centimetres).  If you specify only one dimension, \fBppmtopjxl\fP
+will scale the other one appropriately.
+
+.TP
+\fB-width\fP, \fB-height\fP
+.sp
+Synonyms of \fB-xsize\fP and \fB-ysize\fP.
+
+.TP
+\fB-xscale\fP, \fB-yscale\fP
+.sp
+Alternatives to \fB-xsize\fP and \fB-ysize\fP.  Scale the
+image by a simple factor.
+
+.TP
+\fB-xshift\fP, \fB-yshift\fP
+.sp
+Shift the image on the page.  These move the image the specified
+dimensions right and down.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpnmtopclxl\fP" (1)\c
+\&,
+.BR "\fBpbmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtolj\fP" (1)\c
+\&,
+.BR "\fBppmtopj\fP" (1)\c
+\&,
+.BR "\fBthinkjettopbm\fP" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Angus Duggan
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopjxl.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoppm.1 b/upstream/mageia-cauldron/man1/ppmtoppm.1
new file mode 100644
index 00000000..b0bb2b31
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoppm.1
@@ -0,0 +1,78 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoppm User Manual" 0 "February 2007" "netpbm documentation"
+
+.SH NAME
+ppmtoppm - copy PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoppm\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoppm\fP simply copies a PPM image from Standard Input to
+Standard Output.  This may seem an unnecessary duplication of
+\fBcat\fP, but remember that a PPM program can read a PBM or PGM
+image, and the right kind of PAM, as if it were PPM.  So
+\fBppmtoppm\fP can read either a PBM, PGM, or PPM image and produce a
+PPM image as output.
+.PP
+Even that is of limited usefulness because of the fact that almost
+any program to which you would feed the resulting PPM image could also
+just take the original image directly.  However, sometimes you really
+need a true PPM image.
+.PP
+When you know you have a PGM image and want a PPM image,
+\fBpgmtoppm\fP is a more general way to do that conversion.
+When you know you have a PBM image, use that and \fBpbmtopgm\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtopgm" (1)\c
+\&,
+.BR "pamtopam" (1)\c
+\&,
+.BR "pamtopnm" (1)\c
+\&,
+.BR "pgmtoppm" (1)\c
+\&,
+.BR "pbmtopgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.9 (September 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtopuzz.1 b/upstream/mageia-cauldron/man1/ppmtopuzz.1
new file mode 100644
index 00000000..35682f83
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtopuzz.1
@@ -0,0 +1,57 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtopuzz User Manual" 0 "22 August 1990" "netpbm documentation"
+
+.SH NAME
+
+ppmtopuzz - convert a PPM image to an X11 "puzzle" file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtopuzz\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtopuzz\fP reads a PPM image as input and produces an X11
+"puzzle" file as output.  A "puzzle" file is for
+use with the \fBpuzzle\fP program included with the X11 distribution.
+\fBpuzzle\fP's \fB-picture\fP option lets you specify an image file.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtopuzz\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&, 
+\fBpuzzle\fP
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtopuzz.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtorgb3.1 b/upstream/mageia-cauldron/man1/ppmtorgb3.1
new file mode 100644
index 00000000..b16e5dd6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtorgb3.1
@@ -0,0 +1,71 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtorgb3 User Manual" 0 "10 January 1991" "netpbm documentation"
+
+.SH NAME
+
+ppmtorgb3 - separate a PPM image into three PGMs
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtorgb3\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtorgb3\fP reads a PPM image as input and writes three PGM
+images as output, one each for red, green, and blue.
+.PP
+\fBppmtorgb3\fP constructs the output filenames by taking the
+input filename, stripping off any extension, and appending
+\fB.red\fP, \fB.grn\fP, \fB.blu\fP.  For example, separating
+\fBlenna.ppm\fP would result in \fBlenna.red\fP, \fBlenna.grn\fP,
+and \fBlenna.blu\fP.  If the input comes from stdin, the names are
+\fBnoname.red\fP, \fBnoname.grn\fP, and \fBnoname.blu\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtorgb3\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "rgb3toppm" (1)\c
+\&, 
+.BR "pamchannel" (1)\c
+\&, 
+.BR "ppmtopgm" (1)\c
+\&, 
+.BR "pgmtoppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtorgb3.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtosixel.1 b/upstream/mageia-cauldron/man1/ppmtosixel.1
new file mode 100644
index 00000000..a8a17bdf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtosixel.1
@@ -0,0 +1,98 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtosixel User Manual" 0 "26 April 1991" "netpbm documentation"
+
+.SH NAME
+
+ppmtosixel - convert a PPM image to DEC sixel format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtosixel\fP
+
+[\fB-raw\fP]
+
+[\fB-margin\fP]
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtosixel\fP reads a PPM image as input and produces sixel
+commands (SIX) as output.  The output is formatted for color printing,
+e.g. for a DEC LJ250 color inkjet printer.
+.PP
+If RGB values from the PPM file do not have maxval=100,
+\fBppmtosixel\fP rescales them to maxval 100.  A printer control
+header and a color assignment table begin the SIX file.  Image data is
+in a compressed format by default.  A printer control footer ends the
+image file.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtosixel\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-raw\fP
+If you specify this, each pixel will be explicitly described in
+the image file.  If \fB-raw\fP is not specified, output will default
+to compressed format in which identical adjacent pixels are replaced
+by "repeat pixel" commands.  A raw file is often an order of
+magnitude larger than a compressed file and prints much slower.
+
+.TP
+\fB-margin\fP
+If you don't specify \fB-margin\fP, the image will start at the
+left margin (of the window, paper, or whatever).  If you \fIdo\fP
+specify \fB-margin\fP, a 1.5 inch left margin will offset the image.
+
+
+
+.UN printing
+.SH PRINTING
+.PP
+Generally, sixel files must reach the printer unfiltered.
+Use the lpr -x option or \fBcat filename > /dev/tty0?\fP.
+
+.UN limitations
+.SH LIMITATIONS
+
+Upon rescaling, truncation of the least significant bits of RGB values
+may result in poor color conversion.  If the original PPM maxval was
+greater than 100, rescaling also reduces the image depth.  While the
+actual RGB values from the ppm file are more or less retained, the
+color palette of the LJ250 may not match the colors on your screen.
+This seems to be a printer limitation.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Rick Vinci.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtosixel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtospu.1 b/upstream/mageia-cauldron/man1/ppmtospu.1
new file mode 100644
index 00000000..cb196b7c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtospu.1
@@ -0,0 +1,115 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtospu User Manual" 0 "08 March 2012" "netpbm documentation"
+
+.SH NAME
+ppmtospu - convert a PPM image to an Atari Spectrum 512 image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtospu\fP
+
+[\fB-d0\fP|\fB-d2\fP|\fB-d4\fP]
+[\fIppmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&. 
+.PP
+This program converts from the PPM format to the uncompressed Spectrum 512
+image format used on Atari ST computers.
+.PP
+Input comes from the file you name with the \fIppmfile\fP argument, or
+Standard Input by default.  Output goes to Standard Output.
+.PP
+The input must be 320 pixels wide by 200 pixels high.  If you have an
+image of a different size, you can use \fBpamcut\fP or \fBpamscale\fP
+to force it to these dimensions.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtospu\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-d0\fP
+The program does no dithering.
+
+.TP
+\fB-d2\fP
+The program uses a 2x2 ordered dither.
+.sp
+This is the default.
+
+.TP
+\fB-d4\fP
+The program uses a 4x4 ordered dither.
+    
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "sputoppm" (1)\c
+\&,
+.BR "spctoppm" (1)\c
+\&,
+.BR "pamscale" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1990 by Steve Belczyk
+
+
+.UN history
+.SH HISTORY
+.PP
+This program was new in Netpbm 10.58 (March 2012).
+.PP
+But it was written in 1990.  Steve Belczyk posted it along
+with \fBsputoppm\fP, \fBspctoppm\fP, \fBpi1toppm\fP, and
+\fBpi1toppm\fP - all programs for dealing with Atari image formats -
+to comp.sources.misc on July 15, 1990.  For reasons that have been lost
+to history, all of these entered the Netpbm (then Pbmplus) distribution
+\fIexcept\fP \fBppmtospu\fP.
+.PP
+Georges Kesseler wondered In March 2012 why there was no counterpart to
+\fBsputoppm\fP in Netpbm and searched the web, finding only one reference
+to \fBppmtopsu\fP: the 1990 comp.sources.misc posting, including the source
+code.  He emailed the Netpbm maintainer suggesting it be added.
+.PP
+Bryan Henderson found the source code to be extremely primitive, not even
+using common library code.  So Bryan completely recoded it, but retained
+nearly all of the original logic.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtospu.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoterm.1 b/upstream/mageia-cauldron/man1/ppmtoterm.1
new file mode 100644
index 00000000..be82cfd3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoterm.1
@@ -0,0 +1,112 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoterm User Manual" 0 "17 June 2017" "netpbm documentation"
+
+.SH NAME
+
+ppmtoterm - convert a PPM image to a ANSI ISO 6429 ascii image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoterm\fP
+
+[\fIppmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&. 
+.PP
+This program tries to produce an accurate representation of a PPM
+image on an terminal that implements the ANSI ISO 6429 standard.  It
+approximates colors, finding the minimum Cartesian distance between the
+input RGB vectors and the ones in the generated palette.  As the
+available color palette is somewhat restricted, you get the best
+results when the colors in the original image are few and the RGB
+intensities are close to zero, half of maximum, and maximum.
+.PP
+You can usually get good results with cartoons or images with
+plain colors (no gradients).  With photos, results can vary, but are
+usually not very accurate.
+.PP
+The output image has one line for each row and one character for each
+column of the input image.  E.g. an 80 pixel by 25 pixel PPM image would
+fill up an 80x25 terminal screen.  Use \fBpamscale\fP or \fBpamcut\fP
+to make your image fit properly on your screen.
+.PP
+Furthermore, use \fBpamscale\fP to recover the proper aspect ratio,
+because a character on a terminal screen is rarely square.  Typically, a
+character is twice has high as it is wide, so in order for a 20x20 image to
+appear square on your terminal, as it should, you'll want to squash it
+vertically or stretch it horizontally by a factor of two (resulting int 10x20
+characters are 20x40 characters).
+.PP
+The image starts at the current cursor position on the terminal
+screen.  Each successive row starts at Column 0 on the screen.  If you want
+to shift the image up or down, for example to center it, use
+\fBpnmpad\fP on the input.
+.PP
+This program was born with the objective of displaying nice color
+images on the Linux console, e.g. a proper logo at Linux boot.
+.PP
+\fBppmtoascii\fP does a similar things, but combines 2 or 8 pixels into
+one character, where the character roughly represents those particular pixels,
+whereas \fBppmtoterm\fP displays each character of the image as a single
+pixel.
+.PP
+\fBpbmto4425\fP does a similar thing for black and white images, using
+line drawing characters, on some terminals.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoterm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamscale" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "ppmtoascii" (1)\c
+\&,
+.BR "pbmtoascii" (1)\c
+\&,
+.BR "pbmto4425" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2002 by Ero Carrera.
+
+
+.UN history
+.SH HISTORY
+.PP
+This program was new in Netpbm 10.9 (August 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoterm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtouil.1 b/upstream/mageia-cauldron/man1/ppmtouil.1
new file mode 100644
index 00000000..817ff7af
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtouil.1
@@ -0,0 +1,26 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtouil User Manual" 0 "May 2002" "netpbm documentation"
+
+.SH NAME
+
+ppmtouil - replaced by pamtouil
+
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+In May 2002, \fBppmtouil\fP was extended and renamed to
+.BR "pamtouil" (1)\c
+\&.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtouil.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtowinicon.1 b/upstream/mageia-cauldron/man1/ppmtowinicon.1
new file mode 100644
index 00000000..263c41ac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtowinicon.1
@@ -0,0 +1,149 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtowinicon User Manual" 0 "01 May 2004" "netpbm documentation"
+
+.SH NAME
+ppmtowinicon - convert PPM image into a Windows .ico file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtowinicon\fP
+
+[\fB-andpgms\fP]
+
+[\fB-output=\fP\fIoutput.ico\fP]
+
+[\fIppmfile\fP [\fIandfile\fP] ...]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program is essentially obsolete; The newer \fBpamtowinicon\fP is
+better.
+.PP
+\fBppmtowinicon\fP reads one or more PPM images as input and
+produces a Microsoft Windows .ico file as output.
+.PP
+A Windows icon contains 1 or more images, at different resolutions
+and color depths.  When Windows wants to display the icon, it searches
+through the images to find the one that best matches the number of colors
+and resolution of the display.
+.PP
+Microsoft recommends including at least the following formats in each
+icon.
+
+
+.IP \(bu
+16 x 16 - 4 bpp
+.IP \(bu
+32 x 32 - 4 bpp
+.IP \(bu
+48 x 48 - 8 bpp
+
+.PP
+If you don't specify any input files, input is from Standard Input.
+.PP
+Output is to Standard Output unless you specify \fB-output\fP.
+
+.UN transparency
+.SS Transparency
+.PP
+If you specify the \fB-andmask\fP option, you get (partly)
+transparent icons.  In that case, your arguments are pairs of file
+names, with the first file name being that of the image and the second
+file name being that of a standard Netpbm PGM transparency mask (see
+the
+.BR "pgm format specification" (1)\c
+\&).
+.PP
+In a .ico file, there is no such thing as partial transparency
+(translucency).  Where the PGM mask says completely opaque, the icon will
+be opaque.  Everywhere else, the icon will be transparent.  Note that
+as with any Netpbm program, you can use a PBM image for the transparency
+mask and \fBppmtowinicon\fP will treat it like a PGM.
+.PP
+The and mask is like a transparency mask, except for what it signifies in
+the "not opaque" areas.  In the usual case, the foreground image is
+black in those areas, and in that case the areas are fully transparent
+-- the background shows through the icon.  But in general, a not
+opaque pixel signifies that the background and foreground should be
+merged as follows: The intensities of the color components in the
+foreground and background are represented as binary numbers, then
+corresponding bits of the background and foreground intensities are
+exclusive-or'ed together.  So there is a sort of reverse video effect.
+.PP
+If you don't want this special effect and instead want
+straightforward transparency, use the \fB-truetransparent\fP option.
+This causes \fBppmtowinicon\fP to make the base image black
+everywhere your transparency mask says transparent, regardless of what
+color your input image is at that location.
+.PP
+If you don't specify \fB-andmask\fP, \fBppmtowinicon\fP puts
+all-opaque and masks into the .ico file.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtowinicon\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-andpgms\fP
+Include transparency information in the icons.
+See the 
+.UR #transparency
+transparency section
+.UE
+\&.
+     
+.TP
+\fB-output=\fP\fIoutput.ico\fP
+Name of output file.  By default, \fBppmtowinicon\fP writes the
+icon to Standard Output.
+
+.TP
+\fB-truetransparent\fP
+Make transparency in the icon normal instead of the special reverse
+video effect.  See the 
+.UR #transparency
+transparency section
+.UE
+\&.
+     
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtowinicon" (1)\c
+\&,
+.BR "winicontoppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2000 by Lee Benfield.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtowinicon.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoxpm.1 b/upstream/mageia-cauldron/man1/ppmtoxpm.1
new file mode 100644
index 00000000..45df0cd2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoxpm.1
@@ -0,0 +1,188 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoxpm User Manual" 0 "22 February 2003" "netpbm documentation"
+
+.SH NAME
+ppmtoxpm - convert a PPM image to an X11 pixmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoxpm \fP
+[\fB-name=\fP\fIxpmname\fP]
+[\fB-hexonly\fP]
+[\fB-rgb=\fP\fIrgb-textfile\fP]
+[\fB-alphamask=\fP\fIpgmfile\fP]
+[\fIppmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoxpm\fP reads a PPM image as input and produces X11 pixmap
+(version 3) as output.  This format can be loaded by the XPM library.
+.PP
+In the XPM output, colors may be identified by name, such as "Red", or
+in hexadecimal, for example "#FF0000".  In the hexadecimal format, there
+may be from 1 through 4 hexadecimal digits per RGB component.
+.PP
+By default, \fBppmtoxpbm\fP tries to find a name for each color in
+the image in the 
+.UR libppm.html#dictionary
+system color dictionary
+.UE
+\&, and if it finds one, uses it.  If it doesn't it uses
+hexadecimal.  You can force \fBppmtoxpbm\fP to use hexadecimal only
+with the \fB-hexonly\fP option.  You can specify a different color
+dictionary with the \fB-rgb\fP option.
+.PP
+When \fBppmtoxpm\fP uses the hexadecimal format for identifying a color,
+it uses the one that uses the least number of hexadecimal digits that it
+takes to represent the maxval of the input PPM.  E.g. if the maxval of the
+input PPM is 100, \fBppmtoxpm\fP uses 2 digits per component, as in
+"#FF0000".
+.PP
+Some programs do not properly handle one-digit-per-component
+hexadecimal color specifiers.  They see the wrong colors.  To produce
+an XPM that such a program can handle, make sure the maxval of the input PPM
+is greater than 15, such as by running it through \fBpamdepth 255\fP.
+
+.SS Color Code Lengths - Image Size
+.PP
+In the XPM format, there is a palette ("color map") that
+assigns each color in the image to a unique sequence of printable
+characters called a color code, and a raster that identifies the color
+of each pixel of the image with one of those color codes.  The length
+of the color code affects the size of the image stream.  
+.PP
+All color codes in an image are the same length, and
+\fBppmtoxpm\fP tries to make it as short as possible.  That length
+is, of course, determined by the number of colors in the image.
+\fBppmtoxpm\fP counts the colors in the image, excluding those that will be
+transparent in the output because of your transparency mask, and chooses a
+color code length accordingly.  There are 92 printable characters that can be
+used in a color code.  Therefore, if you have 92 or fewer colors, your color
+codes will be one character.  If you have more than 92 but not more than 92 *
+92, your color codes will be two characters.  And so on.
+.PP
+There's one exception to the above: If you specify a transparency mask
+(the \fB-alpha\fP option, one unique color code represents
+"transparent."  This is true even if the transparency mask doesn't 
+actually produce any transparent pixels.  So subtract one from the number
+of possible colors if you use \fB-alpha\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmtoxpm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-name=\fP\fIxpmname\fP
+This option specifies the prefix string which is specified in the
+resulting XPM output.  If you don't use the \fB-name\fP otpion,
+\fBppmtoxpm\fP defaults to the filename (without extension) of the
+\fIppmfile\fP parameter.  If you do not specify \fB-name\fP or
+\fIppmfile\fP (i.e. your input is from Standard Input), the prefix
+string defaults to the string \fBnoname\fP.
+
+.TP
+\fB-hexonly\fP
+This option says never to put color names in the XPM file, but rather
+to identify names by hexadecimal strings that explicitly identify RGB
+component intensities.  This means the reader of the file need not have
+access to a suitable color dictionary to interpret it.
+.sp
+This option was introduced in Netpbm 10.15 (April 2003).  Before that,
+it was the default, overridden by specifying \fB-rgb\fP.
+
+.TP
+\fB-rgb=\fP\fIrgb-textfile\fP
+This option names the file in which the color dictionary you want
+to use resides.  By default, \fBppmtoxpm\fP uses the 
+.UR libppm.html#dictionary
+system color dictionary
+.UE
+\&, and if it cannot
+open that file, uses hexadecimal color specifiers.
+.sp
+This option in meaningless when you specify \fB-hexonly\fP.
+.sp
+Before Netpbm 10.15 (April 2003), \fBppmtoxpm\fP did not default
+to the system color dictionary.  If you didn't specify \fB-rgb\fP,
+\fBppmtoxpbm\fP would use only hexadecimal color specifiers.
+
+.TP
+\fB-alphamask=\fP\fIpgmfile\fP
+ This option names a PGM file to use as a transparency (alpha)
+mask.  The file must contain an image the same dimensions as the input
+image.  \fBppmtoxpm\fP marks as transparent any pixel whose position
+in the transparency mask image is at most half white.
+.sp
+If you don't specify \fB-alphamask\fP, \fBppmtoxpm\fP makes all
+pixels in the output opaque.
+.sp
+\fBppmcolormask\fP is one way to generate a transparency mask file.  You
+might also generate it by extracting transparency information from an
+XPM file with the \fB-alphaout\fP option to \fBxpmtoppm\fP.
+.sp
+There are similar options on other Netpbm converters that convert from
+formats that include transparency information too.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmcolormask" (1)\c
+\&,
+.BR "xpmtoppm" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+XPM Manual by Arnaud Le Hors \fIlehors@mirsa.inria.fr\fP
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1990 by Mark W. Snitily.
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.  This software is provided "as is" without express or
+implied warranty.
+.PP
+This tool was developed for Schlumberger Technologies, ATE Division, and
+with their permission is being made available to the public with the above
+copyright notice and permission notice.
+.PP
+Upgraded to XPM2 by Paul Breslaw, Mecasoft SA, Zurich, Switzerland (\fIpaul@mecazh.uu.ch\fP), November 8,
+1990.
+.PP
+Upgraded to XPM version 3 by Arnaud Le Hors(\fIlehors@mirsa.inria.fr\fP), April
+9, 1991.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoxpm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoyuv.1 b/upstream/mageia-cauldron/man1/ppmtoyuv.1
new file mode 100644
index 00000000..fa6297de
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoyuv.1
@@ -0,0 +1,104 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoyuv User Manual" 0 "06 June 2005" "netpbm documentation"
+
+.SH NAME
+ppmtoyuv - convert a PPM image to an Abekas YUV file
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoyuv\fP
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoyuv\fP reads a PPM image as input and produces an Abekas
+YUV file as output.
+.PP
+The output file contains a raster of four byte YUV codes, each
+uniquely associated with two side-by-side pixels in the image.  The raster
+contains rows in order from top to bottom, and within each row columns
+from left to right.  So the output file size in bytes is twice the number of
+pixels in the image.
+.PP
+Each YUV code is associated with two pixels from the input image that we
+will call the left pixel and the right pixel.  The 2nd byte of the code is
+the Y value of the left pixel.  The 4th byte of the code is the Y value of
+the right pixel.  The 1st byte of the code is an average of the U value of
+the pixel \fIto the left of the left pixel\fP, the left pixel, and the
+right pixel.  The 3rd byte of the code is analogous for V values.  These
+averages are weighted arithmetic means where the left pixel is weighted
+double what the other two pixels are weighted.
+.PP
+This format is reminiscent of but rather different from the common
+YUV 4:2:0 format (aka YUV 420) and the similar YUV 4:4:4, YUV 4:2:2,
+YUV 4:1:1, YUV 4:1:1s, and YUV 4:1:0.  In YUV 4:2:0, the raster is
+different for even numbered lines and odd numbered lines.  On even
+numbered lines, there are twice as many bits for Y of each pixel as
+for U or V.  On odd numbered lines, there are the same number of bits
+for Y as on even numbered lines, but no bits at all for U and V.
+.PP
+Another YUV-based format is YUV4MPEG2, which is a movie format
+normally used with 
+.UR http://mjpeg.sourceforge.net
+\fBMJPEGTools\fP
+.UE
+\&.  Netpbm
+does not have converters for this format, but \fBMJPEGTools\fP does.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoyuv\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "yuvtoppm" (1)\c
+\&,
+.BR "ppmtoeyuv" (1)\c
+\&,
+.BR "ppmtoyuvsplit" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.UR http://mjpeg.sourceforge.net
+pnmtoy4m
+.UE
+\&,
+.UR http://mjpeg.sourceforge.net
+y4mtopnm
+.UE
+\&
+
+
+.UN author
+.SH AUTHOR
+.PP
+Marc Boucher \fImarc@PostImage.COM\fP, based on
+Example Conversion Program, A60/A64 Digital Video Interface Manual,
+page 69.
+.PP
+Copyright (C) 1991 by DHD PostImage Inc.
+.PP
+Copyright (C) 1987 by Abekas Video Systems Inc.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoyuv.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtoyuvsplit.1 b/upstream/mageia-cauldron/man1/ppmtoyuvsplit.1
new file mode 100644
index 00000000..f9997609
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtoyuvsplit.1
@@ -0,0 +1,77 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtoyuvsplit User Manual" 0 "06 March 2003" "netpbm documentation"
+
+.SH NAME
+
+ppmtoyuvsplit - convert a PPM image to 3 subsampled raw YUV files
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmtoyuvsplit\fP
+\fIbasename\fP
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtoyuvsplit\fP reads a PPM image as input.  Produces 3 raw
+files \fIbasename\fP.Y, \fIbasename\fP.U and \fIbasename\fP.V as
+output.
+.PP
+The output files are the subsampled raw YUV representation of the
+input PPM image, as required by the Stanford MPEG codec.  The Y output
+file contains a byte for each pixel in the image, with the rows going
+from top to bottom and the columns within each row going left to
+right.  The U and V output files are arranged similarly, except that
+each byte represents a square of 4 pixels of the image.  The value is
+the arithmetic mean of the value for each of those 4 pixels.  Hence, the
+Y file is 4 times the size of the U file or V file.
+.PP
+The YUV values are scaled according to CCIR.601, as assumed by
+MPEG.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtoyuvsplit\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "yuvsplittoppm" (1)\c
+\&,
+.BR "ppmtoyuv" (1)\c
+\&,
+.BR "ppmtoeyuv" (1)\c
+\&,
+.BR "ppmtompeg" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1993 by Andre Beck. (\fIAndre_Beck@IRS.Inf.TU-Dresden.de\fP)
+.PP
+Based on ppmtoyuv.c
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtoyuvsplit.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmtv.1 b/upstream/mageia-cauldron/man1/ppmtv.1
new file mode 100644
index 00000000..0f8022dd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmtv.1
@@ -0,0 +1,67 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmtv User Manual" 0 "16 November 1993" "netpbm documentation"
+
+.SH NAME
+
+ppmtv - make a PPM image look like taken from an American TV
+
+.UN synopsis
+.SH SYNOPSIS
+
+ppmtv
+\fIdimfactor\fP
+
+[\fIppmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmtv\fP reads a PPM image as input and dims every other row of
+image data down by the specified dim factor.  This factor may be in
+the range of 0.0 (the alternate lines are totally black) to 1.0
+(original image).
+.PP
+This creates an effect similar to what I've once seen in the video
+clip 'You could be mine' by Guns'n'Roses.  In the scene I'm talking
+about you can see John Connor on his motorbike, looking up from the
+water trench (?)  he's standing in.  While the camera pulls back, the
+image gets 'normal' by brightening up the alternate rows of it. I
+thought this would be an interesting effect to try in MPEG. I did not
+yet check this out, however.  Try for yourself.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBppmtv\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&, 
+.BR "ppmdim" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Frank Neumann
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmtv.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ppmwheel.1 b/upstream/mageia-cauldron/man1/ppmwheel.1
new file mode 100644
index 00000000..d641dd0d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ppmwheel.1
@@ -0,0 +1,134 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ppmwheel User Manual" 0 "03 February 2019" "netpbm documentation"
+
+.SH NAME
+ppmwheel - make a PPM image of a color wheel
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBppmwheel\fP
+\fIdiameter\fP
+[{\fB-huevalue\fP | \fB-huesaturation\fP}]
+[\fB-maxval=\fP\fIN\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBppmwheel\fP produces a PPM image of a color wheel of the
+specified diameter inside a white square just large enough to hold it.
+.PP
+The color wheel is based on the HSV color model.  Hues are distributed
+  angularly around the circle and the values and saturations are distributed
+  radially.
+.PP
+You can generate three kinds of color wheel:
+
+.IP \(bu
+Hue-value: Select this with a \fB-huevalue\fP option.
+.sp
+The saturation is 100% everywhere.  The value goes from zero to 100%
+  linearly, from the center of the wheel to the edge.  So the center is black.
+.sp
+Hence, the image consists of all of the secondary colors based on the
+  red, green, and blue primary colors.  A secondary color is one that is
+  composed of light of at most two of the three primary colors.
+
+.IP \(bu
+Hue-saturation: Select this with a \fB-huesaturation\fP option.
+.sp
+The value is 100% everywhere.  The saturation goes from zero to 100%
+  linearly, from the center of the wheel to the edge.  So the center is white.
+
+.IP \(bu
+Ppmcirc: Select this by not specifying any other wheel type option.
+.sp
+The saturation is 100% everywhere.  The value is a strange function of
+  the distance from the center, increasing as the square root of the distance
+  until halfway out, then decreasing as the 8th root of the distance the rest
+  of the way.  We don't know what the point of this is, but it is what the
+  program Ppmcirc by Peter Kirchgessner in 1995 does, and was the only option
+  in \fBppmwheel\fP from its inception in 2003 to 2019.
+      
+
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+You must specify one non-option argument: the radius of the color wheel
+in pixels.
+.PP
+This is also the height and width of the output image.
+
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBppmwheel\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-huevalue\fP
+  
+This selects a hue-value color wheel.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-huesaturation\fP
+  
+This selects a hue-saturation color wheel.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+.TP
+\fB-maxval=\fP\fIN\fP
+  
+This selects the maxval for the image.  The default is 255.
+.sp
+This option was new in Netpbm 10.86 (March 2019).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmcie" (1)\c
+\&,
+.BR "ppmrainbow" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBppmwheel\fP was added to Netpbm in Release 10.14 (March 2003).
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1995 by Peter Kirchgessner
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ppmwheel.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pr.1 b/upstream/mageia-cauldron/man1/pr.1
new file mode 100644
index 00000000..56e3fd5d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pr.1
@@ -0,0 +1,132 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+pr \- convert text files for printing
+.SH SYNOPSIS
+.B pr
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Paginate or columnate FILE(s) for printing.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
++FIRST_PAGE[:LAST_PAGE], \fB\-\-pages\fR=\fI\,FIRST_PAGE[\/\fR:LAST_PAGE]
+begin [stop] printing with page FIRST_[LAST_]PAGE
+.TP
+\fB\-COLUMN\fR, \fB\-\-columns\fR=\fI\,COLUMN\/\fR
+output COLUMN columns and print columns down,
+unless \fB\-a\fR is used. Balance number of lines in the
+columns on each page
+.TP
+\fB\-a\fR, \fB\-\-across\fR
+print columns across rather than down, used together
+with \fB\-COLUMN\fR
+.TP
+\fB\-c\fR, \fB\-\-show\-control\-chars\fR
+use hat notation (^G) and octal backslash notation
+.TP
+\fB\-d\fR, \fB\-\-double\-space\fR
+double space the output
+.TP
+\fB\-D\fR, \fB\-\-date\-format\fR=\fI\,FORMAT\/\fR
+use FORMAT for the header date
+.TP
+\fB\-e[CHAR[WIDTH]]\fR, \fB\-\-expand\-tabs\fR[=\fI\,CHAR[WIDTH]\/\fR]
+expand input CHARs (TABs) to tab WIDTH (8)
+.TP
+\fB\-F\fR, \fB\-f\fR, \fB\-\-form\-feed\fR
+use form feeds instead of newlines to separate pages
+(by a 3\-line page header with \fB\-F\fR or a 5\-line header
+and trailer without \fB\-F\fR)
+.TP
+\fB\-h\fR, \fB\-\-header\fR=\fI\,HEADER\/\fR
+use a centered HEADER instead of filename in page header,
+\fB\-h\fR "" prints a blank line, don't use \fB\-h\fR""
+.TP
+\fB\-i[CHAR[WIDTH]]\fR, \fB\-\-output\-tabs\fR[=\fI\,CHAR[WIDTH]\/\fR]
+replace spaces with CHARs (TABs) to tab WIDTH (8)
+.TP
+\fB\-J\fR, \fB\-\-join\-lines\fR
+merge full lines, turns off \fB\-W\fR line truncation, no column
+alignment, \fB\-\-sep\-string\fR[=\fI\,STRING\/\fR] sets separators
+.TP
+\fB\-l\fR, \fB\-\-length\fR=\fI\,PAGE_LENGTH\/\fR
+set the page length to PAGE_LENGTH (66) lines
+(default number of lines of text 56, and with \fB\-F\fR 63).
+implies \fB\-t\fR if PAGE_LENGTH <= 10
+.TP
+\fB\-m\fR, \fB\-\-merge\fR
+print all files in parallel, one in each column,
+truncate lines, but join lines of full length with \fB\-J\fR
+.TP
+\fB\-n[SEP[DIGITS]]\fR, \fB\-\-number\-lines\fR[=\fI\,SEP[DIGITS]\/\fR]
+number lines, use DIGITS (5) digits, then SEP (TAB),
+default counting starts with 1st line of input file
+.TP
+\fB\-N\fR, \fB\-\-first\-line\-number\fR=\fI\,NUMBER\/\fR
+start counting with NUMBER at 1st line of first
+page printed (see +FIRST_PAGE)
+.TP
+\fB\-o\fR, \fB\-\-indent\fR=\fI\,MARGIN\/\fR
+offset each line with MARGIN (zero) spaces, do not
+affect \fB\-w\fR or \fB\-W\fR, MARGIN will be added to PAGE_WIDTH
+.TP
+\fB\-r\fR, \fB\-\-no\-file\-warnings\fR
+omit warning when a file cannot be opened
+.TP
+\fB\-s[CHAR]\fR, \fB\-\-separator\fR[=\fI\,CHAR\/\fR]
+separate columns by a single character, default for CHAR
+is the <TAB> character without \fB\-w\fR and 'no char' with \fB\-w\fR.
+\fB\-s[CHAR]\fR turns off line truncation of all 3 column
+options (\fB\-COLUMN\fR|\-a \fB\-COLUMN\fR|\-m) except \fB\-w\fR is set
+.TP
+\fB\-S[STRING]\fR, \fB\-\-sep\-string\fR[=\fI\,STRING\/\fR]
+separate columns by STRING,
+without \fB\-S\fR: Default separator <TAB> with \fB\-J\fR and <space>
+otherwise (same as \fB\-S\fR" "), no effect on column options
+.TP
+\fB\-t\fR, \fB\-\-omit\-header\fR
+omit page headers and trailers;
+implied if PAGE_LENGTH <= 10
+.TP
+\fB\-T\fR, \fB\-\-omit\-pagination\fR
+omit page headers and trailers, eliminate any pagination
+by form feeds set in input files
+.TP
+\fB\-v\fR, \fB\-\-show\-nonprinting\fR
+use octal backslash notation
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,PAGE_WIDTH\/\fR
+set page width to PAGE_WIDTH (72) characters for
+multiple text\-column output only, \fB\-s[char]\fR turns off (72)
+.TP
+\fB\-W\fR, \fB\-\-page\-width\fR=\fI\,PAGE_WIDTH\/\fR
+set page width to PAGE_WIDTH (72) characters always,
+truncate lines, except \fB\-J\fR option is set, no interference
+with \fB\-S\fR or \fB\-s\fR
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Pete TerMaat and Roland Huebner.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/pr>
+.br
+or available locally via: info \(aq(coreutils) pr invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/preconv.1 b/upstream/mageia-cauldron/man1/preconv.1
new file mode 100644
index 00000000..20caf9f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/preconv.1
@@ -0,0 +1,374 @@
+.TH PRECONV 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+preconv \- convert encoding of input files to something GNU troff \
+understands
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr preconv_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 2006-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY preconv
+.OP \-dr
+.OP \-D default_encoding
+.OP \-e encoding
+.RI [ file
+\&.\|.\|.\&]
+.
+.SY preconv
+.B \-h
+.SY preconv
+.B \-\-help
+.YS
+.
+.SY preconv
+.B \-v
+.SY preconv
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B preconv
+reads
+.I files
+and converts its encoding(s) to a form GNU
+.BR troff (1)
+can process, sending the data to standard output.
+.
+Currently, this means ASCII characters and \[oq]\e[uXXXX]\[cq]
+entities, where \[oq]XXXX\[cq] is a hexadecimal number with four to
+six digits, representing a Unicode input code.
+.
+Normally,
+.B preconv
+should be invoked with the
+.B \-k
+and
+.B \-K
+options of
+.BR groff .
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-d
+Emit debugging messages to standard error (mainly the used encoding).
+.
+.TP
+.BI \-D encoding
+Specify default encoding if everything fails (see below).
+.
+.TP
+.BI \-e encoding
+Specify input encoding explicitly, overriding all other methods.
+.
+This corresponds to
+.BR groff 's
+.BI \-K encoding
+option.
+.
+Without this switch,
+.B preconv
+uses the algorithm described below to select the input encoding.
+.
+.TP
+.B \-\-help
+.TQ
+.B \-h
+Print a help message and exit.
+.
+.TP
+.B \-r
+Do not add \&.lf requests.
+.
+.TP
+.B \-\-version
+.TQ
+.B \-v
+Print the version number and exit.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+.B preconv
+tries to find the input encoding with the following algorithm.
+.
+.IP 1.
+If the input encoding has been explicitly specified with option
+.BR \-e ,
+use it.
+.
+.IP 2.
+Otherwise, check whether the input starts with a
+.I Byte Order Mark
+(BOM, see below).
+.
+If found, use it.
+.
+.IP 3.
+Otherwise, check whether there is a known
+.I coding tag
+(see below) in either the first or second input line.
+.
+If found, use it.
+.
+.IP 4
+Finally, if the
+.B uchardet
+library
+(an encoding detector library available on most major distributions)
+is available on the system, use it to try to detect the encoding of the file.
+.
+.IP 5.
+If everything fails, use a default encoding as given with option
+.BR \-D ,
+by the current locale, or \[oq]latin1\[cq] if the locale is set to
+\[oq]C\[cq], \[oq]POSIX\[cq], or empty (in that order).
+.
+.
+.PP
+Note that the
+.B groff
+program supports a
+.I \%GROFF_ENCODING
+environment variable which is eventually expanded to option
+.BR \-k .
+.
+.
+.\" ====================================================================
+.SS "Byte Order Mark"
+.\" ====================================================================
+.
+The Unicode Standard defines character U+FEFF as the Byte Order Mark
+(BOM).
+.
+On the other hand, value U+FFFE is guaranteed not be a Unicode character at
+all.
+.
+This allows detection of the byte order within the data stream (either
+big-endian or little-endian), and the MIME encodings \%\[oq]UTF-16\[cq]
+and \%\[oq]UTF-32\[cq] mandate that the data stream starts with U+FEFF.
+.
+Similarly, the data stream encoded as \%\[oq]UTF-8\[cq] might start
+with a BOM (to ease the conversion from and to \%UTF-16 and \%UTF-32).
+.
+In all cases, the byte order mark is
+.I not
+part of the data but part of the encoding protocol; in other words,
+.BR preconv 's
+output doesn't contain it.
+.
+.
+.PP
+Note that U+FEFF not at the start of the input data actually is
+emitted; it has then the meaning of a \[oq]zero width no-break
+space\[cq] character \[en] something not needed normally in
+.BR groff .
+.
+.
+.\" ====================================================================
+.SS "Coding Tags"
+.\" ====================================================================
+.
+Editors which support more than a single character encoding need tags
+within the input files to mark the file's encoding.
+.
+While it is possible to guess the right input encoding with the help of
+heuristic algorithms for data which represents a greater amount of a natural
+language, it is still just a guess.
+.
+Additionally, all algorithms fail easily for input which is either too short
+or doesn't represent a natural language.
+.
+.
+.PP
+For these reasons,
+.B preconv
+supports the coding tag convention (with some restrictions) as used by
+.B "GNU Emacs"
+and
+.B XEmacs
+(and probably other programs too).
+.
+.
+.PP
+Coding tags in
+.B "GNU Emacs"
+and
+.B XEmacs
+are stored in so-called
+.IR "File Variables" .
+.
+.B preconv
+recognizes the following syntax form which must be put into a troff comment
+in the first or second line.
+.
+.RS
+.PP
+\-*\-
+.IR tag1 :
+.IR value1 ;
+.IR tag2 :
+.IR value2 ;
+\&.\|.\|.\& \-*\-
+.RE
+.
+.
+.PP
+The only relevant tag for
+.B preconv
+is \[oq]coding\[cq] which can take the values listed below.
+.
+Here an example line which tells
+.B Emacs
+to edit a file in troff mode, and to use \%latin2 as its encoding.
+.
+.RS
+.PP
+.EX
+\&.\[rs]" \-*\- mode: troff; coding: latin-2 \-*\-
+.EE
+.RE
+.
+.
+.PP
+The following list gives all MIME coding tags (either lowercase or
+uppercase) supported by
+.BR preconv ;
+this list is hard-coded in the source.
+.
+.RS
+.PP
+.ad l
+\%big5, \%cp1047, \%euc-jp, \%euc-kr, \%gb2312, \%iso-8859-1,
+\%iso-8859-2, \%iso-8859-5, \%iso-8859-7, \%iso-8859-9, \%iso-8859-13,
+\%iso-8859-15, \%koi8-r, \%us-ascii, \%utf-8, \%utf-16, \%utf-16be,
+\%utf-16le
+.ad
+.RE
+.
+.
+.PP
+In addition, the following hard-coded list of other tags is recognized
+which eventually map to values from the list above.
+.
+.RS
+.PP
+.ad l
+\%ascii, \%chinese-big5, \%chinese-euc, \%chinese-iso-8bit, \%cn-big5,
+\%\%cn-gb, \%cn-gb-2312, \%cp878, \%csascii, \%csisolatin1,
+\%cyrillic-iso-8bit, \%cyrillic-koi8, \%euc-china, \%euc-cn,
+\%euc-japan, \%euc-japan-1990, \%euc-korea, \%greek-iso-8bit,
+\%iso-10646/utf8, \%iso-10646/utf-8, \%iso-latin-1, \%iso-latin-2,
+\%iso-latin-5, \%iso-latin-7, \%iso-latin-9, \%japanese-euc,
+\%japanese-iso-8bit, \%jis8, \%koi8, \%korean-euc, \%korean-iso-8bit,
+\%latin-0, \%latin1, \%latin-1, \%latin-2, \%latin-5, \%latin-7,
+\%latin-9, \%mule-utf-8, \%mule-utf-16, \%mule-utf-16be,
+\%mule-utf-16-be, \%mule-utf-16be-with-signature, \%mule-utf-16le,
+\%mule-utf-16-le, \%mule-utf-16le-with-signature, \%utf8, \%utf-16-be,
+\%utf-16-be-with-signature, \%utf-16be-with-signature, \%utf-16-le,
+\%utf-16-le-with-signature, \%utf-16le-with-signature
+.ad
+.RE
+.
+.
+.PP
+Those tags are taken from
+.B "GNU Emacs"
+and
+.BR XEmacs ,
+together with some aliases.
+.
+Trailing \%\[oq]-dos\[cq], \%\[oq]-unix\[cq], and \%\[oq]-mac\[cq]
+suffixes of coding tags (which give the end-of-line convention used in
+the file) are stripped off before the comparison with the above tags
+happens.
+.
+.SS "Iconv Issues"
+.B preconv
+by itself only supports three encodings: \%latin-1, cp1047, and \%UTF-8;
+all other encodings are passed to the
+.B iconv
+library functions.
+.
+At compile time it is searched and checked for a valid
+.B iconv
+implementation; a call to \[oq]preconv \-\-version\[cq] shows whether
+.B iconv
+is used.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+.B preconv
+doesn't support
+.I "local variable lists"
+yet.
+.
+This is a different syntax form to specify local variables at the end of a
+file.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR groff (1)
+.br
+the
+.B "GNU Emacs"
+and
+.B XEmacs
+info pages
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[preconv_C]
+.
+.
+.\" Emacs setting
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/printafm.1 b/upstream/mageia-cauldron/man1/printafm.1
new file mode 100644
index 00000000..83b04307
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/printafm.1
@@ -0,0 +1,18 @@
+.TH PRINTAFM 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+printafm \- Print the metrics from a Postscript font in AFM format using ghostscript
+.SH SYNOPSIS
+\fBprintafm\fR \fIfontname\fR
+.SH DESCRIPTION
+This script invokes
+.BR gs (1)
+to print the metrics from a font in AFM format.
+Output goes to stdout.
+.SH SEE ALSO
+gs(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/printenv.1 b/upstream/mageia-cauldron/man1/printenv.1
new file mode 100644
index 00000000..caf7ffc4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/printenv.1
@@ -0,0 +1,41 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PRINTENV "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+printenv \- print all or part of environment
+.SH SYNOPSIS
+.B printenv
+[\fI\,OPTION\/\fR]... [\fI\,VARIABLE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the values of the specified environment VARIABLE(s).
+If no VARIABLE is specified, print name and value pairs for them all.
+.TP
+\fB\-0\fR, \fB\-\-null\fR
+end each output line with NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NOTE: your shell may have its own version of printenv, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by David MacKenzie and Richard Mlynarik.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/printenv>
+.br
+or available locally via: info \(aq(coreutils) printenv invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/printf.1 b/upstream/mageia-cauldron/man1/printf.1
new file mode 100644
index 00000000..041eae60
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/printf.1
@@ -0,0 +1,104 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PRINTF "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+printf \- format and print data
+.SH SYNOPSIS
+.B printf
+\fI\,FORMAT \/\fR[\fI\,ARGUMENT\/\fR]...
+.br
+.B printf
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print ARGUMENT(s) according to FORMAT, or execute according to OPTION:
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+FORMAT controls the output as in C printf.  Interpreted sequences are:
+.TP
+\e"
+double quote
+.TP
+\e\e
+backslash
+.TP
+\ea
+alert (BEL)
+.TP
+\eb
+backspace
+.TP
+\ec
+produce no further output
+.TP
+\ee
+escape
+.TP
+\ef
+form feed
+.TP
+\en
+new line
+.TP
+\er
+carriage return
+.TP
+\et
+horizontal tab
+.TP
+\ev
+vertical tab
+.TP
+\eNNN
+byte with octal value NNN (1 to 3 digits)
+.TP
+\exHH
+byte with hexadecimal value HH (1 to 2 digits)
+.TP
+\euHHHH
+Unicode (ISO/IEC 10646) character with hex value HHHH (4 digits)
+.TP
+\eUHHHHHHHH
+Unicode character with hex value HHHHHHHH (8 digits)
+.TP
+%%
+a single %
+.TP
+%b
+ARGUMENT as a string with '\e' escapes interpreted,
+except that octal escapes are of the form \e0 or \e0NNN
+.TP
+%q
+ARGUMENT is printed in a format that can be reused as shell input,
+escaping non\-printable characters with the proposed POSIX $'' syntax.
+.PP
+and all C format specifications ending with one of diouxXfeEgGcs, with
+ARGUMENTs converted to proper type first.  Variable widths are handled.
+.PP
+NOTE: your shell may have its own version of printf, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBprintf\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/printf>
+.br
+or available locally via: info \(aq(coreutils) printf invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/procmail.1 b/upstream/mageia-cauldron/man1/procmail.1
new file mode 100644
index 00000000..b8c33795
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/procmail.1
@@ -0,0 +1,917 @@
+.\"if n .pl +(135i-\n(.pu)
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.Id $Id$
+.TH PROCMAIL 1 \*(Dt BuGless
+.rn SH Sh
+.de SH
+.br
+.ne 11
+.Sh "\\$1"
+..
+.rn SS Ss
+.de SS
+.br
+.ne 10
+.Ss "\\$1"
+..
+.rn TP Tp
+.de TP
+.br
+.ne 9
+.Tp \\$1
+..
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.na
+.SH NAME
+procmail \- autonomous mail processor
+.SH SYNOPSIS
+.B procmail
+.RB [ \-ptoY ]
+.RB [ "\-f \fIfromwhom\fP" ]
+.if n .ti +0.5i
+.RI [ "parameter\fB=\fPvalue " | " rcfile" ]
+\&.\|.\|.
+.br
+.B procmail
+.RB [ \-toY ]
+.RB [ "\-f \fIfromwhom\fP" ]
+.RB [ "\-a \fIargument\fP" ]
+\&.\|.\|.
+.if n .ti +0.5i
+.B \-d
+.I recipient
+\&.\|.\|.
+.br
+.B procmail
+.RB [ \-ptY ]
+.B \-m
+.RI [ "parameter\fB=\fPvalue" ]
+\&.\|.\|.
+.I rcfile
+.if n .ti +0.5i
+.RI [ argument ]
+\&.\|.\|.
+.br
+.B procmail
+.B \-v
+.ad
+.SH DESCRIPTION
+For a quick start, see
+.B NOTES
+at the end.
+.PP
+.B Procmail
+should be invoked automatically over the
+.B .forward
+file mechanism as soon as mail arrives.  Alternatively, when installed by
+a system administrator, it can be invoked from within the mailer immediately.
+When invoked, it first sets some environment variables to default values,
+reads the mail message from stdin until an EOF, separates the body from the
+header, and then, if no command line arguments are present, it starts to look
+for a file named
+.BR $HOME/.procmailrc .
+According to the processing recipes in this file,
+the mail message that just arrived gets distributed into the right folder
+(and more).  If no rcfile is found, or processing of the rcfile falls off
+the end, procmail will store the mail in the default system
+mailbox.
+.PP
+If no rcfiles and no
+.B \-p
+have been specified on the command line, procmail will, prior to reading $HOME/.procmailrc, interpret commands from
+.B /etc/procmailrc
+(if present).
+Care must be taken when creating /etc/procmailrc, because, if circumstances permit, it will be executed with root privileges (contrary to the $HOME/.procmailrc file of course).
+.PP
+If running suid root or with root privileges, procmail will be able to
+perform as a functionally enhanced, backwards compatible mail delivery agent.
+.PP
+Procmail can also be used as a general purpose mail filter, i.e., provisions
+have been made to enable procmail to be invoked in a special sendmail rule.
+.PP
+The rcfile format is described in detail in the
+.BR procmailrc (5)
+man page.
+.PP
+The weighted scoring technique is described in detail in the
+.BR procmailsc (5)
+man page.
+.PP
+Examples for rcfile recipes can be looked up in the
+.BR procmailex (5)
+man page.
+.SS Signals
+.TP 1.2i
+.B TERMINATE
+Terminate prematurely and requeue the mail.
+.TP
+.B HANGUP
+Terminate prematurely and bounce the mail.
+.TP
+.B INTERRUPT
+Terminate prematurely and bounce the mail.
+.TP
+.B QUIT
+Terminate prematurely and silently lose the mail.
+.TP
+.B ALARM
+Force a timeout (see
+.BR TIMEOUT).
+.TP
+.B USR1
+Equivalent to a
+.BR VERBOSE =off.
+.TP
+.B USR2
+Equivalent to a
+.BR VERBOSE =on.
+.SH OPTIONS
+.TP 0.5i
+.B \-v
+Procmail will print its version number, display its compile time
+configuration and exit.
+.TP
+.B \-p
+Preserve any old environment.  Normally procmail clears the environment
+upon startup, except for the value of TZ.  However, in any case: any default values will override
+any preexisting environment variables, i.e., procmail will not pay any attention
+to any predefined environment variables, it will happily overwrite them
+with its own defaults.  For the list of environment variables that procmail
+will preset see the
+.BR procmailrc (5)
+man page.  If both \-p and \-m are specified, the
+list of preset environment variables shrinks to just: LOGNAME, HOME, SHELL,
+USER_SHELL, ORGMAIL and MAILDIR.
+.TP
+.B \-t
+Make procmail fail softly, i.e., if procmail cannot deliver the mail to
+any of the destinations you gave, the mail will not bounce, but will return
+to the mailqueue.  Another delivery-attempt will be made at some time in
+the future.
+.TP
+.I "\fB\-f\fP fromwhom"
+Causes procmail to regenerate the leading `From ' line with
+.I fromwhom
+as the sender (instead of \-f one could use the alternate and
+obsolete \-r).  If
+.I fromwhom
+consists merely of a single `-', then procmail will only
+update the timestamp on the `From ' line (if present, if not, it will
+generate a new one).
+.TP
+.B \-o
+Instead of allowing anyone to generate `From ' lines, simply override
+the fakes.
+.TP
+.B \-Y
+Assume traditional Berkeley mailbox format, ignore any
+.B Content-Length:
+fields.
+.TP
+.I "\fB\-a\fP argument"
+This will set $1 to be equal to
+.IR argument .
+Each succeeding
+.I "\fB\-a\fP argument"
+will set the next number variable ($2, $3, etc).  It can be used
+to pass meta information along to procmail.  This is typically done
+by passing along the $@x information from the sendmail mailer rule.
+.TP
+.I "\fB\-d\fP recipient .\|.\|."
+This turns on explicit delivery mode, delivery will be to the local user
+.IR recipient .
+This, of course, only is possible if procmail has root
+privileges (or if procmail is already running with the recipient's euid and egid).
+Procmail will setuid to the intended recipients and delivers the mail as
+if it were invoked by the recipient with no arguments (i.e., if no rcfile
+is found, delivery is like ordinary mail).  This option is incompatible with
+.BR \-p .
+.TP
+.B \-m
+Turns procmail into a general purpose mail filter.  In this mode one rcfile
+must be specified on the command line.  After the rcfile, procmail will
+accept an unlimited number of arguments.
+If the rcfile is an absolute path starting with
+.B /etc/procmailrcs/
+without backward references (i.e. the parent directory cannot be mentioned) procmail will, only if no security violations are found, take on the identity of the owner of the rcfile (or symbolic link).
+For some advanced usage of this option you should look in the
+.B EXAMPLES
+section below.
+.SH ARGUMENTS
+Any arguments containing an '=' are considered to be environment variable
+assignments, they will
+.I all
+be evaluated after the default values have been
+assigned and before the first rcfile is opened.
+.PP
+Any other arguments are presumed to be rcfile paths (either absolute,
+or if they start with `./' relative to the current
+directory;
+.B any other relative
+path is relative to $HOME, unless the
+.B \-m
+option has been given, in which case all relative paths are relative to the
+current directory); procmail will start with the first one it finds on the
+command line.  The following ones will only be parsed if the preceding ones
+have a not matching HOST-directive entry, or in case they should not exist.
+.PP
+If no rcfiles are specified, it looks for
+.BR $HOME/.procmailrc .
+If not even that can be found, processing will continue according to
+the default settings of the environment variables and the ones specified
+on the command line.
+.SH EXAMPLES
+Examples for rcfile recipes can be looked up in the
+.BR procmailex (5)
+man page.
+A small sample rcfile can be found in the
+.B NOTES
+section below.
+.PP
+Skip the rest of this EXAMPLES section unless you are a system administrator
+who is vaguely familiar with sendmail.cf syntax.
+.PP
+The
+.B \-m
+option is typically used when procmail is called from within a rule in the
+sendmail.cf file.  In order to be able to do this it is convenient to create
+an extra `procmail' mailer in your sendmail.cf file (in addition to the perhaps
+already present `local' mailer that starts up procmail).  To create such a
+`procmail' mailer I'd suggest something like:
+.Sx 2
+Mprocmail, P=/usr/bin/procmail, F=mSDFMhun, S=11, R=21,
+        A=procmail \-m $h $g $u
+.Ex
+This enables you to use rules like the following (most likely in ruleset 0)
+to filter mail through the procmail mailer (please note the leading tab
+to continue the rule, and the tab to separate the comments):
+.Sx 4
+R$*<@some.where>$*
+        $#procmail $@/etc/procmailrcs/some.rc $:$1@some.where.procmail$2
+R$*<@$*.procmail>$*
+        $1<@$2>$3       Already filtered, map back
+.Ex
+And /etc/procmailrcs/some.rc could be as simple as:
+.Sx 9
+SENDER = "<$1>"                 # fix for empty sender addresses
+SHIFT = 1                       # remove it from $@
+
+:0                              # sink all junk mail
+* ^Subject:.*junk
+/dev/null
+
+:0 w                            # pass along all other mail
+! \-oi \-f "$SENDER" "$@"
+.Ex
+Do watch out when sending mail from within the /etc/procmailrcs/some.rc file,
+if you send mail to addresses which match the first rule again, you could
+be creating an endless mail loop.
+.SH FILES
+.TP 2.3i
+.B /etc/passwd
+to set the recipient's LOGNAME, HOME and USER_SHELL variable defaults
+.TP
+.B /var/spool/mail/$LOGNAME
+system mailbox; both the system mailbox and the immediate directory
+it is in will be created every time procmail starts and either one is
+not present
+.TP
+.B /etc/procmailrc
+initial global rcfile
+.TP
+.B /etc/procmailrcs/
+special privileges path for rcfiles
+.TP
+.B $HOME/.procmailrc
+default rcfile
+.TP
+.B /var/spool/mail/$LOGNAME.lock
+lockfile for the system mailbox (not automatically used by procmail, unless
+$DEFAULT equals /var/spool/mail/$LOGNAME and procmail is delivering to $DEFAULT)
+.TP
+.B /usr/sbin/sendmail
+default mail forwarder
+.TP
+.B _????`hostname`
+temporary `unique' zero-length files created by procmail
+.SH "SEE ALSO"
+.na
+.nh
+.BR procmailrc (5),
+.BR procmailsc (5),
+.BR procmailex (5),
+.BR sh (1),
+.BR csh (1),
+.BR mail (1),
+.BR mailx (1),
+.BR uucp (1),
+.BR aliases (5),
+.BR sendmail (8),
+.BR egrep (1),
+.BR grep (1),
+.BR biff (1),
+.BR comsat (8),
+.BR lockfile (1),
+.BR formail (1),
+.BR cron (1)
+.hy
+.ad
+.SH DIAGNOSTICS
+.TP 2.3i
+Autoforwarding mailbox found
+The system mailbox had its suid or sgid bit set, procmail terminates with
+EX_NOUSER assuming that this mailbox must not be delivered to.
+.TP
+Bad substitution of "x"
+Not a valid environment variable name specified.
+.TP
+Closing brace unexpected
+There was no corresponding opening brace (nesting block).
+.TP
+Conflicting options
+Not all option combinations are useful
+.TP
+Conflicting x suppressed
+Flag x is not compatible with some other flag on this recipe.
+.TP
+Couldn't create "x"
+The system mailbox was missing and could not/will not be created.
+.TP
+Couldn't create maildir part "x"
+The maildir folder "x" is missing one or more required subdirectories and
+procmail could not create them.
+.TP
+Couldn't create or rename temp file "x"
+An error occurred in the mechanics of  delivering to the directory folder "x".
+.TP
+Couldn't determine implicit lockfile from "x"
+There were no `>>' redirectors to be found, using simply `$LOCKEXT' as
+locallockfile.
+.TP
+Couldn't read "x"
+Procmail was unable to open an rcfile or it was not a regular file, or
+procmail couldn't open an MH directory to find the highest numbered file.
+.TP
+Couldn't unlock "x"
+Lockfile was already gone, or write permission to the directory where the
+lockfile is has been denied.
+.TP
+Deadlock attempted on "x"
+The locallockfile specified on this recipe is equal to a still active
+$LOCKFILE.
+.TP
+Denying special privileges for "x"
+Procmail will not take on the identity that comes with the rcfile because
+a security violation was found (e.g. 
+.B \-p
+or variable assignments on the command line) or procmail had insufficient privileges to do so.
+.TP
+Descriptor "x" was not open
+As procmail was started, stdin, stdout or stderr was not connected (possibly
+an attempt to subvert security)
+.TP
+Enforcing stricter permissions on "x"
+The system mailbox of the recipient was found to be unsecured, procmail
+secured it.
+.TP
+Error while writing to "x"
+Nonexistent subdirectory, no write permission, pipe died or disk full.
+.TP
+Exceeded LINEBUF
+Buffer overflow detected, LINEBUF was too small, PROCMAIL_OVERFLOW has
+been set.
+.TP
+MAILDIR is not an absolute path
+.TP
+MAILDIR path too long
+.TP
+ORGMAIL is not an absolute path
+.TP
+ORGMAIL path too long
+.TP
+default rcfile is not an absolute path
+.TP
+default rcfile path too long
+The specified item's full path, when expanded, was longer than LINEBUF
+or didn't start with a file separator.
+.TP
+Excessive output quenched from "x"
+The backquoted expression "x" tried to produce too much output for
+the current LINEBUF; the rest was discarded and PROCMAIL_OVERFLOW
+has been set.
+.TP
+Extraneous x ignored
+The action line or other flags on this recipe make x meaningless.
+.TP
+Failed forking "x"
+Process table is full (and NORESRETRY has been exhausted).
+.TP
+Failed to execute "x"
+Program not in path, or not executable.
+.TP
+Forced unlock denied on "x"
+No write permission in the directory where
+.B lockfile
+"x" resides, or more than one procmail trying to force a lock at exactly the
+same time.
+.TP
+Forcing lock on "x"
+.B Lockfile
+"x" is going to be removed by force because of a timeout (see also:
+.BR LOCKTIMEOUT ).
+.TP
+Incomplete recipe
+The start of a recipe was found, but it stranded in an EOF.
+.TP
+Insufficient privileges
+Procmail either needs root privileges, or must have the
+right (e)uid
+.B and
+(e)gid to run in delivery mode.  The mail will bounce.
+.TP
+Invalid regexp "x"
+The regular expression "x" contains errors (most likely some missing or
+extraneous parens).
+.TP
+Kernel-lock failed
+While trying to use the kernel-supported locking calls, one of them failed
+(usually indicates an OS error), procmail ignores this error and proceeds.
+.TP
+Kernel-unlock failed
+See above.
+.TP
+Lock failure on "x"
+Can only occur if you specify some real weird (and illegal) lockfilenames
+or if the
+.B lockfile
+could not be created because of insufficient permissions or nonexistent
+subdirectories.
+.TP
+Lost "x"
+Procmail tried to clone itself but could not find back rcfile "x" (it either
+got removed or it was a relative path and you changed directory since
+procmail opened it last time).
+.TP
+Missing action
+The current recipe was found to be incomplete.
+.TP
+Missing closing brace
+A nesting block was started, but never finished.
+.TP
+Missing name
+The \-f option needs an extra argument.
+.TP
+Missing argument
+You specified the \-a option but forgot the argument.
+.TP
+Missing rcfile
+You specified the \-m option, procmail expects the name of an
+rcfile as argument.
+.TP
+Missing recipient
+You specified the \-d option or called procmail under a different
+name, it expects one or more recipients as arguments.
+.TP
+No space left to finish writing "x"
+The filesystem containing "x" does not have enough free space to permit
+delivery of the message to the file.
+.TP
+Out of memory
+The system is out of swap space (and NORESRETRY has been exhausted).
+.TP
+Processing continued
+The unrecognised options on the command line are ignored, proceeding as
+usual.
+.TP
+Program failure (nnn) of "x"
+Program that was started by procmail returned nnn instead of
+EXIT_SUCCESS (=0);
+if nnn is negative, then this is the signal the program died on.
+.TP
+Quota exceeded while writing "x"
+The filesize quota for the recipient on the filesystem containing "x"
+does not permit delivering the message to the file.
+.TP
+Renaming bogus "x" into "x"
+The system mailbox of the recipient was found to be bogus, procmail performed
+evasive actions.
+.TP
+Rescue of unfiltered data succeeded/failed
+A filter returned unsuccessfully, procmail tried to get back the original text.
+.TP
+Skipped: "x"
+Couldn't do anything with "x" in the rcfile (syntax error), ignoring it.
+.TP
+Suspicious rcfile "x"
+The owner of the rcfile was not the recipient or root, the file was
+world writable, or the directory that contained it was world writable,
+or this was the default rcfile ($HOME/.procmailrc) and either it was group
+writable or the directory that contained it was group writable (the
+rcfile was not used).
+.TP
+Terminating prematurely whilst waiting for .\|.\|.
+Procmail received a signal while it was waiting for .\|.\|.
+.TP
+Timeout, terminating "x"
+Timeout has occurred on program or filter "x".
+.TP
+Timeout, was waiting for "x"
+Timeout has occurred on program, filter or file "x".  If it was a program or
+filter, then it didn't seem to be running anymore.
+.TP
+Truncated file to former size
+The file could not be delivered to successfully, so the file was truncated
+to its former size.
+.TP
+Truncating "x" and retrying lock
+"x" does not seem to be a valid filename or the file is not empty.
+.TP
+Unable to treat as directory "x"
+Either the suffix on "x" would indicate that it should be an MH or
+maildir folder, or it was listed as an second folder into which to link,
+but it already exists and is not a directory.
+.TP
+Unexpected EOL
+Missing closing quote, or trying to escape EOF.
+.TP
+Unknown user "x"
+The specified recipient does not have a corresponding uid.
+.SH "EXTENDED DIAGNOSTICS"
+Extended diagnostics can be turned on and off through setting the
+VERBOSE variable.
+.TP 2.3i
+[pid] time & date
+Procmail's pid and a timestamp.  Generated whenever procmail logs a
+diagnostic and at least a second has elapsed since the last timestamp.
+.TP
+Acquiring kernel-lock
+Procmail now tries to kernel-lock the most recently opened file (descriptor).
+.TP
+Assigning "x"
+Environment variable assignment.
+.TP
+Assuming identity of the recipient, VERBOSE=off
+Dropping all privileges (if any), implicitly turns off extended diagnostics.
+.TP
+Bypassed locking "x"
+The mail spool directory was not accessible to procmail, it relied solely
+on kernel locks.
+.TP
+Executing "x"
+Starting program "x".  If it is started by procmail directly (without an
+intermediate shell), procmail will show where it separated the arguments
+by inserting commas.
+.TP
+HOST mismatched "x"
+This host was called "x", HOST contained something else.
+.TP
+Locking "x"
+Creating lockfile "x".
+.TP
+Linking to "x"
+Creating a hardlink between directory folders.
+.TP
+Match on "x"
+Condition matched.
+.TP
+Matched "x"
+Assigned "x" to
+.BR MATCH .
+.TP
+No match on "x"
+Condition didn't match, recipe skipped.
+.TP
+Non-zero exitcode (nnn) by "x"
+Program that was started by procmail as a condition or as the action of
+a recipe with the `W' flag returned nnn instead of
+EXIT_SUCCESS (=0); the usage indicates that this is not an
+entirely unexpected condition.
+.TP
+Notified comsat: "$LOGNAME@offset:file"
+Sent comsat/biff a notice that mail arrived for user $LOGNAME at `offset'
+in `file'.
+.TP
+Opening "x"
+Opening file "x" for appending.
+.TP
+Rcfile: "x"
+Rcfile changed to "x".
+.TP
+Reiterating kernel-lock
+While attempting several locking methods, one of these failed.  Procmail will
+reiterate until they all succeed in rapid succession.
+.TP
+Score: added newtotal "x"
+This condition scored `added' points, which resulted in a `newtotal' score.
+.TP
+Unlocking "x"
+Removing lockfile "x" again.
+.SH WARNINGS
+You should create a shell script that uses
+.BR lockfile (1)
+before invoking your mail shell on any mailbox file other than the system
+mailbox (unless of course, your mail shell uses the same lockfiles (local
+or global) you specified in your rcfile).
+.PP
+In the unlikely event that you absolutely need to kill procmail before it has
+finished, first try and use the regular kill command (i.e.,
+.I not
+kill \-9, see the subsection
+.I Signals
+for suggestions), otherwise some
+.I lockfiles
+might not get removed.
+.PP
+Beware when using the
+.B \-t
+option, if procmail repeatedly is unable to deliver the mail (e.g., due to
+an incorrect rcfile), the system mailqueue could fill up.  This could
+aggravate both the local postmaster and other users.
+.PP
+The
+.B /etc/procmailrc
+file might be executed with root privileges, so be very careful of what you put in it.
+.B SHELL
+will be equal to that of the current recipient, so if procmail has to invoke the shell, you'd better set it to some safe value first.
+See also\h'-\w' 'u' :
+.BR DROPPRIVS .
+.PP
+Keep in mind that if
+.BR chown (1)
+is permitted on files in
+.BR /etc/procmailrcs/ ,
+that they can be chowned to root (or anyone else) by their current owners.
+For maximum security, make sure this directory is
+.I executable
+to root only.
+.PP
+Procmail is not the proper tool for sharing one mailbox among many
+users, such as when you have one POP account for all mail to your
+domain. It can be done if you manage to configure your MTA to add some
+headers with the envelope recipient data in order to tell Procmail who
+a message is for, but this is usually not the right thing to do.
+Perhaps you want to investigate if your MTA offers `virtual user
+tables', or check out the `multidrop' facility of Fetchmail.
+.SH BUGS
+After removing a lockfile by force, procmail waits $SUSPEND seconds before
+creating a new lockfile so that another process that decides to remove the
+stale lockfile will not remove the newly created lock by mistake.
+.PP
+Procmail uses the regular TERMINATE signal to terminate any runaway filter,
+but it does not check if the filter responds to that signal and it only sends
+it to the filter itself, not to any of the filter's children.
+.PP
+A continued
+.B Content-Length:
+field is not handled correctly.
+.PP
+The embedded newlines in a continued header should be skipped when
+matching instead of being treated as a single space as they are now.
+.SH MISCELLANEOUS
+If there is an existing
+.B Content-Length:
+field in the header of the mail and the
+.B \-Y
+option is not specified, procmail will trim the field to report the correct
+size.  Procmail does not change the fieldwidth.
+.PP
+If there is no
+.B Content-Length:
+field or the
+.B \-Y
+option has been specified and procmail appends to regular mailfolders, any
+lines in the body of the message that look like postmarks are prepended with
+`>' (disarms bogus mailheaders).  The regular expression that is used
+to search for these postmarks is:
+.RS
+`\\nFrom '
+.RE
+.PP
+If the destination name used in explicit delivery mode is not in /etc/passwd,
+procmail will proceed as if explicit delivery mode was not in effect.
+If not in explicit delivery mode and
+should the uid procmail is running under, have no corresponding /etc/passwd
+entry, then HOME will default to /, LOGNAME will default to #uid,
+USER_SHELL will default to /bin/sh, and ORGMAIL will default to
+/tmp/dead.letter.
+.PP
+When in explicit delivery mode, procmail will generate a leading `From '
+line if none is present.  If one is already present procmail will leave it
+intact.  If procmail is not invoked with one of the following user or group ids\h'-\w' 'u' : root, daemon, uucp, mail, x400, network, list, slist, lists or news, but still has to generate or accept a new `From ' line,
+it will generate an additional `>From ' line to help distinguish
+fake mails.
+.PP
+For security reasons procmail will only use an absolute or
+$HOME-relative rcfile if it is owned by the recipient or root, not
+world writable, and the directory it is contained in is not world
+writable.  The $HOME/.procmailrc file has the additional constraint of not
+being group-writable or in a group-writable directory.
+.PP
+If /var/spool/mail/$LOGNAME is a bogus mailbox (i.e., does not belong to the
+recipient, is unwritable, is a symbolic link or is a hard link), procmail will
+upon startup try to rename it into a file starting
+with `BOGUS.$LOGNAME.' and
+ending in an inode-sequence-code.  If this turns out to be impossible,
+.B ORGMAIL
+will have
+.I no
+initial value, and hence will inhibit delivery without a proper rcfile.
+.PP
+If /var/spool/mail/$LOGNAME already is a valid mailbox, but has got too loose
+permissions on it, procmail will correct this.  To prevent procmail from doing
+this make sure the u+x bit is set.
+.PP
+When delivering to directories, MH folders, or maildir folders, you
+.B don't
+need to use lockfiles to prevent several concurrently running procmail
+programs from messing up.
+.PP
+Delivering to MH folders is slightly more time consuming than delivering
+to normal directories or mailboxes, because procmail has to search for
+the next available number (instead of having the filename immediately
+available).
+.PP
+On general failure procmail will return EX_CANTCREAT, unless option
+.B \-t
+is specified, in which case it will return EX_TEMPFAIL.
+.PP
+To make `egrepping' of headers more consistent, procmail concatenates all
+continued header fields; but only internally.  When delivering the mail, line
+breaks will appear as before.
+.PP
+If procmail is called under a name not starting with `procmail' (e.g., if it
+is linked to another name and invoked as such), it comes up in explicit
+delivery mode, and expects the recipients' names as command line arguments
+(as if \-d had been specified).
+.PP
+Comsat/biff notifications are done using udp.  They are sent off
+once when procmail generates the regular logfile entry.  The notification
+messages have the following extended format (or as close as you can get when
+final delivery was not to a file):
+.RS
+$LOGNAME@offset_of_message_in_mailbox\h'-\w' 'u' :absolute_path_to_mailbox
+.RE
+.PP
+Whenever procmail itself opens a file to deliver to, it
+consistently uses the following kernel locking strategies\h'-\w' 'u' :
+.BR fcntl (2).
+.PP
+Procmail is NFS-resistant and eight-bit clean.
+.br
+.ne 11
+.SH NOTES
+Calling up procmail with the \-h or \-? options will cause
+it to display a command-line help and recipe flag quick-reference page.
+.PP
+There exists an excellent newbie FAQ about mailfilters (and procmail
+in particular); it is maintained by Nancy McGough <nancym@ii.com>
+and can be obtained by sending a mail to mail-server@rtfm.mit.edu with
+the following in the body:
+.RS
+send usenet/news.answers/mail/filtering-faq
+.RE
+.PP
+If procmail is
+.I not
+installed globally as the default mail delivery agent (ask your system administrator), you have to make sure it is invoked when your mail arrives.
+In this case your $HOME/.forward (beware, it
+.B has
+to be world readable) file should contain the line below.  Be sure to include
+the single and double quotes, and unless you know your site to be running
+smrsh (the SendMail Restricted SHell), it must be an
+.I absolute
+path.The \efB#\efP\efIYOUR_USERNAME\efP is not actually a
+parameter that is required by procmail, in fact, it will be discarded by
+sh before procmail ever sees it; it is however a necessary kludge against
+overoptimising sendmail programs\h'-\w' 'u' :
+
+.PP
+.na
+.nf
+"\h'-\w' 'u' |IFS=' '&&p=/usr/bin/procmail&&test -f $p&&exec $p -Yf-\h'-\w' 'u' |\h'-\w' 'u' |exit 75 \fB#\fP\fIYOUR_USERNAME\fP"
+.fi
+.ad
+.PP
+Some mailers (notably exim) do not currently accept the above syntax.
+In such case use this instead:
+.PP
+.na
+.nf
+|/usr/bin/procmail
+.fi
+.ad
+.PP
+Procmail can also be invoked to postprocess an already filled system
+mailbox.  This can be useful if you don't want to or can't use a
+$HOME/.forward file (in which case the following script could
+periodically be called from within
+.BR cron (1),
+or whenever you start reading mail):
+.Sx 17
+#!/bin/sh
+
+ORGMAIL=/var/spool/mail/$LOGNAME
+
+if cd $HOME &&
+ test \-s $ORGMAIL &&
+ lockfile \-r0 \-l1024 .newmail.lock 2>/dev/null
+then
+  trap "rm \-f .newmail.lock" 1 2 3 13 15
+  umask 077
+  lockfile \-l1024 \-ml
+  cat $ORGMAIL >>.newmail &&
+   cat /dev/null >$ORGMAIL
+  lockfile \-mu
+  formail \-s procmail <.newmail &&
+   rm \-f .newmail
+  rm \-f .newmail.lock
+fi
+exit 0
+.Ex
+.ne 14
+.SS "A sample small $HOME/.procmailrc:"
+.na
+.nf
+PATH=/usr/local/bin:/bin:/usr/bin
+MAILDIR=$HOME/Mail      #you'd better make sure it exists
+DEFAULT=$MAILDIR/mbox   #completely optional
+LOGFILE=$MAILDIR/from   #recommended
+
+:0:
+* ^From.*berg
+from_me
+
+:0
+* ^Subject:.*Flame
+/dev/null
+.fi
+.ad
+.PP
+Other examples for rcfile recipes can be looked up in the
+.BR procmailex (5)
+man page.
+.Sh SOURCE
+This program is part of the
+.I procmail mail-processing-package
+(v3.24) available at http://www.procmail.org/ or
+ftp.procmail.org in
+.BR pub/procmail/ .
+.Sh MAILINGLIST
+There exists a mailinglist for questions relating to any program in the
+procmail package:
+.RS
+<procmail-users@procmail.org>
+.RS
+for submitting questions/answers.
+.RE
+<procmail-users-request@procmail.org>
+.RS
+for subscription requests.
+.RE
+.PP
+.RE
+If you would like to stay informed about new versions and official patches send
+a subscription request to
+.RS
+procmail-announce-request@procmail.org
+.RE
+(this is a readonly list).
+.SH AUTHORS
+Stephen R. van den Berg
+.RS
+<srb@cuci.nl>
+.RE
+.\".if n .pl -(\n(.tu-1i)
+.rm SH
+.rn Sh SH
+.rm SS
+.rn Ss SS
+.rm TP
+.rn Tp TP
+.rm RS
+.rn Rs RS
+.rm RE
+.rn Re RE
diff --git a/upstream/mageia-cauldron/man1/profiles.1 b/upstream/mageia-cauldron/man1/profiles.1
new file mode 100644
index 00000000..6a82847e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/profiles.1
@@ -0,0 +1,136 @@
+'\" t
+.\"     Title: profiles
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/25/2024
+.\"    Manual: User Commands
+.\"    Source: Samba 4.19.5
+.\"  Language: English
+.\"
+.TH "PROFILES" "1" "02/25/2024" "Samba 4\&.19\&.5" "User Commands"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+profiles \- A utility to report and change SIDs in registry files
+.SH "SYNOPSIS"
+.HP \w'\ 'u
+profiles [\-c|\-\-change\-sid=STRING] [\-n|\-\-new\-sid=STRING] [\-v|\-\-verbose] [\-?|\-\-help] [\-\-usage] [\-d|\-\-debuglevel=DEBUGLEVEL] [\-\-debug\-stdout] [\-\-configfile=CONFIGFILE] [\-\-option=name=value] [\-l|\-\-log\-basename=LOGFILEBASE] [\-\-leak\-report] [\-\-leak\-report\-full] {FILE}
+.SH "DESCRIPTION"
+.PP
+This tool is part of the
+\fBsamba\fR(7)
+suite\&.
+.PP
+profiles
+is a utility that reports and changes SIDs in windows registry files\&. It currently only supports NT\&.
+.SH "OPTIONS"
+.PP
+file
+.RS 4
+Registry file to view or edit\&.
+.RE
+.PP
+\-v,\-\-verbose
+.RS 4
+Increases verbosity of messages\&.
+.RE
+.PP
+\-c SID1 \-n SID2, \-\-change\-sid SID1 \-\-new\-sid SID2
+.RS 4
+Change all occurrences of SID1 in
+file
+by SID2\&.
+.RE
+.PP
+\-d|\-\-debuglevel=DEBUGLEVEL
+.RS 4
+\fIlevel\fR
+is an integer from 0 to 10\&. The default value if this parameter is not specified is 1 for client applications\&.
+.sp
+The higher this value, the more detail will be logged to the log files about the activities of the server\&. At level 0, only critical errors and serious warnings will be logged\&. Level 1 is a reasonable level for day\-to\-day running \- it generates a small amount of information about operations carried out\&.
+.sp
+Levels above 1 will generate considerable amounts of log data, and should only be used when investigating a problem\&. Levels above 3 are designed for use only by developers and generate HUGE amounts of log data, most of which is extremely cryptic\&.
+.sp
+Note that specifying this parameter here will override the
+\m[blue]\fBlog level\fR\m[]
+parameter in the
+/etc/samba/smb\&.conf
+file\&.
+.RE
+.PP
+\-\-debug\-stdout
+.RS 4
+This will redirect debug output to STDOUT\&. By default all clients are logging to STDERR\&.
+.RE
+.PP
+\-\-configfile=<configuration file>
+.RS 4
+The file specified contains the configuration details required by the client\&. The information in this file can be general for client and server or only provide client specific like options such as
+\m[blue]\fBclient smb encrypt\fR\m[]\&. See
+/etc/samba/smb\&.conf
+for more information\&. The default configuration file name is determined at compile time\&.
+.RE
+.PP
+\-\-option=<name>=<value>
+.RS 4
+Set the
+\fBsmb.conf\fR(5)
+option "<name>" to value "<value>" from the command line\&. This overrides compiled\-in defaults and options read from the configuration file\&. If a name or a value includes a space, wrap whole \-\-option=name=value into quotes\&.
+.RE
+.PP
+\-l|\-\-log\-basename=logdirectory
+.RS 4
+Base directory name for log/debug files\&. The extension
+\fB"\&.progname"\fR
+will be appended (e\&.g\&. log\&.smbclient, log\&.smbd, etc\&.\&.\&.)\&. The log file is never removed by the client\&.
+.RE
+.PP
+\-\-leak\-report
+.RS 4
+Enable talloc leak reporting on exit\&.
+.RE
+.PP
+\-\-leak\-report\-full
+.RS 4
+Enable full talloc leak reporting on exit\&.
+.RE
+.PP
+\-V|\-\-version
+.RS 4
+Prints the program version number\&.
+.RE
+.PP
+\-?|\-\-help
+.RS 4
+Print a summary of command line options\&.
+.RE
+.PP
+\-\-usage
+.RS 4
+Display brief usage message\&.
+.RE
+.SH "VERSION"
+.PP
+This man page is part of version 4\&.19\&.5 of the Samba suite\&.
+.SH "AUTHOR"
+.PP
+The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
+.PP
+The profiles man page was written by Jelmer Vernooij\&.
diff --git a/upstream/mageia-cauldron/man1/prove.1 b/upstream/mageia-cauldron/man1/prove.1
new file mode 100644
index 00000000..77b3587b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/prove.1
@@ -0,0 +1,478 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PROVE 1"
+.TH PROVE 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+prove \- Run tests through a TAP harness.
+.SH USAGE
+.IX Header "USAGE"
+.Vb 1
+\& prove [options] [files or directories]
+.Ve
+.SH OPTIONS
+.IX Header "OPTIONS"
+Boolean options:
+.PP
+.Vb 10
+\& \-v,  \-\-verbose         Print all test lines.
+\& \-l,  \-\-lib             Add \*(Aqlib\*(Aq to the path for your tests (\-Ilib).
+\& \-b,  \-\-blib            Add \*(Aqblib/lib\*(Aq and \*(Aqblib/arch\*(Aq to the path for
+\&                        your tests
+\& \-s,  \-\-shuffle         Run the tests in random order.
+\& \-c,  \-\-color           Colored test output (default).
+\&      \-\-nocolor         Do not color test output.
+\&      \-\-count           Show the X/Y test count when not verbose
+\&                        (default)
+\&      \-\-nocount         Disable the X/Y test count.
+\& \-D   \-\-dry             Dry run. Show test that would have run.
+\& \-f,  \-\-failures        Show failed tests.
+\& \-o,  \-\-comments        Show comments.
+\&      \-\-ignore\-exit     Ignore exit status from test scripts.
+\& \-m,  \-\-merge           Merge test scripts\*(Aq STDERR with their STDOUT.
+\& \-r,  \-\-recurse         Recursively descend into directories.
+\&      \-\-reverse         Run the tests in reverse order.
+\& \-q,  \-\-quiet           Suppress some test output while running tests.
+\& \-Q,  \-\-QUIET           Only print summary results.
+\& \-p,  \-\-parse           Show full list of TAP parse errors, if any.
+\&      \-\-directives      Only show results with TODO or SKIP directives.
+\&      \-\-timer           Print elapsed time after each test.
+\&      \-\-trap            Trap Ctrl\-C and print summary on interrupt.
+\&      \-\-normalize       Normalize TAP output in verbose output
+\& \-T                     Enable tainting checks.
+\& \-t                     Enable tainting warnings.
+\& \-W                     Enable fatal warnings.
+\& \-w                     Enable warnings.
+\& \-h,  \-\-help            Display this help
+\& \-?,                    Display this help
+\& \-V,  \-\-version         Display the version
+\& \-H,  \-\-man             Longer manpage for prove
+\&      \-\-norc            Don\*(Aqt process default .proverc
+.Ve
+.PP
+Options that take arguments:
+.PP
+.Vb 10
+\& \-I                     Library paths to include.
+\& \-P                     Load plugin (searches App::Prove::Plugin::*.)
+\& \-M                     Load a module.
+\& \-e,  \-\-exec            Interpreter to run the tests (\*(Aq\*(Aq for compiled
+\&                        tests.)
+\&      \-\-ext             Set the extension for tests (default \*(Aq.t\*(Aq)
+\&      \-\-harness         Define test harness to use.  See TAP::Harness.
+\&      \-\-formatter       Result formatter to use. See FORMATTERS.
+\&      \-\-source          Load and/or configure a SourceHandler. See
+\&                        SOURCE HANDLERS.
+\& \-a,  \-\-archive out.tgz Store the resulting TAP in an archive file.
+\& \-j,  \-\-jobs N          Run N test jobs in parallel (try 9.)
+\&      \-\-state=opts      Control prove\*(Aqs persistent state.
+\&      \-\-statefile=file  Use \`file\` instead of \`.prove\` for state
+\&      \-\-rc=rcfile       Process options from rcfile
+\&      \-\-rules           Rules for parallel vs sequential processing.
+.Ve
+.SH NOTES
+.IX Header "NOTES"
+.SS .proverc
+.IX Subsection ".proverc"
+If \fI~/.proverc\fR or \fI./.proverc\fR exist they will be read and any
+options they contain processed before the command line options. Options
+in \fI.proverc\fR are specified in the same way as command line options:
+.PP
+.Vb 3
+\&    # .proverc
+\&    \-\-state=hot,fast,save
+\&    \-j9
+.Ve
+.PP
+Additional option files may be specified with the \f(CW\*(C`\-\-rc\*(C'\fR option.
+Default option file processing is disabled by the \f(CW\*(C`\-\-norc\*(C'\fR option.
+.PP
+Under Windows and VMS the option file is named \fI_proverc\fR rather than
+\&\fI.proverc\fR and is sought only in the current directory.
+.ie n .SS "Reading from ""STDIN"""
+.el .SS "Reading from \f(CWSTDIN\fP"
+.IX Subsection "Reading from STDIN"
+If you have a list of tests (or URLs, or anything else you want to test) in a
+file, you can add them to your tests by using a '\-':
+.PP
+.Vb 1
+\& prove \- < my_list_of_things_to_test.txt
+.Ve
+.PP
+See the \f(CW\*(C`README\*(C'\fR in the \f(CW\*(C`examples\*(C'\fR directory of this distribution.
+.SS "Default Test Directory"
+.IX Subsection "Default Test Directory"
+If no files or directories are supplied, \f(CW\*(C`prove\*(C'\fR looks for all files
+matching the pattern \f(CW\*(C`t/*.t\*(C'\fR.
+.SS "Colored Test Output"
+.IX Subsection "Colored Test Output"
+Colored test output using TAP::Formatter::Color is the default, but
+if output is not to a terminal, color is disabled. You can override this by
+adding the \f(CW\*(C`\-\-color\*(C'\fR switch.
+.PP
+Color support requires Term::ANSIColor and, on windows platforms, also
+Win32::Console::ANSI. If the necessary module(s) are not installed
+colored output will not be available.
+.SS "Exit Code"
+.IX Subsection "Exit Code"
+If the tests fail \f(CW\*(C`prove\*(C'\fR will exit with non-zero status.
+.SS "Arguments to Tests"
+.IX Subsection "Arguments to Tests"
+It is possible to supply arguments to tests. To do so separate them from
+prove's own arguments with the arisdottle, '::'. For example
+.PP
+.Vb 1
+\& prove \-v t/mytest.t :: \-\-url http://example.com
+.Ve
+.PP
+would run \fIt/mytest.t\fR with the options '\-\-url http://example.com'.
+When running multiple tests they will each receive the same arguments.
+.ie n .SS """\-\-exec"""
+.el .SS \f(CW\-\-exec\fP
+.IX Subsection "--exec"
+Normally you can just pass a list of Perl tests and the harness will know how
+to execute them.  However, if your tests are not written in Perl or if you
+want all tests invoked exactly the same way, use the \f(CW\*(C`\-e\*(C'\fR, or \f(CW\*(C`\-\-exec\*(C'\fR
+switch:
+.PP
+.Vb 3
+\& prove \-\-exec \*(Aq/usr/bin/ruby \-w\*(Aq t/
+\& prove \-\-exec \*(Aq/usr/bin/perl \-Tw \-mstrict \-Ilib\*(Aq t/
+\& prove \-\-exec \*(Aq/path/to/my/customer/exec\*(Aq
+.Ve
+.ie n .SS """\-\-merge"""
+.el .SS \f(CW\-\-merge\fP
+.IX Subsection "--merge"
+If you need to make sure your diagnostics are displayed in the correct
+order relative to test results you can use the \f(CW\*(C`\-\-merge\*(C'\fR option to
+merge the test scripts' STDERR into their STDOUT.
+.PP
+This guarantees that STDOUT (where the test results appear) and STDERR
+(where the diagnostics appear) will stay in sync. The harness will
+display any diagnostics your tests emit on STDERR.
+.PP
+Caveat: this is a bit of a kludge. In particular note that if anything
+that appears on STDERR looks like a test result the test harness will
+get confused. Use this option only if you understand the consequences
+and can live with the risk.
+.ie n .SS """\-\-trap"""
+.el .SS \f(CW\-\-trap\fP
+.IX Subsection "--trap"
+The \f(CW\*(C`\-\-trap\*(C'\fR option will attempt to trap SIGINT (Ctrl-C) during a test
+run and display the test summary even if the run is interrupted
+.ie n .SS """\-\-state"""
+.el .SS \f(CW\-\-state\fP
+.IX Subsection "--state"
+You can ask \f(CW\*(C`prove\*(C'\fR to remember the state of previous test runs and
+select and/or order the tests to be run based on that saved state.
+.PP
+The \f(CW\*(C`\-\-state\*(C'\fR switch requires an argument which must be a comma
+separated list of one or more of the following options.
+.ie n .IP """last""" 4
+.el .IP \f(CWlast\fR 4
+.IX Item "last"
+Run the same tests as the last time the state was saved. This makes it
+possible, for example, to recreate the ordering of a shuffled test.
+.Sp
+.Vb 2
+\&    # Run all tests in random order
+\&    $ prove \-b \-\-state=save \-\-shuffle
+\&
+\&    # Run them again in the same order
+\&    $ prove \-b \-\-state=last
+.Ve
+.ie n .IP """failed""" 4
+.el .IP \f(CWfailed\fR 4
+.IX Item "failed"
+Run only the tests that failed on the last run.
+.Sp
+.Vb 2
+\&    # Run all tests
+\&    $ prove \-b \-\-state=save
+\&
+\&    # Run failures
+\&    $ prove \-b \-\-state=failed
+.Ve
+.Sp
+If you also specify the \f(CW\*(C`save\*(C'\fR option newly passing tests will be
+excluded from subsequent runs.
+.Sp
+.Vb 2
+\&    # Repeat until no more failures
+\&    $ prove \-b \-\-state=failed,save
+.Ve
+.ie n .IP """passed""" 4
+.el .IP \f(CWpassed\fR 4
+.IX Item "passed"
+Run only the passed tests from last time. Useful to make sure that no
+new problems have been introduced.
+.ie n .IP """all""" 4
+.el .IP \f(CWall\fR 4
+.IX Item "all"
+Run all tests in normal order. Multiple options may be specified, so to
+run all tests with the failures from last time first:
+.Sp
+.Vb 1
+\&    $ prove \-b \-\-state=failed,all,save
+.Ve
+.ie n .IP """hot""" 4
+.el .IP \f(CWhot\fR 4
+.IX Item "hot"
+Run the tests that most recently failed first. The last failure time of
+each test is stored. The \f(CW\*(C`hot\*(C'\fR option causes tests to be run in most\-recent\-
+failure order.
+.Sp
+.Vb 1
+\&    $ prove \-b \-\-state=hot,save
+.Ve
+.Sp
+Tests that have never failed will not be selected. To run all tests with
+the most recently failed first use
+.Sp
+.Vb 1
+\&    $ prove \-b \-\-state=hot,all,save
+.Ve
+.Sp
+This combination of options may also be specified thus
+.Sp
+.Vb 1
+\&    $ prove \-b \-\-state=adrian
+.Ve
+.ie n .IP """todo""" 4
+.el .IP \f(CWtodo\fR 4
+.IX Item "todo"
+Run any tests with todos.
+.ie n .IP """slow""" 4
+.el .IP \f(CWslow\fR 4
+.IX Item "slow"
+Run the tests in slowest to fastest order. This is useful in conjunction
+with the \f(CW\*(C`\-j\*(C'\fR parallel testing switch to ensure that your slowest tests
+start running first.
+.Sp
+.Vb 1
+\&    $ prove \-b \-\-state=slow \-j9
+.Ve
+.ie n .IP """fast""" 4
+.el .IP \f(CWfast\fR 4
+.IX Item "fast"
+Run test tests in fastest to slowest order.
+.ie n .IP """new""" 4
+.el .IP \f(CWnew\fR 4
+.IX Item "new"
+Run the tests in newest to oldest order based on the modification times
+of the test scripts.
+.ie n .IP """old""" 4
+.el .IP \f(CWold\fR 4
+.IX Item "old"
+Run the tests in oldest to newest order.
+.ie n .IP """fresh""" 4
+.el .IP \f(CWfresh\fR 4
+.IX Item "fresh"
+Run those test scripts that have been modified since the last test run.
+.ie n .IP """save""" 4
+.el .IP \f(CWsave\fR 4
+.IX Item "save"
+Save the state on exit. The state is stored in a file called \fI.prove\fR
+(\fI_prove\fR on Windows and VMS) in the current directory.
+.PP
+The \f(CW\*(C`\-\-state\*(C'\fR switch may be used more than once.
+.PP
+.Vb 1
+\&    $ prove \-b \-\-state=hot \-\-state=all,save
+.Ve
+.SS \-\-rules
+.IX Subsection "--rules"
+The \f(CW\*(C`\-\-rules\*(C'\fR option is used to control which tests are run sequentially and
+which are run in parallel, if the \f(CW\*(C`\-\-jobs\*(C'\fR option is specified. The option may
+be specified multiple times, and the order matters.
+.PP
+The most practical use is likely to specify that some tests are not
+"parallel-ready".  Since mentioning a file with \-\-rules doesn't cause it to
+be selected to run as a test, you can "set and forget" some rules preferences in
+your .proverc file. Then you'll be able to take maximum advantage of the
+performance benefits of parallel testing, while some exceptions are still run
+in parallel.
+.PP
+\fI\-\-rules examples\fR
+.IX Subsection "--rules examples"
+.PP
+.Vb 2
+\&    # All tests are allowed to run in parallel, except those starting with "p"
+\&    \-\-rules=\*(Aqseq=t/p*.t\*(Aq \-\-rules=\*(Aqpar=**\*(Aq
+\&
+\&    # All tests must run in sequence except those starting with "p", which should be run parallel
+\&    \-\-rules=\*(Aqpar=t/p*.t\*(Aq
+.Ve
+.PP
+\fI\-\-rules resolution\fR
+.IX Subsection "--rules resolution"
+.IP \(bu 4
+By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.
+.IP \(bu 4
+"First match wins". The first rule that matches a test will be the one that applies.
+.IP \(bu 4
+Any test which does not match a rule will be run in sequence at the end of the run.
+.IP \(bu 4
+The existence of a rule does not imply selecting a test. You must still specify the tests to run.
+.IP \(bu 4
+Specifying a rule to allow tests to run in parallel does not make them run in parallel. You still need specify the number of parallel \f(CW\*(C`jobs\*(C'\fR in your Harness object.
+.PP
+\fI\-\-rules Glob-style pattern matching\fR
+.IX Subsection "--rules Glob-style pattern matching"
+.PP
+We implement our own glob-style pattern matching for \-\-rules. Here are the
+supported patterns:
+.PP
+.Vb 5
+\&    ** is any number of characters, including /, within a pathname
+\&    * is zero or more characters within a filename/directory name
+\&    ? is exactly one character within a filename/directory name
+\&    {foo,bar,baz} is any of foo, bar or baz.
+\&    \e is an escape character
+.Ve
+.PP
+\fIMore advanced specifications for parallel vs sequence run rules\fR
+.IX Subsection "More advanced specifications for parallel vs sequence run rules"
+.PP
+If you need more advanced management of what runs in parallel vs in sequence, see
+the associated 'rules' documentation in TAP::Harness and TAP::Parser::Scheduler.
+If what's possible directly through \f(CW\*(C`prove\*(C'\fR is not sufficient, you can write your own
+harness to access these features directly.
+.ie n .SS @INC
+.el .SS \f(CW@INC\fP
+.IX Subsection "@INC"
+prove introduces a separation between "options passed to the perl which
+runs prove" and "options passed to the perl which runs tests"; this
+distinction is by design. Thus the perl which is running a test starts
+with the default \f(CW@INC\fR. Additional library directories can be added
+via the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, via \-Ifoo in \f(CW\*(C`PERL5OPT\*(C'\fR or
+via the \f(CW\*(C`\-Ilib\*(C'\fR option to \fIprove\fR.
+.SS "Taint Mode"
+.IX Subsection "Taint Mode"
+Normally when a Perl program is run in taint mode the contents of the
+\&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR.
+.PP
+Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build
+directories to \f(CW@INC\fR prove passes the names of any directories found
+in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this is that
+\&\f(CW\*(C`PERL5LIB\*(C'\fR is honoured even when prove is run in taint mode.
+.SH FORMATTERS
+.IX Header "FORMATTERS"
+You can load a custom TAP::Parser::Formatter:
+.PP
+.Vb 1
+\&  prove \-\-formatter MyFormatter
+.Ve
+.SH "SOURCE HANDLERS"
+.IX Header "SOURCE HANDLERS"
+You can load custom TAP::Parser::SourceHandlers, to change the way the
+parser interprets particular \fIsources\fR of TAP.
+.PP
+.Vb 1
+\&  prove \-\-source MyHandler \-\-source YetAnother t
+.Ve
+.PP
+If you want to provide config to the source you can use:
+.PP
+.Vb 4
+\&  prove \-\-source MyCustom \e
+\&        \-\-source Perl \-\-perl\-option \*(Aqfoo=bar baz\*(Aq \-\-perl\-option avg=0.278 \e
+\&        \-\-source File \-\-file\-option extensions=.txt \-\-file\-option extensions=.tmp t
+\&        \-\-source pgTAP \-\-pgtap\-option pset=format=html \-\-pgtap\-option pset=border=2
+.Ve
+.PP
+Each \f(CW\*(C`\-\-$source\-option\*(C'\fR option must specify a key/value pair separated by an
+\&\f(CW\*(C`=\*(C'\fR. If an option can take multiple values, just specify it multiple times,
+as with the \f(CW\*(C`extensions=\*(C'\fR examples above. If the option should be a hash
+reference, specify the value as a second pair separated by a \f(CW\*(C`=\*(C'\fR, as in the
+\&\f(CW\*(C`pset=\*(C'\fR examples above (escape \f(CW\*(C`=\*(C'\fR with a backslash).
+.PP
+All \f(CW\*(C`\-\-sources\*(C'\fR are combined into a hash, and passed to "new" in TAP::Harness's
+\&\f(CW\*(C`sources\*(C'\fR parameter.
+.PP
+See TAP::Parser::IteratorFactory for more details on how configuration is
+passed to \fISourceHandlers\fR.
+.SH PLUGINS
+.IX Header "PLUGINS"
+Plugins can be loaded using the \f(CW\*(C`\-P\fR\f(CIplugin\fR\f(CW\*(C'\fR syntax, eg:
+.PP
+.Vb 1
+\&  prove \-PMyPlugin
+.Ve
+.PP
+This will search for a module named \f(CW\*(C`App::Prove::Plugin::MyPlugin\*(C'\fR, or failing
+that, \f(CW\*(C`MyPlugin\*(C'\fR.  If the plugin can't be found, \f(CW\*(C`prove\*(C'\fR will complain & exit.
+.PP
+You can pass arguments to your plugin by appending \f(CW\*(C`=arg1,arg2,etc\*(C'\fR to the
+plugin name:
+.PP
+.Vb 1
+\&  prove \-PMyPlugin=fou,du,fafa
+.Ve
+.PP
+Please check individual plugin documentation for more details.
+.SS "Available Plugins"
+.IX Subsection "Available Plugins"
+For an up-to-date list of plugins available, please check CPAN:
+.PP
+<http://search.cpan.org/search?query=App%3A%3AProve+Plugin>
+.SS "Writing Plugins"
+.IX Subsection "Writing Plugins"
+Please see "PLUGINS" in App::Prove.
diff --git a/upstream/mageia-cauldron/man1/ps2ascii.1 b/upstream/mageia-cauldron/man1/ps2ascii.1
new file mode 100644
index 00000000..e36de044
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ps2ascii.1
@@ -0,0 +1,30 @@
+.TH PS2ASCII 1 "01 November 2023" 10.02.1 "Ghostscript Tools" \" -*- nroff -*-
+.SH NAME
+ps2ascii \- Ghostscript translator from PostScript or PDF to ASCII
+.SH SYNOPSIS
+\fBps2ascii\fR [ \fIinput.ps\fR [ \fIoutput.txt\fR ] ]
+.br
+\fBps2ascii\fR \fIinput.pdf\fR [ \fIoutput.txt\fR ]
+.SH DESCRIPTION
+\fBps2ascii\fR uses \fBgs\fR(1) to extract ASCII text from
+\fBPostScript\fR(tm) or Adobe \fBPortable Document Format\fR (PDF)
+files. If no files are specified on the command line, \fBgs\fR reads from
+standard input; but PDF input must come from an explicitly-named file, not
+standard input.  If no output file is specified, the ASCII text is written
+to standard output.
+.PP
+\fBps2ascii\fR doesn't look at font encoding, and isn't very good at
+dealing with kerning, so for PostScript (but not currently PDF), you might
+consider \fBpstotext\fR (see below).
+.SH FILES
+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your
+system, from which you can get more details.
+.SH SEE ALSO
+pstotext(1), http://www.research.digital.com/SRC/virtualpaper/pstotext.html
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+David M. Jones <dmjones@theory.lcs.mit.edu> made substantial improvements
+to \fBps2ascii\fR.
diff --git a/upstream/mageia-cauldron/man1/ps2epsi.1 b/upstream/mageia-cauldron/man1/ps2epsi.1
new file mode 100644
index 00000000..4911c9de
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ps2epsi.1
@@ -0,0 +1,65 @@
+.TH PS2EPSI 1 "01 November 2023" 10.02.1 "Ghostscript Tools" \" -*- nroff -*-
+.SH NAME
+ps2epsi \- generate conforming Encapsulated PostScript
+.SH SYNOPSIS
+\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] \fB(Unix)\fR
+.br
+\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epi\fR ] \fB(DOS)\fR
+.SH DESCRIPTION
+\fBps2epsi\fR uses \fBgs\fR(1) to process a \fBPostScript\fR(tm) file and
+generate as output a new file which conforms to Adobe's \fBEncapsulated
+PostScript Interchange\fR (EPSI) format.  EPSI is a special form of
+encapsulated PostScript (EPS) which adds to the beginning of the file in
+the form of PostScript comments a bitmapped version of the final displayed
+page.  Programs which understand EPSI (usually word processors or DTP
+programs) can use this bitmap to give a preview version on screen of the
+PostScript.  The displayed quality is often not very good (e.g., low
+resolution, no colours), but the final printed version uses the real
+PostScript, and thus has the normal PostScript quality.
+.SH USAGE
+On Unix systems invoke \fBps2epsi\fR like this:
+.PP
+.br
+	\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ]
+.PP
+where "infile.ps" is the input file and "outfile.epsi" is the resulting
+EPSI file.  If the output filename is omitted, it is generated from the
+input filename.  When a standard extension (".ps", ".cps", ".eps" or
+".epsf") is used, it is replaced with the output extension ".epsi".  On
+DOS systems the command is:
+.PP
+.br
+	\fBps2epsi\fR \fIinfile.ps outfile.epi\fR
+.PP
+where "infile.ps" is the original PostScript file, and "outfile.epi"
+is the name of the output file.
+.SH LIMITATIONS
+Not every PostScript file can be encapsulated successfully, because there
+are restrictions on what PostScript constructs a correct encapsulated file
+may contain.  \fBps2epsi\fR does a little extra work to try to help
+encapsulation, and it automatically calculates the bounding box required
+for all encapsulated PostScript files, so most of the time it does a pretty
+good job. There are certain to be cases, however, where the encapsulation
+does not work because of the content of the original PostScript file.
+.SH COMPATIBILITY
+The \fBFramemaker\fR DTP system is one application which understands EPSI
+files, and \fBps2epsi\fR has been tested on a number of PostScript diagrams
+from a variety of sources, using Framemaker 3.0 on a Sun workstation.
+Framemaker on other platforms should be able to use these files, although I
+have not been able to test this.
+.SH FILES
+.TS
+tab(>);
+l l.
+ps2epsi>Unix shell script
+ps2epsi.bat>DOS batch file
+ps2epsi.ps>the Ghostscript program which does the work
+.TE
+.fi
+.SH SEE ALSO
+gs (1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+However, the content may be obsolete, or inconsistent with ps2epsi.txt.
+.SH AUTHOR
+George Cameron
diff --git a/upstream/mageia-cauldron/man1/ps2pdf.1 b/upstream/mageia-cauldron/man1/ps2pdf.1
new file mode 100644
index 00000000..c8288b6e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ps2pdf.1
@@ -0,0 +1,96 @@
+.TH PS2PDF 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+ps2pdf \- Convert PostScript to PDF using ghostscript
+.br
+ps2pdf12 \- Convert PostScript to PDF\ 1.2 (Acrobat\ 3-and-later compatible) using ghostscript
+.br
+ps2pdf13 \- Convert PostScript to PDF\ 1.3 (Acrobat\ 4-and-later compatible) using ghostscript
+.br
+ps2pdf14 \- Convert PostScript to PDF\ 1.4 (Acrobat\ 5-and-later compatible) using ghostscript
+.SH SYNOPSIS
+\fBps2pdf\fR  [options...] {input.[e]ps|-} [output.pdf|-]
+.br
+\fBps2pdf12\fR  [options...] {input.[e]ps|-} [output.pdf|-]
+.br
+\fBps2pdf13\fR  [options...] {input.[e]ps|-} [output.pdf|-]
+.br
+\fBps2pdf14\fR  [options...] {input.[e]ps|-} [output.pdf|-]
+.SH DESCRIPTION
+The
+.B ps2pdf
+scripts are work-alikes for nearly all the functionality (but not the
+user interface) of Adobe's Acrobat(TM) Distiller(TM) product: they
+convert PostScript files to Portable Document Format (PDF) files. 
+.PP
+If the output filename is not specified, the output is placed in a file
+of the same name with a '.pdf' extension in the current working
+directory. Either the input filename or the output filename can be '-'
+to request reading from stdin or writing to stdout, respectively,
+when used as a filter.
+.PP
+The three scripts differ as follows:
+.IP -
+.B ps2pdf12
+will always produce PDF 1.2 output (Acrobat 3-and-later compatible).
+.IP -
+.B ps2pdf13
+will always produce PDF 1.3 output (Acrobat 4-and-later compatible).
+.IP -
+.B ps2pdf14
+will always produce PDF 1.4 output (Acrobat 5-and-later compatible).
+.IP -
+.B ps2pdf
+per se currently produces PDF 1.4 output.
+However, this may change in the future. If you care about
+the compatibility level of the output, use
+.BR ps2pdf12 ,
+.B ps2pdf13
+or
+.BR ps2pdf14 ,
+or use the
+.B \-dCompatibilityLevel=1.x
+switch in the command line.
+.PP
+There are some limitations in
+.BR ps2pdf 's
+conversion. See the HTML documentation for more information. A large 
+number of Adobe Distiller(TM) parameters which can be used to control
+the conversion are also documented there, including instructions for 
+generating PDF/X and PDF/A documents.
+.SH OPTIONS
+The
+.B ps2pdf
+scripts use the same options as gs(1).
+.SH EXAMPLES
+.LP
+Converting a figure.ps to figure.pdf:
+.IP
+.B ps2pdf
+.I figure.ps
+.LP
+A conversion with more specifics:
+.IP
+.B ps2pdf
+-dPDFSETTINGS=/prepress 
+.I figure.ps proof.pdf
+.LP
+Converting as part of a pipe:
+.IP
+.B make_report.pl 
+-t ps |
+.B ps2pdf
+-dCompatibilityLevel=1.3 - - |
+.B lpr
+.SH SEE ALSO
+gs(1), ps2pdfwr(1),
+.br
+VectorDevices.htm in the Ghostscript documentation
+.SH BUGS
+See http://bugs.ghostscript.com/ and the Usenet news group
+comp.lang.postscript.
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/ps2pdfwr.1 b/upstream/mageia-cauldron/man1/ps2pdfwr.1
new file mode 100644
index 00000000..cfd2a8e8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ps2pdfwr.1
@@ -0,0 +1,31 @@
+.TH PS2PDFWR 1 "01 November 2023" 10.02.1 Ghostscript \" -*- nroff -*-
+.SH NAME
+ps2pdfwr \- Convert PostScript to PDF without specifying CompatibilityLevel, using ghostscript
+.SH SYNOPSIS
+\fBps2pdfwr\fR  [options...] {input.[e]ps|-} [output.pdf|-]
+.SH DESCRIPTION
+This wrapper script invokes
+.BR gs (1)
+with following arguments
+
+.ce
+.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite
+
+as well as the appropriate
+.B -dOutputFile
+argument, all preceded and followed by any command-line arguments. Finally, the security option
+.B -dSAFER
+is prepended before all the other options (This is now redundant as "SAFER" is now the default,
+but the option does no harm).
+
+The version-specific
+.B ps2pdf
+scripts all invoke this one with the addition of the respective compatibility level option.
+.SH SEE ALSO
+gs(1), ps2pdf(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the
+primary maintainers of Ghostscript.
+This manpage by George Ferguson.
diff --git a/upstream/mageia-cauldron/man1/ps2ps.1 b/upstream/mageia-cauldron/man1/ps2ps.1
new file mode 100644
index 00000000..884aa021
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ps2ps.1
@@ -0,0 +1,28 @@
+.TH PS2PS 1 "01 November 2023" 10.02.1 "Ghostscript Tools" \" -*- nroff -*-
+.SH NAME
+ps2ps, eps2eps \- Ghostscript PostScript "distiller"
+.SH SYNOPSIS
+\fBps2ps\fR [ \fIoptions\fR ] \fIinput output.ps\fR
+.br
+\fBeps2eps\fR [ \fIoptions\fR ] \fIinput output.eps\fR
+.SH DESCRIPTION
+\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) or \fBPDF\fR(tm) file
+"input" to simpler, normalized and (usually) faster PostScript in
+"output.ps".  The output is level 2 DSC 3.0 conforming PostScript.
+.PP
+\fBeps2eps\fR performs the equivalent optimization, creating Encapsulated
+PostScript (EPS) files. NB, despite the name, the input need not be an
+EPS file, PostScript or indeed PDF files are equally acceptable.
+.PP
+Both accept any general Ghostscript command line options, and
+options specific to the ps2write and eps2write devices.
+.SH FILES
+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your
+system, from which you can get more details.
+.SH SEE ALSO
+ps2pdf(1), ps2ascii(1), ps2epsi(1)
+.SH VERSION
+This document was last revised for Ghostscript version 10.02.1.
+.SH AUTHOR
+Artifex Software, Inc. are the 
+primary maintainers of Ghostscript.
diff --git a/upstream/mageia-cauldron/man1/psbook.1 b/upstream/mageia-cauldron/man1/psbook.1
new file mode 100644
index 00000000..98dab2ed
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psbook.1
@@ -0,0 +1,57 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSBOOK "1" "October 2021" "psbook 2.07" "User Commands"
+.SH NAME
+psbook - rearrange pages in a PostScript document into signatures
+.SH SYNOPSIS
+.B psbook
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Rearrange pages in a PostScript document into signatures.
+.TP
+\fB\-s\fR, \fB\-\-signature\fR=\fI\,N\/\fR
+number of pages per signature;
+0 = all pages in one signature [default];
+1 = one page per signature;
+otherwise, a multiple of 4
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+don't show page numbers being output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+.B Psbook
+uses
+.B Pstops
+to rearrange pages from a PostScript document into \[oq]signatures\[cq] for
+printing books or booklets, creating a new PostScript file.
+The signature size is the number of sides which will be folded and bound
+together; the number given should be a multiple of four.
+Extra blank sides will be added if the file does not contain a multiple of
+four pages.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2016\-2021.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/psfaddtable.1 b/upstream/mageia-cauldron/man1/psfaddtable.1
new file mode 100644
index 00000000..6ad04d20
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psfaddtable.1
@@ -0,0 +1,47 @@
+.\" @(#)psfaddtable.1
+.TH PSFADDTABLE 1 "25 Oct 1994" "kbd"
+.SH NAME
+psfaddtable \- add a Unicode character table to a console font
+.SH SYNOPSIS
+.B psfaddtable
+.I fontfile tablefile outfile
+.SH DESCRIPTION
+.IX "psfaddtable command" "" "\fLpsfaddtable\fR command"  
+.LP
+.B psfaddtable
+takes a console font in .psf format given by
+.I fontfile
+and merges it with the Unicode character table given by
+.I tablefile
+to produce a font file with an embedded character table, which is
+written to
+.IR outfile .
+An input file name of "\-" denotes standard input,
+and an output file name of "\-" denotes standard output.
+If the
+.I fontfile
+already contains an embedded character table, it is ignored.
+.SH TABLE FILE FORMAT
+Each line in the
+.I tablefile
+should be either blank, contain a comment (preceded by
+.IR # ),
+or contain a sequence of numbers in either decimal (default), octal
+(preceded by
+.IR 0 ),
+or hexadecimal (preceded by
+.IR 0x )
+format, separated by spaces or tabs.
+The first number on each line indicates the glyph slot in the
+font that is being referred to, this is between 0 and 0xff for a
+256-character font and 0 and 0x1ff for a 512-character font.  Any
+subsequent numbers on the same line are Unicodes matched by this
+specific glyph slot.  Instead of a single Unicode one may have
+a sequence of Unicodes separates by commas, to denote that the
+glyph depicts the corresponding composed symbol.
+It is permissible to have multiple lines for the same glyph.
+.SH "SEE ALSO"
+.BR setfont (8),
+.BR psfgettable (1),
+.BR psfstriptable (1),
+.BR psfxtable (1)
diff --git a/upstream/mageia-cauldron/man1/psfgettable.1 b/upstream/mageia-cauldron/man1/psfgettable.1
new file mode 100644
index 00000000..34c8e24d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psfgettable.1
@@ -0,0 +1,22 @@
+.\" @(#)psfgettable.1
+.TH PSFGETTABLE 1 "25 Oct 1994" "kbd"
+.SH NAME
+psfgettable \- extract the embedded Unicode character table from a console font
+.SH SYNOPSIS
+.B psfgettable
+.I fontfile
+.RI [ outfile ]
+.SH DESCRIPTION
+.IX "psfgettable command" "" "\fLpsfgettable\fR command"  
+.LP
+.B psfgettable
+extracts the embedded Unicode character table from a .psf format
+console font into a human readable ASCII file of the format used by
+.BR psfaddtable (1).
+If the font file name is a single dash (\-), the font is read from
+standard input.
+.SH "SEE ALSO"
+.BR setfont (8),
+.BR psfaddtable (1),
+.BR psfstriptable (1),
+.BR psfxtable (1)
diff --git a/upstream/mageia-cauldron/man1/psfstriptable.1 b/upstream/mageia-cauldron/man1/psfstriptable.1
new file mode 100644
index 00000000..9e7f95f1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psfstriptable.1
@@ -0,0 +1,23 @@
+.\" @(#)psfstriptable.1
+.TH PSFSTRIPTABLE 1 "25 Oct 1994" "kbd"
+.SH NAME
+psfstriptable \- remove the embedded Unicode character table from a console font
+.SH SYNOPSIS
+.B psfstriptable
+.I fontfile outfile
+.SH DESCRIPTION
+.IX "psfstriptable command" "" "\fLpsfstriptable\fR command"  
+.LP
+.B psfstriptable
+reads a .psf format console font from 
+.IR fontfile ,
+removes the embedded Unicode font table if there is one,
+and writes the result to
+.IR outfile .
+An input file name of "\-" denotes standard input,
+and an output file name of "\-" denotes standard output.
+.SH "SEE ALSO"
+.BR setfont (8),
+.BR psfaddtable (1),
+.BR psfgettable (1),
+.BR psfxtable (1)
diff --git a/upstream/mageia-cauldron/man1/psfxtable.1 b/upstream/mageia-cauldron/man1/psfxtable.1
new file mode 100644
index 00000000..45bab8a3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psfxtable.1
@@ -0,0 +1,55 @@
+.\" @(#)psfxtable.1
+.TH PSFXTABLE 1 "9 Dec 1999" "kbd"
+.SH NAME
+psfxtable \- handle Unicode character tables for console fonts
+.SH SYNOPSIS
+.B psfxtable
+.RB [ \-i
+.IR infont ]
+.RB [ \-o
+.IR outfont ]
+.RB [ \-it
+.IR intable ]
+.RB [ \-ot
+.IR outtable ]
+.RB [ \-nt ]
+.SH DESCRIPTION
+.IX "psfxtable command" "" "\fLpsfxtable\fR command"
+.LP
+.B psfxtable
+handles the embedded Unicode character table for .psf format
+console fonts. It reads a font and possibly a table
+and writes a font and/or a table.
+.BR psfaddtable (1),
+.BR psfgettable (1)
+and
+.BR psfstriptable (1)
+are links to it.
+
+Each of the filenames
+.IR infont ,
+.IR outfont ,
+.IR intable ,
+and
+.I outtable
+may be replaced by a single dash (\-), in which case
+standard input or standard output is used.
+If no \fI\-i\fR option is given, the font is read from standard input.
+If no \fI\-it\fR or \fI\-o\fR or \fI\-ot\fR option is given,
+no input table is read or no output font or output table is written.
+
+By default the output font (if any) will have a Unicode table
+when either the input font has one, or an explicit table
+(which overrides an input font table) has been provided.
+The option \fI\-nt\fR causes output of a font without table.
+When
+.I outfont
+is requested it will get a psf1 header when infont has
+a psf1 header and
+.I intable
+does not have sequences and a psf2 header otherwise.
+.SH "SEE ALSO"
+.BR setfont (8),
+.BR psfaddtable (1),
+.BR psfgettable (1),
+.BR psfstriptable (1)
diff --git a/upstream/mageia-cauldron/man1/psidtopgm.1 b/upstream/mageia-cauldron/man1/psidtopgm.1
new file mode 100644
index 00000000..2f571d5b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psidtopgm.1
@@ -0,0 +1,71 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Psidtopgm User Manual" 0 "02 August 89" "netpbm documentation"
+
+.SH NAME
+
+psidtopgm - convert PostScript "image" data to a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpsidtopgm\fP \fIwidth\fP \fIheight\fP \fIbits/sample\fP [\fIimagedata\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpsidtopgm\fP reads the "image" data from a PostScript
+file as input and produces a PGM image as output.
+.PP
+This program is obsoleted by \fBpstopnm\fP.
+
+What follows was written before \fBpstopnm \fP existed.
+.PP
+This is a very simple and limited program, and is here only because
+so many people have asked for it.  To use it you have to
+\fImanually\fP extract the readhexstring data portion from your
+PostScript file, and then give the width, height, and bits/sample on
+the command line.  Before you attempt this, you should \fIat
+least\fP read the description of the "image" operator in
+the PostScript Language Reference Manual.
+.PP
+It would probably not be too hard to write a script that uses this
+filter to read a specific variety of PostScript image, but the
+variation is too great to make a general-purpose reader.  Unless, of
+course, you want to write a full-fledged PostScript interpreter...
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBpsidtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtops" (1)\c
+\&, 
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/psidtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/psjoin.1 b/upstream/mageia-cauldron/man1/psjoin.1
new file mode 100644
index 00000000..c4cfc549
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psjoin.1
@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSJOIN "1" "October 2021" "psjoin 2.07" "User Commands"
+.SH NAME
+psjoin - concatenate PostScript documents
+.SH SYNOPSIS
+.B psjoin
+[\fI\,OPTION\/\fR...] \fI\,FILE\/\fR...
+.SH DESCRIPTION
+Concatenate PostScript documents.
+.TP
+\fB\-e\fR, \fB\-\-even\fR
+force each file to an even number of pages
+.TP
+\fB\-s\fR, \fB\-\-save\fR
+try to close unclosed save operators
+.TP
+\fB\-n\fR, \fB\-\-nostrip\fR
+do not strip prolog or trailer from input files
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Tom Sato 2002\-2003.
+.br
+Copyright \(co Reuben Thomas 2013\-2020.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/psnup.1 b/upstream/mageia-cauldron/man1/psnup.1
new file mode 100644
index 00000000..64c23f80
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psnup.1
@@ -0,0 +1,118 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSNUP "1" "October 2021" "psnup 2.07" "User Commands"
+.SH NAME
+psnup - put multiple pages of a PostScript document on to one page
+.SH SYNOPSIS
+.B psnup
+[\fI\,OPTION\/\fR...] \fI\,-NUP \/\fR[\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Put multiple pages of a PostScript document on to one page.
+.TP
+\fB\-NUMBER\fR
+number of pages to impose on each output page
+.TP
+\fB\-p\fR, \fB\-\-paper\fR=\fI\,PAPER\/\fR
+output paper name or dimensions
+.TP
+\fB\-P\fR, \fB\-\-inpaper\fR=\fI\,PAPER\/\fR
+input paper name or dimensions
+.TP
+\fB\-m\fR, \fB\-\-margin\fR=\fI\,DIMENSION\/\fR
+width of margin around each output page
+[default 0pt]; useful for thumbnail sheets,
+as the original page margins will be shrunk
+.TP
+\fB\-b\fR, \fB\-\-border\fR=\fI\,DIMENSION\/\fR
+width of border around each input page
+.TP
+\fB\-d\fR, \fB\-\-draw\fR[=\fI\,DIMENSION\/\fR]
+draw a line of given width around each page
+[relative to input page size; argument defaults to
+1pt; default is no line]
+.TP
+\fB\-l\fR, \fB\-\-rotatedleft\fR
+input pages are rotated left 90 degrees
+.TP
+\fB\-r\fR, \fB\-\-rotatedright\fR
+input pages are rotated right 90 degrees
+.TP
+\fB\-f\fR, \fB\-\-flip\fR
+swap output pages' width and height
+.TP
+\fB\-c\fR, \fB\-\-transpose\fR
+swap columns and rows (column\-major order)
+.TP
+\fB\-t\fR, \fB\-\-tolerance\fR=\fI\,NUMBER\/\fR
+maximum wasted area in square pt [default: 100,000]
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+don't show page numbers being output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+psnup aborts with an error if it cannot arrange the input pages so as to
+waste less than the given tolerance.
+.PP
+The output paper size defaults to the input paper size; if that is not given,
+the default given by the `paper' command is used.
+.PP
+The input paper size defaults to the output paper size.
+.PP
+In row\-major order (the default), adjacent pages are placed in rows across
+the paper; in column\-major order, they are placed in columns down the page.
+.PP
+.B Psnup
+uses
+.B Pstops
+to impose multiple logical pages on to each physical sheet of paper.
+.PP
+Paper sizes can be given either as a name (see
+.BR paper(1) )
+or as \fBwidth\fRx\fBheight\fR (see
+.BR psutils (1)
+for the available units).
+
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH EXAMPLES
+The potential use of this utility is varied but one particular 
+use is in conjunction with 
+.BR psbook (1).
+For example, using groff to create a PostScript document and lpr as 
+the 
+.SM UNIX 
+print spooler a typical command line might look like this: 
+.sp
+groff -Tps -ms \fIfile\fP | psbook | psnup -2 | lpr
+.sp
+where file is a 4 page document this command will result in a 
+two page document printing two pages of \fIfile\fP per page and
+rearranges the page order to match the input pages 4 and 1 
+on the first output page and
+pages 2 then 3 of the input document 
+on the second output page.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2016\-2021.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/psresize.1 b/upstream/mageia-cauldron/man1/psresize.1
new file mode 100644
index 00000000..030eae69
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psresize.1
@@ -0,0 +1,60 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSRESIZE "1" "October 2021" "psresize 2.07" "User Commands"
+.SH NAME
+psresize - change the page size of a PostScript document
+.SH SYNOPSIS
+.B psresize
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Change the page size of a PostScript document.
+.TP
+\fB\-p\fR, \fB\-\-paper\fR=\fI\,PAPER\/\fR
+output paper size
+.TP
+\fB\-P\fR, \fB\-\-inpaper\fR=\fI\,PAPER\/\fR
+input paper size
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+don't show page numbers being output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+.B Psresize
+uses
+.B Psnup
+to change the page size of a document, scaling and centering it appropriately.
+See
+.BR psutils (1)
+for the available units.
+
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH EXAMPLES
+The following command converts a document from A4 size to US Letter paper:
+.sp
+psresize -PA4 -pletter in.ps out.ps
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2016\-2021.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/psselect.1 b/upstream/mageia-cauldron/man1/psselect.1
new file mode 100644
index 00000000..c1ad868b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psselect.1
@@ -0,0 +1,60 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSSELECT "1" "October 2021" "psselect 2.07" "User Commands"
+.SH NAME
+psselect - select pages from a PostScript document
+.SH SYNOPSIS
+.B psselect
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Select pages from a PostScript document.
+.TP
+\fB\-R\fR, \fB\-p\fR, \fB\-\-pages\fR=\fI\,PAGES\/\fR
+select the given page ranges
+.TP
+\fB\-e\fR, \fB\-\-even\fR
+select even\-numbered pages
+.TP
+\fB\-o\fR, \fB\-\-odd\fR
+select odd\-numbered pages
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse the order of the pages
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+don't show page numbers being output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+PAGES is a comma\-separated list of pages and page ranges; see
+pstops(1) for more details.
+.B Psselect
+calls
+.B Pstops
+to do the rearrangement.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2016\-2021.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/pstopnm.1 b/upstream/mageia-cauldron/man1/pstopnm.1
new file mode 100644
index 00000000..17e695e7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pstopnm.1
@@ -0,0 +1,562 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pstopnm User Manual" 0 "06 December 2013" "netpbm documentation"
+
+.SH NAME
+pstopnm - convert a PostScript file to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpstopnm\fP
+
+[\fB-stdout\fP]
+
+[\fB-forceplain\fP]
+
+[\fB-help\fP]
+
+[\fB-dpi=\fP\fIdpi\fP]
+
+[\fB-xsize=\fP\fIpixels\fP]
+[\fB-ysize=\fP\fIpixels\fP]
+
+[\fB-xborder=\fP\fIfrac\fP]
+[\fB-yborder=\fP\fIfrac\fP]
+[\fB-landscape\fP]
+
+[\fB-portrait\fP]
+
+[\fB-nocrop\fP]
+
+[\fB-pbm\fP
+
+|\fB-pgm\fP
+
+|\fB-ppm\fP]
+
+[\fB-llx=\fP\fIs\fP]
+[\fB-lly=\fP\fIs\fP]
+[\fB-urx=\fP\fIs\fP]
+[\fB-ury=\fP\fIs\fP]
+
+[\fB-verbose\fP]
+
+[\fB-xmax=\fP\fIpixels\fP]
+[\fB-ymax=\fP\fIpixels\fP]
+
+[\fB-textalphabits=\fP{\fB1\fP,\fB2\fP,\fB4\fP}]
+
+
+\fIpsfile\fP[\fB.ps\fP]
+
+.SH OPTION USAGE
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpstopnm\fP reads a PostScript file as input and produces PBM,
+PGM, or PPM images as output.  This program simply uses GhostScript to
+render a PostScript file with its PNM device drivers.  If you don't
+have GhostScript installed or the version you have installed was not
+built with the relevant PNM device drivers, \fBpstopnm\fP will fail.
+You can see if you have the proper environment by issuing the command
+\f(CWgs --help \fP.  If it responds and lists under "Available
+Devices" \fBpbm\fP, \fBpbmraw\fP, \fBpgm\fP, \fBpgmraw\fP,
+\fBpnm\fP, \fBpnmraw\fP, \fBppm\fP, or \fBppmraw\fP, you're in
+business.
+.PP
+It's important to understand that \fBpstopnm\fP is a Netpbm image file
+format converter only in the broadest sense of the word, because Postscript is
+far from an image file format.  What \fBpstopnm\fP really is is a Postscript
+renderer - an image generator.  One place you'll notice the difference is
+where you expect \f(CWpstopnm | pnmtops\fP to be idempotent (which is not
+the case).  There are details on this kind of conversion below.
+.PP
+\fBpstopnm\fP uses the value of the \fBGHOSTSCRIPT\fP
+environment variable as the file name for the Ghostscript program.  If
+\fBGHOSTSCRIPT\fP is not set, \fBpstopnm\fP searches your
+\fBPATH\fP for a regular file named \fBgs\fP.  If it doesn't find
+one, it assumes Ghostscript is in the file \fB/usr/bin/gs\fP.
+.PP
+\fBpstopnm\fP does not use the Netpbm libraries to generate the
+output files, so may not be entirely consistent with most Netpbm
+programs.
+.PP
+\fIpsfile\fP[\fB.ps\fP] is the name of the input file.
+\fBpstopnm\fP will add the \fBps\fP to the end of the name you specify if no
+file exists by the exact name you specify, but one with \fB.ps\fPadded does.
+For Standard Input, use \fB-\fP or just don't give any argument.
+.PP
+If you use the \fB-stdout \fP option or your input is from Standard
+Input, \fBpstopnm\fP outputs images of all the pages as a multi-image file to
+Standard Output.  Otherwise, \fBpstopnm\fP creates one file for each page in
+the Postscript input.  The files are named as follows: If the input file is
+named \fBpsfile.ps\fP, the name of the files will be
+\fBpsfile001.ppm\fP, \fBpsfile002.ppm\fP, etc.  The filetype suffix
+is \fB.ppm\fP, \fB.pgm\fP, or \fB.pbm\fP, depending on which kind
+of output you choose with your invocation options.  If the input file
+name does not end in \fB.ps\fP, the whole file name is used in the
+output file name.  For example, if the input file is named
+\fBpsfile.old\fP, the output file name is \fBpsfile.old001.ppm\fP,
+etc.
+.PP
+Note that the output file selection is inconsistent with most
+Netpbm programs, because it does not default to Standard Output.  This
+is for historical reasons, based on the fact that the Netpbm formats
+did not always provide for a sequence of images in a single file.
+.PP
+When your input is from Standard Input, you may feed multiple Encapsulated
+Postscript documents, one after another, and \fBpstopnm\fP converts every
+document and places it in the Standard Output stream as an image.  But if your
+input is from a named file, \fBpstopnm\fP expects the file to be an
+Encapsulated Postscript file, which means it contains only one Enapsulated
+Postscript document.  If the file contains multiple concatenated
+documents, \fBpstopnm\fP ignores every document but the first.  This
+distinction does not exist for non-EPSF Postscript input
+- \fBpstopnm\fP generates an output image for each page of the input
+regardless of whether the input is from Standard Input or from a named file.
+.PP
+Note that you can generate both kinds of files - concatenated EPSF
+and multi-page non-EPSF - with \fBpnmtops\fP, selecting with the
+\fB-setpage\fP option.
+.PP
+Each output image contains a rectangular area of the page to which
+it pertains.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\& for
+details on what part of the input image goes into the output image and
+how big it is in the output and what borders and margins are in the
+output image.
+.PP
+It has been reported that on some Postscript Version 1 input,
+Ghostscript, and therefore \fBpstopnm\fP, produces no output.  To
+solve this problem, you can convert the file to Postscript Version 3
+with the program \fBps2ps\fP.  It is reported that the program
+\fBpstops\fP does not work.
+
+.UN dimensions
+.SS Dimensions
+.PP
+This section describes what part of the input image gets used in
+the output and the dimensions of the output, including borders and
+background.
+.PP
+Note that an output image is associated with a single input page.
+
+\fBpstopnm\fP starts by taking a rectangular area from the input page.
+That is called the subject image.
+.PP
+\fBpstopnm\fP may add borders to the subject image to form what is called
+the bordered subject image.
+.PP
+\fBpstopnm\fP places the bordered subject image in the center of
+the output image and clips the edges as necessary to fit the computed
+output image size.
+.PP
+The location of the subject image in the Postscript input page is
+defined by four numbers, the lower left corner and the upper right
+corner x and y coordinates.  These coordinates are usually specified
+by the BoundingBox DSC statement (a Postscript comment) in the
+PostScript file, but they can be overridden by the user by specifying
+one or more of the following options: \fB-llx\fP, \fB-lly\fP,
+\fB-urx\fP, and \fB-ury\fP.
+.PP
+The presence and thickness of a border to be added to the subject
+image to form the bordered subject image is controlled by the options
+\fB-xborder\fP and \fB-yborder\fP.  If \fBpstopnm\fP does not find
+a BoundingBox statement in the input, and you don't specify image area
+coordinates on the command line, \fBpstopnm\fP uses default values.
+If your input is from Standard Input, \fBpstopnm\fP does not use the
+BoundingBox values (because of the technical difficulty of extracting that
+information and still feeding the file to Ghostscript), so you either
+have to specify the image area coordinates or take the default.
+.PP
+The output image size is a confusing thing.  In a Postscript file,
+things have spatial dimensions.  For example, a particular line may be
+3 centimeters long.  A Postscript printer is supposed to print the
+line 3 centimeters long, using however many pixels that takes, without
+regard to how big the sheet of paper on which it is printing is.  In a
+PNM image, by contrast, there is no spatial dimension; there are only
+pixels.  You might have a line that is 100 pixels long, but the PNM
+image says nothing about how long that line should be on a printed
+page.
+.PP
+\fBpstopnm\fP fills the role of a Postscript printer.  The PNM image
+is a virtual printed page.  \fBpstopnm\fP must determine how many pixels
+it will use in the output image to represent an inch of input image,
+which is the "output device resolution."  Think of it as the number of
+dots per inch the virtual printer prints on the virtual page.
+.PP
+The simplest thing is for you to tell \fBpstopnm\fP exactly what
+output device resolution to use, using the \fB-dpi\fP option.  If you
+say for example \fB-dpi=300\fP and the bordered subject image is 2
+inches by 3 inches, the PNM output will be 600 pixels by 900 pixels.
+Using this method, the output device resolution has to be the same in
+both directions.
+.PP
+Or you can set the output image dimensions with \fB-xsize\fP and
+\fB-ysize\fP.  For example, if you say \fB-xsize=1200 -ysize=1800\fP and the
+bordered subject image is 2 inches wide by 3 inches high, the output image is
+1200 by 1800 pixels, with each pixel representing 1/600 inch of input image.
+.PP
+In the unlikely event that you want different output device resolutions in
+the two directions, you could use \fB-xsize\fP and \fB-ysize\fP to do that.
+In the above example, if you change \fB-ysize\fP to 900, a pixel still
+represents 1/600 inch horizontally, but 1/300 inch vertically.
+.PP
+If you specify one of \fB-xsize\fP and \fB-ysize\fP and not the
+other, \fBpstopnm\fP defaults the other such that the output device
+resolution is the same in both directions.
+.PP
+The "x" and "y" of \fB-xsize\fP and \fB-ysize\fP
+refer to the image being printed on the page, not the page.  So if
+\fBpstopnm\fP prints it in landscape orientation, "x" would pertain
+to the vertical direction on the page, i.e. the vertical direction in the
+output PNM image.
+.PP
+If you specify neither the output size nor the output device
+resolution, \fBpstopnm\fP does some weird computation which exists
+mainly for historical reasons:
+.PP
+If you specify \fB-nocrop\fP, \fBpstopnm\fP uses the values of
+\fB-xmax\fP and \fB-ymax\fP for the output image dimensions.  These
+default to 612 and 792 pixels, respectively.
+.PP
+The final case, the default, is where you don't specify any size or
+resolution options or \fB-nocrop\fP.  This is the most complicated
+case.  In this case, \fBpstopnm\fP first chooses an output device
+resolution that would generate the number of pixels indicated by
+\fB-xmax\fP and \fB-ymax\fP from the bordered subject image.  Then,
+based on that resolution, it chooses an output image size that is just
+large enough to accommodate the subject image (no borders).  Remember
+(above) that \fBpstopnm\fP trims the edges of the bordered subject
+image to fit the computed output size.
+
+
+.UN gslimitations
+.SS Ghostscript Limitations
+.PP
+Tests done in 2013 with Ghostscript 8.71 indicate that Ghostscript's
+\fBpgmraw\fP output driver has some kind of rounding error that causes the
+pixel values to change slightly, and that means \fBpstopnm\fP generates
+incorrect output when you have monochrome Postscript input.  But with color
+Postscript input, \fBpstopnm\fP uses Ghostscript's \fBppmraw\fP output
+driver and generates correct PPM output.
+
+
+.UN usagenotes
+.SS Usage Notes
+.PP
+There is some good advice on converting to and from Postscript, in the
+document
+.BR "
+Postcript File Conversions" (1)\c
+\& by Andrew T. Young.
+
+.UN reversible
+.B Reversible Conversion
+.PP
+If you're trying to do the equivalent of the naive 
+\f(CWpnmtops | pstopnm\fP, the following steps will do it.
+
+.nf
+\f(CW
+    $ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps
+    $ pstopnm -xborder=0 -yborder=0 -xsize=\fIXSIZE\fP -ysize=\fIYSIZE\fP \e
+        -portrait -stdout -quiet testimg.ps >testimg2.ppm
+\fP
+
+.fi
+
+\fIXSIZE\fP and \fIYSIZE\fP above are the image dimensions, which you can
+get from testimg.ps like in the following example (the grep, awk and echo
+commands are just to help demonstrate how the other commands work - you
+wouldn't use those in a program).
+
+.nf
+\f(CW
+    $ grep "BoundingBox" testimg.ps
+    %%BoundingBox: 0 0 227 149
+
+    $ awk  '/%%BoundingBox/ {print $4,$5}' testimg.ps
+     227 149
+ 
+    $ xysize=$(awk  '/%%BoundingBox/ {print "-xsize="$4,"-ysize="$5}' testimg.ps)
+    $ echo $xysize
+
+     -xsize=227 -ysize=149
+
+    $ pstopnm -xborder=0 -yborder=0 $xysize -portrait ... testimg.ps
+\fP
+
+.fi
+.PP
+Note that Ghostscript bugs can keep this from doing a perfect
+reversible conversion.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpstopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-forceplain\fP
+ forces the output file to be in plain (text) format.  Otherwise,
+it is in raw (binary) format.  See
+.BR "pbm" (1)\c
+\&,
+etc.  Use this instead of the \fB-plain\fP common option if you need
+plain format output.
+
+.TP
+\fB-llx=\fP\fIbx\fP
+selects \fIbx\fP as the lower left corner x coordinate (in
+inches) on the Postscript input page of the subject image.
+See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-lly=\fP\fIby\fP
+selects \fIby\fP as the lower left corner y coordinate (in inches)
+on the Postscript input page of the subject image.
+See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-landscape\fP
+renders the image in landscape orientation.
+.sp
+If you specify neither \fB-portrait\fP nor \fB-landscape\fP,
+\fBpstopnm\fP chooses the orientation that best fits the image on the
+output page.
+.sp
+Landscape means printed sideways on the page, not printed the long way.
+Those are different things if the long edge of the page is the top one.
+
+.TP
+\fB-portrait\fP
+renders the image in portrait orientation.
+.sp
+See \fB-landscape\fP.
+
+.TP
+\fB-nocrop\fP
+This option causes \fBpstopnm\fP to make the output image
+exactly the dimensions of the bordered subject image.  By default,
+\fBpstopnm\fP makes the output image the dimensions specified by
+\fB-xmax\fP and \fB-ymax\fP.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-pbm\fP
+.TP
+\fB-pgm\fP
+.TP
+\fB-ppm\fP
+selects the format of the output file.  By default, all files are
+rendered as PPM.
+
+.TP
+\fB-stdout\fP
+causes output to go to Standard Output instead of to regular
+files, one per page (see description of output files above).  Use
+\fBpnmsplit\fP to extract individual pages from Standard Output.
+
+.TP
+\fB-urx=\fP\fItx\fP
+selects \fItx\fP as the upper right corner x coordinate (in
+inches) on the Postscript input page of the subject image.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-ury=\fP\fIty\fP
+selects \fIty\fP as the upper right corner y coordinate (in
+inches) on the Postscript input page of the subject image.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+
+.TP
+\fB-verbose\fP
+prints processing information to stdout.
+
+.TP
+\fB-xborder=\fP\fIfrac\fP 
+specifies that the left and right borders added to the subject
+image are to be \fIfrac\fP times the subject image width.  The
+default value is 0.1.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+
+.TP
+\fB-xmax=\fP\fIxmax\fP
+specifies that the output image is to be \fIxmax\fP pixels wide.
+The default is 612.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+
+.TP
+\fB-xsize=\fP\fIxsize\fP
+specifies that the output image is to be \fIxsize\fP pixels wide.
+See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-yborder=\fP\fIfrac\fP
+specifies that the top and bottom borders added to the subject
+image are to be \fIfrac\fP times the subject image height.  The
+default value is 0.1.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+
+.TP
+\fB-ymax=\fP\fIymax\fP
+specifies that the output image is to be \fIymax\fP pixels high.
+The default is 792.  See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-ysize=\fP\fIysize\fP
+specifies that the output image is to be \fIymax\fP pixels high.
+See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+
+.TP
+\fB-dpi=\fP\fIdpi\fP
+specifies the output device resolution, in dots per inch, of the
+Postscript printer that \fBpstopnm\fP simulates.  This is the number of
+PNM pixels \fBpstopnm\fP generates for each inch of image.
+See 
+.UR #dimensions
+the Dimensions section
+.UE
+\&.
+.sp
+This option was new in Netpbm 10.21 (March 2004).
+     
+.TP
+\fB-textalphabits=\fP{\fB1\fP,\fB2\fP,\fB4\fP}
+This controls subsample antialiasing of text.  Antialiasing is a form of
+smoothing that eliminates jagged edges on characters.  Subsample antialiasing
+is a kind of antialiasing that uses subpixels in a box, and the value of this
+option is the size of that box.  4 gives you the best looking output, while 1
+causes no antialiasing.  Smaller numbers make \fBpnmtops\fP use less CPU
+time.
+.sp
+Pstopnm uses Ghostscript's \fBTextAlphaBits\fP parameter for this.
+.sp
+The default is 4.
+.sp
+This option was new in Netpbm 10.53 (December 2010).  Older versions of
+\fBpstopnm\fP do no antialiasing.
+
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The program will produce incorrect results with PostScript files that
+initialize the current transformation matrix.  In these cases, page
+translation and rotation will not have any effect.  To render these
+files, probably the best bet is to use the following options:
+
+.nf
+    pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps
+
+.fi
+.PP
+Additional options may be needed if the document is supposed to be
+rendered on a medium different from letter-size paper.
+
+.UN seealso
+.SH SEE ALSO
+
+\fBgs\fP,
+.BR "pnmtops" (1)\c
+\&,
+.BR "psidtopgm" (1)\c
+\&,
+.BR "pbmtolps" (1)\c
+\&,
+.BR "pbmtoepsi" (1)\c
+\&,
+.BR "pnmsplit" (1)\c
+\&,
+\fBpstofits\fP
+
+
+
+.UN copyright
+.SH COPYRIGHT
+.PP
+Copyright (c) 1992 Smithsonian Astrophysical Observatory
+.PP
+PostScript is a Trademark of Adobe Systems Incorporated.
+
+
+.UN author
+.SH AUTHOR
+.PP
+Alberto Accomazzi, WIPL, Center for Astrophysics.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pstopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/pstops.1 b/upstream/mageia-cauldron/man1/pstops.1
new file mode 100644
index 00000000..be9ce8b6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pstops.1
@@ -0,0 +1,213 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH PSTOPS "1" "October 2021" "pstops 2.07" "User Commands"
+.SH NAME
+pstops - rearrange pages of a PostScript document
+.SH SYNOPSIS
+.B pstops
+[\fI\,OPTION\/\fR...] [\fI\,INFILE \/\fR[\fI\,OUTFILE\/\fR]]
+.SH DESCRIPTION
+Rearrange pages of a PostScript document.
+.PP
+The input PostScript file should follow the Adobe Document Structuring
+Conventions.
+.PP
+.I Pstops
+can be used to perform arbitrary re-arrangements of documents. For many tasks,
+it is simpler to use the other utilities in the PSUtils suite: see
+.BR psutils (1).
+.TP
+\fB\-S\fR, \fB\-\-specs\fR=\fI\,SPECS\/\fR
+page specifications (see below)
+.TP
+\fB\-R\fR, \fB\-\-pages\fR=\fI\,PAGES\/\fR
+select the given page ranges
+.TP
+\fB\-e\fR, \fB\-\-even\fR
+select even\-numbered output pages
+.TP
+\fB\-o\fR, \fB\-\-odd\fR
+select odd\-numbered output pages
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse the order of the output pages
+.TP
+\fB\-p\fR, \fB\-\-paper\fR=\fI\,PAPER\/\fR
+output paper name or dimensions (WIDTHxHEIGHT)
+.TP
+\fB\-P\fR, \fB\-\-inpaper\fR=\fI\,PAPER\/\fR
+input paper name or dimensions (WIDTHxHEIGHT)
+.TP
+\fB\-d\fR, \fB\-\-draw\fR[=\fI\,DIMENSION\/\fR]
+draw a line of given width (relative to original
+page) around each page [argument defaults to 1;
+default is 0]
+.TP
+\fB\-b\fR, \fB\-\-nobind\fR
+disable PostScript bind operators in prolog;
+may be needed for complex page rearrangements
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+don't show page numbers being output
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.PP
+PAGES is a comma\-separated list of pages and page ranges.
+.PP
+Each may be a page number, or a page range of the form
+.IB first \- last .
+If
+.I first
+is omitted, the first page is assumed, and if
+.I last
+is omitted, the last page is assumed.
+The prefix character \[oq]_\[cq] indicates that the page number is relative to the end
+of the document, counting backwards.
+If just this character with no page number is used, a blank page will be
+inserted.
+Page numbers refer to the pages as they occur in the file, starting
+at one.
+The actual page number in the document may be different.
+.PP
+PAGESPECS is a list of page specifications [default is "0", which
+selects each page in its normal order].
+.PP
+Pagespecs have the following syntax:
+.RS
+.TP 12
+.I pagespecs
+=
+.RI [ modulo\fB:\fP ] specs
+.TP
+.I specs
+=
+.IR spec [ \fB+\fPspecs | \fB,\fPspecs ]
+.TP
+.I spec
+=
+.RB [ - ] \fIpageno\fP [\fIturns\fP][ @\fIscale\fP ][ ( \fIxoff\fP , \fIyoff\fP ) ]
+.TP
+.I turns
+=
+.IR turn [ turns ]
+.TP
+.I turn
+=
+.BR L | R | U | H | V
+.RE
+.sp
+.I modulo
+is the number of pages in each block.
+The value of
+.I modulo
+should be greater than 0; the default value is 1.
+.PP
+.I specs
+are the page specifications for the pages in each block.
+The value of the
+.I pageno
+in each
+.I spec
+should be between 0 (for the first page in the block) and \fImodulo\fR\-1
+(for the last page in each block) inclusive.
+If there is only one page specification,
+the \fIpageno\fR (0) may be omitted.
+.PP
+The optional dimensions
+.I xoff
+and
+.I yoff
+shift the page by the specified amount.
+.I xoff
+and
+.I yoff
+may either be lengths (see
+.BR psutils (1))
+or followed by
+.B "w"
+or
+.B "h"
+to indicate a multiple of the output paper width or height.
+.PP
+The optional parameters
+.BR L ,
+.BR R ,
+.BR U ,
+.BR H ,
+and
+.B V
+rotate the page left, right, or upside-down, and flip (mirror) the page
+horizontally or vertically respectively.
+The optional
+.I scale
+parameter scales the page by the fraction specified.
+If the optional minus sign is specified, the page number is relative to the end of
+the document, instead of the start.
+.PP
+Pages whose
+.IR spec s
+are separated by
+.B +
+will be merged into a single page; otherwise,
+they will remain as separate pages.
+.PP
+The shift, rotation, and scaling are applied
+to the PostScript transformation matrix
+in that order, regardless of the order
+in which they appear on the command line.
+.PP
+Paper size names are converted to dimensions using
+.BR paper (1).
+The output paper size, if set, is used (after scaling) to set the
+clipping path for each page.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if arguments or options are incorrect, or there is some other problem
+starting up,
+.TP
+2
+if there is some problem during processing, typically an error reading or
+writing an input or output file.
+.SH EXAMPLES
+To put two pages on one sheet of A4 paper, the pagespec to use is:
+.sp
+.ce
+2:0L@.7(21cm,0)+1L@.7(21cm,14.85cm)
+.sp
+To select all of the odd pages in reverse order, use:
+.sp
+.ce
+2:-0
+.sp
+To re-arrange pages for printing 2-up booklets, use
+.sp
+.ce
+4:-3L@.7(21cm,0)+0L@.7(21cm,14.85cm)
+.sp
+for the front sides, and
+.sp
+.ce
+4:1L@.7(21cm,0)+-2L@.7(21cm,14.85cm)
+.sp
+for the reverse sides (or join them with a comma for duplex printing).
+.SH AUTHOR
+Written by Angus J. C. Duggan and Reuben Thomas.
+.SH BUGS
+.B Pstops
+does not accept all DSC comments.
+.SH COPYRIGHT
+Copyright \(co Reuben Thomas 2017\-2020.
+Released under the GPL version 3, or (at your option) any later version.
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
+.SH "SEE ALSO"
+.BR psutils (1),
+.BR paper (1)
diff --git a/upstream/mageia-cauldron/man1/psutils.1 b/upstream/mageia-cauldron/man1/psutils.1
new file mode 100644
index 00000000..8bcc2874
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/psutils.1
@@ -0,0 +1,41 @@
+.TH PSUTILS 1 "PSUtils"
+.SH NAME
+PSUtils \- PostScript utilities
+.SH DESCRIPTION
+PSUtils is a set of utilities for manipulating PostScript
+documents which follow the Adobe Document Structuring Conventions.
+.SH UNITS OF LENGTH
+PSUtils utilities accept lengths in various units:
+.IP \(bu
+.B pt
+(PostScript points, 72 points per inch)
+.IP \(bu
+.B mm
+(millimetres)
+.IP \(bu
+.B cm
+(centimetres)
+.IP \(bu
+.B in
+(inches, 1 inch is 25.4mm)
+.PP
+Write the length as a number directly followed by the unit, for example,
+.B 4.5mm
+or
+.BR 72pt .
+If no unit is given, PostScript points are assumed.
+.SH AUTHOR
+Written by Angus J. C. Duggan.
+.SH "SEE ALSO"
+.BR psbook (1),
+.BR psselect (1),
+.BR pstops (1),
+.BR epsffit (1),
+.BR psnup (1),
+.BR psresize (1),
+.BR psjoin (1),
+.BR extractres (1),
+.BR includeres (1)
+.SH TRADEMARKS
+.B PostScript
+is a trademark of Adobe Systems Incorporated.
diff --git a/upstream/mageia-cauldron/man1/ptar.1 b/upstream/mageia-cauldron/man1/ptar.1
new file mode 100644
index 00000000..52d8d05d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ptar.1
@@ -0,0 +1,93 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PTAR 1"
+.TH PTAR 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+ptar \- a tar\-like program written in perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+ptar is a small, tar look-alike program that uses the perl module
+Archive::Tar to extract, create and list tar archives.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 5
+\&    ptar \-c [\-v] [\-z] [\-C] [\-f ARCHIVE_FILE | \-] FILE FILE ...
+\&    ptar \-c [\-v] [\-z] [\-C] [\-T index | \-] [\-f ARCHIVE_FILE | \-]
+\&    ptar \-x [\-v] [\-z] [\-f ARCHIVE_FILE | \-]
+\&    ptar \-t [\-z] [\-f ARCHIVE_FILE | \-]
+\&    ptar \-h
+.Ve
+.SH OPTIONS
+.IX Header "OPTIONS"
+.Vb 9
+\&    c   Create ARCHIVE_FILE or STDOUT (\-) from FILE
+\&    x   Extract from ARCHIVE_FILE or STDIN (\-)
+\&    t   List the contents of ARCHIVE_FILE or STDIN (\-)
+\&    f   Name of the ARCHIVE_FILE to use. Default is \*(Aq./default.tar\*(Aq
+\&    z   Read/Write zlib compressed ARCHIVE_FILE (not always available)
+\&    v   Print filenames as they are added or extracted from ARCHIVE_FILE
+\&    h   Prints this help message
+\&    C   CPAN mode \- drop 022 from permissions
+\&    T   get names to create from file
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBtar\fR\|(1), Archive::Tar.
diff --git a/upstream/mageia-cauldron/man1/ptardiff.1 b/upstream/mageia-cauldron/man1/ptardiff.1
new file mode 100644
index 00000000..c8fd57cd
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ptardiff.1
@@ -0,0 +1,96 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PTARDIFF 1"
+.TH PTARDIFF 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+ptardiff \- program that diffs an extracted archive against an unextracted one
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.Vb 2
+\&    ptardiff is a small program that diffs an extracted archive
+\&    against an unextracted one, using the perl module Archive::Tar.
+\&
+\&    This effectively lets you view changes made to an archives contents.
+\&
+\&    Provide the progam with an ARCHIVE_FILE and it will look up all
+\&    the files with in the archive, scan the current working directory
+\&    for a file with the name and diff it against the contents of the
+\&    archive.
+.Ve
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    ptardiff ARCHIVE_FILE
+\&    ptardiff \-h
+\&
+\&    $ tar \-xzf Acme\-Buffy\-1.3.tar.gz
+\&    $ vi Acme\-Buffy\-1.3/README
+\&    [...]
+\&    $ ptardiff Acme\-Buffy\-1.3.tar.gz > README.patch
+.Ve
+.SH OPTIONS
+.IX Header "OPTIONS"
+.Vb 1
+\&    h   Prints this help message
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBtar\fR\|(1), Archive::Tar.
diff --git a/upstream/mageia-cauldron/man1/ptargrep.1 b/upstream/mageia-cauldron/man1/ptargrep.1
new file mode 100644
index 00000000..90a4f441
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ptargrep.1
@@ -0,0 +1,116 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PTARGREP 1"
+.TH PTARGREP 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+ptargrep \- Apply pattern matching to the contents of files in a tar archive
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  ptargrep [options] <pattern> <tar file> ...
+\&
+\&  Options:
+\&
+\&   \-\-basename|\-b     ignore directory paths from archive
+\&   \-\-ignore\-case|\-i  do case\-insensitive pattern matching
+\&   \-\-list\-only|\-l    list matching filenames rather than extracting matches
+\&   \-\-verbose|\-v      write debugging message to STDERR
+\&   \-\-help|\-?         detailed help message
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This utility allows you to apply pattern matching to \fBthe contents\fR of files
+contained in a tar archive.  You might use this to identify all files in an
+archive which contain lines matching the specified pattern and either print out
+the pathnames or extract the files.
+.PP
+The pattern will be used as a Perl regular expression (as opposed to a simple
+grep regex).
+.PP
+Multiple tar archive filenames can be specified \- they will each be processed
+in turn.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP "\fB\-\-basename\fR (alias \-b)" 4
+.IX Item "--basename (alias -b)"
+When matching files are extracted, ignore the directory path from the archive
+and write to the current directory using the basename of the file from the
+archive.  Beware: if two matching files in the archive have the same basename,
+the second file extracted will overwrite the first.
+.IP "\fB\-\-ignore\-case\fR (alias \-i)" 4
+.IX Item "--ignore-case (alias -i)"
+Make pattern matching case-insensitive.
+.IP "\fB\-\-list\-only\fR (alias \-l)" 4
+.IX Item "--list-only (alias -l)"
+Print the pathname of each matching file from the archive to STDOUT.  Without
+this option, the default behaviour is to extract each matching file.
+.IP "\fB\-\-verbose\fR (alias \-v)" 4
+.IX Item "--verbose (alias -v)"
+Log debugging info to STDERR.
+.IP "\fB\-\-help\fR (alias \-?)" 4
+.IX Item "--help (alias -?)"
+Display this documentation.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2010 Grant McLean <grantm@cpan.org>
+.PP
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/ptx.1 b/upstream/mageia-cauldron/man1/ptx.1
new file mode 100644
index 00000000..e099bce7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ptx.1
@@ -0,0 +1,91 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PTX "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+ptx \- produce a permuted index of file contents
+.SH SYNOPSIS
+.B ptx
+[\fI\,OPTION\/\fR]... [\fI\,INPUT\/\fR]...   \fI\,(without -G)\/\fR
+.br
+.B ptx
+\fI\,-G \/\fR[\fI\,OPTION\/\fR]... [\fI\,INPUT \/\fR[\fI\,OUTPUT\/\fR]]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output a permuted index, including context, of the words in the input files.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-A\fR, \fB\-\-auto\-reference\fR
+output automatically generated references
+.TP
+\fB\-G\fR, \fB\-\-traditional\fR
+behave more like System V 'ptx'
+.TP
+\fB\-F\fR, \fB\-\-flag\-truncation\fR=\fI\,STRING\/\fR
+use STRING for flagging line truncations.
+The default is '/'
+.TP
+\fB\-M\fR, \fB\-\-macro\-name\fR=\fI\,STRING\/\fR
+macro name to use instead of 'xx'
+.TP
+\fB\-O\fR, \fB\-\-format\fR=\fI\,roff\/\fR
+generate output as roff directives
+.TP
+\fB\-R\fR, \fB\-\-right\-side\-refs\fR
+put references at right, not counted in \fB\-w\fR
+.TP
+\fB\-S\fR, \fB\-\-sentence\-regexp\fR=\fI\,REGEXP\/\fR
+for end of lines or end of sentences
+.TP
+\fB\-T\fR, \fB\-\-format\fR=\fI\,tex\/\fR
+generate output as TeX directives
+.TP
+\fB\-W\fR, \fB\-\-word\-regexp\fR=\fI\,REGEXP\/\fR
+use REGEXP to match each keyword
+.TP
+\fB\-b\fR, \fB\-\-break\-file\fR=\fI\,FILE\/\fR
+word break characters in this FILE
+.TP
+\fB\-f\fR, \fB\-\-ignore\-case\fR
+fold lower case to upper case for sorting
+.TP
+\fB\-g\fR, \fB\-\-gap\-size\fR=\fI\,NUMBER\/\fR
+gap size in columns between output fields
+.TP
+\fB\-i\fR, \fB\-\-ignore\-file\fR=\fI\,FILE\/\fR
+read ignore word list from FILE
+.TP
+\fB\-o\fR, \fB\-\-only\-file\fR=\fI\,FILE\/\fR
+read only word list from this FILE
+.TP
+\fB\-r\fR, \fB\-\-references\fR
+first field of each line is a reference
+.HP
+\fB\-t\fR, \fB\-\-typeset\-mode\fR               \- not implemented \-
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+output width in columns, reference excluded
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by F. Pinard.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/ptx>
+.br
+or available locally via: info \(aq(coreutils) ptx invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/pwd.1 b/upstream/mageia-cauldron/man1/pwd.1
new file mode 100644
index 00000000..ffe5ef20
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pwd.1
@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH PWD "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+pwd \- print name of current/working directory
+.SH SYNOPSIS
+.B pwd
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the full filename of the current working directory.
+.TP
+\fB\-L\fR, \fB\-\-logical\fR
+use PWD from environment, even if it contains symlinks
+.TP
+\fB\-P\fR, \fB\-\-physical\fR
+avoid all symlinks
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If no option is specified, \fB\-P\fR is assumed.
+.PP
+NOTE: your shell may have its own version of pwd, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBgetcwd\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/pwd>
+.br
+or available locally via: info \(aq(coreutils) pwd invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/python3.12.1 b/upstream/mageia-cauldron/man1/python3.12.1
new file mode 100644
index 00000000..9f89c94a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/python3.12.1
@@ -0,0 +1,629 @@
+.TH PYTHON "1"
+
+.\" To view this file while editing, run it through groff:
+.\"   groff -Tascii -man python.man | less
+
+.SH NAME
+python \- an interpreted, interactive, object-oriented programming language
+.SH SYNOPSIS
+.B python
+[
+.B \-B
+]
+[
+.B \-b
+]
+[
+.B \-d
+]
+[
+.B \-E
+]
+[
+.B \-h
+]
+[
+.B \-i
+]
+[
+.B \-I
+]
+.br
+       [
+.B \-m
+.I module-name
+]
+[
+.B \-q
+]
+[
+.B \-O
+]
+[
+.B \-OO
+]
+[
+.B \-P
+]
+[
+.B \-s
+]
+[
+.B \-S
+]
+[
+.B \-u
+]
+.br
+       [
+.B \-v
+]
+[
+.B \-V
+]
+[
+.B \-W
+.I argument
+]
+[
+.B \-x
+]
+[
+.B \-X
+.I option
+]
+[
+.B \-?
+]
+.br
+       [
+.B \--check-hash-based-pycs
+.I default
+|
+.I always
+|
+.I never
+]
+.br
+       [
+.B \--help
+]
+[
+.B \--help-env
+]
+[
+.B \--help-xoptions
+]
+[
+.B \--help-all
+]
+.br
+       [
+.B \-c
+.I command
+|
+.I script
+|
+\-
+]
+[
+.I arguments
+]
+.SH DESCRIPTION
+Python is an interpreted, interactive, object-oriented programming
+language that combines remarkable power with very clear syntax.
+For an introduction to programming in Python, see the Python Tutorial.
+The Python Library Reference documents built-in and standard types,
+constants, functions and modules.
+Finally, the Python Reference Manual describes the syntax and
+semantics of the core language in (perhaps too) much detail.
+(These documents may be located via the
+.B "INTERNET RESOURCES"
+below; they may be installed on your system as well.)
+.PP
+Python's basic power can be extended with your own modules written in
+C or C++.
+On most systems such modules may be dynamically loaded.
+Python is also adaptable as an extension language for existing
+applications.
+See the internal documentation for hints.
+.PP
+Documentation for installed Python modules and packages can be
+viewed by running the
+.B pydoc
+program.
+.SH COMMAND LINE OPTIONS
+.TP
+.B \-B
+Don't write
+.I .pyc
+files on import. See also PYTHONDONTWRITEBYTECODE.
+.TP
+.B \-b
+Issue warnings about str(bytes_instance), str(bytearray_instance)
+and comparing bytes/bytearray with str. (-bb: issue errors)
+.TP
+.BI "\-c " command
+Specify the command to execute (see next section).
+This terminates the option list (following options are passed as
+arguments to the command).
+.TP
+.BI "\-\-check-hash-based-pycs " mode
+Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
+.TP
+.B \-d
+Turn on parser debugging output (for expert only, depending on
+compilation options).
+.TP
+.B \-E
+Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
+the behavior of the interpreter.
+.TP
+.B \-h ", " \-? ", "\-\-help
+Prints the usage for the interpreter executable and exits.
+.TP
+.B "\-\-help\-env"
+Prints help about Python-specific environment variables and exits.
+.TP
+.B "\-\-help\-xoptions"
+Prints help about implementation-specific \fB\-X\fP options and exits.
+.TP
+.TP
+.B "\-\-help\-all"
+Prints complete usage information and exits.
+.TP
+.B \-i
+When a script is passed as first argument or the \fB\-c\fP option is
+used, enter interactive mode after executing the script or the
+command.  It does not read the $PYTHONSTARTUP file.  This can be
+useful to inspect global variables or a stack trace when a script
+raises an exception.
+.TP
+.B \-I
+Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and \fB\-s\fP. In
+isolated mode sys.path contains neither the script's directory nor the user's
+site-packages directory. All PYTHON* environment variables are ignored, too.
+Further restrictions may be imposed to prevent the user from injecting
+malicious code.
+.TP
+.BI "\-m " module-name
+Searches
+.I sys.path
+for the named module and runs the corresponding
+.I .py
+file as a script. This terminates the option list (following options
+are passed as arguments to the module).
+.TP
+.B \-O
+Remove assert statements and any code conditional on the value of
+__debug__; augment the filename for compiled (bytecode) files by
+adding .opt-1 before the .pyc extension.
+.TP
+.B \-OO
+Do \fB-O\fP and also discard docstrings; change the filename for
+compiled (bytecode) files by adding .opt-2 before the .pyc extension.
+.TP
+.B \-P
+Don't automatically prepend a potentially unsafe path to \fBsys.path\fP such
+as the current directory, the script's directory or an empty string. See also the
+\fBPYTHONSAFEPATH\fP environment variable.
+.TP
+.B \-q
+Do not print the version and copyright messages. These messages are
+also suppressed in non-interactive mode.
+.TP
+.B \-s
+Don't add user site directory to sys.path.
+.TP
+.B \-S
+Disable the import of the module
+.I site
+and the site-dependent manipulations of
+.I sys.path
+that it entails.  Also disable these manipulations if
+.I site
+is explicitly imported later.
+.TP
+.B \-u
+Force the stdout and stderr streams to be unbuffered.
+This option has no effect on the stdin stream.
+.TP
+.B \-v
+Print a message each time a module is initialized, showing the place
+(filename or built-in module) from which it is loaded.  When given
+twice, print a message for each file that is checked for when
+searching for a module.  Also provides information on module cleanup
+at exit.
+.TP
+.B \-V ", " \-\-version
+Prints the Python version number of the executable and exits.  When given
+twice, print more information about the build.
+
+.TP
+.BI "\-W " argument
+Warning control. Python's warning machinery by default prints warning messages
+to
+.IR sys.stderr .
+
+The simplest settings apply a particular action unconditionally to all warnings
+emitted by a process (even those that are otherwise ignored by default):
+
+  -Wdefault  # Warn once per call location
+  -Werror    # Convert to exceptions
+  -Walways   # Warn every time
+  -Wmodule   # Warn once per calling module
+  -Wonce     # Warn once per Python process
+  -Wignore   # Never warn
+
+The action names can be abbreviated as desired and the interpreter will resolve
+them to the appropriate action name. For example,
+.B -Wi
+is the same as
+.B -Wignore .
+
+The full form of argument is:
+.IB action:message:category:module:lineno
+
+Empty fields match all values; trailing empty fields may be omitted. For
+example
+.B -W ignore::DeprecationWarning
+ignores all DeprecationWarning warnings.
+
+The
+.I action
+field is as explained above but only applies to warnings that match
+the remaining fields.
+
+The
+.I message
+field must match the whole printed warning message; this match is
+case-insensitive.
+
+The
+.I category
+field matches the warning category (ex: "DeprecationWarning"). This must be a
+class name; the match test whether the actual warning category of the message
+is a subclass of the specified warning category.
+
+The
+.I module
+field matches the (fully-qualified) module name; this match is case-sensitive.
+
+The
+.I lineno
+field matches the line number, where zero matches all line numbers and is thus
+equivalent to an omitted line number.
+
+Multiple
+.B -W
+options can be given; when a warning matches more than one option, the action
+for the last matching option is performed. Invalid
+.B -W
+options are ignored (though, a warning message is printed about invalid options
+when the first warning is issued).
+
+Warnings can also be controlled using the
+.B PYTHONWARNINGS
+environment variable and from within a Python program using the warnings
+module.  For example, the warnings.filterwarnings() function can be used to use
+a regular expression on the warning message.
+
+.TP
+.BI "\-X " option
+Set implementation-specific option. The following options are available:
+
+    -X faulthandler: enable faulthandler
+
+    -X showrefcount: output the total reference count and number of used
+        memory blocks when the program finishes or after each statement in the
+        interactive interpreter. This only works on debug builds
+
+    -X tracemalloc: start tracing Python memory allocations using the
+        tracemalloc module. By default, only the most recent frame is stored in a
+        traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a
+        traceback limit of NFRAME frames
+
+    -X importtime: show how long each import takes. It shows module name,
+        cumulative time (including nested imports) and self time (excluding
+        nested imports). Note that its output may be broken in multi-threaded
+        application. Typical usage is python3 -X importtime -c 'import asyncio'
+
+    -X dev: enable CPython's "development mode", introducing additional runtime
+        checks which are too expensive to be enabled by default. It will not be
+        more verbose than the default if the code is correct: new warnings are
+        only emitted when an issue is detected. Effect of the developer mode:
+           * Add default warning filter, as -W default
+           * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()
+             C function
+           * Enable the faulthandler module to dump the Python traceback on a crash
+           * Enable asyncio debug mode
+           * Set the dev_mode attribute of sys.flags to True
+           * io.IOBase destructor logs close() exceptions
+
+    -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default
+        locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would
+        otherwise activate automatically). See PYTHONUTF8 for more details
+
+    -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the
+        given directory instead of to the code tree.
+
+    -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'
+
+    -X no_debug_ranges: disable the inclusion of the tables mapping extra location
+       information (end line, start column offset and end column offset) to every
+       instruction in code objects. This is useful when smaller code objects and pyc
+       files are desired as well as suppressing the extra visual location indicators
+       when the interpreter displays tracebacks.
+
+    -X frozen_modules=[on|off]: whether or not frozen modules should be used.
+       The default is "on" (or "off" if you are running a local build).
+
+    -X int_max_str_digits=number: limit the size of int<->str conversions.
+       This helps avoid denial of service attacks when parsing untrusted data.
+       The default is sys.int_info.default_max_str_digits.  0 disables.
+
+.TP
+.B \-x
+Skip the first line of the source.  This is intended for a DOS
+specific hack only.  Warning: the line numbers in error messages will
+be off by one!
+.SH INTERPRETER INTERFACE
+The interpreter interface resembles that of the UNIX shell: when
+called with standard input connected to a tty device, it prompts for
+commands and executes them until an EOF is read; when called with a
+file name argument or with a file as standard input, it reads and
+executes a
+.I script
+from that file;
+when called with
+.B \-c
+.IR command ,
+it executes the Python statement(s) given as
+.IR command .
+Here
+.I command
+may contain multiple statements separated by newlines.
+Leading whitespace is significant in Python statements!
+In non-interactive mode, the entire input is parsed before it is
+executed.
+.PP
+If available, the script name and additional arguments thereafter are
+passed to the script in the Python variable
+.IR sys.argv ,
+which is a list of strings (you must first
+.I import sys
+to be able to access it).
+If no script name is given,
+.I sys.argv[0]
+is an empty string; if
+.B \-c
+is used,
+.I sys.argv[0]
+contains the string
+.I '-c'.
+Note that options interpreted by the Python interpreter itself
+are not placed in
+.IR sys.argv .
+.PP
+In interactive mode, the primary prompt is `>>>'; the second prompt
+(which appears when a command is not complete) is `...'.
+The prompts can be changed by assignment to
+.I sys.ps1
+or
+.IR sys.ps2 .
+The interpreter quits when it reads an EOF at a prompt.
+When an unhandled exception occurs, a stack trace is printed and
+control returns to the primary prompt; in non-interactive mode, the
+interpreter exits after printing the stack trace.
+The interrupt signal raises the
+.I Keyboard\%Interrupt
+exception; other UNIX signals are not caught (except that SIGPIPE is
+sometimes ignored, in favor of the
+.I IOError
+exception).  Error messages are written to stderr.
+.SH FILES AND DIRECTORIES
+These are subject to difference depending on local installation
+conventions; ${prefix} and ${exec_prefix} are installation-dependent
+and should be interpreted as for GNU software; they may be the same.
+The default for both is \fI/usr/local\fP.
+.IP \fI${exec_prefix}/bin/python\fP
+Recommended location of the interpreter.
+.PP
+.I ${prefix}/lib/python<version>
+.br
+.I ${exec_prefix}/lib/python<version>
+.RS
+Recommended locations of the directories containing the standard
+modules.
+.RE
+.PP
+.I ${prefix}/include/python<version>
+.br
+.I ${exec_prefix}/include/python<version>
+.RS
+Recommended locations of the directories containing the include files
+needed for developing Python extensions and embedding the
+interpreter.
+.RE
+.SH ENVIRONMENT VARIABLES
+.IP PYTHONSAFEPATH
+If this is set to a non-empty string, don't automatically prepend a potentially
+unsafe path to \fBsys.path\fP such as the current directory, the script's
+directory or an empty string. See also the \fB\-P\fP option.
+.IP PYTHONHOME
+Change the location of the standard Python libraries.  By default, the
+libraries are searched in ${prefix}/lib/python<version> and
+${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
+are installation-dependent directories, both defaulting to
+\fI/usr/local\fP.  When $PYTHONHOME is set to a single directory, its value
+replaces both ${prefix} and ${exec_prefix}.  To specify different values
+for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
+.IP PYTHONPATH
+Augments the default search path for module files.
+The format is the same as the shell's $PATH: one or more directory
+pathnames separated by colons.
+Non-existent directories are silently ignored.
+The default search path is installation dependent, but generally
+begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
+The default search path is always appended to $PYTHONPATH.
+If a script argument is given, the directory containing the script is
+inserted in the path in front of $PYTHONPATH.
+The search path can be manipulated from within a Python program as the
+variable
+.IR sys.path .
+.IP PYTHONPLATLIBDIR
+Override sys.platlibdir.
+.IP PYTHONSTARTUP
+If this is the name of a readable file, the Python commands in that
+file are executed before the first prompt is displayed in interactive
+mode.
+The file is executed in the same name space where interactive commands
+are executed so that objects defined or imported in it can be used
+without qualification in the interactive session.
+You can also change the prompts
+.I sys.ps1
+and
+.I sys.ps2
+in this file.
+.IP PYTHONOPTIMIZE
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-O\fP option. If set to an integer, it is equivalent to
+specifying \fB\-O\fP multiple times.
+.IP PYTHONDEBUG
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-d\fP option. If set to an integer, it is equivalent to
+specifying \fB\-d\fP multiple times.
+.IP PYTHONDONTWRITEBYTECODE
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-B\fP option (don't try to write
+.I .pyc
+files).
+.IP PYTHONINSPECT
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-i\fP option.
+.IP PYTHONIOENCODING
+If this is set before running the interpreter, it overrides the encoding used
+for stdin/stdout/stderr, in the syntax
+.IB encodingname ":" errorhandler
+The
+.IB errorhandler
+part is optional and has the same meaning as in str.encode. For stderr, the
+.IB errorhandler
+ part is ignored; the handler will always be \'backslashreplace\'.
+.IP PYTHONNOUSERSITE
+If this is set to a non-empty string it is equivalent to specifying the
+\fB\-s\fP option (Don't add the user site directory to sys.path).
+.IP PYTHONUNBUFFERED
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-u\fP option.
+.IP PYTHONVERBOSE
+If this is set to a non-empty string it is equivalent to specifying
+the \fB\-v\fP option. If set to an integer, it is equivalent to
+specifying \fB\-v\fP multiple times.
+.IP PYTHONWARNINGS
+If this is set to a comma-separated string it is equivalent to
+specifying the \fB\-W\fP option for each separate value.
+.IP PYTHONHASHSEED
+If this variable is set to "random", a random value is used to seed the hashes
+of str and bytes objects.
+
+If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for
+generating the hash() of the types covered by the hash randomization.  Its
+purpose is to allow repeatable hashing, such as for selftests for the
+interpreter itself, or to allow a cluster of python processes to share hash
+values.
+
+The integer must be a decimal number in the range [0,4294967295].  Specifying
+the value 0 will disable hash randomization.
+.IP PYTHONINTMAXSTRDIGITS
+Limit the maximum digit characters in an int value
+when converting from a string and when converting an int back to a str.
+A value of 0 disables the limit.  Conversions to or from bases 2, 4, 8,
+16, and 32 are never limited.
+.IP PYTHONMALLOC
+Set the Python memory allocators and/or install debug hooks. The available
+memory allocators are
+.IR malloc
+and
+.IR pymalloc .
+The available debug hooks are
+.IR debug ,
+.IR malloc_debug ,
+and
+.IR pymalloc_debug .
+.IP
+When Python is compiled in debug mode, the default is
+.IR pymalloc_debug
+and the debug hooks are automatically used. Otherwise, the default is
+.IR pymalloc .
+.IP PYTHONMALLOCSTATS
+If set to a non-empty string, Python will print statistics of the pymalloc
+memory allocator every time a new pymalloc object arena is created, and on
+shutdown.
+.IP
+This variable is ignored if the
+.RB $ PYTHONMALLOC
+environment variable is used to force the
+.BR malloc (3)
+allocator of the C library, or if Python is configured without pymalloc support.
+.IP PYTHONASYNCIODEBUG
+If this environment variable is set to a non-empty string, enable the debug
+mode of the asyncio module.
+.IP PYTHONTRACEMALLOC
+If this environment variable is set to a non-empty string, start tracing
+Python memory allocations using the tracemalloc module.
+.IP
+The value of the variable is the maximum number of frames stored in a
+traceback of a trace. For example,
+.IB PYTHONTRACEMALLOC=1
+stores only the most recent frame.
+.IP PYTHONFAULTHANDLER
+If this environment variable is set to a non-empty string,
+.IR faulthandler.enable()
+is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS
+and SIGILL signals to dump the Python traceback.
+.IP
+This is equivalent to the \fB-X faulthandler\fP option.
+.IP PYTHONEXECUTABLE
+If this environment variable is set,
+.IB sys.argv[0]
+will be set to its value instead of the value got through the C runtime. Only
+works on Mac OS X.
+.IP PYTHONUSERBASE
+Defines the user base directory, which is used to compute the path of the user
+.IR site-packages
+directory and installation paths for
+.IR "python \-m pip install \-\-user" .
+.IP PYTHONPROFILEIMPORTTIME
+If this environment variable is set to a non-empty string, Python will
+show how long each import takes. This is exactly equivalent to setting
+\fB\-X importtime\fP on the command line.
+.IP PYTHONBREAKPOINT
+If this environment variable is set to 0, it disables the default debugger. It
+can be set to the callable of your debugger of choice.
+.SS Debug-mode variables
+Setting these variables only has an effect in a debug build of Python, that is,
+if Python was configured with the
+\fB\--with-pydebug\fP build option.
+.IP PYTHONDUMPREFS
+If this environment variable is set, Python will dump objects and reference
+counts still alive after shutting down the interpreter.
+.SH AUTHOR
+The Python Software Foundation: https://www.python.org/psf/
+.SH INTERNET RESOURCES
+Main website:  https://www.python.org/
+.br
+Documentation:  https://docs.python.org/
+.br
+Developer resources:  https://devguide.python.org/
+.br
+Downloads:  https://www.python.org/downloads/
+.br
+Module repository:  https://pypi.org/
+.br
+Newsgroups:  comp.lang.python, comp.lang.python.announce
+.SH LICENSING
+Python is distributed under an Open Source license.  See the file
+"LICENSE" in the Python source distribution for information on terms &
+conditions for accessing and otherwise using Python and for a
+DISCLAIMER OF ALL WARRANTIES.
diff --git a/upstream/mageia-cauldron/man1/qoitopam.1 b/upstream/mageia-cauldron/man1/qoitopam.1
new file mode 100644
index 00000000..edb9744e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/qoitopam.1
@@ -0,0 +1,75 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Qoitopam User Manual" 0 "21 May 2022" "netpbm documentation"
+
+.SH NAME
+pamtoqoi - Convert  QOI format (Quite OK Image format) to Netpbm.
+
+
+.UN synopsis
+.SH SYNOPSIS
+\fBqoitopam\fP
+[\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBqoitopam\fP reads a QOI image from standard input and converts it to a
+Netpbm image written to standard output.
+.PP
+For the QOI specification and details, see
+.UR http://qoiformat.org
+the QOI web site
+.UE
+\&.
+.PP
+Use
+.BR "\fBpamtoqoi\fP" (1)\c
+\& to convert a Netpbm
+image to QOI format.
+.PP
+Input is from Standard Input if you don't specify the input file
+\fIpnmfile\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+The only options are those common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtoqoi" (1)\c
+\&,
+.BR "pam" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtoqoi\fP was new in Netpbm 10.99 (June 2022).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/qoitopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/qrttoppm.1 b/upstream/mageia-cauldron/man1/qrttoppm.1
new file mode 100644
index 00000000..e01d01a0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/qrttoppm.1
@@ -0,0 +1,54 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Qrttoppm User Manual" 0 "25 August 1989" "netpbm documentation"
+
+.SH NAME
+
+qrttoppm - convert output from the QRT ray tracer to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBqrttoppm\fP
+
+[\fIqrtfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBqrttoppm\fP reads a QRT file as input and produces a PPM
+image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBqrttoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/qrttoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ranlib.1 b/upstream/mageia-cauldron/man1/ranlib.1
new file mode 100644
index 00000000..7a711d6a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ranlib.1
@@ -0,0 +1,227 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "RANLIB 1"
+.TH RANLIB 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+ranlib \- generate an index to an archive
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+ranlib [\fB\-\-plugin\fR \fIname\fR] [\fB\-DhHvVt\fR] \fIarchive\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBranlib\fR generates an index to the contents of an archive and
+stores it in the archive.  The index lists each symbol defined by a
+member of an archive that is a relocatable object file.
+.PP
+You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index.
+.PP
+An archive with such an index speeds up linking to the library and
+allows routines in the library to call each other without regard to
+their placement in the archive.
+.PP
+The \s-1GNU\s0 \fBranlib\fR program is another form of \s-1GNU\s0 \fBar\fR; running
+\&\fBranlib\fR is completely equivalent to executing \fBar \-s\fR.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Show usage information for \fBranlib\fR.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Show the version number of \fBranlib\fR.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+Operate in \fIdeterministic\fR mode.  The symbol map archive member's
+header will show zero for the \s-1UID, GID,\s0 and timestamp.  When this
+option is used, multiple runs will produce identical output files.
+.Sp
+If \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by
+default.  It can be disabled with the \fB\-U\fR option, described
+below.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+Update the timestamp of the symbol map of an archive.
+.IP "\fB\-U\fR" 4
+.IX Item "-U"
+Do \fInot\fR operate in \fIdeterministic\fR mode.  This is the
+inverse of the \fB\-D\fR option, above: the archive index will get
+actual \s-1UID, GID,\s0 timestamp, and file mode values.
+.Sp
+If \fIbinutils\fR was configured \fIwithout\fR
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by
+default.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBar\fR\|(1), \fBnm\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/rasttopnm.1 b/upstream/mageia-cauldron/man1/rasttopnm.1
new file mode 100644
index 00000000..2f098768
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rasttopnm.1
@@ -0,0 +1,85 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rasttopnm User Manual" 0 "16 August 2011" "netpbm documentation"
+
+.SH NAME
+rasttopnm - convert a Sun rasterfile to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrasttopnm\fP
+
+[\fB-index\fP]
+
+[\fIrastfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrasttopnm\fP reads a Sun rasterfile as input and produces a PNM
+image as output.  The type of the output file depends on the input
+file - if it's black and white, \fBrasttopnm\fP writes a PBM image.
+If it's grayscale, \fBrasttopnm\fP writes a PGM.  If it's color,
+\fBrasttopnm\fP writes a PPM.  The program tells you which type it is
+generating.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBrasttopnm\fP recognizes the following
+command line option:
+
+
+  
+.TP
+\fB-index\fP
+This odd option tells \fBrasttopnm\fP to use the color map indices in
+the raster as if they are the color values.
+.sp
+In a colormapped Sun rasterfile, the header of the file contains a color
+map, associating each unique color that occurs in the file with an index
+number.  The raster portion of the file then represents the color of a pixel
+with one of those colormap indices.
+.sp
+This option has found use as follows: take a regular grayscale Sun
+rasterfile in which all the grayscale value are represented, so the colormap
+indices are identical to the color values.  Modify its color map so as to
+alter the colors in the image, in particular to equalize the colors.  With
+that modified rasterfile as input, \fBrasttopnm\fP without \fB-index\fP
+produces the modified image.  But with \fB-index\fP, it produces the original
+unmodified image.
+.sp
+This option was new in Netpbm 10.56 (September 2011).
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtorast" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rasttopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rawtopgm.1 b/upstream/mageia-cauldron/man1/rawtopgm.1
new file mode 100644
index 00000000..24b2ee06
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rawtopgm.1
@@ -0,0 +1,168 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rawtopgm User Manual" 0 "14 September 2000" "netpbm documentation"
+
+.SH NAME
+
+rawtopgm - convert raw grayscale bytes to a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrawtopgm\fP
+
+[\fB-bpp\fP [\fB1\fP|\fB2\fP]]
+
+[\fB-littleendian\fP]
+
+[\fB-maxval\fP \fIN\fP]
+
+[\fB-headerskip\fP \fIN\fP]
+
+[\fB-rowskip\fP \fIN\fP]
+
+[\fB-tb\fP|\fB-topbottom\fP]
+
+[\fIwidth\fP \fIheight\fP]
+
+[\fIimagefile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrawtopgm\fP reads raw grayscale values as input and produces a
+PGM image as output.  The input file is just a sequence of pure binary
+numbers, either one or two bytes each, either bigendian or
+littleendian, representing gray values.  They may be arranged either
+top to bottom, left to right or bottom to top, left to right.  There
+may be arbitrary header information at the start of the file (to which
+\fBrawtopgm\fP pays no attention at all other than the header's
+size).
+.PP
+Arguments to \fBrawtopgm\fP tell how to interpret the pixels (a
+function that is served by a header in a regular graphics format).
+.PP
+The \fIwidth\fP and \fIheight\fP parameters tell the dimensions
+of the image.  If you omit these parameters, \fBrawtopgm\fP assumes
+it is a quadratic image and bases the dimensions on the size of the
+input stream.  If this size is not a perfect square, \fBrawtopgm\fP
+fails.
+.PP
+When you don't specify \fIwidth\fP and \fIheight\fP,
+\fBrawtopgm\fP reads the entire input stream into storage at once,
+which may take a lot of storage.  Otherwise, \fBrawtopgm\fP
+ordinarily stores only one row at a time.
+.PP
+If you don't specify \fIimagefile\fP, or specify \fB-\fP, the
+input is from Standard Input.
+.PP
+The PGM output is to Standard Output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBrawtopgm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-maxval\fP \fIN\fP
+\fIN\fP is the maxval for the gray values in the input, and is
+also the maxval of the PGM output image.  The default is the maximum
+value that can be represented in the number of bytes used for each
+sample (i.e. 255 or 65535).
+
+.TP
+\fB-bpp\fP [\fB1\fP|\fB2\fP]
+tells the number of bytes that represent each sample in the input.
+If the value is \fB2\fP, The most significant byte is first in the
+stream.
+.sp
+The default is 1 byte per sample.
+
+.TP
+\fB-littleendian\fP
+says that the bytes of each input sample are ordered with the
+least significant byte first.  Without this option, \fBrawtopgm\fP
+assumes MSB first.  This obviously has no effect when there is only
+one byte per sample.
+
+.TP
+\fB-headerskip\fP \fIN\fP
+\fBrawtopgm\fP skips over \fIN\fP bytes at the beginning of the
+stream and reads the image immediately after.  The default is 0.
+.sp
+This is useful when the input is actually some graphics format that
+has a descriptive header followed by an ordinary raster, and you don't
+have a program that understands the header or you want to ignore the
+header.
+
+.TP
+\fB-rowskip\fP \fIN\fP
+If there is padding at the ends of the rows, you can skip it with
+this option.  Note that rowskip need not be an integer.  Amazingly, I
+once had an image with 0.376 bytes of padding per row.  This turned
+out to be due to a file-transfer problem, but I was still able to read
+the image.
+.sp
+Skipping a fractional byte per row means skipping one byte per
+multiple rows.
+
+.TP
+\fB-bt -bottomfirst\fP
+By default, \fBrawtopgm\fP assumes the pixels in the input go top
+to bottom, left to right.  If you specify \fB-bt\fP or
+\fB-bottomfirst\fP, \fBrawtopgm\fP assumes the pixels go bottom to
+top, left to right.  The Molecular Dynamics and Leica confocal format,
+for example, use the latter arrangement.
+.sp
+If you don't specify \fB-bt\fP when you should or vice versa, the
+resulting image is upside down, which you can correct with
+\fBpamflip\fP.
+.sp
+This option causes \fBrawtopgm\fP to read the entire input stream
+into storage at once, which may take a lot of storage.  Normally,
+\fBrawtopgm\fP stores only one row at a time.
+.sp
+For backwards compatibility, \fBrawtopgm\fP also accepts \fB-tb
+\fP and \fB-topbottom\fP to mean exactly the same thing.  The
+reasons these are named backwards is that the original author thought
+of it as specifying that the wrong results of assuming the data is top
+to bottom should be corrected by flipping the result top for bottom.
+Today, we think of it as simply specifying the format of the input
+data so that there are no wrong results.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgm" (1)\c
+\&,
+.BR "rawtoppm" (1)\c
+\&,
+.BR "pamflip" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1989 by Jef Poskanzer.
+Modified June 1993 by Oliver Trepte, \fIoliver@fysik4.kth.se\fP
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rawtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rawtoppm.1 b/upstream/mageia-cauldron/man1/rawtoppm.1
new file mode 100644
index 00000000..3b0c1cb3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rawtoppm.1
@@ -0,0 +1,111 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rawtoppm User Manual" 0 "06 February 1991" "netpbm documentation"
+
+.SH NAME
+
+rawtoppm - convert a stream of raw RGB bytes to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrawtoppm\fP
+
+[\fB-headerskip\fP \fIN\fP]
+
+[\fB-rowskip\fP \fIN\fP]
+
+[
+\fB-rgb\fP|\fB-rbg\fP|\fB-grb\fP
+|\fB-gbr\fP|\fB-brg\fP|\fB-bgr\fP
+]
+
+[\fB-interpixel\fP|\fB-interrow\fP] \fIwidth\fP \fIheight\fP
+
+[\fIimagedata\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrawtoppm\fP reads raw RGB bytes as input and produces a PPM
+image as output.  The input file is just RGB bytes.  You have to
+specify the width and height on the command line, since the program
+obviously can't get them from the file.  \fBrawtoppm\fP assumes the
+maxval of the input samples is 255, and makes the maxval of the output
+PPM 255.  
+.PP
+\fBrawtoppm\fP assumes the pixels come top first in the input stream.
+If they are actually bottom first, the resulting PPM is upside down, so
+run it through \fBpamflip -tb\fP.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBrawtoppm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-headerskip\fP
+Skip over this many bytes at the beginning of the input stream.
+Use this option when the input has some kind of header followed by
+a raster suitable for \fBrawtoppm\fP.
+
+.TP
+\fB-rowskip\fP
+Skip this many bytes at the end of each row of the raster.  (Some
+input streams have padding at the end of rows).
+
+.TP
+\fB-rgb -rbg -grb -gbr -brg -bgr\fP
+This option specifies the order of the color components for each
+pixel.  The default is \fB-rgb\fP.
+
+.TP
+\fB-interpixel -interrow\fP
+These options specify how the colors are interleaved.  The default
+is \fB-interpixel\fP, meaning interleaved by pixel.  A byte of red, a
+byte of green, and a byte of blue, or whatever color order you
+specified.  \fB-interrow\fP means interleaved by row - a row of red,
+a row of green, a row of blue, assuming standard rgb color order.  An
+\fB-interplane\fP option - all the red pixels, then all the green,
+then all the blue - would be an obvious extension, but is not
+implemented.  You could get the same effect by splitting the file into
+three parts (perhaps using \fBdd\fP), turning each part into a PGM
+file with \fBrawtopgm\fP, and then combining them with \fBrgb3toppm\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppm" (1)\c
+\&, 
+.BR "rawtopgm" (1)\c
+\&, 
+.BR "rgb3toppm" (1)\c
+\&, 
+.BR "pamflip" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rawtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rbash.1 b/upstream/mageia-cauldron/man1/rbash.1
new file mode 100644
index 00000000..3532cdab
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rbash.1
@@ -0,0 +1,115 @@
+.lf 1 ./rbash.1
+.TH RBASH 1 "2021 November 22" "Bash-5.2"
+.SH NAME
+rbash \- restricted bash, see \fBbash\fR(1)
+.SH RESTRICTED SHELL
+.nr zY 1
+.lf 1 ./bash.1
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\"	Chet Ramey
+.\"	Case Western Reserve University
+.\"	chet.ramey@case.edu
+.\"
+.\"	Last Change: Mon Sep 19 11:13:21 EDT 2022
+.\"
+.\" bash_builtins, strip all but Built-Ins section
+.if \n(zZ=1 .ig zZ
+.PP
+If
+.B bash
+is started with the name
+.BR rbash ,
+or the
+.B \-r
+option is supplied at invocation,
+the shell becomes restricted.
+A restricted shell is used to
+set up an environment more controlled than the standard shell.
+It behaves identically to
+.B bash
+with the exception that the following are disallowed or not performed:
+.IP \(bu
+changing directories with \fBcd\fP
+.IP \(bu
+setting or unsetting the values of
+.SM
+.BR SHELL ,
+.SM
+.BR PATH ,
+.SM
+.BR HISTFILE ,
+.SM
+.BR ENV ,
+or
+.SM
+.B BASH_ENV
+.IP \(bu
+specifying command names containing
+.B /
+.IP \(bu
+specifying a filename containing a
+.B /
+as an argument to the
+.B .
+builtin command
+.IP \(bu
+specifying a filename containing a slash as an argument to the
+.B history
+builtin command
+.IP \(bu
+specifying a filename containing a slash as an argument to the
+.B \-p
+option to the
+.B hash
+builtin command
+.IP \(bu
+importing function definitions from the shell environment at startup
+.IP \(bu
+parsing the value of
+.SM
+.B SHELLOPTS
+from the shell environment at startup
+.IP \(bu
+redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
+.IP \(bu
+using the
+.B exec
+builtin command to replace the shell with another command
+.IP \(bu
+adding or deleting builtin commands with the
+.B \-f
+and
+.B \-d
+options to the
+.B enable
+builtin command
+.IP \(bu
+using the \fBenable\fP builtin command to enable disabled shell builtins
+.IP \(bu
+specifying the
+.B \-p
+option to the
+.B command
+builtin command
+.IP \(bu
+turning off restricted mode with
+\fBset +r\fP or \fBshopt -u restricted_shell\fP.
+.PP
+These restrictions are enforced after any startup files are read.
+.PP
+.ie \n(zY=1 When a command that is found to be a shell script is executed,
+.el \{ When a command that is found to be a shell script is executed
+(see
+.SM
+.B "COMMAND EXECUTION"
+above),
+\}
+.B rbash
+turns off any restrictions in the shell spawned to execute the
+script.
+.\" end of rbash.1
+.lf 7 ./rbash.1
+.SH SEE ALSO
+bash(1)
diff --git a/upstream/mageia-cauldron/man1/rcs.1 b/upstream/mageia-cauldron/man1/rcs.1
new file mode 100644
index 00000000..ca4e4754
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rcs.1
@@ -0,0 +1,521 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.if !\n(.g \{\
+.	if !\w|\*(lq| \{\
+.		ds lq ``
+.		if \w'\(lq' .ds lq "\(lq
+.	\}
+.	if !\w|\*(rq| \{\
+.		ds rq ''
+.		if \w'\(rq' .ds rq "\(rq
+.	\}
+.\}
+.TH RCS 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+rcs \- change \*o attributes
+.SH SYNOPSIS
+.B rcs
+.IR "options file " .\|.\|.
+.SH DESCRIPTION
+.B rcs
+creates new \*os or changes attributes of existing ones.
+An \*o contains multiple revisions of text,
+an access list, a change log,
+descriptive text,
+and some control attributes.
+For
+.B rcs
+to work, the caller's login name must be on the access list,
+except if the access list is empty, the caller is the owner of the file
+or the superuser, or
+the
+.B \-i
+option is present.
+.PP
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+Names are paired as explained in
+.BR ci (1).
+Revision numbers use the syntax described in
+.BR ci (1).
+.SH OPTIONS
+.TP
+.B \-i
+Create and initialize a new \*o, but do not deposit any revision.
+If the \*o name has no directory component, try to place it
+first into the subdirectory
+.BR ./RCS ,
+and then into the current directory.
+If the \*o
+already exists, print an error message.
+.TP
+.BI \-a "logins"
+Append the login names appearing in the comma-separated list
+.I logins
+to the access list of the \*o.
+.TP
+.BI \-A "oldfile"
+Append the access list of
+.I oldfile
+to the access list of the \*o.
+.TP
+.BR \-e [\f2logins\fP]
+Erase the login names appearing in the comma-separated list
+.I logins
+from the access list of the \*o.
+If
+.I logins
+is omitted, erase the entire access list.
+.TP
+.BR \-b [\f2rev\fP]
+Set the default branch to
+.IR rev .
+If
+.I rev
+is omitted, the default
+branch is reset to the (dynamically) highest branch on the trunk.
+.TP
+.BI \-c string
+Set the comment leader to
+.IR string .
+An initial
+.BR ci ,
+or an
+.B "rcs\ \-i"
+without
+.BR \-c ,
+guesses the comment leader from the suffix of the working file name.
+.RS
+.PP
+This option is obsolescent, since \*r normally uses the preceding
+.B $\&Log$
+line's prefix when inserting log lines during checkout (see
+.BR co (1)).
+However, older versions of \*r use the comment leader instead of the
+.B $\&Log$
+line's prefix, so
+if you plan to access a file with both old and new versions of \*r,
+make sure its comment leader matches its
+.B $\&Log$
+line prefix.
+.RE
+.TP
+.BI \-k subst
+Set the default keyword substitution to
+.IR subst .
+The effect of keyword substitution is described in
+.BR co (1).
+Giving an explicit
+.B \-k
+option to
+.BR co ,
+.BR rcsdiff ,
+and
+.B rcsmerge
+overrides this default.
+Beware
+.BR "rcs\ \-kv",
+because
+.B \-kv
+is incompatible with
+.BR "co\ \-l".
+Use
+.B "rcs\ \-kkv"
+to restore the normal default keyword substitution.
+.TP
+.BR \-l [\f2rev\fP]
+Lock the revision with number
+.IR rev .
+If a branch is given, lock the latest revision on that branch.
+If
+.I rev
+is omitted, lock the latest revision on the default branch.
+Locking prevents overlapping changes.
+If someone else already holds the lock, the lock is broken as with
+.B "rcs\ \-u"
+(see below).
+.TP
+.BR \-u [\f2rev\fP]
+Unlock the revision with number
+.IR rev .
+If a branch is given, unlock the latest revision on that branch.
+If
+.I rev
+is omitted, remove the latest lock held by the caller.
+Normally, only the locker of a revision can unlock it.
+Somebody else unlocking a revision breaks the lock.
+If RCS was configured
+.BR "\-\-with-mailer" ,
+then this causes a mail message to be sent to the original locker.
+The message contains a commentary solicited from the breaker.
+The commentary is terminated by end-of-file or by a line containing
+.BR \&. "\ by"
+itself.
+.TP
+.B \-L
+Set locking to
+.IR strict .
+Strict locking means that the owner
+of an \*o is not exempt from locking for checkin.
+This option should be used for files that are shared.
+.TP
+.B \-U
+Set locking to non-strict.  Non-strict locking means that the owner of
+a file need not lock a revision for checkin.
+This option should
+.I not
+be used for files that are shared.
+Whether default locking is strict is determined by your system administrator,
+but it is normally strict.
+.TP
+\f3\-m\fP\f2rev\fP\f3:\fP[\f2msg\fP]
+Replace revision
+.IR rev 's
+log message with
+.IR msg .
+If
+.I msg
+is omitted, it defaults to "*** empty log message ***".
+.TP
+.B \-M
+Do not send mail when breaking somebody else's lock.
+This option is not meant for casual use;
+it is meant for programs that warn users by other means, and invoke
+.B "rcs\ \-u"
+only as a low-level lock-breaking operation.
+.TP
+\f3\-n\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
+Associate the symbolic name
+.I name
+with the branch or
+revision
+.IR rev .
+Delete the symbolic name if both
+.B :
+and
+.I rev
+are omitted; otherwise, print an error message if
+.I name
+is already associated with
+another number.
+If
+.I rev
+is symbolic, it is expanded before association.
+A
+.I rev
+consisting of a branch number followed by a
+.B .\&
+stands for the current latest revision in the branch.
+A
+.B :
+with an empty
+.I rev
+stands for the current latest revision on the default branch,
+normally the trunk.
+For example,
+.BI "rcs\ \-n" name ":\ RCS/*"
+associates
+.I name
+with the current latest revision of all the named \*os;
+this contrasts with
+.BI "rcs\ \-n" name ":$\ RCS/*"
+which associates
+.I name
+with the revision numbers extracted from keyword strings
+in the corresponding working files.
+.TP
+\f3\-N\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
+Act like
+.BR \-n ,
+except override any previous assignment of
+.IR name .
+.TP
+.BI \-o range
+deletes (\*(lqoutdates\*(rq) the revisions given by
+.IR range .
+A range consisting of a single revision number means that revision.
+A range consisting of a branch number means the latest revision on that
+branch.
+A range of the form
+.IB rev1 : rev2
+means
+revisions
+.I rev1
+to
+.I rev2
+on the same branch,
+.BI : rev
+means from the beginning of the branch containing
+.I rev
+up to and including
+.IR rev ,
+and
+.IB rev :
+means
+from revision
+.I rev
+to the end of the branch containing
+.IR rev .
+None of the outdated revisions can have branches or locks.
+.TP
+.B \-q
+Run quietly; do not print diagnostics.
+.TP
+.B \-I
+Run interactively, even if the standard input is not a terminal.
+.TP
+.B \-s\f2state\fP\f1[\fP:\f2rev\fP\f1]\fP
+Set the state attribute of the revision
+.I rev
+to
+.IR state .
+If
+.I rev
+is a branch number, assume the latest revision on that branch.
+If
+.I rev
+is omitted, assume the latest revision on the default branch.
+Any identifier is acceptable for
+.IR state .
+A useful set of states
+is
+.B Exp
+(for experimental),
+.B Stab
+(for stable), and
+.B Rel
+(for
+released).
+By default,
+.BR ci (1)
+sets the state of a revision to
+.BR Exp .
+.TP
+.BR \-t [\f2file\fP]
+Write descriptive text from the contents of the named
+.I file
+into the \*o, deleting the existing text.
+The
+.IR file
+name cannot begin with
+.BR \- .
+If
+.I file
+is omitted, obtain the text from standard input,
+terminated by end-of-file or by a line containing
+.BR \&. "\ by"
+itself.
+Prompt for the text if interaction is possible; see
+.BR \-I .
+With
+.BR \-i ,
+descriptive text is obtained
+even if
+.B \-t
+is not given.
+.TP
+.BI \-t\- string
+Write descriptive text from the
+.I string
+into the \*o, deleting the existing text.
+.TP
+.B \-T
+Preserve the modification time on the \*o
+unless a revision is removed.
+This option can suppress extensive recompilation caused by a
+.BR make (1)
+dependency of some copy of the working file on the \*o.
+Use this option with care; it can suppress recompilation even when it is needed,
+i.e. when a change to the \*o
+would mean a change to keyword strings in the working file.
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.IR n .
+See
+.BR co (1)
+for details.
+.TP
+.BI \-x "suffixes"
+Use
+.I suffixes
+to characterize \*os.
+See
+.BR ci (1)
+for details.
+.TP
+.BI \-z zone
+Use
+.I zone
+as the default time zone.
+This option has no effect;
+it is present for compatibility with other \*r commands.
+.PP
+At least one explicit option must be given,
+to ensure compatibility with future planned extensions
+to the
+.B rcs
+command.
+.SH COMPATIBILITY
+The
+.BI \-b rev
+option generates an \*o that cannot be parsed by \*r version 3 or earlier.
+.PP
+The
+.BI \-k subst
+options (except
+.BR \-kkv )
+generate an \*o that cannot be parsed by \*r version 4 or earlier.
+.PP
+Use
+.BI "rcs \-V" n
+to make an \*o acceptable to \*r version
+.I n
+by discarding information that would confuse version
+.IR n .
+.PP
+\*r version 5.5 and earlier does not support the
+.B \-x
+option, and requires a
+.B ,v
+suffix on an \*o name.
+.SH FILES
+.B rcs
+accesses files much as
+.BR ci (1)
+does,
+except that it uses the effective user for all accesses,
+it does not write the working file or its directory,
+and it does not even read the working file unless a revision number of
+.B $
+is specified.
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+The \*o name and the revisions outdated are written to
+the diagnostic output.
+The exit status is zero if and only if all operations were successful.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR co (1),
+.BR ci (1),
+.BR ident (1),
+.BR rcsclean (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rlog (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
+.SH BUGS
+A catastrophe (e.g. a system crash) can cause \*r to leave behind
+a semaphore file that causes later invocations of \*r to claim
+that the \*o is in use.
+To fix this, remove the semaphore file.
+A semaphore file's name typically begins with
+.B ,
+or ends with
+.BR _ .
+.PP
+The separator for revision ranges in the
+.B \-o
+option used to be
+.B \-
+instead of
+.BR : ,
+but this leads to confusion when symbolic names contain
+.BR \- .
+For backwards compatibility
+.B "rcs \-o"
+still supports the old
+.B \-
+separator, but it warns about this obsolete use.
+.PP
+Symbolic names need not refer to existing revisions or branches.
+For example, the
+.B \-o
+option does not remove symbolic names for the outdated revisions; you must use
+.B \-n
+to remove the names.
+.br
diff --git a/upstream/mageia-cauldron/man1/rcsclean.1 b/upstream/mageia-cauldron/man1/rcsclean.1
new file mode 100644
index 00000000..c0aca1fa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rcsclean.1
@@ -0,0 +1,256 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH RCSCLEAN 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+rcsclean \- clean up working files
+.SH SYNOPSIS
+.B rcsclean
+.RI [ options "] [ " file " .\|.\|. ]"
+.SH DESCRIPTION
+.B rcsclean
+removes files that are not being worked on.
+.B "rcsclean \-u"
+also unlocks and removes files that are being worked on
+but have not changed.
+.PP
+For each
+.I file
+given,
+.B rcsclean
+compares the working file and a revision in the corresponding
+\*o.  If it finds a difference, it does nothing.
+Otherwise, it first unlocks the revision if the
+.B \-u
+option is given,
+and then removes the working file
+unless the working file is writable and the revision is locked.
+It logs its actions by outputting the corresponding
+.B "rcs \-u"
+and
+.B "rm \-f"
+commands on the standard output.
+.PP
+Files are paired as explained in
+.BR ci (1).
+If no
+.I file
+is given, all working files in the current directory are cleaned.
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+.PP
+The number of the revision to which the working file is compared
+may be attached to any of the options
+.BR \-n ,
+.BR \-q ,
+.BR \-r ,
+or
+.BR \-u .
+If no revision number is specified, then if the
+.B \-u
+option is given and the caller has one revision locked,
+.B rcsclean
+uses that revision; otherwise
+.B rcsclean
+uses the latest revision on the default branch, normally the root.
+.PP
+.B rcsclean
+is useful for
+.B clean
+targets in makefiles.
+See also
+.BR rcsdiff (1),
+which prints out the differences,
+and
+.BR ci (1),
+which
+normally reverts to the previous revision
+if a file was not changed.
+.SH OPTIONS
+.TP
+.BI \-k subst
+Use
+.I subst
+style keyword substitution when retrieving the revision for comparison.
+See
+.BR co (1)
+for details.
+.TP
+.BR \-n [\f2rev\fP]
+Do not actually remove any files or unlock any revisions.
+Using this option will tell you what
+.B rcsclean
+would do without actually doing it.
+.TP
+.BR \-q [\f2rev\fP]
+Do not log the actions taken on standard output.
+.TP
+.BR \-r [\f2rev\fP]
+This option has no effect other than specifying the revision for comparison.
+.TP
+.B \-T
+Preserve the modification time on the \*o
+even if the \*o changes because a lock is removed.
+This option can suppress extensive recompilation caused by a
+.BR make (1)
+dependency of some other copy of the working file on the \*o.
+Use this option with care; it can suppress recompilation even when it is needed,
+i.e. when the lock removal
+would mean a change to keyword strings in the other working file.
+.TP
+.BR \-u [\f2rev\fP]
+Unlock the revision if it is locked and no difference is found.
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.IR n .
+See
+.BR co (1)
+for details.
+.TP
+.BI \-x "suffixes"
+Use
+.I suffixes
+to characterize \*os.
+See
+.BR ci (1)
+for details.
+.TP
+.BI \-z zone
+Use
+.I zone
+as the time zone for keyword substitution;
+see
+.BR co (1)
+for details.
+.SH EXAMPLES
+.LP
+.RS
+.ft 3
+rcsclean  *.c  *.h
+.ft
+.RE
+.LP
+removes all working files ending in
+.B .c
+or
+.B .h
+that were not changed
+since their checkout.
+.LP
+.RS
+.ft 3
+rcsclean
+.ft
+.RE
+.LP
+removes all working files in the current directory
+that were not changed since their checkout.
+.SH FILES
+.B rcsclean
+accesses files much as
+.BR ci (1)
+does.
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+The exit status is zero if and only if all operations were successful.
+Missing working files and \*os are silently ignored.
+.ds EY 1990, 1991, 1992, 1993
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR co (1),
+.BR ident (1),
+.BR rcs (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rlog (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
+.SH BUGS
+At least one
+.I file
+must be given in older Unix versions that
+do not provide the needed directory scanning operations.
+.br
diff --git a/upstream/mageia-cauldron/man1/rcsdiff.1 b/upstream/mageia-cauldron/man1/rcsdiff.1
new file mode 100644
index 00000000..27668076
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rcsdiff.1
@@ -0,0 +1,219 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH RCSDIFF 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+rcsdiff \- compare RCS revisions
+.SH SYNOPSIS
+.B rcsdiff
+[
+.BI \-k subst
+] [
+.B \-q
+] [
+.BI \-r rev1
+[
+.BI \-r rev2
+] ] [
+.B \-T
+] [
+.RI "\f3\-V\fP[" n ]
+] [
+.BI \-x suffixes
+] [
+.BI \-z zone
+] [
+.I "diff options"
+]
+.I "file .\|.\|."
+.SH DESCRIPTION
+.B rcsdiff
+runs
+.BR diff (1)
+to compare two revisions of each \*o given.
+.PP
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+Names are paired as explained in
+.BR ci (1).
+.PP
+The option
+.B \-q
+suppresses diagnostic output.
+Zero, one, or two revisions may be specified with
+.BR \-r .
+The option
+.BI \-k subst
+affects keyword substitution when extracting
+revisions, as described in
+.BR co (1);
+for example,
+.B "\-kk\ \-r1.1\ \-r1.2"
+ignores differences in keyword values when comparing revisions
+.B 1.1
+and
+.BR 1.2 .
+To avoid excess output from locker name substitution,
+.B \-kkvl
+is assumed if (1) at most one revision option is given,
+(2) no
+.B \-k
+option is given, (3)
+.B \-kkv
+is the default keyword substitution, and
+(4) the working file's mode would be produced by
+.BR "co\ \-l".
+See
+.BR co (1)
+for details
+about
+.BR \-T ,
+.BR \-V ,
+.B \-x
+and
+.BR \-z .
+Otherwise, all options of
+.BR diff (1)
+that apply to regular files are accepted, with the same meaning as for
+.BR diff .
+.PP
+If both
+.I rev1
+and
+.I rev2
+are omitted,
+.B rcsdiff
+compares the latest revision on the
+default branch (by default the trunk)
+with the contents of the corresponding working file.  This is useful
+for determining what you changed since the last checkin.
+.PP
+If
+.I rev1
+is given, but
+.I rev2
+is omitted,
+.B rcsdiff
+compares revision
+.I rev1
+of the \*o with
+the contents of the corresponding working file.
+.PP
+If both
+.I rev1
+and
+.I rev2
+are given,
+.B rcsdiff
+compares revisions
+.I rev1
+and
+.I rev2
+of the \*o.
+.PP
+Both
+.I rev1
+and
+.I rev2
+may be given numerically or symbolically.
+.SH EXAMPLE
+The command
+.LP
+.B "        rcsdiff  f.c"
+.LP
+compares the latest revision on the default branch of the \*o
+to the contents of the working file
+.BR f.c .
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+Exit status is 0 for no differences during any comparison,
+1 for some differences, 2 for trouble.
+.ds EY 1990, 1991, 1992, 1993
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR co (1),
+.BR diff (1),
+.BR ident (1),
+.BR rcs (1),
+.BR rcsmerge (1),
+.BR rlog (1).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
diff --git a/upstream/mageia-cauldron/man1/rcsmerge.1 b/upstream/mageia-cauldron/man1/rcsmerge.1
new file mode 100644
index 00000000..f62e3ecb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rcsmerge.1
@@ -0,0 +1,250 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH RCSMERGE 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+rcsmerge \- merge RCS revisions
+.SH SYNOPSIS
+.B rcsmerge
+.RI [ options ] " file"
+.SH DESCRIPTION
+.B rcsmerge
+incorporates the changes between two revisions
+of an \*o into the corresponding working file.
+.PP
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+Names are paired as explained in
+.BR ci (1).
+.PP
+At least one revision must be specified with one of the options
+described below, usually
+.BR \-r .
+At most two revisions may be specified.
+If only one revision is specified, the latest
+revision on the default branch (normally the highest branch on the trunk)
+is assumed for the second revision.
+Revisions may be specified numerically or symbolically.
+.PP
+.B rcsmerge
+prints a warning if there are overlaps, and delimits
+the overlapping regions as explained in
+.BR merge (1).
+The command is useful for incorporating changes into a checked-out revision.
+.SH OPTIONS
+.TP
+.B \-A
+Output conflicts using the
+.B \-A
+style of
+.BR diff3 (1),
+if supported by
+.BR diff3 .
+This merges all changes leading from
+.I file2
+to
+.I file3
+into
+.IR file1 ,
+and generates the most verbose output.
+.TP
+\f3\-E\fP, \f3\-e\fP
+These options specify conflict styles that generate less information
+than
+.BR \-A .
+See
+.BR diff3 (1)
+for details.
+The default is
+.BR \-E .
+With
+.BR \-e ,
+.B rcsmerge
+does not warn about conflicts.
+.TP
+.BI \-k subst
+Use
+.I subst
+style keyword substitution.
+See
+.BR co (1)
+for details.
+For example,
+.B "\-kk\ \-r1.1\ \-r1.2"
+ignores differences in keyword values when merging the changes from
+.B 1.1
+to
+.BR 1.2 .
+It normally does not make sense to merge binary files as if they were text, so
+.B rcsmerge
+refuses to merge files if
+.B \-kb
+expansion is used.
+.TP
+.BR \-p [\f2rev\fP]
+Send the result to standard output instead of overwriting the working file.
+.TP
+.BR \-q [\f2rev\fP]
+Run quietly; do not print diagnostics.
+.TP
+.BR \-r [\f2rev\fP]
+Merge with respect to revision
+.IR rev .
+Here an empty
+.I rev
+stands for the latest revision on the default branch, normally the head.
+.TP
+.B \-T
+This option has no effect;
+it is present for compatibility with other \*r commands.
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.IR n .
+See
+.BR co (1)
+for details.
+.TP
+.BI \-x "suffixes"
+Use
+.I suffixes
+to characterize \*os.
+See
+.BR ci (1)
+for details.
+.TP
+.BI \-z zone
+Use
+.I zone
+as the time zone for keyword substitution.
+See
+.BR co (1)
+for details.
+.SH EXAMPLES
+Suppose you have released revision 2.8 of
+.BR f.c .
+Assume
+furthermore that after you complete an unreleased revision 3.4, you receive
+updates to release 2.8 from someone else.
+To combine the updates to 2.8 and your changes between 2.8 and 3.4,
+put the updates to 2.8 into file f.c and execute
+.LP
+.B "    rcsmerge  \-p  \-r2.8  \-r3.4  f.c  >f.merged.c"
+.PP
+Then examine
+.BR f.merged.c .
+Alternatively, if you want to save the updates to 2.8 in the \*o,
+check them in as revision 2.8.1.1 and execute
+.BR "co \-j":
+.LP
+.B "    ci  \-r2.8.1.1  f.c"
+.br
+.B "    co  \-r3.4  \-j2.8:2.8.1.1  f.c"
+.PP
+As another example, the following command undoes the changes
+between revision 2.4 and 2.8 in your currently checked out revision
+in
+.BR f.c .
+.LP
+.B "    rcsmerge  \-r2.8  \-r2.4  f.c"
+.PP
+Note the order of the arguments, and that
+.B f.c
+will be
+overwritten.
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+Exit status is 0 for no overlaps, 1 for some overlaps, 2 for trouble.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR co (1),
+.BR ident (1),
+.BR merge (1),
+.BR rcs (1),
+.BR rcsdiff (1),
+.BR rlog (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
diff --git a/upstream/mageia-cauldron/man1/readelf.1 b/upstream/mageia-cauldron/man1/readelf.1
new file mode 100644
index 00000000..3a2b694c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/readelf.1
@@ -0,0 +1,906 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "READELF 1"
+.TH READELF 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+readelf \- display information about ELF files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+readelf [\fB\-a\fR|\fB\-\-all\fR]
+        [\fB\-h\fR|\fB\-\-file\-header\fR]
+        [\fB\-l\fR|\fB\-\-program\-headers\fR|\fB\-\-segments\fR]
+        [\fB\-S\fR|\fB\-\-section\-headers\fR|\fB\-\-sections\fR]
+        [\fB\-g\fR|\fB\-\-section\-groups\fR]
+        [\fB\-t\fR|\fB\-\-section\-details\fR]
+        [\fB\-e\fR|\fB\-\-headers\fR]
+        [\fB\-s\fR|\fB\-\-syms\fR|\fB\-\-symbols\fR]
+        [\fB\-\-dyn\-syms\fR|\fB\-\-lto\-syms\fR]
+        [\fB\-\-sym\-base=[0|8|10|16]\fR]
+        [\fB\-\-demangle\fR\fI=style\fR|\fB\-\-no\-demangle\fR]
+        [\fB\-\-quiet\fR]
+        [\fB\-\-recurse\-limit\fR|\fB\-\-no\-recurse\-limit\fR]
+        [\fB\-U\fR \fImethod\fR|\fB\-\-unicode=\fR\fImethod\fR]
+        [\fB\-n\fR|\fB\-\-notes\fR]
+        [\fB\-r\fR|\fB\-\-relocs\fR]
+        [\fB\-u\fR|\fB\-\-unwind\fR]
+        [\fB\-d\fR|\fB\-\-dynamic\fR]
+        [\fB\-V\fR|\fB\-\-version\-info\fR]
+        [\fB\-A\fR|\fB\-\-arch\-specific\fR]
+        [\fB\-D\fR|\fB\-\-use\-dynamic\fR]
+        [\fB\-L\fR|\fB\-\-lint\fR|\fB\-\-enable\-checks\fR]
+        [\fB\-x\fR <number or name>|\fB\-\-hex\-dump=\fR<number or name>]
+        [\fB\-p\fR <number or name>|\fB\-\-string\-dump=\fR<number or name>]
+        [\fB\-R\fR <number or name>|\fB\-\-relocated\-dump=\fR<number or name>]
+        [\fB\-z\fR|\fB\-\-decompress\fR]
+        [\fB\-c\fR|\fB\-\-archive\-index\fR]
+        [\fB\-w[lLiaprmfFsoORtUuTgAck]\fR|
+         \fB\-\-debug\-dump\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
+        [\fB\-wK\fR|\fB\-\-debug\-dump=follow\-links\fR]
+        [\fB\-wN\fR|\fB\-\-debug\-dump=no\-follow\-links\fR]
+        [\fB\-wD\fR|\fB\-\-debug\-dump=use\-debuginfod\fR]
+        [\fB\-wE\fR|\fB\-\-debug\-dump=do\-not\-use\-debuginfod\fR]
+        [\fB\-P\fR|\fB\-\-process\-links\fR]
+        [\fB\-\-dwarf\-depth=\fR\fIn\fR]
+        [\fB\-\-dwarf\-start=\fR\fIn\fR]
+        [\fB\-\-ctf=\fR\fIsection\fR]
+        [\fB\-\-ctf\-parent=\fR\fIsection\fR]
+        [\fB\-\-ctf\-symbols=\fR\fIsection\fR]
+        [\fB\-\-ctf\-strings=\fR\fIsection\fR]
+        [\fB\-\-sframe=\fR\fIsection\fR]
+        [\fB\-I\fR|\fB\-\-histogram\fR]
+        [\fB\-v\fR|\fB\-\-version\fR]
+        [\fB\-W\fR|\fB\-\-wide\fR]
+        [\fB\-T\fR|\fB\-\-silent\-truncation\fR]
+        [\fB\-H\fR|\fB\-\-help\fR]
+        \fIelffile\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBreadelf\fR displays information about one or more \s-1ELF\s0 format object
+files.  The options control what particular information to display.
+.PP
+\&\fIelffile\fR... are the object files to be examined.  32\-bit and
+64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files.
+.PP
+This program performs a similar function to \fBobjdump\fR but it
+goes into more detail and it exists independently of the \s-1BFD\s0
+library, so if there is a bug in \s-1BFD\s0 then readelf will not be
+affected.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The long and short forms of options, shown here as alternatives, are
+equivalent.  At least one option besides \fB\-v\fR or \fB\-H\fR must be
+given.
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+.PD
+Equivalent to specifying \fB\-\-file\-header\fR,
+\&\fB\-\-program\-headers\fR, \fB\-\-sections\fR, \fB\-\-symbols\fR,
+\&\fB\-\-relocs\fR, \fB\-\-dynamic\fR, \fB\-\-notes\fR,
+\&\fB\-\-version\-info\fR, \fB\-\-arch\-specific\fR, \fB\-\-unwind\fR,
+\&\fB\-\-section\-groups\fR and \fB\-\-histogram\fR.
+.Sp
+Note \- this option does not enable \fB\-\-use\-dynamic\fR itself, so
+if that option is not present on the command line then dynamic symbols
+and dynamic relocs will not be displayed.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-\-file\-header\fR" 4
+.IX Item "--file-header"
+.PD
+Displays the information contained in the \s-1ELF\s0 header at the start of the
+file.
+.IP "\fB\-l\fR" 4
+.IX Item "-l"
+.PD 0
+.IP "\fB\-\-program\-headers\fR" 4
+.IX Item "--program-headers"
+.IP "\fB\-\-segments\fR" 4
+.IX Item "--segments"
+.PD
+Displays the information contained in the file's segment headers, if it
+has any.
+.IP "\fB\-\-quiet\fR" 4
+.IX Item "--quiet"
+Suppress \*(L"no symbols\*(R" diagnostic.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-sections\fR" 4
+.IX Item "--sections"
+.IP "\fB\-\-section\-headers\fR" 4
+.IX Item "--section-headers"
+.PD
+Displays the information contained in the file's section headers, if it
+has any.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-\-section\-groups\fR" 4
+.IX Item "--section-groups"
+.PD
+Displays the information contained in the file's section groups, if it
+has any.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.IP "\fB\-\-section\-details\fR" 4
+.IX Item "--section-details"
+.PD
+Displays the detailed section information. Implies \fB\-S\fR.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-symbols\fR" 4
+.IX Item "--symbols"
+.IP "\fB\-\-syms\fR" 4
+.IX Item "--syms"
+.PD
+Displays the entries in symbol table section of the file, if it has one.
+If a symbol has version information associated with it then this is
+displayed as well.  The version string is displayed as a suffix to the
+symbol name, preceded by an @ character.  For example
+\&\fBfoo@VER_1\fR.  If the version is the default version to be used
+when resolving unversioned references to the symbol then it is
+displayed as a suffix preceded by two @ characters.  For example
+\&\fBfoo@@VER_2\fR.
+.IP "\fB\-\-dyn\-syms\fR" 4
+.IX Item "--dyn-syms"
+Displays the entries in dynamic symbol table section of the file, if it
+has one.  The output format is the same as the format used by the
+\&\fB\-\-syms\fR option.
+.IP "\fB\-\-lto\-syms\fR" 4
+.IX Item "--lto-syms"
+Displays the contents of any \s-1LTO\s0 symbol tables in the file.
+.IP "\fB\-\-sym\-base=[0|8|10|16]\fR" 4
+.IX Item "--sym-base=[0|8|10|16]"
+Forces the size field of the symbol table to use the given base.  Any
+unrecognized options will be treated as \fB0\fR.  \fB\-\-sym\-base=0\fR
+represents the default and legacy behaviour.  This will output sizes as decimal
+for numbers less than 100000.  For sizes 100000 and greater hexadecimal notation
+will be used with a 0x prefix.
+\&\fB\-\-sym\-base=8\fR will give the symbol sizes in octal.
+\&\fB\-\-sym\-base=10\fR will always give the symbol sizes in decimal.
+\&\fB\-\-sym\-base=16\fR will always give the symbol sizes in hexadecimal with a
+0x prefix.
+.IP "\fB\-C\fR" 4
+.IX Item "-C"
+.PD 0
+.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
+.IX Item "--demangle[=style]"
+.PD
+Decode (\fIdemangle\fR) low-level symbol names into user-level names.
+This makes \*(C+ function names readable.  Different compilers have
+different mangling styles.  The optional demangling style argument can
+be used to choose an appropriate demangling style for your
+compiler.
+.IP "\fB\-\-no\-demangle\fR" 4
+.IX Item "--no-demangle"
+Do not demangle low-level symbol names.  This is the default.
+.IP "\fB\-\-recurse\-limit\fR" 4
+.IX Item "--recurse-limit"
+.PD 0
+.IP "\fB\-\-no\-recurse\-limit\fR" 4
+.IX Item "--no-recurse-limit"
+.IP "\fB\-\-recursion\-limit\fR" 4
+.IX Item "--recursion-limit"
+.IP "\fB\-\-no\-recursion\-limit\fR" 4
+.IX Item "--no-recursion-limit"
+.PD
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings.  Since the name mangling formats allow for
+an infinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault.  The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+.Sp
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names.  Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+.IP "\fB\-U\fR \fI[d|i|l|e|x|h]\fR" 4
+.IX Item "-U [d|i|l|e|x|h]"
+.PD 0
+.IP "\fB\-\-unicode=[default|invalid|locale|escape|hex|highlight]\fR" 4
+.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
+.PD
+Controls the display of non-ASCII characters in identifier names.
+The default (\fB\-\-unicode=locale\fR or \fB\-\-unicode=default\fR) is
+to treat them as multibyte characters and display them in the current
+locale.  All other versions of this option treat the bytes as \s-1UTF\-8\s0
+encoded values and attempt to interpret them.  If they cannot be
+interpreted or if the \fB\-\-unicode=invalid\fR option is used then
+they are displayed as a sequence of hex bytes, encloses in curly
+parethesis characters.
+.Sp
+Using the \fB\-\-unicode=escape\fR option will display the characters
+as as unicode escape sequences (\fI\euxxxx\fR).  Using the
+\&\fB\-\-unicode=hex\fR will display the characters as hex byte
+sequences enclosed between angle brackets.
+.Sp
+Using the \fB\-\-unicode=highlight\fR will display the characters as 
+unicode escape sequences but it will also highlighted them in red,
+assuming that colouring is supported by the output device.  The
+colouring is intended to draw attention to the presence of unicode
+sequences when they might not be expected.
+.IP "\fB\-e\fR" 4
+.IX Item "-e"
+.PD 0
+.IP "\fB\-\-headers\fR" 4
+.IX Item "--headers"
+.PD
+Display all the headers in the file.  Equivalent to \fB\-h \-l \-S\fR.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-\-notes\fR" 4
+.IX Item "--notes"
+.PD
+Displays the contents of the \s-1NOTE\s0 segments and/or sections, if any.
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-\-relocs\fR" 4
+.IX Item "--relocs"
+.PD
+Displays the contents of the file's relocation section, if it has one.
+.IP "\fB\-u\fR" 4
+.IX Item "-u"
+.PD 0
+.IP "\fB\-\-unwind\fR" 4
+.IX Item "--unwind"
+.PD
+Displays the contents of the file's unwind section, if it has one.  Only
+the unwind sections for \s-1IA64 ELF\s0 files, as well as \s-1ARM\s0 unwind tables
+(\f(CW\*(C`.ARM.exidx\*(C'\fR / \f(CW\*(C`.ARM.extab\*(C'\fR) are currently supported.  If
+support is not yet implemented for your architecture you could try
+dumping the contents of the \fI.eh_frames\fR section using the
+\&\fB\-\-debug\-dump=frames\fR or \fB\-\-debug\-dump=frames\-interp\fR
+options.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-\-dynamic\fR" 4
+.IX Item "--dynamic"
+.PD
+Displays the contents of the file's dynamic section, if it has one.
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\-info\fR" 4
+.IX Item "--version-info"
+.PD
+Displays the contents of the version sections in the file, it they
+exist.
+.IP "\fB\-A\fR" 4
+.IX Item "-A"
+.PD 0
+.IP "\fB\-\-arch\-specific\fR" 4
+.IX Item "--arch-specific"
+.PD
+Displays architecture-specific information in the file, if there
+is any.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.IP "\fB\-\-use\-dynamic\fR" 4
+.IX Item "--use-dynamic"
+.PD
+When displaying symbols, this option makes \fBreadelf\fR use the
+symbol hash tables in the file's dynamic section, rather than the
+symbol table sections.
+.Sp
+When displaying relocations, this option makes \fBreadelf\fR
+display the dynamic relocations rather than the static relocations.
+.IP "\fB\-L\fR" 4
+.IX Item "-L"
+.PD 0
+.IP "\fB\-\-lint\fR" 4
+.IX Item "--lint"
+.IP "\fB\-\-enable\-checks\fR" 4
+.IX Item "--enable-checks"
+.PD
+Displays warning messages about possible problems with the file(s)
+being examined.  If used on its own then all of the contents of the
+file(s) will be examined.  If used with one of the dumping options
+then the warning messages will only be produced for the things being
+displayed.
+.IP "\fB\-x <number or name>\fR" 4
+.IX Item "-x <number or name>"
+.PD 0
+.IP "\fB\-\-hex\-dump=<number or name>\fR" 4
+.IX Item "--hex-dump=<number or name>"
+.PD
+Displays the contents of the indicated section as a hexadecimal bytes.
+A number identifies a particular section by index in the section table;
+any other string identifies all sections with that name in the object file.
+.IP "\fB\-R <number or name>\fR" 4
+.IX Item "-R <number or name>"
+.PD 0
+.IP "\fB\-\-relocated\-dump=<number or name>\fR" 4
+.IX Item "--relocated-dump=<number or name>"
+.PD
+Displays the contents of the indicated section as a hexadecimal
+bytes.  A number identifies a particular section by index in the
+section table; any other string identifies all sections with that name
+in the object file.  The contents of the section will be relocated
+before they are displayed.
+.IP "\fB\-p <number or name>\fR" 4
+.IX Item "-p <number or name>"
+.PD 0
+.IP "\fB\-\-string\-dump=<number or name>\fR" 4
+.IX Item "--string-dump=<number or name>"
+.PD
+Displays the contents of the indicated section as printable strings.
+A number identifies a particular section by index in the section table;
+any other string identifies all sections with that name in the object file.
+.IP "\fB\-z\fR" 4
+.IX Item "-z"
+.PD 0
+.IP "\fB\-\-decompress\fR" 4
+.IX Item "--decompress"
+.PD
+Requests that the section(s) being dumped by \fBx\fR, \fBR\fR or
+\&\fBp\fR options are decompressed before being displayed.  If the
+section(s) are not compressed then they are displayed as is.
+.IP "\fB\-c\fR" 4
+.IX Item "-c"
+.PD 0
+.IP "\fB\-\-archive\-index\fR" 4
+.IX Item "--archive-index"
+.PD
+Displays the file symbol index information contained in the header part
+of binary archives.  Performs the same function as the \fBt\fR
+command to \fBar\fR, but without using the \s-1BFD\s0 library.
+.IP "\fB\-w[lLiaprmfFsOoRtUuTgAckK]\fR" 4
+.IX Item "-w[lLiaprmfFsOoRtUuTgAckK]"
+.PD 0
+.IP "\fB\-\-debug\-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR" 4
+.IX Item "--debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
+.PD
+Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any
+are present.  Compressed debug sections are automatically decompressed
+(temporarily) before they are displayed.  If one or more of the
+optional letters or words follows the switch then only those type(s)
+of data will be dumped.  The letters and words refer to the following
+information:
+.RS 4
+.ie n .IP """a""" 4
+.el .IP "\f(CWa\fR" 4
+.IX Item "a"
+.PD 0
+.ie n .IP """=abbrev""" 4
+.el .IP "\f(CW=abbrev\fR" 4
+.IX Item "=abbrev"
+.PD
+Displays the contents of the \fB.debug_abbrev\fR section.
+.ie n .IP """A""" 4
+.el .IP "\f(CWA\fR" 4
+.IX Item "A"
+.PD 0
+.ie n .IP """=addr""" 4
+.el .IP "\f(CW=addr\fR" 4
+.IX Item "=addr"
+.PD
+Displays the contents of the \fB.debug_addr\fR section.
+.ie n .IP """c""" 4
+.el .IP "\f(CWc\fR" 4
+.IX Item "c"
+.PD 0
+.ie n .IP """=cu_index""" 4
+.el .IP "\f(CW=cu_index\fR" 4
+.IX Item "=cu_index"
+.PD
+Displays the contents of the \fB.debug_cu_index\fR and/or
+\&\fB.debug_tu_index\fR sections.
+.ie n .IP """f""" 4
+.el .IP "\f(CWf\fR" 4
+.IX Item "f"
+.PD 0
+.ie n .IP """=frames""" 4
+.el .IP "\f(CW=frames\fR" 4
+.IX Item "=frames"
+.PD
+Display the raw contents of a \fB.debug_frame\fR section.
+.ie n .IP """F""" 4
+.el .IP "\f(CWF\fR" 4
+.IX Item "F"
+.PD 0
+.ie n .IP """=frames\-interp""" 4
+.el .IP "\f(CW=frames\-interp\fR" 4
+.IX Item "=frames-interp"
+.PD
+Display the interpreted contents of a \fB.debug_frame\fR section.
+.ie n .IP """g""" 4
+.el .IP "\f(CWg\fR" 4
+.IX Item "g"
+.PD 0
+.ie n .IP """=gdb_index""" 4
+.el .IP "\f(CW=gdb_index\fR" 4
+.IX Item "=gdb_index"
+.PD
+Displays the contents of the \fB.gdb_index\fR and/or
+\&\fB.debug_names\fR sections.
+.ie n .IP """i""" 4
+.el .IP "\f(CWi\fR" 4
+.IX Item "i"
+.PD 0
+.ie n .IP """=info""" 4
+.el .IP "\f(CW=info\fR" 4
+.IX Item "=info"
+.PD
+Displays the contents of the \fB.debug_info\fR section.  Note: the
+output from this option can also be restricted by the use of the 
+\&\fB\-\-dwarf\-depth\fR and \fB\-\-dwarf\-start\fR options.
+.ie n .IP """k""" 4
+.el .IP "\f(CWk\fR" 4
+.IX Item "k"
+.PD 0
+.ie n .IP """=links""" 4
+.el .IP "\f(CW=links\fR" 4
+.IX Item "=links"
+.PD
+Displays the contents of the \fB.gnu_debuglink\fR,
+\&\fB.gnu_debugaltlink\fR and \fB.debug_sup\fR sections, if any of
+them are present.  Also displays any links to separate dwarf object
+files (dwo), if they are specified by the DW_AT_GNU_dwo_name or
+DW_AT_dwo_name attributes in the \fB.debug_info\fR section.
+.ie n .IP """K""" 4
+.el .IP "\f(CWK\fR" 4
+.IX Item "K"
+.PD 0
+.ie n .IP """=follow\-links""" 4
+.el .IP "\f(CW=follow\-links\fR" 4
+.IX Item "=follow-links"
+.PD
+Display the contents of any selected debug sections that are found in
+linked, separate debug info file(s).  This can result in multiple
+versions of the same debug section being displayed if it exists in
+more than one file.
+.Sp
+In addition, when displaying \s-1DWARF\s0 attributes, if a form is found that
+references the separate debug info file, then the referenced contents
+will also be displayed.
+.Sp
+Note \- in some distributions this option is enabled by default.  It
+can be disabled via the \fBN\fR debug option.  The default can be
+chosen when configuring the binutils via the
+\&\fB\-\-enable\-follow\-debug\-links=yes\fR or
+\&\fB\-\-enable\-follow\-debug\-links=no\fR options.  If these are not
+used then the default is to enable the following of debug links.
+.Sp
+Note \- if support for the debuginfod protocol was enabled when the
+binutils were built then this option will also include an attempt to
+contact any debuginfod servers mentioned in the \fI\s-1DEBUGINFOD_URLS\s0\fR
+environment variable.  This could take some time to resolve.  This
+behaviour can be disabled via the \fB=do\-not\-use\-debuginfod\fR debug
+option.
+.ie n .IP """N""" 4
+.el .IP "\f(CWN\fR" 4
+.IX Item "N"
+.PD 0
+.ie n .IP """=no\-follow\-links""" 4
+.el .IP "\f(CW=no\-follow\-links\fR" 4
+.IX Item "=no-follow-links"
+.PD
+Disables the following of links to separate debug info files.
+.ie n .IP """D""" 4
+.el .IP "\f(CWD\fR" 4
+.IX Item "D"
+.PD 0
+.ie n .IP """=use\-debuginfod""" 4
+.el .IP "\f(CW=use\-debuginfod\fR" 4
+.IX Item "=use-debuginfod"
+.PD
+Enables contacting debuginfod servers if there is a need to follow
+debug links.  This is the default behaviour.
+.ie n .IP """E""" 4
+.el .IP "\f(CWE\fR" 4
+.IX Item "E"
+.PD 0
+.ie n .IP """=do\-not\-use\-debuginfod""" 4
+.el .IP "\f(CW=do\-not\-use\-debuginfod\fR" 4
+.IX Item "=do-not-use-debuginfod"
+.PD
+Disables contacting debuginfod servers when there is a need to follow
+debug links.
+.ie n .IP """l""" 4
+.el .IP "\f(CWl\fR" 4
+.IX Item "l"
+.PD 0
+.ie n .IP """=rawline""" 4
+.el .IP "\f(CW=rawline\fR" 4
+.IX Item "=rawline"
+.PD
+Displays the contents of the \fB.debug_line\fR section in a raw
+format.
+.ie n .IP """L""" 4
+.el .IP "\f(CWL\fR" 4
+.IX Item "L"
+.PD 0
+.ie n .IP """=decodedline""" 4
+.el .IP "\f(CW=decodedline\fR" 4
+.IX Item "=decodedline"
+.PD
+Displays the interpreted contents of the \fB.debug_line\fR section.
+.ie n .IP """m""" 4
+.el .IP "\f(CWm\fR" 4
+.IX Item "m"
+.PD 0
+.ie n .IP """=macro""" 4
+.el .IP "\f(CW=macro\fR" 4
+.IX Item "=macro"
+.PD
+Displays the contents of the \fB.debug_macro\fR and/or
+\&\fB.debug_macinfo\fR sections.
+.ie n .IP """o""" 4
+.el .IP "\f(CWo\fR" 4
+.IX Item "o"
+.PD 0
+.ie n .IP """=loc""" 4
+.el .IP "\f(CW=loc\fR" 4
+.IX Item "=loc"
+.PD
+Displays the contents of the \fB.debug_loc\fR and/or
+\&\fB.debug_loclists\fR sections.
+.ie n .IP """O""" 4
+.el .IP "\f(CWO\fR" 4
+.IX Item "O"
+.PD 0
+.ie n .IP """=str\-offsets""" 4
+.el .IP "\f(CW=str\-offsets\fR" 4
+.IX Item "=str-offsets"
+.PD
+Displays the contents of the \fB.debug_str_offsets\fR section.
+.ie n .IP """p""" 4
+.el .IP "\f(CWp\fR" 4
+.IX Item "p"
+.PD 0
+.ie n .IP """=pubnames""" 4
+.el .IP "\f(CW=pubnames\fR" 4
+.IX Item "=pubnames"
+.PD
+Displays the contents of the \fB.debug_pubnames\fR and/or
+\&\fB.debug_gnu_pubnames\fR sections.
+.ie n .IP """r""" 4
+.el .IP "\f(CWr\fR" 4
+.IX Item "r"
+.PD 0
+.ie n .IP """=aranges""" 4
+.el .IP "\f(CW=aranges\fR" 4
+.IX Item "=aranges"
+.PD
+Displays the contents of the \fB.debug_aranges\fR section.
+.ie n .IP """R""" 4
+.el .IP "\f(CWR\fR" 4
+.IX Item "R"
+.PD 0
+.ie n .IP """=Ranges""" 4
+.el .IP "\f(CW=Ranges\fR" 4
+.IX Item "=Ranges"
+.PD
+Displays the contents of the \fB.debug_ranges\fR and/or
+\&\fB.debug_rnglists\fR sections.
+.ie n .IP """s""" 4
+.el .IP "\f(CWs\fR" 4
+.IX Item "s"
+.PD 0
+.ie n .IP """=str""" 4
+.el .IP "\f(CW=str\fR" 4
+.IX Item "=str"
+.PD
+Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR
+and/or \fB.debug_str_offsets\fR sections.
+.ie n .IP """t""" 4
+.el .IP "\f(CWt\fR" 4
+.IX Item "t"
+.PD 0
+.ie n .IP """=pubtype""" 4
+.el .IP "\f(CW=pubtype\fR" 4
+.IX Item "=pubtype"
+.PD
+Displays the contents of the \fB.debug_pubtypes\fR and/or
+\&\fB.debug_gnu_pubtypes\fR sections.
+.ie n .IP """T""" 4
+.el .IP "\f(CWT\fR" 4
+.IX Item "T"
+.PD 0
+.ie n .IP """=trace_aranges""" 4
+.el .IP "\f(CW=trace_aranges\fR" 4
+.IX Item "=trace_aranges"
+.PD
+Displays the contents of the \fB.trace_aranges\fR section.
+.ie n .IP """u""" 4
+.el .IP "\f(CWu\fR" 4
+.IX Item "u"
+.PD 0
+.ie n .IP """=trace_abbrev""" 4
+.el .IP "\f(CW=trace_abbrev\fR" 4
+.IX Item "=trace_abbrev"
+.PD
+Displays the contents of the \fB.trace_abbrev\fR section.
+.ie n .IP """U""" 4
+.el .IP "\f(CWU\fR" 4
+.IX Item "U"
+.PD 0
+.ie n .IP """=trace_info""" 4
+.el .IP "\f(CW=trace_info\fR" 4
+.IX Item "=trace_info"
+.PD
+Displays the contents of the \fB.trace_info\fR section.
+.RE
+.RS 4
+.Sp
+Note: displaying the contents of \fB.debug_static_funcs\fR,
+\&\fB.debug_static_vars\fR and \fBdebug_weaknames\fR sections is not
+currently supported.
+.RE
+.IP "\fB\-\-dwarf\-depth=\fR\fIn\fR" 4
+.IX Item "--dwarf-depth=n"
+Limit the dump of the \f(CW\*(C`.debug_info\*(C'\fR section to \fIn\fR children.
+This is only useful with \fB\-\-debug\-dump=info\fR.  The default is
+to print all DIEs; the special value 0 for \fIn\fR will also have this
+effect.
+.Sp
+With a non-zero value for \fIn\fR, DIEs at or deeper than \fIn\fR
+levels will not be printed.  The range for \fIn\fR is zero-based.
+.IP "\fB\-\-dwarf\-start=\fR\fIn\fR" 4
+.IX Item "--dwarf-start=n"
+Print only DIEs beginning with the \s-1DIE\s0 numbered \fIn\fR.  This is only
+useful with \fB\-\-debug\-dump=info\fR.
+.Sp
+If specified, this option will suppress printing of any header
+information and all DIEs before the \s-1DIE\s0 numbered \fIn\fR.  Only
+siblings and children of the specified \s-1DIE\s0 will be printed.
+.Sp
+This can be used in conjunction with \fB\-\-dwarf\-depth\fR.
+.IP "\fB\-P\fR" 4
+.IX Item "-P"
+.PD 0
+.IP "\fB\-\-process\-links\fR" 4
+.IX Item "--process-links"
+.PD
+Display the contents of non-debug sections found in separate debuginfo
+files that are linked to the main file.  This option automatically
+implies the \fB\-wK\fR option, and only sections requested by other
+command line options will be displayed.
+.IP "\fB\-\-ctf[=\fR\fIsection\fR\fB]\fR" 4
+.IX Item "--ctf[=section]"
+Display the contents of the specified \s-1CTF\s0 section.  \s-1CTF\s0 sections themselves
+contain many subsections, all of which are displayed in order.
+.Sp
+By default, display the name of the section named \fI.ctf\fR, which is the
+name emitted by \fBld\fR.
+.IP "\fB\-\-ctf\-parent=\fR\fImember\fR" 4
+.IX Item "--ctf-parent=member"
+If the \s-1CTF\s0 section contains ambiguously-defined types, it will consist
+of an archive of many \s-1CTF\s0 dictionaries, all inheriting from one
+dictionary containing unambiguous types.  This member is by default
+named \fI.ctf\fR, like the section containing it, but it is possible to
+change this name using the \f(CW\*(C`ctf_link_set_memb_name_changer\*(C'\fR
+function at link time.  When looking at \s-1CTF\s0 archives that have been
+created by a linker that uses the name changer to rename the parent
+archive member, \fB\-\-ctf\-parent\fR can be used to specify the name
+used for the parent.
+.IP "\fB\-\-ctf\-symbols=\fR\fIsection\fR" 4
+.IX Item "--ctf-symbols=section"
+.PD 0
+.IP "\fB\-\-ctf\-strings=\fR\fIsection\fR" 4
+.IX Item "--ctf-strings=section"
+.PD
+Specify the name of another section from which the \s-1CTF\s0 file can inherit
+strings and symbols.  By default, the \f(CW\*(C`.symtab\*(C'\fR and its linked
+string table are used.
+.Sp
+If either of \fB\-\-ctf\-symbols\fR or \fB\-\-ctf\-strings\fR is specified, the
+other must be specified as well.
+.IP "\fB\-I\fR" 4
+.IX Item "-I"
+.PD 0
+.IP "\fB\-\-histogram\fR" 4
+.IX Item "--histogram"
+.PD
+Display a histogram of bucket list lengths when displaying the contents
+of the symbol tables.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Display the version number of readelf.
+.IP "\fB\-W\fR" 4
+.IX Item "-W"
+.PD 0
+.IP "\fB\-\-wide\fR" 4
+.IX Item "--wide"
+.PD
+Don't break output lines to fit into 80 columns. By default
+\&\fBreadelf\fR breaks section header and segment listing lines for
+64\-bit \s-1ELF\s0 files, so that they fit into 80 columns. This option causes
+\&\fBreadelf\fR to print each section header resp. each segment one a
+single line, which is far more readable on terminals wider than 80 columns.
+.IP "\fB\-T\fR" 4
+.IX Item "-T"
+.PD 0
+.IP "\fB\-\-silent\-truncation\fR" 4
+.IX Item "--silent-truncation"
+.PD
+Normally when readelf is displaying a symbol name, and it has to
+truncate the name to fit into an 80 column display, it will add a
+suffix of \f(CW\*(C`[...]\*(C'\fR to the name.  This command line option
+disables this behaviour, allowing 5 more characters of the name to be
+displayed and restoring the old behaviour of readelf (prior to release
+2.35).
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Display the command-line options understood by \fBreadelf\fR.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBobjdump\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/readlink.1 b/upstream/mageia-cauldron/man1/readlink.1
new file mode 100644
index 00000000..7954297f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/readlink.1
@@ -0,0 +1,67 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH READLINK "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+readlink \- print resolved symbolic links or canonical file names
+.SH SYNOPSIS
+.B readlink
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+Note \fBrealpath\fP(1) is the preferred command to use
+for canonicalization functionality.
+.PP
+Print value of a symbolic link or canonical file name
+.TP
+\fB\-f\fR, \fB\-\-canonicalize\fR
+canonicalize by following every symlink in
+every component of the given name recursively;
+all but the last component must exist
+.TP
+\fB\-e\fR, \fB\-\-canonicalize\-existing\fR
+canonicalize by following every symlink in
+every component of the given name recursively,
+all components must exist
+.TP
+\fB\-m\fR, \fB\-\-canonicalize\-missing\fR
+canonicalize by following every symlink in
+every component of the given name recursively,
+without requirements on components existence
+.TP
+\fB\-n\fR, \fB\-\-no\-newline\fR
+do not output the trailing delimiter
+.HP
+\fB\-q\fR, \fB\-\-quiet\fR
+.TP
+\fB\-s\fR, \fB\-\-silent\fR
+suppress most error messages (on by default)
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+report error messages
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Dmitry V. Levin.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBreadlink\fP(2), \fBrealpath\fP(1), \fBrealpath\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/readlink>
+.br
+or available locally via: info \(aq(coreutils) readlink invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/readom.1 b/upstream/mageia-cauldron/man1/readom.1
new file mode 100644
index 00000000..3bdc47b4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/readom.1
@@ -0,0 +1,497 @@
+.\" @(#)readom.1	1.23 06/01/12 Copyright 1996-2006 J. Schilling
+.\" 
+.\" Modified version of readcd.1 by J. Schilling, 11/2006
+.\" 
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License version 2
+.\" as published by the Free Software Foundation.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License along with
+.\" this program; see the file COPYING.  If not, write to the Free Software
+.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
+.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
+.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
+.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
+.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
+.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U
+.if t .ds s \\(*b
+.if t .ds S SS
+.if n .ds a ae
+.if n .ds o oe
+.if n .ds u ue
+.if n .ds s sz
+.TH READOM 1 "Version 2.0" "J\*org Schilling" "Schily\'s USER COMMANDS"
+.SH NAME
+readom \- read or write data Compact Discs
+.SH SYNOPSIS
+.B readom
+.BI dev= device
+[
+.I options
+]
+
+.SH DESCRIPTION
+.B Readom
+is used to read or write Compact Discs.
+.PP
+The
+.I device
+refers to a device location similar to the one used in the wodim command. Refer to its manpage for details.
+.PP
+Also note that this version of readom uses a modified libusal library which has
+a different behaviour compared to the one distributed by its original author.
+
+.SH OPTIONS
+.PP
+If no options except the 
+.I dev=
+option have been specified, 
+.B readom
+goes into interactive mode.
+Select a primary function and then follow the instructions.
+.PP
+.TP
+.B \-version
+Print version information and exit.
+.TP
+.BI dev= target
+Sets the SCSI target for the drive, see notes above.
+A typical device specification is
+.BI dev= 6,0
+\&.
+If a filename must be provided together with the numerical target 
+specification, the filename is implementation specific.
+The correct filename in this case can be found in the system specific
+manuals of the target operating system.
+On a 
+.I FreeBSD
+system without 
+.I CAM
+support, you need to use the control device (e.g.
+.IR /dev/rcd0.ctl ).
+A correct device specification in this case may be
+.BI dev= /dev/rcd0.ctl:@
+\&.
+.sp
+On Linux, drives connected to a parallel port adapter are mapped
+to a virtual SCSI bus. Different adapters are mapped to different
+targets on this virtual SCSI bus.
+.sp
+If no 
+.I dev
+option is present, 
+.B readom
+will try to get the device from the 
+.B CDR_DEVICE
+environment.
+.sp
+If the argument to the
+.B dev=
+option does not contain the characters ',', '/', '@' or ':',
+it is interpreted as an label name that may be found in the file
+/etc/wodim.conf (see FILES section).
+.TP
+.BI timeout= #
+Set the default SCSI command timeout value to 
+.IR # " seconds.
+The default SCSI command timeout is the minimum timeout used for sending
+SCSI commands.
+If a SCSI command fails due to a timeout, you may try to raise the
+default SCSI command timeout above the timeout value of the failed command.
+If the command runs correctly with a raised command timeout,
+please report the better timeout value and the corresponding command to 
+the author of the program.
+If no 
+.I timeout 
+option is present, a default timeout of 40 seconds is used.
+.TP
+.BI debug= "#, " -d
+Set the misc debug value to # (with debug=#) or increment
+the misc debug level by one (with -d). If you specify
+.I -dd,
+this equals to 
+.BI debug= 2.
+This may help to find problems while opening a driver for libusal.
+as well as with sector sizes and sector types.
+Using
+.B \-debug
+slows down the process and may be the reason for a buffer underrun.
+.TP
+.BR kdebug= "#, " kd= #
+Tell the 
+.BR usal -driver
+to modify the kernel debug value while SCSI commands are running.
+.TP
+.BR \-silent ", " \-s
+Do not print out a status report for failed SCSI commands.
+.TP
+.B \-v
+Increment the level of general verbosity by one.
+This is used e.g. to display the progress of the process.
+.TP
+.B \-V
+Increment the verbose level with respect of SCSI command transport by one.
+This helps to debug problems
+during the process, that occur in the CD-Recorder. 
+If you get incomprehensible error messages you should use this flag
+to get more detailed output.
+.B \-VV
+will show data buffer content in addition.
+Using
+.B \-V
+or
+.B \-VV
+slows down the process.
+.TP
+.BI f= file
+Specify the filename where the output should be written or the input should
+be taken from. Using '-' as filename will cause
+.B readom
+to use 
+.BR stdout " resp. " stdin .
+.TP
+.B \-w
+Switch to write mode. If this option is not present,
+.B readom
+reads from the specified device.
+.TP
+.B \-c2scan
+Scans the whole CD or the range specified by the 
+.BI sectors= range
+for C2 errors. C2 errors are errors that are uncorrectable after the second
+stage of the 24/28 + 28/32 Reed Solomon correction system at audio level
+(2352 bytes sector size). If an audio CD has C2 errors, interpolation is needed
+to hide the errors. If a data CD has C2 errors, these errors are in most
+cases corrected by the ECC/EDC code that makes 2352 bytes out of 2048 data
+bytes. The ECC/EDC code should be able to correct about 100 C2 error bytes
+per sector.
+.sp
+If you find C2 errors you may want to reduce the speed using the
+.B speed=
+option as C2 errors may be a result of dynamic unbalance on the medium.
+.TP
+.B \-scanbus
+Scan all SCSI devices on all SCSI busses and print the inquiry
+strings. This option may be used to find SCSI address of the 
+devices on a system.
+The numbers printed out as labels are computed by: 
+.B "bus * 100 + target
+.TP
+.BI sectors= range
+Specify a sector range that should be read.
+The range is specified by the starting sector number, a minus sign and the
+ending sector number.
+The end sector is not included in the list, so 
+.BR sectors= 0-0
+will not read anything and may be used to check for a CD in the drive.
+.TP
+.BR speed= #
+Set the speed factor of the read or write process to #.
+# is an integer, representing a multiple of the audio speed.
+This is about 150 KB/s for CD-ROM and about 172 KB/s for CD-Audio.
+If no 
+.I speed
+option is present, 
+.B readom
+will use maximum speed.
+Only MMC compliant drives will benefit from this option.
+The speed of non MMC drives is not changed.
+.sp
+Using a lower speed may increase the readability of a CD or DVD.
+.TP
+.BR ts= #
+Set the maximum transfer size for a single SCSI command to #.
+The syntax for the 
+.B ts=
+option is the same as for wodim fs=# or sdd bs=#.
+.sp
+If no 
+.B ts=
+option has been specified,
+.B readom
+defaults to a transfer size of 256 kB. If libusal gets lower values from the
+operating system, the value is reduced to the maximum value that is possible
+with the current operating system.
+Sometimes, it may help to further reduce the transfer size or to enhance it,
+but note that it may take a long time to find a better value by experimenting
+with the
+.B ts=
+option.
+.TP
+.B \-notrunc
+Do not truncate the output file when opening it.
+.TP
+.B \-fulltoc
+Retrieve a full TOC from the current disk and print it in hex.
+.TP
+.B \-clone
+Do a clone read. Read the CD with all sub-channel data and a full TOC.
+The full TOC data will be put into a file with similar name as with the
+.B f=
+option but the suffix 
+.B .toc
+added.
+.TP
+.B \-noerror
+Do not abort if the high level error checking in
+.B readom
+found an uncorrectable error in the data stream.
+.TP
+.B \-nocorr
+Switch the drive into a mode where it ignores read errors in data sectors that
+are a result of uncorrectable ECC/EDC errors before reading.
+If
+.B readom
+completes, the error recovery mode of the drive is switched back to the remembered 
+old mode.
+.TP
+.BI retries= #
+Set the retry count for high level retries in
+.B readom
+to 
+.IR # .
+The default is to do 128 retries which may be too much if you like to read a CD
+with many unreadable sectors.
+.TP
+.B \-overhead
+Meter the SCSI command overhead time.
+This is done by executing several commands 1000 times and printing the
+total time used. If you divide the displayed times by 1000, you get 
+the average overhead time for a single command.
+.TP
+.BR meshpoints= #
+Print read-speed at # locations.
+The purpose of this option is to create a list of read speed values suitable
+for e.g.
+.BR gnuplot .
+The speed values are calculated assuming that 1000 bytes are one kilobyte
+as documented in the SCSI standard.
+The output data created for this purpose is written to 
+.IR stdout .
+.TP
+.B \-factor
+Output the speed values for
+.BR meshpoints= #
+as factor based on 
+.I "single speed
+of the current medium.
+This only works if
+.B readom
+is able to determine the current medium type.
+.SH EXAMPLES
+.PP
+For all examples below, it will be assumed that the drive is
+connected to the primary SCSI bus of the machine. The SCSI target id is
+set to 2.
+.PP
+To read the complete media from a CD-ROM writing the data to the file
+.IR cdimage.raw :
+.PP
+    readom dev=2,0 f=cdimage.raw
+.PP
+To read sectors from range 150 ... 10000 from a CD-ROM writing the data to the file
+.IR cdimage.raw :
+.PP
+    readom dev=2,0 sectors=150-10000 f=cdimage.raw
+.PP
+To write the data from the file
+.I cdimage.raw
+(e.g. a filesystem image from 
+.BR genisoimage )
+to a DVD-RAM, call:
+.PP
+    readom dev=2,0 -w f=cdimage.raw
+
+.SH ENVIRONMENT
+.TP
+.B RSH
+If the 
+.B RSH
+environment is present, the remote connection will not be created via
+.BR rcmd (3)
+but by calling the program pointed to by
+.BR RSH .
+Use e.g. 
+.BR RSH= /usr/bin/ssh
+to create a secure shell connection.
+.sp
+Note that this forces 
+.B wodim
+to create a pipe to the 
+.B rsh(1)
+program and disallows
+.B wodim
+to directly access the network socket to the remote server.
+This makes it impossible to set up performance parameters and slows down
+the connection compared to a 
+.B root
+initiated
+.B rcmd(3)
+connection.
+.TP
+.B RSCSI
+If the 
+.B RSCSI
+environment is present, the remote SCSI server will not be the program
+.B /opt/schily/sbin/rscsi
+but the program pointed to by
+.BR RSCSI .
+Note that the remote SCSI server program name will be ignored if you log in
+using an account that has been created with a remote SCSI server program as
+login shell.
+.SH SEE ALSO
+.BR wodim (1),
+.BR genisoimage (1),
+.BR rcmd (3),
+.BR ssh (1).
+
+.SH NOTES
+.PP
+Unless you want to risk getting problems,
+.B readom
+should be run as root. If you don't want to allow users to become root on your system,
+.B readom
+may safely be installed suid root.
+For more information see the additional notes of your system/program
+distribution or README.suidroot which is part of the Cdrkit source.
+.PP
+Documentation of the
+.B wodim
+program contains more technical details which could also apply to
+.B readom.
+
+.SH DIAGNOSTICS
+.PP
+.PP
+A typical error message for a SCSI command looks like:
+.sp
+.RS
+.nf
+readom: I/O error. test unit ready: scsi sendcmd: no error
+CDB:  00 20 00 00 00 00
+status: 0x2 (CHECK CONDITION)
+Sense Bytes: 70 00 05 00 00 00 00 0A 00 00 00 00 25 00 00 00 00 00
+Sense Key: 0x5 Illegal Request, Segment 0
+Sense Code: 0x25 Qual 0x00 (logical unit not supported) Fru 0x0
+Sense flags: Blk 0 (not valid)
+cmd finished after 0.002s timeout 40s
+.fi
+.sp
+.RE
+The first line gives information about the transport of the command.
+The text after the first colon gives the error text for the system call
+from the view of the kernel. It usually is:
+.B "I/O error
+unless other problems happen. The next words contain a short description for
+the SCSI command that fails. The rest of the line tells you if there were
+any problems for the transport of the command over the SCSI bus.
+.B "fatal error
+means that it was not possible to transport the command (i.e. no device present
+at the requested SCSI address).
+.PP
+The second line prints the SCSI command descriptor block for the failed command.
+.PP
+The third line gives information on the SCSI status code returned by the 
+command, if the transport of the command succeeds. 
+This is error information from the SCSI device.
+.PP
+The fourth line is a hex dump of the auto request sense information for the 
+command.
+.PP
+The fifth line is the error text for the sense key if available, followed
+by the segment number that is only valid if the command was a
+.I copy
+command. If the error message is not directly related to the current command,
+the text
+.I deferred error
+is appended.
+.PP
+The sixth line is the error text for the sense code and the sense qualifier if available.
+If the type of the device is known, the sense data is decoded from tables
+in
+.IR scsierrs.c " .
+The text is followed by the error value for a field replaceable unit.
+.PP
+The seventh line prints the block number that is related to the failed command
+and text for several error flags. The block number may not be valid.
+.PP
+The eight line reports the timeout set up for this command and the time
+that the command really needed to complete.
+
+.SH BUGS
+.PP
+The 
+.B readom
+program described here is the Cdrkit spinoff from the original
+.B readcd
+application (see AUTHOR section for details). It may contain bugs not present
+in the original implementation.
+.PP
+It is definitely less portable than the original implementation.
+.PP
+For platform specific bugs, see the corresponding README.platform file in the
+Cdrkit documentation (eg. README.linux).
+
+.SH "MAILING LISTS
+If you want to actively take part on the development of readom,
+you may join the developer mailing list via this URL:
+.sp
+.B
+http://alioth.debian.org/mail/?group_id=31006
+.PP
+The mail address of the list is:
+.B
+debburn-devel@lists.alioth.debian.org
+
+
+
+
+.SH AUTHOR
+.nf
+J\*org Schilling
+Seestr. 110
+D-13353 Berlin
+Germany
+.fi
+
+.PP
+This is application is a spinoff from the original implementation of readcd delivered in
+the cdrtools package [1] created by Joerg Schilling, who deserves the most credits
+for its success. However, he is not involved into the development
+of this spinoff and therefore he shall not be made responsible for any problem
+caused by it. Do not try to get support from the original author!
+.PP
+Additional information can be found on:
+.br
+https://alioth.debian.org/projects/debburn/
+.PP
+If you have support questions, send them to
+.PP
+.B
+debburn-devel@lists.alioth.debian.org
+.br
+.PP
+If you have definitely found a bug, send a mail to this list or to
+.PP
+.B
+submit@bugs.debian.org
+.br
+.PP
+writing at least a short description into the Subject and "Package: cdrkit"
+into the first line of the mail body.
+.SH SOURCES
+.PP
+.br
+[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de
+
diff --git a/upstream/mageia-cauldron/man1/realpath.1 b/upstream/mageia-cauldron/man1/realpath.1
new file mode 100644
index 00000000..d32a09f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/realpath.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH REALPATH "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+realpath \- print the resolved path
+.SH SYNOPSIS
+.B realpath
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the resolved absolute file name;
+all but the last component must exist
+.TP
+\fB\-e\fR, \fB\-\-canonicalize\-existing\fR
+all components of the path must exist
+.TP
+\fB\-m\fR, \fB\-\-canonicalize\-missing\fR
+no path components need exist or be a directory
+.TP
+\fB\-L\fR, \fB\-\-logical\fR
+resolve '..' components before symlinks
+.TP
+\fB\-P\fR, \fB\-\-physical\fR
+resolve symlinks as encountered (default)
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress most error messages
+.TP
+\fB\-\-relative\-to\fR=\fI\,DIR\/\fR
+print the resolved path relative to DIR
+.TP
+\fB\-\-relative\-base\fR=\fI\,DIR\/\fR
+print absolute paths unless paths below DIR
+.TP
+\fB\-s\fR, \fB\-\-strip\fR, \fB\-\-no\-symlinks\fR
+don't expand symlinks
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Padraig Brady.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBreadlink\fP(1), \fBreadlink\fP(2), \fBrealpath\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/realpath>
+.br
+or available locally via: info \(aq(coreutils) realpath invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/recode-sr-latin.1 b/upstream/mageia-cauldron/man1/recode-sr-latin.1
new file mode 100644
index 00000000..3a6a9ae6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/recode-sr-latin.1
@@ -0,0 +1,43 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH RECODE-SR-LATIN "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+recode-sr-latin \- convert Serbian text from Cyrillic to Latin script
+.SH SYNOPSIS
+.B recode-sr-latin
+[\fI\,OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Recode Serbian text from Cyrillic to Latin script.
+The input text is read from standard input.  The converted text is output to
+standard output.
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Danilo Segan and Bruno Haible.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2006\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B recode-sr-latin
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B recode-sr-latin
+programs are properly installed at your site, the command
+.IP
+.B info recode-sr-latin
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/refer.1 b/upstream/mageia-cauldron/man1/refer.1
new file mode 100644
index 00000000..b92d5ff8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/refer.1
@@ -0,0 +1,1769 @@
+.TH REFER 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+refer \- preprocess bibliographic references for groff
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY refer
+.OP \-benCPRS
+.OP \-a n
+.OP \-c fields
+.OP \-f n
+.OP \-i fields
+.OP \-k field
+.OP \-l m,n
+.OP \-p filename
+.OP \-s fields
+.OP \-t n
+.BI "\-B " field . macro
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.SY refer
+.B \-\-help
+.YS
+.
+.SY refer
+.B \-v
+.SY refer
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This file documents the GNU version of
+.BR refer ,
+which is part of the groff document formatting system.
+.
+.B refer
+copies the contents of
+.IR filename \|.\|.\|.\&
+to the standard output,
+except that lines between
+.B .[
+and
+.B .]\&
+are interpreted as citations,
+and lines between
+.B .R1
+and
+.B .R2
+are interpreted as commands about how citations are to be processed.
+.
+.
+.LP
+Each citation specifies a reference.
+.
+The citation can specify a reference that is contained in
+a bibliographic database by giving a set of keywords
+that only that reference contains.
+.
+Alternatively it can specify a reference by supplying a database
+record in the citation.
+.
+A combination of these alternatives is also possible.
+.
+.
+.LP
+For each citation,
+.B refer
+can produce a mark in the text.
+.
+This mark consists of some label which can be separated from
+the text and from other labels in various ways.
+.
+For each reference it also outputs
+.B groff
+commands that can be used by a macro package to produce a formatted
+reference for each citation.
+.
+The output of
+.B refer
+must therefore be processed using a suitable macro package.
+.
+The
+.B \-ms
+and
+.B \-me
+macros are both suitable.
+.
+The commands to format a citation's reference can be output immediately after
+the citation,
+or the references may be accumulated,
+and the commands output at some later point.
+.
+If the references are accumulated, then multiple citations of the same
+reference will produce a single formatted reference.
+.
+.
+.LP
+The interpretation of lines between
+.B .R1
+and
+.B .R2
+as commands is a new feature of GNU
+.BR refer .
+.
+Documents making use of this feature can still be processed by
+Unix refer just by adding the lines
+.
+.RS
+.LP
+.nf
+.ft B
+\&.de R1
+\&.ig R2
+\&..
+.ft
+.fi
+.RE
+.
+to the beginning of the document.
+.
+This will cause
+.B troff
+to ignore everything between
+.B .R1
+and
+.BR .R2 .
+.
+The effect of some commands can also be achieved by options.
+.
+These options are supported mainly for compatibility with Unix refer.
+.
+It is usually more convenient to use commands.
+.
+.
+.LP
+.B refer
+generates
+.B .lf
+lines so that filenames and line numbers in messages produced
+by commands that read
+.B refer
+output will be correct;
+it also interprets lines beginning with
+.B .lf
+so that filenames and line numbers in the messages and
+.B .lf
+lines that it produces will be accurate even if the input has been
+preprocessed by a command such as
+.BR soelim (1).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.LP
+Most options are equivalent to commands
+(for a description of these commands,
+see subsection \(lqCommands\(rq below).
+.
+.
+.nr a \n(.j
+.ad l
+.TP
+.B \-b
+.B "no-label-in-text; no-label-in-reference"
+.
+.
+.TP
+.B \-e
+.B accumulate
+.
+.
+.TP
+.B \-n
+.B no-default-database
+.
+.
+.TP
+.B \-C
+.B compatible
+.
+.
+.TP
+.B \-P
+.B move-punctuation
+.
+.
+.TP
+.B \-S
+.B
+label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
+.
+.
+.TP
+.BI \-a n
+.B reverse
+.BI A n
+.
+.
+.TP
+.BI \-c fields
+.B capitalize
+.I fields
+.
+.
+.TP
+.BI \-f n
+.B label
+.BI % n
+.
+.
+.TP
+.BI \-i fields
+.B search-ignore
+.I fields
+.
+.
+.TP
+.B \-k
+.B label
+.B L\(ti%a
+.
+.
+.TP
+.BI \-k field
+.B label
+.IB field \(ti%a
+.
+.
+.TP
+.B \-l
+.B label
+.B A.nD.y%a
+.
+.
+.TP
+.BI \-l m
+.B label
+.BI A.n+ m D.y%a
+.
+.
+.TP
+.BI \-l, n
+.B label
+.BI A.nD.y\- n %a
+.
+.
+.TP
+.BI \-l m , n
+.B label
+.BI A.n+ m D.y\- n %a
+.
+.
+.TP
+.BI \-p filename
+.B database
+.I filename
+.
+.
+.TP
+.BI \-s spec
+.B sort
+.I spec
+.
+.
+.TP
+.BI \-t n
+.B search-truncate
+.I n
+.ad \na
+.
+.
+.LP
+These options are equivalent to the following commands with the
+addition that the filenames specified on the command line are
+processed as if they were arguments to the
+.B bibliography
+command instead of in the normal way:
+.
+.
+.TP
+.B \-B
+.B "annotate X AP; no-label-in-reference"
+.
+.
+.TP
+.BI \-B field . macro
+.B annotate
+.I field
+.IB macro ;
+.B no-label-in-reference
+.
+.
+.LP
+The following options have no equivalent commands:
+.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.TP
+.B \-R
+Don't recognize lines beginning with
+.BR .R1 / .R2 .
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+.\" ====================================================================
+.SS Bibliographic databases
+.\" ====================================================================
+.
+The bibliographic database is a text file consisting of records
+separated by one or more blank lines.
+.
+Within each record fields start with a
+.B %
+at the beginning of a line.
+.
+Each field has a one character name that immediately follows the
+.BR % .
+It is best to use only upper and lower case letters for the names
+of fields.
+.
+The name of the field should be followed by exactly one space,
+and then by the contents of the field.
+.
+Empty fields are ignored.
+.
+The conventional meaning of each field is as follows:
+.
+.
+.TP
+.B %A
+The name of an author.
+.
+If the name contains a title such as
+.B Jr.\&
+at the end,
+it should be separated from the last name by a comma.
+.
+There can be multiple occurrences of the
+.B %A
+field.
+.
+The order is significant.
+.
+It is a good idea always to supply an
+.B %A
+field or a
+.B %Q
+field.
+.
+.
+.TP
+.B %B
+For an article that is part of a book, the title of the book.
+.
+.
+.TP
+.B %C
+The place (city) of publication.
+.
+.
+.TP
+.B %D
+The date of publication.
+.
+The year should be specified in full.
+.
+If the month is specified, the name rather than the number of the month
+should be used, but only the first three letters are required.
+.
+It is a good idea always to supply a
+.B %D
+field;
+if the date is unknown, a value such as
+.B in press
+or
+.B unknown
+can be used.
+.
+.
+.TP
+.B %E
+For an article that is part of a book, the name of an editor of the book.
+.
+Where the work has editors and no authors,
+the names of the editors should be given as
+.B %A
+fields and
+.B ,\ (ed)
+or
+.B ,\ (eds)
+should be appended to the last author.
+.
+.
+.TP
+.B %G
+US Government ordering number.
+.
+.
+.TP
+.B %I
+The publisher (issuer).
+.
+.
+.TP
+.B %J
+For an article in a journal,
+the name of the journal.
+.
+.
+.TP
+.B %K
+Keywords to be used for searching.
+.
+.
+.TP
+.B %L
+Label.
+.
+.
+.TP
+.B %N
+Journal issue number.
+.
+.
+.TP
+.B %O
+Other information.
+.
+This is usually printed at the end of the reference.
+.
+.
+.TP
+.B %P
+Page number.
+A range of pages can be specified as
+.IB m \- n\fR.
+.
+.
+.TP
+.B %Q
+The name of the author, if the author is not a person.
+.
+This will only be used if there are no
+.B %A
+fields.
+.
+There can only be one
+.B %Q
+field.
+.
+.
+.TP
+.B %R
+Technical report number.
+.
+.
+.TP
+.B %S
+Series name.
+.
+.
+.TP
+.B %T
+Title.
+.
+For an article in a book or journal,
+this should be the title of the article.
+.
+.
+.TP
+.B %V
+Volume number of the journal or book.
+.
+.
+.TP
+.B %X
+Annotation.
+.
+.
+.LP
+For all fields except
+.B %A
+and
+.BR %E ,
+if there is more than one occurrence of a particular field in a record,
+only the last such field will be used.
+.
+.
+.LP
+If accent strings are used, they should follow the character to be accented.
+This means that the
+.B AM
+macro must be used with the
+.B \-ms
+macros.
+.
+Accent strings should not be quoted:
+use one
+.B \e
+rather than two.
+.
+.
+.\" ====================================================================
+.SS Citations
+.\" ====================================================================
+.
+The format of a citation is
+.
+.RS
+.BI .[ opening-text
+.br
+.I "flags keywords"
+.br
+.I fields
+.br
+.BI .] closing-text
+.RE
+.
+.
+.LP
+The
+.IR opening-text ,
+.IR closing-text ,
+and
+.I flags
+components are optional.
+.
+Only one of the
+.I keywords
+and
+.I fields
+components need be specified.
+.
+.
+.LP
+The
+.I keywords
+component says to search the bibliographic databases for a reference
+that contains all the words in
+.IR keywords .
+.
+It is an error if more than one reference if found.
+.
+.
+.LP
+The
+.I fields
+components specifies additional fields to replace or supplement
+those specified in the reference.
+.
+When references are being accumulated and the
+.I keywords
+component is non-empty,
+then additional fields should be specified only on the first
+occasion that a particular reference is cited,
+and will apply to all citations of that reference.
+.
+.
+.LP
+The
+.I opening-text
+and
+.I closing-text
+component specifies strings to be used to bracket the label instead
+of the strings specified in the
+.B bracket-label
+command.
+.
+If either of these components is non-empty,
+the strings specified in the
+.B bracket-label
+command will not be used;
+this behaviour can be altered using the
+.B [
+and
+.B ]
+flags.
+Note that leading and trailing spaces are significant for these components.
+.
+.
+.LP
+The
+.I flags
+component is a list of
+non-alphanumeric characters each of which modifies the treatment
+of this particular citation.
+.
+Unix refer will treat these flags as part of the keywords and
+so will ignore them since they are non-alphanumeric.
+.
+The following flags are currently recognized:
+.
+.
+.TP
+.B #
+This says to use the label specified by the
+.B short-label
+command,
+instead of that specified by the
+.B label
+command.
+.
+If no short label has been specified, the normal label will be used.
+.
+Typically the short label is used with author-date labels
+and consists of only the date and possibly a disambiguating letter;
+the
+.B #
+is supposed to be suggestive of a numeric type of label.
+.
+.
+.TP
+.B [
+Precede
+.I opening-text
+with the first string specified in the
+.B bracket-label
+command.
+.
+.
+.TP
+.B ]
+Follow
+.I closing-text
+with the second string specified in the
+.B bracket-label
+command.
+.
+.
+.LP
+One advantages of using the
+.B [
+and
+.B ]
+flags rather than including the brackets in
+.I opening-text
+and
+.I closing-text
+is that
+you can change the style of bracket used in the document just by changing the
+.B bracket-label
+command.
+.
+Another advantage is that sorting and merging of citations
+will not necessarily be inhibited if the flags are used.
+.
+.
+.LP
+If a label is to be inserted into the text,
+it will be attached to the line preceding the
+.B .[
+line.
+.
+If there is no such line, then an extra line will be inserted before the
+.B .[
+line and a warning will be given.
+.
+.
+.LP
+There is no special notation for making a citation to multiple references.
+Just use a sequence of citations, one for each reference.
+.
+Don't put anything between the citations.
+.
+The labels for all the citations will be attached to the line preceding
+the first citation.
+.
+The labels may also be sorted or merged.
+.
+See the description of the
+.B <>
+label expression, and of the
+.B sort-adjacent-labels
+and
+.B abbreviate-label-ranges
+command.
+A label will not be merged if its citation has a non-empty
+.I opening-text
+or
+.IR closing-text .
+.
+However,
+the labels for a citation using the
+.B ]
+flag and without any
+.I closing-text
+immediately followed by a citation using the
+.B [
+flag and without any
+.I opening-text
+may be sorted and merged
+even though the first citation's
+.I opening-text
+or the second citation's
+.I closing-text
+is non-empty.
+.
+(If you wish to prevent this just make the first citation's
+.I closing-text
+.BR \e& .)
+.
+.
+.\" ====================================================================
+.SS Commands
+.\" ====================================================================
+.
+Commands are contained between lines starting with
+.B .R1
+and
+.BR .R2 .
+.
+Recognition of these lines can be prevented by the
+.B \-R
+option.
+.
+When a
+.B .R1
+line is recognized any accumulated references are flushed out.
+.
+Neither
+.B .R1
+nor
+.B .R2
+lines,
+nor anything between them
+is output.
+.
+.
+.LP
+Commands are separated by newlines or
+.BR ; s.
+.B #
+introduces a comment that extends to the end of the line
+(but does not conceal the newline).
+.
+Each command is broken up into words.
+.
+Words are separated by spaces or tabs.
+.
+A word that begins with
+.B \[dq]
+extends to the next
+.B \[dq]
+that is not followed by another
+.BR \[dq] .
+.
+If there is no such
+.B \[dq]
+the word extends to the end of the line.
+.
+Pairs of
+.B \[dq]
+in a word beginning with
+.B \[dq]
+collapse to a single
+.BR \[dq] .
+.
+Neither
+.B #
+nor
+.B ;
+are recognized inside
+.BR \[dq] s.
+.
+A line can be continued by ending it with
+.BR \e ;
+this works everywhere except after a
+.BR # .
+.
+.
+.LP
+.ds n \fR*
+Each command
+.I name
+that is marked with \*n has an associated negative command
+.BI no- name
+that undoes the effect of
+.IR name .
+.
+For example, the
+.B no-sort
+command specifies that references should not be sorted.
+.
+The negative commands take no arguments.
+.
+.
+.LP
+In the following description each argument must be a single word;
+.I field
+is used for a single upper or lower case letter naming a field;
+.I fields
+is used for a sequence of such letters;
+.I m
+and
+.I n
+are used for a non-negative numbers;
+.I string
+is used for an arbitrary string;
+.I filename
+is used for the name of a file.
+.
+.
+.TP
+.BI abbreviate\*n\  fields\ string1\ string2\ string3\ string4
+Abbreviate the first names of
+.IR fields .
+.
+An initial letter will be separated from another initial letter by
+.IR string1 ,
+from the last name by
+.IR string2 ,
+and from anything else
+(such as a
+.B von
+or
+.BR de )
+by
+.IR string3 .
+.
+These default to a period followed by a space.
+.
+In a hyphenated first name,
+the initial of the first part of the name will be separated from the
+hyphen by
+.IR string4 ;
+this defaults to a period.
+.
+No attempt is made to handle any ambiguities that might
+result from abbreviation.
+.
+Names are abbreviated before sorting and before label construction.
+.
+.
+.TP
+.BI abbreviate-label-ranges\*n\  string
+.
+Three or more adjacent labels that refer to consecutive references
+will be abbreviated to a label consisting of the first label,
+followed by
+.I string
+followed by the last label.
+.
+This is mainly useful with numeric labels.
+.
+If
+.I string
+is omitted it defaults to
+.BR \- .
+.
+.
+.TP
+.B accumulate\*n
+Accumulate references instead of writing out each reference
+as it is encountered.
+.
+Accumulated references will be written out whenever a reference
+of the form
+.
+.RS
+.IP
+.B .[
+.br
+.B $LIST$
+.br
+.B .]
+.
+.
+.LP
+is encountered,
+after all input files have been processed,
+and whenever
+.B .R1
+line is recognized.
+.RE
+.
+.
+.TP
+.BI annotate\*n\  field\ string
+.I field
+is an annotation;
+print it at the end of the reference as a paragraph preceded by the line
+.
+.RS
+.IP
+.BI . string
+.
+.
+.LP
+If
+.I string
+is omitted it will default to
+.BR AP ;
+if
+.I field
+is also omitted it will default to
+.BR X .
+.
+Only one field can be an annotation.
+.RE
+.
+.
+.TP
+.BI articles\  string \fR\|.\|.\|.
+.IR string \|.\|.\|.\&
+are definite or indefinite articles, and should be ignored at the beginning of
+.B T
+fields when sorting.
+.
+Initially,
+.BR the ,
+.B a
+and
+.B an
+are recognized as articles.
+.
+.
+.TP
+.BI bibliography\  filename \fR\|.\|.\|.
+.
+Write out all the references contained in the bibliographic databases
+.IR filename \|.\|.\|.
+.
+This command should come last in a
+.BR .R1 / .R2
+block.
+.
+.
+.TP
+.BI bracket-label\  string1\ string2\ string3
+In the text, bracket each label
+with
+.I string1
+and
+.IR string2 .
+.
+An occurrence of
+.I string2
+immediately followed by
+.I string1
+will be turned into
+.IR string3 .
+.
+The default behaviour is
+.
+.RS
+.IP
+.B
+bracket-label \e*([. \e*(.] ", "
+.RE
+.
+.
+.TP
+.BI capitalize\  fields
+Convert
+.I fields
+to caps and small caps.
+.
+.
+.TP
+.B compatible\*n
+Recognize
+.B .R1
+and
+.B .R2
+even when followed by a character other than space or newline.
+.
+.
+.TP
+.BI database\  filename \fR\|.\|.\|.
+Search the bibliographic databases
+.IR filename \|.\|.\|.
+.
+For each
+.I filename
+if an index
+.IB filename .i
+created by
+.BR indxbib (1)
+exists, then it will be searched instead;
+each index can cover multiple databases.
+.
+.
+.TP
+.BI date-as-label\*n\  string
+.I string
+is a label expression that specifies a string with which to replace the
+.B D
+field after constructing the label.
+.
+See subsection \(lqLabel expressions\(rq below for a description of
+label expressions.
+.
+This command is useful if you do not want explicit labels in the
+reference list,
+but instead want to handle any necessary disambiguation by qualifying
+the date in some way.
+.
+The label used in the text would typically be some combination of the
+author and date.
+.
+In most cases you should also use the
+.B no-label-in-reference
+command.
+For example,
+.
+.RS
+.IP
+.B "date-as-label D.+yD.y%a*D.-y"
+.
+.
+.LP
+would attach a disambiguating letter to the year part of the
+.B D
+field in the reference.
+.RE
+.
+.
+.TP
+.B default-database\*n
+The default database should be searched.
+.
+This is the default behaviour,
+so the negative version of this command is more useful.
+.
+.B refer
+determines whether the default database should be searched
+on the first occasion that it needs to do a search.
+.
+Thus a
+.B no-default-database
+command must be given before then,
+in order to be effective.
+.
+.
+.TP
+.BI discard\*n\  fields
+When the reference is read,
+.I fields
+should be discarded;
+no string definitions for
+.I fields
+will be output.
+.
+Initially,
+.I fields
+are
+.BR XYZ .
+.
+.
+.TP
+.BI et-al\*n\  string\ m\ n
+Control use of
+.B "et al"
+in the evaluation of
+.B @
+expressions in label expressions.
+.
+If the number of authors needed to make the author sequence
+unambiguous is
+.I u
+and the total number of authors is
+.I t
+then the last
+.IR t \|\-\| u
+authors will be replaced by
+.I string
+provided that
+.IR t \|\-\| u
+is not less than
+.I m
+and
+.I t
+is not less than
+.IR n .
+.
+The default behaviour is
+.
+.RS
+.IP
+.B
+et-al " et al" 2 3
+.RE
+.
+.
+.TP
+.BI include\  filename
+Include
+.I filename
+and interpret the contents as commands.
+.
+.
+.TP
+.BI join-authors\  string1\ string2\ string3
+This says how authors should be joined together.
+.
+When there are exactly two authors, they will be joined with
+.IR string1 .
+.
+When there are more than two authors,
+all but the last two will be joined with
+.IR string2 ,
+and the last two authors will be joined with
+.IR string3 .
+.
+If
+.I string3
+is omitted,
+it will default to
+.IR string1 ;
+if
+.I string2
+is also omitted it will also default to
+.IR string1 .
+.
+For example,
+.
+.RS
+.IP
+.B
+join-authors " and " ", " ", and "
+.
+.
+.LP
+will restore the default method for joining authors.
+.RE
+.
+.
+.TP
+.B label-in-reference\*n
+When outputting the reference,
+define the string
+.B [F
+to be the reference's label.
+.
+This is the default behaviour; so the negative version
+of this command is more useful.
+.
+.
+.TP
+.B label-in-text\*n
+For each reference output a label in the text.
+.
+The label will be separated from the surrounding text as described in the
+.B bracket-label
+command.
+.
+This is the default behaviour; so the negative version
+of this command is more useful.
+.
+.
+.TP
+.BI label\  string
+.I string
+is a label expression describing how to label each reference.
+.
+.
+.TP
+.BI separate-label-second-parts\  string
+When merging two-part labels, separate the second part of the second
+label from the first label with
+.IR string .
+.
+See the description of the
+.B <>
+label expression.
+.
+.
+.TP
+.B move-punctuation\*n
+In the text,
+move any punctuation at the end of line past the label.
+.
+It is usually a good idea to give this command unless you are using
+superscripted numbers as labels.
+.
+.
+.TP
+.BI reverse\*n\  string
+Reverse the fields whose names
+are in
+.IR string .
+.
+Each field name can be followed by a number which says
+how many such fields should be reversed.
+.
+If no number is given for a field, all such fields will be reversed.
+.
+.
+.TP
+.BI search-ignore\*n\  fields
+While searching for keys in databases for which no index exists,
+ignore the contents of
+.IR fields .
+.
+Initially, fields
+.B XYZ
+are ignored.
+.
+.
+.TP
+.BI search-truncate\*n\  n
+Only require the first
+.I n
+characters of keys to be given.
+.
+In effect when searching for a given key words in the database are
+truncated to the maximum of
+.I n
+and the length of the key.
+.
+Initially
+.I n
+is\ 6.
+.
+.
+.TP
+.BI short-label\*n\  string
+.I string
+is a label expression that specifies an alternative (usually shorter)
+style of label.
+.
+This is used when the
+.B #
+flag is given in the citation.
+.
+When using author-date style labels, the identity of the author
+or authors is sometimes clear from the context, and so it
+may be desirable to omit the author or authors from the label.
+.
+The
+.B short-label
+command will typically be used to specify a label containing just
+a date and possibly a disambiguating letter.
+.
+.
+.TP
+.BI sort\*n\  string
+Sort references according to
+.BR string .
+.
+References will automatically be accumulated.
+.
+.I string
+should be a list of field names,
+each followed by a number,
+indicating how many fields with the name should be used for sorting.
+.
+.B +
+can be used to indicate that all the fields with the name should be used.
+.
+Also
+.B .\&
+can be used to indicate the references should be sorted using the
+(tentative) label.
+.
+(Subsection \(lqLabel expressions\(rq below describes the concept of a
+tentative label.)
+.
+.
+.TP
+.B sort-adjacent-labels\*n
+Sort labels that are adjacent in the text according to their position
+in the reference list.
+.
+This command should usually be given if the
+.B abbreviate-label-ranges
+command has been given,
+or if the label expression contains a
+.B <>
+expression.
+.
+This will have no effect unless references are being accumulated.
+.
+.
+.\" ====================================================================
+.SS Label expressions
+.\" ====================================================================
+.
+Label expressions can be evaluated both normally and tentatively.
+.
+The result of normal evaluation is used for output.
+.
+The result of tentative evaluation, called the
+.IR "tentative label" ,
+is used to gather the information that normal evaluation needs to
+disambiguate the label.
+.
+Label expressions specified by the
+.B date-as-label
+and
+.B short-label
+commands are not evaluated tentatively.
+.
+Normal and tentative evaluation are the same for all types of
+expression other than
+.BR @ ,
+.BR * ,
+and
+.B %
+expressions.
+.
+The description below applies to normal evaluation,
+except where otherwise specified.
+.
+.
+.TP
+.I field
+.TQ
+.I field\ n
+The
+.IR n -th
+part of
+.IR field .
+.
+If
+.I n
+is omitted, it defaults to\ 1.
+.
+.
+.TP
+.BI ' string '
+The characters in
+.I string
+literally.
+.
+.
+.TP
+.B @
+All the authors joined as specified by the
+.B join-authors
+command.
+.
+The whole of each author's name will be used.
+.
+However, if the references are sorted by author (that is the sort
+specification starts with
+.BR A+ ),
+then authors last names will be used instead,
+provided that this does not introduce ambiguity,
+and also an initial subsequence of the authors may be used instead of
+all the authors,
+again provided that this does not introduce ambiguity.
+.
+The use of only the last name for the
+.IR i -th
+author of some reference
+is considered to be ambiguous if
+there is some other reference,
+such that the first
+.IR i \|\-\|1
+authors of the references are the same,
+the
+.IR i -th
+authors are not the same,
+but the
+.IR i -th
+authors last names are the same.
+.
+A proper initial subsequence of the sequence of authors for some
+reference is considered to be ambiguous if there is a reference with
+some other sequence of authors which also has that subsequence as a
+proper initial subsequence.
+.
+When an initial subsequence of authors is used, the remaining authors
+are replaced by the string specified by the
+.B et-al
+command;
+this command may also specify additional requirements that must be
+met before an initial subsequence can be used.
+.
+.B @
+tentatively evaluates to a canonical representation of the authors,
+such that authors that compare equally for sorting purpose will have
+the same representation.
+.
+.
+.TP
+.BI % n
+.TQ
+.B %a
+.TQ
+.B %A
+.TQ
+.B %i
+.TQ
+.B %I
+The serial number of the reference formatted according to the
+character following the
+.BR % .
+The serial number of a reference is\ 1 plus the number of earlier
+references with same tentative label as this reference.
+.
+These expressions tentatively evaluate to an empty string.
+.
+.TP
+.IB expr *
+If there is another reference with the same tentative label as this
+reference,
+then
+.IR expr ,
+otherwise an empty string.
+.
+It tentatively evaluates to an empty string.
+.
+.
+.TP
+.IB expr + n
+.TQ
+.IB expr \- n
+The first
+.RB ( + )
+or last
+.RB ( \- )
+.I n
+upper or lower case letters or digits of
+.IR expr .
+.
+Troff special characters (such as
+.BR \e('a )
+count as a single letter.
+.
+Accent strings are retained but do not count towards the total.
+.
+.
+.TP
+.IB expr .l
+.I expr
+converted to lowercase.
+.
+.
+.TP
+.IB expr .u
+.I expr
+converted to uppercase.
+.
+.
+.TP
+.IB expr .c
+.I expr
+converted to caps and small caps.
+.
+.
+.TP
+.IB expr .r
+.I expr
+reversed so that the last name is first.
+.
+.
+.TP
+.IB expr .a
+.I expr
+with first names abbreviated.
+.
+Note that fields specified in the
+.B abbreviate
+command are abbreviated before any labels are evaluated.
+.
+Thus
+.B .a
+is useful only when you want a field to be abbreviated in a label
+but not in a reference.
+.
+.
+.TP
+.IB expr .y
+The year part of
+.IR expr .
+.
+.
+.TP
+.IB expr .+y
+The part of
+.I expr
+before the year,
+or the whole of
+.I expr
+if it does not contain a year.
+.
+.
+.TP
+.IB expr .\-y
+The part of
+.I expr
+after the year,
+or an empty string if
+.I expr
+does not contain a year.
+.
+.
+.TP
+.IB expr .n
+The last name part of
+.IR expr .
+.
+.
+.TP
+.IB expr1 \(ti expr2
+.I expr1
+except that if the last character of
+.I expr1
+is
+.B \-
+then it will be replaced by
+.IR expr2 .
+.
+.
+.TP
+.I expr1\ expr2
+The concatenation of
+.I expr1
+and
+.IR expr2 .
+.
+.
+.TP
+.IB expr1 | expr2
+If
+.I expr1
+is non-empty then
+.I expr1
+otherwise
+.IR expr2 .
+.
+.
+.TP
+.IB expr1 & expr2
+If
+.I expr1
+is non-empty
+then
+.I expr2
+otherwise an empty string.
+.
+.
+.TP
+.IB expr1 ? expr2 : expr3
+If
+.I expr1
+is non-empty
+then
+.I expr2
+otherwise
+.IR expr3 .
+.
+.
+.TP
+.BI < expr >
+The label is in two parts, which are separated by
+.IR expr .
+.
+Two adjacent two-part labels which have the same first part will be
+merged by appending the second part of the second label onto the first
+label separated by the string specified in the
+.B separate-label-second-parts
+command (initially,
+a comma followed by a space);
+the resulting label will also be a two-part label with the same first
+part as before merging,
+and so additional labels can be merged into it.
+.
+Note that it is permissible for the first part to be empty;
+this maybe desirable for expressions used in the
+.B short-label
+command.
+.
+.
+.TP
+.BI ( expr )
+The same as
+.IR expr .
+.
+Used for grouping.
+.
+.
+.LP
+The above expressions are listed in order of precedence
+(highest first);
+.B &
+and
+.B |
+have the same precedence.
+.
+.
+.\" ====================================================================
+.SS Macro interface
+.\" ====================================================================
+.
+Each reference starts with a call to the macro
+.BR ]- .
+.
+The string
+.B [F
+will be defined to be the label for this reference,
+unless the
+.B no-label-in-reference
+command has been given.
+.
+There then follows a series of string definitions,
+one for each field:
+string
+.BI [ X
+corresponds to field
+.IR X .
+.
+The number register
+.B [P
+is set to\ 1 if the
+.B P
+field contains a range of pages.
+.
+The
+.BR [T ,
+.B [A
+and
+.B [O
+number registers are set to\ 1 according as the
+.BR T ,
+.B A
+and
+.B O
+fields end with one of the characters
+.BR .?! .
+.
+The
+.B [E
+number register will be set to\ 1 if the
+.B [E
+string contains more than one name.
+.
+The reference is followed by a call to the
+.B ][
+macro.
+.
+The first argument to this macro gives a number representing
+the type of the reference.
+.
+If a reference contains a
+.B J
+field, it will be classified as type\ 1,
+otherwise if it contains a
+.B B
+field, it will type\ 3,
+otherwise if it contains a
+.B G
+or
+.B R
+field it will be type\ 4,
+otherwise if it contains an
+.B I
+field it will be type\ 2,
+otherwise it will be type\ 0.
+.
+The second argument is a symbolic name for the type:
+.BR other ,
+.BR journal-article ,
+.BR book ,
+.B article-in-book
+or
+.BR tech-report .
+.
+Groups of references that have been accumulated or are produced by the
+.B bibliography
+command are preceded by a call to the
+.B ]<
+macro and followed by a call to the
+.B ]>
+macro.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:dict/\:papers/\:Ind
+Default database.
+.
+.
+.TP
+.RI file .i
+Index files.
+.
+.
+.LP
+.B refer
+uses temporary files.
+.
+See the
+.BR groff (1)
+man page for details where such files are created.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I REFER
+If set, overrides the default database.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.BR indxbib (1),
+.BR lookbib (1),
+.BR lkbib (1)
+.br
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+In label expressions,
+.B <>
+expressions are ignored inside
+.BI . char
+expressions.
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/resolvectl.1 b/upstream/mageia-cauldron/man1/resolvectl.1
new file mode 100644
index 00000000..1a735d74
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/resolvectl.1
@@ -0,0 +1,727 @@
+'\" t
+.TH "RESOLVECTL" "1" "" "systemd 255" "resolvectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+resolvectl, resolvconf \- Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services; introspect and reconfigure the DNS resolver
+.SH "SYNOPSIS"
+.HP \w'\fBresolvectl\fR\ 'u
+\fBresolvectl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBresolvectl\fR
+may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource records and services with the
+\fBsystemd-resolved.service\fR(8)
+resolver service\&. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 and IPv6 addresses\&. If the parameters specified are formatted as IPv4 or IPv6 addresses the reverse operation is done, and a hostname is retrieved for the specified addresses\&.
+.PP
+The program\*(Aqs output contains information about the protocol used for the look\-up and on which network interface the data was discovered\&. It also contains information on whether the information could be authenticated\&. All data for which local DNSSEC validation succeeds is considered authenticated\&. Moreover all data originating from local, trusted sources is also reported authenticated, including resolution of the local host name, the
+"localhost"
+hostname or all data from
+/etc/hosts\&.
+.SH "COMMANDS"
+.PP
+\fBquery\fR \fIHOSTNAME|ADDRESS\fR\&...
+.RS 4
+Resolve domain names, as well as IPv4 and IPv6 addresses\&. When used in conjunction with
+\fB\-\-type=\fR
+or
+\fB\-\-class=\fR
+(see below), resolves low\-level DNS resource records\&.
+.sp
+If a single\-label domain name is specified it is searched for according to the configured search domains \(em unless
+\fB\-\-search=no\fR
+or
+\fB\-\-type=\fR/\fB\-\-class=\fR
+are specified, both of which turn this logic off\&.
+.sp
+If an international domain name is specified, it is automatically translated according to IDNA rules when resolved via classic DNS \(em but not for look\-ups via MulticastDNS or LLMNR\&. If
+\fB\-\-type=\fR/\fB\-\-class=\fR
+is used IDNA translation is turned off and domain names are processed as specified\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBservice\fR [[\fINAME\fR] \fITYPE\fR] \fIDOMAIN\fR
+.RS 4
+Resolve
+\m[blue]\fBRFC 6763 DNS\-SD\fR\m[]\&\s-2\u[1]\d\s+2
+and
+\m[blue]\fBRFC 2782 SRV\fR\m[]\&\s-2\u[2]\d\s+2
+services, depending on the specified list of parameters\&. If three parameters are passed the first is assumed to be the DNS\-SD service name, the second the
+\fBSRV\fR
+service type, and the third the domain to search in\&. In this case a full DNS\-SD style
+\fBSRV\fR
+and
+\fBTXT\fR
+lookup is executed\&. If only two parameters are specified, the first is assumed to be the
+\fBSRV\fR
+service type, and the second the domain to look in\&. In this case no
+\fBTXT\fR
+resource record is requested\&. Finally, if only one parameter is specified, it is assumed to be a domain name, that is already prefixed with an
+\fBSRV\fR
+type, and an
+\fBSRV\fR
+lookup is done (no
+\fBTXT\fR)\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBopenpgp\fR \fIEMAIL@DOMAIN\fR\&...
+.RS 4
+Query PGP keys stored as
+\fBOPENPGPKEY\fR
+resource records, see
+\m[blue]\fBRFC 7929\fR\m[]\&\s-2\u[3]\d\s+2\&. Specified e\-mail addresses are converted to the corresponding DNS domain name, and any
+\fBOPENPGPKEY\fR
+keys are printed\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBtlsa\fR [\fIFAMILY\fR] \fIDOMAIN\fR[:\fIPORT\fR]\&...
+.RS 4
+Query TLS public keys stored as
+\fBTLSA\fR
+resource records, see
+\m[blue]\fBRFC 6698\fR\m[]\&\s-2\u[4]\d\s+2\&. A query will be performed for each of the specified names prefixed with the port and family ("_\fIport\fR\&._\fIfamily\fR\&.\fIdomain\fR")\&. The port number may be specified after a colon (":"), otherwise
+\fB443\fR
+will be used by default\&. The family may be specified as the first argument, otherwise
+\fBtcp\fR
+will be used\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBstatus\fR [\fILINK\fR\&...]
+.RS 4
+Shows the global and per\-link DNS settings currently in effect\&. If no command is specified, this is the implied default\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBstatistics\fR
+.RS 4
+Shows general resolver statistics, including information whether DNSSEC is enabled and available, as well as resolution and validation statistics\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBreset\-statistics\fR
+.RS 4
+Resets the statistics counters shown in
+\fBstatistics\fR
+to zero\&. This operation requires root privileges\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBflush\-caches\fR
+.RS 4
+Flushes all DNS resource record caches the service maintains locally\&. This is mostly equivalent to sending the
+\fBSIGUSR2\fR
+to the
+\fBsystemd\-resolved\fR
+service\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBreset\-server\-features\fR
+.RS 4
+Flushes all feature level information the resolver learnt about specific servers, and ensures that the server feature probing logic is started from the beginning with the next look\-up request\&. This is mostly equivalent to sending the
+\fBSIGRTMIN+1\fR
+to the
+\fBsystemd\-resolved\fR
+service\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBdns\fR [\fILINK\fR [\fISERVER\fR\&...]], \fBdomain\fR [\fILINK\fR [\fIDOMAIN\fR\&...]], \fBdefault\-route\fR [\fILINK\fR [\fIBOOL\fR\&...]], \fBllmnr\fR [\fILINK\fR [\fIMODE\fR]], \fBmdns\fR [\fILINK\fR [\fIMODE\fR]], \fBdnssec\fR [\fILINK\fR [\fIMODE\fR]], \fBdnsovertls\fR [\fILINK\fR [\fIMODE\fR]], \fBnta\fR [\fILINK\fR [\fIDOMAIN\fR\&...]]
+.RS 4
+Get/set per\-interface DNS configuration\&. These commands may be used to configure various DNS settings for network interfaces\&. These commands may be used to inform
+\fBsystemd\-resolved\fR
+or
+\fBsystemd\-networkd\fR
+about per\-interface DNS configuration determined through external means\&. The
+\fBdns\fR
+command expects IPv4 or IPv6 address specifications of DNS servers to use\&. Each address can optionally take a port number separated with
+":", a network interface name or index separated with
+"%", and a Server Name Indication (SNI) separated with
+"#"\&. When IPv6 address is specified with a port number, then the address must be in the square brackets\&. That is, the acceptable full formats are
+"111\&.222\&.333\&.444:9953%ifname#example\&.com"
+for IPv4 and
+"[1111:2222::3333]:9953%ifname#example\&.com"
+for IPv6\&. The
+\fBdomain\fR
+command expects valid DNS domains, possibly prefixed with
+"~", and configures a per\-interface search or route\-only domain\&. The
+\fBdefault\-route\fR
+command expects a boolean parameter, and configures whether the link may be used as default route for DNS lookups, i\&.e\&. if it is suitable for lookups on domains no other link explicitly is configured for\&. The
+\fBllmnr\fR,
+\fBmdns\fR,
+\fBdnssec\fR
+and
+\fBdnsovertls\fR
+commands may be used to configure the per\-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings\&. Finally,
+\fBnta\fR
+command may be used to configure additional per\-interface DNSSEC NTA domains\&.
+.sp
+Commands
+\fBdns\fR,
+\fBdomain\fR
+and
+\fBnta\fR
+can take a single empty string argument to clear their respective value lists\&.
+.sp
+For details about these settings, their possible values and their effect, see the corresponding settings in
+\fBsystemd.network\fR(5)\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBrevert \fR\fB\fILINK\fR\fR
+.RS 4
+Revert the per\-interface DNS configuration\&. If the DNS configuration is reverted all per\-interface DNS setting are reset to their defaults, undoing all effects of
+\fBdns\fR,
+\fBdomain\fR,
+\fBdefault\-route\fR,
+\fBllmnr\fR,
+\fBmdns\fR,
+\fBdnssec\fR,
+\fBdnsovertls\fR,
+\fBnta\fR\&. Note that when a network interface disappears all configuration is lost automatically, an explicit reverting is not necessary in that case\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBmonitor\fR
+.RS 4
+Show a continuous stream of local client resolution queries and their responses\&. Whenever a local query is completed the query\*(Aqs DNS resource lookup key and resource records are shown\&. Note that this displays queries issued locally only, and does not immediately relate to DNS requests submitted to configured DNS servers or the LLMNR or MulticastDNS zones, as lookups may be answered from the local cache, or might result in multiple DNS transactions (for example to validate DNSSEC information)\&. If CNAME/CNAME redirection chains are followed, a separate query will be displayed for each element of the chain\&. Use
+\fB\-\-json=\fR
+to enable JSON output\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fBshow\-cache\fR
+.RS 4
+Show current cache content, per scope\&. Use
+\fB\-\-json=\fR
+to enable JSON output\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBshow\-server\-state\fR
+.RS 4
+Show detailed server state information, per DNS Server\&. Use
+\fB\-\-json=\fR
+to enable JSON output\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBlog\-level\fR [\fILEVEL\fR]
+.RS 4
+If no argument is given, print the current log level of the manager\&. If an optional argument
+\fILEVEL\fR
+is provided, then the command changes the current log level of the manager to
+\fILEVEL\fR
+(accepts the same values as
+\fB\-\-log\-level=\fR
+described in
+\fBsystemd\fR(1))\&.
+.sp
+Added in version 244\&.
+.RE
+.SH "OPTIONS"
+.PP
+\fB\-4\fR, \fB\-6\fR
+.RS 4
+By default, when resolving a hostname, both IPv4 and IPv6 addresses are acquired\&. By specifying
+\fB\-4\fR
+only IPv4 addresses are requested, by specifying
+\fB\-6\fR
+only IPv6 addresses are requested\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-i\fR \fIINTERFACE\fR, \fB\-\-interface=\fR\fIINTERFACE\fR
+.RS 4
+Specifies the network interface to execute the query on\&. This may either be specified as numeric interface index or as network interface string (e\&.g\&.
+"en0")\&. Note that this option has no effect if system\-wide DNS configuration (as configured in
+/etc/resolv\&.conf
+or
+/etc/systemd/resolved\&.conf) in place of per\-link configuration is used\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-p\fR \fIPROTOCOL\fR, \fB\-\-protocol=\fR\fIPROTOCOL\fR
+.RS 4
+Specifies the network protocol for the query\&. May be one of
+"dns"
+(i\&.e\&. classic unicast DNS),
+"llmnr"
+(\m[blue]\fBLink\-Local Multicast Name Resolution\fR\m[]\&\s-2\u[5]\d\s+2),
+"llmnr\-ipv4",
+"llmnr\-ipv6"
+(LLMNR via the indicated underlying IP protocols),
+"mdns"
+(\m[blue]\fBMulticast DNS\fR\m[]\&\s-2\u[6]\d\s+2),
+"mdns\-ipv4",
+"mdns\-ipv6"
+(MDNS via the indicated underlying IP protocols)\&. By default the lookup is done via all protocols suitable for the lookup\&. If used, limits the set of protocols that may be used\&. Use this option multiple times to enable resolving via multiple protocols at the same time\&. The setting
+"llmnr"
+is identical to specifying this switch once with
+"llmnr\-ipv4"
+and once via
+"llmnr\-ipv6"\&. Note that this option does not force the service to resolve the operation with the specified protocol, as that might require a suitable network interface and configuration\&. The special value
+"help"
+may be used to list known values\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-t\fR \fITYPE\fR, \fB\-\-type=\fR\fITYPE\fR, \fB\-c\fR \fICLASS\fR, \fB\-\-class=\fR\fICLASS\fR
+.RS 4
+When used in conjunction with the
+\fBquery\fR
+command, specifies the DNS resource record type (e\&.g\&.
+\fBA\fR,
+\fBAAAA\fR,
+\fBMX\fR, \&...) and class (e\&.g\&.
+\fBIN\fR,
+\fBANY\fR, \&...) to look up\&. If these options are used a DNS resource record set matching the specified class and type is requested\&. The class defaults to
+\fBIN\fR
+if only a type is specified\&. The special value
+"help"
+may be used to list known values\&.
+.sp
+Without these options
+\fBresolvectl query\fR
+provides high\-level domain name to address and address to domain name resolution\&. With these options it provides low\-level DNS resource record resolution\&. The search domain logic is automatically turned off when these options are used, i\&.e\&. specified domain names need to be fully qualified domain names\&. Moreover, IDNA internal domain name translation is turned off as well, i\&.e\&. international domain names should be specified in
+"xn\-\-\&..."
+notation, unless look\-up in MulticastDNS/LLMNR is desired, in which case UTF\-8 characters should be used\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-service\-address=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter\&. If true (the default), when doing a service lookup with
+\fB\-\-service\fR
+the hostnames contained in the
+\fBSRV\fR
+resource records are resolved as well\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-service\-txt=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter\&. If true (the default), when doing a DNS\-SD service lookup with
+\fB\-\-service\fR
+the
+\fBTXT\fR
+service metadata record is resolved as well\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-cname=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter\&. If true (the default), DNS
+\fBCNAME\fR
+or
+\fBDNAME\fR
+redirections are followed\&. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is returned\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-validate=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), DNSSEC validation is applied as usual \(em under the condition that it is enabled for the network and for
+systemd\-resolved\&.service
+as a whole\&. If false, DNSSEC validation is disabled for the specific query, regardless of whether it is enabled for the network or in the service\&. Note that setting this option to true does not force DNSSEC validation on systems/networks where DNSSEC is turned off\&. This option is only suitable to turn off such validation where otherwise enabled, not enable validation where otherwise disabled\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-synthesize=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), select domains are resolved on the local system, among them
+"localhost",
+"_gateway",
+"_outbound",
+"_localdnsstub"
+and
+"_localdnsproxy"
+or entries from
+/etc/hosts\&. If false these domains are not resolved locally, and either fail (in case of
+"localhost",
+"_gateway"
+or
+"_outbound"
+and suchlike) or go to the network via regular DNS/mDNS/LLMNR lookups (in case of
+/etc/hosts
+entries)\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-cache=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), lookups use the local DNS resource record cache\&. If false, lookups are routed to the network instead, regardless if already available in the local cache\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-zone=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), lookups are answered from locally registered LLMNR or mDNS resource records, if defined\&. If false, locally registered LLMNR/mDNS records are not considered for the lookup request\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-trust\-anchor=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), lookups for DS and DNSKEY are answered from the local DNSSEC trust anchors if possible\&. If false, the local trust store is not considered for the lookup request\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-network=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), lookups are answered via DNS, LLMNR or mDNS network requests if they cannot be synthesized locally, or be answered from the local cache, zone or trust anchors (see above)\&. If false, the request is not answered from the network and will thus fail if none of the indicated sources can answer them\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-search=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter\&. If true (the default), any specified single\-label hostnames will be searched in the domains configured in the search domain list, if it is non\-empty\&. Otherwise, the search domain logic is disabled\&. Note that this option has no effect if
+\fB\-\-type=\fR
+is used (see above), in which case the search domain logic is unconditionally turned off\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-raw\fR[=payload|packet]
+.RS 4
+Dump the answer as binary data\&. If there is no argument or if the argument is
+"payload", the payload of the packet is exported\&. If the argument is
+"packet", the whole packet is dumped in wire format, prefixed by length specified as a little\-endian 64\-bit number\&. This format allows multiple packets to be dumped and unambiguously parsed\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-legend=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter\&. If true (the default), column headers and meta information about the query response are shown\&. Otherwise, this output is suppressed\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-stale\-data=\fR\fIBOOL\fR
+.RS 4
+Takes a boolean parameter; used in conjunction with
+\fBquery\fR\&. If true (the default), lookups are answered with stale data (expired resource records) if possible\&. If false, the stale data is not considered for the lookup request\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.PP
+\fB\-j\fR
+.RS 4
+Short for
+\fB\-\-json=auto\fR
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "COMPATIBILITY WITH RESOLVCONF(8)"
+.PP
+\fBresolvectl\fR
+is a multi\-call binary\&. When invoked as
+"resolvconf"
+(generally achieved by means of a symbolic link of this name to the
+\fBresolvectl\fR
+binary) it is run in a limited
+\fBresolvconf\fR(8)
+compatibility mode\&. It accepts mostly the same arguments and pushes all data into
+\fBsystemd-resolved.service\fR(8), similar to how
+\fBdns\fR
+and
+\fBdomain\fR
+commands operate\&. Note that
+\fBsystemd\-resolved\&.service\fR
+is the only supported backend, which is different from other implementations of this command\&.
+.PP
+/etc/resolv\&.conf
+will only be updated with servers added with this command when
+/etc/resolv\&.conf
+is a symlink to
+/run/systemd/resolve/resolv\&.conf, and not a static file\&. See the discussion of
+/etc/resolv\&.conf
+handling in
+\fBsystemd-resolved.service\fR(8)\&.
+.PP
+Not all operations supported by other implementations are supported natively\&. Specifically:
+.PP
+\fB\-a\fR
+.RS 4
+Registers per\-interface DNS configuration data with
+\fBsystemd\-resolved\fR\&. Expects a network interface name as only command line argument\&. Reads
+\fBresolv.conf\fR(5)\-compatible DNS configuration data from its standard input\&. Relevant fields are
+"nameserver"
+and
+"domain"/"search"\&. This command is mostly identical to invoking
+\fBresolvectl\fR
+with a combination of
+\fBdns\fR
+and
+\fBdomain\fR
+commands\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-d\fR
+.RS 4
+Unregisters per\-interface DNS configuration data with
+\fBsystemd\-resolved\fR\&. This command is mostly identical to invoking
+\fBresolvectl revert\fR\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-f\fR
+.RS 4
+When specified
+\fB\-a\fR
+and
+\fB\-d\fR
+will not complain about missing network interfaces and will silently execute no operation in that case\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-x\fR
+.RS 4
+This switch for "exclusive" operation is supported only partially\&. It is mapped to an additional configured search domain of
+"~\&."
+\(em i\&.e\&. ensures that DNS traffic is preferably routed to the DNS servers on this interface, unless there are other, more specific domains configured on other interfaces\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-m\fR, \fB\-p\fR
+.RS 4
+These switches are not supported and are silently ignored\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-I\fR, \fB\-i\fR, \fB\-l\fR, \fB\-R\fR, \fB\-r\fR, \fB\-v\fR, \fB\-V\fR, \fB\-\-enable\-updates\fR, \fB\-\-disable\-updates\fR, \fB\-\-are\-updates\-enabled\fR
+.RS 4
+These switches are not supported and the command will fail if used\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+See
+\fBresolvconf\fR(8)
+for details on those command line options\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Retrieve the addresses of the "www\&.0pointer\&.net" domain (A and AAAA resource records)\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl query www\&.0pointer\&.net
+www\&.0pointer\&.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
+                  85\&.214\&.157\&.71
+
+\-\- Information acquired via protocol DNS in 611\&.6ms\&.
+\-\- Data is authenticated: no
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Retrieve the domain of the "85\&.214\&.157\&.71" IP address (PTR resource record)\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl query 85\&.214\&.157\&.71
+85\&.214\&.157\&.71: gardel\&.0pointer\&.net
+
+\-\- Information acquired via protocol DNS in 1\&.2997s\&.
+\-\- Data is authenticated: no
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&3.\ \&Retrieve the MX record of the "yahoo\&.com" domain\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl \-\-legend=no \-t MX query yahoo\&.com
+yahoo\&.com\&. IN MX    1 mta7\&.am0\&.yahoodns\&.net
+yahoo\&.com\&. IN MX    1 mta6\&.am0\&.yahoodns\&.net
+yahoo\&.com\&. IN MX    1 mta5\&.am0\&.yahoodns\&.net
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&4.\ \&Resolve an SRV service\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl service _xmpp\-server\&._tcp gmail\&.com
+_xmpp\-server\&._tcp/gmail\&.com: alt1\&.xmpp\-server\&.l\&.google\&.com:5269 [priority=20, weight=0]
+                             173\&.194\&.210\&.125
+                             alt4\&.xmpp\-server\&.l\&.google\&.com:5269 [priority=20, weight=0]
+                             173\&.194\&.65\&.125
+                             \&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&5.\ \&Retrieve a PGP key (OPENPGP resource record)\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl openpgp zbyszek@fedoraproject\&.org
+d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722\&._openpgpkey\&.fedoraproject\&.org\&. IN OPENPGPKEY
+        mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
+        MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
+        \&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&6.\ \&Retrieve a TLS key (TLSA resource record)\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ resolvectl tlsa tcp fedoraproject\&.org:443
+_443\&._tcp\&.fedoraproject\&.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
+        \-\- Cert\&. usage: CA constraint
+        \-\- Selector: Full Certificate
+        \-\- Matching type: SHA\-256
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+"tcp"
+and
+":443"
+are optional and could be skipped\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-resolved.service\fR(8),
+\fBsystemd.dnssd\fR(5),
+\fBsystemd-networkd.service\fR(8),
+\fBresolvconf\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+RFC 6763 DNS-SD
+.RS 4
+\%https://tools.ietf.org/html/rfc6763
+.RE
+.IP " 2." 4
+RFC 2782 SRV
+.RS 4
+\%https://tools.ietf.org/html/rfc2782
+.RE
+.IP " 3." 4
+RFC 7929
+.RS 4
+\%https://tools.ietf.org/html/rfc7929
+.RE
+.IP " 4." 4
+RFC 6698
+.RS 4
+\%https://tools.ietf.org/html/rfc6698
+.RE
+.IP " 5." 4
+Link-Local Multicast Name Resolution
+.RS 4
+\%https://tools.ietf.org/html/rfc4795
+.RE
+.IP " 6." 4
+Multicast DNS
+.RS 4
+\%https://www.ietf.org/rfc/rfc6762.txt
+.RE
diff --git a/upstream/mageia-cauldron/man1/rgb3toppm.1 b/upstream/mageia-cauldron/man1/rgb3toppm.1
new file mode 100644
index 00000000..6518ff46
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rgb3toppm.1
@@ -0,0 +1,63 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rgb3toppm User Manual" 0 "15 February 1990" "netpbm documentation"
+
+.SH NAME
+
+rgb3toppm - combine three PGM images (R, G, B) into one PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrgb3toppm\fP \fIredpgmfile\fP \fIgreenpgmfile\fP  \fIbluepgmfile\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrgb3toppm\fP reads three PGM images as input, taking each to
+represent one component (red, green, and blue) of a color image.  It
+produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBrgb3toppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtorgb3" (1)\c
+\&, 
+.BR "pamstack" (1)\c
+\&, 
+.BR "pgmtoppm" (1)\c
+\&, 
+.BR "ppmtopgm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rgb3toppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rlatopam.1 b/upstream/mageia-cauldron/man1/rlatopam.1
new file mode 100644
index 00000000..bf48117f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rlatopam.1
@@ -0,0 +1,67 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rlatopam User Manual" 0 "13 January 2006" "netpbm documentation"
+
+.SH NAME
+
+rlatopam - convert Alias/Wavefront RLA and RPF image files
+to PAM image files.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrlatopam\fP
+
+[\fIrlafile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrlatopam\fP converts an Alias RLA (run-length encoded type A)
+or RPF (rich pixel format) image to a PAM image file.  The output PAM
+file can be grayscale or RGB, with or without a transparency channel.
+.PP
+\fIrlafile\fP is the file name of the input file.  If you omit this
+parameter, \fBrlatopam\fP reads the image from Standard Input.
+.PP
+There is no program in Netpbm that converts the other direction.x
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBrlatopam\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBrlatopam\fP was new in Netpbm 10.32 (February 2006).
+
+.UN author
+.SH AUTHOR
+
+Simon Walton
+Matte World Digital
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rlatopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rletopnm.1 b/upstream/mageia-cauldron/man1/rletopnm.1
new file mode 100644
index 00000000..80c89513
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rletopnm.1
@@ -0,0 +1,157 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Rletopnm User Manual" 0 "13 April 2000" "netpbm documentation"
+
+.SH NAME
+rletopnm - convert a Utah Raster Tools RLE image file to a PNM image file.
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBrletopnm\fP
+
+[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fB--headerdump\fP|\fB-h\fP]
+
+[\fB--verbose\fP|\fB-v\fP]
+
+[\fIrlefile\fP|\fB-\fP]
+.PP
+All options may be abbreviated to their minimum unique abbreviation
+and options and arguments may be in any order.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBrletopnm\fP converts Utah Raster Toolkit RLE image files to PNM
+image files.  \fBrletopnm\fP handles four types of RLE files:
+Grayscale (8 bit data, no color map), Pseudocolor (8 bit data with a
+color map), Truecolor (24 bit data with color map), and Directcolor
+(24 bit data, no color map).  \fBrletopnm\fP generates a PPM file for
+all these cases except for the Grayscale file, for which
+\fBrletopnm\fP generates a PGM file.
+.PP
+\fIrlefile\fP is the RLE input file.  If it is absent or \fB-\fP,
+the input comes from Standard Input.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBrletopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB--alphaout=\fP\fIalpha-filename\fP
+\fBrletopnm \fP creates a PGM (portable graymap) file containing the
+transparency channel values in the input image.  If the input image doesn't
+contain an transparency channel, the \fIalpha-filename\fP file contains all
+zero (transparent) transparency values.  If you don't specify
+\fB--alphaout\fP, \fBrletopnm\fP does not generate a transparency file,
+and if the input image has a transparency channel, \fBrletopnm\fP simply
+discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBrletopnm\fP writes the
+transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+
+.TP
+\fB--verbose\fP
+This option causes \fBrletopnm \fP to operate in verbose mode.
+It prints messages about what it's doing, including the contents of
+the RLE image header, to Standard Error.
+
+.TP
+\fB--headerdump\fP
+This option causes \fBrletopnm\fP to operate in header dump mode.
+It prints the contents of the RLE image header to Standard Error, but
+does not produce any other output.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+
+.IP \(bu
+While running in verbose mode, convert lenna.rle to PPM format and
+store the resulting image as lenna.ppm:
+
+.nf
+\f(CW
+    rletopnm --verbose lenna.rle >lenna.ppm
+\fP
+
+.fi
+
+.IP \(bu
+Dump the header information of the RLE file called file.rle:
+
+.nf
+\f(CW
+    rletopnm --headerdump file.rle
+\fP
+
+.fi
+
+.IP \(bu
+Convert RLE file dart.rle to PPM format as dart.ppm.  Store the
+transparency channel of dart.rle as dartalpha.pgm (if dart.rle doesn't have
+a transparency channel, store a fully transparent transparency mask as
+dartalpha.pgm):
+
+.nf
+\f(CW
+    rletopnm --alphaout=dartalpha.pgm dart.rle >dart.ppm
+\fP
+
+.fi
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtorle" (1)\c
+\&,
+.BR "pnmconvol" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+
+.UN author
+.SH AUTHOR
+
+Wes Barris
+Army High Performance Computing Research Center (AHPCRC)
+Minnesota Supercomputer Center, Inc.
+.PP
+Modifications by Eric Haines to produce raw and plain formats.
+.PP
+Modifications by Bryan Henderson to create transparency files and use
+mnemonic options.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/rletopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/rlog.1 b/upstream/mageia-cauldron/man1/rlog.1
new file mode 100644
index 00000000..eab1174f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rlog.1
@@ -0,0 +1,377 @@
+.ds Rv 5.10.1
+.ds Dt 2022-08-17
+.ds i \&\s-1ISO\s0
+.ds r \&\s-1RCS\s0
+.ds u \&\s-1UTC\s0
+.ds o \*r file
+.if n .ds - \%--
+.if t .ds - \(em
+.TH RLOG 1 "\*(Dt" "GNU RCS \*(Rv"
+.SH NAME
+rlog \- print log messages and other information about \*os
+.SH SYNOPSIS
+.B rlog
+.RI [ " options " ] " file " .\|.\|.
+.SH DESCRIPTION
+.B rlog
+prints information about \*os.
+.PP
+Filenames matching an \*r suffix denote \*os;
+all others denote working files.
+Names are paired as explained in
+.BR ci (1).
+.PP
+.B rlog
+prints the following information for each
+\*o: \*o name, working file name, head (i.e., the number
+of the latest revision on the trunk), default branch, access list, locks,
+symbolic names, suffix, total number of revisions,
+number of revisions selected for printing, and
+descriptive text.  This is followed by entries for the selected revisions in
+reverse chronological order for each branch.  For each revision,
+.B rlog
+prints revision number, author, date/time, state, number of
+lines added/deleted (with respect to the previous revision),
+locker of the revision (if any), and log message.
+All times are displayed in Coordinated Universal Time (\*u) by default;
+this can be overridden with
+.BR \-z .
+Without options,
+.B rlog
+prints complete information.
+The options below restrict this output.
+.nr n \w'\f3\-V\fP\f2n\fP'+2n-1/1n
+.ds n \nn
+.if \n(.g .if r an-tag-sep .ds n \w'\f3\-V\fP\f2n\fP'u+\n[an-tag-sep]u
+.TP \*n
+.B \-L
+Ignore \*os that have no locks set.
+This is convenient in combination with
+.BR \-h ,
+.BR \-l ,
+and
+.BR \-R .
+.TP
+.B \-R
+Print only the name of the \*o.
+This is convenient for translating a
+working file name into an \*o name.
+.TP
+.B \-h
+Print only the \*o name, working file name, head,
+default branch, access list, locks,
+symbolic names, and suffix.
+.TP
+.B \-t
+Print the same as
+.BR \-h ,
+plus the descriptive text.
+.TP
+.B \-N
+Do not print the symbolic names.
+.TP
+.B \-b
+Print information about the revisions on the default branch, normally
+the highest branch on the trunk.
+.TP
+.BI \-d "dates"
+Print information about revisions with a checkin date/time in the ranges given by
+the semicolon-separated list of
+.IR dates .
+A range of the form
+.IB d1 < d2
+or
+.IB d2 > d1
+selects the revisions that were deposited between
+.I d1
+and
+.I d2
+exclusive.
+A range of the form
+.BI < d
+or
+.IB d >
+selects
+all revisions earlier than
+.IR d .
+A range of the form
+.IB d <
+or
+.BI > d
+selects
+all revisions dated later than
+.IR d .
+If
+.B <
+or
+.B >
+is followed by
+.B =
+then the ranges are inclusive, not exclusive.
+A range of the form
+.I d
+selects the single, latest revision dated
+.I d
+or earlier.
+The date/time strings
+.IR d ,
+.IR d1 ,
+and
+.I d2
+are in the free format explained in
+.BR co (1).
+Quoting is normally necessary, especially for
+.B <
+and
+.BR > .
+Note that the separator is
+a semicolon.
+.TP
+.BR \-l [\f2lockers\fP]
+Print information about locked revisions only.
+In addition, if the comma-separated list
+.I lockers
+of login names is given,
+ignore all locks other than those held by the
+.IR lockers .
+For example,
+.B "rlog\ \-L\ \-R\ \-lwft\ RCS/*"
+prints the name of \*os locked by the user
+.BR wft .
+.TP
+.BR \-r [\f2revisions\fP]
+prints information about revisions given in the comma-separated list
+.I revisions
+of revisions and ranges.
+A range
+.IB rev1 : rev2
+means revisions
+.I rev1
+to
+.I rev2
+on the same branch,
+.BI : rev
+means revisions from the beginning of the branch up to and including
+.IR rev ,
+and
+.IB rev :
+means revisions starting with
+.I rev
+to the end of the branch containing
+.IR rev .
+An argument that is a branch means all
+revisions on that branch.
+A range of branches means all revisions
+on the branches in that range.
+A branch followed by a
+.B .\&
+means the latest revision in that branch.
+A bare
+.B \-r
+with no
+.I revisions
+means the latest revision on the default branch, normally the trunk.
+.TP
+.BI \-s states
+prints information about revisions whose state attributes match one of the
+states given in the comma-separated list
+.IR states .
+.TP
+.BR \-w [\f2logins\fP]
+prints information about revisions checked in by users with
+login names appearing in the comma-separated list
+.IR logins .
+If
+.I logins
+is omitted, the user's login is assumed.
+.TP
+.B \-q
+This option has no effect;
+it is provided for consistency with other commands.
+.TP
+.B \-T
+This option has no effect;
+it is present for compatibility with other \*r commands.
+.TP
+.BI \-V
+Print \*r's version number.
+.TP
+.BI \-V n
+Emulate \*r version
+.I n
+when generating logs.
+See
+.BR co (1)
+for more.
+.TP
+.BI \-x "suffixes"
+Use
+.I suffixes
+to characterize \*os.
+See
+.BR ci (1)
+for details.
+.PP
+.B rlog
+prints the intersection of the revisions selected with
+the options
+.BR \-d ,
+.BR \-l ,
+.BR \-s ,
+and
+.BR \-w ,
+intersected
+with the union of the revisions selected by
+.B \-b
+and
+.BR \-r .
+.TP
+.BI \-z zone
+specifies the date output format,
+and specifies the default time zone for
+.I date
+in the
+.BI \-d dates
+option.
+The
+.I zone
+should be empty, a numeric \*u offset, or the special string
+.B LT
+for local time.
+The default is an empty
+.IR zone ,
+which uses the traditional \*r format of \*u without any time zone indication
+and with slashes separating the parts of the date;
+otherwise, times are output in \*i 8601 format with time zone indication.
+For example, if local time is January 11, 1990, 8pm Pacific Standard Time,
+eight hours west of \*u,
+then the time is output as follows:
+.RS
+.LP
+.RS
+.nf
+.ta \w'\f3\-z+05:30\fP  'u +\w'\f31990-01-11 09:30:00+05:30\fP  'u
+.ne 4
+\f2option\fP	\f2time output\fP
+\f3\-z\fP	\f31990/01/12 04:00:00\fP	\f2(default)\fP
+\f3\-zLT\fP	\f31990-01-11 20:00:00\-08\fP
+\f3\-z+05:30\fP	\f31990-01-12 09:30:00+05:30\fP
+.ta 4n +4n +4n +4n
+.fi
+.RE
+.SH EXAMPLES
+.LP
+.nf
+.B "    rlog  \-L  \-R  RCS/*"
+.B "    rlog  \-L  \-h  RCS/*"
+.B "    rlog  \-L  \-l  RCS/*"
+.B "    rlog  RCS/*"
+.fi
+.LP
+The first command prints the names of all \*os in the subdirectory
+.B RCS
+that have locks.  The second command prints the headers of those files,
+and the third prints the headers plus the log messages of the locked revisions.
+The last command prints complete information.
+.SH ENVIRONMENT
+.TP
+.B \s-1RCSINIT\s0
+Options prepended to the argument list, separated by spaces.
+A backslash escapes spaces within an option.
+The
+.B \s-1RCSINIT\s0
+options are prepended to the argument lists of most \*r commands.
+Useful
+.B \s-1RCSINIT\s0
+options include
+.BR \-q ,
+.BR \-V ,
+.BR \-x ,
+and
+.BR \-z .
+.TP
+.B \s-1RCS_MEM_LIMIT\s0
+Normally, for speed, commands either memory map or copy into memory
+the \*o if its size is less than the
+.IR memory-limit ,
+currently defaulting to ``unlimited''.
+Otherwise (or if the initially-tried speedy ways fail),
+the commands fall back to using
+standard i/o routines.
+You can adjust the memory limit by setting
+.B \s-1RCS_MEM_LIMIT\s0
+to a numeric value
+.IR lim
+(measured in kilobytes).
+An empty value is silently ignored.
+As a side effect, specifying
+.B \s-1RCS_MEM_LIMIT\s0
+inhibits fall-back to slower routines.
+.TP
+.B \s-1TMPDIR\s0
+Name of the temporary directory.
+If not set, the environment variables
+.B \s-1TMP\s0
+and
+.B \s-1TEMP\s0
+are inspected instead and the first value found is taken;
+if none of them are set,
+a host-dependent default is used, typically
+.BR /tmp .
+.SH DIAGNOSTICS
+The exit status is zero if and only if all operations were successful.
+.ds EY 1990, 1991, 1992, 1993, 1994, 1995
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Manual Page Revision: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 2010-2022 Thien-Thi Nguyen.
+.br
+Copyright \(co \*(EY Paul Eggert.
+.br
+Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
+.br
+.SH "SEE ALSO"
+.BR ci (1),
+.BR co (1),
+.BR ident (1),
+.BR rcs (1),
+.BR rcsdiff (1),
+.BR rcsmerge (1),
+.BR rcsfile (5).
+.PP
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.PP
+The full documentation for \*r is maintained as a Texinfo manual.
+If the
+.BR info (1)
+and \*r programs are properly installed at your site, the command
+.IP
+.B info rcs
+.PP
+should give you access to the complete manual.
+Additionally, the \*r homepage:
+.IP
+.B http://www.gnu.org/software/rcs/
+.PP
+has news and links to the latest release, development site, etc.
+.SH BUGS
+The separator for revision ranges in the
+.B \-r
+option used to be
+.B \-
+instead of
+.BR : ,
+but this leads to confusion when symbolic names contain
+.BR \- .
+For backwards compatibility
+.B "rlog \-r"
+still supports the old
+.B \-
+separator, but it warns about this obsolete use.
+.br
diff --git a/upstream/mageia-cauldron/man1/rm.1 b/upstream/mageia-cauldron/man1/rm.1
new file mode 100644
index 00000000..4e016c62
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rm.1
@@ -0,0 +1,108 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH RM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+rm \- remove files or directories
+.SH SYNOPSIS
+.B rm
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR rm .
+.B rm
+removes each specified file.  By default, it does not remove
+directories.
+.P
+If the \fI\-I\fR or \fI\-\-interactive=once\fR option is given,
+and there are more than three files or the \fI\-r\fR, \fI\-R\fR,
+or \fI\-\-recursive\fR are given, then
+.B rm
+prompts the user for whether to proceed with the entire operation.  If
+the response is not affirmative, the entire command is aborted.
+.P
+Otherwise, if a file is unwritable, standard input is a terminal, and
+the \fI\-f\fR or \fI\-\-force\fR option is not given, or the
+\fI\-i\fR or \fI\-\-interactive=always\fR option is given,
+.B rm
+prompts the user for whether to remove the file.  If the response is
+not affirmative, the file is skipped.
+.SH OPTIONS
+.PP
+Remove (unlink) the FILE(s).
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+ignore nonexistent files and arguments, never prompt
+.TP
+\fB\-i\fR
+prompt before every removal
+.TP
+\fB\-I\fR
+prompt once before removing more than three files, or
+when removing recursively; less intrusive than \fB\-i\fR,
+while still giving protection against most mistakes
+.TP
+\fB\-\-interactive\fR[=\fI\,WHEN\/\fR]
+prompt according to WHEN: never, once (\fB\-I\fR), or
+always (\fB\-i\fR); without WHEN, prompt always
+.TP
+\fB\-\-one\-file\-system\fR
+when removing a hierarchy recursively, skip any
+directory that is on a file system different from
+that of the corresponding command line argument
+.TP
+\fB\-\-no\-preserve\-root\fR
+do not treat '/' specially
+.TP
+\fB\-\-preserve\-root\fR[=\fI\,all\/\fR]
+do not remove '/' (default);
+with 'all', reject any command line argument
+on a separate device from its parent
+.TP
+\fB\-r\fR, \fB\-R\fR, \fB\-\-recursive\fR
+remove directories and their contents recursively
+.TP
+\fB\-d\fR, \fB\-\-dir\fR
+remove empty directories
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+explain what is being done
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+By default, rm does not remove directories.  Use the \fB\-\-recursive\fR (\fB\-r\fR or \fB\-R\fR)
+option to remove each listed directory, too, along with all of its contents.
+.PP
+To remove a file whose name starts with a '\-', for example '\-foo',
+use one of these commands:
+.IP
+rm \fB\-\-\fR \fB\-foo\fR
+.IP
+rm ./\-foo
+.PP
+Note that if you use rm to remove a file, it might be possible to recover
+some of its contents, given sufficient expertise and/or time.  For greater
+assurance that the contents are truly unrecoverable, consider using \fBshred\fP(1).
+.SH AUTHOR
+Written by Paul Rubin, David MacKenzie, Richard M. Stallman,
+and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBunlink\fP(1), \fBunlink\fP(2), \fBchattr\fP(1), \fBshred\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/rm>
+.br
+or available locally via: info \(aq(coreutils) rm invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/rman.1 b/upstream/mageia-cauldron/man1/rman.1
new file mode 100644
index 00000000..91e4c1e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rman.1
@@ -0,0 +1,273 @@
+.TH PolyglotMan 1
+.SH "NAME "
+PolyglotMan, rman - reverse compile man pages from formatted 
+form to a number of source formats 
+.SH "SYNOPSIS "
+rman [ \fIoptions \fR] [ \fIfile \fR] 
+.SH "DESCRIPTION "
+Up-to-date instructions can be found at
+http://polyglotman.sourceforge.net/rman.html
+
+.PP
+\fIPolyglotMan \fR takes man pages from most of the popular flavors 
+of UNIX and transforms them into any of a number of text source 
+formats. PolyglotMan was formerly known as RosettaMan. The name 
+of the binary is still called \fIrman \fR, for scripts that depend 
+on that name; mnemonically, just think "reverse man". Previously \fI
+PolyglotMan \fR required pages to be formatted by nroff prior 
+to its processing. With version 3.0, it \fIprefers [tn]roff source \fR
+and usually produces results that are better yet. And source 
+processing is the only way to translate tables. Source format 
+translation is not as mature as formatted, however, so try formatted 
+translation as a backup. 
+.PP
+In parsing [tn]roff source, one could implement an arbitrarily 
+large subset of [tn]roff, which I did not and will not do, so 
+the results can be off. I did implement a significant subset 
+of those use in man pages, however, including tbl (but not eqn), 
+if tests, and general macro definitions, so usually the results 
+look great. If they don't, format the page with nroff before 
+sending it to PolyglotMan. If PolyglotMan doesn't recognize a 
+key macro used by a large class of pages, however, e-mail me 
+the source and a uuencoded nroff-formatted page and I'll see 
+what I can do. When running PolyglotMan with man page source 
+that includes or redirects to other [tn]roff source using the .so (source 
+or inclusion) macro, you should be in the parent directory of 
+the page, since pages are written with this assumption. For example, 
+if you are translating /usr/man/man1/ls.1, first cd into /usr/man. 
+.PP
+\fIPolyglotMan \fR accepts man pages from: SunOS, Sun Solaris, 
+Hewlett-Packard HP-UX, AT&T System V, OSF/1 aka Digital UNIX, 
+DEC Ultrix, SGI IRIX, Linux, FreeBSD, SCO. Source processing 
+works for: SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System 
+V, OSF/1 aka Digital UNIX, DEC Ultrix. It can produce printable 
+ASCII-only (control characters stripped), section headers-only, 
+Tk, TkMan, [tn]roff (traditional man page source), SGML, HTML, 
+MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD. A modular architecture 
+permits easy addition of additional output formats. 
+.PP
+The latest version of PolyglotMan is available from \fI
+http://polyglotman.sourceforge.net/ \fR. 
+.SH "OPTIONS "
+The following options should not be used with any others and 
+exit PolyglotMan without processing any input. 
+.TP 15
+-h|--help 
+Show list of command line options and exit. 
+.TP 15
+-v|--version 
+Show version number and exit. 
+.PP
+\fIYou should specify the filter first, as this sets a number 
+of parameters, and then specify other options. 
+.TP 15
+-f|--filter <ASCII|roff|TkMan|Tk|Sections|HTML|SGML|MIME|LaTeX|LaTeX2e|RTF|POD> 
+Set the output filter. Defaults to ASCII. 
+.TP 15
+-S|--source 
+PolyglotMan tries to automatically determine whether its input 
+is source or formatted; use this option to declare source input. 
+.TP 15
+-F|--format|--formatted 
+PolyglotMan tries to automatically determine whether its input 
+is source or formatted; use this option to declare formatted 
+input. 
+.TP 15
+-l|--title \fIprintf-string \fR
+In HTML mode this sets the <TITLE> of the man pages, given the 
+same parameters as \fI-r \fR. 
+.TP 15
+-r|--reference|--manref \fIprintf-string \fR
+In HTML and SGML modes this sets the URL form by which to retrieve 
+other man pages. The string can use two supplied parameters: 
+the man page name and its section. (See the Examples section.) 
+If the string is null (as if set from a shell by "-r ''"), `-' 
+or `off', then man page references will not be HREFs, just set 
+in italics. If your printf supports XPG3 positions specifier, 
+this can be quite flexible. 
+.TP 15
+-V|--volumes \fI<colon-separated list> \fR
+Set the list of valid volumes to check against when looking for 
+cross-references to other man pages. Defaults to \fI1:2:3:4:5:6:7:8:9:o:l:n:p \fR(volume 
+names can be multicharacter). If an non-whitespace string in 
+the page is immediately followed by a left parenthesis, then 
+one of the valid volumes, and ends with optional other characters 
+and then a right parenthesis--then that string is reported as 
+a reference to another manual page. If this -V string starts 
+with an equals sign, then no optional characters are allowed 
+between the match to the list of valids and the right parenthesis. (This 
+option is needed for SCO UNIX.) 
+.PP
+The following options apply only when formatted pages are given 
+as input. They do not apply or are always handled correctly with 
+the source. 
+.TP 15
+-b|--subsections 
+Try to recognize subsection titles in addition to section titles. 
+This can cause problems on some UNIX flavors. 
+.TP 15
+-K|--nobreak 
+Indicate manual pages don't have page breaks, so don't look for 
+footers and headers around them. (Older nroff -man macros always 
+put in page breaks, but lately some vendors have realized that 
+printout are made through troff, whereas nroff -man is used to 
+format pages for reading on screen, and so have eliminated page 
+breaks.) \fIPolyglotMan \fR usually gets this right even without 
+this flag. 
+.TP 15
+-k|--keep 
+Keep headers and footers, as a canonical report at the end of 
+the page. changeleft 
+Move changebars, such as those found in the Tcl/Tk manual pages, 
+to the left. --> notaggressive 
+\fIDisable \fR aggressive man page parsing. Aggressive manual, 
+which is on by default, page parsing elides headers and footers, 
+identifies sections and more. --> 
+.TP 15
+-n|--name \fIname \fR
+Set name of man page (used in roff format). If the filename is 
+given in the form " \fIname \fR. \fIsection \fR", the name and 
+section are automatically determined. If the page is being parsed 
+from [tn]roff source and it has a .TH line, this information 
+is extracted from that line. 
+.TP 15
+-p|--paragraph 
+paragraph mode toggle. The filter determines whether lines should 
+be linebroken as they were by nroff, or whether lines should 
+be flowed together into paragraphs. Mainly for internal use. 
+.TP 15
+-s|section \fI# \fR
+Set volume (aka section) number of man page (used in roff format). 
+tables 
+Turn on aggressive table parsing. --> 
+.TP 15
+-t|--tabstops \fI# \fR
+For those macros sets that use tabs in place of spaces where 
+possible in order to reduce the number of characters used, set 
+tabstops every \fI# \fR columns. Defaults to 8. 
+.SH "NOTES ON FILTER TYPES "
+.SS "ROFF "
+Some flavors of UNIX ship man page without [tn]roff source, making 
+one's laser printer little more than a laser-powered daisy wheel. 
+This filer tries to intuit the original [tn]roff directives, 
+which can then be recompiled by [tn]roff. 
+.SS "TkMan "
+TkMan, a hypertext man page browser, uses \fIPolyglotMan \fR 
+to show man pages without the (usually) useless headers and footers 
+on each pages. It also collects section and (optionally) subsection 
+heads for direct access from a pulldown menu. TkMan and Tcl/Tk, 
+the toolkit in which it's written, are available via anonymous 
+ftp from \fIftp://ftp.smli.com/pub/tcl/ \fR
+.SS "Tk "
+This option outputs the text in a series of Tcl lists consisting 
+of text-tags pairs, where tag names roughly correspond to HTML. 
+This output can be inserted into a Tk text widget by doing an \fI
+eval <textwidget> insert end <text> \fR. This format should be 
+relatively easily parsible by other programs that want both the 
+text and the tags. Also see ASCII. 
+.SS "ASCII "
+When printed on a line printer, man pages try to produce special 
+text effects by overstriking characters with themselves (to produce 
+bold) and underscores (underlining). Other text processing software, 
+such as text editors, searchers, and indexers, must counteract 
+this. The ASCII filter strips away this formatting. Piping nroff 
+output through \fIcol -b \fR also strips away this formatting, 
+but it leaves behind unsightly page headers and footers. Also 
+see Tk. 
+.SS "Sections "
+Dumps section and (optionally) subsection titles. This might 
+be useful for another program that processes man pages. 
+.SS "HTML "
+With a simple extention to an HTTP server for Mosaic or other 
+World Wide Web browser, \fIPolyglotMan \fR can produce high quality 
+HTML on the fly. Several such extensions and pointers to several 
+others are included in \fIPolyglotMan \fR's \fIcontrib \fR directory. 
+.SS "SGML "
+This is appoaching the Docbook DTD, but I'm hoping that someone 
+that someone with a real interest in this will polish the tags 
+generated. Try it to see how close the tags are now. 
+.SS "MIME "
+MIME (Multipurpose Internet Mail Extensions) as defined by RFC 1563, 
+good for consumption by MIME-aware e-mailers or as Emacs (>=19.29) 
+enriched documents. 
+.SS "LaTeX and LaTeX2e "
+Why not? 
+.SS "RTF "
+Use output on Mac or NeXT or whatever. Maybe take random man 
+pages and integrate with NeXT's documentation system better. 
+Maybe NeXT has own man page macros that do this. 
+.SS "PostScript and FrameMaker "
+To produce PostScript, use \fIgroff \fR or \fIpsroff \fR. To 
+produce FrameMaker MIF, use FrameMaker's builtin filter. In both 
+cases you need \fI[tn]roff \fR source, so if you only have a 
+formatted version of the manual page, use \fIPolyglotMan \fR's 
+roff filter first. 
+.SH "EXAMPLES "
+To convert the \fIformatted \fR man page named \fIls.1 \fR back 
+into [tn]roff source form: 
+.PP
+\fIrman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1 \fR
+.br
+.PP
+Long man pages are often compressed to conserve space (compression 
+is especially effective on formatted man pages as many of the 
+characters are spaces). As it is a long man page, it probably 
+has subsections, which we try to separate out (some macro sets 
+don't distinguish subsections well enough for \fIPolyglotMan \fR
+to detect them). Let's convert this to LaTeX format: 
+.br
+.PP
+\fIpcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f 
+latex > automount.man \fR
+.br
+.PP
+Alternatively, \fIman 1 automount | rman -b -n automount -s 1 -f 
+latex > automount.man \fR
+.br
+.PP
+For HTML/Mosaic users, \fIPolyglotMan \fR can, without modification 
+of the source code, produce HTML links that point to other HTML 
+man pages either pregenerated or generated on the fly. First 
+let's assume pregenerated HTML versions of man pages stored in \fI/usr/man/html \fR. 
+Generate these one-by-one with the following form: 
+.br
+\fIrman -f html -r 'http:/usr/man/html/%s.%s.html' /usr/man/cat1/ls.1 > /usr/man/html/ls.1.html \fR
+.br
+.PP
+If you've extended your HTML client to generate HTML on the fly 
+you should use something like: 
+.br
+\fIrman -f html -r 'http:~/bin/man2html?%s:%s' /usr/man/cat1/ls.1 \fR
+.br
+when generating HTML. 
+.SH "BUGS/INCOMPATIBILITIES "
+\fIPolyglotMan \fR is not perfect in all cases, but it usually 
+does a good job, and in any case reduces the problem of converting 
+man pages to light editing. 
+.PP
+Tables in formatted pages, especially H-P's, aren't handled very 
+well. Be sure to pass in source for the page to recognize tables. 
+.PP
+The man pager \fIwoman \fR applies its own idea of formatting 
+for man pages, which can confuse \fIPolyglotMan \fR. Bypass \fI
+woman \fR by passing the formatted manual page text directly 
+into \fIPolyglotMan \fR. 
+.PP
+The [tn]roff output format uses fB to turn on boldface. If your 
+macro set requires .B, you'll have to a postprocess the \fIPolyglotMan \fR
+output. 
+.SH "SEE ALSO "
+\fItkman(1) \fR, \fIxman(1) \fR, \fIman(1) \fR, \fIman(7) \fR
+or \fIman(5) \fR depending on your flavor of UNIX 
+.SH "AUTHOR "
+PolyglotMan 
+.br
+by Thomas A. Phelps ( \fIphelps@ACM.org \fR) 
+.br
+developed at the 
+.br
+University of California, Berkeley 
+.br
+Computer Science Division 
+.PP
+Manual page last updated on $Date: 1998/07/13 09:47:28 $ 
diff --git a/upstream/mageia-cauldron/man1/rmdir.1 b/upstream/mageia-cauldron/man1/rmdir.1
new file mode 100644
index 00000000..f56f6335
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rmdir.1
@@ -0,0 +1,47 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH RMDIR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+rmdir \- remove empty directories
+.SH SYNOPSIS
+.B rmdir
+[\fI\,OPTION\/\fR]... \fI\,DIRECTORY\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Remove the DIRECTORY(ies), if they are empty.
+.TP
+\fB\-\-ignore\-fail\-on\-non\-empty\fR
+ignore each failure that is solely because a directory
+is non\-empty
+.TP
+\fB\-p\fR, \fB\-\-parents\fR
+remove DIRECTORY and its ancestors; e.g., 'rmdir \fB\-p\fR a/b/c'
+is similar to 'rmdir a/b/c a/b a'
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+output a diagnostic for every directory processed
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBrmdir\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/rmdir>
+.br
+or available locally via: info \(aq(coreutils) rmdir invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/rnano.1 b/upstream/mageia-cauldron/man1/rnano.1
new file mode 100644
index 00000000..27762bc6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rnano.1
@@ -0,0 +1,60 @@
+.\" Copyright (C) 2002-2007, 2014-2023 Free Software Foundation, Inc.
+.\"
+.\" This document is dual-licensed.  You may distribute and/or modify it
+.\" under the terms of either of the following licenses:
+.\"
+.\" * The GNU General Public License, as published by the Free Software
+.\"   Foundation, version 3 or (at your option) any later version.  You
+.\"   should have received a copy of the GNU General Public License
+.\"   along with this program.  If not, see
+.\"   <https://www.gnu.org/licenses/>.
+.\"
+.\" * The GNU Free Documentation License, as published by the Free
+.\"   Software Foundation, version 1.2 or (at your option) any later
+.\"   version, with no Invariant Sections, no Front-Cover Texts, and no
+.\"   Back-Cover Texts.  You should have received a copy of the GNU Free
+.\"   Documentation License along with this program.  If not, see
+.\"   <https://www.gnu.org/licenses/>.
+.\"
+.TH RNANO 1 "version 7.2" "January 2023"
+
+.SH NAME
+rnano \- a restricted nano
+
+.SH SYNOPSIS
+.B rnano
+.RI [ options "] [[+" line [, column "]]\ " file "]..."
+
+.SH DESCRIPTION
+\fBrnano\fR runs the \fBnano\fR editor in restricted mode.  This allows
+editing only the specified file or files, and doesn't allow the user
+access to the filesystem nor to a command shell.
+.sp
+In restricted mode, \fBnano\fR will:
+.IP \[bu] 2
+not allow suspending;
+.IP \[bu]
+not allow saving the current buffer under a different name;
+.IP \[bu]
+not allow inserting another file or opening a new buffer;
+.IP \[bu]
+not allow appending or prepending to any file;
+.IP \[bu]
+not make backup files nor do spell checking.
+
+.SH OPTIONS
+.TP
+.BR \-h ", " \-\-help
+Show the available command-line options and exit.
+.P
+For all existing options, see the \fBnano\fR(1) man page.
+
+.SH BUGS
+Please report bugs via
+.IR https://savannah.gnu.org/bugs/?group=nano .
+
+.SH HOMEPAGE
+.I https://nano-editor.org/
+
+.SH SEE ALSO
+.BR nano (1)
diff --git a/upstream/mageia-cauldron/man1/rot.1 b/upstream/mageia-cauldron/man1/rot.1
new file mode 100644
index 00000000..df466750
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rot.1
@@ -0,0 +1,104 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ROT 1"
+.TH ROT 1 "2014-03-30" "perl v5.34.1" "Mageia"
+.\" 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"
+rot \- Encrypts/decrypts using rot13
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+rot
+.PP
+(Accept standard input).
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+rot performs \s-1ROT13\s0 encryption/decryption from the standard input into
+the standard output. Note that it only handles \s-1ASCII\s0 properly.
+.PP
+For more information about \s-1ROT13,\s0 see:
+.IP "\(bu" 4
+<https://en.wikipedia.org/wiki/ROT13>
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+All options are ignored.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBfortune\fR
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+This man page was authored by Shlomi Fish, <http://www.shlomifish.org/> for
+the Mageia (<http://www.mageia.org/>) project. It is hereby placed under
+the \s-1MIT/X11\s0 licence (<http://opensource.org/licenses/mit\-license.php>).
diff --git a/upstream/mageia-cauldron/man1/rpdump.1 b/upstream/mageia-cauldron/man1/rpdump.1
new file mode 100644
index 00000000..0d24f3ff
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rpdump.1
@@ -0,0 +1,38 @@
+.TH rpdump 1
+.SH NAME
+rpdump \- alpine remote data utility
+.SH SYNTAX 
+
+.B rpdump
+[ -f ] -l Local_file -r Remote_folder
+.SH DESCRIPTION
+
+Rpdump may be used to copy the actual data from
+remote Alpine configuration files or address
+books into a local file.
+It is intended to be used by system administrators.
+Regular users should normally use the facilities provided within Alpine.
+.LP
+Local_file will normally be a local temporary file.
+Remote_folder is the IMAP folder being used as a remote Alpine configuration
+(with the help of Alpine's -P, -p, and -x commands or PINECONF, PINERC,
+and PINERCEX environment variables) or remote Alpine address book folder.
+A copy of the data from Remote_folder will be copied to Local_file.
+.IP \fB-f\fR 20
+Force the dump even if the remote folder is in an unrecognized format.
+.IP \fB-l\fR\ \fBLocal_file\fR 20
+The file on this system that is to be copied to.
+.IP \fB-r\fR\ \fBRemote_folder\fR 20
+A remote folder name to be copied from.
+See the Alpine documentation for the syntax of a remote folder name.
+One example is
+.br
+{my.imap.server}remote_pinerc.
+.SH DIAGNOSTICS
+Exit status is zero if all goes well, -1 otherwise.
+.SH "SEE ALSO"
+Rpload(1).
+.LP
+Copyright 1989-2007 by the University of Washington.
+
+$Date: 2005/01/14 20:40:14 $
diff --git a/upstream/mageia-cauldron/man1/rpload.1 b/upstream/mageia-cauldron/man1/rpload.1
new file mode 100644
index 00000000..f645a248
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rpload.1
@@ -0,0 +1,49 @@
+.TH rpload 1
+.SH NAME
+rpload \- alpine remote data utility
+.SH SYNTAX 
+
+.B rpload
+[ -f ] [ -s trimSize ] -t Type -l Local_file -r Remote_folder
+.SH DESCRIPTION
+
+Rpload may be used to convert local Alpine configuration files or address
+books into remote configurations or address books.
+It is intended to be used by system administrators.
+Regular users should normally use the facilities provided within Alpine.
+.LP
+Local_file will usually be a user's alpine configuration file, and
+Remote_folder is the IMAP folder which will be used
+(with the help of Alpine's \fB-p\fR, \fB-P\fR, and \fB-x\fR commands or
+PINECONF, PINERC, and PINERCEX environment variables)
+as the user's remote configuration folder.
+A copy of Local_file will be placed in the folder with the correct header
+lines to satisfy Alpine.
+.IP \fB-f\fR 20
+Force the load even if the remote folder is in the wrong format.
+This will \fBdelete\fR the contents of the folder so use it carefully.
+.IP \fB-s\fR\ \fBtrimSize\fR 20
+If the number of messages in the remote folder is more than one plus
+trimsize (one is for the header message), then messages 2, 3, and so on
+will be deleted until there are only one plus trimsize messages left.
+If this option is not set no trimming will be done.
+.IP \fB-t\fR\ \fBType\fR 20
+The possible Types are \fBpinerc\fR, \fBabook\fR, and \fBsig\fR.
+(Sig is mostly obsolete. Literal signatures contained within the remote
+pinerc should be used instead.)
+.IP \fB-l\fR\ \fBLocal_file\fR 20
+The file on this system that is to be copied.
+.IP \fB-r\fR\ \fBRemote_folder\fR 20
+A remote folder name to be copied to.
+See the Alpine documentation for the syntax of a remote folder name.
+One example is
+.br
+{my.imap.server}remote_pinerc.
+.SH DIAGNOSTICS
+Exit status is zero if all goes well, -1 otherwise.
+.SH "SEE ALSO"
+Rpdump(1).
+.LP
+Copyright 1989-2007 by the University of Washington.
+
+$Date: 2005/01/14 20:40:14 $
diff --git a/upstream/mageia-cauldron/man1/rpmdiff.1 b/upstream/mageia-cauldron/man1/rpmdiff.1
new file mode 100644
index 00000000..5f1fff73
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rpmdiff.1
@@ -0,0 +1,70 @@
+.\"
+.\" (C) Copyright 2014, Arturo Borrero Gonzalez <arturo@debian.org>,
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; 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 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH RPMDIFF 1 "February  6, 2014"
+
+.SH NAME
+rpmdiff \- search for differences between two RPM packages
+.SH SYNOPSIS
+.B rpmdiff
+.RI [<options>] " <old_RPM> <new_RPM>"
+.SH DESCRIPTION
+The \fBrpmdiff\fP tool shows differences between two RPM packages.
+
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with long
+options starting with two dashes (`-').
+.TP
+.B \-h, \-\-help
+Show summary of options.
+.TP
+.B \-i, \-\-ignore\fR=\fIproperty\fR
+File property to ignore when calculating differences (may be used
+multiple times).
+.br
+Valid values are:
+.nf
+ S (size)
+ M (mode)
+ 5 (checksum)
+ D (device)
+ N (inode)
+ L (number of links)
+ V (vflags)
+ U (user)
+ G (group)
+ F (digest)
+ T (time)
+.fi
+.SH SEE ALSO
+.BR rpmlint (1),
+.BR rpm (1)
+
+.SH AUTHOR
+Originally written by Frédéric Lepied, modified and maintained by
+numerous contributors since.
+.br
+This manual page was written by Arturo Borrero González
+<arturo@debian.org>, and is free/libre documentation
+(GPL-2+).
diff --git a/upstream/mageia-cauldron/man1/rpmlint.1 b/upstream/mageia-cauldron/man1/rpmlint.1
new file mode 100644
index 00000000..adfd40c7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rpmlint.1
@@ -0,0 +1,115 @@
+.TH RPMLINT "1" "April 2011" "rpmlint" "User Commands"
+.SH NAME
+rpmlint \- check common problems in rpm packages
+.SH SYNOPSIS
+\fBrpmlint\fR [\fIOPTION\fR]... [\fIFILE\fR|\fIPACKAGE\fR]...
+.SH DESCRIPTION
+\fBrpmlint\fR is a tool for checking common errors in rpm packages.
+It can be used to test individual packages and spec files before
+uploading or to check an entire distribution.  By default all
+applicable checks are processed but specific checks can be performed
+by using command line parameters.
+
+\fIFILE\fR can be a rpm package file, a spec file, or a directory.  In
+case of a directory, it is recursively searched for rpm and spec files
+to check.  The special value \fB\-\fR results in standard input being
+read and treated as (single) spec file content.
+\fIPACKAGE\fR is the name of an installed package or a
+.BR glob (7)
+pattern to match installed packages, unless a file by that name exists.
+.TP
+\fB\-i\fR, \fB\-\-info\fR
+Display explanations for reported messages.
+.TP
+\fB-I\fR, \fB\-\-explain\fR=\fImessageid\fR
+Display explanations for the specified message identifiers and exit.
+This option may be given multiple times.
+.TP
+\fB\-c\fR, \fB\-\-check\fR=\fIcheck\fR
+Run only the specified check.  This option may be given multiple times
+to specify multiple checks to run.  \fIcheck\fR is the name of the Python
+module (as it would be given to Python's import statement) containing the
+check.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+Check all installed packages.
+.TP
+\fB\-C\fR, \fB\-\-checkdir\fR=\fIdir\fR
+Insert \fIdir\fR to the front of the list of paths to load checks
+from, unless it is already in the list.  The default list of check
+dirs typically contains only /usr/share/rpmlint.  Directories in the
+check dirs list are also inserted to the front of the list of paths to
+load Python modules from when the check process begins.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display summary of command line options and exit.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Operate in verbose mode.
+.TP
+\fB\-E\fR, \fB\-\-extractdir\fR=\fIdir\fR
+Base directory for extracted temporary files, default is what Python's
+tempfile.gettempdir() returns.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Display version information and exit.
+.TP
+\fB\-n\fR, \fB\-\-noexception\fR
+Ignore output filters.
+.TP
+\fB\-\-rawout\fR=\fIfile\fR
+Write unfiltered output to \fIfile\fR.
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fIconffile\fR
+Load user configuration from the specified file, default is
+$XDG_CONFIG_HOME/rpmlint (~/.config/rpmlint if $XDG_CONFIG_HOME is
+empty or not set).
+.TP
+\fB\-o\fR, \fB\-\-option\fR=\fIvalue\fR
+Override a configuration option.  \fIvalue\fR is a whitespace separated string,
+first word of which is the option name to set, and the Python eval() return
+value for the rest is set as the value for the option.  Passing only an option
+name is treated as if None was passed as its value.  See the file "config"
+shipped with rpmlint for the list of configuration options and their types.
+For example:
+ \-o "NetworkEnabled True"
+ \-o "Distribution \(aqMy favorite distro\(aq"
+ \-o "MaxLineLength 80"
+ \-o "ValidShells (\(aq/bin/sh\(aq, \(aq/bin/bash\(aq)"
+.SH CAVEATS
+All checks do not apply to all argument types.  For best check
+coverage, run rpmlint on all source and binary packages your build
+produces.  The set of checks rpmlint runs on source packages is a
+superset of the one for plain specfiles, the set of checks run for
+installed binary packages is a superset of the one for uninstalled
+binary package files, and the source and binary package check sets are
+quite different.
+.SH FILES
+.TP
+\fB/usr/share/rpmlint/config\fR, \fB/usr/share/rpmlint/config.*\fR
+Built-in configuration.  When invoked as \fIsomeprefix\fR-rpmlint,
+/usr/share/rpmlint/config.\fIsomeprefix\fR is used if it exists,
+otherwise /usr/share/rpmlint/config.
+.TP
+\fB/etc/rpmlint/*config\fR
+System wide configuration.
+.TP
+\fB$XDG_CONFIG_HOME/rpmlint\fR or \fB~/.config/rpmlint\fR
+User configuration.
+.SH EXIT CODES
+.IP 0
+No errors.
+.IP 1
+Unspecified error.
+.IP 2
+Interrupted.
+.IP 64
+One or more error message printed.
+.IP 66
+Badness threshold exceeded.
+.SH AUTHOR
+Originally written by Frédéric Lepied, modified and maintained by
+numerous contributors since.
+.SH COPYRIGHT
+This program is licensed under the GNU General Public License, see the
+file COPYING included in the distribution archive.
diff --git a/upstream/mageia-cauldron/man1/rsync-ssl.1 b/upstream/mageia-cauldron/man1/rsync-ssl.1
new file mode 100644
index 00000000..c7f5ad1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rsync-ssl.1
@@ -0,0 +1,144 @@
+.TH "rsync-ssl" "1" "20 Oct 2022" "rsync-ssl from rsync 3.2.7" "User Commands"
+.\" prefix=/usr
+.P
+.SH "NAME"
+.P
+rsync-ssl \- a helper script for connecting to an ssl rsync daemon
+.P
+.SH "SYNOPSIS"
+.P
+.nf
+rsync-ssl [--type=SSL_TYPE] RSYNC_ARGS
+.fi
+.P
+The online version of this manpage (that includes cross-linking of topics)
+is available at https://download.samba.org/pub/rsync/rsync-ssl.1.
+.P
+.SH "DESCRIPTION"
+.P
+The rsync-ssl script helps you to run an rsync copy to/from an rsync daemon
+that requires ssl connections.
+.P
+The script requires that you specify an rsync-daemon arg in the style of either
+\fBhostname::\fP (with 2 colons) or \fBrsync://hostname/\fP.  The default port used for
+connecting is 874 (one higher than the normal 873) unless overridden in the
+environment.  You can specify an overriding port via \fB\-\-port\fP or by including
+it in the normal spot in the URL format, though both of those require your
+rsync version to be at least 3.2.0.
+.P
+.SH "OPTIONS"
+.P
+If the \fBfirst\fP arg is a \fB\-\-type=SSL_TYPE\fP option, the script will only use
+that particular program to open an ssl connection instead of trying to find an
+openssl or stunnel executable via a simple heuristic (assuming that the
+\fBRSYNC_SSL_TYPE\fP environment variable is not set as well\ \-\- see below).  This
+option must specify one of \fBopenssl\fP or \fBstunnel\fP.  The equal sign is
+required for this particular option.
+.P
+All the other options are passed through to the rsync command, so consult the
+\fBrsync\fP(1) manpage for more information on how it works.
+.P
+.SH "ENVIRONMENT VARIABLES"
+.P
+The ssl helper scripts are affected by the following environment variables:
+.P
+.IP "\fBRSYNC_SSL_TYPE\fP"
+Specifies the program type that should be used to open the ssl connection.
+It must be one of \fBopenssl\fP or \fBstunnel\fP.  The \fB\-\-type=SSL_TYPE\fP option
+overrides this, when specified.
+.IP "\fBRSYNC_SSL_PORT\fP"
+If specified, the value is the port number that is used as the default when
+the user does not specify a port in their rsync command.  When not
+specified, the default port number is 874.  (Note that older rsync versions
+(prior to 3.2.0) did not communicate an overriding port number value to the
+helper script.)
+.IP "\fBRSYNC_SSL_CERT\fP"
+If specified, the value is a filename that contains a certificate to use
+for the connection.
+.IP "\fBRSYNC_SSL_KEY\fP"
+If specified, the value is a filename that contains a key for the provided
+certificate to use for the connection.
+.IP "\fBRSYNC_SSL_CA_CERT\fP"
+If specified, the value is a filename that contains a certificate authority
+certificate that is used to validate the connection.
+.IP "\fBRSYNC_SSL_OPENSSL\fP"
+Specifies the openssl executable to run when the connection type is set to
+openssl.  If unspecified, the $PATH is searched for "openssl".
+.IP "\fBRSYNC_SSL_GNUTLS\fP"
+Specifies the gnutls-cli executable to run when the connection type is set
+to gnutls.  If unspecified, the $PATH is searched for "gnutls-cli".
+.IP "\fBRSYNC_SSL_STUNNEL\fP"
+Specifies the stunnel executable to run when the connection type is set to
+stunnel.  If unspecified, the $PATH is searched first for "stunnel4" and
+then for "stunnel".
+.P
+.SH "EXAMPLES"
+.RS 4
+.P
+.nf
+rsync-ssl -aiv example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl --type=openssl -aiv example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl -aiv --port 9874 example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl -aiv rsync://example.com:9874/mod/ dest
+.fi
+.RE
+.P
+.SH "THE SERVER SIDE"
+.P
+For help setting up an SSL/TLS supporting rsync, see the instructions in
+rsyncd.conf.
+.P
+.SH "SEE ALSO"
+.P
+\fBrsync\fP(1), \fBrsyncd.conf\fP(5)
+.P
+.SH "CAVEATS"
+.P
+Note that using an stunnel connection requires at least version 4 of stunnel,
+which should be the case on modern systems.  Also, it does not verify a
+connection against the CA certificate collection, so it only encrypts the
+connection without any cert validation unless you have specified the
+certificate environment options.
+.P
+This script also supports a \fB\-\-type=gnutls\fP option, but at the time of this
+release the gnutls-cli command was dropping output, making it unusable.  If
+that bug has been fixed in your version, feel free to put gnutls into an
+exported RSYNC_SSL_TYPE environment variable to make its use the default.
+.P
+.SH "BUGS"
+.P
+Please report bugs! See the web site at https://rsync.samba.org/.
+.P
+.SH "VERSION"
+.P
+This manpage is current for version 3.2.7 of rsync.
+.P
+.SH "CREDITS"
+.P
+Rsync is distributed under the GNU General Public License.  See the file
+COPYING for details.
+.P
+A web site is available at https://rsync.samba.org/.  The site includes an
+FAQ-O-Matic which may cover questions unanswered by this manual page.
+.P
+.SH "AUTHOR"
+.P
+This manpage was written by Wayne Davison.
+.P
+Mailing lists for support and development are available at
+https://lists.samba.org/.
diff --git a/upstream/mageia-cauldron/man1/rsync.1 b/upstream/mageia-cauldron/man1/rsync.1
new file mode 100644
index 00000000..0dcb1a6e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rsync.1
@@ -0,0 +1,5062 @@
+.TH "rsync" "1" "20 Oct 2022" "rsync 3.2.7" "User Commands"
+.\" prefix=/usr
+.P
+.SH "NAME"
+.P
+rsync \- a fast, versatile, remote (and local) file-copying tool
+.P
+.SH "SYNOPSIS"
+.P
+.nf
+Local:
+    rsync [OPTION...] SRC... [DEST]
+
+Access via remote shell:
+    Pull:
+        rsync [OPTION...] [USER@]HOST:SRC... [DEST]
+    Push:
+        rsync [OPTION...] SRC... [USER@]HOST:DEST
+
+Access via rsync daemon:
+    Pull:
+        rsync [OPTION...] [USER@]HOST::SRC... [DEST]
+        rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
+    Push:
+        rsync [OPTION...] SRC... [USER@]HOST::DEST
+        rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
+.fi
+.P
+Usages with just one SRC arg and no DEST arg will list the source files instead
+of copying.
+.P
+The online version of this manpage (that includes cross-linking of topics)
+is available at https://download.samba.org/pub/rsync/rsync.1.
+.P
+.SH "DESCRIPTION"
+.P
+Rsync is a fast and extraordinarily versatile file copying tool.  It can copy
+locally, to/from another host over any remote shell, or to/from a remote rsync
+daemon.  It offers a large number of options that control every aspect of its
+behavior and permit very flexible specification of the set of files to be
+copied.  It is famous for its delta-transfer algorithm, which reduces the
+amount of data sent over the network by sending only the differences between
+the source files and the existing files in the destination.  Rsync is widely
+used for backups and mirroring and as an improved copy command for everyday
+use.
+.P
+Rsync finds files that need to be transferred using a "quick check" algorithm
+(by default) that looks for files that have changed in size or in last-modified
+time.  Any changes in the other preserved attributes (as requested by options)
+are made on the destination file directly when the quick check indicates that
+the file's data does not need to be updated.
+.P
+Some of the additional features of rsync are:
+.P
+.IP o
+support for copying links, devices, owners, groups, and permissions
+.IP o
+exclude and exclude-from options similar to GNU tar
+.IP o
+a CVS exclude mode for ignoring the same files that CVS would ignore
+.IP o
+can use any transparent remote shell, including ssh or rsh
+.IP o
+does not require super-user privileges
+.IP o
+pipelining of file transfers to minimize latency costs
+.IP o
+support for anonymous or authenticated rsync daemons (ideal for mirroring)
+.P
+.SH "GENERAL"
+.P
+Rsync copies files either to or from a remote host, or locally on the current
+host (it does not support copying files between two remote hosts).
+.P
+There are two different ways for rsync to contact a remote system: using a
+remote-shell program as the transport (such as ssh or rsh) or contacting an
+rsync daemon directly via TCP.  The remote-shell transport is used whenever the
+source or destination path contains a single colon (:) separator after a host
+specification.  Contacting an rsync daemon directly happens when the source or
+destination path contains a double colon (::) separator after a host
+specification, OR when an rsync:// URL is specified (see also the USING
+RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION section for an
+exception to this latter rule).
+.P
+As a special case, if a single source arg is specified without a destination,
+the files are listed in an output format similar to "\fBls\ \-l\fP".
+.P
+As expected, if neither the source or destination path specify a remote host,
+the copy occurs locally (see also the \fB\-\-list-only\fP option).
+.P
+Rsync refers to the local side as the client and the remote side as the server.
+Don't confuse server with an rsync daemon.  A daemon is always a server, but a
+server can be either a daemon or a remote-shell spawned process.
+.P
+.SH "SETUP"
+.P
+See the file README.md for installation instructions.
+.P
+Once installed, you can use rsync to any machine that you can access via a
+remote shell (as well as some that you can access using the rsync daemon-mode
+protocol).  For remote transfers, a modern rsync uses ssh for its
+communications, but it may have been configured to use a different remote shell
+by default, such as rsh or remsh.
+.P
+You can also specify any remote shell you like, either by using the \fB\-e\fP
+command line option, or by setting the \fBRSYNC_RSH\fP environment variable.
+.P
+Note that rsync must be installed on both the source and destination machines.
+.P
+.SH "USAGE"
+.P
+You use rsync in the same way you use rcp.  You must specify a source and a
+destination, one of which may be remote.
+.P
+Perhaps the best way to explain the syntax is with some examples:
+.RS 4
+.P
+.nf
+rsync -t *.c foo:src/
+.fi
+.RE
+.P
+This would transfer all files matching the pattern \fB*.c\fP from the current
+directory to the directory src on the machine foo.  If any of the files already
+exist on the remote system then the rsync remote-update protocol is used to
+update the file by sending only the differences in the data.  Note that the
+expansion of wildcards on the command-line (\fB*.c\fP) into a list of files is
+handled by the shell before it runs rsync and not by rsync itself (exactly the
+same as all other Posix-style programs).
+.RS 4
+.P
+.nf
+rsync -avz foo:src/bar /data/tmp
+.fi
+.RE
+.P
+This would recursively transfer all files from the directory src/bar on the
+machine foo into the /data/tmp/bar directory on the local machine.  The files
+are transferred in archive mode, which ensures that symbolic links, devices,
+attributes, permissions, ownerships, etc. are preserved in the transfer.
+Additionally, compression will be used to reduce the size of data portions of
+the transfer.
+.RS 4
+.P
+.nf
+rsync -avz foo:src/bar/ /data/tmp
+.fi
+.RE
+.P
+A trailing slash on the source changes this behavior to avoid creating an
+additional directory level at the destination.  You can think of a trailing /
+on a source as meaning "copy the contents of this directory" as opposed to
+"copy the directory by name", but in both cases the attributes of the
+containing directory are transferred to the containing directory on the
+destination.  In other words, each of the following commands copies the files
+in the same way, including their setting of the attributes of /dest/foo:
+.RS 4
+.P
+.nf
+rsync -av /src/foo /dest
+rsync -av /src/foo/ /dest/foo
+.fi
+.RE
+.P
+Note also that host and module references don't require a trailing slash to
+copy the contents of the default directory.  For example, both of these copy
+the remote directory's contents into "/dest":
+.RS 4
+.P
+.nf
+rsync -av host: /dest
+rsync -av host::module /dest
+.fi
+.RE
+.P
+You can also use rsync in local-only mode, where both the source and
+destination don't have a ':' in the name.  In this case it behaves like an
+improved copy command.
+.P
+Finally, you can list all the (listable) modules available from a particular
+rsync daemon by leaving off the module name:
+.RS 4
+.P
+.nf
+rsync somehost.mydomain.com::
+.fi
+.RE
+.P
+.SH "COPYING TO A DIFFERENT NAME"
+.P
+When you want to copy a directory to a different name, use a trailing slash on
+the source directory to put the contents of the directory into any destination
+directory you like:
+.RS 4
+.P
+.nf
+rsync -ai foo/ bar/
+.fi
+.RE
+.P
+Rsync also has the ability to customize a destination file's name when copying
+a single item.  The rules for this are:
+.P
+.IP o
+The transfer list must consist of a single item (either a file or an empty
+directory)
+.IP o
+The final element of the destination path must not exist as a directory
+.IP o
+The destination path must not have been specified with a trailing slash
+.P
+Under those circumstances, rsync will set the name of the destination's single
+item to the last element of the destination path.  Keep in mind that it is best
+to only use this idiom when copying a file and use the above trailing-slash
+idiom when copying a directory.
+.P
+The following example copies the \fBfoo.c\fP file as \fBbar.c\fP in the \fBsave\fP dir
+(assuming that \fBbar.c\fP isn't a directory):
+.RS 4
+.P
+.nf
+rsync -ai src/foo.c save/bar.c
+.fi
+.RE
+.P
+The single-item copy rule might accidentally bite you if you unknowingly copy a
+single item and specify a destination dir that doesn't exist (without using a
+trailing slash).  For example, if \fBsrc/*.c\fP matches one file and \fBsave/dir\fP
+doesn't exist, this will confuse you by naming the destination file \fBsave/dir\fP:
+.RS 4
+.P
+.nf
+rsync -ai src/*.c save/dir
+.fi
+.RE
+.P
+To prevent such an accident, either make sure the destination dir exists or
+specify the destination path with a trailing slash:
+.RS 4
+.P
+.nf
+rsync -ai src/*.c save/dir/
+.fi
+.RE
+.P
+.SH "SORTED TRANSFER ORDER"
+.P
+Rsync always sorts the specified filenames into its internal transfer list.
+This handles the merging together of the contents of identically named
+directories, makes it easy to remove duplicate filenames. It can, however,
+confuse someone when the files are transferred in a different order than what
+was given on the command-line.
+.P
+If you need a particular file to be transferred prior to another, either
+separate the files into different rsync calls, or consider using
+\fB\-\-delay-updates\fP (which doesn't affect the sorted transfer order, but
+does make the final file-updating phase happen much more rapidly).
+.P
+.SH "MULTI-HOST SECURITY"
+.P
+Rsync takes steps to ensure that the file requests that are shared in a
+transfer are protected against various security issues.  Most of the potential
+problems arise on the receiving side where rsync takes steps to ensure that the
+list of files being transferred remains within the bounds of what was
+requested.
+.P
+Toward this end, rsync 3.1.2 and later have aborted when a file list contains
+an absolute or relative path that tries to escape out of the top of the
+transfer.  Also, beginning with version 3.2.5, rsync does two more safety
+checks of the file list to (1) ensure that no extra source arguments were added
+into the transfer other than those that the client requested and (2) ensure
+that the file list obeys the exclude rules that were sent to the sender.
+.P
+For those that don't yet have a 3.2.5 client rsync (or those that want to be
+extra careful), it is safest to do a copy into a dedicated destination
+directory for the remote files when you don't trust the remote host.  For
+example, instead of doing an rsync copy into your home directory:
+.RS 4
+.P
+.nf
+rsync -aiv host1:dir1 ~
+.fi
+.RE
+.P
+Dedicate a "host1-files" dir to the remote content:
+.RS 4
+.P
+.nf
+rsync -aiv host1:dir1 ~/host1-files
+.fi
+.RE
+.P
+See the \fB\-\-trust-sender\fP option for additional details.
+.P
+CAUTION: it is not particularly safe to use rsync to copy files from a
+case-preserving filesystem to a case-ignoring filesystem.  If you must perform
+such a copy, you should either disable symlinks via \fB\-\-no-links\fP or enable the
+munging of symlinks via \fB\-\-munge-links\fP (and make sure you use the
+right local or remote option).  This will prevent rsync from doing potentially
+dangerous things if a symlink name overlaps with a file or directory. It does
+not, however, ensure that you get a full copy of all the files (since that may
+not be possible when the names overlap). A potentially better solution is to
+list all the source files and create a safe list of filenames that you pass to
+the \fB\-\-files-from\fP option.  Any files that conflict in name would need
+to be copied to different destination directories using more than one copy.
+.P
+While a copy of a case-ignoring filesystem to a case-ignoring filesystem can
+work out fairly well, if no \fB\-\-delete-during\fP or \fB\-\-delete-before\fP option is
+active, rsync can potentially update an existing file on the receiveing side
+without noticing that the upper-/lower-case of the filename should be changed
+to match the sender.
+.P
+.SH "ADVANCED USAGE"
+.P
+The syntax for requesting multiple files from a remote host is done by
+specifying additional remote-host args in the same style as the first, or with
+the hostname omitted.  For instance, all these work:
+.RS 4
+.P
+.nf
+rsync -aiv host:file1 :file2 host:file{3,4} /dest/
+rsync -aiv host::modname/file{1,2} host::modname/extra /dest/
+rsync -aiv host::modname/first ::extra-file{1,2} /dest/
+.fi
+.RE
+.P
+Note that a daemon connection only supports accessing one module per copy
+command, so if the start of a follow-up path doesn't begin with the
+modname of the first path, it is assumed to be a path in the module (such as
+the extra-file1 & extra-file2 that are grabbed above).
+.P
+Really old versions of rsync (2.6.9 and before) only allowed specifying one
+remote-source arg, so some people have instead relied on the remote-shell
+performing space splitting to break up an arg into multiple paths. Such
+unintuitive behavior is no longer supported by default (though you can request
+it, as described below).
+.P
+Starting in 3.2.4, filenames are passed to a remote shell in such a way as to
+preserve the characters you give it. Thus, if you ask for a file with spaces
+in the name, that's what the remote rsync looks for:
+.RS 4
+.P
+.nf
+rsync -aiv host:'a simple file.pdf' /dest/
+.fi
+.RE
+.P
+If you use scripts that have been written to manually apply extra quoting to
+the remote rsync args (or to require remote arg splitting), you can ask rsync
+to let your script handle the extra escaping.  This is done by either adding
+the \fB\-\-old-args\fP option to the rsync runs in the script (which requires
+a new rsync) or exporting RSYNC_OLD_ARGS=1 and RSYNC_PROTECT_ARGS=0
+(which works with old or new rsync versions).
+.P
+.SH "CONNECTING TO AN RSYNC DAEMON"
+.P
+It is also possible to use rsync without a remote shell as the transport.  In
+this case you will directly connect to a remote rsync daemon, typically using
+TCP port 873. (This obviously requires the daemon to be running on the remote
+system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS
+section below for information on that.)
+.P
+Using rsync in this way is the same as using it with a remote shell except
+that:
+.P
+.IP o
+Use either double-colon syntax or rsync:// URL syntax instead of the
+single-colon (remote shell) syntax.
+.IP o
+The first element of the "path" is actually a module name.
+.IP o
+Additional remote source args can use an abbreviated syntax that omits the
+hostname and/or the module name, as discussed in ADVANCED USAGE.
+.IP o
+The remote daemon may print a "message of the day" when you connect.
+.IP o
+If you specify only the host (with no module or path) then a list of
+accessible modules on the daemon is output.
+.IP o
+If you specify a remote source path but no destination, a listing of the
+matching files on the remote daemon is output.
+.IP o
+The \fB\-\-rsh\fP (\fB\-e\fP) option must be omitted to avoid changing the
+connection style from using a socket connection to USING RSYNC-DAEMON
+FEATURES VIA A REMOTE-SHELL CONNECTION.
+.P
+An example that copies all the files in a remote module named "src":
+.RS 4
+.P
+.nf
+rsync -av host::src /dest
+.fi
+.RE
+.P
+Some modules on the remote daemon may require authentication.  If so, you will
+receive a password prompt when you connect.  You can avoid the password prompt
+by setting the environment variable \fBRSYNC_PASSWORD\fP to the password you
+want to use or using the \fB\-\-password-file\fP option.  This may be useful
+when scripting rsync.
+.P
+WARNING: On some systems environment variables are visible to all users.  On
+those systems using \fB\-\-password-file\fP is recommended.
+.P
+You may establish the connection via a web proxy by setting the environment
+variable \fBRSYNC_PROXY\fP to a hostname:port pair pointing to your web proxy.
+Note that your web proxy's configuration must support proxy connections to port
+873.
+.P
+You may also establish a daemon connection using a program as a proxy by
+setting the environment variable \fBRSYNC_CONNECT_PROG\fP to the commands you
+wish to run in place of making a direct socket connection.  The string may
+contain the escape "%H" to represent the hostname specified in the rsync
+command (so use "%%" if you need a single "%" in your string).  For example:
+.RS 4
+.P
+.nf
+export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
+rsync -av targethost1::module/src/ /dest/
+rsync -av rsync://targethost2/module/src/ /dest/
+.fi
+.RE
+.P
+The command specified above uses ssh to run nc (netcat) on a proxyhost, which
+forwards all data to port 873 (the rsync daemon) on the targethost (%H).
+.P
+Note also that if the \fBRSYNC_SHELL\fP environment variable is set, that
+program will be used to run the \fBRSYNC_CONNECT_PROG\fP command instead of using
+the default shell of the \fBsystem()\fP call.
+.P
+.SH "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION"
+.P
+It is sometimes useful to use various features of an rsync daemon (such as
+named modules) without actually allowing any new socket connections into a
+system (other than what is already required to allow remote-shell access).
+Rsync supports connecting to a host using a remote shell and then spawning a
+single-use "daemon" server that expects to read its config file in the home dir
+of the remote user.  This can be useful if you want to encrypt a daemon-style
+transfer's data, but since the daemon is started up fresh by the remote user,
+you may not be able to use features such as chroot or change the uid used by
+the daemon. (For another way to encrypt a daemon transfer, consider using ssh
+to tunnel a local port to a remote machine and configure a normal rsync daemon
+on that remote host to only allow connections from "localhost".)
+.P
+From the user's perspective, a daemon transfer via a remote-shell connection
+uses nearly the same command-line syntax as a normal rsync-daemon transfer,
+with the only exception being that you must explicitly set the remote shell
+program on the command-line with the \fB\-\-rsh=COMMAND\fP option. (Setting the
+RSYNC_RSH in the environment will not turn on this functionality.) For example:
+.RS 4
+.P
+.nf
+rsync -av --rsh=ssh host::module /dest
+.fi
+.RE
+.P
+If you need to specify a different remote-shell user, keep in mind that the
+user@ prefix in front of the host is specifying the rsync-user value (for a
+module that requires user-based authentication).  This means that you must give
+the '\-l user' option to ssh when specifying the remote-shell, as in this
+example that uses the short version of the \fB\-\-rsh\fP option:
+.RS 4
+.P
+.nf
+rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest
+.fi
+.RE
+.P
+The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to
+log-in to the "module".
+.P
+In this setup, the daemon is started by the ssh command that is accessing the
+system (which can be forced via the \fB~/.ssh/authorized_keys\fP file, if desired).
+However, when accessing a daemon directly, it needs to be started beforehand.
+.P
+.SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS"
+.P
+In order to connect to an rsync daemon, the remote system needs to have a
+daemon already running (or it needs to have configured something like inetd to
+spawn an rsync daemon for incoming connections on a particular port).  For full
+information on how to start a daemon that will handling incoming socket
+connections, see the \fBrsyncd.conf\fP(5) manpage\ \-\- that is
+the config file for the daemon, and it contains the full details for how to run
+the daemon (including stand-alone and inetd configurations).
+.P
+If you're using one of the remote-shell transports for the transfer, there is
+no need to manually start an rsync daemon.
+.P
+.SH "EXAMPLES"
+.P
+Here are some examples of how rsync can be used.
+.P
+To backup a home directory, which consists of large MS Word files and mail
+folders, a per-user cron job can be used that runs this each day:
+.RS 4
+.P
+.nf
+rsync -aiz . bkhost:backup/joe/
+.fi
+.RE
+.P
+To move some files from a remote host to the local host, you could run:
+.RS 4
+.P
+.nf
+rsync -aiv --remove-source-files rhost:/tmp/{file1,file2}.c ~/src/
+.fi
+.RE
+.P
+.SH "OPTION SUMMARY"
+.P
+Here is a short summary of the options available in rsync.  Each option also
+has its own detailed description later in this manpage.
+.P
+.nf
+--verbose, -v            increase verbosity
+--info=FLAGS             fine-grained informational verbosity
+--debug=FLAGS            fine-grained debug verbosity
+--stderr=e|a|c           change stderr output mode (default: errors)
+--quiet, -q              suppress non-error messages
+--no-motd                suppress daemon-mode MOTD
+--checksum, -c           skip based on checksum, not mod-time & size
+--archive, -a            archive mode is -rlptgoD (no -A,-X,-U,-N,-H)
+--no-OPTION              turn off an implied OPTION (e.g. --no-D)
+--recursive, -r          recurse into directories
+--relative, -R           use relative path names
+--no-implied-dirs        don't send implied dirs with --relative
+--backup, -b             make backups (see --suffix & --backup-dir)
+--backup-deleted         make backups only of deleted files
+--backup-dir=DIR         make backups into hierarchy based in DIR
+--backup-dir-dels=DIR    backup removed files into hierarchy based in DIR
+--suffix=SUFFIX          backup suffix (default ~ w/o --backup-dir)
+--suffix-dels=SUFFIX     set removed-files suffix (def. --suffix w/o b-d-d)
+--update, -u             skip files that are newer on the receiver
+--inplace                update destination files in-place
+--append                 append data onto shorter files
+--append-verify          --append w/old data in file checksum
+--dirs, -d               transfer directories without recursing
+--old-dirs, --old-d      works like --dirs when talking to old rsync
+--mkpath                 create destination's missing path components
+--links, -l              copy symlinks as symlinks
+--copy-links, -L         transform symlink into referent file/dir
+--copy-unsafe-links      only "unsafe" symlinks are transformed
+--safe-links             ignore symlinks that point outside the tree
+--munge-links            munge symlinks to make them safe & unusable
+--copy-dirlinks, -k      transform symlink to dir into referent dir
+--keep-dirlinks, -K      treat symlinked dir on receiver as dir
+--hard-links, -H         preserve hard links
+--perms, -p              preserve permissions
+--executability, -E      preserve executability
+--chmod=CHMOD            affect file and/or directory permissions
+--acls, -A               preserve ACLs (implies --perms)
+--xattrs, -X             preserve extended attributes
+--owner, -o              preserve owner (super-user only)
+--group, -g              preserve group
+--devices                preserve device files (super-user only)
+--copy-devices           copy device contents as a regular file
+--write-devices          write to devices as files (implies --inplace)
+--specials               preserve special files
+-D                       same as --devices --specials
+--times, -t              preserve modification times
+--atimes, -U             preserve access (use) times
+--open-noatime           avoid changing the atime on opened files
+--crtimes, -N            preserve create times (newness)
+--omit-dir-times, -O     omit directories from --times
+--omit-link-times, -J    omit symlinks from --times
+--super                  receiver attempts super-user activities
+--fake-super             store/recover privileged attrs using xattrs
+--sparse, -S             turn sequences of nulls into sparse blocks
+--preallocate            allocate dest files before writing them
+--dry-run, -n            perform a trial run with no changes made
+--whole-file, -W         copy files whole (w/o delta-xfer algorithm)
+--checksum-choice=STR    choose the checksum algorithm (aka --cc)
+--one-file-system, -x    don't cross filesystem boundaries
+--block-size=SIZE, -B    force a fixed checksum block-size
+--rsh=COMMAND, -e        specify the remote shell to use
+--rsync-path=PROGRAM     specify the rsync to run on remote machine
+--existing               skip creating new files on receiver
+--ignore-existing        skip updating files that exist on receiver
+--remove-source-files    sender removes synchronized files (non-dir)
+--del                    an alias for --delete-during
+--delete                 delete extraneous files from dest dirs
+--delete-before          receiver deletes before xfer, not during
+--delete-during          receiver deletes during the transfer
+--delete-delay           find deletions during, delete after
+--delete-after           receiver deletes after transfer, not during
+--delete-excluded        also delete excluded files from dest dirs
+--ignore-missing-args    ignore missing source args without error
+--delete-missing-args    delete missing source args from destination
+--ignore-errors          delete even if there are I/O errors
+--force                  force deletion of dirs even if not empty
+--max-delete=NUM         don't delete more than NUM files
+--max-size=SIZE          don't transfer any file larger than SIZE
+--min-size=SIZE          don't transfer any file smaller than SIZE
+--max-alloc=SIZE         change a limit relating to memory alloc
+--partial                keep partially transferred files
+--partial-dir=DIR        put a partially transferred file into DIR
+--delay-updates          put all updated files into place at end
+--prune-empty-dirs, -m   prune empty directory chains from file-list
+--numeric-ids            don't map uid/gid values by user/group name
+--usermap=STRING         custom username mapping
+--groupmap=STRING        custom groupname mapping
+--chown=USER:GROUP       simple username/groupname mapping
+--timeout=SECONDS        set I/O timeout in seconds
+--contimeout=SECONDS     set daemon connection timeout in seconds
+--ignore-times, -I       don't skip files that match size and time
+--size-only              skip files that match in size
+--modify-window=NUM, -@  set the accuracy for mod-time comparisons
+--temp-dir=DIR, -T       create temporary files in directory DIR
+--fuzzy, -y              find similar file for basis if no dest file
+--compare-dest=DIR       also compare destination files relative to DIR
+--copy-dest=DIR          ... and include copies of unchanged files
+--link-dest=DIR          hardlink to files in DIR when unchanged
+--compress, -z           compress file data during the transfer
+--compress-choice=STR    choose the compression algorithm (aka --zc)
+--compress-level=NUM     explicitly set compression level (aka --zl)
+--skip-compress=LIST     skip compressing files with suffix in LIST
+--cvs-exclude, -C        auto-ignore files in the same way CVS does
+--filter=RULE, -f        add a file-filtering RULE
+-F                       same as --filter='dir-merge /.rsync-filter'
+                         repeated: --filter='- .rsync-filter'
+--exclude=PATTERN        exclude files matching PATTERN
+--exclude-from=FILE      read exclude patterns from FILE
+--include=PATTERN        don't exclude files matching PATTERN
+--include-from=FILE      read include patterns from FILE
+--files-from=FILE        read list of source-file names from FILE
+--from0, -0              all *-from/filter files are delimited by 0s
+--old-args               disable the modern arg-protection idiom
+--secluded-args, -s      use the protocol to safely send the args
+--trust-sender           trust the remote sender's file list
+--copy-as=USER[:GROUP]   specify user & optional group for the copy
+--address=ADDRESS        bind address for outgoing socket to daemon
+--port=PORT              specify double-colon alternate port number
+--sockopts=OPTIONS       specify custom TCP options
+--blocking-io            use blocking I/O for the remote shell
+--outbuf=N|L|B           set out buffering to None, Line, or Block
+--stats                  give some file-transfer stats
+--8-bit-output, -8       leave high-bit chars unescaped in output
+--human-readable, -h     output numbers in a human-readable format
+--progress               show progress during transfer
+-P                       same as --partial --progress
+--itemize-changes, -i    output a change-summary for all updates
+--remote-option=OPT, -M  send OPTION to the remote side only
+--out-format=FORMAT      output updates using the specified FORMAT
+--log-file=FILE          log what we're doing to the specified FILE
+--log-file-format=FMT    log updates using the specified FMT
+--password-file=FILE     read daemon-access password from FILE
+--early-input=FILE       use FILE for daemon's early exec input
+--list-only              list the files instead of copying them
+--bwlimit=RATE           limit socket I/O bandwidth
+--stop-after=MINS        Stop rsync after MINS minutes have elapsed
+--stop-at=y-m-dTh:m      Stop rsync at the specified point in time
+--fsync                  fsync every written file
+--write-batch=FILE       write a batched update to FILE
+--only-write-batch=FILE  like --write-batch but w/o updating dest
+--read-batch=FILE        read a batched update from FILE
+--protocol=NUM           force an older protocol version to be used
+--iconv=CONVERT_SPEC     request charset conversion of filenames
+--checksum-seed=NUM      set block/file checksum seed (advanced)
+--ipv4, -4               prefer IPv4
+--ipv6, -6               prefer IPv6
+--version, -V            print the version + other info and exit
+--help, -h (*)           show this help (* -h is help only on its own)
+.fi
+.P
+Rsync can also be run as a daemon, in which case the following options are
+accepted:
+.P
+.nf
+--daemon                 run as an rsync daemon
+--address=ADDRESS        bind to the specified address
+--bwlimit=RATE           limit socket I/O bandwidth
+--config=FILE            specify alternate rsyncd.conf file
+--dparam=OVERRIDE, -M    override global daemon config parameter
+--no-detach              do not detach from the parent
+--port=PORT              listen on alternate port number
+--log-file=FILE          override the "log file" setting
+--log-file-format=FMT    override the "log format" setting
+--sockopts=OPTIONS       specify custom TCP options
+--verbose, -v            increase verbosity
+--ipv4, -4               prefer IPv4
+--ipv6, -6               prefer IPv6
+--help, -h               show this help (when used with --daemon)
+.fi
+.P
+.SH "OPTIONS"
+.P
+Rsync accepts both long (double-dash + word) and short (single-dash + letter)
+options.  The full list of the available options are described below.  If an
+option can be specified in more than one way, the choices are comma-separated.
+Some options only have a long variant, not a short.
+.P
+If the option takes a parameter, the parameter is only listed after the long
+variant, even though it must also be specified for the short.  When specifying
+a parameter, you can either use the form \fB\-\-option=param\fP, \fB\-\-option\ param\fP,
+\fB\-o=param\fP, \fB\-o\ param\fP, or \fB\-oparam\fP (the latter choices assume that your
+option has a short variant).
+.P
+The parameter may need to be quoted in some manner for it to survive the
+shell's command-line parsing.  Also keep in mind that a leading tilde (\fB~\fP) in
+a pathname is substituted by your shell, so make sure that you separate the
+option name from the pathname using a space if you want the local shell to
+expand it.
+.P
+.IP "\fB\-\-help\fP"
+Print a short help page describing the options available in rsync and exit.
+You can also use \fB\-h\fP for \fB\-\-help\fP when it is used without any other
+options (since it normally means \fB\-\-human-readable\fP).
+.IP "\fB\-\-version\fP, \fB\-V\fP"
+Print the rsync version plus other info and exit.  When repeated, the
+information is output is a JSON format that is still fairly readable
+(client side only).
+.IP
+The output includes a list of compiled-in capabilities, a list of
+optimizations, the default list of checksum algorithms, the default list of
+compression algorithms, the default list of daemon auth digests, a link to
+the rsync web site, and a few other items.
+.IP "\fB\-\-verbose\fP, \fB\-v\fP"
+This option increases the amount of information you are given during the
+transfer.  By default, rsync works silently.  A single \fB\-v\fP will give you
+information about what files are being transferred and a brief summary at
+the end.  Two \fB\-v\fP options will give you information on what files are
+being skipped and slightly more information at the end.  More than two \fB\-v\fP
+options should only be used if you are debugging rsync.
+.IP
+The end-of-run summary tells you the number of bytes sent to the remote
+rsync (which is the receiving side on a local copy), the number of bytes
+received from the remote host, and the average bytes per second of the
+transferred data computed over the entire length of the rsync run. The
+second line shows the total size (in bytes), which is the sum of all the
+file sizes that rsync considered transferring.  It also shows a "speedup"
+value, which is a ratio of the total file size divided by the sum of the
+sent and received bytes (which is really just a feel-good bigger-is-better
+number).  Note that these byte values can be made more (or less)
+human-readable by using the \fB\-\-human-readable\fP (or
+\fB\-\-no-human-readable\fP) options.
+.IP
+In a modern rsync, the \fB\-v\fP option is equivalent to the setting of groups
+of \fB\-\-info\fP and \fB\-\-debug\fP options.  You can choose to use
+these newer options in addition to, or in place of using \fB\-\-verbose\fP, as
+any fine-grained settings override the implied settings of \fB\-v\fP.  Both
+\fB\-\-info\fP and \fB\-\-debug\fP have a way to ask for help that
+tells you exactly what flags are set for each increase in verbosity.
+.IP
+However, do keep in mind that a daemon's "\fBmax\ verbosity\fP" setting will limit
+how high of a level the various individual flags can be set on the daemon
+side.  For instance, if the max is 2, then any info and/or debug flag that
+is set to a higher value than what would be set by \fB\-vv\fP will be downgraded
+to the \fB\-vv\fP level in the daemon's logging.
+.IP "\fB\-\-info=FLAGS\fP"
+This option lets you have fine-grained control over the information output
+you want to see.  An individual flag name may be followed by a level
+number, with 0 meaning to silence that output, 1 being the default output
+level, and higher numbers increasing the output of that flag (for those
+that support higher levels).  Use \fB\-\-info=help\fP to see all the available
+flag names, what they output, and what flag names are added for each
+increase in the verbose level.  Some examples:
+.RS 4
+.IP
+.nf
+rsync -a --info=progress2 src/ dest/
+rsync -avv --info=stats2,misc1,flist0 src/ dest/
+.fi
+.RE
+.IP
+Note that \fB\-\-info=name\fP's output is affected by the \fB\-\-out-format\fP
+and \fB\-\-itemize-changes\fP (\fB\-i\fP) options.  See those options for more
+information on what is output and when.
+.IP
+This option was added to 3.1.0, so an older rsync on the server side might
+reject your attempts at fine-grained control (if one or more flags needed
+to be send to the server and the server was too old to understand them).
+See also the "\fBmax\ verbosity\fP" caveat above when dealing with a daemon.
+.IP "\fB\-\-debug=FLAGS\fP"
+This option lets you have fine-grained control over the debug output you
+want to see.  An individual flag name may be followed by a level number,
+with 0 meaning to silence that output, 1 being the default output level,
+and higher numbers increasing the output of that flag (for those that
+support higher levels).  Use \fB\-\-debug=help\fP to see all the available flag
+names, what they output, and what flag names are added for each increase in
+the verbose level.  Some examples:
+.RS 4
+.IP
+.nf
+rsync -avvv --debug=none src/ dest/
+rsync -avA --del --debug=del2,acl src/ dest/
+.fi
+.RE
+.IP
+Note that some debug messages will only be output when the \fB\-\-stderr=all\fP
+option is specified, especially those pertaining to I/O and buffer debugging.
+.IP
+Beginning in 3.2.0, this option is no longer auto-forwarded to the server
+side in order to allow you to specify different debug values for each side
+of the transfer, as well as to specify a new debug option that is only
+present in one of the rsync versions.  If you want to duplicate the same
+option on both sides, using brace expansion is an easy way to save you some
+typing.  This works in zsh and bash:
+.RS 4
+.IP
+.nf
+rsync -aiv {-M,}--debug=del2 src/ dest/
+.fi
+.RE
+.IP "\fB\-\-stderr=errors|all|client\fP"
+This option controls which processes output to stderr and if info messages
+are also changed to stderr.  The mode strings can be abbreviated, so feel
+free to use a single letter value.  The 3 possible choices are:
+.IP
+.RS
+.IP o
+\fBerrors\fP \- (the default) causes all the rsync processes to send an
+error directly to stderr, even if the process is on the remote side of
+the transfer.  Info messages are sent to the client side via the protocol
+stream.  If stderr is not available (i.e. when directly connecting with a
+daemon via a socket) errors fall back to being sent via the protocol
+stream.
+.IP o
+\fBall\fP \- causes all rsync messages (info and error) to get written
+directly to stderr from all (possible) processes.  This causes stderr to
+become line-buffered (instead of raw) and eliminates the ability to
+divide up the info and error messages by file handle.  For those doing
+debugging or using several levels of verbosity, this option can help to
+avoid clogging up the transfer stream (which should prevent any chance of
+a deadlock bug hanging things up).  It also allows \fB\-\-debug\fP to
+enable some extra I/O related messages.
+.IP o
+\fBclient\fP \- causes all rsync messages to be sent to the client side
+via the protocol stream.  One client process outputs all messages, with
+errors on stderr and info messages on stdout.  This \fBwas\fP the default
+in older rsync versions, but can cause error delays when a lot of
+transfer data is ahead of the messages.  If you're pushing files to an
+older rsync, you may want to use \fB\-\-stderr=all\fP since that idiom has
+been around for several releases.
+.RE
+.IP
+This option was added in rsync 3.2.3.  This version also began the
+forwarding of a non-default setting to the remote side, though rsync uses
+the backward-compatible options \fB\-\-msgs2stderr\fP and \fB\-\-no-msgs2stderr\fP to
+represent the \fBall\fP and \fBclient\fP settings, respectively.  A newer rsync
+will continue to accept these older option names to maintain compatibility.
+.IP "\fB\-\-quiet\fP, \fB\-q\fP"
+This option decreases the amount of information you are given during the
+transfer, notably suppressing information messages from the remote server.
+This option is useful when invoking rsync from cron.
+.IP "\fB\-\-no-motd\fP"
+This option affects the information that is output by the client at the
+start of a daemon transfer.  This suppresses the message-of-the-day (MOTD)
+text, but it also affects the list of modules that the daemon sends in
+response to the "rsync host::" request (due to a limitation in the rsync
+protocol), so omit this option if you want to request the list of modules
+from the daemon.
+.IP "\fB\-\-ignore-times\fP, \fB\-I\fP"
+Normally rsync will skip any files that are already the same size and have
+the same modification timestamp.  This option turns off this "quick check"
+behavior, causing all files to be updated.
+.IP
+This option can be confusing compared to \fB\-\-ignore-existing\fP and
+\fB\-\-ignore-non-existing\fP in that that they cause rsync to transfer
+fewer files, while this option causes rsync to transfer more files.
+.IP "\fB\-\-size-only\fP"
+This modifies rsync's "quick check" algorithm for finding files that need
+to be transferred, changing it from the default of transferring files with
+either a changed size or a changed last-modified time to just looking for
+files that have changed in size.  This is useful when starting to use rsync
+after using another mirroring system which may not preserve timestamps
+exactly.
+.IP "\fB\-\-modify-window=NUM\fP, \fB\-@\fP"
+When comparing two timestamps, rsync treats the timestamps as being equal
+if they differ by no more than the modify-window value.  The default is 0,
+which matches just integer seconds.  If you specify a negative value (and
+the receiver is at least version 3.1.3) then nanoseconds will also be taken
+into account.  Specifying 1 is useful for copies to/from MS Windows FAT
+filesystems, because FAT represents times with a 2-second resolution
+(allowing times to differ from the original by up to 1 second).
+.IP
+If you want all your transfers to default to comparing nanoseconds, you can
+create a \fB~/.popt\fP file and put these lines in it:
+.RS 4
+.IP
+.nf
+rsync alias -a -a@-1
+rsync alias -t -t@-1
+.fi
+.RE
+.IP
+With that as the default, you'd need to specify \fB\-\-modify-window=0\fP (aka
+\fB\-@0\fP) to override it and ignore nanoseconds, e.g. if you're copying
+between ext3 and ext4, or if the receiving rsync is older than 3.1.3.
+.IP "\fB\-\-checksum\fP, \fB\-c\fP"
+This changes the way rsync checks if the files have been changed and are in
+need of a transfer.  Without this option, rsync uses a "quick check" that
+(by default) checks if each file's size and time of last modification match
+between the sender and receiver.  This option changes this to compare a
+128-bit checksum for each file that has a matching size.  Generating the
+checksums means that both sides will expend a lot of disk I/O reading all
+the data in the files in the transfer, so this can slow things down
+significantly (and this is prior to any reading that will be done to
+transfer changed files)
+.IP
+The sending side generates its checksums while it is doing the file-system
+scan that builds the list of the available files.  The receiver generates
+its checksums when it is scanning for changed files, and will checksum any
+file that has the same size as the corresponding sender's file: files with
+either a changed size or a changed checksum are selected for transfer.
+.IP
+Note that rsync always verifies that each \fItransferred\fP file was correctly
+reconstructed on the receiving side by checking a whole-file checksum that
+is generated as the file is transferred, but that automatic
+after-the-transfer verification has nothing to do with this option's
+before-the-transfer "Does this file need to be updated?" check.
+.IP
+The checksum used is auto-negotiated between the client and the server, but
+can be overridden using either the \fB\-\-checksum-choice\fP (\fB\-\-cc\fP)
+option or an environment variable that is discussed in that option's
+section.
+.IP "\fB\-\-archive\fP, \fB\-a\fP"
+This is equivalent to \fB\-rlptgoD\fP.  It is a quick way of saying you want
+recursion and want to preserve almost everything.  Be aware that it does
+\fBnot\fP include preserving ACLs (\fB\-A\fP), xattrs (\fB\-X\fP), atimes (\fB\-U\fP),
+crtimes (\fB\-N\fP), nor the finding and preserving of hardlinks (\fB\-H\fP).
+.IP
+The only exception to the above equivalence is when \fB\-\-files-from\fP
+is specified, in which case \fB\-r\fP is not implied.
+.IP "\fB\-\-no-OPTION\fP"
+You may turn off one or more implied options by prefixing the option name
+with "no-".  Not all positive options have a negated opposite, but a lot
+do, including those that can be used to disable an implied option (e.g.
+\fB\-\-no-D\fP, \fB\-\-no-perms\fP) or have different defaults in various circumstances
+(e.g. \fB\-\-no-whole-file\fP, \fB\-\-no-blocking-io\fP, \fB\-\-no-dirs\fP).  Every
+valid negated option accepts both the short and the long option name after
+the "no-" prefix (e.g. \fB\-\-no-R\fP is the same as \fB\-\-no-relative\fP).
+.IP
+As an example, if you want to use \fB\-\-archive\fP (\fB\-a\fP) but don't want
+\fB\-\-owner\fP (\fB\-o\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you
+can specify \fB\-a\ \-\-no-o\fP (aka \fB\-\-archive\ \-\-no-owner\fP).
+.IP
+The order of the options is important: if you specify \fB\-\-no-r\ \-a\fP, the \fB\-r\fP
+option would end up being turned on, the opposite of \fB\-a\ \-\-no-r\fP.  Note
+also that the side-effects of the \fB\-\-files-from\fP option are NOT
+positional, as it affects the default state of several options and slightly
+changes the meaning of \fB\-a\fP (see the \fB\-\-files-from\fP option
+for more details).
+.IP "\fB\-\-recursive\fP, \fB\-r\fP"
+This tells rsync to copy directories recursively.  See also
+\fB\-\-dirs\fP (\fB\-d\fP) for an option that allows the scanning of a single
+directory.
+.IP
+See the \fB\-\-inc-recursive\fP option for a discussion of the
+incremental recursion for creating the list of files to transfer.
+.IP "\fB\-\-inc-recursive\fP, \fB\-\-i-r\fP"
+This option explicitly enables on incremental recursion when scanning for
+files, which is enabled by default when using the \fB\-\-recursive\fP
+option and both sides of the transfer are running rsync 3.0.0 or newer.
+.IP
+Incremental recursion uses much less memory than non-incremental, while
+also beginning the transfer more quickly (since it doesn't need to scan the
+entire transfer hierarchy before it starts transferring files).  If no
+recursion is enabled in the source files, this option has no effect.
+.IP
+Some options require rsync to know the full file list, so these options
+disable the incremental recursion mode.  These include:
+.IP
+.RS
+.IP o
+\fB\-\-delete-before\fP (the old default of \fB\-\-delete\fP)
+.IP o
+\fB\-\-delete-after\fP
+.IP o
+\fB\-\-prune-empty-dirs\fP
+.IP o
+\fB\-\-delay-updates\fP
+.RE
+.IP
+In order to make \fB\-\-delete\fP compatible with incremental recursion,
+rsync 3.0.0 made \fB\-\-delete-during\fP the default delete mode (which
+was first added in 2.6.4).
+.IP
+One side-effect of incremental recursion is that any missing
+sub-directories inside a recursively-scanned directory are (by default)
+created prior to recursing into the sub-dirs.  This earlier creation point
+(compared to a non-incremental recursion) allows rsync to then set the
+modify time of the finished directory right away (without having to delay
+that until a bunch of recursive copying has finished).  However, these
+early directories don't yet have their completed mode, mtime, or ownership
+set\ \-\- they have more restrictive rights until the subdirectory's copying
+actually begins.  This early-creation idiom can be avoided by using the
+\fB\-\-omit-dir-times\fP option.
+.IP
+Incremental recursion can be disabled using the
+\fB\-\-no-inc-recursive\fP (\fB\-\-no-i-r\fP) option.
+.IP "\fB\-\-no-inc-recursive\fP, \fB\-\-no-i-r\fP"
+Disables the new incremental recursion algorithm of the
+\fB\-\-recursive\fP option.  This makes rsync scan the full file list
+before it begins to transfer files.  See \fB\-\-inc-recursive\fP for more
+info.
+.IP "\fB\-\-relative\fP, \fB\-R\fP"
+Use relative paths.  This means that the full path names specified on the
+command line are sent to the server rather than just the last parts of the
+filenames.  This is particularly useful when you want to send several
+different directories at the same time.  For example, if you used this
+command:
+.RS 4
+.IP
+.nf
+rsync -av /foo/bar/baz.c remote:/tmp/
+.fi
+.RE
+.IP
+would create a file named baz.c in /tmp/ on the remote machine.  If instead
+you used
+.RS 4
+.IP
+.nf
+rsync -avR /foo/bar/baz.c remote:/tmp/
+.fi
+.RE
+.IP
+then a file named /tmp/foo/bar/baz.c would be created on the remote
+machine, preserving its full path.  These extra path elements are called
+"implied directories" (i.e. the "foo" and the "foo/bar" directories in the
+above example).
+.IP
+Beginning with rsync 3.0.0, rsync always sends these implied directories as
+real directories in the file list, even if a path element is really a
+symlink on the sending side.  This prevents some really unexpected behaviors
+when copying the full path of a file that you didn't realize had a symlink
+in its path.  If you want to duplicate a server-side symlink, include both
+the symlink via its path, and referent directory via its real path.  If
+you're dealing with an older rsync on the sending side, you may need to use
+the \fB\-\-no-implied-dirs\fP option.
+.IP
+It is also possible to limit the amount of path information that is sent as
+implied directories for each path you specify.  With a modern rsync on the
+sending side (beginning with 2.6.7), you can insert a dot and a slash into
+the source path, like this:
+.RS 4
+.IP
+.nf
+rsync -avR /foo/./bar/baz.c remote:/tmp/
+.fi
+.RE
+.IP
+That would create /tmp/bar/baz.c on the remote machine. (Note that the dot
+must be followed by a slash, so "/foo/." would not be abbreviated.) For
+older rsync versions, you would need to use a chdir to limit the source
+path.  For example, when pushing files:
+.RS 4
+.IP
+.nf
+(cd /foo; rsync -avR bar/baz.c remote:/tmp/)
+.fi
+.RE
+.IP
+(Note that the parens put the two commands into a sub-shell, so that the
+"cd" command doesn't remain in effect for future commands.) If you're
+pulling files from an older rsync, use this idiom (but only for a
+non-daemon transfer):
+.RS 4
+.IP
+.nf
+rsync -avR --rsync-path="cd /foo; rsync" \\
+     remote:bar/baz.c /tmp/
+.fi
+.RE
+.IP "\fB\-\-no-implied-dirs\fP"
+This option affects the default behavior of the \fB\-\-relative\fP option.  When
+it is specified, the attributes of the implied directories from the source
+names are not included in the transfer.  This means that the corresponding
+path elements on the destination system are left unchanged if they exist,
+and any missing implied directories are created with default attributes.
+This even allows these implied path elements to have big differences, such
+as being a symlink to a directory on the receiving side.
+.IP
+For instance, if a command-line arg or a files-from entry told rsync to
+transfer the file "path/foo/file", the directories "path" and "path/foo"
+are implied when \fB\-\-relative\fP is used.  If "path/foo" is a symlink to "bar"
+on the destination system, the receiving rsync would ordinarily delete
+"path/foo", recreate it as a directory, and receive the file into the new
+directory.  With \fB\-\-no-implied-dirs\fP, the receiving rsync updates
+"path/foo/file" using the existing path elements, which means that the file
+ends up being created in "path/bar".  Another way to accomplish this link
+preservation is to use the \fB\-\-keep-dirlinks\fP option (which will also affect
+symlinks to directories in the rest of the transfer).
+.IP
+When pulling files from an rsync older than 3.0.0, you may need to use this
+option if the sending side has a symlink in the path you request and you
+wish the implied directories to be transferred as normal directories.
+.IP "\fB\-\-backup\fP, \fB\-b\fP"
+With this option, preexisting destination files are renamed as each file is
+transferred or deleted.  You can control where the backup file goes and
+what (if any) suffix gets appended using the \fB\-\-backup-dir\fP and
+\fB\-\-suffix\fP options.
+.IP
+If you don't specify \fB\-\-backup-dir\fP:
+.RS
+.IP
+.IP 1.
+the \fB\-\-omit-dir-times\fP option will be forced on
+.IP 2.
+the use of \fB\-\-delete\fP (without \fB\-\-delete-excluded\fP),
+causes rsync to add a "protect" filter-rule for the
+backup suffix to the end of all your existing filters that looks like
+this: \fB\-f\ "P\ *~"\fP.  This rule prevents previously backed-up files from
+being deleted.
+.RE
+.IP
+Note that if you are supplying your own filter rules, you may need to
+manually insert your own exclude/protect rule somewhere higher up in the
+list so that it has a high enough priority to be effective (e.g. if your
+rules specify a trailing inclusion/exclusion of \fB*\fP, the auto-added rule
+would never be reached).
+.IP "\fB\-\-backup-deleted\fP"
+With this option, deleted destination files are renamed, while modified
+destination files are not. Otherwise, this option behaves the same as
+\fB\-\-backup\fP, described above.  Note that if \fB\-\-backup\fP is
+also specified, whichever option is specified last takes precedence.
+.IP "\fB\-\-backup-dir=DIR\fP"
+This implies the \fB\-\-backup\fP option, and tells rsync to store all
+backups in the specified directory on the receiving side.  This can be used
+for incremental backups.  You can additionally specify a backup suffix
+using the \fB\-\-suffix\fP option (otherwise the files backed up in the
+specified directory will keep their original filenames).
+.IP
+Note that if you specify a relative path, the backup directory will be
+relative to the destination directory, so you probably want to specify
+either an absolute path or a path that starts with "../".  If an rsync
+daemon is the receiver, the backup dir cannot go outside the module's path
+hierarchy, so take extra care not to delete it or copy into it.
+.IP "\fB\-\-backup-dir-dels=DIR\fP"
+Works like \fB\-\-backup-dir\fP except for deleted files in conjunction
+with the \fB\-\-backup-deleted\fP option.
+.IP "\fB\-\-suffix=SUFFIX\fP"
+This option allows you to override the default backup suffix used with the
+\fB\-\-backup\fP (\fB\-b\fP) option.  The default suffix is a \fB~\fP if no
+\fB\-\-backup-dir\fP was specified, otherwise it is an empty string.
+.IP "\fB\-\-update\fP, \fB\-u\fP"
+This forces rsync to skip any files which exist on the destination and have
+a modified time that is newer than the source file. (If an existing
+destination file has a modification time equal to the source file's, it
+will be updated if the sizes are different.)
+.IP
+Note that this does not affect the copying of dirs, symlinks, or other
+special files.  Also, a difference of file format between the sender and
+receiver is always considered to be important enough for an update, no
+matter what date is on the objects.  In other words, if the source has a
+directory where the destination has a file, the transfer would occur
+regardless of the timestamps.
+.IP
+This option is a TRANSFER RULE, so don't expect any
+exclude side effects.
+.IP
+A caution for those that choose to combine \fB\-\-inplace\fP with
+\fB\-\-update\fP: an interrupted transfer will leave behind a partial file on the
+receiving side that has a very recent modified time, so re-running the
+transfer will probably \fBnot\fP continue the interrupted file.  As such, it
+is usually best to avoid combining this with \fB\-\-inplace\fP unless you
+have implemented manual steps to handle any interrupted in-progress files.
+.IP "\fB\-\-inplace\fP"
+This option changes how rsync transfers a file when its data needs to be
+updated: instead of the default method of creating a new copy of the file
+and moving it into place when it is complete, rsync instead writes the
+updated data directly to the destination file.
+.IP
+This has several effects:
+.IP
+.RS
+.IP o
+Hard links are not broken.  This means the new data will be visible
+through other hard links to the destination file.  Moreover, attempts to
+copy differing source files onto a multiply-linked destination file will
+result in a "tug of war" with the destination data changing back and
+forth.
+.IP o
+In-use binaries cannot be updated (either the OS will prevent this from
+happening, or binaries that attempt to swap-in their data will misbehave
+or crash).
+.IP o
+The file's data will be in an inconsistent state during the transfer and
+will be left that way if the transfer is interrupted or if an update
+fails.
+.IP o
+A file that rsync cannot write to cannot be updated.  While a super user
+can update any file, a normal user needs to be granted write permission
+for the open of the file for writing to be successful.
+.IP o
+The efficiency of rsync's delta-transfer algorithm may be reduced if some
+data in the destination file is overwritten before it can be copied to a
+position later in the file.  This does not apply if you use \fB\-\-backup\fP,
+since rsync is smart enough to use the backup file as the basis file for
+the transfer.
+.RE
+.IP
+WARNING: you should not use this option to update files that are being
+accessed by others, so be careful when choosing to use this for a copy.
+.IP
+This option is useful for transferring large files with block-based changes
+or appended data, and also on systems that are disk bound, not network
+bound.  It can also help keep a copy-on-write filesystem snapshot from
+diverging the entire contents of a file that only has minor changes.
+.IP
+The option implies \fB\-\-partial\fP (since an interrupted transfer does
+not delete the file), but conflicts with \fB\-\-partial-dir\fP and
+\fB\-\-delay-updates\fP.  Prior to rsync 2.6.4 \fB\-\-inplace\fP was also
+incompatible with \fB\-\-compare-dest\fP and \fB\-\-link-dest\fP.
+.IP "\fB\-\-append\fP"
+This special copy mode only works to efficiently update files that are
+known to be growing larger where any existing content on the receiving side
+is also known to be the same as the content on the sender.  The use of
+\fB\-\-append\fP \fBcan be dangerous\fP if you aren't 100% sure that all the files
+in the transfer are shared, growing files.  You should thus use filter
+rules to ensure that you weed out any files that do not fit this criteria.
+.IP
+Rsync updates these growing file in-place without verifying any of the
+existing content in the file (it only verifies the content that it is
+appending).  Rsync skips any files that exist on the receiving side that
+are not shorter than the associated file on the sending side (which means
+that new files are transferred).  It also skips any files whose size on the
+sending side gets shorter during the send negotiations (rsync warns about a
+"diminished" file when this happens).
+.IP
+This does not interfere with the updating of a file's non-content
+attributes (e.g.  permissions, ownership, etc.) when the file does not need
+to be transferred, nor does it affect the updating of any directories or
+non-regular files.
+.IP "\fB\-\-append-verify\fP"
+This special copy mode works like \fB\-\-append\fP except that all the
+data in the file is included in the checksum verification (making it less
+efficient but also potentially safer).  This option \fBcan be dangerous\fP if
+you aren't 100% sure that all the files in the transfer are shared, growing
+files.  See the \fB\-\-append\fP option for more details.
+.IP
+Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like
+\fB\-\-append-verify\fP, so if you are interacting with an older rsync (or the
+transfer is using a protocol prior to 30), specifying either append option
+will initiate an \fB\-\-append-verify\fP transfer.
+.IP "\fB\-\-dirs\fP, \fB\-d\fP"
+Tell the sending side to include any directories that are encountered.
+Unlike \fB\-\-recursive\fP, a directory's contents are not copied unless
+the directory name specified is "." or ends with a trailing slash (e.g.
+".", "dir/.", "dir/", etc.).  Without this option or the
+\fB\-\-recursive\fP option, rsync will skip all directories it encounters
+(and output a message to that effect for each one).  If you specify both
+\fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence.
+.IP
+The \fB\-\-dirs\fP option is implied by the \fB\-\-files-from\fP option or the
+\fB\-\-list-only\fP option (including an implied \fB\-\-list-only\fP
+usage) if \fB\-\-recursive\fP wasn't specified (so that directories are
+seen in the listing).  Specify \fB\-\-no-dirs\fP (or \fB\-\-no-d\fP) if you want to
+turn this off.
+.IP
+There is also a backward-compatibility helper option, \fB\-\-old-dirs\fP
+(\fB\-\-old-d\fP) that tells rsync to use a hack of \fB\-r\ \-\-exclude='/*/*'\fP to get
+an older rsync to list a single directory without recursing.
+.IP "\fB\-\-mkpath\fP"
+Create all missing path components of the destination path.
+.IP
+By default, rsync allows only the final component of the destination path
+to not exist, which is an attempt to help you to validate your destination
+path.  With this option, rsync creates all the missing destination-path
+components, just as if \fBmkdir\ \-p\ $DEST_PATH\fP had been run on the receiving
+side.
+.IP
+When specifying a destination path, including a trailing slash ensures that
+the whole path is treated as directory names to be created, even when the
+file list has a single item. See the COPYING TO A DIFFERENT NAME
+section for full details on how rsync decides if a final destination-path
+component should be created as a directory or not.
+.IP
+If you would like the newly-created destination dirs to match the dirs on
+the sending side, you should be using \fB\-\-relative\fP (\fB\-R\fP) instead
+of \fB\-\-mkpath\fP.  For instance, the following two commands result in the same
+destination tree, but only the second command ensures that the
+"some/extra/path" components match the dirs on the sending side:
+.RS 4
+.IP
+.nf
+rsync -ai --mkpath host:some/extra/path/*.c some/extra/path/
+rsync -aiR host:some/extra/path/*.c ./
+.fi
+.RE
+.IP "\fB\-\-links\fP, \fB\-l\fP"
+Add symlinks to the transferred files instead of noisily ignoring them with
+a "non-regular file" warning for each symlink encountered.  You can
+alternately silence the warning by specifying \fB\-\-info=nonreg0\fP.
+.IP
+The default handling of symlinks is to recreate each symlink's unchanged
+value on the receiving side.
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-copy-links\fP, \fB\-L\fP"
+The sender transforms each symlink encountered in the transfer into the
+referent item, following the symlink chain to the file or directory that it
+references.  If a symlink chain is broken, an error is output and the file
+is dropped from the transfer.
+.IP
+This option supersedes any other options that affect symlinks in the
+transfer, since there are no symlinks left in the transfer.
+.IP
+This option does not change the handling of existing symlinks on the
+receiving side, unlike versions of rsync prior to 2.6.3 which had the
+side-effect of telling the receiving side to also follow symlinks.  A
+modern rsync won't forward this option to a remote receiver (since only the
+sender needs to know about it), so this caveat should only affect someone
+using an rsync client older than 2.6.7 (which is when \fB\-L\fP stopped being
+forwarded to the receiver).
+.IP
+See the \fB\-\-keep-dirlinks\fP (\fB\-K\fP) if you need a symlink to a
+directory to be treated as a real directory on the receiving side.
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-copy-unsafe-links\fP"
+This tells rsync to copy the referent of symbolic links that point outside
+the copied tree.  Absolute symlinks are also treated like ordinary files,
+and so are any symlinks in the source path itself when \fB\-\-relative\fP
+is used.
+.IP
+Note that the cut-off point is the top of the transfer, which is the part
+of the path that rsync isn't mentioning in the verbose output.  If you copy
+"/src/subdir" to "/dest/" then the "subdir" directory is a name inside the
+transfer tree, not the top of the transfer (which is /src) so it is legal
+for created relative symlinks to refer to other names inside the /src and
+/dest directories.  If you instead copy "/src/subdir/" (with a trailing
+slash) to "/dest/subdir" that would not allow symlinks to any files outside
+of "subdir".
+.IP
+Note that safe symlinks are only copied if \fB\-\-links\fP was also
+specified or implied. The \fB\-\-copy-unsafe-links\fP option has no extra effect
+when combined with \fB\-\-copy-links\fP.
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-safe-links\fP"
+This tells the receiving rsync to ignore any symbolic links in the transfer
+which point outside the copied tree.  All absolute symlinks are also
+ignored.
+.IP
+Since this ignoring is happening on the receiving side, it will still be
+effective even when the sending side has munged symlinks (when it is using
+\fB\-\-munge-links\fP). It also affects deletions, since the file being
+present in the transfer prevents any matching file on the receiver from
+being deleted when the symlink is deemed to be unsafe and is skipped.
+.IP
+This option must be combined with \fB\-\-links\fP (or
+\fB\-\-archive\fP) to have any symlinks in the transfer to conditionally
+ignore. Its effect is superseded by \fB\-\-copy-unsafe-links\fP.
+.IP
+Using this option in conjunction with \fB\-\-relative\fP may give
+unexpected results.
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-munge-links\fP"
+This option affects just one side of the transfer and tells rsync to munge
+symlink values when it is receiving files or unmunge symlink values when it
+is sending files.  The munged values make the symlinks unusable on disk but
+allows the original contents of the symlinks to be recovered.
+.IP
+The server-side rsync often enables this option without the client's
+knowledge, such as in an rsync daemon's configuration file or by an option
+given to the rrsync (restricted rsync) script.  When specified on the
+client side, specify the option normally if it is the client side that
+has/needs the munged symlinks, or use \fB\-M\-\-munge-links\fP to give the option
+to the server when it has/needs the munged symlinks.  Note that on a local
+transfer, the client is the sender, so specifying the option directly
+unmunges symlinks while specifying it as a remote option munges symlinks.
+.IP
+This option has no effect when sent to a daemon via \fB\-\-remote-option\fP
+because the daemon configures whether it wants munged symlinks via its
+"\fBmunge\ symlinks\fP" parameter.
+.IP
+The symlink value is munged/unmunged once it is in the transfer, so any
+option that transforms symlinks into non-symlinks occurs prior to the
+munging/unmunging \fBexcept\fP for \fB\-\-safe-links\fP, which is a choice
+that the receiver makes, so it bases its decision on the munged/unmunged
+value.  This does mean that if a receiver has munging enabled, that using
+\fB\-\-safe-links\fP will cause all symlinks to be ignored (since they
+are all absolute).
+.IP
+The method that rsync uses to munge the symlinks is to prefix each one's
+value with the string "/rsyncd-munged/".  This prevents the links from
+being used as long as the directory does not exist.  When this option is
+enabled, rsync will refuse to run if that path is a directory or a symlink
+to a directory (though it only checks at startup).  See also the
+"munge-symlinks" python script in the support directory of the source code
+for a way to munge/unmunge one or more symlinks in-place.
+.IP "\fB\-\-copy-dirlinks\fP, \fB\-k\fP"
+This option causes the sending side to treat a symlink to a directory as
+though it were a real directory.  This is useful if you don't want symlinks
+to non-directories to be affected, as they would be using
+\fB\-\-copy-links\fP.
+.IP
+Without this option, if the sending side has replaced a directory with a
+symlink to a directory, the receiving side will delete anything that is in
+the way of the new symlink, including a directory hierarchy (as long as
+\fB\-\-force\fP or \fB\-\-delete\fP is in effect).
+.IP
+See also \fB\-\-keep-dirlinks\fP for an analogous option for the
+receiving side.
+.IP
+\fB\-\-copy-dirlinks\fP applies to all symlinks to directories in the source.  If
+you want to follow only a few specified symlinks, a trick you can use is to
+pass them as additional source args with a trailing slash, using
+\fB\-\-relative\fP to make the paths match up right.  For example:
+.RS 4
+.IP
+.nf
+rsync -r --relative src/./ src/./follow-me/ dest/
+.fi
+.RE
+.IP
+This works because rsync calls \fBlstat\fP(2) on the source arg as given, and
+the trailing slash makes \fBlstat\fP(2) follow the symlink, giving rise to a
+directory in the file-list which overrides the symlink found during the
+scan of "src/./".
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-keep-dirlinks\fP, \fB\-K\fP"
+This option causes the receiving side to treat a symlink to a directory as
+though it were a real directory, but only if it matches a real directory
+from the sender.  Without this option, the receiver's symlink would be
+deleted and replaced with a real directory.
+.IP
+For example, suppose you transfer a directory "foo" that contains a file
+"file", but "foo" is a symlink to directory "bar" on the receiver.  Without
+\fB\-\-keep-dirlinks\fP, the receiver deletes symlink "foo", recreates it as a
+directory, and receives the file into the new directory.  With
+\fB\-\-keep-dirlinks\fP, the receiver keeps the symlink and "file" ends up in
+"bar".
+.IP
+One note of caution: if you use \fB\-\-keep-dirlinks\fP, you must trust all the
+symlinks in the copy or enable the \fB\-\-munge-links\fP option on the
+receiving side!  If it is possible for an untrusted user to create their
+own symlink to any real directory, the user could then (on a subsequent
+copy) replace the symlink with a real directory and affect the content of
+whatever directory the symlink references.  For backup copies, you are
+better off using something like a bind mount instead of a symlink to modify
+your receiving hierarchy.
+.IP
+See also \fB\-\-copy-dirlinks\fP for an analogous option for the sending
+side.
+.IP
+See the SYMBOLIC LINKS section for multi-option info.
+.IP "\fB\-\-hard-links\fP, \fB\-H\fP"
+This tells rsync to look for hard-linked files in the source and link
+together the corresponding files on the destination.  Without this option,
+hard-linked files in the source are treated as though they were separate
+files.
+.IP
+This option does NOT necessarily ensure that the pattern of hard links on
+the destination exactly matches that on the source.  Cases in which the
+destination may end up with extra hard links include the following:
+.IP
+.RS
+.IP o
+If the destination contains extraneous hard-links (more linking than what
+is present in the source file list), the copying algorithm will not break
+them explicitly.  However, if one or more of the paths have content
+differences, the normal file-update process will break those extra links
+(unless you are using the \fB\-\-inplace\fP option).
+.IP o
+If you specify a \fB\-\-link-dest\fP directory that contains hard
+links, the linking of the destination files against the
+\fB\-\-link-dest\fP files can cause some paths in the destination to
+become linked together due to the \fB\-\-link-dest\fP associations.
+.RE
+.IP
+Note that rsync can only detect hard links between files that are inside
+the transfer set.  If rsync updates a file that has extra hard-link
+connections to files outside the transfer, that linkage will be broken.  If
+you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be
+very careful that you know how your files are being updated so that you are
+certain that no unintended changes happen due to lingering hard links (and
+see the \fB\-\-inplace\fP option for more caveats).
+.IP
+If incremental recursion is active (see \fB\-\-inc-recursive\fP), rsync
+may transfer a missing hard-linked file before it finds that another link
+for that contents exists elsewhere in the hierarchy.  This does not affect
+the accuracy of the transfer (i.e. which files are hard-linked together),
+just its efficiency (i.e. copying the data for a new, early copy of a
+hard-linked file that could have been found later in the transfer in
+another member of the hard-linked set of files).  One way to avoid this
+inefficiency is to disable incremental recursion using the
+\fB\-\-no-inc-recursive\fP option.
+.IP "\fB\-\-perms\fP, \fB\-p\fP"
+This option causes the receiving rsync to set the destination permissions
+to be the same as the source permissions. (See also the \fB\-\-chmod\fP
+option for a way to modify what rsync considers to be the source
+permissions.)
+.IP
+When this option is \fIoff\fP, permissions are set as follows:
+.IP
+.RS
+.IP o
+Existing files (including updated files) retain their existing
+permissions, though the \fB\-\-executability\fP option might change
+just the execute permission for the file.
+.IP o
+New files get their "normal" permission bits set to the source file's
+permissions masked with the receiving directory's default permissions
+(either the receiving process's umask, or the permissions specified via
+the destination directory's default ACL), and their special permission
+bits disabled except in the case where a new directory inherits a setgid
+bit from its parent directory.
+.RE
+.IP
+Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled, rsync's
+behavior is the same as that of other file-copy utilities, such as \fBcp\fP(1)
+and \fBtar\fP(1).
+.IP
+In summary: to give destination files (both old and new) the source
+permissions, use \fB\-\-perms\fP.  To give new files the destination-default
+permissions (while leaving existing files unchanged), make sure that the
+\fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures
+that all non-masked bits get enabled).  If you'd care to make this latter
+behavior easier to type, you could define a popt alias for it, such as
+putting this line in the file \fB~/.popt\fP (the following defines the \fB\-Z\fP
+option, and includes \fB\-\-no-g\fP to use the default group of the destination
+dir):
+.RS 4
+.IP
+.nf
+rsync alias -Z --no-p --no-g --chmod=ugo=rwX
+.fi
+.RE
+.IP
+You could then use this new option in a command such as this one:
+.RS 4
+.IP
+.nf
+rsync -avZ src/ dest/
+.fi
+.RE
+.IP
+(Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re-enable the
+two \fB\-\-no-*\fP options mentioned above.)
+.IP
+The preservation of the destination's setgid bit on newly-created
+directories when \fB\-\-perms\fP is off was added in rsync 2.6.7.  Older rsync
+versions erroneously preserved the three special permission bits for
+newly-created files when \fB\-\-perms\fP was off, while overriding the
+destination's setgid bit setting on a newly-created directory.  Default ACL
+observance was added to the ACL patch for rsync 2.6.7, so older (or
+non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
+(Keep in mind that it is the version of the receiving rsync that affects
+these behaviors.)
+.IP "\fB\-\-executability\fP, \fB\-E\fP"
+This option causes rsync to preserve the executability (or
+non-executability) of regular files when \fB\-\-perms\fP is not enabled.
+A regular file is considered to be executable if at least one 'x' is turned
+on in its permissions.  When an existing destination file's executability
+differs from that of the corresponding source file, rsync modifies the
+destination file's permissions as follows:
+.IP
+.RS
+.IP o
+To make a file non-executable, rsync turns off all its 'x' permissions.
+.IP o
+To make a file executable, rsync turns on each 'x' permission that has a
+corresponding 'r' permission enabled.
+.RE
+.IP
+If \fB\-\-perms\fP is enabled, this option is ignored.
+.IP "\fB\-\-acls\fP, \fB\-A\fP"
+This option causes rsync to update the destination ACLs to be the same as
+the source ACLs.  The option also implies \fB\-\-perms\fP.
+.IP
+The source and destination systems must have compatible ACL entries for
+this option to work properly.  See the \fB\-\-fake-super\fP option for a
+way to backup and restore ACLs that are not compatible.
+.IP "\fB\-\-xattrs\fP, \fB\-X\fP"
+This option causes rsync to update the destination extended attributes to
+be the same as the source ones.
+.IP
+For systems that support extended-attribute namespaces, a copy being done
+by a super-user copies all namespaces except system.*.  A normal user only
+copies the user.* namespace.  To be able to backup and restore non-user
+namespaces as a normal user, see the \fB\-\-fake-super\fP option.
+.IP
+The above name filtering can be overridden by using one or more filter
+options with the \fBx\fP modifier.  When you specify an xattr-affecting
+filter rule, rsync requires that you do your own system/user filtering, as
+well as any additional filtering for what xattr names are copied and what
+names are allowed to be deleted.  For example, to skip the system
+namespace, you could specify:
+.RS 4
+.IP
+.nf
+--filter='-x system.*'
+.fi
+.RE
+.IP
+To skip all namespaces except the user namespace, you could specify a
+negated-user match:
+.RS 4
+.IP
+.nf
+--filter='-x! user.*'
+.fi
+.RE
+.IP
+To prevent any attributes from being deleted, you could specify a
+receiver-only rule that excludes all names:
+.RS 4
+.IP
+.nf
+--filter='-xr *'
+.fi
+.RE
+.IP
+Note that the \fB\-X\fP option does not copy rsync's special xattr values (e.g.
+those used by \fB\-\-fake-super\fP) unless you repeat the option (e.g. \fB\-XX\fP).
+This "copy all xattrs" mode cannot be used with \fB\-\-fake-super\fP.
+.IP "\fB\-\-chmod=CHMOD\fP"
+This option tells rsync to apply one or more comma-separated "chmod" modes
+to the permission of the files in the transfer.  The resulting value is
+treated as though it were the permissions that the sending side supplied
+for the file, which means that this option can seem to have no effect on
+existing files if \fB\-\-perms\fP is not enabled.
+.IP
+In addition to the normal parsing rules specified in the \fBchmod\fP(1)
+manpage, you can specify an item that should only apply to a directory by
+prefixing it with a 'D', or specify an item that should only apply to a
+file by prefixing it with a 'F'.  For example, the following will ensure
+that all directories get marked set-gid, that no files are other-writable,
+that both are user-writable and group-writable, and that both have
+consistent executability across all bits:
+.RS 4
+.IP
+.nf
+--chmod=Dg+s,ug+w,Fo-w,+X
+.fi
+.RE
+.IP
+Using octal mode numbers is also allowed:
+.RS 4
+.IP
+.nf
+--chmod=D2775,F664
+.fi
+.RE
+.IP
+It is also legal to specify multiple \fB\-\-chmod\fP options, as each additional
+option is just appended to the list of changes to make.
+.IP
+See the \fB\-\-perms\fP and \fB\-\-executability\fP options for how the
+resulting permission value can be applied to the files in the transfer.
+.IP "\fB\-\-owner\fP, \fB\-o\fP"
+This option causes rsync to set the owner of the destination file to be the
+same as the source file, but only if the receiving rsync is being run as
+the super-user (see also the \fB\-\-super\fP and \fB\-\-fake-super\fP
+options).  Without this option, the owner of new and/or transferred files
+are set to the invoking user on the receiving side.
+.IP
+The preservation of ownership will associate matching names by default, but
+may fall back to using the ID number in some circumstances (see also the
+\fB\-\-numeric-ids\fP option for a full discussion).
+.IP "\fB\-\-group\fP, \fB\-g\fP"
+This option causes rsync to set the group of the destination file to be the
+same as the source file.  If the receiving program is not running as the
+super-user (or if \fB\-\-no-super\fP was specified), only groups that the
+invoking user on the receiving side is a member of will be preserved.
+Without this option, the group is set to the default group of the invoking
+user on the receiving side.
+.IP
+The preservation of group information will associate matching names by
+default, but may fall back to using the ID number in some circumstances
+(see also the \fB\-\-numeric-ids\fP option for a full discussion).
+.IP "\fB\-\-devices\fP"
+This option causes rsync to transfer character and block device files to
+the remote system to recreate these devices.  If the receiving rsync is not
+being run as the super-user, rsync silently skips creating the device files
+(see also the \fB\-\-super\fP and \fB\-\-fake-super\fP options).
+.IP
+By default, rsync generates a "non-regular file" warning for each device
+file encountered when this option is not set.  You can silence the warning
+by specifying \fB\-\-info=nonreg0\fP.
+.IP "\fB\-\-specials\fP"
+This option causes rsync to transfer special files, such as named sockets
+and fifos.  If the receiving rsync is not being run as the super-user,
+rsync silently skips creating the special files (see also the
+\fB\-\-super\fP and \fB\-\-fake-super\fP options).
+.IP
+By default, rsync generates a "non-regular file" warning for each special
+file encountered when this option is not set.  You can silence the warning
+by specifying \fB\-\-info=nonreg0\fP.
+.IP "\fB\-D\fP"
+The \fB\-D\fP option is equivalent to "\fB\-\-devices\fP
+\fB\-\-specials\fP".
+.IP "\fB\-\-copy-devices\fP"
+This tells rsync to treat a device on the sending side as a regular file,
+allowing it to be copied to a normal destination file (or another device
+if \fB\-\-write-devices\fP was also specified).
+.IP
+This option is refused by default by an rsync daemon.
+.IP "\fB\-\-write-devices\fP"
+This tells rsync to treat a device on the receiving side as a regular file,
+allowing the writing of file data into a device.
+.IP
+This option implies the \fB\-\-inplace\fP option.
+.IP
+Be careful using this, as you should know what devices are present on the
+receiving side of the transfer, especially when running rsync as root.
+.IP
+This option is refused by default by an rsync daemon.
+.IP "\fB\-\-times\fP, \fB\-t\fP"
+This tells rsync to transfer modification times along with the files and
+update them on the remote system.  Note that if this option is not used,
+the optimization that excludes files that have not been modified cannot be
+effective; in other words, a missing \fB\-t\fP (or \fB\-a\fP) will cause the
+next transfer to behave as if it used \fB\-\-ignore-times\fP (\fB\-I\fP),
+causing all files to be updated (though rsync's delta-transfer algorithm
+will make the update fairly efficient if the files haven't actually
+changed, you're much better off using \fB\-t\fP).
+.IP
+A modern rsync that is using transfer protocol 30 or 31 conveys a modify
+time using up to 8-bytes. If rsync is forced to speak an older protocol
+(perhaps due to the remote rsync being older than 3.0.0) a modify time is
+conveyed using 4-bytes. Prior to 3.2.7, these shorter values could convey
+a date range of 13-Dec-1901 to 19-Jan-2038.  Beginning with 3.2.7, these
+4-byte values now convey a date range of 1-Jan-1970 to 7-Feb-2106.  If you
+have files dated older than 1970, make sure your rsync executables are
+upgraded so that the full range of dates can be conveyed.
+.IP "\fB\-\-atimes\fP, \fB\-U\fP"
+This tells rsync to set the access (use) times of the destination files to
+the same value as the source files.
+.IP
+If repeated, it also sets the \fB\-\-open-noatime\fP option, which can help you
+to make the sending and receiving systems have the same access times on the
+transferred files without needing to run rsync an extra time after a file
+is transferred.
+.IP
+Note that some older rsync versions (prior to 3.2.0) may have been built
+with a pre-release \fB\-\-atimes\fP patch that does not imply
+\fB\-\-open-noatime\fP when this option is repeated.
+.IP "\fB\-\-open-noatime\fP"
+This tells rsync to open files with the O_NOATIME flag (on systems that
+support it) to avoid changing the access time of the files that are being
+transferred.  If your OS does not support the O_NOATIME flag then rsync
+will silently ignore this option.  Note also that some filesystems are
+mounted to avoid updating the atime on read access even without the
+O_NOATIME flag being set.
+.IP "\fB\-\-crtimes\fP, \fB\-N,\fP"
+This tells rsync to set the create times (newness) of the destination
+files to the same value as the source files.
+.IP "\fB\-\-omit-dir-times\fP, \fB\-O\fP"
+This tells rsync to omit directories when it is preserving modification,
+access, and create times.  If NFS is sharing the directories on the receiving
+side, it is a good idea to use \fB\-O\fP.  This option is inferred if you use
+\fB\-\-backup\fP without \fB\-\-backup-dir\fP.
+.IP
+This option also has the side-effect of avoiding early creation of missing
+sub-directories when incremental recursion is enabled, as discussed in the
+\fB\-\-inc-recursive\fP section.
+.IP "\fB\-\-omit-link-times\fP, \fB\-J\fP"
+This tells rsync to omit symlinks when it is preserving modification,
+access, and create times.
+.IP "\fB\-\-super\fP"
+This tells the receiving side to attempt super-user activities even if the
+receiving rsync wasn't run by the super-user.  These activities include:
+preserving users via the \fB\-\-owner\fP option, preserving all groups
+(not just the current user's groups) via the \fB\-\-group\fP option, and
+copying devices via the \fB\-\-devices\fP option.  This is useful for
+systems that allow such activities without being the super-user, and also
+for ensuring that you will get errors if the receiving side isn't being run
+as the super-user.  To turn off super-user activities, the super-user can
+use \fB\-\-no-super\fP.
+.IP "\fB\-\-fake-super\fP"
+When this option is enabled, rsync simulates super-user activities by
+saving/restoring the privileged attributes via special extended attributes
+that are attached to each file (as needed).  This includes the file's owner
+and group (if it is not the default), the file's device info (device &
+special files are created as empty text files), and any permission bits
+that we won't allow to be set on the real file (e.g. the real file gets
+u-s,g-s,o-t for safety) or that would limit the owner's access (since the
+real super-user can always access/change a file, the files we create can
+always be accessed/changed by the creating user).  This option also handles
+ACLs (if \fB\-\-acls\fP was specified) and non-user extended attributes
+(if \fB\-\-xattrs\fP was specified).
+.IP
+This is a good way to backup data without using a super-user, and to store
+ACLs from incompatible systems.
+.IP
+The \fB\-\-fake-super\fP option only affects the side where the option is used.
+To affect the remote side of a remote-shell connection, use the
+\fB\-\-remote-option\fP (\fB\-M\fP) option:
+.RS 4
+.IP
+.nf
+rsync -av -M--fake-super /src/ host:/dest/
+.fi
+.RE
+.IP
+For a local copy, this option affects both the source and the destination.
+If you wish a local copy to enable this option just for the destination
+files, specify \fB\-M\-\-fake-super\fP.  If you wish a local copy to enable this
+option just for the source files, combine \fB\-\-fake-super\fP with \fB\-M\-\-super\fP.
+.IP
+This option is overridden by both \fB\-\-super\fP and \fB\-\-no-super\fP.
+.IP
+See also the \fBfake\ super\fP setting in the
+daemon's rsyncd.conf file.
+.IP "\fB\-\-sparse\fP, \fB\-S\fP"
+Try to handle sparse files efficiently so they take up less space on the
+destination.  If combined with \fB\-\-inplace\fP the file created might
+not end up with sparse blocks with some combinations of kernel version
+and/or filesystem type.  If \fB\-\-whole-file\fP is in effect (e.g. for a
+local copy) then it will always work because rsync truncates the file prior
+to writing out the updated version.
+.IP
+Note that versions of rsync older than 3.1.3 will reject the combination of
+\fB\-\-sparse\fP and \fB\-\-inplace\fP.
+.IP "\fB\-\-preallocate\fP"
+This tells the receiver to allocate each destination file to its eventual
+size before writing data to the file.  Rsync will only use the real
+filesystem-level preallocation support provided by Linux's \fBfallocate\fP(2)
+system call or Cygwin's \fBposix_fallocate\fP(3), not the slow glibc
+implementation that writes a null byte into each block.
+.IP
+Without this option, larger files may not be entirely contiguous on the
+filesystem, but with this option rsync will probably copy more slowly.  If
+the destination is not an extent-supporting filesystem (such as ext4, xfs,
+NTFS, etc.), this option may have no positive effect at all.
+.IP
+If combined with \fB\-\-sparse\fP, the file will only have sparse blocks
+(as opposed to allocated sequences of null bytes) if the kernel version and
+filesystem type support creating holes in the allocated data.
+.IP "\fB\-\-dry-run\fP, \fB\-n\fP"
+This makes rsync perform a trial run that doesn't make any changes (and
+produces mostly the same output as a real run).  It is most commonly used
+in combination with the \fB\-\-verbose\fP (\fB\-v\fP) and/or
+\fB\-\-itemize-changes\fP (\fB\-i\fP) options to see what an rsync command is
+going to do before one actually runs it.
+.IP
+The output of \fB\-\-itemize-changes\fP is supposed to be exactly the
+same on a dry run and a subsequent real run (barring intentional trickery
+and system call failures); if it isn't, that's a bug.  Other output should
+be mostly unchanged, but may differ in some areas.  Notably, a dry run does
+not send the actual data for file transfers, so \fB\-\-progress\fP has no
+effect, the "bytes sent", "bytes received", "literal data", and "matched
+data" statistics are too small, and the "speedup" value is equivalent to a
+run where no file transfers were needed.
+.IP "\fB\-\-whole-file\fP, \fB\-W\fP"
+This option disables rsync's delta-transfer algorithm, which causes all
+transferred files to be sent whole.  The transfer may be faster if this
+option is used when the bandwidth between the source and destination
+machines is higher than the bandwidth to disk (especially when the "disk"
+is actually a networked filesystem).  This is the default when both the
+source and destination are specified as local paths, but only if no
+batch-writing option is in effect.
+.IP "\fB\-\-no-whole-file\fP, \fB\-\-no-W\fP"
+Disable whole-file updating when it is enabled by default for a local
+transfer.  This usually slows rsync down, but it can be useful if you are
+trying to minimize the writes to the destination file (if combined with
+\fB\-\-inplace\fP) or for testing the checksum-based update algorithm.
+.IP
+See also the \fB\-\-whole-file\fP option.
+.IP "\fB\-\-checksum-choice=STR\fP, \fB\-\-cc=STR\fP"
+This option overrides the checksum algorithms.  If one algorithm name is
+specified, it is used for both the transfer checksums and (assuming
+\fB\-\-checksum\fP is specified) the pre-transfer checksums.  If two
+comma-separated names are supplied, the first name affects the transfer
+checksums, and the second name affects the pre-transfer checksums (\fB\-c\fP).
+.IP
+The checksum options that you may be able to use are:
+.IP
+.RS
+.IP o
+\fBauto\fP (the default automatic choice)
+.IP o
+\fBxxh128\fP
+.IP o
+\fBxxh3\fP
+.IP o
+\fBxxh64\fP (aka \fBxxhash\fP)
+.IP o
+\fBmd5\fP
+.IP o
+\fBmd4\fP
+.IP o
+\fBsha1\fP
+.IP o
+\fBnone\fP
+.RE
+.IP
+Run \fBrsync\ \-\-version\fP to see the default checksum list compiled into your
+version (which may differ from the list above).
+.IP
+If "none" is specified for the first (or only) name, the \fB\-\-whole-file\fP
+option is forced on and no checksum verification is performed on the
+transferred data.  If "none" is specified for the second (or only) name,
+the \fB\-\-checksum\fP option cannot be used.
+.IP
+The "auto" option is the default, where rsync bases its algorithm choice on
+a negotiation between the client and the server as follows:
+.IP
+When both sides of the transfer are at least 3.2.0, rsync chooses the first
+algorithm in the client's list of choices that is also in the server's list
+of choices.  If no common checksum choice is found, rsync exits with
+an error.  If the remote rsync is too old to support checksum negotiation,
+a value is chosen based on the protocol version (which chooses between MD5
+and various flavors of MD4 based on protocol age).
+.IP
+The default order can be customized by setting the environment variable
+\fBRSYNC_CHECKSUM_LIST\fP to a space-separated list of acceptable checksum
+names.  If the string contains a "\fB&\fP" character, it is separated into the
+"client string & server string", otherwise the same string applies to both.
+If the string (or string portion) contains no non-whitespace characters,
+the default checksum list is used.  This method does not allow you to
+specify the transfer checksum separately from the pre-transfer checksum,
+and it discards "auto" and all unknown checksum names.  A list with only
+invalid names results in a failed negotiation.
+.IP
+The use of the \fB\-\-checksum-choice\fP option overrides this environment list.
+.IP "\fB\-\-one-file-system\fP, \fB\-x\fP"
+This tells rsync to avoid crossing a filesystem boundary when recursing.
+This does not limit the user's ability to specify items to copy from
+multiple filesystems, just rsync's recursion through the hierarchy of each
+directory that the user specified, and also the analogous recursion on the
+receiving side during deletion.  Also keep in mind that rsync treats a
+"bind" mount to the same device as being on the same filesystem.
+.IP
+If this option is repeated, rsync omits all mount-point directories from
+the copy.  Otherwise, it includes an empty directory at each mount-point it
+encounters (using the attributes of the mounted directory because those of
+the underlying mount-point directory are inaccessible).
+.IP
+If rsync has been told to collapse symlinks (via \fB\-\-copy-links\fP or
+\fB\-\-copy-unsafe-links\fP), a symlink to a directory on another device
+is treated like a mount-point.  Symlinks to non-directories are unaffected
+by this option.
+.IP "\fB\-\-ignore-non-existing\fP, \fB\-\-existing\fP"
+This tells rsync to skip creating files (including directories) that do not
+exist yet on the destination.  If this option is combined with the
+\fB\-\-ignore-existing\fP option, no files will be updated (which can be
+useful if all you want to do is delete extraneous files).
+.IP
+This option is a TRANSFER RULE, so don't expect any
+exclude side effects.
+.IP "\fB\-\-ignore-existing\fP"
+This tells rsync to skip updating files that already exist on the
+destination (this does \fInot\fP ignore existing directories, or nothing would
+get done).  See also \fB\-\-ignore-non-existing\fP.
+.IP
+This option is a TRANSFER RULE, so don't expect any
+exclude side effects.
+.IP
+This option can be useful for those doing backups using the
+\fB\-\-link-dest\fP option when they need to continue a backup run that
+got interrupted.  Since a \fB\-\-link-dest\fP run is copied into a new
+directory hierarchy (when it is used properly), using [\fB\-\-ignore-existing\fP
+will ensure that the already-handled files don't get tweaked (which avoids
+a change in permissions on the hard-linked files).  This does mean that
+this option is only looking at the existing files in the destination
+hierarchy itself.
+.IP
+When \fB\-\-info=skip2\fP is used rsync will output "FILENAME exists
+(INFO)" messages where the INFO indicates one of "type change", "sum
+change" (requires \fB\-c\fP), "file change" (based on the quick check),
+"attr change", or "uptodate".  Using \fB\-\-info=skip1\fP (which is also
+implied by 2 \fB\-v\fP options) outputs the exists message without the
+INFO suffix.
+.IP "\fB\-\-remove-source-files\fP"
+This tells rsync to remove from the sending side the files (meaning
+non-directories) that are a part of the transfer and have been successfully
+duplicated on the receiving side.
+.IP
+Note that you should only use this option on source files that are
+quiescent.  If you are using this to move files that show up in a
+particular directory over to another host, make sure that the finished
+files get renamed into the source directory, not directly written into it,
+so that rsync can't possibly transfer a file that is not yet fully written.
+If you can't first write the files into a different directory, you should
+use a naming idiom that lets rsync avoid transferring files that are not
+yet finished (e.g. name the file "foo.new" when it is written, rename it to
+"foo" when it is done, and then use the option \fB\-\-exclude='*.new'\fP
+for the rsync transfer).
+.IP
+Starting with 3.1.0, rsync will skip the sender-side removal (and output an
+error) if the file's size or modify time has not stayed unchanged.
+.IP
+Starting with 3.2.6, a local rsync copy will ensure that the sender does
+not remove a file the receiver just verified, such as when the user
+accidentally makes the source and destination directory the same path.
+.IP "\fB\-\-delete\fP"
+This tells rsync to delete extraneous files from the receiving side (ones
+that aren't on the sending side), but only for the directories that are
+being synchronized.  You must have asked rsync to send the whole directory
+(e.g. "\fBdir\fP" or "\fBdir/\fP") without using a wildcard for the directory's
+contents (e.g. "\fBdir/*\fP") since the wildcard is expanded by the shell and
+rsync thus gets a request to transfer individual files, not the files'
+parent directory.  Files that are excluded from the transfer are also
+excluded from being deleted unless you use the \fB\-\-delete-excluded\fP
+option or mark the rules as only matching on the sending side (see the
+include/exclude modifiers in the FILTER RULES section).
+.IP
+Prior to rsync 2.6.7, this option would have no effect unless
+\fB\-\-recursive\fP was enabled.  Beginning with 2.6.7, deletions will
+also occur when \fB\-\-dirs\fP (\fB\-d\fP) is enabled, but only for
+directories whose contents are being copied.
+.IP
+This option can be dangerous if used incorrectly! It is a very good idea to
+first try a run using the \fB\-\-dry-run\fP (\fB\-n\fP) option to see what
+files are going to be deleted.
+.IP
+If the sending side detects any I/O errors, then the deletion of any files
+at the destination will be automatically disabled.  This is to prevent
+temporary filesystem failures (such as NFS errors) on the sending side from
+causing a massive deletion of files on the destination.  You can override
+this with the \fB\-\-ignore-errors\fP option.
+.IP
+The \fB\-\-delete\fP option may be combined with one of the \-\-delete-WHEN options
+without conflict, as well as \fB\-\-delete-excluded\fP.  However, if none
+of the \fB\-\-delete-WHEN\fP options are specified, rsync will choose the
+\fB\-\-delete-during\fP algorithm when talking to rsync 3.0.0 or newer,
+or the \fB\-\-delete-before\fP algorithm when talking to an older rsync.
+See also \fB\-\-delete-delay\fP and \fB\-\-delete-after\fP.
+.IP "\fB\-\-delete-before\fP"
+Request that the file-deletions on the receiving side be done before the
+transfer starts.  See \fB\-\-delete\fP (which is implied) for more
+details on file-deletion.
+.IP
+Deleting before the transfer is helpful if the filesystem is tight for
+space and removing extraneous files would help to make the transfer
+possible.  However, it does introduce a delay before the start of the
+transfer, and this delay might cause the transfer to timeout (if
+\fB\-\-timeout\fP was specified).  It also forces rsync to use the old,
+non-incremental recursion algorithm that requires rsync to scan all the
+files in the transfer into memory at once (see \fB\-\-recursive\fP).
+.IP "\fB\-\-delete-during\fP, \fB\-\-del\fP"
+Request that the file-deletions on the receiving side be done incrementally
+as the transfer happens.  The per-directory delete scan is done right
+before each directory is checked for updates, so it behaves like a more
+efficient \fB\-\-delete-before\fP, including doing the deletions prior to
+any per-directory filter files being updated.  This option was first added
+in rsync version 2.6.4.  See \fB\-\-delete\fP (which is implied) for more
+details on file-deletion.
+.IP "\fB\-\-delete-delay\fP"
+Request that the file-deletions on the receiving side be computed during
+the transfer (like \fB\-\-delete-during\fP), and then removed after the
+transfer completes.  This is useful when combined with
+\fB\-\-delay-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient
+than using \fB\-\-delete-after\fP (but can behave differently, since
+\fB\-\-delete-after\fP computes the deletions in a separate pass after
+all updates are done).  If the number of removed files overflows an
+internal buffer, a temporary file will be created on the receiving side to
+hold the names (it is removed while open, so you shouldn't see it during
+the transfer).  If the creation of the temporary file fails, rsync will try
+to fall back to using \fB\-\-delete-after\fP (which it cannot do if
+\fB\-\-recursive\fP is doing an incremental scan).  See
+\fB\-\-delete\fP (which is implied) for more details on file-deletion.
+.IP "\fB\-\-delete-after\fP"
+Request that the file-deletions on the receiving side be done after the
+transfer has completed.  This is useful if you are sending new
+per-directory merge files as a part of the transfer and you want their
+exclusions to take effect for the delete phase of the current transfer.  It
+also forces rsync to use the old, non-incremental recursion algorithm that
+requires rsync to scan all the files in the transfer into memory at once
+(see \fB\-\-recursive\fP). See \fB\-\-delete\fP (which is implied) for
+more details on file-deletion.
+.IP
+See also the \fB\-\-delete-delay\fP option that might be a faster choice
+for those that just want the deletions to occur at the end of the transfer.
+.IP "\fB\-\-delete-excluded\fP"
+This option turns any unqualified exclude/include rules into server-side
+rules that do not affect the receiver's deletions.
+.IP
+By default, an exclude or include has both a server-side effect (to "hide"
+and "show" files when building the server's file list) and a receiver-side
+effect (to "protect" and "risk" files when deletions are occurring).  Any
+rule that has no modifier to specify what sides it is executed on will be
+instead treated as if it were a server-side rule only, avoiding any
+"protect" effects of the rules.
+.IP
+A rule can still apply to both sides even with this option specified if the
+rule is given both the sender & receiver modifier letters (e.g., \fB\-f'\-sr\ foo'\fP).  Receiver-side protect/risk rules can also be explicitly specified
+to limit the deletions.  This saves you from having to edit a bunch of
+\fB\-f'\-\ foo'\fP rules into \fB\-f'\-s\ foo'\fP (aka \fB\-f'H\ foo'\fP) rules (not to mention
+the corresponding includes).
+.IP
+See the FILTER RULES section for more information.  See
+\fB\-\-delete\fP (which is implied) for more details on deletion.
+.IP "\fB\-\-ignore-missing-args\fP"
+When rsync is first processing the explicitly requested source files (e.g.
+command-line arguments or \fB\-\-files-from\fP entries), it is normally
+an error if the file cannot be found.  This option suppresses that error,
+and does not try to transfer the file.  This does not affect subsequent
+vanished-file errors if a file was initially found to be present and later
+is no longer there.
+.IP "\fB\-\-delete-missing-args\fP"
+This option takes the behavior of the (implied)
+\fB\-\-ignore-missing-args\fP option a step farther: each missing arg
+will become a deletion request of the corresponding destination file on the
+receiving side (should it exist).  If the destination file is a non-empty
+directory, it will only be successfully deleted if \fB\-\-force\fP or
+\fB\-\-delete\fP are in effect.  Other than that, this option is
+independent of any other type of delete processing.
+.IP
+The missing source files are represented by special file-list entries which
+display as a "\fB*missing\fP" entry in the \fB\-\-list-only\fP output.
+.IP "\fB\-\-ignore-errors\fP"
+Tells \fB\-\-delete\fP to go ahead and delete files even when there are
+I/O errors.
+.IP "\fB\-\-force\fP"
+This option tells rsync to delete a non-empty directory when it is to be
+replaced by a non-directory.  This is only relevant if deletions are not
+active (see \fB\-\-delete\fP for details).
+.IP
+Note for older rsync versions: \fB\-\-force\fP used to still be required when
+using \fB\-\-delete-after\fP, and it used to be non-functional unless the
+\fB\-\-recursive\fP option was also enabled.
+.IP "\fB\-\-max-delete=NUM\fP"
+This tells rsync not to delete more than NUM files or directories.  If that
+limit is exceeded, all further deletions are skipped through the end of the
+transfer.  At the end, rsync outputs a warning (including a count of the
+skipped deletions) and exits with an error code of 25 (unless some more
+important error condition also occurred).
+.IP
+Beginning with version 3.0.0, you may specify \fB\-\-max-delete=0\fP to be warned
+about any extraneous files in the destination without removing any of them.
+Older clients interpreted this as "unlimited", so if you don't know what
+version the client is, you can use the less obvious \fB\-\-max-delete=\-1\fP as a
+backward-compatible way to specify that no deletions be allowed (though
+really old versions didn't warn when the limit was exceeded).
+.IP "\fB\-\-max-size=SIZE\fP"
+This tells rsync to avoid transferring any file that is larger than the
+specified SIZE.  A numeric value can be suffixed with a string to indicate
+the numeric units or left unqualified to specify bytes.  Feel free to use a
+fractional value along with the units, such as \fB\-\-max-size=1.5m\fP.
+.IP
+This option is a TRANSFER RULE, so don't expect any
+exclude side effects.
+.IP
+The first letter of a units string can be \fBB\fP (bytes), \fBK\fP (kilo), \fBM\fP
+(mega), \fBG\fP (giga), \fBT\fP (tera), or \fBP\fP (peta).  If the string is a single
+char or has "ib" added to it (e.g. "G" or "GiB") then the units are
+multiples of 1024.  If you use a two-letter suffix that ends with a "B"
+(e.g. "kb") then you get units that are multiples of 1000.  The string's
+letters can be any mix of upper and lower-case that you want to use.
+.IP
+Finally, if the string ends with either "+1" or "\-1", it is offset by one
+byte in the indicated direction.  The largest possible value is usually
+\fB8192P-1\fP.
+.IP
+Examples: \fB\-\-max-size=1.5mb-1\fP is 1499999 bytes, and \fB\-\-max-size=2g+1\fP is
+2147483649 bytes.
+.IP
+Note that rsync versions prior to 3.1.0 did not allow \fB\-\-max-size=0\fP.
+.IP "\fB\-\-min-size=SIZE\fP"
+This tells rsync to avoid transferring any file that is smaller than the
+specified SIZE, which can help in not transferring small, junk files.  See
+the \fB\-\-max-size\fP option for a description of SIZE and other info.
+.IP
+Note that rsync versions prior to 3.1.0 did not allow \fB\-\-min-size=0\fP.
+.IP "\fB\-\-max-alloc=SIZE\fP"
+By default rsync limits an individual malloc/realloc to about 1GB in size.
+For most people this limit works just fine and prevents a protocol error
+causing rsync to request massive amounts of memory.  However, if you have
+many millions of files in a transfer, a large amount of server memory, and
+you don't want to split up your transfer into multiple parts, you can
+increase the per-allocation limit to something larger and rsync will
+consume more memory.
+.IP
+Keep in mind that this is not a limit on the total size of allocated
+memory.  It is a sanity-check value for each individual allocation.
+.IP
+See the \fB\-\-max-size\fP option for a description of how SIZE can be
+specified.  The default suffix if none is given is bytes.
+.IP
+Beginning in 3.2.3, a value of 0 specifies no limit.
+.IP
+You can set a default value using the environment variable
+\fBRSYNC_MAX_ALLOC\fP using the same SIZE values as supported by this
+option.  If the remote rsync doesn't understand the \fB\-\-max-alloc\fP option,
+you can override an environmental value by specifying \fB\-\-max-alloc=1g\fP,
+which will make rsync avoid sending the option to the remote side (because
+"1G" is the default).
+.IP "\fB\-\-block-size=SIZE\fP, \fB\-B\fP"
+This forces the block size used in rsync's delta-transfer algorithm to a
+fixed value.  It is normally selected based on the size of each file being
+updated.  See the technical report for details.
+.IP
+Beginning in 3.2.3 the SIZE can be specified with a suffix as detailed in
+the \fB\-\-max-size\fP option.  Older versions only accepted a byte count.
+.IP "\fB\-\-rsh=COMMAND\fP, \fB\-e\fP"
+This option allows you to choose an alternative remote shell program to use
+for communication between the local and remote copies of rsync.  Typically,
+rsync is configured to use ssh by default, but you may prefer to use rsh on
+a local network.
+.IP
+If this option is used with \fB[user@]host::module/path\fP, then the remote
+shell \fICOMMAND\fP will be used to run an rsync daemon on the remote host, and
+all data will be transmitted through that remote shell connection, rather
+than through a direct socket connection to a running rsync daemon on the
+remote host.  See the USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL
+CONNECTION section above.
+.IP
+Beginning with rsync 3.2.0, the \fBRSYNC_PORT\fP environment variable will
+be set when a daemon connection is being made via a remote-shell
+connection.  It is set to 0 if the default daemon port is being assumed, or
+it is set to the value of the rsync port that was specified via either the
+\fB\-\-port\fP option or a non-empty port value in an \fBrsync://\fP URL.
+This allows the script to discern if a non-default port is being requested,
+allowing for things such as an SSL or stunnel helper script to connect to a
+default or alternate port.
+.IP
+Command-line arguments are permitted in COMMAND provided that COMMAND is
+presented to rsync as a single argument.  You must use spaces (not tabs or
+other whitespace) to separate the command and args from each other, and you
+can use single- and/or double-quotes to preserve spaces in an argument (but
+not backslashes).  Note that doubling a single-quote inside a single-quoted
+string gives you a single-quote; likewise for double-quotes (though you
+need to pay attention to which quotes your shell is parsing and which
+quotes rsync is parsing).  Some examples:
+.RS 4
+.IP
+.nf
+-e 'ssh -p 2234'
+-e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
+.fi
+.RE
+.IP
+(Note that ssh users can alternately customize site-specific connect
+options in their .ssh/config file.)
+.IP
+You can also choose the remote shell program using the \fBRSYNC_RSH\fP
+environment variable, which accepts the same range of values as \fB\-e\fP.
+.IP
+See also the \fB\-\-blocking-io\fP option which is affected by this
+option.
+.IP "\fB\-\-rsync-path=PROGRAM\fP"
+Use this to specify what program is to be run on the remote machine to
+start-up rsync.  Often used when rsync is not in the default remote-shell's
+path (e.g. \fB\-\-rsync-path=/usr/local/bin/rsync\fP).  Note that PROGRAM is run
+with the help of a shell, so it can be any program, script, or command
+sequence you'd care to run, so long as it does not corrupt the standard-in
+& standard-out that rsync is using to communicate.
+.IP
+One tricky example is to set a different default directory on the remote
+machine for use with the \fB\-\-relative\fP option.  For instance:
+.RS 4
+.IP
+.nf
+rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/
+.fi
+.RE
+.IP "\fB\-\-remote-option=OPTION\fP, \fB\-M\fP"
+This option is used for more advanced situations where you want certain
+effects to be limited to one side of the transfer only.  For instance, if
+you want to pass \fB\-\-log-file=FILE\fP and \fB\-\-fake-super\fP to
+the remote system, specify it like this:
+.RS 4
+.IP
+.nf
+rsync -av -M --log-file=foo -M--fake-super src/ dest/
+.fi
+.RE
+.IP
+If you want to have an option affect only the local side of a transfer when
+it normally affects both sides, send its negation to the remote side.  Like
+this:
+.RS 4
+.IP
+.nf
+rsync -av -x -M--no-x src/ dest/
+.fi
+.RE
+.IP
+Be cautious using this, as it is possible to toggle an option that will
+cause rsync to have a different idea about what data to expect next over
+the socket, and that will make it fail in a cryptic fashion.
+.IP
+Note that you should use a separate \fB\-M\fP option for each remote option you
+want to pass.  On older rsync versions, the presence of any spaces in the
+remote-option arg could cause it to be split into separate remote args, but
+this requires the use of \fB\-\-old-args\fP in a modern rsync.
+.IP
+When performing a local transfer, the "local" side is the sender and the
+"remote" side is the receiver.
+.IP
+Note some versions of the popt option-parsing library have a bug in them
+that prevents you from using an adjacent arg with an equal in it next to a
+short option letter (e.g. \fB\-M\-\-log-file=/tmp/foo\fP).  If this bug affects
+your version of popt, you can use the version of popt that is included with
+rsync.
+.IP "\fB\-\-cvs-exclude\fP, \fB\-C\fP"
+This is a useful shorthand for excluding a broad range of files that you
+often don't want to transfer between systems.  It uses a similar algorithm
+to CVS to determine if a file should be ignored.
+.IP
+The exclude list is initialized to exclude the following items (these
+initial items are marked as perishable\ \-\- see the FILTER RULES
+section):
+.RS 4
+.IP
+\fBRCS\fP
+\fBSCCS\fP
+\fBCVS\fP
+\fBCVS.adm\fP
+\fBRCSLOG\fP
+\fBcvslog.*\fP
+\fBtags\fP
+\fBTAGS\fP
+\fB.make.state\fP
+\fB.nse_depinfo\fP
+\fB*~\fP
+\fB#*\fP
+\fB.#*\fP
+\fB,*\fP
+\fB_$*\fP
+\fB*$\fP
+\fB*.old\fP
+\fB*.bak\fP
+\fB*.BAK\fP
+\fB*.orig\fP
+\fB*.rej\fP
+\fB.del-*\fP
+\fB*.a\fP
+\fB*.olb\fP
+\fB*.o\fP
+\fB*.obj\fP
+\fB*.so\fP
+\fB*.exe\fP
+\fB*.Z\fP
+\fB*.elc\fP
+\fB*.ln\fP
+\fBcore\fP
+\fB.svn/\fP
+\fB.git/\fP
+\fB.hg/\fP
+\fB.bzr/\fP
+.RE
+.IP
+then, files listed in a $HOME/.cvsignore are added to the list and any
+files listed in the CVSIGNORE environment variable (all cvsignore names are
+delimited by whitespace).
+.IP
+Finally, any file is ignored if it is in the same directory as a .cvsignore
+file and matches one of the patterns listed therein.  Unlike rsync's
+filter/exclude files, these patterns are split on whitespace.  See the
+\fBcvs\fP(1) manual for more information.
+.IP
+If you're combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should
+note that these CVS excludes are appended at the end of your own rules,
+regardless of where the \fB\-C\fP was placed on the command-line.  This makes
+them a lower priority than any rules you specified explicitly.  If you want
+to control where these CVS excludes get inserted into your filter rules,
+you should omit the \fB\-C\fP as a command-line option and use a combination of
+\fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your
+command-line or by putting the ":C" and "\-C" rules into a filter file with
+your other rules).  The first option turns on the per-directory scanning
+for the .cvsignore file.  The second option does a one-time import of the
+CVS excludes mentioned above.
+.IP "\fB\-\-filter=RULE\fP, \fB\-f\fP"
+This option allows you to add rules to selectively exclude certain files
+from the list of files to be transferred.  This is most useful in
+combination with a recursive transfer.
+.IP
+You may use as many \fB\-\-filter\fP options on the command line as you like to
+build up the list of files to exclude.  If the filter contains whitespace,
+be sure to quote it so that the shell gives the rule to rsync as a single
+argument.  The text below also mentions that you can use an underscore to
+replace the space that separates a rule from its arg.
+.IP
+See the FILTER RULES section for detailed information on this option.
+.IP "\fB\-F\fP"
+The \fB\-F\fP option is a shorthand for adding two \fB\-\-filter\fP rules to
+your command.  The first time it is used is a shorthand for this rule:
+.RS 4
+.IP
+.nf
+--filter='dir-merge /.rsync-filter'
+.fi
+.RE
+.IP
+This tells rsync to look for per-directory .rsync-filter files that have
+been sprinkled through the hierarchy and use their rules to filter the
+files in the transfer.  If \fB\-F\fP is repeated, it is a shorthand for this
+rule:
+.RS 4
+.IP
+.nf
+--filter='exclude .rsync-filter'
+.fi
+.RE
+.IP
+This filters out the .rsync-filter files themselves from the transfer.
+.IP
+See the FILTER RULES section for detailed information on how these
+options work.
+.IP "\fB\-\-exclude=PATTERN\fP"
+This option is a simplified form of the \fB\-\-filter\fP option that
+specifies an exclude rule and does not allow the full rule-parsing syntax
+of normal filter rules.  This is equivalent to specifying \fB\-f'\-\ PATTERN'\fP.
+.IP
+See the FILTER RULES section for detailed information on this option.
+.IP "\fB\-\-exclude-from=FILE\fP"
+This option is related to the \fB\-\-exclude\fP option, but it specifies
+a FILE that contains exclude patterns (one per line).  Blank lines in the
+file are ignored, as are whole-line comments that start with '\fB;\fP' or '\fB#\fP'
+(filename rules that contain those characters are unaffected).
+.IP
+If a line begins with "\fB\-\ \fP" (dash, space) or "\fB+\ \fP" (plus, space), then
+the type of rule is being explicitly specified as an exclude or an include
+(respectively).  Any rules without such a prefix are taken to be an exclude.
+.IP
+If a line consists of just "\fB!\fP", then the current filter rules are cleared
+before adding any further rules.
+.IP
+If \fIFILE\fP is '\fB\-\fP', the list will be read from standard input.
+.IP "\fB\-\-include=PATTERN\fP"
+This option is a simplified form of the \fB\-\-filter\fP option that
+specifies an include rule and does not allow the full rule-parsing syntax
+of normal filter rules.  This is equivalent to specifying \fB\-f'+\ PATTERN'\fP.
+.IP
+See the FILTER RULES section for detailed information on this option.
+.IP "\fB\-\-include-from=FILE\fP"
+This option is related to the \fB\-\-include\fP option, but it specifies
+a FILE that contains include patterns (one per line).  Blank lines in the
+file are ignored, as are whole-line comments that start with '\fB;\fP' or '\fB#\fP'
+(filename rules that contain those characters are unaffected).
+.IP
+If a line begins with "\fB\-\ \fP" (dash, space) or "\fB+\ \fP" (plus, space), then
+the type of rule is being explicitly specified as an exclude or an include
+(respectively).  Any rules without such a prefix are taken to be an include.
+.IP
+If a line consists of just "\fB!\fP", then the current filter rules are cleared
+before adding any further rules.
+.IP
+If \fIFILE\fP is '\fB\-\fP', the list will be read from standard input.
+.IP "\fB\-\-files-from=FILE\fP"
+Using this option allows you to specify the exact list of files to transfer
+(as read from the specified FILE or '\fB\-\fP' for standard input).  It also
+tweaks the default behavior of rsync to make transferring just the
+specified files and directories easier:
+.IP
+.RS
+.IP o
+The \fB\-\-relative\fP (\fB\-R\fP) option is implied, which preserves the
+path information that is specified for each item in the file (use
+\fB\-\-no-relative\fP or \fB\-\-no-R\fP if you want to turn that off).
+.IP o
+The \fB\-\-dirs\fP (\fB\-d\fP) option is implied, which will create
+directories specified in the list on the destination rather than noisily
+skipping them (use \fB\-\-no-dirs\fP or \fB\-\-no-d\fP if you want to turn that off).
+.IP o
+The \fB\-\-archive\fP (\fB\-a\fP) option's behavior does not imply
+\fB\-\-recursive\fP (\fB\-r\fP), so specify it explicitly, if you want it.
+.IP o
+These side-effects change the default state of rsync, so the position of
+the \fB\-\-files-from\fP option on the command-line has no bearing on how other
+options are parsed (e.g. \fB\-a\fP works the same before or after
+\fB\-\-files-from\fP, as does \fB\-\-no-R\fP and all other options).
+.RE
+.IP
+The filenames that are read from the FILE are all relative to the source
+dir\ \-\- any leading slashes are removed and no ".." references are allowed
+to go higher than the source dir.  For example, take this command:
+.RS 4
+.IP
+.nf
+rsync -a --files-from=/tmp/foo /usr remote:/backup
+.fi
+.RE
+.IP
+If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
+directory will be created as /backup/bin on the remote host.  If it
+contains "bin/" (note the trailing slash), the immediate contents of the
+directory would also be sent (without needing to be explicitly mentioned in
+the file\ \-\- this began in version 2.6.4).  In both cases, if the
+\fB\-r\fP option was enabled, that dir's entire hierarchy would also be
+transferred (keep in mind that \fB\-r\fP needs to be specified
+explicitly with \fB\-\-files-from\fP, since it is not implied by \fB\-a\fP.
+Also note that the effect of the (enabled by default) \fB\-r\fP option
+is to duplicate only the path info that is read from the file\ \-\- it does
+not force the duplication of the source-spec path (/usr in this case).
+.IP
+In addition, the \fB\-\-files-from\fP file can be read from the remote host
+instead of the local host if you specify a "host:" in front of the file
+(the host must match one end of the transfer).  As a short-cut, you can
+specify just a prefix of ":" to mean "use the remote end of the transfer".
+For example:
+.RS 4
+.IP
+.nf
+rsync -a --files-from=:/path/file-list src:/ /tmp/copy
+.fi
+.RE
+.IP
+This would copy all the files specified in the /path/file-list file that
+was located on the remote "src" host.
+.IP
+If the \fB\-\-iconv\fP and \fB\-\-secluded-args\fP options are specified
+and the \fB\-\-files-from\fP filenames are being sent from one host to another,
+the filenames will be translated from the sending host's charset to the
+receiving host's charset.
+.IP
+NOTE: sorting the list of files in the \fB\-\-files-from\fP input helps rsync to
+be more efficient, as it will avoid re-visiting the path elements that are
+shared between adjacent entries.  If the input is not sorted, some path
+elements (implied directories) may end up being scanned multiple times, and
+rsync will eventually unduplicate them after they get turned into file-list
+elements.
+.IP "\fB\-\-from0\fP, \fB\-0\fP"
+This tells rsync that the rules/filenames it reads from a file are
+terminated by a null ('\\0') character, not a NL, CR, or CR+LF.  This
+affects \fB\-\-exclude-from\fP, \fB\-\-include-from\fP,
+\fB\-\-files-from\fP, and any merged files specified in a
+\fB\-\-filter\fP rule.  It does not affect \fB\-\-cvs-exclude\fP (since
+all names read from a .cvsignore file are split on whitespace).
+.IP "\fB\-\-old-args\fP"
+This option tells rsync to stop trying to protect the arg values on the
+remote side from unintended word-splitting or other misinterpretation.
+It also allows the client to treat an empty arg as a "." instead of
+generating an error.
+.IP
+The default in a modern rsync is for "shell-active" characters (including
+spaces) to be backslash-escaped in the args that are sent to the remote
+shell.  The wildcard characters \fB*\fP, \fB?\fP, \fB[\fP, & \fB]\fP are not escaped in
+filename args (allowing them to expand into multiple filenames) while being
+protected in option args, such as \fB\-\-usermap\fP.
+.IP
+If you have a script that wants to use old-style arg splitting in its
+filenames, specify this option once.  If the remote shell has a problem
+with any backslash escapes at all, specify this option twice.
+.IP
+You may also control this setting via the \fBRSYNC_OLD_ARGS\fP environment
+variable.  If it has the value "1", rsync will default to a single-option
+setting.  If it has the value "2" (or more), rsync will default to a
+repeated-option setting.  If it is "0", you'll get the default escaping
+behavior.  The environment is always overridden by manually specified
+positive or negative options (the negative is \fB\-\-no-old-args\fP).
+.IP
+Note that this option also disables the extra safety check added in 3.2.5
+that ensures that a remote sender isn't including extra top-level items in
+the file-list that you didn't request.  This side-effect is necessary
+because we can't know for sure what names to expect when the remote shell
+is interpreting the args.
+.IP
+This option conflicts with the \fB\-\-secluded-args\fP option.
+.IP "\fB\-\-secluded-args\fP, \fB\-s\fP"
+This option sends all filenames and most options to the remote rsync via
+the protocol (not the remote shell command line) which avoids letting the
+remote shell modify them.  Wildcards are expanded on the remote host by
+rsync instead of a shell.
+.IP
+This is similar to the default backslash-escaping of args that was added
+in 3.2.4 (see \fB\-\-old-args\fP) in that it prevents things like space
+splitting and unwanted special-character side-effects. However, it has the
+drawbacks of being incompatible with older rsync versions (prior to 3.0.0)
+and of being refused by restricted shells that want to be able to inspect
+all the option values for safety.
+.IP
+This option is useful for those times that you need the argument's
+character set to be converted for the remote host, if the remote shell is
+incompatible with the default backslash-escpaing method, or there is some
+other reason that you want the majority of the options and arguments to
+bypass the command-line of the remote shell.
+.IP
+If you combine this option with \fB\-\-iconv\fP, the args related to the
+remote side will be translated from the local to the remote character-set.
+The translation happens before wild-cards are expanded.  See also the
+\fB\-\-files-from\fP option.
+.IP
+You may also control this setting via the \fBRSYNC_PROTECT_ARGS\fP
+environment variable.  If it has a non-zero value, this setting will be
+enabled by default, otherwise it will be disabled by default.  Either state
+is overridden by a manually specified positive or negative version of this
+option (note that \fB\-\-no-s\fP and \fB\-\-no-secluded-args\fP are the negative
+versions).  This environment variable is also superseded by a non-zero
+\fBRSYNC_OLD_ARGS\fP export.
+.IP
+This option conflicts with the \fB\-\-old-args\fP option.
+.IP
+This option used to be called \fB\-\-protect-args\fP (before 3.2.6) and that
+older name can still be used (though specifying it as \fB\-s\fP is always the
+easiest and most compatible choice).
+.IP "\fB\-\-trust-sender\fP"
+This option disables two extra validation checks that a local client
+performs on the file list generated by a remote sender.  This option should
+only be used if you trust the sender to not put something malicious in the
+file list (something that could possibly be done via a modified rsync, a
+modified shell, or some other similar manipulation).
+.IP
+Normally, the rsync client (as of version 3.2.5) runs two extra validation
+checks when pulling files from a remote rsync:
+.IP
+.RS
+.IP o
+It verifies that additional arg items didn't get added at the top of the
+transfer.
+.IP o
+It verifies that none of the items in the file list are names that should
+have been excluded (if filter rules were specified).
+.RE
+.IP
+Note that various options can turn off one or both of these checks if the
+option interferes with the validation.  For instance:
+.IP
+.RS
+.IP o
+Using a per-directory filter file reads filter rules that only the server
+knows about, so the filter checking is disabled.
+.IP o
+Using the \fB\-\-old-args\fP option allows the sender to manipulate the
+requested args, so the arg checking is disabled.
+.IP o
+Reading the files-from list from the server side means that the client
+doesn't know the arg list, so the arg checking is disabled.
+.IP o
+Using \fB\-\-read-batch\fP disables both checks since the batch file's
+contents will have been verified when it was created.
+.RE
+.IP
+This option may help an under-powered client server if the extra pattern
+matching is slowing things down on a huge transfer.  It can also be used to
+work around a currently-unknown bug in the verification logic for a transfer
+from a trusted sender.
+.IP
+When using this option it is a good idea to specify a dedicated destination
+directory, as discussed in the MULTI-HOST SECURITY section.
+.IP "\fB\-\-copy-as=USER[:GROUP]\fP"
+This option instructs rsync to use the USER and (if specified after a
+colon) the GROUP for the copy operations.  This only works if the user that
+is running rsync has the ability to change users.  If the group is not
+specified then the user's default groups are used.
+.IP
+This option can help to reduce the risk of an rsync being run as root into
+or out of a directory that might have live changes happening to it and you
+want to make sure that root-level read or write actions of system files are
+not possible.  While you could alternatively run all of rsync as the
+specified user, sometimes you need the root-level host-access credentials
+to be used, so this allows rsync to drop root for the copying part of the
+operation after the remote-shell or daemon connection is established.
+.IP
+The option only affects one side of the transfer unless the transfer is
+local, in which case it affects both sides.  Use the
+\fB\-\-remote-option\fP to affect the remote side, such as
+\fB\-M\-\-copy-as=joe\fP.  For a local transfer, the lsh (or lsh.sh) support file
+provides a local-shell helper script that can be used to allow a
+"localhost:" or "lh:" host-spec to be specified without needing to setup
+any remote shells, allowing you to specify remote options that affect the
+side of the transfer that is using the host-spec (and using hostname "lh"
+avoids the overriding of the remote directory to the user's home dir).
+.IP
+For example, the following rsync writes the local files as user "joe":
+.RS 4
+.IP
+.nf
+sudo rsync -aiv --copy-as=joe host1:backups/joe/ /home/joe/
+.fi
+.RE
+.IP
+This makes all files owned by user "joe", limits the groups to those that
+are available to that user, and makes it impossible for the joe user to do
+a timed exploit of the path to induce a change to a file that the joe user
+has no permissions to change.
+.IP
+The following command does a local copy into the "dest/" dir as user "joe"
+(assuming you've installed support/lsh into a dir on your $PATH):
+.RS 4
+.IP
+.nf
+sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/
+.fi
+.RE
+.IP "\fB\-\-temp-dir=DIR\fP, \fB\-T\fP"
+This option instructs rsync to use DIR as a scratch directory when creating
+temporary copies of the files transferred on the receiving side.  The
+default behavior is to create each temporary file in the same directory as
+the associated destination file.  Beginning with rsync 3.1.1, the temp-file
+names inside the specified DIR will not be prefixed with an extra dot
+(though they will still have a random suffix added).
+.IP
+This option is most often used when the receiving disk partition does not
+have enough free space to hold a copy of the largest file in the transfer.
+In this case (i.e. when the scratch directory is on a different disk
+partition), rsync will not be able to rename each received temporary file
+over the top of the associated destination file, but instead must copy it
+into place.  Rsync does this by copying the file over the top of the
+destination file, which means that the destination file will contain
+truncated data during this copy.  If this were not done this way (even if
+the destination file were first removed, the data locally copied to a
+temporary file in the destination directory, and then renamed into place)
+it would be possible for the old file to continue taking up disk space (if
+someone had it open), and thus there might not be enough room to fit the
+new version on the disk at the same time.
+.IP
+If you are using this option for reasons other than a shortage of disk
+space, you may wish to combine it with the \fB\-\-delay-updates\fP
+option, which will ensure that all copied files get put into subdirectories
+in the destination hierarchy, awaiting the end of the transfer.  If you
+don't have enough room to duplicate all the arriving files on the
+destination partition, another way to tell rsync that you aren't overly
+concerned about disk space is to use the \fB\-\-partial-dir\fP option
+with a relative path; because this tells rsync that it is OK to stash off a
+copy of a single file in a subdir in the destination hierarchy, rsync will
+use the partial-dir as a staging area to bring over the copied file, and
+then rename it into place from there. (Specifying a \fB\-\-partial-dir\fP
+with an absolute path does not have this side-effect.)
+.IP "\fB\-\-fuzzy\fP, \fB\-y\fP"
+This option tells rsync that it should look for a basis file for any
+destination file that is missing.  The current algorithm looks in the same
+directory as the destination file for either a file that has an identical
+size and modified-time, or a similarly-named file.  If found, rsync uses
+the fuzzy basis file to try to speed up the transfer.
+.IP
+If the option is repeated, the fuzzy scan will also be done in any matching
+alternate destination directories that are specified via
+\fB\-\-compare-dest\fP, \fB\-\-copy-dest\fP, or \fB\-\-link-dest\fP.
+.IP
+Note that the use of the \fB\-\-delete\fP option might get rid of any
+potential fuzzy-match files, so either use \fB\-\-delete-after\fP or
+specify some filename exclusions if you need to prevent this.
+.IP "\fB\-\-compare-dest=DIR\fP"
+This option instructs rsync to use \fIDIR\fP on the destination machine as an
+additional hierarchy to compare destination files against doing transfers
+(if the files are missing in the destination directory).  If a file is
+found in \fIDIR\fP that is identical to the sender's file, the file will NOT be
+transferred to the destination directory.  This is useful for creating a
+sparse backup of just files that have changed from an earlier backup.  This
+option is typically used to copy into an empty (or newly created)
+directory.
+.IP
+Beginning in version 2.6.4, multiple \fB\-\-compare-dest\fP directories may be
+provided, which will cause rsync to search the list in the order specified
+for an exact match.  If a match is found that differs only in attributes, a
+local copy is made and the attributes updated.  If a match is not found, a
+basis file from one of the \fIDIRs\fP will be selected to try to speed up the
+transfer.
+.IP
+If \fIDIR\fP is a relative path, it is relative to the destination directory.
+See also \fB\-\-copy-dest\fP and \fB\-\-link-dest\fP.
+.IP
+NOTE: beginning with version 3.1.0, rsync will remove a file from a
+non-empty destination hierarchy if an exact match is found in one of the
+compare-dest hierarchies (making the end result more closely match a fresh
+copy).
+.IP "\fB\-\-copy-dest=DIR\fP"
+This option behaves like \fB\-\-compare-dest\fP, but rsync will also copy
+unchanged files found in \fIDIR\fP to the destination directory using a local
+copy.  This is useful for doing transfers to a new destination while
+leaving existing files intact, and then doing a flash-cutover when all
+files have been successfully transferred.
+.IP
+Multiple \fB\-\-copy-dest\fP directories may be provided, which will cause rsync
+to search the list in the order specified for an unchanged file.  If a
+match is not found, a basis file from one of the \fIDIRs\fP will be selected to
+try to speed up the transfer.
+.IP
+If \fIDIR\fP is a relative path, it is relative to the destination directory.
+See also \fB\-\-compare-dest\fP and \fB\-\-link-dest\fP.
+.IP "\fB\-\-link-dest=DIR\fP"
+This option behaves like \fB\-\-copy-dest\fP, but unchanged files are
+hard linked from \fIDIR\fP to the destination directory.  The files must be
+identical in all preserved attributes (e.g. permissions, possibly
+ownership) in order for the files to be linked together.  An example:
+.RS 4
+.IP
+.nf
+rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
+.fi
+.RE
+.IP
+If files aren't linking, double-check their attributes.  Also check if
+some attributes are getting forced outside of rsync's control, such a mount
+option that squishes root to a single user, or mounts a removable drive
+with generic ownership (such as OS X's "Ignore ownership on this volume"
+option).
+.IP
+Beginning in version 2.6.4, multiple \fB\-\-link-dest\fP directories may be
+provided, which will cause rsync to search the list in the order specified
+for an exact match (there is a limit of 20 such directories).  If a match
+is found that differs only in attributes, a local copy is made and the
+attributes updated.  If a match is not found, a basis file from one of the
+\fIDIRs\fP will be selected to try to speed up the transfer.
+.IP
+This option works best when copying into an empty destination hierarchy, as
+existing files may get their attributes tweaked, and that can affect
+alternate destination files via hard-links.  Also, itemizing of changes can
+get a bit muddled.  Note that prior to version 3.1.0, an
+alternate-directory exact match would never be found (nor linked into the
+destination) when a destination file already exists.
+.IP
+Note that if you combine this option with \fB\-\-ignore-times\fP, rsync will not
+link any files together because it only links identical files together as a
+substitute for transferring the file, never as an additional check after
+the file is updated.
+.IP
+If \fIDIR\fP is a relative path, it is relative to the destination directory.
+See also \fB\-\-compare-dest\fP and \fB\-\-copy-dest\fP.
+.IP
+Note that rsync versions prior to 2.6.1 had a bug that could prevent
+\fB\-\-link-dest\fP from working properly for a non-super-user when
+\fB\-\-owner\fP (\fB\-o\fP) was specified (or implied).  You can work-around
+this bug by avoiding the \fB\-o\fP option (or using \fB\-\-no-o\fP) when sending to an
+old rsync.
+.IP "\fB\-\-compress\fP, \fB\-z\fP"
+With this option, rsync compresses the file data as it is sent to the
+destination machine, which reduces the amount of data being transmitted\ \-\-
+something that is useful over a slow connection.
+.IP
+Rsync supports multiple compression methods and will choose one for you
+unless you force the choice using the \fB\-\-compress-choice\fP (\fB\-\-zc\fP)
+option.
+.IP
+Run \fBrsync\ \-\-version\fP to see the default compress list compiled into your
+version.
+.IP
+When both sides of the transfer are at least 3.2.0, rsync chooses the first
+algorithm in the client's list of choices that is also in the server's list
+of choices.  If no common compress choice is found, rsync exits with
+an error.  If the remote rsync is too old to support checksum negotiation,
+its list is assumed to be "zlib".
+.IP
+The default order can be customized by setting the environment variable
+\fBRSYNC_COMPRESS_LIST\fP to a space-separated list of acceptable
+compression names.  If the string contains a "\fB&\fP" character, it is
+separated into the "client string & server string", otherwise the same
+string applies to both.  If the string (or string portion) contains no
+non-whitespace characters, the default compress list is used.  Any unknown
+compression names are discarded from the list, but a list with only invalid
+names results in a failed negotiation.
+.IP
+There are some older rsync versions that were configured to reject a \fB\-z\fP
+option and require the use of \fB\-zz\fP because their compression library was
+not compatible with the default zlib compression method.  You can usually
+ignore this weirdness unless the rsync server complains and tells you to
+specify \fB\-zz\fP.
+.IP "\fB\-\-compress-choice=STR\fP, \fB\-\-zc=STR\fP"
+This option can be used to override the automatic negotiation of the
+compression algorithm that occurs when \fB\-\-compress\fP is used.  The
+option implies \fB\-\-compress\fP unless "none" was specified, which
+instead implies \fB\-\-no-compress\fP.
+.IP
+The compression options that you may be able to use are:
+.IP
+.RS
+.IP o
+\fBzstd\fP
+.IP o
+\fBlz4\fP
+.IP o
+\fBzlibx\fP
+.IP o
+\fBzlib\fP
+.IP o
+\fBnone\fP
+.RE
+.IP
+Run \fBrsync\ \-\-version\fP to see the default compress list compiled into your
+version (which may differ from the list above).
+.IP
+Note that if you see an error about an option named \fB\-\-old-compress\fP or
+\fB\-\-new-compress\fP, this is rsync trying to send the \fB\-\-compress-choice=zlib\fP
+or \fB\-\-compress-choice=zlibx\fP option in a backward-compatible manner that
+more rsync versions understand.  This error indicates that the older rsync
+version on the server will not allow you to force the compression type.
+.IP
+Note that the "zlibx" compression algorithm is just the "zlib" algorithm
+with matched data excluded from the compression stream (to try to make it
+more compatible with an external zlib implementation).
+.IP "\fB\-\-compress-level=NUM\fP, \fB\-\-zl=NUM\fP"
+Explicitly set the compression level to use (see \fB\-\-compress\fP,
+\fB\-z\fP) instead of letting it default.  The \fB\-\-compress\fP option is
+implied as long as the level chosen is not a "don't compress" level for the
+compression algorithm that is in effect (e.g. zlib compression treats level
+0 as "off").
+.IP
+The level values vary depending on the checksum in effect.  Because rsync
+will negotiate a checksum choice by default (when the remote rsync is new
+enough), it can be good to combine this option with a
+\fB\-\-compress-choice\fP (\fB\-\-zc\fP) option unless you're sure of the
+choice in effect.  For example:
+.RS 4
+.IP
+.nf
+rsync -aiv --zc=zstd --zl=22 host:src/ dest/
+.fi
+.RE
+.IP
+For zlib & zlibx compression the valid values are from 1 to 9 with 6 being
+the default.  Specifying \fB\-\-zl=0\fP turns compression off, and specifying
+\fB\-\-zl=\-1\fP chooses the default level of 6.
+.IP
+For zstd compression the valid values are from \-131072 to 22 with 3 being
+the default. Specifying 0 chooses the default of 3.
+.IP
+For lz4 compression there are no levels, so the value is always 0.
+.IP
+If you specify a too-large or too-small value, the number is silently
+limited to a valid value.  This allows you to specify something like
+\fB\-\-zl=999999999\fP and be assured that you'll end up with the maximum
+compression level no matter what algorithm was chosen.
+.IP
+If you want to know the compression level that is in effect, specify
+\fB\-\-debug=nstr\fP to see the "negotiated string" results.  This will
+report something like "\fBClient\ compress:\ zstd\ (level\ 3)\fP" (along with the
+checksum choice in effect).
+.IP "\fB\-\-skip-compress=LIST\fP"
+\fBNOTE:\fP no compression method currently supports per-file compression
+changes, so this option has no effect.
+.IP
+Override the list of file suffixes that will be compressed as little as
+possible.  Rsync sets the compression level on a per-file basis based on
+the file's suffix.  If the compression algorithm has an "off" level, then
+no compression occurs for those files.  Other algorithms that support
+changing the streaming level on-the-fly will have the level minimized to
+reduces the CPU usage as much as possible for a matching file.
+.IP
+The \fBLIST\fP should be one or more file suffixes (without the dot) separated
+by slashes (\fB/\fP).  You may specify an empty string to indicate that no files
+should be skipped.
+.IP
+Simple character-class matching is supported: each must consist of a list
+of letters inside the square brackets (e.g. no special classes, such as
+"[:alpha:]", are supported, and '\-' has no special meaning).
+.IP
+The characters asterisk (\fB*\fP) and question-mark (\fB?\fP) have no special meaning.
+.IP
+Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
+matches 2 suffixes):
+.RS 4
+.IP
+.nf
+--skip-compress=gz/jpg/mp[34]/7z/bz2
+.fi
+.RE
+.IP
+The default file suffixes in the skip-compress list in this version of
+rsync are:
+.RS 4
+.IP
+3g2
+3gp
+7z
+aac
+ace
+apk
+avi
+bz2
+deb
+dmg
+ear
+f4v
+flac
+flv
+gpg
+gz
+iso
+jar
+jpeg
+jpg
+lrz
+lz
+lz4
+lzma
+lzo
+m1a
+m1v
+m2a
+m2ts
+m2v
+m4a
+m4b
+m4p
+m4r
+m4v
+mka
+mkv
+mov
+mp1
+mp2
+mp3
+mp4
+mpa
+mpeg
+mpg
+mpv
+mts
+odb
+odf
+odg
+odi
+odm
+odp
+ods
+odt
+oga
+ogg
+ogm
+ogv
+ogx
+opus
+otg
+oth
+otp
+ots
+ott
+oxt
+png
+qt
+rar
+rpm
+rz
+rzip
+spx
+squashfs
+sxc
+sxd
+sxg
+sxm
+sxw
+sz
+tbz
+tbz2
+tgz
+tlz
+ts
+txz
+tzo
+vob
+war
+webm
+webp
+xz
+z
+zip
+zst
+.RE
+.IP
+This list will be replaced by your \fB\-\-skip-compress\fP list in all but one
+situation: a copy from a daemon rsync will add your skipped suffixes to its
+list of non-compressing files (and its list may be configured to a
+different default).
+.IP "\fB\-\-numeric-ids\fP"
+With this option rsync will transfer numeric group and user IDs rather than
+using user and group names and mapping them at both ends.
+.IP
+By default rsync will use the username and groupname to determine what
+ownership to give files.  The special uid 0 and the special group 0 are
+never mapped via user/group names even if the \fB\-\-numeric-ids\fP option is not
+specified.
+.IP
+If a user or group has no name on the source system or it has no match on
+the destination system, then the numeric ID from the source system is used
+instead.  See also the \fBuse\ chroot\fP setting
+in the rsyncd.conf manpage for some comments on how the chroot setting
+affects rsync's ability to look up the names of the users and groups and
+what you can do about it.
+.IP "\fB\-\-usermap=STRING\fP, \fB\-\-groupmap=STRING\fP"
+These options allow you to specify users and groups that should be mapped
+to other values by the receiving side.  The \fBSTRING\fP is one or more
+\fBFROM\fP:\fBTO\fP pairs of values separated by commas.  Any matching \fBFROM\fP
+value from the sender is replaced with a \fBTO\fP value from the receiver.
+You may specify usernames or user IDs for the \fBFROM\fP and \fBTO\fP values,
+and the \fBFROM\fP value may also be a wild-card string, which will be
+matched against the sender's names (wild-cards do NOT match against ID
+numbers, though see below for why a '\fB*\fP' matches everything).  You may
+instead specify a range of ID numbers via an inclusive range: LOW-HIGH.
+For example:
+.RS 4
+.IP
+.nf
+--usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr
+.fi
+.RE
+.IP
+The first match in the list is the one that is used.  You should specify
+all your user mappings using a single \fB\-\-usermap\fP option, and/or all your
+group mappings using a single \fB\-\-groupmap\fP option.
+.IP
+Note that the sender's name for the 0 user and group are not transmitted to
+the receiver, so you should either match these values using a 0, or use the
+names in effect on the receiving side (typically "root").  All other
+\fBFROM\fP names match those in use on the sending side.  All \fBTO\fP names
+match those in use on the receiving side.
+.IP
+Any IDs that do not have a name on the sending side are treated as having
+an empty name for the purpose of matching.  This allows them to be matched
+via a "\fB*\fP" or using an empty name.  For instance:
+.RS 4
+.IP
+.nf
+--usermap=:nobody --groupmap=*:nobody
+.fi
+.RE
+.IP
+When the \fB\-\-numeric-ids\fP option is used, the sender does not send any
+names, so all the IDs are treated as having an empty name.  This means that
+you will need to specify numeric \fBFROM\fP values if you want to map these
+nameless IDs to different values.
+.IP
+For the \fB\-\-usermap\fP option to work, the receiver will need to be running as
+a super-user (see also the \fB\-\-super\fP and \fB\-\-fake-super\fP
+options).  For the \fB\-\-groupmap\fP option to work, the receiver will need to
+have permissions to set that group.
+.IP
+Starting with rsync 3.2.4, the \fB\-\-usermap\fP option implies the
+\fB\-\-owner\fP (\fB\-o\fP) option while the \fB\-\-groupmap\fP option implies the
+\fB\-\-group\fP (\fB\-g\fP) option (since rsync needs to have those options
+enabled for the mapping options to work).
+.IP
+An older rsync client may need to use \fB\-s\fP to avoid a complaint
+about wildcard characters, but a modern rsync handles this automatically.
+.IP "\fB\-\-chown=USER:GROUP\fP"
+This option forces all files to be owned by USER with group GROUP.  This is
+a simpler interface than using \fB\-\-usermap\fP & \fB\-\-groupmap\fP
+directly, but it is implemented using those options internally so they
+cannot be mixed.  If either the USER or GROUP is empty, no mapping for the
+omitted user/group will occur.  If GROUP is empty, the trailing colon may
+be omitted, but if USER is empty, a leading colon must be supplied.
+.IP
+If you specify "\fB\-\-chown=foo:bar\fP", this is exactly the same as specifying
+"\fB\-\-usermap=*:foo\ \-\-groupmap=*:bar\fP", only easier (and with the same
+implied \fB\-\-owner\fP and/or \fB\-\-group\fP options).
+.IP
+An older rsync client may need to use \fB\-s\fP to avoid a complaint
+about wildcard characters, but a modern rsync handles this automatically.
+.IP "\fB\-\-timeout=SECONDS\fP"
+This option allows you to set a maximum I/O timeout in seconds.  If no data
+is transferred for the specified time then rsync will exit.  The default is
+0, which means no timeout.
+.IP "\fB\-\-contimeout=SECONDS\fP"
+This option allows you to set the amount of time that rsync will wait for
+its connection to an rsync daemon to succeed.  If the timeout is reached,
+rsync exits with an error.
+.IP "\fB\-\-address=ADDRESS\fP"
+By default rsync will bind to the wildcard address when connecting to an
+rsync daemon.  The \fB\-\-address\fP option allows you to specify a specific IP
+address (or hostname) to bind to.
+.IP
+See also the daemon version of the \fB\-\-address\fP option.
+.IP "\fB\-\-port=PORT\fP"
+This specifies an alternate TCP port number to use rather than the default
+of 873.  This is only needed if you are using the double-colon (::) syntax
+to connect with an rsync daemon (since the URL syntax has a way to specify
+the port as a part of the URL).
+.IP
+See also the daemon version of the \fB\-\-port\fP option.
+.IP "\fB\-\-sockopts=OPTIONS\fP"
+This option can provide endless fun for people who like to tune their
+systems to the utmost degree.  You can set all sorts of socket options
+which may make transfers faster (or slower!).  Read the manpage for the
+\fBsetsockopt()\fP system call for details on some of the options you may be
+able to set.  By default no special socket options are set.  This only
+affects direct socket connections to a remote rsync daemon.
+.IP
+See also the daemon version of the \fB\-\-sockopts\fP option.
+.IP "\fB\-\-blocking-io\fP"
+This tells rsync to use blocking I/O when launching a remote shell
+transport.  If the remote shell is either rsh or remsh, rsync defaults to
+using blocking I/O, otherwise it defaults to using non-blocking I/O. (Note
+that ssh prefers non-blocking I/O.)
+.IP "\fB\-\-outbuf=MODE\fP"
+This sets the output buffering mode.  The mode can be None (aka
+Unbuffered), Line, or Block (aka Full).  You may specify as little as a
+single letter for the mode, and use upper or lower case.
+.IP
+The main use of this option is to change Full buffering to Line buffering
+when rsync's output is going to a file or pipe.
+.IP "\fB\-\-itemize-changes\fP, \fB\-i\fP"
+Requests a simple itemized list of the changes that are being made to each
+file, including attribute changes.  This is exactly the same as specifying
+\fB\-\-out-format='%i\ %n%L'\fP.  If you repeat the option, unchanged
+files will also be output, but only if the receiving rsync is at least
+version 2.6.7 (you can use \fB\-vv\fP with older versions of rsync, but that
+also turns on the output of other verbose messages).
+.IP
+The "%i" escape has a cryptic output that is 11 letters long.  The general
+format is like the string \fBYXcstpoguax\fP, where \fBY\fP is replaced by the type
+of update being done, \fBX\fP is replaced by the file-type, and the other
+letters represent attributes that may be output if they are being modified.
+.IP
+The update types that replace the \fBY\fP are as follows:
+.IP
+.RS
+.IP o
+A \fB<\fP means that a file is being transferred to the remote host (sent).
+.IP o
+A \fB>\fP means that a file is being transferred to the local host
+(received).
+.IP o
+A \fBc\fP means that a local change/creation is occurring for the item (such
+as the creation of a directory or the changing of a symlink, etc.).
+.IP o
+A \fBh\fP means that the item is a hard link to another item (requires
+\fB\-\-hard-links\fP).
+.IP o
+A \fB.\fP means that the item is not being updated (though it might have
+attributes that are being modified).
+.IP o
+A \fB*\fP means that the rest of the itemized-output area contains a message
+(e.g. "deleting").
+.RE
+.IP
+The file-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a
+directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a
+special file (e.g. named sockets and fifos).
+.IP
+The other letters in the string indicate if some attributes of the file
+have changed, as follows:
+.IP
+.RS
+.IP o
+"\fB.\fP" \- the attribute is unchanged.
+.IP o
+"\fB+\fP" \- the file is newly created.
+.IP o
+"\fB\ \fP" \- all the attributes are unchanged (all dots turn to spaces).
+.IP o
+"\fB?\fP" \- the change is unknown (when the remote rsync is old).
+.IP o
+A letter indicates an attribute is being updated.
+.RE
+.IP
+The attribute that is associated with each letter is as follows:
+.IP
+.RS
+.IP o
+A \fBc\fP means either that a regular file has a different checksum (requires
+\fB\-\-checksum\fP) or that a symlink, device, or special file has a
+changed value.  Note that if you are sending files to an rsync prior to
+3.0.1, this change flag will be present only for checksum-differing
+regular files.
+.IP o
+A \fBs\fP means the size of a regular file is different and will be updated
+by the file transfer.
+.IP o
+A \fBt\fP means the modification time is different and is being updated to
+the sender's value (requires \fB\-\-times\fP).  An alternate value of
+\fBT\fP means that the modification time will be set to the transfer time,
+which happens when a file/symlink/device is updated without
+\fB\-\-times\fP and when a symlink is changed and the receiver can't
+set its time. (Note: when using an rsync 3.0.0 client, you might see the
+\fBs\fP flag combined with \fBt\fP instead of the proper \fBT\fP flag for this
+time-setting failure.)
+.IP o
+A \fBp\fP means the permissions are different and are being updated to the
+sender's value (requires \fB\-\-perms\fP).
+.IP o
+An \fBo\fP means the owner is different and is being updated to the sender's
+value (requires \fB\-\-owner\fP and super-user privileges).
+.IP o
+A \fBg\fP means the group is different and is being updated to the sender's
+value (requires \fB\-\-group\fP and the authority to set the group).
+.IP o
+.IP
+.RS
+.IP o
+A \fBu\fP|\fBn\fP|\fBb\fP indicates the following information:
+
+\fBu\fP  means the access (use) time is different and is being updated to
+the sender's value (requires \fB\-\-atimes\fP)
+.IP o
+\fBn\fP means the create time (newness) is different and is being updated
+to the sender's value (requires \fB\-\-crtimes\fP)
+.IP o
+\fBb\fP means that both the access and create times are being updated
+.RE
+.IP o
+The \fBa\fP means that the ACL information is being changed.
+.IP o
+The \fBx\fP means that the extended attribute information is being changed.
+.RE
+.IP
+One other output is possible: when deleting files, the "%i" will output the
+string "\fB*deleting\fP" for each item that is being removed (assuming that you
+are talking to a recent enough rsync that it logs deletions instead of
+outputting them as a verbose message).
+.IP "\fB\-\-out-format=FORMAT\fP"
+This allows you to specify exactly what the rsync client outputs to the
+user on a per-update basis.  The format is a text string containing
+embedded single-character escape sequences prefixed with a percent (%)
+character.  A default format of "%n%L" is assumed if either
+\fB\-\-info=name\fP or \fB\-v\fP is specified (this tells you just the
+name of the file and, if the item is a link, where it points).  For a full
+list of the possible escape characters, see the \fBlog\ format\fP setting in the rsyncd.conf manpage.
+.IP
+Specifying the \fB\-\-out-format\fP option implies the \fB\-\-info=name\fP
+option, which will mention each file, dir, etc. that gets updated in a
+significant way (a transferred file, a recreated symlink/device, or a
+touched directory).  In addition, if the itemize-changes escape (%i) is
+included in the string (e.g. if the \fB\-\-itemize-changes\fP option was
+used), the logging of names increases to mention any item that is changed
+in any way (as long as the receiving side is at least 2.6.4).  See the
+\fB\-\-itemize-changes\fP option for a description of the output of "%i".
+.IP
+Rsync will output the out-format string prior to a file's transfer unless
+one of the transfer-statistic escapes is requested, in which case the
+logging is done at the end of the file's transfer.  When this late logging
+is in effect and \fB\-\-progress\fP is also specified, rsync will also
+output the name of the file being transferred prior to its progress
+information (followed, of course, by the out-format output).
+.IP "\fB\-\-log-file=FILE\fP"
+This option causes rsync to log what it is doing to a file.  This is
+similar to the logging that a daemon does, but can be requested for the
+client side and/or the server side of a non-daemon transfer.  If specified
+as a client option, transfer logging will be enabled with a default format
+of "%i %n%L".  See the \fB\-\-log-file-format\fP option if you wish to
+override this.
+.IP
+Here's an example command that requests the remote side to log what is
+happening:
+.RS 4
+.IP
+.nf
+rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
+.fi
+.RE
+.IP
+This is very useful if you need to debug why a connection is closing
+unexpectedly.
+.IP
+See also the daemon version of the \fB\-\-log-file\fP option.
+.IP "\fB\-\-log-file-format=FORMAT\fP"
+This allows you to specify exactly what per-update logging is put into the
+file specified by the \fB\-\-log-file\fP option (which must also be
+specified for this option to have any effect).  If you specify an empty
+string, updated files will not be mentioned in the log file.  For a list of
+the possible escape characters, see the \fBlog\ format\fP
+setting in the rsyncd.conf manpage.
+.IP
+The default FORMAT used if \fB\-\-log-file\fP is specified and this
+option is not is '%i %n%L'.
+.IP
+See also the daemon version of the \fB\-\-log-file-format\fP
+option.
+.IP "\fB\-\-stats\fP"
+This tells rsync to print a verbose set of statistics on the file transfer,
+allowing you to tell how effective rsync's delta-transfer algorithm is for
+your data.  This option is equivalent to \fB\-\-info=stats2\fP if
+combined with 0 or 1 \fB\-v\fP options, or \fB\-\-info=stats3\fP if
+combined with 2 or more \fB\-v\fP options.
+.IP
+The current statistics are as follows:
+.IP
+.RS
+.IP o
+\fBNumber\ of\ files\fP is the count of all "files" (in the generic sense),
+which includes directories, symlinks, etc.  The total count will be
+followed by a list of counts by filetype (if the total is non-zero).  For
+example: "(reg: 5, dir: 3, link: 2, dev: 1, special: 1)" lists the totals
+for regular files, directories, symlinks, devices, and special files.  If
+any of value is 0, it is completely omitted from the list.
+.IP o
+\fBNumber\ of\ created\ files\fP is the count of how many "files" (generic
+sense) were created (as opposed to updated).  The total count will be
+followed by a list of counts by filetype (if the total is non-zero).
+.IP o
+\fBNumber\ of\ deleted\ files\fP is the count of how many "files" (generic
+sense) were deleted.  The total count will be
+followed by a list of counts by filetype (if the total is non-zero).
+Note that this line is only output if deletions are in effect, and only
+if protocol 31 is being used (the default for rsync 3.1.x).
+.IP o
+\fBNumber\ of\ regular\ files\ transferred\fP is the count of normal files that
+were updated via rsync's delta-transfer algorithm, which does not include
+dirs, symlinks, etc.  Note that rsync 3.1.0 added the word "regular" into
+this heading.
+.IP o
+\fBTotal\ file\ size\fP is the total sum of all file sizes in the transfer.
+This does not count any size for directories or special files, but does
+include the size of symlinks.
+.IP o
+\fBTotal\ transferred\ file\ size\fP is the total sum of all files sizes for
+just the transferred files.
+.IP o
+\fBLiteral\ data\fP is how much unmatched file-update data we had to send to
+the receiver for it to recreate the updated files.
+.IP o
+\fBMatched\ data\fP is how much data the receiver got locally when recreating
+the updated files.
+.IP o
+\fBFile\ list\ size\fP is how big the file-list data was when the sender sent
+it to the receiver.  This is smaller than the in-memory size for the file
+list due to some compressing of duplicated data when rsync sends the
+list.
+.IP o
+\fBFile\ list\ generation\ time\fP is the number of seconds that the sender
+spent creating the file list.  This requires a modern rsync on the
+sending side for this to be present.
+.IP o
+\fBFile\ list\ transfer\ time\fP is the number of seconds that the sender spent
+sending the file list to the receiver.
+.IP o
+\fBTotal\ bytes\ sent\fP is the count of all the bytes that rsync sent from the
+client side to the server side.
+.IP o
+\fBTotal\ bytes\ received\fP is the count of all non-message bytes that rsync
+received by the client side from the server side. "Non-message" bytes
+means that we don't count the bytes for a verbose message that the server
+sent to us, which makes the stats more consistent.
+.RE
+.IP "\fB\-\-8-bit-output\fP, \fB\-8\fP"
+This tells rsync to leave all high-bit characters unescaped in the output
+instead of trying to test them to see if they're valid in the current
+locale and escaping the invalid ones.  All control characters (but never
+tabs) are always escaped, regardless of this option's setting.
+.IP
+The escape idiom that started in 2.6.7 is to output a literal backslash
+(\fB\\\fP) and a hash (\fB#\fP), followed by exactly 3 octal digits.  For example, a
+newline would output as "\fB\\#012\fP".  A literal backslash that is in a
+filename is not escaped unless it is followed by a hash and 3 digits (0-9).
+.IP "\fB\-\-human-readable\fP, \fB\-h\fP"
+Output numbers in a more human-readable format.  There are 3 possible levels:
+.RS
+.IP
+.IP 1.
+output numbers with a separator between each set of 3 digits (either a
+comma or a period, depending on if the decimal point is represented by a
+period or a comma).
+.IP 2.
+output numbers in units of 1000 (with a character suffix for larger
+units\ \-\- see below).
+.IP 3.
+output numbers in units of 1024.
+.RE
+.IP
+The default is human-readable level 1.  Each \fB\-h\fP option increases the
+level by one.  You can take the level down to 0 (to output numbers as pure
+digits) by specifying the \fB\-\-no-human-readable\fP (\fB\-\-no-h\fP) option.
+.IP
+The unit letters that are appended in levels 2 and 3 are: \fBK\fP (kilo), \fBM\fP
+(mega), \fBG\fP (giga), \fBT\fP (tera), or \fBP\fP (peta).  For example, a 1234567-byte
+file would output as 1.23M in level-2 (assuming that a period is your local
+decimal point).
+.IP
+Backward compatibility note: versions of rsync prior to 3.1.0 do not
+support human-readable level 1, and they default to level 0.  Thus,
+specifying one or two \fB\-h\fP options will behave in a comparable manner in
+old and new versions as long as you didn't specify a \fB\-\-no-h\fP option prior
+to one or more \fB\-h\fP options.  See the \fB\-\-list-only\fP option for one
+difference.
+.IP "\fB\-\-partial\fP"
+By default, rsync will delete any partially transferred file if the
+transfer is interrupted.  In some circumstances it is more desirable to
+keep partially transferred files.  Using the \fB\-\-partial\fP option tells rsync
+to keep the partial file which should make a subsequent transfer of the
+rest of the file much faster.
+.IP "\fB\-\-partial-dir=DIR\fP"
+This option modifies the behavior of the \fB\-\-partial\fP option while
+also implying that it be enabled.  This enhanced partial-file method puts
+any partially transferred files into the specified \fIDIR\fP instead of writing
+the partial file out to the destination file.  On the next transfer, rsync
+will use a file found in this dir as data to speed up the resumption of the
+transfer and then delete it after it has served its purpose.
+.IP
+Note that if \fB\-\-whole-file\fP is specified (or implied), any
+partial-dir files that are found for a file that is being updated will
+simply be removed (since rsync is sending files without using rsync's
+delta-transfer algorithm).
+.IP
+Rsync will create the \fIDIR\fP if it is missing, but just the last dir\ \-\- not
+the whole path.  This makes it easy to use a relative path (such as
+"\fB\-\-partial-dir=.rsync-partial\fP") to have rsync create the
+partial-directory in the destination file's directory when it is needed,
+and then remove it again when the partial file is deleted.  Note that this
+directory removal is only done for a relative pathname, as it is expected
+that an absolute path is to a directory that is reserved for partial-dir
+work.
+.IP
+If the partial-dir value is not an absolute path, rsync will add an exclude
+rule at the end of all your existing excludes.  This will prevent the
+sending of any partial-dir files that may exist on the sending side, and
+will also prevent the untimely deletion of partial-dir items on the
+receiving side.  An example: the above \fB\-\-partial-dir\fP option would add the
+equivalent of this "perishable" exclude at the end of any other filter
+rules: \fB\-f\ '\-p\ .rsync-partial/'\fP
+.IP
+If you are supplying your own exclude rules, you may need to add your own
+exclude/hide/protect rule for the partial-dir because:
+.RS
+.IP
+.IP 1.
+the auto-added rule may be ineffective at the end of your other rules, or
+.IP 2.
+you may wish to override rsync's exclude choice.
+.RE
+.IP
+For instance, if you want to make rsync clean-up any left-over partial-dirs
+that may be lying around, you should specify \fB\-\-delete-after\fP and
+add a "risk" filter rule, e.g.  \fB\-f\ 'R\ .rsync-partial/'\fP. Avoid using
+\fB\-\-delete-before\fP or \fB\-\-delete-during\fP unless you don't
+need rsync to use any of the left-over partial-dir data during the current
+run.
+.IP
+IMPORTANT: the \fB\-\-partial-dir\fP should not be writable by other users or it
+is a security risk!  E.g. AVOID "/tmp"!
+.IP
+You can also set the partial-dir value the \fBRSYNC_PARTIAL_DIR\fP
+environment variable.  Setting this in the environment does not force
+\fB\-\-partial\fP to be enabled, but rather it affects where partial
+files go when \fB\-\-partial\fP is specified.  For instance, instead of
+using \fB\-\-partial-dir=.rsync-tmp\fP along with \fB\-\-progress\fP, you could
+set \fBRSYNC_PARTIAL_DIR=.rsync-tmp\fP in your environment and then use
+the \fB\-P\fP option to turn on the use of the .rsync-tmp dir for
+partial transfers.  The only times that the \fB\-\-partial\fP option does
+not look for this environment value are:
+.RS
+.IP
+.IP 1.
+when \fB\-\-inplace\fP was specified (since \fB\-\-inplace\fP
+conflicts with \fB\-\-partial-dir\fP), and
+.IP 2.
+when \fB\-\-delay-updates\fP was specified (see below).
+.RE
+.IP
+When a modern rsync resumes the transfer of a file in the partial-dir, that
+partial file is now updated in-place instead of creating yet another
+tmp-file copy (so it maxes out at dest + tmp instead of dest + partial +
+tmp).  This requires both ends of the transfer to be at least version
+3.2.0.
+.IP
+For the purposes of the daemon-config's "\fBrefuse\ options\fP" setting,
+\fB\-\-partial-dir\fP does \fInot\fP imply \fB\-\-partial\fP.  This is so that a
+refusal of the \fB\-\-partial\fP option can be used to disallow the
+overwriting of destination files with a partial transfer, while still
+allowing the safer idiom provided by \fB\-\-partial-dir\fP.
+.IP "\fB\-\-delay-updates\fP"
+This option puts the temporary file from each updated file into a holding
+directory until the end of the transfer, at which time all the files are
+renamed into place in rapid succession.  This attempts to make the updating
+of the files a little more atomic.  By default the files are placed into a
+directory named \fB.~tmp~\fP in each file's destination directory, but if
+you've specified the \fB\-\-partial-dir\fP option, that directory will be
+used instead.  See the comments in the \fB\-\-partial-dir\fP section for
+a discussion of how this \fB.~tmp~\fP dir will be excluded from the transfer,
+and what you can do if you want rsync to cleanup old \fB.~tmp~\fP dirs that
+might be lying around.  Conflicts with \fB\-\-inplace\fP and
+\fB\-\-append\fP.
+.IP
+This option implies \fB\-\-no-inc-recursive\fP since it needs the full
+file list in memory in order to be able to iterate over it at the end.
+.IP
+This option uses more memory on the receiving side (one bit per file
+transferred) and also requires enough free disk space on the receiving side
+to hold an additional copy of all the updated files.  Note also that you
+should not use an absolute path to \fB\-\-partial-dir\fP unless:
+.RS
+.IP
+.IP 1.
+there is no chance of any of the files in the transfer having the same
+name (since all the updated files will be put into a single directory if
+the path is absolute), and
+.IP 2.
+there are no mount points in the hierarchy (since the delayed updates
+will fail if they can't be renamed into place).
+.RE
+.IP
+See also the "atomic-rsync" python script in the "support" subdir for an
+update algorithm that is even more atomic (it uses \fB\-\-link-dest\fP
+and a parallel hierarchy of files).
+.IP "\fB\-\-prune-empty-dirs\fP, \fB\-m\fP"
+This option tells the receiving rsync to get rid of empty directories from
+the file-list, including nested directories that have no non-directory
+children.  This is useful for avoiding the creation of a bunch of useless
+directories when the sending rsync is recursively scanning a hierarchy of
+files using include/exclude/filter rules.
+.IP
+This option can still leave empty directories on the receiving side if you
+make use of TRANSFER_RULES.
+.IP
+Because the file-list is actually being pruned, this option also affects
+what directories get deleted when a delete is active.  However, keep in
+mind that excluded files and directories can prevent existing items from
+being deleted due to an exclude both hiding source files and protecting
+destination files.  See the perishable filter-rule option for how to avoid
+this.
+.IP
+You can prevent the pruning of certain empty directories from the file-list
+by using a global "protect" filter.  For instance, this option would ensure
+that the directory "emptydir" was kept in the file-list:
+.RS 4
+.IP
+.nf
+--filter 'protect emptydir/'
+.fi
+.RE
+.IP
+Here's an example that copies all .pdf files in a hierarchy, only creating
+the necessary destination directories to hold the .pdf files, and ensures
+that any superfluous files and directories in the destination are removed
+(note the hide filter of non-directories being used instead of an exclude):
+.RS 4
+.IP
+.nf
+rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest
+.fi
+.RE
+.IP
+If you didn't want to remove superfluous destination files, the more
+time-honored options of \fB\-\-include='*/'\ \-\-exclude='*'\fP would work
+fine in place of the hide-filter (if that is more natural to you).
+.IP "\fB\-\-progress\fP"
+This option tells rsync to print information showing the progress of the
+transfer.  This gives a bored user something to watch.  With a modern rsync
+this is the same as specifying \fB\-\-info=flist2,name,progress\fP, but
+any user-supplied settings for those info flags takes precedence (e.g.
+\fB\-\-info=flist0\ \-\-progress\fP).
+.IP
+While rsync is transferring a regular file, it updates a progress line that
+looks like this:
+.RS 4
+.IP
+.nf
+782448  63%  110.64kB/s    0:00:04
+.fi
+.RE
+.IP
+In this example, the receiver has reconstructed 782448 bytes or 63% of the
+sender's file, which is being reconstructed at a rate of 110.64 kilobytes
+per second, and the transfer will finish in 4 seconds if the current rate
+is maintained until the end.
+.IP
+These statistics can be misleading if rsync's delta-transfer algorithm is
+in use.  For example, if the sender's file consists of the basis file
+followed by additional data, the reported rate will probably drop
+dramatically when the receiver gets to the literal data, and the transfer
+will probably take much longer to finish than the receiver estimated as it
+was finishing the matched part of the file.
+.IP
+When the file transfer finishes, rsync replaces the progress line with a
+summary line that looks like this:
+.RS 4
+.IP
+.nf
+1,238,099 100%  146.38kB/s    0:00:08  (xfr#5, to-chk=169/396)
+.fi
+.RE
+.IP
+In this example, the file was 1,238,099 bytes long in total, the average
+rate of transfer for the whole file was 146.38 kilobytes per second over
+the 8 seconds that it took to complete, it was the 5th transfer of a
+regular file during the current rsync session, and there are 169 more files
+for the receiver to check (to see if they are up-to-date or not) remaining
+out of the 396 total files in the file-list.
+.IP
+In an incremental recursion scan, rsync won't know the total number of
+files in the file-list until it reaches the ends of the scan, but since it
+starts to transfer files during the scan, it will display a line with the
+text "ir-chk" (for incremental recursion check) instead of "to-chk" until
+the point that it knows the full size of the list, at which point it will
+switch to using "to-chk".  Thus, seeing "ir-chk" lets you know that the
+total count of files in the file list is still going to increase (and each
+time it does, the count of files left to check will increase by the number
+of the files added to the list).
+.IP "\fB\-P\fP"
+The \fB\-P\fP option is equivalent to "\fB\-\-partial\fP
+\fB\-\-progress\fP".  Its purpose is to make it much easier to specify
+these two options for a long transfer that may be interrupted.
+.IP
+There is also a \fB\-\-info=progress2\fP option that outputs statistics
+based on the whole transfer, rather than individual files.  Use this flag
+without outputting a filename (e.g. avoid \fB\-v\fP or specify
+\fB\-\-info=name0\fP) if you want to see how the transfer is doing
+without scrolling the screen with a lot of names. (You don't need to
+specify the \fB\-\-progress\fP option in order to use
+\fB\-\-info=progress2\fP.)
+.IP
+Finally, you can get an instant progress report by sending rsync a signal
+of either SIGINFO or SIGVTALRM.  On BSD systems, a SIGINFO is generated by
+typing a Ctrl+T (Linux doesn't currently support a SIGINFO signal).  When
+the client-side process receives one of those signals, it sets a flag to
+output a single progress report which is output when the current file
+transfer finishes (so it may take a little time if a big file is being
+handled when the signal arrives).  A filename is output (if needed)
+followed by the \fB\-\-info=progress2\fP format of progress info.  If you
+don't know which of the 3 rsync processes is the client process, it's OK to
+signal all of them (since the non-client processes ignore the signal).
+.IP
+CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.
+.IP "\fB\-\-password-file=FILE\fP"
+This option allows you to provide a password for accessing an rsync daemon
+via a file or via standard input if \fBFILE\fP is \fB\-\fP.  The file should
+contain just the password on the first line (all other lines are ignored).
+Rsync will exit with an error if \fBFILE\fP is world readable or if a
+root-run rsync command finds a non-root-owned file.
+.IP
+This option does not supply a password to a remote shell transport such as
+ssh; to learn how to do that, consult the remote shell's documentation.
+When accessing an rsync daemon using a remote shell as the transport, this
+option only comes into effect after the remote shell finishes its
+authentication (i.e. if you have also specified a password in the daemon's
+config file).
+.IP "\fB\-\-early-input=FILE\fP"
+This option allows rsync to send up to 5K of data to the "early exec"
+script on its stdin.  One possible use of this data is to give the script a
+secret that can be used to mount an encrypted filesystem (which you should
+unmount in the the "post-xfer exec" script).
+.IP
+The daemon must be at least version 3.2.1.
+.IP "\fB\-\-list-only\fP"
+This option will cause the source files to be listed instead of
+transferred.  This option is inferred if there is a single source arg and
+no destination specified, so its main uses are:
+.RS
+.IP
+.IP 1.
+to turn a copy command that includes a destination arg into a
+file-listing command, or
+.IP 2.
+to be able to specify more than one source arg.  Note: be sure to
+include the destination.
+.RE
+.IP
+CAUTION: keep in mind that a source arg with a wild-card is expanded by the
+shell into multiple args, so it is never safe to try to specify a single
+wild-card arg to try to infer this option. A safe example is:
+.RS 4
+.IP
+.nf
+rsync -av --list-only foo* dest/
+.fi
+.RE
+.IP
+This option always uses an output format that looks similar to this:
+.RS 4
+.IP
+.nf
+drwxrwxr-x          4,096 2022/09/30 12:53:11 support
+-rw-rw-r--             80 2005/01/11 10:37:37 support/Makefile
+.fi
+.RE
+.IP
+The only option that affects this output style is (as of 3.1.0) the
+\fB\-\-human-readable\fP (\fB\-h\fP) option.  The default is to output sizes
+as byte counts with digit separators (in a 14-character-width column).
+Specifying at least one \fB\-h\fP option makes the sizes output with unit
+suffixes.  If you want old-style bytecount sizes without digit separators
+(and an 11-character-width column) use \fB\-\-no-h\fP.
+.IP
+Compatibility note: when requesting a remote listing of files from an rsync
+that is version 2.6.3 or older, you may encounter an error if you ask for a
+non-recursive listing.  This is because a file listing implies the
+\fB\-\-dirs\fP option w/o \fB\-\-recursive\fP, and older rsyncs don't
+have that option.  To avoid this problem, either specify the \fB\-\-no-dirs\fP
+option (if you don't need to expand a directory's content), or turn on
+recursion and exclude the content of subdirectories: \fB\-r\ \-\-exclude='/*/*'\fP.
+.IP "\fB\-\-bwlimit=RATE\fP"
+This option allows you to specify the maximum transfer rate for the data
+sent over the socket, specified in units per second.  The RATE value can be
+suffixed with a string to indicate a size multiplier, and may be a
+fractional value (e.g. \fB\-\-bwlimit=1.5m\fP).  If no suffix is specified, the
+value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had
+been appended).  See the \fB\-\-max-size\fP option for a description of
+all the available suffixes.  A value of 0 specifies no limit.
+.IP
+For backward-compatibility reasons, the rate limit will be rounded to the
+nearest KiB unit, so no rate smaller than 1024 bytes per second is
+possible.
+.IP
+Rsync writes data over the socket in blocks, and this option both limits
+the size of the blocks that rsync writes, and tries to keep the average
+transfer rate at the requested limit.  Some burstiness may be seen where
+rsync writes out a block of data and then sleeps to bring the average rate
+into compliance.
+.IP
+Due to the internal buffering of data, the \fB\-\-progress\fP option may
+not be an accurate reflection on how fast the data is being sent.  This is
+because some files can show up as being rapidly sent when the data is
+quickly buffered, while other can show up as very slow when the flushing of
+the output buffer occurs.  This may be fixed in a future version.
+.IP
+See also the daemon version of the \fB\-\-bwlimit\fP option.
+.IP "\fB\-\-stop-after=MINS\fP, (\fB\-\-time-limit=MINS\fP)"
+This option tells rsync to stop copying when the specified number of
+minutes has elapsed.
+.IP
+For maximal flexibility, rsync does not communicate this option to the
+remote rsync since it is usually enough that one side of the connection
+quits as specified.  This allows the option's use even when only one side
+of the connection supports it.  You can tell the remote side about the time
+limit using \fB\-\-remote-option\fP (\fB\-M\fP), should the need arise.
+.IP
+The \fB\-\-time-limit\fP version of this option is deprecated.
+.IP "\fB\-\-stop-at=y-m-dTh:m\fP"
+This option tells rsync to stop copying when the specified point in time
+has been reached. The date & time can be fully specified in a numeric
+format of year-month-dayThour:minute (e.g. 2000-12-31T23:59) in the local
+timezone.  You may choose to separate the date numbers using slashes
+instead of dashes.
+.IP
+The value can also be abbreviated in a variety of ways, such as specifying
+a 2-digit year and/or leaving off various values.  In all cases, the value
+will be taken to be the next possible point in time where the supplied
+information matches.  If the value specifies the current time or a past
+time, rsync exits with an error.
+.IP
+For example, "1-30" specifies the next January 30th (at midnight local
+time), "14:00" specifies the next 2 P.M., "1" specifies the next 1st of the
+month at midnight, "31" specifies the next month where we can stop on its
+31st day, and ":59" specifies the next 59th minute after the hour.
+.IP
+For maximal flexibility, rsync does not communicate this option to the
+remote rsync since it is usually enough that one side of the connection
+quits as specified.  This allows the option's use even when only one side
+of the connection supports it.  You can tell the remote side about the time
+limit using \fB\-\-remote-option\fP (\fB\-M\fP), should the need arise.  Do
+keep in mind that the remote host may have a different default timezone
+than your local host.
+.IP "\fB\-\-fsync\fP"
+Cause the receiving side to fsync each finished file.  This may slow down
+the transfer, but can help to provide peace of mind when updating critical
+files.
+.IP "\fB\-\-write-batch=FILE\fP"
+Record a file that can later be applied to another identical destination
+with \fB\-\-read-batch\fP.  See the "BATCH MODE" section for details, and
+also the \fB\-\-only-write-batch\fP option.
+.IP
+This option overrides the negotiated checksum & compress lists and always
+negotiates a choice based on old-school md5/md4/zlib choices.  If you want
+a more modern choice, use the \fB\-\-checksum-choice\fP (\fB\-\-cc\fP) and/or
+\fB\-\-compress-choice\fP (\fB\-\-zc\fP) options.
+.IP "\fB\-\-only-write-batch=FILE\fP"
+Works like \fB\-\-write-batch\fP, except that no updates are made on the
+destination system when creating the batch.  This lets you transport the
+changes to the destination system via some other means and then apply the
+changes via \fB\-\-read-batch\fP.
+.IP
+Note that you can feel free to write the batch directly to some portable
+media: if this media fills to capacity before the end of the transfer, you
+can just apply that partial transfer to the destination and repeat the
+whole process to get the rest of the changes (as long as you don't mind a
+partially updated destination system while the multi-update cycle is
+happening).
+.IP
+Also note that you only save bandwidth when pushing changes to a remote
+system because this allows the batched data to be diverted from the sender
+into the batch file without having to flow over the wire to the receiver
+(when pulling, the sender is remote, and thus can't write the batch).
+.IP "\fB\-\-read-batch=FILE\fP"
+Apply all of the changes stored in FILE, a file previously generated by
+\fB\-\-write-batch\fP.  If \fIFILE\fP is \fB\-\fP, the batch data will be read
+from standard input. See the "BATCH MODE" section for details.
+.IP "\fB\-\-protocol=NUM\fP"
+Force an older protocol version to be used.  This is useful for creating a
+batch file that is compatible with an older version of rsync.  For
+instance, if rsync 2.6.4 is being used with the \fB\-\-write-batch\fP
+option, but rsync 2.6.3 is what will be used to run the
+\fB\-\-read-batch\fP option, you should use "\-\-protocol=28" when creating
+the batch file to force the older protocol version to be used in the batch
+file (assuming you can't upgrade the rsync on the reading system).
+.IP "\fB\-\-iconv=CONVERT_SPEC\fP"
+Rsync can convert filenames between character sets using this option.
+Using a CONVERT_SPEC of "." tells rsync to look up the default
+character-set via the locale setting.  Alternately, you can fully specify
+what conversion to do by giving a local and a remote charset separated by a
+comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g. \fB\-\-iconv=utf8,iso88591\fP.
+This order ensures that the option will stay the same whether you're
+pushing or pulling files.  Finally, you can specify either \fB\-\-no-iconv\fP or
+a CONVERT_SPEC of "\-" to turn off any conversion.  The default setting of
+this option is site-specific, and can also be affected via the
+\fBRSYNC_ICONV\fP environment variable.
+.IP
+For a list of what charset names your local iconv library supports, you can
+run "\fBiconv\ \-\-list\fP".
+.IP
+If you specify the \fB\-\-secluded-args\fP (\fB\-s\fP) option, rsync will
+translate the filenames you specify on the command-line that are being sent
+to the remote host.  See also the \fB\-\-files-from\fP option.
+.IP
+Note that rsync does not do any conversion of names in filter files
+(including include/exclude files).  It is up to you to ensure that you're
+specifying matching rules that can match on both sides of the transfer.
+For instance, you can specify extra include/exclude rules if there are
+filename differences on the two sides that need to be accounted for.
+.IP
+When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the
+daemon uses the charset specified in its "charset" configuration parameter
+regardless of the remote charset you actually pass.  Thus, you may feel
+free to specify just the local charset for a daemon transfer (e.g.
+\fB\-\-iconv=utf8\fP).
+.IP "\fB\-\-ipv4\fP, \fB\-4\fP or \fB\-\-ipv6\fP, \fB\-6\fP"
+Tells rsync to prefer IPv4/IPv6 when creating sockets or running ssh.  This
+affects sockets that rsync has direct control over, such as the outgoing
+socket when directly contacting an rsync daemon, as well as the forwarding
+of the \fB\-4\fP or \fB\-6\fP option to ssh when rsync can deduce that ssh is being
+used as the remote shell.  For other remote shells you'll need to specify
+the "\fB\-\-rsh\ SHELL\ \-4\fP" option directly (or whatever IPv4/IPv6 hint options
+it uses).
+.IP
+See also the daemon version of these options.
+.IP
+If rsync was compiled without support for IPv6, the \fB\-\-ipv6\fP option will
+have no effect.  The \fBrsync\ \-\-version\fP output will contain "\fBno\ IPv6\fP" if
+is the case.
+.IP "\fB\-\-checksum-seed=NUM\fP"
+Set the checksum seed to the integer NUM.  This 4 byte checksum seed is
+included in each block and MD4 file checksum calculation (the more modern
+MD5 file checksums don't use a seed).  By default the checksum seed is
+generated by the server and defaults to the current \fBtime\fP().  This
+option is used to set a specific checksum seed, which is useful for
+applications that want repeatable block checksums, or in the case where the
+user wants a more random checksum seed.  Setting NUM to 0 causes rsync to
+use the default of \fBtime\fP() for checksum seed.
+.P
+.SH "DAEMON OPTIONS"
+.P
+The options allowed when starting an rsync daemon are as follows:
+.P
+.IP "\fB\-\-daemon\fP"
+This tells rsync that it is to run as a daemon.  The daemon you start
+running may be accessed using an rsync client using the \fBhost::module\fP or
+\fBrsync://host/module/\fP syntax.
+.IP
+If standard input is a socket then rsync will assume that it is being run
+via inetd, otherwise it will detach from the current terminal and become a
+background daemon.  The daemon will read the config file (rsyncd.conf) on
+each connect made by a client and respond to requests accordingly.
+.IP
+See the \fBrsyncd.conf\fP(5) manpage for more details.
+.IP "\fB\-\-address=ADDRESS\fP"
+By default rsync will bind to the wildcard address when run as a daemon
+with the \fB\-\-daemon\fP option.  The \fB\-\-address\fP option allows you to specify a
+specific IP address (or hostname) to bind to.  This makes virtual hosting
+possible in conjunction with the \fB\-\-config\fP option.
+.IP
+See also the address global option in the
+rsyncd.conf manpage and the client version of the \fB\-\-address\fP
+option.
+.IP "\fB\-\-bwlimit=RATE\fP"
+This option allows you to specify the maximum transfer rate for the data
+the daemon sends over the socket.  The client can still specify a smaller
+\fB\-\-bwlimit\fP value, but no larger value will be allowed.
+.IP
+See the client version of the \fB\-\-bwlimit\fP option for some
+extra details.
+.IP "\fB\-\-config=FILE\fP"
+This specifies an alternate config file than the default.  This is only
+relevant when \fB\-\-daemon\fP is specified.  The default is
+/etc/rsyncd.conf unless the daemon is running over a remote shell program
+and the remote user is not the super-user; in that case the default is
+rsyncd.conf in the current directory (typically $HOME).
+.IP "\fB\-\-dparam=OVERRIDE\fP, \fB\-M\fP"
+This option can be used to set a daemon-config parameter when starting up
+rsync in daemon mode.  It is equivalent to adding the parameter at the end
+of the global settings prior to the first module's definition.  The
+parameter names can be specified without spaces, if you so desire.  For
+instance:
+.RS 4
+.IP
+.nf
+rsync --daemon -M pidfile=/path/rsync.pid
+.fi
+.RE
+.IP "\fB\-\-no-detach\fP"
+When running as a daemon, this option instructs rsync to not detach itself
+and become a background process.  This option is required when running as a
+service on Cygwin, and may also be useful when rsync is supervised by a
+program such as \fBdaemontools\fP or AIX's \fBSystem\ Resource\ Controller\fP.
+\fB\-\-no-detach\fP is also recommended when rsync is run under a debugger.  This
+option has no effect if rsync is run from inetd or sshd.
+.IP "\fB\-\-port=PORT\fP"
+This specifies an alternate TCP port number for the daemon to listen on
+rather than the default of 873.
+.IP
+See also the client version of the \fB\-\-port\fP option and the
+port global setting in the rsyncd.conf manpage.
+.IP "\fB\-\-log-file=FILE\fP"
+This option tells the rsync daemon to use the given log-file name instead
+of using the "\fBlog\ file\fP" setting in the config file.
+.IP
+See also the client version of the \fB\-\-log-file\fP option.
+.IP "\fB\-\-log-file-format=FORMAT\fP"
+This option tells the rsync daemon to use the given FORMAT string instead
+of using the "\fBlog\ format\fP" setting in the config file.  It also enables
+"\fBtransfer\ logging\fP" unless the string is empty, in which case transfer
+logging is turned off.
+.IP
+See also the client version of the \fB\-\-log-file-format\fP
+option.
+.IP "\fB\-\-sockopts\fP"
+This overrides the \fBsocket\ options\fP
+setting in the rsyncd.conf file and has the same syntax.
+.IP
+See also the client version of the \fB\-\-sockopts\fP option.
+.IP "\fB\-\-verbose\fP, \fB\-v\fP"
+This option increases the amount of information the daemon logs during its
+startup phase.  After the client connects, the daemon's verbosity level
+will be controlled by the options that the client used and the
+"\fBmax\ verbosity\fP" setting in the module's config section.
+.IP
+See also the client version of the \fB\-\-verbose\fP option.
+.IP "\fB\-\-ipv4\fP, \fB\-4\fP or \fB\-\-ipv6\fP, \fB\-6\fP"
+Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the
+rsync daemon will use to listen for connections.  One of these options may
+be required in older versions of Linux to work around an IPv6 bug in the
+kernel (if you see an "address already in use" error when nothing else is
+using the port, try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the
+daemon).
+.IP
+See also the client version of these options.
+.IP
+If rsync was compiled without support for IPv6, the \fB\-\-ipv6\fP option will
+have no effect.  The \fBrsync\ \-\-version\fP output will contain "\fBno\ IPv6\fP" if
+is the case.
+.IP "\fB\-\-help\fP, \fB\-h\fP"
+When specified after \fB\-\-daemon\fP, print a short help page describing the
+options available for starting an rsync daemon.
+.P
+.SH "FILTER RULES"
+.P
+The filter rules allow for custom control of several aspects of how files are
+handled:
+.P
+.IP o
+Control which files the sending side puts into the file list that describes
+the transfer hierarchy
+.IP o
+Control which files the receiving side protects from deletion when the file
+is not in the sender's file list
+.IP o
+Control which extended attribute names are skipped when copying xattrs
+.P
+The rules are either directly specified via option arguments or they can be
+read in from one or more files.  The filter-rule files can even be a part of
+the hierarchy of files being copied, affecting different parts of the tree in
+different ways.
+.P
+.SS "SIMPLE INCLUDE/EXCLUDE RULES"
+.P
+We will first cover the basics of how include & exclude rules affect what files
+are transferred, ignoring any deletion side-effects.  Filter rules mainly
+affect the contents of directories that rsync is "recursing" into, but they can
+also affect a top-level item in the transfer that was specified as a argument.
+.P
+The default for any unmatched file/dir is for it to be included in the
+transfer, which puts the file/dir into the sender's file list.  The use of an
+exclude rule causes one or more matching files/dirs to be left out of the
+sender's file list.  An include rule can be used to limit the effect of an
+exclude rule that is matching too many files.
+.P
+The order of the rules is important because the first rule that matches is the
+one that takes effect.  Thus, if an early rule excludes a file, no include rule
+that comes after it can have any effect. This means that you must place any
+include overrides somewhere prior to the exclude that it is intended to limit.
+.P
+When a directory is excluded, all its contents and sub-contents are also
+excluded.  The sender doesn't scan through any of it at all, which can save a
+lot of time when skipping large unneeded sub-trees.
+.P
+It is also important to understand that the include/exclude rules are applied
+to every file and directory that the sender is recursing into. Thus, if you
+want a particular deep file to be included, you have to make sure that none of
+the directories that must be traversed on the way down to that file are
+excluded or else the file will never be discovered to be included. As an
+example, if the directory "\fBa/path\fP" was given as a transfer argument and you
+want to ensure that the file "\fBa/path/down/deep/wanted.txt\fP" is a part of the
+transfer, then the sender must not exclude the directories "\fBa/path\fP",
+"\fBa/path/down\fP", or "\fBa/path/down/deep\fP" as it makes it way scanning through
+the file tree.
+.P
+When you are working on the rules, it can be helpful to ask rsync to tell you
+what is being excluded/included and why.  Specifying \fB\-\-debug=FILTER\fP or (when
+pulling files) \fB\-M\-\-debug=FILTER\fP turns on level 1 of the FILTER debug
+information that will output a message any time that a file or directory is
+included or excluded and which rule it matched.  Beginning in 3.2.4 it will
+also warn if a filter rule has trailing whitespace, since an exclude of "foo\ "
+(with a trailing space) will not exclude a file named "foo".
+.P
+Exclude and include rules can specify wildcard PATTERN MATCHING RULES
+(similar to shell wildcards) that allow you to match things like a file suffix
+or a portion of a filename.
+.P
+A rule can be limited to only affecting a directory by putting a trailing slash
+onto the filename.
+.P
+.SS "SIMPLE INCLUDE/EXCLUDE EXAMPLE"
+.P
+With the following file tree created on the sending side:
+.RS 4
+.P
+.nf
+mkdir x/
+touch x/file.txt
+mkdir x/y/
+touch x/y/file.txt
+touch x/y/zzz.txt
+mkdir x/z/
+touch x/z/file.txt
+.fi
+.RE
+.P
+Then the following rsync command will transfer the file "\fBx/y/file.txt\fP" and
+the directories needed to hold it, resulting in the path "\fB/tmp/x/y/file.txt\fP"
+existing on the remote host:
+.RS 4
+.P
+.nf
+rsync -ai -f'+ x/' -f'+ x/y/' -f'+ x/y/file.txt' -f'- *' x host:/tmp/
+.fi
+.RE
+.P
+Aside: this copy could also have been accomplished using the \fB\-R\fP
+option (though the 2 commands behave differently if deletions are enabled):
+.RS 4
+.P
+.nf
+rsync -aiR x/y/file.txt host:/tmp/
+.fi
+.RE
+.P
+The following command does not need an include of the "x" directory because it
+is not a part of the transfer (note the traililng slash).  Running this command
+would copy just "\fB/tmp/x/file.txt\fP" because the "y" and "z" dirs get excluded:
+.RS 4
+.P
+.nf
+rsync -ai -f'+ file.txt' -f'- *' x/ host:/tmp/x/
+.fi
+.RE
+.P
+This command would omit the zzz.txt file while copying "x" and everything else
+it contains:
+.RS 4
+.P
+.nf
+rsync -ai -f'- zzz.txt' x host:/tmp/
+.fi
+.RE
+.P
+.SS "FILTER RULES WHEN DELETING"
+.P
+By default the include & exclude filter rules affect both the sender
+(as it creates its file list)
+and the receiver (as it creates its file lists for calculating deletions).  If
+no delete option is in effect, the receiver skips creating the delete-related
+file lists.  This two-sided default can be manually overridden so that you are
+only specifying sender rules or receiver rules, as described in the FILTER
+RULES IN DEPTH section.
+.P
+When deleting, an exclude protects a file from being removed on the receiving
+side while an include overrides that protection (putting the file at risk of
+deletion). The default is for a file to be at risk\ \-\- its safety depends on it
+matching a corresponding file from the sender.
+.P
+An example of the two-sided exclude effect can be illustrated by the copying of
+a C development directory between 2 systems.  When doing a touch-up copy, you
+might want to skip copying the built executable and the \fB.o\fP files (sender
+hide) so that the receiving side can build their own and not lose any object
+files that are already correct (receiver protect).  For instance:
+.RS 4
+.P
+.nf
+rsync -ai --del -f'- *.o' -f'- cmd' src host:/dest/
+.fi
+.RE
+.P
+Note that using \fB\-f'\-p\ *.o'\fP is even better than \fB\-f'\-\ *.o'\fP if there is a
+chance that the directory structure may have changed.  The "p" modifier is
+discussed in FILTER RULE MODIFIERS.
+.P
+One final note, if your shell doesn't mind unexpanded wildcards, you could
+simplify the typing of the filter options by using an underscore in place of
+the space and leaving off the quotes.  For instance, \fB\-f\ \-_*.o\ \-f\ \-_cmd\fP (and
+similar) could be used instead of the filter options above.
+.P
+.SS "FILTER RULES IN DEPTH"
+.P
+Rsync supports old-style include/exclude rules and new-style filter rules.  The
+older rules are specified using \fB\-\-include\fP and \fB\-\-exclude\fP as
+well as the \fB\-\-include-from\fP and \fB\-\-exclude-from\fP. These are
+limited in behavior but they don't require a "\-" or "+" prefix.  An old-style
+exclude rule is turned into a "\fB\-\ name\fP" filter rule (with no modifiers) and an
+old-style include rule is turned into a "\fB+\ name\fP" filter rule (with no
+modifiers).
+.P
+Rsync builds an ordered list of filter rules as specified on the command-line
+and/or read-in from files.  New style filter rules have the following syntax:
+.RS 4
+.P
+.nf
+RULE [PATTERN_OR_FILENAME]
+RULE,MODIFIERS [PATTERN_OR_FILENAME]
+.fi
+.RE
+.P
+You have your choice of using either short or long RULE names, as described
+below.  If you use a short-named rule, the ',' separating the RULE from the
+MODIFIERS is optional.  The PATTERN or FILENAME that follows (when present)
+must come after either a single space or an underscore (_). Any additional
+spaces and/or underscores are considered to be a part of the pattern name.
+Here are the available rule prefixes:
+.P
+.IP "\fBexclude,\ '\-'\fP"
+specifies an exclude pattern that (by default) is both a
+\fBhide\fP and a \fBprotect\fP.
+.IP "\fBinclude,\ '+'\fP"
+specifies an include pattern that (by default) is both a
+\fBshow\fP and a \fBrisk\fP.
+.IP "\fBmerge,\ '.'\fP"
+specifies a merge-file on the client side to read for more
+rules.
+.IP "\fBdir-merge,\ ':'\fP"
+specifies a per-directory merge-file.  Using this kind of
+filter rule requires that you trust the sending side's filter checking, so
+it has the side-effect mentioned under the \fB\-\-trust-sender\fP option.
+.IP "\fBhide,\ 'H'\fP"
+specifies a pattern for hiding files from the transfer.
+Equivalent to a sender-only exclude, so \fB\-f'H\ foo'\fP could also be specified
+as \fB\-f'\-s\ foo'\fP.
+.IP "\fBshow,\ 'S'\fP"
+files that match the pattern are not hidden. Equivalent to a
+sender-only include, so \fB\-f'S\ foo'\fP could also be specified as \fB\-f'+s\ foo'\fP.
+.IP "\fBprotect,\ 'P'\fP"
+specifies a pattern for protecting files from deletion.
+Equivalent to a receiver-only exclude, so \fB\-f'P\ foo'\fP could also be
+specified as \fB\-f'\-r\ foo'\fP.
+.IP "\fBrisk,\ 'R'\fP"
+files that match the pattern are not protected. Equivalent to a
+receiver-only include, so \fB\-f'R\ foo'\fP could also be specified as \fB\-f'+r\ foo'\fP.
+.IP "\fBclear,\ '!'\fP"
+clears the current include/exclude list (takes no arg)
+.P
+When rules are being read from a file (using merge or dir-merge), empty lines
+are ignored, as are whole-line comments that start with a '\fB#\fP' (filename rules
+that contain a hash character are unaffected).
+.P
+Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and
+\fB\-\-exclude\fP options take one rule/pattern each.  To add multiple ones,
+you can repeat the options on the command-line, use the merge-file syntax of
+the \fB\-\-filter\fP option, or the \fB\-\-include-from\fP /
+\fB\-\-exclude-from\fP options.
+.P
+.SS "PATTERN MATCHING RULES"
+.P
+Most of the rules mentioned above take an argument that specifies what the rule
+should match.  If rsync is recursing through a directory hierarchy, keep in
+mind that each pattern is matched against the name of every directory in the
+descent path as rsync finds the filenames to send.
+.P
+The matching rules for the pattern argument take several forms:
+.P
+.IP o
+If a pattern contains a \fB/\fP (not counting a trailing slash) or a "\fB**\fP"
+(which can match a slash), then the pattern is matched against the full
+pathname, including any leading directories within the transfer.  If the
+pattern doesn't contain a (non-trailing) \fB/\fP or a "\fB**\fP", then it is matched
+only against the final component of the filename or pathname. For example,
+\fBfoo\fP means that the final path component must be "foo" while \fBfoo/bar\fP would
+match the last 2 elements of the path (as long as both elements are within
+the transfer).
+.IP o
+A pattern that ends with a \fB/\fP only matches a directory, not a regular file,
+symlink, or device.
+.IP o
+A pattern that starts with a \fB/\fP is anchored to the start of the transfer
+path instead of the end.  For example, \fB/foo/**\fP or \fB/foo/bar/**\fP match only
+leading elements in the path.  If the rule is read from a per-directory
+filter file, the transfer path being matched will begin at the level of the
+filter file instead of the top of the transfer.  See the section on
+ANCHORING INCLUDE/EXCLUDE PATTERNS for a full discussion of how to
+specify a pattern that matches at the root of the transfer.
+.P
+Rsync chooses between doing a simple string match and wildcard matching by
+checking if the pattern contains one of these three wildcard characters: '\fB*\fP',
+\&'\fB?\fP', and '\fB[\fP' :
+.P
+.IP o
+a '\fB?\fP' matches any single character except a slash (\fB/\fP).
+.IP o
+a '\fB*\fP' matches zero or more non-slash characters.
+.IP o
+a '\fB**\fP' matches zero or more characters, including slashes.
+.IP o
+a '\fB[\fP' introduces a character class, such as \fB[a-z]\fP or \fB[[:alpha:]]\fP, that
+must match one character.
+.IP o
+a trailing \fB***\fP in the pattern is a shorthand that allows you to match a
+directory and all its contents using a single rule.  For example, specifying
+"\fBdir_name/***\fP" will match both the "dir_name" directory (as if "\fBdir_name/\fP"
+had been specified) and everything in the directory (as if "\fBdir_name/**\fP"
+had been specified).
+.IP o
+a backslash can be used to escape a wildcard character, but it is only
+interpreted as an escape character if at least one wildcard character is
+present in the match pattern. For instance, the pattern "\fBfoo\\bar\fP" matches
+that single backslash literally, while the pattern "\fBfoo\\bar*\fP" would need to
+be changed to "\fBfoo\\\\bar*\fP" to avoid the "\fB\\b\fP" becoming just "b".
+.P
+Here are some examples of exclude/include matching:
+.P
+.IP o
+Option \fB\-f'\-\ *.o'\fP would exclude all filenames ending with \fB.o\fP
+.IP o
+Option \fB\-f'\-\ /foo'\fP would exclude a file (or directory) named foo in the
+transfer-root directory
+.IP o
+Option \fB\-f'\-\ foo/'\fP would exclude any directory named foo
+.IP o
+Option \fB\-f'\-\ foo/*/bar'\fP would exclude any file/dir named bar which is at two
+levels below a directory named foo (if foo is in the transfer)
+.IP o
+Option \fB\-f'\-\ /foo/**/bar'\fP would exclude any file/dir named bar that was two
+or more levels below a top-level directory named foo (note that /foo/bar is
+\fBnot\fP excluded by this)
+.IP o
+Options \fB\-f'+\ */'\ \-f'+\ *.c'\ \-f'\-\ *'\fP would include all directories and .c
+source files but nothing else
+.IP o
+Options \fB\-f'+\ foo/'\ \-f'+\ foo/bar.c'\ \-f'\-\ *'\fP would include only the foo
+directory and foo/bar.c (the foo directory must be explicitly included or it
+would be excluded by the "\fB\-\ *\fP")
+.P
+.SS "FILTER RULE MODIFIERS"
+.P
+The following modifiers are accepted after an include (+) or exclude (\-) rule:
+.P
+.IP o
+A \fB/\fP specifies that the include/exclude rule should be matched against the
+absolute pathname of the current item.  For example, \fB\-f'\-/\ /etc/passwd'\fP
+would exclude the passwd file any time the transfer was sending files from
+the "/etc" directory, and "\-/ subdir/foo" would always exclude "foo" when it
+is in a dir named "subdir", even if "foo" is at the root of the current
+transfer.
+.IP o
+A \fB!\fP specifies that the include/exclude should take effect if the pattern
+fails to match.  For instance, \fB\-f'\-!\ */'\fP would exclude all non-directories.
+.IP o
+A \fBC\fP is used to indicate that all the global CVS-exclude rules should be
+inserted as excludes in place of the "\-C".  No arg should follow.
+.IP o
+An \fBs\fP is used to indicate that the rule applies to the sending side.  When a
+rule affects the sending side, it affects what files are put into the
+sender's file list.  The default is for a rule to affect both sides unless
+\fB\-\-delete-excluded\fP was specified, in which case default rules become
+sender-side only.  See also the hide (H) and show (S) rules, which are an
+alternate way to specify sending-side includes/excludes.
+.IP o
+An \fBr\fP is used to indicate that the rule applies to the receiving side.  When
+a rule affects the receiving side, it prevents files from being deleted.  See
+the \fBs\fP modifier for more info.  See also the protect (P) and risk (R) rules,
+which are an alternate way to specify receiver-side includes/excludes.
+.IP o
+A \fBp\fP indicates that a rule is perishable, meaning that it is ignored in
+directories that are being deleted.  For instance, the
+\fB\-\-cvs-exclude\fP (\fB\-C\fP) option's default rules that exclude things
+like "CVS" and "\fB*.o\fP" are marked as perishable, and will not prevent a
+directory that was removed on the source from being deleted on the
+destination.
+.IP o
+An \fBx\fP indicates that a rule affects xattr names in xattr copy/delete
+operations (and is thus ignored when matching file/dir names).  If no
+xattr-matching rules are specified, a default xattr filtering rule is used
+(see the \fB\-\-xattrs\fP option).
+.P
+.SS "MERGE-FILE FILTER RULES"
+.P
+You can merge whole files into your filter rules by specifying either a merge
+(.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES
+section above).
+.P
+There are two kinds of merged files\ \-\- single-instance ('.') and per-directory
+(':').  A single-instance merge file is read one time, and its rules are
+incorporated into the filter list in the place of the "." rule.  For
+per-directory merge files, rsync will scan every directory that it traverses
+for the named file, merging its contents when the file exists into the current
+list of inherited rules.  These per-directory rule files must be created on the
+sending side because it is the sending side that is being scanned for the
+available files to transfer.  These rule files may also need to be transferred
+to the receiving side if you want them to affect what files don't get deleted
+(see PER-DIRECTORY RULES AND DELETE below).
+.P
+Some examples:
+.RS 4
+.P
+.nf
+merge /etc/rsync/default.rules
+\&. /etc/rsync/default.rules
+dir-merge .per-dir-filter
+dir-merge,n- .non-inherited-per-dir-excludes
+:n- .non-inherited-per-dir-excludes
+.fi
+.RE
+.P
+The following modifiers are accepted after a merge or dir-merge rule:
+.P
+.IP o
+A \fB\-\fP specifies that the file should consist of only exclude patterns, with
+no other rule-parsing except for in-file comments.
+.IP o
+A \fB+\fP specifies that the file should consist of only include patterns, with
+no other rule-parsing except for in-file comments.
+.IP o
+A \fBC\fP is a way to specify that the file should be read in a CVS-compatible
+manner.  This turns on 'n', 'w', and '\-', but also allows the list-clearing
+token (!) to be specified.  If no filename is provided, ".cvsignore" is
+assumed.
+.IP o
+A \fBe\fP will exclude the merge-file name from the transfer; e.g.  "dir-merge,e
+\&.rules" is like "dir-merge .rules" and "\- .rules".
+.IP o
+An \fBn\fP specifies that the rules are not inherited by subdirectories.
+.IP o
+A \fBw\fP specifies that the rules are word-split on whitespace instead of the
+normal line-splitting.  This also turns off comments.  Note: the space that
+separates the prefix from the rule is treated specially, so "\- foo + bar" is
+parsed as two rules (assuming that prefix-parsing wasn't also disabled).
+.IP o
+You may also specify any of the modifiers for the "+" or "\-" rules (above) in
+order to have the rules that are read in from the file default to having that
+modifier set (except for the \fB!\fP modifier, which would not be useful).  For
+instance, "merge,\-/ .excl" would treat the contents of .excl as absolute-path
+excludes, while "dir-merge,s .filt" and ":sC" would each make all their
+per-directory rules apply only on the sending side.  If the merge rule
+specifies sides to affect (via the \fBs\fP or \fBr\fP modifier or both), then the
+rules in the file must not specify sides (via a modifier or a rule prefix
+such as \fBhide\fP).
+.P
+Per-directory rules are inherited in all subdirectories of the directory where
+the merge-file was found unless the 'n' modifier was used.  Each subdirectory's
+rules are prefixed to the inherited per-directory rules from its parents, which
+gives the newest rules a higher priority than the inherited rules.  The entire
+set of dir-merge rules are grouped together in the spot where the merge-file
+was specified, so it is possible to override dir-merge rules via a rule that
+got specified earlier in the list of global rules.  When the list-clearing rule
+("!") is read from a per-directory file, it only clears the inherited rules for
+the current merge file.
+.P
+Another way to prevent a single rule from a dir-merge file from being inherited
+is to anchor it with a leading slash.  Anchored rules in a per-directory
+merge-file are relative to the merge-file's directory, so a pattern "/foo"
+would only match the file "foo" in the directory where the dir-merge filter
+file was found.
+.P
+Here's an example filter file which you'd specify via \fB\-\-filter=".\ file":\fP
+.RS 4
+.P
+.nf
+merge /home/user/.global-filter
+- *.gz
+dir-merge .rules
++ *.[ch]
+- *.o
+- foo*
+.fi
+.RE
+.P
+This will merge the contents of the /home/user/.global-filter file at the start
+of the list and also turns the ".rules" filename into a per-directory filter
+file.  All rules read in prior to the start of the directory scan follow the
+global anchoring rules (i.e. a leading slash matches at the root of the
+transfer).
+.P
+If a per-directory merge-file is specified with a path that is a parent
+directory of the first transfer directory, rsync will scan all the parent dirs
+from that starting point to the transfer directory for the indicated
+per-directory file.  For instance, here is a common filter (see \fB\-F\fP):
+.RS 4
+.P
+.nf
+--filter=': /.rsync-filter'
+.fi
+.RE
+.P
+That rule tells rsync to scan for the file .rsync-filter in all directories
+from the root down through the parent directory of the transfer prior to the
+start of the normal directory scan of the file in the directories that are sent
+as a part of the transfer. (Note: for an rsync daemon, the root is always the
+same as the module's "path".)
+.P
+Some examples of this pre-scanning for per-directory files:
+.RS 4
+.P
+.nf
+rsync -avF /src/path/ /dest/dir
+rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
+rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir
+.fi
+.RE
+.P
+The first two commands above will look for ".rsync-filter" in "/" and "/src"
+before the normal scan begins looking for the file in "/src/path" and its
+subdirectories.  The last command avoids the parent-dir scan and only looks for
+the ".rsync-filter" files in each directory that is a part of the transfer.
+.P
+If you want to include the contents of a ".cvsignore" in your patterns, you
+should use the rule ":C", which creates a dir-merge of the .cvsignore file, but
+parsed in a CVS-compatible manner.  You can use this to affect where the
+\fB\-\-cvs-exclude\fP (\fB\-C\fP) option's inclusion of the per-directory
+\&.cvsignore file gets placed into your rules by putting the ":C" wherever you
+like in your filter rules.  Without this, rsync would add the dir-merge rule
+for the .cvsignore file at the end of all your other rules (giving it a lower
+priority than your command-line rules).  For example:
+.RS 4
+.P
+.nf
+cat <<EOT | rsync -avC --filter='. -' a/ b
++ foo.o
+:C
+- *.old
+EOT
+rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
+.fi
+.RE
+.P
+Both of the above rsync commands are identical.  Each one will merge all the
+per-directory .cvsignore rules in the middle of the list rather than at the
+end.  This allows their dir-specific rules to supersede the rules that follow
+the :C instead of being subservient to all your rules.  To affect the other CVS
+exclude rules (i.e. the default list of exclusions, the contents of
+$HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the \fB\-C\fP
+command-line option and instead insert a "\-C" rule into your filter rules; e.g.
+"\fB\-\-filter=\-C\fP".
+.P
+.SS "LIST-CLEARING FILTER RULE"
+.P
+You can clear the current include/exclude list by using the "!" filter rule (as
+introduced in the FILTER RULES section above).  The "current" list is either
+the global list of rules (if the rule is encountered while parsing the filter
+options) or a set of per-directory rules (which are inherited in their own
+sub-list, so a subdirectory can use this to clear out the parent's rules).
+.P
+.SS "ANCHORING INCLUDE/EXCLUDE PATTERNS"
+.P
+As mentioned earlier, global include/exclude patterns are anchored at the "root
+of the transfer" (as opposed to per-directory patterns, which are anchored at
+the merge-file's directory).  If you think of the transfer as a subtree of
+names that are being sent from sender to receiver, the transfer-root is where
+the tree starts to be duplicated in the destination directory.  This root
+governs where patterns that start with a / match.
+.P
+Because the matching is relative to the transfer-root, changing the trailing
+slash on a source path or changing your use of the \fB\-\-relative\fP option
+affects the path you need to use in your matching (in addition to changing how
+much of the file tree is duplicated on the destination host).  The following
+examples demonstrate this.
+.P
+Let's say that we want to match two source files, one with an absolute
+path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
+Here is how the various command choices differ for a 2-source transfer:
+.RS 4
+.P
+.nf
+Example cmd: rsync -a /home/me /home/you /dest
++/- pattern: /me/foo/bar
++/- pattern: /you/bar/baz
+Target file: /dest/me/foo/bar
+Target file: /dest/you/bar/baz
+.fi
+.RE
+.RS 4
+.P
+.nf
+Example cmd: rsync -a /home/me/ /home/you/ /dest
++/- pattern: /foo/bar               (note missing "me")
++/- pattern: /bar/baz               (note missing "you")
+Target file: /dest/foo/bar
+Target file: /dest/bar/baz
+.fi
+.RE
+.RS 4
+.P
+.nf
+Example cmd: rsync -a --relative /home/me/ /home/you /dest
++/- pattern: /home/me/foo/bar       (note full path)
++/- pattern: /home/you/bar/baz      (ditto)
+Target file: /dest/home/me/foo/bar
+Target file: /dest/home/you/bar/baz
+.fi
+.RE
+.RS 4
+.P
+.nf
+Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
++/- pattern: /me/foo/bar      (starts at specified path)
++/- pattern: /you/bar/baz     (ditto)
+Target file: /dest/me/foo/bar
+Target file: /dest/you/bar/baz
+.fi
+.RE
+.P
+The easiest way to see what name you should filter is to just look at the
+output when using \fB\-\-verbose\fP and put a / in front of the name (use the
+\fB\-\-dry-run\fP option if you're not yet ready to copy any files).
+.P
+.SS "PER-DIRECTORY RULES AND DELETE"
+.P
+Without a delete option, per-directory rules are only relevant on the sending
+side, so you can feel free to exclude the merge files themselves without
+affecting the transfer.  To make this easy, the 'e' modifier adds this exclude
+for you, as seen in these two equivalent commands:
+.RS 4
+.P
+.nf
+rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
+rsync -av --filter=':e .excl' host:src/dir /dest
+.fi
+.RE
+.P
+However, if you want to do a delete on the receiving side AND you want some
+files to be excluded from being deleted, you'll need to be sure that the
+receiving side knows what files to exclude.  The easiest way is to include the
+per-directory merge files in the transfer and use \fB\-\-delete-after\fP,
+because this ensures that the receiving side gets all the same exclude rules as
+the sending side before it tries to delete anything:
+.RS 4
+.P
+.nf
+rsync -avF --delete-after host:src/dir /dest
+.fi
+.RE
+.P
+However, if the merge files are not a part of the transfer, you'll need to
+either specify some global exclude rules (i.e. specified on the command line),
+or you'll need to maintain your own per-directory merge files on the receiving
+side.  An example of the first is this (assume that the remote .rules files
+exclude themselves):
+.RS 4
+.P
+.nf
+rsync -av --filter=': .rules' --filter='. /my/extra.rules'
+   --delete host:src/dir /dest
+.fi
+.RE
+.P
+In the above example the extra.rules file can affect both sides of the
+transfer, but (on the sending side) the rules are subservient to the rules
+merged from the .rules files because they were specified after the
+per-directory merge rule.
+.P
+In one final example, the remote side is excluding the .rsync-filter files from
+the transfer, but we want to use our own .rsync-filter files to control what
+gets deleted on the receiving side.  To do this we must specifically exclude
+the per-directory merge files (so that they don't get deleted) and then put
+rules into the local files to control what else should not get deleted.  Like
+one of these commands:
+.RS 4
+.P
+.nf
+rsync -av --filter=':e /.rsync-filter' --delete \\
+    host:src/dir /dest
+rsync -avFF --delete host:src/dir /dest
+.fi
+.RE
+.P
+.SH "TRANSFER RULES"
+.P
+In addition to the FILTER RULES that affect the recursive file scans that
+generate the file list on the sending and (when deleting) receiving sides,
+there are transfer rules. These rules affect which files the generator decides
+need to be transferred without the side effects of an exclude filter rule.
+Transfer rules affect only files and never directories.
+.P
+Because a transfer rule does not affect what goes into the sender's (and
+receiver's) file list, it cannot have any effect on which files get deleted on
+the receiving side.  For example, if the file "foo" is present in the sender's
+list but its size is such that it is omitted due to a transfer rule, the
+receiving side does not request the file.  However, its presence in the file
+list means that a delete pass will not remove a matching file named "foo" on
+the receiving side.  On the other hand, a server-side exclude (hide) of the
+file "foo" leaves the file out of the server's file list, and absent a
+receiver-side exclude (protect) the receiver will remove a matching file named
+"foo" if deletions are requested.
+.P
+Given that the files are still in the sender's file list, the
+\fB\-\-prune-empty-dirs\fP option will not judge a directory as being empty
+even if it contains only files that the transfer rules omitted.
+.P
+Similarly, a transfer rule does not have any extra effect on which files are
+deleted on the receiving side, so setting a maximum file size for the transfer
+does not prevent big files from being deleted.
+.P
+Examples of transfer rules include the default "quick check" algorithm (which
+compares size & modify time), the \fB\-\-update\fP option, the
+\fB\-\-max-size\fP option, the \fB\-\-ignore-non-existing\fP option, and a
+few others.
+.P
+.SH "BATCH MODE"
+.P
+Batch mode can be used to apply the same set of updates to many identical
+systems.  Suppose one has a tree which is replicated on a number of hosts.  Now
+suppose some changes have been made to this source tree and those changes need
+to be propagated to the other hosts.  In order to do this using batch mode,
+rsync is run with the write-batch option to apply the changes made to the
+source tree to one of the destination trees.  The write-batch option causes the
+rsync client to store in a "batch file" all the information needed to repeat
+this operation against other, identical destination trees.
+.P
+Generating the batch file once saves having to perform the file status,
+checksum, and data block generation more than once when updating multiple
+destination trees.  Multicast transport protocols can be used to transfer the
+batch update files in parallel to many hosts at once, instead of sending the
+same data to every host individually.
+.P
+To apply the recorded changes to another destination tree, run rsync with the
+read-batch option, specifying the name of the same batch file, and the
+destination tree.  Rsync updates the destination tree using the information
+stored in the batch file.
+.P
+For your convenience, a script file is also created when the write-batch option
+is used: it will be named the same as the batch file with ".sh" appended.  This
+script file contains a command-line suitable for updating a destination tree
+using the associated batch file.  It can be executed using a Bourne (or
+Bourne-like) shell, optionally passing in an alternate destination tree
+pathname which is then used instead of the original destination path.  This is
+useful when the destination tree path on the current host differs from the one
+used to create the batch file.
+.P
+Examples:
+.RS 4
+.P
+.nf
+$ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
+$ scp foo* remote:
+$ ssh remote ./foo.sh /bdest/dir/
+.fi
+.RE
+.RS 4
+.P
+.nf
+$ rsync --write-batch=foo -a /source/dir/ /adest/dir/
+$ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
+.fi
+.RE
+.P
+In these examples, rsync is used to update /adest/dir/ from /source/dir/ and
+the information to repeat this operation is stored in "foo" and "foo.sh".  The
+host "remote" is then updated with the batched data going into the directory
+/bdest/dir.  The differences between the two examples reveals some of the
+flexibility you have in how you deal with batches:
+.P
+.IP o
+The first example shows that the initial copy doesn't have to be local\ \-\- you
+can push or pull data to/from a remote host using either the remote-shell
+syntax or rsync daemon syntax, as desired.
+.IP o
+The first example uses the created "foo.sh" file to get the right rsync
+options when running the read-batch command on the remote host.
+.IP o
+The second example reads the batch data via standard input so that the batch
+file doesn't need to be copied to the remote machine first.  This example
+avoids the foo.sh script because it needed to use a modified
+\fB\-\-read-batch\fP option, but you could edit the script file if you
+wished to make use of it (just be sure that no other option is trying to use
+standard input, such as the \fB\-\-exclude-from=\-\fP option).
+.P
+Caveats:
+.P
+The read-batch option expects the destination tree that it is updating to be
+identical to the destination tree that was used to create the batch update
+fileset.  When a difference between the destination trees is encountered the
+update might be discarded with a warning (if the file appears to be up-to-date
+already) or the file-update may be attempted and then, if the file fails to
+verify, the update discarded with an error.  This means that it should be safe
+to re-run a read-batch operation if the command got interrupted.  If you wish
+to force the batched-update to always be attempted regardless of the file's
+size and date, use the \fB\-I\fP option (when reading the batch).  If an
+error occurs, the destination tree will probably be in a partially updated
+state.  In that case, rsync can be used in its regular (non-batch) mode of
+operation to fix up the destination tree.
+.P
+The rsync version used on all destinations must be at least as new as the one
+used to generate the batch file.  Rsync will die with an error if the protocol
+version in the batch file is too new for the batch-reading rsync to handle.
+See also the \fB\-\-protocol\fP option for a way to have the creating rsync
+generate a batch file that an older rsync can understand.  (Note that batch
+files changed format in version 2.6.3, so mixing versions older than that with
+newer versions will not work.)
+.P
+When reading a batch file, rsync will force the value of certain options to
+match the data in the batch file if you didn't set them to the same as the
+batch-writing command.  Other options can (and should) be changed.  For
+instance \fB\-\-write-batch\fP changes to \fB\-\-read-batch\fP,
+\fB\-\-files-from\fP is dropped, and the \fB\-\-filter\fP /
+\fB\-\-include\fP / \fB\-\-exclude\fP options are not needed unless one of
+the \fB\-\-delete\fP options is specified.
+.P
+The code that creates the BATCH.sh file transforms any filter/include/exclude
+options into a single list that is appended as a "here" document to the shell
+script file.  An advanced user can use this to modify the exclude list if a
+change in what gets deleted by \fB\-\-delete\fP is desired.  A normal user
+can ignore this detail and just use the shell script as an easy way to run the
+appropriate \fB\-\-read-batch\fP command for the batched data.
+.P
+The original batch mode in rsync was based on "rsync+", but the latest
+version uses a new implementation.
+.P
+.SH "SYMBOLIC LINKS"
+.P
+Three basic behaviors are possible when rsync encounters a symbolic
+link in the source directory.
+.P
+By default, symbolic links are not transferred at all.  A message "skipping
+non-regular" file is emitted for any symlinks that exist.
+.P
+If \fB\-\-links\fP is specified, then symlinks are added to the transfer
+(instead of being noisily ignored), and the default handling is to recreate
+them with the same target on the destination.  Note that \fB\-\-archive\fP
+implies \fB\-\-links\fP.
+.P
+If \fB\-\-copy-links\fP is specified, then symlinks are "collapsed" by
+copying their referent, rather than the symlink.
+.P
+Rsync can also distinguish "safe" and "unsafe" symbolic links.  An example
+where this might be used is a web site mirror that wishes to ensure that the
+rsync module that is copied does not include symbolic links to \fB/etc/passwd\fP in
+the public section of the site.  Using \fB\-\-copy-unsafe-links\fP will cause
+any links to be copied as the file they point to on the destination.  Using
+\fB\-\-safe-links\fP will cause unsafe links to be omitted by the receiver.
+(Note that you must specify or imply \fB\-\-links\fP for
+\fB\-\-safe-links\fP to have any effect.)
+.P
+Symbolic links are considered unsafe if they are absolute symlinks (start with
+\fB/\fP), empty, or if they contain enough ".." components to ascend from the top
+of the transfer.
+.P
+Here's a summary of how the symlink options are interpreted.  The list is in
+order of precedence, so if your combination of options isn't mentioned, use the
+first line that is a complete subset of your options:
+.P
+.IP "\fB\-\-copy-links\fP"
+Turn all symlinks into normal files and directories
+(leaving no symlinks in the transfer for any other options to affect).
+.IP "\fB\-\-copy-dirlinks\fP"
+Turn just symlinks to directories into real
+directories, leaving all other symlinks to be handled as described below.
+.IP "\fB\-\-links\ \-\-copy-unsafe-links\fP"
+Turn all unsafe symlinks
+into files and create all safe symlinks.
+.IP "\fB\-\-copy-unsafe-links\fP"
+Turn all unsafe symlinks into files, noisily
+skip all safe symlinks.
+.IP "\fB\-\-links\ \-\-safe-links\fP"
+The receiver skips creating
+unsafe symlinks found in the transfer and creates the safe ones.
+.IP "\fB\-\-links\fP"
+Create all symlinks.
+.P
+For the effect of \fB\-\-munge-links\fP, see the discussion in that option's
+section.
+.P
+Note that the \fB\-\-keep-dirlinks\fP option does not effect symlinks in the
+transfer but instead affects how rsync treats a symlink to a directory that
+already exists on the receiving side.  See that option's section for a warning.
+.P
+.SH "DIAGNOSTICS"
+.P
+Rsync occasionally produces error messages that may seem a little cryptic.  The
+one that seems to cause the most confusion is "protocol version mismatch\ \-\- is
+your shell clean?".
+.P
+This message is usually caused by your startup scripts or remote shell facility
+producing unwanted garbage on the stream that rsync is using for its transport.
+The way to diagnose this problem is to run your remote shell like this:
+.RS 4
+.P
+.nf
+ssh remotehost /bin/true > out.dat
+.fi
+.RE
+.P
+then look at out.dat.  If everything is working correctly then out.dat should
+be a zero length file.  If you are getting the above error from rsync then you
+will probably find that out.dat contains some text or data.  Look at the
+contents and try to work out what is producing it.  The most common cause is
+incorrectly configured shell startup scripts (such as .cshrc or .profile) that
+contain output statements for non-interactive logins.
+.P
+If you are having trouble debugging filter patterns, then try specifying the
+\fB\-vv\fP option.  At this level of verbosity rsync will show why each individual
+file is included or excluded.
+.P
+.SH "EXIT VALUES"
+.P
+.IP o
+\fB0\fP \- Success
+.IP o
+\fB1\fP \- Syntax or usage error
+.IP o
+\fB2\fP \- Protocol incompatibility
+.IP o
+\fB3\fP \- Errors selecting input/output files, dirs
+.IP o
+.P
+.RS
+.IP o
+\fB4\fP \- Requested action not supported. Either:
+
+an attempt was made to manipulate 64-bit files on a platform that cannot support them
+.IP o
+an option was specified that is supported by the client and not by the server
+.RE
+.IP o
+\fB5\fP \- Error starting client-server protocol
+.IP o
+\fB6\fP \- Daemon unable to append to log-file
+.IP o
+\fB10\fP \- Error in socket I/O
+.IP o
+\fB11\fP \- Error in file I/O
+.IP o
+\fB12\fP \- Error in rsync protocol data stream
+.IP o
+\fB13\fP \- Errors with program diagnostics
+.IP o
+\fB14\fP \- Error in IPC code
+.IP o
+\fB20\fP \- Received SIGUSR1 or SIGINT
+.IP o
+\fB21\fP \- Some error returned by \fBwaitpid()\fP
+.IP o
+\fB22\fP \- Error allocating core memory buffers
+.IP o
+\fB23\fP \- Partial transfer due to error
+.IP o
+\fB24\fP \- Partial transfer due to vanished source files
+.IP o
+\fB25\fP \- The \-\-max-delete limit stopped deletions
+.IP o
+\fB30\fP \- Timeout in data send/receive
+.IP o
+\fB35\fP \- Timeout waiting for daemon connection
+.P
+.SH "ENVIRONMENT VARIABLES"
+.P
+.IP "\fBCVSIGNORE\fP"
+The CVSIGNORE environment variable supplements any ignore patterns in
+\&.cvsignore files.  See the \fB\-\-cvs-exclude\fP option for more details.
+.IP "\fBRSYNC_ICONV\fP"
+Specify a default \fB\-\-iconv\fP setting using this environment
+variable. First supported in 3.0.0.
+.IP "\fBRSYNC_OLD_ARGS\fP"
+Specify a "1" if you want the \fB\-\-old-args\fP option to be enabled by
+default, a "2" (or more) if you want it to be enabled in the
+repeated-option state, or a "0" to make sure that it is disabled by
+default. When this environment variable is set to a non-zero value, it
+supersedes the \fBRSYNC_PROTECT_ARGS\fP variable.
+.IP
+This variable is ignored if \fB\-\-old-args\fP, \fB\-\-no-old-args\fP, or
+\fB\-\-secluded-args\fP is specified on the command line.
+.IP
+First supported in 3.2.4.
+.IP "\fBRSYNC_PROTECT_ARGS\fP"
+Specify a non-zero numeric value if you want the \fB\-\-secluded-args\fP
+option to be enabled by default, or a zero value to make sure that it is
+disabled by default.
+.IP
+This variable is ignored if \fB\-\-secluded-args\fP, \fB\-\-no-secluded-args\fP,
+or \fB\-\-old-args\fP is specified on the command line.
+.IP
+First supported in 3.1.0.  Starting in 3.2.4, this variable is ignored if
+\fBRSYNC_OLD_ARGS\fP is set to a non-zero value.
+.IP "\fBRSYNC_RSH\fP"
+This environment variable allows you to override the default shell used as
+the transport for rsync.  Command line options are permitted after the
+command name, just as in the \fB\-\-rsh\fP (\fB\-e\fP) option.
+.IP "\fBRSYNC_PROXY\fP"
+This environment variable allows you to redirect your rsync
+client to use a web proxy when connecting to an rsync daemon.  You should
+set \fBRSYNC_PROXY\fP to a hostname:port pair.
+.IP "\fBRSYNC_PASSWORD\fP"
+This environment variable allows you to set the password for an rsync
+\fBdaemon\fP connection, which avoids the password prompt.  Note that this
+does \fBnot\fP supply a password to a remote shell transport such as ssh
+(consult its documentation for how to do that).
+.IP "\fBUSER\fP or \fBLOGNAME\fP"
+The USER or LOGNAME environment variables are used to determine the default
+username sent to an rsync daemon.  If neither is set, the username defaults
+to "nobody".  If both are set, \fBUSER\fP takes precedence.
+.IP "\fBRSYNC_PARTIAL_DIR\fP"
+This environment variable specifies the directory to use for a
+\fB\-\-partial\fP transfer without implying that partial transfers be
+enabled.  See the \fB\-\-partial-dir\fP option for full details.
+.IP "\fBRSYNC_COMPRESS_LIST\fP"
+This environment variable allows you to customize the negotiation of the
+compression algorithm by specifying an alternate order or a reduced list of
+names.  Use the command \fBrsync\ \-\-version\fP to see the available compression
+names.  See the \fB\-\-compress\fP option for full details.
+.IP "\fBRSYNC_CHECKSUM_LIST\fP"
+This environment variable allows you to customize the negotiation of the
+checksum algorithm by specifying an alternate order or a reduced list of
+names.  Use the command \fBrsync\ \-\-version\fP to see the available checksum
+names.  See the \fB\-\-checksum-choice\fP option for full details.
+.IP "\fBRSYNC_MAX_ALLOC\fP"
+This environment variable sets an allocation maximum as if you had used the
+\fB\-\-max-alloc\fP option.
+.IP "\fBRSYNC_PORT\fP"
+This environment variable is not read by rsync, but is instead set in
+its sub-environment when rsync is running the remote shell in combination
+with a daemon connection.  This allows a script such as
+\fBrsync-ssl\fP to be able to know the port number that the user
+specified on the command line.
+.IP "\fBHOME\fP"
+This environment variable is used to find the user's default .cvsignore
+file.
+.IP "\fBRSYNC_CONNECT_PROG\fP"
+This environment variable is mainly used in debug setups to set the program
+to use when making a daemon connection.  See CONNECTING TO AN RSYNC
+DAEMON for full details.
+.IP "\fBRSYNC_SHELL\fP"
+This environment variable is mainly used in debug setups to set the program
+to use to run the program specified by \fBRSYNC_CONNECT_PROG\fP.  See
+CONNECTING TO AN RSYNC DAEMON for full details.
+.P
+.SH "FILES"
+.P
+/etc/rsyncd.conf or rsyncd.conf
+.P
+.SH "SEE ALSO"
+.P
+\fBrsync-ssl\fP(1), \fBrsyncd.conf\fP(5), \fBrrsync\fP(1)
+.P
+.SH "BUGS"
+.P
+.IP o
+Times are transferred as *nix time_t values.
+.IP o
+When transferring to FAT filesystems rsync may re-sync unmodified files.  See
+the comments on the \fB\-\-modify-window\fP option.
+.IP o
+File permissions, devices, etc. are transferred as native numerical values.
+.IP o
+See also the comments on the \fB\-\-delete\fP option.
+.P
+Please report bugs! See the web site at https://rsync.samba.org/.
+.P
+.SH "VERSION"
+.P
+This manpage is current for version 3.2.7 of rsync.
+.P
+.SH "INTERNAL OPTIONS"
+.P
+The options \fB\-\-server\fP and \fB\-\-sender\fP are used internally by rsync, and should
+never be typed by a user under normal circumstances.  Some awareness of these
+options may be needed in certain scenarios, such as when setting up a login
+that can only run an rsync command.  For instance, the support directory of the
+rsync distribution has an example script named rrsync (for restricted rsync)
+that can be used with a restricted ssh login.
+.P
+.SH "CREDITS"
+.P
+Rsync is distributed under the GNU General Public License.  See the file
+COPYING for details.
+.P
+An rsync web site is available at https://rsync.samba.org/.  The site
+includes an FAQ-O-Matic which may cover questions unanswered by this manual
+page.
+.P
+The rsync github project is https://github.com/WayneD/rsync.
+.P
+We would be delighted to hear from you if you like this program.  Please
+contact the mailing-list at rsync@lists.samba.org.
+.P
+This program uses the excellent zlib compression library written by Jean-loup
+Gailly and Mark Adler.
+.P
+.SH "THANKS"
+.P
+Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
+David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
+gone-but-not-forgotten compadre, J.W. Schultz.
+.P
+Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and
+David Bell.  I've probably missed some people, my apologies if I have.
+.P
+.SH "AUTHOR"
+.P
+Rsync was originally written by Andrew Tridgell and Paul Mackerras.  Many
+people have later contributed to it. It is currently maintained by Wayne
+Davison.
+.P
+Mailing lists for support and development are available at
+https://lists.samba.org/.
diff --git a/upstream/mageia-cauldron/man1/rtf2rtf.1 b/upstream/mageia-cauldron/man1/rtf2rtf.1
new file mode 100644
index 00000000..06098256
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/rtf2rtf.1
@@ -0,0 +1,70 @@
+.\" Process this file with
+.\" groff -man -Tascii rtf2rtf.1
+.\"
+.TH RTF2RTF 1
+.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
+.\" other parms are allowed: see man(7), man(1)
+.SH NAME
+rtf2rtf \- programs to postprocess the raw RTF generated by the mapping files
+.SH SYNOPSIS
+.B rtf2rtf
+.I "[options] .."
+.br
+.SH "DESCRIPTION"
+This manual page documents briefly the
+.BR rtf2rtf
+commands.
+This manual page was written for the Debian GNU/Linux distribution
+because the original program does not have a manual page for rtf2rtf.
+.PP
+.B rtf2rtf
+is a program to postprocess the raw RTF generated by the mapping files.
+.PP
+It is used by other programs in sgml-tools (v1), and usually
+normal user does not need to use this program directly.
+.PP
+Following is quoted from the README in the source tree.
+.TP
+(Begin Quotes)
+.PP
+I'm not proud of this code. It's a hack foisted upon a hack, nested
+within another hack or two.  It sort of works well enough for my
+purposes (generating WinHelp .RTF files for my documents), but it
+could definitely use a redesign/rewrite. It started as a simple
+perturbation of the html2html filter, but got ugly very quickly...
+.PP
+I shamelessly blame the RTF format for most of the hackery here -- RTF
+is not a _language_ like LaTeX or ROFF -- it's just a file format. So,
+we can't rely on RTF to do even simple things like "insert a paragraph
+break here only if the previous token was not also a paragraph
+break. Since the SGML front end has no conditional processing
+capabilities, multiple blank likes in the SGML get translated to
+multiple para breaks in the RTF. That's why we use a "lex" filter
+(rtf2rtf) to postprocess the raw RTF generated by the mapping files.
+.PP
+Again: I offer this to the Linuxdoc community with the hopes that it
+will be useful to others and that someone else can help flesh out the
+missing pieces. What? Missing pieces?  Yes, recall that I say it works
+"well enough for my purposes".  The replacement files (general,
+mapping) started out like as the latex replacement files.  Much of
+them still _are_ the latex replacement files.  I only converted those
+parts that are actually used by my documents. Your documents may
+require more of the files to be translated to RTF.
+.PP
+Since I'm using these mappings for actual documentation, I plan on
+maintaining this backend, so please send me any improvements -- I'll
+coordinate with Greg to make sure they get into the the next official
+release.
+.TP
+(End Quotes)
+
+.SH OPTIONS
+The programs does not support normal command line option.
+
+.SH "SEE ALSO"
+For a complete description, see the README file in the source archive.
+.SH AUTHOR
+.B rtf2rtf
+was written by Steve Tynor (tynor@atlanta.twr.com) December 1995.
+This manual page was written by Taketoshi Sano <sano@debian.org>,
+for the Debian GNU/Linux system (but may be used by others).
diff --git a/upstream/mageia-cauldron/man1/runcon.1 b/upstream/mageia-cauldron/man1/runcon.1
new file mode 100644
index 00000000..f05aeac8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/runcon.1
@@ -0,0 +1,67 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH RUNCON "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+runcon \- run command with specified security context
+.SH SYNOPSIS
+.B runcon
+\fI\,CONTEXT COMMAND \/\fR[\fI\,args\/\fR]
+.br
+.B runcon
+[ \fI\,-c \/\fR] [\fI\,-u USER\/\fR] [\fI\,-r ROLE\/\fR] [\fI\,-t TYPE\/\fR] [\fI\,-l RANGE\/\fR] \fI\,COMMAND \/\fR[\fI\,args\/\fR]
+.SH DESCRIPTION
+Run COMMAND with completely-specified CONTEXT, or with current or
+transitioned security context modified by one or more of LEVEL,
+ROLE, TYPE, and USER.
+.PP
+If none of \fI-c\fR, \fI-t\fR, \fI-u\fR, \fI-r\fR, or \fI-l\fR, is specified,
+the first argument is used as the complete context.  Any additional
+arguments after \fICOMMAND\fR are interpreted as arguments to the
+command.
+.PP
+Note that only carefully-chosen contexts are likely to successfully
+run.
+.PP
+Run a program in a different SELinux security context.
+With neither CONTEXT nor COMMAND, print the current security context.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+CONTEXT
+Complete security context
+.TP
+\fB\-c\fR, \fB\-\-compute\fR
+compute process transition context before modifying
+.TP
+\fB\-t\fR, \fB\-\-type\fR=\fI\,TYPE\/\fR
+type (for same role as parent)
+.TP
+\fB\-u\fR, \fB\-\-user\fR=\fI\,USER\/\fR
+user identity
+.TP
+\fB\-r\fR, \fB\-\-role\fR=\fI\,ROLE\/\fR
+role
+.TP
+\fB\-l\fR, \fB\-\-range\fR=\fI\,RANGE\/\fR
+levelrange
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Russell Coker.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/runcon>
+.br
+or available locally via: info \(aq(coreutils) runcon invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sadf.1 b/upstream/mageia-cauldron/man1/sadf.1
new file mode 100644
index 00000000..a5495a1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sadf.1
@@ -0,0 +1,393 @@
+.\" sadf manual page - (C) 1999-2023 Sebastien Godard (sysstat <at> orange.fr)
+.TH SADF 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+sadf \- Display data collected by sar in multiple formats.
+
+.SH SYNOPSIS
+.B sadf [ -C ] [ -c | -d | -g | -j | -l | -p | -r | -x ] [ -H ] [ -h ] [ -T | -t | -U ] [ -V ] [ -O
+.IB "opts " "[,...] ] [ -P { " "cpu_list " "| ALL } ] [ -s [ "
+.IB "start_time " "] ] ] [ -e [ " "end_time " "] ] ]"
+.BI "[ --dev=" "dev_list " "] [ --fs=" "fs_list " "] [ --iface=" "iface_list" "] [ --int=" "int_list " "] [ --"
+.IB "sar_options " "] [ " "interval " "[ " "count " "] ] [ " "datafile " "| " "-[0-9]+ " "]"
+
+.SH DESCRIPTION
+.RB "The " "sadf"
+command is used for displaying the contents of data files created by the
+.BR "sar" "(1) command. But unlike " "sar" ", " "sadf"
+can write its data in many different formats (CSV, XML, etc.)
+The default format is one that can
+easily be handled by pattern processing commands like
+.BR "awk " "(see option " "-p" "). The " "sadf"
+command can also be used to draw graphs for the various activities collected by
+.B sar
+and display them as SVG (Scalable Vector Graphics) graphics in your web browser
+(see option
+.BR "-g" ")."
+.PP
+.RB "The " "sadf"
+command extracts and writes to standard output records saved in the
+.I datafile
+file. This file must have been created by a version of
+.BR "sar " "which is compatible with that of " "sadf" ". If"
+.I datafile
+.RB "is omitted, " "sadf"
+uses the standard system activity daily data file.
+It is also possible to enter
+.BR "-1" ", " "-2 " "etc. as an argument to " "sadf"
+to display data of that days ago. For example,
+.B -1
+will point at the standard system activity file of yesterday.
+.PP
+The standard system activity daily data file is named
+.IR "saDD " "or " "saYYYYMMDD" ", where"
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day.
+.B sadf
+will look for the most recent of
+.IR "saDD " "and " "saYYYYMMDD" ","
+and use it. By default it is located in the
+.I /var/log/sa
+directory. Yet it is possible to specify an alternate location for it: If
+.I datafile
+is a directory (instead of a plain file) then it will be considered as
+the directory where the standard system activity daily data file is located.
+.PP
+.RI "The " "interval " "and " "count " "parameters are used to tell"
+.BR "sadf " "to select"
+.IR "count " "records at " "interval " "seconds apart. If the " "count"
+parameter is not set, then all the records saved in the data file will be displayed.
+.PP
+All the activity flags of
+.B sar
+may be entered on the command line to indicate which
+activities are to be reported. Before specifying them, put a pair of dashes
+.RB "(" "--" ")"
+on the command line in order not to confuse the flags with those of
+.B sadf.
+Not specifying any flags selects only CPU activity.
+
+.SH OPTIONS
+.TP
+.B -C
+.RB "Tell " "sadf " "to display comments present in file."
+.TP
+.B -c
+Convert an old system activity binary datafile (version 9.1.6 and later)
+to current up-to-date format. Use the following syntax:
+
+.BI "sadf -c " "old_datafile " "> " "new_datafile"
+
+Conversion can be controlled using option
+.BR "-O " "(see below)."
+.TP
+.B -d
+Print the contents of the data file in a format that can easily
+be ingested by a relational database system. The output consists
+of fields separated by a semicolon. Each record contains
+the hostname of the host where the file was created, the interval value
+(or -1 if not applicable), the timestamp in a form easily acceptable by
+most databases, and additional semicolon separated data fields as specified by
+.IR "sar_options " "command line options."
+Note that timestamp output can be controlled by options
+.BR "-T" ", " "-t " "and " "-U" "."
+.TP
+.BI "--dev=" "dev_list"
+Specify the block devices for which statistics are to be displayed by
+.BR "sadf" "."
+.I dev_list
+is a list of comma-separated device names. Useful with option
+.BR "-d " "from " "sar" "."
+.RE
+.PP
+.BI "-e [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "-e [ " "seconds_since_the_epoch " "]"
+.RS
+Set the ending time of the report. The default ending
+time is 18:00:00. Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number).
+.RE
+.TP
+.BI "--fs=" "fs_list"
+Specify the filesystems for which statistics are to be displayed by
+.BR "sadf" "."
+.I fs_list
+is a list of comma-separated filesystem names or mountpoints. Useful with option
+.BR "-F " "from " "sar" "."
+.TP
+.B -g
+Print the contents of the data file in SVG (Scalable Vector Graphics) format.
+This option enables you to display some fancy graphs in your web browser.
+Use the following syntax:
+
+.BI "sadf -g " "your_datafile " "[ -- " "sar_options " "] > " "output.svg"
+
+and open the resulting SVG file in your favorite web browser.
+Output can be controlled using option
+.BR "-O " "(see below)."
+.TP
+.B -H
+Display only the header of the report (when applicable). If no format has
+been specified, then the header data (metadata) of the data file are displayed.
+.TP
+.B -h
+When used in conjunction with option
+.BR "-d" ", all activities will be displayed horizontally on a single line."
+.TP
+.BI "--iface=" "iface_list"
+Specify the network interfaces for which statistics are to be displayed by
+.BR "sadf" "."
+.I iface_list
+is a list of comma-separated interface names. Useful with options
+.BR "-n DEV " "and " "-n EDEV " "from " "sar" "."
+.TP
+.BI "--int=" "int_list"
+Specify the interrupts names for which statistics are to be displayed by
+.BR "sadf" "."
+.I int_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0-16,35,40-" "). Useful with option " "-I " "from " "sar" "."
+.TP
+.B -j
+Print the contents of the data file in JSON (JavaScript Object Notation)
+format. Timestamps can be controlled by options
+.BR "-T " "and " "-t" "."
+.TP
+.B -l
+Export the contents of the data file to a PCP (Performance Co-Pilot) archive.
+The name of the archive can be specified using the keyword
+.BR "pcparchive= " "with option " "-O" "."
+.TP
+.BI "-O " "opts" "[,...]"
+Use the specified options to control the output of
+.BR "sadf" "."
+The following options are used to control SVG output displayed by
+.BR "sadf -g" ":"
+.RS
+.IP autoscale
+Draw all the graphs of a given view as large as possible based on current
+view's scale. To do this, a factor (10, 100, 1000...) is used to
+enlarge the graph drawing.
+This option may be interesting when several graphs are drawn on the same
+view, some with only very small values, and others with high ones,
+the latter making the former hardly visible.
+.IP bwcol
+Use a black and white palette to draw the graphs.
+.IP customcol
+Use a customizable color palette instead of the default one to draw
+the graphs. See environment variable
+.B S_COLORS_PALETTE
+below to know how to customize that palette.
+.IP debug
+Add helpful comments in SVG output file.
+.TP
+.RI "height=" "value"
+Set SVG canvas height to
+.IR "value" "."
+.IP oneday
+Display graphs data over a period of 24 hours. Note that hours are still
+printed in UTC by default: You should use option
+.BR "-T " "to print them in local time"
+and get a time window starting from midnight.
+.IP packed
+Group all views from the same activity (and for the same device) on the same row.
+.IP showidle
+Also display %idle state in graphs for CPU statistics.
+.IP showinfo
+Display additional information (such as the date and the host name) on each view.
+.IP showtoc
+Add a table of contents at the beginning of the SVG output, consisting of links
+pointing at the first graph of each activity.
+.IP skipempty
+Do not display views where all graphs have only zero values.
+.RE
+.IP
+The following option may be used when converting an old system activity binary datafile
+to current up-to-date format:
+.RS
+.TP
+.RI "hz=" "value"
+Specify the number of ticks per second for the machine where the old datafile has been created.
+.RE
+.IP
+The following option may be used when data are exported to a PCP archive:
+.RS
+.TP
+.RI "pcparchive=" "name"
+Specify the name of the PCP archive to create.
+.RE
+.IP
+The following option is used to control raw output displayed by
+.BR "sadf -r" ":"
+.RS
+.IP debug
+Display additional information, mainly useful for debugging purpose.
+.RE
+.TP
+.BI "-P { " "cpu_list " "| ALL }"
+.RB "Tell " "sadf"
+that processor dependent statistics are to be reported only for the
+specified processor or processors.
+.I cpu_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0,2,4-7,12-" ")."
+Note that processor 0 is the first processor, and processor
+.BR "all " "is the global average among all processors. Specifying the " "ALL"
+keyword reports statistics for each individual processor, and globally for
+all processors.
+.TP
+.B -p
+Print the contents of the data file in a format that can
+easily be handled by pattern processing commands like
+.BR "awk" "."
+The output consists of fields separated by a tab. Each record contains the
+hostname of the host where the file was created, the interval value
+(or -1 if not applicable), the timestamp, the device name (or - if not applicable),
+the field name and its value.
+Note that timestamp output can be controlled by options
+.BR "-T" ", " "-t " "and " "-U" "."
+.TP
+.B -r
+Print the raw contents of the data file. With this format, the values for
+all the counters are displayed as read from the kernel, which means e.g., that
+no average values are calculated over the elapsed time interval.
+Output can be controlled using option
+.BR "-O " "(see above)."
+.PP
+.BI "-s [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "-s [ " "seconds_since_the_epoch " "]"
+.RS
+Set the starting time of the data, causing the
+.B sadf
+command to extract records time-tagged at, or following, the time
+specified. The default starting time is 08:00:00.
+Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number).
+.RE
+.TP
+.B -T
+Display timestamp in local time instead of UTC (Coordinated Universal Time).
+.TP
+.B -t
+Display timestamp in the original local time of the data file creator
+instead of UTC (Coordinated Universal Time).
+.TP
+.B -U
+Display timestamp (UTC - Coordinated Universal Time) in seconds from the epoch.
+.TP
+.B -V
+Print version number then exit.
+.TP
+.B -x
+Print the contents of the data file in XML format.
+Timestamps can be controlled by options
+.BR "-T " "and " "-t" "."
+The corresponding DTD (Document Type Definition) and XML Schema are included
+in the sysstat source package. They are also available at
+.IR "https://sysstat.github.io/" "."
+
+.SH ENVIRONMENT
+.RB "The " "sadf"
+command takes into account the following environment variables:
+.TP
+.B S_COLORS_PALETTE
+Specify the colors used by
+.B sadf -g
+to render the SVG output. This environment variable is taken into account
+only when the custom color palette has been selected with the option
+.BR "customcol " "(see option " "-O" ")."
+Its value is a colon-separated list of capabilities associated
+with six-digit, three-byte
+hexadecimal numbers (hex triplets) representing colors that defaults to
+
+.B 0=000000:1=1a1aff:2=1affb2:3=b21aff:
+.br
+.B 4=1ab2ff:5=ff1a1a:6=ffb31a:7=b2ff1a:
+.br
+.B 8=efefef:9=000000:A=1a1aff:B=1affb2:
+.br
+.B C=b21aff:D=1ab2ff:E=ff1a1a:F=ffb31a:
+.br
+.B G=bebebe:H=000000:I=000000:K=ffffff:
+.br
+.B L=000000:T=000000:W=000000:X=000000
+
+Capabilities consisting of a hexadecimal digit
+.RB "(" "0 " "through " "F" ") are used to specify"
+the first sixteen colors in the palette (these colors are used to draw the graphs),
+e.g., 3=ffffff would indicate that the third color in the palette is white (0xffffff).
+.br
+Other capabilities are:
+.RS
+.TP
+.B G=
+Specify the color used to draw the grid lines.
+.TP
+.B H=
+Specify the color used to display the report header.
+.TP
+.B I=
+Specify the color used to display additional information (e.g., date, hostname...)
+.TP
+.B K=
+Specify the color used for the graphs background.
+.TP
+.B L=
+Specify the default color (which is for example used to display the table of contents).
+.TP
+.B T=
+Specify the color used to display the graphs title.
+.TP
+.B W=
+Specify the color used to display warning and error messages.
+.TP
+.B X=
+Specify the color used to draw the axes and display the graduations.
+.RE
+.TP
+.B S_TIME_DEF_TIME
+If this variable exists and its value is
+.BR "UTC " "then " "sadf"
+will use UTC time instead of local time to determine the current daily data
+file located in the
+.IR /var/log/sa
+directory.
+
+.SH EXAMPLES
+.TP
+.B sadf -d /var/log/sa/sa21 -- -r -n DEV
+Extract memory and network statistics from system activity file
+.IR "sa21" ","
+and display them in a format that can be ingested by a database.
+.TP
+.B sadf -p -P 1
+Extract CPU statistics for processor 1 (the second processor) from current
+daily data file, and display them in a format that can easily be handled
+by a pattern processing command.
+
+.SH BUGS
+SVG output (as created by option
+.BR "-g" ")"
+is fully compliant with SVG 1.1 standard.
+Graphics have been successfully displayed in various web browsers, including
+Firefox, Chrome and Opera. Yet SVG rendering is broken on Microsoft browsers
+(tested on Internet Explorer 11 and Edge 13.1): So please don't use them.
+
+.SH FILES
+.I /var/log/sa/saDD
+.br
+.I /var/log/sa/saYYYYMMDD
+.RS
+The standard system activity daily data files and their default location.
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day.
+.RE
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "sadc" "(8), " "sa1" "(8), " "sa2" "(8), " "sysstat" "(5)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/sane-config.1 b/upstream/mageia-cauldron/man1/sane-config.1
new file mode 100644
index 00000000..f1c588a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sane-config.1
@@ -0,0 +1,47 @@
+.TH sane\-config 1 "10 Jul 2008" "" "SANE Scanner Access Now Easy"
+.SH NAME
+sane\-config \- get information about the installed version of libsane
+.SH SYNOPSIS
+.B  sane\-config [\-\-prefix] [\-\-exec\-prefix] [\-\-libs] [\-\-cflags] [\-\-ldflags] [\-\-version] [\-\-help \fI[OPTION]\fP]
+.SH DESCRIPTION
+.PP
+.B sane\-config
+is a tool that is used to determine the compiler and linker
+flags that should be used to compile and link SANE frontends to a SANE backend library (libsane).
+.
+.SH OPTIONS
+.B sane\-config
+accepts the following options (you can't use more than one option at the same time):
+.TP 8
+.B  \-\-version
+Print the currently installed version of libsane on the standard output.
+.TP 8
+.B  \-\-help OPTION
+Print a short usage message. If
+.I OPTION
+is specified, help for that option (e.g.
+.BR \-\-libs )
+is printed (if available).
+.TP 8
+.B  \-\-libs
+Print the additional libraries that are necessary to link a SANE frontend to libsane.
+.TP 8
+.B  \-\-ldflags
+Print the linker flags that are necessary to link a SANE frontend to libsane.
+.TP 8
+.B  \-\-cflags
+Print the compiler flags that are necessary to compile a SANE frontend.
+.TP 8
+.B  \-\-prefix
+Print the prefix used during compilation of libsane.
+.TP 8
+.B  \-\-exec\-prefix
+Print the exec\-prefix used during compilation of libsane.
+
+.SH "SEE ALSO"
+.BR sane (7)
+
+.SH AUTHOR
+This manual page was written by Julien BLACHE
+.RI < jblache@debian.org > ,
+for the Debian GNU/Linux system (but may be used by others).
diff --git a/upstream/mageia-cauldron/man1/sane-find-scanner.1 b/upstream/mageia-cauldron/man1/sane-find-scanner.1
new file mode 100644
index 00000000..d098f7a2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sane-find-scanner.1
@@ -0,0 +1,134 @@
+.TH sane\-find\-scanner 1 "13 Jul 2008" "" "SANE Scanner Access Now Easy"
+.IX sane\-find\-scanner
+.SH NAME
+sane\-find\-scanner \- find SCSI and USB scanners and their device files
+.SH SYNOPSIS
+.B sane\-find\-scanner
+.RB [ \-? | \-h | \-\-help ]
+.RB [ \-v ]
+.RB [ \-q ]
+.RB [ \-p ]
+.RB [ \-f ]
+.RB [ \-F
+.IR filename ]
+.RI [ devname ]
+
+.SH DESCRIPTION
+.B sane\-find\-scanner
+is a command-line tool to find SCSI and USB scanners and determine their UNIX
+device files. Its primary aim is to make sure that scanners can be detected by
+SANE backends.
+.PP
+For
+.B SCSI
+scanners, it checks the default generic SCSI device files (e.g.,
+.IR /dev/sg0 )
+and
+.IR /dev/scanner .
+The test is done by sending a SCSI inquiry command and looking for a device
+type of "scanner" or "processor" (some old HP scanners seem to send
+"processor"). So
+.B sane\-find\-scanner
+will find any SCSI scanner connected to those default device files even if it
+isn't supported by any SANE backend.
+.PP
+For
+.B USB
+scanners, first the USB kernel scanner device files (e.g.
+.IR /dev/usb/scanner0 ,
+.IR /dev/usb/scanner ,
+and
+.IR /dev/usbscanner )
+are tested. The files are opened and the vendor and device ids are determined,
+if the operating system supports this feature. Currently USB scanners are only
+found this way if they are supported by the Linux scanner module or the
+FreeBSD or OpenBSD uscanner driver. After that test,
+.B sane\-find\-scanner
+tries to scan for USB devices found by the USB library libusb (if
+available). There is no special USB class for scanners, so the heuristics used
+to distinguish scanners from other USB devices is not
+perfect.
+.B sane\-find\-scanner
+also tries to find out the type of USB chip used in the scanner. If detected,
+it will be printed after the vendor and product ids.
+.B sane\-find\-scanner
+will even find USB scanners, that are not supported by any SANE backend.
+.PP
+.B sane\-find\-scanner
+won't find most
+parallel port scanners, or scanners connected to proprietary ports. Some
+.B parallel port
+scanners may be detected by
+.I "sane\-find\-scanner -p" .
+At the time of writing this will only detect Mustek parallel port scanners.
+
+.SH OPTIONS
+.TP 8
+.B \-?, \-h, \-\-help
+Prints a short usage message.
+.TP 8
+.B \-v
+Verbose output. If used once,
+.B sane\-find\-scanner
+shows every device name and the test result.  If used twice, SCSI inquiry
+information and the USB device descriptors are also printed.
+.TP 8
+.B \-q
+Be quiet. Print only the devices, no comments.
+.TP 8
+.B \-p
+Probe parallel port scanners.
+.TP 8
+.B \-f
+Force opening all explicitly given devices as SCSI and USB devices. That's
+useful if
+.B sane\-find\-scanner
+is wrong in determining the device type.
+.TP 8
+.B \-F filename
+filename is a file that contains USB descriptors in the format of
+/proc/bus/usb/devices as used by Linux.
+.B sane\-find\-scanner
+tries to identify the chipset(s) of all USB scanners found in such a file. This
+option is useful for developers when the output of
+.I "cat /proc/bus/usb/devices"
+is available but the scanner itself isn't.
+.TP 8
+.B devname
+Test device file "devname". No other devices are checked if devname is given.
+.SH EXAMPLE
+.I sane\-find\-scanner \-v
+.br
+Check all SCSI and USB devices for available scanners and print a line for
+every device file.
+.PP
+.I sane\-find\-scanner /dev/scanner
+.br
+Look for a (SCSI) scanner only at /dev/scanner and print the result.
+.PP
+.I sane\-find\-scanner \-p
+.br
+Probe for parallel port scanners.
+.SH "SEE ALSO"
+.BR sane (7),
+.BR sane\-scsi (5),
+.BR sane\-usb (5),
+.BR scanimage (1),
+.BR xscanimage (1),
+.BR xsane (1),
+.BR sane\-"backendname" (5)
+
+.SH AUTHOR
+Oliver Rauch, Henning Meier-Geinitz and others
+.SH SUPPORTED PLATFORMS
+USB support is limited to Linux (kernel, libusb), FreeBSD (kernel,
+libusb), NetBSD (libusb), OpenBSD (kernel, libusb). Detecting the vendor and
+device ids only works with Linux or libusb.
+.PP
+SCSI support is available on Irix, EMX, Linux, Next, AIX, Solaris, FreeBSD,
+NetBSD, OpenBSD, and HP-UX.
+
+.SH BUGS
+No support for most parallel port scanners yet.
+.br
+Detection of USB chipsets is limited to a few chipsets.
diff --git a/upstream/mageia-cauldron/man1/sar.1 b/upstream/mageia-cauldron/man1/sar.1
new file mode 100644
index 00000000..b1443368
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sar.1
@@ -0,0 +1,1727 @@
+.\" sar manual page - (C) 1999-2023 Sebastien Godard (sysstat <at> orange.fr)
+.TH SAR 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+sar \- Collect, report, or save system activity information.
+
+.SH SYNOPSIS
+.B sar [ -A ] [ -B ] [ -b ] [ -C ] [ -D ] [ -d ] [ -F [ MOUNT ] ] [ -H ] [ -h ] [ -p ]
+.B [ -r [ ALL ] ] [ -S ] [ -t ] [ -u [ ALL ] ] [ -V ] [ -v ] [ -W ] [ -w ] [ -x ] [ -y ] [ -z ]
+.B [ --dec={ 0 | 1 | 2 } ]
+.BI "[ --dev=" "dev_list " "] [ --fs=" "fs_list " "] [ --help ] [ --human ] [ --iface=" "iface_list"
+.BI "] [ --int=" "int_list " "] [ --pretty ] [ --sadc ] [ -I [ SUM | ALL ] ] [ -P { " "cpu_list"
+.B | ALL } ] [ -m {
+.IB "keyword" "[,...] | ALL } ] [ -n { " "keyword" "[,...] | ALL } ] [ -q [ " "keyword" "[,...] | ALL ] ]"
+.B [ -j { SID | ID | LABEL | PATH | UUID | ... } ]
+.BI "[ -f [ " "filename " "] | -o [ " "filename " "] | -[0-9]+ ]"
+.BI "[ -i " "interval " "] [ -s [ " "start_time "
+.BI "] ] [ -e [ " "end_time " "] ] ] [ " "interval " "[ " "count " "] ]"
+
+.SH DESCRIPTION
+.RB "The " "sar"
+command writes to standard output the contents of selected
+cumulative activity counters in the operating system. The accounting
+system, based on the values in the
+.IR "count " "and " "interval"
+parameters, writes information the specified number of times spaced
+at the specified intervals in seconds.
+If the
+.IR "interval " "parameter is set to zero, the"
+.B sar
+command displays the average statistics for the time
+since the system was started. If the
+.IR "interval " "parameter is specified without the " "count"
+parameter, then reports are generated continuously.
+The collected data can also
+be saved in the file specified by the
+.BI "-o " "filename"
+flag, in addition to being displayed onto the screen. If
+.IR "filename " "is omitted,"
+.B sar
+uses the standard system activity daily data file (see below).
+By default all the data available from the kernel are saved in the
+data file.
+.PP
+.RB "The " "sar"
+command extracts and writes to standard output records previously
+saved in a file. This file can be either the one specified by the
+.B -f
+flag or, by default, the standard system activity daily data file.
+It is also possible to enter
+.BR "-1" ", " "-2 " "etc. as an argument to " "sar"
+to display data of that days ago. For example,
+.BR "-1 " "will point at the standard system activity file of yesterday."
+.PP
+Standard system activity daily data files are named
+.IR "saDD " "or " "saYYYYMMDD" ", where"
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day. They are the default files used by
+.B sar
+only when no filename has been explicitly specified.
+When used to write data to files (with its option
+.BR "-o" "), " "sar"
+will use
+.I saYYYYMMDD
+.RB "if option " "-D"
+has also been specified, else it will use
+.IR "saDD" "."
+When used to display the records previously saved in a file,
+.B sar
+will look for the most recent of
+.IR "saDD " "and " "saYYYYMMDD" ", and use it."
+.PP
+Standard system activity daily data files are located in the
+.I /var/log/sa
+directory by default. Yet it is possible to specify an alternate
+location for them: If a directory (instead of a plain file) is used
+with options
+.BR "-f " "or " "-o"
+then it will be considered as the directory containing the data files.
+.PP
+.RB "Without the " "-P " "flag, the " "sar"
+command reports system-wide (global among all processors) statistics,
+which are calculated as averages for values expressed as percentages,
+and as sums otherwise. If the
+.BR "-P " "flag is given, the " "sar"
+command reports activity which relates to the specified processor or
+processors. If
+.BR "-P ALL " "is given, the " "sar"
+command reports statistics for each individual processor and global
+statistics among all processors. Offline processors are not displayed.
+.PP
+You can select information about specific system activities using
+flags. Not specifying any flags selects only CPU activity.
+Specifying the
+.B -A
+flag selects all possible activities.
+.PP
+The default version of the
+.B sar
+command (CPU utilization report) might be one of the first facilities
+the user runs to begin system activity investigation, because it
+monitors major system resources. If CPU utilization is near 100 percent
+(user + nice + system), the workload sampled is CPU-bound.
+
+If multiple samples and multiple reports are desired, it is convenient
+to specify an output file for the
+.BR "sar " "command. Run the " "sar"
+command as a background process. The syntax for this is:
+
+.BI "sar -o " "datafile interval count " ">/dev/null 2>&1 &"
+
+All data are captured in binary form and saved to a file
+.RI "(" "datafile" ")."
+The data can then be selectively displayed with the
+.BR "sar " "command using the " "-f " "option. Set the"
+.IR "interval " "and " "count " "parameters to select " "count " "records at " "interval"
+.RI "second intervals. If the " "count"
+parameter is not set, all the records saved in the file will be selected.
+Collection of data in this manner is useful to characterize
+system usage over a period of time and determine peak usage hours.
+.PP
+.RB "Note: The " "sar"
+command only reports on local activities.
+
+.SH OPTIONS
+.TP
+.B -A
+This is equivalent to specifying
+.BR "-bBdFHISvwWy -m ALL -n ALL -q ALL -r ALL -u ALL" "."
+This option also implies specifying
+.B -I ALL -P ALL
+unless these options are explicitly set on the command line.
+.TP
+.B -B
+Report paging statistics.
+The following values are displayed:
+.RS
+.IP pgpgin/s
+Total number of kilobytes the system paged in from disk per second.
+.IP pgpgout/s
+Total number of kilobytes the system paged out to disk per second.
+.IP fault/s
+Number of page faults (major + minor) made by the system per second.
+This is not a count of page faults that generate I/O, because some page
+faults can be resolved without I/O.
+.IP majflt/s
+Number of major faults the system has made per second, those which
+have required loading a memory page from disk.
+.IP pgfree/s
+Number of pages placed on the free list by the system per second.
+.IP pgscank/s
+Number of pages scanned by the kswapd daemon per second.
+.IP pgscand/s
+Number of pages scanned directly per second.
+.IP pgsteal/s
+Number of pages the system has reclaimed from cache (pagecache and
+swapcache) per second to satisfy its memory demands.
+.IP %vmeff
+Calculated as pgsteal / pgscan, this is a metric of the efficiency of
+page reclaim. If it is near 100% then almost every page coming off the
+tail of the inactive list is being reaped. If it gets too low (e.g. less
+than 30%) then the virtual memory is having some difficulty.
+This field is displayed as zero if no pages have been scanned during the
+interval of time.
+.RE
+.TP
+.B -b
+Report I/O and transfer rate statistics. The following values are displayed:
+.RS
+.IP tps
+Total number of transfers per second that were issued to physical devices.
+A transfer is an I/O request to a physical device. Multiple logical
+requests can be combined into a single I/O request to the device.
+A transfer is of indeterminate size.
+.IP rtps
+Total number of read requests per second issued to physical devices.
+.IP wtps
+Total number of write requests per second issued to physical devices.
+.IP dtps
+Total number of discard requests per second issued to physical devices.
+.IP bread/s
+Total amount of data read from the devices in blocks per second.
+Blocks are equivalent to sectors and therefore have a size of 512 bytes.
+.IP bwrtn/s
+Total amount of data written to devices in blocks per second.
+.IP bdscd/s
+Total amount of data discarded for devices in blocks per second.
+.RE
+.TP
+.B -C
+When reading data from a file, tell
+.BR "sar " "to display comments that have been inserted by " "sadc" "."
+.TP
+.B -D
+.RI "Use " "saYYYYMMDD " "instead of " "saDD"
+as the standard system activity daily data file name. This option
+works only when used in conjunction with option
+.BR "-o " "to save data to file."
+.TP
+.B -d
+Report activity for each block device.
+When data are displayed, the device name is displayed as it
+(should) appear in
+.IR "/dev" "."
+.BR "sar " "uses data in"
+.IR "/sys " "to determine the device name based on its major and minor numbers."
+.RB "If this name resolution fails, " "sar " "will use name mapping controlled by"
+.IR "/etc/sysconfig/sysstat.ioconf " "file."
+Persistent device names can also be printed if option
+.B -j
+is used (see below). Statistics for all devices are displayed unless
+a restricted list is specified using option
+.B --dev=
+(see corresponding option entry).
+Note that disk activity depends on
+.BR "sadc" "'s options " "-S DISK " "and " "-S XDISK"
+to be collected. The following values are displayed:
+.RS
+.IP tps
+Total number of transfers per second that were issued to physical devices.
+A transfer is an I/O request to a physical device. Multiple logical
+requests can be combined into a single I/O request to the device.
+A transfer is of indeterminate size.
+.IP rkB/s
+Number of kilobytes read from the device per second.
+.IP wkB/s
+Number of kilobytes written to the device per second.
+.IP dkB/s
+Number of kilobytes discarded for the device per second.
+.IP areq-sz
+The average size (in kilobytes) of the I/O requests that were issued to the device.
+.br
+Note: In previous versions, this field was known as avgrq-sz and was expressed in sectors.
+.IP aqu-sz
+The average queue length of the requests that were issued to the device.
+.br
+Note: In previous versions, this field was known as avgqu-sz.
+.IP await
+The average time (in milliseconds) for I/O requests issued to the device
+to be served. This includes the time spent by the requests in queue and
+the time spent servicing them.
+.IP %util
+Percentage of elapsed time during which I/O requests were issued to the device
+(bandwidth utilization for the device). Device saturation occurs when this
+value is close to 100% for devices serving requests serially. But for
+devices serving requests in parallel, such as RAID arrays and modern SSDs,
+this number does not reflect their performance limits.
+.RE
+.TP
+.B --dec={ 0 | 1 | 2 }
+Specify the number of decimal places to use (0 to 2, default value is 2).
+.TP
+.BI "--dev=" "dev_list"
+Specify the block devices for which statistics are to be displayed by
+.BR "sar" "."
+.IR "dev_list " "is a list of comma-separated device names."
+.RE
+.PP
+.BI "-e [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "-e [ " "seconds_since_the_epoch " "]"
+.RS
+Set the ending time of the report. The default ending time is
+18:00:00. Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number).
+This option can be used when data are read from
+or written to a file (options
+.BR "-f " "or " "-o" ")."
+.RE
+.TP
+.B -F [ MOUNT ]
+Display statistics for currently mounted filesystems. Pseudo-filesystems are
+ignored. At the end of the report,
+.B sar
+will display a summary of all those filesystems. Use of the
+.B MOUNT
+parameter keyword indicates that mountpoint will be reported instead of
+filesystem device. Statistics for all filesystems are displayed unless
+a restricted list is specified using option
+.B --fs=
+(see corresponding option entry).
+Note that filesystems statistics depend on
+.BR "sadc" "'s option " "-S XDISK "
+to be collected.
+
+The following values are displayed:
+.RS
+.IP MBfsfree
+Total amount of free space in megabytes (including space available only to privileged user).
+.IP MBfsused
+Total amount of space used in megabytes.
+.IP %fsused
+Percentage of filesystem space used, as seen by a privileged user.
+.IP %ufsused
+Percentage of filesystem space used, as seen by an unprivileged user.
+.IP Ifree
+Total number of free file nodes in filesystem.
+.IP Iused
+Total number of file nodes used in filesystem.
+.IP %Iused
+Percentage of file nodes used in filesystem.
+.RE
+.TP
+.BI "-f [ " "filename " "]"
+.RI "Extract records from " "filename " "(created by the"
+.BI "-o " "filename"
+flag). The default value of the
+.I filename
+parameter is the current standard system activity daily data file. If
+.I filename
+is a directory instead of a plain file then it is considered as the
+directory where the standard system activity daily data files are
+located. Option
+.BR "-f " "is exclusive of option " "-o" "."
+.TP
+.BI "--fs=" "fs_list"
+Specify the filesystems for which statistics are to be displayed by
+.BR "sar" "."
+.I fs_list
+is a list of comma-separated filesystem names or mountpoints.
+.TP
+.B -H
+Report hugepages utilization statistics.
+The following values are displayed:
+.RS
+.IP kbhugfree
+Amount of hugepages memory in kilobytes that is not yet allocated.
+.IP kbhugused
+Amount of hugepages memory in kilobytes that has been allocated.
+.IP %hugused
+Percentage of total hugepages memory that has been allocated.
+.IP kbhugrsvd
+Amount of reserved hugepages memory in kilobytes.
+.IP kbhugsurp
+Amount of surplus hugepages memory in kilobytes.
+.RE
+.TP
+.B -h
+This option is equivalent to specifying
+.BR "--pretty --human" "."
+.TP
+.B --help
+Display a short help message then exit.
+.TP
+.B --human
+Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
+The units displayed with this option supersede any other default units (e.g.
+kilobytes, sectors...) associated with the metrics.
+.TP
+.BI "-I [ SUM | ALL ]"
+Report statistics for interrupts. The values displayed are the number of interrupts
+per second for the given processor or among all processors.
+A list of interrupts can be specified using
+.B --int=
+(see this option). The
+.B SUM
+keyword indicates that the total number of interrupts received per second
+is to be displayed. The
+.B ALL
+keyword indicates that statistics from all interrupts are to be reported
+(this is the default).
+Note that interrupts statistics depend on
+.BR "sadc" "'s option " "-S INT"
+to be collected.
+.TP
+.BI "-i " "interval"
+Select data records at seconds as close as possible to the number specified
+.RI "by the " "interval " "parameter."
+.TP
+.BI "--iface=" "iface_list"
+Specify the network interfaces for which statistics are to be displayed by
+.BR "sar" "."
+.I iface_list
+is a list of comma-separated interface names.
+.TP
+.BI "--int=" "int_list"
+Specify the interrupts names for which statistics are to be displayed by
+.BR "sar" "."
+.I int_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0-16,35,40-" ").
+.TP
+.B -j { SID | ID | LABEL | PATH | UUID | ... }
+Display persistent device names. Use this option in conjunction with option
+.BR "-d" ". Keywords " "ID" ", " "LABEL" ","
+etc. specify the type of the persistent name. These keywords are not limited,
+only prerequisite is that directory with required persistent names is present in
+.IR "/dev/disk" "."
+.RB "Keyword " "SID"
+tries to get a stable identifier to use as the device name. A stable
+identifier won't change across reboots for the same physical device. If it exists,
+this identifier is normally the WWN (World Wide Name) of the device, as read from the
+.IR "/dev/disk/by-id " "directory."
+.TP
+.BI "-m { " "keyword" "[,...] | ALL }"
+Report power management statistics.
+Note that these statistics depend on
+.BR "sadc" "'s option " "-S POWER " "to be collected."
+
+Possible keywords are
+.BR "BAT" ", " "CPU" ", " "FAN" ", " "FREQ" ", " "IN" ", " "TEMP " "and " "USB" "."
+
+.RB "With the " "BAT"
+keyword, statistics about batteries capacity are reported.
+The following values are displayed:
+.RS
+.IP %cap
+Battery capacity.
+.IP cap/min
+Capacity lost or gained per minute by the battery.
+.IP status
+Charging status of the battery: ↑ (full), ↗ (charging), → (not charging), ↘ (discharging), ? (unknown).
+.RE
+
+.IP
+.RB "With the " "CPU"
+keyword, statistics about CPU are reported.
+The following value is displayed:
+.RS
+.IP MHz
+Instantaneous CPU clock frequency in MHz.
+.RE
+
+.IP
+.RB "With the " "FAN"
+keyword, statistics about fans speed are reported.
+The following values are displayed:
+.RS
+.IP rpm
+Fan speed expressed in revolutions per minute.
+.IP drpm
+This field is calculated as the difference between current fan speed (rpm)
+and its low limit (fan_min).
+.IP DEVICE
+Sensor device name.
+.RE
+
+.IP
+.RB "With the " "FREQ"
+keyword, statistics about CPU clock frequency are reported.
+The following value is displayed:
+.RS
+.IP wghMHz
+Weighted average CPU clock frequency in MHz.
+Note that the cpufreq-stats driver must be compiled in the
+kernel for this option to work.
+.RE
+
+.IP
+.RB "With the " "IN"
+keyword, statistics about voltage inputs are reported.
+The following values are displayed:
+.RS
+.IP inV
+Voltage input expressed in Volts.
+.IP %in
+Relative input value. A value of 100% means that
+voltage input has reached its high limit (in_max) whereas
+a value of 0% means that it has reached its low limit (in_min).
+.IP DEVICE
+Sensor device name.
+.RE
+
+.IP
+.RB "With the " "TEMP"
+keyword, statistics about devices temperature are reported.
+The following values are displayed:
+.RS
+.IP degC
+Device temperature expressed in degrees Celsius.
+.IP %temp
+Relative device temperature. A value of 100% means that
+temperature has reached its high limit (temp_max).
+.IP DEVICE
+Sensor device name.
+.RE
+
+.IP
+.RB "With the " "USB " "keyword, the " "sar"
+command takes a snapshot of all the USB devices currently plugged into
+the system. At the end of the report,
+.B sar
+will display a summary of all those USB devices.
+The following values are displayed:
+.RS
+.IP BUS
+Root hub number of the USB device.
+.IP idvendor
+Vendor ID number (assigned by USB organization).
+.IP idprod
+Product ID number (assigned by Manufacturer).
+.IP maxpower
+Maximum power consumption of the device (expressed in mA).
+.IP manufact
+Manufacturer name.
+.IP product
+Product name.
+.RE
+
+.IP
+.RB "The " "ALL"
+keyword is equivalent to specifying all the keywords above and therefore all the power
+management statistics are reported.
+.TP
+.BI "-n { " "keyword" "[,...] | ALL }"
+Report network statistics.
+
+Possible keywords are
+.BR "DEV" ", " "EDEV" ", " "FC" ", " "ICMP" ", " "EICMP" ", " "ICMP6" ", " "EICMP6" ","
+.BR "IP" ", " "EIP" ", " "IP6" ", " "EIP6" ", " "NFS" ", " "NFSD" ", " "SOCK" ", " "SOCK6" ","
+.BR "SOFT" ", " "TCP" ", " "ETCP" ", " "UDP " "and " "UDP6" "."
+
+.RB "With the " "DEV"
+keyword, statistics from the network devices are reported.
+Statistics for all network interfaces are displayed unless
+a restricted list is specified using option
+.B --iface=
+(see corresponding option entry).
+The following values are displayed:
+.RS
+.IP IFACE
+Name of the network interface for which statistics are reported.
+.IP rxpck/s
+Total number of packets received per second.
+.IP txpck/s
+Total number of packets transmitted per second.
+.IP rxkB/s
+Total number of kilobytes received per second.
+.IP txkB/s
+Total number of kilobytes transmitted per second.
+.IP rxcmp/s
+Number of compressed packets received per second (for cslip etc.).
+.IP txcmp/s
+Number of compressed packets transmitted per second.
+.IP rxmcst/s
+Number of multicast packets received per second.
+.IP %ifutil
+Utilization percentage of the network interface. For half-duplex interfaces,
+utilization is calculated using the sum of rxkB/s and txkB/s as a percentage
+of the interface speed. For full-duplex, this is the greater of rxkB/S or txkB/s.
+.RE
+
+.IP
+.RB "With the " "EDEV"
+keyword, statistics on failures (errors) from the network devices are reported.
+Statistics for all network interfaces are displayed unless
+a restricted list is specified using option
+.B --iface=
+(see corresponding option entry).
+The following values are displayed:
+.RS
+.IP IFACE
+Name of the network interface for which statistics are reported.
+.IP rxerr/s
+Total number of bad packets received per second.
+.IP txerr/s
+Total number of errors that happened per second while transmitting packets.
+.IP coll/s
+Number of collisions that happened per second while transmitting packets.
+.IP rxdrop/s
+Number of received packets dropped per second because of a lack of space in linux buffers.
+.IP txdrop/s
+Number of transmitted packets dropped per second because of a lack of space in linux buffers.
+.IP txcarr/s
+Number of carrier-errors that happened per second while transmitting packets.
+.IP rxfram/s
+Number of frame alignment errors that happened per second on received packets.
+.IP rxfifo/s
+Number of FIFO overrun errors that happened per second on received packets.
+.IP txfifo/s
+Number of FIFO overrun errors that happened per second on transmitted packets.
+.RE
+
+.IP
+.RB "With the " "FC"
+keyword, statistics about fibre channel traffic are reported.
+Note that fibre channel statistics depend on
+.BR "sadc" "'s option " "-S DISK"
+to be collected.
+The following values are displayed:
+.RS
+.IP FCHOST
+Name of the fibre channel host bus adapter (HBA) interface for which statistics are reported.
+.IP fch_rxf/s
+The total number of frames received per second.
+.IP fch_txf/s
+The total number of frames transmitted per second.
+.IP fch_rxw/s
+The total number of transmission words received per second.
+.IP fch_txw/s
+The total number of transmission words transmitted per second.
+.RE
+
+.IP
+.RB "With the " "ICMP"
+keyword, statistics about ICMPv4 network traffic are reported.
+Note that ICMPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP imsg/s
+The total number of ICMP messages which the entity
+received per second [icmpInMsgs].
+Note that this counter includes all those counted by ierr/s.
+.IP omsg/s
+The total number of ICMP messages which this entity
+attempted to send per second [icmpOutMsgs].
+Note that this counter includes all those counted by oerr/s.
+.IP iech/s
+The number of ICMP Echo (request) messages received per second [icmpInEchos].
+.IP iechr/s
+The number of ICMP Echo Reply messages received per second [icmpInEchoReps].
+.IP oech/s
+The number of ICMP Echo (request) messages sent per second [icmpOutEchos].
+.IP oechr/s
+The number of ICMP Echo Reply messages sent per second [icmpOutEchoReps].
+.IP itm/s
+The number of ICMP Timestamp (request) messages received per second [icmpInTimestamps].
+.IP itmr/s
+The number of ICMP Timestamp Reply messages received per second [icmpInTimestampReps].
+.IP otm/s
+The number of ICMP Timestamp (request) messages sent per second [icmpOutTimestamps].
+.IP otmr/s
+The number of ICMP Timestamp Reply messages sent per second [icmpOutTimestampReps].
+.IP iadrmk/s
+The number of ICMP Address Mask Request messages received per second [icmpInAddrMasks].
+.IP iadrmkr/s
+The number of ICMP Address Mask Reply messages received per second [icmpInAddrMaskReps].
+.IP oadrmk/s
+The number of ICMP Address Mask Request messages sent per second [icmpOutAddrMasks].
+.IP oadrmkr/s
+The number of ICMP Address Mask Reply messages sent per second [icmpOutAddrMaskReps].
+.RE
+
+.IP
+.RB "With the " "EICMP"
+keyword, statistics about ICMPv4 error messages are reported.
+Note that ICMPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP ierr/s
+The number of ICMP messages per second which the entity received but
+determined as having ICMP-specific errors (bad ICMP
+checksums, bad length, etc.) [icmpInErrors].
+.IP oerr/s
+The number of ICMP messages per second which this entity did not send
+due to problems discovered within ICMP such as a lack of buffers [icmpOutErrors].
+.IP idstunr/s
+The number of ICMP Destination Unreachable messages
+received per second [icmpInDestUnreachs].
+.IP odstunr/s
+The number of ICMP Destination Unreachable messages sent per second [icmpOutDestUnreachs].
+.IP itmex/s
+The number of ICMP Time Exceeded messages received per second [icmpInTimeExcds].
+.IP otmex/s
+The number of ICMP Time Exceeded messages sent per second [icmpOutTimeExcds].
+.IP iparmpb/s
+The number of ICMP Parameter Problem messages received per second [icmpInParmProbs].
+.IP oparmpb/s
+The number of ICMP Parameter Problem messages sent per second [icmpOutParmProbs].
+.IP isrcq/s
+The number of ICMP Source Quench messages received per second [icmpInSrcQuenchs].
+.IP osrcq/s
+The number of ICMP Source Quench messages sent per second [icmpOutSrcQuenchs].
+.IP iredir/s
+The number of ICMP Redirect messages received per second [icmpInRedirects].
+.IP oredir/s
+The number of ICMP Redirect messages sent per second [icmpOutRedirects].
+.RE
+
+.IP
+.RB "With the " "ICMP6"
+keyword, statistics about ICMPv6 network traffic are reported.
+Note that ICMPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP imsg6/s
+The total number of ICMP messages received
+by the interface per second which includes all those
+counted by ierr6/s [ipv6IfIcmpInMsgs].
+.IP omsg6/s
+The total number of ICMP messages which this
+interface attempted to send per second [ipv6IfIcmpOutMsgs].
+.IP iech6/s
+The number of ICMP Echo (request) messages
+received by the interface per second [ipv6IfIcmpInEchos].
+.IP iechr6/s
+The number of ICMP Echo Reply messages received
+by the interface per second [ipv6IfIcmpInEchoReplies].
+.IP oechr6/s
+The number of ICMP Echo Reply messages sent
+by the interface per second [ipv6IfIcmpOutEchoReplies].
+.IP igmbq6/s
+The number of ICMPv6 Group Membership Query
+messages received by the interface per second
+[ipv6IfIcmpInGroupMembQueries].
+.IP igmbr6/s
+The number of ICMPv6 Group Membership Response messages
+received by the interface per second
+[ipv6IfIcmpInGroupMembResponses].
+.IP ogmbr6/s
+The number of ICMPv6 Group Membership Response
+messages sent per second
+[ipv6IfIcmpOutGroupMembResponses].
+.IP igmbrd6/s
+The number of ICMPv6 Group Membership Reduction messages
+received by the interface per second
+[ipv6IfIcmpInGroupMembReductions].
+.IP ogmbrd6/s
+The number of ICMPv6 Group Membership Reduction
+messages sent per second
+[ipv6IfIcmpOutGroupMembReductions].
+.IP irtsol6/s
+The number of ICMP Router Solicit messages
+received by the interface per second
+[ipv6IfIcmpInRouterSolicits].
+.IP ortsol6/s
+The number of ICMP Router Solicitation messages
+sent by the interface per second
+[ipv6IfIcmpOutRouterSolicits].
+.IP irtad6/s
+The number of ICMP Router Advertisement messages
+received by the interface per second
+[ipv6IfIcmpInRouterAdvertisements].
+.IP inbsol6/s
+The number of ICMP Neighbor Solicit messages
+received by the interface per second
+[ipv6IfIcmpInNeighborSolicits].
+.IP onbsol6/s
+The number of ICMP Neighbor Solicitation
+messages sent by the interface per second
+[ipv6IfIcmpOutNeighborSolicits].
+.IP inbad6/s
+The number of ICMP Neighbor Advertisement
+messages received by the interface per second
+[ipv6IfIcmpInNeighborAdvertisements].
+.IP onbad6/s
+The number of ICMP Neighbor Advertisement
+messages sent by the interface per second
+[ipv6IfIcmpOutNeighborAdvertisements].
+.RE
+
+.IP
+.RB "With the " "EICMP6"
+keyword, statistics about ICMPv6 error messages are reported.
+Note that ICMPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP ierr6/s
+The number of ICMP messages per second which the interface
+received but determined as having ICMP-specific
+errors (bad ICMP checksums, bad length, etc.)
+[ipv6IfIcmpInErrors]
+.IP idtunr6/s
+The number of ICMP Destination Unreachable
+messages received by the interface per second
+[ipv6IfIcmpInDestUnreachs].
+.IP odtunr6/s
+The number of ICMP Destination Unreachable
+messages sent by the interface per second
+[ipv6IfIcmpOutDestUnreachs].
+.IP itmex6/s
+The number of ICMP Time Exceeded messages
+received by the interface per second
+[ipv6IfIcmpInTimeExcds].
+.IP otmex6/s
+The number of ICMP Time Exceeded messages sent
+by the interface per second
+[ipv6IfIcmpOutTimeExcds].
+.IP iprmpb6/s
+The number of ICMP Parameter Problem messages
+received by the interface per second
+[ipv6IfIcmpInParmProblems].
+.IP oprmpb6/s
+The number of ICMP Parameter Problem messages
+sent by the interface per second
+[ipv6IfIcmpOutParmProblems].
+.IP iredir6/s
+The number of Redirect messages received
+by the interface per second
+[ipv6IfIcmpInRedirects].
+.IP oredir6/s
+The number of Redirect messages sent by
+the interface by second
+[ipv6IfIcmpOutRedirects].
+.IP ipck2b6/s
+The number of ICMP Packet Too Big messages
+received by the interface per second
+[ipv6IfIcmpInPktTooBigs].
+.IP opck2b6/s
+The number of ICMP Packet Too Big messages sent
+by the interface per second
+[ipv6IfIcmpOutPktTooBigs].
+.RE
+
+.IP
+.RB "With the " "IP"
+keyword, statistics about IPv4 network traffic are reported.
+Note that IPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP irec/s
+The total number of input datagrams received from interfaces
+per second, including those received in error [ipInReceives].
+.IP fwddgm/s
+The number of input datagrams per second, for which this entity was not
+their final IP destination, as a result of which an attempt
+was made to find a route to forward them to that final
+destination [ipForwDatagrams].
+.IP idel/s
+The total number of input datagrams successfully delivered per second
+to IP user-protocols (including ICMP) [ipInDelivers].
+.IP orq/s
+The total number of IP datagrams which local IP user-protocols (including ICMP)
+supplied per second to IP in requests for transmission [ipOutRequests].
+Note that this counter does not include any datagrams counted in fwddgm/s.
+.IP asmrq/s
+The number of IP fragments received per second which needed to be
+reassembled at this entity [ipReasmReqds].
+.IP asmok/s
+The number of IP datagrams successfully re-assembled per second [ipReasmOKs].
+.IP fragok/s
+The number of IP datagrams that have been successfully
+fragmented at this entity per second [ipFragOKs].
+.IP fragcrt/s
+The number of IP datagram fragments that have been
+generated per second as a result of fragmentation at this entity [ipFragCreates].
+.RE
+
+.IP
+.RB "With the " "EIP"
+keyword, statistics about IPv4 network errors are reported.
+Note that IPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP ihdrerr/s
+The number of input datagrams discarded per second due to errors in
+their IP headers, including bad checksums, version number
+mismatch, other format errors, time-to-live exceeded, errors
+discovered in processing their IP options, etc. [ipInHdrErrors]
+.IP iadrerr/s
+The number of input datagrams discarded per second because the IP
+address in their IP header's destination field was not a
+valid address to be received at this entity. This count
+includes invalid addresses (e.g., 0.0.0.0) and addresses of
+unsupported Classes (e.g., Class E). For entities which are
+not IP routers and therefore do not forward datagrams, this
+counter includes datagrams discarded because the destination
+address was not a local address [ipInAddrErrors].
+.IP iukwnpr/s
+The number of locally-addressed datagrams received
+successfully but discarded per second because of an unknown or
+unsupported protocol [ipInUnknownProtos].
+.IP idisc/s
+The number of input IP datagrams per second for which no problems were
+encountered to prevent their continued processing, but which
+were discarded (e.g., for lack of buffer space) [ipInDiscards].
+Note that this counter does not include any datagrams discarded while
+awaiting re-assembly.
+.IP odisc/s
+The number of output IP datagrams per second for which no problem was
+encountered to prevent their transmission to their
+destination, but which were discarded (e.g., for lack of
+buffer space) [ipOutDiscards].
+Note that this counter would include
+datagrams counted in fwddgm/s if any such packets met
+this (discretionary) discard criterion.
+.IP onort/s
+The number of IP datagrams discarded per second because no route could
+be found to transmit them to their destination [ipOutNoRoutes].
+Note that this counter includes any packets counted in fwddgm/s
+which meet this 'no-route' criterion.
+Note that this includes any datagrams which a host cannot route because all
+of its default routers are down.
+.IP asmf/s
+The number of failures detected per second by the IP re-assembly
+algorithm (for whatever reason: timed out, errors, etc) [ipReasmFails].
+Note that this is not necessarily a count of discarded IP
+fragments since some algorithms can lose track of the number of
+fragments by combining them as they are received.
+.IP fragf/s
+The number of IP datagrams that have been discarded per second because
+they needed to be fragmented at this entity but could not
+be, e.g., because their Don't Fragment flag was set [ipFragFails].
+.RE
+
+.IP
+.RB "With the " "IP6"
+keyword, statistics about IPv6 network traffic are reported.
+Note that IPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP irec6/s
+The total number of input datagrams received from
+interfaces per second, including those received in error
+[ipv6IfStatsInReceives].
+.IP fwddgm6/s
+The number of output datagrams per second which this
+entity received and forwarded to their final
+destinations [ipv6IfStatsOutForwDatagrams].
+.IP idel6/s
+The total number of datagrams successfully
+delivered per second to IPv6 user-protocols (including ICMP)
+[ipv6IfStatsInDelivers].
+.IP orq6/s
+The total number of IPv6 datagrams which local IPv6
+user-protocols (including ICMP) supplied per second to IPv6 in
+requests for transmission [ipv6IfStatsOutRequests].
+Note that this counter
+does not include any datagrams counted in fwddgm6/s.
+.IP asmrq6/s
+The number of IPv6 fragments received per second which needed
+to be reassembled at this interface [ipv6IfStatsReasmReqds].
+.IP asmok6/s
+The number of IPv6 datagrams successfully
+reassembled per second [ipv6IfStatsReasmOKs].
+.IP imcpck6/s
+The number of multicast packets received per second
+by the interface [ipv6IfStatsInMcastPkts].
+.IP omcpck6/s
+The number of multicast packets transmitted per second
+by the interface [ipv6IfStatsOutMcastPkts].
+.IP fragok6/s
+The number of IPv6 datagrams that have been
+successfully fragmented at this output interface per second
+[ipv6IfStatsOutFragOKs].
+.IP fragcr6/s
+The number of output datagram fragments that have
+been generated per second as a result of fragmentation at
+this output interface [ipv6IfStatsOutFragCreates].
+.RE
+
+.IP
+.RB "With the " "EIP6"
+keyword, statistics about IPv6 network errors are reported.
+Note that IPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP ihdrer6/s
+The number of input datagrams discarded per second due to
+errors in their IPv6 headers, including version
+number mismatch, other format errors, hop count
+exceeded, errors discovered in processing their
+IPv6 options, etc. [ipv6IfStatsInHdrErrors]
+.IP iadrer6/s
+The number of input datagrams discarded per second because
+the IPv6 address in their IPv6 header's destination
+field was not a valid address to be received at
+this entity. This count includes invalid
+addresses (e.g., ::0) and unsupported addresses
+(e.g., addresses with unallocated prefixes). For
+entities which are not IPv6 routers and therefore
+do not forward datagrams, this counter includes
+datagrams discarded because the destination address
+was not a local address [ipv6IfStatsInAddrErrors].
+.IP iukwnp6/s
+The number of locally-addressed datagrams
+received successfully but discarded per second because of an
+unknown or unsupported protocol [ipv6IfStatsInUnknownProtos].
+.IP i2big6/s
+The number of input datagrams that could not be
+forwarded per second because their size exceeded the link MTU
+of outgoing interface [ipv6IfStatsInTooBigErrors].
+.IP idisc6/s
+The number of input IPv6 datagrams per second for which no
+problems were encountered to prevent their
+continued processing, but which were discarded
+(e.g., for lack of buffer space)
+[ipv6IfStatsInDiscards]. Note that this
+counter does not include any datagrams discarded
+while awaiting re-assembly.
+.IP odisc6/s
+The number of output IPv6 datagrams per second for which no
+problem was encountered to prevent their
+transmission to their destination, but which were
+discarded (e.g., for lack of buffer space)
+[ipv6IfStatsOutDiscards]. Note
+that this counter would include datagrams counted
+in fwddgm6/s if any such packets
+met this (discretionary) discard criterion.
+.IP inort6/s
+The number of input datagrams discarded per second because no
+route could be found to transmit them to their
+destination [ipv6IfStatsInNoRoutes].
+.IP onort6/s
+The number of locally generated IP datagrams discarded per second
+because no route could be found to transmit them to their
+destination [unknown formal SNMP name].
+.IP asmf6/s
+The number of failures detected per second by the IPv6
+re-assembly algorithm (for whatever reason: timed
+out, errors, etc.) [ipv6IfStatsReasmFails].
+Note that this is not necessarily a count of discarded
+IPv6 fragments since some algorithms
+can lose track of the number of fragments
+by combining them as they are received.
+.IP fragf6/s
+The number of IPv6 datagrams that have been
+discarded per second because they needed to be fragmented
+at this output interface but could not be
+[ipv6IfStatsOutFragFails].
+.IP itrpck6/s
+The number of input datagrams discarded per second because
+datagram frame didn't carry enough data
+[ipv6IfStatsInTruncatedPkts].
+.RE
+
+.IP
+.RB "With the " "NFS"
+keyword, statistics about NFS client activity are reported.
+The following values are displayed:
+.RS
+.IP call/s
+Number of RPC requests made per second.
+.IP retrans/s
+Number of RPC requests per second, those which needed to be retransmitted
+(for example because of a server timeout).
+.IP read/s
+Number of 'read' RPC calls made per second.
+.IP write/s
+Number of 'write' RPC calls made per second.
+.IP access/s
+Number of 'access' RPC calls made per second.
+.IP getatt/s
+Number of 'getattr' RPC calls made per second.
+.RE
+
+.IP
+.RB "With the " "NFSD"
+keyword, statistics about NFS server activity are reported.
+The following values are displayed:
+.RS
+.IP scall/s
+Number of RPC requests received per second.
+.IP badcall/s
+Number of bad RPC requests received per second, those whose
+processing generated an error.
+.IP packet/s
+Number of network packets received per second.
+.IP udp/s
+Number of UDP packets received per second.
+.IP tcp/s
+Number of TCP packets received per second.
+.IP hit/s
+Number of reply cache hits per second.
+.IP miss/s
+Number of reply cache misses per second.
+.IP sread/s
+Number of 'read' RPC calls received per second.
+.IP swrite/s
+Number of 'write' RPC calls received per second.
+.IP saccess/s
+Number of 'access' RPC calls received per second.
+.IP sgetatt/s
+Number of 'getattr' RPC calls received per second.
+.RE
+
+.IP
+.RB "With the " "SOCK"
+keyword, statistics on sockets in use are reported (IPv4).
+The following values are displayed:
+.RS
+.IP totsck
+Total number of sockets used by the system.
+.IP tcpsck
+Number of TCP sockets currently in use.
+.IP udpsck
+Number of UDP sockets currently in use.
+.IP rawsck
+Number of RAW sockets currently in use.
+.IP ip-frag
+Number of IP fragments currently in queue.
+.IP tcp-tw
+Number of TCP sockets in TIME_WAIT state.
+.RE
+
+.IP
+.RB "With the " "SOCK6"
+keyword, statistics on sockets in use are reported (IPv6).
+Note that IPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed:
+.RS
+.IP tcp6sck
+Number of TCPv6 sockets currently in use.
+.IP udp6sck
+Number of UDPv6 sockets currently in use.
+.IP raw6sck
+Number of RAWv6 sockets currently in use.
+.IP ip6-frag
+Number of IPv6 fragments currently in use.
+.RE
+
+.IP
+.RB "With the " "SOFT"
+keyword, statistics about software-based network processing are reported.
+The following values are displayed:
+.RS
+.IP total/s
+The total number of network frames processed per second.
+.IP dropd/s
+The total number of network frames dropped per second because there
+was no room on the processing queue.
+.IP squeezd/s
+The number of times the softirq handler function terminated per second
+because its budget was consumed or the time limit was reached, but more
+work could have been done.
+.IP rx_rps/s
+The number of times the CPU has been woken up per second
+to process packets via an inter-processor interrupt.
+.IP flw_lim/s
+The number of times the flow limit has been reached per second.
+Flow limiting is an optional RPS feature that can be used to limit the number of
+packets queued to the backlog for each flow to a certain amount.
+This can help ensure that smaller flows are processed even though
+much larger flows are pushing packets in.
+.IP blg_len
+The length of the network backlog.
+.RE
+
+.IP
+.RB "With the " "TCP"
+keyword, statistics about TCPv4 network traffic are reported.
+Note that TCPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP active/s
+The number of times TCP connections have made a direct
+transition to the SYN-SENT state from the CLOSED state per second [tcpActiveOpens].
+.IP passive/s
+The number of times TCP connections have made a direct
+transition to the SYN-RCVD state from the LISTEN state per second [tcpPassiveOpens].
+.IP iseg/s
+The total number of segments received per second, including those
+received in error [tcpInSegs].  This count includes segments received on
+currently established connections.
+.IP oseg/s
+The total number of segments sent per second, including those on
+current connections but excluding those containing only
+retransmitted octets [tcpOutSegs].
+.RE
+
+.IP
+.RB "With the " "ETCP"
+keyword, statistics about TCPv4 network errors are reported.
+Note that TCPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP atmptf/s
+The number of times per second TCP connections have made a direct
+transition to the CLOSED state from either the SYN-SENT
+state or the SYN-RCVD state, plus the number of times per second TCP
+connections have made a direct transition to the LISTEN
+state from the SYN-RCVD state [tcpAttemptFails].
+.IP estres/s
+The number of times per second TCP connections have made a direct
+transition to the CLOSED state from either the ESTABLISHED
+state or the CLOSE-WAIT state [tcpEstabResets].
+.IP retrans/s
+The total number of segments retransmitted per second - that is, the
+number of TCP segments transmitted containing one or more
+previously transmitted octets [tcpRetransSegs].
+.IP isegerr/s
+The total number of segments received in error (e.g., bad
+TCP checksums) per second [tcpInErrs].
+.IP orsts/s
+The number of TCP segments sent per second containing the RST flag [tcpOutRsts].
+.RE
+
+.IP
+.RB "With the " "UDP"
+keyword, statistics about UDPv4 network traffic are reported.
+Note that UDPv4 statistics depend on
+.BR "sadc" "'s option " "-S SNMP"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP idgm/s
+The total number of UDP datagrams delivered per second to UDP users [udpInDatagrams].
+.IP odgm/s
+The total number of UDP datagrams sent per second from this entity [udpOutDatagrams].
+.IP noport/s
+The total number of received UDP datagrams per second for which there
+was no application at the destination port [udpNoPorts].
+.IP idgmerr/s
+The number of received UDP datagrams per second that could not be
+delivered for reasons other than the lack of an application
+at the destination port [udpInErrors].
+.RE
+
+.IP
+.RB "With the " "UDP6"
+keyword, statistics about UDPv6 network traffic are reported.
+Note that UDPv6 statistics depend on
+.BR "sadc" "'s option " "-S IPV6"
+to be collected.
+The following values are displayed (formal SNMP names between
+square brackets):
+.RS
+.IP idgm6/s
+The total number of UDP datagrams delivered per second to UDP users
+[udpInDatagrams].
+.IP odgm6/s
+The total number of UDP datagrams sent per second from this
+entity [udpOutDatagrams].
+.IP noport6/s
+The total number of received UDP datagrams per second for which there
+was no application at the destination port [udpNoPorts].
+.IP idgmer6/s
+The number of received UDP datagrams per second that could not be
+delivered for reasons other than the lack of an application
+at the destination port [udpInErrors].
+.RE
+
+.IP
+.RB "The " "ALL"
+keyword is equivalent to specifying all the keywords above and therefore all the network
+activities are reported.
+.TP
+.BI "-o [ " "filename " "]"
+Save the readings in the file in binary form. Each reading
+is in a separate record. The default value of the
+.I filename
+parameter is the current standard system activity daily data file. If
+.I filename
+is a directory instead of a plain file then it is considered as the directory
+where the standard system activity daily data files are located. Option
+.BR "-o " "is exclusive of option " "-f" "."
+All the data available from the kernel are saved in the file (in fact,
+.BR "sar " "calls its data collector " "sadc " "with the option " "-S ALL" "."
+.RB "See " "sadc" "(8) manual page)."
+.TP
+.BI "-P { " "cpu_list " "| ALL }"
+Report per-processor statistics for the specified processor or processors.
+.I cpu_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0,2,4-7,12-" ")."
+Note that processor 0 is the first processor, and processor
+.B all
+is the global average among all processors.
+Specifying the
+.B ALL
+keyword reports statistics for each individual processor, and globally for
+all processors. Offline processors are not displayed.
+.TP
+.BR "-p" ", " "--pretty"
+Make reports easier to read by a human.
+This option may be especially useful when displaying e.g., network interfaces
+or block devices statistics.
+.TP
+.BI "-q [ " "keyword" "[,...] | ALL ]"
+Report system load and pressure-stall statistics.
+
+Possible keywords are
+.BR "CPU" ", " "IO" ", " "LOAD" ", " "MEM " "and " "PSI" "."
+
+.RB "With the " "CPU"
+keyword, CPU pressure statistics are reported.
+The following values are displayed:
+.RS
+.IP %scpu-10
+Percentage of the time that at least some runnable tasks were delayed because the CPU
+was unavailable to them, over the last 10 second window.
+.IP %scpu-60
+Percentage of the time that at least some runnable tasks were delayed because the CPU
+was unavailable to them, over the last 60 second window.
+.IP %scpu-300
+Percentage of the time that at least some runnable tasks were delayed because the CPU
+was unavailable to them, over the last 300 second window.
+.IP %scpu
+Percentage of the time that at least some runnable tasks were delayed because the CPU
+was unavailable to them, over the last time interval.
+.RE
+
+.IP
+.RB "With the " "IO"
+keyword, I/O pressure statistics are reported.
+The following values are displayed:
+.RS
+.IP %sio-10
+Percentage of the time that at least some tasks lost waiting for I/O,
+over the last 10 second window.
+.IP %sio-60
+Percentage of the time that at least some tasks lost waiting for I/O,
+over the last 60 second window.
+.IP %sio-300
+Percentage of the time that at least some tasks lost waiting for I/O,
+over the last 300 second window.
+.IP %sio
+Percentage of the time that at least some tasks lost waiting for I/O,
+over the last time interval.
+.IP %fio-10
+Percentage of the time during which all non-idle tasks were stalled
+waiting for I/O, over the last 10 second window.
+.IP %fio-60
+Percentage of the time during which all non-idle tasks were stalled
+waiting for I/O, over the last 60 second window.
+.IP %fio-300
+Percentage of the time during which all non-idle tasks were stalled
+waiting for I/O, over the last 300 second window.
+.IP %fio
+Percentage of the time during which all non-idle tasks were stalled
+waiting for I/O, over the last time interval.
+.RE
+
+.IP
+.RB "With the " "LOAD"
+keyword, queue length and load averages statistics are reported.
+The following values are displayed:
+.RS
+.IP runq-sz
+Run queue length (number of tasks running or waiting for run time).
+.IP plist-sz
+Number of tasks in the task list.
+.IP ldavg-1
+System load average for the last minute.
+The load average is calculated as the average number of runnable or
+running tasks (R state), and the number of tasks in uninterruptible
+sleep (D state) over the specified interval.
+.IP ldavg-5
+System load average for the past 5 minutes.
+.IP ldavg-15
+System load average for the past 15 minutes.
+.IP blocked
+Number of tasks currently blocked, waiting for I/O to complete.
+.RE
+
+.IP
+.RB "With the " "MEM"
+keyword, memory pressure statistics are reported.
+The following values are displayed:
+.RS
+.IP %smem-10
+Percentage of the time during which at least some tasks were waiting
+for memory resources, over the last 10 second window.
+.IP %smem-60
+Percentage of the time during which at least some tasks were waiting
+for memory resources, over the last 60 second window.
+.IP %smem-300
+Percentage of the time during which at least some tasks were waiting
+for memory resources, over the last 300 second window.
+.IP %smem
+Percentage of the time during which at least some tasks were waiting
+for memory resources, over the last time interval.
+.IP %fmem-10
+Percentage of the time during which all non-idle tasks were stalled
+waiting for memory resources, over the last 10 second window.
+.IP %fmem-60
+Percentage of the time during which all non-idle tasks were stalled
+waiting for memory resources, over the last 60 second window.
+.IP %fmem-300
+Percentage of the time during which all non-idle tasks were stalled
+waiting for memory resources, over the last 300 second window.
+.IP %fmem
+Percentage of the time during which all non-idle tasks were stalled
+waiting for memory resources, over the last time interval.
+.RE
+
+.IP
+.RB "The " "PSI"
+keyword is equivalent to specifying CPU, IO and MEM keywords together
+and therefore all the pressure-stall statistics are reported.
+
+.RB "The " "ALL"
+keyword is equivalent to specifying all the keywords above
+and therefore all the statistics are reported.
+.TP
+.B -r [ ALL ]
+Report memory utilization statistics. The
+.B ALL
+keyword indicates that all the memory fields should be displayed.
+The following values may be displayed:
+.RS
+.IP kbmemfree
+Amount of free memory available in kilobytes.
+.IP kbavail
+Estimate of how much memory in kilobytes is available for starting new
+applications, without swapping.
+The estimate takes into account that the system needs some page cache to
+function well, and that not all reclaimable slab will be reclaimable,
+due to items being in use. The impact of those factors will vary from
+system to system.
+.IP kbmemused
+Amount of used memory in kilobytes (calculated as total installed memory -
+kbmemfree - kbbuffers - kbcached - kbslab).
+.IP %memused
+Percentage of used memory.
+.IP kbbuffers
+Amount of memory used as buffers by the kernel in kilobytes.
+.IP kbcached
+Amount of memory used to cache data by the kernel in kilobytes.
+.IP kbcommit
+Amount of memory in kilobytes needed for current workload.
+This is an estimate of how much
+RAM/swap is needed to guarantee that there never is out of memory.
+.IP %commit
+Percentage of memory needed for current workload in relation to the
+total amount of memory (RAM+swap). This number may be greater
+than 100% because the kernel usually overcommits memory.
+.IP kbactive
+Amount of active memory in kilobytes (memory that has been used more recently
+and usually not reclaimed unless absolutely necessary).
+.IP kbinact
+Amount of inactive memory in kilobytes (memory which has been less recently
+used. It is more eligible to be reclaimed for other purposes).
+.IP kbdirty
+Amount of memory in kilobytes waiting to get written back to the disk.
+.IP kbanonpg
+Amount of non-file backed pages in kilobytes mapped into userspace page tables.
+.IP kbslab
+Amount of memory in kilobytes used by the kernel to cache data structures
+for its own use.
+.IP kbkstack
+Amount of memory in kilobytes used for kernel stack space.
+.IP kbpgtbl
+Amount of memory in kilobytes dedicated to the lowest level of page tables.
+.IP kbvmused
+Amount of memory in kilobytes of used virtual address space.
+.RE
+.TP
+.B -S
+Report swap space utilization statistics.
+The following values are displayed:
+.RS
+.IP kbswpfree
+Amount of free swap space in kilobytes.
+.IP kbswpused
+Amount of used swap space in kilobytes.
+.IP %swpused
+Percentage of used swap space.
+.IP kbswpcad
+Amount of cached swap memory in kilobytes.
+This is memory that once was swapped out, is swapped back in but still also
+is in the swap area (if memory is needed it doesn't need to be swapped out
+again because it is already in the swap area. This saves I/O).
+.IP %swpcad
+Percentage of cached swap memory in relation to the amount of used swap space.
+.RE
+.PP
+.BI "-s [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "-s [ " "seconds_since_the_epoch " "]"
+.RS
+Set the starting time of the data, causing the
+.B sar
+command to extract records time-tagged at, or following, the time
+specified. The default starting time is 08:00:00.
+Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number). This option can be
+used only when data are read from a file (option
+.BR "-f" ")."
+.RE
+.TP
+.B --sadc
+Indicate which data collector is called by
+.BR "sar" "."
+If the data collector is sought in
+.B PATH
+then enter "which sadc" to know where it is located.
+.TP
+.B -t
+When reading data from a daily data file, indicate that
+.B sar
+should display the timestamps in the original local time of
+the data file creator. Without this option, the
+.B sar
+command displays the timestamps in the user's local time.
+.TP
+.B -u [ ALL ]
+Report CPU utilization. The
+.B ALL
+keyword indicates that all the CPU fields should be displayed.
+The report may show the following fields:
+.RS
+.IP %user
+Percentage of CPU utilization that occurred while executing at the user
+level (application). Note that this field includes time spent running
+virtual processors.
+.IP %usr
+Percentage of CPU utilization that occurred while executing at the user
+level (application). Note that this field does NOT include time spent
+running virtual processors.
+.IP %nice
+Percentage of CPU utilization that occurred while executing at the user
+level with nice priority.
+.IP %system
+Percentage of CPU utilization that occurred while executing at the system
+level (kernel). Note that this field includes time spent servicing
+hardware and software interrupts.
+.IP %sys
+Percentage of CPU utilization that occurred while executing at the system
+level (kernel). Note that this field does NOT include time spent servicing
+hardware or software interrupts.
+.IP %iowait
+Percentage of time that the CPU or CPUs were idle during which
+the system had an outstanding disk I/O request.
+.IP %steal
+Percentage of time spent in involuntary wait by the virtual CPU
+or CPUs while the hypervisor was servicing another virtual processor.
+.IP %irq
+Percentage of time spent by the CPU or CPUs to service hardware interrupts.
+.IP %soft
+Percentage of time spent by the CPU or CPUs to service software interrupts.
+.IP %guest
+Percentage of time spent by the CPU or CPUs to run a virtual processor.
+.IP %gnice
+Percentage of time spent by the CPU or CPUs to run a niced guest.
+.IP %idle
+Percentage of time that the CPU or CPUs were idle and the system
+did not have an outstanding disk I/O request.
+.RE
+.TP
+.B -V
+Print version number then exit.
+.TP
+.B -v
+Report status of inode, file and other kernel tables.
+The following values are displayed:
+.RS
+.IP dentunusd
+Number of unused cache entries in the directory cache.
+.IP file-nr
+Number of file handles used by the system.
+.IP inode-nr
+Number of inode handlers used by the system.
+.IP pty-nr
+Number of pseudo-terminals used by the system.
+.RE
+.TP
+.B -W
+Report swapping statistics. The following values are displayed:
+.RS
+.IP pswpin/s
+Total number of swap pages the system brought in per second.
+.IP pswpout/s
+Total number of swap pages the system brought out per second.
+.RE
+.TP
+.B -w
+Report task creation and system switching activity.
+The following values are displayed:
+.RS
+.IP proc/s
+Total number of tasks created per second.
+.IP cswch/s
+Total number of context switches per second.
+.RE
+.TP
+.B -x
+Extended reports: Display minimum and maximum values in addition to
+average ones at the end of the report.
+.TP
+.B -y
+Report TTY devices activity. The following values are displayed:
+.RS
+.IP rcvin/s
+Number of receive interrupts per second for current serial line.
+Serial line number is given in the TTY column.
+.IP xmtin/s
+Number of transmit interrupts per second for current serial line.
+.IP framerr/s
+Number of frame errors per second for current serial line.
+.IP prtyerr/s
+Number of parity errors per second for current serial line.
+.IP brk/s
+Number of breaks per second for current serial line.
+.IP ovrun/s
+Number of overrun errors per second for current serial line.
+.RE
+.TP
+.B -z
+.RB "Tell " "sar"
+to omit output for any devices for which there was no activity during the
+sample period.
+
+.SH ENVIRONMENT
+The
+.B sar
+command takes into account the following environment variables:
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.IR "never" ", " "always " "or " "auto"
+(the latter is equivalent to the default settings).
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "C=33;22:I=32;22:N=34;1:R=31;22:W=35;1:X=31;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B C=
+SGR (Select Graphic Rendition) substring for comments inserted in the binary daily
+data files.
+.TP
+.B I=
+SGR substring for item names or values (eg. network interfaces, CPU number...)
+.TP
+.B N=
+SGR substring for non-zero statistics values.
+.TP
+.B R=
+SGR substring for restart messages.
+.TP
+.BR "W=" " (or " "M=" ")"
+SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25%
+depending on the metric's meaning).
+It is also used for negative values in the range from -10 to -5.
+.TP
+.BR "X=" " (or " "H=" ")"
+SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10%
+depending on the metric's meaning).
+It is also used for negative values lower than or equal to -10.
+.TP
+.B Z=
+SGR substring for zero values.
+.RE
+.TP
+.B S_REPEAT_HEADER
+This variable contains the maximum number of lines after which a header has to be
+displayed by
+.B sar
+when the output is not a terminal.
+.TP
+.B S_TIME_DEF_TIME
+If this variable exists and its value is
+.BR "UTC " "then " "sar"
+will save its data in UTC time (data will still be displayed in local time).
+.B sar
+will also use UTC time instead of local time to determine the current daily
+data file located in the
+.I /var/log/sa
+directory. This variable may be useful for servers with users located across
+several timezones.
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.B ISO
+then the current locale will be ignored when printing the date in the report header.
+.RB "The " "sar"
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+The timestamp will also be compliant with ISO 8601 format.
+
+.SH EXAMPLES
+.TP
+.B sar -u 2 5
+Report CPU utilization for each 2 seconds. 5 lines are displayed.
+.TP
+.B sar -I --int=14 -o int14.file 2 10
+Report statistics on IRQ 14 for each 2 seconds. 10 lines are displayed.
+Data are stored in a file called
+.IR "int14.file" "."
+.TP
+.B sar -r -n DEV -f /var/log/sa/sa16
+.RI "Display memory and network statistics saved in daily data file " "sa16" "."
+.TP
+.B sar -A
+Display all the statistics saved in current daily data file.
+
+.SH BUGS
+.IR "/proc " "filesystem must be mounted for the
+.BR "sar " "command to work."
+.PP
+All the statistics are not necessarily available, depending on the kernel version used.
+.B sar
+assumes that you are using at least a 2.6 kernel.
+.PP
+.RB "Although " "sar"
+speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
+A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
+
+.SH FILES
+.I /var/log/sa/saDD
+.br
+.I /var/log/sa/saYYYYMMDD
+.RS
+The standard system activity daily data files and their default location.
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day.
+.RE
+
+.IR "/proc " "and " "/sys " "contain various files with system statistics."
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sadc" "(8), " "sa1" "(8), " "sa2" "(8), " "sadf" "(1), " "sysstat" "(5), " "pidstat" "(1),"
+.BR "mpstat" "(1), " "iostat" "(1), " "vmstat" "(8)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/sbigtopgm.1 b/upstream/mageia-cauldron/man1/sbigtopgm.1
new file mode 100644
index 00000000..51f3d25e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sbigtopgm.1
@@ -0,0 +1,73 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sbigtopgm User Manual" 0 "18 January 2015" "netpbm documentation"
+
+.SH NAME
+
+sbigtopgm - convert an SBIG CCDOPS file to PGM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsbigtopgm\fP
+
+[\fIsbigfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsbigtopgm\fP reads an image file in the native format used
+by the Santa Barbara Instrument Group (SBIG) astronomical CCD cameras,
+and produces a PGM image as output.  Additional information on SBIG
+cameras and documentation of the file format is available at the Web
+site, 
+.UR http://www.sbig.com/
+http://www.sbig.com/
+.UE
+\&.
+.PP
+\fBsbigtopgm\fP recognizes some variation on the documented SBIG Type 3
+format.  It allows any capitalization in the header.  It ignores all
+whitespace in the header except newlines.  So a header line can end in
+newline, CRLF, or the bizarre LF-CR actually required by the spec.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBsbigtopgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtosbig" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+John Walker (\fB
+.UR http://www.fourmilab.ch/
+http://www.fourmilab.ch/
+.UE
+\&\fP),
+January 1998.  This program is in the public domain.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sbigtopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/scanimage.1 b/upstream/mageia-cauldron/man1/scanimage.1
new file mode 100644
index 00000000..32319e34
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/scanimage.1
@@ -0,0 +1,524 @@
+.TH scanimage 1 "10 Jul 2008" "" "SANE Scanner Access Now Easy"
+.IX scanimage
+.SH NAME
+scanimage \- scan an image
+.SH SYNOPSIS
+.B scanimage
+.RB [ \-d | \-\-device\-name
+.IR dev ]
+.RB [ \-\-format
+.IR format ]
+.RB [ \-i | \-\-icc\-profile
+.IR profile ]
+.RB [ \-L | \-\-list\-devices ]
+.RB [ \-f | \-\-formatted\-device\-list
+.IR format ]
+.RB [ \-b | \-\-batch
+.RI [ format ]]
+.RB [ \-\-batch\-start
+.IR start ]
+.RB [ \-\-batch\-count
+.IR count ]
+.RB [ \-\-batch\-increment
+.IR increment ]
+.RB [ \-\-batch\-double ]
+.RB [ \-\-accept\-md5\-only ]
+.RB [ \-p | \-\-progress ]
+.RB [ \-o | \-\-output-file
+.IR path ]
+.RB [ \-n | \-\-dont\-scan ]
+.RB [ \-T | \-\-test ]
+.RB [ \-A | \-\-all-options ]
+.RB [ \-h | \-\-help ]
+.RB [ \-v | \-\-verbose ]
+.RB [ \-B | \-\-buffer-size
+.RI [= size ]]
+.RB [ \-V | \-\-version ]
+.RI [ device\-specific\-options ]
+.SH DESCRIPTION
+.B scanimage
+is a command-line interface to control image acquisition devices such
+as flatbed scanners or cameras.  The device is controlled via
+command-line options.  After command-line processing,
+.B scanimage
+normally proceeds to acquire an image.  The image data is written to
+standard output in one of the PNM (portable aNyMaP) formats (PBM for
+black-and-white images, PGM for grayscale images, and PPM for color
+images), TIFF format (black-and-white, grayscale or color), PNG format,
+or JPEG format (compression level 75).
+.B scanimage
+accesses image acquisition devices through the
+.B SANE
+(Scanner Access Now Easy) interface and can thus support any device for which
+there exists a
+.B SANE
+backend (try
+.B apropos
+.I sane\-
+to get a list of available backends).
+
+.SH EXAMPLES
+To get a list of devices:
+
+  scanimage \-L
+
+To scan with default settings to the file image.pnm:
+
+  scanimage >image.pnm
+
+To scan 100x100 mm to the file image.tiff (\-x and \-y may not be available with
+all devices):
+
+  scanimage \-x 100 \-y 100 \-\-format=tiff >image.tiff
+
+To print all available options:
+
+  scanimage \-h
+
+.SH OPTIONS
+There are two sets of options available when running
+.BR scanimage .
+.PP
+The options that are provided by
+.B scanimage
+itself are listed below. In addition, each backend offers its own set of options and these
+can also be specified. Note that the options available from the backend may vary depending on the
+scanning device that is selected.
+.PP
+Often options that are similar in function may be implemented
+differently across backends. An example of this difference is
+.I \-\-mode Gray
+and
+.IR "\-\-mode Grayscale" .
+This may be due to differing backend author preferences.
+At other times, options are defined by the scanning device itself and therefore out of the
+control of the backend code.
+
+.PP
+Parameters are separated by a blank from single-character options (e.g.
+.BI "\-d " epson )
+and by a "=" from multi-character options (e.g.
+.BR \-\-device\-name =\fIepson\FR ).
+
+.TP
+.BR \-d "\fI dev\fR, " \-\-device\-name =\fIdev\fR
+specifies the device to access and must be followed by a SANE device-name like
+.RI ` epson:/dev/sg0 '
+or
+.RI ` hp:/dev/usbscanner0 '.
+A (partial) list of available devices can be obtained with the
+.B \-\-list\-devices
+option (see below).  If no device-name is specified explicitly,
+.B scanimage
+reads a device-name from the environment variable
+.BR SANE_DEFAULT_DEVICE .
+If this variable is not set,
+.B scanimage
+will attempt to open the first available device.
+
+.TP
+.BR \-\-format =\fIformat\fR
+selects how image data is written to standard output or the file specified by
+the
+.B \-\-output\-file
+option.
+.I format
+can be
+.BR pnm ,
+.BR tiff ,
+.BR png ,
+or
+.BR jpeg .
+If
+.B \-\-format
+is not specified, PNM is written by default.
+
+.TP
+.BR \-i "\fI profile\fR, " \-\-icc\-profile =\fIprofile\fR
+is used to include an ICC profile into a TIFF file.
+
+.TP
+.BR \-L ", " \-\-list\-devices
+requests a (partial) list of devices that are available.  The
+list may not be complete since some devices may be available, but are not
+listed in any of the configuration files (which are typically stored
+in directory
+.IR /etc/sane.d ).
+This is particularly the case when accessing scanners through the network.  If
+a device is not listed in a configuration file, the only way to access it is
+by its full device name.  You may need to consult your system administrator to
+find out the names of such devices.
+
+.TP
+.BR \-f "\fI format\fR, " \-\-formatted\-device\-list =\fIformat\fR
+works similar to
+.BR \-\-list\-devices ,
+but requires a format string.
+.B scanimage
+replaces the placeholders
+.B %d %v %m %t %i %n
+with the device name, vendor name, model name, scanner type, an index
+number and newline respectively. The command
+.LP
+.RS
+.B scanimage \-f
+.I \*(lq scanner number %i device %d is a %t, model %m, produced by %v \*(rq
+.LP
+
+will produce something like:
+.PP
+.RS
+scanner number 0  device sharp:/dev/sg1 is  a  flatbed scanner, model JX250
+SCSI, produced by SHARP
+.RE
+.RE
+
+.PP
+The
+.B \-\-batch*
+options provide features for scanning documents using document
+feeders.
+
+.RS
+
+.TP
+.BR \-b " [\fIformat\fR], " \-\-batch =[\fIformat\fR]
+is used to specify the format of the filename that each page will be written
+to.  Each page is written out to a single file.  If
+.I format
+is not specified, the default of
+.I out%d.pnm
+(or
+.I out%d.tif
+for
+.BR "\-\-format tiff" ,
+.I out%d.png
+for
+.B "\-\-format png"
+or
+.I out%d.jpg
+for
+.BR "\-\-format jpeg" )
+will be used.
+This option is incompatible with the
+.B \-\-output\-path
+option.
+.I format
+is given as a printf style string with one integer parameter.
+
+
+.TP
+.BR \-\-batch\-start =\fIstart\fR
+selects the page number to start naming files with. If this option is not
+given, the counter will start at 1.
+
+.TP
+.BR \-\-batch\-count =\fIcount\fR
+specifies the number of pages to attempt to scan.  If not given,
+.B scanimage
+will continue scanning until the scanner returns a state
+other than OK.  Not all scanners with document feeders signal when the
+ADF is empty. Use this option to work around them.
+
+.TP
+.BR \-\-batch\-increment =\fIincrement\fR
+sets the amount that the number in the filename is incremented
+by.  Generally this is used when you are scanning double-sided documents
+on a single-sided document feeder.
+.B \-\-batch\-double
+is a specific command provided to aid this.
+
+.TP
+.B \-\-batch\-double
+will automatically set the increment to 2.
+Equivalent to
+.BR \-\-batch\-increment =2
+
+.TP
+.B \-\-batch\-prompt
+will ask for pressing RETURN before scanning a page. This can be used for
+scanning multiple pages without an automatic document feeder.
+.RE
+
+.TP
+.B \-\-accept\-md5\-only
+only accepts user authorization requests that support MD5 security. The
+.B SANE
+network daemon
+.BR saned (8)
+is capable of doing such requests.
+
+.TP
+.BR \-p ", " \-\-progress
+requests that
+.B scanimage
+prints a progress counter. It shows how much image data of the current image has
+already been received (in percent).
+
+.TP
+.BR \-o "\fI path\fR, " \-\-output\-file =\fIpath\fR
+requests that
+.B scanimage
+saves the scanning output to the given
+.IR path .
+This option is incompatible with the
+.B \-\-batch
+option. The program will try to guess
+.B \-\-format
+from the file name. If that is not possible, it will print an error message and exit.
+
+.TP
+.BR \-n ", " \-\-dont\-scan
+requests that
+.B scanimage
+only sets the options provided by the user but doesn't actually perform a
+scan. This option can be used to e.g. turn off the scanner's lamp (if
+supported by the backend).
+
+.TP
+.BR \-T ", " \-\-test
+requests that
+.B scanimage
+performs a few simple sanity tests to make sure the backend works as
+defined by the
+.B SANE
+API. In particular the
+.BR sane_read ()
+function is exercised by this test.
+
+.TP
+.BR \-A ", " \-\-all\-options
+requests that
+.B scanimage
+lists all available options exposed by the backend, including button options.
+The information is printed on standard output and no scan will be performed.
+
+.TP
+.BR \-h ", " \-\-help
+requests help information.  The information is printed on
+standard output and no scan will be performed.
+
+.TP
+.BR \-v ", " \-\-verbose
+increases the verbosity of the output of
+.B scanimage.
+The option may be specified repeatedly, each time increasing the verbosity
+level.
+
+.TP
+.BR \-B " [\fIsize\fR], " \-\-buffer\-size =[\fIsize\fR]
+changes input buffer size from the default of 32KB to
+.I size
+KB. If
+.I size
+is not specified then the buffer is set to 1 MB.
+
+.TP
+.BR \-V ", " \-\-version
+requests that
+.B scanimage
+prints the program and package name, the version number of
+the
+.B SANE
+distribution that it came with and the version of the backend that it
+loads. If more information about the version
+numbers of the backends are necessary, the
+.B DEBUG
+variable for the dll layer can be used. Example:
+.I "SANE_DEBUG_DLL=3 scanimage \-L" .
+.PP
+As you might imagine, much of the power of
+.B scanimage
+comes from the fact that it can control any
+.B SANE
+backend.  Thus, the exact set of command-line options depends on the
+capabilities of the selected device.  To see the options for a device named
+.IR dev ,
+invoke
+.B scanimage
+via a command-line of the form:
+.PP
+.RS
+scanimage \-\-help \-\-device\-name
+.I dev
+.RE
+.PP
+The documentation for the device-specific options printed by
+.B \-\-help
+is best explained with a few examples:
+
+.B \-l 0..218mm [0]
+.RS
+Top-left x position of scan area.
+.PP
+The description above shows that option
+.B \-l
+expects an option value in the range from 0 to 218 mm.  The
+value in square brackets indicates that the current option value is 0
+mm. Most backends provide similar geometry options for top-left y position
+.RB ( \-t ),
+width
+.RB ( \-x )
+and height of scan-area
+.RB (\-y ).
+.RE
+
+
+.B \-\-brightness \-100..100% [0]
+.RS
+Controls the brightness of the acquired image.
+.PP
+The description above shows that option
+.B \-\-brightness
+expects an option value in the range from \-100 to 100 percent.  The
+value in square brackets indicates that the current option value is 0
+percent.
+.RE
+
+.B \-\-default\-enhancements
+.RS
+Set default values for enhancement controls.
+.PP
+The description above shows that option
+.B \-\-default\-enhancements
+has no option value.  It should be thought of as having an immediate
+effect at the point of the command-line at which it appears.  For
+example, since this option resets the
+.B \-\-brightness
+option, the option-pair
+.B \-\-brightness 50 \-\-default\-enhancements
+would effectively be a no-op.
+.RE
+
+.B \-\-mode Lineart|Gray|Color [Gray]
+.RS
+Selects the scan mode (e.g., lineart or color).
+.PP
+The description above shows that option
+.B \-\-mode
+accepts an argument that must be one of the strings
+.BR Lineart ,
+.BR Gray ,
+or
+.BR Color .
+The value in the square bracket indicates that the option is currently
+set to
+.BR Gray .
+For convenience, it is legal to abbreviate the string values as long as
+they remain unique.  Also, the case of the spelling doesn't matter.  For
+example, option setting
+.B \-\-mode col
+is identical to
+.BR "\-\-mode Color" .
+.RE
+
+.B \-\-custom\-gamma[=(yes|no)] [inactive]
+.RS
+Determines whether a builtin or a custom gamma-table should be used.
+.PP
+The description above shows that option
+.B \-\-custom\-gamma
+expects either no option value, a "yes" string, or a "no" string.
+Specifying the option with no value is equivalent to specifying "yes".
+The value in square-brackets indicates that the option is not
+currently active.  That is, attempting to set the option would result
+in an error message.  The set of available options typically depends
+on the settings of other options.  For example, the
+.B \-\-custom\-gamma
+table might be active only when a grayscale or color scan-mode has
+been requested.
+
+Note that the
+.B \-\-help
+option is processed only after all other options have been processed.
+This makes it possible to see the option settings for a particular
+mode by specifying the appropriate mode-options along
+with the
+.B \-\-help
+option.  For example, the command-line:
+.PP
+.B  scanimage \-\-help \-\-mode
+.I color
+.PP
+would print the option settings that are in effect when the color-mode
+is selected.
+.RE
+
+.B \-\-gamma\-table 0..255,...
+.RS
+Gamma-correction table.  In color mode this option
+equally affects the red, green, and blue channels
+simultaneously (i.e., it is an intensity gamma table).
+.PP
+The description above shows that option
+.B \-\-gamma\-table
+expects zero or more values in the range 0 to 255.  For example, a
+legal value for this option would be "3,4,5,6,7,8,9,10,11,12".  Since
+it's cumbersome to specify long vectors in this form, the same can be
+expressed by the abbreviated form "[0]3-[9]12".  What this means is
+that the first vector element is set to 3, the 9-th element is set to
+12 and the values in between are interpolated linearly.  Of course, it
+is possible to specify multiple such linear segments.  For example,
+"[0]3-[2]3-[6]7,[7]10-[9]6" is equivalent to "3,3,3,4,5,6,7,10,8,6".
+The program
+.B gamma4scanimage
+can be used to generate such gamma tables (see
+.BR gamma4scanimage (1)
+for details).
+.RE
+
+.B \-\-filename <string> [/tmp/input.ppm]
+.RS
+The filename of the image to be loaded.
+.PP
+The description above is an example of an option that takes an
+arbitrary string value (which happens to be a filename).  Again,
+the value in brackets show that the option is current set to the
+filename
+.IR /tmp/input.ppm .
+.RE
+
+.SH ENVIRONMENT
+.TP
+.B SANE_DEFAULT_DEVICE
+The default device-name.
+.SH FILES
+.TP
+.I /etc/sane.d
+This directory holds various configuration files.  For details, please
+refer to the manual pages listed below.
+.TP
+.I ~/.sane/pass
+This file contains lines of the form
+.PP
+.RS
+user:password:resource
+.PP
+.B scanimage
+uses this information to answer user authorization requests
+automatically. The file must have 0600 permissions or stricter. You should
+use this file in conjunction with the
+.B \-\-accept\-md5\-only
+option to avoid
+server-side attacks. The resource may contain any character but is limited
+to 127 characters.
+
+.SH "SEE ALSO"
+.BR sane (7),
+.BR gamma4scanimage (1),
+.BR xscanimage (1),
+.BR xcam (1) ,
+.BR xsane (1) ,
+.BR scanadf (1),
+.BR sane\-dll (5),
+.BR sane\-net (5),
+.BR sane\-"backendname" (5)
+
+.SH AUTHOR
+David Mosberger, Andreas Beck, Gordon Matzigkeit, Caskey Dickson, and many
+others.  For questions and comments contact the sane\-devel mailinglist (see
+.IR http://www.sane\-project.org/mailing\-lists.html ).
+
+.SH BUGS
+For vector options, the help output currently has no indication as to
+how many elements a vector-value should have.
diff --git a/upstream/mageia-cauldron/man1/scp.1 b/upstream/mageia-cauldron/man1/scp.1
new file mode 100644
index 00000000..cb502c2e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/scp.1
@@ -0,0 +1,332 @@
+.\"
+.\" scp.1
+.\"
+.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
+.\"
+.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
+.\"                    All rights reserved
+.\"
+.\" Created: Sun May  7 00:14:37 1995 ylo
+.\"
+.\" $OpenBSD: scp.1,v 1.112 2022/12/16 07:13:22 djm Exp $
+.\"
+.Dd $Mdocdate: December 16 2022 $
+.Dt SCP 1
+.Os
+.Sh NAME
+.Nm scp
+.Nd OpenSSH secure file copy
+.Sh SYNOPSIS
+.Nm scp
+.Op Fl 346ABCOpqRrsTv
+.Op Fl c Ar cipher
+.Op Fl D Ar sftp_server_path
+.Op Fl F Ar ssh_config
+.Op Fl i Ar identity_file
+.Op Fl J Ar destination
+.Op Fl l Ar limit
+.Op Fl o Ar ssh_option
+.Op Fl P Ar port
+.Op Fl S Ar program
+.Op Fl X Ar sftp_option
+.Ar source ... target
+.Sh DESCRIPTION
+.Nm
+copies files between hosts on a network.
+.Pp
+.Nm
+uses the SFTP protocol over a
+.Xr ssh 1
+connection for data transfer, and uses the same authentication and provides
+the same security as a login session.
+.Pp
+.Nm
+will ask for passwords or passphrases if they are needed for
+authentication.
+.Pp
+The
+.Ar source
+and
+.Ar target
+may be specified as a local pathname, a remote host with optional path
+in the form
+.Sm off
+.Oo user @ Oc host : Op path ,
+.Sm on
+or a URI in the form
+.Sm off
+.No scp:// Oo user @ Oc host Oo : port Oc Op / path .
+.Sm on
+Local file names can be made explicit using absolute or relative pathnames
+to avoid
+.Nm
+treating file names containing
+.Sq :\&
+as host specifiers.
+.Pp
+When copying between two remote hosts, if the URI format is used, a
+.Ar port
+cannot be specified on the
+.Ar target
+if the
+.Fl R
+option is used.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 3
+Copies between two remote hosts are transferred through the local host.
+Without this option the data is copied directly between the two remote
+hosts.
+Note that, when using the legacy SCP protocol (via the
+.Fl O
+flag), this option
+selects batch mode for the second host as
+.Nm
+cannot ask for passwords or passphrases for both hosts.
+This mode is the default.
+.It Fl 4
+Forces
+.Nm
+to use IPv4 addresses only.
+.It Fl 6
+Forces
+.Nm
+to use IPv6 addresses only.
+.It Fl A
+Allows forwarding of
+.Xr ssh-agent 1
+to the remote system.
+The default is not to forward an authentication agent.
+.It Fl B
+Selects batch mode (prevents asking for passwords or passphrases).
+.It Fl C
+Compression enable.
+Passes the
+.Fl C
+flag to
+.Xr ssh 1
+to enable compression.
+.It Fl c Ar cipher
+Selects the cipher to use for encrypting the data transfer.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl D Ar sftp_server_path
+Connect directly to a local SFTP server program rather than a
+remote one via
+.Xr ssh 1 .
+This option may be useful in debugging the client and server.
+.It Fl F Ar ssh_config
+Specifies an alternative
+per-user configuration file for
+.Nm ssh .
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl i Ar identity_file
+Selects the file from which the identity (private key) for public key
+authentication is read.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl J Ar destination
+Connect to the target host by first making an
+.Nm
+connection to the jump host described by
+.Ar destination
+and then establishing a TCP forwarding to the ultimate destination from
+there.
+Multiple jump hops may be specified separated by comma characters.
+This is a shortcut to specify a
+.Cm ProxyJump
+configuration directive.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl l Ar limit
+Limits the used bandwidth, specified in Kbit/s.
+.It Fl O
+Use the legacy SCP protocol for file transfers instead of the SFTP protocol.
+Forcing the use of the SCP protocol may be necessary for servers that do
+not implement SFTP, for backwards-compatibility for particular filename
+wildcard patterns and for expanding paths with a
+.Sq ~
+prefix for older SFTP servers.
+.It Fl o Ar ssh_option
+Can be used to pass options to
+.Nm ssh
+in the format used in
+.Xr ssh_config 5 .
+This is useful for specifying options
+for which there is no separate
+.Nm scp
+command-line flag.
+For full details of the options listed below, and their possible values, see
+.Xr ssh_config 5 .
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It AddressFamily
+.It BatchMode
+.It BindAddress
+.It BindInterface
+.It CanonicalDomains
+.It CanonicalizeFallbackLocal
+.It CanonicalizeHostname
+.It CanonicalizeMaxDots
+.It CanonicalizePermittedCNAMEs
+.It CASignatureAlgorithms
+.It CertificateFile
+.It CheckHostIP
+.It Ciphers
+.It Compression
+.It ConnectionAttempts
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
+.It ControlPersist
+.It GlobalKnownHostsFile
+.It GSSAPIAuthentication
+.It GSSAPIDelegateCredentials
+.It HashKnownHosts
+.It Host
+.It HostbasedAcceptedAlgorithms
+.It HostbasedAuthentication
+.It HostKeyAlgorithms
+.It HostKeyAlias
+.It Hostname
+.It IdentitiesOnly
+.It IdentityAgent
+.It IdentityFile
+.It IPQoS
+.It KbdInteractiveAuthentication
+.It KbdInteractiveDevices
+.It KexAlgorithms
+.It KnownHostsCommand
+.It LogLevel
+.It MACs
+.It NoHostAuthenticationForLocalhost
+.It NumberOfPasswordPrompts
+.It PasswordAuthentication
+.It PKCS11Provider
+.It Port
+.It PreferredAuthentications
+.It ProxyCommand
+.It ProxyJump
+.It PubkeyAcceptedAlgorithms
+.It PubkeyAuthentication
+.It RekeyLimit
+.It RequiredRSASize
+.It SendEnv
+.It ServerAliveInterval
+.It ServerAliveCountMax
+.It SetEnv
+.It StrictHostKeyChecking
+.It TCPKeepAlive
+.It UpdateHostKeys
+.It User
+.It UserKnownHostsFile
+.It VerifyHostKeyDNS
+.El
+.It Fl P Ar port
+Specifies the port to connect to on the remote host.
+Note that this option is written with a capital
+.Sq P ,
+because
+.Fl p
+is already reserved for preserving the times and mode bits of the file.
+.It Fl p
+Preserves modification times, access times, and file mode bits from the
+source file.
+.It Fl q
+Quiet mode: disables the progress meter as well as warning and diagnostic
+messages from
+.Xr ssh 1 .
+.It Fl R
+Copies between two remote hosts are performed by connecting to the origin
+host and executing
+.Nm
+there.
+This requires that
+.Nm
+running on the origin host can authenticate to the destination host without
+requiring a password.
+.It Fl r
+Recursively copy entire directories.
+Note that
+.Nm
+follows symbolic links encountered in the tree traversal.
+.It Fl S Ar program
+Name of
+.Ar program
+to use for the encrypted connection.
+The program must understand
+.Xr ssh 1
+options.
+.It Fl T
+Disable strict filename checking.
+By default when copying files from a remote host to a local directory
+.Nm
+checks that the received filenames match those requested on the command-line
+to prevent the remote end from sending unexpected or unwanted files.
+Because of differences in how various operating systems and shells interpret
+filename wildcards, these checks may cause wanted files to be rejected.
+This option disables these checks at the expense of fully trusting that
+the server will not send unexpected filenames.
+.It Fl v
+Verbose mode.
+Causes
+.Nm
+and
+.Xr ssh 1
+to print debugging messages about their progress.
+This is helpful in
+debugging connection, authentication, and configuration problems.
+.It Fl X Ar sftp_option
+Specify an option that controls aspects of SFTP protocol behaviour.
+The valid options are:
+.Bl -tag -width Ds
+.It Cm nrequests Ns = Ns Ar value
+Controls how many concurrent SFTP read or write requests may be in progress
+at any point in time during a download or upload.
+By default 64 requests may be active concurrently.
+.It Cm buffer Ns = Ns Ar value
+Controls the maximum buffer size for a single SFTP read/write operation used
+during download or upload.
+By default a 32KB buffer is used.
+.El
+.El
+.Pp
+Usage of SCP protocol can be blocked by creating a world-readable
+.Ar /etc/ssh/disable_scp
+file. If this file exists, when SCP protocol is in use (either remotely or 
+via the
+.Fl O
+option), the program will exit.
+.Sh EXIT STATUS
+.Ex -std scp
+.Sh SEE ALSO
+.Xr sftp 1 ,
+.Xr ssh 1 ,
+.Xr ssh-add 1 ,
+.Xr ssh-agent 1 ,
+.Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
+.Xr sftp-server 8 ,
+.Xr sshd 8
+.Sh HISTORY
+.Nm
+is based on the rcp program in
+.Bx
+source code from the Regents of the University of California.
+.Pp
+Since OpenSSH 9.0,
+.Nm
+has used the SFTP protocol for transfers by default.
+.Sh AUTHORS
+.An Timo Rinne Aq Mt tri@iki.fi
+.An Tatu Ylonen Aq Mt ylo@cs.hut.fi
+.Sh CAVEATS
+The legacy SCP protocol (selected by the
+.Fl O
+flag) requires execution of the remote user's shell to perform
+.Xr glob 3
+pattern matching.
+This requires careful quoting of any characters that have special meaning to
+the remote shell, such as quote characters.
diff --git a/upstream/mageia-cauldron/man1/sdiff.1 b/upstream/mageia-cauldron/man1/sdiff.1
new file mode 100644
index 00000000..c349f6fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sdiff.1
@@ -0,0 +1,104 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.4.
+.TH SDIFF "1" "May 2023" "diffutils 3.10" "User Commands"
+.SH NAME
+sdiff \- side-by-side merge of file differences
+.SH SYNOPSIS
+.B sdiff
+[\fIOPTION\fR]... \fIFILE1 FILE2\fR
+.SH DESCRIPTION
+Side\-by\-side merge of differences between FILE1 and FILE2.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR
+operate interactively, sending output to FILE
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+consider upper\- and lower\-case to be the same
+.TP
+\fB\-E\fR, \fB\-\-ignore\-tab\-expansion\fR
+ignore changes due to tab expansion
+.TP
+\fB\-Z\fR, \fB\-\-ignore\-trailing\-space\fR
+ignore white space at line end
+.TP
+\fB\-b\fR, \fB\-\-ignore\-space\-change\fR
+ignore changes in the amount of white space
+.TP
+\fB\-W\fR, \fB\-\-ignore\-all\-space\fR
+ignore all white space
+.TP
+\fB\-B\fR, \fB\-\-ignore\-blank\-lines\fR
+ignore changes whose lines are all blank
+.TP
+\fB\-I\fR, \fB\-\-ignore\-matching\-lines\fR=\fIRE\fR
+ignore changes all whose lines match RE
+.TP
+\fB\-\-strip\-trailing\-cr\fR
+strip trailing carriage return on input
+.TP
+\fB\-a\fR, \fB\-\-text\fR
+treat all files as text
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fINUM\fR
+output at most NUM (default 130) print columns
+.TP
+\fB\-l\fR, \fB\-\-left\-column\fR
+output only the left column of common lines
+.TP
+\fB\-s\fR, \fB\-\-suppress\-common\-lines\fR
+do not output common lines
+.TP
+\fB\-t\fR, \fB\-\-expand\-tabs\fR
+expand tabs to spaces in output
+.TP
+\fB\-\-tabsize\fR=\fINUM\fR
+tab stops at every NUM (default 8) print columns
+.TP
+\fB\-d\fR, \fB\-\-minimal\fR
+try hard to find a smaller set of changes
+.TP
+\fB\-H\fR, \fB\-\-speed\-large\-files\fR
+assume large files, many scattered small changes
+.TP
+\fB\-\-diff\-program\fR=\fIPROGRAM\fR
+use PROGRAM to compare files
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+output version information and exit
+.PP
+If a FILE is '\-', read standard input.
+Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
+.SH AUTHOR
+Written by Thomas Lord.
+.SH "REPORTING BUGS"
+Report bugs to: bug\-diffutils@gnu.org
+.br
+GNU diffutils home page: <https://www.gnu.org/software/diffutils/>
+.br
+General help using GNU software: <https://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR cmp (1),
+.BR diff (1),
+.BR diff3 (1)
+.PP
+The full documentation for
+.B sdiff
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B sdiff
+programs are properly installed at your site, the command
+.IP
+.B info sdiff
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/sed.1 b/upstream/mageia-cauldron/man1/sed.1
new file mode 100644
index 00000000..4af94ce0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sed.1
@@ -0,0 +1,433 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SED "1" "November 2022" "GNU sed 4.9" "User Commands"
+.SH NAME
+sed \- stream editor for filtering and transforming text
+.SH SYNOPSIS
+.nf
+sed [-V] [--version] [--help] [-n] [--quiet] [--silent]
+    [-l N] [--line-length=N] [-u] [--unbuffered]
+    [-E] [-r] [--regexp-extended]
+    [-e script] [--expression=script]
+    [-f script-file] [--file=script-file]
+    [script-if-no-other-script]
+    [file...]
+.fi
+.SH DESCRIPTION
+.ds sd \fIsed\fP
+.ds Sd \fISed\fP
+\*(Sd is a stream editor.
+A stream editor is used to perform basic text
+transformations on an input stream
+(a file or input from a pipeline).
+While in some ways similar to an editor which
+permits scripted edits (such as \fIed\fP),
+\*(sd works by making only one pass over the
+input(s), and is consequently more efficient.
+But it is \*(sd's ability to filter text in a pipeline
+which particularly distinguishes it from other types of
+editors.
+.HP
+\fB\-n\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+.IP
+suppress automatic printing of pattern space
+.HP
+\fB\-\-debug\fR
+.IP
+annotate program execution
+.HP
+\fB\-e\fR script, \fB\-\-expression\fR=\fI\,script\/\fR
+.IP
+add the script to the commands to be executed
+.HP
+\fB\-f\fR script\-file, \fB\-\-file\fR=\fI\,script\-file\/\fR
+.IP
+add the contents of script\-file to the commands to be executed
+.HP
+\fB\-\-follow\-symlinks\fR
+.IP
+follow symlinks when processing in place
+.HP
+\fB\-i[SUFFIX]\fR, \fB\-\-in\-place\fR[=\fI\,SUFFIX\/\fR]
+.IP
+edit files in place (makes backup if SUFFIX supplied)
+.HP
+\fB\-l\fR N, \fB\-\-line\-length\fR=\fI\,N\/\fR
+.IP
+specify the desired line\-wrap length for the `l' command
+.HP
+\fB\-\-posix\fR
+.IP
+disable all GNU extensions.
+.HP
+\fB\-E\fR, \fB\-r\fR, \fB\-\-regexp\-extended\fR
+.IP
+use extended regular expressions in the script
+(for portability use POSIX \fB\-E\fR).
+.HP
+\fB\-s\fR, \fB\-\-separate\fR
+.IP
+consider files as separate rather than as a single,
+continuous long stream.
+.HP
+\fB\-\-sandbox\fR
+.IP
+operate in sandbox mode (disable e/r/w commands).
+.HP
+\fB\-u\fR, \fB\-\-unbuffered\fR
+.IP
+load minimal amounts of data from the input files and flush
+the output buffers more often
+.HP
+\fB\-z\fR, \fB\-\-null\-data\fR
+.IP
+separate lines by NUL characters
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If no \fB\-e\fR, \fB\-\-expression\fR, \fB\-f\fR, or \fB\-\-file\fR option is given, then the first
+non\-option argument is taken as the sed script to interpret.  All
+remaining arguments are names of input files; if no input files are
+specified, then the standard input is read.
+.PP
+GNU sed home page: <https://www.gnu.org/software/sed/>.
+General help using GNU software: <https://www.gnu.org/gethelp/>.
+E\-mail bug reports to: <bug\-sed@gnu.org>.
+.SH "COMMAND SYNOPSIS"
+This is just a brief synopsis of \*(sd commands to serve as
+a reminder to those who already know \*(sd;
+other documentation (such as the texinfo document)
+must be consulted for fuller descriptions.
+.SS
+Zero-address ``commands''
+.TP
+.RI :\  label
+Label for
+.B b
+and
+.B t
+commands.
+.TP
+.RI # comment
+The comment extends until the next newline (or the end of a
+.B \-e
+script fragment).
+.TP
+}
+The closing bracket of a { } block.
+.SS
+Zero- or One- address commands
+.TP
+=
+Print the current line number.
+.TP
+a \e
+.TP
+.I text
+Append
+.IR text ,
+which has each embedded newline preceded by a backslash.
+.TP
+i \e
+.TP
+.I text
+Insert
+.IR text ,
+which has each embedded newline preceded by a backslash.
+.TP
+q [\fIexit-code\fR]
+Immediately quit the \*(sd script without processing
+any more input, except that if auto-print is not disabled
+the current pattern space will be printed.  The exit code
+argument is a GNU extension.
+.TP
+Q [\fIexit-code\fR]
+Immediately quit the \*(sd script without processing
+any more input.  This is a GNU extension.
+.TP
+.RI r\  filename
+Append text read from
+.IR filename .
+.TP
+.RI R\  filename
+Append a line read from
+.IR filename .
+Each invocation of the command reads a line from the file.
+This is a GNU extension.
+.SS
+Commands which accept address ranges
+.TP
+{
+Begin a block of commands (end with a }).
+.TP
+.RI b\  label
+Branch to
+.IR label ;
+if
+.I label
+is omitted, branch to end of script.
+.TP
+c \e
+.TP
+.I text
+Replace the selected lines with
+.IR text ,
+which has each embedded newline preceded by a backslash.
+.TP
+d
+Delete pattern space.
+Start next cycle.
+.TP
+D
+If pattern space contains no newline, start a normal new cycle as if
+the d command was issued.  Otherwise, delete text in the pattern
+space up to the first newline, and restart cycle with the resultant
+pattern space, without reading a new line of input.
+.TP
+h H
+Copy/append pattern space to hold space.
+.TP
+g G
+Copy/append hold space to pattern space.
+.TP
+l
+List out the current line in a ``visually unambiguous'' form.
+.TP
+.RI l\  width
+List out the current line in a ``visually unambiguous'' form,
+breaking it at
+.I width
+characters.  This is a GNU extension.
+.TP
+n N
+Read/append the next line of input into the pattern space.
+.TP
+p
+Print the current pattern space.
+.TP
+P
+Print up to the first embedded newline of the current pattern space.
+.TP
+.RI s/ regexp / replacement /
+Attempt to match
+.I regexp
+against the pattern space.
+If successful, replace that portion matched
+with
+.IR replacement .
+The
+.I replacement
+may contain the special character
+.B &
+to refer to that portion of the pattern space which matched,
+and the special escapes \e1 through \e9 to refer to the
+corresponding matching sub-expressions in the
+.IR regexp .
+.TP
+.RI t\  label
+If a s/// has done a successful substitution since the
+last input line was read and since the last t or T
+command, then branch to
+.IR label ;
+if
+.I label
+is omitted, branch to end of script.
+.TP
+.RI T\  label
+If no s/// has done a successful substitution since the
+last input line was read and since the last t or T
+command, then branch to
+.IR label ;
+if
+.I label
+is omitted, branch to end of script.  This is a GNU
+extension.
+.TP
+.RI w\  filename
+Write the current pattern space to
+.IR filename .
+.TP
+.RI W\  filename
+Write the first line of the current pattern space to
+.IR filename .
+This is a GNU extension.
+.TP
+x
+Exchange the contents of the hold and pattern spaces.
+.TP
+.RI y/ source / dest /
+Transliterate the characters in the pattern space which appear in
+.I source
+to the corresponding character in
+.IR dest .
+.SH
+Addresses
+\*(Sd commands can be given with no addresses, in which
+case the command will be executed for all input lines;
+with one address, in which case the command will only be executed
+for input lines which match that address; or with two
+addresses, in which case the command will be executed
+for all input lines which match the inclusive range of
+lines starting from the first address and continuing to
+the second address.
+Three things to note about address ranges:
+the syntax is
+.IR addr1 , addr2
+(i.e., the addresses are separated by a comma);
+the line which
+.I addr1
+matched will always be accepted,
+even if
+.I addr2
+selects an earlier line;
+and if
+.I addr2
+is a
+.IR regexp ,
+it will not be tested against the line that
+.I addr1
+matched.
+.PP
+After the address (or address-range),
+and before the command, a
+.B !
+may be inserted,
+which specifies that the command shall only be
+executed if the address (or address-range) does
+.B not
+match.
+.PP
+The following address types are supported:
+.TP
+.I number
+Match only the specified line
+.IR number
+(which increments cumulatively across files, unless the
+.B \-s
+option is specified on the command line).
+.TP
+.IR first ~ step
+Match every
+.IR step 'th
+line starting with line
+.IR first .
+For example, ``sed \-n 1~2p'' will print all the odd-numbered lines in
+the input stream, and the address 2~5 will match every fifth line,
+starting with the second.
+.I first
+can be zero; in this case, \*(sd operates as if it were equal to
+.IR step .
+(This is an extension.)
+.TP
+$
+Match the last line.
+.TP
+.RI / regexp /
+Match lines matching the regular expression
+.IR regexp .
+Matching is performed on the current pattern space, which
+can be modified with commands such as ``s///''.
+.TP
+.BI \fR\e\fPc regexp c
+Match lines matching the regular expression
+.IR regexp .
+The
+.B c
+may be any character.
+.PP
+GNU \*(sd also supports some special 2-address forms:
+.TP
+.RI 0, addr2
+Start out in "matched first address" state, until
+.I addr2
+is found.
+This is similar to
+.RI 1, addr2 ,
+except that if
+.I addr2
+matches the very first line of input the
+.RI 0, addr2
+form will be at the end of its range, whereas the
+.RI 1, addr2
+form will still be at the beginning of its range.
+This works only when
+.I addr2
+is a regular expression.
+.TP
+.IR addr1 ,+ N
+Will match
+.I addr1
+and the
+.I N
+lines following
+.IR addr1 .
+.TP
+.IR addr1 ,~ N
+Will match
+.I addr1
+and the lines following
+.I addr1
+until the next line whose input line number is a multiple of
+.IR N .
+.SH "REGULAR EXPRESSIONS"
+POSIX.2 BREs
+.I should
+be supported, but they aren't completely because of performance
+problems.
+The
+.B \en
+sequence in a regular expression matches the newline character,
+and similarly for
+.BR \ea ,
+.BR \et ,
+and other sequences.
+The \fI-E\fP option switches to using extended regular expressions instead;
+it has been supported for years by GNU sed, and is now
+included in POSIX.
+.SH BUGS
+.PP
+E-mail bug reports to
+.BR bug-sed@gnu.org .
+Also, please include the output of ``sed \-\-version'' in the body
+of your report if at all possible.
+.SH AUTHOR
+Written by Jay Fenlason, Tom Lord, Ken Pizzini,
+Paolo Bonzini, Jim Meyering, and Assaf Gordon.
+.PP
+This sed program was built without SELinux support.
+.PP
+GNU sed home page: <https://www.gnu.org/software/sed/>.
+General help using GNU software: <https://www.gnu.org/gethelp/>.
+E\-mail bug reports to: <bug\-sed@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+.BR awk (1),
+.BR ed (1),
+.BR grep (1),
+.BR tr (1),
+.BR perlre (1),
+sed.info,
+any of various books on \*(sd,
+.na
+the \*(sd FAQ (http://sed.sf.net/grabbag/tutorials/sedfaq.txt),
+http://sed.sf.net/grabbag/.
+.PP
+The full documentation for
+.B sed
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B sed
+programs are properly installed at your site, the command
+.IP
+.B info sed
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/seq.1 b/upstream/mageia-cauldron/man1/seq.1
new file mode 100644
index 00000000..09ff9127
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/seq.1
@@ -0,0 +1,62 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SEQ "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+seq \- print a sequence of numbers
+.SH SYNOPSIS
+.B seq
+[\fI\,OPTION\/\fR]... \fI\,LAST\/\fR
+.br
+.B seq
+[\fI\,OPTION\/\fR]... \fI\,FIRST LAST\/\fR
+.br
+.B seq
+[\fI\,OPTION\/\fR]... \fI\,FIRST INCREMENT LAST\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print numbers from FIRST to LAST, in steps of INCREMENT.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-f\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR
+use printf style floating\-point FORMAT
+.TP
+\fB\-s\fR, \fB\-\-separator\fR=\fI\,STRING\/\fR
+use STRING to separate numbers (default: \en)
+.TP
+\fB\-w\fR, \fB\-\-equal\-width\fR
+equalize width by padding with leading zeroes
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If FIRST or INCREMENT is omitted, it defaults to 1.  That is, an
+omitted INCREMENT defaults to 1 even when LAST is smaller than FIRST.
+The sequence of numbers ends when the sum of the current number and
+INCREMENT would become greater than LAST.
+FIRST, INCREMENT, and LAST are interpreted as floating point values.
+INCREMENT is usually positive if FIRST is smaller than LAST, and
+INCREMENT is usually negative if FIRST is greater than LAST.
+INCREMENT must not be 0; none of FIRST, INCREMENT and LAST may be NaN.
+FORMAT must be suitable for printing one argument of type 'double';
+it defaults to %.PRECf if FIRST, INCREMENT, and LAST are all fixed point
+decimal numbers with maximum precision PREC, and to %g otherwise.
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/seq>
+.br
+or available locally via: info \(aq(coreutils) seq invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sessreg.1 b/upstream/mageia-cauldron/man1/sessreg.1
new file mode 100644
index 00000000..084afae6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sessreg.1
@@ -0,0 +1,119 @@
+.\" Copyright 1994, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH SESSREG 1 "sessreg 1.1.3" "X Version 11"
+.SH NAME
+sessreg \- manage utmpx/wtmpx entries for non-init clients
+.SH SYNOPSIS
+.B sessreg
+[-w \fIwtmpx-file\fP]
+[-u \fIutmpx-file\fP]
+[-L \fIlastlog-file\fP]
+[-l \fIline-name\fP]
+[-h \fIhost-name\fP]
+[-s \fIslot-number\fP]
+[-x \fIXservers-file\fP]
+[-t \fIttys-file\fP]
+[-V]
+[-a]
+[-d]
+\fIuser-name\fP
+.SH DESCRIPTION
+.PP
+\fISessreg\fP is a simple program for managing utmpx/wtmpx and lastlog
+entries for xdm sessions.
+.\" __BEGIN_UTMPX_ONLY__
+.PP
+This version of \fIsessreg\fP is built using the modern POSIX
+.BR pututxline (3c)
+interfaces, which no longer require the slot-number, ttys-file, or
+Xservers-file mappings.  For compatibility with older versions and other
+operating systems, the \fB-s\fP, \fB-t\fP, and \fB-x\fP flags are accepted,
+but ignored.
+.\" __END_UTMPX_ONLY__
+.SH USAGE
+.PP
+In Xstartup, place a call like:
+.nf
+
+       sessreg -a -l $DISPLAY -x /etc/X11/xdm/Xservers $USER
+
+.fi
+and in Xreset:
+.nf
+
+       sessreg -d -l $DISPLAY -x /etc/X11/xdm/Xservers $USER
+.fi
+.SH OPTIONS
+.IP "\fB-w\fP \fIwtmpx-file\fP"
+This specifies an alternate wtmpx file, instead of
+.BR "/var/log/wtmp" .
+The special name "none" disables writing records to the wtmpx file.
+.IP "\fB-u\fP \fIutmpx-file\fP"
+This specifies an alternate utmpx file, instead of
+.BR "/run/utmp" .
+The special name "none" disables writing records to the utmpx file.
+.IP "\fB-L\fP \fIlastlog-file\fP"
+This specifies an alternate lastlog file, instead of
+.BR "/var/log/lastlog" ,
+if the platform supports lastlog files.
+The special name "none" disables writing records to the lastlog file.
+.IP "\fB-l\fP \fIline-name\fP"
+This describes the "line" name of the entry.  For terminal sessions,
+this is the final pathname segment of the terminal device filename
+(e.g. ttyd0).  For X sessions, it should probably be the local display name
+given to the users session (e.g. :0).  If none is specified, the
+terminal name will be determined with ttyname(3) and stripped of leading
+components.
+.IP "\fB-h\fP \fIhost-name\fP"
+This is set to indicate that the session was initiated from
+a remote host.  In typical xdm usage, this options is not used.
+.IP "\fB-s\fP \fIslot-number\fP"
+.\" __BEGIN_UTMPX_ONLY__
+This option is accepted for compatibility, but does nothing in
+this version of \fIsessreg\fP.
+.\" __END_UTMPX_ONLY__
+.IP "\fB-x\fP \fIXservers-file\fP"
+.\" __BEGIN_UTMPX_ONLY__
+This option is accepted for compatibility, but does nothing in
+this version of \fIsessreg\fP.
+.\" __END_UTMPX_ONLY__
+.IP "\fB-t\fP \fIttys-file\fP"
+.\" __BEGIN_UTMPX_ONLY__
+This option is accepted for compatibility, but does nothing in
+this version of \fIsessreg\fP.
+.\" __END_UTMPX_ONLY__
+.IP "\fB-V\fP"
+This option causes the command to print its version and exit.
+.IP "\fB-a\fP"
+This session should be added to utmpx/wtmpx.
+.IP "\fB-d\fP"
+This session should be deleted from utmpx/wtmpx.  One of -a/-d must
+be specified.
+.SH "SEE ALSO"
+.BR xdm (1),
+.BR utmpx (5),
+.BR wtmpx (5)
+.SH AUTHOR
+Keith Packard, MIT X Consortium
diff --git a/upstream/mageia-cauldron/man1/setleds.1 b/upstream/mageia-cauldron/man1/setleds.1
new file mode 100644
index 00000000..58dd9644
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/setleds.1
@@ -0,0 +1,84 @@
+.\" @(#)setleds.1 1.0 940924 aeb
+.TH SETLEDS 1 "24 Sep 1994" "kbd"
+.SH NAME
+setleds \- set the keyboard leds
+.SH SYNOPSIS
+.B setleds
+.RI [ "-v" "] [" "-L" "] [" "-D" "] [" "-F" ]
+.RI [ {+|-}num "] [" {+|-}caps "] [" {+|-}scroll ]
+.SH DESCRIPTION
+.IX "setleds command" "" "\fLsetleds\fR command"
+.LP
+.B Setleds
+reports and changes the led flag settings of a VT
+(namely NumLock, CapsLock and ScrollLock).
+Without arguments,
+.B setleds
+prints the current settings.
+With arguments, it sets or clears the indicated flags
+(and leaves the others unchanged). The settings before
+and after the change are reported if the \-v flag is given.
+.LP
+The led flag settings are specific for each VT (and the VT
+corresponding to stdin is used).
+.LP
+By default (or with option \-F),
+.B setleds
+will only change the VT flags (and their setting may be
+reflected by the keyboard leds).
+.LP
+With option \-D,
+.B setleds
+will change both the VT flags and their default settings
+(so that a subsequent reset will not undo the change).
+This might be useful for people who always want to have numlock set.
+.LP
+With option \-L,
+.B setleds
+will not touch the VT flags, but only change the leds.
+From this moment on, the leds will no longer reflect the VT flags
+(but display whatever is put into them). The command
+.B "setleds -L"
+(without further arguments) will restore the situation in which
+the leds reflect the VT flags.
+.LP
+One might use
+.B setleds
+in /etc/rc to define the initial and default state of NumLock,
+e.g. by
+.br
+.in +5m
+INITTY=/dev/tty[1-8]
+.br
+for tty in $INITTY; do
+.br
+.in +5m
+setleds \-D +num < $tty
+.br
+.in -5m
+done
+.in -5m
+.SH OPTIONS
+.TP
+\-num +num
+Clear or set NumLock.
+(At present, the NumLock setting influences the
+interpretation of keypad keys.
+Pressing the NumLock key complements the NumLock setting.)
+.TP
+\-caps +caps
+Clear or set CapsLock.
+(At present, the CapsLock setting complements the Shift key
+when applied to letters.
+Pressing the CapsLock key complements the CapsLock setting.)
+.TP
+\-scroll +scroll
+Clear or set ScrollLock.
+(At present, pressing the ScrollLock key (or ^S/^Q) stops/starts
+console output.)
+.SH "BUGS"
+In keyboard application mode the NumLock key does not
+influence the NumLock flag setting.
+.SH "SEE ALSO"
+.BR loadkeys (1)
+
diff --git a/upstream/mageia-cauldron/man1/setmetamode.1 b/upstream/mageia-cauldron/man1/setmetamode.1
new file mode 100644
index 00000000..57568ef4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/setmetamode.1
@@ -0,0 +1,61 @@
+.\" @(#)setmetamode.1 1.0 940130 aeb
+.TH SETMETAMODE 1 "30 Jan 1994" "kbd"
+.SH NAME
+setmetamode \- define the keyboard meta key handling
+.SH SYNOPSIS
+.B setmetamode
+[
+.I options
+]
+[
+.I argument
+]
+.SH DESCRIPTION
+.IX "setmetamode command" "" "\fLsetmetamode\fR command"  
+.LP
+Without argument,
+.B setmetamode
+prints the current Meta key mode.
+With argument, it sets the Meta key mode as indicated.
+The setting before and after the change are reported.
+.LP
+The Meta key mode is specific for each VT (and the VT
+corresponding to stdin is used).
+One might use
+.B setmetamode
+in /etc/rc to define the initial state of the Meta key mode,
+e.g. by
+.LP
+.br
+.in +5m
+INITTY=/dev/tty[1-8]
+.br
+for tty in $INITTY; do
+.br
+.in +5m
+setmetamode escprefix < $tty
+.br
+.in -5m
+done
+.in -5m
+.SH ARGUMENTS
+.TP
+\fBesc\fR, \fBprefix\fR, \fBescprefix\fR
+The Meta key sends an Escape prefix.
+.TP
+\fBmeta\fR, \fBbit\fR, \fBmetabit\fR
+The Meta key sets the high order bit of the character.
+.SH OPTIONS
+.TP
+\fB\-C\fR, \fB\-\-console\fR=\fI\,DEV\/\fR
+the console device to be used;
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number;
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+print this usage message.
+.SH "SEE ALSO"
+.BR loadkeys (1),
+.BR kbdinfo (1)
+
diff --git a/upstream/mageia-cauldron/man1/sftp.1 b/upstream/mageia-cauldron/man1/sftp.1
new file mode 100644
index 00000000..68923ae2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sftp.1
@@ -0,0 +1,728 @@
+.\" $OpenBSD: sftp.1,v 1.143 2022/12/16 03:40:03 djm Exp $
+.\"
+.\" Copyright (c) 2001 Damien Miller.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 16 2022 $
+.Dt SFTP 1
+.Os
+.Sh NAME
+.Nm sftp
+.Nd OpenSSH secure file transfer
+.Sh SYNOPSIS
+.Nm sftp
+.Op Fl 46AaCfNpqrv
+.Op Fl B Ar buffer_size
+.Op Fl b Ar batchfile
+.Op Fl c Ar cipher
+.Op Fl D Ar sftp_server_command
+.Op Fl F Ar ssh_config
+.Op Fl i Ar identity_file
+.Op Fl J Ar destination
+.Op Fl l Ar limit
+.Op Fl o Ar ssh_option
+.Op Fl P Ar port
+.Op Fl R Ar num_requests
+.Op Fl S Ar program
+.Op Fl s Ar subsystem | sftp_server
+.Op Fl X Ar sftp_option
+.Ar destination
+.Sh DESCRIPTION
+.Nm
+is a file transfer program, similar to
+.Xr ftp 1 ,
+which performs all operations over an encrypted
+.Xr ssh 1
+transport.
+It may also use many features of ssh, such as public key authentication and
+compression.
+.Pp
+The
+.Ar destination
+may be specified either as
+.Sm off
+.Oo user @ Oc host Op : path
+.Sm on
+or as a URI in the form
+.Sm off
+.No sftp:// Oo user @ Oc host Oo : port Oc Op / path .
+.Sm on
+.Pp
+If the
+.Ar destination
+includes a
+.Ar path
+and it is not a directory,
+.Nm
+will retrieve files automatically if a non-interactive
+authentication method is used; otherwise it will do so after
+successful interactive authentication.
+.Pp
+If no
+.Ar path
+is specified, or if the
+.Ar path
+is a directory,
+.Nm
+will log in to the specified
+.Ar host
+and enter interactive command mode, changing to the remote directory
+if one was specified.
+An optional trailing slash can be used to force the
+.Ar path
+to be interpreted as a directory.
+.Pp
+Since the destination formats use colon characters to delimit host
+names from path names or port numbers, IPv6 addresses must be
+enclosed in square brackets to avoid ambiguity.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 4
+Forces
+.Nm
+to use IPv4 addresses only.
+.It Fl 6
+Forces
+.Nm
+to use IPv6 addresses only.
+.It Fl A
+Allows forwarding of
+.Xr ssh-agent 1
+to the remote system.
+The default is not to forward an authentication agent.
+.It Fl a
+Attempt to continue interrupted transfers rather than overwriting
+existing partial or complete copies of files.
+If the partial contents differ from those being transferred,
+then the resultant file is likely to be corrupt.
+.It Fl B Ar buffer_size
+Specify the size of the buffer that
+.Nm
+uses when transferring files.
+Larger buffers require fewer round trips at the cost of higher
+memory consumption.
+The default is 32768 bytes.
+.It Fl b Ar batchfile
+Batch mode reads a series of commands from an input
+.Ar batchfile
+instead of
+.Em stdin .
+Since it lacks user interaction, it should be used in conjunction with
+non-interactive authentication to obviate the need to enter a password
+at connection time (see
+.Xr sshd 8
+and
+.Xr ssh-keygen 1
+for details).
+.Pp
+A
+.Ar batchfile
+of
+.Sq \-
+may be used to indicate standard input.
+.Nm
+will abort if any of the following
+commands fail:
+.Ic get , put , reget , reput , rename , ln ,
+.Ic rm , mkdir , chdir , ls ,
+.Ic lchdir , copy , cp , chmod , chown ,
+.Ic chgrp , lpwd , df , symlink ,
+and
+.Ic lmkdir .
+.Pp
+Termination on error can be suppressed on a command by command basis by
+prefixing the command with a
+.Sq \-
+character (for example,
+.Ic -rm /tmp/blah* ) .
+Echo of the command may be suppressed by prefixing the command with a
+.Sq @
+character.
+These two prefixes may be combined in any order, for example
+.Ic -@ls /bsd .
+.It Fl C
+Enables compression (via ssh's
+.Fl C
+flag).
+.It Fl c Ar cipher
+Selects the cipher to use for encrypting the data transfers.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl D Ar sftp_server_command
+Connect directly to a local sftp server
+(rather than via
+.Xr ssh 1 ) .
+A command and arguments may be specified, for example
+.Qq /path/sftp-server -el debug3 .
+This option may be useful in debugging the client and server.
+.It Fl F Ar ssh_config
+Specifies an alternative
+per-user configuration file for
+.Xr ssh 1 .
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl f
+Requests that files be flushed to disk immediately after transfer.
+When uploading files, this feature is only enabled if the server
+implements the "fsync@openssh.com" extension.
+.It Fl i Ar identity_file
+Selects the file from which the identity (private key) for public key
+authentication is read.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl J Ar destination
+Connect to the target host by first making an
+.Nm
+connection to the jump host described by
+.Ar destination
+and then establishing a TCP forwarding to the ultimate destination from
+there.
+Multiple jump hops may be specified separated by comma characters.
+This is a shortcut to specify a
+.Cm ProxyJump
+configuration directive.
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl l Ar limit
+Limits the used bandwidth, specified in Kbit/s.
+.It Fl N
+Disables quiet mode, e.g. to override the implicit quiet mode set by the
+.Fl b
+flag.
+.It Fl o Ar ssh_option
+Can be used to pass options to
+.Nm ssh
+in the format used in
+.Xr ssh_config 5 .
+This is useful for specifying options
+for which there is no separate
+.Nm sftp
+command-line flag.
+For example, to specify an alternate port use:
+.Ic sftp -oPort=24 .
+For full details of the options listed below, and their possible values, see
+.Xr ssh_config 5 .
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It AddressFamily
+.It BatchMode
+.It BindAddress
+.It BindInterface
+.It CanonicalDomains
+.It CanonicalizeFallbackLocal
+.It CanonicalizeHostname
+.It CanonicalizeMaxDots
+.It CanonicalizePermittedCNAMEs
+.It CASignatureAlgorithms
+.It CertificateFile
+.It CheckHostIP
+.It Ciphers
+.It Compression
+.It ConnectionAttempts
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
+.It ControlPersist
+.It GlobalKnownHostsFile
+.It GSSAPIAuthentication
+.It GSSAPIDelegateCredentials
+.It HashKnownHosts
+.It Host
+.It HostbasedAcceptedAlgorithms
+.It HostbasedAuthentication
+.It HostKeyAlgorithms
+.It HostKeyAlias
+.It Hostname
+.It IdentitiesOnly
+.It IdentityAgent
+.It IdentityFile
+.It IPQoS
+.It KbdInteractiveAuthentication
+.It KbdInteractiveDevices
+.It KexAlgorithms
+.It KnownHostsCommand
+.It LogLevel
+.It MACs
+.It NoHostAuthenticationForLocalhost
+.It NumberOfPasswordPrompts
+.It PasswordAuthentication
+.It PKCS11Provider
+.It Port
+.It PreferredAuthentications
+.It ProxyCommand
+.It ProxyJump
+.It PubkeyAcceptedAlgorithms
+.It PubkeyAuthentication
+.It RekeyLimit
+.It RequiredRSASize
+.It SendEnv
+.It ServerAliveInterval
+.It ServerAliveCountMax
+.It SetEnv
+.It StrictHostKeyChecking
+.It TCPKeepAlive
+.It UpdateHostKeys
+.It User
+.It UserKnownHostsFile
+.It VerifyHostKeyDNS
+.El
+.It Fl P Ar port
+Specifies the port to connect to on the remote host.
+.It Fl p
+Preserves modification times, access times, and modes from the
+original files transferred.
+.It Fl q
+Quiet mode: disables the progress meter as well as warning and
+diagnostic messages from
+.Xr ssh 1 .
+.It Fl R Ar num_requests
+Specify how many requests may be outstanding at any one time.
+Increasing this may slightly improve file transfer speed
+but will increase memory usage.
+The default is 64 outstanding requests.
+.It Fl r
+Recursively copy entire directories when uploading and downloading.
+Note that
+.Nm
+does not follow symbolic links encountered in the tree traversal.
+.It Fl S Ar program
+Name of the
+.Ar program
+to use for the encrypted connection.
+The program must understand
+.Xr ssh 1
+options.
+.It Fl s Ar subsystem | sftp_server
+Specifies the SSH2 subsystem or the path for an sftp server
+on the remote host.
+A path is useful when the remote
+.Xr sshd 8
+does not have an sftp subsystem configured.
+.It Fl v
+Raise logging level.
+This option is also passed to ssh.
+.It Fl X Ar sftp_option
+Specify an option that controls aspects of SFTP protocol behaviour.
+The valid options are:
+.Bl -tag -width Ds
+.It Cm nrequests Ns = Ns Ar value
+Controls how many concurrent SFTP read or write requests may be in progress
+at any point in time during a download or upload.
+By default 64 requests may be active concurrently.
+.It Cm buffer Ns = Ns Ar value
+Controls the maximum buffer size for a single SFTP read/write operation used
+during download or upload.
+By default a 32KB buffer is used.
+.El
+.El
+.Sh INTERACTIVE COMMANDS
+Once in interactive mode,
+.Nm
+understands a set of commands similar to those of
+.Xr ftp 1 .
+Commands are case insensitive.
+Pathnames that contain spaces must be enclosed in quotes.
+Any special characters contained within pathnames that are recognized by
+.Xr glob 3
+must be escaped with backslashes
+.Pq Sq \e .
+.Bl -tag -width Ds
+.It Ic bye
+Quit
+.Nm sftp .
+.It Ic cd Op Ar path
+Change remote directory to
+.Ar path .
+If
+.Ar path
+is not specified, then change directory to the one the session started in.
+.It Xo Ic chgrp
+.Op Fl h
+.Ar grp
+.Ar path
+.Xc
+Change group of file
+.Ar path
+to
+.Ar grp .
+.Ar path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+.Ar grp
+must be a numeric GID.
+.Pp
+If the
+.Fl h
+flag is specified, then symlinks will not be followed.
+Note that this is only supported by servers that implement
+the "lsetstat@openssh.com" extension.
+.It Xo Ic chmod
+.Op Fl h
+.Ar mode
+.Ar path
+.Xc
+Change permissions of file
+.Ar path
+to
+.Ar mode .
+.Ar path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+.Pp
+If the
+.Fl h
+flag is specified, then symlinks will not be followed.
+Note that this is only supported by servers that implement
+the "lsetstat@openssh.com" extension.
+.It Xo Ic chown
+.Op Fl h
+.Ar own
+.Ar path
+.Xc
+Change owner of file
+.Ar path
+to
+.Ar own .
+.Ar path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+.Ar own
+must be a numeric UID.
+.Pp
+If the
+.Fl h
+flag is specified, then symlinks will not be followed.
+Note that this is only supported by servers that implement
+the "lsetstat@openssh.com" extension.
+.It Ic copy Ar oldpath Ar newpath
+Copy remote file from
+.Ar oldpath
+to
+.Ar newpath .
+.Pp
+Note that this is only supported by servers that implement the "copy-data"
+extension.
+.It Ic cp Ar oldpath Ar newpath
+Alias to
+.Ic copy
+command.
+.It Xo Ic df
+.Op Fl hi
+.Op Ar path
+.Xc
+Display usage information for the filesystem holding the current directory
+(or
+.Ar path
+if specified).
+If the
+.Fl h
+flag is specified, the capacity information will be displayed using
+"human-readable" suffixes.
+The
+.Fl i
+flag requests display of inode information in addition to capacity information.
+This command is only supported on servers that implement the
+.Dq statvfs@openssh.com
+extension.
+.It Ic exit
+Quit
+.Nm sftp .
+.It Xo Ic get
+.Op Fl afpR
+.Ar remote-path
+.Op Ar local-path
+.Xc
+Retrieve the
+.Ar remote-path
+and store it on the local machine.
+If the local
+path name is not specified, it is given the same name it has on the
+remote machine.
+.Ar remote-path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+If it does and
+.Ar local-path
+is specified, then
+.Ar local-path
+must specify a directory.
+.Pp
+If the
+.Fl a
+flag is specified, then attempt to resume partial transfers of existing files.
+Note that resumption assumes that any partial copy of the local file matches
+the remote copy.
+If the remote file contents differ from the partial local copy then the
+resultant file is likely to be corrupt.
+.Pp
+If the
+.Fl f
+flag is specified, then
+.Xr fsync 2
+will be called after the file transfer has completed to flush the file
+to disk.
+.Pp
+If the
+.Fl p
+.\" undocumented redundant alias
+.\" or
+.\" .Fl P
+flag is specified, then full file permissions and access times are
+copied too.
+.Pp
+If the
+.Fl R
+.\" undocumented redundant alias
+.\" or
+.\" .Fl r
+flag is specified then directories will be copied recursively.
+Note that
+.Nm
+does not follow symbolic links when performing recursive transfers.
+.It Ic help
+Display help text.
+.It Ic lcd Op Ar path
+Change local directory to
+.Ar path .
+If
+.Ar path
+is not specified, then change directory to the local user's home directory.
+.It Ic lls Op Ar ls-options Op Ar path
+Display local directory listing of either
+.Ar path
+or current directory if
+.Ar path
+is not specified.
+.Ar ls-options
+may contain any flags supported by the local system's
+.Xr ls 1
+command.
+.Ar path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+.It Ic lmkdir Ar path
+Create local directory specified by
+.Ar path .
+.It Xo Ic ln
+.Op Fl s
+.Ar oldpath
+.Ar newpath
+.Xc
+Create a link from
+.Ar oldpath
+to
+.Ar newpath .
+If the
+.Fl s
+flag is specified the created link is a symbolic link, otherwise it is
+a hard link.
+.It Ic lpwd
+Print local working directory.
+.It Xo Ic ls
+.Op Fl 1afhlnrSt
+.Op Ar path
+.Xc
+Display a remote directory listing of either
+.Ar path
+or the current directory if
+.Ar path
+is not specified.
+.Ar path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+.Pp
+The following flags are recognized and alter the behaviour of
+.Ic ls
+accordingly:
+.Bl -tag -width Ds
+.It Fl 1
+Produce single columnar output.
+.It Fl a
+List files beginning with a dot
+.Pq Sq \&. .
+.It Fl f
+Do not sort the listing.
+The default sort order is lexicographical.
+.It Fl h
+When used with a long format option, use unit suffixes: Byte, Kilobyte,
+Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
+the number of digits to four or fewer using powers of 2 for sizes (K=1024,
+M=1048576, etc.).
+.It Fl l
+Display additional details including permissions
+and ownership information.
+.It Fl n
+Produce a long listing with user and group information presented
+numerically.
+.It Fl r
+Reverse the sort order of the listing.
+.It Fl S
+Sort the listing by file size.
+.It Fl t
+Sort the listing by last modification time.
+.El
+.It Ic lumask Ar umask
+Set local umask to
+.Ar umask .
+.It Ic mkdir Ar path
+Create remote directory specified by
+.Ar path .
+.It Ic progress
+Toggle display of progress meter.
+.It Xo Ic put
+.Op Fl afpR
+.Ar local-path
+.Op Ar remote-path
+.Xc
+Upload
+.Ar local-path
+and store it on the remote machine.
+If the remote path name is not specified, it is given the same name it has
+on the local machine.
+.Ar local-path
+may contain
+.Xr glob 7
+characters and may match multiple files.
+If it does and
+.Ar remote-path
+is specified, then
+.Ar remote-path
+must specify a directory.
+.Pp
+If the
+.Fl a
+flag is specified, then attempt to resume partial
+transfers of existing files.
+Note that resumption assumes that any partial copy of the remote file
+matches the local copy.
+If the local file contents differ from the remote local copy then
+the resultant file is likely to be corrupt.
+.Pp
+If the
+.Fl f
+flag is specified, then a request will be sent to the server to call
+.Xr fsync 2
+after the file has been transferred.
+Note that this is only supported by servers that implement
+the "fsync@openssh.com" extension.
+.Pp
+If the
+.Fl p
+.\" undocumented redundant alias
+.\" or
+.\" .Fl P
+flag is specified, then full file permissions and access times are
+copied too.
+.Pp
+If the
+.Fl R
+.\" undocumented redundant alias
+.\" or
+.\" .Fl r
+flag is specified then directories will be copied recursively.
+Note that
+.Nm
+does not follow symbolic links when performing recursive transfers.
+.It Ic pwd
+Display remote working directory.
+.It Ic quit
+Quit
+.Nm sftp .
+.It Xo Ic reget
+.Op Fl fpR
+.Ar remote-path
+.Op Ar local-path
+.Xc
+Resume download of
+.Ar remote-path .
+Equivalent to
+.Ic get
+with the
+.Fl a
+flag set.
+.It Xo Ic reput
+.Op Fl fpR
+.Ar local-path
+.Op Ar remote-path
+.Xc
+Resume upload of
+.Ar local-path .
+Equivalent to
+.Ic put
+with the
+.Fl a
+flag set.
+.It Ic rename Ar oldpath newpath
+Rename remote file from
+.Ar oldpath
+to
+.Ar newpath .
+.It Ic rm Ar path
+Delete remote file specified by
+.Ar path .
+.It Ic rmdir Ar path
+Remove remote directory specified by
+.Ar path .
+.It Ic symlink Ar oldpath newpath
+Create a symbolic link from
+.Ar oldpath
+to
+.Ar newpath .
+.It Ic version
+Display the
+.Nm
+protocol version.
+.It Ic \&! Ns Ar command
+Execute
+.Ar command
+in local shell.
+.It Ic \&!
+Escape to local shell.
+.It Ic \&?
+Synonym for help.
+.El
+.Sh SEE ALSO
+.Xr ftp 1 ,
+.Xr ls 1 ,
+.Xr scp 1 ,
+.Xr ssh 1 ,
+.Xr ssh-add 1 ,
+.Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
+.Xr glob 7 ,
+.Xr sftp-server 8 ,
+.Xr sshd 8
+.Rs
+.%A T. Ylonen
+.%A S. Lehtinen
+.%T "SSH File Transfer Protocol"
+.%N draft-ietf-secsh-filexfer-00.txt
+.%D January 2001
+.%O work in progress material
+.Re
diff --git a/upstream/mageia-cauldron/man1/sgitopnm.1 b/upstream/mageia-cauldron/man1/sgitopnm.1
new file mode 100644
index 00000000..20167e26
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgitopnm.1
@@ -0,0 +1,111 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sgitopnm User Manual" 0 "25 April 2014" "netpbm documentation"
+
+.SH NAME
+sgitopnm - convert a SGI image file to PNM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsgitopnm\fP
+
+[\fB-verbose\fP]
+
+[\fB-channel\fP \fIc\fP]
+
+[\fISgiFileName\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsgitopnm\fP reads an SGI image file as input and produces a PGM
+image for a 2-dimensional (1- or 2-channel) input file, and a PPM image for
+a 3-dimensional (3 or more channels) input file.
+.PP
+Alternatively, the program produces a PGM image of any one of the
+channels in the input file.
+.PP
+Before Netpbm 10.67 (June 2014), \fBsgitopnm\fP does not work on 2-channel
+SGI images.  It fails if you try.
+.PP
+If you don't specify the \fISgiFileName\fP argument, input is from
+Standard Input.
+.PP
+Before Netpbm 10.67 (June 2014), \fBsgitopnm\fP requires its input to
+be a seekable file, so for example you can't feed it from a pipe.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBsgitopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Give some information about the SGI image file.
+
+.TP
+\fB-channel\fP \fIn\fP
+Extract channel \fIn\fP of the image as a PGM image.
+.sp
+Without this option, \fBsgitopnm\fP extracts the first 3 channels as a PPM
+image or, if the input has 1 or 2 channels, extracts the first channel as a
+PGM image.
+.sp
+A 2-channel image is grayscale plus transparency, so you can get
+the transparency information with \fB-channel=2\fP.  You could then
+combine them into a PAM image of tuple type GRAYSCALE_ALPHA with
+\fBpamstack\fP.
+
+
+
+.UN references
+.SH REFERENCES
+.PP
+The SGI image format specification version 1.0 is at
+ftp://ftp.sgi.com/graphics/grafica/sgiimage.html .
+.PP
+There is an example SGI file at 
+https://github.com/ZaaLabs/ZaaIL-TestImages/tree/master/SGI .
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnmtosgi" (1)\c
+\&,
+.BR "pamstack" (1)\c
+\&
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1994 by Ingo Wilken
+(\fI
+Ingo.Wilken@informatik.uni-oldenburg.de\fP)
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sgitopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/sgml2html.1 b/upstream/mageia-cauldron/man1/sgml2html.1
new file mode 100644
index 00000000..7383f458
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2html.1
@@ -0,0 +1,92 @@
+.\" Process this file with
+.\" groff -man -Tascii sgml2html.1
+.\"
+.TH SGML2HTML 1 "16 May 2000"
+.SH NAME
+sgml2html \- create HTML output from a LinuxDoc DTD SGML source file
+.SH SYNOPSIS
+.B sgml2html [generic-option...] [--split
+.I 0|1|2
+.B ] [--toc
+.I 0|1|2
+.B ] [--dosnames] [--imagebuttons]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2html
+is an old and obsoleted form of the html converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B html
+now.
+This converts a LinuxDoc DTD SGML source file to HTML output.
+Output will appear in the top level file
+.I file.html
+and
+.I file-n.html
+for each section, where
+.I file
+is the name of the SGML source file and
+.I n
+is the section name.
+.LP
+The attribute/value pair "output=html" is set for conditionals.
+.SH OPTIONS
+.B sgml2html accepts all the generic options described in
+.BR linuxdoc (1),
+and the following specific options:
+.IP "--split, -s"
+What level to split source documents.  0 = don't split, 1 = split by
+major sections, 2 = split by subsections.
+.IP "--toc, -T"
+What level to generate toc.
+  0 = don't generate toc at all,
+  1 = includes major sections(/chapters/parts),
+  2 = includes subsections.
+.IP "--dosnames, -h"
+Use ".htm" rather than ".html" as the extension of
+.IP "--imagebuttons, -I"
+Use the "next", "previous", and "contents" arrow image icons included
+in /usr/share/linuxdoc-tools as navigation buttons.
+.IP "--footer, -F"
+Use the specified file as the footer in each resulted html file.
+Default footer is just plain
+
+.nh
+.nf
+.ad l
+ </BODY>\\n </HTML>\\n
+.hy
+.fi
+.IP "--header, -H"
+Use the specified file as the top part of the header in each resulted
+html file. Note this is not the full part of the header.
+(i.e. the title and the links (next,previous,contents) in the default
+header are retained. Default is
+
+.nh
+.nf
+.ad l
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\\n
+ <HTML>\\n <HEAD>\\n
+.hy
+.fi
+.IP file
+The SGML source file, named either
+.I file
+or
+.IR file.sgml .
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by Greg Hankins <greg.hankins@cc.gatech.edu>, and
+Cees de Groot <cg@cdegroot.com> for SGML-Tools (v1).
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2info (1),
+.BR sgml2latex (1),
+.BR sgml2lyx (1),
+.BR sgml2rtf (1),
+.BR sgml2txt (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgml2info.1 b/upstream/mageia-cauldron/man1/sgml2info.1
new file mode 100644
index 00000000..13822828
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2info.1
@@ -0,0 +1,48 @@
+.\" Process this file with
+.\" groff -man -Tascii sgml2info.1
+.\"
+.TH SGML2INFO 1 "16 May 2000"
+.SH NAME
+sgml2info \- create GNU info output from a LinuxDoc DTD SGML source file
+.SH SYNOPSIS
+.B sgml2info [generic-option...]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2info
+is an old and obsoleted form of the info converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B info
+now.
+This converts a LinuxDoc DTD SGML source file to GNU info format.
+Output will appear in
+.I file.info
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=info" is set for conditionals.
+.SH OPTIONS
+.B sgml2info
+accepts all the generic options described in
+.BR linuxdoc (1).
+.IP file
+specifies the SGML source file, named either
+.I file
+or
+.I file.sgml
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools are used.
+.SH AUTHOR
+Originally written by
+Christian Schwarz <schwarz@monet.m.isar.de>,
+Greg Hankins <greg.hankins@cc.gatech.edu>,
+Cees de Groot <cg@cdegroot.com>.
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2latex (1),
+.BR sgml2lyx (1),
+.BR sgml2rtf (1),
+.BR sgml2txt (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgml2latex.1 b/upstream/mageia-cauldron/man1/sgml2latex.1
new file mode 100644
index 00000000..c27eeaa5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2latex.1
@@ -0,0 +1,133 @@
+.\" Process this file with
+.\" groff -man -Tascii sgml2latex.1
+.\"
+.TH SGML2LATEX 1 "18 May 2000"
+.SH NAME
+sgml2latex \- create LaTeX, DVI, PostScript or PDF output from a LinuxDoc DTD
+SGML source file
+.SH SYNOPSIS
+.B sgml2latex [generic-option...]
+.BI [--output= tex | dvi | ps | pdf]
+.B [--bibtex] [--makeindex]
+.BI [--pagenumber= n ]
+.B --quick
+.BI [--latex= hlatexp | platex]
+.BI [--dvips= dvips | dvi2ps]
+.BI [--verbosity=n]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2latex
+is an old and obsoleted form of the latex converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B latex
+now.
+It converts a LinuxDoc DTD SGML source file to LaTeX output, using the
+.BR nsgmls (1)
+or
+.BR onsgmls (1)
+parser, and the
+.BR sgmlsasp (1)
+translator.  Using the LaTeX output, and the
+.BR latex (1)
+text formatter, you can then create DVI output, and PostScript output
+using the
+.BR dvips (1)
+converter. Output will appear in
+.I file.tex
+for LaTeX output,
+.I file.dvi
+for DVI output, or
+.I file.ps
+for PostScript output,
+where
+.I file
+is the name of the SGML source file.
+.LP
+Using  the LaTeX output, and the
+.BR pdflatex (1)
+text formatter, you can then create a nice PDF output, suitable for
+viewing with PDF viewers as
+.BR xpdf (1),
+.BR acroread (1)
+or
+.BR ghostview (1).
+.LP
+The attribute/value pair "output=latex2e" is set for conditionals.
+.SH OPTIONS
+.B sgml2latex
+accepts all the generic options described in
+.BR linuxdoc (1),
+and the following specific options:
+.IP "--output=\fIfmt\fR, -o"
+Specify the desired output format.  The specifier
+.I fmt
+may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
+.PP
+Note: This version does not overwrite/remove the intermediate
+files: tex file for dvi output, or tex/dvi files for ps output.
+This is different behavior from the original SGML-Tools 1.0.9,
+so you are warned here.
+.IP "--bibtex, -b"
+Process the generated TeX with
+.BR bibtex (1).
+.IP "--makeindex, -m"
+Generate a TeX index file suitable for processing with
+.BR makeindex (1)
+from and <idx> and <cdx> tags present in the SGML source.
+.IP "--pagenumber, -n"
+Set the starting page number in the output DVI or PS file.
+.IP "--quick, -q"
+Do only one pass of LaTeX formatting.  This is often not sufficient
+to produce final output (because of references, etc.) but is useful
+for spotting TeX errors and justification problems.
+.IP "--pass, -P"
+The argument of the pass option is inserted just after the LaTeX
+preamble generated by the document-type tag.
+Specify the desired output format.  The specifier
+.I fmt
+may be ``tex'', ``dvi'', ``ps'', or ``pdf''.
+.IP "--latex=\fIalternate_latex_command\fR, -x"
+This option is currently for Korean and Japanese.
+The
+.I alternate_latex_command
+can be ``latex'' (default), ``hlatexp'' (for Korean), ``platex''
+or ``jlatex'' (for Japanese).
+This option can be used to render Korean document using HLaTeXp,
+or to render Japanese document using pLaTeX/jLaTeX.
+If not, HLaTeX should be installed to render Korean document.
+On the other hand, Japanese document can be rendered with jLaTeX
+ (which is the default when ``\-c nippon'' is specified), so if you
+already have jLaTeX, you may not need to install the pLaTeX.
+.IP "--dvips=\fIalternate_dvips_command\fR, -s"
+This option is currently for Japanese.
+The
+.I alternate_dvips_command
+can be ``dvips'' or ``dvi2ps''.  If you don't know this, then
+you may not need this.
+.IP "--verbosity, -V"
+Set verbosity. '0' (default) will show info about LaTeX run only
+in case of errors. '1' will always show info for last run. '2'
+will show info for all runs.
+.IP file
+The SGML source file, named either
+.I file
+or
+.I file.sgml
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by
+Greg Hankins <greg.hankins@cc.gatech.edu>, based on scripts by Tom Gordon and
+Alexander Horz. Later rewritten by Cees de Groot <cg@cdegroot.com>.
+PDF patches by Juan Jose Amor <jjamor@hispalinux.es>.
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2info (1),
+.BR sgml2lyx (1),
+.BR sgml2rtf (1),
+.BR sgml2txt (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgml2lyx.1 b/upstream/mageia-cauldron/man1/sgml2lyx.1
new file mode 100644
index 00000000..14149c5d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2lyx.1
@@ -0,0 +1,48 @@
+e.\" Process this file with
+.\" groff -man -Tascii sgml2lyx.1
+.\"
+.TH SGML2LYX 1 "16 May 2000"
+.SH NAME
+sgml2lyx \- create LyX output from a LinuxDoc DTD SGML source file
+.SH SYNOPSIS
+.B sgml2lyx [generic-option...]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2lyx
+is an old and obsoleted form of the lyx converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B lyx
+now.
+It converts a LinuxDoc DTD SGML source file to LyX output.
+Output will appear in
+.I file.lyx
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=lyx" is set for conditionals.
+.SH OPTIONS
+.B sgm2lyx
+accepts all the generic options described in
+.BR linuxdoc (1).
+.IP file
+The SGML source file, named either
+.I file
+or
+.I file.sgml
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by Frank Pavageau <frank@via.ecp.fr> and
+Cees de Groot <cg@cdegroot.com> as sgml2lyx.
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2info (1),
+.BR sgml2latex (1),
+.BR sgml2rtf (1),
+.BR sgml2txt (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgml2rtf.1 b/upstream/mageia-cauldron/man1/sgml2rtf.1
new file mode 100644
index 00000000..ea6504c1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2rtf.1
@@ -0,0 +1,54 @@
+.\" Process this file with
+.\" groff -man -Tascii sgml2rtf.1
+.\"
+.TH SGML2RTF 1 "16 May 2000"
+.SH NAME
+sgml2rtf \- create RTF output from a LinuxDoc DTD SGML source file
+.SH SYNOPSIS
+.B sgml2rtf [generic_option...] [--twosplit]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2rtf
+is an old and obsoleted form of the rtf converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B rtf
+now.
+It converts a LinuxDoc DTD SGML source file to RTF, the Rich Text Tormat
+used by the Microsoft Windows help system. Output will appear in the top
+level file
+.I file.rtf
+and
+.I file-n.rtf
+for each section, where
+.I file
+is the name of the SGML source file.  The RTF output is tailored for
+compilation by the Windows Help Compiler (hc31.exe).
+.LP
+The attribute/value pair "output=rtf" is set for conditionals.
+.SH OPTIONS
+.B sgml2rtf
+accepts all the generic options described in
+.BR linuxdoc (1), and:
+.IP "--twosplit, -2"
+Splits files both at n. sections and n.m. subsections
+.IP file
+The SGML source file, named either
+.I file
+or
+.I file.sgml
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by Steve Tynor <tynor@atlanta.twr.com>, and
+Cees de Groot <cg@pobox.com> for sgml-tools (v1).
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2info (1),
+.BR sgml2latex (1),
+.BR sgml2lyx (1),
+.BR sgml2txt (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgml2txt.1 b/upstream/mageia-cauldron/man1/sgml2txt.1
new file mode 100644
index 00000000..758eb15b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgml2txt.1
@@ -0,0 +1,64 @@
+.\" Process this file with
+.\" groff -man -Tascii sgml2txt.1
+.\"
+.TH SGML2TXT 1 "16 May 2000"
+.SH NAME
+sgml2txt \- create plain text output from a LinuxDoc DTD SGML source file
+.SH SYNOPSIS
+.B sgml2txt [generic-option...] [--manpage] [--filter] [--blanks=\fIn\fB]
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgml2txt
+is an old and obsoleted form of the text converter command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B text
+now.
+It converts a LinuxDoc DTD SGML source file to ASCII, ISO-8859-1, or EUC-JP
+output. Output will appear in
+.I file.txt
+where
+.I file
+is the name of the SGML source file.
+.LP
+The attribute/value pair "output=txt" is set for conditionals.
+.SH OPTIONS
+.B sgml2txt accepts all the generic options described in
+.BR linuxdoc (1),
+and the following specific options:
+.IP "--manpage, -m"
+Outputs a groff source file, suitable for formatting with
+.B groff -man
+for man pages
+.IP "--filter, -f"
+Remove backspace-overstrikes from the intermediate form generated by
+\fBgroff\fR(1).
+.IP "--pass, -P"
+The argument of the pass option is added to the command-line options
+handed to
+.BR groff (1).
+.IP "--blanks=\fIn\fR, -b"
+Set the limit of continuous blank lines for generating the output
+document.  The default limit is 3. if 0 (zero) is specified,
+the result have many continuous blank lines.
+.IP file
+The SGML source file, named either
+.I file
+or
+.I file.sgml
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by Greg Hankins <greg.hankins@cc.gatech.edu>,
+based on scripts by Tom Gordon and Alexander Horz, and later
+rewritten by Cees de Groot <cg@cdegroot.com> for SGML-Tools (v1).
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2info (1),
+.BR sgml2latex (1),
+.BR sgml2lyx (1),
+.BR sgml2rtf (1),
+.BR sgmlcheck (1).
diff --git a/upstream/mageia-cauldron/man1/sgmlcheck.1 b/upstream/mageia-cauldron/man1/sgmlcheck.1
new file mode 100644
index 00000000..1cd2ce7a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgmlcheck.1
@@ -0,0 +1,43 @@
+.\" Process this file with
+.\" groff -man -Tascii sgmlcheck.1
+.\"
+.TH SGMLCHECK 1 "16 May 2000"
+.SH NAME
+sgmlcheck \- check the syntax of an LinuxDoc DTD sgml source file
+.SH SYNOPSIS
+.B sgmlcheck
+.IR file [.sgml]
+.SH DESCRIPTION
+.B sgmlcheck
+is an old and obsoleted form of the SGML source checker command
+of LinuxDoc-Tools.  It is recommended to switch the new form
+.B linuxdoc -B check
+now.
+It runs an SGML parse on the specified document source.  Any errors
+are reported to standard output.  No formatted version of the source
+is produced.
+.LP
+Note that
+.B sgmlcheck
+preprocesses the LinuxDoc DTD SGML source, doing the conditionalization
+described by any <#if></#if> and <#unless></#unless> tags.
+Document sources containing these tags will confuse a standalone SGML parser.
+.SH OPTIONS
+None.  The generic options described in
+.BR linuxdoc (1)
+are accepted, but have no effect (except for \-D).
+.SH FILES
+Many files and executables in /usr/share/linuxdoc-tools and /usr/bin are used.
+.SH BUGS
+None known.
+.SH AUTHOR
+Originally written by Cees de Groot <cg@cdegroot.com> as sgmlcheck
+for SGML-Tools v1.
+Currently maintained by Taketoshi Sano <sano@debian.org> for Linuxdoc-Tools.
+.SH "SEE ALSO"
+.BR linuxdoc (1),
+.BR sgml2html (1),
+.BR sgml2info (1),
+.BR sgml2latex (1),
+.BR sgml2rtf (1),
+.BR sgml2txt (1).
diff --git a/upstream/mageia-cauldron/man1/sgmlpre.1 b/upstream/mageia-cauldron/man1/sgmlpre.1
new file mode 100644
index 00000000..c5fa26ac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgmlpre.1
@@ -0,0 +1,60 @@
+.\" Process this file with
+.\" groff -man -Tascii sgmlpre.1
+.\"
+.TH SGMLPRE "1"
+.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
+.\" other parms are allowed: see man(7), man(1)
+.SH NAME
+sgmlpre \- handle SGML conditionalization for SGML-tools
+.SH SYNOPSIS
+.B sgmlpre
+.I "[options] ..."
+.SH "DESCRIPTION"
+This manual page documents briefly the
+.BR sgmlpre
+commands.
+This manual page was written for the Debian GNU/Linux distribution
+because the original program does not have a manual page for sgmlpre.
+.PP
+.B sgmlpre
+is a program that handle SGML conditionalization for SGML-tools
+.PP
+It is used by other programs in sgml-tools (v1), and usually
+normal user does not need to use this program directly by himself.
+.PP
+Following is quoted from the header in the source code.
+.TP
+(Begin Quotes)
+
+.B sgmlpre
+-- handle SGML conditionalization for SGML-tools
+by Eric S. Raymond <esr@thyrsus.com>, 3 Nov 1997
+
+Filter SGML according to conditionalizing markup.  Argument/value pairs
+from the command line are matched against the attributes of <#if> and
+<#unless> tags.  Spans between <#if>/</#if> are passed through unaltered
+if there is no attribute mismatch; spans between <#unless></#unless> are
+passed if there is at least one attribute mismatch.  An attribute mismatch
+happens  if an attribute occurs in both the command-line arguments and the
+tag, but the values do not match.  Value matching is by string equality,
+except that "|" is interpreted as an alternation character.  Even if a span
+is not passed through, its newlines are (this to avoid messing up the
+line  numbers in error messages).
+
+This lexer requires flex.  Limitations; attribute names may only be
+256 chars long, values may be only 16384 (YY_BUF_SIZE) characters long.
+Doesn't do checking that only </if> matches <if> and </unless> matches
+<unless> (that would need a stack and introduce another limit).
+.TP
+(End Quotes)
+
+.SH OPTIONS
+The program does not support normal command line options.
+.SH "SEE ALSO"
+For a complete description, see the header in the source archive.
+.SH AUTHOR
+.B sgmlpre
+was written by Eric S. Raymond <esr@thyrsus.com>, 3 Nov 1997.
+
+This manual page was written by Taketoshi Sano <sano@debian.org>,
+for the Debian GNU/Linux system (but may be used by others).
diff --git a/upstream/mageia-cauldron/man1/sgmlsasp.1 b/upstream/mageia-cauldron/man1/sgmlsasp.1
new file mode 100644
index 00000000..ab033711
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sgmlsasp.1
@@ -0,0 +1,30 @@
+.\" -*- nroff -*-
+.TH SGMLSASP 1
+.SH NAME
+sgmlsasp \- translate output of sgmls using ASP replacement files
+.SH SYNOPSIS
+.B sgmls
+.RB [ \-n ]
+.I replacement_file\|.\|.\|.
+.SH DESCRIPTION
+.I sgmlsasp
+translates the standard input using the specification in
+.I replacement_file\|.\|.\|.
+and writes the result to the standard output.
+The standard input must be in the format output by
+.IR sgmls .
+Each replacement file must be in the format of an
+Amsterdam SGML parser (ASP) replacement file;
+this format is described in the ASP documentation.
+Duplicate replacements are silently ignored.
+The
+.B \-n
+option disables upper-case substitution (folding) for names in
+replacement files; this option should be used with concrete syntaxes
+that do not specify upper-case substitution for general names (that
+is, names that are not entity names).
+.SH BUGS
+References to external data entities are ignored.
+(Support for external data entities is not implemented in ASP.)
+.SH "SEE ALSO"
+.IR sgmls (1)
diff --git a/upstream/mageia-cauldron/man1/sha1sum.1 b/upstream/mageia-cauldron/man1/sha1sum.1
new file mode 100644
index 00000000..9209d6a3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sha1sum.1
@@ -0,0 +1,83 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHA1SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sha1sum \- compute and check SHA1 message digest
+.SH SYNOPSIS
+.B sha1sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check SHA1 (160\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in FIPS\-180\-1.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH BUGS
+Do not use the SHA-1 algorithm for security related purposes.
+Instead, use an SHA\-2 algorithm, implemented in the programs
+\fBsha224sum\fP(1), \fBsha256sum\fP(1), \fBsha384sum\fP(1), \fBsha512sum\fP(1),
+or the BLAKE2 algorithm, implemented in \fBb2sum\fP(1)
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sha1sum>
+.br
+or available locally via: info \(aq(coreutils) sha1sum invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sha224sum.1 b/upstream/mageia-cauldron/man1/sha224sum.1
new file mode 100644
index 00000000..3b6a4d74
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sha224sum.1
@@ -0,0 +1,78 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHA224SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sha224sum \- compute and check SHA224 message digest
+.SH SYNOPSIS
+.B sha224sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check SHA224 (224\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in RFC 3874.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sha224sum>
+.br
+or available locally via: info \(aq(coreutils) sha2 utilities\(aq
diff --git a/upstream/mageia-cauldron/man1/sha256sum.1 b/upstream/mageia-cauldron/man1/sha256sum.1
new file mode 100644
index 00000000..27720419
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sha256sum.1
@@ -0,0 +1,78 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHA256SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sha256sum \- compute and check SHA256 message digest
+.SH SYNOPSIS
+.B sha256sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check SHA256 (256\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in FIPS\-180\-2.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sha256sum>
+.br
+or available locally via: info \(aq(coreutils) sha2 utilities\(aq
diff --git a/upstream/mageia-cauldron/man1/sha384sum.1 b/upstream/mageia-cauldron/man1/sha384sum.1
new file mode 100644
index 00000000..03c38db4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sha384sum.1
@@ -0,0 +1,78 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHA384SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sha384sum \- compute and check SHA384 message digest
+.SH SYNOPSIS
+.B sha384sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check SHA384 (384\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in FIPS\-180\-2.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sha384sum>
+.br
+or available locally via: info \(aq(coreutils) sha2 utilities\(aq
diff --git a/upstream/mageia-cauldron/man1/sha512sum.1 b/upstream/mageia-cauldron/man1/sha512sum.1
new file mode 100644
index 00000000..6e69d2ee
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sha512sum.1
@@ -0,0 +1,78 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHA512SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sha512sum \- compute and check SHA512 message digest
+.SH SYNOPSIS
+.B sha512sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check SHA512 (512\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR
+read in binary mode
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+read checksums from the FILEs and check them
+.TP
+\fB\-\-tag\fR
+create a BSD\-style checksum
+.TP
+\fB\-t\fR, \fB\-\-text\fR
+read in text mode (default)
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+end each output line with NUL, not newline,
+and disable file name escaping
+.SS "The following five options are useful only when verifying checksums:"
+.TP
+\fB\-\-ignore\-missing\fR
+don't fail or report status for missing files
+.TP
+\fB\-\-quiet\fR
+don't print OK for each successfully verified file
+.TP
+\fB\-\-status\fR
+don't output anything, status code shows success
+.TP
+\fB\-\-strict\fR
+exit non\-zero for improperly formatted checksum lines
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+warn about improperly formatted checksum lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The sums are computed as described in FIPS\-180\-2.
+When checking, the input should be a former output of this program.
+The default mode is to print a line with: checksum, a space,
+a character indicating input mode ('*' for binary, ' ' for text
+or where binary is insignificant), and name for each FILE.
+.PP
+Note: There is no difference between binary mode and text mode on GNU systems.
+.SH AUTHOR
+Written by Ulrich Drepper, Scott Miller, and David Madore.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcksum\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sha512sum>
+.br
+or available locally via: info \(aq(coreutils) sha2 utilities\(aq
diff --git a/upstream/mageia-cauldron/man1/shar.1 b/upstream/mageia-cauldron/man1/shar.1
new file mode 100644
index 00000000..2c6f1f3f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/shar.1
@@ -0,0 +1,635 @@
+.de1 NOP
+.  it 1 an-trap
+.  if \\n[.$] \,\\$*\/
+..
+.ie t \
+.ds B-Font [CB]
+.ds I-Font [CI]
+.ds R-Font [CR]
+.el \
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+.TH shar 1 "30 May 2015" "GNU sharutils (4.15.2)" "User Commands"
+.\"
+.\" DO NOT EDIT THIS FILE (in-mem file)
+.\"
+.\" It has been AutoGen-ed
+.\" From the definitions shar-opts.def
+.\" and the template file agman-cmd.tpl
+.SH NAME
+\f\*[B-Font]shar\fP
+\- create a shell archive
+.SH SYNOPSIS
+\f\*[B-Font]shar\fP
+.\" Mixture of short (flag) options and long options
+[\f\*[B-Font]\-flags\f[]]
+[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
+[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
+[<file>...]
+.sp \n(Ppu
+.ne 2
+
+If no \fIfile\fPs are specified, the list of input files is read
+from standard input.  Standard input must not be a terminal.
+.SH "DESCRIPTION"
+\fBshar\fP creates "shell archives" (or shar files) which are in
+text format and can be emailed.  These files may be unpacked later by
+executing them with \fI/bin/sh\fP.  The resulting archive is sent to
+standard out unless the \fB-o\fP option is given.  A wide range of
+features provide extensive flexibility in manufacturing shars and in
+specifying \fBshar\fP "smartness".  Archives may be fairly simple
+(\fB--vanilla-operation\fP) or essentially a mailable \fBtar\fP
+archive.
+.sp
+Options may be specified in any order until a \fBfile\fP argument is
+recognized.  If the \fB--intermix-type\fP option has been specified,
+more compression and encoding options will be recognized between the
+\fIfile\fP arguments.
+.sp
+Though this program supports \fBuuencode\fP-d files, they
+are deprecated.  If you are emailing files, please consider
+mime-encoded files.  If you do \fBuuencode\fP, base64 is the
+preferred encoding method.
+.SH "OPTIONS"
+.SS "Specifying compression"
+.TP
+.NOP \f\*[B-Font]\-p\f[], \f\*[B-Font]\-\-intermix\-type\f[]
+specify compression for input files.
+This option must not appear in combination with any of the following options:
+vanilla-operation.
+.sp
+Allow positional parameter options.  The compression method and
+encoding method options may be intermixed with file names.
+Files named after these options will be processed in the specified way.
+.TP
+.NOP \f\*[B-Font]\-C\f[] \f\*[I-Font]program\f[], \f\*[B-Font]\-\-compactor\f[]=\f\*[I-Font]program\f[]
+specify compaction (compression) program.
+This option may appear an unlimited number of times.
+This option must not appear in combination with any of the following options:
+vanilla-operation.
+.sp
+The \fBgzip\fP, \fBbzip2\fP and \fBcompress\fP compactor
+commands may be specified by the program name as the option name,
+e.g. \fB--gzip\fP.  Those options, however, are being deprecated.
+There is also the \fBxz\fP compactor now.  Specify \fBxz\fP
+with \fB-C xz\fP or \fB--compactor=xz\fP.
+.sp
+        Specifying the compactor "\fBnone\fP" will disable file compression.
+Compressed files are never processed as plain text.  They are always
+uuencoded and the recipient must have \fBuudecode\fP to unpack
+them.
+.sp
+Specifying the compactor \fBcompress\fP is deprecated.
+.TP
+.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]level\f[], \f\*[B-Font]\-\-level\-of\-compression\f[]=\f\*[I-Font]level\f[]
+pass \fILEVEL\fP for compression.
+This option takes an integer number as its argument.
+The value of
+\f\*[I-Font]level\f[]
+is constrained to being:
+.in +4
+.nf
+.na
+in the range  1 through 9
+.fi
+.in -4
+The default
+\f\*[I-Font]level\f[]
+for this option is:
+.ti +4
+ 9
+.sp
+Some compression programs allow for a level of compression.  The
+default is \fB9\fP, but this option allows you to specify something
+else.  This value is used by \fBgzip\fP, \fBbzip2\fP and
+\fBxz\fP, but not \fBcompress\fP.
+.TP
+.NOP \f\*[B-Font]\-j\f[], \f\*[B-Font]\-\-bzip2\f[]
+\fBbzip2\fP and \fBuuencode\fP files.
+This option may appear an unlimited number of times.
+.sp
+\fBbzip2\fP compress and \fBuuencode\fP all files
+prior to packing.  The recipient must have \fBuudecode\fP
+\fBbzip2\fP in order to unpack.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.TP
+.NOP \f\*[B-Font]\-z\f[], \f\*[B-Font]\-\-gzip\f[]
+\fBgzip\fP and \fBuuencode\fP files.
+This option may appear an unlimited number of times.
+.sp
+\fBgzip\fP compress and \fBuuencode\fP all files prior
+to packing.  The recipient must have \fBuudecode\fP and
+\fBgzip\fP in order to unpack.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.TP
+.NOP \f\*[B-Font]\-Z\f[], \f\*[B-Font]\-\-compress\f[]
+\fBcompress\fP and \fBuuencode\fP files.
+This option may appear an unlimited number of times.
+.sp
+\fBcompress\fP and \fBuuencode\fP all files prior to
+packing.  The recipient must have \fBuudecode\fP and
+\fBcompress\fP in order to unpack.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.TP
+.NOP \f\*[B-Font]\-\-level-for-gzip\f[]
+This is an alias for the \fI--level-of-compression\fR option.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.TP
+.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]bits\f[], \f\*[B-Font]\-\-bits\-per\-code\f[]=\f\*[I-Font]bits\f[]
+pass \fIbits\fP (default 12) to compress.
+The default
+\f\*[I-Font]bits\f[]
+for this option is:
+.ti +4
+ 12
+.sp
+This is the compression factor used by the \fBcompress\fP program.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.SS "Specifying file encoding methodology"
+Files may be stored in the shar either as plain text or uuencoded.
+By default, the program selects which by examining the file.
+You may force the selection for all files.  In intermixed option/file
+mode, this setting may be changed during processing.
+.TP
+.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-mixed\-uuencode\f[]
+decide uuencoding for each file.
+This option is a member of the mixed-uuencode class of options.
+.sp
+Automatically determine if the files are text or binary and archive
+correctly.  Files found to be binary are uuencoded prior to packing.
+This is the default behavior for \fBshar\fP.
+.sp
+For a file to be considered a text file instead of a binary file,
+all the following should be true:
+.sp 1
+The file does not contain any ASCII control character besides \fIBS\fP
+(backspace), \fIHT\fP (horizontal tab), \fILF\fP (new line) or
+\fIFF\fP (form feed).
+.sp 1
+The file contains no character with its eighth-bit set.
+.sp 1
+The file contains no line beginning with the five letters
+"\fBfrom \fP", capitalized or not.  (Mail handling programs
+will often gratuitously insert a \fB>\fP character before it.)
+.sp 1
+The file is either empty or ends with a \fILF\fP (newline) byte.
+.sp 1
+No line in the file contains more than 200 characters.  For counting
+purpose, lines are separated by a \fILF\fP (newline).
+.br
+.TP
+.NOP \f\*[B-Font]\-B\f[], \f\*[B-Font]\-\-uuencode\f[]
+treat all files as binary.
+This option is a member of the mixed-uuencode class of options.
+.sp
+Use \fBuuencode\fP prior to packing all files.  This
+increases the size of the archive.  The recipient must have
+\fBuudecode\fP in order to unpack.  Compressed files are
+always encoded.
+.TP
+.NOP \f\*[B-Font]\-T\f[], \f\*[B-Font]\-\-text\-files\f[]
+treat all files as text.
+This option is a member of the mixed-uuencode class of options.
+.sp
+If you have files with non-ascii bytes or text that some mail handling
+programs do not like, you may find difficulties.  However, if you are
+using FTP or SSH/SCP, the non-conforming text files should be okay.
+.SS "Specifying file selection and output modes"
+.TP
+.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]prefix\f[], \f\*[B-Font]\-\-output\-prefix\f[]=\f\*[I-Font]prefix\f[]
+print output to file PREFIX.nn.
+.sp
+Save the archive to files \fIprefix.01\fP thru \fIprefix.nn\fP
+instead of sending all output to standard out.  Must be specified when
+the \fB--whole-size-limit\fP or \fB--split-size-limit\fP
+options are specified.
+.sp
+When \fBprefix\fP contains a \fB%\fP character, \fBprefix\fP is then
+interpreted as a \fBsprintf\fP format, which should be able to display
+a single decimal number.  When \fBprefix\fP does not contain such a
+\fB%\fP character, the string \fB.%02d\fP is internally appended.
+.TP
+.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]size\f[], \f\*[B-Font]\-\-whole\-size\-limit\f[]=\f\*[I-Font]size\f[]
+split archive, not files, to \fIsize\fP.
+This option is a member of the whole-size-limit class of options.
+This option must appear in combination with the following options:
+output-prefix.
+This option takes an integer number as its argument.
+The value of
+\f\*[I-Font]size\f[]
+is constrained to being:
+.in +4
+.nf
+.na
+in the range  8 through 1023, or
+in the range  8192 through 4194304
+.fi
+.in -4
+.sp
+Limit the output file size to \fIsize\fP bytes, but don't split input
+files.  If \fIsize\fP is less than 1024, then it will be multiplied
+by 1024.  The value may also be specified with a k, K, m or M suffix.
+The number is then multiplied by 1000, 1024, 1000000, or 1048576,
+respectively.  4M (4194304) is the maximum allowed.
+.sp
+Unlike the \fBsplit-size-limit\fP option, this allows the recipient
+of the shar files to unpack them in any order.
+.TP
+.NOP \f\*[B-Font]\-L\f[] \f\*[I-Font]size\f[], \f\*[B-Font]\-\-split\-size\-limit\f[]=\f\*[I-Font]size\f[]
+split archive or files to \fIsize\fP.
+This option is a member of the whole-size-limit class of options.
+This option must appear in combination with the following options:
+output-prefix.
+This option takes an integer number as its argument.
+The value of
+\f\*[I-Font]size\f[]
+is constrained to being:
+.in +4
+.nf
+.na
+in the range  8 through 1023, or
+in the range  8192 through 4194304
+.fi
+.in -4
+.sp
+Limit output file size to \fIsize\fP bytes, splitting files if
+necessary.  The allowed values are specified as with the
+\fB--whole-size-limit\fP option.
+.sp
+The archive parts created with this option must be unpacked in the
+correct order.  If the recipient of the shell archives wants to put
+all of them in a single email folder (file), they will have to be
+saved in the correct order for \fBunshar\fP to unpack them all at
+once (using one of the split archive options).
+see: unshar Invocation.
+.TP
+.NOP \f\*[B-Font]\-I\f[] \f\*[I-Font]file\f[], \f\*[B-Font]\-\-input\-file\-list\f[]=\f\*[I-Font]file\f[]
+read file list from a file.
+.sp
+This option causes \fIfile\fP to be reopened as standard input.  If
+no files are found on the input line, then standard input is read for
+input file names.  Use of this option will prohibit input files from
+being listed on the command line.
+.sp
+Input must be in a form similar to that generated by \fBfind\fP,
+one filename per line.  This switch is especially useful when the
+command line will not hold the list of files to be archived.
+.sp
+If the \fB--intermix-type\fP option is specified on the command
+line, then the compression options may be included in the standard
+input on lines by themselves and no file name may begin with a hyphen.
+.sp
+For example:
+.nf
+    { echo \--compact xz
+       find . \-type f \-print | sort
+    } | shar \-S \-p \-L50K \-o /somewhere/big
+.fi
+.TP
+.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-stdin\-file\-list\f[]
+read file list from standard input.
+.sp
+This option is actually a no-op.  It is a wrapper for
+\fB--input-file-list=-\fP.
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.SS "Controlling the shar headers"
+.TP
+.NOP \f\*[B-Font]\-n\f[] \f\*[I-Font]name\f[], \f\*[B-Font]\-\-archive\-name\f[]=\f\*[I-Font]name\f[]
+use \fIname\fP to document the archive.
+.sp
+Name of archive to be included in the subject header of the shar
+files.  See the \fB--net-headers\fP option.
+.TP
+.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]who@where\f[], \f\*[B-Font]\-\-submitter\f[]=\f\*[I-Font]who@where\f[]
+override the submitter name.
+.sp
+\fBshar\fP will normally determine the submitter name by querying
+the system.  Use this option if it is being done on behalf of another.
+.TP
+.NOP \f\*[B-Font]\-a\f[], \f\*[B-Font]\-\-net\-headers\f[]
+output Submitted-by: & Archive-name: headers.
+This option must appear in combination with the following options:
+archive-name.
+.sp
+Adds specialized email headers:
+.nf
+    Submitted-by: \fIwho@@where\fP
+    Archive-name: \fIname\fP/part##
+.fi
+The \fIwho@@where\fP is normally derived, but can be specified with the
+\fB--submitter\fP option.  The \fIname\fP must be provided with the
+\fB--archive-name\fP option.  If the archive name includes a slash
+(\fB/\fP) character, then the \fB/part##\fP is omitted.  Thus
+\fB-n xyzzy\fP produces:
+.nf
+    xyzzy/part01
+    xyzzy/part02
+.fi
+.sp
+while \fB-n xyzzy/patch\fP produces:
+.nf
+    xyzzy/patch01
+    xyzzy/patch02
+.fi
+.sp
+and \fB-n xyzzy/patch01.\fP produces:
+.nf
+    xyzzy/patch01.01
+    xyzzy/patch01.02
+.fi
+.TP
+.NOP \f\*[B-Font]\-c\f[], \f\*[B-Font]\-\-cut\-mark\f[]
+start the shar with a cut line.
+.sp
+A line saying 'Cut here' is placed at the
+start of each output file.
+.TP
+.NOP \f\*[B-Font]\-t\f[], \f\*[B-Font]\-\-translate\f[]
+translate messages in the script.
+.sp
+Translate messages in the script.  If you have set the \fBLANG\fP
+environment variable, messages printed by \fBshar\fP will be in the
+specified language.  The produced script will still be emitted using
+messages in the lingua franca of the computer world: English.  This
+option will cause the script messages to appear in the languages
+specified by the \fBLANG\fP environment variable set when the script
+is produced.
+.SS "Protecting against transmission issues"
+.TP
+.NOP \f\*[B-Font]\-\-no\-character\-count\f[]
+do not use `wc \-c' to check size.
+.sp
+Do NOT check each file with 'wc \-c' after unpack.
+The default is to check.
+.TP
+.NOP \f\*[B-Font]\-D\f[], \f\*[B-Font]\-\-no\-md5\-digest\f[]
+do not use \fBmd5sum\fP digest to verify.
+.sp
+Do \fInot\fP use \fBmd5sum\fP digest to verify the unpacked files.
+The default is to check.
+.TP
+.NOP \f\*[B-Font]\-F\f[], \f\*[B-Font]\-\-force\-prefix\f[]
+apply the prefix character on every line.
+.sp
+Forces the prefix character to be prepended to every line, even if
+not required.  This option may slightly increase the size of the archive,
+especially if \fB--uuencode\fP or a compression option is used.
+.TP
+.NOP \f\*[B-Font]\-d\f[] \f\*[I-Font]delim\f[], \f\*[B-Font]\-\-here\-delimiter\f[]=\f\*[I-Font]delim\f[]
+use \fIdelim\fP to delimit the files.
+The default
+\f\*[I-Font]delim\f[]
+for this option is:
+.ti +4
+ SHAR_EOF
+.sp
+Use DELIM to delimit the files in the shar instead of SHAR_EOF.
+This is for those who want to personalize their shar files.
+The delimiter will always be prefixed and suffixed with underscores.
+.SS "Producing different kinds of shars"
+.TP
+.NOP \f\*[B-Font]\-V\f[], \f\*[B-Font]\-\-vanilla\-operation\f[]
+produce very simple shars.
+.sp
+This option produces \fBvanilla\fP shars which rely only upon the
+existence of \fBecho\fP, \fBtest\fP and \fBsed\fP in the
+unpacking environment.
+.sp
+It changes the default behavior from mixed mode
+(\fB--mixed-uuencode\fP) to text mode (\fB--text-files\fP).
+Warnings are produced if options are specified that will require
+decompression or decoding in the unpacking environment.
+.TP
+.NOP \f\*[B-Font]\-P\f[], \f\*[B-Font]\-\-no\-piping\f[]
+use temporary files between programs.
+.sp
+In the \fIshar\fP file, use a temporary file to hold file contents
+between unpacking stages instead of using pipes.  This option is
+mandatory when you know the unpacking will happen on systems that do
+not support pipes.
+.TP
+.NOP \f\*[B-Font]\-x\f[], \f\*[B-Font]\-\-no\-check\-existing\f[]
+blindly overwrite existing files.
+.sp
+Create the archive so that when processed it will overwrite existing
+files without checking first.  If neither this option nor the
+\fB--query-user\fP option is specified, the unpack will not
+overwrite pre-existing files.  In all cases, however, if
+\fB--cut-mark\fP is passed as a parameter to the script when
+unpacking, then existing files will be overwritten unconditionally.
+.sp
+.nf
+    sh shar-archive-file \-c
+.fi
+.TP
+.NOP \f\*[B-Font]\-X\f[], \f\*[B-Font]\-\-query\-user\f[]
+ask user before overwriting files.
+This option must not appear in combination with any of the following options:
+vanilla-operation.
+.sp
+When unpacking, interactively ask the user if files should be
+overwritten.  Do not use for shars submitted to the net.
+.sp
+Use of this option produces shars which \fIwill\fP cause problems
+with some unshar-style procedures, particularly when used
+together with vanilla mode (\fB--vanilla-operation\fP).  Use this
+feature mainly for archives to be passed among agreeable parties.
+Certainly, \fB-X\fP is \fInot\fP for shell archives which are to be
+submitted to Usenet or other public networks.
+.sp
+The problem is that \fBunshar\fP programs or procedures often feed
+\fI/bin/sh\fP from its standard input, thus putting \fI/bin/sh\fP
+and the shell archive script in competition for input lines.  As an
+attempt to alleviate this problem, \fBshar\fP will try to detect
+if \fI/dev/tty\fP exists at the receiving site and will use it to
+read user replies.  But this does not work in all cases, it may happen
+that the receiving user will have to avoid using \fBunshar\fP
+programs or procedures, and call \fI/bin/sh\fP directly.  In vanilla
+mode, using \fI/dev/tty\fP is not even attempted.
+.TP
+.NOP \f\*[B-Font]\-m\f[], \f\*[B-Font]\-\-no\-timestamp\f[]
+do not restore modification times.
+.sp
+Avoid generating 'touch' commands to restore the file modification
+dates when unpacking files from the archive.
+.sp
+When file modification times are not preserved, project build programs
+like "make" will see built files older than the files they get built
+from.  This is why, when this option is not used, a special effort is
+made to restore timestamps.
+.TP
+.NOP \f\*[B-Font]\-Q\f[], \f\*[B-Font]\-\-quiet\-unshar\f[]
+avoid verbose messages at unshar time.
+.sp
+Verbose OFF.  Disables the inclusion of comments to be output when
+the archive is unpacked.
+.TP
+.NOP \f\*[B-Font]\-f\f[], \f\*[B-Font]\-\-basename\f[]
+restore in one directory, despite hierarchy.
+.sp
+Restore by the base file name only, rather than path.  This option
+causes only file names to be used, which is useful when building a
+shar from several directories, or another directory.  Note that if a
+directory name is passed to shar, the substructure of that directory
+will be restored whether this option is specified or not.
+.SS "Internationalization options"
+.TP
+.NOP \f\*[B-Font]\-\-no\-i18n\f[]
+do not internationalize.
+.sp
+Do not produce internationalized shell archives, use default English
+messages.  By default, shar produces archives that will try to output
+messages in the unpackers preferred language (as determined by the
+LANG/LC_MESSAGES environmental variables) when they are unpacked.  If
+no message file for the unpackers language is found at unpack time,
+messages will be in English.
+.TP
+.NOP \f\*[B-Font]\-\-print\-text\-domain\-dir\f[]
+print directory with shar messages.
+.sp
+Prints the directory shar looks in to find messages files
+for different languages, then immediately exits.
+.SS "User feedback/entertainment"
+.TP
+.NOP \f\*[B-Font]\-q\f[], \f\*[B-Font]\-\-quiet\f[]
+do not output verbose messages.
+.sp
+omit progress messages.
+.TP
+.NOP \f\*[B-Font]\-\-silent\f[]
+This is an alias for the \fI--quiet\fR option.
+.TP
+.NOP \f\*[B-Font]\-h\f[], \f\*[B-Font]\-\-help\f[]
+Display usage information and exit.
+.TP
+.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
+Pass the extended usage information through a pager.
+.TP
+.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
+Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+The command will exit after updating the config file.
+.TP
+.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
+Load options from \fIcfgfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
+out of order.
+.TP
+.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]
+Output version of program and exit.  The default mode is `v', a simple
+version.  The `c' mode will print copyright information and `n' will
+print the full copyright notice.
+.PP
+.SH "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from configuration ("RC" or ".INI") file(s).
+The file "\fI$HOME/.sharrc\fP" will be used, if present.
+.SH WARNINGS
+No attempt is made to restore the protection and modification dates
+for directories, even if this is done by default for files.  Thus, if
+a directory is given to \fBshar\fP, the protection and modification
+dates of corresponding unpacked directory may not match those of the
+original.
+.sp
+If a directory is passed to shar, it may be scanned more than once, to
+conserve memory.  Therefore, do not change the directory contents
+while shar is running.
+.sp
+Be careful that the output file(s) are not included in the inputs or
+shar may loop until the disk fills up.  Be particularly careful when a
+directory is passed to shar that the output files are not in that
+directory or a subdirectory of it.
+.sp
+Use of the compression and encoding options will slow the archive
+process, perhaps considerably.
+.sp
+Use of the \fB\-\-query\-user\fP produces shars which \fIwill\fP
+cause problems with many unshar procedures.  Use this feature only for
+archives to be passed among agreeable parties.  Certainly,
+\fBquery\-user\fP is NOT for shell archives which are to be
+distributed across the net.  The use of compression in net shars will
+cause you to be flamed off the earth.  Not using the
+\fB\-\-no\-timestamp\fP or \fB\-\-force\-prefix\fP options may also
+get you occasional complaints.  Put these options into your
+\fI~/.sharrc\fP file.
+.SH "FILES"
+See \fBOPTION PRESETS\fP for configuration files.
+.SH EXAMPLES
+The first shows how to make a shell archive out of all C program
+sources.  The second produces a shell archive with all \fI.c\fP and
+\fI.h\fP files, which unpacks silently.  The third gives a shell
+archive of all uuencoded \fI.arc\fP files, into numbered files
+starting from \fIarc.sh.01\fP.  The last example gives a shell
+archive which will use only the file names at unpack time.
+.sp
+.br
+.in +4
+.nf
+shar *.c > cprog.shar
+shar \-Q *.[ch] > cprog.shar
+shar \-B \-l28 \-oarc.sh *.arc
+shar \-f /lcl/src/u*.c > u.sh
+.in -4
+.fi
+.SH "EXIT STATUS"
+One of the following exit values will be returned:
+.TP
+.NOP 0 " (EXIT_SUCCESS)"
+Successful program execution.
+.TP
+.NOP 1 " (EXIT_OPTION_ERROR)"
+The command options were misconfigured.
+.TP
+.NOP 2 " (EXIT_FILE_NOT_FOUND)"
+a specified input could not be found
+.TP
+.NOP 3 " (EXIT_CANNOT_OPENDIR)"
+open/close of specified directory failed
+.TP
+.NOP 4 " (EXIT_FAILED)"
+Resource limit/miscelleaneous shar command failure
+.TP
+.NOP 63 " (EXIT_BUG)"
+There is a shar command bug.  Please report it.
+.TP
+.NOP 66 " (EX_NOINPUT)"
+A specified configuration file could not be loaded.
+.TP
+.NOP 70 " (EX_SOFTWARE)"
+libopts had an internal operational error.  Please report
+it to autogen-users@lists.sourceforge.net.  Thank you.
+.PP
+.SH "SEE ALSO"
+unshar(1)
+.SH AUTHORS
+The \fIshar\fP and \fIunshar\fP programs is the collective work of
+many authors.  Many people contributed by reporting problems,
+suggesting various improvements or submitting actual code.  A list of
+these people is in the \fITHANKS\fP file in the sharutils distribution.
+.SH "COPYRIGHT"
+Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
+This program is released under the terms of the GNU General Public License, version 3 or later.
+.SH BUGS
+Please put \fBsharutils\fP in the subject line for emailed bug
+reports.  It helps to spot the message.
+.sp \n(Ppu
+.ne 2
+
+Please send bug reports to: bug-gnu-utils@gnu.org
+.SH "NOTES"
+This manual page was \fIAutoGen\fP-erated from the \fBshar\fP
+option definitions.
diff --git a/upstream/mageia-cauldron/man1/shasum.1 b/upstream/mageia-cauldron/man1/shasum.1
new file mode 100644
index 00000000..e47a9f8b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/shasum.1
@@ -0,0 +1,145 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "SHASUM 1"
+.TH SHASUM 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+shasum \- Print or Check SHA Checksums
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\& Usage: shasum [OPTION]... [FILE]...
+\& Print or check SHA checksums.
+\& With no FILE, or when FILE is \-, read standard input.
+\&
+\&   \-a, \-\-algorithm   1 (default), 224, 256, 384, 512, 512224, 512256
+\&   \-b, \-\-binary      read in binary mode
+\&   \-c, \-\-check       read SHA sums from the FILEs and check them
+\&       \-\-tag         create a BSD\-style checksum
+\&   \-t, \-\-text        read in text mode (default)
+\&   \-U, \-\-UNIVERSAL   read in Universal Newlines mode
+\&                         produces same digest on Windows/Unix/Mac
+\&   \-0, \-\-01          read in BITS mode
+\&                         ASCII \*(Aq0\*(Aq interpreted as 0\-bit,
+\&                         ASCII \*(Aq1\*(Aq interpreted as 1\-bit,
+\&                         all other characters ignored
+\&
+\& The following five options are useful only when verifying checksums:
+\&       \-\-ignore\-missing  don\*(Aqt fail or report status for missing files
+\&   \-q, \-\-quiet           don\*(Aqt print OK for each successfully verified file
+\&   \-s, \-\-status          don\*(Aqt output anything, status code shows success
+\&       \-\-strict          exit non\-zero for improperly formatted checksum lines
+\&   \-w, \-\-warn            warn about improperly formatted checksum lines
+\&
+\&   \-h, \-\-help        display this help and exit
+\&   \-v, \-\-version     output version information and exit
+\&
+\& When verifying SHA\-512/224 or SHA\-512/256 checksums, indicate the
+\& algorithm explicitly using the \-a option, e.g.
+\&
+\&   shasum \-a 512224 \-c checksumfile
+\&
+\& The sums are computed as described in FIPS PUB 180\-4.  When checking,
+\& the input should be a former output of this program.  The default
+\& mode is to print a line with checksum, a character indicating type
+\& (\`*\*(Aq for binary, \` \*(Aq for text, \`U\*(Aq for UNIVERSAL, \`^\*(Aq for BITS),
+\& and name for each FILE.  The line starts with a \`\e\*(Aq character if the
+\& FILE name contains either newlines or backslashes, which are then
+\& replaced by the two\-character sequences \`\en\*(Aq and \`\e\e\*(Aq respectively.
+\&
+\& Report shasum bugs to mshelor@cpan.org
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Running \fIshasum\fR is often the quickest way to compute SHA message
+digests.  The user simply feeds data to the script through files or
+standard input, and then collects the results from standard output.
+.PP
+The following command shows how to compute digests for typical inputs
+such as the NIST test vector "abc":
+.PP
+.Vb 1
+\&        perl \-e "print qq(abc)" | shasum
+.Ve
+.PP
+Or, if you want to use SHA\-256 instead of the default SHA\-1, simply say:
+.PP
+.Vb 1
+\&        perl \-e "print qq(abc)" | shasum \-a 256
+.Ve
+.PP
+Since \fIshasum\fR mimics the behavior of the combined GNU \fIsha1sum\fR,
+\&\fIsha224sum\fR, \fIsha256sum\fR, \fIsha384sum\fR, and \fIsha512sum\fR programs,
+you can install this script as a convenient drop-in replacement.
+.PP
+Unlike the GNU programs, \fIshasum\fR encompasses the full SHA standard by
+allowing partial-byte inputs.  This is accomplished through the BITS
+option (\fI\-0\fR).  The following example computes the SHA\-224 digest of
+the 7\-bit message \fI0001100\fR:
+.PP
+.Vb 1
+\&        perl \-e "print qq(0001100)" | shasum \-0 \-a 224
+.Ve
+.SH AUTHOR
+.IX Header "AUTHOR"
+Copyright (C) 2003\-2023 Mark Shelor <mshelor@cpan.org>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIshasum\fR is implemented using the Perl module Digest::SHA.
diff --git a/upstream/mageia-cauldron/man1/showkey.1 b/upstream/mageia-cauldron/man1/showkey.1
new file mode 100644
index 00000000..ae7628b1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/showkey.1
@@ -0,0 +1,91 @@
+.\" @(#)showkey.1 1.1 980201 aeb
+.TH SHOWKEY 1 "1 Feb 1998" "kbd"
+.SH NAME
+showkey \- examine the codes sent by the keyboard
+.SH SYNOPSIS
+showkey [\-h|\-\-help] [\-a|\-\-ascii] [\-s|\-\-scancodes] [\-k|\-\-keycodes] [\-V|\-\-version]
+.SH DESCRIPTION
+.IX "showkey command" "" "\fLshowkey\fR command"  
+.LP
+.B showkey
+prints to standard output either the scan codes or the keycode
+or the `ascii' code of each key pressed.
+In the first two modes the program runs until 10 seconds have elapsed
+since the last key press or release event, or until it receives
+a suitable signal, like SIGTERM, from another process.
+In `ascii' mode the program terminates when the user types ^D.
+.LP
+When in scancode dump mode, 
+.B showkey
+prints in hexadecimal format each byte received from the keyboard to the
+standard output. A new line is printed when an interval of about 0.1
+seconds occurs between the bytes received, or when the internal receive
+buffer fills up. This can be used to determine roughly, what byte
+sequences the keyboard sends at once on a given key press. The scan code
+dumping mode is primarily intended for debugging the keyboard driver or
+other low level interfaces. As such it shouldn't be of much interest to
+the regular end-user. However, some modern keyboards have keys or buttons
+that produce scancodes to which the kernel does not associate a keycode,
+and, after finding out what these are, the user can assign keycodes with
+.BR setkeycodes (8).
+.LP
+When in the default keycode dump mode,
+.B showkey
+prints to the standard output the keycode number or each key pressed or
+released. The kind of the event, press or release, is also reported.
+Keycodes are numbers assigned by the kernel to each individual physical
+key. Every key has always only one associated keycode number, whether
+the keyboard sends single or multiple scan codes when pressing it. Using
+.B showkey
+in this mode, you can find out what numbers to use in your personalized
+keymap files.
+.LP
+When in `ascii' dump mode,
+.B showkey
+prints to the standard output the decimal, octal, and hexadecimal
+value(s) of the key pressed, according to he present keymap.
+.SH OPTIONS
+.TP
+\-h \-\-help
+.B showkey
+prints to the standard error output its version number, a compile
+option and a short usage message, then exits.
+.TP
+\-s \-\-scancodes
+Starts
+.B showkey
+in scan code dump mode.
+.TP
+\-k \-\-keycodes
+Starts
+.B showkey
+in keycode dump mode. This is the default, when no command line options
+are present.
+.TP
+\-a \-\-ascii
+Starts
+.B showkey
+in `ascii' dump mode.
+.TP
+\-V \-\-version
+.B showkey
+prints version number and exits.
+.SH "2.6 KERNELS"
+In 2.6 kernels key codes lie in the range 1-255, instead of 1-127.
+Key codes larger than 127 are returned as three bytes of which the
+low order 7 bits are: zero, bits 13-7, and bits 6-0 of the key code.
+The high order bits are: 0/1 for make/break, 1, 1.
+.LP
+In 2.6 kernels raw mode, or scancode mode, is not very raw at all.
+Scan codes are first translated to key codes, and when scancodes
+are desired, the key codes are translated back. Various transformations
+are involved, and there is no guarantee at all that the final result
+corresponds to what the keyboard hardware did send. So, if you want
+to know the scan codes sent by various keys it is better to boot a
+2.4 kernel. Since 2.6.9 there also is the boot option atkbd.softraw=0
+that tells the 2.6 kernel to return the actual scan codes.
+.SH "SEE ALSO"
+.BR loadkeys (1),
+.BR dumpkeys (1),
+.BR keymaps (5),
+.BR setkeycodes (8)
diff --git a/upstream/mageia-cauldron/man1/showrgb.1 b/upstream/mageia-cauldron/man1/showrgb.1
new file mode 100644
index 00000000..75841a9d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/showrgb.1
@@ -0,0 +1,45 @@
+.\" Copyright 1993, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH SHOWRGB 1 "rgb 1.1.0" "X Version 11"
+.SH NAME
+showrgb \- display an rgb color-name database
+.SH SYNOPSIS
+.B showrgb
+[
+.I database
+]
+.SH DESCRIPTION
+The
+.I showrgb
+program reads an rgb color-name database from a text file
+and converts it back to source form, printing the
+result to standard output.  The default
+database is the one that X was built with, and may be overridden on
+the command line.  Specify the database name without
+the \fI.txt\fP, \fI.pag\fP or \fI.dir\fP suffix.
+.SH FILES
+.TP 20
+.I /usr/share/X11/rgb
+default database.
diff --git a/upstream/mageia-cauldron/man1/shred.1 b/upstream/mageia-cauldron/man1/shred.1
new file mode 100644
index 00000000..1ac0d992
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/shred.1
@@ -0,0 +1,81 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHRED "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+shred \- overwrite a file to hide its contents, and optionally delete it
+.SH SYNOPSIS
+.B shred
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Overwrite the specified FILE(s) repeatedly, in order to make it harder
+for even very expensive hardware probing to recover the data.
+.PP
+If FILE is \-, shred standard output.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+change permissions to allow writing if necessary
+.TP
+\fB\-n\fR, \fB\-\-iterations\fR=\fI\,N\/\fR
+overwrite N times instead of the default (3)
+.TP
+\fB\-\-random\-source\fR=\fI\,FILE\/\fR
+get random bytes from FILE
+.TP
+\fB\-s\fR, \fB\-\-size\fR=\fI\,N\/\fR
+shred this many bytes (suffixes like K, M, G accepted)
+.TP
+\fB\-u\fR
+deallocate and remove file after overwriting
+.TP
+\fB\-\-remove\fR[=\fI\,HOW\/\fR]
+like \fB\-u\fR but give control on HOW to delete;  See below
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+show progress
+.TP
+\fB\-x\fR, \fB\-\-exact\fR
+do not round file sizes up to the next full block;
+.IP
+this is the default for non\-regular files
+.TP
+\fB\-z\fR, \fB\-\-zero\fR
+add a final overwrite with zeros to hide shredding
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Delete FILE(s) if \fB\-\-remove\fR (\fB\-u\fR) is specified.  The default is not to remove
+the files because it is common to operate on device files like \fI\,/dev/hda\/\fP,
+and those files usually should not be removed.
+The optional HOW parameter indicates how to remove a directory entry:
+\&'unlink' => use a standard unlink call.
+\&'wipe' => also first obfuscate bytes in the name.
+\&'wipesync' => also sync each obfuscated byte to the device.
+The default mode is 'wipesync', but note it can be expensive.
+.PP
+CAUTION: shred assumes the file system and hardware overwrite data in place.
+Although this is common, many platforms operate otherwise.  Also, backups
+and mirrors may contain unremovable copies that will let a shredded file
+be recovered later.  See the GNU coreutils manual for details.
+.SH AUTHOR
+Written by Colin Plumb.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/shred>
+.br
+or available locally via: info \(aq(coreutils) shred invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/shuf.1 b/upstream/mageia-cauldron/man1/shuf.1
new file mode 100644
index 00000000..6593cd4b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/shuf.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SHUF "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+shuf \- generate random permutations
+.SH SYNOPSIS
+.B shuf
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.br
+.B shuf
+\fI\,-e \/\fR[\fI\,OPTION\/\fR]... [\fI\,ARG\/\fR]...
+.br
+.B shuf
+\fI\,-i LO-HI \/\fR[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write a random permutation of the input lines to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-e\fR, \fB\-\-echo\fR
+treat each ARG as an input line
+.TP
+\fB\-i\fR, \fB\-\-input\-range\fR=\fI\,LO\-HI\/\fR
+treat each number LO through HI as an input line
+.TP
+\fB\-n\fR, \fB\-\-head\-count\fR=\fI\,COUNT\/\fR
+output at most COUNT lines
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write result to FILE instead of standard output
+.TP
+\fB\-\-random\-source\fR=\fI\,FILE\/\fR
+get random bytes from FILE
+.TP
+\fB\-r\fR, \fB\-\-repeat\fR
+output lines can be repeated
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Paul Eggert.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/shuf>
+.br
+or available locally via: info \(aq(coreutils) shuf invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sirtopnm.1 b/upstream/mageia-cauldron/man1/sirtopnm.1
new file mode 100644
index 00000000..79cbaee0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sirtopnm.1
@@ -0,0 +1,59 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sirtopnm User Manual" 0 "20 March 1991" "netpbm documentation"
+
+.SH NAME
+
+sirtopnm - convert a Solitaire file to PNM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsirtopnm\fP
+
+[\fIsirfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBsirtopnm\fP reads a Solitaire Image Recorder file as input and
+produces a PNM image as output.  The type of the output file depends
+on the input file - if it's an MGI TYPE 17 file, \fBsirtopnm\fP
+generates a PGM file.  If it's an MGI TYPE 11 file, \fBsirtopnm\fP
+generates PPM.  The program tells you which type it is writing.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBsirtopnm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtosir" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Marvin Landis.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sirtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/size.1 b/upstream/mageia-cauldron/man1/size.1
new file mode 100644
index 00000000..c6e64760
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/size.1
@@ -0,0 +1,312 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "SIZE 1"
+.TH SIZE 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+size \- list section sizes and total size of binary files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+size [\fB\-A\fR|\fB\-B\fR|\fB\-G\fR|\fB\-\-format=\fR\fIcompatibility\fR]
+     [\fB\-\-help\fR]
+     [\fB\-d\fR|\fB\-o\fR|\fB\-x\fR|\fB\-\-radix=\fR\fInumber\fR]
+     [\fB\-\-common\fR]
+     [\fB\-t\fR|\fB\-\-totals\fR]
+     [\fB\-\-target=\fR\fIbfdname\fR] [\fB\-V\fR|\fB\-\-version\fR]
+     [\fB\-f\fR]
+     [\fIobjfile\fR...]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \s-1GNU\s0 \fBsize\fR utility lists the section sizes and the total
+size for each of the binary files \fIobjfile\fR on its argument list.
+By default, one line of output is generated for each file or each
+module if the file is an archive.
+.PP
+\&\fIobjfile\fR... are the files to be examined.  If none are
+specified, the file \f(CW\*(C`a.out\*(C'\fR will be used instead.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The command-line options have the following meanings:
+.IP "\fB\-A\fR" 4
+.IX Item "-A"
+.PD 0
+.IP "\fB\-B\fR" 4
+.IX Item "-B"
+.IP "\fB\-G\fR" 4
+.IX Item "-G"
+.IP "\fB\-\-format=\fR\fIcompatibility\fR" 4
+.IX Item "--format=compatibility"
+.PD
+Using one of these options, you can choose whether the output from \s-1GNU\s0
+\&\fBsize\fR resembles output from System V \fBsize\fR (using \fB\-A\fR,
+or \fB\-\-format=sysv\fR), or Berkeley \fBsize\fR (using \fB\-B\fR, or
+\&\fB\-\-format=berkeley\fR).  The default is the one-line format similar to
+Berkeley's.  Alternatively, you can choose the \s-1GNU\s0 format output
+(using \fB\-G\fR, or \fB\-\-format=gnu\fR), this is similar to
+Berkeley's output format, but sizes are counted differently.
+.Sp
+Here is an example of the Berkeley (default) format of output from
+\&\fBsize\fR:
+.Sp
+.Vb 4
+\&        $ size \-\-format=Berkeley ranlib size
+\&           text    data     bss     dec     hex filename
+\&         294880   81920   11592  388392   5ed28 ranlib
+\&         294880   81920   11888  388688   5ee50 size
+.Ve
+.Sp
+The Berkeley style output counts read only data in the \f(CW\*(C`text\*(C'\fR
+column, not in the \f(CW\*(C`data\*(C'\fR column, the \f(CW\*(C`dec\*(C'\fR and \f(CW\*(C`hex\*(C'\fR
+columns both display the sum of the \f(CW\*(C`text\*(C'\fR, \f(CW\*(C`data\*(C'\fR, and
+\&\f(CW\*(C`bss\*(C'\fR columns in decimal and hexadecimal respectively.
+.Sp
+The \s-1GNU\s0 format counts read only data in the \f(CW\*(C`data\*(C'\fR column, not
+the \f(CW\*(C`text\*(C'\fR column, and only displays the sum of the \f(CW\*(C`text\*(C'\fR,
+\&\f(CW\*(C`data\*(C'\fR, and \f(CW\*(C`bss\*(C'\fR columns once, in the \f(CW\*(C`total\*(C'\fR column.
+The \fB\-\-radix\fR option can be used to change the number base for
+all columns.  Here is the same data displayed with \s-1GNU\s0 conventions:
+.Sp
+.Vb 4
+\&        $ size \-\-format=GNU ranlib size
+\&              text       data        bss      total filename
+\&            279880      96920      11592     388392 ranlib
+\&            279880      96920      11888     388688 size
+.Ve
+.Sp
+This is the same data, but displayed closer to System V conventions:
+.Sp
+.Vb 7
+\&        $ size \-\-format=SysV ranlib size
+\&        ranlib  :
+\&        section         size         addr
+\&        .text         294880         8192
+\&        .data          81920       303104
+\&        .bss           11592       385024
+\&        Total         388392
+\&        
+\&        
+\&        size  :
+\&        section         size         addr
+\&        .text         294880         8192
+\&        .data          81920       303104
+\&        .bss           11888       385024
+\&        Total         388688
+.Ve
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD 0
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.IP "\fB\-?\fR" 4
+.IX Item "-?"
+.PD
+Show a summary of acceptable arguments and options.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-o\fR" 4
+.IX Item "-o"
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.IP "\fB\-\-radix=\fR\fInumber\fR" 4
+.IX Item "--radix=number"
+.PD
+Using one of these options, you can control whether the size of each
+section is given in decimal (\fB\-d\fR, or \fB\-\-radix=10\fR); octal
+(\fB\-o\fR, or \fB\-\-radix=8\fR); or hexadecimal (\fB\-x\fR, or
+\&\fB\-\-radix=16\fR).  In \fB\-\-radix=\fR\fInumber\fR, only the three
+values (8, 10, 16) are supported.  The total size is always given in two
+radices; decimal and hexadecimal for \fB\-d\fR or \fB\-x\fR output, or
+octal and hexadecimal if you're using \fB\-o\fR.
+.IP "\fB\-\-common\fR" 4
+.IX Item "--common"
+Print total size of common symbols in each file.  When using Berkeley
+or \s-1GNU\s0 format these are included in the bss size.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+.PD 0
+.IP "\fB\-\-totals\fR" 4
+.IX Item "--totals"
+.PD
+Show totals of all objects listed (Berkeley or \s-1GNU\s0 format mode only).
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+Specify that the object-code format for \fIobjfile\fR is
+\&\fIbfdname\fR.  This option may not be necessary; \fBsize\fR can
+automatically recognize many formats.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Display the version number of \fBsize\fR.
+.IP "\fB\-f\fR" 4
+.IX Item "-f"
+Ignored.  This option is used by other versions of the \fBsize\fR
+program, but it is not supported by the \s-1GNU\s0 Binutils version.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBar\fR\|(1), \fBobjdump\fR\|(1), \fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/sldtoppm.1 b/upstream/mageia-cauldron/man1/sldtoppm.1
new file mode 100644
index 00000000..e426824a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sldtoppm.1
@@ -0,0 +1,187 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sldtoppm User Manual" 0 "10 October 1991" "netpbm documentation"
+
+.SH NAME
+
+sldtoppm - convert an AutoCAD slide file to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsldtoppm\fP
+[\fB-adjust\fP]
+[\fB-dir\fP]
+[{\fB-height\fP|\fB-ysize\fP} \fIs\fP]
+[\fB-info\fP]
+[{\fB-lib\fP|\fB-Lib\fP} \fIname\fP]
+[\fB-scale\fP \fIs\fP]
+[\fB-verbose\fP]
+[{\fB-width\fP|\fB-xsize\fP} \fIs\fP]
+[\fIslidefile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsldtoppm\fP reads an AutoCAD\*R slide file and outputs a PPM
+image.  If you don't specify \fIslidefile\fP, \fBsldtoppm\fP reads
+input from Standard Input.  \fBsldtoppm\fP uses the \fBppmdraw\fP
+library to convert the vector and polygon information in the slide
+file to a raster; see the file \fBppmdraw.h\fP for details on this
+package.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBsldtoppm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-adjust\fP
+If the display on which the slide file was created had non-square
+pixels, when you process the slide with \fBsldtoppm\fP and don't
+specify \fB-adjust\fP, \fBsldtoppm\fP issues the following warning;
+
+.RS
+Warning - pixels on source screen were non-square.
+.RE
+.sp
+Specifying \fB-adjust\fP will correct the image width to
+compensate.  Specifying the \fB-adjust\fP option causes
+\fBsldtoppm\fP to scale the width of the image so that pixels in the
+resulting PPM image are square (and hence circles appear as true
+circles, not ellipses).  The scaling is performed in the vector
+domain, before scan converting the objects.  The results are,
+therefore, superior in appearance to what you'd obtain were you to
+perform the equivalent scaling with \fBpamscale\fP after the bitmap
+had been created.
+
+.TP
+\fB-dir\fP
+The input is assumed to be an AutoCAD slide library file.  A
+directory listing each slide in the library is printed on standard
+error.
+
+.TP
+\fB-height\fP \fIsize\fP
+Scales the image in the vector domain so it is \fIsize\fP pixels
+in height.  If you don't specify \fB-width\fP or \fB-xsize\fP,
+\fBsldtoppm\fP adjusts the width to preserve the pixel aspect ratio.
+
+.TP
+\fB-info\fP
+Dump the slide file header on standard error, displaying the original
+screen size and aspect ratio among other information.
+
+.TP
+\fB-lib\fP \fIname\fP
+Extracts the slide with the given \fIname\fP from the slide
+library given as input.  \fBsldtoppm\fP converts the specified
+\fIname\fP to upper case.
+
+.TP
+\fB-Lib\fP\fI name\fP
+Extracts the slide with the given \fIname\fP from the slide
+library given as input.  \fBsldtoppm\fP uses \fIname\fP in the case
+specified; it does not convert it to upper case.
+
+.TP
+\fB-scale\fP \fIs\fP
+Scales the image by factor \fIs\fP, which may be any floating
+point value greater than zero.  \fBsldtoppm\fP does the scaling after
+aspect ratio adjustment, if any.  Since it does the scaling in the
+vector domain, before rasterisation, the results look much better than
+running the output of \fBsldtoppm\fP through \fBpamscale\fP.
+
+.TP
+\fB-verbose\fP
+Dumps the slide file header and lists every vector and polygon 
+to Standard Error.
+
+.TP
+\fB-width\fP \fIsize\fP
+Scales the image in the vector domain so it is \fIsize\fP pixels
+wide.  If you don't specify \fB-height\fP or \fB-ysize\fP,
+\fBsldtoppm\fP adjusts the height to preserve the pixel aspect ratio.
+
+.TP
+\fB-xsize\fP \fIsize\fP
+Scales the image in the vector domain so it is \fIsize\fP pixels
+wide.  If you don't specify \fB-height\fP or \fB-ysize\fP,
+\fBsldtoppm\fP adjusts the height to preserve the pixel aspect ratio.
+
+.TP
+\fB-ysize\fP \fIsize\fP
+Scales the image in the vector domain so it is \fIsize\fP pixels
+in height.  If you don't specify \fB-width\fP or \fB-xsize\fP,
+\fBsldtoppm\fP adjusts the width to preserve the pixel aspect ratio.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBsldtoppm\fP can convert only Level 2 slides.  Level 1 format
+has been obsolete since the advent of AutoCAD Release 9 in 1987, and
+was not portable across machine architectures.
+.PP
+Slide library items with names containing 8 bit (such as ISO) or 16
+bit (Kanji, for example) characters may not be found when chosen with
+the \fB-lib\fP option unless \fBsldtoppm\fP was built with character
+set conversion functions appropriate to the locale.  You can always
+retrieve slides from libraries regardless of the character set by
+using the \fB-Lib\fP option and specifying the precise name of
+library member.  Use the \fB-dir\fP option to list the slides in a
+library if you're unsure of the exact name.
+
+.UN seealso
+.SH SEE ALSO
+
+AutoCAD Reference Manual: \fISlide File Format\fP,
+.BR "pamscale" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+.nf
+John Walker
+Autodesk SA
+Avenue des Champs-Montants 14b
+CH-2074 MARIN
+Suisse/Schweiz/Svizzera/Svizra/Switzerland
+    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
+    \fBFax:\fP038/33 88 15
+    \fBVoice:\fP038/33 76 33
+
+.fi
+.PP
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+without any conditions or restrictions.  This software is provided
+"as is" without express or implied warranty.
+.PP
+AutoCAD and Autodesk are registered trademarks of Autodesk, Inc.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sldtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/sleep.1 b/upstream/mageia-cauldron/man1/sleep.1
new file mode 100644
index 00000000..9dd032e7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sleep.1
@@ -0,0 +1,42 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SLEEP "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sleep \- delay for a specified amount of time
+.SH SYNOPSIS
+.B sleep
+\fI\,NUMBER\/\fR[\fI\,SUFFIX\/\fR]...
+.br
+.B sleep
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Pause for NUMBER seconds.  SUFFIX may be 's' for seconds (the default),
+\&'m' for minutes, 'h' for hours or 'd' for days.  NUMBER need not be an
+integer.  Given two or more arguments, pause for the amount of time
+specified by the sum of their values.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Jim Meyering and Paul Eggert.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBsleep\fP(3)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sleep>
+.br
+or available locally via: info \(aq(coreutils) sleep invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/smbcontrol.1 b/upstream/mageia-cauldron/man1/smbcontrol.1
new file mode 100644
index 00000000..e3529b85
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/smbcontrol.1
@@ -0,0 +1,349 @@
+'\" t
+.\"     Title: smbcontrol
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/25/2024
+.\"    Manual: User Commands
+.\"    Source: Samba 4.19.5
+.\"  Language: English
+.\"
+.TH "SMBCONTROL" "1" "02/25/2024" "Samba 4\&.19\&.5" "User Commands"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+smbcontrol \- send messages to smbd, nmbd or winbindd processes
+.SH "SYNOPSIS"
+.HP \w'\ 'u
+smbcontrol [\-?|\-\-help] [\-\-usage] [\-t|\-\-timeout] [\-d|\-\-debuglevel=DEBUGLEVEL] [\-\-debug\-stdout] [\-\-configfile=CONFIGFILE] [\-\-option=name=value] [\-l|\-\-log\-basename=LOGFILEBASE] [\-\-leak\-report] [\-\-leak\-report\-full]
+.HP \w'\ 'u
+smbcontrol [destination] [message\-type] [parameter]
+.SH "DESCRIPTION"
+.PP
+This tool is part of the
+\fBsamba\fR(7)
+suite\&.
+.PP
+smbcontrol
+is a very small program, which sends messages to a
+\fBsmbd\fR(8), a
+\fBnmbd\fR(8), or a
+\fBwinbindd\fR(8)
+daemon running on the system\&.
+.SH "OPTIONS"
+.PP
+\-t|\-\-timeout
+.RS 4
+Set timeout to seconds\&.
+.RE
+.PP
+destination
+.RS 4
+One of
+\fInmbd\fR,
+\fIsmbd\fR,
+\fIwinbindd\fR
+or a process ID\&.
+.sp
+The
+\fIall\fR
+destination causes the message to "broadcast" to all running daemons including nmbd and winbind\&. This is a change for Samba 3\&.3, prior to this the parameter smbd used to do this\&.
+.sp
+The
+\fIsmbd\fR
+destination causes the message to be sent to the smbd daemon specified in the
+smbd\&.pid
+file\&.
+.sp
+The
+\fInmbd\fR
+destination causes the message to be sent to the nmbd daemon specified in the
+nmbd\&.pid
+file\&.
+.sp
+The
+\fIwinbindd\fR
+destination causes the message to be sent to the winbind daemon specified in the
+winbindd\&.pid
+file\&.
+.sp
+If a single process ID is given, the message is sent to only that process\&.
+.RE
+.PP
+message\-type
+.RS 4
+Type of message to send\&. See the section
+\fBMESSAGE\-TYPES\fR
+for details\&.
+.RE
+.PP
+parameters
+.RS 4
+any parameters required for the message\-type
+.RE
+.PP
+\-?|\-\-help
+.RS 4
+Print a summary of command line options\&.
+.RE
+.PP
+\-\-usage
+.RS 4
+Display brief usage message\&.
+.RE
+.PP
+\-d|\-\-debuglevel=DEBUGLEVEL
+.RS 4
+\fIlevel\fR
+is an integer from 0 to 10\&. The default value if this parameter is not specified is 1 for client applications\&.
+.sp
+The higher this value, the more detail will be logged to the log files about the activities of the server\&. At level 0, only critical errors and serious warnings will be logged\&. Level 1 is a reasonable level for day\-to\-day running \- it generates a small amount of information about operations carried out\&.
+.sp
+Levels above 1 will generate considerable amounts of log data, and should only be used when investigating a problem\&. Levels above 3 are designed for use only by developers and generate HUGE amounts of log data, most of which is extremely cryptic\&.
+.sp
+Note that specifying this parameter here will override the
+\m[blue]\fBlog level\fR\m[]
+parameter in the
+/etc/samba/smb\&.conf
+file\&.
+.RE
+.PP
+\-\-debug\-stdout
+.RS 4
+This will redirect debug output to STDOUT\&. By default all clients are logging to STDERR\&.
+.RE
+.PP
+\-\-configfile=<configuration file>
+.RS 4
+The file specified contains the configuration details required by the client\&. The information in this file can be general for client and server or only provide client specific like options such as
+\m[blue]\fBclient smb encrypt\fR\m[]\&. See
+/etc/samba/smb\&.conf
+for more information\&. The default configuration file name is determined at compile time\&.
+.RE
+.PP
+\-\-option=<name>=<value>
+.RS 4
+Set the
+\fBsmb.conf\fR(5)
+option "<name>" to value "<value>" from the command line\&. This overrides compiled\-in defaults and options read from the configuration file\&. If a name or a value includes a space, wrap whole \-\-option=name=value into quotes\&.
+.RE
+.PP
+\-l|\-\-log\-basename=logdirectory
+.RS 4
+Base directory name for log/debug files\&. The extension
+\fB"\&.progname"\fR
+will be appended (e\&.g\&. log\&.smbclient, log\&.smbd, etc\&.\&.\&.)\&. The log file is never removed by the client\&.
+.RE
+.PP
+\-\-leak\-report
+.RS 4
+Enable talloc leak reporting on exit\&.
+.RE
+.PP
+\-\-leak\-report\-full
+.RS 4
+Enable full talloc leak reporting on exit\&.
+.RE
+.PP
+\-V|\-\-version
+.RS 4
+Prints the program version number\&.
+.RE
+.SH "MESSAGE\-TYPES"
+.PP
+Available message types are:
+.PP
+close\-share
+.RS 4
+Order smbd to close the client connections to the named share\&. Note that this doesn\*(Aqt affect client connections to any other shares\&. This message\-type takes an argument of the share name for which client connections will be closed, or the "*" character which will close all currently open shares\&. This may be useful if you made changes to the access controls on the share\&. This message can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+close\-denied\-share
+.RS 4
+Behave like
+\fBclose\-share\fR, but don\*(Aqt disconnect users that are still allowed to access the share\&. It can safely be sent to all smbds after changing share access controls\&. It will only affect users who have been denied access since having connected initially\&. This message can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+debug
+.RS 4
+Set debug level to the value specified by the parameter\&. This can be sent to any of the destinations\&. If this message is sent to either the smbd or winbindd daemons, the parent process will rebroadcast the message to all child processes changing the debug level in each one\&.
+.RE
+.PP
+kill\-client\-ip
+.RS 4
+Order smbd to close the client connections from a given IP address\&. This message\-type takes an argument of the IP address from which client connections will be closed\&. This message can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+force\-election
+.RS 4
+This message causes the
+nmbd
+daemon to force a new browse master election\&.
+.RE
+.PP
+ping
+.RS 4
+Send specified number of "ping" messages and wait for the same number of reply "pong" messages\&. This can be sent to any of the destinations\&.
+.RE
+.PP
+profile
+.RS 4
+Change profile settings of a daemon, based on the parameter\&. The parameter can be "on" to turn on profile stats collection, "off" to turn off profile stats collection, "count" to enable only collection of count stats (time stats are disabled), and "flush" to zero the current profile stats\&. This can be sent to any smbd or nmbd destinations\&.
+.RE
+.PP
+debuglevel
+.RS 4
+Request debuglevel of a certain daemon and write it to stdout\&. This can be sent to any of the destinations\&.
+.RE
+.PP
+profilelevel
+.RS 4
+Request profilelevel of a certain daemon and write it to stdout\&. This can be sent to any smbd or nmbd destinations\&.
+.RE
+.PP
+printnotify
+.RS 4
+Order smbd to send a printer notify message to any Windows NT clients connected to a printer\&. This message\-type takes the following arguments:
+.PP
+queuepause printername
+.RS 4
+Send a queue pause change notify message to the printer specified\&.
+.RE
+.PP
+queueresume printername
+.RS 4
+Send a queue resume change notify message for the printer specified\&.
+.RE
+.PP
+jobpause printername unixjobid
+.RS 4
+Send a job pause change notify message for the printer and unix jobid specified\&.
+.RE
+.PP
+jobresume printername unixjobid
+.RS 4
+Send a job resume change notify message for the printer and unix jobid specified\&.
+.RE
+.PP
+jobdelete printername unixjobid
+.RS 4
+Send a job delete change notify message for the printer and unix jobid specified\&.
+.RE
+.sp
+Note that this message only sends notification that an event has occurred\&. It doesn\*(Aqt actually cause the event to happen\&.
+.sp
+This message can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+dmalloc\-mark
+.RS 4
+Set a mark for dmalloc\&. Can be sent to both smbd and nmbd\&. Only available if samba is built with dmalloc support\&.
+.RE
+.PP
+dmalloc\-log\-changed
+.RS 4
+Dump the pointers that have changed since the mark set by dmalloc\-mark\&. Can be sent to both smbd and nmbd\&. Only available if samba is built with dmalloc support\&.
+.RE
+.PP
+shutdown
+.RS 4
+Shut down specified daemon\&. Can be sent to both smbd and nmbd\&.
+.RE
+.PP
+pool\-usage
+.RS 4
+Print a human\-readable description of all talloc(pool) memory usage by the specified daemon/process\&. Available for both smbd and nmbd\&.
+.RE
+.PP
+ringbuf\-log
+.RS 4
+Fetch and print the ringbuf log\&. Requires
+\fIlogging = ringbuf\fR\&. Available for smbd, winbindd and nmbd\&.
+.RE
+.PP
+drvupgrade
+.RS 4
+Force clients of printers using specified driver to update their local version of the driver\&. Can only be sent to smbd\&.
+.RE
+.PP
+reload\-config
+.RS 4
+Force daemon to reload smb\&.conf configuration file\&. Can be sent to
+\fBsmbd\fR,
+\fBnmbd\fR, or
+\fBwinbindd\fR\&.
+.RE
+.PP
+reload\-printers
+.RS 4
+Force smbd to reload printers\&. Can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+idmap
+.RS 4
+Notify about changes of id mapping\&. Can be sent to
+\fBsmbd\fR
+or (not implemented yet)
+\fBwinbindd\fR\&.
+.PP
+flush [uid|gid]
+.RS 4
+Flush caches for sid <\-> gid and/or sid <\-> uid mapping\&.
+.RE
+.PP
+delete <ID>
+.RS 4
+Remove a mapping from cache\&. The mapping is given by <ID> which may either be a sid: S\-x\-\&.\&.\&., a gid: "GID number" or a uid: "UID number"\&.
+.RE
+.PP
+kill <ID>
+.RS 4
+Remove a mapping from cache\&. Terminate
+\fBsmbd\fR
+if the id is currently in use\&.
+.RE
+.RE
+.PP
+num\-children
+.RS 4
+Query the number of smbd child processes\&. This message can only be sent to
+\fBsmbd\fR\&.
+.RE
+.PP
+reload\-certs
+.RS 4
+Instruct the LDAP server of a Samba AD DC to reload the TLS certificates protecting ldaps:// connections\&. This message can only be sent to
+\fBldap_server\fR\&.
+.RE
+.SH "VERSION"
+.PP
+This man page is part of version 4\&.19\&.5 of the Samba suite\&.
+.SH "SEE ALSO"
+.PP
+\fBnmbd\fR(8)
+and
+\fBsmbd\fR(8)\&.
+.SH "AUTHOR"
+.PP
+The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
diff --git a/upstream/mageia-cauldron/man1/smime_keys.1 b/upstream/mageia-cauldron/man1/smime_keys.1
new file mode 100644
index 00000000..ca92b34b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/smime_keys.1
@@ -0,0 +1,73 @@
+.\" -*-nroff-*-
+.\"
+.\"
+.\"     Copyright (C) 2001,2002 Oliver Ehli <elmy@acm.org>
+.\"     Copyright (C) 2001 Mike Schiraldi <raldi@research.netsol.com>
+.\"     Copyright (C) 2003 Bjoern Jacke <bjoern@j3e.de>
+.\"     Copyright (C) 2015 Kevin J. McCarthy <kevin@8t8.us>
+.\"
+.\"     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 2 of the License, or
+.\"     (at your option) any later version.
+.\"
+.\"     This program is distributed in the hope that it will be useful,
+.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"     GNU General Public License for more details.
+.\"
+.\"     You should have received a copy of the GNU General Public License
+.\"     along with this program; if not, write to the Free Software
+.\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+.\"
+.TH smime_keys 1 "September 19, 2020" Unix "User Manuals"
+.SH "NAME"
+smime_keys \- Utility to add S/MIME certificate to the internal database used by mutt
+.SH SYNOPSIS
+.PP
+.B smime_keys
+<operation>  [file(s) | keyID [file(s)]]
+.SH "DESCRIPTION"
+The purpose of this tool is to manipulate the internal database of S/MIME certificates
+used by mutt to sign mail messages which will be sent or to verify mail messages received
+and signed with S/MIME.
+.SH OPTIONS
+.PP
+.IP \fBinit\fP
+no files needed, inits directory structure.
+.IP \fBrefresh\fP
+no files needed. refreshes index files, including
+trust flag/expiration.
+.IP \fBlist\fP
+lists the certificates stored in database.
+.IP \fBlabel\fP
+keyID required. changes/removes/adds label.
+.IP \fBremove\fP
+keyID required.
+.IP \fBverify\fP
+1=keyID and optionally 2=CRL.
+Verifies the certificate chain, and optionally whether
+this certificate is included in supplied CRL (PEM format).
+Note: to verify all certificates at the same time,
+replace keyID with "all".
+.IP \fBadd_cert\fP
+certificate required.
+.IP \fBadd_chain\fP
+three files reqd: 1=Key, 2=certificate
+plus 3=intermediate certificate(s).
+.IP \fBadd_p12\fP
+one file reqd. Adds keypair to database.
+file is PKCS12 (e.g. export from netscape).
+.IP \fBadd_pem\fP
+one file reqd. Adds keypair to database.
+(file was converted from e.g. PKCS12).
+.IP \fBadd_root\fP
+one file reqd. Adds PEM root certificate to the location
+specified within muttrc (smime_verify_* command).
+.SH NO WARRANTIES
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+.PP
+Mutt Home Page: http://www.mutt.org/
diff --git a/upstream/mageia-cauldron/man1/soelim.1 b/upstream/mageia-cauldron/man1/soelim.1
new file mode 100644
index 00000000..e51209f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/soelim.1
@@ -0,0 +1,283 @@
+'\" p
+.TH SOELIM 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+soelim \- interpret .so requests in groff input
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr soelim_C \n[.C]
+.cp 0
+.mso pic.tmac
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY soelim
+.OP \-Crtv
+.OP \-I dir
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B soelim
+reads
+.I files
+and replaces lines of the form
+.IP
+.BI .so\~ file
+.LP
+by the contents of
+.IR file .
+.
+It is useful if files included with
+.B .so
+need to be preprocessed.
+.
+Normally,
+.B soelim
+should be invoked with the
+.B \-s
+option of
+.BR groff .
+.
+.
+.PP
+To embed \[oq]\[rs]\[cq] in the file name, write \[oq]\[rs]\[rs]\[cq]
+or \[oq]\[rs]e\[cq].
+.
+To embed a space, write \[oq]\[rs]\ \[cq].
+.
+Any other escape sequence in
+.I file
+makes
+.B soelim
+ignore the whole line.
+.
+.
+.PP
+Note that there must be no whitespace between the leading dot and the two
+characters \[oq]s\[cq] and \[oq]o\[cq].
+.
+Otherwise, only
+.B groff
+interprets the
+.B .so
+request (and
+.B soelim
+ignores it).
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-C
+Recognize
+.B .so
+even when followed by a character other than space or newline.
+.
+.TP
+.BI \-I dir
+This option may be used to add a directory to the search path for
+files (both those on the command line and those named in
+.B .so
+requests).
+.
+The search path is initialized with the current directory.
+.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+.
+If you want to make the current directory be read before other
+directories, add
+.B \-I.\&
+at the appropriate place.
+.
+.IP
+No directory search is performed for files with an absolute file name.
+.
+.TP
+.B \-r
+Do not add
+.B .lf
+requests (for general use, with non-groff files).
+.
+.TP
+.B \-t
+Don't emit
+.B .lf
+requests but TeX comment lines (starting with \[oq]%\[cq]) giving the
+current file and line number.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.\" ====================================================================
+.SH USAGE
+.\" ====================================================================
+.
+The normal processing sequence of groff is this:
+.
+.
+.PP
+.ie t \{\
+.PS
+.ps 10
+.vs 12
+box invisible width 0.5 height 0.4 "input" "file";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.8 height 0.2 "preprocessor";
+move to last box .right
+right;
+arrow 0.3;
+A: box invisible width 0.35 height 0.2 "troff";
+move to last box .top;
+up;
+move 0.3;
+box invisible width 0.6 height 0.4 "sourced" "file";
+line <- up 0.3 from A.top;
+move to A.right;
+right;
+arrow 0.3;
+box invisible width 0.85 height 0.2 "postprocessor";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
+.PE
+.\}
+.el \{\
+.nf
+          input        sourced
+          file          file
+            |             |
+            v             v
+        preprocessor -> troff -> postprocessor
+                                      |
+                                      v
+                                   output
+                                    file
+.fi
+.\}
+.PP
+.
+That is, files sourced with
+.B .so
+are normally read
+.I only
+by
+.B troff
+(the actual formatter).
+.
+.B soelim
+is
+.I not
+required for
+.B troff
+to source files.
+.
+.
+.PP
+If a file to be sourced should also be preprocessed, it must already be read
+.I before
+the input file passes through the preprocessor.
+.
+This is handled by
+.BR soelim :
+.
+.PP
+.ie t \{\
+.PS
+.ps 10
+.vs 12
+box invisible width 0.5 height 0.4 "input" "file";
+move to last box .bottom;
+down;
+arrow 0.3;
+A: box invisible width 0.5 height 0.2 "soelim";
+line <- 0.3;
+box invisible width 0.5 height 0.4 "sourced" "file";
+move to A.right;
+right;
+arrow 0.3;
+box invisible width 0.8 height 0.2 "preprocessor";
+arrow 0.3;
+box invisible width 0.35 height 0.2 "troff";
+arrow 0.3
+box invisible width 0.85 height 0.2 "postprocessor";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
+.PE
+.\}
+.el \{\
+.nf
+          input
+          file
+            |
+            v
+          soelim -> preprocessor -> troff -> postprocessor
+            ^                                     |
+            |                                     v
+         sourced                               output
+          file                                  file
+.fi
+.\}
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR groff (1)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[soelim_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/sort.1 b/upstream/mageia-cauldron/man1/sort.1
new file mode 100644
index 00000000..b5ec4766
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sort.1
@@ -0,0 +1,158 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SORT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sort \- sort lines of text files
+.SH SYNOPSIS
+.B sort
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.br
+.B sort
+[\fI\,OPTION\/\fR]... \fI\,--files0-from=F\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write sorted concatenation of all FILE(s) to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+Ordering options:
+.TP
+\fB\-b\fR, \fB\-\-ignore\-leading\-blanks\fR
+ignore leading blanks
+.TP
+\fB\-d\fR, \fB\-\-dictionary\-order\fR
+consider only blanks and alphanumeric characters
+.TP
+\fB\-f\fR, \fB\-\-ignore\-case\fR
+fold lower case to upper case characters
+.TP
+\fB\-g\fR, \fB\-\-general\-numeric\-sort\fR
+compare according to general numerical value
+.TP
+\fB\-i\fR, \fB\-\-ignore\-nonprinting\fR
+consider only printable characters
+.TP
+\fB\-M\fR, \fB\-\-month\-sort\fR
+compare (unknown) < 'JAN' < ... < 'DEC'
+.TP
+\fB\-h\fR, \fB\-\-human\-numeric\-sort\fR
+compare human readable numbers (e.g., 2K 1G)
+.TP
+\fB\-n\fR, \fB\-\-numeric\-sort\fR
+compare according to string numerical value
+.TP
+\fB\-R\fR, \fB\-\-random\-sort\fR
+shuffle, but group identical keys.  See \fBshuf\fP(1)
+.TP
+\fB\-\-random\-source\fR=\fI\,FILE\/\fR
+get random bytes from FILE
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse the result of comparisons
+.TP
+\fB\-\-sort\fR=\fI\,WORD\/\fR
+sort according to WORD:
+general\-numeric \fB\-g\fR, human\-numeric \fB\-h\fR, month \fB\-M\fR,
+numeric \fB\-n\fR, random \fB\-R\fR, version \fB\-V\fR
+.TP
+\fB\-V\fR, \fB\-\-version\-sort\fR
+natural sort of (version) numbers within text
+.PP
+Other options:
+.TP
+\fB\-\-batch\-size\fR=\fI\,NMERGE\/\fR
+merge at most NMERGE inputs at once;
+for more use temp files
+.TP
+\fB\-c\fR, \fB\-\-check\fR, \fB\-\-check\fR=\fI\,diagnose\-first\/\fR
+check for sorted input; do not sort
+.TP
+\fB\-C\fR, \fB\-\-check\fR=\fI\,quiet\/\fR, \fB\-\-check\fR=\fI\,silent\/\fR
+like \fB\-c\fR, but do not report first bad line
+.TP
+\fB\-\-compress\-program\fR=\fI\,PROG\/\fR
+compress temporaries with PROG;
+decompress them with PROG \fB\-d\fR
+.TP
+\fB\-\-debug\fR
+annotate the part of the line used to sort,
+and warn about questionable usage to stderr
+.TP
+\fB\-\-files0\-from\fR=\fI\,F\/\fR
+read input from the files specified by
+NUL\-terminated names in file F;
+If F is \- then read names from standard input
+.TP
+\fB\-k\fR, \fB\-\-key\fR=\fI\,KEYDEF\/\fR
+sort via a key; KEYDEF gives location and type
+.TP
+\fB\-m\fR, \fB\-\-merge\fR
+merge already sorted files; do not sort
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write result to FILE instead of standard output
+.TP
+\fB\-s\fR, \fB\-\-stable\fR
+stabilize sort by disabling last\-resort comparison
+.TP
+\fB\-S\fR, \fB\-\-buffer\-size\fR=\fI\,SIZE\/\fR
+use SIZE for main memory buffer
+.TP
+\fB\-t\fR, \fB\-\-field\-separator\fR=\fI\,SEP\/\fR
+use SEP instead of non\-blank to blank transition
+.TP
+\fB\-T\fR, \fB\-\-temporary\-directory\fR=\fI\,DIR\/\fR
+use DIR for temporaries, not $TMPDIR or \fI\,/tmp\/\fP;
+multiple options specify multiple directories
+.TP
+\fB\-\-parallel\fR=\fI\,N\/\fR
+change the number of sorts run concurrently to N
+.TP
+\fB\-u\fR, \fB\-\-unique\fR
+with \fB\-c\fR, check for strict ordering;
+without \fB\-c\fR, output only the first of an equal run
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+KEYDEF is F[.C][OPTS][,F[.C][OPTS]] for start and stop position, where F is a
+field number and C a character position in the field; both are origin 1, and
+the stop position defaults to the line's end.  If neither \fB\-t\fR nor \fB\-b\fR is in
+effect, characters in a field are counted from the beginning of the preceding
+whitespace.  OPTS is one or more single\-letter ordering options [bdfgiMhnRrV],
+which override global ordering options for that key.  If no key is given, use
+the entire line as the key.  Use \fB\-\-debug\fR to diagnose incorrect key usage.
+.PP
+SIZE may be followed by the following multiplicative suffixes:
+% 1% of memory, b 1, K 1024 (default), and so on for M, G, T, P, E, Z, Y.
+.PP
+*** WARNING ***
+The locale specified by the environment affects sort order.
+Set LC_ALL=C to get the traditional sort order that uses
+native byte values.
+.SH AUTHOR
+Written by Mike Haertel and Paul Eggert.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBshuf\fP(1), \fBuniq\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sort>
+.br
+or available locally via: info \(aq(coreutils) sort invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/spctoppm.1 b/upstream/mageia-cauldron/man1/spctoppm.1
new file mode 100644
index 00000000..c1b37fe6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/spctoppm.1
@@ -0,0 +1,56 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Spctoppm User Manual" 0 "19 July 1990" "netpbm documentation"
+
+.SH NAME
+
+spctoppm - convert an Atari compressed Spectrum file to a PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBspctoppm\fP
+
+[\fIspcfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBspctoppm\fP reads an Atari compressed Spectrum file as input
+and produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBspctoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "sputoppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/spctoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/splain.1 b/upstream/mageia-cauldron/man1/splain.1
new file mode 100644
index 00000000..709d5726
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/splain.1
@@ -0,0 +1,256 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "SPLAIN 1"
+.TH SPLAIN 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+diagnostics, splain \- produce verbose warning diagnostics
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+Using the \f(CW\*(C`diagnostics\*(C'\fR pragma:
+.PP
+.Vb 2
+\&    use diagnostics;
+\&    use diagnostics \-verbose;
+\&
+\&    enable  diagnostics;
+\&    disable diagnostics;
+.Ve
+.PP
+Using the \f(CW\*(C`splain\*(C'\fR standalone filter program:
+.PP
+.Vb 2
+\&    perl program 2>diag.out
+\&    splain [\-v] [\-p] diag.out
+.Ve
+.PP
+Using diagnostics to get stack traces from a misbehaving script:
+.PP
+.Vb 1
+\&    perl \-Mdiagnostics=\-traceonly my_script.pl
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.ie n .SS "The ""diagnostics"" Pragma"
+.el .SS "The \f(CWdiagnostics\fP Pragma"
+.IX Subsection "The diagnostics Pragma"
+This module extends the terse diagnostics normally emitted by both the
+perl compiler and the perl interpreter (from running perl with a \-w 
+switch or \f(CW\*(C`use warnings\*(C'\fR), augmenting them with the more
+explicative and endearing descriptions found in perldiag.  Like the
+other pragmata, it affects the compilation phase of your program rather
+than merely the execution phase.
+.PP
+To use in your program as a pragma, merely invoke
+.PP
+.Vb 1
+\&    use diagnostics;
+.Ve
+.PP
+at the start (or near the start) of your program.  (Note 
+that this \fIdoes\fR enable perl's \fB\-w\fR flag.)  Your whole
+compilation will then be subject(ed :\-) to the enhanced diagnostics.
+These still go out \fBSTDERR\fR.
+.PP
+Due to the interaction between runtime and compiletime issues,
+and because it's probably not a very good idea anyway,
+you may not use \f(CW\*(C`no diagnostics\*(C'\fR to turn them off at compiletime.
+However, you may control their behaviour at runtime using the 
+\&\fBdisable()\fR and \fBenable()\fR methods to turn them off and on respectively.
+.PP
+The \fB\-verbose\fR flag first prints out the perldiag introduction before
+any other diagnostics.  The \f(CW$diagnostics::PRETTY\fR variable can generate nicer
+escape sequences for pagers.
+.PP
+Warnings dispatched from perl itself (or more accurately, those that match
+descriptions found in perldiag) are only displayed once (no duplicate
+descriptions).  User code generated warnings a la \fBwarn()\fR are unaffected,
+allowing duplicate user messages to be displayed.
+.PP
+This module also adds a stack trace to the error message when perl dies.
+This is useful for pinpointing what
+caused the death.  The \fB\-traceonly\fR (or
+just \fB\-t\fR) flag turns off the explanations of warning messages leaving just
+the stack traces.  So if your script is dieing, run it again with
+.PP
+.Vb 1
+\&  perl \-Mdiagnostics=\-traceonly my_bad_script
+.Ve
+.PP
+to see the call stack at the time of death.  By supplying the \fB\-warntrace\fR
+(or just \fB\-w\fR) flag, any warnings emitted will also come with a stack
+trace.
+.SS "The \fIsplain\fP Program"
+.IX Subsection "The splain Program"
+Another program, \fIsplain\fR is actually nothing
+more than a link to the (executable) \fIdiagnostics.pm\fR module, as well as
+a link to the \fIdiagnostics.pod\fR documentation.  The \fB\-v\fR flag is like
+the \f(CW\*(C`use diagnostics \-verbose\*(C'\fR directive.
+The \fB\-p\fR flag is like the
+\&\f(CW$diagnostics::PRETTY\fR variable.  Since you're post-processing with 
+\&\fIsplain\fR, there's no sense in being able to \fBenable()\fR or \fBdisable()\fR processing.
+.PP
+Output from \fIsplain\fR is directed to \fBSTDOUT\fR, unlike the pragma.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+The following file is certain to trigger a few errors at both
+runtime and compiletime:
+.PP
+.Vb 8
+\&    use diagnostics;
+\&    print NOWHERE "nothing\en";
+\&    print STDERR "\en\etThis message should be unadorned.\en";
+\&    warn "\etThis is a user warning";
+\&    print "\enDIAGNOSTIC TESTER: Please enter a <CR> here: ";
+\&    my $a, $b = scalar <STDIN>;
+\&    print "\en";
+\&    print $x/$y;
+.Ve
+.PP
+If you prefer to run your program first and look at its problem
+afterwards, do this:
+.PP
+.Vb 2
+\&    perl \-w test.pl 2>test.out
+\&    ./splain < test.out
+.Ve
+.PP
+Note that this is not in general possible in shells of more dubious heritage, 
+as the theoretical
+.PP
+.Vb 2
+\&    (perl \-w test.pl >/dev/tty) >& test.out
+\&    ./splain < test.out
+.Ve
+.PP
+Because you just moved the existing \fBstdout\fR to somewhere else.
+.PP
+If you don't want to modify your source code, but still have on-the-fly
+warnings, do this:
+.PP
+.Vb 1
+\&    exec 3>&1; perl \-w test.pl 2>&1 1>&3 3>&\- | splain 1>&2 3>&\-
+.Ve
+.PP
+Nifty, eh?
+.PP
+If you want to control warnings on the fly, do something like this.
+Make sure you do the \f(CW\*(C`use\*(C'\fR first, or you won't be able to get
+at the \fBenable()\fR or \fBdisable()\fR methods.
+.PP
+.Vb 4
+\&    use diagnostics; # checks entire compilation phase 
+\&        print "\entime for 1st bogus diags: SQUAWKINGS\en";
+\&        print BOGUS1 \*(Aqnada\*(Aq;
+\&        print "done with 1st bogus\en";
+\&
+\&    disable diagnostics; # only turns off runtime warnings
+\&        print "\entime for 2nd bogus: (squelched)\en";
+\&        print BOGUS2 \*(Aqnada\*(Aq;
+\&        print "done with 2nd bogus\en";
+\&
+\&    enable diagnostics; # turns back on runtime warnings
+\&        print "\entime for 3rd bogus: SQUAWKINGS\en";
+\&        print BOGUS3 \*(Aqnada\*(Aq;
+\&        print "done with 3rd bogus\en";
+\&
+\&    disable diagnostics;
+\&        print "\entime for 4th bogus: (squelched)\en";
+\&        print BOGUS4 \*(Aqnada\*(Aq;
+\&        print "done with 4th bogus\en";
+.Ve
+.SH INTERNALS
+.IX Header "INTERNALS"
+Diagnostic messages derive from the \fIperldiag.pod\fR file when available at
+runtime.  Otherwise, they may be embedded in the file itself when the
+splain package is built.   See the \fIMakefile\fR for details.
+.PP
+If an extant \f(CW$SIG\fR{_\|_WARN_\|_} handler is discovered, it will continue
+to be honored, but only after the \fBdiagnostics::splainthis()\fR function 
+(the module's \f(CW$SIG\fR{_\|_WARN_\|_} interceptor) has had its way with your
+warnings.
+.PP
+There is a \f(CW$diagnostics::DEBUG\fR variable you may set if you're desperately
+curious what sorts of things are being intercepted.
+.PP
+.Vb 1
+\&    BEGIN { $diagnostics::DEBUG = 1 }
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+Not being able to say "no diagnostics" is annoying, but may not be
+insurmountable.
+.PP
+The \f(CW\*(C`\-pretty\*(C'\fR directive is called too late to affect matters.
+You have to do this instead, and \fIbefore\fR you load the module.
+.PP
+.Vb 1
+\&    BEGIN { $diagnostics::PRETTY = 1 }
+.Ve
+.PP
+I could start up faster by delaying compilation until it should be
+needed, but this gets a "panic: top_level" when using the pragma form
+in Perl 5.001e.
+.PP
+While it's true that this documentation is somewhat subserious, if you use
+a program named \fIsplain\fR, you should expect a bit of whimsy.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen <\fItchrist@mox.perl.com\fR>, 25 June 1995.
diff --git a/upstream/mageia-cauldron/man1/split.1 b/upstream/mageia-cauldron/man1/split.1
new file mode 100644
index 00000000..f905c471
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/split.1
@@ -0,0 +1,108 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SPLIT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+split \- split a file into pieces
+.SH SYNOPSIS
+.B split
+[\fI\,OPTION\/\fR]... [\fI\,FILE \/\fR[\fI\,PREFIX\/\fR]]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output pieces of FILE to PREFIXaa, PREFIXab, ...;
+default size is 1000 lines, and default PREFIX is 'x'.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-suffix\-length\fR=\fI\,N\/\fR
+generate suffixes of length N (default 2)
+.TP
+\fB\-\-additional\-suffix\fR=\fI\,SUFFIX\/\fR
+append an additional SUFFIX to file names
+.TP
+\fB\-b\fR, \fB\-\-bytes\fR=\fI\,SIZE\/\fR
+put SIZE bytes per output file
+.TP
+\fB\-C\fR, \fB\-\-line\-bytes\fR=\fI\,SIZE\/\fR
+put at most SIZE bytes of records per output file
+.TP
+\fB\-d\fR
+use numeric suffixes starting at 0, not alphabetic
+.TP
+\fB\-\-numeric\-suffixes\fR[=\fI\,FROM\/\fR]
+same as \fB\-d\fR, but allow setting the start value
+.TP
+\fB\-x\fR
+use hex suffixes starting at 0, not alphabetic
+.TP
+\fB\-\-hex\-suffixes\fR[=\fI\,FROM\/\fR]
+same as \fB\-x\fR, but allow setting the start value
+.TP
+\fB\-e\fR, \fB\-\-elide\-empty\-files\fR
+do not generate empty output files with '\-n'
+.TP
+\fB\-\-filter\fR=\fI\,COMMAND\/\fR
+write to shell COMMAND; file name is $FILE
+.TP
+\fB\-l\fR, \fB\-\-lines\fR=\fI\,NUMBER\/\fR
+put NUMBER lines/records per output file
+.TP
+\fB\-n\fR, \fB\-\-number\fR=\fI\,CHUNKS\/\fR
+generate CHUNKS output files; see explanation below
+.TP
+\fB\-t\fR, \fB\-\-separator\fR=\fI\,SEP\/\fR
+use SEP instead of newline as the record separator;
+\&'\e0' (zero) specifies the NUL character
+.TP
+\fB\-u\fR, \fB\-\-unbuffered\fR
+immediately copy input to output with '\-n r/...'
+.TP
+\fB\-\-verbose\fR
+print a diagnostic just before each
+output file is opened
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.SS "CHUNKS may be:"
+.TP
+N
+split into N files based on size of input
+.TP
+K/N
+output Kth of N to stdout
+.TP
+l/N
+split into N files without splitting lines/records
+.TP
+l/K/N
+output Kth of N to stdout without splitting lines/records
+.TP
+r/N
+like 'l' but use round robin distribution
+.TP
+r/K/N
+likewise but only output Kth of N to stdout
+.SH AUTHOR
+Written by Torbjorn Granlund and Richard M. Stallman.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/split>
+.br
+or available locally via: info \(aq(coreutils) split invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/spottopgm.1 b/upstream/mageia-cauldron/man1/spottopgm.1
new file mode 100644
index 00000000..2b169e53
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/spottopgm.1
@@ -0,0 +1,101 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Spottopgm User Manual" 0 "22 July 2004" "netpbm documentation"
+
+.SH NAME
+
+spottopgm - convert SPOT satellite images to a PGM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBspottopgm\fP 
+[\fB-1\fP|\fB-2\fP|\fB-3\fP] 
+[\fIFirstcol\fP \fIFirstline\fP \fILastcol\fP \fILastline\fP] 
+\fIinputfile\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBspottopgm\fP converts the named \fBinputfile\fP to PGM format,
+defaulting to the first color and the whole SPOT image unless
+you specify otherwise with the options.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBspottopgm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-1\fP
+.TP
+\fB-2\fP
+.TP
+\fB-3\fP
+Extract the given color from the SPOT image.  The colors are
+infrared, visible light, and ultraviolet, although I don't know which
+corresponds to which number.  If the image is in color,
+\fBspottopgm\fP announces this on Standard Error.  The default color
+is 1.
+
+
+
+.UN parameters
+.SH PARAMETERS
+
+
+.TP
+\fIFirstcol Firstline Lastcol Lastline\fP
+Extract the specified rectangle from the SPOT image.  Most SPOT
+images are 3000 lines long and 3000 or more columns
+wide. Unfortunately, the SPOT format only gives the width and not the
+length.  The width is printed on standard error.  The default
+rectangle is the width of the input image by 3000 lines.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBspottopgm\fP doesn't determine the length of the input file;
+this would involve two passes over the input file.  It defaults to
+3000 lines instead.
+.PP
+\fBspottopgm\fP could extract a three-color image (as a PPM), but
+I didn't feel like making the program more complicated than it is now.
+Besides, there is no one-to-one correspondence between red, green,
+blue and infrared, visible and ultraviolet.
+.PP
+I've had only a limited number of SPOT images to play with, and
+therefore wouldn't guarantee that this will work on any other images.
+
+.UN author
+.SH AUTHOR
+
+Warren Toomey \fIwkt@csadfa.cs.adfa.oz.au\fP
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pgm" (1)\c
+\&
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/spottopgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/sputoppm.1 b/upstream/mageia-cauldron/man1/sputoppm.1
new file mode 100644
index 00000000..ae16e9c4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sputoppm.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sputoppm User Manual" 0 "19 July 1990" "netpbm documentation"
+
+.SH NAME
+
+sputoppm - convert an Atari uncompressed Spectrum file to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsputoppm\fP
+
+[\fIspufile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsputoppm\fP reads an Atari uncompressed Spectrum file as input
+and produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBsputoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtospu" (1)\c
+\&, 
+.BR "spctoppm" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1991 by Steve Belczyk (\fIseb3@gte.com\fP) and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sputoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/srftopam.1 b/upstream/mageia-cauldron/man1/srftopam.1
new file mode 100644
index 00000000..e9c339d3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/srftopam.1
@@ -0,0 +1,91 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Srftopam User Manual" 0 "27 May 2011" "netpbm documentation"
+
+.SH NAME
+srftopam - convert a SRF image file to Netpbm images
+
+
+.UN synopsis
+.SH SYNOPSIS
+.PP
+\fBsrftopam\fP
+[\fB-verbose\fP]
+[\fInetpbmfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsrftopam\fP reads a SRF image file as input and produces a
+multi-image stream of PAM images as output.
+.PP
+This program performs the inverse of the conversion that \fBpamtosrf\fP
+does.  See that program's manual for more information about SRF and
+the relationship between the SRF and Netpbm representation of the
+images.
+.PP
+\fInetpbmfile\fP is the input stream, which defaults to Standard Input.
+Output is always on Standard Output.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBsrftopam\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-verbose\fP
+Issue informational messages about the input and the conversion process.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "pamtosrf" (1)\c
+\&
+.IP \(bu
+
+.BR "pamdice" (1)\c
+\&
+.IP \(bu
+
+.BR "pamsplit" (1)\c
+\&
+.IP \(bu
+
+.BR "pam" (1)\c
+\&
+  
+
+.UN history
+.SH HISTORY
+.PP
+\fBsrftopam\fP was new in Netpbm 10.55 (June 2011).
+.PP
+It was contributed by Mike Frysinger.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/srftopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/ssconvert.1 b/upstream/mageia-cauldron/man1/ssconvert.1
new file mode 100644
index 00000000..ad3b2c64
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssconvert.1
@@ -0,0 +1,424 @@
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH SSCONVERT 1 "2020-04-19" "gnumeric" "GNOME"
+.SH NAME
+ssconvert \- a command line spreadsheet format converter
+
+.SH SYNOPSIS
+\fBssconvert\fR [\fIOPTIONS\fR] \fIinfile\fR \fIoutfile\fR
+.P
+\fBssconvert\fR [\fIOPTIONS\fR] \fB\-\-merge\-to\fR \fIoutfile\fR \fIinfile1\fR \fIinfile2\fR \fB...\fR
+
+.SH DESCRIPTION
+\fBssconvert\fR is a command line utility to convert spreadsheet files
+between various spreadsheet file formats. It is a companion utility to
+\fBGnumeric\fR, the powerful spreadsheet program created by the GNOME
+project.
+
+\fBssconvert\fR accepts either file names or URIs as \fIinfile\fR
+\fIoutfile\fR. The special URIs \fIfd://0\fR and \fIfd://1\fR can be
+used for standard input and standard output respectively.
+
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with single
+letter options starting with a single dash (`-') and longer options
+starting with two dashes (`--').
+
+.SS "Main options"
+.TP
+.B \-\-recalc
+Recalculate all cells before writing the result.
+.TP
+.B \-\-set \fICELL=CONTENTS\fR
+Set the value of \fICELL\fR to \fICONTENTS\fR.  To
+put an expression in a cell, add an extra =, for example \-\-set "A11==A10+1".
+This option may be repeated as many times as needed.  The workbook will be
+recalculated after all cells have been set, provided that the workbook is
+set for automatic recalculation.  If not, recalculation can be forced
+with \-\-recalc.
+.TP
+.B \-v, \-\-verbose
+Be slightly more verbose about what is going on.
+.TP
+.B \-\-list\-exporters
+List the available exporters (file formats that can be written).
+.TP
+.B \-T, \-\-export\-type=\fIID\fR
+Specify which exporter to use; see below for a list. This is only
+necessary when the right format does not follow from the output file
+name.  The list of available export formats can be generated using the
+\-\-list\-exporters option.  However, when image export is requested
+using the \-\-export\-graphs option, the list of image formats should be
+consulted instead.  That list can be generated using the
+\-\-list\-image\-formats option.
+.TP
+.B \-O, \-\-export\-options=\fIoptionsstring\fR
+Specify parameters for the chosen exporter.
+\fIoptionsstring\fR is a list of \fIparameter\fR=\fIvalue\fR pairs, separated
+by spaces.
+The parameter names and values allowed are specific to the exporter and are
+documented below. Multiple parameters can be specified
+.TP
+.B \-\-export\-graphs
+Export the graphs (or charts) inside the input spreadsheet to
+numbered image files (SVG by default).  The list of available image
+formats can be printed with \-\-list\-image-formats
+.TP
+.B \-\-list\-importers
+List the available importers (file formats that can be read).
+.B \-I, \-\-import\-type=\fIID\fR
+Specify which importer to use; see below for a list. This is only
+necessary when the right format does not follow from the input file
+name.
+.TP
+.B \-\-list\-image\-formats
+List the available image formats for graph export
+.TP
+.B \-E, \-\-import\-encoding=\fISTRING\fR
+Specify an encoding for imported content.
+.TP
+.B \-M, \-\-merge\-to=\fIFILENAME\fR
+Merge a collection of workbooks into one.  Sheet size will expand
+to the largest in all the workbooks.  Names in the scope of
+individual workbooks will end up in the scope of the merged
+workbook.  The merge will be aborted if there are name conflicts.
+.TP
+.B \-S, \-\-export\-file\-per\-sheet
+Export a file for each sheet if the exporter only supports one sheet at a
+time.  The output filename is treated as a template in which sheet number
+is substituted for %n, sheet name is substituted for %s, and sheet object
+name is substituted for %o in case of graph export.  If there are no
+substitutions, a default of ".%n" is added.
+
+.SS "Help options"
+.TP
+.B \-\-version
+Display ssconvert's version.
+.TP
+.B \-h, \-\-help, \-\-usage
+Display a brief usage message.
+.TP
+.B \-\-help\-all
+Show all help options.
+.TP
+.B \-\-help\-libspreadsheet
+Show Gnumeric options.
+
+.SH LIST OF IMPORTER/EXPORTER IDS
+The following IDs can be can be used both for import (reading) and export
+(writing).
+.TP
+.B Gnumeric_XmlIO:sax
+Gnumeric's XML file format (*.gnumeric)
+.TP
+.B Gnumeric_OpenCalc:openoffice
+.URL "http://en.wikipedia.org/wiki/OpenDocument" "OpenDocument"
+or
+.URL "http://en.wikipedia.org/wiki/OpenOffice.org_Calc" "OpenOffice Calc"
+(*.sxc, *.ods) format.
+As an exporter, this is ODF/OpenOffice without foreign elements (*.ods).
+.TP
+.B Gnumeric_dif:dif
+.URL "http://en.wikipedia.org/wiki/Data_Interchange_Format" "Data Interchange Format"
+(*.dif)
+.TP
+.B Gnumeric_paradox:paradox
+.URL "http://en.wikipedia.org/wiki/Paradox_%28database%29" "Paradox database"
+or primary index file (*.db, *.px)
+.TP
+.B Gnumeric_stf:stf_assistant
+Text (configurable)
+.TP
+.B Gnumeric_sylk:sylk
+.URL "http://en.wikipedia.org/wiki/Multiplan" "MultiPlan"
+.URL "http://en.wikipedia.org/wiki/SYmbolic_LinK_%28SYLK%29" "Symbolic Link (SYLK)"
+(*.slk)
+.TP
+.B Gnumeric_Excel:xlsx
+Microsoft Excel (tm) 2007 ("Office Open XML",
+.URL "http://en.wikipedia.org/wiki/XLSX" "OOXML"
+) format
+
+.SH LIST OF IMPORTANT IMPORTER IDS
+.TP
+.B Gnumeric_stf:stf_csvtab
+Comma or tab separated values (CSV/TSV) (*.csv)
+.TP
+.B Gnumeric_html:html
+HTML (*.html, *.htm)
+.TP
+.B Gnumeric_Excel:excel
+Microsoft Excel (tm) (*.xls)
+.TP
+.B Gnumeric_Excel:excel_xml
+Microsoft Excel (tm) 2003 SpreadsheetML
+
+.SH LIST OF OTHER IMPORTER IDS
+.TP
+.B Gnumeric_QPro:qpro
+.URL "http://en.wikipedia.org/wiki/Quattro_Pro" "Quattro Pro"
+(*.wb1, *.wb2, *.wb3)
+.TP
+.B Gnumeric_applix:applix
+Applix (*.as)
+.TP
+.B Gnumeric_lotus:lotus
+.URL "http://en.wikipedia.org/wiki/Lotus_1-2-3" "Lotus 1-2-3"
+(*.wk1, *.wks, *.123)
+.TP
+.B Gnumeric_mps:mps
+.URL "http://en.wikipedia.org/wiki/MPS_%28format%29" "MPS (Mathematical Programming System) format"
+Linear programming and mixed integer programming file format (*.mps)
+.TP
+.B Gnumeric_oleo:oleo
+.URL "http://en.wikipedia.org/wiki/GNU_Oleo" "GNU Oleo"
+(*.oleo)
+.TP
+.B Gnumeric_plan_perfect:pln
+PlanPerfect Format (PLN)
+.TP
+.B Gnumeric_psiconv:psiconv
+Psion (*.psisheet)
+.TP
+.B Gnumeric_sc:sc
+SC/xspread
+.TP
+.B Gnumeric_xbase:xbase
+.URL "http://en.wikipedia.org/wiki/XBase" "xBase"
+(*.dbf) file format
+
+.SH LIST OF IMPORTANT EXPORTER IDS
+.TP
+.B Gnumeric_OpenCalc:odf
+ODF/OpenOffice with foreign elements (*.ods)
+.TP
+.B Gnumeric_glpk:glpk
+GLPK Linear Program Solver
+.TP
+.B Gnumeric_html:html40
+HTML 4.0 (*.html)
+.TP
+.B Gnumeric_html:html40frag
+HTML (*.html) fragment
+.TP
+.B Gnumeric_html:xhtml
+XHTML (*.html)
+.TP
+.B Gnumeric_html:xhtml_range
+XHTML range - for export to clipboard
+.TP
+.B Gnumeric_pdf:pdf_assistant
+Portable Document Format (*.PDF)
+.TP
+.B Gnumeric_stf:stf_csv
+Comma separated values (CSV)
+.TP
+.B Gnumeric_Excel:excel_dsf
+Microsoft Excel (tm) 97/2000/XP & 5.0/95
+
+.SH LIST OF OTHER EXPORTER IDS
+.TP
+.B Gnumeric_Excel:excel_biff7
+Microsoft Excel (tm) 5.0/95
+.TP
+.B Gnumeric_Excel:excel_biff8
+Microsoft S Excel (tm) 97/2000/XP
+.TP
+.B Gnumeric_GnomeGlossary:po
+Gnome Glossary PO file format
+.TP
+.B Gnumeric_html:html32
+HTML 3.2 (*.html)
+.TP
+.B Gnumeric_html:latex
+LaTeX 2e (*.tex)
+.TP
+.B Gnumeric_html:latex_table
+LaTeX 2e (*.tex) table fragment
+.TP
+.B Gnumeric_html:roff
+.URL "http://en.wikipedia.org/wiki/Troff" "TROFF"
+(*.me) format.
+.TP
+.B Gnumeric_lpsolve:lpsolve
+.URL "http://sourceforge.net/projects/lpsolve/" "LPSolve"
+Mixed Integer Linear Programming (MILP) solver
+
+.SH OPTIONS FOR THE PORTABLE DOCUMENT FORMAT (*.pdf) EXPORTER
+
+.TP
+.B sheet
+Name of the workbook sheet to operate on.
+You can specify several sheets by repeating this option.
+This is ignored if the \fBobject\fR option is given.
+
+.TP
+.B active-sheet
+Select the active sheet to operate on.  The value for this option is
+irrelevant, but the equal sign is mandatory.
+
+.TP
+.B object
+Name of the sheet object to print. If this option is given any \fBsheet\fR option is ignored.
+Only the first \fBobject\fR given is exported.
+
+.TP
+.B paper
+Paper size. Valid values include "\fBA4\fR" for ISO A4 and
+"\fBna_letter_8.5x11in\fR" for US Letter. If an individual graph is specified through the
+\fBobject\fR option, then a paper size of "\fBfit\fR" reduces the size of the paper to the
+size of the graph.
+.\" FIXME Is there a convenient way to list all valid paper sizes?
+.\" It looks like at least the values from plugins/excel/ms-excel-read.c's
+.\" paper_size_table[] are supported.
+
+.SH OPTIONS FOR THE CONFIGURABLE TEXT (*.txt) EXPORTER
+.\" Cf. "g_object_class_install_property" calls in src/stf-export.c
+
+.TP
+.B sheet
+Name of the workbook sheet to operate on.
+You can specify several sheets by repeating this option.
+
+.TP
+.B active-sheet
+Select the active sheet to operate on.  The value for this option is
+irrelevant, but the equal sign is mandatory.
+
+.TP
+.B eol
+End Of Line convention; how lines are terminated.
+"\fBunix\fR" for linefeed,
+"\fBmac\fR" for carriage return;
+"\fBwindows\fR" for carriage return plus linefeed.
+
+.TP
+.B charset
+The character encoding of the output. Defaults to UTF-8.
+
+.TP
+.B locale
+The locale to use for number and date formatting.
+Defaults to the current locale as reported by \fBlocale\fR(1).
+Consult \fBlocale \-a\fR output for acceptable values.
+
+.TP
+.B quote
+The character or string used for quoting fields. Defaults to "\fB\\"\fR"
+(quotation mark / double quote).
+
+.TP
+.B separator
+The string used to separate fields. Defaults to space.
+
+.TP
+.B format
+How cells should be formatted.
+Acceptable values:
+"\fBautomatic\fR" (apply automatic formatting; default),
+"\fBraw\fR" (output data raw, unformatted), or
+"\fBpreserve\fR" (preserve the formatting from the source document).
+
+This deals with the difference between a cell's contents and the way those
+contents are formatted.
+
+Consider a cell in a Gnumeric input document that was
+input as "4/19/73" in a US locale, with a format set to "d-mmm-yyyy" and
+thus formatted as "19-Apr-1973".
+
+With the default \fBformat\fR setting of "\fBautomatic\fR" it will be output
+as "1973/04/19". With "\fBpreserve\fR", the formatting will be preserved and
+it will be output as "19-Apr-1973". With "\fBraw\fR" it will be output as
+"26773" (Gnumeric's internal representation: days since an epoch).
+
+.TP
+.B transliterate-mode
+How to handle unrepresentable characters (characters that cannot be
+represented in the chosen output character set).
+Acceptable values:
+"\fBtransliterate\fR", or
+"\fBescape\fR".
+
+.TP
+.B quoting-mode
+When does data need to be quoted?
+"\fBnever\fR",
+"\fBauto\fR" (puts quotes where needed), or
+"\fBalways\fR". Defaults to "\fBauto\fR".
+
+.TP
+.B quoting-on-whitespace
+Controls whether initial or terminal whitespace forces quoting. Defaults to
+\fBTRUE\fR.
+
+
+.\".SH EXIT STATUS
+.\".SH RETURN VALUE
+.\".SH ERRORS
+.\".SH ENVIRONMENT
+.\".SH FILES
+.\".SH VERSIONS
+.\".SH CONFORMING TO
+.\".SH NOTES
+.\".SH BUGS
+.\".SH USAGE
+.SH EXAMPLE
+To convert the Gnumeric file \fIfoo.gnumeric\fR to a Microsoft Excel(TM)
+format file
+\fIfoo.xls\fR:
+.PP
+\fBssconvert\fR \fIfoo.gnumeric\fR \fIfoo.xls\fR
+.PP
+The export format can be specified explicitly, to override the default
+(which is based on the file extension):
+.PP
+\fBssconvert\fR \fB\-\-export\-type=\fRGnumeric_stf:stf_csv\fR \fIfoo.xls\fR
+\fIfoo.txt\fR
+.PP
+To convert an Excel format file \fIstatfuns.xls\fR to a text file,
+specifying the semicolon as the separator character:
+.PP
+\fBssconvert\fR \fB-O 'separator=; format=raw'\fR \fIsamples/excel/statfuns.xls\fR \fIstatfuns.txt\fR
+.PP
+To export the charts from the input file \fIinput.gnumeric\fR to numbered
+SVG files:
+.PP
+\fBssconvert\fR \fB\-\-export\-graphs\fR \fIinput.gnumeric\fR \fI'output.%n.svg'\fR
+.PP
+To export the charts from the input file \fIinput.gnumeric\fR to numbered
+PNG files:
+.PP
+\fBssconvert\fR \fB\-\-export\-type=png\fR \fB\-\-export\-graphs\fR \fIinput.gnumeric\fR \fI'output.%n.png'\fR
+.PP
+
+.SH LICENSE
+
+\fBssconvert\fR is licensed under the terms of the General Public
+License (GPL), version 2 or 3. For information on this license look at the
+source code that came with the software or see the
+.URL "http://www.gnu.org" "GNU project page" .
+
+.SH COPYRIGHT
+
+The copyright on the \fBGnumeric\fR software and source code is held
+by the individual authors as is documented in the source code.
+
+.SH AUTHOR
+
+\fBssconvert\fR's primary author is Jody Goldberg <jody@gnome.org>;
+\fBssconvert\fR builds on the \fBGnumeric\fR codebase.
+
+The initial version of this manpage was written by J.H.M. Dassen (Ray)
+<jdassen@debian.org>.
+
+.SH SEE ALSO
+.BR gnumeric(1),
+.BR ssdiff(1),
+.BR ssgrep(1),
+.BR ssindex(1)
+
+.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" .
+
+.URL "http://www.gnome.org/" "The GNOME project page" .
diff --git a/upstream/mageia-cauldron/man1/ssdiff.1 b/upstream/mageia-cauldron/man1/ssdiff.1
new file mode 100644
index 00000000..95c56bac
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssdiff.1
@@ -0,0 +1,81 @@
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH SSDIFF 1 "2012-12-24" gnumeric "GNOME"
+.SH NAME
+ssdiff \- compare two spreadsheets
+
+.SH SYNOPSIS
+\fBssdiff \fR [\fIOPTIONS\fR] \fIOLDFILE\fR \fINEWFILE\fR
+
+.SH DESCRIPTION
+This manual page briefly documents the \fBssdiff\fR command.
+
+\fBssdiff\fR is a command line utility to compare two spreadsheets and list their differences
+
+.\".SH "RETURN VALUE"
+.\".SH "EXIT STATUS"
+.\".SH ERRORS
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with single
+letter options starting with a single dash (`-') and longer options
+starting with two dashes (`--').
+
+.SS "Output options"
+.TP
+.B \-x, \-\-xml
+Display differences in xml format
+
+.SS "Help options"
+.TP
+.B \-V, \-\-version
+Display ssdiff's version
+.TP
+.B \-?, \-\-help
+Display the supported options
+
+.\".SH USAGE
+.SH EXAMPLE
+To compare an old version of a file with a newer file, run:
+.PP
+\fBssdiff\fR \fIold.gnumeric\fR \fInew.gnumeric\fR
+.PP
+
+The exit code will be 0 if no differences were found, 1 if differences
+were found, and 2 in case of trouble.
+
+.\".SH FILES
+.\".SH ENVIRONMENT
+.\".SH DIAGNOSTICS
+.\".SH SECURITY
+.\".SH CONFORMING TO
+.\".SH NOTES
+.\".SH BUGS
+
+.SH LICENSE
+
+\fBssdiff\fR is licensed under the terms of the General Public
+License (GPL), version 2 or 3. For information on this license look at the
+source code that came with the software or see the
+.URL "http://www.gnu.org" "GNU project page" .
+
+.SH COPYRIGHT
+
+The copyright on \fBssdiff\fR and the \fBgnumeric\fR software and source
+code is held by the individual authors as is documented in the source code.
+
+.SH AUTHOR
+
+\fBssdiff\fR's primary author is Morten Welinder <terra@gnome.org>;
+\fBssdiff\fR builds on the \fBgnumeric\fR codebase.
+
+.SH SEE ALSO
+\fBgnumeric\fR(1),
+\fBssconvert\fR(1),
+\fBssindex\fR(1)
+\fBssgrep\fR(1)
+
+.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" .
+
+.URL "http://www.gnome.org/" "The GNOME project page" .
diff --git a/upstream/mageia-cauldron/man1/ssgrep.1 b/upstream/mageia-cauldron/man1/ssgrep.1
new file mode 100644
index 00000000..0bdd771d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssgrep.1
@@ -0,0 +1,139 @@
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH SSGREP 1 "2009-02-08" gnumeric "GNOME"
+.SH NAME
+ssgrep \- search spreadsheets for strings
+
+.SH SYNOPSIS
+\fBssgrep \fR [\fIOPTIONS\fR] [\fIFILES\fR]
+
+.SH DESCRIPTION
+This manual page briefly documents the \fBssgrep\fR command.
+
+\fBssgrep\fR is a command line utility to search for strings in spreadsheets of
+any format supported by gnumeric. Without any output modifying options,
+\fBssgrep\fR prints one line for each match. A match consists of the matching
+content of a cell or, if the \fB\-R\fR option is given, the matching expression
+result of a cell.
+
+.\".SH "RETURN VALUE"
+.\".SH "EXIT STATUS"
+.\".SH ERRORS
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with single
+letter options starting with a single dash (`-') and longer options
+starting with two dashes (`--').
+
+.SS "Options controlling input file handling"
+.TP
+.B \-\-recalc
+Recalculate all cells
+
+.SS "Options controlling patterns and pattern matching"
+.TP
+.B \-f, \-\-keyword\-file=\fIFILE\fR
+The path to a text file containing one key per line
+.TP
+.B \-i, \-\-ignore\-case
+Ignore differences in letter case
+.TP
+.B \-w, \-\-word\-regexp
+Match only whole words
+.TP
+.B \-F, \-\-fixed\-strings
+Pattern is a set of fixed strings
+.TP
+.B \-R, \-\-search\-results
+Search results of expressions too
+.TP
+.B \-v, \-\-invert-match
+Search for cells that do not match
+
+.SS "Options controlling output in general"
+.TP
+.B \-c, \-\-count
+Only print a count of matches per file
+.TP
+.B \-L, \-\-files\-without\-matches
+Print filenames without matches
+.TP
+.B \-l, \-\-files\-with\-matches
+Print filenames with matches
+.TP
+.B \-q, \-\-quiet
+Suppress all normal output
+.TP
+.B \-H, \-\-with\-filename
+Print the filename for each match
+.TP
+.B \-h, \-\-without\-filename
+Do not print the filename for each match
+.TP
+.B \-n, \-\-print\-locus
+Print the location of each match
+.TP
+.B \-T, \-\-print\-type
+Print the location type of each match
+
+.SS "Help options"
+.TP
+.B \-V, \-\-version
+Display ssgrep's version
+.TP
+.B \-?, \-\-help
+Display the supported options
+.TP
+.B \-\-usage
+Display a brief usage message
+
+.\".SH USAGE
+.SH EXAMPLE
+To search for the string "SUM" in the file \fIfoo.gnumeric\fR :
+.PP
+\fBssgrep\fR \fISUM\fR \fIfoo.gnumeric\fR
+.PP
+To search for the strings from the file \fIkeywords\fR in the spreadsheet \fIfoo.xls\fR :
+.PP
+\fBssgrep\fR \fB\-\-keyword\-file=\fIkeywords\fR \fIfoo.xls\fR
+.PP
+
+.\".SH FILES
+.\".SH ENVIRONMENT
+.\".SH DIAGNOSTICS
+.\".SH SECURITY
+.\".SH CONFORMING TO
+.\".SH NOTES
+.\".SH BUGS
+
+.SH LICENSE
+
+\fBssgrep\fR is licensed under the terms of the General Public
+License (GPL), version 2 or 3. For information on this license look at the
+source code that came with the software or see the
+.URL "http://www.gnu.org" "GNU project page" .
+
+.SH COPYRIGHT
+
+The copyright on \fBssgrep\fR and the \fBgnumeric\fR software and source
+code is held by the individual authors as is documented in the source code.
+
+.SH AUTHOR
+
+\fBssgrep\fR's primary author is Jody Goldberg <jody@gnome.org>;
+\fBssgrep\fR builds on the \fBgnumeric\fR codebase.
+
+The initial version of this manpage was based on ssindex.1 by J.H.M. Dassen
+(Ray) <jdassen@debian.org>.
+
+.SH SEE ALSO
+\fBbeagled\fR(1),
+\fBgnumeric\fR(1),
+\fBssconvert\fR(1),
+\fBssdiff\fR(1)
+\fBssindex\fR(1)
+
+.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" .
+
+.URL "http://www.gnome.org/" "The GNOME project page" .
diff --git a/upstream/mageia-cauldron/man1/ssh-add.1 b/upstream/mageia-cauldron/man1/ssh-add.1
new file mode 100644
index 00000000..4601f598
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssh-add.1
@@ -0,0 +1,342 @@
+.\"	$OpenBSD: ssh-add.1,v 1.84 2022/02/04 02:49:17 dtucker Exp $
+.\"
+.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
+.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
+.\"                    All rights reserved
+.\"
+.\" As far as I am concerned, the code I have written for this software
+.\" can be used freely for any purpose.  Any derived versions of this
+.\" software must be clearly marked as such, and if the derived work is
+.\" incompatible with the protocol description in the RFC file, it must be
+.\" called by a name other than "ssh" or "Secure Shell".
+.\"
+.\"
+.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
+.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
+.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: February 4 2022 $
+.Dt SSH-ADD 1
+.Os
+.Sh NAME
+.Nm ssh-add
+.Nd adds private key identities to the OpenSSH authentication agent
+.Sh SYNOPSIS
+.Nm ssh-add
+.Op Fl cDdKkLlqvXx
+.Op Fl E Ar fingerprint_hash
+.Op Fl H Ar hostkey_file
+.Op Fl h Ar destination_constraint
+.Op Fl S Ar provider
+.Op Fl t Ar life
+.Op Ar
+.Nm ssh-add
+.Fl s Ar pkcs11
+.Nm ssh-add
+.Fl e Ar pkcs11
+.Nm ssh-add
+.Fl T
+.Ar pubkey ...
+.Sh DESCRIPTION
+.Nm
+adds private key identities to the authentication agent,
+.Xr ssh-agent 1 .
+When run without arguments, it adds the files
+.Pa ~/.ssh/id_rsa ,
+.Pa ~/.ssh/id_ecdsa ,
+.Pa ~/.ssh/id_ecdsa_sk ,
+.Pa ~/.ssh/id_ed25519 ,
+.Pa ~/.ssh/id_ed25519_sk ,
+and
+.Pa ~/.ssh/id_dsa .
+After loading a private key,
+.Nm
+will try to load corresponding certificate information from the
+filename obtained by appending
+.Pa -cert.pub
+to the name of the private key file.
+Alternative file names can be given on the command line.
+.Pp
+If any file requires a passphrase,
+.Nm
+asks for the passphrase from the user.
+The passphrase is read from the user's tty.
+.Nm
+retries the last passphrase if multiple identity files are given.
+.Pp
+The authentication agent must be running and the
+.Ev SSH_AUTH_SOCK
+environment variable must contain the name of its socket for
+.Nm
+to work.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl c
+Indicates that added identities should be subject to confirmation before
+being used for authentication.
+Confirmation is performed by
+.Xr ssh-askpass 1 .
+Successful confirmation is signaled by a zero exit status from
+.Xr ssh-askpass 1 ,
+rather than text entered into the requester.
+.It Fl D
+Deletes all identities from the agent.
+.It Fl d
+Instead of adding identities, removes identities from the agent.
+If
+.Nm
+has been run without arguments, the keys for the default identities and
+their corresponding certificates will be removed.
+Otherwise, the argument list will be interpreted as a list of paths to
+public key files to specify keys and certificates to be removed from the agent.
+If no public key is found at a given path,
+.Nm
+will append
+.Pa .pub
+and retry.
+If the argument list consists of
+.Dq -
+then
+.Nm
+will read public keys to be removed from standard input.
+.It Fl E Ar fingerprint_hash
+Specifies the hash algorithm used when displaying key fingerprints.
+Valid options are:
+.Dq md5
+and
+.Dq sha256 .
+The default is
+.Dq sha256 .
+.It Fl e Ar pkcs11
+Remove keys provided by the PKCS#11 shared library
+.Ar pkcs11 .
+.It Fl H Ar hostkey_file
+Specifies a known hosts file to look up hostkeys when using
+destination-constrained keys via the
+.Fl h
+flag.
+This option may be specified multiple times to allow multiple files to be
+searched.
+If no files are specified,
+.Nm
+will use the default
+.Xr ssh_config 5
+known hosts files:
+.Pa ~/.ssh/known_hosts ,
+.Pa ~/.ssh/known_hosts2 ,
+.Pa /etc/ssh/ssh_known_hosts ,
+and
+.Pa /etc/ssh/ssh_known_hosts2 .
+.It Fl h Ar destination_constraint
+When adding keys, constrain them to be usable only through specific hosts or to
+specific destinations.
+.Pp
+Destination constraints of the form
+.Sq [user@]dest-hostname
+permit use of the key only from the origin host (the one running
+.Xr ssh-agent 1 )
+to the listed destination host, with optional user name.
+.Pp
+Constraints of the form
+.Sq src-hostname>[user@]dst-hostname
+allow a key available on a forwarded
+.Xr ssh-agent 1
+to be used through a particular host (as specified by
+.Sq src-hostname )
+to authenticate to a further host,
+specified by
+.Sq dst-hostname .
+.Pp
+Multiple destination constraints may be added when loading keys.
+When attempting authentication with a key that has destination constraints,
+the whole connection path, including
+.Xr ssh-agent 1
+forwarding, is tested against those constraints and each
+hop must be permitted for the attempt to succeed.
+For example, if key is forwarded to a remote host,
+.Sq host-b ,
+and is attempting authentication to another host,
+.Sq host-c ,
+then the operation will be successful only if
+.Sq host-b
+was permitted from the origin host and the subsequent
+.Sq host-b>host-c
+hop is also permitted by destination constraints.
+.Pp
+Hosts are identified by their host keys, and are looked up from known hosts
+files by
+.Nm .
+Wildcards patterns may be used for hostnames and certificate host
+keys are supported.
+By default, keys added by
+.Nm
+are not destination constrained.
+.Pp
+Destination constraints were added in OpenSSH release 8.9.
+Support in both the remote SSH client and server is required when using
+destination-constrained keys over a forwarded
+.Xr ssh-agent 1
+channel.
+.Pp
+It is also important to note that destination constraints can only be
+enforced by
+.Xr ssh-agent 1
+when a key is used, or when it is forwarded by a
+.Sy cooperating
+.Xr ssh 1 .
+Specifically, it does not prevent an attacker with access to a remote
+.Ev SSH_AUTH_SOCK
+from forwarding it again and using it on a different host (but only to
+a permitted destination).
+.It Fl K
+Load resident keys from a FIDO authenticator.
+.It Fl k
+When loading keys into or deleting keys from the agent, process plain private
+keys only and skip certificates.
+.It Fl L
+Lists public key parameters of all identities currently represented
+by the agent.
+.It Fl l
+Lists fingerprints of all identities currently represented by the agent.
+.It Fl q
+Be quiet after a successful operation.
+.It Fl S Ar provider
+Specifies a path to a library that will be used when adding
+FIDO authenticator-hosted keys, overriding the default of using the
+internal USB HID support.
+.It Fl s Ar pkcs11
+Add keys provided by the PKCS#11 shared library
+.Ar pkcs11 .
+.It Fl T Ar pubkey ...
+Tests whether the private keys that correspond to the specified
+.Ar pubkey
+files are usable by performing sign and verify operations on each.
+.It Fl t Ar life
+Set a maximum lifetime when adding identities to an agent.
+The lifetime may be specified in seconds or in a time format
+specified in
+.Xr sshd_config 5 .
+.It Fl v
+Verbose mode.
+Causes
+.Nm
+to print debugging messages about its progress.
+This is helpful in debugging problems.
+Multiple
+.Fl v
+options increase the verbosity.
+The maximum is 3.
+.It Fl X
+Unlock the agent.
+.It Fl x
+Lock the agent with a password.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
+If
+.Nm
+needs a passphrase, it will read the passphrase from the current
+terminal if it was run from a terminal.
+If
+.Nm
+does not have a terminal associated with it but
+.Ev DISPLAY
+and
+.Ev SSH_ASKPASS
+are set, it will execute the program specified by
+.Ev SSH_ASKPASS
+(by default
+.Dq ssh-askpass )
+and open an X11 window to read the passphrase.
+This is particularly useful when calling
+.Nm
+from a
+.Pa .xsession
+or related script.
+.Pp
+.Ev SSH_ASKPASS_REQUIRE
+allows further control over the use of an askpass program.
+If this variable is set to
+.Dq never
+then
+.Nm
+will never attempt to use one.
+If it is set to
+.Dq prefer ,
+then
+.Nm
+will prefer to use the askpass program instead of the TTY when requesting
+passwords.
+Finally, if the variable is set to
+.Dq force ,
+then the askpass program will be used for all passphrase input regardless
+of whether
+.Ev DISPLAY
+is set.
+.It Ev SSH_AUTH_SOCK
+Identifies the path of a
+.Ux Ns -domain
+socket used to communicate with the agent.
+.It Ev SSH_SK_PROVIDER
+Specifies a path to a library that will be used when loading any
+FIDO authenticator-hosted keys, overriding the default of using
+the built-in USB HID support.
+.El
+.Sh FILES
+.Bl -tag -width Ds -compact
+.It Pa ~/.ssh/id_dsa
+.It Pa ~/.ssh/id_ecdsa
+.It Pa ~/.ssh/id_ecdsa_sk
+.It Pa ~/.ssh/id_ed25519
+.It Pa ~/.ssh/id_ed25519_sk
+.It Pa ~/.ssh/id_rsa
+Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
+authenticator-hosted Ed25519 or RSA authentication identity of the user.
+.El
+.Pp
+Identity files should not be readable by anyone but the user.
+Note that
+.Nm
+ignores identity files if they are accessible by others.
+.Sh EXIT STATUS
+Exit status is 0 on success, 1 if the specified command fails,
+and 2 if
+.Nm
+is unable to contact the authentication agent.
+.Sh SEE ALSO
+.Xr ssh 1 ,
+.Xr ssh-agent 1 ,
+.Xr ssh-askpass 1 ,
+.Xr ssh-keygen 1 ,
+.Xr sshd 8
+.Sh AUTHORS
+OpenSSH is a derivative of the original and free
+ssh 1.2.12 release by Tatu Ylonen.
+Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
+Theo de Raadt and Dug Song
+removed many bugs, re-added newer features and
+created OpenSSH.
+Markus Friedl contributed the support for SSH
+protocol versions 1.5 and 2.0.
diff --git a/upstream/mageia-cauldron/man1/ssh-agent.1 b/upstream/mageia-cauldron/man1/ssh-agent.1
new file mode 100644
index 00000000..97f4cab0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssh-agent.1
@@ -0,0 +1,274 @@
+.\" $OpenBSD: ssh-agent.1,v 1.75 2022/10/07 06:00:58 jmc Exp $
+.\"
+.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
+.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
+.\"                    All rights reserved
+.\"
+.\" As far as I am concerned, the code I have written for this software
+.\" can be used freely for any purpose.  Any derived versions of this
+.\" software must be clearly marked as such, and if the derived work is
+.\" incompatible with the protocol description in the RFC file, it must be
+.\" called by a name other than "ssh" or "Secure Shell".
+.\"
+.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
+.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
+.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: October 7 2022 $
+.Dt SSH-AGENT 1
+.Os
+.Sh NAME
+.Nm ssh-agent
+.Nd OpenSSH authentication agent
+.Sh SYNOPSIS
+.Nm ssh-agent
+.Op Fl c | s
+.Op Fl \&Dd
+.Op Fl a Ar bind_address
+.Op Fl E Ar fingerprint_hash
+.Op Fl O Ar option
+.Op Fl P Ar allowed_providers
+.Op Fl t Ar life
+.Nm ssh-agent
+.Op Fl a Ar bind_address
+.Op Fl E Ar fingerprint_hash
+.Op Fl O Ar option
+.Op Fl P Ar allowed_providers
+.Op Fl t Ar life
+.Ar command Op Ar arg ...
+.Nm ssh-agent
+.Op Fl c | s
+.Fl k
+.Sh DESCRIPTION
+.Nm
+is a program to hold private keys used for public key authentication.
+Through use of environment variables the agent can be located
+and automatically used for authentication when logging in to other
+machines using
+.Xr ssh 1 .
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl a Ar bind_address
+Bind the agent to the
+.Ux Ns -domain
+socket
+.Ar bind_address .
+The default is
+.Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
+.It Fl c
+Generate C-shell commands on
+.Dv stdout .
+This is the default if
+.Ev SHELL
+looks like it's a csh style of shell.
+.It Fl D
+Foreground mode.
+When this option is specified,
+.Nm
+will not fork.
+.It Fl d
+Debug mode.
+When this option is specified,
+.Nm
+will not fork and will write debug information to standard error.
+.It Fl E Ar fingerprint_hash
+Specifies the hash algorithm used when displaying key fingerprints.
+Valid options are:
+.Dq md5
+and
+.Dq sha256 .
+The default is
+.Dq sha256 .
+.It Fl k
+Kill the current agent (given by the
+.Ev SSH_AGENT_PID
+environment variable).
+.It Fl O Ar option
+Specify an option when starting
+.Nm .
+Currently two options are supported:
+.Cm allow-remote-pkcs11
+and
+.Cm no-restrict-websafe .
+.Pp
+The
+.Cm allow-remote-pkcs11
+option allows clients of a forwarded
+.Nm
+to load PKCS#11 or FIDO provider libraries.
+By default only local clients may perform this operation.
+Note that signalling that a
+.Nm
+client remote is performed by
+.Xr ssh 1 ,
+and use of other tools to forward access to the agent socket may circumvent
+this restriction.
+.Pp
+The
+.Cm no-restrict-websafe ,
+instructs
+.Nm
+to permit signatures using FIDO keys that might be web authentication
+requests.
+By default,
+.Nm
+refuses signature requests for FIDO keys where the key application string
+does not start with
+.Dq ssh:
+and when the data to be signed does not appear to be a
+.Xr ssh 1
+user authentication request or a
+.Xr ssh-keygen 1
+signature.
+The default behaviour prevents forwarded access to a FIDO key from also
+implicitly forwarding the ability to authenticate to websites.
+.It Fl P Ar allowed_providers
+Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO
+authenticator middleware shared libraries that may be used with the
+.Fl S
+or
+.Fl s
+options to
+.Xr ssh-add 1 .
+Libraries that do not match the pattern list will be refused.
+See PATTERNS in
+.Xr ssh_config 5
+for a description of pattern-list syntax.
+The default list is
+.Dq /usr/lib/*,/usr/local/lib/* .
+.It Fl s
+Generate Bourne shell commands on
+.Dv stdout .
+This is the default if
+.Ev SHELL
+does not look like it's a csh style of shell.
+.It Fl t Ar life
+Set a default value for the maximum lifetime of identities added to the agent.
+The lifetime may be specified in seconds or in a time format specified in
+.Xr sshd_config 5 .
+A lifetime specified for an identity with
+.Xr ssh-add 1
+overrides this value.
+Without this option the default maximum lifetime is forever.
+.It Ar command Op Ar arg ...
+If a command (and optional arguments) is given,
+this is executed as a subprocess of the agent.
+The agent exits automatically when the command given on the command
+line terminates.
+.El
+.Pp
+There are two main ways to get an agent set up.
+The first is at the start of an X session,
+where all other windows or programs are started as children of the
+.Nm
+program.
+The agent starts a command under which its environment
+variables are exported, for example
+.Cm ssh-agent xterm & .
+When the command terminates, so does the agent.
+.Pp
+The second method is used for a login session.
+When
+.Nm
+is started,
+it prints the shell commands required to set its environment variables,
+which in turn can be evaluated in the calling shell, for example
+.Cm eval `ssh-agent -s` .
+.Pp
+In both cases,
+.Xr ssh 1
+looks at these environment variables
+and uses them to establish a connection to the agent.
+.Pp
+The agent initially does not have any private keys.
+Keys are added using
+.Xr ssh-add 1
+or by
+.Xr ssh 1
+when
+.Cm AddKeysToAgent
+is set in
+.Xr ssh_config 5 .
+Multiple identities may be stored in
+.Nm
+concurrently and
+.Xr ssh 1
+will automatically use them if present.
+.Xr ssh-add 1
+is also used to remove keys from
+.Nm
+and to query the keys that are held in one.
+.Pp
+Connections to
+.Nm
+may be forwarded from further remote hosts using the
+.Fl A
+option to
+.Xr ssh 1
+(but see the caveats documented therein),
+avoiding the need for authentication data to be stored on other machines.
+Authentication passphrases and private keys never go over the network:
+the connection to the agent is forwarded over SSH remote connections
+and the result is returned to the requester,
+allowing the user access to their identities anywhere in the network
+in a secure fashion.
+.Sh ENVIRONMENT
+.Bl -tag -width "SSH_AGENT_PID"
+.It Ev SSH_AGENT_PID
+When
+.Nm
+starts, it stores the name of the agent's process ID (PID) in this variable.
+.It Ev SSH_AUTH_SOCK
+When
+.Nm
+starts, it creates a
+.Ux Ns -domain
+socket and stores its pathname in this variable.
+It is accessible only to the current user,
+but is easily abused by root or another instance of the same user.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
+.Ux Ns -domain
+sockets used to contain the connection to the authentication agent.
+These sockets should only be readable by the owner.
+The sockets should get automatically removed when the agent exits.
+.El
+.Sh SEE ALSO
+.Xr ssh 1 ,
+.Xr ssh-add 1 ,
+.Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
+.Xr sshd 8
+.Sh AUTHORS
+.An -nosplit
+OpenSSH is a derivative of the original and free ssh 1.2.12 release by
+.An Tatu Ylonen .
+.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
+and
+.An Dug Song
+removed many bugs, re-added newer features and created OpenSSH.
+.An Markus Friedl
+contributed the support for SSH protocol versions 1.5 and 2.0.
diff --git a/upstream/mageia-cauldron/man1/ssh-copy-id.1 b/upstream/mageia-cauldron/man1/ssh-copy-id.1
new file mode 100644
index 00000000..c141a296
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssh-copy-id.1
@@ -0,0 +1,198 @@
+.ig \"  -*- nroff -*-
+Copyright (c) 1999-2020 hands.com Ltd. <http://hands.com/>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+..
+.Dd $Mdocdate: June 17 2010 $
+.Dt SSH-COPY-ID 1
+.Os
+.Sh NAME
+.Nm ssh-copy-id
+.Nd use locally available keys to authorise logins on a remote machine
+.Sh SYNOPSIS
+.Nm
+.Op Fl f
+.Op Fl n
+.Op Fl s
+.Op Fl i Op Ar identity_file
+.Op Fl p Ar port
+.Op Fl o Ar ssh_option
+.Op Ar user Ns @ Ns
+.Ar hostname
+.Nm
+.Fl h | Fl ?
+.br
+.Sh DESCRIPTION
+.Nm
+is a script that uses
+.Xr ssh 1
+to log into a remote machine (presumably using a login password,
+so password authentication should be enabled, unless you've done some
+clever use of multiple identities).  It assembles a list of one or more
+fingerprints (as described below) and tries to log in with each key, to
+see if any of them are already installed (of course, if you are not using
+.Xr ssh-agent 1
+this may result in you being repeatedly prompted for pass-phrases).
+It then assembles a list of those that failed to log in, and using ssh,
+enables logins with those keys on the remote server.  By default it adds
+the keys by appending them to the remote user's
+.Pa ~/.ssh/authorized_keys
+(creating the file, and directory, if necessary).  It is also capable
+of detecting if the remote system is a NetScreen, and using its
+.Ql set ssh pka-dsa key ...
+command instead.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl i Ar identity_file
+Use only the key(s) contained in
+.Ar identity_file
+(rather than looking for identities via
+.Xr ssh-add 1
+or in the
+.Ic default_ID_file ) .
+If the filename does not end in
+.Pa .pub
+this is added.  If the filename is omitted, the 
+.Ic default_ID_file
+is used.
+.Pp
+Note that this can be used to ensure that the keys copied have the
+comment one prefers and/or extra options applied, by ensuring that the
+key file has these set as preferred before the copy is attempted.
+.It Fl f
+Forced mode: doesn't check if the keys are present on the remote server.
+This means that it does not need the private key.  Of course, this can result
+in more than one copy of the key being installed on the remote system.
+.It Fl n
+do a dry-run.  Instead of installing keys on the remote system simply
+prints the key(s) that would have been installed.
+.It Fl s
+SFTP mode: usually the public keys are installed by executing commands on the remote side.
+With this option the user's
+.Pa ~/.ssh/authorized_keys
+file will be downloaded, modified locally and uploaded with sftp.
+This option is useful if the server has restrictions on commands which can be used on the remote side.
+.It Fl h , Fl ?
+Print Usage summary
+.It Fl p Ar port , Fl o Ar ssh_option
+These two options are simply passed through untouched, along with their
+argument, to allow one to set the port or other
+.Xr ssh 1
+options, respectively.
+.Pp
+Rather than specifying these as command line options, it is often better to use (per-host) settings in
+.Xr ssh 1 Ns 's
+configuration file:
+.Xr ssh_config 5 .
+.El
+.Pp
+Default behaviour without
+.Fl i ,
+is to check if
+.Ql ssh-add -L
+provides any output, and if so those keys are used.  Note that this results in
+the comment on the key being the filename that was given to
+.Xr ssh-add 1
+when the key was loaded into your
+.Xr ssh-agent 1
+rather than the comment contained in that file, which is a bit of a shame.
+Otherwise, if
+.Xr ssh-add 1
+provides no keys contents of the 
+.Ic default_ID_file
+will be used.
+.Pp
+The
+.Ic default_ID_file
+is the most recent file that matches:
+.Pa ~/.ssh/id*.pub ,
+(excluding those that match
+.Pa ~/.ssh/*-cert.pub )
+so if you create a key that is not the one you want
+.Nm
+to use, just use
+.Xr touch 1
+on your preferred key's 
+.Pa .pub
+file to reinstate it as the most recent.
+.Pp
+.Sh EXAMPLES
+If you have already installed keys from one system on a lot of remote
+hosts, and you then create a new key, on a new client machine, say,
+it can be difficult to keep track of which systems on which you've
+installed the new key.  One way of dealing with this is to load both
+the new key and old key(s) into your
+.Xr ssh-agent 1 .
+Load the new key first, without the
+.Fl c
+option, then load one or more old keys into the agent, possibly by
+ssh-ing to the client machine that has that old key, using the
+.Fl A
+option to allow agent forwarding:
+.Pp
+.D1 user@newclient$ ssh-add
+.D1 user@newclient$ ssh -A old.client
+.D1 user@oldl$ ssh-add -c
+.D1 No   ... prompt for pass-phrase ...
+.D1 user@old$ logoff
+.D1 user@newclient$ ssh someserver
+.Pp
+now, if the new key is installed on the server, you'll be allowed in
+unprompted, whereas if you only have the old key(s) enabled, you'll be
+asked for confirmation, which is your cue to log back out and run
+.Pp
+.D1 user@newclient$ ssh-copy-id -i someserver
+.Pp
+The reason you might want to specify the -i option in this case is to
+ensure that the comment on the installed key is the one from the
+.Pa .pub
+file, rather than just the filename that was loaded into your agent.
+It also ensures that only the id you intended is installed, rather than
+all the keys that you have in your
+.Xr ssh-agent 1 .
+Of course, you can specify another id, or use the contents of the
+.Xr ssh-agent 1
+as you prefer.
+.Pp
+Having mentioned
+.Xr ssh-add 1 Ns 's
+.Fl c
+option, you might consider using this whenever using agent forwarding
+to avoid your key being hijacked, but it is much better to instead use
+.Xr ssh 1 Ns 's
+.Ar ProxyCommand
+and 
+.Fl W
+option,
+to bounce through remote servers while always doing direct end-to-end
+authentication. This way the middle hop(s) don't get access to your
+.Xr ssh-agent 1 .
+A web search for
+.Ql ssh proxycommand nc
+should prove enlightening (N.B. the modern approach is to use the
+.Fl W
+option, rather than
+.Xr nc 1 ) .
+.Sh "SEE ALSO"
+.Xr ssh 1 ,
+.Xr ssh-agent 1 ,
+.Xr sshd 8
diff --git a/upstream/mageia-cauldron/man1/ssh-keyscan.1 b/upstream/mageia-cauldron/man1/ssh-keyscan.1
new file mode 100644
index 00000000..aa6d34f6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssh-keyscan.1
@@ -0,0 +1,193 @@
+.\"	$OpenBSD: ssh-keyscan.1,v 1.49 2023/02/10 06:41:53 jmc Exp $
+.\"
+.\" Copyright 1995, 1996 by David Mazieres <dm@lcs.mit.edu>.
+.\"
+.\" Modification and redistribution in source and binary forms is
+.\" permitted provided that due credit is given to the author and the
+.\" OpenBSD project by leaving this copyright notice intact.
+.\"
+.Dd $Mdocdate: February 10 2023 $
+.Dt SSH-KEYSCAN 1
+.Os
+.Sh NAME
+.Nm ssh-keyscan
+.Nd gather SSH public keys from servers
+.Sh SYNOPSIS
+.Nm ssh-keyscan
+.Op Fl 46cDHv
+.Op Fl f Ar file
+.Op Fl O Ar option
+.Op Fl p Ar port
+.Op Fl T Ar timeout
+.Op Fl t Ar type
+.Op Ar host | addrlist namelist
+.Sh DESCRIPTION
+.Nm
+is a utility for gathering the public SSH host keys of a number of
+hosts.
+It was designed to aid in building and verifying
+.Pa ssh_known_hosts
+files,
+the format of which is documented in
+.Xr sshd 8 .
+.Nm
+provides a minimal interface suitable for use by shell and perl
+scripts.
+.Pp
+.Nm
+uses non-blocking socket I/O to contact as many hosts as possible in
+parallel, so it is very efficient.
+The keys from a domain of 1,000
+hosts can be collected in tens of seconds, even when some of those
+hosts are down or do not run
+.Xr sshd 8 .
+For scanning, one does not need
+login access to the machines that are being scanned, nor does the
+scanning process involve any encryption.
+.Pp
+Hosts to be scanned may be specified by hostname, address or by CIDR
+network range (e.g. 192.168.16/28).
+If a network range is specified, then all addresses in that range will
+be scanned.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 4
+Force
+.Nm
+to use IPv4 addresses only.
+.It Fl 6
+Force
+.Nm
+to use IPv6 addresses only.
+.It Fl c
+Request certificates from target hosts instead of plain keys.
+.It Fl D
+Print keys found as SSHFP DNS records.
+The default is to print keys in a format usable as a
+.Xr ssh 1
+.Pa known_hosts
+file.
+.It Fl f Ar file
+Read hosts or
+.Dq addrlist namelist
+pairs from
+.Ar file ,
+one per line.
+If
+.Sq -
+is supplied instead of a filename,
+.Nm
+will read from the standard input.
+Names read from a file must start with an address, hostname or CIDR network
+range to be scanned.
+Addresses and hostnames may optionally be followed by comma-separated name
+or address aliases that will be copied to the output.
+For example:
+.Bd -literal
+192.168.11.0/24
+10.20.1.1
+happy.example.org
+10.0.0.1,sad.example.org
+.Ed
+.It Fl H
+Hash all hostnames and addresses in the output.
+Hashed names may be used normally by
+.Xr ssh 1
+and
+.Xr sshd 8 ,
+but they do not reveal identifying information should the file's contents
+be disclosed.
+.It Fl O Ar option
+Specify a key/value option.
+At present, only a single option is supported:
+.Bl -tag -width Ds
+.It Cm hashalg Ns = Ns Ar algorithm
+Selects a hash algorithm to use when printing SSHFP records using the
+.Fl D
+flag.
+Valid algorithms are
+.Dq sha1
+and
+.Dq sha256 .
+The default is to print both.
+.El
+.It Fl p Ar port
+Connect to
+.Ar port
+on the remote host.
+.It Fl T Ar timeout
+Set the timeout for connection attempts.
+If
+.Ar timeout
+seconds have elapsed since a connection was initiated to a host or since the
+last time anything was read from that host, the connection is
+closed and the host in question considered unavailable.
+The default is 5 seconds.
+.It Fl t Ar type
+Specify the type of the key to fetch from the scanned hosts.
+The possible values are
+.Dq dsa ,
+.Dq ecdsa ,
+.Dq ed25519 ,
+.Dq ecdsa-sk ,
+.Dq ed25519-sk ,
+or
+.Dq rsa .
+Multiple values may be specified by separating them with commas.
+The default is to fetch
+.Dq rsa ,
+.Dq ecdsa ,
+.Dq ed25519 ,
+.Dq ecdsa-sk ,
+and
+.Dq ed25519-sk
+keys.
+.It Fl v
+Verbose mode:
+print debugging messages about progress.
+.El
+.Pp
+If an ssh_known_hosts file is constructed using
+.Nm
+without verifying the keys, users will be vulnerable to
+.Em man in the middle
+attacks.
+On the other hand, if the security model allows such a risk,
+.Nm
+can help in the detection of tampered keyfiles or man in the middle
+attacks which have begun after the ssh_known_hosts file was created.
+.Sh FILES
+.Pa /etc/ssh/ssh_known_hosts
+.Sh EXAMPLES
+Print the RSA host key for machine
+.Ar hostname :
+.Pp
+.Dl $ ssh-keyscan -t rsa hostname
+.Pp
+Search a network range, printing all supported key types:
+.Pp
+.Dl $ ssh-keyscan 192.168.0.64/25
+.Pp
+Find all hosts from the file
+.Pa ssh_hosts
+which have new or different keys from those in the sorted file
+.Pa ssh_known_hosts :
+.Bd -literal -offset indent
+$ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
+	sort -u - ssh_known_hosts | diff ssh_known_hosts -
+.Ed
+.Sh SEE ALSO
+.Xr ssh 1 ,
+.Xr sshd 8
+.Rs
+.%D 2006
+.%R RFC 4255
+.%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
+.Re
+.Sh AUTHORS
+.An -nosplit
+.An David Mazieres Aq Mt dm@lcs.mit.edu
+wrote the initial version, and
+.An Wayne Davison Aq Mt wayned@users.sourceforge.net
+added support for protocol version 2.
diff --git a/upstream/mageia-cauldron/man1/ssh.1 b/upstream/mageia-cauldron/man1/ssh.1
new file mode 100644
index 00000000..71c16a0d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssh.1
@@ -0,0 +1,1801 @@
+.\"
+.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
+.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
+.\"                    All rights reserved
+.\"
+.\" As far as I am concerned, the code I have written for this software
+.\" can be used freely for any purpose.  Any derived versions of this
+.\" software must be clearly marked as such, and if the derived work is
+.\" incompatible with the protocol description in the RFC file, it must be
+.\" called by a name other than "ssh" or "Secure Shell".
+.\"
+.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
+.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
+.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $OpenBSD: ssh.1,v 1.433 2022/11/28 01:37:36 djm Exp $
+.Dd $Mdocdate: November 28 2022 $
+.Dt SSH 1
+.Os
+.Sh NAME
+.Nm ssh
+.Nd OpenSSH remote login client
+.Sh SYNOPSIS
+.Nm ssh
+.Op Fl 46AaCfGgKkMNnqsTtVvXxYy
+.Op Fl B Ar bind_interface
+.Op Fl b Ar bind_address
+.Op Fl c Ar cipher_spec
+.Op Fl D Oo Ar bind_address : Oc Ns Ar port
+.Op Fl E Ar log_file
+.Op Fl e Ar escape_char
+.Op Fl F Ar configfile
+.Op Fl I Ar pkcs11
+.Op Fl i Ar identity_file
+.Op Fl J Ar destination
+.Op Fl L Ar address
+.Op Fl l Ar login_name
+.Op Fl m Ar mac_spec
+.Op Fl O Ar ctl_cmd
+.Op Fl o Ar option
+.Op Fl p Ar port
+.Op Fl Q Ar query_option
+.Op Fl R Ar address
+.Op Fl S Ar ctl_path
+.Op Fl W Ar host : Ns Ar port
+.Op Fl w Ar local_tun Ns Op : Ns Ar remote_tun
+.Ar destination
+.Op Ar command Op Ar argument ...
+.Sh DESCRIPTION
+.Nm
+(SSH client) is a program for logging into a remote machine and for
+executing commands on a remote machine.
+It is intended to provide secure encrypted communications between
+two untrusted hosts over an insecure network.
+X11 connections, arbitrary TCP ports and
+.Ux Ns -domain
+sockets can also be forwarded over the secure channel.
+.Pp
+.Nm
+connects and logs into the specified
+.Ar destination ,
+which may be specified as either
+.Sm off
+.Oo user @ Oc hostname
+.Sm on
+or a URI of the form
+.Sm off
+.No ssh:// Oo user @ Oc hostname Op : port .
+.Sm on
+The user must prove
+their identity to the remote machine using one of several methods
+(see below).
+.Pp
+If a
+.Ar command
+is specified,
+it will be executed on the remote host instead of a login shell.
+A complete command line may be specified as
+.Ar command ,
+or it may have additional arguments.
+If supplied, the arguments will be appended to the command, separated by
+spaces, before it is sent to the server to be executed.
+.Pp
+The options are as follows:
+.Pp
+.Bl -tag -width Ds -compact
+.It Fl 4
+Forces
+.Nm
+to use IPv4 addresses only.
+.Pp
+.It Fl 6
+Forces
+.Nm
+to use IPv6 addresses only.
+.Pp
+.It Fl A
+Enables forwarding of connections from an authentication agent such as
+.Xr ssh-agent 1 .
+This can also be specified on a per-host basis in a configuration file.
+.Pp
+Agent forwarding should be enabled with caution.
+Users with the ability to bypass file permissions on the remote host
+(for the agent's
+.Ux Ns -domain
+socket) can access the local agent through the forwarded connection.
+An attacker cannot obtain key material from the agent,
+however they can perform operations on the keys that enable them to
+authenticate using the identities loaded into the agent.
+A safer alternative may be to use a jump host
+(see
+.Fl J ) .
+.Pp
+.It Fl a
+Disables forwarding of the authentication agent connection.
+.Pp
+.It Fl B Ar bind_interface
+Bind to the address of
+.Ar bind_interface
+before attempting to connect to the destination host.
+This is only useful on systems with more than one address.
+.Pp
+.It Fl b Ar bind_address
+Use
+.Ar bind_address
+on the local machine as the source address
+of the connection.
+Only useful on systems with more than one address.
+.Pp
+.It Fl C
+Requests compression of all data (including stdin, stdout, stderr, and
+data for forwarded X11, TCP and
+.Ux Ns -domain
+connections).
+The compression algorithm is the same used by
+.Xr gzip 1 .
+Compression is desirable on modem lines and other
+slow connections, but will only slow down things on fast networks.
+The default value can be set on a host-by-host basis in the
+configuration files; see the
+.Cm Compression
+option in
+.Xr ssh_config 5 .
+.Pp
+.It Fl c Ar cipher_spec
+Selects the cipher specification for encrypting the session.
+.Ar cipher_spec
+is a comma-separated list of ciphers
+listed in order of preference.
+See the
+.Cm Ciphers
+keyword in
+.Xr ssh_config 5
+for more information.
+.Pp
+.It Fl D Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port
+.Sm on
+.Xc
+Specifies a local
+.Dq dynamic
+application-level port forwarding.
+This works by allocating a socket to listen to
+.Ar port
+on the local side, optionally bound to the specified
+.Ar bind_address .
+Whenever a connection is made to this port, the
+connection is forwarded over the secure channel, and the application
+protocol is then used to determine where to connect to from the
+remote machine.
+Currently the SOCKS4 and SOCKS5 protocols are supported, and
+.Nm
+will act as a SOCKS server.
+Only root can forward privileged ports.
+Dynamic port forwardings can also be specified in the configuration file.
+.Pp
+IPv6 addresses can be specified by enclosing the address in square brackets.
+Only the superuser can forward privileged ports.
+By default, the local port is bound in accordance with the
+.Cm GatewayPorts
+setting.
+However, an explicit
+.Ar bind_address
+may be used to bind the connection to a specific address.
+The
+.Ar bind_address
+of
+.Dq localhost
+indicates that the listening port be bound for local use only, while an
+empty address or
+.Sq *
+indicates that the port should be available from all interfaces.
+.Pp
+.It Fl E Ar log_file
+Append debug logs to
+.Ar log_file
+instead of standard error.
+.Pp
+.It Fl e Ar escape_char
+Sets the escape character for sessions with a pty (default:
+.Ql ~ ) .
+The escape character is only recognized at the beginning of a line.
+The escape character followed by a dot
+.Pq Ql \&.
+closes the connection;
+followed by control-Z suspends the connection;
+and followed by itself sends the escape character once.
+Setting the character to
+.Dq none
+disables any escapes and makes the session fully transparent.
+.Pp
+.It Fl F Ar configfile
+Specifies an alternative per-user configuration file.
+If a configuration file is given on the command line,
+the system-wide configuration file
+.Pq Pa /etc/ssh/ssh_config
+will be ignored.
+The default for the per-user configuration file is
+.Pa ~/.ssh/config .
+If set to
+.Dq none ,
+no configuration files will be read.
+.Pp
+.It Fl f
+Requests
+.Nm
+to go to background just before command execution.
+This is useful if
+.Nm
+is going to ask for passwords or passphrases, but the user
+wants it in the background.
+This implies
+.Fl n .
+The recommended way to start X11 programs at a remote site is with
+something like
+.Ic ssh -f host xterm .
+.Pp
+If the
+.Cm ExitOnForwardFailure
+configuration option is set to
+.Dq yes ,
+then a client started with
+.Fl f
+will wait for all remote port forwards to be successfully established
+before placing itself in the background.
+Refer to the description of
+.Cm ForkAfterAuthentication
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl G
+Causes
+.Nm
+to print its configuration after evaluating
+.Cm Host
+and
+.Cm Match
+blocks and exit.
+.Pp
+.It Fl g
+Allows remote hosts to connect to local forwarded ports.
+If used on a multiplexed connection, then this option must be specified
+on the master process.
+.Pp
+.It Fl I Ar pkcs11
+Specify the PKCS#11 shared library
+.Nm
+should use to communicate with a PKCS#11 token providing keys for user
+authentication.
+.Pp
+.It Fl i Ar identity_file
+Selects a file from which the identity (private key) for
+public key authentication is read.
+You can also specify a public key file to use the corresponding
+private key that is loaded in
+.Xr ssh-agent 1
+when the private key file is not present locally.
+The default is
+.Pa ~/.ssh/id_rsa ,
+.Pa ~/.ssh/id_ecdsa ,
+.Pa ~/.ssh/id_ecdsa_sk ,
+.Pa ~/.ssh/id_ed25519 ,
+.Pa ~/.ssh/id_ed25519_sk
+and
+.Pa ~/.ssh/id_dsa .
+Identity files may also be specified on
+a per-host basis in the configuration file.
+It is possible to have multiple
+.Fl i
+options (and multiple identities specified in
+configuration files).
+If no certificates have been explicitly specified by the
+.Cm CertificateFile
+directive,
+.Nm
+will also try to load certificate information from the filename obtained
+by appending
+.Pa -cert.pub
+to identity filenames.
+.Pp
+.It Fl J Ar destination
+Connect to the target host by first making a
+.Nm
+connection to the jump host described by
+.Ar destination
+and then establishing a TCP forwarding to the ultimate destination from
+there.
+Multiple jump hops may be specified separated by comma characters.
+This is a shortcut to specify a
+.Cm ProxyJump
+configuration directive.
+Note that configuration directives supplied on the command-line generally
+apply to the destination host and not any specified jump hosts.
+Use
+.Pa ~/.ssh/config
+to specify configuration for jump hosts.
+.Pp
+.It Fl K
+Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI
+credentials to the server.
+.Pp
+.It Fl k
+Disables forwarding (delegation) of GSSAPI credentials to the server.
+.Pp
+.It Fl L Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : host : hostport
+.Sm on
+.Xc
+.It Fl L Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : remote_socket
+.Sm on
+.Xc
+.It Fl L Xo
+.Sm off
+.Ar local_socket : host : hostport
+.Sm on
+.Xc
+.It Fl L Xo
+.Sm off
+.Ar local_socket : remote_socket
+.Sm on
+.Xc
+Specifies that connections to the given TCP port or Unix socket on the local
+(client) host are to be forwarded to the given host and port, or Unix socket,
+on the remote side.
+This works by allocating a socket to listen to either a TCP
+.Ar port
+on the local side, optionally bound to the specified
+.Ar bind_address ,
+or to a Unix socket.
+Whenever a connection is made to the local port or socket, the
+connection is forwarded over the secure channel, and a connection is
+made to either
+.Ar host
+port
+.Ar hostport ,
+or the Unix socket
+.Ar remote_socket ,
+from the remote machine.
+.Pp
+Port forwardings can also be specified in the configuration file.
+Only the superuser can forward privileged ports.
+IPv6 addresses can be specified by enclosing the address in square brackets.
+.Pp
+By default, the local port is bound in accordance with the
+.Cm GatewayPorts
+setting.
+However, an explicit
+.Ar bind_address
+may be used to bind the connection to a specific address.
+The
+.Ar bind_address
+of
+.Dq localhost
+indicates that the listening port be bound for local use only, while an
+empty address or
+.Sq *
+indicates that the port should be available from all interfaces.
+.Pp
+.It Fl l Ar login_name
+Specifies the user to log in as on the remote machine.
+This also may be specified on a per-host basis in the configuration file.
+.Pp
+.It Fl M
+Places the
+.Nm
+client into
+.Dq master
+mode for connection sharing.
+Multiple
+.Fl M
+options places
+.Nm
+into
+.Dq master
+mode but with confirmation required using
+.Xr ssh-askpass 1
+before each operation that changes the multiplexing state
+(e.g. opening a new session).
+Refer to the description of
+.Cm ControlMaster
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl m Ar mac_spec
+A comma-separated list of MAC (message authentication code) algorithms,
+specified in order of preference.
+See the
+.Cm MACs
+keyword in
+.Xr ssh_config 5
+for more information.
+.Pp
+.It Fl N
+Do not execute a remote command.
+This is useful for just forwarding ports.
+Refer to the description of
+.Cm SessionType
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl n
+Redirects stdin from
+.Pa /dev/null
+(actually, prevents reading from stdin).
+This must be used when
+.Nm
+is run in the background.
+A common trick is to use this to run X11 programs on a remote machine.
+For example,
+.Ic ssh -n shadows.cs.hut.fi emacs &
+will start an emacs on shadows.cs.hut.fi, and the X11
+connection will be automatically forwarded over an encrypted channel.
+The
+.Nm
+program will be put in the background.
+(This does not work if
+.Nm
+needs to ask for a password or passphrase; see also the
+.Fl f
+option.)
+Refer to the description of
+.Cm StdinNull
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl O Ar ctl_cmd
+Control an active connection multiplexing master process.
+When the
+.Fl O
+option is specified, the
+.Ar ctl_cmd
+argument is interpreted and passed to the master process.
+Valid commands are:
+.Dq check
+(check that the master process is running),
+.Dq forward
+(request forwardings without command execution),
+.Dq cancel
+(cancel forwardings),
+.Dq exit
+(request the master to exit), and
+.Dq stop
+(request the master to stop accepting further multiplexing requests).
+.Pp
+.It Fl o Ar option
+Can be used to give options in the format used in the configuration file.
+This is useful for specifying options for which there is no separate
+command-line flag.
+For full details of the options listed below, and their possible values, see
+.Xr ssh_config 5 .
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It AddKeysToAgent
+.It AddressFamily
+.It BatchMode
+.It BindAddress
+.It BindInterface
+.It CanonicalDomains
+.It CanonicalizeFallbackLocal
+.It CanonicalizeHostname
+.It CanonicalizeMaxDots
+.It CanonicalizePermittedCNAMEs
+.It CASignatureAlgorithms
+.It CertificateFile
+.It CheckHostIP
+.It Ciphers
+.It ClearAllForwardings
+.It Compression
+.It ConnectionAttempts
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
+.It ControlPersist
+.It DynamicForward
+.It EnableSSHKeysign
+.It EnableEscapeCommandline
+.It EscapeChar
+.It ExitOnForwardFailure
+.It FingerprintHash
+.It ForkAfterAuthentication
+.It ForwardAgent
+.It ForwardX11
+.It ForwardX11Timeout
+.It ForwardX11Trusted
+.It GatewayPorts
+.It GlobalKnownHostsFile
+.It GSSAPIAuthentication
+.It GSSAPIKeyExchange
+.It GSSAPIClientIdentity
+.It GSSAPIDelegateCredentials
+.It GSSAPIKexAlgorithms
+.It GSSAPIRenewalForcesRekey
+.It GSSAPIServerIdentity
+.It GSSAPITrustDns
+.It HashKnownHosts
+.It Host
+.It HostbasedAcceptedAlgorithms
+.It HostbasedAuthentication
+.It HostKeyAlgorithms
+.It HostKeyAlias
+.It Hostname
+.It IdentitiesOnly
+.It IdentityAgent
+.It IdentityFile
+.It IgnoreUnknown
+.It Include
+.It IPQoS
+.It KbdInteractiveAuthentication
+.It KbdInteractiveDevices
+.It KexAlgorithms
+.It KnownHostsCommand
+.It LocalCommand
+.It LocalForward
+.It LogLevel
+.It LogVerbose
+.It MACs
+.It Match
+.It NoHostAuthenticationForLocalhost
+.It NumberOfPasswordPrompts
+.It PasswordAuthentication
+.It PermitLocalCommand
+.It PermitRemoteOpen
+.It PKCS11Provider
+.It Port
+.It PreferredAuthentications
+.It ProxyCommand
+.It ProxyJump
+.It ProxyUseFdpass
+.It PubkeyAcceptedAlgorithms
+.It PubkeyAuthentication
+.It RekeyLimit
+.It RemoteCommand
+.It RemoteForward
+.It RequestTTY
+.It RevokedHostKeys
+.It SecurityKeyProvider
+.It RequiredRSASize
+.It SendEnv
+.It ServerAliveInterval
+.It ServerAliveCountMax
+.It SessionType
+.It SetEnv
+.It StdinNull
+.It StreamLocalBindMask
+.It StreamLocalBindUnlink
+.It StrictHostKeyChecking
+.It SyslogFacility
+.It TCPKeepAlive
+.It Tunnel
+.It TunnelDevice
+.It UpdateHostKeys
+.It User
+.It UserKnownHostsFile
+.It VerifyHostKeyDNS
+.It VisualHostKey
+.It XAuthLocation
+.El
+.Pp
+.It Fl p Ar port
+Port to connect to on the remote host.
+This can be specified on a
+per-host basis in the configuration file.
+.Pp
+.It Fl Q Ar query_option
+Queries for the algorithms supported by one of the following features:
+.Ar cipher
+(supported symmetric ciphers),
+.Ar cipher-auth
+(supported symmetric ciphers that support authenticated encryption),
+.Ar help
+(supported query terms for use with the
+.Fl Q
+flag),
+.Ar mac
+(supported message integrity codes),
+.Ar kex
+(key exchange algorithms),
+.Ar kex-gss
+(GSSAPI key exchange algorithms),
+.Ar key
+(key types),
+.Ar key-cert
+(certificate key types),
+.Ar key-plain
+(non-certificate key types),
+.Ar key-sig
+(all key types and signature algorithms),
+.Ar protocol-version
+(supported SSH protocol versions), and
+.Ar sig
+(supported signature algorithms).
+Alternatively, any keyword from
+.Xr ssh_config 5
+or
+.Xr sshd_config 5
+that takes an algorithm list may be used as an alias for the corresponding
+query_option.
+.Pp
+.It Fl q
+Quiet mode.
+Causes most warning and diagnostic messages to be suppressed.
+.Pp
+.It Fl R Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : host : hostport
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : local_socket
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Ar remote_socket : host : hostport
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Ar remote_socket : local_socket
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port
+.Sm on
+.Xc
+Specifies that connections to the given TCP port or Unix socket on the remote
+(server) host are to be forwarded to the local side.
+.Pp
+This works by allocating a socket to listen to either a TCP
+.Ar port
+or to a Unix socket on the remote side.
+Whenever a connection is made to this port or Unix socket, the
+connection is forwarded over the secure channel, and a connection
+is made from the local machine to either an explicit destination specified by
+.Ar host
+port
+.Ar hostport ,
+or
+.Ar local_socket ,
+or, if no explicit destination was specified,
+.Nm
+will act as a SOCKS 4/5 proxy and forward connections to the destinations
+requested by the remote SOCKS client.
+.Pp
+Port forwardings can also be specified in the configuration file.
+Privileged ports can be forwarded only when
+logging in as root on the remote machine.
+IPv6 addresses can be specified by enclosing the address in square brackets.
+.Pp
+By default, TCP listening sockets on the server will be bound to the loopback
+interface only.
+This may be overridden by specifying a
+.Ar bind_address .
+An empty
+.Ar bind_address ,
+or the address
+.Ql * ,
+indicates that the remote socket should listen on all interfaces.
+Specifying a remote
+.Ar bind_address
+will only succeed if the server's
+.Cm GatewayPorts
+option is enabled (see
+.Xr sshd_config 5 ) .
+.Pp
+If the
+.Ar port
+argument is
+.Ql 0 ,
+the listen port will be dynamically allocated on the server and reported
+to the client at run time.
+When used together with
+.Ic -O forward ,
+the allocated port will be printed to the standard output.
+.Pp
+.It Fl S Ar ctl_path
+Specifies the location of a control socket for connection sharing,
+or the string
+.Dq none
+to disable connection sharing.
+Refer to the description of
+.Cm ControlPath
+and
+.Cm ControlMaster
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl s
+May be used to request invocation of a subsystem on the remote system.
+Subsystems facilitate the use of SSH
+as a secure transport for other applications (e.g.\&
+.Xr sftp 1 ) .
+The subsystem is specified as the remote command.
+Refer to the description of
+.Cm SessionType
+in
+.Xr ssh_config 5
+for details.
+.Pp
+.It Fl T
+Disable pseudo-terminal allocation.
+.Pp
+.It Fl t
+Force pseudo-terminal allocation.
+This can be used to execute arbitrary
+screen-based programs on a remote machine, which can be very useful,
+e.g. when implementing menu services.
+Multiple
+.Fl t
+options force tty allocation, even if
+.Nm
+has no local tty.
+.Pp
+.It Fl V
+Display the version number and exit.
+.Pp
+.It Fl v
+Verbose mode.
+Causes
+.Nm
+to print debugging messages about its progress.
+This is helpful in
+debugging connection, authentication, and configuration problems.
+Multiple
+.Fl v
+options increase the verbosity.
+The maximum is 3.
+.Pp
+.It Fl W Ar host : Ns Ar port
+Requests that standard input and output on the client be forwarded to
+.Ar host
+on
+.Ar port
+over the secure channel.
+Implies
+.Fl N ,
+.Fl T ,
+.Cm ExitOnForwardFailure
+and
+.Cm ClearAllForwardings ,
+though these can be overridden in the configuration file or using
+.Fl o
+command line options.
+.Pp
+.It Fl w Xo
+.Ar local_tun Ns Op : Ns Ar remote_tun
+.Xc
+Requests
+tunnel
+device forwarding with the specified
+.Xr tun 4
+devices between the client
+.Pq Ar local_tun
+and the server
+.Pq Ar remote_tun .
+.Pp
+The devices may be specified by numerical ID or the keyword
+.Dq any ,
+which uses the next available tunnel device.
+If
+.Ar remote_tun
+is not specified, it defaults to
+.Dq any .
+See also the
+.Cm Tunnel
+and
+.Cm TunnelDevice
+directives in
+.Xr ssh_config 5 .
+.Pp
+If the
+.Cm Tunnel
+directive is unset, it will be set to the default tunnel mode, which is
+.Dq point-to-point .
+If a different
+.Cm Tunnel
+forwarding mode it desired, then it should be specified before
+.Fl w .
+.Pp
+.It Fl X
+Enables X11 forwarding.
+This can also be specified on a per-host basis in a configuration file.
+.Pp
+X11 forwarding should be enabled with caution.
+Users with the ability to bypass file permissions on the remote host
+(for the user's X authorization database)
+can access the local X11 display through the forwarded connection.
+An attacker may then be able to perform activities such as keystroke monitoring.
+.Pp
+For this reason, X11 forwarding is subjected to X11 SECURITY extension
+restrictions by default.
+Refer to the
+.Nm
+.Fl Y
+option and the
+.Cm ForwardX11Trusted
+directive in
+.Xr ssh_config 5
+for more information.
+.Pp
+.It Fl x
+Disables X11 forwarding.
+.Pp
+.It Fl Y
+Enables trusted X11 forwarding.
+Trusted X11 forwardings are not subjected to the X11 SECURITY extension
+controls.
+.Pp
+.It Fl y
+Send log information using the
+.Xr syslog 3
+system module.
+By default this information is sent to stderr.
+.El
+.Pp
+.Nm
+may additionally obtain configuration data from
+a per-user configuration file and a system-wide configuration file.
+The file format and configuration options are described in
+.Xr ssh_config 5 .
+.Sh AUTHENTICATION
+The OpenSSH SSH client supports SSH protocol 2.
+.Pp
+The methods available for authentication are:
+GSSAPI-based authentication,
+host-based authentication,
+public key authentication,
+keyboard-interactive authentication,
+and password authentication.
+Authentication methods are tried in the order specified above,
+though
+.Cm PreferredAuthentications
+can be used to change the default order.
+.Pp
+Host-based authentication works as follows:
+If the machine the user logs in from is listed in
+.Pa /etc/hosts.equiv
+or
+.Pa /etc/ssh/shosts.equiv
+on the remote machine, the user is non-root and the user names are
+the same on both sides, or if the files
+.Pa ~/.rhosts
+or
+.Pa ~/.shosts
+exist in the user's home directory on the
+remote machine and contain a line containing the name of the client
+machine and the name of the user on that machine, the user is
+considered for login.
+Additionally, the server
+.Em must
+be able to verify the client's
+host key (see the description of
+.Pa /etc/ssh/ssh_known_hosts
+and
+.Pa ~/.ssh/known_hosts ,
+below)
+for login to be permitted.
+This authentication method closes security holes due to IP
+spoofing, DNS spoofing, and routing spoofing.
+[Note to the administrator:
+.Pa /etc/hosts.equiv ,
+.Pa ~/.rhosts ,
+and the rlogin/rsh protocol in general, are inherently insecure and should be
+disabled if security is desired.]
+.Pp
+Public key authentication works as follows:
+The scheme is based on public-key cryptography,
+using cryptosystems
+where encryption and decryption are done using separate keys,
+and it is unfeasible to derive the decryption key from the encryption key.
+The idea is that each user creates a public/private
+key pair for authentication purposes.
+The server knows the public key, and only the user knows the private key.
+.Nm
+implements public key authentication protocol automatically,
+using one of the DSA, ECDSA, Ed25519 or RSA algorithms.
+The HISTORY section of
+.Xr ssl 8
+contains a brief discussion of the DSA and RSA algorithms.
+.Pp
+The file
+.Pa ~/.ssh/authorized_keys
+lists the public keys that are permitted for logging in.
+When the user logs in, the
+.Nm
+program tells the server which key pair it would like to use for
+authentication.
+The client proves that it has access to the private key
+and the server checks that the corresponding public key
+is authorized to accept the account.
+.Pp
+The server may inform the client of errors that prevented public key
+authentication from succeeding after authentication completes using a
+different method.
+These may be viewed by increasing the
+.Cm LogLevel
+to
+.Cm DEBUG
+or higher (e.g. by using the
+.Fl v
+flag).
+.Pp
+The user creates their key pair by running
+.Xr ssh-keygen 1 .
+This stores the private key in
+.Pa ~/.ssh/id_dsa
+(DSA),
+.Pa ~/.ssh/id_ecdsa
+(ECDSA),
+.Pa ~/.ssh/id_ecdsa_sk
+(authenticator-hosted ECDSA),
+.Pa ~/.ssh/id_ed25519
+(Ed25519),
+.Pa ~/.ssh/id_ed25519_sk
+(authenticator-hosted Ed25519),
+or
+.Pa ~/.ssh/id_rsa
+(RSA)
+and stores the public key in
+.Pa ~/.ssh/id_dsa.pub
+(DSA),
+.Pa ~/.ssh/id_ecdsa.pub
+(ECDSA),
+.Pa ~/.ssh/id_ecdsa_sk.pub
+(authenticator-hosted ECDSA),
+.Pa ~/.ssh/id_ed25519.pub
+(Ed25519),
+.Pa ~/.ssh/id_ed25519_sk.pub
+(authenticator-hosted Ed25519),
+or
+.Pa ~/.ssh/id_rsa.pub
+(RSA)
+in the user's home directory.
+The user should then copy the public key
+to
+.Pa ~/.ssh/authorized_keys
+in their home directory on the remote machine.
+The
+.Pa authorized_keys
+file corresponds to the conventional
+.Pa ~/.rhosts
+file, and has one key
+per line, though the lines can be very long.
+After this, the user can log in without giving the password.
+.Pp
+A variation on public key authentication
+is available in the form of certificate authentication:
+instead of a set of public/private keys,
+signed certificates are used.
+This has the advantage that a single trusted certification authority
+can be used in place of many public/private keys.
+See the CERTIFICATES section of
+.Xr ssh-keygen 1
+for more information.
+.Pp
+The most convenient way to use public key or certificate authentication
+may be with an authentication agent.
+See
+.Xr ssh-agent 1
+and (optionally) the
+.Cm AddKeysToAgent
+directive in
+.Xr ssh_config 5
+for more information.
+.Pp
+Keyboard-interactive authentication works as follows:
+The server sends an arbitrary
+.Qq challenge
+text and prompts for a response, possibly multiple times.
+Examples of keyboard-interactive authentication include
+.Bx
+Authentication (see
+.Xr login.conf 5 )
+and PAM (some
+.Pf non- Ox
+systems).
+.Pp
+Finally, if other authentication methods fail,
+.Nm
+prompts the user for a password.
+The password is sent to the remote
+host for checking; however, since all communications are encrypted,
+the password cannot be seen by someone listening on the network.
+.Pp
+.Nm
+automatically maintains and checks a database containing
+identification for all hosts it has ever been used with.
+Host keys are stored in
+.Pa ~/.ssh/known_hosts
+in the user's home directory.
+Additionally, the file
+.Pa /etc/ssh/ssh_known_hosts
+is automatically checked for known hosts.
+Any new hosts are automatically added to the user's file.
+If a host's identification ever changes,
+.Nm
+warns about this and disables password authentication to prevent
+server spoofing or man-in-the-middle attacks,
+which could otherwise be used to circumvent the encryption.
+The
+.Cm StrictHostKeyChecking
+option can be used to control logins to machines whose
+host key is not known or has changed.
+.Pp
+When the user's identity has been accepted by the server, the server
+either executes the given command in a non-interactive session or,
+if no command has been specified, logs into the machine and gives
+the user a normal shell as an interactive session.
+All communication with
+the remote command or shell will be automatically encrypted.
+.Pp
+If an interactive session is requested,
+.Nm
+by default will only request a pseudo-terminal (pty) for interactive
+sessions when the client has one.
+The flags
+.Fl T
+and
+.Fl t
+can be used to override this behaviour.
+.Pp
+If a pseudo-terminal has been allocated, the
+user may use the escape characters noted below.
+.Pp
+If no pseudo-terminal has been allocated,
+the session is transparent and can be used to reliably transfer binary data.
+On most systems, setting the escape character to
+.Dq none
+will also make the session transparent even if a tty is used.
+.Pp
+The session terminates when the command or shell on the remote
+machine exits and all X11 and TCP connections have been closed.
+.Sh ESCAPE CHARACTERS
+When a pseudo-terminal has been requested,
+.Nm
+supports a number of functions through the use of an escape character.
+.Pp
+A single tilde character can be sent as
+.Ic ~~
+or by following the tilde by a character other than those described below.
+The escape character must always follow a newline to be interpreted as
+special.
+The escape character can be changed in configuration files using the
+.Cm EscapeChar
+configuration directive or on the command line by the
+.Fl e
+option.
+.Pp
+The supported escapes (assuming the default
+.Ql ~ )
+are:
+.Bl -tag -width Ds
+.It Cm ~.
+Disconnect.
+.It Cm ~^Z
+Background
+.Nm .
+.It Cm ~#
+List forwarded connections.
+.It Cm ~&
+Background
+.Nm
+at logout when waiting for forwarded connection / X11 sessions to terminate.
+.It Cm ~?
+Display a list of escape characters.
+.It Cm ~B
+Send a BREAK to the remote system
+(only useful if the peer supports it).
+.It Cm ~C
+Open command line.
+Currently this allows the addition of port forwardings using the
+.Fl L ,
+.Fl R
+and
+.Fl D
+options (see above).
+It also allows the cancellation of existing port-forwardings
+with
+.Sm off
+.Fl KL Oo Ar bind_address : Oc Ar port
+.Sm on
+for local,
+.Sm off
+.Fl KR Oo Ar bind_address : Oc Ar port
+.Sm on
+for remote and
+.Sm off
+.Fl KD Oo Ar bind_address : Oc Ar port
+.Sm on
+for dynamic port-forwardings.
+.Ic !\& Ns Ar command
+allows the user to execute a local command if the
+.Ic PermitLocalCommand
+option is enabled in
+.Xr ssh_config 5 .
+Basic help is available, using the
+.Fl h
+option.
+.It Cm ~R
+Request rekeying of the connection
+(only useful if the peer supports it).
+.It Cm ~V
+Decrease the verbosity
+.Pq Ic LogLevel
+when errors are being written to stderr.
+.It Cm ~v
+Increase the verbosity
+.Pq Ic LogLevel
+when errors are being written to stderr.
+.El
+.Sh TCP FORWARDING
+Forwarding of arbitrary TCP connections over a secure channel
+can be specified either on the command line or in a configuration file.
+One possible application of TCP forwarding is a secure connection to a
+mail server; another is going through firewalls.
+.Pp
+In the example below, we look at encrypting communication for an IRC client,
+even though the IRC server it connects to does not directly
+support encrypted communication.
+This works as follows:
+the user connects to the remote host using
+.Nm ,
+specifying the ports to be used to forward the connection.
+After that it is possible to start the program locally,
+and
+.Nm
+will encrypt and forward the connection to the remote server.
+.Pp
+The following example tunnels an IRC session from the client
+to an IRC server at
+.Dq server.example.com ,
+joining channel
+.Dq #users ,
+nickname
+.Dq pinky ,
+using the standard IRC port, 6667:
+.Bd -literal -offset 4n
+$ ssh -f -L 6667:localhost:6667 server.example.com sleep 10
+$ irc -c '#users' pinky IRC/127.0.0.1
+.Ed
+.Pp
+The
+.Fl f
+option backgrounds
+.Nm
+and the remote command
+.Dq sleep 10
+is specified to allow an amount of time
+(10 seconds, in the example)
+to start the program which is going to use the tunnel.
+If no connections are made within the time specified,
+.Nm
+will exit.
+.Sh X11 FORWARDING
+If the
+.Cm ForwardX11
+variable is set to
+.Dq yes
+(or see the description of the
+.Fl X ,
+.Fl x ,
+and
+.Fl Y
+options above)
+and the user is using X11 (the
+.Ev DISPLAY
+environment variable is set), the connection to the X11 display is
+automatically forwarded to the remote side in such a way that any X11
+programs started from the shell (or command) will go through the
+encrypted channel, and the connection to the real X server will be made
+from the local machine.
+The user should not manually set
+.Ev DISPLAY .
+Forwarding of X11 connections can be
+configured on the command line or in configuration files.
+.Pp
+The
+.Ev DISPLAY
+value set by
+.Nm
+will point to the server machine, but with a display number greater than zero.
+This is normal, and happens because
+.Nm
+creates a
+.Dq proxy
+X server on the server machine for forwarding the
+connections over the encrypted channel.
+.Pp
+.Nm
+will also automatically set up Xauthority data on the server machine.
+For this purpose, it will generate a random authorization cookie,
+store it in Xauthority on the server, and verify that any forwarded
+connections carry this cookie and replace it by the real cookie when
+the connection is opened.
+The real authentication cookie is never
+sent to the server machine (and no cookies are sent in the plain).
+.Pp
+If the
+.Cm ForwardAgent
+variable is set to
+.Dq yes
+(or see the description of the
+.Fl A
+and
+.Fl a
+options above) and
+the user is using an authentication agent, the connection to the agent
+is automatically forwarded to the remote side.
+.Sh VERIFYING HOST KEYS
+When connecting to a server for the first time,
+a fingerprint of the server's public key is presented to the user
+(unless the option
+.Cm StrictHostKeyChecking
+has been disabled).
+Fingerprints can be determined using
+.Xr ssh-keygen 1 :
+.Pp
+.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
+.Pp
+If the fingerprint is already known, it can be matched
+and the key can be accepted or rejected.
+If only legacy (MD5) fingerprints for the server are available, the
+.Xr ssh-keygen 1
+.Fl E
+option may be used to downgrade the fingerprint algorithm to match.
+.Pp
+Because of the difficulty of comparing host keys
+just by looking at fingerprint strings,
+there is also support to compare host keys visually,
+using
+.Em random art .
+By setting the
+.Cm VisualHostKey
+option to
+.Dq yes ,
+a small ASCII graphic gets displayed on every login to a server, no matter
+if the session itself is interactive or not.
+By learning the pattern a known server produces, a user can easily
+find out that the host key has changed when a completely different pattern
+is displayed.
+Because these patterns are not unambiguous however, a pattern that looks
+similar to the pattern remembered only gives a good probability that the
+host key is the same, not guaranteed proof.
+.Pp
+To get a listing of the fingerprints along with their random art for
+all known hosts, the following command line can be used:
+.Pp
+.Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts
+.Pp
+If the fingerprint is unknown,
+an alternative method of verification is available:
+SSH fingerprints verified by DNS.
+An additional resource record (RR),
+SSHFP,
+is added to a zonefile
+and the connecting client is able to match the fingerprint
+with that of the key presented.
+.Pp
+In this example, we are connecting a client to a server,
+.Dq host.example.com .
+The SSHFP resource records should first be added to the zonefile for
+host.example.com:
+.Bd -literal -offset indent
+$ ssh-keygen -r host.example.com.
+.Ed
+.Pp
+The output lines will have to be added to the zonefile.
+To check that the zone is answering fingerprint queries:
+.Pp
+.Dl $ dig -t SSHFP host.example.com
+.Pp
+Finally the client connects:
+.Bd -literal -offset indent
+$ ssh -o "VerifyHostKeyDNS ask" host.example.com
+[...]
+Matching host key fingerprint found in DNS.
+Are you sure you want to continue connecting (yes/no)?
+.Ed
+.Pp
+See the
+.Cm VerifyHostKeyDNS
+option in
+.Xr ssh_config 5
+for more information.
+.Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
+.Nm
+contains support for Virtual Private Network (VPN) tunnelling
+using the
+.Xr tun 4
+network pseudo-device,
+allowing two networks to be joined securely.
+The
+.Xr sshd_config 5
+configuration option
+.Cm PermitTunnel
+controls whether the server supports this,
+and at what level (layer 2 or 3 traffic).
+.Pp
+The following example would connect client network 10.0.50.0/24
+with remote network 10.0.99.0/24 using a point-to-point connection
+from 10.1.1.1 to 10.1.1.2,
+provided that the SSH server running on the gateway to the remote network,
+at 192.168.1.15, allows it.
+.Pp
+On the client:
+.Bd -literal -offset indent
+# ssh -f -w 0:1 192.168.1.15 true
+# ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
+# route add 10.0.99.0/24 10.1.1.2
+.Ed
+.Pp
+On the server:
+.Bd -literal -offset indent
+# ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
+# route add 10.0.50.0/24 10.1.1.1
+.Ed
+.Pp
+Client access may be more finely tuned via the
+.Pa /root/.ssh/authorized_keys
+file (see below) and the
+.Cm PermitRootLogin
+server option.
+The following entry would permit connections on
+.Xr tun 4
+device 1 from user
+.Dq jane
+and on tun device 2 from user
+.Dq john ,
+if
+.Cm PermitRootLogin
+is set to
+.Dq forced-commands-only :
+.Bd -literal -offset 2n
+tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
+tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john
+.Ed
+.Pp
+Since an SSH-based setup entails a fair amount of overhead,
+it may be more suited to temporary setups,
+such as for wireless VPNs.
+More permanent VPNs are better provided by tools such as
+.Xr ipsecctl 8
+and
+.Xr isakmpd 8 .
+.Sh ENVIRONMENT
+.Nm
+will normally set the following environment variables:
+.Bl -tag -width "SSH_ORIGINAL_COMMAND"
+.It Ev DISPLAY
+The
+.Ev DISPLAY
+variable indicates the location of the X11 server.
+It is automatically set by
+.Nm
+to point to a value of the form
+.Dq hostname:n ,
+where
+.Dq hostname
+indicates the host where the shell runs, and
+.Sq n
+is an integer \*(Ge 1.
+.Nm
+uses this special value to forward X11 connections over the secure
+channel.
+The user should normally not set
+.Ev DISPLAY
+explicitly, as that
+will render the X11 connection insecure (and will require the user to
+manually copy any required authorization cookies).
+.It Ev HOME
+Set to the path of the user's home directory.
+.It Ev LOGNAME
+Synonym for
+.Ev USER ;
+set for compatibility with systems that use this variable.
+.It Ev MAIL
+Set to the path of the user's mailbox.
+.It Ev PATH
+Set to the default
+.Ev PATH ,
+as specified when compiling
+.Nm .
+.It Ev SSH_ASKPASS
+If
+.Nm
+needs a passphrase, it will read the passphrase from the current
+terminal if it was run from a terminal.
+If
+.Nm
+does not have a terminal associated with it but
+.Ev DISPLAY
+and
+.Ev SSH_ASKPASS
+are set, it will execute the program specified by
+.Ev SSH_ASKPASS
+and open an X11 window to read the passphrase.
+This is particularly useful when calling
+.Nm
+from a
+.Pa .xsession
+or related script.
+(Note that on some machines it
+may be necessary to redirect the input from
+.Pa /dev/null
+to make this work.)
+.It Ev SSH_ASKPASS_REQUIRE
+Allows further control over the use of an askpass program.
+If this variable is set to
+.Dq never
+then
+.Nm
+will never attempt to use one.
+If it is set to
+.Dq prefer ,
+then
+.Nm
+will prefer to use the askpass program instead of the TTY when requesting
+passwords.
+Finally, if the variable is set to
+.Dq force ,
+then the askpass program will be used for all passphrase input regardless
+of whether
+.Ev DISPLAY
+is set.
+.It Ev SSH_AUTH_SOCK
+Identifies the path of a
+.Ux Ns -domain
+socket used to communicate with the agent.
+.It Ev SSH_CONNECTION
+Identifies the client and server ends of the connection.
+The variable contains
+four space-separated values: client IP address, client port number,
+server IP address, and server port number.
+.It Ev SSH_ORIGINAL_COMMAND
+This variable contains the original command line if a forced command
+is executed.
+It can be used to extract the original arguments.
+.It Ev SSH_TTY
+This is set to the name of the tty (path to the device) associated
+with the current shell or command.
+If the current session has no tty,
+this variable is not set.
+.It Ev SSH_TUNNEL
+Optionally set by
+.Xr sshd 8
+to contain the interface names assigned if tunnel forwarding was
+requested by the client.
+.It Ev SSH_USER_AUTH
+Optionally set by
+.Xr sshd 8 ,
+this variable may contain a pathname to a file that lists the authentication
+methods successfully used when the session was established, including any
+public keys that were used.
+.It Ev TZ
+This variable is set to indicate the present time zone if it
+was set when the daemon was started (i.e. the daemon passes the value
+on to new connections).
+.It Ev USER
+Set to the name of the user logging in.
+.El
+.Pp
+Additionally,
+.Nm
+reads
+.Pa ~/.ssh/environment ,
+and adds lines of the format
+.Dq VARNAME=value
+to the environment if the file exists and users are allowed to
+change their environment.
+For more information, see the
+.Cm PermitUserEnvironment
+option in
+.Xr sshd_config 5 .
+.Sh FILES
+.Bl -tag -width Ds -compact
+.It Pa ~/.rhosts
+This file is used for host-based authentication (see above).
+On some machines this file may need to be
+world-readable if the user's home directory is on an NFS partition,
+because
+.Xr sshd 8
+reads it as root.
+Additionally, this file must be owned by the user,
+and must not have write permissions for anyone else.
+The recommended
+permission for most machines is read/write for the user, and not
+accessible by others.
+.Pp
+.It Pa ~/.shosts
+This file is used in exactly the same way as
+.Pa .rhosts ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
+.Pp
+.It Pa ~/.ssh/
+This directory is the default location for all user-specific configuration
+and authentication information.
+There is no general requirement to keep the entire contents of this directory
+secret, but the recommended permissions are read/write/execute for the user,
+and not accessible by others.
+.Pp
+.It Pa ~/.ssh/authorized_keys
+Lists the public keys (DSA, ECDSA, Ed25519, RSA)
+that can be used for logging in as this user.
+The format of this file is described in the
+.Xr sshd 8
+manual page.
+This file is not highly sensitive, but the recommended
+permissions are read/write for the user, and not accessible by others.
+.Pp
+.It Pa ~/.ssh/config
+This is the per-user configuration file.
+The file format and configuration options are described in
+.Xr ssh_config 5 .
+Because of the potential for abuse, this file must have strict permissions:
+read/write for the user, and not writable by others.
+.Pp
+.It Pa ~/.ssh/environment
+Contains additional definitions for environment variables; see
+.Sx ENVIRONMENT ,
+above.
+.Pp
+.It Pa ~/.ssh/id_dsa
+.It Pa ~/.ssh/id_ecdsa
+.It Pa ~/.ssh/id_ecdsa_sk
+.It Pa ~/.ssh/id_ed25519
+.It Pa ~/.ssh/id_ed25519_sk
+.It Pa ~/.ssh/id_rsa
+Contains the private key for authentication.
+These files
+contain sensitive data and should be readable by the user but not
+accessible by others (read/write/execute).
+.Nm
+will simply ignore a private key file if it is accessible by others.
+It is possible to specify a passphrase when
+generating the key which will be used to encrypt the
+sensitive part of this file using AES-128.
+.Pp
+.It Pa ~/.ssh/id_dsa.pub
+.It Pa ~/.ssh/id_ecdsa.pub
+.It Pa ~/.ssh/id_ecdsa_sk.pub
+.It Pa ~/.ssh/id_ed25519.pub
+.It Pa ~/.ssh/id_ed25519_sk.pub
+.It Pa ~/.ssh/id_rsa.pub
+Contains the public key for authentication.
+These files are not
+sensitive and can (but need not) be readable by anyone.
+.Pp
+.It Pa ~/.ssh/known_hosts
+Contains a list of host keys for all hosts the user has logged into
+that are not already in the systemwide list of known host keys.
+See
+.Xr sshd 8
+for further details of the format of this file.
+.Pp
+.It Pa ~/.ssh/rc
+Commands in this file are executed by
+.Nm
+when the user logs in, just before the user's shell (or command) is
+started.
+See the
+.Xr sshd 8
+manual page for more information.
+.Pp
+.It Pa /etc/hosts.equiv
+This file is for host-based authentication (see above).
+It should only be writable by root.
+.Pp
+.It Pa /etc/ssh/shosts.equiv
+This file is used in exactly the same way as
+.Pa hosts.equiv ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
+.Pp
+.It Pa /etc/ssh/ssh_config
+Systemwide configuration file.
+The file format and configuration options are described in
+.Xr ssh_config 5 .
+.Pp
+.It Pa /etc/ssh/ssh_host_key
+.It Pa /etc/ssh/ssh_host_dsa_key
+.It Pa /etc/ssh/ssh_host_ecdsa_key
+.It Pa /etc/ssh/ssh_host_ed25519_key
+.It Pa /etc/ssh/ssh_host_rsa_key
+These files contain the private parts of the host keys
+and are used for host-based authentication.
+.Pp
+.It Pa /etc/ssh/ssh_known_hosts
+Systemwide list of known host keys.
+This file should be prepared by the
+system administrator to contain the public host keys of all machines in the
+organization.
+It should be world-readable.
+See
+.Xr sshd 8
+for further details of the format of this file.
+.Pp
+.It Pa /etc/ssh/sshrc
+Commands in this file are executed by
+.Nm
+when the user logs in, just before the user's shell (or command) is started.
+See the
+.Xr sshd 8
+manual page for more information.
+.El
+.Sh EXIT STATUS
+.Nm
+exits with the exit status of the remote command or with 255
+if an error occurred.
+.Sh IPV6
+IPv6 address can be used everywhere where IPv4 address. In all entries must be the IPv6 address enclosed in square brackets. Note: The square brackets are metacharacters for the shell and must be escaped in shell.
+.Sh SEE ALSO
+.Xr scp 1 ,
+.Xr sftp 1 ,
+.Xr ssh-add 1 ,
+.Xr ssh-agent 1 ,
+.Xr ssh-keygen 1 ,
+.Xr ssh-keyscan 1 ,
+.Xr tun 4 ,
+.Xr ssh_config 5 ,
+.Xr ssh-keysign 8 ,
+.Xr sshd 8
+.Sh STANDARDS
+.Rs
+.%A S. Lehtinen
+.%A C. Lonvick
+.%D January 2006
+.%R RFC 4250
+.%T The Secure Shell (SSH) Protocol Assigned Numbers
+.Re
+.Pp
+.Rs
+.%A T. Ylonen
+.%A C. Lonvick
+.%D January 2006
+.%R RFC 4251
+.%T The Secure Shell (SSH) Protocol Architecture
+.Re
+.Pp
+.Rs
+.%A T. Ylonen
+.%A C. Lonvick
+.%D January 2006
+.%R RFC 4252
+.%T The Secure Shell (SSH) Authentication Protocol
+.Re
+.Pp
+.Rs
+.%A T. Ylonen
+.%A C. Lonvick
+.%D January 2006
+.%R RFC 4253
+.%T The Secure Shell (SSH) Transport Layer Protocol
+.Re
+.Pp
+.Rs
+.%A T. Ylonen
+.%A C. Lonvick
+.%D January 2006
+.%R RFC 4254
+.%T The Secure Shell (SSH) Connection Protocol
+.Re
+.Pp
+.Rs
+.%A J. Schlyter
+.%A W. Griffin
+.%D January 2006
+.%R RFC 4255
+.%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
+.Re
+.Pp
+.Rs
+.%A F. Cusack
+.%A M. Forssen
+.%D January 2006
+.%R RFC 4256
+.%T Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
+.Re
+.Pp
+.Rs
+.%A J. Galbraith
+.%A P. Remaker
+.%D January 2006
+.%R RFC 4335
+.%T The Secure Shell (SSH) Session Channel Break Extension
+.Re
+.Pp
+.Rs
+.%A M. Bellare
+.%A T. Kohno
+.%A C. Namprempre
+.%D January 2006
+.%R RFC 4344
+.%T The Secure Shell (SSH) Transport Layer Encryption Modes
+.Re
+.Pp
+.Rs
+.%A B. Harris
+.%D January 2006
+.%R RFC 4345
+.%T Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol
+.Re
+.Pp
+.Rs
+.%A M. Friedl
+.%A N. Provos
+.%A W. Simpson
+.%D March 2006
+.%R RFC 4419
+.%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol
+.Re
+.Pp
+.Rs
+.%A J. Galbraith
+.%A R. Thayer
+.%D November 2006
+.%R RFC 4716
+.%T The Secure Shell (SSH) Public Key File Format
+.Re
+.Pp
+.Rs
+.%A D. Stebila
+.%A J. Green
+.%D December 2009
+.%R RFC 5656
+.%T Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer
+.Re
+.Pp
+.Rs
+.%A A. Perrig
+.%A D. Song
+.%D 1999
+.%O International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
+.%T Hash Visualization: a New Technique to improve Real-World Security
+.Re
+.Sh AUTHORS
+OpenSSH is a derivative of the original and free
+ssh 1.2.12 release by Tatu Ylonen.
+Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
+Theo de Raadt and Dug Song
+removed many bugs, re-added newer features and
+created OpenSSH.
+Markus Friedl contributed the support for SSH
+protocol versions 1.5 and 2.0.
diff --git a/upstream/mageia-cauldron/man1/ssindex.1 b/upstream/mageia-cauldron/man1/ssindex.1
new file mode 100644
index 00000000..58f1ac2b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ssindex.1
@@ -0,0 +1,88 @@
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH SSINDEX 1 "2009-02-08" gnumeric "GNOME"
+.SH NAME
+ssindex \- generate index data for spreadsheet files
+
+.SH SYNOPSIS
+\fBssindex \fR [\fIOPTIONS\fR] [\fIFILES\fR]
+
+.SH DESCRIPTION
+This manual page briefly documents the \fBssindex\fR command.
+
+\fBssindex\fR is a command line utility to generate index data for
+various spreadsheet file formats. It is primarily used by the \fBBeagle\fR
+indexing sub-system and search aggregator.
+
+.\".SH "RETURN VALUE"
+.\".SH "EXIT STATUS"
+.\".SH ERRORS
+.SH OPTIONS
+This program follows the usual GNU command line syntax, with single
+letter options starting with a single dash (`-') and longer options
+starting with two dashes (`--').
+
+.SS "Main options"
+.TP
+.B \-E, \-\-import\-encoding=\fIENCODING\fR
+Specify an encoding for imported content
+.TP
+.B \-i, \-\-index
+Index the given files
+.TP
+.B \-m, \-\-list\-mime\-types
+List the MIME types which ssindex is able to read
+
+.SS "Help options"
+.TP
+.B \-v, \-\-version
+Display ssindex's version
+.TP
+.B \-?, \-\-help
+Display the supported options
+.TP
+.B \-\-usage
+Display a brief usage message
+
+.\".SH USAGE
+.\".SH EXAMPLES
+.\".SH FILES
+.\".SH ENVIRONMENT
+.\".SH DIAGNOSTICS
+.\".SH SECURITY
+.\".SH CONFORMING TO
+.\".SH NOTES
+.\".SH BUGS
+
+.SH LICENSE
+
+\fBssindex\fR is licensed under the terms of the General Public
+License (GPL), version 2 or 3. For information on this license look at the
+source code that came with the software or see the
+.URL "http://www.gnu.org" "GNU project page" .
+
+.SH COPYRIGHT
+
+The copyright on \fBssindex\fR and the \fBgnumeric\fR software and source
+code is held by the individual authors as is documented in the source code.
+
+.SH AUTHOR
+
+\fBssindex\fR's primary author is Jody Goldberg <jody@gnome.org>;
+\fBssindex\fR builds on the \fBgnumeric\fR codebase.
+
+The initial version of this manpage was written by J.H.M. Dassen (Ray)
+<jdassen@debian.org>.
+
+.SH SEE ALSO
+\fBbeagled\fR(1),
+\fBgnumeric\fR(1),
+\fBssconvert\fR(1),
+\fBssdiff\fR(1)
+\fBssgrep\fR(1)
+
+.URL "http://www.gnome.org/projects/gnumeric/" "The Gnumeric Homepage" .
+
+.URL "http://www.gnome.org/" "The GNOME project page" .
diff --git a/upstream/mageia-cauldron/man1/st4topgm.1 b/upstream/mageia-cauldron/man1/st4topgm.1
new file mode 100644
index 00000000..222930db
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/st4topgm.1
@@ -0,0 +1,81 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "St4topgm User Manual" 0 "20 January 2015" "netpbm documentation"
+
+.SH NAME
+
+st4topgm - convert an SBIG ST-4 camera file to PGM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBst4topgm\fP
+
+[\fIst4file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBst4topgm\fP reads an image file in the native format used
+by the Santa Barbara Instrument Group (SBIG) ST-4 astronomical CCD cameras,
+and produces a PGM image as output.  This format is not to be confused with
+the format most other SBIG cameras use, for which you can use
+\fBsbigtopgm\fP.
+.PP
+Additional information on SBIG cameras and documentation of the file format
+is available at the Web
+site, 
+.UR http://www.sbig.com/
+http://www.sbig.com/
+.UE
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBst4topgm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pgmtost4" (1)\c
+\&
+.BR "sbigtopgm" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Bryan Henderson wrote \fBst4topgm\fP for Sourceforge Netpbm in 
+January 2015.  However, there has been another program by the same name for
+the same purpose since December 2003, in the Debian version of Netpbm.
+It was written by Justin Pryzby <justinpryzby@users.sf.net>.
+.PP
+Bryan discovered the Debian version when Prophet of the Way did a
+comparison of the two Netpbms in January 2015.  It was the only program that
+the Debian version had that the Netpbm version did not (not counting one that
+really didn't belong in any Netpbm), so Bryan decided to add it.  Because it
+was a small program, Bryan decided to write a replacement in the Netpbm coding
+style rather than just copy Pryzby's code, but Bryan endeavoured to keep the
+same function.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/st4topgm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/startx.1 b/upstream/mageia-cauldron/man1/startx.1
new file mode 100644
index 00000000..f445876d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/startx.1
@@ -0,0 +1,208 @@
+.\"
+.\" Copyright 1993, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.\"
+.TH STARTX 1 "xinit 1.4.2" "X Version 11"
+.SH NAME
+startx \- initialize an X session
+.SH SYNOPSIS
+.B startx
+[ [
+.I client
+]
+.I options
+\&\.\|.\|. ] [
+.B \-\^\-
+[
+.I server
+] [
+.I display
+]
+.I options
+\&.\|.\|. ]
+.SH DESCRIPTION
+The \fBstartx\fP script is a front end to
+.BR xinit (1)
+that provides a
+somewhat nicer user interface for running a single session of the X
+Window System.  It is often run with no arguments.
+.PP
+Arguments immediately following the
+.I startx
+command are used to start a client in the same manner as
+.BR xinit (1).
+The special argument
+.RB '\-\^\-'
+marks the end of client arguments and the beginning of server options.
+It may be convenient to specify server options with startx to change them on a
+per-session basis.
+Some examples of specifying server arguments follow; consult
+the manual page for your X server to determine which arguments are legal.
+.RS
+.PP
+startx \-\^\- \-depth 16
+.PP
+startx \-\^\- \-dpi 100
+.PP
+startx \-\^\- \-layout Multihead
+.RE
+.PP
+To determine the client to run,
+.B startx
+first checks the environment variable
+.I XINITRC
+for a filename. If that variable is unset, or does not contain a filename,
+it looks for a file called
+.I .xinitrc
+in the user's home directory.  If that is not found, it uses
+the file
+.I xinitrc
+in the
+.I xinit
+library directory.
+If command line client options are given, they override this
+behavior and revert to the
+.BR xinit (1)
+behavior.
+To determine the server to run,
+.B startx
+checks the environment variable
+.I XSERVERRC
+for a filename. If that variable is unset, or does not contain a filename,
+it looks for a file called
+.I .xserverrc
+in the user's home directory.  If that is not found, it uses
+the file
+.I xserverrc
+in the
+.I xinit
+library directory.
+If command line server options are given, they override this
+behavior and revert to the
+.BR xinit (1)
+behavior.  Users rarely need to provide a
+.I .xserverrc
+file.
+See the
+.BR xinit (1)
+manual page for more details on the arguments.
+.PP
+The system-wide
+.I xinitrc
+and
+.I xserverrc
+files are found in the
+.I /etc/X11/xinit
+directory.
+.PP
+The
+.I .xinitrc
+is typically a shell script which starts many clients according to the
+user's preference.  When this shell script exits,
+.B startx
+kills the server and performs any other session shutdown needed.
+Most of the clients started by
+.I .xinitrc
+should be run in the background.  The last client should run in the
+foreground; when it exits, the session will exit.  People often choose
+a session manager, window manager, or \fIxterm\fP as the ''magic'' client.
+.SH EXAMPLE
+.PP
+Below is a sample \fI\.xinitrc\fP that starts several applications and
+leaves the window manager running as the ''last'' application.  Assuming that
+the window manager has been configured properly, the user
+then chooses the ''Exit'' menu item to shut down X.
+.sp
+.in +4
+.nf
+xrdb \-load $HOME/.Xresources
+xsetroot \-solid gray &
+xbiff \-geometry \-430+5 &
+oclock \-geometry 75x75\-0\-0 &
+xload \-geometry \-80\-0 &
+xterm \-geometry +0+60 \-ls &
+xterm \-geometry +0\-100 &
+xconsole \-geometry \-0+0 \-fn 5x7 &
+exec twm
+.fi
+.in -4
+.SH "ENVIRONMENT VARIABLES"
+.TP 25
+DISPLAY
+This variable gets set to the name of the display to which clients should
+connect.  Note that this gets
+.IR set ,
+not read.
+.TP 25
+XAUTHORITY
+This variable, if not already defined, gets set to
+.IR $(HOME)/.Xauthority .
+This is to prevent the X server, if not given the
+.I \-auth
+argument, from automatically setting up insecure host-based authentication
+for the local host.  See the
+.BR Xserver (1)
+and
+.IR Xsecurity (7)
+manual pages for more information on X client/server authentication.
+.TP 25
+XINITRC
+This variable should contain the location of an xinitrc file. If unset,
+.I $(HOME)/.xinitrc
+or
+.I /etc/X11/xinit/xinitrc
+will be used.
+.TP 25
+XSERVERRC
+This variable should contain the location of an xserver file. If unset,
+.I $(HOME)/.xinitrc
+or
+.I /etc/X11/xinit/xserverrc
+will be used.
+.SH FILES
+.TP 25
+.I $(HOME)/.xinitrc
+Client to run.  Typically a shell script which runs many programs in
+the background.
+.TP 25
+.I $(HOME)/.xserverrc
+Server to run.  The default is
+.IR X .
+.TP 25
+.I /etc/X11/xinit/xinitrc
+Client to run if the user has no
+.I .xinitrc
+file.
+.TP 25
+.I /etc/X11/xinit/xserverrc
+Server to run if the user has no
+.I .xserverrc
+file.
+.SH "SEE ALSO"
+.BR xinit (1),
+.BR X (7),
+.BR Xserver (1),
+.BR Xorg (1),
+.BR xorg.conf (5)
diff --git a/upstream/mageia-cauldron/man1/stat.1 b/upstream/mageia-cauldron/man1/stat.1
new file mode 100644
index 00000000..d2c0f090
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/stat.1
@@ -0,0 +1,223 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH STAT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+stat \- display file or file system status
+.SH SYNOPSIS
+.B stat
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Display file or file system status.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+follow links
+.TP
+\fB\-f\fR, \fB\-\-file\-system\fR
+display file system status instead of file status
+.TP
+\fB\-\-cached\fR=\fI\,MODE\/\fR
+specify how to use cached attributes;
+useful on remote file systems. See MODE below
+.TP
+\fB\-c\fR  \fB\-\-format\fR=\fI\,FORMAT\/\fR
+use the specified FORMAT instead of the default;
+output a newline after each use of FORMAT
+.TP
+\fB\-\-printf\fR=\fI\,FORMAT\/\fR
+like \fB\-\-format\fR, but interpret backslash escapes,
+and do not output a mandatory trailing newline;
+if you want a newline, include \en in FORMAT
+.TP
+\fB\-t\fR, \fB\-\-terse\fR
+print the information in terse form
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The MODE argument of \fB\-\-cached\fR can be: always, never, or default.
+\&'always' will use cached attributes if available, while
+\&'never' will try to synchronize with the latest attributes, and
+\&'default' will leave it up to the underlying file system.
+.PP
+The valid format sequences for files (without \fB\-\-file\-system\fR):
+.TP
+%a
+permission bits in octal (note '#' and '0' printf flags)
+.TP
+%A
+permission bits and file type in human readable form
+.TP
+%b
+number of blocks allocated (see %B)
+.TP
+%B
+the size in bytes of each block reported by %b
+.TP
+%C
+SELinux security context string
+.TP
+%d
+device number in decimal (st_dev)
+.TP
+%D
+device number in hex (st_dev)
+.TP
+%Hd
+major device number in decimal
+.TP
+%Ld
+minor device number in decimal
+.TP
+%f
+raw mode in hex
+.TP
+%F
+file type
+.TP
+%g
+group ID of owner
+.TP
+%G
+group name of owner
+.TP
+%h
+number of hard links
+.TP
+%i
+inode number
+.TP
+%m
+mount point
+.TP
+%n
+file name
+.TP
+%N
+quoted file name with dereference if symbolic link
+.TP
+%o
+optimal I/O transfer size hint
+.TP
+%s
+total size, in bytes
+.TP
+%r
+device type in decimal (st_rdev)
+.TP
+%R
+device type in hex (st_rdev)
+.TP
+%Hr
+major device type in decimal, for character/block device special files
+.TP
+%Lr
+minor device type in decimal, for character/block device special files
+.TP
+%t
+major device type in hex, for character/block device special files
+.TP
+%T
+minor device type in hex, for character/block device special files
+.TP
+%u
+user ID of owner
+.TP
+%U
+user name of owner
+.TP
+%w
+time of file birth, human\-readable; \- if unknown
+.TP
+%W
+time of file birth, seconds since Epoch; 0 if unknown
+.TP
+%x
+time of last access, human\-readable
+.TP
+%X
+time of last access, seconds since Epoch
+.TP
+%y
+time of last data modification, human\-readable
+.TP
+%Y
+time of last data modification, seconds since Epoch
+.TP
+%z
+time of last status change, human\-readable
+.TP
+%Z
+time of last status change, seconds since Epoch
+.PP
+Valid format sequences for file systems:
+.TP
+%a
+free blocks available to non\-superuser
+.TP
+%b
+total data blocks in file system
+.TP
+%c
+total file nodes in file system
+.TP
+%d
+free file nodes in file system
+.TP
+%f
+free blocks in file system
+.TP
+%i
+file system ID in hex
+.TP
+%l
+maximum length of filenames
+.TP
+%n
+file name
+.TP
+%s
+block size (for faster transfers)
+.TP
+%S
+fundamental block size (for block counts)
+.TP
+%t
+file system type in hex
+.TP
+%T
+file system type in human readable form
+.SS "--terse is equivalent to the following FORMAT:"
+.IP
+%n %s %b %f %u %g %D %i %h %t %T %X %Y %Z %W %o
+.SS "--terse --file-system is equivalent to the following FORMAT:"
+.IP
+%n %i %l %t %s %S %b %f %a %c %d
+.PP
+NOTE: your shell may have its own version of stat, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Michael Meskes.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBstat\fP(2), \fBstatfs\fP(2), \fBstatx\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/stat>
+.br
+or available locally via: info \(aq(coreutils) stat invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/stdbuf.1 b/upstream/mageia-cauldron/man1/stdbuf.1
new file mode 100644
index 00000000..8f39212c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/stdbuf.1
@@ -0,0 +1,68 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH STDBUF "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+stdbuf \-
+Run COMMAND, with modified buffering operations for its standard streams.
+.SH SYNOPSIS
+.B stdbuf
+\fI\,OPTION\/\fR... \fI\,COMMAND\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Run COMMAND, with modified buffering operations for its standard streams.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-i\fR, \fB\-\-input\fR=\fI\,MODE\/\fR
+adjust standard input stream buffering
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,MODE\/\fR
+adjust standard output stream buffering
+.TP
+\fB\-e\fR, \fB\-\-error\fR=\fI\,MODE\/\fR
+adjust standard error stream buffering
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If MODE is 'L' the corresponding stream will be line buffered.
+This option is invalid with standard input.
+.PP
+If MODE is '0' the corresponding stream will be unbuffered.
+.PP
+Otherwise MODE is a number which may be followed by one of the following:
+KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+In this case the corresponding stream will be fully buffered with the buffer
+size set to MODE bytes.
+.PP
+NOTE: If COMMAND adjusts the buffering of its standard streams ('tee' does
+for example) then that will override corresponding changes by 'stdbuf'.
+Also some filters (like 'dd' and 'cat' etc.) don't use streams for I/O,
+and are thus unaffected by 'stdbuf' settings.
+.SH EXAMPLES
+.B tail -f access.log | stdbuf -oL cut -d \(aq \(aq -f1 | uniq
+.br
+This will immediately display unique entries from access.log
+.SH BUGS
+On GLIBC platforms, specifying a buffer size, i.e., using fully buffered mode
+will result in undefined operation.
+.SH AUTHOR
+Written by Padraig Brady.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/stdbuf>
+.br
+or available locally via: info \(aq(coreutils) stdbuf invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/streamzip.1 b/upstream/mageia-cauldron/man1/streamzip.1
new file mode 100644
index 00000000..fed69aa1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/streamzip.1
@@ -0,0 +1,199 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "STREAMZIP 1"
+.TH STREAMZIP 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+streamzip \- create a zip file from stdin
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    producer | streamzip [opts] | consumer
+\&    producer | streamzip [opts] \-zipfile=output.zip
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This program will read data from \f(CW\*(C`stdin\*(C'\fR, compress it into a zip container
+and, by default, write a \fIstreamed\fR zip file to \f(CW\*(C`stdout\*(C'\fR. No temporary
+files are created.
+.PP
+The zip container written to \f(CW\*(C`stdout\*(C'\fR is, by necessity, written in
+streaming format. Most programs that read Zip files can cope with a
+streamed zip file, but if interoperability is important, and your workflow
+allows you to write the zip file directly to disk you can create a
+non-streamed zip file using the \f(CW\*(C`zipfile\*(C'\fR option.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.IP \-zip64 5
+.IX Item "-zip64"
+Create a Zip64\-compliant zip container. Use this option if the input is
+greater than 4Gig.
+.Sp
+Default is disabled.
+.IP \-zipfile=F 5
+.IX Item "-zipfile=F"
+Write zip container to the filename \f(CW\*(C`F\*(C'\fR.
+.Sp
+Use the \f(CW\*(C`Stream\*(C'\fR option to force the creation of a streamed zip file.
+.IP \-member\-name=M 5
+.IX Item "-member-name=M"
+This option is used to name the "file" in the zip container.
+.Sp
+Default is '\-'.
+.IP \-stream 5
+.IX Item "-stream"
+Ignored when writing to \f(CW\*(C`stdout\*(C'\fR.
+.Sp
+If the \f(CW\*(C`zipfile\*(C'\fR option is specified, including this option will trigger
+the creation of a streamed zip file.
+.Sp
+Default: Always enabled when writing to \f(CW\*(C`stdout\*(C'\fR, otherwise disabled.
+.IP \-method=M 5
+.IX Item "-method=M"
+Compress using method \f(CW\*(C`M\*(C'\fR.
+.Sp
+Valid method names are
+.Sp
+.Vb 6
+\&    * store    Store without compression
+\&    * deflate  Use Deflate compression [Deflault]
+\&    * bzip2    Use Bzip2 compression
+\&    * lzma     Use LZMA compression
+\&    * xz       Use xz compression
+\&    * zstd     Use Zstandard compression
+.Ve
+.Sp
+Note that Lzma compress needs \f(CW\*(C`IO::Compress::Lzma\*(C'\fR to be installed.
+.Sp
+Note that Zstd compress needs \f(CW\*(C`IO::Compress::Zstd\*(C'\fR to be installed.
+.Sp
+Default is \f(CW\*(C`deflate\*(C'\fR.
+.IP "\-0, \-1, \-2, \-3, \-4, \-5, \-6, \-7, \-8, \-9" 5
+.IX Item "-0, -1, -2, -3, -4, -5, -6, -7, -8, -9"
+Sets the compression level for \f(CW\*(C`deflate\*(C'\fR. Ignored for all other compression methods.
+.Sp
+\&\f(CW\-0\fR means no compression and \f(CW\-9\fR for maximum compression.
+.Sp
+Default is 6
+.IP \-version 5
+.IX Item "-version"
+Display version number
+.IP \-help 5
+.IX Item "-help"
+Display help
+.SS Examples
+.IX Subsection "Examples"
+Create a zip file bt reading daa from stdin
+.PP
+.Vb 1
+\&    $ echo Lorem ipsum dolor sit | perl ./bin/streamzip >abcd.zip
+.Ve
+.PP
+Check the contents of \f(CW\*(C`abcd,zip\*(C'\fR with the standard \f(CW\*(C`unzip\*(C'\fR utility
+.PP
+.Vb 6
+\&    Archive:  abcd.zip
+\&      Length      Date    Time    Name
+\&    \-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-   \-\-\-\-
+\&           22  2021\-01\-08 19:45   \-
+\&    \-\-\-\-\-\-\-\-\-                     \-\-\-\-\-\-\-
+\&           22                     1 file
+.Ve
+.PP
+Notice how the \f(CW\*(C`Name\*(C'\fR is set to \f(CW\*(C`\-\*(C'\fR.
+That is the default for a few zip utilities whwre the member name is not given.
+.PP
+If you want to explicitly name the file, use the \f(CW\*(C`\-member\-name\*(C'\fR option as follows
+.PP
+.Vb 1
+\&    $ echo Lorem ipsum dolor sit | perl ./bin/streamzip \-member\-name latin >abcd.zip
+\&
+\&    $ unzip \-l abcd.zip
+\&    Archive:  abcd.zip
+\&      Length      Date    Time    Name
+\&    \-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-   \-\-\-\-
+\&           22  2021\-01\-08 19:47   latin
+\&    \-\-\-\-\-\-\-\-\-                     \-\-\-\-\-\-\-
+\&           22                     1 file
+.Ve
+.SS "When to write a Streamed Zip File"
+.IX Subsection "When to write a Streamed Zip File"
+A Streamed Zip File is useful in situations where you cannot seek
+backwards/forwards in the file.
+.PP
+A good examples is when you are serving dynamic content from a Web Server
+straight into a socket without needing to create a temporary zip file in
+the filesystsm.
+.PP
+Similarly if your workfow uses a Linux pipelined commands.
+.SH SUPPORT
+.IX Header "SUPPORT"
+General feedback/questions/bug reports should be sent to
+<https://github.com/pmqs/IO\-Compress/issues> (preferred) or
+<https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess \fIpmqs@cpan.org\fR.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2019\-2022 Paul Marquess. All rights reserved.
+.PP
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/strfile.1 b/upstream/mageia-cauldron/man1/strfile.1
new file mode 100644
index 00000000..fe3043e9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/strfile.1
@@ -0,0 +1,220 @@
+'\" t
+.\"     Title: STRFILE
+.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 12/29/2021
+.\"    Manual: 4th Berkeley Distribution
+.\"    Source: June 9, 1993 [Apr. 1997]
+.\"  Language: English
+.\"
+.TH "STRFILE" "1" "12/29/2021" "June 9, 1993 [Apr\&. 1997]" "4th Berkeley Distribution"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+
+.SH "NAME"
+strfile \- create a random access file for storing strings
+.br
+unstr \- dump strings in pointer order
+
+.SH "SYNOPSIS"
+.HP \w'\fBstrfile\fR\ 'u
+
+  \fBstrfile\fR     [\-iorsx]
+     [\-c\ \fIchar\fR]
+     \fIsourcefile\fR
+     [\fIoutputfile\fR]
+
+.HP \w'\fBunstr\fR\ 'u
+
+  \fBunstr\fR     [\-c\ \fIchar\fR]
+     \fIdatafile\&.[ext]\fR
+     [\fIoutputfile\fR]
+
+.SH "DESCRIPTION"
+.PP
+\fBstrfile\fR
+reads a file containing groups of lines separated by a line containing a single percent `%\*(Aq sign (or other specified delimiter character) and creates a data file which contains a header structure and a table of file offsets for each group of lines\&. This allows random access of the strings\&.
+
+.PP
+The output file, if not specified on the command line, is named
+\fIsourcefile\&.dat\fR\&.
+
+.PP
+The purpose of
+\fBunstr\fR
+is to undo the work of
+\fBstrfile\fR\&. It prints out the strings contained in the sourcefile, which is
+\fIdatafile\&.ext\fR
+without its extension, or
+\fIdatafile\fR
+if no extension is specified (in this case, the extension
+\fB\&.dat\fR
+is added to the name of the datafile) in the order that they are listed in the header file
+\fIdatafile\fR\&. If no
+\fIoutputfile\fR
+is specified, it prints to standard output; otherwise it prints to the file specified\&.
+\fBunstr\fR
+can also universally change the delimiter character in a strings file\&. It is possible to create sorted versions of input files by using
+\fBstrfile \-o\fR
+and then using
+\fBunstr\fR
+to dump them out in the table order\&.
+
+.SS "Options"
+.PP
+The options are as follows:
+
+.PP
+\fB\-c \fR\fIchar\fR
+.RS 4
+
+Change the delimiting character from the percent sign to
+\fIchar\fR\&. This option is available for both
+\fBstrfile\fR
+and
+\fBunstr\fR\&.
+
+.RE
+.PP
+\fB\-i\fR
+.RS 4
+
+Ignore case when ordering the strings\&.
+
+.RE
+.PP
+\fB\-o\fR
+.RS 4
+
+Order the strings in alphabetical order\&. The offset table will be sorted in the alphabetical order of the groups of lines referenced\&. Any initial non\-alphanumeric characters are ignored\&. This option causes the STR_ORDERED bit in the header
+\fIstr_flags\fR
+field to be set\&. (It also now really does sort! It didn\*(Aqt used to)\&.
+
+.RE
+.PP
+\fB\-r\fR
+.RS 4
+
+Randomize access to the strings\&. Entries in the offset table will be randomly ordered\&. This option causes the STR_RANDOM bit in the header
+\fIstr_flags\fR
+field to be set\&. (And really does randomize)
+
+.RE
+.PP
+\fB\-s\fR
+.RS 4
+
+Run silently; don\*(Aqt give a summary message when finished\&.
+
+.RE
+.PP
+\fB\-x\fR
+.RS 4
+
+Note that each alphabetic character in the groups of lines is rotated 13 positions in a simple caesar cypher\&. This option causes the STR_ROTATED bit in the header
+\fIstr_flags\fR
+field to be set\&. Note that it
+\fBdoes not\fR
+rotate the strings\-\-that operation must be performed separately\&.
+
+.RE
+
+.SS "Header"
+.PP
+The format of the header is:
+
+.PP
+#define VERSION 1
+unsigned long str_version; /* version number */
+unsigned long str_numstr; /* # of strings in the file */
+unsigned long str_longlen; /* length of longest string */
+unsigned long str_shortlen; /* shortest string length */
+#define STR_RANDOM 0x1 /* randomized pointers */
+#define STR_ORDERED 0x2 /* ordered pointers */
+#define STR_ROTATED 0x4 /* rot\-13\*(Aqd text */
+unsigned long str_flags; /* bit field for flags */
+char str_delim; /* delimiting character */
+
+.PP
+All fields are written in network byte order\&.
+
+.SH "BUGS"
+.PP
+Fewer now, one hopes\&. However, fortunes (text strings) beginning with a blank line appear to be sorted between random letters\&. This includes ASCII art that contains no letters, and first lines that are solely non\-alphanumeric, apparently\&. I\*(Aqve no idea why this should be\&.
+
+.SH "OTHER USES"
+.PP
+What can you do with this besides printing sarcastic and obscene messages to the screens of lusers at login or logout?
+
+.PP
+There
+\fBare\fR
+some other possibilities\&. Source code for a sample program,
+\fBrandstr\fR, is included with this distribution: randstr splits the difference between
+\fBunstr\fR
+and
+\fBfortune\fR\&. It reads a single, specified file, and randomly selects a single text string\&.
+
+.PP
+1
+.RS 4
+
+Include
+\fIstrfile\&.h\fR
+into a news reading/posting program, to generate random signatures\&.
+\fBTin\fR(1)
+does something similar, in a much more complex manner\&.
+
+.RE
+.PP
+2
+.RS 4
+
+Include it in a game\&. While strfile doesn\*(Aqt support \*(Aqfields\*(Aq or \*(Aqrecords\*(Aq, there\*(Aqs no reason that the text strings can\*(Aqt be consistent: first line, a die roll; second line, a score; third and subsequent lines, a text message\&.
+
+.RE
+.PP
+3
+.RS 4
+
+Use it to store your address book\&. Hell, some of the guys I know would be as well off using it to decide who to call on Friday nights (and for some, it wouldn\*(Aqt matter whether there were phone numbers in it or not)\&.
+
+.RE
+.PP
+4
+.RS 4
+
+Use it in \*(Aqlottery\*(Aq situations\&. If you\*(Aqre an ISP, write a script to store login names and GECOS from
+/etc/passwd
+in strfile format, write another to send \*(Aqcongratulations, you\*(Aqve won\*(Aq to the lucky login selected\&. The prize might be a month\*(Aqs free service, or if you\*(Aqre AOL, a month free on a real service provider\&.
+
+.RE
+
+.SH "SEE ALSO"
+.PP
+\fBbyteorder\fR(3),
+\fBfortune\fR(6)
+
+.SH "HISTORY"
+.PP
+The
+\fBstrfile\fR
+utility first appeared in 4\&.4BSD\&. This version was heavily modified, much of it in ways peculiar to Linux\&. Work has since been done to make the code more generic, and has so far been tested to work with SunOS 4\&.x\&. More platforms are expected to be supported as work continues\&.
+
diff --git a/upstream/mageia-cauldron/man1/strings.1 b/upstream/mageia-cauldron/man1/strings.1
new file mode 100644
index 00000000..44aadf6a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/strings.1
@@ -0,0 +1,346 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "STRINGS 1"
+.TH STRINGS 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+strings \- print the sequences of printable characters in files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+strings [\fB\-afovV\fR] [\fB\-\fR\fImin-len\fR]
+        [\fB\-n\fR \fImin-len\fR] [\fB\-\-bytes=\fR\fImin-len\fR]
+        [\fB\-t\fR \fIradix\fR] [\fB\-\-radix=\fR\fIradix\fR]
+        [\fB\-e\fR \fIencoding\fR] [\fB\-\-encoding=\fR\fIencoding\fR]
+        [\fB\-U\fR \fImethod\fR] [\fB\-\-unicode=\fR\fImethod\fR]
+        [\fB\-\fR] [\fB\-\-all\fR] [\fB\-\-print\-file\-name\fR]
+        [\fB\-T\fR \fIbfdname\fR] [\fB\-\-target=\fR\fIbfdname\fR]
+        [\fB\-w\fR] [\fB\-\-include\-all\-whitespace\fR]
+        [\fB\-s\fR] [\fB\-\-output\-separator\fR \fIsep_string\fR]
+        [\fB\-\-help\fR] [\fB\-\-version\fR] \fIfile\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+For each \fIfile\fR given, \s-1GNU\s0 \fBstrings\fR prints the
+printable character sequences that are at least 4 characters long (or
+the number given with the options below) and are followed by an
+unprintable character.
+.PP
+Depending upon how the strings program was configured it will default
+to either displaying all the printable sequences that it can find in
+each file, or only those sequences that are in loadable, initialized
+data sections.  If the file type is unrecognizable, or if strings is
+reading from stdin then it will always display all of the printable
+sequences that it can find.
+.PP
+For backwards compatibility any file that occurs after a command-line
+option of just \fB\-\fR will also be scanned in full, regardless of
+the presence of any \fB\-d\fR option.
+.PP
+\&\fBstrings\fR is mainly useful for determining the contents of
+non-text files.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+.IP "\fB\-\fR" 4
+.IX Item "-"
+.PD
+Scan the whole file, regardless of what sections it contains or
+whether those sections are loaded or initialized.  Normally this is
+the default behaviour, but strings can be configured so that the
+\&\fB\-d\fR is the default instead.
+.Sp
+The \fB\-\fR option is position dependent and forces strings to
+perform full scans of any file that is mentioned after the \fB\-\fR
+on the command line, even if the \fB\-d\fR option has been
+specified.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-\-data\fR" 4
+.IX Item "--data"
+.PD
+Only print strings from initialized, loaded data sections in the
+file.  This may reduce the amount of garbage in the output, but it
+also exposes the strings program to any security flaws that may be
+present in the \s-1BFD\s0 library used to scan and load sections.  Strings
+can be configured so that this option is the default behaviour.  In
+such cases the \fB\-a\fR option can be used to avoid using the \s-1BFD\s0
+library and instead just print all of the strings found in the file.
+.IP "\fB\-f\fR" 4
+.IX Item "-f"
+.PD 0
+.IP "\fB\-\-print\-file\-name\fR" 4
+.IX Item "--print-file-name"
+.PD
+Print the name of the file before each string.
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Print a summary of the program usage on the standard output and exit.
+.IP "\fB\-\fR\fImin-len\fR" 4
+.IX Item "-min-len"
+.PD 0
+.IP "\fB\-n\fR \fImin-len\fR" 4
+.IX Item "-n min-len"
+.IP "\fB\-\-bytes=\fR\fImin-len\fR" 4
+.IX Item "--bytes=min-len"
+.PD
+Print sequences of displayable characters that are at least
+\&\fImin-len\fR characters long.  If not specified a default minimum
+length of 4 is used.  The distinction between displayable and
+non-displayable characters depends upon the setting of the 
+\&\fB\-e\fR and \fB\-U\fR options.  Sequences are always terminated
+at control characters such as new-line and carriage-return, but not
+the tab character.
+.IP "\fB\-o\fR" 4
+.IX Item "-o"
+Like \fB\-t o\fR.  Some other versions of \fBstrings\fR have \fB\-o\fR
+act like \fB\-t d\fR instead.  Since we can not be compatible with both
+ways, we simply chose one.
+.IP "\fB\-t\fR \fIradix\fR" 4
+.IX Item "-t radix"
+.PD 0
+.IP "\fB\-\-radix=\fR\fIradix\fR" 4
+.IX Item "--radix=radix"
+.PD
+Print the offset within the file before each string.  The single
+character argument specifies the radix of the offset\-\-\-\fBo\fR for
+octal, \fBx\fR for hexadecimal, or \fBd\fR for decimal.
+.IP "\fB\-e\fR \fIencoding\fR" 4
+.IX Item "-e encoding"
+.PD 0
+.IP "\fB\-\-encoding=\fR\fIencoding\fR" 4
+.IX Item "--encoding=encoding"
+.PD
+Select the character encoding of the strings that are to be found.
+Possible values for \fIencoding\fR are: \fBs\fR = single\-7\-bit\-byte
+characters (default), \fBS\fR =
+single\-8\-bit\-byte characters, \fBb\fR = 16\-bit bigendian, \fBl\fR =
+16\-bit littleendian, \fBB\fR = 32\-bit bigendian, \fBL\fR = 32\-bit
+littleendian.  Useful for finding wide character strings. (\fBl\fR
+and \fBb\fR apply to, for example, Unicode \s-1UTF\-16/UCS\-2\s0 encodings).
+.IP "\fB\-U\fR \fI[d|i|l|e|x|h]\fR" 4
+.IX Item "-U [d|i|l|e|x|h]"
+.PD 0
+.IP "\fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR" 4
+.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
+.PD
+Controls the display of \s-1UTF\-8\s0 encoded multibyte characters in strings.
+The default (\fB\-\-unicode=default\fR) is to give them no special
+treatment, and instead rely upon the setting of the
+\&\fB\-\-encoding\fR option.  The other values for this option
+automatically enable \fB\-\-encoding=S\fR.
+.Sp
+The \fB\-\-unicode=invalid\fR option treats them as non-graphic
+characters and hence not part of a valid string.  All the remaining
+options treat them as valid string characters.
+.Sp
+The \fB\-\-unicode=locale\fR option displays them in the current
+locale, which may or may not support \s-1UTF\-8\s0 encoding.  The
+\&\fB\-\-unicode=hex\fR option displays them as hex byte sequences
+enclosed between \fI<>\fR characters.  The \fB\-\-unicode=escape\fR
+option displays them as escape sequences (\fI\euxxxx\fR) and the
+\&\fB\-\-unicode=highlight\fR option displays them as escape sequences
+highlighted in red (if supported by the output device).  The colouring
+is intended to draw attention to the presence of unicode sequences
+where they might not be expected.
+.IP "\fB\-T\fR \fIbfdname\fR" 4
+.IX Item "-T bfdname"
+.PD 0
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+.PD
+Specify an object code format other than your system's default format.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Print the program version number on the standard output and exit.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+.PD 0
+.IP "\fB\-\-include\-all\-whitespace\fR" 4
+.IX Item "--include-all-whitespace"
+.PD
+By default tab and space characters are included in the strings that
+are displayed, but other whitespace characters, such a newlines and
+carriage returns, are not.  The \fB\-w\fR option changes this so
+that all whitespace characters are considered to be part of a string.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-output\-separator\fR" 4
+.IX Item "--output-separator"
+.PD
+By default, output strings are delimited by a new-line. This option
+allows you to supply any string to be used as the output record
+separator.  Useful with \-\-include\-all\-whitespace where strings
+may contain new-lines internally.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBar\fR\|(1), \fBnm\fR\|(1), \fBobjdump\fR\|(1), \fBranlib\fR\|(1), \fBreadelf\fR\|(1)
+and the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/strip.1 b/upstream/mageia-cauldron/man1/strip.1
new file mode 100644
index 00000000..4f45c4fb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/strip.1
@@ -0,0 +1,510 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "STRIP 1"
+.TH STRIP 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+strip \- discard symbols and other data from object files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+strip [\fB\-F\fR \fIbfdname\fR |\fB\-\-target=\fR\fIbfdname\fR]
+      [\fB\-I\fR \fIbfdname\fR |\fB\-\-input\-target=\fR\fIbfdname\fR]
+      [\fB\-O\fR \fIbfdname\fR |\fB\-\-output\-target=\fR\fIbfdname\fR]
+      [\fB\-s\fR|\fB\-\-strip\-all\fR]
+      [\fB\-S\fR|\fB\-g\fR|\fB\-d\fR|\fB\-\-strip\-debug\fR]
+      [\fB\-\-strip\-dwo\fR]
+      [\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR]
+      [\fB\-M\fR|\fB\-\-merge\-notes\fR][\fB\-\-no\-merge\-notes\fR]
+      [\fB\-N\fR \fIsymbolname\fR |\fB\-\-strip\-symbol=\fR\fIsymbolname\fR]
+      [\fB\-w\fR|\fB\-\-wildcard\fR]
+      [\fB\-x\fR|\fB\-\-discard\-all\fR] [\fB\-X\fR |\fB\-\-discard\-locals\fR]
+      [\fB\-R\fR \fIsectionname\fR |\fB\-\-remove\-section=\fR\fIsectionname\fR]
+      [\fB\-\-keep\-section=\fR\fIsectionpattern\fR]
+      [\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR]
+      [\fB\-o\fR \fIfile\fR] [\fB\-p\fR|\fB\-\-preserve\-dates\fR]
+      [\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR]
+      [\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR]
+      [\fB\-\-keep\-section\-symbols\fR]
+      [\fB\-\-keep\-file\-symbols\fR]
+      [\fB\-\-only\-keep\-debug\fR]
+      [\fB\-v\fR |\fB\-\-verbose\fR] [\fB\-V\fR|\fB\-\-version\fR]
+      [\fB\-\-help\fR] [\fB\-\-info\fR]
+      \fIobjfile\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\s-1GNU\s0 \fBstrip\fR discards all symbols from object files
+\&\fIobjfile\fR.  The list of object files may include archives.
+At least one object file must be given.
+.PP
+\&\fBstrip\fR modifies the files named in its argument,
+rather than writing modified copies under different names.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-F\fR \fIbfdname\fR" 4
+.IX Item "-F bfdname"
+.PD 0
+.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
+.IX Item "--target=bfdname"
+.PD
+Treat the original \fIobjfile\fR as a file with the object
+code format \fIbfdname\fR, and rewrite it in the same format.
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+Show a summary of the options to \fBstrip\fR and exit.
+.IP "\fB\-\-info\fR" 4
+.IX Item "--info"
+Display a list showing all architectures and object formats available.
+.IP "\fB\-I\fR \fIbfdname\fR" 4
+.IX Item "-I bfdname"
+.PD 0
+.IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4
+.IX Item "--input-target=bfdname"
+.PD
+Treat the original \fIobjfile\fR as a file with the object
+code format \fIbfdname\fR.
+.IP "\fB\-O\fR \fIbfdname\fR" 4
+.IX Item "-O bfdname"
+.PD 0
+.IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4
+.IX Item "--output-target=bfdname"
+.PD
+Replace \fIobjfile\fR with a file in the output format \fIbfdname\fR.
+.IP "\fB\-R\fR \fIsectionname\fR" 4
+.IX Item "-R sectionname"
+.PD 0
+.IP "\fB\-\-remove\-section=\fR\fIsectionname\fR" 4
+.IX Item "--remove-section=sectionname"
+.PD
+Remove any section named \fIsectionname\fR from the output file, in
+addition to whatever sections would otherwise be removed.  This
+option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.  The wildcard
+character \fB*\fR may be given at the end of \fIsectionname\fR.  If
+so, then any section starting with \fIsectionname\fR will be removed.
+.Sp
+If the first character of \fIsectionpattern\fR is the exclamation
+point (!) then matching sections will not be removed even if an
+earlier use of \fB\-\-remove\-section\fR on the same command line
+would otherwise remove it.  For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-section=.text.* \-\-remove\-section=!.text.foo
+.Ve
+.Sp
+will remove all sections matching the pattern '.text.*', but will not
+remove the section '.text.foo'.
+.IP "\fB\-\-keep\-section=\fR\fIsectionpattern\fR" 4
+.IX Item "--keep-section=sectionpattern"
+When removing sections from the output file, keep sections that match
+\&\fIsectionpattern\fR.
+.IP "\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR" 4
+.IX Item "--remove-relocations=sectionpattern"
+Remove relocations from the output file for any section matching
+\&\fIsectionpattern\fR.  This option may be given more than once.  Note
+that using this option inappropriately may make the output file
+unusable.  Wildcard characters are accepted in \fIsectionpattern\fR.
+For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-relocations=.text.*
+.Ve
+.Sp
+will remove the relocations for all sections matching the patter
+\&'.text.*'.
+.Sp
+If the first character of \fIsectionpattern\fR is the exclamation
+point (!) then matching sections will not have their relocation
+removed even if an earlier use of \fB\-\-remove\-relocations\fR on the
+same command line would otherwise cause the relocations to be removed.
+For example:
+.Sp
+.Vb 1
+\&          \-\-remove\-relocations=.text.* \-\-remove\-relocations=!.text.foo
+.Ve
+.Sp
+will remove all relocations for sections matching the pattern
+\&'.text.*', but will not remove relocations for the section
+\&'.text.foo'.
+.IP "\fB\-s\fR" 4
+.IX Item "-s"
+.PD 0
+.IP "\fB\-\-strip\-all\fR" 4
+.IX Item "--strip-all"
+.PD
+Remove all symbols.
+.IP "\fB\-g\fR" 4
+.IX Item "-g"
+.PD 0
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.IP "\fB\-\-strip\-debug\fR" 4
+.IX Item "--strip-debug"
+.PD
+Remove debugging symbols only.
+.IP "\fB\-\-strip\-dwo\fR" 4
+.IX Item "--strip-dwo"
+Remove the contents of all \s-1DWARF\s0 .dwo sections, leaving the
+remaining debugging sections and all symbols intact.
+See the description of this option in the \fBobjcopy\fR section
+for more information.
+.IP "\fB\-\-strip\-unneeded\fR" 4
+.IX Item "--strip-unneeded"
+Remove all symbols that are not needed for relocation processing in
+addition to debugging symbols and sections stripped by
+\&\fB\-\-strip\-debug\fR.
+.IP "\fB\-K\fR \fIsymbolname\fR" 4
+.IX Item "-K symbolname"
+.PD 0
+.IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--keep-symbol=symbolname"
+.PD
+When stripping symbols, keep symbol \fIsymbolname\fR even if it would
+normally be stripped.  This option may be given more than once.
+.IP "\fB\-M\fR" 4
+.IX Item "-M"
+.PD 0
+.IP "\fB\-\-merge\-notes\fR" 4
+.IX Item "--merge-notes"
+.IP "\fB\-\-no\-merge\-notes\fR" 4
+.IX Item "--no-merge-notes"
+.PD
+For \s-1ELF\s0 files, attempt (or do not attempt) to reduce the size of any
+\&\s-1SHT_NOTE\s0 type sections by removing duplicate notes.  The default is to
+attempt this reduction unless stripping debug or \s-1DWO\s0 information.
+.IP "\fB\-N\fR \fIsymbolname\fR" 4
+.IX Item "-N symbolname"
+.PD 0
+.IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4
+.IX Item "--strip-symbol=symbolname"
+.PD
+Remove symbol \fIsymbolname\fR from the source file. This option may be
+given more than once, and may be combined with strip options other than
+\&\fB\-K\fR.
+.IP "\fB\-o\fR \fIfile\fR" 4
+.IX Item "-o file"
+Put the stripped output in \fIfile\fR, rather than replacing the
+existing file.  When this argument is used, only one \fIobjfile\fR
+argument may be specified.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-preserve\-dates\fR" 4
+.IX Item "--preserve-dates"
+.PD
+Preserve the access and modification dates of the file.
+.IP "\fB\-D\fR" 4
+.IX Item "-D"
+.PD 0
+.IP "\fB\-\-enable\-deterministic\-archives\fR" 4
+.IX Item "--enable-deterministic-archives"
+.PD
+Operate in \fIdeterministic\fR mode.  When copying archive members
+and writing the archive index, use zero for UIDs, GIDs, timestamps,
+and use consistent file modes for all files.
+.Sp
+If \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
+It can be disabled with the \fB\-U\fR option, below.
+.IP "\fB\-U\fR" 4
+.IX Item "-U"
+.PD 0
+.IP "\fB\-\-disable\-deterministic\-archives\fR" 4
+.IX Item "--disable-deterministic-archives"
+.PD
+Do \fInot\fR operate in \fIdeterministic\fR mode.  This is the
+inverse of the \fB\-D\fR option, above: when copying archive members
+and writing the archive index, use their actual \s-1UID, GID,\s0 timestamp,
+and file mode values.
+.Sp
+This is the default unless \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
+.PD 0
+.IP "\fB\-\-wildcard\fR" 4
+.IX Item "--wildcard"
+.PD
+Permit regular expressions in \fIsymbolname\fRs used in other command
+line options.  The question mark (?), asterisk (*), backslash (\e) and
+square brackets ([]) operators can be used anywhere in the symbol
+name.  If the first character of the symbol name is the exclamation
+point (!) then the sense of the switch is reversed for that symbol.
+For example:
+.Sp
+.Vb 1
+\&          \-w \-K !foo \-K fo*
+.Ve
+.Sp
+would cause strip to only keep symbols that start with the letters
+\&\*(L"fo\*(R", but to discard the symbol \*(L"foo\*(R".
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.IP "\fB\-\-discard\-all\fR" 4
+.IX Item "--discard-all"
+.PD
+Remove non-global symbols.
+.IP "\fB\-X\fR" 4
+.IX Item "-X"
+.PD 0
+.IP "\fB\-\-discard\-locals\fR" 4
+.IX Item "--discard-locals"
+.PD
+Remove compiler-generated local symbols.
+(These usually start with \fBL\fR or \fB.\fR.)
+.IP "\fB\-\-keep\-section\-symbols\fR" 4
+.IX Item "--keep-section-symbols"
+When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
+\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying section names,
+which would otherwise get stripped.
+.IP "\fB\-\-keep\-file\-symbols\fR" 4
+.IX Item "--keep-file-symbols"
+When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
+\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names,
+which would otherwise get stripped.
+.IP "\fB\-\-only\-keep\-debug\fR" 4
+.IX Item "--only-keep-debug"
+Strip a file, emptying the contents of any sections that would not be
+stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections
+intact.  In \s-1ELF\s0 files, this preserves all the note sections in the
+output as well.
+.Sp
+Note \- the section headers of the stripped sections are preserved,
+including their sizes, but the contents of the section are discarded.
+The section headers are preserved so that other tools can match up the
+debuginfo file with the real executable, even if that executable has
+been relocated to a different address space.
+.Sp
+The intention is that this option will be used in conjunction with
+\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable.  One a
+stripped binary which will occupy less space in \s-1RAM\s0 and in a
+distribution and the second a debugging information file which is only
+needed if debugging abilities are required.  The suggested procedure
+to create these files is as follows:
+.RS 4
+.IP "1.<Link the executable as normal.  Assuming that it is called>" 4
+.IX Item "1.<Link the executable as normal. Assuming that it is called>"
+\&\f(CW\*(C`foo\*(C'\fR then...
+.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4
+.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>"
+create a file containing the debugging info.
+.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4
+.IX Item "1.<Run objcopy --strip-debug foo to create a>"
+stripped executable.
+.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4
+.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>"
+to add a link to the debugging info into the stripped executable.
+.RE
+.RS 4
+.Sp
+Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info
+file is arbitrary.  Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is
+optional.  You could instead do this:
+.IP "1.<Link the executable as normal.>" 4
+.IX Item "1.<Link the executable as normal.>"
+.PD 0
+.ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4
+.el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4
+.IX Item "1.<Copy foo to foo.full>"
+.ie n .IP "1.<Run ""strip \-\-strip\-debug foo"">" 4
+.el .IP "1.<Run \f(CWstrip \-\-strip\-debug foo\fR>" 4
+.IX Item "1.<Run strip --strip-debug foo>"
+.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4
+.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4
+.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>"
+.RE
+.RS 4
+.PD
+.Sp
+i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the
+full executable.  It does not have to be a file created by the
+\&\fB\-\-only\-keep\-debug\fR switch.
+.Sp
+Note\-\-\-this switch is only intended for use on fully linked files.  It
+does not make sense to use it on object files where the debugging
+information may be incomplete.  Besides the gnu_debuglink feature
+currently only supports the presence of one filename containing
+debugging information, not multiple filenames on a one-per-object-file
+basis.
+.RE
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Show the version number for \fBstrip\fR.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-verbose\fR" 4
+.IX Item "--verbose"
+.PD
+Verbose output: list all object files modified.  In the case of
+archives, \fBstrip \-v\fR lists all members of the archive.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/stty.1 b/upstream/mageia-cauldron/man1/stty.1
new file mode 100644
index 00000000..5037e0d7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/stty.1
@@ -0,0 +1,413 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH STTY "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+stty \- change and print terminal line settings
+.SH SYNOPSIS
+.B stty
+[\fI\,-F DEVICE | --file=DEVICE\/\fR] [\fI\,SETTING\/\fR]...
+.br
+.B stty
+[\fI\,-F DEVICE | --file=DEVICE\/\fR] [\fI\,-a|--all\/\fR]
+.br
+.B stty
+[\fI\,-F DEVICE | --file=DEVICE\/\fR] [\fI\,-g|--save\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or change terminal characteristics.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+print all current settings in human\-readable form
+.TP
+\fB\-g\fR, \fB\-\-save\fR
+print all current settings in a stty\-readable form
+.TP
+\fB\-F\fR, \fB\-\-file\fR=\fI\,DEVICE\/\fR
+open and use the specified DEVICE instead of stdin
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Optional \- before SETTING indicates negation.  An * marks non\-POSIX
+settings.  The underlying system defines which settings are available.
+.SS "Special characters:"
+.TP
+* discard CHAR
+CHAR will toggle discarding of output
+.TP
+eof CHAR
+CHAR will send an end of file (terminate the input)
+.TP
+eol CHAR
+CHAR will end the line
+.TP
+* eol2 CHAR
+alternate CHAR for ending the line
+.TP
+erase CHAR
+CHAR will erase the last character typed
+.TP
+intr CHAR
+CHAR will send an interrupt signal
+.TP
+kill CHAR
+CHAR will erase the current line
+.TP
+* lnext CHAR
+CHAR will enter the next character quoted
+.TP
+quit CHAR
+CHAR will send a quit signal
+.TP
+* rprnt CHAR
+CHAR will redraw the current line
+.TP
+start CHAR
+CHAR will restart the output after stopping it
+.TP
+stop CHAR
+CHAR will stop the output
+.TP
+susp CHAR
+CHAR will send a terminal stop signal
+.TP
+* swtch CHAR
+CHAR will switch to a different shell layer
+.TP
+* werase CHAR
+CHAR will erase the last word typed
+.SS "Special settings:"
+.TP
+N
+set the input and output speeds to N bauds
+.TP
+* cols N
+tell the kernel that the terminal has N columns
+.TP
+* columns N
+same as cols N
+.TP
+* [\-]drain
+wait for transmission before applying settings (on by default)
+.TP
+ispeed N
+set the input speed to N
+.TP
+* line N
+use line discipline N
+.TP
+min N
+with \fB\-icanon\fR, set N characters minimum for a completed read
+.TP
+ospeed N
+set the output speed to N
+.TP
+* rows N
+tell the kernel that the terminal has N rows
+.TP
+* size
+print the number of rows and columns according to the kernel
+.TP
+speed
+print the terminal speed
+.TP
+time N
+with \fB\-icanon\fR, set read timeout of N tenths of a second
+.SS "Control settings:"
+.TP
+[\-]clocal
+disable modem control signals
+.TP
+[\-]cread
+allow input to be received
+.TP
+* [\-]crtscts
+enable RTS/CTS handshaking
+.TP
+csN
+set character size to N bits, N in [5..8]
+.TP
+[\-]cstopb
+use two stop bits per character (one with '\-')
+.TP
+[\-]hup
+send a hangup signal when the last process closes the tty
+.TP
+[\-]hupcl
+same as [\-]hup
+.TP
+[\-]parenb
+generate parity bit in output and expect parity bit in input
+.TP
+[\-]parodd
+set odd parity (or even parity with '\-')
+.TP
+* [\-]cmspar
+use "stick" (mark/space) parity
+.SS "Input settings:"
+.TP
+[\-]brkint
+breaks cause an interrupt signal
+.TP
+[\-]icrnl
+translate carriage return to newline
+.TP
+[\-]ignbrk
+ignore break characters
+.TP
+[\-]igncr
+ignore carriage return
+.TP
+[\-]ignpar
+ignore characters with parity errors
+.TP
+* [\-]imaxbel
+beep and do not flush a full input buffer on a character
+.TP
+[\-]inlcr
+translate newline to carriage return
+.TP
+[\-]inpck
+enable input parity checking
+.TP
+[\-]istrip
+clear high (8th) bit of input characters
+.TP
+* [\-]iutf8
+assume input characters are UTF\-8 encoded
+.TP
+* [\-]iuclc
+translate uppercase characters to lowercase
+.TP
+* [\-]ixany
+let any character restart output, not only start character
+.TP
+[\-]ixoff
+enable sending of start/stop characters
+.TP
+[\-]ixon
+enable XON/XOFF flow control
+.TP
+[\-]parmrk
+mark parity errors (with a 255\-0\-character sequence)
+.TP
+[\-]tandem
+same as [\-]ixoff
+.SS "Output settings:"
+.TP
+* bsN
+backspace delay style, N in [0..1]
+.TP
+* crN
+carriage return delay style, N in [0..3]
+.TP
+* ffN
+form feed delay style, N in [0..1]
+.TP
+* nlN
+newline delay style, N in [0..1]
+.TP
+* [\-]ocrnl
+translate carriage return to newline
+.TP
+* [\-]ofdel
+use delete characters for fill instead of NUL characters
+.TP
+* [\-]ofill
+use fill (padding) characters instead of timing for delays
+.TP
+* [\-]olcuc
+translate lowercase characters to uppercase
+.TP
+* [\-]onlcr
+translate newline to carriage return\-newline
+.TP
+* [\-]onlret
+newline performs a carriage return
+.TP
+* [\-]onocr
+do not print carriage returns in the first column
+.TP
+[\-]opost
+postprocess output
+.TP
+* tabN
+horizontal tab delay style, N in [0..3]
+.TP
+* tabs
+same as tab0
+.TP
+* \fB\-tabs\fR
+same as tab3
+.TP
+* vtN
+vertical tab delay style, N in [0..1]
+.SS "Local settings:"
+.TP
+[\-]crterase
+echo erase characters as backspace\-space\-backspace
+.TP
+* crtkill
+kill all line by obeying the echoprt and echoe settings
+.TP
+* \fB\-crtkill\fR
+kill all line by obeying the echoctl and echok settings
+.TP
+* [\-]ctlecho
+echo control characters in hat notation ('^c')
+.TP
+[\-]echo
+echo input characters
+.TP
+* [\-]echoctl
+same as [\-]ctlecho
+.TP
+[\-]echoe
+same as [\-]crterase
+.TP
+[\-]echok
+echo a newline after a kill character
+.TP
+* [\-]echoke
+same as [\-]crtkill
+.TP
+[\-]echonl
+echo newline even if not echoing other characters
+.TP
+* [\-]echoprt
+echo erased characters backward, between '\e' and '/'
+.TP
+* [\-]extproc
+enable "LINEMODE"; useful with high latency links
+.TP
+* [\-]flusho
+discard output
+.TP
+[\-]icanon
+enable special characters: erase, kill, werase, rprnt
+.TP
+[\-]iexten
+enable non\-POSIX special characters
+.TP
+[\-]isig
+enable interrupt, quit, and suspend special characters
+.TP
+[\-]noflsh
+disable flushing after interrupt and quit special characters
+.TP
+* [\-]prterase
+same as [\-]echoprt
+.TP
+* [\-]tostop
+stop background jobs that try to write to the terminal
+.TP
+* [\-]xcase
+with icanon, escape with '\e' for uppercase characters
+.SS "Combination settings:"
+.TP
+* [\-]LCASE
+same as [\-]lcase
+.TP
+cbreak
+same as \fB\-icanon\fR
+.TP
+\fB\-cbreak\fR
+same as icanon
+.TP
+cooked
+same as brkint ignpar istrip icrnl ixon opost isig
+icanon, eof and eol characters to their default values
+.TP
+\fB\-cooked\fR
+same as raw
+.TP
+crt
+same as echoe echoctl echoke
+.TP
+dec
+same as echoe echoctl echoke \fB\-ixany\fR intr ^c erase 0177
+kill ^u
+.TP
+* [\-]decctlq
+same as [\-]ixany
+.TP
+ek
+erase and kill characters to their default values
+.TP
+evenp
+same as parenb \fB\-parodd\fR cs7
+.TP
+\fB\-evenp\fR
+same as \fB\-parenb\fR cs8
+.TP
+* [\-]lcase
+same as xcase iuclc olcuc
+.TP
+litout
+same as \fB\-parenb\fR \fB\-istrip\fR \fB\-opost\fR cs8
+.TP
+\fB\-litout\fR
+same as parenb istrip opost cs7
+.TP
+nl
+same as \fB\-icrnl\fR \fB\-onlcr\fR
+.TP
+\fB\-nl\fR
+same as icrnl \fB\-inlcr\fR \fB\-igncr\fR onlcr \fB\-ocrnl\fR \fB\-onlret\fR
+.TP
+oddp
+same as parenb parodd cs7
+.TP
+\fB\-oddp\fR
+same as \fB\-parenb\fR cs8
+.TP
+[\-]parity
+same as [\-]evenp
+.TP
+pass8
+same as \fB\-parenb\fR \fB\-istrip\fR cs8
+.TP
+\fB\-pass8\fR
+same as parenb istrip cs7
+.TP
+raw
+same as \fB\-ignbrk\fR \fB\-brkint\fR \fB\-ignpar\fR \fB\-parmrk\fR \fB\-inpck\fR \fB\-istrip\fR
+\fB\-inlcr\fR \fB\-igncr\fR \fB\-icrnl\fR \fB\-ixon\fR \fB\-ixoff\fR \fB\-icanon\fR \fB\-opost\fR
+\fB\-isig\fR \fB\-iuclc\fR \fB\-ixany\fR \fB\-imaxbel\fR \fB\-xcase\fR min 1 time 0
+.TP
+\fB\-raw\fR
+same as cooked
+.TP
+sane
+same as cread \fB\-ignbrk\fR brkint \fB\-inlcr\fR \fB\-igncr\fR icrnl
+icanon iexten echo echoe echok \fB\-echonl\fR \fB\-noflsh\fR
+\fB\-ixoff\fR \fB\-iutf8\fR \fB\-iuclc\fR \fB\-ixany\fR imaxbel \fB\-xcase\fR \fB\-olcuc\fR \fB\-ocrnl\fR
+opost \fB\-ofill\fR onlcr \fB\-onocr\fR \fB\-onlret\fR nl0 cr0 tab0 bs0 vt0 ff0
+isig \fB\-tostop\fR \fB\-ofdel\fR \fB\-echoprt\fR echoctl echoke \fB\-extproc\fR \fB\-flusho\fR,
+all special characters to their default values
+.PP
+Handle the tty line connected to standard input.  Without arguments,
+prints baud rate, line discipline, and deviations from stty sane.  In
+settings, CHAR is taken literally, or coded as in ^c, 0x37, 0177 or
+127; special values ^\- or undef used to disable special characters.
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/stty>
+.br
+or available locally via: info \(aq(coreutils) stty invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sum.1 b/upstream/mageia-cauldron/man1/sum.1
new file mode 100644
index 00000000..a09bb1e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sum.1
@@ -0,0 +1,41 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SUM "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sum \- checksum and count the blocks in a file
+.SH SYNOPSIS
+.B sum
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print or check BSD (16\-bit) checksums.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-r\fR
+use BSD sum algorithm (the default), use 1K blocks
+.TP
+\fB\-s\fR, \fB\-\-sysv\fR
+use System V sum algorithm, use 512 bytes blocks
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Kayvan Aghaiepour and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/sum>
+.br
+or available locally via: info \(aq(coreutils) sum invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/sunicontopnm.1 b/upstream/mageia-cauldron/man1/sunicontopnm.1
new file mode 100644
index 00000000..a2f48981
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sunicontopnm.1
@@ -0,0 +1,103 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Sunicontopnm User Manual" 0 "23 October 2010" "netpbm documentation"
+
+.SH NAME
+sunicontopnm - convert a Sun icon into a Netpbm image
+
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsunicontopnm\fP
+[\fIiconfile\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsunicontopnm\fP reads a Sun icon as input and produces a PBM or PGM
+image as output.
+.PP
+If the input is of the Depth=8 variety, the output is PGM.  Otherwise,
+it is PBM.  Before Netpbm 10.53 (December 2010), the program would not work
+on a Depth=8 icon.
+.PP
+If the input is color, the output is still PGM (the program can't do
+any better because developers haven't figured out how).  If you know the
+palette used by the Sun icon image, you can use \fBpamlookup\fP to
+convert the PGM output to the proper color Netpbm image.
+
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBsunicontopnm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN sunicons
+.SH ABOUT SUN ICONS
+.PP
+It seems that this icon format was used in Sunview and was usable in its
+successor Openlook/Openwindows in Sun 4.1.1, which offered backward
+compatibility for Sunview, including the icons.  Sunview's desktop was
+monochrome.  OpenWindows had color icons.  Sun 4 came with OpenWindows.
+OpenWindows appears to have been an X-based gui so presumably the icons were
+mostly XPM files.
+.PP
+So in addition to \fBsunicontopnm\fP, you should try \fBxpmtoppm\fP and
+\fBxbmtopbm\fP on icons from a Sun Workstation.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtosunicon" (1)\c
+\&,
+.BR "winicontoppm" (1)\c
+\&,
+.BR "xpmtoppm" (1)\c
+\&,
+.BR "xbmtopbm" (1)\c
+\&,
+.BR "infotopam" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+.BR "pgm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+Jef Poskanzer wrote the program under the name \fBicontopbm\fP in 1988.
+.PP
+In October 2010, Prophet Of The Way (afu@wta.att.ne.jp) converted it to use
+the more recent "packed PBM" library functions, thus speeding it up
+.PP
+Netpbm 10.53 (December 2010) renamed the program to \fBsunicontopnm\fP.
+This name reflects the fact that there are lots of kinds of icons in the world
+besides the Sun variety, Windows ones being most popular.  It also takes
+into account the new Depth=8 capability (see below).
+.PP
+Netpbm 10.53 (December 2010) added the ability to work with Depth=8
+icon input and input with 32 bit "items."  Whereas the previous
+program always produced PBM output, the new program produced PGM in the
+Depth=8 case.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/sunicontopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/svgtopam.1 b/upstream/mageia-cauldron/man1/svgtopam.1
new file mode 100644
index 00000000..e97fae8b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/svgtopam.1
@@ -0,0 +1,98 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Svgtopam User Manual" 0 "28 June 2017" "netpbm documentation"
+
+.SH NAME
+svgtopam - convert an SVG (Scalable Vector Graphics) image to Netpbm format
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBsvgtopam\fP
+[\fB-trace\fP]
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBsvgtopam\fP reads an SVG (Scalable Vector Graphics) image as input and
+produces a PAM image as output.
+.PP
+\fBsvgtopam\fP is so weak that it is probably not useful in general for
+converting SVG images.  It understands only <path> SVG elements which
+use only the "M", "L", and "z" commands, and only those that use whole number
+arguments.  This is sufficient for converting most of what comes out of
+\fBpamtosvg\fP (not by coincidence - the program was developed for the
+specific task of testing \fBpamtosvg\fP), but the main reason it is part of
+Netpbm is to provide a base for someone to create a full SVG to Netpbm
+converter.
+.PP
+SVG is a vector image format, which means it describes curves that
+compose an image.  By contrast, PNM is a raster format, which means it
+describes dots that compose an image.  The main practical difference
+between the two types is that you can scale vector images better.  A
+vector image also takes a lot less data to describe an image if the
+image is composed of simple curves.
+.PP
+That means it is really an understatement to say that \fBsvgtopam\fP
+is an image format converter.  It's really an image drawer, not unlike
+\fBppmdraw\fP.
+.PP
+For more information on SVG, see 
+.UR http://www.w3.org/Graphics/SVG/
+the Worldwide Web Consortium's SVG web page
+.UE
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBsvgtopam\fP recognizes the following
+command line option:
+
+
+
+.TP
+\fB-trace\fP
+This option makes \fBsvgtopam\fP issue messages describing the drawing.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtosvg" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBsvgtopam\fP was added to Netpbm in Version 10.34 (May 2006).
+.PP
+Bryan Henderson created \fBsvgtopam\fP to test \fBpamtosvg\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/svgtopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/sync.1 b/upstream/mageia-cauldron/man1/sync.1
new file mode 100644
index 00000000..19d69a10
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/sync.1
@@ -0,0 +1,48 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH SYNC "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+sync \- Synchronize cached writes to persistent storage
+.SH SYNOPSIS
+.B sync
+[\fI\,OPTION\/\fR] [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Synchronize cached writes to persistent storage
+.PP
+If one or more files are specified, sync only them,
+or their containing file systems.
+.TP
+\fB\-d\fR, \fB\-\-data\fR
+sync only file data, no unneeded metadata
+.TP
+\fB\-f\fR, \fB\-\-file\-system\fR
+sync the file systems that contain the files
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH BUGS
+Persistence guarantees vary per system.
+See the system calls below for more details.
+.SH AUTHOR
+Written by Jim Meyering and Giuseppe Scrivano.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBfdatasync\fP(2), \fBfsync\fP(2), \fBsync\fP(2), \fBsyncfs\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/sync>
+.br
+or available locally via: info \(aq(coreutils) sync invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/systemctl.1 b/upstream/mageia-cauldron/man1/systemctl.1
new file mode 100644
index 00000000..e6609537
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemctl.1
@@ -0,0 +1,3040 @@
+'\" t
+.TH "SYSTEMCTL" "1" "" "systemd 255" "systemctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemctl \- Control the systemd system and service manager
+.SH "SYNOPSIS"
+.HP \w'\fBsystemctl\fR\ 'u
+\fBsystemctl\fR [OPTIONS...] COMMAND [UNIT...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemctl\fR
+may be used to introspect and control the state of the
+"systemd"
+system and service manager\&. Please refer to
+\fBsystemd\fR(1)
+for an introduction into the basic concepts and functionality this tool manages\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.SS "Unit Commands (Introspection and Modification)"
+.PP
+\fBlist\-units\fR [\fIPATTERN\fR\&...]
+.RS 4
+List units that
+\fBsystemd\fR
+currently has in memory\&. This includes units that are either referenced directly or through a dependency, units that are pinned by applications programmatically, or units that were active in the past and have failed\&. By default only units which are active, have pending jobs, or have failed are shown; this can be changed with option
+\fB\-\-all\fR\&. If one or more
+\fIPATTERN\fRs are specified, only units matching one of them are shown\&. The units that are shown are additionally filtered by
+\fB\-\-type=\fR
+and
+\fB\-\-state=\fR
+if those options are specified\&.
+.sp
+Note that this command does not show unit templates, but only instances of unit templates\&. Units templates that aren\*(Aqt instantiated are not runnable, and will thus never show up in the output of this command\&. Specifically this means that
+foo@\&.service
+will never be shown in this list \(em unless instantiated, e\&.g\&. as
+foo@bar\&.service\&. Use
+\fBlist\-unit\-files\fR
+(see below) for listing installed unit template files\&.
+.sp
+Produces output similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+  UNIT                         LOAD   ACTIVE SUB     DESCRIPTION
+  sys\-module\-fuse\&.device       loaded active plugged /sys/module/fuse
+  \-\&.mount                      loaded active mounted Root Mount
+  boot\-efi\&.mount               loaded active mounted /boot/efi
+  systemd\-journald\&.service     loaded active running Journal Service
+  systemd\-logind\&.service       loaded active running Login Service
+â—� user@1000\&.service            loaded failed failed  User Manager for UID 1000
+  \&...
+  systemd\-tmpfiles\-clean\&.timer loaded active waiting Daily Cleanup of Temporary Directories
+
+LOAD   = Reflects whether the unit definition was properly loaded\&.
+ACTIVE = The high\-level unit activation state, i\&.e\&. generalization of SUB\&.
+SUB    = The low\-level unit activation state, values depend on unit type\&.
+
+123 loaded units listed\&. Pass \-\-all to see loaded but inactive units, too\&.
+To show all installed unit files use \*(Aqsystemctl list\-unit\-files\*(Aq\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The header and the last unit of a given type are underlined if the terminal supports that\&. A colored dot is shown next to services which were masked, not found, or otherwise failed\&.
+.sp
+The LOAD column shows the load state, one of
+\fBloaded\fR,
+\fBnot\-found\fR,
+\fBbad\-setting\fR,
+\fBerror\fR,
+\fBmasked\fR\&. The ACTIVE columns shows the general unit state, one of
+\fBactive\fR,
+\fBreloading\fR,
+\fBinactive\fR,
+\fBfailed\fR,
+\fBactivating\fR,
+\fBdeactivating\fR\&. The SUB column shows the unit\-type\-specific detailed state of the unit, possible values vary by unit type\&. The list of possible LOAD, ACTIVE, and SUB states is not constant and new systemd releases may both add and remove values\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemctl \-\-state=help
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+command may be used to display the current set of possible values\&.
+.sp
+This is the default command\&.
+.RE
+.PP
+\fBlist\-automounts\fR [\fIPATTERN\fR\&...]
+.RS 4
+List automount units currently in memory, ordered by mount path\&. If one or more
+\fIPATTERN\fRs are specified, only automount units matching one of them are shown\&. Produces output similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+WHAT        WHERE                    MOUNTED IDLE TIMEOUT UNIT
+/dev/sdb1   /mnt/test                no      120s         mnt\-test\&.automount
+binfmt_misc /proc/sys/fs/binfmt_misc yes     0            proc\-sys\-fs\-binfmt_misc\&.automount
+
+2 automounts listed\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Also see
+\fB\-\-show\-types\fR,
+\fB\-\-all\fR, and
+\fB\-\-state=\fR\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fBlist\-paths\fR [\fIPATTERN\fR\&...]
+.RS 4
+List path units currently in memory, ordered by path\&. If one or more
+\fIPATTERN\fRs are specified, only path units matching one of them are shown\&. Produces output similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+PATH                           CONDITION         UNIT                               ACTIVATES
+/run/systemd/ask\-password      DirectoryNotEmpty systemd\-ask\-password\-plymouth\&.path systemd\-ask\-password\-plymouth\&.service
+/run/systemd/ask\-password      DirectoryNotEmpty systemd\-ask\-password\-wall\&.path     systemd\-ask\-password\-wall\&.service
+/var/cache/cups/org\&.cups\&.cupsd PathExists        cups\&.path                          cups\&.service
+
+3 paths listed\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Also see
+\fB\-\-show\-types\fR,
+\fB\-\-all\fR, and
+\fB\-\-state=\fR\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBlist\-sockets\fR [\fIPATTERN\fR\&...]
+.RS 4
+List socket units currently in memory, ordered by listening address\&. If one or more
+\fIPATTERN\fRs are specified, only socket units matching one of them are shown\&. Produces output similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+LISTEN           UNIT                        ACTIVATES
+/dev/initctl     systemd\-initctl\&.socket      systemd\-initctl\&.service
+\&...
+[::]:22          sshd\&.socket                 sshd\&.service
+kobject\-uevent 1 systemd\-udevd\-kernel\&.socket systemd\-udevd\&.service
+
+5 sockets listed\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Note: because the addresses might contains spaces, this output is not suitable for programmatic consumption\&.
+.sp
+Also see
+\fB\-\-show\-types\fR,
+\fB\-\-all\fR, and
+\fB\-\-state=\fR\&.
+.sp
+Added in version 202\&.
+.RE
+.PP
+\fBlist\-timers\fR [\fIPATTERN\fR\&...]
+.RS 4
+List timer units currently in memory, ordered by the time they elapse next\&. If one or more
+\fIPATTERN\fRs are specified, only units matching one of them are shown\&. Produces output similar to
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+NEXT                         LEFT          LAST                         PASSED     UNIT                         ACTIVATES
+\-                            \-             Thu 2017\-02\-23 13:40:29 EST  3 days ago ureadahead\-stop\&.timer        ureadahead\-stop\&.service
+Sun 2017\-02\-26 18:55:42 EST  1min 14s left Thu 2017\-02\-23 13:54:44 EST  3 days ago systemd\-tmpfiles\-clean\&.timer systemd\-tmpfiles\-clean\&.service
+Sun 2017\-02\-26 20:37:16 EST  1h 42min left Sun 2017\-02\-26 11:56:36 EST  6h ago     apt\-daily\&.timer              apt\-daily\&.service
+Sun 2017\-02\-26 20:57:49 EST  2h 3min left  Sun 2017\-02\-26 11:56:36 EST  6h ago     snapd\&.refresh\&.timer          snapd\&.refresh\&.service
+            
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+\fINEXT\fR
+shows the next time the timer will run\&.
+.sp
+\fILEFT\fR
+shows how long till the next time the timer runs\&.
+.sp
+\fILAST\fR
+shows the last time the timer ran\&.
+.sp
+\fIPASSED\fR
+shows how long has passed since the timer last ran\&.
+.sp
+\fIUNIT\fR
+shows the name of the timer
+.sp
+\fIACTIVATES\fR
+shows the name the service the timer activates when it runs\&.
+.sp
+Also see
+\fB\-\-all\fR
+and
+\fB\-\-state=\fR\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBis\-active \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Check whether any of the specified units are active (i\&.e\&. running)\&. Returns an exit code
+\fB0\fR
+if at least one is active, or non\-zero otherwise\&. Unless
+\fB\-\-quiet\fR
+is specified, this will also print the current unit state to standard output\&.
+.RE
+.PP
+\fBis\-failed \fR\fB[\fIPATTERN\fR\&...]\fR
+.RS 4
+Check whether any of the specified units is in the "failed" state\&. If no unit is specified, check whether there are any failed units, which corresponds to the
+"degraded"
+state returned by
+\fBis\-system\-running\fR\&. Returns an exit code
+\fB0\fR
+if at least one has failed, non\-zero otherwise\&. Unless
+\fB\-\-quiet\fR
+is specified, this will also print the current unit or system state to standard output\&.
+.sp
+Added in version 197\&.
+.RE
+.PP
+\fBstatus\fR [\fIPATTERN\fR\&...|\fIPID\fR\&...]]
+.RS 4
+Show runtime status information about the whole system or about one or more units followed by most recent log data from the journal\&. If no positional arguments are specified, and no unit filter is given with
+\fB\-\-type=\fR,
+\fB\-\-state=\fR, or
+\fB\-\-failed\fR, shows the status of the whole system\&. If combined with
+\fB\-\-all\fR, follows that with the status of all units\&. If positional arguments are specified, each positional argument is treated as either a unit name to show, or a glob pattern to show units whose names match that pattern, or a PID to show the unit containing that PID\&. When
+\fB\-\-type=\fR,
+\fB\-\-state=\fR, or
+\fB\-\-failed\fR
+are used, units are additionally filtered by the TYPE and ACTIVE state\&.
+.sp
+This function is intended to generate human\-readable output\&. If you are looking for computer\-parsable output, use
+\fBshow\fR
+instead\&. By default, this function only shows 10 lines of output and ellipsizes lines to fit in the terminal window\&. This can be changed with
+\fB\-\-lines\fR
+and
+\fB\-\-full\fR, see above\&. In addition,
+\fBjournalctl \-\-unit=\fR\fB\fINAME\fR\fR
+or
+\fBjournalctl \-\-user\-unit=\fR\fB\fINAME\fR\fR
+use a similar filter for messages and might be more convenient\&.
+.sp
+Note that this operation only displays
+\fIruntime\fR
+status, i\&.e\&. information about the current invocation of the unit (if it is running) or the most recent invocation (if it is not running anymore, and has not been released from memory)\&. Information about earlier invocations, invocations from previous system boots, or prior invocations that have already been released from memory may be retrieved via
+\fBjournalctl \-\-unit=\fR\&.
+.sp
+systemd implicitly loads units as necessary, so just running the
+\fBstatus\fR
+will attempt to load a file\&. The command is thus not useful for determining if something was already loaded or not\&. The units may possibly also be quickly unloaded after the operation is completed if there\*(Aqs no reason to keep it in memory thereafter\&.
+.PP
+\fBExample\ \&1.\ \&Example output from systemctl status\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemctl status bluetooth
+â—� bluetooth\&.service \- Bluetooth service
+   Loaded: loaded (/usr/lib/systemd/system/bluetooth\&.service; enabled; preset: enabled)
+   Active: active (running) since Wed 2017\-01\-04 13:54:04 EST; 1 weeks 0 days ago
+     Docs: man:bluetoothd(8)
+ Main PID: 930 (bluetoothd)
+   Status: "Running"
+    Tasks: 1
+   Memory: 648\&.0K
+      CPU: 435ms
+   CGroup: /system\&.slice/bluetooth\&.service
+           └─930 /usr/lib/bluetooth/bluetoothd
+
+Jan 12 10:46:45 example\&.com bluetoothd[8900]: Not enough free handles to register service
+Jan 12 10:46:45 example\&.com bluetoothd[8900]: Current Time Service could not be registered
+Jan 12 10:46:45 example\&.com bluetoothd[8900]: gatt\-time\-server: Input/output error (5)
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The dot ("â—�") uses color on supported terminals to summarize the unit state at a glance\&. Along with its color, its shape varies according to its state:
+"inactive"
+or
+"maintenance"
+is a white circle ("â—‹"),
+"active"
+is a green dot ("â—�"),
+"deactivating"
+is a white dot,
+"failed"
+or
+"error"
+is a red cross ("\(mu"), and
+"reloading"
+is a green clockwise circle arrow ("↻")\&.
+.sp
+The "Loaded:" line in the output will show
+"loaded"
+if the unit has been loaded into memory\&. Other possible values for "Loaded:" include:
+"error"
+if there was a problem loading it,
+"not\-found"
+if no unit file was found for this unit,
+"bad\-setting"
+if an essential unit file setting could not be parsed and
+"masked"
+if the unit file has been masked\&. Along with showing the path to the unit file, this line will also show the enablement state\&. Enabled units are included in the dependency network between units, and thus are started at boot or via some other form of activation\&. See the full table of possible enablement states \(em including the definition of
+"masked"
+\(em in the documentation for the
+\fBis\-enabled\fR
+command\&.
+.sp
+The "Active:" line shows active state\&. The value is usually
+"active"
+or
+"inactive"\&. Active could mean started, bound, plugged in, etc depending on the unit type\&. The unit could also be in process of changing states, reporting a state of
+"activating"
+or
+"deactivating"\&. A special
+"failed"
+state is entered when the service failed in some way, such as a crash, exiting with an error code or timing out\&. If the failed state is entered the cause will be logged for later reference\&.
+.RE
+.PP
+\fBshow\fR [\fIPATTERN\fR\&...|\fIJOB\fR\&...]
+.RS 4
+Show properties of one or more units, jobs, or the manager itself\&. If no argument is specified, properties of the manager will be shown\&. If a unit name is specified, properties of the unit are shown, and if a job ID is specified, properties of the job are shown\&. By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBstatus\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+Many properties shown by
+\fBsystemctl show\fR
+map directly to configuration settings of the system and service manager and its unit files\&. Note that the properties shown by the command are generally more low\-level, normalized versions of the original configuration settings and expose runtime state in addition to configuration\&. For example, properties shown for service units include the service\*(Aqs current main process identifier as
+"MainPID"
+(which is runtime state), and time settings are always exposed as properties ending in the
+"\&...USec"
+suffix even if a matching configuration options end in
+"\&...Sec", because microseconds is the normalized time unit used internally by the system and service manager\&.
+.sp
+For details about many of these properties, see the documentation of the D\-Bus interface backing these properties, see
+\fBorg.freedesktop.systemd1\fR(5)\&.
+.RE
+.PP
+\fBcat \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Show backing files of one or more units\&. Prints the "fragment" and "drop\-ins" (source files) of units\&. Each file is preceded by a comment which includes the file name\&. Note that this shows the contents of the backing files on disk, which may not match the system manager\*(Aqs understanding of these units if any unit files were updated on disk and the
+\fBdaemon\-reload\fR
+command wasn\*(Aqt issued since\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBhelp \fR\fB\fIPATTERN\fR\fR\fB\&...|\fR\fB\fIPID\fR\fR\fB\&...\fR
+.RS 4
+Show manual pages for one or more units, if available\&. If a PID is given, the manual pages for the unit the process belongs to are shown\&.
+.sp
+Added in version 185\&.
+.RE
+.PP
+\fBlist\-dependencies\fR [\fIUNIT\fR\&.\&.\&.]
+.RS 4
+Shows units required and wanted by the specified units\&. This recursively lists units following the
+\fIRequires=\fR,
+\fIRequisite=\fR,
+\fIWants=\fR,
+\fIConsistsOf=\fR,
+\fIBindsTo=\fR, and
+\fIUpholds=\fR
+dependencies\&. If no units are specified,
+default\&.target
+is implied\&.
+.sp
+The units that are shown are additionally filtered by
+\fB\-\-type=\fR
+and
+\fB\-\-state=\fR
+if those options are specified\&. Note that we won\*(Aqt be able to use a tree structure in this case, so
+\fB\-\-plain\fR
+is implied\&.
+.sp
+By default, only target units are recursively expanded\&. When
+\fB\-\-all\fR
+is passed, all other units are recursively expanded as well\&.
+.sp
+Options
+\fB\-\-reverse\fR,
+\fB\-\-after\fR,
+\fB\-\-before\fR
+may be used to change what types of dependencies are shown\&.
+.sp
+Note that this command only lists units currently loaded into memory by the service manager\&. In particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a specific unit, as it won\*(Aqt list the dependencies declared by units currently not loaded\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fBstart \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Start (activate) one or more units specified on the command line\&.
+.sp
+Note that unit glob patterns expand to names of units currently in memory\&. Units which are not active and are not in a failed state usually are not in memory, and will not be matched by any pattern\&. In addition, in case of instantiated units, systemd is often unaware of the instance name until the instance has been started\&. Therefore, using glob patterns with
+\fBstart\fR
+has limited usefulness\&. Also, secondary alias names of units are not considered\&.
+.sp
+Option
+\fB\-\-all\fR
+may be used to also operate on inactive units which are referenced by other loaded units\&. Note that this is not the same as operating on "all" possible units, because as the previous paragraph describes, such a list is ill\-defined\&. Nevertheless,
+\fBsystemctl start \-\-all \fR\fB\fIGLOB\fR\fR
+may be useful if all the units that should match the pattern are pulled in by some target which is known to be loaded\&.
+.RE
+.PP
+\fBstop \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Stop (deactivate) one or more units specified on the command line\&.
+.sp
+This command will fail if the unit does not exist or if stopping of the unit is prohibited (see
+\fIRefuseManualStop=\fR
+in
+\fBsystemd.unit\fR(5))\&. It will
+\fInot\fR
+fail if any of the commands configured to stop the unit (\fIExecStop=\fR, etc\&.) fail, because the manager will still forcibly terminate the unit\&.
+.sp
+If a unit that gets stopped can still be triggered by other units, a warning containing the names of the triggering units is shown\&.
+\fB\-\-no\-warn\fR
+can be used to suppress the warning\&.
+.RE
+.PP
+\fBreload \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Asks all units listed on the command line to reload their configuration\&. Note that this will reload the service\-specific configuration, not the unit configuration file of systemd\&. If you want systemd to reload the configuration file of a unit, use the
+\fBdaemon\-reload\fR
+command\&. In other words: for the example case of Apache, this will reload Apache\*(Aqs
+httpd\&.conf
+in the web server, not the
+apache\&.service
+systemd unit file\&.
+.sp
+This command should not be confused with the
+\fBdaemon\-reload\fR
+command\&.
+.RE
+.PP
+\fBrestart \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Stop and then start one or more units specified on the command line\&. If the units are not running yet, they will be started\&.
+.sp
+Note that restarting a unit with this command does not necessarily flush out all of the unit\*(Aqs resources before it is started again\&. For example, the per\-service file descriptor storage facility (see
+\fIFileDescriptorStoreMax=\fR
+in
+\fBsystemd.service\fR(5)) will remain intact as long as the unit has a job pending, and is only cleared when the unit is fully stopped and no jobs are pending anymore\&. If it is intended that the file descriptor store is flushed out, too, during a restart operation an explicit
+\fBsystemctl stop\fR
+command followed by
+\fBsystemctl start\fR
+should be issued\&.
+.RE
+.PP
+\fBtry\-restart \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Stop and then start one or more units specified on the command line if the units are running\&. This does nothing if units are not running\&.
+.RE
+.PP
+\fBreload\-or\-restart \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Reload one or more units if they support it\&. If not, stop and then start them instead\&. If the units are not running yet, they will be started\&.
+.RE
+.PP
+\fBtry\-reload\-or\-restart \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Reload one or more units if they support it\&. If not, stop and then start them instead\&. This does nothing if the units are not running\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fBisolate \fR\fB\fIUNIT\fR\fR
+.RS 4
+Start the unit specified on the command line and its dependencies and stop all others, unless they have
+\fBIgnoreOnIsolate=yes\fR
+(see
+\fBsystemd.unit\fR(5))\&. If a unit name with no extension is given, an extension of
+"\&.target"
+will be assumed\&.
+.sp
+This command is dangerous, since it will immediately stop processes that are not enabled in the new target, possibly including the graphical environment or terminal you are currently using\&.
+.sp
+Note that this operation is allowed only on units where
+\fBAllowIsolate=\fR
+is enabled\&. See
+\fBsystemd.unit\fR(5)
+for details\&.
+.RE
+.PP
+\fBkill \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Send a UNIX process signal to one or more processes of the unit\&. Use
+\fB\-\-kill\-whom=\fR
+to select which process to send the signal to\&. Use
+\fB\-\-signal=\fR
+to select the signal to send\&. Combine with
+\fB\-\-kill\-value=\fR
+to enqueue a POSIX Realtime Signal with an associated value\&.
+.RE
+.PP
+\fBclean \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Remove the configuration, state, cache, logs or runtime data of the specified units\&. Use
+\fB\-\-what=\fR
+to select which kind of resource to remove\&. For service units this may be used to remove the directories configured with
+\fIConfigurationDirectory=\fR,
+\fIStateDirectory=\fR,
+\fICacheDirectory=\fR,
+\fILogsDirectory=\fR
+and
+\fIRuntimeDirectory=\fR, see
+\fBsystemd.exec\fR(5)
+for details\&. It may also be used to clear the file descriptor store as enabled via
+\fIFileDescriptorStoreMax=\fR, see
+\fBsystemd.service\fR(5)
+for details\&. For timer units this may be used to clear out the persistent timestamp data if
+\fIPersistent=\fR
+is used and
+\fB\-\-what=state\fR
+is selected, see
+\fBsystemd.timer\fR(5)\&. This command only applies to units that use either of these settings\&. If
+\fB\-\-what=\fR
+is not specified, the cache and runtime data as well as the file descriptor store are removed (as these three types of resources are generally redundant and reproducible on the next invocation of the unit)\&. Note that the specified units must be stopped to invoke this operation\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fBfreeze \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Freeze one or more units specified on the command line using cgroup freezer
+.sp
+Freezing the unit will cause all processes contained within the cgroup corresponding to the unit to be suspended\&. Being suspended means that unit\*(Aqs processes won\*(Aqt be scheduled to run on CPU until thawed\&. Note that this command is supported only on systems that use unified cgroup hierarchy\&. Unit is automatically thawed just before we execute a job against the unit, e\&.g\&. before the unit is stopped\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBthaw \fR\fB\fIPATTERN\fR\fR\fB\&...\fR
+.RS 4
+Thaw (unfreeze) one or more units specified on the command line\&.
+.sp
+This is the inverse operation to the
+\fBfreeze\fR
+command and resumes the execution of processes in the unit\*(Aqs cgroup\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBset\-property \fR\fB\fIUNIT\fR\fR\fB \fR\fB\fIPROPERTY\fR\fR\fB=\fR\fB\fIVALUE\fR\fR\fB\&...\fR
+.RS 4
+Set the specified unit properties at runtime where this is supported\&. This allows changing configuration parameter properties such as resource control settings at runtime\&. Not all properties may be changed at runtime, but many resource control settings (primarily those in
+\fBsystemd.resource-control\fR(5)) may\&. The changes are applied immediately, and stored on disk for future boots, unless
+\fB\-\-runtime\fR
+is passed, in which case the settings only apply until the next reboot\&. The syntax of the property assignment follows closely the syntax of assignments in unit files\&.
+.sp
+Example:
+\fBsystemctl set\-property foobar\&.service CPUWeight=200\fR
+.sp
+If the specified unit appears to be inactive, the changes will be only stored on disk as described previously hence they will be effective when the unit will be started\&.
+.sp
+Note that this command allows changing multiple properties at the same time, which is preferable over setting them individually\&.
+.sp
+Example:
+\fBsystemctl set\-property foobar\&.service CPUWeight=200 MemoryMax=2G IPAccounting=yes\fR
+.sp
+Like with unit file configuration settings, assigning an empty setting usually resets a property to its defaults\&.
+.sp
+Example:
+\fBsystemctl set\-property avahi\-daemon\&.service IPAddressDeny=\fR
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fBbind\fR \fIUNIT\fR \fIPATH\fR [\fIPATH\fR]
+.RS 4
+Bind\-mounts a file or directory from the host into the specified unit\*(Aqs mount namespace\&. The first path argument is the source file or directory on the host, the second path argument is the destination file or directory in the unit\*(Aqs mount namespace\&. When the latter is omitted, the destination path in the unit\*(Aqs mount namespace is the same as the source path on the host\&. When combined with the
+\fB\-\-read\-only\fR
+switch, a ready\-only bind mount is created\&. When combined with the
+\fB\-\-mkdir\fR
+switch, the destination path is first created before the mount is applied\&.
+.sp
+Note that this option is currently only supported for units that run within a mount namespace (e\&.g\&.: with
+\fBRootImage=\fR,
+\fBPrivateMounts=\fR, etc\&.)\&. This command supports bind\-mounting directories, regular files, device nodes,
+\fBAF_UNIX\fR
+socket nodes, as well as FIFOs\&. The bind mount is ephemeral, and it is undone as soon as the current unit process exists\&. Note that the namespace mentioned here, where the bind mount will be added to, is the one where the main service process runs\&. Other processes (those exececuted by
+\fBExecReload=\fR,
+\fBExecStartPre=\fR, etc\&.) run in distinct namespaces\&.
+.sp
+If supported by the kernel, any prior mount on the selected target will be replaced by the new mount\&. If not supported, any prior mount will be over\-mounted, but remain pinned and inaccessible\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fBmount\-image\fR \fIUNIT\fR \fIIMAGE\fR [\fIPATH\fR [\fIPARTITION_NAME\fR:\fIMOUNT_OPTIONS\fR]]
+.RS 4
+Mounts an image from the host into the specified unit\*(Aqs mount namespace\&. The first path argument is the source image on the host, the second path argument is the destination directory in the unit\*(Aqs mount namespace (i\&.e\&. inside
+\fBRootImage=\fR/\fBRootDirectory=\fR)\&. The following argument, if any, is interpreted as a colon\-separated tuple of partition name and comma\-separated list of mount options for that partition\&. The format is the same as the service
+\fBMountImages=\fR
+setting\&. When combined with the
+\fB\-\-read\-only\fR
+switch, a ready\-only mount is created\&. When combined with the
+\fB\-\-mkdir\fR
+switch, the destination path is first created before the mount is applied\&.
+.sp
+Note that this option is currently only supported for units that run within a mount namespace (i\&.e\&. with
+\fBRootImage=\fR,
+\fBPrivateMounts=\fR, etc\&.)\&. Note that the namespace mentioned here where the image mount will be added to, is the one where the main service process runs\&. Note that the namespace mentioned here, where the bind mount will be added to, is the one where the main service process runs\&. Other processes (those exececuted by
+\fBExecReload=\fR,
+\fBExecStartPre=\fR, etc\&.) run in distinct namespaces\&.
+.sp
+If supported by the kernel, any prior mount on the selected target will be replaced by the new mount\&. If not supported, any prior mount will be over\-mounted, but remain pinned and inaccessible\&.
+.sp
+Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemctl mount\-image foo\&.service /tmp/img\&.raw /var/lib/image root:ro,nosuid
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemctl mount\-image \-\-mkdir bar\&.service /tmp/img\&.raw /var/lib/baz/img
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fBservice\-log\-level\fR \fISERVICE\fR [\fILEVEL\fR]
+.RS 4
+If the
+\fILEVEL\fR
+argument is not given, print the current log level as reported by service
+\fISERVICE\fR\&.
+.sp
+If the optional argument
+\fILEVEL\fR
+is provided, then change the current log level of the service to
+\fILEVEL\fR\&. The log level should be a typical syslog log level, i\&.e\&. a value in the range 0\&...7 or one of the strings
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR; see
+\fBsyslog\fR(3)
+for details\&.
+.sp
+The service must have the appropriate
+\fIBusName=\fR\fI\fIdestination\fR\fR
+property and also implement the generic
+\fBorg.freedesktop.LogControl1\fR(5)
+interface\&. (systemctl
+will use the generic D\-Bus protocol to access the
+org\&.freedesktop\&.LogControl1\&.LogLevel
+interface for the D\-Bus name
+\fIdestination\fR\&.)
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fBservice\-log\-target\fR \fISERVICE\fR [\fITARGET\fR]
+.RS 4
+If the
+\fITARGET\fR
+argument is not given, print the current log target as reported by service
+\fISERVICE\fR\&.
+.sp
+If the optional argument
+\fITARGET\fR
+is provided, then change the current log target of the service to
+\fITARGET\fR\&. The log target should be one of the strings
+\fBconsole\fR
+(for log output to the service\*(Aqs standard error stream),
+\fBkmsg\fR
+(for log output to the kernel log buffer),
+\fBjournal\fR
+(for log output to
+\fBsystemd-journald.service\fR(8)
+using the native journal protocol),
+\fBsyslog\fR
+(for log output to the classic syslog socket
+/dev/log),
+\fBnull\fR
+(for no log output whatsoever) or
+\fBauto\fR
+(for an automatically determined choice, typically equivalent to
+\fBconsole\fR
+if the service is invoked interactively, and
+\fBjournal\fR
+or
+\fBsyslog\fR
+otherwise)\&.
+.sp
+For most services, only a small subset of log targets make sense\&. In particular, most "normal" services should only implement
+\fBconsole\fR,
+\fBjournal\fR, and
+\fBnull\fR\&. Anything else is only appropriate for low\-level services that are active in very early boot before proper logging is established\&.
+.sp
+The service must have the appropriate
+\fIBusName=\fR\fI\fIdestination\fR\fR
+property and also implement the generic
+\fBorg.freedesktop.LogControl1\fR(5)
+interface\&. (systemctl
+will use the generic D\-Bus protocol to access the
+org\&.freedesktop\&.LogControl1\&.LogLevel
+interface for the D\-Bus name
+\fIdestination\fR\&.)
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fBreset\-failed [\fR\fB\fIPATTERN\fR\fR\fB\&...]\fR
+.RS 4
+Reset the
+"failed"
+state of the specified units, or if no unit name is passed, reset the state of all units\&. When a unit fails in some way (i\&.e\&. process exiting with non\-zero error code, terminating abnormally or timing out), it will automatically enter the
+"failed"
+state and its exit code and status is recorded for introspection by the administrator until the service is stopped/re\-started or reset with this command\&.
+.sp
+In addition to resetting the
+"failed"
+state of a unit it also resets various other per\-unit properties: the start rate limit counter of all unit types is reset to zero, as is the restart counter of service units\&. Thus, if a unit\*(Aqs start limit (as configured with
+\fIStartLimitIntervalSec=\fR/\fIStartLimitBurst=\fR) is hit and the unit refuses to be started again, use this command to make it startable again\&.
+.RE
+.PP
+\fBwhoami [\fR\fB\fIPID\fR\fR\fB\&...]\fR
+.RS 4
+Returns the units the processes referenced by the given PIDs belong to (one per line)\&. If no PID is specified returns the unit the
+\fBsystemctl\fR
+command is invoked in\&.
+.sp
+Added in version 254\&.
+.RE
+.SS "Unit File Commands"
+.PP
+\fBlist\-unit\-files\fR [\fIPATTERN\&...\fR]
+.RS 4
+List unit files installed on the system, in combination with their enablement state (as reported by
+\fBis\-enabled\fR)\&. If one or more
+\fIPATTERN\fRs are specified, only unit files whose name matches one of them are shown (patterns matching unit file system paths are not supported)\&.
+.sp
+Unlike
+\fBlist\-units\fR
+this command will list template units in addition to explicitly instantiated units\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBenable \fR\fB\fIUNIT\fR\fR\fB\&...\fR, \fBenable \fR\fB\fIPATH\fR\fR\fB\&...\fR
+.RS 4
+Enable one or more units or unit instances\&. This will create a set of symlinks, as encoded in the [Install] sections of the indicated unit files\&. After the symlinks have been created, the system manager configuration is reloaded (in a way equivalent to
+\fBdaemon\-reload\fR), in order to ensure the changes are taken into account immediately\&. Note that this does
+\fInot\fR
+have the effect of also starting any of the units being enabled\&. If this is desired, combine this command with the
+\fB\-\-now\fR
+switch, or invoke
+\fBstart\fR
+with appropriate arguments later\&. Note that in case of unit instance enablement (i\&.e\&. enablement of units of the form
+foo@bar\&.service), symlinks named the same as instances are created in the unit configuration directory, however they point to the single template unit file they are instantiated from\&.
+.sp
+This command expects either valid unit names (in which case various unit file directories are automatically searched for unit files with appropriate names), or absolute paths to unit files (in which case these files are read directly)\&. If a specified unit file is located outside of the usual unit file directories, an additional symlink is created, linking it into the unit configuration path, thus ensuring it is found when requested by commands such as
+\fBstart\fR\&. The file system where the linked unit files are located must be accessible when systemd is started (e\&.g\&. anything underneath
+/home/
+or
+/var/
+is not allowed, unless those directories are located on the root file system)\&.
+.sp
+This command will print the file system operations executed\&. This output may be suppressed by passing
+\fB\-\-quiet\fR\&.
+.sp
+Note that this operation creates only the symlinks suggested in the [Install] section of the unit files\&. While this command is the recommended way to manipulate the unit configuration directory, the administrator is free to make additional changes manually by placing or removing symlinks below this directory\&. This is particularly useful to create configurations that deviate from the suggested default installation\&. In this case, the administrator must make sure to invoke
+\fBdaemon\-reload\fR
+manually as necessary, in order to ensure the changes are taken into account\&.
+.sp
+When using this operation on units without install information, a warning about it is shown\&.
+\fB\-\-no\-warn\fR
+can be used to suppress the warning\&.
+.sp
+Enabling units should not be confused with starting (activating) units, as done by the
+\fBstart\fR
+command\&. Enabling and starting units is orthogonal: units may be enabled without being started and started without being enabled\&. Enabling simply hooks the unit into various suggested places (for example, so that the unit is automatically started on boot or when a particular kind of hardware is plugged in)\&. Starting actually spawns the daemon process (in case of service units), or binds the socket (in case of socket units), and so on\&.
+.sp
+Depending on whether
+\fB\-\-system\fR,
+\fB\-\-user\fR,
+\fB\-\-runtime\fR, or
+\fB\-\-global\fR
+is specified, this enables the unit for the system, for the calling user only, for only this boot of the system, or for all future logins of all users\&. Note that in the last case, no systemd daemon configuration is reloaded\&.
+.sp
+Using
+\fBenable\fR
+on masked units is not supported and results in an error\&.
+.RE
+.PP
+\fBdisable \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Disables one or more units\&. This removes all symlinks to the unit files backing the specified units from the unit configuration directory, and hence undoes any changes made by
+\fBenable\fR
+or
+\fBlink\fR\&. Note that this removes
+\fIall\fR
+symlinks to matching unit files, including manually created symlinks, and not just those actually created by
+\fBenable\fR
+or
+\fBlink\fR\&. Note that while
+\fBdisable\fR
+undoes the effect of
+\fBenable\fR, the two commands are otherwise not symmetric, as
+\fBdisable\fR
+may remove more symlinks than a prior
+\fBenable\fR
+invocation of the same unit created\&.
+.sp
+This command expects valid unit names only, it does not accept paths to unit files\&.
+.sp
+In addition to the units specified as arguments, all units are disabled that are listed in the
+\fIAlso=\fR
+setting contained in the [Install] section of any of the unit files being operated on\&.
+.sp
+This command implicitly reloads the system manager configuration after completing the operation\&. Note that this command does not implicitly stop the units that are being disabled\&. If this is desired, either combine this command with the
+\fB\-\-now\fR
+switch, or invoke the
+\fBstop\fR
+command with appropriate arguments later\&.
+.sp
+This command will print information about the file system operations (symlink removals) executed\&. This output may be suppressed by passing
+\fB\-\-quiet\fR\&.
+.sp
+If a unit gets disabled but its triggering units are still active, a warning containing the names of the triggering units is shown\&.
+\fB\-\-no\-warn\fR
+can be used to suppress the warning\&.
+.sp
+When this command is used with
+\fB\-\-user\fR, the units being operated on might still be enabled in global scope, and thus get started automatically even after a successful disablement in user scope\&. In this case, a warning about it is shown, which can be suppressed using
+\fB\-\-no\-warn\fR\&.
+.sp
+This command honors
+\fB\-\-system\fR,
+\fB\-\-user\fR,
+\fB\-\-runtime\fR,
+\fB\-\-global\fR
+and
+\fB\-\-no\-warn\fR
+in a similar way as
+\fBenable\fR\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fBreenable \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Reenable one or more units, as specified on the command line\&. This is a combination of
+\fBdisable\fR
+and
+\fBenable\fR
+and is useful to reset the symlinks a unit file is enabled with to the defaults configured in its [Install] section\&. This command expects a unit name only, it does not accept paths to unit files\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fBpreset \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Reset the enable/disable status one or more unit files, as specified on the command line, to the defaults configured in the preset policy files\&. This has the same effect as
+\fBdisable\fR
+or
+\fBenable\fR, depending how the unit is listed in the preset files\&.
+.sp
+Use
+\fB\-\-preset\-mode=\fR
+to control whether units shall be enabled and disabled, or only enabled, or only disabled\&.
+.sp
+If the unit carries no install information, it will be silently ignored by this command\&.
+\fIUNIT\fR
+must be the real unit name, any alias names are ignored silently\&.
+.sp
+For more information on the preset policy format, see
+\fBsystemd.preset\fR(5)\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fBpreset\-all\fR
+.RS 4
+Resets all installed unit files to the defaults configured in the preset policy file (see above)\&.
+.sp
+Use
+\fB\-\-preset\-mode=\fR
+to control whether units shall be enabled and disabled, or only enabled, or only disabled\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fBis\-enabled \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Checks whether any of the specified unit files are enabled (as with
+\fBenable\fR)\&. Returns an exit code of 0 if at least one is enabled, non\-zero otherwise\&. Prints the current enable status (see table)\&. To suppress this output, use
+\fB\-\-quiet\fR\&. To show installation targets, use
+\fB\-\-full\fR\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \& is\-enabled output
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+Name
+T}:T{
+Description
+T}:T{
+Exit Code
+T}
+.T&
+l l l
+l ^ ^
+l l l
+l ^ ^
+l l l
+l l l
+l ^ ^
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+"enabled"
+T}:T{
+Enabled via \&.wants/, \&.requires/ or \fIAlias=\fR symlinks (permanently in /etc/systemd/system/, or transiently in /run/systemd/system/)\&.
+T}:T{
+0
+T}
+T{
+"enabled\-runtime"
+T}::
+T{
+"linked"
+T}:T{
+Made available through one or more symlinks to the unit file (permanently in /etc/systemd/system/ or transiently in /run/systemd/system/), even though the unit file might reside outside of the unit file search path\&.
+T}:T{
+> 0
+T}
+T{
+"linked\-runtime"
+T}::
+T{
+"alias"
+T}:T{
+The name is an alias (symlink to another unit file)\&.
+T}:T{
+0
+T}
+T{
+"masked"
+T}:T{
+Completely disabled, so that any start operation on it fails (permanently in /etc/systemd/system/ or transiently in /run/systemd/systemd/)\&.
+T}:T{
+> 0
+T}
+T{
+"masked\-runtime"
+T}::
+T{
+"static"
+T}:T{
+The unit file is not enabled, and has no provisions for enabling in the [Install] unit file section\&.
+T}:T{
+0
+T}
+T{
+"indirect"
+T}:T{
+The unit file itself is not enabled, but it has a non\-empty \fIAlso=\fR setting in the [Install] unit file section, listing other unit files that might be enabled, or it has an alias under a different name through a symlink that is not specified in \fIAlso=\fR\&. For template unit files, an instance different than the one specified in \fIDefaultInstance=\fR is enabled\&.
+T}:T{
+0
+T}
+T{
+"disabled"
+T}:T{
+The unit file is not enabled, but contains an [Install] section with installation instructions\&.
+T}:T{
+> 0
+T}
+T{
+"generated"
+T}:T{
+The unit file was generated dynamically via a generator tool\&. See \fBsystemd.generator\fR(7)\&. Generated unit files may not be enabled, they are enabled implicitly by their generator\&.
+T}:T{
+0
+T}
+T{
+"transient"
+T}:T{
+The unit file has been created dynamically with the runtime API\&. Transient units may not be enabled\&.
+T}:T{
+0
+T}
+T{
+"bad"
+T}:T{
+The unit file is invalid or another error occurred\&. Note that \fBis\-enabled\fR will not actually return this state, but print an error message instead\&. However the unit file listing printed by \fBlist\-unit\-files\fR might show it\&.
+T}:T{
+> 0
+T}
+T{
+"not\-found"
+T}:T{
+The unit file doesn\*(Aqt exist\&.
+T}:T{
+4
+T}
+.TE
+.sp 1
+Added in version 238\&.
+.RE
+.PP
+\fBmask \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Mask one or more units, as specified on the command line\&. This will link these unit files to
+/dev/null, making it impossible to start them\&. This is a stronger version of
+\fBdisable\fR, since it prohibits all kinds of activation of the unit, including enablement and manual activation\&. Use this option with care\&. This honors the
+\fB\-\-runtime\fR
+option to only mask temporarily until the next reboot of the system\&. The
+\fB\-\-now\fR
+option may be used to ensure that the units are also stopped\&. This command expects valid unit names only, it does not accept unit file paths\&.
+.sp
+Note that this will create a symlink under the unit\*(Aqs name in
+/etc/systemd/system/
+(in case
+\fB\-\-runtime\fR
+is not specified) or
+/run/systemd/system/
+(in case
+\fB\-\-runtime\fR
+is specified)\&. If a matching unit file already exists under these directories this operation will hence fail\&. This means that the operation is primarily useful to mask units shipped by the vendor (as those are shipped in
+/usr/lib/systemd/system/
+and not the aforementioned two directories), but typically doesn\*(Aqt work for units created locally (as those are typically placed precisely in the two aforementioned directories)\&. Similar restrictions apply for
+\fB\-\-user\fR
+mode, in which case the directories are below the user\*(Aqs home directory however\&.
+.sp
+If a unit gets masked but its triggering units are still active, a warning containing the names of the triggering units is shown\&.
+\fB\-\-no\-warn\fR
+can be used to suppress the warning\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fBunmask \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Unmask one or more unit files, as specified on the command line\&. This will undo the effect of
+\fBmask\fR\&. This command expects valid unit names only, it does not accept unit file paths\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fBlink \fR\fB\fIPATH\fR\fR\fB\&...\fR
+.RS 4
+Link a unit file that is not in the unit file search path into the unit file search path\&. This command expects an absolute path to a unit file\&. The effect of this may be undone with
+\fBdisable\fR\&. The effect of this command is that a unit file is made available for commands such as
+\fBstart\fR, even though it is not installed directly in the unit search path\&. The file system where the linked unit files are located must be accessible when systemd is started (e\&.g\&. anything underneath
+/home/
+or
+/var/
+is not allowed, unless those directories are located on the root file system)\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBrevert \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Revert one or more unit files to their vendor versions\&. This command removes drop\-in configuration files that modify the specified units, as well as any user\-configured unit file that overrides a matching vendor supplied unit file\&. Specifically, for a unit
+"foo\&.service"
+the matching directories
+"foo\&.service\&.d/"
+with all their contained files are removed, both below the persistent and runtime configuration directories (i\&.e\&. below
+/etc/systemd/system
+and
+/run/systemd/system); if the unit file has a vendor\-supplied version (i\&.e\&. a unit file located below
+/usr/) any matching persistent or runtime unit file that overrides it is removed, too\&. Note that if a unit file has no vendor\-supplied version (i\&.e\&. is only defined below
+/etc/systemd/system
+or
+/run/systemd/system, but not in a unit file stored below
+/usr/), then it is not removed\&. Also, if a unit is masked, it is unmasked\&.
+.sp
+Effectively, this command may be used to undo all changes made with
+\fBsystemctl edit\fR,
+\fBsystemctl set\-property\fR
+and
+\fBsystemctl mask\fR
+and puts the original unit file with its settings back in effect\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fBadd\-wants \fR\fB\fITARGET\fR\fR\fB \fR\fB\fIUNIT\fR\fR\fB\&...\fR, \fBadd\-requires \fR\fB\fITARGET\fR\fR\fB \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Adds
+"Wants="
+or
+"Requires="
+dependencies, respectively, to the specified
+\fITARGET\fR
+for one or more units\&.
+.sp
+This command honors
+\fB\-\-system\fR,
+\fB\-\-user\fR,
+\fB\-\-runtime\fR
+and
+\fB\-\-global\fR
+in a way similar to
+\fBenable\fR\&.
+.sp
+Added in version 217\&.
+.RE
+.PP
+\fBedit \fR\fB\fIUNIT\fR\fR\fB\&...\fR
+.RS 4
+Edit a drop\-in snippet or a whole replacement file if
+\fB\-\-full\fR
+is specified, to extend or override the specified unit\&.
+.sp
+Depending on whether
+\fB\-\-system\fR
+(the default),
+\fB\-\-user\fR, or
+\fB\-\-global\fR
+is specified, this command creates a drop\-in file for each unit either for the system, for the calling user, or for all futures logins of all users\&. Then, the editor (see the "Environment" section below) is invoked on temporary files which will be written to the real location if the editor exits successfully\&.
+.sp
+If
+\fB\-\-drop\-in=\fR
+is specified, the given drop\-in file name will be used instead of the default
+override\&.conf\&.
+.sp
+If
+\fB\-\-full\fR
+is specified, this will copy the original units instead of creating drop\-in files\&.
+.sp
+If
+\fB\-\-force\fR
+is specified and any units do not already exist, new unit files will be opened for editing\&.
+.sp
+If
+\fB\-\-runtime\fR
+is specified, the changes will be made temporarily in
+/run/
+and they will be lost on the next reboot\&.
+.sp
+If the temporary file is empty upon exit, the modification of the related unit is canceled\&.
+.sp
+After the units have been edited, systemd configuration is reloaded (in a way that is equivalent to
+\fBdaemon\-reload\fR)\&.
+.sp
+Note that this command cannot be used to remotely edit units and that you cannot temporarily edit units which are in
+/etc/, since they take precedence over
+/run/\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fBget\-default\fR
+.RS 4
+Return the default target to boot into\&. This returns the target unit name
+default\&.target
+is aliased (symlinked) to\&.
+.sp
+Added in version 205\&.
+.RE
+.PP
+\fBset\-default \fR\fB\fITARGET\fR\fR
+.RS 4
+Set the default target to boot into\&. This sets (symlinks) the
+default\&.target
+alias to the given target unit\&.
+.sp
+Added in version 205\&.
+.RE
+.SS "Machine Commands"
+.PP
+\fBlist\-machines\fR [\fIPATTERN\fR\&...]
+.RS 4
+List the host and all running local containers with their state\&. If one or more
+\fIPATTERN\fRs are specified, only containers matching one of them are shown\&.
+.sp
+Added in version 212\&.
+.RE
+.SS "Job Commands"
+.PP
+\fBlist\-jobs \fR\fB[\fIPATTERN\&...\fR]\fR
+.RS 4
+List jobs that are in progress\&. If one or more
+\fIPATTERN\fRs are specified, only jobs for units matching one of them are shown\&.
+.sp
+When combined with
+\fB\-\-after\fR
+or
+\fB\-\-before\fR
+the list is augmented with information on which other job each job is waiting for, and which other jobs are waiting for it, see above\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBcancel \fR\fB[\fIJOB\fR\&...]\fR
+.RS 4
+Cancel one or more jobs specified on the command line by their numeric job IDs\&. If no job ID is specified, cancel all pending jobs\&.
+.sp
+Added in version 233\&.
+.RE
+.SS "Environment Commands"
+.PP
+\fBsystemd\fR
+supports an environment block that is passed to processes the manager spawns\&. The names of the variables can contain ASCII letters, digits, and the underscore character\&. Variable names cannot be empty or start with a digit\&. In variable values, most characters are allowed, but the whole sequence must be valid UTF\-8\&. (Note that control characters like newline (\fBNL\fR), tab (\fBTAB\fR), or the escape character (\fBESC\fR),
+\fIare\fR
+valid ASCII and thus valid UTF\-8)\&. The total length of the environment block is limited to
+\fB_SC_ARG_MAX\fR
+value defined by
+\fBsysconf\fR(3)\&.
+.PP
+\fBshow\-environment\fR
+.RS 4
+Dump the systemd manager environment block\&. This is the environment block that is passed to all processes the manager spawns\&. The environment block will be dumped in straightforward form suitable for sourcing into most shells\&. If no special characters or whitespace is present in the variable values, no escaping is performed, and the assignments have the form
+"VARIABLE=value"\&. If whitespace or characters which have special meaning to the shell are present, dollar\-single\-quote escaping is used, and assignments have the form
+"VARIABLE=$\*(Aqvalue\*(Aq"\&. This syntax is known to be supported by
+\fBbash\fR(1),
+\fBzsh\fR(1),
+\fBksh\fR(1), and
+\fBbusybox\fR(1)\*(Aqs
+\fBash\fR(1), but not
+\fBdash\fR(1)
+or
+\fBfish\fR(1)\&.
+.RE
+.PP
+\fBset\-environment \fR\fB\fIVARIABLE=VALUE\fR\fR\fB\&...\fR
+.RS 4
+Set one or more systemd manager environment variables, as specified on the command line\&. This command will fail if variable names and values do not conform to the rules listed above\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBunset\-environment \fR\fB\fIVARIABLE\fR\fR\fB\&...\fR
+.RS 4
+Unset one or more systemd manager environment variables\&. If only a variable name is specified, it will be removed regardless of its value\&. If a variable and a value are specified, the variable is only removed if it has the specified value\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fBimport\-environment\fR \fIVARIABLE\&...\fR
+.RS 4
+Import all, one or more environment variables set on the client into the systemd manager environment block\&. If a list of environment variable names is passed, client\-side values are then imported into the manager\*(Aqs environment block\&. If any names are not valid environment variable names or have invalid values according to the rules described above, an error is raised\&. If no arguments are passed, the entire environment block inherited by the
+\fBsystemctl\fR
+process is imported\&. In this mode, any inherited invalid environment variables are quietly ignored\&.
+.sp
+Importing of the full inherited environment block (calling this command without any arguments) is deprecated\&. A shell will set dozens of variables which only make sense locally and are only meant for processes which are descendants of the shell\&. Such variables in the global environment block are confusing to other processes\&.
+.sp
+Added in version 209\&.
+.RE
+.SS "Manager State Commands"
+.PP
+\fBdaemon\-reload\fR
+.RS 4
+Reload the systemd manager configuration\&. This will rerun all generators (see
+\fBsystemd.generator\fR(7)), reload all unit files, and recreate the entire dependency tree\&. While the daemon is being reloaded, all sockets systemd listens on behalf of user configuration will stay accessible\&.
+.sp
+This command should not be confused with the
+\fBreload\fR
+command\&.
+.RE
+.PP
+\fBdaemon\-reexec\fR
+.RS 4
+Reexecute the systemd manager\&. This will serialize the manager state, reexecute the process and deserialize the state again\&. This command is of little use except for debugging and package upgrades\&. Sometimes, it might be helpful as a heavy\-weight
+\fBdaemon\-reload\fR\&. While the daemon is being reexecuted, all sockets systemd listening on behalf of user configuration will stay accessible\&.
+.RE
+.PP
+\fBlog\-level\fR [\fILEVEL\fR]
+.RS 4
+If no argument is given, print the current log level of the manager\&. If an optional argument
+\fILEVEL\fR
+is provided, then the command changes the current log level of the manager to
+\fILEVEL\fR
+(accepts the same values as
+\fB\-\-log\-level=\fR
+described in
+\fBsystemd\fR(1))\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fBlog\-target\fR [\fITARGET\fR]
+.RS 4
+If no argument is given, print the current log target of the manager\&. If an optional argument
+\fITARGET\fR
+is provided, then the command changes the current log target of the manager to
+\fITARGET\fR
+(accepts the same values as
+\fB\-\-log\-target=\fR, described in
+\fBsystemd\fR(1))\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fBservice\-watchdogs\fR [yes|no]
+.RS 4
+If no argument is given, print the current state of service runtime watchdogs of the manager\&. If an optional boolean argument is provided, then globally enables or disables the service runtime watchdogs (\fBWatchdogSec=\fR) and emergency actions (e\&.g\&.
+\fBOnFailure=\fR
+or
+\fBStartLimitAction=\fR); see
+\fBsystemd.service\fR(5)\&. The hardware watchdog is not affected by this setting\&.
+.sp
+Added in version 244\&.
+.RE
+.SS "System Commands"
+.PP
+\fBis\-system\-running\fR
+.RS 4
+Checks whether the system is operational\&. This returns success (exit code 0) when the system is fully up and running, specifically not in startup, shutdown or maintenance mode, and with no failed services\&. Failure is returned otherwise (exit code non\-zero)\&. In addition, the current state is printed in a short string to standard output, see the table below\&. Use
+\fB\-\-quiet\fR
+to suppress this output\&.
+.sp
+Use
+\fB\-\-wait\fR
+to wait until the boot process is completed before printing the current state and returning the appropriate error status\&. If
+\fB\-\-wait\fR
+is in use, states
+\fIinitializing\fR
+or
+\fIstarting\fR
+will not be reported, instead the command will block until a later state (such as
+\fIrunning\fR
+or
+\fIdegraded\fR) is reached\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&2.\ \&is\-system\-running output
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+Name
+T}:T{
+Description
+T}:T{
+Exit Code
+T}
+.T&
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+\fIinitializing\fR
+T}:T{
+Early bootup, before
+basic\&.target
+is reached or the
+\fImaintenance\fR
+state entered\&.
+T}:T{
+> 0
+T}
+T{
+\fIstarting\fR
+T}:T{
+Late bootup, before the job queue becomes idle for the first time, or one of the rescue targets are reached\&.
+T}:T{
+> 0
+T}
+T{
+\fIrunning\fR
+T}:T{
+The system is fully operational\&.
+T}:T{
+0
+T}
+T{
+\fIdegraded\fR
+T}:T{
+The system is operational but one or more units failed\&.
+T}:T{
+> 0
+T}
+T{
+\fImaintenance\fR
+T}:T{
+The rescue or emergency target is active\&.
+T}:T{
+> 0
+T}
+T{
+\fIstopping\fR
+T}:T{
+The manager is shutting down\&.
+T}:T{
+> 0
+T}
+T{
+\fIoffline\fR
+T}:T{
+The manager is not running\&. Specifically, this is the operational state if an incompatible program is running as system manager (PID 1)\&.
+T}:T{
+> 0
+T}
+T{
+\fIunknown\fR
+T}:T{
+The operational state could not be determined, due to lack of resources or another error cause\&.
+T}:T{
+> 0
+T}
+.TE
+.sp 1
+Added in version 215\&.
+.RE
+.PP
+\fBdefault\fR
+.RS 4
+Enter default mode\&. This is equivalent to
+\fBsystemctl isolate default\&.target\fR\&. This operation is blocking by default, use
+\fB\-\-no\-block\fR
+to request asynchronous behavior\&.
+.RE
+.PP
+\fBrescue\fR
+.RS 4
+Enter rescue mode\&. This is equivalent to
+\fBsystemctl isolate rescue\&.target\fR\&. This operation is blocking by default, use
+\fB\-\-no\-block\fR
+to request asynchronous behavior\&.
+.RE
+.PP
+\fBemergency\fR
+.RS 4
+Enter emergency mode\&. This is equivalent to
+\fBsystemctl isolate emergency\&.target\fR\&. This operation is blocking by default, use
+\fB\-\-no\-block\fR
+to request asynchronous behavior\&.
+.RE
+.PP
+\fBhalt\fR
+.RS 4
+Shut down and halt the system\&. This is mostly equivalent to
+\fBsystemctl start halt\&.target \-\-job\-mode=replace\-irreversibly \-\-no\-block\fR, but also prints a wall message to all users\&. This command is asynchronous; it will return after the halt operation is enqueued, without waiting for it to complete\&. Note that this operation will simply halt the OS kernel after shutting down, leaving the hardware powered on\&. Use
+\fBsystemctl poweroff\fR
+for powering off the system (see below)\&.
+.sp
+If combined with
+\fB\-\-force\fR, shutdown of all running services is skipped, however all processes are killed and all file systems are unmounted or mounted read\-only, immediately followed by the system halt\&. If
+\fB\-\-force\fR
+is specified twice, the operation is immediately executed without terminating any processes or unmounting any file systems\&. This may result in data loss\&. Note that when
+\fB\-\-force\fR
+is specified twice the halt operation is executed by
+\fBsystemctl\fR
+itself, and the system manager is not contacted\&. This means the command should succeed even when the system manager has crashed\&.
+.sp
+If combined with
+\fB\-\-when=\fR, shutdown will be scheduled after the given timestamp\&. And
+\fB\-\-when=cancel\fR
+will cancel the shutdown\&.
+.RE
+.PP
+\fBpoweroff\fR
+.RS 4
+Shut down and power\-off the system\&. This is mostly equivalent to
+\fBsystemctl start poweroff\&.target \-\-job\-mode=replace\-irreversibly \-\-no\-block\fR, but also prints a wall message to all users\&. This command is asynchronous; it will return after the power\-off operation is enqueued, without waiting for it to complete\&.
+.sp
+This command honors
+\fB\-\-force\fR
+and
+\fB\-\-when=\fR
+in a similar way as
+\fBhalt\fR\&.
+.RE
+.PP
+\fBreboot\fR
+.RS 4
+Shut down and reboot the system\&.
+.sp
+This command mostly equivalent to
+\fBsystemctl start reboot\&.target \-\-job\-mode=replace\-irreversibly \-\-no\-block\fR, but also prints a wall message to all users\&. This command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to complete\&.
+.sp
+If the switch
+\fB\-\-reboot\-argument=\fR
+is given, it will be passed as the optional argument to the
+\fBreboot\fR(2)
+system call\&.
+.sp
+Options
+\fB\-\-boot\-loader\-entry=\fR,
+\fB\-\-boot\-loader\-menu=\fR, and
+\fB\-\-firmware\-setup\fR
+can be used to select what to do
+\fIafter\fR
+the reboot\&. See the descriptions of those options for details\&.
+.sp
+This command honors
+\fB\-\-force\fR
+and
+\fB\-\-when=\fR
+in a similar way as
+\fBhalt\fR\&.
+.sp
+If a new kernel has been loaded via
+\fBkexec \-\-load\fR, a
+\fBkexec\fR
+will be performed instead of a reboot, unless
+"SYSTEMCTL_SKIP_AUTO_KEXEC=1"
+has been set\&. If a new root file system has been set up on
+"/run/nextroot/", a
+\fBsoft\-reboot\fR
+will be performed instead of a reboot, unless
+"SYSTEMCTL_SKIP_AUTO_SOFT_REBOOT=1"
+has been set\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBkexec\fR
+.RS 4
+Shut down and reboot the system via
+\fBkexec\fR\&. This command will load a kexec kernel if one wasn\*(Aqt loaded yet or fail\&. A kernel may be loaded earlier by a separate step, this is particularly useful if a custom initrd or additional kernel command line options are desired\&. The
+\fB\-\-force\fR
+can be used to continue without a kexec kernel, i\&.e\&. to perform a normal reboot\&. The final reboot step is equivalent to
+\fBsystemctl start kexec\&.target \-\-job\-mode=replace\-irreversibly \-\-no\-block\fR\&.
+.sp
+To load a kernel, an enumeration is performed following the
+\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, and the default boot entry is loaded\&. For this step to succeed, the system must be using UEFI and the boot loader entries must be configured appropriately\&.
+\fBbootctl list\fR
+may be used to list boot entries, see
+\fBbootctl\fR(1)\&.
+.sp
+This command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to complete\&.
+.sp
+This command honors
+\fB\-\-force\fR
+and
+\fB\-\-when=\fR
+similarly to
+\fBhalt\fR\&.
+.sp
+If a new kernel has been loaded via
+\fBkexec \-\-load\fR, a
+\fBkexec\fR
+will be performed when
+\fBreboot\fR
+is invoked, unless
+"SYSTEMCTL_SKIP_AUTO_KEXEC=1"
+has been set\&.
+.RE
+.PP
+\fBsoft\-reboot\fR
+.RS 4
+Shut down and reboot userspace\&. This is equivalent to
+\fBsystemctl start soft\-reboot\&.target \-\-job\-mode=replace\-irreversibly \-\-no\-block\fR\&. This command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to complete\&.
+.sp
+This command honors
+\fB\-\-force\fR
+and
+\fB\-\-when=\fR
+in a similar way as
+\fBhalt\fR\&.
+.sp
+This operation only reboots userspace, leaving the kernel running\&. See
+\fBsystemd-soft-reboot.service\fR(8)
+for details\&.
+.sp
+If a new root file system has been set up on
+"/run/nextroot/", a
+\fBsoft\-reboot\fR
+will be performed when
+\fBreboot\fR
+is invoked, unless
+"SYSTEMCTL_SKIP_AUTO_SOFT_REBOOT=1"
+has been set\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBexit\fR [\fIEXIT_CODE\fR]
+.RS 4
+Ask the service manager to quit\&. This is only supported for user service managers (i\&.e\&. in conjunction with the
+\fB\-\-user\fR
+option) or in containers and is equivalent to
+\fBpoweroff\fR
+otherwise\&. This command is asynchronous; it will return after the exit operation is enqueued, without waiting for it to complete\&.
+.sp
+The service manager will exit with the specified exit code, if
+\fIEXIT_CODE\fR
+is passed\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fBswitch\-root\fR [\fIROOT\fR [\fIINIT\fR]]
+.RS 4
+Switches to a different root directory and executes a new system manager process below it\&. This is intended for use in the initrd, and will transition from the initrd\*(Aqs system manager process (a\&.k\&.a\&. "init" process, PID 1) to the main system manager process which is loaded from the actual host root files system\&. This call takes two arguments: the directory that is to become the new root directory, and the path to the new system manager binary below it to execute as PID 1\&. If both are omitted or the former is an empty string it defaults to
+/sysroot/\&. If the latter is omitted or is an empty string, a systemd binary will automatically be searched for and used as service manager\&. If the system manager path is omitted, equal to the empty string or identical to the path to the systemd binary, the state of the initrd\*(Aqs system manager process is passed to the main system manager, which allows later introspection of the state of the services involved in the initrd boot phase\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fBsuspend\fR
+.RS 4
+Suspend the system\&. This will trigger activation of the special target unit
+suspend\&.target\&. This command is asynchronous, and will return after the suspend operation is successfully enqueued\&. It will not wait for the suspend/resume cycle to complete\&.
+.RE
+.PP
+\fBhibernate\fR
+.RS 4
+Hibernate the system\&. This will trigger activation of the special target unit
+hibernate\&.target\&. This command is asynchronous, and will return after the hibernation operation is successfully enqueued\&. It will not wait for the hibernate/thaw cycle to complete\&.
+.RE
+.PP
+\fBhybrid\-sleep\fR
+.RS 4
+Hibernate and suspend the system\&. This will trigger activation of the special target unit
+hybrid\-sleep\&.target\&. This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued\&. It will not wait for the sleep/wake\-up cycle to complete\&.
+.sp
+Added in version 196\&.
+.RE
+.PP
+\fBsuspend\-then\-hibernate\fR
+.RS 4
+Suspend the system and hibernate it after the delay specified in
+systemd\-sleep\&.conf\&. This will trigger activation of the special target unit
+suspend\-then\-hibernate\&.target\&. This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued\&. It will not wait for the sleep/wake\-up or hibernate/thaw cycle to complete\&.
+.sp
+Added in version 240\&.
+.RE
+.SS "Parameter Syntax"
+.PP
+Unit commands listed above take either a single unit name (designated as
+\fIUNIT\fR), or multiple unit specifications (designated as
+\fIPATTERN\fR\&...)\&. In the first case, the unit name with or without a suffix must be given\&. If the suffix is not specified (unit name is "abbreviated"), systemctl will append a suitable suffix,
+"\&.service"
+by default, and a type\-specific suffix in case of commands which operate only on specific unit types\&. For example,
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl start sshd
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+and
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl start sshd\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+are equivalent, as are
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl isolate default
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+and
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl isolate default\&.target
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) paths to mount unit names\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl status /dev/sda
+# systemctl status /home
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+are equivalent to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl status dev\-sda\&.device
+# systemctl status home\&.mount
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+In the second case, shell\-style globs will be matched against the primary names of all units currently in memory; literal unit names, with or without a suffix, will be treated as in the first case\&. This means that literal unit names always refer to exactly one unit, but globs may match zero units and this is not considered an error\&.
+.PP
+Glob patterns use
+\fBfnmatch\fR(3), so normal shell\-style globbing rules are used, and
+"*",
+"?",
+"[]"
+may be used\&. See
+\fBglob\fR(7)
+for more details\&. The patterns are matched against the primary names of units currently in memory, and patterns which do not match anything are silently skipped\&. For example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl stop sshd@*\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+will stop all
+sshd@\&.service
+instances\&. Note that alias names of units, and units that aren\*(Aqt in memory are not considered for glob expansion\&.
+.PP
+For unit file commands, the specified
+\fIUNIT\fR
+should be the name of the unit file (possibly abbreviated, see above), or the absolute path to the unit file:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl enable foo\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+or
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemctl link /path/to/foo\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-t\fR, \fB\-\-type=\fR
+.RS 4
+The argument is a comma\-separated list of unit types such as
+\fBservice\fR
+and
+\fBsocket\fR\&. When units are listed with
+\fBlist\-units\fR,
+\fBlist\-dependencies\fR,
+\fBshow\fR, or
+\fBstatus\fR, only units of the specified types will be shown\&. By default, units of all types are shown\&.
+.sp
+As a special case, if one of the arguments is
+\fBhelp\fR, a list of allowed values will be printed and the program will exit\&.
+.RE
+.PP
+\fB\-\-state=\fR
+.RS 4
+The argument is a comma\-separated list of unit LOAD, SUB, or ACTIVE states\&. When listing units with
+\fBlist\-units\fR,
+\fBlist\-dependencies\fR,
+\fBshow\fR
+or
+\fBstatus\fR, show only those in the specified states\&. Use
+\fB\-\-state=failed\fR
+or
+\fB\-\-failed\fR
+to show only failed units\&.
+.sp
+As a special case, if one of the arguments is
+\fBhelp\fR, a list of allowed values will be printed and the program will exit\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-property=\fR
+.RS 4
+When showing unit/job/manager properties with the
+\fBshow\fR
+command, limit display to properties specified in the argument\&. The argument should be a comma\-separated list of property names, such as
+"MainPID"\&. Unless specified, all known properties are shown\&. If specified more than once, all properties with the specified names are shown\&. Shell completion is implemented for property names\&.
+.sp
+For the manager itself,
+\fBsystemctl\ \&show\fR
+will show all available properties, most of which are derived or closely match the options described in
+\fBsystemd-system.conf\fR(5)\&.
+.sp
+Properties for units vary by unit type, so showing any unit (even a non\-existent one) is a way to list properties pertaining to this type\&. Similarly, showing any job will list properties pertaining to all jobs\&. Properties for units are documented in
+\fBsystemd.unit\fR(5), and the pages for individual unit types
+\fBsystemd.service\fR(5),
+\fBsystemd.socket\fR(5), etc\&.
+.RE
+.PP
+\fB\-P\fR
+.RS 4
+Equivalent to
+\fB\-\-value\fR
+\fB\-\-property=\fR, i\&.e\&. shows the value of the property without the property name or
+"="\&. Note that using
+\fB\-P\fR
+once will also affect all properties listed with
+\fB\-p\fR/\fB\-\-property=\fR\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-all\fR
+.RS 4
+When listing units with
+\fBlist\-units\fR, also show inactive units and units which are following other units\&. When showing unit/job/manager properties, show all properties regardless whether they are set or not\&.
+.sp
+To list all units installed in the file system, use the
+\fBlist\-unit\-files\fR
+command instead\&.
+.sp
+When listing units with
+\fBlist\-dependencies\fR, recursively show dependencies of all dependent units (by default only dependencies of target units are shown)\&.
+.sp
+When used with
+\fBstatus\fR, show journal messages in full, even if they include unprintable characters or are very long\&. By default, fields with unprintable characters are abbreviated as "blob data"\&. (Note that the pager may escape unprintable characters again\&.)
+.RE
+.PP
+\fB\-r\fR, \fB\-\-recursive\fR
+.RS 4
+When listing units, also show units of local containers\&. Units of local containers will be prefixed with the container name, separated by a single colon character (":")\&.
+.sp
+Added in version 212\&.
+.RE
+.PP
+\fB\-\-reverse\fR
+.RS 4
+Show reverse dependencies between units with
+\fBlist\-dependencies\fR, i\&.e\&. follow dependencies of type
+\fIWantedBy=\fR,
+\fIRequiredBy=\fR,
+\fIUpheldBy=\fR,
+\fIPartOf=\fR,
+\fIBoundBy=\fR, instead of
+\fIWants=\fR
+and similar\&.
+.sp
+Added in version 203\&.
+.RE
+.PP
+\fB\-\-after\fR
+.RS 4
+With
+\fBlist\-dependencies\fR, show the units that are ordered before the specified unit\&. In other words, recursively list units following the
+\fIAfter=\fR
+dependency\&.
+.sp
+Note that any
+\fIAfter=\fR
+dependency is automatically mirrored to create a
+\fIBefore=\fR
+dependency\&. Temporal dependencies may be specified explicitly, but are also created implicitly for units which are
+\fIWantedBy=\fR
+targets (see
+\fBsystemd.target\fR(5)), and as a result of other directives (for example
+\fIRequiresMountsFor=\fR)\&. Both explicitly and implicitly introduced dependencies are shown with
+\fBlist\-dependencies\fR\&.
+.sp
+When passed to the
+\fBlist\-jobs\fR
+command, for each printed job show which other jobs are waiting for it\&. May be combined with
+\fB\-\-before\fR
+to show both the jobs waiting for each job as well as all jobs each job is waiting for\&.
+.sp
+Added in version 203\&.
+.RE
+.PP
+\fB\-\-before\fR
+.RS 4
+With
+\fBlist\-dependencies\fR, show the units that are ordered after the specified unit\&. In other words, recursively list units following the
+\fIBefore=\fR
+dependency\&.
+.sp
+When passed to the
+\fBlist\-jobs\fR
+command, for each printed job show which other jobs it is waiting for\&. May be combined with
+\fB\-\-after\fR
+to show both the jobs waiting for each job as well as all jobs each job is waiting for\&.
+.sp
+Added in version 212\&.
+.RE
+.PP
+\fB\-\-with\-dependencies\fR
+.RS 4
+When used with
+\fBstatus\fR,
+\fBcat\fR,
+\fBlist\-units\fR, and
+\fBlist\-unit\-files\fR, those commands print all specified units and the dependencies of those units\&.
+.sp
+Options
+\fB\-\-reverse\fR,
+\fB\-\-after\fR,
+\fB\-\-before\fR
+may be used to change what types of dependencies are shown\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize unit names, process tree entries, journal output, or truncate unit descriptions in the output of
+\fBstatus\fR,
+\fBlist\-units\fR,
+\fBlist\-jobs\fR, and
+\fBlist\-timers\fR\&.
+.sp
+Also, show installation targets in the output of
+\fBis\-enabled\fR\&.
+.RE
+.PP
+\fB\-\-value\fR
+.RS 4
+When printing properties with
+\fBshow\fR, only print the value, and skip the property name and
+"="\&. Also see option
+\fB\-P\fR
+above\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-show\-types\fR
+.RS 4
+When showing sockets, show the type of the socket\&.
+.sp
+Added in version 202\&.
+.RE
+.PP
+\fB\-\-job\-mode=\fR
+.RS 4
+When queuing a new job, this option controls how to deal with already queued jobs\&. It takes one of
+"fail",
+"replace",
+"replace\-irreversibly",
+"isolate",
+"ignore\-dependencies",
+"ignore\-requirements",
+"flush",
+"triggering", or
+"restart\-dependencies"\&. Defaults to
+"replace", except when the
+\fBisolate\fR
+command is used which implies the
+"isolate"
+job mode\&.
+.sp
+If
+"fail"
+is specified and a requested operation conflicts with a pending job (more specifically: causes an already pending start job to be reversed into a stop job or vice versa), cause the operation to fail\&.
+.sp
+If
+"replace"
+(the default) is specified, any conflicting pending job will be replaced, as necessary\&.
+.sp
+If
+"replace\-irreversibly"
+is specified, operate like
+"replace", but also mark the new jobs as irreversible\&. This prevents future conflicting transactions from replacing these jobs (or even being enqueued while the irreversible jobs are still pending)\&. Irreversible jobs can still be cancelled using the
+\fBcancel\fR
+command\&. This job mode should be used on any transaction which pulls in
+shutdown\&.target\&.
+.sp
+"isolate"
+is only valid for start operations and causes all other units to be stopped when the specified unit is started\&. This mode is always used when the
+\fBisolate\fR
+command is used\&.
+.sp
+"flush"
+will cause all queued jobs to be canceled when the new job is enqueued\&.
+.sp
+If
+"ignore\-dependencies"
+is specified, then all unit dependencies are ignored for this new job and the operation is executed immediately\&. If passed, no required units of the unit passed will be pulled in, and no ordering dependencies will be honored\&. This is mostly a debugging and rescue tool for the administrator and should not be used by applications\&.
+.sp
+"ignore\-requirements"
+is similar to
+"ignore\-dependencies", but only causes the requirement dependencies to be ignored, the ordering dependencies will still be honored\&.
+.sp
+"triggering"
+may only be used with
+\fBsystemctl stop\fR\&. In this mode, the specified unit and any active units that trigger it are stopped\&. See the discussion of
+\fITriggers=\fR
+in
+\fBsystemd.unit\fR(5)
+for more information about triggering units\&.
+.sp
+"restart\-dependencies"
+may only be used with
+\fBsystemctl start\fR\&. In this mode, dependencies of the specified unit will receive restart propagation, as if a restart job had been enqueued for the unit\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-T\fR, \fB\-\-show\-transaction\fR
+.RS 4
+When enqueuing a unit job (for example as effect of a
+\fBsystemctl start\fR
+invocation or similar), show brief information about all jobs enqueued, covering both the requested job and any added because of unit dependencies\&. Note that the output will only include jobs immediately part of the transaction requested\&. It is possible that service start\-up program code run as effect of the enqueued jobs might request further jobs to be pulled in\&. This means that completion of the listed jobs might ultimately entail more jobs than the listed ones\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-fail\fR
+.RS 4
+Shorthand for
+\fB\-\-job\-mode=\fRfail\&.
+.sp
+When used with the
+\fBkill\fR
+command, if no units were killed, the operation results in an error\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-check\-inhibitors=\fR
+.RS 4
+When system shutdown or sleep state is requested, this option controls checking of inhibitor locks\&. It takes one of
+"auto",
+"yes"
+or
+"no"\&. Defaults to
+"auto", which will behave like
+"yes"
+for interactive invocations (i\&.e\&. from a TTY) and
+"no"
+for non\-interactive invocations\&.
+"yes"
+lets the request respect inhibitor locks\&.
+"no"
+lets the request ignore inhibitor locks\&.
+.sp
+Applications can establish inhibitor locks to prevent certain important operations (such as CD burning) from being interrupted by system shutdown or sleep\&. Any user may take these locks and privileged users may override these locks\&. If any locks are taken, shutdown and sleep state requests will normally fail (unless privileged)\&. However, if
+"no"
+is specified or
+"auto"
+is specified on a non\-interactive requests, the operation will be attempted\&. If locks are present, the operation may require additional privileges\&.
+.sp
+Option
+\fB\-\-force\fR
+provides another way to override inhibitors\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-i\fR
+.RS 4
+Shortcut for
+\fB\-\-check\-inhibitors=no\fR\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-\-dry\-run\fR
+.RS 4
+Just print what would be done\&. Currently supported by verbs
+\fBhalt\fR,
+\fBpoweroff\fR,
+\fBreboot\fR,
+\fBkexec\fR,
+\fBsuspend\fR,
+\fBhibernate\fR,
+\fBhybrid\-sleep\fR,
+\fBsuspend\-then\-hibernate\fR,
+\fBdefault\fR,
+\fBrescue\fR,
+\fBemergency\fR, and
+\fBexit\fR\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppress printing of the results of various commands and also the hints about truncated log lines\&. This does not suppress output of commands for which the printed output is the only result (like
+\fBshow\fR)\&. Errors are always printed\&.
+.RE
+.PP
+\fB\-\-no\-warn\fR
+.RS 4
+Don\*(Aqt generate the warnings shown by default in the following cases:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+when
+\fBsystemctl\fR
+is invoked without procfs mounted on
+/proc/,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+when using
+\fBenable\fR
+or
+\fBdisable\fR
+on units without install information (i\&.e\&. don\*(Aqt have or have an empty [Install] section),
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+when using
+\fBdisable\fR
+combined with
+\fB\-\-user\fR
+on units that are enabled in global scope,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+when a
+\fBstop\fR\-ped,
+\fBdisable\fR\-d, or
+\fBmask\fR\-ed unit still has active triggering units\&.
+.RE
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-no\-block\fR
+.RS 4
+Do not synchronously wait for the requested operation to finish\&. If this is not specified, the job will be verified, enqueued and
+\fBsystemctl\fR
+will wait until the unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&. This option may not be combined with
+\fB\-\-wait\fR\&.
+.RE
+.PP
+\fB\-\-wait\fR
+.RS 4
+Synchronously wait for started units to terminate again\&. This option may not be combined with
+\fB\-\-no\-block\fR\&. Note that this will wait forever if any given unit never terminates (by itself or by getting stopped explicitly); particularly services which use
+"RemainAfterExit=yes"\&.
+.sp
+When used with
+\fBis\-system\-running\fR, wait until the boot process is completed before returning\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-user\fR
+.RS 4
+Talk to the service manager of the calling user, rather than the service manager of the system\&.
+.RE
+.PP
+\fB\-\-system\fR
+.RS 4
+Talk to the service manager of the system\&. This is the implied default\&.
+.RE
+.PP
+\fB\-\-failed\fR
+.RS 4
+List units in failed state\&. This is equivalent to
+\fB\-\-state=failed\fR\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-\-no\-wall\fR
+.RS 4
+Do not send wall message before halt, power\-off and reboot\&.
+.RE
+.PP
+\fB\-\-global\fR
+.RS 4
+When used with
+\fBenable\fR
+and
+\fBdisable\fR, operate on the global user configuration directory, thus enabling or disabling a unit file globally for all future logins of all users\&.
+.RE
+.PP
+\fB\-\-no\-reload\fR
+.RS 4
+When used with
+\fBenable\fR
+and
+\fBdisable\fR, do not implicitly reload daemon configuration after executing the changes\&.
+.RE
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+When used with
+\fBstart\fR
+and related commands, disables asking for passwords\&. Background services may require input of a password or passphrase string, for example to unlock system hard disks or cryptographic certificates\&. Unless this option is specified and the command is invoked from a terminal,
+\fBsystemctl\fR
+will query the user on the terminal for the necessary secrets\&. Use this option to switch this behavior off\&. In this case, the password must be supplied by some other means (for example graphical password agents) or the service might fail\&. This also disables querying the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-\-kill\-whom=\fR
+.RS 4
+When used with
+\fBkill\fR, choose which processes to send a UNIX process signal to\&. Must be one of
+\fBmain\fR,
+\fBcontrol\fR
+or
+\fBall\fR
+to select whether to kill only the main process, the control process or all processes of the unit\&. The main process of the unit is the one that defines the life\-time of it\&. A control process of a unit is one that is invoked by the manager to induce state changes of it\&. For example, all processes started due to the
+\fIExecStartPre=\fR,
+\fIExecStop=\fR
+or
+\fIExecReload=\fR
+settings of service units are control processes\&. Note that there is only one control process per unit at a time, as only one state change is executed at a time\&. For services of type
+\fIType=forking\fR, the initial process started by the manager for
+\fIExecStart=\fR
+is a control process, while the process ultimately forked off by that one is then considered the main process of the unit (if it can be determined)\&. This is different for service units of other types, where the process forked off by the manager for
+\fIExecStart=\fR
+is always the main process itself\&. A service unit consists of zero or one main process, zero or one control process plus any number of additional processes\&. Not all unit types manage processes of these types however\&. For example, for mount units, control processes are defined (which are the invocations of
+/usr/bin/mount
+and
+/usr/bin/umount), but no main process is defined\&. If omitted, defaults to
+\fBall\fR\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-kill\-value=\fR\fIINT\fR
+.RS 4
+If used with the
+\fBkill\fR
+command, enqueues a signal along with the specified integer value parameter to the specified process(es)\&. This operation is only available for POSIX Realtime Signals (i\&.e\&.
+\fB\-\-signal=SIGRTMIN+\&...\fR
+or
+\fB\-\-signal=SIGRTMAX\-\&...\fR), and ensures the signals are generated via the
+\fBsigqueue\fR(3)
+system call, rather than
+\fBkill\fR(3)\&. The specified value must be a 32\-bit signed integer, and may be specified either in decimal, in hexadecimal (if prefixed with
+"0x"), octal (if prefixed with
+"0o") or binary (if prefixed with
+"0b")
+.sp
+If this option is used the signal will only be enqueued on the control or main process of the unit, never on other processes belonging to the unit, i\&.e\&.
+\fB\-\-kill\-whom=all\fR
+will only affect main and control processes but no other processes\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-s\fR, \fB\-\-signal=\fR
+.RS 4
+When used with
+\fBkill\fR, choose which signal to send to selected processes\&. Must be one of the well\-known signal specifiers such as
+\fBSIGTERM\fR,
+\fBSIGINT\fR
+or
+\fBSIGSTOP\fR\&. If omitted, defaults to
+\fBSIGTERM\fR\&.
+.sp
+The special value
+"help"
+will list the known values and the program will exit immediately, and the special value
+"list"
+will list known values along with the numerical signal numbers and the program will exit immediately\&.
+.RE
+.PP
+\fB\-\-what=\fR
+.RS 4
+Select what type of per\-unit resources to remove when the
+\fBclean\fR
+command is invoked, see above\&. Takes one of
+\fBconfiguration\fR,
+\fBstate\fR,
+\fBcache\fR,
+\fBlogs\fR,
+\fBruntime\fR,
+\fBfdstore\fR
+to select the type of resource\&. This option may be specified more than once, in which case all specified resource types are removed\&. Also accepts the special value
+\fBall\fR
+as a shortcut for specifying all six resource types\&. If this option is not specified defaults to the combination of
+\fBcache\fR,
+\fBruntime\fR
+and
+\fBfdstore\fR, i\&.e\&. the three kinds of resources that are generally considered to be redundant and can be reconstructed on next invocation\&. Note that the explicit removal of the
+\fBfdstore\fR
+resource type is only useful if the
+\fIFileDescriptorStorePreserve=\fR
+option is enabled, since the file descriptor store is otherwise cleaned automatically when the unit is stopped\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fB\-f\fR, \fB\-\-force\fR
+.RS 4
+When used with
+\fBenable\fR, overwrite any existing conflicting symlinks\&.
+.sp
+When used with
+\fBedit\fR, create all of the specified units which do not already exist\&.
+.sp
+When used with
+\fBhalt\fR,
+\fBpoweroff\fR,
+\fBreboot\fR
+or
+\fBkexec\fR, execute the selected operation without shutting down all units\&. However, all processes will be killed forcibly and all file systems are unmounted or remounted read\-only\&. This is hence a drastic but relatively safe option to request an immediate reboot\&. If
+\fB\-\-force\fR
+is specified twice for these operations (with the exception of
+\fBkexec\fR), they will be executed immediately, without terminating any processes or unmounting any file systems\&. Warning: specifying
+\fB\-\-force\fR
+twice with any of these operations might result in data loss\&. Note that when
+\fB\-\-force\fR
+is specified twice the selected operation is executed by
+\fBsystemctl\fR
+itself, and the system manager is not contacted\&. This means the command should succeed even when the system manager has crashed\&.
+.RE
+.PP
+\fB\-\-message=\fR
+.RS 4
+When used with
+\fBhalt\fR,
+\fBpoweroff\fR
+or
+\fBreboot\fR, set a short message explaining the reason for the operation\&. The message will be logged together with the default shutdown message\&.
+.sp
+Added in version 225\&.
+.RE
+.PP
+\fB\-\-now\fR
+.RS 4
+When used with
+\fBenable\fR, the units will also be started\&. When used with
+\fBdisable\fR
+or
+\fBmask\fR, the units will also be stopped\&. The start or stop operation is only carried out when the respective enable or disable operation has been successful\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-root=\fR
+.RS 4
+When used with
+\fBenable\fR/\fBdisable\fR/\fBis\-enabled\fR
+(and related commands), use the specified root path when looking for unit files\&. If this option is present,
+\fBsystemctl\fR
+will operate on the file system directly, instead of communicating with the
+\fBsystemd\fR
+daemon to carry out changes\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIimage\fR\fR
+.RS 4
+Takes a path to a disk image file or block device node\&. If specified, all operations are applied to file system in the indicated disk image\&. This option is similar to
+\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. For further information on supported disk images, see
+\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-runtime\fR
+.RS 4
+When used with
+\fBenable\fR,
+\fBdisable\fR,
+\fBedit\fR, (and related commands), make changes only temporarily, so that they are lost on the next reboot\&. This will have the effect that changes are not made in subdirectories of
+/etc/
+but in
+/run/, with identical immediate effects, however, since the latter is lost on reboot, the changes are lost too\&.
+.sp
+Similarly, when used with
+\fBset\-property\fR, make changes only temporarily, so that they are lost on the next reboot\&.
+.RE
+.PP
+\fB\-\-preset\-mode=\fR
+.RS 4
+Takes one of
+"full"
+(the default),
+"enable\-only",
+"disable\-only"\&. When used with the
+\fBpreset\fR
+or
+\fBpreset\-all\fR
+commands, controls whether units shall be disabled and enabled according to the preset rules, or only enabled, or only disabled\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-lines=\fR
+.RS 4
+When used with
+\fBstatus\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument, or 0 to disable journal output\&. Defaults to 10\&.
+.RE
+.PP
+\fB\-o\fR, \fB\-\-output=\fR
+.RS 4
+When used with
+\fBstatus\fR, controls the formatting of the journal entries that are shown\&. For the available choices, see
+\fBjournalctl\fR(1)\&. Defaults to
+"short"\&.
+.RE
+.PP
+\fB\-\-firmware\-setup\fR
+.RS 4
+When used with the
+\fBreboot\fR,
+\fBpoweroff\fR, or
+\fBhalt\fR
+command, indicate to the system\*(Aqs firmware to reboot into the firmware setup interface for the next boot\&. Note that this functionality is not available on all systems\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-boot\-loader\-menu=\fR\fB\fItimeout\fR\fR
+.RS 4
+When used with the
+\fBreboot\fR,
+\fBpoweroff\fR, or
+\fBhalt\fR
+command, indicate to the system\*(Aqs boot loader to show the boot loader menu on the following boot\&. Takes a time value as parameter \(em indicating the menu timeout\&. Pass zero in order to disable the menu timeout\&. Note that not all boot loaders support this functionality\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-boot\-loader\-entry=\fR\fB\fIID\fR\fR
+.RS 4
+When used with the
+\fBreboot\fR,
+\fBpoweroff\fR, or
+\fBhalt\fR
+command, indicate to the system\*(Aqs boot loader to boot into a specific boot loader entry on the following boot\&. Takes a boot loader entry identifier as argument, or
+"help"
+in order to list available entries\&. Note that not all boot loaders support this functionality\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-reboot\-argument=\fR
+.RS 4
+This switch is used with
+\fBreboot\fR\&. The value is architecture and firmware specific\&. As an example,
+"recovery"
+might be used to trigger system recovery, and
+"fota"
+might be used to trigger a
+\(lqfirmware over the air\(rq
+update\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-plain\fR
+.RS 4
+When used with
+\fBlist\-dependencies\fR,
+\fBlist\-units\fR
+or
+\fBlist\-machines\fR, the output is printed as a list instead of a tree, and the bullet circles are omitted\&.
+.sp
+Added in version 203\&.
+.RE
+.PP
+\fB\-\-timestamp=\fR
+.RS 4
+Change the format of printed timestamps\&. The following values may be used:
+.PP
+\fBpretty\fR (this is the default)
+.RS 4
+"Day YYYY\-MM\-DD HH:MM:SS TZ"
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fBunix\fR
+.RS 4
+"@seconds\-since\-the\-epoch"
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fBus\fR, \fBμs\fR
+.RS 4
+"Day YYYY\-MM\-DD HH:MM:SS\&.UUUUUU TZ"
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fButc\fR
+.RS 4
+"Day YYYY\-MM\-DD HH:MM:SS UTC"
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fBus+utc\fR, \fBμs+utc\fR
+.RS 4
+"Day YYYY\-MM\-DD HH:MM:SS\&.UUUUUU UTC"
+.sp
+Added in version 248\&.
+.RE
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-mkdir\fR
+.RS 4
+When used with
+\fBbind\fR, creates the destination file or directory before applying the bind mount\&. Note that even though the name of this option suggests that it is suitable only for directories, this option also creates the destination file node to mount over if the object to mount is not a directory, but a regular file, device node, socket or FIFO\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-marked\fR
+.RS 4
+Only allowed with
+\fBreload\-or\-restart\fR\&. Enqueues restart jobs for all units that have the
+"needs\-restart"
+mark, and reload jobs for units that have the
+"needs\-reload"
+mark\&. When a unit marked for reload does not support reload, restart will be queued\&. Those properties can be set using
+\fBset\-property Markers=\&...\fR\&.
+.sp
+Unless
+\fB\-\-no\-block\fR
+is used,
+\fBsystemctl\fR
+will wait for the queued jobs to finish\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-read\-only\fR
+.RS 4
+When used with
+\fBbind\fR, creates a read\-only bind mount\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-drop\-in=\fR\fINAME\fR
+.RS 4
+When used with
+\fBedit\fR, use
+\fINAME\fR
+as the drop\-in file name instead of
+override\&.conf\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-when=\fR
+.RS 4
+When used with
+\fBhalt\fR,
+\fBpoweroff\fR,
+\fBreboot\fR
+or
+\fBkexec\fR, schedule the action to be performed at the given timestamp, which should adhere to the syntax documented in
+\fBsystemd.time\fR(7)
+section "PARSING TIMESTAMPS"\&. Specially, if
+"show"
+is given, the currently scheduled action will be shown, which can be canceled by passing an empty string or
+"cancel"\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-legend=\fR\fIBOOL\fR
+.RS 4
+Enable or disable printing of the legend, i\&.e\&. column headers and the footer with hints\&. The legend is printed by default, unless disabled with
+\fB\-\-quiet\fR
+or similar\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.PP
+\fBsystemctl\fR
+uses the return codes defined by LSB, as defined in
+\m[blue]\fBLSB 3\&.0\&.0\fR\m[]\&\s-2\u[3]\d\s+2\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&3.\ \&LSB return codes
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+Value
+T}:T{
+Description in LSB
+T}:T{
+Use in systemd
+T}
+.T&
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+\fB0\fR
+T}:T{
+"program is running or service is OK"
+T}:T{
+unit is active
+T}
+T{
+\fB1\fR
+T}:T{
+"program is dead and /var/run pid file exists"
+T}:T{
+unit \fInot\fR failed (used by \fBis\-failed\fR)
+T}
+T{
+\fB2\fR
+T}:T{
+"program is dead and /var/lock lock file exists"
+T}:T{
+unused
+T}
+T{
+\fB3\fR
+T}:T{
+"program is not running"
+T}:T{
+unit is not active
+T}
+T{
+\fB4\fR
+T}:T{
+"program or service status is unknown"
+T}:T{
+no such unit
+T}
+.TE
+.sp 1
+.PP
+The mapping of LSB service states to systemd unit states is imperfect, so it is better to not rely on those return values but to look for specific unit states and substates instead\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_EDITOR\fR
+.RS 4
+Editor to use when editing units; overrides
+\fI$EDITOR\fR
+and
+\fI$VISUAL\fR\&. If neither
+\fI$SYSTEMD_EDITOR\fR
+nor
+\fI$EDITOR\fR
+nor
+\fI$VISUAL\fR
+are present or if it is set to an empty string or if their execution failed, systemctl will try to execute well known editors in this order:
+\fBeditor\fR(1),
+\fBnano\fR(1),
+\fBvim\fR(1),
+\fBvi\fR(1)\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBjournalctl\fR(1),
+\fBloginctl\fR(1),
+\fBmachinectl\fR(1),
+\fBsystemd.unit\fR(5),
+\fBsystemd.resource-control\fR(5),
+\fBsystemd.special\fR(7),
+\fBwall\fR(1),
+\fBsystemd.preset\fR(5),
+\fBsystemd.generator\fR(7),
+\fBglob\fR(7)
+.SH "NOTES"
+.IP " 1." 4
+Boot Loader Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/boot_loader_specification
+.RE
+.IP " 2." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
+.IP " 3." 4
+LSB 3.0.0
+.RS 4
+\%http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/iniscrptact.html
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-ac-power.1 b/upstream/mageia-cauldron/man1/systemd-ac-power.1
new file mode 100644
index 00000000..aadfbf33
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-ac-power.1
@@ -0,0 +1,66 @@
+'\" t
+.TH "SYSTEMD\-AC\-POWER" "1" "" "systemd 255" "systemd-ac-power"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-ac-power \- Report whether we are connected to an external power source
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-ac\-power\fR\ 'u
+\fBsystemd\-ac\-power\fR [OPTIONS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-ac\-power\fR
+may be used to check whether the system is running on AC power or not\&. By default it will simply return success (if we can detect that we are running on AC power) or failure, with no output\&. This can be useful for example to debug
+\fIConditionACPower=\fR
+(see
+\fBsystemd.unit\fR(5))\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-v\fR, \fB\-\-verbose\fR
+.RS 4
+Show result as text instead of just returning success or failure\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-low\fR
+.RS 4
+Instead of showing AC power state, show low battery state\&. In this case will return zero if all batteries are currently discharging and below 5% of maximum charge\&. Returns non\-zero otherwise\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success (running on AC power), 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-analyze.1 b/upstream/mageia-cauldron/man1/systemd-analyze.1
new file mode 100644
index 00000000..ce1a2b09
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-analyze.1
@@ -0,0 +1,1885 @@
+'\" t
+.TH "SYSTEMD\-ANALYZE" "1" "" "systemd 255" "systemd-analyze"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-analyze \- Analyze and debug system manager
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] [time]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] blame
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] critical\-chain [\fIUNIT\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] dump [\fIPATTERN\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] plot [>file\&.svg]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] dot [\fIPATTERN\fR...] [>file\&.dot]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] unit\-files
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] unit\-paths
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] exit\-status [\fISTATUS\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] capability [\fICAPABILITY\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] condition \fICONDITION\fR\&...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] syscall\-filter [\fISET\fR\&...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] filesystems [\fISET\fR\&...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] calendar \fISPEC\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] timestamp \fITIMESTAMP\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] timespan \fISPAN\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] cat\-config \fINAME\fR|\fIPATH\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] compare\-versions \fIVERSION1\fR [\fIOP\fR] \fIVERSION2\fR
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] verify \fIFILE\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] security [\fIUNIT\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] inspect\-elf \fIFILE\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] malloc [\fID\-BUS\ SERVICE\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] fdstore \fIUNIT\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] image\-policy \fIPOLICY\fR...
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] pcrs [\fIPCR\fR...]
+.HP \w'\fBsystemd\-analyze\fR\ 'u
+\fBsystemd\-analyze\fR [OPTIONS...] srk > \fIFILE\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-analyze\fR
+may be used to determine system boot\-up performance statistics and retrieve other state and tracing information from the system and service manager, and to verify the correctness of unit files\&. It is also used to access special functions useful for advanced system manager debugging\&.
+.PP
+If no command is passed,
+\fBsystemd\-analyze time\fR
+is implied\&.
+.SS "systemd\-analyze time"
+.PP
+This command prints the time spent in the kernel before userspace has been reached, the time spent in the initrd before normal system userspace has been reached, and the time normal system userspace took to initialize\&. Note that these measurements simply measure the time passed up to the point where all system services have been spawned, but not necessarily until they fully finished initialization or the disk is idle\&.
+.PP
+\fBExample\ \&1.\ \&Show how long the boot took\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# in a container
+$ systemd\-analyze time
+Startup finished in 296ms (userspace)
+multi\-user\&.target reached after 275ms in userspace
+
+# on a real machine
+$ systemd\-analyze time
+Startup finished in 2\&.584s (kernel) + 19\&.176s (initrd) + 47\&.847s (userspace) = 1min 9\&.608s
+multi\-user\&.target reached after 47\&.820s in userspace
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze blame"
+.PP
+This command prints a list of all running units, ordered by the time they took to initialize\&. This information may be used to optimize boot\-up times\&. Note that the output might be misleading as the initialization of one service might be slow simply because it waits for the initialization of another service to complete\&. Also note:
+\fBsystemd\-analyze blame\fR
+doesn\*(Aqt display results for services with
+\fIType=simple\fR, because systemd considers such services to be started immediately, hence no measurement of the initialization delays can be done\&. Also note that this command only shows the time units took for starting up, it does not show how long unit jobs spent in the execution queue\&. In particular it shows the time units spent in
+"activating"
+state, which is not defined for units such as device units that transition directly from
+"inactive"
+to
+"active"\&. This command hence gives an impression of the performance of program code, but cannot accurately reflect latency introduced by waiting for hardware and similar events\&.
+.PP
+\fBExample\ \&2.\ \&Show which units took the most time during boot\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze blame
+         32\&.875s pmlogger\&.service
+         20\&.905s systemd\-networkd\-wait\-online\&.service
+         13\&.299s dev\-vda1\&.device
+         \&.\&.\&.
+            23ms sysroot\&.mount
+            11ms initrd\-udevadm\-cleanup\-db\&.service
+             3ms sys\-kernel\-config\&.mount
+        
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze critical\-chain [\fIUNIT\fR\&.\&.\&.]"
+.PP
+This command prints a tree of the time\-critical chain of units (for each of the specified
+\fIUNIT\fRs or for the default target otherwise)\&. The time after the unit is active or started is printed after the "@" character\&. The time the unit takes to start is printed after the "+" character\&. Note that the output might be misleading as the initialization of services might depend on socket activation and because of the parallel execution of units\&. Also, similarly to the
+\fBblame\fR
+command, this only takes into account the time units spent in
+"activating"
+state, and hence does not cover units that never went through an
+"activating"
+state (such as device units that transition directly from
+"inactive"
+to
+"active")\&. Moreover it does not show information on jobs (and in particular not jobs that timed out)\&.
+.PP
+\fBExample\ \&3.\ \&systemd\-analyze critical\-chain\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze critical\-chain
+multi\-user\&.target @47\&.820s
+└─pmie\&.service @35\&.968s +548ms
+  └─pmcd\&.service @33\&.715s +2\&.247s
+    └─network\-online\&.target @33\&.712s
+      └─systemd\-networkd\-wait\-online\&.service @12\&.804s +20\&.905s
+        └─systemd\-networkd\&.service @11\&.109s +1\&.690s
+          └─systemd\-udevd\&.service @9\&.201s +1\&.904s
+            └─systemd\-tmpfiles\-setup\-dev\&.service @7\&.306s +1\&.776s
+              └─kmod\-static\-nodes\&.service @6\&.976s +177ms
+                └─systemd\-journald\&.socket
+                  └─system\&.slice
+                    └─\-\&.slice
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze dump [\fIpattern\fR\&...]"
+.PP
+Without any parameter, this command outputs a (usually very long) human\-readable serialization of the complete service manager state\&. Optional glob pattern may be specified, causing the output to be limited to units whose names match one of the patterns\&. The output format is subject to change without notice and should not be parsed by applications\&. This command is rate limited for unprivileged users\&.
+.PP
+\fBExample\ \&4.\ \&Show the internal state of user manager\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze \-\-user dump
+Timestamp userspace: Thu 2019\-03\-14 23:28:07 CET
+Timestamp finish: Thu 2019\-03\-14 23:28:07 CET
+Timestamp generators\-start: Thu 2019\-03\-14 23:28:07 CET
+Timestamp generators\-finish: Thu 2019\-03\-14 23:28:07 CET
+Timestamp units\-load\-start: Thu 2019\-03\-14 23:28:07 CET
+Timestamp units\-load\-finish: Thu 2019\-03\-14 23:28:07 CET
+\-> Unit proc\-timer_list\&.mount:
+        Description: /proc/timer_list
+        \&.\&.\&.
+\-> Unit default\&.target:
+        Description: Main user target
+\&.\&.\&.
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze malloc [\fID\-Bus service\fR\&...]"
+.PP
+This command can be used to request the output of the internal memory state (as returned by
+\fBmalloc_info\fR(3)) of a D\-Bus service\&. If no service is specified, the query will be sent to
+org\&.freedesktop\&.systemd1
+(the system or user service manager)\&. The output format is not guaranteed to be stable and should not be parsed by applications\&.
+.PP
+The service must implement the
+org\&.freedesktop\&.MemoryAllocation1
+interface\&. In the systemd suite, it is currently only implemented by the manager\&.
+.SS "systemd\-analyze plot"
+.PP
+This command prints either an SVG graphic, detailing which system services have been started at what time, highlighting the time they spent on initialization, or the raw time data in JSON or table format\&.
+.PP
+\fBExample\ \&5.\ \&Plot a bootchart\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze plot >bootup\&.svg
+$ eog bootup\&.svg&
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note that this plot is based on the most recent per\-unit timing data of loaded units\&. This means that if a unit gets started, then stopped and then started again the information shown will cover the most recent start cycle, not the first one\&. Thus it\*(Aqs recommended to consult this information only shortly after boot, so that this distinction doesn\*(Aqt matter\&. Moreover, units that are not referenced by any other unit through a dependency might be unloaded by the service manager once they terminate (and did not fail)\&. Such units will not show up in the plot\&.
+.SS "systemd\-analyze dot [\fIpattern\fR\&.\&.\&.]"
+.PP
+This command generates textual dependency graph description in dot format for further processing with the GraphViz
+\fBdot\fR(1)
+tool\&. Use a command line like
+\fBsystemd\-analyze dot | dot \-Tsvg >systemd\&.svg\fR
+to generate a graphical dependency tree\&. Unless
+\fB\-\-order\fR
+or
+\fB\-\-require\fR
+is passed, the generated graph will show both ordering and requirement dependencies\&. Optional pattern globbing style specifications (e\&.g\&.
+*\&.target) may be given at the end\&. A unit dependency is included in the graph if any of these patterns match either the origin or destination node\&.
+.PP
+\fBExample\ \&6.\ \&Plot all dependencies of any unit whose name starts with "avahi\-daemon"\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze dot \*(Aqavahi\-daemon\&.*\*(Aq | dot \-Tsvg >avahi\&.svg
+$ eog avahi\&.svg
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&7.\ \&Plot the dependencies between all known target units\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze dot \-\-to\-pattern=\*(Aq*\&.target\*(Aq \-\-from\-pattern=\*(Aq*\&.target\*(Aq \e
+      | dot \-Tsvg >targets\&.svg
+$ eog targets\&.svg
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze unit\-paths"
+.PP
+This command outputs a list of all directories from which unit files,
+\&.d
+overrides, and
+\&.wants,
+\&.requires
+symlinks may be loaded\&. Combine with
+\fB\-\-user\fR
+to retrieve the list for the user manager instance, and
+\fB\-\-global\fR
+for the global configuration of user manager instances\&.
+.PP
+\fBExample\ \&8.\ \&Show all paths for generated units\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze unit\-paths | grep \*(Aq^/run\*(Aq
+/run/systemd/system\&.control
+/run/systemd/transient
+/run/systemd/generator\&.early
+/run/systemd/system
+/run/systemd/system\&.attached
+/run/systemd/generator
+/run/systemd/generator\&.late
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note that this verb prints the list that is compiled into
+\fBsystemd\-analyze\fR
+itself, and does not communicate with the running manager\&. Use
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemctl [\-\-user] [\-\-global] show \-p UnitPath \-\-value
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+to retrieve the actual list that the manager uses, with any empty directories omitted\&.
+.SS "systemd\-analyze exit\-status [\fISTATUS\fR\&.\&.\&.]"
+.PP
+This command prints a list of exit statuses along with their "class", i\&.e\&. the source of the definition (one of
+"glibc",
+"systemd",
+"LSB", or
+"BSD"), see the Process Exit Codes section in
+\fBsystemd.exec\fR(5)\&. If no additional arguments are specified, all known statuses are shown\&. Otherwise, only the definitions for the specified codes are shown\&.
+.PP
+\fBExample\ \&9.\ \&Show some example exit status names\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze exit\-status 0 1 {63\&.\&.65}
+NAME    STATUS CLASS
+SUCCESS 0      glibc
+FAILURE 1      glibc
+\-       63     \-
+USAGE   64     BSD
+DATAERR 65     BSD
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze capability [\fICAPABILITY\fR\&.\&.\&.]"
+.PP
+This command prints a list of Linux capabilities along with their numeric IDs\&. See
+\fBcapabilities\fR(7)
+for details\&. If no argument is specified the full list of capabilities known to the service manager and the kernel is shown\&. Capabilities defined by the kernel but not known to the service manager are shown as
+"cap_???"\&. Optionally, if arguments are specified they may refer to specific cabilities by name or numeric ID, in which case only the indicated capabilities are shown in the table\&.
+.PP
+\fBExample\ \&10.\ \&Show some example capability names\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze capability 0 1 {30\&.\&.32}
+NAME              NUMBER
+cap_chown              0
+cap_dac_override       1
+cap_audit_control     30
+cap_setfcap           31
+cap_mac_override      32
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze condition \fICONDITION\fR\&.\&.\&."
+.PP
+This command will evaluate
+\fICondition*=\&.\&.\&.\fR
+and
+\fIAssert*=\&.\&.\&.\fR
+assignments, and print their values, and the resulting value of the combined condition set\&. See
+\fBsystemd.unit\fR(5)
+for a list of available conditions and asserts\&.
+.PP
+\fBExample\ \&11.\ \&Evaluate conditions that check kernel versions\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze condition \*(AqConditionKernelVersion = ! <4\&.0\*(Aq \e
+        \*(AqConditionKernelVersion = >=5\&.1\*(Aq \e
+        \*(AqConditionACPower=|false\*(Aq \e
+        \*(AqConditionArchitecture=|!arm\*(Aq \e
+        \*(AqAssertPathExists=/etc/os\-release\*(Aq
+test\&.service: AssertPathExists=/etc/os\-release succeeded\&.
+Asserts succeeded\&.
+test\&.service: ConditionArchitecture=|!arm succeeded\&.
+test\&.service: ConditionACPower=|false failed\&.
+test\&.service: ConditionKernelVersion=>=5\&.1 succeeded\&.
+test\&.service: ConditionKernelVersion=!<4\&.0 succeeded\&.
+Conditions succeeded\&.
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze syscall\-filter [\fISET\fR\&.\&.\&.]"
+.PP
+This command will list system calls contained in the specified system call set
+\fISET\fR, or all known sets if no sets are specified\&. Argument
+\fISET\fR
+must include the
+"@"
+prefix\&.
+.SS "systemd\-analyze filesystems [\fISET\fR\&.\&.\&.]"
+.PP
+This command will list filesystems in the specified filesystem set
+\fISET\fR, or all known sets if no sets are specified\&. Argument
+\fISET\fR
+must include the
+"@"
+prefix\&.
+.SS "systemd\-analyze calendar \fIEXPRESSION\fR\&.\&.\&."
+.PP
+This command will parse and normalize repetitive calendar time events, and will calculate when they elapse next\&. This takes the same input as the
+\fIOnCalendar=\fR
+setting in
+\fBsystemd.timer\fR(5), following the syntax described in
+\fBsystemd.time\fR(7)\&. By default, only the next time the calendar expression will elapse is shown; use
+\fB\-\-iterations=\fR
+to show the specified number of next times the expression elapses\&. Each time the expression elapses forms a timestamp, see the
+\fBtimestamp\fR
+verb below\&.
+.PP
+\fBExample\ \&12.\ \&Show leap days in the near future\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze calendar \-\-iterations=5 \*(Aq*\-2\-29 0:0:0\*(Aq
+  Original form: *\-2\-29 0:0:0
+Normalized form: *\-02\-29 00:00:00
+    Next elapse: Sat 2020\-02\-29 00:00:00 UTC
+       From now: 11 months 15 days left
+       Iter\&. #2: Thu 2024\-02\-29 00:00:00 UTC
+       From now: 4 years 11 months left
+       Iter\&. #3: Tue 2028\-02\-29 00:00:00 UTC
+       From now: 8 years 11 months left
+       Iter\&. #4: Sun 2032\-02\-29 00:00:00 UTC
+       From now: 12 years 11 months left
+       Iter\&. #5: Fri 2036\-02\-29 00:00:00 UTC
+       From now: 16 years 11 months left
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze timestamp \fITIMESTAMP\fR\&.\&.\&."
+.PP
+This command parses a timestamp (i\&.e\&. a single point in time) and outputs the normalized form and the difference between this timestamp and now\&. The timestamp should adhere to the syntax documented in
+\fBsystemd.time\fR(7), section "PARSING TIMESTAMPS"\&.
+.PP
+\fBExample\ \&13.\ \&Show parsing of timestamps\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze timestamp yesterday now tomorrow
+  Original form: yesterday
+Normalized form: Mon 2019\-05\-20 00:00:00 CEST
+       (in UTC): Sun 2019\-05\-19 22:00:00 UTC
+   UNIX seconds: @15583032000
+       From now: 1 day 9h ago
+
+  Original form: now
+Normalized form: Tue 2019\-05\-21 09:48:39 CEST
+       (in UTC): Tue 2019\-05\-21 07:48:39 UTC
+   UNIX seconds: @1558424919\&.659757
+       From now: 43us ago
+
+  Original form: tomorrow
+Normalized form: Wed 2019\-05\-22 00:00:00 CEST
+       (in UTC): Tue 2019\-05\-21 22:00:00 UTC
+   UNIX seconds: @15584760000
+       From now: 14h left
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze timespan \fIEXPRESSION\fR\&.\&.\&."
+.PP
+This command parses a time span (i\&.e\&. a difference between two timestamps) and outputs the normalized form and the equivalent value in microseconds\&. The time span should adhere to the syntax documented in
+\fBsystemd.time\fR(7), section "PARSING TIME SPANS"\&. Values without units are parsed as seconds\&.
+.PP
+\fBExample\ \&14.\ \&Show parsing of timespans\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze timespan 1s 300s \*(Aq1year 0\&.000001s\*(Aq
+Original: 1s
+      μs: 1000000
+   Human: 1s
+
+Original: 300s
+      μs: 300000000
+   Human: 5min
+
+Original: 1year 0\&.000001s
+      μs: 31557600000001
+   Human: 1y 1us
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze cat\-config \fINAME\fR|\fIPATH\fR\&.\&.\&."
+.PP
+This command is similar to
+\fBsystemctl cat\fR, but operates on config files\&. It will copy the contents of a config file and any drop\-ins to standard output, using the usual systemd set of directories and rules for precedence\&. Each argument must be either an absolute path including the prefix (such as
+/etc/systemd/logind\&.conf
+or
+/usr/lib/systemd/logind\&.conf), or a name relative to the prefix (such as
+systemd/logind\&.conf)\&.
+.PP
+\fBExample\ \&15.\ \&Showing logind configuration\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze cat\-config systemd/logind\&.conf
+# /etc/systemd/logind\&.conf
+\&.\&.\&.
+[Login]
+NAutoVTs=8
+\&.\&.\&.
+
+# /usr/lib/systemd/logind\&.conf\&.d/20\-test\&.conf
+\&.\&.\&. some override from another package
+
+# /etc/systemd/logind\&.conf\&.d/50\-override\&.conf
+\&.\&.\&. some administrator override
+        
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze compare\-versions \fIVERSION1\fR [\fIOP\fR] \fIVERSION2\fR"
+.PP
+This command has two distinct modes of operation, depending on whether the operator
+\fIOP\fR
+is specified\&.
+.PP
+In the first mode \(em when
+\fIOP\fR
+is not specified \(em it will compare the two version strings and print either
+"\fIVERSION1\fR < \fIVERSION2\fR", or
+"\fIVERSION1\fR == \fIVERSION2\fR", or
+"\fIVERSION1\fR > \fIVERSION2\fR"
+as appropriate\&.
+.PP
+The exit status is
+\fB0\fR
+if the versions are equal,
+\fB11\fR
+if the version of the right is smaller, and
+\fB12\fR
+if the version of the left is smaller\&. (This matches the convention used by
+\fBrpmdev\-vercmp\fR\&.)
+.PP
+In the second mode \(em when
+\fIOP\fR
+is specified \(em it will compare the two version strings using the operation
+\fIOP\fR
+and return
+\fB0\fR
+(success) if they condition is satisfied, and
+\fB1\fR
+(failure) otherwise\&.
+\fBOP\fR
+may be
+\fBlt\fR,
+\fBle\fR,
+\fBeq\fR,
+\fBne\fR,
+\fBge\fR,
+\fBgt\fR\&. In this mode, no output is printed\&. (This matches the convention used by
+\fBdpkg\fR(1)
+\fB\-\-compare\-versions\fR\&.)
+.PP
+\fBExample\ \&16.\ \&Compare versions of a package\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze compare\-versions systemd\-250~rc1\&.fc36\&.aarch64 systemd\-251\&.fc36\&.aarch64
+systemd\-250~rc1\&.fc36\&.aarch64 < systemd\-251\&.fc36\&.aarch64
+$ echo $?
+12
+
+$ systemd\-analyze compare\-versions 1 lt 2; echo $?
+0
+$ systemd\-analyze compare\-versions 1 ge 2; echo $?
+1
+        
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze verify \fIFILE\fR\&.\&.\&."
+.PP
+This command will load unit files and print warnings if any errors are detected\&. Files specified on the command line will be loaded, but also any other units referenced by them\&. A unit\*(Aqs name on disk can be overridden by specifying an alias after a colon; see below for an example\&. The full unit search path is formed by combining the directories for all command line arguments, and the usual unit load paths\&. The variable
+\fI$SYSTEMD_UNIT_PATH\fR
+is supported, and may be used to replace or augment the compiled in set of unit load paths; see
+\fBsystemd.unit\fR(5)\&. All units files present in the directories containing the command line arguments will be used in preference to the other paths\&.
+.PP
+The following errors are currently detected:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+unknown sections and directives,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+missing dependencies which are required to start the given unit,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+man pages listed in
+\fIDocumentation=\fR
+which are not found in the system,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+commands listed in
+\fIExecStart=\fR
+and similar which are not found in the system or not executable\&.
+.RE
+.PP
+\fBExample\ \&17.\ \&Misspelt directives\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ cat \&./user\&.slice
+[Unit]
+WhatIsThis=11
+Documentation=man:nosuchfile(1)
+Requires=different\&.service
+
+[Service]
+Description=x
+
+$ systemd\-analyze verify \&./user\&.slice
+[\&./user\&.slice:9] Unknown lvalue \*(AqWhatIsThis\*(Aq in section \*(AqUnit\*(Aq
+[\&./user\&.slice:13] Unknown section \*(AqService\*(Aq\&. Ignoring\&.
+Error: org\&.freedesktop\&.systemd1\&.LoadFailed:
+   Unit different\&.service failed to load:
+   No such file or directory\&.
+Failed to create user\&.slice/start: Invalid argument
+user\&.slice: man nosuchfile(1) command failed with code 16
+        
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&18.\ \&Missing service units\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ tail \&./a\&.socket \&./b\&.socket
+==> \&./a\&.socket <==
+[Socket]
+ListenStream=100
+
+==> \&./b\&.socket <==
+[Socket]
+ListenStream=100
+Accept=yes
+
+$ systemd\-analyze verify \&./a\&.socket \&./b\&.socket
+Service a\&.service not loaded, a\&.socket cannot be started\&.
+Service b@0\&.service not loaded, b\&.socket cannot be started\&.
+        
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&19.\ \&Aliasing a unit\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ cat /tmp/source
+[Unit]
+Description=Hostname printer
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/echo %H
+MysteryKey=true
+
+$ systemd\-analyze verify /tmp/source
+Failed to prepare filename /tmp/source: Invalid argument
+
+$ systemd\-analyze verify /tmp/source:alias\&.service
+alias\&.service:7: Unknown key name \*(AqMysteryKey\*(Aq in section \*(AqService\*(Aq, ignoring\&.
+        
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze security [\fIUNIT\fR\&.\&.\&.]"
+.PP
+This command analyzes the security and sandboxing settings of one or more specified service units\&. If at least one unit name is specified the security settings of the specified service units are inspected and a detailed analysis is shown\&. If no unit name is specified, all currently loaded, long\-running service units are inspected and a terse table with results shown\&. The command checks for various security\-related service settings, assigning each a numeric "exposure level" value, depending on how important a setting is\&. It then calculates an overall exposure level for the whole unit, which is an estimation in the range 0\&.0\&...10\&.0 indicating how exposed a service is security\-wise\&. High exposure levels indicate very little applied sandboxing\&. Low exposure levels indicate tight sandboxing and strongest security restrictions\&. Note that this only analyzes the per\-service security features systemd itself implements\&. This means that any additional security mechanisms applied by the service code itself are not accounted for\&. The exposure level determined this way should not be misunderstood: a high exposure level neither means that there is no effective sandboxing applied by the service code itself, nor that the service is actually vulnerable to remote or local attacks\&. High exposure levels do indicate however that most likely the service might benefit from additional settings applied to them\&.
+.PP
+Please note that many of the security and sandboxing settings individually can be circumvented \(em unless combined with others\&. For example, if a service retains the privilege to establish or undo mount points many of the sandboxing options can be undone by the service code itself\&. Due to that is essential that each service uses the most comprehensive and strict sandboxing and security settings possible\&. The tool will take into account some of these combinations and relationships between the settings, but not all\&. Also note that the security and sandboxing settings analyzed here only apply to the operations executed by the service code itself\&. If a service has access to an IPC system (such as D\-Bus) it might request operations from other services that are not subject to the same restrictions\&. Any comprehensive security and sandboxing analysis is hence incomplete if the IPC access policy is not validated too\&.
+.PP
+\fBExample\ \&20.\ \&Analyze systemd\-logind\&.service\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze security \-\-no\-pager systemd\-logind\&.service
+  NAME                DESCRIPTION                              EXPOSURE
+✗ PrivateNetwork=     Service has access to the host\*(Aqs network      0\&.5
+✗ User=/DynamicUser=  Service runs as root user                     0\&.4
+✗ DeviceAllow=        Service has no device ACL                     0\&.2
+✓ IPAddressDeny=      Service blocks all IP address ranges
+\&.\&.\&.
+→ Overall exposure level for systemd\-logind\&.service: 4\&.1 OK 🙂
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze inspect\-elf \fIFILE\fR\&.\&.\&."
+.PP
+This command will load the specified files, and if they are ELF objects (executables, libraries, core files, etc\&.) it will parse the embedded packaging metadata, if any, and print it in a table or json format\&. See the
+\m[blue]\fBPackaging Metadata\fR\m[]\&\s-2\u[1]\d\s+2
+documentation for more information\&.
+.PP
+\fBExample\ \&21.\ \&Print information about a core file as JSON\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze inspect\-elf \-\-json=pretty \e
+        core\&.fsverity\&.1000\&.f77dac5dc161402aa44e15b7dd9dcf97\&.58561\&.1637106137000000
+{
+        "elfType" : "coredump",
+        "elfArchitecture" : "AMD x86\-64",
+        "/home/bluca/git/fsverity\-utils/fsverity" : {
+                "type" : "deb",
+                "name" : "fsverity\-utils",
+                "version" : "1\&.3\-1",
+                "buildId" : "7c895ecd2a271f93e96268f479fdc3c64a2ec4ee"
+        },
+        "/home/bluca/git/fsverity\-utils/libfsverity\&.so\&.0" : {
+                "type" : "deb",
+                "name" : "fsverity\-utils",
+                "version" : "1\&.3\-1",
+                "buildId" : "b5e428254abf14237b0ae70ed85fffbb98a78f88"
+        }
+}
+        
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze fdstore \fIUNIT\fR\&.\&.\&."
+.PP
+Lists the current contents of the specified service unit\*(Aqs file descriptor store\&. This shows names, inode types, device numbers, inode numbers, paths and open modes of the open file descriptors\&. The specified units must have
+\fIFileDescriptorStoreMax=\fR
+enabled, see
+\fBsystemd.service\fR(5)
+for details\&.
+.PP
+\fBExample\ \&22.\ \&Table output\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze fdstore systemd\-journald\&.service
+FDNAME TYPE DEVNO   INODE RDEVNO PATH             FLAGS
+stored sock 0:8   4218620 \-      socket:[4218620] ro
+stored sock 0:8   4213198 \-      socket:[4213198] ro
+stored sock 0:8   4213190 \-      socket:[4213190] ro
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note: the "DEVNO" column refers to the major/minor numbers of the device node backing the file system the file descriptor\*(Aqs inode is on\&. The "RDEVNO" column refers to the major/minor numbers of the device node itself if the file descriptor refers to one\&. Compare with corresponding
+\fI\&.st_dev\fR
+and
+\fI\&.st_rdev\fR
+fields in
+\fBstruct stat\fR
+(see
+\fBstat\fR(2)
+for details)\&. The listed inode numbers in the "INODE" column are on the file system indicated by "DEVNO"\&.
+.SS "systemd\-analyze image\-policy \fIPOLICY\fR\&..."
+.PP
+This command analyzes the specified image policy string, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is normalized and simplified\&. For each currently defined partition identifier (as per the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[2]\d\s+2) the effect of the image policy string is shown in tabular form\&.
+.PP
+\fBExample\ \&23.\ \&Example Output\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze image\-policy swap=encrypted:usr=read\-only\-on+verity:root=encrypted
+Analyzing policy: root=encrypted:usr=verity+read\-only\-on:swap=encrypted
+       Long form: root=encrypted:usr=verity+read\-only\-on:swap=encrypted:=unused+absent
+
+PARTITION       MODE        READ\-ONLY GROWFS
+root            encrypted   \-         \-
+usr             verity      yes       \-
+home            ignore      \-         \-
+srv             ignore      \-         \-
+esp             ignore      \-         \-
+xbootldr        ignore      \-         \-
+swap            encrypted   \-         \-
+root\-verity     ignore      \-         \-
+usr\-verity      unprotected yes       \-
+root\-verity\-sig ignore      \-         \-
+usr\-verity\-sig  ignore      \-         \-
+tmp             ignore      \-         \-
+var             ignore      \-         \-
+default         ignore      \-         \-
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze pcrs [\fIPCR\fR\&...]"
+.PP
+This command shows the known TPM2 PCRs along with their identifying names and current values\&.
+.PP
+\fBExample\ \&24.\ \&Example Output\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-analyze pcrs
+NR NAME                SHA256
+ 0 platform\-code       bcd2eb527108bbb1f5528409bcbe310aa9b74f687854cc5857605993f3d9eb11
+ 1 platform\-config     b60622856eb7ce52637b80f30a520e6e87c347daa679f3335f4f1a600681bb01
+ 2 external\-code       1471262403e9a62f9c392941300b4807fbdb6f0bfdd50abfab752732087017dd
+ 3 external\-config     3d458cfe55cc03ea1f443f1562beec8df51c75e14a9fcf9a7234a13f198e7969
+ 4 boot\-loader\-code    939f7fa1458e1f7ce968874d908e524fc0debf890383d355e4ce347b7b78a95c
+ 5 boot\-loader\-config  864c61c5ea5ecbdb6951e6cb6d9c1f4b4eac79772f7fe13b8bece569d83d3768
+ 6 \-                   3d458cfe55cc03ea1f443f1562beec8df51c75e14a9fcf9a7234a13f198e7969
+ 7 secure\-boot\-policy  9c905bd9b9891bfb889b90a54c4b537b889cfa817c4389cc25754823a9443255
+ 8 \-                   0000000000000000000000000000000000000000000000000000000000000000
+ 9 kernel\-initrd       9caa29b128113ef42aa53d421f03437be57211e5ebafc0fa8b5d4514ee37ff0c
+10 ima                 5ea9e3dab53eb6b483b6ec9e3b2c712bea66bca1b155637841216e0094387400
+11 kernel\-boot         0000000000000000000000000000000000000000000000000000000000000000
+12 kernel\-config       627ffa4b405e911902fe1f1a8b0164693b31acab04f805f15bccfe2209c7eace
+13 sysexts             0000000000000000000000000000000000000000000000000000000000000000
+14 shim\-policy         0000000000000000000000000000000000000000000000000000000000000000
+15 system\-identity     0000000000000000000000000000000000000000000000000000000000000000
+16 debug               0000000000000000000000000000000000000000000000000000000000000000
+17 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+18 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+19 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+20 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+21 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+22 \-                   ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+23 application\-support 0000000000000000000000000000000000000000000000000000000000000000
+.fi
+.if n \{\
+.RE
+.\}
+.SS "systemd\-analyze srk > \fIFILE\fR"
+.PP
+This command reads the Storage Root Key (SRK) from the TPM2 device, and writes it in marshalled TPM2B_PUBLIC format to stdout\&. Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-analyze srk > srk\&.tpm2b_public
+.fi
+.if n \{\
+.RE
+.\}
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-system\fR
+.RS 4
+Operates on the system systemd instance\&. This is the implied default\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-user\fR
+.RS 4
+Operates on the user systemd instance\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-global\fR
+.RS 4
+Operates on the system\-wide configuration for user systemd instance\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fB\-\-order\fR, \fB\-\-require\fR
+.RS 4
+When used in conjunction with the
+\fBdot\fR
+command (see above), selects which dependencies are shown in the dependency graph\&. If
+\fB\-\-order\fR
+is passed, only dependencies of type
+\fIAfter=\fR
+or
+\fIBefore=\fR
+are shown\&. If
+\fB\-\-require\fR
+is passed, only dependencies of type
+\fIRequires=\fR,
+\fIRequisite=\fR,
+\fIWants=\fR
+and
+\fIConflicts=\fR
+are shown\&. If neither is passed, this shows dependencies of all these types\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-\-from\-pattern=\fR, \fB\-\-to\-pattern=\fR
+.RS 4
+When used in conjunction with the
+\fBdot\fR
+command (see above), this selects which relationships are shown in the dependency graph\&. Both options require a
+\fBglob\fR(7)
+pattern as an argument, which will be matched against the left\-hand and the right\-hand, respectively, nodes of a relationship\&.
+.sp
+Each of these can be used more than once, in which case the unit name must match one of the values\&. When tests for both sides of the relation are present, a relation must pass both tests to be shown\&. When patterns are also specified as positional arguments, they must match at least one side of the relation\&. In other words, patterns specified with those two options will trim the list of edges matched by the positional arguments, if any are given, and fully determine the list of edges shown otherwise\&.
+.sp
+Added in version 201\&.
+.RE
+.PP
+\fB\-\-fuzz=\fR\fItimespan\fR
+.RS 4
+When used in conjunction with the
+\fBcritical\-chain\fR
+command (see above), also show units, which finished
+\fItimespan\fR
+earlier, than the latest unit in the same level\&. The unit of
+\fItimespan\fR
+is seconds unless specified with a different unit, e\&.g\&. "50ms"\&.
+.sp
+Added in version 203\&.
+.RE
+.PP
+\fB\-\-man=no\fR
+.RS 4
+Do not invoke
+\fBman\fR(1)
+to verify the existence of man pages listed in
+\fIDocumentation=\fR\&.
+.sp
+Added in version 235\&.
+.RE
+.PP
+\fB\-\-generators\fR
+.RS 4
+Invoke unit generators, see
+\fBsystemd.generator\fR(7)\&. Some generators require root privileges\&. Under a normal user, running with generators enabled will generally result in some warnings\&.
+.sp
+Added in version 235\&.
+.RE
+.PP
+\fB\-\-recursive\-errors=\fR\fB\fIMODE\fR\fR
+.RS 4
+Control verification of units and their dependencies and whether
+\fBsystemd\-analyze verify\fR
+exits with a non\-zero process exit status or not\&. With
+\fByes\fR, return a non\-zero process exit status when warnings arise during verification of either the specified unit or any of its associated dependencies\&. With
+\fBno\fR, return a non\-zero process exit status when warnings arise during verification of only the specified unit\&. With
+\fBone\fR, return a non\-zero process exit status when warnings arise during verification of either the specified unit or its immediate dependencies\&. If this option is not specified, zero is returned as the exit status regardless whether warnings arise during verification or not\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-root=\fR\fB\fIPATH\fR\fR
+.RS 4
+With
+\fBcat\-files\fR
+and
+\fBverify\fR, operate on files underneath the specified root path
+\fIPATH\fR\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIPATH\fR\fR
+.RS 4
+With
+\fBcat\-files\fR
+and
+\fBverify\fR, operate on files inside the specified image path
+\fIPATH\fR\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-offline=\fR\fB\fIBOOL\fR\fR
+.RS 4
+With
+\fBsecurity\fR, perform an offline security review of the specified unit files, i\&.e\&. does not have to rely on PID 1 to acquire security information for the files like the
+\fBsecurity\fR
+verb when used by itself does\&. This means that
+\fB\-\-offline=\fR
+can be used with
+\fB\-\-root=\fR
+and
+\fB\-\-image=\fR
+as well\&. If a unit\*(Aqs overall exposure level is above that set by
+\fB\-\-threshold=\fR
+(default value is 100),
+\fB\-\-offline=\fR
+will return an error\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-profile=\fR\fB\fIPATH\fR\fR
+.RS 4
+With
+\fBsecurity\fR
+\fB\-\-offline=\fR, takes into consideration the specified portable profile when assessing unit settings\&. The profile can be passed by name, in which case the well\-known system locations will be searched, or it can be the full path to a specific drop\-in file\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-threshold=\fR\fB\fINUMBER\fR\fR
+.RS 4
+With
+\fBsecurity\fR, allow the user to set a custom value to compare the overall exposure level with, for the specified unit files\&. If a unit\*(Aqs overall exposure level, is greater than that set by the user,
+\fBsecurity\fR
+will return an error\&.
+\fB\-\-threshold=\fR
+can be used with
+\fB\-\-offline=\fR
+as well and its default value is 100\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-security\-policy=\fR\fB\fIPATH\fR\fR
+.RS 4
+With
+\fBsecurity\fR, allow the user to define a custom set of requirements formatted as a JSON file against which to compare the specified unit file(s) and determine their overall exposure level to security threats\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \&Accepted Assessment Test Identifiers
+.TS
+allbox tab(:);
+lB.
+T{
+Assessment Test Identifier
+T}
+.T&
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l
+l.
+T{
+UserOrDynamicUser
+T}
+T{
+SupplementaryGroups
+T}
+T{
+PrivateMounts
+T}
+T{
+PrivateDevices
+T}
+T{
+PrivateTmp
+T}
+T{
+PrivateNetwork
+T}
+T{
+PrivateUsers
+T}
+T{
+ProtectControlGroups
+T}
+T{
+ProtectKernelModules
+T}
+T{
+ProtectKernelTunables
+T}
+T{
+ProtectKernelLogs
+T}
+T{
+ProtectClock
+T}
+T{
+ProtectHome
+T}
+T{
+ProtectHostname
+T}
+T{
+ProtectSystem
+T}
+T{
+RootDirectoryOrRootImage
+T}
+T{
+LockPersonality
+T}
+T{
+MemoryDenyWriteExecute
+T}
+T{
+NoNewPrivileges
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_ADMIN
+T}
+T{
+CapabilityBoundingSet_CAP_SET_UID_GID_PCAP
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_PTRACE
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_TIME
+T}
+T{
+CapabilityBoundingSet_CAP_NET_ADMIN
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_RAWIO
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_MODULE
+T}
+T{
+CapabilityBoundingSet_CAP_AUDIT
+T}
+T{
+CapabilityBoundingSet_CAP_SYSLOG
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_NICE_RESOURCE
+T}
+T{
+CapabilityBoundingSet_CAP_MKNOD
+T}
+T{
+CapabilityBoundingSet_CAP_CHOWN_FSETID_SETFCAP
+T}
+T{
+CapabilityBoundingSet_CAP_DAC_FOWNER_IPC_OWNER
+T}
+T{
+CapabilityBoundingSet_CAP_KILL
+T}
+T{
+CapabilityBoundingSet_CAP_NET_BIND_SERVICE_BROADCAST_RAW
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_BOOT
+T}
+T{
+CapabilityBoundingSet_CAP_MAC
+T}
+T{
+CapabilityBoundingSet_CAP_LINUX_IMMUTABLE
+T}
+T{
+CapabilityBoundingSet_CAP_IPC_LOCK
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_CHROOT
+T}
+T{
+CapabilityBoundingSet_CAP_BLOCK_SUSPEND
+T}
+T{
+CapabilityBoundingSet_CAP_WAKE_ALARM
+T}
+T{
+CapabilityBoundingSet_CAP_LEASE
+T}
+T{
+CapabilityBoundingSet_CAP_SYS_TTY_CONFIG
+T}
+T{
+CapabilityBoundingSet_CAP_BPF
+T}
+T{
+UMask
+T}
+T{
+KeyringMode
+T}
+T{
+ProtectProc
+T}
+T{
+ProcSubset
+T}
+T{
+NotifyAccess
+T}
+T{
+RemoveIPC
+T}
+T{
+Delegate
+T}
+T{
+RestrictRealtime
+T}
+T{
+RestrictSUIDSGID
+T}
+T{
+RestrictNamespaces_user
+T}
+T{
+RestrictNamespaces_mnt
+T}
+T{
+RestrictNamespaces_ipc
+T}
+T{
+RestrictNamespaces_pid
+T}
+T{
+RestrictNamespaces_cgroup
+T}
+T{
+RestrictNamespaces_uts
+T}
+T{
+RestrictNamespaces_net
+T}
+T{
+RestrictAddressFamilies_AF_INET_INET6
+T}
+T{
+RestrictAddressFamilies_AF_UNIX
+T}
+T{
+RestrictAddressFamilies_AF_NETLINK
+T}
+T{
+RestrictAddressFamilies_AF_PACKET
+T}
+T{
+RestrictAddressFamilies_OTHER
+T}
+T{
+SystemCallArchitectures
+T}
+T{
+SystemCallFilter_swap
+T}
+T{
+SystemCallFilter_obsolete
+T}
+T{
+SystemCallFilter_clock
+T}
+T{
+SystemCallFilter_cpu_emulation
+T}
+T{
+SystemCallFilter_debug
+T}
+T{
+SystemCallFilter_mount
+T}
+T{
+SystemCallFilter_module
+T}
+T{
+SystemCallFilter_raw_io
+T}
+T{
+SystemCallFilter_reboot
+T}
+T{
+SystemCallFilter_privileged
+T}
+T{
+SystemCallFilter_resources
+T}
+T{
+IPAddressDeny
+T}
+T{
+DeviceAllow
+T}
+T{
+AmbientCapabilities
+T}
+.TE
+.sp 1
+See example "JSON Policy" below\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-json=\fR\fB\fIMODE\fR\fR
+.RS 4
+With the
+\fBsecurity\fR
+command, generate a JSON formatted output of the security analysis table\&. The format is a JSON array with objects containing the following fields:
+\fIset\fR
+which indicates if the setting has been enabled or not,
+\fIname\fR
+which is what is used to refer to the setting,
+\fIjson_field\fR
+which is the JSON compatible identifier of the setting,
+\fIdescription\fR
+which is an outline of the setting state, and
+\fIexposure\fR
+which is a number in the range 0\&.0\&...10\&.0, where a higher value corresponds to a higher security threat\&. The JSON version of the table is printed to standard output\&. The
+\fIMODE\fR
+passed to the option can be one of three:
+\fBoff\fR
+which is the default,
+\fBpretty\fR
+and
+\fBshort\fR
+which respectively output a prettified or shorted JSON version of the security table\&. With the
+\fBplot\fR
+command, generate a JSON formatted output of the raw time data\&. The format is a JSON array with objects containing the following fields:
+\fIname\fR
+which is the unit name,
+\fIactivated\fR
+which is the time after startup the service was activated,
+\fIactivating\fR
+which is how long after startup the service was initially started,
+\fItime\fR
+which is how long the service took to activate from when it was initially started,
+\fIdeactivated\fR
+which is the time after startup that the service was deactivated,
+\fIdeactivating\fR
+which is the time after startup that the service was initially told to deactivate\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-iterations=\fR\fB\fINUMBER\fR\fR
+.RS 4
+When used with the
+\fBcalendar\fR
+command, show the specified number of iterations the specified calendar expression will elapse next\&. Defaults to 1\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-base\-time=\fR\fB\fITIMESTAMP\fR\fR
+.RS 4
+When used with the
+\fBcalendar\fR
+command, show next iterations relative to the specified point in time\&. If not specified defaults to the current time\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-\-unit=\fR\fB\fIUNIT\fR\fR
+.RS 4
+When used with the
+\fBcondition\fR
+command, evaluate all the
+\fICondition*=\&.\&.\&.\fR
+and
+\fIAssert*=\&.\&.\&.\fR
+assignments in the specified unit file\&. The full unit search path is formed by combining the directories for the specified unit with the usual unit load paths\&. The variable
+\fI$SYSTEMD_UNIT_PATH\fR
+is supported, and may be used to replace or augment the compiled in set of unit load paths; see
+\fBsystemd.unit\fR(5)\&. All units files present in the directory containing the specified unit will be used in preference to the other paths\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-table\fR
+.RS 4
+When used with the
+\fBplot\fR
+command, the raw time data is output in a table\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+When used with the
+\fBplot\fR
+command in combination with either
+\fB\-\-table\fR
+or
+\fB\-\-json=\fR, no legends or hints are included in the output\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppress hints and other non\-essential output\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-tldr\fR
+.RS 4
+With
+\fBcat\-config\fR, only print the "interesting" parts of the configuration files, skipping comments and empty lines and section headers followed only by comments and empty lines\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+For most commands, 0 is returned on success, and a non\-zero failure code otherwise\&.
+.PP
+With the verb
+\fBcompare\-versions\fR, in the two\-argument form,
+\fB12\fR,
+\fB0\fR,
+\fB11\fR
+is returned if the second version string is respectively larger, equal, or smaller to the first\&. In the three\-argument form,
+\fB0\fR
+or
+\fB1\fR
+if the condition is respectively true or false\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&25.\ \&JSON Policy\fR
+.PP
+The JSON file passed as a path parameter to
+\fB\-\-security\-policy=\fR
+has a top\-level JSON object, with keys being the assessment test identifiers mentioned above\&. The values in the file should be JSON objects with one or more of the following fields:
+\fBdescription_na\fR
+(string),
+\fBdescription_good\fR
+(string),
+\fBdescription_bad\fR
+(string),
+\fBweight\fR
+(unsigned integer), and
+\fBrange\fR
+(unsigned integer)\&. If any of these fields corresponding to a specific id of the unit file is missing from the JSON object, the default built\-in field value corresponding to that same id is used for security analysis as default\&. The weight and range fields are used in determining the overall exposure level of the unit files: the value of each setting is assigned a badness score, which is multiplied by the policy weight and divided by the policy range to determine the overall exposure that the setting implies\&. The computed badness is summed across all settings in the unit file, normalized to the 1\&...100 range, and used to determine the overall exposure level of the unit\&. By allowing users to manipulate these fields, the \*(Aqsecurity\*(Aq verb gives them the option to decide for themself which ids are more important and hence should have a greater effect on the exposure level\&. A weight of
+"0"
+means the setting will not be checked\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+{
+  "PrivateDevices":
+    {
+    "description_good": "Service has no access to hardware devices",
+    "description_bad": "Service potentially has access to hardware devices",
+    "weight": 1000,
+    "range": 1
+    },
+  "PrivateMounts":
+    {
+    "description_good": "Service cannot install system mounts",
+    "description_bad": "Service may install system mounts",
+    "weight": 1000,
+    "range": 1
+    },
+  "PrivateNetwork":
+    {
+    "description_good": "Service has no access to the host\*(Aqs network",
+    "description_bad": "Service has access to the host\*(Aqs network",
+    "weight": 2500,
+    "range": 1
+    },
+  "PrivateTmp":
+    {
+    "description_good": "Service has no access to other software\*(Aqs temporary files",
+    "description_bad": "Service has access to other software\*(Aqs temporary files",
+    "weight": 1000,
+    "range": 1
+    },
+  "PrivateUsers":
+    {
+    "description_good": "Service does not have access to other users",
+    "description_bad": "Service has access to other users",
+    "weight": 1000,
+    "range": 1
+    }
+}
+      
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Packaging Metadata
+.RS 4
+\%https://systemd.io/COREDUMP_PACKAGE_METADATA/
+.RE
+.IP " 2." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-ask-password.1 b/upstream/mageia-cauldron/man1/systemd-ask-password.1
new file mode 100644
index 00000000..8583162a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-ask-password.1
@@ -0,0 +1,251 @@
+'\" t
+.TH "SYSTEMD\-ASK\-PASSWORD" "1" "" "systemd 255" "systemd-ask-password"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-ask-password \- Query the user for a system password
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-ask\-password\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[MESSAGE]\fR\ 'u
+\fBsystemd\-ask\-password \fR\fB[OPTIONS...]\fR\fB \fR\fB[MESSAGE]\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-ask\-password\fR
+may be used to query a system password or passphrase from the user, using a question message specified on the command line\&. When run from a TTY it will query a password on the TTY and print it to standard output\&. When run with no TTY or with
+\fB\-\-no\-tty\fR
+it will use the system\-wide query mechanism, which allows active users to respond via several agents, listed below\&.
+.PP
+The purpose of this tool is to query system\-wide passwords \(em that is passwords not attached to a specific user account\&. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers\&.
+.PP
+Existing agents are:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A boot\-time password agent asking the user for passwords using
+\fBplymouth\fR(8),
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A boot\-time password agent querying the user directly on the console \(em
+\fBsystemd-ask-password-console.service\fR(8),
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+An agent requesting password input via a
+\fBwall\fR(1)
+message \(em
+\fBsystemd-ask-password-wall.service\fR(8),
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A TTY agent that is temporarily spawned during
+\fBsystemctl\fR(1)
+invocations,
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A command line agent which can be started temporarily to process queued password requests \(em
+\fBsystemd\-tty\-ask\-password\-agent \-\-query\fR\&.
+.RE
+.PP
+Answering system\-wide password queries is a privileged operation, hence all the agents listed above (except for the last one), run as privileged system services\&. The last one also needs elevated privileges, so should be run through
+\fBsudo\fR(8)
+or similar\&.
+.PP
+Additional password agents may be implemented according to the
+\m[blue]\fBsystemd Password Agent Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.PP
+If a password is queried on a TTY, the user may press TAB to hide the asterisks normally shown for each character typed\&. Pressing Backspace as first key achieves the same effect\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-icon=\fR
+.RS 4
+Specify an icon name alongside the password query, which may be used in all agents supporting graphical display\&. The icon name should follow the
+\m[blue]\fBXDG Icon Naming Specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.RE
+.PP
+\fB\-\-id=\fR
+.RS 4
+Specify an identifier for this password query\&. This identifier is freely choosable and allows recognition of queries by involved agents\&. It should include the subsystem doing the query and the specific object the query is done for\&. Example:
+"\-\-id=cryptsetup:/dev/sda5"\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-keyname=\fR
+.RS 4
+Configure a kernel keyring key name to use as cache for the password\&. If set, then the tool will try to push any collected passwords into the kernel keyring of the root user, as a key of the specified name\&. If combined with
+\fB\-\-accept\-cached\fR, it will also try to retrieve such cached passwords from the key in the kernel keyring instead of querying the user right away\&. By using this option, the kernel keyring may be used as effective cache to avoid repeatedly asking users for passwords, if there are multiple objects that may be unlocked with the same password\&. The cached key will have a timeout of 2\&.5min set, after which it will be purged from the kernel keyring\&. Note that it is possible to cache multiple passwords under the same keyname, in which case they will be stored as
+\fBNUL\fR\-separated list of passwords\&. Use
+\fBkeyctl\fR(1)
+to access the cached key via the kernel keyring directly\&. Example:
+"\-\-keyname=cryptsetup"
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-credential=\fR
+.RS 4
+Configure a credential to read the password from \(en if it exists\&. This may be used in conjunction with the
+\fIImportCredential=\fR,
+\fILoadCredential=\fR
+and
+\fISetCredential=\fR
+settings in unit files\&. See
+\fBsystemd.exec\fR(5)
+for details\&. If not specified, defaults to
+"password"\&. This option has no effect if no credentials directory is passed to the program (i\&.e\&.
+\fI$CREDENTIALS_DIRECTORY\fR
+is not set) or if the no credential of the specified name exists\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-timeout=\fR
+.RS 4
+Specify the query timeout in seconds\&. Defaults to 90s\&. A timeout of 0 waits indefinitely\&.
+.RE
+.PP
+\fB\-\-echo=yes|no|masked\fR
+.RS 4
+Controls whether to echo user input\&. Takes a boolean or the special string
+"masked", the default being the latter\&. If enabled the typed characters are echoed literally, which is useful for prompting for usernames and other non\-protected data\&. If disabled the typed characters are not echoed in any form, the user will not get feedback on their input\&. If set to
+"masked", an asterisk ("*") is echoed for each character typed\&. In this mode, if the user hits the tabulator key ("↹"), echo is turned off\&. (Alternatively, if the user hits the backspace key ("⌫") while no data has been entered otherwise, echo is turned off, too)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-echo\fR, \fB\-e\fR
+.RS 4
+Equivalent to
+\fB\-\-echo=yes\fR, see above\&.
+.sp
+Added in version 217\&.
+.RE
+.PP
+\fB\-\-emoji=yes|no|auto\fR
+.RS 4
+Controls whether or not to prefix the query with a lock and key emoji (�), if the TTY settings permit this\&. The default is
+"auto", which defaults to
+"yes", unless
+\fB\-\-echo=yes\fR
+is given\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-no\-tty\fR
+.RS 4
+Never ask for password on current TTY even if one is available\&. Always use agent system\&.
+.RE
+.PP
+\fB\-\-accept\-cached\fR
+.RS 4
+If passed, accept cached passwords, i\&.e\&. passwords previously entered\&.
+.RE
+.PP
+\fB\-\-multiple\fR
+.RS 4
+When used in conjunction with
+\fB\-\-accept\-cached\fR
+accept multiple passwords\&. This will output one password per line\&.
+.RE
+.PP
+\fB\-\-no\-output\fR
+.RS 4
+Do not print passwords to standard output\&. This is useful if you want to store a password in kernel keyring with
+\fB\-\-keyname=\fR
+but do not want it to show up on screen or in logs\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-n\fR
+.RS 4
+By default, when the acquired password is written to standard output it is suffixed by a newline character\&. This may be turned off with the
+\fB\-n\fR
+switch, similarly to the switch of the same name of the
+\fBecho\fR(1)
+command\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-ask-password-console.service\fR(8),
+\fBsystemd-tty-ask-password-agent\fR(1),
+\fBkeyctl\fR(1),
+\fBplymouth\fR(8),
+\fBwall\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+systemd Password Agent Specification
+.RS 4
+\%https://systemd.io/PASSWORD_AGENTS/
+.RE
+.IP " 2." 4
+XDG Icon Naming Specification
+.RS 4
+\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-bootchart.1 b/upstream/mageia-cauldron/man1/systemd-bootchart.1
new file mode 100644
index 00000000..eccf4508
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-bootchart.1
@@ -0,0 +1,197 @@
+'\" t
+.TH "SYSTEMD\-BOOTCHART" "1" "" "systemd 234" "systemd-bootchart"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-bootchart \- Boot performance graphing tool
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-bootchart\fR
+is a tool, usually run at system startup, that collects the CPU load, disk load, memory usage, as well as per\-process information from a running system\&. Collected results are output as an SVG graph\&. Normally, systemd\-bootchart is invoked by the kernel by passing
+\fBinit=\fR\fB/usr/lib/systemd/systemd\-bootchart\fR
+on the kernel command line, adding
+\fBinitcall_debug\fR
+to collect data on kernel init threads\&. systemd\-bootchart will then fork the real init off to resume normal system startup, while monitoring and logging startup information in the background\&.
+.PP
+After collecting a certain amount of data (usually 15\-30 seconds, default 20 s) the logging stops and a graph is generated from the logged information\&. This graph contains vital clues as to which resources are being used, in which order, and where possible problems exist in the startup sequence of the system\&. It is essentially a more detailed version of the
+\fBsystemd\-analyze plot\fR
+function\&.
+.PP
+Of course, bootchart can also be used at any moment in time to collect and graph some data for an amount of time\&. It is recommended to use the
+\fB\-\-rel\fR
+switch in this case\&.
+.PP
+Bootchart does not require root privileges, and will happily run as a normal user\&.
+.PP
+Bootchart graphs are by default written time\-stamped in
+/run/log
+and saved to the journal with
+\fIMESSAGE_ID=9f26aa562cf440c2b16c773d0479b518\fR\&. Journal field
+\fIBOOTCHART=\fR
+contains the bootchart in SVG format\&.
+.SH "INVOCATION"
+.PP
+\fBsystemd\-bootchart\fR
+can be invoked in several different ways:
+.PP
+\fIKernel invocation\fR
+.RS 4
+The kernel can invoke
+\fBsystemd\-bootchart\fR
+instead of the init process\&. In turn,
+\fBsystemd\-bootchart\fR
+will invoke
+\fB/usr/lib/systemd/systemd\fR\&. Data will be collected on kernel init threads and also processes including the services started by systemd\&.
+.RE
+.PP
+\fIsystemd unit\fR
+.RS 4
+A unit file is provided,
+\fBsystemd\-bootchart\&.service\fR\&. If enabled when the system starts it will collect data on processes including the services started by systemd\&.
+.RE
+.PP
+\fIStarted as a standalone program\fR
+.RS 4
+One can execute
+\fBsystemd\-bootchart\fR
+as normal application from the command line\&. In this mode it is highly recommended to pass the
+\fB\-r\fR
+flag in order to not graph the time elapsed since boot and before systemd\-bootchart was started, as it may result in extremely large graphs\&. The time elapsed since boot might also include any time that the system was suspended\&.
+.RE
+.SH "OPTIONS"
+.PP
+These options can also be set in the
+/etc/systemd/bootchart\&.conf
+file\&. See
+\fBbootchart.conf\fR(5)\&.
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-sample \fR\fB\fIN\fR\fR
+.RS 4
+Specify the number of samples,
+\fIN\fR, to record\&. Samples will be recorded at intervals defined with
+\fB\-\-freq\fR\&.
+.RE
+.PP
+\fB\-f\fR, \fB\-\-freq \fR\fB\fIf\fR\fR
+.RS 4
+Specify the sample log frequency, a positive real
+\fIf\fR, in Hz\&. Most systems can cope with values up to 25\-50 without creating too much overhead\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-rel\fR
+.RS 4
+Use relative times instead of absolute times\&. This is useful for using bootchart at post\-boot time to profile an already booted system\&. Without this option the graph would become extremely large\&. If set, the horizontal axis starts at the first recorded sample instead of time 0\&.0\&.
+.RE
+.PP
+\fB\-F\fR, \fB\-\-no\-filter\fR
+.RS 4
+Disable filtering of tasks that did not contribute significantly to the boot\&. Processes that are too short\-lived (only seen in one sample) or that do not consume any significant CPU time (less than 0\&.001 s) will not be displayed in the output graph\&.
+.RE
+.PP
+\fB\-C\fR, \fB\-\-cmdline\fR
+.RS 4
+Display the full command line with arguments of processes, instead of only the process name\&.
+.RE
+.PP
+\fB\-g\fR, \fB\-\-control\-group\fR
+.RS 4
+Display process control group
+.RE
+.PP
+\fB\-o\fR, \fB\-\-output \fR\fB\fIpath\fR\fR
+.RS 4
+Specify the output directory for the graphs\&. By default, bootchart writes the graphs to
+/run/log\&.
+.RE
+.PP
+\fB\-i\fR, \fB\-\-init \fR\fB\fIpath\fR\fR
+.RS 4
+Use this init binary\&. Defaults to
+\fB/usr/lib/systemd/systemd\fR\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-pss\fR
+.RS 4
+Enable logging and graphing of processes\*(Aq PSS (Proportional Set Size) memory consumption\&. See
+filesystems/proc\&.txt
+in the kernel documentation for an explanation of this field\&.
+.RE
+.PP
+\fB\-e\fR, \fB\-\-entropy\fR
+.RS 4
+Enable logging and graphing of the kernel random entropy pool size\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-scale\-x \fR\fB\fIN\fR\fR
+.RS 4
+Horizontal scaling factor for all variable graph components\&.
+.RE
+.PP
+\fB\-y\fR, \fB\-\-scale\-y \fR\fB\fIN\fR\fR
+.RS 4
+Vertical scaling factor for all variable graph components\&.
+.RE
+.SH "OUTPUT"
+.PP
+\fBsystemd\-bootchart\fR
+generates SVG graphs\&. In order to render those on a graphical display any SVG capable viewer can be used\&. It should be noted that the SVG render engines in most browsers (including Chrome and Firefox) are many times faster than dedicated graphical applications like Gimp and Inkscape\&. Just point your browser at
+\m[blue]\fB\%file:///run/log/\fR\m[]!
+.SH "HISTORY"
+.PP
+This version of bootchart was implemented from scratch, but is inspired by former bootchart incantations:
+.PP
+\fIOriginal bash\fR
+.RS 4
+The original bash/shell code implemented bootchart\&. This version created a compressed tarball for processing with external applications\&. This version did not graph anything, only generated data\&.
+.RE
+.PP
+\fIUbuntu C Implementation\fR
+.RS 4
+This version replaced the shell version with a fast and efficient data logger, but also did not graph the data\&.
+.RE
+.PP
+\fIJava bootchart\fR
+.RS 4
+This was the original graphing application for charting the data, written in java\&.
+.RE
+.PP
+\fIpybootchartgui\&.py\fR
+.RS 4
+pybootchart created a graph from the data collected by either the bash or C version\&.
+.RE
+.PP
+The version of bootchart you are using now combines both the data collection and the charting into a single application, making it more efficient and simpler\&. There are no longer any timing issues with the data collector and the grapher, as the graphing cannot be run until the data has been collected\&. Also, the data kept in memory is reduced to the absolute minimum needed\&.
+.SH "SEE ALSO"
+.PP
+\fBbootchart.conf\fR(5)
+.SH "BUGS"
+.PP
+systemd\-bootchart does not get the model information for the hard drive unless the root device is specified with
+root=/dev/sdxY\&. Using UUIDs or PARTUUIDs will boot fine, but the hard drive model will not be added to the chart\&.
+.PP
+For bugs, please contact the author and current maintainer:
+.RS 4
+Auke Kok <auke\-jan\&.h\&.kok@intel\&.com>
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-cat.1 b/upstream/mageia-cauldron/man1/systemd-cat.1
new file mode 100644
index 00000000..0e441745
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-cat.1
@@ -0,0 +1,140 @@
+'\" t
+.TH "SYSTEMD\-CAT" "1" "" "systemd 255" "systemd-cat"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-cat \- Connect a pipeline or program\*(Aqs output with the journal
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-cat\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[COMMAND]\fR\fB\ \fR\fB[ARGUMENTS...]\fR\ 'u
+\fBsystemd\-cat \fR\fB[OPTIONS...]\fR\fB \fR\fB[COMMAND]\fR\fB \fR\fB[ARGUMENTS...]\fR
+.HP \w'\fBsystemd\-cat\ \fR\fB[OPTIONS...]\fR\ 'u
+\fBsystemd\-cat \fR\fB[OPTIONS...]\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-cat\fR
+may be used to connect the standard input and output of a process to the journal, or as a filter tool in a shell pipeline to pass the output the previous pipeline element generates to the journal\&.
+.PP
+If no parameter is passed,
+\fBsystemd\-cat\fR
+will write everything it reads from standard input (stdin) to the journal\&.
+.PP
+If parameters are passed, they are executed as command line with standard output (stdout) and standard error output (stderr) connected to the journal, so that all it writes is stored in the journal\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-t\fR, \fB\-\-identifier=\fR
+.RS 4
+Specify a short string that is used to identify the logging tool\&. If not specified, no identification string is written to the journal\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-priority=\fR
+.RS 4
+Specify the default priority level for the logged messages\&. Pass one of
+"emerg",
+"alert",
+"crit",
+"err",
+"warning",
+"notice",
+"info",
+"debug", or a value between 0 and 7 (corresponding to the same named levels)\&. These priority values are the same as defined by
+\fBsyslog\fR(3)\&. Defaults to
+"info"\&. Note that this simply controls the default, individual lines may be logged with different levels if they are prefixed accordingly\&. For details, see
+\fB\-\-level\-prefix=\fR
+below\&.
+.RE
+.PP
+\fB\-\-stderr\-priority=\fR
+.RS 4
+Specifies the default priority level for messages from the process\*(Aqs standard error output (stderr)\&. Usage of this option is the same as the
+\fB\-\-priority=\fR
+option, above, and both can be used at once\&. When both are used,
+\fB\-\-priority=\fR
+will specify the default priority for standard output (stdout)\&.
+.sp
+If
+\fB\-\-stderr\-priority=\fR
+is not specified, messages from stderr will still be logged, with the same default priority level as stdout\&.
+.sp
+Also, note that when stdout and stderr use the same default priority, the messages will be strictly ordered, because one channel is used for both\&. When the default priority differs, two channels are used, and so stdout messages will not be strictly ordered with respect to stderr messages \- though they will tend to be approximately ordered\&.
+.sp
+Added in version 241\&.
+.RE
+.PP
+\fB\-\-level\-prefix=\fR
+.RS 4
+Controls whether lines read are parsed for syslog priority level prefixes\&. If enabled (the default), a line prefixed with a priority prefix such as
+"<5>"
+is logged at priority 5 ("notice"), and similarly for the other priority levels\&. Takes a boolean argument\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Invoke a program\fR
+.PP
+This calls
+/bin/ls
+with standard output and error connected to the journal:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-cat ls
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Usage in a shell pipeline\fR
+.PP
+This builds a shell pipeline also invoking
+/bin/ls
+and writes the output it generates to the journal:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# ls | systemd\-cat
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Even though the two examples have very similar effects, the first is preferable, since only one process is running at a time and both stdout and stderr are captured, while in the second example, only stdout is captured\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBlogger\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-cgls.1 b/upstream/mageia-cauldron/man1/systemd-cgls.1
new file mode 100644
index 00000000..781d9307
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-cgls.1
@@ -0,0 +1,116 @@
+'\" t
+.TH "SYSTEMD\-CGLS" "1" "" "systemd 255" "systemd-cgls"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-cgls \- Recursively show control group contents
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-cgls\fR\ 'u
+\fBsystemd\-cgls\fR [OPTIONS...] [CGROUP...]
+.HP \w'\fBsystemd\-cgls\fR\ 'u
+\fBsystemd\-cgls\fR [OPTIONS...] \fB\-\-unit\fR|\fB\-\-user\-unit\fR [UNIT...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-cgls\fR
+recursively shows the contents of the selected Linux control group hierarchy in a tree\&. If arguments are specified, shows all member processes of the specified control groups plus all their subgroups and their members\&. The control groups may either be specified by their full file paths or are assumed in the systemd control group hierarchy\&. If no argument is specified and the current working directory is beneath the control group mount point
+/sys/fs/cgroup/, shows the contents of the control group the working directory refers to\&. Otherwise, the full systemd control group hierarchy is shown\&.
+.PP
+By default, empty control groups are not shown\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-all\fR
+.RS 4
+Do not hide empty control groups in the output\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize process tree members\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-\-unit\fR
+.RS 4
+Show cgroup subtrees for the specified units\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-\-user\-unit\fR
+.RS 4
+Show cgroup subtrees for the specified user units\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-k\fR
+.RS 4
+Include kernel threads in output\&.
+.RE
+.PP
+\fB\-M \fR\fB\fIMACHINE\fR\fR, \fB\-\-machine=\fR\fB\fIMACHINE\fR\fR
+.RS 4
+Limit control groups shown to the part corresponding to the container
+\fIMACHINE\fR\&.
+.sp
+Added in version 203\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-xattr=\fR
+.RS 4
+Controls whether to include information about extended attributes of the listed control groups in the output\&. With the long option, expects a boolean value\&. Defaults to no\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-cgroup\-id=\fR
+.RS 4
+Controls whether to include the numeric ID of the listed control groups in the output\&. With the long option, expects a boolean value\&. Defaults to no\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd-cgtop\fR(1),
+\fBsystemd-nspawn\fR(1),
+\fBps\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-cgtop.1 b/upstream/mageia-cauldron/man1/systemd-cgtop.1
new file mode 100644
index 00000000..c67d5e34
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-cgtop.1
@@ -0,0 +1,290 @@
+'\" t
+.TH "SYSTEMD\-CGTOP" "1" "" "systemd 255" "systemd-cgtop"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-cgtop \- Show top control groups by their resource usage
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-cgtop\fR\ 'u
+\fBsystemd\-cgtop\fR [OPTIONS...] [GROUP]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-cgtop\fR
+shows the top control groups of the local Linux control group hierarchy, ordered by their CPU, memory, or disk I/O load\&. The display is refreshed in regular intervals (by default every 1s), similar in style to
+\fBtop\fR(1)\&. If a control group path is specified, shows only the services of the specified control group\&.
+.PP
+If
+\fBsystemd\-cgtop\fR
+is not connected to a tty, no column headers are printed and the default is to only run one iteration\&. The
+\fB\-\-iterations=\fR
+argument, if given, is honored\&. This mode is suitable for scripting\&.
+.PP
+Resource usage is only accounted for control groups with the appropriate controllers turned on:
+"cpu"
+controller for CPU usage,
+"memory"
+controller for memory usage, and
+"io"
+controller for disk I/O consumption\&. If resource monitoring for these resources is required, it is recommended to add the
+\fICPUAccounting=1\fR,
+\fIMemoryAccounting=1\fR
+and
+\fIIOAccounting=1\fR
+settings in the unit files in question\&. See
+\fBsystemd.resource-control\fR(5)
+for details\&.
+.PP
+The CPU load value can be between 0 and 100 times the number of processors the system has\&. For example, if the system has 8 processors, the CPU load value is going to be between 0% and 800%\&. The number of processors can be found in
+"/proc/cpuinfo"\&.
+.PP
+To emphasize: unless
+"CPUAccounting=1",
+"MemoryAccounting=1", and
+"IOAccounting=1"
+are enabled for the services in question, no resource accounting will be available for system services and the data shown by
+\fBsystemd\-cgtop\fR
+will be incomplete\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-p\fR, \fB\-\-order=path\fR
+.RS 4
+Order by control group path name\&.
+.RE
+.PP
+\fB\-t\fR, \fB\-\-order=tasks\fR
+.RS 4
+Order by number of tasks/processes in the control group\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-order=cpu\fR
+.RS 4
+Order by CPU load\&.
+.RE
+.PP
+\fB\-m\fR, \fB\-\-order=memory\fR
+.RS 4
+Order by memory usage\&.
+.RE
+.PP
+\fB\-i\fR, \fB\-\-order=io\fR
+.RS 4
+Order by disk I/O load\&.
+.RE
+.PP
+\fB\-b\fR, \fB\-\-batch\fR
+.RS 4
+Run in "batch" mode: do not accept input and run until the iteration limit set with
+\fB\-\-iterations=\fR
+is exhausted or until killed\&. This mode could be useful for sending output from
+\fBsystemd\-cgtop\fR
+to other programs or to a file\&.
+.sp
+Added in version 188\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-raw\fR
+.RS 4
+Format byte counts (as in memory usage and I/O metrics) and CPU time with raw numeric values rather than human\-readable numbers\&.
+.sp
+Added in version 221\&.
+.RE
+.PP
+\fB\-\-cpu=percentage\fR, \fB\-\-cpu=time\fR
+.RS 4
+Controls whether the CPU usage is shown as percentage or time\&. By default, the CPU usage is shown as percentage\&. This setting may also be toggled at runtime by pressing the
+%
+key\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+\fB\-P\fR
+.RS 4
+Count only userspace processes instead of all tasks\&. By default, all tasks are counted: each kernel thread and each userspace thread individually\&. With this setting, kernel threads are excluded from the count and each userspace process only counts as one task, regardless of how many threads it consists of\&. This setting may also be toggled at runtime by pressing the
+P
+key\&. This option may not be combined with
+\fB\-k\fR\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-k\fR
+.RS 4
+Count only userspace processes and kernel threads instead of all tasks\&. By default, all tasks are counted: each kernel thread and each userspace thread individually\&. With this setting, kernel threads are included in the count and each userspace process only counts as one task, regardless of how many threads it consists of\&. This setting may also be toggled at runtime by pressing the
+k
+key\&. This option may not be combined with
+\fB\-P\fR\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+\fB\-\-recursive=\fR
+.RS 4
+Controls whether the number of processes shown for a control group shall include all processes that are contained in any of the child control groups as well\&. Takes a boolean argument, which defaults to
+"yes"\&. If enabled, the processes in child control groups are included, if disabled, only the processes in the control group itself are counted\&. This setting may also be toggled at runtime by pressing the
+r
+key\&. Note that this setting only applies to process counting, i\&.e\&. when the
+\fB\-P\fR
+or
+\fB\-k\fR
+options are used\&. It has not effect if all tasks are counted, in which case the counting is always recursive\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-iterations=\fR
+.RS 4
+Perform only this many iterations\&. A value of 0 indicates that the program should run indefinitely\&.
+.sp
+Added in version 188\&.
+.RE
+.PP
+\fB\-1\fR
+.RS 4
+A shortcut for
+\fB\-\-iterations=1\fR\&.
+.sp
+Added in version 238\&.
+.RE
+.PP
+\fB\-d\fR, \fB\-\-delay=\fR
+.RS 4
+Specify refresh delay in seconds (or if one of
+"ms",
+"us",
+"min"
+is specified as unit in this time unit)\&. This setting may also be increased and decreased at runtime by pressing the
++
+and
+\-
+keys\&.
+.RE
+.PP
+\fB\-\-depth=\fR
+.RS 4
+Maximum control group tree traversal depth\&. Specifies how deep
+\fBsystemd\-cgtop\fR
+shall traverse the control group hierarchies\&. If 0 is specified, only the root group is monitored\&. For 1, only the first level of control groups is monitored, and so on\&. Defaults to 3\&.
+.RE
+.PP
+\fB\-M \fR\fB\fIMACHINE\fR\fR, \fB\-\-machine=\fR\fB\fIMACHINE\fR\fR
+.RS 4
+Limit control groups shown to the part corresponding to the container
+\fIMACHINE\fR\&. This option may not be used when a control group path is specified\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "KEYS"
+.PP
+\fBsystemd\-cgtop\fR
+is an interactive tool and may be controlled via user input using the following keys:
+.PP
+h
+.RS 4
+Shows a short help text\&.
+.RE
+.PP
+Space
+.RS 4
+Immediately refresh output\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+q
+.RS 4
+Terminate the program\&.
+.RE
+.PP
+p, t, c, m, i
+.RS 4
+Sort the control groups by path, number of tasks, CPU load, memory usage, or I/O load, respectively\&. This setting may also be controlled using the
+\fB\-\-order=\fR
+command line switch\&.
+.RE
+.PP
+%
+.RS 4
+Toggle between showing CPU time as time or percentage\&. This setting may also be controlled using the
+\fB\-\-cpu=\fR
+command line switch\&.
+.sp
+Added in version 201\&.
+.RE
+.PP
++, \-
+.RS 4
+Increase or decrease refresh delay, respectively\&. This setting may also be controlled using the
+\fB\-\-delay=\fR
+command line switch\&.
+.RE
+.PP
+P
+.RS 4
+Toggle between counting all tasks, or only userspace processes\&. This setting may also be controlled using the
+\fB\-P\fR
+command line switch (see above)\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+k
+.RS 4
+Toggle between counting all tasks, or only userspace processes and kernel threads\&. This setting may also be controlled using the
+\fB\-k\fR
+command line switch (see above)\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+r
+.RS 4
+Toggle between recursively including or excluding processes in child control groups in control group process counts\&. This setting may also be controlled using the
+\fB\-\-recursive=\fR
+command line switch\&. This key is not available if all tasks are counted, it is only available if processes are counted, as enabled with the
+P
+or
+k
+keys\&.
+.sp
+Added in version 226\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd-cgls\fR(1),
+\fBsystemd.resource-control\fR(5),
+\fBtop\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-creds.1 b/upstream/mageia-cauldron/man1/systemd-creds.1
new file mode 100644
index 00000000..db9944ec
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-creds.1
@@ -0,0 +1,554 @@
+'\" t
+.TH "SYSTEMD\-CREDS" "1" "" "systemd 255" "systemd-creds"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-creds \- Lists, shows, encrypts and decrypts service credentials
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-creds\fR\ 'u
+\fBsystemd\-creds\fR [OPTIONS...] COMMAND [ARGS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-creds\fR
+is a tool for listing, showing, encrypting and decrypting unit credentials\&. Credentials are limited\-size binary or textual objects that may be passed to unit processes\&. They are primarily used for passing cryptographic keys (both public and private) or certificates, user account information or identity information from the host to services\&.
+.PP
+Credentials are configured in unit files via the
+\fIImportCredential=\fR,
+\fILoadCredential=\fR,
+\fISetCredential=\fR,
+\fILoadCredentialEncrypted=\fR, and
+\fISetCredentialEncrypted=\fR
+settings, see
+\fBsystemd.exec\fR(5)
+for details\&.
+.PP
+For further information see
+\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[1]\d\s+2
+documentation\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBlist\fR
+.RS 4
+Show a list of credentials passed into the current execution context\&. This command shows the files in the directory referenced by the
+\fI$CREDENTIALS_DIRECTORY\fR
+environment variable, and is intended to be executed from within service context\&.
+.sp
+Along with each credential name, the size and security state is shown\&. The latter is one of
+"secure"
+(in case the credential is backed by unswappable memory, i\&.e\&.
+"ramfs"),
+"weak"
+(in case it is backed by any other type of memory), or
+"insecure"
+(if having any access mode that is not 0400, i\&.e\&. if readable by anyone but the owner)\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBcat\fR \fIcredential\&.\&.\&.\fR
+.RS 4
+Show contents of specified credentials passed into the current execution context\&. Takes one or more credential names, whose contents shall be written to standard output\&.
+.sp
+When combined with
+\fB\-\-json=\fR
+or
+\fB\-\-transcode=\fR
+the output is transcoded in simple ways before outputting\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBsetup\fR
+.RS 4
+Generates a host encryption key for credentials, if one has not been generated already\&. This ensures the
+/var/lib/systemd/credential\&.secret
+file is initialized with a random secret key if it doesn\*(Aqt exist yet\&. This secret key is used when encrypting/decrypting credentials with
+\fBencrypt\fR
+or
+\fBdecrypt\fR, and is only accessible to the root user\&. Note that there\*(Aqs typically no need to invoke this command explicitly as it is implicitly called when
+\fBencrypt\fR
+is invoked, and credential host key encryption selected\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBencrypt\fR \fIinput|\-\fR \fIoutput|\-\fR
+.RS 4
+Loads the specified (unencrypted plaintext) input credential file, encrypts it and writes the (encrypted ciphertext) output to the specified target credential file\&. The resulting file may be referenced in the
+\fILoadCredentialEncrypted=\fR
+setting in unit files, or its contents used literally in
+\fISetCredentialEncrypted=\fR
+settings\&.
+.sp
+Takes two file system paths\&. The file name part of the output path is embedded as name in the encrypted credential, to ensure encrypted credentials cannot be renamed and reused for different purposes without this being noticed\&. The credential name to embed may be overridden with the
+\fB\-\-name=\fR
+setting\&. The input or output paths may be specified as
+"\-", in which case the credential data is read from/written to standard input and standard output\&. If the output path is specified as
+"\-"
+the credential name cannot be derived from the file system path, and thus should be specified explicitly via the
+\fB\-\-name=\fR
+switch\&.
+.sp
+The credential data is encrypted and authenticated symmetrically with one of the following encryption keys:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+A secret key automatically derived from the system\*(Aqs TPM2 chip\&. This encryption key is not stored on the host system and thus decryption is only possible with access to the original TPM2 chip\&. Or in other words, the credential secured in this way can only be decrypted again by the local machine\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+A secret key stored in the
+/var/lib/systemd/credential\&.secret
+file which is only accessible to the root user\&. This "host" encryption key is stored on the host file system, and thus decryption is possible with access to the host file system and sufficient privileges\&. The key is automatically generated when needed, but can also be created explicitly with the
+\fBsetup\fR
+command, see above\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+A combination of the above: an encryption key derived from both the TPM2 chip and the host file system\&. This means decryption requires both access to the original TPM2 chip and the OS installation\&. This is the default mode of operation if a TPM2 chip is available and
+/var/lib/systemd/
+resides on persistent media\&.
+.RE
+.sp
+Which of the three keys shall be used for encryption may be configured with the
+\fB\-\-with\-key=\fR
+switch\&. Depending on the use\-case for the encrypted credential the key to use may differ\&. For example, for credentials that shall be accessible from the initrd, encryption with the host key is not appropriate, since access to the host key is typically not available from the initrd\&. Thus, for such credentials only the TPM2 key should be used\&.
+.sp
+Encrypted credentials are always encoded in Base64\&.
+.sp
+Use
+\fBdecrypt\fR
+(see below) to undo the encryption operation, and acquire the decrypted plaintext credential from the encrypted ciphertext credential\&.
+.sp
+The credential data is encrypted using AES256\-GCM, i\&.e\&. providing both confidentiality and integrity, keyed by a SHA256 hash of one or both of the secret keys described above\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBdecrypt\fR \fIinput|\-\fR [\fIoutput|\-\fR]
+.RS 4
+Undoes the effect of the
+\fBencrypt\fR
+operation: loads the specified (encrypted ciphertext) input credential file, decrypts and authenticates it and writes the (decrypted plaintext) output to the specified target credential file\&.
+.sp
+Takes one or two file system paths\&. The file name part of the input path is compared with the credential name embedded in the encrypted file\&. If it does not match decryption fails\&. This is done in order to ensure that encrypted credentials are not re\-purposed without this being detected\&. The credential name to compare with the embedded credential name may also be overridden with the
+\fB\-\-name=\fR
+switch\&. If the input path is specified as
+"\-", the encrypted credential is read from standard input\&. If only one path is specified or the output path specified as
+"\-", the decrypted credential is written to standard output\&. In this mode, the expected name embedded in the credential cannot be derived from the path and should be specified explicitly with
+\fB\-\-name=\fR\&.
+.sp
+Decrypting credentials requires access to the original TPM2 chip and/or credentials host key, see above\&. Information about which keys are required is embedded in the encrypted credential data, and thus decryption is entirely automatic\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBhas\-tpm2\fR
+.RS 4
+Reports whether the system is equipped with a TPM2 device usable for protecting credentials\&. If a TPM2 device has been discovered, is supported, and is being used by firmware, by the OS kernel drivers and by userspace (i\&.e\&. systemd) this prints
+"yes"
+and exits with exit status zero\&. If no such device is discovered/supported/used, prints
+"no"\&. Otherwise prints
+"partial"\&. In either of these two cases exits with non\-zero exit status\&. It also shows four lines indicating separately whether firmware, drivers, the system and the kernel discovered/support/use TPM2\&.
+.sp
+Combine with
+\fB\-\-quiet\fR
+to suppress the output\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "OPTIONS"
+.PP
+\fB\-\-system\fR
+.RS 4
+When specified with the
+\fBlist\fR
+and
+\fBcat\fR
+commands operates on the credentials passed to system as a whole instead of on those passed to the current execution context\&. This is useful in container environments where credentials may be passed in from the container manager\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-transcode=\fR
+.RS 4
+When specified with the
+\fBcat\fR
+or
+\fBdecrypt\fR
+commands, transcodes the output before showing it\&. Takes one of
+"base64",
+"unbase64",
+"hex"
+or
+"unhex"
+as argument, in order to encode/decode the credential data with Base64 or as series of hexadecimal values\&.
+.sp
+Note that this has no effect on the
+\fBencrypt\fR
+command, as encrypted credentials are unconditionally encoded in Base64\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-newline=\fR
+.RS 4
+When specified with
+\fBcat\fR
+or
+\fBdecrypt\fR
+controls whether to add a trailing newline character to the end of the output if it doesn\*(Aqt end in one, anyway\&. Takes one of
+"auto",
+"yes"
+or
+"no"\&. The default mode of
+"auto"
+will suffix the output with a single newline character only when writing credential data to a TTY\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-pretty\fR, \fB\-p\fR
+.RS 4
+When specified with
+\fBencrypt\fR
+controls whether to show the encrypted credential as
+\fISetCredentialEncrypted=\fR
+setting that may be pasted directly into a unit file\&. Has effect only when used together with
+\fB\-\-name=\fR
+and
+"\-"
+as the output file\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-name=\fR\fIname\fR
+.RS 4
+When specified with the
+\fBencrypt\fR
+command controls the credential name to embed in the encrypted credential data\&. If not specified the name is chosen automatically from the filename component of the specified output path\&. If specified as empty string no credential name is embedded in the encrypted credential, and no verification of credential name is done when the credential is decrypted\&.
+.sp
+When specified with the
+\fBdecrypt\fR
+command control the credential name to validate the credential name embedded in the encrypted credential with\&. If not specified the name is chosen automatically from the filename component of the specified input path\&. If no credential name is embedded in the encrypted credential file (i\&.e\&. the
+\fB\-\-name=\fR
+with an empty string was used when encrypted) the specified name has no effect as no credential name validation is done\&.
+.sp
+Embedding the credential name in the encrypted credential is done in order to protect against reuse of credentials for purposes they weren\*(Aqt originally intended for, under the assumption the credential name is chosen carefully to encode its intended purpose\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-timestamp=\fR\fItimestamp\fR
+.RS 4
+When specified with the
+\fBencrypt\fR
+command controls the timestamp to embed into the encrypted credential\&. Defaults to the current time\&. Takes a timestamp specification in the format described in
+\fBsystemd.time\fR(7)\&.
+.sp
+When specified with the
+\fBdecrypt\fR
+command controls the timestamp to use to validate the "not\-after" timestamp that was configured with
+\fB\-\-not\-after=\fR
+during encryption\&. If not specified defaults to the current system time\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-not\-after=\fR\fItimestamp\fR
+.RS 4
+When specified with the
+\fBencrypt\fR
+command controls the time when the credential shall not be used anymore\&. This embeds the specified timestamp in the encrypted credential\&. During decryption the timestamp is checked against the current system clock, and if the timestamp is in the past the decryption will fail\&. By default no such timestamp is set\&. Takes a timestamp specification in the format described in
+\fBsystemd.time\fR(7)\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-with\-key=\fR, \fB\-H\fR, \fB\-T\fR
+.RS 4
+When specified with the
+\fBencrypt\fR
+command controls the encryption/signature key to use\&. Takes one of
+"host",
+"tpm2",
+"host+tpm2",
+"tpm2\-absent",
+"auto",
+"auto\-initrd"\&. See above for details on the three key types\&. If set to
+"auto"
+(which is the default) the TPM2 key is used if a TPM2 device is found and not running in a container\&. The host key is used if
+/var/lib/systemd/
+is on persistent media\&. This means on typical systems the encryption is by default bound to both the TPM2 chip and the OS installation, and both need to be available to decrypt the credential again\&. If
+"auto"
+is selected but neither TPM2 is available (or running in container) nor
+/var/lib/systemd/
+is on persistent media, encryption will fail\&. If set to
+"tpm2\-absent"
+a fixed zero length key is used (thus, in this mode no confidentiality nor authenticity are provided!)\&. This logic is useful to cover for systems that lack a TPM2 chip but where credentials shall be generated\&. Note that decryption of such credentials is refused on systems that have a TPM2 chip and where UEFI SecureBoot is enabled (this is done so that such a locked down system cannot be tricked into loading a credential generated this way that lacks authentication information)\&. If set to
+"auto\-initrd"
+a TPM2 key is used if a TPM2 is found\&. If not a fixed zero length key is used, equivalent to
+"tpm2\-absent"
+mode\&. This option is particularly useful to generate credentials files that are encrypted/authenticated against TPM2 where available but still work on systems lacking support for this\&.
+.sp
+The
+\fB\-H\fR
+switch is a shortcut for
+\fB\-\-with\-key=host\fR\&. Similar,
+\fB\-T\fR
+is a shortcut for
+\fB\-\-with\-key=tpm2\fR\&.
+.sp
+When encrypting credentials that shall be used in the initrd (where
+/var/lib/systemd/
+is typically not available) make sure to use
+\fB\-\-with\-key=auto\-initrd\fR
+mode, to disable binding against the host secret\&.
+.sp
+This switch has no effect on the
+\fBdecrypt\fR
+command, as information on which key to use for decryption is included in the encrypted credential already\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-tpm2\-device=\fR\fIPATH\fR
+.RS 4
+Controls the TPM2 device to use\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
+/dev/tpmrm0)\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one)\&. The special value
+"list"
+may be used to enumerate all suitable TPM2 devices currently discovered\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-tpm2\-pcrs=\fR [PCR...]
+.RS 4
+Configures the TPM2 PCRs (Platform Configuration Registers) to bind the encryption key to\&. Takes a
+"+"
+separated list of numeric PCR indexes in the range 0\&...23\&. If not used, defaults to PCR 7 only\&. If an empty string is specified, binds the encryption key to no PCRs at all\&. For details about the PCRs available, see the documentation of the switch of the same name for
+\fBsystemd-cryptenroll\fR(1)\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-tpm2\-public\-key=\fR [PATH], \fB\-\-tpm2\-public\-key\-pcrs=\fR [PCR...]
+.RS 4
+Configures a TPM2 signed PCR policy to bind encryption to, for use with the
+\fBencrypt\fR
+command\&. The
+\fB\-\-tpm2\-public\-key=\fR
+option accepts a path to a PEM encoded RSA public key, to bind the encryption to\&. If this is not specified explicitly, but a file
+tpm2\-pcr\-public\-key\&.pem
+exists in one of the directories
+/etc/systemd/,
+/run/systemd/,
+/usr/lib/systemd/
+(searched in this order), it is automatically used\&. The
+\fB\-\-tpm2\-public\-key\-pcrs=\fR
+option takes a list of TPM2 PCR indexes to bind to (same syntax as
+\fB\-\-tpm2\-pcrs=\fR
+described above)\&. If not specified defaults to 11 (i\&.e\&. this binds the policy to any unified kernel image for which a PCR signature can be provided)\&.
+.sp
+Note the difference between
+\fB\-\-tpm2\-pcrs=\fR
+and
+\fB\-\-tpm2\-public\-key\-pcrs=\fR: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided\&. The latter is hence more useful in scenarios where software updates shall be possible without losing access to all previously encrypted secrets\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-tpm2\-signature=\fR [PATH]
+.RS 4
+Takes a path to a TPM2 PCR signature file as generated by the
+\fBsystemd-measure\fR(1)
+tool and that may be used to allow the
+\fBdecrypt\fR
+command to decrypt credentials that are bound to specific signed PCR values\&. If this is not specified explicitly, and a credential with a signed PCR policy is attempted to be decrypted, a suitable signature file
+tpm2\-pcr\-signature\&.json
+is searched for in
+/etc/systemd/,
+/run/systemd/,
+/usr/lib/systemd/
+(in this order) and used\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-quiet\fR, \fB\-q\fR
+.RS 4
+When used with
+\fBhas\-tpm2\fR
+suppresses the output, and only returns an exit status indicating support for TPM2\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned\&.
+.PP
+In case of the
+\fBhas\-tpm2\fR
+command returns 0 if a TPM2 device is discovered, supported and used by firmware, driver, and userspace (i\&.e\&. systemd)\&. Otherwise returns the OR combination of the value 1 (in case firmware support is missing), 2 (in case driver support is missing) and 4 (in case userspace support is missing)\&. If no TPM2 support is available at all, value 7 is hence returned\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Encrypt a password for use as credential\fR
+.PP
+The following command line encrypts the specified password
+"hunter2", writing the result to a file
+password\&.cred\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# echo \-n hunter2 | systemd\-creds encrypt \- password\&.cred
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This decrypts the file
+password\&.cred
+again, revealing the literal password:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-creds decrypt password\&.cred
+hunter2
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Encrypt a password and include it in a unit file\fR
+.PP
+The following command line prompts the user for a password and generates a
+\fISetCredentialEncrypted=\fR
+line from it for a credential named
+"mysql\-password", suitable for inclusion in a unit file\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-ask\-password \-n | systemd\-creds encrypt \-\-name=mysql\-password \-p \- \-
+� Password: ****
+SetCredentialEncrypted=mysql\-password: \e
+        k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \e
+        NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \e
+        mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \e
+        700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \e
+        yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \e
+        gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \e
+        9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A==
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The generated line can be pasted 1:1 into a unit file, and will ensure the acquired password will be made available in the
+\fI$CREDENTIALS_DIRECTORY\fR/mysql\-password
+credential file for the started service\&.
+.PP
+Utilizing the unit file drop\-in logic this can be used to securely pass a password credential to a unit\&. A similar, more comprehensive set of commands to insert a password into a service
+xyz\&.service:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# mkdir \-p /etc/systemd/system/xyz\&.service\&.d
+# systemd\-ask\-password \-n | ( echo "[Service]" && systemd\-creds encrypt \-\-name=mysql\-password \-p \- \- ) >/etc/systemd/system/xyz\&.service\&.d/50\-password\&.conf
+# systemctl daemon\-reload
+# systemctl restart xyz\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd.exec\fR(5),
+\fBsystemd-measure\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+System and Service Credentials
+.RS 4
+\%https://systemd.io/CREDENTIALS
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-cryptenroll.1 b/upstream/mageia-cauldron/man1/systemd-cryptenroll.1
new file mode 100644
index 00000000..e65f3cd0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-cryptenroll.1
@@ -0,0 +1,749 @@
+'\" t
+.TH "SYSTEMD\-CRYPTENROLL" "1" "" "systemd 255" "systemd-cryptenroll"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-cryptenroll \- Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-cryptenroll\fR\ 'u
+\fBsystemd\-cryptenroll\fR [OPTIONS...] [DEVICE]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-cryptenroll\fR
+is a tool for enrolling hardware security tokens and devices into a LUKS2 encrypted volume, which may then be used to unlock the volume during boot\&. Specifically, it supports tokens and credentials of the following kind to be enrolled:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+PKCS#11 security tokens and smartcards that may carry an RSA key pair (e\&.g\&. various YubiKeys)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+FIDO2 security tokens that implement the
+"hmac\-secret"
+extension (most FIDO2 keys, including YubiKeys)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+TPM2 security devices
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+Regular passphrases
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+Recovery keys\&. These are similar to regular passphrases, however are randomly generated on the computer and thus generally have higher entropy than user\-chosen passphrases\&. Their character set has been designed to ensure they are easy to type in, while having high entropy\&. They may also be scanned off screen using QR codes\&. Recovery keys may be used for unlocking LUKS2 volumes wherever passphrases are accepted\&. They are intended to be used in combination with an enrolled hardware security token, as a recovery option when the token is lost\&.
+.RE
+.PP
+In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset of them\&. The latter may be combined with the enrollment operation of a new security token, in order to update or replace enrollments\&.
+.PP
+The tool supports only LUKS2 volumes, as it stores token meta\-information in the LUKS2 JSON token area, which is not available in other encryption formats\&.
+.SS "TPM2 PCRs and policies"
+.PP
+PCRs allow binding of the encryption of secrets to specific software versions and system state, so that the enrolled key is only accessible (may be "unsealed") if specific trusted software and/or configuration is used\&. Such bindings may be created with the option
+\fB\-\-tpm2\-pcrs=\fR
+described below\&.
+.PP
+Secrets may also be bound indirectly: a signed policy for a state of some combination of PCR values is provided, and the secret is bound to the public part of the key used to sign this policy\&. This means that the owner of a key can generate a sequence of signed policies, for specific software versions and system states, and the secret can be decrypted as long as the machine state matches one of those policies\&. For example, a vendor may provide such a policy for each kernel+initrd update, allowing users to encrypt secrets so that they can be decrypted when running any kernel+initrd signed by the vendor\&. Such bindings may be created with the options
+\fB\-\-tpm2\-public\-key=\fR,
+\fB\-\-tpm2\-public\-key\-pcrs=\fR,
+\fB\-\-tpm2\-signature=\fR
+described below\&.
+.PP
+See
+\m[blue]\fBLinux TPM PCR Registry\fR\m[]\&\s-2\u[1]\d\s+2
+for an authoritative list of PCRs and how they are updated\&. The table below contains a quick reference, describing in particular the PCRs modified by systemd\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \&Well\-known PCR Definitions
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+PCR
+T}:T{
+name
+T}:T{
+Explanation
+T}
+.T&
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+0
+T}:T{
+platform\-code
+T}:T{
+Core system firmware executable code; changes on firmware updates
+T}
+T{
+1
+T}:T{
+platform\-config
+T}:T{
+Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements
+T}
+T{
+2
+T}:T{
+external\-code
+T}:T{
+Extended or pluggable executable code; includes option ROMs on pluggable hardware
+T}
+T{
+3
+T}:T{
+external\-config
+T}:T{
+Extended or pluggable firmware data; includes information about pluggable hardware
+T}
+T{
+4
+T}:T{
+boot\-loader\-code
+T}:T{
+Boot loader and additional drivers, PE binaries invoked by the boot loader; changes on boot loader updates\&. \fBsd-stub\fR(7) measures system extension images read from the ESP here too (see \fBsystemd-sysext\fR(8))\&.
+T}
+T{
+5
+T}:T{
+boot\-loader\-config
+T}:T{
+GPT/Partition table; changes when the partitions are added, modified, or removed
+T}
+T{
+7
+T}:T{
+secure\-boot\-policy
+T}:T{
+Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, \&...) changes\&.
+T}
+T{
+9
+T}:T{
+kernel\-initrd
+T}:T{
+The Linux kernel measures all initrds it receives into this PCR\&.
+T}
+T{
+10
+T}:T{
+ima
+T}:T{
+The IMA project measures its runtime state into this PCR\&.
+T}
+T{
+11
+T}:T{
+kernel\-boot
+T}:T{
+\fBsystemd-stub\fR(7) measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR\&. \fBsystemd-pcrphase.service\fR(8) measures boot phase strings into this PCR at various milestones of the boot process\&.
+T}
+T{
+12
+T}:T{
+kernel\-config
+T}:T{
+\fBsystemd-boot\fR(7) measures the kernel command line into this PCR\&. \fBsystemd-stub\fR(7) measures any manually specified kernel command line (i\&.e\&. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR\&.
+T}
+T{
+13
+T}:T{
+sysexts
+T}:T{
+\fBsystemd-stub\fR(7) measures any \fBsystemd-sysext\fR(8) images it passes to the booted kernel into this PCR\&.
+T}
+T{
+14
+T}:T{
+shim\-policy
+T}:T{
+The shim project measures its "MOK" certificates and hashes into this PCR\&.
+T}
+T{
+15
+T}:T{
+system\-identity
+T}:T{
+\fBsystemd-cryptsetup\fR(8) optionally measures the volume key of activated LUKS volumes into this PCR\&. \fBsystemd-pcrmachine.service\fR(8) measures the \fBmachine-id\fR(5) into this PCR\&. \fBsystemd-pcrfs@.service\fR(8) measures mount points, file system UUIDs, labels, partition UUIDs of the root and /var/ filesystems into this PCR\&.
+T}
+T{
+16
+T}:T{
+debug
+T}:T{
+Debug
+T}
+T{
+23
+T}:T{
+application\-support
+T}:T{
+Application Support
+T}
+.TE
+.sp 1
+.PP
+In general, encrypted volumes would be bound to some combination of PCRs 7, 11, and 14 (if shim/MOK is used)\&. In order to allow firmware and OS version updates, it is typically not advisable to use PCRs such as 0 and 2, since the program code they cover should already be covered indirectly through the certificates measured into PCR 7\&. Validation through certificates hashes is typically preferable over validation through direct measurements as it is less brittle in context of OS/firmware updates: the measurements will change on every update, but signatures should remain unchanged\&. See the
+\m[blue]\fBLinux TPM PCR Registry\fR\m[]\&\s-2\u[1]\d\s+2
+for more discussion\&.
+.SH "LIMITATIONS"
+.PP
+Note that currently when enrolling a new key of one of the five supported types listed above, it is required to first provide a passphrase, a recovery key or a FIDO2 token\&. It\*(Aqs currently not supported to unlock a device with a TPM2/PKCS#11 key in order to enroll a new TPM2/PKCS#11 key\&. Thus, if in future key roll\-over is desired it\*(Aqs generally recommended to ensure a passphrase, a recovery key or a FIDO2 token is always enrolled\&.
+.PP
+Also note that support for enrolling multiple FIDO2 tokens is currently limited\&. When multiple FIDO2 tokens are enrolled,
+\fBsystemd\-cryptseup\fR
+will perform pre\-flight requests to attempt to identify which of the enrolled tokens are currently plugged in\&. However, this is not possible for FIDO2 tokens with user verification (UV, usually via biometrics), in which case it will fall back to attempting each enrolled token one by one\&. This will result in multiple prompts for PIN and user verification\&. This limitation does not apply to PKCS#11 tokens\&.
+.SH "COMPATIBILITY"
+.PP
+Security technology both in systemd and in the general industry constantly evolves\&. In order to provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated in newer versions of systemd\&. Whenever this happens the following compatibility guarantees are given:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Old enrollments continue to be supported and may be unlocked with newer versions of
+\fBsystemd-cryptsetup@.service\fR(8)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The opposite is not guaranteed however: it might not be possible to unlock volumes with enrollments done with a newer version of
+\fBsystemd\-cryptenroll\fR
+with an older version of
+\fBsystemd\-cryptsetup\fR\&.
+.RE
+.PP
+That said, it is generally recommended to use matching versions of
+\fBsystemd\-cryptenroll\fR
+and
+\fBsystemd\-cryptsetup\fR, since this is best tested and supported\&.
+.PP
+It might be advisable to re\-enroll existing enrollments to take benefit of newer security features, as they are added to systemd\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-password\fR
+.RS 4
+Enroll a regular password/passphrase\&. This command is mostly equivalent to
+\fBcryptsetup luksAddKey\fR, however may be combined with
+\fB\-\-wipe\-slot=\fR
+in one call, see below\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-recovery\-key\fR
+.RS 4
+Enroll a recovery key\&. Recovery keys are mostly identical to passphrases, but are computer\-generated instead of being chosen by a human, and thus have a guaranteed high entropy\&. The key uses a character set that is easy to type in, and may be scanned off screen via a QR code\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-unlock\-key\-file=\fR\fIPATH\fR
+.RS 4
+Use a file instead of a password/passphrase read from stdin to unlock the volume\&. Expects the PATH to the file containing your key to unlock the volume\&. Currently there is nothing like
+\fB\-\-key\-file\-offset=\fR
+or
+\fB\-\-key\-file\-size=\fR
+so this file has to only contain the full key\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-unlock\-fido2\-device=\fR\fIPATH\fR
+.RS 4
+Use a FIDO2 device instead of a password/passphrase read from stdin to unlock the volume\&. Expects a
+hidraw
+device referring to the FIDO2 device (e\&.g\&.
+/dev/hidraw1)\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the device node of a currently plugged in security token (of which there must be exactly one)\&. This automatic discovery is unsupported if
+\fB\-\-fido2\-device=\fR
+option is also specified\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-pkcs11\-token\-uri=\fR\fIURI\fR
+.RS 4
+Enroll a PKCS#11 security token or smartcard (e\&.g\&. a YubiKey)\&. Expects a PKCS#11 smartcard URI referring to the token\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the URI of a currently plugged in security token (of which there must be exactly one)\&. The special value
+"list"
+may be used to enumerate all suitable PKCS#11 tokens currently plugged in\&. The security token must contain an RSA key pair which is used to encrypt the randomly generated key that is used to unlock the LUKS2 volume\&. The encrypted key is then stored in the LUKS2 JSON token header area\&.
+.sp
+In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the
+\fBpkcs11\-uri=\fR
+option in the respective
+/etc/crypttab
+line:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+myvolume /dev/sda1 \- pkcs11\-uri=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+See
+\fBcrypttab\fR(5)
+for a more comprehensive example of a
+\fBsystemd\-cryptenroll\fR
+invocation and its matching
+/etc/crypttab
+line\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-fido2\-credential\-algorithm=\fR\fISTRING\fR
+.RS 4
+Specify COSE algorithm used in credential generation\&. The default value is
+"es256"\&. Supported values are
+"es256",
+"rs256"
+and
+"eddsa"\&.
+.sp
+"es256"
+denotes ECDSA over NIST P\-256 with SHA\-256\&.
+"rs256"
+denotes 2048\-bit RSA with PKCS#1\&.5 padding and SHA\-256\&.
+"eddsa"
+denotes EDDSA over Curve25519 with SHA\-512\&.
+.sp
+Note that your authenticator may not support some algorithms\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-fido2\-device=\fR\fIPATH\fR
+.RS 4
+Enroll a FIDO2 security token that implements the
+"hmac\-secret"
+extension (e\&.g\&. a YubiKey)\&. Expects a
+hidraw
+device referring to the FIDO2 device (e\&.g\&.
+/dev/hidraw1)\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the device node of a currently plugged in security token (of which there must be exactly one)\&. This automatic discovery is unsupported if
+\fB\-\-unlock\-fido2\-device=\fR
+option is also specified\&. The special value
+"list"
+may be used to enumerate all suitable FIDO2 tokens currently plugged in\&. Note that many hardware security tokens that implement FIDO2 also implement the older PKCS#11 standard\&. Typically FIDO2 is preferable, given it\*(Aqs simpler to use and more modern\&.
+.sp
+In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the
+\fBfido2\-device=\fR
+option in the respective
+/etc/crypttab
+line:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+myvolume /dev/sda1 \- fido2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+See
+\fBcrypttab\fR(5)
+for a more comprehensive example of a
+\fBsystemd\-cryptenroll\fR
+invocation and its matching
+/etc/crypttab
+line\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-client\-pin=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require the user to enter a PIN when unlocking the volume (the FIDO2
+"clientPin"
+feature)\&. Defaults to
+"yes"\&. (Note: this setting is without effect if the security token does not support the
+"clientPin"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-user\-presence=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require the user to verify presence (tap the token, the FIDO2
+"up"
+feature) when unlocking the volume\&. Defaults to
+"yes"\&. (Note: this setting is without effect if the security token does not support the
+"up"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-fido2\-with\-user\-verification=\fR\fIBOOL\fR
+.RS 4
+When enrolling a FIDO2 security token, controls whether to require user verification when unlocking the volume (the FIDO2
+"uv"
+feature)\&. Defaults to
+"no"\&. (Note: this setting is without effect if the security token does not support the
+"uv"
+feature at all, or does not allow enabling or disabling it\&.)
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-tpm2\-device=\fR\fIPATH\fR
+.RS 4
+Enroll a TPM2 security chip\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
+/dev/tpmrm0)\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the device node of a currently discovered TPM2 device (of which there must be exactly one)\&. The special value
+"list"
+may be used to enumerate all suitable TPM2 devices currently discovered\&.
+.sp
+In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the
+\fBtpm2\-device=\fR
+option in the respective
+/etc/crypttab
+line:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+myvolume /dev/sda1 \- tpm2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+See
+\fBcrypttab\fR(5)
+for a more comprehensive example of a
+\fBsystemd\-cryptenroll\fR
+invocation and its matching
+/etc/crypttab
+line\&.
+.sp
+Use
+\fB\-\-tpm2\-pcrs=\fR
+(see below) to configure which TPM2 PCR indexes to bind the enrollment to\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-tpm2\-device\-key=\fR\fIPATH\fR
+.RS 4
+Enroll a TPM2 security chip using its public key\&. Expects a path referring to the TPM2 public key in TPM2B_PUBLIC format\&. This cannot be used with
+\fB\-\-tpm2\-device=\fR, as it performs the same operation, but without connecting to the TPM2 security chip; instead the enrollment is calculated using the provided TPM2 key\&. This is useful in situations where the TPM2 security chip is not available at the time of enrollment\&.
+.sp
+The key, in most cases, should be the Storage Root Key (SRK) from a local TPM2 security chip\&. If a key from a different handle (not the SRK) is used, you must specify its handle index using
+\fB\-\-tpm2\-seal\-key\-handle=\fR\&.
+.sp
+The
+\fBsystemd-tpm2-setup.service\fR(8)
+service writes the SRK to
+/run/systemd/tpm2\-srk\-public\-key\&.tpm2b_public
+automatically during boot, in the correct format\&.
+.sp
+Alternatively, you may use
+\fBsystemd\-analyze srk\fR
+to retrieve the SRK from the TPM2 security chip explicitly\&. See
+\fBsystemd-analyze\fR(1)
+for details\&. Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-analyze srk > srk\&.tpm2b_public
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-tpm2\-seal\-key\-handle=\fR\fIHANDLE\fR
+.RS 4
+Configures which parent key to use for sealing, using the TPM handle (index) of the key\&. This is used to "seal" (encrypt) a secret and must be used later to "unseal" (decrypt) the secret\&. Expects a hexadecimal 32bit integer, optionally prefixed with
+"0x"\&. Allowable values are any handle index in the persistent ("0x81000000"\-"0x81ffffff") or transient ("0x80000000"\-"0x80ffffff") ranges\&. Since transient handles are lost after a TPM reset, and may be flushed during TPM context switching, they should not be used except for very specific use cases, e\&.g\&. testing\&.
+.sp
+The default is the Storage Root Key (SRK) handle index
+"0x81000001"\&. A value of 0 will use the default\&. For the SRK handle, a new key will be created and stored in the TPM if one does not already exist; for any other handle, the key must already exist in the TPM at the specified handle index\&.
+.sp
+This should not be changed unless you know what you are doing\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-tpm2\-pcrs=\fR [PCR...]
+.RS 4
+Configures the TPM2 PCRs (Platform Configuration Registers) to bind to when enrollment is requested via
+\fB\-\-tpm2\-device=\fR\&. Takes a list of PCR entries, where each entry starts with a name or numeric index in the range 0\&...23, optionally followed by
+":"
+and a hash algorithm name (specifying the PCR bank), optionally followed by
+"="
+and a hash digest value\&. Multiple PCR entries are separated by
+"+"\&. If not specified, the default is to use PCR 7 only\&. If an empty string is specified, binds the enrollment to no PCRs at all\&. See the table above for a list of available PCRs\&.
+.sp
+Example:
+\fB\-\-tpm2\-pcrs=boot\-loader\-code+platform\-config+boot\-loader\-config\fR
+specifies that PCR registers 4, 1, and 5 should be used\&.
+.sp
+Example:
+\fB\-\-tpm2\-pcrs=7:sha256\fR
+specifies that PCR register 7 from the SHA256 bank should be used\&.
+.sp
+Example:
+\fB\-\-tpm2\-pcrs=4:sha1=3a3f780f11a4b49969fcaa80cd6e3957c33b2275\fR
+specifies that PCR register 4 from the SHA1 bank should be used, and a hash digest value of 3a3f780f11a4b49969fcaa80cd6e3957c33b2275 will be used instead of reading the current PCR value\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-tpm2\-with\-pin=\fR\fIBOOL\fR
+.RS 4
+When enrolling a TPM2 device, controls whether to require the user to enter a PIN when unlocking the volume in addition to PCR binding, based on TPM2 policy authentication\&. Defaults to
+"no"\&. Despite being called PIN, any character can be used, not just numbers\&.
+.sp
+Note that incorrect PIN entry when unlocking increments the TPM dictionary attack lockout mechanism, and may lock out users for a prolonged time, depending on its configuration\&. The lockout mechanism is a global property of the TPM,
+\fBsystemd\-cryptenroll\fR
+does not control or configure the lockout mechanism\&. You may use tpm2\-tss tools to inspect or configure the dictionary attack lockout, with
+\fBtpm2_getcap\fR(1)
+and
+\fBtpm2_dictionarylockout\fR(1)
+commands, respectively\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-\-tpm2\-public\-key=\fR [PATH], \fB\-\-tpm2\-public\-key\-pcrs=\fR [PCR...], \fB\-\-tpm2\-signature=\fR [PATH]
+.RS 4
+Configures a TPM2 signed PCR policy to bind encryption to\&. The
+\fB\-\-tpm2\-public\-key=\fR
+option accepts a path to a PEM encoded RSA public key, to bind the encryption to\&. If this is not specified explicitly, but a file
+tpm2\-pcr\-public\-key\&.pem
+exists in one of the directories
+/etc/systemd/,
+/run/systemd/,
+/usr/lib/systemd/
+(searched in this order), it is automatically used\&. The
+\fB\-\-tpm2\-public\-key\-pcrs=\fR
+option takes a list of TPM2 PCR indexes to bind to (same syntax as
+\fB\-\-tpm2\-pcrs=\fR
+described above)\&. If not specified defaults to 11 (i\&.e\&. this binds the policy to any unified kernel image for which a PCR signature can be provided)\&.
+.sp
+Note the difference between
+\fB\-\-tpm2\-pcrs=\fR
+and
+\fB\-\-tpm2\-public\-key\-pcrs=\fR: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided\&. The latter is hence more useful in scenarios where software updates shell be possible without losing access to all previously encrypted LUKS2 volumes\&. Like with
+\fB\-\-tpm2\-pcrs=\fR, names defined in the table above can also be used to specify the registers, for instance
+\fB\-\-tpm2\-public\-key\-pcrs=boot\-loader\-code+system\-identity\fR\&.
+.sp
+The
+\fB\-\-tpm2\-signature=\fR
+option takes a path to a TPM2 PCR signature file as generated by the
+\fBsystemd-measure\fR(1)
+tool\&. If this is not specified explicitly, a suitable signature file
+tpm2\-pcr\-signature\&.json
+is searched for in
+/etc/systemd/,
+/run/systemd/,
+/usr/lib/systemd/
+(in this order) and used\&. If a signature file is specified or found it is used to verify if the volume can be unlocked with it given the current PCR state, before the new slot is written to disk\&. This is intended as safety net to ensure that access to a volume is not lost if a public key is enrolled for which no valid signature for the current PCR state is available\&. If the supplied signature does not unlock the current PCR state and public key combination, no slot is enrolled and the operation will fail\&. If no signature file is specified or found no such safety verification is done\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-tpm2\-pcrlock=\fR [PATH]
+.RS 4
+Configures a TPM2 pcrlock policy to bind encryption to\&. Expects a path to a pcrlock policy file as generated by the
+\fBsystemd-pcrlock\fR(1)
+tool\&. If a TPM2 device is enrolled and this option is not used but a file
+pcrlock\&.json
+is found in
+/run/systemd/
+or
+/var/lib/systemd/
+it is automatically used\&. Assign an empty string to turn this behaviour off\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-wipe\-slot=\fR [SLOT...]
+.RS 4
+Wipes one or more LUKS2 key slots\&. Takes a comma separated list of numeric slot indexes, or the special strings
+"all"
+(for wiping all key slots),
+"empty"
+(for wiping all key slots that are unlocked by an empty passphrase),
+"password"
+(for wiping all key slots that are unlocked by a traditional passphrase),
+"recovery"
+(for wiping all key slots that are unlocked by a recovery key),
+"pkcs11"
+(for wiping all key slots that are unlocked by a PKCS#11 token),
+"fido2"
+(for wiping all key slots that are unlocked by a FIDO2 token),
+"tpm2"
+(for wiping all key slots that are unlocked by a TPM2 chip), or any combination of these strings or numeric indexes, in which case all slots matching either are wiped\&. As safety precaution an operation that wipes all slots without exception (so that the volume cannot be unlocked at all anymore, unless the volume key is known) is refused\&.
+.sp
+This switch may be used alone, in which case only the requested wipe operation is executed\&. It may also be used in combination with any of the enrollment options listed above, in which case the enrollment is completed first, and only when successful the wipe operation executed \(em and the newly added slot is always excluded from the wiping\&. Combining enrollment and slot wiping may thus be used to update existing enrollments:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-cryptenroll /dev/sda1 \-\-wipe\-slot=tpm2 \-\-tpm2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The above command will enroll the TPM2 chip, and then wipe all previously created TPM2 enrollments on the LUKS2 volume, leaving only the newly created one\&. Combining wiping and enrollment may also be used to replace enrollments of different types, for example for changing from a PKCS#11 enrollment to a FIDO2 one:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-cryptenroll /dev/sda1 \-\-wipe\-slot=pkcs11 \-\-fido2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Or for replacing an enrolled empty password by TPM2:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-cryptenroll /dev/sda1 \-\-wipe\-slot=empty \-\-tpm2\-device=auto
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "EXAMPLES"
+.PP
+\fBcrypttab\fR(5)
+and
+\fBsystemd-measure\fR(1)
+contain various examples employing
+\fBsystemd\-cryptenroll\fR\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-cryptsetup@.service\fR(8),
+\fBcrypttab\fR(5),
+\fBcryptsetup\fR(8),
+\fBsystemd-measure\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Linux TPM PCR Registry
+.RS 4
+\%https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-delta.1 b/upstream/mageia-cauldron/man1/systemd-delta.1
new file mode 100644
index 00000000..d874587b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-delta.1
@@ -0,0 +1,169 @@
+'\" t
+.TH "SYSTEMD\-DELTA" "1" "" "systemd 255" "systemd-delta"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-delta \- Find overridden configuration files
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-delta\fR\ 'u
+\fBsystemd\-delta\fR [OPTIONS...] [\fIPREFIX\fR[/\fISUFFIX\fR]|\fISUFFIX\fR...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-delta\fR
+may be used to identify and compare configuration files that override other configuration files\&. Files in
+/etc/
+have highest priority, files in
+/run/
+have the second highest priority, \&..., files in
+/usr/lib/
+have lowest priority\&. Files in a directory with higher priority override files with the same name in directories of lower priority\&. In addition, certain configuration files can have
+"\&.d"
+directories which contain "drop\-in" files with configuration snippets which augment the main configuration file\&. "Drop\-in" files can be overridden in the same way by placing files with the same name in a directory of higher priority (except that, in case of "drop\-in" files, both the "drop\-in" file name and the name of the containing directory, which corresponds to the name of the main configuration file, must match)\&. For a fuller explanation, see
+\fBsystemd.unit\fR(5)\&.
+.PP
+The command line argument will be split into a prefix and a suffix\&. Either is optional\&. The prefix must be one of the directories containing configuration files (/etc/,
+/run/,
+/usr/lib/, \&...)\&. If it is given, only overriding files contained in this directory will be shown\&. Otherwise, all overriding files will be shown\&. The suffix must be a name of a subdirectory containing configuration files like
+tmpfiles\&.d,
+sysctl\&.d
+or
+systemd/system\&. If it is given, only configuration files in this subdirectory (across all configuration paths) will be analyzed\&. Otherwise, all configuration files will be analyzed\&. If the command line argument is not given at all, all configuration files will be analyzed\&. See below for some examples\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-t\fR, \fB\-\-type=\fR
+.RS 4
+When listing the differences, only list those that are asked for\&. The list itself is a comma\-separated list of desired difference types\&.
+.sp
+Recognized types are:
+.PP
+\fImasked\fR
+.RS 4
+Show masked files
+.RE
+.PP
+\fIequivalent\fR
+.RS 4
+Show overridden files that while overridden, do not differ in content\&.
+.RE
+.PP
+\fIredirected\fR
+.RS 4
+Show files that are redirected to another\&.
+.RE
+.PP
+\fIoverridden\fR
+.RS 4
+Show overridden, and changed files\&.
+.RE
+.PP
+\fIextended\fR
+.RS 4
+Show
+*\&.conf
+files in drop\-in directories for units\&.
+.sp
+Added in version 205\&.
+.RE
+.PP
+\fIunchanged\fR
+.RS 4
+Show unmodified files too\&.
+.RE
+.sp
+.RE
+.PP
+\fB\-\-diff=\fR
+.RS 4
+When showing modified files, when a file is overridden show a diff as well\&. This option takes a boolean argument\&. If omitted, it defaults to
+\fBtrue\fR\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXAMPLES"
+.PP
+To see all local configuration:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-delta
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To see all runtime configuration:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-delta /run
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To see all system unit configuration changes:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-delta systemd/system
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To see all runtime "drop\-in" changes for system units:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-delta \-\-type=extended /run/systemd/system
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd.unit\fR(5)
diff --git a/upstream/mageia-cauldron/man1/systemd-detect-virt.1 b/upstream/mageia-cauldron/man1/systemd-detect-virt.1
new file mode 100644
index 00000000..1a0b04e5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-detect-virt.1
@@ -0,0 +1,358 @@
+'\" t
+.TH "SYSTEMD\-DETECT\-VIRT" "1" "" "systemd 255" "systemd-detect-virt"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-detect-virt \- Detect execution in a virtualized environment
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-detect\-virt\fR\ 'u
+\fBsystemd\-detect\-virt\fR [OPTIONS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-detect\-virt\fR
+detects execution in a virtualized environment\&. It identifies the virtualization technology and can distinguish full machine virtualization from container virtualization\&.
+systemd\-detect\-virt
+exits with a return value of 0 (success) if a virtualization technology is detected, and non\-zero (error) otherwise\&. By default, any type of virtualization is detected, and the options
+\fB\-\-container\fR
+and
+\fB\-\-vm\fR
+can be used to limit what types of virtualization are detected\&.
+.PP
+When executed without
+\fB\-\-quiet\fR
+will print a short identifier for the detected virtualization technology\&. The following technologies are currently identified:
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \&Known virtualization technologies (both VM, i\&.e\&. full hardware virtualization, and container, i\&.e\&. shared kernel virtualization)
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+Type
+T}:T{
+ID
+T}:T{
+Product
+T}
+.T&
+lt l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+l l l
+lt l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l
+^ l l.
+T{
+VM
+T}:T{
+\fIqemu\fR
+T}:T{
+QEMU software virtualization, without KVM
+T}
+:T{
+\fIkvm\fR
+T}:T{
+Linux KVM kernel virtual machine, in combination with QEMU\&. Not used for other virtualizers using the KVM interfaces, such as Oracle VirtualBox or Amazon EC2 Nitro, see below\&.
+T}
+:T{
+\fIamazon\fR
+T}:T{
+Amazon EC2 Nitro using Linux KVM
+T}
+:T{
+\fIzvm\fR
+T}:T{
+s390 z/VM
+T}
+:T{
+\fIvmware\fR
+T}:T{
+VMware Workstation or Server, and related products
+T}
+:T{
+\fImicrosoft\fR
+T}:T{
+Hyper\-V, also known as Viridian or Windows Server Virtualization
+T}
+:T{
+\fIoracle\fR
+T}:T{
+Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems), for legacy and KVM hypervisor
+T}
+:T{
+\fIpowervm\fR
+T}:T{
+IBM PowerVM hypervisor \(em comes as firmware with some IBM POWER servers
+T}
+:T{
+\fIxen\fR
+T}:T{
+Xen hypervisor (only domU, not dom0)
+T}
+:T{
+\fIbochs\fR
+T}:T{
+Bochs Emulator
+T}
+:T{
+\fIuml\fR
+T}:T{
+User\-mode Linux
+T}
+:T{
+\fIparallels\fR
+T}:T{
+Parallels Desktop, Parallels Server
+T}
+:T{
+\fIbhyve\fR
+T}:T{
+bhyve, FreeBSD hypervisor
+T}
+:T{
+\fIqnx\fR
+T}:T{
+QNX hypervisor
+T}
+:T{
+\fIacrn\fR
+T}:T{
+\m[blue]\fBACRN hypervisor\fR\m[]\&\s-2\u[1]\d\s+2
+T}
+:T{
+\fIapple\fR
+T}:T{
+\m[blue]\fBApple virtualization framework\fR\m[]\&\s-2\u[2]\d\s+2
+T}
+:T{
+\fIsre\fR
+T}:T{
+\m[blue]\fBLMHS SRE hypervisor\fR\m[]\&\s-2\u[3]\d\s+2
+T}
+T{
+\fIgoogle\fR
+T}:T{
+\m[blue]\fBGoogle Compute Engine\fR\m[]\&\s-2\u[4]\d\s+2
+T}:T{
+\ \&
+T}
+T{
+Container
+T}:T{
+\fIopenvz\fR
+T}:T{
+OpenVZ/Virtuozzo
+T}
+:T{
+\fIlxc\fR
+T}:T{
+Linux container implementation by LXC
+T}
+:T{
+\fIlxc\-libvirt\fR
+T}:T{
+Linux container implementation by libvirt
+T}
+:T{
+\fIsystemd\-nspawn\fR
+T}:T{
+systemd\*(Aqs minimal container implementation, see \fBsystemd-nspawn\fR(1)
+T}
+:T{
+\fIdocker\fR
+T}:T{
+Docker container manager
+T}
+:T{
+\fIpodman\fR
+T}:T{
+\m[blue]\fBPodman\fR\m[]\&\s-2\u[5]\d\s+2 container manager
+T}
+:T{
+\fIrkt\fR
+T}:T{
+rkt app container runtime
+T}
+:T{
+\fIwsl\fR
+T}:T{
+\m[blue]\fBWindows Subsystem for Linux\fR\m[]\&\s-2\u[6]\d\s+2
+T}
+:T{
+\fIproot\fR
+T}:T{
+\m[blue]\fBproot\fR\m[]\&\s-2\u[7]\d\s+2 userspace chroot/bind mount emulation
+T}
+:T{
+\fIpouch\fR
+T}:T{
+\m[blue]\fBPouch\fR\m[]\&\s-2\u[8]\d\s+2 Container Engine
+T}
+.TE
+.sp 1
+.PP
+If multiple virtualization solutions are used, only the "innermost" is detected and identified\&. That means if both machine and container virtualization are used in conjunction, only the latter will be identified (unless
+\fB\-\-vm\fR
+is passed)\&.
+.PP
+Windows Subsystem for Linux is not a Linux container, but an environment for running Linux userspace applications on top of the Windows kernel using a Linux\-compatible interface\&. WSL is categorized as a container for practical purposes\&. Multiple WSL environments share the same kernel and services should generally behave like when being run in a container\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-c\fR, \fB\-\-container\fR
+.RS 4
+Only detects container virtualization (i\&.e\&. shared kernel virtualization)\&.
+.RE
+.PP
+\fB\-v\fR, \fB\-\-vm\fR
+.RS 4
+Only detects hardware virtualization\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-chroot\fR
+.RS 4
+Detect whether invoked in a
+\fBchroot\fR(2)
+environment\&. In this mode, no output is written, but the return value indicates whether the process was invoked in a
+\fBchroot()\fR
+environment or not\&.
+.sp
+Added in version 228\&.
+.RE
+.PP
+\fB\-\-private\-users\fR
+.RS 4
+Detect whether invoked in a user namespace\&. In this mode, no output is written, but the return value indicates whether the process was invoked inside of a user namespace or not\&. See
+\fBuser_namespaces\fR(7)
+for more information\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-cvm\fR
+.RS 4
+Detect whether invoked in a confidential virtual machine\&. The result of this detection may be used to disable features that should not be used in confidential VMs\&. It must not be used to release security sensitive information\&. The latter must only be released after attestation of the confidential environment\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Suppress output of the virtualization technology identifier\&.
+.RE
+.PP
+\fB\-\-list\fR
+.RS 4
+Output all currently known and detectable container and VM environments\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-list\-cvm\fR
+.RS 4
+Output all currently known and detectable confidential virtualization technologies\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+If a virtualization technology is detected, 0 is returned, a non\-zero code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-nspawn\fR(1),
+\fBchroot\fR(2),
+\fBnamespaces\fR(7)
+.SH "NOTES"
+.IP " 1." 4
+ACRN hypervisor
+.RS 4
+\%https://projectacrn.org
+.RE
+.IP " 2." 4
+Apple virtualization framework
+.RS 4
+\%https://developer.apple.com/documentation/virtualization
+.RE
+.IP " 3." 4
+LMHS SRE hypervisor
+.RS 4
+\%https://www.lockheedmartin.com/en-us/products/Hardened-Security-for-Intel-Processors.html
+.RE
+.IP " 4." 4
+Google Compute Engine
+.RS 4
+\%https://cloud.google.com/compute
+.RE
+.IP " 5." 4
+Podman
+.RS 4
+\%https://podman.io
+.RE
+.IP " 6." 4
+Windows Subsystem for Linux
+.RS 4
+\%https://docs.microsoft.com/en-us/windows/wsl/about
+.RE
+.IP " 7." 4
+proot
+.RS 4
+\%https://proot-me.github.io/
+.RE
+.IP " 8." 4
+Pouch
+.RS 4
+\%https://github.com/alibaba/pouch
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-dissect.1 b/upstream/mageia-cauldron/man1/systemd-dissect.1
new file mode 100644
index 00000000..994c72a0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-dissect.1
@@ -0,0 +1,629 @@
+'\" t
+.TH "SYSTEMD\-DISSECT" "1" "" "systemd 255" "systemd-dissect"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-dissect, mount.ddi \- Dissect Discoverable Disk Images (DDIs)
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fIIMAGE\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fIIMAGE\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-mount\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\fB\ \fR\fB\fIPATH\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-mount\fR\fR\fB \fR\fB\fIIMAGE\fR\fR\fB \fR\fB\fIPATH\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-umount\fR\fR\fB\ \fR\fB\fIPATH\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-umount\fR\fR\fB \fR\fB\fIPATH\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-attach\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-attach\fR\fR\fB \fR\fB\fIIMAGE\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-detach\fR\fR\fB\ \fR\fB\fIPATH\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-detach\fR\fR\fB \fR\fB\fIPATH\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-list\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-list\fR\fR\fB \fR\fB\fIIMAGE\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-mtree\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-mtree\fR\fR\fB \fR\fB\fIIMAGE\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-with\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\fB\ \fR\fB[\fICOMMAND\fR...]\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-with\fR\fR\fB \fR\fB\fIIMAGE\fR\fR\fB \fR\fB[\fICOMMAND\fR...]\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-copy\-from\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\fB\ \fR\fB\fIPATH\fR\fR\fB\ \fR\fB[\fITARGET\fR]\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-copy\-from\fR\fR\fB \fR\fB\fIIMAGE\fR\fR\fB \fR\fB\fIPATH\fR\fR\fB \fR\fB[\fITARGET\fR]\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-copy\-to\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\fB\ \fR\fB[\fISOURCE\fR]\fR\fB\ \fR\fB\fIPATH\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-copy\-to\fR\fR\fB \fR\fB\fIIMAGE\fR\fR\fB \fR\fB[\fISOURCE\fR]\fR\fB \fR\fB\fIPATH\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-discover\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-discover\fR\fR
+.HP \w'\fBsystemd\-dissect\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB\fB\-\-validate\fR\fR\fB\ \fR\fB\fIIMAGE\fR\fR\ 'u
+\fBsystemd\-dissect \fR\fB[OPTIONS...]\fR\fB \fR\fB\fB\-\-validate\fR\fR\fB \fR\fB\fIIMAGE\fR\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-dissect\fR
+is a tool for introspecting and interacting with file system OS disk images, specifically Discoverable Disk Images (DDIs)\&. It supports four different operations:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+Show general OS image information, including the image\*(Aqs
+\fBos-release\fR(5)
+data, machine ID, partition information and more\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+Mount an OS image to a local directory\&. In this mode it will dissect the OS image and mount the included partitions according to their designation onto a directory and possibly sub\-directories\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+Unmount an OS image from a local directory\&. In this mode it will recursively unmount the mounted partitions and remove the underlying loop device, including all the partition sub\-devices\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+Copy files and directories in and out of an OS image\&.
+.RE
+.PP
+The tool may operate on three types of OS images:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+OS disk images containing a GPT partition table envelope, with partitions marked according to the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+OS disk images containing just a plain file\-system without an enveloping partition table\&. (This file system is assumed to be the root file system of the OS\&.)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+OS disk images containing a GPT or MBR partition table, with a single partition only\&. (This partition is assumed to contain the root file system of the OS\&.)
+.RE
+.PP
+OS images may use any kind of Linux\-supported file systems\&. In addition they may make use of LUKS disk encryption, and contain Verity integrity information\&. Note that qualifying OS images may be booted with
+\fBsystemd-nspawn\fR(1)\*(Aqs
+\fB\-\-image=\fR
+switch, and be used as root file system for system service using the
+\fIRootImage=\fR
+unit file setting, see
+\fBsystemd.exec\fR(5)\&.
+.PP
+Note that the partition table shown when invoked without command switch (as listed below) does not necessarily show all partitions included in the image, but just the partitions that are understood and considered part of an OS disk image\&. Specifically, partitions of unknown types are ignored, as well as duplicate partitions (i\&.e\&. more than one per partition type), as are root and
+/usr/
+partitions of architectures not compatible with the local system\&. In other words: this tool will display what it operates with when mounting the image\&. To display the complete list of partitions use a tool such as
+\fBfdisk\fR(8)\&.
+.PP
+The
+\fBsystemd\-dissect\fR
+command may be invoked as
+\fBmount\&.ddi\fR
+in which case it implements the
+\fBmount\fR(8)
+"external helper" interface\&. This ensures disk images compatible with
+\fBsystemd\-dissect\fR
+can be mounted directly by
+\fBmount\fR
+and
+\fBfstab\fR(5)\&. For details see below\&.
+.SH "COMMANDS"
+.PP
+If neither of the command switches listed below are passed the specified disk image is opened and general information about the image and the contained partitions and their use is shown\&.
+.PP
+\fB\-\-mount\fR, \fB\-m\fR
+.RS 4
+Mount the specified OS image to the specified directory\&. This will dissect the image, determine the OS root file system \(em as well as possibly other partitions \(em and mount them to the specified directory\&. If the OS image contains multiple partitions marked with the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2
+multiple nested mounts are established\&. This command expects two arguments: a path to an image file and a path to a directory where to mount the image\&.
+.sp
+To unmount an OS image mounted like this use the
+\fB\-\-umount\fR
+operation\&.
+.sp
+When the OS image contains LUKS encrypted or Verity integrity protected file systems appropriate volumes are automatically set up and marked for automatic disassembly when the image is unmounted\&.
+.sp
+The OS image may either be specified as path to an OS image stored in a regular file or may refer to block device node (in the latter case the block device must be the "whole" device, i\&.e\&. not a partition device)\&. (The other supported commands described here support this, too\&.)
+.sp
+All mounted file systems are checked with the appropriate
+\fBfsck\fR(8)
+implementation in automatic fixing mode, unless explicitly turned off (\fB\-\-fsck=no\fR) or read\-only operation is requested (\fB\-\-read\-only\fR)\&.
+.sp
+Note that this functionality is also available in
+\fBmount\fR(8)
+via a command such as
+\fBmount \-t ddi myimage\&.raw targetdir/\fR, as well as in
+\fBfstab\fR(5)\&. For details, see below\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-M\fR
+.RS 4
+This is a shortcut for
+\fB\-\-mount \-\-mkdir\fR\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-umount\fR, \fB\-u\fR
+.RS 4
+Unmount an OS image from the specified directory\&. This command expects one argument: a directory where an OS image was mounted\&.
+.sp
+All mounted partitions will be recursively unmounted, and the underlying loop device will be removed, along with all its partition sub\-devices\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-U\fR
+.RS 4
+This is a shortcut for
+\fB\-\-umount \-\-rmdir\fR\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-attach\fR
+.RS 4
+Attach the specified disk image to an automatically allocated loopback block device, and print the path to the loopback block device to standard output\&. This is similar to an invocation of
+\fBlosetup \-\-find \-\-show\fR, but will validate the image as DDI before attaching, and derive the correct sector size to use automatically\&. Moreover, it ensures the per\-partition block devices are created before returning\&. Takes a path to a disk image file\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-detach\fR
+.RS 4
+Detach the specified disk image from a loopback block device\&. This undoes the effect of
+\fB\-\-attach\fR
+above\&. This expects either a path to a loopback block device as an argument, or the path to the backing image file\&. In the latter case it will automatically determine the right device to detach\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-list\fR, \fB\-l\fR
+.RS 4
+Prints the paths of all the files and directories in the specified OS image or directory to standard output\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-mtree\fR
+.RS 4
+Generates a BSD
+\fBmtree\fR(8)
+compatible file manifest of the specified disk image or directory\&. This is useful for comparing image contents in detail, including inode information and other metadata\&. While the generated manifest will contain detailed inode information, it currently excludes extended attributes, file system capabilities, MAC labels,
+\fBchattr\fR(1)
+file flags,
+\fBbtrfs\fR(5)
+subvolume information, and various other file metadata\&. File content information is shown via a SHA256 digest\&. Additional fields might be added in future\&. Note that inode information such as link counts, inode numbers and timestamps is excluded from the output on purpose, as it typically complicates reproducibility\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-with\fR
+.RS 4
+Runs the specified command with the specified OS image mounted\&. This will mount the image to a temporary directory, switch the current working directory to it, and invoke the specified command line as child process\&. Once the process ends it will unmount the image again, and remove the temporary directory\&. If no command is specified a shell is invoked\&. The image is mounted writable, use
+\fB\-\-read\-only\fR
+to switch to read\-only operation\&. The invoked process will have the
+\fI$SYSTEMD_DISSECT_ROOT\fR
+environment variable set, containing the absolute path name of the temporary mount point, i\&.e\&. the same directory that is set as the current working directory\&. It will also have the
+\fI$SYSTEMD_DISSECT_DEVICE\fR
+environment variable set, containing the absolute path name of the loop device the image was attached to\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-copy\-from\fR, \fB\-x\fR
+.RS 4
+Copies a file or directory from the specified OS image or directory into the specified location on the host file system\&. Expects three arguments: a path to an image file or directory, a source path (relative to the image\*(Aqs root directory) and a destination path (relative to the current working directory, or an absolute path, both outside of the image)\&. If the destination path is omitted or specified as dash ("\-"), the specified file is written to standard output\&. If the source path in the image file system refers to a regular file it is copied to the destination path\&. In this case access mode, extended attributes and timestamps are copied as well, but file ownership is not\&. If the source path in the image refers to a directory, it is copied to the destination path, recursively with all containing files and directories\&. In this case the file ownership is copied too\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-copy\-to\fR, \fB\-a\fR
+.RS 4
+Copies a file or directory from the specified location in the host file system into the specified OS image or directory\&. Expects three arguments: a path to an image file or directory, a source path (relative to the current working directory, or an absolute path, both outside of the image) and a destination path (relative to the image\*(Aqs root directory)\&. If the source path is omitted or specified as dash ("\-"), the data to write is read from standard input\&. If the source path in the host file system refers to a regular file, it is copied to the destination path\&. In this case access mode, extended attributes and timestamps are copied as well, but file ownership is not\&. If the source path in the host file system refers to a directory it is copied to the destination path, recursively with all containing files and directories\&. In this case the file ownership is copied too\&.
+.sp
+As with
+\fB\-\-mount\fR
+file system checks are implicitly run before the copy operation begins\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-discover\fR
+.RS 4
+Show a list of DDIs in well\-known directories\&. This will show machine, portable service and system/configuration extension disk images in the usual directories
+/usr/lib/machines/,
+/usr/lib/portables/,
+/usr/lib/confexts/,
+/var/lib/machines/,
+/var/lib/portables/,
+/var/lib/extensions/
+and so on\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-validate\fR
+.RS 4
+Validates the partition arrangement of a disk image (DDI), and ensures it matches the image policy specified via
+\fB\-\-image\-policy=\fR, if one is specified\&. This parses the partition table and probes the file systems in the image, but does not attempt to mount them (nor to set up disk encryption/authentication via LUKS/Verity)\&. It does this taking the configured image dissection policy into account\&. Since this operation does not mount file systems, this command \(en unlike all other commands implemented by this tool \(en requires no privileges other than the ability to access the specified file\&. Prints "OK" and returns zero if the image appears to be in order and matches the specified image dissection policy\&. Otherwise prints an error message and returns non\-zero\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-read\-only\fR, \fB\-r\fR
+.RS 4
+Operate in read\-only mode\&. By default
+\fB\-\-mount\fR
+will establish writable mount points\&. If this option is specified they are established in read\-only mode instead\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-fsck=no\fR
+.RS 4
+Turn off automatic file system checking\&. By default when an image is accessed for writing (by
+\fB\-\-mount\fR
+or
+\fB\-\-copy\-to\fR) the file systems contained in the OS image are automatically checked using the appropriate
+\fBfsck\fR(8)
+command, in automatic fixing mode\&. This behavior may be switched off using
+\fB\-\-fsck=no\fR\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-growfs=no\fR
+.RS 4
+Turn off automatic growing of accessed file systems to their partition size, if marked for that in the GPT partition table\&. By default when an image is accessed for writing (by
+\fB\-\-mount\fR
+or
+\fB\-\-copy\-to\fR) the file systems contained in the OS image are automatically grown to their partition sizes, if bit 59 in the GPT partition flags is set for partition types that are defined by the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. This behavior may be switched off using
+\fB\-\-growfs=no\fR\&. File systems are grown automatically on access if all of the following conditions are met:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+The file system is mounted writable
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+The file system currently is smaller than the partition it is contained in (and thus can be grown)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+The image contains a GPT partition table
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+The file system is stored on a partition defined by the Discoverable Partitions Specification
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+Bit 59 of the GPT partition flags for this partition is set, as per specification
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 6.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  6." 4.2
+.\}
+The
+\fB\-\-growfs=no\fR
+option is not passed\&.
+.RE
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-mkdir\fR
+.RS 4
+If combined with
+\fB\-\-mount\fR
+the directory to mount the OS image to is created if it is missing\&. Note that the directory is not automatically removed when the disk image is unmounted again\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-rmdir\fR
+.RS 4
+If combined with
+\fB\-\-umount\fR
+the specified directory where the OS image is mounted is removed after unmounting the OS image\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-discard=\fR
+.RS 4
+Takes one of
+"disabled",
+"loop",
+"all",
+"crypto"\&. If
+"disabled"
+the image is accessed with empty block discarding turned off\&. If
+"loop"
+discarding is enabled if operating on a regular file\&. If
+"crypt"
+discarding is enabled even on encrypted file systems\&. If
+"all"
+discarding is unconditionally enabled\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-in\-memory\fR
+.RS 4
+If specified an in\-memory copy of the specified disk image is used\&. This may be used to operate with write\-access on a (possibly read\-only) image, without actually modifying the original file\&. This may also be used in order to operate on a disk image without keeping the originating file system busy, in order to allow it to be unmounted\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-root\-hash=\fR, \fB\-\-root\-hash\-sig=\fR, \fB\-\-verity\-data=\fR
+.RS 4
+Configure various aspects of Verity data integrity for the OS image\&. Option
+\fB\-\-root\-hash=\fR
+specifies a hex\-encoded top\-level Verity hash to use for setting up the Verity integrity protection\&. Option
+\fB\-\-root\-hash\-sig=\fR
+specifies the path to a file containing a PKCS#7 signature for the hash\&. This signature is passed to the kernel during activation, which will match it against signature keys available in the kernel keyring\&. Option
+\fB\-\-verity\-data=\fR
+specifies a path to a file with the Verity data to use for the OS image, in case it is stored in a detached file\&. It is recommended to embed the Verity data directly in the image, using the Verity mechanisms in the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fB\-\-loop\-ref=\fR
+.RS 4
+Configures the "reference" string the kernel shall report as backing file for the loopback block device\&. While this is supposed to be a path or filename referencing the backing file, this is not enforced and the kernel accepts arbitrary free\-form strings, chosen by the user\&. Accepts arbitrary strings up to a length of 63 characters\&. This sets the kernel\*(Aqs
+"\&.lo_file_name"
+field for the block device\&. Note this is distinct from the
+/sys/class/block/loopX/loop/backing_file
+attribute file that always reports a path referring to the actual backing file\&. The latter is subject to mount namespace translation, the former is not\&.
+.sp
+This setting is particularly useful in combination with the
+\fB\-\-attach\fR
+command, as it allows later referencing the allocated loop device via
+/dev/disk/by\-loop\-ref/\&...
+symlinks\&. Example: first, set up the loopback device via
+\fBsystemd\-dissect attach \-\-loop\-ref=quux foo\&.raw\fR, and then reference it in a command via the specified filename:
+\fBcfdisk /dev/disk/by\-loop\-ref/quux\fR\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-mtree\-hash=no\fR
+.RS 4
+If combined with
+\fB\-\-mtree\fR, turns off inclusion of file hashes in the mtree output\&. This makes the
+\fB\-\-mtree\fR
+faster when operating on large images\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&. If the
+\fB\-\-with\fR
+command is used the exit status of the invoked command is propagated\&.
+.SH "INVOCATION AS /SBIN/MOUNT\&.DDI"
+.PP
+The
+\fBsystemd\-dissect\fR
+executable may be symlinked to
+/sbin/mount\&.ddi\&. If invoked through that it implements
+\fBmount\fR(8)\*(Aqs "external helper" interface for the (pseudo) file system type
+"ddi"\&. This means conformant disk images may be mounted directly via
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# mount \-t ddi myimage\&.raw targetdir/
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+in a fashion mostly equivalent to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-dissect \-\-mount myimage\&.raw targetdir/
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note that since a single DDI may contain multiple file systems it should later be unmounted with
+\fBumount \-R targetdir/\fR, for recursive operation\&.
+.PP
+This functionality is particularly useful to mount DDIs automatically at boot via simple
+/etc/fstab
+entries\&. For example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+/path/to/myimage\&.raw /images/myimage/ ddi defaults 0 0
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+When invoked this way the mount options
+"ro",
+"rw",
+"discard",
+"nodiscard"
+map to the corresponding options listed above (i\&.e\&.
+\fB\-\-read\-only\fR,
+\fB\-\-discard=all\fR,
+\fB\-\-discard=disabled\fR)\&. Mount options are
+\fInot\fR
+generically passed on to the file systems inside the images\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Generate a tarball from an OS disk image\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-dissect \-\-with foo\&.raw tar cz \&. >foo\&.tar\&.gz
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-nspawn\fR(1),
+\fBsystemd.exec\fR(5),
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2,
+\fBmount\fR(8),
+\fBumount\fR(8),
+\fBfdisk\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-escape.1 b/upstream/mageia-cauldron/man1/systemd-escape.1
new file mode 100644
index 00000000..a69c2c8d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-escape.1
@@ -0,0 +1,223 @@
+'\" t
+.TH "SYSTEMD\-ESCAPE" "1" "" "systemd 255" "systemd-escape"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-escape \- Escape strings for usage in systemd unit names
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-escape\fR\ 'u
+\fBsystemd\-escape\fR [OPTIONS...] [STRING...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-escape\fR
+may be used to escape strings for inclusion in systemd unit names\&. The command may be used to escape and to undo escaping of strings\&.
+.PP
+The command takes any number of strings on the command line, and will process them individually, one after another\&. It will output them separated by spaces to stdout\&.
+.PP
+By default, this command will escape the strings passed, unless
+\fB\-\-unescape\fR
+is passed which results in the inverse operation being applied\&. If
+\fB\-\-mangle\fR
+is given, a special mode of escaping is applied instead, which assumes the string is already escaped but will escape everything that appears obviously non\-escaped\&.
+.PP
+For details on the escaping and unescaping algorithms see the relevant section in
+\fBsystemd.unit\fR(5)\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-suffix=\fR
+.RS 4
+Appends the specified unit type suffix to the escaped string\&. Takes one of the unit types supported by systemd, such as
+"service"
+or
+"mount"\&. May not be used in conjunction with
+\fB\-\-template=\fR,
+\fB\-\-unescape\fR
+or
+\fB\-\-mangle\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-template=\fR
+.RS 4
+Inserts the escaped strings in a unit name template\&. Takes a unit name template such as
+foobar@\&.service\&. With
+\fB\-\-unescape\fR, expects instantiated unit names for this template and extracts and unescapes just the instance part\&. May not be used in conjunction with
+\fB\-\-suffix=\fR,
+\fB\-\-instance\fR
+or
+\fB\-\-mangle\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-path\fR, \fB\-p\fR
+.RS 4
+When escaping or unescaping a string, assume it refers to a file system path\&. This simplifies the path (leading, trailing, and duplicate
+"/"
+characters are removed, no\-op path
+"\&."
+components are removed, and for absolute paths, leading
+"\&.\&."
+components are removed)\&. After the simplification, the path must not contain
+"\&.\&."\&.
+.sp
+This is particularly useful for generating strings suitable for unescaping with the
+"%f"
+specifier in unit files, see
+\fBsystemd.unit\fR(5)\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-unescape\fR, \fB\-u\fR
+.RS 4
+Instead of escaping the specified strings, undo the escaping, reversing the operation\&. May not be used in conjunction with
+\fB\-\-suffix=\fR
+or
+\fB\-\-mangle\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-mangle\fR, \fB\-m\fR
+.RS 4
+Like
+\fB\-\-escape\fR, but only escape characters that are obviously not escaped yet, and possibly automatically append an appropriate unit type suffix to the string\&. May not be used in conjunction with
+\fB\-\-suffix=\fR,
+\fB\-\-template=\fR
+or
+\fB\-\-unescape\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-instance\fR
+.RS 4
+With
+\fB\-\-unescape\fR, unescape and print only the instance part of an instantiated unit name template\&. Results in an error for an uninstantiated template like
+ssh@\&.service
+or a non\-template name like
+ssh\&.service\&. Must be used in conjunction with
+\fB\-\-unescape\fR
+and may not be used in conjunction with
+\fB\-\-template\fR\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXAMPLES"
+.PP
+To escape a single string:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \*(AqHallöchen, Meister\*(Aq
+Hall\exc3\exb6chen\ex2c\ex20Meister
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To undo escaping on a single string:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \-u \*(AqHall\exc3\exb6chen\ex2c\ex20Meister\*(Aq
+Hallöchen, Meister
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To generate the mount unit for a path:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \-p \-\-suffix=mount "/tmp//waldi/foobar/"
+tmp\-waldi\-foobar\&.mount
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To generate instance names of three strings:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \-\-template=systemd\-nspawn@\&.service \*(AqMy Container 1\*(Aq \*(Aqcontainerb\*(Aq \*(Aqcontainer/III\*(Aq
+systemd\-nspawn@My\ex20Container\ex201\&.service systemd\-nspawn@containerb\&.service systemd\-nspawn@container\-III\&.service
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To extract the instance part of an instantiated unit:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \-u \-\-instance \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
+My Container 1
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+To extract the instance part of an instance of a particular template:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-escape \-u \-\-template=systemd\-nspawn@\&.service \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
+My Container 1
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd.unit\fR(5),
+\fBsystemctl\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-firstboot.1 b/upstream/mageia-cauldron/man1/systemd-firstboot.1
new file mode 100644
index 00000000..2b65a8ad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-firstboot.1
@@ -0,0 +1,475 @@
+'\" t
+.TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 255" "systemd-firstboot"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-firstboot, systemd-firstboot.service \- Initialize basic system settings on or before the first boot\-up of a system
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-firstboot\fR\ 'u
+\fBsystemd\-firstboot\fR [OPTIONS...]
+.PP
+systemd\-firstboot\&.service
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-firstboot\fR
+initializes basic system settings interactively during the first boot, or non\-interactively on an offline system image\&. The service is started during boot if
+\fIConditionFirstBoot=yes\fR
+is met, which essentially means that
+/etc/
+is unpopulated, see
+\fBsystemd.unit\fR(5)
+for details\&.
+.PP
+The following settings may be configured:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The machine ID of the system
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The system locale, more specifically the two locale variables
+\fILANG=\fR
+and
+\fILC_MESSAGES\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The system keyboard map
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The system time zone
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The system hostname
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The kernel command line used when installing kernel images
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The root user\*(Aqs password and shell
+.RE
+.PP
+Each of the fields may either be queried interactively by users, set non\-interactively on the tool\*(Aqs command line, or be copied from a host system that is used to set up the system image\&.
+.PP
+If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting\&.
+.PP
+Note that this tool operates directly on the file system and does not involve any running system services, unlike
+\fBlocalectl\fR(1),
+\fBtimedatectl\fR(1)
+or
+\fBhostnamectl\fR(1)\&. This allows
+\fBsystemd\-firstboot\fR
+to operate on mounted but not booted disk images and in early boot\&. It is not recommended to use
+\fBsystemd\-firstboot\fR
+on the running system after it has been set up\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-root=\fR\fB\fIroot\fR\fR
+.RS 4
+Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
+\fIroot\fR
+path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIpath\fR\fR
+.RS 4
+Takes a path to a disk image file or block device node\&. If specified all operations are applied to file system in the indicated disk image\&. This is similar to
+\fB\-\-root=\fR
+but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
+\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-locale=\fR\fB\fILOCALE\fR\fR, \fB\-\-locale\-messages=\fR\fB\fILOCALE\fR\fR
+.RS 4
+Sets the system locale, more specifically the
+\fILANG=\fR
+and
+\fILC_MESSAGES\fR
+settings\&. The argument should be a valid locale identifier, such as
+"de_DE\&.UTF\-8"\&. This controls the
+\fBlocale.conf\fR(5)
+configuration file\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-keymap=\fR\fB\fIKEYMAP\fR\fR
+.RS 4
+Sets the system keyboard layout\&. The argument should be a valid keyboard map, such as
+"de\-latin1"\&. This controls the
+"KEYMAP"
+entry in the
+\fBvconsole.conf\fR(5)
+configuration file\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-\-timezone=\fR\fB\fITIMEZONE\fR\fR
+.RS 4
+Sets the system time zone\&. The argument should be a valid time zone identifier, such as
+"Europe/Berlin"\&. This controls the
+\fBlocaltime\fR(5)
+symlink\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-hostname=\fR\fB\fIHOSTNAME\fR\fR
+.RS 4
+Sets the system hostname\&. The argument should be a hostname, compatible with DNS\&. This controls the
+\fBhostname\fR(5)
+configuration file\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-setup\-machine\-id\fR
+.RS 4
+Initialize the system\*(Aqs machine ID to a random ID\&. This controls the
+\fBmachine-id\fR(5)
+file\&.
+.sp
+This option only works in combination with
+\fB\-\-root=\fR
+or
+\fB\-\-image=\fR\&. On a running system,
+machine\-id
+is written by the manager with help from
+\fBsystemd-machine-id-commit.service\fR(8)\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-machine\-id=\fR\fB\fIID\fR\fR
+.RS 4
+Set the system\*(Aqs machine ID to the specified value\&. The same restrictions apply as to
+\fB\-\-setup\-machine\-id\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-root\-password=\fR\fB\fIPASSWORD\fR\fR, \fB\-\-root\-password\-file=\fR\fB\fIPATH\fR\fR, \fB\-\-root\-password\-hashed=\fR\fB\fIHASHED_PASSWORD\fR\fR
+.RS 4
+Sets the password of the system\*(Aqs root user\&. This creates/modifies the
+\fBpasswd\fR(5)
+and
+\fBshadow\fR(5)
+files\&. This setting exists in three forms:
+\fB\-\-root\-password=\fR
+accepts the password to set directly on the command line,
+\fB\-\-root\-password\-file=\fR
+reads it from a file and
+\fB\-\-root\-password\-hashed=\fR
+accepts an already hashed password on the command line\&. See
+\fBshadow\fR(5)
+for more information on the format of the hashed password\&. Note that it is not recommended to specify plaintext passwords on the command line, as other users might be able to see them simply by invoking
+\fBps\fR(1)\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-root\-shell=\fR\fB\fISHELL\fR\fR
+.RS 4
+Sets the shell of the system\*(Aqs root user\&. This creates/modifies the
+\fBpasswd\fR(5)
+file\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-kernel\-command\-line=\fR\fB\fICMDLINE\fR\fR
+.RS 4
+Sets the system\*(Aqs kernel command line\&. This controls the
+/etc/kernel/cmdline
+file which is used by
+\fBkernel-install\fR(8)\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-prompt\-locale\fR, \fB\-\-prompt\-keymap\fR, \fB\-\-prompt\-timezone\fR, \fB\-\-prompt\-hostname\fR, \fB\-\-prompt\-root\-password\fR, \fB\-\-prompt\-root\-shell\fR
+.RS 4
+Prompt the user interactively for a specific basic setting\&. Note that any explicit configuration settings specified on the command line take precedence, and the user is not prompted for it\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-prompt\fR
+.RS 4
+Query the user for locale, keymap, timezone, hostname, root\*(Aqs password, and root\*(Aqs shell\&. This is equivalent to specifying
+\fB\-\-prompt\-locale\fR,
+\fB\-\-prompt\-keymap\fR,
+\fB\-\-prompt\-timezone\fR,
+\fB\-\-prompt\-hostname\fR,
+\fB\-\-prompt\-root\-password\fR,
+\fB\-\-prompt\-root\-shell\fR
+in combination\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-copy\-locale\fR, \fB\-\-copy\-keymap\fR, \fB\-\-copy\-timezone\fR, \fB\-\-copy\-root\-password\fR, \fB\-\-copy\-root\-shell\fR
+.RS 4
+Copy a specific basic setting from the host\&. This only works in combination with
+\fB\-\-root=\fR
+or
+\fB\-\-image=\fR\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-copy\fR
+.RS 4
+Copy locale, keymap, time zone, root password and shell from the host\&. This is equivalent to specifying
+\fB\-\-copy\-locale\fR,
+\fB\-\-copy\-keymap\fR,
+\fB\-\-copy\-timezone\fR,
+\fB\-\-copy\-root\-password\fR,
+\fB\-\-copy\-root\-shell\fR
+in combination\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-force\fR
+.RS 4
+Write configuration even if the relevant files already exist\&. Without this option,
+\fBsystemd\-firstboot\fR
+doesn\*(Aqt modify or replace existing files\&. Note that when configuring the root account, even with this option,
+\fBsystemd\-firstboot\fR
+only modifies the entry of the
+"root"
+user, leaving other entries in
+/etc/passwd
+and
+/etc/shadow
+intact\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-reset\fR
+.RS 4
+If specified, all existing files that are configured by
+\fBsystemd\-firstboot\fR
+are removed\&. Note that the files are removed regardless of whether they\*(Aqll be configured with a new value or not\&. This operation ensures that the next boot of the image will be considered a first boot, and
+\fBsystemd\-firstboot\fR
+will prompt again to configure each of the removed files\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-delete\-root\-password\fR
+.RS 4
+Removes the password of the system\*(Aqs root user, enabling login as root without a password unless the root account is locked\&. Note that this is extremely insecure and hence this option should not be used lightly\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-welcome=\fR
+.RS 4
+Takes a boolean argument\&. By default when prompting the user for configuration options a brief welcome text is shown before the first question is asked\&. Pass false to this option to turn off the welcome text\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "CREDENTIALS"
+.PP
+\fBsystemd\-firstboot\fR
+supports the service credentials logic as implemented by
+\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
+(see
+\fBsystemd.exec\fR(5)
+for details)\&. The following credentials are used when passed in:
+.PP
+\fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
+.RS 4
+A hashed or plaintext version of the root password to use, in place of prompting the user\&. These credentials are equivalent to the same ones defined for the
+\fBsystemd-sysusers.service\fR(8)
+service\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fIpasswd\&.shell\&.root\fR
+.RS 4
+Specifies the shell binary to use for the specified account\&. Equivalent to the credential of the same name defined for the
+\fBsystemd-sysusers.service\fR(8)
+service\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
+.RS 4
+These credentials specify the locale settings to set during first boot, in place of prompting the user\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fIfirstboot\&.keymap\fR
+.RS 4
+This credential specifies the keyboard setting to set during first boot, in place of prompting the user\&.
+.sp
+Note the relationship to the
+\fIvconsole\&.keymap\fR
+credential understood by
+\fBsystemd-vconsole-setup.service\fR(8): both ultimately affect the same setting, but
+\fIfirstboot\&.keymap\fR
+is written into
+/etc/vconsole\&.conf
+on first boot (if not already configured), and then read from there by
+\fBsystemd\-vconsole\-setup\fR, while
+\fIvconsole\&.keymap\fR
+is read on every boot, and is not persisted to disk (but any configuration in
+vconsole\&.conf
+will take precedence if present)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fIfirstboot\&.timezone\fR
+.RS 4
+This credential specifies the system timezone setting to set during first boot, in place of prompting the user\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+Note that by default the
+systemd\-firstboot\&.service
+unit file is set up to inherit the listed credentials from the service manager\&. Thus, when invoking a container with an unpopulated
+/etc/
+for the first time it is possible to configure the root user\*(Aqs password to be
+"systemd"
+like this:
+.PP
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-nspawn \-\-image=\&... \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note that these credentials are only read and applied during the first boot process\&. Once they are applied they remain applied for subsequent boots, and the credentials are not considered anymore\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "KERNEL COMMAND LINE"
+.PP
+\fIsystemd\&.firstboot=\fR
+.RS 4
+Takes a boolean argument, defaults to on\&. If off,
+systemd\-firstboot\&.service
+won\*(Aqt interactively query the user for basic settings at first boot, even if those settings are not initialized yet\&.
+.sp
+Added in version 233\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBlocale.conf\fR(5),
+\fBvconsole.conf\fR(5),
+\fBlocaltime\fR(5),
+\fBhostname\fR(5),
+\fBmachine-id\fR(5),
+\fBshadow\fR(5),
+\fBsystemd-machine-id-setup\fR(1),
+\fBlocalectl\fR(1),
+\fBtimedatectl\fR(1),
+\fBhostnamectl\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-id128.1 b/upstream/mageia-cauldron/man1/systemd-id128.1
new file mode 100644
index 00000000..79d82b32
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-id128.1
@@ -0,0 +1,185 @@
+'\" t
+.TH "SYSTEMD\-ID128" "1" "" "systemd 255" "systemd-id128"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-id128 \- Generate and print sd\-128 identifiers
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-id128\fR\ 'u
+\fBsystemd\-id128\fR [OPTIONS...] new
+.HP \w'\fBsystemd\-id128\fR\ 'u
+\fBsystemd\-id128\fR [OPTIONS...] machine\-id
+.HP \w'\fBsystemd\-id128\fR\ 'u
+\fBsystemd\-id128\fR [OPTIONS...] boot\-id
+.HP \w'\fBsystemd\-id128\fR\ 'u
+\fBsystemd\-id128\fR [OPTIONS...] invocation\-id
+.HP \w'\fBsystemd\-id128\fR\ 'u
+\fBsystemd\-id128\fR [OPTIONS...] show [NAME|UUID...]
+.SH "DESCRIPTION"
+.PP
+\fBid128\fR
+may be used to conveniently print
+\fBsd-id128\fR(3)
+UUIDs\&. What identifier is printed depends on the specific verb\&.
+.PP
+With
+\fBnew\fR, a new random identifier will be generated\&.
+.PP
+With
+\fBmachine\-id\fR, the identifier of the current machine will be printed\&. See
+\fBmachine-id\fR(5)\&.
+.PP
+With
+\fBboot\-id\fR, the identifier of the current boot will be printed\&.
+.PP
+With
+\fBinvocation\-id\fR, the identifier of the current service invocation will be printed\&. This is available in systemd services\&. See
+\fBsystemd.exec\fR(5)\&.
+.PP
+With
+\fBshow\fR, well\-known IDs are printed (for now, only GPT partition type UUIDs), along with brief identifier strings\&. When no arguments are specified, all known IDs are shown\&. When arguments are specified, they may be the identifiers or ID values of one or more known IDs, which are then printed with their name, or arbitrary IDs, which are then printed with a placeholder name\&. Combine with
+\fB\-\-uuid\fR
+to list the IDs in UUID style, i\&.e\&. the way GPT partition type UUIDs are usually shown\&.
+.PP
+\fBmachine\-id\fR,
+\fBboot\-id\fR, and
+\fBshow\fR
+may be combined with the
+\fB\-\-app\-specific=\fR\fB\fIapp\-id\fR\fR
+switch to generate application\-specific IDs\&. See
+\fBsd_id128_get_machine\fR(3)
+for the discussion when this is useful\&. Support for
+\fBshow \-\-app\-specific=\fR
+was added in version 255\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-p\fR, \fB\-\-pretty\fR
+.RS 4
+Generate output as programming language snippets\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-P\fR, \fB\-\-value\fR
+.RS 4
+Only print the value\&. May be combined with
+\fB\-u\fR/\fB\-\-uuid\fR\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-a \fR\fB\fIapp\-id\fR\fR, \fB\-\-app\-specific=\fR\fB\fIapp\-id\fR\fR
+.RS 4
+With this option, identifiers will be printed that are the result of hashing the application identifier
+\fIapp\-id\fR
+and another ID\&. The
+\fIapp\-id\fR
+argument must be a valid sd\-id128 string identifying the application\&. When used with
+\fBmachine\-id\fR, the other ID will be the machine ID as described in
+\fBmachine-id\fR(5), when used with
+\fBboot\-id\fR, the other ID will be the boot ID, and when used with
+\fBshow\fR, the other ID or IDs should be specified via the positional arguments\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-\-uuid\fR
+.RS 4
+Generate output as a UUID formatted in the "canonical representation", with five groups of digits separated by hyphens\&. See the Wikipedia entry for
+\m[blue]\fBUniversally Unique Identifiers\fR\m[]\&\s-2\u[1]\d\s+2
+for more discussion\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success 0 is returned, and a non\-zero failure code otherwise\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Show a well\-known UUID\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-id128 show \-\-value user\-home
+773f91ef66d449b5bd83d683bf40ad16
+
+$ systemd\-id128 show \-\-value \-\-uuid user\-home
+773f91ef\-66d4\-49b5\-bd83\-d683bf40ad16
+
+$ systemd\-id128 show 773f91ef\-66d4\-49b5\-bd83\-d683bf40ad16
+NAME      ID
+user\-home 773f91ef66d449b5bd83d683bf40ad16
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Generate an application\-specific UUID\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-id128 machine\-id \-u
+3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7
+
+$ systemd\-id128 new \-u
+1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
+
+$ systemd\-id128 machine\-id \-u \-a 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
+47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1
+
+$ systemd\-id128 \-Pu show 3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7 \e
+    \-a 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
+47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+On a given machine with the ID 3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7, for the application 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a, we generate an application\-specific machine ID (47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1)\&. If we want to later recreate the same calculation on a different machine, we need to specify both IDs explicitly as parameters to
+\fBshow\fR\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsd-id128\fR(3),
+\fBsd_id128_get_machine\fR(3)
+.SH "NOTES"
+.IP " 1." 4
+Universally Unique Identifiers
+.RS 4
+\%https://en.wikipedia.org/wiki/Universally_unique_identifier#Format
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-inhibit.1 b/upstream/mageia-cauldron/man1/systemd-inhibit.1
new file mode 100644
index 00000000..19950530
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-inhibit.1
@@ -0,0 +1,333 @@
+'\" t
+.TH "SYSTEMD\-INHIBIT" "1" "" "systemd 255" "systemd-inhibit"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-inhibit \- Execute a program with an inhibition lock taken
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-inhibit\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[COMMAND]\fR\fB\ \fR\fB[ARGUMENTS...]\fR\ 'u
+\fBsystemd\-inhibit \fR\fB[OPTIONS...]\fR\fB \fR\fB[COMMAND]\fR\fB \fR\fB[ARGUMENTS...]\fR
+.HP \w'\fBsystemd\-inhibit\ \fR\fB[OPTIONS...]\fR\fB\ \-\-list\fR\ 'u
+\fBsystemd\-inhibit \fR\fB[OPTIONS...]\fR\fB \-\-list\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-inhibit\fR
+may be used to execute a program with a shutdown, sleep, or idle inhibitor lock taken\&. The lock will be acquired before the specified command line is executed and released afterwards\&.
+.PP
+Inhibitor locks may be used to block or delay system sleep and shutdown requests from the user, as well as automatic idle handling of the OS\&. This is useful to avoid system suspends while an optical disc is being recorded, or similar operations that should not be interrupted\&.
+.PP
+For more information see the
+\m[blue]\fBInhibitor Lock Developer Documentation\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-what=\fR
+.RS 4
+Takes a colon\-separated list of one or more operations to inhibit:
+"shutdown",
+"sleep",
+"idle",
+"handle\-power\-key",
+"handle\-suspend\-key",
+"handle\-hibernate\-key",
+"handle\-lid\-switch", for inhibiting reboot/power\-off/halt/kexec/soft\-reboot, suspending/hibernating, the automatic idle detection, or the low\-level handling of the power/sleep key and the lid switch, respectively\&. If omitted, defaults to
+"idle:sleep:shutdown"\&.
+.RE
+.PP
+\fB\-\-who=\fR
+.RS 4
+Takes a short, human\-readable descriptive string for the program taking the lock\&. If not passed, defaults to the command line string\&.
+.RE
+.PP
+\fB\-\-why=\fR
+.RS 4
+Takes a short, human\-readable descriptive string for the reason for taking the lock\&. Defaults to "Unknown reason"\&.
+.RE
+.PP
+\fB\-\-mode=\fR
+.RS 4
+Takes either
+"block"
+or
+"delay"
+and describes how the lock is applied\&. If
+"block"
+is used (the default), the lock prohibits any of the requested operations without time limit, and only privileged users may override it\&. If
+"delay"
+is used, the lock can only delay the requested operations for a limited time\&. If the time elapses, the lock is ignored and the operation executed\&. The time limit may be specified in
+\fBlogind.conf\fR(5)\&. Note that
+"delay"
+is only available for
+"sleep"
+and
+"shutdown"\&.
+.RE
+.PP
+\fB\-\-list\fR
+.RS 4
+Lists all active inhibition locks instead of acquiring one\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+Returns the exit status of the executed program\&.
+.SH "EXAMPLE"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-inhibit wodim foobar\&.iso
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This burns the ISO image
+foobar\&.iso
+on a CD using
+\fBwodim\fR(1), and inhibits system sleeping, shutdown and idle while doing so\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBlogind.conf\fR(5)
+.SH "NOTES"
+.IP " 1." 4
+Inhibitor Lock Developer Documentation
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/systemd/inhibit
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-machine-id-setup.1 b/upstream/mageia-cauldron/man1/systemd-machine-id-setup.1
new file mode 100644
index 00000000..4dbbe6f3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-machine-id-setup.1
@@ -0,0 +1,185 @@
+'\" t
+.TH "SYSTEMD\-MACHINE\-ID\-SETUP" "1" "" "systemd 255" "systemd-machine-id-setup"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-machine-id-setup \- Initialize the machine ID in /etc/machine\-id
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-machine\-id\-setup\fR\ 'u
+\fBsystemd\-machine\-id\-setup\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-machine\-id\-setup\fR
+may be used by system installer tools to initialize the machine ID stored in
+/etc/machine\-id
+at install time, with a provisioned or randomly generated ID\&. See
+\fBmachine-id\fR(5)
+for more information about this file\&.
+.PP
+If the tool is invoked without the
+\fB\-\-commit\fR
+switch,
+/etc/machine\-id
+is initialized with a valid, new machine ID if it is missing or empty\&. The new machine ID will be acquired in the following fashion:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+If a valid D\-Bus machine ID is already configured for the system, the D\-Bus machine ID is copied and used to initialize the machine ID in
+/etc/machine\-id\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+If run inside a KVM virtual machine and a UUID is configured (via the
+\fB\-uuid\fR
+option), this UUID is used to initialize the machine ID\&. The caller must ensure that the UUID passed is sufficiently unique and is different for every booted instance of the VM\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+Similarly, if run inside a Linux container environment and a UUID is configured for the container, this is used to initialize the machine ID\&. For details, see the documentation of the
+\m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+Otherwise, a new ID is randomly generated\&.
+.RE
+.PP
+The
+\fB\-\-commit\fR
+switch may be used to commit a transient machined ID to disk, making it persistent\&. For details, see below\&.
+.PP
+Use
+\fBsystemd-firstboot\fR(1)
+to initialize the machine ID on mounted (but not booted) system images\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-root=\fR\fB\fIpath\fR\fR
+.RS 4
+Takes a directory path as argument\&. All paths operated on will be prefixed with the given alternate
+\fIroot\fR
+path, including the path for
+/etc/machine\-id
+itself\&.
+.sp
+Added in version 212\&.
+.RE
+.PP
+\fB\-\-image=\fR\fB\fIpath\fR\fR
+.RS 4
+Takes a path to a device node or regular file as argument\&. This is similar to
+\fB\-\-root=\fR
+as described above, but operates on a disk image instead of a directory tree\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to the
+"*"
+policy, i\&.e\&. all recognized file systems in the image are used\&.
+.RE
+.PP
+\fB\-\-commit\fR
+.RS 4
+Commit a transient machine ID to disk\&. This command may be used to convert a transient machine ID into a persistent one\&. A transient machine ID file is one that was bind mounted from a memory file system (usually
+"tmpfs") to
+/etc/machine\-id
+during the early phase of the boot process\&. This may happen because
+/etc/
+is initially read\-only and was missing a valid machine ID file at that point\&.
+.sp
+This command will execute no operation if
+/etc/machine\-id
+is not mounted from a memory file system, or if
+/etc/
+is read\-only\&. The command will write the current transient machine ID to disk and unmount the
+/etc/machine\-id
+mount point in a race\-free manner to ensure that this file is always valid and accessible for other processes\&.
+.sp
+This command is primarily used by the
+\fBsystemd-machine-id-commit.service\fR(8)
+early boot service\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-print\fR
+.RS 4
+Print the machine ID generated or committed after the operation is complete\&.
+.sp
+Added in version 231\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBmachine-id\fR(5),
+\fBsystemd-machine-id-commit.service\fR(8),
+\fBdbus-uuidgen\fR(1),
+\fBsystemd-firstboot\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+Container Interface
+.RS 4
+\%https://systemd.io/CONTAINER_INTERFACE
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-measure.1 b/upstream/mageia-cauldron/man1/systemd-measure.1
new file mode 100644
index 00000000..cbb356f3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-measure.1
@@ -0,0 +1,429 @@
+'\" t
+.TH "SYSTEMD\-MEASURE" "1" "" "systemd 255" "systemd-measure"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-measure \- Pre\-calculate and sign expected TPM2 PCR values for booted unified kernel images
+.SH "SYNOPSIS"
+.HP \w'\fB/usr/lib/systemd/systemd\-measure\ \fR\fB[OPTIONS...]\fR\ 'u
+\fB/usr/lib/systemd/systemd\-measure \fR\fB[OPTIONS...]\fR
+.SH "DESCRIPTION"
+.PP
+Note: this command is experimental for now\&. While it is likely to become a regular component of systemd, it might still change in behaviour and interface\&.
+.PP
+\fBsystemd\-measure\fR
+is a tool that may be used to pre\-calculate and sign the expected TPM2 PCR 11 values that should be seen when a Linux
+\m[blue]\fBUnified Kernel Image (UKI)\fR\m[]\&\s-2\u[1]\d\s+2
+based on
+\fBsystemd-stub\fR(7)
+is booted up\&. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel command line file,
+\fBos-release\fR(5)
+file, boot splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the PCR values expected to be in place after booting the image\&. Calculation starts with a zero\-initialized PCR 11, and is executed in a fashion compatible with what
+systemd\-stub
+does at boot\&. The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked if a certain set of kernels is booted, for which such a PCR signature can be provided\&.
+.PP
+It usually doesn\*(Aqt make sense to call this tool directly when constructing a UKI\&. Instead,
+\fBukify\fR(1)
+should be used; it will invoke
+\fBsystemd\-measure\fR
+and take care of embedding the resulting measurements into the UKI\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBstatus\fR
+.RS 4
+This is the default command if none is specified\&. This queries the local system\*(Aqs TPM2 PCR 11+12+13 values and displays them\&. The data is written in a similar format as the
+\fBcalculate\fR
+command below, and may be used to quickly compare expectation with reality\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fBcalculate\fR
+.RS 4
+Pre\-calculate the expected values seen in PCR register 11 after boot\-up of a unified kernel image consisting of the components specified with
+\fB\-\-linux=\fR,
+\fB\-\-osrel=\fR,
+\fB\-\-cmdline=\fR,
+\fB\-\-initrd=\fR,
+\fB\-\-splash=\fR,
+\fB\-\-dtb=\fR,
+\fB\-\-uname=\fR,
+\fB\-\-sbat=\fR,
+\fB\-\-pcrpkey=\fR
+see below\&. Only
+\fB\-\-linux=\fR
+is mandatory\&. (Alternatively, specify
+\fB\-\-current\fR
+to use the current values of PCR register 11 instead\&.)
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fBsign\fR
+.RS 4
+As with the
+\fBcalculate\fR
+command, pre\-calculate the expected value seen in TPM2 PCR register 11 after boot\-up of a unified kernel image\&. Then, cryptographically sign the resulting values with the private/public key pair (RSA) configured via
+\fB\-\-private\-key=\fR
+and
+\fB\-\-public\-key=\fR\&. This will write a JSON object to standard output that contains signatures for all specified PCR banks (see the
+\fB\-\-bank=\fR
+option below), which may be used to unlock encrypted credentials (see
+\fBsystemd-creds\fR(1)) or LUKS volumes (see
+\fBsystemd-cryptsetup@.service\fR(8))\&. This allows binding secrets to a set of kernels for which such PCR 11 signatures can be provided\&.
+.sp
+Note that a TPM2 device must be available for this signing to take place, even though the result is not tied to any TPM2 device or its state\&.
+.sp
+Added in version 252\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-linux=\fR\fB\fIPATH\fR\fR, \fB\-\-osrel=\fR\fB\fIPATH\fR\fR, \fB\-\-cmdline=\fR\fB\fIPATH\fR\fR, \fB\-\-initrd=\fR\fB\fIPATH\fR\fR, \fB\-\-splash=\fR\fB\fIPATH\fR\fR, \fB\-\-dtb=\fR\fB\fIPATH\fR\fR, \fB\-\-uname=\fR\fB\fIPATH\fR\fR, \fB\-\-sbat=\fR\fB\fIPATH\fR\fR, \fB\-\-pcrpkey=\fR\fB\fIPATH\fR\fR
+.RS 4
+When used with the
+\fBcalculate\fR
+or
+\fBsign\fR
+verb, configures the files to read the unified kernel image components from\&. Each option corresponds with the equally named section in the unified kernel PE file\&. The
+\fB\-\-linux=\fR
+switch expects the path to the ELF kernel file that the unified PE kernel will wrap\&. All switches except
+\fB\-\-linux=\fR
+are optional\&. Each option may be used at most once\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-current\fR
+.RS 4
+When used with the
+\fBcalculate\fR
+or
+\fBsign\fR
+verb, takes the PCR 11 values currently in effect for the system (which should typically reflect the hashes of the currently booted kernel)\&. This can be used in place of
+\fB\-\-linux=\fR
+and the other switches listed above\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-bank=\fR\fB\fIDIGEST\fR\fR
+.RS 4
+Controls the PCR banks to pre\-calculate the PCR values for \(en in case
+\fBcalculate\fR
+or
+\fBsign\fR
+is invoked \(en, or the banks to show in the
+\fBstatus\fR
+output\&. May be used more then once to specify multiple banks\&. If not specified, defaults to the four banks
+"sha1",
+"sha256",
+"sha384",
+"sha512"\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-private\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-public\-key=\fR\fB\fIPATH\fR\fR
+.RS 4
+These switches take paths to a pair of PEM encoded RSA key files, for use with the
+\fBsign\fR
+command\&.
+.sp
+Note the difference between the
+\fB\-\-pcrpkey=\fR
+and
+\fB\-\-public\-key=\fR
+switches\&. The former selects the data to include in the
+"\&.pcrpkey"
+PE section of the unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR 11 values\&. The former is the key that the booted system will likely use to lock disk and credential encryption to, the latter is the key used for unlocking such resources again\&. Hence, typically the same PEM key should be supplied in both cases\&.
+.sp
+If the
+\fB\-\-public\-key=\fR
+is not specified but
+\fB\-\-private\-key=\fR
+is specified the public key is automatically derived from the private key\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-tpm2\-device=\fR\fIPATH\fR
+.RS 4
+Controls which TPM2 device to use\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
+/dev/tpmrm0)\&. Alternatively the special value
+"auto"
+may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one)\&. The special value
+"list"
+may be used to enumerate all suitable TPM2 devices currently discovered\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-phase=\fR\fIPHASE\fR
+.RS 4
+Controls which boot phases to calculate expected PCR 11 values for\&. This takes a series of colon\-separated strings that encode boot "paths" for entering a specific phase of the boot process\&. Each of the specified strings is measured by the
+systemd\-pcrphase\-initrd\&.service,
+systemd\-pcrphase\-sysinit\&.service, and
+\fBsystemd-pcrphase.service\fR(8)
+into PCR 11 during different milestones of the boot process\&. This switch may be specified multiple times to calculate PCR values for multiple boot phases at once\&. If not used defaults to
+"enter\-initrd",
+"enter\-initrd:leave\-initrd",
+"enter\-initrd:leave\-initrd:sysinit",
+"enter\-initrd:leave\-initrd:sysinit:ready", i\&.e\&. calculates expected PCR values for the boot phase in the initrd, during early boot, during later boot, and during system runtime, but excluding the phases before the initrd or when shutting down\&. This setting is honoured both by
+\fBcalculate\fR
+and
+\fBsign\fR\&. When used with the latter it\*(Aqs particularly useful for generating PCR signatures that can only be used for unlocking resources during specific parts of the boot process\&.
+.sp
+For further details about PCR boot phases, see
+\fBsystemd-pcrphase.service\fR(8)\&.
+.sp
+Added in version 252\&.
+.RE
+.PP
+\fB\-\-append=\fR\fIPATH\fR
+.RS 4
+When generating a PCR JSON signature (via the
+\fBsign\fR
+command), combine it with a previously generated PCR JSON signature, and output it as one\&. The specified path must refer to a regular file that contains a valid JSON PCR signature object\&. The specified file is not modified\&. It will be read first, then the newly generated signature appended to it, and the resulting object is written to standard output\&. Use this to generate a single JSON object consisting from signatures made with a number of signing keys (for example, to have one key per boot phase)\&. The command will suppress duplicates: if a specific signature is already included in a JSON signature object it is not added a second time\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Shows output formatted as JSON\&. Expects one of
+"short"
+(for the shortest possible output without any redundant whitespace or line breaks),
+"pretty"
+(for a pretty version of the same, with indentation and line breaks) or
+"off"
+(to turn off JSON output, the default)\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Generate a unified kernel image, and calculate the expected TPM PCR 11 value\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ ukify \-\-output=vmlinux\&.efi \e
+     \-\-os\-release=@os\-release\&.txt \e
+     \-\-cmdline=@cmdline\&.txt \e
+     \-\-splash=splash\&.bmp \e
+     \-\-devicetree=devicetree\&.dtb \e
+     \-\-measure \e
+     vmlinux initrd\&.cpio
+11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
+11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
+11:sha384=1cf67dff4757e61e5\&.\&.\&.7f49ad720be02fd07263e1f93061243aec599d1ee4b4
+11:sha512=8e79acd3ddbbc8282\&.\&.\&.0c3e8ec0c714821032038f525f744960bcd082d937da
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBukify\fR(1)
+internally calls
+\fBsystemd\-measure\fR\&. The output with hashes is from
+\fBsystemd\-measure\fR\&.
+.PP
+\fBExample\ \&2.\ \&Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for it, and embed the signature and the public key in the image\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ openssl genpkey \-algorithm RSA \-pkeyopt rsa_keygen_bits:2048 \-out tpm2\-pcr\-private\&.pem
+\&.\&.+\&.+++++++++\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.+\&.\&.\&.\&.\&.+\&.+\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.
+$ openssl rsa \-pubout \-in tpm2\-pcr\-private\&.pem \-out tpm2\-pcr\-public\&.pem
+# systemd\-measure sign \e
+     \-\-linux=vmlinux \e
+     \-\-osrel=os\-release\&.txt \e
+     \-\-cmdline=cmdline\&.txt \e
+     \-\-initrd=initrd\&.cpio \e
+     \-\-splash=splash\&.bmp \e
+     \-\-dtb=devicetree\&.dtb \e
+     \-\-pcrpkey=tpm2\-pcr\-public\&.pem \e
+     \-\-bank=sha1 \e
+     \-\-bank=sha256 \e
+     \-\-private\-key=tpm2\-pcr\-private\&.pem \e
+     \-\-public\-key=tpm2\-pcr\-public\&.pem >tpm2\-pcr\-signature\&.json
+# ukify \-\-output=vmlinuz\&.efi \e
+     \-\-os\-release=@os\-release\&.txt \e
+     \-\-cmdline=@cmdline\&.txt \e
+     \-\-splash=splash\&.bmp \e
+     \-\-devicetree=devicetree\&.dtb \e
+     \-\-pcr\-private\-key=tpm2\-pcr\-private\&.pem \e
+     \-\-pcr\-public\-key=tpm2\-pcr\-public\&.pem \e
+     \-\-pcr\-banks=sha1,sha256 \e
+     vmlinux initrd\&.cpio
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Later on, enroll the signed PCR policy on a LUKS volume:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-cryptenroll \-\-tpm2\-device=auto \e
+     \-\-tpm2\-public\-key=tpm2\-pcr\-public\&.pem \e
+     \-\-tpm2\-signature=tpm2\-pcr\-signature\&.json \e
+     /dev/sda5
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+And then unlock the device with the signature:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-cryptsetup attach \e
+     volume5 /dev/sda5 \- \e
+     tpm2\-device=auto,tpm2\-signature=/path/to/tpm2\-pcr\-signature\&.json
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Note that when the generated unified kernel image
+vmlinux\&.efi
+is booted, the signature and public key files will be placed at locations
+\fBsystemd\-cryptenroll\fR
+and
+\fBsystemd\-cryptsetup\fR
+will look for anyway, and thus these paths do not actually need to be specified\&.
+.PP
+\fBExample\ \&3.\ \&Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase\fR
+.PP
+This example extends the previous one, but we now introduce a second signing key that is only used to sign PCR policies restricted to the initrd boot phase\&. This can be used to lock down root volumes in a way that they can only be unlocked before the transition to the host system\&. Thus we have two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the other that can only be used in the initrd\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ openssl genpkey \-algorithm RSA \-pkeyopt rsa_keygen_bits:2048 \-out tpm2\-pcr\-private\&.pem
+\&.+\&.\&.\&.\&.\&.\&.\&.\&.+\&.+\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.+\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.+\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.
+$ openssl rsa \-pubout \-in tpm2\-pcr\-private\&.pem \-out tpm2\-pcr\-public\&.pem
+$ openssl genpkey \-algorithm RSA \-pkeyopt rsa_keygen_bits:2048 \-out tpm2\-pcr\-initrd\-private\&.pem
+\&.\&.+\&.\&.\&.\&.\&.\&.\&.++\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.+\&.\&.\&.\&.+\&.\&.\&.\&.\&.+\&.+\&.\&.+\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.
+$ openssl rsa \-pubout \-in tpm2\-pcr\-initrd\-private\&.pem \-out tpm2\-pcr\-initrd\-public\&.pem
+# ukify \-\-output vmlinux\-1\&.2\&.3\&.efi \e
+     \-\-os\-release=@os\-release\&.txt \e
+     \-\-cmdline=@cmdline\&.txt \e
+     \-\-splash=splash\&.bmp \e
+     \-\-devicetree=devicetree\&.dtb \e
+     \-\-pcr\-private\-key=tpm2\-pcr\-private\&.pem \e
+     \-\-pcr\-public\-key=tpm2\-pcr\-public\&.pem \e
+     \-\-phases=enter\-initrd,enter\-initrd:leave\-initrd,enter\-initrd:leave\-initrd:sysinit,enter\-initrd:leave\-initrd:sysinit:ready \e
+     \-\-pcr\-banks=sha1,sha256 \e
+     \-\-pcr\-private\-key=tpm2\-pcr\-initrd\-private\&.pem \e
+     \-\-pcr\-public\-key=tpm2\-pcr\-initrd\-public\&.pem \e
+     \-\-phases=enter\-initrd \e
+     vmlinux\-1\&.2\&.3 initrd\&.cpio \e
+     \-\-uname=1\&.2\&.3
++ /usr/lib/systemd/systemd\-measure sign \-\-linux=vmlinux\-1\&.2\&.3 \e
+\-\-osrel=os\-release\&.txt \-\-cmdline=cmdline\&.txt \-\-dtb=devicetree\&.dtb \e
+\-\-splash=splash\&.bmp \-\-initrd=initrd\&.cpio \-\-bank=sha1 \-\-bank=sha256 \e
+\-\-private\-key=tpm2\-pcr\-private\&.pem \-\-public\-key=tpm2\-pcr\-public\&.pem \e
+\-\-phase=enter\-initrd \-\-phase=enter\-initrd:leave\-initrd \e
+\-\-phase=enter\-initrd:leave\-initrd:sysinit \e
+\-\-phase=enter\-initrd:leave\-initrd:sysinit:ready
++ /usr/lib/systemd/systemd\-measure sign \-\-linux=vmlinux\-1\&.2\&.3 \e
+\-\-osrel=os\-release\&.txt \-\-cmdline=cmdline\&.txt \-\-dtb=devicetree\&.dtb \e
+\-\-splash=splash\&.bmp \-\-initrd=initrd\&.cpio \-\-bank=sha1 \-\-bank=sha256 \e
+\-\-private\-key=tpm2\-pcr\-initrd\-private\&.pem \e
+\-\-public\-key=tpm2\-pcr\-initrd\-public\&.pem \e
+\-\-phase=enter\-initrd
+Wrote unsigned vmlinux\-1\&.2\&.3\&.efi
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBukify\fR
+prints out both invocations of
+\fBsystemd\-measure\fR
+as informative output (the lines starting with
+"+"); this allows us to see how
+\fBsystemd\-measure\fR
+is called\&. It then merges the output of both invocations into the
+"\&.pcrsig"
+section\&.
+\fBsystemd\-measure\fR
+may also do this merge itself using the
+\fB\-\-append=\fR
+option\&.
+.PP
+Note that in this example the
+"\&.pcrpkey"
+PE section contains the key specified by the first
+\fB\-\-pcr\-private\-key=\fR
+option, covering all boot phases\&. The
+"\&.pcrpkey"
+section is used in the default policies of
+\fBsystemd\-cryptenroll\fR
+and
+\fBsystemd\-creds\fR\&. To use the stricter policy bound to
+tpm\-pcr\-initrd\-public\&.pem, specify
+\fB\-\-tpm2\-public\-key=\fR
+on the command line of those tools\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-stub\fR(7),
+\fBukify\fR(1),
+\fBsystemd-creds\fR(1),
+\fBsystemd-cryptsetup@.service\fR(8),
+\fBsystemd-pcrphase.service\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Unified Kernel Image (UKI)
+.RS 4
+\%https://uapi-group.org/specifications/specs/unified_kernel_image/
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-mount.1 b/upstream/mageia-cauldron/man1/systemd-mount.1
new file mode 100644
index 00000000..22f5c0be
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-mount.1
@@ -0,0 +1,405 @@
+'\" t
+.TH "SYSTEMD\-MOUNT" "1" "" "systemd 255" "systemd-mount"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-mount, systemd-umount \- Establish and destroy transient mount or auto\-mount points
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-mount\fR\ 'u
+\fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fIWHAT\fR [\fIWHERE\fR]
+.HP \w'\fBsystemd\-mount\fR\ 'u
+\fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-tmpfs\fR [\fINAME\fR] \fIWHERE\fR
+.HP \w'\fBsystemd\-mount\fR\ 'u
+\fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-list\fR
+.HP \w'\fBsystemd\-mount\fR\ 'u
+\fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-umount\fR \fIWHAT|WHERE\fR...
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-mount\fR
+may be used to create and start a transient
+\&.mount
+or
+\&.automount
+unit of the file system
+\fIWHAT\fR
+on the mount point
+\fIWHERE\fR\&.
+.PP
+In many ways,
+\fBsystemd\-mount\fR
+is similar to the lower\-level
+\fBmount\fR(8)
+command, however instead of executing the mount operation directly and immediately,
+\fBsystemd\-mount\fR
+schedules it through the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system checker to execute a priori), and may make use of the auto\-mounting logic\&.
+.PP
+The command takes either one or two arguments\&. If only one argument is specified it should refer to a block device or regular file containing a file system (e\&.g\&.
+"/dev/sdb1"
+or
+"/path/to/disk\&.img")\&. The block device or image file is then probed for a file system label and other metadata, and is mounted to a directory below
+/run/media/system/
+whose name is generated from the file system label\&. In this mode the block device or image file must exist at the time of invocation of the command, so that it may be probed\&. If the device is found to be a removable block device (e\&.g\&. a USB stick), an automount point is created instead of a regular mount point (i\&.e\&. the
+\fB\-\-automount=\fR
+option is implied, see below)\&. If the option
+\fB\-\-tmpfs\fR
+is specified, then the argument is interpreted as the path where the new temporary file system shall be mounted\&.
+.PP
+If two arguments are specified, the first indicates the mount source (the
+\fIWHAT\fR) and the second indicates the path to mount it on (the
+\fIWHERE\fR)\&. In this mode no probing of the source is attempted, and a backing device node doesn\*(Aqt have to exist\&. However, if this mode is combined with
+\fB\-\-discover\fR, device node probing for additional metadata is enabled, and \(en much like in the single\-argument case discussed above \(en the specified device has to exist at the time of invocation of the command\&.
+.PP
+Use the
+\fB\-\-list\fR
+command to show a terse table of all local, known block devices with file systems that may be mounted with this command\&.
+.PP
+\fBsystemd\-umount\fR
+can be used to unmount a mount or automount point\&. It is the same as
+\fBsystemd\-mount\fR
+\fB\-\-umount\fR\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-block\fR
+.RS 4
+Do not synchronously wait for the requested operation to finish\&. If this is not specified, the job will be verified, enqueued and
+\fBsystemd\-mount\fR
+will wait until the mount or automount unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-full\fR
+.RS 4
+Do not ellipsize the output when
+\fB\-\-list\fR
+is specified\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.RE
+.PP
+\fB\-\-quiet\fR, \fB\-q\fR
+.RS 4
+Suppresses additional informational output while running\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-discover\fR
+.RS 4
+Enable probing of the mount source\&. This switch is implied if a single argument is specified on the command line\&. If passed, additional metadata is read from the device to enhance the unit to create\&. For example, a descriptive string for the transient units is generated from the file system label and device model\&. Moreover if a removable block device (e\&.g\&. USB stick) is detected an automount unit instead of a regular mount unit is created, with a short idle timeout, in order to ensure the file\-system is placed in a clean state quickly after each access\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-type=\fR, \fB\-t\fR
+.RS 4
+Specifies the file system type to mount (e\&.g\&.
+"vfat"
+or
+"ext4")\&. If omitted or set to
+"auto", the file system type is determined automatically\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-options=\fR, \fB\-o\fR
+.RS 4
+Additional mount options for the mount point\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-owner=\fR\fB\fIUSER\fR\fR
+.RS 4
+Let the specified user
+\fIUSER\fR
+own the mounted file system\&. This is done by appending
+\fBuid=\fR
+and
+\fBgid=\fR
+options to the list of mount options\&. Only certain file systems support this option\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-\-fsck=\fR
+.RS 4
+Takes a boolean argument, defaults to on\&. Controls whether to run a file system check immediately before the mount operation\&. In the automount case (see
+\fB\-\-automount=\fR
+below) the check will be run the moment the first access to the device is made, which might slightly delay the access\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-description=\fR
+.RS 4
+Provide a description for the mount or automount unit\&. See
+\fIDescription=\fR
+in
+\fBsystemd.unit\fR(5)\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-property=\fR, \fB\-p\fR
+.RS 4
+Sets a unit property for the mount unit that is created\&. This takes an assignment in the same format as
+\fBsystemctl\fR(1)\*(Aqs
+\fBset\-property\fR
+command\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-automount=\fR
+.RS 4
+Takes a boolean argument\&. Controls whether to create an automount point or a regular mount point\&. If true an automount point is created that is backed by the actual file system at the time of first access\&. If false a plain mount point is created that is backed by the actual file system immediately\&. Automount points have the benefit that the file system stays unmounted and hence in clean state until it is first accessed\&. In automount mode the
+\fB\-\-timeout\-idle\-sec=\fR
+switch (see below) may be used to ensure the mount point is unmounted automatically after the last access and an idle period passed\&.
+.sp
+If this switch is not specified it defaults to false\&. If not specified and
+\fB\-\-discover\fR
+is used (or only a single argument passed, which implies
+\fB\-\-discover\fR, see above), and the file system block device is detected to be removable, it is set to true, in order to increase the chance that the file system is in a fully clean state if the device is unplugged abruptly\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-A\fR
+.RS 4
+Equivalent to
+\fB\-\-automount=yes\fR\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-timeout\-idle\-sec=\fR
+.RS 4
+Takes a time value that controls the idle timeout in automount mode\&. If set to
+"infinity"
+(the default) no automatic unmounts are done\&. Otherwise the file system backing the automount point is detached after the last access and the idle timeout passed\&. See
+\fBsystemd.time\fR(7)
+for details on the time syntax supported\&. This option has no effect if only a regular mount is established, and automounting is not used\&.
+.sp
+Note that if
+\fB\-\-discover\fR
+is used (or only a single argument passed, which implies
+\fB\-\-discover\fR, see above), and the file system block device is detected to be removable,
+\fB\-\-timeout\-idle\-sec=1s\fR
+is implied\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-automount\-property=\fR
+.RS 4
+Similar to
+\fB\-\-property=\fR, but applies additional properties to the automount unit created, instead of the mount unit\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-bind\-device\fR
+.RS 4
+This option only has an effect in automount mode, and controls whether the automount unit shall be bound to the backing device\*(Aqs lifetime\&. If set, the automount unit will be stopped automatically when the backing device vanishes\&. By default the automount unit stays around, and subsequent accesses will block until backing device is replugged\&. This option has no effect in case of non\-device mounts, such as network or virtual file system mounts\&.
+.sp
+Note that if
+\fB\-\-discover\fR
+is used (or only a single argument passed, which implies
+\fB\-\-discover\fR, see above), and the file system block device is detected to be removable, this option is implied\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-\-list\fR
+.RS 4
+Instead of establishing a mount or automount point, print a terse list of block devices containing file systems that may be mounted with
+"systemd\-mount", along with useful metadata such as labels, etc\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-\-umount\fR
+.RS 4
+Stop the mount and automount units corresponding to the specified mount points
+\fIWHERE\fR
+or the devices
+\fIWHAT\fR\&.
+\fBsystemd\-mount\fR
+with this option or
+\fBsystemd\-umount\fR
+can take multiple arguments which can be mount points, devices,
+/etc/fstab
+style node names, or backing files corresponding to loop devices, like
+\fBsystemd\-mount \-\-umount /path/to/umount /dev/sda1 UUID=xxxxxx\-xxxx LABEL=xxxxx /path/to/disk\&.img\fR\&. Note that when
+\fB\-H\fR
+or
+\fB\-M\fR
+is specified, only absolute paths to mount points are supported\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-G\fR, \fB\-\-collect\fR
+.RS 4
+Unload the transient unit after it completed, even if it failed\&. Normally, without this option, all mount units that mount and failed are kept in memory until the user explicitly resets their failure state with
+\fBsystemctl reset\-failed\fR
+or an equivalent command\&. On the other hand, units that stopped successfully are unloaded immediately\&. If this option is turned on the "garbage collection" of units is more aggressive, and unloads units regardless if they exited successfully or failed\&. This option is a shortcut for
+\fB\-\-property=CollectMode=inactive\-or\-failed\fR, see the explanation for
+\fICollectMode=\fR
+in
+\fBsystemd.unit\fR(5)
+for further information\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-T\fR, \fB\-\-tmpfs\fR
+.RS 4
+Create and mount a new
+\fBtmpfs\fR
+file system on
+\fIWHERE\fR, with an optional
+\fINAME\fR
+that defaults to
+"tmpfs"\&.
+.sp
+The file system is mounted with the top\-level directory mode determined by the
+\fBumask\fR(2)
+setting of the caller, i\&.e\&.
+\fBrwxrwxrwx\fR
+masked by the umask of the caller\&. This matches what
+\fBmkdir\fR(1)
+does, but is different from the kernel default of
+"rwxrwxrwxt", i\&.e\&. a world\-writable directory with the sticky bit set\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-user\fR
+.RS 4
+Talk to the service manager of the calling user, rather than the service manager of the system\&.
+.RE
+.PP
+\fB\-\-system\fR
+.RS 4
+Talk to the service manager of the system\&. This is the implied default\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "THE UDEV DATABASE"
+.PP
+If
+\fB\-\-discover\fR
+is used,
+\fBsystemd\-mount\fR
+honors a couple of additional udev properties of block devices:
+.PP
+\fISYSTEMD_MOUNT_OPTIONS=\fR
+.RS 4
+The mount options to use, if
+\fB\-\-options=\fR
+is not used\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fISYSTEMD_MOUNT_WHERE=\fR
+.RS 4
+The file system path to place the mount point at, instead of the automatically generated one\&.
+.sp
+Added in version 232\&.
+.RE
+.SH "EXAMPLE"
+.PP
+Use a udev rule like the following to automatically mount all USB storage plugged in:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_USAGE}=="filesystem", \e
+        RUN{program}+="/usr/bin/systemd\-mount \-\-no\-block \-\-automount=yes \-\-collect $devnode"
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBmount\fR(8),
+\fBsystemctl\fR(1),
+\fBsystemd.unit\fR(5),
+\fBsystemd.mount\fR(5),
+\fBsystemd.automount\fR(5),
+\fBsystemd-run\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-notify.1 b/upstream/mageia-cauldron/man1/systemd-notify.1
new file mode 100644
index 00000000..a8f251e3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-notify.1
@@ -0,0 +1,275 @@
+'\" t
+.TH "SYSTEMD\-NOTIFY" "1" "" "systemd 255" "systemd-notify"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-notify \- Notify service manager about start\-up completion and other daemon status changes
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-notify\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[VARIABLE=VALUE...]\fR\ 'u
+\fBsystemd\-notify \fR\fB[OPTIONS...]\fR\fB \fR\fB[VARIABLE=VALUE...]\fR
+.HP \w'\fBsystemd\-notify\ \-\-exec\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[VARIABLE=VALUE...]\fR\fB\ ;\ \fR\fB[CMDLINE...]\fR\ 'u
+\fBsystemd\-notify \-\-exec \fR\fB[OPTIONS...]\fR\fB \fR\fB[VARIABLE=VALUE...]\fR\fB ; \fR\fB[CMDLINE...]\fR
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-notify\fR
+may be called by service scripts to notify the invoking service manager about status changes\&. It can be used to send arbitrary information, encoded in an environment\-block\-like list of strings\&. Most importantly, it can be used for start\-up completion notification\&.
+.PP
+This is mostly just a wrapper around
+\fBsd_notify()\fR
+and makes this functionality available to shell scripts\&. For details see
+\fBsd_notify\fR(3)\&.
+.PP
+The command line may carry a list of environment variables to send as part of the status update\&.
+.PP
+Note that systemd will refuse reception of status updates from this command unless
+\fINotifyAccess=\fR
+is appropriately set for the service unit this command is called from\&. See
+\fBsystemd.service\fR(5)
+for details\&.
+.PP
+Note that
+\fBsd_notify()\fR
+notifications may be attributed to units correctly only if either the sending process is still around at the time the service manager processes the message, or if the sending process is explicitly runtime\-tracked by the service manager\&. The latter is the case if the service manager originally forked off the process, i\&.e\&. on all processes that match
+\fINotifyAccess=\fR\fBmain\fR
+or
+\fINotifyAccess=\fR\fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an
+\fBsd_notify()\fR
+message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if
+\fINotifyAccess=\fR\fBall\fR
+is set for it\&. To address this
+\fBsystemd\-notify\fR
+will wait until the notification message has been processed by the service manager\&. When
+\fB\-\-no\-block\fR
+is used, this synchronization for reception of notifications is disabled, and hence the aforementioned race may occur if the invoking process is not the service manager or spawned by the service manager\&.
+.PP
+\fBsystemd\-notify\fR
+will first attempt to invoke
+\fBsd_notify()\fR
+pretending to have the PID of the parent process of
+\fBsystemd\-notify\fR
+(i\&.e\&. the invoking process)\&. This will only succeed when invoked with sufficient privileges\&. On failure, it will then fall back to invoking it under its own PID\&. This behaviour is useful in order that when the tool is invoked from a shell script the shell process \(em and not the
+\fBsystemd\-notify\fR
+process \(em appears as sender of the message, which in turn is helpful if the shell process is the main process of a service, due to the limitations of
+\fINotifyAccess=\fR\fBall\fR\&. Use the
+\fB\-\-pid=\fR
+switch to tweak this behaviour\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-ready\fR
+.RS 4
+Inform the invoking service manager about service start\-up or configuration reload completion\&. This is equivalent to
+\fBsystemd\-notify READY=1\fR\&. For details about the semantics of this option see
+\fBsd_notify\fR(3)\&.
+.RE
+.PP
+\fB\-\-reloading\fR
+.RS 4
+Inform the invoking service manager about the beginning of a configuration reload cycle\&. This is equivalent to
+\fBsystemd\-notify RELOADING=1\fR
+(but implicitly also sets a
+\fIMONOTONIC_USEC=\fR
+field as required for
+\fIType=notify\-reload\fR
+services, see
+\fBsystemd.service\fR(5)
+for details)\&. For details about the semantics of this option see
+\fBsd_notify\fR(3)\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-stopping\fR
+.RS 4
+Inform the invoking service manager about the beginning of the shutdown phase of the service\&. This is equivalent to
+\fBsystemd\-notify STOPPING=1\fR\&. For details about the semantics of this option see
+\fBsd_notify\fR(3)\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-pid=\fR
+.RS 4
+Inform the service manager about the main PID of the service\&. Takes a PID as argument\&. If the argument is specified as
+"auto"
+or omitted, the PID of the process that invoked
+\fBsystemd\-notify\fR
+is used, except if that\*(Aqs the service manager\&. If the argument is specified as
+"self", the PID of the
+\fBsystemd\-notify\fR
+command itself is used, and if
+"parent"
+is specified the calling process\*(Aq PID is used \(em even if it is the service manager\&. The latter is equivalent to
+\fBsystemd\-notify MAINPID=$PID\fR\&. For details about the semantics of this option see
+\fBsd_notify\fR(3)\&.
+.sp
+If this switch is used in an
+\fBsystemd\-notify\fR
+invocation from a process that shall become the new main process of a service \(em and which is not the process forked off by the service manager (or the current main process) \(em, then it is essential to set
+\fINotifyAccess=all\fR
+in the service unit file, or otherwise the notification will be ignored for security reasons\&. See
+\fBsystemd.service\fR(5)
+for details\&.
+.RE
+.PP
+\fB\-\-uid=\fR\fIUSER\fR
+.RS 4
+Set the user ID to send the notification from\&. Takes a UNIX user name or numeric UID\&. When specified the notification message will be sent with the specified UID as sender, in place of the user the command was invoked as\&. This option requires sufficient privileges in order to be able manipulate the user identity of the process\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-\-status=\fR
+.RS 4
+Send a free\-form human readable status string for the daemon to the service manager\&. This option takes the status string as argument\&. This is equivalent to
+\fBsystemd\-notify STATUS=\&...\fR\&. For details about the semantics of this option see
+\fBsd_notify\fR(3)\&. This information is shown in
+\fBsystemctl\fR(1)\*(Aqs
+\fBstatus\fR
+output, among other places\&.
+.RE
+.PP
+\fB\-\-booted\fR
+.RS 4
+Returns 0 if the system was booted up with systemd, non\-zero otherwise\&. If this option is passed, no message is sent\&. This option is hence unrelated to the other options\&. For details about the semantics of this option, see
+\fBsd_booted\fR(3)\&. An alternate way to check for this state is to call
+\fBsystemctl\fR(1)
+with the
+\fBis\-system\-running\fR
+command\&. It will return
+"offline"
+if the system was not booted with systemd\&.
+.RE
+.PP
+\fB\-\-no\-block\fR
+.RS 4
+Do not synchronously wait for the requested operation to finish\&. Use of this option is only recommended when
+\fBsystemd\-notify\fR
+is spawned by the service manager, or when the invoking process is directly spawned by the service manager and has enough privileges to allow
+\fBsystemd\-notify\fR
+to send the notification on its behalf\&. Sending notifications with this option set is prone to race conditions in all other cases\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-exec\fR
+.RS 4
+If specified
+\fBsystemd\-notify\fR
+will execute another command line after it completed its operation, replacing its own process\&. If used, the list of assignments to include in the message sent must be followed by a
+";"
+character (as separate argument), followed by the command line to execute\&. This permits "chaining" of commands, i\&.e\&. issuing one operation, followed immediately by another, without changing PIDs\&.
+.sp
+Note that many shells interpret
+";"
+as their own separator for command lines, hence when
+\fBsystemd\-notify\fR
+is invoked from a shell the semicolon must usually be escaped as
+"\e;"\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-fd=\fR
+.RS 4
+Send a file descriptor along with the notification message\&. This is useful when invoked in services that have the
+\fIFileDescriptorStoreMax=\fR
+setting enabled, see
+\fBsystemd.service\fR(5)
+for details\&. The specified file descriptor must be passed to
+\fBsystemd\-notify\fR
+when invoked\&. This option may be used multiple times to pass multiple file descriptors in a single notification message\&.
+.sp
+To use this functionality from a
+\fBbash\fR(1)
+shell, use an expression like the following:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-notify \-\-fd=4 \-\-fd=5 4</some/file 5</some/other/file
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-fdname=\fR
+.RS 4
+Set a name to assign to the file descriptors passed via
+\fB\-\-fd=\fR
+(see above)\&. This controls the
+"FDNAME="
+field\&. This setting may only be specified once, and applies to all file descriptors passed\&. Invoke this tool multiple times in case multiple file descriptors with different file descriptor names shall be submitted\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "EXAMPLE"
+.PP
+\fBExample\ \&1.\ \&Start\-up Notification and Status Updates\fR
+.PP
+A simple shell daemon that sends start\-up notifications after having set up its communication channel\&. During runtime it sends further status updates to the init system:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#!/bin/sh
+
+mkfifo /tmp/waldo
+systemd\-notify \-\-ready \-\-status="Waiting for data\&..."
+
+while : ; do
+        read \-r a < /tmp/waldo
+        systemd\-notify \-\-status="Processing $a"
+
+        # Do something with $a \&...
+
+        systemd\-notify \-\-status="Waiting for data\&..."
+done
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd.unit\fR(5),
+\fBsystemd.service\fR(5),
+\fBsd_notify\fR(3),
+\fBsd_booted\fR(3)
diff --git a/upstream/mageia-cauldron/man1/systemd-nspawn.1 b/upstream/mageia-cauldron/man1/systemd-nspawn.1
new file mode 100644
index 00000000..bfd09f6b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-nspawn.1
@@ -0,0 +1,2278 @@
+'\" t
+.TH "SYSTEMD\-NSPAWN" "1" "" "systemd 255" "systemd-nspawn"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-nspawn \- Spawn a command or OS in a light\-weight container
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-nspawn\fR\ 'u
+\fBsystemd\-nspawn\fR [OPTIONS...] [\fICOMMAND\fR\ [ARGS...]]
+.HP \w'\fBsystemd\-nspawn\fR\ 'u
+\fBsystemd\-nspawn\fR \-\-boot [OPTIONS...] [ARGS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-nspawn\fR
+may be used to run a command or OS in a light\-weight namespace container\&. In many ways it is similar to
+\fBchroot\fR(1), but more powerful since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and the host and domain name\&.
+.PP
+\fBsystemd\-nspawn\fR
+may be invoked on any directory tree containing an operating system tree, using the
+\fB\-\-directory=\fR
+command line option\&. By using the
+\fB\-\-machine=\fR
+option an OS tree is automatically searched for in a couple of locations, most importantly in
+/var/lib/machines/, the suggested directory to place OS container images installed on the system\&.
+.PP
+In contrast to
+\fBchroot\fR(1)\ \&\fBsystemd\-nspawn\fR
+may be used to boot full Linux\-based operating systems in a container\&.
+.PP
+\fBsystemd\-nspawn\fR
+limits access to various kernel interfaces in the container to read\-only, such as
+/sys/,
+/proc/sys/
+or
+/sys/fs/selinux/\&. The host\*(Aqs network interfaces and the system clock may not be changed from within the container\&. Device nodes may not be created\&. The host system cannot be rebooted and kernel modules may not be loaded from within the container\&.
+.PP
+Use a tool like
+\fBdnf\fR(8),
+\fBdebootstrap\fR(8), or
+\fBpacman\fR(8)
+to set up an OS directory tree suitable as file system hierarchy for
+\fBsystemd\-nspawn\fR
+containers\&. See the Examples section below for details on suitable invocation of these commands\&.
+.PP
+As a safety check
+\fBsystemd\-nspawn\fR
+will verify the existence of
+/usr/lib/os\-release
+or
+/etc/os\-release
+in the container tree before booting a container (see
+\fBos-release\fR(5))\&. It might be necessary to add this file to the container tree manually if the OS of the container is too old to contain this file out\-of\-the\-box\&.
+.PP
+\fBsystemd\-nspawn\fR
+may be invoked directly from the interactive command line or run as system service in the background\&. In this mode each container instance runs as its own service instance; a default template unit file
+systemd\-nspawn@\&.service
+is provided to make this easy, taking the container name as instance identifier\&. Note that different default options apply when
+\fBsystemd\-nspawn\fR
+is invoked by the template unit file than interactively on the command line\&. Most importantly the template unit file makes use of the
+\fB\-\-boot\fR
+option which is not the default in case
+\fBsystemd\-nspawn\fR
+is invoked from the interactive command line\&. Further differences with the defaults are documented along with the various supported options below\&.
+.PP
+The
+\fBmachinectl\fR(1)
+tool may be used to execute a number of operations on containers\&. In particular it provides easy\-to\-use commands to run containers as system services using the
+systemd\-nspawn@\&.service
+template unit file\&.
+.PP
+Along with each container a settings file with the
+\&.nspawn
+suffix may exist, containing additional settings to apply when running the container\&. See
+\fBsystemd.nspawn\fR(5)
+for details\&. Settings files override the default options used by the
+systemd\-nspawn@\&.service
+template unit file, making it usually unnecessary to alter this template file directly\&.
+.PP
+Note that
+\fBsystemd\-nspawn\fR
+will mount file systems private to the container to
+/dev/,
+/run/
+and similar\&. These will not be visible outside of the container, and their contents will be lost when the container exits\&.
+.PP
+Note that running two
+\fBsystemd\-nspawn\fR
+containers from the same directory tree will not make processes in them see each other\&. The PID namespace separation of the two containers is complete and the containers will share very few runtime objects except for the underlying file system\&. Rather use
+\fBmachinectl\fR(1)\*(Aqs
+\fBlogin\fR
+or
+\fBshell\fR
+commands to request an additional login session in a running container\&.
+.PP
+\fBsystemd\-nspawn\fR
+implements the
+\m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[1]\d\s+2
+specification\&.
+.PP
+While running, containers invoked with
+\fBsystemd\-nspawn\fR
+are registered with the
+\fBsystemd-machined\fR(8)
+service that keeps track of running containers, and provides programming interfaces to interact with them\&.
+.SH "OPTIONS"
+.PP
+If option
+\fB\-\-boot\fR
+is specified, the arguments are used as arguments for the init program\&. Otherwise,
+\fICOMMAND\fR
+specifies the program to launch in the container, and the remaining arguments are used as arguments for this program\&. If
+\fB\-\-boot\fR
+is not used and no arguments are specified, a shell is launched in the container\&.
+.PP
+The following options are understood:
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Turns off any status output by the tool itself\&. When this switch is used, the only output from nspawn will be the console output of the container OS itself\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-settings=\fR\fIMODE\fR
+.RS 4
+Controls whether
+\fBsystemd\-nspawn\fR
+shall search for and use additional per\-container settings from
+\&.nspawn
+files\&. Takes a boolean or the special values
+\fBoverride\fR
+or
+\fBtrusted\fR\&.
+.sp
+If enabled (the default), a settings file named after the machine (as specified with the
+\fB\-\-machine=\fR
+setting, or derived from the directory or image file name) with the suffix
+\&.nspawn
+is searched in
+/etc/systemd/nspawn/
+and
+/run/systemd/nspawn/\&. If it is found there, its settings are read and used\&. If it is not found there, it is subsequently searched in the same directory as the image file or in the immediate parent of the root directory of the container\&. In this case, if the file is found, its settings will be also read and used, but potentially unsafe settings are ignored\&. Note that in both these cases, settings on the command line take precedence over the corresponding settings from loaded
+\&.nspawn
+files, if both are specified\&. Unsafe settings are considered all settings that elevate the container\*(Aqs privileges or grant access to additional resources such as files or directories of the host\&. For details about the format and contents of
+\&.nspawn
+files, consult
+\fBsystemd.nspawn\fR(5)\&.
+.sp
+If this option is set to
+\fBoverride\fR, the file is searched, read and used the same way, however, the order of precedence is reversed: settings read from the
+\&.nspawn
+file will take precedence over the corresponding command line options, if both are specified\&.
+.sp
+If this option is set to
+\fBtrusted\fR, the file is searched, read and used the same way, but regardless of being found in
+/etc/systemd/nspawn/,
+/run/systemd/nspawn/
+or next to the image file or container root directory, all settings will take effect, however, command line arguments still take precedence over corresponding settings\&.
+.sp
+If disabled, no
+\&.nspawn
+file is read and no settings except the ones on the command line are in effect\&.
+.sp
+Added in version 226\&.
+.RE
+.SS "Image Options"
+.PP
+\fB\-D\fR, \fB\-\-directory=\fR
+.RS 4
+Directory to use as file system root for the container\&.
+.sp
+If neither
+\fB\-\-directory=\fR, nor
+\fB\-\-image=\fR
+is specified the directory is determined by searching for a directory named the same as the machine name specified with
+\fB\-\-machine=\fR\&. See
+\fBmachinectl\fR(1)
+section "Files and Directories" for the precise search path\&.
+.sp
+If neither
+\fB\-\-directory=\fR,
+\fB\-\-image=\fR, nor
+\fB\-\-machine=\fR
+are specified, the current directory will be used\&. May not be specified together with
+\fB\-\-image=\fR\&.
+.RE
+.PP
+\fB\-\-template=\fR
+.RS 4
+Directory or
+"btrfs"
+subvolume to use as template for the container\*(Aqs root directory\&. If this is specified and the container\*(Aqs root directory (as configured by
+\fB\-\-directory=\fR) does not yet exist it is created as
+"btrfs"
+snapshot (if supported) or plain directory (otherwise) and populated from this template tree\&. Ideally, the specified template path refers to the root of a
+"btrfs"
+subvolume, in which case a simple copy\-on\-write snapshot is taken, and populating the root directory is instant\&. If the specified template path does not refer to the root of a
+"btrfs"
+subvolume (or not even to a
+"btrfs"
+file system at all), the tree is copied (though possibly in a \*(Aqreflink\*(Aq copy\-on\-write scheme \(em if the file system supports that), which can be substantially more time\-consuming\&. Note that the snapshot taken is of the specified directory or subvolume, including all subdirectories and subvolumes below it, but excluding any sub\-mounts\&. May not be specified together with
+\fB\-\-image=\fR
+or
+\fB\-\-ephemeral\fR\&.
+.sp
+Note that this switch leaves hostname, machine ID and all other settings that could identify the instance unmodified\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-ephemeral\fR
+.RS 4
+If specified, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates\&. May not be specified together with
+\fB\-\-template=\fR\&.
+.sp
+Note that this switch leaves hostname, machine ID and all other settings that could identify the instance unmodified\&. Please note that \(em as with
+\fB\-\-template=\fR
+\(em taking the temporary snapshot is more efficient on file systems that support subvolume snapshots or \*(Aqreflinks\*(Aq natively ("btrfs"
+or new
+"xfs") than on more traditional file systems that do not ("ext4")\&. Note that the snapshot taken is of the specified directory or subvolume, including all subdirectories and subvolumes below it, but excluding any sub\-mounts\&.
+.sp
+With this option no modifications of the container image are retained\&. Use
+\fB\-\-volatile=\fR
+(described below) for other mechanisms to restrict persistency of container images during runtime\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-i\fR, \fB\-\-image=\fR
+.RS 4
+Disk image to mount the root directory for the container from\&. Takes a path to a regular file or to a block device node\&. The file or block device must contain either:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+An MBR partition table with a single partition of type 0x83 that is marked bootable\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A GUID partition table (GPT) with a single partition of type 0fc63daf\-8483\-4772\-8e79\-3d69d8477de4\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A GUID partition table (GPT) with a marked root partition which is mounted as the root directory of the container\&. Optionally, GPT images may contain a home and/or a server data partition which are mounted to the appropriate places in the container\&. All these partitions must be identified by the partition types defined by the
+\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+No partition table, and a single file system spanning the whole image\&.
+.RE
+.sp
+On GPT images, if an EFI System Partition (ESP) is discovered, it is automatically mounted to
+/efi
+(or
+/boot
+as fallback) in case a directory by this name exists and is empty\&.
+.sp
+Partitions encrypted with LUKS are automatically decrypted\&. Also, on GPT images dm\-verity data integrity hash partitions are set up if the root hash for them is specified using the
+\fB\-\-root\-hash=\fR
+option\&.
+.sp
+Single file system images (i\&.e\&. file systems without a surrounding partition table) can be opened using dm\-verity if the integrity data is passed using the
+\fB\-\-root\-hash=\fR
+and
+\fB\-\-verity\-data=\fR
+(and optionally
+\fB\-\-root\-hash\-sig=\fR) options\&.
+.sp
+Any other partitions, such as foreign partitions or swap partitions are not mounted\&. May not be specified together with
+\fB\-\-directory=\fR,
+\fB\-\-template=\fR\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
+.RS 4
+Takes an image policy string as argument, as per
+\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
+\fB\-\-image=\fR, see above\&. If not specified defaults to
+"root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent:home=encrypted+unprotected+absent:srv=encrypted+unprotected+absent:esp=unprotected+absent:xbootldr=unprotected+absent:tmp=encrypted+unprotected+absent:var=encrypted+unprotected+absent", i\&.e\&. all recognized file systems in the image are used, but not the swap partition\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-oci\-bundle=\fR
+.RS 4
+Takes the path to an OCI runtime bundle to invoke, as specified in the
+\m[blue]\fBOCI Runtime Specification\fR\m[]\&\s-2\u[3]\d\s+2\&. In this case no
+\&.nspawn
+file is loaded, and the root directory and various settings are read from the OCI runtime JSON data (but data passed on the command line takes precedence)\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-read\-only\fR
+.RS 4
+Mount the container\*(Aqs root file system (and any other file systems container in the container image) read\-only\&. This has no effect on additional mounts made with
+\fB\-\-bind=\fR,
+\fB\-\-tmpfs=\fR
+and similar options\&. This mode is implied if the container image file or directory is marked read\-only itself\&. It is also implied if
+\fB\-\-volatile=\fR
+is used\&. In this case the container image on disk is strictly read\-only, while changes are permitted but kept non\-persistently in memory only\&. For further details, see below\&.
+.RE
+.PP
+\fB\-\-volatile\fR, \fB\-\-volatile=\fR\fIMODE\fR
+.RS 4
+Boots the container in volatile mode\&. When no mode parameter is passed or when mode is specified as
+\fByes\fR, full volatile mode is enabled\&. This means the root directory is mounted as a mostly unpopulated
+"tmpfs"
+instance, and
+/usr/
+from the OS tree is mounted into it in read\-only mode (the system thus starts up with read\-only OS image, but pristine state and configuration, any changes are lost on shutdown)\&. When the mode parameter is specified as
+\fBstate\fR, the OS tree is mounted read\-only, but
+/var/
+is mounted as a writable
+"tmpfs"
+instance into it (the system thus starts up with read\-only OS resources and configuration, but pristine state, and any changes to the latter are lost on shutdown)\&. When the mode parameter is specified as
+\fBoverlay\fR
+the read\-only root file system is combined with a writable
+tmpfs
+instance through
+"overlayfs", so that it appears at it normally would, but any changes are applied to the temporary file system only and lost when the container is terminated\&. When the mode parameter is specified as
+\fBno\fR
+(the default), the whole OS tree is made available writable (unless
+\fB\-\-read\-only\fR
+is specified, see above)\&.
+.sp
+Note that if one of the volatile modes is chosen, its effect is limited to the root file system (or
+/var/
+in case of
+\fBstate\fR), and any other mounts placed in the hierarchy are unaffected \(em regardless if they are established automatically (e\&.g\&. the EFI system partition that might be mounted to
+/efi/
+or
+/boot/) or explicitly (e\&.g\&. through an additional command line option such as
+\fB\-\-bind=\fR, see below)\&. This means, even if
+\fB\-\-volatile=overlay\fR
+is used changes to
+/efi/
+or
+/boot/
+are prohibited in case such a partition exists in the container image operated on, and even if
+\fB\-\-volatile=state\fR
+is used the hypothetical file
+/etc/foobar
+is potentially writable if
+\fB\-\-bind=/etc/foobar\fR
+if used to mount it from outside the read\-only container
+/etc/
+directory\&.
+.sp
+The
+\fB\-\-ephemeral\fR
+option is closely related to this setting, and provides similar behaviour by making a temporary, ephemeral copy of the whole OS image and executing that\&. For further details, see above\&.
+.sp
+The
+\fB\-\-tmpfs=\fR
+and
+\fB\-\-overlay=\fR
+options provide similar functionality, but for specific sub\-directories of the OS image only\&. For details, see below\&.
+.sp
+This option provides similar functionality for containers as the
+"systemd\&.volatile="
+kernel command line switch provides for host systems\&. See
+\fBkernel-command-line\fR(7)
+for details\&.
+.sp
+Note that setting this option to
+\fByes\fR
+or
+\fBstate\fR
+will only work correctly with operating systems in the container that can boot up with only
+/usr/
+mounted, and are able to automatically populate
+/var/
+(and
+/etc/
+in case of
+"\-\-volatile=yes")\&. Specifically, this means that operating systems that follow the historic split of
+/bin/
+and
+/lib/
+(and related directories) from
+/usr/
+(i\&.e\&. where the former are not symlinks into the latter) are not supported by
+"\-\-volatile=yes"
+as container payload\&. The
+\fBoverlay\fR
+option does not require any particular preparations in the OS, but do note that
+"overlayfs"
+behaviour differs from regular file systems in a number of ways, and hence compatibility is limited\&.
+.sp
+Added in version 216\&.
+.RE
+.PP
+\fB\-\-root\-hash=\fR
+.RS 4
+Takes a data integrity (dm\-verity) root hash specified in hexadecimal\&. This option enables data integrity checks using dm\-verity, if the used image contains the appropriate integrity data (see above)\&. The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 formatted hexadecimal characters) long (in case of SHA256 for example)\&. If this option is not specified, but the image file carries the
+"user\&.verity\&.roothash"
+extended file attribute (see
+\fBxattr\fR(7)), then the root hash is read from it, also as formatted hexadecimal characters\&. If the extended file attribute is not found (or is not supported by the underlying file system), but a file with the
+\&.roothash
+suffix is found next to the image file, bearing otherwise the same name (except if the image has the
+\&.raw
+suffix, in which case the root hash file must not have it in its name), the root hash is read from it and automatically used, also as formatted hexadecimal characters\&.
+.sp
+Note that this configures the root hash for the root file system\&. Disk images may also contain separate file systems for the
+/usr/
+hierarchy, which may be Verity protected as well\&. The root hash for this protection may be configured via the
+"user\&.verity\&.usrhash"
+extended file attribute or via a
+\&.usrhash
+file adjacent to the disk image, following the same format and logic as for the root hash for the root file system described here\&. Note that there\*(Aqs currently no switch to configure the root hash for the
+/usr/
+from the command line\&.
+.sp
+Also see the
+\fIRootHash=\fR
+option in
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fB\-\-root\-hash\-sig=\fR
+.RS 4
+Takes a PKCS7 signature of the
+\fB\-\-root\-hash=\fR
+option\&. The semantics are the same as for the
+\fIRootHashSignature=\fR
+option, see
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-verity\-data=\fR
+.RS 4
+Takes the path to a data integrity (dm\-verity) file\&. This option enables data integrity checks using dm\-verity, if a root\-hash is passed and if the used image itself does not contain the integrity data\&. The integrity data must be matched by the root hash\&. If this option is not specified, but a file with the
+\&.verity
+suffix is found next to the image file, bearing otherwise the same name (except if the image has the
+\&.raw
+suffix, in which case the verity data file must not have it in its name), the verity data is read from it and automatically used\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-pivot\-root=\fR
+.RS 4
+Pivot the specified directory to
+/
+inside the container, and either unmount the container\*(Aqs old root, or pivot it to another specified directory\&. Takes one of: a path argument \(em in which case the specified path will be pivoted to
+/
+and the old root will be unmounted; or a colon\-separated pair of new root path and pivot destination for the old root\&. The new root path will be pivoted to
+/, and the old
+/
+will be pivoted to the other directory\&. Both paths must be absolute, and are resolved in the container\*(Aqs file system namespace\&.
+.sp
+This is for containers which have several bootable directories in them; for example, several
+\m[blue]\fBOSTree\fR\m[]\&\s-2\u[4]\d\s+2
+deployments\&. It emulates the behavior of the boot loader and the initrd which normally select which directory to mount as the root and start the container\*(Aqs PID 1 in\&.
+.sp
+Added in version 233\&.
+.RE
+.SS "Execution Options"
+.PP
+\fB\-a\fR, \fB\-\-as\-pid2\fR
+.RS 4
+Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init)\&. By default, if neither this option nor
+\fB\-\-boot\fR
+is used, the selected program is run as the process with PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 has on UNIX\&. For example, it needs to reap all processes reparented to it, and should implement
+\fBsysvinit\fR
+compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute on SIGTERM, reload configuration on SIGHUP, and so on)\&. With
+\fB\-\-as\-pid2\fR
+a minimal stub init process is run as PID 1 and the selected program is executed as PID 2 (and hence does not need to implement any special semantics)\&. The stub init process will reap processes as necessary and react appropriately to signals\&. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been modified to run correctly as PID 1\&. Or in other words: this switch should be used for pretty much all commands, except when the command refers to an init or shell implementation, as these are generally capable of running correctly as PID 1\&. This option may not be combined with
+\fB\-\-boot\fR\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fB\-b\fR, \fB\-\-boot\fR
+.RS 4
+Automatically search for an init program and invoke it as PID 1, instead of a shell or a user supplied program\&. If this option is used, arguments specified on the command line are used as arguments for the init program\&. This option may not be combined with
+\fB\-\-as\-pid2\fR\&.
+.sp
+The following table explains the different modes of invocation and relationship to
+\fB\-\-as\-pid2\fR
+(see above):
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.B Table\ \&1.\ \&Invocation Mode
+.TS
+allbox tab(:);
+lB lB.
+T{
+Switch
+T}:T{
+Explanation
+T}
+.T&
+l l
+l l
+l l.
+T{
+Neither \fB\-\-as\-pid2\fR nor \fB\-\-boot\fR specified
+T}:T{
+The passed parameters are interpreted as the command line, which is executed as PID 1 in the container\&.
+T}
+T{
+\fB\-\-as\-pid2\fR specified
+T}:T{
+The passed parameters are interpreted as the command line, which is executed as PID 2 in the container\&. A stub init process is run as PID 1\&.
+T}
+T{
+\fB\-\-boot\fR specified
+T}:T{
+An init program is automatically searched for and run as PID 1 in the container\&. The passed parameters are used as invocation parameters for this process\&.
+T}
+.TE
+.sp 1
+Note that
+\fB\-\-boot\fR
+is the default mode of operation if the
+systemd\-nspawn@\&.service
+template unit file is used\&.
+.RE
+.PP
+\fB\-\-chdir=\fR
+.RS 4
+Change to the specified working directory before invoking the process in the container\&. Expects an absolute path in the container\*(Aqs file system namespace\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fB\-E \fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR, \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
+.RS 4
+Specifies an environment variable to pass to the init process in the container\&. This may be used to override the default variables or to set additional variables\&. It may be used more than once to set multiple variables\&. When
+"="
+and
+\fIVALUE\fR
+are omitted, the value of the variable with the same name in the program environment will be used\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-u\fR, \fB\-\-user=\fR
+.RS 4
+After transitioning into the container, change to the specified user defined in the container\*(Aqs user database\&. Like all other systemd\-nspawn features, this is not a security feature and provides protection against accidental destructive operations only\&.
+.RE
+.PP
+\fB\-\-kill\-signal=\fR
+.RS 4
+Specify the process signal to send to the container\*(Aqs PID 1 when nspawn itself receives
+\fBSIGTERM\fR, in order to trigger an orderly shutdown of the container\&. Defaults to
+\fBSIGRTMIN+3\fR
+if
+\fB\-\-boot\fR
+is used (on systemd\-compatible init systems
+\fBSIGRTMIN+3\fR
+triggers an orderly shutdown)\&. If
+\fB\-\-boot\fR
+is not used and this option is not specified the container\*(Aqs processes are terminated abruptly via
+\fBSIGKILL\fR\&. For a list of valid signals, see
+\fBsignal\fR(7)\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-notify\-ready=\fR
+.RS 4
+Configures support for notifications from the container\*(Aqs init process\&.
+\fB\-\-notify\-ready=\fR
+takes a boolean (\fBno\fR
+and
+\fByes\fR)\&. With option
+\fBno\fR
+systemd\-nspawn notifies systemd with a
+"READY=1"
+message when the init process is created\&. With option
+\fByes\fR
+systemd\-nspawn waits for the
+"READY=1"
+message from the init process in the container before sending its own to systemd\&. For more details about notifications see
+\fBsd_notify\fR(3)\&.
+.sp
+Added in version 231\&.
+.RE
+.PP
+\fB\-\-suppress\-sync=\fR
+.RS 4
+Expects a boolean argument\&. If true, turns off any form of on\-disk file system synchronization for the container payload\&. This means all system calls such as
+\fBsync\fR(2),
+\fBfsync()\fR,
+\fBsyncfs()\fR, \&... will execute no operation, and the
+\fBO_SYNC\fR/\fBO_DSYNC\fR
+flags to
+\fBopen\fR(2)
+and related calls will be made unavailable\&. This is potentially dangerous, as assumed data integrity guarantees to the container payload are not actually enforced (i\&.e\&. data assumed to have been written to disk might be lost if the system is shut down abnormally)\&. However, this can dramatically improve container runtime performance \(en as long as these guarantees are not required or desirable, for example because any data written by the container is of temporary, redundant nature, or just an intermediary artifact that will be further processed and finalized by a later step in a pipeline\&. Defaults to false\&.
+.sp
+Added in version 250\&.
+.RE
+.SS "System Identity Options"
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Sets the machine name for this container\&. This name may be used to identify this container during its runtime (for example in tools like
+\fBmachinectl\fR(1)
+and similar), and is used to initialize the container\*(Aqs hostname (which the container can choose to override, however)\&. If not specified, the last component of the root directory path of the container is used, possibly suffixed with a random identifier in case
+\fB\-\-ephemeral\fR
+mode is selected\&. If the root directory selected is the host\*(Aqs root directory the host\*(Aqs hostname is used as default instead\&.
+.sp
+Added in version 202\&.
+.RE
+.PP
+\fB\-\-hostname=\fR
+.RS 4
+Controls the hostname to set within the container, if different from the machine name\&. Expects a valid hostname as argument\&. If this option is used, the kernel hostname of the container will be set to this value, otherwise it will be initialized to the machine name as controlled by the
+\fB\-\-machine=\fR
+option described above\&. The machine name is used for various aspect of identification of the container from the outside, the kernel hostname configurable with this option is useful for the container to identify itself from the inside\&. It is usually a good idea to keep both forms of identification synchronized, in order to avoid confusion\&. It is hence recommended to avoid usage of this option, and use
+\fB\-\-machine=\fR
+exclusively\&. Note that regardless whether the container\*(Aqs hostname is initialized from the name set with
+\fB\-\-hostname=\fR
+or the one set with
+\fB\-\-machine=\fR, the container can later override its kernel hostname freely on its own as well\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-uuid=\fR
+.RS 4
+Set the specified UUID for the container\&. The init system will initialize
+/etc/machine\-id
+from this if this file is not set yet\&. Note that this option takes effect only if
+/etc/machine\-id
+in the container is unpopulated\&.
+.RE
+.SS "Property Options"
+.PP
+\fB\-S\fR, \fB\-\-slice=\fR
+.RS 4
+Make the container part of the specified slice, instead of the default
+machine\&.slice\&. This applies only if the machine is run in its own scope unit, i\&.e\&. if
+\fB\-\-keep\-unit\fR
+isn\*(Aqt used\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-property=\fR
+.RS 4
+Set a unit property on the scope unit to register for the machine\&. This applies only if the machine is run in its own scope unit, i\&.e\&. if
+\fB\-\-keep\-unit\fR
+isn\*(Aqt used\&. Takes unit property assignments in the same format as
+\fBsystemctl set\-property\fR\&. This is useful to set memory limits and similar for the container\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-register=\fR
+.RS 4
+Controls whether the container is registered with
+\fBsystemd-machined\fR(8)\&. Takes a boolean argument, which defaults to
+"yes"\&. This option should be enabled when the container runs a full Operating System (more specifically: a system and service manager as PID 1), and is useful to ensure that the container is accessible via
+\fBmachinectl\fR(1)
+and shown by tools such as
+\fBps\fR(1)\&. If the container does not run a service manager, it is recommended to set this option to
+"no"\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-keep\-unit\fR
+.RS 4
+Instead of creating a transient scope unit to run the container in, simply use the service or scope unit
+\fBsystemd\-nspawn\fR
+has been invoked in\&. If
+\fB\-\-register=yes\fR
+is set this unit is registered with
+\fBsystemd-machined\fR(8)\&. This switch should be used if
+\fBsystemd\-nspawn\fR
+is invoked from within a service unit, and the service unit\*(Aqs sole purpose is to run a single
+\fBsystemd\-nspawn\fR
+container\&. This option is not available if run from a user session\&.
+.sp
+Note that passing
+\fB\-\-keep\-unit\fR
+disables the effect of
+\fB\-\-slice=\fR
+and
+\fB\-\-property=\fR\&. Use
+\fB\-\-keep\-unit\fR
+and
+\fB\-\-register=no\fR
+in combination to disable any kind of unit allocation or registration with
+\fBsystemd\-machined\fR\&.
+.sp
+Added in version 209\&.
+.RE
+.SS "User Namespacing Options"
+.PP
+\fB\-\-private\-users=\fR
+.RS 4
+Controls user namespacing\&. If enabled, the container will run with its own private set of UNIX user and group ids (UIDs and GIDs)\&. This involves mapping the private UIDs/GIDs used in the container (starting with the container\*(Aqs root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other purposes (usually in the range beyond the host\*(Aqs UID/GID 65536)\&. The parameter may be specified as follows:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+If one or two colon\-separated numbers are specified, user namespacing is turned on\&. The first parameter specifies the first host UID/GID to assign to the container, the second parameter specifies the number of host UIDs/GIDs to assign to the container\&. If the second parameter is omitted, 65536 UIDs/GIDs are assigned\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+If the parameter is
+"yes", user namespacing is turned on\&. The UID/GID range to use is determined automatically from the file ownership of the root directory of the container\*(Aqs directory tree\&. To use this option, make sure to prepare the directory tree in advance, and ensure that all files and directories in it are owned by UIDs/GIDs in the range you\*(Aqd like to use\&. Also, make sure that used file ACLs exclusively reference UIDs/GIDs in the appropriate range\&. In this mode, the number of UIDs/GIDs assigned to the container is 65536, and the owner UID/GID of the root directory must be a multiple of 65536\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+If the parameter is
+"no", user namespacing is turned off\&. This is the default\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+If the parameter is
+"identity", user namespacing is employed with an identity mapping for the first 65536 UIDs/GIDs\&. This is mostly equivalent to
+\fB\-\-private\-users=0:65536\fR\&. While it does not provide UID/GID isolation, since all host and container UIDs/GIDs are chosen identically it does provide process capability isolation, and hence is often a good choice if proper user namespacing with distinct UID maps is not appropriate\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+The special value
+"pick"
+turns on user namespacing\&. In this case the UID/GID range is automatically chosen\&. As first step, the file owner UID/GID of the root directory of the container\*(Aqs directory tree is read, and it is checked that no other container is currently using it\&. If this check is successful, the UID/GID range determined this way is used, similarly to the behavior if
+"yes"
+is specified\&. If the check is not successful (and thus the UID/GID range indicated in the root directory\*(Aqs file owner is already used elsewhere) a new \(en currently unused \(en UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and 1878982656, always starting at a multiple of 65536, and, if possible, consistently hashed from the machine name\&. This setting implies
+\fB\-\-private\-users\-ownership=auto\fR
+(see below), which possibly has the effect that the files and directories in the container\*(Aqs directory tree will be owned by the appropriate users of the range picked\&. Using this option makes user namespace behavior fully automatic\&. Note that the first invocation of a previously unused container image might result in picking a new UID/GID range for it, and thus in the (possibly expensive) file ownership adjustment operation\&. However, subsequent invocations of the container will be cheap (unless of course the picked UID/GID range is assigned to a different use by then)\&.
+.RE
+.sp
+It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the container covers 16 bit\&. For best security, do not assign overlapping UID/GID ranges to multiple containers\&. It is hence a good idea to use the upper 16 bit of the host 32\-bit UIDs/GIDs as container identifier, while the lower 16 bit encode the container UID/GID used\&. This is in fact the behavior enforced by the
+\fB\-\-private\-users=pick\fR
+option\&.
+.sp
+When user namespaces are used, the GID range assigned to each container is always chosen identical to the UID range\&.
+.sp
+In most cases, using
+\fB\-\-private\-users=pick\fR
+is the recommended option as it enhances container security massively and operates fully automatically in most cases\&.
+.sp
+Note that the picked UID/GID range is not written to
+/etc/passwd
+or
+/etc/group\&. In fact, the allocation of the range is not stored persistently anywhere, except in the file ownership of the files and directories of the container\&.
+.sp
+Note that when user namespacing is used file ownership on disk reflects this, and all of the container\*(Aqs files and directories are owned by the container\*(Aqs effective user and group IDs\&. This means that copying files from and to the container image requires correction of the numeric UID/GID values, according to the UID/GID shift applied\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-private\-users\-ownership=\fR
+.RS 4
+Controls how to adjust the container image\*(Aqs UIDs and GIDs to match the UID/GID range chosen with
+\fB\-\-private\-users=\fR, see above\&. Takes one of
+"off"
+(to leave the image as is),
+"chown"
+(to recursively
+\fBchown()\fR
+the container\*(Aqs directory tree as needed),
+"map"
+(in order to use transparent ID mapping mounts) or
+"auto"
+for automatically using
+"map"
+where available and
+"chown"
+where not\&.
+.sp
+If
+"chown"
+is selected, all files and directories in the container\*(Aqs directory tree will be adjusted so that they are owned by the appropriate UIDs/GIDs selected for the container (see above)\&. This operation is potentially expensive, as it involves iterating through the full directory tree of the container\&. Besides actual file ownership, file ACLs are adjusted as well\&.
+.sp
+Typically
+"map"
+is the best choice, since it transparently maps UIDs/GIDs in memory as needed without modifying the image, and without requiring an expensive recursive adjustment operation\&. However, it is not available for all file systems, currently\&.
+.sp
+The
+\fB\-\-private\-users\-ownership=auto\fR
+option is implied if
+\fB\-\-private\-users=pick\fR
+is used\&. This option has no effect if user namespacing is not used\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-U\fR
+.RS 4
+If the kernel supports the user namespaces feature, equivalent to
+\fB\-\-private\-users=pick \-\-private\-users\-ownership=auto\fR, otherwise equivalent to
+\fB\-\-private\-users=no\fR\&.
+.sp
+Note that
+\fB\-U\fR
+is the default if the
+systemd\-nspawn@\&.service
+template unit file is used\&.
+.sp
+Note: it is possible to undo the effect of
+\fB\-\-private\-users\-ownership=chown\fR
+(or
+\fB\-U\fR) on the file system by redoing the operation with the first UID of 0:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+systemd\-nspawn \&... \-\-private\-users=0 \-\-private\-users\-ownership=chown
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Added in version 230\&.
+.RE
+.SS "Networking Options"
+.PP
+\fB\-\-private\-network\fR
+.RS 4
+Disconnect networking of the container from the host\&. This makes all network interfaces unavailable in the container, with the exception of the loopback device and those specified with
+\fB\-\-network\-interface=\fR
+and configured with
+\fB\-\-network\-veth\fR\&. If this option is specified, the
+\fBCAP_NET_ADMIN\fR
+capability will be added to the set of capabilities the container retains\&. The latter may be disabled by using
+\fB\-\-drop\-capability=\fR\&. If this option is not specified (or implied by one of the options listed below), the container will have full access to the host network\&.
+.RE
+.PP
+\fB\-\-network\-interface=\fR
+.RS 4
+Assign the specified network interface to the container\&. Either takes a single interface name, referencing the name on the host, or a colon\-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container\&. When the container terminates, the interface is moved back to the calling namespace and renamed to its original name\&. Note that
+\fB\-\-network\-interface=\fR
+implies
+\fB\-\-private\-network\fR\&. This option may be used more than once to add multiple network interfaces to the container\&.
+.sp
+Note that any network interface specified this way must already exist at the time the container is started\&. If the container shall be started automatically at boot via a
+systemd\-nspawn@\&.service
+unit file instance, it might hence make sense to add a unit file drop\-in to the service instance (e\&.g\&.
+/etc/systemd/system/systemd\-nspawn@foobar\&.service\&.d/50\-network\&.conf) with contents like the following:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+[Unit]
+Wants=sys\-subsystem\-net\-devices\-ens1\&.device
+After=sys\-subsystem\-net\-devices\-ens1\&.device
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+This will make sure that activation of the container service will be delayed until the
+"ens1"
+network interface has shown up\&. This is required since hardware probing is fully asynchronous, and network interfaces might be discovered only later during the boot process, after the container would normally be started without these explicit dependencies\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-network\-macvlan=\fR
+.RS 4
+Create a
+"macvlan"
+interface of the specified Ethernet network interface and add it to the container\&. Either takes a single interface name, referencing the name on the host, or a colon\-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container\&. A
+"macvlan"
+interface is a virtual interface that adds a second MAC address to an existing physical Ethernet link\&. If the container interface name is not defined, the interface in the container will be named after the interface on the host, prefixed with
+"mv\-"\&. Note that
+\fB\-\-network\-macvlan=\fR
+implies
+\fB\-\-private\-network\fR\&. This option may be used more than once to add multiple network interfaces to the container\&.
+.sp
+As with
+\fB\-\-network\-interface=\fR, the underlying Ethernet network interface must already exist at the time the container is started, and thus similar unit file drop\-ins as described above might be useful\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-network\-ipvlan=\fR
+.RS 4
+Create an
+"ipvlan"
+interface of the specified Ethernet network interface and add it to the container\&. Either takes a single interface name, referencing the name on the host, or a colon\-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container\&. An
+"ipvlan"
+interface is a virtual interface, similar to a
+"macvlan"
+interface, which uses the same MAC address as the underlying interface\&. If the container interface name is not defined, the interface in the container will be named after the interface on the host, prefixed with
+"iv\-"\&. Note that
+\fB\-\-network\-ipvlan=\fR
+implies
+\fB\-\-private\-network\fR\&. This option may be used more than once to add multiple network interfaces to the container\&.
+.sp
+As with
+\fB\-\-network\-interface=\fR, the underlying Ethernet network interface must already exist at the time the container is started, and thus similar unit file drop\-ins as described above might be useful\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-network\-veth\fR
+.RS 4
+Create a virtual Ethernet link ("veth") between host and container\&. The host side of the Ethernet link will be available as a network interface named after the container\*(Aqs name (as specified with
+\fB\-\-machine=\fR), prefixed with
+"ve\-"\&. The container side of the Ethernet link will be named
+"host0"\&. The
+\fB\-\-network\-veth\fR
+option implies
+\fB\-\-private\-network\fR\&.
+.sp
+Note that
+\fBsystemd-networkd.service\fR(8)
+includes by default a network file
+/usr/lib/systemd/network/80\-container\-ve\&.network
+matching the host\-side interfaces created this way, which contains settings to enable automatic address provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host\*(Aqs external network interfaces\&. It also contains
+/usr/lib/systemd/network/80\-container\-host0\&.network
+matching the container\-side interface created this way, containing settings to enable client side address assignment via DHCP\&. In case
+systemd\-networkd
+is running on both the host and inside the container, automatic IP communication from the container to the host is thus available, with further connectivity to the external network\&.
+.sp
+Note that
+\fB\-\-network\-veth\fR
+is the default if the
+systemd\-nspawn@\&.service
+template unit file is used\&.
+.sp
+Note that on Linux network interface names may have a length of 15 characters at maximum, while container names may have a length up to 64 characters\&. As this option derives the host\-side interface name from the container name the name is possibly truncated\&. Thus, care needs to be taken to ensure that interface names remain unique in this case, or even better container names are generally not chosen longer than 12 characters, to avoid the truncation\&. If the name is truncated,
+\fBsystemd\-nspawn\fR
+will automatically append a 4\-digit hash value to the name to reduce the chance of collisions\&. However, the hash algorithm is not collision\-free\&. (See
+\fBsystemd.net-naming-scheme\fR(7)
+for details on older naming algorithms for this interface)\&. Alternatively, the
+\fB\-\-network\-veth\-extra=\fR
+option may be used, which allows free configuration of the host\-side interface name independently of the container name \(em but might require a bit more additional configuration in case bridging in a fashion similar to
+\fB\-\-network\-bridge=\fR
+is desired\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-network\-veth\-extra=\fR
+.RS 4
+Adds an additional virtual Ethernet link between host and container\&. Takes a colon\-separated pair of host interface name and container interface name\&. The latter may be omitted in which case the container and host sides will be assigned the same name\&. This switch is independent of
+\fB\-\-network\-veth\fR, and \(em in contrast \(em may be used multiple times, and allows configuration of the network interface names\&. Note that
+\fB\-\-network\-bridge=\fR
+has no effect on interfaces created with
+\fB\-\-network\-veth\-extra=\fR\&.
+.sp
+Added in version 228\&.
+.RE
+.PP
+\fB\-\-network\-bridge=\fR
+.RS 4
+Adds the host side of the Ethernet link created with
+\fB\-\-network\-veth\fR
+to the specified Ethernet bridge interface\&. Expects a valid network interface name of a bridge device as argument\&. Note that
+\fB\-\-network\-bridge=\fR
+implies
+\fB\-\-network\-veth\fR\&. If this option is used, the host side of the Ethernet link will use the
+"vb\-"
+prefix instead of
+"ve\-"\&. Regardless of the used naming prefix the same network interface name length limits imposed by Linux apply, along with the complications this creates (for details see above)\&.
+.sp
+As with
+\fB\-\-network\-interface=\fR, the underlying bridge network interface must already exist at the time the container is started, and thus similar unit file drop\-ins as described above might be useful\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-network\-zone=\fR
+.RS 4
+Creates a virtual Ethernet link ("veth") to the container and adds it to an automatically managed Ethernet bridge interface\&. The bridge interface is named after the passed argument, prefixed with
+"vz\-"\&. The bridge interface is automatically created when the first container configured for its name is started, and is automatically removed when the last container configured for its name exits\&. Hence, each bridge interface configured this way exists only as long as there\*(Aqs at least one container referencing it running\&. This option is very similar to
+\fB\-\-network\-bridge=\fR, besides this automatic creation/removal of the bridge device\&.
+.sp
+This setting makes it easy to place multiple related containers on a common, virtual Ethernet\-based broadcast domain, here called a "zone"\&. Each container may only be part of one zone, but each zone may contain any number of containers\&. Each zone is referenced by its name\&. Names may be chosen freely (as long as they form valid network interface names when prefixed with
+"vz\-"), and it is sufficient to pass the same name to the
+\fB\-\-network\-zone=\fR
+switch of the various concurrently running containers to join them in one zone\&.
+.sp
+Note that
+\fBsystemd-networkd.service\fR(8)
+includes by default a network file
+/usr/lib/systemd/network/80\-container\-vz\&.network
+matching the bridge interfaces created this way, which contains settings to enable automatic address provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host\*(Aqs external network interfaces\&. Using
+\fB\-\-network\-zone=\fR
+is hence in most cases fully automatic and sufficient to connect multiple local containers in a joined broadcast domain to the host, with further connectivity to the external network\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-network\-namespace\-path=\fR
+.RS 4
+Takes the path to a file representing a kernel network namespace that the container shall run in\&. The specified path should refer to a (possibly bind\-mounted) network namespace file, as exposed by the kernel below
+/proc/$PID/ns/net\&. This makes the container enter the given network namespace\&. One of the typical use cases is to give a network namespace under
+/run/netns
+created by
+\fBip-netns\fR(8), for example,
+\fB\-\-network\-namespace\-path=/run/netns/foo\fR\&. Note that this option cannot be used together with other network\-related options, such as
+\fB\-\-private\-network\fR
+or
+\fB\-\-network\-interface=\fR\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-port=\fR
+.RS 4
+If private networking is enabled, maps an IP port on the host onto an IP port on the container\&. Takes a protocol specifier (either
+"tcp"
+or
+"udp"), separated by a colon from a host port number in the range 1 to 65535, separated by a colon from a container port number in the range from 1 to 65535\&. The protocol specifier and its separating colon may be omitted, in which case
+"tcp"
+is assumed\&. The container port number and its colon may be omitted, in which case the same port as the host port is implied\&. This option is only supported if private networking is used, such as with
+\fB\-\-network\-veth\fR,
+\fB\-\-network\-zone=\fR
+\fB\-\-network\-bridge=\fR\&.
+.sp
+Added in version 219\&.
+.RE
+.SS "Security Options"
+.PP
+\fB\-\-capability=\fR
+.RS 4
+List one or more additional capabilities to grant the container\&. Takes a comma\-separated list of capability names, see
+\fBcapabilities\fR(7)
+for more information\&. Note that the following capabilities will be granted in any way:
+\fBCAP_AUDIT_CONTROL\fR,
+\fBCAP_AUDIT_WRITE\fR,
+\fBCAP_CHOWN\fR,
+\fBCAP_DAC_OVERRIDE\fR,
+\fBCAP_DAC_READ_SEARCH\fR,
+\fBCAP_FOWNER\fR,
+\fBCAP_FSETID\fR,
+\fBCAP_IPC_OWNER\fR,
+\fBCAP_KILL\fR,
+\fBCAP_LEASE\fR,
+\fBCAP_LINUX_IMMUTABLE\fR,
+\fBCAP_MKNOD\fR,
+\fBCAP_NET_BIND_SERVICE\fR,
+\fBCAP_NET_BROADCAST\fR,
+\fBCAP_NET_RAW\fR,
+\fBCAP_SETFCAP\fR,
+\fBCAP_SETGID\fR,
+\fBCAP_SETPCAP\fR,
+\fBCAP_SETUID\fR,
+\fBCAP_SYS_ADMIN\fR,
+\fBCAP_SYS_BOOT\fR,
+\fBCAP_SYS_CHROOT\fR,
+\fBCAP_SYS_NICE\fR,
+\fBCAP_SYS_PTRACE\fR,
+\fBCAP_SYS_RESOURCE\fR,
+\fBCAP_SYS_TTY_CONFIG\fR\&. Also
+\fBCAP_NET_ADMIN\fR
+is retained if
+\fB\-\-private\-network\fR
+is specified\&. If the special value
+"all"
+is passed, all capabilities are retained\&.
+.sp
+If the special value of
+"help"
+is passed, the program will print known capability names and exit\&.
+.sp
+This option sets the bounding set of capabilities which also limits the ambient capabilities as given with the
+\fB\-\-ambient\-capability=\fR\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-drop\-capability=\fR
+.RS 4
+Specify one or more additional capabilities to drop for the container\&. This allows running the container with fewer capabilities than the default (see above)\&.
+.sp
+If the special value of
+"help"
+is passed, the program will print known capability names and exit\&.
+.sp
+This option sets the bounding set of capabilities which also limits the ambient capabilities as given with the
+\fB\-\-ambient\-capability=\fR\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-\-ambient\-capability=\fR
+.RS 4
+Specify one or more additional capabilities to pass in the inheritable and ambient set to the program started within the container\&. The value
+"all"
+is not supported for this setting\&.
+.sp
+All capabilities specified here must be in the set allowed with the
+\fB\-\-capability=\fR
+and
+\fB\-\-drop\-capability=\fR
+options\&. Otherwise, an error message will be shown\&.
+.sp
+This option cannot be combined with the boot mode of the container (as requested via
+\fB\-\-boot\fR)\&.
+.sp
+If the special value of
+"help"
+is passed, the program will print known capability names and exit\&.
+.sp
+Added in version 248\&.
+.RE
+.PP
+\fB\-\-no\-new\-privileges=\fR
+.RS 4
+Takes a boolean argument\&. Specifies the value of the
+\fBPR_SET_NO_NEW_PRIVS\fR
+flag for the container payload\&. Defaults to off\&. When turned on the payload code of the container cannot acquire new privileges, i\&.e\&. the "setuid" file bit as well as file system capabilities will not have an effect anymore\&. See
+\fBprctl\fR(2)
+for details about this flag\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-system\-call\-filter=\fR
+.RS 4
+Alter the system call filter applied to containers\&. Takes a space\-separated list of system call names or group names (the latter prefixed with
+"@", as listed by the
+\fBsyscall\-filter\fR
+command of
+\fBsystemd-analyze\fR(1))\&. Passed system calls will be permitted\&. The list may optionally be prefixed by
+"~", in which case all listed system calls are prohibited\&. If this command line option is used multiple times the configured lists are combined\&. If both a positive and a negative list (that is one system call list without and one with the
+"~"
+prefix) are configured, the negative list takes precedence over the positive list\&. Note that
+\fBsystemd\-nspawn\fR
+always implements a system call allow list (as opposed to a deny list!), and this command line option hence adds or removes entries from the default allow list, depending on the
+"~"
+prefix\&. Note that the applied system call filter is also altered implicitly if additional capabilities are passed using the
+\fB\-\-capabilities=\fR\&.
+.sp
+Added in version 235\&.
+.RE
+.PP
+\fB\-Z\fR, \fB\-\-selinux\-context=\fR
+.RS 4
+Sets the SELinux security context to be used to label processes in the container\&.
+.sp
+Added in version 209\&.
+.RE
+.PP
+\fB\-L\fR, \fB\-\-selinux\-apifs\-context=\fR
+.RS 4
+Sets the SELinux security context to be used to label files in the virtual API file systems in the container\&.
+.sp
+Added in version 209\&.
+.RE
+.SS "Resource Options"
+.PP
+\fB\-\-rlimit=\fR
+.RS 4
+Sets the specified POSIX resource limit for the container payload\&. Expects an assignment of the form
+"\fILIMIT\fR=\fISOFT\fR:\fIHARD\fR"
+or
+"\fILIMIT\fR=\fIVALUE\fR", where
+\fILIMIT\fR
+should refer to a resource limit type, such as
+\fBRLIMIT_NOFILE\fR
+or
+\fBRLIMIT_NICE\fR\&. The
+\fISOFT\fR
+and
+\fIHARD\fR
+fields should refer to the numeric soft and hard resource limit values\&. If the second form is used,
+\fIVALUE\fR
+may specify a value that is used both as soft and hard limit\&. In place of a numeric value the special string
+"infinity"
+may be used to turn off resource limiting for the specific type of resource\&. This command line option may be used multiple times to control limits on multiple limit types\&. If used multiple times for the same limit type, the last use wins\&. For details about resource limits see
+\fBsetrlimit\fR(2)\&. By default resource limits for the container\*(Aqs init process (PID 1) are set to the same values the Linux kernel originally passed to the host init system\&. Note that some resource limits are enforced on resources counted per user, in particular
+\fBRLIMIT_NPROC\fR\&. This means that unless user namespacing is deployed (i\&.e\&.
+\fB\-\-private\-users=\fR
+is used, see above), any limits set will be applied to the resource usage of the same user on all local containers as well as the host\&. This means particular care needs to be taken with these limits as they might be triggered by possibly less trusted code\&. Example:
+"\-\-rlimit=RLIMIT_NOFILE=8192:16384"\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-oom\-score\-adjust=\fR
+.RS 4
+Changes the OOM ("Out Of Memory") score adjustment value for the container payload\&. This controls
+/proc/self/oom_score_adj
+which influences the preference with which this container is terminated when memory becomes scarce\&. For details see
+\fBproc\fR(5)\&. Takes an integer in the range \-1000\&...1000\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-cpu\-affinity=\fR
+.RS 4
+Controls the CPU affinity of the container payload\&. Takes a comma separated list of CPU numbers or number ranges (the latter\*(Aqs start and end value separated by dashes)\&. See
+\fBsched_setaffinity\fR(2)
+for details\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-personality=\fR
+.RS 4
+Control the architecture ("personality") reported by
+\fBuname\fR(2)
+in the container\&. Currently, only
+"x86"
+and
+"x86\-64"
+are supported\&. This is useful when running a 32\-bit container on a 64\-bit host\&. If this setting is not used, the personality reported in the container is the same as the one reported on the host\&.
+.sp
+Added in version 209\&.
+.RE
+.SS "Integration Options"
+.PP
+\fB\-\-resolv\-conf=\fR
+.RS 4
+Configures how
+/etc/resolv\&.conf
+inside of the container shall be handled (i\&.e\&. DNS configuration synchronization from host to container)\&. Takes one of
+"off",
+"copy\-host",
+"copy\-static",
+"copy\-uplink",
+"copy\-stub",
+"replace\-host",
+"replace\-static",
+"replace\-uplink",
+"replace\-stub",
+"bind\-host",
+"bind\-static",
+"bind\-uplink",
+"bind\-stub",
+"delete"
+or
+"auto"\&.
+.sp
+If set to
+"off"
+the
+/etc/resolv\&.conf
+file in the container is left as it is included in the image, and neither modified nor bind mounted over\&.
+.sp
+If set to
+"copy\-host", the
+/etc/resolv\&.conf
+file from the host is copied into the container, unless the file exists already and is not a regular file (e\&.g\&. a symlink)\&. Similarly, if
+"replace\-host"
+is used the file is copied, replacing any existing inode, including symlinks\&. Similarly, if
+"bind\-host"
+is used, the file is bind mounted from the host into the container\&.
+.sp
+If set to
+"copy\-static",
+"replace\-static"
+or
+"bind\-static"
+the static
+resolv\&.conf
+file supplied with
+\fBsystemd-resolved.service\fR(8)
+(specifically:
+/usr/lib/systemd/resolv\&.conf) is copied or bind mounted into the container\&.
+.sp
+If set to
+"copy\-uplink",
+"replace\-uplink"
+or
+"bind\-uplink"
+the uplink
+resolv\&.conf
+file managed by
+systemd\-resolved\&.service
+(specifically:
+/run/systemd/resolve/resolv\&.conf) is copied or bind mounted into the container\&.
+.sp
+If set to
+"copy\-stub",
+"replace\-stub"
+or
+"bind\-stub"
+the stub
+resolv\&.conf
+file managed by
+systemd\-resolved\&.service
+(specifically:
+/run/systemd/resolve/stub\-resolv\&.conf) is copied or bind mounted into the container\&.
+.sp
+If set to
+"delete"
+the
+/etc/resolv\&.conf
+file in the container is deleted if it exists\&.
+.sp
+Finally, if set to
+"auto"
+the file is left as it is if private networking is turned on (see
+\fB\-\-private\-network\fR)\&. Otherwise, if
+systemd\-resolved\&.service
+is running its stub
+resolv\&.conf
+file is used, and if not the host\*(Aqs
+/etc/resolv\&.conf
+file\&. In the latter cases the file is copied if the image is writable, and bind mounted otherwise\&.
+.sp
+It\*(Aqs recommended to use
+"copy\-\&..."
+or
+"replace\-\&..."
+if the container shall be able to make changes to the DNS configuration on its own, deviating from the host\*(Aqs settings\&. Otherwise
+"bind"
+is preferable, as it means direct changes to
+/etc/resolv\&.conf
+in the container are not allowed, as it is a read\-only bind mount (but note that if the container has enough privileges, it might simply go ahead and unmount the bind mount anyway)\&. Note that both if the file is bind mounted and if it is copied no further propagation of configuration is generally done after the one\-time early initialization (this is because the file is usually updated through copying and renaming)\&. Defaults to
+"auto"\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-timezone=\fR
+.RS 4
+Configures how
+/etc/localtime
+inside of the container (i\&.e\&. local timezone synchronization from host to container) shall be handled\&. Takes one of
+"off",
+"copy",
+"bind",
+"symlink",
+"delete"
+or
+"auto"\&. If set to
+"off"
+the
+/etc/localtime
+file in the container is left as it is included in the image, and neither modified nor bind mounted over\&. If set to
+"copy"
+the
+/etc/localtime
+file of the host is copied into the container\&. Similarly, if
+"bind"
+is used, the file is bind mounted from the host into the container\&. If set to
+"symlink", a symlink is created pointing from
+/etc/localtime
+in the container to the timezone file in the container that matches the timezone setting on the host\&. If set to
+"delete", the file in the container is deleted, should it exist\&. If set to
+"auto"
+and the
+/etc/localtime
+file of the host is a symlink, then
+"symlink"
+mode is used, and
+"copy"
+otherwise, except if the image is read\-only in which case
+"bind"
+is used instead\&. Defaults to
+"auto"\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-link\-journal=\fR
+.RS 4
+Control whether the container\*(Aqs journal shall be made visible to the host system\&. If enabled, allows viewing the container\*(Aqs journal files from the host (but not vice versa)\&. Takes one of
+"no",
+"host",
+"try\-host",
+"guest",
+"try\-guest",
+"auto"\&. If
+"no", the journal is not linked\&. If
+"host", the journal files are stored on the host file system (beneath
+/var/log/journal/\fImachine\-id\fR) and the subdirectory is bind\-mounted into the container at the same location\&. If
+"guest", the journal files are stored on the guest file system (beneath
+/var/log/journal/\fImachine\-id\fR) and the subdirectory is symlinked into the host at the same location\&.
+"try\-host"
+and
+"try\-guest"
+do the same but do not fail if the host does not have persistent journaling enabled, or if the container is in the
+\fB\-\-ephemeral\fR
+mode\&. If
+"auto"
+(the default), and the right subdirectory of
+/var/log/journal
+exists, it will be bind mounted into the container\&. If the subdirectory does not exist, no linking is performed\&. Effectively, booting a container once with
+"guest"
+or
+"host"
+will link the journal persistently if further on the default of
+"auto"
+is used\&.
+.sp
+Note that
+\fB\-\-link\-journal=try\-guest\fR
+is the default if the
+systemd\-nspawn@\&.service
+template unit file is used\&.
+.sp
+Added in version 187\&.
+.RE
+.PP
+\fB\-j\fR
+.RS 4
+Equivalent to
+\fB\-\-link\-journal=try\-guest\fR\&.
+.sp
+Added in version 187\&.
+.RE
+.SS "Mount Options"
+.PP
+\fB\-\-bind=\fR, \fB\-\-bind\-ro=\fR
+.RS 4
+Bind mount a file or directory from the host into the container\&. Takes one of: a path argument\ \&\(em in which case the specified path will be mounted from the host to the same path in the container, or a colon\-separated pair of paths\ \&\(em in which case the first specified path is the source in the host, and the second path is the destination in the container, or a colon\-separated triple of source path, destination path and mount options\&. The source path may optionally be prefixed with a
+"+"
+character\&. If so, the source path is taken relative to the image\*(Aqs root directory\&. This permits setting up bind mounts within the container image\&. The source path may be specified as empty string, in which case a temporary directory below the host\*(Aqs
+/var/tmp/
+directory is used\&. It is automatically removed when the container is shut down\&. If the source path is not absolute, it is resolved relative to the current working directory\&. The
+\fB\-\-bind\-ro=\fR
+option creates read\-only bind mounts\&. Backslash escapes are interpreted, so
+"\e:"
+may be used to embed colons in either path\&. This option may be specified multiple times for creating multiple independent bind mount points\&.
+.sp
+Mount options are comma\-separated\&.
+\fBrbind\fR
+and
+\fBnorbind\fR
+control whether to create a recursive or a regular bind mount\&. Defaults to
+\fBrbind\fR\&.
+\fBnoidmap\fR,
+\fBidmap\fR, and
+\fBrootidmap\fR
+control ID mapping\&.
+.sp
+Using
+\fBidmap\fR
+or
+\fBrootidmap\fR
+requires support by the source filesystem for user/group ID mapped mounts\&. Defaults to
+\fBnoidmap\fR\&. With
+\fBx\fR
+being the container\*(Aqs UID range offset,
+\fBy\fR
+being the length of the container\*(Aqs UID range, and
+\fBp\fR
+being the owner UID of the bind mount source inode on the host:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+If
+\fBnoidmap\fR
+is used, any user
+\fBz\fR
+in the range
+\fB0 \&... y\fR
+seen from inside of the container is mapped to
+\fBx + z\fR
+in the
+\fBx \&... x + y\fR
+range on the host\&. Other host users are mapped to
+\fBnobody\fR
+inside the container\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+If
+\fBidmap\fR
+is used, any user
+\fBz\fR
+in the UID range
+\fB0 \&... y\fR
+as seen from inside the container is mapped to the same
+\fBz\fR
+in the same
+\fB0 \&... y\fR
+range on the host\&. Other host users are mapped to
+\fBnobody\fR
+inside the container\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+If
+\fBrootidmap\fR
+is used, the user
+\fB0\fR
+seen from inside of the container is mapped to
+\fBp\fR
+on the host\&. Other host users are mapped to
+\fBnobody\fR
+inside the container\&.
+.RE
+.sp
+Whichever ID mapping option is used, the same mapping will be used for users and groups IDs\&. If
+\fBrootidmap\fR
+is used, the group owning the bind mounted directory will have no effect\&.
+.sp
+Note that when this option is used in combination with
+\fB\-\-private\-users\fR, the resulting mount points will be owned by the
+\fBnobody\fR
+user\&. That\*(Aqs because the mount and its files and directories continue to be owned by the relevant host users and groups, which do not exist in the container, and thus show up under the wildcard UID 65534 (nobody)\&. If such bind mounts are created, it is recommended to make them read\-only, using
+\fB\-\-bind\-ro=\fR\&. Alternatively you can use the "idmap" mount option to map the filesystem IDs\&.
+.sp
+Added in version 198\&.
+.RE
+.PP
+\fB\-\-bind\-user=\fR
+.RS 4
+Binds the home directory of the specified user on the host into the container\&. Takes the name of an existing user on the host as argument\&. May be used multiple times to bind multiple users into the container\&. This does three things:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+The user\*(Aqs home directory is bind mounted from the host into
+/run/host/home/\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+An additional UID/GID mapping is added that maps the host user\*(Aqs UID/GID to a container UID/GID, allocated from the 60514\&...60577 range\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+A JSON user and group record is generated in
+/run/userdb/
+that describes the mapped user\&. It contains a minimized representation of the host\*(Aqs user record, adjusted to the UID/GID and home directory path assigned to the user in the container\&. The
+\fBnss-systemd\fR(8)
+glibc NSS module will pick up these records from there and make them available in the container\*(Aqs user/group databases\&.
+.RE
+.sp
+The combination of the three operations above ensures that it is possible to log into the container using the same account information as on the host\&. The user is only mapped transiently, while the container is running, and the mapping itself does not result in persistent changes to the container (except maybe for log messages generated at login time, and similar)\&. Note that in particular the UID/GID assignment in the container is not made persistently\&. If the user is mapped transiently, it is best to not allow the user to make persistent changes to the container\&. If the user leaves files or directories owned by the user, and those UIDs/GIDs are reused during later container invocations (possibly with a different
+\fB\-\-bind\-user=\fR
+mapping), those files and directories will be accessible to the "new" user\&.
+.sp
+The user/group record mapping only works if the container contains systemd 249 or newer, with
+\fBnss\-systemd\fR
+properly configured in
+nsswitch\&.conf\&. See
+\fBnss-systemd\fR(8)
+for details\&.
+.sp
+Note that the user record propagated from the host into the container will contain the UNIX password hash of the user, so that seamless logins in the container are possible\&. If the container is less trusted than the host it\*(Aqs hence important to use a strong UNIX password hash function (e\&.g\&. yescrypt or similar, with the
+"$y$"
+hash prefix)\&.
+.sp
+When binding a user from the host into the container checks are executed to ensure that the username is not yet known in the container\&. Moreover, it is checked that the UID/GID allocated for it is not currently defined in the user/group databases of the container\&. Both checks directly access the container\*(Aqs
+/etc/passwd
+and
+/etc/group, and thus might not detect existing accounts in other databases\&.
+.sp
+This operation is only supported in combination with
+\fB\-\-private\-users=\fR/\fB\-U\fR\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-inaccessible=\fR
+.RS 4
+Make the specified path inaccessible in the container\&. This over\-mounts the specified path (which must exist in the container) with a file node of the same type that is empty and has the most restrictive access mode supported\&. This is an effective way to mask files, directories and other file system objects from the container payload\&. This option may be used more than once in case all specified paths are masked\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-tmpfs=\fR
+.RS 4
+Mount a tmpfs file system into the container\&. Takes a single absolute path argument that specifies where to mount the tmpfs instance to (in which case the directory access mode will be chosen as 0755, owned by root/root), or optionally a colon\-separated pair of path and mount option string that is used for mounting (in which case the kernel default for access mode and owner will be chosen, unless otherwise specified)\&. Backslash escapes are interpreted in the path, so
+"\e:"
+may be used to embed colons in the path\&.
+.sp
+Note that this option cannot be used to replace the root file system of the container with a temporary file system\&. However, the
+\fB\-\-volatile=\fR
+option described below provides similar functionality, with a focus on implementing stateless operating system images\&.
+.sp
+Added in version 214\&.
+.RE
+.PP
+\fB\-\-overlay=\fR, \fB\-\-overlay\-ro=\fR
+.RS 4
+Combine multiple directory trees into one overlay file system and mount it into the container\&. Takes a list of colon\-separated paths to the directory trees to combine and the destination mount point\&.
+.sp
+Backslash escapes are interpreted in the paths, so
+"\e:"
+may be used to embed colons in the paths\&.
+.sp
+If three or more paths are specified, then the last specified path is the destination mount point in the container, all paths specified before refer to directory trees on the host and are combined in the specified order into one overlay file system\&. The left\-most path is hence the lowest directory tree, the second\-to\-last path the highest directory tree in the stacking order\&. If
+\fB\-\-overlay\-ro=\fR
+is used instead of
+\fB\-\-overlay=\fR, a read\-only overlay file system is created\&. If a writable overlay file system is created, all changes made to it are written to the highest directory tree in the stacking order, i\&.e\&. the second\-to\-last specified\&.
+.sp
+If only two paths are specified, then the second specified path is used both as the top\-level directory tree in the stacking order as seen from the host, as well as the mount point for the overlay file system in the container\&. At least two paths have to be specified\&.
+.sp
+The source paths may optionally be prefixed with
+"+"
+character\&. If so they are taken relative to the image\*(Aqs root directory\&. The uppermost source path may also be specified as an empty string, in which case a temporary directory below the host\*(Aqs
+/var/tmp/
+is used\&. The directory is removed automatically when the container is shut down\&. This behaviour is useful in order to make read\-only container directories writable while the container is running\&. For example, use
+"\-\-overlay=+/var::/var"
+in order to automatically overlay a writable temporary directory on a read\-only
+/var/
+directory\&. If a source path is not absolute, it is resolved relative to the current working directory\&.
+.sp
+For details about overlay file systems, see
+\m[blue]\fBOverlay Filesystem\fR\m[]\&\s-2\u[5]\d\s+2\&. Note that the semantics of overlay file systems are substantially different from normal file systems, in particular regarding reported device and inode information\&. Device and inode information may change for a file while it is being written to, and processes might see out\-of\-date versions of files at times\&. Note that this switch automatically derives the
+"workdir="
+mount option for the overlay file system from the top\-level directory tree, making it a sibling of it\&. It is hence essential that the top\-level directory tree is not a mount point itself (since the working directory must be on the same file system as the top\-most directory tree)\&. Also note that the
+"lowerdir="
+mount option receives the paths to stack in the opposite order of this switch\&.
+.sp
+Note that this option cannot be used to replace the root file system of the container with an overlay file system\&. However, the
+\fB\-\-volatile=\fR
+option described above provides similar functionality, with a focus on implementing stateless operating system images\&.
+.sp
+Added in version 220\&.
+.RE
+.SS "Input/Output Options"
+.PP
+\fB\-\-console=\fR\fIMODE\fR
+.RS 4
+Configures how to set up standard input, output and error output for the container payload, as well as the
+/dev/console
+device for the container\&. Takes one of
+\fBinteractive\fR,
+\fBread\-only\fR,
+\fBpassive\fR,
+\fBpipe\fR
+or
+\fBautopipe\fR\&. If
+\fBinteractive\fR, a pseudo\-TTY is allocated and made available as
+/dev/console
+in the container\&. It is then bi\-directionally connected to the standard input and output passed to
+\fBsystemd\-nspawn\fR\&.
+\fBread\-only\fR
+is similar but only the output of the container is propagated and no input from the caller is read\&. If
+\fBpassive\fR, a pseudo TTY is allocated, but it is not connected anywhere\&. In
+\fBpipe\fR
+mode no pseudo TTY is allocated, but the standard input, output and error output file descriptors passed to
+\fBsystemd\-nspawn\fR
+are passed on \(em as they are \(em to the container payload, see the following paragraph\&. Finally,
+\fBautopipe\fR
+mode operates like
+\fBinteractive\fR
+when
+\fBsystemd\-nspawn\fR
+is invoked on a terminal, and like
+\fBpipe\fR
+otherwise\&. Defaults to
+\fBinteractive\fR
+if
+\fBsystemd\-nspawn\fR
+is invoked from a terminal, and
+\fBread\-only\fR
+otherwise\&.
+.sp
+In
+\fBpipe\fR
+mode,
+/dev/console
+will not exist in the container\&. This means that the container payload generally cannot be a full init system as init systems tend to require
+/dev/console
+to be available\&. On the other hand, in this mode container invocations can be used within shell pipelines\&. This is because intermediary pseudo TTYs do not permit independent bidirectional propagation of the end\-of\-file (EOF) condition, which is necessary for shell pipelines to work correctly\&.
+\fINote that the \fR\fI\fBpipe\fR\fR\fI mode should be used carefully\fR, as passing arbitrary file descriptors to less trusted container payloads might open up unwanted interfaces for access by the container payload\&. For example, if a passed file descriptor refers to a TTY of some form, APIs such as
+\fBTIOCSTI\fR
+may be used to synthesize input that might be used for escaping the container\&. Hence
+\fBpipe\fR
+mode should only be used if the payload is sufficiently trusted or when the standard input/output/error output file descriptors are known safe, for example pipes\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-pipe\fR, \fB\-P\fR
+.RS 4
+Equivalent to
+\fB\-\-console=pipe\fR\&.
+.sp
+Added in version 242\&.
+.RE
+.SS "Credentials"
+.PP
+\fB\-\-load\-credential=\fR\fIID\fR:\fIPATH\fR, \fB\-\-set\-credential=\fR\fIID\fR:\fIVALUE\fR
+.RS 4
+Pass a credential to the container\&. These two options correspond to the
+\fILoadCredential=\fR
+and
+\fISetCredential=\fR
+settings in unit files\&. See
+\fBsystemd.exec\fR(5)
+for details about these concepts, as well as the syntax of the option\*(Aqs arguments\&.
+.sp
+Note: when
+\fBsystemd\-nspawn\fR
+runs as systemd system service it can propagate the credentials it received via
+\fILoadCredential=\fR/\fISetCredential=\fR
+to the container payload\&. A systemd service manager running as PID 1 in the container can further propagate them to the services it itself starts\&. It is thus possible to easily propagate credentials from a parent service manager to a container manager service and from there into its payload\&. This can even be done recursively\&.
+.sp
+In order to embed binary data into the credential data for
+\fB\-\-set\-credential=\fR, use C\-style escaping (i\&.e\&.
+"\en"
+to embed a newline, or
+"\ex00"
+to embed a
+\fBNUL\fR
+byte)\&. Note that the invoking shell might already apply unescaping once, hence this might require double escaping!\&.
+.sp
+The
+\fBsystemd-sysusers.service\fR(8)
+and
+\fBsystemd-firstboot\fR(1)
+services read credentials configured this way for the purpose of configuring the container\*(Aqs root user\*(Aqs password and shell, as well as system locale, keymap and timezone during the first boot process of the container\&. This is particularly useful in combination with
+\fB\-\-volatile=yes\fR
+where every single boot appears as first boot, since configuration applied to
+/etc/
+is lost on container reboot cycles\&. See the respective man pages for details\&. Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-nspawn \-i image\&.raw \e
+          \-\-volatile=yes \e
+          \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \e
+          \-\-set\-credential=passwd\&.hashed\-password\&.root:\*(Aq$y$j9T$yAuRJu1o5HioZAGDYPU5d\&.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC\*(Aq \e
+          \-b
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The above command line will invoke the specified image file
+image\&.raw
+in volatile mode, i\&.e\&. with empty
+/etc/
+and
+/var/\&. The container payload will recognize this as a first boot, and will invoke
+systemd\-firstboot\&.service, which then reads the two passed credentials to configure the system\*(Aqs initial locale and root password\&.
+.sp
+Added in version 247\&.
+.RE
+.SS "Other"
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Download a Fedora image and start a shell in it\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# machinectl pull\-raw \-\-verify=no \e
+      https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora\-Cloud\-Base\-38\-1\&.6\&.x86_64\&.raw\&.xz \e
+      Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+# systemd\-nspawn \-M Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This downloads an image using
+\fBmachinectl\fR(1)
+and opens a shell in it\&.
+.PP
+\fBExample\ \&2.\ \&Build and boot a minimal Fedora distribution in a container\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# dnf \-y \-\-releasever=38 \-\-installroot=/var/lib/machines/f38 \e
+      \-\-repo=fedora \-\-repo=updates \-\-setopt=install_weak_deps=False install \e
+      passwd dnf fedora\-release vim\-minimal util\-linux systemd systemd\-networkd
+# systemd\-nspawn \-bD /var/lib/machines/f38
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This installs a minimal Fedora distribution into the directory
+/var/lib/machines/f38
+and then boots that OS in a namespace container\&. Because the installation is located underneath the standard
+/var/lib/machines/
+directory, it is also possible to start the machine using
+\fBsystemd\-nspawn \-M f38\fR\&.
+.PP
+\fBExample\ \&3.\ \&Spawn a shell in a container of a minimal Debian unstable distribution\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# debootstrap unstable ~/debian\-tree/
+# systemd\-nspawn \-D ~/debian\-tree/
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This installs a minimal Debian unstable distribution into the directory
+~/debian\-tree/
+and then spawns a shell from this image in a namespace container\&.
+.PP
+\fBdebootstrap\fR
+supports
+\m[blue]\fBDebian\fR\m[]\&\s-2\u[7]\d\s+2,
+\m[blue]\fBUbuntu\fR\m[]\&\s-2\u[8]\d\s+2, and
+\m[blue]\fBTanglu\fR\m[]\&\s-2\u[9]\d\s+2
+out of the box, so the same command can be used to install any of those\&. For other distributions from the Debian family, a mirror has to be specified, see
+\fBdebootstrap\fR(8)\&.
+.PP
+\fBExample\ \&4.\ \&Boot a minimal Arch Linux distribution in a container\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# pacstrap \-c ~/arch\-tree/ base
+# systemd\-nspawn \-bD ~/arch\-tree/
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This installs a minimal Arch Linux distribution into the directory
+~/arch\-tree/
+and then boots an OS in a namespace container in it\&.
+.PP
+\fBExample\ \&5.\ \&Install the OpenSUSE Tumbleweed rolling distribution\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# zypper \-\-root=/var/lib/machines/tumbleweed ar \-c \e
+      https://download\&.opensuse\&.org/tumbleweed/repo/oss tumbleweed
+# zypper \-\-root=/var/lib/machines/tumbleweed refresh
+# zypper \-\-root=/var/lib/machines/tumbleweed install \-\-no\-recommends \e
+      systemd shadow zypper openSUSE\-release vim
+# systemd\-nspawn \-M tumbleweed passwd root
+# systemd\-nspawn \-M tumbleweed \-b
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&6.\ \&Boot into an ephemeral snapshot of the host system\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-nspawn \-D / \-xb
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This runs a copy of the host system in a snapshot which is removed immediately when the container exits\&. All file system changes made during runtime will be lost on shutdown, hence\&.
+.PP
+\fBExample\ \&7.\ \&Run a container with SELinux sandbox security contexts\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \-R /srv/container
+# systemd\-nspawn \-L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \e
+      \-Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 \-D /srv/container /bin/sh
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&8.\ \&Run a container with an OSTree deployment\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-nspawn \-b \-i ~/image\&.raw \e
+      \-\-pivot\-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \e
+      \-\-bind=+/sysroot/ostree/deploy/$OS/var:/var
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXIT STATUS"
+.PP
+The exit code of the program executed in the container is returned\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd.nspawn\fR(5),
+\fBchroot\fR(1),
+\fBdnf\fR(8),
+\fBdebootstrap\fR(8),
+\fBpacman\fR(8),
+\fBzypper\fR(8),
+\fBsystemd.slice\fR(5),
+\fBmachinectl\fR(1),
+\fBbtrfs\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Container Interface
+.RS 4
+\%https://systemd.io/CONTAINER_INTERFACE
+.RE
+.IP " 2." 4
+Discoverable Partitions Specification
+.RS 4
+\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+.RE
+.IP " 3." 4
+OCI Runtime Specification
+.RS 4
+\%https://github.com/opencontainers/runtime-spec/blob/master/spec.md
+.RE
+.IP " 4." 4
+OSTree
+.RS 4
+\%https://ostree.readthedocs.io/en/latest/
+.RE
+.IP " 5." 4
+Overlay Filesystem
+.RS 4
+\%https://docs.kernel.org/filesystems/overlayfs.html
+.RE
+.IP " 6." 4
+Fedora
+.RS 4
+\%https://getfedora.org
+.RE
+.IP " 7." 4
+Debian
+.RS 4
+\%https://www.debian.org
+.RE
+.IP " 8." 4
+Ubuntu
+.RS 4
+\%https://www.ubuntu.com
+.RE
+.IP " 9." 4
+Tanglu
+.RS 4
+\%https://www.tanglu.org
+.RE
+.IP "10." 4
+Arch Linux
+.RS 4
+\%https://www.archlinux.org
+.RE
+.IP "11." 4
+OpenSUSE Tumbleweed
+.RS 4
+\%https://software.opensuse.org/distributions/tumbleweed
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-path.1 b/upstream/mageia-cauldron/man1/systemd-path.1
new file mode 100644
index 00000000..ca933fef
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-path.1
@@ -0,0 +1,70 @@
+'\" t
+.TH "SYSTEMD\-PATH" "1" "" "systemd 255" "systemd-path"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-path \- List and query system and user paths
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-path\fR\ 'u
+\fBsystemd\-path\fR [OPTIONS...] [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-path\fR
+may be used to query system and user paths\&. The tool makes many of the paths described in
+\fBfile-hierarchy\fR(7)
+available for querying\&.
+.PP
+When invoked without arguments, a list of known paths and their current values is shown\&. When at least one argument is passed, the path with this name is queried and its value shown\&. The variables whose name begins with
+"search\-"
+do not refer to individual paths, but instead to a list of colon\-separated search paths, in their order of precedence\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-suffix=\fR
+.RS 4
+Printed paths are suffixed by the specified string\&.
+.sp
+Added in version 215\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBfile-hierarchy\fR(7)
diff --git a/upstream/mageia-cauldron/man1/systemd-run.1 b/upstream/mageia-cauldron/man1/systemd-run.1
new file mode 100644
index 00000000..b2792c09
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-run.1
@@ -0,0 +1,759 @@
+'\" t
+.TH "SYSTEMD\-RUN" "1" "" "systemd 255" "systemd-run"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-run \- Run programs in transient scope units, service units, or path\-, socket\-, or timer\-triggered service units
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-run\fR\ 'u
+\fBsystemd\-run\fR [OPTIONS...] \fICOMMAND\fR\ [ARGS...] 
+.HP \w'\fBsystemd\-run\fR\ 'u
+\fBsystemd\-run\fR [OPTIONS...] [PATH\ OPTIONS...] {\fICOMMAND\fR} [ARGS...]
+.HP \w'\fBsystemd\-run\fR\ 'u
+\fBsystemd\-run\fR [OPTIONS...] [SOCKET\ OPTIONS...] {\fICOMMAND\fR} [ARGS...]
+.HP \w'\fBsystemd\-run\fR\ 'u
+\fBsystemd\-run\fR [OPTIONS...] [TIMER\ OPTIONS...] {\fICOMMAND\fR} [ARGS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-run\fR
+may be used to create and start a transient
+\&.service
+or
+\&.scope
+unit and run the specified
+\fICOMMAND\fR
+in it\&. It may also be used to create and start a transient
+\&.path,
+\&.socket, or
+\&.timer
+unit, that activates a
+\&.service
+unit when elapsing\&.
+.PP
+If a command is run as transient service unit, it will be started and managed by the service manager like any other service, and thus shows up in the output of
+\fBsystemctl list\-units\fR
+like any other unit\&. It will run in a clean and detached execution environment, with the service manager as its parent process\&. In this mode,
+\fBsystemd\-run\fR
+will start the service asynchronously in the background and return after the command has begun execution (unless
+\fB\-\-no\-block\fR
+or
+\fB\-\-wait\fR
+are specified, see below)\&.
+.PP
+If a command is run as transient scope unit, it will be executed by
+\fBsystemd\-run\fR
+itself as parent process and will thus inherit the execution environment of the caller\&. However, the processes of the command are managed by the service manager similarly to normal services, and will show up in the output of
+\fBsystemctl list\-units\fR\&. Execution in this case is synchronous, and will return only when the command finishes\&. This mode is enabled via the
+\fB\-\-scope\fR
+switch (see below)\&.
+.PP
+If a command is run with path, socket, or timer options such as
+\fB\-\-on\-calendar=\fR
+(see below), a transient path, socket, or timer unit is created alongside the service unit for the specified command\&. Only the transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the path, socket, or timer unit\&. If the
+\fB\-\-unit=\fR
+option is specified, the
+\fICOMMAND\fR
+may be omitted\&. In this case,
+\fBsystemd\-run\fR
+creates only a
+\&.path,
+\&.socket, or
+\&.timer
+unit that triggers the specified unit\&.
+.PP
+By default, services created with
+\fBsystemd\-run\fR
+default to the
+\fBsimple\fR
+type, see the description of
+\fIType=\fR
+in
+\fBsystemd.service\fR(5)
+for details\&. Note that when this type is used, the service manager (and thus the
+\fBsystemd\-run\fR
+command) considers service start\-up successful as soon as the
+\fBfork()\fR
+for the main service process succeeded, i\&.e\&. before the
+\fBexecve()\fR
+is invoked, and thus even if the specified command cannot be started\&. Consider using the
+\fBexec\fR
+service type (i\&.e\&.
+\fB\-\-property=Type=exec\fR) to ensure that
+\fBsystemd\-run\fR
+returns successfully only if the specified command line has been successfully started\&.
+.PP
+After
+\fBsystemd\-run\fR
+passes the command to the service manager, the manager performs variable expansion\&. This means that dollar characters ("$") which should not be expanded need to be escaped as
+"$$"\&. Expansion can also be disabled using
+\fI\-\-expand\-environment=no\fR\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.sp
+Added in version 226\&.
+.RE
+.PP
+\fB\-\-scope\fR
+.RS 4
+Create a transient
+\&.scope
+unit instead of the default transient
+\&.service
+unit (see above)\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-unit=\fR, \fB\-u\fR
+.RS 4
+Use this unit name instead of an automatically generated one\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-property=\fR, \fB\-p\fR
+.RS 4
+Sets a property on the scope or service unit that is created\&. This option takes an assignment in the same format as
+\fBsystemctl\fR(1)\*(Aqs
+\fBset\-property\fR
+command\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-description=\fR
+.RS 4
+Provide a description for the service, scope, path, socket, or timer unit\&. If not specified, the command itself will be used as a description\&. See
+\fIDescription=\fR
+in
+\fBsystemd.unit\fR(5)\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-slice=\fR
+.RS 4
+Make the new
+\&.service
+or
+\&.scope
+unit part of the specified slice, instead of
+system\&.slice
+(when running in
+\fB\-\-system\fR
+mode) or the root slice (when running in
+\fB\-\-user\fR
+mode)\&.
+.sp
+Added in version 206\&.
+.RE
+.PP
+\fB\-\-slice\-inherit\fR
+.RS 4
+Make the new
+\&.service
+or
+\&.scope
+unit part of the inherited slice\&. This option can be combined with
+\fB\-\-slice=\fR\&.
+.sp
+An inherited slice is located within
+\fBsystemd\-run\fR
+slice\&. Example: if
+\fBsystemd\-run\fR
+slice is
+foo\&.slice, and the
+\fB\-\-slice=\fR
+argument is
+bar, the unit will be placed under the
+foo\-bar\&.slice\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-expand\-environment=\fR\fB\fIBOOL\fR\fR
+.RS 4
+Expand environment variables in command arguments\&. If enabled, environment variables specified as
+"${\fIVARIABLE\fR}"
+will be expanded in the same way as in commands specified via
+\fIExecStart=\fR
+in units\&. With
+\fI\-\-scope\fR, this expansion is performed by
+\fBsystemd\-run\fR
+itself, and in other cases by the service manager that spawns the command\&. Note that this is similar to, but not the same as variable expansion in
+\fBbash\fR(1)
+and other shells\&.
+.sp
+The default is to enable this option in all cases, except for
+\fI\-\-scope\fR
+where it is disabled by default, for backward compatibility reasons\&. Note that this will be changed in a future release, where it will be switched to enabled by default as well\&.
+.sp
+See
+\fBsystemd.service\fR(5)
+for a description of variable expansion\&. Disabling variable expansion is useful if the specified command includes or may include a
+"$"
+sign\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-remain\-after\-exit\fR
+.RS 4
+After the service process has terminated, keep the service around until it is explicitly stopped\&. This is useful to collect runtime information about the service after it finished running\&. Also see
+\fIRemainAfterExit=\fR
+in
+\fBsystemd.service\fR(5)\&.
+.sp
+Added in version 207\&.
+.RE
+.PP
+\fB\-\-send\-sighup\fR
+.RS 4
+When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM\&. This is useful to indicate to shells and shell\-like processes that the connection has been severed\&. Also see
+\fISendSIGHUP=\fR
+in
+\fBsystemd.kill\fR(5)\&.
+.sp
+Added in version 207\&.
+.RE
+.PP
+\fB\-\-service\-type=\fR
+.RS 4
+Sets the service type\&. Also see
+\fIType=\fR
+in
+\fBsystemd.service\fR(5)\&. This option has no effect in conjunction with
+\fB\-\-scope\fR\&. Defaults to
+\fBsimple\fR\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-uid=\fR, \fB\-\-gid=\fR
+.RS 4
+Runs the service process under the specified UNIX user and group\&. Also see
+\fIUser=\fR
+and
+\fIGroup=\fR
+in
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-nice=\fR
+.RS 4
+Runs the service process with the specified nice level\&. Also see
+\fINice=\fR
+in
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-working\-directory=\fR
+.RS 4
+Runs the service process with the specified working directory\&. Also see
+\fIWorkingDirectory=\fR
+in
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-\-same\-dir\fR, \fB\-d\fR
+.RS 4
+Similar to
+\fB\-\-working\-directory=\fR, but uses the current working directory of the caller for the service to execute\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-E \fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR, \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
+.RS 4
+Runs the service process with the specified environment variable set\&. This parameter may be used more than once to set multiple variables\&. When
+"="
+and
+\fIVALUE\fR
+are omitted, the value of the variable with the same name in the program environment will be used\&.
+.sp
+Also see
+\fIEnvironment=\fR
+in
+\fBsystemd.exec\fR(5)\&.
+.sp
+Added in version 211\&.
+.RE
+.PP
+\fB\-\-pty\fR, \fB\-t\fR
+.RS 4
+When invoking the command, the transient service connects its standard input, output and error to the terminal
+\fBsystemd\-run\fR
+is invoked on, via a pseudo TTY device\&. This allows running programs that expect interactive user input/output as services, such as interactive command shells\&.
+.sp
+Note that
+\fBmachinectl\fR(1)\*(Aqs
+\fBshell\fR
+command is usually a better alternative for requesting a new, interactive login session on the local host or a local container\&.
+.sp
+See below for details on how this switch combines with
+\fB\-\-pipe\fR\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-pipe\fR, \fB\-P\fR
+.RS 4
+If specified, standard input, output, and error of the transient service are inherited from the
+\fBsystemd\-run\fR
+command itself\&. This allows
+\fBsystemd\-run\fR
+to be used within shell pipelines\&. Note that this mode is not suitable for interactive command shells and similar, as the service process will not become a TTY controller when invoked on a terminal\&. Use
+\fB\-\-pty\fR
+instead in that case\&.
+.sp
+When both
+\fB\-\-pipe\fR
+and
+\fB\-\-pty\fR
+are used in combination the more appropriate option is automatically determined and used\&. Specifically, when invoked with standard input, output and error connected to a TTY
+\fB\-\-pty\fR
+is used, and otherwise
+\fB\-\-pipe\fR\&.
+.sp
+When this option is used the original file descriptors
+\fBsystemd\-run\fR
+receives are passed to the service processes as\-is\&. If the service runs with different privileges than
+\fBsystemd\-run\fR, this means the service might not be able to re\-open the passed file descriptors, due to normal file descriptor access restrictions\&. If the invoked process is a shell script that uses the
+\fBecho "hello" >/dev/stderr\fR
+construct for writing messages to stderr, this might cause problems, as this only works if stderr can be re\-opened\&. To mitigate this use the construct
+\fBecho "hello" >&2\fR
+instead, which is mostly equivalent and avoids this pitfall\&.
+.sp
+Added in version 235\&.
+.RE
+.PP
+\fB\-\-shell\fR, \fB\-S\fR
+.RS 4
+A shortcut for
+"\-\-pty \-\-same\-dir \-\-wait \-\-collect \-\-service\-type=exec $SHELL", i\&.e\&. requests an interactive shell in the current working directory, running in service context, accessible with a single switch\&.
+.sp
+Added in version 240\&.
+.RE
+.PP
+\fB\-\-quiet\fR, \fB\-q\fR
+.RS 4
+Suppresses additional informational output while running\&. This is particularly useful in combination with
+\fB\-\-pty\fR
+when it will suppress the initial message explaining how to terminate the TTY connection\&.
+.sp
+Added in version 219\&.
+.RE
+.PP
+\fB\-\-on\-active=\fR, \fB\-\-on\-boot=\fR, \fB\-\-on\-startup=\fR, \fB\-\-on\-unit\-active=\fR, \fB\-\-on\-unit\-inactive=\fR
+.RS 4
+Defines a monotonic timer relative to different starting points for starting the specified command\&. See
+\fIOnActiveSec=\fR,
+\fIOnBootSec=\fR,
+\fIOnStartupSec=\fR,
+\fIOnUnitActiveSec=\fR
+and
+\fIOnUnitInactiveSec=\fR
+in
+\fBsystemd.timer\fR(5)
+for details\&. These options are shortcuts for
+\fB\-\-timer\-property=\fR
+with the relevant properties\&. These options may not be combined with
+\fB\-\-scope\fR
+or
+\fB\-\-pty\fR\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-on\-calendar=\fR
+.RS 4
+Defines a calendar timer for starting the specified command\&. See
+\fIOnCalendar=\fR
+in
+\fBsystemd.timer\fR(5)\&. This option is a shortcut for
+\fB\-\-timer\-property=OnCalendar=\fR\&. This option may not be combined with
+\fB\-\-scope\fR
+or
+\fB\-\-pty\fR\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-on\-clock\-change\fR, \fB\-\-on\-timezone\-change\fR
+.RS 4
+Defines a trigger based on system clock jumps or timezone changes for starting the specified command\&. See
+\fIOnClockChange=\fR
+and
+\fIOnTimezoneChange=\fR
+in
+\fBsystemd.timer\fR(5)\&. These options are shortcuts for
+\fB\-\-timer\-property=OnClockChange=yes\fR
+and
+\fB\-\-timer\-property=OnTimezoneChange=yes\fR\&. These options may not be combined with
+\fB\-\-scope\fR
+or
+\fB\-\-pty\fR\&.
+.sp
+Added in version 242\&.
+.RE
+.PP
+\fB\-\-path\-property=\fR, \fB\-\-socket\-property=\fR, \fB\-\-timer\-property=\fR
+.RS 4
+Sets a property on the path, socket, or timer unit that is created\&. This option is similar to
+\fB\-\-property=\fR, but applies to the transient path, socket, or timer unit rather than the transient service unit created\&. This option takes an assignment in the same format as
+\fBsystemctl\fR(1)\*(Aqs
+\fBset\-property\fR
+command\&. These options may not be combined with
+\fB\-\-scope\fR
+or
+\fB\-\-pty\fR\&.
+.sp
+Added in version 218\&.
+.RE
+.PP
+\fB\-\-no\-block\fR
+.RS 4
+Do not synchronously wait for the unit start operation to finish\&. If this option is not specified, the start request for the transient unit will be verified, enqueued and
+\fBsystemd\-run\fR
+will wait until the unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&. This option may not be combined with
+\fB\-\-wait\fR\&.
+.sp
+Added in version 220\&.
+.RE
+.PP
+\fB\-\-wait\fR
+.RS 4
+Synchronously wait for the transient service to terminate\&. If this option is specified, the start request for the transient unit is verified, enqueued, and waited for\&. Subsequently the invoked unit is monitored, and it is waited until it is deactivated again (most likely because the specified command completed)\&. On exit, terse information about the unit\*(Aqs runtime is shown, including total runtime (as well as CPU usage, if
+\fB\-\-property=CPUAccounting=1\fR
+was set) and the exit code and status of the main process\&. This output may be suppressed with
+\fB\-\-quiet\fR\&. This option may not be combined with
+\fB\-\-no\-block\fR,
+\fB\-\-scope\fR
+or the various path, socket, or timer options\&.
+.sp
+Added in version 232\&.
+.RE
+.PP
+\fB\-G\fR, \fB\-\-collect\fR
+.RS 4
+Unload the transient unit after it completed, even if it failed\&. Normally, without this option, all units that ran and failed are kept in memory until the user explicitly resets their failure state with
+\fBsystemctl reset\-failed\fR
+or an equivalent command\&. On the other hand, units that ran successfully are unloaded immediately\&. If this option is turned on the "garbage collection" of units is more aggressive, and unloads units regardless if they exited successfully or failed\&. This option is a shortcut for
+\fB\-\-property=CollectMode=inactive\-or\-failed\fR, see the explanation for
+\fICollectMode=\fR
+in
+\fBsystemd.unit\fR(5)
+for further information\&.
+.sp
+Added in version 236\&.
+.RE
+.PP
+\fB\-\-user\fR
+.RS 4
+Talk to the service manager of the calling user, rather than the service manager of the system\&.
+.RE
+.PP
+\fB\-\-system\fR
+.RS 4
+Talk to the service manager of the system\&. This is the implied default\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+All command line arguments after the first non\-option argument become part of the command line of the launched process\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned\&. If
+\fBsystemd\-run\fR
+failed to start the service, a non\-zero return value will be returned\&. If
+\fBsystemd\-run\fR
+waits for the service to terminate, the return value will be propagated from the service\&. 0 will be returned on success, including all the cases where systemd considers a service to have exited cleanly, see the discussion of
+\fISuccessExitStatus=\fR
+in
+\fBsystemd.service\fR(5)\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Logging environment variables provided by systemd to services\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-run env
+Running as unit: run\-19945\&.service
+# journalctl \-u run\-19945\&.service
+Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env\&.\&.\&.
+Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env\&.
+Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
+Sep 08 07:37:21 bupkis env[19948]: LANG=en_US\&.UTF\-8
+Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz\-3\&.11\&.0\-0\&.rc5\&.git6\&.2\&.fc20\&.x86_64
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Limiting resources available to a command\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-run \-p IOWeight=10 updatedb
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This command invokes the
+\fBupdatedb\fR(8)
+tool, but lowers the block I/O weight for it to 10\&. See
+\fBsystemd.resource-control\fR(5)
+for more information on the
+\fIIOWeight=\fR
+property\&.
+.PP
+\fBExample\ \&3.\ \&Running commands at a specified time\fR
+.PP
+The following command will touch a file after 30 seconds\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# date; systemd\-run \-\-on\-active=30 \-\-timer\-property=AccuracySec=100ms /bin/touch /tmp/foo
+Mon Dec  8 20:44:24 KST 2014
+Running as unit: run\-71\&.timer
+Will run service as unit: run\-71\&.service
+# journalctl \-b \-u run\-71\&.timer
+\-\- Journal begins at Fri 2014\-12\-05 19:09:21 KST, ends at Mon 2014\-12\-08 20:44:54 KST\&. \-\-
+Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo\&.
+Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo\&.
+# journalctl \-b \-u run\-71\&.service
+\-\- Journal begins at Fri 2014\-12\-05 19:09:21 KST, ends at Mon 2014\-12\-08 20:44:54 KST\&. \-\-
+Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo\&.\&.\&.
+Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&4.\ \&Allowing access to the tty\fR
+.PP
+The following command invokes
+\fBbash\fR(1)
+as a service passing its standard input, output and error to the calling TTY\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-run \-t \-\-send\-sighup bash
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&5.\ \&Start screen as a user service\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-run \-\-scope \-\-user screen
+Running scope as unit run\-r14b0047ab6df45bfb45e7786cc839e76\&.scope\&.
+
+$ screen \-ls
+There is a screen on:
+        492\&.\&.laptop     (Detached)
+1 Socket in /var/run/screen/S\-fatima\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This starts the
+\fBscreen\fR
+process as a child of the
+\fBsystemd \-\-user\fR
+process that was started by
+user@\&.service, in a scope unit\&. A
+\fBsystemd.scope\fR(5)
+unit is used instead of a
+\fBsystemd.service\fR(5)
+unit, because
+\fBscreen\fR
+will exit when detaching from the terminal, and a service unit would be terminated\&. Running
+\fBscreen\fR
+as a user unit has the advantage that it is not part of the session scope\&. If
+\fIKillUserProcesses=yes\fR
+is configured in
+\fBlogind.conf\fR(5), the default, the session scope will be terminated when the user logs out of that session\&.
+.PP
+The
+user@\&.service
+is started automatically when the user first logs in, and stays around as long as at least one login session is open\&. After the user logs out of the last session,
+user@\&.service
+and all services underneath it are terminated\&. This behavior is the default, when "lingering" is not enabled for that user\&. Enabling lingering means that
+user@\&.service
+is started automatically during boot, even if the user is not logged in, and that the service is not terminated when the user logs out\&.
+.PP
+Enabling lingering allows the user to run processes without being logged in, for example to allow
+\fBscreen\fR
+to persist after the user logs out, even if the session scope is terminated\&. In the default configuration, users can enable lingering for themselves:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ loginctl enable\-linger
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&6.\ \&Variable expansion by the manager\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-run \-t echo "<${INVOCATION_ID}>" \*(Aq<${INVOCATION_ID}>\*(Aq
+      <> <5d0149bfa2c34b79bccb13074001eb20>
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The first argument is expanded by the shell (double quotes), but the second one is not expanded by the shell (single quotes)\&.
+\fBecho\fR(1)
+is called with ["/usr/bin/echo",
+"<>",
+"<${INVOCATION_ID}>"] as the argument array, and then
+\fBsystemd\fR(1)
+generates
+\fI${INVOCATION_ID}\fR
+and substitutes it in the command\-line\&. This substitution could not be done on the client side, because the target ID that will be set for the service isn\*(Aqt known before the call is made\&.
+.PP
+\fBExample\ \&7.\ \&Variable expansion and output redirection using a shell\fR
+.PP
+Variable expansion by
+\fBsystemd\fR(1)
+can be disabled with
+\fI\-\-expand\-environment=no\fR\&.
+.PP
+Disabling variable expansion can be useful if the command to execute contains dollar characters and escaping them would be inconvenient\&. For example, when a shell is used:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-run \-\-expand\-environment=no \-t bash \e
+      \-c \*(Aqecho $SHELL $$ >/dev/stdout\*(Aq
+/bin/bash 12345
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The last argument is passed verbatim to the
+\fBbash\fR(1)
+shell which is started by the service unit\&. The shell expands
+"$SHELL"
+to the path of the shell, and
+"$$"
+to its process number, and then those strings are passed to the
+\fBecho\fR
+built\-in and printed to standard output (which in this case is connected to the calling terminal)\&.
+.PP
+\fBExample\ \&8.\ \&Return value\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-run \-\-user \-\-wait true
+$ systemd\-run \-\-user \-\-wait \-p SuccessExitStatus=11 bash \-c \*(Aqexit 11\*(Aq
+$ systemd\-run \-\-user \-\-wait \-p SuccessExitStatus=SIGUSR1 \-\-expand\-environment=no \e
+      bash \-c \*(Aqkill \-SIGUSR1 $$\*(Aq
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Those three invocations will succeed, i\&.e\&. terminate with an exit code of 0\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd.unit\fR(5),
+\fBsystemd.service\fR(5),
+\fBsystemd.scope\fR(5),
+\fBsystemd.slice\fR(5),
+\fBsystemd.exec\fR(5),
+\fBsystemd.resource-control\fR(5),
+\fBsystemd.timer\fR(5),
+\fBsystemd-mount\fR(1),
+\fBmachinectl\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-socket-activate.1 b/upstream/mageia-cauldron/man1/systemd-socket-activate.1
new file mode 100644
index 00000000..e9235e31
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-socket-activate.1
@@ -0,0 +1,176 @@
+'\" t
+.TH "SYSTEMD\-SOCKET\-ACTIVATE" "1" "" "systemd 255" "systemd-socket-activate"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-socket-activate \- Test socket activation of daemons
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-socket\-activate\fR\ 'u
+\fBsystemd\-socket\-activate\fR [OPTIONS...] \fIdaemon\fR [OPTIONS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-socket\-activate\fR
+may be used to launch a socket\-activated service program from the command line for testing purposes\&. It may also be used to launch individual instances of the service program per connection\&.
+.PP
+The daemon to launch and its options should be specified after options intended for
+\fBsystemd\-socket\-activate\fR\&.
+.PP
+If the
+\fB\-\-inetd\fR
+option is given, the socket file descriptor will be used as the standard input and output of the launched process\&. Otherwise, standard input and output will be inherited, and sockets will be passed through file descriptors 3 and higher\&. Sockets passed through
+\fI$LISTEN_FDS\fR
+to
+\fBsystemd\-socket\-activate\fR
+will be passed through to the daemon, in the original positions\&. Other sockets specified with
+\fB\-\-listen=\fR
+will use consecutive descriptors\&. By default,
+\fBsystemd\-socket\-activate\fR
+listens on a stream socket, use
+\fB\-\-datagram\fR
+and
+\fB\-\-seqpacket\fR
+to listen on datagram or sequential packet sockets instead (see below)\&.
+.SH "OPTIONS"
+.PP
+\fB\-l \fR\fB\fIaddress\fR\fR, \fB\-\-listen=\fR\fB\fIaddress\fR\fR
+.RS 4
+Listen on this
+\fIaddress\fR\&. Takes a string like
+"2000"
+or
+"127\&.0\&.0\&.1:2001"\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-accept\fR
+.RS 4
+Launch an instance of the service program for each connection and pass the connection socket\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-d\fR, \fB\-\-datagram\fR
+.RS 4
+Listen on a datagram socket (\fBSOCK_DGRAM\fR), instead of a stream socket (\fBSOCK_STREAM\fR)\&. May not be combined with
+\fB\-\-seqpacket\fR\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-seqpacket\fR
+.RS 4
+Listen on a sequential packet socket (\fBSOCK_SEQPACKET\fR), instead of a stream socket (\fBSOCK_STREAM\fR)\&. May not be combined with
+\fB\-\-datagram\fR\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-inetd\fR
+.RS 4
+Use the inetd protocol for passing file descriptors, i\&.e\&. as standard input and standard output, instead of the new\-style protocol for passing file descriptors using
+\fI$LISTEN_FDS\fR
+(see above)\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-E \fR\fB\fIVAR\fR\fR\fB[=\fIVALUE\fR]\fR, \fB\-\-setenv=\fR\fB\fIVAR\fR\fR\fB[=\fIVALUE\fR]\fR
+.RS 4
+Add this variable to the environment of the launched process\&. If
+\fIVAR\fR
+is followed by
+"=", assume that it is a variable\(envalue pair\&. Otherwise, obtain the value from the environment of
+\fBsystemd\-socket\-activate\fR
+itself\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-\-fdname=\fR\fINAME\fR[:\fINAME\fR\&...]
+.RS 4
+Specify names for the file descriptors passed\&. This is equivalent to setting
+\fIFileDescriptorName=\fR
+in socket unit files, and enables use of
+\fBsd_listen_fds_with_names\fR(3)\&. Multiple entries may be specifies using separate options or by separating names with colons (":") in one option\&. In case more names are given than descriptors, superfluous ones will be ignored\&. In case less names are given than descriptors, the remaining file descriptors will be unnamed\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "ENVIRONMENT VARIABLES"
+.PP
+\fI$LISTEN_FDS\fR, \fI$LISTEN_PID\fR, \fI$LISTEN_FDNAMES\fR
+.RS 4
+See
+\fBsd_listen_fds\fR(3)\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR, \fI$SYSTEMD_LOG_LEVEL\fR, \fI$SYSTEMD_LOG_TIME\fR, \fI$SYSTEMD_LOG_COLOR\fR, \fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+Same as in
+\fBsystemd\fR(1)\&.
+.sp
+Added in version 230\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Run an echo server on port 2000\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-socket\-activate \-l 2000 \-\-inetd \-a cat
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Run a socket\-activated instance of systemd-journal-gatewayd(8)\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemd\-socket\-activate \-l 19531 /usr/lib/systemd/systemd\-journal\-gatewayd
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd.socket\fR(5),
+\fBsystemd.service\fR(5),
+\fBsystemd-run\fR(1),
+\fBsd_listen_fds\fR(3),
+\fBsd_listen_fds_with_names\fR(3),
+\fBcat\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd-stdio-bridge.1 b/upstream/mageia-cauldron/man1/systemd-stdio-bridge.1
new file mode 100644
index 00000000..e5c06413
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-stdio-bridge.1
@@ -0,0 +1,105 @@
+'\" t
+.TH "SYSTEMD\-STDIO\-BRIDGE" "1" "" "systemd 255" "systemd-stdio-bridge"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-stdio-bridge \- D\-Bus proxy
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-stdio\-bridge\fR\ 'u
+\fBsystemd\-stdio\-bridge\fR [OPTIONS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-stdio\-bridge\fR
+implements a proxy between STDIN/STDOUT and a D\-Bus bus\&. It expects to receive an open connection via STDIN/STDOUT when started, and will create a new connection to the specified bus\&. It will then forward messages between the two connections\&. This program is suitable for socket activation: the first connection may be a pipe or a socket and must be passed as either standard input, or as an open file descriptor according to the protocol described in
+\fBsd_listen_fds\fR(3)\&. The second connection will be made by default to the local system bus, but this can be influenced by the
+\fB\-\-user\fR,
+\fB\-\-system\fR,
+\fB\-\-machine=\fR, and
+\fB\-\-bus\-path=\fR
+options described below\&.
+.PP
+\fBsd-bus\fR(3)
+uses
+\fBsystemd\-stdio\-bridge\fR
+to forward D\-Bus connections over
+\fBssh\fR(1), or to connect to the bus of a different user, see
+\fBsd_bus_set_address\fR(3)\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-user\fR
+.RS 4
+Talk to the service manager of the calling user, rather than the service manager of the system\&.
+.RE
+.PP
+\fB\-\-system\fR
+.RS 4
+Talk to the service manager of the system\&. This is the implied default\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-p \fR\fB\fIPATH\fR\fR, \fB\-\-bus\-path=\fR\fB\fIPATH\fR\fR
+.RS 4
+Path to the bus address\&. Default:
+"unix:path=/run/dbus/system_bus_socket"
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBdbus-daemon\fR(1),
+\fBdbus-broker\fR(1),
+\m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[1]\d\s+2,
+\fBsystemd\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+D-Bus
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/dbus
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-tty-ask-password-agent.1 b/upstream/mageia-cauldron/man1/systemd-tty-ask-password-agent.1
new file mode 100644
index 00000000..d6643734
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-tty-ask-password-agent.1
@@ -0,0 +1,116 @@
+'\" t
+.TH "SYSTEMD\-TTY\-ASK\-PASSWORD\-AGENT" "1" "" "systemd 255" "systemd-tty-ask-password-agent"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-tty-ask-password-agent \- List or process pending systemd password requests
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-tty\-ask\-password\-agent\fR\ 'u
+\fBsystemd\-tty\-ask\-password\-agent\fR [OPTIONS...] [VARIABLE=VALUE...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-tty\-ask\-password\-agent\fR
+is a password agent that handles password requests of the system, for example for hard disk encryption passwords or SSL certificate passwords that need to be queried at boot\-time or during runtime\&.
+.PP
+\fBsystemd\-tty\-ask\-password\-agent\fR
+implements the
+\m[blue]\fBPassword Agents Specification\fR\m[]\&\s-2\u[1]\d\s+2, and is one of many possible response agents which answer to queries formulated with
+\fBsystemd-ask-password\fR(1)\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-list\fR
+.RS 4
+Lists all currently pending system password requests\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-query\fR
+.RS 4
+Process all currently pending system password requests by querying the user on the calling TTY\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-watch\fR
+.RS 4
+Continuously process password requests\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-wall\fR
+.RS 4
+Forward password requests to
+\fBwall\fR(1)
+instead of querying the user on the calling TTY\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-plymouth\fR
+.RS 4
+Ask question with
+\fBplymouth\fR(8)
+instead of querying the user on the calling TTY\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-\-console\fR[=\fIDEVICE\fR]
+.RS 4
+Ask question on TTY
+\fIDEVICE\fR
+instead of querying the user on the calling TTY\&. If
+\fIDEVICE\fR
+is not specified,
+/dev/console
+will be used\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemctl\fR(1),
+\fBsystemd-ask-password-console.service\fR(8),
+\fBwall\fR(1),
+\fBplymouth\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Password Agents Specification
+.RS 4
+\%https://systemd.io/PASSWORD_AGENTS/
+.RE
diff --git a/upstream/mageia-cauldron/man1/systemd-vmspawn.1 b/upstream/mageia-cauldron/man1/systemd-vmspawn.1
new file mode 100644
index 00000000..85b7c5e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd-vmspawn.1
@@ -0,0 +1,378 @@
+'\" t
+.TH "SYSTEMD\-VMSPAWN" "1" "" "systemd 255" "systemd-vmspawn"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd-vmspawn \- Spawn an OS in a virtual machine\&.
+.SH "SYNOPSIS"
+.HP \w'\fBsystemd\-vmspawn\fR\ 'u
+\fBsystemd\-vmspawn\fR [OPTIONS...] [ARGS...]
+.SH "DESCRIPTION"
+.PP
+\fBsystemd\-vmspawn\fR
+may be used to start a virtual machine from an OS image\&. In many ways it is similar to
+\fBsystemd-nspawn\fR(1), but it launches a full virtual machine instead of using namespaces\&.
+.PP
+Note: on Ubuntu/Debian derivatives systemd\-vmspawn requires the user to be in the
+"kvm"
+group to use the VSock options\&.
+.SH "OPTIONS"
+.PP
+The excess arguments are passed as extra kernel command line arguments using SMBIOS\&.
+.PP
+The following options are understood:
+.SS "Image Options"
+.PP
+\fB\-i\fR, \fB\-\-image=\fR
+.RS 4
+Root file system disk image (or device node) for the virtual machine\&.
+.sp
+Added in version 255\&.
+.RE
+.SS "Host Configuration"
+.PP
+\fB\-\-qemu\-smp=\fR\fISMP\fR
+.RS 4
+Configures the number of CPUs to start the virtual machine with\&. Defaults to 1\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-qemu\-mem=\fR\fIMEM\fR
+.RS 4
+Configures the amount of memory to start the virtual machine with\&. Defaults to 2G\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-qemu\-kvm=\fR\fIBOOL\fR
+.RS 4
+Configures whether to use KVM\&. If the option is not specified KVM support will be detected automatically\&. If true, KVM is always used, and if false, KVM is never used\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-qemu\-vsock=\fR\fIBOOL\fR
+.RS 4
+Configure whether to use VSock networking\&.
+.sp
+If the option is not specified VSock support will be detected automatically\&. If yes is specified VSocks are always used, and vice versa if no is set VSocks are never used\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-vsock\-cid=\fR\fICID\fR
+.RS 4
+Configure vmspawn to use a specific CID for the guest\&.
+.sp
+If the option is not specified or an empty argument is supplied the guest will be assigned a random CID\&.
+.sp
+Valid CIDs are in the range
+\fB3\fR
+to
+\fB4294967294\fR
+(\fB0xFFFF_FFFE\fR)\&. CIDs outside of this range are reserved\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-qemu\-gui\fR
+.RS 4
+Start QEMU in graphical mode\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-secure\-boot=\fR\fIBOOL\fR
+.RS 4
+Configure whether to search for firmware which supports Secure Boot\&.
+.sp
+If the option is not specified the first firmware which is detected will be used\&. If the option is set to yes then the first firmware with Secure Boot support will be selected\&. If no is specified then the first firmware without Secure Boot will be selected\&.
+.sp
+Added in version 255\&.
+.RE
+.SS "System Identity Options"
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Sets the machine name for this container\&. This name may be used to identify this container during its runtime (for example in tools like
+\fBmachinectl\fR(1)
+and similar)\&.
+.sp
+Added in version 255\&.
+.RE
+.SS "Credentials"
+.PP
+\fB\-\-load\-credential=\fR\fIID\fR:\fIPATH\fR, \fB\-\-set\-credential=\fR\fIID\fR:\fIVALUE\fR
+.RS 4
+Pass a credential to the container\&. These two options correspond to the
+\fILoadCredential=\fR
+and
+\fISetCredential=\fR
+settings in unit files\&. See
+\fBsystemd.exec\fR(5)
+for details about these concepts, as well as the syntax of the option\*(Aqs arguments\&.
+.sp
+In order to embed binary data into the credential data for
+\fB\-\-set\-credential=\fR, use C\-style escaping (i\&.e\&.
+"\en"
+to embed a newline, or
+"\ex00"
+to embed a
+\fBNUL\fR
+byte)\&. Note that the invoking shell might already apply unescaping once, hence this might require double escaping!\&.
+.sp
+Added in version 255\&.
+.RE
+.SS "Other"
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Run an Arch Linux VM image generated by mkosi\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ mkosi \-d arch \-p systemd \-p linux \-\-autologin \-o image\&.raw \-f build
+$ systemd\-vmspawn \-\-image=image\&.raw
+      
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXIT STATUS"
+.PP
+If an error occurred the value errno is propagated to the return code\&. If EXIT_STATUS is supplied by the running image that is returned\&. Otherwise EXIT_SUCCESS is returned\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBmkosi\fR(1)
diff --git a/upstream/mageia-cauldron/man1/systemd.1 b/upstream/mageia-cauldron/man1/systemd.1
new file mode 100644
index 00000000..24ba6297
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/systemd.1
@@ -0,0 +1,1566 @@
+'\" t
+.TH "SYSTEMD" "1" "" "systemd 255" "systemd"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+systemd, init \- systemd system and service manager
+.SH "SYNOPSIS"
+.HP \w'\fB/usr/lib/systemd/systemd\fR\ 'u
+\fB/usr/lib/systemd/systemd\fR [OPTIONS...]
+.HP \w'\fBinit\fR\ 'u
+\fBinit\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+systemd is a system and service manager for Linux operating systems\&. When run as first process on boot (as PID 1), it acts as init system that brings up and maintains userspace services\&. Separate instances are started for logged\-in users to start their services\&.
+.PP
+\fBsystemd\fR
+is usually not invoked directly by the user, but is installed as the
+/sbin/init
+symlink and started during early boot\&. The user manager instances are started automatically through the
+\fBuser@.service\fR(5)
+service\&.
+.PP
+For compatibility with SysV, if the binary is called as
+\fBinit\fR
+and is not the first process on the machine (PID is not 1), it will execute
+\fBtelinit\fR
+and pass all command line arguments unmodified\&. That means
+\fBinit\fR
+and
+\fBtelinit\fR
+are mostly equivalent when invoked from normal login sessions\&. See
+\fBtelinit\fR(8)
+for more information\&.
+.PP
+When run as a system instance, systemd interprets the configuration file
+system\&.conf
+and the files in
+system\&.conf\&.d
+directories; when run as a user instance, systemd interprets the configuration file
+user\&.conf
+and the files in
+user\&.conf\&.d
+directories\&. See
+\fBsystemd-system.conf\fR(5)
+for more information\&.
+.SH "CONCEPTS"
+.PP
+systemd provides a dependency system between various entities called "units" of 11 different types\&. Units encapsulate various objects that are relevant for system boot\-up and maintenance\&. The majority of units are configured in unit configuration files, whose syntax and basic set of options is described in
+\fBsystemd.unit\fR(5), however some are created automatically from other configuration files, dynamically from system state or programmatically at runtime\&. Units may be "active" (meaning started, bound, plugged in, \&..., depending on the unit type, see below), or "inactive" (meaning stopped, unbound, unplugged, \&...), as well as in the process of being activated or deactivated, i\&.e\&. between the two states (these states are called "activating", "deactivating")\&. A special "failed" state is available as well, which is very similar to "inactive" and is entered when the service failed in some way (process returned error code on exit, or crashed, an operation timed out, or after too many restarts)\&. If this state is entered, the cause will be logged, for later reference\&. Note that the various unit types may have a number of additional substates, which are mapped to the five generalized unit states described here\&.
+.PP
+The following unit types are available:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+Service units, which start and control daemons and the processes they consist of\&. For details, see
+\fBsystemd.service\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+Socket units, which encapsulate local IPC or network sockets in the system, useful for socket\-based activation\&. For details about socket units, see
+\fBsystemd.socket\fR(5), for details on socket\-based activation and other forms of activation, see
+\fBdaemon\fR(7)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+Target units are useful to group units, or provide well\-known synchronization points during boot\-up, see
+\fBsystemd.target\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+Device units expose kernel devices in systemd and may be used to implement device\-based activation\&. For details, see
+\fBsystemd.device\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+Mount units control mount points in the file system, for details see
+\fBsystemd.mount\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 6.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  6." 4.2
+.\}
+Automount units provide automount capabilities, for on\-demand mounting of file systems as well as parallelized boot\-up\&. See
+\fBsystemd.automount\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 7.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  7." 4.2
+.\}
+Timer units are useful for triggering activation of other units based on timers\&. You may find details in
+\fBsystemd.timer\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 8.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  8." 4.2
+.\}
+Swap units are very similar to mount units and encapsulate memory swap partitions or files of the operating system\&. They are described in
+\fBsystemd.swap\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 9.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  9." 4.2
+.\}
+Path units may be used to activate other services when file system objects change or are modified\&. See
+\fBsystemd.path\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'10.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "10." 4.2
+.\}
+Slice units may be used to group units which manage system processes (such as service and scope units) in a hierarchical tree for resource management purposes\&. See
+\fBsystemd.slice\fR(5)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'11.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "11." 4.2
+.\}
+Scope units are similar to service units, but manage foreign processes instead of starting them as well\&. See
+\fBsystemd.scope\fR(5)\&.
+.RE
+.PP
+Units are named as their configuration files\&. Some units have special semantics\&. A detailed list is available in
+\fBsystemd.special\fR(7)\&.
+.PP
+systemd knows various kinds of dependencies, including positive and negative requirement dependencies (i\&.e\&.
+\fIRequires=\fR
+and
+\fIConflicts=\fR) as well as ordering dependencies (\fIAfter=\fR
+and
+\fIBefore=\fR)\&. NB: ordering and requirement dependencies are orthogonal\&. If only a requirement dependency exists between two units (e\&.g\&.
+foo\&.service
+requires
+bar\&.service), but no ordering dependency (e\&.g\&.
+foo\&.service
+after
+bar\&.service) and both are requested to start, they will be started in parallel\&. It is a common pattern that both requirement and ordering dependencies are placed between two units\&. Also note that the majority of dependencies are implicitly created and maintained by systemd\&. In most cases, it should be unnecessary to declare additional dependencies manually, however it is possible to do this\&.
+.PP
+Application programs and units (via dependencies) may request state changes of units\&. In systemd, these requests are encapsulated as \*(Aqjobs\*(Aq and maintained in a job queue\&. Jobs may succeed or can fail, their execution is ordered based on the ordering dependencies of the units they have been scheduled for\&.
+.PP
+On boot systemd activates the target unit
+default\&.target
+whose job is to activate on\-boot services and other on\-boot units by pulling them in via dependencies\&. Usually, the unit name is just an alias (symlink) for either
+graphical\&.target
+(for fully\-featured boots into the UI) or
+multi\-user\&.target
+(for limited console\-only boots for use in embedded or server environments, or similar; a subset of graphical\&.target)\&. However, it is at the discretion of the administrator to configure it as an alias to any other target unit\&. See
+\fBsystemd.special\fR(7)
+for details about these target units\&.
+.PP
+On first boot,
+\fBsystemd\fR
+will enable or disable units according to preset policy\&. See
+\fBsystemd.preset\fR(5)
+and "First Boot Semantics" in
+\fBmachine-id\fR(5)\&.
+.PP
+systemd only keeps a minimal set of units loaded into memory\&. Specifically, the only units that are kept loaded into memory are those for which at least one of the following conditions is true:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+It is in an active, activating, deactivating or failed state (i\&.e\&. in any unit state except for
+"inactive")
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+It has a job queued for it
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+It is a dependency of at least one other unit that is loaded into memory
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+It has some form of resource still allocated (e\&.g\&. a service unit that is inactive but for which a process is still lingering that ignored the request to be terminated)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+It has been pinned into memory programmatically by a D\-Bus call
+.RE
+.PP
+systemd will automatically and implicitly load units from disk \(em if they are not loaded yet \(em as soon as operations are requested for them\&. Thus, in many respects, the fact whether a unit is loaded or not is invisible to clients\&. Use
+\fBsystemctl list\-units \-\-all\fR
+to comprehensively list all units currently loaded\&. Any unit for which none of the conditions above applies is promptly unloaded\&. Note that when a unit is unloaded from memory its accounting data is flushed out too\&. However, this data is generally not lost, as a journal log record is generated declaring the consumed resources whenever a unit shuts down\&.
+.PP
+Processes systemd spawns are placed in individual Linux control groups named after the unit which they belong to in the private systemd hierarchy\&. (see
+\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[1]\d\s+2
+for more information about control groups, or short "cgroups")\&. systemd uses this to effectively keep track of processes\&. Control group information is maintained in the kernel, and is accessible via the file system hierarchy (beneath
+/sys/fs/cgroup/), or in tools such as
+\fBsystemd-cgls\fR(1)
+or
+\fBps\fR(1)
+(\fBps xawf \-eo pid,user,cgroup,args\fR
+is particularly useful to list all processes and the systemd units they belong to\&.)\&.
+.PP
+systemd is compatible with the SysV init system to a large degree: SysV init scripts are supported and simply read as an alternative (though limited) configuration file format\&. The SysV
+/dev/initctl
+interface is provided, and compatibility implementations of the various SysV client tools are available\&. In addition to that, various established Unix functionality such as
+/etc/fstab
+or the
+utmp
+database are supported\&.
+.PP
+systemd has a minimal transaction system: if a unit is requested to start up or shut down it will add it and all its dependencies to a temporary transaction\&. Then, it will verify if the transaction is consistent (i\&.e\&. whether the ordering of all units is cycle\-free)\&. If it is not, systemd will try to fix it up, and removes non\-essential jobs from the transaction that might remove the loop\&. Also, systemd tries to suppress non\-essential jobs in the transaction that would stop a running service\&. Finally it is checked whether the jobs of the transaction contradict jobs that have already been queued, and optionally the transaction is aborted then\&. If all worked out and the transaction is consistent and minimized in its impact it is merged with all already outstanding jobs and added to the run queue\&. Effectively this means that before executing a requested operation, systemd will verify that it makes sense, fixing it if possible, and only failing if it really cannot work\&.
+.PP
+Note that transactions are generated independently of a unit\*(Aqs state at runtime, hence, for example, if a start job is requested on an already started unit, it will still generate a transaction and wake up any inactive dependencies (and cause propagation of other jobs as per the defined relationships)\&. This is because the enqueued job is at the time of execution compared to the target unit\*(Aqs state and is marked successful and complete when both satisfy\&. However, this job also pulls in other dependencies due to the defined relationships and thus leads to, in our example, start jobs for any of those inactive units getting queued as well\&.
+.PP
+systemd contains native implementations of various tasks that need to be executed as part of the boot process\&. For example, it sets the hostname or configures the loopback network device\&. It also sets up and mounts various API file systems, such as
+/sys/
+or
+/proc/\&.
+.PP
+For more information about the concepts and ideas behind systemd, please refer to the
+\m[blue]\fBOriginal Design Document\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.PP
+Note that some but not all interfaces provided by systemd are covered by the
+\m[blue]\fBInterface Portability and Stability Promise\fR\m[]\&\s-2\u[3]\d\s+2\&.
+.PP
+Units may be generated dynamically at boot and system manager reload time, for example based on other configuration files or parameters passed on the kernel command line\&. For details, see
+\fBsystemd.generator\fR(7)\&.
+.PP
+The D\-Bus API of
+\fBsystemd\fR
+is described in
+\fBorg.freedesktop.systemd1\fR(5)
+and
+\fBorg.freedesktop.LogControl1\fR(5)\&.
+.PP
+Systems which invoke systemd in a container or initrd environment should implement the
+\m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[4]\d\s+2
+or
+\m[blue]\fBinitrd Interface\fR\m[]\&\s-2\u[5]\d\s+2
+specifications, respectively\&.
+.SH "DIRECTORIES"
+.PP
+System unit directories
+.RS 4
+The systemd system manager reads unit configuration from various directories\&. Packages that want to install unit files shall place them in the directory returned by
+\fBpkg\-config systemd \-\-variable=systemdsystemunitdir\fR\&. Other directories checked are
+/usr/local/lib/systemd/system
+and
+/usr/lib/systemd/system\&. User configuration always takes precedence\&.
+\fBpkg\-config systemd \-\-variable=systemdsystemconfdir\fR
+returns the path of the system configuration directory\&. Packages should alter the content of these directories only with the
+\fBenable\fR
+and
+\fBdisable\fR
+commands of the
+\fBsystemctl\fR(1)
+tool\&. Full list of directories is provided in
+\fBsystemd.unit\fR(5)\&.
+.RE
+.PP
+User unit directories
+.RS 4
+Similar rules apply for the user unit directories\&. However, here the
+\m[blue]\fBXDG Base Directory specification\fR\m[]\&\s-2\u[6]\d\s+2
+is followed to find units\&. Applications should place their unit files in the directory returned by
+\fBpkg\-config systemd \-\-variable=systemduserunitdir\fR\&. Global configuration is done in the directory reported by
+\fBpkg\-config systemd \-\-variable=systemduserconfdir\fR\&. The
+\fBenable\fR
+and
+\fBdisable\fR
+commands of the
+\fBsystemctl\fR(1)
+tool can handle both global (i\&.e\&. for all users) and private (for one user) enabling/disabling of units\&. Full list of directories is provided in
+\fBsystemd.unit\fR(5)\&.
+.RE
+.PP
+SysV init scripts directory
+.RS 4
+The location of the SysV init script directory varies between distributions\&. If systemd cannot find a native unit file for a requested service, it will look for a SysV init script of the same name (with the
+\&.service
+suffix removed)\&.
+.RE
+.PP
+SysV runlevel link farm directory
+.RS 4
+The location of the SysV runlevel link farm directory varies between distributions\&. systemd will take the link farm into account when figuring out whether a service shall be enabled\&. Note that a service unit with a native unit configuration file cannot be started by activating it in the SysV runlevel link farm\&.
+.RE
+.SH "SIGNALS"
+.PP
+\fBSIGTERM\fR
+.RS 4
+Upon receiving this signal the systemd system manager serializes its state, reexecutes itself and deserializes the saved state again\&. This is mostly equivalent to
+\fBsystemctl daemon\-reexec\fR\&.
+.sp
+systemd user managers will start the
+exit\&.target
+unit when this signal is received\&. This is mostly equivalent to
+\fBsystemctl \-\-user start exit\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.RE
+.PP
+\fBSIGINT\fR
+.RS 4
+Upon receiving this signal the systemd system manager will start the
+ctrl\-alt\-del\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start ctrl\-alt\-del\&.target \-\-job\-mode=replace\-irreversibly\fR\&. If this signal is received more than 7 times per 2s, an immediate reboot is triggered\&. Note that pressing
+Ctrl+Alt+Del
+on the console will trigger this signal\&. Hence, if a reboot is hanging, pressing
+Ctrl+Alt+Del
+more than 7 times in 2 seconds is a relatively safe way to trigger an immediate reboot\&.
+.sp
+systemd user managers treat this signal the same way as
+\fBSIGTERM\fR\&.
+.RE
+.PP
+\fBSIGWINCH\fR
+.RS 4
+When this signal is received the systemd system manager will start the
+kbrequest\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start kbrequest\&.target\fR\&.
+.sp
+This signal is ignored by systemd user managers\&.
+.RE
+.PP
+\fBSIGPWR\fR
+.RS 4
+When this signal is received the systemd manager will start the
+sigpwr\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start sigpwr\&.target\fR\&.
+.RE
+.PP
+\fBSIGUSR1\fR
+.RS 4
+When this signal is received the systemd manager will try to reconnect to the D\-Bus bus\&.
+.RE
+.PP
+\fBSIGUSR2\fR
+.RS 4
+When this signal is received the systemd manager will log its complete state in human\-readable form\&. The data logged is the same as printed by
+\fBsystemd\-analyze dump\fR\&.
+.RE
+.PP
+\fBSIGHUP\fR
+.RS 4
+Reloads the complete daemon configuration\&. This is mostly equivalent to
+\fBsystemctl daemon\-reload\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+0\fR
+.RS 4
+Enters default mode, starts the
+default\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl isolate default\&.target\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+1\fR
+.RS 4
+Enters rescue mode, starts the
+rescue\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl isolate rescue\&.target\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+2\fR
+.RS 4
+Enters emergency mode, starts the
+emergency\&.service
+unit\&. This is mostly equivalent to
+\fBsystemctl isolate emergency\&.service\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+3\fR
+.RS 4
+Halts the machine, starts the
+halt\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start halt\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+4\fR
+.RS 4
+Powers off the machine, starts the
+poweroff\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start poweroff\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+5\fR
+.RS 4
+Reboots the machine, starts the
+reboot\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start reboot\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+6\fR
+.RS 4
+Reboots the machine via kexec, starts the
+kexec\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start kexec\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.RE
+.PP
+\fBSIGRTMIN+7\fR
+.RS 4
+Reboots userspace, starts the
+soft\-reboot\&.target
+unit\&. This is mostly equivalent to
+\fBsystemctl start soft\-reboot\&.target \-\-job\-mode=replace\-irreversibly\fR\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBSIGRTMIN+13\fR
+.RS 4
+Immediately halts the machine\&.
+.RE
+.PP
+\fBSIGRTMIN+14\fR
+.RS 4
+Immediately powers off the machine\&.
+.RE
+.PP
+\fBSIGRTMIN+15\fR
+.RS 4
+Immediately reboots the machine\&.
+.RE
+.PP
+\fBSIGRTMIN+16\fR
+.RS 4
+Immediately reboots the machine with kexec\&.
+.RE
+.PP
+\fBSIGRTMIN+17\fR
+.RS 4
+Immediately reboots the userspace\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fBSIGRTMIN+20\fR
+.RS 4
+Enables display of status messages on the console, as controlled via
+\fIsystemd\&.show_status=1\fR
+on the kernel command line\&.
+.RE
+.PP
+\fBSIGRTMIN+21\fR
+.RS 4
+Disables display of status messages on the console, as controlled via
+\fIsystemd\&.show_status=0\fR
+on the kernel command line\&.
+.RE
+.PP
+\fBSIGRTMIN+22\fR
+.RS 4
+Sets the service manager\*(Aqs log level to
+"debug", in a fashion equivalent to
+\fIsystemd\&.log_level=debug\fR
+on the kernel command line\&.
+.RE
+.PP
+\fBSIGRTMIN+23\fR
+.RS 4
+Restores the log level to its configured value\&. The configured value is derived from \(en in order of priority \(en the value specified with
+\fIsystemd\&.log\-level=\fR
+on the kernel command line, or the value specified with
+\fBLogLevel=\fR
+in the configuration file, or the built\-in default of
+"info"\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBSIGRTMIN+24\fR
+.RS 4
+Immediately exits the manager (only available for \-\-user instances)\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBSIGRTMIN+25\fR
+.RS 4
+Upon receiving this signal the systemd manager will reexecute itself\&. This is mostly equivalent to
+\fBsystemctl daemon\-reexec\fR
+except that it will be done asynchronously\&.
+.sp
+The systemd system manager treats this signal the same way as
+\fBSIGTERM\fR\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fBSIGRTMIN+26\fR
+.RS 4
+Restores the log target to its configured value\&. The configured value is derived from \(en in order of priority \(en the value specified with
+\fIsystemd\&.log\-target=\fR
+on the kernel command line, or the value specified with
+\fBLogTarget=\fR
+in the configuration file, or the built\-in default\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBSIGRTMIN+27\fR, \fBSIGRTMIN+28\fR
+.RS 4
+Sets the log target to
+"console"
+on
+\fBSIGRTMIN+27\fR
+(or
+"kmsg"
+on
+\fBSIGRTMIN+28\fR), in a fashion equivalent to
+\fIsystemd\&.log_target=console\fR
+(or
+\fIsystemd\&.log_target=kmsg\fR
+on
+\fBSIGRTMIN+28\fR) on the kernel command line\&.
+.sp
+Added in version 239\&.
+.RE
+.SH "ENVIRONMENT"
+.PP
+The environment block for the system manager is initially set by the kernel\&. (In particular,
+"key=value"
+assignments on the kernel command line are turned into environment variables for PID 1)\&. For the user manager, the system manager sets the environment as described in the "Environment Variables in Spawned Processes" section of
+\fBsystemd.exec\fR(5)\&. The
+\fIDefaultEnvironment=\fR
+setting in the system manager applies to all services including
+user@\&.service\&. Additional entries may be configured (as for any other service) through the
+\fIEnvironment=\fR
+and
+\fIEnvironmentFile=\fR
+settings for
+user@\&.service
+(see
+\fBsystemd.exec\fR(5))\&. Also, additional environment variables may be set through the
+\fIManagerEnvironment=\fR
+setting in
+\fBsystemd-system.conf\fR(5)
+and
+\fBsystemd-user.conf\fR(5)\&.
+.PP
+Some of the variables understood by
+\fBsystemd\fR:
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.sp
+This can be overridden with
+\fB\-\-log\-level=\fR\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This can be overridden with
+\fB\-\-log\-color=\fR\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This can be overridden with
+\fB\-\-log\-time=\fR\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+This can be overridden with
+\fB\-\-log\-location=\fR\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Added in version 247\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.sp
+This can be overridden with
+\fB\-\-log\-target=\fR\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fI$XDG_CONFIG_HOME\fR, \fI$XDG_CONFIG_DIRS\fR, \fI$XDG_DATA_HOME\fR, \fI$XDG_DATA_DIRS\fR
+.RS 4
+The systemd user manager uses these variables in accordance to the
+\m[blue]\fBXDG Base Directory specification\fR\m[]\&\s-2\u[6]\d\s+2
+to find its configuration\&.
+.RE
+.PP
+\fI$SYSTEMD_UNIT_PATH\fR, \fI$SYSTEMD_GENERATOR_PATH\fR, \fI$SYSTEMD_ENVIRONMENT_GENERATOR_PATH\fR
+.RS 4
+Controls where systemd looks for unit files and generators\&.
+.sp
+These variables may contain a list of paths, separated by colons (":")\&. When set, if the list ends with an empty component ("\&.\&.\&.:"), this list is prepended to the usual set of paths\&. Otherwise, the specified list replaces the usual set of paths\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.PP
+\fI$LISTEN_PID\fR, \fI$LISTEN_FDS\fR, \fI$LISTEN_FDNAMES\fR
+.RS 4
+Set by systemd for supervised processes during socket\-based activation\&. See
+\fBsd_listen_fds\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$NOTIFY_SOCKET\fR
+.RS 4
+Set by systemd for supervised processes for status and start\-up completion notification\&. See
+\fBsd_notify\fR(3)
+for more information\&.
+.RE
+.PP
+For further environment variables understood by systemd and its various components, see
+\m[blue]\fBKnown Environment Variables\fR\m[]\&\s-2\u[7]\d\s+2\&.
+.SH "KERNEL COMMAND LINE"
+.PP
+When run as the system instance, systemd parses a number of options listed below\&. They can be specified as kernel command line arguments which are parsed from a number of sources depending on the environment in which systemd is executed\&. If run inside a Linux container, these options are parsed from the command line arguments passed to systemd itself, next to any of the command line options listed in the Options section above\&. If run outside of Linux containers, these arguments are parsed from
+/proc/cmdline
+and from the
+"SystemdOptions"
+EFI variable (on EFI systems) instead\&. Options from
+/proc/cmdline
+have higher priority\&.
+.PP
+Note: use of
+"SystemdOptions"
+is deprecated\&.
+.PP
+The following variables are understood:
+.PP
+\fIsystemd\&.unit=\fR, \fIrd\&.systemd\&.unit=\fR
+.RS 4
+Overrides the unit to activate on boot\&. Defaults to
+default\&.target\&. This may be used to temporarily boot into a different boot unit, for example
+rescue\&.target
+or
+emergency\&.service\&. See
+\fBsystemd.special\fR(7)
+for details about these units\&. The option prefixed with
+"rd\&."
+is honored only in the initrd, while the one that is not prefixed only in the main system\&.
+.RE
+.PP
+\fIsystemd\&.dump_core\fR
+.RS 4
+Takes a boolean argument or enables the option if specified without an argument\&. If enabled, the systemd manager (PID 1) dumps core when it crashes\&. Otherwise, no core dump is created\&. Defaults to enabled\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fIsystemd\&.crash_chvt\fR
+.RS 4
+Takes a positive integer, or a boolean argument\&. Can be also specified without an argument, with the same effect as a positive boolean\&. If a positive integer (in the range 1\(en63) is specified, the system manager (PID 1) will activate the specified virtual terminal when it crashes\&. Defaults to disabled, meaning that no such switch is attempted\&. If set to enabled, the virtual terminal the kernel messages are written to is used instead\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fIsystemd\&.crash_shell\fR
+.RS 4
+Takes a boolean argument or enables the option if specified without an argument\&. If enabled, the system manager (PID 1) spawns a shell when it crashes, after a 10s delay\&. Otherwise, no shell is spawned\&. Defaults to disabled, for security reasons, as the shell is not protected by password authentication\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fIsystemd\&.crash_reboot\fR
+.RS 4
+Takes a boolean argument or enables the option if specified without an argument\&. If enabled, the system manager (PID 1) will reboot the machine automatically when it crashes, after a 10s delay\&. Otherwise, the system will hang indefinitely\&. Defaults to disabled, in order to avoid a reboot loop\&. If combined with
+\fIsystemd\&.crash_shell\fR, the system is rebooted after the shell exits\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fIsystemd\&.confirm_spawn\fR
+.RS 4
+Takes a boolean argument or a path to the virtual console where the confirmation messages should be emitted\&. Can be also specified without an argument, with the same effect as a positive boolean\&. If enabled, the system manager (PID 1) asks for confirmation when spawning processes using
+\fB/dev/console\fR\&. If a path or a console name (such as
+"ttyS0") is provided, the virtual console pointed to by this path or described by the give name will be used instead\&. Defaults to disabled\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fIsystemd\&.service_watchdogs=\fR
+.RS 4
+Takes a boolean argument\&. If disabled, all service runtime watchdogs (\fBWatchdogSec=\fR) and emergency actions (e\&.g\&.
+\fBOnFailure=\fR
+or
+\fBStartLimitAction=\fR) are ignored by the system manager (PID 1); see
+\fBsystemd.service\fR(5)\&. Defaults to enabled, i\&.e\&. watchdogs and failure actions are processed normally\&. The hardware watchdog is not affected by this option\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fIsystemd\&.show_status\fR
+.RS 4
+Takes a boolean argument or the constants
+\fBerror\fR
+and
+\fBauto\fR\&. Can be also specified without an argument, with the same effect as a positive boolean\&. If enabled, the systemd manager (PID 1) shows terse service status updates on the console during bootup\&. With
+\fBerror\fR, only messages about failures are shown, but boot is otherwise quiet\&.
+\fBauto\fR
+behaves like
+\fBfalse\fR
+until there is a significant delay in boot\&. Defaults to enabled, unless
+\fBquiet\fR
+is passed as kernel command line option, in which case it defaults to
+\fBerror\fR\&. If specified overrides the system manager configuration file option
+\fBShowStatus=\fR, see
+\fBsystemd-system.conf\fR(5)\&.
+.sp
+Added in version 233\&.
+.RE
+.PP
+\fIsystemd\&.status_unit_format=\fR
+.RS 4
+Takes
+\fBname\fR,
+\fBdescription\fR
+or
+\fBcombined\fR
+as the value\&. If
+\fBname\fR, the system manager will use unit names in status messages\&. If
+\fBcombined\fR, the system manager will use unit names and description in status messages\&. When specified, overrides the system manager configuration file option
+\fBStatusUnitFormat=\fR, see
+\fBsystemd-system.conf\fR(5)\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fIsystemd\&.log_color\fR, \fIsystemd\&.log_level=\fR, \fIsystemd\&.log_location\fR, \fIsystemd\&.log_target=\fR, \fIsystemd\&.log_time\fR, \fIsystemd\&.log_tid\fR, \fIsystemd\&.log_ratelimit_kmsg\fR
+.RS 4
+Controls log output, with the same effect as the
+\fI$SYSTEMD_LOG_COLOR\fR,
+\fI$SYSTEMD_LOG_LEVEL\fR,
+\fI$SYSTEMD_LOG_LOCATION\fR,
+\fI$SYSTEMD_LOG_TARGET\fR,
+\fI$SYSTEMD_LOG_TIME\fR,
+\fI$SYSTEMD_LOG_TID\fR
+and
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+environment variables described above\&.
+\fIsystemd\&.log_color\fR,
+\fIsystemd\&.log_location\fR,
+\fIsystemd\&.log_time\fR,
+\fIsystemd\&.log_tid\fR
+and
+\fIsystemd\&.log_ratelimit_kmsg\fR
+can be specified without an argument, with the same effect as a positive boolean\&.
+.RE
+.PP
+\fIsystemd\&.default_standard_output=\fR, \fIsystemd\&.default_standard_error=\fR
+.RS 4
+Controls default standard output and error output for services and sockets\&. That is, controls the default for
+\fBStandardOutput=\fR
+and
+\fBStandardError=\fR
+(see
+\fBsystemd.exec\fR(5)
+for details)\&. Takes one of
+\fBinherit\fR,
+\fBnull\fR,
+\fBtty\fR,
+\fBjournal\fR,
+\fBjournal+console\fR,
+\fBkmsg\fR,
+\fBkmsg+console\fR\&. If the argument is omitted
+\fIsystemd\&.default\-standard\-output=\fR
+defaults to
+\fBjournal\fR
+and
+\fIsystemd\&.default\-standard\-error=\fR
+to
+\fBinherit\fR\&.
+.RE
+.PP
+\fIsystemd\&.setenv=\fR
+.RS 4
+Takes a string argument in the form VARIABLE=VALUE\&. May be used to set default environment variables to add to forked child processes\&. May be used more than once to set multiple variables\&.
+.RE
+.PP
+\fIsystemd\&.machine_id=\fR
+.RS 4
+Takes a 32 character hex value to be used for setting the machine\-id\&. Intended mostly for network booting where the same machine\-id is desired for every boot\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fIsystemd\&.set_credential=\fR, \fIsystemd\&.set_credential_binary=\fR
+.RS 4
+Sets a system credential, which can then be propagated to system services using the
+\fIImportCredential=\fR
+or
+\fILoadCredential=\fR
+setting, see
+\fBsystemd.exec\fR(5)
+for details\&. Takes a pair of credential name and value, separated by a colon\&. The
+\fIsystemd\&.set_credential=\fR
+parameter expects the credential value in literal text form, the
+\fIsystemd\&.set_credential_binary=\fR
+parameter takes binary data encoded in Base64\&. Note that the kernel command line is typically accessible by unprivileged programs in
+/proc/cmdline\&. Thus, this mechanism is not suitable for transferring sensitive data\&. Use it only for data that is not sensitive (e\&.g\&. public keys/certificates, rather than private keys), or in testing/debugging environments\&.
+.sp
+For further information see
+\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[8]\d\s+2
+documentation\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fIsystemd\&.import_credentials=\fR
+.RS 4
+Takes a boolean argument\&. If false disables importing credentials from the kernel command line, the DMI/SMBIOS OEM string table, the qemu_fw_cfg subsystem or the EFI kernel stub\&.
+.sp
+Added in version 251\&.
+.RE
+.PP
+\fIquiet\fR
+.RS 4
+Turn off status output at boot, much like
+\fIsystemd\&.show_status=no\fR
+would\&. Note that this option is also read by the kernel itself and disables kernel log output\&. Passing this option hence turns off the usual output from both the system manager and the kernel\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fIdebug\fR
+.RS 4
+Turn on debugging output\&. This is equivalent to
+\fIsystemd\&.log_level=debug\fR\&. Note that this option is also read by the kernel itself and enables kernel debug output\&. Passing this option hence turns on the debug output from both the system manager and the kernel\&.
+.sp
+Added in version 205\&.
+.RE
+.PP
+\fIemergency\fR, \fIrd\&.emergency\fR, \fI\-b\fR
+.RS 4
+Boot into emergency mode\&. This is equivalent to
+\fIsystemd\&.unit=emergency\&.target\fR
+or
+\fIrd\&.systemd\&.unit=emergency\&.target\fR, respectively, and provided for compatibility reasons and to be easier to type\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fIrescue\fR, \fIrd\&.rescue\fR, \fIsingle\fR, \fIs\fR, \fIS\fR, \fI1\fR
+.RS 4
+Boot into rescue mode\&. This is equivalent to
+\fIsystemd\&.unit=rescue\&.target\fR
+or
+\fIrd\&.systemd\&.unit=rescue\&.target\fR, respectively, and provided for compatibility reasons and to be easier to type\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fI2\fR, \fI3\fR, \fI4\fR, \fI5\fR
+.RS 4
+Boot into the specified legacy SysV runlevel\&. These are equivalent to
+\fIsystemd\&.unit=runlevel2\&.target\fR,
+\fIsystemd\&.unit=runlevel3\&.target\fR,
+\fIsystemd\&.unit=runlevel4\&.target\fR, and
+\fIsystemd\&.unit=runlevel5\&.target\fR, respectively, and provided for compatibility reasons and to be easier to type\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+\fIlocale\&.LANG=\fR, \fIlocale\&.LANGUAGE=\fR, \fIlocale\&.LC_CTYPE=\fR, \fIlocale\&.LC_NUMERIC=\fR, \fIlocale\&.LC_TIME=\fR, \fIlocale\&.LC_COLLATE=\fR, \fIlocale\&.LC_MONETARY=\fR, \fIlocale\&.LC_MESSAGES=\fR, \fIlocale\&.LC_PAPER=\fR, \fIlocale\&.LC_NAME=\fR, \fIlocale\&.LC_ADDRESS=\fR, \fIlocale\&.LC_TELEPHONE=\fR, \fIlocale\&.LC_MEASUREMENT=\fR, \fIlocale\&.LC_IDENTIFICATION=\fR
+.RS 4
+Set the system locale to use\&. This overrides the settings in
+/etc/locale\&.conf\&. For more information, see
+\fBlocale.conf\fR(5)
+and
+\fBlocale\fR(7)\&.
+.sp
+Added in version 186\&.
+.RE
+.PP
+For other kernel command line parameters understood by components of the core OS, please refer to
+\fBkernel-command-line\fR(7)\&.
+.SH "SYSTEM CREDENTIALS"
+.PP
+During initialization the service manager will import credentials from various sources into the system\*(Aqs set of credentials, which can then be propagated into services and consumed by generators:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+When the service manager first initializes it will read system credentials from SMBIOS Type 11 vendor strings
+\fIio\&.systemd\&.credential:\fR\fI\fIname\fR\fR\fI=\fR\fI\fIvalue\fR\fR, and
+\fIio\&.systemd\&.credential\&.binary:\fR\fI\fIname\fR\fR\fI=\fR\fI\fIvalue\fR\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+At the same time it will import credentials from QEMU
+"fw_cfg"\&. (Note that the SMBIOS mechanism is generally preferred, because it is faster and generic\&.)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Credentials may be passed via the kernel command line, using the
+\fIsystemd\&.set\-credential=\fR
+parameter, see above\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Credentials may be passed from the UEFI environment via
+\fBsystemd-stub\fR(7)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+When the service manager is invoked during the initrd → host transition it will import all files in
+/run/credentials/@initrd/
+as system credentials\&.
+.RE
+.PP
+Invoke
+\fBsystemd-creds\fR(1)
+as follows to see the list of credentials passed into the system:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# systemd\-creds \-\-system list
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+For further information see
+\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[8]\d\s+2
+documentation\&.
+.PP
+The service manager when run as PID 1 consumes the following system credentials:
+.PP
+\fIvmm\&.notify_socket\fR
+.RS 4
+Contains a
+\fBAF_VSOCK\fR
+or
+\fBAF_UNIX\fR
+address where to send a
+\fBREADY=1\fR
+notification datagram when the system has finished booting\&. See
+\fBsd_notify\fR(3)
+for more information\&. Note that in case the hypervisor does not support
+\fBSOCK_DGRAM\fR
+over
+\fBAF_VSOCK\fR,
+\fBSOCK_SEQPACKET\fR
+will be tried instead\&. The credential payload for
+\fBAF_VSOCK\fR
+should be in the form
+"vsock:CID:PORT"\&.
+.sp
+This feature is useful for hypervisors/VMMs or other processes on the host to receive a notification via VSOCK when a virtual machine has finished booting\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fIsystem\&.machine_id\fR
+.RS 4
+Takes a 128bit hexadecimal ID to initialize
+/etc/machine\-id
+from, if the file is not set up yet\&. See
+\fBmachine-id\fR(5)
+for details\&.
+.sp
+Added in version 254\&.
+.RE
+.SH "OPTIONS"
+.PP
+\fBsystemd\fR
+is only very rarely invoked directly, since it is started early and is already running by the time users may interact with it\&. Normally, tools like
+\fBsystemctl\fR(1)
+are used to give commands to the manager\&. Since
+\fBsystemd\fR
+is usually not invoked directly, the options listed below are mostly useful for debugging and special purposes\&.
+.SS "Introspection and debugging options"
+.PP
+Those options are used for testing and introspection, and
+\fBsystemd\fR
+may be invoked with them at any time:
+.PP
+\fB\-\-dump\-configuration\-items\fR
+.RS 4
+Dump understood unit configuration items\&. This outputs a terse but complete list of configuration items understood in unit definition files\&.
+.RE
+.PP
+\fB\-\-dump\-bus\-properties\fR
+.RS 4
+Dump exposed bus properties\&. This outputs a terse but complete list of properties exposed on D\-Bus\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-test\fR
+.RS 4
+Determine the initial start\-up transaction (i\&.e\&. the list of jobs enqueued at start\-up), dump it and exit \(em without actually executing any of the determined jobs\&. This option is useful for debugging only\&. Note that during regular service manager start\-up additional units not shown by this operation may be started, because hardware, socket, bus or other kinds of activation might add additional jobs as the transaction is executed\&. Use
+\fB\-\-system\fR
+to request the initial transaction of the system service manager (this is also the implied default), combine with
+\fB\-\-user\fR
+to request the initial transaction of the per\-user service manager instead\&.
+.RE
+.PP
+\fB\-\-system\fR, \fB\-\-user\fR
+.RS 4
+When used in conjunction with
+\fB\-\-test\fR, selects whether to calculate the initial transaction for the system instance or for a per\-user instance\&. These options have no effect when invoked without
+\fB\-\-test\fR, as during regular (i\&.e\&. non\-\fB\-\-test\fR) invocations the service manager will automatically detect whether it shall operate in system or per\-user mode, by checking whether the PID it is run as is 1 or not\&. Note that it is not supported booting and maintaining a system with the service manager running in
+\fB\-\-system\fR
+mode but with a PID other than 1\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SS "Options that duplicate kernel command line settings"
+.PP
+Those options correspond directly to options listed above in "Kernel Command Line"\&. Both forms may be used equivalently for the system manager, but it is recommended to use the forms listed above in this context, because they are properly namespaced\&. When an option is specified both on the kernel command line and as a normal command line argument, the latter has higher precedence\&.
+.PP
+When
+\fBsystemd\fR
+is used as a user manager, the kernel command line is ignored and only the options described below are understood\&. Nevertheless,
+\fBsystemd\fR
+is usually started in this mode through the
+\fBuser@.service\fR(5)
+service, which is shared between all users\&. It may be more convenient to use configuration files to modify settings (see
+\fBsystemd-user.conf\fR(5)), or environment variables\&. See the "Environment" section above for a discussion of how the environment block is set\&.
+.PP
+\fB\-\-unit=\fR
+.RS 4
+Set default unit to activate on startup\&. If not specified, defaults to
+default\&.target\&. See
+\fIsystemd\&.unit=\fR
+above\&.
+.RE
+.PP
+\fB\-\-dump\-core\fR
+.RS 4
+Enable core dumping on crash\&. This switch has no effect when running as user instance\&. Same as
+\fIsystemd\&.dump_core=\fR
+above\&.
+.RE
+.PP
+\fB\-\-crash\-vt=\fR\fIVT\fR
+.RS 4
+Switch to a specific virtual console (VT) on crash\&. This switch has no effect when running as user instance\&. Same as
+\fIsystemd\&.crash_chvt=\fR
+above (but not the different spelling!)\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-crash\-shell\fR
+.RS 4
+Run a shell on crash\&. This switch has no effect when running as user instance\&. See
+\fIsystemd\&.crash_shell=\fR
+above\&.
+.RE
+.PP
+\fB\-\-crash\-reboot\fR
+.RS 4
+Automatically reboot the system on crash\&. This switch has no effect when running as user instance\&. See
+\fIsystemd\&.crash_reboot\fR
+above\&.
+.sp
+Added in version 227\&.
+.RE
+.PP
+\fB\-\-confirm\-spawn\fR
+.RS 4
+Ask for confirmation when spawning processes\&. This switch has no effect when run as user instance\&. See
+\fIsystemd\&.confirm_spawn\fR
+above\&.
+.RE
+.PP
+\fB\-\-show\-status\fR
+.RS 4
+Show terse unit status information on the console during boot\-up and shutdown\&. See
+\fIsystemd\&.show_status\fR
+above\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-\-log\-color\fR
+.RS 4
+Highlight important log messages\&. See
+\fIsystemd\&.log_color\fR
+above\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-\-log\-level=\fR
+.RS 4
+Set log level\&. See
+\fIsystemd\&.log_level\fR
+above\&.
+.RE
+.PP
+\fB\-\-log\-location\fR
+.RS 4
+Include code location in log messages\&. See
+\fIsystemd\&.log_location\fR
+above\&.
+.sp
+Added in version 244\&.
+.RE
+.PP
+\fB\-\-log\-target=\fR
+.RS 4
+Set log target\&. See
+\fIsystemd\&.log_target\fR
+above\&.
+.RE
+.PP
+\fB\-\-log\-time=\fR
+.RS 4
+Prefix console messages with timestamp\&. See
+\fIsystemd\&.log_time\fR
+above\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fB\-\-machine\-id=\fR
+.RS 4
+Override the machine\-id set on the hard drive\&. See
+\fIsystemd\&.machine_id=\fR
+above\&.
+.sp
+Added in version 229\&.
+.RE
+.PP
+\fB\-\-service\-watchdogs\fR
+.RS 4
+Globally enable/disable all service watchdog timeouts and emergency actions\&. See
+\fIsystemd\&.service_watchdogs\fR
+above\&.
+.sp
+Added in version 237\&.
+.RE
+.PP
+\fB\-\-default\-standard\-output=\fR, \fB\-\-default\-standard\-error=\fR
+.RS 4
+Sets the default output or error output for all services and sockets, respectively\&. See
+\fIsystemd\&.default_standard_output=\fR
+and
+\fIsystemd\&.default_standard_error=\fR
+above\&.
+.RE
+.SH "SOCKETS AND FIFOS"
+.PP
+/run/systemd/notify
+.RS 4
+Daemon status notification socket\&. This is an
+\fBAF_UNIX\fR
+datagram socket and is used to implement the daemon notification logic as implemented by
+\fBsd_notify\fR(3)\&.
+.RE
+.PP
+/run/systemd/private
+.RS 4
+Used internally as communication channel between
+\fBsystemctl\fR(1)
+and the systemd process\&. This is an
+\fBAF_UNIX\fR
+stream socket\&. This interface is private to systemd and should not be used in external projects\&.
+.RE
+.PP
+/dev/initctl
+.RS 4
+Limited compatibility support for the SysV client interface, as implemented by the
+systemd\-initctl\&.service
+unit\&. This is a named pipe in the file system\&. This interface is obsolete and should not be used in new applications\&.
+.RE
+.SH "HISTORY"
+.PP
+systemd 252
+.RS 4
+Kernel command\-line arguments
+\fIsystemd\&.unified_cgroup_hierarchy\fR
+and
+\fIsystemd\&.legacy_systemd_cgroup_controller\fR
+were deprecated\&. Please switch to the unified cgroup hierarchy\&.
+.sp
+Added in version 252\&.
+.RE
+.SH "SEE ALSO"
+.PP
+The
+\m[blue]\fBsystemd Homepage\fR\m[]\&\s-2\u[9]\d\s+2,
+\fBsystemd-system.conf\fR(5),
+\fBlocale.conf\fR(5),
+\fBsystemctl\fR(1),
+\fBjournalctl\fR(1),
+\fBsystemd-notify\fR(1),
+\fBdaemon\fR(7),
+\fBsd-daemon\fR(3),
+\fBorg.freedesktop.systemd1\fR(5),
+\fBsystemd.unit\fR(5),
+\fBsystemd.special\fR(7),
+\fBpkg-config\fR(1),
+\fBkernel-command-line\fR(7),
+\fBbootup\fR(7),
+\fBsystemd.directives\fR(7)
+.SH "NOTES"
+.IP " 1." 4
+Control Groups v2
+.RS 4
+\%https://docs.kernel.org/admin-guide/cgroup-v2.html
+.RE
+.IP " 2." 4
+Original Design Document
+.RS 4
+\%https://0pointer.de/blog/projects/systemd.html
+.RE
+.IP " 3." 4
+Interface Portability and Stability Promise
+.RS 4
+\%https://systemd.io/PORTABILITY_AND_STABILITY/
+.RE
+.IP " 4." 4
+Container Interface
+.RS 4
+\%https://systemd.io/CONTAINER_INTERFACE
+.RE
+.IP " 5." 4
+initrd Interface
+.RS 4
+\%https://systemd.io/INITRD_INTERFACE/
+.RE
+.IP " 6." 4
+XDG Base Directory specification
+.RS 4
+\%https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
+.RE
+.IP " 7." 4
+Known Environment Variables
+.RS 4
+\%https://systemd.io/ENVIRONMENT
+.RE
+.IP " 8." 4
+System and Service Credentials
+.RS 4
+\%https://systemd.io/CREDENTIALS
+.RE
+.IP " 9." 4
+systemd Homepage
+.RS 4
+\%https://systemd.io/
+.RE
diff --git a/upstream/mageia-cauldron/man1/tabs.1 b/upstream/mageia-cauldron/man1/tabs.1
new file mode 100644
index 00000000..5e16beee
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tabs.1
@@ -0,0 +1,358 @@
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 2008-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: tabs.1,v 1.55 2024/01/20 16:54:03 tom Exp $
+.TH tabs 1 2024-01-20 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.
+.SH NAME
+\fB\%tabs\fP \-
+set terminal tab stops
+.SH SYNOPSIS
+\fBtabs\fP [\fIoptions\fP] [\fItabstop-list\fP]
+.SH DESCRIPTION
+The \fBtabs\fP program clears and sets tab-stops on the terminal.
+This uses the terminfo \fBclear_all_tabs\fP and \fBset_tab\fP capabilities.
+If either is absent, \fBtabs\fP is unable to clear/set tab-stops.
+The terminal should be configured to use hard tabs, e.g.,
+.PP
+.RS 4
+.EX
+stty tab0
+.EE
+.RE
+.PP
+Like \fBclear\fP(1), \fBtabs\fP writes to the standard output.
+You can redirect the standard output to a file (which prevents
+\fBtabs\fP from actually changing the tabstops),
+and later \fBcat\fP the file to the screen, setting tabstops at that point.
+.PP
+These are hardware tabs, which cannot be queried rapidly by applications
+running in the terminal, if at all.
+Curses and other full-screen applications may use hardware tabs
+in optimizing their output to the terminal.
+If the hardware tabstops differ from the information in the terminal
+database, the result is unpredictable.
+Before running curses programs,
+you should either reset tab-stops to the standard interval
+.PP
+.RS 4
+.EX
+tabs \-8
+.EE
+.RE
+.PP
+or use the \fBreset\fP program,
+since the normal initialization sequences do not ensure that tab-stops
+are reset.
+.SH OPTIONS
+.SS "General Options"
+.TP 5
+.BI \-T "name"
+Tell \fBtabs\fP which terminal type to use.
+If this option is not given, \fBtabs\fP will use the \fB$TERM\fP
+environment variable.
+If that is not set, it will use the \fIansi+tabs\fP entry.
+.TP 5
+.B \-d
+The debugging option shows a ruler line, followed by two data lines.
+The first data line shows the expected tab-stops marked with asterisks.
+The second data line shows the actual tab-stops, marked with asterisks.
+.TP 5
+.B \-n
+This option tells \fBtabs\fP to check the options and run any debugging
+option, but not to modify the terminal settings.
+.TP
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
+.PP
+The \fBtabs\fP program processes a single list of tab stops.
+The last option to be processed which defines a list is the one that
+determines the list to be processed.
+.SS "Implicit Lists"
+Use a single number as an option,
+e.g., \*(``\fB\-5\fP\*('' to set tabs at the given
+interval (in this case 1, 6, 11, 16, 21, etc.).
+Tabs are repeated up to the right margin of the screen.
+.PP
+Use \*(``\fB\-0\fP\*('' to clear all tabs.
+.PP
+Use \*(``\fB\-8\fP\*('' to set tabs to the standard interval.
+.SS "Explicit Lists"
+An explicit list can be defined after the options
+(this does not use a \*(``\-\*('').
+The values in the list must be in increasing numeric order,
+and greater than zero.
+They are separated by a comma or a blank, for example,
+.PP
+.RS 4
+.EX
+tabs 1,6,11,16,21
+tabs 1 6 11 16 21
+.EE
+.RE
+.PP
+Use a \*(``+\*('' to treat a number
+as an increment relative to the previous value,
+e.g.,
+.PP
+.RS 4
+.EX
+tabs 1,+5,+5,+5,+5
+.EE
+.RE
+.PP
+which is equivalent to the 1,6,11,16,21 example.
+.SS "Predefined Tab Stops"
+POSIX defines several predefined lists of tab stops.
+.TP 5
+.B \-a
+Assembler, IBM S/370, first format
+.br
+1,10,16,36,72
+.TP 5
+.B \-a2
+Assembler, IBM S/370, second format
+.br
+1,10,16,40,72
+.TP 5
+.B \-c
+COBOL, normal format
+.br
+1,8,12,16,20,55
+.TP 5
+.B \-c2
+COBOL compact format
+.br
+1,6,10,14,49
+.TP 5
+.B \-c3
+COBOL compact format extended
+.br
+1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67
+.TP 5
+.B \-f
+FORTRAN
+.br
+1,7,11,15,19,23
+.TP 5
+.B \-p
+PL/I
+.br
+1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61
+.TP 5
+.B \-s
+SNOBOL
+.br
+1,10,55
+.TP 5
+.B \-u
+UNIVAC 1100 Assembler
+.br
+1,12,20,44
+.SS Margins
+A few terminals expose a means of changing their left and right margins.
+\fBtabs\fP supports this feature with an option.
+.TP 5
+.BI +m \ margin
+The effect depends on whether the terminal has the margin capabilities:
+.RS
+.bP
+If the terminal provides the capability for setting the left margin,
+\fBtabs\fP uses this,
+and adjusts the available tab stop widths.
+.bP
+If the terminal does not provide the margin capabilities,
+\fBtabs\fP imitates their effect,
+putting tab stops at appropriate places on each line.
+The terminal's left margin is not modified.
+.RE
+.IP
+If the
+.I margin
+parameter is omitted,
+the default is 10.
+Use
+.B +m0
+to reset the left margin,
+that is,
+to make it the left edge of the terminal's display.
+Before setting a left margin,
+\fBtabs\fP resets the margin to reduce problems that might arise
+from moving the cursor to the left of the current left margin.
+.PP
+When setting or resetting the left margin,
+\fBtabs\fP may also reset the right margin.
+.SH FILES
+.TP
+.I /usr/share/tabset
+tab stop initialization database
+.SH PORTABILITY
+IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008)
+describes a
+.B tabs
+utility.
+However,
+.bP
+this standard describes a
+.B +m
+option to set a terminal's left margin.
+Very few of the entries in the terminal database provide the
+.B \%set_left_margin
+.RB ( smgl )
+or
+.B \%set_left_margin_parm
+.RB \%( smglp )
+capabilities needed to support the feature.
+.bP
+There is no counterpart in X/Open Curses Issue 7 for this utility,
+unlike \fBtput\fP(1).
+.PP
+The
+.B \-d
+(debug) and
+.B \-n
+(no-op) options are
+.I \%ncurses
+extensions not provided by other implementations.
+.SH HISTORY
+A
+.B tabs
+utility appeared in PWB/Unix 1.0 (1977).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s2/\
+.\"   tabs.c
+A reduced version shipped in Seventh Edition Unix
+(early 1979)
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/tabs.c
+and in 3BSD
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\"   tabs.c
+(later the same year);
+it supported a \*(``\-n\*('' option to set the first tab stop at the
+left margin.
+That option is not documented by POSIX.
+.PP
+The PWB/Unix
+.B tabs
+utility returned in System III (1980),
+and used built-in tables,
+rather than the terminal database,
+to support a half-dozen hardcopy terminal (printer) types.
+It also had built-in logic to support setting the left margin,
+as well as a feature for copying the tab settings from a file.
+.PP
+Versions of the program in later releases of AT&T Unix,
+such as SVr4,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=SysVR4/cmd/tabs/tabs.c
+added support for the terminal database,
+but retained the tables to support the printers.
+By this time,
+System\ V
+.B tput
+had incorporated the tab stop initialization feature of BSD's
+.B tset
+from 1982,
+but employed the
+.I \%term\%info
+database to do so.
+.PP
+The
+.B +m
+option was documented in the POSIX Base Specifications Issue 5
+(Unix98, 1997),
+then omitted in Issue 6
+(Unix03, 2004)
+without express motivation,
+though an introductory comment
+\*(``and optionally adjusts the margin\*('' remains,
+overlooked in the removal.
+The
+.B tabs
+utility documented in Issues 6 and later has no mechanism for setting
+margins.
+The
+.B +m
+option in
+.I \%ncurses
+\fB\%tabs\fP differs from the SVr4 feature by using terminal
+capabilities rather than built-in tables.
+.PP
+POSIX documents no limit on the number of tab stops.
+Other implementations impose one;
+the limit is 20 in PWB/Unix's
+.B tabs
+utility.
+While some terminals may not accept an arbitrary number of tab stops,
+.I \%ncurses
+\fB\%tabs\fP attempts to set tab stops up to the right margin if the
+list thereof is sufficiently long.
+.PP
+The \*(``Rationale\*('' section of the Issue 6
+.B tabs
+reference page
+.\" https://pubs.opengroup.org/onlinepubs/009604499/utilities/tabs.html
+details how the committee considered redesigning the
+.B tabs
+and
+.B tput
+utilities,
+without settling on an improved solution.
+It claims that
+.PP
+.RS 4
+\*(``no known historical version of
+.I tabs
+supports the capability of setting arbitrary tab stops.\*(''
+.RE
+.PP
+The feature described in subsection \*(``Explicit Lists\*('' above was
+implemented in PWB/Unix,
+.\" see URL above
+and permitted the setting of abitrary tab stops nevertheless.
+.SH SEE ALSO
+\fB\%infocmp\fP(1M),
+\fB\%tset\fP(1),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/tac.1 b/upstream/mageia-cauldron/man1/tac.1
new file mode 100644
index 00000000..d2da7866
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tac.1
@@ -0,0 +1,49 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TAC "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tac \- concatenate and print files in reverse
+.SH SYNOPSIS
+.B tac
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write each FILE to standard output, last line first.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-b\fR, \fB\-\-before\fR
+attach the separator before instead of after
+.TP
+\fB\-r\fR, \fB\-\-regex\fR
+interpret the separator as a regular expression
+.TP
+\fB\-s\fR, \fB\-\-separator\fR=\fI\,STRING\/\fR
+use STRING as the separator instead of newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Jay Lepreau and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcat\fP(1), \fBrev\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/tac>
+.br
+or available locally via: info \(aq(coreutils) tac invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tail.1 b/upstream/mageia-cauldron/man1/tail.1
new file mode 100644
index 00000000..849bcf0f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tail.1
@@ -0,0 +1,99 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TAIL "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tail \- output the last part of files
+.SH SYNOPSIS
+.B tail
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the last 10 lines of each FILE to standard output.
+With more than one FILE, precede each with a header giving the file name.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\/\fR+]NUM
+output the last NUM bytes; or use \fB\-c\fR +NUM to
+output starting with byte NUM of each file
+.TP
+\fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
+output appended data as the file grows;
+.IP
+an absent option argument means 'descriptor'
+.TP
+\fB\-F\fR
+same as \fB\-\-follow\fR=\fI\,name\/\fR \fB\-\-retry\fR
+.TP
+\fB\-n\fR, \fB\-\-lines\fR=\fI\,[\/\fR+]NUM
+output the last NUM lines, instead of the last 10;
+or use \fB\-n\fR +NUM to output starting with line NUM
+.TP
+\fB\-\-max\-unchanged\-stats\fR=\fI\,N\/\fR
+with \fB\-\-follow\fR=\fI\,name\/\fR, reopen a FILE which has not
+.IP
+changed size after N (default 5) iterations
+to see if it has been unlinked or renamed
+(this is the usual case of rotated log files);
+with inotify, this option is rarely useful
+.TP
+\fB\-\-pid\fR=\fI\,PID\/\fR
+with \fB\-f\fR, terminate after process ID, PID dies
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+never output headers giving file names
+.TP
+\fB\-\-retry\fR
+keep trying to open a file if it is inaccessible
+.TP
+\fB\-s\fR, \fB\-\-sleep\-interval\fR=\fI\,N\/\fR
+with \fB\-f\fR, sleep for approximately N seconds
+(default 1.0) between iterations;
+with inotify and \fB\-\-pid\fR=\fI\,P\/\fR, check process P at
+least once every N seconds
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+always output headers giving file names
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NUM may have a multiplier suffix:
+b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,
+GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+With \fB\-\-follow\fR (\fB\-f\fR), tail defaults to following the file descriptor, which
+means that even if a tail'ed file is renamed, tail will continue to track
+its end.  This default behavior is not desirable when you really want to
+track the actual name of the file, not the file descriptor (e.g., log
+rotation).  Use \fB\-\-follow\fR=\fI\,name\/\fR in that case.  That causes tail to track the
+named file in a way that accommodates renaming, removal and creation.
+.SH AUTHOR
+Written by Paul Rubin, David MacKenzie, Ian Lance Taylor,
+and Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBhead\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/tail>
+.br
+or available locally via: info \(aq(coreutils) tail invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tapestat.1 b/upstream/mageia-cauldron/man1/tapestat.1
new file mode 100644
index 00000000..d054c699
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tapestat.1
@@ -0,0 +1,233 @@
+.\" tapestat manual page - (C) 2015 Hewlett-Packard Development Company, L.P.
+.\" Maintained by Sebastien Godard (sysstat <at> orange.fr)
+.TH TAPESTAT 1 "MAY 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+tapestat \- Report tape statistics.
+
+.SH SYNOPSIS
+.B tapestat [ -k | -m ] [ -t ] [ -V ] [ -y ] [ -z ] [ --human ] [
+.IB "interval " "[ " "count " "] ]"
+
+.SH DESCRIPTION
+.RB "The " "tapestat"
+command is used for monitoring the activity of tape drives connected to a system.
+.PP
+The first report generated by the
+.BR "tapestat " "command provides statistics"
+concerning the time since the system was booted, unless the
+.B -y
+option is used, when this first report is omitted.
+Each subsequent report covers the time since the previous report.
+.PP
+.RI "The " "interval"
+parameter specifies the amount of time in seconds between each report. The
+.I count
+parameter can be specified in conjunction with the
+.IR "interval " "parameter. If the " "count " "parameter is specified, the value of " "count"
+determines the number of reports generated at
+.IR "interval " "seconds apart. If the " "interval " "parameter is specified without the " "count"
+.RB "parameter, the " "tapestat"
+command generates reports continuously.
+
+.SH REPORT
+The
+.B tapestat
+report provides statistics for each tape drive connected to the system.
+The following data are displayed:
+.IP r/s
+The number of reads issued expressed as the number per second averaged over the interval.
+.IP w/s
+The number of writes issued expressed as the number per second averaged over the interval.
+.IP "kB_read/s | MB_read/s"
+The amount of data read expressed in kilobytes (by default or if option
+.BR "-k " "used) or megabytes (if option " "-m"
+used) per second averaged over the interval.
+.IP "kB_wrtn/s | MB_wrtn/s"
+The amount of data written expressed in kilobytes (by default or if option
+.BR "-k " "used) or megabytes (if option " "-m"
+used) per second averaged over the interval.
+.IP %Rd
+Read percentage wait - The percentage of time over the interval spent waiting for read requests
+to complete.
+The time is measured from when the request is dispatched to the SCSI mid-layer until it signals
+that it completed.
+.IP %Wr
+Write percentage wait - The percentage of time over the interval spent waiting for write requests
+to complete. The time is measured from when the request is dispatched to the SCSI mid-layer until
+it signals that it completed.
+.IP %Oa
+Overall percentage wait - The percentage of time over the interval spent waiting for any
+I/O request to complete (read, write, and other).
+.IP Rs/s
+The number of I/Os, expressed as the number per second averaged over the interval, where
+a non-zero residual value was encountered.
+.IP Ot/s
+The number of I/Os, expressed as the number per second averaged over the interval, that
+were included as "other". Other I/O includes ioctl calls made to the tape driver and
+implicit operations performed by the tape driver such as rewind on close
+(for tape devices that implement rewind on close). It does not include any I/O performed
+using methods outside of the tape driver (e.g. via sg ioctls).
+
+.SH OPTIONS
+.TP
+.B --human
+Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
+The units displayed with this option supersede any other default units (e.g.
+kilobytes, sectors...) associated with the metrics.
+.TP
+.B -k
+Show the amount of data written or read in kilobytes per second instead of megabytes.
+This option is mutually exclusive with
+.BR "-m" "."
+.TP
+.B -m
+Show the amount of data written or read in megabytes per second instead of kilobytes.
+This option is mutually exclusive with
+.BR "-k" "."
+.TP
+.B -t
+Display time stamps. The time stamp format may depend
+on the value of the
+.BR "S_TIME_FORMAT " "environment variable (see below)."
+.TP
+.B -V
+Print version and exit.
+.TP
+.B -y
+Omit the initial statistic showing values since boot.
+.TP
+.B -z
+.RB "Tell " "tapestat"
+to omit output for any tapes for which there was no activity
+during the sample period.
+
+.SH CONSIDERATIONS
+It is possible for a percentage value (read, write, or other) to be greater than 100 percent (the
+.B tapestat
+command will never show a percentage value more than 999).
+If rewinding a tape takes 40 seconds where the interval time is 5 seconds the %Oa value
+would show as 0 in the intervals before the rewind completed and then show as approximately
+800 percent when the rewind completes.
+
+Similar values will be observed for %Rd and %Wr if a tape drive stops reading or writing
+and then restarts (that is it stopped streaming). In such a case you may see the r/s or w/s drop to zero and the %Rd/%Wr value could be higher than 100 when reading or writing continues
+(depending on how long it takes to restart writing or reading).
+This is only an issue if it happens a lot as it may cause tape wear and will impact
+on the backup times.
+
+For fast tape drives you may see low percentage wait times.
+This does not indicate an issue with the tape drive. For a slower tape drive (e.g. an older
+generation DDS drive) the speed of the tape (and tape drive) is much slower than filesystem I/O,
+percent wait times are likely to be higher. For faster tape drives (e.g. LTO) the percentage
+wait times are likely to be lower as program writing to or reading from tape is going
+to be doing a lot more filesystem I/O because of the higher throughput.
+
+Although tape statistics are implemented in the kernel using atomic variables they cannot be
+read atomically as a group. All of the statistics values are read from different files under
+.IR "/sys" ","
+because of this there may be I/O completions while reading the different files for the
+one tape drive. This may result in a set of statistics for a device that contain some values
+before an I/O completed and some after.
+
+This command uses rounding down as the rounding method when calculating per second statistics.
+If, for example, you are using
+.BR "dd " "to copy one tape to another and running " "tapestat"
+with an interval of 5 seconds and over the interval there were 3210 writes and 3209 reads
+then w/s would show 642 and r/s 641 (641.8 rounded down to 641). In such a case if it was
+a tar archive being copied (with a 10k block size) you would also see a difference between
+the kB_read/s and kB_wrtn/s of 2 (one I/O 10k in size divided by the interval period of 5
+seconds). If instead there were 3210 writes and 3211 reads both w/s and r/s would both show
+642 but you would still see a difference between the kB_read/s and kB_wrtn/s values of 2 kB/s.
+
+This command is provided with an interval in seconds. However internally the interval is
+tracked per device and can potentially have an effect on the per second statistics reported.
+The time each set of statistics is captured is kept with those statistics. The difference
+between the current and previous time is converted to milliseconds for use in calculations.
+We can look at how this can impact the statistics reported if we use an example of a tar
+archive being copied between two tape drives using
+.BR "dd" "."
+If both devices reported 28900 kilobytes
+transferred and the reading tape drive had an interval of 5001 milliseconds and the writing
+tape drive 5000 milliseconds that would calculate out as 5778 kB_read/s and 5780 kB_wrtn/s.
+
+The impact of some retrieving statistics during an I/O completion, rounding down, and small differences in the interval period on the statistics calculated should be minimal but may be non-zero.
+
+.SH ENVIRONMENT
+.RB "The " "tapestat"
+command takes into account the following environment variables:
+.TP
+.B S_COLORS
+By default statistics are displayed in color when the output is connected to a terminal.
+Use this variable to change the settings. Possible values for this variable are
+.IR "never" ", " "always " "or " "auto"
+(the latter is equivalent to the default settings).
+.br
+Please note that the color (being red, yellow, or some other color) used to display a value
+is not indicative of any kind of issue simply because of the color. It only indicates different
+ranges of values.
+.TP
+.B S_COLORS_SGR
+Specify the colors and other attributes used to display statistics on the terminal.
+Its value is a colon-separated list of capabilities that defaults to
+.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
+Supported capabilities are:
+.RS
+.TP
+.B I=
+SGR (Select Graphic Rendition) substring for tape names.
+.TP
+.B N=
+SGR substring for non-zero statistics values.
+.TP
+.BR "W=" " (or " "M=" ")"
+SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
+metric's meaning).
+.TP
+.BR "X=" " (or " "H=" ")"
+SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
+metric's meaning).
+.TP
+.B Z=
+SGR substring for zero values.
+.RE
+.TP
+.B S_TIME_FORMAT
+If this variable exists and its value is
+.BR ISO
+then the current locale will be ignored when printing the date in the report
+header. The
+.B tapestat
+command will use the ISO 8601 format (YYYY-MM-DD) instead.
+The timestamp displayed with option
+.B -t
+will also be compliant with ISO 8601 format.
+
+.SH BUGS
+.IR "/sys " "filesystem must be mounted for"
+.B tapestat
+to work. It will not work on kernels that do not have sysfs support
+.PP
+This command requires kernel version 4.2 or later
+(or tape statistics support backported for an earlier kernel version).
+.PP
+.RB "Although " "tapestat"
+speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
+A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
+
+.SH FILES
+.I /sys/class/scsi_tape/st<num>/stats/*
+.RS
+Statistics files for tape devices.
+.RE
+.PP
+.IR "/proc/uptime " "contains system uptime."
+
+.SH AUTHOR
+Initial revision by Shane M. SEYMOUR (shane.seymour <at> hpe.com)
+.br
+Modified for sysstat by Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "iostat" "(1), " "mpstat" "(1)"
+.PP
+.I https://github.com/sysstat/sysstat
diff --git a/upstream/mageia-cauldron/man1/tar.1 b/upstream/mageia-cauldron/man1/tar.1
new file mode 100644
index 00000000..fcbf3457
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tar.1
@@ -0,0 +1,652 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.33.
+.TH TAR "1" "January 2024" "tar 1.35" "User Commands"
+.SH NAME
+A tar (tape archiver) program.
+.SH SYNOPSIS
+.B tar
+[\fIOPTION\fR...] [\fIFILE\fR]...
+.SH DESCRIPTION
+GNU 'tar' saves many files together into a single tape or disk archive, and can
+restore individual files from the archive.
+.SH EXAMPLES
+.TP
+tar \fB\-cf\fR archive.tar foo bar
+# Create archive.tar from files foo and bar.
+.TP
+tar \fB\-tvf\fR archive.tar
+# List all files in archive.tar verbosely.
+.TP
+tar \fB\-xf\fR archive.tar
+# Extract all files from archive.tar.
+.IP
+Main operation mode:
+.TP
+\fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
+append tar files to an archive
+.TP
+\fB\-c\fR, \fB\-\-create\fR
+create a new archive
+.TP
+\fB\-\-delete\fR
+delete from the archive (not on mag tapes!)
+.TP
+\fB\-d\fR, \fB\-\-diff\fR, \fB\-\-compare\fR
+find differences between archive and file system
+.TP
+\fB\-r\fR, \fB\-\-append\fR
+append files to the end of an archive
+.TP
+\fB\-\-test\-label\fR
+test the archive volume label and exit
+.TP
+\fB\-t\fR, \fB\-\-list\fR
+list the contents of an archive
+.TP
+\fB\-u\fR, \fB\-\-update\fR
+only append files newer than copy in archive
+.TP
+\fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
+extract files from an archive
+.IP
+Operation modifiers:
+.TP
+\fB\-\-check\-device\fR
+check device numbers when creating incremental
+archives (default)
+.TP
+\fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
+handle new GNU-format incremental backup
+.TP
+\fB\-G\fR, \fB\-\-incremental\fR
+handle old GNU-format incremental backup
+.TP
+\fB\-\-hole\-detection\fR=\fITYPE\fR
+technique to detect holes
+.TP
+\fB\-\-ignore\-failed\-read\fR
+do not exit with nonzero on unreadable files
+.TP
+\fB\-\-level\fR=\fINUMBER\fR
+dump level for created listed-incremental archive
+.TP
+\fB\-\-no\-check\-device\fR
+do not check device numbers when creating
+incremental archives
+.TP
+\fB\-\-no\-seek\fR
+archive is not seekable
+.TP
+\fB\-n\fR, \fB\-\-seek\fR
+archive is seekable
+.TP
+\fB\-\-occurrence\fR[=\fINUMBER\fR]
+process only the NUMBERth occurrence of each file
+in the archive; this option is valid only in
+conjunction with one of the subcommands \fB\-\-delete\fR,
+\fB\-\-diff\fR, \fB\-\-extract\fR or \fB\-\-list\fR and when a list of
+files is given either on the command line or via
+the \fB\-T\fR option; NUMBER defaults to 1
+.TP
+\fB\-\-sparse\-version\fR=\fIMAJOR[\fR.MINOR]
+set version of the sparse format to use (implies
+\fB\-\-sparse\fR)
+.TP
+\fB\-S\fR, \fB\-\-sparse\fR
+handle sparse files efficiently
+.IP
+Local file name selection:
+.TP
+\fB\-\-add\-file\fR=\fIFILE\fR
+add given FILE to the archive (useful if its name
+starts with a dash)
+.TP
+\fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
+change to directory DIR
+.TP
+\fB\-\-exclude\fR=\fIPATTERN\fR
+exclude files, given as a PATTERN
+.TP
+\fB\-\-exclude\-backups\fR
+exclude backup and lock files
+.TP
+\fB\-\-exclude\-caches\fR
+exclude contents of directories containing
+CACHEDIR.TAG, except for the tag file itself
+.TP
+\fB\-\-exclude\-caches\-all\fR
+exclude directories containing CACHEDIR.TAG
+.TP
+\fB\-\-exclude\-caches\-under\fR exclude everything under directories containing
+CACHEDIR.TAG
+.TP
+\fB\-\-exclude\-ignore\fR=\fIFILE\fR
+read exclude patterns for each directory from
+FILE, if it exists
+.TP
+\fB\-\-exclude\-ignore\-recursive\fR=\fIFILE\fR
+read exclude patterns for each directory and its
+subdirectories from FILE, if it exists
+.TP
+\fB\-\-exclude\-tag\fR=\fIFILE\fR
+exclude contents of directories containing FILE,
+except for FILE itself
+.HP
+\fB\-\-exclude\-tag\-all\fR=\fIFILE\fR exclude directories containing FILE
+.TP
+\fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
+exclude everything under directories
+containing FILE
+.TP
+\fB\-\-exclude\-vcs\fR
+exclude version control system directories
+.TP
+\fB\-\-exclude\-vcs\-ignores\fR
+read exclude patterns from the VCS ignore files
+.TP
+\fB\-\-no\-null\fR
+disable the effect of the previous \fB\-\-null\fR option
+.TP
+\fB\-\-no\-recursion\fR
+avoid descending automatically in directories
+.TP
+\fB\-\-no\-unquote\fR
+do not unquote input file or member names
+.TP
+\fB\-\-no\-verbatim\-files\-from\fR   \fB\-T\fR treats file names starting with dash as
+options (default)
+.TP
+\fB\-\-null\fR                 \fB\-T\fR reads null-terminated names; implies
+\fB\-\-verbatim\-files\-from\fR
+.TP
+\fB\-\-recursion\fR
+recurse into directories (default)
+.TP
+\fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
+get names to extract or create from FILE
+.TP
+\fB\-\-unquote\fR
+unquote input file or member names (default)
+.TP
+\fB\-\-verbatim\-files\-from\fR  \fB\-T\fR reads file names verbatim (no escape or option
+handling)
+.TP
+\fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
+exclude patterns listed in FILE
+.IP
+File name matching options (affect both exclude and include patterns):
+.TP
+\fB\-\-anchored\fR
+patterns match file name start
+.TP
+\fB\-\-ignore\-case\fR
+ignore case
+.TP
+\fB\-\-no\-anchored\fR
+patterns match after any '/' (default for
+exclusion)
+.TP
+\fB\-\-no\-ignore\-case\fR
+case sensitive matching (default)
+.TP
+\fB\-\-no\-wildcards\fR
+verbatim string matching
+.TP
+\fB\-\-no\-wildcards\-match\-slash\fR
+wildcards do not match '/'
+.TP
+\fB\-\-wildcards\fR
+use wildcards (default for exclusion)
+.TP
+\fB\-\-wildcards\-match\-slash\fR
+wildcards match '/' (default for exclusion)
+.IP
+Overwrite control:
+.TP
+\fB\-\-keep\-directory\-symlink\fR
+preserve existing symlinks to directories when
+extracting
+.TP
+\fB\-\-keep\-newer\-files\fR
+don't replace existing files that are newer than
+their archive copies
+.TP
+\fB\-k\fR, \fB\-\-keep\-old\-files\fR
+don't replace existing files when extracting,
+treat them as errors
+.TP
+\fB\-\-no\-overwrite\-dir\fR
+preserve metadata of existing directories
+.TP
+\fB\-\-one\-top\-level\fR[=\fIDIR\fR]
+create a subdirectory to avoid having loose files
+extracted
+.TP
+\fB\-\-overwrite\fR
+overwrite existing files when extracting
+.TP
+\fB\-\-overwrite\-dir\fR
+overwrite metadata of existing directories when
+extracting (default)
+.TP
+\fB\-\-recursive\-unlink\fR
+empty hierarchies prior to extracting directory
+.TP
+\fB\-\-remove\-files\fR
+remove files after adding them to the archive
+.TP
+\fB\-\-skip\-old\-files\fR
+don't replace existing files when extracting,
+silently skip over them
+.TP
+\fB\-U\fR, \fB\-\-unlink\-first\fR
+remove each file prior to extracting over it
+.TP
+\fB\-W\fR, \fB\-\-verify\fR
+attempt to verify the archive after writing it
+.IP
+Select output stream:
+.HP
+\fB\-\-ignore\-command\-error\fR ignore exit codes of children
+.TP
+\fB\-\-no\-ignore\-command\-error\fR
+treat non-zero exit codes of children as
+error
+.TP
+\fB\-O\fR, \fB\-\-to\-stdout\fR
+extract files to standard output
+.TP
+\fB\-\-to\-command\fR=\fICOMMAND\fR
+pipe extracted files to another program
+.IP
+Handling of file attributes:
+.TP
+\fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
+preserve access times on dumped files, either
+by restoring the times after reading
+(METHOD='replace'; default) or by not setting the
+times in the first place (METHOD='system')
+.TP
+\fB\-\-clamp\-mtime\fR
+only set time when the file is more recent than
+what was given with \fB\-\-mtime\fR
+.TP
+\fB\-\-delay\-directory\-restore\fR
+delay setting modification times and
+permissions of extracted directories until the end
+of extraction
+.TP
+\fB\-\-group\fR=\fINAME\fR
+force NAME as group for added files
+.TP
+\fB\-\-group\-map\fR=\fIFILE\fR
+use FILE to map file owner GIDs and names
+.TP
+\fB\-\-mode\fR=\fICHANGES\fR
+force (symbolic) mode CHANGES for added files
+.TP
+\fB\-\-mtime\fR=\fIDATE\-OR\-FILE\fR
+set mtime for added files from DATE-OR-FILE
+.TP
+\fB\-m\fR, \fB\-\-touch\fR
+don't extract file modified time
+.TP
+\fB\-\-no\-delay\-directory\-restore\fR
+cancel the effect of \fB\-\-delay\-directory\-restore\fR
+option
+.TP
+\fB\-\-no\-same\-owner\fR
+extract files as yourself (default for ordinary
+users)
+.TP
+\fB\-\-no\-same\-permissions\fR
+apply the user's umask when extracting permissions
+from the archive (default for ordinary users)
+.TP
+\fB\-\-numeric\-owner\fR
+always use numbers for user/group names
+.TP
+\fB\-\-owner\fR=\fINAME\fR
+force NAME as owner for added files
+.TP
+\fB\-\-owner\-map\fR=\fIFILE\fR
+use FILE to map file owner UIDs and names
+.TP
+\fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
+extract information about file permissions
+(default for superuser)
+.TP
+\fB\-\-same\-owner\fR
+try extracting files with the same ownership as
+exists in the archive (default for superuser)
+.TP
+\fB\-\-sort\fR=\fIORDER\fR
+directory sorting order: none (default), name or
+inode
+.TP
+\fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
+member arguments are listed in the same order as
+the files in the archive
+.IP
+Handling of extended file attributes:
+.TP
+\fB\-\-acls\fR
+Enable the POSIX ACLs support
+.TP
+\fB\-\-no\-acls\fR
+Disable the POSIX ACLs support
+.TP
+\fB\-\-no\-selinux\fR
+Disable the SELinux context support
+.TP
+\fB\-\-no\-xattrs\fR
+Disable extended attributes support
+.TP
+\fB\-\-selinux\fR
+Enable the SELinux context support
+.TP
+\fB\-\-xattrs\fR
+Enable extended attributes support
+.TP
+\fB\-\-xattrs\-exclude\fR=\fIMASK\fR
+specify the exclude pattern for xattr keys
+.TP
+\fB\-\-xattrs\-include\fR=\fIMASK\fR
+specify the include pattern for xattr keys
+.IP
+Device selection and switching:
+.TP
+\fB\-\-force\-local\fR
+archive file is local even if it has a colon
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
+use archive file or device ARCHIVE
+.TP
+\fB\-F\fR, \fB\-\-info\-script\fR=\fINAME\fR, \fB\-\-new\-volume\-script\fR=\fINAME\fR
+run script at end of each tape (implies \fB\-M\fR)
+.TP
+\fB\-L\fR, \fB\-\-tape\-length\fR=\fINUMBER\fR
+change tape after writing NUMBER x 1024 bytes
+.TP
+\fB\-M\fR, \fB\-\-multi\-volume\fR
+create/list/extract multi-volume archive
+.TP
+\fB\-\-rmt\-command\fR=\fICOMMAND\fR
+use given rmt COMMAND instead of rmt
+.TP
+\fB\-\-rsh\-command\fR=\fICOMMAND\fR
+use remote COMMAND instead of rsh
+.TP
+\fB\-\-volno\-file\fR=\fIFILE\fR
+use/update the volume number in FILE
+.IP
+Device blocking:
+.TP
+\fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
+BLOCKS x 512 bytes per record
+.TP
+\fB\-B\fR, \fB\-\-read\-full\-records\fR
+reblock as we read (for 4.2BSD pipes)
+.TP
+\fB\-i\fR, \fB\-\-ignore\-zeros\fR
+ignore zeroed blocks in archive (means EOF)
+.TP
+\fB\-\-record\-size\fR=\fINUMBER\fR
+NUMBER of bytes per record, multiple of 512
+.IP
+Archive format selection:
+.TP
+\fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
+create archive of the given format
+.IP
+FORMAT is one of the following:
+.TP
+gnu
+GNU tar 1.13.x format
+.TP
+oldgnu
+GNU format as per tar <= 1.12
+.TP
+pax
+POSIX 1003.1-2001 (pax) format
+.TP
+posix
+same as pax
+.TP
+ustar
+POSIX 1003.1-1988 (ustar) format
+.TP
+v7
+old V7 tar format
+.TP
+\fB\-\-old\-archive\fR, \fB\-\-portability\fR
+same as \fB\-\-format\fR=\fIv7\fR
+.TP
+\fB\-\-pax\-option\fR=\fIkeyword[[\fR:]=value][,keyword[[:]=value]]...
+control pax keywords
+.TP
+\fB\-\-posix\fR
+same as \fB\-\-format\fR=\fIposix\fR
+.TP
+\fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
+create archive with volume name TEXT; at
+list/extract time, use TEXT as a globbing pattern
+for volume name
+.IP
+Compression options:
+.TP
+\fB\-a\fR, \fB\-\-auto\-compress\fR
+use archive suffix to determine the compression
+program
+.TP
+\fB\-I\fR, \fB\-\-use\-compress\-program\fR=\fIPROG\fR
+filter through PROG (must accept \fB\-d\fR)
+.TP
+\fB\-j\fR, \fB\-\-bzip2\fR
+filter the archive through bzip2
+.TP
+\fB\-J\fR, \fB\-\-xz\fR
+filter the archive through xz
+.TP
+\fB\-\-lzip\fR
+filter the archive through lzip
+.TP
+\fB\-\-lzop\fR
+filter the archive through lzop
+.TP
+\fB\-\-no\-auto\-compress\fR
+do not use archive suffix to determine the
+compression program
+.TP
+\fB\-Y\fR, \fB\-\-lzma\fR
+filter the archive through xz \fB\-\-format\fR=\fIlzma\fR
+.TP
+\fB\-\-zstd\fR
+filter the archive through zstd
+.TP
+\fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
+filter the archive through gzip
+.TP
+\fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
+filter the archive through compress
+.IP
+Local file selection:
+.TP
+\fB\-\-backup\fR[=\fICONTROL\fR]
+backup before removal, choose version CONTROL
+.TP
+\fB\-\-hard\-dereference\fR
+follow hard links; archive and dump the files they
+refer to
+.TP
+\fB\-h\fR, \fB\-\-dereference\fR
+follow symlinks; archive and dump the files they
+point to
+.TP
+\fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\-NAME\fR
+begin at member MEMBER-NAME when reading the
+archive
+.TP
+\fB\-\-newer\-mtime\fR=\fIDATE\fR
+compare date and time when data changed only
+.TP
+\fB\-N\fR, \fB\-\-newer\fR=\fIDATE\-OR\-FILE\fR, \fB\-\-after\-date\fR=\fIDATE\-OR\-FILE\fR
+only store files newer than DATE-OR-FILE
+.TP
+\fB\-\-one\-file\-system\fR
+stay in local file system when creating archive
+.TP
+\fB\-P\fR, \fB\-\-absolute\-names\fR
+don't strip leading '/'s from file names
+.TP
+\fB\-\-suffix\fR=\fISTRING\fR
+backup before removal, override usual suffix ('~'
+unless overridden by environment variable
+SIMPLE_BACKUP_SUFFIX)
+.IP
+File name transformations:
+.TP
+\fB\-\-strip\-components\fR=\fINUMBER\fR
+strip NUMBER leading components from file
+names on extraction
+.TP
+\fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
+use sed replace EXPRESSION to transform file
+names
+.IP
+Informative output:
+.TP
+\fB\-\-checkpoint\fR[=\fINUMBER\fR]
+display progress messages every NUMBERth record
+(default 10)
+.TP
+\fB\-\-checkpoint\-action\fR=\fIACTION\fR
+execute ACTION on each checkpoint
+.TP
+\fB\-\-full\-time\fR
+print file time to its full resolution
+.TP
+\fB\-\-index\-file\fR=\fIFILE\fR
+send verbose output to FILE
+.TP
+\fB\-l\fR, \fB\-\-check\-links\fR
+print a message if not all links are dumped
+.TP
+\fB\-\-no\-quote\-chars\fR=\fISTRING\fR
+disable quoting for characters from STRING
+.TP
+\fB\-\-quote\-chars\fR=\fISTRING\fR
+additionally quote characters from STRING
+.TP
+\fB\-\-quoting\-style\fR=\fISTYLE\fR
+set name quoting style; see below for valid STYLE
+values
+.TP
+\fB\-R\fR, \fB\-\-block\-number\fR
+show block number within archive with each message
+.TP
+\fB\-\-show\-defaults\fR
+show tar defaults
+.TP
+\fB\-\-show\-omitted\-dirs\fR
+when listing or extracting, list each directory
+that does not match search criteria
+.TP
+\fB\-\-show\-snapshot\-field\-ranges\fR
+show valid ranges for snapshot-file fields
+.TP
+\fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
+show file or archive names after transformation
+.TP
+\fB\-\-totals\fR[=\fISIGNAL\fR]
+print total bytes after processing the archive;
+with an argument - print total bytes when this
+SIGNAL is delivered; Allowed signals are: SIGHUP,
+SIGQUIT, SIGINT, SIGUSR1 and SIGUSR2; the names
+without SIG prefix are also accepted
+.TP
+\fB\-\-utc\fR
+print file modification times in UTC
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely list files processed
+.TP
+\fB\-\-warning\fR=\fIKEYWORD\fR
+warning control
+.TP
+\fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
+ask for confirmation for every action
+.IP
+Compatibility options:
+.TP
+\fB\-o\fR
+when creating, same as \fB\-\-old\-archive\fR; when
+extracting, same as \fB\-\-no\-same\-owner\fR
+.IP
+Other options:
+.TP
+-?, \fB\-\-help\fR
+give this help list
+.TP
+\fB\-\-restrict\fR
+disable use of some potentially harmful options
+.TP
+\fB\-\-usage\fR
+give a short usage message
+.TP
+\fB\-\-version\fR
+print program version
+.PP
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+.PP
+The backup suffix is '~', unless set with \fB\-\-suffix\fR or SIMPLE_BACKUP_SUFFIX.
+The version control may be set with \fB\-\-backup\fR or VERSION_CONTROL, values are:
+.TP
+none, off
+never make backups
+.TP
+t, numbered
+make numbered backups
+.TP
+nil, existing
+numbered if numbered backups exist, simple otherwise
+.TP
+never, simple
+always make simple backups
+.PP
+Valid arguments for the \fB\-\-quoting\-style\fR option are:
+.IP
+literal
+shell
+shell-always
+shell-escape
+shell-escape-always
+c
+c-maybe
+escape
+locale
+clocale
+.PP
+*This* tar defaults to:
+\fB\-\-format\fR=\fIgnu\fR \fB\-f\-\fR \fB\-b20\fR \fB\-\-quoting\-style\fR=\fIescape\fR \fB\-\-rmt\-command=\fR/usr/sbin/rmt
+\fB\-\-rsh\-command=\fR/usr/bin/ssh
+.SH AUTHOR
+Written by John Gilmore and Jay Fenlason.
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B tar
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B tar
+programs are properly installed at your site, the command
+.IP
+.B info tar
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/tbl.1 b/upstream/mageia-cauldron/man1/tbl.1
new file mode 100644
index 00000000..32e4346f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tbl.1
@@ -0,0 +1,1233 @@
+'\" t
+.TH TBL 1 "18 November 2018" "groff 1.22.4"
+.SH NAME
+tbl \- format tables for troff
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr tbl_C \n[.C]
+.cp 0
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Bernd Warken <groff-bernd.warken-72@web.de> added simple examples.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY tbl
+.OP \-Cv
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This manual page describes the GNU version of
+.BR tbl ,
+which is part of the groff document formatting system.
+.
+.B tbl
+compiles descriptions of tables embedded within
+.B troff
+input files into commands that are understood by
+.BR troff .
+.
+Normally, it should be invoked using the
+.B \-t
+option of
+.B groff.
+.
+It is highly compatible with Unix
+.BR tbl .
+.
+The output generated by GNU
+.B tbl
+cannot be processed with Unix
+.BR troff ;
+it must be processed with GNU
+.BR troff .
+.
+If no files are given on the command line or a filename of
+.B \-
+is given, the standard input is read.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+.TP
+.B \-C
+Enable compatibility mode to
+recognize
+.B .TS
+and
+.B .TE
+even when followed by a character other than space or newline.
+.
+Leader characters (\[rs]a) are handled as interpreted.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.
+.\" ====================================================================
+.SH "LANGUAGE OVERVIEW"
+.\" ====================================================================
+.
+.B tbl
+expects to find table descriptions wrapped in the
+.B .TS
+(table start) and
+.B .TE
+(table end) macros.
+.
+Within each such table sections, another table can be defined by
+using the request
+.B .T&
+before the final command
+.BR .TE .
+.
+Each table definition has the following structure:
+.
+.TP
+.I Global options
+This is optional.
+.
+This table part can use several of these options distributed in 1 or
+more lines.
+.
+The
+.I global option part
+must always be finished by a
+.B "semi-colon ;" .
+.
+.TP
+.I Table format specification
+.
+This part must be given, it is not optional.
+.
+It determines the number of columns (cells) of the table.
+.
+Moreover each cell is classified by being central, left adjusted, or
+numerical, etc.
+.
+This specification can have several lines, but must be finished by a
+.B dot .
+at the end of the last line.
+.
+After each cell definition,
+.I column specifiers
+can be appended, but that's optional.
+.
+.
+.P
+Cells are separated by a tab character by default.
+.
+That can be changed by the
+.I global option
+.BI tab( c )\c
+,
+where
+.I c
+is an arbitrary character.
+.
+.
+.\" ====================================================================
+.SH "SIMPLE EXAMPLES"
+.\" ====================================================================
+.
+The easiest table definition is.
+.RS
+.EX
+\&.TS
+c c c .
+This	is	centered
+Well,	this	also
+\&.TE
+.EE
+.RE
+.
+.
+By using
+.B c c
+.BR c ,
+each cell in the whole table will be centered.
+.
+The separating character is here the default
+.IR tab .
+.
+.
+.P
+The result is
+.RS
+.TS
+c c c .
+This	is	centered
+Well,	this	also
+.TE
+.RE
+.
+.
+.P
+This definition is identical to
+.RS
+.EX
+\&.TS
+tab(@);
+ccc.
+This@is@centered
+Well,@this@also
+\&.TE
+.EE
+.RE
+.
+Here, the separating tab character is changed to the letter
+.BR @ .
+.
+.
+.P
+Moreover a title can be added and the centering directions can be
+changed to many other formats:
+.RS
+.EX
+\&.TS
+tab(@);
+c s s
+l c n .
+Title
+left@centers@123
+another@number@75
+\&.TE
+.EE
+.RE
+.
+The result is
+.RS
+.TS
+tab(@);
+c s s
+l c n .
+Title
+left@centers@123
+another@number@75
+.TE
+.RE
+.
+Here
+.B l
+means
+.IR left\-justified ,
+and
+.B n
+means
+.IR numerical ,
+which is here
+.IR right\-justified .
+.
+.
+.\" ====================================================================
+.SH USAGE
+.
+.\" ====================================================================
+.SS Global options
+.\" ====================================================================
+.
+The line immediately following the
+.B .TS
+macro may contain any of the following global options (ignoring the
+case of characters \[en] Unix tbl only accepts options with all
+characters lowercase or all characters uppercase), separated by
+spaces, tabs, or commas:
+.
+.TP
+.B allbox
+Enclose each item of the table in a box.
+.
+.TP
+.B box
+Enclose the table in a box.
+.
+.TP
+.B center
+Center the table (default is left-justified).
+.
+The alternative keyword name
+.B centre
+is also recognized (this is a GNU tbl extension).
+.
+.TP
+.BI decimalpoint( c )
+Set the character to be recognized as the decimal point in numeric
+columns (GNU tbl only).
+.
+.TP
+.BI delim( xy )
+Use
+.I x
+and\~\c
+.I y
+as start and end delimiters for
+.BR eqn (1).
+.
+.TP
+.B doublebox
+Enclose the table in a double box.
+.
+.TP
+.B doubleframe
+Same as doublebox (GNU tbl only).
+.
+.TP
+.B expand
+Make the table as wide as the current line length (providing a column
+separation factor).
+.
+Ignored if one or more \[oq]x\[cq] column specifiers are used (see
+below).
+.
+.IP
+In case the sum of the column widths is larger than the current line length,
+the column separation factor is set to zero; such tables extend into the
+right margin, and there is no column separation at all.
+.
+.TP
+.B frame
+Same as box (GNU tbl only).
+.
+.TP
+.BI linesize( n )
+Set lines or rules (e.g.\& from
+.BR box )
+in
+.IR n -point
+type.
+.
+.TP
+.B nokeep
+Don't use diversions to prevent page breaks (GNU tbl only).
+.
+Normally
+.B tbl
+attempts to prevent undesirable breaks in boxed tables by using diversions.
+.
+This can sometimes interact badly with macro packages' own use of
+diversions\[em]when footnotes, for example, are used.
+.
+.TP
+.B nospaces
+Ignore leading and trailing spaces in data items (GNU tbl only).
+.
+.TP
+.B nowarn
+Turn off warnings related to tables exceeding the current line width
+(GNU tbl only).
+.
+.TP
+.BI tab( x )
+Use the character
+.I x
+instead of a tab to separate items in a line of input data.
+.
+.
+.LP
+The global options must end with a semicolon.
+.
+There might be whitespace between an option and its argument in
+parentheses.
+.
+.
+.\" ====================================================================
+.SS Table format specification
+.\" ====================================================================
+.
+After global options come lines describing the format of each line of
+the table.
+.
+Each such format line describes one line of the table itself, except
+that the last format line (which you must end with a period) describes
+all remaining lines of the table.
+.
+A single-key character describes each column of each line of the table.
+Key characters can be separated by spaces or tabs.
+.
+You may run format specifications for multiple lines together on the
+same line by separating them with commas.
+.
+.
+.LP
+You may follow each key character with specifiers that determine the
+font and point size of the corresponding item, that determine column
+width, inter-column spacing, etc.
+.
+.
+.LP
+The longest format line defines the number of columns in the table;
+missing format descriptors at the end of format lines are assumed to
+be\~\c
+.BR L .
+.
+Extra columns in the data (which have no corresponding format entry)
+are ignored.
+.
+.
+.LP
+The available key characters are:
+.
+.TP
+.BR a , A
+Center longest line in this column and then left-justifies all other
+lines in this column with respect to that centered line.
+.
+The idea is to use such alphabetic subcolumns (hence the name of the
+key character) in combination with\~
+.BR L ;
+they are called subcolumns because
+.BR A \~items
+are indented by\~1n relative to
+.BR L \~entries.
+.
+Example:
+.RS
+.IP
+.EX
+\&.TS
+\&tab(;);
+\&ln,an.
+\&item one;1
+\&subitem two;2
+\&subitem three;3
+\&.T&
+\&ln,an.
+\&item eleven;11
+\&subitem twentytwo;22
+\&subitem thirtythree;33
+\&.TE
+.EE
+.RE
+.
+.IP
+Result:
+.
+.RS
+.IP
+.TS
+tab(;);
+ln,an.
+item one;1
+subitem two;2
+subitem three;3
+.T&
+ln,an.
+item eleven;11
+subitem twentytwo;22
+subitem thirtythree;33
+.TE
+.RE
+.
+.TP
+.BR c , C
+Center item within the column.
+.
+.TP
+.BR l , L
+Left-justify item within the column.
+.
+.TP
+.BR n , N
+Numerically justify item in the column: Units positions of numbers are
+aligned vertically.
+.
+If there is one or more dots adjacent to a digit, use the rightmost one for
+vertical alignment.
+.
+If there is no dot, use the rightmost digit for vertical alignment;
+otherwise, center the item within the column.
+.
+Alignment can be forced to a certain position using \[oq]\[rs]&\[cq];
+if there is one or more instances of this special (non-printing)
+character present within the data, use the leftmost one for alignment.
+.
+Example:
+.RS
+.IP
+.EX
+\&.TS
+\&n.
+\&1
+\&1.5
+\&1.5.3
+\&abcde
+\&a\[rs]&bcde
+\&.TE
+.EE
+.RE
+.
+.IP
+Result:
+.
+.RS
+.IP
+.TS
+n.
+1
+1.5
+1.5.3
+abcde
+a\&bcde
+.TE
+.RE
+.
+.IP
+If numerical entries are combined with
+.B L
+or
+.BR R \~entries
+\[en] this can happen if the table format is changed with
+.B .T&
+\%\[en]
+center the widest
+.I number
+(of the data entered under the
+.BR N \~specifier
+regime) relative to the widest
+.B L
+or
+.BR R \~entry,
+preserving the alignment of all numerical entries.
+.
+Contrary to
+.BR A \~type
+entries, there is no extra indentation.
+.
+.IP
+Using equations (to be processed with
+.BR eqn )
+within columns which use the
+.BR N \~specifier
+is problematic in most cases due to
+.BR tbl 's
+algorithm for finding the vertical alignment, as described above.
+.
+Using the global
+.B delim
+option, however, it is possible to make
+.B tbl
+ignore the data within
+.B eqn
+delimiters for that purpose.
+.
+.
+.TP
+.BR r , R
+Right-justify item within the column.
+.
+.TP
+.BR s , S
+Span previous item on the left into this column.
+.
+Not allowed for the first column.
+.
+.TP
+.B ^
+Span down entry from previous row in this column.
+.
+Not allowed for the first row.
+.
+.TP
+.BR _ , -
+Replace this entry with a horizontal line.
+.
+Note that \[oq]_\[cq] and \[oq]-\[cq] can be used for table fields only,
+not for column separator lines.
+.
+.TP
+.B =
+.
+Replace this entry with a double horizontal line.
+.
+Note that \[oq]=\[cq] can be used for table fields only,
+not for column separator lines.
+.
+.TP
+.B |
+The corresponding column becomes a vertical rule (if two of these are
+adjacent, a double vertical rule).
+.
+.
+.LP
+A vertical bar to the left of the first key letter or to the right of
+the last one produces a line at the edge of the table.
+.
+.
+.LP
+To change the data format within a table, use the
+.B .T&
+command (at the start of a line).
+.
+It is followed by format and data lines (but no global options)
+similar to the
+.B .TS
+request.
+.
+.
+.\" ====================================================================
+.SS Column specifiers
+.\" ====================================================================
+.
+Here are the specifiers that can appear in suffixes to column key
+letters (in any order):
+.
+.TP
+.BR b , B
+Short form of
+.B fB
+(make affected entries bold).
+.
+.TP
+.BR d , D
+Start an item that vertically spans rows,
+using the \[oq]^\[cq] column specifier or \[oq]\[rs]^\[cq] data item,
+at the bottom of its range rather
+than vertically centering it (GNU tbl only).
+.
+Example:
+.RS
+.IP
+.EX
+\&.TS
+\&tab(;) allbox;
+\&l l
+\&l ld
+\&r ^
+\&l rd.
+\&0000;foobar
+\&T{
+\&1111
+\&.br
+\&2222
+\&T};foo
+\&r;
+\&T{
+\&3333
+\&.br
+\&4444
+\&T};bar
+\&\[rs]^;\[rs]^
+\&.TE
+.EE
+.RE
+.
+.IP
+Result:
+.
+.RS
+.IP
+.TS
+tab(;) allbox;
+l l
+l ld
+r ^
+l rd.
+0000;foobar
+T{
+1111
+.br
+2222
+T};foo
+r;
+T{
+3333
+.br
+4444
+T};bar
+\^;\^
+.TE
+.RE
+.
+.TP
+.BR e , E
+Make equally-spaced columns.
+.
+All columns marked with this specifier get the same width; this happens
+after the affected column widths have been computed (this means that the
+largest width value rules).
+.
+.TP
+.BR f , F
+Either of these specifiers may be followed by a font name (either one or two
+characters long), font number (a single digit), or long name in parentheses
+(the last form is a GNU tbl extension).
+.
+A one-letter font name must be separated by one or more blanks from whatever
+follows.
+.
+.TP
+.BR i , I
+Short form of
+.B fI
+(make affected entries italic).
+.
+.TP
+.BR m , M
+This is a GNU tbl extension.
+.
+Either of these specifiers may be followed by a macro name
+(either one or two characters long),
+or long name in parentheses.
+.
+A one-letter macro name must be separated by one or more blanks from
+whatever follows.
+.
+The macro which name can be specified here must be defined before
+creating the table.
+.
+It is called just before the table's cell text is output.
+.
+As implemented currently, this macro is only called if block input is
+used, that is, text between \[oq]T{\[cq] and \[oq]T}\[cq].
+.
+The macro should contain only simple
+.B troff
+requests to change the text block formatting, like text adjustment,
+hyphenation, size, or font.
+.
+The macro is called
+.I after
+other cell modifications like
+.BR b ,
+.B f
+or
+.B v
+are output.
+.
+Thus the macro can overwrite other modification specifiers.
+.
+.TP
+.BR p , P
+Followed by a number, this does a point size change for the affected fields.
+.
+If signed, the current point size is incremented or decremented (using
+a signed number instead of a signed digit is a GNU tbl extension).
+.
+A point size specifier followed by a column separation number must be
+separated by one or more blanks.
+.
+.TP
+.BR t , T
+Start an item vertically spanning rows at the top of its range rather than
+vertically centering it.
+.
+.TP
+.BR u , U
+Move the corresponding column up one half-line.
+.
+.TP
+.BR v , V
+Followed by a number, this indicates the vertical line spacing to be
+used in a multi-line table entry.
+.
+If signed, the current vertical line spacing is incremented or
+decremented (using a signed number instead of a signed digit is a GNU
+tbl extension).
+.
+A vertical line spacing specifier followed by a column separation
+number must be separated by one or more blanks.
+.
+No effect if the corresponding table entry isn't a text block.
+.
+.TP
+.BR w , W
+Minimum column width value.
+Must be followed either by a
+.BR troff (1)
+width expression in parentheses or a unitless integer.
+.
+If no unit is given, en units are used.
+.
+Also used as the default line length for included text blocks.
+.
+If used multiple times to specify the width for a particular column,
+the last entry takes effect.
+.
+.TP
+.BR x , X
+An expanded column.
+.
+After computing all column widths without an
+.BR x \~specifier,
+use the remaining line width for this column.
+.
+If there is more than one expanded column, distribute the remaining
+horizontal space evenly among the affected columns (this is a GNU
+extension).
+.
+This feature has the same effect as specifying a minimum column width.
+.
+.TP
+.BR z , Z
+Ignore the corresponding column for width-calculation purposes, this
+is, don't use the fields but only the specifiers of this column to
+compute its width.
+.
+.
+.LP
+A number suffix on a key character is interpreted as a column
+separation in en units (multiplied in proportion if the
+.B expand
+option is on \[en] in case of overfull tables this might be zero).
+.
+Default separation is 3n.
+.
+.
+.LP
+The column
+.RB specifier\~ x
+is mutually exclusive with
+.B e
+.RB and\~ w
+(but
+.B e
+is not mutually exclusive
+.RB with\~ w );
+if specified multiple times for a particular column, the last entry takes
+effect:
+.BR x \~unsets
+both
+.B e
+.RB and\~ w ,
+while either
+.B e
+or
+.B w
+.RB overrides\~ x .
+.
+.
+.\" ====================================================================
+.SS Table data
+.\" ====================================================================
+.
+The format lines are followed by lines containing the actual data for the
+table, followed finally by
+.BR .TE .
+.
+Within such data lines, items are normally separated by tab characters
+(or the character specified with the
+.B tab
+option).
+.
+Long input lines can be broken across multiple lines if the last
+character on the line is \[oq]\[rs]\[cq] (which vanishes after
+concatenation).
+.
+.
+.LP
+Note that
+.B tbl
+computes the column widths line by line, applying \[rs]w on each entry
+which isn't a text block.
+.
+As a consequence, constructions like
+.IP
+.EX
+\&.TS
+\&c,l.
+\&\[rs]s[20]MM
+\&MMMM
+\&.TE
+.EE
+.
+.LP
+fail; you must either say
+.IP
+.EX
+\&.TS
+\&cp20,lp20.
+\&MM
+\&MMMM
+\&.TE
+.EE
+.
+.LP
+or
+.
+.IP
+.EX
+\&.TS
+\&c,l.
+\&\[rs]s[20]MM
+\&\[rs]s[20]MMMM
+\&.TE
+.EE
+.
+.
+.LP
+A dot starting a line, followed by anything but a digit is handled as
+a troff command, passed through without changes.
+.
+The table position is unchanged in this case.
+.
+.
+.LP
+If a data line consists of only \[oq]_\[cq] or \[oq]=\[cq], a single
+or double line, respectively, is drawn across the table at that point;
+if a single item in a data line consists of only \[oq]_\[cq] or
+\[oq]=\[cq], then that item is replaced by a single or double line,
+joining its neighbours.
+.
+If a data item consists only of \[oq]\[rs]_\[cq] or \[oq]\[rs]=\[cq],
+a single or double line, respectively, is drawn across the field at
+that point which does not join its neighbours.
+.
+.
+.LP
+A data item consisting only of \[oq]\[rs]Rx\[cq] (\[oq]x\[cq] any
+character) is replaced by repetitions of character \[oq]x\[cq] as wide
+as the column (not joining its neighbours).
+.
+.
+.LP
+A data item consisting only of \[oq]\[rs]^\[cq] indicates that the
+field immediately above spans downward over this row.
+.
+.
+.\" ====================================================================
+.SS Text blocks
+.\" ====================================================================
+.
+A text block can be used to enter data as a single entry which would
+be too long as a simple string between tabs.
+.
+It is started with \[oq]T{\[cq] and closed with \[oq]T}\[cq].
+.
+The former must end a line, and the latter must start a line, probably
+followed by other data columns (separated with tabs or the character
+given with the
+.B tab
+global option).
+.
+.
+.LP
+By default, the text block is formatted with the settings which were
+active before entering the table, possibly overridden by the
+.BR m ,
+.BR v ,
+and
+.B w
+tbl specifiers.
+.
+For example, to make all text blocks ragged-right, insert
+.B .na
+right before the starting
+.B .TS
+(and
+.B .ad
+after the table).
+.
+.
+.LP
+If either \[oq]w\[cq] or \[oq]x\[cq] specifiers are not given for
+.I all
+columns of a text block span, the default length of the text block (to
+be more precise, the line length used to process the text block
+diversion) is computed as L\[tmu]C/(N+1), where \[oq]L\[cq] is the
+current line length, \[oq]C\[cq] the number of columns spanned by the
+text block, and \[oq]N\[cq] the total number of columns in the table.
+.
+Note, however, that the actual diversion width as returned in register
+.B \[rs]n[dl]
+is used eventually as the text block width.
+.
+If necessary, you can also control the text block width with a direct
+insertion of a
+.B .ll
+request right after \[oq]T{\[cq].
+.
+.
+.\" ====================================================================
+.SS Miscellaneous
+.\" ====================================================================
+.
+The number register
+.B \[rs]n[TW]
+holds the table width; it can't be used within the table itself
+but is defined right before calling
+.B .TE
+so that this macro can make use of it.
+.
+.
+.LP
+.B tbl
+also defines a macro
+.B .T#
+which produces the bottom and side lines of a boxed table.
+.
+While
+.B tbl
+does call this macro itself at the end of the table, it can be used by
+macro packages to create boxes for multi-page tables by calling it within the
+page footer.
+.
+An example of this is shown by the
+.B \-ms
+macros which provide this functionality if a table starts with
+.B .TS\ H
+instead of the standard call to the
+.B .TS
+macro.
+.
+.
+.\" ====================================================================
+.SH "INTERACTION WITH EQN"
+.\" ====================================================================
+.
+.BR tbl (1)
+should always be called before
+.BR eqn (1)
+.RB ( groff (1)
+automatically takes care of the correct order of preprocessors).
+.
+.
+.\" ====================================================================
+.SH "GNU TBL ENHANCEMENTS"
+.\" ====================================================================
+.
+There is no limit on the number of columns in a table, nor any limit on the
+number of text blocks.
+.
+All the lines of a table are considered in deciding column widths, not just
+the first 200.
+.
+Table continuation
+.RB ( .T& )
+lines are not restricted to the first 200 lines.
+.
+.
+.LP
+Numeric and alphabetic items may appear in the same column.
+.
+.
+.LP
+Numeric and alphabetic items may span horizontally.
+.
+.
+.LP
+.B tbl
+uses register, string, macro and diversion names beginning with the digit\~\c
+.BR 3 .
+.
+When using
+.B tbl
+you should avoid using any names beginning with a\~\c
+.BR 3 .
+.
+.
+.\" ====================================================================
+.SH "GNU TBL WITHIN MACROS"
+.\" ====================================================================
+.
+Since
+.B tbl
+defines its own macros (right before each table) it is necessary to use
+an \[oq]end-of-macro\[cq] macro.
+.
+Additionally, the escape character has to be switched off.
+.
+Here an example.
+.IP
+.EX
+\&.eo
+\&.de ATABLE ..
+\&.TS
+\&allbox tab(;);
+\&cl.
+\&\[rs]$1;\[rs]$2
+\&.TE
+\&...
+\&.ec
+\&.ATABLE A table
+\&.ATABLE Another table
+\&.ATABLE And \[dq]another one\[dq]
+.EE
+.
+.
+.LP
+Note, however, that not all features of
+.B tbl
+can be wrapped into a macro because
+.B tbl
+sees the input earlier than
+.BR troff .
+.
+For example, number formatting with vertically aligned decimal points
+fails if those numbers are passed on as macro parameters because
+decimal point alignment is handled by
+.B tbl
+itself: It only sees \[oq]\[rs]$1\[cq], \[oq]\[rs]$2\[cq], etc., and
+therefore can't recognize the decimal point.
+.
+.
+.\" ====================================================================
+.SH BUGS
+.\" ====================================================================
+.
+You should use
+.BR .TS\ H / .TH
+in conjunction with a supporting macro package for
+.I all
+multi-page boxed tables.
+.
+If there is no header that you wish to appear at the top of each page
+of the table, place the
+.B .TH
+line immediately after the format section.
+.
+Do not enclose a multi-page table within keep/release macros,
+or divert it in any other way.
+.
+.
+.LP
+A text block within a table must be able to fit on one page.
+.
+.
+.LP
+The
+.B bp
+request cannot be used to force a page-break in a multi-page table.
+.
+Instead, define
+.B BP
+as follows
+.
+.IP
+.EX
+\&.de BP
+\&.  ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
+\&.  el \[rs]!.BP \[rs]\[rs]$1
+\&..
+.EE
+.
+.
+.LP
+and use
+.B BP
+instead of
+.BR bp .
+.
+.
+.LP
+Using \[rs]a directly in a table to get leaders does not work (except in
+compatibility mode).
+.
+This is correct behaviour: \[rs]a is an
+.B uninterpreted
+leader.
+.
+To get leaders use a real leader, either by using a control A or like
+this:
+.
+.IP
+.EX
+\&.ds a \[rs]a
+\&.TS
+\&tab(;);
+\&lw(1i) l.
+\&A\[rs]*a;B
+\&.TE
+.EE
+.
+.
+.LP
+A leading and/or trailing \[oq]|\[cq] in a format line, such as
+.
+.IP
+.EX
+|l r|.
+.EE
+.
+.
+.LP
+gives output which has a 1n\~space between the resulting
+bordering vertical rule and the content of the adjacent column,
+as in
+.
+.IP
+.EX
+\&.TS
+\&tab(#);
+\&|l r|.
+\&left column#right column
+\&.TE
+.EE
+.
+.
+.LP
+If it is desired to have zero space (so that the rule touches
+the content), this can be achieved by introducing extra \[lq]dummy\[rq]
+columns, with no content and zero separation, before and/or after,
+as in
+.
+.IP
+.EX
+\&.TS
+\&tab(#);
+\&r0|l r0|l.
+\&#left column#right column#
+\&.TE
+.EE
+.
+.
+.LP
+The resulting \[lq]dummy\[rq] columns are invisible and have zero width;
+note that such columns usually don't work with TTY devices.
+.
+.
+.\" ====================================================================
+.SH REFERENCE
+.\" ====================================================================
+Lesk, M.E.: "TBL \[en] A Program to Format Tables".
+For copyright reasons it cannot be included in the groff distribution,
+but copies can be found with a title search on the World Wide Web.
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR groff (1),
+.BR troff (1)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[tbl_C]
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/tee.1 b/upstream/mageia-cauldron/man1/tee.1
new file mode 100644
index 00000000..048c2736
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tee.1
@@ -0,0 +1,63 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TEE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tee \- read from standard input and write to standard output and files
+.SH SYNOPSIS
+.B tee
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Copy standard input to each FILE, and also to standard output.
+.TP
+\fB\-a\fR, \fB\-\-append\fR
+append to the given FILEs, do not overwrite
+.TP
+\fB\-i\fR, \fB\-\-ignore\-interrupts\fR
+ignore interrupt signals
+.TP
+\fB\-p\fR
+diagnose errors writing to non pipes
+.TP
+\fB\-\-output\-error\fR[=\fI\,MODE\/\fR]
+set behavior on write error.  See MODE below
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SS "MODE determines behavior with write errors on the outputs:"
+.TP
+warn
+diagnose errors writing to any output
+.TP
+warn\-nopipe
+diagnose errors writing to any output not a pipe
+.TP
+exit
+exit on error writing to any output
+.TP
+exit\-nopipe
+exit on error writing to any output not a pipe
+.PP
+The default MODE for the \fB\-p\fR option is 'warn\-nopipe'.
+The default operation when \fB\-\-output\-error\fR is not specified, is to
+exit immediately on error writing to a pipe, and diagnose errors
+writing to non pipe outputs.
+.SH AUTHOR
+Written by Mike Parker, Richard M. Stallman, and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/tee>
+.br
+or available locally via: info \(aq(coreutils) tee invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/telnet.1 b/upstream/mageia-cauldron/man1/telnet.1
new file mode 100644
index 00000000..ae193957
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/telnet.1
@@ -0,0 +1,1509 @@
+.\"	$OpenBSD: telnet.1,v 1.27 2000/11/09 17:52:41 aaron Exp $
+.\"	$NetBSD: telnet.1,v 1.5 1996/02/28 21:04:12 thorpej Exp $
+.\"
+.\" Copyright (c) 1983, 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	from: @(#)telnet.1	8.4 (Berkeley) 2/3/94
+.\"
+.Dd February 3, 1994
+.Dt TELNET 1
+.Os
+.Sh NAME
+.Nm telnet
+.Nd user interface to the
+.Tn TELNET
+protocol
+.Sh SYNOPSIS
+.Nm telnet
+.Op Fl 8EFKLacdfrx
+.Op Fl X Ar authtype
+.Op Fl b Ar hostalias
+.Op Fl e Ar escapechar
+.Op Fl k Ar realm
+.Op Fl l Ar user
+.Op Fl n Ar tracefile
+.Oo
+.Ar host
+.Op Ar port
+.Oc
+.Sh DESCRIPTION
+The
+.Nm
+command
+is used to communicate with another host using the
+.Tn TELNET
+protocol.
+If
+.Nm
+is invoked without the
+.Ar host
+argument, it enters command mode,
+indicated by its prompt
+.Pq Nm telnet\&> .
+In this mode, it accepts and executes the commands listed below.
+If it is invoked with arguments, it performs an
+.Ic open
+command with those arguments.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 7
+Strip 8th bit on input and output. Telnet is 8-bit clean by default but doesn't send the TELNET BINARY option unless forced.
+.It Fl 8
+Specifies an 8-bit data path.
+This causes an attempt to negotiate the
+.Dv TELNET BINARY
+option on both input and output.
+.It Fl E
+Stops any character from being recognized as an escape character.
+.It Fl F
+If Kerberos V5 authentication is being used, the
+.Fl F
+option allows the local credentials to be forwarded
+to the remote system, including any credentials that
+have already been forwarded into the local environment.
+.It Fl K
+Specifies no automatic login to the remote system.
+.It Fl L
+Specifies an 8-bit data path on output.
+This causes the BINARY option to be negotiated on output.
+.It Fl X Ar atype
+Disables the
+.Ar atype
+type of authentication.
+.It Fl a
+Attempt automatic login.
+Currently, this sends the user name via the
+.Ev USER
+variable
+of the
+.Ev ENVIRON
+option if supported by the remote system.
+The name used is that of the current user as returned by
+.Xr getlogin 2
+if it agrees with the current user ID,
+otherwise it is the name associated with the user ID.
+.It Fl b Ar hostalias
+Uses
+.Xr bind 2
+on the local socket to bind it to an aliased address (see
+.Xr ifconfig 8
+and the ``alias'' specifier) or to the address of
+another interface than the one naturally chosen by
+.Xr connect 2 .
+This can be useful when connecting to services which use IP addresses
+for authentication and reconfiguration of the server is undesirable (or
+impossible).
+.It Fl c
+Disables the reading of the user's
+.Pa \&.telnetrc
+file.
+(See the
+.Ic toggle skiprc
+command on this man page.)
+.It Fl d
+Sets the initial value of the
+.Ic debug
+toggle to
+.Dv TRUE .
+.It Fl e Ar escapechar
+Sets the initial
+.Nm
+escape character to
+.Ar escapechar Ns .
+If
+.Ar escapechar
+is omitted, then
+there will be no escape character.
+.It Fl f
+If Kerberos V5 authentication is being used, the
+.Fl f
+option allows the local credentials to be forwarded to the remote system.
+.It Fl k Ar realm
+If Kerberos authentication is being used, the
+.Fl k
+option requests that
+.Nm
+obtain tickets for the remote host in
+realm
+.Ar realm
+instead of the remote host's realm, as determined
+by
+.Xr krb_realmofhost 3 .
+.It Fl l Ar user
+When connecting to the remote system, if the remote system
+understands the
+.Ev ENVIRON
+option, then
+.Ar user
+will be sent to the remote system as the value for the variable USER.
+This option implies the
+.Fl a
+option.
+This option may also be used with the
+.Ic open
+command.
+.It Fl n Ar tracefile
+Opens
+.Ar tracefile
+for recording trace information.
+See the
+.Ic set tracefile
+command below.
+.It Fl r
+Specifies a user interface similar to
+.Xr rlogin 1 .
+In this
+mode, the escape character is set to the tilde (~) character,
+unless modified by the
+.Fl e
+option.
+.It Fl x
+Turns on encryption of the data stream if possible.
+.It Ar host
+Indicates the official name, an alias, or the Internet address
+of a remote host.
+.It Ar port
+Indicates a port number (address of an application).
+If a number is not specified, the default
+.Nm
+port is used.
+.El
+.Pp
+When in rlogin mode, a line of the form ~.
+disconnects from the
+remote host; ~ is the telnet escape character.
+Similarly, the line ~^Z suspends the telnet session.
+The line ~^] escapes to the normal telnet escape prompt.
+.Pp
+Once a connection has been opened,
+.Nm
+will attempt to enable the
+.Dv TELNET LINEMODE
+option.
+If this fails,
+.Nm
+will revert to one of two input modes:
+either ``character at a time''
+or ``old line by line''
+depending on what the remote system supports.
+.Pp
+When
+.Dv LINEMODE
+is enabled, character processing is done on the
+local system, under the control of the remote system.
+When input
+editing or character echoing is to be disabled, the remote system
+will relay that information.
+The remote system will also relay
+changes to any special characters that happen on the remote
+system, so that they can take effect on the local system.
+.Pp
+In ``character at a time'' mode, most
+text typed is immediately sent to the remote host for processing.
+.Pp
+In ``old line by line'' mode, all text is echoed locally,
+and (normally) only completed lines are sent to the remote host.
+The ``local echo character'' (initially ``^E'') may be used
+to turn off and on the local echo
+(this would mostly be used to enter passwords
+without the password being echoed).
+.Pp
+If the
+.Dv LINEMODE
+option is enabled, or if the
+.Ic localchars
+toggle is
+.Dv TRUE
+(the default for ``old line by line''; see below),
+the user's
+.Ic quit ,
+.Ic intr ,
+and
+.Ic flush
+characters are trapped locally, and sent as
+.Tn TELNET
+protocol sequences to the remote side.
+If
+.Dv LINEMODE
+has ever been enabled, then the user's
+.Ic susp
+and
+.Ic eof
+are also sent as
+.Tn TELNET
+protocol sequences,
+and
+.Ic quit
+is sent as a
+.Dv TELNET ABORT
+instead of
+.Dv BREAK .
+There are options (see
+.Ic toggle
+.Ic autoflush
+and
+.Ic toggle
+.Ic autosynch
+below)
+which cause this action to flush subsequent output to the terminal
+(until the remote host acknowledges the
+.Tn TELNET
+sequence) and flush previous terminal input
+(in the case of
+.Ic quit
+and
+.Ic intr ) .
+.Pp
+While connected to a remote host,
+.Nm
+command mode may be entered by typing the
+.Nm
+``escape character'' (initially ``^]'').
+When in command mode, the normal terminal editing conventions are available.
+Note that the escape character will return to the command mode of the initial
+invocation of
+.Nm
+that has the controlling terminal.
+Use the
+.Cm send escape
+command to switch to command mode in subsequent
+.Nm
+processes on remote hosts.
+.Pp
+The following
+.Nm
+commands are available.
+Only enough of each command to uniquely identify it need be typed
+(this is also true for arguments to the
+.Ic mode ,
+.Ic set ,
+.Ic toggle ,
+.Ic unset ,
+.Ic slc ,
+.Ic environ ,
+and
+.Ic display
+commands).
+.Bl -tag -width "mode type"
+.It Ic auth Ar argument Op Ar ...
+The
+.Ic auth
+command manipulates the information sent through the
+.Dv TELNET AUTHENTICATE
+option.
+Valid arguments for the
+.Ic auth
+command are as follows:
+.Bl -tag -width "disable type"
+.It Ic disable Ar type
+Disables the specified
+.Ar type
+of authentication.
+To obtain a list of available types, use the
+.Ic auth disable \&?
+command.
+.It Ic enable Ar type
+Enables the specified
+.Ar type
+of authentication.
+To obtain a list of available types, use the
+.Ic auth enable \&?
+command.
+.It Ic status
+Lists the current status of the various types of
+authentication.
+.El
+.It Ic close
+Close a
+.Tn TELNET
+session and return to command mode.
+.It Ic display Ar argument Op Ar ...
+Displays all, or some, of the
+.Ic set
+and
+.Ic toggle
+values (see below).
+.It Ic encrypt Ar argument Op Ar ...
+The
+.Ic encrypt
+command manipulates the information sent through the
+.Dv TELNET ENCRYPT
+option.
+.Pp
+Valid arguments for the encrypt command are as follows:
+.Bl -tag -width Ar
+.It Ic disable Ar type Ic [input|output]
+Disables the specified
+.Ar type
+of encryption.
+If you omit
+.Ic input
+and
+.Ic output ,
+both input and output
+are disabled.
+To obtain a list of available types, use the
+.Ic encrypt disable \&?
+command.
+.It Ic enable Ar type Ic [input|output]
+Enables the specified
+.Ar type
+of encryption.
+If you omit
+.Ic input
+and
+.Ic output ,
+both input and output are
+enabled.
+To obtain a list of available types, use the
+.Ic encrypt enable \&?
+command.
+.It Ic input
+This is the same as the
+.Ic encrypt start input
+command.
+.It Ic -input
+This is the same as the
+.Ic encrypt stop input
+command.
+.It Ic output
+This is the same as the
+.Ic encrypt start output
+command.
+.It Ic -output
+This is the same as the
+.Ic encrypt stop output
+command.
+.It Ic start Ic [input|output]
+Attempts to start encryption.
+If you omit
+.Ic input
+and
+.Ic output ,
+both input and output are enabled.
+To obtain a list of available types, use the
+.Ic encrypt enable \&?
+command.
+.It Ic status
+Lists the current status of encryption.
+.It Ic stop Ic [input|output]
+Stops encryption.
+If you omit
+.Ic input
+and
+.Ic output ,
+encryption is on both input and output.
+.It Ic type Ar type
+Sets the default type of encryption to be used
+with later
+.Ic encrypt start
+or
+.Ic encrypt stop
+commands.
+.El
+.It Ic environ Ar arguments Op Ar ...
+The
+.Ic environ
+command is used to manipulate the
+variables that may be sent through the
+.Dv TELNET ENVIRON
+option.
+The initial set of variables is taken from the user's
+environment, with only the
+.Ev DISPLAY ,
+.Ev PRINTER ,
+and
+.Ev XAUTHORITY
+variables being exported by default.
+The
+.Ev USER
+variable is also exported if the
+.Fl a
+or
+.Fl l
+options are used.
+Additionally, the value of the
+.Ev TERM
+variable is by default available to be queried by the server.
+.Pp
+Valid arguments for the
+.Ic environ
+command are:
+.Bl -tag -width Fl
+.It Ic define Ar variable value
+Define the variable
+.Ar variable
+to have a value of
+.Ar value .
+Any variables defined by this command are automatically exported.
+The
+.Ar value
+may be enclosed in single or double quotes so
+that tabs and spaces may be included.
+.It Ic undefine Ar variable
+Remove
+.Ar variable
+from the list of environment variables.
+.It Ic export Ar variable
+Mark the variable
+.Ar variable
+to be exported to the remote side.
+.It Ic unexport Ar variable
+Mark the variable
+.Ar variable
+to not be exported.
+.It Ic list
+List the current set of environment variables.
+Those marked with a
+.Cm *
+will be sent automatically,
+those marked with a
+.Cm +
+will only be sent if explicitly requested by the server,
+and others won't be revealed to the server even if requested.
+.It Ic \&?
+Prints out help information for the
+.Ic environ
+command.
+.El
+.It Ic logout
+Sends the
+.Dv TELNET LOGOUT
+option to the remote side.
+This command is similar to a
+.Ic close
+command; however, if the remote side does not support the
+.Dv LOGOUT
+option, nothing happens.
+If, however, the remote side does support the
+.Dv LOGOUT
+option, this command should cause the remote side to close the
+.Tn TELNET
+connection.
+If the remote side also supports the concept of
+suspending a user's session for later reattachment,
+the logout argument indicates that you
+should terminate the session immediately.
+.It Ic mode Ar type
+.Ar type
+is one of several options, depending on the state of the
+.Tn TELNET
+session.
+The remote host is asked for permission to go into the requested mode.
+If the remote host is capable of entering that mode, the requested
+mode will be entered.
+.Bl -tag -width Ar
+.It Ic character
+Disable the
+.Dv TELNET LINEMODE
+option, or, if the remote side does not understand the
+.Dv LINEMODE
+option, then enter ``character at a time'' mode.
+.It Ic line
+Enable the
+.Dv TELNET LINEMODE
+option, or, if the remote side does not understand the
+.Dv LINEMODE
+option, then attempt to enter ``old-line-by-line'' mode.
+.It Ic isig Pq Ic \-isig
+Attempt to enable (disable) the
+.Dv TRAPSIG
+mode of the
+.Dv LINEMODE
+option.
+This requires that the
+.Dv LINEMODE
+option be enabled.
+.It Ic edit Pq Ic \-edit
+Attempt to enable (disable) the
+.Dv EDIT
+mode of the
+.Dv LINEMODE
+option.
+This requires that the
+.Dv LINEMODE
+option be enabled.
+.It Ic softtabs Pq Ic \-softtabs
+Attempt to enable (disable) the
+.Dv SOFT_TAB
+mode of the
+.Dv LINEMODE
+option.
+This requires that the
+.Dv LINEMODE
+option be enabled.
+.It Ic litecho Pq Ic \-litecho
+Attempt to enable (disable) the
+.Dv LIT_ECHO
+mode of the
+.Dv LINEMODE
+option.
+This requires that the
+.Dv LINEMODE
+option be enabled.
+.It Ic \&?
+Prints out help information for the
+.Ic mode
+command.
+.El
+.It Xo
+.Ic open Ar host
+.Op Fl l Ar user
+.Oo Op Fl
+.Ar port Oc
+.Xc
+Open a connection to the named host.
+If no port number
+is specified,
+.Nm
+will attempt to contact a
+.Tn TELNET
+server at the default port.
+The host specification may be either a host name (see
+.Xr hosts 5 )
+or an Internet address specified in the ``dot notation'' (see
+.Xr inet 3 ) .
+The
+.Fl l
+option may be used to specify the user name
+to be passed to the remote system via the
+.Ev ENVIRON
+option.
+When connecting to a non-standard port,
+.Nm
+omits any automatic initiation of
+.Tn TELNET
+options.
+When the port number is preceded by a minus sign,
+the initial option negotiation is done.
+After establishing a connection, the file
+.Pa \&.telnetrc
+in the
+user's home directory is opened.
+Lines beginning with a ``#'' are
+comment lines.
+Blank lines are ignored.
+Lines that begin
+without whitespace are the start of a machine entry.
+The first thing on the line is the name of the machine that is
+being connected to.
+The rest of the line, and successive
+lines that begin with whitespace are assumed to be
+.Nm
+commands and are processed as if they had been typed
+in manually to the
+.Nm
+command prompt.
+.It Ic quit
+Close any open
+.Tn TELNET
+session and exit
+.Nm telnet .
+An end-of-file (in command mode) will also close a session and exit.
+.It Ic send Ar arguments
+Sends one or more special character sequences to the remote host.
+The following are the arguments which may be specified
+(more than one argument may be specified at a time):
+.Bl -tag -width escape
+.It Ic abort
+Sends the
+.Dv TELNET ABORT
+(Abort
+processes)
+sequence.
+.It Ic ao
+Sends the
+.Dv TELNET AO
+(Abort Output) sequence, which should cause the remote system to flush
+all output
+.Em from
+the remote system
+.Em to
+the user's terminal.
+.It Ic ayt
+Sends the
+.Dv TELNET AYT
+(Are You There)
+sequence, to which the remote system may or may not choose to respond.
+.It Ic brk
+Sends the
+.Dv TELNET BRK
+(Break) sequence, which may have significance to the remote
+system.
+.It Ic ec
+Sends the
+.Dv TELNET EC
+(Erase Character)
+sequence, which should cause the remote system to erase the last character
+entered.
+.It Ic el
+Sends the
+.Dv TELNET EL
+(Erase Line)
+sequence, which should cause the remote system to erase the line currently
+being entered.
+.It Ic eof
+Sends the
+.Dv TELNET EOF
+(End Of File)
+sequence.
+.It Ic eor
+Sends the
+.Dv TELNET EOR
+(End of Record)
+sequence.
+.It Ic escape
+Sends the current
+.Nm
+escape character (initially ``^]'').
+.It Ic ga
+Sends the
+.Dv TELNET GA
+(Go Ahead)
+sequence, which likely has no significance to the remote system.
+.It Ic getstatus
+If the remote side supports the
+.Dv TELNET STATUS
+command,
+.Ic getstatus
+will send the subnegotiation to request that the server send
+its current option status.
+.It Ic ip
+Sends the
+.Dv TELNET IP
+(Interrupt Process) sequence, which should cause the remote
+system to abort the currently running process.
+.It Ic nop
+Sends the
+.Dv TELNET NOP
+(No OPeration)
+sequence.
+.It Ic susp
+Sends the
+.Dv TELNET SUSP
+(SUSPend process)
+sequence.
+.It Ic synch
+Sends the
+.Dv TELNET SYNCH
+sequence.
+This sequence causes the remote system to discard all previously typed
+(but not yet read) input.
+This sequence is sent as
+.Tn TCP
+urgent
+data (and may not work if the remote system is a
+.Bx 4.2
+system -- if
+it doesn't work, a lower case ``r'' may be echoed on the terminal).
+.It Ic do Ar cmd
+Sends the
+.Dv TELNET DO
+.Ar cmd
+sequence.
+.Ar cmd
+can be either a decimal number between 0 and 255,
+or a symbolic name for a specific
+.Dv TELNET
+command.
+.Ar cmd
+can also be either
+.Ic help
+or
+.Ic \&?
+to print out help information, including
+a list of known symbolic names.
+.It Ic dont Ar cmd
+Sends the
+.Dv TELNET DONT
+.Ar cmd
+sequence.
+.Ar cmd
+can be either a decimal number between 0 and 255,
+or a symbolic name for a specific
+.Dv TELNET
+command.
+.Ar cmd
+can also be either
+.Ic help
+or
+.Ic \&?
+to print out help information, including
+a list of known symbolic names.
+.It Ic will Ar cmd
+Sends the
+.Dv TELNET WILL
+.Ar cmd
+sequence.
+.Ar cmd
+can be either a decimal number between 0 and 255,
+or a symbolic name for a specific
+.Dv TELNET
+command.
+.Ar cmd
+can also be either
+.Ic help
+or
+.Ic \&?
+to print out help information, including
+a list of known symbolic names.
+.It Ic wont Ar cmd
+Sends the
+.Dv TELNET WONT
+.Ar cmd
+sequence.
+.Ar cmd
+can be either a decimal number between 0 and 255,
+or a symbolic name for a specific
+.Dv TELNET
+command.
+.Ar cmd
+can also be either
+.Ic help
+or
+.Ic \&?
+to print out help information, including
+a list of known symbolic names.
+.It Ic \&?
+Prints out help information for the
+.Ic send
+command.
+.El
+.It Ic set Ar argument value
+.It Ic unset Ar argument value
+The
+.Ic set
+command will set any one of a number of
+.Nm
+variables to a specific value or to
+.Dv TRUE .
+The special value
+.Ic off
+turns off the function associated with
+the variable; this is equivalent to using the
+.Ic unset
+command.
+The
+.Ic unset
+command will disable or set to
+.Dv FALSE
+any of the specified functions.
+The values of variables may be interrogated with the
+.Ic display
+command.
+The variables which may be set or unset, but not toggled, are
+listed here.
+In addition, any of the variables for the
+.Ic toggle
+command may be explicitly set or unset using
+the
+.Ic set
+and
+.Ic unset
+commands.
+.Bl -tag -width escape
+.It Ic ayt
+If
+.Tn TELNET
+is in
+.Ic localchars
+mode, or
+.Dv LINEMODE
+is enabled, and the status character is typed, a
+.Dv TELNET AYT
+sequence (see
+.Ic send ayt
+preceding) is sent to the
+remote host.
+The initial value for the "Are You There"
+character is the terminal's status character.
+.It Ic echo
+This is the value (initially ``^E'') which, when in
+``line by line'' mode, toggles between doing local echoing
+of entered characters (for normal processing), and suppressing
+echoing of entered characters (for entering, say, a password).
+.It Ic eof
+If
+.Nm
+is operating in
+.Dv LINEMODE
+or ``old line by line'' mode, entering this character
+as the first character on a line will cause this character to be
+sent to the remote system.
+The initial value of the
+.Ic eof
+character is taken to be the terminal's
+.Ic eof
+character.
+.It Ic erase
+If
+.Nm
+is in
+.Ic localchars
+mode (see
+.Ic toggle
+.Ic localchars
+below),
+and if
+.Nm
+is operating in ``character at a time'' mode, then when this
+character is typed, a
+.Dv TELNET EC
+sequence (see
+.Ic send
+.Ic ec
+above)
+is sent to the remote system.
+The initial value for the
+.Ic erase
+character is taken to be
+the terminal's
+.Ic erase
+character.
+.It Ic escape
+This is the
+.Nm
+escape character (initially ``^['') which causes entry
+into
+.Nm
+command mode (when connected to a remote system).
+.It Ic flushoutput
+If
+.Nm
+is in
+.Ic localchars
+mode (see
+.Ic toggle
+.Ic localchars
+below)
+and the
+.Ic flushoutput
+character is typed, a
+.Dv TELNET AO
+sequence (see
+.Ic send
+.Ic ao
+above)
+is sent to the remote host.
+The initial value for the
+.Ic flush
+character is taken to be
+the terminal's
+.Ic flush
+character.
+.It Ic forw1
+.It Ic forw2
+If
+.Tn TELNET
+is operating in
+.Dv LINEMODE ,
+these are the
+characters that, when typed, cause partial lines to be
+forwarded to the remote system.
+The initial value for
+the forwarding characters are taken from the terminal's
+eol and eol2 characters.
+.It Ic interrupt
+If
+.Nm
+is in
+.Ic localchars
+mode (see
+.Ic toggle
+.Ic localchars
+below)
+and the
+.Ic interrupt
+character is typed, a
+.Dv TELNET IP
+sequence (see
+.Ic send
+.Ic ip
+above)
+is sent to the remote host.
+The initial value for the
+.Ic interrupt
+character is taken to be
+the terminal's
+.Ic intr
+character.
+.It Ic kill
+If
+.Nm
+is in
+.Ic localchars
+mode (see
+.Ic toggle
+.Ic localchars
+below),
+and if
+.Nm
+is operating in ``character at a time'' mode, then when this
+character is typed, a
+.Dv TELNET EL
+sequence (see
+.Ic send
+.Ic el
+above)
+is sent to the remote system.
+The initial value for the
+.Ic kill
+character is taken to be
+the terminal's
+.Ic kill
+character.
+.It Ic lnext
+If
+.Nm
+is operating in
+.Dv LINEMODE
+or ``old line by line'' mode, then this character is taken to
+be the terminal's
+.Ic lnext
+character.
+The initial value for the
+.Ic lnext
+character is taken to be
+the terminal's
+.Ic lnext
+character.
+.It Ic quit
+If
+.Nm
+is in
+.Ic localchars
+mode (see
+.Ic toggle
+.Ic localchars
+below)
+and the
+.Ic quit
+character is typed, a
+.Dv TELNET BRK
+sequence (see
+.Ic send
+.Ic brk
+above)
+is sent to the remote host.
+The initial value for the
+.Ic quit
+character is taken to be
+the terminal's
+.Ic quit
+character.
+.It Ic reprint
+If
+.Nm
+is operating in
+.Dv LINEMODE
+or old line by line'' mode, then this character is taken to
+be the terminal's
+.Ic reprint
+character.
+The initial value for the
+.Ic reprint
+character is taken to be
+the terminal's
+.Ic reprint
+character.
+.It Ic rlogin
+This is the rlogin escape character.
+If set, the normal
+.Tn TELNET
+escape character is ignored unless it is
+preceded by this character at the beginning of a line.
+This character, at the beginning of a line, followed by
+a "." closes the connection; when followed by a ^Z it
+suspends the
+.Nm
+command.
+The initial state is to
+disable the
+.Ic rlogin
+escape character.
+.It Ic start
+If the
+.Dv TELNET TOGGLE-FLOW-CONTROL
+option has been enabled,
+then this character is taken to
+be the terminal's
+.Ic start
+character.
+The initial value for the
+.Ic start
+character is taken to be
+the terminal's
+.Ic start
+character.
+.It Ic stop
+If the
+.Dv TELNET TOGGLE-FLOW-CONTROL
+option has been enabled,
+then this character is taken to
+be the terminal's
+.Ic stop
+character.
+The initial value for the
+.Ic stop
+character is taken to be
+the terminal's
+.Ic stop
+character.
+.It Ic susp
+If
+.Nm
+is in
+.Ic localchars
+mode, or
+.Dv LINEMODE
+is enabled, and the
+.Ic suspend
+character is typed, a
+.Dv TELNET SUSP
+sequence (see
+.Ic send
+.Ic susp
+above)
+is sent to the remote host.
+The initial value for the
+.Ic suspend
+character is taken to be
+the terminal's
+.Ic suspend
+character.
+.It Ic tracefile
+This is the file to which the output, caused by
+.Ic netdata
+or
+.Ic option
+tracing being
+.Dv TRUE ,
+will be written.
+If it is set to
+.Dq Fl ,
+then tracing information will be written to standard output (the default).
+.It Ic worderase
+If
+.Nm
+is operating in
+.Dv LINEMODE
+or ``old line by line'' mode, then this character is taken to
+be the terminal's
+.Ic worderase
+character.
+The initial value for the
+.Ic worderase
+character is taken to be
+the terminal's
+.Ic worderase
+character.
+.It Ic \&?
+Displays the legal
+.Ic set
+.Pq Ic unset
+commands.
+.El
+.It Ic skey Ar sequence challenge
+The
+.Ic skey
+command computes a response to the S/Key challenge.
+See
+.Xr skey 1
+for more information on the S/Key system.
+.It Ic slc Ar state
+The
+.Ic slc
+command (Set Local Characters) is used to set
+or change the state of the special
+characters when the
+.Dv TELNET LINEMODE
+option has
+been enabled.
+Special characters are characters that get mapped to
+.Tn TELNET
+commands sequences (like
+.Ic ip
+or
+.Ic quit )
+or line editing characters (like
+.Ic erase
+and
+.Ic kill ) .
+By default, the local special characters are exported.
+.Bl -tag -width Fl
+.It Ic check
+Verify the current settings for the current special characters.
+The remote side is requested to send all the current special
+character settings, and if there are any discrepancies with
+the local side, the local side will switch to the remote value.
+.It Ic export
+Switch to the local defaults for the special characters.
+The local default characters are those of the local terminal at
+the time when
+.Nm
+was started.
+.It Ic import
+Switch to the remote defaults for the special characters.
+The remote default characters are those of the remote system
+at the time when the
+.Tn TELNET
+connection was established.
+.It Ic \&?
+Prints out help information for the
+.Ic slc
+command.
+.El
+.It Ic status
+Show the current status of
+.Nm telnet .
+This includes the peer one is connected to, as well
+as the current mode.
+.It Ic toggle Ar arguments Op Ar ...
+Toggle (between
+.Dv TRUE
+and
+.Dv FALSE )
+various flags that control how
+.Nm
+responds to events.
+These flags may be set explicitly to
+.Dv TRUE
+or
+.Dv FALSE
+using the
+.Ic set
+and
+.Ic unset
+commands listed above.
+More than one argument may be specified.
+The state of these flags may be interrogated with the
+.Ic display
+command.
+Valid arguments are:
+.Bl -tag -width Ar
+.It Ic authdebug
+Turns on debugging information for the authentication code.
+.It Ic autoflush
+If
+.Ic autoflush
+and
+.Ic localchars
+are both
+.Dv TRUE ,
+then when the
+.Ic ao
+or
+.Ic quit
+characters are recognized (and transformed into
+.Tn TELNET
+sequences; see
+.Ic set
+above for details),
+.Nm
+refuses to display any data on the user's terminal
+until the remote system acknowledges (via a
+.Dv TELNET TIMING MARK
+option)
+that it has processed those
+.Tn TELNET
+sequences.
+The initial value for this toggle is
+.Dv TRUE
+if the terminal user had not
+done an "stty noflsh", otherwise
+.Dv FALSE
+(see
+.Xr stty 1 ) .
+.It Ic autodecrypt
+When the
+.Dv TELNET ENCRYPT
+option is negotiated, by
+default the actual encryption (decryption) of the data
+stream does not start automatically.
+The
+.Ic autoencrypt
+.Pq Ic autodecrypt
+command states that encryption of the
+output (input) stream should be enabled as soon as
+possible.
+.Pp
+.It Ic autologin
+If the remote side supports the
+.Dv TELNET AUTHENTICATION
+option
+.Tn TELNET
+attempts to use it to perform automatic authentication.
+If the
+.Dv AUTHENTICATION
+option is not supported, the user's login
+name are propagated through the
+.Dv TELNET ENVIRON
+option.
+This command is the same as specifying
+.Ar a
+option on the
+.Ic open
+command.
+.It Ic autosynch
+If
+.Ic autosynch
+and
+.Ic localchars
+are both
+.Dv TRUE ,
+then when either the
+.Ic intr
+or
+.Ic quit
+character is typed (see
+.Ic set
+above for descriptions of the
+.Ic intr
+and
+.Ic quit
+characters), the resulting
+.Tn TELNET
+sequence sent is followed by the
+.Dv TELNET SYNCH
+sequence.
+This procedure
+.Em should
+cause the remote system to begin throwing away all previously
+typed input until both of the
+.Tn TELNET
+sequences have been read and acted upon.
+The initial value of this toggle is
+.Dv FALSE .
+.It Ic binary
+Enable or disable the
+.Dv TELNET BINARY
+option on both input and output.
+.It Ic inbinary
+Enable or disable the
+.Dv TELNET BINARY
+option on input.
+.It Ic outbinary
+Enable or disable the
+.Dv TELNET BINARY
+option on output.
+.It Ic crlf
+If this is
+.Dv TRUE ,
+then carriage returns will be sent as
+.Li <CR><LF> .
+If this is
+.Dv FALSE ,
+then carriage returns will be send as
+.Li <CR><NUL> .
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic crmod
+Toggle carriage return mode.
+When this mode is enabled, most carriage return characters received from
+the remote host will be mapped into a carriage return followed by
+a line feed.
+This mode does not affect those characters typed by the user, only
+those received from the remote host.
+This mode is not very useful unless the remote host
+only sends carriage return, but never line feeds.
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic debug
+Toggles socket level debugging (useful only to the superuser).
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic encdebug
+Turns on debugging information for the encryption code.
+.It Ic localchars
+If this is
+.Dv TRUE ,
+then the
+.Ic flush ,
+.Ic interrupt ,
+.Ic quit ,
+.Ic erase ,
+and
+.Ic kill
+characters (see
+.Ic set
+above) are recognized locally, and transformed into (hopefully) appropriate
+.Tn TELNET
+control sequences
+(respectively
+.Ic ao ,
+.Ic ip ,
+.Ic brk ,
+.Ic ec ,
+and
+.Ic el ;
+see
+.Ic send
+above).
+The initial value for this toggle is
+.Dv TRUE
+in ``old line by line'' mode,
+and
+.Dv FALSE
+in ``character at a time'' mode.
+When the
+.Dv LINEMODE
+option is enabled, the value of
+.Ic localchars
+is ignored, and assumed to always be
+.Dv TRUE .
+If
+.Dv LINEMODE
+has ever been enabled, then
+.Ic quit
+is sent as
+.Ic abort ,
+and
+.Ic eof
+and
+.Ic suspend
+are sent as
+.Ic eof
+and
+.Ic susp
+(see
+.Ic send
+above).
+.It Ic netdata
+Toggles the display of all network data (in hexadecimal format).
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic options
+Toggles the display of some internal
+.Nm
+protocol processing (having to do with
+.Tn TELNET
+options).
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic prettydump
+When the
+.Ic netdata
+toggle is enabled, if
+.Ic prettydump
+is enabled the output from the
+.Ic netdata
+command will be formatted in a more user readable format.
+Spaces are put between each character in the output, and the
+beginning of any
+.Tn TELNET
+escape sequence is preceded by a '*' to aid in locating them.
+.It Ic skiprc
+When the skiprc toggle is
+.Dv TRUE ,
+.Tn TELNET
+skips the reading of the
+.Pa \&.telnetrc
+file in the user's home
+directory when connections are opened.
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic termdata
+Toggles the display of all terminal data (in hexadecimal format).
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic verbose_encrypt
+When the
+.Ic verbose_encrypt
+toggle is
+.Dv TRUE ,
+.Nm
+prints out a message each time encryption is enabled or
+disabled.
+The initial value for this toggle is
+.Dv FALSE .
+.It Ic \&?
+Displays the legal
+.Ic toggle
+commands.
+.El
+.It Ic z
+Suspend
+.Nm telnet .
+This command only works when the user is using the
+.Xr csh 1 .
+.It Ic \&! Op Ar command
+Execute a single command in a subshell on the local
+system.
+If
+.Ar command
+is omitted, then an interactive
+subshell is invoked.
+.It Ic \&? Op Ar command
+Get help.
+With no arguments,
+.Nm
+prints a help summary.
+If a command is specified,
+.Nm
+will print the help information for just that command.
+.El
+.Sh ENVIRONMENT
+.Nm
+uses at least the
+.Ev HOME ,
+.Ev SHELL ,
+.Ev DISPLAY ,
+and
+.Ev TERM
+environment variables.
+Other environment variables may be propagated
+to the other side via the
+.Dv TELNET ENVIRON
+option.
+.Sh FILES
+.Bl -tag -width ~/.telnetrc -compact
+.It Pa ~/.telnetrc
+user customized telnet startup values
+.El
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Bx 4.2 .
+.Sh NOTES
+On some remote systems, echo has to be turned off manually when in
+``old line by line'' mode.
+.Pp
+In ``old line by line'' mode or
+.Dv LINEMODE
+the terminal's
+.Ic eof
+character is only recognized (and sent to the remote system)
+when it is the first character on a line.
+.Pp
+Source routing is not supported yet for IPv6.
diff --git a/upstream/mageia-cauldron/man1/test.1 b/upstream/mageia-cauldron/man1/test.1
new file mode 100644
index 00000000..47efded5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/test.1
@@ -0,0 +1,179 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TEST "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+test \- check file types and compare values
+.SH SYNOPSIS
+.B test
+.I EXPRESSION
+.br
+.B test
+.br
+.\" \& tells doclifter the brackets are literal (Bug#31803).
+.B [\&
+.I EXPRESSION
+.B ]\&
+.br
+.B "[\& ]\&"
+.br
+.B [\&
+.I OPTION
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Exit with the status determined by EXPRESSION.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+An omitted EXPRESSION defaults to false.  Otherwise,
+EXPRESSION is true or false and sets exit status.  It is one of:
+.TP
+( EXPRESSION )
+EXPRESSION is true
+.TP
+! EXPRESSION
+EXPRESSION is false
+.TP
+EXPRESSION1 \fB\-a\fR EXPRESSION2
+both EXPRESSION1 and EXPRESSION2 are true
+.TP
+EXPRESSION1 \fB\-o\fR EXPRESSION2
+either EXPRESSION1 or EXPRESSION2 is true
+.TP
+\fB\-n\fR STRING
+the length of STRING is nonzero
+.TP
+STRING
+equivalent to \fB\-n\fR STRING
+.TP
+\fB\-z\fR STRING
+the length of STRING is zero
+.TP
+STRING1 = STRING2
+the strings are equal
+.TP
+STRING1 != STRING2
+the strings are not equal
+.TP
+INTEGER1 \fB\-eq\fR INTEGER2
+INTEGER1 is equal to INTEGER2
+.TP
+INTEGER1 \fB\-ge\fR INTEGER2
+INTEGER1 is greater than or equal to INTEGER2
+.TP
+INTEGER1 \fB\-gt\fR INTEGER2
+INTEGER1 is greater than INTEGER2
+.TP
+INTEGER1 \fB\-le\fR INTEGER2
+INTEGER1 is less than or equal to INTEGER2
+.TP
+INTEGER1 \fB\-lt\fR INTEGER2
+INTEGER1 is less than INTEGER2
+.TP
+INTEGER1 \fB\-ne\fR INTEGER2
+INTEGER1 is not equal to INTEGER2
+.TP
+FILE1 \fB\-ef\fR FILE2
+FILE1 and FILE2 have the same device and inode numbers
+.TP
+FILE1 \fB\-nt\fR FILE2
+FILE1 is newer (modification date) than FILE2
+.TP
+FILE1 \fB\-ot\fR FILE2
+FILE1 is older than FILE2
+.TP
+\fB\-b\fR FILE
+FILE exists and is block special
+.TP
+\fB\-c\fR FILE
+FILE exists and is character special
+.TP
+\fB\-d\fR FILE
+FILE exists and is a directory
+.TP
+\fB\-e\fR FILE
+FILE exists
+.TP
+\fB\-f\fR FILE
+FILE exists and is a regular file
+.TP
+\fB\-g\fR FILE
+FILE exists and is set\-group\-ID
+.TP
+\fB\-G\fR FILE
+FILE exists and is owned by the effective group ID
+.TP
+\fB\-h\fR FILE
+FILE exists and is a symbolic link (same as \fB\-L\fR)
+.TP
+\fB\-k\fR FILE
+FILE exists and has its sticky bit set
+.TP
+\fB\-L\fR FILE
+FILE exists and is a symbolic link (same as \fB\-h\fR)
+.TP
+\fB\-N\fR FILE
+FILE exists and has been modified since it was last read
+.TP
+\fB\-O\fR FILE
+FILE exists and is owned by the effective user ID
+.TP
+\fB\-p\fR FILE
+FILE exists and is a named pipe
+.TP
+\fB\-r\fR FILE
+FILE exists and the user has read access
+.TP
+\fB\-s\fR FILE
+FILE exists and has a size greater than zero
+.TP
+\fB\-S\fR FILE
+FILE exists and is a socket
+.TP
+\fB\-t\fR FD
+file descriptor FD is opened on a terminal
+.TP
+\fB\-u\fR FILE
+FILE exists and its set\-user\-ID bit is set
+.TP
+\fB\-w\fR FILE
+FILE exists and the user has write access
+.TP
+\fB\-x\fR FILE
+FILE exists and the user has execute (or search) access
+.PP
+Except for \fB\-h\fR and \fB\-L\fR, all FILE\-related tests dereference symbolic links.
+Beware that parentheses need to be escaped (e.g., by backslashes) for shells.
+INTEGER may also be \fB\-l\fR STRING, which evaluates to the length of STRING.
+.PP
+NOTE: Binary \fB\-a\fR and \fB\-o\fR are inherently ambiguous.  Use 'test EXPR1 && test
+EXPR2' or 'test EXPR1 || test EXPR2' instead.
+.PP
+NOTE: [ honors the \fB\-\-help\fR and \fB\-\-version\fR options, but test does not.
+test treats each of those as it treats any other nonempty STRING.
+.PP
+NOTE: your shell may have its own version of test and/or [, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Kevin Braunsdorf and Matthew Bradburn.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBaccess\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/test>
+.br
+or available locally via: info \(aq(coreutils) test invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/testparm.1 b/upstream/mageia-cauldron/man1/testparm.1
new file mode 100644
index 00000000..68dbbf71
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/testparm.1
@@ -0,0 +1,194 @@
+'\" t
+.\"     Title: testparm
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/25/2024
+.\"    Manual: User Commands
+.\"    Source: Samba 4.19.5
+.\"  Language: English
+.\"
+.TH "TESTPARM" "1" "02/25/2024" "Samba 4\&.19\&.5" "User Commands"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+testparm \- check an smb\&.conf configuration file for internal correctness
+.SH "SYNOPSIS"
+.HP \w'\ 'u
+testparm [\-s|\-\-suppress\-prompt] [\-v|\-\-verbose] [\-?|\-\-help] [\-\-usage] [\-d|\-\-debuglevel=DEBUGLEVEL] [\-\-debug\-stdout] {config\ filename} [hostname\ hostIP]
+.SH "DESCRIPTION"
+.PP
+This tool is part of the
+\fBsamba\fR(7)
+suite\&.
+.PP
+testparm
+is a very simple test program to check an
+\fBsmbd\fR(8)
+configuration file for internal correctness\&. If this program reports no problems, you can use the configuration file with confidence that
+smbd
+will successfully load the configuration file\&.
+.PP
+Note that this is
+\fINOT\fR
+a guarantee that the services specified in the configuration file will be available or will operate as expected\&.
+.PP
+If the optional host name and host IP address are specified on the command line, this test program will run through the service entries reporting whether the specified host has access to each service\&.
+.PP
+If
+testparm
+finds an error in the
+smb\&.conf
+file it returns an exit code of 1 to the calling program, else it returns an exit code of 0\&. This allows shell scripts to test the output from
+testparm\&.
+.SH "OPTIONS"
+.PP
+\-s|\-\-suppress\-prompt
+.RS 4
+Without this option,
+testparm
+will prompt for a carriage return after printing the service names and before dumping the service definitions\&.
+.RE
+.PP
+\-v|\-\-verbose
+.RS 4
+If this option is specified, testparm will also output all options that were not used in
+\fBsmb.conf\fR(5)
+and are thus set to their defaults\&.
+.RE
+.PP
+\-\-parameter\-name parametername
+.RS 4
+Dumps the named parameter\&. If no section\-name is set the view is limited by default to the global section\&. It is also possible to dump a parametrical option\&. Therefore the option has to be separated by a colon from the parametername\&.
+.RE
+.PP
+\-\-section\-name sectionname
+.RS 4
+Dumps the named section\&.
+.RE
+.PP
+\-\-show\-all\-parameters
+.RS 4
+Show the parameters, type, possible values\&.
+.RE
+.PP
+\-l|\-\-skip\-logic\-checks
+.RS 4
+Skip the global checks\&.
+.RE
+.PP
+\-?|\-\-help
+.RS 4
+Print a summary of command line options\&.
+.RE
+.PP
+\-\-usage
+.RS 4
+Display brief usage message\&.
+.RE
+.PP
+\-d|\-\-debuglevel=DEBUGLEVEL
+.RS 4
+\fIlevel\fR
+is an integer from 0 to 10\&. The default value if this parameter is not specified is 1 for client applications\&.
+.sp
+The higher this value, the more detail will be logged to the log files about the activities of the server\&. At level 0, only critical errors and serious warnings will be logged\&. Level 1 is a reasonable level for day\-to\-day running \- it generates a small amount of information about operations carried out\&.
+.sp
+Levels above 1 will generate considerable amounts of log data, and should only be used when investigating a problem\&. Levels above 3 are designed for use only by developers and generate HUGE amounts of log data, most of which is extremely cryptic\&.
+.sp
+Note that specifying this parameter here will override the
+\m[blue]\fBlog level\fR\m[]
+parameter in the
+/etc/samba/smb\&.conf
+file\&.
+.RE
+.PP
+\-\-debug\-stdout
+.RS 4
+This will redirect debug output to STDOUT\&. By default all clients are logging to STDERR\&.
+.RE
+.PP
+\-\-configfile=<configuration file>
+.RS 4
+The file specified contains the configuration details required by the client\&. The information in this file can be general for client and server or only provide client specific like options such as
+\m[blue]\fBclient smb encrypt\fR\m[]\&. See
+/etc/samba/smb\&.conf
+for more information\&. The default configuration file name is determined at compile time\&.
+.RE
+.PP
+\-\-option=<name>=<value>
+.RS 4
+Set the
+\fBsmb.conf\fR(5)
+option "<name>" to value "<value>" from the command line\&. This overrides compiled\-in defaults and options read from the configuration file\&. If a name or a value includes a space, wrap whole \-\-option=name=value into quotes\&.
+.RE
+.PP
+\-V|\-\-version
+.RS 4
+Prints the program version number\&.
+.RE
+.PP
+configfilename
+.RS 4
+This is the name of the configuration file to check\&. If this parameter is not present then the default
+\fBsmb.conf\fR(5)
+file will be checked\&.
+.RE
+.PP
+hostname
+.RS 4
+If this parameter and the following are specified, then
+testparm
+will examine the
+\fIhosts allow\fR
+and
+\fIhosts deny\fR
+parameters in the
+\fBsmb.conf\fR(5)
+file to determine if the hostname with this IP address would be allowed access to the
+smbd
+server\&. If this parameter is supplied, the hostIP parameter must also be supplied\&.
+.RE
+.PP
+hostIP
+.RS 4
+This is the IP address of the host specified in the previous parameter\&. This address must be supplied if the hostname parameter is supplied\&.
+.RE
+.SH "FILES"
+.PP
+\fBsmb.conf\fR(5)
+.RS 4
+This is usually the name of the configuration file used by
+\fBsmbd\fR(8)\&.
+.RE
+.SH "DIAGNOSTICS"
+.PP
+The program will issue a message saying whether the configuration file loaded OK or not\&. This message may be preceded by errors and warnings if the file did not load\&. If the file was loaded OK, the program then dumps all known service details to stdout\&.
+.PP
+For certain use cases, SMB protocol requires use of cryptographic algorithms which are known to be weak and already broken\&. DES and ARCFOUR (RC4) ciphers and the SHA1 and MD5 hash algorithms are considered weak but they are required for backward compatibility\&. The testparm utility shows whether the Samba tools will fall back to these weak crypto algorithms if it is not possible to use strong cryptography by default\&. In FIPS mode weak crypto cannot be enabled\&.
+.SH "VERSION"
+.PP
+This man page is part of version 4\&.19\&.5 of the Samba suite\&.
+.SH "SEE ALSO"
+.PP
+\fBsmb.conf\fR(5),
+\fBsmbd\fR(8)
+.SH "AUTHOR"
+.PP
+The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
diff --git a/upstream/mageia-cauldron/man1/texi2dvi.1 b/upstream/mageia-cauldron/man1/texi2dvi.1
new file mode 100644
index 00000000..cb5ee6f7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/texi2dvi.1
@@ -0,0 +1,170 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH TEXI2DVI "1" "October 2023" "texi2dvi (GNU Texinfo 7.1)" "User Commands"
+.SH NAME
+texi2dvi \- convert Texinfo documents to DVI or PDF
+.SH SYNOPSIS
+.B texi2dvi
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.br
+.B texi2pdf
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.br
+.B pdftexi2dvi
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+Run each Texinfo or (La)TeX FILE through TeX in turn until all
+cross\-references are resolved, building all indices.  The directory
+containing each FILE is searched for included files.  The suffix of FILE
+is used to determine its language ((La)TeX or Texinfo).  To process
+(e)plain TeX files, set the environment variable LATEX=tex.
+.PP
+When invoked as `texi2pdf' or given the option \fB\-\-pdf\fR generate PDF output.
+Otherwise, generate DVI.
+.SS "General options:"
+.TP
+\fB\-D\fR, \fB\-\-debug\fR
+turn on shell debugging (set \fB\-x\fR)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit successfully
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,OFILE\/\fR
+leave output in OFILE; only one input FILE is allowed
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+no output unless errors
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+display version information and exit successfully
+.TP
+\fB\-V\fR, \fB\-\-verbose\fR
+report on what is done
+.TP
+\fB\-\-max\-iterations\fR=\fI\,N\/\fR
+don't process files more than N times [7]
+.TP
+\fB\-\-mostly\-clean\fR
+remove auxiliary files or directories from
+previous runs (but not the output)
+.SS "Output format:"
+.TP
+\fB\-\-dvi\fR
+output a DVI file [default]
+.TP
+\fB\-\-dvipdf\fR
+output a PDF file via DVI (using a dvi\-to\-pdf program)
+.TP
+\fB\-\-html\fR
+output an HTML file from LaTeX, using HeVeA
+.TP
+\fB\-\-info\fR
+output an Info file from LaTeX, using HeVeA
+.TP
+\fB\-p\fR, \fB\-\-pdf\fR
+use pdftex or pdflatex for processing
+.TP
+\fB\-\-ps\fR
+output a PostScript file via DVI (using dvips)
+.TP
+\fB\-\-text\fR
+output a plain text file from LaTeX, using HeVeA
+.SS "TeX tuning:"
+.TP
+\fB\-E\fR, \fB\-\-expand\fR
+macro expansion using makeinfo
+.TP
+\fB\-I\fR DIR
+search DIR for Texinfo files
+.TP
+\fB\-l\fR, \fB\-\-language\fR=\fI\,LANG\/\fR
+specify LANG for FILE, either latex or texinfo
+.TP
+\fB\-\-no\-line\-error\fR
+do not pass \fB\-\-file\-line\-error\fR to TeX
+.TP
+\fB\-\-shell\-escape\fR
+pass \fB\-\-shell\-escape\fR to TeX
+.TP
+\fB\-\-src\-specials\fR
+pass \fB\-\-src\-specials\fR to TeX
+.TP
+\fB\-\-translate\-file\fR=\fI\,FILE\/\fR
+use given charset translation file for TeX
+.TP
+\fB\-t\fR, \fB\-\-command\fR=\fI\,CMD\/\fR
+insert CMD in copy of input file
+.SS "Build modes:"
+.TP
+\fB\-\-build\fR=\fI\,MODE\/\fR
+specify the treatment of auxiliary files [local]
+.TP
+\fB\-\-tidy\fR
+same as \fB\-\-build\fR=\fI\,tidy\/\fR
+.TP
+\fB\-c\fR, \fB\-\-clean\fR
+same as \fB\-\-build\fR=\fI\,clean\/\fR
+.TP
+\fB\-\-build\-dir\fR=\fI\,DIR\/\fR
+specify where the tidy compilation is performed;
+implies \fB\-\-tidy\fR
+.PP
+The MODE specifies where the TeX compilation takes place, and, as a
+consequence, how auxiliary files are treated.
+.SS "Valid values of MODE are:"
+.TP
+`local'
+compile in the current directory, leaving all the auxiliary
+files around.  This is the traditional TeX use.
+.TP
+`tidy'
+compile in a local *.t2d directory, where the auxiliary files
+are left.  Output files are copied back to the original file.
+.TP
+`clean'
+same as `tidy', but remove the auxiliary directory afterwards.
+Every compilation therefore requires the full cycle.
+.PP
+The build mode can also be set using the environment variable
+TEXI2DVI_BUILD_MODE.  The tidy build directory can also be set using
+the environment variable TEXI2DVI_BUILD_DIRECTORY.
+.PP
+The values of these environment variables are used to run the
+corresponding commands, if they are set:
+.IP
+BIBER BIBTEX DVIPDF DVIPS EGREP HEVEA LATEX MAKEINDEX MAKEINFO
+PDFLATEX PDFTEX SED T4HT TEX TEX4HT TEXINDEX TEXINDY THUMBPDF_CMD
+.PP
+Regarding \fB\-\-dvipdf\fR, if DVIPDF is not set in the environment, the
+following programs are looked for (in this order): dvipdfmx dvipdfm
+dvipdf dvi2pdf dvitopdf.
+.PP
+If Texinfo is installed on your site, then the command
+.IP
+info texi2dvi
+.PP
+should give you access to more documentation.
+.SH "REPORTING BUGS"
+Report bugs to bug\-texinfo@gnu.org,
+general questions and discussion to help\-texinfo@gnu.org.
+.br
+GNU Texinfo home page: <http://www.gnu.org/software/texinfo/>
+.br
+General help using GNU software: <http://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B texi2dvi
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B texi2dvi
+programs are properly installed at your site, the command
+.IP
+.B info texi2dvi
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/texindex.1 b/upstream/mageia-cauldron/man1/texindex.1
new file mode 100644
index 00000000..40a83cd0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/texindex.1
@@ -0,0 +1,43 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH TEXINDEX "1" "October 2023" "GNU texinfo 7.1" "User Commands"
+.SH NAME
+texindex \- sort Texinfo index files
+.SH SYNOPSIS
+.B texindex
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+Generate a sorted index for each TeX output FILE.
+Usually FILE... is specified as `foo.??' for a document `foo.texi'.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+display version information and exit
+.TP
+\fB\-\-\fR
+end option processing
+.SH "REPORTING BUGS"
+Email bug reports to bug\-texinfo@gnu.org,
+general questions and discussion to help\-texinfo@gnu.org.
+.br
+Texinfo home page: https://www.gnu.org/software/texinfo/
+.SH COPYRIGHT
+Copyright \(co 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B texindex
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B texindex
+programs are properly installed at your site, the command
+.IP
+.B info texindex
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/tfmtodit.1 b/upstream/mageia-cauldron/man1/tfmtodit.1
new file mode 100644
index 00000000..6d3841fe
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tfmtodit.1
@@ -0,0 +1,251 @@
+.TH TFMTODIT 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+tfmtodit \- create font files for use with groff \-Tdvi
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el .ds tx TeX
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY tfmtodit
+.OP \-s
+.OP \-g gf_file
+.OP \-k skewchar
+.I tfm_file
+.I map_file
+.I font
+.YS
+.
+.SY tfmtodit
+.B \-\-help
+.YS
+.
+.SY tfmtodit
+.B \-v
+.SY tfmtodit
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+.B tfmtodit
+creates a font file for use with
+.B
+groff \-Tdvi\fR.
+.
+.I tfm_file
+is the name of the \*(tx font metric file for the font.
+.
+.I map_file
+is a file giving the groff names for characters in the font;
+this file should consist of a sequence of lines of the form:
+.IP
+.I
+n c1 c2 \fR.\|.\|.
+.
+.
+.LP
+where
+.I n
+is a decimal integer giving the position of the character in the font,
+and
+.IR c1 ,
+.IR c2 ,.\|.\|.
+are the groff names of the character.
+.
+If a character has no groff names but exists in the tfm file,
+then it will be put in the groff font file as an unnamed character.
+.
+.I font
+is the name of the groff font file.
+.
+The groff font file is written to
+.IR font .
+.
+.
+.LP
+The
+.B \-s
+option should be given if the font is special
+(a font is
+.I special
+if
+.B troff
+should search it whenever
+a character is not found in the current font.)
+.
+If the font is special,
+it should be listed in the
+.B fonts
+command in the DESC file;
+if it is not special, there is no need to list it, since
+.B troff
+can automatically mount it when it's first used.
+.
+.
+.LP
+To do a good job of math typesetting, groff requires font metric
+information not present in the tfm file.
+.
+The reason for this is that \*(tx has separate math italic fonts
+whereas groff uses normal italic fonts for math.
+.
+The additional information required by groff is given by the two
+arguments to the
+.B math_fit
+macro in the Metafont programs for the Computer Modern fonts.
+.
+In a text font (a font for which
+.B math_fitting
+is false), Metafont normally ignores these two arguments.
+.
+Metafont can be made to put this information in the gf file by loading
+the following definition after
+.B cmbase
+when creating
+.IR cm.base :
+.IP
+.nf
+.ft B
+def ignore_math_fit(expr left_adjustment,right_adjustment) =
+    special "adjustment";
+    numspecial left_adjustment*16/designsize;
+    numspecial right_adjustment*16/designsize;
+    enddef;
+.fi
+.ft R
+.LP
+For the EC font family, load the following definition after
+.B exbase
+(it is probably easiest to patch
+.I exbase.mf
+locally):
+.IP
+.nf
+.ft B
+def ignore_math_fit(expr left_adjustment,right_adjustment) =
+    ori_special "adjustment";
+    ori_numspecial left_adjustment*16/designsize;
+    ori_numspecial right_adjustment*16/designsize;
+    enddef;
+.fi
+.ft R
+.LP
+The gf file created using this modified
+.I cm.base
+or
+.I exbase
+should be specified with the
+.B \-g
+option.
+.
+The
+.B \-g
+option should not be given for a font for which
+.B math_fitting
+is true.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.B \-s
+The font is special.
+.
+The effect of this option is to add the
+.B special
+command to the font file.
+.
+.TP
+.BI \-k n
+The skewchar of this font is at position
+.IR n .
+.
+.I n
+should be an integer;
+it may be given in decimal,
+or with a leading
+.B 0
+in octal,
+or with a leading
+.B 0x
+in hexadecimal.
+.
+The effect of this option is to ignore any kerns whose second
+component is the specified character.
+.
+.TP
+.BI \-g gf_file
+.I gf_file
+is a gf file produced by Metafont containing special and numspecial
+commands giving additional font metric information.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:font/devdvi/DESC
+Device description file.
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/devdvi/ F
+Font description file for font
+.IR F .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.BR groff (1),
+.BR grodvi (1),
+.BR groff_font (5)
+.
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/tgatoppm.1 b/upstream/mageia-cauldron/man1/tgatoppm.1
new file mode 100644
index 00000000..37d45a03
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tgatoppm.1
@@ -0,0 +1,88 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Tgatoppm User Manual" 0 "02 April 2000" "netpbm documentation"
+
+.SH NAME
+
+tgatoppm - convert TrueVision Targa file to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBtgatoppm\fP
+	[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+	[\fB--headerdump\fP] \fItga-filename\fP
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBtgatoppm\fP reads a TrueVision Targa file as input and produces
+a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBtgatoppm\fP recognizes the following
+command line options:
+.PP
+All options can be abbreviated to their shortest unique prefix.
+
+
+
+.TP
+\fB--alphaout=\fP\fIalpha-filename\fP
+\fBtgatoppm \fP creates a PGM image containing the transparency channel
+values in the input image.  If the input image doesn't contain a
+transparency channel, the \fIalpha-filename\fP file contains all zero
+(transparent) transparency values.  If you don't specify \fB--alphaout\fP,
+\fBtgatoppm\fP does not generate an alpha file, and if the input
+image has a transparency channel, \fBtgatoppm\fP simply discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBtgatoppm\fP writes the
+transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+
+.TP
+\fB--headerdump\fP
+Causes \fBtgatoppm\fP to dump information from the TGA header to
+Standard Error.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtotga" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Partially based on tga2rast, version 1.0, by Ian J. MacPhedran.
+.PP
+Copyright (C) 1989 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/tgatoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/thinkjettopbm.1 b/upstream/mageia-cauldron/man1/thinkjettopbm.1
new file mode 100644
index 00000000..bb237975
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/thinkjettopbm.1
@@ -0,0 +1,86 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Thinkjettopbm User Manual" 0 "03 April 2001" "netpbm documentation"
+
+.SH NAME
+
+thinkjettopbm - convert HP ThinkJet printer commands file to PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBthinkjettopbm\fP
+
+[\fB-d\fP]
+
+[\fIthinkjet_file\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBthinkjettopbm\fP reads HP ThinkJet printer commands from the
+standard input, or \fIthinkjet_file\fP if specified, and writes a PBM
+image to Standard Output.  
+.PP
+\fBthinkjettopbm\fP silently ignores
+text and non-graphics command sequences.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBthinkjettopbm\fP recognizes the following
+command line option:
+
+
+
+.TP
+\fB-d\fP
+Turns on debugging messages which are written to the standard error stream.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+The program handles only a small subset of ThinkJet command
+sequences, but enough to convert screen images from older HP test
+equipment.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtopclxl" (1)\c
+\&,
+.BR "pbmtolj" (1)\c
+\&,
+.BR "ppmtolj" (1)\c
+\&,
+.BR "ppmtopj" (1)\c
+\&,
+.BR "pjtoppm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2001 by W. Eric Norum
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/thinkjettopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/tic.1m b/upstream/mageia-cauldron/man1/tic.1m
new file mode 100644
index 00000000..c8d1dddf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tic.1m
@@ -0,0 +1,622 @@
+.\"***************************************************************************
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: tic.1m,v 1.106 2023/12/30 21:36:32 tom Exp $
+.TH tic 1M 2023-12-30 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.
+.ds d /usr/share/terminfo
+.SH NAME
+\fB\%tic\fP \-
+compile terminal descriptions for \fIterminfo\fR or \fItermcap\fR
+.SH SYNOPSIS
+\fBtic\fP
+[\fB\-\
+0\
+1\
+a\
+c\
+C\
+D\
+f\
+g\
+G\
+I\
+K\
+L\
+N\
+q\
+r\
+s\
+t\
+T\
+U\
+V\
+W\
+x\
+\fP]
+[\fB\-e\fP \fIterminal-type-list\fP]
+[\fB\-o\fP \fIdir\fP]
+[\fB\-Q\fP[\fIn\fP]]
+[\fB\-R\fP \fIsubset\fP]
+[\fB\-v\fP[\fIn\fP]]
+[\fB\-w\fP[\fIn\fP]]
+\fIfile\fP
+.SH DESCRIPTION
+The \fBtic\fP command translates a \fBterminfo\fP file from source
+format into compiled format.
+The compiled format is necessary for use with
+the library routines in \fB\%ncurses\fP(3X).
+.PP
+As described in \fBterm\fP(5), the database may be either a directory
+tree (one file per terminal entry) or a hashed database (one record per entry).
+The \fBtic\fP command writes only one type of entry,
+depending on how it was built:
+.bP
+For directory trees, the top-level directory, e.g., /usr/share/terminfo,
+specifies the location of the database.
+.bP
+For hashed databases, a filename is needed.
+If the given file is not found by that name,
+but can be found by adding the suffix ".db",
+then that is used.
+.IP
+The default name for the hashed database is the same as the
+default directory name (only adding a ".db" suffix).
+.PP
+In either case (directory or hashed database),
+\fBtic\fP will create the container if it does not exist.
+For a directory, this would be the \*(``terminfo\*('' leaf,
+versus a "terminfo.db" file.
+.PP
+The results are normally placed in the system terminfo database \fB\*d\fP.
+The compiled terminal description can be placed
+in a different terminfo database.
+There are two ways to achieve this:
+.bP
+First, you may override the system default either by
+using the \fB\-o\fP option,
+or by setting the variable \fI\%TERMINFO\fP
+in your shell environment to a valid database location.
+.bP
+Secondly, if \fBtic\fP cannot write in \fI\*d\fP
+or the location specified using your \fI\%TERMINFO\fP variable,
+it looks for the directory \fI$HOME/.terminfo\fP
+(or hashed database \fI$HOME/.terminfo.db)\fP;
+if that location exists, the entry is placed there.
+.PP
+Libraries that read terminfo entries are expected to check in succession
+.bP
+a location specified with the \fI\%TERMINFO\fP environment variable,
+.bP
+\fI$HOME/.terminfo\fP,
+.bP
+directories listed in the \fI\%TERMINFO_DIRS\fP environment variable,
+.bP
+a compiled-in list of directories (/usr/share/terminfo), and
+.bP
+the system terminfo database (\fI\*d\fP).
+.PP
+The \fIFetching Compiled Descriptions\fP section in the \fBterminfo\fR(5)
+manual goes into further detail.
+.SS Aliases
+This is the same program as infotocap and captoinfo;
+usually those are linked to, or copied from this program:
+.bP
+When invoked as infotocap, tic sets the \fB\-I\fP option.
+.bP
+When invoked as captoinfo, tic sets the \fB\-C\fP option.
+.SH OPTIONS
+.TP
+\fB\-0\fP
+restricts the output to a single line
+.TP
+\fB\-1\fP
+restricts the output to a single column
+.TP
+\fB\-a\fP
+tells \fBtic\fP to retain commented-out capabilities rather than discarding
+them.
+Capabilities are commented by prefixing them with a period.
+This sets the \fB\-x\fP option, because it treats the commented-out
+entries as user-defined names.
+If the source is termcap, accept the 2-character names required by version 6.
+Otherwise these are ignored.
+.TP
+\fB\-C\fP
+Force source translation to termcap format.
+Note: this differs from the \fB\-C\fP
+option of \fBinfocmp\fP(1M) in that it does not merely translate capability
+names, but also translates terminfo strings to termcap format.
+Capabilities
+that are not translatable are left in the entry under their terminfo names
+but commented out with two preceding dots.
+The actual format used incorporates some improvements for escaped characters
+from terminfo format.
+For a stricter BSD-compatible translation, add the \fB\-K\fP option.
+.IP
+If this is combined with \fB\-c\fP, \fBtic\fP makes additional checks
+to report cases where the terminfo values do not have an exact equivalent
+in termcap form.
+For example:
+.RS
+.bP
+\fBsgr\fP usually will not convert, because termcap lacks the ability to
+work with more than two parameters, and because termcap lacks many of
+the arithmetic/logical operators used in terminfo.
+.bP
+capabilities with more than one delay or with delays before the end of
+the string will not convert completely.
+.RE
+.TP
+\fB\-c\fP
+tells \fBtic\fP to only check \fIfile\fP for errors,
+including syntax problems and bad use-links.
+If you specify \fB\-C\fP (\fB\-I\fP) with this option, the code
+will print warnings about entries which, after use resolution, are more than
+1023 (4096) bytes long.
+Due to a fixed buffer length in older termcap libraries,
+as well as buggy checking for the buffer length
+(and a documented limit in terminfo),
+these entries may cause core
+dumps with other implementations.
+.IP
+\fBtic\fP checks string capabilities to ensure that those with parameters
+will be valid expressions.
+It does this check only for the predefined string capabilities;
+those which are defined with the \fB\-x\fP option are ignored.
+.TP
+\fB\-D\fP
+tells \fBtic\fP to print the database locations that it knows about, and exit.
+The first location shown is the one to which it would write compiled
+terminal descriptions.
+If \fBtic\fP is not able to find a writable database location
+according to the rules summarized above,
+it will print a diagnostic and exit with an error rather than
+printing a list of database locations.
+.TP
+\fB\-e \fIlist\fR
+Limit writes and translations to the comma-separated \fIlist\fP of
+terminal types.
+If any name or alias of a terminal matches one of the names in
+the list, the entry will be written or translated as normal.
+Otherwise no output will be generated for it.
+The option value is interpreted as a file containing the list if it
+contains a '/'.
+(Note: depending on how tic was compiled,
+this option may require \fB\-I\fP or \fB\-C\fP.)
+.TP
+\fB\-f\fP
+Display complex terminfo strings which contain if/then/else/endif expressions
+indented for readability.
+.TP
+\fB\-G\fP
+Display constant literals in decimal form
+rather than their character equivalents.
+.TP
+\fB\-g\fP
+Display constant character literals in quoted form
+rather than their decimal equivalents.
+.TP
+\fB\-I\fP
+Force source translation to terminfo format.
+.TP
+\fB\-K\fP
+Suppress some longstanding \fI\%ncurses\fP extensions to termcap format,
+e.g., "\es" for space.
+.TP
+\fB\-L\fP
+Force source translation to terminfo format
+using the long C variable names listed in <\fBterm.h\fP>
+.TP
+\fB\-N\fP
+Disable smart defaults.
+Normally, when translating from termcap to terminfo, the compiler makes
+a number of assumptions about the defaults of string capabilities
+\fBreset1_string\fP, \fBcarriage_return\fP, \fBcursor_left\fP,
+\fBcursor_down\fP, \fBscroll_forward\fP, \fBtab\fP, \fBnewline\fP,
+\fBkey_backspace\fP, \fBkey_left\fP, and \fBkey_down\fP, then attempts
+to use obsolete termcap capabilities to deduce correct values.
+It also
+normally suppresses output of obsolete termcap capabilities such as \fBbs\fP.
+This option forces a more literal translation that also preserves the
+obsolete capabilities.
+.TP
+\fB\-o\fIdir\fR
+Write compiled entries to given database location.
+Overrides the \fI\%TERMINFO\fP environment variable.
+.TP
+\fB\-Q\fIn\fR
+Rather than show source in terminfo (text) format,
+print the compiled (binary) format in hexadecimal or base64 form,
+depending on the option's value:
+.RS 8
+.TP 3
+1
+hexadecimal
+.TP 3
+2
+base64
+.TP 3
+3
+hexadecimal and base64
+.RE
+.TP
+\fB\-q\fP
+Suppress comments and blank lines when showing translated source.
+.TP
+\fB\-R\fIsubset\fR
+Restrict output to a given subset.
+This option is for use with archaic
+versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
+the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
+that have their own extensions incompatible with SVr4/XSI.
+.IP
+Available subsets are
+.RS
+\*(``SVr1\*('',
+\*(``Ultrix\*('',
+\*(``HP\*('',
+\*(``BSD\*('', and
+\*(``AIX\*(''
+.RE
+.IP
+See \fBterminfo\fP(5) for details.
+.TP
+\fB\-r\fP
+Force entry resolution (so there are no remaining tc capabilities) even
+when doing translation to termcap format.
+This may be needed if you are
+preparing a termcap file for a termcap library (such as GNU termcap through
+version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
+tc capabilities per entry.
+.TP
+\fB\-s\fP
+Summarize the compile by showing the database location into which entries
+are written, and the number of entries which are compiled.
+.TP
+\fB\-T\fP
+eliminates size-restrictions on the generated text.
+This is mainly useful for testing and analysis, since the compiled
+descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
+.TP
+\fB\-t\fP
+tells \fBtic\fP to discard commented-out capabilities.
+Normally when translating from terminfo to termcap,
+untranslatable capabilities are commented-out.
+.TP 5
+\fB\-U\fP
+tells \fBtic\fP to not post-process the data after parsing the source file.
+Normally, it infers data which is commonly missing in older terminfo data,
+or in termcaps.
+.TP
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
+.TP
+\fB\-v\fIn\fR
+specifies that (verbose) output be written to standard error trace
+information showing \fBtic\fP's progress.
+.IP
+The optional parameter \fIn\fP is a number from 1 to 9, inclusive,
+indicating the desired level of detail of information.
+.RS
+.bP
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
+.bP
+If \fIn\fP is omitted, the default level is 1.
+.bP
+If \fIn\fP is specified and greater than 1, the level of
+detail is increased, and the output is written (with tracing information)
+to the \*(``trace\*('' file.
+.RE
+.RS
+.PP
+The debug flag levels are as follows:
+.TP 4
+1
+Names of files created and linked
+.TP
+2
+Information related to the \*(``use\*('' facility
+.TP
+3
+Statistics from the hashing algorithm
+.TP
+4
+Details of extended capabilities
+.TP
+5
+(unused)
+.TP
+6
+(unused)
+.TP
+7
+Entries into the string-table
+.TP
+8
+List of tokens encountered by scanner
+.TP
+9
+All values computed in construction of the hash table
+.RE
+.TP
+\fB\-W\fP
+By itself, the \fB\-w\fP option will not force long strings to be wrapped.
+Use the \fB\-W\fP option to do this.
+.IP
+If you specify both \fB\-f\fP and \fB\-W\fP options,
+the latter is ignored when \fB\-f\fP has already split the line.
+.TP
+\fB\-w\fIn\fR
+specifies the width of the output.
+The parameter is optional.
+If it is omitted, it defaults to 60.
+.TP
+\fB\-x\fP
+Treat unknown capabilities as user-defined (see \fBuser_caps\fP(5)).
+That is, if you supply a capability name which \fBtic\fP does not recognize,
+it will infer its type (Boolean, number or string) from the syntax and
+make an extended table entry for that.
+User-defined capability strings
+whose name begins with \*(``k\*('' are treated as function keys.
+.SS Parameters
+.TP
+\fIfile\fP
+contains one or more \fBterminfo\fP terminal descriptions in source
+format [see \fBterminfo\fP(5)].
+Each description in the file
+describes the capabilities of a particular terminal.
+.IP
+If \fIfile\fP is \*(``-\*('', then the data is read from the standard input.
+The \fIfile\fP parameter may also be the path of a character-device.
+.SS Processing
+All but one of the capabilities recognized by \fBtic\fP are documented
+in \fBterminfo\fP(5).
+The exception is the \fBuse\fP capability.
+.PP
+When a \fBuse\fP=\fIentry\fP\-\fIname\fP field is discovered in a
+terminal entry currently being compiled, \fBtic\fP reads in the binary
+from \fB\*d\fP to complete the entry.
+(Entries created from
+\fIfile\fP will be used first.
+\fBtic\fP duplicates the capabilities in
+\fIentry\fP\-\fIname\fP for the current entry, with the exception of
+those capabilities that explicitly are defined in the current entry.
+.PP
+When an entry, e.g., \fBentry_name_1\fP, contains a
+\fBuse=\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
+capabilities in \fIentry\fR_\fIname\fR_\fI2\fP must also appear in
+\fBentry_name_1\fP before \fBuse=\fP for these capabilities to be
+canceled in \fBentry_name_1\fP.
+.PP
+Total compiled entries cannot exceed
+4096 bytes in the legacy storage format, or
+32768 using the extended number format.
+The name field cannot
+exceed 512 bytes.
+Terminal names exceeding the maximum alias length
+(32 characters on systems with long filenames, 14 characters otherwise)
+will be truncated to the maximum alias length
+and a warning message will be printed.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH NOTES
+There is some evidence that historic \fBtic\fP implementations treated
+description fields with no whitespace in them as additional aliases or
+short names.
+This \fBtic\fP does not do that, but it does warn when
+description fields may be treated that way and check them for dangerous
+characters.
+.SH EXTENSIONS
+Unlike the SVr4 \fBtic\fP command, this implementation can actually
+compile termcap sources.
+In fact, entries in terminfo and termcap syntax can
+be mixed in a single source file.
+See \fBterminfo\fP(5) for the list of
+termcap names taken to be equivalent to terminfo names.
+.PP
+The SVr4 manual pages are not clear on the resolution rules for \fBuse\fP
+capabilities.
+This implementation of \fBtic\fP will find \fBuse\fP targets anywhere
+in the source file,
+or anywhere in the file tree rooted at
+\fI\%TERMINFO\fP
+(if
+\fI\%TERMINFO\fP is defined),
+or in the user's \fI$HOME/.terminfo\fP database
+(if it exists),
+or (finally) anywhere in the system's file tree of
+compiled entries.
+.PP
+The error messages from this \fBtic\fP have the same format as GNU C
+error messages, and can be parsed by GNU Emacs's compile facility.
+.PP
+Aside from \fB\-c\fP and \fB\-v\fP, options are not portable:
+.bP
+Most of tic's options
+are not supported by SVr4 \fBtic\fP:
+.sp
+.RS
+\fB\-0\fP
+\fB\-1\fP
+\fB\-C\fP
+\fB\-G\fP
+\fB\-I\fP
+\fB\-N\fP
+\fB\-R\fP
+\fB\-T\fP
+\fB\-V\fP
+\fB\-a\fP
+\fB\-e\fP
+\fB\-f\fP
+\fB\-g\fP
+\fB\-o\fP
+\fB\-r\fP
+\fB\-s\fP
+\fB\-t\fP
+\fB\-x\fP
+.RE
+.bP
+The NetBSD \fBtic\fP supports a few of the \fI\%ncurses\fP options
+.sp
+.RS
+\fB\-a\fP
+\fB\-o\fP
+\fB\-x\fP
+.RE
+.IP
+and adds \fB\-S\fP
+(a feature which does the same thing
+as infocmp's \fB\-e\fP and \fB\-E\fP options).
+.PP
+The SVr4 \fB\-c\fP mode does not report bad \*(``use=\*('' links.
+.PP
+System V does not compile entries to or read entries from your
+\fI$HOME/.terminfo\fP database unless \fI\%TERMINFO\fP is explicitly set
+to it.
+.SH PORTABILITY
+X/Open Curses, Issue 7 (2009) provides a brief description of \fBtic\fP.
+It lists one option: \fB\-c\fP.
+The omission of \fB\-v\fP is unexpected.
+The change history states that the description is derived from Tru64.
+According to its manual pages, that system also supported the \fB\-v\fP option.
+.PP
+Shortly after Issue 7 was released, Tru64 was discontinued.
+As of 2019, the surviving implementations of \fBtic\fP
+are SVr4 (AIX, HP-UX and Solaris),
+\fI\%ncurses\fP
+and NetBSD curses.
+The SVr4 \fBtic\fP programs all support the \fB\-v\fP option.
+The NetBSD \fBtic\fP program follows X/Open's documentation,
+omitting the \fB\-v\fP option.
+.PP
+The X/Open rationale states that some implementations of \fBtic\fP
+read terminal descriptions from the standard input if the \fIfile\fP
+parameter is omitted.
+None of these implementations do that.
+Further, it comments that some may choose to read from \*(''./terminfo.src\*(''
+but that is obsolescent behavior from SVr2,
+and is not (for example) a documented feature of SVr3.
+.SH HISTORY
+System V Release 2 provided a \fBtic\fP utility.
+It accepted a single option: \fB\-v\fP (optionally followed by a number).
+According to Ross Ridge's comment in \fImytinfo\fP,
+this version of \fBtic\fP was
+unable to represent cancelled capabilities.
+.PP
+System V Release 3 provided a different \fBtic\fP utility,
+written by Pavel Curtis,
+(originally named \*(``compile\*('' in \fIpcurses\fP).
+This added an option \fB\-c\fP to check the file for
+errors, with the caveat that errors in \*(``use=\*('' links
+would not be reported.
+System V Release 3 documented a few warning messages which
+did not appear in \fIpcurses\fP.
+While the program itself was changed little as development
+continued with System V Release 4,
+the table of capabilities grew from 180 (\fIpcurses\fP) to 464 (Solaris).
+.PP
+In early development of \fI\%ncurses\fP (1993),
+Zeyd Ben-Halim used the table from \fImytinfo\fP to
+extend the \fIpcurses\fP table to 469 capabilities
+(456 matched SVr4, 8 were only in SVr4, 13 were not in SVr4).
+Of those 13, 11 were ultimately discarded
+(perhaps to match the draft of X/Open Curses).
+The exceptions were
+\fB\%memory_lock_above\fP and
+\fB\%memory_unlock\fP (see \fB\%user_caps\fP(5)).
+.PP
+Eric Raymond incorporated parts of \fImytinfo\fP into \fI\%ncurses\fP
+to implement the termcap-to-terminfo source conversion,
+and extended that to begin development of
+the corresponding terminfo-to-termcap source conversion,
+Thomas Dickey completed that development over the course of several years.
+.PP
+In 1999, Thomas Dickey added the \fB\-x\fP option
+to support user-defined capabilities.
+.PP
+In 2010, Roy Marples provided a \fBtic\fP program
+and terminfo library for NetBSD.
+That implementation adapts several features from \fI\%ncurses\fP,
+including \fBtic\fP's \fB\-x\fP option.
+.PP
+The \fB\-c\fP option tells \fBtic\fP to check for problems in the
+terminfo source file.
+Continued development provides additional checks:
+.bP
+\fIpcurses\fP had 8 warnings
+.bP
+\fI\%ncurses\fP in 1996 had 16 warnings
+.bP
+Solaris (SVr4) curses has 28 warnings
+.bP
+NetBSD tic in 2019 has 19 warnings.
+.bP
+\fI\%ncurses\fP in 2019 has 96 warnings
+.PP
+The checking done in \fI\%ncurses\fP' \fBtic\fP helps with the
+conversion to termcap,
+as well as pointing out errors and inconsistencies.
+It is also used to ensure consistency with the user-defined capabilities.
+There are 527 distinct capabilities in \fI\%ncurses\fP' terminal
+database;
+128 of those are user-defined.
+.SH AUTHORS
+Eric S. Raymond <esr@snark.thyrsus.com>
+and
+.br
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%captoinfo\fP(1M),
+\fB\%infocmp\fP(1M),
+\fB\%infotocap\fP(1M),
+\fB\%toe\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%term\fP(5),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
diff --git a/upstream/mageia-cauldron/man1/tifftopnm.1 b/upstream/mageia-cauldron/man1/tifftopnm.1
new file mode 100644
index 00000000..064840b6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tifftopnm.1
@@ -0,0 +1,354 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Tifftopnm User Manual" 0 "02 January 2015" "netpbm documentation"
+
+.SH NAME
+
+tifftopnm - convert a TIFF file into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBtifftopnm\fP
+
+[\fB-alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fB-headerdump\fP]
+[\fB-verbose\fP]
+[\fB-respectfillorder\fP]
+[\fB-byrow\fP]
+[\fB-orientraw\fP]
+[\fItiff-filename\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBtifftopnm\fP reads a TIFF file as input and produces a PNM image as
+output.  The type of the output file depends on the input file - if it's black
+and white, \fBtifftopnm\fP generates a PBM image; if it's grayscale, it
+generates a PGM image; otherwise, the output is PPM.  The program tells you
+which type it is writing.
+.PP
+If the TIFF file contains multiple images (multiple
+"directories"), \fBtifftopnm\fP generates a multi-image PNM
+output stream.  Before Netpbm 10.27 (March 2005), however, it would
+just ignore all but the first input image.
+.PP
+The \fItiff-filename\fP argument names the file that contains the Tiff
+image.  If you specify "-" or don't specify this
+argument, \fBtifftopnm\fP uses Standard Input.
+.PP
+In either case, before Netpbm 10.70 (March 2015), the file must be
+seekable.  That means no pipe, but any regular file is fine.  In current
+Netpbm, the file need not be seekable, but if it isn't, \fBtifftopnm\fP
+creates a temporary regular file containing the entire image, so you must have
+resources for that (and it may defeat your reason for using a pipe).
+
+.UN library
+.SS TIFF Capability
+.PP
+\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever
+equivalent you provide) to interpret the TIFF input.  So the set of files
+it is able to interpret is determined mostly by that library.
+.PP
+This program cannot read every possible TIFF file -- there are
+myriad variations of the TIFF format.  However, it does understand
+monochrome and gray scale, RGB, RGBA (red/green/blue with transparency
+channel), CMYK (Cyan-Magenta-Yellow-Black ink color separation), and
+color palette TIFF files.  An RGB file can have either single plane
+(interleaved) color or multiple plane format.  The program reads 1-8
+and 16 bit-per-sample input, the latter in either bigendian or
+littlendian encoding.  Tiff directory information may also be either
+bigendian or littlendian.
+.PP
+There are many TIFF formats that \fBtifftopnm\fP can read only if
+the image is small enough to fit in memory.  \fBtifftopnm\fP uses the
+TIFF library's TIFFRGBAImageGet() function to process the TIFF image
+if it can get enough memory for TIFFRGBAImageGet() to store the whole
+image in memory at once (that's what TIFFRGBAImageGet() does).  If
+not, \fBtifftopnm\fP uses a more primitive row-by-row conversion
+strategy using the raw data returned by TIFFReadScanLine() and native
+intelligence.  That native intelligence does not know as many formats
+as TIFFRGBAImageGet() does.  And certain compressed formats simply
+cannot be read with TIFFReadScanLine().
+.PP
+Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP never used
+TIFFRGBAImageGet(), so it could not interpret many of the formats it
+can interpret today.
+.PP
+There is no fundamental reason that this program could not read
+other kinds of TIFF files even when they don't fit in memory all at
+once.  The existing limitations are mainly because no one has asked
+for more.
+
+.UN output
+.SS Output Image
+.PP
+The PNM output has the same maxval as the Tiff input, except that
+if the Tiff input is colormapped (which implies a maxval of 65535) the
+PNM output has a maxval of 255.  Though this may result in lost
+information, such input images hardly ever actually have more color
+resolution than a maxval of 255 provides and people often cannot deal
+with PNM files that have maxval > 255.  By contrast, a
+non-colormapped Tiff image that doesn't need a maxval > 255 doesn't
+\fIhave\fP a maxval > 255, so when \fBtifftopnm\fP sees a
+non-colormapped maxval > 255, it takes it seriously and produces a
+matching output maxval.
+.PP
+Another exception is where the TIFF maxval is greater than 65535,
+which is the maximum allowed by the Netpbm formats.  In that case,
+\fBtifftopnm\fP uses a maxval of 65535, and you lose some information
+in the conversion.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBtifftopnm\fP recognizes the following
+command line options:
+.PP
+You may abbreviate any option to its shortest unique prefix.  You may use
+two hyphens instead of one in options.  You may separate an option and
+its value either by an equals sign or white space.
+
+
+.TP
+\fB-alphaout=\fP\fIalpha-filename\fP
+\fBtifftopnm \fPcreates a PGM file containing the alpha channel
+values in the input image.  If the input image doesn't contain a
+transparency channel, the \fIalpha-filename\fP file contains all zero
+(transparent) transparency values.  If you don't specify \fB-alphaout\fP,
+
+\fBtifftopnm\fP does not generate a transparency file, and if the input
+image has an transparency channel, \fBtifftopnm\fP simply discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBtifftopnm\fP
+writes the transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+
+.TP
+\fB-respectfillorder\fP
+By default, \fBtifftopnm \fP ignores the "fillorder"
+tag in the TIFF input, which means it may incorrectly interpret the
+image.  To make it follow the spec, use this option.  For a lengthy
+but engaging discussion of why \fBtifftopnm\fP works this way and how
+to use the \fB-respectfillorder\fP option, see the note on fillorder
+below.  
+
+.TP
+\fB-byrow\fP
+This option can make \fBtifftopnm\fP run faster.
+.sp
+\fBtifftopnm\fP has two ways to do the conversion from Tiff to PNM, using
+respectively two facilities of the TIFF library:
+
+
+
+.TP
+Whole Image
+Decode the entire image into memory at once, using
+\fBTIFFRGBAImageGet()\fP, then convert to PNM and output row by row.
+   
+.TP
+Row By Row
+Read, convert, and output one row at a time
+using \fBTIFFReadScanline()\fP
+
+
+.sp
+Whole Image is preferable because the Tiff library does more of the
+work, which means it understands more of the Tiff format possibilities
+now and in the future.  Also, some compressed TIFF formats don't allow
+you to extract an individual row.
+.sp
+Row By Row uses far less memory, which means with large images, it
+can run in environments where Whole Image cannot and may also run
+faster.  And because Netpbm code does more of the work, it's possible
+that it can be more flexible or at least give better diagnostic
+information if there's something wrong with the TIFF.
+.sp
+The Netpbm native code may do something correctly that the TIFF
+library does incorrectly, or vice versa.
+.sp
+In Netpbm, we stress function over performance, so by default we
+try Whole Image first, and if we can't get enough memory for the
+decoded image or \fBTIFFRGBAImageGet()\fP fails, we fall back to Row By Row.
+But if you specify the \fB-byrow\fP option, \fBtifftopnm\fP will not
+attempt Whole Image.  If Row By Row does not work, it simply fails.
+.sp
+See 
+.UR #cmyk
+Color Separation (CMYK) TIFFs
+.UE
+\& for a
+description of one way Row By Row makes a significant difference in
+your results.
+.sp
+Whole Image costs you precision when your TIFF image uses more than
+8 bits per sample.  \fBTIFFRGBAImageGet()\fP converts the samples to 8 bits.
+\fBtifftopnm\fP then scales them back to maxval 65535, but the lower
+8 bits of information is gone.
+.sp
+In many versions of the TIFF library, \fBTIFFRGBAImageGet()\fP does not
+correctly interpret TIFF files in which the raster orientation is
+column-major (i.e. a row of the raster is a column of the image).
+With such a TIFF library and file, you must use \fB-byrow\fP to get
+correct output.
+.sp
+Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP always did Row
+By Row.  Netpbm 10.12 always tried Whole Image first.  \fB-byrow\fP
+came in with Netpbm 10.13 (January 2003).
+
+.TP
+\fB-orientraw\fP
+A TIFF stream contains raster data which can be arranged in the
+stream various ways.  Most commonly, it is arranged by rows, with the
+top row first, and the pixels left to right within each row, but many
+other orientations are possible.
+.sp
+The common orientation is the same one the Netpbm formats use, so
+\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
+is oriented that way.
+.sp
+But if the TIFF raster is oriented any other way, it can take a
+considerable amount of processing for \fBtifftopnm\fP to convert it to
+Netpbm format.
+.sp
+\fB-orientraw\fP says to produce an output image that represents the raw
+raster in the TIFF stream rather than the image the TIFF stream is supposed to
+represent.  In the output, the top left corner corresponds to the start of the
+TIFF raster, the next pixel to the right is the next pixel in the TIFF raster,
+etc.  \fBtifftopnm\fP can do this easily, but you don't get the right image
+out.  You can use \fBpamflip\fP to turn the output into the image the TIFF
+stream represents (but if you do that, you pretty much lose the benefit of
+\fB-orientraw\fP).
+.sp
+With this option, \fBtifftopnm\fP always uses the Row By Row method
+(see \fB-byrow\fP).
+.sp
+This option was new in Netpbm 10.42 (March 2008).  Before that,
+\fBtifftopnm\fP generally produces arbitrary results with TIFF images
+that have an orientation other than the common one.
+
+.TP
+\fB-verbose\fP
+Print extra messages to Standard Error about the conversion.
+
+.TP
+\fB-headerdump\fP
+Dump TIFF file information to stderr.  This information may be useful 
+in debugging TIFF file conversion problems.  
+
+
+
+.UN notes
+.SH NOTES
+
+.UN fillorder
+.SS Fillorder
+.PP
+There is a piece of information in the header of a TIFF image called
+"fillorder." The TIFF specification quite clearly states
+that this value tells the order in which bits are arranged in a byte
+in the description of the image's pixels.  There are two options,
+assuming that the image has a format where more than one pixel can be
+represented by a single byte: 1) the byte is filled from most
+significant bit to least significant bit going left to right in the
+image; and 2) the opposite.
+.PP
+However, there is confusion in the world as to the meaning of
+fillorder.  Evidence shows that some people believe it has to do with
+byte order when a single value is represented by two bytes.
+.PP
+These people cause TIFF images to be created that, while they use a 
+MSB-to-LSB fillorder, have a fillorder tag that says they used LSB-to-MSB.
+A program that properly interprets a TIFF image will not end up with the
+image that the author intended in this case.
+.PP
+For a long time, \fBtifftopnm\fP did not understand fillorder itself
+and assumed the fillorder was MSB-to-LSB regardless of the fillorder
+tag in the TIFF header.  And as far as I know, there is no legitimate
+reason to use a fillorder other than MSB-to-LSB.  So users of
+\fBtifftopnm\fP were happily using those TIFF images that had
+incorrect fillorder tags.
+.PP
+So that those users can continue to be happy, \fBtifftopnm\fP today
+continues to ignore the fillorder tag unless you tell it not to.  (It
+does, however, warn you when the fillorder tag does not say MSB-to-LSB
+that the tag is being ignored).
+.PP
+If for some reason you have a TIFF image that actually has LSB-to-MSB
+fillorder, and its fillorder tag correctly indicates that, you must
+use the \fB-respectfillorder\fP option on \fBtifftopnm\fP to get
+proper results.
+.PP
+Examples of incorrect TIFF images are at 
+.UR ftp://weather.noaa.gov.
+ftp://weather.noaa.gov.
+.UE
+\& They are
+apparently created by a program called \fBfaxtotiff\fP.
+.PP
+This note was written on January 1, 2002.
+
+
+.UN cmyk
+.SS Color Separation (CMYK) TIFFs
+.PP
+Some TIFF images contain color information in CMYK form, whereas PNM
+images use RGB.  There are various formulas for converting between these
+two forms, and \fBtifftopnm\fP can use either of two.
+.PP
+The TIFF library (Version 3.5.4 from libtiff.org) uses
+Y=(1-K)*(1-B) (similar for R and G) in its TIFFRGBAImageGet() service.
+When \fBtifftopnm\fP works in Whole Image mode, it uses that service,
+so that's the conversion you get.
+.PP
+But when \fBtifftopnm\fP runs in Row By Row mode, it does not use
+TIFFRGBAImageGet(), and you get what appears to be more useful:
+Y=1-(B+K).  This is the inverse of what \fBpnmtotiffcmyk\fP does.
+.PP
+See the \fB-byrow\fP option for more information on Whole Image versus
+Row By Row mode.
+.PP
+Before Netpbm 10.21 (March 2004), \fBtifftopnm\fP used the
+Y=(1-K)*(1-B) formula always.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtotiff" (1)\c
+\&,
+.BR "pnmtotiffcmyk" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c)
+1990 by Sun Microsystems, Inc.  Author: Patrick J. Naughton (\fInaughton@wind.sun.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/tifftopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/time.1 b/upstream/mageia-cauldron/man1/time.1
new file mode 100644
index 00000000..9b0f2c46
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/time.1
@@ -0,0 +1,329 @@
+.\" Copyright Andries Brouwer, 2000
+.\" Some fragments of text came from the time-1.7 info file.
+.\" Inspired by kromJx@crosswinds.net.
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.TH time 1 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+time \- time a simple command or give resource usage
+.SH SYNOPSIS
+.B time
+.RI [ option \~.\|.\|.\&] " command " [ argument \~.\|.\|.]
+.SH DESCRIPTION
+The
+.B time
+command runs the specified program
+.I command
+with the given arguments.
+When
+.I command
+finishes,
+.B time
+writes a message to standard error giving timing statistics
+about this program run.
+These statistics consist of (i) the elapsed real time
+between invocation and termination, (ii) the user CPU time
+(the sum of the
+.I tms_utime
+and
+.I tms_cutime
+values in a
+.I "struct tms"
+as returned by
+.BR times (2)),
+and (iii) the system CPU time (the sum of the
+.I  tms_stime
+and
+.I tms_cstime
+values in a
+.I "struct tms"
+as returned by
+.BR times (2)).
+.P
+Note: some shells (e.g.,
+.BR bash (1))
+have a built-in
+.B time
+command that provides similar information on the usage of time and
+possibly other resources.
+To access the real command, you may need to specify its pathname
+(something like
+.IR /usr/bin/time ).
+.SH OPTIONS
+.TP
+.B \-p
+When in the POSIX locale, use the precise traditional format
+.IP
+.in +4n
+.EX
+"real %f\enuser %f\ensys %f\en"
+.EE
+.in
+.IP
+(with numbers in seconds)
+where the number of decimals in the output for %f is unspecified
+but is sufficient to express the clock tick accuracy, and at least one.
+.SH EXIT STATUS
+If
+.I command
+was invoked, the exit status is that of
+.IR command .
+Otherwise, it is 127 if
+.I command
+could not be found, 126 if it could be found but could not be invoked,
+and some other nonzero value (1\[en]125) if something else went wrong.
+.SH ENVIRONMENT
+The variables
+.BR LANG ,
+.BR LC_ALL ,
+.BR LC_CTYPE ,
+.BR LC_MESSAGES ,
+.BR LC_NUMERIC ,
+and
+.B NLSPATH
+are used for the text and formatting of the output.
+.B PATH
+is used to search for
+.IR command .
+.SH GNU VERSION
+Below a description of the GNU 1.7 version of
+.BR time .
+Disregarding the name of the utility, GNU makes it output lots of
+useful information, not only about time used, but also on other
+resources like memory, I/O and IPC calls (where available).
+The output is formatted using a format string that can be specified
+using the
+.I \-f
+option or the
+.B TIME
+environment variable.
+.P
+The default format string is:
+.P
+.in +4n
+.EX
+%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
+%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
+.EE
+.in
+.P
+When the
+.I \-p
+option is given, the (portable) output format is used:
+.P
+.in +4n
+.EX
+real %e
+user %U
+sys %S
+.EE
+.in
+.\"
+.SS The format string
+The format is interpreted in the usual printf-like way.
+Ordinary characters are directly copied, tab, newline,
+and backslash are escaped using \et, \en, and \e\e,
+a percent sign is represented by %%, and otherwise %
+indicates a conversion.
+The program
+.B time
+will always add a trailing newline itself.
+The conversions follow.
+All of those used by
+.BR tcsh (1)
+are supported.
+.P
+.B "Time"
+.TP
+.B %E
+Elapsed real time (in [hours:]minutes:seconds).
+.TP
+.B %e
+(Not in
+.BR tcsh (1).)
+Elapsed real time (in seconds).
+.TP
+.B %S
+Total number of CPU-seconds that the process spent in kernel mode.
+.TP
+.B %U
+Total number of CPU-seconds that the process spent in user mode.
+.TP
+.B %P
+Percentage of the CPU that this job got, computed as (%U + %S) / %E.
+.P
+.B "Memory"
+.TP
+.B %M
+Maximum resident set size of the process during its lifetime, in Kbytes.
+.TP
+.B %t
+(Not in
+.BR tcsh (1).)
+Average resident set size of the process, in Kbytes.
+.TP
+.B %K
+Average total (data+stack+text) memory use of the process,
+in Kbytes.
+.TP
+.B %D
+Average size of the process's unshared data area, in Kbytes.
+.TP
+.B %p
+(Not in
+.BR tcsh (1).)
+Average size of the process's unshared stack space, in Kbytes.
+.TP
+.B %X
+Average size of the process's shared text space, in Kbytes.
+.TP
+.B %Z
+(Not in
+.BR tcsh (1).)
+System's page size, in bytes.
+This is a per-system constant, but varies between systems.
+.TP
+.B %F
+Number of major page faults that occurred while the process was running.
+These are faults where the page has to be read in from disk.
+.TP
+.B %R
+Number of minor, or recoverable, page faults.
+These are faults for pages that are not valid but which have
+not yet been claimed by other virtual pages.
+Thus the data
+in the page is still valid but the system tables must be updated.
+.TP
+.B %W
+Number of times the process was swapped out of main memory.
+.TP
+.B %c
+Number of times the process was context-switched involuntarily
+(because the time slice expired).
+.TP
+.B %w
+Number of waits: times that the program was context-switched voluntarily,
+for instance while waiting for an I/O operation to complete.
+.P
+.B "I/O"
+.TP
+.B %I
+Number of filesystem inputs by the process.
+.TP
+.B %O
+Number of filesystem outputs by the process.
+.TP
+.B %r
+Number of socket messages received by the process.
+.TP
+.B %s
+Number of socket messages sent by the process.
+.TP
+.B %k
+Number of signals delivered to the process.
+.TP
+.B %C
+(Not in
+.BR tcsh (1).)
+Name and command-line arguments of the command being timed.
+.TP
+.B %x
+(Not in
+.BR tcsh (1).)
+Exit status of the command.
+.SS GNU options
+.TP
+.BI "\-f " format ", \-\-format=" format
+Specify output format, possibly overriding the format specified
+in the environment variable TIME.
+.TP
+.B "\-p, \-\-portability"
+Use the portable output format.
+.TP
+.BI "\-o " file ", \-\-output=" file
+Do not send the results to
+.IR stderr ,
+but overwrite the specified file.
+.TP
+.B "\-a, \-\-append"
+(Used together with \-o.) Do not overwrite but append.
+.TP
+.B "\-v, \-\-verbose"
+Give very verbose output about all the program knows about.
+.TP
+.B "\-q, \-\-quiet"
+Don't report abnormal program termination (where
+.I command
+is terminated by a signal) or nonzero exit status.
+.\"
+.SS GNU standard options
+.TP
+.B "\-\-help"
+Print a usage message on standard output and exit successfully.
+.TP
+.B "\-V, \-\-version"
+Print version information on standard output, then exit successfully.
+.TP
+.B "\-\-"
+Terminate option list.
+.SH BUGS
+Not all resources are measured by all versions of UNIX,
+so some of the values might be reported as zero.
+The present selection was mostly inspired by the data
+provided by 4.2 or 4.3BSD.
+.P
+GNU time version 1.7 is not yet localized.
+Thus, it does not implement the POSIX requirements.
+.P
+The environment variable
+.B TIME
+was badly chosen.
+It is not unusual for systems like
+.BR autoconf (1)
+or
+.BR make (1)
+to use environment variables with the name of a utility to override
+the utility to be used.
+Uses like MORE or TIME for options to programs
+(instead of program pathnames) tend to lead to difficulties.
+.P
+It seems unfortunate that
+.I \-o
+overwrites instead of appends.
+(That is, the
+.I \-a
+option should be the default.)
+.P
+Mail suggestions and bug reports for GNU
+.B time
+to
+.IR bug\-time@gnu.org .
+Please include the version of
+.BR time ,
+which you can get by running
+.P
+.in +4n
+.EX
+time \-\-version
+.EE
+.in
+.P
+and the operating system
+and C compiler you used.
+.\" .SH AUTHORS
+.\" .TP
+.\" .IP "David Keppel"
+.\" Original version
+.\" .IP "David MacKenzie"
+.\" POSIXization, autoconfiscation, GNU getoptization,
+.\" documentation, other bug fixes and improvements.
+.\" .IP "Arne Henrik Juul"
+.\" Helped with portability
+.\" .IP "Francois Pinard"
+.\" Helped with portability
+.SH SEE ALSO
+.BR bash (1),
+.BR tcsh (1),
+.BR times (2),
+.BR wait3 (2)
diff --git a/upstream/mageia-cauldron/man1/timedatectl.1 b/upstream/mageia-cauldron/man1/timedatectl.1
new file mode 100644
index 00000000..1a6738e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/timedatectl.1
@@ -0,0 +1,551 @@
+'\" t
+.TH "TIMEDATECTL" "1" "" "systemd 255" "timedatectl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+timedatectl \- Control the system time and date
+.SH "SYNOPSIS"
+.HP \w'\fBtimedatectl\fR\ 'u
+\fBtimedatectl\fR [OPTIONS...] {COMMAND}
+.SH "DESCRIPTION"
+.PP
+\fBtimedatectl\fR
+may be used to query and change the system clock and its settings, and enable or disable time synchronization services\&.
+.PP
+Use
+\fBsystemd-firstboot\fR(1)
+to initialize the system time zone for mounted (but not booted) system images\&.
+.PP
+\fBtimedatectl\fR
+may be used to show the current status of time synchronization services, for example
+\fBsystemd-timesyncd.service\fR(8)\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBstatus\fR
+.RS 4
+Show current settings of the system clock and RTC, including whether network time synchronization is active\&. If no command is specified, this is the implied default\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBshow\fR
+.RS 4
+Show the same information as
+\fBstatus\fR, but in machine readable form\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBstatus\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBset\-time [TIME]\fR
+.RS 4
+Set the system clock to the specified time\&. This will also update the RTC time accordingly\&. The time may be specified in the format "2012\-10\-30 18:17:16"\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-timezone [TIMEZONE]\fR
+.RS 4
+Set the system time zone to the specified value\&. Available timezones can be listed with
+\fBlist\-timezones\fR\&. If the RTC is configured to be in the local time, this will also update the RTC time\&. This call will alter the
+/etc/localtime
+symlink\&. See
+\fBlocaltime\fR(5)
+for more information\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBlist\-timezones\fR
+.RS 4
+List available time zones, one per line\&. Entries from the list can be set as the system timezone with
+\fBset\-timezone\fR\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-local\-rtc [BOOL]\fR
+.RS 4
+Takes a boolean argument\&. If
+"0", the system is configured to maintain the RTC in universal time\&. If
+"1", it will maintain the RTC in local time instead\&. Note that maintaining the RTC in the local timezone is not fully supported and will create various problems with time zone changes and daylight saving adjustments\&. If at all possible, keep the RTC in UTC mode\&. Note that invoking this will also synchronize the RTC from the system clock, unless
+\fB\-\-adjust\-system\-clock\fR
+is passed (see above)\&. This command will change the 3rd line of
+/etc/adjtime, as documented in
+\fBhwclock\fR(8)\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fBset\-ntp [BOOL]\fR
+.RS 4
+Takes a boolean argument\&. Controls whether network time synchronization is active and enabled (if available)\&. If the argument is true, this enables and starts the first existing network synchronization service\&. If the argument is false, then this disables and stops the known network synchronization services\&. The way that the list of services is built is described in
+\fBsystemd-timedated.service\fR(8)\&.
+.sp
+Added in version 195\&.
+.RE
+.SS "systemd\-timesyncd Commands"
+.PP
+The following commands are specific to
+\fBsystemd-timesyncd.service\fR(8)\&.
+.PP
+\fBtimesync\-status\fR
+.RS 4
+Show current status of
+\fBsystemd-timesyncd.service\fR(8)\&. If
+\fB\-\-monitor\fR
+is specified, then this will monitor the status updates\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBshow\-timesync\fR
+.RS 4
+Show the same information as
+\fBtimesync\-status\fR, but in machine readable form\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
+\fBtimesync\-status\fR
+if you are looking for formatted human\-readable output\&.
+.sp
+By default, empty properties are suppressed\&. Use
+\fB\-\-all\fR
+to show those too\&. To select specific properties to show, use
+\fB\-\-property=\fR\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fBntp\-servers \fR\fB\fIINTERFACE\fR\fR\fB \fR\fB\fISERVER\fR\fR\fB\&...\fR
+.RS 4
+Set the interface specific NTP servers\&. This command can be used only when the interface is managed by
+\fBsystemd\-networkd\fR\&.
+.sp
+Added in version 243\&.
+.RE
+.PP
+\fBrevert \fR\fB\fIINTERFACE\fR\fR
+.RS 4
+Revert the interface specific NTP servers\&. This command can be used only when the interface is managed by
+\fBsystemd\-networkd\fR\&.
+.sp
+Added in version 243\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-no\-ask\-password\fR
+.RS 4
+Do not query the user for authentication for privileged operations\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-adjust\-system\-clock\fR
+.RS 4
+If
+\fBset\-local\-rtc\fR
+is invoked and this option is passed, the system clock is synchronized from the RTC again, taking the new setting into account\&. Otherwise, the RTC is synchronized from the system clock\&.
+.sp
+Added in version 195\&.
+.RE
+.PP
+\fB\-\-monitor\fR
+.RS 4
+If
+\fBtimesync\-status\fR
+is invoked and this option is passed, then
+\fBtimedatectl\fR
+monitors the status of
+\fBsystemd-timesyncd.service\fR(8)
+and updates the outputs\&. Use
+Ctrl+C
+to terminate the monitoring\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-a\fR, \fB\-\-all\fR
+.RS 4
+When showing properties of
+\fBsystemd-timesyncd.service\fR(8), show all properties regardless of whether they are set or not\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-property=\fR
+.RS 4
+When showing properties of
+\fBsystemd-timesyncd.service\fR(8), limit display to certain properties as specified as argument\&. If not specified, all set properties are shown\&. The argument should be a property name, such as
+"ServerName"\&. If specified more than once, all properties with the specified names are shown\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-\-value\fR
+.RS 4
+When printing properties with
+\fBshow\-timesync\fR, only print the value, and skip the property name and
+"="\&.
+.sp
+Added in version 239\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host=\fR
+.RS 4
+Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
+"@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
+":", and then a container name, separated by
+"/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
+\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
+.RE
+.PP
+\fB\-M\fR, \fB\-\-machine=\fR
+.RS 4
+Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
+"@"
+character\&. If the special string
+"\&.host"
+is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
+"\-\-user \-\-machine=lennart@\&.host")\&. If the
+"@"
+syntax is not used, the connection is made as root user\&. If the
+"@"
+syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
+"\&.host"
+are implied\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "EXAMPLES"
+.PP
+Show current settings:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ timedatectl
+               Local time: Thu 2017\-09\-21 16:08:56 CEST
+           Universal time: Thu 2017\-09\-21 14:08:56 UTC
+                 RTC time: Thu 2017\-09\-21 14:08:56
+                Time zone: Europe/Warsaw (CEST, +0200)
+System clock synchronized: yes
+              NTP service: active
+          RTC in local TZ: no
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Enable network time synchronization:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ timedatectl set\-ntp true
+==== AUTHENTICATING FOR org\&.freedesktop\&.timedate1\&.set\-ntp ===
+Authentication is required to control whether network time synchronization shall be enabled\&.
+Authenticating as: user
+Password: ********
+==== AUTHENTICATION COMPLETE ===
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ systemctl status systemd\-timesyncd\&.service
+â—� systemd\-timesyncd\&.service \- Network Time Synchronization
+   Loaded: loaded (/usr/lib/systemd/system/systemd\-timesyncd\&.service; enabled)
+   Active: active (running) since Mo 2015\-03\-30 14:20:38 CEST; 5s ago
+     Docs: man:systemd\-timesyncd\&.service(8)
+ Main PID: 595 (systemd\-timesyn)
+   Status: "Using Time Server 216\&.239\&.38\&.15:123 (time4\&.google\&.com)\&."
+   CGroup: /system\&.slice/systemd\-timesyncd\&.service
+           └─595 /usr/lib/systemd/systemd\-timesyncd
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Show current status of
+\fBsystemd-timesyncd.service\fR(8):
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ timedatectl timesync\-status
+       Server: 216\&.239\&.38\&.15 (time4\&.google\&.com)
+Poll interval: 1min 4s (min: 32s; max 34min 8s)
+         Leap: normal
+      Version: 4
+      Stratum: 1
+    Reference: GPS
+    Precision: 1us (\-20)
+Root distance: 335us (max: 5s)
+       Offset: +316us
+        Delay: 349us
+       Jitter: 0
+ Packet count: 1
+    Frequency: \-8\&.802ppm
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBhwclock\fR(8),
+\fBdate\fR(1),
+\fBlocaltime\fR(5),
+\fBsystemctl\fR(1),
+\fBsystemd-timedated.service\fR(8),
+\fBsystemd-timesyncd.service\fR(8),
+\fBsystemd-firstboot\fR(1)
diff --git a/upstream/mageia-cauldron/man1/timeout.1 b/upstream/mageia-cauldron/man1/timeout.1
new file mode 100644
index 00000000..8edadad5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/timeout.1
@@ -0,0 +1,99 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TIMEOUT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+timeout \- run a command with a time limit
+.SH SYNOPSIS
+.B timeout
+[\fI\,OPTION\/\fR] \fI\,DURATION COMMAND \/\fR[\fI\,ARG\/\fR]...
+.br
+.B timeout
+[\fI\,OPTION\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Start COMMAND, and kill it if still running after DURATION.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.HP
+\fB\-\-preserve\-status\fR
+.IP
+exit with the same status as COMMAND, even when the
+.IP
+command times out
+.HP
+\fB\-\-foreground\fR
+.IP
+when not running timeout directly from a shell prompt,
+.IP
+allow COMMAND to read from the TTY and get TTY signals;
+in this mode, children of COMMAND will not be timed out
+.HP
+\fB\-k\fR, \fB\-\-kill\-after\fR=\fI\,DURATION\/\fR
+.IP
+also send a KILL signal if COMMAND is still running
+.IP
+this long after the initial signal was sent
+.HP
+\fB\-s\fR, \fB\-\-signal\fR=\fI\,SIGNAL\/\fR
+.IP
+specify the signal to be sent on timeout;
+.IP
+SIGNAL may be a name like 'HUP' or a number;
+see 'kill \fB\-l\fR' for a list of signals
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+diagnose to stderr any signal sent upon timeout
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+DURATION is a floating point number with an optional suffix:
+\&'s' for seconds (the default), 'm' for minutes, 'h' for hours or 'd' for days.
+A duration of 0 disables the associated timeout.
+.PP
+Upon timeout, send the TERM signal to COMMAND, if no other SIGNAL specified.
+The TERM signal kills any process that does not block or catch that signal.
+It may be necessary to use the KILL signal, since this signal can't be caught.
+.SS "EXIT status:"
+.TP
+124
+if COMMAND times out, and \fB\-\-preserve\-status\fR is not specified
+.TP
+125
+if the timeout command itself fails
+.TP
+126
+if COMMAND is found but cannot be invoked
+.TP
+127
+if COMMAND cannot be found
+.TP
+137
+if COMMAND (or timeout itself) is sent the KILL (9) signal (128+9)
+.TP
+\-
+the exit status of COMMAND otherwise
+.SH BUGS
+Some platforms don't currently support timeouts beyond the year 2038.
+.SH AUTHOR
+Written by Padraig Brady.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBkill\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/timeout>
+.br
+or available locally via: info \(aq(coreutils) timeout invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/toe.1m b/upstream/mageia-cauldron/man1/toe.1m
new file mode 100644
index 00000000..6fcbf810
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/toe.1m
@@ -0,0 +1,239 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2019-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: toe.1m,v 1.64 2024/01/20 16:51:21 tom Exp $
+.TH toe 1M 2024-01-20 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.ds d /usr/share/terminfo
+.SH NAME
+\fB\%toe\fP \-
+list table of entries of \fIterminfo\fR terminal types
+.SH SYNOPSIS
+.B toe
+.RB [ \-ahs ]
+.RB [ \-v\ \c
+.RI [ n ]]
+.RI [ directory
+\&.\|.\|.]
+.PP
+.B toe
+.RB [ \-u | \-U ]
+.I file
+.PP
+.B "toe \-V"
+.SH DESCRIPTION
+\fB\%toe\fP reports to the standard output stream the (primary) names
+and descriptions of the terminal types available to the \fIterminfo\fP
+library.
+Each \fIdirectory\fP is scanned;
+if none are given,
+\fB\%toe\fP scans the default \fIterminfo\fP directory.
+.SH OPTIONS
+The \fB\-h\fP option can be helpful to observe where \fB\%toe\fP is
+looking for terminal descriptions.
+Other options support maintainers of \fIterminfo\fP terminal
+descriptions.
+.TP 9 \" "-u file" + 2n
+.B \-a
+lists entries from all terminal database directories that \fIterminfo\fP
+would search,
+instead of only the first that it finds.
+.IP
+If the \fB\-s\fP option is also given,
+\fB\%toe\fP adds a column to the report,
+showing (like \fB\%conflict\fP(1)) which entries belong to a given
+terminal database.
+An \*(``*\*('' marks entries that differ,
+and \*(``+\*('' marks equivalent entries.
+.IP
+Without the \fB\-s\fP option,
+\fB\%toe\fP does not attempt to merge duplicates in its report.
+.TP
+.B \-h
+writes a heading naming each each directory as it is accessed.
+.TP
+.B \-s
+sorts the output by the entry names.
+.TP
+.BI \-u\  file
+lists terminal type dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\fBtc\fP (\fItermcap\fP) relations:
+each line comprises the primary name of a terminal type employing
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types thus
+named,
+and a newline.
+.TP
+.BI \-U\  file
+lists terminal type reverse dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\fBtc\fP (\fItermcap\fP) reverse relations:
+each line comprises the primary name of a terminal type occurring in
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types
+naming them thus,
+and a newline.
+.TP
+.BR \-v\  [\c
+.IR n ]
+reports verbose status information to the standard error stream,
+showing \fB\%toe\fP's progress.
+.IP
+The optional parameter \fIn\fP is an integer between 1 and 10 inclusive,
+interpreted as for \fB\%tic\fP(1M).
+If \fI\%ncurses\fP is built without tracing support,
+\fIn\fP is ignored.
+.TP
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH PORTABILITY
+\fB\%toe\fP is not provided by other implementations.
+There is no applicable X/Open or POSIX standard for it.
+.SH HISTORY
+\fB\%toe\fP replaces a \fB\-T\fP option that was briefly supported by
+the \fI\%ncurses\fP \fB\%infocmp\fP utility in 1995.
+.PP
+The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
+respectively.
+.PP
+The program's name originates with a developer's pun:
+.bP
+\fBtic\fP,
+.bP
+\fBtac\fP (now \fBtack\fP),
+.bP
+\fBtoe\fP.
+.SH EXAMPLES
+When not sorting with the \fB\-s\fP option,
+the \fB\-a\fP option reports all of the names found in all of the
+terminal database directories named in the \fI\%TERMINFO\fP and
+\fI\%TERMINFO_DIRS\fP environment variables.
+.RS 4
+.PP
+.\" toe -a | grep -E '^(xterm|vt)'
+.ft \*(CW
+.TS
+L2 Lx.
+xterm\-color	generic color xterm
+xterm\-xfree86	xterm terminal emulator (XFree86)
+xterm\-vt220	xterm emulating vt220
+xterm\-256color	xterm with 256 colors
+xterm\-r6	xterm X11R6 version
+xterm\-r5	xterm R5 version
+xterm\-mono	monochrome xterm
+xterm	T{
+.ad l
+xterm terminal emulator (X Window System)
+T}
+vt220	dec vt220
+vt102	dec vt102
+vt100	dec vt100 (w/advanced video)
+vt52	dec vt52
+.T&
+L.
+\&.\|.\|.
+.TE
+.ft
+.RE
+.PP
+Use the \fB\-a\fP and \fB\-s\fP options together to show where each
+terminal description was found.
+.RS 4
+.PP
+.\" toe -as | grep -E '(^-+>|:.(xterm|vt))'
+.ft \*(CW
+.TS
+Lx.
+\-\-> /etc/terminfo
+\-\-\-\-> /lib/terminfo
+\-\-\-\-\-\-> /usr/share/terminfo
+.TE
+.TS
+L1 L2 Lx.
+\-\-*\-\-\-:	vt100	dec vt100 (w/advanced video)
+\-\-*\-\-\-:	vt102	dec vt102
+\-\-*\-\-\-:	vt220	dec vt220
+\-\-*\-\-\-:	vt52	dec vt52
+\-\-*\-\-\-:	xterm	T{
+.ad l
+xterm terminal emulator (X Window System)
+T}
+\-\-*\-\-\-:	xterm\-256color	xterm with 256 colors
+\-\-*\-\-\-:	xterm\-color	generic color xterm
+\-\-*\-\-\-:	xterm\-mono	monochrome xterm
+\-\-*\-\-\-:	xterm\-r5	xterm R5 version
+\-\-*\-\-\-:	xterm\-r6	xterm X11R6 version
+\-\-*\-\-\-:	xterm\-vt220	xterm emulating vt220
+\-\-*\-\-\-:	xterm\-xfree86	T{
+.ad l
+xterm terminal emulator (XFree86)
+T}
+.T&
+L.
+\&.\|.\|.
+.TE
+.ft
+.RE
+.SH SEE ALSO
+\fB\%captoinfo\fP(1M),
+\fB\%infocmp\fP(1M),
+\fB\%infotocap\fP(1M),
+\fB\%tic\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/touch.1 b/upstream/mageia-cauldron/man1/touch.1
new file mode 100644
index 00000000..8eaf9327
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/touch.1
@@ -0,0 +1,84 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TOUCH "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+touch \- change file timestamps
+.SH SYNOPSIS
+.B touch
+[\fI\,OPTION\/\fR]... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Update the access and modification times of each FILE to the current time.
+.PP
+A FILE argument that does not exist is created empty, unless \fB\-c\fR or \fB\-h\fR
+is supplied.
+.PP
+A FILE argument string of \- is handled specially and causes touch to
+change the times of the file associated with standard output.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR
+change only the access time
+.TP
+\fB\-c\fR, \fB\-\-no\-create\fR
+do not create any files
+.TP
+\fB\-d\fR, \fB\-\-date\fR=\fI\,STRING\/\fR
+parse STRING and use it instead of current time
+.TP
+\fB\-f\fR
+(ignored)
+.TP
+\fB\-h\fR, \fB\-\-no\-dereference\fR
+affect each symbolic link instead of any referenced
+file (useful only on systems that can change the
+timestamps of a symlink)
+.TP
+\fB\-m\fR
+change only the modification time
+.TP
+\fB\-r\fR, \fB\-\-reference\fR=\fI\,FILE\/\fR
+use this file's times instead of current time
+.TP
+\fB\-t\fR STAMP
+use [[CC]YY]MMDDhhmm[.ss] instead of current time
+.TP
+\fB\-\-time\fR=\fI\,WORD\/\fR
+change the specified time:
+WORD is access, atime, or use: equivalent to \fB\-a\fR
+WORD is modify or mtime: equivalent to \fB\-m\fR
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+Note that the \fB\-d\fR and \fB\-t\fR options accept different time\-date formats.
+.SH "DATE STRING"
+.\" NOTE: keep this paragraph in sync with the one in date.x
+The --date=STRING is a mostly free format human readable date string
+such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or
+even "next Thursday".  A date string may contain items indicating
+calendar date, time of day, time zone, day of week, relative time,
+relative date, and numbers.  An empty string indicates the beginning
+of the day.  The date string format is more complex than is easily
+documented here but is fully described in the info documentation.
+.SH AUTHOR
+Written by Paul Rubin, Arnold Robbins, Jim Kingdon,
+David MacKenzie, and Randy Smith.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/touch>
+.br
+or available locally via: info \(aq(coreutils) touch invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tput.1 b/upstream/mageia-cauldron/man1/tput.1
new file mode 100644
index 00000000..d8e7e460
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tput.1
@@ -0,0 +1,999 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: tput.1,v 1.105 2024/01/20 19:41:02 tom Exp $
+.TH tput 1 2024-01-20 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.ds d /usr/share/terminfo
+.SH NAME
+\fB\%tput\fP \-
+initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
+.SH SYNOPSIS
+\fBtput\fP [\fB\-T\fP \fIterminal-type\fP]
+{\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
+.PP
+\fBtput\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
+.PP
+\fBtput\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
+.PP
+\fBtput\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
+.PP
+\fBtput\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
+.PP
+\fBtput \-S\fP
+.PP
+\fBtput \-V\fP
+.SH DESCRIPTION
+\fB\%tput\fP uses the
+.I \%term\%info
+library and database to make terminal-specific capabilities and
+information available to the shell,
+to initialize or reset the terminal,
+or
+to report a description of the current
+(or specified)
+terminal type.
+Terminal capabilities are accessed by
+.IR cap-code .
+.PP
+\fB\%terminfo\fP(5) discusses terminal capabilities at length
+and presents a complete list of
+.I cap-codes.
+.PP
+When retrieving capability values,
+the result depends upon the capability's type.
+.TP 9 \" "Boolean" + 2n
+Boolean
+\fB\%tput\fP sets its exit status to
+.B 0
+if the terminal possesses
+.I cap-code,
+and
+.B 1
+if it does not.
+.TP
+numeric
+\fB\%tput\fP writes
+.IR cap-code 's
+decimal value to the standard output stream if defined
+.RB ( \-1
+if it is not)
+followed by a newline.
+.TP
+string
+\fB\%tput\fP writes
+.IR cap-code 's
+value to the standard output stream if defined,
+without a trailing newline.
+.PP
+Before using a value returned on the standard output,
+the application should test \fB\%tput\fP's exit status
+to be sure it is 0;
+see section \*(``EXIT STATUS\*('' below.
+.SS Operands
+Generally,
+an operand is a
+.I cap-code,
+a capability code from the terminal database,
+or a parameter thereto.
+Three others are specially recognized by \fB\%tput\fP:
+.BR init ,
+.BR \%reset ,
+and
+.BR \%longname .
+Although these resemble capability codes,
+they in fact receive special handling;
+we term them \*(``pseudo-capabilities\*(''.
+.TP 11n \" "longname" + 2n + adjustment for PDF
+.I cap-code
+indicates a capability from the terminal database.
+.IP
+If the capability is of string type and takes parameters,
+the arguments following the capability will be used as its parameters.
+.IP
+Most parameters are numeric.
+Only a few terminal capabilities require string parameters;
+\fB\%tput\fP uses a table to decide which to pass as strings.
+Normally \fB\%tput\fP uses \fB\%tparm\fP(3X) to perform the
+substitution.
+If no parameters are given for the capability,
+\fB\%tput\fP writes the string without performing the substitution.
+.TP
+.B init
+initializes the terminal.
+If the terminal database is present
+and an entry for the user's terminal type exists,
+the following occur.
+.RS
+.TP 5
+(1)
+\fB\%tput\fP retrieves the terminal's mode settings.
+It successively tests the file descriptors corresponding to
+.RS
+.bP
+the standard error stream,
+.bP
+the standard output stream,
+.bP
+the standard input stream,
+and
+.bP
+.I \%/dev/tty
+.RE
+.IP
+to obtain terminal settings.
+Having retrieved them,
+\fB\%tput\fP remembers which descriptor to use for further updates.
+.TP
+(2)
+If the terminal dimensions cannot be obtained from the operating system,
+but the environment or terminal type database entry describes them,
+\fB\%tput\fP updates the operating system's notion of them.
+.TP
+(3)
+\fB\%tput\fP updates the terminal modes.
+.RS
+.bP
+Any delays specified in the entry
+(for example,
+when a newline is sent)
+are set in the terminal driver.
+.bP
+Tab expansion is turned on or off per the specification in the entry,
+and
+.bP
+if tabs are not expanded,
+standard tabs
+(every 8 spaces)
+are set.
+.RE
+.TP
+(4)
+If initialization capabilities,
+detailed in subsection \*(``Tabs and Initialization\*('' of
+\fB\%terminfo\fP(5),
+are present,
+\fB\%tput\fP writes them to the standard output stream.
+.TP
+(5)
+\fB\%tput\fP flushes the standard output stream.
+.RE
+.IP
+If an entry lacks the information needed for an activity above,
+that activity is silently skipped.
+.TP
+.B reset
+re-initializes the terminal.
+A reset differs from initialization in two ways.
+.RS
+.TP 5
+(1)
+\fB\%tput\fP sets the the terminal modes to a \*(``sane\*('' state,
+.RS
+.bP
+enabling cooked and echo modes,
+.bP
+disabling cbreak and raw modes,
+.bP
+enabling newline translation,
+and
+.bP
+setting any unset special characters to their default values.
+.RE
+.TP 5
+(2)
+If any reset capabilities are defined for the terminal type,
+\fB\%tput\fP writes them to the output stream.
+Otherwise,
+\fB\%tput\fP uses any defined initialization capabilities.
+Reset capabilities are detailed in subsection
+\*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
+.RE
+.TP
+.B longname
+A
+.I \%term\%info
+entry begins with one or more names by which an application
+can refer to the entry,
+before the list of terminal capabilities.
+The names are separated by \*(``|\*('' characters.
+X/Open Curses terms the last name the \*(``long name\*('',
+and indicates that it may include blanks.
+.IP
+\fB\%tic\fP warns if the last name does not include blanks,
+to accommodate old
+.I \%term\%info
+entries that treated the long name as an optional feature.
+The long name is often referred to as the description field.
+.IP
+If the terminal database is present and an entry for the user's terminal
+type exists,
+\fB\%tput\fP reports its description to the standard output stream,
+without a trailing newline.
+See \fB\%terminfo\fP(5).
+.PP
+.I Note:
+Redirecting the output of
+.RB \%\*(`` "tput init" \*(''
+or
+.RB \%\*(`` "tput reset" \*(''
+to a file will capture only part of their actions.
+Changes to the terminal modes are not affected by file descriptor
+redirection,
+since the terminal modes are altered via \fB\%ioctl\fP(2).
+.SS Aliases
+If \fB\%tput\fP is invoked via link with any of the names
+.BR clear ,
+.BR init ,
+or
+.BR \%reset ,
+it operates as if run with the corresponding (pseudo-)capability
+operand.
+For example,
+executing a link named
+.B \%reset
+that points to \fB\%tput\fP has the same effect as
+.RB \%\*(`` "tput \%reset" \*(''.
+.PP
+This feature was introduced by
+.I \%ncurses
+5.2 in 2000.
+It is rarely used:
+.TP
+.B \%clear
+is a separate program,
+which is both smaller and more frequently executed.
+.TP
+.B init
+has the same name as another program in widespread use.
+.TP
+.B \%reset
+is provided
+by the \fB\%tset\fP(1) utility (also via a link named
+.BR \%reset ")."
+.SS "Terminal Size"
+Besides the pseudo-capabilities
+(such as
+.BR init ),
+\fB\%tput\fP treats the
+.B lines
+and
+.B cols
+.I cap-codes
+specially:
+it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
+.bP
+First,
+\fB\%tput\fP attempts to obtain these capabilities from the terminal
+database.
+This generally fails for terminal emulators,
+which lack a fixed window size and thus omit the capabilities.
+.bP
+It then asks the operating system for the terminal's size,
+which generally works,
+unless the connection is via a serial line that
+does not support \*(``NAWS\*('': negotiations about window size.
+.bP
+Finally,
+it inspects the environment variables
+.I LINES
+and
+.I \%COLUMNS,
+which may override the terminal size.
+.PP
+If the
+.B \-T
+option is given,
+\fB\%tput\fP ignores the environment variables by calling
+.BR \%use_tioctl(TRUE) ,
+relying upon the operating system
+(or,
+ultimately,
+the terminal database).
+.SH OPTIONS
+.TP 9n \" "-T type" + 2n
+.B \-S
+retrieves more than one capability per invocation of \fB\%tput\fP.
+The capabilities must be passed to \fB\%tput\fP from the standard
+input stream instead of from the command line
+(see section \*(``EXAMPLES\*('' below).
+Only one
+.I cap-code
+is allowed per line.
+The
+.B \-S
+option changes the meanings of the
+.B 0
+and
+.B 1
+exit statuses
+(see section \*(``EXIT STATUS\*('' below).
+.IP
+Some capabilities use string parameters rather than numeric ones.
+\fB\%tput\fP employs a built-in table and the presence of parameters
+in its input to decide how to interpret them,
+and whether to use \fB\%tparm\fP(3X).
+.TP
+.BI \-T\  type
+indicates the terminal's
+.I type.
+Normally this option is unnecessary,
+because a default is taken from the
+.I TERM
+environment variable.
+If specified,
+the environment variables
+.I LINES
+and
+.I \%COLUMNS
+are also ignored.
+.TP
+.B \-V
+reports the version of
+.I \%ncurses
+associated with \fB\%tput\fP,
+and exits with a successful status.
+.TP
+.B \-x
+prevents
+.RB \%\*(`` "tput clear" \*(''
+from attempting to clear the scrollback buffer.
+.SH EXIT STATUS
+Normally,
+one should interpret \fB\%tput\fP's exit statuses as follows.
+.PP
+.if n .ne 3
+.if t .ne 2
+.TS
+Lb Lb
+Lb Lx.
+Status	Meaning When \-S Not Specified
+_
+0	Boolean or string capability present
+1	Boolean or numeric capability absent
+2	usage error or no terminal type specified
+3	unrecognized terminal type
+4	unrecognized capability code
+>4	system error (4 + \fBerrno\fP)
+.TE
+.PP
+When the
+.B \-S
+option is used,
+some statuses change meanings.
+.PP
+.if n .ne 4
+.if t .ne 3
+.TS
+Lb Lb
+Lb Lx.
+Status	Meaning When \-S Specified
+_
+0	all operands interpreted
+1	unused
+4	some operands not interpreted
+.TE
+.SH ENVIRONMENT
+\fBtput\fP reads one environment variable.
+.TP 8n \" "TERM" + 2n + adjustment for PDF
+.I TERM
+denotes the terminal type.
+Each terminal type is distinct,
+though many are similar.
+The
+.B \-T
+option overrides its value.
+.SH FILES
+.TP
+.I /usr/share/tabset
+tab stop initialization database
+.TP
+.I \*d
+compiled terminal description database
+.SH PORTABILITY
+Over time
+.I \%ncurses
+\fB\%tput\fP
+has differed from that of System\ V in two important respects,
+one now mostly historical.
+.bP
+\%\*(``\fBtput\fP
+.IR cap-code \*(''
+writes to the standard output,
+which need not be a terminal device.
+However,
+the operands that manipulate terminal modes might not use the standard
+output.
+.IP
+System\ V
+.BR tput 's
+.B init
+and
+.B \%reset
+operands use logic from 4.1cBSD
+.BR tset ,
+manipulating terminal modes.
+It checks the same file descriptors
+(and
+.IR \%/dev/tty )
+for association with a terminal device as
+.I \%ncurses
+now does,
+and if none are,
+finally assumes a 1200 baud terminal.
+When updating terminal modes,
+it ignores errors.
+.IP
+Until
+.I \%ncurses
+6.1
+(see section \*(``HISTORY\*('' below),
+\fB\%tput\fP did not modify terminal modes.
+It now employs a scheme similar to System\ V,
+using functions shared with \fB\%tset\fP
+(and ultimately based on 4.4BSD
+.BR tset ).
+If it is not able to open a terminal
+(for instance,
+when run by \fIcron\fP(1)),
+\fB\%tput\fP exits with an error status.
+.bP
+System\ V
+.B tput
+assumes that the type of a
+.I cap-code
+operand is numeric if all the characters of its value are decimal
+numbers;
+if they are not,
+it treats
+.I cap-code
+as a string capability.
+.IP
+Most implementations that provide support for
+.I cap-code
+operands use the \fB\%tparm\fP(3X) function to expand its parameters.
+That function expects a mixture of numeric and string parameters,
+requiring \fB\%tput\fP to know which type to use.
+.IP
+.I \%ncurses
+\fB\%tput\fP
+uses a table to determine the parameter types for
+the standard
+.I cap-code
+operands,
+and an internal function to analyze nonstandard
+.I cap-code
+operands.
+.IP
+While more reliable than System\ V's utility,
+a portability problem is introduced by this analysis.
+An OpenBSD developer adapted the internal library function from
+.I \%ncurses
+to port NetBSD's
+.IR termcap -based
+.B tput
+to
+.I \%term\%info,
+and modified it to interpret multiple
+.I cap-codes
+(and parameters)
+on the command line.
+Portable applications should not rely upon this feature;
+.I \%ncurses
+offers it to support applications written specifically for OpenBSD.
+.PP
+This implementation,
+unlike others,
+accepts both
+.I termcap
+and
+.I \%term\%info
+.I cap-codes
+if
+.I termcap
+support is compiled in.
+In that case,
+however,
+the predefined
+.I termcap
+and
+.I \%term\%info
+codes have two
+ambiguities;
+.I \%ncurses
+assumes the
+.I \%term\%info
+code.
+.bP
+The
+.I cap-code
+.B dl
+means
+.B \%delete_line
+to
+.I termcap
+but
+.B \%parm_delete_line
+to
+.I \%term\%info.
+.I termcap
+uses the code
+.B DL
+for
+.BR \%parm_delete_line .
+.I \%term\%info
+uses the code
+.B dch1
+for
+.BR \%delete_line .
+.bP
+The
+.I cap-code
+.B ed
+means
+.B \%exit_delete_mode
+to
+.I termcap
+but
+.B \%clr_eos
+to
+.I \%term\%info.
+.I termcap
+uses the code
+.B cd
+for
+.BR \%clr_eos .
+.I \%term\%info
+uses the code
+.B rmdc
+for
+.BR \%exit_delete_mode .
+.PP
+The
+.B \%longname
+operand,
+.B \-S
+option,
+and the parameter-substitution features used in the
+.B cup
+example below,
+were not supported in
+AT&T/USL
+.I curses
+before SVr4 (1989).
+Later,
+4.3BSD-Reno (1990) added support for
+.BR \%longname ,
+.\" longname was added in October 1989.
+and in 1994,
+NetBSD added support for the parameter-substitution features.
+.PP
+IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008)
+documents only the
+.BR clear ,
+.BR init ,
+and
+.B \%reset
+operands.
+A few observations of interest arise from that selection.
+.bP
+.I \%ncurses
+supports
+.B clear
+as it does any other standard
+.I cap-code.
+The others
+.RB ( init
+and
+.BR \%longname )
+do not correspond to terminal capabilities.
+.bP
+The
+.B tput
+on SVr4-based systems such as Solaris,
+IRIX64,
+and HP-UX,
+as well as others such as AIX and Tru64,
+also support standard
+.I cap-code
+operands.
+.bP
+A few platforms such as FreeBSD recognize
+.I termcap
+codes rather than
+.I \%term\%info
+capability codes in their respective
+.B tput
+commands.
+Since 2010,
+NetBSD's
+.B tput
+uses
+.I \%term\%info
+codes.
+Before that,
+it
+(like FreeBSD)
+recognized
+.I termcap
+codes.
+.IP
+Beginning in 2021,
+FreeBSD uses
+.I \%ncurses
+.BR tput ,
+configured for both
+.I \%term\%info
+(tested first)
+and
+.I termcap
+(as a fallback).
+.PP
+Because (apparently) all
+.I certified
+Unix systems support the full set of capability codes,
+the reason for documenting only a few may not be apparent.
+.bP
+X/Open Curses Issue 7 documents
+.B tput
+differently,
+with
+.I cap-code
+and the other features used in this implementation.
+.bP
+That is,
+there are two standards for
+.BR tput :
+POSIX (a subset) and X/Open Curses (the full implementation).
+POSIX documents a subset to avoid the complication of including
+X/Open Curses and the terminal capability database.
+.bP
+While it is certainly possible to write a
+.B tput
+program without using
+.I curses,
+no system with a
+.I curses
+implementation provides a
+.B tput
+utility that does not also support standard
+.I cap-codes.
+.PP
+X/Open Curses Issue 7 (2009) is the first version to document utilities.
+However that part of X/Open Curses does not follow existing practice
+(that is,
+System\ V
+.I curses
+behavior).
+.bP
+It assigns exit status 4 to \*(``invalid operand\*('',
+which may have the same meaning as \*(``unknown capability\*(''.
+For instance,
+the source code for
+Solaris
+.I xcurses
+uses the term \*(``invalid\*('' in this case.
+.bP
+It assigns exit status 255 to a numeric variable that is not specified
+in the
+.I \%term\%info
+database.
+That likely is a documentation error,
+mistaking the \*(``\-1\*('' written to the standard output to indicate
+an absent or cancelled numeric capability for an (unsigned) exit status.
+.PP
+The various System\ V implementations
+(AIX,
+HP-UX,
+Solaris)
+use the same exit statuses as
+.I \%ncurses.
+.PP
+NetBSD
+.I curses
+documents exit statuses that correspond to neither
+.I \%ncurses
+nor X/Open Curses.
+.SH HISTORY
+Bill Joy wrote a
+.B tput
+command during development of 4BSD in October 1980.
+This initial version only cleared the screen,
+and did not ship with official distributions.
+.\" It also exited with backwards exit status (1 on success, 0 on
+.\" failure), and was characterized by Bostic in 1988 as "pretty
+.\" unreasonable".
+.\" See Spinellis's "unix-history-repo" on GitHub.
+.PP
+System\ V developed a different
+.B tput
+command.
+.bP
+SVr2 (1984) provided a rudimentary
+.B tput
+that checked the parameter against each
+predefined capability and returned the corresponding value.
+This version of
+.B tput
+did not use \fB\%tparm\fP(3X) for parameterized capabilities.
+.bP
+SVr3 (1987) replaced that
+.\" SVr3 released in 1987, not 1985.
+.\" https://unix.org/what_is_unix/history_timeline.html
+with a more extensive program
+whose support for
+.B init
+and
+.B \%reset
+operands
+(more than half the program)
+incorporated the
+.B \%reset
+feature of BSD
+.B tset
+written by Eric Allman.
+.bP
+SVr4 (1989) added color initialization by using the
+.B \%orig_colors
+.RB ( oc )
+and
+.B \%orig_pair
+.RB ( op )
+capabilities in its
+.B init
+logic.
+.PP
+Keith Bostic refactored BSD
+.B tput
+for shipment in 4.3BSD-Tahoe (1988),
+then replaced it the next year with a new implementation based on
+System\ V
+.BR tput .
+Bostic's version similarly accepted some parameters named for
+.I \%term\%info
+(pseudo-)capabilities:
+.BR clear ,
+.BR init ,
+.BR \%longname ,
+and
+.BR \%reset .
+However,
+because he had only
+.I termcap
+available,
+it accepted
+.I termcap
+codes for other capabilities.
+Also,
+Bostic's BSD
+.B tput
+did not modify the terminal modes as the earlier BSD
+.B tset
+had done.
+.PP
+At the same time,
+Bostic added a shell script named \*(``clear\*('' that used
+.B tput
+to clear the screen.
+Both of these appeared in 4.4BSD,
+becoming the \*(``modern\*('' BSD implementation of
+.BR tput .
+.PP
+The origin of
+.I \%ncurses
+\fB\%tput\fP lies outside both System\ V and BSD,
+in Ross Ridge's
+.I \%mytinfo
+package,
+published on
+.I comp.sources.unix
+in December 1992.
+Ridge's program made more sophisticated use of the terminal capabilities
+than the BSD program.
+Eric Raymond used that
+.B tput
+program
+(and other parts of
+.IR \%mytinfo )
+in
+.I \%ncurses
+in June 1995.
+Incorporating the portions dealing with terminal capabilities
+almost without change,
+Raymond made improvements to the way command-line parameters
+were handled.
+.PP
+Before
+.I \%ncurses
+6.1 (2018),
+its \fB\%tset\fP and \fB\%tput\fP utilities differed.
+.bP
+\fB\%tset\fP was more effective,
+resetting the terminal modes and special characters.
+.bP
+On the other hand,
+\fB\%tset\fP's repertoire of terminal capabilities for resetting the
+terminal was more limited;
+it had only equivalents of
+.B \%reset_1string
+.RB ( rs1 ),
+.B \%reset_2string
+.RB ( rs2 ),
+and
+.B \%reset_file
+.RB ( rf ),
+and not the tab stop and margin update features of \fB\%tput\fP.
+.PP
+The
+.B \%reset
+program is traditionally an alias for \fB\%tset\fP due to its ability
+to reset terminal modes and special characters.
+.PP
+As of
+.I \%ncurses
+6.1,
+the \*(``reset\*('' features of the two programs are (mostly) the same.
+Two minor differences remain.
+.bP
+The \fB\%tset\fP program waits one second when resetting,
+in case the terminal happens to be a hardware device.
+.bP
+The two programs write the terminal initialization strings
+to different streams;
+that is,
+standard error for \fB\%tset\fP and
+standard output for \fB\%tput\fP.
+.SH EXAMPLES
+.TP
+.B "tput init"
+Initialize the terminal according to the type of
+terminal in the
+.I TERM
+environment variable.
+If the system does not reliably initialize the terminal upon login,
+this command can be included in
+.I \%$HOME/.profile
+after exporting the
+.I TERM
+environment variable.
+.TP
+.B "tput \-T5620 reset"
+Reset an AT&T 5620 terminal,
+overriding the terminal type in the
+.I TERM
+environment variable.
+.TP
+.B "tput cnorm"
+Set cursor to normal visibility.
+.TP
+.B "tput home"
+Move the cursor to row 0,
+column 0:
+the upper left corner of the screen,
+usually known as the \*(``home\*('' cursor position.
+.TP
+.B "tput clear"
+Clear the screen:
+write the
+.B \%clear_screen
+capability's value to the standard output stream.
+.TP
+.B "tput cols"
+Report the number of columns used by the current terminal type.
+.TP
+.B "tput \-Tadm3a cols"
+Report the number of columns used by an ADM-3A terminal.
+.TP
+.B "strong=\(gatput smso\(ga normal=\(gatput rmso\(ga"
+Set shell variables to capability values:
+.B strong
+and
+.BR normal ,
+to begin and end,
+respectively,
+stand-out mode for the terminal.
+One might use these to present a prompt.
+.IP
+.EX
+.RS 14
+printf "${strong}Username:${normal} "
+.RE
+.EE
+.TP
+.B "tput hc"
+Indicate via exit status whether the terminal is a hard copy device.
+.TP
+.B "tput cup 23 4"
+Move the cursor to row 23,
+column 4.
+.TP
+.B "tput cup"
+Report the value of the
+.B \%cursor_address
+.RB ( cup )
+capability
+(used for cursor movement),
+with no parameters substituted.
+.TP
+.B "tput longname"
+Report the
+.I \%term\%info
+database's description of the terminal type specified in the
+.I TERM
+environment variable.
+.TP
+.B "tput \-S"
+Process multiple capabilities.
+The
+.B \-S
+option can be profitably used with a shell \*(``here document\*(''.
+.IP
+.EX
+.RB $\  "tput \-S <<!"
+.RB >\  clear
+.RB >\  "cup 10 10"
+.RB >\  bold
+.RB >\  !
+.EE
+.IP
+The foregoing
+clears the screen,
+moves the cursor to position
+(10, 10)
+and turns on bold
+(extra bright)
+mode.
+.TP
+.B "tput clear cup 10 10 bold"
+Perform the same actions as the foregoing
+.RB \%\*(`` "tput \-S" \*(''
+example.
+.SH SEE ALSO
+\fB\%clear\fP(1),
+\fB\%stty\fP(1),
+\fB\%tabs\fP(1),
+\fB\%tset\fP(1),
+\fB\%curs_termcap\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/upstream/mageia-cauldron/man1/tr.1 b/upstream/mageia-cauldron/man1/tr.1
new file mode 100644
index 00000000..f2534669
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tr.1
@@ -0,0 +1,143 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tr \- translate or delete characters
+.SH SYNOPSIS
+.B tr
+[\fI\,OPTION\/\fR]... \fI\,STRING1 \/\fR[\fI\,STRING2\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Translate, squeeze, and/or delete characters from standard input,
+writing to standard output.  STRING1 and STRING2 specify arrays of
+characters ARRAY1 and ARRAY2 that control the action.
+.TP
+\fB\-c\fR, \fB\-C\fR, \fB\-\-complement\fR
+use the complement of ARRAY1
+.TP
+\fB\-d\fR, \fB\-\-delete\fR
+delete characters in ARRAY1, do not translate
+.TP
+\fB\-s\fR, \fB\-\-squeeze\-repeats\fR
+replace each sequence of a repeated character
+that is listed in the last specified ARRAY,
+with a single occurrence of that character
+.TP
+\fB\-t\fR, \fB\-\-truncate\-set1\fR
+first truncate ARRAY1 to length of ARRAY2
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+ARRAYs are specified as strings of characters.  Most represent themselves.
+Interpreted sequences are:
+.TP
+\eNNN
+character with octal value NNN (1 to 3 octal digits)
+.TP
+\e\e
+backslash
+.TP
+\ea
+audible BEL
+.TP
+\eb
+backspace
+.TP
+\ef
+form feed
+.TP
+\en
+new line
+.TP
+\er
+return
+.TP
+\et
+horizontal tab
+.TP
+\ev
+vertical tab
+.TP
+CHAR1\-CHAR2
+all characters from CHAR1 to CHAR2 in ascending order
+.TP
+[CHAR*]
+in ARRAY2, copies of CHAR until length of ARRAY1
+.TP
+[CHAR*REPEAT]
+REPEAT copies of CHAR, REPEAT octal if starting with 0
+.TP
+[:alnum:]
+all letters and digits
+.TP
+[:alpha:]
+all letters
+.TP
+[:blank:]
+all horizontal whitespace
+.TP
+[:cntrl:]
+all control characters
+.TP
+[:digit:]
+all digits
+.TP
+[:graph:]
+all printable characters, not including space
+.TP
+[:lower:]
+all lower case letters
+.TP
+[:print:]
+all printable characters, including space
+.TP
+[:punct:]
+all punctuation characters
+.TP
+[:space:]
+all horizontal or vertical whitespace
+.TP
+[:upper:]
+all upper case letters
+.TP
+[:xdigit:]
+all hexadecimal digits
+.TP
+[=CHAR=]
+all characters which are equivalent to CHAR
+.PP
+Translation occurs if \fB\-d\fR is not given and both STRING1 and STRING2 appear.
+\fB\-t\fR may be used only when translating.  ARRAY2 is extended to length of
+ARRAY1 by repeating its last character as necessary.  Excess characters
+of ARRAY2 are ignored.  Character classes expand in unspecified order;
+while translating, [:lower:] and [:upper:] may be used in pairs to
+specify case conversion.  Squeezing occurs after translation or deletion.
+.SH BUGS
+.PP
+Full support is available only for safe single-byte locales,
+in which every possible input byte represents a single character.
+The C locale is safe in GNU systems, so you can avoid this issue
+in the shell by running
+.B "LC_ALL=C tr"
+instead of plain
+.BR tr .
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/tr>
+.br
+or available locally via: info \(aq(coreutils) tr invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tree.1 b/upstream/mageia-cauldron/man1/tree.1
new file mode 100644
index 00000000..1f4f80e3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tree.1
@@ -0,0 +1,505 @@
+.\" $Copyright: $
+.\" Copyright (c) 1996 - 2022 by Steve Baker
+.\" All Rights reserved
+.\"
+.\" 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 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+.\"
+...
+.TH TREE 1 "" "Tree 2.1.0"
+.SH NAME
+tree \- list contents of directories in a tree-like format.
+.SH SYNOPSIS
+\fBtree\fP
+[\fB-acdfghilnpqrstuvxACDFJQNSUX\fP]
+[\fB-L\fP \fIlevel\fP [\fB-R\fP]]
+[\fB-H\fP \fIbaseHREF\fP]
+[\fB-T\fP \fItitle\fP]
+[\fB-o\fP \fIfilename\fP]
+[\fB-P\fP \fIpattern\fP]
+[\fB-I\fP \fIpattern\fP]
+[\fB--gitignore\fP]
+[\fB--gitfile\fP[\fB=\fP]\fIfile\fP]
+[\fB--matchdirs\fP]
+[\fB--metafirst\fP]
+[\fB--ignore-case\fP]
+[\fB--nolinks\fP]
+[\fB--hintro\fP[\fB=\fP]\fIfile\fP]
+[\fB--houtro\fP[\fB=\fP]\fIfile\fP]
+[\fB--inodes\fP]
+[\fB--device\fP]
+[\fB--sort\fP[\fB=\fP]\fIname\fP]
+[\fB--dirsfirst\fP]
+[\fB--filesfirst\fP]
+[\fB--filelimit\fP \fI#\fP]
+[\fB--si\fP]
+[\fB--du\fP]
+[\fB--prune\fP]
+[\fB--charset[\fB=\fP]X\fP]
+[\fB--timefmt\fP[\fB=\fP]\fIformat\fP]
+[\fB--fromfile\fP]
+[\fB--fflinks\fP]
+[\fB--info\fP]
+[\fB--infofile\fP[\fB=\fP]\fIfile\fP]
+[\fB--noreport\fP]
+[\fB--version\fP]
+[\fB--help\fP]
+[\fB--\fP] [\fIdirectory\fP ...]
+
+.br
+.SH DESCRIPTION
+\fITree\fP is a recursive directory listing program that produces a depth
+indented listing of files, which is colorized ala \fIdircolors\fP if the
+\fBLS_COLORS\fP environment variable is set and output is to tty.  With no
+arguments, \fItree\fP lists the files in the current directory.  When directory
+arguments are given, \fItree\fP lists all the files and/or directories found in
+the given directories each in turn.  Upon completion of listing all
+files/directories found, \fItree\fP returns the total number of files and/or
+directories listed.
+
+By default, when a symbolic link is encountered, the path that the symbolic
+link refers to is printed after the name of the link in the format:
+.br
+
+    name -> real-path
+.br
+
+If the `\fB-l\fP' option is given and the symbolic link refers to an actual
+directory, then \fItree\fP will follow the path of the symbolic link as if
+it were a real directory.
+.br
+
+.SH OPTIONS
+\fITree\fP understands the following command line switches:
+
+.SH LISTING OPTIONS
+
+.TP
+.B -a
+All files are printed.  By default tree does not print hidden files (those
+beginning with a dot `.').  In no event does tree print the file system
+constructs `.' (current directory) and `..' (previous directory).
+.PP
+.TP
+.B -d
+List directories only.
+.PP
+.TP
+.B -l
+Follows symbolic links if they point to directories, as if they were
+directories. Symbolic links that will result in recursion are avoided when
+detected.
+.PP
+.TP
+.B -f
+Prints the full path prefix for each file.
+.PP
+.TP
+.B -x
+Stay on the current file-system only.  Ala \fBfind \fI-xdev\fP.
+.PP
+.TP
+.B -L \fIlevel\fP
+Max display depth of the directory tree.
+.PP
+.TP
+.B -R
+Recursively cross down the tree each \fIlevel\fP directories (see \fB-L\fP
+option), and at each level outputting to a file named \fB00Tree.html\fP
+(ala \fB-o\fP).
+.PP
+.TP
+.B -P \fIpattern\fP
+List only those files that match the wild-card \fIpattern\fP.  You may have
+multiple -P options. Note: you must use the \fI-a\fP option to also consider
+those files beginning with a dot `.' for matching.  Valid wildcard operators
+are `*' (any zero or more characters), `**` (any zero or more characters as
+well as null /'s, i.e. /**/ may match a single /), `?' (any single character),
+`[...]' (any single character listed between brackets (optional - (dash) for
+character range may be used: ex: [A-Z]), and `[^...]' (any single character
+not listed in brackets) and `|' separates alternate patterns. A '/' at the
+end of the pattern matches directories, but not files.
+.PP
+.TP
+.B -I \fIpattern\fP
+Do not list those files that match the wild-card \fIpattern\fP.  You may have
+multiple -I options.  See \fI-P\fP above for information on wildcard patterns.
+.PP
+.TP
+.B --gitignore
+Uses git \fB.gitignore\fP files for filtering files and directories.  Also
+uses \fB$GIT_DIR/info/exclude\fP if present.
+.PP
+.TP
+.B --gitfile\fR[\fB=\fR]\fIfile\fP
+Use \fIfile\fP explicitly as a gitignore file.
+.PP
+.TP
+.B --ignore-case
+If a match pattern is specified by the \fB-P\fP or \fB-I\fP option, this will
+cause the pattern to match without regard to the case of each letter.
+.PP
+.TP
+.B --matchdirs
+If a match pattern is specified by the \fB-P\fP option, this will cause the
+pattern to be applied to directory names (in addition to filenames).  In the
+event of a match on the directory name, matching is disabled for the directory's
+contents. If the \fB--prune\fP option is used, empty folders that match the
+pattern will not be pruned.
+.PP
+.TP
+.B --metafirst
+Print the meta-data information at the beginning of the line rather than
+after the indentation lines.
+.PP
+.TP
+.B --prune
+Makes tree prune empty directories from the output, useful when used in
+conjunction with \fB-P\fP or \fB-I\fP.  See \fBBUGS AND NOTES\fP below for
+more information on this option. 
+.PP
+.TP
+.B --info
+Prints file comments found in .info files.  See \fB.INFO FILES\fP below
+for more information on the format of .info files.
+.PP
+.TP
+.B --infofile\fR[\fB=\fR]\fIfile\fP
+Use \fIfile\fP explicitly as a info file.
+.PP
+.TP
+.B --noreport
+Omits printing of the file and directory report at the end of the tree
+listing.
+.PP
+.TP
+.B --charset\fR[\fB=\fR]\fIcharset\fP
+Set the character set to use when outputting HTML and for line drawing.
+.PP
+.TP
+.B --filelimit\fR[\fB=\fR]\fI#\fP
+Do not descend directories that contain more than \fI#\fP entries.
+.PP
+.TP
+.B --timefmt\fR[\fB=\fR]\fIformat\fP
+Prints (implies -D) and formats the date according to the format string
+which uses the \fBstrftime\fP(3) syntax.
+.PP
+.TP
+.B -o \fIfilename\fP
+Send output to \fIfilename\fP.
+.PP
+
+.SH FILE OPTIONS
+
+.TP
+.B -q
+Print non-printable characters in filenames as question marks instead of the
+default.
+.PP
+.TP
+.B -N
+Print non-printable characters as is instead of as escaped octal numbers.
+.PP
+.TP
+.B -Q
+Quote the names of files in double quotes.
+.PP
+.TP
+.B -p
+Print the file type and permissions for each file (as per ls -l).
+.PP
+.TP
+.B -u
+Print the username, or UID # if no username is available, of the file.
+.PP
+.TP
+.B -g
+Print the group name, or GID # if no group name is available, of the file.
+.PP
+.TP
+.B -s
+Print the size of each file in bytes along with the name.
+.PP
+.TP
+.B -h
+Print the size of each file but in a more human readable way, e.g. appending a
+size letter for kilobytes (K), megabytes (M), gigabytes (G), terabytes (T),
+petabytes (P) and exabytes (E).
+.PP
+.TP
+.B --si
+Like \fB-h\fP but use SI units (powers of 1000) instead.
+.PP
+.TP
+.B --du
+For each directory report its size as the accumulation of sizes of all its files
+and sub-directories (and their files, and so on).  The total amount of used
+space is also given in the final report (like the 'du -c' command.) This option
+requires tree to read the entire directory tree before emitting it, see
+\fBBUGS AND NOTES\fP below.  Implies \fB-s\fP.
+.PP
+.TP
+.B -D
+Print the date of the last modification time or if \fB-c\fP is used, the last
+status change time for the file listed.
+.PP
+.TP
+.B -F
+Append a `/' for directories, a `=' for socket files, a `*' for executable
+files, a `>' for doors (Solaris) and a `|' for FIFO's, as per ls -F
+.PP
+.TP
+.B --inodes
+Prints the inode number of the file or directory
+.PP
+.TP
+.B --device
+Prints the device number to which the file or directory belongs
+.PP
+
+.SH SORTING OPTIONS
+
+.TP
+.B -v
+Sort the output by version.
+.PP
+.TP
+.B -t
+Sort the output by last modification time instead of alphabetically.
+.PP
+.TP
+.B -c
+Sort the output by last status change instead of alphabetically.  Modifies the
+\fB-D\fP option (if used) to print the last status change instead of
+modification time.
+.PP
+.TP
+.B -U
+Do not sort.  Lists files in directory order. Disables \fB--dirsfirst\fP.
+.PP
+.TP
+.B -r
+Sort the output in reverse order.  This is a meta-sort that alter the above sorts.
+This option is disabled when \fB-U\fP is used.
+.PP
+.TP
+.B --dirsfirst
+List directories before files. This is a meta-sort that alters the above sorts.
+This option is disabled when \fB-U\fP is used.
+.PP
+.TP
+.B --filesfirst
+List files before directories. This is a meta-sort that alters the above sorts.
+This option is disabled when \fB-U\fP is used.
+.PP
+.TP
+.B --sort\fR[\fB=\fR]\fItype\fR
+Sort the output by \fItype\fR instead of name. Possible values are:
+\fBctime\fR (\fB-c\fP),
+\fBmtime\fR (\fB-t\fB), \fBsize\fR, or \fBversion\fR (\fB-v\fB).
+
+.SH GRAPHICS OPTIONS
+
+.TP
+.B -i
+Makes tree not print the indentation lines, useful when used in conjunction
+with the \fB-f\fP option.  Also removes as much whitespace as possible when used
+with the \fB-J\fP or \fB-X\fP options.
+.PP
+.TP
+.B -A
+Turn on ANSI line graphics hack when printing the indentation lines.
+.PP
+.TP
+.B -S
+Turn on CP437 line graphics (useful when using Linux console mode fonts). This
+option is now equivalent to `--charset=IBM437' and may eventually be depreciated.
+.PP
+.TP
+.B -n
+Turn colorization off always, over-ridden by the \fB-C\fP option, however
+overrides CLICOLOR_FORCE if present.
+.PP
+.TP
+.B -C
+Turn colorization on always, using built-in color defaults if the LS_COLORS or
+TREE_COLORS environment variables are not set.  Useful to colorize output to a
+pipe.
+.PP
+
+.SH XML/JSON/HTML OPTIONS
+
+.TP
+.B -X
+Turn on XML output. Outputs the directory tree as an XML formatted file.
+.PP
+.TP
+.B -J
+Turn on JSON output. Outputs the directory tree as a JSON formatted array.
+.PP
+.TP
+.B -H \fIbaseHREF\fP
+Turn on HTML output, including HTTP references. Useful for ftp sites.
+\fIbaseHREF\fP gives the base ftp location when using HTML output. That is, the
+local directory may be `/local/ftp/pub', but it must be referenced as
+`ftp://hostname.organization.domain/pub' (\fIbaseHREF\fP should be
+`ftp://hostname.organization.domain'). Hint: don't use ANSI lines with this
+option, and don't give more than one directory in the directory list. If you
+wish to use colors via CSS style-sheet, use the -C option in addition to this
+option to force color output.
+.PP
+.TP
+.B --hintro\fR[\fB=\fR]\fIfile\fP
+Use \fIfile\fP as the HTML intro in place of the default one.  Use an empty
+file or \fI/dev/null\fP to eliminate the intro altogether.
+.PP
+.TP
+.B --houtro\fR[\fB=\fR]\fIfile\fP
+Use \fIfile\fP as the HTML outro in place of the default one.  Use an empty
+file or \fI/dev/null\fP to eliminate the outro altogether.
+.PP
+.TP
+.B -T \fItitle\fP
+Sets the title and H1 header string in HTML output mode.
+.PP
+.TP
+.B --nolinks
+Turns off hyperlinks in HTML output.
+.PP
+
+.SH INPUT OPTIONS
+
+.TP
+.B --fromfile
+Reads a directory listing from a file rather than the file-system.  Paths
+provided on the command line are files to read from rather than directories to
+search.  The dot (.) directory indicates that tree should read paths from
+standard input. NOTE: this is only suitable for reading the output of a program
+such as find, not 'tree -fi' as symlinks are not distinguished from files that
+simply contain ' -> ' as part of the filename unless the \fB--fflinks\fP option
+is used.
+.PP
+.TP
+.B --fflinks
+Processes symbolic link information found in a file, as from the output of
+\fB'tree -fi --noreport'\fP.  Only the first occurrence of the string \fB' -> '\fP
+is used to denote the separation of the filename from the link.
+.PP
+
+.SH MISC OPTIONS
+
+.TP
+.B --help
+Outputs a verbose usage listing.
+.PP
+.TP
+.B --version
+Outputs the version of tree.
+.PP
+.TP
+.B --
+Option processing terminator.  No further options will be processed after this.
+.PP
+
+.SH .INFO FILES
+
+\fB.info\fP files are similiar to \.gitignore files, if a .info file is found
+while scanning a directory it is read and added to a stack of .info
+information. Each file is composed of comments (lines starting with hash marks
+(#),) or wild-card patterns which may match a file relative to the directory
+the \.info file is found in.  If a file should match a pattern, the tab indented
+comment that follows the pattern is used as the file comment.  A comment is
+terminated by a non-tab indented line. Multiple patterns, each to a line, may
+share the same comment.
+
+.br
+.SH FILES
+\fB/etc/DIR_COLORS\fP		System color database.
+.br
+\fB~/.dircolors\fP			Users color database.
+.br
+\fB.gitignore\fP			Git exclusion file
+.br
+\fB$GIT_DIR/info/exclude\fP	Global git file exclusion list
+.br
+\fB.info\fP				File comment file
+.br
+\fB/usr/share/finfo/global_info\fP	Global file comment file
+
+
+.SH ENVIRONMENT
+\fBLS_COLORS\fP		Color information created by dircolors
+.br
+\fBTREE_COLORS\fP	Uses this for color information over LS_COLORS if it is set.
+.br
+\fBTREE_CHARSET\fP	Character set for tree to use in HTML mode.
+.br
+\fBCLICOLOR\fP		Enables colorization even if TREE_COLORS or LS_COLORS is not set.
+.br
+\fBCLICOLOR_FORCE\fP	Always enables colorization (effectively -C)
+.br
+\fBNO_COLOR\fP		Disable colorization (effectively -n) (see \fBhttps://no-color.org/\fP)
+.br
+\fBLC_CTYPE\fP		Locale for filename output.
+.br
+\fBLC_TIME\fP		Locale for timefmt output, see \fBstrftime\fP(3).
+.br
+\fBTZ\fP			Timezone for timefmt output, see \fBstrftime\fP(3).
+.br
+\fBSTDDATA_FD\fP	Enable the stddata feature, optionally set descriptor to use.
+
+.SH AUTHOR
+Steve Baker (ice@mama.indstate.edu)
+.br
+HTML output hacked by Francesc Rocher (rocher@econ.udg.es)
+.br
+Charsets and OS/2 support by Kyosuke Tokoro (NBG01720@nifty.ne.jp)
+
+.SH BUGS AND NOTES
+Tree does not prune "empty" directories when the -P and -I options are used by
+default. Use the --prune option.
+
+The -h and --si options round to the nearest whole number unlike the ls
+implementations which rounds up always.
+
+Pruning files and directories with the -I, -P and --filelimit options will
+lead to incorrect file/directory count reports.
+
+The --prune and --du options cause tree to accumulate the entire tree in memory
+before emitting it. For large directory trees this can cause a significant delay
+in output and the use of large amounts of memory.
+
+The timefmt expansion buffer is limited to a ridiculously large 255 characters.
+Output of time strings longer than this will be undefined, but are guaranteed
+to not exceed 255 characters.
+
+XML/JSON trees are not colored, which is a bit of a shame.
+
+Probably more.
+
+As of version 2.0.0, in Linux, tree will attempt to automatically output a
+compact JSON tree on file descriptor 3 (what I call stddata,) if present and the
+environment variable STDDATA_FD is defined or set to a positive non-zero file
+descriptor value to use to output on.  It is hoped that some day a better
+Linux/Unix shell may take advantage of this feature, though BSON would probably
+be a better format for this.
+
+.SH SEE ALSO
+.BR dircolors (1),
+.BR ls (1),
+.BR find (1),
+.BR du (1),
+.BR strftime (3)
+.BR gitignore (5)
diff --git a/upstream/mageia-cauldron/man1/troff.1 b/upstream/mageia-cauldron/man1/troff.1
new file mode 100644
index 00000000..2403abdc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/troff.1
@@ -0,0 +1,682 @@
+'\" t
+.TH TROFF 1 "17 December 2018" "groff 1.22.4"
+.SH NAME
+troff \- the troff processor of the groff text formatting system
+.
+.\" troff.man -> troff.1
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\"
+.\" This file is part of groff, the GNU roff type-setting system.
+.\"
+.\" Permission is granted to copy, distribute and/or modify this
+.\" document under the terms of the GNU Free Documentation License,
+.\" Version 1.3 or any later version published by the Free Software
+.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
+.\" and with no Back-Cover Texts.
+.\"
+.\" A copy of the Free Documentation License is included as a file
+.\" called FDL in the main directory of the groff source package.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY troff
+.OP \-abcivzCERU
+.OP \-d cs
+.OP \-f fam
+.OP \-F dir
+.OP \-I dir
+.OP \-m name
+.OP \-M dir
+.OP \-n num
+.OP \-o list
+.OP \-r cn
+.OP \-T name
+.OP \-w name
+.OP \-W name
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This manual page describes the GNU version of
+.BR troff .
+.
+It is part of the groff document formatting system.
+.
+It is functionally compatible with Unix troff, but has many
+extensions, see
+.BR \%groff_diff (7).
+.
+Usually it should be invoked using the
+.BR groff (1)
+command which will also run preprocessors and postprocessors in the
+appropriate order and with the appropriate options.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-a
+Generate an ASCII approximation of the typeset output.
+.
+.TP
+.B \-b
+Print a backtrace with each warning or error message.
+.
+This backtrace should help track down the cause of the error.
+.
+The line numbers given in the backtrace may not always be correct, for
+.BR troff 's
+idea of line numbers gets confused by
+.B as
+or
+.B am
+requests.
+.
+.TP
+.B \-c
+Disable color output (always disabled in compatibility mode).
+.
+.TP
+.B \-C
+Enable compatibility mode.
+.
+.TP
+.BI \-d cs
+.TQ
+.BI \-d name = s
+Define
+.I c
+or
+.I name
+to be a string
+.IR s ;
+.I c
+must be a one letter name.
+.
+.TP
+.B \-E
+Inhibit all error messages of
+.BR troff .
+.
+Note that this doesn't affect messages output to standard error by
+macro packages using the
+.B tm
+or
+.B tm1
+requests.
+.
+.TP
+.BI \-f fam
+Use
+.I fam
+as the default font family.
+.
+.TP
+.BI \-F dir
+Search in directory (or directory path)
+.I dir
+for subdirectories
+.IR dev name
+.RI ( name
+is the name of the device) and there for the
+.I DESC
+file and font files.
+.
+.I dir
+is scanned before all other font directories.
+.
+.TP
+.B \-i
+Read the standard input after all the named input files have been
+processed.
+.
+.TP
+.BI \-I dir
+This option may be used to add a directory to the search path for
+files (both those on the command line and those named in
+.B \&.psbb
+requests).
+.
+The search path is initialized with the current directory.
+.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+.
+If you want to make the current directory be read before other
+directories, add
+.B \-I.\&
+at the appropriate place.
+.
+.IP
+No directory search is performed for files with an absolute file name.
+.
+.TP
+.BI \-m name
+Read in the file
+.RI name .tmac .
+.
+If it isn't found, try
+.IR tmac. name
+instead.
+.
+It will be first searched for in directories given with the
+.B \-M
+command-line option, then in directories given in the
+.I GROFF_TMAC_PATH
+environment variable, then in the current directory (only if in unsafe
+mode), the home directory,
+.IR /usr/\:lib64/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+and
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
+.
+.TP
+.BI \-M dir
+Search directory (or directory path)
+.I dir
+for macro files.
+.
+This is scanned before all other macro directories.
+.
+.TP
+.BI \-n num
+Number the first page
+.IR num .
+.
+.TP
+.BI \-o list
+Output only pages in
+.IR list ,
+which is a comma-separated list of page ranges;
+.I n
+means print page
+.IR n ,
+.IB m \- n
+means print every page between
+.I m
+and
+.IR n ,
+.BI \- n
+means print every page up to
+.IR n ,
+.IB n \-
+means print every page from
+.IR n .
+.
+.B troff
+will exit after printing the last page in the list.
+.
+.TP
+.BI \-r cn
+.TQ
+.BI \-r name = n
+Set number register
+.I c
+or
+.I name
+to
+.IR n ;
+.I c
+must be a one character name;
+.I n
+can be any troff numeric expression.
+.
+.TP
+.B \-R
+Don't load
+.I troffrc
+and
+.IR troffrc\-end .
+.
+.TP
+.BI \-T name
+Prepare output for device
+.IR name ,
+rather than the default
+.BR ps ;
+see
+.BR groff (1)
+for a more detailed description.
+.
+.TP
+.B \-U
+Unsafe mode.
+.
+This will enable the following requests:
+.BR open ,
+.BR opena ,
+.BR pso ,
+.BR sy ,
+and
+.BR pi .
+For security reasons, these potentially dangerous requests are
+disabled otherwise.
+.
+It will also add the current directory to the macro search path.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.BI \-w name
+Enable warning
+.IR  name .
+.
+Available warnings are described in section \(lqWarnings\(rq below.
+.
+To enable most useful warnings use
+.B \-w
+.BR all .
+To enable absolutely all warnings use
+.B \-w w
+instead.
+Multiple
+.B \-w
+options are allowed.
+.
+.TP
+.BI \-W name
+Inhibit warning
+.IR name .
+.
+Multiple
+.B \-W
+options are allowed.
+.
+.TP
+.B \-z
+Suppress formatted output.
+.
+.
+.\" ====================================================================
+.SH WARNINGS
+.\" ====================================================================
+.
+The warnings that can be given by
+.B troff
+are divided into the following categories.
+.
+The name associated with each warning is used by the
+.B \-w
+and
+.B \-W
+options; the number is used by the
+.B warn
+request, and by the
+.B .warn
+register; it is always a power of 2 to allow bitwise composition.
+.
+.P
+.TS
+tab(@), center, box;
+c c c | c c c
+r rI lB | r rI lB.
+Bit@Code@Warning@Bit@Code@Warning
+_
+0@1@char@10@1024@reg
+1@2@number@11@2048@tab
+2@4@break@12@4096@right-brace
+3@8@delim@13@8192@missing
+4@16@el@14@16384@input
+5@32@scale@15@32768@escape
+6@64@range@16@65536@space
+7@128@syntax@17@131072@font
+8@256@di@18@262144@ig
+9@512@mac@19@524288@color
+@@@20@1048576@file
+.TE
+.
+.P
+.nr x \w'\fBright-brace'+1n+\w'00000'u
+.ta \nxuR
+.
+.TP \nxu+3n
+.BR break "\t4"
+In fill mode, lines which could not be broken so that their length was
+less than the line length.
+.
+This is enabled by default.
+.
+.TP
+.BR char "\t1"
+Non-existent characters.
+.
+This is enabled by default.
+.
+.TP
+.BR color "\t524288"
+Color-related warnings.
+.
+.TP
+.BR delim "\t8"
+Missing or mismatched closing delimiters.
+.
+.TP
+.BR di "\t256"
+Use of
+.B di
+or
+.B da
+without an argument when there is no current diversion.
+.
+.TP
+.BR el "\t16"
+Use of the
+.B el
+request with no matching
+.B ie
+request.
+.
+.TP
+.BR escape "\t32768"
+Unrecognized escape sequences.
+.
+When an unrecognized escape sequence is encountered, the escape
+character is ignored.
+.
+.TP
+.BR file "\t1048576"
+Indicates a missing file for the
+.B mso
+request.
+.
+Enabled by default.
+.
+.TP
+.BR font "\t131072"
+Non-existent fonts.
+.
+This is enabled by default.
+.
+.TP
+.BR ig "\t262144"
+Invalid escapes in text ignored with the
+.B ig
+request.
+.
+These are conditions that are errors when they do not occur in ignored
+text.
+.
+.TP
+.BR input "\t16384"
+Invalid input characters.
+.
+.TP
+.BR mac "\t512"
+Use of undefined strings, macros and diversions.
+.
+When an undefined string, macro or diversion is used, that string is
+automatically defined as empty.
+.
+So, in most cases, at most one warning will be given for each name.
+.
+.TP
+.BR missing "\t8192"
+Requests that are missing non-optional arguments.
+.
+.TP
+.BR number "\t2"
+Invalid numeric expressions.
+.
+This is enabled by default.
+.
+.TP
+.BR range "\t64"
+Out of range arguments.
+.
+.TP
+.BR reg "\t1024"
+Use of undefined number registers.
+.
+When an undefined number register is used, that register is
+automatically defined to have a value of\~0.
+.
+So, in most cases, at most one warning will be given for use of a
+particular name.
+.
+.TP
+.BR right-brace "\t4096"
+Use of
+.B \(rs}
+where a number was expected.
+.
+.TP
+.BR scale "\t32"
+Meaningless scaling indicators.
+.
+.TP
+.BR space "\t65536"
+Missing space between a request or macro and its argument.
+.
+This warning will be given when an undefined name longer than two
+characters is encountered, and the first two characters of the name
+make a defined name.
+.
+The request or macro will not be invoked.
+.
+When this warning is given, no macro is automatically defined.
+.
+This is enabled by default.
+.
+This warning will never occur in compatibility mode.
+.
+.TP
+.BR syntax "\t128"
+Dubious syntax in numeric expressions.
+.
+.TP
+.BR tab "\t2048"
+Inappropriate use of a tab character.
+.
+Either use of a tab character where a number was expected, or use of tab
+character in an unquoted macro argument.
+.
+.P
+There are also names that can be used to refer to groups of warnings:
+.
+.TP
+.B all
+All warnings except
+.BR di ,
+.BR mac ,
+and
+.BR reg .
+.
+It is intended that this covers all warnings that are useful with
+traditional macro packages.
+.
+.TP
+.B w
+All warnings.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_TMAC_PATH
+A colon separated list of directories in which to search for
+macro files.
+.
+.B troff
+will scan directories given in the
+.B \-M
+option before these, and in standard directories (current directory if
+in unsafe mode, home directory,
+.IR /usr/\:lib64/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac )
+after these.
+.
+.TP
+.I GROFF_TYPESETTER
+Default device.
+.
+.TP
+.I GROFF_FONT_PATH
+A colon separated list of directories in which to search for the
+.IR dev name
+directory.
+.
+.B troff
+will scan directories given in the
+.B \-F
+option before these, and in standard directories
+.RI ( /usr/\:share/\:groff/\:site\-font ,
+.IR /usr/\:share/\:groff/\:1.22.4/\:font ,
+.IR /usr/\:lib/\:font )
+after these.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc
+Initialization file (called before any other macro package).
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc\-end
+Initialization file (called after any other macro package).
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/ name .tmac
+.TQ
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/tmac. name
+Macro files
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name /DESC
+Device description file for device
+.IR name .
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name / F
+Font file for font
+.I F
+of device
+.IR name .
+.
+.
+.P
+Note that
+.I troffrc
+and
+.I troffrc\-end
+are searched for neither in the current nor the home directory by
+default for security reasons (even if the
+.B \-U
+option is given).
+.
+Use the
+.B \-M
+command-line option or the
+.I GROFF_TMAC_PATH
+environment variable to add these directories to the search path if
+necessary.
+.
+.
+.\" ====================================================================
+.SH AUTHORS
+.\" ====================================================================
+.
+The GNU version of
+.I troff
+was originally written by James Clark;
+he also wrote the original version of this document,
+which was modified by
+.MT wl@\:gnu.org
+Werner Lemberg
+.ME
+and
+.MT groff\-bernd.warken\-72@\:web.de
+Bernd Warken
+.ME .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.TP
+.BR groff (1)
+The main program of the
+.I groff
+system, a wrapper around
+.IR troff .
+.
+.TP
+.BR groff (7)
+A description of the
+.I groff
+language, including a short but complete reference of all predefined
+requests, registers, and escapes of plain
+.IR groff .
+.
+From the command line, this is called by
+.RS
+.IP
+.B man 7 groff
+.RE
+.
+.TP
+.BR \%groff_diff (7)
+The differences of the
+.I groff
+language and the
+.I classical troff
+language.
+.
+Currently, this is the most actual document of the
+.I groff
+system.
+.
+.TP
+.BR roff (7)
+An overview over
+.I groff
+and other
+.I roff
+systems, including pointers to further related documentation.
+.
+.
+.P
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \(lqinfo groff\(rq.
+.
+.
+.\" ====================================================================
+.\" Emacs variables
+.\" ====================================================================
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff:
diff --git a/upstream/mageia-cauldron/man1/true.1 b/upstream/mageia-cauldron/man1/true.1
new file mode 100644
index 00000000..de9fa185
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/true.1
@@ -0,0 +1,40 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TRUE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+true \- do nothing, successfully
+.SH SYNOPSIS
+.B true
+[\fI\,ignored command line arguments\/\fR]
+.br
+.B true
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Exit with a status code indicating success.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+NOTE: your shell may have its own version of true, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+.SH AUTHOR
+Written by Jim Meyering.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/true>
+.br
+or available locally via: info \(aq(coreutils) true invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/truncate.1 b/upstream/mageia-cauldron/man1/truncate.1
new file mode 100644
index 00000000..b460f311
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/truncate.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TRUNCATE "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+truncate \- shrink or extend the size of a file to the specified size
+.SH SYNOPSIS
+.B truncate
+\fI\,OPTION\/\fR... \fI\,FILE\/\fR...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Shrink or extend the size of each FILE to the specified size
+.PP
+A FILE argument that does not exist is created.
+.PP
+If a FILE is larger than the specified size, the extra data is lost.
+If a FILE is shorter, it is extended and the sparse extended part (hole)
+reads as zero bytes.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-c\fR, \fB\-\-no\-create\fR
+do not create any files
+.TP
+\fB\-o\fR, \fB\-\-io\-blocks\fR
+treat SIZE as number of IO blocks instead of bytes
+.TP
+\fB\-r\fR, \fB\-\-reference\fR=\fI\,RFILE\/\fR
+base size on RFILE
+.TP
+\fB\-s\fR, \fB\-\-size\fR=\fI\,SIZE\/\fR
+set or adjust the file size by SIZE bytes
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+SIZE may also be prefixed by one of the following modifying characters:
+\&'+' extend by, '\-' reduce by, '<' at most, '>' at least,
+\&'/' round down to multiple of, '%' round up to multiple of.
+.SH AUTHOR
+Written by Padraig Brady.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBdd\fP(1), \fBtruncate\fP(2), \fBftruncate\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/truncate>
+.br
+or available locally via: info \(aq(coreutils) truncate invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tset.1 b/upstream/mageia-cauldron/man1/tset.1
new file mode 100644
index 00000000..88777169
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tset.1
@@ -0,0 +1,462 @@
+.\"***************************************************************************
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: tset.1,v 1.79 2023/12/23 16:20:07 tom Exp $
+.TH tset 1 2023-12-23 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ^  \(ha
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.ds       ^  ^
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.
+.ds d /usr/share/terminfo
+.SH NAME
+\fB\%tset\fP,
+\fB\%reset\fP \-
+initialize or reset terminal state
+.SH SYNOPSIS
+\fBtset\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal-type\fP]
+.br
+\fBreset\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal-type\fP]
+.SH DESCRIPTION
+.SS "\fItset\fP \(em initialization"
+This program initializes terminals.
+.PP
+First, \fBtset\fP retrieves the current terminal mode settings
+for your terminal.
+It does this by successively testing
+.bP
+the standard error,
+.bP
+standard output,
+.bP
+standard input and
+.bP
+ultimately \*(``/dev/tty\*(''
+.PP
+to obtain terminal settings.
+Having retrieved these settings, \fBtset\fP remembers which
+file descriptor to use when updating settings.
+.PP
+Next, \fBtset\fP determines the type of terminal that you are using.
+This determination is done as follows, using the first terminal type found.
+.PP
+1. The \fBterminal\fP argument specified on the command line.
+.PP
+2. The value of the \fITERM\fP environment variable.
+.PP
+3. (BSD systems only.) The terminal type associated with the standard
+error output device in the \fI/etc/ttys\fP file.
+(On System\ V hosts and systems using that convention,
+\fI\%getty\fP(8) does this job by setting
+\fITERM\fP according to the type passed to it by \fI\%/etc/inittab\fP.)
+.PP
+4. The default terminal type, \*(``unknown\*('',
+is not suitable for curses applications.
+.PP
+If the terminal type was not specified on the command-line, the \fB\-m\fP
+option mappings are then applied;
+see subsection \*(``Terminal Type Mapping\*(''.
+Then, if the terminal type begins with a question mark (\*(``?\*(''), the
+user is prompted for confirmation of the terminal type.
+An empty
+response confirms the type, or, another type can be entered to specify
+a new type.
+Once the terminal type has been determined,
+the terminal description for the terminal is retrieved.
+If no terminal description is found
+for the type, the user is prompted for another terminal type.
+.PP
+Once the terminal description is retrieved,
+.bP
+if the \*(``\fB\-w\fP\*('' option is enabled, \fBtset\fP may update
+the terminal's window size.
+.IP
+If the window size cannot be obtained from the operating system,
+but the terminal description
+(or environment,
+e.g.,
+\fILINES\fP and \fI\%COLUMNS\fP variables specify this),
+use this to set the operating system's notion of the window size.
+.bP
+if the \*(``\fB\-c\fP\*('' option is enabled,
+the backspace, interrupt and line kill characters
+(among many other things) are set
+.bP
+unless the \*(``\fB\-I\fP\*('' option is enabled,
+the terminal
+and tab \fIinitialization\fP strings are sent to the standard error output,
+and \fBtset\fP waits one second (in case a hardware reset was issued).
+.bP
+Finally, if the erase, interrupt and line kill characters have changed,
+or are not set to their default values, their values are displayed to the
+standard error output.
+.SS "\fIreset\fP \(em reinitialization"
+When invoked as \fBreset\fP, \fBtset\fP sets the terminal
+modes to \*(``sane\*('' values:
+.bP
+sets cooked and echo modes,
+.bP
+turns off cbreak and raw modes,
+.bP
+turns on newline translation and
+.bP
+resets any unset special characters to their default values
+.PP
+before
+doing the terminal initialization described above.
+Also, rather than using the terminal \fIinitialization\fP strings,
+it uses the terminal \fIreset\fP strings.
+.PP
+The \fBreset\fP command is useful
+after a program dies leaving a terminal in an abnormal state:
+.bP
+you may have to type
+.sp
+    \fI<LF>\fBreset\fI<LF>\fR
+.sp
+(the line-feed character is normally control-J) to get the terminal
+to work, as carriage-return may no longer work in the abnormal state.
+.bP
+Also, the terminal will often not echo the command.
+.SS "Setting the Environment"
+It is often desirable to enter the terminal type and information about
+the terminal's capabilities into the shell's environment.
+This is done using the \fB\-s\fP option.
+.PP
+When the \fB\-s\fP option is specified, the commands to enter the information
+into the shell's environment are written to the standard output.
+If the \fISHELL\fP environment variable ends in \*(``csh\*('',
+the commands
+are for \fIcsh\fP(1),
+otherwise,
+they are for \fIsh\fP(1).
+The \fIcsh\fP commands set and unset the shell variable \fBnoglob\fP,
+leaving it unset.
+The following line in the \fB.login\fP
+or \fB.profile\fP files will initialize the environment correctly:
+.sp
+    eval \(gatset \-s options ... \(ga
+.
+.SS "Terminal Type Mapping"
+When the terminal is not hardwired into the system (or the current
+system information is incorrect) the terminal type derived from the
+\fI/etc/ttys\fP file or the \fITERM\fP environment variable is often
+something generic like \fBnetwork\fP, \fBdialup\fP, or \fBunknown\fP.
+When \fBtset\fP is used in a startup script it is often desirable to
+provide information about the type of terminal used on such ports.
+.PP
+The \fB\-m\fP options maps
+from some set of conditions to a terminal type, that is, to
+tell \fBtset\fP
+\*(``If I'm on this port at a particular speed,
+guess that I'm on that kind of terminal\*(''.
+.PP
+The argument to the \fB\-m\fP option consists of an optional port type, an
+optional operator, an optional baud rate specification, an optional
+colon (\*(``:\*('') character and a terminal type.
+The port type is a
+string (delimited by either the operator or the colon character).
+The operator may be any combination of
+\*(``>\*('',
+\*(``<\*('',
+\*(``@\*('',
+and \*(``!\*('';
+\*(``>\*('' means greater than,
+\*(``<\*('' means less than,
+\*(``@\*('' means equal to and
+\*(``!\*('' inverts the sense of the test.
+The baud rate is specified as a number and is compared with the speed
+of the standard error output (which should be the control terminal).
+The terminal type is a string.
+.PP
+If the terminal type is not specified on the command line, the \fB\-m\fP
+mappings are applied to the terminal type.
+If the port type and baud
+rate match the mapping, the terminal type specified in the mapping
+replaces the current type.
+If more than one mapping is specified, the
+first applicable mapping is used.
+.PP
+For example, consider the following mapping: \fBdialup>9600:vt100\fP.
+The port type is dialup , the operator is >, the baud rate
+specification is 9600, and the terminal type is vt100.
+The result of
+this mapping is to specify that if the terminal type is \fBdialup\fP,
+and the baud rate is greater than 9600 baud, a terminal type of
+\fBvt100\fP will be used.
+.PP
+If no baud rate is specified, the terminal type will match any baud rate.
+If no port type is specified, the terminal type will match any port type.
+For example, \fB\-m dialup:vt100 \-m :?xterm\fP
+will cause any dialup port, regardless of baud rate, to match the terminal
+type vt100, and any non-dialup port type to match the terminal type ?xterm.
+Note, because of the leading question mark, the user will be
+queried on a default port as to whether they are actually using an xterm
+terminal.
+.PP
+No whitespace characters are permitted in the \fB\-m\fP option argument.
+Also, to avoid problems with meta-characters, it is suggested that the
+entire \fB\-m\fP option argument be placed within single quote characters,
+and that \fIcsh\fP users insert a backslash character (\*(``\e\*('')
+before any exclamation marks (\*(``!\*('').
+.SH OPTIONS
+The options are as follows:
+.TP 5
+.B \-c
+Set control characters and modes.
+.TP 5
+.BI \-e\  ch
+Set the erase character to \fIch\fP.
+.TP
+.B \-I
+Do not send the terminal or tab initialization strings to the terminal.
+.TP
+.BI \-i\  ch
+Set the interrupt character to \fIch\fP.
+.TP
+.BI \-k\  ch
+Set the line kill character to \fIch\fP.
+.TP
+.BI \-m\  mapping
+Specify a mapping from a port type to a terminal;
+see subsection \*(``Terminal Type Mapping\*(''.
+.TP
+.B \-Q
+Do not display any values for the erase, interrupt and line kill characters.
+Normally \fBtset\fP displays the values for control characters which
+differ from the system's default values.
+.TP
+.B \-q
+The terminal type is displayed to the standard output, and the terminal is
+not initialized in any way.
+The option \*(``\-\*('' by itself is equivalent but archaic.
+.TP
+.B \-r
+Print the terminal type to the standard error output.
+.TP
+.B \-s
+Print the sequence of shell commands to initialize the environment variable
+\fITERM\fP to the standard output;
+see subsection \*(``Setting the Environment\*(''.
+.TP
+.B \-V
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
+.TP
+.B \-w
+Resize the window to match the size deduced via \fBsetupterm\fP(3X).
+Normally this has no effect,
+unless \fBsetupterm\fP is not able to detect the window size.
+.PP
+The arguments for the \fB\-e\fP, \fB\-i\fP, and \fB\-k\fP
+options may either be entered as actual characters
+or by using the \*(``hat\*(''
+notation, i.e., control-h may be specified as \*(``\*^H\*('' or \*(``\*^h\*(''.
+.PP
+If neither \fB\-c\fP or \fB\-w\fP is given, both options are assumed.
+.SH ENVIRONMENT
+The \fBtset\fP command uses these environment variables:
+.TP 5
+.I SHELL
+tells \fBtset\fP whether to initialize \fITERM\fP using \fIsh\fP(1) or
+\fIcsh\fP(1) syntax.
+.TP 5
+.I TERM
+Denotes your terminal type.
+Each terminal type is distinct, though many are similar.
+.TP 5
+.I TERMCAP
+may denote the location of a termcap database.
+If it is not an absolute pathname, e.g., begins with a \*(``/\*('',
+\fBtset\fP removes the variable from the environment before looking
+for the terminal description.
+.SH FILES
+.TP
+.I /etc/ttys
+system port name to terminal type mapping database (BSD versions only).
+.TP
+.I \*d
+compiled terminal description database directory
+.SH PORTABILITY
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008) nor
+X/Open Curses Issue 7 documents \fBtset\fP or \fBreset\fP.
+.PP
+The AT&T \fBtput\fP utility (AIX, HP-UX, Solaris)
+incorporated the terminal-mode manipulation as well as termcap-based features
+such as resetting tabstops from \fBtset\fP in BSD (4.1c),
+presumably with the intention of making \fBtset\fP obsolete.
+However, each of those systems still provides \fBtset\fP.
+In fact, the commonly-used \fBreset\fP utility
+is always an alias for \fBtset\fP.
+.PP
+The \fB\%tset\fP utility provides backward compatibility with BSD
+environments;
+under most modern Unices,
+\fI\%/etc/inittab\fP and \fI\%getty\fP(8) can set \fITERM\fP
+appropriately for each dial-up line,
+obviating what was \fB\%tset\fP's most important use.
+This implementation behaves like 4.4BSD \fBtset\fP,
+with a few exceptions we shall consider now.
+.PP
+A few options are different
+because the \fI\%TERMCAP\fP variable
+is no longer supported under terminfo-based \fI\%ncurses\fP:
+.bP
+The \fB\-S\fP option of BSD \fBtset\fP no longer works;
+it prints an error message to the standard error and dies.
+.bP
+The \fB\-s\fP option only sets \fITERM\fP,
+not \fI\%TERMCAP\fP.
+.PP
+There was an undocumented 4.4BSD feature
+that invoking \fBtset\fP via a link named
+\*(``TSET\*('' (or via any other name beginning with an upper-case letter)
+set the terminal to use upper-case only.
+This feature has been omitted.
+.PP
+The \fB\-A\fP, \fB\-E\fP, \fB\-h\fP, \fB\-u\fP and \fB\-v\fP
+options were deleted from the \fBtset\fP
+utility in 4.4BSD.
+None of them were documented in 4.3BSD and all are
+of limited utility at best.
+The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options are similarly
+not documented or useful, but were retained as they appear to be in
+widespread use.
+It is strongly recommended that any usage of these
+three options be changed to use the \fB\-m\fP option instead.
+The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options
+are therefore omitted from the usage summary above.
+.PP
+Very old systems, e.g., 3BSD, used a different terminal driver which
+was replaced in 4BSD in the early 1980s.
+To accommodate these older systems, the 4BSD \fBtset\fP provided a
+\fB\-n\fP option to specify that the new terminal driver should be used.
+This implementation does not provide that choice.
+.PP
+It is still permissible to specify the \fB\-e\fP, \fB\-i\fP,
+and \fB\-k\fP options without arguments,
+although it is strongly recommended that such usage be fixed to
+explicitly specify the character.
+.PP
+As of 4.4BSD,
+executing \fBtset\fP as \fBreset\fP no longer implies the \fB\-Q\fP option.
+Also, the interaction between the \- option and the \fIterminal\fP
+argument in some historic implementations of \fBtset\fP has been removed.
+.PP
+The \fB\-c\fP and \fB\-w\fP options are not found in earlier implementations.
+However, a different window size-change feature was provided in 4.4BSD.
+.bP
+In 4.4BSD, \fBtset\fP uses the window size from the termcap description
+to set the window size if \fBtset\fP is not able to obtain the window
+size from the operating system.
+.bP
+In \fI\%ncurses\fP, \fBtset\fP obtains the window size using
+\fBsetupterm\fP, which may be from
+the operating system,
+the \fILINES\fP and \fICOLUMNS\fP environment variables or
+the terminal description.
+.PP
+Obtaining the window size from the terminal description is common to
+both implementations, but considered obsolescent.
+Its only practical use is for hardware terminals.
+Generally speaking, a window size would be unset only if there were
+some problem obtaining the value from the operating system
+(and \fBsetupterm\fP would still fail).
+For that reason,
+the \fILINES\fP and \fI\%COLUMNS\fP environment variables
+may be useful for working around window-size problems.
+Those have the drawback that if the window is resized,
+those variables must be recomputed and reassigned.
+To do this more easily, use the \fBresize\fP(1) program.
+.SH HISTORY
+A \fB\%reset\fP command written by Kurt Shoens appeared in 1BSD
+(March 1978).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/reset.c
+It set the \fIerase\fP and \fIkill\fP characters
+to \fB\*^H\fP (backspace) and \fB@\fP respectively.
+Mark Horton improved this \fB\%reset\fP in 3BSD
+(October 1979),
+adding \fIintr\fP,
+\fIquit\fP,
+\fIstart\fP/\fIstop\fP,
+and \fIeof\fP
+characters as well as changing the program to avoid modifying any user
+settings.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\"   reset.c
+That version of \fB\%reset\fP did not use \fI\%termcap\fP.
+.PP
+Eric Allman wrote a distinct \fBtset\fP command for 1BSD,
+using a forerunner of \fI\%termcap\fP called \fI\%ttycap\fP.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/tset.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+Allman's comments in the source code indicate
+that he began work in October 1977,
+continuing development over the next few years.
+By late 1979,
+it had migrated to \fI\%termcap\fP and handled the \fI\%TERMCAP\fP
+variable.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\"   tset/tset.c
+Later comments indicate that \fBtset\fP was modified in September 1980
+to use logic copied from the 3BSD \*(``reset\*('' program when it was
+invoked as \fB\%reset\fP.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2.9BSD/usr/src/ucb/\
+.\"   tset/tset.c
+This version appeared in 4.1cBSD, \" and backported to 2.9BSD
+late in 1982.
+Other developers such as Keith Bostic and Jim Bloom continued to modify
+\fBtset\fP until 4.4BSD was released in 1993.
+.PP
+The \fI\%ncurses\fP implementation was lightly adapted from the 4.4BSD
+sources to use the \fI\%terminfo\fP API by Eric S.\& Raymond
+<esr@snark.thyrsus.com>.
+.SH SEE ALSO
+\fB\%csh\fP(1),
+\fB\%sh\fP(1),
+\fB\%stty\fP(1),
+\fB\%curs_terminfo\fP(3X),
+\fB\%tty\fP(4),
+\fB\%terminfo\fP(5),
+\fB\%ttys\fP(5),
+\fB\%environ\fP(7)
diff --git a/upstream/mageia-cauldron/man1/tsort.1 b/upstream/mageia-cauldron/man1/tsort.1
new file mode 100644
index 00000000..b40d8445
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tsort.1
@@ -0,0 +1,35 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TSORT "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tsort \- perform topological sort
+.SH SYNOPSIS
+.B tsort
+[\fI\,OPTION\/\fR] [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Write totally ordered list consistent with the partial ordering in FILE.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Mark Kettenis.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/tsort>
+.br
+or available locally via: info \(aq(coreutils) tsort invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/tty.1 b/upstream/mageia-cauldron/man1/tty.1
new file mode 100644
index 00000000..cf5d11af
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tty.1
@@ -0,0 +1,36 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH TTY "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+tty \- print the file name of the terminal connected to standard input
+.SH SYNOPSIS
+.B tty
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the file name of the terminal connected to standard input.
+.TP
+\fB\-s\fR, \fB\-\-silent\fR, \fB\-\-quiet\fR
+print nothing, only return an exit status
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/tty>
+.br
+or available locally via: info \(aq(coreutils) tty invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/ukify.1 b/upstream/mageia-cauldron/man1/ukify.1
new file mode 100644
index 00000000..00e7ff62
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ukify.1
@@ -0,0 +1,673 @@
+'\" t
+.TH "UKIFY" "1" "" "systemd 255" "ukify"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+ukify \- Combine components into a signed Unified Kernel Image for UEFI systems
+.SH "SYNOPSIS"
+.HP \w'\fBukify\fR\ 'u
+\fBukify\fR [OPTIONS...] build
+.HP \w'\fBukify\fR\ 'u
+\fBukify\fR [OPTIONS...] genkey
+.HP \w'\fBukify\fR\ 'u
+\fBukify\fR [OPTIONS...] inspect FILE...
+.SH "DESCRIPTION"
+.PP
+\fBukify\fR
+is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and a UEFI boot stub) to create a
+\m[blue]\fBUnified Kernel Image (UKI)\fR\m[]\&\s-2\u[1]\d\s+2
+\(em a PE binary that can be executed by the firmware to start the embedded linux kernel\&. See
+\fBsystemd-stub\fR(7)
+for details about the stub\&.
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.SS "build"
+.PP
+This command creates a Unified Kernel Image\&. The two primary options that should be specified for the
+\fBbuild\fR
+verb are
+\fILinux=\fR/\fB\-\-linux=\fR, and
+\fIInitrd=\fR/\fB\-\-initrd=\fR\&.
+\fIInitrd=\fR
+accepts multiple whitespace\-separated paths and
+\fB\-\-initrd=\fR
+can be specified multiple times\&.
+.PP
+Additional sections will be inserted into the UKI, either automatically or only if a specific option is provided\&. See the discussions of
+\fICmdline=\fR/\fB\-\-cmdline=\fR,
+\fIOSRelease=\fR/\fB\-\-os\-release=\fR,
+\fIDeviceTree=\fR/\fB\-\-devicetree=\fR,
+\fISplash=\fR/\fB\-\-splash=\fR,
+\fIPCRPKey=\fR/\fB\-\-pcrpkey=\fR,
+\fIUname=\fR/\fB\-\-uname=\fR,
+\fISBAT=\fR/\fB\-\-sbat=\fR, and
+\fB\-\-section=\fR
+below\&.
+.PP
+\fBukify\fR
+can also be used to assemble a PE binary that is not executable but contains auxiliary data, for example additional kernel command line entries\&.
+.PP
+If PCR signing keys are provided via the
+\fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR
+and
+\fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
+options, PCR values that will be seen after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI\&.
+\fBsystemd-measure\fR(1)
+is used to perform this calculation and signing\&.
+.PP
+The calculation of PCR values is done for specific boot phase paths\&. Those can be specified with the
+\fIPhases=\fR/\fB\-\-phases=\fR
+option\&. If not specified, the default provided by
+\fBsystemd\-measure\fR
+is used\&. It is also possible to specify the
+\fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
+\fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR, and
+\fIPhases=\fR/\fB\-\-phases=\fR
+arguments more than once\&. Signatures will then be performed with each of the specified keys\&. On the command line, when both
+\fB\-\-phases=\fR
+and
+\fB\-\-pcr\-private\-key=\fR
+are used, they must be specified the same number of times, and then the n\-th boot phase path set will be signed by the n\-th key\&. This can be used to build different trust policies for different phases of the boot\&. In the config file,
+\fIPCRPrivateKey=\fR,
+\fIPCRPublicKey=\fR, and
+\fIPhases=\fR
+are grouped into separate sections, describing separate boot phases\&.
+.PP
+If a SecureBoot signing key is provided via the
+\fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
+option, the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot\&. Also see the discussion of automatic enrollment in
+\fBsystemd-boot\fR(7)\&.
+.PP
+If the stub and/or the kernel contain
+"\&.sbat"
+sections they will be merged in the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim\&. For more information on SBAT see
+\m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.SS "genkey"
+.PP
+This command creates the keys for PCR signing and the key and certificate used for SecureBoot signing\&. The same configuration options that determine what keys and in which paths will be needed for signing when
+\fBbuild\fR
+is used, here determine which keys will be created\&. See the discussion of
+\fIPCRPrivateKey=\fR/\fB\-\-pcr\-private\-key=\fR,
+\fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR, and
+\fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
+below\&.
+.PP
+The output files must not exist\&.
+.SS "inspect"
+.PP
+Display information about the sections in a given binary or binaries\&. If
+\fB\-\-all\fR
+is given, all sections are shown\&. Otherwise, if
+\fB\-\-section=\fR
+option is specified at least once, only those sections are shown\&. Otherwise, well\-known sections that are typically included in an UKI are shown\&. For each section, its name, size, and sha256\-digest is printed\&. For text sections, the contents are printed\&.
+.PP
+Also see the description of
+\fB\-j\fR/\fB\-\-json=\fR
+and
+\fB\-\-section=\fR\&.
+.SH "CONFIGURATION SETTINGS"
+.PP
+Settings can appear in configuration files (the syntax with
+\fISomeSetting=\fR\fI\fIvalue\fR\fR) and on the command line (the syntax with
+\fB\-\-some\-setting=\fR\fB\fIvalue\fR\fR)\&. For some command line parameters, a single\-letter shortcut is also allowed\&. In the configuration files, the setting must be in the appropriate section, so the descriptions are grouped by section below\&. When the same setting appears in the configuration file and on the command line, generally the command line setting has higher priority and overwrites the config file setting completely\&. If some setting behaves differently, this is described below\&.
+.PP
+If no config file is provided via the option
+\fB\-\-config=\fR\fB\fIPATH\fR\fR,
+\fBukify\fR
+will try to look for a default configuration file in the following paths in this order:
+/run/systemd/ukify\&.conf,
+/etc/systemd/ukify\&.conf,
+/usr/local/lib/systemd/ukify\&.conf, and
+/usr/lib/systemd/ukify\&.conf, and then load the first one found\&.
+\fBukify\fR
+will proceed normally if no configuration file is specified and no default one is found\&.
+.PP
+The
+\fILINUX\fR
+and
+\fIINITRD\fR
+positional arguments, or the equivalent
+\fILinux=\fR
+and
+\fIInitrd=\fR
+settings, are optional\&. If more than one initrd is specified, they will all be combined into a single PE section\&. This is useful to, for example, prepend microcode before the actual initrd\&.
+.PP
+The following options and settings are understood:
+.SS "Command line\-only options"
+.PP
+\fB\-\-config=\fR\fB\fIPATH\fR\fR
+.RS 4
+Load configuration from the given config file\&. In general, settings specified in the config file have lower precedence than the settings specified via options\&. In cases where the command line option does not fully override the config file setting are explicitly mentioned in the descriptions of individual options\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-measure\fR, \fB\-\-no\-measure\fR
+.RS 4
+Enable or disable a call to
+\fBsystemd-measure\fR(1)
+to print pre\-calculated PCR values\&. Defaults to false\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR, \fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fBtext|binary\fR\fB[@\fIPATH\fR]\fR
+.RS 4
+For all verbs except
+\fBinspect\fR, the first syntax is used\&. Specify an arbitrary additional section
+"\fINAME\fR"\&. The argument may be a literal string, or
+"@"
+followed by a path name\&. This option may be specified more than once\&. Any sections specified in this fashion will be inserted (in order) before the
+"\&.linux"
+section which is always last\&.
+.sp
+For the
+\fBinspect\fR
+verb, the second syntax is used\&. The section
+\fINAME\fR
+will be inspected (if found)\&. If the second argument is
+"text", the contents will be printed\&. If the third argument is given, the contents will be saved to file
+\fIPATH\fR\&.
+.sp
+Note that the name is used as\-is, and if the section name should start with a dot, it must be included in
+\fINAME\fR\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-tools=\fR\fB\fIDIRS\fR\fR
+.RS 4
+Specify one or more directories with helper tools\&.
+\fBukify\fR
+will look for helper tools in those directories first, and if not found, try to load them from
+\fI$PATH\fR
+in the usual fashion\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-output=\fR\fB\fIFILENAME\fR\fR
+.RS 4
+The output filename\&. If not specified, the name of the
+\fILINUX\fR
+argument, with the suffix
+"\&.unsigned\&.efi"
+or
+"\&.signed\&.efi"
+will be used, depending on whether signing for SecureBoot was performed\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fB\-\-summary\fR
+.RS 4
+Print a summary of loaded config and exit\&. This is useful to check how the options from the configuration file and the command line are combined\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fB\-\-all\fR
+.RS 4
+Print all sections (with
+\fBinspect\fR
+verb)\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-json\fR
+.RS 4
+Generate JSON output (with
+\fBinspect\fR
+verb)\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SS "[UKI] section"
+.PP
+\fILinux=\fR\fI\fILINUX\fR\fR, \fB\-\-linux=\fR\fB\fILINUX\fR\fR
+.RS 4
+A path to the kernel binary\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fIInitrd=\fR\fI\fIINITRD\fR\fR\fI\&.\&.\&.\fR, \fB\-\-initrd=\fR\fB\fILINUX\fR\fR
+.RS 4
+Zero or more initrd paths\&. In the configuration file, items are separated by whitespace\&. The initrds are combined in the order of specification, with the initrds specified in the config file first\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fICmdline=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-cmdline=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
+.RS 4
+The kernel command line (the
+"\&.cmdline"
+section)\&. The argument may be a literal string, or
+"@"
+followed by a path name\&. If not specified, no command line will be embedded\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIOSRelease=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-os\-release=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
+.RS 4
+The os\-release description (the
+"\&.osrel"
+section)\&. The argument may be a literal string, or
+"@"
+followed by a path name\&. If not specified, the
+\fBos-release\fR(5)
+file will be picked up from the host system\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIDeviceTree=\fR\fI\fIPATH\fR\fR, \fB\-\-devicetree=\fR\fB\fIPATH\fR\fR
+.RS 4
+The devicetree description (the
+"\&.dtb"
+section)\&. The argument is a path to a compiled binary DeviceTree file\&. If not specified, the section will not be present\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISplash=\fR\fI\fIPATH\fR\fR, \fB\-\-splash=\fR\fB\fIPATH\fR\fR
+.RS 4
+A picture to display during boot (the
+"\&.splash"
+section)\&. The argument is a path to a BMP file\&. If not specified, the section will not be present\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIPCRPKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcrpkey=\fR\fB\fIPATH\fR\fR
+.RS 4
+A path to a public key to embed in the
+"\&.pcrpkey"
+section\&. If not specified, and there\*(Aqs exactly one
+\fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR
+argument, that key will be used\&. Otherwise, the section will not be present\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIUname=\fR\fI\fIVERSION\fR\fR, \fB\-\-uname=\fR\fB\fIVERSION\fR\fR
+.RS 4
+Specify the kernel version (as in
+\fBuname \-r\fR, the
+"\&.uname"
+section)\&. If not specified, an attempt will be made to extract the version string from the kernel image\&. It is recommended to pass this explicitly if known, because the extraction is based on heuristics and not very reliable\&. If not specified and extraction fails, the section will not be present\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIPCRBanks=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-banks=\fR\fB\fIPATH\fR\fR
+.RS 4
+A comma or space\-separated list of PCR banks to sign a policy for\&. If not present, all known banks will be used ("sha1",
+"sha256",
+"sha384",
+"sha512"), which will fail if not supported by the system\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISecureBootSigningTool=\fR\fI\fISIGNER\fR\fR, \fB\-\-signtool=\fR\fB\fISIGNER\fR\fR
+.RS 4
+Whether to use
+"sbsign"
+or
+"pesign"\&. Depending on this choice, different parameters are required in order to sign an image\&. Defaults to
+"sbsign"\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fISecureBootPrivateKey=\fR\fI\fISB_KEY\fR\fR, \fB\-\-secureboot\-private\-key=\fR\fB\fISB_KEY\fR\fR
+.RS 4
+A path to a private key to use for signing of the resulting binary\&. If the
+\fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
+option is used, this may also be an engine\-specific designation\&. This option is required by
+\fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISecureBootCertificate=\fR\fI\fISB_CERT\fR\fR, \fB\-\-secureboot\-certificate=\fR\fB\fISB_CERT\fR\fR
+.RS 4
+A path to a certificate to use for signing of the resulting binary\&. If the
+\fISigningEngine=\fR/\fB\-\-signing\-engine=\fR
+option is used, this may also be an engine\-specific designation\&. This option is required by
+\fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISecureBootCertificateDir=\fR\fI\fISB_PATH\fR\fR, \fB\-\-secureboot\-certificate\-dir=\fR\fB\fISB_PATH\fR\fR
+.RS 4
+A path to a nss certificate database directory to use for signing of the resulting binary\&. Takes effect when
+\fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR
+is used\&. Defaults to
+/etc/pki/pesign\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fISecureBootCertificateName=\fR\fI\fISB_CERTNAME\fR\fR, \fB\-\-secureboot\-certificate\-name=\fR\fB\fISB_CERTNAME\fR\fR
+.RS 4
+The name of the nss certificate database entry to use for signing of the resulting binary\&. This option is required by
+\fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fISecureBootCertificateValidity=\fR\fI\fIDAYS\fR\fR, \fB\-\-secureboot\-certificate\-validity=\fR\fB\fIDAYS\fR\fR
+.RS 4
+Period of validity (in days) for a certificate created by
+\fBgenkey\fR\&. Defaults to 3650, i\&.e\&. 10 years\&.
+.sp
+Added in version 254\&.
+.RE
+.PP
+\fISigningEngine=\fR\fI\fIENGINE\fR\fR, \fB\-\-signing\-engine=\fR\fB\fIENGINE\fR\fR
+.RS 4
+An "engine" for signing of the resulting binary\&. This option is currently passed verbatim to the
+\fB\-\-engine=\fR
+option of
+\fBsbsign\fR(1)\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISignKernel=\fR\fI\fIBOOL\fR\fR, \fB\-\-sign\-kernel\fR, \fB\-\-no\-sign\-kernel\fR
+.RS 4
+Override the detection of whether to sign the Linux binary itself before it is embedded in the combined image\&. If not specified, it will be signed if a SecureBoot signing key is provided via the
+\fISecureBootPrivateKey=\fR/\fB\-\-secureboot\-private\-key=\fR
+option and the binary has not already been signed\&. If
+\fISignKernel=\fR/\fB\-\-sign\-kernel\fR
+is true, and the binary has already been signed, the signature will be appended anyway\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fISBAT=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-sbat=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR
+.RS 4
+SBAT metadata associated with the UKI or addon\&. SBAT policies are useful to revoke whole groups of UKIs or addons with a single, static policy update that does not take space in DBX/MOKX\&. If not specified manually, a default metadata entry consisting of
+"uki,1,UKI,uki,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html"
+will be used, to ensure it is always possible to revoke UKIs and addons\&. For more information on SBAT see
+\m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.sp
+Added in version 254\&.
+.RE
+.SS "[PCRSignature:\fINAME\fR] section"
+.PP
+In the config file, those options are grouped by section\&. On the command line, they must be specified in the same order\&. The sections specified in both sources are combined\&.
+.PP
+\fIPCRPrivateKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-private\-key=\fR\fB\fIPATH\fR\fR
+.RS 4
+A private key to use for signing PCR policies\&. On the command line, this option may be specified more than once, in which case multiple signatures will be made\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIPCRPublicKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-public\-key=\fR\fB\fIPATH\fR\fR
+.RS 4
+A public key to use for signing PCR policies\&.
+.sp
+On the command line, this option may be specified more than once, similarly to the
+\fB\-\-pcr\-private\-key=\fR
+option\&. If not present, the public keys will be extracted from the private keys\&. On the command line, if present, this option must be specified the same number of times as the
+\fB\-\-pcr\-private\-key=\fR
+option\&.
+.sp
+Added in version 253\&.
+.RE
+.PP
+\fIPhases=\fR\fI\fILIST\fR\fR, \fB\-\-phases=\fR\fB\fILIST\fR\fR
+.RS 4
+A comma or space\-separated list of colon\-separated phase paths to sign a policy for\&. Each set of boot phase paths will be signed with the corresponding private key\&. If not present, the default of
+\fBsystemd-measure\fR(1)
+will be used\&.
+.sp
+On the command line, when this argument is present, it must appear the same number of times as the
+\fB\-\-pcr\-private\-key=\fR
+option\&.
+.sp
+Added in version 253\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Minimal invocation\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ ukify build \e
+      \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
+      \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
+      \-\-cmdline=\*(Aqquiet rw\*(Aq
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This creates an unsigned UKI
+\&./vmlinuz\&.unsigned\&.efi\&.
+.PP
+\fBExample\ \&2.\ \&All the bells and whistles\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ ukify build \e
+      \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
+      \-\-initrd=early_cpio \e
+      \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e
+      \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
+      uki\&.author\&.myimage,1,UKI for System,uki\&.author\&.myimage,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq \e
+      \-\-pcr\-private\-key=pcr\-private\-initrd\-key\&.pem \e
+      \-\-pcr\-public\-key=pcr\-public\-initrd\-key\&.pem \e
+      \-\-phases=\*(Aqenter\-initrd\*(Aq \e
+      \-\-pcr\-private\-key=pcr\-private\-system\-key\&.pem \e
+      \-\-pcr\-public\-key=pcr\-public\-system\-key\&.pem \e
+      \-\-phases=\*(Aqenter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit \e
+                enter\-initrd:leave\-initrd:sysinit:ready\*(Aq \e
+      \-\-pcr\-banks=sha384,sha512 \e
+      \-\-secureboot\-private\-key=sb\&.key \e
+      \-\-secureboot\-certificate=sb\&.cert \e
+      \-\-sign\-kernel \e
+      \-\-cmdline=\*(Aqquiet rw rhgb\*(Aq
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This creates a signed UKI
+\&./vmlinuz\&.signed\&.efi\&. The initrd section contains two concatenated parts,
+early_cpio
+and
+initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img\&. The policy embedded in the
+"\&.pcrsig"
+section will be signed for the initrd (the
+\fBenter\-initrd\fR
+phase) with the key
+pcr\-private\-initrd\-key\&.pem, and for the main system (phases
+\fBleave\-initrd\fR,
+\fBsysinit\fR,
+\fBready\fR) with the key
+pcr\-private\-system\-key\&.pem\&. The Linux binary and the resulting combined image will be signed with the SecureBoot key
+sb\&.key\&.
+.PP
+\fBExample\ \&3.\ \&All the bells and whistles, via a config file\fR
+.PP
+This is the same as the previous example, but this time the configuration is stored in a file:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ cat ukify\&.conf
+[UKI]
+Initrd=early_cpio
+Cmdline=quiet rw rhgb
+
+SecureBootPrivateKey=sb\&.key
+SecureBootCertificate=sb\&.cert
+SignKernel=yes
+PCRBanks=sha384,sha512
+
+[PCRSignature:initrd]
+PCRPrivateKey=pcr\-private\-initrd\-key\&.pem
+PCRPublicKey=pcr\-public\-initrd\-key\&.pem
+Phases=enter\-initrd
+
+[PCRSignature:system]
+PCRPrivateKey=pcr\-private\-system\-key\&.pem
+PCRPublicKey=pcr\-public\-system\-key\&.pem
+Phases=enter\-initrd:leave\-initrd
+       enter\-initrd:leave\-initrd:sysinit
+       enter\-initrd:leave\-initrd:sysinit:ready
+
+$ ukify \-c ukify\&.conf build \e
+        \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e
+        \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+One "initrd" (early_cpio) is specified in the config file, and the other initrd (initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img) is specified on the command line\&. This may be useful for example when the first initrd contains microcode for the CPU and does not need to be updated when the kernel version changes, unlike the actual initrd\&.
+.PP
+\fBExample\ \&4.\ \&Kernel command line auxiliary PE\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ukify build \e
+      \-\-secureboot\-private\-key=sb\&.key \e
+      \-\-secureboot\-certificate=sb\&.cert \e
+      \-\-cmdline=\*(Aqdebug\*(Aq \e
+      \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md
+      uki\&.addon\&.author,1,UKI Addon for System,uki\&.addon\&.author,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq
+      \-\-output=debug\&.cmdline
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+This creates a signed PE binary that contains the additional kernel command line parameter
+"debug"
+with SBAT metadata referring to the owner of the addon\&.
+.PP
+\fBExample\ \&5.\ \&Decide signing policy and create certificate and keys\fR
+.PP
+First, let\*(Aqs create an config file that specifies what signatures shall be made:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# cat >/etc/kernel/uki\&.conf <<EOF
+[UKI]
+SecureBootPrivateKey=/etc/kernel/secure\-boot\&.key\&.pem
+SecureBootCertificate=/etc/kernel/secure\-boot\&.cert\&.pem
+
+[PCRSignature:initrd]
+Phases=enter\-initrd
+PCRPrivateKey=/etc/kernel/pcr\-initrd\&.key\&.pem
+PCRPublicKey=/etc/kernel/pcr\-initrd\&.pub\&.pem
+
+[PCRSignature:system]
+Phases=enter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit
+       enter\-initrd:leave\-initrd:sysinit:ready
+PCRPrivateKey=/etc/kernel/pcr\-system\&.key\&.pem
+PCRPublicKey=/etc/kernel/pcr\-system\&.pub\&.pem
+EOF
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Next, we can generate the certificate and keys:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# ukify genkey \-\-config=/etc/kernel/uki\&.conf
+Writing SecureBoot private key to /etc/kernel/secure\-boot\&.key\&.pem
+Writing SecureBoot certificate to /etc/kernel/secure\-boot\&.cert\&.pem
+Writing private key for PCR signing to /etc/kernel/pcr\-initrd\&.key\&.pem
+Writing public key for PCR signing to /etc/kernel/pcr\-initrd\&.pub\&.pem
+Writing private key for PCR signing to /etc/kernel/pcr\-system\&.key\&.pem
+Writing public key for PCR signing to /etc/kernel/pcr\-system\&.pub\&.pem
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+(Both operations need to be done as root to allow write access to
+/etc/kernel/\&.)
+.PP
+Subsequent invocations using the config file (\fBukify build \-\-config=/etc/kernel/uki\&.conf\fR) will use this certificate and key files\&. Note that the
+\fBkernel-install\fR(8)
+plugin
+60\-ukify\&.install
+uses
+/etc/kernel/uki\&.conf
+by default, so after this file has been created, installations of kernels that create a UKI on the local machine using
+\fBkernel\-install\fR
+will perform signing using this config\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-stub\fR(7),
+\fBsystemd-boot\fR(7),
+\fBsystemd-measure\fR(1),
+\fBsystemd-pcrphase.service\fR(8)
+.SH "NOTES"
+.IP " 1." 4
+Unified Kernel Image (UKI)
+.RS 4
+\%https://uapi-group.org/specifications/specs/unified_kernel_image/
+.RE
+.IP " 2." 4
+Shim documentation
+.RS 4
+\%https://github.com/rhboot/shim/blob/main/SBAT.md
+.RE
diff --git a/upstream/mageia-cauldron/man1/uname.1 b/upstream/mageia-cauldron/man1/uname.1
new file mode 100644
index 00000000..06f4c8a0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uname.1
@@ -0,0 +1,64 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH UNAME "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+uname \- print system information
+.SH SYNOPSIS
+.B uname
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print certain system information.  With no OPTION, same as \fB\-s\fR.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+print all information, in the following order,
+except omit \fB\-p\fR and \fB\-i\fR if unknown:
+.TP
+\fB\-s\fR, \fB\-\-kernel\-name\fR
+print the kernel name
+.TP
+\fB\-n\fR, \fB\-\-nodename\fR
+print the network node hostname
+.TP
+\fB\-r\fR, \fB\-\-kernel\-release\fR
+print the kernel release
+.TP
+\fB\-v\fR, \fB\-\-kernel\-version\fR
+print the kernel version
+.TP
+\fB\-m\fR, \fB\-\-machine\fR
+print the machine hardware name
+.TP
+\fB\-p\fR, \fB\-\-processor\fR
+print the processor type (non\-portable)
+.TP
+\fB\-i\fR, \fB\-\-hardware\-platform\fR
+print the hardware platform (non\-portable)
+.TP
+\fB\-o\fR, \fB\-\-operating\-system\fR
+print the operating system
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBarch\fP(1), \fBuname\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/uname>
+.br
+or available locally via: info \(aq(coreutils) uname invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/unexpand.1 b/upstream/mageia-cauldron/man1/unexpand.1
new file mode 100644
index 00000000..6e62d2fb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unexpand.1
@@ -0,0 +1,57 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH UNEXPAND "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+unexpand \- convert spaces to tabs
+.SH SYNOPSIS
+.B unexpand
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Convert blanks in each FILE to tabs, writing to standard output.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+convert all blanks, instead of just initial blanks
+.TP
+\fB\-\-first\-only\fR
+convert only leading sequences of blanks (overrides \fB\-a\fR)
+.TP
+\fB\-t\fR, \fB\-\-tabs\fR=\fI\,N\/\fR
+have tabs N characters apart instead of 8 (enables \fB\-a\fR)
+.TP
+\fB\-t\fR, \fB\-\-tabs\fR=\fI\,LIST\/\fR
+use comma separated list of tab positions.
+The last specified position can be prefixed with '/'
+to specify a tab size to use after the last
+explicitly specified tab stop.  Also a prefix of '+'
+can be used to align remaining tab stops relative to
+the last specified tab stop instead of the first column
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBexpand\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/unexpand>
+.br
+or available locally via: info \(aq(coreutils) unexpand invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/unicode_start.1 b/upstream/mageia-cauldron/man1/unicode_start.1
new file mode 100644
index 00000000..d11c314b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unicode_start.1
@@ -0,0 +1,39 @@
+.\" @(#)unicode_start.1 1.0 010203 aeb
+.TH UNICODE_START 1 "3 Feb 2001" "kbd"
+.SH NAME
+unicode_start \- put keyboard and console in unicode mode
+.SH SYNOPSIS
+.B unicode_start
+.RI [ font " [" umap ]]
+.SH DESCRIPTION
+.IX "unicode_start command" "" "\fLunicode_start\fR command"
+.LP
+The
+.B unicode_start
+command will put the keyboard and console into Unicode (UTF-8) mode.
+.LP
+For the keyboard this means that one can attach 16-bit U+xxxx values
+to keyboard keys using
+.BR loadkeys (1),
+and have these appear as UTF-8 input to user programs.
+Also, that one can type hexadecimal Alt-xxxx using the numeric keypad,
+and again produce UTF-8.
+.LP
+For the console this means that the kernel expects UTF-8 output
+from user programs, and displays the output accordingly.
+.LP
+The parameter
+.I font
+is a font that is loaded. It should have a built-in Unicode map,
+or, if it hasn't, such a map can be given explicitly as second parameter.
+When no font was specified, the current font is kept.
+.SH NOTE
+Unicode mode is a parameter with a value per virtual console.
+However, usually the font and keymap is common to all consoles.
+.SH "SEE ALSO"
+.BR dumpkeys (1),
+.BR kbd_mode (1),
+.BR loadkeys (1),
+.BR unicode_stop (1),
+.BR utf-8 (7),
+.BR setfont (8)
diff --git a/upstream/mageia-cauldron/man1/unicode_stop.1 b/upstream/mageia-cauldron/man1/unicode_stop.1
new file mode 100644
index 00000000..7a6246f9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unicode_stop.1
@@ -0,0 +1,20 @@
+.\" @(#)unicode_stop.1 1.0 010203 aeb
+.TH UNICODE_STOP 1 "3 Feb 2001" "kbd"
+.SH NAME
+unicode_stop \- revert keyboard and console from unicode mode
+.SH SYNOPSIS
+.B unicode_stop
+.SH DESCRIPTION
+.IX "unicode_stop command" "" "\fLunicode_stop\fR command"
+.LP
+The
+.B unicode_stop
+command will more-or-less undo the effect of
+.BR unicode_start .
+It puts the keyboard in ASCII (XLATE) mode, and clears
+the console UTF-8 mode.
+.SH "SEE ALSO"
+.BR kbd_mode (1),
+.BR unicode_start (1),
+.BR utf-8 (7),
+.BR setfont (8)
diff --git a/upstream/mageia-cauldron/man1/uniq.1 b/upstream/mageia-cauldron/man1/uniq.1
new file mode 100644
index 00000000..32327b02
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uniq.1
@@ -0,0 +1,83 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH UNIQ "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+uniq \- report or omit repeated lines
+.SH SYNOPSIS
+.B uniq
+[\fI\,OPTION\/\fR]... [\fI\,INPUT \/\fR[\fI\,OUTPUT\/\fR]]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Filter adjacent matching lines from INPUT (or standard input),
+writing to OUTPUT (or standard output).
+.PP
+With no options, matching lines are merged to the first occurrence.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-c\fR, \fB\-\-count\fR
+prefix lines by the number of occurrences
+.TP
+\fB\-d\fR, \fB\-\-repeated\fR
+only print duplicate lines, one for each group
+.TP
+\fB\-D\fR
+print all duplicate lines
+.TP
+\fB\-\-all\-repeated\fR[=\fI\,METHOD\/\fR]
+like \fB\-D\fR, but allow separating groups
+with an empty line;
+METHOD={none(default),prepend,separate}
+.TP
+\fB\-f\fR, \fB\-\-skip\-fields\fR=\fI\,N\/\fR
+avoid comparing the first N fields
+.TP
+\fB\-\-group\fR[=\fI\,METHOD\/\fR]
+show all items, separating groups with an empty line;
+METHOD={separate(default),prepend,append,both}
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+ignore differences in case when comparing
+.TP
+\fB\-s\fR, \fB\-\-skip\-chars\fR=\fI\,N\/\fR
+avoid comparing the first N characters
+.TP
+\fB\-u\fR, \fB\-\-unique\fR
+only print unique lines
+.TP
+\fB\-z\fR, \fB\-\-zero\-terminated\fR
+line delimiter is NUL, not newline
+.TP
+\fB\-w\fR, \fB\-\-check\-chars\fR=\fI\,N\/\fR
+compare no more than N characters in lines
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+A field is a run of blanks (usually spaces and/or TABs), then non\-blank
+characters.  Fields are skipped before chars.
+.PP
+Note: 'uniq' does not detect repeated lines unless they are adjacent.
+You may want to sort the input first, or use 'sort \fB\-u\fR' without 'uniq'.
+.SH AUTHOR
+Written by Richard M. Stallman and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBcomm\fP(1), \fBjoin\fP(1), \fBsort\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/uniq>
+.br
+or available locally via: info \(aq(coreutils) uniq invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/unlink.1 b/upstream/mageia-cauldron/man1/unlink.1
new file mode 100644
index 00000000..e6479a2e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unlink.1
@@ -0,0 +1,39 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH UNLINK "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+unlink \- call the unlink function to remove the specified file
+.SH SYNOPSIS
+.B unlink
+\fI\,FILE\/\fR
+.br
+.B unlink
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Call the unlink function to remove the specified FILE.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Michael Stone.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBunlink\fP(2)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/unlink>
+.br
+or available locally via: info \(aq(coreutils) unlink invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/unshar.1 b/upstream/mageia-cauldron/man1/unshar.1
new file mode 100644
index 00000000..f0512a6e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unshar.1
@@ -0,0 +1,184 @@
+.de1 NOP
+.  it 1 an-trap
+.  if \\n[.$] \,\\$*\/
+..
+.ie t \
+.ds B-Font [CB]
+.ds I-Font [CI]
+.ds R-Font [CR]
+.el \
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+.TH unshar 1 "30 May 2015" "GNU sharutils (4.15.2)" "User Commands"
+.\"
+.\" DO NOT EDIT THIS FILE (in-mem file)
+.\"
+.\" It has been AutoGen-ed
+.\" From the definitions unshar-opts.def
+.\" and the template file agman-cmd.tpl
+.SH NAME
+\f\*[B-Font]unshar\fP
+\- unpack a shar archive
+.SH SYNOPSIS
+\f\*[B-Font]unshar\fP
+.\" Mixture of short (flag) options and long options
+[\f\*[B-Font]\-flags\f[]]
+[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
+[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
+[<file>...]
+.sp \n(Ppu
+.ne 2
+
+The operands that this program operates on may be specified either
+on the command line or read from standard input, one per line.
+In that input, leading and trailing white space is stripped,
+blank lines are ignored.
+Standard input may not be a terminal.
+.sp \n(Ppu
+.ne 2
+
+.SH "DESCRIPTION"
+Unshar scans the input files (typically email messages) looking for
+the start of a shell archive.  If no files are given, then standard
+input is processed instead.  It then passes each archive discovered
+through an invocation of the shell program to unpack it.
+.sp \n(Ppu
+.ne 2
+
+This program will perform its function for every file named on the command
+line or every file named in a list read from stdin.  The arguments or input
+names must be pre\-existing files.  The input list may contain comments,
+which are blank lines or lines beginning with a '#' character.
+.SH "OPTIONS"
+.TP
+.NOP \f\*[B-Font]\-d\f[] \f\*[I-Font]dir\f[], \f\*[B-Font]\-\-directory\f[]=\f\*[I-Font]dir\f[]
+unpack into the directory \fIdir\fP.
+.sp
+The input file names are relative to the current directory
+when the program was started.  This option tells \fBunshar\fP
+to insert a \fBcd <dir>\fP commad at the start of the
+\fBshar\fP text written to the shell.
+.TP
+.NOP \f\*[B-Font]\-c\f[], \f\*[B-Font]\-\-overwrite\f[]
+overwrite any pre-existing files.
+.sp
+This option is passed through as an option to the shar file.  Many
+shell archive scripts accept a \fB-c\fP argument to indicate that
+existing files should be overwritten.
+.TP
+.NOP \f\*[B-Font]\-f\f[], \f\*[B-Font]\-\-force\f[]
+This is an alias for the \fI--overwrite\fR option.
+.TP
+.NOP \f\*[B-Font]\-E\f[] \f\*[I-Font]split\-mark\f[], \f\*[B-Font]\-\-split\-at\f[]=\f\*[I-Font]split\-mark\f[]
+split input on \fBsplit-mark\fP lines.
+The default
+\f\*[I-Font]split\-mark\f[]
+for this option is:
+.ti +4
+ exit 0
+.sp
+With this option, \fBunshar\fP isolates each different shell archive
+from the others which have been placed in the same file, unpacking each
+in turn, from the beginning of the file to the end.  Its proper
+operation relies on the fact that many shar files are terminated by a
+readily identifiable string at the start of the last line.
+.sp
+For example, noticing that most `.signatures' have a double hyphen
+("--") on a line right before them, one can then sometimes use
+\fB--split-at=--\fP.  The signature will then be skipped, along with
+the headers of the following message.
+.TP
+.NOP \f\*[B-Font]\-e\f[], \f\*[B-Font]\-\-exit\-0\f[]
+split input on "exit 0" lines.
+This option must not appear in combination with any of the following options:
+split-at.
+.sp
+Most shell archives end with a line consisting of simply "exit 0".
+This option is equivalent to (and conflicts with)
+\fB--split-at="exit 0"\fP.
+.TP
+.NOP \f\*[B-Font]\-D\f[], \f\*[B-Font]\-\-debug\f[]
+debug the shell code.
+.sp
+"set \-x" will be emitted into the code the shell interprets.
+.TP
+.NOP \f\*[B-Font]\-h\f[], \f\*[B-Font]\-\-help\f[]
+Display usage information and exit.
+.TP
+.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
+Pass the extended usage information through a pager.
+.TP
+.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
+Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+The command will exit after updating the config file.
+.TP
+.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
+Load options from \fIcfgfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
+out of order.
+.TP
+.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]
+Output version of program and exit.  The default mode is `v', a simple
+version.  The `c' mode will print copyright information and `n' will
+print the full copyright notice.
+.PP
+.SH "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from configuration ("RC" or ".INI") file(s).
+The file "\fI$HOME/.sharrc\fP" will be used, if present.
+.SH "FILES"
+See \fBOPTION PRESETS\fP for configuration files.
+.SH "EXIT STATUS"
+One of the following exit values will be returned:
+.TP
+.NOP 0 " (EXIT_SUCCESS)"
+Successful program execution.
+.TP
+.NOP 1 " (EXIT_FAILURE)"
+There was an error in command usage.
+.TP
+.NOP 2 " (EXIT_POPEN_PROBLEM)"
+cannot spawn or write to a shell process
+.TP
+.NOP 3 " (EXIT_CANNOT_CREATE)"
+cannot create output file
+.TP
+.NOP 4 " (EXIT_BAD_DIRECTORY)"
+the working directory structure is invalid
+.TP
+.NOP 5 " (EXIT_NOMEM)"
+memory allocation failure
+.TP
+.NOP 6 " (EXIT_INVALID)"
+invalid input, does not contain a shar file
+.TP
+.NOP 66 " (EX_NOINPUT)"
+A specified configuration file could not be loaded.
+.TP
+.NOP 70 " (EX_SOFTWARE)"
+libopts had an internal operational error.  Please report
+it to autogen-users@lists.sourceforge.net.  Thank you.
+.PP
+.SH "SEE ALSO"
+shar(1)
+.SH AUTHORS
+The \fIshar\fP and \fIunshar\fP programs is the collective work of
+many authors.  Many people contributed by reporting problems,
+suggesting various improvements or submitting actual code.  A list of
+these people is in the \fITHANKS\fP file in the sharutils distribution.
+.SH "COPYRIGHT"
+Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
+This program is released under the terms of the GNU General Public License, version 3 or later.
+.SH BUGS
+Please put \fBsharutils\fP in the subject line for emailed bug
+reports.  It helps to spot the message.
+.sp \n(Ppu
+.ne 2
+
+Please send bug reports to: bug-gnu-utils@gnu.org
+.SH "NOTES"
+This manual page was \fIAutoGen\fP-erated from the \fBunshar\fP
+option definitions.
diff --git a/upstream/mageia-cauldron/man1/unzip.1 b/upstream/mageia-cauldron/man1/unzip.1
new file mode 100644
index 00000000..4d66073c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unzip.1
@@ -0,0 +1,1042 @@
+.\"  Copyright (c) 1990-2009 Info-ZIP.  All rights reserved.
+.\"
+.\"  See the accompanying file LICENSE, version 2009-Jan-02 or later
+.\"  (the contents of which are also included in unzip.h) for terms of use.
+.\"  If, for some reason, all these files are missing, the Info-ZIP license
+.\"  also may be found at:  ftp://ftp.info-zip.org/pub/infozip/license.html
+.\"
+.\" unzip.1 by Greg Roelofs, Fulvio Marino, Jim van Zandt and others.
+.\"
+.\" =========================================================================
+.\" define .EX/.EE (for multiline user-command examples; normal Courier font)
+.de EX
+.in +4n
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.fi
+.in -4n
+..
+.\" =========================================================================
+.TH UNZIP 1L "20 April 2009 (v6.0)" "Info-ZIP"
+.SH NAME
+unzip \- list, test and extract compressed files in a ZIP archive
+.PD
+.SH SYNOPSIS
+\fBunzip\fP [\fB\-Z\fP] [\fB\-cflptTuvz\fP[\fBabjnoqsCDKLMUVWX$/:^\fP]]
+\fIfile\fP[\fI.zip\fP] [\fIfile(s)\fP\ .\|.\|.]
+[\fB\-x\fP\ \fIxfile(s)\fP\ .\|.\|.] [\fB\-d\fP\ \fIexdir\fP]
+.PD
+.\" =========================================================================
+.SH DESCRIPTION
+\fIunzip\fP will list, test, or extract files from a ZIP archive, commonly
+found on MS-DOS systems.  The default behavior (with no options) is to extract
+into the current directory (and subdirectories below it) all files from the
+specified ZIP archive.  A companion program, \fIzip\fP(1L), creates ZIP
+archives; both programs are compatible with archives created by PKWARE's
+\fIPKZIP\fP and \fIPKUNZIP\fP for MS-DOS, but in many cases the program
+options or default behaviors differ.
+.PD
+.\" =========================================================================
+.SH ARGUMENTS
+.TP
+.IR file [ .zip ]
+Path of the ZIP archive(s).  If the file specification is a wildcard,
+each matching file is processed in an order determined by the operating
+system (or file system).  Only the filename can be a wildcard; the path
+itself cannot.  Wildcard expressions are similar to those supported in
+commonly used Unix shells (\fIsh\fP, \fIksh\fP, \fIcsh\fP) and may contain:
+.RS
+.IP *
+matches a sequence of 0 or more characters
+.IP ?
+matches exactly 1 character
+.IP [.\|.\|.]
+matches any single character found inside the brackets; ranges are specified
+by a beginning character, a hyphen, and an ending character.  If an exclamation
+point or a caret (`!' or `^') follows the left bracket, then the range of
+characters within the brackets is complemented (that is, anything \fIexcept\fP
+the characters inside the brackets is considered a match).  To specify a
+verbatim left bracket, the three-character sequence ``[[]'' has to be used.
+.RE
+.IP
+(Be sure to quote any character that might otherwise be interpreted or
+modified by the operating system, particularly under Unix and VMS.)  If no
+matches are found, the specification is assumed to be a literal filename;
+and if that also fails, the suffix \fC.zip\fR is appended.  Note that
+self-extracting ZIP files are supported, as with any other ZIP archive;
+just specify the \fC.exe\fR suffix (if any) explicitly.
+.IP [\fIfile(s)\fP]
+An optional list of archive members to be processed, separated by spaces.
+(VMS versions compiled with VMSCLI defined must delimit files with commas
+instead.  See \fB\-v\fP in \fBOPTIONS\fP below.)
+Regular expressions (wildcards) may be used to match multiple members; see
+above.  Again, be sure to quote expressions that would otherwise be expanded
+or modified by the operating system.
+.IP [\fB\-x\fP\ \fIxfile(s)\fP]
+An optional list of archive members to be excluded from processing.
+Since wildcard characters normally match (`/') directory separators
+(for exceptions see the option \fB\-W\fP), this option may be used
+to exclude any files that are in subdirectories.  For
+example, ``\fCunzip foo *.[ch] -x */*\fR'' would extract all C source files
+in the main directory, but none in any subdirectories.  Without the \fB\-x\fP
+option, all C source files in all directories within the zipfile would be
+extracted.
+.IP [\fB\-d\fP\ \fIexdir\fP]
+An optional directory to which to extract files.  By default, all files
+and subdirectories are recreated in the current directory; the \fB\-d\fP
+option allows extraction in an arbitrary directory (always assuming one
+has permission to write to the directory).  This option need not appear
+at the end of the command line; it is also accepted before the zipfile
+specification (with the normal options), immediately after the zipfile
+specification, or between the \fIfile(s)\fP and the \fB\-x\fP option.
+The option and directory may be concatenated without any white space
+between them, but note that this may cause normal shell behavior to be
+suppressed.  In particular, ``\fC\-d\ ~\fR'' (tilde) is expanded by Unix
+C shells into the name of the user's home directory, but ``\fC\-d~\fR''
+is treated as a literal subdirectory ``\fB~\fP'' of the current directory.
+.\" =========================================================================
+.SH OPTIONS
+Note that, in order to support obsolescent hardware, \fIunzip\fP's usage
+screen is limited to 22 or 23 lines and should therefore be considered
+only a reminder of the basic \fIunzip\fP syntax rather than an exhaustive
+list of all possible flags.  The exhaustive list follows:
+.TP
+.B \-Z
+\fIzipinfo\fP(1L) mode.  If the first option on the command line is \fB\-Z\fP,
+the remaining options are taken to be \fIzipinfo\fP(1L) options.  See the
+appropriate manual page for a description of these options.
+.TP
+.B \-A
+[OS/2, Unix DLL] print extended help for the DLL's programming interface (API).
+.TP
+.B \-c
+extract files to stdout/screen (``CRT'').  This option is similar to the
+\fB\-p\fP option except that the name of each file is printed as it is
+extracted, the \fB\-a\fP option is allowed, and ASCII-EBCDIC conversion
+is automatically performed if appropriate.  This option is not listed in
+the \fIunzip\fP usage screen.
+.TP
+.B \-f
+freshen existing files, i.e., extract only those files that
+already exist on disk and that are newer than the disk copies.  By
+default \fIunzip\fP queries before overwriting, but the \fB\-o\fP option
+may be used to suppress the queries.  Note that under many operating systems,
+the TZ (timezone) environment variable must be set correctly in order for
+\fB\-f\fP and \fB\-u\fP to work properly (under Unix the variable is usually
+set automatically).  The reasons for this are somewhat subtle but
+have to do with the differences between DOS-format file times (always local
+time) and Unix-format times (always in GMT/UTC) and the necessity to compare
+the two.  A typical TZ value is ``PST8PDT'' (US Pacific time with automatic
+adjustment for Daylight Savings Time or ``summer time'').
+.TP
+.B \-l
+list archive files (short format).  The names, uncompressed file sizes and
+modification dates and times of the specified files are printed, along
+with totals for all files specified.  If UnZip was compiled with OS2_EAS
+defined, the \fB\-l\fP option also lists columns for the sizes of stored
+OS/2 extended attributes (EAs) and OS/2 access control lists (ACLs).  In
+addition, the zipfile comment and individual file comments (if any) are
+displayed.  If a file was archived from a single-case file system (for
+example, the old MS-DOS FAT file system) and the \fB\-L\fP option was given,
+the filename is converted to lowercase and is prefixed with a caret (^).
+.TP
+.B \-p
+extract files to pipe (stdout).  Nothing but the file data is sent to
+stdout, and the files are always extracted in binary format, just as they
+are stored (no conversions).
+.TP
+.B \-t
+test archive files.  This option extracts each specified file in memory
+and compares the CRC (cyclic redundancy check, an enhanced checksum) of
+the expanded file with the original file's stored CRC value.
+.TP
+.B \-T
+[most OSes] set the timestamp on the archive(s) to that of the newest file
+in each one.  This corresponds to \fIzip\fP's \fB\-go\fP option except that
+it can be used on wildcard zipfiles (e.g., ``\fCunzip \-T \e*.zip\fR'') and
+is much faster.
+.TP
+.B \-u
+update existing files and create new ones if needed.  This option performs
+the same function as the \fB\-f\fP option, extracting (with query) files
+that are newer than those with the same name on disk, and in addition it
+extracts those files that do not already exist on disk.  See \fB\-f\fP
+above for information on setting the timezone properly.
+.TP
+.B \-v
+list archive files (verbose format) or show diagnostic version info.
+This option has evolved and now behaves as both an option and a modifier.
+As an option it has two purposes:  when a zipfile is specified with no
+other options, \fB\-v\fP lists archive files verbosely, adding to the
+basic \fB\-l\fP info the compression method, compressed size,
+compression ratio and 32-bit CRC.  In contrast to most of the competing
+utilities, \fIunzip\fP removes the 12 additional header bytes of
+encrypted entries from the compressed size numbers.  Therefore,
+compressed size and compression ratio figures are independent of the entry's
+encryption status and show the correct compression performance.  (The complete
+size of the encrypted compressed data stream for zipfile entries is reported
+by the more verbose \fIzipinfo\fP(1L) reports, see the separate manual.)
+When no zipfile is specified (that is, the complete command is simply
+``\fCunzip \-v\fR''), a diagnostic screen is printed.  In addition to
+the normal header with release date and version, \fIunzip\fP lists the
+home Info-ZIP ftp site and where to find a list of other ftp and non-ftp
+sites; the target operating system for which it was compiled, as well
+as (possibly) the hardware on which it was compiled, the compiler and
+version used, and the compilation date; any special compilation options
+that might affect the program's operation (see also \fBDECRYPTION\fP below);
+and any options stored in environment variables that might do the same
+(see \fBENVIRONMENT OPTIONS\fP below).  As a modifier it works in
+conjunction with other options (e.g., \fB\-t\fP) to produce more
+verbose or debugging output; this is not yet fully implemented
+but will be in future releases.
+.TP
+.B \-z
+display only the archive comment.
+.PD
+.\" =========================================================================
+.SH MODIFIERS
+.TP
+.B \-a
+convert text files.  Ordinarily all files are extracted exactly as they
+are stored (as ``binary'' files).  The \fB\-a\fP option causes files identified
+by \fIzip\fP as text files (those with the `t' label in \fIzipinfo\fP
+listings, rather than `b') to be automatically extracted as such, converting
+line endings, end-of-file characters and the character set itself as necessary.
+(For example, Unix files use line feeds (LFs) for end-of-line (EOL) and
+have no end-of-file (EOF) marker; Macintoshes use carriage returns (CRs)
+for EOLs; and most PC operating systems use CR+LF for EOLs and control-Z for
+EOF.  In addition, IBM mainframes and the Michigan Terminal System use EBCDIC
+rather than the more common ASCII character set, and NT supports Unicode.)
+Note that \fIzip\fP's identification of text files is by no means perfect; some
+``text'' files may actually be binary and vice versa.  \fIunzip\fP therefore
+prints ``\fC[text]\fR'' or ``\fC[binary]\fR'' as a visual check for each file
+it extracts when using the \fB\-a\fP option.  The \fB\-aa\fP option forces
+all files to be extracted as text, regardless of the supposed file type.
+On VMS, see also \fB\-S\fP.
+.TP
+.B \-b
+[general] treat all files as binary (no text conversions).  This is a shortcut
+for \fB\-\-\-a\fP.
+.TP
+.B \-b
+[Tandem] force the creation files with filecode type 180 ('C') when
+extracting Zip entries marked as "text". (On Tandem, \fB\-a\fP is enabled
+by default, see above).
+.TP
+.B \-b
+[VMS] auto-convert binary files (see \fB\-a\fP above) to fixed-length,
+512-byte record format.  Doubling the option (\fB\-bb\fP) forces all files
+to be extracted in this format. When extracting to standard output
+(\fB\-c\fP or \fB\-p\fP option in effect), the default conversion of text
+record delimiters is disabled for binary (\fB\-b\fP) resp. all (\fB\-bb\fP)
+files.
+.TP
+.B \-B
+[when compiled with UNIXBACKUP defined] save a backup copy of each
+overwritten file. The backup file is gets the name of the target file with
+a tilde and optionally a unique sequence number (up to 5 digits) appended.
+The sequence number is applied whenever another file with the original name
+plus tilde already exists.  When used together with the "overwrite all"
+option \fB\-o\fP, numbered backup files are never created. In this case,
+all backup files are named as the original file with an appended tilde,
+existing backup files are deleted without notice.
+This feature works similarly to the default behavior of \fIemacs\fP(1)
+in many locations.
+.IP
+Example: the old copy of ``\fCfoo\fR'' is renamed to ``\fCfoo~\fR''.
+.IP
+Warning: Users should be aware that the \fB-B\fP option does not prevent
+loss of existing data under all circumstances.  For example, when
+\fIunzip\fP is run in overwrite-all mode, an existing ``\fCfoo~\fR'' file
+is deleted before \fIunzip\fP attempts to rename ``\fCfoo\fR'' to
+``\fCfoo~\fR''.  When this rename attempt fails (because of a file locks,
+insufficient privileges, or ...), the extraction of ``\fCfoo~\fR'' gets
+cancelled, but the old backup file is already lost.  A similar scenario
+takes place when the sequence number range for numbered backup files gets
+exhausted (99999, or 65535 for 16-bit systems).  In this case, the backup
+file with the maximum sequence number is deleted and replaced by the new
+backup version without notice.
+.TP
+.B \-C
+use case-insensitive matching for the selection of archive entries
+from the command-line list of extract selection patterns.
+\fIunzip\fP's philosophy is ``you get what you ask for'' (this is
+also responsible for the \fB\-L\fP/\fB\-U\fP change; see the relevant
+options below).  Because some file systems are fully case-sensitive
+(notably those under the Unix operating system) and because
+both ZIP archives and \fIunzip\fP itself are portable across platforms,
+\fIunzip\fP's default behavior is to match both wildcard and literal
+filenames case-sensitively.  That is, specifying ``\fCmakefile\fR''
+on the command line will \fIonly\fP match ``makefile'' in the archive,
+not ``Makefile'' or ``MAKEFILE'' (and similarly for wildcard specifications).
+Since this does not correspond to the behavior of many other
+operating/file systems (for example, OS/2 HPFS, which preserves
+mixed case but is not sensitive to it), the \fB\-C\fP option may be
+used to force all filename matches to be case-insensitive.  In the
+example above, all three files would then match ``\fCmakefile\fR''
+(or ``\fCmake*\fR'', or similar).  The \fB\-C\fP option affects
+file specs in both the normal file list and the excluded-file list (xlist).
+.IP
+Please note that the \fB\-C\fP option does neither affect the search for
+the zipfile(s) nor the matching of archive entries to existing files on
+the extraction path.  On a case-sensitive file system, \fIunzip\fP will
+never try to overwrite a file ``FOO'' when extracting an entry ``foo''!
+.TP
+.B \-D
+skip restoration of timestamps for extracted items.  Normally, \fIunzip\fP
+tries to restore all meta-information for extracted items that are supplied
+in the Zip archive (and do not require privileges or impose a security risk).
+By specifying \fB\-D\fP, \fIunzip\fP is told to suppress restoration of
+timestamps for directories explicitly created from Zip archive entries.
+This option only applies to ports that support setting timestamps for
+directories (currently ATheOS, BeOS, MacOS, OS/2, Unix, VMS, Win32, for other
+\fIunzip\fP ports, \fB\-D\fP has no effect).
+The duplicated option \fB\-DD\fP forces suppression of timestamp restoration
+for all extracted entries (files and directories).  This option results in
+setting the timestamps for all extracted entries to the current time.
+.IP
+On VMS, the default setting for this option is \fB\-D\fP for consistency
+with the behaviour of BACKUP: file timestamps are restored, timestamps of
+extracted directories are left at the current time.  To enable restoration
+of directory timestamps, the negated option \fB\--D\fP should be specified.
+On VMS, the option \fB\-D\fP disables timestamp restoration for all extracted
+Zip archive items.  (Here, a single \fB\-D\fP on the command line combines
+with the default \fB\-D\fP to do what an explicit \fB\-DD\fP does on other
+systems.)
+.TP
+.B \-E
+[MacOS only] display contents of MacOS extra field during restore operation.
+.TP
+.B \-F
+[Acorn only] suppress removal of NFS filetype extension from stored filenames.
+.TP
+.B \-F
+[non-Acorn systems supporting long filenames with embedded commas,
+and only if compiled with ACORN_FTYPE_NFS defined] translate
+filetype information from ACORN RISC OS extra field blocks into a
+NFS filetype extension and append it to the names of the extracted files.
+(When the stored filename appears to already have an appended NFS filetype
+extension, it is replaced by the info from the extra field.)
+.TP
+.B \-i
+[MacOS only] ignore filenames stored in MacOS extra fields. Instead, the
+most compatible filename stored in the generic part of the entry's header
+is used.
+.TP
+.B \-j
+junk paths.  The archive's directory structure is not recreated; all files
+are deposited in the extraction directory (by default, the current one).
+.TP
+.B \-J
+[BeOS only] junk file attributes.  The file's BeOS file attributes are not
+restored, just the file's data.
+.TP
+.B \-J
+[MacOS only] ignore MacOS extra fields.  All Macintosh specific info
+is skipped. Data-fork and resource-fork are restored as separate files.
+.TP
+.B \-K
+[AtheOS, BeOS, Unix only] retain SUID/SGID/Tacky file attributes.  Without
+this flag, these attribute bits are cleared for security reasons.
+.TP
+.B \-L
+convert to lowercase any filename originating on an uppercase-only operating
+system or file system.  (This was \fIunzip\fP's default behavior in releases
+prior to 5.11; the new default behavior is identical to the old behavior with
+the \fB\-U\fP option, which is now obsolete and will be removed in a future
+release.)  Depending on the archiver, files archived under single-case
+file systems (VMS, old MS-DOS FAT, etc.) may be stored as all-uppercase names;
+this can be ugly or inconvenient when extracting to a case-preserving
+file system such as OS/2 HPFS or a case-sensitive one such as under
+Unix.  By default \fIunzip\fP lists and extracts such filenames exactly as
+they're stored (excepting truncation, conversion of unsupported characters,
+etc.); this option causes the names of all files from certain systems to be
+converted to lowercase.  The \fB\-LL\fP option forces conversion of every
+filename to lowercase, regardless of the originating file system.
+.TP
+.B \-M
+pipe all output through an internal pager similar to the Unix \fImore\fP(1)
+command.  At the end of a screenful of output, \fIunzip\fP pauses with a
+``\-\-More\-\-'' prompt; the next screenful may be viewed by pressing the
+Enter (Return) key or the space bar.  \fIunzip\fP can be terminated by
+pressing the ``q'' key and, on some systems, the Enter/Return key.  Unlike
+Unix \fImore\fP(1), there is no forward-searching or editing capability.
+Also, \fIunzip\fP doesn't notice if long lines wrap at the edge of the screen,
+effectively resulting in the printing of two or more lines and the likelihood
+that some text will scroll off the top of the screen before being viewed.
+On some systems the number of available lines on the screen is not detected,
+in which case \fIunzip\fP assumes the height is 24 lines.
+.TP
+.B \-n
+never overwrite existing files.  If a file already exists, skip the extraction
+of that file without prompting.  By default \fIunzip\fP queries before
+extracting any file that already exists; the user may choose to overwrite
+only the current file, overwrite all files, skip extraction of the current
+file, skip extraction of all existing files, or rename the current file.
+.TP
+.B \-N
+[Amiga] extract file comments as Amiga filenotes.  File comments are created
+with the \-c option of \fIzip\fP(1L), or with the \-N option of the Amiga port
+of \fIzip\fP(1L), which stores filenotes as comments.
+.TP
+.B \-o
+overwrite existing files without prompting.  This is a dangerous option, so
+use it with care.  (It is often used with \fB\-f\fP, however, and is the only
+way to overwrite directory EAs under OS/2.)
+.IP \fB\-P\fP\ \fIpassword\fP
+use \fIpassword\fP to decrypt encrypted zipfile entries (if any).  \fBTHIS IS
+INSECURE!\fP  Many multi-user operating systems provide ways for any user to
+see the current command line of any other user; even on stand-alone systems
+there is always the threat of over-the-shoulder peeking.  Storing the plaintext
+password as part of a command line in an automated script is even worse.
+Whenever possible, use the non-echoing, interactive prompt to enter passwords.
+(And where security is truly important, use strong encryption such as Pretty
+Good Privacy instead of the relatively weak encryption provided by standard
+zipfile utilities.)
+.TP
+.B \-q
+perform operations quietly (\fB\-qq\fP = even quieter).  Ordinarily \fIunzip\fP
+prints the names of the files it's extracting or testing, the extraction
+methods, any file or zipfile comments that may be stored in the archive,
+and possibly a summary when finished with each archive.  The \fB\-q\fP[\fBq\fP]
+options suppress the printing of some or all of these messages.
+.TP
+.B \-s
+[OS/2, NT, MS-DOS] convert spaces in filenames to underscores.  Since all PC
+operating systems allow spaces in filenames, \fIunzip\fP by default extracts
+filenames with spaces intact (e.g., ``\fCEA\ DATA.\ SF\fR'').  This can be
+awkward, however, since MS-DOS in particular does not gracefully support
+spaces in filenames.  Conversion of spaces to underscores can eliminate the
+awkwardness in some cases.
+.TP
+.B \-S
+[VMS] convert text files (\fB\-a\fP, \fB\-aa\fP) into Stream_LF record format,
+instead of the text-file default, variable-length record format.
+(Stream_LF is the default record format of VMS \fIunzip\fP. It is applied
+unless conversion (\fB\-a\fP, \fB\-aa\fP and/or \fB\-b\fP, \fB\-bb\fP) is
+requested or a VMS-specific entry is processed.)
+.TP
+.B \-U
+[UNICODE_SUPPORT only] modify or disable UTF-8 handling.
+When UNICODE_SUPPORT is available, the option \fB\-U\fP forces \fIunzip\fP
+to escape all non-ASCII characters from UTF-8 coded filenames as ``#Uxxxx''
+(for UCS-2 characters, or ``#Lxxxxxx'' for unicode codepoints needing 3
+octets).  This option is mainly provided for debugging purpose when the
+fairly new UTF-8 support is suspected to mangle up extracted filenames.
+.IP
+The option \fB\-UU\fP allows to entirely disable the recognition of UTF-8
+encoded filenames.  The handling of filename codings within \fIunzip\fP falls
+back to the behaviour of previous versions.
+.IP
+[old, obsolete usage] leave filenames uppercase if
+created under MS-DOS, VMS, etc.  See \fB\-L\fP above.
+.TP
+.B \-V
+retain (VMS) file version numbers.  VMS files can be stored with a version
+number, in the format \fCfile.ext;##\fR.  By default the ``\fC;##\fR'' version
+numbers are stripped, but this option allows them to be retained.  (On
+file systems that limit filenames to particularly short lengths, the version
+numbers may be truncated or stripped regardless of this option.)
+.TP
+.B \-W
+[only when WILD_STOP_AT_DIR compile-time option enabled]
+modifies the pattern matching routine so that both `?' (single-char wildcard)
+and `*' (multi-char wildcard) do not match the directory separator character
+`/'.  (The two-character sequence ``**'' acts as a multi-char wildcard that
+includes the directory separator in its matched characters.)  Examples:
+.PP
+.EX
+    "*.c" matches "foo.c" but not "mydir/foo.c"
+    "**.c" matches both "foo.c" and "mydir/foo.c"
+    "*/*.c" matches "bar/foo.c" but not "baz/bar/foo.c"
+    "??*/*" matches "ab/foo" and "abc/foo"
+            but not "a/foo" or "a/b/foo"
+.EE
+.IP
+This modified behaviour is equivalent to the pattern matching style
+used by the shells of some of UnZip's supported target OSs (one
+example is Acorn RISC OS).  This option may not be available on systems
+where the Zip archive's internal directory separator character `/' is
+allowed as regular character in native operating system filenames.
+(Currently, UnZip uses the same pattern matching rules for both wildcard
+zipfile specifications and zip entry selection patterns in most ports.
+For systems allowing `/' as regular filename character, the -W option
+would not work as expected on a wildcard zipfile specification.)
+.TP
+.B \-X
+[VMS, Unix, OS/2, NT, Tandem] restore owner/protection info (UICs and ACL
+entries) under VMS, or user and group info (UID/GID) under Unix, or access
+control lists (ACLs) under certain network-enabled versions of OS/2
+(Warp Server with IBM LAN Server/Requester 3.0 to 5.0; Warp Connect with
+IBM Peer 1.0), or security ACLs under Windows NT.  In most cases this will
+require special system privileges, and doubling the option (\fB\-XX\fP)
+under NT instructs \fIunzip\fP to use privileges for extraction; but under
+Unix, for example, a user who belongs to several groups can restore files
+owned by any of those groups, as long as the user IDs match his or her own.
+Note that ordinary file attributes are always restored--this option applies
+only to optional, extra ownership info available on some operating systems.
+[NT's access control lists do not appear to be especially compatible with
+OS/2's, so no attempt is made at cross-platform portability of access
+privileges.  It is not clear under what conditions this would ever be
+useful anyway.]
+.TP
+.B \-Y
+[VMS] treat archived file name endings of ``.nnn'' (where ``nnn'' is a
+decimal  number) as if they were VMS version numbers (``;nnn'').
+(The default is to treat them as file types.)  Example:
+.EX
+     "a.b.3" -> "a.b;3".
+.EE
+.TP
+.B \-$
+.\" Amiga support possible eventually, but not yet
+[MS-DOS, OS/2, NT] restore the volume label if the extraction medium is
+removable (e.g., a diskette).  Doubling the option (\fB\-$$\fP) allows fixed
+media (hard disks) to be labeled as well.  By default, volume labels are
+ignored.
+.IP \fB\-/\fP\ \fIextensions\fP
+[Acorn only] overrides the extension list supplied by Unzip$Ext environment
+variable. During extraction, filename extensions that match one of the items
+in this extension list are swapped in front of the base name of the extracted
+file.
+.TP
+.B \-:
+[all but Acorn, VM/CMS, MVS, Tandem] allows to extract archive members into
+locations outside of the current `` extraction root folder''. For security
+reasons, \fIunzip\fP normally removes ``parent dir'' path components
+(``../'') from the names of extracted file.  This safety feature (new for
+version 5.50) prevents \fIunzip\fP from accidentally writing files to
+``sensitive'' areas outside the active extraction folder tree head.  The
+\fB\-:\fP option lets \fIunzip\fP switch back to its previous, more liberal
+behaviour, to allow exact extraction of (older) archives that used ``../''
+components to create multiple directory trees at the level of the current
+extraction folder.  This option does not enable writing explicitly to the
+root directory (``/'').  To achieve this, it is necessary to set the
+extraction target folder to root (e.g. \fB\-d / \fP).  However, when the
+\fB\-:\fP option is specified, it is still possible to implicitly write to
+the root directory by specifying enough ``../'' path components within the
+zip archive.
+Use this option with extreme caution.
+.TP
+.B \-^
+[Unix only] allow control characters in names of extracted ZIP archive
+entries.  On Unix, a file name may contain any (8-bit) character code with
+the two exception '/' (directory delimiter) and NUL (0x00, the C string
+termination indicator), unless the specific file system has more
+restrictive conventions.  Generally, this allows to embed ASCII control
+characters (or even sophisticated control sequences) in file names, at least
+on 'native' Unix file systems.  However, it may be highly suspicious to
+make use of this Unix "feature".  Embedded control characters in file names
+might have nasty side effects when displayed on screen by some listing code
+without sufficient filtering.  And, for ordinary users, it may be difficult
+to handle such file names (e.g. when trying to specify it for open, copy,
+move, or delete operations).  Therefore, \fIunzip\fP applies a filter by
+default that removes potentially dangerous control characters from the
+extracted file names. The \fB-^\fP option allows to override this filter
+in the rare case that embedded filename control characters are to be
+intentionally restored.
+.TP
+.B \-2
+[VMS] force unconditionally conversion of file names to ODS2-compatible
+names.  The default is to exploit the destination file system, preserving
+case and extended file name characters on an ODS5 destination file system;
+and applying the ODS2-compatibility file name filtering on an ODS2 destination
+file system.
+.PD
+.\" =========================================================================
+.SH "ENVIRONMENT OPTIONS"
+\fIunzip\fP's default behavior may be modified via options placed in
+an environment variable.  This can be done with any option, but it
+is probably most useful with the \fB\-a\fP, \fB\-L\fP, \fB\-C\fP, \fB\-q\fP,
+\fB\-o\fP, or \fB\-n\fP modifiers:  make \fIunzip\fP auto-convert text
+files by default, make it convert filenames from uppercase systems to
+lowercase, make it match names case-insensitively, make it quieter,
+or make it always overwrite or never overwrite files as it extracts
+them.  For example, to make \fIunzip\fP act as quietly as possible, only
+reporting errors, one would use one of the following commands:
+.TP
+  Unix Bourne shell:
+UNZIP=\-qq; export UNZIP
+.TP
+  Unix C shell:
+setenv UNZIP \-qq
+.TP
+  OS/2 or MS-DOS:
+set UNZIP=\-qq
+.TP
+  VMS (quotes for \fIlowercase\fP):
+define UNZIP_OPTS "\-qq"
+.PP
+Environment options are, in effect, considered to be just like any other
+command-line options, except that they are effectively the first options
+on the command line.  To override an environment option, one may use the
+``minus operator'' to remove it.  For instance, to override one of the
+quiet-flags in the example above, use the command
+.PP
+.EX
+unzip \-\-q[\fIother options\fP] zipfile
+.EE
+.PP
+The first hyphen is the normal
+switch character, and the second is a minus sign, acting on the q option.
+Thus the effect here is to cancel one quantum of quietness.  To cancel
+both quiet flags, two (or more) minuses may be used:
+.PP
+.EX
+unzip \-t\-\-q zipfile
+unzip \-\-\-qt zipfile
+.EE
+.PP
+(the two are equivalent).  This may seem awkward
+or confusing, but it is reasonably intuitive:  just ignore the first
+hyphen and go from there.  It is also consistent with the behavior of
+Unix \fInice\fP(1).
+.PP
+As suggested by the examples above, the default variable names are UNZIP_OPTS
+for VMS (where the symbol used to install \fIunzip\fP as a foreign command
+would otherwise be confused with the environment variable), and UNZIP
+for all other operating systems.  For compatibility with \fIzip\fP(1L),
+UNZIPOPT is also accepted (don't ask).  If both UNZIP and UNZIPOPT
+are defined, however, UNZIP takes precedence.  \fIunzip\fP's diagnostic
+option (\fB\-v\fP with no zipfile name) can be used to check the values
+of all four possible \fIunzip\fP and \fIzipinfo\fP environment variables.
+.PP
+The timezone variable (TZ) should be set according to the local timezone
+in order for the \fB\-f\fP and \fB\-u\fP to operate correctly.  See the
+description of \fB\-f\fP above for details.  This variable may also be
+necessary to get timestamps of extracted files to be set correctly.
+The WIN32 (Win9x/ME/NT4/2K/XP/2K3) port of \fIunzip\fP gets the timezone
+configuration from the registry, assuming it is correctly set in the
+Control Panel.  The TZ variable is ignored for this port.
+.PD
+.\" =========================================================================
+.SH DECRYPTION
+Encrypted archives are fully supported by Info-ZIP software, but due to
+United States export restrictions, de-/encryption support might be disabled
+in your compiled binary.  However, since spring 2000, US export restrictions
+have been liberated, and our source archives do now include full crypt code.
+In case you need binary distributions with crypt support enabled, see the
+file ``WHERE'' in any Info-ZIP source or binary distribution for locations
+both inside and outside the US.
+.PP
+Some compiled versions of \fIunzip\fP may not support decryption.
+To check a version for crypt support, either attempt to test or extract
+an encrypted archive, or else check \fIunzip\fP's diagnostic
+screen (see the \fB\-v\fP option above) for ``\fC[decryption]\fR'' as one
+of the special compilation options.
+.PP
+As noted above, the \fB\-P\fP option may be used to supply a password on
+the command line, but at a cost in security.  The preferred decryption
+method is simply to extract normally; if a zipfile member is encrypted,
+\fIunzip\fP will prompt for the password without echoing what is typed.
+\fIunzip\fP continues to use the same password as long as it appears to be
+valid, by testing a 12-byte header on each file.  The correct password will
+always check out against the header, but there is a 1-in-256 chance that an
+incorrect password will as well.  (This is a security feature of the PKWARE
+zipfile format; it helps prevent brute-force attacks that might otherwise
+gain a large speed advantage by testing only the header.)  In the case that
+an incorrect password is given but it passes the header test anyway, either
+an incorrect CRC will be generated for the extracted data or else \fIunzip\fP
+will fail during the extraction because the ``decrypted'' bytes do not
+constitute a valid compressed data stream.
+.PP
+If the first password fails the header check on some file, \fIunzip\fP will
+prompt for another password, and so on until all files are extracted.  If
+a password is not known, entering a null password (that is, just a carriage
+return or ``Enter'') is taken as a signal to skip all further prompting.
+Only unencrypted files in the archive(s) will thereafter be extracted.  (In
+fact, that's not quite true; older versions of \fIzip\fP(1L) and
+\fIzipcloak\fP(1L) allowed null passwords, so \fIunzip\fP checks each encrypted
+file to see if the null password works.  This may result in ``false positives''
+and extraction errors, as noted above.)
+.PP
+Archives encrypted with 8-bit passwords (for example, passwords with accented
+European characters) may not be portable across systems and/or other
+archivers.  This problem stems from the use of multiple encoding methods for
+such characters, including Latin-1 (ISO 8859-1) and OEM code page 850.
+DOS \fIPKZIP\fP 2.04g uses the OEM code page; Windows \fIPKZIP\fP 2.50
+uses Latin-1 (and is therefore incompatible with DOS \fIPKZIP\fP); Info-ZIP
+uses the OEM code page on DOS, OS/2 and Win3.x ports but ISO coding
+(Latin-1 etc.) everywhere else; and Nico Mak's \fIWinZip\fP 6.x does not
+allow 8-bit passwords at all.  \fIUnZip\fP 5.3 (or newer) attempts to use
+the default character set first (e.g., Latin-1), followed by the alternate
+one (e.g., OEM code page) to test passwords.  On EBCDIC systems, if both
+of these fail, EBCDIC encoding will be tested as a last resort.  (EBCDIC is
+not tested on non-EBCDIC systems, because there are no known archivers
+that encrypt using EBCDIC encoding.)  ISO character encodings other than
+Latin-1 are not supported.  The new addition of (partially) Unicode (resp.
+UTF-8) support in \fIUnZip\fP 6.0 has not yet been adapted to the encryption
+password handling in \fIunzip\fP.  On systems that use UTF-8 as native
+character encoding, \fIunzip\fP simply tries decryption with the native
+UTF-8 encoded password; the built-in attempts to check the password in
+translated encoding have not yet been adapted for UTF-8 support and
+will consequently fail.
+.PD
+.\" =========================================================================
+.SH EXAMPLES
+To use \fIunzip\fP to extract all members of the archive \fIletters.zip\fP
+into the current directory and subdirectories below it, creating any
+subdirectories as necessary:
+.PP
+.EX
+unzip letters
+.EE
+.PP
+To extract all members of \fIletters.zip\fP into the current directory only:
+.PP
+.EX
+unzip -j letters
+.EE
+.PP
+To test \fIletters.zip\fP, printing only a summary message indicating
+whether the archive is OK or not:
+.PP
+.EX
+unzip -tq letters
+.EE
+.PP
+To test \fIall\fP zipfiles in the current directory, printing only the
+summaries:
+.PP
+.EX
+unzip -tq \e*.zip
+.EE
+.PP
+(The backslash before the asterisk is only required if the shell expands
+wildcards, as in Unix; double quotes could have been used instead, as in
+the source examples below.)\ \ To extract to standard output all members of
+\fIletters.zip\fP whose names end in \fI.tex\fP, auto-converting to the
+local end-of-line convention and piping the output into \fImore\fP(1):
+.PP
+.EX
+unzip \-ca letters \e*.tex | more
+.EE
+.PP
+To extract the binary file \fIpaper1.dvi\fP to standard output and pipe it
+to a printing program:
+.PP
+.EX
+unzip \-p articles paper1.dvi | dvips
+.EE
+.PP
+To extract all FORTRAN and C source files--*.f, *.c, *.h, and Makefile--into
+the /tmp directory:
+.PP
+.EX
+unzip source.zip "*.[fch]" Makefile -d /tmp
+.EE
+.PP
+(the double quotes are necessary only in Unix and only if globbing is turned
+on).  To extract all FORTRAN and C source files, regardless of case (e.g.,
+both *.c and *.C, and any makefile, Makefile, MAKEFILE or similar):
+.PP
+.EX
+unzip \-C source.zip "*.[fch]" makefile -d /tmp
+.EE
+.PP
+To extract any such files but convert any uppercase MS-DOS or VMS names to
+lowercase and convert the line-endings of all of the files to the local
+standard (without respect to any files that might be marked ``binary''):
+.PP
+.EX
+unzip \-aaCL source.zip "*.[fch]" makefile -d /tmp
+.EE
+.PP
+To extract only newer versions of the files already in the current
+directory, without querying (NOTE:  be careful of unzipping in one timezone a
+zipfile created in another--ZIP archives other than those created by Zip 2.1
+or later contain no timezone information, and a ``newer'' file from an eastern
+timezone may, in fact, be older):
+.PP
+.EX
+unzip \-fo sources
+.EE
+.PP
+To extract newer versions of the files already in the current directory and
+to create any files not already there (same caveat as previous example):
+.PP
+.EX
+unzip \-uo sources
+.EE
+.PP
+To display a diagnostic screen showing which \fIunzip\fP and \fIzipinfo\fP
+options are stored in environment variables, whether decryption support was
+compiled in, the compiler with which \fIunzip\fP was compiled, etc.:
+.PP
+.EX
+unzip \-v
+.EE
+.PP
+In the last five examples, assume that UNZIP or UNZIP_OPTS is set to -q.
+To do a singly quiet listing:
+.PP
+.EX
+unzip \-l file.zip
+.EE
+.PP
+To do a doubly quiet listing:
+.PP
+.EX
+unzip \-ql file.zip
+.EE
+.PP
+(Note that the ``\fC.zip\fR'' is generally not necessary.)  To do a standard
+listing:
+.PP
+.EX
+unzip \-\-ql file.zip
+.EE
+or
+.EX
+unzip \-l\-q file.zip
+.EE
+or
+.EX
+unzip \-l\-\-q file.zip
+.EE
+\fR(Extra minuses in options don't hurt.)
+.PD
+.\" =========================================================================
+.SH TIPS
+The current maintainer, being a lazy sort, finds it very useful to define
+a pair of aliases:  \fCtt\fR for ``\fCunzip \-tq\fR'' and \fCii\fR for
+``\fCunzip \-Z\fR'' (or ``\fCzipinfo\fR'').  One may then simply type
+``\fCtt zipfile\fR'' to test an archive, something that is worth making a
+habit of doing.  With luck \fIunzip\fP will report ``\fCNo errors detected
+in compressed data of zipfile.zip\fR,'' after which one may breathe a sigh
+of relief.
+.PP
+The maintainer also finds it useful to set the UNZIP environment variable
+to ``\fC\-aL\fR'' and is tempted to add ``\fC\-C\fR'' as well.  His ZIPINFO
+variable is set to ``\fC\-z\fR''.
+.PD
+.\" =========================================================================
+.SH DIAGNOSTICS
+The exit status (or error level) approximates the exit codes defined by PKWARE
+and takes on the following values, except under VMS:
+.RS
+.IP 0
+normal; no errors or warnings detected.
+.IP 1
+one or more warning errors were encountered, but processing completed
+successfully anyway.  This includes zipfiles where one or more files
+was skipped due to unsupported compression method or encryption with an
+unknown password.
+.IP 2
+a generic error in the zipfile format was detected.  Processing may have
+completed successfully anyway; some broken zipfiles created by other
+archivers have simple work-arounds.
+.IP 3
+a severe error in the zipfile format was detected.  Processing probably
+failed immediately.
+.IP 4
+\fIunzip\fP was unable to allocate memory for one or more buffers during
+program initialization.
+.IP 5
+\fIunzip\fP was unable to allocate memory or unable to obtain a tty to read
+the decryption password(s).
+.IP 6
+\fIunzip\fP was unable to allocate memory during decompression to disk.
+.IP 7
+\fIunzip\fP was unable to allocate memory during in-memory decompression.
+.IP 8
+[currently not used]
+.IP 9
+the specified zipfiles were not found.
+.IP 10
+invalid options were specified on the command line.
+.IP 11
+no matching files were found.
+.IP 12
+invalid zip file with overlapped components (possible zip bomb).
+.IP 50
+the disk is (or was) full during extraction.
+.IP 51
+the end of the ZIP archive was encountered prematurely.
+.IP 80
+the user aborted \fIunzip\fP prematurely with control-C (or similar)
+.IP 81
+testing or extraction of one or more files failed due to unsupported
+compression methods or unsupported decryption.
+.IP 82
+no files were found due to bad decryption password(s).  (If even one file is
+successfully processed, however, the exit status is 1.)
+.RE
+.PP
+VMS interprets standard Unix (or PC) return values as other, scarier-looking
+things, so \fIunzip\fP instead maps them into VMS-style status codes.  The
+current mapping is as follows:   1 (success) for normal exit, 0x7fff0001
+for warning errors, and (0x7fff000? + 16*normal_unzip_exit_status) for all
+other errors, where the `?' is 2 (error) for \fIunzip\fP values 2, 9-11 and
+80-82, and 4 (fatal error) for the remaining ones (3-8, 50, 51).  In addition,
+there is a compilation option to expand upon this behavior:  defining
+RETURN_CODES results in a human-readable explanation of what the error
+status means.
+.PD
+.\" =========================================================================
+.SH BUGS
+Multi-part archives are not yet supported, except in conjunction with
+\fIzip\fP.  (All parts must be concatenated together in order, and then
+``\fCzip \-F\fR'' (for \fIzip 2.x\fP) or ``\fCzip \-FF\fR'' (for
+\fIzip 3.x\fP) must be performed on the concatenated archive in order to
+``fix'' it.  Also, \fIzip 3.0\fP and later can combine multi-part (split)
+archives into a combined single-file archive using ``\fCzip \-s\- inarchive
+-O outarchive\fR''.  See the \fIzip 3\fP manual page for more information.)
+This will definitely be corrected in the next major release.
+.PP
+Archives read from standard input are not yet supported, except with
+\fIfunzip\fP (and then only the first member of the archive can be extracted).
+.PP
+Archives encrypted with 8-bit passwords (e.g., passwords with accented
+European characters) may not be portable across systems and/or other
+archivers.  See the discussion in \fBDECRYPTION\fP above.
+.PP
+\fIunzip\fP's \fB\-M\fP (``more'') option tries to take into account automatic
+wrapping of long lines. However, the code may fail to detect the correct
+wrapping locations. First, TAB characters (and similar control sequences) are
+not taken into account, they are handled as ordinary printable characters.
+Second, depending on the actual system / OS port, \fIunzip\fP may not detect
+the true screen geometry but rather rely on "commonly used" default dimensions.
+The correct handling of tabs would require the implementation of a query for
+the actual tabulator setup on the output console.
+.PP
+Dates, times and permissions of stored directories are not restored except
+under Unix. (On Windows NT and successors, timestamps are now restored.)
+.PP
+[MS-DOS] When extracting or testing files from an archive on a defective
+floppy diskette, if the ``Fail'' option is chosen from DOS's ``Abort, Retry,
+Fail?'' message, older versions of \fIunzip\fP may hang the system, requiring
+a reboot.  This problem appears to be fixed, but control-C (or control-Break)
+can still be used to terminate \fIunzip\fP.
+.PP
+Under DEC Ultrix, \fIunzip\fP would sometimes fail on long zipfiles (bad CRC,
+not always reproducible).  This was apparently due either to a hardware bug
+(cache memory) or an operating system bug (improper handling of page faults?).
+Since Ultrix has been abandoned in favor of Digital Unix (OSF/1), this may not
+be an issue anymore.
+.PP
+[Unix] Unix special files such as FIFO buffers (named pipes), block devices
+and character devices are not restored even if they are somehow represented
+in the zipfile, nor are hard-linked files relinked.  Basically the only file
+types restored by \fIunzip\fP are regular files, directories and symbolic
+(soft) links.
+.PP
+[OS/2] Extended attributes for existing directories are only updated if the
+\fB\-o\fP (``overwrite all'') option is given.  This is a limitation of the
+operating system; because directories only have a creation time associated
+with them, \fIunzip\fP has no way to determine whether the stored attributes
+are newer or older than those on disk.  In practice this may mean a two-pass
+approach is required:  first unpack the archive normally (with or without
+freshening/updating existing files), then overwrite just the directory entries
+(e.g., ``\fCunzip -o foo */\fR'').
+.PP
+[VMS] When extracting to another directory, only the \fI[.foo]\fP syntax is
+accepted for the \fB\-d\fP option; the simple Unix \fIfoo\fP syntax is
+silently ignored (as is the less common VMS \fIfoo.dir\fP syntax).
+.PP
+[VMS] When the file being extracted already exists, \fIunzip\fP's query only
+allows skipping, overwriting or renaming; there should additionally be a
+choice for creating a new version of the file.  In fact, the ``overwrite''
+choice does create a new version; the old version is not overwritten or
+deleted.
+.PD
+.\" =========================================================================
+.SH "SEE ALSO"
+\fIfunzip\fP(1L), \fIzip\fP(1L), \fIzipcloak\fP(1L), \fIzipgrep\fP(1L),
+\fIzipinfo\fP(1L), \fIzipnote\fP(1L), \fIzipsplit\fP(1L)
+.PD
+.\" =========================================================================
+.SH URL
+The Info-ZIP home page is currently at
+.EX
+\fChttp://www.info-zip.org/pub/infozip/\fR
+.EE
+or
+.EX
+\fCftp://ftp.info-zip.org/pub/infozip/\fR .
+.EE
+.PD
+.\" =========================================================================
+.SH AUTHORS
+The primary Info-ZIP authors (current semi-active members of the Zip-Bugs
+workgroup) are:  Ed Gordon (Zip, general maintenance, shared code, Zip64,
+Win32, Unix, Unicode); Christian Spieler (UnZip maintenance coordination,
+VMS, MS-DOS, Win32, shared code, general Zip and UnZip integration and
+optimization); Onno van der Linden (Zip); Mike White (Win32, Windows GUI,
+Windows DLLs); Kai Uwe Rommel (OS/2, Win32); Steven M. Schweda (VMS, Unix,
+support of new features); Paul Kienitz (Amiga, Win32, Unicode); Chris
+Herborth (BeOS, QNX, Atari); Jonathan Hudson (SMS/QDOS); Sergio Monesi
+(Acorn RISC OS); Harald Denker (Atari, MVS); John Bush (Solaris, Amiga);
+Hunter Goatley (VMS, Info-ZIP Site maintenance); Steve Salisbury (Win32);
+Steve Miller (Windows CE GUI), Johnny Lee (MS-DOS, Win32, Zip64); and Dave
+Smith (Tandem NSK).
+.PP
+The following people were former members of the Info-ZIP development group
+and provided major contributions to key parts of the current code:
+Greg ``Cave Newt'' Roelofs (UnZip, unshrink decompression);
+Jean-loup Gailly (deflate compression);
+Mark Adler (inflate decompression, fUnZip).
+.PP
+The author of the original unzip code upon which Info-ZIP's was based
+is Samuel H. Smith; Carl Mascott did the first Unix port; and David P.
+Kirschbaum organized and led Info-ZIP in its early days with Keith Petersen
+hosting the original mailing list at WSMR-SimTel20.  The full list of
+contributors to UnZip has grown quite large; please refer to the CONTRIBS
+file in the UnZip source distribution for a relatively complete version.
+.PD
+.\" =========================================================================
+.SH VERSIONS
+.ta \w'vx.xxnn'u +\w'fall 1989'u+3n
+.PD 0
+.IP "v1.2\t15 Mar 89" \w'\t\t'u
+Samuel H. Smith
+.IP "v2.0\t\ 9 Sep 89"
+Samuel H. Smith
+.IP "v2.x\tfall 1989"
+many Usenet contributors
+.IP "v3.0\t\ 1 May 90"
+Info-ZIP (DPK, consolidator)
+.IP "v3.1\t15 Aug 90"
+Info-ZIP (DPK, consolidator)
+.IP "v4.0\t\ 1 Dec 90"
+Info-ZIP (GRR, maintainer)
+.IP "v4.1\t12 May 91"
+Info-ZIP
+.IP "v4.2\t20 Mar 92"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.0\t21 Aug 92"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.01\t15 Jan 93"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.1\t\ 7 Feb 94"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.11\t\ 2 Aug 94"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.12\t28 Aug 94"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.2\t30 Apr 96"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.3\t22 Apr 97"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.31\t31 May 97"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.32\t\ 3 Nov 97"
+Info-ZIP (Zip-Bugs subgroup, GRR)
+.IP "v5.4\t28 Nov 98"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v5.41\t16 Apr 00"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v5.42\t14 Jan 01"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v5.5\t17 Feb 02"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v5.51\t22 May 04"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v5.52\t28 Feb 05"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.IP "v6.0\t20 Apr 09"
+Info-ZIP (Zip-Bugs subgroup, SPC)
+.PD
diff --git a/upstream/mageia-cauldron/man1/unzipsfx.1 b/upstream/mageia-cauldron/man1/unzipsfx.1
new file mode 100644
index 00000000..d9a0e59b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/unzipsfx.1
@@ -0,0 +1,336 @@
+.\"  Copyright (c) 1990-2009 Info-ZIP.  All rights reserved.
+.\"
+.\"  See the accompanying file LICENSE, version 2009-Jan-02 or later
+.\"  (the contents of which are also included in unzip.h) for terms of use.
+.\"  If, for some reason, all these files are missing, the Info-ZIP license
+.\"  also may be found at:  ftp://ftp.info-zip.org/pub/infozip/license.html
+.\"
+.\" unzipsfx.1 by Greg Roelofs
+.\"
+.\" =========================================================================
+.\" define .EX/.EE (for multiline user-command examples; normal Courier font)
+.de EX
+.in +4n
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.fi
+.in -4n
+..
+.\" =========================================================================
+.TH UNZIPSFX 1L "20 April 2009 (v6.0)" "Info-ZIP"
+.SH NAME
+unzipsfx \- self-extracting stub for prepending to ZIP archives
+.PD
+.SH SYNOPSIS
+\fB<name of unzipsfx+archive combo>\fP [\fB\-cfptuz\fP[\fBajnoqsCLV$\fP]]
+[\fIfile(s)\fP\ .\|.\|. [\fB\-x\fP\ \fIxfile(s)\fP\ .\|.\|.]]
+.PD
+.\" =========================================================================
+.SH DESCRIPTION
+\fIunzipsfx\fP is a modified version of \fIunzip\fP(1L) designed to be
+prepended to existing ZIP archives in order to form self-extracting archives.
+Instead of taking its first non-flag argument to be the zipfile(s) to be
+extracted, \fIunzipsfx\fP seeks itself under the name by which it was invoked
+and tests or extracts the contents of the appended archive.  Because the
+executable stub adds bulk to the archive (the whole purpose of which is to
+be as small as possible), a number of the less-vital capabilities in regular
+\fIunzip\fP have been removed.  Among these are the usage (or help) screen,
+the listing and diagnostic functions (\fB\-l\fP and \fB\-v\fP), the ability
+to decompress older compression formats (the ``reduce,'' ``shrink'' and
+``implode'' methods).  The ability to extract to a directory other than
+the current one can be selected as a compile-time option, which is now enabled
+by default since UnZipSFX version 5.5.  Similarly, decryption is supported as
+a compile-time option but should be avoided unless the attached archive
+contains encrypted files. Starting with release 5.5, another compile-time
+option adds a simple ``run command after extraction'' feature.  This feature
+is currently incompatible with the ``extract to different directory''
+feature and remains disabled by default.
+.PP
+\fBNote that
+self-extracting archives made with\fP \fIunzipsfx\fP \fBare no more (or less)
+portable across different operating systems than is
+the\fP \fIunzip\fP \fBexecutable itself.\fP  In general a self-extracting
+archive made on
+a particular Unix system, for example, will only self-extract under the same
+flavor of Unix.  Regular \fIunzip\fP may still be used to extract the
+embedded archive as with any normal zipfile, although it will generate
+a harmless warning about extra bytes at the beginning of the zipfile.
+\fIDespite this\fP, however, the self-extracting archive is technically
+\fInot\fP a valid ZIP archive, and PKUNZIP may be unable to test or extract
+it.  This limitation is due to the simplistic manner in which the archive
+is created; the internal directory structure is not updated to reflect the
+extra bytes prepended to the original zipfile.
+.PD
+.\" =========================================================================
+.SH ARGUMENTS
+.IP [\fIfile(s)\fP]
+An optional list of archive members to be processed.
+Regular expressions (wildcards) similar to those in Unix \fIegrep\fP(1)
+may be used to match multiple members.  These wildcards may contain:
+.RS
+.IP *
+matches a sequence of 0 or more characters
+.IP ?
+matches exactly 1 character
+.IP [.\|.\|.]
+matches any single character found inside the brackets; ranges are specified
+by a beginning character, a hyphen, and an ending character.  If an exclamation
+point or a caret (`!' or `^') follows the left bracket, then the range of
+characters within the brackets is complemented (that is, anything \fIexcept\fP
+the characters inside the brackets is considered a match).
+.RE
+.IP
+(Be sure to quote any character that might otherwise be interpreted or
+modified by the operating system, particularly under Unix and VMS.)
+.IP [\fB\-x\fP\ \fIxfile(s)\fP]
+An optional list of archive members to be excluded from processing.
+Since wildcard characters match directory separators (`/'), this option
+may be used to exclude any files that are in subdirectories.  For
+example, ``\fCfoosfx *.[ch] -x */*\fR'' would extract all C source files
+in the main directory, but none in any subdirectories.  Without the \fB\-x\fP
+option, all C source files in all directories within the zipfile would be
+extracted.
+.PP
+If \fIunzipsfx\fP is compiled with SFX_EXDIR defined, the following option
+is also enabled:
+.IP [\fB\-d\fP\ \fIexdir\fP]
+An optional directory to which to extract files.  By default, all files
+and subdirectories are recreated in the current directory; the \fB\-d\fP
+option allows extraction in an arbitrary directory (always assuming one
+has permission to write to the directory).  The option and directory may
+be concatenated without any white space between them, but note that this
+may cause normal shell behavior to be suppressed.  In particular,
+``\fC\-d\ ~\fR'' (tilde) is expanded by Unix C shells into the name
+of the user's home directory, but ``\fC\-d~\fR'' is treated as a
+literal subdirectory ``\fB~\fP'' of the current directory.
+.PD
+.\" =========================================================================
+.SH OPTIONS
+\fIunzipsfx\fP supports the following \fIunzip\fP(1L) options:  \fB\-c\fP
+and \fB\-p\fP (extract to standard output/screen), \fB\-f\fP and \fB\-u\fP
+(freshen and update existing files upon extraction), \fB\-t\fP (test
+archive) and \fB\-z\fP (print archive comment).  All normal listing options
+(\fB\-l\fP, \fB\-v\fP and \fB\-Z\fP) have been removed, but the testing
+option (\fB\-t\fP) may be used as a ``poor man's'' listing.  Alternatively,
+those creating self-extracting archives may wish to include a short listing
+in the zipfile comment.
+.PP
+See \fIunzip\fP(1L) for a more complete description of these options.
+.PD
+.\" =========================================================================
+.SH MODIFIERS
+\fIunzipsfx\fP currently supports all \fIunzip\fP(1L) modifiers:  \fB\-a\fP
+(convert text files), \fB\-n\fP (never overwrite), \fB\-o\fP (overwrite
+without prompting), \fB\-q\fP (operate quietly), \fB\-C\fP (match names
+case-insensitively), \fB\-L\fP (convert uppercase-OS names to lowercase),
+\fB\-j\fP (junk paths) and \fB\-V\fP (retain version numbers); plus the
+following operating-system specific options:  \fB\-X\fP (restore VMS
+owner/protection info), \fB\-s\fP (convert spaces in filenames to underscores
+[DOS, OS/2, NT]) and \fB\-$\fP (restore volume label [DOS, OS/2, NT, Amiga]).
+.PP
+(Support for regular ASCII text-conversion may be removed in future versions,
+since it is simple enough for the archive's creator to ensure that text
+files have the appropriate format for the local OS.  EBCDIC conversion will
+of course continue to be supported since the zipfile format implies ASCII
+storage of text files.)
+.PP
+See \fIunzip\fP(1L) for a more complete description of these modifiers.
+.PD
+.\" =========================================================================
+.SH "ENVIRONMENT OPTIONS"
+\fIunzipsfx\fP uses the same environment variables as \fIunzip\fP(1L) does,
+although this is likely to be an issue only for the person creating and
+testing the self-extracting archive.  See \fIunzip\fP(1L) for details.
+.PD
+.\" =========================================================================
+.SH DECRYPTION
+Decryption is supported exactly as in \fIunzip\fP(1L); that is, interactively
+with a non-echoing prompt for the password(s).  See \fIunzip\fP(1L) for
+details.  Once again, note that if the archive has no encrypted files there
+is no reason to use a version of \fIunzipsfx\fP with decryption support;
+that only adds to the size of the archive.
+.PD
+.\" =========================================================================
+.SH AUTORUN COMMAND
+When \fIunzipsfx\fP was compiled with CHEAP_SFX_AUTORUN defined, a simple
+``command autorun'' feature is supported. You may enter a command into the
+Zip archive comment, using the following format:
+.PP
+.EX
+$AUTORUN$>[command line string]
+.EE
+.PP
+When \fIunzipsfx\fP recognizes the ``$AUTORUN$>'' token at the beginning
+of the Zip archive comment, the remainder of the first line of the comment
+(until the first newline character) is passed as a shell command to the
+operating system using the C rtl ``system'' function. Before executing
+the command, \fIunzipsfx\fP displays the command on the console and prompts
+the user for confirmation.  When the user has switched off prompting by
+specifying the \fB-q\fP option, autorun commands are never executed.
+.PP
+In case the archive comment contains additional lines of text, the remainder
+of the archive comment following the first line is displayed normally, unless
+quiet operation was requested by supplying a \fB-q\fP option.
+.PD
+.\" =========================================================================
+.SH EXAMPLES
+To create a self-extracting archive \fIletters\fP from a regular zipfile
+\fIletters.zip\fP and change the new archive's permissions to be
+world-executable under Unix:
+.PP
+.EX
+cat unzipsfx letters.zip > letters
+chmod 755 letters
+zip -A letters
+.EE
+.PP
+To create the same archive under MS-DOS, OS/2 or NT (note the use of the
+\fB/b\fP [binary] option to the \fIcopy\fP command):
+.PP
+.EX
+copy /b unzipsfx.exe+letters.zip letters.exe
+zip -A letters.exe
+.EE
+.PP
+Under VMS:
+.PP
+.EX
+copy unzipsfx.exe,letters.zip letters.exe
+letters == "$currentdisk:[currentdir]letters.exe"
+zip -A letters.exe
+.EE
+.PP
+(The VMS \fIappend\fP command may also be used.  The second command installs
+the new program as a ``foreign command'' capable of taking arguments.  The
+third line assumes that Zip is already installed as a foreign command.)
+Under AmigaDOS:
+.PP
+.EX
+MakeSFX letters letters.zip UnZipSFX
+.EE
+.PP
+(MakeSFX is included with the UnZip source distribution and with Amiga
+binary distributions.  ``\fCzip -A\fR'' doesn't work on Amiga self-extracting
+archives.)
+To test (or list) the newly created self-extracting archive:
+.PP
+.EX
+letters \-t
+.EE
+.PP
+To test \fIletters\fP quietly, printing only a summary message indicating
+whether the archive is OK or not:
+.PP
+.EX
+letters \-tqq
+.EE
+.PP
+To extract the complete contents into the current directory, recreating all
+files and subdirectories as necessary:
+.PP
+.EX
+letters
+.EE
+.PP
+To extract all \fC*.txt\fR files (in Unix quote the `*'):
+.PP
+.EX
+letters *.txt
+.EE
+.PP
+To extract everything \fIexcept\fP the \fC*.txt\fR files:
+.PP
+.EX
+letters -x *.txt
+.EE
+.PP
+To extract only the README file to standard output (the screen):
+.PP
+.EX
+letters -c README
+.EE
+.PP
+To print only the zipfile comment:
+.PP
+.EX
+letters \-z
+.EE
+.PD
+.\" =========================================================================
+.SH LIMITATIONS
+The principle and fundamental limitation of \fIunzipsfx\fP is that it is
+not portable across architectures or operating systems, and therefore
+neither are the resulting archives.  For some architectures there is
+limited portability, however (e.g., between some flavors of Intel-based Unix).
+.PP
+Another problem with the current implementation is that any archive
+with ``junk'' prepended to the beginning technically is no longer a zipfile
+(unless \fIzip\fP(1) is used to adjust the zipfile offsets appropriately,
+as noted above).  \fIunzip\fP(1) takes note of the prepended bytes
+and ignores them since some file-transfer protocols, notably MacBinary, are
+also known to prepend junk.  But PKWARE's archiver suite may not be able to
+deal with the modified archive unless its offsets have been adjusted.
+.PP
+\fIunzipsfx\fP has no knowledge of the user's PATH, so in general an archive
+must either be in the current directory when it is invoked, or else a full
+or relative path must be given.  If a user attempts to extract the archive
+from a directory in the PATH other than the current one, \fIunzipsfx\fP will
+print a warning to the effect, ``can't find myself.''  This is always true
+under Unix and may be true in some cases under MS-DOS, depending on the
+compiler used (Microsoft C fully qualifies the program name, but other
+compilers may not).  Under OS/2 and NT there are operating-system calls
+available that provide the full path name, so the archive may be invoked
+from anywhere in the user's path.  The situation is not known for AmigaDOS,
+Atari TOS, MacOS, etc.
+.PP
+As noted above, a number of the normal \fIunzip\fP(1L) functions have
+been removed in order to make \fIunzipsfx\fP smaller:  usage and diagnostic
+info, listing functions and extraction to other directories.  Also, only
+stored and deflated files are supported.  The latter limitation is mainly
+relevant to those who create SFX archives, however.
+.PP
+VMS users must know how to set up self-extracting archives as foreign
+commands in order to use any of \fIunzipsfx\fP's options.  This is not
+necessary for simple extraction, but the command to do so then becomes,
+e.g., ``\fCrun letters\fR'' (to continue the examples given above).
+.PP
+\fIunzipsfx\fP on the Amiga requires the use of a special program, MakeSFX,
+in order to create working self-extracting archives; simple concatenation
+does not work.  (For technically oriented users, the attached archive is
+defined as a ``debug hunk.'')  There may be compatibility problems between
+the ROM levels of older Amigas and newer ones.
+.PP
+All current bugs in \fIunzip\fP(1L) exist in \fIunzipsfx\fP as well.
+.PD
+.\" =========================================================================
+.SH DIAGNOSTICS
+\fIunzipsfx\fP's exit status (error level) is identical to that of
+\fIunzip\fP(1L); see the corresponding man page.
+.PD
+.\" =========================================================================
+.SH "SEE ALSO"
+\fIfunzip\fP(1L), \fIunzip\fP(1L), \fIzip\fP(1L), \fIzipcloak\fP(1L),
+\fIzipgrep\fP(1L), \fIzipinfo\fP(1L), \fIzipnote\fP(1L), \fIzipsplit\fP(1L)
+.PD
+.PD
+.\" =========================================================================
+.SH URL
+The Info-ZIP home page is currently at
+.EX
+\fChttp://www.info-zip.org/pub/infozip/\fR
+.EE
+or
+.EX
+\fCftp://ftp.info-zip.org/pub/infozip/\fR .
+.EE
+.PD
+.\" =========================================================================
+.SH AUTHORS
+Greg Roelofs was responsible for the basic modifications to UnZip necessary
+to create UnZipSFX.  See \fIunzip\fP(1L) for the current list of Zip-Bugs
+authors, or the file CONTRIBS in the UnZip source distribution for the
+full list of Info-ZIP contributors.
+.PD
diff --git a/upstream/mageia-cauldron/man1/usb-devices.1 b/upstream/mageia-cauldron/man1/usb-devices.1
new file mode 100644
index 00000000..910cc643
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/usb-devices.1
@@ -0,0 +1,55 @@
+.\" SPDX-License-Identifier: GPL-2.0-only
+.\" Copyright (c) 2004 Greg Kroah-Hartman <greg@kroah.com>
+.\" Copyright (c) 2004 Randy Dunlap <rdunlap@xenotime.net>
+.\" Copyright (c) 2004 Frans Pop <elendil@planet.nl>
+.TH usb-devices 1 "23 June 2009" "usbutils-017" "Linux USB Utilities"
+.IX usb-devices
+.SH NAME
+usb-devices \- print USB device details
+.SH SYNOPSIS
+.B usb-devices
+
+.SH DESCRIPTION
+.B usb-devices
+is a shell script that can be used to display details of USB
+buses in the system and the devices connected to them.
+
+The output of the script is similar to the \fIusb/devices\fP file
+available either under \fI/proc/bus\fP (if usbfs is mounted), or under
+\fI/sys/kernel/debug\fP (if debugfs is mounted there). The script is
+primarily intended to be used if the file is not available.
+
+In contrast to the \fIusb/devices\fP file, this script only lists
+\fIactive\fP interfaces (those marked with a "*" in the \fIusb/devices\fP
+file) and their endpoints.
+
+Be advised that there can be differences in the way information is sorted,
+as well as in the format of the output.
+
+.SH RETURN VALUE
+If sysfs is not mounted, a non-zero exit code is returned.
+
+.SH FILES
+.TP
+.B /sys/bus/usb/devices/usb*
+The part of the sysfs tree the script walks through to assemble the
+printed information.
+.TP
+.B /proc/bus/usb/devices
+Location where the \fIusb/devices\fP file can normally be found for
+Linux kernels before 2.6.31, if usbfs is mounted.
+.TP
+.B /sys/kernel/debug/usb/devices
+Location where the \fIusb/devices\fP file can normally be found for
+Linux kernel 2.6.31 and later, if debugfs is mounted.
+
+.SH SEE ALSO
+.BR lsusb (8),
+.BR usbview (8).
+
+.SH AUTHORS
+Greg Kroah-Hartman <greg@kroah.com>
+.P
+Randy Dunlap <rdunlap@xenotime.net>
+.P
+Frans Pop <elendil@planet.nl>
diff --git a/upstream/mageia-cauldron/man1/userdbctl.1 b/upstream/mageia-cauldron/man1/userdbctl.1
new file mode 100644
index 00000000..a5445353
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/userdbctl.1
@@ -0,0 +1,595 @@
+'\" t
+.TH "USERDBCTL" "1" "" "systemd 255" "userdbctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+userdbctl \- Inspect users, groups and group memberships
+.SH "SYNOPSIS"
+.HP \w'\fBuserdbctl\fR\ 'u
+\fBuserdbctl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBuserdbctl\fR
+may be used to inspect user and groups (as well as group memberships) of the system\&. This client utility inquires user/group information provided by various system services, both operating on JSON user/group records (as defined by the
+\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2
+and
+\m[blue]\fBJSON Group Records\fR\m[]\&\s-2\u[2]\d\s+2
+definitions), and classic UNIX NSS/glibc user and group records\&. This tool is primarily a client to the
+\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[3]\d\s+2, and may also pick up drop\-in JSON user and group records from
+/etc/userdb/,
+/run/userdb/,
+/run/host/userdb/,
+/usr/lib/userdb/\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-output=\fR\fIMODE\fR
+.RS 4
+Choose the output mode, takes one of
+"classic",
+"friendly",
+"table",
+"json"\&. If
+"classic", an output very close to the format of
+/etc/passwd
+or
+/etc/group
+is generated\&. If
+"friendly"
+a more comprehensive and user friendly, human readable output is generated; if
+"table"
+a minimal, tabular output is generated; if
+"json"
+a JSON formatted output is generated\&. Defaults to
+"friendly"
+if a user/group is specified on the command line,
+"table"
+otherwise\&.
+.sp
+Note that most output formats do not show all available information\&. In particular,
+"classic"
+and
+"table"
+show only the most important fields\&. Various modes also do not show password hashes\&. Use
+"json"
+to view all fields, including any authentication fields\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIFORMAT\fR
+.RS 4
+Selects JSON output mode (like
+\fB\-\-output=json\fR) and selects the precise display mode\&. Takes one of
+"pretty"
+or
+"short"\&. If
+"pretty", human\-friendly whitespace and newlines are inserted in the output to make the JSON data more readable\&. If
+"short", all superfluous whitespace is suppressed\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-service=\fR\fISERVICE\fR[:\fISERVICE\&...\fR], \fB\-s\fR \fISERVICE\fR:\fISERVICE\&...\fR
+.RS 4
+Controls which services to query for users/groups\&. Takes a list of one or more service names, separated by
+":"\&. See below for a list of well\-known service names\&. If not specified all available services are queried at once\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-with\-nss=\fR\fIBOOL\fR
+.RS 4
+Controls whether to include classic glibc/NSS user/group lookups in the output\&. If
+\fB\-\-with\-nss=no\fR
+is used any attempts to resolve or enumerate users/groups provided only via glibc NSS is suppressed\&. If
+\fB\-\-with\-nss=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-with\-varlink=\fR\fIBOOL\fR
+.RS 4
+Controls whether to include Varlink user/group lookups in the output, i\&.e\&. those done via the
+\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[3]\d\s+2\&. If
+\fB\-\-with\-varlink=no\fR
+is used any attempts to resolve or enumerate users/groups provided only via Varlink are suppressed\&. If
+\fB\-\-with\-varlink=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-with\-dropin=\fR\fIBOOL\fR
+.RS 4
+Controls whether to include user/group lookups in the output that are defined using drop\-in files in
+/etc/userdb/,
+/run/userdb/,
+/run/host/userdb/,
+/usr/lib/userdb/\&. If
+\fB\-\-with\-dropin=no\fR
+is used these records are suppressed\&. If
+\fB\-\-with\-dropin=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+\fB\-\-synthesize=\fR\fIBOOL\fR
+.RS 4
+Controls whether to synthesize records for the root and nobody users/groups if they aren\*(Aqt defined otherwise\&. By default (or
+"yes") such records are implicitly synthesized if otherwise missing since they have special significance to the OS\&. When
+"no"
+this synthesizing is turned off\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-N\fR
+.RS 4
+This option is short for
+\fB\-\-with\-nss=no\fR
+\fB\-\-synthesize=no\fR\&. Use this option to show only records that are natively defined as JSON user or group records, with all NSS/glibc compatibility and all implicit synthesis turned off\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fB\-\-multiplexer=\fR\fIBOOL\fR
+.RS 4
+Controls whether to do lookups via the multiplexer service (if specified as true, the default) or do lookups in the client (if specified as false)\&. Using the multiplexer service is typically preferable, since it runs in a locked down sandbox\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-chain\fR
+.RS 4
+When used with the
+\fBssh\-authorized\-keys\fR
+command, this will allow passing an additional command line after the user name that is chain executed after the lookup completed\&. This allows chaining multiple tools that show SSH authorized keys\&.
+.sp
+Added in version 250\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBuser\fR [\fIUSER\fR\&...]
+.RS 4
+List all known users records or show details of one or more specified user records\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBgroup\fR [\fIGROUP\fR\&...]
+.RS 4
+List all known group records or show details of one or more specified group records\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBusers\-in\-group\fR [\fIGROUP\fR\&...]
+.RS 4
+List users that are members of the specified groups\&. If no groups are specified list all user/group memberships defined\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBgroups\-of\-user\fR [\fIUSER\fR\&...]
+.RS 4
+List groups that the specified users are members of\&. If no users are specified list all user/group memberships defined (in this case
+\fBgroups\-of\-user\fR
+and
+\fBusers\-in\-group\fR
+are equivalent)\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBservices\fR
+.RS 4
+List all services currently providing user/group definitions to the system\&. See below for a list of well\-known services providing user information\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBssh\-authorized\-keys\fR
+.RS 4
+Show SSH authorized keys for this account\&. This command is intended to be used to allow the SSH daemon to pick up authorized keys from user records, see below\&.
+.sp
+Added in version 245\&.
+.RE
+.SH "WELL\-KNOWN SERVICES"
+.PP
+The
+\fBuserdbctl services\fR
+command will list all currently running services that provide user or group definitions to the system\&. The following well\-known services are shown among this list:
+.PP
+\fBio\&.systemd\&.DynamicUser\fR
+.RS 4
+This service is provided by the system service manager itself (i\&.e\&. PID 1) and makes all users (and their groups) synthesized through the
+\fIDynamicUser=\fR
+setting in service unit files available to the system (see
+\fBsystemd.exec\fR(5)
+for details about this setting)\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBio\&.systemd\&.Home\fR
+.RS 4
+This service is provided by
+\fBsystemd-homed.service\fR(8)
+and makes all users (and their groups) belonging to home directories managed by that service available to the system\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBio\&.systemd\&.Machine\fR
+.RS 4
+This service is provided by
+\fBsystemd-machined.service\fR(8)
+and synthesizes records for all users/groups used by a container that employs user namespacing\&.
+.sp
+Added in version 246\&.
+.RE
+.PP
+\fBio\&.systemd\&.Multiplexer\fR
+.RS 4
+This service is provided by
+\fBsystemd-userdbd.service\fR(8)
+and multiplexes user/group look\-ups to all other running lookup services\&. This is the primary entry point for user/group record clients, as it simplifies client side implementation substantially since they can ask a single service for lookups instead of asking all running services in parallel\&.
+\fBuserdbctl\fR
+uses this service preferably, too, unless
+\fB\-\-with\-nss=\fR
+or
+\fB\-\-service=\fR
+are used, in which case finer control over the services to talk to is required\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBio\&.systemd\&.NameServiceSwitch\fR
+.RS 4
+This service is (also) provided by
+\fBsystemd-userdbd.service\fR(8)
+and converts classic NSS/glibc user and group records to JSON user/group records, providing full backwards compatibility\&. Use
+\fB\-\-with\-nss=no\fR
+to disable this compatibility, see above\&. Note that compatibility is actually provided in both directions:
+\fBnss-systemd\fR(8)
+will automatically synthesize classic NSS/glibc user/group records from all JSON user/group records provided to the system, thus using both APIs is mostly equivalent and provides access to the same data, however the NSS/glibc APIs necessarily expose a more reduced set of fields only\&.
+.sp
+Added in version 245\&.
+.RE
+.PP
+\fBio\&.systemd\&.DropIn\fR
+.RS 4
+This service is (also) provided by
+\fBsystemd-userdbd.service\fR(8)
+and picks up JSON user/group records from
+/etc/userdb/,
+/run/userdb/,
+/run/host/userdb/,
+/usr/lib/userdb/\&.
+.sp
+Added in version 249\&.
+.RE
+.PP
+Note that
+\fBuserdbctl\fR
+has internal support for NSS\-based lookups too\&. This means that if neither
+\fBio\&.systemd\&.Multiplexer\fR
+nor
+\fBio\&.systemd\&.NameServiceSwitch\fR
+are running look\-ups into the basic user/group databases will still work\&.
+.SH "INTEGRATION WITH SSH"
+.PP
+The
+\fBuserdbctl\fR
+tool may be used to make the list of SSH authorized keys possibly contained in a user record available to the SSH daemon for authentication\&. For that configure the following in
+\fBsshd_config\fR(5):
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\&...
+AuthorizedKeysCommand /usr/bin/userdbctl ssh\-authorized\-keys %u
+AuthorizedKeysCommandUser root
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Sometimes it\*(Aqs useful to allow chain invocation of another program to list SSH authorized keys\&. By using the
+\fB\-\-chain\fR
+such a tool may be chain executed by
+\fBuserdbctl ssh\-authorized\-keys\fR
+once a lookup completes (regardless if an SSH key was found or not)\&. Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\&...
+AuthorizedKeysCommand /usr/bin/userdbctl ssh\-authorized\-keys %u \-\-chain /usr/bin/othertool %u
+AuthorizedKeysCommandUser root
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The above will first query the userdb database for SSH keys, and then chain execute
+\fB/usr/bin/othertool\fR
+to also be queried\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(1), until one is found\&. If no pager implementation is discovered no pager is invoked\&. Setting this environment variable to an empty string or the value
+"cat"
+is equivalent to passing
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
+.RE
+.sp
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-userdbd.service\fR(8),
+\fBsystemd-homed.service\fR(8),
+\fBnss-systemd\fR(8),
+\fBgetent\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+JSON User Records
+.RS 4
+\%https://systemd.io/USER_RECORD
+.RE
+.IP " 2." 4
+JSON Group Records
+.RS 4
+\%https://systemd.io/GROUP_RECORD
+.RE
+.IP " 3." 4
+User/Group Record Lookup API via Varlink
+.RS 4
+\%https://systemd.io/USER_GROUP_API
+.RE
diff --git a/upstream/mageia-cauldron/man1/users.1 b/upstream/mageia-cauldron/man1/users.1
new file mode 100644
index 00000000..86a91d73
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/users.1
@@ -0,0 +1,37 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH USERS "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+users \- print the user names of users currently logged in to the current host
+.SH SYNOPSIS
+.B users
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Output who is currently logged in according to FILE.
+If FILE is not specified, use \fI\,/run/utmp\/\fP.  \fI\,/var/log/wtmp\/\fP as FILE is common.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Joseph Arceneaux and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+\fBgetent\fP(1), \fBwho\fP(1)
+.PP
+.br
+Full documentation <https://www.gnu.org/software/coreutils/users>
+.br
+or available locally via: info \(aq(coreutils) users invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/usleep.1 b/upstream/mageia-cauldron/man1/usleep.1
new file mode 100644
index 00000000..30db2bad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/usleep.1
@@ -0,0 +1,30 @@
+.TH USLEEP 1 "Red Hat, Inc" \" -*- nroff -*-
+.SH NAME
+usleep \- sleep some number of microseconds
+.SH SYNOPSIS
+.B usleep
+[\fInumber\fP]
+.SH DESCRIPTION
+.B usleep
+sleeps some number of microseconds.  The default is 1.
+.SH WARNING
+.B usleep
+has been deprecated, and will be removed in near future. Use sleep(1) instead.
+.SH OPTIONS
+\fI--usage\fP
+Show short usage message.
+.TP
+\fI--help, -?\fP
+Print help information.
+.TP
+\fI-v, --version\fP
+Print version information.
+.SH BUGS
+Probably not accurate on many machines down to the microsecond.  Count
+on precision only to -4 or maybe -5.
+.SH AUTHOR
+Donald Barnes <djb@redhat.com>
+.br
+Erik Troan <ewt@redhat.com>
+.SH SEE ALSO
+sleep(1)
diff --git a/upstream/mageia-cauldron/man1/uucp.1 b/upstream/mageia-cauldron/man1/uucp.1
new file mode 100644
index 00000000..be6ce8b3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uucp.1
@@ -0,0 +1,197 @@
+''' $Id: uucp.1,v 1.12 2002/03/05 22:13:33 ian Rel $
+.TH uucp 1 "Taylor UUCP 1.07"
+.SH NAME
+uucp \- Unix to Unix copy
+.SH SYNOPSIS
+.B uucp
+[ options ] source-file destination-file
+.PP
+.B uucp
+[ options ] source-file... destination-directory
+.SH DESCRIPTION
+The
+.I uucp
+command copies files between systems.  Each
+.I file
+argument is either a pathname on the local machine or is of the form
+.IP
+system!path
+.LP
+which is interpreted as being on a remote system.
+In the first form, the contents of the first file are copied to the
+second.  In the second form, each source file is copied into the
+destination directory.
+
+A file be transferred to or from
+.I system2
+via
+.I system1
+by using
+.IP
+system1!system2!path.
+.LP
+
+Any pathname that does not begin with / or ~ will be appended to the
+current directory (unless the
+.B \-W
+or
+.B \--noexpand
+option is used); this resulting path will not necessarily exist on a
+remote system.  A pathname beginning with a simple ~ starts at the
+UUCP public directory; a pathname beginning with ~name starts at the
+home directory of the named user.  The ~ is interpreted on the
+appropriate system.  Note that some shells will interpret a simple ~
+to the local home directory before
+.I uucp
+sees it; to avoid this the ~ must be quoted.
+
+Shell metacharacters ? * [ ] are interpreted on the appropriate
+system, assuming they are quoted to prevent the shell from
+interpreting them first.
+
+The copy does not take place immediately, but is queued up for the
+.I uucico
+(8) daemon; the daemon is started immediately unless the 
+.B \-r
+or
+.B \-\-nouucico
+switch is given.  In any case, the next time the remote system is called the
+file(s) will be copied.
+.SH OPTIONS
+The following options may be given to
+.I uucp.
+.TP 5
+.B \-c, \-\-nocopy
+Do not copy local source files to the spool directory.  If they are
+removed before being processed by the
+.I uucico
+(8) daemon, the copy will fail.  The files must be readable by the
+.I uucico
+(8) daemon, and by the invoking user.
+.TP 5
+.B \-C, \-\-copy
+Copy local source files to the spool directory.  This is the default.
+.TP 5
+.B \-d, \-\-directories
+Create all necessary directories when doing the copy.  This is the
+default.
+.TP 5
+.B \-f, \-\-nodirectories
+If any necessary directories do not exist for the destination path,
+abort the copy.
+.TP 5
+.B \-R, \-\-recursive
+If any of the source file names are directories, copy their contents
+recursively to the destination (which must itself be a directory).
+.TP 5
+.B \-g grade, \-\-grade grade
+Set the grade of the file transfer command.  Jobs of a higher grade
+are executed first.  Grades run 0 ... 9 A ... Z a ... z from high to
+low.
+.TP 5
+.B \-m, \-\-mail
+Report completion or failure of the file transfer by
+.I mail
+(1).
+.TP 5
+.B \-n user, \-\-notify user
+Report completion or failure of the file transfer by
+.I mail
+(1) to the named
+user on the remote system.
+.TP 5
+.B \-r, \-\-nouucico
+Do not start
+.I uucico
+(8) daemon immediately; merely queue up the file transfer for later
+execution.
+.TP 5
+.B \-j, \-\-jobid
+Print jobid on standard output.  The job may be
+later cancelled by passing the jobid to the
+.B \-k
+switch of
+.I uustat
+(1).
+It is possible for some complex operations to produce more than one
+jobid, in which case each will be printed on a separate line.  For
+example
+.br
+.in +0.5i
+.nf
+uucp sys1!~user1/file1 sys2!~user2/file2 ~user3
+.fi
+.in -0.5i
+will generate two separate jobs, one for the system
+.I sys1
+and one for the system
+.I sys2.
+.TP 5
+.B \-W, \-\-noexpand
+Do not prepend remote relative path names with the current directory.
+.TP 5
+.B \-t, \-\-uuto
+This option is used by the 
+.I uuto
+shell script.  It causes
+.I uucp
+to interpret the final argument as
+.I system!user.
+The file(s) are sent to
+.I ~/receive/USER/LOCAL
+on the remote system, where
+.I USER
+is from the final argument and
+.I LOCAL
+is the local UUCP
+system name.  Also,
+.I uucp
+will act as though
+.I \-\-notify user
+were specified.
+.TP 5
+.B \-x type, \-\-debug type
+Turn on particular debugging types.  The following types are
+recognized: abnormal, chat, handshake, uucp-proto, proto, port,
+config, spooldir, execute, incoming, outgoing.  Only abnormal, config,
+spooldir and execute are meaningful for
+.I uucp.
+
+Multiple types may be given, separated by commas, and the
+.B \-\-debug
+option may appear multiple times.  A number may also be given, which
+will turn on that many types from the foregoing list; for example,
+.B \-\-debug 2
+is equivalent to
+.B \-\-debug abnormal,chat.
+.TP 5
+.B \-I file, \-\-config file
+Set configuration file to use.  This option may not be available,
+depending upon how
+.I uucp
+was compiled.
+.TP 5
+.B \-v, \-\-version
+Report version information and exit.
+.TP 5
+.B \-\-help
+Print a help message and exit.
+.SH SEE ALSO
+mail(1), uux(1), uustat(1), uucico(8)
+.SH BUGS
+Some of the options are dependent on the capabilities of the
+.I uucico
+(8) daemon on the remote system.
+
+The 
+.I \-n
+and
+.I \-m
+switches do not work when transferring a file from one remote system
+to another.
+
+File modes are not preserved, except for the execute bit.  The
+resulting file is owned by the uucp user.
+.SH AUTHOR
+Ian Lance Taylor
+<ian@airs.com>
diff --git a/upstream/mageia-cauldron/man1/uudecode.1 b/upstream/mageia-cauldron/man1/uudecode.1
new file mode 100644
index 00000000..8b6d0f52
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uudecode.1
@@ -0,0 +1,170 @@
+.de1 NOP
+.  it 1 an-trap
+.  if \\n[.$] \,\\$*\/
+..
+.ie t \
+.ds B-Font [CB]
+.ds I-Font [CI]
+.ds R-Font [CR]
+.el \
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+.TH uudecode 1 "30 May 2015" "GNU sharutils (4.15.2)" "User Commands"
+.\"
+.\" DO NOT EDIT THIS FILE (in-mem file)
+.\"
+.\" It has been AutoGen-ed
+.\" From the definitions uudecode-opts.def
+.\" and the template file agman-cmd.tpl
+.SH NAME
+\f\*[B-Font]uudecode\fP
+\- decode an encoded file
+.SH SYNOPSIS
+\f\*[B-Font]uudecode\fP
+.\" Mixture of short (flag) options and long options
+[\f\*[B-Font]\-flags\f[]]
+[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
+[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
+[<file>...]
+.sp \n(Ppu
+.ne 2
+
+If no \fIfile\fP(s) are provided, then standard input is decoded.
+.SH "DESCRIPTION"
+\fIuudecode\fP transforms uuencoded files into their original form.
+.sp
+The encoded file(s) may be specified on the command line, or one may
+be read from standard input.  The output file name is specified in
+the encoded file, but may be overridden with the \fB-o\fP option.
+It will have the mode of the original file, except that setuid and
+execute bits are not retained.  If the output file is specified to
+be \fI/dev/stdout\fP or \fI-\fP, the result will be written to
+standard output. If there are multiple input files and the second or
+subsquent file specifies standard output, the decoded data will be
+written to the same file as the previous output.  Don't do that.
+.sp
+\fIuudecode\fP ignores any leading and trailing lines.  It looks
+for a line that starts with "\fBbegin\fP" and proceeds until the
+end-of-encoding marker is found.  The program determines from the
+header line of the encoded file which of the two supported encoding
+schemes was used and whether or not the output file name has been
+encoded with base64 encoding.  See \fIuuencode(5)\fP.
+.SH "OPTIONS"
+.TP
+.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]file\f[], \f\*[B-Font]\-\-output\-file\f[]=\f\*[I-Font]file\f[]
+direct output to \fIfile\fP.
+.sp
+If specified, decoded data are written to this file.  When multiple
+inputs are specified on the command line, this option cannot be
+specified.  All decoded data must be written to the file name
+encoded in the data.
+.TP
+.NOP \f\*[B-Font]\-c\f[], \f\*[B-Font]\-\-ignore\-chmod\f[]
+ignore \fBfchmod(3P)\fP errors.
+.sp
+By default, if the output file permissions cannot be changed to
+the permissions specified in the encoded data, the file will not
+be written out and execution stops.  This option will cause that
+error to be ignored.  The resulting file will have all the data,
+but the incorrect mode settings.
+.sp
+\fBfchmod()\fP errors are also ignored if
+\fBPOSIXLY_CORRECT\fP is set in the environment.  RE:
+\fIhttp://austingroupbugs.net/view.php?id=635\fP
+.sp
+A warning is always emitted when \fBfchmod()\fP fails.
+.TP
+.NOP \f\*[B-Font]\-h\f[], \f\*[B-Font]\-\-help\f[]
+Display usage information and exit.
+.TP
+.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more\-help\f[]
+Pass the extended usage information through a pager.
+.TP
+.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save\-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
+Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+The command will exit after updating the config file.
+.TP
+.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load\-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no\-load\-opts\f[]
+Load options from \fIcfgfile\fP.
+The \fIno\-load\-opts\fP form will disable the loading
+of earlier config/rc/ini files.  \fI\-\-no\-load\-opts\fP is handled early,
+out of order.
+.TP
+.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]
+Output version of program and exit.  The default mode is `v', a simple
+version.  The `c' mode will print copyright information and `n' will
+print the full copyright notice.
+.PP
+.sp
+.SH "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from configuration ("RC" or ".INI") file(s).
+The file "\fI$HOME/.sharrc\fP" will be used, if present.
+.SH STANDARDS
+This implementation is compliant with P1003.2b/D11.
+.SH "FILES"
+See \fBOPTION PRESETS\fP for configuration files.
+.SH "EXIT STATUS"
+One of the following exit values will be returned:
+.TP
+.NOP 0 " (EXIT_SUCCESS)"
+Successful program execution.
+.TP
+.NOP 1 " (EXIT_OPTION_ERROR)"
+The command options were misconfigured.
+.TP
+.NOP 2 " (EXIT_INVALID)"
+(warning) One or more input files contained no valid data
+.TP
+.NOP 4 " (EXIT_NO_INPUT)"
+(warning) The specified input file was not found
+.TP
+.NOP 8 " (EXIT_NO_OUTPUT)"
+The specified output file could not be created (error); or else one of the output files could not be written or its access mode could not be changed (warnings).  The accompanying message(s) will distinguish.
+.TP
+.NOP 9 " (EXIT_NO_MEM)"
+No process memory available
+.TP
+.NOP 66 " (EX_NOINPUT)"
+A specified configuration file could not be loaded.
+.TP
+.NOP 70 " (EX_SOFTWARE)"
+libopts had an internal operational error.  Please report
+it to autogen-users@lists.sourceforge.net.  Thank you.
+.sp \n(Ppu
+.ne 2
+
+The exit status codes are (mostly) warning codes.
+As such, each code is "or"\-ed into the final exit code as the input
+files are processed.  For example, an exit code of '6' is not listed
+above.  It is the sum of \fBEXIT_INVALID\fP and \fBEXIT_NO_INPUT\fP.
+It would mean that at least one input file contained invalid
+data and also at least one input file could not be found at all.
+.PP
+.SH "SEE ALSO"
+uuencode(1), uuencode(5)
+.SH "AUTHORS"
+Free Software Foundation, Inc.
+.SH "COPYRIGHT"
+Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
+This program is released under the terms of the GNU General Public License, version 3 or later.
+.SH BUGS
+Please put \fBsharutils\fP in the subject line for emailed bug
+reports.  It helps to spot the message.
+.sp \n(Ppu
+.ne 2
+
+If more than one \fIname\fP in the encoded files are the same, or
+if the second or following input files specifies standard output
+for the output file, then the result is probably not what is expected.
+Specifically, standard output will be appended to and named output
+files will be replaced.
+.sp \n(Ppu
+.ne 2
+
+Please send bug reports to: bug-gnu-utils@gnu.org
+.SH "NOTES"
+This manual page was \fIAutoGen\fP-erated from the \fBuudecode\fP
+option definitions.
diff --git a/upstream/mageia-cauldron/man1/uuencode.1 b/upstream/mageia-cauldron/man1/uuencode.1
new file mode 100644
index 00000000..c59622d9
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uuencode.1
@@ -0,0 +1,132 @@
+.de1 NOP
+.  it 1 an-trap
+.  if \\n[.$] \,\\$*\/
+..
+.ie t \
+.ds B-Font [CB]
+.ds I-Font [CI]
+.ds R-Font [CR]
+.el \
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+.TH uuencode 1 "30 May 2015" "GNU sharutils (4.15.2)" "User Commands"
+.\"
+.\" DO NOT EDIT THIS FILE (in-mem file)
+.\"
+.\" It has been AutoGen-ed
+.\" From the definitions uuencode-opts.def
+.\" and the template file agman-cmd.tpl
+.SH NAME
+\f\*[B-Font]uuencode\fP
+\- encode a file into email friendly text
+.SH SYNOPSIS
+\f\*[B-Font]uuencode\fP
+.\" Mixture of short (flag) options and long options
+[\f\*[B-Font]\-flags\f[]]
+[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
+[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
+[<in-file>] <output-name>
+.sp \n(Ppu
+.ne 2
+
+.SH "DESCRIPTION"
+\fIuuencode\fP is used to create an ASCII representation of a file
+that can be sent over channels that may otherwise corrupt the data.
+Specifically, email cannot handle binary data and will often even
+insert a character when the six character sequence "\nFrom " is seen.
+.sp
+\fIuuencode\fP will read \fIin-file\fP if provided and otherwise
+read data from standard in and write the encoded form to standard out.
+The output will begin with a header line for use by \fIuudecode\fP
+giving it the resulting suggested file \fIoutput-name\fP and access
+mode.  If the \fIoutput-name\fP is specifically \fI/dev/stdout\fP,
+then \fIuudecode\fP will emit the decoded file to standard out.
+.sp
+\fBNote\fP: \fIuuencode\fP uses buffered input and assumes that it
+is not hand typed from a tty.  The consequence is that at a tty, you
+may need to hit Ctl-D several times to terminate input.
+.SH "OPTIONS"
+.TP
+.NOP \f\*[B-Font]\-m\f[], \f\*[B-Font]\-\-base64\f[]
+convert using base64.
+.sp
+By default, \fIuuencode\fP will encode using the traditional
+conversion.  It is slower and less compact than base64.
+The encoded form of the file is expanded by 37% for UU encoding
+and by 35% for base64 encoding (3 bytes become 4 plus control
+information).
+.TP
+.NOP \f\*[B-Font]\-e\f[], \f\*[B-Font]\-\-encode\-file\-name\f[]
+encode the output file name.
+.sp
+Since output file names may contain characters that are not
+handled well by various transmission modes, you may specify
+that the \fIoutput-name\fP be base64 encoded as well.
+(Traditional uuencoding of the file name is not supported.)
+.TP
+.NOP \f\*[B-Font]\-h\f[], \f\*[B-Font]\-\-help\f[]
+Display usage information and exit.
+.TP
+.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
+Pass the extended usage information through a pager.
+.TP
+.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
+Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+The command will exit after updating the config file.
+.TP
+.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
+Load options from \fIcfgfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
+out of order.
+.TP
+.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]
+Output version of program and exit.  The default mode is `v', a simple
+version.  The `c' mode will print copyright information and `n' will
+print the full copyright notice.
+.PP
+.SH "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from configuration ("RC" or ".INI") file(s).
+The file "\fI$HOME/.sharrc\fP" will be used, if present.
+.SH STANDARDS
+This implementation is compliant with P1003.2b/D11.
+.SH "FILES"
+See \fBOPTION PRESETS\fP for configuration files.
+.SH "EXIT STATUS"
+One of the following exit values will be returned:
+.TP
+.NOP 0 " (EXIT_SUCCESS)"
+Successful program execution.
+.TP
+.NOP 1 " (EXIT_FAILURE)"
+The operation failed or the command syntax was not valid.
+.TP
+.NOP 66 " (EX_NOINPUT)"
+A specified configuration file could not be loaded.
+.TP
+.NOP 70 " (EX_SOFTWARE)"
+libopts had an internal operational error.  Please report
+it to autogen-users@lists.sourceforge.net.  Thank you.
+.PP
+.SH "SEE ALSO"
+uudecode(1), uuencode(5)
+.SH HISTORY
+The \fBuuencode\fP command first appeared in BSD 4.0.
+.SH "AUTHORS"
+Free Software Foundation, Inc.
+.SH "COPYRIGHT"
+Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
+This program is released under the terms of the GNU General Public License, version 3 or later.
+.SH BUGS
+Please put \fBsharutils\fP in the subject line for emailed bug
+reports.  It helps to spot the message.
+.sp \n(Ppu
+.ne 2
+
+Please send bug reports to: bug-gnu-utils@gnu.org
+.SH "NOTES"
+This manual page was \fIAutoGen\fP-erated from the \fBuuencode\fP
+option definitions.
diff --git a/upstream/mageia-cauldron/man1/uustat.1 b/upstream/mageia-cauldron/man1/uustat.1
new file mode 100644
index 00000000..14cc9d57
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uustat.1
@@ -0,0 +1,542 @@
+''' $Id: uustat.1,v 1.14 2002/03/05 22:15:10 ian Rel $
+.TH uustat 1 "Taylor UUCP 1.07"
+.SH NAME
+uustat \- UUCP status inquiry and control
+.SH SYNOPSIS
+.B uustat \-a
+.PP
+.B uustat \-\-all
+.PP
+.B uustat
+[
+.B \-eKRiMNQ ] [
+.B \-sS
+system ] [
+.B \-uU
+user ] [
+.B \-cC
+command ] [
+.B \-oy
+hours ] [
+.B \-B
+lines ] [
+.B \-\-executions
+] [
+.B \-\-kill-all
+] [
+.B \-\-rejuvenate-all
+] [
+.B \-\-prompt
+] [
+.B \-\-mail
+] [
+.B \-\-notify
+] [
+.B \-\-no-list
+] [
+.B \-\-system
+system ] [
+.B \-\-not-system
+system ] [
+.B \-\-user
+user ] [
+.B \-\-not-user
+user ] [
+.B \-\-command
+command ] [
+.B \-\-not-command
+command ] [
+.B \-\-older-than
+hours ] [
+.B \-\-younger-than
+hours ] [
+.B \-\-mail-lines
+lines ]
+.PP
+.B uustat
+[
+.B \-kr
+jobid ] [
+.B \-\-kill
+jobid ] [
+.B \-\-rejuvenate
+jobid ]
+.PP
+.B uustat \-q [
+.B \-sS
+system ] [
+.B \-oy
+hours ] [
+.B \-\-system
+system ] [
+.B \-\-not-system
+system ] [
+.B \-\-older-than
+hours ] [
+.B \-\-younger-than
+hours ]
+.PP
+.B uustat \-\-list [
+.B \-sS
+system ] [
+.B \-oy
+hours ] [
+.B \-\-system
+system ] [
+.B \-\-not-system
+system ] [
+.B \-\-older-than
+hours ] [
+.B \-\-younger-than
+hours ]
+.PP
+.B uustat \-m
+.PP
+.B uustat \-\-status
+.PP
+.B uustat \-p
+.PP
+.B uustat \-\-ps
+.SH DESCRIPTION
+The
+.I uustat
+command can display various types of status information about the UUCP
+system.  It can also be used to cancel or rejuvenate requests made by
+.I uucp
+(1) or
+.I uux
+(1).
+
+By default
+.I uustat
+displays all jobs queued up for the invoking user, as if given the
+.B \-\-user
+option with the appropriate argument.
+
+If any of the
+.B \-a,
+.B \-\-all,
+.B \-e,
+.B \-\-executions,
+.B \-s,
+.B \-\-system,
+.B \-S,
+.B \-\-not-system,
+.B \-u,
+.B \-\-user,
+.B \-U,
+.B \-\-not-user,
+.B \-c,
+.B \-\-command,
+.B \-C,
+.B \-\-not-command,
+.B \-o,
+.B \-\-older-than,
+.B \-y,
+.B \-\-younger-than
+options are given, then all jobs which match the combined
+specifications are displayed.
+
+The 
+.B \-K
+or
+.B \-\-kill-all
+option may be used to kill off a selected group of jobs, such as all
+jobs more than 7 days old.
+.SH OPTIONS
+The following options may be given to
+.I uustat.
+.TP 5
+.B \-a, \-\-all
+List all queued file transfer requests.
+.TP 5
+.B \-e, \-\-executions
+List queued execution requests rather than queued file transfer
+requests.  Queued execution requests are processed by
+.I uuxqt
+(8) rather than
+.I uucico
+(8).  Queued execution requests may be waiting for some file to be
+transferred from a remote system.  They are created by an invocation
+of
+.I uux
+(1).
+.TP 5
+.B \-s system, \-\-system system
+List all jobs queued up for the named system.  These options may be
+specified multiple times, in which case all jobs for all the systems
+will be listed.  If used with
+.B \-\-list
+only the systems named will be listed.
+.TP 5
+.B \-S system, \-\-not-system system
+List all jobs queued for systems other than the one named.  These
+options may be specified multiple times, in which case no jobs from
+any of the specified systems will be listed.  If used with
+.B \-\-list
+only the systems not named will be listed.  These options may not be
+used with
+.B \-s
+or
+.B \-\-system.
+.TP 5
+.B \-u user, \-\-user user
+List all jobs queued up for the named user.  These options may be
+specified multiple times, in which case all jobs for all the users
+will be listed.
+.TP 5
+.B \-U user, \-\-not-user user
+List all jobs queued up for users other than the one named.  These
+options may be specified multiple times, in which case no jobs from
+any of the specified users will be listed.  These options may not be
+used with
+.B \-u
+or
+.B \-\-user.
+.TP 5
+.B \-c command, \-\-command command
+List all jobs requesting the execution of the named command.  If
+.B command
+is
+.I ALL
+this will list all jobs requesting the execution of some command (as
+opposed to simply requesting a file transfer).  These options may be
+specified multiple times, in which case all jobs requesting any of the
+commands will be listed.
+.TP 5
+.B \-C command, \-\-not-command command
+List all jobs requesting execution of some command other than the
+named command, or, if
+.B command
+is
+.I ALL,
+list all jobs that simply request a file transfer (as opposed to
+requesting the execution of some command).  These options may be
+specified multiple times, in which case no job requesting one of the
+specified commands will be listed.  These options may not be used with
+.B \-c
+or
+.B \-\-command.
+.TP 5
+.B \-o hours, \-\-older-than hours
+List all queued jobs older than the given number of hours.  If used
+with
+.B \-\-list
+only systems whose oldest job is older than the given number of hours
+will be listed.
+.TP 5
+.B \-y hours, \-\-younger-than hours
+List all queued jobs younger than the given number of hours.  If used
+with
+.B \-\-list
+only systems whose oldest job is younger than the given number of
+hours will be listed.
+.TP 5
+.B \-k jobid, \-\-kill jobid
+Kill the named job.  The job id is shown by the default output format,
+as well as by the
+.B \-j
+or
+.B \-\-jobid
+option to
+.I uucp
+(1) or
+.I uux
+(1).  A job may only be killed by the user who created the job, or by
+the UUCP administrator or the superuser.  The
+.B \-k
+or
+.B \-\-kill
+options may be used multiple times on the command line to kill several
+jobs.
+.TP 5
+.B \-r jobid, \-\-rejuvenate jobid
+Rejuvenate the named job.  This will mark it as having been invoked at
+the current time, affecting the output of the
+.B \-o,
+.B \-\-older-than,
+.B \-y,
+or
+.B \-\-younger-than
+options and preserving it from any automated cleanup daemon.  The job
+id is shown by the default output format, as well as by the
+.B \-j
+or
+.B \-\-jobid
+options to
+.I uucp
+(1) or
+.I uux
+(1).  A job may only be rejuvenated by the user who created the job,
+or by the UUCP administrator or the superuser.  The
+.B \-r
+or
+.B \-\-rejuvenate
+options may be used multiple times on the command line to rejuvenate
+several jobs.
+.TP 5
+.B \-q, \-\-list
+Display the status of commands, executions and conversations for all
+remote systems for which commands or executions are queued.  The
+.B \-s,
+.B \-\-system,
+.B \-S,
+.B \-\-not-system,
+.B \-o,
+.B \-\-older-than,
+.B \-y,
+and
+.B \-\-younger-than
+options may be used to restrict the systems which are listed.  Systems
+for which no commands or executions are queued will never be listed.
+.TP 5
+.B \-m, \-\-status
+Display the status of conversations for all remote systems.
+.TP 5
+.B \-p, \-\-ps
+Display the status of all processes holding UUCP locks on systems or
+ports.
+.TP 5
+.B \-i, \-\-prompt
+For each listed job, prompt whether to kill the job or not.  If the
+first character of the input line is
+.I y
+or
+.I Y
+the job will be killed.
+.TP 5
+.B \-K, \-\-kill-all
+Automatically kill each listed job.  This can be useful for automatic
+cleanup scripts, in conjunction with the
+.B \-\-mail
+and
+.B \-\-notify
+options.
+.TP 5
+.B \-R, \-\-rejuvenate-all
+Automatically rejuvenate each listed job.  This may not be used with
+.B \-\-kill-all.
+.TP 5
+.B \-M, \-\-mail
+For each listed job, send mail to the UUCP administrator.  If the job
+is killed (due to
+.B \-\-kill-all
+or
+.B \-\-prompt
+with an affirmative response) the mail will indicate that.  A comment
+specified by the
+.B \-\-comment
+option may be included.  If the job is an execution, the initial
+portion of its standard input will be included in the mail message;
+the number of lines to include may be set with the
+.B \-\-mail-lines
+option (the default is 100).  If the standard input contains null
+characters, it is assumed to be a binary file and is not included.
+.TP 5
+.B \-N, \-\-notify
+For each listed job, send mail to the user who requested the job.  The
+mail is identical to that sent by the
+.B \-M
+or
+.B \-\-mail
+options.
+.TP 5
+.B \-W comment, \-\-comment comment
+Specify a comment to be included in mail sent with the
+.B \-M,
+.B \-\-mail,
+.B \-N,
+or
+.B \-\-notify
+options.
+.TP 5
+.B \-B lines, \-\-mail-lines lines
+When the
+.B \-M,
+.B \-\-mail,
+.B \-N,
+or
+.B \-\-notify
+options are used to send mail about an execution with standard input,
+this option controls the number of lines of standard input to include
+in the message.  The default is 100.
+.TP 5
+.B \-Q, \-\-no-list
+Do not actually list the job, but only take any actions indicated by
+the
+.B \-i,
+.B \-\-prompt,
+.B \-K,
+.B \-\-kill-all,
+.B \-M,
+.B \-\-mail,
+.B \-N
+or
+.B \-\-notify
+options.
+.TP 5
+.B \-x type, \-\-debug type
+Turn on particular debugging types.  The following types are
+recognized: abnormal, chat, handshake, uucp-proto, proto, port,
+config, spooldir, execute, incoming, outgoing.  Only abnormal, config,
+spooldir and execute are meaningful for
+.I uustat.
+
+Multiple types may be given, separated by commas, and the
+.B \-\-debug
+option may appear multiple times.  A number may also be given, which
+will turn on that many types from the foregoing list; for example,
+.B \-\-debug 2
+is equivalent to
+.B \-\-debug abnormal,chat.
+.TP 5
+.B \-I file, \-\-config file
+Set configuration file to use.  This option may not be available,
+depending upon how
+.I uustat
+was compiled.
+.TP 5
+.B \-v, \-\-version
+Report version information and exit.
+.TP 5
+.B \-\-help
+Print a help message and exit.
+.SH EXAMPLES
+.br
+.nf
+uustat --all
+.fi
+Display status of all jobs.  A sample output line is as follows:
+.br
+.in +0.5i
+.nf
+bugsA027h bugs ian 04-01 13:50 Executing rmail ian@airs.com (sending 1283 bytes)
+.fi
+.in -0.5i
+The format is
+.br
+.in +0.5i
+.nf
+jobid system user queue-date command (size)
+.fi
+.in -0.5i
+The jobid may be passed to the
+.B \-\-kill
+or
+.B \-\-rejuvenate
+options.
+The size indicates how much data is to be transferred to the remote
+system, and is absent for a file receive request.
+The
+.B \-\-system,
+.B \-\-not-system,
+.B \-\-user,
+.B \-\-not-user,
+.B \-\-command,
+.B \-\-not-command,
+.B \-\-older-than,
+and
+.B \-\-younger-than
+options may be used to control which jobs are listed.
+
+.br
+.nf
+uustat --executions
+.fi
+Display status of queued up execution requests.  A sample output line
+is as follows:
+.br
+.in +0.5i
+.nf
+bugs bugs!ian 05-20 12:51 rmail ian
+.fi
+.in -0.5i
+The format is
+.br
+.in +0.5i
+.nf
+system requestor queue-date command
+.fi
+.in -0.5i
+The
+.B \-\-system,
+.B \-\-not-system,
+.B \-\-user,
+.B \-\-not-user,
+.B \-\-command,
+.B \-\-not-command,
+.B \-\-older-than,
+and
+.B \-\-younger-than
+options may be used to control which requests are listed.
+
+.br
+.nf
+uustat --list
+.fi
+Display status for all systems with queued up commands.  A sample
+output line is as follows:
+.br
+.in +0.5i
+.nf
+bugs            4C (1 hour)   0X (0 secs) 04-01 14:45 Dial failed
+.fi
+.in -0.5i
+This indicates the system, the number of queued commands, the age of
+the oldest queued command, the number of queued local executions, the
+age of the oldest queued execution, the date of the last conversation,
+and the status of that conversation.
+
+.br
+.nf
+uustat --status
+.fi
+Display conversation status for all remote systems.  A sample output
+line is as follows:
+.br
+.in +0.5i
+.nf
+bugs           04-01 15:51 Conversation complete
+.fi
+.in -0.5i
+This indicates the system, the date of the last conversation, and the
+status of that conversation.  If the last conversation failed,
+.I uustat
+will indicate how many attempts have been made to call the system.  If
+the retry period is currently preventing calls to that system,
+.I uustat
+also displays the time when the next call will be permitted.
+
+.br
+.nf
+uustat --ps
+.fi
+Display the status of all processes holding UUCP locks.  The output
+format is system dependent, as
+.I uustat
+simply invokes
+.I ps
+(1) on each process holding a lock.
+
+.br
+.in +0.5i
+.nf
+uustat --command rmail --older-than 168 --kill-all --no-list --mail --notify --comment "Queued for over 1 week"
+.fi
+.in -0.5i
+This will kill all
+.I rmail
+commands that have been queued up waiting for delivery for over 1 week
+(168 hours).  For each such command, mail will be sent both to the
+UUCP administrator and to the user who requested the rmail execution.
+The mail message sent will include the string given by the
+.B \-\-comment
+option.  The
+.B \-\-no-list
+option prevents any of the jobs from being listed on the terminal, so
+any output from the program will be error messages.
+.SH SEE ALSO
+ps(1), rmail(1), uucp(1), uux(1), uucico(8), uuxqt(8)
+.SH AUTHOR
+Ian Lance Taylor
+(ian@airs.com)
diff --git a/upstream/mageia-cauldron/man1/uux.1 b/upstream/mageia-cauldron/man1/uux.1
new file mode 100644
index 00000000..08daeb04
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/uux.1
@@ -0,0 +1,254 @@
+''' $Id: uux.1,v 1.15 2002/03/05 22:20:48 ian Rel $
+.TH uux 1 "Taylor UUCP 1.07"
+.SH NAME
+uux \- Remote command execution over UUCP
+.SH SYNOPSIS
+.B uux
+[ options ] command
+.SH DESCRIPTION
+The
+.I uux
+command is used to execute a command on a remote system, or to execute
+a command on the local system using files from remote systems.
+The command
+is not executed immediately; the request is queued until the
+.I uucico
+(8) daemon calls the system and executes it.  The daemon is
+started automatically unless one of the
+.B \-r
+or
+.B \-\-nouucico
+options is given.
+
+The actual command execution is done by the
+.I uuxqt
+(8) daemon.
+
+File arguments can be gathered from remote systems to the execution
+system, as can standard input.  Standard output may be directed to a
+file on a remote system.
+
+The command name may be preceded by a system name followed by an
+exclamation point if it is to be executed on a remote system.  An
+empty system name is taken as the local system.
+
+Each argument that contains an exclamation point is treated as naming
+a file.  The system which the file is on is before the exclamation
+point, and the pathname on that system follows it.  An empty system
+name is taken as the local system; this must be used to transfer a
+file to a command being executed on a remote system.  If the path is
+not absolute, it will be appended to the current working directory on
+the local system; the result may not be meaningful on the remote
+system.  A pathname may begin with ~/, in which case it is relative to
+the UUCP public directory (usually /usr/spool/uucppublic or
+/var/spool/uucppublic) on the appropriate system.  A pathname may
+begin with ~name/, in which case it is relative to the home directory
+of the named user on the appropriate system.
+
+Standard input and output may be redirected as usual; the pathnames
+used may contain exclamation points to indicate that they are on
+remote systems.  Note that the redirection characters must be quoted
+so that they are passed to
+.I uux
+rather than interpreted by the shell.  Append redirection (>>) does
+not work.
+
+All specified files are gathered together into a single directory
+before execution of the command begins.  This means that each file
+must have a distinct base name.  For example,
+.br
+.in +0.5i
+.nf
+uux 'sys1!diff sys2!~user1/foo sys3!~user2/foo >!foo.diff'
+.fi
+.in -0.5i
+will fail because both files will be copied to sys1 and stored under
+the name foo.
+
+Arguments may be quoted by parentheses to avoid interpretation of
+exclamation points.  This is useful when executing the
+.I uucp
+command on a remote system.
+
+A request to execute an empty command (e.g.,
+.I uux sys!)
+will create a poll file for the specified system.
+
+The exit status of
+.I uux
+is one of the codes found in the header file
+.B sysexits.h.
+In particular,
+.B EX_OK
+(
+.B 0
+) indicates success, and 
+.B EX_TEMPFAIL
+(
+.B 75
+) indicates a temporary failure.
+.SH OPTIONS
+The following options may be given to
+.I uux.
+.TP 5
+.B \-, \-p, \-\-stdin
+Read standard input and use it as the standard input for the command
+to be executed.
+.TP 5
+.B \-c, \-\-nocopy
+Do not copy local files to the spool directory.  This is the default.
+If they are
+removed before being processed by the
+.I uucico
+(8) daemon, the copy will fail.  The files must be readable by the
+.I uucico
+(8) daemon,
+as well as the by the invoker of
+.I uux.
+.TP 5
+.B \-C, \-\-copy
+Copy local files to the spool directory.
+.TP 5
+.B \-l, \-\-link
+Link local files into the spool directory.  If a file can not be
+linked because it is on a different device, it will be copied unless
+one of the
+.B \-c
+or
+.B \-\-nocopy
+options also appears (in other words, use of
+.B \-\-link
+switches the default from
+.B \-\-nocopy
+to
+.B \-\-copy).
+If the files are changed before being processed by the
+.I uucico
+(8) daemon, the changed versions will be used.  The files must be
+readable by the
+.I uucico
+(8) daemon, as well as by the invoker of
+.I uux.
+.TP 5
+.B \-g grade, \-\-grade grade
+Set the grade of the file transfer command.  Jobs of a higher grade
+are executed first.  Grades run 0 ... 9 A ... Z a ... z from high to
+low.
+.TP 5
+.B \-n, \-\-notification=no
+Do not send mail about the status of the job, even if it fails.
+.TP 5
+.B \-z, \-\-notification=error
+Send mail about the status of the job if an error occurs.  For many
+.I uuxqt
+daemons, including the Taylor UUCP
+.I uuxqt,
+this is the default action; for those,
+.B \-\-notification=error
+will have no effect.  However, some
+.I uuxqt
+daemons will send mail if the job succeeds unless the
+.B \-\-notification=error
+option is used, and some other
+.I uuxqt
+daemons will not send mail if the job fails unless the
+.B \-\-notification=error
+option is used.
+.TP 5
+.B \-r, \-\-nouucico
+Do not start the
+.I uucico
+(8) daemon immediately; merely queue up the execution request for later
+processing.
+.TP 5
+.B \-j, \-\-jobid
+Print jobids on standard output.  A jobid will be generated for each
+file copy operation required to perform the operation.  These file
+copies may be cancelled by passing the jobid to the
+.B \-\-kill
+switch of
+.I uustat
+(1), which will make the execution impossible to complete.
+.TP 5
+.B \-a address, \-\-requestor address
+Report job status to the specified e-mail address.
+.TP 5
+.B \-x type, \-\-debug type
+Turn on particular debugging types.  The following types are
+recognized: abnormal, chat, handshake, uucp-proto, proto, port,
+config, spooldir, execute, incoming, outgoing.  Only abnormal, config,
+spooldir and execute are meaningful for
+.I uux.
+
+Multiple types may be given, separated by commas, and the
+.B \-\-debug
+option may appear multiple times.  A number may also be given, which
+will turn on that many types from the foregoing list; for example,
+.B \-\-debug 2
+is equivalent to
+.B \-\-debug abnormal,chat.
+.TP 5
+.B \-I file, \-\-config file
+Set configuration file to use.  This option may not be available,
+depending upon how
+.I uux
+was compiled.
+.TP 5
+.B \-v, \-\-version
+Report version information and exit.
+.TP 5
+.B \-\-help
+Print a help message and exit.
+.SH EXAMPLES
+.br
+.nf
+uux -z - sys1!rmail user1
+.fi
+Execute the command ``rmail user1'' on the system sys1, giving it as
+standard input whatever is given to
+.I uux
+as standard input.  If a failure occurs, send a message using
+.I mail
+(1).
+
+.br
+.nf
+uux 'diff -c sys1!~user1/file1 sys2!~user2/file2 >!file.diff'
+.fi
+Fetch the two named files from system sys1 and system sys2 and execute
+.I diff
+putting the result in file.diff in the current directory.  The current
+directory must be writable by the
+.I uuxqt
+(8) daemon for this to work.
+
+.br
+.nf
+uux 'sys1!uucp ~user1/file1 (sys2!~user2/file2)'
+.fi
+Execute 
+.I uucp
+on the system sys1 copying file1 (on system sys1) to sys2.  This
+illustrates the use of parentheses for quoting.
+.SH RESTRICTIONS
+The remote system may not permit you to execute certain commands.
+Many remote systems only permit the execution of
+.I rmail
+and
+.I rnews.
+
+Some of the options are dependent on the capabilities of the
+.I uuxqt
+(8) daemon on the remote system.
+.SH SEE ALSO
+mail(1), uustat(1), uucp(1), uucico(8), uuxqt(8)
+.SH BUGS
+Files can not be referenced across multiple systems.
+
+Too many jobids are output by
+.B \-\-jobid,
+and there is no good way to cancel a local execution requiring remote
+files.
+.SH AUTHOR
+Ian Lance Taylor
+(ian@airs.com)
diff --git a/upstream/mageia-cauldron/man1/vacation.1 b/upstream/mageia-cauldron/man1/vacation.1
new file mode 100644
index 00000000..158fab1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/vacation.1
@@ -0,0 +1,285 @@
+.\" Copyright (c) 1999-2002 Proofpoint, Inc. and its suppliers.
+.\"	All rights reserved.
+.\" Copyright (c) 1985, 1987, 1990, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\"
+.\" By using this file, you agree to the terms and conditions set
+.\" forth in the LICENSE file which can be found at the top level of
+.\" the sendmail distribution.
+.\"
+.\"
+.\"	$Id: vacation.1,v 8.35 2013-11-22 20:52:02 ca Exp $
+.\"
+.TH VACATION 1 "$Date: 2013-11-22 20:52:02 $"
+.SH NAME
+vacation
+\- E-mail auto-responder
+.SH SYNOPSIS
+.B vacation
+.RB [ \-a
+.IR alias ]
+.RB [ \-C
+.IR cffile ]
+.RB [ \-d ]
+.RB [ \-f
+.IR database ]
+.RB [ \-i ]
+.RB [ \-I ]
+.RB [ \-j ]
+.RB [ \-l ]
+.RB [ \-m
+.IR message ]
+.RB [ \-R
+.IR returnaddr ]
+.RB [ \-r
+.IR interval ]
+.RB [ \-s
+.IR address ]
+.RB [ \-t
+.IR time ]
+.RB [ \-U ]
+.RB [ \-x ]
+.RB [ \-z ]
+.I login
+.SH DESCRIPTION
+.B Vacation
+returns a message,
+.IR ~/.vacation.msg
+by default, to the sender informing them that you are currently not
+reading your mail.
+The message is only sent to each sender once per reply interval (see
+.B \-r
+below).
+The intended use is in a
+.I .forward
+file.  For example, your
+.I .forward
+file might have:
+.IP
+\eeric, "|/usr/bin/vacation -a allman eric"
+.PP
+which would send messages to you (assuming your login name was eric) and
+reply to any messages for
+``eric''
+or
+``allman''.
+.PP
+Available options:
+.TP
+.BI \-a " alias"
+Handle messages for
+.I alias
+in the same manner as those received for the user's
+login name.
+.TP
+.BI \-C " cfpath"
+Specify pathname of the sendmail configuration file.
+This option is ignored if
+.B \-U
+is specified.
+This option defaults to the standard sendmail configuration file,
+located at /etc/mail/sendmail.cf on most systems.
+.TP
+.B \-d
+Send error/debug messages to stderr instead of syslog.
+Otherwise, fatal errors, such as calling
+.B vacation
+with incorrect arguments, or with non-existent
+.IR login s,
+are logged in the system log file, using
+syslog(8).
+This should only be used on the command line, not in your
+.I .forward
+file.
+.TP
+.BI \-f " filename"
+Use
+.I filename
+as name of the database instead of
+.IR ~/.vacation.db
+or
+.IR ~/.vacation.{dir,pag} .
+Unless the
+.I filename
+starts with / it is relative to ~.
+.TP
+.B \-i
+Initialize the vacation database files.  It should be used
+before you modify your
+.I .forward
+file.
+This should only be used on the command line, not in your
+.I .forward
+file.
+.TP
+.B \-I
+Same as
+.B \-i
+(for backwards compatibility).
+This should only be used on the command line, not in your
+.I .forward
+file.
+.TP
+.B \-j
+Respond to the message regardless of whether the login is listed as
+a recipient for the message.
+Do not use this flag unless you are sure of the consequences.
+For example, this will cause
+.i vacation
+to reply to mailing list messages which may result in removing
+you from the list.
+.TP
+.B \-l
+List the content of the vacation database file including the address
+and the associated time of the last auto-response to that address.
+This should only be used on the command line, not in your
+.I .forward
+file.
+.TP
+.BI \-m " filename"
+Use
+.I filename
+as name of the file containing the message to send instead of
+.IR ~/.vacation.msg .
+Unless the
+.I filename
+starts with / it is relative to ~.
+.TP
+.BI \-R " returnaddr"
+Set the reply envelope sender address
+.TP
+.BI \-r " interval"
+Set the reply interval to
+.I interval
+days.  The default is one week.
+An interval of ``0'' or
+``infinite''
+(actually, any non-numeric character) will never send more than
+one reply.
+The
+.B \-r
+option should only be used when the vacation database is initialized
+(see
+.B \-i
+above).
+.TP
+.BI \-s " address"
+Use
+.I address
+instead of the incoming message sender address on the
+.I From
+line as the recipient for the vacation message.
+.TP
+.BI \-t " time"
+Ignored, available only for compatibility with Sun's
+vacation program.
+.TP
+.B \-U
+Do not attempt to lookup
+.I login
+in the password file.
+The -f and -m options must be used to specify the database and message file
+since there is no home directory for the default settings for these options.
+.TP
+.B \-x
+Reads an exclusion list from stdin (one address per line).
+Mails coming from an address
+in this exclusion list won't get a reply by
+.BR vacation .
+It is possible to exclude complete domains by specifying
+``@domain''
+as element of the exclusion list.
+This should only be used on the command line, not in your
+.I .forward
+file.
+.TP
+.B \-z
+Set the sender of the vacation message to
+``<>''
+instead of the user.
+This probably violates the RFCs since vacation messages are
+not required by a standards-track RFC to have a null reverse-path.
+.PP
+.B Vacation
+reads the first line from the standard input for a
+UNIX
+``From''
+line to determine the sender.
+Sendmail(8)
+includes this
+``From''
+line automatically.
+.PP
+No message will be sent unless
+.I login
+(or an
+.I alias
+supplied using the
+.B \-a
+option) is part of either the
+``To:''
+or
+``Cc:''
+headers of the mail.
+No messages from
+``???-REQUEST'',
+``???-RELAY'',
+``???-OWNER'',
+``OWNER-???'',
+``Postmaster'',
+``UUCP'',
+``MAILER'',
+or
+``MAILER-DAEMON''
+will be replied to (where these strings are
+case insensitive) nor is a notification sent if a
+``Precedence: bulk''
+or
+``Precedence: junk''
+line is included in the mail headers.
+The people who have sent you messages are maintained as a
+db(3)
+or
+dbm(3)
+database in the file
+.I .vacation.db
+or
+.I .vacation.{dir,pag}
+in your home directory.
+.PP
+.B Vacation
+expects a file
+.IR .vacation.msg ,
+in your home directory, containing a message to be sent back to each
+sender.  It should be an entire message (including headers).  For
+example, it might contain:
+.IP
+.nf
+From: eric@CS.Berkeley.EDU (Eric Allman)
+Subject: I am on vacation
+Delivered-By-The-Graces-Of: The Vacation program
+Precedence: bulk
+
+I am on vacation until July 22.  If you have something urgent,
+please contact Keith Bostic <bostic@CS.Berkeley.EDU>.
+--eric
+.fi
+.SH FILES
+.TP 1.8i
+~/.vacation.db
+default database file for db(3)
+.TP 1.8i
+~/.vacation.{dir,pag}
+default database file for dbm(3)
+.TP
+~/.vacation.msg
+default message to send
+.SH SEE ALSO
+sendmail(8),
+syslog(8)
+.SH HISTORY
+The
+.B vacation
+command appeared in
+4.3BSD.
diff --git a/upstream/mageia-cauldron/man1/varlinkctl.1 b/upstream/mageia-cauldron/man1/varlinkctl.1
new file mode 100644
index 00000000..61b4aa3c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/varlinkctl.1
@@ -0,0 +1,324 @@
+'\" t
+.TH "VARLINKCTL" "1" "" "systemd 255" "varlinkctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+varlinkctl \- Introspect with and invoke Varlink services
+.SH "SYNOPSIS"
+.HP \w'\fBvarlinkctl\fR\ 'u
+\fBvarlinkctl\fR [OPTIONS...] info \fIADDRESS\fR
+.HP \w'\fBvarlinkctl\fR\ 'u
+\fBvarlinkctl\fR [OPTIONS...] list\-interfaces \fIADDRESS\fR
+.HP \w'\fBvarlinkctl\fR\ 'u
+\fBvarlinkctl\fR [OPTIONS...] introspect \fIADDRESS\fR \fIINTERFACE\fR
+.HP \w'\fBvarlinkctl\fR\ 'u
+\fBvarlinkctl\fR [OPTIONS...] call \fIADDRESS\fR \fIMETHOD\fR [\fIPARAMETERS\fR]
+.HP \w'\fBvarlinkctl\fR\ 'u
+\fBvarlinkctl\fR [OPTIONS...] validate\-idl [\fIFILE\fR]
+.SH "DESCRIPTION"
+.PP
+\fBvarlinkctl\fR
+may be used to introspect and invoke
+\m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
+services\&.
+.PP
+Services are referenced by one of the following:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A Varlink service reference starting with the
+"unix:"
+string, followed by an absolute
+\fBAF_UNIX\fR
+path, or by
+"@"
+and an arbitrary string (the latter for referencing sockets in the abstract namespace)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A Varlink service reference starting with the
+"exec:"
+string, followed by an absolute path of a binary to execute\&.
+.RE
+.PP
+For convenience these two simpler (redundant) service address syntaxes are also supported:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A file system path to an
+\fBAF_UNIX\fR
+socket, either absolute (i\&.e\&. begins with
+"/") or relative (in which case it must begin with
+"\&./")\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+A file system path to an executable, either absolute or relative (as above, must begin with
+"/", resp\&.
+"\&./")\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBinfo\fR \fIADDRESS\fR
+.RS 4
+Show brief information about the specified service, including vendor name and list of implemented interfaces\&. Expects a service address in the formats described above\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBlist\-interfaces\fR \fIADDRESS\fR
+.RS 4
+Show list of interfaces implemented by the specified service\&. Expects a service address in the formats described above\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBintrospect\fR \fIADDRESS\fR \fIINTERFACE\fR
+.RS 4
+Show interface definition of the specified interface provided by the specified service\&. Expects a service address in the formats described above and a Varlink interface name\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBcall\fR \fIADDRESS\fR \fIMETHOD\fR [\fIARGUMENTS\fR]
+.RS 4
+Call the specified method of the specified service\&. Expects a service address in the format described above, a fully qualified Varlink method name, and a JSON arguments object\&. If the arguments object is not specified, it is read from STDIN instead\&. To pass an empty list of parameters, specify the empty object
+"{}"\&.
+.sp
+The reply parameters are written as JSON object to STDOUT\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBvalidate\-idl\fR [\fIFILE\fR]
+.RS 4
+Reads a Varlink interface definition file, parses and validates it, then outputs it with syntax highlighting\&. This checks for syntax and internal consistency of the interface\&. Expects a file name to read the interface definition from\&. If omitted reads the interface definition from STDIN\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fBhelp\fR
+.RS 4
+Show command syntax help\&.
+.sp
+Added in version 255\&.
+.RE
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-more\fR
+.RS 4
+When used with
+\fBcall\fR: expect multiple method replies\&. If this flag is set the method call is sent with the
+\fBmore\fR
+flag set, which tells the service to generate multiple replies, if needed\&. The command remains running until the service sends a reply message that indicates it is the last in the series\&. This flag should be set only for method calls that support this mechanism\&.
+.sp
+If this mode is enabled output is automatically switched to JSON\-SEQ mode, so that individual reply objects can be easily discerned\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-oneway\fR
+.RS 4
+When used with
+\fBcall\fR: do not expect a method reply\&. If this flag is set the method call is sent with the
+\fBoneway\fR
+flag set (the command exits immediately after), which tells the service not to generate a reply\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIMODE\fR
+.RS 4
+Selects the JSON output formatting, one of
+"pretty"
+(for nicely indented, colorized output) or
+"short"
+(for terse output with minimal whitespace and no newlines), defaults to
+"short"\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-j\fR
+.RS 4
+Equivalent to
+\fB\-\-json=pretty\fR
+when invoked interactively from a terminal\&. Otherwise equivalent to
+\fB\-\-json=short\fR, in particular when the output is piped to some other program\&.
+.sp
+Added in version 255\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Investigating a Service\fR
+.PP
+The following three commands inspect the
+"io\&.systemd\&.Resolve"
+service implemented by
+\fBsystemd-resolved.service\fR(8), listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ varlinkctl info /run/systemd/resolve/io\&.systemd\&.Resolve
+    Vendor: The systemd Project
+   Product: systemd (systemd\-resolved)
+   Version: 254 (254\-1522\-g4790521^)
+       URL: https://systemd\&.io/
+Interfaces: io\&.systemd
+            io\&.systemd\&.Resolve
+            org\&.varlink\&.service
+$ varlinkctl list\-interfaces /run/systemd/resolve/io\&.systemd\&.Resolve
+io\&.systemd
+io\&.systemd\&.Resolve
+org\&.varlink\&.service
+$ varlinkctl introspect /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve
+interface io\&.systemd\&.Resolve
+type ResolvedAddress(
+        ifindex: ?int,
+        \&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+(Interface definition has been truncated in the example above, in the interest of brevity\&.)
+.PP
+\fBExample\ \&2.\ \&Invoking a Method\fR
+.PP
+The following command resolves a hostname via
+\fBsystemd-resolved.service\fR(8)\*(Aqs
+\fBResolveHostname\fR
+method call\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ varlinkctl call /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve\&.ResolveHostname \*(Aq{"name":"systemd\&.io","family":2}\*(Aq \-j
+{
+        "addresses" : [
+                {
+                        "ifindex" : 2,
+                        "family" : 2,
+                        "address" : [
+                                185,
+                                199,
+                                111,
+                                153
+                        ]
+                }
+        ],
+        "name" : "systemd\&.io",
+        "flags" : 1048577
+}
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&3.\ \&Investigating a Service Executable\fR
+.PP
+The following command inspects the
+/usr/lib/systemd/systemd\-pcrextend
+executable and the IPC APIs it provides\&. It then invokes a method on it:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# varlinkctl info /usr/lib/systemd/systemd\-pcrextend
+    Vendor: The systemd Project
+   Product: systemd (systemd\-pcrextend)
+   Version: 254 (254\-1536\-g97734fb)
+       URL: https://systemd\&.io/
+Interfaces: io\&.systemd
+            io\&.systemd\&.PCRExtend
+            org\&.varlink\&.service
+# varlinkctl introspect /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend
+interface io\&.systemd\&.PCRExtend
+
+method Extend(
+        pcr: int,
+        text: ?string,
+        data: ?string
+) \-> ()
+# varlinkctl call /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend\&.Extend \*(Aq{"pcr":15,"text":"foobar"}\*(Aq
+{}
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBbusctl\fR(1),
+\m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
+.SH "NOTES"
+.IP " 1." 4
+Varlink
+.RS 4
+\%https://varlink.org/
+.RE
diff --git a/upstream/mageia-cauldron/man1/vcut.1 b/upstream/mageia-cauldron/man1/vcut.1
new file mode 100644
index 00000000..84761b99
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/vcut.1
@@ -0,0 +1,30 @@
+.\" Process this file with
+.\" groff -man -Tascii vcut.1
+.\"
+.TH VCUT 1 "2003 September 1" "Xiph.Org Foundation" "Vorbis Tools"
+
+.SH NAME
+vcut \- cuts Ogg Vorbis files
+
+.SH SYNOPSIS
+.B vcut
+.I infile.ogg
+.I outfile1.ogg
+.I outfile2.ogg
+.I [ cutpoint | +cutpoint]
+
+.SH DESCRIPTION
+.B vcut
+reads an Ogg Vorbis audio file and splits it at the given cutpoint, which is a
+sample number.  If the cutpoint is prefixed with '+', the cutpoint is an
+integer number of seconds.
+
+.SH AUTHORS
+
+.TP
+Program Author:
+Michael Smith <msmith@xiph.org>
+
+.TP
+Manpage Author:
+Christoper L Cheney <ccheney@debian.org>
diff --git a/upstream/mageia-cauldron/man1/vdir.1 b/upstream/mageia-cauldron/man1/vdir.1
new file mode 100644
index 00000000..d701dc6c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/vdir.1
@@ -0,0 +1,264 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH VDIR "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+vdir \- list directory contents
+.SH SYNOPSIS
+.B vdir
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+List information about the FILEs (the current directory by default).
+Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with .
+.TP
+\fB\-A\fR, \fB\-\-almost\-all\fR
+do not list implied . and ..
+.TP
+\fB\-\-author\fR
+with \fB\-l\fR, print the author of each file
+.TP
+\fB\-b\fR, \fB\-\-escape\fR
+print C\-style escapes for nongraphic characters
+.TP
+\fB\-\-block\-size\fR=\fI\,SIZE\/\fR
+with \fB\-l\fR, scale sizes by SIZE when printing them;
+e.g., '\-\-block\-size=M'; see SIZE format below
+.TP
+\fB\-B\fR, \fB\-\-ignore\-backups\fR
+do not list implied entries ending with ~
+.TP
+\fB\-c\fR
+with \fB\-lt\fR: sort by, and show, ctime (time of last
+modification of file status information);
+with \fB\-l\fR: show ctime and sort by name;
+otherwise: sort by ctime, newest first
+.TP
+\fB\-C\fR
+list entries by columns
+.TP
+\fB\-\-color\fR[=\fI\,WHEN\/\fR]
+color the output WHEN; more info below
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+list directories themselves, not their contents
+.TP
+\fB\-D\fR, \fB\-\-dired\fR
+generate output designed for Emacs' dired mode
+.TP
+\fB\-f\fR
+list all entries in directory order
+.TP
+\fB\-F\fR, \fB\-\-classify\fR[=\fI\,WHEN\/\fR]
+append indicator (one of */=>@|) to entries WHEN
+.TP
+\fB\-\-file\-type\fR
+likewise, except do not append '*'
+.TP
+\fB\-\-format\fR=\fI\,WORD\/\fR
+across \fB\-x\fR, commas \fB\-m\fR, horizontal \fB\-x\fR, long \fB\-l\fR,
+single\-column \fB\-1\fR, verbose \fB\-l\fR, vertical \fB\-C\fR
+.TP
+\fB\-\-full\-time\fR
+like \fB\-l\fR \fB\-\-time\-style\fR=\fI\,full\-iso\/\fR
+.TP
+\fB\-g\fR
+like \fB\-l\fR, but do not list owner
+.TP
+\fB\-\-group\-directories\-first\fR
+group directories before files;
+can be augmented with a \fB\-\-sort\fR option, but any
+use of \fB\-\-sort\fR=\fI\,none\/\fR (\fB\-U\fR) disables grouping
+.TP
+\fB\-G\fR, \fB\-\-no\-group\fR
+in a long listing, don't print group names
+.TP
+\fB\-h\fR, \fB\-\-human\-readable\fR
+with \fB\-l\fR and \fB\-s\fR, print sizes like 1K 234M 2G etc.
+.TP
+\fB\-\-si\fR
+likewise, but use powers of 1000 not 1024
+.TP
+\fB\-H\fR, \fB\-\-dereference\-command\-line\fR
+follow symbolic links listed on the command line
+.TP
+\fB\-\-dereference\-command\-line\-symlink\-to\-dir\fR
+follow each command line symbolic link
+that points to a directory
+.TP
+\fB\-\-hide\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+(overridden by \fB\-a\fR or \fB\-A\fR)
+.TP
+\fB\-\-hyperlink\fR[=\fI\,WHEN\/\fR]
+hyperlink file names WHEN
+.TP
+\fB\-\-indicator\-style\fR=\fI\,WORD\/\fR
+append indicator with style WORD to entry names:
+none (default), slash (\fB\-p\fR),
+file\-type (\fB\-\-file\-type\fR), classify (\fB\-F\fR)
+.TP
+\fB\-i\fR, \fB\-\-inode\fR
+print the index number of each file
+.TP
+\fB\-I\fR, \fB\-\-ignore\fR=\fI\,PATTERN\/\fR
+do not list implied entries matching shell PATTERN
+.TP
+\fB\-k\fR, \fB\-\-kibibytes\fR
+default to 1024\-byte blocks for file system usage;
+used only with \fB\-s\fR and per directory totals
+.TP
+\fB\-l\fR
+use a long listing format
+.TP
+\fB\-L\fR, \fB\-\-dereference\fR
+when showing file information for a symbolic
+link, show information for the file the link
+references rather than for the link itself
+.TP
+\fB\-m\fR
+fill width with a comma separated list of entries
+.TP
+\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR
+like \fB\-l\fR, but list numeric user and group IDs
+.TP
+\fB\-N\fR, \fB\-\-literal\fR
+print entry names without quoting
+.TP
+\fB\-o\fR
+like \fB\-l\fR, but do not list group information
+.TP
+\fB\-p\fR, \fB\-\-indicator\-style\fR=\fI\,slash\/\fR
+append / indicator to directories
+.TP
+\fB\-q\fR, \fB\-\-hide\-control\-chars\fR
+print ? instead of nongraphic characters
+.TP
+\fB\-\-show\-control\-chars\fR
+show nongraphic characters as\-is (the default,
+unless program is 'ls' and output is a terminal)
+.TP
+\fB\-Q\fR, \fB\-\-quote\-name\fR
+enclose entry names in double quotes
+.TP
+\fB\-\-quoting\-style\fR=\fI\,WORD\/\fR
+use quoting style WORD for entry names:
+literal, locale, shell, shell\-always,
+shell\-escape, shell\-escape\-always, c, escape
+(overrides QUOTING_STYLE environment variable)
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse order while sorting
+.TP
+\fB\-R\fR, \fB\-\-recursive\fR
+list subdirectories recursively
+.TP
+\fB\-s\fR, \fB\-\-size\fR
+print the allocated size of each file, in blocks
+.TP
+\fB\-S\fR
+sort by file size, largest first
+.TP
+\fB\-\-sort\fR=\fI\,WORD\/\fR
+sort by WORD instead of name: none (\fB\-U\fR), size (\fB\-S\fR),
+time (\fB\-t\fR), version (\fB\-v\fR), extension (\fB\-X\fR), width
+.TP
+\fB\-\-time\fR=\fI\,WORD\/\fR
+change the default of using modification times;
+access time (\fB\-u\fR): atime, access, use;
+change time (\fB\-c\fR): ctime, status;
+birth time: birth, creation;
+.IP
+with \fB\-l\fR, WORD determines which time to show;
+with \fB\-\-sort\fR=\fI\,time\/\fR, sort by WORD (newest first)
+.TP
+\fB\-\-time\-style\fR=\fI\,TIME_STYLE\/\fR
+time/date format with \fB\-l\fR; see TIME_STYLE below
+.TP
+\fB\-t\fR
+sort by time, newest first; see \fB\-\-time\fR
+.TP
+\fB\-T\fR, \fB\-\-tabsize\fR=\fI\,COLS\/\fR
+assume tab stops at each COLS instead of 8
+.TP
+\fB\-u\fR
+with \fB\-lt\fR: sort by, and show, access time;
+with \fB\-l\fR: show access time and sort by name;
+otherwise: sort by access time, newest first
+.TP
+\fB\-U\fR
+do not sort; list entries in directory order
+.TP
+\fB\-v\fR
+natural sort of (version) numbers within text
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,COLS\/\fR
+set output width to COLS.  0 means no limit
+.TP
+\fB\-x\fR
+list entries by lines instead of by columns
+.TP
+\fB\-X\fR
+sort alphabetically by entry extension
+.TP
+\fB\-Z\fR, \fB\-\-context\fR
+print any security context of each file
+.TP
+\fB\-\-zero\fR
+end each output line with NUL, not newline
+.TP
+\fB\-1\fR
+list one file per line
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
+Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).
+Binary prefixes can be used, too: KiB=K, MiB=M, and so on.
+.PP
+The TIME_STYLE argument can be full\-iso, long\-iso, iso, locale, or +FORMAT.
+FORMAT is interpreted like in \fBdate\fP(1).  If FORMAT is FORMAT1<newline>FORMAT2,
+then FORMAT1 applies to non\-recent files and FORMAT2 to recent files.
+TIME_STYLE prefixed with 'posix\-' takes effect only outside the POSIX locale.
+Also the TIME_STYLE environment variable sets the default style to use.
+.PP
+The WHEN argument defaults to 'always' and can also be 'auto' or 'never'.
+.PP
+Using color to distinguish file types is disabled both by default and
+with \fB\-\-color\fR=\fI\,never\/\fR.  With \fB\-\-color\fR=\fI\,auto\/\fR, ls emits color codes only when
+standard output is connected to a terminal.  The LS_COLORS environment
+variable can change the settings.  Use the \fBdircolors\fP(1) command to set it.
+.SS "Exit status:"
+.TP
+0
+if OK,
+.TP
+1
+if minor problems (e.g., cannot access subdirectory),
+.TP
+2
+if serious trouble (e.g., cannot access command\-line argument).
+.SH AUTHOR
+Written by Richard M. Stallman and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/vdir>
+.br
+or available locally via: info \(aq(coreutils) vdir invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/vlock.1 b/upstream/mageia-cauldron/man1/vlock.1
new file mode 100644
index 00000000..c0e6e5e4
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/vlock.1
@@ -0,0 +1,49 @@
+.TH VLOCK 1 "16 May 1996" "kbd"
+.SH NAME
+vlock \- Virtual Console lock program
+.SH SYNOPSIS
+.B vlock
+.PP
+.B vlock [ -a,--all ] [ -c,--current ] [ -h,--help ] [ -v,--version ]
+.SH DESCRIPTION
+.B vlock
+is a program to lock one or more sessions on the Linux console.  This is
+especially useful for Linux machines which have multiple users with access
+to the console.  One user may lock his or her session(s) while still allowing
+other users to use the system on other virtual consoles.  If desired, the
+entire console may be locked and virtual console switching disabled.
+.PP
+By default, only the current VC (virtual console) is locked.  With the
+\fB-a,-all\fR option all VCs are locked.  The locked VCs cannot be unlocked
+without the invoker's password.  And, for the paranoid,
+vlock makes it a trying experience for those attempting to guess the
+password, so unauthorized access to session(s) is highly unlikely.
+.PP
+Please note that it is entirely possible to completely lock yourself out of
+the console with the \fB-a,--all\fR option if you cannot remember your
+password!  Unless you are able to kill vlock by logging in remotely via a
+serial terminal or network, a hard reset is the only method of ``unlocking''
+the display.
+.PP
+\fBvlock\fR works for console sessions primarily.  However, there is
+support for trying to lock non-console sessions as well, but that
+support has not been well tested.
+.SH OPTIONS
+.B -a,--all
+.IP
+Lock all console sessions and disable VC switching.
+.PP
+.B -c,--current
+.IP
+Lock the current session (this is the default).
+.PP
+.B -h,--help
+.IP
+Print a brief help message.
+.PP
+.B -v,--version
+.IP
+Print the version number of \fBvlock\fR.
+.PP
+.SH AUTHOR
+Michael K. Johnson <johnsonm@redhat.com>
diff --git a/upstream/mageia-cauldron/man1/vorbiscomment.1 b/upstream/mageia-cauldron/man1/vorbiscomment.1
new file mode 100644
index 00000000..0211b468
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/vorbiscomment.1
@@ -0,0 +1,112 @@
+.\" Process this file with
+.\" groff -man -Tascii vorbiscomment.1
+.\"
+.TH VORBISCOMMENT 1 "December 30, 2008" "Xiph.Org Foundation" "Ogg Vorbis Tools"
+
+.SH NAME
+vorbiscomment \- List or edit comments in Ogg Vorbis files
+
+.SH SYNOPSIS
+.B vorbiscomment
+.B [-l]
+.RB [ -R ]
+.RB [ -e ]
+.I file.ogg
+.br
+.B vorbiscomment
+.B -a
+.B [ -c commentfile | -t \*(lqname=value\*(rq | -d \*(lqname=value\*(rq ]
+.RB [ -q ]
+.RB [ -R ]
+.RB [ -e ]
+.I in.ogg
+.I [out.ogg]
+.br
+.B vorbiscomment
+.B -w
+.B [ -c commentfile | -t \*(lqname=value\*(rq ]
+.RB [ -q ]
+.RB [ -R ]
+.RB [ -e ]
+.I in.ogg
+.I [out.ogg]
+
+.SH DESCRIPTION
+.B vorbiscomment
+Reads, modifies, and appends Ogg Vorbis audio file metadata tags.
+
+.SH OPTIONS
+.IP "-a, --append"
+Updates comments.
+.IP "-c file, --commentfile file"
+Take comments from a file. The file is the same format as is output by the the -l option or given to the -t option: one element per line in 'tag=value' format. If the file is /dev/null and -w was passed, the existing comments will be removed.
+.IP "-h, --help"
+Show command help.
+.IP "-l, --list"
+List the comments in the Ogg Vorbis file.
+.IP "-q, --quiet"
+Quiet mode.  No messages are displayed.
+.IP "-t 'name=value', --tag 'name=value'"
+Specify a new tag on the command line. Each tag is given as a single string. The part before the '=' is treated as the tag name and the part after as the value.
+.IP "-d 'name[=value]', --rm 'name[=value]'"
+Specify a tag on the command line for removal. Each tag is given as a single string. The part before the '=' is treated as the tag name and the part after as the value. If no value is given all tags are deleted with the given name. Otherwise only those with matching values are deleted.
+.IP "-w, --write"
+Replace comments with the new set given either on the command line with -t or from a file with -c. If neither -c nor -t is given, the new set will be read from the standard input.
+.IP "-R, --raw"
+Read and write comments in UTF-8, rather than converting to the user's character set.
+.IP "-e, --escapes"
+Quote/unquote newlines and backslashes in the comments. This ensures every comment is exactly one line in the output (or input), allowing to filter and round-trip them. Without it, you can only write multi-line comments by using -t and you can't reliably distinguish them from multiple one-line comments.
+
+Supported escapes are c-style "\en", "\er", "\e\e" and "\e0". A backslash followed by anything else is an error.
+
+Note: currently, anything after the first "\e0" is thrown away while writing.  This is a bug -- the Vorbis format can safely store null characters, but most other tools wouldn't handle them anyway.
+.IP "-V, --version"
+Display the version of vorbiscomment.
+
+.\" Examples go here
+.SH EXAMPLES
+
+To just see what comment tags are in a file:
+
+    vorbiscomment -l file.ogg
+
+To edit those comments:
+
+    vorbiscomment -l file.ogg > file.txt
+    [edit the comments in file.txt to your satisfaction]
+    vorbiscomment -w -c file.txt file.ogg newfile.ogg
+
+To simply add a comment:
+
+    vorbiscomment -a -t 'ARTIST=No One You Know' file.ogg newfile.ogg
+
+To add a set of comments from the standard input:
+
+    vorbiscomment -a file.ogg
+    ARTIST=No One You Know
+    ALBUM=The Famous Album
+    <ctrl-d>
+
+.SH TAG FORMAT
+
+See https://xiph.org/vorbis/doc/v-comment.html for documentation on the Ogg Vorbis tag format, including a suggested list of canonical tag names.
+
+.SH AUTHORS
+
+.TP
+Program Authors:
+.br
+Michael Smith <msmith@xiph.org>
+.br
+Ralph Giles <giles@xiph.org>
+.br
+
+.TP
+Manpage Author:
+.br
+Christopher L Cheney <ccheney@debian.org>
+
+.SH "SEE ALSO"
+
+.PP
+\fBoggenc\fR(1), \fBoggdec\fR(1), \fBogg123\fR(1), \fBogginfo\fR(1)
diff --git a/upstream/mageia-cauldron/man1/wbmptopbm.1 b/upstream/mageia-cauldron/man1/wbmptopbm.1
new file mode 100644
index 00000000..2d5879ab
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/wbmptopbm.1
@@ -0,0 +1,64 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Wbmptopbm User Manual" 0 "19 November 1999" "netpbm documentation"
+
+.SH NAME
+
+wbmptopbm - convert a wireless bitmap (wbmp) file to a PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBwbmptopbm\fP
+
+[\fIwbmpfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBwbmptopbm\fP reads a wbmp file as input and produces a PBM
+image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBwbmptopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBwbmptopbm\fP recognizes only WBMP type 0.  This is the only
+type specified in the WAP 1.1 specifications.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbm" (1)\c
+\&,
+.BR "pbmtowbmp" (1)\c
+\&,
+
+Wireless Application Environment Specification.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1999 Terje Sannum <\fIterje@looplab.com\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/wbmptopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/wc.1 b/upstream/mageia-cauldron/man1/wc.1
new file mode 100644
index 00000000..7f2d63f7
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/wc.1
@@ -0,0 +1,63 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH WC "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+wc \- print newline, word, and byte counts for each file
+.SH SYNOPSIS
+.B wc
+[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+.br
+.B wc
+[\fI\,OPTION\/\fR]... \fI\,--files0-from=F\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print newline, word, and byte counts for each FILE, and a total line if
+more than one FILE is specified.  A word is a non\-zero\-length sequence of
+printable characters delimited by white space.
+.PP
+With no FILE, or when FILE is \-, read standard input.
+.PP
+The options below may be used to select which counts are printed, always in
+the following order: newline, word, character, byte, maximum line length.
+.TP
+\fB\-c\fR, \fB\-\-bytes\fR
+print the byte counts
+.TP
+\fB\-m\fR, \fB\-\-chars\fR
+print the character counts
+.TP
+\fB\-l\fR, \fB\-\-lines\fR
+print the newline counts
+.TP
+\fB\-\-files0\-from\fR=\fI\,F\/\fR
+read input from the files specified by
+NUL\-terminated names in file F;
+If F is \- then read names from standard input
+.TP
+\fB\-L\fR, \fB\-\-max\-line\-length\fR
+print the maximum display width
+.TP
+\fB\-w\fR, \fB\-\-words\fR
+print the word counts
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Paul Rubin and David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/wc>
+.br
+or available locally via: info \(aq(coreutils) wc invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/wdiff.1 b/upstream/mageia-cauldron/man1/wdiff.1
new file mode 100644
index 00000000..29aa1199
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/wdiff.1
@@ -0,0 +1,98 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.45.1.
+.TH WDIFF "1" "April 2014" "wdiff 1.2.2" "User Commands"
+.SH NAME
+wdiff - display word differences between text files
+.SH SYNOPSIS
+.B wdiff
+[\fI\,OPTION\/\fR]... \fI\,FILE1 FILE2\/\fR
+.br
+.B wdiff
+\fI\,-d \/\fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]
+.SH DESCRIPTION
+wdiff \- Compares words in two files and report differences.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+\fB\-C\fR, \fB\-\-copyright\fR
+display copyright then exit
+.TP
+\fB\-1\fR, \fB\-\-no\-deleted\fR
+inhibit output of deleted words
+.TP
+\fB\-2\fR, \fB\-\-no\-inserted\fR
+inhibit output of inserted words
+.TP
+\fB\-3\fR, \fB\-\-no\-common\fR
+inhibit output of common words
+.TP
+\fB\-a\fR, \fB\-\-auto\-pager\fR
+automatically calls a pager
+.TP
+\fB\-d\fR, \fB\-\-diff\-input\fR
+use single unified diff as input
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help then exit
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+fold character case while comparing
+.TP
+\fB\-l\fR, \fB\-\-less\-mode\fR
+variation of printer mode for "less"
+.TP
+\fB\-n\fR, \fB\-\-avoid\-wraps\fR
+do not extend fields through newlines
+.TP
+\fB\-p\fR, \fB\-\-printer\fR
+overstrike as for printers
+.TP
+\fB\-s\fR, \fB\-\-statistics\fR
+say how many words deleted, inserted etc.
+.TP
+\fB\-t\fR, \fB\-\-terminal\fR
+use termcap as for terminal displays
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+display program version then exit
+.TP
+\fB\-w\fR, \fB\-\-start\-delete\fR=\fI\,STRING\/\fR
+string to mark beginning of delete region
+.TP
+\fB\-x\fR, \fB\-\-end\-delete\fR=\fI\,STRING\/\fR
+string to mark end of delete region
+.TP
+\fB\-y\fR, \fB\-\-start\-insert\fR=\fI\,STRING\/\fR
+string to mark beginning of insert region
+.TP
+\fB\-z\fR, \fB\-\-end\-insert\fR=\fI\,STRING\/\fR
+string to mark end of insert region
+.SH COMPATIBILITY
+Some options that used to provide some unique functionality are no
+longer recommended, but still recognized for the sake of backwards
+compatibility.
+.TP
+\fB\-K\fR, \fB\-\-no\-init\-term\fR
+Now synonymous to \fI\-\-terminal\fR, which never initializes the
+terminal.
+.SH AUTHOR
+Written by Franc,ois Pinard <pinard@iro.umontreal.ca>.
+.SH "REPORTING BUGS"
+Report bugs to <wdiff\-bugs@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1992, 1997, 1998, 1999, 2009, 2010, 2011, 2012 Free Software
+Foundation, Inc.
+.br
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+The full documentation for
+.B wdiff
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B wdiff
+programs are properly installed at your site, the command
+.IP
+.B info wdiff
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/wget.1 b/upstream/mageia-cauldron/man1/wget.1
new file mode 100644
index 00000000..6782cfaa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/wget.1
@@ -0,0 +1,2388 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "WGET 1"
+.TH WGET 1 "2023-05-22" "GNU Wget 1.21.4" "GNU Wget"
+.\" 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"
+Wget \- The non\-interactive network downloader.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+wget [\fIoption\fR]... [\fI\s-1URL\s0\fR]...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\s-1GNU\s0 Wget is a free utility for non-interactive download of files from
+the Web.  It supports \s-1HTTP, HTTPS,\s0 and \s-1FTP\s0 protocols, as
+well as retrieval through \s-1HTTP\s0 proxies.
+.PP
+Wget is non-interactive, meaning that it can work in the background,
+while the user is not logged on.  This allows you to start a retrieval
+and disconnect from the system, letting Wget finish the work.  By
+contrast, most of the Web browsers require constant user's presence,
+which can be a great hindrance when transferring a lot of data.
+.PP
+Wget can follow links in \s-1HTML, XHTML,\s0 and \s-1CSS\s0 pages, to
+create local versions of remote web sites, fully recreating the
+directory structure of the original site.  This is sometimes referred to
+as \*(L"recursive downloading.\*(R"  While doing that, Wget respects the Robot
+Exclusion Standard (\fI/robots.txt\fR).  Wget can be instructed to
+convert the links in downloaded files to point at the local files, for
+offline viewing.
+.PP
+Wget has been designed for robustness over slow or unstable network
+connections; if a download fails due to a network problem, it will
+keep retrying until the whole file has been retrieved.  If the server
+supports regetting, it will instruct the server to continue the
+download from where it left off.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.SS "Option Syntax"
+.IX Subsection "Option Syntax"
+Since Wget uses \s-1GNU\s0 getopt to process command-line arguments, every
+option has a long form along with the short one.  Long options are
+more convenient to remember, but take time to type.  You may freely
+mix different option styles, or specify options after the command-line
+arguments.  Thus you may write:
+.PP
+.Vb 1
+\&        wget \-r \-\-tries=10 http://fly.srk.fer.hr/ \-o log
+.Ve
+.PP
+The space between the option accepting an argument and the argument may
+be omitted.  Instead of \fB\-o log\fR you can write \fB\-olog\fR.
+.PP
+You may put several options that do not require arguments together,
+like:
+.PP
+.Vb 1
+\&        wget \-drc <URL>
+.Ve
+.PP
+This is completely equivalent to:
+.PP
+.Vb 1
+\&        wget \-d \-r \-c <URL>
+.Ve
+.PP
+Since the options can be specified after the arguments, you may
+terminate them with \fB\-\-\fR.  So the following will try to download
+\&\s-1URL\s0 \fB\-x\fR, reporting failure to \fIlog\fR:
+.PP
+.Vb 1
+\&        wget \-o log \-\- \-x
+.Ve
+.PP
+The options that accept comma-separated lists all respect the convention
+that specifying an empty list clears its value.  This can be useful to
+clear the \fI.wgetrc\fR settings.  For instance, if your \fI.wgetrc\fR
+sets \f(CW\*(C`exclude_directories\*(C'\fR to \fI/cgi\-bin\fR, the following
+example will first reset it, and then set it to exclude \fI/~nobody\fR
+and \fI/~somebody\fR.  You can also clear the lists in \fI.wgetrc\fR.
+.PP
+.Vb 1
+\&        wget \-X "" \-X /~nobody,/~somebody
+.Ve
+.PP
+Most options that do not accept arguments are \fIboolean\fR options,
+so named because their state can be captured with a yes-or-no
+(\*(L"boolean\*(R") variable.  For example, \fB\-\-follow\-ftp\fR tells Wget
+to follow \s-1FTP\s0 links from \s-1HTML\s0 files and, on the other hand,
+\&\fB\-\-no\-glob\fR tells it not to perform file globbing on \s-1FTP\s0 URLs.  A
+boolean option is either \fIaffirmative\fR or \fInegative\fR
+(beginning with \fB\-\-no\fR).  All such options share several
+properties.
+.PP
+Unless stated otherwise, it is assumed that the default behavior is
+the opposite of what the option accomplishes.  For example, the
+documented existence of \fB\-\-follow\-ftp\fR assumes that the default
+is to \fInot\fR follow \s-1FTP\s0 links from \s-1HTML\s0 pages.
+.PP
+Affirmative options can be negated by prepending the \fB\-\-no\-\fR to
+the option name; negative options can be negated by omitting the
+\&\fB\-\-no\-\fR prefix.  This might seem superfluous\-\-\-if the default for
+an affirmative option is to not do something, then why provide a way
+to explicitly turn it off?  But the startup file may in fact change
+the default.  For instance, using \f(CW\*(C`follow_ftp = on\*(C'\fR in
+\&\fI.wgetrc\fR makes Wget \fIfollow\fR \s-1FTP\s0 links by default, and
+using \fB\-\-no\-follow\-ftp\fR is the only way to restore the factory
+default from the command line.
+.SS "Basic Startup Options"
+.IX Subsection "Basic Startup Options"
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Display the version of Wget.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Print a help message describing all of Wget's command-line options.
+.IP "\fB\-b\fR" 4
+.IX Item "-b"
+.PD 0
+.IP "\fB\-\-background\fR" 4
+.IX Item "--background"
+.PD
+Go to background immediately after startup.  If no output file is
+specified via the \fB\-o\fR, output is redirected to \fIwget-log\fR.
+.IP "\fB\-e\fR \fIcommand\fR" 4
+.IX Item "-e command"
+.PD 0
+.IP "\fB\-\-execute\fR \fIcommand\fR" 4
+.IX Item "--execute command"
+.PD
+Execute \fIcommand\fR as if it were a part of \fI.wgetrc\fR.  A command thus invoked will be executed
+\&\fIafter\fR the commands in \fI.wgetrc\fR, thus taking precedence over
+them.  If you need to specify more than one wgetrc command, use multiple
+instances of \fB\-e\fR.
+.SS "Logging and Input File Options"
+.IX Subsection "Logging and Input File Options"
+.IP "\fB\-o\fR \fIlogfile\fR" 4
+.IX Item "-o logfile"
+.PD 0
+.IP "\fB\-\-output\-file=\fR\fIlogfile\fR" 4
+.IX Item "--output-file=logfile"
+.PD
+Log all messages to \fIlogfile\fR.  The messages are normally reported
+to standard error.
+.IP "\fB\-a\fR \fIlogfile\fR" 4
+.IX Item "-a logfile"
+.PD 0
+.IP "\fB\-\-append\-output=\fR\fIlogfile\fR" 4
+.IX Item "--append-output=logfile"
+.PD
+Append to \fIlogfile\fR.  This is the same as \fB\-o\fR, only it appends
+to \fIlogfile\fR instead of overwriting the old log file.  If
+\&\fIlogfile\fR does not exist, a new file is created.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-\-debug\fR" 4
+.IX Item "--debug"
+.PD
+Turn on debug output, meaning various information important to the
+developers of Wget if it does not work properly.  Your system
+administrator may have chosen to compile Wget without debug support, in
+which case \fB\-d\fR will not work.  Please note that compiling with
+debug support is always safe\-\-\-Wget compiled with the debug support will
+\&\fInot\fR print any debug info unless requested with \fB\-d\fR.
+.IP "\fB\-q\fR" 4
+.IX Item "-q"
+.PD 0
+.IP "\fB\-\-quiet\fR" 4
+.IX Item "--quiet"
+.PD
+Turn off Wget's output.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-verbose\fR" 4
+.IX Item "--verbose"
+.PD
+Turn on verbose output, with all the available data.  The default output
+is verbose.
+.IP "\fB\-nv\fR" 4
+.IX Item "-nv"
+.PD 0
+.IP "\fB\-\-no\-verbose\fR" 4
+.IX Item "--no-verbose"
+.PD
+Turn off verbose without being completely quiet (use \fB\-q\fR for
+that), which means that error messages and basic information still get
+printed.
+.IP "\fB\-\-report\-speed=\fR\fItype\fR" 4
+.IX Item "--report-speed=type"
+Output bandwidth as \fItype\fR.  The only accepted value is \fBbits\fR.
+.IP "\fB\-i\fR \fIfile\fR" 4
+.IX Item "-i file"
+.PD 0
+.IP "\fB\-\-input\-file=\fR\fIfile\fR" 4
+.IX Item "--input-file=file"
+.PD
+Read URLs from a local or external \fIfile\fR.  If \fB\-\fR is
+specified as \fIfile\fR, URLs are read from the standard input.  
+(Use \fB./\-\fR to read from a file literally named \fB\-\fR.)
+.Sp
+If this function is used, no URLs need be present on the command
+line.  If there are URLs both on the command line and in an input
+file, those on the command lines will be the first ones to be
+retrieved.  If \fB\-\-force\-html\fR is not specified, then \fIfile\fR
+should consist of a series of URLs, one per line.
+.Sp
+However, if you specify \fB\-\-force\-html\fR, the document will be
+regarded as \fBhtml\fR.  In that case you may have problems with
+relative links, which you can solve either by adding \f(CW\*(C`<base
+href="\f(CIurl\f(CW">\*(C'\fR to the documents or by specifying
+\&\fB\-\-base=\fR\fIurl\fR on the command line.
+.Sp
+If the \fIfile\fR is an external one, the document will be automatically
+treated as \fBhtml\fR if the Content-Type matches \fBtext/html\fR.
+Furthermore, the \fIfile\fR's location will be implicitly used as base
+href if none was specified.
+.IP "\fB\-\-input\-metalink=\fR\fIfile\fR" 4
+.IX Item "--input-metalink=file"
+Downloads files covered in local Metalink \fIfile\fR. Metalink version 3
+and 4 are supported.
+.IP "\fB\-\-keep\-badhash\fR" 4
+.IX Item "--keep-badhash"
+Keeps downloaded Metalink's files with a bad hash. It appends .badhash
+to the name of Metalink's files which have a checksum mismatch, except
+without overwriting existing files.
+.IP "\fB\-\-metalink\-over\-http\fR" 4
+.IX Item "--metalink-over-http"
+Issues \s-1HTTP HEAD\s0 request instead of \s-1GET\s0 and extracts Metalink metadata
+from response headers. Then it switches to Metalink download.
+If no valid Metalink metadata is found, it falls back to ordinary \s-1HTTP\s0 download.
+Enables \fBContent-Type: application/metalink4+xml\fR files download/processing.
+.IP "\fB\-\-metalink\-index=\fR\fInumber\fR" 4
+.IX Item "--metalink-index=number"
+Set the Metalink \fBapplication/metalink4+xml\fR metaurl ordinal
+\&\s-1NUMBER.\s0 From 1 to the total number of \*(L"application/metalink4+xml\*(R"
+available.  Specify 0 or \fBinf\fR to choose the first good one.
+Metaurls, such as those from a \fB\-\-metalink\-over\-http\fR, may have
+been sorted by priority key's value; keep this in mind to choose the
+right \s-1NUMBER.\s0
+.IP "\fB\-\-preferred\-location\fR" 4
+.IX Item "--preferred-location"
+Set preferred location for Metalink resources. This has effect if multiple
+resources with same priority are available.
+.IP "\fB\-\-xattr\fR" 4
+.IX Item "--xattr"
+Enable use of file system's extended attributes to save the
+original \s-1URL\s0 and the Referer \s-1HTTP\s0 header value if used.
+.Sp
+Be aware that the \s-1URL\s0 might contain private information like
+access tokens or credentials.
+.IP "\fB\-F\fR" 4
+.IX Item "-F"
+.PD 0
+.IP "\fB\-\-force\-html\fR" 4
+.IX Item "--force-html"
+.PD
+When input is read from a file, force it to be treated as an \s-1HTML\s0
+file.  This enables you to retrieve relative links from existing
+\&\s-1HTML\s0 files on your local disk, by adding \f(CW\*(C`<base
+href="\f(CIurl\f(CW">\*(C'\fR to \s-1HTML,\s0 or using the \fB\-\-base\fR command-line
+option.
+.IP "\fB\-B\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-B URL"
+.PD 0
+.IP "\fB\-\-base=\fR\fI\s-1URL\s0\fR" 4
+.IX Item "--base=URL"
+.PD
+Resolves relative links using \fI\s-1URL\s0\fR as the point of reference,
+when reading links from an \s-1HTML\s0 file specified via the
+\&\fB\-i\fR/\fB\-\-input\-file\fR option (together with
+\&\fB\-\-force\-html\fR, or when the input file was fetched remotely from
+a server describing it as \s-1HTML\s0). This is equivalent to the
+presence of a \f(CW\*(C`BASE\*(C'\fR tag in the \s-1HTML\s0 input file, with
+\&\fI\s-1URL\s0\fR as the value for the \f(CW\*(C`href\*(C'\fR attribute.
+.Sp
+For instance, if you specify \fBhttp://foo/bar/a.html\fR for
+\&\fI\s-1URL\s0\fR, and Wget reads \fB../baz/b.html\fR from the input file, it
+would be resolved to \fBhttp://foo/baz/b.html\fR.
+.IP "\fB\-\-config=\fR\fI\s-1FILE\s0\fR" 4
+.IX Item "--config=FILE"
+Specify the location of a startup file you wish to use instead of the
+default one(s). Use \-\-no\-config to disable reading of config files.
+If both \-\-config and \-\-no\-config are given, \-\-no\-config is ignored.
+.IP "\fB\-\-rejected\-log=\fR\fIlogfile\fR" 4
+.IX Item "--rejected-log=logfile"
+Logs all \s-1URL\s0 rejections to \fIlogfile\fR as comma separated values.  The values
+include the reason of rejection, the \s-1URL\s0 and the parent \s-1URL\s0 it was found in.
+.SS "Download Options"
+.IX Subsection "Download Options"
+.IP "\fB\-\-bind\-address=\fR\fI\s-1ADDRESS\s0\fR" 4
+.IX Item "--bind-address=ADDRESS"
+When making client \s-1TCP/IP\s0 connections, bind to \fI\s-1ADDRESS\s0\fR on
+the local machine.  \fI\s-1ADDRESS\s0\fR may be specified as a hostname or \s-1IP\s0
+address.  This option can be useful if your machine is bound to multiple
+IPs.
+.IP "\fB\-\-bind\-dns\-address=\fR\fI\s-1ADDRESS\s0\fR" 4
+.IX Item "--bind-dns-address=ADDRESS"
+[libcares only]
+This address overrides the route for \s-1DNS\s0 requests. If you ever need to
+circumvent the standard settings from /etc/resolv.conf, this option together
+with \fB\-\-dns\-servers\fR is your friend.
+\&\fI\s-1ADDRESS\s0\fR must be specified either as IPv4 or IPv6 address.
+Wget needs to be built with libcares for this option to be available.
+.IP "\fB\-\-dns\-servers=\fR\fI\s-1ADDRESSES\s0\fR" 4
+.IX Item "--dns-servers=ADDRESSES"
+[libcares only]
+The given address(es) override the standard nameserver
+addresses,  e.g. as configured in /etc/resolv.conf.
+\&\fI\s-1ADDRESSES\s0\fR may be specified either as IPv4 or IPv6 addresses,
+comma-separated.
+Wget needs to be built with libcares for this option to be available.
+.IP "\fB\-t\fR \fInumber\fR" 4
+.IX Item "-t number"
+.PD 0
+.IP "\fB\-\-tries=\fR\fInumber\fR" 4
+.IX Item "--tries=number"
+.PD
+Set number of tries to \fInumber\fR. Specify 0 or \fBinf\fR for
+infinite retrying.  The default is to retry 20 times, with the exception
+of fatal errors like \*(L"connection refused\*(R" or \*(L"not found\*(R" (404),
+which are not retried.
+.IP "\fB\-O\fR \fIfile\fR" 4
+.IX Item "-O file"
+.PD 0
+.IP "\fB\-\-output\-document=\fR\fIfile\fR" 4
+.IX Item "--output-document=file"
+.PD
+The documents will not be written to the appropriate files, but all
+will be concatenated together and written to \fIfile\fR.  If \fB\-\fR
+is used as \fIfile\fR, documents will be printed to standard output,
+disabling link conversion.  (Use \fB./\-\fR to print to a file
+literally named \fB\-\fR.)
+.Sp
+Use of \fB\-O\fR is \fInot\fR intended to mean simply "use the name
+\&\fIfile\fR instead of the one in the \s-1URL\s0;" rather, it is
+analogous to shell redirection:
+\&\fBwget \-O file http://foo\fR is intended to work like
+\&\fBwget \-O \- http://foo > file\fR; \fIfile\fR will be truncated
+immediately, and \fIall\fR downloaded content will be written there.
+.Sp
+For this reason, \fB\-N\fR (for timestamp-checking) is not supported
+in combination with \fB\-O\fR: since \fIfile\fR is always newly
+created, it will always have a very new timestamp. A warning will be
+issued if this combination is used.
+.Sp
+Similarly, using \fB\-r\fR or \fB\-p\fR with \fB\-O\fR may not work as
+you expect: Wget won't just download the first file to \fIfile\fR and
+then download the rest to their normal names: \fIall\fR downloaded
+content will be placed in \fIfile\fR. This was disabled in version
+1.11, but has been reinstated (with a warning) in 1.11.2, as there are
+some cases where this behavior can actually have some use.
+.Sp
+A combination with \fB\-nc\fR is only accepted if the given output
+file does not exist.
+.Sp
+Note that a combination with \fB\-k\fR is only permitted when
+downloading a single document, as in that case it will just convert
+all relative URIs to external ones; \fB\-k\fR makes no sense for
+multiple URIs when they're all being downloaded to a single file;
+\&\fB\-k\fR can be used only when the output is a regular file.
+.IP "\fB\-nc\fR" 4
+.IX Item "-nc"
+.PD 0
+.IP "\fB\-\-no\-clobber\fR" 4
+.IX Item "--no-clobber"
+.PD
+If a file is downloaded more than once in the same directory, Wget's
+behavior depends on a few options, including \fB\-nc\fR.  In certain
+cases, the local file will be \fIclobbered\fR, or overwritten, upon
+repeated download.  In other cases it will be preserved.
+.Sp
+When running Wget without \fB\-N\fR, \fB\-nc\fR, \fB\-r\fR, or
+\&\fB\-p\fR, downloading the same file in the same directory will result
+in the original copy of \fIfile\fR being preserved and the second copy
+being named \fIfile\fR\fB.1\fR.  If that file is downloaded yet
+again, the third copy will be named \fIfile\fR\fB.2\fR, and so on.
+(This is also the behavior with \fB\-nd\fR, even if \fB\-r\fR or
+\&\fB\-p\fR are in effect.)  When \fB\-nc\fR is specified, this behavior
+is suppressed, and Wget will refuse to download newer copies of
+\&\fIfile\fR.  Therefore, "\f(CW\*(C`no\-clobber\*(C'\fR" is actually a
+misnomer in this mode\-\-\-it's not clobbering that's prevented (as the
+numeric suffixes were already preventing clobbering), but rather the
+multiple version saving that's prevented.
+.Sp
+When running Wget with \fB\-r\fR or \fB\-p\fR, but without \fB\-N\fR,
+\&\fB\-nd\fR, or \fB\-nc\fR, re-downloading a file will result in the
+new copy simply overwriting the old.  Adding \fB\-nc\fR will prevent
+this behavior, instead causing the original version to be preserved
+and any newer copies on the server to be ignored.
+.Sp
+When running Wget with \fB\-N\fR, with or without \fB\-r\fR or
+\&\fB\-p\fR, the decision as to whether or not to download a newer copy
+of a file depends on the local and remote timestamp and size of the
+file.  \fB\-nc\fR may not be specified at the
+same time as \fB\-N\fR.
+.Sp
+A combination with \fB\-O\fR/\fB\-\-output\-document\fR is only accepted
+if the given output file does not exist.
+.Sp
+Note that when \fB\-nc\fR is specified, files with the suffixes
+\&\fB.html\fR or \fB.htm\fR will be loaded from the local disk and
+parsed as if they had been retrieved from the Web.
+.IP "\fB\-\-backups=\fR\fIbackups\fR" 4
+.IX Item "--backups=backups"
+Before (over)writing a file, back up an existing file by adding a
+\&\fB.1\fR suffix (\fB_1\fR on \s-1VMS\s0) to the file name.  Such backup
+files are rotated to \fB.2\fR, \fB.3\fR, and so on, up to
+\&\fIbackups\fR (and lost beyond that).
+.IP "\fB\-\-no\-netrc\fR" 4
+.IX Item "--no-netrc"
+Do not try to obtain credentials from \fI.netrc\fR file. By default
+\&\fI.netrc\fR file is searched for credentials in case none have been
+passed on command line and authentication is required.
+.IP "\fB\-c\fR" 4
+.IX Item "-c"
+.PD 0
+.IP "\fB\-\-continue\fR" 4
+.IX Item "--continue"
+.PD
+Continue getting a partially-downloaded file.  This is useful when you
+want to finish up a download started by a previous instance of Wget, or
+by another program.  For instance:
+.Sp
+.Vb 1
+\&        wget \-c ftp://sunsite.doc.ic.ac.uk/ls\-lR.Z
+.Ve
+.Sp
+If there is a file named \fIls\-lR.Z\fR in the current directory, Wget
+will assume that it is the first portion of the remote file, and will
+ask the server to continue the retrieval from an offset equal to the
+length of the local file.
+.Sp
+Note that you don't need to specify this option if you just want the
+current invocation of Wget to retry downloading a file should the
+connection be lost midway through.  This is the default behavior.
+\&\fB\-c\fR only affects resumption of downloads started \fIprior\fR to
+this invocation of Wget, and whose local files are still sitting around.
+.Sp
+Without \fB\-c\fR, the previous example would just download the remote
+file to \fIls\-lR.Z.1\fR, leaving the truncated \fIls\-lR.Z\fR file
+alone.
+.Sp
+If you use \fB\-c\fR on a non-empty file, and the server does not support
+continued downloading, Wget will restart the download from scratch and overwrite
+the existing file entirely.
+.Sp
+Beginning with Wget 1.7, if you use \fB\-c\fR on a file which is of
+equal size as the one on the server, Wget will refuse to download the
+file and print an explanatory message.  The same happens when the file
+is smaller on the server than locally (presumably because it was changed
+on the server since your last download attempt)\-\-\-because \*(L"continuing\*(R"
+is not meaningful, no download occurs.
+.Sp
+On the other side of the coin, while using \fB\-c\fR, any file that's
+bigger on the server than locally will be considered an incomplete
+download and only \f(CW\*(C`(length(remote) \- length(local))\*(C'\fR bytes will be
+downloaded and tacked onto the end of the local file.  This behavior can
+be desirable in certain cases\-\-\-for instance, you can use \fBwget \-c\fR
+to download just the new portion that's been appended to a data
+collection or log file.
+.Sp
+However, if the file is bigger on the server because it's been
+\&\fIchanged\fR, as opposed to just \fIappended\fR to, you'll end up
+with a garbled file.  Wget has no way of verifying that the local file
+is really a valid prefix of the remote file.  You need to be especially
+careful of this when using \fB\-c\fR in conjunction with \fB\-r\fR,
+since every file will be considered as an \*(L"incomplete download\*(R" candidate.
+.Sp
+Another instance where you'll get a garbled file if you try to use
+\&\fB\-c\fR is if you have a lame \s-1HTTP\s0 proxy that inserts a
+\&\*(L"transfer interrupted\*(R" string into the local file.  In the future a
+\&\*(L"rollback\*(R" option may be added to deal with this case.
+.Sp
+Note that \fB\-c\fR only works with \s-1FTP\s0 servers and with \s-1HTTP\s0
+servers that support the \f(CW\*(C`Range\*(C'\fR header.
+.IP "\fB\-\-start\-pos=\fR\fI\s-1OFFSET\s0\fR" 4
+.IX Item "--start-pos=OFFSET"
+Start downloading at zero-based position \fI\s-1OFFSET\s0\fR.  Offset may be expressed
+in bytes, kilobytes with the `k' suffix, or megabytes with the `m' suffix, etc.
+.Sp
+\&\fB\-\-start\-pos\fR has higher precedence over \fB\-\-continue\fR.  When
+\&\fB\-\-start\-pos\fR and \fB\-\-continue\fR are both specified, wget will emit a
+warning then proceed as if \fB\-\-continue\fR was absent.
+.Sp
+Server support for continued download is required, otherwise \fB\-\-start\-pos\fR
+cannot help.  See \fB\-c\fR for details.
+.IP "\fB\-\-progress=\fR\fItype\fR" 4
+.IX Item "--progress=type"
+Select the type of the progress indicator you wish to use.  Legal
+indicators are \*(L"dot\*(R" and \*(L"bar\*(R".
+.Sp
+The \*(L"bar\*(R" indicator is used by default.  It draws an \s-1ASCII\s0 progress
+bar graphics (a.k.a \*(L"thermometer\*(R" display) indicating the status of
+retrieval.  If the output is not a \s-1TTY,\s0 the \*(L"dot\*(R" bar will be used by
+default.
+.Sp
+Use \fB\-\-progress=dot\fR to switch to the \*(L"dot\*(R" display.  It traces
+the retrieval by printing dots on the screen, each dot representing a
+fixed amount of downloaded data.
+.Sp
+The progress \fItype\fR can also take one or more parameters.  The parameters
+vary based on the \fItype\fR selected.  Parameters to \fItype\fR are passed by
+appending them to the type sperated by a colon (:) like this:
+\&\fB\-\-progress=\fR\fItype\fR\fB:\fR\fIparameter1\fR\fB:\fR\fIparameter2\fR.
+.Sp
+When using the dotted retrieval, you may set the \fIstyle\fR by
+specifying the type as \fBdot:\fR\fIstyle\fR.  Different styles assign
+different meaning to one dot.  With the \f(CW\*(C`default\*(C'\fR style each dot
+represents 1K, there are ten dots in a cluster and 50 dots in a line.
+The \f(CW\*(C`binary\*(C'\fR style has a more \*(L"computer\*(R"\-like orientation\-\-\-8K
+dots, 16\-dots clusters and 48 dots per line (which makes for 384K
+lines).  The \f(CW\*(C`mega\*(C'\fR style is suitable for downloading large
+files\-\-\-each dot represents 64K retrieved, there are eight dots in a
+cluster, and 48 dots on each line (so each line contains 3M).
+If \f(CW\*(C`mega\*(C'\fR is not enough then you can use the \f(CW\*(C`giga\*(C'\fR
+style\-\-\-each dot represents 1M retrieved, there are eight dots in a
+cluster, and 32 dots on each line (so each line contains 32M).
+.Sp
+With \fB\-\-progress=bar\fR, there are currently two possible parameters,
+\&\fIforce\fR and \fInoscroll\fR.
+.Sp
+When the output is not a \s-1TTY,\s0 the progress bar always falls back to \*(L"dot\*(R",
+even if \fB\-\-progress=bar\fR was passed to Wget during invocation. This
+behaviour can be overridden and the \*(L"bar\*(R" output forced by using the \*(L"force\*(R"
+parameter as \fB\-\-progress=bar:force\fR.
+.Sp
+By default, the \fBbar\fR style progress bar scroll the name of the file from
+left to right for the file being downloaded if the filename exceeds the maximum
+length allotted for its display.  In certain cases, such as with
+\&\fB\-\-progress=bar:force\fR, one may not want the scrolling filename in the
+progress bar.  By passing the \*(L"noscroll\*(R" parameter, Wget can be forced to
+display as much of the filename as possible without scrolling through it.
+.Sp
+Note that you can set the default style using the \f(CW\*(C`progress\*(C'\fR
+command in \fI.wgetrc\fR.  That setting may be overridden from the
+command line.  For example, to force the bar output without scrolling,
+use \fB\-\-progress=bar:force:noscroll\fR.
+.IP "\fB\-\-show\-progress\fR" 4
+.IX Item "--show-progress"
+Force wget to display the progress bar in any verbosity.
+.Sp
+By default, wget only displays the progress bar in verbose mode.  One may
+however, want wget to display the progress bar on screen in conjunction with
+any other verbosity modes like \fB\-\-no\-verbose\fR or \fB\-\-quiet\fR.  This
+is often a desired a property when invoking wget to download several small/large
+files.  In such a case, wget could simply be invoked with this parameter to get
+a much cleaner output on the screen.
+.Sp
+This option will also force the progress bar to be printed to \fIstderr\fR when
+used alongside the \fB\-\-output\-file\fR option.
+.IP "\fB\-N\fR" 4
+.IX Item "-N"
+.PD 0
+.IP "\fB\-\-timestamping\fR" 4
+.IX Item "--timestamping"
+.PD
+Turn on time-stamping.
+.IP "\fB\-\-no\-if\-modified\-since\fR" 4
+.IX Item "--no-if-modified-since"
+Do not send If-Modified-Since header in \fB\-N\fR mode. Send preliminary \s-1HEAD\s0
+request instead. This has only effect in \fB\-N\fR mode.
+.IP "\fB\-\-no\-use\-server\-timestamps\fR" 4
+.IX Item "--no-use-server-timestamps"
+Don't set the local file's timestamp by the one on the server.
+.Sp
+By default, when a file is downloaded, its timestamps are set to
+match those from the remote file. This allows the use of
+\&\fB\-\-timestamping\fR on subsequent invocations of wget. However, it
+is sometimes useful to base the local file's timestamp on when it was
+actually downloaded; for that purpose, the
+\&\fB\-\-no\-use\-server\-timestamps\fR option has been provided.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+.PD 0
+.IP "\fB\-\-server\-response\fR" 4
+.IX Item "--server-response"
+.PD
+Print the headers sent by \s-1HTTP\s0 servers and responses sent by
+\&\s-1FTP\s0 servers.
+.IP "\fB\-\-spider\fR" 4
+.IX Item "--spider"
+When invoked with this option, Wget will behave as a Web \fIspider\fR,
+which means that it will not download the pages, just check that they
+are there.  For example, you can use Wget to check your bookmarks:
+.Sp
+.Vb 1
+\&        wget \-\-spider \-\-force\-html \-i bookmarks.html
+.Ve
+.Sp
+This feature needs much more work for Wget to get close to the
+functionality of real web spiders.
+.IP "\fB\-T seconds\fR" 4
+.IX Item "-T seconds"
+.PD 0
+.IP "\fB\-\-timeout=\fR\fIseconds\fR" 4
+.IX Item "--timeout=seconds"
+.PD
+Set the network timeout to \fIseconds\fR seconds.  This is equivalent
+to specifying \fB\-\-dns\-timeout\fR, \fB\-\-connect\-timeout\fR, and
+\&\fB\-\-read\-timeout\fR, all at the same time.
+.Sp
+When interacting with the network, Wget can check for timeout and
+abort the operation if it takes too long.  This prevents anomalies
+like hanging reads and infinite connects.  The only timeout enabled by
+default is a 900\-second read timeout.  Setting a timeout to 0 disables
+it altogether.  Unless you know what you are doing, it is best not to
+change the default timeout settings.
+.Sp
+All timeout-related options accept decimal values, as well as
+subsecond values.  For example, \fB0.1\fR seconds is a legal (though
+unwise) choice of timeout.  Subsecond timeouts are useful for checking
+server response times or for testing network latency.
+.IP "\fB\-\-dns\-timeout=\fR\fIseconds\fR" 4
+.IX Item "--dns-timeout=seconds"
+Set the \s-1DNS\s0 lookup timeout to \fIseconds\fR seconds.  \s-1DNS\s0 lookups that
+don't complete within the specified time will fail.  By default, there
+is no timeout on \s-1DNS\s0 lookups, other than that implemented by system
+libraries.
+.IP "\fB\-\-connect\-timeout=\fR\fIseconds\fR" 4
+.IX Item "--connect-timeout=seconds"
+Set the connect timeout to \fIseconds\fR seconds.  \s-1TCP\s0 connections that
+take longer to establish will be aborted.  By default, there is no
+connect timeout, other than that implemented by system libraries.
+.IP "\fB\-\-read\-timeout=\fR\fIseconds\fR" 4
+.IX Item "--read-timeout=seconds"
+Set the read (and write) timeout to \fIseconds\fR seconds.  The
+\&\*(L"time\*(R" of this timeout refers to \fIidle time\fR: if, at any point in
+the download, no data is received for more than the specified number
+of seconds, reading fails and the download is restarted.  This option
+does not directly affect the duration of the entire download.
+.Sp
+Of course, the remote server may choose to terminate the connection
+sooner than this option requires.  The default read timeout is 900
+seconds.
+.IP "\fB\-\-limit\-rate=\fR\fIamount\fR" 4
+.IX Item "--limit-rate=amount"
+Limit the download speed to \fIamount\fR bytes per second.  Amount may
+be expressed in bytes, kilobytes with the \fBk\fR suffix, or megabytes
+with the \fBm\fR suffix.  For example, \fB\-\-limit\-rate=20k\fR will
+limit the retrieval rate to 20KB/s.  This is useful when, for whatever
+reason, you don't want Wget to consume the entire available bandwidth.
+.Sp
+This option allows the use of decimal numbers, usually in conjunction
+with power suffixes; for example, \fB\-\-limit\-rate=2.5k\fR is a legal
+value.
+.Sp
+Note that Wget implements the limiting by sleeping the appropriate
+amount of time after a network read that took less time than specified
+by the rate.  Eventually this strategy causes the \s-1TCP\s0 transfer to slow
+down to approximately the specified rate.  However, it may take some
+time for this balance to be achieved, so don't be surprised if limiting
+the rate doesn't work well with very small files.
+.IP "\fB\-w\fR \fIseconds\fR" 4
+.IX Item "-w seconds"
+.PD 0
+.IP "\fB\-\-wait=\fR\fIseconds\fR" 4
+.IX Item "--wait=seconds"
+.PD
+Wait the specified number of seconds between the retrievals.  Use of
+this option is recommended, as it lightens the server load by making the
+requests less frequent.  Instead of in seconds, the time can be
+specified in minutes using the \f(CW\*(C`m\*(C'\fR suffix, in hours using \f(CW\*(C`h\*(C'\fR
+suffix, or in days using \f(CW\*(C`d\*(C'\fR suffix.
+.Sp
+Specifying a large value for this option is useful if the network or the
+destination host is down, so that Wget can wait long enough to
+reasonably expect the network error to be fixed before the retry.  The
+waiting interval specified by this function is influenced by
+\&\f(CW\*(C`\-\-random\-wait\*(C'\fR, which see.
+.IP "\fB\-\-waitretry=\fR\fIseconds\fR" 4
+.IX Item "--waitretry=seconds"
+If you don't want Wget to wait between \fIevery\fR retrieval, but only
+between retries of failed downloads, you can use this option.  Wget will
+use \fIlinear backoff\fR, waiting 1 second after the first failure on a
+given file, then waiting 2 seconds after the second failure on that
+file, up to the maximum number of \fIseconds\fR you specify.
+.Sp
+By default, Wget will assume a value of 10 seconds.
+.IP "\fB\-\-random\-wait\fR" 4
+.IX Item "--random-wait"
+Some web sites may perform log analysis to identify retrieval programs
+such as Wget by looking for statistically significant similarities in
+the time between requests. This option causes the time between requests
+to vary between 0.5 and 1.5 * \fIwait\fR seconds, where \fIwait\fR was
+specified using the \fB\-\-wait\fR option, in order to mask Wget's
+presence from such analysis.
+.Sp
+A 2001 article in a publication devoted to development on a popular
+consumer platform provided code to perform this analysis on the fly.
+Its author suggested blocking at the class C address level to ensure
+automated retrieval programs were blocked despite changing DHCP-supplied
+addresses.
+.Sp
+The \fB\-\-random\-wait\fR option was inspired by this ill-advised
+recommendation to block many unrelated users from a web site due to the
+actions of one.
+.IP "\fB\-\-no\-proxy\fR" 4
+.IX Item "--no-proxy"
+Don't use proxies, even if the appropriate \f(CW*_proxy\fR environment
+variable is defined.
+.IP "\fB\-Q\fR \fIquota\fR" 4
+.IX Item "-Q quota"
+.PD 0
+.IP "\fB\-\-quota=\fR\fIquota\fR" 4
+.IX Item "--quota=quota"
+.PD
+Specify download quota for automatic retrievals.  The value can be
+specified in bytes (default), kilobytes (with \fBk\fR suffix), or
+megabytes (with \fBm\fR suffix).
+.Sp
+Note that quota will never affect downloading a single file.  So if you
+specify \fBwget \-Q10k https://example.com/ls\-lR.gz\fR, all of the
+\&\fIls\-lR.gz\fR will be downloaded.  The same goes even when several
+URLs are specified on the command-line.  The quota is checked only
+at the end of each downloaded file, so it will never result in a partially
+downloaded file. Thus you may safely type \fBwget \-Q2m \-i sites\fR\-\-\-download
+will be aborted after the file that exhausts the quota is completely
+downloaded.
+.Sp
+Setting quota to 0 or to \fBinf\fR unlimits the download quota.
+.IP "\fB\-\-no\-dns\-cache\fR" 4
+.IX Item "--no-dns-cache"
+Turn off caching of \s-1DNS\s0 lookups.  Normally, Wget remembers the \s-1IP\s0
+addresses it looked up from \s-1DNS\s0 so it doesn't have to repeatedly
+contact the \s-1DNS\s0 server for the same (typically small) set of hosts it
+retrieves from.  This cache exists in memory only; a new Wget run will
+contact \s-1DNS\s0 again.
+.Sp
+However, it has been reported that in some situations it is not
+desirable to cache host names, even for the duration of a
+short-running application like Wget.  With this option Wget issues a
+new \s-1DNS\s0 lookup (more precisely, a new call to \f(CW\*(C`gethostbyname\*(C'\fR or
+\&\f(CW\*(C`getaddrinfo\*(C'\fR) each time it makes a new connection.  Please note
+that this option will \fInot\fR affect caching that might be
+performed by the resolving library or by an external caching layer,
+such as \s-1NSCD.\s0
+.Sp
+If you don't understand exactly what this option does, you probably
+won't need it.
+.IP "\fB\-\-restrict\-file\-names=\fR\fImodes\fR" 4
+.IX Item "--restrict-file-names=modes"
+Change which characters found in remote URLs must be escaped during
+generation of local filenames.  Characters that are \fIrestricted\fR
+by this option are escaped, i.e. replaced with \fB\f(CB%HH\fB\fR, where
+\&\fB\s-1HH\s0\fR is the hexadecimal number that corresponds to the restricted
+character. This option may also be used to force all alphabetical
+cases to be either lower\- or uppercase.
+.Sp
+By default, Wget escapes the characters that are not valid or safe as
+part of file names on your operating system, as well as control
+characters that are typically unprintable.  This option is useful for
+changing these defaults, perhaps because you are downloading to a
+non-native partition, or because you want to disable escaping of the
+control characters, or you want to further restrict characters to only
+those in the \s-1ASCII\s0 range of values.
+.Sp
+The \fImodes\fR are a comma-separated set of text values. The
+acceptable values are \fBunix\fR, \fBwindows\fR, \fBnocontrol\fR,
+\&\fBascii\fR, \fBlowercase\fR, and \fBuppercase\fR. The values
+\&\fBunix\fR and \fBwindows\fR are mutually exclusive (one will
+override the other), as are \fBlowercase\fR and
+\&\fBuppercase\fR. Those last are special cases, as they do not change
+the set of characters that would be escaped, but rather force local
+file paths to be converted either to lower\- or uppercase.
+.Sp
+When \*(L"unix\*(R" is specified, Wget escapes the character \fB/\fR and
+the control characters in the ranges 0\-\-31 and 128\-\-159.  This is the
+default on Unix-like operating systems.
+.Sp
+When \*(L"windows\*(R" is given, Wget escapes the characters \fB\e\fR,
+\&\fB|\fR, \fB/\fR, \fB:\fR, \fB?\fR, \fB"\fR, \fB*\fR, \fB<\fR,
+\&\fB>\fR, and the control characters in the ranges 0\-\-31 and 128\-\-159.
+In addition to this, Wget in Windows mode uses \fB+\fR instead of
+\&\fB:\fR to separate host and port in local file names, and uses
+\&\fB@\fR instead of \fB?\fR to separate the query portion of the file
+name from the rest.  Therefore, a \s-1URL\s0 that would be saved as
+\&\fBwww.xemacs.org:4300/search.pl?input=blah\fR in Unix mode would be
+saved as \fBwww.xemacs.org+4300/search.pl@input=blah\fR in Windows
+mode.  This mode is the default on Windows.
+.Sp
+If you specify \fBnocontrol\fR, then the escaping of the control
+characters is also switched off. This option may make sense
+when you are downloading URLs whose names contain \s-1UTF\-8\s0 characters, on
+a system which can save and display filenames in \s-1UTF\-8\s0 (some possible
+byte values used in \s-1UTF\-8\s0 byte sequences fall in the range of values
+designated by Wget as \*(L"controls\*(R").
+.Sp
+The \fBascii\fR mode is used to specify that any bytes whose values
+are outside the range of \s-1ASCII\s0 characters (that is, greater than
+127) shall be escaped. This can be useful when saving filenames
+whose encoding does not match the one used locally.
+.IP "\fB\-4\fR" 4
+.IX Item "-4"
+.PD 0
+.IP "\fB\-\-inet4\-only\fR" 4
+.IX Item "--inet4-only"
+.IP "\fB\-6\fR" 4
+.IX Item "-6"
+.IP "\fB\-\-inet6\-only\fR" 4
+.IX Item "--inet6-only"
+.PD
+Force connecting to IPv4 or IPv6 addresses.  With \fB\-\-inet4\-only\fR
+or \fB\-4\fR, Wget will only connect to IPv4 hosts, ignoring \s-1AAAA\s0
+records in \s-1DNS,\s0 and refusing to connect to IPv6 addresses specified in
+URLs.  Conversely, with \fB\-\-inet6\-only\fR or \fB\-6\fR, Wget will
+only connect to IPv6 hosts and ignore A records and IPv4 addresses.
+.Sp
+Neither options should be needed normally.  By default, an IPv6\-aware
+Wget will use the address family specified by the host's \s-1DNS\s0 record.
+If the \s-1DNS\s0 responds with both IPv4 and IPv6 addresses, Wget will try
+them in sequence until it finds one it can connect to.  (Also see
+\&\f(CW\*(C`\-\-prefer\-family\*(C'\fR option described below.)
+.Sp
+These options can be used to deliberately force the use of IPv4 or
+IPv6 address families on dual family systems, usually to aid debugging
+or to deal with broken network configuration.  Only one of
+\&\fB\-\-inet6\-only\fR and \fB\-\-inet4\-only\fR may be specified at the
+same time.  Neither option is available in Wget compiled without IPv6
+support.
+.IP "\fB\-\-prefer\-family=none/IPv4/IPv6\fR" 4
+.IX Item "--prefer-family=none/IPv4/IPv6"
+When given a choice of several addresses, connect to the addresses
+with specified address family first.  The address order returned by
+\&\s-1DNS\s0 is used without change by default.
+.Sp
+This avoids spurious errors and connect attempts when accessing hosts
+that resolve to both IPv6 and IPv4 addresses from IPv4 networks.  For
+example, \fBwww.kame.net\fR resolves to
+\&\fB2001:200:0:8002:203:47ff:fea5:3085\fR and to
+\&\fB203.178.141.194\fR.  When the preferred family is \f(CW\*(C`IPv4\*(C'\fR, the
+IPv4 address is used first; when the preferred family is \f(CW\*(C`IPv6\*(C'\fR,
+the IPv6 address is used first; if the specified value is \f(CW\*(C`none\*(C'\fR,
+the address order returned by \s-1DNS\s0 is used without change.
+.Sp
+Unlike \fB\-4\fR and \fB\-6\fR, this option doesn't inhibit access to
+any address family, it only changes the \fIorder\fR in which the
+addresses are accessed.  Also note that the reordering performed by
+this option is \fIstable\fR\-\-\-it doesn't affect order of addresses of
+the same family.  That is, the relative order of all IPv4 addresses
+and of all IPv6 addresses remains intact in all cases.
+.IP "\fB\-\-retry\-connrefused\fR" 4
+.IX Item "--retry-connrefused"
+Consider \*(L"connection refused\*(R" a transient error and try again.
+Normally Wget gives up on a \s-1URL\s0 when it is unable to connect to the
+site because failure to connect is taken as a sign that the server is
+not running at all and that retries would not help.  This option is
+for mirroring unreliable sites whose servers tend to disappear for
+short periods of time.
+.IP "\fB\-\-user=\fR\fIuser\fR" 4
+.IX Item "--user=user"
+.PD 0
+.IP "\fB\-\-password=\fR\fIpassword\fR" 4
+.IX Item "--password=password"
+.PD
+Specify the username \fIuser\fR and password \fIpassword\fR for both
+\&\s-1FTP\s0 and \s-1HTTP\s0 file retrieval.  These parameters can be overridden
+using the \fB\-\-ftp\-user\fR and \fB\-\-ftp\-password\fR options for 
+\&\s-1FTP\s0 connections and the \fB\-\-http\-user\fR and \fB\-\-http\-password\fR 
+options for \s-1HTTP\s0 connections.
+.IP "\fB\-\-ask\-password\fR" 4
+.IX Item "--ask-password"
+Prompt for a password for each connection established. Cannot be specified
+when \fB\-\-password\fR is being used, because they are mutually exclusive.
+.IP "\fB\-\-use\-askpass=\fR\fIcommand\fR" 4
+.IX Item "--use-askpass=command"
+Prompt for a user and password using the specified command.  If no command is
+specified then the command in the environment variable \s-1WGET_ASKPASS\s0 is used.
+If \s-1WGET_ASKPASS\s0 is not set then the command in the environment variable
+\&\s-1SSH_ASKPASS\s0 is used.
+.Sp
+You can set the default command for use-askpass in the \fI.wgetrc\fR.  That
+setting may be overridden from the command line.
+.IP "\fB\-\-no\-iri\fR" 4
+.IX Item "--no-iri"
+Turn off internationalized \s-1URI\s0 (\s-1IRI\s0) support. Use \fB\-\-iri\fR to
+turn it on. \s-1IRI\s0 support is activated by default.
+.Sp
+You can set the default state of \s-1IRI\s0 support using the \f(CW\*(C`iri\*(C'\fR
+command in \fI.wgetrc\fR. That setting may be overridden from the
+command line.
+.IP "\fB\-\-local\-encoding=\fR\fIencoding\fR" 4
+.IX Item "--local-encoding=encoding"
+Force Wget to use \fIencoding\fR as the default system encoding. That affects
+how Wget converts URLs specified as arguments from locale to \s-1UTF\-8\s0 for
+\&\s-1IRI\s0 support.
+.Sp
+Wget use the function \f(CW\*(C`nl_langinfo()\*(C'\fR and then the \f(CW\*(C`CHARSET\*(C'\fR
+environment variable to get the locale. If it fails, \s-1ASCII\s0 is used.
+.Sp
+You can set the default local encoding using the \f(CW\*(C`local_encoding\*(C'\fR
+command in \fI.wgetrc\fR. That setting may be overridden from the
+command line.
+.IP "\fB\-\-remote\-encoding=\fR\fIencoding\fR" 4
+.IX Item "--remote-encoding=encoding"
+Force Wget to use \fIencoding\fR as the default remote server encoding.
+That affects how Wget converts URIs found in files from remote encoding
+to \s-1UTF\-8\s0 during a recursive fetch. This options is only useful for
+\&\s-1IRI\s0 support, for the interpretation of non-ASCII characters.
+.Sp
+For \s-1HTTP,\s0 remote encoding can be found in \s-1HTTP\s0 \f(CW\*(C`Content\-Type\*(C'\fR
+header and in \s-1HTML\s0 \f(CW\*(C`Content\-Type http\-equiv\*(C'\fR meta tag.
+.Sp
+You can set the default encoding using the \f(CW\*(C`remoteencoding\*(C'\fR
+command in \fI.wgetrc\fR. That setting may be overridden from the
+command line.
+.IP "\fB\-\-unlink\fR" 4
+.IX Item "--unlink"
+Force Wget to unlink file instead of clobbering existing file. This
+option is useful for downloading to the directory with hardlinks.
+.SS "Directory Options"
+.IX Subsection "Directory Options"
+.IP "\fB\-nd\fR" 4
+.IX Item "-nd"
+.PD 0
+.IP "\fB\-\-no\-directories\fR" 4
+.IX Item "--no-directories"
+.PD
+Do not create a hierarchy of directories when retrieving recursively.
+With this option turned on, all files will get saved to the current
+directory, without clobbering (if a name shows up more than once, the
+filenames will get extensions \fB.n\fR).
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+.PD 0
+.IP "\fB\-\-force\-directories\fR" 4
+.IX Item "--force-directories"
+.PD
+The opposite of \fB\-nd\fR\-\-\-create a hierarchy of directories, even if
+one would not have been created otherwise.  E.g. \fBwget \-x
+http://fly.srk.fer.hr/robots.txt\fR will save the downloaded file to
+\&\fIfly.srk.fer.hr/robots.txt\fR.
+.IP "\fB\-nH\fR" 4
+.IX Item "-nH"
+.PD 0
+.IP "\fB\-\-no\-host\-directories\fR" 4
+.IX Item "--no-host-directories"
+.PD
+Disable generation of host-prefixed directories.  By default, invoking
+Wget with \fB\-r http://fly.srk.fer.hr/\fR will create a structure of
+directories beginning with \fIfly.srk.fer.hr/\fR.  This option disables
+such behavior.
+.IP "\fB\-\-protocol\-directories\fR" 4
+.IX Item "--protocol-directories"
+Use the protocol name as a directory component of local file names.  For
+example, with this option, \fBwget \-r http://\fR\fIhost\fR will save to
+\&\fBhttp/\fR\fIhost\fR\fB/...\fR rather than just to \fIhost\fR\fB/...\fR.
+.IP "\fB\-\-cut\-dirs=\fR\fInumber\fR" 4
+.IX Item "--cut-dirs=number"
+Ignore \fInumber\fR directory components.  This is useful for getting a
+fine-grained control over the directory where recursive retrieval will
+be saved.
+.Sp
+Take, for example, the directory at
+\&\fBftp://ftp.xemacs.org/pub/xemacs/\fR.  If you retrieve it with
+\&\fB\-r\fR, it will be saved locally under
+\&\fIftp.xemacs.org/pub/xemacs/\fR.  While the \fB\-nH\fR option can
+remove the \fIftp.xemacs.org/\fR part, you are still stuck with
+\&\fIpub/xemacs\fR.  This is where \fB\-\-cut\-dirs\fR comes in handy; it
+makes Wget not \*(L"see\*(R" \fInumber\fR remote directory components.  Here
+are several examples of how \fB\-\-cut\-dirs\fR option works.
+.Sp
+.Vb 4
+\&        No options        \-> ftp.xemacs.org/pub/xemacs/
+\&        \-nH               \-> pub/xemacs/
+\&        \-nH \-\-cut\-dirs=1  \-> xemacs/
+\&        \-nH \-\-cut\-dirs=2  \-> .
+\&        
+\&        \-\-cut\-dirs=1      \-> ftp.xemacs.org/xemacs/
+\&        ...
+.Ve
+.Sp
+If you just want to get rid of the directory structure, this option is
+similar to a combination of \fB\-nd\fR and \fB\-P\fR.  However, unlike
+\&\fB\-nd\fR, \fB\-\-cut\-dirs\fR does not lose with subdirectories\-\-\-for
+instance, with \fB\-nH \-\-cut\-dirs=1\fR, a \fIbeta/\fR subdirectory will
+be placed to \fIxemacs/beta\fR, as one would expect.
+.IP "\fB\-P\fR \fIprefix\fR" 4
+.IX Item "-P prefix"
+.PD 0
+.IP "\fB\-\-directory\-prefix=\fR\fIprefix\fR" 4
+.IX Item "--directory-prefix=prefix"
+.PD
+Set directory prefix to \fIprefix\fR.  The \fIdirectory prefix\fR is the
+directory where all other files and subdirectories will be saved to,
+i.e. the top of the retrieval tree.  The default is \fB.\fR (the
+current directory).
+.SS "\s-1HTTP\s0 Options"
+.IX Subsection "HTTP Options"
+.IP "\fB\-\-default\-page=\fR\fIname\fR" 4
+.IX Item "--default-page=name"
+Use \fIname\fR as the default file name when it isn't known (i.e., for
+URLs that end in a slash), instead of \fIindex.html\fR.
+.IP "\fB\-E\fR" 4
+.IX Item "-E"
+.PD 0
+.IP "\fB\-\-adjust\-extension\fR" 4
+.IX Item "--adjust-extension"
+.PD
+If a file of type \fBapplication/xhtml+xml\fR or \fBtext/html\fR is 
+downloaded and the \s-1URL\s0 does not end with the regexp 
+\&\fB\e.[Hh][Tt][Mm][Ll]?\fR, this option will cause the suffix \fB.html\fR 
+to be appended to the local filename.  This is useful, for instance, when 
+you're mirroring a remote site that uses \fB.asp\fR pages, but you want 
+the mirrored pages to be viewable on your stock Apache server.  Another 
+good use for this is when you're downloading CGI-generated materials.  A \s-1URL\s0 
+like \fBhttp://site.com/article.cgi?25\fR will be saved as
+\&\fIarticle.cgi?25.html\fR.
+.Sp
+Note that filenames changed in this way will be re-downloaded every time
+you re-mirror a site, because Wget can't tell that the local
+\&\fI\fIX\fI.html\fR file corresponds to remote \s-1URL\s0 \fIX\fR (since
+it doesn't yet know that the \s-1URL\s0 produces output of type
+\&\fBtext/html\fR or \fBapplication/xhtml+xml\fR.
+.Sp
+As of version 1.12, Wget will also ensure that any downloaded files of
+type \fBtext/css\fR end in the suffix \fB.css\fR, and the option was
+renamed from \fB\-\-html\-extension\fR, to better reflect its new
+behavior. The old option name is still acceptable, but should now be
+considered deprecated.
+.Sp
+As of version 1.19.2, Wget will also ensure that any downloaded files with
+a \f(CW\*(C`Content\-Encoding\*(C'\fR of \fBbr\fR, \fBcompress\fR, \fBdeflate\fR
+or \fBgzip\fR end in the suffix \fB.br\fR, \fB.Z\fR, \fB.zlib\fR
+and \fB.gz\fR respectively.
+.Sp
+At some point in the future, this option may well be expanded to
+include suffixes for other types of content, including content types
+that are not parsed by Wget.
+.IP "\fB\-\-http\-user=\fR\fIuser\fR" 4
+.IX Item "--http-user=user"
+.PD 0
+.IP "\fB\-\-http\-password=\fR\fIpassword\fR" 4
+.IX Item "--http-password=password"
+.PD
+Specify the username \fIuser\fR and password \fIpassword\fR on an
+\&\s-1HTTP\s0 server.  According to the type of the challenge, Wget will
+encode them using either the \f(CW\*(C`basic\*(C'\fR (insecure),
+the \f(CW\*(C`digest\*(C'\fR, or the Windows \f(CW\*(C`NTLM\*(C'\fR authentication scheme.
+.Sp
+Another way to specify username and password is in the \s-1URL\s0 itself.  Either method reveals your password to anyone who
+bothers to run \f(CW\*(C`ps\*(C'\fR.  To prevent the passwords from being seen,
+use the \fB\-\-use\-askpass\fR or store them in \fI.wgetrc\fR or \fI.netrc\fR,
+and make sure to protect those files from other users with \f(CW\*(C`chmod\*(C'\fR.  If
+the passwords are really important, do not leave them lying in those files
+either\-\-\-edit the files and delete them after Wget has started the download.
+.IP "\fB\-\-no\-http\-keep\-alive\fR" 4
+.IX Item "--no-http-keep-alive"
+Turn off the \*(L"keep-alive\*(R" feature for \s-1HTTP\s0 downloads.  Normally, Wget
+asks the server to keep the connection open so that, when you download
+more than one document from the same server, they get transferred over
+the same \s-1TCP\s0 connection.  This saves time and at the same time reduces
+the load on the server.
+.Sp
+This option is useful when, for some reason, persistent (keep-alive)
+connections don't work for you, for example due to a server bug or due
+to the inability of server-side scripts to cope with the connections.
+.IP "\fB\-\-no\-cache\fR" 4
+.IX Item "--no-cache"
+Disable server-side cache.  In this case, Wget will send the remote
+server appropriate directives (\fBCache-Control: no-cache\fR and
+\&\fBPragma: no-cache\fR) to get the file from the remote service,
+rather than returning the cached version. This is especially useful
+for retrieving and flushing out-of-date documents on proxy servers.
+.Sp
+Caching is allowed by default.
+.IP "\fB\-\-no\-cookies\fR" 4
+.IX Item "--no-cookies"
+Disable the use of cookies.  Cookies are a mechanism for maintaining
+server-side state.  The server sends the client a cookie using the
+\&\f(CW\*(C`Set\-Cookie\*(C'\fR header, and the client responds with the same cookie
+upon further requests.  Since cookies allow the server owners to keep
+track of visitors and for sites to exchange this information, some
+consider them a breach of privacy.  The default is to use cookies;
+however, \fIstoring\fR cookies is not on by default.
+.IP "\fB\-\-load\-cookies\fR \fIfile\fR" 4
+.IX Item "--load-cookies file"
+Load cookies from \fIfile\fR before the first \s-1HTTP\s0 retrieval.
+\&\fIfile\fR is a textual file in the format originally used by Netscape's
+\&\fIcookies.txt\fR file.
+.Sp
+You will typically use this option when mirroring sites that require
+that you be logged in to access some or all of their content.  The login
+process typically works by the web server issuing an \s-1HTTP\s0 cookie
+upon receiving and verifying your credentials.  The cookie is then
+resent by the browser when accessing that part of the site, and so
+proves your identity.
+.Sp
+Mirroring such a site requires Wget to send the same cookies your
+browser sends when communicating with the site.  This is achieved by
+\&\fB\-\-load\-cookies\fR\-\-\-simply point Wget to the location of the
+\&\fIcookies.txt\fR file, and it will send the same cookies your browser
+would send in the same situation.  Different browsers keep textual
+cookie files in different locations:
+.RS 4
+.ie n .IP """Netscape 4.x.""" 4
+.el .IP "\f(CWNetscape 4.x.\fR" 4
+.IX Item "Netscape 4.x."
+The cookies are in \fI~/.netscape/cookies.txt\fR.
+.ie n .IP """Mozilla and Netscape 6.x.""" 4
+.el .IP "\f(CWMozilla and Netscape 6.x.\fR" 4
+.IX Item "Mozilla and Netscape 6.x."
+Mozilla's cookie file is also named \fIcookies.txt\fR, located
+somewhere under \fI~/.mozilla\fR, in the directory of your profile.
+The full path usually ends up looking somewhat like
+\&\fI~/.mozilla/default/\fIsome-weird-string\fI/cookies.txt\fR.
+.ie n .IP """Internet Explorer.""" 4
+.el .IP "\f(CWInternet Explorer.\fR" 4
+.IX Item "Internet Explorer."
+You can produce a cookie file Wget can use by using the File menu,
+Import and Export, Export Cookies.  This has been tested with Internet
+Explorer 5; it is not guaranteed to work with earlier versions.
+.ie n .IP """Other browsers.""" 4
+.el .IP "\f(CWOther browsers.\fR" 4
+.IX Item "Other browsers."
+If you are using a different browser to create your cookies,
+\&\fB\-\-load\-cookies\fR will only work if you can locate or produce a
+cookie file in the Netscape format that Wget expects.
+.RE
+.RS 4
+.Sp
+If you cannot use \fB\-\-load\-cookies\fR, there might still be an
+alternative.  If your browser supports a \*(L"cookie manager\*(R", you can use
+it to view the cookies used when accessing the site you're mirroring.
+Write down the name and value of the cookie, and manually instruct Wget
+to send those cookies, bypassing the \*(L"official\*(R" cookie support:
+.Sp
+.Vb 1
+\&        wget \-\-no\-cookies \-\-header "Cookie: <name>=<value>"
+.Ve
+.RE
+.IP "\fB\-\-save\-cookies\fR \fIfile\fR" 4
+.IX Item "--save-cookies file"
+Save cookies to \fIfile\fR before exiting.  This will not save cookies
+that have expired or that have no expiry time (so-called \*(L"session
+cookies\*(R"), but also see \fB\-\-keep\-session\-cookies\fR.
+.IP "\fB\-\-keep\-session\-cookies\fR" 4
+.IX Item "--keep-session-cookies"
+When specified, causes \fB\-\-save\-cookies\fR to also save session
+cookies.  Session cookies are normally not saved because they are
+meant to be kept in memory and forgotten when you exit the browser.
+Saving them is useful on sites that require you to log in or to visit
+the home page before you can access some pages.  With this option,
+multiple Wget runs are considered a single browser session as far as
+the site is concerned.
+.Sp
+Since the cookie file format does not normally carry session cookies,
+Wget marks them with an expiry timestamp of 0.  Wget's
+\&\fB\-\-load\-cookies\fR recognizes those as session cookies, but it might
+confuse other browsers.  Also note that cookies so loaded will be
+treated as other session cookies, which means that if you want
+\&\fB\-\-save\-cookies\fR to preserve them again, you must use
+\&\fB\-\-keep\-session\-cookies\fR again.
+.IP "\fB\-\-ignore\-length\fR" 4
+.IX Item "--ignore-length"
+Unfortunately, some \s-1HTTP\s0 servers (\s-1CGI\s0 programs, to be more
+precise) send out bogus \f(CW\*(C`Content\-Length\*(C'\fR headers, which makes Wget
+go wild, as it thinks not all the document was retrieved.  You can spot
+this syndrome if Wget retries getting the same document again and again,
+each time claiming that the (otherwise normal) connection has closed on
+the very same byte.
+.Sp
+With this option, Wget will ignore the \f(CW\*(C`Content\-Length\*(C'\fR header\-\-\-as
+if it never existed.
+.IP "\fB\-\-header=\fR\fIheader-line\fR" 4
+.IX Item "--header=header-line"
+Send \fIheader-line\fR along with the rest of the headers in each
+\&\s-1HTTP\s0 request.  The supplied header is sent as-is, which means it
+must contain name and value separated by colon, and must not contain
+newlines.
+.Sp
+You may define more than one additional header by specifying
+\&\fB\-\-header\fR more than once.
+.Sp
+.Vb 3
+\&        wget \-\-header=\*(AqAccept\-Charset: iso\-8859\-2\*(Aq \e
+\&             \-\-header=\*(AqAccept\-Language: hr\*(Aq        \e
+\&               http://fly.srk.fer.hr/
+.Ve
+.Sp
+Specification of an empty string as the header value will clear all
+previous user-defined headers.
+.Sp
+As of Wget 1.10, this option can be used to override headers otherwise
+generated automatically.  This example instructs Wget to connect to
+localhost, but to specify \fBfoo.bar\fR in the \f(CW\*(C`Host\*(C'\fR header:
+.Sp
+.Vb 1
+\&        wget \-\-header="Host: foo.bar" http://localhost/
+.Ve
+.Sp
+In versions of Wget prior to 1.10 such use of \fB\-\-header\fR caused
+sending of duplicate headers.
+.IP "\fB\-\-compression=\fR\fItype\fR" 4
+.IX Item "--compression=type"
+Choose the type of compression to be used.  Legal values are
+\&\fBauto\fR, \fBgzip\fR and \fBnone\fR.
+.Sp
+If \fBauto\fR or \fBgzip\fR are specified, Wget asks the server to
+compress the file using the gzip compression format. If the server
+compresses the file and responds with the \f(CW\*(C`Content\-Encoding\*(C'\fR
+header field set appropriately, the file will be decompressed
+automatically.
+.Sp
+If \fBnone\fR is specified, wget will not ask the server to compress
+the file and will not decompress any server responses. This is the default.
+.Sp
+Compression support is currently experimental. In case it is turned on,
+please report any bugs to \f(CW\*(C`bug\-wget@gnu.org\*(C'\fR.
+.IP "\fB\-\-max\-redirect=\fR\fInumber\fR" 4
+.IX Item "--max-redirect=number"
+Specifies the maximum number of redirections to follow for a resource.
+The default is 20, which is usually far more than necessary. However, on
+those occasions where you want to allow more (or fewer), this is the
+option to use.
+.IP "\fB\-\-proxy\-user=\fR\fIuser\fR" 4
+.IX Item "--proxy-user=user"
+.PD 0
+.IP "\fB\-\-proxy\-password=\fR\fIpassword\fR" 4
+.IX Item "--proxy-password=password"
+.PD
+Specify the username \fIuser\fR and password \fIpassword\fR for
+authentication on a proxy server.  Wget will encode them using the
+\&\f(CW\*(C`basic\*(C'\fR authentication scheme.
+.Sp
+Security considerations similar to those with \fB\-\-http\-password\fR
+pertain here as well.
+.IP "\fB\-\-referer=\fR\fIurl\fR" 4
+.IX Item "--referer=url"
+Include `Referer: \fIurl\fR' header in \s-1HTTP\s0 request.  Useful for
+retrieving documents with server-side processing that assume they are
+always being retrieved by interactive web browsers and only come out
+properly when Referer is set to one of the pages that point to them.
+.IP "\fB\-\-save\-headers\fR" 4
+.IX Item "--save-headers"
+Save the headers sent by the \s-1HTTP\s0 server to the file, preceding the
+actual contents, with an empty line as the separator.
+.IP "\fB\-U\fR \fIagent-string\fR" 4
+.IX Item "-U agent-string"
+.PD 0
+.IP "\fB\-\-user\-agent=\fR\fIagent-string\fR" 4
+.IX Item "--user-agent=agent-string"
+.PD
+Identify as \fIagent-string\fR to the \s-1HTTP\s0 server.
+.Sp
+The \s-1HTTP\s0 protocol allows the clients to identify themselves using a
+\&\f(CW\*(C`User\-Agent\*(C'\fR header field.  This enables distinguishing the
+\&\s-1WWW\s0 software, usually for statistical purposes or for tracing of
+protocol violations.  Wget normally identifies as
+\&\fBWget/\fR\fIversion\fR, \fIversion\fR being the current version
+number of Wget.
+.Sp
+However, some sites have been known to impose the policy of tailoring
+the output according to the \f(CW\*(C`User\-Agent\*(C'\fR\-supplied information.
+While this is not such a bad idea in theory, it has been abused by
+servers denying information to clients other than (historically)
+Netscape or, more frequently, Microsoft Internet Explorer.  This
+option allows you to change the \f(CW\*(C`User\-Agent\*(C'\fR line issued by Wget.
+Use of this option is discouraged, unless you really know what you are
+doing.
+.Sp
+Specifying empty user agent with \fB\-\-user\-agent=""\fR instructs Wget
+not to send the \f(CW\*(C`User\-Agent\*(C'\fR header in \s-1HTTP\s0 requests.
+.IP "\fB\-\-post\-data=\fR\fIstring\fR" 4
+.IX Item "--post-data=string"
+.PD 0
+.IP "\fB\-\-post\-file=\fR\fIfile\fR" 4
+.IX Item "--post-file=file"
+.PD
+Use \s-1POST\s0 as the method for all \s-1HTTP\s0 requests and send the specified
+data in the request body.  \fB\-\-post\-data\fR sends \fIstring\fR as
+data, whereas \fB\-\-post\-file\fR sends the contents of \fIfile\fR.
+Other than that, they work in exactly the same way. In particular,
+they \fIboth\fR expect content of the form \f(CW\*(C`key1=value1&key2=value2\*(C'\fR,
+with percent-encoding for special characters; the only difference is
+that one expects its content as a command-line parameter and the other
+accepts its content from a file. In particular, \fB\-\-post\-file\fR is
+\&\fInot\fR for transmitting files as form attachments: those must
+appear as \f(CW\*(C`key=value\*(C'\fR data (with appropriate percent-coding) just
+like everything else. Wget does not currently support
+\&\f(CW\*(C`multipart/form\-data\*(C'\fR for transmitting \s-1POST\s0 data; only
+\&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR. Only one of
+\&\fB\-\-post\-data\fR and \fB\-\-post\-file\fR should be specified.
+.Sp
+Please note that wget does not require the content to be of the form
+\&\f(CW\*(C`key1=value1&key2=value2\*(C'\fR, and neither does it test for it. Wget will
+simply transmit whatever data is provided to it. Most servers however expect
+the \s-1POST\s0 data to be in the above format when processing \s-1HTML\s0 Forms.
+.Sp
+When sending a \s-1POST\s0 request using the \fB\-\-post\-file\fR option, Wget treats
+the file as a binary file and will send every character in the \s-1POST\s0 request
+without stripping trailing newline or formfeed characters. Any other control
+characters in the text will also be sent as-is in the \s-1POST\s0 request.
+.Sp
+Please be aware that Wget needs to know the size of the \s-1POST\s0 data in
+advance.  Therefore the argument to \f(CW\*(C`\-\-post\-file\*(C'\fR must be a regular
+file; specifying a \s-1FIFO\s0 or something like \fI/dev/stdin\fR won't work.
+It's not quite clear how to work around this limitation inherent in
+\&\s-1HTTP/1.0.\s0  Although \s-1HTTP/1.1\s0 introduces \fIchunked\fR transfer that
+doesn't require knowing the request length in advance, a client can't
+use chunked unless it knows it's talking to an \s-1HTTP/1.1\s0 server.  And it
+can't know that until it receives a response, which in turn requires the
+request to have been completed \*(-- a chicken-and-egg problem.
+.Sp
+Note: As of version 1.15 if Wget is redirected after the \s-1POST\s0 request is
+completed, its behaviour will depend on the response code returned by the
+server.  In case of a 301 Moved Permanently, 302 Moved Temporarily or
+307 Temporary Redirect, Wget will, in accordance with \s-1RFC2616,\s0 continue
+to send a \s-1POST\s0 request.
+In case a server wants the client to change the Request method upon
+redirection, it should send a 303 See Other response code.
+.Sp
+This example shows how to log in to a server using \s-1POST\s0 and then proceed to
+download the desired pages, presumably only accessible to authorized
+users:
+.Sp
+.Vb 4
+\&        # Log in to the server.  This can be done only once.
+\&        wget \-\-save\-cookies cookies.txt \e
+\&             \-\-post\-data \*(Aquser=foo&password=bar\*(Aq \e
+\&             http://example.com/auth.php
+\&        
+\&        # Now grab the page or pages we care about.
+\&        wget \-\-load\-cookies cookies.txt \e
+\&             \-p http://example.com/interesting/article.php
+.Ve
+.Sp
+If the server is using session cookies to track user authentication,
+the above will not work because \fB\-\-save\-cookies\fR will not save
+them (and neither will browsers) and the \fIcookies.txt\fR file will
+be empty.  In that case use \fB\-\-keep\-session\-cookies\fR along with
+\&\fB\-\-save\-cookies\fR to force saving of session cookies.
+.IP "\fB\-\-method=\fR\fIHTTP-Method\fR" 4
+.IX Item "--method=HTTP-Method"
+For the purpose of RESTful scripting, Wget allows sending of other \s-1HTTP\s0 Methods
+without the need to explicitly set them using \fB\-\-header=Header\-Line\fR.
+Wget will use whatever string is passed to it after \fB\-\-method\fR as the \s-1HTTP\s0
+Method to the server.
+.IP "\fB\-\-body\-data=\fR\fIData-String\fR" 4
+.IX Item "--body-data=Data-String"
+.PD 0
+.IP "\fB\-\-body\-file=\fR\fIData-File\fR" 4
+.IX Item "--body-file=Data-File"
+.PD
+Must be set when additional data needs to be sent to the server along with the
+Method specified using \fB\-\-method\fR.  \fB\-\-body\-data\fR sends \fIstring\fR as
+data, whereas \fB\-\-body\-file\fR sends the contents of \fIfile\fR.  Other than that,
+they work in exactly the same way.
+.Sp
+Currently, \fB\-\-body\-file\fR is \fInot\fR for transmitting files as a whole.
+Wget does not currently support \f(CW\*(C`multipart/form\-data\*(C'\fR for transmitting data;
+only \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR. In the future, this may be changed
+so that wget sends the \fB\-\-body\-file\fR as a complete file instead of sending its
+contents to the server. Please be aware that Wget needs to know the contents of
+\&\s-1BODY\s0 Data in advance, and hence the argument to \fB\-\-body\-file\fR should be a
+regular file. See \fB\-\-post\-file\fR for a more detailed explanation.
+Only one of \fB\-\-body\-data\fR and \fB\-\-body\-file\fR should be specified.
+.Sp
+If Wget is redirected after the request is completed, Wget will
+suspend the current method and send a \s-1GET\s0 request till the redirection
+is completed.  This is true for all redirection response codes except
+307 Temporary Redirect which is used to explicitly specify that the
+request method should \fInot\fR change.  Another exception is when
+the method is set to \f(CW\*(C`POST\*(C'\fR, in which case the redirection rules
+specified under \fB\-\-post\-data\fR are followed.
+.IP "\fB\-\-content\-disposition\fR" 4
+.IX Item "--content-disposition"
+If this is set to on, experimental (not fully-functional) support for
+\&\f(CW\*(C`Content\-Disposition\*(C'\fR headers is enabled. This can currently result in
+extra round-trips to the server for a \f(CW\*(C`HEAD\*(C'\fR request, and is known
+to suffer from a few bugs, which is why it is not currently enabled by default.
+.Sp
+This option is useful for some file-downloading \s-1CGI\s0 programs that use
+\&\f(CW\*(C`Content\-Disposition\*(C'\fR headers to describe what the name of a
+downloaded file should be.
+.Sp
+When combined with \fB\-\-metalink\-over\-http\fR and \fB\-\-trust\-server\-names\fR,
+a \fBContent-Type: application/metalink4+xml\fR file is named using the
+\&\f(CW\*(C`Content\-Disposition\*(C'\fR filename field, if available.
+.IP "\fB\-\-content\-on\-error\fR" 4
+.IX Item "--content-on-error"
+If this is set to on, wget will not skip the content when the server responds
+with a http status code that indicates error.
+.IP "\fB\-\-trust\-server\-names\fR" 4
+.IX Item "--trust-server-names"
+If this is set, on a redirect, the local file name will be based
+on the redirection \s-1URL.\s0  By default the local file name is based on
+the original \s-1URL.\s0  When doing recursive retrieving this can be helpful
+because in many web sites redirected URLs correspond to an underlying
+file structure, while link URLs do not.
+.IP "\fB\-\-auth\-no\-challenge\fR" 4
+.IX Item "--auth-no-challenge"
+If this option is given, Wget will send Basic \s-1HTTP\s0 authentication
+information (plaintext username and password) for all requests, just
+like Wget 1.10.2 and prior did by default.
+.Sp
+Use of this option is not recommended, and is intended only to support
+some few obscure servers, which never send \s-1HTTP\s0 authentication
+challenges, but accept unsolicited auth info, say, in addition to
+form-based authentication.
+.IP "\fB\-\-retry\-on\-host\-error\fR" 4
+.IX Item "--retry-on-host-error"
+Consider host errors, such as \*(L"Temporary failure in name resolution\*(R",
+as non-fatal, transient errors.
+.IP "\fB\-\-retry\-on\-http\-error=\fR\fIcode[,code,...]\fR" 4
+.IX Item "--retry-on-http-error=code[,code,...]"
+Consider given \s-1HTTP\s0 response codes as non-fatal, transient errors.
+Supply a comma-separated list of 3\-digit \s-1HTTP\s0 response codes as
+argument. Useful to work around special circumstances where retries
+are required, but the server responds with an error code normally not
+retried by Wget. Such errors might be 503 (Service Unavailable) and
+429 (Too Many Requests). Retries enabled by this option are performed
+subject to the normal retry timing and retry count limitations of
+Wget.
+.Sp
+Using this option is intended to support special use cases only and is
+generally not recommended, as it can force retries even in cases where
+the server is actually trying to decrease its load. Please use wisely
+and only if you know what you are doing.
+.SS "\s-1HTTPS\s0 (\s-1SSL/TLS\s0) Options"
+.IX Subsection "HTTPS (SSL/TLS) Options"
+To support encrypted \s-1HTTP\s0 (\s-1HTTPS\s0) downloads, Wget must be compiled
+with an external \s-1SSL\s0 library. The current default is GnuTLS.
+In addition, Wget also supports \s-1HSTS\s0 (\s-1HTTP\s0 Strict Transport Security).
+If Wget is compiled without \s-1SSL\s0 support, none of these options are available.
+.IP "\fB\-\-secure\-protocol=\fR\fIprotocol\fR" 4
+.IX Item "--secure-protocol=protocol"
+Choose the secure protocol to be used.  Legal values are \fBauto\fR,
+\&\fBSSLv2\fR, \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1_1\fR, \fBTLSv1_2\fR,
+\&\fBTLSv1_3\fR and \fB\s-1PFS\s0\fR.  If \fBauto\fR is used, the \s-1SSL\s0 library is
+given the liberty of choosing the appropriate protocol automatically, which is
+achieved by sending a TLSv1 greeting. This is the default.
+.Sp
+Specifying \fBSSLv2\fR, \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1_1\fR,
+\&\fBTLSv1_2\fR or \fBTLSv1_3\fR forces the use of the corresponding
+protocol.  This is useful when talking to old and buggy \s-1SSL\s0 server
+implementations that make it hard for the underlying \s-1SSL\s0 library to choose
+the correct protocol version.  Fortunately, such servers are quite rare.
+.Sp
+Specifying \fB\s-1PFS\s0\fR enforces the use of the so-called Perfect Forward
+Security cipher suites. In short, \s-1PFS\s0 adds security by creating a one-time
+key for each \s-1SSL\s0 connection. It has a bit more \s-1CPU\s0 impact on client and server.
+We use known to be secure ciphers (e.g. no \s-1MD4\s0) and the \s-1TLS\s0 protocol. This mode
+also explicitly excludes non-PFS key exchange methods, such as \s-1RSA.\s0
+.IP "\fB\-\-https\-only\fR" 4
+.IX Item "--https-only"
+When in recursive mode, only \s-1HTTPS\s0 links are followed.
+.IP "\fB\-\-ciphers\fR" 4
+.IX Item "--ciphers"
+Set the cipher list string. Typically this string sets the
+cipher suites and other \s-1SSL/TLS\s0 options that the user wish should be used, in a
+set order of preference (GnuTLS calls it 'priority string'). This string
+will be fed verbatim to the \s-1SSL/TLS\s0 engine (OpenSSL or GnuTLS) and hence
+its format and syntax is dependent on that. Wget will not process or manipulate it
+in any way. Refer to the OpenSSL or GnuTLS documentation for more information.
+.IP "\fB\-\-no\-check\-certificate\fR" 4
+.IX Item "--no-check-certificate"
+Don't check the server certificate against the available certificate
+authorities.  Also don't require the \s-1URL\s0 host name to match the common
+name presented by the certificate.
+.Sp
+As of Wget 1.10, the default is to verify the server's certificate
+against the recognized certificate authorities, breaking the \s-1SSL\s0
+handshake and aborting the download if the verification fails.
+Although this provides more secure downloads, it does break
+interoperability with some sites that worked with previous Wget
+versions, particularly those using self-signed, expired, or otherwise
+invalid certificates.  This option forces an \*(L"insecure\*(R" mode of
+operation that turns the certificate verification errors into warnings
+and allows you to proceed.
+.Sp
+If you encounter \*(L"certificate verification\*(R" errors or ones saying
+that \*(L"common name doesn't match requested host name\*(R", you can use
+this option to bypass the verification and proceed with the download.
+\&\fIOnly use this option if you are otherwise convinced of the
+site's authenticity, or if you really don't care about the validity of
+its certificate.\fR  It is almost always a bad idea not to check the
+certificates when transmitting confidential or important data.
+For self\-signed/internal certificates, you should download the certificate
+and verify against that instead of forcing this insecure mode.
+If you are really sure of not desiring any certificate verification, you
+can specify \-\-check\-certificate=quiet to tell wget to not print any
+warning about invalid certificates, albeit in most cases this is the
+wrong thing to do.
+.IP "\fB\-\-certificate=\fR\fIfile\fR" 4
+.IX Item "--certificate=file"
+Use the client certificate stored in \fIfile\fR.  This is needed for
+servers that are configured to require certificates from the clients
+that connect to them.  Normally a certificate is not required and this
+switch is optional.
+.IP "\fB\-\-certificate\-type=\fR\fItype\fR" 4
+.IX Item "--certificate-type=type"
+Specify the type of the client certificate.  Legal values are
+\&\fB\s-1PEM\s0\fR (assumed by default) and \fB\s-1DER\s0\fR, also known as
+\&\fB\s-1ASN1\s0\fR.
+.IP "\fB\-\-private\-key=\fR\fIfile\fR" 4
+.IX Item "--private-key=file"
+Read the private key from \fIfile\fR.  This allows you to provide the
+private key in a file separate from the certificate.
+.IP "\fB\-\-private\-key\-type=\fR\fItype\fR" 4
+.IX Item "--private-key-type=type"
+Specify the type of the private key.  Accepted values are \fB\s-1PEM\s0\fR
+(the default) and \fB\s-1DER\s0\fR.
+.IP "\fB\-\-ca\-certificate=\fR\fIfile\fR" 4
+.IX Item "--ca-certificate=file"
+Use \fIfile\fR as the file with the bundle of certificate authorities
+(\*(L"\s-1CA\*(R"\s0) to verify the peers.  The certificates must be in \s-1PEM\s0 format.
+.Sp
+Without this option Wget looks for \s-1CA\s0 certificates at the
+system-specified locations, chosen at OpenSSL installation time.
+.IP "\fB\-\-ca\-directory=\fR\fIdirectory\fR" 4
+.IX Item "--ca-directory=directory"
+Specifies directory containing \s-1CA\s0 certificates in \s-1PEM\s0 format.  Each
+file contains one \s-1CA\s0 certificate, and the file name is based on a hash
+value derived from the certificate.  This is achieved by processing a
+certificate directory with the \f(CW\*(C`c_rehash\*(C'\fR utility supplied with
+OpenSSL.  Using \fB\-\-ca\-directory\fR is more efficient than
+\&\fB\-\-ca\-certificate\fR when many certificates are installed because
+it allows Wget to fetch certificates on demand.
+.Sp
+Without this option Wget looks for \s-1CA\s0 certificates at the
+system-specified locations, chosen at OpenSSL installation time.
+.IP "\fB\-\-crl\-file=\fR\fIfile\fR" 4
+.IX Item "--crl-file=file"
+Specifies a \s-1CRL\s0 file in \fIfile\fR.  This is needed for certificates
+that have been revocated by the CAs.
+.IP "\fB\-\-pinnedpubkey=file/hashes\fR" 4
+.IX Item "--pinnedpubkey=file/hashes"
+Tells wget to use the specified public key file (or hashes) to verify the peer.
+This can be a path to a file which contains a single public key in \s-1PEM\s0 or \s-1DER\s0
+format, or any number of base64 encoded sha256 hashes preceded by \*(L"sha256//\*(R"
+and separated by \*(L";\*(R"
+.Sp
+When negotiating a \s-1TLS\s0 or \s-1SSL\s0 connection, the server sends a certificate
+indicating its identity. A public key is extracted from this certificate and if
+it does not exactly match the public key(s) provided to this option, wget will
+abort the connection before sending or receiving any data.
+.IP "\fB\-\-random\-file=\fR\fIfile\fR" 4
+.IX Item "--random-file=file"
+[OpenSSL and LibreSSL only]
+Use \fIfile\fR as the source of random data for seeding the
+pseudo-random number generator on systems without \fI/dev/urandom\fR.
+.Sp
+On such systems the \s-1SSL\s0 library needs an external source of randomness
+to initialize.  Randomness may be provided by \s-1EGD\s0 (see
+\&\fB\-\-egd\-file\fR below) or read from an external source specified by
+the user.  If this option is not specified, Wget looks for random data
+in \f(CW$RANDFILE\fR or, if that is unset, in \fI\f(CI$HOME\fI/.rnd\fR.
+.Sp
+If you're getting the \*(L"Could not seed OpenSSL \s-1PRNG\s0; disabling \s-1SSL.\*(R"\s0 
+error, you should provide random data using some of the methods
+described above.
+.IP "\fB\-\-egd\-file=\fR\fIfile\fR" 4
+.IX Item "--egd-file=file"
+[OpenSSL only]
+Use \fIfile\fR as the \s-1EGD\s0 socket.  \s-1EGD\s0 stands for \fIEntropy
+Gathering Daemon\fR, a user-space program that collects data from
+various unpredictable system sources and makes it available to other
+programs that might need it.  Encryption software, such as the \s-1SSL\s0
+library, needs sources of non-repeating randomness to seed the random
+number generator used to produce cryptographically strong keys.
+.Sp
+OpenSSL allows the user to specify his own source of entropy using the
+\&\f(CW\*(C`RAND_FILE\*(C'\fR environment variable.  If this variable is unset, or
+if the specified file does not produce enough randomness, OpenSSL will
+read random data from \s-1EGD\s0 socket specified using this option.
+.Sp
+If this option is not specified (and the equivalent startup command is
+not used), \s-1EGD\s0 is never contacted.  \s-1EGD\s0 is not needed on modern Unix
+systems that support \fI/dev/urandom\fR.
+.IP "\fB\-\-no\-hsts\fR" 4
+.IX Item "--no-hsts"
+Wget supports \s-1HSTS\s0 (\s-1HTTP\s0 Strict Transport Security, \s-1RFC 6797\s0) by default.
+Use \fB\-\-no\-hsts\fR to make Wget act as a non-HSTS-compliant \s-1UA.\s0 As a
+consequence, Wget would ignore all the \f(CW\*(C`Strict\-Transport\-Security\*(C'\fR
+headers, and would not enforce any existing \s-1HSTS\s0 policy.
+.IP "\fB\-\-hsts\-file=\fR\fIfile\fR" 4
+.IX Item "--hsts-file=file"
+By default, Wget stores its \s-1HSTS\s0 database in \fI~/.wget\-hsts\fR.
+You can use \fB\-\-hsts\-file\fR to override this. Wget will use
+the supplied file as the \s-1HSTS\s0 database. Such file must conform to the
+correct \s-1HSTS\s0 database format used by Wget. If Wget cannot parse the provided
+file, the behaviour is unspecified.
+.Sp
+The Wget's \s-1HSTS\s0 database is a plain text file. Each line contains an \s-1HSTS\s0 entry
+(ie. a site that has issued a \f(CW\*(C`Strict\-Transport\-Security\*(C'\fR header and that
+therefore has specified a concrete \s-1HSTS\s0 policy to be applied). Lines starting with
+a dash (\f(CW\*(C`#\*(C'\fR) are ignored by Wget. Please note that in spite of this convenient
+human-readability hand-hacking the \s-1HSTS\s0 database is generally not a good idea.
+.Sp
+An \s-1HSTS\s0 entry line consists of several fields separated by one or more whitespace:
+.Sp
+\&\f(CW\*(C`<hostname> SP [<port>] SP <include subdomains> SP <created> SP <max\-age>\*(C'\fR
+.Sp
+The \fIhostname\fR and \fIport\fR fields indicate the hostname and port to which
+the given \s-1HSTS\s0 policy applies. The \fIport\fR field may be zero, and it will, in
+most of the cases. That means that the port number will not be taken into account
+when deciding whether such \s-1HSTS\s0 policy should be applied on a given request (only
+the hostname will be evaluated). When \fIport\fR is different to zero, both the
+target hostname and the port will be evaluated and the \s-1HSTS\s0 policy will only be applied
+if both of them match. This feature has been included for testing/development purposes only.
+The Wget testsuite (in \fItestenv/\fR) creates \s-1HSTS\s0 databases with explicit ports
+with the purpose of ensuring Wget's correct behaviour. Applying \s-1HSTS\s0 policies to ports
+other than the default ones is discouraged by \s-1RFC 6797\s0 (see Appendix B \*(L"Differences
+between \s-1HSTS\s0 Policy and Same-Origin Policy\*(R"). Thus, this functionality should not be used
+in production environments and \fIport\fR will typically be zero. The last three fields
+do what they are expected to. The field \fIinclude_subdomains\fR can either be \f(CW1\fR
+or \f(CW0\fR and it signals whether the subdomains of the target domain should be
+part of the given \s-1HSTS\s0 policy as well. The \fIcreated\fR and \fImax-age\fR fields
+hold the timestamp values of when such entry was created (first seen by Wget) and the
+HSTS-defined value 'max\-age', which states how long should that \s-1HSTS\s0 policy remain active,
+measured in seconds elapsed since the timestamp stored in \fIcreated\fR. Once that time
+has passed, that \s-1HSTS\s0 policy will no longer be valid and will eventually be removed
+from the database.
+.Sp
+If you supply your own \s-1HSTS\s0 database via \fB\-\-hsts\-file\fR, be aware that Wget
+may modify the provided file if any change occurs between the \s-1HSTS\s0 policies
+requested by the remote servers and those in the file. When Wget exits,
+it effectively updates the \s-1HSTS\s0 database by rewriting the database file with the new entries.
+.Sp
+If the supplied file does not exist, Wget will create one. This file will contain the new \s-1HSTS\s0
+entries. If no \s-1HSTS\s0 entries were generated (no \f(CW\*(C`Strict\-Transport\-Security\*(C'\fR headers
+were sent by any of the servers) then no file will be created, not even an empty one. This
+behaviour applies to the default database file (\fI~/.wget\-hsts\fR) as well: it will not be
+created until some server enforces an \s-1HSTS\s0 policy.
+.Sp
+Care is taken not to override possible changes made by other Wget processes at
+the same time over the \s-1HSTS\s0 database. Before dumping the updated \s-1HSTS\s0 entries
+on the file, Wget will re-read it and merge the changes.
+.Sp
+Using a custom \s-1HSTS\s0 database and/or modifying an existing one is discouraged.
+For more information about the potential security threats arose from such practice,
+see section 14 \*(L"Security Considerations\*(R" of \s-1RFC 6797,\s0 specially section 14.9
+\&\*(L"Creative Manipulation of \s-1HSTS\s0 Policy Store\*(R".
+.IP "\fB\-\-warc\-file=\fR\fIfile\fR" 4
+.IX Item "--warc-file=file"
+Use \fIfile\fR as the destination \s-1WARC\s0 file.
+.IP "\fB\-\-warc\-header=\fR\fIstring\fR" 4
+.IX Item "--warc-header=string"
+Use \fIstring\fR into as the warcinfo record.
+.IP "\fB\-\-warc\-max\-size=\fR\fIsize\fR" 4
+.IX Item "--warc-max-size=size"
+Set the maximum size of the \s-1WARC\s0 files to \fIsize\fR.
+.IP "\fB\-\-warc\-cdx\fR" 4
+.IX Item "--warc-cdx"
+Write \s-1CDX\s0 index files.
+.IP "\fB\-\-warc\-dedup=\fR\fIfile\fR" 4
+.IX Item "--warc-dedup=file"
+Do not store records listed in this \s-1CDX\s0 file.
+.IP "\fB\-\-no\-warc\-compression\fR" 4
+.IX Item "--no-warc-compression"
+Do not compress \s-1WARC\s0 files with \s-1GZIP.\s0
+.IP "\fB\-\-no\-warc\-digests\fR" 4
+.IX Item "--no-warc-digests"
+Do not calculate \s-1SHA1\s0 digests.
+.IP "\fB\-\-no\-warc\-keep\-log\fR" 4
+.IX Item "--no-warc-keep-log"
+Do not store the log file in a \s-1WARC\s0 record.
+.IP "\fB\-\-warc\-tempdir=\fR\fIdir\fR" 4
+.IX Item "--warc-tempdir=dir"
+Specify the location for temporary files created by the \s-1WARC\s0 writer.
+.SS "\s-1FTP\s0 Options"
+.IX Subsection "FTP Options"
+.IP "\fB\-\-ftp\-user=\fR\fIuser\fR" 4
+.IX Item "--ftp-user=user"
+.PD 0
+.IP "\fB\-\-ftp\-password=\fR\fIpassword\fR" 4
+.IX Item "--ftp-password=password"
+.PD
+Specify the username \fIuser\fR and password \fIpassword\fR on an
+\&\s-1FTP\s0 server.  Without this, or the corresponding startup option, 
+the password defaults to \fB\-wget@\fR, normally used for anonymous 
+\&\s-1FTP.\s0
+.Sp
+Another way to specify username and password is in the \s-1URL\s0 itself.  Either method reveals your password to anyone who
+bothers to run \f(CW\*(C`ps\*(C'\fR.  To prevent the passwords from being seen,
+store them in \fI.wgetrc\fR or \fI.netrc\fR, and make sure to protect
+those files from other users with \f(CW\*(C`chmod\*(C'\fR.  If the passwords are
+really important, do not leave them lying in those files either\-\-\-edit
+the files and delete them after Wget has started the download.
+.IP "\fB\-\-no\-remove\-listing\fR" 4
+.IX Item "--no-remove-listing"
+Don't remove the temporary \fI.listing\fR files generated by \s-1FTP\s0
+retrievals.  Normally, these files contain the raw directory listings
+received from \s-1FTP\s0 servers.  Not removing them can be useful for
+debugging purposes, or when you want to be able to easily check on the
+contents of remote server directories (e.g. to verify that a mirror
+you're running is complete).
+.Sp
+Note that even though Wget writes to a known filename for this file,
+this is not a security hole in the scenario of a user making
+\&\fI.listing\fR a symbolic link to \fI/etc/passwd\fR or something and
+asking \f(CW\*(C`root\*(C'\fR to run Wget in his or her directory.  Depending on
+the options used, either Wget will refuse to write to \fI.listing\fR,
+making the globbing/recursion/time\-stamping operation fail, or the
+symbolic link will be deleted and replaced with the actual
+\&\fI.listing\fR file, or the listing will be written to a
+\&\fI.listing.\fInumber\fI\fR file.
+.Sp
+Even though this situation isn't a problem, though, \f(CW\*(C`root\*(C'\fR should
+never run Wget in a non-trusted user's directory.  A user could do
+something as simple as linking \fIindex.html\fR to \fI/etc/passwd\fR
+and asking \f(CW\*(C`root\*(C'\fR to run Wget with \fB\-N\fR or \fB\-r\fR so the file
+will be overwritten.
+.IP "\fB\-\-no\-glob\fR" 4
+.IX Item "--no-glob"
+Turn off \s-1FTP\s0 globbing.  Globbing refers to the use of shell-like
+special characters (\fIwildcards\fR), like \fB*\fR, \fB?\fR, \fB[\fR
+and \fB]\fR to retrieve more than one file from the same directory at
+once, like:
+.Sp
+.Vb 1
+\&        wget ftp://gnjilux.srk.fer.hr/*.msg
+.Ve
+.Sp
+By default, globbing will be turned on if the \s-1URL\s0 contains a
+globbing character.  This option may be used to turn globbing on or off
+permanently.
+.Sp
+You may have to quote the \s-1URL\s0 to protect it from being expanded by
+your shell.  Globbing makes Wget look for a directory listing, which is
+system-specific.  This is why it currently works only with Unix \s-1FTP\s0
+servers (and the ones emulating Unix \f(CW\*(C`ls\*(C'\fR output).
+.IP "\fB\-\-no\-passive\-ftp\fR" 4
+.IX Item "--no-passive-ftp"
+Disable the use of the \fIpassive\fR \s-1FTP\s0 transfer mode.  Passive \s-1FTP\s0
+mandates that the client connect to the server to establish the data
+connection rather than the other way around.
+.Sp
+If the machine is connected to the Internet directly, both passive and
+active \s-1FTP\s0 should work equally well.  Behind most firewall and \s-1NAT\s0
+configurations passive \s-1FTP\s0 has a better chance of working.  However,
+in some rare firewall configurations, active \s-1FTP\s0 actually works when
+passive \s-1FTP\s0 doesn't.  If you suspect this to be the case, use this
+option, or set \f(CW\*(C`passive_ftp=off\*(C'\fR in your init file.
+.IP "\fB\-\-preserve\-permissions\fR" 4
+.IX Item "--preserve-permissions"
+Preserve remote file permissions instead of permissions set by umask.
+.IP "\fB\-\-retr\-symlinks\fR" 4
+.IX Item "--retr-symlinks"
+By default, when retrieving \s-1FTP\s0 directories recursively and a symbolic link
+is encountered, the symbolic link is traversed and the pointed-to files are
+retrieved.  Currently, Wget does not traverse symbolic links to directories to
+download them recursively, though this feature may be added in the future.
+.Sp
+When \fB\-\-retr\-symlinks=no\fR is specified, the linked-to file is not
+downloaded.  Instead, a matching symbolic link is created on the local
+file system.  The pointed-to file will not be retrieved unless this recursive
+retrieval would have encountered it separately and downloaded it anyway.  This
+option poses a security risk where a malicious \s-1FTP\s0 Server may cause Wget to
+write to files outside of the intended directories through a specially crafted
+\&.LISTING file.
+.Sp
+Note that when retrieving a file (not a directory) because it was
+specified on the command-line, rather than because it was recursed to,
+this option has no effect.  Symbolic links are always traversed in this
+case.
+.SS "\s-1FTPS\s0 Options"
+.IX Subsection "FTPS Options"
+.IP "\fB\-\-ftps\-implicit\fR" 4
+.IX Item "--ftps-implicit"
+This option tells Wget to use \s-1FTPS\s0 implicitly. Implicit \s-1FTPS\s0 consists of initializing
+\&\s-1SSL/TLS\s0 from the very beginning of the control connection. This option does not send
+an \f(CW\*(C`AUTH TLS\*(C'\fR command: it assumes the server speaks \s-1FTPS\s0 and directly starts an
+\&\s-1SSL/TLS\s0 connection. If the attempt is successful, the session continues just like
+regular \s-1FTPS\s0 (\f(CW\*(C`PBSZ\*(C'\fR and \f(CW\*(C`PROT\*(C'\fR are sent, etc.).
+Implicit \s-1FTPS\s0 is no longer a requirement for \s-1FTPS\s0 implementations, and thus
+many servers may not support it. If \fB\-\-ftps\-implicit\fR is passed and no explicit
+port number specified, the default port for implicit \s-1FTPS, 990,\s0 will be used, instead
+of the default port for the \*(L"normal\*(R" (explicit) \s-1FTPS\s0 which is the same as that of \s-1FTP,
+21.\s0
+.IP "\fB\-\-no\-ftps\-resume\-ssl\fR" 4
+.IX Item "--no-ftps-resume-ssl"
+Do not resume the \s-1SSL/TLS\s0 session in the data channel. When starting a data connection,
+Wget tries to resume the \s-1SSL/TLS\s0 session previously started in the control connection.
+\&\s-1SSL/TLS\s0 session resumption avoids performing an entirely new handshake by reusing
+the \s-1SSL/TLS\s0 parameters of a previous session. Typically, the \s-1FTPS\s0 servers want it that way,
+so Wget does this by default. Under rare circumstances however, one might want to
+start an entirely new \s-1SSL/TLS\s0 session in every data connection.
+This is what \fB\-\-no\-ftps\-resume\-ssl\fR is for.
+.IP "\fB\-\-ftps\-clear\-data\-connection\fR" 4
+.IX Item "--ftps-clear-data-connection"
+All the data connections will be in plain text. Only the control connection will be
+under \s-1SSL/TLS.\s0 Wget will send a \f(CW\*(C`PROT C\*(C'\fR command to achieve this, which must be
+approved by the server.
+.IP "\fB\-\-ftps\-fallback\-to\-ftp\fR" 4
+.IX Item "--ftps-fallback-to-ftp"
+Fall back to \s-1FTP\s0 if \s-1FTPS\s0 is not supported by the target server. For security reasons,
+this option is not asserted by default. The default behaviour is to exit with an error.
+If a server does not successfully reply to the initial \f(CW\*(C`AUTH TLS\*(C'\fR command, or in the
+case of implicit \s-1FTPS,\s0 if the initial \s-1SSL/TLS\s0 connection attempt is rejected, it is
+considered that such server does not support \s-1FTPS.\s0
+.SS "Recursive Retrieval Options"
+.IX Subsection "Recursive Retrieval Options"
+.IP "\fB\-r\fR" 4
+.IX Item "-r"
+.PD 0
+.IP "\fB\-\-recursive\fR" 4
+.IX Item "--recursive"
+.PD
+Turn on recursive retrieving.    The default maximum depth is 5.
+.IP "\fB\-l\fR \fIdepth\fR" 4
+.IX Item "-l depth"
+.PD 0
+.IP "\fB\-\-level=\fR\fIdepth\fR" 4
+.IX Item "--level=depth"
+.PD
+Set the maximum number of subdirectories that Wget will recurse into to \fIdepth\fR.
+In order to prevent one from accidentally downloading very large websites when using recursion
+this is limited to a depth of 5 by default, i.e., it will traverse at most 5 directories deep
+starting from the provided \s-1URL.\s0
+Set \fB\-l 0\fR or \fB\-l inf\fR for infinite recursion depth.
+.Sp
+.Vb 1
+\&        wget \-r \-l 0 http://<site>/1.html
+.Ve
+.Sp
+Ideally, one would expect this to download just \fI1.html\fR.
+but unfortunately this is not the case, because \fB\-l 0\fR is equivalent to
+\&\fB\-l inf\fR\-\-\-that is, infinite recursion.  To download a single \s-1HTML\s0
+page (or a handful of them), specify them all on the command line and leave away \fB\-r\fR
+and \fB\-l\fR. To download the essential items to view a single \s-1HTML\s0 page, see \fBpage requisites\fR.
+.IP "\fB\-\-delete\-after\fR" 4
+.IX Item "--delete-after"
+This option tells Wget to delete every single file it downloads,
+\&\fIafter\fR having done so.  It is useful for pre-fetching popular
+pages through a proxy, e.g.:
+.Sp
+.Vb 1
+\&        wget \-r \-nd \-\-delete\-after http://whatever.com/~popular/page/
+.Ve
+.Sp
+The \fB\-r\fR option is to retrieve recursively, and \fB\-nd\fR to not
+create directories.
+.Sp
+Note that \fB\-\-delete\-after\fR deletes files on the local machine.  It
+does not issue the \fB\s-1DELE\s0\fR command to remote \s-1FTP\s0 sites, for
+instance.  Also note that when \fB\-\-delete\-after\fR is specified,
+\&\fB\-\-convert\-links\fR is ignored, so \fB.orig\fR files are simply not
+created in the first place.
+.IP "\fB\-k\fR" 4
+.IX Item "-k"
+.PD 0
+.IP "\fB\-\-convert\-links\fR" 4
+.IX Item "--convert-links"
+.PD
+After the download is complete, convert the links in the document to
+make them suitable for local viewing.  This affects not only the visible
+hyperlinks, but any part of the document that links to external content,
+such as embedded images, links to style sheets, hyperlinks to non-HTML
+content, etc.
+.Sp
+Each link will be changed in one of the two ways:
+.RS 4
+.IP "\(bu" 4
+The links to files that have been downloaded by Wget will be changed to
+refer to the file they point to as a relative link.
+.Sp
+Example: if the downloaded file \fI/foo/doc.html\fR links to
+\&\fI/bar/img.gif\fR, also downloaded, then the link in \fIdoc.html\fR
+will be modified to point to \fB../bar/img.gif\fR.  This kind of
+transformation works reliably for arbitrary combinations of directories.
+.IP "\(bu" 4
+The links to files that have not been downloaded by Wget will be changed
+to include host name and absolute path of the location they point to.
+.Sp
+Example: if the downloaded file \fI/foo/doc.html\fR links to
+\&\fI/bar/img.gif\fR (or to \fI../bar/img.gif\fR), then the link in
+\&\fIdoc.html\fR will be modified to point to
+\&\fIhttp://\fIhostname\fI/bar/img.gif\fR.
+.RE
+.RS 4
+.Sp
+Because of this, local browsing works reliably: if a linked file was
+downloaded, the link will refer to its local name; if it was not
+downloaded, the link will refer to its full Internet address rather than
+presenting a broken link.  The fact that the former links are converted
+to relative links ensures that you can move the downloaded hierarchy to
+another directory.
+.Sp
+Note that only at the end of the download can Wget know which links have
+been downloaded.  Because of that, the work done by \fB\-k\fR will be
+performed at the end of all the downloads.
+.RE
+.IP "\fB\-\-convert\-file\-only\fR" 4
+.IX Item "--convert-file-only"
+This option converts only the filename part of the URLs, leaving the rest
+of the URLs untouched. This filename part is sometimes referred to as the
+\&\*(L"basename\*(R", although we avoid that term here in order not to cause confusion.
+.Sp
+It works particularly well in conjunction with \fB\-\-adjust\-extension\fR, although
+this coupling is not enforced. It proves useful to populate Internet caches
+with files downloaded from different hosts.
+.Sp
+Example: if some link points to \fI//foo.com/bar.cgi?xyz\fR with
+\&\fB\-\-adjust\-extension\fR asserted and its local destination is intended to be
+\&\fI./foo.com/bar.cgi?xyz.css\fR, then the link would be converted to
+\&\fI//foo.com/bar.cgi?xyz.css\fR. Note that only the filename part has been
+modified. The rest of the \s-1URL\s0 has been left untouched, including the net path
+(\f(CW\*(C`//\*(C'\fR) which would otherwise be processed by Wget and converted to the
+effective scheme (ie. \f(CW\*(C`http://\*(C'\fR).
+.IP "\fB\-K\fR" 4
+.IX Item "-K"
+.PD 0
+.IP "\fB\-\-backup\-converted\fR" 4
+.IX Item "--backup-converted"
+.PD
+When converting a file, back up the original version with a \fB.orig\fR
+suffix.  Affects the behavior of \fB\-N\fR.
+.IP "\fB\-m\fR" 4
+.IX Item "-m"
+.PD 0
+.IP "\fB\-\-mirror\fR" 4
+.IX Item "--mirror"
+.PD
+Turn on options suitable for mirroring.  This option turns on recursion
+and time-stamping, sets infinite recursion depth and keeps \s-1FTP\s0
+directory listings.  It is currently equivalent to
+\&\fB\-r \-N \-l inf \-\-no\-remove\-listing\fR.
+.IP "\fB\-p\fR" 4
+.IX Item "-p"
+.PD 0
+.IP "\fB\-\-page\-requisites\fR" 4
+.IX Item "--page-requisites"
+.PD
+This option causes Wget to download all the files that are necessary to
+properly display a given \s-1HTML\s0 page.  This includes such things as
+inlined images, sounds, and referenced stylesheets.
+.Sp
+Ordinarily, when downloading a single \s-1HTML\s0 page, any requisite documents
+that may be needed to display it properly are not downloaded.  Using
+\&\fB\-r\fR together with \fB\-l\fR can help, but since Wget does not
+ordinarily distinguish between external and inlined documents, one is
+generally left with \*(L"leaf documents\*(R" that are missing their
+requisites.
+.Sp
+For instance, say document \fI1.html\fR contains an \f(CW\*(C`<IMG>\*(C'\fR tag
+referencing \fI1.gif\fR and an \f(CW\*(C`<A>\*(C'\fR tag pointing to external
+document \fI2.html\fR.  Say that \fI2.html\fR is similar but that its
+image is \fI2.gif\fR and it links to \fI3.html\fR.  Say this
+continues up to some arbitrarily high number.
+.Sp
+If one executes the command:
+.Sp
+.Vb 1
+\&        wget \-r \-l 2 http://<site>/1.html
+.Ve
+.Sp
+then \fI1.html\fR, \fI1.gif\fR, \fI2.html\fR, \fI2.gif\fR, and
+\&\fI3.html\fR will be downloaded.  As you can see, \fI3.html\fR is
+without its requisite \fI3.gif\fR because Wget is simply counting the
+number of hops (up to 2) away from \fI1.html\fR in order to determine
+where to stop the recursion.  However, with this command:
+.Sp
+.Vb 1
+\&        wget \-r \-l 2 \-p http://<site>/1.html
+.Ve
+.Sp
+all the above files \fIand\fR \fI3.html\fR's requisite \fI3.gif\fR
+will be downloaded.  Similarly,
+.Sp
+.Vb 1
+\&        wget \-r \-l 1 \-p http://<site>/1.html
+.Ve
+.Sp
+will cause \fI1.html\fR, \fI1.gif\fR, \fI2.html\fR, and \fI2.gif\fR
+to be downloaded.  One might think that:
+.Sp
+.Vb 1
+\&        wget \-r \-l 0 \-p http://<site>/1.html
+.Ve
+.Sp
+would download just \fI1.html\fR and \fI1.gif\fR, but unfortunately
+this is not the case, because \fB\-l 0\fR is equivalent to
+\&\fB\-l inf\fR\-\-\-that is, infinite recursion.  To download a single \s-1HTML\s0
+page (or a handful of them, all specified on the command-line or in a
+\&\fB\-i\fR \s-1URL\s0 input file) and its (or their) requisites, simply leave off
+\&\fB\-r\fR and \fB\-l\fR:
+.Sp
+.Vb 1
+\&        wget \-p http://<site>/1.html
+.Ve
+.Sp
+Note that Wget will behave as if \fB\-r\fR had been specified, but only
+that single page and its requisites will be downloaded.  Links from that
+page to external documents will not be followed.  Actually, to download
+a single page and all its requisites (even if they exist on separate
+websites), and make sure the lot displays properly locally, this author
+likes to use a few options in addition to \fB\-p\fR:
+.Sp
+.Vb 1
+\&        wget \-E \-H \-k \-K \-p http://<site>/<document>
+.Ve
+.Sp
+To finish off this topic, it's worth knowing that Wget's idea of an
+external document link is any \s-1URL\s0 specified in an \f(CW\*(C`<A>\*(C'\fR tag, an
+\&\f(CW\*(C`<AREA>\*(C'\fR tag, or a \f(CW\*(C`<LINK>\*(C'\fR tag other than \f(CW\*(C`<LINK
+REL="stylesheet">\*(C'\fR.
+.IP "\fB\-\-strict\-comments\fR" 4
+.IX Item "--strict-comments"
+Turn on strict parsing of \s-1HTML\s0 comments.  The default is to terminate
+comments at the first occurrence of \fB\-\->\fR.
+.Sp
+According to specifications, \s-1HTML\s0 comments are expressed as \s-1SGML\s0
+\&\fIdeclarations\fR.  Declaration is special markup that begins with
+\&\fB<!\fR and ends with \fB>\fR, such as \fB<!DOCTYPE ...>\fR, that
+may contain comments between a pair of \fB\-\-\fR delimiters.  \s-1HTML\s0
+comments are \*(L"empty declarations\*(R", \s-1SGML\s0 declarations without any
+non-comment text.  Therefore, \fB<!\-\-foo\-\->\fR is a valid comment, and
+so is \fB<!\-\-one\*(-- \-\-two\-\->\fR, but \fB<!\-\-1\-\-2\-\->\fR is not.
+.Sp
+On the other hand, most \s-1HTML\s0 writers don't perceive comments as anything
+other than text delimited with \fB<!\-\-\fR and \fB\-\->\fR, which is not
+quite the same.  For example, something like \fB<!\-\-\-\-\-\-\-\-\-\-\-\->\fR
+works as a valid comment as long as the number of dashes is a multiple
+of four (!).  If not, the comment technically lasts until the next
+\&\fB\-\-\fR, which may be at the other end of the document.  Because of
+this, many popular browsers completely ignore the specification and
+implement what users have come to expect: comments delimited with
+\&\fB<!\-\-\fR and \fB\-\->\fR.
+.Sp
+Until version 1.9, Wget interpreted comments strictly, which resulted in
+missing links in many web pages that displayed fine in browsers, but had
+the misfortune of containing non-compliant comments.  Beginning with
+version 1.9, Wget has joined the ranks of clients that implements
+\&\*(L"naive\*(R" comments, terminating each comment at the first occurrence of
+\&\fB\-\->\fR.
+.Sp
+If, for whatever reason, you want strict comment parsing, use this
+option to turn it on.
+.SS "Recursive Accept/Reject Options"
+.IX Subsection "Recursive Accept/Reject Options"
+.IP "\fB\-A\fR \fIacclist\fR \fB\-\-accept\fR \fIacclist\fR" 4
+.IX Item "-A acclist --accept acclist"
+.PD 0
+.IP "\fB\-R\fR \fIrejlist\fR \fB\-\-reject\fR \fIrejlist\fR" 4
+.IX Item "-R rejlist --reject rejlist"
+.PD
+Specify comma-separated lists of file name suffixes or patterns to
+accept or reject. Note that if
+any of the wildcard characters, \fB*\fR, \fB?\fR, \fB[\fR or
+\&\fB]\fR, appear in an element of \fIacclist\fR or \fIrejlist\fR,
+it will be treated as a pattern, rather than a suffix.
+In this case, you have to enclose the pattern into quotes to prevent
+your shell from expanding it, like in \fB\-A \*(L"*.mp3\*(R"\fR or \fB\-A '*.mp3'\fR.
+.IP "\fB\-\-accept\-regex\fR \fIurlregex\fR" 4
+.IX Item "--accept-regex urlregex"
+.PD 0
+.IP "\fB\-\-reject\-regex\fR \fIurlregex\fR" 4
+.IX Item "--reject-regex urlregex"
+.PD
+Specify a regular expression to accept or reject the complete \s-1URL.\s0
+.IP "\fB\-\-regex\-type\fR \fIregextype\fR" 4
+.IX Item "--regex-type regextype"
+Specify the regular expression type.  Possible types are \fBposix\fR or
+\&\fBpcre\fR.  Note that to be able to use \fBpcre\fR type, wget has to be
+compiled with libpcre support.
+.IP "\fB\-D\fR \fIdomain-list\fR" 4
+.IX Item "-D domain-list"
+.PD 0
+.IP "\fB\-\-domains=\fR\fIdomain-list\fR" 4
+.IX Item "--domains=domain-list"
+.PD
+Set domains to be followed.  \fIdomain-list\fR is a comma-separated list
+of domains.  Note that it does \fInot\fR turn on \fB\-H\fR.
+.IP "\fB\-\-exclude\-domains\fR \fIdomain-list\fR" 4
+.IX Item "--exclude-domains domain-list"
+Specify the domains that are \fInot\fR to be followed.
+.IP "\fB\-\-follow\-ftp\fR" 4
+.IX Item "--follow-ftp"
+Follow \s-1FTP\s0 links from \s-1HTML\s0 documents.  Without this option,
+Wget will ignore all the \s-1FTP\s0 links.
+.IP "\fB\-\-follow\-tags=\fR\fIlist\fR" 4
+.IX Item "--follow-tags=list"
+Wget has an internal table of \s-1HTML\s0 tag / attribute pairs that it
+considers when looking for linked documents during a recursive
+retrieval.  If a user wants only a subset of those tags to be
+considered, however, he or she should be specify such tags in a
+comma-separated \fIlist\fR with this option.
+.IP "\fB\-\-ignore\-tags=\fR\fIlist\fR" 4
+.IX Item "--ignore-tags=list"
+This is the opposite of the \fB\-\-follow\-tags\fR option.  To skip
+certain \s-1HTML\s0 tags when recursively looking for documents to download,
+specify them in a comma-separated \fIlist\fR.
+.Sp
+In the past, this option was the best bet for downloading a single page
+and its requisites, using a command-line like:
+.Sp
+.Vb 1
+\&        wget \-\-ignore\-tags=a,area \-H \-k \-K \-r http://<site>/<document>
+.Ve
+.Sp
+However, the author of this option came across a page with tags like
+\&\f(CW\*(C`<LINK REL="home" HREF="/">\*(C'\fR and came to the realization that
+specifying tags to ignore was not enough.  One can't just tell Wget to
+ignore \f(CW\*(C`<LINK>\*(C'\fR, because then stylesheets will not be downloaded.
+Now the best bet for downloading a single page and its requisites is the
+dedicated \fB\-\-page\-requisites\fR option.
+.IP "\fB\-\-ignore\-case\fR" 4
+.IX Item "--ignore-case"
+Ignore case when matching files and directories.  This influences the
+behavior of \-R, \-A, \-I, and \-X options, as well as globbing
+implemented when downloading from \s-1FTP\s0 sites.  For example, with this
+option, \fB\-A \*(L"*.txt\*(R"\fR will match \fBfile1.txt\fR, but also
+\&\fBfile2.TXT\fR, \fBfile3.TxT\fR, and so on.
+The quotes in the example are to prevent the shell from expanding the
+pattern.
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.PD 0
+.IP "\fB\-\-span\-hosts\fR" 4
+.IX Item "--span-hosts"
+.PD
+Enable spanning across hosts when doing recursive retrieving.
+.IP "\fB\-L\fR" 4
+.IX Item "-L"
+.PD 0
+.IP "\fB\-\-relative\fR" 4
+.IX Item "--relative"
+.PD
+Follow relative links only.  Useful for retrieving a specific home page
+without any distractions, not even those from the same hosts.
+.IP "\fB\-I\fR \fIlist\fR" 4
+.IX Item "-I list"
+.PD 0
+.IP "\fB\-\-include\-directories=\fR\fIlist\fR" 4
+.IX Item "--include-directories=list"
+.PD
+Specify a comma-separated list of directories you wish to follow when
+downloading.  Elements
+of \fIlist\fR may contain wildcards.
+.IP "\fB\-X\fR \fIlist\fR" 4
+.IX Item "-X list"
+.PD 0
+.IP "\fB\-\-exclude\-directories=\fR\fIlist\fR" 4
+.IX Item "--exclude-directories=list"
+.PD
+Specify a comma-separated list of directories you wish to exclude from
+download.  Elements of
+\&\fIlist\fR may contain wildcards.
+.IP "\fB\-np\fR" 4
+.IX Item "-np"
+.PD 0
+.IP "\fB\-\-no\-parent\fR" 4
+.IX Item "--no-parent"
+.PD
+Do not ever ascend to the parent directory when retrieving recursively.
+This is a useful option, since it guarantees that only the files
+\&\fIbelow\fR a certain hierarchy will be downloaded.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+Wget supports proxies for both \s-1HTTP\s0 and \s-1FTP\s0 retrievals.  The
+standard way to specify proxy location, which Wget recognizes, is using
+the following environment variables:
+.IP "\fBhttp_proxy\fR" 4
+.IX Item "http_proxy"
+.PD 0
+.IP "\fBhttps_proxy\fR" 4
+.IX Item "https_proxy"
+.PD
+If set, the \fBhttp_proxy\fR and \fBhttps_proxy\fR variables should
+contain the URLs of the proxies for \s-1HTTP\s0 and \s-1HTTPS\s0
+connections respectively.
+.IP "\fBftp_proxy\fR" 4
+.IX Item "ftp_proxy"
+This variable should contain the \s-1URL\s0 of the proxy for \s-1FTP\s0
+connections.  It is quite common that \fBhttp_proxy\fR and
+\&\fBftp_proxy\fR are set to the same \s-1URL.\s0
+.IP "\fBno_proxy\fR" 4
+.IX Item "no_proxy"
+This variable should contain a comma-separated list of domain extensions
+proxy should \fInot\fR be used for.  For instance, if the value of
+\&\fBno_proxy\fR is \fB.mit.edu\fR, proxy will not be used to retrieve
+documents from \s-1MIT.\s0
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+Wget may return one of several error codes if it encounters problems.
+.ie n .IP "0" 4
+.el .IP "\f(CW0\fR" 4
+.IX Item "0"
+No problems occurred.
+.ie n .IP "1" 4
+.el .IP "\f(CW1\fR" 4
+.IX Item "1"
+Generic error code.
+.ie n .IP "2" 4
+.el .IP "\f(CW2\fR" 4
+.IX Item "2"
+Parse error\-\-\-for instance, when parsing command-line options, the
+\&\fB.wgetrc\fR or \fB.netrc\fR...
+.ie n .IP "3" 4
+.el .IP "\f(CW3\fR" 4
+.IX Item "3"
+File I/O error.
+.ie n .IP "4" 4
+.el .IP "\f(CW4\fR" 4
+.IX Item "4"
+Network failure.
+.ie n .IP "5" 4
+.el .IP "\f(CW5\fR" 4
+.IX Item "5"
+\&\s-1SSL\s0 verification failure.
+.ie n .IP "6" 4
+.el .IP "\f(CW6\fR" 4
+.IX Item "6"
+Username/password authentication failure.
+.ie n .IP "7" 4
+.el .IP "\f(CW7\fR" 4
+.IX Item "7"
+Protocol errors.
+.ie n .IP "8" 4
+.el .IP "\f(CW8\fR" 4
+.IX Item "8"
+Server issued an error response.
+.PP
+With the exceptions of 0 and 1, the lower-numbered exit codes take
+precedence over higher-numbered ones, when multiple types of errors
+are encountered.
+.PP
+In versions of Wget prior to 1.12, Wget's exit status tended to be
+unhelpful and inconsistent. Recursive downloads would virtually always
+return 0 (success), regardless of any issues encountered, and
+non-recursive fetches only returned the status corresponding to the
+most recently-attempted download.
+.SH "FILES"
+.IX Header "FILES"
+.IP "\fB/etc/wgetrc\fR" 4
+.IX Item "/etc/wgetrc"
+Default location of the \fIglobal\fR startup file.
+.IP "\fB.wgetrc\fR" 4
+.IX Item ".wgetrc"
+User startup file.
+.SH "BUGS"
+.IX Header "BUGS"
+You are welcome to submit bug reports via the \s-1GNU\s0 Wget bug tracker (see
+<\fBhttps://savannah.gnu.org/bugs/?func=additem&group=wget\fR>) or to our
+mailing list <\fBbug\-wget@gnu.org\fR>.
+.PP
+Visit <\fBhttps://lists.gnu.org/mailman/listinfo/bug\-wget\fR> to
+get more info (how to subscribe, list archives, ...).
+.PP
+Before actually submitting a bug report, please try to follow a few
+simple guidelines.
+.IP "1." 4
+Please try to ascertain that the behavior you see really is a bug.  If
+Wget crashes, it's a bug.  If Wget does not behave as documented,
+it's a bug.  If things work strange, but you are not sure about the way
+they are supposed to work, it might well be a bug, but you might want to
+double-check the documentation and the mailing lists.
+.IP "2." 4
+Try to repeat the bug in as simple circumstances as possible.  E.g. if
+Wget crashes while downloading \fBwget \-rl0 \-kKE \-t5 \-\-no\-proxy
+http://example.com \-o /tmp/log\fR, you should try to see if the crash is
+repeatable, and if will occur with a simpler set of options.  You might
+even try to start the download at the page where the crash occurred to
+see if that page somehow triggered the crash.
+.Sp
+Also, while I will probably be interested to know the contents of your
+\&\fI.wgetrc\fR file, just dumping it into the debug message is probably
+a bad idea.  Instead, you should first try to see if the bug repeats
+with \fI.wgetrc\fR moved out of the way.  Only if it turns out that
+\&\fI.wgetrc\fR settings affect the bug, mail me the relevant parts of
+the file.
+.IP "3." 4
+Please start Wget with \fB\-d\fR option and send us the resulting
+output (or relevant parts thereof).  If Wget was compiled without
+debug support, recompile it\-\-\-it is \fImuch\fR easier to trace bugs
+with debug support on.
+.Sp
+Note: please make sure to remove any potentially sensitive information
+from the debug log before sending it to the bug address.  The
+\&\f(CW\*(C`\-d\*(C'\fR won't go out of its way to collect sensitive information,
+but the log \fIwill\fR contain a fairly complete transcript of Wget's
+communication with the server, which may include passwords and pieces
+of downloaded data.  Since the bug address is publicly archived, you
+may assume that all bug reports are visible to the public.
+.IP "4." 4
+If Wget has crashed, try to run it in a debugger, e.g. \f(CW\*(C`gdb \`which
+wget\` core\*(C'\fR and type \f(CW\*(C`where\*(C'\fR to get the backtrace.  This may not
+work if the system administrator has disabled core files, but it is
+safe to try.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+This is \fBnot\fR the complete manual for \s-1GNU\s0 Wget.
+For more complete information, including more detailed explanations of
+some of the options, and a number of commands available
+for use with \fI.wgetrc\fR files and the \fB\-e\fR option, see the \s-1GNU\s0
+Info entry for \fIwget\fR.
+.PP
+Also see \fBwget2\fR\|(1), the updated version of \s-1GNU\s0 Wget with even better
+support for recursive downloading and modern protocols like \s-1HTTP/2.\s0
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Originally written by Hrvoje Nikšić <hniksic@xemacs.org>.
+Currently maintained by Darshit Shah <darnir@gnu.org> and
+Tim Rühsen <tim.ruehsen@gmx.de>.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1996\-\-2011, 2015, 2018\-\-2023 Free Software
+Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled
+\&\*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/which.1 b/upstream/mageia-cauldron/man1/which.1
new file mode 100644
index 00000000..e91db9e0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/which.1
@@ -0,0 +1,155 @@
+.TH WHICH 1
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.na
+.SH NAME
+which \- shows the full path of (shell) commands.
+.SH SYNOPSIS
+.B which
+[options] [\-\-] programname [...]
+.SH DESCRIPTION
+\fBWhich\fR takes one or more arguments. For each of its arguments
+it prints to stdout the full path of the executables
+that would have been executed when this argument had been
+entered at the shell prompt. It does this by searching
+for an executable or script in the directories listed in
+the environment variable \fBPATH\fR using the same algorithm as \fBbash(1)\fR.
+
+This man page is generated from the file \fIwhich.texinfo\fR.
+.SH OPTIONS
+
+.TP 4
+.B --all\fR, \fB-a\fR
+Print all matching executables in \fBPATH\fR, not just the first.
+.TP
+.B --read-alias\fR, \fB-i\fR
+Read aliases from stdin, reporting matching ones on
+stdout. This is useful in combination with using an
+alias for which itself. For example
+.br
+.B 
+alias which=\'alias | which -i\'\fR.
+.TP
+.B --skip-alias\fR
+Ignore option \`--read-alias\', if any. This is useful to
+explicity search for normal binaries, while using
+the \`--read-alias\' option in an alias or function for which.
+.TP
+.B --read-functions\fR
+Read shell function definitions from stdin, reporting matching
+ones on stdout. This is useful in combination with using a shell
+function for which itself.  For example:
+.br
+.B 
+which() { declare -f | which --read-functions $@ }
+.br
+export -f which\fR
+.TP
+.B --skip-functions\fR
+Ignore option \`--read-functions\', if any. This is useful to
+explicity search for normal binaries, while using
+the \`--read-functions\' option in an alias or function for which.
+.TP
+.B --skip-dot\fR
+Skip directories in \fBPATH\fR that start with a dot.
+.TP
+.B --skip-tilde\fR
+Skip directories in \fBPATH\fR that start with a tilde and
+executables which reside in the \fBHOME\fR directory.
+.TP
+.B --show-dot\fR
+If a directory in \fBPATH\fR starts with a dot and a matching
+executable was found for that path, then print
+"./programname" rather than the full path.
+.TP
+.B --show-tilde\fR
+Output a tilde when a directory matches the \fBHOME\fR
+directory. This option is ignored when which is
+invoked as root.
+.TP
+.B --tty-only\fR
+Stop processing options on the right if not on tty.
+.TP
+.B --version,-v,-V\fR
+Print version information on standard output then exit
+successfully.
+.TP
+.B --help\fR
+Print usage information on standard output then exit
+successfully.
+.SH RETURN VALUE
+\fBWhich\fR returns the number of failed arguments, or -1 when
+no \`programname\' was given.
+.SH EXAMPLE
+The recommended way to use this utility is by adding an alias (C shell)
+or shell function (Bourne shell) for \fBwhich\fR like the following:
+
+[ba]sh:
+
+.in +5
+.nf
+.na
+which ()
+{
+  (alias; declare -f) | /usr/bin/which --tty-only --read-alias --read-functions --show-tilde --show-dot $@
+}
+export -f which
+.in -5
+.ad
+.fi
+
+[t]csh:
+
+.in +5
+.nf
+.na
+alias which \'alias | /usr/bin/which --tty-only --read-alias --show-dot --show-tilde\'
+.in -5
+.ad
+.fi
+
+This will print the readable ~/ and ./ when starting which
+from your prompt, while still printing the full path when
+used from a script:
+
+.in +5
+.nf
+.na
+> which q2
+~/bin/q2
+> echo \`which q2\`
+/home/carlo/bin/q2
+.in -5
+.ad
+.fi
+
+.SH BUGS
+The \fBHOME\fR directory is determined by looking for the \fBHOME\fR
+environment variable, which aborts when this variable
+doesn\'t exist.  \fBWhich\fR will consider two equivalent directories
+to be different when one of them contains a path
+with a symbolic link.
+.SH AUTHOR
+.br
+Carlo Wood <carlo@gnu.org>
+.SH "SEE ALSO"
+\fBbash(1)\fR
diff --git a/upstream/mageia-cauldron/man1/who.1 b/upstream/mageia-cauldron/man1/who.1
new file mode 100644
index 00000000..d1675b1f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/who.1
@@ -0,0 +1,84 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH WHO "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+who \- show who is logged on
+.SH SYNOPSIS
+.B who
+[\fI\,OPTION\/\fR]... [ \fI\,FILE | ARG1 ARG2 \/\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print information about users who are currently logged in.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+same as \fB\-b\fR \fB\-d\fR \fB\-\-login\fR \fB\-p\fR \fB\-r\fR \fB\-t\fR \fB\-T\fR \fB\-u\fR
+.TP
+\fB\-b\fR, \fB\-\-boot\fR
+time of last system boot
+.TP
+\fB\-d\fR, \fB\-\-dead\fR
+print dead processes
+.TP
+\fB\-H\fR, \fB\-\-heading\fR
+print line of column headings
+.TP
+\fB\-l\fR, \fB\-\-login\fR
+print system login processes
+.TP
+\fB\-\-lookup\fR
+attempt to canonicalize hostnames via DNS
+.TP
+\fB\-m\fR
+only hostname and user associated with stdin
+.TP
+\fB\-p\fR, \fB\-\-process\fR
+print active processes spawned by init
+.TP
+\fB\-q\fR, \fB\-\-count\fR
+all login names and number of users logged on
+.TP
+\fB\-r\fR, \fB\-\-runlevel\fR
+print current runlevel
+.TP
+\fB\-s\fR, \fB\-\-short\fR
+print only name, line, and time (default)
+.TP
+\fB\-t\fR, \fB\-\-time\fR
+print last system clock change
+.TP
+\fB\-T\fR, \fB\-w\fR, \fB\-\-mesg\fR
+add user's message status as +, \- or ?
+.TP
+\fB\-u\fR, \fB\-\-users\fR
+list users logged in
+.TP
+\fB\-\-message\fR
+same as \fB\-T\fR
+.TP
+\fB\-\-writable\fR
+same as \fB\-T\fR
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.PP
+If FILE is not specified, use \fI\,/run/utmp\/\fP.  \fI\,/var/log/wtmp\/\fP as FILE is common.
+If ARG1 ARG2 given, \fB\-m\fR presumed: 'am i' or 'mom likes' are usual.
+.SH AUTHOR
+Written by Joseph Arceneaux, David MacKenzie, and Michael Stone.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/who>
+.br
+or available locally via: info \(aq(coreutils) who invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/whoami.1 b/upstream/mageia-cauldron/man1/whoami.1
new file mode 100644
index 00000000..931d0b88
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/whoami.1
@@ -0,0 +1,34 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH WHOAMI "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+whoami \- print effective user name
+.SH SYNOPSIS
+.B whoami
+[\fI\,OPTION\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Print the user name associated with the current effective user ID.
+Same as id \fB\-un\fR.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by Richard Mlynarik.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/whoami>
+.br
+or available locally via: info \(aq(coreutils) whoami invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/whois-mkpasswd.1 b/upstream/mageia-cauldron/man1/whois-mkpasswd.1
new file mode 100644
index 00000000..121cc5a3
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/whois-mkpasswd.1
@@ -0,0 +1,94 @@
+.TH MKPASSWD 1 "2019-12-30" "Marco d'Itri" "Debian GNU/Linux"
+.SH NAME
+mkpasswd \- Overfeatured front end to crypt(3)
+.SH SYNOPSIS
+.B mkpasswd
+.I PASSWORD
+.RI [ SALT ]
+.SH DESCRIPTION
+.B mkpasswd
+encrypts the given password with the
+.BR crypt (3)
+libc function, using the given salt.
+.SH OPTIONS
+.TP
+.BR \-S ", "\c
+.BI \-\-salt= STRING
+Use the
+.I STRING
+as salt. If it begins with
+.I $
+then it will be passed straight to
+.BR crypt (3)
+without any checks.
+.TP
+.BR \-R ", "\c
+.BI \-\-rounds= NUMBER
+Use
+.I NUMBER
+rounds. This argument is ignored if the method chosen
+does not support variable rounds. For the OpenBSD Blowfish method this is
+the logarithm of the number of rounds.
+The behavior is undefined if this option is used without
+.IR \-\-method .
+.TP
+.BR \-m ", "\c
+.BI \-\-method= TYPE
+Compute the password using the
+.I TYPE
+method.
+If
+.I TYPE
+is
+.I help
+then the list of available methods is printed.
+If
+.I TYPE
+begins and end with
+.I $
+characters then the string is passed to
+.IR crypt_gensalt (3)
+as-is.
+.TP
+.B -5
+Like
+.IR \-\-method=md5crypt .
+.TP
+.B \-P \c
+.IR NUM ", "\c
+.BI \-\-password-fd= NUM
+Read the password from file descriptor
+.I NUM
+instead of using
+.IR getpass (3).
+If the file descriptor is not connected to a tty then no other text
+than the hashed password is printed on stdout.
+.TP
+.BR \-s ", " \-\-stdin
+Like
+.IR \-\-password-fd=0 .
+.SH ENVIRONMENT
+.IP "MKPASSWD_OPTIONS"
+A list of options which will be evaluated before the ones specified on the
+command line.
+.SH BUGS
+If the
+.I \-\-stdin
+option is used then passwords containing some control
+characters may not be read correctly.
+.P
+This program suffers of a bad case of featuritis.
+.SH "SEE ALSO"
+.IR passwd (1),
+.IR passwd (5),
+.IR crypt (3),
+.IR crypt (5),
+.IR crypt_gensalt (3),
+.IR getpass (3).
+.SH AUTHOR
+.B mkpasswd
+and this man page were written by Marco d'Itri
+.RI < md@linux.it >
+and are licensed under the terms of the GNU General Public License,
+version 2 or later.
+\" SPDX-License-Identifier: GPL-2.0-or-later
diff --git a/upstream/mageia-cauldron/man1/whois.1 b/upstream/mageia-cauldron/man1/whois.1
new file mode 100644
index 00000000..580c891f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/whois.1
@@ -0,0 +1,307 @@
+.TH "WHOIS" "1" "2019-12-30" "Marco d'Itri" "Debian GNU/Linux"
+.SH NAME
+whois \- client for the whois directory service
+.SH SYNOPSIS
+.B whois
+[
+.RB {\~ \-h \~|\~ \-\-host \~}
+.I HOST
+] [
+.RB {\~ \-p \~|\~ \-\-port \~}
+.I PORT
+] [\~\c
+.B \-abBcdGHIKlLmMrRx
+] [\~\c
+.BI \-g \~SOURCE:FIRST\-LAST
+] [\~\c
+.BR \-i \~
+.IR ATTR [, ATTR ]...\~]
+[\~\c
+.BR \-s \~
+.IR SOURCE [, SOURCE ]...\~]
+[\~\c
+.BR \-T \~
+.IR TYPE [, TYPE ]...\~]
+.RB [\~ \-\-verbose \~]
+.RB [\~ \-\-no\-recursion \~]
+.I OBJECT
+
+.B whois
+.B \-q
+.I KEYWORD
+
+.B whois
+.B \-t
+.I TYPE
+
+.B whois
+.B \-v
+.I TYPE
+
+.B whois \-\-help
+
+.B whois \-\-version
+
+.SH DESCRIPTION
+.B whois
+searches for an object in a
+.I RFC 3912
+database.
+.P
+This version of the whois client tries to guess the right server to
+ask for the specified object. If no guess can be made it will connect to
+.I whois.networksolutions.com
+for NIC handles or
+.I whois.arin.net
+for IPv4 addresses and network names.
+.SH OPTIONS
+.TP 8
+.B \-h \c
+.IR HOST ,
+.BI \-\-host= HOST
+Connect to
+.IR HOST .
+.TP 8
+.B \-H
+Do not display the legal disclaimers that some registries like to show you.
+.TP 8
+.B \-p \c
+.IR PORT ,
+.BI \-\-port= PORT
+Connect to
+.IR PORT .
+.TP 8
+.B \-I
+First query
+.I whois.iana.org
+and then follow its referral to the
+whois server authoritative for that request. This works for IP addresses,
+AS numbers and domains.
+.BR BEWARE :
+this implies that the IANA server will receive your complete query.
+.TP 8
+.B \-\-no\-recursion
+Disable recursion from registry to registrar servers.
+.TP 8
+.B \-\-verbose
+Be verbose.
+.TP 8
+.B \-\-help
+Display online help.
+.TP 8
+.B \-\-version
+Display the program version.
+.P
+Other options are flags understood by
+.I whois.ripe.net
+and some other
+RIPE-like servers:
+.TP 8
+.B \-a
+Also search all the mirrored databases.
+.TP 8
+.B \-b
+Return brief IP address ranges with abuse contact.
+.TP 8
+.B \-B
+Disable objects filtering.
+(Show the e-mail addresses.)
+.TP 8
+.B \-c
+Return the smallest IP address range with a reference to an irt object.
+.TP 8
+.B \-d
+Return the reverse DNS delegation object too.
+.TP 8
+.B \-g \c
+.I SOURCE:FIRST\-LAST
+Search updates from
+.I SOURCE
+database between
+.I FIRST
+and
+.I LAST
+update serial number. It is useful to obtain Near Real Time Mirroring stream.
+.TP 8
+.B \-G
+Disable grouping of associated objects.
+.TP 8
+.B \-i \c
+.IR ATTR [, ATTR ]...
+Inverse-search objects having associated attributes.
+.I ATTR
+is the attribute name, while the positional
+.I OBJECT
+argument is the attribute value.
+.TP 8
+.B \-K
+Return primary key attributes only. An exception is the
+.I members
+attribute of
+.I set
+objects, which is always returned. Another exception are all
+attributes of the objects
+.IR organisation ,
+.I person
+and
+.IR role ,
+that are never returned.
+.TP 8
+.B \-l
+Return the one level less specific object.
+.TP 8
+.B \-L
+Return all levels of less specific objects.
+.TP 8
+.B \-m
+Return all one level more specific objects.
+.TP 8
+.B \-M
+Return all levels of more specific objects.
+.TP 8
+.B \-q \c
+.I KEYWORD
+Return information about the server.
+.I KEYWORD
+can be
+.I version
+for the server version,
+.I sources
+for the list of database sources or
+.I types
+for the list of supported object types.
+.TP 8
+.B \-r
+Disable recursive lookups for contact information.
+.TP 8
+.B \-R
+Disable following referrals and force showing the object from the local copy
+in the server.
+.TP 8
+.B \-s \c
+.IR SOURCE [, SOURCE ]...
+Request the server to search for objects mirrored from
+.IR SOURCE .
+Sources are delimited by comma, and the order is significant.
+Use the
+.I \-q sources
+parameter to obtain a list of valid sources.
+.TP 8
+.B \-t \c
+.I TYPE
+Return the template for a object of
+.IR TYPE .
+.TP 8
+.B \-T \c
+.IR TYPE [, TYPE ]...
+Restrict the search to objects of
+.IR TYPE .
+Multiple types are separated by a comma.
+.TP 8
+.B \-v \c
+.I TYPE
+Return the verbose template for a object of
+.IR TYPE .
+.TP 8
+.B \-x
+Search for only exact match on network address prefix.
+.SH NOTES
+When querying the Verisign gTLDs (e.g.\& \&.com, \&.net...\&) thin registry servers
+for a domain, the program will automatically prepend the
+.I domain
+keyword to only show domain records.  The
+.I nameserver
+or
+.I registrar
+keywords must be used to show other kinds of records.
+.P
+When querying
+.I whois.arin.net
+for IPv4 or IPv6 networks, the CIDR
+netmask length will be automatically removed from the query string.
+.P
+When querying
+.I whois.nic.ad.jp
+for AS numbers, the program will automatically convert the request
+in the appropriate format, inserting a space after the string
+.IR AS .
+.P
+When querying
+.I whois.denic.de
+for domain names and no other
+flags have been specified, the program will automatically add the flag
+.IR "\-T dn" .
+.P
+When querying
+.I whois.dk\-hostmaster.dk
+for domain names and no other
+flags have been specified, the program will automatically add the flag
+.IR "\-\-show\-handles" .
+.P
+RIPE-specific command line options are ignored when querying non-RIPE
+servers. This may or may not be the behaviour intended by the user.
+When using non-standard query parameters then the command line options
+which are not to be interpreted by the client must follow the
+.I \-\-
+separator (which marks the beginning of the query string).
+.P
+If the
+.I /etc/whois.conf
+configuration file exists, it will be consulted
+to find a server before applying the normal rules. Each line of the
+file should contain a regular expression to be matched against the query
+text and the whois server to use, separated by white space.
+IDN domains must use the ACE format.
+.P
+The whois protocol does not specify an encoding for characters which
+cannot be represented by ASCII and implementations vary wildly.
+If the program knows that a specific server uses a certain encoding,
+if needed it will transcode the server output to the encoding specified
+by the current system locale.
+.P
+Command line arguments will always be interpreted accordingly to the
+current system locale and converted to the IDN ASCII Compatible Encoding.
+.SH "FILES"
+/etc/whois.conf
+.SH "ENVIRONMENT"
+.IP LANG
+When querying
+.I whois.nic.ad.jp
+and
+.I whois.jprs.jp
+English text is requested unless the
+.I LANG
+or
+.I LC_MESSAGES
+environment variables specify a Japanese locale.
+.IP "WHOIS_OPTIONS"
+A list of options which will be evaluated before the ones specified on the
+command line.
+.IP "WHOIS_SERVER"
+This server will be queried if the program cannot guess where some kind
+of objects are located. If the variable does not exist then
+.I whois.arin.net
+will be queried.
+.SH "SEE ALSO"
+.IR whois.conf (5).
+.P
+.IR "RFC 3912" :
+WHOIS Protocol Specification.
+.P
+.IR "RIPE Database Query Reference Manual" :
+.RI < http://www.ripe.net/data\-tools/support/documentation/ripe\-database\-query\-reference\-manual >
+.SH BUGS
+The program may have buffer overflows in the command line parser:
+be sure to not pass untrusted data to it.
+It should be rewritten to use a dynamic strings library.
+.SH HISTORY
+This program closely tracks the user interface of the whois client
+developed at RIPE by Ambrose Magee and others on the base of the
+original BSD client.
+.SH AUTHOR
+.B Whois
+and this man page were written by Marco d'Itri
+.RI < md@linux.it >
+and are licensed under the terms of the GNU General Public License,
+version 2 or later.
+\" SPDX-License-Identifier: GPL-2.0-or-later
diff --git a/upstream/mageia-cauldron/man1/windmc.1 b/upstream/mageia-cauldron/man1/windmc.1
new file mode 100644
index 00000000..9d16ddea
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/windmc.1
@@ -0,0 +1,360 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.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'
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.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 "WINDMC 1"
+.TH WINDMC 1 "2023-06-27" "binutils-2.40" "GNU Development Tools"
+.\" 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"
+windmc \- generates Windows message resources
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+windmc [options] input-file
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBwindmc\fR reads message definitions from an input file (.mc) and
+translate them into a set of output files.  The output files may be of
+four kinds:
+.ie n .IP """h""" 4
+.el .IP "\f(CWh\fR" 4
+.IX Item "h"
+A C header file containing the message definitions.
+.ie n .IP """rc""" 4
+.el .IP "\f(CWrc\fR" 4
+.IX Item "rc"
+A resource file compilable by the \fBwindres\fR tool.
+.ie n .IP """bin""" 4
+.el .IP "\f(CWbin\fR" 4
+.IX Item "bin"
+One or more binary files containing the resource data for a specific
+message language.
+.ie n .IP """dbg""" 4
+.el .IP "\f(CWdbg\fR" 4
+.IX Item "dbg"
+A C include file that maps message id's to their symbolic name.
+.PP
+The exact description of these different formats is available in
+documentation from Microsoft.
+.PP
+When \fBwindmc\fR converts from the \f(CW\*(C`mc\*(C'\fR format to the \f(CW\*(C`bin\*(C'\fR
+format, \f(CW\*(C`rc\*(C'\fR, \f(CW\*(C`h\*(C'\fR, and optional \f(CW\*(C`dbg\*(C'\fR it is acting like the
+Windows Message Compiler.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-a\fR" 4
+.IX Item "-a"
+.PD 0
+.IP "\fB\-\-ascii_in\fR" 4
+.IX Item "--ascii_in"
+.PD
+Specifies that the input file specified is \s-1ASCII.\s0 This is the default
+behaviour.
+.IP "\fB\-A\fR" 4
+.IX Item "-A"
+.PD 0
+.IP "\fB\-\-ascii_out\fR" 4
+.IX Item "--ascii_out"
+.PD
+Specifies that messages in the output \f(CW\*(C`bin\*(C'\fR files should be in \s-1ASCII\s0
+format.
+.IP "\fB\-b\fR" 4
+.IX Item "-b"
+.PD 0
+.IP "\fB\-\-binprefix\fR" 4
+.IX Item "--binprefix"
+.PD
+Specifies that \f(CW\*(C`bin\*(C'\fR filenames should have to be prefixed by the
+basename of the source file.
+.IP "\fB\-c\fR" 4
+.IX Item "-c"
+.PD 0
+.IP "\fB\-\-customflag\fR" 4
+.IX Item "--customflag"
+.PD
+Sets the customer bit in all message id's.
+.IP "\fB\-C\fR \fIcodepage\fR" 4
+.IX Item "-C codepage"
+.PD 0
+.IP "\fB\-\-codepage_in\fR \fIcodepage\fR" 4
+.IX Item "--codepage_in codepage"
+.PD
+Sets the default codepage to be used to convert input file to \s-1UTF16.\s0 The
+default is ocdepage 1252.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+.PD 0
+.IP "\fB\-\-decimal_values\fR" 4
+.IX Item "--decimal_values"
+.PD
+Outputs the constants in the header file in decimal. Default is using
+hexadecimal output.
+.IP "\fB\-e\fR \fIext\fR" 4
+.IX Item "-e ext"
+.PD 0
+.IP "\fB\-\-extension\fR \fIext\fR" 4
+.IX Item "--extension ext"
+.PD
+The extension for the header file. The default is .h extension.
+.IP "\fB\-F\fR \fItarget\fR" 4
+.IX Item "-F target"
+.PD 0
+.IP "\fB\-\-target\fR \fItarget\fR" 4
+.IX Item "--target target"
+.PD
+Specify the \s-1BFD\s0 format to use for a bin file as output.  This
+is a \s-1BFD\s0 target name; you can use the \fB\-\-help\fR option to see a list
+of supported targets.  Normally \fBwindmc\fR will use the default
+format, which is the first one listed by the \fB\-\-help\fR option.
+.IP "\fB\-h\fR \fIpath\fR" 4
+.IX Item "-h path"
+.PD 0
+.IP "\fB\-\-headerdir\fR \fIpath\fR" 4
+.IX Item "--headerdir path"
+.PD
+The target directory of the generated header file. The default is the
+current directory.
+.IP "\fB\-H\fR" 4
+.IX Item "-H"
+.PD 0
+.IP "\fB\-\-help\fR" 4
+.IX Item "--help"
+.PD
+Displays a list of command-line options and then exits.
+.IP "\fB\-m\fR \fIcharacters\fR" 4
+.IX Item "-m characters"
+.PD 0
+.IP "\fB\-\-maxlength\fR \fIcharacters\fR" 4
+.IX Item "--maxlength characters"
+.PD
+Instructs \fBwindmc\fR to generate a warning if the length
+of any message exceeds the number specified.
+.IP "\fB\-n\fR" 4
+.IX Item "-n"
+.PD 0
+.IP "\fB\-\-nullterminate\fR" 4
+.IX Item "--nullterminate"
+.PD
+Terminate message text in \f(CW\*(C`bin\*(C'\fR files by zero. By default they are
+terminated by \s-1CR/LF.\s0
+.IP "\fB\-o\fR" 4
+.IX Item "-o"
+.PD 0
+.IP "\fB\-\-hresult_use\fR" 4
+.IX Item "--hresult_use"
+.PD
+Not yet implemented. Instructs \f(CW\*(C`windmc\*(C'\fR to generate an \s-1OLE2\s0 header
+file, using \s-1HRESULT\s0 definitions. Status codes are used if the flag is not
+specified.
+.IP "\fB\-O\fR \fIcodepage\fR" 4
+.IX Item "-O codepage"
+.PD 0
+.IP "\fB\-\-codepage_out\fR \fIcodepage\fR" 4
+.IX Item "--codepage_out codepage"
+.PD
+Sets the default codepage to be used to output text files. The default
+is ocdepage 1252.
+.IP "\fB\-r\fR \fIpath\fR" 4
+.IX Item "-r path"
+.PD 0
+.IP "\fB\-\-rcdir\fR \fIpath\fR" 4
+.IX Item "--rcdir path"
+.PD
+The target directory for the generated \f(CW\*(C`rc\*(C'\fR script and the generated
+\&\f(CW\*(C`bin\*(C'\fR files that the resource compiler script includes. The default
+is the current directory.
+.IP "\fB\-u\fR" 4
+.IX Item "-u"
+.PD 0
+.IP "\fB\-\-unicode_in\fR" 4
+.IX Item "--unicode_in"
+.PD
+Specifies that the input file is \s-1UTF16.\s0
+.IP "\fB\-U\fR" 4
+.IX Item "-U"
+.PD 0
+.IP "\fB\-\-unicode_out\fR" 4
+.IX Item "--unicode_out"
+.PD
+Specifies that messages in the output \f(CW\*(C`bin\*(C'\fR file should be in \s-1UTF16\s0
+format. This is the default behaviour.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+.PD 0
+.IP "\fB\-\-verbose\fR" 4
+.IX Item "--verbose"
+.PD
+Enable verbose mode.
+.IP "\fB\-V\fR" 4
+.IX Item "-V"
+.PD 0
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+.PD
+Prints the version number for \fBwindmc\fR.
+.IP "\fB\-x\fR \fIpath\fR" 4
+.IX Item "-x path"
+.PD 0
+.IP "\fB\-\-xdgb\fR \fIpath\fR" 4
+.IX Item "--xdgb path"
+.PD
+The path of the \f(CW\*(C`dbg\*(C'\fR C include file that maps message id's to the
+symbolic name. No such file is generated without specifying the switch.
+.IP "\fB@\fR\fIfile\fR" 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+the Info entries for \fIbinutils\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2023 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
diff --git a/upstream/mageia-cauldron/man1/winicon.1 b/upstream/mageia-cauldron/man1/winicon.1
new file mode 100644
index 00000000..f22d043f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/winicon.1
@@ -0,0 +1,130 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Windows Icons" 1 "12 April 2013" "netpbm documentation"
+
+.SH NAME
+
+Microsoft Windows icon files
+
+.UN description
+.SH DESCRIPTION
+.PP
+A Microsoft Windows icon file contains one or more images, at
+resolutions up to 256 by 256 pixels and various bpp values.  The
+images are encoded either as Portable Network Graphics file (PNG), or
+in a format similar to Microsoft's BMP format.
+.PP
+If encoded as BMP, the image includes an "AND mask",
+which contains 1-bit transparency data.  It may also contain
+additional 8-bit transparency data together with the color
+information.
+
+.UN colordepth
+.SS Color Depth
+
+Except for the 16 bits per pixel images and images with bit fields, which both
+are rare, the colors in all BMP encoded images are RGB with 8 bits per
+channel.  Images with bpp values lower than 16 use a palette.
+.PP
+I.e. the bpp value gives the number of distinct colors, not the color
+depth.
+
+
+.UN masks
+.SS XOR Mask and AND Mask
+.PP
+BMP encoded images contain two pixel maps: The so-called "XOR
+mask" stores the color information for each pixel, and the
+"AND mask" stores the transparency belonging to it.
+.PP
+The names and the function of these maps are most easily
+understood by looking at how a 1-bpp icon image is rendered on a
+monochrome screen: The pixels on the screen are logically AND-ed with
+the bits on the AND mask, then the result is logically XOR-ed with the
+bits on the XOR mask.
+.PP
+The result is that if a bit on the AND mask is reset, the corresponding bit
+on the XOR mask determines the color of the pixel on the screen.  If a bit in
+the AND mask is set and the corresponding bit in the XOR mask is black
+(reset), the image is transparent.  Finally, if the bits are set in both the
+AND and XOR mask (the pixel on the XOR mask is white), the background of the
+screen is inverted.
+.PP
+In color environments, a pixel on the XOR mask outside the opaque area of
+the image is usually black and sometimes white, but a color other than black
+and white will hardly give predictable results.
+.PP
+Since Windows XP, there may also be an 8-bit transparency channel in 32-bpp
+BMP encoded icon images. The AND mask, however, is still required and used
+e.g. for generating shadows.
+.PP
+PNG encoded images don't contain AND masks.  While rendering a PNG encoded
+image, Windows constructs an AND mask on the fly from the transparency
+channel, if present.
+
+
+.UN evolution
+.SS Evolution of Windows Icons
+.PP
+The Windows icon file format has undergone some extensions since it was
+invented in the mid-eighties for Windows\ 1:
+
+
+.IP \(bu
+Windows\ 1 used monochrome 32x32 icons only.
+.IP \(bu
+Windows\ 3.0 added color icons with bpp values up to 8.
+.IP \(bu
+Windows 4.0 (a.k.a. Windows95) added option for 32-bpp images and
+resolutions up to 256 by 256.
+.IP \(bu
+NT\ 5.1 (a.k.a. Windows\ XP) added option for the 8-bit
+transparency channel in the unused bits of 32-bpp images.
+.IP \(bu
+NT\ 6.0 (a.k.a. Windows\ Vista) added option for PNG
+encoded images
+
+
+.UN resolutions
+.SS Common Resolutions and BPP Values
+.PP
+Typical resolutions and bpp values of the Windows shell icons include:
+
+.TS
+l l l.
+_
+OS	resolutions	bpp values
+Windows\ 3	32x32	1, 4
+
+Windows\ 4	16x16, 32x32, 48x48	4, 8
+NT\ 5	16x16, 32x32, 48x48	4, 8, 32
+NT\ 6	16x16, 32x32, 48x48	4, 8, 32
+24x24, 96x96	8, 32
+
+256x256	32 (PNG encoded)
+
+.TE
+.PP
+Within the icon file, the images with low bpp values are usually
+stored first.  With the same bpp value, the images are sorted by
+resolution, large images first.
+
+
+.UN mimetype
+.SS MIME Type and File Name Extension
+.PP
+The MIME type of Windows icon files is registered by IANA as
+\fBimage/vnd.microsoft.icon\fP, but the unofficial name
+\fBimage/x-icon\fP is still widely used.
+.PP
+The file name extension (used by Microsoft operating systems as
+file type identifier) is \fB.ico\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/winicon.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/winicontopam.1 b/upstream/mageia-cauldron/man1/winicontopam.1
new file mode 100644
index 00000000..8b2d69e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/winicontopam.1
@@ -0,0 +1,157 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Winicontopam User Manual" 0 "29 August 2020" "netpbm documentation"
+
+.SH NAME
+
+winicontopam - convert a Microsoft Windows icon file into a Netpbm PAM file
+
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBwinicontopam\fP
+[\fB-image=\fP\fIindex\fP | \fB-allimages\fP]
+[\fB-andmasks\fP]
+[\fB-verbose\fP]
+[\fIicon_file\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or equals signs between an option name and
+its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBwinicontopam\fP reads a Microsoft Windows icon file and converts it to
+one or more RGB_ALPHA Netpbm PAM images.
+.PP
+There are two kinds of transparency information a a Windows icon can have:
+and mask and graded transparency map.  The and mask is older and indicates for
+each pixel whether it is fully opaque or fully transparent.  The graded
+transparency map can indicate translucent values too.  The graded transparency
+map is present in an icon that uses PNG encoding or uses BMP encoding with 32
+bits per pixel.
+.PP
+The transparency plane in the PAM output of \fBwinicontopam\fP comes from
+  the graded transparency map if it exists and the and mask otherwise.
+.PP
+An icon may actually have both forms of transparency information.  See
+\fB-andmasks\fP.
+.PP
+The output goes to Standard Output.
+.PP
+The output is a multi-image PAM file.  If you want a separate file for
+each image, use
+.BR "\fBpamsplit\fP" (1)\c
+\&.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBwinicontopam\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-allimages\fP
+Convert all images in the input.
+.sp
+You may not specify this together with \fB-image\fP.
+.sp
+By default, \fBwinicontopam\fP converts only the one "best
+quality" image (largest, then most bits per pixel).
+
+.TP
+\fB-image=\fP\fIindex\fP
+Convert image number \fIindex\fP (starting with zero).
+.sp
+You may not specify this together with \fB-allimages\fP.
+.sp
+By default, \fBwinicontopam\fP converts the "best quality"
+image (largest, then most bits per pixel).
+
+.TP
+\fB-andmasks\fP
+If the image to be extracted contains both graded transparency data and an
+AND mask, produce five-channel Netpbm PAM images with the AND mask as the
+fifth plane.  An image that formally has graded transparency data, but it
+indicates nothing but opaque pixels is considered not to have graded
+transparency data, so \fB-andmasks\fP would have no effect on it.
+
+.TP
+\fB-verbose\fP
+Print more messages
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+
+
+.IP \(bu
+
+.BR "\fBpamtowinicon\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBwinicontoppm\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBpamsplit\fP" (1)\c
+\&
+.IP \(bu
+
+.BR "\fBpam\fP" (1)\c
+\& 
+.IP \(bu
+
+.BR "\fBwinicon\fP" (1)\c
+\&
+
+.PP
+For information on the PNG format,
+see 
+.UR http://schaik.com/png
+http://schaik.com/png
+.UE
+\&.
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBwinicontopam\fP was new in Netpbm 10.63 (June 2013).  It obsoleted
+\fBwinicontoppm\fP by providing more function and conforming better to Netpbm
+conventions.
+
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 2013 by Ludolf Holzheid.
+.PP
+Translated to Netpbm coding style by Bryan Henderson.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/winicontopam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/winicontoppm.1 b/upstream/mageia-cauldron/man1/winicontoppm.1
new file mode 100644
index 00000000..20786036
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/winicontoppm.1
@@ -0,0 +1,116 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Winicontoppm User Manual" 0 "23 March 2003" "netpbm documentation"
+
+.SH NAME
+winicontoppm - convert a Windows .ico image into 1 or more PPM images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBwinicontoppm\fP
+[\fB-writeands\fP]
+[\fB-allicons\fP|\fB-bestqual\fP]
+[\fB-multippm\fP]
+[\fB-verbose\fP]
+[\fIiconfile\fP]
+[\fIppmdestfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+This program is essentially obsolete; The newer \fBwinicontopam\fP is
+better.
+.PP
+\fBwinicontoppm\fP reads a Microsoft Windows .ico file and
+converts it to one or more PPMs.
+.PP
+A Windows icon contains one or more images, at different resolutions
+and color depths.  Each image has an 'and' mask, which contains transparancy
+data. 
+.PP
+By default, the output goes to Standard Output.  If you specify
+\fIppmdestfile\fP, output goes into one or more files named as
+follows.  If it's just one file (i.e. you specify the \fB-multippm\fP
+option or don't specify \fB-allicons\fP), the file name is
+\fIppmdestfile\fP\fB.ppm\fP.  If it's multiple files, their file
+names are \fIppmdestfile\fP\fB_1.ppm\fP,
+\fIppmdestfile\fP\fB_2.ppm\fP, etc.  
+.PP
+ When you specify the
+\fB-writeands\fP option, the file names above are modified to include
+the string \fBxor\fP as in \fIppmdestfile\fP\fB_xor.ppm\fP or
+\fIppmdestfile\fP\fB_xor_1.ppm\fP.
+.PP
+\fBwinicontoppm\fP can convert .ico images with 1, 4, 8, 24, or
+32 bits per pixel.  Before Netpbm 10.15 (April 2003), it could not handle
+24 and 32.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBwinicontoppm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-writeands\fP
+For each icon written, also write the 'and' (transparancy) mask as
+a separate PBM file.  It's name is of the form
+\fIppmdestfile\fP\fB_and.pbm\fP or
+\fIppmdestfile\fP\fB_and_1.pbm\fP.
+
+.TP
+\fB-allicons\fP
+Extract all images from the .ico file.
+.sp
+If you specify neither this nor \fB-bestqual\fP, \fBwinicontoppm\fP
+extracts the first image.
+
+.TP
+\fB-bestqual\fP
+Extract only the best quality (largest, then highest bpp) image
+from the .ico file.
+.sp
+If you specify neither this nor \fB-allicons\fP, \fBwinicontoppm\fP
+extracts the first image.
+
+.TP
+\fB-multippm\fP
+Write all PPMs to a single file.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "winicontopam" (1)\c
+\&,
+.BR "pamtowinicon" (1)\c
+\&,
+.BR "bmptopnm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 2000, 2003 by Lee Benfield.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/winicontoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/wodim.1 b/upstream/mageia-cauldron/man1/wodim.1
new file mode 100644
index 00000000..1af2e515
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/wodim.1
@@ -0,0 +1,2353 @@
+.\" @(#)wodim.1	 06/12/18 Copyright 2006 Cdrkit maintainers
+.\" derived from:
+.\" @(#)cdrecord.1	1.106 06/02/09 Copyright 1996 J. Schilling
+.\" 
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License version 2
+.\" as published by the Free Software Foundation.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License along with
+.\" this program; see the file COPYING.  If not, write to the Free Software
+.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.\"
+.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
+.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
+.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
+.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
+.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
+.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U
+.if t .ds s \\(*b
+.if t .ds S SS
+.if n .ds a ae
+.if n .ds o oe
+.if n .ds u ue
+.if n .ds s sz
+.if t .ds m \\(*m
+.if n .ds m micro
+.TH wodim 1 "Version 2.0" "" ""
+.SH NAME
+wodim \- write data to optical disk media
+.SH SYNOPSIS
+.B wodim
+.RI [ options "] " track1 .\|.\|. trackn
+.SH NOTE
+There may be similarities and differences between this program and other disk recording application(s). See the
+.B CREDITS
+and
+.B AUTHORS
+sections below to learn about the origin of
+.B wodim.
+
+.SH DESCRIPTION
+.B wodim
+is used to record data or audio Compact Discs on an Orange Book
+CD-Recorder or to write DVD media on a DVD-Recorder.
+.PP
+The
+.I device
+is the device file or label offered by the operating system to access the
+recorder with SCSI GENERIC (sg) interface. Note that some operating systems may
+provide separate device nodes for block\-oriented and sg access. For example, on
+older
+.I Linux
+systems, the sg access was available through
+.IR /dev/sg...
+files while the block oriented access was done through associated (but not identical)
+.IR /dev/hd...
+and 
+.IR /dev/sr...
+(or 
+.IR /dev/scd...
+) files.
+.PP
+In any case, the user running 
+.B wodim
+needs read and write access to the particular device file on a Linux system. It
+is recommended to be root or install the application as suid-root, because
+certain versions of Linux (kernel) limit the set of SCSI commands allowed for
+non-root users. Even if usage without root identity is possible in many cases,
+some device drivers still may fail, show unexplainable problems and generally
+the problems become harder to debug. The risk for buffer-underruns is also
+increased. See the
+.IR "PROCESS SCHEDULING PRIORITY"
+section below for more details.
+.PP
+There is an alternative way of specifying the device, using the traditional SCSI descriptions in form of
+.IR devicetype:bus/target/lun
+specification. However, the success of this method is not guaranteed since it
+requires an adaptation scheme for your architecture, and the numbers may vary
+depending on the hardware-internal numbering or on the order of hot-plug device
+detection. If your operating system does not provide a sufficient framework for
+keeping this numbers persistent, don't rely on them. See 
+.B \-scanbus
+and
+.B \-\-devices
+options below for details.
+.PP
+There are emulated SCSI compatible device systems, using the SCSI protocols
+transported over various hardware/media types. The most known examples is ATAPI
+("IDE burners") or USB storage ("external USB case"). If the pseudo-SCSI b/t/l
+device address specification is used instead of the native one, you need to
+prepend the "devicetype:" description to the emulated "bus/target/lun" device
+address.
+.PP
+If a file /etc/wodim.conf exists, the parameter to the
+.B dev=
+option may also be a drive name label in that file (see FILES section).
+.PP
+As a special exception, the device specification can be
+.IR -1
+or just omitted, which invokes automatic guessing of an appropriate device for
+the selected operation. However, this guessing is not available everywhere and
+is not reliable; it is only available for the user's convenience in simple
+environments.
+.PP
+In 
+.I Track At Once 
+mode, each
+.I track
+corresponds to a single file that contains the prepared data for that track.
+If the argument is 
+.RB ` \- ',
+standard input is used for that track. 
+Only one track may be taken from 
+.IR stdin .
+In the other write modes, the direct file to track relation may not be implemented.
+In 
+.B \-clone
+mode, a single file contains all data for the whole disk.
+To allow DVD writing on platforms that do not implement large file support,
+.B wodim
+concatenates all file arguments to a single track when writing to DVD media.
+
+.SH "PROCESS SCHEDULING PRIORITY"
+.PP
+Wodim tries to get higher process priority using different methods. This is
+important because the burn process is usually a realtime task, no long delays
+should occur while transmitting fresh data to the recorder. This is especially
+important on systems with insufficient RAM where swapping can create delays of
+many seconds.
+.PP
+A possible workaround on underpowered systems is the use of the burnfree or
+similar feature, allowing the recorder to resume.
+.PP
+Root permissions are usually required to get higher process scheduling priority.
+.PP
+On 
+.B SVr4 
+compliant systems, 
+.B wodim 
+uses the real time class to get the highest scheduling priority that is
+possible (higher than all kernel processes).
+On systems with 
+.B POSIX real time scheduling
+wodim uses real time scheduling too, 
+but may not be able to gain a priority that is higher than all kernel processes.
+.PP
+In order to be able to use the SCSI transport subsystem of the OS, run at highest
+priority and lock itself into core
+.B
+wodim
+either needs to be run as root, needs to be installed suid root or
+must be called via
+.B RBACs
+pfexec mechanism.
+
+.SH "GENERAL OPTIONS
+.PP
+General options must be before any track file name or track option.
+.TP
+.B \-version
+Print version information and exit.
+.TP
+.B \-v
+Increment the level of general verbosity by one.
+This is used e.g. to display the progress of the writing process.
+.TP
+.B \-V
+Increment the verbose level in respect of SCSI command transport by one.
+This helps to debug problems
+during the writing process, that occur in the CD/DVD-Recorder. 
+If you get incomprehensible error messages you should use this flag
+to get more detailed output.
+.B \-VV
+will show data buffer content in addition.
+Using
+.B \-V
+or
+.B \-VV
+slows down the process and may be the reason for a buffer underrun.
+.TP
+.BI debug= "#, " -d
+Set the misc debug value to # (with debug=#) or increment
+the misc debug level by one (with -d). If you specify
+.I -dd,
+this equals to 
+.BI debug= 2.
+This may help to find problems while opening a driver for libusal
+as well as with sector sizes and sector types.
+Using
+.B \-debug
+slows down the process and may be the reason for a buffer underrun.
+.TP
+.BR kdebug= "#, " kd= #
+Tell the 
+.BR usal -driver
+to modify the kernel debug value while SCSI commands are running.
+.TP
+.BR \-silent ", " \-s
+Do not print out a status report for failed SCSI commands.
+.TP
+.B \-force
+Force to continue on some errors. Be careful when using this option.
+.B wodim
+implements several checks that prevent you from doing unwanted things
+like damaging CD-RW media by improper drives. Many of the sanity checks are 
+disabled when the 
+.B \-force
+option is used.
+.sp
+This option also implements some tricks that will allow 
+you to blank bad CD-RW disks.
+.TP
+.B \-immed
+Tell wodim to set the
+.B "SCSI IMMED"
+flag in certain commands
+(load/eject/blank/close_track/close_session).
+This can be useful
+on broken systems with ATAPI harddisk and CD/DVD writer on the same bus or
+with SCSI systems that don't use disconnect/reconnect.
+These systems will freeze while blanking or fixating a CD/DVD or while a DVD
+writer is filling up a session to the minimum amount (approx. 800 MB).
+Setting the
+.B \-immed
+flag will request the command to return immediately
+while the operation proceeds in background, making
+the bus usable for the other devices and avoiding the system freeze.
+This is an experimental feature which may work or not, depending on the model
+of the CD/DVD writer.
+A correct solution would be to set up a correct cabling but there seem to be 
+notebooks around that have been set up the wrong way by the manufacturer.
+As it is impossible to fix this problem in notebooks, the
+.B \-immed
+option has been added.
+.sp
+A second experimental feature of the
+.B \-immed
+flag is to tell wodim to try to wait short times while writing to the
+media. This is expected to free the IDE bus if the CD/DVD writer and the
+data source are connected to the same IDE cable. In this case, the CD/DVD
+writer would otherwise usually block the IDE bus for nearly all the time
+making it impossible to fetch data from the source drive. See also
+.B minbuf=
+and
+.B \-v
+option.
+.sp
+Use both features at your own risk.
+If it turns out that it would make sense to have a separate option
+for the wait feature, write to the author and convince him.
+.TP
+.BI minbuf= value
+The #
+.B minbuf=
+option allows to define the minimum drive buffer fill ratio for the
+experimental ATAPI wait mode that is intended to free the IDE bus
+to allow hard disk and CD/DVD writer to be on the same IDE cable.
+As the wait mode currently only works when the verbose option
+.B \-v
+has been specified, 
+.B wodim
+implies the verbose option in case the 
+.B \-immed
+or
+.B minbuf=
+option have been specified.
+Valid values for 
+.B minbuf= 
+are between 25 and 95 for 25%.\|.\|.95% minimum drive buffer fill ratio.
+.TP
+.B \-dummy
+The CD/DVD-Recorder will go through all steps of the recording process,
+but the laser is turned off during this procedure.
+It is recommended to run several tests before actually writing to a 
+Compact Disk or Digital Versatile Disk,
+if the timing and load response of the system is not known.
+.TP
+.B \-clone
+Tells 
+.B wodim
+to handle images created by
+.IR "readom \-clone" .
+The
+.B \-clone
+may only be used in conjunction with with the
+.B \-raw96r
+or with the
+.B \-raw16
+option.
+Using
+.B \-clone
+together with
+.B \-raw96r
+is preferred as it allows to write all subchannel data.
+The option
+.B \-raw16
+should only be used with drives that do not support to write in
+.B \-raw96r
+mode.
+.TP
+.B \-dao
+.TP
+.B \-sao
+Set 
+.B "SAO (Session At Once)
+mode which is usually called
+.BR "Disk At Once " mode.
+This currently only works with MMC drives that support
+.B "Session At Once
+mode.
+Note that wodim needs to know the size of each track in advance for this mode
+(see the
+.B "genisoimage \-print-size"
+option and the 
+.I EXAMPLES
+section for more information).
+.TP
+.B \-tao
+Set
+.B "TAO (Track At Once) writing mode.
+This is the default write mode in previous
+.B wodim
+versions.
+With most drives, this write mode is required for multi session recording.
+.TP
+.B \-raw
+Set
+.B "RAW writing mode.
+Using this option defaults to 
+.BR \-raw96r .
+Note that wodim needs to know the size of each track in advance for this mode
+(see the
+.B "genisoimage \-print-size"
+option and the 
+.I EXAMPLES
+section for more information).
+.TP
+.B \-raw96r
+Select
+Set
+.B "RAW writing mode
+with 2352 byte sectors plus 96 bytes of raw P-W subchannel data resulting
+in a sector size of 2448 bytes.
+This is the preferred raw writing mode as it gives best control over the
+CD writing process.
+If you find any problems with the layout of a disk or with sub channel 
+content (e.g. wrong times on the display when playing the CD) and your drive
+supports to write in 
+.B \-raw96r
+or
+.B \-raw16
+mode, you should give it a try. There are several CD writers with bad firmware
+that result in broken disks when writing in TAO or SAO mode.
+Writing data disks in raw mode needs significantly more CPU time than other
+write modes. If your CPU is too slow, this may result in buffer underruns.
+Note that wodim needs to know the size of each track in advance for this mode
+(see the
+.B "genisoimage \-print-size"
+option and the 
+.I EXAMPLES
+section for more information).
+.TP
+.B \-raw96p
+Select
+Set
+.B "RAW writing mode
+with 2352 byte sectors plus 96 bytes of packed P-W subchannel data resulting
+in a sector size of 2448 bytes.
+This is the less preferred raw writing mode as only a few recorders support
+it and some of these recorders have bugs in the firmware implementation.
+Don't use this mode if your recorder supports
+.B \-raw96r
+or
+.BR \-raw16 .
+Writing data disks in raw mode needs significantly more CPU time than other
+write modes. If your CPU is too slow, this may result in buffer underruns.
+Note that wodim needs to know the size of each track in advance for this mode
+(see the
+.B "genisoimage \-print-size"
+option and the 
+.I EXAMPLES
+section for more information).
+.TP
+.B \-raw16
+Select
+Set
+.B "RAW writing mode
+with 2352 byte sectors plus 16 bytes of P-Q subchannel data resulting
+in a sector size of 2368 bytes.
+If a recorder does not support 
+.BR \-raw96r ,
+this is the preferred raw writing mode.
+It does not allow to write
+.I CD-Text
+or
+.I CD+Graphics
+but it is the only raw writing mode in cheap CD writers.
+As these cheap writers in most cases do not support
+.B \-dao
+mode.
+Don't use this mode if your recorder supports
+.BR \-raw96r .
+Writing data disks in raw mode needs significantly more CPU time than other
+write modes. If your CPU is too slow, this may result in buffer underruns.
+Note that wodim needs to know the size of each track in advance for this mode
+(see the
+.B "genisoimage \-print-size"
+option and the 
+.I EXAMPLES
+section for more information).
+.TP
+.B \-multi
+Allow multi session CDs to be made. This flag needs to be present
+on all sessions of a multi session disk,
+except you want to create a session that will be 
+the last session on the media.
+The fixation will be done in a way that allows the CD/DVD-Recorder to
+append additional sessions later. This is done by generation a TOC
+with a link to the next program area. The so generated media is not
+100% compatible to manufactured CDs (except for CDplus). 
+Use only for recording of multi session CDs.
+If this option is present, the default track type is
+.BR "CD-ROM XA mode 2 form 1"
+and the sector size is 2048 bytes. 
+The XA sector subheaders will be created by the drive. 
+The 
+.I Sony 
+drives have no hardware support for 
+.BR "CD-ROM XA mode 2 form 1" .
+You have to specify the 
+.B \-data 
+option in order to create multi session disks on these drives.
+As long as wodim does not have a coder for converting data sectors
+to audio sectors, you need to force 
+.B CD-ROM
+sectors by including the
+.B \-data
+option if you like to record a multisession disk in SAO mode.
+Not all drives allow multisession CDs in SAO mode.
+.TP
+.B \-msinfo
+Retrieve multi session info in a form suitable for 
+.B genisoimage
+and print it to standard output. See
+.B msifile=
+option for another version.
+.sp
+This option makes only sense with a CD that contains at least
+one closed session and is appendable (not finally closed yet). 
+Some drives create error messages if you try to get the multi 
+session info for a disk that is not suitable for this operation.
+.TP
+.BR msifile= filename
+Like 
+.B \-msinfo
+option but also stores the multi session info in a file.
+.TP
+.B \-toc
+Retrieve and print out the table of content or PMA of a CD.
+With this option, 
+.B wodim
+will work with CD-R drives and with CD-ROM drives.
+.TP
+.B \-atip
+Retrieve and print out the ATIP (absolute Time in Pre-groove) info of a CD/DVD
+recordable or CD/DVD re-writable media.
+With this option, 
+.B wodim
+will try to retrieve the ATIP info. If the actual drive does not support
+to read the ATIP info, it may be that only a reduced set of information
+records or even nothing is displayed. Only a limited number of MMC compliant
+drives support to read the ATIP info.
+.sp
+If 
+.B wodim
+is able to retrieve the lead-in start time for the first session, it will try to
+decode and print the manufacturer info from the media.
+DVD media does not have ATIP information but there is equivalent prerecorded
+information that is read out and printed.
+.TP
+.B \-fix
+The disk will only be fixated (i.e. a TOC for a CD-Reader will be written). 
+This may be used, if for some reason the disk has been written but not
+fixated. This option currently does not work with old TEAC drives (CD-R50S and
+CD-R55S).
+.TP
+.B \-nofix
+Do not fixate the disk after writing the tracks. This may be used
+to create an audio disk in steps. An un-fixated disk can usually not be used
+on a non CD-writer type drive but there are audio CD players that will
+be able to play such a disk.
+.TP
+.B \-waiti
+Wait for input to become available on standard input before trying to open
+the SCSI driver. This allows 
+.B wodim
+to read its input from a pipe even
+when writing additional sessions to a multi session disk.
+When writing another session to a multi session disk,
+.B genisoimage 
+needs to read the old session from the device before writing output.
+This cannot be done if
+.B wodim 
+opens the SCSI driver at the same time.
+.TP
+.B \-load
+Load the media and exit. This only works with a tray loading mechanism
+but seems to be useful when using the Kodak disk transporter.
+.TP
+.B \-lock
+Load the media, lock the door and exit. This only works with a tray loading mechanism
+but seems to be useful when using the Kodak disk transporter.
+.TP
+.B \-eject
+Eject disk after doing the work.
+Some devices (e.g. Philips) need to eject the medium before creating a new
+disk. Doing a \-dummy test and immediately creating a real disk would not
+work on these devices.
+.TP
+.BR speed= #
+Set the speed factor of the writing process to #.
+# is an integer, representing a multiple of the audio speed.
+This is about 150\ KB/s for CD-ROM, about 172\ KB/s for CD-Audio and about 1385\ kB/s
+for DVD media.
+If no 
+.I speed
+option is present,
+.B wodim
+will try to get a drive specific speed value from the file
+.B /etc/wodim.conf
+and if it cannot find one, it will try to get the speed value from the
+.B CDR_SPEED
+environment and later from the 
+.B CDR_SPEED=
+entry in
+.BR /etc/wodim.conf .
+If no speed value could be found, wodim uses a drive specific default speed.
+The default for all new (MMC compliant) drives is to use the maximum supported by the drive.
+If you use 
+.I "speed=0"
+with a MMC compliant drive,
+.B wodim
+will switch to the lowest possible speed for drive and medium.
+If you are using an old (non MMC) drive that has problems with
+.I "speed=2 
+or 
+.IR "speed=4" , 
+you should try 
+.IR "speed=0" .
+.TP
+.BI blank= type
+Blank a CD-RW and exit or blank a CD-RW before writing. The blanking type may be one of:
+.RS
+.TP 12
+help
+Display a list of possible blanking types.
+.TP
+all
+Blank the entire disk. This may take a long time.
+.TP
+fast
+Minimally blank the disk. This results in erasing the PMA, the TOC and the pregap.
+.TP
+track
+Blank a track.
+.TP
+unreserve
+Unreserve a reserved track.
+.TP
+trtail
+Blank the tail of a track.
+.TP
+unclose
+Unclose last session.
+.TP
+session
+Blank the last session.
+.RE
+Not all drives support all blanking types. It may be necessary to use
+.B "blank=all
+if a drive reports a specified command as being invalid.
+If used together with the 
+.B \-force
+flag, this option may be used to blank CD-RW disks that otherwise cannot be
+blanked. Note that you may need to specify
+.BI blank= all
+because some drives will not continue with certain types of bad CD-RW
+disks. Note also that
+.B wodim
+does its best if the 
+.B \-force 
+flag is used but it finally depends on the drive's firmware 
+whether the blanking operation will succeed or not.
+.TP
+.B \-format
+Format a CD-RW/DVD-RW/DVD+RW disc.
+Formatting is currently only implemented for DVD+RW media.
+A 'maiden' DVD+RW media needs to
+be formatted before you may write to it.
+However, as
+.B wodim
+autodetects the need for formatting in this case and auto formats the medium
+before it starts writing, the
+.B \-format
+option is only needed if you like to forcibly reformat a DVD+RW medium.
+.TP
+.BR fs= #
+Set the FIFO (ring buffer) size to #.
+You may use the same syntax as in 
+.BR dd (1),
+.BR sdd (1)
+or
+.BR star (1).
+The number representing the size is taken in bytes unless otherwise specified.
+If a number is followed directly by the letter `b', `k', `m', `s' or `f',
+the size is multiplied by 512, 1024, 1024*1024, 2048 or 2352.
+If the size consists of numbers separated by `x' or `*', multiplication of the 
+two numbers is performed.
+Thus 
+.I "fs=10x63k
+will specify a FIFO size of 630\ kBytes.
+.sp
+The size specified by the 
+.I fs=
+argument includes the shared memory that is needed for administration. This
+is at least one page of memory.
+If no
+.IR fs =
+option is present, 
+.B wodim
+will try to get the FIFO size value from the 
+.B CDR_FIFOSIZE
+environment.
+The default FIFO size is currently 4 MB.
+.sp
+The FIFO is used to increase buffering for the real time writing process.
+It allows to run a pipe from 
+.B genisoimage
+directly into 
+.BR wodim .
+If the FIFO is active and a pipe from 
+.B genisoimage
+into 
+.B wodim
+is used to create a CD, 
+.B wodim
+will abort prior to do any modifications on the disk if 
+.B genisoimage 
+dies before it starts writing.
+The recommended FIFO size is between 4 and 128\ MBytes.
+As a rule of thumb, the FIFO size should be at least equal to the size
+of the internal buffer of the CD/DVD-Recorder and no more than half of
+the physical amount of RAM available in the machine.
+If the FIFO size is big enough, the FIFO statistics will print a FIFO
+empty count of zero and the FIFO min fill is not below 20%.
+It is not wise to use too much space for the FIFO. If you need more
+than 8 MB to write a CD at a speed less than 20x from an image on a
+local file system on an idle machine, your machine is either underpowered,
+has hardware problems or is mis-configured.
+If you like to write DVDs or CDs at higher speed, it makes sense
+to use at least 16\ MB for the FIFO.
+.sp
+On old and small machines, you need to be more careful with the FIFO size.
+If your machine has less than 256\ MB of physical RAM, you should not
+set up a FIFO size that is more than 32\ MB.
+The sun4c architecture (e.g. a Sparcstation-2) has only MMU page table entries
+for 16\ MBytes per process. Using more than 14\ MBytes for the FIFO
+may cause the operating system in this case to spend much time to constantly
+reload the MMU tables. Newer machines from Sun do not have this MMU
+hardware problem. I have no information on PC-hardware reflecting
+this problem.
+.sp
+Old Linux systems for non x86 platforms have broken definitions for
+the shared memory size. You need to fix them and rebuild the kernel
+or manually tell
+.B wodim
+to use a smaller FIFO.
+.sp
+If you have buffer underruns or similar problems (like a constantly empty
+drive buffer) and observe a zero
+.IR "fifo empty count" ,
+you have hardware problems that prevents the data from flowing fast enough
+from the kernel memory to the drive. The FIFO size in this case is sufficient,
+but you should check for a working DMA setup.
+.TP
+.BR ts= #
+Set the maximum transfer size for a single SCSI command to #.
+The syntax for the 
+.B ts=
+option is the same as for wodim fs=# or sdd bs=#.
+.sp
+If no 
+.B ts=
+option has been specified,
+.B wodim
+defaults to a transfer size of 63\ kB. If libusal gets lower values from the
+operating system, the value is reduced to the maximum value that is possible
+with the current operating system.
+Sometimes, it may help to further reduce the transfer size or to enhance it,
+but note that it may take a long time to find a better value by experimenting
+with the
+.B ts=
+option.
+.TP
+.BI dev= target
+Sets the SCSI target for the CD/DVD-Recorder, see notes above.
+A typical device specification is
+.BI dev= 6,0
+\&.
+A filename or virtual device name can be passed instead of the symbolic SCSI
+numbers.  The correct device/filename in this case can be found in the system
+specific manuals of the target operating system.
+On a 
+.I FreeBSD
+system without 
+.I CAM
+support, you need to use the control device (e.g.
+.IR /dev/rcd0.ctl ).
+A correct device specification in this case may be
+.BI dev= /dev/rcd0.ctl:@
+\&.
+.sp
+On Linux and Windows 2000/XP, drives are accessible with their device (or
+drive) names or with the symbolic SCSI numbers (not recommended, mapping is not
+stable and could be completely removed in the future).
+.sp
+If no 
+.I dev
+option is present, 
+.B wodim
+will try to get the device from the 
+.B CDR_DEVICE
+environment.
+.sp
+If the argument to the
+.B dev=
+option does not contain the characters ',', '/', '@' or ':',
+it is interpreted as an label name that may be found in the file
+/etc/wodim.conf (see FILES section).
+.TP
+.BI gracetime= #
+Set the grace time before starting to write to
+.IR # " seconds.
+Values below 2 seconds are not recommended to give the kernel or volume
+management a chance to learn the new state.
+.TP
+.BI timeout= #
+Set the default SCSI command timeout value to 
+.IR # " seconds.
+The default SCSI command timeout is the minimum timeout used for sending
+SCSI commands.
+If a SCSI command fails due to a timeout, you may try to raise the
+default SCSI command timeout above the timeout value of the failed command.
+If the command runs correctly with a raised command timeout,
+please report the better timeout value and the corresponding command to 
+the author of the program.
+If no 
+.I timeout 
+option is present, a default timeout of 40 seconds is used.
+.TP
+.BI driver= name
+Allows the user to manually select a driver for the device.
+The reason for the existence of the
+.BI driver= name
+option is to allow users to use
+.B wodim
+with drives that are similar to supported drives but not known
+directly by
+.BR wodim .
+All drives made after 1997 should be MMC standard compliant and
+thus supported by one of the MMC drivers.
+It is most unlikely that
+.B wodim
+is unable to find the right driver automatically.
+Use this option with extreme care. If a wrong driver is used for a
+device, the possibility of creating corrupted disks is high.
+The minimum problem related to a wrong driver is that the 
+.B speed=
+or 
+.B \-dummy
+will not work.
+.br
+.RS
+.ne 8
+.PP
+The following driver names are supported:
+.TP
+.B help
+To get a list of possible drivers together with a short description.
+.TP
+.B mmc_cd
+The generic SCSI-3/mmc CD-ROM driver is auto-selected whenever
+.B wodim
+finds a MMC compliant drive that does not identify itself to support writing at
+all, or that only identifies to support media or write modes not implemented in
+.BR wodim .
+.TP
+.B mmc_cd_dvd
+The generic SCSI-3/mmc CD/DVD driver is auto-selected whenever
+.B wodim
+finds a MMC-2 or MMC-3 compliant drive that seems to support more than 
+one medium type and the tray is open or no medium could be found to select the
+right driver.
+This driver tries to close the tray, checks the medium found in the tray and then
+branches to the driver that matches the current medium.
+.TP
+.B mmc_cdr
+The generic SCSI-3/mmc CD-R/CD-RW driver is auto-selected whenever
+.B wodim
+find a MMC compliant drive that only supports to write CDs or a multi system
+drive that contains a CD as the current medium.
+.TP
+.B mmc_cdr_sony
+The generic SCSI-3/mmc CD-R/CD-RW driver is auto-selected whenever
+.B wodim
+would otherwise select the
+.B mmc_cdr
+driver but the device seems to be made by Sony.
+The
+.B mmc_cdr_sony
+is definitely needed for the Sony CDU 928 as this drive does not completely
+implement the MMC standard and some of the MMC SCSI commands have to be
+replaced by Sony proprietary commands. It seems that all Sony drives (even
+newer ones) still implement the Sony proprietary SCSI commands so it has
+not yet become a problem to use this driver for all Sony drives. If you find
+a newer Sony drive that does not work with this driver, please report.
+.TP
+.B mmc_mdvd
+The generic SCSI-3/mmc-2 DVD-R/DVD-RW driver is auto-selected whenever
+.B wodim
+finds a MMC-2 or MMC-3 compliant drive that supports to write DVDs and
+an appropriate medium is loaded.
+Note that for unknown reason, the DVD-Plus alliance does not
+like that there is a simulation mode for DVD+R and DVD+RW media nor a way 
+to erase DVD+RW media.
+DVD+R and DVD+RW only supports one write mode that is somewhere between 
+Track At Once and Packet writing; this mode is selected in 
+.B wodim
+via a the 
+.BR \-dao / \-sao
+option.
+As DVD+RW media needs to be formatted before its first use, 
+.B wodim
+auto-detects this media state and performs a format before it starts
+to write. 
+.sp
+Note: If you have any problems during burning DVDs using 
+.BR wodim , 
+please consider 
+.B growisofs 
+from package
+.BR dvd+rw-tools , 
+which often works better 
+in these cases.
+.TP
+.B cw_7501
+The driver for Matsushita/Panasonic CW-7501 is auto-selected when
+.B wodim
+finds this old pre MMC drive.
+.B wodim
+supports all write modes for this drive type.
+.TP
+.B kodak_pcd_600
+The driver for Kodak PCD-600 is auto-selected when
+.B wodim
+finds this old pre MMC drive which has been the first high speed (6x)
+CD writer for a long time. This drive behaves similar to the
+Philips CDD-521 drive.
+.TP
+.B philips_cdd521
+The driver for Philips CDD-521 is auto-selected when
+.B wodim
+finds a Philips CDD-521 drive (which is the first CD writer ever made)
+or one of the other drives that are known to behave similar to this
+drive.
+All Philips CDD-521 or similar drives (see other drivers in this list)
+do not support Session At Once recording.
+.TP
+.B philips_cdd521_old
+The driver for Philips old CDD-521 is auto-selected when
+.B wodim
+finds a Philips CDD-521 with very old firmware which has some known limitations.
+.TP
+.B philips_cdd522
+The driver for Philips CDD-522 is auto-selected when
+.B wodim
+finds a Philips CDD-522 which is the successor of the 521 or one of its variants
+with Kodak label.
+.B wodim
+does not support Session At Once recording with these drives.
+.TP
+.B philips_dumb
+The driver for Philips CDD-521 with pessimistic assumptions is never auto-selected.
+It may be used by hand with drives that behave similar to the Philips CDD-521.
+.TP
+.B pioneer_dws114x
+The driver for Pioneer DW-S114X is auto-selected when
+.B wodim
+finds one of the old non MMC CD writers from Pioneer.
+.TP
+.B plasmon_rf4100
+The driver for Plasmon RF 4100 is auto-selected when
+.B wodim
+finds this specific variant of the Philips CDD-521.
+.TP
+.B ricoh_ro1060c
+The driver for Ricoh RO-1060C is auto-selected when
+.B wodim
+finds this drive. There is no real support for this drive yet.
+.TP
+.B ricoh_ro1420c
+The driver for Ricoh RO-1420C is auto-selected when
+.B wodim
+finds a drive with this specific variant of the Philips CDD-521 command set.
+.TP
+.B scsi2_cd
+The generic SCSI-2 CD-ROM driver is auto-selected whenever
+.B wodim
+finds a pre MMC drive that does not support writing or a pre MMC writer that is
+not supported by
+.BR wodim .
+.TP
+.B sony_cdu924
+The driver for Sony CDU-924 / CDU-948 is auto-selected whenever
+.B wodim
+finds one of the old pre MMC CD writers from Sony.
+.TP
+.B teac_cdr50
+The driver for Teac CD-R50S, Teac CD-R55S, JVC XR-W2010, Pinnacle RCD-5020
+is auto-selected whenever one of the drives is found that is known to the
+non MMC command set used by TEAC and JVC.
+Note that many drives from JVC will not work because they do not correctly implement
+the documented command set and JVC has been unwilling to fix or document the
+bugs.
+There is no support for the Session At Once write mode yet.
+.TP
+.B tyuden_ew50
+The driver for Taiyo Yuden EW-50 is auto-selected when
+.B wodim
+finds a drive with this specific variant of the Philips CDD-521 command set.
+.TP
+.B yamaha_cdr100
+The driver for Yamaha CDR-100 / CDR-102 is auto-selected when
+.B wodim
+finds one of the old pre MMC CD writers from Yamaha.
+There is no support for the Session At Once write mode yet.
+.TP
+.B cdr_simul
+The simulation CD-R driver allows to run timing and speed tests
+with parameters that match the behavior of CD writers.
+.TP
+.B dvd_simul
+The simulation DVD-R driver allows to run timing and speed tests
+with parameters that match the behavior of DVD writers.
+.PP
+
+.sp
+There are two special driver entries in the list:
+.B cdr_simul
+and
+.BR dvd_simul .
+These driver entries are designed to make timing tests at any speed
+or timing tests for drives that do not support the 
+.B \-dummy
+option.
+The simulation drivers implement a drive with a buffer size of 1\ MB
+that can be changed via the 
+.B CDR_SIMUL_BUFSIZE
+environment variable.
+The simulation driver correctly simulates even a buffer underrun condition.
+If the 
+.B \-dummy 
+option is present, the simulation is not aborted in case of a buffer underrun.
+.RE
+.TP
+.BI driveropts= "option list"
+Set driver specific options. The options are specified a comma separated list.
+To get a list of valid options use 
+.BI driveropts= help
+together with the 
+.I \-checkdrive
+option.
+If you like to set driver options without running a typical
+.B wodim
+task, you need to use the
+.B \-setdropts
+option in addition, otherwise the command line parser in
+.B wodim
+will complain.
+Currently implemented driver options are:
+.RS
+.TP
+.B burnfree 
+Turn the support for Buffer Underrun Free writing on.
+This only works for drives that support Buffer Underrun Free technology, which
+is available on most drives manufactured in this millennium. 
+This may be called:
+.BR "Sanyo BURN-Proof" ,
+.BR "Ricoh Just-Link" ,
+.B "Yamaha Lossless-Link"
+or similar.
+.sp
+This option is deprecated and is mentioned here for documentation purposes
+only. The BURN-Free feature is enabled by default if the drive supports it.
+However, use of BURN-Free may cause decreased burning quality. Therefore it can
+be useful to disable it for certain purposes, eg. when creating a master copy
+for mass CD production.
+.TP
+.B noburnfree 
+Turn the support for Buffer Underrun Free writing off.
+.TP
+.BI varirec= value
+Turn on the 
+.B "Plextor VariRec"
+writing mode. The mandatory parameter
+.I value
+is the laser power offset and currently may be selected from
+-2, -1, 0, 1, 2.
+In addition, you need to set the write speed to 4 in order to allow
+.B "VariRec"
+to work.
+.TP
+.BI gigarec= value
+Manage the
+.B "Plextor GigaRec"
+writing mode. The mandatory parameter
+.I value
+is the disk capacity ratio compared to normal recording and currently may be selected from
+0.6, 0.7, 0.8, 1.0, 1.2, 1.3, 1.4.
+If values < 1.0 are used, then the effect is similar to the
+.B "Yamaha Audio Master Q. R."
+feature. If values > 1.0 are used, then the disk capacity is 
+increased.
+.sp
+Not all drives support all 
+.B GigaRec
+values.
+When a drive uses the 
+.B GigaRec
+feature, the write speed is limited to 8x.
+.TP
+.B audiomaster
+Turn on the 
+.B "Yamaha Audio Master Q. R."
+feature which usually should result in high quality CDs that
+have less reading problems in Hi-Fi players.
+As this is implemented as a variant of the 
+Session at Once write mode, it will only work if you select 
+SAO write mode and there is no need to turn it off.
+The 
+.B "Audio Master"
+mode will work with a limited speed but
+may also be used with data CDs. In
+.B "Audio Master"
+mode, the pits on the CD will be written larger then usual so the capacity
+of the medium is reduced when turning this feature on.
+A 74 minute CD will only have a capacity of 63 minutes if
+.B "Audio Master"
+is active and the capacity of a 80 minute CD will be reduced to 68 minutes.
+.TP
+.B forcespeed
+Normally, modern drives know the highest possible speed for different
+media and may reduce the speed in order to grant best write quality.
+This technology may be called:
+.BR "Plextor PowerRec" ,
+.BR "Ricoh Just-Speed" ,
+.B "Yamaha Optimum Write Speed Control"
+or similar.
+Some drives (e.g. Plextor, Ricoh and Yamaha) allow to force the drive to
+use the selected speed even if the medium is so bad that the
+write quality would be poor. This option tells such a drive to
+force to use the selected speed regardless of the medium quality.
+.sp
+Use this option with extreme care and note that the drive should know better
+which medium will work at full speed.
+The default is to turn 
+.B forcespeed
+off, regardless of the defaults of the drive.
+.TP
+.B noforcespeed
+Turn off the 
+.B "force speed
+feature.
+.TP
+.B speedread
+Some ultra high speed drives such as 48x and faster drives from Plextor
+limit the read speed for unknown media to e.g. 40x in order to avoid
+damaged disks and drives.
+Using this option tells the drive to read any media as fast as possible.
+Be very careful as this may cause the media to break in the drive 
+while reading, resulting in a damaged media and drive! 
+.TP
+.B nospeedread
+Turn off unlimited read speed.
+.TP
+.B singlesession
+Turn the drive into a single session only drive.
+This allows to read defective or non-compliant (illegal) media with extremely
+non-standard additional (broken/illegal) TOC entries in the TOC from the second
+or higher session. Some of these disks become
+usable if only the information from the first session is used.
+You need to enable Single Session mode before you insert the defective disk!
+.TP
+.B nosinglesession
+Turn off single session mode. The drive will again behave as usual.
+.TP
+.B hidecdr
+Hide the fact that a medium might be a recordable medium.
+This allows to make CD-Rs look like CD-ROMs and applications believe 
+that the media in the drive is not a CD-R. 
+.TP
+.B nohidecdr
+Turn off hiding CD-R media.
+.TP
+.B tattooinfo
+Use this option together with
+.B \-checkdrive
+to retrieve the image size information for the
+.B "Yamaha DiskT@2
+feature. The images always have a line length of 3744 pixel.
+Line number 0 (radius 0) is mapped to the center of the disk.
+If you know the inner and outer radius you will be able to create a
+pre distorted image that later may appear undistorted on the disk.
+.TP
+.BI tattoofile= name
+Use this option together with
+.B \-checkdrive
+to write an image prepared for the
+.B "Yamaha DiskT@2
+feature to the medium.
+The file must be a file with raw image B&W data (one byte per pixel) 
+in a size as retrieved by a previous call to
+.BI tattoofile= name
+\&.
+If the size of the image equals the maximum possible size
+(3744 x 320 pixel), 
+.B wodim
+will use the first part of the file. This first part then will 
+be written to the leftover space on the CD.
+.sp
+Note that the image must be mirrored to be readable from the pick up
+side of the CD.
+.RE
+.TP
+.B \-setdropts
+Set the driveropts specified by
+.BI driveropts= "option list" ,
+the 
+.B speed
+of the drive and the 
+.B dummy
+flag and exit.
+This allows wodim to set drive specific parameters that are not directly 
+used by
+.B wodim
+like e.g.
+.BR "single session mode" ", " "hide cdr"
+and similar.
+It is needed in case that 
+.BI driveropts= "option list"
+should be called without planning to run a typical
+.B wodim
+task.
+.TP
+.B \-checkdrive
+Checks if a driver for the current drive is present and exit.
+If the drive is a known drive, 
+.B wodim
+uses exit code 0.
+.TP
+.B \-prcap
+Print the drive capabilities for SCSI-3/mmc compliant drives
+as obtained from mode page 0x2A. Values marked with 
+.I kB
+use 1000 bytes as kilo-byte, values marked with
+.I KB
+use 1024 bytes as Kilo-byte.
+.TP
+.B \-inq
+Do an inquiry for the drive, print the inquiry info and exit.
+.TP
+.B \-scanbus
+Scan all SCSI devices on all SCSI busses and print the inquiry
+strings. This option may be used to find SCSI address of the 
+CD/DVD-Recorder on a system. If some device types are invisible, try using
+.B dev=ATA:
+or similar option to give a hint about the device type you are looking for.
+The numbers printed out as labels are computed by: 
+.B "bus * 100 + target.
+On platforms and device systems without persistent SCSI number management the
+results are not reliable. Use the .B \-\-devices option instead.
+.TP
+.B \-\-devices
+Look for useable devices using the system specific functions, eg. probing with
+usual device nodes in /dev/*, and display the detections using symbolic device
+names in OS specific syntax.
+.TP
+.B \-reset
+Try to reset the SCSI bus where the CD recorder is located. This works not
+on all operating systems.
+.TP
+.B \-abort
+Try to send an 
+.B abort
+sequence to the drive.
+If you use 
+.B wodim
+only, this should never be needed; but other software may leave a drive 
+in an unusable condition.
+Calling
+.B "wodim \-reset
+may be needed if a previous write has been interrupted and the software did 
+not tell the drive that it will not continue to write.
+.TP
+.B \-overburn
+Allow 
+.B wodim 
+to write more than the official size of a medium. This feature is usually
+called 
+.I overburning
+and depends on the fact that most blank media may hold more space than the
+official size. As the official size of the lead-out area on the disk is
+90 seconds (6750 sectors) and a disk usually works if there are at least
+150 sectors of lead out, all media may be overburned by at least 88 seconds
+(6600 sectors).
+Most CD recorders only do overburning in 
+.B SAO
+or
+.B RAW
+mode. Known exceptions are TEAC CD-R50S, TEAC CD-R55S and the Panasonic
+CW-7502.
+Some drives do not allow to overburn as much as you might like and limit
+the size of a CD to e.g. 76 minutes. This problem may be circumvented by
+writing the CD in RAW mode because this way the drive has no chance to find
+the size before starting to burn.
+There is no guarantee that your drive supports overburning at all.
+Make a test to check if your drive implements the feature.
+.TP
+.B \-ignsize
+Ignore the known size of the medium. This option should be used with extreme
+care, it exists only for debugging purposes don't use it for other reasons.
+It is not needed to write disks with more than the nominal capacity.
+This option implies
+.BR \-overburn .
+.TP
+.B \-useinfo
+Use
+.B "*.inf
+files to overwrite audio options.
+If this option is used, the pregap size information is read from 
+the
+.B "*.inf
+file that is associated with the file that contains the audio
+data for a track.
+.sp
+If used together with the
+.B \-audio
+option,
+.B wodim
+may be used to write audio CDs from a pipe from
+.B icedax
+if you call
+.B wodim
+with the
+.B *.inf
+files as track parameter list instead of using audio files.
+The audio data is read from 
+.B stdin
+in this case.
+See
+.B EXAMPLES
+section below.
+.B wodim
+first verifies that 
+.B stdin
+is not connected to a terminal and runs some heuristic consistency checks
+on the
+.B *.inf
+files and then sets the track lengths from the information in
+the
+.B *.inf
+files.
+.sp
+If you like to write from 
+.BR stdin ,
+make sure that wodim is called with a large enough FIFO size, reduce the write
+speed to a value below the read speed of the source drive and switch the burn-free
+option for the recording drive on.
+.TP
+.BR defpregap= #
+Set the default pre-gap size for all tracks except track number 1.
+This option currently only makes sense with the TEAC drive when
+creating track-at-once disks without the 2 second silence before each track.
+.br
+This option may go away in future. 
+.TP
+.B \-packet
+Set 
+.B "Packet writing mode. 
+This is an experimental interface.
+.TP
+.BR pktsize= #
+Set the packet size to #, forces fixed packet mode.
+This is an experimental interface.
+.TP
+.B \-noclose
+Do not close the current track, useful only when in packet writing mode.
+This is an experimental interface.
+.TP
+.BI mcn= med_cat_nr
+Set the 
+.B "Media Catalog Number
+of the CD to 
+.IR med_cat_nr .
+.TP
+.B \-text
+Write CD-Text information
+based on information taken from a file that contains ascii information
+for the text strings. 
+.B wodim
+supports CD-Text information based on the content of the
+.B *.inf
+files created by 
+.B icedax 
+and CD-Text information based on the content from a
+.B "CUE sheet
+file.
+If a 
+.B "CUE sheet
+file contains both (binary CDTEXTFILE and text based SONGWRITER)
+entries, then the information based on the CDTEXTFILE entry will win.
+.sp
+You need to use the
+.B \-useinfo
+option in addition in order to tell 
+.B wodim
+to read the
+.B "*.inf
+files or
+.BI cuefile= filename
+in order to tell
+.B wodim
+to read a
+.B CUE sheet
+file in addition.
+If you like to write your own CD-Text information,
+edit the
+.B *.inf
+files or the
+.B "CUE sheet
+file with a text editor and change the fields
+that are relevant for CD-Text.
+.TP
+.BI textfile= filename
+Write CD-Text based on information found in the binary file
+.IR filename .
+This file must contain information in a data format defined in the
+SCSI-3 MMC-2 standard and in the Red Book. The four byte size header that is 
+defined in the SCSI standard is optional and allows to make the recognition of
+correct data less ambiguous.
+This is the best option to be used to copy CD-Text data from existing CDs
+that already carry CD-Text information. To get data in a format suitable
+for this option use 
+.B wodim \-vv \-toc
+to extract the information from disk.
+If both, 
+.BI textfile= filename
+and CD-Text information from
+.B *.inf
+or
+.B *.cue
+files are present,
+.BI textfile= filename
+will overwrite the other information.
+.TP
+.BI cuefile= filename
+Take all recording related information from a CDRWIN compliant
+.B "CUE sheet
+file.
+No track files are allowed when this option is present and the option
+.B \-dao
+is currently needed in addition.
+
+.SH "TRACK OPTIONS
+.PP
+Track options may be mixed with track file names.
+.TP
+.BI isrc= ISRC_number
+Set the 
+.B "International Standard Recording Number
+for the next track to
+.IR ISRC_number .
+.TP
+.BI index= list
+Sets an index list for the next track.
+In index list is a comma separated list of numbers that are counting
+from index 1. The first entry in this list must contain a 0, the following 
+numbers must be an ascending list of numbers (counting in 1/75 seconds) that 
+represent the start of the indices. An index list in the form:
+0,7500,15000 sets index 1 to the start of the track, index 2 100 seconds from
+the start of the track and index 3 200 seconds from the start of the track.
+.TP
+.B \-audio
+If this flag is present, all subsequent tracks are written in
+.B "CD-DA 
+(similar to Red Book) audio format.
+The file with data for this tracks should
+contain stereo, 16-bit digital audio with 44100 samples/s.
+The byte order should be the following: MSB left, LSB left, 
+MSB right, LSB right, MSB left and so on. The track should be a multiple of 
+2352 bytes. It is not possible to put the master image of an audio track 
+on a raw disk because 
+data will be read in multiple of 2352 bytes during the recording process.
+.sp
+If a filename ends in 
+.I .au
+or
+.I .wav
+the file is considered to be a structured audio data file.
+.B wodim
+assumes that the file in this case is a Sun audio file or a
+Microsoft .WAV file
+and extracts the audio data from the files by skipping over the
+non-audio header information.
+In all other cases, wodim will only work correctly if the
+audio data stream does not have any header.
+Because many structured audio files do not have an integral
+number of blocks (1/75th second) in length,
+it is often necessary to specify the
+.B \-pad
+option as well.
+.B wodim
+recognizes that audio data in a .WAV file is stored in Intel
+(little-endian) byte order, and will automatically byte-swap the data
+if the CD recorder requires big-endian data.  
+.B wodim
+will reject any audio file that does not match the Red Book requirements
+of 16-bit stereo samples in PCM coding at 44100 samples/second.
+.sp
+Using other structured audio data formats as input to 
+.B wodim
+will usually work if the structure of the data is the 
+structure described above (raw pcm data in big-endian byte order).
+However, if the data format includes a header,
+you will hear a click at the start of a track.
+.TP
+.I " "
+If neither 
+.I \-data 
+nor
+.I \-audio
+have been specified, 
+.B wodim
+defaults to 
+.I \-audio
+for all filenames that end in
+.I .au
+or 
+.I .wav
+and to
+.I \-data 
+for all other files.
+.TP
+.B \-swab
+If this flag is present, audio data is assumed to be in byte-swapped
+(little-endian) order.  Some types of CD-Writers e.g. Yamaha, Sony and the
+new SCSI-3/mmc drives require audio data to be presented in
+little-endian order,
+.\" (which is the order in which it's actually recorded on the CD) ????
+while other writers require audio data to be
+presented in the big-endian (network) byte order normally used by the
+SCSI protocol.
+.B wodim
+knows if a CD-Recorder needs audio data in big- or little-endian order,
+and corrects the byte order of the data stream to match the needs
+of the recorder.
+You only need the 
+.I \-swab 
+flag if your data stream is in Intel (little-endian) byte order.
+.sp
+Note that the verbose output of
+.B wodim
+will show you if swapping is necessary to make the byte order of 
+the input data fit the required byte order of the recorder.
+.B wodim
+will not show you if the 
+.I \-swab 
+flag was actually present for a track.
+.TP
+.B \-data
+If this flag is present, all subsequent tracks are written in
+.B "CD-ROM mode 1
+(Yellow Book) format. The data size is a multiple of 2048 bytes.
+The file with track data should contain an 
+.BR ISO-9660 " or " "Rock Ridge
+filesystem image (see 
+.B genisoimage
+for more details). If the track data is an
+.B ufs
+filesystem image, fragment size should be set to 2\ KB or more to allow
+CD-drives with 2\ KB sector size to be used for reading.
+.TP
+.I " "
+.I \-data
+is the default, if no other flag is present and the file does not
+appear to be of one of the well known audio file types.
+.TP
+.I " "
+If neither 
+.I \-data 
+nor
+.I \-audio
+have been specified, 
+.B wodim
+defaults to 
+.I \-audio
+for all filenames that end in
+.I .au
+or 
+.I .wav
+and to
+.I \-data 
+for all other files.
+.TP
+.B \-mode2
+If this flag is present, all subsequent tracks are written in
+.B "CD-ROM mode 2
+format. The data size is a multiple of 2336 bytes.
+.TP
+.B \-xa
+If this flag is present, all subsequent tracks are written in
+.B "CD-ROM XA mode 2 form 1
+format. The data size is a multiple of 2048 bytes.
+The XA sector sub headers will be created by the drive.
+With this option, the write mode is the same as with the
+.B \-multi
+option.
+.TP
+.B \-xa1
+If this flag is present, all subsequent tracks are written in
+.B "CD-ROM XA mode 2 form 1
+format. The data size is a multiple of 2056 bytes.
+The XA sector sub headers are part of the user data and have to be
+supplied by the application that prepares the data to be written.
+.TP
+.B \-xa2
+If this flag is present, all subsequent tracks are written in
+.B "CD-ROM XA mode 2 form 2
+format. The data is a multiple of 2324 bytes.
+The XA sector sub headers will be created by the drive.
+.TP
+.B \-xamix
+If this flag is present, all subsequent tracks are written in a way
+that allows a mix of 
+.B "CD-ROM XA mode 2 form 1/2
+format. The data size is a multiple of 2332 bytes.
+The XA sector sub headers are part of the user data and have to be
+supplied by the application that prepares the data to be written.
+The CRC and the P/Q parity ECC/EDC information (depending on the sector
+type) have to be supplied by the application that prepares the data to be written.
+.TP
+.B \-cdi
+If this flag is present, the TOC type for the disk is set to
+.BR CDI .
+This only makes sense with XA disks.
+.TP
+.B \-isosize
+Use the 
+.B "ISO-9660
+file system size as the size of the next track.
+This option is needed if you want 
+.B wodim
+to directly read the image of a track from
+a raw disk partition or from a 
+.I TAO 
+master CD. In the first case the option
+.B \-isosize
+is needed to limit the size of the CD to the size of the ISO filesystem.
+In the second case the option
+.B \-isosize
+is needed to prevent 
+.B wodim
+from reading the two run out blocks that are appended by each CD-recorder
+in track at once mode. These two run out blocks cannot be read and would
+cause a buffer underrun that would cause a defective copy.
+Do not use this option on files created by 
+.B genisoimage
+and in case
+.B wodim
+reads the track data from 
+.IR stdin .
+In the first case, you would prevent 
+.B wodim 
+from writing the amount of padding that has been appended by
+.B genisoimage
+and in the latter case, it will not work because 
+.I stdin
+is not seekable.
+.sp
+If 
+.B \-isosize
+is used for a track, 
+.B wodim
+will automatically add padding for this track as if the
+.B \-pad
+option has been used but the amount of padding may be less than the padding
+written by 
+.BR  genisoimage .
+Note that if you use
+.B \-isosize
+on a track that contains Sparc boot information, the boot information will
+be lost.
+.sp
+Note also that
+this option cannot be used to determine the size of a file system
+if the multi session option is present.
+.TP
+.B \-pad
+If the track is a data track, 15 sectors of zeroed data
+will be added to the end of this and each subsequent data track.
+In this case, the 
+.B \-pad 
+option is superseded by the 
+.B padsize=
+option. It will remain however as a shorthand for
+.BI padsize= 15s.
+If the 
+.I \-pad 
+option refers to an audio track,
+.B wodim 
+will pad the audio data to be a multiple of 2352 bytes. 
+The audio data padding is done with binary zeroes which is 
+equal to absolute silence.
+.sp
+.B \-pad 
+remains valid until disabled by 
+.BR \-nopad .
+.TP
+.BR padsize= #
+Set the amount of data to be appended as padding to the next track to #.
+Opposed to the behavior of the 
+.B \-pad
+option, the value for 
+.I padsize=
+is reset to zero for each new track.
+wodim assumes a sector size of 2048 bytes for the
+.I padsize=
+option, independent from the real 
+sector size and independent from the write mode.
+The megabytes mentioned in the verbose mode output however are counting
+the output sector size which is e.g. 2448 bytes when writing in RAW/RAW96
+mode.
+See
+.BR fs =
+option for possible arguments.
+To pad the equivalent of 20 minutes on a CD, you may write
+.BR padsize= 20x60x75s.
+Use this option if your CD-drive is not able to read the last sectors of
+a track or if you want to be able to read the CD
+on a 
+.B Linux 
+system with the ISO-9660 filesystem read ahead bug.
+If an empty file is used for track data, 
+this option may be used to create a disk that is entirely made of padding.
+This may e.g. be used to find out how much overburning is possible with a 
+specific media.
+.TP
+.B \-nopad
+Do not pad the following tracks \- the default.
+.TP
+.B \-shorttrack
+Allow all subsequent tracks to violate the Red Book track length standard
+which requires a minimum track length of 4 seconds.
+This option is only useful when used in SAO or RAW mode.
+Not all drives support this feature. The drive must accept the
+resulting CUE sheet or support RAW writing.
+.TP
+.B \-noshorttrack
+Re-enforce the Red Book track length standard. Tracks must be
+at least 4 seconds.
+.TP
+.BR pregap= #
+Set the  pre-gap size for the next track.
+This option currently only makes sense with the TEAC drive when
+creating track-at-once disks without the 2 second silence before each track.
+.br
+This option may go away in future. 
+.TP
+.B \-preemp
+If this flag is present, all TOC entries for subsequent audio tracks 
+will indicate that the audio data has been sampled with 50/15 \*msec
+pre-emphasis.
+The data, however is not modified during the process of transferring from file
+to disk. 
+This option has no effect on data tracks.
+.TP
+.B \-nopreemp
+If this flag is present, all TOC entries for subsequent audio tracks 
+will indicate that the audio data has been mastered with linear data \- 
+this is the default.
+.TP
+.B \-copy
+If this flag is present, all TOC entries for subsequent audio tracks
+of the resulting CD
+will indicate that the audio data has permission to be copied without limit.
+This option has no effect on data tracks.
+.TP
+.B \-nocopy
+If this flag is present, all TOC entries for subsequent audio tracks 
+of the resulting CD
+will indicate that the audio data has permission to be copied only once for
+personal use \-
+this is the default.
+.TP
+.B \-scms
+If this flag is present, all TOC entries for subsequent audio tracks 
+of the resulting CD
+will indicate that the audio data has no permission to be copied anymore.
+.TP
+.BR tsize= #
+If the master image for the next track has been stored on a raw disk, 
+use this option
+to specify the valid amount of data on this disk. If the image of the next 
+track is stored in a regular file, the size of that file is taken to determine
+the length of this track.
+If the track contains an ISO 9660 filesystem image use the 
+.I \-isosize
+option to determine the length of that filesystem image.
+.br
+In Disk at Once mode and with some drives that use
+the TEAC programming interface, even in Track at Once mode,
+.B wodim
+needs to know the size of each track before starting to write the disk.
+wodim now checks this and aborts before starting to write.
+If this happens you will need to run
+.B "genisoimage -print-size
+before and use the output (with `s' appended) as an argument to the 
+.BR tsize =
+option of 
+.B wodim
+(e.g. tsize=250000s).
+.br
+See
+.BR fs =
+option for possible arguments.
+
+.SH EXAMPLES
+.PP
+For all examples below, it will be assumed that the CD/DVD-Recorder is
+connected to the primary SCSI bus of the machine. The SCSI target id is
+set to 2.
+.PP
+To record a pure CD-ROM at double speed, using data from the file
+.IR cdimage.raw :
+.PP
+    wodim \-v speed=2 dev=2,0 cdimage.raw
+.PP
+To create an image for a ISO 9660 filesystem with Rock Ridge extensions:
+.PP
+    genisoimage \-R \-o cdimage.raw /home/joerg/master/tree
+.PP
+To check the resulting file before writing to CD on Solaris:
+.PP
+    mount \-r \-F fbk \-o type=hsfs /dev/fbk0:cdimage.raw /mnt
+.PP
+On Linux:
+.PP
+    mount cdimage.raw \-r \-t iso9660 \-o loop /mnt
+.PP
+Go on with:
+.br
+    ls \-lR /mnt
+.br
+    umount /mnt
+.PP
+If the overall speed of the system is sufficient and the structure of
+the filesystem is not too complex, wodim will run without creating an
+image of the ISO 9660 filesystem. Simply run the pipeline:
+.PP
+    genisoimage \-R /master/tree | wodim \-v fs=6m speed=2 dev=2,0 -
+.PP
+The recommended minimum FIFO size for running this pipeline is 4 MBytes.
+As the default FIFO size is 4 MB, the 
+.B fs=
+option needs only be present if you want to use a different FIFO size.
+If your system is loaded, you should run genisoimage in the real time class too.
+To raise the priority of 
+.B genisoimage
+replace the command
+.PP
+    genisoimage \-R /master/tree
+.br
+by
+.br
+    priocntl \-e \-c RT \-p 59 genisoimage \-R /master/tree
+.sp
+on Solaris and by
+.sp
+    nice --18 genisoimage \-R /master/tree
+.sp
+on systems that don't have
+.B "UNIX International
+compliant real-time scheduling.
+.PP
+wodim runs at priority 59 on Solaris, you should run genisoimage
+at no more than priority 58. On other systems, you should run genisoimage
+at no less than nice --18.
+.PP
+Creating a CD-ROM without file system image on disk has been tested
+on a Sparcstation-2 with a Yamaha CDR-400. It did work up to quad speed
+when the machine was not loaded.
+A faster machine may be able to handle quad speed also in the loaded case.
+.PP
+To record a pure CD-DA (audio) at single speed, with each track contained
+in a file named
+.IR track01.cdaudio ,
+.IR track02.cdaudio ,
+etc:
+.PP
+    wodim \-v speed=1 dev=/dev/cdrw -audio track*.cdaudio
+.PP
+To check if it will be ok to use double speed for the example above. 
+Use the dummy write option:
+.PP
+    wodim \-v \-dummy speed=2 dev=/dev/cdrw \-audio track*.cdaudio
+.PP
+To record a mixed-mode CD with an ISO 9660 filesystem from
+.I cdimage.raw
+on the first track, the other tracks being audio tracks from the files
+.IR track01.cdaudio ,
+.IR track02.cdaudio ,
+etc:
+.PP
+    wodim \-v dev=2,0 cdimage.raw \-audio track*.cdaudio
+.PP
+To handle drives that need to know the size of a track before starting to write,
+first run
+.PP
+    genisoimage -R -q -print-size /master/tree
+.PP
+and then run
+.PP
+    genisoimage -R /master/tree | wodim speed=2 dev=2,0 tsize=XXXs -
+.PP
+where 
+.I XXX
+is replaced by the output of the previous run of genisoimage.
+.PP
+To copy an audio CD in the most accurate way, first run
+.PP
+    icedax dev=/dev/cdrom \-vall cddb=0 -B \-Owav
+.PP
+and then run
+.PP
+    wodim dev=/dev/cdrw \-v \-dao \-useinfo \-text  *.wav
+.PP
+This will try to copy track indices and to read CD-Text information from disk.
+If there is no CD-Text information, 
+.B icedax
+will try to get the information from freedb.org instead.
+.PP
+To copy an audio CD from a pipe (without intermediate files), first run
+.PP
+    icedax dev=1,0 \-vall cddb=0 \-info-only
+.PP
+and then run
+.PP
+    icedax dev=1,0 \-no-infofile \-B \-Oraw \- | \\
+.br
+    wodim dev=2,0 \-v \-dao \-audio \-useinfo \-text *.inf
+.PP
+This will get all information (including track size info) from the
+.B *.inf
+files and then read the audio data from stdin.
+.sp
+If you like to write from 
+.BR stdin ,
+make sure that wodim is called with a large enough FIFO size (e.g.
+.BR fs=128m ),
+reduce the write speed to a value below the read speed of the source drive
+(e.g.
+.BR speed=12 ),
+and get a CD/DVD drive with BURN-Free feature if it is not available yet.
+.PP
+To set drive options without writing a CD (e.g. to switch a drive
+to single session mode), run
+.PP
+    wodim dev=1,0 \-setdropts driveropts=singlesession
+.PP
+If you like to do this when no CD is in the drive, call
+.PP
+    wodim dev=1,0 \-force \-setdropts driveropts=singlesession
+.PP
+To copy a CD in clone mode, first read the master CD using:
+.PP
+    readom dev=b,t,l \-clone f=somefile
+.PP
+or (in case the CD contains many sectors that are unreadable by intention)
+by calling:
+.PP
+    readom dev=1,0 -clone -nocorr f=somefile
+.PP
+will create the files
+.I somefile
+and
+.IR somefile.toc .
+Then write the CD using:
+.PP
+    wodim dev=1,0 -raw96r -clone -v somefile
+
+
+.SH ENVIRONMENT
+.TP
+.B CDR_DEVICE
+This may either hold a device identifier that is suitable to the open
+call of the SCSI transport library or a label in the file /etc/wodim.conf.
+.TP
+.B CDR_SPEED
+Sets the default speed value for writing (see also 
+.B speed=
+option).
+.TP
+.B CDR_FIFOSIZE
+Sets the default size of the FIFO (see also 
+.BR fs= #
+option).
+.TP
+.B CDR_FORCERAWSPEED
+If this environment variable is set, 
+.B wodim
+will allow you to write at the full RAW encoding speed a single CPU supports.
+This will create high potential of buffer underruns. Use with care.
+.TP
+.B CDR_FORCESPEED
+If this environment variable is set, 
+.B wodim
+will allow you to write at the full DMA speed the system supports.
+There is no DMA reserve for reading the data that is to be written from disk.
+This will create high potential of buffer underruns. Use with care.
+.TP
+.B RSH
+If the 
+.B RSH
+environment is present, the remote connection will not be created via
+.BR rcmd (3)
+but by calling the program pointed to by
+.BR RSH .
+Use e.g. 
+.BR RSH= /usr/bin/ssh
+to create a secure shell connection.
+.sp
+Note that this forces 
+.B wodim
+to create a pipe to the 
+.B rsh(1)
+program and disallows
+.B wodim
+to directly access the network socket to the remote server.
+This makes it impossible to set up performance parameters and slows down
+the connection compared to a 
+.B root
+initiated
+.B rcmd(3)
+connection.
+.TP
+.B RSCSI
+If the 
+.B RSCSI
+environment is present, the remote SCSI server will not be the program
+.B /opt/schily/sbin/rscsi
+but the program pointed to by
+.BR RSCSI .
+Note that the remote SCSI server program name will be ignored if you log in
+using an account that has been created with a remote SCSI server program as
+login shell.
+
+.SH FILES
+.TP
+/etc/wodim.conf
+Default values can be set for the following options in /etc/wodim.conf.
+For example:
+.SM CDR_FIFOSIZE=8m
+or
+.SM CDR_SPEED=2
+.RS
+.TP
+CDR_DEVICE
+This may either hold a device identifier that is suitable to the open
+call of the SCSI transport library or a label in the file /etc/wodim.conf 
+that allows to identify a specific drive on the system.
+.TP
+CDR_SPEED
+Sets the default speed value for writing (see also 
+.B speed=
+option).
+.TP
+CDR_FIFOSIZE
+Sets the default size of the FIFO (see also 
+.BR fs= #
+option).
+.TP
+CDR_MAXFIFOSIZE
+Sets the maximum size of the FIFO (see also 
+.BR fs= #
+option).
+.TP
+Any other keyword (label) is an identifier (symbolic name) for a specific drive
+on the system.  Such an identifier may not contain the characters ',', '/', '@'
+or ':'.
+.sp
+Each line that follows a label contains a whitespace separated list of items.
+Currently, four items are recognized: the drive's target specification, the
+default speed that should be used for this drive, the default FIFO size
+that should be used for this drive and drive specific options. The values for 
+.I speed
+and
+.I fifosize
+may be set to -1 to tell wodim to use the global defaults.
+.I target
+can be -1 to use the auto-guessing of the drive (see above).
+
+The value for driveropts may be omitted or set to "" if no driveropts are used.
+A typical line may look this way:
+.sp
+plex760= 0,5,0	12	50m	varirec=1
+.sp
+pioneer= /dev/hdd	-1	-1
+.sp
+This tells
+.B wodim
+that a drive named
+.I plex760
+is at scsibus 0, target 5, lun 0 and should be used with speed 12 and
+a FIFO size of 50 MB. It also uses some device specific parameter.
+A second drive may is accessible via the device file /dev/hdd and uses the
+default speed and the default FIFO size.
+.RE
+
+.SH SEE ALSO
+.BR icedax (1),
+.BR readom (1),
+.BR genisoimage (1),
+.BR ssh (1).
+
+.SH NOTES
+.PP
+On Solaris you need to stop the volume management if you like to use the USCSI
+fallback SCSI transport code. Even things like 
+.B "wodim -scanbus
+will not work if the volume management is running.
+.PP
+Disks made in 
+.B "Track At Once 
+mode are not suitable as a master for direct mass production by CD manufacturers.
+You will need the 
+.B "disk at once
+option to record such disks.
+Nevertheless the disks made in
+.B "Track At Once 
+will normally be read in all CD players. Some old
+audio CD players however may produce a two second click between two audio tracks.
+.PP
+The minimal size of a track is 4 seconds or 300 sectors. If you write 
+smaller tracks, the CD-Recorder will add dummy blocks. This is not an
+error, even though the SCSI-error message looks this way.
+.PP
+The Yamaha CDR-400 and all new SCSI-3/mmc conforming drives are supported
+in single and multi-session.
+.PP
+You should run several tests in all supported speeds of your drive with the
+.B \-dummy
+option turned on if you are using 
+.B wodim
+on an unknown system. Writing a CD is a real-time process. 
+.B NFS, CIFS
+and other network file systems
+won't always deliver constantly the needed data rates.
+If you want to use 
+.B wodim 
+with CD-images that are located on a
+.B NFS
+mounted filesystem, be sure that the FIFO size is big enough.
+If you want to make sure that buffer underruns are not
+caused by your source disk, you may use the command
+.PP
+.B "    wodim -dummy dev=2,0 padsize=600m /dev/null
+.PP
+to create a disk that is entirely made of dummy data.
+.PP
+There are also cases where you either need to be root or install
+.B wodim 
+executable with suid-root permissions. First, if you are using a device
+manufactured before 1999 which requires a non-MMC driver, you should run
+.B wodim
+in dummy mode before writing data. If you find a problem doing this, please
+report it to the
+.B cdrkit
+maintainers (see below).
+.PP
+Second, certain functionality may be unusable because of Linux's SCSI
+command filtering. When using
+.B wodim
+for anything except of pure data writing, you should also test the process in
+dummy mode and report trouble to the contact address below.
+.PP
+If you still want to run
+.B wodim
+with root permissions, you can set the permissions of the executable to
+suid-root. See the additional notes of your system/program distribution or
+README.suidroot which is part of the cdrkit source.
+.PP
+You should not connect old drives that do not support
+disconnect/reconnect to either the SCSI bus that is connected to the
+CD-Recorder or the source disk.
+.PP
+A Compact Disc can have no more than 99 tracks.
+.PP
+When creating a disc with both audio and data tracks, 
+the data should be on track 1 otherwise you should create
+a CDplus disk which is a multi session disk with the first session 
+containing the audio tracks and the following session containing the data track.
+.PP
+Many operating systems are not able to read more than a single data track, or
+need special software to do so.
+.PP
+If you have more information or SCSI command manuals for currently 
+unsupported CD/DVD/BR/HD-DVD-Recorders, please contact the
+.B cdrkit
+maintainers (see below).
+.PP
+Many CD recorders have bugs and often require a firmware update to work
+correctly. If you experience problems which cannot be solved or explained by the
+notes above, please look for instructions on the homepage of the particular
+manufacturer.
+.PP
+Some bugs will force you to power cycle the device or to reboot the machine.
+.PP
+The FIFO percent output is computed just after a block of data has been written
+to the CD/DVD-Recorder. For this reason, there will never be 100% FIFO fill ratio
+while the FIFO is in streaming mode.
+
+.SH DIAGNOSTICS
+.PP
+You have 4 seconds to abort
+.B wodim
+start after you see the message:
+.PP
+Starting to write CD at speed %d in %s mode for %s session.
+In most shells you can do that by pressing Ctrl-C.
+.PP
+A typical error message for a SCSI command looks like:
+.sp
+.RS
+.nf
+wodim: I/O error. test unit ready: scsi sendcmd: no error
+CDB:  00 20 00 00 00 00
+status: 0x2 (CHECK CONDITION)
+Sense Bytes: 70 00 05 00 00 00 00 0A 00 00 00 00 25 00 00 00 00 00
+Sense Key: 0x5 Illegal Request, Segment 0
+Sense Code: 0x25 Qual 0x00 (logical unit not supported) Fru 0x0
+Sense flags: Blk 0 (not valid)
+cmd finished after 0.002s timeout 40s
+.fi
+.RE
+.sp
+The first line gives information about the transport of the command.
+The text after the first colon gives the error text for the system call
+from the view of the kernel. It usually is:
+.B "I/O error
+unless other problems happen. The next words contain a short description for
+the SCSI command that fails. The rest of the line tells you if there were
+any problems for the transport of the command over the SCSI bus.
+.B "fatal error
+means that it was not possible to transport the command (i.e. no device present
+at the requested SCSI address).
+.PP
+The second line prints the SCSI command descriptor block for the failed command.
+.PP
+The third line gives information on the SCSI status code returned by the 
+command, if the transport of the command succeeds. 
+This is error information from the SCSI device.
+.PP
+The fourth line is a hex dump of the auto request sense information for the 
+command.
+.PP
+The fifth line is the error text for the sense key if available, followed
+by the segment number that is only valid if the command was a
+.I copy
+command. If the error message is not directly related to the current command,
+the text
+.I deferred error
+is appended.
+.PP
+The sixth line is the error text for the sense code and the sense qualifier if available.
+If the type of the device is known, the sense data is decoded from tables
+in
+.IR scsierrs.c " .
+The text is followed by the error value for a field replaceable unit.
+.PP
+The seventh line prints the block number that is related to the failed command
+and text for several error flags. The block number may not be valid.
+.PP
+The eight line reports the timeout set up for this command and the time
+that the command really needed to complete.
+.PP
+The following message is not an error:
+.sp
+.RS
+.nf
+Track 01: Total bytes read/written: 2048/2048 (1 sectors).
+wodim: I/O error. flush cache: scsi sendcmd: no error
+CDB:  35 00 00 00 00 00 00 00 00 00
+status: 0x2 (CHECK CONDITION)
+Sense Bytes: F0 00 05 80 00 00 27 0A 00 00 00 00 B5 00 00 00 00 00
+Sense Key: 0x5 Illegal Request, Segment 0
+Sense Code: 0xB5 Qual 0x00 (dummy data blocks added) Fru 0x0
+Sense flags: Blk -2147483609 (valid)
+cmd finished after 0.002s timeout 40s
+.fi
+.RE
+.sp
+It simply notifies, that a track that is smaller than the minimum size has been
+expanded to 300 sectors.
+.SH BUGS
+.PP
+.B netscsid
+does not work properly and is generally unmaintained. It is probably not
+compatible with rscsi from 
+.BR cdrtools
+either. Good bugfixes are welcome, talk to Cdrkit maintainers.
+.PP
+.B cuefile support is very limited, only one file is allowed. For volunteers,
+see TODO file in the source.
+.PP
+.B Specifying an audio file multiple times causes corruption of the second
+track (effectively no data plus minimum padding).
+.PP
+Some of the bugs may be fixed in Joerg Schilling's cdrtools. See there for
+details, URL attached below.
+
+.SH CREDITS
+.PP
+.TP 15
+Joerg Schilling (schilling@fokus.fhg.de)
+.br
+For writing cdrecord and libscg which represent the most parts of wodim's code.
+.PP
+.TP 15
+Bill Swartz	(Bill_Swartz@twolf.com)
+.br
+For helping me with the TEAC driver support
+.TP
+Aaron Newsome	(aaron.d.newsome@wdc.com)
+.br
+For letting me develop Sony support on his drive
+.TP
+Eric Youngdale	(eric@andante.jic.com)
+.br
+For supplying mkisofs
+.TP
+Gadi Oxman	(gadio@netvision.net.il)
+.br
+For tips on the ATAPI standard
+.TP
+Finn Arne Gangstad	(finnag@guardian.no)
+.br
+For the first FIFO implementation.
+.TP
+Dave Platt	(dplatt@feghoot.ml.org)
+.br
+For creating the experimental packet writing support,
+the first implementation of CD-RW blanking support,
+the first .wav file decoder 
+and many nice discussions on cdrecord.
+.TP
+Chris P. Ross (cross@eng.us.uu.net)
+.br
+For the first implementation of a BSDI SCSI transport.
+.TP
+Grant R. Guenther   (grant@torque.net)
+.br
+For creating the first parallel port transport implementation
+for Linux.
+.TP
+Kenneth D. Merry (ken@kdm.org)
+.br
+for providing the CAM port for FreeBSD together with Michael Smith (msmith@freebsd.org)
+.TP
+Heiko Ei\*sfeldt (heiko@hexco.de)
+for making libedc_ecc available (needed to write RAW data sectors).
+
+.SH "MAILING LISTS
+If you want to actively take part on the development of wodim,
+you may join the developer mailing list via this URL:
+.sp
+.B
+https://alioth.debian.org/mail/?group_id=31006
+.PP
+The mail address of the list is:
+.B
+debburn-devel@lists.alioth.debian.org
+
+.SH AUTHORS
+.B wodim
+is currently maintained as part of the cdrkit project by its developers. Most of the code and this manual page was originally written by:
+.PP
+.nf
+Joerg Schilling
+Seestr. 110
+D-13353 Berlin
+Germany
+.fi
+.PP
+This application is derived from "cdrecord" as included
+in the cdrtools package [1] created by Joerg
+Schilling, who deserves most of the credit for its success. However, he is not
+involved into the development of this spinoff and therefore he shall not be
+held responsible for any problems caused by it. Do not refer to this application
+as "cdrecord", do not try to get support for wodim by contacting the original
+authors.
+.PP
+Additional information can be found on:
+.br
+https://alioth.debian.org/projects/debburn/
+.PP
+If you have support questions, send them to
+.PP
+.B
+debburn-devel@lists.alioth.debian.org
+.br
+.PP
+If you have definitely found a bug, send a mail to this list or to
+.PP
+.B
+submit@bugs.debian.org
+.br
+.PP
+writing at least a short description into the Subject and "Package: cdrkit" in the first line of the mail body.
+.SH SOURCES
+.PP
+.br
+[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de
+
diff --git a/upstream/mageia-cauldron/man1/xargs.1 b/upstream/mageia-cauldron/man1/xargs.1
new file mode 100644
index 00000000..f743e60c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xargs.1
@@ -0,0 +1,511 @@
+.TH XARGS 1 \" -*- nroff -*-
+.SH NAME
+xargs \- build and execute command lines from standard input
+.SH SYNOPSIS
+.B xargs
+.nh
+[\fIoptions\fR]
+[\fIcommand\fR [\fIinitial-arguments\fR]]
+.hy
+.
+.SH DESCRIPTION
+This manual page
+documents the GNU version of
+.BR xargs .
+.B xargs
+reads items from the standard input, delimited by blanks (which can be
+protected with double or single quotes or a backslash) or newlines,
+and executes the
+.I command
+(default is
+.IR echo )
+one or more times with any
+.I initial-arguments
+followed by items read from standard input.  Blank lines on the
+standard input are ignored.
+.P
+The command line for
+.I command
+is built up until it reaches a system-defined limit (unless the
+.B \-n
+and
+.B \-L
+options are used).  The specified
+.I command
+will be invoked as many times as necessary to use up the list of input
+items.  In general, there will be many fewer invocations of
+.I command
+than there were items in the input.  This will normally have
+significant performance benefits.  Some commands can usefully be
+executed in parallel too; see the
+.B \-P
+option.
+.P
+Because Unix filenames can contain blanks and newlines, this default
+behaviour is often problematic; filenames containing blanks
+and/or newlines are incorrectly processed by
+.BR xargs .
+In these situations it is better to use the
+.B \-0
+option, which
+prevents such problems.   When using this option you will need to
+ensure that the program which produces the input for
+.B xargs
+also uses a null character as a separator.  If that program is
+GNU
+.B find
+for example, the
+.B \-print0
+option does this for you.
+.P
+If any invocation of the command exits with a status of 255,
+.B xargs
+will stop immediately without reading any further input.  An error
+message is issued on stderr when this happens.
+.
+.SH OPTIONS
+.TP
+.B \-0, \-\-null
+Input items are terminated by a null character instead of by
+whitespace, and the quotes and backslash are not special (every
+character is taken literally).  Disables the end of file string, which
+is treated like any other argument.  Useful when input items might
+contain white space, quote marks, or backslashes.  The GNU find
+\-print0 option produces input suitable for this mode.
+
+.TP
+.BI "\-a " file ", \-\-arg\-file=" file
+Read items from
+.I file
+instead of standard input.  If you use this option, stdin remains
+unchanged when commands are run.  Otherwise, stdin is redirected
+from
+.IR /dev/null .
+
+.TP
+.BI "\-\-delimiter=" delim ", \-d" " delim"
+Input items are terminated by the specified character.  The specified
+delimiter may be a single character, a C-style character escape such
+as
+.BR \en ,
+or an octal or hexadecimal escape code.  Octal and hexadecimal
+escape codes are understood as for the
+.B printf
+command.   Multibyte characters are not supported.
+When processing the input, quotes and backslash are not special; every
+character in the input is taken literally.  The
+.B \-d
+option disables any end-of-file string, which is treated like any
+other argument.  You can use this option when the input consists of
+simply newline-separated items, although it is almost always better to
+design your program to use
+.B \-\-null
+where this is possible.
+
+.TP
+.BI \-E " eof-str"
+Set the end of file string to \fIeof-str\fR.  If the end of file
+string occurs as a line of input, the rest of the input is ignored.
+If neither
+.B \-E
+nor
+.B \-e
+is used, no end of file string is used.
+.TP
+.BR \-e "[\fIeof-str\fR], " "\-\-eof" [\fI=eof-str\fR]
+This option is a synonym for the
+.B \-E
+option.  Use
+.B \-E
+instead,
+because it is POSIX compliant while this option is not.  If
+\fIeof-str\fR is omitted, there is no end of file string.  If neither
+.B \-E
+nor
+.B \-e
+is used, no end of file string is used.
+.TP
+.BI \-I " replace-str"
+Replace occurrences of \fIreplace-str\fR in the initial-arguments with
+names read from standard input.  Also, unquoted blanks do not
+terminate input items; instead the separator is the newline character.
+Implies
+.B \-x
+and
+.B \-L
+1.
+.TP
+.BR \-i "[\fIreplace-str\fR], " "\-\-replace" [\fI=replace-str\fR]
+This option is a synonym for
+.BI \-I replace-str
+if
+.I replace-str
+is specified.  If the
+.I replace-str
+argument is missing, the effect is the same as
+.BR \-I {}.
+This option is deprecated; use
+.B \-I
+instead.
+.TP
+.BI \-L " max-lines"
+Use at most \fImax-lines\fR nonblank input lines per command line.
+Trailing blanks cause an input line to be logically continued on the
+next input line.  Implies
+.BR \-x .
+.TP
+.BR \-l "[\fImax-lines\fR], " \-\-max-lines "[=\fImax-lines\fR]"
+Synonym for the
+.B \-L
+option.  Unlike
+.BR \-L ,
+the
+.I max-lines
+argument is optional.  If
+.I max-lines
+is not specified, it defaults to one.  The
+.B \-l
+option is deprecated since the POSIX standard specifies
+.B \-L
+instead.
+.TP
+.BI \-n " max-args\fB, \fI" "\-\-max\-args" \fR=\fImax-args
+Use at most \fImax-args\fR arguments per command line.  Fewer than
+.I max-args
+arguments will be used if the size (see the
+.B \-s
+option) is exceeded, unless the
+.B \-x
+option is given, in which case
+.B xargs will exit.
+.TP
+.BI \-P " max-procs\fR, \fI" \-\-max\-procs "\fR=\fImax-procs"
+Run up to
+.I max-procs
+processes at a time; the default is 1.  If
+.I max-procs
+is 0,
+.B xargs
+will run as many processes as
+possible at a time.  Use the
+.B \-n
+option or the
+.B \-L
+option with
+.BR \-P ;
+otherwise chances are that only one exec will be done.
+While
+.B xargs
+is running, you can send its process a SIGUSR1 signal to increase the
+number of commands to run simultaneously, or a SIGUSR2 to decrease the
+number.  You cannot increase it above an implementation-defined limit
+(which is shown with \-\-show-limits).  You cannot decrease it below
+1.
+.B xargs
+never terminates its commands; when asked to decrease, it merely
+waits for more than one existing command to terminate before starting
+another.
+
+.B Please note
+that it is up to the called processes to properly manage parallel
+access to shared resources.  For example, if more than one of them
+tries to print to stdout, the output will be produced in an
+indeterminate order (and very likely mixed up) unless the processes
+collaborate in some way to prevent this.  Using some kind of locking
+scheme is one way to prevent such problems.  In general, using a
+locking scheme will help ensure correct output but reduce performance.
+If you don't want to tolerate the performance difference, simply
+arrange for each process to produce a separate output file (or
+otherwise use separate resources).
+.TP
+.B \-o, \-\-open\-tty
+Reopen stdin as
+.I /dev/tty
+in the child process before executing the command.  This is useful if
+you want
+.B xargs
+to run an interactive application.
+.TP
+.B \-p, \-\-interactive
+Prompt the user about whether to run each command line and read a line
+from the terminal.  Only run the command line if the response starts
+with `y' or `Y'.  Implies
+.BR -t .
+.TP
+.BR \-\-process\-slot\-var "=\fIname\fR"
+Set the environment variable
+.I name
+to a unique value in each running child process.  Values are reused
+once child processes exit.  This can be used in a rudimentary load
+distribution scheme, for example.
+.TP
+.B \-r, \-\-no\-run\-if\-empty
+If the standard input does not contain any nonblanks, do not run the
+command.  Normally, the command is run once even if there is no input.
+This option is a GNU extension.
+.TP
+.BI -s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR"
+Use at most \fImax-chars\fR characters per command line, including the
+command and initial-arguments and the terminating nulls at the ends of
+the argument strings.  The largest allowed value is system-dependent,
+and is calculated as the argument length limit for exec, less the size
+of your environment, less 2048 bytes of headroom.  If this value is
+more than 128KiB, 128Kib is used as the default value; otherwise, the
+default value is the maximum.  1KiB is 1024 bytes.
+.B xargs
+automatically adapts to tighter constraints.
+.TP
+.B "\-\-show\\-limits"
+Display the limits on the command-line length which are imposed by the
+operating system,
+.BR xargs '
+choice of buffer size and the
+.B \-s
+option.  Pipe the input from
+.I /dev/null
+(and perhaps specify
+.BR --no-run-if-empty )
+if you don't want
+.B xargs
+to do anything.
+.TP
+.B \-t, \-\-verbose
+Print the command line on the standard error output before executing
+it.
+.TP
+.B \-x, \-\-exit
+Exit if the size (see the
+.B \-s
+option) is exceeded.
+.TP
+.B "\-\-help"
+Print a summary of the options to
+.B xargs
+and exit.
+.TP
+.B "\-\-version"
+Print the version number of
+.B xargs
+and exit.
+.PP
+The options
+.B \-\-max-lines
+(\fB\-L\fP, \fB\-l\fP),
+.B \-\-replace
+(\fB\-I\fP, \fB\-i\fP)
+and
+.B \-\-max-args
+(\fB\-n\fP)
+are mutually exclusive. If some of them are specified at the same
+time, then
+.B xargs
+will generally use the option specified last on the command line,
+i.e., it will reset the value of the offending option (given before)
+to its default value.
+Additionally,
+.B xargs
+will issue a warning diagnostic on
+.IR stderr .
+The exception to this rule is that the special
+.I max-args
+value
+.I 1
+('\fB\-n\fP\fI1\fP')
+is ignored after the
+.B \-\-replace
+option and its aliases
+.B \-I
+and
+.BR \-i ,
+because it would not actually conflict.
+
+.
+.SH "EXAMPLES"
+.nf
+.B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
+
+.fi
+Find files named
+.B core
+in or below the directory
+.B /tmp
+and delete them.  Note that this will work incorrectly if there are
+any filenames containing newlines or spaces.
+.P
+.B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
+
+Find files named
+.B core
+in or below the directory
+.B /tmp
+and delete them, processing filenames in such a way that file or
+directory names containing spaces or newlines are correctly handled.
+
+.P
+.B find /tmp \-depth \-name core \-type f \-delete
+
+Find files named
+.B core
+in or below the directory
+.B /tmp
+and delete them, but more efficiently than in the previous example
+(because we avoid the need to use
+.BR fork (2)
+and
+.BR exec (2)
+to launch
+.B rm
+and we don't need the extra
+.B xargs
+process).
+
+.P
+.nf
+.B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
+
+.fi
+Generates a compact listing of all the users on the system.
+.
+.SH "EXIT STATUS"
+.B xargs
+exits with the following status:
+.RS
+.IP 0
+if it succeeds
+.IP 123
+if any invocation of the command exited with status 1-125
+.IP 124
+if the command exited with status 255
+.IP 125
+if the command is killed by a signal
+.IP 126
+if the command cannot be run
+.IP 127
+if the command is not found
+.IP 1
+if some other error occurred.
+.RE
+
+.P
+Exit codes greater than 128 are used by the shell to indicate that
+a program died due to a fatal signal.
+.
+.SH "STANDARDS CONFORMANCE"
+As of GNU xargs version 4.2.9, the default behaviour of
+.B xargs
+is not to have a logical end-of-file marker.  POSIX (IEEE Std 1003.1,
+2004 Edition) allows this.
+.P
+The \-l and \-i options appear in the 1997 version of the POSIX
+standard, but do not appear in the 2004 version of the standard.
+Therefore you should use \-L and \-I instead, respectively.
+.P
+The \-o option is an extension to the POSIX standard for better
+compatibility with BSD.
+.P
+The POSIX standard allows implementations to have a limit on the size
+of arguments to the
+.B exec
+functions.  This limit could be as low as 4096 bytes including the size of the
+environment.  For scripts to be portable, they must not rely on a
+larger value.  However, I know of no implementation whose actual limit
+is that small.  The
+.B \-\-show\-limits
+option can be used to discover the actual limits in force on the
+current system.
+.
+.SH "BUGS"
+It is not possible for
+.B xargs
+to be used securely, since there will always be a time gap between the
+production of the list of input files and their use in the commands
+that
+.B xargs
+issues.  If other users have access to the system, they can manipulate
+the filesystem during this time window to force the action of the
+commands
+.B xargs
+runs to apply to files that you didn't intend.  For a more detailed
+discussion of this and related problems, please refer to the
+``Security Considerations'' chapter in the findutils Texinfo
+documentation.  The
+.B \-execdir
+option of
+.B find
+can often be used as a more secure alternative.
+
+When you use the
+.B \-I
+option, each line read from the input is buffered
+internally.   This means that there is an upper limit on the length
+of input line that
+.B xargs
+will accept when used with the
+.B \-I
+option.  To work around this
+limitation, you can use the
+.B \-s
+option to increase the amount of
+buffer space that
+.B xargs
+uses, and you can also use an extra invocation of
+.B xargs
+to ensure that very long lines do not occur.
+For example:
+.P
+.B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
+.P
+Here, the first invocation of
+.B xargs
+has no input line length limit
+because it doesn't use the
+.B \-i
+option.  The second invocation of
+.B xargs
+does have such a limit, but we have ensured that it never encounters
+a line which is longer than it can handle.   This is not an ideal
+solution.  Instead, the
+.B \-i
+option should not impose a line length
+limit, which is why this discussion appears in the BUGS section.
+The problem doesn't occur with the output of
+.BR find (1)
+because it emits just one filename per line.
+.
+.SH "REPORTING BUGS"
+GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.PP
+Report any other issue via the form at the GNU Savannah bug tracker:
+.RS
+<https://savannah.gnu.org/bugs/?group=findutils>
+.RE
+General topics about the GNU findutils package are discussed at the
+.I bug\-findutils
+mailing list:
+.RS
+<https://lists.gnu.org/mailman/listinfo/bug-findutils>
+.RE
+.
+.SH COPYRIGHT
+Copyright \(co 1990-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.
+.SH "SEE ALSO"
+.BR find (1),
+.BR kill (1),
+.BR locate (1),
+.BR updatedb (1),
+.BR fork (2),
+.BR execvp (3),
+.BR locatedb (5),
+.BR signal (7)
+.PP
+Full documentation <https://www.gnu.org/software/findutils/xargs>
+.br
+or available locally via:
+.B info xargs
diff --git a/upstream/mageia-cauldron/man1/xaumix.1 b/upstream/mageia-cauldron/man1/xaumix.1
new file mode 100644
index 00000000..e5ac431a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xaumix.1
@@ -0,0 +1,66 @@
+.\" $Aumix: aumix/doc/xaumix.1,v 1.3 2010/04/30 05:12:12 trevor Exp $
+.\" from mdoc.samples(7)
+.\"
+.\" The following requests are required for all man pages.
+.\"           .Dd Month day, year
+.\"           .Os OPERATING_SYSTEM [version/release]
+.\"           .Dt DOCUMENT_TITLE [section number] [volume]
+.\"           .Sh NAME
+.\"           .Nm name
+.\"           .Nd one line description of name
+.\"           .Sh SYNOPSIS
+.\"           .Sh DESCRIPTION
+.\" The following requests should be uncommented and
+.\" used where appropriate.  This next request is
+.\" for sections 2, 3 and 9 function return values only.
+.\" .Sh RETURN VALUES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\" .Sh ENVIRONMENT
+.\" .Sh FILES
+.\" .Sh EXAMPLES
+.\" This next request is for sections 1, 6, 7, 8 & 9 only
+.\"     (command return values (to shell) and
+.\"       fprintf/stderr type diagnostics)
+.\" .Sh DIAGNOSTICS
+.\" The next request is for sections 2, 3 and 9 error
+.\" and signal handling only.
+.\" .Sh ERRORS
+.\" .Sh SEE ALSO
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.\" .Sh BUGS
+.\"
+.Dd July 13, 2000
+.Os
+.Dt XAUMIX 1
+.Sh NAME
+.Nm xaumix
+.Nd aumix wrapper for X
+.Sh SYNOPSIS
+.Nm
+.Sh DESCRIPTION
+.Nm
+is a wrapper to select one of rxvt, xterm, kterm, or one of the other possible
+xterm "clones", and to launch that with aumix running in it. For some X
+terminal emulators an aumix colour scheme file is used to generate a sensible
+display (for example, rxvt and xterm behave differently with respect to the
+handling of colours).
+.Pp
+This script was originally intended for use from the Debian
+menu
+system, but may also be invoked manually from a shell.
+The GTK+ interface to
+aumix
+largely supersedes it.
+.Sh AUTHORS
+Paul Slootman <paul@debian.org>
+.br
+.Sh SEE ALSO
+.Xr aumix 1 ,
+.Xr eterm 1 ,
+.Xr kterm 1 ,
+.Xr rxvt 1 ,
+.Xr wterm 1 ,
+.Xr xterm 1x ,
+.Xr xvt 1
diff --git a/upstream/mageia-cauldron/man1/xbmtopbm.1 b/upstream/mageia-cauldron/man1/xbmtopbm.1
new file mode 100644
index 00000000..e7427aa8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xbmtopbm.1
@@ -0,0 +1,58 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Xbmtopbm User Manual" 0 "31 August 1988" "netpbm documentation"
+
+.SH NAME
+
+xbmtopbm - convert an X11 or X10 bitmap to a PBM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBxbmtopbm\fP
+
+[\fIbitmapfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBxbmtopbm\fP reads an X11 or X10 bitmap as input and produces a PBM
+image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBxbmtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoxbm" (1)\c
+\&, 
+.BR "pbmtox10bm" (1)\c
+\&, 
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1988 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/xbmtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/xcmsdb.1 b/upstream/mageia-cauldron/man1/xcmsdb.1
new file mode 100644
index 00000000..5a74ee1b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xcmsdb.1
@@ -0,0 +1,103 @@
+.\" $Xorg: xcmsdb.man,v 1.4 2001/02/09 02:05:39 xorgcvs Exp $
+.\" Copyright 1990, Tektronix Inc.
+.\" Copyright 1993, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included in
+.\" all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+.\" THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+.\" SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall not
+.\" be used in advertising or otherwise to promote the sale, use or other
+.\" dealing in this Software without prior written authorization from the
+.\" The Open Group.
+.\"
+.\" $XFree86: xc/programs/xcmsdb/xcmsdb.man,v 1.6 2001/01/27 18:21:09 dawes Exp $
+.\"
+.TH XCMSDB 1 "xcmsdb 1.0.6" "X Version 11"
+.SH NAME
+xcmsdb \- Device Color Characterization utility for X Color Management System
+.SH SYNOPSIS
+.B xcmsdb
+[ \fB\-query\fP ] [ \fB\-remove\fP ]
+[ \fB\-format\032\fP|\fB16\fP|\fB8\fP ]
+[ \fB\-help\fP ] [ \fB\-version\fP ]
+[ \fIfilename\fP ]
+.SH DESCRIPTION
+.I xcmsdb
+is used to load, query, or remove Device Color Characterization data
+stored in properties on the root window of the screen as specified
+in section 7, Device Color Characterization, of the ICCCM.
+Device Color Characterization data (also called the Device Profile)
+is an integral part of Xlib's X Color Management System (Xcms), necessary
+for proper conversion of color specification between device-independent
+and device-dependent forms.
+Xcms uses 3x3 matrices stored in the XDCCC_LINEAR_RGB_MATRICES property to
+convert color specifications between CIEXYZ and RGB Intensity (XcmsRGBi, also
+referred to as linear RGB).
+Xcms then uses display gamma information stored in the
+XDCCC_LINEAR_RGB_CORRECTION property to convert color specifications between
+RGBi and RGB device (XcmsRGB, also referred to as device RGB).
+.LP
+Note that Xcms allows clients to register \fIfunction sets\fP
+in addition to its
+built-in function set for CRT color monitors.  Additional function sets
+may store their device profile information in other properties in function
+set specific format.
+This utility is unaware of these non-standard properties.
+.LP
+The ASCII readable contents of
+.I filename
+(or the standard input if no input file is given)
+are appropriately transformed for storage in properties, provided the
+.B \-query
+or
+.B \-remove
+options are not specified.
+.SH "OPTIONS"
+.I xcmsdb
+program accepts the following options:
+.TP 8
+.B \-query
+This option attempts to read the XDCCC properties off the screen's root
+window.
+If successful, it transforms the data into a more readable format, then
+sends the data to standard out.
+.TP 8
+.B \-remove
+This option attempts to remove the XDCCC properties on the screen's root
+window.
+.TP 8
+\fB\-format\032\fP|\fB16\fP|\fB8\fP
+Specifies the property format (32, 16, or 8 bits per entry) for the
+XDCCC_LINEAR_RGB_CORRECTION property.
+Precision of encoded floating point values increases with the increase
+in bits per entry.
+The default is 32 bits per entry.
+.TP 8
+.B \-help
+This option prints a summary of the available options and exits.
+.TP 8
+.B \-version
+This option prints the program version and exits.
+.SH "SEE ALSO"
+xprop(1), Xlib documentation
+.SH ENVIRONMENT
+.TP 8
+.B DISPLAY
+to figure out which display and screen to use.
+.SH AUTHOR
+Chuck Adams, Tektronix Inc.
+Al Tabayoyon, SynChromatics Inc. (added multi-visual support)
diff --git a/upstream/mageia-cauldron/man1/xgamma.1 b/upstream/mageia-cauldron/man1/xgamma.1
new file mode 100644
index 00000000..baed7c10
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xgamma.1
@@ -0,0 +1,104 @@
+.\" Copyright 1999  by The XFree86 Project, Inc.
+.\"
+.\" All Rights Reserved.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE XFREE86 PROJECT BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The XFree86 Project shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The XFree86 Project.
+.\"
+.TH xgamma 1 "xgamma 1.0.7" "X Version 11"
+.SH NAME
+xgamma - Alter a monitor's gamma correction through the X server
+.SH SYNOPSIS
+.B "xgamma"
+[-display \fIdisplay\fP] [-screen \fIscreen\fP] [-quiet] [-version]
+[-gamma f.f | [[-rgamma f.f] [-ggamma f.f] [-bgamma f.f]]]
+.SH DESCRIPTION
+.PP
+.B xgamma
+allows X users to query and alter the gamma correction of a monitor via
+the X video mode extension (XFree86-VidModeExtension).
+.PP
+Note that the \fBxgamma\fP utility is obsolete and deficient, \fBxrandr\fP
+should be used with drivers that support the \fBXRandr\fP extension.
+.PP
+If no value for the gamma correction is given via the
+.I -gamma
+or
+.IR -rgamma / -ggamma / -bgamma
+options,
+.B xgamma
+prints the current gamma correction of the display.
+.SH OPTIONS
+.PP
+.TP 8
+.B "-display \fIdisplay\fP"
+This argument allows you to specify the server to connect to; see \fIX(7)\fP.
+.PP
+.TP 8
+.B "-screen \fIscreen\fP"
+When multiple displays are configured as a single logical display, this option
+allows you to select the screen you wish to change.
+.PP
+.TP 8
+.B "-quiet"
+Silence the normal output of
+.B xgamma
+.PP
+.TP 8
+.B "-help"
+Print out the `Usage:' command syntax summary.
+.PP
+.TP 8
+.B "-version"
+Print out the program version and exit.
+.PP
+.TP 8
+.B "-gamma f.f"
+The gamma correction can either be defined as a single value, or
+separately for the red, green and blue components. This argument
+specifies the gamma correction as a single value.
+.PP
+.TP 8
+.B "-rgamma f.f"
+This argument specifies the red component of the gamma correction.
+.PP
+.TP 8
+.B "-ggamma f.f"
+This argument specifies the green component of the gamma correction.
+.PP
+.TP 8
+.B "-bgamma f.f"
+This argument specifies the blue component of the gamma correction.
+.SH ENVIRONMENT
+.PP
+.TP 8
+.B DISPLAY
+To get default host and display number.
+.SH BUGS
+.PP
+This client changes the internal values of the gamma correction for the
+Xserver. Whether or not these values are respected depends on the video
+drivers.
+.PP
+The gamma values are passed to the Xserver with 3 decimal places of
+accuracy.
+.SH SEE ALSO
+xvidtune(1),
+xrandr(1)
+.SH AUTHORS
+Kaleb S. Keithley, X Consortium.
+.br
+David Dawes, David Bateman
diff --git a/upstream/mageia-cauldron/man1/xgettext.1 b/upstream/mageia-cauldron/man1/xgettext.1
new file mode 100644
index 00000000..88a3c0e2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xgettext.1
@@ -0,0 +1,249 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
+.TH XGETTEXT "1" "October 2022" "GNU gettext-tools 0.21.1" "User Commands"
+.SH NAME
+xgettext \- extract gettext strings from source
+.SH SYNOPSIS
+.B xgettext
+[\fI\,OPTION\/\fR] [\fI\,INPUTFILE\/\fR]...
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Extract translatable strings from given input files.
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+Similarly for optional arguments.
+.SS "Input file location:"
+.TP
+INPUTFILE ...
+input files
+.TP
+\fB\-f\fR, \fB\-\-files\-from\fR=\fI\,FILE\/\fR
+get list of input files from FILE
+.TP
+\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIRECTORY\/\fR
+add DIRECTORY to list for input files search
+.PP
+If input file is \-, standard input is read.
+.SS "Output file location:"
+.TP
+\fB\-d\fR, \fB\-\-default\-domain\fR=\fI\,NAME\/\fR
+use NAME.po for output (instead of messages.po)
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+write output to specified file
+.TP
+\fB\-p\fR, \fB\-\-output\-dir\fR=\fI\,DIR\/\fR
+output files will be placed in directory DIR
+.PP
+If output file is \-, output is written to standard output.
+.SS "Choice of input file language:"
+.TP
+\fB\-L\fR, \fB\-\-language\fR=\fI\,NAME\/\fR
+recognise the specified language
+(C, C++, ObjectiveC, PO, Shell, Python, Lisp,
+EmacsLisp, librep, Scheme, Smalltalk, Java,
+JavaProperties, C#, awk, YCP, Tcl, Perl, PHP,
+Ruby, GCC\-source, NXStringTable, RST, RSJ,
+Glade, Lua, JavaScript, Vala, Desktop)
+.TP
+\fB\-C\fR, \fB\-\-c\fR++
+shorthand for \fB\-\-language\fR=\fI\,C\/\fR++
+.PP
+By default the language is guessed depending on the input file name extension.
+.SS "Input file interpretation:"
+.TP
+\fB\-\-from\-code\fR=\fI\,NAME\/\fR
+encoding of input files
+(except for Python, Tcl, Glade)
+.PP
+By default the input files are assumed to be in ASCII.
+.SS "Operation mode:"
+.TP
+\fB\-j\fR, \fB\-\-join\-existing\fR
+join messages with existing file
+.TP
+\fB\-x\fR, \fB\-\-exclude\-file\fR=\fI\,FILE\/\fR.po
+entries from FILE.po are not extracted
+.TP
+\fB\-cTAG\fR, \fB\-\-add\-comments\fR=\fI\,TAG\/\fR
+place comment blocks starting with TAG and
+preceding keyword lines in output file
+.TP
+\fB\-c\fR, \fB\-\-add\-comments\fR
+place all comment blocks preceding keyword lines
+in output file
+.TP
+\fB\-\-check\fR=\fI\,NAME\/\fR
+perform syntax check on messages
+(ellipsis\-unicode, space\-ellipsis,
+.IP
+quote\-unicode, bullet\-unicode)
+.TP
+\fB\-\-sentence\-end\fR=\fI\,TYPE\/\fR
+type describing the end of sentence
+(single\-space, which is the default,
+.IP
+or double\-space)
+.SS "Language specific options:"
+.TP
+\fB\-a\fR, \fB\-\-extract\-all\fR
+extract all strings
+(only languages C, C++, ObjectiveC, Shell,
+Python, Lisp, EmacsLisp, librep, Scheme, Java,
+C#, awk, Tcl, Perl, PHP, GCC\-source, Glade,
+Lua, JavaScript, Vala)
+.TP
+\fB\-kWORD\fR, \fB\-\-keyword\fR=\fI\,WORD\/\fR
+look for WORD as an additional keyword
+.TP
+\fB\-k\fR, \fB\-\-keyword\fR
+do not to use default keywords
+(only languages C, C++, ObjectiveC, Shell,
+Python, Lisp, EmacsLisp, librep, Scheme, Java,
+C#, awk, Tcl, Perl, PHP, GCC\-source, Glade,
+Lua, JavaScript, Vala, Desktop)
+.TP
+\fB\-\-flag\fR=\fI\,WORD\/\fR:ARG:FLAG
+additional flag for strings inside the argument
+number ARG of keyword WORD
+.TP
+(only languages C, C++, ObjectiveC, Shell,
+Python, Lisp, EmacsLisp, librep, Scheme, Java,
+C#, awk, YCP, Tcl, Perl, PHP, GCC\-source,
+Lua, JavaScript, Vala)
+.TP
+\fB\-T\fR, \fB\-\-trigraphs\fR
+understand ANSI C trigraphs for input
+(only languages C, C++, ObjectiveC)
+.TP
+\fB\-\-its\fR=\fI\,FILE\/\fR
+apply ITS rules from FILE
+(only XML based languages)
+.TP
+\fB\-\-qt\fR
+recognize Qt format strings
+(only language C++)
+.TP
+\fB\-\-kde\fR
+recognize KDE 4 format strings
+(only language C++)
+.TP
+\fB\-\-boost\fR
+recognize Boost format strings
+(only language C++)
+.TP
+\fB\-\-debug\fR
+more detailed formatstring recognition result
+.SS "Output details:"
+.TP
+\fB\-\-color\fR
+use colors and other text attributes always
+.TP
+\fB\-\-color\fR=\fI\,WHEN\/\fR
+use colors and other text attributes if WHEN.
+WHEN may be 'always', 'never', 'auto', or 'html'.
+.TP
+\fB\-\-style\fR=\fI\,STYLEFILE\/\fR
+specify CSS style rule file for \fB\-\-color\fR
+.TP
+\fB\-e\fR, \fB\-\-no\-escape\fR
+do not use C escapes in output (default)
+.TP
+\fB\-E\fR, \fB\-\-escape\fR
+use C escapes in output, no extended chars
+.TP
+\fB\-\-force\-po\fR
+write PO file even if empty
+.TP
+\fB\-i\fR, \fB\-\-indent\fR
+write the .po file using indented style
+.TP
+\fB\-\-no\-location\fR
+do not write '#: filename:line' lines
+.TP
+\fB\-n\fR, \fB\-\-add\-location\fR
+generate '#: filename:line' lines (default)
+.TP
+\fB\-\-strict\fR
+write out strict Uniforum conforming .po file
+.TP
+\fB\-\-properties\-output\fR
+write out a Java .properties file
+.TP
+\fB\-\-stringtable\-output\fR
+write out a NeXTstep/GNUstep .strings file
+.TP
+\fB\-\-itstool\fR
+write out itstool comments
+.TP
+\fB\-w\fR, \fB\-\-width\fR=\fI\,NUMBER\/\fR
+set output page width
+.TP
+\fB\-\-no\-wrap\fR
+do not break long message lines, longer than
+the output page width, into several lines
+.TP
+\fB\-s\fR, \fB\-\-sort\-output\fR
+generate sorted output
+.TP
+\fB\-F\fR, \fB\-\-sort\-by\-file\fR
+sort output by file location
+.TP
+\fB\-\-omit\-header\fR
+don't write header with 'msgid ""' entry
+.TP
+\fB\-\-copyright\-holder\fR=\fI\,STRING\/\fR
+set copyright holder in output
+.TP
+\fB\-\-foreign\-user\fR
+omit FSF copyright in output for foreign user
+.TP
+\fB\-\-package\-name\fR=\fI\,PACKAGE\/\fR
+set package name in output
+.TP
+\fB\-\-package\-version\fR=\fI\,VERSION\/\fR
+set package version in output
+.TP
+\fB\-\-msgid\-bugs\-address\fR=\fI\,EMAIL\/\fR@ADDRESS
+set report address for msgid bugs
+.TP
+\fB\-m[STRING]\fR, \fB\-\-msgstr\-prefix\fR[=\fI\,STRING\/\fR]
+use STRING or "" as prefix for msgstr
+values
+.TP
+\fB\-M[STRING]\fR, \fB\-\-msgstr\-suffix\fR[=\fI\,STRING\/\fR]
+use STRING or "" as suffix for msgstr
+values
+.SS "Informative output:"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase verbosity level
+.SH AUTHOR
+Written by Ulrich Drepper.
+.SH "REPORTING BUGS"
+Report bugs in the bug tracker at <https://savannah.gnu.org/projects/gettext>
+or by email to <bug\-gettext@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 1995\-2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B xgettext
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B xgettext
+programs are properly installed at your site, the command
+.IP
+.B info xgettext
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/xhost.1 b/upstream/mageia-cauldron/man1/xhost.1
new file mode 100644
index 00000000..b1224256
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xhost.1
@@ -0,0 +1,187 @@
+.\" Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved.
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the "Software"),
+.\" to deal in the Software without restriction, including without limitation
+.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
+.\" and/or sell copies of the Software, and to permit persons to whom the
+.\" Software is furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice (including the next
+.\" paragraph) shall be included in all copies or substantial portions of the
+.\" Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+.\" DEALINGS IN THE SOFTWARE.
+.\"
+.\" Copyright 1988, 1998  The Open Group
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, and/or sell copies of the Software, and to permit persons
+.\" to whom the Software is furnished to do so, provided that the above
+.\" copyright notice(s) and this permission notice appear in all copies of
+.\" the Software and that both the above copyright notice(s) and this
+.\" permission notice appear in supporting documentation.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
+.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
+.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of a copyright holder
+.\" shall not be used in advertising or otherwise to promote the sale, use
+.\" or other dealings in this Software without prior written authorization
+.\" of the copyright holder.
+.\"
+.\" X Window System is a trademark of The Open Group.
+.\"
+.TH XHOST 1 "xhost 1.0.9" "X Version 11"
+.SH NAME
+xhost \- server access control program for X
+.SH SYNOPSIS
+.B xhost
+[[+\-]name ...]
+.SH DESCRIPTION
+The \fIxhost\fP program
+is used to add and delete host names or user names to the list allowed
+to make connections to the X server.  In the case of hosts, this provides
+a rudimentary form of privacy control and security.  It is only sufficient
+for a workstation (single user) environment, although it does limit the
+worst abuses.  Environments which require more sophisticated measures should
+implement the user-based mechanism or use the hooks in the
+protocol for passing other authentication data to the server.
+.SH OPTIONS
+\fIXhost\fP accepts the following command line options described below.  For
+security, the options that affect access control may only be run from the
+"controlling host".  For workstations, this is the same machine as the
+server.  For X terminals, it is the login host.
+.TP 8
+.B \-help
+Prints a usage message.
+.TP 8
+.BI "[+]" "name"
+The given \fIname\fP (the plus sign is optional)
+is added to the list allowed to connect to the X server.
+The name can be a host name or a complete name (See
+.SM
+.B NAMES
+for more details).
+.TP 8
+.BI \- "name"
+The given \fIname\fP is removed from the list of allowed
+to connect to the server.  The name can be a host name or a complete
+name (See
+.SM
+.B NAMES
+for more details).
+Existing connections are not broken, but new
+connection attempts will be denied.
+Note that the current machine is allowed to be removed; however, further
+connections (including attempts to add it back) will not be permitted.
+Resetting the server (thereby breaking all connections)
+is the only way to allow local connections again.
+.TP 8
+.B \+
+Access is granted to everyone, even if they aren't on the list
+(i.e., access control is turned off).
+.TP 8
+.B \-
+Access is restricted to only those on the list
+(i.e., access control is turned on).
+.TP 8
+.I nothing
+If no command line arguments are given,
+a message indicating whether or not access control is currently enabled
+is printed, followed by the list of those allowed to connect.
+This is the only option that may be used from machines other than
+the controlling host.
+.SH NAMES
+A complete name has the syntax
+``family:name'' where the families are
+as follows:
+.PP
+.nf
+.ta 1i
+inet	Internet host (IPv4)
+inet6	Internet host (IPv6)
+dnet	DECnet host
+nis	Secure RPC network name
+krb	Kerberos V5 principal
+local	contains only one name, the empty string
+si	Server Interpreted
+.fi
+.PP
+The family is case insensitive.
+The format of the name varies with the family.
+.PP
+When Secure RPC is being used, the
+network independent netname (e.g., "nis:unix.\fIuid\fP@\fIdomainname\fP") can
+be specified, or a local user can be specified with just the username
+and a trailing at-sign (e.g., "nis:pat@").
+.PP
+For backward compatibility with pre-R6 \fIxhost\fP,
+names that contain an at-sign (@) are assumed to be in the nis family.
+Otherwise they are assumed to be Internet addresses. If compiled to support
+IPv6, then all IPv4 and IPv6 addresses returned by getaddrinfo(3) are added to
+the access list in the appropriate inet or inet6 family.
+.PP
+The local family specifies all the local connections at once. However,
+the server interpreted address "si:localuser:\fIusername\fP" can be
+used to specify a single local user. (See the
+\fIXsecurity\fP(7) manual page for more details.)
+.PP
+Server interpreted addresses consist of a case-sensitive type tag and a
+string representing a given value, separated by a colon.  For example,
+"si:hostname:almas" is a server interpreted address of type \fIhostname\fP,
+with a value of \fIalmas\fP.   For more information on the available forms
+of server interpreted addresses, see the \fIXsecurity\fP(7)
+manual page.
+.PP
+The initial access control list for display number \fBn\fP
+may be set by the file \fI/etc/X\fBn\fI.hosts\fR, where
+\fBn\fP is the display number of the server.  See \fIXserver\fP(1)
+for details.
+.SH DIAGNOSTICS
+For each name added to the access control list,
+a line of the form "\fIname\fP being added to access control list"
+is printed.
+For each name removed from the access control list,
+a line of the form "\fIname\fP being removed from access control list"
+is printed.
+.SH "SEE ALSO"
+X(7), Xsecurity(7), Xserver(1), xdm(1), xauth(1), getaddrinfo(3)
+.SH ENVIRONMENT
+.TP 8
+.B DISPLAY
+to get the default host and display to use.
+.SH BUGS
+.PP
+You can't specify a display on the command line because
+.B \-display
+is a valid command line argument (indicating that you want
+to remove the machine named
+.I ``display''
+from the access list).
+.PP
+The X server stores network addresses, not host names, unless you use
+the server-interpreted hostname type address.  If somehow you change a
+host's network address while the server is still running, and you are
+using a network-address based form of authentication, \fIxhost\fP must
+be used to add the new address and/or remove the old address.
+.SH AUTHORS
+Bob Scheifler, MIT Laboratory for Computer Science,
+.br
+Jim Gettys, MIT Project Athena (DEC).
diff --git a/upstream/mageia-cauldron/man1/ximtoppm.1 b/upstream/mageia-cauldron/man1/ximtoppm.1
new file mode 100644
index 00000000..785446fe
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ximtoppm.1
@@ -0,0 +1,85 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ximtoppm User Manual" 0 "02 April 2000" "netpbm documentation"
+
+.SH NAME
+
+ximtoppm - convert an Xim file to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBximtoppm\fP
+
+[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fIximfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBximptoppm\fP reads an Xim file as input and produces a PPM
+image as output.  The Xim toolkit is included in the contrib tree of
+the X.V11R4 release.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBximtoppm\fP recognizes the following
+command line option:
+.PP
+You can abbreviate any option to its shortest unique prefix.
+
+
+.TP
+\fB--alphaout=\fP\fIalpha-filename\fP
+\fBximtoppm\fP creates a PGM file containing the transparency channel
+values in the input image.  If the input image doesn't contain a
+transparency channel, the \fIalpha-filename\fP file contains all zero
+(transparent) transparency values.  If you don't specify \fB--alphaout\fP,
+\fBximtoppm\fP does not generate a transparency file, and if the input
+image has a transparency channel, \fBximtoppm\fP simply discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBximtoppm\fP writes the
+transparency output to Standard Output and discards the image.
+.sp
+Actually, an Xim image can contain an arbitrary fourth channel --
+it need not be a transparency channel.  \fBximtoppm\fP extracts any fourth
+channel it finds as described above; it doesn't matter if it is a
+transparency channel or not.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ximtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/xinit.1 b/upstream/mageia-cauldron/man1/xinit.1
new file mode 100644
index 00000000..ed68b8c2
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xinit.1
@@ -0,0 +1,199 @@
+.\"
+.\" Copyright 1988, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XINIT 1 "xinit 1.4.2" "X Version 11"
+.SH NAME
+xinit \- X Window System initializer
+.SH SYNOPSIS
+.B xinit
+[ [
+.I client
+]
+.I options
+\&\.\|.\|. ] [
+.B \-\^\-
+[
+.I server
+] [
+.I display
+]
+.I options
+\&.\|.\|. ]
+.SH DESCRIPTION
+The \fBxinit\fP program is used to start the X Window System server and a first
+client program on systems that are not using a display manager such as
+.BR xdm (1)
+or in environments
+that use multiple window systems.  When this first client exits,
+\fBxinit\fP will kill the X server and then terminate.
+.PP
+If no specific client program is given on the command line,
+\fBxinit\fP will look for a file in the user's home directory
+called \fI.xinitrc\fP to run as a shell script to start up client programs.
+If no such file exists, \fBxinit\fP will use the following as a default:
+.sp
+	xvt  \-geometry  +1+1  \-display  :0
+.sp
+.PP
+If no specific server program is given on the command line,
+\fBxinit\fP will look for a file in the user's home directory
+called \fI.xserverrc\fP to run as a shell script to start up the server.
+If no such file exists, \fIxinit\fP will use the following as a default:
+.sp
+	X  :0
+.sp
+Note that this assumes that there is a program named \fIX\fP in the current
+search path.  The site administrator should, therefore, make a link to the
+appropriate type of server on the machine, or create a shell script that
+runs \fBxinit\fP with the appropriate server.
+.PP
+Note, when using a \fI.xserverrc\fP script be sure to ``exec'' the real X server.
+Failing to do this can make the X server slow to start and exit.  For example:
+.sp
+	exec Xdisplaytype
+.PP
+An important point is that programs which are run by \fI\.xinitrc\fP
+should be run in the background if they do
+not exit right away, so that they don't prevent other programs from
+starting up.
+However, the last long-lived program started (usually
+a window manager or terminal emulator) should be
+left in the foreground so that the script won't exit (which
+indicates that the user is done and that \fBxinit\fP should exit).
+.PP
+An alternate client and/or server may be specified on the
+command line.  The desired client program and its arguments should be given
+as the first command line arguments to \fBxinit\fP.  To specify a particular
+server command line, append a double dash (\-\^\-) to the \fBxinit\fP command
+line (after any client and arguments) followed by the desired server command.
+.PP
+Both the client program name and the server program name must begin with a
+slash (/) or a period (.).  Otherwise, they are treated as an arguments to be
+appended to their respective startup lines.  This makes it possible to
+add arguments (for example, foreground and background colors) without
+having to retype the whole command line.
+.PP
+If an explicit server name is not given and the first argument following the
+double dash (\-\^\-) is a colon followed by a digit, \fBxinit\fP will use that
+number as the display
+number instead of zero.  All remaining arguments are appended to the server
+command line.
+.PP
+.SH EXAMPLES
+Below are several examples of how command line arguments in \fBxinit\fP are
+used.
+.TP 8
+.B "xinit"
+This will start up a server named \fIX\fP and run the user's \fI\.xinitrc\fP,
+if it exists, or else start an \fIxterm\fP.
+.TP 8
+.B "xinit \-\^\- /usr/bin/Xvnc  :1"
+This is how one could start a specific type of server on an alternate display.
+.TP 8
+.B "xinit \-geometry =80x65+10+10 \-fn 8x13 \-j \-fg white \-bg navy"
+This will start up a server named \fIX\fP, and will append the given
+arguments to the default \fIxterm\fP command.  It will ignore \fI\.xinitrc\fP.
+.TP 8
+.B "xinit \-e widgets \-\^\- ./Xorg \-l \-c"
+This will use the command \fI\./Xorg \-l \-c\fP to start the server and will
+append the arguments \fI\-e widgets\fP to the default \fIxterm\fP command.
+.TP 8
+.B "xinit /usr/bin/ssh \-X fasthost cpupig \-\^\-  :1 \-a 2 \-t 5"
+This will start a server named \fIX\fP on display 1 with the arguments
+\fI\-a 2 \-t 5\fP.  It will then start a remote shell on the machine
+\fBfasthost\fP in which it will run the command \fIcpupig\fP, telling it
+to display back on the local workstation.
+.PP
+Below is a sample \fI\.xinitrc\fP that starts a clock, several terminals, and
+leaves the window manager running as the ``last'' application.  Assuming that
+the window manager has been configured properly, the user
+then chooses the ``Exit'' menu item to shut down X.
+.sp
+.in +8
+.nf
+xrdb \-load $HOME/.Xresources
+xsetroot \-solid gray &
+xclock \-g 50x50\-0+0 \-bw 0 &
+xload \-g 50x50\-50+0 \-bw 0 &
+xterm \-g 80x24+0+0 &
+xterm \-g 80x24+0\-0 &
+twm
+.fi
+.in -8
+.sp
+Sites that want to create a common startup environment could simply create
+a default \fI\.xinitrc\fP that references a site-wide startup file:
+.sp
+.in +8
+.nf
+\&#!/bin/sh
+\&. /etc/X11/xinit/site.xinitrc
+.fi
+.in -8
+.sp
+Another approach is to write a script that starts \fBxinit\fP with a specific
+shell script.  Such scripts are usually named \fIx11\fP, \fIxstart\fP, or
+\fIstartx\fP and are a convenient way to provide a simple interface for
+novice users:
+.sp
+.in +8
+.nf
+\&#!/bin/sh
+xinit /etc/X11/xinit/site.xinitrc \-\^\- /usr/bin/X \-br
+.fi
+.in -8
+.sp
+.SH "ENVIRONMENT VARIABLES"
+.TP 15
+.B DISPLAY
+This variable gets set to the name of the display to which clients should
+connect.
+.TP 15
+.B XINITRC
+This variable specifies an init file containing shell commands to start up the
+initial windows.  By default, \fI\.xinitrc\fP in the home directory will be
+used.
+.SH FILES
+.TP 15
+.I .xinitrc
+default client script
+.TP 15
+.I xterm
+client to run if \fI.xinitrc\fP does not exist
+.TP 15
+.I .xserverrc
+default server script
+.TP 15
+.I X
+server to run if \fI.xserverrc\fP does not exist
+.SH "SEE ALSO"
+.BR X (7),
+.BR startx (1),
+.BR Xserver (1),
+.BR Xorg (1),
+.BR xorg.conf (5),
+.BR xterm (1)
+.SH AUTHOR
+Bob Scheifler, MIT Laboratory for Computer Science
diff --git a/upstream/mageia-cauldron/man1/xload.1 b/upstream/mageia-cauldron/man1/xload.1
new file mode 100644
index 00000000..b7a11120
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xload.1
@@ -0,0 +1,109 @@
+.\"
+.TH XLOAD 1 "xload 1.1.4" "X Version 11"
+.SH NAME
+xload \- system load average display for X
+.SH SYNOPSIS
+\fBxload\fP	[-\fItoolkitoption\fP ...] [-scale \fIinteger\fP] [-update \fIseconds\fP]
+.br
+        [-hl \fIcolor\fP] [-highlight \fIcolor\fP]  [-remote \fIhost\fP]
+.br
+        [-jumpscroll \fIpixels\fP] [-label \fIstring\fP] [-nolabel] [-lights]
+.SH DESCRIPTION
+The
+.I xload
+program displays a periodically updating histogram of the system load average.
+.SH OPTIONS
+.PP
+.I Xload
+accepts all of the standard X Toolkit command line options (see
+.BR X (7)).
+The order of the options is unimportant.  xload also accepts the
+following additional options:
+.PP
+.TP 8
+\fB\-hl\fP \fIcolor\fP or \fB\-highlight\fP \fIcolor\fP
+This option specifies the color of the scale lines.
+.TP 8
+.B \-jumpscroll \fIpixels\fP
+The number of pixels to shift the graph to the left when the graph
+reaches the right edge of the window.  The default value is 1/2 the width
+of the current window.  Smooth scrolling can be achieved by setting it to 1.
+.TP 8
+.B \-label \fIstring\fP
+The string to put into the label above the load average.
+.TP 8
+.B \-nolabel
+If this command line option is specified then no label will be
+displayed above the load graph.
+.TP 8
+.B \-lights
+When specified, this option causes
+.I xload
+to display the current load average by using the keyboard leds; for
+a load average of \fIn\fP, xload lights the first \fIn\fP keyboard leds.
+This option turns off the usual screen display.
+.TP 8
+.B \-scale \fIinteger\fP
+This option specifies the minimum number of tick marks in the histogram,
+where one division represents one load average point.  If the load goes
+above this number, \fIxload\fP will create more divisions, but it will never
+use fewer than this number.  The default is 1.
+.PP
+.TP 8
+.B \-update \fIseconds\fP
+This option specifies the interval in seconds at which \fIxload\fP
+updates its display.  The minimum amount of time allowed between updates
+is 1 second.  The default is 10.
+.TP 8
+.B \-remote \fIhost\fP
+This option tells \fIxload\fP to display the load of \fIhost\fP instead of \fIlocalhost\fP. \fIXload\fP gets the information from the \fIrwhod\fP database and consequently requires \fIrwhod\fP to be executing both on \fIlocalhost\fP and \fIhost\fP.
+.SH RESOURCES
+In addition to the resources available to each of the widgets used by
+\fIxload\fP there is one resource defined by the application itself.
+.TP 8
+.B showLabel (\fPclass \fIBoolean\fB)
+If False then no label will be displayed.
+.SH WIDGETS
+In order to specify resources, it is useful to know the hierarchy of
+the widgets which compose \fIxload\fR.  In the notation below,
+indentation indicates hierarchical structure.  The widget class name
+is given first, followed by the widget instance name.
+.sp
+.nf
+XLoad  xload
+        Paned  paned
+                Label  label
+                StripChart  load
+.fi
+.sp
+.SH ENVIRONMENT
+.PP
+.TP 8
+.B DISPLAY
+to get the default host and display number.
+.TP 8
+.B XENVIRONMENT
+to get the name of a resource file that overrides the global resources
+stored in the RESOURCE_MANAGER property.
+.SH FILES
+.TP
+.I /usr/share/X11/app-defaults/XLoad
+specifies required resources
+.SH SEE ALSO
+.BR X (7),
+.BR xrdb (1),
+.BR mem (4),
+Athena StripChart Widget.
+.SH BUGS
+On older platforms, this program may require the ability to open and read
+the special system file \fI/dev/kmem\fP.  Sites that do not allow general
+access to this file may need to make \fIxload\fP belong to the same group
+as \fI/dev/kmem\fP and turn on the \fIset group id\fP permission flag.
+.PP
+Reading the load average is inherently non-portable.  Therefore, the routine
+used to read it (get_load.c) must be ported to each new operating system.
+.SH AUTHORS
+K. Shane Hartman (MIT-LCS) and Stuart A. Malone (MIT-LCS);
+.br
+with features added by Jim Gettys (MIT-Athena), Bob Scheifler (MIT-LCS),
+Tony Della Fera (MIT-Athena), and Chris Peterson (MIT-LCS).
diff --git a/upstream/mageia-cauldron/man1/xmodmap.1 b/upstream/mageia-cauldron/man1/xmodmap.1
new file mode 100644
index 00000000..c3b7443d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xmodmap.1
@@ -0,0 +1,339 @@
+.\" Copyright (c) 1987, 2010, Oracle and/or its affiliates. All rights reserved.
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the "Software"),
+.\" to deal in the Software without restriction, including without limitation
+.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
+.\" and/or sell copies of the Software, and to permit persons to whom the
+.\" Software is furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice (including the next
+.\" paragraph) shall be included in all copies or substantial portions of the
+.\" Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+.\" DEALINGS IN THE SOFTWARE.
+.\"
+.\" Copyright 1988, 1989, 1990, 1998  The Open Group
+.\" 
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\" 
+.de EX		\"Begin example
+.ne 5
+.if n .sp 1
+.if t .sp .5
+.nf
+.in +.5i
+..
+.de EE
+.fi
+.in -.5i
+.if n .sp 1
+.if t .sp .5
+..
+.TH XMODMAP 1 "xmodmap 1.0.11" "X Version 11"
+.SH NAME
+xmodmap - utility for modifying keymaps and pointer button mappings in X
+.SH SYNOPSIS
+.B xmodmap
+[-options ...] [filename]
+.SH DESCRIPTION
+.PP
+The \fIxmodmap\fP program is used to edit and display the 
+keyboard \fImodifier map\fP and \fIkeymap table\fP that are used by client 
+applications to convert event keycodes into keysyms.  It is usually run from 
+the user's session startup script to configure the keyboard according to 
+personal tastes.
+.SH OPTIONS
+.PP
+The following options may be used with \fIxmodmap\fP:
+.TP 8
+.B \-display \fIdisplay\fP
+This option specifies the host and display to use.
+.TP 8
+.B \-help
+This option indicates that a brief description of the command line arguments
+should be printed on the standard error channel.  This will be done whenever an
+unhandled argument is given to
+.I xmodmap.
+.TP 8
+.B \-grammar
+This option indicates that a help message describing the expression grammar 
+used in files and with \-e expressions should be printed on the standard error.
+.TP 8
+.B \-version
+This option indicates that
+.I xmodmap
+should print its version information and exit.
+.TP 8
+.B \-verbose
+This option indicates that 
+.I xmodmap
+should print logging information as it parses its input.
+.TP 8
+.B \-quiet
+This option turns off the verbose logging.  This is the default.
+.TP 8
+.B \-n
+This option indicates that 
+.I xmodmap
+should not change the mappings, but should display what it would do, like
+\fImake(1)\fP does when given this option.
+.TP 8
+.B \-e \fIexpression\fB
+This option specifies an expression to be executed.  Any number of expressions
+may be specified from the command line.
+.TP 8
+.B \-pm
+This option indicates that the current modifier map should be printed on the
+standard output.   This is the default mode of operation if no other mode
+options are specified.
+.TP 8
+.B \-pk
+This option indicates that the current keymap table should be printed on the
+standard output.
+.TP 8
+.B \-pke
+This option indicates that the current keymap table should be printed on the
+standard output in the form of expressions that can be fed back to
+\fIxmodmap\fP.
+.TP 8
+.B \-pp
+This option indicates that the current pointer map should be printed on the
+standard output.
+.TP 8
+.B \-
+A lone dash means that the standard input should be used as the input file.
+.PP
+The \fIfilename\fP specifies a file containing \fIxmodmap\fP expressions
+to be executed.  This file is usually kept in the user's home directory with
+a name like \fI.xmodmaprc\fP.
+.SH EXPRESSION GRAMMAR
+.PP
+The
+.I xmodmap
+program reads a list of expressions and parses them all before attempting
+to execute any of them.  This makes it possible to refer to keysyms that are
+being redefined in a natural way without having to worry as much about name
+conflicts.
+.PP
+The list of keysym names may be found in the header file
+\fI<X11/keysymdef.h>\fP (without the \fIXK_\fP prefix).
+Keysyms matching Unicode characters may be specified as "U0020" to "U007E"
+and "U00A0" to "U10FFFF" for all possible Unicode characters.
+.TP 8
+.B keycode \fINUMBER\fP = \fIKEYSYMNAME ...\fP
+The list of keysyms is assigned to the indicated keycode 
+(which may be specified in decimal, hex or octal and can be determined by 
+running the
+.I xev
+program).  Up to eight keysyms may be attached to a key, however the last four
+are not used in any major X server implementation.  The first keysym is used
+when no modifier key is pressed in conjunction with this key, the second with
+Shift, the third when the Mode_switch key is used with this key and the fourth
+when both the Mode_switch and Shift keys are used.
+.TP 8
+.B keycode any = \fIKEYSYMNAME ...\fP
+If no existing key has the specified list of keysyms assigned to it,
+a spare key on the keyboard is selected and the keysyms are assigned to it.
+The list of keysyms may be specified in decimal, hex or octal.
+.TP 8
+.B keysym \fIKEYSYMNAME\fP = \fIKEYSYMNAME ...\fP
+The \fIKEYSYMNAME\fP on the left hand side is translated into matching keycodes
+used to perform the corresponding set of \fBkeycode\fP expressions.  Note that
+if the same keysym is bound to multiple keys, the expression is executed
+for each matching keycode.
+.TP 8
+.B clear \fIMODIFIERNAME\fP
+This removes all entries in the modifier map for the given modifier, where 
+valid name are:
+.BR Shift ,
+.BR Lock ,
+.BR Control ,
+.BR Mod1 ,
+.BR Mod2 ,
+.BR Mod3 ,
+.BR Mod4 ,
+and \fBMod5\fP (case 
+does not matter in modifier names, although it does matter for all other
+names).  For example, ``clear Lock'' will remove
+all any keys that were bound to the shift lock modifier.
+.TP 8
+.B add \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP
+This adds all keys containing the given keysyms to the indicated modifier map.
+The keysym names
+are evaluated after all input expressions are read to make it easy to write
+expressions to swap keys (see the EXAMPLES section).
+.TP 8
+.B remove \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP
+This removes all keys containing the given keysyms from the indicated
+modifier map.  Unlike
+.B add,
+the keysym names are evaluated as the line is read in.  This allows you to
+remove keys from a modifier without having to worry about whether or not they
+have been reassigned.
+.TP 8
+.B "pointer = default"
+This sets the pointer map back to its default settings (button 1 generates a 
+code of 1, button 2 generates a 2, etc.).
+.TP 8
+.B pointer = \fINUMBER ...\fP
+This sets the pointer map to contain the indicated button codes.  The list
+always starts with the first physical button.  Setting a button code to 0
+disables events from that button.
+.PP
+Lines that begin with an exclamation point (!) are taken as comments.
+.PP
+If you want to change the binding of a modifier key, you must also remove it
+from the appropriate modifier map.
+.SH EXAMPLES
+.PP
+Many pointers are designed such that the first button is pressed using the
+index finger of the right hand.  People who are left-handed frequently find
+that it is more comfortable to reverse the button codes that get generated
+so that the primary button is pressed using the index finger of the left hand.
+This could be done on a 3 button pointer as follows:
+.EX
+%  xmodmap -e "pointer = 3 2 1"
+.EE
+.PP
+Many applications support the notion of Meta keys (similar to Control 
+keys except that Meta is held down instead of Control).  However,
+some servers do not have a Meta keysym in the default keymap table, so one
+needs to be added by hand.
+The following command will attach Meta to the Multi-language key (sometimes
+labeled Compose Character).  It also takes advantage of the fact that 
+applications that need a Meta key simply need to get the keycode and don't
+require the keysym to be in the first column of the keymap table.  This
+means that applications that are looking for a Multi_key (including the
+default modifier map) won't notice any change.
+.EX
+%  xmodmap -e "keysym Multi_key = Multi_key Meta_L"
+.EE
+.PP
+Similarly, some keyboards have an Alt key but no Meta key.
+In that case the following may be useful:
+.EX
+%  xmodmap -e "keysym Alt_L = Meta_L Alt_L"
+.EE
+.PP
+One of the more simple, yet convenient, uses of \fIxmodmap\fP is to set the
+keyboard's "rubout" key to generate an alternate keysym.  This frequently
+involves exchanging Backspace with Delete to be more comfortable to the user.
+If the \fIttyModes\fP resource in \fIxterm\fP is set as well, all terminal 
+emulator windows will use the same key for erasing characters:
+.EX
+%  xmodmap -e "keysym BackSpace = Delete"
+%  echo "XTerm*ttyModes:  erase ^?" | xrdb -merge
+.EE
+.PP
+Some keyboards do not automatically generate less than and greater than
+characters when the comma and period keys are shifted.  This can be remedied
+with \fIxmodmap\fP by resetting the bindings for the comma and period with
+the following scripts:
+.EX
+!
+! make shift-, be < and shift-. be >
+!
+keysym comma = comma less
+keysym period = period greater
+.EE
+.PP
+One of the more irritating differences between keyboards is the location of the
+Control and CapsLock keys.  A common use of \fIxmodmap\fP is to swap these
+two keys as follows:
+.EX
+!
+! Swap Caps_Lock and Control_L
+!
+remove Lock = Caps_Lock
+remove Control = Control_L
+keysym Control_L = Caps_Lock
+keysym Caps_Lock = Control_L
+add Lock = Caps_Lock
+add Control = Control_L
+.EE
+.PP
+This example can be run again to swap the keys back to their previous 
+assignments.
+.PP
+The \fIkeycode\fP command is useful for assigning the same keysym to
+multiple keycodes.  Although unportable, it also makes it possible to write
+scripts that can reset the keyboard to a known state.  The following script
+sets the backspace key to generate Delete (as shown above), flushes all 
+existing caps lock bindings, makes the CapsLock
+key be a control key, make F5 generate Escape, and makes Break/Reset be a
+shift lock.
+.EX
+!
+! On the HP, the following keycodes have key caps as listed:
+!
+!     101  Backspace
+!      55  Caps
+!      14  Ctrl
+!      15  Break/Reset
+!      86  Stop
+!      89  F5
+!
+keycode 101 = Delete
+keycode 55 = Control_R
+clear Lock
+add Control = Control_R
+keycode 89 = Escape
+keycode 15 = Caps_Lock
+add Lock = Caps_Lock
+.EE
+.SH ENVIRONMENT
+.PP
+.TP 8
+.B DISPLAY
+to get default host and display number.
+.SH SEE ALSO
+X(7), xev(1), setxkbmap(1),
+XStringToKeysym(3),
+\fIXlib\fP documentation on key and pointer events
+.SH BUGS
+.PP
+Every time a \fBkeycode\fP expression is evaluated, the server generates
+a \fIMappingNotify\fP event on every client.  This can cause some thrashing.
+All of the changes should be batched together and done at once.
+Clients that receive keyboard input and ignore \fIMappingNotify\fP events
+will not notice any changes made to keyboard mappings.
+.PP
+.I Xmodmap
+should generate "add" and "remove" expressions automatically
+whenever a keycode that is already bound to a modifier is changed.
+.PP
+There should be a way to have the
+.I remove
+expression accept keycodes as well as keysyms for those times when you really
+mess up your mappings.
+.SH AUTHOR
+Jim Fulton, MIT X Consortium, rewritten from an earlier version by
+David Rosenthal of Sun Microsystems.
+
diff --git a/upstream/mageia-cauldron/man1/xpmtoppm.1 b/upstream/mageia-cauldron/man1/xpmtoppm.1
new file mode 100644
index 00000000..d00b1b0a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xpmtoppm.1
@@ -0,0 +1,111 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Xpmtoppm User Manual" 0 "31 December 2011" "netpbm documentation"
+
+.SH NAME
+xpmtoppm - convert an X11 pixmap to a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBxpmtoppm\fP
+
+[\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fB-verbose\fP]
+
+[\fIxpmfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBxpbtoppm\fP reads an X11 pixmap (XPM version 1 or 3) as input
+and produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBxpmtoppm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB--alphaout=\fP\fIalpha-filename\fP
+\fBxpmtoppm\fP creates a PBM file containing the transparency
+mask for the image.  If the input image doesn't contain transparency
+information, the \fIalpha-filename\fP file contains all white
+(opaque) transparency values.  If you don't specify \fB--alphaout\fP,
+\fBxpmtoppm\fP does not generate a transparency file, and if the input
+image has transparency information, \fBxpmtoppm\fP simply discards
+it.
+.sp
+If you specify \fB-\fP as the filename, \fBxpmtoppm\fP writes the
+transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+.sp
+\fBxpmtoppm\fP can't handle a line longer than 8K characters in
+the XPM input.  If an input line exceeds this limit,
+\fBxpmtoppm\fP quits with an error message to that effect.  Before
+Netpbm 10.30 (October 2005), the limit was 2K.
+
+.TP
+\fB--verbose\fP
+\fBxpmtoppm\fP prints information about its processing on Standard Error.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+\fBxpmtoppm\fP recognizes only a limited set of the features of XPM
+Version 3; i.e. it rejects as invalid many valid XPM images.
+.PP
+The only place a comment block is valid is starting in Column 1 of the
+line immediately after "static char ...".
+.PP
+In addition, \fBppmtoxpm\fP properly recognizes any single-line
+comment that begins in Column 1 in the color table part of the file.
+.PP
+There must be for every pixel a default colorname for a color type visual.
+.PP
+Before Netpbm 10.58 (March 2012), zero bytes per pixel causes the program
+to fail with a message about premature EOF on input.
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoxpm" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1991 by Jef Poskanzer.
+.PP
+Upgraded to work with XPM version 3 by Arnaud Le
+Hors<\fIlehors@mirsa.inria.fr\fP>,
+Tue Apr 9 1991.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/xpmtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/xrandr.1 b/upstream/mageia-cauldron/man1/xrandr.1
new file mode 100644
index 00000000..da2eb83d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xrandr.1
@@ -0,0 +1,409 @@
+.\"
+.\" Copyright 2001 Keith Packard
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation, and that the name of Keith Packard not be used in
+.\" advertising or publicity pertaining to distribution of the software without
+.\" specific, written prior permission.  Keith Packard makes no
+.\" representations about the suitability of this software for any purpose.  It
+.\" is provided "as is" without express or implied warranty.
+.\"
+.\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+.\" EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+.\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+.\" DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
+.\"
+.TH XRANDR 1 "xrandr 1.5.2" "X Version 11"
+.SH NAME
+xrandr \- primitive command line interface to RandR extension
+.SH SYNOPSIS
+.B "xrandr"
+[\-\-help]  [\-\-display \fIdisplay\fP]
+[\-q] [\-v]
+[\-\-verbose]
+[\-\-dryrun]
+[\-\-screen \fIsnum\fP]
+[\-\-q1]
+[\-\-q12]
+[\-\-current]
+[\-\-noprimary]
+[\-\-panning \fIwidth\fPx\fIheight\fP[+\fIx\fP+\fIy\fP[/\fItrack_width\fPx\fItrack_height\fP+\fItrack_x\fP+\fItrack_y\fP[/\fIborder_left\fP/\fIborder_top\fP/\fIborder_right\fP/\fIborder_bottom\fP]]]]
+[\-\-scale \fIx\fP[x\fIy\fP]]
+[\-\-scale-from \fIw\fPx\fIh\fP]
+[\-\-transform \fIa\fP,\fIb\fP,\fIc\fP,\fId\fP,\fIe\fP,\fIf\fP,\fIg\fP,\fIh\fP,\fIi\fP]
+[\-\-primary]
+[\-\-prop]
+[\-\-fb \fIwidth\fPx\fIheight\fP]
+[\-\-fbmm \fIwidth\fPx\fIheight\fP]
+[\-\-dpi \fIdpi\fP]
+[\-\-dpi \fIfrom-output\fP]
+[\-\-newmode \fIname\fP \fImode\fP]
+[\-\-rmmode \fIname\fP]
+[\-\-addmode \fIoutput\fP \fIname\fP]
+[\-\-delmode \fIoutput\fP \fIname\fP]
+[\-\-output \fIoutput\fP]
+[\-\-auto]
+[\-\-mode \fImode\fP]
+[\-\-preferred]
+[\-\-pos \fIx\fPx\fIy\fP]
+[\-\-rate \fIrate\fP]
+[\-\-reflect \fIreflection\fP]
+[\-\-rotate \fIorientation\fP]
+[\-\-left\-of \fIoutput\fP\]
+[\-\-right\-of \fIoutput\fP\]
+[\-\-above \fIoutput\fP\]
+[\-\-below \fIoutput\fP\]
+[\-\-same-as \fIoutput\fP\]
+[\-\-set \fIproperty\fP \fIvalue\fP]
+[\-\-off]
+[\-\-crtc \fIcrtc\fP]
+[\-\-gamma \fIred\fP[:\fIgreen\fP:\fIblue\fP]]
+[\-\-brightness \fIbrightness\fP]
+[\-o \fIorientation\fP]
+[\-s \fIsize\fP]
+[\-r \fIrate\fP]
+[\-x] [\-y]
+[\-\-listproviders]
+[\-\-setprovideroutputsource \fIprovider\fP \fIsource\fP]
+[\-\-setprovideroffloadsink \fIprovider\fP \fIsink\fP]
+[\-\-listmonitors]
+[\-\-listactivemonitors]
+[\-\-setmonitor \fIname\fP \fIgeometry\fP \fIoutputs\fP]
+[\-\-delmonitor \fIname\fP]
+.SH DESCRIPTION
+.I Xrandr
+is used to set the size, orientation and/or reflection of the outputs for a
+screen. It can also set the screen size.
+
+If invoked without any option, it will dump the state of the outputs,
+showing the existing modes for each of them, with a '+' after the preferred
+modes and a '*' after the current mode.
+
+There are a few global options. Other options modify the last output that is
+specified in earlier parameters in the command line. Multiple outputs may
+be modified at the same time by passing multiple \-\-output options followed
+immediately by their corresponding modifying options.
+.IP \-\-help
+Print out a summary of the usage and exit.
+.IP "\-v, \-\-version"
+Print out the RandR version reported by the X server and exit.
+.IP \-\-verbose
+Causes xrandr to be more verbose. When used with \-q (or without other
+options), xrandr will display more information about the server state. Please
+note that the gamma and brightness information are only approximations of the
+complete color profile stored in the server. When
+used along with options that reconfigure the system, progress will be
+reported while executing the configuration changes.
+.IP "\-q, \-\-query"
+When this option is present, or when no configuration changes are requested,
+xrandr will display the current state of the system.
+.IP "\-\-dryrun"
+Performs all the actions specified except that no changes are made.
+.IP "\-\-nograb"
+Apply the modifications without grabbing the screen. It avoids to block other
+applications during the update but it might also cause some applications that
+detect screen resize to receive old values.
+.IP "\-d, \-\-display \fIname\fP"
+This option selects the X display to use. Note this refers to the X
+screen abstraction, not the monitor (or output).
+.IP "\-\-screen \fIsnum\fP"
+This option selects which screen to manipulate. Note this refers to the X
+screen abstraction, not the monitor (or output).
+.IP \-\-q1
+Forces the usage of the RandR version 1.1 protocol, even if a higher version
+is available.
+.IP \-\-q12
+Forces the usage of the RandR version 1.2 protocol, even if the display does
+not report it as supported or a higher version is available.
+.PP
+.SH "RandR version 1.5 options"
+.PP
+Options for RandR 1.5 are used as a superset of the options for RandR 1.4.
+.PP
+.IP \-\-listmonitors
+Report information about all defined monitors.
+.IP \-\-listactivemonitors
+Report information about currently active monitors.
+.IP "\-\-setmonitor \fIname\fP \fIgeometry\fP \fIoutputs\fP"} {none|\fIoutput\fP,\fIoutput\fP,...}\n"
+Define a new monitor with the given geometry and associated to the given outputs.
+The output list is either the keyword \fBnone\fP or a comma-separated list of outputs.
+The geometry is either the keyword \fBauto\fP, in which case the monitor
+will automatically track the geometry of the associated outputs, or a manual specification
+in the form
+\fIw\fP/\fImmw\fPx\fIh\fP/\fImmh\fP+\fIx\fP+\fIy\fP
+where w, h, x, y are in pixels and mmw, mmh are the physical dimensions of the monitor.
+.IP "\-\-delmonitor \fIname\fP"
+Delete the given user-defined monitor.
+.PP
+.SH "RandR version 1.4 options"
+.PP
+Options for RandR 1.4 are used as a superset of the options for RandR 1.3.
+.IP \-\-listproviders
+Report information about the providers available.
+.IP "\-\-setprovideroutputsource \fIprovider\fP \fIsource\fP"
+Set \fIsource\fP as the source of display output images for \fIprovider\fP.
+This is only possible if \fIsource\fP and \fIprovider\fP have the \fBSource
+Output\fR and \fBSink Output\fR capabilities, respectively.
+If \fIsource\fP is \fB0x0\fP, then \fIprovider\fP is disconnected from its
+current output source.
+.IP "\-\-setprovideroffloadsink \fIprovider\fP \fIsink\fP"
+Set \fIprovider\fP as a render offload device for \fIsink\fP.
+This is only possible if \fIprovider\fP and \fIsink\fP have the \fBSource
+Offload\fR and \fBSink Offload\fR capabilities, respectively.
+If \fIsink\fP is \fB0x0\fP, then \fIprovider\fP is disconnected from its current
+render offload sink.
+.PP
+.SH "RandR version 1.3 options"
+.PP
+Options for RandR 1.3 are used as a superset of the options for RandR 1.2.
+.PP
+.IP \-\-current
+Return the current screen configuration, without polling for hardware changes.
+.IP \-\-noprimary
+Don't define a primary output.
+.PP
+.B "Per-output options"
+.IP "\-\-panning \fIwidth\fPx\fIheight\fP[+\fIx\fP+\fIy\fP[/\fItrack_width\fPx\fItrack_height\fP+\fItrack_x\fP+\fItrack_y\fP[/\fIborder_left\fP/\fIborder_top\fP/\fIborder_right\fP/\fIborder_bottom\fP]]]"
+This option sets the panning parameters.  As soon as panning is
+enabled, the CRTC position can change with every pointer move.
+The first four parameters specify the total panning area, the next four the
+pointer tracking area (which defaults to the same area). The last four
+parameters specify the border and default to 0. A width or height set to zero
+disables panning on the according axis. You typically have to set the screen
+size with \fI--fb\fP simultaneously.
+.IP "\-\-transform \fIa\fP,\fIb\fP,\fIc\fP,\fId\fP,\fIe\fP,\fIf\fP,\fIg\fP,\fIh\fP,\fIi\fP"
+Specifies a transformation matrix to apply on the output.
+A bilinear filter is selected automatically unless the \-\-filter parameter is
+also specified.
+The mathematical form corresponds to:
+.RS
+.RS
+a b c
+.br
+d e f
+.br
+g h i
+.RE
+The transformation is based on homogeneous coordinates. The matrix multiplied
+by the coordinate vector of a pixel of the output gives the transformed
+coordinate vector of a pixel in the graphic buffer.  More precisely, the vector
+.RI "(x y)"
+of the output pixel is extended to 3 values
+.RI "(x y w),"
+with 1 as the w coordinate and multiplied against the matrix. The final device
+coordinates of the pixel are then calculated with the so-called homogenic
+division by the transformed w coordinate.  In other words, the device
+coordinates
+.RI "(x' y')"
+of the transformed pixel are:
+.RS
+x' = (ax + by + c) / w'   and
+.br
+y' = (dx + ey + f) / w'   ,
+.br
+with  w' = (gx + hy + i)  .
+.RE
+Typically, \fIa\fP and
+\fIe\fP corresponds to the scaling on the X and Y axes, \fIc\fP and \fIf\fP
+corresponds to the translation on those axes, and \fIg\fP, \fIh\fP, and \fIi\fP
+are respectively 0, 0 and 1. The matrix can also be used to express more
+complex transformations such as keystone correction, or rotation.  For a
+rotation of an angle T, this formula can be used:
+.RS
+cos T  -sin T   0
+.br
+sin T   cos T   0
+.br
+ 0       0      1
+.RE
+As a special argument, instead of
+passing a matrix, one can pass the string \fInone\fP, in which case the default
+values are used (a unit matrix without filter).
+.RE
+.IP "\-\-filter \fIfiltermode\fP"
+Chooses the scaling filter method to be applied when the screen is scaled or
+transformed.
+Can be either 'bilinear' or 'nearest'.
+.IP "\-\-scale \fIx\fP[x\fIy\fP]"
+Changes the dimensions of the output picture.
+If the \fIy\fP value is omitted, the \fIx\fP value will be used for both dimensions.
+Values larger than 1 lead to a compressed screen (screen dimension bigger
+than the dimension of the output mode), and values less than 1 lead to
+a zoom in on the output.
+This option is actually a shortcut version of the \fI\-\-transform\fP option.
+.IP "\-\-scale-from \fIw\fPx\fIh\fP"
+Specifies the size in pixels of the area of the framebuffer to be displayed on
+this output.
+This option is actually a shortcut version of the \fI\-\-transform\fP option.
+.IP \-\-primary
+Set the output as primary.
+It will be sorted first in Xinerama and RANDR geometry requests.
+.PP
+.SH "RandR version 1.2 options"
+These options are only available for X server supporting RandR version 1.2
+or newer.
+.IP "\-\-prop, \-\-properties"
+This option causes xrandr to display the contents of properties for each
+output. \-\-verbose also enables \-\-prop.
+.IP "\-\-fb \fIwidth\fPx\fIheight\fP"
+Reconfigures the screen to the specified size. All configured monitors must
+fit within this size. When this option is not provided, xrandr computes the
+smallest screen size that will hold the set of configured outputs; this
+option provides a way to override that behaviour.
+.IP "\-\-fbmm \fIwidth\fPx\fIheight\fP"
+Sets the value reported as physical size of the X screen as a whole
+(union of all configured monitors). In configurations with multiple
+monitors with different DPIs, the value has no physical meaning, but
+it may be used by some legacy clients which do not support RandR
+version 1.2 to compute a reference font scaling. Normally,
+xrandr resets the reported physical size values to keep the DPI constant.
+This overrides that computation. Default DPI value is 96.
+.IP "\-\-dpi \fIdpi\fP"
+.IP "\-\-dpi \fIfrom-output\fP"
+This also sets the value reported as physical size of the X screen as a whole
+(union of all configured monitors). In configurations with multiple
+monitors with different DPIs, the value has no physical meaning, but
+it may be used by some legacy clients which do not support RandR
+version 1.2 to compute a reference font scaling. This option uses either
+the specified DPI value, or the DPI of the given output, to compute an appropriate
+physical size using whatever pixel size will be set. Typical values are
+the default (96 DPI), the DPI of the only monitor in single-monitor
+configurations, or the DPI of the primary monitor in multi-monitor
+configurations.
+.IP "\-\-newmode \fIname\fP \fImode\fP"
+New modelines can be added to the server and then associated with outputs.
+This option does the former. The \fImode\fP is specified using the ModeLine
+syntax for xorg.conf: clock hdisp hsyncstart hsyncend htotal vdisp vsyncstart
+vsyncend vtotal \fIflags\fP. \fIflags\fP can be zero or more of +HSync,
+-HSync, +VSync, -VSync, Interlace, DoubleScan, CSync, +CSync, -CSync. Several
+tools permit to compute the usual modeline from a height, width, and refresh
+rate, for instance you can use \fBcvt\fR.
+.IP "\-\-rmmode \fIname\fP"
+This removes a mode from the server if it is otherwise unused.
+.IP "\-\-addmode \fIoutput\fP \fIname\fP"
+Add a mode to the set of valid modes for an output.
+.IP "\-\-delmode \fIoutput\fP \fIname\fP"
+Remove a mode from the set of valid modes for an output.
+.PP
+.B "Per-output options"
+.IP "\-\-output \fIoutput\fP"
+Selects an output to reconfigure. Use either the name of the output or the
+XID.
+.IP \-\-auto
+For connected but disabled outputs, this will enable them using their
+first preferred mode (or, something close to 96dpi if they have no preferred
+mode). For disconnected but enabled outputs, this will disable them.
+.IP "\-\-mode \fImode\fP"
+This selects a mode. Use either the name or the XID for \fImode\fP
+.IP "\-\-preferred"
+This selects the same mode as \-\-auto, but it doesn't automatically enable or
+disable the output.
+.IP "\-\-pos \fIx\fPx\fIy\fP"
+Position the output within the screen using pixel coordinates. In case reflection
+or rotation is applied, the translation is applied after the effects.
+.IP "\-\-rate \fIrate\fP"
+This marks a preference for refresh rates close to the specified value, when
+multiple modes have the same name, this will select the one with the nearest
+refresh rate.
+.IP "\-\-reflect \fIreflection\fP"
+Reflection can be one of 'normal' 'x', 'y' or 'xy'. This causes the output
+contents to be reflected across the specified axes.
+.IP "\-\-rotate \fIrotation\fP"
+Rotation can be one of 'normal', 'left', 'right' or 'inverted'. This causes
+the output contents to be rotated in the specified direction. 'right' specifies
+a clockwise rotation of the picture and 'left' specifies a counter-clockwise
+rotation.
+.IP "\-\-left\-of, \-\-right\-of, \-\-above, \-\-below, \-\-same-as \fIanother-output\fP"
+Use one of these options to position the output relative to the position of
+another output. This allows convenient tiling of outputs within the screen.
+The position is always computed relative to the new position of the other
+output, so it is not valid to say \-\-output a \-\-left\-of b \-\-output
+b \-\-left\-of a.
+.IP "\-\-set \fIproperty\fP \fIvalue\fP"
+Sets an output property. Integer properties may be specified as a valid
+(see \-\-prop) comma-separated list of decimal or hexadecimal (with a leading 0x) values.
+Atom properties may be set to any of the valid atoms (see \-\-prop).
+String properties may be set to any value.
+.IP "\-\-off"
+Disables the output.
+.IP "\-\-crtc \fIcrtc\fP"
+Uses the specified crtc (either as an index in the list of CRTCs or XID).
+In normal usage, this option is not required as xrandr tries to make
+sensible choices about which crtc to use with each output. When that fails
+for some reason, this option can override the normal selection.
+.IP "\-\-gamma \fIred\fP[:\fIgreen\fP:\fIblue\fP]"
+Set the specified floating point values as gamma correction on the crtc
+currently attached to this output.
+If green and blue are not specified, the red value will be used
+for all three components.
+Note that you cannot get two different values
+for cloned outputs (i.e.: which share the same crtc) and that switching an output to another crtc doesn't change
+the crtc gamma corrections at all.
+.IP "\-\-brightness \fIbrightness\fP"
+Multiply the gamma values on the crtc currently attached to the output to
+specified floating value. Useful for overly bright or overly dim outputs.
+However, this is a software only modification, if your hardware has support to
+actually change the brightness, you will probably prefer to use \fBxbacklight\fR.
+.PP
+.SH "RandR version 1.1 options"
+These options are available for X servers supporting RandR version 1.1 or
+older. They are still valid for newer X servers, but they don't interact
+sensibly with version 1.2 options on the same command line.
+.IP "\-s, \-\-size \fIsize-index\fP or \-\-size \fIwidth\fPx\fIheight\fP"
+This sets the screen size, either matching by size or using the index into
+the list of available sizes.
+.IP "\-r, \-\-rate, \-\-refresh \fIrate\fP"
+This sets the refresh rate closest to the specified value.
+.IP "\-o, \-\-orientation \fIrotation\fP"
+This specifies the orientation of the screen,
+and can be one of normal, inverted, left or right.
+.IP \-x
+Reflect across the X axis.
+.IP \-y
+Reflect across the Y axis.
+.SH EXAMPLES
+Sets an output called LVDS to its preferred mode, and on its right put an
+output called VGA to preferred mode of a screen which has been physically rotated clockwise:
+.RS
+xrandr --output LVDS --auto --rotate normal --pos 0x0 --output VGA --auto --rotate left --right-of LVDS
+.RE
+.PP
+Forces to use a 1024x768 mode on an output called VGA:
+.RS
+xrandr --newmode "1024x768" 63.50  1024 1072 1176 1328  768 771 775 798 -hsync +vsync
+.br
+xrandr --addmode VGA 1024x768
+.br
+xrandr --output VGA --mode 1024x768
+.RE
+.PP
+Enables panning on a 1600x768 desktop while displaying 1024x768 mode on an output called VGA:
+.RS
+xrandr --fb 1600x768 --output VGA --mode 1024x768 --panning 1600x0
+.RE
+.PP
+Have one small 1280x800 LVDS screen showing a small version of a huge 3200x2000 desktop, and have a
+big VGA screen display the surrounding of the mouse at normal size.
+.RS
+xrandr --fb 3200x2000 --output LVDS --scale 2.5x2.5 --output VGA --pos 0x0 --panning 3200x2000+0+0/3200x2000+0+0/64/64/64/64
+.RE
+.PP
+Displays the VGA output in trapezoid shape so that it is keystone corrected
+when the projector is slightly above the screen:
+.RS
+xrandr --fb 1024x768 --output VGA --transform 1.24,0.16,-124,0,1.24,0,0,0.000316,1
+.RE
+.SH "SEE ALSO"
+Xrandr(3), cvt(1), xkeystone(1), xbacklight(1)
+.SH AUTHORS
+Keith Packard,
+Open Source Technology Center, Intel Corporation.
+and
+Jim Gettys,
+Cambridge Research Laboratory, HP Labs, HP.
diff --git a/upstream/mageia-cauldron/man1/xrdb.1 b/upstream/mageia-cauldron/man1/xrdb.1
new file mode 100644
index 00000000..16164aad
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xrdb.1
@@ -0,0 +1,324 @@
+.\" Copyright 1991, Digital Equipment Corporation.
+.\" Copyright 1991, 1994, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XRDB 1 "xrdb 1.2.2" "X Version 11"
+.SH NAME
+xrdb - X server resource database utility
+.SH SYNOPSIS
+.B xrdb
+[-option ...] [\fIfilename\fP]
+.SH DESCRIPTION
+.I Xrdb
+is used to get or set the contents of the RESOURCE_MANAGER property
+on the root window of screen 0, or the SCREEN_RESOURCES property on
+the root window of any or all screens, or everything combined.
+You would normally run this program from your X startup file.
+.LP
+Most X clients use the RESOURCE_MANAGER and SCREEN_RESOURCES properties to
+get user preferences about
+color, fonts, and so on for applications.  Having this information in
+the server (where it is available to all clients) instead of on disk,
+solves the problem in previous versions of X that required you to
+maintain \fIdefaults\fP files on every machine that you might use.
+It also allows for dynamic changing of defaults without editing files.
+.LP
+The RESOURCE_MANAGER property is used for resources that apply to all
+screens of the display.  The SCREEN_RESOURCES property on each screen
+specifies additional (or overriding) resources to be used for that screen.
+(When there is only one screen, SCREEN_RESOURCES is normally not used,
+all resources are just placed in the RESOURCE_MANAGER property.)
+.LP
+The file specified by
+.I filename
+(or the contents from standard input if - or no filename is given)
+is optionally passed through the C preprocessor with the
+following symbols defined, based on the capabilities of the server
+being used:
+.TP 8
+.B SERVERHOST=\fIhostname\fP
+the hostname portion of the display to which you are connected.
+.TP 8
+.B SRVR_\fIname\fB
+the SERVERHOST hostname string turned into a legal identifier.
+For example, "my-dpy.lcs.mit.edu" becomes SRVR_my_dpy_lcs_mit_edu.
+.TP 8
+.B HOST=\fIhostname\fP
+the same as
+.BR SERVERHOST .
+.TP 8
+.B DISPLAY_NUM=\fInum\fP
+the number of the display on the server host.
+.TP 8
+.B CLIENTHOST=\fIhostname\fP
+the name of the host on which
+.I xrdb
+is running.
+.TP 8
+.B CLNT_\fIname\fB
+the CLIENTHOST hostname string turned into a legal identifier.
+For example, "expo.lcs.mit.edu" becomes CLNT_expo_lcs_mit_edu.
+.TP 8
+.B RELEASE=\fInum\fP
+the vendor release number for the server.  The interpretation of this
+number will vary depending on VENDOR.
+.TP 8
+.B REVISION=\fInum\fP
+the X protocol minor version supported by this server (currently 0).
+.TP 8
+.B VERSION=\fInum\fP
+the X protocol major version supported by this server (should always be 11).
+.TP 8
+.B VENDOR="\fIvendor\fP"
+a string literal specifying the vendor of the server.
+.TP 8
+.B VNDR_\fIname\fP
+the VENDOR name string turned into a legal identifier.
+For example, "MIT X Consortium" becomes VNDR_MIT_X_Consortium.
+.TP 8
+.B EXT_\fIname\fP
+A symbol is defined for each protocol extension supported by the server.
+Each extension string name is turned into a legal identifier.
+For example, "X3D-PEX" becomes EXT_X3D_PEX.
+.TP 8
+.B NUM_SCREENS=\fInum\fP
+the total number of screens.
+.TP 8
+.B SCREEN_NUM=\fInum\fP
+the number of the current screen (from zero).
+.TP 8
+.B BITS_PER_RGB=\fInum\fP
+the number of significant bits in an RGB color specification.  This is the
+log base 2 of the number of distinct shades of each primary that the hardware
+can generate.  Note that it usually is not related to PLANES.
+.TP 8
+.B CLASS=\fIvisualclass\fP
+one of StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor,
+DirectColor.  This is the visual class of the root window.
+.TP 8
+.B CLASS_\fIvisualclass\fP=\fIvisualid\fP
+the visual class of the root window in a form you can \fI#ifdef\fP on.
+The value is the numeric id of the visual.
+.TP 8
+.B COLOR
+defined only if CLASS is one of StaticColor, PseudoColor, TrueColor, or
+DirectColor.
+.TP 8
+.B CLASS_\fIvisualclass\fP_\fIdepth\fP=\fInum\fP
+A symbol is defined for each visual supported for the screen.
+The symbol includes the class of the visual and its depth;
+the value is the numeric id of the visual.
+(If more than one visual has the same class and depth, the numeric id
+of the first one reported by the server is used.)
+.TP 8
+.B HEIGHT=\fInum\fP
+the height of the root window in pixels.
+.TP 8
+.B WIDTH=\fInum\fP
+the width of the root window in pixels.
+.TP 8
+.B PLANES=\fInum\fP
+the number of bit planes (the depth) of the root window.
+.TP 8
+.B X_RESOLUTION=\fInum\fP
+the x resolution of the screen in pixels per meter.
+.TP 8
+.B Y_RESOLUTION=\fInum\fP
+the y resolution of the screen in pixels per meter.
+.LP
+SRVR_\fIname\fP, CLNT_\fIname\fP, VNDR_\fIname\fP, and EXT_\fIname\fP
+identifiers are formed by changing all characters other than letters
+and digits into underscores (_).
+.LP
+Lines that begin with an exclamation mark (!) are ignored and may
+be used as comments.
+.LP
+Note that since
+.I xrdb
+can read from standard input, it can be used to
+the change the contents of properties directly from
+a terminal or from a shell script.
+.SH "OPTIONS"
+.PP
+.I xrdb
+program accepts the following options:
+.TP 8
+.B \-help
+This option (or any unsupported option) will cause a brief description of
+the allowable options and parameters to be printed.
+.TP 8
+.B \-version
+This option will cause the xrdb version to be printed and the program to exit
+without performing any other operations.
+.TP 8
+.B \-display \fIdisplay\fP
+This option specifies the X server to be used; see \fIX(7)\fP.
+It also specifies the screen to use for the \fI-screen\fP option,
+and it specifies the screen from which preprocessor symbols are
+derived for the \fI-global\fP option.
+.TP 8
+.B \-all
+This option indicates that operation should be performed on the
+screen-independent resource property (RESOURCE_MANAGER), as well as
+the screen-specific property (SCREEN_RESOURCES) on every screen of the
+display.  For example, when used in conjunction with \fI-query\fP,
+the contents of all properties are output.  For \fI-load\fP, \fI-override\fP
+and \fI-merge\fP,
+the input file is processed once for each screen.  The resources which occur
+in common in the output for every screen are collected, and these are applied
+as the screen-independent resources.  The remaining resources are applied
+for each individual per-screen property.  This the default mode of operation.
+.TP 8
+.B \-global
+This option indicates that the operation should only be performed on
+the screen-independent RESOURCE_MANAGER property.
+.TP 8
+.B \-screen
+This option indicates that the operation should only be performed on
+the SCREEN_RESOURCES property of the default screen of the display.
+.TP 8
+.B \-screens
+This option indicates that the operation should be performed on
+the SCREEN_RESOURCES property of each screen of the display.
+For \fI-load\fP, \fI-override\fP and \fI-merge\fP, the input file is
+processed for each screen.
+.TP 8
+.B \-n
+This option indicates that changes to the specified properties (when used with
+\fI-load\fP, \fI-override\fP or \fI-merge\fP)
+or to the resource file (when used with \fI-edit\fP) should be shown on the
+standard output, but should not be performed.
+.TP 8
+.B \-quiet
+This option indicates that warning about duplicate entries should not be
+displayed.
+.TP 8
+.B -cpp \fIfilename\fP
+This option specifies the pathname of the C preprocessor program to be used.
+Although
+.I xrdb
+was designed to use CPP, any program that acts as a filter
+and accepts the -D, -I, and -U options may be used.
+.TP 8
+.B -nocpp
+This option indicates that
+.I xrdb
+should not run the input file through a preprocessor before loading it
+into properties.
+.TP 8
+.B -undef
+This option is passed to the C preprocessor if used. It prevents it from
+predefining any system specific macros.
+.TP 8
+.B \-E
+This option indicates that any cpp command run and the output from it should
+be shown on standard output.  If \fB\-nocpp\fP was also specified, the input
+file will be shown as read.  The specified changes will also be performed
+unless the \fB\-n\fP option is also specified.
+.TP 8
+.B \-symbols
+This option indicates that the symbols that are defined for the preprocessor
+should be printed onto the standard output.
+.TP 8
+.B \-query
+This option indicates that the current contents of the specified
+properties should be printed onto the standard output.  Note that since
+preprocessor commands in the input resource file are part of the input
+file, not part of the property, they won't appear in the output from this
+option.  The
+.B \-edit
+option can be used to merge the contents of properties back into the input
+resource file without damaging preprocessor commands.
+.TP 8
+.B \-get \fIname\fP
+This option indicates that the current content of the property matching
+\fIname\fP should be printed onto the standard output.
+.TP 8
+.B \-load
+This option indicates that the input should be loaded as the new value
+of the specified properties, replacing whatever was there (i.e.
+the old contents are removed).  This is the default action.
+.TP 8
+.B \-override
+This option indicates that the input should be added to, instead of
+replacing, the current contents of the specified properties.
+New entries override previous entries.
+.TP 8
+.B \-merge
+This option indicates that the input should be merged and lexicographically
+sorted with, instead of replacing, the current contents of the specified
+properties.
+.TP 8
+.B \-remove
+This option indicates that the specified properties should be removed
+from the server.
+.TP 8
+.B \-retain
+This option indicates that the server should be instructed not to reset if
+\fIxrdb\fP is the first client.  This should never be necessary under normal
+conditions, since \fIxdm\fP and \fIxinit\fP always act as the first client.
+.TP 8
+.B \-edit \fIfilename\fP
+This option indicates that the contents of the specified properties
+should be edited into the given file, replacing any values already listed
+there.  This allows you to put changes that you have made to your defaults
+back into your resource file, preserving any comments or preprocessor lines.
+.TP 8
+.B \-backup \fIstring\fP
+This option specifies a suffix to be appended to the filename used with
+.B \-edit
+to generate a backup file.
+.TP 8
+.B \-D\fIname[=value]\fP
+This option is passed through to the preprocessor and is used to define
+symbols for use with conditionals such as
+.I #ifdef.
+.TP 8
+.B \-U\fIname\fP
+This option is passed through to the preprocessor and is used to remove
+any definitions of this symbol.
+.TP 8
+.B \-I\fIdirectory\fP
+This option is passed through to the preprocessor and is used to specify
+a directory to search for files that are referenced with
+.I #include.
+.SH FILES
+.I Xrdb
+does not load any files on its own, but many desktop environments use
+xrdb to load \fI~/.Xresources\fP files on session startup to initialize
+the resource database, as a generalized replacement for \fI~/.Xdefaults\fP
+files.
+.SH "SEE ALSO"
+X(7), appres(1), listres(1),
+Xlib Resource Manager documentation, Xt resource documentation
+.SH ENVIRONMENT
+.TP 8
+.B DISPLAY
+to figure out which display to use.
+.SH BUGS
+.PP
+The default for no arguments should be to query, not to overwrite, so that
+it is consistent with other programs.
+.SH AUTHORS
+Bob Scheifler, Phil Karlton, rewritten from the original by Jim Gettys
diff --git a/upstream/mageia-cauldron/man1/xrefresh.1 b/upstream/mageia-cauldron/man1/xrefresh.1
new file mode 100644
index 00000000..548a71be
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xrefresh.1
@@ -0,0 +1,104 @@
+.\" Copyright 1988, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XREFRESH 1 "xrefresh 1.0.7" "X Version 11"
+.SH NAME
+xrefresh - refresh all or part of an X screen
+.SH SYNOPSIS
+.B "xrefresh"
+[-option ...]
+.SH DESCRIPTION
+.PP
+.I Xrefresh
+is a simple X program that causes all or part of your screen to be repainted.
+This is useful when system messages have messed up your screen.
+.I Xrefresh
+maps a window on top of the desired area of the screen and then immediately
+unmaps it,
+causing refresh events to be sent to all applications.  By default,
+a window with no background is used, causing all applications to repaint
+``smoothly.''
+However, the various options can be used to indicate that a solid background
+(of any color) or the root window background should be used instead.
+.SH ARGUMENTS
+.PP
+.TP 10
+.B \-white
+Use a white background.  The screen just appears to flash quickly, and then
+repaint.
+.PP
+.TP 10
+.B \-black
+Use a black background.  This can be somewhat disorienting as everything goes
+black for a moment.
+.PP
+.TP 10
+.B \-solid \fIcolor\fP
+Use a solid background of the specified color.  Try green.
+.PP
+.TP 10
+.B \-root
+Use the root window background.
+.PP
+.TP 10
+.B \-none
+This is the default.  All of the windows simply repaint.
+.PP
+.TP 10
+.B \-geometry \fIWxH+X+Y\fP
+Specifies the portion of the screen to be repainted; see \fIX(7)\fP.
+.PP
+.TP 10
+.B \-display \fIdisplay\fP
+This  argument  allows  you  to  specify the server and screen to
+refresh; see \fIX(7)\fP.
+.PP
+.TP 10
+.B \-version
+This argument prints the program version and exits.
+.SH X DEFAULTS
+The
+.I xrefresh
+program uses the routine
+.I XGetDefault(3)
+to read defaults, so its resource names are all capitalized.
+.PP
+.TP 8
+.B Black\fP, \fBWhite\fP, \fBSolid\fP, \fBNone\fP, \fBRoot\fP
+Determines what sort of window background to use.
+.PP
+.TP 8
+.B Geometry
+Determines the area to refresh.  Not very useful.
+.SH ENVIRONMENT
+.PP
+.TP 8
+DISPLAY - To get default host and display number.
+.SH SEE ALSO
+X(7)
+.SH BUGS
+.PP
+It should have just one default type for the background.
+.SH AUTHORS
+Jim Gettys, Digital Equipment Corp., MIT Project Athena
diff --git a/upstream/mageia-cauldron/man1/xset.1 b/upstream/mageia-cauldron/man1/xset.1
new file mode 100644
index 00000000..1ab13114
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xset.1
@@ -0,0 +1,308 @@
+.\" Copyright 1988, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XSET 1 "xset 1.2.5" "X Version 11"
+.SH NAME
+xset - user preference utility for X
+.SH SYNOPSIS
+.B xset
+[-display \fIdisplay\fP]
+.br
+[-b] [b {on|off}] [b [\fIvolume\fP [\fIpitch\fP [\fIduration\fP]]]]
+.br
+[-bc] [bc]
+.br
+[-c] [c {on|off}] [c [\fIvolume\fP]]
+.br
+[+dpms] [-dpms]
+.br
+	[dpms \fIstandby\fP [\fI suspend\fP [\fI off\fP]]]
+.br
+	[dpms force {standby|suspend|off|on}]
+.br
+[fp=\fIpathlist\fP]
+[-fp=\fIpathlist\fP]
+[+fp=\fIpathlist\fP]
+[fp-\fIpathlist\fP]
+[fp+\fIpathlist\fP]
+.br
+[fp default] [fp rehash]
+.br
+[-led [\fIinteger\fP|named \fIindicator\fP]]
+[led [\fIinteger\fP|named \fIindicator\fP]]
+.br
+[led {on|off}]
+.br
+[mouse [\fIaccel_mult\fP[/\fIaccel_div\fP] [\fIthreshold\fP]]] [mouse default]
+.br
+[p \fIpixel\fP \fIcolor\fP]
+.br
+[-r [keycode]]  [r [keycode]]
+[r {on|off}] [r rate \fIdelay\fP [\fIrate\fP]]
+.br
+[s [\fIlength\fP [\fIperiod\fP]]] [s {blank|noblank}]
+.br
+[s {expose|noexpose}] [s {on|off}] [s default] [s activate] [s reset]
+.br
+[q]
+.br
+[-version]
+.SH DESCRIPTION
+This program is used to set various user preference options of the display.
+.SH OPTIONS
+.PP
+.TP 8
+.B \-display \fIdisplay\fP
+This option specifies the server to use; see \fIX(7)\fP.
+.PP
+.TP 8
+.B b
+The \fBb\fP option controls bell volume, pitch and duration.
+This option accepts up to three numerical parameters, a preceding
+dash(-), or a 'on/off' flag.  If no parameters are
+given, or the 'on' flag is used, the system defaults will be used.
+If the dash or 'off' are given, the bell will be turned
+off.
+If only one numerical parameter is given, the
+bell volume will be set to that value, as a percentage of its maximum.
+Likewise, the second numerical
+parameter specifies the bell pitch, in hertz, and
+the third numerical parameter
+specifies the duration in milliseconds.  Note that not
+all hardware can vary the bell characteristics.  The X server will set
+the characteristics of the bell as closely as it can to the user's
+specifications.
+.PP
+.TP 8
+.B bc
+The \fBbc\fP option controls \fIbug compatibility\fP mode in the server,
+if possible; a preceding dash(-) disables the mode, otherwise the mode
+is enabled.  Various pre-R4 clients pass illegal values in some
+protocol requests, and pre-R4 servers did not correctly generate
+errors in these cases.  Such clients, when run against an R4 server,
+will terminate abnormally or otherwise fail to operate correctly.
+Bug compatibility mode explicitly reintroduces certain bugs into the
+X server, so that many such clients can still be run.  This mode should be
+used with care; new application development should be done with this mode
+disabled.  The server must support the MIT-SUNDRY-NONSTANDARD
+protocol extension in order for this option to work.
+.TP 8
+.B c
+The \fBc\fP option controls key click.
+This option can take an optional value, a preceding dash(-),
+or an 'on/off' flag.
+If no parameter or the 'on' flag is given, the system defaults
+will be used. If the dash or 'off' flag is used, keyclick will be
+disabled.
+If a value from 0 to 100 is given, it is used to
+indicate volume, as a percentage of the maximum.
+The X server will set
+the volume to the nearest value that the hardware can support.
+.PP
+.TP 8
+.B \-dpms
+The \fB\-dpms\fP option disables Display Power Management Signaling (DPMS) features.
+.TP 8
+.B +dpms
+The \fB+dpms\fP option enables Display Power Management Signaling (DPMS) features.
+.TP 8
+.B dpms \fIflags...\fP
+The \fBdpms\fP option allows the Display Power Management Signaling (DPMS)
+parameters to be set.
+The option can take up to three numerical values, or the `force'
+flag followed by a DPMS state.  The `force' flags forces the server
+to immediately switch to the DPMS state specified.  The DPMS state can
+be one of `standby', `suspend', `off', or `on'.  When numerical values are
+given, they set the inactivity period
+(in units of seconds)
+before the three modes are activated.
+The first value given is for the `standby' mode, the second is for the
+`suspend' mode, and the third is for the `off' mode.  Setting these
+values implicitly enables the DPMS features.  A value of zero disables
+a particular mode.
+.TP 8
+.B fp= \fIpath,...\fP
+The \fBfp=\fP sets the font path to the entries given in the path argument.
+The entries are interpreted by the server, not by the client.
+Typically they are directory names or font server names, but the
+interpretation is server-dependent.
+.TP 8
+.B fp \fBdefault\fP
+The \fBdefault\fP argument causes the font path to be reset to the server's
+default.
+.TP 8
+.B fp \fBrehash\fP
+The \fBrehash\fP argument resets the font path to its current value,
+causing the server to reread the font databases in
+the current font path.  This is generally only used when adding new fonts to
+a font directory (after running \fImkfontdir\fP to recreate the font database).
+.PP
+.TP 8
+.B "\-fp \fRor\fP fp\-"
+The \fB\-fp\fP and \fBfp\-\fP options remove elements from the current
+font path.  They must be followed by a comma-separated list of entries.
+.PP
+.TP 8
+.B "\+fp \fRor\fP fp\+"
+This \fB\+fp\fP and \fBfp\+\fP options prepend and append elements to the
+current font path, respectively.  They must be followed by a comma-separated
+list of entries.
+.PP
+.TP 8
+.B led
+The \fBled\fP option controls the keyboard LEDs.
+This controls the turning on or off of one or all of the LEDs.
+It accepts an optional integer, a preceding dash(-) or an 'on/off' flag.
+If no parameter or the 'on' flag is given, all LEDs are turned on.
+If a preceding dash or the flag 'off' is given, all LEDs are turned off.
+If a value between 1 and 32 is given, that LED will be turned on or off
+depending on the existence of a preceding dash.
+``xset led 3'' would turn led #3 on.  ``xset -led 3'' would turn it off.
+The particular LED values may refer to different LEDs on different
+hardware.
+If the X server supports the XKEYBOARD (XKB) extension, leds may be
+referenced by the XKB indicator name by specifying the `named' keyword
+and the indicator name.   For example, to turn on the Scroll Lock LED:
+.IP
+xset led named "Scroll Lock"
+.PP
+.TP 8
+.B mouse
+The \fBm\fP option controls the mouse parameters; it may be
+abbreviated to 'm'. Of course, it applies to most pointing devices, not just
+mice. The parameters for the pointing device are `acceleration' and
+`threshold'. The acceleration can be specified as an integer, or as a simple
+fraction. Threshold is just an integer. The setting is applied to all connected
+pointing devices. xinput(1) should be used if you need device-specific settings.
+.PP
+By default the pointer (the on-screen representation of the pointing device)
+will go `acceleration' times as fast when the device travels more than
+`threshold' mickeys (i.e. would-be pixels) in 10 ms, including a small
+transition range. This way, the pointing device can be used for precise
+alignment when it is moved slowly, yet it can be set to travel across
+the screen in a flick of the wrist when desired.  One or both
+parameters for the
+.B m
+option can be omitted, but if only one is
+given, it will be interpreted as the acceleration.
+If no parameters or the flag 'default' is used, the system defaults will
+be set.
+.PP
+If the `threshold' parameter is provided and 0, the `acceleration'
+parameter will be used in the exponent of a more natural and continuous
+formula, giving precise control for slow motion but big reach for fast
+motion, and a progressive transition for motions in between.
+Recommended `acceleration' value in this case is 3/2 to 3, but not
+limited to that range.
+.PP
+In the X.org X Server 1.6 and above, the behaviour described so far is linked
+to the default profile. There are other profiles (i.e. functions determining
+pointer acceleration from device velocity) and additional settings, so the
+above description may not apply to non-default cases. In the X.org Server 1.7,
+these are available as input device properties (see xinput).
+
+.PP
+.TP 8
+.B p
+The \fBp\fP option controls pixel color values.
+The parameters are the color map entry number in decimal,
+and a color specification.  The root background colors may be changed
+on some servers by altering the entries for BlackPixel and WhitePixel.
+Although these are often 0 and 1, they need not be.  Also, a server may
+choose to allocate those colors privately, in which case an error will
+be generated.  The map entry must not be a read-only color,
+or an error will result.
+.PP
+.TP 8
+.B r
+The \fBr\fP option controls the autorepeat.
+Invoking with "\fB-r\fP", or "\fBr\ off\fP", will disable autorepeat, whereas
+"\fBr\fP", or "\fBr\ on\fP" will enable autorepeat.
+Following the "\fB-r\fP" or "\fBr\fP" option with an integer keycode between 0 and
+255 will disable or enable autorepeat on that key respectively, but only
+if it makes sense for the particular keycode.  Keycodes below 8 are
+not typically valid for this command.  Example: "\fBxset\ -r\ 10\fP" will
+disable autorepeat for the "1" key on the top row of an IBM PC keyboard.
+
+If the server supports the XFree86-Misc extension, or the XKB extension,
+then a parameter
+of 'rate' is accepted and should be followed by zero, one or two numeric
+values. The first specifies the delay before autorepeat starts and
+the second specifies the repeat rate.  In the case that the server
+supports the XKB extension, the delay is the number of milliseconds
+before autorepeat starts, and the rate is the number of repeats
+per second.  If the rate or delay is not given, it will be set
+to the default value.
+.PP
+.TP 8
+.B s
+The \fBs\fP option lets you set the screen saver parameters.
+This option accepts up to two numerical parameters, a 'blank/noblank'
+flag, an 'expose/noexpose' flag, an 'on/off' flag, an 'activate/reset' flag,
+or the 'default' flag.
+If no parameters or the 'default' flag is used, the system will be set
+to its default screen saver characteristics.
+The 'on/off' flags simply turn the screen saver functions on or off.
+The 'activate' flag forces activation of screen saver even if the screen
+saver had been turned off.
+The 'reset' flag forces deactivation of screen saver if it is active.
+The 'blank' flag sets the
+preference to blank the video (if the hardware can do so) rather than
+display a background pattern, while 'noblank' sets the
+preference to display a pattern rather than blank the video.
+The 'expose' flag sets the
+preference to allow window exposures (the server can freely discard
+window contents), while 'noexpose' sets the preference to disable
+screen saver unless the server can regenerate the screens without
+causing exposure events.
+The length and period
+parameters for the screen saver function determines how long the
+server must be inactive for screen saving to activate, and the period
+to change the background pattern to avoid burn in.
+The arguments are specified in seconds.
+If only one numerical parameter is given, it will be used for the length.
+.PP
+.TP 8
+.B q
+The \fBq\fP option gives you information on the current settings.
+.PP
+.TP 8
+.B -version
+The \fB-version\fP option prints the program version and exits without
+doing anything else.
+.PP
+These settings will be reset to default values when you log out.
+.PP
+Note that not all X implementations are guaranteed to honor all of these
+options.
+.SH "SEE ALSO"
+X(7), Xserver(1), xmodmap(1), xrdb(1), xsetroot(1), xinput(1)
+.SH AUTHOR
+Bob Scheifler, MIT Laboratory for Computer Science
+.br
+David Krikorian, MIT Project Athena (X11 version)
+.br
+XFree86-Misc support added by David Dawes and Joe Moss
+.br
+Manpage updates added by Mike A. Harris <mharris@redhat.com>
diff --git a/upstream/mageia-cauldron/man1/xsetroot.1 b/upstream/mageia-cauldron/man1/xsetroot.1
new file mode 100644
index 00000000..016a03c8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xsetroot.1
@@ -0,0 +1,123 @@
+.\" Copyright 1988, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XSETROOT 1 "xsetroot 1.1.3" "X Version 11"
+.SH NAME
+xsetroot \- root window parameter setting utility for X
+.SH SYNOPSIS
+.B xsetroot
+[-help]
+[-version]
+[-def]
+[-display \fIdisplay\fP]
+[-cursor \fIcursorfile maskfile\fP]
+[-cursor_name \fIcursorfontname\fP]
+[-xcf \fIcursorfile\fP \fIcursorsize\fP]
+[-bitmap \fIfilename\fP
+| -mod \fIx y\fP
+| -gray
+| -grey
+| -solid \fIcolor\fP]
+[-bg \fIcolor\fP]
+[-fg \fIcolor\fP]
+[-rv]
+[-name \fIstring\fP]
+[-d \fIdisplay\fP]
+.SH DESCRIPTION
+The
+.I xsetroot
+program
+allows you to tailor the appearance of the background ("root")
+window on a workstation display running X.  Normally, you experiment with
+.I xsetroot
+until you find a personalized look that you like, then put the
+.I xsetroot
+command that produces it into your X startup file.
+If no options are specified, or if
+.I -def
+is specified, the window is reset to its default state.  The
+.I -def
+option can be specified along with other options and only the non-specified
+characteristics will be reset to the default state.
+.PP
+Only one of the background color/tiling changing options
+(-solid, -gray, -grey, -bitmap, and -mod) may be specified at a time.
+.SH OPTIONS
+.PP
+The various options are as follows:
+.IP "\fB-help\fP"
+Print a usage message and exit.
+.IP "\fB-version\fP"
+Print a version message and exit.
+.IP "\fB-def, -default\fP"
+Reset unspecified attributes to the default values.  (Restores the background
+to the familiar gray mesh and the cursor to the hollow x shape.)
+.IP "\fB-cursor\fP \fIcursorfile\fP \fImaskfile\fP"
+This lets you change the pointer cursor to whatever
+you want when the pointer cursor is outside of any window.
+Cursor and mask files are bitmaps (little pictures), and can be made with the
+.I bitmap(1)
+program.  You probably want the mask file to be all black until you
+get used to the way masks work.
+.IP "\fB-cursor_name\fP \fIcursorfontname\fP"
+This lets you change the pointer cursor to one of the standard
+cursors from the cursor font.  Refer to appendix B of the X protocol for
+the names (except that the XC_ prefix is elided for this option).
+.IP "\fB-xcf\fP \fIcursorfile\fP \fIcursorsize\fP"
+This lets you change the pointer cursor to one loaded from an Xcursor file
+as defined by libXcursor, at the specified size.
+.IP "\fB-bitmap\fP \fIfilename\fP"
+Use the bitmap specified in the file to set the window pattern.  You can
+make your own bitmap files (little pictures) using the
+.I bitmap(1)
+program.  The entire background will be made up of repeated "tiles" of
+the bitmap.
+.IP "\fB-mod\fP \fIx\fP \fIy\fP"
+This is used if you want a plaid-like grid pattern on your screen.
+x and y are integers ranging from 1 to 16.  Try the different combinations.
+Zero and negative numbers are taken as 1.
+.IP "\fB-gray, -grey\fP"
+Make the entire background gray (Easier on the eyes).
+.IP "\fB-bg, -background\fP \fIcolor\fP"
+Use ``color'' as the background color.
+.IP "\fB-fg, -foreground\fP \fIcolor\fP"
+Use ``color'' as the foreground color.  Foreground and background colors
+are meaningful only in combination with -cursor, -bitmap, or -mod.
+.IP "\fB-rv, -reverse\fP"
+This exchanges the foreground and background colors.  Normally the foreground
+color is black and the background color is white.
+.IP "\fB-solid\fP \fIcolor\fP"
+This sets the background of the root window to the specified color.  This
+option is only useful on color servers.
+.IP "\fB-name\fP \fIstring\fP"
+Set the name of the root window to ``string''.  There is no default value.
+Usually a name is assigned to a window so that the
+window manager can use a text representation when the window is iconified.
+This option is unused since you can't iconify the background.
+.IP "\fB-d, -display\fP \fIdisplay\fP"
+Specifies the server to connect to; see \fIX(7)\fP.
+.SH "SEE ALSO"
+X(7), xset(1), xrdb(1), Xcursor(3)
+.SH AUTHOR
+Mark Lillibridge, MIT Project Athena
diff --git a/upstream/mageia-cauldron/man1/xsubpp.1 b/upstream/mageia-cauldron/man1/xsubpp.1
new file mode 100644
index 00000000..344cfdaa
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xsubpp.1
@@ -0,0 +1,167 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "XSUBPP 1"
+.TH XSUBPP 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+xsubpp \- compiler to convert Perl XS code into C code
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBxsubpp\fR [\fB\-v\fR] [\fB\-except\fR] [\fB\-s pattern\fR] [\fB\-prototypes\fR] [\fB\-noversioncheck\fR] [\fB\-nolinenumbers\fR] [\fB\-nooptimize\fR] [\fB\-typemap typemap\fR] [\fB\-output filename\fR]... file.xs
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This compiler is typically run by the makefiles created by ExtUtils::MakeMaker
+or by Module::Build or other Perl module build tools.
+.PP
+\&\fIxsubpp\fR will compile XS code into C code by embedding the constructs
+necessary to let C functions manipulate Perl values and creates the glue
+necessary to let Perl access those functions.  The compiler uses typemaps to
+determine how to map C function parameters and variables to Perl values.
+.PP
+The compiler will search for typemap files called \fItypemap\fR.  It will use
+the following search path to find default typemaps, with the rightmost
+typemap taking precedence.
+.PP
+.Vb 1
+\&        ../../../typemap:../../typemap:../typemap:typemap
+.Ve
+.PP
+It will also use a default typemap installed as \f(CW\*(C`ExtUtils::typemap\*(C'\fR.
+.SH OPTIONS
+.IX Header "OPTIONS"
+Note that the \f(CW\*(C`XSOPT\*(C'\fR MakeMaker option may be used to add these options to
+any makefiles generated by MakeMaker.
+.IP \fB\-hiertype\fR 5
+.IX Item "-hiertype"
+Retains '::' in type names so that C++ hierarchical types can be mapped.
+.IP \fB\-except\fR 5
+.IX Item "-except"
+Adds exception handling stubs to the C code.
+.IP "\fB\-typemap typemap\fR" 5
+.IX Item "-typemap typemap"
+Indicates that a user-supplied typemap should take precedence over the
+default typemaps.  This option may be used multiple times, with the last
+typemap having the highest precedence.
+.IP "\fB\-output filename\fR" 5
+.IX Item "-output filename"
+Specifies the name of the output file to generate.  If no file is
+specified, output will be written to standard output.
+.IP \fB\-v\fR 5
+.IX Item "-v"
+Prints the \fIxsubpp\fR version number to standard output, then exits.
+.IP \fB\-prototypes\fR 5
+.IX Item "-prototypes"
+By default \fIxsubpp\fR will not automatically generate prototype code for
+all xsubs. This flag will enable prototypes.
+.IP \fB\-noversioncheck\fR 5
+.IX Item "-noversioncheck"
+Disables the run time test that determines if the object file (derived
+from the \f(CW\*(C`.xs\*(C'\fR file) and the \f(CW\*(C`.pm\*(C'\fR files have the same version
+number.
+.IP \fB\-nolinenumbers\fR 5
+.IX Item "-nolinenumbers"
+Prevents the inclusion of '#line' directives in the output.
+.IP \fB\-nooptimize\fR 5
+.IX Item "-nooptimize"
+Disables certain optimizations.  The only optimization that is currently
+affected is the use of \fItarget\fRs by the output C code (see perlguts).
+This may significantly slow down the generated code, but this is the way
+\&\fBxsubpp\fR of 5.005 and earlier operated.
+.IP \fB\-noinout\fR 5
+.IX Item "-noinout"
+Disable recognition of \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT_LIST\*(C'\fR and \f(CW\*(C`INOUT_LIST\*(C'\fR declarations.
+.IP \fB\-noargtypes\fR 5
+.IX Item "-noargtypes"
+Disable recognition of ANSI-like descriptions of function signature.
+.IP \fB\-C++\fR 5
+.IX Item "-C++"
+Currently doesn't do anything at all.  This flag has been a no-op for
+many versions of perl, at least as far back as perl5.003_07.  It's
+allowed here for backwards compatibility.
+.IP "\fB\-s=...\fR or \fB\-strip=...\fR" 5
+.IX Item "-s=... or -strip=..."
+\&\fIThis option is obscure and discouraged.\fR
+.Sp
+If specified, the given string will be stripped off from the beginning
+of the C function name in the generated XS functions (if it starts with that prefix).
+This only applies to XSUBs without \f(CW\*(C`CODE\*(C'\fR or \f(CW\*(C`PPCODE\*(C'\fR blocks.
+For example, the XS:
+.Sp
+.Vb 1
+\&  void foo_bar(int i);
+.Ve
+.Sp
+when \f(CW\*(C`xsubpp\*(C'\fR is invoked with \f(CW\*(C`\-s foo_\*(C'\fR will install a \f(CW\*(C`foo_bar\*(C'\fR
+function in Perl, but really call \f(CWbar(i)\fR in C. Most of the time,
+this is the opposite of what you want and failure modes are somewhat
+obscure, so please avoid this option where possible.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+No environment variables are used.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Originally by Larry Wall.  Turned into the \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR module
+by Ken Williams.
+.SH "MODIFICATION HISTORY"
+.IX Header "MODIFICATION HISTORY"
+See the file \fIChanges\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1), \fBperlxs\fR\|(1), \fBperlxstut\fR\|(1), ExtUtils::ParseXS
diff --git a/upstream/mageia-cauldron/man1/xvidtune.1 b/upstream/mageia-cauldron/man1/xvidtune.1
new file mode 100644
index 00000000..76c4f423
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xvidtune.1
@@ -0,0 +1,184 @@
+.\" $XFree86: xc/programs/xvidtune/xvidtune.man,v $
+.\"
+.\" Copyright (c) 1995  Kaleb S. KEITHLEY
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL Kaleb S. KEITHLEY BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of Kaleb S. KEITHLEY shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from Kaleb S. KEITHLEY.
+.\"
+.TH xvidtune 1 "xvidtune 1.0.4" "X Version 11"
+.SH NAME
+xvidtune \- video mode tuner for Xorg
+.SH SYNOPSIS
+.B xvidtune
+[
+.B -show
+|
+.B -prev
+|
+.B -next
+|
+.B -unlock
+|
+.B -timeout
+.I sec
+] [
+.I \-toolkitoption
+\&.\|.\|. ]
+.SH DESCRIPTION
+Xvidtune is a client interface to the X server video mode
+extension (XFree86-VidModeExtension).
+.PP
+When given one of the non-toolkit options, xvidtune provides
+a command line interface to either print or switch the video mode.
+.PP
+Without any options (or with only toolkit options) it
+presents the user with various buttons and sliders that can be
+used to interactively adjust existing video modes.
+It will also print the settings in a format suitable for inclusion
+in an xorg.conf file.
+.PP
+Normally the Xorg X servers only allow changes to be made with
+the XFree86-VidModeExtension from clients connected via a local
+connection type.
+.PP
+Note:  The original mode settings can be restored by pressing the `R' key,
+and this can be used to restore a stable screen in situations where the
+screen becomes unreadable.
+.PP
+The available buttons are:
+.PP
+.nf
+.B Left
+.B Right
+.B Up
+.B Down
+.fi
+.RS 10
+Adjust the video mode so that the display will be moved in the
+appropriate direction.
+.RE
+.PP
+.nf
+.B Wider
+.B Narrower
+.B Shorter
+.B Taller
+.fi
+.RS 10
+Adjust the video mode so that the display size is altered
+appropriately.
+.RE
+.TP 10
+.B Quit
+Exit the program.
+.TP 10
+.B Apply
+Adjust the current video mode to match the selected settings.
+.TP 10
+.B Auto
+Cause the Up/Down/Right/Left, Wider/Narrower/Shorter/Taller, Restore,
+and the special S3 buttons to be applied immediately.
+This button can be toggled.
+.TP 10
+.B Test
+Temporarily switch to the selected settings.
+.TP 10
+.B Restore
+Return the settings to their original values.
+.TP 10
+.B Fetch
+Query the server for its current settings.
+.TP 10
+.B Show
+Print the currently selected settings to stdout in xorg.conf
+"Modeline" format.  The primary selection is similarly set.
+.TP 10
+.B Next
+Switch the Xserver to the next video mode.
+.TP 10
+.B Prev
+Switch the Xserver to the previous video mode.
+.PP
+For some S3-based cards (964 and 968) the following are also available:
+.TP 10
+.B InvertVCLK
+Change the VCLK invert/non-invert state.
+.TP 10
+.B EarlySC
+Change the Early SC state.  This affects screen wrapping.
+.PP
+.nf
+.B BlankDelay1
+.B BlankDelay2
+.fi
+.RS 10
+Set the blank delay values.  This affects screen wrapping.  Acceptable
+values are in the range 0\-7.  The values may be incremented or decremented
+with the `+' and `-' buttons, or by pressing the `+' or `-' keys in the
+text field.
+.RE
+.PP
+For S3-864/868 based cards \fIInvertVCLK\fP and \fIBlankDelay1\fP may
+be useful.  For S3 Trio32/Trio64 cards only \fIInvertVCLK\fP is available.
+At the moment there are no default settings available for these chips
+in the video mode extension and thus this feature is disabled in xvidtune.
+It can be enabled by setting any of the optional S3 commands in the
+screen section of xorg.conf, e.g. using
+.RS 10
+.B blank_delay \fI"\(**"\fP 0
+.RE
+.SH OPTIONS
+\fIxvidtune\fP accepts the standard X Toolkit command line options as well
+as the following:
+.TP 10
+.B \-show
+Print the current settings to stdout in xorg.conf
+"Modeline" format and exit.
+.TP 10
+.B \-prev
+Switch the Xserver to the previous video mode.
+.TP 10
+.B \-next
+Switch the Xserver to the next video mode.
+.TP 10
+.B \-unlock
+Normally, \fIxvidtune\fP will disable the switching of video modes
+via hot-keys while it is running.  If for some reason the program
+did not exit cleanly and they are still disabled, the program can
+be re-run with this option to re-enable the mode switching key
+combinations.
+.TP 10
+.B \-timeout \fIsec\fP
+Set testmode timeout in seconds.
+.SH SEE ALSO
+.BR xrandr (1),
+.BR Xorg (1),
+.BR xorg.conf (5).
+.SH AUTHORS
+Kaleb S. Keithley, X Consortium.
+.br
+Additions and modifications by Jon Tombs, David Dawes, and Joe Moss.
+.SH BUGS
+X Error handling, i.e. when the server does not allow xvidtune
+clients to write new modes, could be better.
diff --git a/upstream/mageia-cauldron/man1/xvminitoppm.1 b/upstream/mageia-cauldron/man1/xvminitoppm.1
new file mode 100644
index 00000000..3e7a91a0
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xvminitoppm.1
@@ -0,0 +1,63 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Xvminitoppm User Manual" 0 "02 April 2006" "netpbm documentation"
+
+.SH NAME
+
+xvminitoppm - convert an XV "thumbnail" picture to PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBxvminitoppm\fP
+
+[\fIxvminipic\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBxvminittoppm\fP reads an XV "thumbnail" picture (a
+miniature picture generated by the "VisualSchnauzer"
+browser) as input and produces a PPM image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBxvminitoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtoxvmini" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&, 
+\fBxv\fP manual
+
+.UN history
+.SH HISTORY
+.PP
+A program of this name was written in 1993 by Ingo Wilken and was
+part of Netpbm until Release 10.34 (April 2006).  At that time, it was
+replaced in Netpbm by the current program, which was written by Bryan
+Henderson.  The function of the newer program is identical to that of
+the older one; the reason for the replacement is that the newer one is
+easier to maintain.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/xvminitoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/xwd.1 b/upstream/mageia-cauldron/man1/xwd.1
new file mode 100644
index 00000000..6904f68b
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xwd.1
@@ -0,0 +1,140 @@
+.\" Copyright 1988, 1994, 1998  The Open Group
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.\"
+.TH XWD 1 "xwd 1.0.9" "X Version 11"
+.SH NAME
+xwd - dump an image of an X window
+.SH SYNOPSIS
+.B "xwd"
+[-debug] [-help] [-nobdrs] [-out \fIfile\fP] [-xy] [-frame] [-add \fIvalue\fP]
+[-root | -id \fIwdid\fP | -name \fIwdname\fP ] [-icmap] [-screen] [-silent]
+[-display \fIhost:dpy\fP] [-version]
+.SH DESCRIPTION
+.PP
+.I Xwd
+is an X Window System window dumping utility.
+.I Xwd
+allows X users to store window images in a specially formatted dump
+file.  This file can then be read by various other X utilities for
+redisplay, printing, editing, formatting, archiving, image processing, etc.
+The target window is selected by clicking the pointer in the desired window.
+The keyboard bell is rung once at the beginning of the dump and twice when
+the dump is completed.
+.SH OPTIONS
+.PP
+.TP 8
+.B "-debug"
+Enable debug mode.
+.PP
+.TP 8
+.B "-d, -display \fIhost:dpy\fP"
+This argument allows you to specify the server to connect to; see \fIX(7)\fP.
+.PP
+.TP 8
+.B "-help"
+Print out the `Usage:' command syntax summary.
+.PP
+.TP 8
+.B "-nobdrs"
+This argument specifies that the window dump should not include the
+pixels that compose the X window border.  This is useful in situations
+where you may wish to include the window contents in a document
+as an illustration.
+.PP
+.TP 8
+.B "-out \fIfile\fP"
+This argument allows the user to explicitly specify the output
+file on the command line.  The default is to output to standard out.
+.PP
+.TP 8
+.B "-xy"
+This option applies to color displays only. It selects `XY' format dumping
+instead of the default `Z' format.
+.PP
+.TP 8
+.B "-add \fIvalue\fP"
+This option specifies a signed value to be added to every pixel.
+.PP
+.TP 8
+.B "-frame"
+This option indicates that the window manager frame should be included when
+manually selecting a window.
+.PP
+.TP 8
+.B "-root"
+This option indicates that the root window should be selected for the
+window dump, without requiring the user to select a window with the pointer.
+.PP
+.TP 8
+.B "-id \fIwdid\fP"
+This option indicates that the window with the specified resource id
+should be selected for the window dump, without requiring the user to
+select a window with the pointer.
+.PP
+.TP 8
+.B "-name \fIwdname\fP"
+This option indicates that the window with the specified WM_NAME property
+should be selected for the window dump, without requiring the user to
+select a window with the pointer.
+.PP
+.TP 8
+.B "-icmap"
+Normally the colormap of the chosen window is used to obtain RGB values.
+This option forces the first installed colormap of the screen to be used
+instead.
+.PP
+.TP 8
+.B "-screen"
+This option indicates that the GetImage request used to obtain the image
+should be done on the root window, rather than directly on the specified
+window.  In this way, you can obtain pieces of other windows that overlap
+the specified window, and more importantly, you can capture menus or other
+popups that are independent windows but appear over the specified window.
+.PP
+.TP 8
+.B "-silent"
+Operate silently, i.e. don't ring any bells before and after dumping
+the window.
+.PP
+.TP 8
+.B "-version"
+This option indicates that
+.I xwd
+should print its version information and exit.
+.SH ENVIRONMENT
+.PP
+.TP 8
+.B DISPLAY
+To get default host and display number.
+.SH FILES
+.PP
+.TP 8
+.B XWDFile.h
+X Window Dump File format definition file.
+.SH SEE ALSO
+xwud(1), X(7)
+.SH AUTHORS
+Tony Della Fera, Digital Equipment Corp., MIT Project Athena
+.br
+William F. Wyatt, Smithsonian Astrophysical Observatory
diff --git a/upstream/mageia-cauldron/man1/xwdtopnm.1 b/upstream/mageia-cauldron/man1/xwdtopnm.1
new file mode 100644
index 00000000..fa6ebb42
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/xwdtopnm.1
@@ -0,0 +1,144 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Xwdtopnm User Manual" 0 "08 January 2010" "netpbm documentation"
+
+.SH NAME
+xwdtopnm - convert an X11 or X10 window dump file to a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBxwdtopnm\fP
+[\fB-verbose\fP]
+[\fB-headerdump\fP]
+[\fIxwdfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBxwdtopnm\fP reads an X11 or X10 window dump file as input and
+produces a PNM image as output.  The type of the output image depends
+on the input file - if it's black and white, the output is PBM.  If
+it's grayscale, the output is PGM.  Otherwise, it's PPM.  The program
+tells you which type it is writing.
+.PP
+Using this program, you can convert anything you can display on an
+X workstation's screen into a PNM image.  Just display whatever you're
+interested in, run the \fBxwd\fP program to capture the contents of
+the window, run it through \fBxwdtopnm\fP, and then use \fBpamcut\fP
+to select the part you want.
+.PP
+Note that a pseudocolor XWD image (typically what you get when you
+make a dump of a pseudocolor X window) has maxval 65535, which means
+the PNM file that \fBxwdtopnm\fP generates has maxval 65535.  Many
+older image processing programs (that aren't part of the Netpbm
+package and don't use the Netpbm programming library) don't know how
+to handle a PNM image with maxval greater than 255 (because there are
+two bytes instead of one for each sample in the image).  So you may
+want to run the output of \fBxwdtopnm\fP through \fBpamdepth\fP
+before feeding it to one of these old programs.
+.PP
+\fBxwdtopnm\fP can't convert every kind of XWD image (which essentially
+means it can't convert an XWD created from every kind of X display
+configuration).  In particular, it cannot convert one with more than 24 bits
+per pixel.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBxwdtopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+This option causes \fBxwdtopnm\fP to display handy information about the
+input image and the conversion process
+
+.TP
+\fB-headerdump\fP
+This option causes \fBxwdtopnm\fP to display the contents of the
+X11 header.  It has no effect when the input is X10.  This option was
+new in Netpbm 10.26 (December 2004).
+
+
+
+.UN notes
+.SH NOTES
+
+.UN twobytesamples
+.SS Two Byte Samples
+.PP
+\fBxwdtopnm\fP sometimes produces output with a maxval greater than 255,
+which means the maximum value of a sample (one intensity value, e.g. the
+red component of a pixel) is greater than 255 and therefore each sample
+takes 2 bytes to represent.  This can be a problem because some programs
+expect those bytes in a different order from what the Netpbm format specs
+say, which is what \fBxwdtopnm\fP produces, which means they will see totally
+different colors than they should.   \fBxv\fP is one such program.
+.PP
+If this is a problem (e.g. you want to look at the output of \fBxwdtopnm\fP
+with \fBxv\fP), there are two ways to fix it:
+
+
+.IP \(bu
+Pass the output through \fBpamendian\fP to produce the format the
+program expects.
+.IP \(bu
+Pass the output through \fBpamdepth\fP to reduce the maxval below 256
+so there is only one byte per sample.
+
+.PP
+Often, there is no good reason to have a maxval greater than 255.  It
+happens because in XWD, but not PNM, each color component of a pixel can have
+different resolution, for example 5 bits for blue (maxval 31), 5 bits for red
+(maxval 31), and 6 bits for green (maxval 63), for a total of 16 bits per
+pixel.  In order to reproduce the colors as closely as possible,
+\fBxwdtopnm\fP has to use a large maxval.  In this example, it would use
+31 * 63 = 1953, and use 48 bits per pixel.
+.PP
+Because this is a common and frustrating problem when using \fBxwdtopnm\fP,
+the program issues a warning whenever it generates output with two byte
+samples.  You can quiet this warning with the \fB-quiet\fP 
+.UR index.html#commonoptions
+common option
+.UE
+\&.  The warning was new in Netpbm 10.46
+(March 2009).
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtoxwd" (1)\c
+\&,
+.BR "pamendian" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBxwd\fP man page
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/xwdtopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/yacc.1 b/upstream/mageia-cauldron/man1/yacc.1
new file mode 100644
index 00000000..d911bf88
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yacc.1
@@ -0,0 +1,41 @@
+.TH YACC "1" "November 2007" "GNU Bison 3.8.2" "User Commands"
+.SH NAME
+yacc \- GNU Project parser generator
+.SH SYNOPSIS
+.B yacc
+[\fIOPTION\fR]... \fIFILE\fR
+.SH DESCRIPTION
+.I Yacc
+(Yet Another Compiler Compiler) is a parser generator.  This
+version is a simple wrapper around
+.IR bison (1).
+It passes option
+\fB\-y\fR, \fB\-\-yacc\fR
+to activate the upward compatibility mode.  See
+.IR bison (1)
+for more information.
+.SH AUTHOR
+Written by Paul Eggert.
+.SH "REPORTING BUGS"
+Report bugs to <bug-bison@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2021 Free Software Foundation, Inc.
+.br
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.BR lex (1),
+.BR flex (1),
+.BR bison (1).
+.PP
+The full documentation for
+.B bison
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B bison
+programs are properly installed at your site, the command
+.IP
+.B info bison
+.PP
+should give you access to the complete manual.
diff --git a/upstream/mageia-cauldron/man1/yaps.1 b/upstream/mageia-cauldron/man1/yaps.1
new file mode 100644
index 00000000..eaed22fb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yaps.1
@@ -0,0 +1,201 @@
+.TH YAPS 1 "13 August 2005"
+.SH NAME
+.B
+YAPS
+\- converts an abc file to a PostScript file
+.SH SYNOPSIS
+yaps \fiabc\ file\fP [\-d] [\-e\ <list>] [\-E] [\-l] [\-M \fiXXXxYYY\fP] \
+[\-N] [\-k nn] [\-o \fifile\ name\fP] [\-P \-\fiss\fP] [\-s \fiXX\fP] [\-V]\
+[\-ver] [\-x] [\-OCC]
+
+
+
+.SH OPTIONS
+.TP
+.B -d
+For debugging only. Displays the internal data structures used in the program.
+.TP
+.B -e \fi<list>\fP
+Draws tunes with reference numbers in a comma separated list. Spaces are
+not allowed but a range of reference numbers can be specified. For example,
+1,3,7-10.
+.TP
+.B -E
+Generates Encapsulated Postscript output.
+.TP
+.B -M \fiXXXxYYY\fb
+Set margin sizes in points where 28.3 points = 1cm and 72 points = 1 inch.
+.TP
+.B -N
+Adds page numbering.
+.TP
+.B -k [nn]
+Adds bar numbering. If number nn is included, then every nn'th bar
+is numbered. Otherwise all bars are numbered.
+.TP
+.B -o \fifilename\fP 
+Specifies the output postscript file name.
+.TP
+.B -P \fiss\fP
+Specifies the paper size where 0 is A4 and 1 is US Letter
+or XXXxYYY sets the paper size in point units.
+ units.
+.TP
+.B  -s \fiXX\fP
+Specifies the scaling factor (default is 0.7)
+.TP
+.B -V
+Voices are printed out separately for a multi-voice tune. Otherwise they
+ are interleaved.
+
+.TP
+.B -ver
+Prints version number and exits.
+.TP
+.B  -x
+Print tune number in X: field
+.TP
+.B -OCC
+Required if the tune uses the old convention for chords delineated
+with +..+ instead of [...].
+
+.SH FEATURES
+
+.PP
+* Uses the abc2midi parsing code, so hopefully compatibility with
+abc2midi will be good.
+.PP
+* Measures the width of lyric text for lyric typesetting.
+.PP
+* Uses dynamically extensible data structures in most places, so
+you should not be restricted by compiled-in limits.
+.PP
+* Multiple voices drawn with notes played at the same time aligned.
+.PP
+* Supports special characters using ISO latin 1 font. Special
+characters are created with a TeX-like code e.g. \'E or a 3 digit octal
+code e.g. \315 .
+.PP
+* Supports the following clefs : baritone, tenor, alto, mezzo, soprano,
+treble, bass. Recommended use is
+.PP
+* Invisible rests (x) are displayed like normal rests.
+.PP
+* Nonnumeric voice id's, eg. V: soprano are accepted.
+.PP
+  I:clef=bass
+.PP
+To make it easier to enter tunes in clefs othan than treble clef,
+yaps supports I:octave=-1 to indicate that a C in the tune represents
+the note one octave below the pitch defined in the abc standard. These
+may be combined in one I: statement e.g.
+.PP
+I:clef=bass octave=-2
+.PP
+You can also use clefs that are one, two or three octaves higher or
+lower than normal using e.g. treble-8, treble+15, treble-22. The clef is
+drawn with a small 8, 15 or 22 above or below the clef symbol. The clef=
+and octave= commands may also go in the K: field e.g.
+.PP
+K:G clef=bass-8 octave=-3
+.PP
+Note that there is an incompatibility between the behaviour of yaps and
+the behaviour of abc2ps 1.3.3. abc2ps 1.3.3 does not support the
+I:octave=N command, but selecting certain clefs causes it to automatically
+transpose by several octaves. You can produce abc that works for both by
+following the clef change with an I:octave=N command to do the transpose
+that abc2ps does automatically.
+.PP
+* Produces boxed part labels.
+.PP
+* Supports the segno symbol with !segno! and coda with !coda! . Other
+musical instructions such as !fine! and !D.C.! come out as text.
+* Supports the U: field for abbreviating symbols to single characters.  e.g.
+.PP
+U:S = !segno!
+.PP
+allows S to be used to produce the segno symbol. Currently this only
+allows new symbols to be defined and does not allow the existing
+pre-defined symbols M,L,R,H and T to be altered.
+.PP
+* Supports the !red! and !black! instructions for switching from
+black to red or vice-versa.
+.PP
+* Supports the following abc2ps extensions to abc :
+.PP
+   %%newpage  - start a new page,
+.br
+   %%vskip N  - adds vertical space of N points. If N is followed by
+                'cm' or 'in' the units are taken as centimetres or
+                inches instead of points e.g. 4cm.
+.br
+   %%text     - print text
+.br
+   %%centre (or %%center for Americans) - print centred text.
+.br
+   If %%text or %%centre appear in the header, the text appears above
+   the tune.
+.PP
+   %%staffsep SIZE - set the vertical blank space between 2 consecutive
+                     music staves.
+.PP
+   %%titleleft N - select title placed to the left or centred. N = 1
+                   places the title on the left while N = 0 centres it.
+.br
+   %%titlecaps - title is displayed in upper case (capital) letters.
+.br
+   %%textfont NAME SIZE - select font called NAME and point size SIZE
+   for text produced by %%text or %%centre. If only NAME is given, the
+   font stays the same size. Likewise, if '-' is given as the NAME,
+   only the font size changes.
+.br
+   %%titlefont NAME SIZE - select font for title.
+.br
+   %%subtitlefont NAME SIZE - select font for titles after the first
+   title.
+.br
+   %%composerfont NAME SIZE - select font for words in C: and O: fields
+                             and part specifier (P: in header).
+.br
+   %%wordsfont NAME SIZE - select font for words in W: fields.
+.br
+   %%partsfont NAME SIZE - select font for boxed parts and
+   !instruction! .
+.br
+   %%vocalfont NAME SIZE - select font for words in w: fields.
+.br
+   %%gchordfont NAME SIZE - select font for guitar chords in the music.
+   (It is advisable not to change the font name for the last two, since
+    the program calculates the width of strings using default fonts)
+.br
+   %%titlespace, %%subtitlespace, %%textspace, %%composerspace,
+   %%wordsspace, %%partsspace, %%vocalspace and %%gchordspace
+   determine the amount of space left above the relevant type 
+   of text. Each of these should be followed by a size in points
+   or value in centrimetres or inches.
+.br
+   e.g. %%composerfont 3
+        %%titlefont 2cm
+.PP
+* Supports placing of accompaniment chords either above or below the
+  stave.
+.PP
+   %%chordsabove - places accompaniment chords above the stave
+   (default).
+.br
+   %%chordsbelow - places accompaniment chords below the stave.
+.PP
+* Supports optional text enclosed in quotes before and after the
+  tempo specification in the Q: field. This extension comes from
+  abc2ps.
+
+.SH AUTHOR
+James Allwright <J.R.Allwright@westminster.ac.uk>
+.SH SUPPORTED
+Seymour Shlien <fy733@ncf.ca>
+.PP
+More complete documentation can be found in abcguide.txt which
+comes with the abcMIDI distribution package.
+.SH VERSION
+This man page describes version 1.39 August 13 2005.
+
diff --git a/upstream/mageia-cauldron/man1/ybmtopbm.1 b/upstream/mageia-cauldron/man1/ybmtopbm.1
new file mode 100644
index 00000000..ebf35115
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/ybmtopbm.1
@@ -0,0 +1,57 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Ybmtopbm User Manual" 0 "06 March 1990" "netpbm documentation"
+
+.SH NAME
+
+ybmtopbm - convert a Bennet Yee "face" file to PBM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBybmtopbm\fP
+
+[\fIfacefile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBymtopbm\fP reads a file acceptable to the \fBface\fP and
+\fBxbm\fP programs by Bennet Yee (\fIbsy+@cs.cmu.edu\fP).  and writes a PBM
+image as output.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fBybmtopbm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "pbmtoybm" (1)\c
+\&, 
+.BR "pbm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/ybmtopbm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/yes.1 b/upstream/mageia-cauldron/man1/yes.1
new file mode 100644
index 00000000..aa8d0bbf
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yes.1
@@ -0,0 +1,36 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
+.TH YES "1" "April 2022" "GNU coreutils 9.1" "User Commands"
+.SH NAME
+yes \- output a string repeatedly until killed
+.SH SYNOPSIS
+.B yes
+[\fI\,STRING\/\fR]...
+.br
+.B yes
+\fI\,OPTION\/\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Repeatedly output a line with all specified STRING(s), or 'y'.
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.SH AUTHOR
+Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+.br
+Report any translation bugs to <https://translationproject.org/team/>
+.SH COPYRIGHT
+Copyright \(co 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+Full documentation <https://www.gnu.org/software/coreutils/yes>
+.br
+or available locally via: info \(aq(coreutils) yes invocation\(aq
diff --git a/upstream/mageia-cauldron/man1/yum-changelog.1 b/upstream/mageia-cauldron/man1/yum-changelog.1
new file mode 100644
index 00000000..c4d3e01e
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yum-changelog.1
@@ -0,0 +1,101 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "YUM-CHANGELOG" "1" "Jan 30, 2024" "4.4.3" "dnf-plugins-core"
+.SH NAME
+yum-changelog \- redirecting to DNF changelog Plugin
+.SH DESCRIPTION
+.sp
+\fIchangelog\fP is a plugin for viewing package changelogs.
+.SH SYNOPSIS
+.sp
+\fBdnf changelog [<options>] <package\-spec>...\fP
+.SH ARGUMENTS
+.INDENT 0.0
+.TP
+.B \fB<package\-spec>\fP
+Package specification for packages to display changelogs.
+.UNINDENT
+.SH OPTIONS
+.sp
+All general DNF options are accepted, see \fIOptions\fP in \fBdnf(8)\fP for details.
+.INDENT 0.0
+.TP
+.B \fB\-\-since=<date>\fP
+Show only changelog entries since \fB<date>\fP\&. To avoid ambiguosity using YYYY\-MM\-DD date format is recommended.
+.TP
+.B \fB\-\-count=<number>\fP
+Show maximum of \fB<number>\fP changelog entries per package.
+.TP
+.B \fB\-\-upgrades\fP
+Show only new changelog entries for packages, that provide an upgrade for some of already installed packages.
+.UNINDENT
+.SH EXAMPLES
+.sp
+Show changelogs for all packages since November 1, 2018:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dnf changelog \-\-since=2018\-11\-1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Show 3 latest changelogs of package dnf:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dnf changelog \-\-count=3 dnf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Show what is new in upgradable packages:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dnf changelog \-\-upgrades
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+See AUTHORS in your Core DNF Plugins distribution
+.SH COPYRIGHT
+2014, Red Hat, Licensed under GPLv2+
+.\" Generated by docutils manpage writer.
+.
diff --git a/upstream/mageia-cauldron/man1/yuvsplittoppm.1 b/upstream/mageia-cauldron/man1/yuvsplittoppm.1
new file mode 100644
index 00000000..f82aca90
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yuvsplittoppm.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Yuvsplittoppm User Manual" 0 "26 August 93" "netpbm documentation"
+
+.SH NAME
+
+yuvsplittoppm - convert separate Y, U, and V files into a PPM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fByuvsplittoppm \fP
+
+\fIbasename\fP 
+\fIwidth\fP 
+\fIheight\fP
+[\fB-ccir601\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fByuvsplittoppm\fP reads three files, containing the YUV
+components, as input.  These files are \fIbasename\fP.Y,
+\fIbasename\fP.U, and \fIbasename\fP.V.  Produces a PPM image
+on Standard Output.
+.PP
+Since the YUV files are raw files, the dimensions \fIwidth\fP and
+\fIheight\fP must be specified on the command line.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fByuvsplittoppm\fP recognizes the following
+command line option:
+
+
+.TP
+\fB-ccir601\fP
+Assumes that the YUV triplets are scaled into the smaller range of the
+CCIR 601 (MPEG) standard. Else, the JFIF (JPEG) standard is assumed.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoyuvsplit" (1)\c
+\&, 
+.BR "yuvtoppm" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Marcel Wijkstra <\fIwijkstra@fwi.uva.nl\fP>, based
+on \fBppmtoyuvsplit\fP.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/yuvsplittoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/yuvtoppm.1 b/upstream/mageia-cauldron/man1/yuvtoppm.1
new file mode 100644
index 00000000..bb61ba3f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yuvtoppm.1
@@ -0,0 +1,72 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Yuvtoppm User Manual" 0 "25 March 91" "netpbm documentation"
+
+.SH NAME
+
+yuvtoppm - convert Abekas YUV bytes to PPM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fByuvtoppm\fP
+
+\fIwidth\fP 
+\fIheight\fP
+[\fIimagedata\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fByuvtoppm\fP reads raw Abekas YUV bytes as input and produces a
+PPM image as output.  The input file is just YUV bytes.  You have to
+specify the width and height on the command line, since the program
+obviously can't get them from the file.  \fByuvotppm\fP assumes the
+maxval of the input is 255.
+.PP
+The
+.BR "\fBppmtoyuv\fP manual" (1)\c
+\& tells a little
+about the Abekas YUV format.
+
+.UN options
+.SH OPTIONS
+.PP
+There are no command line options defined specifically
+for \fByuvtoppm\fP, but it recognizes the options common to all
+programs based on libnetpbm (See 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&.)
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmtoyuv" (1)\c
+\&, 
+.BR "ppm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Marc Boucher <\fImarc@PostImage.COM\fP>, based on
+Example Conversion Program, A60/A64 Digital Video Interface Manual,
+page 69.
+.PP
+Copyright (C) 1991 by DHD PostImage Inc.
+.PP
+Copyright (C) 1987 by Abekas Video Systems Inc.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/yuvtoppm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/yuy2topam.1 b/upstream/mageia-cauldron/man1/yuy2topam.1
new file mode 100644
index 00000000..06d47466
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/yuy2topam.1
@@ -0,0 +1,74 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Yuy2topam User Manual" 0 "23 December 2014" "netpbm documentation"
+
+.SH NAME
+
+yuy2topam - convert YUY2 bytes to PAM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fByuy2topam\fP
+
+\fB-width=\fP\fIpixels\fP 
+\fB-height=\fP\fIpixels\fP
+[\fIfilename\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fByuy2topam\fP reads raw YUY2 bytes as input and produces a
+PAM image as output.  The input file is just YUY2 bytes.  You have to
+specify the width and height on the command line, since the program
+obviously can't get them from the file.
+
+The output image has maxval 255.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fByuy2topam\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-width\fP=\fIwidth\fP
+Width of the image, in pixels.  This must be an even number. 
+
+.TP
+\fB-height\fP=\fIheight\fP
+Height of the image.
+
+
+.PP
+These options are mandatory.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pam" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Michael Haardt <\fImichael@moria.de\fP>.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/yuy2topam.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/zdiff.1 b/upstream/mageia-cauldron/man1/zdiff.1
new file mode 100644
index 00000000..037b582c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zdiff.1
@@ -0,0 +1,50 @@
+.TH ZDIFF 1
+.SH NAME
+zcmp, zdiff \- compare compressed files
+.SH SYNOPSIS
+.B zcmp
+[ cmp_options ] file1
+[ file2 ]
+.br
+.B zdiff
+[ diff_options ] file1
+[ file2 ]
+.SH DESCRIPTION
+The
+.B zcmp
+and
+.B zdiff
+commands
+are used to invoke the
+.B cmp
+or the
+.B diff
+program on files compressed via
+.BR gzip "."
+All options specified are passed directly to
+.B cmp
+or
+.BR diff "."
+If only
+.I file1
+is specified, it is compared to the uncompressed contents of
+.IB file1 ".gz" .
+If two files are specified, their contents (uncompressed if necessary) are fed to
+.B cmp
+or
+.BR diff "."
+The input files are not modified.
+The exit status from
+.B cmp
+or
+.B diff
+is preserved.
+.SH "SEE ALSO"
+cmp(1), diff(1), zmore(1), zgrep(1), znew(1), zforce(1), gzip(1), gzexe(1)
+.SH BUGS
+Messages from the
+.B cmp
+or
+.B diff
+programs may refer to file names such as "\-" instead of to the file
+names specified.
diff --git a/upstream/mageia-cauldron/man1/zeisstopnm.1 b/upstream/mageia-cauldron/man1/zeisstopnm.1
new file mode 100644
index 00000000..a37e11a8
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zeisstopnm.1
@@ -0,0 +1,72 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Zeisstopnm User Manual" 0 "15 June 1993" "netpbm documentation"
+
+.SH NAME
+zeisstopnm - convert a Zeiss confocal file to PNM
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBzeisstopnm\fP
+
+[\fB-pgm\fP | \fB-ppm\fP]
+
+[\fIzeissfile\fP]
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBzeisstopnm\fP reads a Zeiss confocal file as input and produces
+a PNM image as output.  
+.PP
+By default, the exact type of the output depends on the input file:
+If it's grayscale a PGM image; otherwise a PPM.  The program tells you
+which type it is writing.  You can override the default with the 
+\fB-pgm\fP and \fB-ppm\fP options.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBzeisstopnm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-pgm\fP
+Force the output to be in PGM format.
+
+.TP
+\fB-ppm\fP
+Force the output to be in PPM format.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1993 by Oliver Trepte
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/zeisstopnm.html
+.PP
\ No newline at end of file
diff --git a/upstream/mageia-cauldron/man1/zforce.1 b/upstream/mageia-cauldron/man1/zforce.1
new file mode 100644
index 00000000..508686fc
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zforce.1
@@ -0,0 +1,24 @@
+.TH ZFORCE 1
+.SH NAME
+zforce \- force a '.gz' extension on all gzip files
+.SH SYNOPSIS
+.B zforce
+[ name ...  ]
+.SH DESCRIPTION
+The
+.B zforce
+command
+forces a
+.B .gz
+extension on all
+.B gzip
+files so that
+.B gzip
+will not compress them twice.
+This can be useful for files with names truncated after a file transfer.
+On systems with a 14 char limitation on file names, the original name
+is truncated to make room for the .gz suffix. For example,
+12345678901234 is renamed to 12345678901.gz. A file name such as foo.tgz
+is left intact.
+.SH "SEE ALSO"
+gzip(1), znew(1), zmore(1), zgrep(1), zdiff(1), gzexe(1)
diff --git a/upstream/mageia-cauldron/man1/zgrep.1 b/upstream/mageia-cauldron/man1/zgrep.1
new file mode 100644
index 00000000..4daaab9c
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zgrep.1
@@ -0,0 +1,58 @@
+.TH ZGREP 1
+.SH NAME
+zgrep \- search possibly compressed files for a regular expression
+.SH SYNOPSIS
+.B zgrep
+[ grep_options ]
+.BI  [\ -e\ ] " pattern"
+.IR filename ".\|.\|."
+.SH DESCRIPTION
+The
+.B zgrep
+command invokes
+.B grep
+on compressed or gzipped files.
+All options specified are passed directly to
+.BR grep .
+If no file is specified, then the standard input is decompressed
+if necessary and fed to grep.
+Otherwise the given files are uncompressed if necessary and fed to
+.BR grep .
+.PP
+If the GREP environment variable is set,
+.B zgrep
+uses it as the
+.B grep
+program to be invoked.
+.SH "EXIT STATUS"
+Exit status is 0 for a match, 1 for no matches, and 2 if trouble.
+.SH BUGS
+.PP
+The following
+.B grep
+options are not supported:
+.B --dereference-recursive
+.RB ( \-R ),
+.B --directories
+.RB ( \-d ),
+.BR --exclude ,
+.BR --exclude-from ,
+.BR --exclude-dir ,
+.BR --include ,
+.B --null
+.RB ( \-Z ),
+.B --null-data
+.RB ( \-z ),
+and
+.B --recursive
+.RB ( \-r ).
+.SH AUTHOR
+Charles Levert (charles@comm.polymtl.ca)
+.SH "SEE ALSO"
+.BR grep (1),
+.BR gzexe (1),
+.BR gzip (1),
+.BR zdiff (1),
+.BR zforce (1),
+.BR zmore (1),
+.BR znew (1)
diff --git a/upstream/mageia-cauldron/man1/zipdetails.1 b/upstream/mageia-cauldron/man1/zipdetails.1
new file mode 100644
index 00000000..90bce2d6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zipdetails.1
@@ -0,0 +1,405 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "ZIPDETAILS 1"
+.TH ZIPDETAILS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+zipdetails \- display the internal structure of zip files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\&    zipdetails [\-v][\-\-scan][\-\-redact][\-\-utc] zipfile.zip
+\&    zipdetails \-h
+\&    zipdetails \-\-version
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This program creates a detailed report on the internal structure of zip
+files. For each item of metadata within a zip file the program will output
+.IP "the offset into the zip file where the item is located." 5
+.IX Item "the offset into the zip file where the item is located."
+.PD 0
+.IP "a textual representation for the item." 5
+.IX Item "a textual representation for the item."
+.IP "an optional hex dump of the item." 5
+.IX Item "an optional hex dump of the item."
+.PD
+.PP
+The program assumes a prior understanding of the internal structure of Zip
+files. You should have a copy of the Zip
+APPNOTE.TXT <http://www.pkware.com/documents/casestudies/APPNOTE.TXT> file
+at hand to help understand the output from this program.
+.SS "Default Behaviour"
+.IX Subsection "Default Behaviour"
+By default the program expects to be given a well-formed zip file.  It will
+navigate the Zip file by first parsing the zip central directory at the end
+of the file.  If that is found, it will then walk through the zip records
+starting at the beginning of the file. Any badly formed zip data structures
+encountered are likely to terminate the program.
+.PP
+If the program finds any structural problems with the zip file it will
+print a summary at the end of the output report. The set of error cases
+reported is very much a work in progress, so don't rely on this feature to
+find all the possible errors in a zip file. If you have suggestions for
+use-cases where this could be enhanced please consider creating an
+enhancement request (see "SUPPORT").
+.PP
+Date/time fields are found in zip files are displayed in local time. Use
+the \f(CW\*(C`\-\-utc\*(C'\fR option to display these fields in Coordinated Universal Time
+(UTC).
+.SS Scan-Mode
+.IX Subsection "Scan-Mode"
+If you do have a potentially corrupt zip file, particulatly where the
+central directory at the end of the file is absent/incomplete, you can try
+usng the \f(CW\*(C`\-\-scan\*(C'\fR option to search for zip records that are still present.
+.PP
+When Scan-mode is enabled, the program will walk the zip file from the
+start, blindly looking for the 4\-byte signatures that preceed each of the
+zip data structures. If it finds any of the recognised signatures it will
+attempt to dump the associated zip record. For very large zip files, this
+operation can take a long time to run.
+.PP
+Note that the 4\-byte signatures used in zip files can sometimes match with
+random data stored in the zip file, so care is needed interpreting the
+results.
+.SS OPTIONS
+.IX Subsection "OPTIONS"
+.IP \-h 5
+.IX Item "-h"
+Display help
+.IP \-\-redact 5
+.IX Item "--redact"
+Obscure filenames in the output. Handy for the use case where the zip files
+contains sensitive data that cannot be shared.
+.IP \-\-scan 5
+.IX Item "--scan"
+Walk the zip file loking for possible zip records. Can be error-prone.
+See "Scan-Mode"
+.IP \-\-utc 5
+.IX Item "--utc"
+By default, date/time fields are displayed in local time. Use this option
+to display them in in Coordinated Universal Time (UTC).
+.IP \-v 5
+.IX Item "-v"
+Enable Verbose mode. See "Verbose Output".
+.IP \-\-version 5
+.IX Item "--version"
+Display version number of the program and exit.
+.SS "Default Output"
+.IX Subsection "Default Output"
+By default zipdetails will output the details of the zip file in three
+columns.
+.IP "Column 1" 5
+.IX Item "Column 1"
+This contains the offset from the start of the file in hex.
+.IP "Column 2" 5
+.IX Item "Column 2"
+This contains a textual description of the field.
+.IP "Column 3" 5
+.IX Item "Column 3"
+If the field contains a numeric value it will be displayed in hex. Zip
+stores most numbers in little-endian format \- the value displayed will have
+the little-endian encoding removed.
+.Sp
+Next, is an optional description of what the value means.
+.PP
+For example, assuming you have a zip file with two entries, like this
+.PP
+.Vb 8
+\&    $ unzip \-l test.zip
+\&    Archive:  setup/test.zip
+\&    Length      Date    Time    Name
+\&    \-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-   \-\-\-\-
+\&            6  2021\-03\-23 18:52   latters.txt
+\&            6  2021\-03\-23 18:52   numbers.txt
+\&    \-\-\-\-\-\-\-\-\-                     \-\-\-\-\-\-\-
+\&        12                     2 files
+.Ve
+.PP
+Running \f(CW\*(C`zipdetails\*(C'\fR will gives this output
+.PP
+.Vb 1
+\&    $ zipdetails test.zip
+\&
+\&    0000 LOCAL HEADER #1       04034B50
+\&    0004 Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0005 Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0006 General Purpose Flag  0000
+\&    0008 Compression Method    0000 \*(AqStored\*(Aq
+\&    000A Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    000E CRC                   0F8A149C
+\&    0012 Compressed Length     00000006
+\&    0016 Uncompressed Length   00000006
+\&    001A Filename Length       000B
+\&    001C Extra Length          0000
+\&    001E Filename              \*(Aqletters.txt\*(Aq
+\&    0029 PAYLOAD               abcde.
+\&
+\&    002F LOCAL HEADER #2       04034B50
+\&    0033 Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0034 Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0035 General Purpose Flag  0000
+\&    0037 Compression Method    0000 \*(AqStored\*(Aq
+\&    0039 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    003D CRC                   261DAFE6
+\&    0041 Compressed Length     00000006
+\&    0045 Uncompressed Length   00000006
+\&    0049 Filename Length       000B
+\&    004B Extra Length          0000
+\&    004D Filename              \*(Aqnumbers.txt\*(Aq
+\&    0058 PAYLOAD               12345.
+\&
+\&    005E CENTRAL HEADER #1     02014B50
+\&    0062 Created Zip Spec      1E \*(Aq3.0\*(Aq
+\&    0063 Created OS            03 \*(AqUnix\*(Aq
+\&    0064 Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0065 Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0066 General Purpose Flag  0000
+\&    0068 Compression Method    0000 \*(AqStored\*(Aq
+\&    006A Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    006E CRC                   0F8A149C
+\&    0072 Compressed Length     00000006
+\&    0076 Uncompressed Length   00000006
+\&    007A Filename Length       000B
+\&    007C Extra Length          0000
+\&    007E Comment Length        0000
+\&    0080 Disk Start            0000
+\&    0082 Int File Attributes   0001
+\&         [Bit 0]               1 Text Data
+\&    0084 Ext File Attributes   81B40000
+\&    0088 Local Header Offset   00000000
+\&    008C Filename              \*(Aqletters.txt\*(Aq
+\&
+\&    0097 CENTRAL HEADER #2     02014B50
+\&    009B Created Zip Spec      1E \*(Aq3.0\*(Aq
+\&    009C Created OS            03 \*(AqUnix\*(Aq
+\&    009D Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    009E Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    009F General Purpose Flag  0000
+\&    00A1 Compression Method    0000 \*(AqStored\*(Aq
+\&    00A3 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    00A7 CRC                   261DAFE6
+\&    00AB Compressed Length     00000006
+\&    00AF Uncompressed Length   00000006
+\&    00B3 Filename Length       000B
+\&    00B5 Extra Length          0000
+\&    00B7 Comment Length        0000
+\&    00B9 Disk Start            0000
+\&    00BB Int File Attributes   0001
+\&         [Bit 0]               1 Text Data
+\&    00BD Ext File Attributes   81B40000
+\&    00C1 Local Header Offset   0000002F
+\&    00C5 Filename              \*(Aqnumbers.txt\*(Aq
+\&
+\&    00D0 END CENTRAL HEADER    06054B50
+\&    00D4 Number of this disk   0000
+\&    00D6 Central Dir Disk no   0000
+\&    00D8 Entries in this disk  0002
+\&    00DA Total Entries         0002
+\&    00DC Size of Central Dir   00000072
+\&    00E0 Offset to Central Dir 0000005E
+\&    00E4 Comment Length        0000
+\&    Done
+.Ve
+.SS "Verbose Output"
+.IX Subsection "Verbose Output"
+If the \f(CW\*(C`\-v\*(C'\fR option is present, column 1 is expanded to include
+.IP \(bu 5
+The offset from the start of the file in hex.
+.IP \(bu 5
+The length of the field in hex.
+.IP \(bu 5
+A hex dump of the bytes in field in the order they are stored in the zip
+file.
+.PP
+Here is the same zip file dumped using the \f(CW\*(C`zipdetails\*(C'\fR \f(CW\*(C`\-v\*(C'\fR option:
+.PP
+.Vb 1
+\&    $ zipdetails \-v test.zip
+\&
+\&    0000 0004 50 4B 03 04 LOCAL HEADER #1       04034B50
+\&    0004 0001 0A          Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0005 0001 00          Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0006 0002 00 00       General Purpose Flag  0000
+\&    0008 0002 00 00       Compression Method    0000 \*(AqStored\*(Aq
+\&    000A 0004 3D 98 77 52 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    000E 0004 9C 14 8A 0F CRC                   0F8A149C
+\&    0012 0004 06 00 00 00 Compressed Length     00000006
+\&    0016 0004 06 00 00 00 Uncompressed Length   00000006
+\&    001A 0002 0B 00       Filename Length       000B
+\&    001C 0002 00 00       Extra Length          0000
+\&    001E 000B 6C 65 74 74 Filename              \*(Aqletters.txt\*(Aq
+\&              65 72 73 2E
+\&              74 78 74
+\&    0029 0006 61 62 63 64 PAYLOAD               abcde.
+\&              65 0A
+\&
+\&    002F 0004 50 4B 03 04 LOCAL HEADER #2       04034B50
+\&    0033 0001 0A          Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0034 0001 00          Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0035 0002 00 00       General Purpose Flag  0000
+\&    0037 0002 00 00       Compression Method    0000 \*(AqStored\*(Aq
+\&    0039 0004 3D 98 77 52 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    003D 0004 E6 AF 1D 26 CRC                   261DAFE6
+\&    0041 0004 06 00 00 00 Compressed Length     00000006
+\&    0045 0004 06 00 00 00 Uncompressed Length   00000006
+\&    0049 0002 0B 00       Filename Length       000B
+\&    004B 0002 00 00       Extra Length          0000
+\&    004D 000B 6E 75 6D 62 Filename              \*(Aqnumbers.txt\*(Aq
+\&              65 72 73 2E
+\&              74 78 74
+\&    0058 0006 31 32 33 34 PAYLOAD               12345.
+\&              35 0A
+\&
+\&    005E 0004 50 4B 01 02 CENTRAL HEADER #1     02014B50
+\&    0062 0001 1E          Created Zip Spec      1E \*(Aq3.0\*(Aq
+\&    0063 0001 03          Created OS            03 \*(AqUnix\*(Aq
+\&    0064 0001 0A          Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    0065 0001 00          Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    0066 0002 00 00       General Purpose Flag  0000
+\&    0068 0002 00 00       Compression Method    0000 \*(AqStored\*(Aq
+\&    006A 0004 3D 98 77 52 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    006E 0004 9C 14 8A 0F CRC                   0F8A149C
+\&    0072 0004 06 00 00 00 Compressed Length     00000006
+\&    0076 0004 06 00 00 00 Uncompressed Length   00000006
+\&    007A 0002 0B 00       Filename Length       000B
+\&    007C 0002 00 00       Extra Length          0000
+\&    007E 0002 00 00       Comment Length        0000
+\&    0080 0002 00 00       Disk Start            0000
+\&    0082 0002 01 00       Int File Attributes   0001
+\&                          [Bit 0]               1 Text Data
+\&    0084 0004 00 00 B4 81 Ext File Attributes   81B40000
+\&    0088 0004 00 00 00 00 Local Header Offset   00000000
+\&    008C 000B 6C 65 74 74 Filename              \*(Aqletters.txt\*(Aq
+\&              65 72 73 2E
+\&              74 78 74
+\&
+\&    0097 0004 50 4B 01 02 CENTRAL HEADER #2     02014B50
+\&    009B 0001 1E          Created Zip Spec      1E \*(Aq3.0\*(Aq
+\&    009C 0001 03          Created OS            03 \*(AqUnix\*(Aq
+\&    009D 0001 0A          Extract Zip Spec      0A \*(Aq1.0\*(Aq
+\&    009E 0001 00          Extract OS            00 \*(AqMS\-DOS\*(Aq
+\&    009F 0002 00 00       General Purpose Flag  0000
+\&    00A1 0002 00 00       Compression Method    0000 \*(AqStored\*(Aq
+\&    00A3 0004 3D 98 77 52 Last Mod Time         5277983D \*(AqTue Mar 23 19:01:58 2021\*(Aq
+\&    00A7 0004 E6 AF 1D 26 CRC                   261DAFE6
+\&    00AB 0004 06 00 00 00 Compressed Length     00000006
+\&    00AF 0004 06 00 00 00 Uncompressed Length   00000006
+\&    00B3 0002 0B 00       Filename Length       000B
+\&    00B5 0002 00 00       Extra Length          0000
+\&    00B7 0002 00 00       Comment Length        0000
+\&    00B9 0002 00 00       Disk Start            0000
+\&    00BB 0002 01 00       Int File Attributes   0001
+\&                          [Bit 0]               1 Text Data
+\&    00BD 0004 00 00 B4 81 Ext File Attributes   81B40000
+\&    00C1 0004 2F 00 00 00 Local Header Offset   0000002F
+\&    00C5 000B 6E 75 6D 62 Filename              \*(Aqnumbers.txt\*(Aq
+\&              65 72 73 2E
+\&              74 78 74
+\&
+\&    00D0 0004 50 4B 05 06 END CENTRAL HEADER    06054B50
+\&    00D4 0002 00 00       Number of this disk   0000
+\&    00D6 0002 00 00       Central Dir Disk no   0000
+\&    00D8 0002 02 00       Entries in this disk  0002
+\&    00DA 0002 02 00       Total Entries         0002
+\&    00DC 0004 72 00 00 00 Size of Central Dir   00000072
+\&    00E0 0004 5E 00 00 00 Offset to Central Dir 0000005E
+\&    00E4 0002 00 00       Comment Length        0000
+\&    Done
+.Ve
+.SH LIMITATIONS
+.IX Header "LIMITATIONS"
+The following zip file features are not supported by this program:
+.IP \(bu 5
+Multi-part archives.
+.IP \(bu 5
+The strong encryption features defined in the APPNOTE.TXT <http://www.pkware.com/documents/casestudies/APPNOTE.TXT> document.
+.SH TODO
+.IX Header "TODO"
+Error handling is a work in progress. If the program encounters a problem
+reading a zip file it is likely to terminate with an unhelpful error
+message.
+.SH SUPPORT
+.IX Header "SUPPORT"
+General feedback/questions/bug reports should be sent to
+<https://github.com/pmqs/zipdetails/issues>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The primary reference for Zip files is
+APPNOTE.TXT <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>.
+.PP
+An alternative reference is the Info-Zip appnote. This is available from
+<ftp://ftp.info\-zip.org/pub/infozip/doc/>
+.PP
+For details of WinZip AES encryption see AES Encryption Information:
+Encryption Specification AE\-1 and AE\-2 <https://www.winzip.com/win/es/aes_info.html>.
+.PP
+The \f(CW\*(C`zipinfo\*(C'\fR program that comes with the info-zip distribution
+(<http://www.info\-zip.org/>) can also display details of the structure of
+a zip file.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess \fIpmqs@cpan.org\fR.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 2011\-2022 Paul Marquess. All rights reserved.
+.PP
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
diff --git a/upstream/mageia-cauldron/man1/zipinfo.1 b/upstream/mageia-cauldron/man1/zipinfo.1
new file mode 100644
index 00000000..428e4b97
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zipinfo.1
@@ -0,0 +1,517 @@
+.\"  Copyright (c) 1990-2009 Info-ZIP.  All rights reserved.
+.\"
+.\"  See the accompanying file LICENSE, version 2009-Jan-02 or later
+.\"  (the contents of which are also included in unzip.h) for terms of use.
+.\"  If, for some reason, all these files are missing, the Info-ZIP license
+.\"  also may be found at:  ftp://ftp.info-zip.org/pub/infozip/license.html
+.\"
+.\" zipinfo.1 by Greg Roelofs and others.
+.\"
+.\" =========================================================================
+.\" define .X macro (for long-line ZipInfo output examples; small Courier):
+.de X
+.nf
+.ft CW
+.ie n .ti -5
+.el \{ .ti +2m
+.ps -1 \}
+\&\\$1
+.ie n .ti +5
+.el \{ .ti -2m
+.ps +1 \}
+.ft
+.fi
+..
+.\" define .EX/.EE (for multiline user-command examples; normal Courier font)
+.de EX
+.in +4n
+.nf
+.ft CW
+..
+.de EE
+.ft
+.fi
+.in -4n
+..
+.\" =========================================================================
+.TH ZIPINFO 1L "20 April 2009 (v3.0)" "Info-ZIP"
+.SH NAME
+zipinfo \- list detailed information about a ZIP archive
+.PD
+.SH SYNOPSIS
+\fBzipinfo\fP [\fB\-12smlvhMtTz\fP] \fIfile\fP[\fI.zip\fP]
+[\fIfile(s)\fP\ .\|.\|.] [\fB\-x\fP\ \fIxfile(s)\fP\ .\|.\|.]
+.PP
+\fBunzip\fP \fB\-Z\fP [\fB\-12smlvhMtTz\fP] \fIfile\fP[\fI.zip\fP]
+[\fIfile(s)\fP\ .\|.\|.] [\fB\-x\fP\ \fIxfile(s)\fP\ .\|.\|.]
+.PD
+.\" =========================================================================
+.SH DESCRIPTION
+\fIzipinfo\fP lists technical information about files in a ZIP archive, most
+commonly found on MS-DOS systems.  Such information includes file access
+permissions, encryption status, type of compression, version and operating
+system or file system of compressing program, and the like.  The default
+behavior (with no options) is
+to list single-line entries for each file in the archive, with header and
+trailer lines providing summary information for the entire archive.  The
+format is a cross between Unix ``\fCls \-l\fR'' and ``\fCunzip \-v\fR''
+output.  See
+.B "DETAILED DESCRIPTION"
+below.  Note that \fIzipinfo\fP is the same program as \fIunzip\fP (under
+Unix, a link to it); on some systems, however, \fIzipinfo\fP support may
+have been omitted when \fIunzip\fP was compiled.
+.PD
+.\" =========================================================================
+.SH ARGUMENTS
+.TP
+.IR file [ .zip ]
+Path of the ZIP archive(s).  If the file specification is a wildcard,
+each matching file is processed in an order determined by the operating
+system (or file system).  Only the filename can be a wildcard; the path
+itself cannot.  Wildcard expressions are similar to Unix \fIegrep\fP(1)
+(regular) expressions and may contain:
+.RS
+.IP *
+matches a sequence of 0 or more characters
+.IP ?
+matches exactly 1 character
+.IP [.\|.\|.]
+matches any single character found inside the brackets; ranges are specified
+by a beginning character, a hyphen, and an ending character.  If an exclamation
+point or a caret (`!' or `^') follows the left bracket, then the range of
+characters within the brackets is complemented (that is, anything \fIexcept\fP
+the characters inside the brackets is considered a match).  To specify a
+verbatim left bracket, the three-character sequence ``[[]'' has to be used.
+.RE
+.IP
+(Be sure to quote any character that might otherwise be interpreted or
+modified by the operating system, particularly under Unix and VMS.)  If no
+matches are found, the specification is assumed to be a literal filename;
+and if that also fails, the suffix \fC.zip\fR is appended.  Note that
+self-extracting ZIP files are supported, as with any other ZIP archive;
+just specify the \fC.exe\fR suffix (if any) explicitly.
+.IP [\fIfile(s)\fP]
+An optional list of archive members to be processed, separated by spaces.
+(VMS versions compiled with VMSCLI defined must delimit files with commas
+instead.)
+Regular expressions (wildcards) may be used to match multiple members; see
+above.  Again, be sure to quote expressions that would otherwise be expanded
+or modified by the operating system.
+.IP [\fB\-x\fP\ \fIxfile(s)\fP]
+An optional list of archive members to be excluded from processing.
+.\" =========================================================================
+.SH OPTIONS
+.TP
+.B \-1
+list filenames only, one per line.  This option excludes all others; headers,
+trailers and zipfile comments are never printed.  It is intended for use in
+Unix shell scripts.
+.TP
+.B \-2
+list filenames only, one per line, but allow headers (\fB\-h\fP), trailers
+(\fB\-t\fP) and zipfile comments (\fB\-z\fP), as well.  This option may be
+useful in cases where the stored filenames are particularly long.
+.TP
+.B \-s
+list zipfile info in short Unix ``\fCls \-l\fR'' format.  This is the default
+behavior; see below.
+.TP
+.B \-m
+list zipfile info in medium Unix ``\fCls \-l\fR'' format.  Identical to the
+\fB\-s\fP output, except that the compression factor, expressed as a
+percentage, is also listed.
+.TP
+.B \-l
+list zipfile info in long Unix ``\fCls \-l\fR'' format.  As with \fB\-m\fP
+except that the compressed size (in bytes) is printed instead of the
+compression ratio.
+.TP
+.B \-v
+list zipfile information in verbose, multi-page format.
+.TP
+.B \-h
+list header line.  The archive name, actual size (in bytes) and total number
+of files is printed.
+.TP
+.B \-M
+pipe all output through an internal pager similar to the Unix \fImore\fP(1)
+command.  At the end of a screenful of output, \fIzipinfo\fP pauses with a
+``\-\-More\-\-'' prompt; the next screenful may be viewed by pressing the
+Enter (Return) key or the space bar.  \fIzipinfo\fP can be terminated by
+pressing the ``q'' key and, on some systems, the Enter/Return key.  Unlike
+Unix \fImore\fP(1), there is no forward-searching or editing capability.
+Also, \fIzipinfo\fP doesn't notice if long lines wrap at the edge of the
+screen, effectively resulting in the printing of two or more lines and the
+likelihood that some text will scroll off the top of the screen before being
+viewed.  On some systems the number of available lines on the screen is not
+detected, in which case \fIzipinfo\fP assumes the height is 24 lines.
+.TP
+.B \-t
+list totals for files listed or for all files.  The number of files listed,
+their uncompressed and compressed total sizes , and their overall compression
+factor is printed; or, if only the totals line is being printed, the values
+for the entire archive are given.  The compressed total size does not include
+the 12 additional header bytes of each encrypted entry. Note that the total
+compressed (data) size will never match the actual zipfile size, since the
+latter includes all of the internal zipfile headers in addition to the
+compressed data.
+.TP
+.B \-T
+print the file dates and times in a sortable decimal format (yymmdd.hhmmss).
+The default date format is a more standard, human-readable version with
+abbreviated month names (see examples below).
+.TP
+.B \-U
+[UNICODE_SUPPORT only] modify or disable UTF-8 handling.
+When UNICODE_SUPPORT is available, the option \fB\-U\fP forces \fIunzip\fP
+to escape all non-ASCII characters from UTF-8 coded filenames as ``#Uxxxx''.
+This option is mainly provided for debugging purpose when the fairly new
+UTF-8 support is suspected to mangle up extracted filenames.
+.IP
+The option \fB\-UU\fP allows to entirely disable the recognition of UTF-8
+encoded filenames.  The handling of filename codings within \fIunzip\fP falls
+back to the behaviour of previous versions.
+.TP
+.B \-z
+include the archive comment (if any) in the listing.
+.PD
+.\" =========================================================================
+.SH "DETAILED DESCRIPTION"
+.I zipinfo
+has a number of modes, and its behavior can be rather difficult to fathom
+if one isn't familiar with Unix \fIls\fP(1) (or even if one is).  The default
+behavior is to list files in the following format:
+.PP
+.X "-rw-rws---  1.9 unx    2802 t- defX 11-Aug-91 13:48 perms.2660"
+.PP
+The last three fields are the modification date and time of
+the file, and its name.  The case of the filename is respected; thus
+files that come from MS-DOS PKZIP are always capitalized.  If the file
+was zipped with a stored directory name, that is also displayed as part
+of the filename.
+.PP
+The second and third fields indicate that the file was zipped under
+Unix with version 1.9 of \fIzip\fP.  Since it comes from Unix, the file
+permissions at the beginning of the line are printed in Unix format.
+The uncompressed file-size (2802 in this example) is the fourth field.
+.PP
+The fifth field consists of two characters, either of which may take
+on several values.  The first character may be either `t' or `b', indicating
+that \fIzip\fP believes the file to be text or binary, respectively;
+but if the file is encrypted, \fIzipinfo\fP
+notes this fact by capitalizing the character (`T' or `B').  The second
+character may also take on four values, depending on whether there is
+an extended local header and/or an ``extra field'' associated with the
+file (fully explained in PKWare's APPNOTE.TXT, but basically analogous to
+pragmas in ANSI C--i.e., they provide a standard way to include non-standard
+information in the archive).  If neither exists, the character
+will be a hyphen (`\-'); if there is an extended local header but no extra
+field, `l'; if the reverse, `x'; and if both exist, `X'.  Thus the
+file in this example is (probably) a text file, is not encrypted, and
+has neither an extra field nor an extended local header associated with it.
+The example below, on the other hand, is an encrypted binary file with an
+extra field:
+.PP
+.X "RWD,R,R     0.9 vms     168 Bx shrk  9-Aug-91 19:15 perms.0644"
+.PP
+Extra fields are used for various purposes (see discussion of the \fB\-v\fP
+option below) including the storage of VMS file attributes, which is
+presumably the case here.  Note that the file attributes are listed in
+VMS format.  Some other possibilities for the host operating system (which
+is actually a misnomer--host file system is more correct) include
+OS/2 or NT with High Performance File System (HPFS), MS-DOS, OS/2 or NT
+with File Allocation Table (FAT) file system, and Macintosh.  These are
+denoted as follows:
+.PP
+.X "-rw-a--     1.0 hpf    5358 Tl i4:3  4-Dec-91 11:33 longfilename.hpfs"
+.X "-r--ahs     1.1 fat    4096 b- i4:2 14-Jul-91 12:58 EA DATA. SF"
+.X "--w-------  1.0 mac   17357 bx i8:2  4-May-92 04:02 unzip.macr"
+.PP
+File attributes in the first two cases are indicated in a Unix-like format,
+where the seven subfields indicate whether the file:  (1) is a directory,
+(2) is readable (always true), (3) is writable, (4) is executable (guessed
+on the basis of the extension--\fI.exe\fP, \fI.com\fP, \fI.bat\fP, \fI.cmd\fP
+and \fI.btm\fP files are assumed to be so), (5) has its archive bit set,
+(6) is hidden, and (7) is a system file.  Interpretation of Macintosh file
+attributes is unreliable because some Macintosh archivers don't store any
+attributes in the archive.
+.PP
+Finally, the sixth field indicates
+the compression method and possible sub-method used.  There are six methods
+known at present:  storing (no compression), reducing, shrinking, imploding,
+tokenizing (never publicly released), and deflating.  In addition, there are
+four levels of reducing (1 through 4); four types of imploding (4K or 8K
+sliding dictionary, and 2 or 3 Shannon-Fano trees); and four levels of
+deflating (superfast, fast, normal, maximum compression).  \fIzipinfo\fP
+represents these methods and their sub-methods as follows:  \fIstor\fP;
+\fIre:1\fP, \fIre:2\fP, etc.; \fIshrk\fP; \fIi4:2\fP, \fIi8:3\fP, etc.;
+\fItokn\fP; and \fIdefS\fP, \fIdefF\fP, \fIdefN\fP, and \fIdefX\fP.
+.PP
+The medium and long listings are almost identical to the short format except
+that they add information on the file's compression.  The medium format lists
+the file's compression factor as a percentage indicating the amount of space
+that has been ``removed'':
+.PP
+.X "-rw-rws---  1.5 unx    2802 t- 81% defX 11-Aug-91 13:48 perms.2660"
+.PP
+In this example, the file has been compressed by more than a factor of
+five; the compressed data are only 19% of the original size.  The long
+format gives the compressed file's size in bytes, instead:
+.PP
+.X "-rw-rws---  1.5 unx    2802 t-     538 defX 11-Aug-91 13:48 perms.2660"
+.PP
+In contrast to the \fIunzip\fP listings, the compressed size figures in
+this listing format denote the complete size of compressed data, including
+the 12 extra header bytes in case of encrypted entries.
+.PP
+Adding the \fB\-T\fP option changes the file date and time to decimal
+format:
+.PP
+.X "-rw-rws---  1.5 unx    2802 t-     538 defX 910811.134804 perms.2660"
+.PP
+Note that because of limitations in the MS-DOS format used to store file
+times, the seconds field is always rounded to the nearest even second.
+For Unix files this is expected to change in the next major releases of
+\fIzip\fP(1L) and \fIunzip\fP.
+.PP
+In addition to individual file information, a default zipfile listing
+also includes header and trailer lines:
+.PP
+.X "Archive:  OS2.zip   5453 bytes   5 files"
+.X ",,rw,       1.0 hpf     730 b- i4:3 26-Jun-92 23:40 Contents"
+.X ",,rw,       1.0 hpf    3710 b- i4:3 26-Jun-92 23:33 makefile.os2"
+.X ",,rw,       1.0 hpf    8753 b- i8:3 26-Jun-92 15:29 os2unzip.c"
+.X ",,rw,       1.0 hpf      98 b- stor 21-Aug-91 15:34 unzip.def"
+.X ",,rw,       1.0 hpf      95 b- stor 21-Aug-91 17:51 zipinfo.def"
+.X "5 files, 13386 bytes uncompressed, 4951 bytes compressed:  63.0%"
+.PP
+The header line gives the name of the archive, its total size, and the
+total number of files; the trailer gives the number of files listed,
+their total uncompressed size, and their total compressed size (not
+including any of \fIzip\fP's internal overhead).  If, however, one or
+more \fIfile(s)\fP are provided, the header and trailer lines are
+not listed.  This behavior is also similar to that of Unix's ``\fCls \-l\fR'';
+it may be overridden by specifying the \fB\-h\fP and \fB\-t\fP options
+explicitly.
+In such a case the listing format must also be specified explicitly,
+since \fB\-h\fP or \fB\-t\fP (or both) in the absence of other options implies
+that ONLY the header or trailer line (or both) is listed.  See the
+\fBEXAMPLES\fP section below for a semi-intelligible translation of this
+nonsense.
+.PP
+The verbose listing is mostly self-explanatory.  It also lists file
+comments and the zipfile comment, if any, and the type and number of bytes
+in any stored extra fields.  Currently known types of extra fields include
+PKWARE's authentication (``AV'') info; OS/2 extended attributes; VMS
+filesystem info, both PKWARE and Info-ZIP versions; Macintosh resource
+forks; Acorn/Archimedes SparkFS info; and so on.  (Note
+that in the case of OS/2 extended attributes--perhaps the most common
+use of zipfile extra fields--the size of the stored EAs as reported by
+\fIzipinfo\fP may not match the number given by OS/2's \fIdir\fP command:
+OS/2 always reports the number of bytes required in 16-bit format, whereas
+\fIzipinfo\fP always reports the 32-bit storage.)
+.PP
+Again, the compressed size figures of the individual entries include the
+12 extra header bytes for encrypted entries.  In contrast, the archive total
+compressed size and the average compression ratio shown in the summary
+bottom line are calculated \fBwithout\fP the extra 12 header bytes of
+encrypted entries.
+.PD
+.\" =========================================================================
+.SH "ENVIRONMENT OPTIONS"
+Modifying \fIzipinfo\fP's default behavior via options placed in
+an environment variable can be a bit complicated to explain, due to
+\fIzipinfo\fP's attempts to handle various defaults in an intuitive,
+yet Unix-like, manner.  (Try not to laugh.)  Nevertheless, there is some
+underlying logic.  In brief,
+there are three ``priority levels'' of options:  the default options;
+environment options, which can override or add to the defaults; and
+explicit options given by the user, which can override or add to
+either of the above.
+.PP
+The default listing format, as noted above, corresponds roughly
+to the "\fCzipinfo \-hst\fR" command (except when individual zipfile members
+are specified).
+A user who prefers the long-listing format (\fB\-l\fP) can make use of the
+\fIzipinfo\fP's environment variable to change this default:
+.TP
+Unix Bourne shell:
+\f(CW\&ZIPINFO=\-l; export ZIPINFO\fP
+.TP
+Unix C shell:
+\f(CW\&setenv ZIPINFO \-l\fP
+.TP
+OS/2 or MS-DOS:
+\f(CW\&set ZIPINFO=\-l\fP
+.TP
+VMS (quotes for \fIlowercase\fP):
+\f(CW\&define ZIPINFO_OPTS "\-l"\fP
+.EE
+.PP
+If, in addition, the user dislikes the trailer line, \fIzipinfo\fP's
+concept of ``negative options'' may be used to override the default
+inclusion of the line.  This is accomplished by preceding the undesired
+option with one or more minuses:  e.g., ``\fC\-l\-t\fR'' or ``\fC\-\-tl\fR'',
+in this example.  The first hyphen is the regular switch character, but the
+one before the `t' is a minus sign.  The dual use of hyphens may seem a
+little awkward, but it's reasonably intuitive nonetheless:  simply ignore
+the first hyphen and go from there.  It is also consistent with the behavior
+of the Unix command \fInice\fP(1).
+.PP
+As suggested above, the default variable names are ZIPINFO_OPTS for VMS
+(where the symbol used to install \fIzipinfo\fP as a foreign command
+would otherwise be confused with the environment variable), and ZIPINFO
+for all other operating systems.  For compatibility with \fIzip\fP(1L),
+ZIPINFOOPT is also accepted (don't ask).  If both ZIPINFO and ZIPINFOOPT
+are defined, however, ZIPINFO takes precedence.  \fIunzip\fP's diagnostic
+option (\fB\-v\fP with no zipfile name) can be used to check the values
+of all four possible \fIunzip\fP and \fIzipinfo\fP environment variables.
+.PD
+.\" =========================================================================
+.SH EXAMPLES
+To get a basic, short-format listing of the complete contents of a ZIP
+archive \fIstorage.zip\fP, with both header and totals lines, use only
+the archive name as an argument to zipinfo:
+.PP
+.EX
+zipinfo storage
+.EE
+.PP
+To produce a basic, long-format listing (not verbose), including header and
+totals lines, use \fB\-l\fP:
+.PP
+.EX
+zipinfo \-l storage
+.EE
+.PP
+To list the complete contents of the archive without header and totals
+lines, either negate the \fB\-h\fP and \fB\-t\fP options or else specify the
+contents explicitly:
+.PP
+.EX
+zipinfo \-\-h\-t storage
+zipinfo storage \e*
+.EE
+.PP
+(where the backslash is required only if the shell would otherwise expand
+the `*' wildcard, as in Unix when globbing is turned on--double quotes around
+the asterisk would have worked as well).  To turn off the totals line by
+default, use the environment variable (C shell is assumed here):
+.PP
+.EX
+setenv ZIPINFO \-\-t
+zipinfo storage
+.EE
+.PP
+To get the full, short-format listing of the first example again, given
+that the environment variable is set as in the previous example, it is
+necessary to specify the \fB\-s\fP option explicitly, since the \fB\-t\fP
+option by itself implies that ONLY the footer line is to be printed:
+.PP
+.EX
+setenv ZIPINFO \-\-t
+zipinfo \-t storage            \fR[only totals line]\fP
+zipinfo \-st storage           \fR[full listing]\fP
+.EE
+.PP
+The \fB\-s\fP option, like \fB\-m\fP and \fB\-l\fP, includes headers and
+footers by default, unless otherwise specified.  Since the environment
+variable specified no footers and that has a higher precedence than the
+default behavior of \fB\-s\fP, an explicit \fB\-t\fP option was necessary
+to produce the full listing.  Nothing was indicated about the header,
+however, so the \fB\-s\fP option was sufficient.  Note that both the
+\fB\-h\fP and \fB\-t\fP options, when used by themselves or with
+each other, override any default listing of member files; only the header
+and/or footer are printed.  This behavior is useful when \fIzipinfo\fP is
+used with a wildcard zipfile specification; the contents of all zipfiles
+are then summarized with a single command.
+.PP
+To list information on a single file within the archive, in medium format,
+specify the filename explicitly:
+.PP
+.EX
+zipinfo \-m storage unshrink.c
+.EE
+.PP
+The specification of any member file, as in this example, will override
+the default header and totals lines; only the single line of information
+about the requested file will be printed.  This is intuitively what one
+would expect when requesting information about a single file.  For multiple
+files, it is often useful to know the total compressed and uncompressed
+size; in such cases \fB\-t\fP may be specified explicitly:
+.PP
+.EX
+zipinfo \-mt storage "*.[ch]" Mak\e*
+.EE
+.PP
+To get maximal information about the ZIP archive, use the verbose
+option.  It is usually wise to pipe the output into a filter such as
+Unix \fImore\fP(1) if the operating system allows it:
+.PP
+.EX
+zipinfo \-v storage | more
+.EE
+.PP
+Finally, to see the most recently modified files in the archive, use
+the \fB\-T\fP option in conjunction with an external sorting utility
+such as Unix \fIsort\fP(1) (and \fIsed\fP(1) as well, in this example):
+.PP
+.EX
+zipinfo \-T storage | sort -nr -k 7 | sed 15q
+.EE
+.PP
+The \fB\-nr\fP option to \fIsort\fP(1) tells it to sort numerically
+in reverse order rather than in textual order, and the \fB\-k\ 7\fP option
+tells it to sort on the seventh field.  This
+assumes the default short-listing format; if \fB\-m\fP or \fB\-l\fP is
+used, the proper \fIsort\fP(1) option would be \fB\-k\ 8\fP.
+Older versions of \fIsort\fP(1) do not support the \fB\-k\fP option,
+but you can use the traditional \fB\+\fP option instead, e.g.,
+\fB\+6\fP instead of \fB\-k\ 7\fP.  The \fIsed\fP(1)
+command filters out all but the first 15 lines of the listing.  Future
+releases of \fIzipinfo\fP may incorporate date/time and filename sorting
+as built-in options.
+.PD
+.\" =========================================================================
+.SH TIPS
+The author finds it convenient to define an alias \fIii\fP for \fIzipinfo\fP
+on systems that allow aliases (or, on other systems, copy/rename the
+executable, create a link or create a command file with the name \fIii\fP).
+The \fIii\fP usage parallels the common \fIll\fP alias for long listings in
+Unix, and the similarity between the outputs of the two commands was
+intentional.
+.PD
+.\" =========================================================================
+.SH BUGS
+As with \fIunzip\fP, \fIzipinfo\fP's \fB\-M\fP (``more'') option is overly
+simplistic in its handling of screen output; as noted above, it fails to detect
+the wrapping of long lines and may thereby cause lines at the top of the screen
+to be scrolled off before being read.  \fIzipinfo\fP should detect and treat
+each occurrence of line-wrap as one additional line printed.  This requires
+knowledge of the screen's width as well as its height.  In addition,
+\fIzipinfo\fP should detect the true screen geometry on all systems.
+.PP
+\fIzipinfo\fP's listing-format behavior is unnecessarily complex and should
+be simplified.  (This is not to say that it will be.)
+.PP
+.\" =========================================================================
+.SH "SEE ALSO"
+\fIls\fP(1), \fIfunzip\fP(1L), \fIunzip\fP(1L), \fIunzipsfx\fP(1L),
+\fIzip\fP(1L), \fIzipcloak\fP(1L), \fIzipnote\fP(1L), \fIzipsplit\fP(1L)
+.PD
+.\" =========================================================================
+.SH URL
+The Info-ZIP home page is currently at
+.EX
+\fChttp://www.info-zip.org/pub/infozip/\fR
+.EE
+or
+.EX
+\fCftp://ftp.info-zip.org/pub/infozip/\fR .
+.EE
+.PD
+.\" =========================================================================
+.SH AUTHOR
+Greg ``Cave Newt'' Roelofs.  ZipInfo contains pattern-matching code
+by Mark Adler and fixes/improvements by many others.  Please refer to the
+CONTRIBS file in the UnZip source distribution for a more complete list.
diff --git a/upstream/mageia-cauldron/man1/zless.1 b/upstream/mageia-cauldron/man1/zless.1
new file mode 100644
index 00000000..42c5fb70
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zless.1
@@ -0,0 +1,58 @@
+.TH ZLESS 1
+.SH NAME
+zless \- file perusal filter for crt viewing of compressed text
+.SH SYNOPSIS
+.B zless
+[ name ...  ]
+.SH DESCRIPTION
+The
+.B zless
+command
+is a filter which allows examination of compressed or plain text files
+one screenful at a time on a soft-copy terminal.  It is the equivalent of
+setting the environment variable LESSOPEN to '|gzip -cdfq -- %s',
+and the environment variable LESSMETACHARS to
+\&'<space><tab><newline>;*?"()<>[|&^`#\e$%=~',
+and then running
+.BR less .
+However, enough people seem to think that having the
+command
+.B zless
+available is important to be worth providing it.
+.SH "SEE ALSO"
+.BR zmore (1),
+.BR less (1)
+.SH "BUGS"
+The
+.B zless
+command
+does not work with compressed data that is piped to it via standard
+input; it requires that input files be specified as arguments.
+To read compressed data from a pipe, you can use
+.RB ".\|.\|." "|gunzip|less"
+instead of
+.RB ".\|.\|." "|zless" .
+.SH "COPYRIGHT NOTICE"
+Copyright \(co 2006-2007, 2015-2023 Free Software Foundation, Inc.
+.br
+Copyright \(co 1992, 1993 Jean-loup Gailly
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.
diff --git a/upstream/mageia-cauldron/man1/zmore.1 b/upstream/mageia-cauldron/man1/zmore.1
new file mode 100644
index 00000000..c387dd1a
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zmore.1
@@ -0,0 +1,148 @@
+.TH ZMORE 1
+.SH NAME
+zmore \- file perusal filter for crt viewing of compressed text
+.SH SYNOPSIS
+.B zmore
+[ name ...  ]
+.SH DESCRIPTION
+The
+.I zmore
+command
+is a filter which allows examination of compressed or plain text files
+one screenful at a time on a soft-copy terminal.
+The
+.B zmore
+command
+works on files compressed with
+.BR compress ,
+.B pack
+or
+.BR gzip ,
+and also on uncompressed files.
+If a file does not exist,
+.B zmore
+looks for a file of the same name with the addition of a .gz, .z or .Z suffix.
+.PP
+The
+.B zmore
+command
+normally pauses after each screenful, printing --More--
+at the bottom of the screen.
+If the user then types a carriage return, one more line is displayed.
+If the user hits a space,
+another screenful is displayed.  Other possibilities are enumerated later.
+.PP
+The
+.B zmore
+command
+looks in the file
+.I /etc/termcap
+to determine terminal characteristics,
+and to determine the default window size.
+On a terminal capable of displaying 24 lines,
+the default window size is 22 lines.
+To use a pager other than the default
+.BR more ,
+set environment variable PAGER to the name of the desired program, such as
+.BR less .
+.PP
+Other sequences which may be typed when
+.B zmore
+pauses, and their effects, are as follows (\fIi\fP is an optional integer
+argument, defaulting to 1) :
+.PP
+.IP \fIi\^\fP<space>
+display
+.I i
+more lines, (or another screenful if no argument is given)
+.PP
+.IP ^D
+display 11 more lines (a ``scroll'').
+If
+.I i
+is given, then the scroll size is set to \fIi\fP.
+.PP
+.IP d
+same as ^D (control-D)
+.PP
+.IP \fIi\^\fPz
+same as typing a space except that \fIi\fP, if present, becomes the new
+window size.
+.PP
+.IP \fIi\^\fPs
+skip \fIi\fP lines and print a screenful of lines
+.PP
+.IP \fIi\^\fPf
+skip \fIi\fP screenfuls and print a screenful of lines
+.PP
+.IP "q or Q"
+Quit.
+.PP
+.IP =
+Display the current line number.
+.PP
+.IP \fIi\fP/expr
+search for the \fIi\^\fP-th occurrence of the regular expression \fIexpr.\fP
+The user's erase and kill characters may be used to edit the regular
+expression.
+Erasing back past the first column cancels the search command.
+.PP
+.IP \fIi\^\fPn
+search for the \fIi\^\fP-th occurrence of the last regular expression entered.
+.PP
+.IP !command
+invoke a shell with \fIcommand\fP.
+The character `!' in "command" is replaced with the
+previous shell command.  The sequence "\\!" is replaced by "!".
+.PP
+.IP ":q or :Q"
+Quit
+(same as q or Q).
+.PP
+.IP .
+(dot) repeat the previous command.
+.PP
+The commands take effect immediately, i.e., it is not necessary to
+type a carriage return.
+Up to the time when the command character itself is given,
+the user may hit the line kill character to cancel the numerical
+argument being formed.
+In addition, the user may hit the erase character to redisplay the
+--More-- message.
+.PP
+At any time when output is being sent to the terminal, the user can
+hit the quit key (normally control\-\\).
+The
+.I zmore
+command
+will stop sending output, and will display the usual --More--
+prompt.
+The user may then enter one of the above commands in the normal manner.
+Unfortunately, some output is lost when this is done, due to the
+fact that any characters waiting in the terminal's output queue
+are flushed when the quit signal occurs.
+.PP
+The terminal is set to
+.I noecho
+mode by this program so that the output can be continuous.
+What you type will thus not show on your terminal, except for the / and !
+commands.
+.PP
+If the standard output is not a teletype, then
+.B zmore
+acts just like
+.BR zcat ,
+except that a header is printed before each file
+if there is more than one file.
+.SH FILES
+.TP
+/etc/termcap
+Terminal data base
+.SH "SEE ALSO"
+.BR more (1),
+.BR gzip (1),
+.BR zdiff (1),
+.BR zgrep (1),
+.BR znew (1),
+.BR zforce (1),
+.BR gzexe (1)
diff --git a/upstream/mageia-cauldron/man1/znew.1 b/upstream/mageia-cauldron/man1/znew.1
new file mode 100644
index 00000000..72419c9f
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/znew.1
@@ -0,0 +1,55 @@
+.TH ZNEW 1
+.SH NAME
+znew \-   recompress .Z files to .gz files
+.SH SYNOPSIS
+.B znew
+[ -ftv9PK] [ name.Z ...  ]
+.SH DESCRIPTION
+The
+.B Znew
+command
+recompresses files from .Z (compress) format to .gz (gzip) format.
+If you want to recompress a file already in gzip format, rename the file
+to force a .Z extension then apply znew.
+.SH OPTIONS
+.TP
+.B \-f
+Force recompression from .Z to .gz format even if a .gz file already exists.
+.TP
+.B \-t
+Tests the new files before deleting originals.
+.TP
+.B \-v
+Verbose. Display the name and percentage reduction for each file compressed.
+.TP
+.B \-9
+Use the slowest compression method (optimal compression).
+.TP
+.B \-P
+Use pipes for the conversion to reduce disk space usage.
+.TP
+.B \-K
+Keep a .Z file when it is smaller than the .gz file; implies
+.BR -t .
+.SH "SEE ALSO"
+.BR gzip (1),
+.BR zmore (1),
+.BR zdiff (1),
+.BR zgrep (1),
+.BR zforce (1),
+.BR gzexe (1),
+.BR compress(1)
+.SH BUGS
+If the
+.B \-P
+option is used,
+.B znew
+does not maintain the timestamp if
+.BR touch (1)
+does not support the
+.B \-r
+option, and does not maintain permissions if
+.BR chmod (1)
+does not support the
+.B \-\-reference
+option.
diff --git a/upstream/mageia-cauldron/man1/zstd.1 b/upstream/mageia-cauldron/man1/zstd.1
new file mode 100644
index 00000000..286c6e3d
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zstd.1
@@ -0,0 +1,388 @@
+.TH "ZSTD" "1" "March 2023" "zstd 1.5.5" "User Commands"
+.SH "NAME"
+\fBzstd\fR \- zstd, zstdmt, unzstd, zstdcat \- Compress or decompress \.zst files
+.SH "SYNOPSIS"
+.TS
+allbox;
+\fBzstd\fR [\fIOPTIONS\fR] [\-	\fIINPUT\-FILE\fR] [\-o \fIOUTPUT\-FILE\fR]
+.TE
+.P
+\fBzstdmt\fR is equivalent to \fBzstd \-T0\fR
+.P
+\fBunzstd\fR is equivalent to \fBzstd \-d\fR
+.P
+\fBzstdcat\fR is equivalent to \fBzstd \-dcf\fR
+.SH "DESCRIPTION"
+\fBzstd\fR is a fast lossless compression algorithm and data compression tool, with command line syntax similar to \fBgzip\fR(1) and \fBxz\fR(1)\. It is based on the \fBLZ77\fR family, with further FSE & huff0 entropy stages\. \fBzstd\fR offers highly configurable compression speed, from fast modes at > 200 MB/s per core, to strong modes with excellent compression ratios\. It also features a very fast decoder, with speeds > 500 MB/s per core\.
+.P
+\fBzstd\fR command line syntax is generally similar to gzip, but features the following differences:
+.IP "\[ci]" 4
+Source files are preserved by default\. It\'s possible to remove them automatically by using the \fB\-\-rm\fR command\.
+.IP "\[ci]" 4
+When compressing a single file, \fBzstd\fR displays progress notifications and result summary by default\. Use \fB\-q\fR to turn them off\.
+.IP "\[ci]" 4
+\fBzstd\fR displays a short help page when command line is an error\. Use \fB\-q\fR to turn it off\.
+.IP "\[ci]" 4
+\fBzstd\fR does not accept input from console, though it does accept \fBstdin\fR when it\'s not the console\.
+.IP "\[ci]" 4
+\fBzstd\fR does not store the input\'s filename or attributes, only its contents\.
+.IP "" 0
+.P
+\fBzstd\fR processes each \fIfile\fR according to the selected operation mode\. If no \fIfiles\fR are given or \fIfile\fR is \fB\-\fR, \fBzstd\fR reads from standard input and writes the processed data to standard output\. \fBzstd\fR will refuse to write compressed data to standard output if it is a terminal: it will display an error message and skip the file\. Similarly, \fBzstd\fR will refuse to read compressed data from standard input if it is a terminal\.
+.P
+Unless \fB\-\-stdout\fR or \fB\-o\fR is specified, \fIfiles\fR are written to a new file whose name is derived from the source \fIfile\fR name:
+.IP "\[ci]" 4
+When compressing, the suffix \fB\.zst\fR is appended to the source filename to get the target filename\.
+.IP "\[ci]" 4
+When decompressing, the \fB\.zst\fR suffix is removed from the source filename to get the target filename
+.IP "" 0
+.SS "Concatenation with \.zst Files"
+It is possible to concatenate multiple \fB\.zst\fR files\. \fBzstd\fR will decompress such agglomerated file as if it was a single \fB\.zst\fR file\.
+.SH "OPTIONS"
+.SS "Integer Suffixes and Special Values"
+In most places where an integer argument is expected, an optional suffix is supported to easily indicate large integers\. There must be no space between the integer and the suffix\.
+.TP
+\fBKiB\fR
+Multiply the integer by 1,024 (2\e^10)\. \fBKi\fR, \fBK\fR, and \fBKB\fR are accepted as synonyms for \fBKiB\fR\.
+.TP
+\fBMiB\fR
+Multiply the integer by 1,048,576 (2\e^20)\. \fBMi\fR, \fBM\fR, and \fBMB\fR are accepted as synonyms for \fBMiB\fR\.
+.SS "Operation Mode"
+If multiple operation mode options are given, the last one takes effect\.
+.TP
+\fB\-z\fR, \fB\-\-compress\fR
+Compress\. This is the default operation mode when no operation mode option is specified and no other operation mode is implied from the command name (for example, \fBunzstd\fR implies \fB\-\-decompress\fR)\.
+.TP
+\fB\-d\fR, \fB\-\-decompress\fR, \fB\-\-uncompress\fR
+Decompress\.
+.TP
+\fB\-t\fR, \fB\-\-test\fR
+Test the integrity of compressed \fIfiles\fR\. This option is equivalent to \fB\-\-decompress \-\-stdout > /dev/null\fR, decompressed data is discarded and checksummed for errors\. No files are created or removed\.
+.TP
+\fB\-b#\fR
+Benchmark file(s) using compression level \fI#\fR\. See \fIBENCHMARK\fR below for a description of this operation\.
+.TP
+\fB\-\-train FILES\fR
+Use \fIFILES\fR as a training set to create a dictionary\. The training set should contain a lot of small files (> 100)\. See \fIDICTIONARY BUILDER\fR below for a description of this operation\.
+.TP
+\fB\-l\fR, \fB\-\-list\fR
+Display information related to a zstd compressed file, such as size, ratio, and checksum\. Some of these fields may not be available\. This command\'s output can be augmented with the \fB\-v\fR modifier\.
+.SS "Operation Modifiers"
+.IP "\[ci]" 4
+\fB\-#\fR: selects \fB#\fR compression level [1\-19] (default: 3)
+.IP "\[ci]" 4
+\fB\-\-ultra\fR: unlocks high compression levels 20+ (maximum 22), using a lot more memory\. Note that decompression will also require more memory when using these levels\.
+.IP "\[ci]" 4
+\fB\-\-fast[=#]\fR: switch to ultra\-fast compression levels\. If \fB=#\fR is not present, it defaults to \fB1\fR\. The higher the value, the faster the compression speed, at the cost of some compression ratio\. This setting overwrites compression level if one was set previously\. Similarly, if a compression level is set after \fB\-\-fast\fR, it overrides it\.
+.IP "\[ci]" 4
+\fB\-T#\fR, \fB\-\-threads=#\fR: Compress using \fB#\fR working threads (default: 1)\. If \fB#\fR is 0, attempt to detect and use the number of physical CPU cores\. In all cases, the nb of threads is capped to \fBZSTDMT_NBWORKERS_MAX\fR, which is either 64 in 32\-bit mode, or 256 for 64\-bit environments\. This modifier does nothing if \fBzstd\fR is compiled without multithread support\.
+.IP "\[ci]" 4
+\fB\-\-single\-thread\fR: Use a single thread for both I/O and compression\. As compression is serialized with I/O, this can be slightly slower\. Single\-thread mode features significantly lower memory usage, which can be useful for systems with limited amount of memory, such as 32\-bit systems\.
+.IP
+Note 1: this mode is the only available one when multithread support is disabled\.
+.IP
+Note 2: this mode is different from \fB\-T1\fR, which spawns 1 compression thread in parallel with I/O\. Final compressed result is also slightly different from \fB\-T1\fR\.
+.IP "\[ci]" 4
+\fB\-\-auto\-threads={physical,logical} (default: physical)\fR: When using a default amount of threads via \fB\-T0\fR, choose the default based on the number of detected physical or logical cores\.
+.IP "\[ci]" 4
+\fB\-\-adapt[=min=#,max=#]\fR: \fBzstd\fR will dynamically adapt compression level to perceived I/O conditions\. Compression level adaptation can be observed live by using command \fB\-v\fR\. Adaptation can be constrained between supplied \fBmin\fR and \fBmax\fR levels\. The feature works when combined with multi\-threading and \fB\-\-long\fR mode\. It does not work with \fB\-\-single\-thread\fR\. It sets window size to 8 MiB by default (can be changed manually, see \fBwlog\fR)\. Due to the chaotic nature of dynamic adaptation, compressed result is not reproducible\.
+.IP
+\fINote\fR: at the time of this writing, \fB\-\-adapt\fR can remain stuck at low speed when combined with multiple worker threads (>=2)\.
+.IP "\[ci]" 4
+\fB\-\-long[=#]\fR: enables long distance matching with \fB#\fR \fBwindowLog\fR, if \fB#\fR is not present it defaults to \fB27\fR\. This increases the window size (\fBwindowLog\fR) and memory usage for both the compressor and decompressor\. This setting is designed to improve the compression ratio for files with long matches at a large distance\.
+.IP
+Note: If \fBwindowLog\fR is set to larger than 27, \fB\-\-long=windowLog\fR or \fB\-\-memory=windowSize\fR needs to be passed to the decompressor\.
+.IP "\[ci]" 4
+\fB\-D DICT\fR: use \fBDICT\fR as Dictionary to compress or decompress FILE(s)
+.IP "\[ci]" 4
+\fB\-\-patch\-from FILE\fR: Specify the file to be used as a reference point for zstd\'s diff engine\. This is effectively dictionary compression with some convenient parameter selection, namely that \fIwindowSize\fR > \fIsrcSize\fR\.
+.IP
+Note: cannot use both this and \fB\-D\fR together\.
+.IP
+Note: \fB\-\-long\fR mode will be automatically activated if \fIchainLog\fR < \fIfileLog\fR (\fIfileLog\fR being the \fIwindowLog\fR required to cover the whole file)\. You can also manually force it\.
+.IP
+Note: for all levels, you can use \fB\-\-patch\-from\fR in \fB\-\-single\-thread\fR mode to improve compression ratio at the cost of speed\.
+.IP
+Note: for level 19, you can get increased compression ratio at the cost of speed by specifying \fB\-\-zstd=targetLength=\fR to be something large (i\.e\. 4096), and by setting a large \fB\-\-zstd=chainLog=\fR\.
+.IP "\[ci]" 4
+\fB\-\-rsyncable\fR: \fBzstd\fR will periodically synchronize the compression state to make the compressed file more rsync\-friendly\. There is a negligible impact to compression ratio, and a potential impact to compression speed, perceptible at higher speeds, for example when combining \fB\-\-rsyncable\fR with many parallel worker threads\. This feature does not work with \fB\-\-single\-thread\fR\. You probably don\'t want to use it with long range mode, since it will decrease the effectiveness of the synchronization points, but your mileage may vary\.
+.IP "\[ci]" 4
+\fB\-C\fR, \fB\-\-[no\-]check\fR: add integrity check computed from uncompressed data (default: enabled)
+.IP "\[ci]" 4
+\fB\-\-[no\-]content\-size\fR: enable / disable whether or not the original size of the file is placed in the header of the compressed file\. The default option is \fB\-\-content\-size\fR (meaning that the original size will be placed in the header)\.
+.IP "\[ci]" 4
+\fB\-\-no\-dictID\fR: do not store dictionary ID within frame header (dictionary compression)\. The decoder will have to rely on implicit knowledge about which dictionary to use, it won\'t be able to check if it\'s correct\.
+.IP "\[ci]" 4
+\fB\-M#\fR, \fB\-\-memory=#\fR: Set a memory usage limit\. By default, \fBzstd\fR uses 128 MiB for decompression as the maximum amount of memory the decompressor is allowed to use, but you can override this manually if need be in either direction (i\.e\. you can increase or decrease it)\.
+.IP
+This is also used during compression when using with \fB\-\-patch\-from=\fR\. In this case, this parameter overrides that maximum size allowed for a dictionary\. (128 MiB)\.
+.IP
+Additionally, this can be used to limit memory for dictionary training\. This parameter overrides the default limit of 2 GiB\. zstd will load training samples up to the memory limit and ignore the rest\.
+.IP "\[ci]" 4
+\fB\-\-stream\-size=#\fR: Sets the pledged source size of input coming from a stream\. This value must be exact, as it will be included in the produced frame header\. Incorrect stream sizes will cause an error\. This information will be used to better optimize compression parameters, resulting in better and potentially faster compression, especially for smaller source sizes\.
+.IP "\[ci]" 4
+\fB\-\-size\-hint=#\fR: When handling input from a stream, \fBzstd\fR must guess how large the source size will be when optimizing compression parameters\. If the stream size is relatively small, this guess may be a poor one, resulting in a higher compression ratio than expected\. This feature allows for controlling the guess when needed\. Exact guesses result in better compression ratios\. Overestimates result in slightly degraded compression ratios, while underestimates may result in significant degradation\.
+.IP "\[ci]" 4
+\fB\-o FILE\fR: save result into \fBFILE\fR\.
+.IP "\[ci]" 4
+\fB\-f\fR, \fB\-\-force\fR: disable input and output checks\. Allows overwriting existing files, input from console, output to stdout, operating on links, block devices, etc\. During decompression and when the output destination is stdout, pass\-through unrecognized formats as\-is\.
+.IP "\[ci]" 4
+\fB\-c\fR, \fB\-\-stdout\fR: write to standard output (even if it is the console); keep original files unchanged\.
+.IP "\[ci]" 4
+\fB\-\-[no\-]sparse\fR: enable / disable sparse FS support, to make files with many zeroes smaller on disk\. Creating sparse files may save disk space and speed up decompression by reducing the amount of disk I/O\. default: enabled when output is into a file, and disabled when output is stdout\. This setting overrides default and can force sparse mode over stdout\.
+.IP "\[ci]" 4
+\fB\-\-[no\-]pass\-through\fR enable / disable passing through uncompressed files as\-is\. During decompression when pass\-through is enabled, unrecognized formats will be copied as\-is from the input to the output\. By default, pass\-through will occur when the output destination is stdout and the force (\fB\-f\fR) option is set\.
+.IP "\[ci]" 4
+\fB\-\-rm\fR: remove source file(s) after successful compression or decompression\. This command is silently ignored if output is \fBstdout\fR\. If used in combination with \fB\-o\fR, triggers a confirmation prompt (which can be silenced with \fB\-f\fR), as this is a destructive operation\.
+.IP "\[ci]" 4
+\fB\-k\fR, \fB\-\-keep\fR: keep source file(s) after successful compression or decompression\. This is the default behavior\.
+.IP "\[ci]" 4
+\fB\-r\fR: operate recursively on directories\. It selects all files in the named directory and all its subdirectories\. This can be useful both to reduce command line typing, and to circumvent shell expansion limitations, when there are a lot of files and naming breaks the maximum size of a command line\.
+.IP "\[ci]" 4
+\fB\-\-filelist FILE\fR read a list of files to process as content from \fBFILE\fR\. Format is compatible with \fBls\fR output, with one file per line\.
+.IP "\[ci]" 4
+\fB\-\-output\-dir\-flat DIR\fR: resulting files are stored into target \fBDIR\fR directory, instead of same directory as origin file\. Be aware that this command can introduce name collision issues, if multiple files, from different directories, end up having the same name\. Collision resolution ensures first file with a given name will be present in \fBDIR\fR, while in combination with \fB\-f\fR, the last file will be present instead\.
+.IP "\[ci]" 4
+\fB\-\-output\-dir\-mirror DIR\fR: similar to \fB\-\-output\-dir\-flat\fR, the output files are stored underneath target \fBDIR\fR directory, but this option will replicate input directory hierarchy into output \fBDIR\fR\.
+.IP
+If input directory contains "\.\.", the files in this directory will be ignored\. If input directory is an absolute directory (i\.e\. "/var/tmp/abc"), it will be stored into the "output\-dir/var/tmp/abc"\. If there are multiple input files or directories, name collision resolution will follow the same rules as \fB\-\-output\-dir\-flat\fR\.
+.IP "\[ci]" 4
+\fB\-\-format=FORMAT\fR: compress and decompress in other formats\. If compiled with support, zstd can compress to or decompress from other compression algorithm formats\. Possibly available options are \fBzstd\fR, \fBgzip\fR, \fBxz\fR, \fBlzma\fR, and \fBlz4\fR\. If no such format is provided, \fBzstd\fR is the default\.
+.IP "\[ci]" 4
+\fB\-h\fR/\fB\-H\fR, \fB\-\-help\fR: display help/long help and exit
+.IP "\[ci]" 4
+\fB\-V\fR, \fB\-\-version\fR: display version number and exit\. Advanced: \fB\-vV\fR also displays supported formats\. \fB\-vvV\fR also displays POSIX support\. \fB\-q\fR will only display the version number, suitable for machine reading\.
+.IP "\[ci]" 4
+\fB\-v\fR, \fB\-\-verbose\fR: verbose mode, display more information
+.IP "\[ci]" 4
+\fB\-q\fR, \fB\-\-quiet\fR: suppress warnings, interactivity, and notifications\. specify twice to suppress errors too\.
+.IP "\[ci]" 4
+\fB\-\-no\-progress\fR: do not display the progress bar, but keep all other messages\.
+.IP "\[ci]" 4
+\fB\-\-show\-default\-cparams\fR: shows the default compression parameters that will be used for a particular input file, based on the provided compression level and the input size\. If the provided file is not a regular file (e\.g\. a pipe), this flag will output the parameters used for inputs of unknown size\.
+.IP "\[ci]" 4
+\fB\-\-\fR: All arguments after \fB\-\-\fR are treated as files
+
+.SH Parallel Zstd OPTIONS
+Additional options for the pzstd utility
+.TP
+.BR \-p ", " --processes
+ number of threads to use for (de)compression (default:4)
+
+.IP "" 0
+.SS "gzip Operation Modifiers"
+When invoked via a \fBgzip\fR symlink, \fBzstd\fR will support further options that intend to mimic the \fBgzip\fR behavior:
+.TP
+\fB\-n\fR, \fB\-\-no\-name\fR
+do not store the original filename and timestamps when compressing a file\. This is the default behavior and hence a no\-op\.
+.TP
+\fB\-\-best\fR
+alias to the option \fB\-9\fR\.
+.SS "Environment Variables"
+Employing environment variables to set parameters has security implications\. Therefore, this avenue is intentionally limited\. Only \fBZSTD_CLEVEL\fR and \fBZSTD_NBTHREADS\fR are currently supported\. They set the compression level and number of threads to use during compression, respectively\.
+.P
+\fBZSTD_CLEVEL\fR can be used to set the level between 1 and 19 (the "normal" range)\. If the value of \fBZSTD_CLEVEL\fR is not a valid integer, it will be ignored with a warning message\. \fBZSTD_CLEVEL\fR just replaces the default compression level (\fB3\fR)\.
+.P
+\fBZSTD_NBTHREADS\fR can be used to set the number of threads \fBzstd\fR will attempt to use during compression\. If the value of \fBZSTD_NBTHREADS\fR is not a valid unsigned integer, it will be ignored with a warning message\. \fBZSTD_NBTHREADS\fR has a default value of (\fB1\fR), and is capped at ZSTDMT_NBWORKERS_MAX==200\. \fBzstd\fR must be compiled with multithread support for this to have any effect\.
+.P
+They can both be overridden by corresponding command line arguments: \fB\-#\fR for compression level and \fB\-T#\fR for number of compression threads\.
+.SH "DICTIONARY BUILDER"
+\fBzstd\fR offers \fIdictionary\fR compression, which greatly improves efficiency on small files and messages\. It\'s possible to train \fBzstd\fR with a set of samples, the result of which is saved into a file called a \fBdictionary\fR\. Then, during compression and decompression, reference the same dictionary, using command \fB\-D dictionaryFileName\fR\. Compression of small files similar to the sample set will be greatly improved\.
+.TP
+\fB\-\-train FILEs\fR
+Use FILEs as training set to create a dictionary\. The training set should ideally contain a lot of samples (> 100), and weight typically 100x the target dictionary size (for example, ~10 MB for a 100 KB dictionary)\. \fB\-\-train\fR can be combined with \fB\-r\fR to indicate a directory rather than listing all the files, which can be useful to circumvent shell expansion limits\.
+.IP
+Since dictionary compression is mostly effective for small files, the expectation is that the training set will only contain small files\. In the case where some samples happen to be large, only the first 128 KiB of these samples will be used for training\.
+.IP
+\fB\-\-train\fR supports multithreading if \fBzstd\fR is compiled with threading support (default)\. Additional advanced parameters can be specified with \fB\-\-train\-fastcover\fR\. The legacy dictionary builder can be accessed with \fB\-\-train\-legacy\fR\. The slower cover dictionary builder can be accessed with \fB\-\-train\-cover\fR\. Default \fB\-\-train\fR is equivalent to \fB\-\-train\-fastcover=d=8,steps=4\fR\.
+.TP
+\fB\-o FILE\fR
+Dictionary saved into \fBFILE\fR (default name: dictionary)\.
+.TP
+\fB\-\-maxdict=#\fR
+Limit dictionary to specified size (default: 112640 bytes)\. As usual, quantities are expressed in bytes by default, and it\'s possible to employ suffixes (like \fBKB\fR or \fBMB\fR) to specify larger values\.
+.TP
+\fB\-#\fR
+Use \fB#\fR compression level during training (optional)\. Will generate statistics more tuned for selected compression level, resulting in a \fIsmall\fR compression ratio improvement for this level\.
+.TP
+\fB\-B#\fR
+Split input files into blocks of size # (default: no split)
+.TP
+\fB\-M#\fR, \fB\-\-memory=#\fR
+Limit the amount of sample data loaded for training (default: 2 GB)\. Note that the default (2 GB) is also the maximum\. This parameter can be useful in situations where the training set size is not well controlled and could be potentially very large\. Since speed of the training process is directly correlated to the size of the training sample set, a smaller sample set leads to faster training\.
+.IP
+In situations where the training set is larger than maximum memory, the CLI will randomly select samples among the available ones, up to the maximum allowed memory budget\. This is meant to improve dictionary relevance by mitigating the potential impact of clustering, such as selecting only files from the beginning of a list sorted by modification date, or sorted by alphabetical order\. The randomization process is deterministic, so training of the same list of files with the same parameters will lead to the creation of the same dictionary\.
+.TP
+\fB\-\-dictID=#\fR
+A dictionary ID is a locally unique ID\. The decoder will use this value to verify it is using the right dictionary\. By default, zstd will create a 4\-bytes random number ID\. It\'s possible to provide an explicit number ID instead\. It\'s up to the dictionary manager to not assign twice the same ID to 2 different dictionaries\. Note that short numbers have an advantage: an ID < 256 will only need 1 byte in the compressed frame header, and an ID < 65536 will only need 2 bytes\. This compares favorably to 4 bytes default\.
+.IP
+Note that RFC8878 reserves IDs less than 32768 and greater than or equal to 2\e^31, so they should not be used in public\.
+.TP
+\fB\-\-train\-cover[=k#,d=#,steps=#,split=#,shrink[=#]]\fR
+Select parameters for the default dictionary builder algorithm named cover\. If \fId\fR is not specified, then it tries \fId\fR = 6 and \fId\fR = 8\. If \fIk\fR is not specified, then it tries \fIsteps\fR values in the range [50, 2000]\. If \fIsteps\fR is not specified, then the default value of 40 is used\. If \fIsplit\fR is not specified or split <= 0, then the default value of 100 is used\. Requires that \fId\fR <= \fIk\fR\. If \fIshrink\fR flag is not used, then the default value for \fIshrinkDict\fR of 0 is used\. If \fIshrink\fR is not specified, then the default value for \fIshrinkDictMaxRegression\fR of 1 is used\.
+.IP
+Selects segments of size \fIk\fR with highest score to put in the dictionary\. The score of a segment is computed by the sum of the frequencies of all the subsegments of size \fId\fR\. Generally \fId\fR should be in the range [6, 8], occasionally up to 16, but the algorithm will run faster with d <= \fI8\fR\. Good values for \fIk\fR vary widely based on the input data, but a safe range is [2 * \fId\fR, 2000]\. If \fIsplit\fR is 100, all input samples are used for both training and testing to find optimal \fId\fR and \fIk\fR to build dictionary\. Supports multithreading if \fBzstd\fR is compiled with threading support\. Having \fIshrink\fR enabled takes a truncated dictionary of minimum size and doubles in size until compression ratio of the truncated dictionary is at most \fIshrinkDictMaxRegression%\fR worse than the compression ratio of the largest dictionary\.
+.IP
+Examples:
+.IP
+\fBzstd \-\-train\-cover FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=k=50,d=8 FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=d=8,steps=500 FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=k=50 FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=k=50,split=60 FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=shrink FILEs\fR
+.IP
+\fBzstd \-\-train\-cover=shrink=2 FILEs\fR
+.TP
+\fB\-\-train\-fastcover[=k#,d=#,f=#,steps=#,split=#,accel=#]\fR
+Same as cover but with extra parameters \fIf\fR and \fIaccel\fR and different default value of split If \fIsplit\fR is not specified, then it tries \fIsplit\fR = 75\. If \fIf\fR is not specified, then it tries \fIf\fR = 20\. Requires that 0 < \fIf\fR < 32\. If \fIaccel\fR is not specified, then it tries \fIaccel\fR = 1\. Requires that 0 < \fIaccel\fR <= 10\. Requires that \fId\fR = 6 or \fId\fR = 8\.
+.IP
+\fIf\fR is log of size of array that keeps track of frequency of subsegments of size \fId\fR\. The subsegment is hashed to an index in the range [0,2^\fIf\fR \- 1]\. It is possible that 2 different subsegments are hashed to the same index, and they are considered as the same subsegment when computing frequency\. Using a higher \fIf\fR reduces collision but takes longer\.
+.IP
+Examples:
+.IP
+\fBzstd \-\-train\-fastcover FILEs\fR
+.IP
+\fBzstd \-\-train\-fastcover=d=8,f=15,accel=2 FILEs\fR
+.TP
+\fB\-\-train\-legacy[=selectivity=#]\fR
+Use legacy dictionary builder algorithm with the given dictionary \fIselectivity\fR (default: 9)\. The smaller the \fIselectivity\fR value, the denser the dictionary, improving its efficiency but reducing its achievable maximum size\. \fB\-\-train\-legacy=s=#\fR is also accepted\.
+.IP
+Examples:
+.IP
+\fBzstd \-\-train\-legacy FILEs\fR
+.IP
+\fBzstd \-\-train\-legacy=selectivity=8 FILEs\fR
+.SH "BENCHMARK"
+.TP
+\fB\-b#\fR
+benchmark file(s) using compression level #
+.TP
+\fB\-e#\fR
+benchmark file(s) using multiple compression levels, from \fB\-b#\fR to \fB\-e#\fR (inclusive)
+.TP
+\fB\-i#\fR
+minimum evaluation time, in seconds (default: 3s), benchmark mode only
+.TP
+\fB\-B#\fR, \fB\-\-block\-size=#\fR
+cut file(s) into independent chunks of size # (default: no chunking)
+.TP
+\fB\-\-priority=rt\fR
+set process priority to real\-time
+.P
+\fBOutput Format:\fR CompressionLevel#Filename: InputSize \-> OutputSize (CompressionRatio), CompressionSpeed, DecompressionSpeed
+.P
+\fBMethodology:\fR For both compression and decompression speed, the entire input is compressed/decompressed in\-memory to measure speed\. A run lasts at least 1 sec, so when files are small, they are compressed/decompressed several times per run, in order to improve measurement accuracy\.
+.SH "ADVANCED COMPRESSION OPTIONS"
+### \-B#: Specify the size of each compression job\. This parameter is only available when multi\-threading is enabled\. Each compression job is run in parallel, so this value indirectly impacts the nb of active threads\. Default job size varies depending on compression level (generally \fB4 * windowSize\fR)\. \fB\-B#\fR makes it possible to manually select a custom size\. Note that job size must respect a minimum value which is enforced transparently\. This minimum is either 512 KB, or \fBoverlapSize\fR, whichever is largest\. Different job sizes will lead to non\-identical compressed frames\.
+.SS "\-\-zstd[=options]:"
+\fBzstd\fR provides 22 predefined regular compression levels plus the fast levels\. This compression level is translated internally into a number of specific parameters that actually control the behavior of the compressor\. (You can see the result of this translation with \fB\-\-show\-default\-cparams\fR\.) These specific parameters can be overridden with advanced compression options\. The \fIoptions\fR are provided as a comma\-separated list\. You may specify only the options you want to change and the rest will be taken from the selected or default compression level\. The list of available \fIoptions\fR:
+.TP
+\fBstrategy\fR=\fIstrat\fR, \fBstrat\fR=\fIstrat\fR
+Specify a strategy used by a match finder\.
+.IP
+There are 9 strategies numbered from 1 to 9, from fastest to strongest: 1=\fBZSTD_fast\fR, 2=\fBZSTD_dfast\fR, 3=\fBZSTD_greedy\fR, 4=\fBZSTD_lazy\fR, 5=\fBZSTD_lazy2\fR, 6=\fBZSTD_btlazy2\fR, 7=\fBZSTD_btopt\fR, 8=\fBZSTD_btultra\fR, 9=\fBZSTD_btultra2\fR\.
+.TP
+\fBwindowLog\fR=\fIwlog\fR, \fBwlog\fR=\fIwlog\fR
+Specify the maximum number of bits for a match distance\.
+.IP
+The higher number of increases the chance to find a match which usually improves compression ratio\. It also increases memory requirements for the compressor and decompressor\. The minimum \fIwlog\fR is 10 (1 KiB) and the maximum is 30 (1 GiB) on 32\-bit platforms and 31 (2 GiB) on 64\-bit platforms\.
+.IP
+Note: If \fBwindowLog\fR is set to larger than 27, \fB\-\-long=windowLog\fR or \fB\-\-memory=windowSize\fR needs to be passed to the decompressor\.
+.TP
+\fBhashLog\fR=\fIhlog\fR, \fBhlog\fR=\fIhlog\fR
+Specify the maximum number of bits for a hash table\.
+.IP
+Bigger hash tables cause fewer collisions which usually makes compression faster, but requires more memory during compression\.
+.IP
+The minimum \fIhlog\fR is 6 (64 entries / 256 B) and the maximum is 30 (1B entries / 4 GiB)\.
+.TP
+\fBchainLog\fR=\fIclog\fR, \fBclog\fR=\fIclog\fR
+Specify the maximum number of bits for the secondary search structure, whose form depends on the selected \fBstrategy\fR\.
+.IP
+Higher numbers of bits increases the chance to find a match which usually improves compression ratio\. It also slows down compression speed and increases memory requirements for compression\. This option is ignored for the \fBZSTD_fast\fR \fBstrategy\fR, which only has the primary hash table\.
+.IP
+The minimum \fIclog\fR is 6 (64 entries / 256 B) and the maximum is 29 (512M entries / 2 GiB) on 32\-bit platforms and 30 (1B entries / 4 GiB) on 64\-bit platforms\.
+.TP
+\fBsearchLog\fR=\fIslog\fR, \fBslog\fR=\fIslog\fR
+Specify the maximum number of searches in a hash chain or a binary tree using logarithmic scale\.
+.IP
+More searches increases the chance to find a match which usually increases compression ratio but decreases compression speed\.
+.IP
+The minimum \fIslog\fR is 1 and the maximum is \'windowLog\' \- 1\.
+.TP
+\fBminMatch\fR=\fImml\fR, \fBmml\fR=\fImml\fR
+Specify the minimum searched length of a match in a hash table\.
+.IP
+Larger search lengths usually decrease compression ratio but improve decompression speed\.
+.IP
+The minimum \fImml\fR is 3 and the maximum is 7\.
+.TP
+\fBtargetLength\fR=\fItlen\fR, \fBtlen\fR=\fItlen\fR
+The impact of this field vary depending on selected strategy\.
+.IP
+For \fBZSTD_btopt\fR, \fBZSTD_btultra\fR and \fBZSTD_btultra2\fR, it specifies the minimum match length that causes match finder to stop searching\. A larger \fBtargetLength\fR usually improves compression ratio but decreases compression speed\.
+.IP
+For \fBZSTD_fast\fR, it triggers ultra\-fast mode when > 0\. The value represents the amount of data skipped between match sampling\. Impact is reversed: a larger \fBtargetLength\fR increases compression speed but decreases compression ratio\.
+.IP
+For all other strategies, this field has no impact\.
+.IP
+The minimum \fItlen\fR is 0 and the maximum is 128 KiB\.
+.TP
+\fBoverlapLog\fR=\fIovlog\fR, \fBovlog\fR=\fIovlog\fR
+Determine \fBoverlapSize\fR, amount of data reloaded from previous job\. This parameter is only available when multithreading is enabled\. Reloading more data improves compression ratio, but decreases speed\.
+.IP
+The minimum \fIovlog\fR is 0, and the maximum is 9\. 1 means "no overlap", hence completely independent jobs\. 9 means "full overlap", meaning up to \fBwindowSize\fR is reloaded from previous job\. Reducing \fIovlog\fR by 1 reduces the reloaded amount by a factor 2\. For example, 8 means "windowSize/2", and 6 means "windowSize/8"\. Value 0 is special and means "default": \fIovlog\fR is automatically determined by \fBzstd\fR\. In which case, \fIovlog\fR will range from 6 to 9, depending on selected \fIstrat\fR\.
+.TP
+\fBldmHashLog\fR=\fIlhlog\fR, \fBlhlog\fR=\fIlhlog\fR
+Specify the maximum size for a hash table used for long distance matching\.
+.IP
+This option is ignored unless long distance matching is enabled\.
+.IP
+Bigger hash tables usually improve compression ratio at the expense of more memory during compression and a decrease in compression speed\.
+.IP
+The minimum \fIlhlog\fR is 6 and the maximum is 30 (default: 20)\.
+.TP
+\fBldmMinMatch\fR=\fIlmml\fR, \fBlmml\fR=\fIlmml\fR
+Specify the minimum searched length of a match for long distance matching\.
+.IP
+This option is ignored unless long distance matching is enabled\.
+.IP
+Larger/very small values usually decrease compression ratio\.
+.IP
+The minimum \fIlmml\fR is 4 and the maximum is 4096 (default: 64)\.
+.TP
+\fBldmBucketSizeLog\fR=\fIlblog\fR, \fBlblog\fR=\fIlblog\fR
+Specify the size of each bucket for the hash table used for long distance matching\.
+.IP
+This option is ignored unless long distance matching is enabled\.
+.IP
+Larger bucket sizes improve collision resolution but decrease compression speed\.
+.IP
+The minimum \fIlblog\fR is 1 and the maximum is 8 (default: 3)\.
+.TP
+\fBldmHashRateLog\fR=\fIlhrlog\fR, \fBlhrlog\fR=\fIlhrlog\fR
+Specify the frequency of inserting entries into the long distance matching hash table\.
+.IP
+This option is ignored unless long distance matching is enabled\.
+.IP
+Larger values will improve compression speed\. Deviating far from the default value will likely result in a decrease in compression ratio\.
+.IP
+The default value is \fBwlog \- lhlog\fR\.
+.SS "Example"
+The following parameters sets advanced compression options to something similar to predefined level 19 for files bigger than 256 KB:
+.P
+\fB\-\-zstd\fR=wlog=23,clog=23,hlog=22,slog=6,mml=3,tlen=48,strat=6
+.SH "SEE ALSO"
+\fBzstdgrep\fR(1), \fBzstdless\fR(1), \fBgzip\fR(1), \fBxz\fR(1)
+.P
+The \fIzstandard\fR format is specified in Y\. Collet, "Zstandard Compression and the \'application/zstd\' Media Type", https://www\.ietf\.org/rfc/rfc8878\.txt, Internet RFC 8878 (February 2021)\.
+.SH "BUGS"
+Report bugs at: https://github\.com/facebook/zstd/issues
+.SH "AUTHOR"
+Yann Collet
diff --git a/upstream/mageia-cauldron/man1/zstdgrep.1 b/upstream/mageia-cauldron/man1/zstdgrep.1
new file mode 100644
index 00000000..1204e5bb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zstdgrep.1
@@ -0,0 +1,17 @@
+.TH "ZSTDGREP" "1" "March 2023" "zstd 1.5.5" "User Commands"
+.SH "NAME"
+\fBzstdgrep\fR \- print lines matching a pattern in zstandard\-compressed files
+.SH "SYNOPSIS"
+\fBzstdgrep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \|\.\|\.\|\.]
+.SH "DESCRIPTION"
+\fBzstdgrep\fR runs \fBgrep\fR(1) on files, or \fBstdin\fR if no files argument is given, after decompressing them with \fBzstdcat\fR(1)\.
+.P
+The \fIgrep\-flags\fR and \fIpattern\fR arguments are passed on to \fBgrep\fR(1)\. If an \fB\-e\fR flag is found in the \fIgrep\-flags\fR, \fBzstdgrep\fR will not look for a \fIpattern\fR argument\.
+.P
+Note that modern \fBgrep\fR alternatives such as \fBripgrep\fR (\fBrg\fR(1)) support \fBzstd\fR\-compressed files out of the box, and can prove better alternatives than \fBzstdgrep\fR notably for unsupported complex pattern searches\. Note though that such alternatives may also feature some minor command line differences\.
+.SH "EXIT STATUS"
+In case of missing arguments or missing pattern, 1 will be returned, otherwise 0\.
+.SH "SEE ALSO"
+\fBzstd\fR(1)
+.SH "AUTHORS"
+Thomas Klausner \fIwiz@NetBSD\.org\fR
diff --git a/upstream/mageia-cauldron/man1/zstdless.1 b/upstream/mageia-cauldron/man1/zstdless.1
new file mode 100644
index 00000000..bc019b26
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/zstdless.1
@@ -0,0 +1,9 @@
+.TH "ZSTDLESS" "1" "March 2023" "zstd 1.5.5" "User Commands"
+.SH "NAME"
+\fBzstdless\fR \- view zstandard\-compressed files
+.SH "SYNOPSIS"
+\fBzstdless\fR [\fIflags\fR] [\fIfile\fR \|\.\|\.\|\.]
+.SH "DESCRIPTION"
+\fBzstdless\fR runs \fBless\fR(1) on files or stdin, if no \fIfile\fR argument is given, after decompressing them with \fBzstdcat\fR(1)\.
+.SH "SEE ALSO"
+\fBzstd\fR(1)